@xingular/harness 2.1.2 → 3.0.0

package/src/terminal/terminal.test.ts

@@ -107,11 +107,8 @@ describe('a pi terminal session', () => {
     expect(`${result.stdout}${result.stderr}`).toMatch(/usage|options|pi coding agent/i)
   })
 
-  it('passes what the harness found as paths, the enabled registry items with them, and its own extension last', async () => {
+  it('passes what the harness found as paths, the harness tree\'s skills and trusted plugins with them, and its own extension last', async () => {
     const root = rootWithProject()
-    writeFile(join(root, 'registry/skills/release/SKILL.md'), '# Release\n')
-    writeFile(join(root, 'registry/prompts/review.md'), 'Review this.\n')
-    writeFile(join(root, 'config/registry-enabled.json'), JSON.stringify({ p1: ['skills/release', 'prompts/review'] }))
     writeFile(join(root, '.pi/extensions/local.ts'), 'export default function () {}\n')
     const item = (kind: Found['kind'], path: string, origin: Found['origin'], enabled = true): Found => ({ kind, path, origin, project: origin === 'project', packageRoot: null, source: null, enabled })
     const found = [
@@ -126,12 +123,17 @@ describe('a pi terminal session', () => {
     const harness = createHarness({ dataRoot: root, stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), piProgram: () => '/opt/pi/bin/pi', assets: { node: '/opt/node', cli: '/opt/harness/cli.js', piExtension: '/opt/harness/terminal-pi.js' }, resolver: async () => found })
     open.push(harness)
     const account = harness.accounts.create('Main', 'apiKey').accounts[0]
-    const prepare = async () => (await harness.terminals.prepare({ sessionId: 'term-1', accountId: account.id, projectId: 'p1', cwd: root, sessionFolder: join(root, 'sessions', 'p1', 'term-1') })).args.slice(2)
+    const tree = { 'systemprompt.md': 'Ship releases.\n', 'guardrails.md': '- When cutting a release, load the `release` skill.\n', 'memory.md': '', 'tool_guidance.md': '', 'skills/release/SKILL.md': '---\nname: release\ndescription: cutting a release\n---\nTag it.\n', 'plugins/guard.ts': 'export default function (pi) {}\n' }
+    const { commit, versionPath, head } = await import('../tree/store')
+    commit(root, 'term-agent', tree, { kind: 'seed' })
+    harness.trust.grant(tree['plugins/guard.ts'], 'plugins/guard.ts', 'term-agent')
+    const version = versionPath(root, 'term-agent', head(root, 'term-agent')!.fingerprint)
+    const prepare = async () => (await harness.terminals.prepare({ sessionId: 'term-1', accountId: account.id, projectId: 'p1', cwd: root, sessionFolder: join(root, 'sessions', 'p1', 'term-1'), harness: { scope: 'term-agent' } })).args.slice(2)
 
     const loaded = [
-      '--extension', '/shared/extensions/mine.ts', '--extension', 'builtin:mcp',
-      '--skill', join(root, 'registry/skills/release/SKILL.md'), '--skill', '/shared/skills/alpha/SKILL.md',
-      '--prompt-template', join(root, 'registry/prompts/review.md'), '--prompt-template', '/shared/prompts/p.md',
+      '--extension', '/shared/extensions/mine.ts', '--extension', 'builtin:mcp', '--extension', join(version, 'plugins/guard.ts'),
+      '--skill', join(version, 'skills'), '--skill', '/shared/skills/alpha/SKILL.md',
+      '--prompt-template', '/shared/prompts/p.md',
       '--theme', '/shared/themes/dark.json',
       '--extension', '/opt/harness/terminal-pi.js', '--session-dir', join(root, 'sessions', 'p1', 'term-1', 'pi')
     ]
@@ -191,24 +193,6 @@ describe('a pi terminal session', () => {
     expect(loadRun(root, 'reserved').status).toBe('interrupted')
   })
 
-  it('sends a memory block that changed since the session started along with the next instruction', async () => {
-    const { tell, harness, connection } = await setup()
-    await tell('ready', {})
-    await socketCall(connection, 'memory.append', { block: 'project', text: 'Prefers pnpm.' })
-    const first = harness.terminals.send({ sessionId: 'term-1', text: 'Continue' })
-    let delivered = ''
-    await vi.waitFor(async () => {
-      const { command } = await tell('poll')
-      expect(command?.type).toBe('send')
-      delivered = command.text
-    })
-    await tell('begin', { text: delivered })
-    await first
-    expect(delivered.startsWith('[Memory updated since this session')).toBe(true)
-    expect(delivered).toContain('Prefers pnpm.')
-    expect(delivered.endsWith('\n\nContinue')).toBe(true)
-  })
-
   it('will not send over a draft the person is typing, and fails a delivery the native session never acknowledges', async () => {
     const { tell, harness, root } = await setup()
     await tell('ready', {})
@@ -389,11 +373,11 @@ describe('a pi terminal session', () => {
     expect(harness.terminals.state('term-1').ready).toBe(false)
   })
 
-  it('serves memory and connected apps to the session over the socket, until the terminal ends', async () => {
+  it('serves the Wiki, skills and connected apps to the session over the socket, until the terminal ends', async () => {
     const { connection, harness, tell } = await setup()
     await tell('ready', {})
-    expect(await socketCall<string>(connection, 'wiki.entrypoint')).toContain('# Xingular Harness context')
-    expect(await socketCall<string>(connection, 'wiki.list')).toContain('library')
+    expect(await socketCall<string>(connection, 'skill.load')).toBe('You have no skills.')
+    expect(await socketCall<string>(connection, 'wiki.list')).toContain('home')
     const listed = await socketCall<{ tools: { name: string; parameters: { type: string } }[] }>(connection, 'tools.list')
     expect(listed.tools.map((tool) => tool.name)).toEqual(['mcp_list_tools', 'mcp_call_tool'])
     expect(listed.tools[0].parameters.type).toBe('object')
@@ -429,19 +413,17 @@ describe('the session socket', () => {
 })
 
 describe('xagent-wiki command', () => {
-  it('maps commands onto memory and Wiki calls', () => {
-    expect(parseCli(['search', 'deploy', 'steps', '--kind', 'page'])).toEqual({ kind: 'call', call: 'wiki.search', params: { query: 'deploy steps', kinds: ['page'] } })
-    expect(parseCli(['read', '/projects/app/arch'])).toEqual({ kind: 'call', call: 'wiki.read', params: { id: '/projects/app/arch' } })
+  it('maps commands onto Wiki, skill and history calls', () => {
+    expect(parseCli(['search', 'deploy', 'steps', '--project', 'app'])).toEqual({ kind: 'call', call: 'wiki.search', params: { query: 'deploy steps', project: 'app' } })
+    expect(parseCli(['read', 'projects/app/arch'])).toEqual({ kind: 'call', call: 'wiki.read', params: { path: 'projects/app/arch' } })
     expect(parseCli(['list'])).toEqual({ kind: 'call', call: 'wiki.list', params: {} })
-    expect(parseCli(['skill', 'review'])).toEqual({ kind: 'call', call: 'wiki.skill', params: { name: 'review' } })
-    expect(parseCli(['memory', '--namespace', '/projects/app'])).toEqual({ kind: 'call', call: 'wiki.memory', params: { namespace: '/projects/app' } })
+    expect(parseCli(['list', 'library'])).toEqual({ kind: 'call', call: 'wiki.list', params: { project: 'library' } })
+    expect(parseCli(['write', 'library/notes', 'Use', 'pnpm.'])).toEqual({ kind: 'call', call: 'wiki.write', params: { path: 'library/notes', text: 'Use pnpm.' } })
+    expect(parseCli(['write', 'library/notes', '-'])).toEqual({ kind: 'stdin-write', path: 'library/notes' })
+    expect(parseCli(['skill', 'review'])).toEqual({ kind: 'call', call: 'skill.load', params: { name: 'review' } })
     expect(parseCli(['recall', 'the', 'outage', '--scope', 'all'])).toEqual({ kind: 'call', call: 'recall.search', params: { query: 'the outage', scope: 'all' } })
-    expect(parseCli(['propose', '{"kind":"memory","title":"t","body":"b"}'])).toMatchObject({ kind: 'call', call: 'wiki.propose', params: { kind: 'memory' } })
-    expect(parseCli(['propose', '-'])).toEqual({ kind: 'stdin-propose' })
-    expect(parseCli(['block', 'append', 'project', 'Uses', 'pnpm.'])).toEqual({ kind: 'call', call: 'memory.append', params: { block: 'project', text: 'Uses pnpm.' } })
-    expect(parseCli(['block', 'replace', 'project', '--old', 'npm', '--new', 'pnpm'])).toEqual({ kind: 'call', call: 'memory.replace', params: { block: 'project', old: 'npm', new: 'pnpm' } })
     expect(parseCli(['search'])).toEqual({ kind: 'help' })
-    expect(parseCli(['nonsense'])).toEqual({ kind: 'help' })
+    expect(parseCli(['block', 'append', 'x', 'y'])).toEqual({ kind: 'help' })
   })
 })
 

package/src/terminal/terminals.ts

@@ -24,19 +24,20 @@ import { HarnessError, invalid } from '../core/errors'
 import { newId, now } from '../core/fs'
 import { prependSearchPath, searchPath } from '../core/path'
 import type { BrokerSession, ConnectedApps } from '../mcp/service'
-import type { CallerContext } from '../memory/caller'
-import { dispatch } from '../memory/dispatch'
+import type { CallerContext } from '../core/caller'
+import { dispatch } from '../tools/dispatch'
+import { materialise, type HarnessChoice } from '../tree/materialise'
+import type { TreeTrust } from '../tree/trust'
 import type { AttachParams, PluginScope } from '../plugins/api'
 import type { Loading, Plugins } from '../plugins/plugins'
 import type { Plugin } from '../plugins/types'
 import type { Hub } from '../hub/hub'
-import { compile, copyToRun, memoryDelta, record, render, saveForSession, type Launch } from '../prompt/compile'
+import { compile, copyToRun, record, render, saveForSession, type Launch } from '../prompt/compile'
 import type { RunRecord } from '../sessions/contracts'
 import { isActiveStatus } from '../sessions/contracts'
 import type { ToolPolicy } from '../sessions/policy'
 import type { ActiveRun, RunRegistry } from '../sessions/registry'
 import { findRun, loadRun, saveRun, updateRun } from '../sessions/runStore'
-import { resources } from '../skills/registry'
 import type { ToolSpec } from '../tools/types'
 import { APPS_COMMAND, WIKI_COMMAND } from './cli'
 import { SOCKET_ENV, TOKEN_ENV } from './client'
@@ -87,6 +88,8 @@ export interface TerminalPrepareInput {
   readOnly?: boolean
   /** What the application adds to the instructions, and which of its tools it describes. */
   launch?: Launch
+  /** The harness tree the session runs; its version is pinned for the session. */
+  harness?: HarnessChoice | null
   /** Give the session the connected-apps broker. Defaults to yes. */
   connections?: boolean
   /** Fields copied onto each run this session records. */
@@ -112,6 +115,8 @@ interface Live {
 }
 
 export interface TerminalsOptions {
+  /** Which plugin code in harness trees a person trusted. */
+  trust?: TreeTrust | null
   subagents?: Subagents
   resolveCapabilities?: (caller: CallerContext, tools: readonly string[], cwd: string) => Promise<CapabilitySet>
   env: HarnessEnv
@@ -144,6 +149,8 @@ const READ_ONLY_TOOLS = new Set(['read', 'grep', 'find', 'ls'])
 
 export class Terminals {
   private readonly sessions = new Map<string, Live>()
+  /** The harness tree each live session runs, for loading its skills. */
+  private readonly treeDirs = new Map<string, string>()
   private readonly socket: SessionSocket
   private readonly assets: TerminalAssets
   /** A session's `/accounts` switch, taken once its Pi process has ended. */
@@ -167,7 +174,7 @@ export class Terminals {
       }
     })
     this.socket = new SessionSocket(socketPath(options.stateDir), {
-      memory: (caller, call, params) => dispatch(options.env, caller, call, params),
+      memory: (caller, call, params) => dispatch(options.env, caller, call, params, { treeDir: (caller.sessionId && this.treeDirs.get(caller.sessionId)) || null }),
       apps: (session, call, params) => this.appsCall(session, call, params),
       plugins: (grant, call, params, control) => this.pluginsCall(grant.sessionId, call, params, control),
       accounts: (grant, call, params, control) => this.accountsCall(grant.sessionId, call, params, control)
@@ -513,8 +520,10 @@ export class Terminals {
       const broker = input.connections === false ? null : apps.grant({ sessionId, runId: null, caller, readOnly: !!input.readOnly, depth: 0 })
       // The session keeps these instructions; each of its runs records a copy, and a memory
       // block that changes later is sent along as a note.
-      const pack = compile(env, caller, { input: '', ...input.launch })
-      record(root, caller, pack)
+      const tree = input.harness ? materialise(root, input.harness, { trust: this.options.trust ?? null }) : null
+      if (tree) this.treeDirs.set(sessionId, tree.dir)
+      const pack = compile(env, caller, input.launch ?? {}, tree)
+      record(root, pack)
       mkdirSync(this.historyDir(input), { recursive: true })
       saveForSession(input.sessionFolder, pack)
 
@@ -584,10 +593,9 @@ export class Terminals {
       if (loading) {
         // Pi's own discovery is off: the terminal loads what the harness found and nothing else.
         args.push('--no-extensions', '--no-skills', '--no-prompt-templates', '--no-themes')
-        const enabled = resources(root, input.projectId ?? null)
-        for (const path of [...loading.extensionPaths, ...loading.builtins]) args.push('--extension', path)
-        for (const path of [...enabled.skillPaths, ...loading.skillPaths]) args.push('--skill', path)
-        for (const path of [...enabled.promptPaths, ...loading.promptPaths]) args.push('--prompt-template', path)
+        for (const path of [...loading.extensionPaths, ...loading.builtins, ...(tree?.extensionPaths ?? [])]) args.push('--extension', path)
+        for (const path of [...(tree?.skillPaths ?? []), ...loading.skillPaths]) args.push('--skill', path)
+        for (const path of loading.promptPaths) args.push('--prompt-template', path)
         for (const path of loading.themePaths) args.push('--theme', path)
       }
       // Last, so its gate sees a tool call as every other extension left it.
@@ -626,10 +634,9 @@ export class Terminals {
     const runId = input.runId || newId()
     if (findRun(root, runId)) throw invalid('This run already exists.')
     saveRun(root, this.runRecord(live, runId, input.text))
-    const note = memoryDelta(env, live.input.sessionFolder, { ...live.caller, runId })
     copyToRun(root, live.input.sessionFolder, runId)
     try {
-      await live.controller.send(runId, note ? `${note}\n\n${input.text}` : input.text)
+      await live.controller.send(runId, input.text)
     } catch (error) {
       updateRun(root, runId, (run) => {
         if (!isActiveStatus(run.status)) return

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

@@ -3,7 +3,17 @@ import { stripTerminalSequences } from '@earendil-works/pi-tui'
 import { describe, expect, it, vi } from 'vitest'
 
 vi.mock('../control', () => ({ controlCall: vi.fn(async () => ({})) }))
+vi.mock('./piAdapter', async importOriginal => ({
+  ...await importOriginal<typeof import('./piAdapter')>(),
+  loadPiAdapter: vi.fn()
+}))
+vi.mock('./clipboardFiles', async importOriginal => ({
+  ...await importOriginal<typeof import('./clipboardFiles')>(),
+  stageClipboardFiles: vi.fn()
+}))
 import { controlCall } from '../control'
+import { loadPiAdapter, type PiAdapter } from './piAdapter'
+import { stageClipboardFiles } from './clipboardFiles'
 import { TerminalApplication } from './application'
 import { createTerminalCommands } from './commands'
 import type { TerminalDecision } from './runtime'
@@ -62,6 +72,54 @@ function setup() {
 }
 
 describe('the owned terminal application', () => {
+  it('pastes staged Finder image paths and removes their temporary files on shutdown', async () => {
+    const { application, app, ui } = setup()
+    const paths = ['/Photos/portrait.heic', '/work/notes.md']
+    const pasteToEditor = vi.fn()
+    const shutdownOrder: string[] = []
+    const cleanup = vi.fn(async () => { shutdownOrder.push('clipboard files removed') })
+    const adapter = {
+      builtins: [], setTheme: vi.fn(), withBuiltInRenderers: vi.fn(),
+      readClipboardText: vi.fn(async () => null), readClipboardFilePaths: vi.fn(async () => paths),
+      readClipboardImage: vi.fn(async () => null), extensionForImageMimeType: vi.fn(() => null)
+    }
+    Object.assign(ui, { pasteToEditor })
+    vi.mocked(loadPiAdapter).mockResolvedValue(adapter as unknown as PiAdapter)
+    vi.mocked(stageClipboardFiles).mockResolvedValue({ paths: ['/tmp/prepared.png', paths[1]!], cleanup })
+    app.runtime.dispose.mockImplementation(async () => { shutdownOrder.push('runtime disposed') })
+
+    await (application as unknown as { pasteClipboard(): Promise<void> }).pasteClipboard()
+
+    expect(stageClipboardFiles).toHaveBeenCalledWith(paths)
+    expect(adapter.readClipboardImage).not.toHaveBeenCalled()
+    expect(pasteToEditor).toHaveBeenCalledWith(`/tmp/prepared.png\n${paths[1]}`)
+    await application.shutdown()
+    expect(cleanup).toHaveBeenCalledOnce()
+    expect(shutdownOrder).toEqual(['runtime disposed', 'clipboard files removed'])
+  })
+
+  it('leaves the prompt unchanged and reports an error when clipboard staging fails', async () => {
+    const { application, app, ui } = setup()
+    const message = 'Could not prepare HEIC image "portrait.heic" for the terminal.'
+    const adapter = {
+      builtins: [], setTheme: vi.fn(), withBuiltInRenderers: vi.fn(),
+      readClipboardText: vi.fn(async () => null), readClipboardFilePaths: vi.fn(async () => ['/Photos/portrait.heic']),
+      readClipboardImage: vi.fn(async () => null), extensionForImageMimeType: vi.fn(() => null)
+    }
+    const pasteToEditor = vi.fn()
+    const notice = vi.spyOn(app.transcript, 'notice')
+    Object.assign(ui, { pasteToEditor })
+    vi.mocked(loadPiAdapter).mockResolvedValue(adapter as unknown as PiAdapter)
+    vi.mocked(stageClipboardFiles).mockRejectedValueOnce(new Error(message))
+    const pasteClipboard = (application as unknown as { pasteClipboard(): Promise<void> }).pasteClipboard.bind(application)
+    ;(application as unknown as { attempt(action: () => Promise<void>): void }).attempt(() => pasteClipboard())
+
+    await vi.waitFor(() => expect(notice).toHaveBeenCalledWith(message, 'error'))
+
+    expect(pasteToEditor).not.toHaveBeenCalled()
+    await application.shutdown()
+  })
+
   it('shows a stable animated verb, then keeps completion status until the next turn', async () => {
     const { application, app } = setup()
     let now = 1000

package/src/terminal/tui/application.ts

@@ -24,6 +24,7 @@ import { createTerminalUi, type TerminalUi } from './ui'
 import { chooseWorkingVerb, createCompletionStatus, getWorkingSpinnerFrames, SPINNER_INTERVAL_MS, spinnerFrameAt } from './workingStatus'
 import { HarnessWelcome } from './welcome'
 import { answerTerminalQuestion } from './questions'
+import { stageClipboardFiles } from './clipboardFiles'
 import type { QuestionAnswer } from '../../sessions/registry'
 import { readHarnessLogSnapshot, type HarnessLogChunk, type HarnessLogInfo } from '../logs'
 import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../trajectory'
@@ -114,7 +115,7 @@ export class TerminalApplication {
   private failure?: Error
   private finish!: () => void
   private done = new Promise<void>(resolve => { this.finish = resolve })
-  private cleanup: (() => void)[] = []
+  private cleanup: (() => void | Promise<void>)[] = []
   private finalCleanup: (() => void)[] = []
   private draftSync = Promise.resolve()
   private lastInput = ''
@@ -648,7 +649,9 @@ export class TerminalApplication {
     const files = await adapter.readClipboardFilePaths()
     if (files?.length) {
       if (files.some(file => /[\x00-\x1f\x7f]/.test(file))) throw new Error('Clipboard file paths contain control characters.')
-      this.ui.pasteToEditor(files.join('\n'))
+      const staged = await stageClipboardFiles(files)
+      if (staged.cleanup) this.cleanup.push(staged.cleanup)
+      this.ui.pasteToEditor(staged.paths.join('\n'))
       return
     }
     const image = await adapter.readClipboardImage()
@@ -656,7 +659,7 @@ export class TerminalApplication {
       const directory = await mkdtemp(join(tmpdir(), 'harness-clipboard-'))
       const file = join(directory, `${randomUUID()}.${adapter.extensionForImageMimeType(image.mimeType) ?? 'png'}`)
       await writeFile(file, image.bytes, { mode: 0o600 })
-      this.cleanup.push(() => { void rm(directory, { recursive: true, force: true }) })
+      this.cleanup.push(() => rm(directory, { recursive: true, force: true }))
       this.ui.pasteToEditor(file)
       return
     }
@@ -689,12 +692,15 @@ export class TerminalApplication {
       this.stopped = true
       protect(() => this.pendingAbort?.abort())
       protect(() => this.ui?.dispose())
-      for (const cleanup of this.cleanup.splice(0)) protect(cleanup)
       // Captured while the runtime and its components still exist; written only after the alternate screen is left.
       const scrollback = this.exitScrollback()
       try { await this.runtime?.dispose() }
       catch (error) { this.failure ??= error instanceof Error ? error : new Error(String(error)) }
       finally {
+        for (const cleanup of this.cleanup.splice(0)) {
+          try { await cleanup() }
+          catch (error) { this.failure ??= error instanceof Error ? error : new Error(String(error)) }
+        }
         await this.terminal.drainInput(200, 30).catch(() => {})
         protect(() => this.tui.stop())
         if (scrollback) protect(() => writeScrollback(this.terminal, scrollback))

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

@@ -0,0 +1,94 @@
+import { execFile } from 'node:child_process'
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { promisify } from 'node:util'
+import { describe, expect, it, vi } from 'vitest'
+import { stageClipboardFiles } from './clipboardFiles'
+
+const exec = promisify(execFile)
+const pngSignature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+async function createRoot() {
+  const root = await mkdtemp(join(tmpdir(), 'harness-heic-test-'))
+  return root
+}
+
+describe('clipboard image files', () => {
+  it('converts HEIC and HEIF paths to private PNGs while preserving order and other paths', async () => {
+    const root = await createRoot()
+    const convert = vi.fn(async (_source: string, output: string) => { await writeFile(output, pngSignature) })
+    const staged = await stageClipboardFiles([
+      '/Photos/first photo.HEIC',
+      '/work/notes.md',
+      '/Photos/second.heif'
+    ], { platform: 'darwin', tempRoot: root, convert })
+
+    expect(staged.paths).toHaveLength(3)
+    expect(staged.paths[0]).toMatch(/\.png$/)
+    expect(staged.paths[1]).toBe('/work/notes.md')
+    expect(staged.paths[2]).toMatch(/\.png$/)
+    expect(convert.mock.calls.map(([source]) => source)).toEqual(['/Photos/first photo.HEIC', '/Photos/second.heif'])
+    expect(await readFile(staged.paths[0])).toEqual(pngSignature)
+    expect(await readFile(staged.paths[2])).toEqual(pngSignature)
+
+    await staged.cleanup?.()
+    await expect(readdir(dirname(staged.paths[0]))).rejects.toThrow()
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it('leaves clipboard paths unchanged on non-macOS platforms', async () => {
+    const convert = vi.fn(async () => {})
+    const paths = ['/Photos/portrait.heic', '/work/notes.md']
+
+    const staged = await stageClipboardFiles(paths, { platform: 'linux', convert })
+
+    expect(staged.paths).toEqual(paths)
+    expect(staged.cleanup).toBeUndefined()
+    expect(convert).not.toHaveBeenCalled()
+  })
+
+  it('cleans staged files and rejects the whole paste if conversion fails', async () => {
+    const root = await createRoot()
+    const convert = vi.fn(async (source: string, output: string) => {
+      if (source.endsWith('broken.heic')) throw new Error('decode failed')
+      await writeFile(output, pngSignature)
+    })
+
+    await expect(stageClipboardFiles([
+      '/Photos/valid.heic',
+      '/Photos/broken.heic'
+    ], { platform: 'darwin', tempRoot: root, convert })).rejects.toThrow('Could not prepare HEIC image "broken.heic" for the terminal.')
+    expect(await readdir(root)).toEqual([])
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it('rejects an empty or non-PNG conversion result', async () => {
+    const root = await createRoot()
+    await expect(stageClipboardFiles(['/Photos/invalid.heic'], {
+      platform: 'darwin',
+      tempRoot: root,
+      convert: async (_source, output) => { await writeFile(output, 'not a PNG') }
+    })).rejects.toThrow('Could not prepare HEIC image "invalid.heic" for the terminal.')
+    expect(await readdir(root)).toEqual([])
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it.skipIf(process.platform !== 'darwin')('converts a real HEIC file with macOS sips without changing the original', async () => {
+    const root = await createRoot()
+    const sourcePng = join(root, 'pixel.png')
+    const sourceHeic = join(root, 'portrait.heic')
+    await writeFile(sourcePng, Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64'))
+    await exec('/usr/bin/sips', ['-s', 'format', 'heic', sourcePng, '--out', sourceHeic])
+    const original = await readFile(sourceHeic)
+
+    const staged = await stageClipboardFiles([sourceHeic], { tempRoot: root })
+    expect(staged.paths[0]).not.toBe(sourceHeic)
+    expect((await readFile(staged.paths[0]!)).subarray(0, 8)).toEqual(pngSignature)
+    expect(await readFile(sourceHeic)).toEqual(original)
+
+    await staged.cleanup?.()
+    expect((await readdir(root)).sort()).toEqual(['pixel.png', 'portrait.heic'])
+    await rm(root, { recursive: true, force: true })
+  })
+})

package/src/terminal/tui/clipboardFiles.ts

@@ -0,0 +1,86 @@
+import { execFile } from 'node:child_process'
+import { chmod, mkdtemp, open, rm, stat } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { promisify } from 'node:util'
+
+const exec = promisify(execFile)
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+export interface ClipboardFileOptions {
+  platform?: NodeJS.Platform
+  tempRoot?: string
+  convert?: (source: string, output: string) => Promise<void>
+}
+
+export interface StagedClipboardFiles {
+  paths: string[]
+  cleanup?: () => Promise<void>
+}
+
+function isHeicPath(path: string): boolean {
+  return /\.hei[cf]$/i.test(path)
+}
+
+async function convertWithSips(source: string, output: string): Promise<void> {
+  await exec('/usr/bin/sips', ['-s', 'format', 'png', source, '--out', output], {
+    timeout: 30_000,
+    maxBuffer: 1024 * 1024
+  })
+}
+
+async function assertPng(path: string): Promise<void> {
+  const info = await stat(path)
+  if (!info.isFile() || info.size < PNG_SIGNATURE.length) throw new Error('Conversion did not create an image.')
+
+  const file = await open(path, 'r')
+  try {
+    const signature = Buffer.alloc(PNG_SIGNATURE.length)
+    const { bytesRead } = await file.read(signature, 0, signature.length, 0)
+    if (bytesRead !== PNG_SIGNATURE.length || !signature.equals(PNG_SIGNATURE)) throw new Error('Conversion did not create a PNG image.')
+  } finally {
+    await file.close()
+  }
+}
+
+/** Convert Finder-copied HEIC/HEIF paths to images that Pi's terminal reader can consume. */
+export async function stageClipboardFiles(paths: string[], options: ClipboardFileOptions = {}): Promise<StagedClipboardFiles> {
+  const platform = options.platform ?? process.platform
+  if (platform !== 'darwin' || !paths.some(isHeicPath)) return { paths }
+
+  let directory: string | undefined
+  try {
+    directory = await mkdtemp(join(options.tempRoot ?? tmpdir(), 'harness-clipboard-'))
+    const stagedPaths: string[] = []
+    for (const [index, path] of paths.entries()) {
+      if (!isHeicPath(path)) {
+        stagedPaths.push(path)
+        continue
+      }
+
+      const output = join(directory, `${index}-${randomUUID()}.png`)
+      try {
+        await (options.convert ?? convertWithSips)(path, output)
+        await chmod(output, 0o600)
+        await assertPng(output)
+      } catch {
+        throw new Error(`Could not prepare HEIC image "${basename(path)}" for the terminal.`)
+      }
+      stagedPaths.push(output)
+    }
+
+    let cleaned = false
+    return {
+      paths: stagedPaths,
+      cleanup: async () => {
+        if (cleaned || !directory) return
+        cleaned = true
+        await rm(directory, { recursive: true, force: true })
+      }
+    }
+  } catch (error) {
+    if (directory) await rm(directory, { recursive: true, force: true }).catch(() => {})
+    throw error
+  }
+}

package/src/terminal/tui/piAdapter.ts

@@ -1,10 +1,12 @@
 // Pi 1.2.0 omits CLI builtins, rich builtin renderers, clipboard reads and the global theme setter
 // from its public exports. Keep those version-sensitive presentation hooks here; session/runtime
 // work uses public APIs. Clipboard helpers are only called for an explicit user paste.
-import { getPackageDir, VERSION, type InlineExtension, type Theme, type ToolRenderers } from '@earendil-works/pi-coding-agent'
+import type { InlineExtension, Theme, ToolRenderers } from '@earendil-works/pi-coding-agent'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
+import { loadPi, PINNED_PI_VERSION } from '../../pi/runtime'
+
 export interface PiAdapter {
   builtins: InlineExtension[]
   setTheme(theme: Theme): void
@@ -19,13 +21,14 @@ let adapter: PiAdapter | undefined
 let loading: Promise<PiAdapter> | undefined
 
 export function assertPiAdapterVersion(version: string): void {
-  if (version !== '1.2.0') throw new Error(`The Harness terminal adapter requires Pi 1.2.0; found ${version}. Install the Harness package's pinned dependencies.`)
+  if (version !== PINNED_PI_VERSION) throw new Error(`The Harness terminal adapter requires Pi ${PINNED_PI_VERSION}; found ${version}. Install the Harness package's pinned dependencies.`)
 }
 
 export function loadPiAdapter(): Promise<PiAdapter> {
   loading ??= (async () => {
-    assertPiAdapterVersion(VERSION)
-    const root = getPackageDir()
+    const pi = await loadPi()
+    assertPiAdapterVersion(pi.VERSION)
+    const root = pi.getPackageDir()
     const [extensions, theme, renderers, clipboard, images] = await Promise.all([
       import(pathToFileURL(join(root, 'dist/extensions/index.js')).href),
       import(pathToFileURL(join(root, 'dist/modes/interactive/theme/theme.js')).href),

package/src/terminal/tui/runtime.ts

@@ -11,6 +11,7 @@ import terminalExtension, { type TerminalPlanRunState } from '../piExtension'
 import { planModeTools } from './planMode'
 import { claimTerminalControl, controlCall } from '../control'
 import { loadPiAdapter } from './piAdapter'
+import { loadPi } from '../../pi/runtime'
 import type { SessionAccount } from '../accountsMenu'
 import type { QuestionAnswer } from '../../sessions/registry'
 import type { TerminalQuestion } from './questions'
@@ -174,6 +175,7 @@ export async function createTerminalRuntime(args: string[], host: TerminalRuntim
     assertTerminalSessionScope(resume, cwd)
   }
 
+  await loadPi()
   // 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)