@xingular/harness 2.1.1 → 3.0.0

package/src/harness.ts

@@ -1,6 +1,7 @@
-// The harness, assembled: Pi sessions on isolated accounts, a compiled prompt, a memory
-// lifecycle, tools, connected apps, and skills. An application embeds one of these and adds
-// its own prompt sections, tools, and policy; nothing here knows what that application is.
+// The harness, assembled: Pi sessions on isolated accounts, versioned harness trees that shape
+// them, refinement that improves those trees from evidence, a compiled prompt, project notes,
+// tools, and connected apps. An application embeds one of these and adds its own prompt
+// sections, tools, and policy; nothing here knows what that application is.
 import { Subagents } from './sessions/subagentService'
 import { mkdirSync } from 'node:fs'
 import { join } from 'node:path'
@@ -15,18 +16,15 @@ import { DEFAULT_PRODUCT_NAME, EMPTY_DIRECTORY, type Directory, type HarnessEnv
 import { HarnessError } from './core/errors'
 import { readJsonOr } from './core/fs'
 import { closeIndex } from './core/index'
-import { projectsOrNone } from './core/projects'
 import { ConnectedApps } from './mcp/service'
 import type { AppOAuthClients } from './mcp/types'
 import { migrateConnectionScopes } from './mcp/scopeMigration'
-import type { MaintainerFactory } from './memory/maintainer'
-import { Maintenance } from './memory/maintenance'
-import * as migrate from './memory/migrate'
-import { writeIndex } from './memory/proposals'
-import * as recall from './memory/recall'
-import * as store from './memory/store'
-import { countPages } from './memory/wiki'
-import * as wikiIndex from './memory/wikiIndex'
+import * as recall from './history/recall'
+import type { RefineHost } from './refine/host'
+import { Refinements } from './refine/service'
+import { configureBuiltins } from './tree/components'
+import { TreeTrust } from './tree/trust'
+import * as notes from './wiki/notes'
 import * as pluginApi from './plugins/api'
 import * as attachments from './plugins/attachments'
 import { HARNESS_PLUGINS } from './plugins/builtin'
@@ -40,7 +38,6 @@ import { RunRegistry } from './sessions/registry'
 import { markInterruptedRuns } from './sessions/runStore'
 import type { SessionFactory } from './sessions/runner'
 import { Sessions } from './sessions/sessions'
-import * as registry from './skills/registry'
 import { Terminals, type TerminalAssets } from './terminal/terminals'
 
 export interface HarnessOptions {
@@ -57,19 +54,13 @@ export interface HarnessOptions {
   policy?: ToolPolicy
   /** Replaces Pi, for tests. */
   sessionFactory?: SessionFactory
-  maintainerFactory?: MaintainerFactory
-  /** Delegate maintenance execution to the embedding host through durable requests. */
-  externalMaintenance?: boolean
-  maintenanceExcludedTriggers?: string[]
-  /** Queue consolidation after every settled run (the default). False leaves memory to explicit proposals and scheduled merges. */
-  maintenanceRunTrigger?: boolean
-  /** How long the maintenance queue stays empty before full memory blocks are condensed. */
-  idleMs?: number
+  /** Where refinement executions work and with what; without it, a temporary copy of the task's source and Pi's own tools. */
+  refineHost?: RefineHost
   /** Where the built commands a terminal session runs are, when they are not beside this package. */
   assets?: TerminalAssets
   /** Optional legacy executable override. The default is the Harness-owned terminal frontend. */
   piProgram?: () => string | null
-  /** Folders of built-in skills, prompts, and rules, each laid out like `registry/`. */
+  /** Folders of built-in skills, prompts, and rules for the component library, each laid out like `registry/`. */
   builtins?: string[]
   /**
    * The application's own parts, described as plugins: which tools, prompt sections and tool
@@ -90,7 +81,10 @@ export interface HarnessOptions {
 /** What starting on a data root found and repaired. */
 export interface Recovery {
   interruptedRuns: number
+  /** Notes in the Wiki. */
   reindexedPages: number
+  /** Where an earlier Wiki's memory, facts and revisions were moved, when they were. */
+  legacyWiki?: string | null
   /** Set when the storage migration failed; the old data is left as it was. */
   migrationError: string | null
 }
@@ -133,7 +127,11 @@ export class Harness {
   applicationPlugins: ReadonlySet<string> = new Set()
   readonly subagents: Subagents
   readonly sessions: Sessions
-  readonly maintenance: Maintenance
+  /** Which plugin code in harness trees a person trusted. */
+  readonly trust: TreeTrust
+  /** Refinement: improving a harness tree from evidence of how it ran. */
+  readonly refine: Refinements
+  refineHost: RefineHost | null
   readonly terminals: Terminals
   /** Resolves when what was loaded in the background at construction is in place. */
   readonly ready: Promise<void>
@@ -147,7 +145,9 @@ export class Harness {
     this.env = new Env(options.dataRoot || null, options.directory ?? EMPTY_DIRECTORY, options.productName ?? DEFAULT_PRODUCT_NAME, this.bus)
     this.hub = new Hub(this, options.hub)
     this.policy = options.policy ?? {}
-    registry.configureBuiltins(options.builtins ?? [])
+    configureBuiltins(options.builtins ?? [])
+    this.trust = new TreeTrust(this.stateDir)
+    this.refineHost = options.refineHost ?? null
     const secrets = options.secrets ?? fileSecretStore(join(this.stateDir, 'secrets.json'))
     this.accounts = new Accounts({ dir: join(this.stateDir, 'accounts'), secrets, bus: this.bus })
     this.approvals = new Approvals(this.stateDir, this.bus)
@@ -200,10 +200,11 @@ export class Harness {
       broker: this.apps,
       plugins: this.plugins,
       resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }),
-      factory: options.sessionFactory
+      factory: options.sessionFactory,
+      trust: this.trust
     })
-    this.maintenance = new Maintenance({ env: this.env, bus: this.bus, accounts: this.accounts, factory: options.maintainerFactory, idleMs: options.idleMs, external: options.externalMaintenance, excludedTriggers: options.maintenanceExcludedTriggers, runTrigger: options.maintenanceRunTrigger })
-    this.terminals = new Terminals({ subagents: this.subagents, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope) }, assets: options.assets, program: options.piProgram, hub: this.hub })
+    this.refine = new Refinements({ root: () => this.env.root, bus: this.bus, trust: this.trust, host: () => this.refineHost, runtime: { root: () => this.env.root, runs: this.runs, run: (input) => this.sessions.run(input) } })
+    this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope) }, assets: options.assets, program: options.piProgram, hub: this.hub })
     this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)))
     this.runs.listen((event, run) => {
       this.accounts.onRunEvent(event, run)
@@ -212,8 +213,6 @@ export class Harness {
       if ((event.type === 'completed' || event.type === 'failed') && run) {
         this.hooks.emit({ type: 'history.run.ended', runId: run.id, sessionId: run.sessionId, status: run.status, goal: run.goal ?? null, agentId: run.agentId ?? null, projectId: run.projectId ?? null, startedAt: run.startedAt, endedAt: run.endedAt ?? null, at: event.timestamp })
       }
-      if (event.type === 'completed' || event.type === 'failed' || (event.type === 'status.changed' && (event.payload as { status?: string }).status === 'interrupted')) this.maintenance.finishRun(event.runId, event.type !== 'completed')
-      this.maintenance.onRunEvent(event)
     })
   }
 
@@ -230,27 +229,28 @@ export class Harness {
   }
 
   /**
-   * Opens a data root: brings its Wiki to the current layout, settles runs that never ended,
-   * and refreshes the index. `agentIds` are the agents that get their own memory blocks when an
-   * older Wiki is migrated.
+   * Opens a data root: moves an earlier Wiki's memory and facts aside (once), lays out the Wiki,
+   * settles runs that never ended, and refreshes the history index. `agentIds` is accepted for
+   * hosts written against earlier versions and is not used.
    */
-  open(dataRoot: string, agentIds: readonly string[] = []): Recovery {
+  open(dataRoot: string, _agentIds: readonly string[] = []): Recovery {
     if (this.hub.busy && this.env.dataRoot !== dataRoot) throw new HarnessError('hub_busy', 'Wait for the hub installation before changing the data location.')
     if (this.env.dataRoot && this.env.dataRoot !== dataRoot) closeIndex(this.env.dataRoot)
     this.env.dataRoot = dataRoot
     this.hub.watch(dataRoot)
     const root = dataRoot
-    this.hooks.watch(store.wikiDir(root))
+    this.hooks.watch(notes.wikiDir(root))
     void this.hooks.reload()
-    for (const folder of ['registry/skills', 'registry/prompts', 'registry/rules', 'config', 'runs']) mkdirSync(join(root, folder), { recursive: true })
+    for (const folder of ['registry/skills', 'registry/prompts', 'registry/rules', 'config', 'runs', 'harnesses']) mkdirSync(join(root, folder), { recursive: true })
     let migrationError: string | null = null
-    let wikiMigrationError: string | null = null
+    let legacyWiki: string | null = null
     try {
-      if (migrate.run(this.env, agentIds)) log(`started Wiki storage version ${migrate.WIKI_VERSION}; the earlier Wiki is kept as a backup in the data root`)
+      legacyWiki = notes.moveLegacy(root)
+      if (legacyWiki) log(`moved the earlier Wiki's memory, facts and revisions to ${legacyWiki}`)
+      notes.ensureLayout(root, this.env.productName)
     } catch (error) {
       migrationError = error instanceof Error ? error.message : String(error)
-      wikiMigrationError = migrationError
-      log('Wiki migration failed', migrationError)
+      log('Wiki layout', migrationError)
     }
     try {
       migrateConnectionScopes(root, this.stateDir)
@@ -259,55 +259,36 @@ export class Harness {
       migrationError = migrationError ? `${migrationError}; connector scope migration: ${detail}` : detail
       log('connector scope migration failed', detail)
     }
-    if (!wikiMigrationError) {
-      try {
-        store.ensureLayout(root, this.env.productName)
-        // Every project has its fixed pages, and the generated indexes match the files.
-        for (const project of projectsOrNone(root)) store.ensureProjectNamespace(root, project.slug, project.name)
-        writeIndex(store.wikiDir(root))
-      } catch (error) {
-        log('Wiki layout', error instanceof Error ? error.message : String(error))
-      }
-    }
     let interruptedRuns = 0
     try {
       interruptedRuns = markInterruptedRuns(root, `${this.env.productName} stopped before the run settled.`)
     } catch (error) {
       log('run recovery', error instanceof Error ? error.message : String(error))
     }
-    let reindexedPages: number
-    try {
-      reindexedPages = wikiIndex.ensure(root)
-    } catch (error) {
-      log('index', error instanceof Error ? error.message : String(error))
-      reindexedPages = countPages(root)
-    }
     try {
-      // Runs recorded while nothing was running, or before recall existed, become searchable.
+      // Runs recorded while nothing was running become searchable.
       recall.sync(root)
     } catch (error) {
       log('recall', error instanceof Error ? error.message : String(error))
     }
-    this.recovery = { interruptedRuns, reindexedPages, migrationError }
-    this.maintenance.start()
+    this.recovery = { interruptedRuns, reindexedPages: safeCount(root), migrationError, legacyWiki }
     return this.recovery
   }
 
-  /** Deletes the index and rebuilds it from the files. Returns the pages indexed. */
+  /** Rebuilds the history index from the run records. Returns the notes in the Wiki. */
   rebuildIndex(): number {
-    const pages = wikiIndex.rebuild(this.env.root)
     recall.sync(this.env.root)
-    this.recovery = { ...this.recovery, reindexedPages: pages }
-    return pages
+    const count = safeCount(this.env.root)
+    this.recovery = { ...this.recovery, reindexedPages: count }
+    return count
   }
 
-  /** Stops live runs and releases the index. */
+  /** Stops live runs and refinements and releases the index. */
   async close(): Promise<void> {
     this.hub.close()
-    this.maintenance.stop()
+    await this.refine.close()
     await this.terminals.close()
     await this.runs.interruptAll()
-    await this.maintenance.settled()
     await this.hooks.settled().catch(() => undefined)
     this.hooks.close()
     await this.apps.close()
@@ -315,6 +296,14 @@ export class Harness {
   }
 }
 
+function safeCount(root: string): number {
+  try {
+    return notes.paths(root).length
+  } catch {
+    return 0
+  }
+}
+
 export function createHarness(options: HarnessOptions): Harness {
   const harness = new Harness(options)
   if (options.dataRoot) harness.open(options.dataRoot)

package/src/{memory → history}/recall.test.ts

@@ -9,7 +9,7 @@ import { newId, writeJson } from '../core/fs'
 import { closeIndex } from '../core/index'
 import { runRecordSchema, type RunRecord } from '../sessions/contracts'
 import { parseEvent } from '../sessions/runStore'
-import type { CallerContext } from './caller'
+import type { CallerContext } from '../core/caller'
 import { passages, read, readTool, search, searchTool, sync } from './recall'
 
 const run = (id: string, mode: string, session: string, project: string | null, goal: string): RunRecord =>

package/src/{memory → history}/recall.ts

@@ -12,7 +12,7 @@ import { charCount, takeChars } from '../core/text'
 import type { RunEvent, RunRecord } from '../sessions/contracts'
 import { readAllRuns } from '../sessions/runIndex'
 import { findRun, readEvents } from '../sessions/runStore'
-import { isSession, projectOf, type CallerContext } from './caller'
+import { isSession, projectOf, type CallerContext } from '../core/caller'
 
 const PASSAGE_LIMIT = 6000
 const READ_LIMIT = 12_000

package/src/{memory → history}/trajectory.test.ts

@@ -8,9 +8,9 @@ import { closeIndex } from '../core/index'
 import { writeJson } from '../core/fs'
 import { runRecordSchema, type RunEvent, type RunRecord } from '../sessions/contracts'
 import { appendEvent, saveRun } from '../sessions/runStore'
-import { WIKI_AGENT_TOOLS } from '../tools/definitions'
-import type { CallerContext } from './caller'
-import { dispatch } from './dispatch'
+import { HARNESS_TOOLS } from '../tools/definitions'
+import type { CallerContext } from '../core/caller'
+import { dispatch } from '../tools/dispatch'
 import { readTool, searchTool } from './trajectory'
 
 const roots: string[] = []
@@ -170,7 +170,7 @@ test('trajectory calls reject malformed filters and missing current runs', () =>
 test('the model tool registry exposes both trajectory calls through Wiki dispatch', () => {
   const { root, env } = setup()
   save(root, run('registered-run'))
-  const calls = WIKI_AGENT_TOOLS.map((tool) => tool.call)
+  const calls = HARNESS_TOOLS.map((tool) => tool.call)
   expect(calls).toContain('trajectory.search')
   expect(calls).toContain('trajectory.read')
   expect(JSON.parse(dispatch(env, agent, 'trajectory.search', {})).runs[0].id).toBe('registered-run')

package/src/{memory → history}/trajectory.ts

@@ -8,7 +8,7 @@ import { scrubSensitive } from '../mcp/connections'
 import { isActiveStatus, runStatusSchema, type RunEvent, type RunRecord } from '../sessions/contracts'
 import { readAllRuns } from '../sessions/runIndex'
 import { findRun, snapshot } from '../sessions/runStore'
-import type { CallerContext } from './caller'
+import type { CallerContext } from '../core/caller'
 
 const SEARCH_DEFAULT = 10
 const SEARCH_MAX = 30

package/src/hub/hub.test.ts

@@ -6,7 +6,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Bus } from '../core/bus'
 import { Harness } from '../harness'
 import { memorySecretStore } from '../accounts/secrets'
-import * as registry from '../skills/registry'
+import * as registry from '../tree/components'
 import { Hub } from './hub'
 import { hubCatalogSchema, hubEntrySchema, type HubEntry } from './schema'
 import { runHubMenu } from '../terminal/hubMenu'
@@ -47,7 +47,7 @@ describe('Hub installation', () => {
     const { hub, root } = fixture([entry('registry', skill())])
     const receipt = await hub.install('example/review', '1.0.0')
     expect(receipt.resourceIds).toEqual(['skills/review'])
-    expect(registry.enabledFor(root, null)).toEqual([])
+    expect(registry.list(root).map((item) => item.id)).toContain('skills/review')
     const content = readFileSync(join(root, 'registry', 'skills', 'review', 'SKILL.md'), 'utf8')
     const collision = { ...entry('registry', skill()), id: 'other/review' }
     const another = new Hub(({ dataRoot: root, env: { root }, stateDir: join(root, 'state'), bus: new Bus() }) as Harness, { catalog: { schemaVersion: 1, entries: [collision] } })
@@ -67,7 +67,7 @@ describe('Hub installation', () => {
       const { hub, root } = fixture([item])
       await hub.install(item.id, item.version)
       expect(readFileSync(join(root, 'registry', kind, 'review.md'), 'utf8')).toContain('Read evidence')
-      expect(registry.enabledFor(root, null)).toEqual([])
+      expect(registry.list(root).map((entry) => entry.id)).toContain(`${kind}/review`)
     }
   })
   it('does not commit a download with the wrong digest', async () => {
@@ -140,12 +140,11 @@ describe('Hub installation', () => {
   it('can reinstall deleted resources and clears stale attachment grants', async () => {
     const { hub, root } = fixture([entry('registry', skill())])
     await hub.install('example/review', '1.0.0')
-    registry.setEnabled(root, null, ['skills/review'])
     rmSync(join(root, 'registry', 'skills', 'review'), { recursive: true })
     expect((await hub.list()).installed[0]).toMatchObject({ state: 'incomplete' })
     await hub.uninstall('example/review', '1.0.0')
     await hub.install('example/review', '1.0.0')
-    expect(registry.enabledFor(root, null)).toEqual([])
+    expect(registry.list(root).map((entry) => entry.id)).toEqual(['skills/review'])
     expect((await hub.list()).installed).toHaveLength(1)
   })
   it('preserves corrupt installation records rather than overwriting them', async () => {

package/src/hub/hub.ts

@@ -8,7 +8,7 @@ import { atomicWrite, now, readJson, readJsonOr, writeJson } from '../core/fs'
 import type { Harness } from '../harness'
 import * as pluginApi from '../plugins/api'
 import * as packages from '../plugins/install'
-import * as registry from '../skills/registry'
+import * as registry from '../tree/components'
 import * as attachments from '../plugins/attachments'
 import { version as harnessVersion } from '../../package.json'
 import bundled from './catalog.json'
@@ -244,7 +244,7 @@ export class Hub {
           const payload = JSON.parse(text)
           const previous = new Set(registry.list(root).map((item) => item.id))
           const imported = registry.importItems(root, delivery.registryKind, payload.items)
-          receipt.resourceIds = imported.items.filter((item) => !previous.has(item.id)).map((item) => item.id)
+          receipt.resourceIds = imported.filter((item) => !previous.has(item.id)).map((item) => item.id)
           const choices = structuredClone(choicesBefore)
           const ids = new Set(receipt.resourceIds)
           for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {

package/src/index.ts

@@ -1,11 +1,13 @@
-// @xingular/harness: a Pi agent harness. Multi-account Pi sessions, a compiled system prompt
-// with stable-prefix delivery, a memory lifecycle (Wiki, blocks, facts, recall, sleep-time
-// consolidation), tools with a gate and standing approvals, connected apps over MCP, and
-// skills (a person's own and built-in).
+// @xingular/harness: a Pi agent harness built on recursive harnessing (Harness², Apache-2.0,
+// Google LLC). Each agent runs on a versioned harness tree of eight components (system prompt,
+// guardrails, memory, tool guidance, subagents, skills, scripts, plugins); refinement improves a
+// tree from evidence through Propose–Probe–Compose, blind selection and an experience library.
+// Around it: multi-account Pi sessions, a compiled prompt with stable-prefix delivery, project
+// notes (the Wiki), history, tools with a gate and standing approvals, and connected apps.
 //
 // An application embeds it with `createHarness` and extends it through prompt sections, tool
-// providers, a tool policy, a secret store, a directory of its own names, and a description of
-// its own parts as plugins. Everything else is reachable by path, e.g. `@xingular/harness/memory/wiki`.
+// providers, a tool policy, a secret store, a directory of its own names, a description of its
+// own parts as plugins, and a refinement host. Everything else is reachable by path.
 export { createHarness, Harness, type HarnessOptions, type Recovery } from './harness'
 export { hubCatalogSchema, hubEntrySchema, hubOverviewSchema, hubReceiptSchema, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './hub/schema'
 
@@ -20,8 +22,8 @@ export type { AccountLoginSnapshot, ModelOption } from './accounts/accounts'
 export type { Capability, CapabilityCatalogue, CapabilityKind, CapabilityScope, CapabilitySet } from './capabilities/types'
 export type { RunCapabilitySnapshot } from './capabilities/runSnapshot'
 
-export type { CallerContext } from './memory/caller'
-export { dispatch as memoryCall } from './memory/dispatch'
+export type { CallerContext } from './core/caller'
+export { dispatch as harnessCall } from './tools/dispatch'
 
 export {
   compile,
@@ -30,7 +32,6 @@ export {
   CONTEXT_MESSAGE_TYPE,
   CONTEXT_SNAPSHOT_KEY,
   type ContextPack,
-  type ContextProfile,
   type HostSection,
   type HostToolGroup,
   type Launch,
@@ -45,19 +46,32 @@ export type { ActiveRun, ApprovalDecision, ApprovalInput, QuestionAnswer, Questi
 export type { RunFields, SessionRunInput } from './sessions/sessions'
 export type { Effort } from './sessions/runner'
 
-export { describeTool, WIKI_TOOLS, WIKI_TOOL_NAMES, type WikiCall, type WikiToolDefinition } from './tools/definitions'
+export { describeTool, HARNESS_TOOLS, DEFAULT_TOOL_NAMES, WIKI_WRITE, type HarnessCall, type HarnessToolDefinition } from './tools/definitions'
 export type { ToolProvider, ToolResult, ToolSession, ToolSpec } from './tools/types'
 export { SPAWN_SUBAGENT, SUBAGENT_RELATION } from './tools/spawnSubagent'
-export { maintenanceTools, MAINTENANCE_PLUGIN, MAINTENANCE_TOOL_NAMES } from './tools/maintenance'
-export type { CurationJob } from './memory/curation'
 export { webTools, WEB_PLUGIN, WEB_SEARCH_KEY, type WebToolOptions } from './web/tools'
-export { registryTools, REGISTRY_WRITE, PLUGIN_WRITE, REGISTRY_WRITE_PLUGIN, type RegistryToolOptions } from './tools/registryWrite'
 export { safeRequest, type WebRequest, type WebResponse } from './web/safeRequest'
 
 export type { BrokeredTools, BrokerSession, BrokerTool } from './mcp/service'
 export type { Connection, ConnectionInput, AppOAuthClients } from './mcp/types'
 
-export { configureBuiltins, type RegistryItem, type RegistryState, type SkillBundleInput } from './skills/registry'
+export { configureBuiltins, type ComponentItem, type SkillBundleInput } from './tree/components'
+
+// The harness tree and refinement.
+export { PI_SURFACE, componentOf, type ComponentGroup, type ComponentId, type ComponentInfo, type SurfaceSpec, type Tree } from './tree/surface'
+export { validate as validateTree, autotrigger, diffSummary, TreeError, type TreeCensus, type TreeDiff } from './tree/tree'
+export { fingerprint, type Head, type VersionRecord, type VersionSource } from './tree/store'
+export { materialise, type HarnessChoice, type Materialised } from './tree/materialise'
+export { seedTree, type SeedInput } from './tree/seed'
+export type { TrustedPlugin } from './tree/trust'
+export { DEFAULT_REFINE_HOST, defaultDeliverable, type RefineHost, type RolloutSession, type RolloutWorkspace } from './refine/host'
+export { PROBE_TRIGGER, IMPROVER_TRIGGER, type ImproverSettings } from './refine/pi'
+export type { CandidateView, StartInput as RefineStartInput } from './refine/service'
+export type { RefineEvent, RefineStatus, RefineSummary } from './refine/runner'
+export type { Executor, Improver, RecursionMode, RefineTask, Rollout } from './refine/types'
+export type { WorkPrompts } from './refine/prompts'
+export type { Experience } from './refine/library'
+export type { Note, NoteSummary } from './wiki/notes'
 
 export type { TerminalAssets, TerminalLaunch, TerminalPrepareInput } from './terminal/terminals'
 

package/src/mcp/connections.ts

@@ -8,7 +8,7 @@ import type { Bus } from '../core/bus'
 import { HarnessError, invalid, notFound } from '../core/errors'
 import { newId, readJson, safeId, writeJson } from '../core/fs'
 import { findBinary, pathVariableName, searchPath } from '../core/path'
-import { isDir } from '../memory/store'
+import { isDir } from '../core/fs'
 import type { RunEvent } from '../sessions/contracts'
 import * as attachments from '../plugins/attachments'
 import { connectionScopeMigrationComplete } from './scopeMigration'

package/src/mcp/service.ts

@@ -11,7 +11,7 @@ import { HarnessError, invalid, notFound } from '../core/errors'
 import { newId, now, readJson, writeJson } from '../core/fs'
 import { charCount, takeChars } from '../core/text'
 import type { CapabilitySet } from '../capabilities/types'
-import type { CallerContext } from '../memory/caller'
+import type { CallerContext } from '../core/caller'
 import type { ToolPolicy } from '../sessions/policy'
 import type { ActiveRun, RunRegistry } from '../sessions/registry'
 import { findRun, runDir } from '../sessions/runStore'

package/src/pi/proxy.test.ts

@@ -0,0 +1,68 @@
+import { execFile } from 'node:child_process'
+import { createServer } from 'node:http'
+import { promisify } from 'node:util'
+import { afterEach, expect, it } from 'vitest'
+
+const execFileAsync = promisify(execFile)
+const servers: ReturnType<typeof createServer>[] = []
+afterEach(async () => {
+  for (const server of servers.splice(0)) await new Promise<void>((resolve, reject) => server.close(error => error ? reject(error) : resolve()))
+})
+
+it('routes Pi HTTP requests through the process proxy environment', async () => {
+  const requests: Array<{ url: string | undefined; host: string | undefined; tunnel: boolean }> = []
+  const proxy = createServer((request, response) => {
+    requests.push({ url: request.url, host: request.headers.host, tunnel: false })
+    response.writeHead(200, { 'content-type': 'text/plain' })
+    response.end('served by local proxy')
+  })
+  proxy.on('connect', (request, socket, head) => {
+    requests.push({ url: request.url, host: request.headers.host, tunnel: true })
+    socket.write('HTTP/1.1 200 Connection Established\r\n\r\n')
+    let received = head.toString('utf8')
+    const respond = (): void => {
+      if (!received.includes('\r\n\r\n')) return
+      const body = 'served by local proxy'
+      socket.end(`HTTP/1.1 200 OK\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`)
+    }
+    socket.on('data', chunk => {
+      received += chunk.toString('utf8')
+      respond()
+    })
+    respond()
+  })
+  servers.push(proxy)
+  await new Promise<void>((resolve, reject) => {
+    proxy.once('error', reject)
+    proxy.listen(0, '127.0.0.1', resolve)
+  })
+
+  const address = proxy.address()
+  if (!address || typeof address === 'string') throw new Error('The local proxy did not bind to a TCP port.')
+  const proxyUrl = `http://127.0.0.1:${address.port}`
+  const script = `
+    import { join } from 'node:path'
+    import { pathToFileURL } from 'node:url'
+
+    const pi = await import('@earendil-works/pi-coding-agent')
+    const dispatcherUrl = pathToFileURL(join(pi.getPackageDir(), 'dist/bundle/chunks/chunk-TJXZSVTD.js')).href
+    const { configureHttpDispatcher } = await import(dispatcherUrl)
+    configureHttpDispatcher()
+    const response = await fetch('http://127.0.0.2/dispatcher-check')
+    if (response.status !== 200 || await response.text() !== 'served by local proxy') throw new Error('Pi did not receive the local proxy response')
+  `
+  const env: NodeJS.ProcessEnv = {
+    ...(process.env.PATH ? { PATH: process.env.PATH } : {}),
+    HTTP_PROXY: proxyUrl,
+    HTTPS_PROXY: proxyUrl,
+    NO_PROXY: 'localhost,127.0.0.1'
+  }
+
+  await execFileAsync(process.execPath, ['--input-type=module', '-e', script], {
+    cwd: process.cwd(),
+    env,
+    timeout: 10_000
+  })
+
+  expect(requests).toEqual([{ url: '127.0.0.2:80', host: '127.0.0.2', tunnel: true }])
+})

package/src/pi/runtime.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { createPiLoader } from './runtime'
+
+describe('Pi runtime initialization', () => {
+  it('configures Pi networking before returning the module and shares concurrent initialization', async () => {
+    const events: string[] = []
+    const pi = { VERSION: '1.2.0', getPackageDir: () => '/pinned/pi' }
+    const load = createPiLoader(
+      async () => {
+        events.push('import Pi')
+        return pi
+      },
+      async (packageDir) => {
+        events.push(`load dispatcher from ${packageDir}`)
+        return { configureHttpDispatcher: () => events.push('configure dispatcher') }
+      }
+    )
+
+    const [first, second] = await Promise.all([load(), load()])
+
+    expect(first).toBe(pi)
+    expect(second).toBe(pi)
+    expect(events).toEqual(['import Pi', 'load dispatcher from /pinned/pi', 'configure dispatcher'])
+  })
+
+  it('rejects a Pi version change before loading its private dispatcher', async () => {
+    const loadDispatcher = vi.fn(async () => ({ configureHttpDispatcher: vi.fn() }))
+    const load = createPiLoader(async () => ({ VERSION: '1.3.0', getPackageDir: () => '/other/pi' }), loadDispatcher)
+
+    await expect(load()).rejects.toThrow('requires Pi 1.2.0')
+    expect(loadDispatcher).not.toHaveBeenCalled()
+  })
+
+  it('reports when Pi no longer exposes its private dispatcher hook', async () => {
+    const load = createPiLoader(
+      async () => ({ VERSION: '1.2.0', getPackageDir: () => '/pinned/pi' }),
+      async () => ({})
+    )
+
+    await expect(load()).rejects.toThrow('pinned Pi 1.2.0 HTTP dispatcher hook')
+  })
+
+  it('can retry initialization after a transient dispatcher load failure', async () => {
+    const configure = vi.fn()
+    let attempts = 0
+    const load = createPiLoader(
+      async () => ({ VERSION: '1.2.0', getPackageDir: () => '/pinned/pi' }),
+      async () => {
+        attempts++
+        if (attempts === 1) throw new Error('temporary import failure')
+        return { configureHttpDispatcher: configure }
+      }
+    )
+
+    await expect(load()).rejects.toThrow('temporary import failure')
+    await expect(load()).resolves.toMatchObject({ VERSION: '1.2.0' })
+    expect(attempts).toBe(2)
+    expect(configure).toHaveBeenCalledOnce()
+  })
+})

package/src/pi/runtime.ts

@@ -0,0 +1,50 @@
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export const PINNED_PI_VERSION = '1.2.0'
+const HTTP_DISPATCHER_CHUNK = 'dist/bundle/chunks/chunk-TJXZSVTD.js'
+
+type PiRuntimeModule = {
+  VERSION: string
+  getPackageDir(): string
+}
+
+type PiDispatcherModule = {
+  configureHttpDispatcher?: unknown
+}
+
+export function assertPiRuntimeVersion(version: string): void {
+  if (version !== PINNED_PI_VERSION) throw new Error(`The Harness Pi runtime requires Pi ${PINNED_PI_VERSION}; found ${version}. Install the Harness package's pinned dependencies.`)
+}
+
+/** Builds a cached Pi loader so initialization order and compatibility behavior can be verified. */
+export function createPiLoader<T extends PiRuntimeModule>(
+  importPi: () => Promise<T>,
+  importDispatcher: (packageDir: string) => Promise<PiDispatcherModule>
+): () => Promise<T> {
+  let loading: Promise<T> | undefined
+
+  return () => {
+    if (!loading) {
+      loading = (async () => {
+        const pi = await importPi()
+        assertPiRuntimeVersion(pi.VERSION)
+        const dispatcher = await importDispatcher(pi.getPackageDir())
+        if (typeof dispatcher.configureHttpDispatcher !== 'function') {
+          throw new Error(`The Harness requires the pinned Pi ${PINNED_PI_VERSION} HTTP dispatcher hook; install the Harness package's pinned dependencies.`)
+        }
+        dispatcher.configureHttpDispatcher()
+        return pi
+      })().catch((error: unknown) => {
+        loading = undefined
+        throw error
+      })
+    }
+    return loading
+  }
+}
+
+export const loadPi = createPiLoader(
+  () => import('@earendil-works/pi-coding-agent'),
+  async (packageDir) => await import(pathToFileURL(join(packageDir, HTTP_DISPATCHER_CHUNK)).href) as PiDispatcherModule
+)