@namzu/sdk 34.2.0 → 35.0.0

package/src/sandbox/provider/local.ts

@@ -25,18 +25,20 @@ 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,
 } from '../../types/sandbox/index.js'
 import { subscribeToAbort } from '../../utils/abort.js'
@@ -208,6 +210,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 +269,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 +281,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 +379,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 +433,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 +463,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 +562,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 +626,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 +650,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 +680,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 +729,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 +745,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 +754,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 []
 
@@ -759,6 +799,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 +875,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 +1155,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/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')
 	}
 }
 

package/src/store/run/checkpoint-disk.ts

@@ -16,6 +16,7 @@ import type {
 } from '../../types/run/checkpoint-store.js'
 import type { RunStoreConfig } from '../../types/run/index.js'
 import type { ProjectId } from '../../types/session/ids.js'
+import { asRunId, isEntityId } from '../../utils/id.js'
 import { acquireClaim, currentFence, readClaim, releaseClaim } from './claim-disk.js'
 import { RunDiskStore, readCheckpointsIn } from './disk.js'
 import {
@@ -56,14 +57,14 @@ export interface DiskCheckpointStoreAttribution {
  * participate in directory resolution — `tenantId`/`projectId`/`sessionId`
  * exist for backends that key by attribution instead of path.
  *
- * One `RunDiskStore` is bound (and its run directory created) per distinct
- * `runId`, then cached, so repeated checkpoint operations against the same
- * run don't re-run `initRun`.
+ * One `RunDiskStore` is bound per resolved run directory, then cached, so
+ * repeated checkpoint operations against the same run don't re-run `initRun`.
+ * Parent attribution remains part of the address even when a cache is warm.
  */
 export class DiskCheckpointStore implements CheckpointStore {
 	private readonly config: RunStoreConfig
 	private readonly attribution?: DiskCheckpointStoreAttribution
-	private readonly bound = new Map<RunId, Promise<RunDiskStore>>()
+	private readonly bound = new Map<string, Promise<RunDiskStore>>()
 
 	/**
 	 * @param config the run-store config; `baseDir` is one session's `runs/`
@@ -79,17 +80,18 @@ export class DiskCheckpointStore implements CheckpointStore {
 	}
 
 	private bind(scope: CheckpointRunScope): Promise<RunDiskStore> {
-		const cached = this.bound.get(scope.runId)
+		const path = this.runDir(scope)
+		const cached = this.bound.get(path)
 		if (cached) return cached
 		const promise = (async () => {
 			const store = new RunDiskStore(this.config)
 			await store.initRun(scope.runId, scope.parentRunId)
 			return store
 		})()
-		this.bound.set(scope.runId, promise)
+		this.bound.set(path, promise)
 		// A failed bind must not poison the cache — the next call retries.
 		promise.catch(() => {
-			this.bound.delete(scope.runId)
+			this.bound.delete(path)
 		})
 		return promise
 	}
@@ -130,6 +132,8 @@ export class DiskCheckpointStore implements CheckpointStore {
 	 * the two stay together if the layout ever moves.
 	 */
 	private runDir(scope: CheckpointRunScope): string {
+		asRunId(scope.runId)
+		if (scope.parentRunId !== undefined) asRunId(scope.parentRunId)
 		return scope.parentRunId
 			? join(this.config.baseDir, scope.parentRunId, 'children', scope.runId)
 			: join(this.config.baseDir, scope.runId)
@@ -247,27 +251,10 @@ export class DiskCheckpointStore implements CheckpointStore {
 	private async readRunDirs(dir: string): Promise<RunId[]> {
 		try {
 			const found = await readdir(dir, { withFileTypes: true })
-			// Filtered by prefix, not just by "is a directory", so the declared
-			// `RunId[]` is true of what comes back. An editor's scratch folder or
-			// a `tmp-` left by a crashed write is not a run, and the assertion
-			// below is what let it be returned as one.
-			//
-			// **Unobservable through `listDurableRuns` today, and kept
-			// deliberately.** Measured, not assumed: removing this filter, and
-			// separately weakening it to `startsWith('r')`, leaves every test in
-			// this package green. `toDurableRunEntry` returns undefined for a
-			// directory with no checkpoints in it, so a junk name is already
-			// dropped one layer down — the filter saves the `readdir` and the
-			// parse, not a wrong answer. It is here because `readRunDirs` is a
-			// private helper with two callers and a declared element type, and
-			// the next caller inherits the type rather than the accident that
-			// currently covers for it.
-			//
-			// Filtered rather than refused, whatever the reach: a scan that
-			// threw on one piece of junk could not list the runs that are fine,
-			// during exactly the incident this listing exists for.
+			// The directory supplies the entity kind. Admit current and legacy
+			// run IDs; ignore scratch entries without hiding durable UUID runs.
 			return found
-				.filter((e) => e.isDirectory() && e.name.startsWith('run_'))
+				.filter((e) => e.isDirectory() && isEntityId(e.name, 'run'))
 				.map((e) => e.name as RunId)
 		} catch (err) {
 			if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []

package/src/store/run/claim-disk.ts

@@ -275,7 +275,7 @@ const NO_LINK = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EXDEV', 'E
  *
  * Some filesystems — a few network and removable volumes — support no hard
  * link at all. **This refuses rather than falling back**, per
- * [refuse-do-not-degrade](../../../../../docs/conventions/refuse-do-not-degrade.md).
+ * [refuse-do-not-degrade](../../../../../"refuse do not degrade").
  * The only available fallback is the `wx` publish this replaced, and that one
  * carries the defect described in the module header: two workers restore and
  * run the same run. A claim that silently becomes non-exclusive is worse than