@xingular/harness 0.1.7 → 2.0.0

package/src/sessions/subagents.ts

@@ -0,0 +1,97 @@
+import { takeChars } from '../core/text'
+import { findRun, loadRun, readEvents } from './runStore'
+
+export const SPAWN_SUBAGENT = 'spawn_subagent'
+export const WAIT_SUBAGENTS = 'wait_subagents'
+export const SUBAGENT_RELATION = 'subagent'
+
+/** How deep subagents may nest when the caller does not say. */
+export const DEFAULT_SUBAGENT_DEPTH = 1
+export const MAX_SUBAGENT_DEPTH = 3
+
+export interface SubagentOptions {
+  /** Maximum consecutive native subagent levels below a caller (1 to 3). */
+  maxDepth?: number
+}
+
+export function subagentDepth(options: SubagentOptions | undefined): number {
+  const value = Math.trunc(options?.maxDepth ?? DEFAULT_SUBAGENT_DEPTH)
+  return Math.min(MAX_SUBAGENT_DEPTH, Math.max(1, Number.isFinite(value) ? value : DEFAULT_SUBAGENT_DEPTH))
+}
+
+export interface SubagentInput {
+  parentRunId: string
+  brief: string
+  tools?: string[]
+  wait?: boolean
+}
+
+export interface SubagentSelection {
+  parentRunId: string
+  runIds?: string[]
+}
+
+export interface SubagentResult {
+  runId: string
+  status: string
+  text: string
+  terminalReason: string | null
+}
+
+export interface SubagentReceipt {
+  version: 1
+  ownerRunId: string
+  spawned?: string[]
+  delivered?: string[]
+}
+
+export const SUBAGENT_RECEIPT = 'xingularSubagents'
+export const SUBAGENT_OWNER = 'xingular-subagent-owner'
+export const SUBAGENT_RESULTS = 'xingular-subagent-results'
+
+/** Read explicit native metadata, including entries retained before compaction. */
+export function subagentHistory(entries: readonly unknown[]): { owners: string[]; receipts: SubagentReceipt[] } {
+  const owners: string[] = []
+  const receipts: SubagentReceipt[] = []
+  for (const raw of entries) {
+    if (!raw || typeof raw !== 'object') continue
+    const entry = raw as Record<string, any>
+    if (entry.type === 'custom' && entry.customType === SUBAGENT_OWNER && typeof entry.data?.runId === 'string') owners.push(entry.data.runId)
+    const message = entry.type === 'message' ? entry.message : entry
+    const receipt = message?.details?.[SUBAGENT_RECEIPT]
+    if (!receipt || receipt.version !== 1 || typeof receipt.ownerRunId !== 'string') continue
+    const strings = (value: unknown): value is string[] => Array.isArray(value) && value.every((id) => typeof id === 'string')
+    if ((receipt.spawned !== undefined && !strings(receipt.spawned)) || (receipt.delivered !== undefined && !strings(receipt.delivered))) continue
+    receipts.push(receipt)
+  }
+  return { owners, receipts }
+}
+
+/** Native nesting is independent of a host's other uses of the generic caller depth. */
+export function subagentNesting(root: string, run: { relation?: string | null; parentRunId?: string | null }): number {
+  let current: typeof run = run
+  let depth = 0
+  const visited = new Set<string>()
+  while (current.relation === SUBAGENT_RELATION) {
+    const parent = current.parentRunId
+    if (!parent || visited.has(parent)) return MAX_SUBAGENT_DEPTH
+    visited.add(parent)
+    depth++
+    const record = findRun(root, parent)
+    if (!record) return MAX_SUBAGENT_DEPTH
+    current = record
+  }
+  return depth
+}
+
+/** The child's final reply, or why it ended without one. */
+export function subagentReport(root: string, runId: string): string {
+  const run = loadRun(root, runId)
+  const reply = readEvents(root, runId).filter((event) => event.type === 'message.completed' && (event.payload as { role?: unknown }).role === 'assistant').at(-1)
+  const text = typeof (reply?.payload as { text?: unknown } | undefined)?.text === 'string' ? takeChars((reply!.payload as { text: string }).text, 16_000) : ''
+  const lines = [`Subagent run ${runId} · ${run.status}`]
+  if (text) lines.push(`Result:\n${text}`)
+  else if (run.status === 'completed') lines.push('It finished without a written reply.')
+  if (run.status !== 'completed' && run.terminalReason) lines.push(`Stopped because: ${run.terminalReason}`)
+  return lines.join('\n')
+}

package/src/terminal/controller.ts

@@ -12,6 +12,8 @@ export interface PolicyReply {
   allowed: boolean
   reason?: string | null
   requiresApproval?: boolean
+  rememberable?: boolean
+  standing?: 'full' | 'switch' | 'none'
 }
 
 export interface ControllerHooks {
@@ -21,6 +23,8 @@ export interface ControllerHooks {
   begin(input: { reservedRunId: string | null; nativeTurnId: string; text: string }): ActiveRun
   /** Whether a native tool call may run. */
   policy(run: ActiveRun, tool: string, args: unknown): Promise<PolicyReply>
+  /** Saves a user-selected tool grant in the shared local approval store. */
+  allowToolGlobally(target: string): void
   /** The native conversation identity changed. */
   native(nativeSessionId: string): void
   telemetry(event: string): void
@@ -148,18 +152,23 @@ export class TerminalController {
   }
 
   /** Project registry-owned questions, including grouped requests, into the terminal inbox. */
-  observe(event: RunEvent): void {
-    if (this.disposed || event.runId !== this.activeRun?.runId) return
+  observe(event: RunEvent, descendant = false): void {
+    if (this.disposed || !this.activeRun || (!descendant && event.runId !== this.activeRun.runId)) return
     if (event.type === 'question.requested') {
       const payload = event.payload as Record<string, unknown>
-      this.pending.set(String(payload.questionId), { ...payload, type: 'question', requestId: payload.questionId })
+      this.pending.set(String(payload.questionId), { ...payload, type: 'question', requestId: payload.questionId, runId: event.runId })
+    } else if (descendant && event.type === 'approval.requested') {
+      const payload = event.payload as Record<string, unknown>
+      if (!payload.automatic) this.pending.set(String(payload.approvalId), { ...payload, type: 'approval', requestId: payload.approvalId, runId: event.runId })
+    } else if (event.type === 'approval.resolved') {
+      this.pending.delete(String((event.payload as { approvalId: string }).approvalId))
     } else if (event.type === 'question.answered') {
       this.pending.delete(String((event.payload as { questionId: string }).questionId))
     }
   }
 
   /** The socket grants this interface only to the process that owns terminal input. */
-  control(call: string, data: Record<string, any>): unknown {
+  async control(call: string, data: Record<string, any>): Promise<unknown> {
     if (this.disposed) throw new HarnessError('terminal_not_ready', 'This terminal has ended.')
     if (call === 'terminal.draft') {
       this.dirty = data.dirty === true
@@ -168,12 +177,18 @@ export class TerminalController {
     }
     if (call === 'terminal.pending') return { requests: [...this.pending.values()] }
     if (call === 'terminal.interrupt') return this.activeRun && this.hooks.interrupt ? this.hooks.interrupt(this.activeRun.runId) : {}
+    if (call === 'terminal.policy') {
+      const run = this.activeRun
+      if (!run || typeof data.tool !== 'string' || !data.tool) throw new HarnessError('invalid_request', 'An active run and tool name are required.')
+      return this.hooks.policy(run, data.tool, data.args ?? {})
+    }
+    if (call === 'terminal.approval') return this.requestNativeApproval(data)
     if (call === 'terminal.answers' && this.hooks.answerQuestions) {
       const run = this.activeRun
       const batchId = String(data.batchId ?? '')
       const requests = [...this.pending.values()].filter(request => request.batchId === batchId)
       if (!run || !batchId || !requests.length || !Array.isArray(data.answers)) throw new HarnessError('invalid_request', 'This question batch is no longer pending.')
-      this.hooks.answerQuestions(run.runId, batchId, data.answers)
+      this.hooks.answerQuestions(String(requests[0].runId ?? run.runId), batchId, data.answers)
       return {}
     }
     const requestId = String(data.requestId ?? '')
@@ -182,17 +197,65 @@ export class TerminalController {
     if (!request || !run) throw new HarnessError('invalid_request', 'This terminal decision is no longer pending.')
     if (call === 'terminal.approve' && request.type === 'approval' && this.hooks.resolveApproval) {
       if (data.decision !== 'approved' && data.decision !== 'denied') throw new HarnessError('invalid_request', 'Choose approve or deny.')
-      this.hooks.resolveApproval(run.runId, requestId, data.decision)
+      const alwaysAllow = data.alwaysAllow === true
+      if (alwaysAllow && request.rememberable !== true) throw new HarnessError('invalid_request', 'This approval cannot be remembered for other sessions.')
+      let decision: ApprovalDecision = data.decision
+      if (decision === 'approved' && request.direct === true) {
+        const operation = request.operation as { tool?: unknown; args?: unknown } | undefined
+        const tool = typeof operation?.tool === 'string' ? operation.tool : ''
+        const current = await this.hooks.policy(run, tool, operation?.args ?? {})
+        if (!current.allowed && !current.requiresApproval) decision = 'denied'
+        if (alwaysAllow && current.rememberable !== true) {
+          request.rememberable = false
+          throw new HarnessError('invalid_request', 'This tool can no longer be allowed across sessions. Review the approval again.')
+        }
+      }
+      if (decision === 'approved' && alwaysAllow) this.hooks.allowToolGlobally(String(request.target ?? ''))
+      this.hooks.resolveApproval(String(request.runId ?? run.runId), requestId, decision)
       return {}
     }
     if (call === 'terminal.answer' && request.type === 'question' && this.hooks.answerQuestion) {
       if (!data.answer || !Array.isArray(data.answer.selected)) throw new HarnessError('invalid_request', 'A question answer is required.')
-      this.hooks.answerQuestion(run.runId, requestId, data.answer)
+      this.hooks.answerQuestion(String(request.runId ?? run.runId), requestId, data.answer)
       return {}
     }
     throw new HarnessError('unknown_method', `Unknown terminal control ${call}.`)
   }
 
+  private async requestNativeApproval(data: Record<string, any>): Promise<unknown> {
+    const run = this.activeRun
+    const requestId = typeof data.requestId === 'string' ? data.requestId : ''
+    const tool = typeof data.tool === 'string' ? data.tool : ''
+    if (!run || !requestId || !tool) throw new HarnessError('invalid_request', 'An active run, request id, and tool name are required.')
+    const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args as Record<string, unknown> : {}
+    const policy = await this.hooks.policy(run, tool, args)
+    if (!policy.allowed && !policy.requiresApproval) return { decision: 'denied' }
+    if (policy.allowed && !policy.requiresApproval) return { decision: 'approved' }
+    const key = this.requestId(`approval:${requestId}`)
+    const existing = this.seen.get(key)
+    if (existing) return { decision: await existing }
+    const action = JSON.stringify(args)
+    const operation = { tool, args }
+    const response = run.requestApproval({
+      requestId: key,
+      target: tool,
+      action,
+      operation,
+      rememberable: policy.rememberable === true,
+      standing: policy.standing
+    })
+    this.pending.set(key, {
+      type: 'approval', requestId: key, runId: run.runId, target: tool, action,
+      operation, rememberable: policy.rememberable === true, direct: true
+    })
+    this.seen.set(key, response)
+    try {
+      return { decision: await response }
+    } finally {
+      this.pending.delete(key)
+    }
+  }
+
   async accept(event: string, data: Record<string, any>): Promise<unknown> {
     if (this.disposed) throw new Error('This terminal controller was disposed.')
     if (event !== 'poll') this.hooks.telemetry(event)
@@ -220,8 +283,8 @@ export class TerminalController {
       return {}
     }
     if (event === 'begin') {
-      this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''))
-      return {}
+      const run = this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''))
+      return { runId: run.runId }
     }
     if (event === 'shutdown') {
       this.ready = false
@@ -229,7 +292,7 @@ export class TerminalController {
       return {}
     }
     if (event === 'settled') {
-      this.finish(data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined)
+      this.finish(data.aborted ? 'interrupted' : data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined)
       return {}
     }
     const run = this.run

package/src/terminal/piExtension.ts

@@ -9,7 +9,8 @@ import { connectionFromEnv, socketCall, terminalCall } from './client'
 import { runAccountsMenu, type SessionAccount } from './accountsMenu'
 import { runPluginsMenu } from './pluginMenu'
 import { runHubMenu } from './hubMenu'
-import { claimTerminalControl } from './control'
+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'
 
@@ -27,9 +28,18 @@ function resultSize(result: unknown): number | null {
   return content.reduce((total: number, part: { type?: string; text?: unknown }) => total + (part?.type === 'text' && typeof part.text === 'string' ? part.text.length : 0), 0)
 }
 
+async function withParentCancellation<T>(signal: AbortSignal | undefined, work: () => Promise<T>): Promise<T> {
+  const stop = () => { void controlCall('terminal.interrupt').catch(() => {}) }
+  if (signal?.aborted) stop()
+  signal?.addEventListener('abort', stop, { once: true })
+  try { return await work() } finally { signal?.removeEventListener('abort', stop) }
+}
+
 export default async function (pi: ExtensionAPI) {
   await terminalCall('startup', { phase: 'Pi extension loaded' })
   let context: ExtensionContext | null = null
+  let nativeSubagents = false
+  let subagentParent = false
   let timer: ReturnType<typeof setInterval> | null = null
   let polling = false
   let failure: string | undefined
@@ -105,6 +115,15 @@ export default async function (pi: ExtensionAPI) {
         }
       })
     }
+    const native = await controlCall<{ tools: SocketTool[] }>('terminal.subagents.tools')
+    nativeSubagents = native.tools.length > 0
+    for (const tool of native.tools) pi.registerTool({
+      name: tool.name, label: tool.label, description: tool.description, parameters: Type.Unsafe(tool.parameters),
+      execute: async (_id, input, signal) => {
+        const result = await withParentCancellation(signal, () => controlCall<{ text: string; details?: Record<string, unknown> }>('terminal.subagents.call', { name: tool.name, input }, 2_147_483_647))
+        return { content: [{ type: 'text' as const, text: result.text }], details: result.details ?? {} }
+      }
+    })
   } catch (error) {
     await terminalCall('startupFailed', { reason: `${stage} failed: ${error instanceof Error ? error.message : 'Unavailable'}` }).catch(() => {})
     throw error
@@ -142,8 +161,21 @@ export default async function (pi: ExtensionAPI) {
     reasoningTokens = undefined
     costReported = false
     // A run a plugin starts with a custom message has no user prompt to record; it still begins a turn.
-    await terminalCall('begin', { text: event.messageType === 'user' ? event.prompt : '' })
+    const begun = await terminalCall<{ runId: string }>('begin', { text: event.messageType === 'user' ? event.prompt : '' })
+    if (nativeSubagents) {
+      pi.appendEntry(SUBAGENT_OWNER, { runId: begun.runId })
+      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
+    }
   })
+  const deliverChildren = async (event: any, ctx: ExtensionContext, settle: boolean) => {
+    if (!nativeSubagents || (settle && event.outcome !== 'completed') || ctx.signal?.aborted) return
+    const result = await withParentCancellation(ctx.signal, () => controlCall<{ text: string; receipt: SubagentReceipt } | null>('terminal.subagents.delivery', { history: subagentHistory([...ctx.sessionManager.getBranch(), ...event.entries]), settle }, 2_147_483_647))
+    if (!result) return
+    return { entries: [...event.entries, { type: 'custom_message' as const, customType: SUBAGENT_RESULTS, content: result.text, display: false, details: { [SUBAGENT_RECEIPT]: result.receipt } }], continue: true }
+  }
+  pi.on('turn_end', (event, ctx) => deliverChildren(event, ctx, false))
+  pi.on('agent_before_settle', (event, ctx) => deliverChildren(event, ctx, true))
   pi.on('message_end', async (event) => {
     if (event.message.role !== 'assistant') return
     if (event.message.stopReason === 'error' || event.message.stopReason === 'aborted') failure = event.message.errorMessage ?? `Pi stopped: ${event.message.stopReason}`
@@ -193,9 +225,9 @@ export default async function (pi: ExtensionAPI) {
   })
   pi.on('tool_call', async (event) => {
     try {
-      const policy = await terminalCall<{ allowed: boolean; reason?: string; requiresApproval?: boolean }>('policy', { tool: event.toolName, args: event.input })
+      const policy = await controlCall<{ allowed: boolean; reason?: string; requiresApproval?: boolean }>('terminal.policy', { tool: event.toolName, args: event.input })
       if (policy.requiresApproval) {
-        const approval = await terminalCall<{ decision: string }>('approval', { requestId: event.toolCallId, target: event.toolName, action: JSON.stringify(event.input), tool: event.toolName, args: event.input })
+        const approval = await controlCall<{ decision: string }>('terminal.approval', { requestId: event.toolCallId, tool: event.toolName, args: event.input })
         if (approval.decision === 'approved') return
         return { block: true, reason: 'The user denied this action. Ask how they would like to proceed.' }
       }
@@ -218,8 +250,12 @@ export default async function (pi: ExtensionAPI) {
     fileTools.delete(event.toolCallId)
     if (!event.isError && path) await terminalCall('file', { path, change: 'modified' })
   })
-  pi.on('agent_settled', async () => {
-    await terminalCall('settled', { error: failure })
+  pi.on('agent_settled', async (event, ctx) => {
+    if (subagentParent && !event.aborted && !failure) {
+      try { await controlCall('terminal.subagents.verify', { history: subagentHistory(ctx.sessionManager.getBranch()) }, 2_147_483_647) } catch (error) { failure = error instanceof Error ? error.message : String(error) }
+    }
+    subagentParent = false
+    await terminalCall('settled', { error: failure, aborted: event.aborted })
   })
   pi.on('user_bash', async () => {
     throw new Error('Use the bash tool so this action can be checked.')

package/src/terminal/socket.test.ts

@@ -33,6 +33,29 @@ describe('session socket path', () => {
 })
 
 describe('session socket', () => {
+  it.skipIf(process.platform === 'win32')('keeps an existing Harness socket reachable when another instance uses the same state folder', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'sock-shared-state-'))
+    const path = socketPath(base)
+    const first = new SessionSocket(path, handlers)
+    const second = new SessionSocket(path, handlers)
+    const canConnect = (socketPath: string): Promise<void> => new Promise((resolve, reject) => {
+      const client = createConnection(socketPath)
+      client.once('connect', () => { client.end(); resolve() })
+      client.once('error', reject)
+    })
+    try {
+      await first.listen()
+      await second.listen()
+      expect(second.path).not.toBe(first.path)
+      await second.close()
+      await expect(canConnect(first.path)).resolves.toBeUndefined()
+    } finally {
+      await first.close()
+      await second.close()
+      rmSync(base, { recursive: true, force: true })
+    }
+  })
+
   it.skipIf(process.platform !== 'win32')('listens on a named pipe and answers a request on Windows', async () => {
     const socket = new SessionSocket(socketPath('unused'), handlers)
     await socket.listen()

package/src/terminal/socket.ts

@@ -56,6 +56,11 @@ export function socketPath(stateDir: string): string {
   return join(tmpdir(), `xh-${createHash('sha256').update(path).digest('hex').slice(0, 16)}.sock`)
 }
 
+function alternateSocketPath(path: string): string {
+  const candidate = join(dirname(path), `harness-${process.pid}-${randomBytes(8).toString('hex')}.sock`)
+  return Buffer.byteLength(candidate) <= MAX_SOCKET_PATH ? candidate : join(tmpdir(), `xh-${randomBytes(16).toString('hex')}.sock`)
+}
+
 /** A named pipe has no folder, file mode, or owner to check or clean up. */
 const isPipePath = (path: string): boolean => path.startsWith('\\\\.\\pipe\\')
 
@@ -88,6 +93,7 @@ function refusedBind(path: string, error: unknown): unknown {
 export class SessionSocket {
   private server: Server | null = null
   private listening: Promise<void> | null = null
+  private socketPathValue: string
   private readonly grants = new Map<string, SocketGrant>()
   /**
    * A second key per token, handed out once. The token is in the session's environment, where a
@@ -97,10 +103,11 @@ export class SessionSocket {
   private readonly controls = new Map<string, string>()
   private readonly clients = new Set<Socket>()
 
-  constructor(
-    readonly path: string,
-    private readonly handlers: SocketHandlers
-  ) {}
+  constructor(path: string, private readonly handlers: SocketHandlers) {
+    this.socketPathValue = path
+  }
+
+  get path(): string { return this.socketPathValue }
 
   issue(grant: SocketGrant): string {
     const token = `${newId()}${newId()}`.replaceAll('-', '')
@@ -141,6 +148,7 @@ export class SessionSocket {
       const call = typeof request.call === 'string' ? request.call : ''
       const params = (request.params && typeof request.params === 'object' ? request.params : {}) as Record<string, unknown>
       if (['wiki.', 'memory.', 'recall.'].some((prefix) => call.startsWith(prefix))) return { result: this.handlers.memory(grant.caller(), call, params) }
+      if (call === 'tools.list' && !grant.broker) return { result: { tools: [] } }
       if (['mcp.', 'tools.'].some((prefix) => call.startsWith(prefix))) {
         if (!grant.broker) throw new HarnessError('mcp_unauthorized', 'Connected apps are not available to this session.')
         return { result: await this.handlers.apps(grant.broker, call, params) }
@@ -193,22 +201,14 @@ export class SessionSocket {
     })
   }
 
-  /** Binds the socket once; later calls wait for the same bind. */
-  listen(): Promise<void> {
-    this.listening ??= new Promise<void>((resolve, reject) => {
-      if (!isPipePath(this.path)) {
-        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
-        rmSync(this.path, { force: true })
-      }
+  private bind(path: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
       const server = createServer((client) => this.serve(client))
-      server.once('error', (error) => {
-        this.listening = null
-        reject(refusedBind(this.path, error))
-      })
-      server.listen(this.path, () => {
-        if (!isPipePath(this.path)) {
+      server.once('error', reject)
+      server.listen(path, () => {
+        if (!isPipePath(path)) {
           try {
-            chmodSync(this.path, 0o600)
+            chmodSync(path, 0o600)
           } catch (error) {
             log('session socket permissions', error instanceof Error ? error.message : String(error))
           }
@@ -217,6 +217,30 @@ export class SessionSocket {
         resolve()
       })
     })
+  }
+
+  /** Binds the usual path, or an instance-specific path if another Harness owns it. */
+  private async bindAvailablePath(): Promise<void> {
+    if (!isPipePath(this.path)) mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
+    try {
+      await this.bind(this.path)
+    } catch (error) {
+      if (isPipePath(this.path) || (error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw refusedBind(this.path, error)
+      this.socketPathValue = alternateSocketPath(this.path)
+      try {
+        await this.bind(this.path)
+      } catch (alternateError) {
+        throw refusedBind(this.path, alternateError)
+      }
+    }
+  }
+
+  /** Binds the socket once; later calls wait for the same bind. */
+  listen(): Promise<void> {
+    this.listening ??= this.bindAvailablePath().catch(error => {
+      this.listening = null
+      throw error
+    })
     return this.listening
   }
 

package/src/terminal/standalone.ts

@@ -1,9 +1,11 @@
 // The standalone host prepares an isolated Harness terminal and supervises its frontend.
 import { spawn as nodeSpawn } from 'node:child_process'
 import { createHash, randomUUID } from 'node:crypto'
+import { appendFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { isAbsolute, join, resolve } from 'node:path'
 
+import { setLogSink } from '../core/bus'
 import { createHarness, type Harness, type HarnessOptions } from '../harness'
 import type { TerminalLaunch } from './terminals'
 
@@ -128,6 +130,15 @@ export async function runStandaloneTerminal(argv: string[], dependencies: Standa
   const harness = makeHarness({ dataRoot: paths.dataRoot, stateDir: paths.stateDir, productName: 'Xingular Harness' })
   const newSessionId = dependencies.createSessionId ?? randomUUID
   let current = { sessionId: newSessionId(), accountId: null as string | null, nativeSessionId: null as string | null }
+  // The frontend draws on this terminal, so the host's diagnostics go to a file the person can read instead.
+  const logFile = join(paths.stateDir, 'harness.log')
+  setLogSink((text) => {
+    try {
+      appendFileSync(logFile, `${new Date().toISOString()} ${text}\n`)
+    } catch {
+      // Diagnostics are best effort; a full disk must not stop the terminal.
+    }
+  })
 
   try {
     await harness.ready
@@ -149,5 +160,6 @@ export async function runStandaloneTerminal(argv: string[], dependencies: Standa
   } finally {
     await harness.terminals.dispose(current.sessionId)
     await harness.close()
+    setLogSink(null)
   }
 }