@xingular/harness 0.1.6 → 2.0.0

package/src/accounts/accounts.ts

@@ -1,7 +1,7 @@
 // The accounts service: everything that needs the secret store, the Pi runtime, or a notice.
 // Credentials go to the embedding application's secret store; nothing here writes one to the
 // harness's own files, except a terminal session's `auth.json` while that terminal runs.
-import { chmodSync, rmSync } from 'node:fs'
+import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
 import { randomUUID } from 'node:crypto'
 import { join } from 'node:path'
 
@@ -38,6 +38,36 @@ export interface ModelOption {
 
 type Credential = Record<string, unknown> & { type: 'api_key' | 'oauth' }
 
+/** The lease files of an account: one per process that has a terminal on it. */
+const leaseFolder = (dir: string, accountId: string): string => join(dir, accountId, 'terminal-leases')
+
+/** Whether a process with this id exists. One that exists but belongs to another user still counts. */
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/** The credentials in an auth.json, or null when there is no readable file. */
+function readAuth(path: string): Record<string, Credential> | null {
+  try {
+    const parsed = readJson<Record<string, Credential>>(path)
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** Compares two credentials by their fields, not their key order, which Pi may change when it rewrites the file. */
+function sameCredential(a: Credential | undefined, b: Credential | undefined): boolean {
+  if (a === b) return true
+  if (!a || !b) return false
+  return JSON.stringify(a, Object.keys(a).sort()) === JSON.stringify(b, Object.keys(b).sort())
+}
+
 function validProvider(provider: string): string {
   if (provider && provider.length <= 64 && /^[A-Za-z0-9._-]+$/.test(provider)) return provider
   throw invalid('Invalid provider name.')
@@ -45,8 +75,26 @@ function validProvider(provider: string): string {
 
 interface PendingLogin {
   accountId: string
+  provider: string
+  method: 'oauth' | 'api_key'
   cancel: () => void
   prompts: Map<string, { resolve: (value: string) => void; reject: (error: Error) => void }>
+  revision: number
+  events: Record<string, unknown>[]
+  prompt: Record<string, unknown> | null
+}
+
+export interface AccountLoginSnapshot {
+  accountId: string
+  loginId: string
+  provider: string
+  method: string
+  revision: number
+  status: 'running' | 'completed' | 'failed' | 'cancelled'
+  events: Record<string, unknown>[]
+  prompt: Record<string, unknown> | null
+  success: boolean | null
+  error: string | null
 }
 
 interface Probe {
@@ -71,7 +119,12 @@ export class Accounts {
   private readonly bus: Bus
   private readonly runtimes = new Map<string, Promise<ModelRuntime>>()
   private readonly logins = new Map<string, PendingLogin>()
+  private readonly latestLogins = new Map<string, AccountLoginSnapshot>()
+  /** How many of this process's terminals use each account's auth.json. */
   private readonly terminals = new Map<string, number>()
+  /** The credentials this process wrote to, or found in, each account's auth.json when its first terminal began. */
+  private readonly terminalSnapshots = new Map<string, Record<string, Credential>>()
+  private installationDeviceIdPromise: Promise<string> | null = null
 
   constructor(options: AccountsOptions) {
     this.dir = options.dir
@@ -157,6 +210,25 @@ export class Accounts {
     }
   }
 
+  /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
+  installationDeviceId(): Promise<string> {
+    if (!this.installationDeviceIdPromise) {
+      this.installationDeviceIdPromise = this.loadInstallationDeviceId().catch((error: unknown) => {
+        this.installationDeviceIdPromise = null
+        throw error
+      })
+    }
+    return this.installationDeviceIdPromise
+  }
+
+  private async loadInstallationDeviceId(): Promise<string> {
+    const { SettingsManager } = await import('@earendil-works/pi-coding-agent')
+    const settings = SettingsManager.create(process.cwd(), env.ensureSharedDir(this.dir))
+    const deviceId = settings.getOrCreateDeviceId()
+    await settings.flush()
+    return deviceId
+  }
+
   // ---- The Pi runtime ---------------------------------------------------------------------
 
   /** The lazily loaded Pi runtime of one account: its models and its credentials. Pi's own `~/.pi` is never used. */
@@ -250,7 +322,7 @@ export class Accounts {
         const keepLimitError = current.lastError !== null && store.isLimitCategory(current.lastError.category) && store.limitErrorActive(current.lastError)
         if (probe.signedIn === true && !keepLimitError) current.lastError = null
       } else {
-        current.lastError = { category: 'unknown', message: store.scrub(failure ?? ''), at: now(), resetsAt: null }
+        current.lastError = { category: classifyMessage(failure ?? '') ?? 'unknown', message: store.scrub(failure ?? ''), at: now(), resetsAt: null }
       }
     })
     if (previous !== state.health) store.audit(this.dir, account.id, 'health.changed', `${previous} → ${state.health} (status check)`)
@@ -295,6 +367,8 @@ export class Accounts {
   /** Deletes the account: removes its stored credentials and its runtime folder. Sessions pinned to it ask for another account next time they start. */
   async remove(accountId: string): Promise<AccountsOverview> {
     const account = this.find(accountId)
+    for (const login of this.logins.values()) if (login.accountId === accountId) login.cancel()
+    this.latestLogins.delete(accountId)
     await this.forgetCredentials(account).catch(() => undefined)
     await this.secrets.delete(secretKey(account.id, 'apiKey')).catch(() => undefined)
     store.forgetAccount(this.dir, account)
@@ -354,7 +428,7 @@ export class Accounts {
     return this.overview()
   }
 
-  private finishLogin(loginId: string, success: boolean, error: string | null): void {
+  private finishLogin(loginId: string, success: boolean, error: string | null, cancelled = false): void {
     const login = this.logins.get(loginId)
     if (!login) return
     this.logins.delete(loginId)
@@ -363,7 +437,25 @@ export class Accounts {
     store.audit(this.dir, login.accountId, success ? 'login.completed' : 'login.failed', error ?? '')
     // A fresh sign-in starts clean; a limit that still applies is reported again by the next run.
     if (success) store.updateState(this.dir, login.accountId, (current) => void (current.lastError = null))
-    this.bus.emit({ type: 'accounts.login', accountId: login.accountId, loginId, success, error })
+    login.revision += 1
+    const status: AccountLoginSnapshot['status'] = success ? 'completed' : cancelled ? 'cancelled' : 'failed'
+    if (this.latestLogins.get(login.accountId)?.loginId === loginId) {
+      this.latestLogins.set(login.accountId, {
+        accountId: login.accountId,
+        loginId,
+        provider: login.provider,
+        method: login.method,
+        revision: login.revision,
+        status,
+        // A terminal result is enough to reconcile the client. In particular, do not retain a
+        // device code after the attempt ends.
+        events: [],
+        prompt: null,
+        success,
+        error
+      })
+    }
+    this.bus.emit({ type: 'accounts.login', accountId: login.accountId, loginId, revision: login.revision, success, error })
     try {
       void this.refreshOne(this.find(login.accountId)).catch(() => undefined)
     } catch {
@@ -379,12 +471,55 @@ export class Accounts {
     const account = this.find(accountId)
     if (!provider) throw invalid('Choose which Pi provider to sign in to.')
     store.audit(this.dir, account.id, 'login.started', `${method ?? 'oauth'} · ${provider}`)
-    const runtime = await this.runtime(account)
     const loginId = randomUUID()
     const controller = new AbortController()
-    const login: PendingLogin = { accountId: account.id, prompts: new Map(), cancel: () => controller.abort() }
+    const login: PendingLogin = {
+      accountId: account.id,
+      provider,
+      method: method === 'api_key' ? 'api_key' : 'oauth',
+      prompts: new Map(),
+      cancel: () => controller.abort(),
+      revision: 0,
+      events: [],
+      prompt: null
+    }
     this.logins.set(loginId, login)
-    const event = (payload: Record<string, unknown>): void => this.bus.emit({ type: 'accounts.loginEvent', accountId: account.id, loginId, event: payload })
+    this.latestLogins.set(account.id, {
+      accountId: account.id,
+      loginId,
+      provider: login.provider,
+      method: login.method,
+      revision: 0,
+      status: 'running',
+      events: [],
+      prompt: null,
+      success: null,
+      error: null
+    })
+    const event = (payload: Record<string, unknown>): void => {
+      login.revision += 1
+      if (payload.type === 'prompt') login.prompt = payload
+      else if (payload.type === 'promptClosed' && login.prompt?.promptId === payload.promptId) login.prompt = null
+      else {
+        login.events.push(payload)
+        if (login.events.length > 50) login.events.shift()
+      }
+      if (this.latestLogins.get(account.id)?.loginId === loginId) {
+        this.latestLogins.set(account.id, {
+          accountId: account.id,
+          loginId,
+          provider: login.provider,
+          method: login.method,
+          revision: login.revision,
+          status: 'running',
+          events: login.events.map((step) => ({ ...step })),
+          prompt: login.prompt ? { ...login.prompt } : null,
+          success: null,
+          error: null
+        })
+      }
+      this.bus.emit({ type: 'accounts.loginEvent', accountId: account.id, loginId, revision: login.revision, event: payload })
+    }
     const interaction = {
       signal: controller.signal,
       notify: (notification: Record<string, unknown>) => event(notification),
@@ -400,24 +535,53 @@ export class Accounts {
           event({ type: 'prompt', promptId, prompt: { type: prompt.type, message: prompt.message, placeholder: prompt.placeholder ?? null, options: prompt.options ?? null } })
         })
     }
-    runtime
-      .login(provider, method === 'api_key' ? 'api_key' : 'oauth', interaction as never)
+    void this.runtime(account)
+      .then(async (runtime) => {
+        if (login.method !== 'oauth') return runtime.login(provider, login.method, interaction as never)
+        const deviceId = await this.installationDeviceId()
+        return runtime.login(provider, login.method, interaction as never, { getDeviceId: () => deviceId })
+      })
       .then(() => this.finishLogin(loginId, true, null))
-      .catch((error: unknown) => this.finishLogin(loginId, false, controller.signal.aborted ? 'Sign-in was cancelled.' : error instanceof Error ? error.message : String(error)))
+      .catch((error: unknown) => this.finishLogin(
+        loginId,
+        false,
+        controller.signal.aborted ? 'Sign-in was cancelled.' : error instanceof Error ? error.message : String(error),
+        controller.signal.aborted
+      ))
     return { loginId }
   }
 
+  /** Current in-memory sign-in progress for one account; codes and prompts are never written to disk. */
+  loginStatus(accountId: string): AccountLoginSnapshot | null {
+    this.find(accountId)
+    const snapshot = this.latestLogins.get(accountId)
+    return snapshot ? structuredClone(snapshot) : null
+  }
+
   loginRespond(loginId: string, promptId: string, value: string | null): void {
     const login = this.logins.get(loginId)
     const prompt = login?.prompts.get(promptId)
     if (!login || !prompt) throw new HarnessError('not_found', 'That sign-in step is no longer waiting.')
     login.prompts.delete(promptId)
+    // The renderer's recoverable snapshot must stop presenting a prompt as soon as it is answered.
+    const current = this.latestLogins.get(login.accountId)
+    if (current?.loginId === loginId && current.prompt?.promptId === promptId) {
+      login.prompt = null
+      current.revision += 1
+      login.revision = current.revision
+      current.prompt = null
+      this.latestLogins.set(login.accountId, current)
+      this.bus.emit({ type: 'accounts.loginEvent', accountId: login.accountId, loginId, revision: current.revision, event: { type: 'promptClosed', promptId } })
+    }
     if (value === null) prompt.reject(new Error('Cancelled.'))
     else prompt.resolve(value)
   }
 
   loginCancel(accountId: string, loginId?: string | null): void {
-    if (loginId) this.logins.get(loginId)?.cancel()
+    if (loginId) {
+      const login = this.logins.get(loginId)
+      if (login?.accountId === accountId) login.cancel()
+    } else for (const login of this.logins.values()) if (login.accountId === accountId) login.cancel()
     store.audit(this.dir, accountId, 'login.cancelled', '')
   }
 
@@ -428,26 +592,49 @@ export class Accounts {
    * account's stored credentials are written there (mode 0600) while the terminal runs, then
    * read back and removed.
    */
+  /** How many terminal sessions are running on this account right now. */
+  terminalCount(accountId: string): number {
+    return this.terminals.get(accountId) ?? 0
+  }
+
+  /**
+   * Starts a terminal's use of the account's auth.json. The file is written from the store when the
+   * first terminal of the account begins. While another process's terminal still uses it, the tokens
+   * already in the file stay, because that terminal may have refreshed them; only a provider the file
+   * lacks is added from the store, so a key saved after the other terminal began still reaches this one.
+   */
   async terminalBegin(account: Account): Promise<void> {
     const count = (this.terminals.get(account.id) ?? 0) + 1
     this.terminals.set(account.id, count)
     if (count > 1) return
     const path = join(env.configDir(this.dir, account), 'auth.json')
+    let shared = false
     try {
-      const data: Record<string, unknown> = {}
-      for (const provider of store.loadState(this.dir, account.id).piProviders) {
-        const credential = await this.readCredential(account.id, provider).catch(() => null)
-        if (credential) data[provider] = credential
+      shared = this.otherTerminalProcesses(account.id)
+      this.claimLease(account.id)
+      const existing = shared && existsSync(path) ? readAuth(path) : null
+      const data = await this.storedCredentials(account.id, existing ?? {})
+      if (!existing || Object.keys(data).length > Object.keys(existing).length) {
+        atomicWrite(path, JSON.stringify(data, null, 2))
+        chmodSync(path, 0o600)
       }
-      atomicWrite(path, JSON.stringify(data, null, 2))
-      chmodSync(path, 0o600)
+      this.terminalSnapshots.set(account.id, data)
     } catch (error) {
       this.terminals.delete(account.id)
-      rmSync(path, { force: true })
+      this.terminalSnapshots.delete(account.id)
+      this.releaseLease(account.id)
+      if (!shared) rmSync(path, { force: true })
       throw error
     }
   }
 
+  /**
+   * Ends a terminal's use of the auth.json. Each terminal saves what its Pi changed since it began (a
+   * refreshed or new sign-in, or a provider it signed out of), even while another process still uses the
+   * file, so no refresh is lost when the other terminal ends first. A credential saved to the store after
+   * the terminal began is in neither the file nor the snapshot, so it stays. The last terminal of the
+   * account to end, in every process, removes the file.
+   */
   async terminalEnd(account: Account): Promise<void> {
     const remaining = Math.max(0, (this.terminals.get(account.id) ?? 1) - 1)
     if (remaining > 0) {
@@ -455,21 +642,72 @@ export class Accounts {
       return
     }
     this.terminals.delete(account.id)
+    const snapshot = this.terminalSnapshots.get(account.id) ?? {}
+    this.terminalSnapshots.delete(account.id)
+    this.releaseLease(account.id)
     const path = join(env.configDir(this.dir, account), 'auth.json')
-    let data: Record<string, Credential> | null = null
+    const data = readAuth(path)
+    if (data) {
+      let changed = false
+      for (const provider of new Set([...Object.keys(snapshot), ...Object.keys(data)])) {
+        if (provider in data) {
+          if (sameCredential(data[provider], snapshot[provider])) continue
+          await this.writeCredential(account.id, provider, data[provider]).catch(() => undefined)
+          changed = true
+        } else if (provider in snapshot) {
+          await this.writeCredential(account.id, provider, null).catch(() => undefined)
+          changed = true
+        }
+      }
+      if (changed) {
+        this.invalidate(account.id)
+        store.audit(this.dir, account.id, 'credentials.synced', 'Pi terminal sign-in saved to the Keychain.')
+      }
+    }
+    if (!this.otherTerminalProcesses(account.id)) rmSync(path, { force: true })
+  }
+
+  /** The account's stored credentials, with `existing` kept as it is for every provider it already has. */
+  private async storedCredentials(accountId: string, existing: Record<string, Credential>): Promise<Record<string, Credential>> {
+    const data = { ...existing }
+    for (const provider of store.loadState(this.dir, accountId).piProviders) {
+      if (provider in data) continue
+      const credential = await this.readCredential(accountId, provider).catch(() => null)
+      if (credential) data[provider] = credential
+    }
+    return data
+  }
+
+  /**
+   * Whether another live process has a terminal on this account. Lease files of processes that have
+   * ended are removed, so a crash never leaves the account looking busy.
+   */
+  private otherTerminalProcesses(accountId: string): boolean {
+    const folder = leaseFolder(this.dir, accountId)
+    let names: string[]
     try {
-      const parsed = readJson<Record<string, Credential>>(path)
-      data = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
+      names = readdirSync(folder)
     } catch {
-      data = null
+      return false
     }
-    if (data) {
-      for (const provider of store.loadState(this.dir, account.id).piProviders) if (!(provider in data)) await this.writeCredential(account.id, provider, null).catch(() => undefined)
-      for (const [provider, credential] of Object.entries(data)) await this.writeCredential(account.id, provider, credential).catch(() => undefined)
-      this.invalidate(account.id)
-      store.audit(this.dir, account.id, 'credentials.synced', 'Pi terminal sign-in saved to the Keychain.')
+    let others = false
+    for (const name of names) {
+      const pid = Number(name)
+      if (!/^\d+$/.test(name) || pid <= 0 || pid === process.pid) continue
+      if (processAlive(pid)) others = true
+      else rmSync(join(folder, name), { force: true })
     }
-    rmSync(path, { force: true })
+    return others
+  }
+
+  private claimLease(accountId: string): void {
+    const folder = leaseFolder(this.dir, accountId)
+    mkdirSync(folder, { recursive: true, mode: 0o700 })
+    atomicWrite(join(folder, String(process.pid)), JSON.stringify({ pid: process.pid, startedAt: now() }))
+  }
+
+  private releaseLease(accountId: string): void {
+    rmSync(join(leaseFolder(this.dir, accountId), String(process.pid)), { force: true })
   }
 
   // ---- Health from runs ---------------------------------------------------------------------

package/src/cli.ts

@@ -12,6 +12,7 @@ import { resolve } from 'node:path'
 import { log } from './core/bus'
 import { createHarness, type HarnessOptions } from './harness'
 import { runPluginsCli, terminalAsk } from './plugins/cli'
+import { runHubCli } from './hub/cli'
 import { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './server/remote'
 import { RpcPeer, stdioTransport } from './server/rpc'
 import { attach } from './server/serve'
@@ -19,16 +20,17 @@ import { runAppsCli, runWikiCli } from './terminal/cli'
 import { runStandaloneTerminal, standaloneArguments } from './terminal/standalone'
 
 const USAGE = `Usage: xingular-harness [--data <dir>] [--state <dir>]
-       xingular-harness <terminal | serve | wiki | mcp | plugins> [arguments]
+       xingular-harness <terminal | serve | wiki | mcp | plugins | hub> [arguments]
 
-  (no command)       Start the interactive Pi terminal
-  terminal           Start the interactive Pi terminal
+  (no command)       Start the interactive Harness terminal
+  terminal           Start the interactive Harness terminal
   serve --state <dir> [--data <dir>] [--name <product>] [--builtins <dir>]
         [--host-secrets] [--host-policy] [--host-tools] [--host-directory]
                      Serve the harness over newline-delimited JSON
   wiki <command>     Memory and Wiki commands for a terminal session
   mcp <command>      Connected-app commands for a terminal session
   plugins <command>  List, install, switch and trust plugins (plugins help)
+  hub <command>      Browse and install curated items (hub help)
 
 Standalone terminal options:
   --data <dir>       Data directory (default: ~/.xingular-harness/data)
@@ -91,6 +93,7 @@ function serveCommand(argv: string[]): Promise<number> {
 async function main(): Promise<number> {
   const argv = process.argv.slice(2)
   const [command, ...rest] = argv
+  if (command === 'terminal-frontend') return (await import('./terminal/tui/application')).runTerminalFrontend(rest)
   if (argv.includes('--help') || argv.includes('-h')) {
     process.stdout.write(USAGE)
     return 0
@@ -101,6 +104,7 @@ async function main(): Promise<number> {
   if (command === 'wiki') return runWikiCli(rest)
   if (command === 'mcp') return runAppsCli(rest)
   if (command === 'plugins') return runPluginsCli(rest, { ask: terminalAsk() })
+  if (command === 'hub') return runHubCli(rest)
   process.stdout.write(USAGE)
   return command ? 2 : 0
 }

package/src/core/bus.test.ts

@@ -0,0 +1,22 @@
+import { afterEach, expect, test, vi } from 'vitest'
+
+import { log, logLine, setLogSink } from './bus'
+
+afterEach(() => setLogSink(null))
+
+test('diagnostics go to the sink when one is set, and to stderr otherwise', () => {
+  const lines: string[] = []
+  setLogSink((text) => void lines.push(text))
+  log('maintenance', 'paused')
+  logLine('[index] reindex failed: boom')
+  expect(lines).toEqual(['[harness] maintenance paused', '[index] reindex failed: boom'])
+
+  setLogSink(null)
+  const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+  try {
+    logLine('plain')
+    expect(write).toHaveBeenCalledWith('plain\n')
+  } finally {
+    write.mockRestore()
+  }
+})

package/src/core/bus.ts

@@ -28,7 +28,22 @@ export class Bus {
   }
 }
 
-/** Diagnostics go to stderr; stdout may be carrying a protocol. */
+let logSink: ((text: string) => void) | null = null
+
+/**
+ * Sends diagnostics somewhere other than stderr, or back to stderr with `null`. A host whose stderr is
+ * the terminal a frontend is drawing on must not write into it, so it sets a sink.
+ */
+export function setLogSink(sink: ((text: string) => void) | null): void {
+  logSink = sink
+}
+
+/** One line of diagnostics. Diagnostics go to stderr by default; stdout may be carrying a protocol. */
+export function logLine(text: string): void {
+  if (logSink) logSink(text)
+  else process.stderr.write(`${text}\n`)
+}
+
 export function log(...parts: unknown[]): void {
-  process.stderr.write(`[harness] ${parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ')}\n`)
+  logLine(`[harness] ${parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ')}`)
 }

package/src/harness.ts

@@ -1,10 +1,12 @@
 // 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 { Subagents } from './sessions/subagentService'
 import { mkdirSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { Accounts } from './accounts/accounts'
+import { Hub, type HubOptions } from './hub/hub'
 import * as capabilities from './capabilities/api'
 import { ensureSharedDir, isolateProcess } from './accounts/env'
 import { fileSecretStore, type SecretStore } from './accounts/secrets'
@@ -15,6 +17,7 @@ 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'
@@ -41,6 +44,7 @@ import * as registry from './skills/registry'
 import { Terminals, type TerminalAssets } from './terminal/terminals'
 
 export interface HarnessOptions {
+  hub?: HubOptions
   /** 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. */
@@ -54,11 +58,16 @@ export interface HarnessOptions {
   /** 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 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. */
+  /** 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/`. */
   builtins?: string[]
@@ -69,6 +78,11 @@ export interface HarnessOptions {
   plugins?: PluginDescriptor[]
   /** Replaces Pi's own search for extensions, skills, prompts and themes, for tests. */
   resolver?: Resolver
+  /**
+   * The application's own registered OAuth clients, so a connector it publishes needs no client
+   * from the person. Only a catalog entry listed in `ids` can use one, and nothing is stored.
+   */
+  oauthClients?: AppOAuthClients
   /** Replaces how a plugin's hooks file is read as a module, for tests. */
   hookImporter?: (address: string) => Promise<unknown>
 }
@@ -102,6 +116,7 @@ class Env implements HarnessEnv {
 }
 
 export class Harness {
+  readonly hub: Hub
   readonly bus = new Bus()
   readonly env: Env
   readonly stateDir: string
@@ -116,6 +131,7 @@ export class Harness {
   /** 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 subagents: Subagents
   readonly sessions: Sessions
   readonly maintenance: Maintenance
   readonly terminals: Terminals
@@ -129,6 +145,7 @@ export class Harness {
     // 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.hub = new Hub(this, options.hub)
     this.policy = options.policy ?? {}
     registry.configureBuiltins(options.builtins ?? [])
     const secrets = options.secrets ?? fileSecretStore(join(this.stateDir, 'secrets.json'))
@@ -143,7 +160,7 @@ export class Harness {
       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.apps = new ConnectedApps({ env: this.env, stateDir: this.stateDir, secrets, bus: this.bus, runs: this.runs, policy: this.policy, oauthClients: options.oauthClients })
     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,
@@ -173,7 +190,9 @@ export class Harness {
       reloadTimer.unref?.()
     })
     this.describe(options.plugins ?? [])
+    this.subagents = new Subagents(this.env, this.runs, (input) => this.sessions.run(input))
     this.sessions = new Sessions({
+      subagents: this.subagents,
       env: this.env,
       accounts: this.accounts,
       runs: this.runs,
@@ -183,8 +202,8 @@ export class Harness {
       resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, 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.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.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)
@@ -193,6 +212,7 @@ 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)
     })
   }
@@ -215,8 +235,10 @@ export class Harness {
    * older Wiki is migrated.
    */
   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))
     void this.hooks.reload()
@@ -281,6 +303,7 @@ export class Harness {
 
   /** Stops live runs and releases the index. */
   async close(): Promise<void> {
+    this.hub.close()
     this.maintenance.stop()
     await this.terminals.close()
     await this.runs.interruptAll()