@xingular/harness 0.1.7 → 1.1.1

package/src/memory/maintenance.ts

@@ -1,518 +0,0 @@
-// The memory lifecycle. Imported sources and eligible settled runs become jobs; one job runs at
-// a time, so the Wiki has a single writer. A job asks the maintainer session for proposals,
-// checks every one against the evidence, applies the valid ones as one undoable operation, and
-// sends the rest to the Inbox. When no job arrives for a while, memory blocks that are close to
-// their limit are condensed.
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-
-import type { Accounts } from '../accounts/accounts'
-import { log, type Bus } from '../core/bus'
-import type { HarnessEnv } from '../core/env'
-import { newId, now, readJsonOr } from '../core/fs'
-import { findProject } from '../core/projects'
-import { charCount, takeChars } from '../core/text'
-import type { RunEvent } from '../sessions/contracts'
-import { findRun, readEvents } from '../sessions/runStore'
-import { evidenceText, transcript } from './api'
-import * as blocks from './blocks'
-import { callerBlocks, type CallerContext } from './caller'
-import * as facts from './facts'
-import { piMaintainerFactory, runMaintenance, type ExistingBlock, type ExistingMemory, type ExistingPage, type MaintainerFactory, type MaintenanceRequest } from './maintainer'
-import { inbox, undo } from './operations'
-import { accept, apply, captureHashes, describeTrigger, parseProposalSet, writeIndex, type Evidence, type Trigger } from './proposals'
-import { looksSecret } from './secrets'
-import { enqueueCuration, listCuration, curationJob, saveCuration, requireCurator, type CurationJob } from './curation'
-import * as registry from '../skills/registry'
-import * as attachments from '../plugins/attachments'
-import { parkPluginProposal, pluginProposalSchema } from '../plugins/proposal'
-import { registryProposalSchema } from './proposals'
-import { writeJson } from '../core/fs'
-import { invalid } from '../core/errors'
-import * as store from './store'
-import { namespaces, searchEntries } from './wiki'
-import { reindexQuietly } from './wikiIndex'
-
-export type Job = { kind: 'ingest'; namespace: string; sourceId: string } | { kind: 'run'; runId: string; namespace?: string } | { kind: 'consolidate'; blockIds: string[] } | { kind: 'review'; requestId?: string; manual?: boolean }
-
-const FULL_PAGES = 5
-const FULL_PAGE_LIMIT = 6000
-/** A block this full is condensed when nothing else is happening. */
-const NEAR_LIMIT_PERCENT = 90
-const IDLE_CHECK_MS = 600_000
-
-/** Conversations belong to no project, so only this setting can pause them. Absent means on. */
-export function chatUpdatesPaused(settings: unknown): boolean {
-  return (settings as { autoMaintenanceChat?: unknown } | null)?.autoMaintenanceChat === false
-}
-
-/** Where a settled run's knowledge is filed and what the job reads of it; throws the reason it is not eligible. */
-function runEvidence(root: string, runId: string): { namespace: string; transcript: string } {
-  const run = findRun(root, runId)
-  if (!run) throw new Error('Run was not found.')
-  const settings = readJsonOr<{ excludedSourceIds?: unknown } | null>(join(root, 'config/settings.json'), null)
-  if (Array.isArray(settings?.excludedSourceIds) && settings.excludedSourceIds.includes(runId)) throw new Error('run excluded in settings')
-  const projectId = run.mode === 'chat' || run.mode === 'code' ? run.projectId : null
-  let namespace: string
-  if (projectId) {
-    const project = findProject(root, projectId)
-    if (!project.autoMaintenance) throw new Error('automatic updates are paused for this project')
-    namespace = project.wikiNamespace
-  } else if (run.mode === 'chat') {
-    if (chatUpdatesPaused(settings)) throw new Error('automatic updates are paused for Chat')
-    namespace = store.LIBRARY_NAMESPACE
-  } else {
-    throw new Error('run has no project')
-  }
-  const text = transcript(run.goal ?? '', readEvents(root, runId))
-  if (!text.includes('Assistant:')) throw new Error('no recorded assistant output to use as evidence')
-  if (looksSecret(text)) throw new Error('the run contains text that looks like a credential')
-  return { namespace, transcript: text }
-}
-
-/**
- * The blocks attached to a run, which its consolidation may rewrite: an agent's blocks for its
- * own conversation, or the `user` block and the project's brief for a session in a project.
- */
-function runBlocks(env: HarnessEnv, runId: string): blocks.Block[] {
-  const run = findRun(env.root, runId)
-  if (!run) return []
-  const chat = run.mode === 'chat'
-  // What the session was told it is when it started, when that was recorded.
-  const recorded = readJsonOr<CallerContext | null>(join(env.root, 'runs', run.id, 'caller.json'), null)
-  const context: CallerContext = recorded ?? {
-    runId: run.id,
-    sessionId: run.sessionId,
-    projectId: run.projectId,
-    // A conversation's run names its agent; older records rely on the session being the agent's own.
-    agentId: chat ? (run.agentId ?? (env.directory.agentName(run.sessionId) !== null ? run.sessionId : null)) : null,
-    actor: chat ? 'Chat' : 'Code'
-  }
-  let attached: blocks.Block[]
-  try {
-    attached = callerBlocks(env, context).attached
-  } catch {
-    // A run with no single agent has only the shared user block attached.
-    attached = [blocks.ensureUser(store.wikiDir(env.root))]
-  }
-  return attached.filter((block) => !block.front.readOnly)
-}
-
-/**
- * What the job sees of the Wiki: the target namespace's pages, entries relevant to the
- * evidence from anywhere (the closest few in full), and the facts that apply.
- */
-function maintainerContext(root: string, namespace: string, evidence: string): { pages: ExistingPage[]; memories: ExistingMemory[] } {
-  const wiki = store.wikiDir(root)
-  const pages = store.loadPages(wiki)
-  const query = evidence.split(/\s+/).filter((word) => Buffer.byteLength(word) > 4).slice(0, 12).join(' ')
-  const ranked = searchEntries(root, query, { kinds: ['page'], limit: 30 }).map((hit) => hit.id)
-  const inFull = new Set(ranked.slice(0, FULL_PAGES))
-  const small = pages.filter((page) => page.location.namespace === namespace).length <= FULL_PAGES
-  return {
-    pages: pages
-      .filter((page) => page.location.namespace === namespace || ranked.includes(page.frontmatter.id))
-      .slice(0, 150)
-      .map((page) => ({
-        id: page.frontmatter.id,
-        title: page.frontmatter.title,
-        type: page.frontmatter.type,
-        path: page.location.path,
-        summary: store.firstParagraph(page.body),
-        // An update replaces the whole body, so the job must see what the page says now.
-        ...(inFull.has(page.frontmatter.id) || (page.location.namespace === namespace && small) ? { body: takeChars(page.body, FULL_PAGE_LIMIT) } : {})
-      })),
-    memories: facts
-      .loadMemories(wiki)
-      .filter((memory) => facts.appliesTo(memory.front, store.projectNamespaceOf(namespace)))
-      .slice(0, 60)
-      .map((memory) => ({ id: memory.front.id, title: memory.front.title, kind: memory.front.kind, namespace: memory.front.namespace, body: takeChars(memory.body, 300) }))
-  }
-}
-
-/** Blocks at or over `NEAR_LIMIT_PERCENT` of their limit that have not been tried in this state. */
-export function fullBlocks(wiki: string, tried: Set<string>): string[] {
-  return blocks
-    .loadAll(wiki)
-    .filter((block) => !block.front.readOnly && block.front.limit > 0 && charCount(block.body) * 100 >= block.front.limit * NEAR_LIMIT_PERCENT)
-    .filter((block) => {
-      const key = `${block.id}\u0000${store.currentRevision(wiki, block.id) ?? ''}`
-      return !tried.has(key) && Boolean(tried.add(key))
-    })
-    .map((block) => block.id)
-}
-
-const blockValues = (found: readonly blocks.Block[]): ExistingBlock[] => found.map((block) => ({ id: block.id, label: block.front.label, description: block.front.description, limit: block.front.limit, body: block.body }))
-
-export interface MaintenanceOptions {
-  env: HarnessEnv
-  bus: Bus
-  accounts: Accounts
-  factory?: MaintainerFactory
-  /** How long the queue stays empty before full blocks are condensed. */
-  idleMs?: number
-  external?: boolean
-  excludedTriggers?: string[]
-  /** False: a settled run queues no consolidation of its own. */
-  runTrigger?: boolean
-}
-
-export class Maintenance {
-  private chain: Promise<void> = Promise.resolve()
-  private idle: ReturnType<typeof setTimeout> | null = null
-  private readonly tried = new Set<string>()
-  private stopped = false
-
-  constructor(private readonly options: MaintenanceOptions) {}
-
-  /** Starts the idle check. Jobs can be queued whether or not it runs. */
-  start(): void {
-    this.stopped = false
-    if (this.options.external) {
-      for (const job of this.jobs().filter((job) => job.status === 'running')) {
-        job.status = 'failed'
-        job.reason = 'The previous process stopped before this request settled. Retry it explicitly.'
-        saveCuration(this.options.env.root, job)
-      }
-    }
-    this.rest()
-  }
-
-  stop(): void {
-    this.stopped = true
-    if (this.idle) clearTimeout(this.idle)
-    this.idle = null
-  }
-
-  /** Resolves when every queued job has finished. */
-  settled(): Promise<void> {
-    return this.chain
-  }
-
-  private rest(): void {
-    if (this.idle) clearTimeout(this.idle)
-    if (this.stopped) return
-    this.idle = setTimeout(() => {
-      try {
-        const blockIds = fullBlocks(store.wikiDir(this.options.env.root), this.tried)
-        if (blockIds.length) this.enqueue({ kind: 'consolidate', blockIds })
-        else this.rest()
-      } catch {
-        this.rest()
-      }
-    }, this.options.idleMs ?? IDLE_CHECK_MS)
-    this.idle.unref?.()
-  }
-
-  enqueue(job: Job): void {
-    if (this.idle) clearTimeout(this.idle)
-    if (this.options.external) {
-      if (job.kind === 'run') {
-        try { runEvidence(this.options.env.root, job.runId) } catch (error) { log('maintenance source skipped', error instanceof Error ? error.message : String(error)); return }
-        const run = findRun(this.options.env.root, job.runId)
-        const namespace = run?.projectId ? findProject(this.options.env.root, run.projectId).wikiNamespace : store.LIBRARY_NAMESPACE
-        enqueueCuration(this.options.env.root, { ...job, namespace })
-      } else enqueueCuration(this.options.env.root, job)
-      this.options.bus.emit({ type: 'maintenance.queued' })
-      this.rest()
-      return
-    }
-    this.chain = this.chain
-      .then(() => this.process(job))
-      .catch((error) => log('maintenance', error instanceof Error ? error.message : String(error)))
-      .then(() => this.rest())
-  }
-
-  /** A settled run is evidence; whether it is eligible is decided when its job runs. */
-  onRunEvent(event: RunEvent): void {
-    if (this.options.runTrigger === false) return
-    const caller = readJsonOr<CallerContext | null>(join(this.options.env.root, 'runs', event.runId, 'caller.json'), null)
-    if (caller?.vaultAccess === 'curator' || this.options.excludedTriggers?.includes(findRun(this.options.env.root, event.runId)?.trigger ?? '')) return
-    if (event.type === 'completed') this.enqueue({ kind: 'run', runId: event.runId })
-  }
-
-  jobs(): CurationJob[] { return listCuration(this.options.env.root) }
-
-  claim(context: CallerContext, id: string, prepare = true): CurationJob {
-    requireCurator(context)
-    const root = this.options.env.root
-    const job = curationJob(root, id)
-    if (job.status === 'completed' || job.status === 'rejected' || job.status === 'needs_user') return job
-    if (context.maintenanceJobIds !== undefined && !context.maintenanceJobIds.includes(id) && !('caller' in job.input && job.input.caller.runId === context.runId)) throw invalid('This request is not assigned to this run.')
-    if (job.runId && job.runId !== context.runId && job.status === 'running') throw invalid('Another run owns this request.')
-    job.runId = context.runId!
-    if (prepare && job.input.kind !== 'proposal' && job.input.kind !== 'registry' && job.input.kind !== 'plugin' && !job.prepared) {
-      let prepared: ReturnType<Maintenance['prepare']>
-      try { prepared = this.prepare(job.input) } catch (error) { job.status = 'failed'; job.reason = error instanceof Error ? error.message : String(error); saveCuration(root, job); throw error }
-      job.prepared = { request: prepared.request, evidence: prepared.evidence, namespace: prepared.namespace, trigger: prepared.trigger }
-      job.hashes = [...prepared.captured]
-      if (job.prepared.evidence.sourceText) job.prepared.evidence.sourceText = takeChars(job.prepared.evidence.sourceText, 60_000)
-    }
-    if (prepare && job.input.kind === 'proposal' && !job.prepared) {
-      const input = job.input
-      const origin = input.caller.runId
-      const attached = input.proposals.blocks.map((proposal) => blocks.find(store.wikiDir(root), proposal.block))
-      const evidence = origin && input.caller.vaultAccess !== 'curator' ? evidenceText(root, origin) : ''
-      const context = maintainerContext(root, input.namespace, evidence)
-      job.prepared = { request: { jobId: job.id, namespace: input.namespace, trigger: { kind: 'run', runId: origin ?? '', transcript: takeChars(evidence, 24_000) }, pages: context.pages, memories: context.memories, blocks: blockValues(attached), index: '' }, evidence: { runText: evidence, blocks: attached.map((block) => block.id) }, namespace: input.namespace, trigger: { kind: 'agent', runId: origin ?? null, actor: 'Curator' } }
-    }
-    job.status = 'running'
-    job.runId = context.runId!
-    return saveCuration(root, job)
-  }
-
-  readJob(context: CallerContext, id: string): unknown {
-    const job = this.claim(context, id)
-    return { id: job.id, status: job.status, input: job.input, context: job.prepared?.request ?? null, receipt: job.receipt }
-  }
-
-  decide(context: CallerContext, id: string, decision: 'reject' | 'needs_user', reason: string): CurationJob {
-    if (!reason.trim()) throw invalid('Explain the decision.')
-    const job = this.claim(context, id, false)
-    if (job.status === 'completed' || job.status === 'rejected' || job.status === 'needs_user') return job
-    job.status = decision === 'reject' ? 'rejected' : 'needs_user'
-    job.reason = reason.trim()
-    job.receipt = { operationId: null, notes: [job.reason], parked: decision === 'needs_user' ? 1 : 0, flagged: 0 }
-    if (decision === 'needs_user') {
-      const input = job.input
-      if (input.kind === 'registry') {
-        const proposal = input.proposal
-        inbox(store.wikiDir(this.options.env.root), 'proposed', `Review ${proposal.kind}: ${proposal.name}`, reason, [], null, { kind: proposal.kind, proposal, curationJobId: id })
-      } else if (input.kind === 'plugin') parkPluginProposal(store.wikiDir(this.options.env.root), `Curated request ${id}`, pluginProposalSchema.parse(input.proposal))
-      else inbox(store.wikiDir(this.options.env.root), 'unresolved', 'Maintenance needs your decision', reason, [])
-    }
-    this.options.bus.emit({ type: 'wiki.changed' })
-    return saveCuration(this.options.env.root, job)
-  }
-
-  applyJob(context: CallerContext, id: string, replacement?: unknown, reason = '', scope?: attachments.AttachScope): CurationJob {
-    if (!reason.trim()) throw invalid('Explain why this change should be applied.')
-    const root = this.options.env.root
-    const wiki = store.wikiDir(root)
-    const job = this.claim(context, id)
-    if (job.status === 'completed' || job.status === 'rejected' || job.status === 'needs_user') return job
-    const committed = readJsonOr<{ id: string } | null>(join(wiki, 'operations', `${job.id}.json`), null)
-    if (committed) {
-      job.status = 'completed'
-      job.receipt = { operationId: committed.id, notes: ['This request was already committed.'], parked: 0, flagged: 0 }
-      return saveCuration(root, job)
-    }
-    const input = job.input
-    if (input.kind === 'plugin') return this.decide(context, id, 'needs_user', reason || 'Plugin files require user review before activation; executable code also needs explicit trust.')
-    if (input.kind === 'registry') {
-      const proposal = registryProposalSchema.parse(input.proposal)
-      const itemId = `${proposal.kind}s/${store.slug(proposal.name)}`
-      if (!['skill', 'prompt', 'rule'].includes(proposal.kind) || !proposal.name.trim() || !proposal.body.trim() || looksSecret(proposal.body)) throw invalid('Invalid text resource proposal.')
-      const existing = registry.list(root).find((item) => item.id === itemId)
-      const current = captureHashes(wiki).get(itemId)
-      if (existing?.builtin || current !== new Map(job.hashes).get(itemId)) return this.decide(context, id, 'needs_user', 'The resource is built-in or changed since it was proposed. Review the current version.')
-      const target = scope ?? { agentId: input.caller.agentId ?? context.agentId }
-      if (target.agentId && target.projectId) throw invalid('Choose one attachment scope.')
-      if (target.agentId && target.agentId !== context.agentId && target.agentId !== input.caller.agentId && !this.options.env.directory.agentName(target.agentId)) throw invalid('Unknown attachment target.')
-      if (target.projectId) findProject(root, target.projectId)
-      const before = existing ? store.snapshot(wiki, itemId, readFileSync(existing.path, 'utf8'), 'Curator', `Before ${id}`).id : null
-      const beforeChoices = attachments.load(root)
-      registry.writeItem(root, proposal.kind, proposal.name, proposal.description, proposal.body, `Curated request ${id}: ${reason || proposal.reason}`, context.agentName ?? 'Curator')
-      const saved = registry.list(root).find((item) => item.id === itemId)!
-      const after = store.currentRevision(wiki, itemId)!
-      const choices = attachments.load(root)
-      attachments.set(choices, [itemId], target, true, false)
-      attachments.save(root, choices)
-      writeJson(join(wiki, 'operations', `${id}.json`), { id, createdAt: now(), trigger: `Curated request ${id}`, pages: [{ pageId: itemId, path: saved.path, beforeRevisionId: before, afterRevisionId: after }], undone: false, protected: true, attachmentsBefore: beforeChoices, attachmentsAfter: choices })
-      job.receipt = { operationId: id, notes: [`Saved ${itemId}; enabled for ${target.agentId ?? target.projectId ?? 'everyone'}. ${reason || proposal.reason}`], parked: 0, flagged: 0 }
-      this.options.bus.emit({ type: 'plugins.changed' })
-    } else {
-      const prepared = job.prepared
-      const proposalInput = input.kind === 'proposal' ? input : null
-      const proposals = parseProposalSet(replacement ?? proposalInput?.proposals)
-      const origin = proposalInput?.caller.runId ?? null
-      const trigger: Trigger = prepared?.trigger ?? { kind: 'agent', runId: origin, actor: context.agentName ?? 'Curator' }
-      const evidence: Evidence = input.kind === 'proposal' ? (prepared?.evidence ?? {}) : this.prepare(input).evidence
-      const originEvidence: Evidence = prepared?.evidence ?? { runText: origin ? evidenceText(root, origin) : null, blocks: proposals.blocks.map((block) => block.block) }
-      {
-        if (input.kind === 'proposal') Object.assign(evidence, originEvidence)
-        evidence.runs = {}
-        evidence.sources = {}
-        const refs = [...proposals.pages, ...proposals.memories, ...proposals.blocks].flatMap(proposal => proposal.sourceRefs).slice(0, 20)
-        for (const ref of refs) {
-          if (ref.kind === 'run' && findRun(root, ref.ref) && readJsonOr<CallerContext | null>(join(root, 'runs', ref.ref, 'caller.json'), null)?.vaultAccess !== 'curator') {
-            const excluded = readJsonOr<{ excludedSourceIds?: string[] }>(join(root, 'config/settings.json'), {}).excludedSourceIds ?? []
-            const text = evidenceText(root, ref.ref)
-            if (!excluded.includes(ref.ref) && !looksSecret(text)) evidence.runs[ref.ref] = takeChars(text, 60_000)
-          }
-          if (ref.kind === 'source') {
-            const source = store.listSources(wiki).find(source => source.id === ref.ref)
-            if (source) {
-              const text = readFileSync(join(wiki, 'raw', source.id, source.name), 'utf8')
-              if (!looksSecret(text)) evidence.sources[ref.ref] = takeChars(text, 60_000)
-            }
-          }
-        }
-      }
-      const outcome = apply(wiki, prepared?.namespace ?? proposalInput?.namespace ?? store.LIBRARY_NAMESPACE, trigger, proposals, new Map(job.hashes), evidence, id, context.agentName ?? 'Curator')
-      if (outcome.operation) writeJson(join(wiki, 'operations', `${outcome.operation.id}.json`), { ...outcome.operation, protected: true })
-      job.receipt = { operationId: outcome.operation?.id ?? null, notes: outcome.notes, parked: outcome.parked, flagged: outcome.flagged }
-    }
-    job.status = job.receipt.parked ? 'needs_user' : 'completed'
-    job.reason = reason
-    reindexQuietly(root)
-    this.options.bus.emit({ type: 'wiki.changed' })
-    return saveCuration(root, job)
-  }
-
-  finishRun(runId: string, failed: boolean): void {
-    for (const job of this.jobs().filter((job) => job.runId === runId && job.status === 'running')) {
-      job.status = failed ? 'failed' : 'completed'
-      job.reason = failed ? 'The run stopped before completing this request. Retry it explicitly.' : 'The review completed without applying a change.'
-      job.receipt ??= { operationId: null, notes: [job.reason], parked: 0, flagged: 0 }
-      saveCuration(this.options.env.root, job)
-    }
-  }
-
-  retry(id: string): CurationJob {
-    const job = curationJob(this.options.env.root, id)
-    if (job.status !== 'failed') throw invalid('Only a failed request can be retried.')
-    return saveCuration(this.options.env.root, { ...job, status: 'queued', runId: null, reason: '', receipt: null })
-  }
-
-  prepare(job: Job): { request: MaintenanceRequest; evidence: Evidence; captured: Map<string, string>; namespace: string; trigger: Trigger } {
-    const { env } = this.options
-    const root = env.root
-    const wiki = store.wikiDir(root)
-    const evidence: Evidence = {}
-    let attached: blocks.Block[] = []
-    let namespace: string
-    let trigger: Trigger
-    let request: MaintenanceRequest['trigger']
-    let shown = ''
-    if (job.kind === 'ingest') {
-      const directory = join(wiki, 'raw', job.sourceId)
-      const name = readJsonOr<{ name?: unknown } | null>(join(directory, 'meta.json'), null)?.name
-      const sourceName = typeof name === 'string' ? name : 'source'
-      let text: string | null = null
-      try {
-        text = new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(join(directory, sourceName)))
-      } catch {
-        text = null
-      }
-      if (text === null) {
-        throw invalid('Only text sources can be synthesized automatically right now.')
-      }
-      shown = takeChars(text, 60_000)
-      evidence.sourceText = text
-      namespace = job.namespace
-      trigger = { kind: 'ingest', sourceId: job.sourceId, sourceName }
-      request = { kind: 'ingest', sourceId: job.sourceId, sourceName, text: shown }
-    } else if (job.kind === 'run') {
-      let found: ReturnType<typeof runEvidence>
-      try {
-        found = runEvidence(root, job.runId)
-      } catch (error) {
-        throw error
-      }
-      evidence.runText = evidenceText(root, job.runId)
-      attached = runBlocks(env, job.runId)
-      shown = found.transcript
-      namespace = found.namespace
-      trigger = { kind: 'run', runId: job.runId }
-      request = { kind: 'run', runId: job.runId, transcript: shown }
-    } else {
-      attached = (job.kind === 'review' ? blocks.loadAll(wiki).filter((block) => !block.front.readOnly).sort((a, b) => charCount(b.body) / b.front.limit - charCount(a.body) / a.front.limit).slice(0, 30).map((block) => block.id) : job.blockIds).flatMap((id) => {
-        try {
-          const block = blocks.find(wiki, id)
-          return block.front.readOnly ? [] : [block]
-        } catch {
-          return []
-        }
-      })
-      if (!attached.length && job.kind !== 'review') throw invalid('No writable blocks remain in this job.')
-      namespace = store.LIBRARY_NAMESPACE
-      trigger = { kind: 'consolidate' }
-      request = { kind: 'consolidate' }
-    }
-    evidence.blocks = attached.map((block) => block.id)
-    const captured = captureHashes(wiki)
-    const context = trigger.kind === 'consolidate' ? { pages: [], memories: [] } : maintainerContext(root, namespace, shown)
-    let index = ''
-    try {
-      index = takeChars(readFileSync(join(wiki, 'index.md'), 'utf8'), 8000)
-    } catch {
-      index = ''
-    }
-    return { request: { jobId: '', namespace, trigger: request, pages: context.pages, memories: context.memories, blocks: blockValues(attached), namespaces: namespaces(root), index }, evidence, captured, namespace, trigger }
-  }
-
-  private async process(job: Job): Promise<void> {
-    const { env, bus } = this.options
-    const root = env.root
-    const wiki = store.wikiDir(root)
-    let prepared: ReturnType<Maintenance['prepare']>
-    try { prepared = this.prepare(job) } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      if (job.kind === 'run') log(`maintenance skipped run ${job.runId}: ${message}`)
-      else if (job.kind === 'ingest') { inbox(wiki, 'unresolved', 'Source was imported but not summarized', message, []); bus.emit({ type: 'wiki.changed' }) }
-      return
-    }
-    const { namespace, trigger, evidence, captured } = prepared
-    const described = describeTrigger(trigger)
-    try {
-      // The job runs on the default account.
-      const account = this.options.accounts.context(this.options.accounts.resolve())
-      const proposed = await runMaintenance(
-        { ...prepared.request, jobId: newId() },
-        { cwd: wiki, product: env.productName, account, runtime: () => this.options.accounts.runtime(account) },
-        this.options.factory ?? piMaintainerFactory
-      )
-      const outcome = apply(wiki, namespace, trigger, parseProposalSet(proposed), captured, evidence)
-      reindexQuietly(root)
-      if (outcome.operation) {
-        const count = outcome.operation.pages.length
-        bus.emit({ type: 'wiki.maintenance', namespace, title: `Wiki updated ${count} entr${count === 1 ? 'y' : 'ies'}`, detail: `From ${described}. ${outcome.parked} parked, ${outcome.flagged} flagged for review.` })
-      }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      try {
-        inbox(wiki, 'blocked', `Consolidation for ${described} did not finish`, message, [])
-        store.log(wiki, `- ${now()} · Sleep-time · ${described} · failed: ${message}`)
-      } catch {
-        // The failure is still logged by the queue.
-      }
-    }
-    bus.emit({ type: 'wiki.changed' })
-  }
-
-  // ---- What a person does from the Inbox -------------------------------------------------------
-
-  /** Reverts an applied operation through new revisions. */
-  undoOperation(operationId: string): void {
-    const { root } = this.options.env
-    const wiki = store.wikiDir(root)
-    const operation = undo(wiki, operationId)
-    writeIndex(wiki)
-    const count = operation.pages.length
-    inbox(wiki, 'applied', `Undid an update to ${count} entr${count === 1 ? 'y' : 'ies'}`, "Earlier content was restored as new revisions; created entries moved to the Wiki's trash folder.", operation.pages.map((page) => page.pageId))
-    reindexQuietly(root)
-    this.options.bus.emit({ type: 'wiki.changed' })
-  }
-
-  /** Accepts a parked proposal with the user as the authority. */
-  acceptInboxItem(itemId: string): string {
-    const { root } = this.options.env
-    const message = accept(root, itemId)
-    reindexQuietly(root)
-    this.options.bus.emit({ type: 'wiki.changed' })
-    return message
-  }
-
-  /** Imports a file as an immutable source and queues the job that reads it. */
-  ingest(name: string, bytes: Uint8Array, namespace: string = store.LIBRARY_NAMESPACE): store.WikiSource {
-    const { root } = this.options.env
-    const wiki = store.wikiDir(root)
-    store.namespaceDir(wiki, namespace)
-    const source = store.importSource(wiki, name.replace(/[/\\]/g, '_'), bytes)
-    reindexQuietly(root)
-    this.enqueue({ kind: 'ingest', namespace, sourceId: source.id })
-    return source
-  }
-}
-

package/src/memory/migrate.ts

@@ -1,79 +0,0 @@
-// Storage migration to version 3: memory blocks, facts, and the Library.
-//
-// Version 3 starts from an empty Wiki. Whatever came before is kept whole as a backup and is
-// not carried over: a version 2 `wiki/` becomes `wiki.pre-v3/`, and a version 1 `knowledge/`
-// becomes `knowledge.pre-v2/`. The new tree is staged in `wiki.migrating/` before anything is
-// renamed; on failure the staged tree is removed and the earlier Wiki is left in place.
-import { existsSync, renameSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
-
-import type { HarnessEnv } from '../core/env'
-import { HarnessError } from '../core/errors'
-import { now, readJsonOr, writeJson } from '../core/fs'
-import { listProjects } from '../core/projects'
-import * as registry from '../skills/registry'
-import * as blocks from './blocks'
-import { writeIndex } from './proposals'
-import * as store from './store'
-
-export const WIKI_VERSION = 3
-
-const storagePath = (root: string): string => join(root, 'config/storage.json')
-
-export function version(root: string): number {
-  const stored = readJsonOr<{ wikiVersion?: unknown } | null>(storagePath(root), null)?.wikiVersion
-  if (typeof stored === 'number' && Number.isInteger(stored) && stored >= 0) return stored
-  const wiki = store.wikiDir(root)
-  if (store.isDir(join(root, 'knowledge'))) return 1
-  // A version 2 Wiki whose marker is missing still has its old folders and no blocks.
-  if (!existsSync(join(wiki, 'blocks')) && (store.isDir(join(wiki, 'docs')) || store.isDir(join(wiki, 'memory')))) return 2
-  return WIKI_VERSION
-}
-
-const stamp = (): string => now().replace(/[:.]/g, '-')
-
-/** Moves `from` to `<name>` beside it, or `<name>-<time>` when that backup already exists. */
-function backUp(root: string, from: string, name: string): void {
-  if (!existsSync(from)) return
-  renameSync(from, existsSync(join(root, name)) ? join(root, `${name}-${stamp()}`) : join(root, name))
-}
-
-/**
- * Brings a data root to the current Wiki layout. Safe to call on every start. `agentIds` are
- * the agents that get their own blocks. Returns whether a migration happened.
- */
-export function run(env: HarnessEnv, agentIds: readonly string[] = []): boolean {
-  const { root } = env
-  if (version(root) >= WIKI_VERSION) return false
-  const failed = (detail: string): HarnessError => new HarnessError('migration_failed', `The Wiki was not migrated to version 3; your Wiki is unchanged. ${detail}`)
-  const staging = join(root, 'wiki.migrating')
-  rmSync(staging, { recursive: true, force: true })
-  try {
-    store.ensureLayoutAt(staging, env.productName)
-    blocks.ensureUser(staging)
-    for (const agentId of agentIds) blocks.ensureAgent(staging, agentId)
-    for (const project of listProjects(root)) blocks.ensureProject(staging, project.slug, project.name)
-    store.log(staging, `- ${now()} · ${env.productName} · started storage version 3; the earlier Wiki is kept as a backup beside it`)
-    backUp(root, store.wikiDir(root), 'wiki.pre-v3')
-  } catch (error) {
-    rmSync(staging, { recursive: true, force: true })
-    throw failed(error instanceof Error ? error.message : String(error))
-  }
-  renameSync(staging, store.wikiDir(root))
-  backUp(root, join(root, 'knowledge'), 'knowledge.pre-v2')
-
-  store.ensureLayout(root, env.productName)
-  for (const project of listProjects(root)) store.ensureProjectNamespace(root, project.slug, project.name)
-  // Registry items that version 1 enabled for personal agents are enabled for everyone.
-  const enablement = registry.enablement(root)
-  if ('personal' in enablement) {
-    const ids = registry.enablementIds(enablement, registry.GLOBAL_KEY)
-    for (const id of registry.enablementIds(enablement, 'personal')) if (!ids.includes(id)) ids.push(id)
-    delete enablement.personal
-    enablement[registry.GLOBAL_KEY] = ids
-    writeJson(join(root, 'config/registry-enabled.json'), enablement)
-  }
-  writeIndex(store.wikiDir(root))
-  writeJson(storagePath(root), { wikiVersion: WIKI_VERSION, migratedAt: now() })
-  return true
-}