@xingular/harness 0.1.7 → 2.1.0

package/src/memory/curation.test.ts

@@ -11,9 +11,10 @@ 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 { findMemory, saveAsUser } from './facts'
 import * as registry from '../skills/registry'
 import * as attachments from '../plugins/attachments'
+import { listInbox } from './operations'
 import { wikiDir } from './store'
 
 const opened: Harness[] = []
@@ -57,6 +58,48 @@ test('a shared fact is proposed without writing, then validated against its orig
   expect(h.maintenance.applyJob(curator, job.id, undefined, 'Retry receipt').receipt).toEqual(receipt.receipt)
 })
 
+test('an assigned proposal batch is read together and committed as one reconciled Wiki operation', async () => {
+  const h = setup(); await origin(h)
+  propose(h.env, self, { kind: 'fact', title: 'Build package', body: 'Prefer pnpm for builds.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'Prefer pnpm for all builds.' }] })
+  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 ids = h.maintenance.jobs().filter(job => job.input.kind === 'proposal').map(job => job.id)
+  const batchCurator = { ...curator, maintenanceJobIds: ids }
+  expect(h.maintenance.readBatch(batchCurator).jobs).toHaveLength(2)
+
+  const applied = h.maintenance.applyBatch(batchCurator, ids.map(id => ({ id, decision: 'apply' as const, reason: 'Merge duplicate statements into one evidence-backed fact.' })), {
+    pages: [],
+    memories: [{ title: 'Build tool', kind: 'preference', body: 'Prefer pnpm for builds.', namespace: '/', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'origin', excerpt: 'Prefer pnpm for all builds.' }], links: [] }],
+    blocks: [],
+    flags: []
+  })
+
+  expect(applied.operationId).toMatch(/^batch-/)
+  expect(applied.jobs.map(job => job.status)).toEqual(['completed', 'completed'])
+  expect(applied.jobs.filter(job => job.receipt?.operationId === applied.operationId)).toHaveLength(1)
+  expect(findMemory(wikiDir(h.env.root), 'build-tool').body.trim()).toBe('Prefer pnpm for builds.')
+  expect(listInbox(wikiDir(h.env.root)).filter(item => item.operationId === applied.operationId)).toHaveLength(1)
+})
+
+test('a batch parks updates whose captured Wiki target changed before review', async () => {
+  const h = setup(); await origin(h)
+  const wiki = wikiDir(h.env.root)
+  saveAsUser(wiki, { id: 'build-tool', title: 'Build tool', kind: 'preference', namespace: '/', body: 'Use pnpm for builds.' })
+  propose(h.env, self, { kind: 'fact', id: 'build-tool', title: 'Build tool', body: 'Prefer pnpm for all builds.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'Prefer pnpm for all builds.' }] })
+  const id = h.maintenance.jobs().find(job => job.input.kind === 'proposal')!.id
+  saveAsUser(wiki, { id: 'build-tool', title: 'Build tool', kind: 'preference', namespace: '/', body: 'The user changed this preference.' })
+
+  const result = h.maintenance.applyBatch({ ...curator, maintenanceJobIds: [id] }, [{ id, decision: 'apply', reason: 'Review the proposed update against its evidence.' }], {
+    pages: [],
+    memories: [{ id: 'build-tool', title: 'Build tool', kind: 'preference', body: 'Prefer pnpm for all builds.', namespace: '/', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'origin', excerpt: 'Prefer pnpm for all builds.' }], links: [] }],
+    blocks: [],
+    flags: []
+  })
+
+  expect(result.jobs[0].status).toBe('needs_user')
+  expect(result.operationId).toBeNull()
+  expect(findMemory(wiki, 'build-tool').body.trim()).toBe('The user changed this preference.')
+})
+
 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.' }] })

package/src/memory/dispatch.ts

@@ -7,6 +7,7 @@ import { launchText, load, render } from '../prompt/compile'
 import * as api from './api'
 import type { CallerContext } from './caller'
 import * as recall from './recall'
+import * as trajectory from './trajectory'
 import { reindexQuietly } from './wikiIndex'
 
 export type DispatchEnv = HarnessEnv & { bus?: Bus }
@@ -22,6 +23,10 @@ export function dispatch(env: DispatchEnv, context: CallerContext, call: string,
       return recall.searchTool(env, context, params)
     case 'recall.read':
       return recall.readTool(env, context, params)
+    case 'trajectory.search':
+      return trajectory.searchTool(env, context, params)
+    case 'trajectory.read':
+      return trajectory.readTool(env, context, params)
     case 'memory.append':
     case 'memory.replace':
     case 'memory.rethink': {

package/src/memory/maintenance.test.ts

@@ -5,7 +5,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 
 import { memorySecretStore } from '../accounts/secrets'
 import { writeJson } from '../core/fs'
-import type { Notice } from '../core/bus'
+import { setLogSink, type Notice } from '../core/bus'
 import { createHarness, type Harness } from '../harness'
 import type { PiSessionLike } from '../sessions/runner'
 import * as blocks from './blocks'
@@ -132,6 +132,22 @@ describe('the memory lifecycle', () => {
     expect([chatUpdatesPaused({}), chatUpdatesPaused({ autoMaintenanceChat: true }), chatUpdatesPaused({ autoMaintenanceChat: false })]).toEqual([false, false, true])
   })
 
+  it('a code run outside any project is not maintained, and it leaves no log line', async () => {
+    const lines: string[] = []
+    setLogSink((text) => void lines.push(text))
+    try {
+      let jobs = 0
+      const { harness } = setup(async () => ({ prompt: async () => void (jobs += 1), dispose: () => undefined, error: () => null }))
+      await harness.sessions.run({ run: { id: 'code-1', sessionId: 'nora', mode: 'code' },cwd: harness.env.root, sessionDir: join(harness.env.root, 'history'), text: 'Which shell do we use?', caller: { agentId: 'nora', agentName: 'Nora', actor: 'Code' }, tools: { allow: [] } })
+      await new Promise((resolve) => setTimeout(resolve, 30))
+      await harness.maintenance.settled()
+      expect(jobs).toBe(0)
+      expect(lines.filter((line) => line.includes('maintenance'))).toEqual([])
+    } finally {
+      setLogSink(null)
+    }
+  })
+
   it('an imported source is read once and its proposals are checked against its text', async () => {
     const { harness, wiki } = setup(async ({ kind, collect }) => ({
       prompt: async () => {

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,7 +21,7 @@ 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'
@@ -46,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 }
 }
 
@@ -144,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
@@ -208,7 +218,12 @@ export class Maintenance {
     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 }
+        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 })
@@ -233,6 +248,150 @@ export class Maintenance {
 
   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
@@ -448,6 +607,8 @@ export class Maintenance {
     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' }) }

package/src/memory/recall.ts

@@ -3,6 +3,7 @@
 // and events stay canonical; the recall index is rebuilt from `runs/`.
 import type { DatabaseSync } from 'node:sqlite'
 
+import { logLine } from '../core/bus'
 import type { HarnessEnv } from '../core/env'
 import { invalid, notFound } from '../core/errors'
 import { all, run as execute, transaction, withIndex } from '../core/index'
@@ -67,7 +68,7 @@ export function indexRun(root: string, runId: string): void {
   try {
     withIndex(root, (database) => writeRun(database, run, found))
   } catch (error) {
-    process.stderr.write(`[recall] run ${runId} was not indexed: ${error instanceof Error ? error.message : String(error)}\n`)
+    logLine(`[recall] run ${runId} was not indexed: ${error instanceof Error ? error.message : String(error)}`)
   }
 }
 

package/src/memory/trajectory.test.ts

@@ -0,0 +1,178 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, expect, test } from 'vitest'
+
+import { createEnv } from '../core/env'
+import { closeIndex } from '../core/index'
+import { writeJson } from '../core/fs'
+import { runRecordSchema, type RunEvent, type RunRecord } from '../sessions/contracts'
+import { appendEvent, saveRun } from '../sessions/runStore'
+import { WIKI_AGENT_TOOLS } from '../tools/definitions'
+import type { CallerContext } from './caller'
+import { dispatch } from './dispatch'
+import { readTool, searchTool } from './trajectory'
+
+const roots: string[] = []
+afterEach(() => roots.splice(0).forEach(closeIndex))
+
+function setup() {
+  const root = mkdtempSync(join(tmpdir(), 'harness-trajectory-'))
+  roots.push(root)
+  writeJson(join(root, 'projects.json'), [
+    { id: 'p1', name: 'App', slug: 'app', rootPath: '/tmp/app', autoMaintenance: true, createdAt: 't' },
+    { id: 'p2', name: 'Site', slug: 'site', rootPath: '/tmp/site', autoMaintenance: true, createdAt: 't' }
+  ])
+  const env = createEnv(root, {
+    directory: {
+      agentName: (id) => ({ 'agent-a': 'Nora', 'agent-b': 'Kai', 'agent-hidden': 'Hidden' })[id] ?? null,
+      sessionAgent: (id) => id === 'hidden-session' ? 'agent-hidden' : null
+    }
+  })
+  return { root, env }
+}
+
+function run(id: string, overrides: Partial<RunRecord> = {}): RunRecord {
+  return runRecordSchema.parse({
+    id,
+    projectId: null,
+    mode: 'chat',
+    harness: 'pi',
+    sessionType: 'structured',
+    sessionId: `session-${id}`,
+    goal: `Goal for ${id}`,
+    startedAt: '2026-10-18T10:00:00.000Z',
+    endedAt: null,
+    status: 'running',
+    agentId: 'agent-a',
+    ...overrides
+  })
+}
+
+function event(runId: string, sequence: number, type: RunEvent['type'], payload: unknown, native?: unknown): RunEvent {
+  return {
+    id: `${runId}-event-${sequence}`,
+    runId,
+    sessionId: `session-${runId}`,
+    sequence,
+    timestamp: `2026-10-18T10:00:${String(sequence).padStart(2, '0')}.000Z`,
+    type,
+    payload,
+    ...(native === undefined ? {} : { native })
+  } as RunEvent
+}
+
+function save(root: string, record: RunRecord, events: RunEvent[] = []): void {
+  saveRun(root, record)
+  for (const entry of events) appendEvent(root, entry)
+}
+
+const agent: CallerContext = { agentId: 'agent-a', actor: 'Chat' }
+
+test('trajectory search filters runs and paginates deterministically, including active runs', () => {
+  const { root, env } = setup()
+  save(root, run('z-run', { projectId: 'p2', agentId: 'agent-b' }))
+  save(root, run('b-run', { projectId: 'p2', agentId: 'agent-b' }))
+  save(root, run('a-run', { projectId: 'p1', agentId: 'agent-a', startedAt: '2026-10-17T10:00:00.000Z', status: 'completed', endedAt: '2026-10-17T10:01:00.000Z' }))
+
+  const first = JSON.parse(searchTool(env, agent, { project: 'site', agent: 'Kai', limit: 1 }))
+  expect(first.runs.map((item: { id: string }) => item.id)).toEqual(['z-run'])
+  expect(first.runs[0]).toMatchObject({ agentId: 'agent-b', agentName: 'Kai', project: { id: 'p2', name: 'Site', slug: 'site' }, status: 'running' })
+  expect(first.hasMore).toBe(true)
+
+  const second = JSON.parse(searchTool(env, agent, { project: 'p2', agent: 'agent-b', limit: 1, cursor: first.nextCursor }))
+  expect(second.runs.map((item: { id: string }) => item.id)).toEqual(['b-run'])
+  expect(second.hasMore).toBe(false)
+
+  const bounded = JSON.parse(searchTool(env, agent, { since: '2026-10-18', until: '2026-10-18', status: 'running' }))
+  expect(bounded.runs.map((item: { id: string }) => item.id)).toEqual(['z-run', 'b-run'])
+})
+
+test('trajectory search and read keep host-excluded agents hidden', () => {
+  const { root, env } = setup()
+  save(root, run('hidden-agent-run', { agentId: 'agent-hidden' }))
+  save(root, run('hidden-session-run', { agentId: null, sessionId: 'hidden-session' }))
+  save(root, run('visible-run'))
+  const caller = { ...agent, recallExcludeAgents: ['agent-hidden'] }
+
+  const results = JSON.parse(searchTool(env, caller, {}))
+  expect(results.runs.map((item: { id: string }) => item.id)).toEqual(['visible-run'])
+  expect(() => readTool(env, caller, { run: 'hidden-agent-run' })).toThrow()
+  expect(() => readTool(env, caller, { run: 'hidden-session-run' })).toThrow()
+})
+
+test('trajectory_read resolves current and returns bounded event pages without native data', () => {
+  const { root, env } = setup()
+  const longInput = 'x'.repeat(20_000)
+  save(root, run('active-run'), [
+    event('active-run', 0, 'context.snapshot', { systemPrompt: 'Be useful', tools: [] }, { privateNative: true }),
+    event('active-run', 1, 'tool.started', { toolCallId: 't1', name: 'read', input: longInput }),
+    event('active-run', 2, 'tool.completed', { toolCallId: 't1', name: 'read', output: 'file contents' })
+  ])
+  const caller = { ...agent, runId: 'active-run' }
+
+  const initial = JSON.parse(readTool(env, caller, { run: 'current', limit: 1 }))
+  expect(initial.events[0]).toMatchObject({ sequence: 0, type: 'context.snapshot', payload: { systemPrompt: 'Be useful', tools: [] } })
+  expect(JSON.stringify(initial)).not.toContain('privateNative')
+
+  const first = JSON.parse(readTool(env, caller, { run: 'current', afterSequence: 0, limit: 1 }))
+  expect(first).toMatchObject({ active: true, run: { id: 'active-run', status: 'running' }, hasMore: true, nextAfterSequence: 1 })
+  expect(first.events[0]).toMatchObject({ sequence: 1, type: 'tool.started', truncatedFields: ['payload.input'] })
+  expect(JSON.stringify(first)).not.toContain('privateNative')
+  expect(first.events[0].payload.input.length).toBeLessThan(longInput.length)
+
+  const second = JSON.parse(readTool(env, caller, { run: 'active-run', afterSequence: first.nextAfterSequence, limit: 1 }))
+  expect(second.events[0]).toMatchObject({ sequence: 2, type: 'tool.completed', payload: { output: 'file contents' } })
+  expect(second.hasMore).toBe(false)
+})
+
+test('trajectory_read follows execution events through the first outcome only', () => {
+  const { root, env } = setup()
+  save(root, run('settled-run', { status: 'completed', endedAt: '2026-10-18T10:01:00.000Z' }), [
+    event('settled-run', 0, 'started', {}),
+    event('settled-run', 1, 'completed', {}),
+    event('settled-run', 2, 'tool.started', { toolCallId: 'late', name: 'ignored' }, { hostIgnored: 'run_already_ended' })
+  ])
+
+  const result = JSON.parse(readTool(env, agent, { run: 'settled-run' }))
+  expect(result.active).toBe(false)
+  expect(result.events.map((item: { sequence: number }) => item.sequence)).toEqual([0, 1])
+  expect(JSON.stringify(result)).not.toContain('ignored')
+})
+
+test('trajectory_read keeps account identifiers and credential fields out of event payloads', () => {
+  const { root, env } = setup()
+  save(root, run('safe-run'), [
+    event('safe-run', 0, 'account.status', { accountId: 'private-account-id', category: 'quota', message: 'Limit reached for sk-abcdefghijklmnopqrstuvwxyz012345' }),
+    event('safe-run', 1, 'tool.started', { toolCallId: 't1', name: 'login', input: '{"username":"ada","password":"private-password"}' }),
+    event('safe-run', 2, 'usage.updated', { inputTokens: 10, request: { index: 1, reasoningSummary: 'private reasoning summary' } })
+  ])
+
+  const result = JSON.parse(readTool(env, agent, { run: 'safe-run' }))
+  expect(result.events[0].omittedFields).toContain('payload.accountId')
+  expect(JSON.stringify(result)).not.toContain('private-account-id')
+  expect(JSON.stringify(result)).not.toContain('sk-abcdefghijklmnopqrstuvwxyz012345')
+  expect(JSON.stringify(result)).not.toContain('private-password')
+  expect(result.events[1].payload.input).not.toContain('password')
+  expect(result.events[2].omittedFields).toContain('payload.request.reasoningSummary')
+  expect(JSON.stringify(result)).not.toContain('private reasoning summary')
+})
+
+test('trajectory calls reject malformed filters and missing current runs', () => {
+  const { env } = setup()
+  expect(() => searchTool(env, agent, { status: 'unknown' })).toThrow()
+  expect(() => searchTool(env, agent, { since: 'not-a-date' })).toThrow()
+  expect(() => searchTool(env, agent, { cursor: 'not-a-cursor' })).toThrow()
+  expect(() => readTool(env, agent, { run: 'current' })).toThrow()
+  expect(() => readTool(env, agent, { run: 'missing' })).toThrow()
+})
+
+test('the model tool registry exposes both trajectory calls through Wiki dispatch', () => {
+  const { root, env } = setup()
+  save(root, run('registered-run'))
+  const calls = WIKI_AGENT_TOOLS.map((tool) => tool.call)
+  expect(calls).toContain('trajectory.search')
+  expect(calls).toContain('trajectory.read')
+  expect(JSON.parse(dispatch(env, agent, 'trajectory.search', {})).runs[0].id).toBe('registered-run')
+  expect(JSON.parse(dispatch(env, agent, 'trajectory.read', { run: 'registered-run' })).run.id).toBe('registered-run')
+})