@namzu/sdk 2.0.0 → 3.1.0

package/src/sandbox/__tests__/resource-limits.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest'
+
+import type { SandboxEnvironment } from '../../types/sandbox/index.js'
+import { buildLimitedSpawn } from '../provider/local.js'
+
+/**
+ * `memoryLimitMb` and `maxProcesses` were applied on one tier and dropped on
+ * the other two — and the two that dropped them are the STRONGER ones. A
+ * host that asked for isolation got its blast-radius caps silently removed
+ * by choosing better isolation, which is the worst direction for a control
+ * to fail in.
+ *
+ * The sibling backend in the sandbox package already treats this as an
+ * error rather than a default: unenforceable per-sandbox controls are
+ * refused there, not ignored. Here they are enforceable on every tier —
+ * the mechanism is a shell builtin, and each tier already spawns through
+ * a wrapper it can sit inside — so they are enforced.
+ */
+
+const TIERS: SandboxEnvironment[] = ['basic', 'linux-namespace', 'macos-seatbelt']
+
+function spawnFor(environment: SandboxEnvironment, limits: Record<string, number>) {
+	return buildLimitedSpawn({
+		environment,
+		command: 'node',
+		args: ['-e', "console.log('hi')"],
+		rootDir: '/tmp/sandbox-root',
+		...limits,
+	})
+}
+
+describe('a resource cap survives the choice of tier', () => {
+	for (const environment of TIERS) {
+		it(`applies a memory cap under ${environment}`, () => {
+			const spawn = spawnFor(environment, { memoryLimitMb: 256 })
+			const rendered = [spawn.spawnCommand, ...spawn.spawnArgs].join(' ')
+
+			expect(rendered).toContain('ulimit -v 262144')
+		})
+
+		it(`applies a process cap under ${environment}`, () => {
+			const spawn = spawnFor(environment, { maxProcesses: 32 })
+			const rendered = [spawn.spawnCommand, ...spawn.spawnArgs].join(' ')
+
+			expect(rendered).toContain('ulimit -u 32')
+		})
+
+		it(`applies both together under ${environment}`, () => {
+			const spawn = spawnFor(environment, { memoryLimitMb: 128, maxProcesses: 8 })
+			const rendered = [spawn.spawnCommand, ...spawn.spawnArgs].join(' ')
+
+			expect(rendered).toContain('ulimit -v 131072')
+			expect(rendered).toContain('ulimit -u 8')
+		})
+	}
+})
+
+describe('the tier keeps doing its own job', () => {
+	it('still unshares the namespaces when a cap is set', () => {
+		const spawn = spawnFor('linux-namespace', { maxProcesses: 4 })
+
+		expect(spawn.spawnCommand).toBe('unshare')
+		expect(spawn.spawnArgs.join(' ')).toContain('--pid')
+	})
+
+	it('still installs the confinement profile when a cap is set', () => {
+		const spawn = spawnFor('macos-seatbelt', { maxProcesses: 4 })
+
+		expect(spawn.spawnCommand).toBe('sandbox-exec')
+		expect(spawn.spawnArgs).toContain('-p')
+	})
+})
+
+describe('nothing is wrapped when nothing was capped', () => {
+	it('spawns the command directly under the unconfined tier', () => {
+		const spawn = spawnFor('basic', {})
+
+		expect(spawn.spawnCommand).toBe('node')
+		expect(spawn.spawnArgs).toEqual(['-e', "console.log('hi')"])
+	})
+
+	it('leaves the wrapper alone under the stronger tiers', () => {
+		const spawn = spawnFor('linux-namespace', {})
+
+		expect(spawn.spawnArgs).toContain('node')
+		expect(spawn.spawnArgs.join(' ')).not.toContain('ulimit')
+	})
+})
+
+describe('an argument cannot break out of the shell that applies the cap', () => {
+	it('quotes a single quote in an argument', () => {
+		const spawn = buildLimitedSpawn({
+			environment: 'basic',
+			command: 'echo',
+			args: ["it's; rm -rf /"],
+			rootDir: '/tmp/sandbox-root',
+			maxProcesses: 4,
+		})
+		const rendered = spawn.spawnArgs.join(' ')
+
+		// The payload survives as ONE argument rather than becoming a second
+		// command: the `;` stays inside the quoting.
+		expect(rendered).not.toContain("; rm -rf / '")
+		expect(rendered).toContain("'\\''")
+	})
+})

package/src/sandbox/factory.ts

@@ -6,7 +6,7 @@ export class SandboxProviderFactory {
 	static create(config: SandboxConfig, log: Logger): SandboxProvider {
 		switch (config.provider) {
 			case 'local':
-				return new LocalSandboxProvider(log)
+				return new LocalSandboxProvider(log, { requireIsolation: config.requireIsolation })
 			default: {
 				const _exhaustive: never = config.provider
 				throw new Error(`Unknown sandbox provider: ${_exhaustive}`)

package/src/sandbox/index.ts

@@ -1,2 +1,4 @@
 export { LocalSandboxProvider } from './provider/local.js'
+export type { LocalSandboxProviderOptions } from './provider/local.js'
 export { SandboxProviderFactory } from './factory.js'
+export { assertIsolation, describeIsolation, isolationOf, missingIsolation } from './isolation.js'

package/src/sandbox/isolation.ts

@@ -0,0 +1,72 @@
+import type {
+	SandboxEnvironment,
+	SandboxIsolationControl,
+	SandboxIsolationReport,
+} from '../types/sandbox/index.js'
+import { SANDBOX_ISOLATION_CONTROLS } from '../types/sandbox/index.js'
+
+/**
+ * What each tier actually enforces on the spawned process.
+ *
+ * This table is deliberately pessimistic: a control is `true` only where
+ * the spawn arguments enforce it, never where the tier's name suggests it.
+ * The gap being closed here is that a caller who turned isolation on got a
+ * tier-dependent amount of it under one undifferentiated provider name,
+ * with no way to tell which controls were live.
+ *
+ * `linux-namespace` reports `filesystem: false` on purpose. The tier
+ * unshares the mount namespace but never remounts anything, so the child
+ * still sees the whole host filesystem — a private mount table is not
+ * confinement. Claiming otherwise here would reintroduce the exact defect
+ * this table exists to end.
+ */
+const ISOLATION_BY_ENVIRONMENT: Readonly<Record<SandboxEnvironment, SandboxIsolationReport>> = {
+	'macos-seatbelt': { filesystem: true, network: true, process: true },
+	'linux-namespace': { filesystem: false, network: true, process: true },
+	basic: { filesystem: false, network: false, process: false },
+}
+
+export function isolationOf(environment: SandboxEnvironment): SandboxIsolationReport {
+	const report = ISOLATION_BY_ENVIRONMENT[environment]
+	if (report === undefined) {
+		throw new Error(`Unknown sandbox environment: ${environment}`)
+	}
+	return report
+}
+
+/** The requested controls this environment cannot supply, in a stable order. */
+export function missingIsolation(
+	environment: SandboxEnvironment,
+	required: readonly SandboxIsolationControl[],
+): SandboxIsolationControl[] {
+	const report = isolationOf(environment)
+	return SANDBOX_ISOLATION_CONTROLS.filter(
+		(control) => required.includes(control) && !report[control],
+	)
+}
+
+/**
+ * Refuse when the host cannot supply a control the caller asked for.
+ *
+ * Refusing is the whole point. A security control that is accepted and
+ * then silently not applied is worse than one that was never offered: the
+ * caller stops looking, and the run proceeds believing it is confined.
+ */
+export function assertIsolation(
+	environment: SandboxEnvironment,
+	required: readonly SandboxIsolationControl[],
+): void {
+	const missing = missingIsolation(environment, required)
+	if (missing.length === 0) return
+
+	throw new Error(
+		`Sandbox environment "${environment}" cannot enforce ${missing.join(', ')} isolation, which this run requires. Enforced here: ${describeIsolation(environment)}. Run on a host that supports it, or drop the requirement explicitly — it will not be silently downgraded.`,
+	)
+}
+
+/** Human-readable summary for logs and error messages. */
+export function describeIsolation(environment: SandboxEnvironment): string {
+	const report = isolationOf(environment)
+	const enforced = SANDBOX_ISOLATION_CONTROLS.filter((control) => report[control])
+	return enforced.length === 0 ? 'nothing' : enforced.join(', ')
+}

package/src/sandbox/provider/local.ts

@@ -27,11 +27,13 @@ import type {
 	SandboxExecOptions,
 	SandboxExecResult,
 	SandboxFileEntry,
+	SandboxIsolationControl,
 	SandboxProvider,
 	SandboxStatus,
 } from '../../types/sandbox/index.js'
 import { generateSandboxId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
+import { assertIsolation, describeIsolation } from '../isolation.js'
 
 // ---------------------------------------------------------------------------
 // Path safety
@@ -50,15 +52,134 @@ function assertInsideSandbox(sandboxRoot: string, targetPath: string): string {
 // Platform detection
 // ---------------------------------------------------------------------------
 
+/**
+ * Flags the Linux tier spawns under. Kept next to the probe so detection
+ * tests the isolation that will actually be applied, not a weaker subset.
+ */
+const LINUX_UNSHARE_FLAGS = ['--mount', '--pid', '--fork', '--map-root-user', '--net']
+
+/**
+ * One output stream, accumulated under a byte cap that it reports hitting.
+ *
+ * The clipping was inline and the flag was not set, so a run whose output
+ * ran past the cap returned a result that looked whole. The tool layer
+ * already renders `stdoutTruncated` when a backend sets it — this one
+ * simply never did, which is the silent truncation the contract's own doc
+ * says the kernel does not do.
+ */
+export class CappedStream {
+	private chunks = ''
+	private bytes = 0
+
+	constructor(private readonly capBytes: number) {}
+
+	push(chunk: Buffer): void {
+		if (this.bytes < this.capBytes) {
+			this.chunks += chunk.subarray(0, this.capBytes - this.bytes).toString('utf-8')
+		}
+		this.bytes += chunk.length
+	}
+
+	get text(): string {
+		return this.chunks
+	}
+
+	/** True once more arrived than was kept. */
+	get truncated(): boolean {
+		return this.bytes > this.capBytes
+	}
+}
+
+export interface LimitedSpawnRequest {
+	readonly environment: SandboxEnvironment
+	readonly command: string
+	readonly args: readonly string[]
+	readonly rootDir: string
+	readonly memoryLimitMb?: number
+	readonly maxProcesses?: number
+}
+
+/** Single-quote for a shell, escaping any quote already inside. */
+function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, "'\\''")}'`
+}
+
+/**
+ * How one command is spawned under a tier, with the resource caps applied.
+ *
+ * The caps used to live inside the unconfined tier's branch only, so a host
+ * that asked for stronger isolation had its memory and process limits
+ * silently dropped — a control failing in the one direction nobody checks.
+ * They are the same shell builtin on every tier; the only difference is
+ * that the stronger tiers apply them one level in, inside the wrapper they
+ * already spawn through.
+ */
+export function buildLimitedSpawn(request: LimitedSpawnRequest): {
+	spawnCommand: string
+	spawnArgs: string[]
+} {
+	const { environment, command, args, rootDir } = request
+
+	const limits: string[] = []
+	if (request.memoryLimitMb !== undefined) {
+		limits.push(`ulimit -v ${request.memoryLimitMb * 1024}`)
+	}
+	if (request.maxProcesses !== undefined) {
+		limits.push(`ulimit -u ${request.maxProcesses}`)
+	}
+
+	// The innermost command: either the target itself, or the target behind
+	// a shell that sets the caps first.
+	const inner: readonly string[] =
+		limits.length > 0
+			? [
+					'/bin/sh',
+					'-c',
+					`${limits.join(' && ')} && ${[command, ...args].map(shellQuote).join(' ')}`,
+				]
+			: [command, ...args]
+
+	switch (environment) {
+		case 'linux-namespace':
+			return {
+				spawnCommand: 'unshare',
+				spawnArgs: [...LINUX_UNSHARE_FLAGS, '--', ...inner],
+			}
+
+		case 'macos-seatbelt':
+			return {
+				spawnCommand: 'sandbox-exec',
+				spawnArgs: ['-p', buildSeatbeltProfile(rootDir), '--', ...inner],
+			}
+
+		case 'basic': {
+			const [head, ...rest] = inner
+			return { spawnCommand: head as string, spawnArgs: rest }
+		}
+
+		default: {
+			const _exhaustive: never = environment
+			throw new Error(`Unknown sandbox environment: ${_exhaustive}`)
+		}
+	}
+}
+
 function detectEnvironment(): SandboxEnvironment {
 	const { platform } = process
 
 	if (platform === 'linux') {
 		try {
-			execSync('unshare --version', { stdio: 'ignore' })
+			// Probe the real flags, not just the binary. `unshare --version`
+			// succeeds on a host where unprivileged user namespaces are
+			// disabled by sysctl and every actual spawn would fail — the tier
+			// would be claimed and never delivered. The other platform's probe
+			// already runs its sandbox for real; this one now does too.
+			execSync(`unshare ${LINUX_UNSHARE_FLAGS.join(' ')} -- /bin/true`, {
+				stdio: 'ignore',
+			})
 			return 'linux-namespace'
 		} catch {
-			// unshare not available
+			// unshare missing, or the host refuses the namespaces we need
 		}
 	}
 
@@ -82,8 +203,6 @@ function detectEnvironment(): SandboxEnvironment {
  * Resolve a path to its canonical form so seatbelt matches correctly.
  * macOS symlinks like /var → /private/var must be resolved before use
  * in SBPL rules, because the kernel evaluates real paths.
- *
- * Reference: Anthropic sandbox-runtime normalizePathForSandbox()
  */
 function canonicalizePath(p: string): string {
 	try {
@@ -99,7 +218,6 @@ function canonicalizePath(p: string): string {
 /**
  * Build a macOS seatbelt (SBPL) profile for sandbox isolation.
  *
- * Reference: Anthropic sandbox-runtime generateSandboxProfile()
  * Key principle: (deny default) + explicit allows. Network always denied.
  */
 function buildSeatbeltProfile(sandboxRoot: string): string {
@@ -354,52 +472,16 @@ class LocalSandbox implements Sandbox {
 		command: string,
 		args: string[],
 	): { spawnCommand: string; spawnArgs: string[] } {
-		switch (this.environment) {
-			case 'linux-namespace':
-				return {
-					spawnCommand: 'unshare',
-					spawnArgs: ['--mount', '--pid', '--fork', '--map-root-user', '--', command, ...args],
-				}
-
-			case 'macos-seatbelt': {
-				const profile = buildSeatbeltProfile(this.rootDir)
-				return {
-					spawnCommand: 'sandbox-exec',
-					spawnArgs: ['-p', profile, '--', command, ...args],
-				}
-			}
-
-			case 'basic': {
-				const limits: string[] = []
-
-				const memoryMb = this.config.memoryLimitMb
-				if (memoryMb !== undefined) {
-					const memoryKb = memoryMb * 1024
-					limits.push(`ulimit -v ${memoryKb}`)
-				}
-
-				const maxProcs = this.config.maxProcesses
-				if (maxProcs !== undefined) {
-					limits.push(`ulimit -u ${maxProcs}`)
-				}
-
-				if (limits.length > 0) {
-					const prefix = limits.join(' && ')
-					const fullCommand = `${prefix} && ${command} ${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`
-					return {
-						spawnCommand: '/bin/sh',
-						spawnArgs: ['-c', fullCommand],
-					}
-				}
-
-				return { spawnCommand: command, spawnArgs: args }
-			}
-
-			default: {
-				const _exhaustive: never = this.environment
-				throw new Error(`Unknown sandbox environment: ${_exhaustive}`)
-			}
-		}
+		return buildLimitedSpawn({
+			environment: this.environment,
+			command,
+			args,
+			rootDir: this.rootDir,
+			...(this.config.memoryLimitMb !== undefined
+				? { memoryLimitMb: this.config.memoryLimitMb }
+				: {}),
+			...(this.config.maxProcesses !== undefined ? { maxProcesses: this.config.maxProcesses } : {}),
+		})
 	}
 
 	private spawnProcess(
@@ -423,27 +505,12 @@ class LocalSandbox implements Sandbox {
 				return
 			}
 
-			let stdout = ''
-			let stderr = ''
-			let stdoutBytes = 0
-			let stderrBytes = 0
+			const stdout = new CappedStream(SANDBOX_MAX_OUTPUT_BYTES)
+			const stderr = new CappedStream(SANDBOX_MAX_OUTPUT_BYTES)
 			let timedOut = false
 
-			child.stdout?.on('data', (chunk: Buffer) => {
-				if (stdoutBytes < SANDBOX_MAX_OUTPUT_BYTES) {
-					const remaining = SANDBOX_MAX_OUTPUT_BYTES - stdoutBytes
-					stdout += chunk.subarray(0, remaining).toString('utf-8')
-				}
-				stdoutBytes += chunk.length
-			})
-
-			child.stderr?.on('data', (chunk: Buffer) => {
-				if (stderrBytes < SANDBOX_MAX_OUTPUT_BYTES) {
-					const remaining = SANDBOX_MAX_OUTPUT_BYTES - stderrBytes
-					stderr += chunk.subarray(0, remaining).toString('utf-8')
-				}
-				stderrBytes += chunk.length
-			})
+			child.stdout?.on('data', (chunk: Buffer) => stdout.push(chunk))
+			child.stderr?.on('data', (chunk: Buffer) => stderr.push(chunk))
 
 			child.on('error', (err: NodeJS.ErrnoException) => {
 				if (err.code === 'ABORT_ERR' || ac.signal.aborted) {
@@ -466,10 +533,16 @@ class LocalSandbox implements Sandbox {
 			child.on('close', (code, signal) => {
 				resolvePromise({
 					exitCode: code ?? (timedOut ? 124 : 1),
-					stdout,
-					stderr,
+					stdout: stdout.text,
+					stderr: stderr.text,
 					signal: signal ?? undefined,
 					timedOut,
+					// The contract has carried these since the other backend
+					// needed them, and this one clipped without setting them:
+					// the model read a complete-looking result whose tail was
+					// gone. The tool layer already renders the flag.
+					stdoutTruncated: stdout.truncated,
+					stderrTruncated: stderr.truncated,
 				})
 			})
 		})
@@ -480,6 +553,15 @@ class LocalSandbox implements Sandbox {
 // LocalSandboxProvider
 // ---------------------------------------------------------------------------
 
+export interface LocalSandboxProviderOptions {
+	/**
+	 * Controls this run relies on. Construction throws when the detected
+	 * environment cannot enforce one of them, rather than downgrading to
+	 * whatever the host happens to offer.
+	 */
+	readonly requireIsolation?: readonly SandboxIsolationControl[]
+}
+
 export class LocalSandboxProvider implements SandboxProvider {
 	readonly id = 'local'
 	readonly name = 'Local Sandbox'
@@ -487,11 +569,28 @@ export class LocalSandboxProvider implements SandboxProvider {
 
 	private readonly log: Logger
 
-	constructor(log: Logger) {
+	constructor(log: Logger, options: LocalSandboxProviderOptions = {}) {
 		this.environment = detectEnvironment()
 		this.log = log.child({ component: 'LocalSandboxProvider' })
 
-		this.log.info('Initialized', { environment: this.environment })
+		assertIsolation(this.environment, options.requireIsolation ?? [])
+
+		const enforced = describeIsolation(this.environment)
+		if (this.environment === 'basic') {
+			// `warn`, not `info`. This tier confines nothing: the spawned
+			// process sees the whole host filesystem, the whole network, and
+			// every host process. The host-side controls that do survive (env
+			// scrubbed to a safe key set, cwd anchored, the SDK's own file
+			// helpers path-checked) are not process confinement, and a run
+			// that reads "sandbox created" in its log has every reason to
+			// believe otherwise.
+			this.log.warn('No isolation available on this host; commands run unconfined', {
+				environment: this.environment,
+				enforced,
+			})
+		} else {
+			this.log.info('Initialized', { environment: this.environment, enforced })
+		}
 	}
 
 	async create(config?: SandboxCreateConfig): Promise<Sandbox> {

package/src/session/__tests__/integration/spawn-rollback.test.ts

@@ -1,7 +1,7 @@
 /**
  * Integration — AgentManager.provisionSpawn compensating rollback.
  *
- * Covers Codex SPAWN-ROLLBACK critique (ses_001-hierarchy-redesign Phase 2
+ * Covers spawn-rollback critique (ses_001-hierarchy-redesign Phase 2
  * adversarial review, 2026-04-18). Without the try/catch wrapper around the
  * createSession → updateSession → createSubSession → workspace.create
  * mutation block, a failure after createSession leaves an `active` child

package/src/session/handoff/broadcast.ts

@@ -126,9 +126,9 @@ export async function executeBroadcastHandoff(
 		}
 	}
 
-	// 2. Dedupe recipients — same concern as the collab doc's Codex R: two rows
-	//    targeting the same actor would produce duplicate sub-sessions + racy
-	//    worktree paths. Reject before any side effect.
+	// 2. Dedupe recipients: two rows targeting the same actor would produce
+	//    duplicate sub-sessions and racy worktree paths. Reject before any
+	//    side effect.
 	const seen = new Set<string>()
 	for (const a of assignments) {
 		const key = recipientKey(a.recipientActor)

package/src/session/migration/__tests__/filesystem.test.ts

@@ -2,6 +2,7 @@ import { chmod, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/pr
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { IS_WINDOWS } from '../../../test-support/paths.js'
 import { UNKNOWN_TENANT_ID } from '../../../types/ids/index.js'
 import { FilesystemMigrationError } from '../errors.js'
 import {
@@ -241,23 +242,29 @@ describe('DefaultFilesystemMigrator.migrate', () => {
 		expect(await pathExists(newRunDir)).toBe(true)
 	})
 
-	it('error path: unwritable marker directory surfaces FilesystemMigrationError', async () => {
-		// Make the rootDir read-only so write_marker fails on the noop branch
-		// (simplest repro — no legacy threads needed).
-		await chmod(root, 0o555)
-
-		const migrator = new DefaultFilesystemMigrator()
-		try {
-			await migrator.migrate(root)
-			expect.fail('expected migrate() to throw')
-		} catch (err) {
-			expect(err).toBeInstanceOf(FilesystemMigrationError)
-			const details = (err as FilesystemMigrationError).details
-			expect(details.op).toBe('write_marker')
-			expect(details.path).toContain('v0.2.0')
-		} finally {
-			// restore perms so afterEach can clean up
-			await chmod(root, 0o755).catch(() => undefined)
-		}
-	})
+	// chmod 0o555 does not prevent directory writes on Windows, so the
+	// failure this asserts cannot be induced there. Skip rather than leave
+	// the suite permanently red for Windows contributors.
+	it.skipIf(IS_WINDOWS)(
+		'error path: unwritable marker directory surfaces FilesystemMigrationError',
+		async () => {
+			// Make the rootDir read-only so write_marker fails on the noop branch
+			// (simplest repro — no legacy threads needed).
+			await chmod(root, 0o555)
+
+			const migrator = new DefaultFilesystemMigrator()
+			try {
+				await migrator.migrate(root)
+				expect.fail('expected migrate() to throw')
+			} catch (err) {
+				expect(err).toBeInstanceOf(FilesystemMigrationError)
+				const details = (err as FilesystemMigrationError).details
+				expect(details.op).toBe('write_marker')
+				expect(details.path).toContain('v0.2.0')
+			} finally {
+				// restore perms so afterEach can clean up
+				await chmod(root, 0o755).catch(() => undefined)
+			}
+		},
+	)
 })

package/src/session/migration/filesystem.ts

@@ -44,6 +44,7 @@ import { join } from 'node:path'
 import type { TenantId } from '../../types/ids/index.js'
 import { UNKNOWN_TENANT_ID } from '../../types/ids/index.js'
 import type { ProjectId, SessionId } from '../../types/session/ids.js'
+import { atomicWriteFile } from '../../utils/atomic-write.js'
 import { FilesystemMigrationError } from './errors.js'
 import { acquireMigrationLock, readMarker, releaseMigrationLock, writeMarker } from './marker.js'
 
@@ -369,20 +370,14 @@ export class DefaultFilesystemMigrator implements FilesystemMigrator {
 }
 
 /**
- * Shared atomic-write helper. Mirrors `store/session/disk.ts:atomicWriteJson`
- * — intentionally duplicated so `session/migration/` has no inbound
- * dependency on the store layer (Convention #4 dependency direction).
+ * The duplication this replaced existed to keep `session/migration/` free
+ * of an inbound dependency on the store layer, which was the right
+ * instinct — and it also meant this copy kept the fixed sidecar name after
+ * the stores were fixed. Living in `utils/` satisfies both: everything may
+ * depend on it, so there is nothing left to duplicate.
  */
 async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
-	const { writeFile, rename: renameFile, unlink } = await import('node:fs/promises')
-	const tmp = `${filePath}.tmp`
-	try {
-		await writeFile(tmp, JSON.stringify(value, null, 2), 'utf-8')
-		await renameFile(tmp, filePath)
-	} catch (err) {
-		await unlink(tmp).catch(() => undefined)
-		throw err
-	}
+	await atomicWriteFile(filePath, JSON.stringify(value, null, 2))
 }
 
 async function directoryExists(path: string): Promise<boolean> {

package/src/session/migration/marker.ts

@@ -17,9 +17,10 @@
  *    again"; a corrupt marker is safer to retry than to honor as valid.
  */
 
-import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import type { ProjectId } from '../../types/session/ids.js'
+import { atomicWriteFile } from '../../utils/atomic-write.js'
 
 /**
  * Marker payload. `migratedThreads` preserves the legacy → new mapping so
@@ -93,14 +94,9 @@ export async function writeMarker(path: string, marker: MigrationMarker): Promis
 			newProjectId: m.newProjectId as string,
 		})),
 	}
-	const tmp = `${path}.write.tmp`
-	try {
-		await writeFile(tmp, JSON.stringify(serialized, null, 2), 'utf-8')
-		await rename(tmp, path)
-	} catch (err) {
-		await unlink(tmp).catch(() => undefined)
-		throw err
-	}
+	// Through the shared writer, which picks a sidecar no other writer
+	// can pick. A fixed name is shared by every writer of the record.
+	await atomicWriteFile(path, JSON.stringify(serialized, null, 2))
 }
 
 /**