@xingular/harness 2.1.0 → 2.1.2

package/src/terminal/logs.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { LOG_READ_CHUNK_BYTES, readHarnessLogSnapshot } from './logs'
+
+describe('terminal diagnostic log snapshots', () => {
+  it('reads the complete fixed-size snapshot in bounded byte chunks', async () => {
+    const original = `${'x'.repeat(LOG_READ_CHUNK_BYTES - 1)}🧠and the rest`
+    const bytes = Buffer.from(original)
+    const info = vi.fn(async () => ({ size: bytes.length }))
+    const chunk = vi.fn(async (snapshotSize: number, offset: number) => {
+      expect(snapshotSize).toBe(bytes.length)
+      const nextOffset = Math.min(bytes.length, offset + LOG_READ_CHUNK_BYTES)
+      return { data: bytes.subarray(offset, nextOffset).toString('base64'), nextOffset }
+    })
+
+    await expect(readHarnessLogSnapshot(info, chunk)).resolves.toBe(original)
+    expect(chunk).toHaveBeenCalledTimes(2)
+    expect(chunk.mock.calls.map(([, offset]) => offset)).toEqual([0, LOG_READ_CHUNK_BYTES])
+  })
+
+  it('returns an empty snapshot when this host has not captured process diagnostics', async () => {
+    const chunk = vi.fn()
+    await expect(readHarnessLogSnapshot(async () => ({ size: null }), chunk)).resolves.toBe('')
+    expect(chunk).not.toHaveBeenCalled()
+  })
+})

package/src/terminal/logs.ts

@@ -0,0 +1,67 @@
+import { closeSync, openSync, readSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const LOG_READ_CHUNK_BYTES = 32 * 1024
+
+export interface HarnessLogInfo {
+  size: number | null
+}
+
+export interface HarnessLogChunk {
+  data: string
+  nextOffset: number
+}
+
+/** Captures the byte length of the host-owned diagnostics file; callers never supply a path. */
+export function harnessLogInfo(stateDir: string): HarnessLogInfo {
+  try {
+    const stat = statSync(join(stateDir, 'harness.log'))
+    if (!stat.isFile()) throw new Error('The Harness diagnostics path is not a regular file.')
+    return { size: stat.size }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { size: null }
+    throw error
+  }
+}
+
+/** Reads one bounded range from the file size captured by `harnessLogInfo`. */
+export function readHarnessLogChunk(stateDir: string, snapshotSize: number, offset: number): HarnessLogChunk {
+  if (!Number.isSafeInteger(snapshotSize) || snapshotSize < 0 || !Number.isSafeInteger(offset) || offset < 0 || offset >= snapshotSize) {
+    throw new Error('The Harness diagnostics snapshot range is invalid.')
+  }
+  const path = join(stateDir, 'harness.log')
+  const current = statSync(path)
+  if (!current.isFile() || current.size < snapshotSize) throw new Error('The Harness diagnostics file changed while it was being read.')
+  const length = Math.min(LOG_READ_CHUNK_BYTES, snapshotSize - offset)
+  const buffer = Buffer.allocUnsafe(length)
+  const descriptor = openSync(path, 'r')
+  try {
+    const bytesRead = readSync(descriptor, buffer, 0, length, offset)
+    if (bytesRead !== length) throw new Error('The Harness diagnostics file changed while it was being read.')
+    return { data: buffer.toString('base64'), nextOffset: offset + bytesRead }
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
+/** Collects a fixed-size snapshot while keeping each socket reply bounded. */
+export async function readHarnessLogSnapshot(
+  info: () => Promise<HarnessLogInfo>,
+  chunk: (snapshotSize: number, offset: number) => Promise<HarnessLogChunk>
+): Promise<string> {
+  const { size } = await info()
+  if (size === null || size === 0) return ''
+  if (!Number.isSafeInteger(size) || size < 0) throw new Error('The Harness returned an invalid diagnostics file size.')
+  const buffers: Buffer[] = []
+  let offset = 0
+  while (offset < size) {
+    const page = await chunk(size, offset)
+    const buffer = Buffer.from(page.data, 'base64')
+    if (!buffer.length || page.nextOffset !== offset + buffer.length || page.nextOffset > size) {
+      throw new Error('The Harness returned an invalid diagnostics file page.')
+    }
+    buffers.push(buffer)
+    offset = page.nextOffset
+  }
+  return Buffer.concat(buffers).toString('utf8')
+}

package/src/terminal/piExtension.lifecycle.test.ts

@@ -11,7 +11,8 @@ vi.mock('./client', () => ({
   terminalCall: transport.telemetry
 }))
 
-import terminalExtension from './piExtension'
+import terminalExtension, { type TerminalPlanRunState } from './piExtension'
+import { PLAN_INSTRUCTIONS } from '../sessions/planMode'
 
 function extension() {
   const handlers = new Map<string, (...args: unknown[]) => unknown>()
@@ -28,6 +29,32 @@ function extension() {
 afterEach(() => vi.useRealTimers())
 
 describe('terminal bridge lifecycle', () => {
+  it('adds plan instructions as a one-run context section and withdraws them on the next user request', async () => {
+    const state: TerminalPlanRunState = { active: true, allowedTools: new Set(['read']) }
+    const { api, ctx, handlers } = extension()
+    await terminalExtension(api, state)
+    const planned = { messageType: 'user', prompt: 'inspect this', systemPrompt: 'stable prefix', systemPromptOptions: { sections: { identity: 'identity' } } }
+    await handlers.get('before_agent_start')!(planned, ctx)
+    expect(planned.systemPromptOptions.sections).toEqual({ identity: 'identity', plan: PLAN_INSTRUCTIONS })
+    expect(planned.systemPrompt).toBe('stable prefix')
+
+    state.active = false
+    const ordinary = { messageType: 'user', prompt: 'now implement', systemPrompt: 'stable prefix', systemPromptOptions: { sections: { identity: 'identity', plan: PLAN_INSTRUCTIONS } } }
+    await handlers.get('before_agent_start')!(ordinary, ctx)
+    expect(ordinary.systemPromptOptions.sections).toEqual({ identity: 'identity' })
+    expect(ordinary.systemPrompt).toBe('stable prefix')
+  })
+
+  it('blocks tools outside the active plan allowlist before consulting terminal policy', async () => {
+    const state: TerminalPlanRunState = { active: true, allowedTools: new Set(['read']) }
+    const { api, ctx, handlers } = extension()
+    await terminalExtension(api, state)
+    const policyCalls = transport.socket.mock.calls.filter(([, call]) => call === 'terminal.policy').length
+    const result = await handlers.get('tool_call')!({ toolName: 'bash', toolCallId: 'call-1', input: { command: 'touch unsafe' } }, ctx)
+    expect(result).toMatchObject({ block: true, reason: expect.stringContaining('Plan mode is research-only') })
+    expect(transport.socket.mock.calls.filter(([, call]) => call === 'terminal.policy')).toHaveLength(policyCalls)
+  })
+
   it('keeps one private control claim while replacing native session pollers and restoring readiness', async () => {
     vi.useFakeTimers()
     const first = extension()

package/src/terminal/piExtension.ts

@@ -13,6 +13,7 @@ import { claimTerminalControl, controlCall } from './control'
 import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory, type SubagentReceipt } from '../sessions/subagents'
 import { askUserTool } from '../tools/askUser'
 import type { QuestionAnswer } from '../sessions/registry'
+import { PLAN_INSTRUCTIONS, planRefusal } from '../sessions/planMode'
 
 interface SocketTool {
   name: string
@@ -21,6 +22,11 @@ interface SocketTool {
   parameters: Record<string, unknown>
 }
 
+export interface TerminalPlanRunState {
+  active: boolean
+  allowedTools: ReadonlySet<string>
+}
+
 /** 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
@@ -35,7 +41,7 @@ async function withParentCancellation<T>(signal: AbortSignal | undefined, work:
   try { return await work() } finally { signal?.removeEventListener('abort', stop) }
 }
 
-export default async function (pi: ExtensionAPI) {
+export default async function (pi: ExtensionAPI, planRun?: TerminalPlanRunState) {
   await terminalCall('startup', { phase: 'Pi extension loaded' })
   let context: ExtensionContext | null = null
   let nativeSubagents = false
@@ -167,6 +173,10 @@ export default async function (pi: ExtensionAPI) {
       await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) })
       subagentParent = true
     }
+    if (planRun && event.messageType === 'user') {
+      if (planRun.active) event.systemPromptOptions.sections.plan = PLAN_INSTRUCTIONS
+      else delete event.systemPromptOptions.sections.plan
+    }
   })
   const deliverChildren = async (event: any, ctx: ExtensionContext, settle: boolean) => {
     if (!nativeSubagents || (settle && event.outcome !== 'completed') || ctx.signal?.aborted) return
@@ -224,6 +234,10 @@ export default async function (pi: ExtensionAPI) {
     requestStartedAt = Date.now()
   })
   pi.on('tool_call', async (event) => {
+    if (planRun?.active && !planRun.allowedTools.has(event.toolName)) {
+      const reason = planRefusal(event.toolName, new Set()) ?? `Plan mode is research-only: ${event.toolName} is not available in this session.`
+      return { block: true, reason }
+    }
     try {
       const policy = await controlCall<{ allowed: boolean; reason?: string; requiresApproval?: boolean }>('terminal.policy', { tool: event.toolName, args: event.input })
       if (policy.requiresApproval) {
@@ -280,10 +294,10 @@ export default async function (pi: ExtensionAPI) {
   pi.registerTool({
     name: 'ask_user_question',
     label: 'Ask a question',
-    description: 'Ask the user a question and wait for their answer.',
+    description: 'Ask the user a question and wait for their answer. Recommendations are visual only and never preselect answers; submitted choices keep their labels. Mark options with recommended: true, at most one for single-choice questions or several when multiSelect is true.',
     parameters: Type.Object({
       question: Type.String(),
-      options: Type.Optional(Type.Array(Type.Object({ label: Type.String(), description: Type.Optional(Type.String()) }))),
+      options: Type.Optional(Type.Array(Type.Object({ label: Type.String(), description: Type.Optional(Type.String()), recommended: Type.Optional(Type.Boolean()) }))),
       multiSelect: Type.Optional(Type.Boolean())
     }),
     async execute(id, input) {

package/src/terminal/terminal.test.ts

@@ -15,6 +15,7 @@ import { rootWithProject, writeFile } from '../../tests/helpers'
 import { parseCli } from './cli'
 import { SOCKET_ENV, TOKEN_ENV, socketCall, type SocketConnection } from './client'
 import { SessionSocket } from './socket'
+import { LOG_READ_CHUNK_BYTES } from './logs'
 
 const open: Harness[] = []
 afterEach(async () => {
@@ -467,6 +468,25 @@ describe('decisions in the Harness-owned frontend', () => {
     await expect(socketCall(connection, 'terminal.trajectory.list', {}, 1000, key)).resolves.toEqual({ runs: [] })
   })
 
+  it('serves a bounded diagnostic snapshot only through the private terminal control channel', async () => {
+    const { connection, harness } = await setup()
+    await expect(socketCall(connection, 'terminal.logs.info')).rejects.toMatchObject({ code: 'unauthorized' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    await expect(socketCall(connection, 'terminal.logs.info', {}, 1000, key)).resolves.toEqual({ size: null })
+    await expect(socketCall(connection, 'terminal.logs.read', { snapshotSize: 1, offset: 0 }, 1000, key)).rejects.toMatchObject({ code: 'invalid_request' })
+
+    const text = `${'a'.repeat(LOG_READ_CHUNK_BYTES - 1)}🧠tail`
+    writeFileSync(join(harness.stateDir, 'harness.log'), text)
+    const { size } = await socketCall<{ size: number }>(connection, 'terminal.logs.info', {}, 1000, key)
+    expect(size).toBe(Buffer.byteLength(text))
+    await expect(socketCall(connection, 'terminal.logs.read', { snapshotSize: size, offset: size }, 1000, key)).rejects.toMatchObject({ code: 'invalid_request' })
+    const first = await socketCall<{ data: string; nextOffset: number }>(connection, 'terminal.logs.read', { snapshotSize: size, offset: 0 }, 1000, key)
+    const second = await socketCall<{ data: string; nextOffset: number }>(connection, 'terminal.logs.read', { snapshotSize: size, offset: first.nextOffset }, 1000, key)
+    expect(first.nextOffset).toBe(LOG_READ_CHUNK_BYTES)
+    expect(second.nextOffset).toBe(size)
+    expect(Buffer.concat([Buffer.from(first.data, 'base64'), Buffer.from(second.data, 'base64')]).toString('utf8')).toBe(text)
+  })
+
   it('requires the private input-owner key for pending decisions and exact draft state', async () => {
     const { connection, harness, tell } = await setup()
     await tell('ready', { nativeSessionId: '/native.jsonl' })

package/src/terminal/terminals.ts

@@ -43,6 +43,7 @@ import { SOCKET_ENV, TOKEN_ENV } from './client'
 import { TerminalController, type PolicyReply } from './controller'
 import { resolvePiCommand, terminalCommandFiles } from './launch'
 import { SessionSocket, socketPath } from './socket'
+import { harnessLogInfo, readHarnessLogChunk } from './logs'
 import { listTerminalTrajectoryRuns, readTerminalTrajectory } from './trajectory'
 
 /** Identity of the exact resource decision that this terminal was prepared with. */
@@ -543,6 +544,16 @@ export class Terminals {
         broker,
         terminal: { accept: (event, data) => live.controller.accept(event, data), disconnected: () => live.controller.disconnected(), control: async (call, params) => {
           if (call.startsWith('terminal.subagents.')) return this.subagentsCall(live, call, params)
+          if (call === 'terminal.logs.info') return harnessLogInfo(this.options.stateDir)
+          if (call === 'terminal.logs.read') {
+            const { snapshotSize, offset } = params
+            if (typeof snapshotSize !== 'number' || !Number.isSafeInteger(snapshotSize) || snapshotSize < 0 || typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0 || offset >= snapshotSize) {
+              throw invalid('A valid diagnostics snapshot size and byte offset are required.')
+            }
+            const current = harnessLogInfo(this.options.stateDir).size
+            if (current === null || snapshotSize > current) throw invalid('The diagnostics snapshot is no longer available.')
+            return readHarnessLogChunk(this.options.stateDir, snapshotSize, offset)
+          }
           if (call.startsWith('terminal.trajectory.')) return this.trajectoryCall(live, call, params)
           if (call === 'terminal.permissions.get') {
             const policy = this.options.approvals.read()

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

@@ -5,7 +5,7 @@ import { describe, expect, it, vi } from 'vitest'
 vi.mock('../control', () => ({ controlCall: vi.fn(async () => ({})) }))
 import { controlCall } from '../control'
 import { TerminalApplication } from './application'
-import { createTerminalCommands, type TerminalCommandHost } from './commands'
+import { createTerminalCommands } from './commands'
 import type { TerminalDecision } from './runtime'
 import { terminalKeybindings } from './keybindings'
 import { autocompleteRuleColor, createHarnessTheme } from './theme'
@@ -22,10 +22,8 @@ function setup() {
     }
     keybindings: ReturnType<typeof terminalKeybindings>
     editor: CustomEditor
-    runtime: { interrupt: ReturnType<typeof vi.fn>; dispose: ReturnType<typeof vi.fn>; session: object; snapshot(): { hasUserMessages: boolean; cwd?: string; model?: { name: string; reasoning: boolean; contextWindow: number }; thinkingLevel?: string; account?: { label: string } | null; context?: { percent: number | null; window: number }; costUsd?: number; subscription?: boolean } }
-    commands: ReturnType<typeof createTerminalCommands> | { execute: ReturnType<typeof vi.fn> }
-    planMode: boolean
-    setPlanMode(enabled: boolean): void
+    runtime: { interrupt: ReturnType<typeof vi.fn>; dispose: ReturnType<typeof vi.fn>; submit: ReturnType<typeof vi.fn>; submitPlan: ReturnType<typeof vi.fn>; session: object; snapshot(): { hasUserMessages: boolean; cwd?: string; model?: { name: string; reasoning: boolean; contextWindow: number }; thinkingLevel?: string; account?: { label: string } | null; context?: { percent: number | null; window: number }; costUsd?: number; subscription?: boolean } }
+    commands: ReturnType<typeof createTerminalCommands> | { execute: ReturnType<typeof vi.fn>; expandSkill(text: string): string }
     masthead: { render(width: number): string[] }
     header?: { render(width: number): string[]; invalidate(): void }
     branch: string | null
@@ -52,7 +50,7 @@ function setup() {
   app.keybindings = terminalKeybindings('/unused/isolated-account')
   app.initialized = true
   const context = {}
-  app.runtime = { interrupt: vi.fn(async () => {}), dispose: vi.fn(async () => {}), snapshot: () => ({
+  app.runtime = { interrupt: vi.fn(async () => {}), dispose: vi.fn(async () => {}), submit: vi.fn(async () => {}), submitPlan: vi.fn(async () => {}), snapshot: () => ({
     hasUserMessages: false, cwd: '/work/project', model: { name: 'Claude Sonnet 4.6', reasoning: true, contextWindow: 200_000 },
     thinkingLevel: 'high', account: { label: 'Tanny' }, context: { percent: null, window: 0 }, costUsd: 0, subscription: false
   }), session: {
@@ -226,7 +224,7 @@ describe('the owned terminal application', () => {
     const { application, app } = setup()
     app.mountEditor()
     let resolve!: (value: boolean) => void
-    app.commands = { execute: vi.fn(() => new Promise<boolean>(done => { resolve = done })) }
+    app.commands = { execute: vi.fn(() => new Promise<boolean>(done => { resolve = done })), expandSkill: text => text }
     app.submit('   /settings')
     await vi.waitFor(() => expect(app.commands.execute).toHaveBeenCalledWith('   /settings'))
     app.submit('/model')
@@ -237,35 +235,33 @@ describe('the owned terminal application', () => {
     await application.shutdown()
   })
 
-  it('toggles plan mode with /plan, narrowing to read-only tools', async () => {
+  it('keeps a queued plan isolated and sends later messages after it settles', async () => {
     const { application, app } = setup()
-    const session = app.runtime.session as { getActiveToolNames(): string[]; setActiveToolsByName(names: string[]): void; cycleThinkingLevel(): void }
-    const setActiveToolsByName = vi.fn()
-    const cycleThinkingLevel = vi.fn()
-    Object.assign(session, { getActiveToolNames: () => ['read', 'bash', 'edit', 'write', 'grep', 'spawn_subagent'], setActiveToolsByName, cycleThinkingLevel })
-    app.commands = createTerminalCommands({
-      session: () => session as never,
-      runtime: () => ({} as never),
-      ui: app.ui,
-      cwd: () => '/work/project',
-      sessionDirectory: () => '/isolated/account/history',
-      refresh: () => {},
-      changed: () => {},
-      planMode: () => app.planMode,
-      setPlanMode: enabled => app.setPlanMode(enabled),
-      shutdown: () => {},
-      setEditorText: () => {},
-      copyText: async () => {},
-      trajectory: {} as TerminalCommandHost['trajectory']
-    })
+    const session = app.runtime.session as { isIdle: boolean }
+    Object.assign(session, { isIdle: false })
+    const sent: string[] = []
+    app.runtime.submitPlan = vi.fn(async brief => { sent.push(`plan:${brief}`) })
+    app.runtime.submit = vi.fn(async text => { sent.push(`prompt:${text}`) })
+    const enqueuePlan = (application as unknown as { enqueuePlan(brief: string): void }).enqueuePlan.bind(application)
     app.mountEditor()
-    app.submit('/plan')
-    await vi.waitFor(() => expect(setActiveToolsByName).toHaveBeenCalledWith(['read', 'grep']))
-    expect(setActiveToolsByName).toHaveBeenLastCalledWith(['read', 'grep'])
-    app.submit('/plan off')
-    await vi.waitFor(() => expect(setActiveToolsByName).toHaveBeenLastCalledWith(['read', 'bash', 'edit', 'write', 'grep', 'spawn_subagent']))
-    expect(setActiveToolsByName).toHaveBeenLastCalledWith(['read', 'bash', 'edit', 'write', 'grep', 'spawn_subagent'])
-    expect(cycleThinkingLevel).not.toHaveBeenCalled()
+    app.commands = {
+      execute: vi.fn(async text => {
+        if (text.trimStart().startsWith('/plan ')) { enqueuePlan(text.trimStart().slice('/plan '.length)); return true }
+        return false
+      }),
+      expandSkill: text => text
+    }
+
+    app.submit('/plan inspect the source')
+    await vi.waitFor(() => expect(app.commandBusy).toBe(false))
+    app.submit('then implement it')
+    await vi.waitFor(() => expect((application as unknown as { deferredInputs: unknown[] }).deferredInputs).toHaveLength(2))
+    expect(sent).toEqual([])
+
+    session.isIdle = true
+    app.accept({ type: 'agent_settled' } as AgentSessionEvent)
+    await vi.waitFor(() => expect(sent).toEqual(['plan:inspect the source', 'prompt:then implement it']))
+    expect(app.runtime.submitPlan).toHaveBeenCalledOnce()
     await application.shutdown()
   })
 

package/src/terminal/tui/application.ts

@@ -16,7 +16,6 @@ import { HARNESS_KEYBINDINGS, terminalKeybindings } from './keybindings'
 import { loadPiAdapter, setPiTheme } from './piAdapter'
 import { createTerminalRuntime, type TerminalDecision, type TerminalRuntime } from './runtime'
 import { createDock, createTerminalScreen, mountTerminalLayout, readScreenPreferences, scrollbackLines, writeScrollback, type ScreenHooks, type ScreenPreferences, type TerminalScreen } from './screen'
-import { planModeTools } from './planMode'
 import { renderStatusBand, singleLine } from './status'
 import { skillCompletions } from './skillInvocation'
 import { createHarnessLightTheme, createHarnessTheme } from './theme'
@@ -26,10 +25,12 @@ import { chooseWorkingVerb, createCompletionStatus, getWorkingSpinnerFrames, SPI
 import { HarnessWelcome } from './welcome'
 import { answerTerminalQuestion } from './questions'
 import type { QuestionAnswer } from '../../sessions/registry'
+import { readHarnessLogSnapshot, type HarnessLogChunk, type HarnessLogInfo } from '../logs'
 import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../trajectory'
 
 const exec = promisify(execFile)
 type Mounted = Component & { dispose?(): void }
+type DeferredTerminalInput = { kind: 'plan'; text: string } | { kind: 'prompt'; text: string; followUp: boolean }
 type EditorFactory = Parameters<ExtensionUIContext['setEditorComponent']>[0]
 type HeaderFactory = Parameters<ExtensionUIContext['setHeader']>[0]
 type FooterFactory = Parameters<ExtensionUIContext['setFooter']>[0]
@@ -102,8 +103,11 @@ export class TerminalApplication {
   private phase?: string
   private viewport?: ScrollView
   private toolsExpanded = false
-  private planMode = false
-  private normalTools?: string[]
+  private deferredInputs: DeferredTerminalInput[] = []
+  private planBarrierOpen = false
+  private planActive = false
+  private drainingDeferred = false
+  private activeDeferredKind?: DeferredTerminalInput['kind']
   private stopped = false
   private initialized = false
   private closing?: Promise<void>
@@ -184,9 +188,13 @@ export class TerminalApplication {
         session: () => this.session, runtime: () => this.runtime!, ui: this.ui,
         cwd: () => this.runtime!.cwd, sessionDirectory: () => this.runtime!.sessionDirectory,
         refresh: () => this.refresh(), shutdown: () => { void this.shutdown() }, setEditorText: text => { this.editor.setText(text); this.syncDraft(text) },
-        planMode: () => this.planMode, setPlanMode: enabled => this.setPlanMode(enabled),
+        plan: brief => this.enqueuePlan(brief),
         copyText: copyToClipboard, openExternal,
         changed: this.change,
+        logs: { read: () => readHarnessLogSnapshot(
+          () => controlCall<HarnessLogInfo>('terminal.logs.info'),
+          (snapshotSize, offset) => controlCall<HarnessLogChunk>('terminal.logs.read', { snapshotSize, offset })
+        ) },
         trajectory: {
           list: async () => (await controlCall<{ runs: TerminalTrajectoryRun[] }>('terminal.trajectory.list')).runs,
           read: (runId, afterSequence) => controlCall<TerminalTrajectorySnapshot>('terminal.trajectory.events', { runId, ...(afterSequence === undefined ? {} : { afterSequence }) })
@@ -202,7 +210,7 @@ export class TerminalApplication {
       })
       this.cleanup.push(this.runtime.subscribe(event => this.accept(event)))
       this.cleanup.push(this.runtime.onBeforeSessionChange(() => this.resetPresentation()))
-      this.cleanup.push(this.runtime.onSessionChange(() => { this.keybindings.reload(); this.resetWorkingStatus(); this.scrollToLatest(); this.planMode = false; this.normalTools = undefined; this.refresh(true) }))
+      this.cleanup.push(this.runtime.onSessionChange(() => { this.keybindings.reload(); this.resetWorkingStatus(); this.scrollToLatest(); this.refresh(true) }))
       this.initialized = true
       this.phase = undefined
       this.refresh(true)
@@ -307,20 +315,46 @@ export class TerminalApplication {
     this.completionStatus = undefined
     this.phase = undefined
   }
-  /** Plan mode narrows the session to read-only tools; leaving it restores the set the session had before. */
-  private setPlanMode(enabled: boolean): void {
-    if (!this.runtime) return
-    if (this.planMode === enabled) return
-    if (this.planMode) {
-      this.session.setActiveToolsByName(this.normalTools ?? this.session.getActiveToolNames())
-      this.normalTools = undefined
-    } else {
-      this.normalTools = this.session.getActiveToolNames()
-      this.session.setActiveToolsByName(planModeTools(this.normalTools))
-    }
-    this.planMode = enabled
-    this.notify(this.planMode ? 'Plan mode: only read-only tools are available. Use /plan off to return to normal.' : 'Normal mode: all tools are available.')
+  private enqueuePlan(brief: string): void {
+    const text = brief.trim()
+    if (!text) { this.notify('Use /plan <plan brief>.', 'error'); return }
+    const waiting = !this.session.isIdle
+    this.planBarrierOpen = true
+    this.deferredInputs.push({ kind: 'plan', text })
+    this.notify(waiting ? 'Plan request queued to run by itself after the current response.' : 'Plan request queued as an isolated run.')
     this.change()
+    this.drainDeferred()
+  }
+  private drainDeferred(): void {
+    if (this.drainingDeferred || !this.planBarrierOpen || !this.runtime || !this.session.isIdle || !this.deferredInputs.length) return
+    this.drainingDeferred = true
+    void (async () => {
+      try {
+        while (this.deferredInputs.length && !this.stopped && this.runtime && this.session.isIdle) {
+          const next = this.deferredInputs.shift()!
+          this.activeDeferredKind = next.kind
+          this.change()
+          try {
+            if (next.kind === 'plan') {
+              this.planActive = true
+              await this.runtime.submitPlan(next.text)
+            } else {
+              await this.runtime.submit(next.text, next.followUp)
+            }
+          } catch (error) {
+            this.notify(error instanceof Error ? error.message : String(error), 'error')
+          } finally {
+            if (next.kind === 'plan') this.planActive = false
+            this.activeDeferredKind = undefined
+          }
+        }
+      } finally {
+        this.drainingDeferred = false
+        if (!this.deferredInputs.length && !this.planActive) this.planBarrierOpen = false
+        this.change()
+        if (this.deferredInputs.length && this.runtime?.session.isIdle) this.drainDeferred()
+      }
+    })()
   }
   private scrollToLatest(): void { this.viewport?.scrollToEnd() }
   private async chooseApproval(request: TerminalDecision, signal: AbortSignal): Promise<{ decision: 'approved' | 'denied'; alwaysAllow: boolean }> {
@@ -397,7 +431,9 @@ export class TerminalApplication {
   private queuedMessages(width: number): string[] {
     if (!this.ui) return []
     const state = this.runtime?.snapshot()
-    return state ? [...state.queue.steering.map(text => `Steering: ${text}`), ...state.queue.followUp.map(text => `Follow-up: ${text}`)].flatMap(text => wrapTextWithAnsi(this.theme.fg('muted', text), width)) : []
+    const native = state ? [...state.queue.steering.map(text => `Steering: ${text}`), ...state.queue.followUp.map(text => `Follow-up: ${text}`)] : []
+    const deferred = this.deferredInputs.map(input => input.kind === 'plan' ? `Plan: /plan ${input.text}` : `Queued: ${input.text}`)
+    return [...native, ...deferred].flatMap(text => wrapTextWithAnsi(this.theme.fg('muted', text), width))
   }
   private statusLines(width: number): string[] {
     return this.statuses.size ? wrapTextWithAnsi([...this.statuses.values()].join('  '), width) : []
@@ -427,7 +463,13 @@ export class TerminalApplication {
         if (this.stopped) return
         if (command && await this.commands.execute(text)) return
         if (text.trimStart().startsWith('!')) throw new Error('Use the bash tool so this action can be checked.')
-        await this.runtime!.submit(this.commands.expandSkill(text), followUp)
+        const expanded = this.commands.expandSkill(text)
+        if (this.planBarrierOpen) {
+          this.deferredInputs.push({ kind: 'prompt', text: expanded, followUp })
+          this.change()
+          return
+        }
+        await this.runtime!.submit(expanded, followUp)
       } finally { if (command) this.commandBusy = false }
     })
   }
@@ -455,7 +497,14 @@ export class TerminalApplication {
     else if (is('app.tools.expand')) this.ui.setToolsExpanded(!this.toolsExpanded)
     else if (is('app.thinking.toggle')) { const hidden = !this.session.settingsManager.getHideThinkingBlock(); this.session.settingsManager.setHideThinkingBlock(hidden); this.transcript.setThinking(hidden) }
     else if (is('app.message.followUp')) this.submit(this.editor.getExpandedText?.() ?? this.editor.getText(), true)
-    else if (is('app.message.dequeue')) { const pending = this.session.clearQueue(); this.editor.setText([...pending.steering, ...pending.followUp, this.editor.getText()].filter(Boolean).join('\n')); this.syncDraft(this.editor.getText()) }
+    else if (is('app.message.dequeue')) {
+      const pending = this.session.clearQueue()
+      const deferred = this.deferredInputs.map(input => input.kind === 'plan' ? `/plan ${input.text}` : input.text)
+      this.deferredInputs = []
+      this.planBarrierOpen = this.planActive || this.activeDeferredKind === 'plan'
+      this.editor.setText([...pending.steering, ...pending.followUp, ...deferred, this.editor.getText()].filter(Boolean).join('\n'))
+      this.syncDraft(this.editor.getText())
+    }
     else if (is('app.editor.external')) this.attempt(() => this.externalEditor())
     else if (is('app.message.copy')) this.attempt(() => this.commands.execute('/copy'))
     else if (is('app.clipboard.pasteImage')) this.attempt(() => this.pasteClipboard())
@@ -498,6 +547,7 @@ export class TerminalApplication {
       this.requestStartedAt = null
       this.phase = undefined
       this.terminal.setProgress(false)
+      queueMicrotask(() => this.drainDeferred())
     }
     if (event.type === 'compaction_start') this.phase = 'Compacting context…'
     if (event.type === 'compaction_end') { this.phase = undefined; this.transcript.bind(this.session); if (event.errorMessage) this.notify(event.errorMessage, 'error') }
@@ -527,6 +577,7 @@ export class TerminalApplication {
   }
   private resetPresentation(): void {
     this.pendingAbort?.abort(); this.dismissedDecisions.clear()
+    this.deferredInputs = []; this.planBarrierOpen = false; this.planActive = false; this.activeDeferredKind = undefined
     this.resetWorkingStatus()
     this.requestStartedAt = null; this.lastTokensPerSecond = null
     this.transcript.clearSession()

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

@@ -31,8 +31,9 @@ function setup() {
     session: () => session, runtime: () => runtime as unknown as ReturnType<TerminalCommandHost['runtime']>, ui,
     cwd: () => '/isolated/project', sessionDirectory: () => '/isolated/account/history',
     refresh: vi.fn(), changed: vi.fn(), shutdown: vi.fn(), setEditorText: vi.fn(), copyText: vi.fn(async () => {}),
-    planMode: () => false, setPlanMode: vi.fn(),
+    plan: vi.fn(),
     hotkeys: () => 'Escape: interrupt', changelog: async () => 'Harness release notes',
+    logs: { read: vi.fn(async () => '[harness] diagnostic') },
     trajectory: {
       list: vi.fn(async () => [trajectoryRun]),
       read: vi.fn(async () => ({ run: trajectoryRun, events: [] }))
@@ -59,12 +60,24 @@ describe('owned terminal commands', () => {
   it('populates completion from builtins and loaded resources', () => {
     const { commands } = setup()
     const names = commands.completions().map(item => item.name)
-    expect(names).toEqual(expect.arrayContaining(['model', 'resume', 'accounts', 'review', 'effort', 'trajectory', 'permissions']))
+    expect(names).toEqual(expect.arrayContaining(['model', 'resume', 'accounts', 'review', 'effort', 'trajectory', 'log', 'permissions']))
     expect(names).not.toContain('thinking')
     expect(names).not.toContain('skill:diagnose')
     expect(new Set(names).size).toBe(names.length)
   })
 
+  it('runs one plan request from /plan <brief> and rejects toggle syntax', async () => {
+    const { commands, host, ui } = setup()
+    expect(await commands.execute('/plan inspect the current implementation')).toBe(true)
+    expect(host.plan).toHaveBeenCalledWith('inspect the current implementation')
+    expect(await commands.execute('/plan')).toBe(true)
+    expect(await commands.execute('/plan on')).toBe(true)
+    expect(await commands.execute('/plan toggle')).toBe(true)
+    expect(host.plan).toHaveBeenCalledOnce()
+    expect(ui.notify).toHaveBeenLastCalledWith('Use /plan <plan brief>.', 'error')
+    expect(commands.completions().find(item => item.name === 'plan')?.description).toContain('/plan <brief>')
+  })
+
   it('invokes a loaded skill as $name, and leaves other text for the SDK', () => {
     const { commands, session } = setup()
     expect(commands.skills()).toEqual([{ name: 'diagnose', description: 'Diagnose a problem' }])
@@ -160,6 +173,17 @@ describe('owned terminal commands', () => {
     expect(host.trajectory.read).toHaveBeenLastCalledWith('run-1')
   })
 
+  it('opens a full-screen snapshot combining diagnostics and current-conversation run events', async () => {
+    const { commands, host, ui } = setup()
+    await commands.execute('/log')
+    expect(host.logs.read).toHaveBeenCalledOnce()
+    expect(host.trajectory.list).toHaveBeenCalledOnce()
+    expect(host.trajectory.read).toHaveBeenCalledWith('run-1')
+    expect(ui.custom).toHaveBeenCalledWith(expect.any(Function), {
+      overlay: true, overlayOptions: { width: '100%', maxHeight: '100%', anchor: 'top-left' }
+    })
+  })
+
   it('shows shared tool grants and confirms Full Permission before enabling it', async () => {
     const { commands, host, runtime, ui } = setup()
     vi.mocked(ui.custom).mockImplementationOnce(async () => 'tool:bash' as never)