@namzu/sdk 60.1.0 → 60.2.1

package/src/runtime/query/executor.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import { join, resolve } from 'node:path'
+import { isAbsolute, join, resolve } from 'node:path'
 import type { Span } from '@opentelemetry/api'
 import type { AuthorizationGate } from '../../authorization/gate.js'
 import { unknownProgramInLine } from '../../authorization/program.js'
@@ -24,7 +24,7 @@ import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
 import { sandboxShellSpawn, withoutBashStartup } from '../../tools/command-shell.js'
 import { isAlwaysDestructive } from '../../tools/defineTool.js'
 import { createFileReadTracker } from '../../tools/file-read-tracker.js'
-import { pathOutsideRoots, toolRoots } from '../../tools/paths.js'
+import { pathOutsideRoots, resolveWithinAnyReal, toolRoots } from '../../tools/paths.js'
 import { resolveRetainedOutput } from '../../tools/retained-output.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type { ToolSourceRef } from '../../toolsets/types.js'
@@ -70,6 +70,7 @@ import { generateToolCallId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
 import { parseStructuredResultJson } from '../../utils/structured-result-json.js'
+import { ensureScratchpadDirectory } from '../../utils/temp.js'
 import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
 import { type BatchDetach, stillRunningResult } from './detached-calls.js'
 import {
@@ -155,12 +156,15 @@ export interface PreparedToolBatch {
 		readonly escalation?: ToolCallEscalation
 		/** What a `pre_tool_use` hook asked for this call's approval; see `ToolCallSummary.hookPermission`. */
 		readonly hookPermission?: PluginHookPermission
+		/** The call writes inside the session's scratch folder; see `ToolCallSummary.scratchpadWrite`. */
+		readonly scratchpadWrite?: true
 	}[]
 }
 
 interface OwnedPreparedToolBatch extends PreparedToolBatch {
 	readonly calls: ReadonlyMap<string, PreparedDirectCall>
 	readonly escalations: ReadonlyMap<string, ToolCallEscalation>
+	readonly scratchpadWrites: ReadonlySet<string>
 }
 
 /**
@@ -363,6 +367,13 @@ export interface ToolExecutorConfig {
 	workingDirectory: string
 	/** See `ToolContext.additionalDirectories`. */
 	additionalDirectories?: readonly string[]
+	/**
+	 * Where this session's own scratch folder is (it need not exist). It becomes
+	 * a root of the file tools, and a write inside it needs no review, once a call
+	 * names it and the folder has been made and checked. Unset on a sandboxed
+	 * turn and on a session with no layout on disk.
+	 */
+	scratchpadDirectory?: string
 	/** See `QueryParams.outsideRootAccess`. Default `'refuse'`. */
 	outsideRootAccess?: 'refuse' | 'review'
 	/** See `QueryParams.sandboxEscape`. Default `'refuse'`. */
@@ -814,6 +825,68 @@ export class ToolExecutor {
 	}
 
 	/** True once the turn has a sandbox, or is certain to get one before a tool runs. */
+	/** The scratch folder, once a call has named it and it has been made and checked. */
+	private scratchpadReady: string | undefined
+
+	/** The tools' roots now: the turn's, plus the scratch folder once it is ready. */
+	private rootsNow(): readonly string[] {
+		return toolRoots({
+			workingDirectory: this.config.workingDirectory,
+			additionalDirectories: this.additionalDirectoriesNow(),
+		})
+	}
+
+	private additionalDirectoriesNow(): readonly string[] | undefined {
+		if (this.scratchpadReady === undefined) return this.config.additionalDirectories
+		return [...(this.config.additionalDirectories ?? []), this.scratchpadReady]
+	}
+
+	/**
+	 * Make the session's scratch folder a root when a call names it. Lazy: a
+	 * session that never uses it leaves nothing on disk. The folder must be
+	 * inside the private temporary root with no link on the way; otherwise it
+	 * stays outside the roots and a path in it is asked about like any other.
+	 */
+	private admitScratchpad(call: PreparedSafetyCall): void {
+		const directory = this.config.scratchpadDirectory
+		if (directory === undefined || this.scratchpadReady !== undefined || this.sandboxed) return
+		if (call.kind === 'synthetic') return
+		let named = false
+		try {
+			named = JSON.stringify(call.input)?.includes(JSON.stringify(directory).slice(1, -1)) === true
+		} catch {
+			// An input that cannot be serialised names nothing.
+		}
+		if (!named) return
+		try {
+			this.scratchpadReady = ensureScratchpadDirectory(directory)
+		} catch (error) {
+			this.log.warn('The session scratch folder could not be made, so it stays outside the roots', {
+				'exception.message': error instanceof Error ? error.message : String(error),
+			})
+		}
+	}
+
+	/** Whether `call` writes a file inside the ready scratch folder and nothing else about it is notable. */
+	private async writesScratchpad(
+		call: PreparedSafetyCall,
+		escalation: ToolCallEscalation | undefined,
+	): Promise<boolean> {
+		const root = this.scratchpadReady
+		if (root === undefined || escalation !== undefined || call.kind === 'synthetic') return false
+		if (call.toolName !== 'write' && call.toolName !== 'edit') return false
+		const tool = this.config.tools.get(call.toolName)
+		if (!tool?.pathArgument || call.input === null || typeof call.input !== 'object') return false
+		const value = (call.input as Record<string, unknown>)[tool.pathArgument]
+		if (typeof value !== 'string' || !isAbsolute(value)) return false
+		try {
+			await resolveWithinAnyReal([root], value)
+			return true
+		} catch {
+			return false
+		}
+	}
+
 	private get sandboxed(): boolean {
 		return this.config.sandbox !== undefined || this.sandboxGate !== undefined
 	}
@@ -1126,6 +1199,7 @@ export class ToolExecutor {
 		if ((response.message.toolCalls ?? []).length > 0) await this.awaitSandbox()
 		const calls = new Map<string, PreparedDirectCall>()
 		const escalations = new Map<string, ToolCallEscalation>()
+		const scratchpadWrites = new Set<string>()
 		const earlierPaths: string[] = []
 		for (const toolCall of response.message.toolCalls ?? []) {
 			const prepared = await prepareDirectCall(
@@ -1137,11 +1211,13 @@ export class ToolExecutor {
 			const path = inputPathOf(prepared)
 			if (path !== undefined) earlierPaths.push(path)
 			calls.set(toolCall.id, call)
+			this.admitScratchpad(call)
 			const escalation = await this.escalationOrUnfinished(call)
 			if (escalation) escalations.set(toolCall.id, escalation)
+			if (await this.writesScratchpad(call, escalation)) scratchpadWrites.add(toolCall.id)
 		}
 		this.config.abortSignal.throwIfAborted()
-		return this.publishPreparedBatch(calls, escalations)
+		return this.publishPreparedBatch(calls, escalations, scratchpadWrites)
 	}
 
 	/**
@@ -1250,7 +1326,7 @@ export class ToolExecutor {
 				// result that was cut told the model to look.
 				const retained =
 					tool.name === 'read' && (await resolveRetainedOutput(this.outputDirectory(), value))
-				const outside = retained ? undefined : await pathOutsideRoots(toolRoots(this.config), value)
+				const outside = retained ? undefined : await pathOutsideRoots(this.rootsNow(), value)
 				if (outside !== undefined) outsidePaths = [outside]
 			}
 		}
@@ -1307,7 +1383,7 @@ export class ToolExecutor {
 		protectedPaths: readonly string[]
 		dangerousRemoval?: string
 	}> {
-		const roots = toolRoots(this.config)
+		const roots = this.rootsNow()
 		const protectedPaths: string[] = []
 		let outsidePaths: readonly string[] = []
 		let removal: string | undefined
@@ -1376,6 +1452,7 @@ export class ToolExecutor {
 		}
 		const calls = new Map((previous as OwnedPreparedToolBatch).calls)
 		const escalations = new Map((previous as OwnedPreparedToolBatch).escalations)
+		const scratchpadWrites = new Set((previous as OwnedPreparedToolBatch).scratchpadWrites)
 		const earlierPaths: string[] = []
 		for (const toolCall of response.message.toolCalls ?? []) {
 			if (changedCallIds.has(toolCall.id)) {
@@ -1384,21 +1461,25 @@ export class ToolExecutor {
 					earlierPaths,
 				)
 				calls.set(toolCall.id, call)
+				this.admitScratchpad(call)
 				const escalation = await this.escalationOrUnfinished(call)
 				if (escalation) escalations.set(toolCall.id, escalation)
 				else escalations.delete(toolCall.id)
+				if (await this.writesScratchpad(call, escalation)) scratchpadWrites.add(toolCall.id)
+				else scratchpadWrites.delete(toolCall.id)
 			}
 			const prepared = calls.get(toolCall.id)
 			const path = prepared ? inputPathOf(prepared) : undefined
 			if (path !== undefined) earlierPaths.push(path)
 		}
 		this.config.abortSignal.throwIfAborted()
-		return this.publishPreparedBatch(calls, escalations)
+		return this.publishPreparedBatch(calls, escalations, scratchpadWrites)
 	}
 
 	private publishPreparedBatch(
 		calls: ReadonlyMap<string, PreparedDirectCall>,
 		escalations: ReadonlyMap<string, ToolCallEscalation>,
+		scratchpadWrites: ReadonlySet<string>,
 	): PreparedToolBatch {
 		const reviewCalls = [...calls.values()]
 			.filter(
@@ -1414,12 +1495,14 @@ export class ToolExecutor {
 					input: call.input,
 					...(escalation ? { escalation } : {}),
 					...(hookPermission ? { hookPermission } : {}),
+					...(scratchpadWrites.has(call.toolCall.id) ? { scratchpadWrite: true as const } : {}),
 				}
 			})
 		const batch: OwnedPreparedToolBatch = Object.freeze({
 			reviewCalls: Object.freeze(reviewCalls),
 			calls: new Map(calls),
 			escalations: new Map(escalations),
+			scratchpadWrites: new Set(scratchpadWrites),
 		})
 		this.preparedBatches.add(batch)
 		return batch
@@ -2032,6 +2115,7 @@ export class ToolExecutor {
 		} catch {
 			needsApproval = true
 		}
+		this.admitScratchpad(preparedCall)
 		const nestedEscalation = await this.escalationOrUnfinished(preparedCall)
 		if (nestedEscalation || needsApproval || (gateResult && gateResult.decision !== 'allow')) {
 			const reason = nestedEscalation
@@ -2276,8 +2360,8 @@ export class ToolExecutor {
 			sessionId: this.config.sessionId,
 			turnId: this.config.turnId,
 			workingDirectory: this.config.workingDirectory,
-			...(this.config.additionalDirectories?.length
-				? { additionalDirectories: this.config.additionalDirectories }
+			...(this.additionalDirectoriesNow()?.length
+				? { additionalDirectories: this.additionalDirectoriesNow() }
 				: {}),
 			...(this.config.authorizationGate
 				? {

package/src/runtime/query/index.ts

@@ -1542,6 +1542,17 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		// pre-approves ends with the turn. Shared by the executor, where the
 		// `skill` tool records a grant, and the review phase, which reads it.
 		const skillGrants = new SkillGrantSet()
+		// The session's own scratch folder, a root of the file tools once a call
+		// names it. Not for a sandboxed turn (it is not mounted there), and not
+		// for a session whose state is not on disk.
+		let scratchpadDirectory: string | undefined
+		if (!params.sandboxProvider) {
+			try {
+				scratchpadDirectory = ctx.storage.paths?.scratchpadPath(ctx.sessionId)
+			} catch {
+				scratchpadDirectory = undefined
+			}
+		}
 		const toolExecutor = ToolingBootstrap.init(
 			{
 				skillGrants,
@@ -1555,6 +1566,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				...(params.additionalDirectories?.length
 					? { additionalDirectories: params.additionalDirectories }
 					: {}),
+				...(scratchpadDirectory ? { scratchpadDirectory } : {}),
 				...(params.outsideRootAccess ? { outsideRootAccess: params.outsideRootAccess } : {}),
 				...(params.sandboxEscape ? { sandboxEscape: params.sandboxEscape } : {}),
 				permissionMode: () => ctx.permissionMode.current,

package/src/runtime/query/iteration/index.ts

@@ -73,6 +73,7 @@ import {
 	markProviderRejectedImage,
 	projectRequestRichContent,
 } from '../request-rich-content.js'
+import { withoutVoidAssistantTurns } from '../request-void-turns.js'
 import { formatSteeringNote, isOperatorUserMessage } from '../steering.js'
 import { effortForModel } from './effort-clamp.js'
 import { parseNativeCandidate } from './native-output.js'
@@ -929,7 +930,7 @@ export class IterationOrchestrator {
 					// and a mode change would re-key the whole conversation.
 					if (policyNotice) requestHistory.push(stepContextMessage(policyNotice))
 					const projected = projectRequestRichContent(
-						this.projectObservations(requestHistory),
+						withoutVoidAssistantTurns(this.projectObservations(requestHistory)),
 						this.ctx.turnConfig.maxRequestRichContentBytes ??
 							DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 						{ imagesReadable: this.modelReadsImages(stepModel) },
@@ -3155,7 +3156,7 @@ export class IterationOrchestrator {
 				...(workingMemory.context ? [workingMemory.context] : []),
 			]
 			const finalMessages = projectRequestRichContent(
-				this.projectObservations(finalHistory),
+				withoutVoidAssistantTurns(this.projectObservations(finalHistory)),
 				this.ctx.turnConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 				{ imagesReadable: this.modelReadsImages(model) },
 			)

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -238,6 +238,12 @@ export async function* runToolReview(
 				...(requiresApproval ? { requiresApproval: true as const } : {}),
 				...(escalation ? { escalation } : {}),
 				...(hookPermission ? { hookPermission } : {}),
+				...('scratchpadWrite' in tc && tc.scratchpadWrite
+					? { scratchpadWrite: true as const }
+					: {}),
+				...('scratchpadWrite' in tc && tc.scratchpadWrite
+					? { scratchpadWrite: true as const }
+					: {}),
 			}
 		})
 	}

package/src/runtime/query/request-void-turns.ts

@@ -0,0 +1,28 @@
+import type { Message } from '../../types/message/index.js'
+
+/**
+ * The provider-bound view of a conversation without assistant entries that
+ * carry nothing at all: no text, no tool call, no reasoning, no citation.
+ *
+ * An empty reply (a refused or cut-off model, or a completion that produced
+ * nothing) is recorded in the history, and the loop goes on to ask again, so
+ * the next request would carry it. Chat Completions endpoints reject such an
+ * entry ("content or tool_calls must be set"), and no wire gives it a meaning.
+ * The stored history is never edited; only the request leaves it out.
+ *
+ * An entry that still holds reasoning stays: a driver whose wire replays signed
+ * or native reasoning needs it, and each driver decides what a reasoning-only
+ * entry looks like on its own wire. An entry with tool calls always stays, so a
+ * tool result still follows the call it answers. Returns the original array
+ * when nothing is dropped.
+ */
+export function withoutVoidAssistantTurns(messages: Message[]): Message[] {
+	const isVoid = (message: Message): boolean =>
+		message.role === 'assistant' &&
+		!message.content &&
+		(message.toolCalls?.length ?? 0) === 0 &&
+		(message.reasoning?.length ?? 0) === 0 &&
+		(message.citations?.length ?? 0) === 0 &&
+		(message.textParts?.length ?? 0) === 0
+	return messages.some(isVoid) ? messages.filter((message) => !isVoid(message)) : messages
+}

package/src/runtime/query/review-policy.ts

@@ -1051,8 +1051,19 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			mode === 'plan' &&
 			options.planModeWrite?.(tc) === true &&
 			tc.authorization?.decision !== 'deny'
+		// A file written inside the session's own scratch folder, in any mode but
+		// `strict`: the folder is the session's, so it is not a change anyone
+		// reviews, and not "outside the roots". A rule that asked for review keeps
+		// the call in the batch; a deny still refuses it.
+		const isScratchpadWrite = (tc: ToolCallSummary): boolean =>
+			mode !== 'strict' &&
+			tc.scratchpadWrite === true &&
+			tc.escalation === undefined &&
+			tc.requiresApproval !== true &&
+			!tc.authorization?.explicitReview &&
+			tc.authorization?.decision !== 'deny'
 		const reviewable = request.toolCalls.filter(
-			(tc) => !(isPlanFileWrite(tc) && !tc.authorization?.explicitReview),
+			(tc) => !(isPlanFileWrite(tc) && !tc.authorization?.explicitReview) && !isScratchpadWrite(tc),
 		)
 		if (!batchNeedsReview(reviewable, exempt)) {
 			return { action: 'approve_tools' }
@@ -1089,7 +1100,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		if (
 			mode === 'plan' &&
 			!onlyReadsOutsideRoots(
-				reviewable.filter((tc) => !isPlanFileWrite(tc)),
+				reviewable.filter((tc) => !isPlanFileWrite(tc) && !isScratchpadWrite(tc)),
 				exempt,
 			)
 		) {

package/src/runtime/query/tooling.ts

@@ -28,6 +28,8 @@ export interface ToolingBootstrapConfig {
 	workingDirectory: string
 	/** See `QueryParams.additionalDirectories`. */
 	additionalDirectories?: readonly string[]
+	/** See `ToolExecutorConfig.scratchpadDirectory`. */
+	scratchpadDirectory?: string
 	/** See `QueryParams.outsideRootAccess`. */
 	outsideRootAccess?: 'refuse' | 'review'
 	/** See `QueryParams.sandboxEscape`. */
@@ -99,6 +101,7 @@ export class ToolingBootstrap {
 				...(config.additionalDirectories?.length
 					? { additionalDirectories: config.additionalDirectories }
 					: {}),
+				...(config.scratchpadDirectory ? { scratchpadDirectory: config.scratchpadDirectory } : {}),
 				...(config.outsideRootAccess ? { outsideRootAccess: config.outsideRootAccess } : {}),
 				...(config.sandboxEscape ? { sandboxEscape: config.sandboxEscape } : {}),
 				permissionMode: config.permissionMode,

package/src/sandbox/provider/local.ts

@@ -53,6 +53,7 @@ import {
 	applyEnvironmentOverrides,
 	pickEnvironmentEntries,
 } from '../../utils/process-environment.js'
+import { createTempDir, resolveTempBase } from '../../utils/temp.js'
 import { walkFilesLocally } from '../file-walk.js'
 import { assertIsolation, describeIsolation } from '../isolation.js'
 import type { PtyLoader } from '../terminal.js'
@@ -317,7 +318,7 @@ function detectEnvironment(): DetectedEnvironment {
 		// hosts that mediate namespace helpers and can claim a tier production
 		// cannot actually drive.
 		const bwrap = resolveTrustedWrapper('bwrap')
-		if (bwrap !== undefined && probeBwrapSpawn(bwrap, buildBwrapArgs(tmpdir()))) {
+		if (bwrap !== undefined && probeBwrapSpawn(bwrap, buildBwrapArgs(resolveTempBase()))) {
 			return { environment: 'linux-bwrap', wrapperCommand: bwrap }
 		}
 
@@ -329,7 +330,10 @@ function detectEnvironment(): DetectedEnvironment {
 
 	if (platform === 'darwin') {
 		const seatbelt = resolveTrustedWrapper('sandbox-exec')
-		if (seatbelt !== undefined && probeSandboxSpawn(seatbelt, buildSeatbeltArgs(tmpdir()))) {
+		if (
+			seatbelt !== undefined &&
+			probeSandboxSpawn(seatbelt, buildSeatbeltArgs(resolveTempBase()))
+		) {
 			return { environment: 'macos-seatbelt', wrapperCommand: seatbelt }
 		}
 	}
@@ -1091,7 +1095,7 @@ class LocalSandbox implements Sandbox {
 					exitCode,
 					stderr: stderr.text,
 					timedOut,
-					allowedRoots: [...this.roots, tmpdir(), '/tmp', '/var/tmp', '/dev'],
+					allowedRoots: [...this.roots, tmpdir(), resolveTempBase(), '/tmp', '/var/tmp', '/dev'],
 				})
 				resolvePromise({
 					exitCode,
@@ -1229,8 +1233,7 @@ export class LocalSandboxProvider implements SandboxProvider {
 			}
 		} else {
 			// No workspace was named: this allocation owns a fresh temporary root.
-			const { mkdtemp } = await import('node:fs/promises')
-			const rawDir = await mkdtemp(join(tmpdir(), SANDBOX_TEMP_DIR_PREFIX))
+			const rawDir = await createTempDir(SANDBOX_TEMP_DIR_PREFIX)
 			rootDir = canonicalizePath(rawDir)
 			removeRootOnDestroy = true
 		}

package/src/session/paths.ts

@@ -1,7 +1,5 @@
 import { createHash } from 'node:crypto'
-import { lstatSync, mkdirSync } from 'node:fs'
 import { link, mkdir, open, readFile, realpath, unlink } from 'node:fs/promises'
-import { tmpdir, userInfo } from 'node:os'
 import { basename, dirname, join } from 'node:path'
 import type {
 	CheckpointId,
@@ -14,6 +12,12 @@ import type {
 } from '../types/ids/index.js'
 import { type ProjectDocument, ProjectDocumentSchema } from '../types/session/records.js'
 import { type EntityIdKind, asSessionId, generateProjectId, isEntityId } from '../utils/id.js'
+import {
+	type PrivateTempRootOptions,
+	TempDirectoryError,
+	privateTempRoot,
+	privateTempRootPath,
+} from '../utils/temp.js'
 import { uuidv7 } from '../utils/uuidv7.js'
 
 /**
@@ -243,68 +247,26 @@ export async function ensureProject(options: EnsureProjectOptions): Promise<Ensu
 	)
 }
 
-export interface TempRootOptions {
-	/** Base directory. Default `os.tmpdir()`. */
-	readonly tmpdir?: string
-	/** Default `process.platform`. */
-	readonly platform?: NodeJS.Platform
-	/**
-	 * Default `process.getuid`. Pass `undefined` explicitly to model a
-	 * platform without it (win32).
-	 */
-	readonly getuid?: (() => number) | undefined
-	/** Default `os.userInfo().username`. */
-	readonly username?: () => string
-}
+/** See {@link PrivateTempRootOptions}; `tmpdir` is the base. */
+export type TempRootOptions = PrivateTempRootOptions
 
 /**
- * The per-user temporary root, `$TMPDIR/namzu-<user>`, created if missing.
- *
- * `<user>` is the numeric uid where the platform has one; otherwise the first
- * 12 hex digits of the SHA-256 of the user name; otherwise `user`. On POSIX
- * the directory is created with mode 0700 and refused if it is a symlink, not
- * a directory, owned by another uid, or open to group or others. On win32
- * `%TEMP%` is already per user: a symlink or junction is refused and the
- * owner check is skipped.
+ * The per-user temporary root, `<base>/namzu-<user>`, created if missing,
+ * where the base is `NAMZU_TMPDIR` or `os.tmpdir()`. A root that is a symlink,
+ * not a directory, owned by another uid or open to others is refused with a
+ * {@link SessionPathError}; one that cannot be created raises the
+ * {@link TempDirectoryError} that names the directory and `NAMZU_TMPDIR`.
+ * See {@link privateTempRoot}.
  */
 export function tempRoot(options: TempRootOptions = {}): string {
-	const platform = options.platform ?? process.platform
-	const getuid = 'getuid' in options ? options.getuid : process.getuid?.bind(process)
-	let user = 'user'
-	if (typeof getuid === 'function') {
-		user = String(getuid())
-	} else {
-		try {
-			const name = (options.username ?? (() => userInfo().username))()
-			if (name.length > 0) user = sha256Hex(name).slice(0, 12)
-		} catch {
-			// No user database entry: fall back to the fixed segment.
-		}
-	}
-	const root = join(options.tmpdir ?? tmpdir(), `namzu-${user}`)
 	try {
-		mkdirSync(root, { mode: 0o700 })
+		return privateTempRoot(options)
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
-	}
-	const entry = lstatSync(root)
-	if (entry.isSymbolicLink()) {
-		throw new SessionPathError(`Refusing temporary root ${root}: it is a symbolic link.`)
-	}
-	if (!entry.isDirectory()) {
-		throw new SessionPathError(`Refusing temporary root ${root}: it is not a directory.`)
-	}
-	if (platform !== 'win32' && typeof getuid === 'function') {
-		if (entry.uid !== getuid()) {
-			throw new SessionPathError(`Refusing temporary root ${root}: it belongs to uid ${entry.uid}.`)
-		}
-		if ((entry.mode & 0o077) !== 0) {
-			throw new SessionPathError(
-				`Refusing temporary root ${root}: mode ${(entry.mode & 0o777).toString(8)} lets other users in; it must be 700.`,
-			)
+		if (error instanceof TempDirectoryError && error.reason === 'refused') {
+			throw new SessionPathError(error.message)
 		}
+		throw error
 	}
-	return root
 }
 
 /** Every path of one project's layout. Pure: nothing is created or read. */
@@ -451,9 +413,22 @@ export class SessionPaths {
 		return join(this.sessionDir(locator), 'lease.json')
 	}
 
-	/** `$TMPDIR/namzu-<user>/<slug>/<session-id>/scratchpad`. Not created; the per-user root is. */
+	/** `<temp base>/namzu-<user>/<slug>/<session-id>/scratchpad`. Not created; the per-user root is. */
 	tempDir(sessionId: SessionId): string {
 		this.#tempRoot ??= tempRoot()
 		return join(this.#tempRoot, this.slug, checkId(sessionId, 'session'), 'scratchpad')
 	}
+
+	/**
+	 * Where {@link tempDir} is, creating and checking nothing, not even the
+	 * per-user root: for a caller that makes the folder only when it is first used.
+	 */
+	scratchpadPath(sessionId: SessionId): string {
+		return join(
+			this.#tempRoot ?? privateTempRootPath(),
+			this.slug,
+			checkId(sessionId, 'session'),
+			'scratchpad',
+		)
+	}
 }