@namzu/sdk 43.0.0 → 44.0.0

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

@@ -1,11 +1,11 @@
 /**
- * How a run resolves calls routed to review.
+ * How a turn resolves calls routed to review.
  *
  * An authorization rule says what a tool may do. A review policy says what
  * happens to calls the rules did not cover or explicitly routed to REVIEW.
  * The two axes are separate on purpose — a rule is a durable
- * statement an operator reviewed, and a mode is a property of ONE run, the
- * difference between "we never force-push" and "this run is unattended".
+ * statement an operator reviewed, and a mode is a property of ONE turn, the
+ * difference between "we never force-push" and "this turn is unattended".
  *
  * Only calls the gate routed to review arrive here. A rule that denied one
  * already stopped it, and a rule that allowed one never asked. So a mode
@@ -25,13 +25,13 @@ import type { ToolRegistry } from '../../registry/tool/execute.js'
 import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
 import type { HITLResumeDecision, ResumeHandler, ToolCallSummary } from '../../types/hitl/index.js'
 import type { ApprovalPolicy } from '../../types/hitl/policy.js'
-import type { RunId } from '../../types/ids/index.js'
+import type { SessionId, TurnId } from '../../types/ids/index.js'
 import { PLAN_MODE_REFUSAL } from '../../types/permission/index.js'
 
 export type ReviewMode =
 	/** Ask a person. The default when a `prompt` is supplied. */
 	| 'prompt'
-	/** Approve it. The default without a `prompt`, and what every headless run has always done. */
+	/** Approve it. The default without a `prompt`, and what every headless turn has always done. */
 	| 'auto'
 	/**
 	 * Approve a file edit, ask about everything else.
@@ -46,8 +46,9 @@ export type ReviewMode =
 	 */
 	| 'accept-edits'
 	/**
-	 * Read and think, do not act. A call that only reads is approved; a call
-	 * that would change anything is refused with feedback telling the model
+	 * Read and think, do not act. A call that only reads is approved (one that
+	 * reads outside the roots is asked about, as in every mode but `strict`); a
+	 * call that would change anything is refused with feedback telling the model
 	 * to present its plan instead. The operator reads the plan and switches
 	 * mode to have it carried out — the switch IS the approval. The kernel's
 	 * `permissionMode: 'plan'` is the floor under this: it blocks a mutating
@@ -58,7 +59,7 @@ export type ReviewMode =
 	/**
 	 * Refuse it. Nothing runs unless a rule allowed it by name or pattern —
 	 * the allowlist is the whole permission surface, which is the only form
-	 * an unattended run can actually be reasoned about.
+	 * an unattended turn can actually be reasoned about.
 	 */
 	| 'strict'
 
@@ -78,7 +79,7 @@ export { PLAN_MODE_REFUSAL }
 
 /** What the model is told when a call is refused under `strict`. */
 export const STRICT_MODE_REFUSAL =
-	'Refused: this run only permits tools an explicit rule allows, and no rule covers this call. Asking again will not change it — either the operator adds a rule, or this has to be done another way.'
+	'Refused: this turn only permits tools an explicit rule allows, and no rule covers this call. Asking again will not change it — either the operator adds a rule, or this has to be done another way.'
 
 /** The tools `accept-edits` approves without asking. Everything else prompts. */
 export const ACCEPT_EDITS_TOOLS: ReadonlySet<string> = new Set(['edit', 'write'])
@@ -98,7 +99,7 @@ export const ACCEPT_EDITS_TOOLS: ReadonlySet<string> = new Set(['edit', 'write']
  *
  * `save_memory` is deliberately NOT here. Content saved now is retrievable
  * by `search_memory` in a later session, so a tool result that talks the
- * model into saving something reaches a future run's reasoning. A write
+ * model into saving something reaches a future turn's reasoning. A write
  * that survives the process is not read-only under any reading.
  */
 export const REVIEW_EXEMPT_WRITES: ReadonlySet<string> = new Set([
@@ -132,26 +133,81 @@ export function isReviewExempt(
 
 export type ReviewExemption = (name: string, input: unknown) => boolean
 
-/** Review explicit requests and calls that are destructive or not exempt. */
+/**
+ * Review explicit requests, escalated calls, and calls that are destructive
+ * or not exempt.
+ *
+ * An escalated call (`ToolCallSummary.escalation`) is reviewed even when its
+ * tool only reads: a read of a file outside the working directory is exactly
+ * the read the boundary was about, and "the tool is read-only" answers a
+ * different question.
+ */
 export function batchNeedsReview(
 	toolCalls: readonly ToolCallSummary[],
 	exempt: ReviewExemption,
 ): boolean {
 	return toolCalls.some(
-		(tc) => tc.authorization?.explicitReview || tc.isDestructive || !exempt(tc.name, tc.input),
+		(tc) =>
+			tc.authorization?.explicitReview ||
+			tc.escalation !== undefined ||
+			tc.isDestructive ||
+			!exempt(tc.name, tc.input),
 	)
 }
 
+/**
+ * Whether every call in a batch only reads, so that what brought it to review
+ * can only be a path outside the roots: no explicit review from a rule,
+ * nothing destructive, no sandbox escape, and a tool exempt from review.
+ */
+function onlyReadsOutsideRoots(
+	toolCalls: readonly ToolCallSummary[],
+	exempt: ReviewExemption,
+): boolean {
+	return toolCalls.every(
+		(tc) =>
+			!tc.authorization?.explicitReview &&
+			!tc.isDestructive &&
+			tc.escalation?.sandboxEscape !== true &&
+			exempt(tc.name, tc.input),
+	)
+}
+
+/**
+ * What the model is told when a batch asks to leave the sandbox and nobody
+ * can be asked.
+ *
+ * The whole batch is refused rather than the escape alone: the policy
+ * answers for the batch as a unit, and approving its other calls while the
+ * one that needed a person is dropped would run a plan with a hole in it.
+ */
+export const SANDBOX_ESCAPE_UNATTENDED_REFUSAL =
+	'Refused: a call in this batch asks to run outside the sandbox, which needs a person to confirm it each time, and nobody can be asked in this session. Nothing in this batch ran. Run the command inside the sandbox, or resend the other calls without the escape.'
+
+/**
+ * What the model is told when a batch reaches a path outside the turn's roots
+ * and nobody can be asked.
+ *
+ * Refused rather than approved by `auto`: the path is outside what the turn
+ * was given, and an approval of it is a person's, per call. A host with
+ * nobody to ask widens the roots up front instead (`additionalDirectories`,
+ * the CLI's `--add-dir`), where an operator wrote the directory down.
+ */
+export const OUTSIDE_ROOTS_UNATTENDED_REFUSAL =
+	"Refused: a call in this batch reaches a path outside the working directory and the added directories, which needs a person to approve it each time, and nobody can be asked in this session. Nothing in this batch ran. Stay inside the working directory, or tell the user which directory you need so they can add it to the session (the CLI's --add-dir)."
+
 /** The batch a person is asked about. */
 export interface ToolReviewRequest {
-	/** Originating run, preserved by createReviewHandler for host attribution. */
-	readonly runId?: RunId
+	/** Originating session, preserved by createReviewHandler for host attribution. */
+	readonly sessionId?: SessionId
+	/** Originating turn, preserved by createReviewHandler for host attribution. */
+	readonly turnId?: TurnId
 	readonly toolCalls: readonly ToolCallSummary[]
 }
 
 export type ToolReviewAnswer =
 	| { readonly kind: 'approve' }
-	/** Approve, and stop asking for the rest of the run. */
+	/** Approve, and stop asking for the rest of the turn. */
 	| { readonly kind: 'approve-all' }
 	| { readonly kind: 'reject'; readonly feedback?: string }
 
@@ -171,6 +227,17 @@ export interface ReviewPolicyOptions {
 	 * read the same fact; omitted, the policy keeps one privately.
 	 */
 	readonly remembered?: { all: boolean }
+	/**
+	 * What happens to a sandbox escape when there is no `prompt`.
+	 *
+	 * `'refuse'` (the default) refuses the batch: an escape is consented to by
+	 * a person, per call, and a turn with nobody to ask has no one to consent.
+	 * `'allow'` confirms it without asking, for an unattended host whose
+	 * operator decided in configuration that its commands may leave the
+	 * sandbox. With a `prompt` this is not consulted: the person is asked,
+	 * in every mode that does not refuse the call outright.
+	 */
+	readonly unattendedSandboxEscape?: 'refuse' | 'allow'
 }
 
 /** The handler behind `createReviewPolicy`, for a host that wants only the function. */
@@ -198,6 +265,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			request.toolCalls.every(
 				(tc) =>
 					!tc.authorization?.explicitReview &&
+					tc.escalation === undefined &&
 					!tc.isDestructive &&
 					(ACCEPT_EDITS_TOOLS.has(tc.name) || exempt(tc.name, tc.input)),
 			)
@@ -206,13 +274,73 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		}
 		// Ordinary reads were approved above. Remaining calls either change
 		// state or carry explicit review; plan mode does not grant that authority.
-		if (mode === 'plan') return { action: 'reject_tools', feedback: PLAN_MODE_REFUSAL }
+		// Except a batch of reads whose only reason to be here is a path outside
+		// the roots: plan mode is for reading, a read is what it tells the model
+		// to do, and the question such a path gets is the same in every mode that
+		// lets reads run. It goes on to that question below; `strict` still
+		// refuses it, since no rule can approve a path outside the roots.
+		if (mode === 'plan' && !onlyReadsOutsideRoots(request.toolCalls, exempt)) {
+			return { action: 'reject_tools', feedback: PLAN_MODE_REFUSAL }
+		}
 		if (mode === 'strict') return { action: 'reject_tools', feedback: STRICT_MODE_REFUSAL }
+		// A sandbox escape is asked about every time, in every mode that got
+		// this far — `auto` and a remembered "approve all" included, because
+		// both are answers somebody gave BEFORE this command existed. The
+		// kernel refuses an escape an approval does not name by id, so the
+		// ids below are the consent, and only a person (or an operator's
+		// explicit unattended setting) supplies them.
+		const escapes = request.toolCalls
+			.filter((tc) => tc.escalation?.sandboxEscape === true)
+			.map((tc) => tc.id)
+		if (escapes.length > 0) {
+			if (!prompt) {
+				return options.unattendedSandboxEscape === 'allow'
+					? { action: 'approve_tools', confirmedEscalations: escapes }
+					: { action: 'reject_tools', feedback: SANDBOX_ESCAPE_UNATTENDED_REFUSAL }
+			}
+			const answer = await prompt({
+				sessionId: request.sessionId,
+				turnId: request.turnId,
+				toolCalls: request.toolCalls,
+			})
+			if (answer.kind === 'reject') {
+				return {
+					action: 'reject_tools',
+					feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+				}
+			}
+			// "Approve all" still latches for the calls that follow; it never
+			// reaches the next escape, which is asked about above regardless.
+			if (answer.kind === 'approve-all') remembered.all = true
+			return { action: 'approve_tools', confirmedEscalations: escapes }
+		}
+		// A path outside the roots is a question for a person, every time,
+		// like an escape: `auto` and a remembered "approve all" were answers
+		// given about tools, before this path was named, and neither saw it.
+		// With nobody to ask it is refused, not approved.
+		if (request.toolCalls.some((tc) => (tc.escalation?.outsidePaths?.length ?? 0) > 0)) {
+			if (!prompt) return { action: 'reject_tools', feedback: OUTSIDE_ROOTS_UNATTENDED_REFUSAL }
+			const answer = await prompt({
+				sessionId: request.sessionId,
+				turnId: request.turnId,
+				toolCalls: request.toolCalls,
+			})
+			if (answer.kind === 'reject') {
+				return {
+					action: 'reject_tools',
+					feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+				}
+			}
+			// Latches for the ordinary calls that follow, never for the next path.
+			if (answer.kind === 'approve-all') remembered.all = true
+			return { action: 'approve_tools' }
+		}
 		if (mode === 'auto' || !prompt || remembered.all) {
 			return { action: 'approve_tools' }
 		}
 		const answer = await prompt({
-			runId: request.runId,
+			sessionId: request.sessionId,
+			turnId: request.turnId,
 			toolCalls: request.toolCalls,
 		})
 		switch (answer.kind) {
@@ -232,8 +360,8 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 
 /**
  * The mode as an `ApprovalPolicy`, named after itself so a durable log can
- * say which one approved a call. Swap it on a run's `RunApprovalPolicy`
- * to change mode without ending the run.
+ * say which one approved a call. Swap it on a turn's `SessionApprovalPolicy`
+ * to change mode without ending the turn.
  */
 export function createReviewPolicy(options: ReviewPolicyOptions = {}): ApprovalPolicy {
 	const mode: ReviewMode = options.mode ?? (options.prompt ? 'prompt' : 'auto')

package/src/runtime/query/sandbox-lifecycle.ts

@@ -2,7 +2,7 @@ import type { Sandbox, SandboxCreateConfig, SandboxProvider } from '../../types/
 
 const MAX_TIMER_DELAY_MS = 2_147_483_647
 
-/** A sandbox release gets thirty seconds before the run stops waiting for it. */
+/** A sandbox release gets thirty seconds before the turn stops waiting for it. */
 export const DEFAULT_SANDBOX_TEARDOWN_TIMEOUT_MS = 30_000
 
 export function resolveSandboxTeardownTimeoutMs(value: number | undefined): number {
@@ -55,10 +55,10 @@ function notifyLateTeardown(
 /**
  * Release a sandbox under a fresh owner.
  *
- * The run signal is deliberately not an input: cleanup normally begins because
+ * The turn signal is deliberately not an input: cleanup normally begins because
  * that signal is already aborted. A private signal gives the implementation a
  * chance to stop its transport at the teardown deadline, while the independent
- * race keeps a third-party implementation that ignores it from pinning the run.
+ * race keeps a third-party implementation that ignores it from pinning the turn.
  */
 export async function teardownSandbox(
 	sandbox: Sandbox,
@@ -97,7 +97,7 @@ export async function teardownSandbox(
 /**
  * Acquire a sandbox without allowing foreign setup to outlive run authority.
  *
- * Cancellation or the run timeout settles this function even when a provider
+ * Cancellation or the turn timeout settles this function even when a provider
  * ignores the signal.
  * A handle that arrives later is never published and is released exactly once.
  * This proves host/run liveness and cleanup of every handle the provider
@@ -109,7 +109,7 @@ export async function acquireSandbox(options: {
 	readonly provider: SandboxProvider
 	readonly config: Omit<SandboxCreateConfig, 'signal'>
 	readonly signal: AbortSignal
-	/** Remaining wall-clock owned by the run, not a second sandbox budget. */
+	/** Remaining wall-clock owned by the turn, not a second sandbox budget. */
 	readonly timeoutMs: number
 	readonly teardownTimeoutMs: number
 	readonly onLateTeardown?: (result: SandboxTeardownResult) => void

package/src/runtime/query/session-storage.ts

@@ -0,0 +1,302 @@
+import { readdir, realpath } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+import { resolveNamzuHome } from '../../session/home.js'
+import { type SessionLocator, SessionPaths, ensureProject } from '../../session/paths.js'
+import {
+	DiskSessionTokenBudgetStore,
+	InMemorySessionTokenBudgetStore,
+	type SessionTokenBudgetStore,
+} from '../../store/budget/index.js'
+import {
+	type CheckpointLogView,
+	type CheckpointScope,
+	DiskSessionCheckpointStore,
+	InMemorySessionCheckpointStore,
+	type SessionCheckpointStore,
+} from '../../store/checkpoint/index.js'
+import {
+	DiskSessionLog,
+	type InMemoryLogMedium,
+	InMemorySessionLog,
+	type SessionLog,
+} from '../../store/session-log/index.js'
+import type { ChildSessionStorage } from '../../types/agent/task.js'
+import type { CheckpointId, SessionId } from '../../types/ids/index.js'
+import { asSessionId, isEntityId } from '../../utils/id.js'
+
+/** What an in-memory session keeps beside its log. */
+interface HeldState {
+	readonly checkpoints: InMemorySessionCheckpointStore
+	readonly tokenBudgets: InMemorySessionTokenBudgetStore
+}
+
+/** Keyed by the log's bytes, so a reopened instance of one log finds the same stores. */
+const held = new WeakMap<InMemoryLogMedium, HeldState>()
+
+/** Where one session's log, checkpoints, ledger and child sessions go. */
+export interface SessionStorage {
+	readonly log: SessionLog
+	/** The project layout, when the session is on disk. */
+	readonly paths: SessionPaths | undefined
+	/** `<session-id>/`, beside the log, when the log is on disk. */
+	readonly sessionDir: string | undefined
+	readonly checkpoints: SessionCheckpointStore
+	/** Ledgers of root turns, keyed by (rootSessionId, rootTurnId). */
+	readonly tokenBudget: SessionTokenBudgetStore
+	/** What a delegated child session is told; `undefined` leaves it alone. */
+	readonly children: ChildSessionStorage | undefined
+}
+
+export interface SessionStorageInput {
+	readonly sessionId: SessionId
+	/** The delegating session, for a child session's default log location. */
+	readonly parentSessionId?: SessionId
+	readonly sessionLog?: SessionLog
+	readonly paths?: SessionPaths
+	readonly checkpointStore?: SessionCheckpointStore
+	readonly tokenBudgetStore?: SessionTokenBudgetStore
+	/** The directory the project slug is derived from when no `paths` is given. */
+	readonly workingDirectory?: string
+}
+
+/**
+ * The one answer to "where does this session's state live", read by every
+ * place that opens a session log, a checkpoint store or a token ledger.
+ *
+ * - **Log.** An explicit `sessionLog` wins. Otherwise the log at `paths`
+ *   (default: `SessionPaths` under `resolveNamzuHome()` for the working
+ *   directory's project).
+ * - **Checkpoints and ledger.** An explicit store wins. Otherwise a session
+ *   whose log is an {@link InMemorySessionLog} and which names no `paths`
+ *   keeps both in memory, beside its log; every other session keeps them on
+ *   disk under `<session-id>/checkpoints/` and `<root-session-id>/budgets/`.
+ * - **Children.** An in-memory session hands that choice to its delegated
+ *   children, so a child does not fall back to a disk tree its parent never
+ *   asked for; a session on disk hands down its layout, so its children's
+ *   logs nest under its session directory.
+ */
+export async function resolveSessionStorage(input: SessionStorageInput): Promise<SessionStorage> {
+	const inMemory = input.sessionLog instanceof InMemorySessionLog && input.paths === undefined
+	const paths =
+		input.paths ?? (inMemory ? undefined : await defaultSessionPaths(input.workingDirectory))
+	// A disk log in this layout knows its place from its path. Any other log
+	// is placed like a session named without a log, under its parent wherever
+	// that is, so its checkpoints never land at the top: that includes a log
+	// kept outside the layout whose file name alone reads as a place in one.
+	const locator = paths
+		? ((await placeInLayout(paths, input.sessionLog)) ??
+			(await locateSession(paths, input.sessionId, input.parentSessionId)))
+		: undefined
+	const log =
+		input.sessionLog ?? DiskSessionLog.at(paths as SessionPaths, locator as SessionLocator)
+	const state = inMemory ? heldState(log as InMemorySessionLog) : undefined
+	const checkpoints =
+		input.checkpointStore ??
+		state?.checkpoints ??
+		new DiskSessionCheckpointStore({
+			paths: paths as SessionPaths,
+			log: checkpointLogView(log),
+			...(locator ? { session: locator } : {}),
+		})
+	const tokenBudget =
+		input.tokenBudgetStore ??
+		state?.tokenBudgets ??
+		new DiskSessionTokenBudgetStore({ paths: paths as SessionPaths })
+	const children: ChildSessionStorage | undefined = inMemory
+		? {
+				kind: 'memory',
+				...(input.checkpointStore ? { checkpointStore: input.checkpointStore } : {}),
+			}
+		: paths
+			? { kind: 'disk', paths }
+			: undefined
+	const sessionDir = log instanceof DiskSessionLog ? log.sessionDir : undefined
+	return { log, paths, sessionDir, checkpoints, tokenBudget, children }
+}
+
+/**
+ * Where `log` sits in `paths`'s layout, read from its path: its locator, only
+ * when that locator's log in this layout is the very file it writes.
+ * `sessionLocatorFromLogFile` reads any `<id>.jsonl` as a place, because a log
+ * does not know which project it belongs to; a file outside this project (or
+ * one named for a place it is not at) is `undefined` here.
+ */
+async function placeInLayout(
+	paths: SessionPaths,
+	log: SessionLog | undefined,
+): Promise<SessionLocator | undefined> {
+	if (!(log instanceof DiskSessionLog) || !log.locator) return undefined
+	// Canonical, not lexical. `NAMZU_HOME` reached through a symlinked home
+	// (`/home/me -> /data/me`) and a log opened by its real path name the same
+	// file with two spellings; comparing them with `resolve()` read that as a
+	// log outside the layout and placed a child's checkpoints under its parent
+	// a second time, beside the ones its own log already points at.
+	const [expected, actual] = await Promise.all([
+		canonicalPath(paths.sessionLog(log.locator)),
+		canonicalPath(log.file),
+	])
+	return expected === actual ? log.locator : undefined
+}
+
+/**
+ * `path` with every symlink in its existing prefix resolved. A log is often
+ * placed before its first append, so the file (and even its session
+ * directory) may not exist yet: the deepest ancestor that does is
+ * canonicalized and the rest appended lexically, which cannot hide a link
+ * because nothing is there to be one. Falls back to `resolve()` when nothing
+ * on the path exists at all.
+ */
+async function canonicalPath(path: string): Promise<string> {
+	let existing = resolve(path)
+	let remainder = ''
+	for (;;) {
+		const found = await realpath(existing).catch(() => undefined)
+		if (found !== undefined) return remainder ? join(found, remainder) : found
+		const parent = dirname(existing)
+		if (parent === existing) return resolve(path)
+		remainder = remainder ? join(basename(existing), remainder) : basename(existing)
+		existing = parent
+	}
+}
+
+/**
+ * The locator of a session named without its log: a root session sits at the
+ * top of the project; a child session sits under its parent, wherever the
+ * parent is. The parent's own place is found on disk, so a grandchild nests
+ * under every ancestor and not beside its parent at the top level. A parent
+ * with no log in the layout yet is taken to be a root session.
+ */
+export async function locateSession(
+	paths: SessionPaths,
+	sessionId: SessionId,
+	parentSessionId?: SessionId,
+): Promise<SessionLocator> {
+	if (!parentSessionId) return { sessionId }
+	const parent = (await findSessionLocator(paths, parentSessionId)) ?? {
+		sessionId: parentSessionId,
+	}
+	return { sessionId, ancestors: [...(parent.ancestors ?? []), parent.sessionId] }
+}
+
+/** Deeper than any delegation tree a project allows; a guard against a cyclic tree on disk. */
+const MAX_SEARCH_DEPTH = 64
+
+/**
+ * Where `sessionId`'s log is in the project's layout: at the top level, or in
+ * some session's `subagents/`, searched breadth first. `undefined` when no log
+ * of that session exists.
+ */
+async function findSessionLocator(
+	paths: SessionPaths,
+	sessionId: SessionId,
+): Promise<SessionLocator | undefined> {
+	const target = `${sessionId}.jsonl`
+	let frontier: SessionLocator[] = []
+	const top = await listDirectory(paths.projectDir())
+	if (top.files.has(target)) return { sessionId }
+	for (const name of top.directories) {
+		if (isEntityId(name, 'session')) frontier.push({ sessionId: asSessionId(name) })
+	}
+	for (let depth = 0; depth < MAX_SEARCH_DEPTH && frontier.length > 0; depth++) {
+		const next: SessionLocator[] = []
+		for (const parent of frontier) {
+			const children = await listDirectory(join(paths.sessionDir(parent), 'subagents'))
+			const ancestors = [...(parent.ancestors ?? []), parent.sessionId]
+			if (children.files.has(target)) return { sessionId, ancestors }
+			for (const name of children.directories) {
+				if (isEntityId(name, 'session')) next.push({ sessionId: asSessionId(name), ancestors })
+			}
+		}
+		frontier = next
+	}
+	return undefined
+}
+
+async function listDirectory(
+	directory: string,
+): Promise<{ files: Set<string>; directories: string[] }> {
+	try {
+		const entries = await readdir(directory, { withFileTypes: true })
+		return {
+			files: new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name)),
+			directories: entries
+				.filter((entry) => entry.isDirectory())
+				.map((entry) => entry.name)
+				.sort(),
+		}
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code
+		if (code === 'ENOENT' || code === 'ENOTDIR') return { files: new Set(), directories: [] }
+		throw error
+	}
+}
+
+/** `SessionPaths` for the working directory's project under `resolveNamzuHome()`. */
+export async function defaultSessionPaths(workingDirectory?: string): Promise<SessionPaths> {
+	const home = resolveNamzuHome()
+	const project = await ensureProject({ home, cwd: workingDirectory ?? process.cwd() })
+	return new SessionPaths({ home, slug: project.slug })
+}
+
+function heldState(log: InMemorySessionLog): HeldState {
+	const current = held.get(log.medium)
+	if (current) return current
+	const next: HeldState = {
+		checkpoints: new InMemorySessionCheckpointStore({ log: checkpointLogView(log) }),
+		tokenBudgets: new InMemorySessionTokenBudgetStore(),
+	}
+	held.set(log.medium, next)
+	return next
+}
+
+/**
+ * @internal What an in-memory session holds beside its log right now, for
+ * tests that assert where its state went.
+ */
+export function heldSessionState(log: InMemorySessionLog): HeldState | undefined {
+	return held.get(log.medium)
+}
+
+/**
+ * The checkpoint store's view of one session log: whether a checkpoint was
+ * committed, whether the prefix it covers is intact, and which checkpoints
+ * an open decision still references.
+ */
+export function checkpointLogView(log: SessionLog): CheckpointLogView {
+	const own = (scope: CheckpointScope): void => {
+		if (scope.sessionId !== log.sessionId) {
+			throw new Error(
+				`This checkpoint store answers for session ${log.sessionId}, not ${scope.sessionId}.`,
+			)
+		}
+	}
+	return {
+		async verifyThrough(scope, throughSeq, throughSha256) {
+			own(scope)
+			const read = await log.readAll({ mode: 'tolerant', throughSeq })
+			const entry = read.entries.at(-1)
+			return entry?.pointer.seq === throughSeq && entry.pointer.sha256 === throughSha256
+		},
+		async writtenDocSha256(scope, checkpointId) {
+			own(scope)
+			let found: string | null = null
+			for await (const { record } of log.read({ mode: 'tolerant' })) {
+				if (record.type === 'checkpoint_written' && record.checkpointId === checkpointId) {
+					found = record.docSha256
+				}
+			}
+			return found
+		},
+		async openDecisionCheckpoints(scope) {
+			own(scope)
+			const open = new Map<string, CheckpointId>()
+			for await (const { record } of log.read({ mode: 'tolerant' })) {
+				if (record.type === 'decision_requested') open.set(record.decisionId, record.checkpointId)
+				if (record.type === 'decision_resolved' || record.type === 'decision_expired') {
+					open.delete(record.decisionId)
+				}
+			}
+			return open.values()
+		},
+	}
+}

package/src/runtime/query/steering.ts

@@ -17,9 +17,9 @@ export function isOperatorUserMessage(message: Message): message is UserMessage
  * The gap this closes is narrow and was documented rather than fixed:
  * `AgentManager` has had `queueMessage` / `drainMessages` for a while, and
  * nothing in the iteration loop ever read them — the type says so in as many
- * words. So a host watching a run go the wrong way had two options, and both
+ * words. So a host watching a turn go the wrong way had two options, and both
  * are worse than they sound. Cancel and start over throws away every tool
- * result the run had already paid for. Reject through the review gate only
+ * result the turn had already paid for. Reject through the review gate only
  * works if a tool call happens to be pending approval, and it says "no" when
  * the host wanted to say "yes, but look at this first".
  *
@@ -90,7 +90,7 @@ export class SteeringBinding implements SteeringChannel {
  * as something the tool said — so a steer saying "stop and ask me first" would
  * look like output from `bash`.
  *
- * This is NOT the untrusted-content envelope. The host operating the run is
+ * This is NOT the untrusted-content envelope. The host operating the turn is
  * the one party whose words the agent SHOULD act on; framing them as material
  * to be worked with rather than followed would inverting the very thing the
  * host is trying to do. Different party, different frame, on purpose.
@@ -138,8 +138,21 @@ export function formatJobNote(text: string): string {
 	return `\n\n[Background job update]\n${text}`
 }
 
+const STEERING_NOTE_HEADER =
+	'\n\n[Message from the operator, received while this tool was running]\n'
+
 export function formatSteeringNote(text: string): string {
-	return `\n\n[Message from the operator, received while this tool was running]\n${text}`
+	return `${STEERING_NOTE_HEADER}${text}`
+}
+
+/**
+ * The operator guidance the last steering note in a tool result carries, or
+ * `undefined` when the result carries none. The inverse of
+ * {@link formatSteeringNote} applied by {@link attachSteering}.
+ */
+export function readSteeringNote(content: string): string | undefined {
+	const at = content.lastIndexOf(STEERING_NOTE_HEADER)
+	return at < 0 ? undefined : content.slice(at + STEERING_NOTE_HEADER.length)
 }
 
 /**