@namzu/sdk 60.0.0 → 60.2.0

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

@@ -7,6 +7,8 @@ import { estimateMessageTokens } from '../../../compaction/token-estimate.js'
 import {
 	AUTO_CONTINUATION_USER_MESSAGE,
 	REASONING_CUT_USER_MESSAGE,
+	REFUSED_REPLY_CALL_RESULT,
+	REFUSED_REPLY_RETRY_MESSAGE,
 } from '../../../constants/continuation.js'
 import { CHARS_PER_TOKEN } from '../../../constants/limits.js'
 import {
@@ -37,6 +39,7 @@ import {
 	createAssistantMessage,
 	createRuntimeContextMessage,
 	createSystemMessage,
+	createToolMessage,
 } from '../../../types/message/index.js'
 import { classifyProviderError, readOutputOverflow } from '../../../types/provider/errors.js'
 import type { ChatCompletionResponse } from '../../../types/provider/index.js'
@@ -71,6 +74,7 @@ import {
 	projectRequestRichContent,
 } from '../request-rich-content.js'
 import { formatSteeringNote, isOperatorUserMessage } from '../steering.js'
+import { effortForModel } from './effort-clamp.js'
 import { parseNativeCandidate } from './native-output.js'
 import {
 	drainArrivedTaskCompletions,
@@ -225,7 +229,10 @@ export class IterationOrchestrator {
 	 * serving from the member it last moved to, so that member, not the head,
 	 * is the one whose reading of images counts.
 	 */
-	private servingModel(model: string): { readonly providerId: string; readonly model: string } {
+	private servingModel(model: string): {
+		readonly providerId: string
+		readonly model: string
+	} {
 		const serving = this.ctx.servingMember?.()
 		return {
 			providerId: serving?.providerId ?? this.ctx.provider.id,
@@ -291,6 +298,16 @@ export class IterationOrchestrator {
 	private stopDeferredForOutstandingWork = false
 	/** Nudges sent since the model last finished a call without hitting its output cap. */
 	private outputContinuations = 0
+	/**
+	 * The model a refused request moved to. Once set it replaces the model the
+	 * step asked for, for the rest of the turn: the request that was refused
+	 * would only be refused again.
+	 */
+	private refusalPinnedModel: string | undefined
+	/** The request has already been re-run on another model once this turn. */
+	private refusalFallbackUsed = false
+	/** The request has already been re-run on the same model once this turn. */
+	private refusalRetryUsed = false
 	/**
 	 * `turn_end` (and, for a child, `subagent_stop`) fired when the model
 	 * finished and no hook asked for more. `finalizeTurn` then does not fire
@@ -319,7 +336,11 @@ export class IterationOrchestrator {
 		const feedback: string[] = []
 		const ask = async (
 			event: 'turn_end' | 'subagent_stop',
-			extra: { parentSessionId?: SessionId; parentTurnId?: TurnId; agentType?: string },
+			extra: {
+				parentSessionId?: SessionId
+				parentTurnId?: TurnId
+				agentType?: string
+			},
 		): Promise<void> => {
 			const results = await manager.executeHooks(
 				event,
@@ -795,7 +816,7 @@ export class IterationOrchestrator {
 					// Preparation inference belongs to the turn, not the main-model step.
 					usageBefore = { ...recorder.tokenUsage }
 					costBefore = { ...recorder.costInfo }
-					stepModel = step.model ?? model
+					stepModel = this.refusalPinnedModel ?? step.model ?? model
 					await selectContextModel(shaping, stepModel)
 					// Preserve post-compaction preparation/recall semantics. A changed
 					// model needs a second check against its own window; never replay
@@ -824,7 +845,7 @@ export class IterationOrchestrator {
 					// still call any of them by name.
 					this.ctx.toolExecutor.setStepAllowedTools(stepAllowedTools)
 					const enforceToolInputSchema = enforcedModelInputToolNames(this.ctx.tools, llmTools)
-					stepModel = step.model ?? model
+					stepModel = this.refusalPinnedModel ?? step.model ?? model
 
 					// The closing directive is appended LAST, after every piece of
 					// request-only context below, so it is the final thing the model
@@ -1051,6 +1072,25 @@ export class IterationOrchestrator {
 						model: requestedMember.model ?? stepModel,
 						chainIndex: requestedMember.index,
 					}
+					// The turn's effort was chosen for the turn's own model. A request
+					// moved to another model (a refusal fallback, a live pick) carries
+					// the nearest level that model offers, for this request only.
+					let requestEffort = turnConfig.effort
+					if (requestEffort && stepModel !== model) {
+						requestEffort = effortForModel(
+							this.ctx.provider,
+							stepModel,
+							requestEffort,
+							turnConfig.thinking,
+						)
+						if (requestEffort !== turnConfig.effort) {
+							this.ctx.log.debug('Effort lowered to a level this model offers', {
+								'namzu.runtime.model': stepModel,
+								'namzu.runtime.effort_requested': turnConfig.effort,
+								'namzu.runtime.effort_used': requestEffort,
+							})
+						}
+					}
 					const operatorInputAtDispatch = this.latestUserMessage
 					const latestReviewUserMessage =
 						(this.ctx.reviewAnswer || this.ctx.structuredOutput?.review) && operatorInputAtDispatch
@@ -1092,7 +1132,7 @@ export class IterationOrchestrator {
 								outputCapOverride ?? step.maxResponseTokens ?? turnConfig.maxResponseTokens,
 							cacheControl: { type: 'auto' },
 							...(turnConfig.thinking ? { thinking: turnConfig.thinking } : {}),
-							...(turnConfig.effort ? { effort: turnConfig.effort } : {}),
+							...(requestEffort ? { effort: requestEffort } : {}),
 							...(!forceFinalize && turnConfig.webSearch
 								? { webSearch: turnConfig.webSearch }
 								: {}),
@@ -1247,6 +1287,34 @@ export class IterationOrchestrator {
 						...contextFigures,
 					})
 
+					// A reply the provider declined to give is its own case. It is not
+					// an empty completion: asking again with the same history on the
+					// same model is refused again, at the full price of the prompt.
+					// Recovered here, before the reply can enter the history.
+					if (response.finishReason === 'content_filter') {
+						iterSpan.setStatus({ code: SpanStatusCode.OK })
+						if (iterationActivity) {
+							this.ctx.activityStore.complete(iterationActivity.id, {
+								content: response.message.content,
+								hasToolCalls: false,
+							})
+						}
+						const outcome = yield* this.recoverFromRefusal({
+							response,
+							messageId,
+							stepModel,
+							servedBy,
+							forceFinalize,
+							limitStopReason: forceFinalize ? guardResult.stopReason : undefined,
+							iterationNum,
+							stepStartedAt,
+							usageBefore,
+							costBefore,
+						})
+						if (outcome === 'retry') continue
+						break
+					}
+
 					// Durable reasoning and its adapter-private replay envelope ride
 					// with the turn they belong to. Trimming therefore removes both;
 					// retaining them gives the target adapter enough evidence to
@@ -1681,7 +1749,10 @@ export class IterationOrchestrator {
 								[NAMZU.ITERATION]: iterationNum,
 								'namzu.runtime.finish_reason': response.finishReason,
 							})
-							closingStopReason = await this.requestFinalResponse(model, 'end_turn')
+							closingStopReason = await this.requestFinalResponse(
+								this.refusalPinnedModel ?? model,
+								'end_turn',
+							)
 							yield* this.ctx.drainPending()
 						}
 
@@ -2873,6 +2944,179 @@ export class IterationOrchestrator {
 		})
 	}
 
+	/**
+	 * A reply the provider declined to give.
+	 *
+	 * The refused reply never enters the history sent next, except on the
+	 * same-model retry, where the stopped partial reply stays so the model can
+	 * see what to avoid. At most one automatic retry of each kind per turn:
+	 *
+	 * 1. Another model of the same provider, when the provider names one and
+	 *    the host has not turned `refusalFallback` off. The model is kept for
+	 *    the rest of the turn and announced in a `model_refusal` event.
+	 * 2. The same model once more, only when the refused reply had partial
+	 *    text or tool calls: unfinished calls get an error result and the
+	 *    model is told the reply was stopped.
+	 * 3. Otherwise the turn settles `refused`.
+	 */
+	private async *recoverFromRefusal(input: {
+		response: ChatCompletionResponse
+		messageId: MessageId
+		stepModel: string
+		servedBy: StepProvenance
+		forceFinalize: boolean
+		/** The limit that asked for this closing step; it stays the reason the turn ended. */
+		limitStopReason?: StopReason | undefined
+		iterationNum: number
+		stepStartedAt: number
+		usageBefore: TokenUsage
+		costBefore: CostInfo
+	}): AsyncGenerator<SessionEvent, 'retry' | 'settled'> {
+		const { recorder } = this.ctx
+		const { response, servedBy, iterationNum } = input
+		const refusal = response.refusal ?? {}
+		const toolCalls = response.message.toolCalls ?? []
+		const hasPartial =
+			(response.message.content !== null && response.message.content.length > 0) ||
+			toolCalls.length > 0
+
+		this.ctx.log.warn('The model declined to answer', {
+			[NAMZU.TURN_ID]: recorder.turnId,
+			[NAMZU.ITERATION]: iterationNum,
+			'namzu.runtime.model': servedBy.model,
+			'namzu.runtime.refusal_category': refusal.category,
+			'namzu.runtime.has_partial_output': hasPartial,
+		})
+
+		const announce = async (outcome: 'fallback' | 'retry' | 'declined', fallbackModel?: string) => {
+			await this.ctx.emitEvent({
+				type: 'model_refusal',
+				turnId: recorder.turnId,
+				iteration: iterationNum,
+				model: servedBy.model,
+				providerId: servedBy.providerId,
+				outcome,
+				...(fallbackModel !== undefined ? { fallbackModel } : {}),
+				...(refusal.category ? { category: refusal.category } : {}),
+				...(refusal.explanation ? { explanation: refusal.explanation } : {}),
+			})
+		}
+		const closeIteration = async () => {
+			this.recordStep({
+				stepNumber: iterationNum,
+				model: input.stepModel,
+				servedBy,
+				messageId: input.messageId,
+				response,
+				toolResults: [],
+				toolExecutionMs: 0,
+				startedAt: input.stepStartedAt,
+				usageBefore: input.usageBefore,
+				costBefore: input.costBefore,
+			})
+			await this.ctx.emitEvent({
+				type: 'iteration_completed',
+				turnId: recorder.turnId,
+				iteration: iterationNum,
+				hasToolCalls: false,
+			})
+		}
+
+		if (this.ctx.abortController.signal.aborted) {
+			recorder.setStopReason('cancelled')
+			recorder.markCancelled()
+			await closeIteration()
+			yield* this.ctx.drainPending()
+			return 'settled'
+		}
+
+		if (!input.forceFinalize && !this.refusalFallbackUsed && this.ctx.refusalFallback !== 'off') {
+			const next = await this.refusalFallbackModel(input.stepModel, refusal)
+			if (next !== undefined) {
+				this.refusalFallbackUsed = true
+				this.refusalPinnedModel = next
+				await announce('fallback', next)
+				await closeIteration()
+				yield* this.ctx.drainPending()
+				return 'retry'
+			}
+		}
+
+		if (!input.forceFinalize && !this.refusalRetryUsed && hasPartial) {
+			this.refusalRetryUsed = true
+			recorder.pushMessage(
+				withStreamedMessageIdentity(
+					createAssistantMessage(
+						response.message.content,
+						toolCalls.length > 0 ? toolCalls : undefined,
+						response.message.reasoning,
+						response.message.citations,
+						{
+							type: 'model',
+							...servedBy,
+							...(response.message.replayState !== undefined
+								? { replayState: response.message.replayState }
+								: {}),
+						},
+						response.message.textParts,
+					),
+					input.messageId,
+				),
+			)
+			for (const call of toolCalls) {
+				recorder.pushMessage(createToolMessage(REFUSED_REPLY_CALL_RESULT, call.id, true))
+			}
+			recorder.pushMessage(
+				createRuntimeContextMessage(REFUSED_REPLY_RETRY_MESSAGE, 'refusal-retry'),
+			)
+			await announce('retry')
+			await closeIteration()
+			yield* this.ctx.drainPending()
+			return 'retry'
+		}
+
+		recorder.setLastError(
+			`${servedBy.model} declined to answer this message${refusal.explanation ? `: ${refusal.explanation}` : '.'}`,
+		)
+		// A closing step that a limit asked for keeps that limit as the reason
+		// the turn ended; the refusal is still announced.
+		recorder.setStopReason(input.limitStopReason ?? 'refused')
+		await announce('declined')
+		await closeIteration()
+		yield* this.ctx.drainPending()
+		return 'settled'
+	}
+
+	/**
+	 * Another model to try after `model` declined, or `undefined` when there is
+	 * none. Only the provider can say: it names its own recommendation or its
+	 * own declared order, checked against what this credential can serve. A
+	 * chain member declared with a model of its own cannot be swapped, because
+	 * the chain would put its own model back on the request.
+	 */
+	private async refusalFallbackModel(
+		model: string,
+		refusal: NonNullable<ChatCompletionResponse['refusal']>,
+	): Promise<string | undefined> {
+		if (this.ctx.servingMember?.()?.model !== undefined) return undefined
+		const pick = this.ctx.provider.refusalFallbackFor
+		if (!pick) return undefined
+		try {
+			const next = await pick.call(
+				this.ctx.provider,
+				model,
+				refusal,
+				this.ctx.abortController.signal,
+			)
+			return next !== undefined && next.length > 0 && next !== model ? next : undefined
+		} catch (err) {
+			this.ctx.log.warn('The provider could not name a model to retry a refusal on', {
+				'exception.message': toErrorMessage(err),
+			})
+			return undefined
+		}
+	}
+
 	private async requestFinalResponse(
 		model: string,
 		reason: StopReason,
@@ -2980,6 +3224,16 @@ export class IterationOrchestrator {
 				model: servedBy.model,
 			})
 
+			// A closing request the provider declined has nothing to add, and its
+			// empty reply must not be stored or sent again.
+			if (response.finishReason === 'content_filter') {
+				this.ctx.log.warn('The closing response was declined by the model', {
+					[NAMZU.TURN_ID]: this.ctx.recorder.turnId,
+					'namzu.runtime.model': servedBy.model,
+				})
+				return undefined
+			}
+
 			const finalMessageId = generateMessageId()
 			const assistantMsg = withStreamedMessageIdentity(
 				createAssistantMessage(

package/src/runtime/query/iteration/phases/context.ts

@@ -224,6 +224,8 @@ export interface IterationContext {
 	readonly compactionConfig?: CompactionConfig
 	/** See `QueryParams.maxOutputContinuations`. */
 	readonly maxOutputContinuations?: number
+	/** See `QueryParams.refusalFallback`. */
+	readonly refusalFallback?: 'auto' | 'off'
 
 	/**
 	 * What the driver said this model's context window is, resolved once.

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/iteration/stream-turn.ts

@@ -284,6 +284,8 @@ export async function* streamProviderTurn(
 	let reportedFinishReason: ChatCompletionResponse['finishReason'] | undefined
 	// Which limit a 'length' finish reached, when it was the context window.
 	let finishDetail: ChatCompletionResponse['finishDetail']
+	// What the provider said about a refusal, kept with the finish that carried it.
+	let refusal: ChatCompletionResponse['refusal']
 	let usage: ChatCompletionResponse['usage'] = {
 		promptTokens: 0,
 		completionTokens: 0,
@@ -416,6 +418,7 @@ export async function* streamProviderTurn(
 		finishReason = 'stop'
 		reportedFinishReason = undefined
 		finishDetail = undefined
+		refusal = undefined
 		streamedLength = 0
 		lastOutputCall = undefined
 		usage = {
@@ -766,6 +769,7 @@ export async function* streamProviderTurn(
 				reportedFinishReason = chunk.finishReason
 				finishDetail = chunk.finishReason === 'length' ? chunk.finishDetail : undefined
 			}
+			if (chunk.refusal) refusal = chunk.refusal
 			// Merge (per-field max), not last-write-wins: a late usage frame that
 			// omits input/cache tokens must not zero the counts seen earlier in the
 			// stream, which would under-report this turn's accumulated usage.
@@ -1061,6 +1065,7 @@ export async function* streamProviderTurn(
 		},
 		finishReason: effectiveFinishReason,
 		...(effectiveFinishReason === 'length' && finishDetail ? { finishDetail } : {}),
+		...(effectiveFinishReason === 'content_filter' && refusal ? { refusal } : {}),
 		usage,
 	}
 

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',
+		)
+	}
 }

package/src/store/memory/disk.ts

@@ -261,6 +261,7 @@ export class DiskMemoryStore implements ConditionalMemoryStore {
 		const release = await acquireMemoryOperationLock(
 			join(dirname(location.indexPath), 'operation.lock'),
 			this.lockTimeoutMs,
+			{ logger: this.log },
 		)
 		try {
 			await this.reloadIndex(location)

package/src/store/memory/markdown.ts

@@ -418,6 +418,7 @@ export class MarkdownMemoryStore implements ConditionalMemoryStore {
 		const release = await acquireMemoryOperationLock(
 			join(dir, 'operation.lock'),
 			this.lockTimeoutMs,
+			{ logger: this.log },
 		)
 		try {
 			const { loaded, superseded } = await this.load(dir, mode.importing ?? false)