@xingular/harness 0.1.6 → 2.0.0

package/src/memory/maintenance.ts

@@ -5,6 +5,7 @@
 // their limit are condensed.
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { createHash } from 'node:crypto'
 
 import type { Accounts } from '../accounts/accounts'
 import { log, type Bus } from '../core/bus'
@@ -20,13 +21,20 @@ 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 { accept, apply, captureHashes, describeTrigger, parseProposalSet, writeIndex, type Evidence, type ProposalSet, type SourceRef, 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 } | { kind: 'consolidate'; blockIds: string[] }
+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
@@ -39,27 +47,30 @@ export function chatUpdatesPaused(settings: unknown): boolean {
   return (settings as { autoMaintenanceChat?: unknown } | null)?.autoMaintenanceChat === false
 }
 
+/** A run that automatic maintenance leaves alone for a settled reason: a setting, a pause, or no project. Not an error. */
+class NotEligible extends Error {}
+
 /** 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')
+  if (Array.isArray(settings?.excludedSourceIds) && settings.excludedSourceIds.includes(runId)) throw new NotEligible('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')
+    if (!project.autoMaintenance) throw new NotEligible('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')
+    if (chatUpdatesPaused(settings)) throw new NotEligible('automatic updates are paused for Chat')
     namespace = store.LIBRARY_NAMESPACE
   } else {
-    throw new Error('run has no project')
+    throw new NotEligible('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')
+  if (!text.includes('Assistant:')) throw new NotEligible('no recorded assistant output to use as evidence')
+  if (looksSecret(text)) throw new NotEligible('the run contains text that looks like a credential')
   return { namespace, transcript: text }
 }
 
@@ -137,6 +148,12 @@ export function fullBlocks(wiki: string, tried: Set<string>): string[] {
 
 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 MaintenanceBatchDecision {
+  id: string
+  decision: 'apply' | 'reject' | 'needs_user'
+  reason: string
+}
+
 export interface MaintenanceOptions {
   env: HarnessEnv
   bus: Bus
@@ -144,6 +161,10 @@ export interface MaintenanceOptions {
   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 {
@@ -157,6 +178,13 @@ export class Maintenance {
   /** 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()
   }
 
@@ -188,6 +216,22 @@ export class Maintenance {
 
   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) {
+          if (!(error instanceof NotEligible)) 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)))
@@ -196,11 +240,302 @@ export class Maintenance {
 
   /** 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 })
   }
 
-  private async process(job: Job): Promise<void> {
-    const { env, bus } = this.options
+  jobs(): CurationJob[] { return listCuration(this.options.env.root) }
+
+  /** Reads every request frozen into the current host-assigned review batch. */
+  readBatch(context: CallerContext): { jobs: unknown[] } {
+    requireCurator(context)
+    const ids = context.maintenanceJobIds ?? (context.maintenanceJobId ? [context.maintenanceJobId] : [])
+    return {
+      jobs: ids.map((id) => {
+        try {
+          return this.readJob(context, id)
+        } catch (error) {
+          return { id, status: 'failed', error: error instanceof Error ? error.message : String(error) }
+        }
+      })
+    }
+  }
+
+  /** Applies one evidence-checked Wiki change set for all accepted Wiki requests in a batch. */
+  applyBatch(context: CallerContext, decisions: readonly MaintenanceBatchDecision[], replacement: unknown): { operationId: string | null; jobs: CurationJob[] } {
+    requireCurator(context)
+    if (!decisions.length) throw invalid('Decide every assigned request in the batch.')
+    const ids = decisions.map((decision) => decision.id)
+    if (new Set(ids).size !== ids.length) throw invalid('Each request can appear only once in a batch decision.')
+    const assigned = context.maintenanceJobIds ?? (context.maintenanceJobId ? [context.maintenanceJobId] : [])
+    const pending = assigned.map((id) => curationJob(this.options.env.root, id)).filter((job) => !['completed', 'rejected', 'needs_user'].includes(job.status))
+    if (pending.some((job) => !ids.includes(job.id))) throw invalid('Decide every assigned request in one batch.')
+
+    const entries = decisions.map((decision) => {
+      if (!decision.reason.trim()) throw invalid('Explain every batch decision.')
+      if (!['apply', 'reject', 'needs_user'].includes(decision.decision)) throw invalid('Choose apply, reject, or needs_user for every request.')
+      const job = curationJob(this.options.env.root, decision.id)
+      if (context.maintenanceJobIds !== undefined && !context.maintenanceJobIds.includes(decision.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.')
+      return { decision, job }
+    })
+    const wikiEntries = entries.filter(({ decision, job }) => decision.decision === 'apply' && !['registry', 'plugin'].includes(job.input.kind) && !['completed', 'rejected', 'needs_user'].includes(job.status))
+    if (wikiEntries.length && replacement === undefined) throw invalid('Provide one combined, evidence-backed Wiki change set for the approved requests.')
+    const proposals: ProposalSet | null = wikiEntries.length ? parseProposalSet(replacement) : null
+    const operationId = wikiEntries.length ? `batch-${createHash('sha256').update(wikiEntries.map(({ job }) => job.id).sort().join('\0')).digest('hex').slice(0, 32)}` : null
+    const results = new Map<string, CurationJob>()
+
+    if (wikiEntries.length) {
+      const prepared = wikiEntries.map(({ job }) => this.claim(context, job.id))
+      const root = this.options.env.root
+      const wiki = store.wikiDir(root)
+      const evidence: Evidence = { runs: {}, sources: {}, blocks: [] }
+      const blocksSeen = new Set<string>()
+      const captured = new Map<string, string>()
+      const conflicts = new Set<string>()
+      for (const job of prepared) {
+        const input = job.input
+        for (const id of job.prepared?.evidence.blocks ?? (input.kind === 'proposal' ? input.proposals.blocks.map((proposal) => proposal.block) : [])) blocksSeen.add(id)
+        for (const [id, hash] of job.hashes) {
+          const previous = captured.get(id)
+          if (previous !== undefined && previous !== hash) conflicts.add(id)
+          else captured.set(id, hash)
+        }
+      }
+      for (const id of conflicts) captured.set(id, `conflicting-batch-snapshot:${id}`)
+      evidence.blocks = [...blocksSeen]
+
+      const refs: SourceRef[] = [...proposals!.pages, ...proposals!.memories, ...proposals!.blocks].flatMap((proposal) => proposal.sourceRefs)
+      const excluded = readJsonOr<{ excludedSourceIds?: unknown } | null>(join(root, 'config/settings.json'), null)?.excludedSourceIds
+      const excludedIds = Array.isArray(excluded) ? excluded.filter((id): id is string => typeof id === 'string') : []
+      for (const ref of refs) {
+        if (ref.kind === 'run' && findRun(root, ref.ref)) {
+          const caller = readJsonOr<CallerContext | null>(join(root, 'runs', ref.ref, 'caller.json'), null)
+          if (!excludedIds.includes(ref.ref) && caller?.vaultAccess !== 'curator') {
+            const text = evidenceText(root, ref.ref)
+            if (!looksSecret(text)) evidence.runs![ref.ref] = takeChars(text, 60_000)
+          }
+        }
+        if (ref.kind === 'source') {
+          const source = store.listSources(wiki).find((item) => item.id === ref.ref)
+          if (source) {
+            try {
+              const text = readFileSync(join(wiki, 'raw', source.id, source.name), 'utf8')
+              if (!looksSecret(text)) evidence.sources![ref.ref] = takeChars(text, 60_000)
+            } catch {
+              // Missing or unreadable evidence is rejected by the proposal validator.
+            }
+          }
+        }
+      }
+
+      const namespaceFor = (sourceRefs: readonly SourceRef[]): string => {
+        for (const ref of sourceRefs) {
+          const sourceJob = prepared.find((job) => {
+            if (job.input.kind === 'proposal') return job.input.caller.runId === ref.ref
+            if (job.input.kind === 'run') return job.input.runId === ref.ref
+            if (job.input.kind === 'ingest') return job.input.sourceId === ref.ref
+            return false
+          })
+          const namespace = sourceJob?.prepared?.namespace ?? (sourceJob?.input.kind === 'proposal' ? sourceJob.input.namespace : undefined)
+          if (namespace) return namespace
+        }
+        return prepared[0]?.prepared?.namespace ?? (prepared[0]?.input.kind === 'proposal' ? prepared[0].input.namespace : undefined) ?? store.LIBRARY_NAMESPACE
+      }
+      const batchProposals: ProposalSet = {
+        ...proposals!,
+        pages: proposals!.pages.map((proposal) => ({ ...proposal, namespace: proposal.namespace ?? namespaceFor(proposal.sourceRefs) })),
+        memories: proposals!.memories.map((proposal) => ({ ...proposal, namespace: proposal.namespace ?? namespaceFor(proposal.sourceRefs) }))
+      }
+      const trigger: Trigger = prepared.some((job) => job.input.kind === 'consolidate')
+        ? { kind: 'consolidate' }
+        : prepared.some((job) => job.input.kind === 'run')
+          ? { kind: 'run', runId: (prepared.find((job) => job.input.kind === 'run')!.input as Extract<Job, { kind: 'run' }>).runId }
+          : prepared.some((job) => job.input.kind === 'ingest')
+            ? (prepared.find((job) => job.input.kind === 'ingest')!.prepared?.trigger ?? { kind: 'agent', runId: context.runId ?? null, actor: context.agentName ?? 'Curator' })
+            : { kind: 'agent', runId: context.runId ?? null, actor: context.agentName ?? 'Curator' }
+      const outcome = apply(wiki, namespaceFor(refs), trigger, batchProposals, captured, evidence, operationId!, context.agentName ?? 'Curator')
+      if (outcome.operation) writeJson(join(wiki, 'operations', `${outcome.operation.id}.json`), { ...outcome.operation, protected: true })
+      reindexQuietly(root)
+      this.options.bus.emit({ type: 'wiki.changed' })
+      let operationAssigned = false
+      for (const { decision, job: original } of wikiEntries) {
+        const job = curationJob(root, original.id)
+        const jobReason = decision.reason.trim()
+        job.status = outcome.parked ? 'needs_user' : 'completed'
+        job.reason = jobReason
+        job.receipt = {
+          operationId: outcome.operation && !operationAssigned ? outcome.operation.id : null,
+          notes: [...outcome.notes, ...(outcome.operation ? [`Combined batch operation ${outcome.operation.id}.`] : ['The combined review produced no Wiki changes.'])],
+          parked: outcome.parked,
+          flagged: outcome.flagged
+        }
+        if (outcome.operation && !operationAssigned) operationAssigned = true
+        results.set(job.id, saveCuration(root, job))
+      }
+    }
+
+    for (const { decision, job } of entries) {
+      if (results.has(job.id) || ['completed', 'rejected', 'needs_user'].includes(job.status)) {
+        results.set(job.id, curationJob(this.options.env.root, job.id))
+        continue
+      }
+      if (decision.decision === 'apply') {
+        results.set(job.id, this.applyJob(context, job.id, undefined, decision.reason))
+      } else {
+        results.set(job.id, this.decide(context, job.id, decision.decision, decision.reason))
+      }
+    }
+    const receiptOperationId = [...results.values()].find((job) => job.receipt?.operationId)?.receipt?.operationId ?? null
+    return { operationId: receiptOperationId, jobs: decisions.map(({ id }) => results.get(id) ?? curationJob(this.options.env.root, id)) }
+  }
+
+  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 = {}
@@ -220,9 +555,7 @@ export class Maintenance {
         text = null
       }
       if (text === null) {
-        inbox(wiki, 'unresolved', `${sourceName} was imported but not summarized`, 'Only text sources can be synthesized automatically right now.', [])
-        bus.emit({ type: 'wiki.changed' })
-        return
+        throw invalid('Only text sources can be synthesized automatically right now.')
       }
       shown = takeChars(text, 60_000)
       evidence.sourceText = text
@@ -234,8 +567,7 @@ export class Maintenance {
       try {
         found = runEvidence(root, job.runId)
       } catch (error) {
-        log(`maintenance skipped run ${job.runId}: ${error instanceof Error ? error.message : String(error)}`)
-        return
+        throw error
       }
       evidence.runText = evidenceText(root, job.runId)
       attached = runBlocks(env, job.runId)
@@ -244,7 +576,7 @@ export class Maintenance {
       trigger = { kind: 'run', runId: job.runId }
       request = { kind: 'run', runId: job.runId, transcript: shown }
     } else {
-      attached = job.blockIds.flatMap((id) => {
+      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]
@@ -252,7 +584,7 @@ export class Maintenance {
           return []
         }
       })
-      if (!attached.length) 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' }
@@ -266,12 +598,29 @@ export class Maintenance {
     } 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) {
+      // A run that is not eligible is an expected outcome, not a problem to report.
+      if (error instanceof NotEligible) return
+      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(
-        { jobId: newId(), namespace, trigger: request, pages: context.pages, memories: context.memories, blocks: blockValues(attached), namespaces: namespaces(root), index },
+        { ...prepared.request, jobId: newId() },
         { cwd: wiki, product: env.productName, account, runtime: () => this.options.accounts.runtime(account) },
         this.options.factory ?? piMaintainerFactory
       )

package/src/memory/operations.ts

@@ -8,6 +8,8 @@ import { invalid, notFound } from '../core/errors'
 import { atomicWrite, newId, now, readJson, safeId, writeJson } from '../core/fs'
 import { compareText } from '../core/text'
 import * as store from './store'
+import * as attachments from '../plugins/attachments'
+import { dirname } from 'node:path'
 
 export interface OperationPage {
   pageId: string
@@ -23,6 +25,9 @@ export interface Operation {
   trigger: string
   pages: OperationPage[]
   undone: boolean
+  protected?: boolean
+  attachmentsBefore?: attachments.Attachments
+  attachmentsAfter?: attachments.Attachments
 }
 
 export function operationsDir(wiki: string): string {
@@ -107,7 +112,14 @@ export function undo(wiki: string, operationId: string): Operation {
   const operation = readJson<Operation>(path)
   if (!operation) throw notFound('Maintenance operation')
   if (operation.undone) throw invalid('This operation was already undone.')
+  if (operation.protected) {
+    for (const page of operation.pages) {
+      if (!existsSync(page.path) || readFileSync(page.path, 'utf8') !== store.revisionText(wiki, page.pageId, page.afterRevisionId)) throw invalid('An entry changed after this operation; review it before undoing.')
+    }
+    if (operation.attachmentsAfter && JSON.stringify(attachments.load(dirname(wiki))) !== JSON.stringify(operation.attachmentsAfter)) throw invalid('Attachment settings changed after this operation; review them before undoing.')
+  }
   const short = operation.id.slice(0, 8)
+  if (operation.attachmentsBefore) attachments.save(dirname(wiki), operation.attachmentsBefore)
   for (const page of operation.pages) {
     let current = ''
     try {

package/src/memory/proposals.ts

@@ -95,6 +95,8 @@ export interface Evidence {
   sourceText?: string | null
   /** Ids of the blocks attached to the run. */
   blocks?: string[]
+  runs?: Record<string, string>
+  sources?: Record<string, string>
 }
 
 const MIN_EXCERPT = 12
@@ -175,6 +177,7 @@ export function captureHashes(wiki: string): Map<string, string> {
   for (const page of store.loadPages(wiki)) add(page.frontmatter.id, page.path)
   for (const memory of facts.loadMemories(wiki)) add(memory.front.id, memory.path)
   for (const block of blocks.loadAll(wiki)) add(block.id, block.path)
+  for (const item of registry.list(dirname(wiki))) add(item.id, item.path)
   return hashes
 }
 
@@ -223,7 +226,11 @@ interface Write {
 }
 
 /** Validates proposals and applies the valid ones as one operation. Pure file logic. */
-export function apply(wiki: string, defaultNamespace: string, trigger: Trigger, proposals: ProposalSet, captured: ReadonlyMap<string, string>, evidence: Evidence): ApplyOutcome {
+export function apply(wiki: string, defaultNamespace: string, trigger: Trigger, proposals: ProposalSet, captured: ReadonlyMap<string, string>, evidence: Evidence, operationKey?: string, appliedBy?: string): ApplyOutcome {
+  if (operationKey) {
+    const committed = readJson<Operation>(join(operationsDir(wiki), `${safeId(operationKey)}.json`))
+    if (committed) return { operation: committed, parked: 0, flagged: 0, notes: ['This request was already applied.'] }
+  }
   const existing = store.loadPages(wiki)
   const existingMemories = facts.loadMemories(wiki)
   const root = dirname(wiki)
@@ -240,7 +247,7 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
   ])
   const outcome: ApplyOutcome = { operation: null, parked: 0, flagged: 0, notes: [] }
   const writes: Write[] = []
-  const actor = triggerActor(trigger)
+  const actor = appliedBy ?? triggerActor(trigger)
   const described = describeTrigger(trigger)
   const fromUser = trigger.kind === 'user'
 
@@ -248,7 +255,7 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
   const park = (kind: string, title: string, label: string, reason: string, body: string, entryId: string, payload: unknown): void => {
     outcome.parked += 1
     outcome.notes.push(`${label} went to the Inbox: ${reason}`)
-    inbox(wiki, kind, title, `${reason}\n\n${takeChars(body, 600)}`, [entryId], null, payload)
+    inbox(wiki, kind, title, `${reason}\n\n${takeChars(body, 600)}`, [entryId], null, operationKey && payload && typeof payload === 'object' ? { ...payload, curationJobId: operationKey } : payload)
   }
 
   // Evidence: a source in the Wiki, the triggering run, a URL, or the user's acceptance. A run
@@ -259,11 +266,12 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
     for (const reference of refs) {
       let id: string | null = null
       if (reference.kind === 'source') {
-        if (sourceIds.has(reference.ref) && (evidence.sourceText == null || quotedIn(evidence.sourceText, reference.excerpt))) id = reference.ref
+        const source = evidence.sources?.[reference.ref] ?? (trigger.kind === 'ingest' && trigger.sourceId === reference.ref ? evidence.sourceText : null)
+        if (sourceIds.has(reference.ref) && (operationKey ? quotedIn(source, reference.excerpt) : (evidence.sourceText == null || quotedIn(evidence.sourceText, reference.excerpt)))) id = reference.ref
       } else if (reference.kind === 'run') {
-        if (triggerRunId(trigger) === reference.ref && quotedIn(evidence.runText, reference.excerpt)) id = `run:${reference.ref}`
+        if (quotedIn(evidence.runs?.[reference.ref] ?? (triggerRunId(trigger) === reference.ref ? evidence.runText : null), reference.excerpt)) id = `run:${reference.ref}`
       } else if (reference.kind === 'url') {
-        if (reference.ref.startsWith('https://') || reference.ref.startsWith('http://')) id = `url:${reference.ref}`
+        if (!operationKey && (reference.ref.startsWith('https://') || reference.ref.startsWith('http://'))) id = `url:${reference.ref}`
       } else if (reference.kind === 'user') {
         if (fromUser) id = 'user:accepted'
       }
@@ -277,7 +285,7 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
       .filter((link) => knownIds.has(link.toId) || proposedIds.has(link.toId))
       .filter((link) => link.toId !== ownId)
       .map((link) => ({ fromId: ownId, toId: link.toId, type: link.type }))
-  const changedSince = (id: string, path: string): boolean => captured.has(id) && captured.get(id) !== fileHash(path)
+  const changedSince = (id: string, path: string): boolean => (captured.has(id) || Boolean(operationKey)) && captured.get(id) !== fileHash(path)
 
   for (const proposal of proposals.pages) {
     const pageId = store.slug(proposal.id ?? proposal.title)
@@ -464,7 +472,7 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
     }
   })
 
-  const operationId = newId()
+  const operationId = operationKey ?? newId()
   const short = operationId.slice(0, 8)
   const pages: OperationPage[] = writes.map((write) => ({
     pageId: write.entryId,

package/src/memory/recall.test.ts

@@ -87,6 +87,17 @@ test('an agent recalls its own chats by default and everything on request', () =
   expect(searchTool(env, { ...agent('agent-a'), runId: 'chat-1' }, { query: 'pnpm' })).not.toContain('run chat-1')
 })
 
+test('a caller cannot recall the conversations of agents its host excludes', () => {
+  const env = setup()
+  sync(env.root)
+  const caller = { ...agent('agent-a'), recallExcludeAgents: ['agent-b'] }
+  const all = searchTool(env, caller, { query: 'pnpm', scope: 'all' })
+  expect(all).toContain('chat-1')
+  expect(all).not.toContain('chat-2')
+  expect(() => readTool(env, caller, { run: 'chat-2' })).toThrow()
+  expect(readTool(env, agent('agent-a'), { run: 'chat-2' })).toContain('Plan the launch')
+})
+
 test('a session recalls only session runs of its project', () => {
   const env = setup()
   sync(env.root)