@xingular/harness 0.1.7 → 2.0.0

package/src/terminal/terminal.test.ts

@@ -22,6 +22,23 @@ afterEach(async () => {
   for (const harness of open.splice(0)) await harness.close()
 })
 
+function tellOn(connection: SocketConnection, event: string, data: Record<string, unknown> = {}) {
+  return new Promise<any>((resolve, reject) => {
+    const stream = connect(connection.socket)
+    let buffer = ''
+    stream.on('connect', () => stream.write(`${JSON.stringify({ token: connection.token, event, data })}\n`))
+    stream.on('data', (chunk) => {
+      buffer += chunk.toString()
+      if (!buffer.includes('\n')) return
+      const reply = JSON.parse(buffer.slice(0, buffer.indexOf('\n')))
+      stream.end()
+      if (reply.error) reject(new Error(reply.error.message))
+      else resolve(reply.result)
+    })
+    stream.on('error', reject)
+  })
+}
+
 async function setup(policy: ToolPolicy = {}) {
   const root = rootWithProject()
   const harness = createHarness({ dataRoot: root, stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), policy, piProgram: () => '/opt/pi/bin/pi', assets: { node: '/opt/node', cli: '/opt/harness/cli.js', piExtension: '/opt/harness/terminal-pi.js' } })
@@ -39,21 +56,7 @@ async function setup(policy: ToolPolicy = {}) {
   const launch = await harness.terminals.prepare({ sessionId: 'term-1', accountId: account.id, projectId: 'p1', cwd: root, sessionFolder, model: 'chosen-model', launch: { connections: 'Use mcp_list_tools.' } })
   const connection: SocketConnection = { socket: String(launch.env[SOCKET_ENV]), token: String(launch.env[TOKEN_ENV]) }
   /** One telemetry line, as the native extension sends it. */
-  const tell = (event: string, data: Record<string, unknown> = {}) =>
-    new Promise<any>((resolve, reject) => {
-      const stream = connect(connection.socket)
-      let buffer = ''
-      stream.on('connect', () => stream.write(`${JSON.stringify({ token: connection.token, event, data })}\n`))
-      stream.on('data', (chunk) => {
-        buffer += chunk.toString()
-        if (!buffer.includes('\n')) return
-        const reply = JSON.parse(buffer.slice(0, buffer.indexOf('\n')))
-        stream.end()
-        if (reply.error) reject(new Error(reply.error.message))
-        else resolve(reply.result)
-      })
-      stream.on('error', reject)
-    })
+  const tell = (event: string, data: Record<string, unknown> = {}) => tellOn(connection, event, data)
   return { harness, root, account, events, notices, launch, connection, tell, sessionFolder }
 }
 
@@ -237,6 +240,117 @@ describe('a pi terminal session', () => {
     expect(await decision).toEqual({ decision: 'approved' })
   })
 
+  it('protects permission controls and shares saved terminal grants across sessions', async () => {
+    const { connection, harness, account, root } = await setup()
+    await expect(socketCall(connection, 'terminal.permissions.get')).rejects.toMatchObject({ code: 'unauthorized' })
+    await expect(socketCall(connection, 'terminal.policy', { tool: 'bash', args: {} })).rejects.toMatchObject({ code: 'unauthorized' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    expect(await socketCall(connection, 'terminal.permissions.get', {}, 1000, key)).toEqual({ full: false, globalTools: [] })
+    await socketCall(connection, 'terminal.permissions.setTool', { tool: 'bash', allowed: true }, 1000, key)
+    await socketCall(connection, 'terminal.permissions.setFull', { enabled: true }, 1000, key)
+
+    const secondLaunch = await harness.terminals.prepare({ sessionId: 'term-2', accountId: account.id, projectId: 'p1', cwd: root, sessionFolder: join(root, 'sessions', 'p1', 'term-2') })
+    const secondConnection: SocketConnection = { socket: String(secondLaunch.env[SOCKET_ENV]), token: String(secondLaunch.env[TOKEN_ENV]) }
+    const { key: secondKey } = await socketCall<{ key: string }>(secondConnection, 'control.claim')
+    expect(await socketCall(secondConnection, 'terminal.permissions.get', {}, 1000, secondKey)).toEqual({ full: true, globalTools: ['bash'] })
+    await socketCall(secondConnection, 'terminal.permissions.setTool', { tool: 'bash', allowed: false }, 1000, secondKey)
+    expect(await socketCall(connection, 'terminal.permissions.get', {}, 1000, key)).toEqual({ full: true, globalTools: [] })
+    await expect(socketCall(connection, 'terminal.permissions.setFull', { enabled: 'yes' }, 1000, key)).rejects.toMatchObject({ code: 'invalid_request' })
+  })
+
+  it('does not let a permission change retroactively resolve an already pending approval', async () => {
+    const { connection, tell } = await setup()
+    await tell('ready')
+    await tell('begin', { text: 'Wait for a decision' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    const approval = socketCall<{ decision: string }>(connection, 'terminal.approval', { requestId: 'already-pending', tool: 'bash', args: { command: 'pwd' } }, 1000, key)
+    let requestId = ''
+    await vi.waitFor(async () => {
+      const { requests } = await socketCall<{ requests: Array<{ requestId: string }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(requests).toHaveLength(1)
+      requestId = requests[0]!.requestId
+    })
+
+    await socketCall(connection, 'terminal.permissions.setFull', { enabled: true }, 1000, key)
+    expect(await socketCall(connection, 'terminal.pending', {}, 1000, key)).toMatchObject({ requests: [{ requestId }] })
+    await socketCall(connection, 'terminal.approve', { requestId, decision: 'denied' }, 1000, key)
+    expect(await approval).toEqual({ decision: 'denied' })
+  })
+
+  it('rechecks native tool policy when a pending approval is resolved', async () => {
+    let denied = false
+    const { connection, tell } = await setup({
+      scope: async () => denied ? { allowed: false, reason: 'The policy now denies this tool.' } : { allowed: true, requiresApproval: true }
+    })
+    await tell('ready')
+    await tell('begin', { text: 'Run a tool' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    expect(await socketCall(connection, 'terminal.policy', { tool: 'bash', args: { command: 'pwd' } }, 1000, key)).toMatchObject({ requiresApproval: true, rememberable: true })
+    const approval = socketCall<{ decision: string }>(connection, 'terminal.approval', { requestId: 'call-approval', tool: 'bash', args: { command: 'pwd' } }, 1000, key)
+    let requestId = ''
+    await vi.waitFor(async () => {
+      const pending = await socketCall<{ requests: Array<{ requestId: string }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(pending.requests).toHaveLength(1)
+      requestId = pending.requests[0]!.requestId
+    })
+
+    denied = true
+    await socketCall(connection, 'terminal.approve', { requestId, decision: 'approved' }, 1000, key)
+    expect(await approval).toEqual({ decision: 'denied' })
+  })
+
+  it('keeps human-only rules out of tool grants and Full Permission unless the host opts in', async () => {
+    const { connection, tell, events, harness } = await setup({
+      scope: async () => ({ allowed: true, humanOnly: true, allowGlobalApproval: false })
+    })
+    harness.approvals.setAuto('pi', true)
+    await tell('ready')
+    await tell('begin', { text: 'Human decision required' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    expect(await socketCall(connection, 'terminal.policy', { tool: 'bash', args: {} }, 1000, key)).toMatchObject({ requiresApproval: true, rememberable: false, standing: 'none' })
+    const approval = socketCall<{ decision: string }>(connection, 'terminal.approval', { requestId: 'human-only', tool: 'bash', args: {} }, 1000, key)
+    let requestId = ''
+    await vi.waitFor(async () => {
+      expect(events.some(event => event.type === 'approval.requested')).toBe(true)
+      const { requests } = await socketCall<{ requests: Array<{ requestId: string; rememberable?: boolean }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(requests).toHaveLength(1)
+      expect(requests[0]?.rememberable).toBe(false)
+      requestId = requests[0]!.requestId
+    })
+    await socketCall(connection, 'terminal.approve', { requestId, decision: 'denied' }, 1000, key)
+    expect(await approval).toEqual({ decision: 'denied' })
+  })
+
+  it('remembers a tool choice for future Pi terminal sessions sharing the state directory', async () => {
+    const { connection, tell, events, harness, account, root } = await setup()
+    await tell('ready')
+    await tell('begin', { text: 'Allow a tool' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    const first = socketCall<{ decision: string }>(connection, 'terminal.approval', { requestId: 'remember-call', tool: 'bash', args: { command: 'pwd' } }, 1000, key)
+    let requestId = ''
+    await vi.waitFor(async () => {
+      const { requests } = await socketCall<{ requests: Array<{ requestId: string; rememberable?: boolean }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(requests[0]?.rememberable).toBe(true)
+      requestId = requests[0]!.requestId
+    })
+    await socketCall(connection, 'terminal.approve', { requestId, decision: 'approved', alwaysAllow: true }, 1000, key)
+    expect(await first).toEqual({ decision: 'approved' })
+    expect(harness.approvals.read().globalTools.pi).toEqual(['bash'])
+
+    const launch = await harness.terminals.prepare({ sessionId: 'term-2', accountId: account.id, projectId: 'p1', cwd: root, sessionFolder: join(root, 'sessions', 'p1', 'term-2') })
+    const next: SocketConnection = { socket: String(launch.env[SOCKET_ENV]), token: String(launch.env[TOKEN_ENV]) }
+    await tellOn(next, 'startup', { phase: 'ready' })
+    await tellOn(next, 'ready')
+    await tellOn(next, 'begin', { text: 'Reuse the grant' })
+    const { key: nextKey } = await socketCall<{ key: string }>(next, 'control.claim')
+    const before = events.filter(event => event.type === 'approval.requested').length
+    expect(await socketCall(next, 'terminal.approval', { requestId: 'next-call', tool: 'bash', args: { command: 'git status' } }, 1000, nextKey)).toEqual({ decision: 'approved' })
+    const automatic = events.filter(event => event.type === 'approval.requested').slice(before)
+    expect(automatic).toHaveLength(1)
+    expect(automatic[0]?.payload).toMatchObject({ automatic: 'remembered', target: 'bash' })
+    expect(await socketCall(next, 'terminal.pending', {}, 1000, nextKey)).toEqual({ requests: [] })
+  })
+
   it('applies the application policy to native tool calls', async () => {
     const seen: string[] = []
     const { tell } = await setup({
@@ -332,6 +446,27 @@ describe('xagent-wiki command', () => {
 
 
 describe('decisions in the Harness-owned frontend', () => {
+  it('exposes trajectory reads only to the input owner and scopes them to the current native conversation', async () => {
+    const { connection, tell, events } = await setup()
+    await tell('ready', { nativeSessionId: '/history/current.jsonl' })
+    await tell('begin', { text: 'Inspect this run' })
+    await tell('message', { text: 'Recorded response' })
+    await tell('settled', {})
+    const runId = events.find(event => event.type === 'started')!.runId
+
+    await expect(socketCall(connection, 'terminal.trajectory.list')).rejects.toMatchObject({ code: 'unauthorized' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    const listed = await socketCall<{ runs: Array<{ id: string }> }>(connection, 'terminal.trajectory.list', {}, 1000, key)
+    expect(listed.runs.map(run => run.id)).toContain(runId)
+    await expect(socketCall(connection, 'terminal.trajectory.events', { runId }, 1000, key)).resolves.toMatchObject({
+      run: { id: runId }, events: expect.arrayContaining([expect.objectContaining({ type: 'message.completed' })])
+    })
+
+    await tell('ready', { nativeSessionId: '/history/another.jsonl' })
+    await expect(socketCall(connection, 'terminal.trajectory.events', { runId }, 1000, key)).rejects.toMatchObject({ code: 'not_found' })
+    await expect(socketCall(connection, 'terminal.trajectory.list', {}, 1000, key)).resolves.toEqual({ runs: [] })
+  })
+
   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

@@ -5,7 +5,16 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, unlinkSync,
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { Type } from 'typebox'
+
+import type { CapabilitySet } from '../capabilities/types'
+import { freezeRun } from '../capabilities/runSnapshot'
+import type { Subagents } from '../sessions/subagentService'
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, type SubagentOptions } from '../sessions/subagents'
+import { subagentTools } from '../tools/spawnSubagent'
+import type { Effort } from '../sessions/runner'
 import type { Accounts } from '../accounts/accounts'
+import type { Approvals } from '../sessions/approvals'
 import { configDir, launchEnv } from '../accounts/env'
 import { readAudit, type Account } from '../accounts/store'
 import type { Bus } from '../core/bus'
@@ -34,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 { listTerminalTrajectoryRuns, readTerminalTrajectory } from './trajectory'
 
 /** Identity of the exact resource decision that this terminal was prepared with. */
 function resourceIdentity(loading: Loading | null): string {
@@ -63,6 +73,7 @@ export function defaultAssets(): TerminalAssets {
 }
 
 export interface TerminalPrepareInput {
+  subagents?: SubagentOptions | null
   sessionId: string
   /** The account the session is pinned to. Omitted only for a session that has none yet; it then takes the default and keeps it. */
   accountId?: string | null
@@ -100,10 +111,13 @@ interface Live {
 }
 
 export interface TerminalsOptions {
+  subagents?: Subagents
+  resolveCapabilities?: (caller: CallerContext, tools: readonly string[], cwd: string) => Promise<CapabilitySet>
   env: HarnessEnv
   stateDir: string
   accounts: Accounts
   runs: RunRegistry
+  approvals: Approvals
   apps: ConnectedApps
   policy: ToolPolicy
   bus: Bus
@@ -136,7 +150,21 @@ export class Terminals {
 
   constructor(private readonly options: TerminalsOptions) {
     this.assets = options.assets ?? defaultAssets()
-    options.runs.listen(event => this.sessions.get(event.sessionId)?.controller.observe(event))
+    options.runs.listen(event => {
+      this.sessions.get(event.sessionId)?.controller.observe(event)
+      const record = findRun(options.env.root, event.runId)
+      if (record?.relation !== 'subagent') return
+      let parentId = record.parentRunId
+      const seen = new Set<string>()
+      while (parentId && !seen.has(parentId)) {
+        seen.add(parentId)
+        const parent = findRun(options.env.root, parentId)
+        if (!parent) break
+        const owner = this.sessions.get(parent.sessionId)
+        if (owner?.controller.activeRun?.runId === parent.id) { owner.controller.observe(event, true); break }
+        parentId = parent.parentRunId
+      }
+    })
     this.socket = new SessionSocket(socketPath(options.stateDir), {
       memory: (caller, call, params) => dispatch(options.env, caller, call, params),
       apps: (session, call, params) => this.appsCall(session, call, params),
@@ -383,19 +411,80 @@ export class Terminals {
     const { policy } = this.options
     if (policy.scope) {
       const scope = await policy.scope(call)
-      if (!scope.allowed && !scope.requiresApproval) return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.' }
+      if (!scope.allowed && (scope.automatic || !scope.requiresApproval)) return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.' }
       try {
         await policy.authorize?.(call)
       } catch (error) {
         return { allowed: false, reason: error instanceof Error ? error.message : 'Tool unavailable in the settings.' }
       }
-      return { allowed: scope.allowed, requiresApproval: !!scope.requiresApproval, reason: scope.reason ?? null }
+      const requiresApproval = !!scope.requiresApproval || (scope.allowed && !!scope.humanOnly)
+      return {
+        allowed: scope.allowed,
+        requiresApproval,
+        reason: scope.reason ?? null,
+        rememberable: scope.allowed && !scope.humanOnly,
+        ...(scope.humanOnly ? { standing: scope.allowGlobalApproval ? 'switch' as const : 'none' as const } : {})
+      }
     }
     // With no application policy: reads run, a read-only session refuses the rest, and anything else asks.
     const name = tool.toLowerCase()
-    if (READ_ONLY_TOOLS.has(name) || this.options.apps.toolNames.includes(name as never)) return { allowed: true }
+    if (name === SPAWN_SUBAGENT || name === WAIT_SUBAGENTS || READ_ONLY_TOOLS.has(name) || this.options.apps.toolNames.includes(name as never)) return { allowed: true }
     if (live.input.readOnly) return { allowed: false, reason: 'This session is read-only.' }
-    return { allowed: false, requiresApproval: true, reason: 'This native action requires approval.' }
+    return { allowed: false, requiresApproval: true, rememberable: true, reason: 'This native action requires approval.' }
+  }
+
+  private async subagentsCall(live: Live, call: string, params: Record<string, any>): Promise<unknown> {
+    const service = this.options.subagents
+    if (!service || live.input.subagents === null) {
+      if (call === 'terminal.subagents.tools') return { tools: [] }
+      throw invalid('Subagents are disabled for this terminal.')
+    }
+    if (call === 'terminal.subagents.tools') return { tools: subagentTools(service, '').map(tool => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })) }
+    const run = live.controller.activeRun
+    if (!run) throw new HarnessError('run_not_active', 'This terminal has no active parent run.')
+    if (call === 'terminal.subagents.register') {
+      if (!Array.isArray(params.tools) || params.tools.some((name: unknown) => typeof name !== 'string')) throw invalid('Native tool names are required.')
+      const readOnly = live.input.readOnly === true
+      const readTools = new Set([...READ_ONLY_TOOLS, SPAWN_SUBAGENT, WAIT_SUBAGENTS, 'ask_user', 'mcp_list_tools', 'mcp_call_tool', 'history_search', 'history_read', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load'])
+      const tools = params.tools.filter((name: string) => !readOnly || readTools.has(name)) as string[]
+      const capabilities = this.options.resolveCapabilities ? await this.options.resolveCapabilities(live.caller, tools, live.input.cwd) : { version: 1 as const, tools, connectors: [], contributions: [] }
+      freezeRun(this.options.env.root, run.runId, live.caller, capabilities)
+      service.register({
+        run: { id: run.runId, sessionId: live.input.sessionId, mode: live.input.run?.mode ?? 'code', projectId: live.input.projectId, worktreeId: live.input.run?.worktreeId },
+        cwd: live.input.cwd, sessionDir: this.historyDir(live.input), text: '', caller: live.caller,
+        model: typeof params.model === 'string' ? params.model : live.input.model,
+        effort: typeof params.effort === 'string' ? params.effort as Effort : null,
+        launch: live.input.launch, tools: { allow: capabilities.tools, gated: capabilities.tools.filter(name => !readTools.has(name)) },
+        connections: live.input.connections === false ? false : { readOnly }, subagents: live.input.subagents,
+        capabilities
+      }, live.account.id, capabilities)
+      service.restore(run.runId, params.history ?? { owners: [], receipts: [] })
+      return { runId: run.runId }
+    }
+    if (call === 'terminal.subagents.verify') { await service.verify(run.runId, params.history); return {} }
+    if (call === 'terminal.subagents.delivery') return service.delivery(run.runId, params.history, params.settle === true)
+    if (call === 'terminal.subagents.call') {
+      const tool = subagentTools(service, run.runId).find(tool => tool.name === params.name)
+      if (!tool) throw invalid('Unknown subagent tool.')
+      const reason = await this.decide(live, run, tool.name, params.input ?? {})
+      if (!reason.allowed) throw new HarnessError('tool_denied', reason.reason ?? 'Subagents are unavailable.')
+      const result = await tool.execute(params.input ?? {})
+      return typeof result === 'string' ? { text: result } : result
+    }
+    throw invalid('Unknown subagent operation.')
+  }
+
+  private trajectoryCall(live: Live, call: string, params: Record<string, unknown>): unknown {
+    if (call === 'terminal.trajectory.list') {
+      return { runs: listTerminalTrajectoryRuns(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId) }
+    }
+    if (call === 'terminal.trajectory.events') {
+      if (typeof params.runId !== 'string' || !params.runId) throw invalid('A run id is required.')
+      const afterSequence = params.afterSequence
+      if (afterSequence !== undefined && typeof afterSequence !== 'number') throw invalid('The event sequence must be a number.')
+      return readTerminalTrajectory(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId, params.runId, afterSequence as number | undefined)
+    }
+    throw new HarnessError('unknown_method', `Unknown call ${call}.`)
   }
 
   /**
@@ -403,6 +492,7 @@ export class Terminals {
    * process's end with `dispose`, also when it never starts.
    */
   async prepare(input: TerminalPrepareInput): Promise<TerminalLaunch> {
+    input = structuredClone(input)
     const { env, accounts, apps, bus } = this.options
     const { root } = env
     if (!input?.sessionId || !input.cwd || !input.sessionFolder) throw invalid('A terminal session needs an id, a working folder, and its own folder.')
@@ -438,6 +528,7 @@ export class Terminals {
           nativeSessionId: input.nativeSessionId ?? null,
           begin: ({ reservedRunId, text }) => this.begin(live, reservedRunId, text),
           policy: (run, tool, args) => this.decide(live, run, tool, args),
+          allowToolGlobally: target => { this.options.approvals.allowTool('pi', target) },
           native: (nativeSessionId) => bus.emit({ type: 'terminal.native', sessionId, nativeSessionId }),
           telemetry: (event) => bus.emit({ type: 'terminal.telemetry', sessionId, event }),
           interrupt: runId => this.options.runs.interrupt(runId),
@@ -451,6 +542,23 @@ export class Terminals {
         caller: () => ({ ...caller, runId: live.controller.activeRun?.runId ?? null }),
         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.startsWith('terminal.trajectory.')) return this.trajectoryCall(live, call, params)
+          if (call === 'terminal.permissions.get') {
+            const policy = this.options.approvals.read()
+            return { full: this.options.approvals.isAuto('pi'), globalTools: policy.globalTools.pi ?? [] }
+          }
+          if (call === 'terminal.permissions.setFull') {
+            if (typeof params.enabled !== 'boolean') throw invalid('A boolean permission state is required.')
+            return { full: this.options.approvals.setAuto('pi', params.enabled).auto.pi === true }
+          }
+          if (call === 'terminal.permissions.setTool') {
+            if (typeof params.tool !== 'string' || !params.tool.trim() || typeof params.allowed !== 'boolean') throw invalid('A tool name and boolean permission state are required.')
+            const policy = params.allowed
+              ? this.options.approvals.allowTool('pi', params.tool)
+              : this.options.approvals.revokeTool('pi', params.tool)
+            return { globalTools: policy.globalTools.pi ?? [] }
+          }
           if (call !== 'terminal.resources') return live.controller.control(call, params)
           const current = await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, account), install: false, caller: { projectId: input.projectId ?? null } }) ?? null
           if (resourceIdentity(current) !== resourceIdentity(loading)) throw new HarnessError('terminal_resources_changed', 'Trusted resources changed since this terminal was prepared. Review /plugins and reopen the terminal to load the new selection.')

package/src/terminal/trajectory.test.ts

@@ -0,0 +1,66 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, expect, it } from 'vitest'
+
+import { closeIndex } from '../core/index'
+import type { RunEvent, RunRecord } from '../sessions/contracts'
+import { appendEvent, saveRun } from '../sessions/runStore'
+import { listTerminalTrajectoryRuns, readTerminalTrajectory } from './trajectory'
+
+const roots: string[] = []
+afterEach(() => {
+  for (const root of roots.splice(0)) closeIndex(root)
+})
+
+function setup() {
+  const root = mkdtempSync(join(tmpdir(), 'harness-terminal-trajectory-'))
+  roots.push(root)
+  const run = (id: string, sessionId: string, nativeSessionId: string | null): RunRecord => ({
+    id, sessionId, nativeSessionId, mode: 'code', goal: id,
+    resumedFromRunId: null, parentRunId: null, relation: null, terminalReason: null,
+    projectId: null, harness: 'pi', sessionType: 'terminal', workingDirectory: '/project',
+    worktreeId: null, attachmentCount: 0, startedAt: `2026-10-18T00:00:0${id.slice(-1)}Z`,
+    endedAt: null, status: 'running', exitCode: null, handoffId: null,
+    accountId: 'account-1', agentId: null, trigger: null
+  })
+  return { root, run }
+}
+
+const event = (runId: string, sessionId: string, sequence: number): RunEvent => ({
+  id: `${runId}-event-${sequence}`, runId, sessionId, sequence,
+  timestamp: `2026-10-18T00:00:0${sequence}Z`, type: 'started', payload: {}
+})
+
+it('lists newest runs only for the current terminal session and native conversation', () => {
+  const { root, run } = setup()
+  for (const item of [
+    run('run-1', 'terminal-1', '/history/one.jsonl'),
+    run('run-2', 'terminal-1', '/history/two.jsonl'),
+    run('run-3', 'terminal-2', '/history/one.jsonl')
+  ]) saveRun(root, item)
+
+  expect(listTerminalTrajectoryRuns(root, 'terminal-1', '/history/one.jsonl').map(item => item.id)).toEqual(['run-1'])
+  expect(listTerminalTrajectoryRuns(root, 'terminal-1', null)).toEqual([])
+})
+
+it('reads a selected run and only returns events after the requested sequence', () => {
+  const { root, run } = setup()
+  saveRun(root, run('run-1', 'terminal-1', '/history/current.jsonl'))
+  appendEvent(root, event('run-1', 'terminal-1', 0))
+  appendEvent(root, event('run-1', 'terminal-1', 1))
+
+  expect(readTerminalTrajectory(root, 'terminal-1', '/history/current.jsonl', 'run-1', 0)).toMatchObject({
+    run: { id: 'run-1', goal: 'run-1' },
+    events: [{ sequence: 1 }]
+  })
+})
+
+it('does not reveal runs from a different terminal or native conversation', () => {
+  const { root, run } = setup()
+  saveRun(root, run('run-1', 'terminal-1', '/history/one.jsonl'))
+
+  expect(() => readTerminalTrajectory(root, 'terminal-2', '/history/one.jsonl', 'run-1')).toThrow('Run was not found')
+  expect(() => readTerminalTrajectory(root, 'terminal-1', '/history/two.jsonl', 'run-1')).toThrow('Run was not found')
+  expect(() => readTerminalTrajectory(root, 'terminal-1', '/history/one.jsonl', 'run-1', -1)).toThrow('Run was not found')
+})

package/src/terminal/trajectory.ts

@@ -0,0 +1,44 @@
+import { notFound } from '../core/errors'
+import type { RunEvent, RunRecord } from '../sessions/contracts'
+import { findRun, listRuns, readEvents } from '../sessions/runStore'
+
+export type TerminalTrajectoryRun = Pick<RunRecord, 'id' | 'mode' | 'goal' | 'startedAt' | 'endedAt' | 'status'>
+
+export interface TerminalTrajectorySnapshot {
+  run: TerminalTrajectoryRun
+  events: RunEvent[]
+}
+
+function summary(run: RunRecord): TerminalTrajectoryRun {
+  return {
+    id: run.id,
+    mode: run.mode,
+    goal: run.goal,
+    startedAt: run.startedAt,
+    endedAt: run.endedAt,
+    status: run.status
+  }
+}
+
+/** The native conversation file is the terminal's boundary for this read-only view. */
+export function listTerminalTrajectoryRuns(root: string, sessionId: string, nativeSessionId: string | null): TerminalTrajectoryRun[] {
+  if (!nativeSessionId) return []
+  return listRuns(root, { sessionId })
+    .filter(run => run.nativeSessionId === nativeSessionId)
+    .map(summary)
+}
+
+/** Read a run only when it belongs to both this terminal and its current native conversation. */
+export function readTerminalTrajectory(
+  root: string,
+  sessionId: string,
+  nativeSessionId: string | null,
+  runId: string,
+  afterSequence?: number
+): TerminalTrajectorySnapshot {
+  if (!nativeSessionId || !Number.isSafeInteger(afterSequence ?? 0) || (afterSequence ?? 0) < 0) throw notFound('Run')
+  const run = findRun(root, runId)
+  if (!run || run.sessionId !== sessionId || run.nativeSessionId !== nativeSessionId) throw notFound('Run')
+  const events = readEvents(root, runId).filter(event => afterSequence === undefined || event.sequence > afterSequence)
+  return { run: summary(run), events }
+}