@xingular/harness 2.1.1 → 3.0.0

package/src/terminal/cli.ts

@@ -1,6 +1,6 @@
-// `xagent-wiki` and `xagent-mcp`: the harness's memory, Wiki, and connected apps as commands,
-// for a `pi` terminal session's shell. Each command maps onto one call to the session socket.
-import type { WikiCall } from '../tools/definitions'
+// `xagent-wiki` and `xagent-mcp`: the harness's notes, skills, history and connected apps as
+// commands, for a `pi` terminal session's shell. Each command maps onto one call to the session socket.
+import type { HarnessCall } from '../tools/definitions'
 import { connectionFromEnv, socketCall } from './client'
 
 export const WIKI_COMMAND = 'xagent-wiki'
@@ -8,22 +8,14 @@ export const APPS_COMMAND = 'xagent-mcp'
 
 export const USAGE = `Usage: ${WIKI_COMMAND} <command> [arguments]
 
-  entrypoint                         Your context pack: memory blocks, rules, skills, project map
-  search <query> [--kind K] [--namespace NS]
-                                     Search every namespace (K: page, fact, skill, rule, prompt)
-  read <id or path>                  Read one page, fact, skill, rule, or prompt
-  list [namespace] [--kind K]        List namespaces and pages, or all entries of a kind
-  skill [name]                       Load a skill, or list skills
-  facts [query] [--namespace NS]     Recall facts (also: memory)
+  search <query> [--project SLUG]    Search the Wiki's project notes
+  read <path>                        Read one note, e.g. projects/<slug>/decisions
+  list [project slug | library]      List notes
+  write <path> <text | ->            Save a note (when this session may write the Wiki)
+  skill [name]                       Load one of your skills, or list them
   history <query> [--scope all] [--since YYYY-MM-DD]
                                      Search earlier conversations and runs (also: recall)
   history-read <run id>              Read one earlier run (also: recall-read)
-  block append <label> <text>        Add to a memory block (user, project, or a shared block)
-  block replace <label> --old <text> --new <text>
-                                     Replace one exact passage in a memory block
-  block rethink <label> <text>       Rewrite a whole memory block
-  propose <json | ->                 Record knowledge, e.g. {"kind":"fact","title":"…","body":"…",
-                                     "type":"preference","sourceRefs":[{"kind":"run","ref":"current"}]}
 `
 
 export const APPS_USAGE = `Usage: ${APPS_COMMAND} <command>
@@ -33,15 +25,15 @@ export const APPS_USAGE = `Usage: ${APPS_COMMAND} <command>
                                      Use one of them
 `
 
-export type CliCommand = { kind: 'call'; call: WikiCall; params: Record<string, unknown> } | { kind: 'help' } | { kind: 'stdin-propose' }
+export type CliCommand = { kind: 'call'; call: HarnessCall; params: Record<string, unknown> } | { kind: 'help' } | { kind: 'stdin-write'; path: string }
 
 function options(args: string[]): { positional: string[]; flags: Record<string, string> } {
   const positional: string[] = []
   const flags: Record<string, string> = {}
   for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]
+    const arg = args[index]!
     if (arg.startsWith('--') && index + 1 < args.length) {
-      flags[arg.slice(2)] = args[index + 1]
+      flags[arg.slice(2)] = args[index + 1]!
       index += 1
     } else {
       positional.push(arg)
@@ -55,21 +47,23 @@ export function parseCli(argv: string[]): CliCommand {
   const { positional, flags } = options(rest)
   const joined = positional.join(' ').trim()
   switch (command) {
-    case 'entrypoint':
-      return { kind: 'call', call: 'wiki.entrypoint', params: {} }
     case 'search':
       if (!joined) return { kind: 'help' }
-      return { kind: 'call', call: 'wiki.search', params: { query: joined, ...(flags.kind ? { kinds: [flags.kind] } : {}), ...(flags.namespace ? { namespace: flags.namespace } : {}) } }
+      return { kind: 'call', call: 'wiki.search', params: { query: joined, ...(flags.project ? { project: flags.project } : {}) } }
     case 'read':
       if (!joined) return { kind: 'help' }
-      return { kind: 'call', call: 'wiki.read', params: { id: joined } }
+      return { kind: 'call', call: 'wiki.read', params: { path: joined } }
     case 'list':
-      return { kind: 'call', call: 'wiki.list', params: { ...(joined ? { namespace: joined } : {}), ...(flags.kind ? { kind: flags.kind } : {}) } }
+      return { kind: 'call', call: 'wiki.list', params: joined ? { project: joined } : {} }
+    case 'write': {
+      const [path, ...words] = positional
+      if (!path) return { kind: 'help' }
+      if (words.join(' ').trim() === '-') return { kind: 'stdin-write', path }
+      if (!words.length) return { kind: 'help' }
+      return { kind: 'call', call: 'wiki.write', params: { path, text: words.join(' ') } }
+    }
     case 'skill':
-      return { kind: 'call', call: 'wiki.skill', params: joined ? { name: joined } : {} }
-    case 'facts':
-    case 'memory':
-      return { kind: 'call', call: 'wiki.memory', params: { ...(joined ? { query: joined } : {}), ...(flags.namespace ? { namespace: flags.namespace } : {}) } }
+      return { kind: 'call', call: 'skill.load', params: joined ? { name: joined } : {} }
     case 'history':
     case 'recall':
       if (!joined) return { kind: 'help' }
@@ -78,24 +72,6 @@ export function parseCli(argv: string[]): CliCommand {
     case 'recall-read':
       if (!joined) return { kind: 'help' }
       return { kind: 'call', call: 'recall.read', params: { run: joined } }
-    case 'block': {
-      const [action, label, ...words] = positional
-      const body = words.join(' ').trim()
-      if (action === 'append' && label && body) return { kind: 'call', call: 'memory.append', params: { block: label, text: body } }
-      if (action === 'rethink' && label && body) return { kind: 'call', call: 'memory.rethink', params: { block: label, body } }
-      if (action === 'replace' && label && flags.old !== undefined && flags.new !== undefined) return { kind: 'call', call: 'memory.replace', params: { block: label, old: flags.old, new: flags.new } }
-      return { kind: 'help' }
-    }
-    case 'propose': {
-      if (joined === '-') return { kind: 'stdin-propose' }
-      try {
-        const params = JSON.parse(joined) as unknown
-        if (params && typeof params === 'object' && !Array.isArray(params)) return { kind: 'call', call: 'wiki.propose', params: params as Record<string, unknown> }
-      } catch {
-        // Falls through to help.
-      }
-      return { kind: 'help' }
-    }
     default:
       return { kind: 'help' }
   }
@@ -119,8 +95,8 @@ export async function runWikiCli(argv: string[]): Promise<number> {
   try {
     const connection = connectionFromEnv()
     const result =
-      command.kind === 'stdin-propose'
-        ? await socketCall<string>(connection, 'wiki.propose', JSON.parse(await readStdin()) as Record<string, unknown>)
+      command.kind === 'stdin-write'
+        ? await socketCall<string>(connection, 'wiki.write', { path: command.path, text: await readStdin() })
         : await socketCall<string>(connection, command.call, command.params)
     process.stdout.write(`${typeof result === 'string' ? result : JSON.stringify(result)}\n`)
     return 0

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

@@ -51,7 +51,7 @@ describe('terminal bridge lifecycle', () => {
     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 read-only') })
+    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)
   })
 

package/src/terminal/piExtension.ts

@@ -235,7 +235,7 @@ export default async function (pi: ExtensionAPI, planRun?: TerminalPlanRunState)
   })
   pi.on('tool_call', async (event) => {
     if (planRun?.active && !planRun.allowedTools.has(event.toolName)) {
-      const reason = planRefusal(event.toolName, new Set()) ?? `Plan mode is read-only: ${event.toolName} is not available in this session.`
+      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 {
@@ -294,10 +294,10 @@ export default async function (pi: ExtensionAPI, planRun?: TerminalPlanRunState)
   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/pluginControl.test.ts

@@ -80,21 +80,20 @@ describe('plugin control from a terminal session', () => {
     const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
     const call = <T>(method: string, params?: Record<string, unknown>) => socketCall<T>(connection, method, params ?? {}, 5_000, key)
     const rows = menuRows(await call<Plugin[]>('plugins.list'), 'p1')
-    expect(rows.map((row) => row.label)).toEqual(['● review-kit · code not trusted', '○ Run tests · instruction in Yours', '○ Budget guard · runs code', '○ Output trim · runs code'])
+    expect(rows.map((row) => row.label)).toEqual(['● review-kit · code not trusted', '○ Budget guard · runs code', '○ Output trim · runs code'])
     expect(rowActions(rows[0], 'p1')).toEqual(['Switch off for this project', 'Switch off everywhere', 'Trust its code', 'Back'])
     expect(rowActions(rows[1], null)).toEqual(['Switch on everywhere', 'Back'])
     // A part that ships with the harness needs no trust: it is the harness's own code.
-    expect(rowActions(rows[2], 'p1')).toEqual(['Switch on for this project', 'Switch on everywhere', 'Back'])
+    expect(rowActions(rows[1], 'p1')).toEqual(['Switch on for this project', 'Switch on everywhere', 'Back'])
 
-    // Declining the trust question leaves the code untrusted; then they trust it, switch a rule on, and leave.
-    const { ui, shown, said } = person(['● review-kit · code not trusted', 'Trust its code', false, '● review-kit · code not trusted', 'Trust its code', true, '○ Run tests · instruction in Yours', 'Switch on for this project', 'Done'])
+    // Declining the trust question leaves the code untrusted; then they trust it and leave.
+    const { ui, shown, said } = person(['● review-kit · code not trusted', 'Trust its code', false, '● review-kit · code not trusted', 'Trust its code', true, 'Done'])
     await runPluginsMenu(ui, call, 'p1')
     expect(shown.find((line) => line.startsWith('Trust this code?'))).toContain('extensions/guard.ts')
     expect(shown.find((line) => line.startsWith('Trust this code?'))).toContain('can do anything this app can')
     expect(said).toEqual(['Saved. It applies when this session restarts.'])
     const after = await call<Plugin[]>('plugins.list')
     expect(after.find((plugin) => plugin.id === 'package:review-kit')).toMatchObject({ trust: 'trusted' })
-    expect(after.flatMap((plugin) => plugin.contributions).find((entry) => entry.id === 'yours/rules/tests')).toMatchObject({ state: 'on', scope: 'App' })
     expect(harness.plugins.trust.list()).toHaveLength(1)
 
     // Leaving at once changes nothing and says nothing.
@@ -113,7 +112,7 @@ describe('the plugins command', () => {
     const last = (): string => lines.at(-1) ?? ''
 
     expect(await run(['list'])).toBe(0)
-    expect(last()).toMatch(/^memory\s+required\s+Memory$/m)
+    expect(last()).toMatch(/^harness\s+required\s+Harness$/m)
     expect(await run(['install', join(base, 'kit')])).toBe(0)
     expect(last()).toContain('Installed, switched off.')
     expect(last()).toContain('trust its code with "plugins trust <id>"')
@@ -134,8 +133,8 @@ describe('the plugins command', () => {
     expect(last()).toContain('Code (trusted)')
     expect(last()).toContain('● skill audit (package:review-kit/skill/audit)')
 
-    expect(await run(['detach', 'memory'])).toBe(1)
-    expect(last()).toContain('Memory cannot be switched off.')
+    expect(await run(['detach', 'harness'])).toBe(1)
+    expect(last()).toContain('Harness cannot be switched off.')
     expect(await run(['untrust', 'package:review-kit'])).toBe(0)
     expect(await run(['remove', 'package:review-kit'])).toBe(0)
     expect(await run(['show', 'package:review-kit'])).toBe(1)

package/src/terminal/socket.ts

@@ -13,7 +13,7 @@ import { log } from '../core/bus'
 import { HarnessError, toErrorShape } from '../core/errors'
 import { newId } from '../core/fs'
 import type { BrokerSession } from '../mcp/service'
-import type { CallerContext } from '../memory/caller'
+import type { CallerContext } from '../core/caller'
 
 /** What a token stands for. */
 export interface SocketGrant {
@@ -27,7 +27,7 @@ export interface SocketGrant {
 }
 
 export interface SocketHandlers {
-  /** `wiki.*`, `memory.*`, `recall.*`. */
+  /** `wiki.*`, `skill.*`, `recall.*`, `trajectory.*`. */
   memory(caller: CallerContext, call: string, params: Record<string, unknown>): string
   /** `mcp.list`, `mcp.call`, `mcp.revision`, `tools.list`, `tools.call`. */
   apps(session: BrokerSession, call: string, params: Record<string, unknown>): Promise<unknown>
@@ -147,7 +147,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 (['wiki.', 'skill.', 'recall.', 'trajectory.'].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.')

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 () => {
@@ -106,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 = [
@@ -125,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')
     ]
@@ -190,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', {})
@@ -388,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')
@@ -428,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' })
   })
 })
 
@@ -467,6 +450,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

@@ -24,25 +24,27 @@ 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'
 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. */
@@ -86,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. */
@@ -111,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
@@ -143,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. */
@@ -166,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)
@@ -512,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)
 
@@ -543,6 +553,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()
@@ -573,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.
@@ -615,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