@namzu/sdk 38.2.1 → 40.0.0

package/src/run/index.ts

@@ -29,3 +29,14 @@ export { RUN_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js'
 export type { MemoryPromoterOptions } from './memory-promoter.js'
 export { createMemoryRecallStep } from './memory-recall.js'
 export type { MemoryRecallOptions } from './memory-recall.js'
+export { createJsonClaimVerifier } from './json-claim-verifier.js'
+export type {
+	JsonClaimValue,
+	JsonClaimRequirement,
+	JsonClaimReadRequest,
+	JsonClaimObservation,
+	JsonClaimReceipt,
+	JsonClaimVerdict,
+	JsonClaimVerifierOptions,
+	JsonClaimVerifier,
+} from './json-claim-verifier.js'

package/src/run/json-claim-verifier.ts

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { performance } from 'node:perf_hooks'
+import type { RunId } from '../types/ids/index.js'
+import type { AnswerReviewContext } from '../types/run/answer-review.js'
+
+/** Numbers are restricted to safe integers; use strings for exact decimal values. */
+export type JsonClaimValue = string | number | boolean | null
+
+export interface JsonClaimRequirement {
+	readonly id: string
+	/** Host-selected source identifier, never an address supplied by the candidate. */
+	readonly source: string
+	/** RFC 6901 pointer to a scalar in the complete JSON document. */
+	readonly pointer: string
+	/** Optional postcondition in addition to candidate/source equality. */
+	readonly expected?: JsonClaimValue
+}
+
+export interface JsonClaimReadRequest {
+	readonly scope: string
+	readonly runId: RunId
+	readonly iteration: number
+	readonly requestId: string
+	readonly startedAt: number
+	/** Remaining total allowance. The host must bound capture, not only the returned buffer. */
+	readonly maxBytes: number
+	readonly signal: AbortSignal
+}
+
+export interface JsonClaimObservation {
+	readonly scope: string
+	readonly runId: RunId
+	readonly iteration: number
+	readonly requestId: string
+	readonly source: string
+	readonly observedAt: number
+	readonly complete: boolean
+	readonly kind: 'current' | 'historical'
+	readonly bytes: Uint8Array
+}
+
+export interface JsonClaimReceipt {
+	readonly scope: string
+	readonly runId: RunId
+	readonly iteration: number
+	readonly claims: Readonly<Record<string, JsonClaimValue>>
+	readonly observations: readonly {
+		readonly source: string
+		readonly requestId: string
+		readonly observedAt: number
+		readonly bytes: number
+		readonly sha256: string
+	}[]
+}
+
+export type JsonClaimVerdict =
+	| { readonly accept: true; readonly receipt: JsonClaimReceipt }
+	| { readonly accept: false; readonly feedback: string }
+
+export interface JsonClaimVerifierOptions {
+	/** Host-owned authorization scope, including the admitted revision/claim where applicable. */
+	readonly scope: string
+	readonly runId: RunId
+	readonly requirements: readonly JsonClaimRequirement[]
+	/**
+	 * Trusted, read-only adapter. Enforce access, capture bounds and cancellation;
+	 * observe during this call. A matching envelope is not authentication against
+	 * a dishonest adapter. Do not replay an action or relabel an archive as current.
+	 */
+	readonly observe: (source: string, request: JsonClaimReadRequest) => Promise<JsonClaimObservation>
+	/** Total captured source bytes per verification; default 1 MiB, at most 8 MiB. */
+	readonly maxBytes?: number
+	/** Whole verification deadline; default 2 seconds, at most 30 seconds. */
+	readonly timeoutMs?: number
+}
+
+export interface JsonClaimVerifier {
+	/** False while an observer is outstanding, including after timeout/cancellation. */
+	isDrained(): boolean
+	/** No success cache. Every call observes the configured sources again. */
+	verify(
+		claims: unknown,
+		context: Pick<AnswerReviewContext, 'runId' | 'iteration' | 'signal'>,
+	): Promise<JsonClaimVerdict>
+}
+
+function scalar(value: unknown): value is JsonClaimValue {
+	return (
+		value === null ||
+		typeof value === 'boolean' ||
+		(typeof value === 'string' && value.length <= 2_000) ||
+		(typeof value === 'number' && Number.isSafeInteger(value))
+	)
+}
+
+function reject(reason: string): JsonClaimVerdict {
+	return {
+		accept: false,
+		feedback: `Claim verification failed: ${reason} Do not claim verified completion. Correct the claims using a permitted observation, or report that completion is unavailable.`,
+	}
+}
+
+function pointerParts(pointer: string): string[] {
+	if (pointer === '') return []
+	if (!pointer.startsWith('/') || pointer.length > 512 || /~(?:[^01]|$)/u.test(pointer))
+		throw new Error('Invalid JSON claim pointer.')
+	return pointer
+		.slice(1)
+		.split('/')
+		.map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+}
+
+function select(document: unknown, parts: readonly string[]): unknown {
+	let value = document
+	for (const part of parts) {
+		if (value === null || typeof value !== 'object' || !Object.hasOwn(value, part)) return undefined
+		if (Array.isArray(value) && !/^(0|[1-9]\d*)$/u.test(part)) return undefined
+		value = (value as Record<string, unknown>)[part]
+	}
+	return value
+}
+
+/**
+ * Compare explicit candidate fields with fresh, host-authorized JSON observations.
+ * This does not judge prose or prove the broader task complete. A receipt describes
+ * observation time, not an atomic snapshot or continuing truth after the read.
+ */
+export function createJsonClaimVerifier(options: JsonClaimVerifierOptions): JsonClaimVerifier {
+	const { scope, runId, observe } = options
+	const maxBytes = options.maxBytes ?? 1_048_576
+	const timeoutMs = options.timeoutMs ?? 2_000
+	if (
+		typeof scope !== 'string' ||
+		!scope ||
+		scope.length > 2_000 ||
+		typeof runId !== 'string' ||
+		!runId ||
+		typeof observe !== 'function'
+	)
+		throw new Error('JSON claim verification requires a scope, run ID and observer.')
+	if (
+		!Number.isSafeInteger(maxBytes) ||
+		maxBytes < 1 ||
+		maxBytes > 8_388_608 ||
+		!Number.isSafeInteger(timeoutMs) ||
+		timeoutMs < 1 ||
+		timeoutMs > 30_000
+	)
+		throw new Error('Invalid JSON claim verification bounds.')
+	if (!options.requirements.length || options.requirements.length > 32)
+		throw new Error('JSON claim verification requires 1–32 requirements.')
+	const ids = new Set<string>()
+	const requirements = options.requirements.map((item) => {
+		if (
+			!/^[a-zA-Z][a-zA-Z0-9_-]{0,99}$/u.test(item.id) ||
+			ids.has(item.id) ||
+			typeof item.source !== 'string' ||
+			!item.source ||
+			item.source.length > 512 ||
+			typeof item.pointer !== 'string' ||
+			(Object.hasOwn(item, 'expected') && !scalar(item.expected))
+		)
+			throw new Error('Invalid or duplicate JSON claim requirement.')
+		ids.add(item.id)
+		return { ...item, parts: pointerParts(item.pointer) }
+	})
+	let active = false
+	let pending = 0
+	return {
+		isDrained: () => !active && pending === 0,
+		async verify(claims, context) {
+			context.signal?.throwIfAborted()
+			if (
+				context.runId !== runId ||
+				!Number.isSafeInteger(context.iteration) ||
+				context.iteration < 0
+			)
+				return reject('The review belongs to a different run or invalid iteration.')
+			if (active || pending) return reject('A previous observation has not drained.')
+			if (
+				!claims ||
+				typeof claims !== 'object' ||
+				Array.isArray(claims) ||
+				Object.keys(claims).length !== requirements.length ||
+				Object.keys(claims).some((id) => !ids.has(id))
+			)
+				return reject('Supply exactly the configured claim IDs and scalar values.')
+			const values: Record<string, JsonClaimValue> = Object.create(null)
+			for (const item of requirements) {
+				if (!Object.hasOwn(claims, item.id)) return reject('A required claim is missing.')
+				const value = (claims as Record<string, unknown>)[item.id]
+				if (!scalar(value)) return reject(`Claim ${item.id} is not a supported scalar.`)
+				values[item.id] = value
+			}
+			active = true
+			const controller = new AbortController()
+			const expiresAt = performance.now() + timeoutMs
+			const ensureActive = () => {
+				// A synchronous adapter can delay timers; late bytes still cannot pass.
+				if (performance.now() >= expiresAt) controller.abort(new Error('Verification timed out.'))
+				controller.signal.throwIfAborted()
+			}
+			const onAbort = () => controller.abort(context.signal?.reason)
+			context.signal?.addEventListener('abort', onAbort, { once: true })
+			const timer = setTimeout(
+				() => controller.abort(new Error('Verification timed out.')),
+				timeoutMs,
+			)
+			const observations: JsonClaimReceipt['observations'][number][] = []
+			let remaining = maxBytes
+			let removeAbort: (() => void) | undefined
+			try {
+				for (const source of new Set(requirements.map((item) => item.source))) {
+					ensureActive()
+					if (remaining < 1) return reject('The source byte allowance is exhausted.')
+					const request = Object.freeze({
+						scope,
+						runId,
+						iteration: context.iteration,
+						requestId: randomUUID(),
+						startedAt: Date.now(),
+						maxBytes: remaining,
+						signal: controller.signal,
+					})
+					pending++
+					const work = Promise.resolve()
+						.then(() => {
+							ensureActive()
+							return observe(source, request)
+						})
+						.finally(() => {
+							pending--
+						})
+					const aborted = new Promise<never>((_, fail) => {
+						const listener = () => fail(controller.signal.reason)
+						controller.signal.addEventListener('abort', listener, { once: true })
+						removeAbort = () => controller.signal.removeEventListener('abort', listener)
+					})
+					const observation = await Promise.race([work, aborted])
+					removeAbort?.()
+					ensureActive()
+					if (
+						!observation ||
+						observation.scope !== scope ||
+						observation.runId !== runId ||
+						observation.iteration !== context.iteration ||
+						observation.requestId !== request.requestId ||
+						observation.source !== source ||
+						observation.complete !== true ||
+						observation.kind !== 'current' ||
+						!Number.isSafeInteger(observation.observedAt) ||
+						observation.observedAt < request.startedAt ||
+						observation.observedAt > Date.now() ||
+						!(observation.bytes instanceof Uint8Array)
+					)
+						return reject('The observation is incomplete, historical or outside this review scope.')
+					if (observation.bytes.byteLength > remaining)
+						return reject('A source exceeded the byte allowance.')
+					const bytes = Buffer.from(observation.bytes)
+					remaining -= bytes.byteLength
+					const document: unknown = JSON.parse(
+						new TextDecoder('utf-8', { fatal: true }).decode(bytes),
+					)
+					for (const item of requirements.filter((item) => item.source === source)) {
+						const actual = select(document, item.parts)
+						if (!scalar(actual) || actual !== values[item.id])
+							return reject(`Claim ${item.id} does not match the selected source field.`)
+						if (Object.hasOwn(item, 'expected') && actual !== item.expected)
+							return reject(`Claim ${item.id} does not satisfy the configured postcondition.`)
+					}
+					observations.push({
+						source,
+						requestId: request.requestId,
+						observedAt: observation.observedAt,
+						bytes: bytes.byteLength,
+						sha256: createHash('sha256').update(bytes).digest('hex'),
+					})
+				}
+				ensureActive()
+				return {
+					accept: true,
+					receipt: { scope, runId, iteration: context.iteration, claims: values, observations },
+				}
+			} catch {
+				context.signal?.throwIfAborted()
+				return reject(
+					'A current source could not be fully observed and parsed within the deadline.',
+				)
+			} finally {
+				clearTimeout(timer)
+				removeAbort?.()
+				context.signal?.removeEventListener('abort', onAbort)
+				controller.abort()
+				active = false
+			}
+		},
+	}
+}

package/src/run/preparation-context-error.ts

@@ -0,0 +1,16 @@
+import { toErrorMessage } from '../utils/error.js'
+
+/**
+ * Internal bridge for SDK preparation failures with a safe availability note
+ * and, when available, fully validated fallback evidence within the same budget.
+ * The cause remains diagnostic-only. Ordinary thrown errors never become context.
+ */
+export class PreparationContextError extends Error {
+	constructor(
+		cause: unknown,
+		readonly context: string,
+	) {
+		super(toErrorMessage(cause), { cause })
+		this.name = 'PreparationContextError'
+	}
+}

package/src/run-query/index.ts

@@ -62,7 +62,7 @@ export class RunTranscriptUnavailableError extends Error {
 /** What one compaction pass removed. */
 export interface ShedPass {
 	readonly iteration: number
-	readonly reason: 'threshold' | 'overflow'
+	readonly reason: Extract<PersistedRunEvent, { type: 'compaction_shed' }>['reason']
 	readonly messages: readonly Message[]
 	/** Where in the log the pass sits, for a caller correlating with events. */
 	readonly seq: number

package/src/runtime/jobs/awaited-jobs.ts

@@ -0,0 +1,271 @@
+import type { BackgroundJob, BackgroundJobRegistry } from './registry.js'
+
+/**
+ * What this adapter needs from a registry: the jobs' exits, and one job's
+ * current status. Structural rather than the class, for the reason
+ * `BackgroundJobRegistryRef` is: the kernel passes the real registry, and a
+ * test that needs two exits and nothing else should not have to spawn
+ * processes to produce them.
+ */
+export type AwaitedJobSource = Pick<BackgroundJobRegistry, 'get' | 'onExit'>
+
+/** Exits and the text that puts them in front of the model. See {@link AwaitedJobs.takeDelivery}. */
+export interface DeliverableJobExits {
+	/** The notice text, already queued by the exit that produced it. */
+	readonly text: string
+	/** The exits that text accounts for, taken from the record. */
+	readonly exits: readonly BackgroundJob[]
+}
+
+/**
+ * Background jobs the model SAID it is waiting on.
+ *
+ * `CompletionInbox` gives a run a bounded, zero-token wait for a delegated
+ * task nobody is blocked on, and `holdForOutstandingWork` spends it: the
+ * model stops calling tools, the loop races the inbox against operator input,
+ * and the run only settles once the result is in the transcript or the grace
+ * is gone. Background shell jobs had none of it — so a model that started a
+ * job and then had nothing left to do improvised, and the recorded run
+ * (research/resident/results/2026-09-14-exploration-policy-terra-tui.json)
+ * shows what that costs: six `job read` polls, three `job list` polls and a
+ * `sleep 30`, each one a full context resend.
+ *
+ * This is the same three-method shape the hold already races —
+ * {@link hasPendingWork}, {@link waitForArrival}, {@link drain} — over the
+ * job registry instead of the task gateway.
+ *
+ * **Intent is stated, never inferred.** A job is only outstanding here once
+ * `wait_for_job` named it (see {@link expect}); job existence means nothing.
+ * That is the same distinction `CompletionInbox.expect` draws for a
+ * background task, and it is what keeps a dev server or a file watcher —
+ * started precisely so it would keep running — from holding every run of the
+ * session open for its grace period. The model that wants to wait says so.
+ */
+export class AwaitedJobs {
+	/** Awaited and still running. Nothing else can hold a run open. */
+	private readonly outstanding = new Set<string>()
+	/** Exits since the last {@link drain}. */
+	private exits: BackgroundJob[] = []
+	private readonly arrivals = new Set<() => void>()
+	private detach?: () => void
+
+	constructor(
+		private readonly source: AwaitedJobSource,
+		/** Whose jobs these are — the run or the session the jobs are bound to. */
+		private readonly owner: string,
+		/**
+		 * Whether the exit notice this run queues for the model is still
+		 * unread. A second opinion on {@link noticesDelivered}, and it can
+		 * only ever narrow what counts as pending.
+		 *
+		 * An exit is work only until the model has seen it, and this adapter is
+		 * not what shows it: the text rides out on the next tool result
+		 * (`attachNotice`), which is what normally happens, long before any
+		 * hold opens. {@link noticesDelivered} is how that delivery says so,
+		 * and it is the per-job record — the entry goes, so nothing can count
+		 * it again.
+		 *
+		 * This stays because the two answer different questions. That one is
+		 * reported BY a delivery site, so it is only as good as the sites that
+		 * remember to call it; this reads the channel itself, and a channel
+		 * with nothing queued cannot have news in it whatever the record says.
+		 * It is also safe in one direction only: it can suppress a hold, never
+		 * open one, so a stale `true` here is not a turn the model gets to
+		 * spend — which is the failure this pair exists to prevent.
+		 *
+		 * `CompletionInbox.claim` draws the same line on the task side. It can
+		 * name the task, because the call that delivers a completion knows
+		 * which one it delivered; a notice is text by the time it reaches the
+		 * tool result, so this asks the channel instead.
+		 *
+		 * Absent means nothing else consumes the notices, so a recorded exit is
+		 * unread by definition.
+		 */
+		private readonly unreadNotice?: () => boolean,
+	) {}
+
+	/**
+	 * Start listening.
+	 *
+	 * Returns the detach, and attaching twice is a no-op rather than a second
+	 * subscription — the same rule `CompletionInbox.attach` follows, for the
+	 * same reason: two subscriptions would record each exit twice.
+	 */
+	attach(): () => void {
+		if (this.detach) return this.detach
+		this.detach = this.source.onExit((job) => {
+			// `onExit` is a broadcast over a registry a host may share between
+			// runs, and the filter is the same one the exit-notice channel
+			// applies in `runtime/query/index.ts`.
+			if (job.owner !== this.owner) return
+			// `outstanding` is the gate, so an id nobody awaited is ignored and
+			// a second announcement for the same job cannot queue twice.
+			if (!this.outstanding.delete(job.id)) return
+			this.exits.push(job)
+			for (const wake of [...this.arrivals]) wake()
+		})
+		return this.detach
+	}
+
+	/**
+	 * Say that the model is waiting on this job's exit.
+	 *
+	 * Called by `wait_for_job`, and by nothing else: the wait is the whole
+	 * signal. A job that has ALREADY stopped is not recorded, because the
+	 * call that marks it is the same call that returns its output — holding
+	 * the run open afterwards would buy a turn to read a result the model has
+	 * just read. `CompletionInbox.expect` skips an already-claimed task for
+	 * the same reason.
+	 *
+	 * An id the registry does not know is ignored rather than raised: the
+	 * caller is about to fail on it anyway, and a marking call is not the
+	 * place that decides what an unknown job means.
+	 */
+	expect(id: string): void {
+		let job: BackgroundJob
+		try {
+			job = this.source.get(id)
+		} catch {
+			return
+		}
+		if (job.owner !== this.owner) return
+		if (job.status !== 'running') return
+		this.outstanding.add(id)
+	}
+
+	/**
+	 * Recorded exits the model has not been shown yet.
+	 *
+	 * Both halves of the same question: {@link noticesDelivered} drops the
+	 * entry when its notice goes out, and the `unreadNotice` constructor
+	 * argument asks the channel whether anything is still queued. A queued
+	 * exit whose notice has already been delivered is history, not pending
+	 * work, and an exit nobody awaited is not this adapter's news to carry.
+	 */
+	private get unreadExits(): boolean {
+		if (this.exits.length === 0) return false
+		return this.unreadNotice?.() ?? true
+	}
+
+	/** Whether an awaited job is still running, or one has exited unread. */
+	get hasPendingWork(): boolean {
+		return this.unreadExits || this.outstanding.size > 0
+	}
+
+	/**
+	 * Wait for the next awaited job's exit, deadline or abort, whichever comes
+	 * first. Aborting releases only this waiter; the jobs are untouched.
+	 *
+	 * Bounded by the caller, exactly as `CompletionInbox.waitForArrival` is: a
+	 * job that never exits — a dev server someone did await — must not keep a
+	 * run open, and only the run's own budget knows how long is long enough.
+	 */
+	waitForArrival(timeoutMs: number, signal?: AbortSignal): Promise<void> {
+		if (signal?.aborted) return Promise.resolve()
+		if (this.unreadExits) return Promise.resolve()
+		if (this.outstanding.size === 0) return Promise.resolve()
+
+		return new Promise((resolve) => {
+			const finish = (): void => {
+				clearTimeout(timer)
+				this.arrivals.delete(finish)
+				signal?.removeEventListener('abort', finish)
+				resolve()
+			}
+			const timer = setTimeout(finish, timeoutMs)
+			// `unref` where the runtime has it, so a pending wait never keeps a
+			// process alive past the job it was waiting for.
+			;(timer as { unref?: () => void }).unref?.()
+
+			this.arrivals.add(finish)
+			signal?.addEventListener('abort', finish, { once: true })
+			if (signal?.aborted) finish()
+		})
+	}
+
+	/**
+	 * Say that the queued exit notices have been put in front of the model.
+	 *
+	 * Called by the tool-result delivery (`attachNotice`), which is where an
+	 * exit normally reaches the model; {@link takeDelivery} does the same for
+	 * the hold's own path by taking the entries as it delivers them.
+	 *
+	 * Every recorded exit goes, and that is per-job rather than a blunt
+	 * clear: the channel hands over ALL its queued text at once, and an exit
+	 * is recorded here in the same synchronous announcement that queues its
+	 * notice, so the text just delivered is exactly the notices of the exits
+	 * in hand. An exit recorded after this call keeps its entry, because its
+	 * notice was queued after that text was taken.
+	 *
+	 * Without it the entry outlived the delivery, and the channel-level gate
+	 * above was the only thing standing between a read exit and a model turn
+	 * — a gate that reopens the moment ANY later job, awaited or not, queues
+	 * a notice of its own.
+	 */
+	noticesDelivered(): void {
+		this.exits = []
+	}
+
+	/**
+	 * Take the recorded exits together with the text that delivers them, or
+	 * take neither.
+	 *
+	 * The pairing is the whole method. Draining the exits first and then
+	 * asking for the notice loses them on the branch that finds none: the
+	 * records are gone, no text was written, and the exit the run held itself
+	 * open for is delivered by nobody. So {@link drain} is not called until
+	 * the delivery is certain, and an exit this could not deliver stays in
+	 * hand for the next one.
+	 */
+	takeDelivery(notice: () => string | undefined): DeliverableJobExits | undefined {
+		if (this.exits.length === 0) return undefined
+		const text = notice()
+		if (text === undefined) return undefined
+		return { text, exits: this.drain() }
+	}
+
+	/**
+	 * Take every exit recorded since the last call, leaving none behind.
+	 *
+	 * Draining rather than peeking, for the reason `CompletionInbox.drain`
+	 * gives: an exit that stays queued after being delivered is a duplicate
+	 * waiting to happen. Callers that are delivering want
+	 * {@link takeDelivery}, which will not take them without the notice that
+	 * accounts for them.
+	 */
+	drain(): readonly BackgroundJob[] {
+		if (this.exits.length === 0) return []
+		const exits = this.exits
+		this.exits = []
+		return exits
+	}
+
+	/**
+	 * Awaited jobs still running.
+	 *
+	 * Read when a run ends, so it can say which wait it walked away from.
+	 * Nothing here is stopped by being read — the ids are a statement, and a
+	 * job's lifetime belongs to whoever owns it.
+	 */
+	get outstandingJobIds(): readonly string[] {
+		return [...this.outstanding]
+	}
+
+	/**
+	 * Stop listening. Safe to call more than once.
+	 *
+	 * A run that ends without this leaves its listener on a registry the host
+	 * reuses across runs — the leak `CompletionInbox.close` exists to prevent,
+	 * on the other subsystem.
+	 */
+	close(): void {
+		this.detach?.()
+		this.detach = undefined
+		this.outstanding.clear()
+		this.exits = []
+		// Release anyone still waiting. A closed adapter would otherwise hold
+		// them to their own deadline for an exit that can no longer reach them.
+		for (const wake of [...this.arrivals]) wake()
+		this.arrivals.clear()
+	}
+}

package/src/runtime/jobs/registry.ts

@@ -3,6 +3,7 @@ import { spawn } from 'node:child_process'
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { killTree } from '../../process/kill-tree.js'
 import { scrubInheritedEnv } from '../../tools/env-scrub.js'
+import { awaitWithAbort } from '../../utils/await-with-abort.js'
 
 /**
  * Work that outlives a tool call, owned by whoever started it.
@@ -310,6 +311,32 @@ export class BackgroundJobRegistry {
 		return entry.record
 	}
 
+	/**
+	 * Await one job's exit — the public counterpart to `onExit`, for a
+	 * caller that wants a single result rather than a standing
+	 * subscription. Resolves at once for a job that has already stopped, so
+	 * a caller that lost the race against a fast-finishing job never blocks
+	 * on a promise that would otherwise never settle.
+	 *
+	 * `signal` is honoured: an aborted wait rejects and detaches rather than
+	 * holding the internal exit promise's continuation open for a job that
+	 * may run for another hour. That only ends the WAIT — the job itself is
+	 * untouched either way, exactly as a timed-out `kill`-less wait leaves
+	 * it. See `wait-for-job-bounds.ts`, the first caller.
+	 */
+	waitForExit(id: string, opts: { signal?: AbortSignal } = {}): Promise<BackgroundJob> {
+		const entry = this.jobs.get(id)
+		if (!entry) throw new UnknownBackgroundJobError({ id })
+		if (entry.record.status !== 'running') return Promise.resolve(entry.record)
+		// `entry` is the same object the `finalize` closure in `start()`
+		// mutates in place, so reading `entry.record` after `exit` settles
+		// sees the final status — the same trick `kill()` already relies on.
+		return awaitWithAbort(
+			entry.exit.then(() => entry.record),
+			opts.signal,
+		)
+	}
+
 	/**
 	 * Output since `fromOffset`, with what the cap dropped stated.
 	 *
@@ -410,6 +437,17 @@ export function bindOwner(
 			readonly workingDirectory: string
 			readonly env?: Record<string, string>
 		}) => JobProcess
+		/**
+		 * Be told that the model said it is waiting on a job's exit.
+		 *
+		 * The registry does not keep this: wait-intent belongs to the RUN that
+		 * expressed it, not to a registry a host may share across runs and
+		 * sessions. The run passes its own recorder here — `AwaitedJobs`, which
+		 * is what the iteration loop holds open for. Absent means nobody is
+		 * listening, and `markAwaited` is then absent from the bound ref rather
+		 * than present and silently doing nothing.
+		 */
+		readonly onAwaited?: (id: string) => void
 	} = {},
 ) {
 	const mine = (id: string): BackgroundJob => {
@@ -443,6 +481,18 @@ export function bindOwner(
 			mine(id)
 			return registry.read(id, opts ?? {})
 		},
+		waitForExit: (id: string, opts?: { signal?: AbortSignal }) => {
+			mine(id)
+			return registry.waitForExit(id, opts ?? {})
+		},
+		...(defaults.onAwaited
+			? {
+					markAwaited: (id: string) => {
+						mine(id)
+						defaults.onAwaited?.(id)
+					},
+				}
+			: {}),
 		kill: async (id: string) => {
 			mine(id)
 			return await registry.kill(id)