@xingular/harness 0.1.6 → 0.1.7

package/src/memory/caller.ts

@@ -10,11 +10,23 @@ import * as blocks from './blocks'
  * never limits what can be read.
  */
 export interface CallerContext {
+  /** Opaque, host-owned policy data frozen when this session starts. The harness only forwards it to the embedding app's tool policy. */
+  policyContext?: unknown
+  /**
+   * Trusted, frozen vault mutation capability supplied by an embedding host. `self` writes its own
+   * persona and notes directly and proposes the rest; `propose` writes nothing directly; `curator`
+   * applies proposals.
+   */
+  vaultAccess?: 'self' | 'propose' | 'curator'
+  maintenanceJobId?: string | null
+  maintenanceJobIds?: string[]
   runId?: string | null
   sessionId?: string | null
   projectId?: string | null
   /** The agent calling; it decides which memory blocks are attached and editable. */
   agentId?: string | null
+  /** Agents whose conversations this caller may not recall (opaque ids from the embedding host). */
+  recallExcludeAgents?: string[] | null
   /** The agent's name, recorded on the revisions it makes. */
   agentName?: string | null
   /** Projects whose briefs the agent carries, most recently active first. */
@@ -42,7 +54,7 @@ export function projectOf(root: string, context: CallerContext): Project | null
 export function blockCaller(env: HarnessEnv, context: CallerContext): blocks.Caller {
   if (isSession(context)) return { kind: 'session', projectSlug: projectOf(env.root, context)?.slug ?? null }
   if (!context.agentId) throw invalid('Memory blocks need an agent or a Harness session.')
-  return { kind: 'agent', id: context.agentId, name: context.agentName ?? env.directory.agentName(context.agentId) ?? context.agentId }
+  return { kind: 'agent', id: context.agentId, name: context.agentName ?? env.directory.agentName(context.agentId) ?? context.agentId, vaultAccess: context.vaultAccess === 'propose' ? 'propose' : context.vaultAccess ? 'self' : undefined }
 }
 
 /** The blocks in the caller's context: an agent also carries the briefs of its active projects. */

package/src/memory/curation.test.ts

@@ -0,0 +1,163 @@
+import { existsSync, mkdtempSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { afterEach, expect, test } from 'vitest'
+
+import { createHarness, type Harness } from '../harness'
+import { memorySecretStore } from '../accounts/secrets'
+import type { PiSessionLike } from '../sessions/runner'
+import { registryTools } from '../tools/registryWrite'
+import type { ToolSession } from '../tools/types'
+import * as blocks from './blocks'
+import { memoryEdit, propose } from './api'
+import { enqueueCuration } from './curation'
+import { findMemory } from './facts'
+import * as registry from '../skills/registry'
+import * as attachments from '../plugins/attachments'
+import { wikiDir } from './store'
+
+const opened: Harness[] = []
+afterEach(async () => { for (const harness of opened.splice(0)) await harness.close() })
+const self = { agentId: 'nora', agentName: 'Nora', actor: 'Chat', vaultAccess: 'self' as const, runId: 'origin' }
+const curator = { agentId: 'curator', agentName: 'Curator', actor: 'Chat', vaultAccess: 'curator' as const, runId: 'review' }
+
+function setup(): Harness {
+  let emit: (event: unknown) => void = () => undefined
+  const session: PiSessionLike = { sessionId: 'test-session', subscribe: listener => { emit = listener as never; return () => undefined }, prompt: async () => { emit({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'Prefer pnpm for all builds.' }] } }) }, sendCustomMessage: async () => undefined, abort: async () => undefined, dispose: () => undefined }
+  const harness = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'curation-data-')), stateDir: mkdtempSync(join(tmpdir(), 'curation-state-')), externalMaintenance: true, secrets: memorySecretStore(), sessionFactory: async () => session, maintainerFactory: async () => { throw new Error('Hidden maintenance must not run') } })
+  opened.push(harness)
+  harness.accounts.create('Main', 'apiKey')
+  blocks.ensureAgent(wikiDir(harness.env.root), 'nora')
+  return harness
+}
+async function origin(harness: Harness): Promise<void> {
+  await harness.sessions.run({ run: { id: 'origin', sessionId: 'nora' }, cwd: harness.env.root, sessionDir: join(harness.env.root, 'history'), text: 'Prefer pnpm for all builds.', caller: self, tools: { allow: [] } })
+  await new Promise(resolve => setTimeout(resolve, 30))
+}
+
+test('normal callers directly write only their own persona and notes; standalone callers retain their prior scope', () => {
+  const h = setup()
+  expect(memoryEdit(h.env, self, 'memory.append', { block: 'notes', text: 'Working on release notes.' })).toContain('Updated')
+  expect(() => memoryEdit(h.env, self, 'memory.append', { block: 'user', text: 'A shared preference.' })).toThrow('outside your writable memory')
+  blocks.ensureAgent(wikiDir(h.env.root), 'other')
+  expect(() => memoryEdit(h.env, self, 'memory.append', { block: 'blocks/agents/other/notes', text: 'Not mine.' })).toThrow()
+  expect(memoryEdit(h.env, { ...self, vaultAccess: undefined }, 'memory.append', { block: 'user', text: 'Standalone scope.' })).toContain('Updated')
+})
+
+test('a shared fact is proposed without writing, then validated against its original run and applied once', async () => {
+  const h = setup(); await origin(h)
+  const submitted = propose(h.env, self, { kind: 'fact', title: 'Build tool', body: 'Use pnpm for builds.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'Prefer pnpm for all builds.' }] })
+  const job = h.maintenance.jobs().find(job => job.input.kind === 'proposal')!
+  expect(submitted).toContain(job.id)
+  expect(() => findMemory(wikiDir(h.env.root), 'build-tool')).toThrow()
+  expect(() => h.maintenance.readJob(self, job.id)).toThrow('curator capability')
+  const receipt = h.maintenance.applyJob(curator, job.id, undefined, 'Preserve the stated build preference.')
+  expect(receipt.status).toBe('completed')
+  expect(findMemory(wikiDir(h.env.root), 'build-tool').front.sourceIds).toContain('run:origin')
+  expect(h.maintenance.applyJob(curator, job.id, undefined, 'Retry receipt').receipt).toEqual(receipt.receipt)
+})
+
+test('invented evidence is parked and a read-only memory block is not rewritten', async () => {
+  const h = setup(); await origin(h)
+  propose(h.env, self, { kind: 'fact', title: 'Invented', body: 'Use another tool.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'This was never said anywhere.' }] })
+  const job = h.maintenance.jobs().find(job => job.input.kind === 'proposal')!
+  expect(h.maintenance.applyJob(curator, job.id, undefined, 'Review the claimed evidence').status).toBe('needs_user')
+  expect(() => findMemory(wikiDir(h.env.root), 'invented')).toThrow()
+  const block = blocks.find(wikiDir(h.env.root), 'blocks/agents/nora/notes')
+  blocks.saveAsUser(wikiDir(h.env.root), { id: block.id, body: '', description: block.front.description, limit: 2000, readOnly: true })
+  expect(() => propose(h.env, self, { kind: 'block', id: block.id, title: 'Notes', body: 'Changed.' })).toThrow('user-only')
+})
+
+test('text resources remain inactive until curated; undo restores attachments and preserves subsequent user edits', async () => {
+  const h = setup()
+  const tool = (await registryTools({ harness: h })({ caller: self } as ToolSession)).find(tool => tool.name === 'registry_write')!
+  await tool.execute({ kind: 'skill', name: 'release-notes', description: 'Write release notes', body: 'Summarize verified changes.', reason: 'Repeated release work.' })
+  const job = h.maintenance.jobs().find(job => job.input.kind === 'registry')!
+  expect(registry.list(h.env.root).some(item => item.id === 'skills/release-notes')).toBe(false)
+  const receipt = h.maintenance.applyJob(curator, job.id, undefined, 'Reuse the repeated release procedure.')
+  expect(attachments.attached(attachments.load(h.env.root), ['skills/release-notes'], { agentId: 'nora' }, false)).toBe(true)
+  h.maintenance.undoOperation(receipt.receipt!.operationId!)
+  expect(registry.list(h.env.root).some(item => item.id === 'skills/release-notes')).toBe(false)
+  const next = enqueueCuration(h.env.root, { kind: 'registry', caller: self, proposal: { kind: 'skill', name: 'other-notes', description: 'Notes', body: 'Write verified notes.', reason: 'Workflow improvement.' } })
+  const applied = h.maintenance.applyJob(curator, next.id, undefined, 'Apply text-only improvement.')
+  registry.writeItem(h.env.root, 'skill', 'other-notes', 'Notes', 'The user changed this.', 'User edit')
+  expect(() => h.maintenance.undoOperation(applied.receipt!.operationId!)).toThrow('changed after')
+})
+
+test('changed target versions are escalated instead of overwritten', () => {
+  const h = setup()
+  registry.writeItem(h.env.root, 'skill', 'notes', 'Notes', 'Original notes.', 'Initial')
+  const job = enqueueCuration(h.env.root, { kind: 'registry', caller: self, proposal: { kind: 'skill', name: 'notes', description: 'Notes', body: 'Proposed notes.', reason: 'Improve' } })
+  registry.writeItem(h.env.root, 'skill', 'notes', 'Notes', 'User edits win.', 'User edit')
+  expect(h.maintenance.applyJob(curator, job.id, undefined, 'Review update').status).toBe('needs_user')
+  expect(registry.list(h.env.root).find(item => item.id === 'skills/notes')).toBeDefined()
+})
+
+test('executable plugins are submitted without saving, activation or trust', async () => {
+  const h = setup()
+  const tool = (await registryTools({ harness: h })({ caller: self } as ToolSession)).find(tool => tool.name === 'plugin_write')!
+  await tool.execute({ name: 'code-change', description: 'A code plugin', files: [{ path: 'extensions/index.ts', content: 'export default () => {}' }] })
+  const job = h.maintenance.jobs().find(job => job.input.kind === 'plugin')!
+  expect(h.maintenance.applyJob(curator, job.id, undefined, 'Code needs trust').status).toBe('needs_user')
+  expect(existsSync(join(h.env.root, 'plugins/code-change'))).toBe(false)
+})
+
+test('external jobs persist and repeated schedule occurrences are distinct; no hidden provider runs', async () => {
+  const h = setup()
+  const source = h.maintenance.ingest('source.txt', Buffer.from('Prefer pnpm for all builds.'))
+  expect(h.maintenance.jobs().some(job => job.input.kind === 'ingest' && job.input.sourceId === source.id)).toBe(true)
+  h.maintenance.enqueue({ kind: 'review', requestId: 'day-one' })
+  h.maintenance.enqueue({ kind: 'review', requestId: 'day-one' })
+  h.maintenance.enqueue({ kind: 'review', requestId: 'day-two' })
+  expect(h.maintenance.jobs().filter(job => job.input.kind === 'review')).toHaveLength(2)
+  await h.maintenance.settled()
+})
+
+test('a curator run never enqueues another completed-run maintenance job', async () => {
+  const h = setup()
+  await h.sessions.run({ run: { id: 'curator-run', sessionId: 'curator' }, cwd: h.env.root, sessionDir: join(h.env.root, 'curator-history'), text: 'Review maintenance.', caller: curator, tools: { allow: [] } })
+  await new Promise(resolve => setTimeout(resolve, 30))
+  expect(h.maintenance.jobs().some(job => job.input.kind === 'run' && job.input.runId === 'curator-run')).toBe(false)
+})
+
+test('curator prose cannot become its own evidence; original source runs can support a review', async () => {
+  const h = setup(); await origin(h)
+  await h.sessions.run({ run: { id: 'review', sessionId: 'curator' }, cwd: h.env.root, sessionDir: join(h.env.root, 'curator-history'), text: 'Prefer pnpm for all builds.', caller: curator, tools: { allow: [] } })
+  await new Promise(resolve => setTimeout(resolve, 30))
+  propose(h.env, curator, { kind: 'fact', title: 'Curator claim', body: 'A claim from the review.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'Prefer pnpm for all builds.' }] })
+  const own = h.maintenance.jobs().find(job => job.input.kind === 'proposal')!
+  expect(h.maintenance.applyJob(curator, own.id, undefined, 'Check the original evidence.').status).toBe('needs_user')
+  expect(() => findMemory(wikiDir(h.env.root), 'curator-claim')).toThrow()
+  const review = enqueueCuration(h.env.root, { kind: 'review', requestId: 'grounded-review' })
+  const applied = h.maintenance.applyJob(curator, review.id, { memories: [{ title: 'Original preference', kind: 'preference', body: 'Prefer pnpm.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'origin', excerpt: 'Prefer pnpm for all builds.' }] }] }, 'Retain the original recorded preference.')
+  expect(applied.status).toBe('completed')
+  expect(findMemory(wikiDir(h.env.root), 'original-preference').front.sourceIds).toContain('run:origin')
+})
+
+
+test('a failed evidence preparation remains attributed and can be rejected without rereading invalid input', () => {
+  const h = setup()
+  const job = enqueueCuration(h.env.root, { kind: 'consolidate', blockIds: ['missing-block'] })
+  expect(() => h.maintenance.readJob(curator, job.id)).toThrow('No writable blocks')
+  expect(h.maintenance.jobs().find(item => item.id === job.id)).toMatchObject({ status: 'failed', runId: 'review' })
+  expect(h.maintenance.decide(curator, job.id, 'reject', 'The target no longer exists.').status).toBe('rejected')
+})
+
+test('a propose-only caller writes no memory directly, not even its own persona and notes', () => {
+  const h = setup()
+  const proposer = { ...self, vaultAccess: 'propose' as const }
+  expect(() => memoryEdit(h.env, proposer, 'memory.append', { block: 'notes', text: 'Working on release notes.' })).toThrow('Memory changes are proposals')
+  expect(() => memoryEdit(h.env, proposer, 'memory.append', { block: 'persona', text: 'I am terse.' })).toThrow('Memory changes are proposals')
+  expect(propose(h.env, proposer, { kind: 'block', id: 'blocks/agents/nora/notes', title: 'Notes', body: 'Working on release notes.' })).toContain('Submitted proposal')
+})
+
+test('with the run trigger off, a settled run queues no consolidation of its own', async () => {
+  let emit: (event: unknown) => void = () => undefined
+  const session: PiSessionLike = { sessionId: 'quiet', subscribe: listener => { emit = listener as never; return () => undefined }, prompt: async () => { emit({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'Prefer pnpm for all builds.' }] } }) }, sendCustomMessage: async () => undefined, abort: async () => undefined, dispose: () => undefined }
+  const h = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'curation-data-')), stateDir: mkdtempSync(join(tmpdir(), 'curation-state-')), externalMaintenance: true, maintenanceRunTrigger: false, secrets: memorySecretStore(), sessionFactory: async () => session })
+  opened.push(h)
+  h.accounts.create('Main', 'apiKey')
+  await h.sessions.run({ run: { id: 'quiet-run', sessionId: 'nora' }, cwd: h.env.root, sessionDir: join(h.env.root, 'history'), text: 'Prefer pnpm.', caller: self, tools: { allow: [] } })
+  await new Promise(resolve => setTimeout(resolve, 30))
+  expect(h.maintenance.jobs().filter(job => job.input.kind === 'run')).toEqual([])
+})

package/src/memory/curation.ts

@@ -0,0 +1,64 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+
+import { invalid, notFound } from '../core/errors'
+import { newId, now, readJson, safeId, writeJson } from '../core/fs'
+import type { CallerContext } from './caller'
+import type { Job } from './maintenance'
+import type { MaintenanceRequest } from './maintainer'
+import { captureHashes, parseProposalSet, type ProposalSet, type RegistryProposal, type Evidence, type Trigger } from './proposals'
+import { looksSecret } from './secrets'
+import * as store from './store'
+
+export type CurationInput = Job
+  | { kind: 'proposal'; namespace: string; proposals: ProposalSet; caller: CallerContext }
+  | { kind: 'registry'; proposal: RegistryProposal; caller: CallerContext }
+  | { kind: 'plugin'; proposal: unknown; caller: CallerContext }
+export interface CurationJob {
+  id: string
+  key: string
+  input: CurationInput
+  status: 'queued' | 'running' | 'completed' | 'failed' | 'rejected' | 'needs_user'
+  createdAt: string
+  updatedAt: string
+  runId: string | null
+  reason: string
+  hashes: [string, string][]
+  prepared?: { request: MaintenanceRequest; evidence: Evidence; namespace: string; trigger: Trigger }
+  receipt: { operationId: string | null; notes: string[]; parked: number; flagged: number } | null
+}
+
+const directory = (root: string): string => join(store.wikiDir(root), 'maintenance-jobs')
+export function listCuration(root: string): CurationJob[] {
+  let names: string[] = []
+  try { names = readdirSync(directory(root)) } catch { return [] }
+  return names.filter((name) => name.endsWith('.json')).flatMap((name) => {
+    const job = readJson<CurationJob>(join(directory(root), name))
+    return job && typeof job.id === 'string' && job.input && typeof job.input.kind === 'string' ? [job] : []
+  }).sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+}
+export function curationJob(root: string, id: string): CurationJob {
+  const job = readJson<CurationJob>(join(directory(root), `${safeId(id)}.json`))
+  if (!job) throw notFound('Maintenance job')
+  return job
+}
+export function saveCuration(root: string, job: CurationJob): CurationJob {
+  writeJson(join(directory(root), `${safeId(job.id)}.json`), { ...job, updatedAt: now() })
+  return job
+}
+export function enqueueCuration(root: string, input: CurationInput): CurationJob {
+  if (input.kind === 'proposal') input = { ...input, proposals: parseProposalSet(input.proposals) }
+  if (Buffer.byteLength(JSON.stringify(input)) > 256 * 1024) throw invalid('The proposal is larger than 256 KiB.')
+  if (looksSecret(JSON.stringify(input))) throw invalid('The proposal contains text that looks like a credential.')
+  const captured = captureHashes(store.wikiDir(root))
+  const revisions = input.kind === 'consolidate' ? input.blockIds.map(id => [id, captured.get(id)]) : undefined
+  const key = createHash('sha256').update(JSON.stringify({ input, revisions })).digest('hex')
+  const existing = listCuration(root).find((job) => job.key === key)
+  if (existing) return existing
+  const timestamp = now()
+  return saveCuration(root, { id: newId(), key, input, status: 'queued', createdAt: timestamp, updatedAt: timestamp, runId: null, reason: '', hashes: [...captured], receipt: null })
+}
+export function requireCurator(context: CallerContext): void {
+  if (context.vaultAccess !== 'curator' || !context.runId) throw invalid('This operation needs a curator capability issued by the host for this run.')
+}

package/src/memory/maintenance.ts

@@ -22,11 +22,18 @@ import { piMaintainerFactory, runMaintenance, type ExistingBlock, type ExistingM
 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 } | { 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
@@ -144,6 +151,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 +168,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 +206,17 @@ 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) { 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 +225,158 @@ 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) }
+
+  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 +396,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 +408,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 +417,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 +425,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 +439,27 @@ 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) {
+      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 {