@xingular/harness 0.1.7 → 2.0.0

package/src/harness.ts

@@ -1,6 +1,7 @@
 // The harness, assembled: Pi sessions on isolated accounts, a compiled prompt, a memory
 // lifecycle, tools, connected apps, and skills. An application embeds one of these and adds
 // its own prompt sections, tools, and policy; nothing here knows what that application is.
+import { Subagents } from './sessions/subagentService'
 import { mkdirSync } from 'node:fs'
 import { join } from 'node:path'
 
@@ -16,6 +17,7 @@ import { readJsonOr } from './core/fs'
 import { closeIndex } from './core/index'
 import { projectsOrNone } from './core/projects'
 import { ConnectedApps } from './mcp/service'
+import type { AppOAuthClients } from './mcp/types'
 import { migrateConnectionScopes } from './mcp/scopeMigration'
 import type { MaintainerFactory } from './memory/maintainer'
 import { Maintenance } from './memory/maintenance'
@@ -76,6 +78,11 @@ export interface HarnessOptions {
   plugins?: PluginDescriptor[]
   /** Replaces Pi's own search for extensions, skills, prompts and themes, for tests. */
   resolver?: Resolver
+  /**
+   * The application's own registered OAuth clients, so a connector it publishes needs no client
+   * from the person. Only a catalog entry listed in `ids` can use one, and nothing is stored.
+   */
+  oauthClients?: AppOAuthClients
   /** Replaces how a plugin's hooks file is read as a module, for tests. */
   hookImporter?: (address: string) => Promise<unknown>
 }
@@ -124,6 +131,7 @@ export class Harness {
   /** Every part described as a plugin: the harness's own, then the application's. */
   descriptors: readonly PluginDescriptor[] = HARNESS_PLUGINS
   applicationPlugins: ReadonlySet<string> = new Set()
+  readonly subagents: Subagents
   readonly sessions: Sessions
   readonly maintenance: Maintenance
   readonly terminals: Terminals
@@ -152,7 +160,7 @@ export class Harness {
       redact: (event) => this.apps.connections.redactEvent(event),
       ended: (runId, sessionId) => this.apps.revokeRun(runId, sessionId)
     })
-    this.apps = new ConnectedApps({ env: this.env, stateDir: this.stateDir, secrets, bus: this.bus, runs: this.runs, policy: this.policy })
+    this.apps = new ConnectedApps({ env: this.env, stateDir: this.stateDir, secrets, bus: this.bus, runs: this.runs, policy: this.policy, oauthClients: options.oauthClients })
     this.plugins = new Plugins({ stateDir: this.stateDir, bus: this.bus, resolver: options.resolver, attachments: () => (this.env.dataRoot ? attachments.load(this.env.dataRoot) : null), packagesDir: () => (this.env.dataRoot ? join(this.env.dataRoot, 'plugins') : null) })
     this.hooks = new Hooks({
       stateDir: this.stateDir,
@@ -182,7 +190,9 @@ export class Harness {
       reloadTimer.unref?.()
     })
     this.describe(options.plugins ?? [])
+    this.subagents = new Subagents(this.env, this.runs, (input) => this.sessions.run(input))
     this.sessions = new Sessions({
+      subagents: this.subagents,
       env: this.env,
       accounts: this.accounts,
       runs: this.runs,
@@ -193,7 +203,7 @@ export class Harness {
       factory: options.sessionFactory
     })
     this.maintenance = new Maintenance({ env: this.env, bus: this.bus, accounts: this.accounts, factory: options.maintainerFactory, idleMs: options.idleMs, external: options.externalMaintenance, excludedTriggers: options.maintenanceExcludedTriggers, runTrigger: options.maintenanceRunTrigger })
-    this.terminals = new Terminals({ env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope) }, assets: options.assets, program: options.piProgram, hub: this.hub })
+    this.terminals = new Terminals({ subagents: this.subagents, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope) }, assets: options.assets, program: options.piProgram, hub: this.hub })
     this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)))
     this.runs.listen((event, run) => {
       this.accounts.onRunEvent(event, run)

package/src/index.ts

@@ -47,7 +47,7 @@ export type { Effort } from './sessions/runner'
 
 export { describeTool, WIKI_TOOLS, WIKI_TOOL_NAMES, type WikiCall, type WikiToolDefinition } from './tools/definitions'
 export type { ToolProvider, ToolResult, ToolSession, ToolSpec } from './tools/types'
-export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, type SubagentOptions } from './tools/spawnSubagent'
+export { SPAWN_SUBAGENT, SUBAGENT_RELATION } from './tools/spawnSubagent'
 export { maintenanceTools, MAINTENANCE_PLUGIN, MAINTENANCE_TOOL_NAMES } from './tools/maintenance'
 export type { CurationJob } from './memory/curation'
 export { webTools, WEB_PLUGIN, WEB_SEARCH_KEY, type WebToolOptions } from './web/tools'
@@ -55,7 +55,7 @@ export { registryTools, REGISTRY_WRITE, PLUGIN_WRITE, REGISTRY_WRITE_PLUGIN, typ
 export { safeRequest, type WebRequest, type WebResponse } from './web/safeRequest'
 
 export type { BrokeredTools, BrokerSession, BrokerTool } from './mcp/service'
-export type { Connection, ConnectionInput } from './mcp/types'
+export type { Connection, ConnectionInput, AppOAuthClients } from './mcp/types'
 
 export { configureBuiltins, type RegistryItem, type RegistryState, type SkillBundleInput } from './skills/registry'
 
@@ -73,3 +73,8 @@ export { methods } from './server/methods'
 export { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './server/remote'
 export { PROTOCOL_VERSION, RpcPeer, stdioTransport, type Handler, type Transport } from './server/rpc'
 export { attach, serve, type Served } from './server/serve'
+
+export { DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, type SubagentOptions, type SubagentInput } from './sessions/subagents'
+
+export { Subagents } from './sessions/subagentService'
+export { WAIT_SUBAGENTS, type SubagentResult, type SubagentSelection } from './sessions/subagents'

package/src/mcp/connections.ts

@@ -12,7 +12,7 @@ import { isDir } from '../memory/store'
 import type { RunEvent } from '../sessions/contracts'
 import * as attachments from '../plugins/attachments'
 import { connectionScopeMigrationComplete } from './scopeMigration'
-import { connectionCapabilityId, connectionInputSchema, connectionSchema, type Connection, type ConnectionInput, type LaunchConfig, type Scope } from './types'
+import { connectionCapabilityId, connectionInputSchema, connectionSchema, type AppOAuthClients, type Connection, type ConnectionInput, type LaunchConfig, type Scope } from './types'
 
 const OAUTH_STATE = 'oauth'
 const OAUTH_CLIENT_ID = 'oauth_client_id'
@@ -175,7 +175,8 @@ export class Connections {
     stateDir: string,
     private readonly secrets: SecretStore,
     private readonly bus: Bus,
-    private readonly attachmentRoot: () => string | null = () => null
+    private readonly attachmentRoot: () => string | null = () => null,
+    private readonly appClients: AppOAuthClients | null = null
   ) {
     this.path = join(stateDir, 'connections.json')
   }
@@ -468,23 +469,49 @@ export class Connections {
 
   // ---- OAuth state --------------------------------------------------------------------------
 
-  private requireOauth(id: string): void {
-    if (!this.list().some((item) => item.id === id && item.kind === 'remote' && item.auth === 'oauth')) throw notFound('Connection')
+  private requireOauth(id: string): Connection {
+    const connection = this.list().find((item) => item.id === id && item.kind === 'remote' && item.auth === 'oauth')
+    if (!connection) throw notFound('Connection')
+    return connection
   }
 
-  /** The saved sign-in of a connection, with the client the user registered, if any. */
+  /** The saved sign-in of a connection, with the client the user registered, or the application's own. */
   async oauthLoad(id: string): Promise<Record<string, unknown>> {
-    this.requireOauth(id)
+    const connection = this.requireOauth(id)
     const saved = (parsedContainer((await this.secret(id, OAUTH_STATE)) ?? '') ?? {}) as Record<string, unknown>
     const state = Array.isArray(saved) ? {} : saved
-    const clientId = await this.secret(id, OAUTH_CLIENT_ID)
-    if (clientId) {
-      const clientSecret = await this.secret(id, OAUTH_CLIENT_SECRET)
-      state.staticClient = { client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}) }
+    delete state.staticClient
+    if (connection.oauthClient === 'app') {
+      const client = await this.appClient(connection)
+      if (client) state.staticClient = { client_id: client.clientId, ...(client.clientSecret ? { client_secret: client.clientSecret } : {}) }
+    } else if (connection.oauthClient === 'user' || connection.oauthClient === null) {
+      const clientId = await this.secret(id, OAUTH_CLIENT_ID)
+      if (clientId) {
+        const clientSecret = await this.secret(id, OAUTH_CLIENT_SECRET)
+        state.staticClient = { client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}) }
+      }
     }
     return state
   }
 
+  /** The client this application registered for a catalog entry, if it has one. */
+  private async appClient(connection: Connection): Promise<{ clientId: string; clientSecret?: string } | null> {
+    if (!connection.catalogId) return null
+    return (await this.appClients?.get(connection.catalogId)) ?? null
+  }
+
+  /** Whether a sign-in can be started: a dynamic server registers itself, the others need a client. */
+  async hasSignInClient(connection: Connection): Promise<boolean> {
+    if (connection.oauthClient === 'user') return (await this.secret(connection.id, OAUTH_CLIENT_ID)) !== null
+    if (connection.oauthClient === 'app') return (await this.appClient(connection)) !== null
+    return true
+  }
+
+  /** The catalog entries this application can sign in for without asking for a client. */
+  availableAppClients(): string[] {
+    return this.appClients?.ids() ?? []
+  }
+
   async oauthSave(id: string, state: Record<string, unknown>): Promise<void> {
     this.requireOauth(id)
     const { staticClient: _static, ...saved } = state ?? {}
@@ -515,7 +542,7 @@ export class Connections {
     if (remote) {
       if (!webUrl(connection.url)) throw invalid('Server URL must be an https:// address.')
       if (!['none', 'headers', 'oauth'].includes(connection.auth)) throw invalid('Unsupported sign-in method.')
-      if (connection.oauthClient && !['dynamic', 'user'].includes(connection.oauthClient)) throw invalid('Unsupported OAuth client.')
+      if (connection.oauthClient && !['dynamic', 'user', 'app'].includes(connection.oauthClient)) throw invalid('Unsupported OAuth client.')
       Object.assign(connection, { command: '', args: [], cwd: null })
       if (connection.auth !== 'oauth') Object.assign(connection, { oauthClient: null, oauthScopes: [] })
     } else {
@@ -533,7 +560,7 @@ export class Connections {
     connection.envKeys = [...(existing?.envKeys ?? [])]
     connection.headerKeys = [...(existing?.headerKeys ?? [])]
     // A sign-in belongs to one server and one client; never carry it to another.
-    const sameServer = (existing?.url ?? null) === connection.url && (existing?.auth ?? '') === connection.auth && !oauthCredentials
+    const sameServer = (existing?.url ?? null) === connection.url && (existing?.auth ?? '') === connection.auth && existing?.oauthClient === connection.oauthClient && existing?.catalogId === connection.catalogId && !oauthCredentials
     if (!sameServer || connection.auth !== 'oauth') await this.forgetSignIn(connection.id)
     connection.authState = connection.auth === 'oauth' ? (sameServer ? (existing?.authState ?? 'signed_out') : 'signed_out') : null
     if (oauthCredentials) {

package/src/mcp/service.test.ts

@@ -8,7 +8,7 @@ import { McpServer, WebStandardStreamableHTTPServerTransport } from '@modelconte
 import { afterEach, describe, expect, it } from 'vitest'
 
 import { memorySecretStore } from '../accounts/secrets'
-import { createHarness, type Harness } from '../harness'
+import { createHarness, type Harness, type HarnessOptions } from '../harness'
 import type { RunEvent } from '../sessions/contracts'
 import type { ToolPolicy } from '../sessions/policy'
 import type { PiSessionLike } from '../sessions/runner'
@@ -106,12 +106,12 @@ afterEach(async () => {
 const tick = (ms = 30) => new Promise((resolve) => setTimeout(resolve, ms))
 
 /** A harness with one live run whose session keeps going until the test releases it. */
-async function live(policy: ToolPolicy = {}) {
+async function live(policy: ToolPolicy = {}, extra: Partial<HarnessOptions> = {}) {
   let release: () => void = () => undefined
   const stateDir = mkdtempSync(join(tmpdir(), 'harness-mcp-state-'))
   const secrets = memorySecretStore()
   const session: PiSessionLike = { sessionId: 'native', subscribe: () => () => undefined, prompt: () => new Promise<void>((resolve) => (release = resolve)), sendCustomMessage: async () => undefined, abort: async () => release(), dispose: () => undefined }
-  const harness = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'harness-mcp-data-')), stateDir, secrets, policy, sessionFactory: async () => session })
+  const harness = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'harness-mcp-data-')), stateDir, secrets, policy, sessionFactory: async () => session, ...extra })
   open.push(harness)
   harness.accounts.create('Main', 'apiKey')
   const events: RunEvent[] = []
@@ -277,6 +277,7 @@ describe('remote connected apps', () => {
     await expect(harness.apps.save({ name: '', kind: 'local', command: 'x' })).rejects.toThrow('A name, executable')
     await expect(harness.apps.save({ ...local, env: { 'BAD NAME': 'x' } })).rejects.toThrow('environment variable')
     await expect(harness.apps.save({ ...remote, url: 'https://x.example/mcp', auth: 'headers', headers: { 'X-Key': 'a\nb' } })).rejects.toThrow('header')
+    await expect(harness.apps.save({ ...remote, url: 'https://x.example/mcp', auth: 'oauth', oauthClient: 'whoever' })).rejects.toThrow('Unsupported OAuth client')
     const workspace = await harness.apps.save({ name: 'Xingular Workspace', kind: 'workspace', command: process.execPath, enabled: true, global: true })
     expect(() => harness.apps.connections.allowTool(workspace.id, 'x_workspace_mutation_apply')).toThrow('one at a time')
     await harness.apps.remove(workspace.id)
@@ -373,4 +374,49 @@ describe('signing in to a remote connected app', () => {
     expect(server.seen.tokenRequests[0]).toContain('fixture-code')
     expect(server.seen.tokenRequests[0]).toMatch(/own-client|b3duLWNsaWVudDpvd24tc2VjcmV0/)
   })
+
+  it('signs in with the application\'s own client, keeps it out of storage, and offers it only for that catalog entry', async () => {
+    const server = await oauthFixture()
+    const { harness, secrets } = await live({}, { oauthClients: { ids: () => ['fixture-app'], get: async (id) => (id === 'fixture-app' ? { clientId: 'app-client', clientSecret: 'app-secret' } : null) } })
+    harness.bus.on((notice) => {
+      if (notice.type === 'connections.openUrl') void fetch(String(notice.url))
+    })
+    expect(harness.apps.appClients()).toEqual({ catalogIds: ['fixture-app'] })
+    const saved = await harness.apps.save({ name: 'App client', kind: 'remote', enabled: true, global: true, url: server.url, auth: 'oauth', oauthClient: 'app', catalogId: 'fixture-app', oauthScopes: ['read'] })
+    expect((await harness.apps.signIn(saved.id)).authState).toBe('signed_in')
+    // No client of its own is registered, and the application's client is what the provider sees.
+    expect(server.seen.registered).toBe(0)
+    expect(server.seen.authorizeUrls[0].searchParams.get('client_id')).toBe('app-client')
+    // Neither the saved connection nor the secret store ever holds the application's client secret.
+    expect(JSON.stringify(harness.apps.connections.list())).not.toContain('app-secret')
+    expect(JSON.stringify([...secrets.values.entries()])).not.toContain('app-secret')
+    expect(JSON.parse(secrets.values.get(`mcp--${saved.id}/oauth`)!).tokens).toMatchObject({ refresh_token: 'fixture-refresh' })
+  })
+
+  it('uses the application client and resets sign-in when switching from a saved user client', async () => {
+    const server = await oauthFixture()
+    const { harness, secrets } = await live({}, { oauthClients: { ids: () => ['fixture-app'], get: async (id) => (id === 'fixture-app' ? { clientId: 'app-client', clientSecret: 'app-secret' } : null) } })
+    harness.bus.on((notice) => {
+      if (notice.type === 'connections.openUrl') void fetch(String(notice.url))
+    })
+    const user = await harness.apps.save({ name: 'Switched client', kind: 'remote', enabled: true, global: true, url: server.url, auth: 'oauth', oauthClient: 'user', oauthCredentials: { clientId: 'user-client', clientSecret: 'user-secret' } })
+    const signedInUser = await harness.apps.signIn(user.id)
+    expect(signedInUser.authState).toBe('signed_in')
+
+    const app = await harness.apps.save({ ...user, oauthClient: 'app', catalogId: 'fixture-app' })
+    expect(app.authState).toBe('signed_out')
+    expect(secrets.values.has(`mcp--${user.id}/oauth`)).toBe(false)
+    await harness.apps.signIn(user.id)
+
+    expect(server.seen.authorizeUrls.map((url) => url.searchParams.get('client_id'))).toEqual(['user-client', 'app-client'])
+    expect(server.seen.tokenRequests[1]).toMatch(/app-client|YXBwLWNsaWVudDphcHAtc2VjcmV0/)
+  })
+
+  it('refuses an application sign-in this build has no client for, naming the reason', async () => {
+    const { harness } = await live()
+    const saved = await harness.apps.save({ name: 'No client', kind: 'remote', enabled: true, global: true, url: 'https://example.com/mcp', auth: 'oauth', oauthClient: 'app', catalogId: 'google-drive', oauthScopes: [] })
+    expect(harness.apps.appClients()).toEqual({ catalogIds: [] })
+    await expect(harness.apps.signIn(saved.id)).rejects.toThrow(/no app sign-in/)
+    expect(harness.apps.connections.find(saved.id).authState).toBe('signed_out')
+  })
 })

package/src/mcp/service.ts

@@ -20,7 +20,7 @@ import type { ToolSession, ToolSpec } from '../tools/types'
 import { allowed, Connections, webUrl } from './connections'
 import { isSignInRequired, McpManager, signInRequired } from './manager'
 import { signIn, type OAuthHost } from './oauth'
-import type { Connection, HttpConfig, LaunchConfig, McpSource, McpTrace } from './types'
+import type { AppOAuthClients, Connection, HttpConfig, LaunchConfig, McpSource, McpTrace } from './types'
 
 /** A session's access to the broker. A terminal session presents `token`; an SDK session holds the object. */
 export interface BrokerSession {
@@ -118,6 +118,8 @@ export interface ConnectedAppsOptions {
   bus: Bus
   runs: RunRegistry
   policy: ToolPolicy
+  /** The application's own registered OAuth clients, if it has any. */
+  oauthClients?: AppOAuthClients
 }
 
 /** The scope a plugin hook's connections are opened under: they belong to no session. */
@@ -134,7 +136,7 @@ export class ConnectedApps implements SessionBroker {
   private brokered: BrokeredTools | null = null
 
   constructor(private readonly options: ConnectedAppsOptions) {
-    this.connections = new Connections(options.stateDir, options.secrets, options.bus, () => options.env.root)
+    this.connections = new Connections(options.stateDir, options.secrets, options.bus, () => options.env.root, options.oauthClients ?? null)
     this.oauth = {
       clientName: options.env.productName,
       load: (id) => this.connections.oauthLoad(id),
@@ -469,7 +471,11 @@ export class ConnectedApps implements SessionBroker {
   async signIn(connectionId: string): Promise<Connection> {
     const connection = this.connections.find(connectionId)
     if (connection.kind !== 'remote' || connection.auth !== 'oauth') throw invalid('This connection does not use browser sign-in.')
-    if (connection.oauthClient === 'user' && !(await this.connections.hasOauthClient(connection.id))) throw invalid('Add your OAuth client ID before signing in.')
+    if (!(await this.connections.hasSignInClient(connection))) {
+      throw invalid(connection.oauthClient === 'app'
+        ? 'This connector has no app sign-in in this build. Enable its OAuth client or use your own client.'
+        : 'Add your OAuth client ID before signing in.')
+    }
     await signIn(this.oauth, (await this.connections.launch(connection)) as HttpConfig)
     const updated = this.connections.update(connectionId, (item) => Object.assign(item, { authState: 'signed_in', error: null }))
     await this.manager.close(connectionId)
@@ -477,6 +483,11 @@ export class ConnectedApps implements SessionBroker {
     return updated
   }
 
+  /** The catalog entries this application can sign in for, so a client need not be added by hand. */
+  appClients(): { catalogIds: string[] } {
+    return { catalogIds: this.connections.availableAppClients() }
+  }
+
   async signOut(connectionId: string): Promise<Connection> {
     const updated = await this.connections.signOut(connectionId)
     this.cancelConnection(connectionId)

package/src/mcp/types.ts

@@ -7,6 +7,16 @@ import { z } from 'zod'
 export const MCP_OAUTH_PORT = 47823
 export const MCP_OAUTH_REDIRECT_URL = `http://127.0.0.1:${MCP_OAUTH_PORT}/oauth/callback`
 
+/**
+ * The application's own registered OAuth clients, by catalog entry. A client supplied here is
+ * used for that sign-in only and is never written to the connection or the secret store.
+ */
+export interface AppOAuthClients {
+  /** The catalog entries this application can sign in for. */
+  ids(): string[]
+  get(catalogId: string): Promise<{ clientId: string; clientSecret?: string } | null>
+}
+
 /** Stable attachment key for a connected app's capability switch. */
 export const connectionCapabilityId = (id: string): string => `connected-apps/connection/${id}`
 

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 () => {