@namzu/sdk 34.2.0 → 36.0.0

package/src/sandbox/provider/local.ts

@@ -25,19 +25,22 @@ import {
 // registry needs the same one, and a near-copy would reproduce in the copy
 // every bug the original's comment was written to record.
 import { killTree } from '../../process/kill-tree.js'
-import { resolveWithinReal } from '../../tools/paths.js'
+import { resolveWithinAny, resolveWithinAnyReal } from '../../tools/paths.js'
 import type { SandboxId } from '../../types/ids/index.js'
 import type {
 	Sandbox,
 	SandboxCreateConfig,
 	SandboxDestroyOptions,
+	SandboxDetachedProcess,
 	SandboxEnvironment,
 	SandboxExecOptions,
 	SandboxExecResult,
 	SandboxFileEntry,
 	SandboxIsolationControl,
 	SandboxProvider,
+	SandboxSpawnOptions,
 	SandboxStatus,
+	SandboxWalkFilesOptions,
 } from '../../types/sandbox/index.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { generateSandboxId } from '../../utils/id.js'
@@ -47,6 +50,7 @@ import {
 	applyEnvironmentOverrides,
 	pickEnvironmentEntries,
 } from '../../utils/process-environment.js'
+import { walkFilesLocally } from '../file-walk.js'
 import { assertIsolation, describeIsolation } from '../isolation.js'
 import type { PtyLoader } from '../terminal.js'
 
@@ -208,6 +212,8 @@ export interface LimitedSpawnRequest {
 	readonly command: string
 	readonly args: readonly string[]
 	readonly rootDir: string
+	/** Bound read-write beside the root; see `SandboxCreateConfig.additionalDirectories`. */
+	readonly additionalDirectories?: readonly string[]
 	readonly memoryLimitMb?: number
 	readonly maxProcesses?: number
 }
@@ -265,7 +271,7 @@ export function buildLimitedSpawn(request: LimitedSpawnRequest): {
 		case 'linux-bwrap':
 			return {
 				spawnCommand: requiredWrapper(request),
-				spawnArgs: [...buildBwrapArgs(rootDir), '--', ...inner],
+				spawnArgs: [...buildBwrapArgs(rootDir, request.additionalDirectories), '--', ...inner],
 			}
 
 		case 'linux-namespace':
@@ -277,7 +283,7 @@ export function buildLimitedSpawn(request: LimitedSpawnRequest): {
 		case 'macos-seatbelt':
 			return {
 				spawnCommand: requiredWrapper(request),
-				spawnArgs: [...buildSeatbeltArgs(rootDir), '--', ...inner],
+				spawnArgs: [...buildSeatbeltArgs(rootDir, request.additionalDirectories), '--', ...inner],
 			}
 
 		case 'basic': {
@@ -375,7 +381,10 @@ function canonicalizePath(p: string): string {
  * process table through them — a bound `/proc` would hand back the process
  * isolation the same flag just removed.
  */
-export function buildBwrapArgs(sandboxRoot: string): string[] {
+export function buildBwrapArgs(
+	sandboxRoot: string,
+	additionalDirectories: readonly string[] = [],
+): string[] {
 	const root = canonicalizePath(sandboxRoot)
 
 	const args = [
@@ -426,9 +435,15 @@ export function buildBwrapArgs(sandboxRoot: string): string[] {
 		'--bind',
 		root,
 		root,
-		'--chdir',
-		root,
 	)
+	// The host's added directories, read-write at their own paths, so a
+	// path the model was given on the host means the same thing inside.
+	for (const dir of additionalDirectories) {
+		const canonical = canonicalizePath(dir)
+		if (canonical === root) continue
+		args.push('--bind', canonical, canonical)
+	}
+	args.push('--chdir', root)
 
 	return args
 }
@@ -450,10 +465,21 @@ const BWRAP_SYSTEM_PATHS: readonly string[] = [
 	'/opt',
 ]
 
-function buildSeatbeltProfile(): string {
+function seatbeltString(value: string): string {
+	return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+}
+
+function buildSeatbeltProfile(additionalDirectories: readonly string[] = []): string {
 	return [
 		'(version 1)',
 		'(deny default)',
+		// The host's added directories, read-write, by the same contract as
+		// the root. Literal paths rather than params: sandbox-exec takes one
+		// -D per name and the count here is the operator's.
+		...additionalDirectories.flatMap((dir) => [
+			`(allow file-read* (subpath ${seatbeltString(canonicalizePath(dir))}))`,
+			`(allow file-write* (subpath ${seatbeltString(canonicalizePath(dir))}))`,
+		]),
 
 		// --- Process lifecycle ---
 		'(allow process-exec)',
@@ -538,8 +564,15 @@ function buildSeatbeltProfile(): string {
  * remain path bytes instead of becoming policy syntax. This is the same
  * parameter boundary used by Codex's seatbelt builder.
  */
-function buildSeatbeltArgs(sandboxRoot: string): string[] {
-	return ['-p', buildSeatbeltProfile(), `-DNAMZU_SANDBOX_ROOT=${canonicalizePath(sandboxRoot)}`]
+function buildSeatbeltArgs(
+	sandboxRoot: string,
+	additionalDirectories: readonly string[] = [],
+): string[] {
+	return [
+		'-p',
+		buildSeatbeltProfile(additionalDirectories),
+		`-DNAMZU_SANDBOX_ROOT=${canonicalizePath(sandboxRoot)}`,
+	]
 }
 
 // ---------------------------------------------------------------------------
@@ -595,6 +628,12 @@ class LocalSandbox implements Sandbox {
 	private _status: SandboxStatus
 	private readonly config: SandboxCreateConfig
 	private readonly log: Logger
+	/** The host's added directories, canonical; bound beside the root. */
+	private readonly additionalDirectories: readonly string[]
+	/** Where this sandbox's own file API may reach: the root, then the added directories. */
+	private get roots(): readonly string[] {
+		return [this.rootDir, ...this.additionalDirectories]
+	}
 
 	get status(): SandboxStatus {
 		return this._status
@@ -613,6 +652,9 @@ class LocalSandbox implements Sandbox {
 		this.rootDir = rootDir
 		this.environment = environment
 		this.config = config
+		this.additionalDirectories = (config.additionalDirectories ?? [])
+			.map((dir) => canonicalizePath(resolve(dir)))
+			.filter((dir) => dir !== rootDir)
 		this._status = 'ready'
 		this.log = log.child({
 			[SCOPE_ATTRIBUTE]: 'sandbox/provider/local',
@@ -640,7 +682,7 @@ class LocalSandbox implements Sandbox {
 		const env = buildSafeEnv(this.config.env, opts?.env)
 		const timeout = opts?.timeout ?? this.config.timeoutMs ?? SANDBOX_DEFAULT_TIMEOUT_MS
 
-		const cwd = opts?.cwd ? await resolveWithinReal(this.rootDir, opts.cwd) : this.rootDir
+		const cwd = opts?.cwd ? await resolveWithinAnyReal(this.roots, opts.cwd) : this.rootDir
 
 		const { spawnCommand, spawnArgs, bwrapInfoFd, bwrapBlockFd } = this.buildSpawnArgs(
 			command,
@@ -689,7 +731,7 @@ class LocalSandbox implements Sandbox {
 			throw new Error(`Sandbox ${this.id} is destroyed`)
 		}
 
-		const resolved = await resolveWithinReal(this.rootDir, path)
+		const resolved = await resolveWithinAnyReal(this.roots, path)
 		await mkdir(dirname(resolved), { recursive: true })
 
 		// Convention 8: Atomic write (write-tmp-rename)
@@ -705,7 +747,7 @@ class LocalSandbox implements Sandbox {
 			throw new Error(`Sandbox ${this.id} is destroyed`)
 		}
 
-		const resolved = await resolveWithinReal(this.rootDir, path)
+		const resolved = await resolveWithinAnyReal(this.roots, path)
 		return fsReadFile(resolved)
 	}
 
@@ -714,7 +756,7 @@ class LocalSandbox implements Sandbox {
 			throw new Error(`Sandbox ${this.id} is destroyed`)
 		}
 
-		const resolved = await resolveWithinReal(this.rootDir, rootPath)
+		const resolved = await resolveWithinAnyReal(this.roots, rootPath)
 		const root = await stat(resolved).catch(() => null)
 		if (!root || !root.isDirectory()) return []
 
@@ -739,6 +781,17 @@ class LocalSandbox implements Sandbox {
 		return entries
 	}
 
+	async *walkFiles(
+		rootPath: string,
+		options: SandboxWalkFilesOptions,
+	): AsyncGenerator<SandboxFileEntry> {
+		if (this._status === 'destroyed') throw new Error(`Sandbox ${this.id} is destroyed`)
+		options.signal?.throwIfAborted()
+		const resolved = await resolveWithinAnyReal(this.roots, rootPath)
+		options.signal?.throwIfAborted()
+		yield* walkFilesLocally(resolved, options)
+	}
+
 	async destroy(_options?: SandboxDestroyOptions): Promise<void> {
 		if (this._status === 'destroyed') {
 			return
@@ -759,6 +812,67 @@ class LocalSandbox implements Sandbox {
 	// Private helpers
 	// -----------------------------------------------------------------------
 
+	spawnDetached(
+		command: string,
+		args: readonly string[] = [],
+		opts?: SandboxSpawnOptions,
+	): SandboxDetachedProcess {
+		if (this._status === 'destroyed') {
+			throw new Error(`Sandbox ${this.id} is destroyed`)
+		}
+		// Lexical containment for the cwd: the caller does not wait, so
+		// neither does this. The mounts are the same ones `exec` uses.
+		const cwd = opts?.cwd ? resolveWithinAny(this.roots, opts.cwd) : this.rootDir
+		const { spawnCommand, spawnArgs, bwrapInfoFd, bwrapBlockFd } = this.buildSpawnArgs(command, [
+			...args,
+		])
+		const env = buildSafeEnv(this.config.env, opts?.env)
+		const child = spawn(spawnCommand, spawnArgs, {
+			cwd,
+			env,
+			stdio:
+				bwrapInfoFd === undefined
+					? ['ignore', 'pipe', 'pipe']
+					: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
+			detached: process.platform !== 'win32',
+		})
+		let bwrapChildPid: number | undefined
+		let requested: NodeJS.Signals | undefined
+		// Same dance as `exec`: bwrap's inner reaper is in its own session, so
+		// a kill has to reach it by the pid the info fd reports, and a kill
+		// asked for before that pid is known is delivered when it arrives.
+		const bwrapInfo = bwrapInfoFd === undefined ? undefined : child.stdio[bwrapInfoFd]
+		const bwrapBlock = bwrapBlockFd === undefined ? undefined : child.stdio[bwrapBlockFd]
+		let bwrapInfoBuffer = ''
+		bwrapInfo?.on('data', (chunk: Buffer) => {
+			if (bwrapChildPid !== undefined) return
+			bwrapInfoBuffer += chunk.toString('utf8')
+			const observed = readBwrapChildPid(bwrapInfoBuffer)
+			if (observed === undefined) return
+			bwrapChildPid = observed
+			if (requested !== undefined) {
+				killTree(child, 'SIGKILL')
+				killBwrapChild(bwrapChildPid, 'SIGKILL')
+			} else if (bwrapBlock !== undefined && bwrapBlock !== null && 'end' in bwrapBlock) {
+				bwrapBlock.end(Buffer.from([1]))
+			}
+		})
+		this.log.debug('Detached process started', {
+			'namzu.sandbox.command': command,
+			'namzu.sandbox.args': args,
+			'namzu.execution.environment': this.environment,
+		})
+		return {
+			child,
+			kill: (signal) => {
+				requested = signal
+				if (bwrapBlockFd !== undefined && bwrapChildPid === undefined) return
+				killTree(child, signal)
+				killBwrapChild(bwrapChildPid, signal)
+			},
+		}
+	}
+
 	private buildSpawnArgs(
 		command: string,
 		args: string[],
@@ -774,6 +888,9 @@ class LocalSandbox implements Sandbox {
 			command,
 			args,
 			rootDir: this.rootDir,
+			...(this.additionalDirectories.length > 0
+				? { additionalDirectories: this.additionalDirectories }
+				: {}),
 			...(this.config.memoryLimitMb !== undefined
 				? { memoryLimitMb: this.config.memoryLimitMb }
 				: {}),
@@ -1051,6 +1168,12 @@ export class LocalSandboxProvider implements SandboxProvider {
 				)
 			}
 			removeRootOnDestroy = false
+			for (const dir of config.additionalDirectories ?? []) {
+				const entry = await stat(resolve(dir)).catch(() => null)
+				if (!entry?.isDirectory()) {
+					throw new Error(`Sandbox additional directory is not a directory: ${resolve(dir)}`)
+				}
+			}
 		} else {
 			// No workspace was named: this allocation owns a fresh temporary root.
 			const { mkdtemp } = await import('node:fs/promises')

package/src/scheduler/completion-inbox.ts

@@ -231,38 +231,33 @@ export class CompletionInbox {
 	}
 
 	/**
-	 * Wait for the next completion, or for the deadline, whichever comes first.
+	 * Wait for the next completion, deadline or abort, whichever comes first.
+	 * Aborting releases only this waiter; work and undelivered results remain owned.
 	 *
 	 * Bounded on purpose. A worker that never finishes must not hold a run
 	 * open forever, and the caller decides how long "long enough" is — the
 	 * run's own budget is the only thing that knows.
 	 */
-	waitForArrival(timeoutMs: number): Promise<void> {
+	waitForArrival(timeoutMs: number, signal?: AbortSignal): Promise<void> {
+		if (signal?.aborted) return Promise.resolve()
 		if (this.unheard.size > 0) return Promise.resolve()
 		if (this.outstanding.size === 0) return Promise.resolve()
 
 		return new Promise((resolve) => {
+			const finish = (): void => {
+				clearTimeout(timer)
+				this.arrivals.delete(finish)
+				signal?.removeEventListener('abort', finish)
+				resolve()
+			}
 			const timer = setTimeout(finish, timeoutMs)
 			// `unref` where the runtime has it, so a pending wait never keeps
 			// a process alive past the work it was waiting for.
 			;(timer as { unref?: () => void }).unref?.()
 
-			function finish(): void {
-				clearTimeout(timer)
-				wake.done = true
-				resolve()
-			}
-
-			const wake = Object.assign(
-				() => {
-					if (!wake.done) {
-						this.arrivals.delete(wake)
-						finish()
-					}
-				},
-				{ done: false },
-			)
-			this.arrivals.add(wake)
+			this.arrivals.add(finish)
+			signal?.addEventListener('abort', finish, { once: true })
+			if (signal?.aborted) finish()
 		})
 	}
 
@@ -423,7 +418,21 @@ function neutralizeNotificationDelimiter(content: string): string {
 export function formatCompletionNotification(handles: readonly TaskHandle[]): string {
 	const blocks = handles.map((handle) => {
 		const durationMs = handle.completedAt ? handle.completedAt - handle.createdAt : undefined
-		const output = handle.result?.result ?? handle.result?.lastError ?? ''
+		const run = handle.result
+		let output = run?.result || run?.lastError || ''
+		// A hard guard can stop immediately after a tool round, before the result
+		// assembler has a final answer. Preserve visible partial prose, never reasoning.
+		if (!output && run?.stopReason && run.stopReason !== 'end_turn') {
+			const partial = [...(run.messages ?? [])]
+				.reverse()
+				.find(
+					(message) =>
+						message.role === 'assistant' &&
+						typeof message.content === 'string' &&
+						message.content.length > 0,
+				)
+			if (partial) output = `Partial output before ${run.stopReason}:\n${partial.content}`
+		}
 		const overLimit = output.length > NOTIFICATION_OUTPUT_LIMIT
 		const shown = overLimit ? output.slice(0, NOTIFICATION_OUTPUT_LIMIT) : output
 
@@ -455,6 +464,7 @@ export function formatCompletionNotification(handles: readonly TaskHandle[]): st
 			`task_id: ${handle.taskId}`,
 			`agent: ${handle.agentId}`,
 			`state: ${handle.state}`,
+			...(handle.result?.stopReason ? [`stop_reason: ${handle.result.stopReason}`] : []),
 			...(durationMs !== undefined ? [`duration_ms: ${durationMs}`] : []),
 			'',
 			body,

package/src/scheduler/delegating.ts

@@ -3,9 +3,9 @@ import type { Delegate, DelegateRequest, DelegateResult } from '../types/agent/d
 import type { CreateTaskOptions, TaskHandle, TaskScheduler } from '../types/agent/scheduler.js'
 import type { AgentTaskState } from '../types/agent/task.js'
 import type { RunExecutionStatus } from '../types/common/index.js'
-import type { TaskId } from '../types/ids/index.js'
+import type { RunId, TaskId } from '../types/ids/index.js'
 import { type CancelCause, RunCancelled } from '../types/run/cancel-cause.js'
-import { asRunId, generateTaskId } from '../utils/id.js'
+import { generateRunId, generateTaskId } from '../utils/id.js'
 
 /**
  * Presents a set of foreign delegates as a `TaskScheduler`.
@@ -113,6 +113,7 @@ const OUTCOME: Record<
 
 interface Entry {
 	handle: TaskHandle
+	runId: RunId
 	delegate: Delegate
 	controller: AbortController
 	settled: Promise<void>
@@ -135,7 +136,10 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 				// Checked at registration, not at the call. A capability that
 				// claims a method the object does not have is a lie the caller
 				// would otherwise find mid-delegation, with a worker running.
-				throw new DelegateCapabilityMismatchError({ id: delegate.id, capability: 'continue' })
+				throw new DelegateCapabilityMismatchError({
+					id: delegate.id,
+					capability: 'continue',
+				})
 			}
 			this.byId.set(delegate.id, delegate)
 		}
@@ -146,6 +150,10 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 		return this.byId.get(agentId)
 	}
 
+	get budget() {
+		return this.config.local?.budget
+	}
+
 	async createTask(options: CreateTaskOptions): Promise<TaskHandle> {
 		const delegate = this.byId.get(options.agentId)
 		if (!delegate) {
@@ -153,6 +161,12 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 			return await this.config.local.createTask(options)
 		}
 
+		if (this.budget) {
+			throw new Error(
+				'Foreign delegates cannot run under a shared token budget without a metering contract',
+			)
+		}
+
 		const taskId = generateTaskId()
 		const controller = new AbortController()
 		const request: DelegateRequest = {
@@ -163,6 +177,7 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 		}
 
 		const entry: Entry = {
+			runId: generateRunId(),
 			handle: {
 				taskId,
 				agentId: options.agentId,
@@ -178,7 +193,9 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 		entry.settled = (async () => {
 			let result: DelegateResult
 			try {
-				result = await delegate.dispatch(request, { signal: controller.signal })
+				result = await delegate.dispatch(request, {
+					signal: controller.signal,
+				})
 			} catch (err) {
 				// A delegate that threw failed; it did not vanish. Leaving the
 				// handle `running` would have `waitForTask` hang forever on a
@@ -188,25 +205,24 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 					error: err instanceof Error ? err.message : String(err),
 				}
 			}
-			entry.handle = this.settle(entry.handle, result)
+			entry.handle = this.settle(entry.handle, entry.runId, result)
 			for (const listener of this.listeners) listener(entry.handle)
 		})()
 
 		return entry.handle
 	}
 
-	private settle(handle: TaskHandle, result: DelegateResult): TaskHandle {
+	private settle(handle: TaskHandle, runId: RunId, result: DelegateResult): TaskHandle {
 		const outcome = OUTCOME[result.status]
 		return {
 			...handle,
 			state: outcome.state,
 			completedAt: Date.now(),
 			result: {
-				// A synthetic run record. The id names the task rather than
-				// borrowing a run id that does not exist: a foreign delegate has
-				// no run in this kernel, and minting a plausible-looking `run_`
-				// would put an id in the transcript that nothing can resolve.
-				runId: asRunId(`run_delegate_${handle.taskId}`),
+				// Identity of this dispatch, allocated once with its task. The
+				// scheduler owns the correlation; the ID's spelling carries none.
+				// A foreign dispatch does not imply a local resumable checkpoint.
+				runId,
 				status: outcome.status,
 				// Zero, and honestly so: this kernel did not spend these tokens
 				// and has no way to learn what the delegate spent. `ZERO_COST`
@@ -244,7 +260,10 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 			// Refused, not silently dropped. A no-op here has the parent
 			// believe it steered a worker that never heard it — and it would
 			// go on believing that until the answer came back unchanged.
-			throw new DelegateCapabilityError({ id: entry.delegate.id, capability: 'continue' })
+			throw new DelegateCapabilityError({
+				id: entry.delegate.id,
+				capability: 'continue',
+			})
 		}
 		await entry.delegate.continue(message)
 	}
@@ -256,7 +275,10 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 			return
 		}
 		if (!entry.delegate.capabilities.cancel) {
-			throw new DelegateCapabilityError({ id: entry.delegate.id, capability: 'cancel' })
+			throw new DelegateCapabilityError({
+				id: entry.delegate.id,
+				capability: 'cancel',
+			})
 		}
 		controllerAbort(entry, cause)
 	}

package/src/scheduler/local.ts

@@ -97,6 +97,10 @@ export class LocalTaskScheduler implements TaskScheduler {
 		}
 	}
 
+	get budget() {
+		return this.taskContext.budget
+	}
+
 	async createTask(options: CreateTaskOptions): Promise<TaskHandle> {
 		// Filled once the spawn resolves. A box rather than a bare binding
 		// because the assignment happens AFTER the `await` that the reader is
@@ -140,13 +144,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 						}
 					: {}),
 			},
-			// The budget tracker is SHARED on purpose and must not be cloned.
-			// `AgentManager.spawn` debits it (`remaining -= allocatedTokens`)
-			// so siblings divide one pool; handing each spawn a fresh copy
-			// made the debit land on a throwaway object, so every child saw
-			// the parent's untouched `remaining` and N children were each
-			// allocated `maxBudgetFraction` of the SAME number — N x 50% of a
-			// budget that only had 100% in it.
+			// Every sibling reserves from this same authority before provisioning.
 			this.taskContext,
 			// The host's listener still sees everything it always did; this
 			// only tees off the fact that SOMETHING happened, which is what an

package/src/session/index.ts

@@ -11,6 +11,5 @@ export * from './workspace/index.js'
 export * from './handoff/index.js'
 export * from './summary/index.js'
 export * from './intervention/index.js'
-export * from './migration/index.js'
 export * from './retention/index.js'
 export { TenantIsolationError, WorkspaceBackendError, AncestryCycleError } from './errors.js'

package/src/session/workspace/path-builder.ts

@@ -24,6 +24,7 @@
 import { join } from 'node:path'
 import type { ProjectId, RunId, SessionId } from '../../types/ids/index.js'
 import type { SubSessionId } from '../../types/session/ids.js'
+import { asProjectId, asRunId, asSessionId, asSubSessionId } from '../../utils/id.js'
 
 /**
  * Canonical filesystem layout contract. All paths returned are absolute
@@ -54,18 +55,18 @@ export class DefaultPathBuilder implements PathBuilder {
 	}
 
 	projectDir(projectId: ProjectId): string {
-		return join(this.root, 'projects', projectId)
+		return join(this.root, 'projects', asProjectId(projectId))
 	}
 
 	sessionDir(projectId: ProjectId, sessionId: SessionId): string {
-		return join(this.projectDir(projectId), 'sessions', sessionId)
+		return join(this.projectDir(projectId), 'sessions', asSessionId(sessionId))
 	}
 
 	subSessionDir(projectId: ProjectId, sessionId: SessionId, subSessionId: SubSessionId): string {
-		return join(this.sessionDir(projectId, sessionId), 'subsessions', subSessionId)
+		return join(this.sessionDir(projectId, sessionId), 'subsessions', asSubSessionId(subSessionId))
 	}
 
 	runDir(projectId: ProjectId, sessionId: SessionId, runId: RunId): string {
-		return join(this.sessionDir(projectId, sessionId), 'runs', runId)
+		return join(this.sessionDir(projectId, sessionId), 'runs', asRunId(runId))
 	}
 }

package/src/store/feedback/disk.ts

@@ -58,9 +58,8 @@ export interface DiskMessageFeedbackStoreConfig {
 
 /** Filesystem-safe file name for one rated message. */
 function fileName(messageId: MessageId): string {
-	// Message ids are `msg_` + an alphabet with no separators, so this is a
-	// pass-through today. Written as a function anyway: the day an id gains
-	// a `/` is the day this silently starts writing outside its directory.
+	// Retain the historical projection spelling. Callers validate the id
+	// first, so suffixes this replacement once flattened are now rejected.
 	return `${messageId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`
 }
 
@@ -119,9 +118,8 @@ export class DiskMessageFeedbackStore implements MessageFeedbackStore {
 		return {
 			legacyPath: join(this.runDir(runId), legacyName),
 			revisionsDir: join(this.revisionsDir(runId), revisionFileSegment(checkedMessageId)),
-			// The previous filename replacement is lossy for punctuation and
-			// separators. Read such a legacy path forward if it exists, but never
-			// publish a new projection that could overwrite another message's file.
+			// Preserve the projection guard from the previous layout. Checked ids
+			// now retain their spelling; unsafe custom suffixes are rejected above.
 			publishLegacyProjection: legacyName === `${checkedMessageId}.json`,
 		}
 	}

package/src/store/index.ts

@@ -6,6 +6,8 @@ export { InMemoryRunStore } from './run/memory.js'
 export { DiskCheckpointStore } from './run/checkpoint-disk.js'
 export type { DiskCheckpointStoreAttribution } from './run/checkpoint-disk.js'
 export { InMemoryCheckpointStore } from './run/checkpoint-memory.js'
+export { DiskTokenBudgetStore, openTokenBudget } from './run/token-budget-disk.js'
+export type { DiskTokenBudgetStoreConfig, OpenTokenBudgetOptions } from './run/token-budget-disk.js'
 // The refusing entry point to the optional listing capability, plus the two
 // projections a host implementing its own backend actually calls: one turns
 // a run's checkpoints into a row, the other applies the contract's filter,

package/src/store/memory/disk.ts

@@ -10,7 +10,7 @@ import type {
 	MemorySearchResult,
 	MemoryStore,
 } from '../../types/memory/index.js'
-import { asMemoryId, generateMemoryId } from '../../utils/id.js'
+import { generateMemoryId, isEntityId } from '../../utils/id.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { DiskRecordStore } from '../kv/record-store.js'
@@ -27,8 +27,6 @@ import { InMemoryMemoryIndex } from './index.js'
  */
 const SCHEMA = defineSchema({ kind: 'memory-store', current: 1, migrations: {} })
 
-const SAFE_STORAGE_ID = /^mem_[A-Za-z0-9_-]+$/
-
 interface StorageLocation {
 	readonly indexPath: string
 	readonly contentDir: string
@@ -83,14 +81,8 @@ function assertStorageMemoryId(
 	value: unknown,
 	refuse: (reason: string) => never,
 ): asserts value is MemoryId {
-	if (typeof value !== 'string') refuse('id must be a memory ID string')
-	try {
-		asMemoryId(value)
-	} catch {
-		refuse('id must use the recognized mem_ prefix')
-	}
-	if (!SAFE_STORAGE_ID.test(value)) {
-		refuse('id must be one cross-platform safe filename segment')
+	if (!isEntityId(value, 'memory')) {
+		refuse('id must be a UUID; prefixed memory IDs are not supported')
 	}
 }