@namzu/sdk 34.2.0 → 35.0.0

package/src/store/session/disk.ts

@@ -53,10 +53,15 @@ import type {
 	SessionSummaryRef,
 } from '../../types/summary/ref.js'
 import {
+	asProjectId,
+	asSessionId,
+	asSubSessionId,
+	asTopicId,
 	generateMessageId,
 	generateProjectId,
 	generateSessionId,
 	generateSubSessionId,
+	isEntityId,
 } from '../../utils/id.js'
 import { DiskRecordStore } from '../kv/record-store.js'
 import {
@@ -151,26 +156,19 @@ const rootPathBindings = new DiskRevisionRecordStore<RootPathBinding>(
 )
 
 /**
- * v2 → v3: NZ-TOPIC-04 narrows the Topic id prefix from `thd_` to `top_`.
- * The FIELD is already `topicId` (the v1→v2 step above handled that); this
- * step rewrites only the VALUE, and only when it still carries the old
- * prefix — a record already at v3, or one that just arrived here via the
- * v1→v2 step in the same `migrate()` call, has `topicId` starting `top_`
- * (or `thd_`, freshly renamed from `threadId` — this step runs on it next
- * in the same pass) either way, and the check below is what makes running
- * it on an already-correct value a same-object no-op rather than a
- * needless copy. Same one-function-runs-over-every-kind shape as its
- * v1→v2 sibling: only `PersistedSession.topicId` is ever `thd_`-prefixed,
- * so every other kind this schema stamps (project.json, subsession.json,
- * summary.json, each messages.jsonl line) has no `topicId` key and comes
- * back untouched.
+ * Validate topic UUIDs before accepting a stored record. Prefixed IDs are
+ * rejected without rewriting stored references.
+ * This migrator runs over every session-store record kind; records without
+ * a topicId are intentionally untouched.
  */
 export function migrateSessionStoreTopicIdPrefix(
 	record: Record<string, unknown>,
 ): Record<string, unknown> {
 	const topicId = record.topicId
-	if (typeof topicId !== 'string' || !topicId.startsWith('thd_')) return record
-	return { ...record, topicId: `top_${topicId.slice('thd_'.length)}` }
+	if (typeof topicId === 'string') {
+		asTopicId(topicId)
+	}
+	return record
 }
 
 /**
@@ -567,6 +565,7 @@ export class DiskSessionStore implements SessionStore {
 
 		const found: Project[] = []
 		for (const entry of entries) {
+			if (!isEntityId(entry, 'project')) continue
 			const raw = await records.read<PersistedProject>(join(projectsRoot, entry, 'project.json'))
 			if (!raw) continue
 			// Another tenant's project is absent, not an error — a listing is a
@@ -585,13 +584,17 @@ export class DiskSessionStore implements SessionStore {
 	// Session CRUD ------------------------------------------------------------
 
 	async createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session> {
+		const id = params.id === undefined ? generateSessionId() : asSessionId(params.id)
 		const project = await this.getProject(params.projectId, tenantId)
 		if (!project) {
 			throw new Error(`Project ${params.projectId} not found`)
 		}
 		const now = new Date()
+		if (params.id !== undefined && (await this.getSession(id, tenantId))) {
+			throw new Error(`Session ${params.id} already exists`)
+		}
 		const session: Session = {
-			id: generateSessionId(),
+			id,
 			topicId: params.topicId,
 			projectId: params.projectId,
 			tenantId,
@@ -647,11 +650,11 @@ export class DiskSessionStore implements SessionStore {
 
 		const results: Session[] = []
 		for (const rawProject of projectDirs) {
-			if (!rawProject.startsWith('prj_')) continue
+			if (!isEntityId(rawProject, 'project')) continue
 			const sessionsRoot = join(projectsDir, rawProject, 'sessions')
 			const sessionDirs = await records.scanNames(sessionsRoot, '')
 			for (const rawSessionId of sessionDirs) {
-				if (!rawSessionId.startsWith('ses_')) continue
+				if (!isEntityId(rawSessionId, 'session')) continue
 				const path = join(sessionsRoot, rawSessionId)
 				const raw = await records.read<PersistedSession>(join(path, 'session.json'))
 				if (!raw) continue
@@ -682,7 +685,7 @@ export class DiskSessionStore implements SessionStore {
 
 		const results: Session[] = []
 		for (const rawSessionId of sessionDirs) {
-			if (!rawSessionId.startsWith('ses_')) continue
+			if (!isEntityId(rawSessionId, 'session')) continue
 			const path = join(sessionsRoot, rawSessionId)
 			const raw = await records.read<PersistedSession>(join(path, 'session.json'))
 			if (!raw) continue
@@ -747,7 +750,7 @@ export class DiskSessionStore implements SessionStore {
 		// match the in-memory semantics.
 		const subsDir = join(located.path, 'subsessions')
 		const subEntries = await records.scanNames(subsDir, '')
-		if (subEntries.some((e) => e.startsWith('sub_'))) {
+		if (subEntries.some((entry) => isEntityId(entry, 'subSession'))) {
 			throw new Error(
 				`Session ${sessionId} has attached sub-sessions; delete them before deleting the session`,
 			)
@@ -761,15 +764,15 @@ export class DiskSessionStore implements SessionStore {
 		const projectsDir = join(this.rootDir, 'projects')
 		const projectDirs = await records.scanNames(projectsDir, '')
 		for (const rawProject of projectDirs) {
-			if (!rawProject.startsWith('prj_')) continue
+			if (!isEntityId(rawProject, 'project')) continue
 			const sessionsRoot = join(projectsDir, rawProject, 'sessions')
 			const siblingSessions = await records.scanNames(sessionsRoot, '')
 			for (const rawSib of siblingSessions) {
-				if (!rawSib.startsWith('ses_')) continue
+				if (!isEntityId(rawSib, 'session')) continue
 				const sibSubsDir = join(sessionsRoot, rawSib, 'subsessions')
 				const sibSubs = await records.scanNames(sibSubsDir, '')
 				for (const rawSub of sibSubs) {
-					if (!rawSub.startsWith('sub_')) continue
+					if (!isEntityId(rawSub, 'subSession')) continue
 					const subRaw = await records.read<PersistedSubSession>(
 						join(sibSubsDir, rawSub, 'subsession.json'),
 					)
@@ -1091,6 +1094,7 @@ export class DiskSessionStore implements SessionStore {
 	}
 
 	private projectDir(projectId: ProjectId): string {
+		asProjectId(projectId)
 		const cached = this.projectIndex.get(projectId)
 		if (cached) return cached.path
 		const path = join(this.rootDir, 'projects', projectId)
@@ -1099,6 +1103,7 @@ export class DiskSessionStore implements SessionStore {
 	}
 
 	private async locateSession(sessionId: SessionId): Promise<SessionIndexEntry | null> {
+		asSessionId(sessionId)
 		const cached = this.sessionIndex.get(sessionId)
 		if (cached) return cached
 
@@ -1107,12 +1112,12 @@ export class DiskSessionStore implements SessionStore {
 		// same `return null` the old catch took directly.
 		const projectDirs = await records.scanNames(projectsDir, '')
 		for (const rawId of projectDirs) {
-			if (!rawId.startsWith('prj_')) continue
+			if (!isEntityId(rawId, 'project')) continue
 			const projectId = rawId as ProjectId
 			const sessionsRoot = join(projectsDir, projectId, 'sessions')
 			const sessionDirs = await records.scanNames(sessionsRoot, '')
 			for (const rawSessionId of sessionDirs) {
-				if (!rawSessionId.startsWith('ses_')) continue
+				if (!isEntityId(rawSessionId, 'session')) continue
 				if (rawSessionId === sessionId) {
 					const entry: SessionIndexEntry = {
 						sessionId,
@@ -1133,6 +1138,7 @@ export class DiskSessionStore implements SessionStore {
 		projectId: ProjectId
 		path: string
 	} | null> {
+		asSubSessionId(subSessionId)
 		const cached = this.subSessionIndex.get(subSessionId)
 		if (cached) return cached
 
@@ -1141,12 +1147,12 @@ export class DiskSessionStore implements SessionStore {
 		// same `return null` the old catch took directly.
 		const projectDirs = await records.scanNames(projectsDir, '')
 		for (const rawProject of projectDirs) {
-			if (!rawProject.startsWith('prj_')) continue
+			if (!isEntityId(rawProject, 'project')) continue
 			const projectId = rawProject as ProjectId
 			const sessionsRoot = join(projectsDir, projectId, 'sessions')
 			const sessionDirs = await records.scanNames(sessionsRoot, '')
 			for (const rawSession of sessionDirs) {
-				if (!rawSession.startsWith('ses_')) continue
+				if (!isEntityId(rawSession, 'session')) continue
 				const sessionId = rawSession as SessionId
 				const subsDir = join(sessionsRoot, sessionId, 'subsessions')
 				const subDirs = await records.scanNames(subsDir, '')
@@ -1177,14 +1183,15 @@ export class DiskSessionStore implements SessionStore {
 		const projectDirs = await records.scanNames(projectsDir, '')
 
 		for (const rawProject of projectDirs) {
-			if (!rawProject.startsWith('prj_')) continue
+			if (!isEntityId(rawProject, 'project')) continue
 			const sessionsRoot = join(projectsDir, rawProject, 'sessions')
 			const sessionDirs = await records.scanNames(sessionsRoot, '')
 			for (const rawSession of sessionDirs) {
-				if (!rawSession.startsWith('ses_')) continue
+				if (!isEntityId(rawSession, 'session')) continue
 				const subsRoot = join(sessionsRoot, rawSession, 'subsessions')
 				const subDirs = await records.scanNames(subsRoot, '')
 				for (const rawSub of subDirs) {
+					if (!isEntityId(rawSub, 'subSession')) continue
 					const raw = await records.read<PersistedSubSession>(
 						join(subsRoot, rawSub, 'subsession.json'),
 					)

package/src/store/session/memory.ts

@@ -8,6 +8,8 @@
  * (Convention #5 deny-by-default, session-hierarchy.md §12.2).
  */
 
+import { realpathSync } from 'node:fs'
+import { resolve } from 'node:path'
 import {
 	ProjectRootPathTakenError,
 	StaleProjectError,
@@ -32,6 +34,8 @@ import type {
 import type { SubSession } from '../../types/session/sub-session.js'
 import type { SessionSummaryRef } from '../../types/summary/ref.js'
 import {
+	asProjectId,
+	asTenantId,
 	generateMessageId,
 	generateProjectId,
 	generateSessionId,
@@ -80,6 +84,36 @@ export class InMemorySessionStore implements SessionStore {
 	private readonly messages = new Map<SessionId, SessionMessage[]>()
 	private readonly summaries = new Map<SessionId, SummaryRecord>()
 
+	/** Hydrate existing Project snapshots without minting replacement identities. */
+	constructor(projects: readonly Project[] = []) {
+		const roots = new Map<string, ProjectId>()
+		for (const input of projects) {
+			const project = structuredClone(input)
+			asProjectId(project.id)
+			asTenantId(project.tenantId)
+			if (this.projects.has(project.id)) throw new Error(`Duplicate project ${project.id}`)
+			if (project.rootPath !== undefined) {
+				let rootPath: string
+				try {
+					rootPath = realpathSync(project.rootPath)
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+					rootPath = resolve(project.rootPath)
+				}
+				const key = `${project.tenantId}\0${rootPath}`
+				const existingProjectId = roots.get(key)
+				if (existingProjectId) throw new ProjectRootPathTakenError({ rootPath, existingProjectId })
+				roots.set(key, project.id)
+				this.projects.set(project.id, {
+					tenantId: project.tenantId,
+					project: { ...project, rootPath },
+				})
+			} else {
+				this.projects.set(project.id, { tenantId: project.tenantId, project })
+			}
+		}
+	}
+
 	// Project CRUD ------------------------------------------------------------
 
 	async createProject(params: CreateProjectParams, tenantId: TenantId): Promise<Project> {
@@ -229,8 +263,11 @@ export class InMemorySessionStore implements SessionStore {
 		this.assertTenant(projectRecord.tenantId, tenantId, `project(${params.projectId})`)
 
 		const now = new Date()
+		if (params.id !== undefined && (await this.getSession(params.id, tenantId))) {
+			throw new Error(`Session ${params.id} already exists`)
+		}
 		const session: Session = {
-			id: generateSessionId(),
+			id: params.id ?? generateSessionId(),
 			topicId: params.topicId,
 			projectId: params.projectId,
 			tenantId,

package/src/store/task/disk.ts

@@ -11,7 +11,7 @@ import type {
 	TaskStore,
 	UpdateTaskParams,
 } from '../../types/task/index.js'
-import { generateTaskId } from '../../utils/id.js'
+import { asRunId, asTaskId, asTenantId, generateTaskId, 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'
@@ -82,12 +82,13 @@ export class DiskTaskStore implements TaskStore {
 
 	constructor(config: DiskTaskStoreConfig) {
 		this.baseDir = config.baseDir
-		this.defaultRunId = config.defaultRunId
-		this.tenantId = config.tenantId
+		this.defaultRunId = asRunId(config.defaultRunId)
+		this.tenantId = config.tenantId === undefined ? undefined : asTenantId(config.tenantId)
 		this.log = resolveLogger(config.logger).child({ [SCOPE_ATTRIBUTE]: 'store/task/disk' })
 	}
 
 	private taskDir(runId: RunId): string {
+		asRunId(runId)
 		if (this.tenantId) {
 			return join(this.baseDir, 'tenants', this.tenantId, 'tasks', runId)
 		}
@@ -95,6 +96,7 @@ export class DiskTaskStore implements TaskStore {
 	}
 
 	private taskPath(runId: RunId, taskId: TaskId): string {
+		asTaskId(taskId)
 		return join(this.taskDir(runId), `${taskId}.json`)
 	}
 
@@ -498,12 +500,9 @@ export class DiskTaskStore implements TaskStore {
 			: join(this.baseDir, 'tasks')
 		try {
 			const entries = await readdir(root, { withFileTypes: true })
-			// Prefix-filtered for the reason `DiskCheckpointStore.readRunDirs`
-			// gives, including the honest half: a directory that is not a run must
-			// not be enumerated as one, this is not observable downstream today,
-			// and it is the declared return type that makes it worth keeping.
+			// The tasks directory identifies runs; either ID encoding is valid.
 			return entries
-				.filter((e) => e.isDirectory() && e.name.startsWith('run_'))
+				.filter((e) => e.isDirectory() && isEntityId(e.name, 'run'))
 				.map((e) => e.name as RunId)
 		} catch (err) {
 			const code = (err as NodeJS.ErrnoException).code

package/src/store/topic/memory.ts

@@ -19,7 +19,7 @@ import type { TenantId } from '../../types/ids/index.js'
 import type { ProjectId, TopicId } from '../../types/session/ids.js'
 import type { Topic } from '../../types/topic/entity.js'
 import type { CreateTopicParams, TopicStore } from '../../types/topic/store.js'
-import { generateTopicId } from '../../utils/id.js'
+import { asProjectId, asTenantId, asTopicId, generateTopicId } from '../../utils/id.js'
 
 interface TopicRecord {
 	tenantId: TenantId
@@ -29,6 +29,18 @@ interface TopicRecord {
 export class InMemoryTopicStore implements TopicStore {
 	private readonly topics = new Map<TopicId, TopicRecord>()
 
+	/** Hydrate existing Topic snapshots without creating new topic identities. */
+	constructor(topics: readonly Topic[] = []) {
+		for (const input of topics) {
+			const topic = structuredClone(input)
+			asTopicId(topic.id)
+			asProjectId(topic.projectId)
+			asTenantId(topic.tenantId)
+			if (this.topics.has(topic.id)) throw new Error(`Duplicate topic ${topic.id}`)
+			this.topics.set(topic.id, { tenantId: topic.tenantId, topic })
+		}
+	}
+
 	async createTopic(params: CreateTopicParams, tenantId: TenantId): Promise<Topic> {
 		const now = new Date()
 		const topic: Topic = {

package/src/test-support/ids.ts

@@ -1,22 +1,6 @@
-/**
- * Unchecked id constructors, for fixtures only.
- *
- * A test that needs three hundred distinct ids is not testing prefix
- * validation, and paying a `startsWith` per literal to say `ses_1` buys it
- * nothing. These are the cheap landing zone for that: same call shape as the
- * `as*Id` constructors in `utils/id.ts`, no check.
- *
- * **Deliberately NOT exported from the package barrel.** The whole value of
- * the checked constructors is that a malformed id cannot reach a store key,
- * and an unchecked one on the public surface is a supported way around that.
- * `test-support/` is reachable from inside this repo and nowhere else, which
- * is exactly the reach this needs.
- *
- * Two shapes rather than forty functions, because a fixture wants brevity:
- * `fixtureId.run('a')` reads at the call site, and `unchecked<RunId>(s)`
- * covers anything the table misses.
- */
+/** Deterministic UUID fixtures. Deliberately absent from the package barrel. */
 
+import { createHash } from 'node:crypto'
 import { unsafeId } from '../types/ids/brand.js'
 import type {
 	ActivityId,
@@ -66,52 +50,71 @@ export function unchecked<T extends string>(value: string): T {
 	return unsafeId<T>(value)
 }
 
+/** Maps a readable fixture label to a stable, valid UUID without global state. */
+export function fixtureUuid(label: string): string {
+	const bytes = createHash('sha256').update(label).digest().subarray(0, 16)
+	bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40
+	bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80
+	const hex = bytes.toString('hex')
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
 /**
- * One entry per prefixed id type, keyed by the bare concept rather than the
+ * One entry per entity type, keyed by the bare concept rather than the
  * type name — `fixtureId.run('a')`, not `fixtureId.RunId('a')`.
  */
 export const fixtureId = {
-	run: (suffix: string): RunId => unsafeId<RunId>(`run_${suffix}`),
-	message: (suffix: string): MessageId => unsafeId<MessageId>(`msg_${suffix}`),
-	session: (suffix: string): SessionId => unsafeId<SessionId>(`ses_${suffix}`),
-	toolCall: (suffix: string): ToolCallId => unsafeId<ToolCallId>(`call_${suffix}`),
-	activity: (suffix: string): ActivityId => unsafeId<ActivityId>(`act_${suffix}`),
-	task: (suffix: string): TaskId => unsafeId<TaskId>(`task_${suffix}`),
-	plan: (suffix: string): PlanId => unsafeId<PlanId>(`plan_${suffix}`),
-	knowledgeBase: (suffix: string): KnowledgeBaseId => unsafeId<KnowledgeBaseId>(`kb_${suffix}`),
-	document: (suffix: string): DocumentId => unsafeId<DocumentId>(`doc_${suffix}`),
-	chunk: (suffix: string): ChunkId => unsafeId<ChunkId>(`chk_${suffix}`),
-	connector: (suffix: string): ConnectorId => unsafeId<ConnectorId>(`conn_${suffix}`),
+	run: (suffix: string): RunId => unsafeId<RunId>(fixtureUuid(`run_${suffix}`)),
+	message: (suffix: string): MessageId => unsafeId<MessageId>(fixtureUuid(`msg_${suffix}`)),
+	session: (suffix: string): SessionId => unsafeId<SessionId>(fixtureUuid(`ses_${suffix}`)),
+	toolCall: (suffix: string): ToolCallId => unsafeId<ToolCallId>(fixtureUuid(`call_${suffix}`)),
+	activity: (suffix: string): ActivityId => unsafeId<ActivityId>(fixtureUuid(`act_${suffix}`)),
+	task: (suffix: string): TaskId => unsafeId<TaskId>(fixtureUuid(`task_${suffix}`)),
+	plan: (suffix: string): PlanId => unsafeId<PlanId>(fixtureUuid(`plan_${suffix}`)),
+	knowledgeBase: (suffix: string): KnowledgeBaseId =>
+		unsafeId<KnowledgeBaseId>(fixtureUuid(`kb_${suffix}`)),
+	document: (suffix: string): DocumentId => unsafeId<DocumentId>(fixtureUuid(`doc_${suffix}`)),
+	chunk: (suffix: string): ChunkId => unsafeId<ChunkId>(fixtureUuid(`chk_${suffix}`)),
+	connector: (suffix: string): ConnectorId => unsafeId<ConnectorId>(fixtureUuid(`conn_${suffix}`)),
 	connectorInstance: (suffix: string): ConnectorInstanceId =>
-		unsafeId<ConnectorInstanceId>(`ci_${suffix}`),
-	tenant: (suffix: string): TenantId => unsafeId<TenantId>(`tnt_${suffix}`),
-	credential: (suffix: string): CredentialId => unsafeId<CredentialId>(`cred_${suffix}`),
+		unsafeId<ConnectorInstanceId>(fixtureUuid(`ci_${suffix}`)),
+	tenant: (suffix: string): TenantId => unsafeId<TenantId>(fixtureUuid(`tnt_${suffix}`)),
+	credential: (suffix: string): CredentialId =>
+		unsafeId<CredentialId>(fixtureUuid(`cred_${suffix}`)),
 	executionContext: (suffix: string): ExecutionContextId =>
-		unsafeId<ExecutionContextId>(`ectx_${suffix}`),
-	mCPServer: (suffix: string): MCPServerId => unsafeId<MCPServerId>(`mcp_${suffix}`),
-	mCPClient: (suffix: string): MCPClientId => unsafeId<MCPClientId>(`mcpc_${suffix}`),
-	mCPSession: (suffix: string): MCPSessionId => unsafeId<MCPSessionId>(`mcps_${suffix}`),
-	environment: (suffix: string): EnvironmentId => unsafeId<EnvironmentId>(`env_${suffix}`),
-	checkpoint: (suffix: string): CheckpointId => unsafeId<CheckpointId>(`cp_${suffix}`),
-	lock: (suffix: string): LockId => unsafeId<LockId>(`lock_${suffix}`),
-	advisory: (suffix: string): AdvisoryId => unsafeId<AdvisoryId>(`adv_${suffix}`),
-	advisoryCall: (suffix: string): AdvisoryCallId => unsafeId<AdvisoryCallId>(`advc_${suffix}`),
-	emergencySave: (suffix: string): EmergencySaveId => unsafeId<EmergencySaveId>(`esave_${suffix}`),
-	memory: (suffix: string): MemoryId => unsafeId<MemoryId>(`mem_${suffix}`),
-	plugin: (suffix: string): PluginId => unsafeId<PluginId>(`plg_${suffix}`),
-	sandbox: (suffix: string): SandboxId => unsafeId<SandboxId>(`sbx_${suffix}`),
-	auditEvent: (suffix: string): AuditEventId => unsafeId<AuditEventId>(`aud_${suffix}`),
-	user: (suffix: string): UserId => unsafeId<UserId>(`usr_${suffix}`),
-	agent: (suffix: string): AgentId => unsafeId<AgentId>(`agt_${suffix}`),
-	memoryStoreRef: (suffix: string): MemoryStoreRef => unsafeId<MemoryStoreRef>(`mms_${suffix}`),
-	vaultRef: (suffix: string): VaultRef => unsafeId<VaultRef>(`vlt_${suffix}`),
+		unsafeId<ExecutionContextId>(fixtureUuid(`ectx_${suffix}`)),
+	mCPServer: (suffix: string): MCPServerId => unsafeId<MCPServerId>(fixtureUuid(`mcp_${suffix}`)),
+	mCPClient: (suffix: string): MCPClientId => unsafeId<MCPClientId>(fixtureUuid(`mcpc_${suffix}`)),
+	mCPSession: (suffix: string): MCPSessionId =>
+		unsafeId<MCPSessionId>(fixtureUuid(`mcps_${suffix}`)),
+	environment: (suffix: string): EnvironmentId =>
+		unsafeId<EnvironmentId>(fixtureUuid(`env_${suffix}`)),
+	checkpoint: (suffix: string): CheckpointId => unsafeId<CheckpointId>(fixtureUuid(`cp_${suffix}`)),
+	lock: (suffix: string): LockId => unsafeId<LockId>(fixtureUuid(`lock_${suffix}`)),
+	advisory: (suffix: string): AdvisoryId => unsafeId<AdvisoryId>(fixtureUuid(`adv_${suffix}`)),
+	advisoryCall: (suffix: string): AdvisoryCallId =>
+		unsafeId<AdvisoryCallId>(fixtureUuid(`advc_${suffix}`)),
+	emergencySave: (suffix: string): EmergencySaveId =>
+		unsafeId<EmergencySaveId>(fixtureUuid(`esave_${suffix}`)),
+	memory: (suffix: string): MemoryId => unsafeId<MemoryId>(fixtureUuid(`mem_${suffix}`)),
+	plugin: (suffix: string): PluginId => unsafeId<PluginId>(fixtureUuid(`plg_${suffix}`)),
+	sandbox: (suffix: string): SandboxId => unsafeId<SandboxId>(fixtureUuid(`sbx_${suffix}`)),
+	auditEvent: (suffix: string): AuditEventId =>
+		unsafeId<AuditEventId>(fixtureUuid(`aud_${suffix}`)),
+	user: (suffix: string): UserId => unsafeId<UserId>(fixtureUuid(`usr_${suffix}`)),
+	agent: (suffix: string): AgentId => unsafeId<AgentId>(fixtureUuid(`agt_${suffix}`)),
+	memoryStoreRef: (suffix: string): MemoryStoreRef =>
+		unsafeId<MemoryStoreRef>(fixtureUuid(`mms_${suffix}`)),
+	vaultRef: (suffix: string): VaultRef => unsafeId<VaultRef>(fixtureUuid(`vlt_${suffix}`)),
 	knowledgeBaseRef: (suffix: string): KnowledgeBaseRef =>
-		unsafeId<KnowledgeBaseRef>(`kbs_${suffix}`),
-	project: (suffix: string): ProjectId => unsafeId<ProjectId>(`prj_${suffix}`),
-	topic: (suffix: string): TopicId => unsafeId<TopicId>(`top_${suffix}`),
-	subSession: (suffix: string): SubSessionId => unsafeId<SubSessionId>(`sub_${suffix}`),
-	handoff: (suffix: string): HandoffId => unsafeId<HandoffId>(`hof_${suffix}`),
-	workspace: (suffix: string): WorkspaceId => unsafeId<WorkspaceId>(`wsp_${suffix}`),
-	summary: (suffix: string): SummaryId => unsafeId<SummaryId>(`sum_${suffix}`),
-	deliverable: (suffix: string): DeliverableId => unsafeId<DeliverableId>(`del_${suffix}`),
+		unsafeId<KnowledgeBaseRef>(fixtureUuid(`kbs_${suffix}`)),
+	project: (suffix: string): ProjectId => unsafeId<ProjectId>(fixtureUuid(`prj_${suffix}`)),
+	topic: (suffix: string): TopicId => unsafeId<TopicId>(fixtureUuid(`top_${suffix}`)),
+	subSession: (suffix: string): SubSessionId =>
+		unsafeId<SubSessionId>(fixtureUuid(`sub_${suffix}`)),
+	handoff: (suffix: string): HandoffId => unsafeId<HandoffId>(fixtureUuid(`hof_${suffix}`)),
+	workspace: (suffix: string): WorkspaceId => unsafeId<WorkspaceId>(fixtureUuid(`wsp_${suffix}`)),
+	summary: (suffix: string): SummaryId => unsafeId<SummaryId>(fixtureUuid(`sum_${suffix}`)),
+	deliverable: (suffix: string): DeliverableId =>
+		unsafeId<DeliverableId>(fixtureUuid(`del_${suffix}`)),
 } as const

package/src/tools/advisory/index.ts

@@ -77,7 +77,9 @@ export function buildAdvisoryTools(opts: AdvisoryToolsOptions): ToolDefinition[]
 		permissions: [],
 		readOnly: true,
 		destructive: false,
-		concurrencySafe: true,
+		// Consultations debit one run account and one per-run advisory quota.
+		// Serial execution makes the next admission see the preceding receipt.
+		concurrencySafe: false,
 		async execute({ advisor_id, question, domain, urgency, include_context }) {
 			const budgetCheck = advisoryCtx.checkBudget()
 			if (!budgetCheck.allowed) {

package/src/tools/builtins/bash.ts

@@ -92,6 +92,10 @@ function isDangerousCommand(command: string): boolean {
 	return DANGEROUS_PATTERNS.some((pattern) => pattern.test(command))
 }
 
+/** The refusal when a sandbox cannot host a detached process; exported so the test states the same words. */
+export const SANDBOX_CANNOT_DETACH =
+	'run_in_background is unavailable: this sandbox cannot start a detached process, and the job will not be run on the host to get around it. Run the command in the foreground, or raise `timeout` up to the tool maximum.'
+
 export const BashTool = defineTool({
 	name: 'bash',
 	description:
@@ -123,21 +127,16 @@ export const BashTool = defineTool({
 		}
 
 		if (input.run_in_background) {
-			// The current registry owns a host process. Foreground execution,
-			// however, goes through `context.sandbox.exec()` below. Treating the
-			// same command as host work just because `run_in_background` changed
-			// would make that boolean an escape hatch from the configured boundary.
-			//
-			// Query-built contexts structurally withhold the registry in this
-			// composition. This explicit check also protects direct tool callers
-			// and says why the capability is absent instead of misdiagnosing the
-			// host as having configured no registry.
-			if (context.sandbox) {
+			// A sandboxed run gets a registry only when its sandbox can start a
+			// detached process inside the boundary (`Sandbox.spawnDetached`);
+			// the executor withholds it otherwise. This check is for direct
+			// tool callers, who could hand a host registry and a sandbox to the
+			// same context: the boolean is never an escape from the boundary.
+			if (context.sandbox && context.sandbox.spawnDetached === undefined) {
 				return {
 					success: false,
 					output: '',
-					error:
-						'run_in_background is unavailable while a sandbox is active because the host background-job registry cannot preserve that sandbox boundary. Run the command in the foreground, or use a sandbox-aware persistent-process capability.',
+					error: SANDBOX_CANNOT_DETACH,
 				}
 			}
 			// Refused, not degraded to `cmd &`. The fallback is not a lesser

package/src/tools/builtins/computer-use.ts

@@ -152,7 +152,11 @@ function buildDescription(host: ComputerUseHost): string {
 		`Available actions: ${available.join('; ') || 'none'}.`,
 	]
 	if (unavailable.length > 0) {
-		lines.push(`Unavailable on this host: ${unavailable.join(', ')}.`)
+		lines.push(
+			caps.unavailableReason
+				? `Unavailable on this host: ${unavailable.join(', ')} — ${caps.unavailableReason} Do not retry; tell the user.`
+				: `Unavailable on this host: ${unavailable.join(', ')}.`,
+		)
 	}
 	lines.push(
 		'Coordinates are in logical pixels from the top-left of the primary display. Call getDisplayGeometry through screenshot output before clicking to confirm bounds.',
@@ -303,7 +307,7 @@ export function createComputerUseTool(host: ComputerUseHost): ToolDefinition<Act
 				return {
 					success: false,
 					output: '',
-					error: `computer_use: action "${input.type}" requires capability "${required}" which is not available on this host (displayServer=${host.capabilities.displayServer}).`,
+					error: `computer_use: action "${input.type}" requires capability "${required}" which is not available on this host (displayServer=${host.capabilities.displayServer}).${host.capabilities.unavailableReason ? ` ${host.capabilities.unavailableReason} Do not retry; tell the user.` : ''}`,
 				}
 			}
 			try {

package/src/tools/builtins/edit.ts

@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises'
 import { z } from 'zod'
 import type { ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
-import { resolveWithinReal } from '../paths.js'
+import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
@@ -350,7 +350,7 @@ export const EditTool = defineTool({
 		// machine, and answers it with whatever happens to exist there.
 		const filePath = context.sandbox
 			? undefined
-			: await resolveWithinReal(context.workingDirectory, parsed.data.path)
+			: await resolveWithinAnyReal(toolRoots(context), parsed.data.path)
 		// Read-modify-write is not atomic on its own: two edits to the same
 		// path interleave their reads, and the second write lands on content
 		// the first had already replaced — so one edit vanishes and the loser

package/src/tools/builtins/glob.ts

@@ -5,7 +5,7 @@ import type { Sandbox } from '../../types/sandbox/index.js'
 import type { ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { matchesGlob } from '../glob-match.js'
-import { resolveWithin } from '../paths.js'
+import { resolveWithinAny, toolRoots } from '../paths.js'
 import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js'
 
 /**
@@ -111,7 +111,7 @@ export const GlobTool = defineTool({
 		// Contained, not merely resolved. This was a bare `resolve`, so
 		// `path: "../../.."` reached whatever sits above the working
 		// directory — with no sandbox needed to make it work.
-		const basePath = resolveWithin(context.workingDirectory, input.path)
+		const basePath = resolveWithinAny(toolRoots(context), input.path)
 
 		let searchPath = basePath
 		let pattern = input.pattern
@@ -121,7 +121,7 @@ export const GlobTool = defineTool({
 			// A base directory lifted out of the PATTERN is caller-supplied
 			// too: `pattern: "../../**/*.pem"` is the same escape wearing a
 			// different argument.
-			const resolvedPatternBase = resolveWithin(context.workingDirectory, baseDir)
+			const resolvedPatternBase = resolveWithinAny(toolRoots(context), baseDir)
 			if (resolvedPatternBase === basePath || resolvedPatternBase.startsWith(`${basePath}/`)) {
 				searchPath = resolvedPatternBase
 				pattern = relativePattern

package/src/tools/builtins/grep.ts

@@ -4,7 +4,7 @@ import { z } from 'zod'
 import type { Sandbox } from '../../types/sandbox/index.js'
 import { defineTool } from '../defineTool.js'
 import { matchesGlob } from '../glob-match.js'
-import { resolveWithin } from '../paths.js'
+import { resolveWithinAny } from '../paths.js'
 import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js'
 
 /**
@@ -135,7 +135,7 @@ export const GrepTool = defineTool({
 		// working directory, with no sandbox needed to make it work.
 		const searchRoot = source.posix
 			? resolveWithinPosix(source.root, input.path)
-			: resolveWithin(source.root, input.path)
+			: resolveWithinAny([source.root, ...(context.additionalDirectories ?? [])], input.path)
 
 		// Auto-prepend **/ for simple patterns (e.g. "*.ts" → "**/*.ts")
 		let filePattern = input.include ?? '**/*'

package/src/tools/builtins/ls.ts

@@ -4,7 +4,7 @@ import { z } from 'zod'
 import type { Sandbox } from '../../types/sandbox/index.js'
 import type { ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
-import { resolveWithin } from '../paths.js'
+import { resolveWithinAny, toolRoots } from '../paths.js'
 import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js'
 
 const inputSchema = z.object({
@@ -220,7 +220,7 @@ export const LsTool = defineTool({
 		}
 
 		// Contained, not merely resolved — see `resolveWithin`.
-		const targetPath = resolveWithin(context.workingDirectory, input.path)
+		const targetPath = resolveWithinAny(toolRoots(context), input.path)
 
 		if (input.recursive) {
 			const output: string[] = []