@xingular/harness 0.0.0-stage → 0.1.0

package/src/core/index.ts

@@ -0,0 +1,193 @@
+// Derived SQLite index at `<data root>/index.sqlite`: full-text search over every Wiki entry
+// (pages, facts, blocks, registry skills/prompts/rules), links, sources, revisions, run
+// metadata, and recall passages. Markdown, raw sources, revision manifests, registry files, and
+// run files stay canonical; the index can always be deleted and rebuilt from them.
+import { copyFileSync, existsSync, readdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite'
+
+import { HarnessError } from './errors'
+
+/** Index migration 4: recall, the searchable record of conversations and runs. */
+const RECALL_SCHEMA = `CREATE TABLE recall_runs (run_id TEXT PRIMARY KEY, passages INTEGER NOT NULL, status TEXT NOT NULL);
+     CREATE VIRTUAL TABLE recall_fts USING fts5(run_id UNINDEXED, seq UNINDEXED, role UNINDEXED, at UNINDEXED,
+        mode UNINDEXED, session_id UNINDEXED, project_id UNINDEXED, text, tokenize = 'unicode61 remove_diacritics 2');`
+
+/** Ordered, append-only migrations. Each runs in one transaction; the file is backed up first. */
+export const MIGRATIONS: readonly string[] = [
+  // 1: initial schema
+  `CREATE TABLE pages (scope TEXT NOT NULL, id TEXT NOT NULL, title TEXT NOT NULL, type TEXT NOT NULL,
+        updated_at TEXT, path TEXT NOT NULL, source_ids TEXT NOT NULL, PRIMARY KEY (scope, id));
+     CREATE VIRTUAL TABLE pages_fts USING fts5(scope UNINDEXED, id UNINDEXED, title, body, links, sources,
+        tokenize = 'unicode61 remove_diacritics 2');
+     CREATE TABLE links (scope TEXT NOT NULL, from_id TEXT NOT NULL, to_id TEXT NOT NULL, type TEXT NOT NULL);
+     CREATE INDEX links_to ON links (scope, to_id);
+     CREATE TABLE sources (scope TEXT NOT NULL, id TEXT NOT NULL, name TEXT NOT NULL, imported_at TEXT, version INTEGER,
+        PRIMARY KEY (scope, id));
+     CREATE TABLE revisions (scope TEXT NOT NULL, page_id TEXT NOT NULL, id TEXT NOT NULL, created_at TEXT, actor TEXT,
+        PRIMARY KEY (scope, id));
+     CREATE TABLE runs (id TEXT PRIMARY KEY, project_id TEXT, mode TEXT, harness TEXT, session_type TEXT,
+        session_id TEXT, status TEXT, started_at TEXT, ended_at TEXT);
+     CREATE INDEX runs_session ON runs (session_id, started_at);`,
+  // 2: accounts and token usage per run
+  `ALTER TABLE runs ADD COLUMN account_id TEXT;
+     CREATE INDEX runs_account ON runs (account_id, started_at);
+     CREATE TABLE usage (run_id TEXT PRIMARY KEY, account_id TEXT, harness TEXT, model TEXT, day TEXT NOT NULL,
+        input_tokens INTEGER NOT NULL DEFAULT 0, output_tokens INTEGER NOT NULL DEFAULT 0);
+     CREATE INDEX usage_account ON usage (account_id, day);`,
+  // 3: one global Wiki; entries replace per-scope pages and include facts and registry items
+  `DROP TABLE IF EXISTS pages_fts; DROP TABLE IF EXISTS pages; DROP TABLE IF EXISTS links;
+     DROP TABLE IF EXISTS sources; DROP TABLE IF EXISTS revisions;
+     CREATE TABLE entries (id TEXT PRIMARY KEY, kind TEXT NOT NULL, title TEXT NOT NULL, type TEXT, path TEXT NOT NULL,
+        namespace TEXT NOT NULL, file TEXT NOT NULL, updated_at TEXT, source_ids TEXT NOT NULL);
+     CREATE VIRTUAL TABLE entries_fts USING fts5(id UNINDEXED, kind UNINDEXED, namespace UNINDEXED, title, body, links, sources,
+        tokenize = 'unicode61 remove_diacritics 2');
+     CREATE TABLE links (from_id TEXT NOT NULL, to_id TEXT NOT NULL, type TEXT NOT NULL);
+     CREATE INDEX links_to ON links (to_id);
+     CREATE TABLE sources (id TEXT PRIMARY KEY, name TEXT NOT NULL, imported_at TEXT, version INTEGER);
+     CREATE TABLE revisions (entry_id TEXT NOT NULL, id TEXT PRIMARY KEY, created_at TEXT, actor TEXT);
+     CREATE INDEX revisions_entry ON revisions (entry_id, created_at);`,
+  RECALL_SCHEMA,
+  // 5: a per-run summary cache for the embedding application's analytics
+  `CREATE TABLE run_stats (run_id TEXT PRIMARY KEY, session_id TEXT NOT NULL, version INTEGER NOT NULL, stats TEXT NOT NULL);
+     CREATE INDEX run_stats_session ON run_stats (session_id, version);`,
+  // 6: the agent that replied, so one agent's runs can be read across its sessions
+  `ALTER TABLE runs ADD COLUMN agent_id TEXT;
+     CREATE INDEX runs_agent ON runs (agent_id, started_at);
+     CREATE INDEX runs_started ON runs (started_at);`,
+  // 7: the per-account usage table goes
+  'DROP TABLE IF EXISTS usage;'
+]
+
+const connections = new Map<string, DatabaseSync>()
+
+export function dbPath(root: string): string {
+  return join(root, 'index.sqlite')
+}
+
+function sqlError(error: unknown): HarnessError {
+  return new HarnessError('index_error', error instanceof Error ? error.message : String(error), 'Settings → Projects and Storage → Repair index.')
+}
+
+function schemaVersion(database: DatabaseSync): number {
+  database.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);')
+  const row = database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get() as { value?: string } | undefined
+  const version = Number.parseInt(row?.value ?? '', 10)
+  return Number.isInteger(version) && version >= 0 ? version : 0
+}
+
+/** Runs `work` inside one transaction, rolling back if it throws. */
+export function transaction<T>(database: DatabaseSync, work: () => T): T {
+  database.exec('BEGIN')
+  try {
+    const result = work()
+    database.exec('COMMIT')
+    return result
+  } catch (error) {
+    try {
+      database.exec('ROLLBACK')
+    } catch {
+      // The transaction is already gone.
+    }
+    throw error
+  }
+}
+
+/**
+ * Applies pending migrations. The database file is copied first; if any migration fails, the
+ * copy is restored and the error is reported.
+ */
+export function migrate(path: string, migrations: readonly string[]): DatabaseSync {
+  let database: DatabaseSync
+  let current: number
+  try {
+    database = new DatabaseSync(path)
+    current = schemaVersion(database)
+  } catch (error) {
+    throw sqlError(error)
+  }
+  if (current >= migrations.length) return database
+  const backup = `${path.replace(/\.sqlite$/, '')}.sqlite.bak-v${current}`
+  const hadFile = existsSync(path) && current > 0
+  if (hadFile) {
+    try {
+      database.exec('PRAGMA wal_checkpoint(TRUNCATE);')
+    } catch {
+      // A checkpoint that cannot run leaves the copy slightly behind, which a rebuild repairs.
+    }
+    copyFileSync(path, backup)
+  }
+  for (let index = current; index < migrations.length; index += 1) {
+    try {
+      transaction(database, () => {
+        database.exec(migrations[index])
+        database.prepare("INSERT INTO meta (key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(String(index + 1))
+      })
+    } catch (error) {
+      database.close()
+      if (hadFile) copyFileSync(backup, path)
+      else rmSync(path, { force: true })
+      throw new HarnessError('migration_failed', `Index migration ${index + 1} failed and the previous index was restored: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  return database
+}
+
+/** Runs `work` with the shared connection for this data root, opening and migrating it on first use. */
+export function withIndex<T>(root: string, work: (database: DatabaseSync) => T): T {
+  const path = dbPath(root)
+  let database = connections.get(path)
+  if (!database) {
+    database = migrate(path, MIGRATIONS)
+    try {
+      database.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;')
+    } catch (error) {
+      database.close()
+      throw sqlError(error)
+    }
+    connections.set(path, database)
+  }
+  try {
+    return work(database)
+  } catch (error) {
+    throw error instanceof HarnessError ? error : sqlError(error)
+  }
+}
+
+/** Closes this data root's connection, if one is open. */
+export function closeIndex(root: string): void {
+  const path = dbPath(root)
+  connections.get(path)?.close()
+  connections.delete(path)
+}
+
+/** Closes the connection and removes the index files; the next use rebuilds the schema. */
+export function deleteIndex(root: string): void {
+  closeIndex(root)
+  for (const suffix of ['', '-wal', '-shm']) rmSync(`${dbPath(root)}${suffix}`, { force: true })
+}
+
+export type Param = SQLInputValue
+
+export function all<T>(database: DatabaseSync, sql: string, ...params: Param[]): T[] {
+  return database.prepare(sql).all(...params) as T[]
+}
+
+export function run(database: DatabaseSync, sql: string, ...params: Param[]): void {
+  database.prepare(sql).run(...params)
+}
+
+/** Folder names under `<data root>/runs`. */
+export function runFolders(root: string): string[] {
+  try {
+    return readdirSync(join(root, 'runs'))
+  } catch {
+    return []
+  }
+}
+
+/** Turns free text into an FTS5 query: each word becomes a quoted prefix term. */
+export function ftsQuery(query: string): string | null {
+  const terms = query.split(/[^\p{Alphabetic}\p{N}]+/u).filter(Boolean).map((term) => `"${term.replaceAll('"', '')}"*`)
+  return terms.length ? terms.join(' ') : null
+}

package/src/core/path.ts

@@ -0,0 +1,45 @@
+// Where executables are found. A desktop application starts with a minimal PATH, so the login
+// shell's PATH is resolved once and used for everything the harness launches.
+import { execFileSync } from 'node:child_process'
+import { accessSync, constants, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, isAbsolute, join } from 'node:path'
+
+let resolved: string | null = null
+
+export function searchPath(): string {
+  if (resolved !== null) return resolved
+  const entries: string[] = []
+  try {
+    const output = execFileSync(process.env.SHELL || '/bin/zsh', ['-ilc', 'printf %s "$PATH"'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] })
+    // Interactive shells may print banners; the PATH is the last line.
+    entries.push(...(output.split('\n').filter(Boolean).at(-1) ?? '').split(delimiter))
+  } catch {
+    // The inherited PATH and the usual folders still apply.
+  }
+  entries.push(...(process.env.PATH ?? '').split(delimiter))
+  const home = homedir()
+  if (home) entries.push(...['.local/bin', '.bun/bin', '.npm-global/bin', '.cargo/bin'].map((folder) => join(home, folder)))
+  entries.push('/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin')
+  resolved = [...new Set(entries.filter(Boolean))].join(delimiter)
+  return resolved
+}
+
+function isExecutable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK)
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** The executable `name` resolves to: itself when absolute, else the first match on the search path. */
+export function findBinary(name: string): string | null {
+  if (isAbsolute(name)) return isExecutable(name) ? name : null
+  for (const directory of searchPath().split(delimiter)) {
+    const candidate = join(directory, name)
+    if (isExecutable(candidate)) return candidate
+  }
+  return null
+}

package/src/core/projects.ts

@@ -0,0 +1,90 @@
+// Projects: named working folders, each with a Wiki namespace (`/projects/<slug>`). The harness
+// reads `<data root>/projects.json`; the embedding application adds, renames, and removes them.
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { notFound } from './errors'
+import { readJson } from './fs'
+import { newId } from './fs'
+
+interface ProjectRecord {
+  id: string
+  name: string
+  rootPath: string
+  autoMaintenance: boolean
+  createdAt: string
+  /** Stable Wiki namespace segment; kept when the project is renamed. */
+  slug?: string
+}
+
+export interface Project {
+  id: string
+  name: string
+  rootPath: string
+  isGitRepository: boolean
+  autoMaintenance: boolean
+  createdAt: string
+  slug: string
+  /** `/projects/<slug>`: where this project's pages live in the Wiki. */
+  wikiNamespace: string
+}
+
+/** Same rule as the Wiki's page slugs, kept here so `core` does not depend on `memory`. */
+export function slugify(text: string): string {
+  let value = ''
+  for (const character of text.toLowerCase()) {
+    if (/^[a-z0-9]$/.test(character)) value += character
+    else if (value && !value.endsWith('-')) value += '-'
+  }
+  value = value.replace(/^-+|-+$/g, '').slice(0, 60)
+  return value || `page-${newId().slice(0, 8)}`
+}
+
+export function uniqueSlug(name: string, taken: readonly string[]): string {
+  const slug = slugify(name)
+  const base = slug.startsWith('page-') ? 'project' : slug
+  let candidate = base
+  for (let counter = 2; taken.includes(candidate); counter += 1) candidate = `${base}-${counter}`
+  return candidate
+}
+
+function load(root: string): ProjectRecord[] {
+  const records = readJson<ProjectRecord[]>(join(root, 'projects.json')) ?? []
+  // Records without a slug get a unique one derived from the name, in list order, so the result
+  // is the same on every read until the application persists it.
+  const taken = records.map((record) => record.slug ?? '').filter(Boolean)
+  for (const record of records) {
+    if (record.slug) continue
+    record.slug = uniqueSlug(record.name, taken)
+    taken.push(record.slug)
+  }
+  return records
+}
+
+export function listProjects(root: string): Project[] {
+  return load(root).map((record) => ({
+    id: record.id,
+    name: record.name,
+    rootPath: record.rootPath,
+    isGitRepository: existsSync(join(record.rootPath, '.git')),
+    autoMaintenance: record.autoMaintenance,
+    createdAt: record.createdAt,
+    slug: record.slug!,
+    wikiNamespace: `/projects/${record.slug}`
+  }))
+}
+
+/** `listProjects` for callers that treat an unreadable registry like an empty one. */
+export function projectsOrNone(root: string): Project[] {
+  try {
+    return listProjects(root)
+  } catch {
+    return []
+  }
+}
+
+export function findProject(root: string, projectId: string): Project {
+  const project = listProjects(root).find((entry) => entry.id === projectId)
+  if (!project) throw notFound('Project')
+  return project
+}

package/src/core/text.ts

@@ -0,0 +1,39 @@
+// Text helpers that count Unicode characters, not UTF-16 units, so budgets and cuts agree across languages.
+
+export function charCount(text: string): number {
+  let count = 0
+  for (const _ of text) count += 1
+  return count
+}
+
+export function takeChars(text: string, count: number): string {
+  if (text.length <= count) return text
+  let taken = 0
+  let end = 0
+  for (const character of text) {
+    if (taken >= count) break
+    taken += 1
+    end += character.length
+  }
+  return text.slice(0, end)
+}
+
+/** Lines without their terminators; a final newline does not add an empty last line. */
+export function lines(text: string): string[] {
+  if (!text) return []
+  const parts = text.split('\n')
+  if (parts[parts.length - 1] === '') parts.pop()
+  return parts.map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line))
+}
+
+/** Orders file paths segment by segment, so a folder sorts before a sibling whose name extends it. */
+export function comparePaths(left: string, right: string): number {
+  const a = left.split('/')
+  const b = right.split('/')
+  for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1
+  }
+  return a.length - b.length
+}
+
+export const compareText = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0)

package/src/harness.ts

@@ -0,0 +1,289 @@
+// 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.
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { Accounts } from './accounts/accounts'
+import * as capabilities from './capabilities/api'
+import { ensureSharedDir, isolateProcess } from './accounts/env'
+import { fileSecretStore, type SecretStore } from './accounts/secrets'
+import { Bus, log } from './core/bus'
+import { DEFAULT_PRODUCT_NAME, EMPTY_DIRECTORY, type Directory, type HarnessEnv } from './core/env'
+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 { 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 pluginApi from './plugins/api'
+import * as attachments from './plugins/attachments'
+import { HARNESS_PLUGINS } from './plugins/builtin'
+import type { Resolver } from './plugins/discover'
+import { Hooks } from './plugins/hooks'
+import { packageFolders, Plugins } from './plugins/plugins'
+import type { PluginDescriptor } from './plugins/types'
+import { approvalKey, Approvals } from './sessions/approvals'
+import type { ToolPolicy } from './sessions/policy'
+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 {
+  /** Where knowledge and history live. May be set later with `open`. */
+  dataRoot?: string | null
+  /** Device-local state that never belongs in the data root: accounts, approvals, connections, sockets. */
+  stateDir: string
+  /** Where credentials are kept. Defaults to an owner-only file in the state directory. */
+  secrets?: SecretStore
+  /** How the harness names itself to a model. */
+  productName?: string
+  directory?: Directory
+  policy?: ToolPolicy
+  /** Replaces Pi, for tests. */
+  sessionFactory?: SessionFactory
+  maintainerFactory?: MaintainerFactory
+  /** How long the maintenance queue stays empty before full memory blocks are condensed. */
+  idleMs?: number
+  /** Where the built commands a terminal session runs are, when they are not beside this package. */
+  assets?: TerminalAssets
+  /** The `pi` executable a terminal session runs. Defaults to the one on the search path. */
+  piProgram?: () => string | null
+  /** Folders of built-in skills, prompts, and rules, each laid out like `registry/`. */
+  builtins?: string[]
+  /**
+   * The application's own parts, described as plugins: which tools, prompt sections and tool
+   * groups each one provides. Data only; it changes what is listed, never what runs.
+   */
+  plugins?: PluginDescriptor[]
+  /** Replaces Pi's own search for extensions, skills, prompts and themes, for tests. */
+  resolver?: Resolver
+  /** Replaces how a plugin's hooks file is read as a module, for tests. */
+  hookImporter?: (address: string) => Promise<unknown>
+}
+
+/** What starting on a data root found and repaired. */
+export interface Recovery {
+  interruptedRuns: number
+  reindexedPages: number
+  /** Set when the storage migration failed; the old data is left as it was. */
+  migrationError: string | null
+}
+
+class Env implements HarnessEnv {
+  dataRoot: string | null
+  readonly bus: Bus
+
+  constructor(
+    dataRoot: string | null,
+    readonly directory: Directory,
+    readonly productName: string,
+    bus: Bus
+  ) {
+    this.dataRoot = dataRoot
+    this.bus = bus
+  }
+
+  get root(): string {
+    if (!this.dataRoot) throw new HarnessError('data_root_missing', 'Choose a data location first.', 'Open Settings → Projects and Storage.')
+    return this.dataRoot
+  }
+}
+
+export class Harness {
+  readonly bus = new Bus()
+  readonly env: Env
+  readonly stateDir: string
+  readonly policy: ToolPolicy
+  readonly accounts: Accounts
+  readonly approvals: Approvals
+  readonly runs: RunRegistry
+  readonly apps: ConnectedApps
+  readonly plugins: Plugins
+  /** Code plugins gave the harness to run after memory, the Wiki or history changed. */
+  readonly hooks: Hooks
+  /** Every part described as a plugin: the harness's own, then the application's. */
+  descriptors: readonly PluginDescriptor[] = HARNESS_PLUGINS
+  applicationPlugins: ReadonlySet<string> = new Set()
+  readonly sessions: Sessions
+  readonly maintenance: Maintenance
+  readonly terminals: Terminals
+  /** Resolves when what was loaded in the background at construction is in place. */
+  readonly ready: Promise<void>
+  recovery: Recovery = { interruptedRuns: 0, reindexedPages: 0, migrationError: null }
+
+  constructor(options: HarnessOptions) {
+    this.stateDir = options.stateDir
+    mkdirSync(this.stateDir, { recursive: true })
+    // Before anything can start a session: no inherited credential, no `~/.pi`.
+    isolateProcess(join(this.stateDir, 'accounts'))
+    this.env = new Env(options.dataRoot || null, options.directory ?? EMPTY_DIRECTORY, options.productName ?? DEFAULT_PRODUCT_NAME, this.bus)
+    this.policy = options.policy ?? {}
+    registry.configureBuiltins(options.builtins ?? [])
+    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)
+    this.runs = new RunRegistry({
+      root: () => this.env.root,
+      automatic: async (run, target, operation, standing) => {
+        if (standing === 'switch') return this.approvals.isAuto(approvalKey(run)) ? 'always' : null
+        return this.approvals.automatic(run, target, (await this.policy.approval?.({ run, target, operation })) ?? {})
+      },
+      redact: (event) => this.apps.connections.redactEvent(event),
+      ended: (runId, sessionId) => this.apps.revokeRun(runId, sessionId)
+    })
+    this.apps = new ConnectedApps({ env: this.env, stateDir: this.stateDir, secrets, bus: this.bus, runs: this.runs, policy: this.policy })
+    this.plugins = new Plugins({ stateDir: this.stateDir, bus: this.bus, resolver: options.resolver, attachments: () => (this.env.dataRoot ? attachments.load(this.env.dataRoot) : null), packagesDir: () => (this.env.dataRoot ? join(this.env.dataRoot, 'plugins') : null) })
+    this.hooks = new Hooks({
+      stateDir: this.stateDir,
+      bus: this.bus,
+      // A hook runs for everyone or not at all, so only what is on everywhere and trusted counts.
+      // The shared folder stands in for an account: packages are the same for all of them.
+      wanted: async () => {
+        if (!this.env.dataRoot) return []
+        const shared = ensureSharedDir(join(this.stateDir, 'accounts'))
+        // A hook comes only with a package: one kept beside the data, or one the shared settings
+        // name. With neither there is nothing to look for, and Pi is not loaded to find that out.
+        const named = readJsonOr<{ packages?: unknown }>(join(shared, 'settings.json'), {}).packages
+        if (!packageFolders(join(this.env.dataRoot, 'plugins')).length && !(Array.isArray(named) && named.length)) return []
+        return (await this.plugins.loading({ cwd: this.stateDir, agentDir: shared, caller: {} })).hooks
+      },
+      call: (connection, tool, args) => this.apps.callUnattended(connection, tool, args ?? {}),
+      importFile: options.hookImporter
+    })
+    let reloadTimer: ReturnType<typeof setTimeout> | null = null
+    this.bus.on((notice) => {
+      if (notice.type !== 'plugins.changed' || reloadTimer) return
+      // Several changes arrive together when a plugin is installed or switched; one reload covers them.
+      reloadTimer = setTimeout(() => {
+        reloadTimer = null
+        void this.hooks.reload()
+      }, 50)
+      reloadTimer.unref?.()
+    })
+    this.describe(options.plugins ?? [])
+    this.sessions = new Sessions({
+      env: this.env,
+      accounts: this.accounts,
+      runs: this.runs,
+      policy: this.policy,
+      broker: this.apps,
+      plugins: this.plugins,
+      resolveCapabilities: (caller, tools) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, tools }),
+      factory: options.sessionFactory
+    })
+    this.maintenance = new Maintenance({ env: this.env, bus: this.bus, accounts: this.accounts, factory: options.maintainerFactory, idleMs: options.idleMs })
+    this.terminals = new Terminals({ env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, 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 })
+    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)
+      // Each run is indexed when it ends, so the next turn can already recall it.
+      if (event.type === 'completed' || event.type === 'failed') recall.indexRun(this.env.root, event.runId)
+      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 })
+      }
+      this.maintenance.onRunEvent(event)
+    })
+  }
+
+  get dataRoot(): string | null {
+    return this.env.dataRoot
+  }
+
+  /** Sets the application's own parts, described as plugins. One with a harness plugin's id is ignored. */
+  describe(plugins: readonly PluginDescriptor[]): void {
+    const own = new Set(HARNESS_PLUGINS.map((plugin) => plugin.id))
+    const supplied = plugins.filter((plugin) => plugin && typeof plugin.id === 'string' && !own.has(plugin.id))
+    this.descriptors = [...HARNESS_PLUGINS, ...supplied]
+    this.applicationPlugins = new Set(supplied.map((plugin) => plugin.id))
+  }
+
+  /**
+   * 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.
+   */
+  open(dataRoot: string, agentIds: readonly string[] = []): Recovery {
+    if (this.env.dataRoot && this.env.dataRoot !== dataRoot) closeIndex(this.env.dataRoot)
+    this.env.dataRoot = dataRoot
+    const root = dataRoot
+    this.hooks.watch(store.wikiDir(root))
+    void this.hooks.reload()
+    for (const folder of ['registry/skills', 'registry/prompts', 'registry/rules', 'config', 'runs']) mkdirSync(join(root, folder), { recursive: true })
+    let migrationError: 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`)
+    } catch (error) {
+      migrationError = error instanceof Error ? error.message : String(error)
+      log('Wiki migration failed', migrationError)
+    }
+    if (!migrationError) {
+      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.
+      recall.sync(root)
+    } catch (error) {
+      log('recall', error instanceof Error ? error.message : String(error))
+    }
+    this.recovery = { interruptedRuns, reindexedPages, migrationError }
+    this.maintenance.start()
+    return this.recovery
+  }
+
+  /** Deletes the index and rebuilds it from the files. Returns the pages indexed. */
+  rebuildIndex(): number {
+    const pages = wikiIndex.rebuild(this.env.root)
+    recall.sync(this.env.root)
+    this.recovery = { ...this.recovery, reindexedPages: pages }
+    return pages
+  }
+
+  /** Stops live runs and releases the index. */
+  async close(): Promise<void> {
+    this.maintenance.stop()
+    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()
+    if (this.env.dataRoot) closeIndex(this.env.dataRoot)
+  }
+}
+
+export function createHarness(options: HarnessOptions): Harness {
+  const harness = new Harness(options)
+  if (options.dataRoot) harness.open(options.dataRoot)
+  return harness
+}