@namzu/sdk 38.2.1 → 40.0.0

package/src/tools/builtins/read-render.ts

@@ -0,0 +1,104 @@
+/**
+ * How `read` turns a file's body into the text the model sees.
+ *
+ * Pulled out of the tool for the reason `edit-apply` was: a second caller —
+ * the resume seed, deciding whether a `read` receipt in history shows exactly
+ * the body it already believes the file had — has to produce byte-for-byte
+ * what the tool produced, and a parallel implementation of the numbering or
+ * the window arithmetic would silently stop agreeing with it.
+ *
+ * Pure by construction: no filesystem access, no `ToolContext`.
+ */
+
+/**
+ * Lines returned when the caller specifies no window.
+ *
+ * Chosen to cover the overwhelming majority of source files whole while
+ * bounding the pathological case.
+ */
+export const DEFAULT_READ_LINES = 2000
+
+/** The window fields of `read`'s input; the path plays no part in rendering. */
+export interface ReadWindowRequest {
+	/**
+	 * `[start, end]`, 1-indexed inclusive.
+	 *
+	 * Typed as a number array rather than a pair because the tool's schema
+	 * pins the length at two with `.length(2)` instead of a `z.tuple` — a
+	 * tuple renders as draft-07 `items: [a, b]`, which a 2020-12 wire refuses.
+	 * The parse still rejects any other length, so a caller reaching here has
+	 * two numbers; `resolveReadWindow` reads them defensively anyway, because
+	 * this interface is also implemented by hand elsewhere in the kernel.
+	 */
+	readonly readRange?: readonly number[]
+	readonly offset?: number
+	readonly limit?: number
+}
+
+export interface RenderedRead {
+	/** Exactly what `read` returns as its output for this body and window. */
+	readonly output: string
+	readonly totalLines: number
+	readonly returnedLines: number
+	/** Whether the window left any of the file out, which is what adds the notice. */
+	readonly partial: boolean
+}
+
+/**
+ * Render `content` the way `read` renders it.
+ *
+ * The numbering is what makes this reversible enough to compare against: every
+ * line goes out behind its own `${n}\t`, so two different bodies cannot render
+ * to one string, and the partial-view notice below — whose lines carry no such
+ * prefix — cannot be mistaken for part of a body.
+ */
+export function renderNumberedRead(content: string, input: ReadWindowRequest): RenderedRead {
+	const lines = content.split('\n')
+	const { start, end } = resolveReadWindow(input, lines.length)
+	const selected = lines.slice(start, end)
+	const numbered = selected.map((line, i) => `${start + i + 1}\t${line}`).join('\n')
+	return {
+		output: numbered + partialViewNotice(start, selected.length, lines.length),
+		totalLines: lines.length,
+		returnedLines: selected.length,
+		partial: selected.length < lines.length,
+	}
+}
+
+/**
+ * Tell the model, explicitly, when it is looking at a window rather than
+ * the file.
+ *
+ * Without this a truncated read is indistinguishable from a short file, and
+ * the agent reasons about a fragment as if it were the whole thing — the
+ * most expensive silent failure a read tool can have. The notice names the
+ * exact next call rather than describing it.
+ */
+function partialViewNotice(start: number, returned: number, total: number): string {
+	if (returned >= total) return ''
+	const shownTo = start + returned
+	return [
+		'',
+		'',
+		`[PARTIAL view — lines ${start + 1}-${shownTo} of ${total}.`,
+		`Continue with read({ offset: ${shownTo}, limit: N }), or narrow with grep.]`,
+	].join('\n')
+}
+
+export function resolveReadWindow(
+	input: ReadWindowRequest,
+	totalLines: number,
+): { start: number; end: number } {
+	const [first, last] = input.readRange ?? []
+	if (first !== undefined && last !== undefined) {
+		const start = Math.max(0, first - 1)
+		const end = Math.min(totalLines, Math.max(start, last))
+		return { start, end }
+	}
+	const start = Math.max(0, input.offset ?? 0)
+	// A bare `read({ path })` used to return the entire file, so a 2 MB
+	// lockfile became ~500k tokens in one tool_result. Default to a window
+	// and say so in the output; the model asks for more when it needs it.
+	const end = input.limit ? start + input.limit : Math.min(totalLines, start + DEFAULT_READ_LINES)
+	return { start, end }
+}

package/src/tools/builtins/wait-for-job-bounds.ts

@@ -0,0 +1,179 @@
+import type { BackgroundJobRegistryRef } from '../../types/tool/index.js'
+
+/**
+ * Waiting on a background job, bounded by two different questions — the
+ * shell-job counterpart to `waitForTaskWithBounds`
+ * (`../coordinator/wait-with-idle-bound.ts`), which this mirrors.
+ *
+ * A delegated agent task reports its own progress through
+ * `TaskScheduler.onTaskProgress`. A shell job has no such channel: the only
+ * signal it ever produces is bytes on stdout/stderr. So where the task
+ * version resets its idle clock on a progress EVENT, this one resets it on
+ * OBSERVED OUTPUT GROWTH — read on every tick, compared against the last
+ * tick's offset. A tick that finds nothing new is not progress; treating it
+ * as progress would make the idle bound unable to fire for a wedged job at
+ * all, which is the exact failure this exists to catch.
+ *
+ *  - the **run bound** counts elapsed time and is never refreshed. It
+ *    exists for a job that stays busy forever (a server, a stuck build).
+ *  - the **idle bound** counts time since output last grew, and resets
+ *    whenever it does. It exists for a job that stopped producing anything
+ *    without exiting.
+ *
+ * Neither bound cancels the job. A wait that ran out is a statement about
+ * the WAITER, not the work — the job keeps running, and its output is still
+ * there to read with `job` or a later `wait_for_job` call.
+ */
+export interface JobWaitOptions {
+	/** Elapsed-time ceiling, never refreshed. */
+	readonly runMs: number
+	/**
+	 * Time-without-new-output ceiling, refreshed whenever `read` returns
+	 * more than it did last tick. Omit to bound by the run clock alone.
+	 */
+	readonly idleMs?: number
+	/** Resume from here rather than the start of what the job has retained. */
+	readonly fromOffset?: number
+	/** Stop preempts a wait that has not resolved yet; the job is untouched. */
+	readonly signal?: AbortSignal
+}
+
+interface JobWaitProgress {
+	readonly output: string
+	readonly nextOffset: number
+	readonly droppedBytes: number
+}
+
+export type JobWaitOutcome =
+	| ({
+			readonly kind: 'exited'
+			readonly status: string
+			readonly exitCode?: number
+	  } & JobWaitProgress)
+	| ({
+			readonly kind: 'timeout'
+			/** Which clock ran out. */
+			readonly cause: 'idle' | 'run'
+			readonly elapsedMs: number
+	  } & JobWaitProgress)
+
+/**
+ * How often the bounds are checked, and how often output is drained.
+ *
+ * Coarse on purpose, same reasoning as the task version's own interval:
+ * both bounds are measured in minutes, so a second of latency noticing
+ * either one is irrelevant, and this is an internal timer, not a model
+ * turn — it costs nothing external no matter how often it fires.
+ */
+const POLL_INTERVAL_MS = 1_000
+
+/**
+ * Await a job under both bounds, accumulating its output as it goes.
+ *
+ * Returns the output gathered so far either way: a completed wait has all
+ * of it, and a timed-out one has everything read up to the moment it gave
+ * up, so the caller never has to throw away a partial answer.
+ */
+export async function waitForJobWithBounds(
+	jobs: Pick<BackgroundJobRegistryRef, 'read' | 'waitForExit'>,
+	id: string,
+	options: JobWaitOptions,
+	now: () => number = Date.now,
+): Promise<JobWaitOutcome> {
+	if (!jobs.waitForExit) {
+		throw new Error('This background job registry cannot wait for a job to exit.')
+	}
+	const waitForExit = jobs.waitForExit.bind(jobs)
+
+	const startedAt = now()
+	let lastProgressAt = startedAt
+	let cursor = options.fromOffset ?? 0
+	let output = ''
+	let droppedBytes = 0
+	let settled = false
+
+	/** Read whatever is new since `cursor`, and count it as progress if it is. */
+	const drain = (): void => {
+		const chunk = jobs.read(id, { fromOffset: cursor })
+		if (chunk.droppedBytes > 0) droppedBytes += chunk.droppedBytes
+		if (chunk.nextOffset > cursor) lastProgressAt = now()
+		cursor = chunk.nextOffset
+		if (chunk.chunk) output += chunk.chunk
+	}
+
+	try {
+		const exited = waitForExit(id, { signal: options.signal }).then((job): JobWaitOutcome => {
+			// One last read: the job can exit between ticks, and the bytes
+			// it wrote in its final moment are exactly the ones a caller
+			// most wants — the error, the summary line, the exit trace.
+			drain()
+			return {
+				kind: 'exited',
+				status: job.status,
+				...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }),
+				output,
+				nextOffset: cursor,
+				droppedBytes,
+			}
+		})
+
+		const expiry = new Promise<JobWaitOutcome>((resolve) => {
+			// Polled rather than scheduled, for the same reason the task
+			// version is: the idle deadline MOVES on every byte of new
+			// output, and a timer armed for it would have to be cleared and
+			// rearmed on every tick that mattered.
+			const tick = setInterval(() => {
+				if (settled) return
+				drain()
+				const elapsed = now() - startedAt
+				if (elapsed >= options.runMs) {
+					clearInterval(tick)
+					resolve({
+						kind: 'timeout',
+						cause: 'run',
+						elapsedMs: elapsed,
+						output,
+						nextOffset: cursor,
+						droppedBytes,
+					})
+					return
+				}
+				if (options.idleMs !== undefined) {
+					const quietFor = now() - lastProgressAt
+					if (quietFor >= options.idleMs) {
+						clearInterval(tick)
+						resolve({
+							kind: 'timeout',
+							cause: 'idle',
+							elapsedMs: elapsed,
+							output,
+							nextOffset: cursor,
+							droppedBytes,
+						})
+					}
+				}
+			}, POLL_INTERVAL_MS)
+			// Never the reason a process stays alive — this races a real
+			// exit promise, so the wait is held open by work that is
+			// genuinely outstanding rather than by this timer.
+			;(tick as { unref?: () => void }).unref?.()
+		})
+
+		return await Promise.race([exited, expiry])
+	} finally {
+		settled = true
+	}
+}
+
+/** What to tell the model, in the words that fit what actually happened. */
+export function describeJobWaitTimeout(
+	id: string,
+	outcome: Extract<JobWaitOutcome, { kind: 'timeout' }>,
+): string {
+	const seconds = Math.round(outcome.elapsedMs / 1000)
+	const resume = `call wait_for_job again, or job read with from_offset ${outcome.nextOffset}, to see what it does next`
+	if (outcome.cause === 'idle') {
+		return `Job ${id} went quiet: no new output for a while, after ${seconds}s. It has not been stopped and may still be working — ${resume}.`
+	}
+	return `Job ${id} has been running for ${seconds}s without finishing. It has not been stopped — ${resume}.`
+}

package/src/tools/builtins/wait-for-job.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod'
+
+import { readPositiveIntEnv } from '../../utils/env.js'
+import { defineTool } from '../defineTool.js'
+import { describeJobWaitTimeout, waitForJobWithBounds } from './wait-for-job-bounds.js'
+
+/**
+ * Block until a background job ends, instead of reading it in a loop.
+ *
+ * `job`'s own tool used to say, in as many words, "poll a job with action
+ * read" — and a model that took the instruction literally paid for it: one
+ * recorded run launched a single background job, then spent six `job read`
+ * calls, three `job list` calls and an improvised `sleep 30` waiting on it,
+ * burning more tokens on the wait than the work it was waiting for cost.
+ * `wait_for_task` already solved this for delegated agent work by blocking
+ * inside ONE tool call instead of asking the model to check back; this is
+ * the same fix for shell jobs, built the same way — see
+ * `wait-for-job-bounds.ts` and its task-surface counterpart.
+ */
+
+const DEFAULT_TIMEOUT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_TIMEOUT_MS', 5 * 60 * 1000)
+const DEFAULT_IDLE_TIMEOUT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_IDLE_MS', 2 * 60 * 1000)
+
+/**
+ * The longest either bound will accept from the model.
+ *
+ * Same number `wait_for_task` uses for a delegated agent, and the same
+ * reasoning applies: a generic stopwatch is the wrong instrument for a job
+ * that is making progress, so this is "how long is too long" rather than a
+ * guess at any one job's real duration, and a request past it is REFUSED by
+ * the schema rather than silently clamped — see `bash`'s own `timeout` field
+ * for the same trade.
+ */
+const MAX_WAIT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_MAX_MS', 60 * 60 * 1000)
+
+const inputSchema = z.object({
+	id: z.string().describe('The job id, as returned by bash with run_in_background.'),
+	timeout_ms: z
+		.number()
+		.int()
+		.positive()
+		.max(MAX_WAIT_MS)
+		.optional()
+		.describe(
+			`Give up after this long even if the job keeps producing output, in milliseconds. Default: ${DEFAULT_TIMEOUT_MS}, maximum: ${MAX_WAIT_MS}. The job is never stopped by this running out.`,
+		),
+	idle_timeout_ms: z
+		.number()
+		.int()
+		.positive()
+		.max(MAX_WAIT_MS)
+		.optional()
+		.describe(
+			`Give up if the job produces no new output for this long, in milliseconds. Default: ${DEFAULT_IDLE_TIMEOUT_MS}. Resets on every new byte of output, so a job that is still working is not cut off; only real silence ends the wait early.`,
+		),
+})
+
+type WaitForJobInput = z.infer<typeof inputSchema>
+
+export const WaitForJobTool = defineTool({
+	name: 'wait_for_job',
+	description:
+		'Block until a background job started by bash with run_in_background ends, and return its accumulated output in one call. Use this instead of calling job with action "read" in a loop: it costs one call and no waiting turns. Gives up — WITHOUT stopping the job — if it runs too long or goes quiet for too long; either outcome says so, and the job keeps running either way.',
+	inputSchema,
+	category: 'shell',
+	permissions: ['shell_execute'],
+	// Waiting is watching, not acting: this tool only ever reads a job's
+	// output and status through the same registry `job read` uses, and has
+	// no branch that touches a job's lifetime. `wait_for_task` is `readOnly:
+	// true` for the identical reason, and unlike `job` there is no second
+	// action here that would make this a function of input.
+	readOnly: true,
+	destructive: false,
+	concurrencySafe: true,
+	// A tool whose whole purpose is to wait must not be cut off for waiting.
+	// A margin over MAX_WAIT_MS so the tool's own bound — which reports a
+	// clean timeout result — always fires before the executor's harsher
+	// "abandoned" one would.
+	timeoutMs: MAX_WAIT_MS + 30_000,
+
+	presentCall(input) {
+		return {
+			kind: 'generic',
+			presentation: 'activity',
+			label: `Wait for background job · ${input.id ?? '(missing id)'}`,
+		}
+	},
+
+	async execute(input: WaitForJobInput, context) {
+		if (!context.backgroundJobs) {
+			return {
+				success: false,
+				output: '',
+				error: 'This host provides no background job registry, so there is no job to wait for.',
+			}
+		}
+		const jobs = context.backgroundJobs
+
+		try {
+			jobs.get(input.id)
+		} catch (err) {
+			return {
+				success: false,
+				output: '',
+				error: err instanceof Error ? err.message : String(err),
+			}
+		}
+
+		if (!jobs.waitForExit) {
+			return {
+				success: false,
+				output: '',
+				error:
+					'This host\'s background job registry cannot wait for a job to exit. Use job with action "read" instead.',
+			}
+		}
+
+		// The wait IS the intent, so it is recorded before the bounds are: a
+		// call that gives up at `timeout_ms` with the job still running is the
+		// case the kernel's hold exists to back up, and one that started the
+		// wait and then ended its turn is the same case a beat later. Nothing
+		// infers this from the job's existence — a dev server the model never
+		// waited on never holds a run open. See `runtime/jobs/awaited-jobs.ts`.
+		jobs.markAwaited?.(input.id)
+
+		let outcome: Awaited<ReturnType<typeof waitForJobWithBounds>>
+		try {
+			outcome = await waitForJobWithBounds(jobs, input.id, {
+				runMs: input.timeout_ms ?? DEFAULT_TIMEOUT_MS,
+				idleMs: input.idle_timeout_ms ?? DEFAULT_IDLE_TIMEOUT_MS,
+				signal: context.abortSignal,
+			})
+		} catch {
+			// The signal fired before either bound did — Stop, or the run's
+			// own deadline. The job is untouched: ending a WAIT is not
+			// ending the WORK. The executor has already raced this same
+			// signal against the whole call and reports the cancellation
+			// itself; this only keeps that rejection from reaching the
+			// model as an unlabelled tool failure.
+			return {
+				success: false,
+				output: `This wait for job ${input.id} was abandoned before it finished; it is still running and was not stopped. Call wait_for_job again, or job read with from_offset, to pick up where this left off.`,
+				data: { jobId: input.id, abandoned: true },
+			}
+		}
+
+		if (outcome.kind === 'timeout') {
+			return {
+				success: false,
+				output: describeJobWaitTimeout(input.id, outcome),
+				data: {
+					jobId: input.id,
+					timedOut: outcome.cause,
+					nextOffset: outcome.nextOffset,
+					droppedBytes: outcome.droppedBytes,
+				},
+			}
+		}
+
+		// The dropped count is stated, never absorbed — same rule `job read`
+		// follows, for the same reason: a job whose middle vanished quietly
+		// reads as a complete result that happens to be short.
+		const notice =
+			outcome.droppedBytes > 0
+				? `[${outcome.droppedBytes} bytes were dropped before this point — the job produced output faster than the retention cap holds]\n`
+				: ''
+		const status =
+			outcome.exitCode === undefined
+				? outcome.status
+				: `${outcome.status} with code ${outcome.exitCode}`
+
+		return {
+			success: true,
+			output: `${notice}${outcome.output || '(no output)'}\n\n[job ${input.id} is ${status}; next_offset ${outcome.nextOffset}]`,
+			data: {
+				jobId: input.id,
+				status: outcome.status,
+				nextOffset: outcome.nextOffset,
+				droppedBytes: outcome.droppedBytes,
+				...(outcome.exitCode === undefined ? {} : { exitCode: outcome.exitCode }),
+			},
+		}
+	},
+})

package/src/tools/builtins/write-file.ts

@@ -150,7 +150,7 @@ export const WriteFileTool = defineTool({
 				// This write is now the runtime's newest observation. Recording only
 				// the boolean would leave an older content fingerprint in place and
 				// make the next same-run write refuse its own predecessor as drift.
-				context.fileReadTracker?.recordRead(valid.path, content)
+				context.fileReadTracker?.recordRead(valid.path, content, context.toolUseId)
 				return fileWriteResult(
 					valid.path,
 					current === null ? null : current?.toString('utf-8'),
@@ -171,7 +171,7 @@ export const WriteFileTool = defineTool({
 			// leaves the destination truncated — and this tool overwrites a
 			// whole file, so the truncation is the user's previous work.
 			await atomicWriteFile(hostPath, content)
-			context.fileReadTracker?.recordRead(hostPath, content)
+			context.fileReadTracker?.recordRead(hostPath, content, context.toolUseId)
 
 			return fileWriteResult(hostPath, current, content)
 		})
@@ -204,6 +204,11 @@ function enforceFreshOverwrite(
 	// fingerprint the host never promised to capture.
 	const observed = context.fileReadTracker?.fingerprint?.(key)
 	if (observed !== undefined && observed !== fingerprintContent(currentContent)) {
+		// The disk has just been read and found moved. Say so — without saying
+		// what was found, which would re-baseline the comparison right above —
+		// so a reader that cannot touch the filesystem stops referencing this
+		// path. Optional on the interface; an older tracker keeps its behavior.
+		context.fileReadTracker?.recordDriftObserved?.(key)
 		return { success: false, output: '', error: staleFileError(key, 'write') }
 	}
 	return null

package/src/tools/coordinator/index.ts

@@ -8,6 +8,7 @@ import type { ResumeHandler } from '../../types/hitl/index.js'
 import type { RunId, TaskId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
+import { readPositiveIntEnv } from '../../utils/env.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { asTaskId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
@@ -374,13 +375,6 @@ export const DELEGATION_TIMEOUT_MS = 60 * 60 * 1000
  */
 export const DELEGATION_IDLE_MS = readPositiveIntEnv('NAMZU_DELEGATION_IDLE_MS', 5 * 60 * 1000)
 
-function readPositiveIntEnv(key: string, fallback: number): number {
-	const value = process.env[key]?.trim()
-	if (!value) return fallback
-	const parsed = Number(value)
-	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
-}
-
 /**
  * The answer a delegated child produced, as the string a parent model reads.
  *

package/src/tools/defineTool.ts

@@ -17,7 +17,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	validationErrorHint?: string
 	category: ToolDefinition['category']
 	permissions: ToolPermission[]
-	readOnly: boolean
+	/** Whether this exact call only observes state; conservative for unknown inputs. */
+	readOnly: boolean | ((input: z.infer<S>) => boolean)
 	destructive: boolean | ((input: z.infer<S>) => boolean)
 	concurrencySafe: boolean
 	/** Batch ordering boundary; see {@link ToolDefinition.executionBarrier}. */
@@ -88,7 +89,8 @@ export function defineTool<S extends z.ZodType>(
 			: {}),
 		category: options.category,
 		permissions: options.permissions,
-		isReadOnly: () => options.readOnly,
+		isReadOnly:
+			typeof options.readOnly === 'function' ? options.readOnly : () => options.readOnly as boolean,
 		isDestructive:
 			typeof options.destructive === 'function'
 				? options.destructive

package/src/tools/file-read-tracker.ts

@@ -5,12 +5,96 @@ import { fingerprintContent } from './builtins/content-fingerprint.js'
 export function createFileReadTracker(): FileReadTracker {
 	const paths = new Set<string>()
 	const fingerprints = new Map<string, string>()
+	const writes = new Map<string, string>()
+	// Edits stacked on top of `writes.get(key)`, in order. Kept beside the
+	// write id rather than replacing it, because the write is the base a
+	// replay starts from and is still needed once edits sit on it — while
+	// `writeCallId` must stop reporting it the moment the file's body stops
+	// being that call's body.
+	const chains = new Map<string, string[]>()
+	// Reads whose receipt still holds the whole body, with the fingerprint of
+	// the rendering that receipt is supposed to be. Kept apart from `writes`
+	// rather than folded into it: a write's body is the model's own argument
+	// and an edit can be replayed onto it, while this one exists only as text
+	// formatted for a reader — so it roots nothing, and the rendering is the
+	// only thing anyone is allowed to check it against.
+	const reads = new Map<string, { callId: string; renderedFingerprint: string }>()
+	// Paths a built-in mutation refused for drift. A flag and not an
+	// observation: the refusing tool did read the disk, but it reported only
+	// that what it found differs — writing a fingerprint from it would
+	// re-baseline the very check that refused and let the next mutation
+	// through. So this touches nothing `fingerprint`, `hasRead`, `writeCallId`,
+	// `editChain` or `readWitness` answers; it says only that what this ledger
+	// holds for the path is known to be behind the disk.
+	const drifted = new Set<string>()
+	// One observation, whatever witness the caller goes on to record against it.
+	// A shared function rather than `this.recordRead`, so a destructured method
+	// keeps working.
+	function observe(key: string, content?: string, fullWriteCallId?: string): void {
+		paths.add(key)
+		drifted.delete(key)
+		const next = content === undefined ? undefined : fingerprintContent(content)
+		if (next === undefined || next !== fingerprints.get(key)) {
+			writes.delete(key)
+			chains.delete(key)
+			reads.delete(key)
+		}
+		if (next !== undefined) fingerprints.set(key, next)
+		else fingerprints.delete(key)
+		if (next !== undefined && fullWriteCallId) {
+			writes.set(key, fullWriteCallId)
+			// A full body arrived whole in one call, so the chain is empty
+			// again: nothing has been applied on top of what is now on disk.
+			chains.delete(key)
+		}
+	}
 	return {
-		recordRead(key, content) {
+		recordRead: observe,
+		recordFullRead(key, content, callId, renderedFingerprint) {
+			observe(key, content)
+			// A surviving write witness outranks this one: it names a body the
+			// model composed itself, and the chain machinery can replay onto it.
+			// This is the same observation either way — only the witness differs.
+			if (!writes.has(key)) reads.set(key, { callId, renderedFingerprint })
+		},
+		readWitness: (key) => reads.get(key),
+		recordEdit(key, content, callId) {
+			// Both conditions are about the PRE-image, not this edit. A chain
+			// replays only if the content this edit ran against is itself
+			// reproducible: there has to be a witnessed write underneath it, and
+			// a fingerprint for what the edit actually started from — which is
+			// also the value the tool's own drift check compared before writing.
+			// Without both, this is an observation of a body nobody can replay.
+			const chained = writes.has(key) && fingerprints.has(key) && callId.length > 0
 			paths.add(key)
-			if (content !== undefined) fingerprints.set(key, fingerprintContent(content))
+			drifted.delete(key)
+			// Unconditionally, even where the content is unchanged: a read
+			// witness points at a receipt showing the body BEFORE this edit, and
+			// no chain can be rooted at a rendering to carry it forward.
+			reads.delete(key)
+			fingerprints.set(key, fingerprintContent(content))
+			if (!chained) {
+				writes.delete(key)
+				chains.delete(key)
+				return
+			}
+			chains.set(key, [...(chains.get(key) ?? []), callId])
 		},
+		recordDriftObserved(key) {
+			drifted.add(key)
+		},
+		driftObserved: (key) => drifted.has(key),
 		hasRead: (key) => paths.has(key),
 		fingerprint: (key) => fingerprints.get(key),
+		// Withheld while edits sit on top of it. A consumer that knows only this
+		// method asks "is the current body the body of a call I can see?", and
+		// once an edit has landed the honest answer is no.
+		writeCallId: (key) => (chains.has(key) ? undefined : writes.get(key)),
+		editChain: (key) => {
+			const editCallIds = chains.get(key)
+			const rootWriteCallId = writes.get(key)
+			if (!editCallIds?.length || rootWriteCallId === undefined) return undefined
+			return { rootWriteCallId, editCallIds: [...editCallIds] }
+		},
 	}
 }