@namzu/sdk 0.6.0 → 1.1.0

package/src/runtime/query/iteration/phases/working-memory-compaction.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Regression test for the ses_055 Layer-B SDK seam (#104):
+ *
+ *   1. **Compaction FIRES** under a small `contextWindowTokens` even with the
+ *      run-level `tokenBudget = 0` (UNLIMITED) — proving the F1 fix repointed
+ *      BOTH the `<= 0` guard AND the divisor, closing the silent-no-op trap.
+ *   2. **The pinned working-memory slot SURVIVES** the compaction pass (it is a
+ *      leading system message → preserved by header identity).
+ *   3. **No premature stop** from `tokenBudget = 0` alone: with NO
+ *      `contextWindowTokens`, the same overflowing run does NOT compact (the
+ *      legacy fallback), so consumers that never set the new field are
+ *      byte-identical.
+ *
+ * The test drives `refreshWorkingMemory` (to pin the slot) then
+ * `runCompactionCheck` directly against a mock `IterationContext`, which is the
+ * exact sequence the iteration loop runs each turn.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import { findDanglingMessages } from '../../../../compaction/dangling.js'
+import { WorkingStateManager } from '../../../../compaction/manager.js'
+import { CompactionConfigSchema } from '../../../../config/runtime.js'
+import type { RunId } from '../../../../types/ids/index.js'
+import {
+	type Message,
+	createAssistantMessage,
+	createSystemMessage,
+	createToolMessage,
+	createUserMessage,
+} from '../../../../types/message/index.js'
+import type { Logger } from '../../../../utils/logger.js'
+import { runCompactionCheck } from './compaction.js'
+import type { IterationContext } from './context.js'
+import { WORKING_MEMORY_HEADER, refreshWorkingMemory } from './working-memory.js'
+
+function makeLogger(): Logger {
+	const self = {
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		debug: vi.fn(),
+		child: vi.fn(),
+	} as unknown as Logger
+	;(self as { child: (ctx: unknown) => Logger }).child = vi.fn(() => self)
+	return self
+}
+
+/** A long string so a handful of messages overflow a small context window. */
+const FILLER = 'x'.repeat(200)
+
+function buildOverflowingMessages(): Message[] {
+	const msgs: Message[] = [createSystemMessage(`STATIC SYSTEM PROMPT ${FILLER}`, 'cache')]
+	for (let i = 0; i < 8; i++) {
+		msgs.push(createUserMessage(`user turn ${i} ${FILLER}`))
+		msgs.push(createAssistantMessage(`assistant turn ${i} ${FILLER}`))
+	}
+	return msgs
+}
+
+function makeCtx(opts: {
+	messages: Message[]
+	contextWindowTokens?: number
+	workingMemoryProvider?: IterationContext['workingMemoryProvider']
+}): IterationContext {
+	const config = CompactionConfigSchema.parse({
+		strategy: 'structured',
+		llmVerification: false,
+		...(opts.contextWindowTokens !== undefined
+			? { contextWindowTokens: opts.contextWindowTokens }
+			: {}),
+	})
+	const manager = new WorkingStateManager(config)
+	// Seed a couple of slots so serializeState produces non-trivial output.
+	manager.addDecision('built the report as .docx')
+
+	return {
+		runConfig: { tokenBudget: 0 }, // UNLIMITED cumulative cost cap
+		compactionConfig: config,
+		workingStateManager: manager,
+		workingMemoryProvider: opts.workingMemoryProvider,
+		log: makeLogger(),
+		runMgr: {
+			id: 'run_1' as RunId,
+			currentIteration: 3,
+			messages: opts.messages,
+		},
+	} as unknown as IterationContext
+}
+
+const WM_BLOCK =
+	'ARTIFACTS\n  • report.docx · Word document · 48.2 KB · imp:H\n       path: /mnt/user-data/outputs/report.docx'
+
+describe('Layer-B compaction seam (ses_055 #104)', () => {
+	it('FIRES on small contextWindowTokens with tokenBudget=0 AND preserves the pinned WM slot', async () => {
+		const messages = buildOverflowingMessages()
+		const ctx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => WM_BLOCK,
+		})
+
+		await refreshWorkingMemory(ctx)
+		// The slot is pinned as the last leading system message (index 1).
+		expect(messages[1]?.role).toBe('system')
+		expect(messages[1]?.content?.startsWith(WORKING_MEMORY_HEADER)).toBe(true)
+
+		const before = messages.length
+		await runCompactionCheck(ctx)
+
+		// (1) compaction fired: a [COMPACTED CONTEXT] message appeared and the
+		// transcript shrank.
+		expect(messages.length).toBeLessThan(before)
+		expect(messages.some((m) => m.content?.includes('[COMPACTED CONTEXT]'))).toBe(true)
+
+		// (2) the pinned working-memory slot survived by header identity.
+		const wm = messages.filter(
+			(m) => m.role === 'system' && m.content?.startsWith(WORKING_MEMORY_HEADER),
+		)
+		expect(wm).toHaveLength(1)
+		expect(wm[0]?.content).toContain('report.docx')
+	})
+
+	it('does NOT compact when contextWindowTokens is absent and tokenBudget=0 (byte-identical fallback)', async () => {
+		const messages = buildOverflowingMessages()
+		const ctx = makeCtx({ messages })
+
+		const before = messages.length
+		await runCompactionCheck(ctx)
+
+		// budget = tokenBudget = 0 → guard returns; no compaction, no mutation.
+		expect(messages.length).toBe(before)
+		expect(messages.some((m) => m.content?.includes('[COMPACTED CONTEXT]'))).toBe(false)
+	})
+
+	it('removes the slot when the provider returns an empty block', async () => {
+		const messages = buildOverflowingMessages()
+		const ctx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => WM_BLOCK,
+		})
+		await refreshWorkingMemory(ctx)
+		expect(messages.some((m) => m.content?.startsWith(WORKING_MEMORY_HEADER))).toBe(true)
+
+		// Same transcript, provider now returns blank ⇒ the slot is removed.
+		const blankCtx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => '   ',
+		})
+		await refreshWorkingMemory(blankCtx)
+		expect(messages.some((m) => m.content?.startsWith(WORKING_MEMORY_HEADER))).toBe(false)
+	})
+
+	it('keeps the prior slot when the provider throws (failure-isolated)', async () => {
+		const messages = buildOverflowingMessages()
+		const ctx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => WM_BLOCK,
+		})
+		await refreshWorkingMemory(ctx)
+
+		const throwingCtx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => {
+				throw new Error('provider boom')
+			},
+		})
+		await refreshWorkingMemory(throwingCtx)
+		// Prior slot retained; run not broken.
+		expect(messages.some((m) => m.content?.startsWith(WORKING_MEMORY_HEADER))).toBe(true)
+	})
+
+	it('does NOT orphan a tool_result when the recent-window cut splits a tool pair (C1)', async () => {
+		// keepRecentMessages defaults to 4. Lay the transcript out so the NAIVE
+		// cut (length - 4 = index 5) lands right AFTER the assistant-with-toolCall
+		// (index 4) but BEFORE... no — exactly ON its tool result (index 5), which
+		// a naive slice would keep in the recent window while dropping the
+		// assistant into the summarized older set → an orphaned tool_result at the
+		// head of the recent window → Anthropic 400. The fix snaps keepStart
+		// forward past the complete pair.
+		const toolCall = {
+			id: 't1',
+			type: 'function' as const,
+			function: { name: 'read', arguments: '{}' },
+		}
+		const messages: Message[] = [
+			createSystemMessage(`STATIC SYSTEM PROMPT ${FILLER}`, 'cache'),
+			createUserMessage(`user 0 ${FILLER}`),
+			createAssistantMessage(`assistant 0 ${FILLER}`),
+			createUserMessage(`user 1 ${FILLER}`),
+			createAssistantMessage(`calling a tool ${FILLER}`, [toolCall]), // idx 4
+			createToolMessage(`tool result ${FILLER}`, 't1'), // idx 5 — naive recent[0]
+			createAssistantMessage(`assistant 2 ${FILLER}`),
+			createUserMessage(`user 3 ${FILLER}`),
+			createAssistantMessage(`assistant 3 ${FILLER}`),
+		]
+		const ctx = makeCtx({ messages, contextWindowTokens: 100 })
+
+		await runCompactionCheck(ctx)
+
+		// Compaction fired.
+		expect(messages.some((m) => m.content?.includes('[COMPACTED CONTEXT]'))).toBe(true)
+		// The surviving transcript has NO dangling tool pair — the tool result
+		// whose assistant was summarized away was moved into the older set too,
+		// so no orphaned tool_result remains to 400 the next provider turn.
+		expect(findDanglingMessages(messages).isValid).toBe(true)
+		// And a `tool` message never leads the recent window.
+		const firstNonSystem = messages.find((m) => m.role !== 'system')
+		expect(firstNonSystem?.role).not.toBe('tool')
+	})
+})

package/src/runtime/query/iteration/phases/working-memory.ts

@@ -0,0 +1,86 @@
+import { createSystemMessage } from '../../../../types/message/index.js'
+import type { IterationContext } from './context.js'
+
+/**
+ * Sentinel header identifying the single PINNED working-memory system message.
+ *
+ * The SDK finds + replaces the slot by this header every turn and uses the same
+ * identity to re-pin it if compaction ever drops it (the OPAQUE survival guard
+ * in `compaction.ts` — no host-format knowledge required). The host's rendered
+ * block is stored verbatim AFTER this header; the SDK never parses it.
+ */
+export const WORKING_MEMORY_HEADER =
+	'[WORKING MEMORY] Authoritative state for this conversation — you produced these.'
+
+/**
+ * True when `content` is the pinned working-memory slot (header identity only).
+ * Shared with `compaction.ts` so the survival guard re-pins by the SAME rule.
+ */
+export function isWorkingMemoryMessage(content: string | null | undefined): boolean {
+	return typeof content === 'string' && content.startsWith(WORKING_MEMORY_HEADER)
+}
+
+/**
+ * Resolve the host's working-memory string and rewrite a single PINNED leading
+ * system message in place. Insert-or-replace keyed by {@link WORKING_MEMORY_HEADER};
+ * an empty/blank string removes the slot.
+ *
+ * The slot is an EPHEMERAL system message placed as the LAST leading system
+ * message (after the cached static + dynamic system messages), so it never
+ * busts the prompt-cache prefix yet still rides inside the compaction-preserved
+ * leading-system run (the primacy edge Lost-in-the-Middle / Context-Rot need).
+ *
+ * Failure-isolated (the `web-search` seam rule): a throwing/slow provider
+ * degrades to "no refresh this turn" (keeps the prior slot), never breaks the
+ * run. Early-returns when no provider is configured ⇒ byte-identical run path.
+ */
+export async function refreshWorkingMemory(ctx: IterationContext): Promise<void> {
+	const provider = ctx.workingMemoryProvider
+	if (!provider) return
+
+	let block: string
+	try {
+		block =
+			(await provider({
+				runId: ctx.runMgr.id,
+				iteration: ctx.runMgr.currentIteration,
+			})) ?? ''
+	} catch (err) {
+		ctx.log.warn('workingMemoryProvider failed; keeping prior slot', {
+			runId: ctx.runMgr.id,
+			error: err instanceof Error ? err.message : String(err),
+		})
+		return
+	}
+
+	const msgs = ctx.runMgr.messages
+
+	// Bound the search to the LEADING system run (the compaction-preserved
+	// region). A working-memory header appearing later in the transcript (e.g.
+	// echoed by a tool result) must not be mistaken for the pinned slot.
+	let leadEnd = 0
+	while (leadEnd < msgs.length && msgs[leadEnd]?.role === 'system') leadEnd++
+
+	let idx = -1
+	for (let i = 0; i < leadEnd; i++) {
+		const m = msgs[i]
+		if (m && m.role === 'system' && isWorkingMemoryMessage(m.content)) {
+			idx = i
+			break
+		}
+	}
+
+	if (!block.trim()) {
+		// Empty block ⇒ remove the slot (byte-identical-when-empty).
+		if (idx >= 0) msgs.splice(idx, 1)
+		return
+	}
+
+	const wm = createSystemMessage(`${WORKING_MEMORY_HEADER}\n\n${block}`, 'ephemeral')
+	if (idx >= 0) {
+		msgs[idx] = wm
+	} else {
+		// Insert as the LAST leading system message (after static + dynamic).
+		msgs.splice(leadEnd, 0, wm)
+	}
+}

package/src/runtime/query/prompt.ts

@@ -1,5 +1,5 @@
 import { FILESYSTEM_TOOLS } from '../../constants/tools/index.js'
-import { assembleSystemPrompt } from '../../persona/assembler.js'
+import { assembleSystemPrompt, renderSkillsSection } from '../../persona/assembler.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
 import type { AgentPersona } from '../../types/persona/index.js'
@@ -83,6 +83,14 @@ export class PromptBuilder {
 			parts.push(this.config.systemPrompt)
 		} else if (this.config.persona) {
 			parts.push(assembleSystemPrompt(this.config.persona, this.config.skills))
+		} else {
+			const skillSection = renderSkillsSection(this.config.skills)
+			if (skillSection) parts.push(skillSection)
+		}
+
+		if (this.config.systemPrompt) {
+			const skillSection = renderSkillsSection(this.config.skills)
+			if (skillSection) parts.push(skillSection)
 		}
 
 		if (contextLevel !== 'minimal') {
@@ -133,6 +141,14 @@ export class PromptBuilder {
 			if (this.config.persona.sessionContext) {
 				dynamicParts.push(`## Session Context\n${this.config.persona.sessionContext.trim()}`)
 			}
+		} else {
+			const skillSection = renderSkillsSection(this.config.skills)
+			if (skillSection) staticParts.push(skillSection)
+		}
+
+		if (this.config.systemPrompt) {
+			const skillSection = renderSkillsSection(this.config.skills)
+			if (skillSection) staticParts.push(skillSection)
 		}
 
 		if (contextLevel !== 'minimal') {

package/src/runtime/query/tooling.ts

@@ -17,6 +17,7 @@ export interface ToolingBootstrapConfig {
 	permissionMode: PermissionMode
 	env: Record<string, string>
 	abortSignal: AbortSignal
+	allowedTools?: readonly string[]
 	invocationState?: InvocationState
 	pluginManager?: PluginLifecycleManager
 }
@@ -36,6 +37,7 @@ export class ToolingBootstrap {
 				permissionMode: config.permissionMode,
 				env: config.env,
 				abortSignal: config.abortSignal,
+				allowedTools: config.allowedTools,
 				invocationState: config.invocationState,
 				pluginManager: config.pluginManager,
 			},

package/src/sandbox/provider/local.ts

@@ -4,8 +4,10 @@ import {
 	readFile as fsReadFile,
 	writeFile as fsWriteFile,
 	mkdir,
+	readdir,
 	rename,
 	rm,
+	stat,
 } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
@@ -24,6 +26,7 @@ import type {
 	SandboxEnvironment,
 	SandboxExecOptions,
 	SandboxExecResult,
+	SandboxFileEntry,
 	SandboxProvider,
 	SandboxStatus,
 } from '../../types/sandbox/index.js'
@@ -302,6 +305,36 @@ class LocalSandbox implements Sandbox {
 		return fsReadFile(resolved)
 	}
 
+	async listFiles(rootPath: string): Promise<readonly SandboxFileEntry[]> {
+		if (this._status === 'destroyed') {
+			throw new Error(`Sandbox ${this.id} is destroyed`)
+		}
+
+		const resolved = assertInsideSandbox(this.rootDir, rootPath)
+		const root = await stat(resolved).catch(() => null)
+		if (!root || !root.isDirectory()) return []
+
+		const entries: SandboxFileEntry[] = []
+		const stack: string[] = [resolved]
+		while (stack.length > 0) {
+			const dir = stack.pop()
+			if (!dir) break
+			const dirents = await readdir(dir, { withFileTypes: true }).catch(() => [])
+			for (const ent of dirents) {
+				const full = join(dir, ent.name)
+				if (ent.isDirectory()) {
+					stack.push(full)
+					continue
+				}
+				if (!ent.isFile()) continue
+				const info = await stat(full).catch(() => null)
+				if (!info) continue
+				entries.push({ path: full, size: info.size })
+			}
+		}
+		return entries
+	}
+
 	async destroy(): Promise<void> {
 		if (this._status === 'destroyed') {
 			return

package/src/session/workspace/__tests__/shared-run.test.ts

@@ -0,0 +1,181 @@
+import { mkdtemp, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { SharedRunWorkspace } from '../shared-run.js'
+
+describe('SharedRunWorkspace', () => {
+	it('creates a canonical workspace manifest with runtime-visible paths', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+			label: 'Cowork task',
+			now: new Date('2026-05-08T10:00:00.000Z'),
+		})
+
+		const manifest = await workspace.readManifest()
+		expect(manifest.kind).toBe('shared-run-workspace')
+		expect(manifest.label).toBe('Cowork task')
+		expect(manifest.paths).toMatchObject({
+			root: '/mnt/user-data/outputs/_work',
+			manifest: '/mnt/user-data/outputs/_work/manifest.json',
+			sharedContext: '/mnt/user-data/outputs/_work/02_shared_context.md',
+			sources: '/mnt/user-data/outputs/_work/sources',
+			plans: '/mnt/user-data/outputs/_work/plans',
+			agents: '/mnt/user-data/outputs/_work/agents',
+		})
+		expect(workspace.refs().supervisorBriefPath).toBe(
+			'/mnt/user-data/outputs/_work/00_supervisor_brief.md',
+		)
+		expect(workspace.refs().sharedContextPath).toBe(
+			'/mnt/user-data/outputs/_work/02_shared_context.md',
+		)
+	})
+
+	it('records source inventory and seeded supervisor brief before workers launch', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work/',
+		})
+
+		await workspace.writeSourceInventory([
+			{
+				id: 'file_abc',
+				label: 'SBD.docx',
+				path: '/mnt/user-data/uploads/file_abc/SBD.docx',
+				kind: 'docx',
+				sizeBytes: 123,
+			},
+		])
+		const briefPath = await workspace.seedSupervisorBrief({
+			briefText: 'Root task seed brief',
+		})
+		const agentPath = await workspace.registerAgentWork({
+			agentId: 'solution-architecture',
+			taskId: 'task_123',
+		})
+
+		expect(briefPath).toBe('/mnt/user-data/outputs/_work/00_supervisor_brief.md')
+		expect(agentPath).toBe('/mnt/user-data/outputs/_work/agents/solution-architecture/task_123')
+		const inventory = await readFile(join(hostRoot, 'sources', 'inventory.md'), 'utf8')
+		expect(inventory).toContain('SBD.docx')
+		expect(inventory).toContain('/mnt/user-data/uploads/file_abc/SBD.docx')
+		const manifest = await workspace.readManifest()
+		expect(manifest.sources).toHaveLength(1)
+		expect(manifest.plans[0]?.status).toBe('seeded')
+		expect(manifest.agents[0]?.workPath).toBe(agentPath)
+	})
+
+	it('preserves every agent record when workers register concurrently', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+		})
+
+		await Promise.all(
+			Array.from({ length: 9 }, (_, index) =>
+				workspace.registerAgentWork({
+					agentId: `agent-${index + 1}`,
+					taskId: `task_${index + 1}`,
+					status: 'running',
+				}),
+			),
+		)
+
+		const manifest = await workspace.readManifest()
+		expect(manifest.agents).toHaveLength(9)
+		expect(manifest.agents.map((agent) => agent.agentId).sort()).toEqual([
+			'agent-1',
+			'agent-2',
+			'agent-3',
+			'agent-4',
+			'agent-5',
+			'agent-6',
+			'agent-7',
+			'agent-8',
+			'agent-9',
+		])
+	})
+
+	it('writes and appends per-worker briefs without losing earlier sections', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+		})
+
+		const briefPath = await workspace.writeAgentBrief({
+			agentId: 'solution-architecture',
+			taskId: 'task_abc',
+			briefText: '# Worker Brief\n\n## Assignment\n\nDraft the solution architecture section.',
+		})
+		expect(briefPath).toBe(
+			'/mnt/user-data/outputs/_work/agents/solution-architecture/task_abc/00_brief.md',
+		)
+
+		const appended = await workspace.appendAgentBrief({
+			agentId: 'solution-architecture',
+			taskId: 'task_abc',
+			sectionText:
+				'## Follow-up 2026-05-10T18:00:00.000Z\n\n### Follow-up message\n\nAdd a risks subsection.',
+		})
+		expect(appended).toBe(briefPath)
+
+		const hostBriefPath = join(
+			hostRoot,
+			'agents',
+			'solution-architecture',
+			'task_abc',
+			'00_brief.md',
+		)
+		const content = await readFile(hostBriefPath, 'utf8')
+		expect(content).toContain('Draft the solution architecture section.')
+		expect(content).toContain('Add a risks subsection.')
+		// Initial seed must precede the appended section, not the other way around.
+		const seedIndex = content.indexOf('Draft the solution architecture')
+		const followIndex = content.indexOf('Add a risks subsection.')
+		expect(seedIndex).toBeGreaterThan(-1)
+		expect(followIndex).toBeGreaterThan(seedIndex)
+	})
+
+	it('writeTaskContext stores the user request verbatim under 01_task_context.md', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+		})
+
+		const big = `# Task Context\n\n${'A'.repeat(40_000)}`
+		const path = await workspace.writeTaskContext(big)
+		expect(path).toBe('/mnt/user-data/outputs/_work/01_task_context.md')
+		expect(workspace.refs().taskContextPath).toBe(path)
+		const content = await readFile(join(hostRoot, '01_task_context.md'), 'utf8')
+		// Trailing newline added by the writer is OK; user content must not be truncated.
+		expect(content.length).toBeGreaterThanOrEqual(big.length)
+		expect(content).toContain('A'.repeat(40_000))
+	})
+
+	it('writeSharedContext stores the shared coordination packet under 02_shared_context.md', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+		})
+
+		const path = await workspace.writeSharedContext('# Shared Context\n\nRead this first.')
+		expect(path).toBe('/mnt/user-data/outputs/_work/02_shared_context.md')
+		expect(workspace.refs().sharedContextPath).toBe(path)
+		const content = await readFile(join(hostRoot, '02_shared_context.md'), 'utf8')
+		expect(content).toContain('Read this first.')
+	})
+
+	it('rejects host paths that escape the shared workspace root', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({ hostRoot })
+
+		expect(() => workspace.hostPath('..', 'outside')).toThrow(/escapes root/)
+	})
+})

package/src/session/workspace/index.ts

@@ -24,3 +24,9 @@ export { WorkspaceBackendRegistry } from './registry.js'
 
 export { GitWorktreeDriver, parseWorktreeList } from './git-worktree.js'
 export type { ExecFile, ExecFileResult, GitWorktreeDriverConfig } from './git-worktree.js'
+
+export { SharedRunWorkspace } from './shared-run.js'
+export type {
+	RegisterSharedRunPlanInput,
+	SharedRunWorkspaceConfig,
+} from './shared-run.js'