@namzu/sdk 39.0.0 → 40.0.0

package/src/registry/tool/portable.ts

@@ -0,0 +1,264 @@
+/**
+ * The schema shape every wire namzu speaks reads the same way.
+ *
+ * `dialect.ts` solves the problem one wire at a time: render draft-07, and let
+ * each driver say it again in the dialect it knows its endpoint parses. That
+ * works only where a driver HAS a measurement. Of the ten driver packages,
+ * three convert; the other seven forward the rendering verbatim, because
+ * nobody had measured their wires.
+ *
+ * One of those seven then got measured, the hard way. Its gateway validates a
+ * tool's `parameters` against the JSON Schema 2020-12 metaschema, and `read`'s
+ * `readRange` — the only `z.tuple(...)` in the first-party tool surface —
+ * renders draft-07 as `items: [a, b]`:
+ *
+ *     [400] Tool 4 function has invalid 'parameters' schema:
+ *     [{'minimum': 1, 'type': 'integer'}, {'minimum': 1, 'type': 'integer'}]
+ *     is not of type 'object', 'boolean'
+ *
+ * The lesson is not "convert in five more drivers". Wiring each driver to a
+ * dialect requires a measurement per wire, and the two hardest to measure are
+ * precisely the ones nobody can measure on a user's behalf: the driver whose
+ * schema field the vendor documents nowhere, and every compatible endpoint a
+ * user points the generic HTTP driver at.
+ *
+ * So the kernel emits the INTERSECTION instead: the subset of JSON Schema that
+ * is valid, and means the same thing, in draft-07 and in 2020-12 alike. A
+ * schema in that subset needs no conversion anywhere, which is why this runs at
+ * the rendering boundary rather than at ten driver boundaries.
+ *
+ * `toSchemaDialect` is not replaced by this and does not become dead: a driver
+ * can still be handed a `parameters` object namzu never rendered (a host
+ * passing `ChatCompletionParams` straight in), and converting at the boundary
+ * remains the right answer there.
+ */
+
+export interface PortableSchemaViolation {
+	/** Dotted path to the offending keyword, e.g. `properties.readRange.items`. */
+	readonly path: string
+	readonly keyword: string
+	/** What to write instead. */
+	readonly remedy: string
+}
+
+const NO_TUPLES =
+	'say the array uniformly — one `items` schema plus `minItems`/`maxItems`; a tuple is spelled differently in draft-07 and 2020-12 and is invalid in one of them either way'
+
+/**
+ * Keywords outside the intersection, and why each one is out.
+ *
+ * A deny-list, like `findStrictSchemaViolations` and for the same reason: an
+ * allow-list would have to enumerate every annotation a schema may carry and
+ * would refuse a schema for saying something harmless.
+ *
+ * Every entry names a wire in the driver matrix that reads it wrong, not a
+ * style preference.
+ */
+const OUTSIDE_THE_INTERSECTION: ReadonlyMap<string, string> = new Map([
+	// 2020-12 moved the positional schemas to `prefixItems` and kept `items`
+	// for the tail, so an array-valued `items` does not merely look old — it
+	// means something else, and a 2020-12 validator rejects the whole request.
+	// Measured on Zen's Console gateway; the quote is in this file's header.
+	['additionalItems', NO_TUPLES],
+	// The other spelling of the same tuple. A draft-07 validator does not know
+	// the keyword, so it ignores it — which turns a constrained array into an
+	// unconstrained one SILENTLY, the worse failure of the two. The strict
+	// tool-input subset refuses it outright as well (`strict-schema.ts`), and
+	// the function-declaration schema on one of these wires is an OpenAPI 3.0
+	// subset that has never documented it.
+	['prefixItems', NO_TUPLES],
+	// A rendered tool schema has to stand alone. The renderer already runs with
+	// `$refStrategy: 'none'`, and the MCP bridge inlines refs before handing a
+	// schema out, because a wire that does not resolve them sees an empty
+	// constraint or refuses the document.
+	['$ref', 'inline the referenced schema; a tool schema has to stand alone'],
+	['$defs', 'inline the definitions; a tool schema has to stand alone'],
+	['definitions', 'inline the definitions; a tool schema has to stand alone'],
+	['$id', 'drop it; a tool schema is not a retrievable document'],
+	['$anchor', 'drop it; there are no references to anchor'],
+	['$dynamicRef', 'inline the referenced schema; a tool schema has to stand alone'],
+	['$dynamicAnchor', 'drop it; there are no references to anchor'],
+	// Nothing on any wire reads it, and asserting a dialect is the one thing a
+	// schema that must work in both must not do. It also rides in the tools
+	// block, which renders at position 0 inside the prompt-cache prefix.
+	['$schema', 'drop it; no provider reads it and it asserts a dialect'],
+	// 2019-09 vocabulary. Same silent-widening hazard as `prefixItems` on a
+	// draft-07 validator.
+	['unevaluatedItems', 'state the constraint with `items` and `maxItems`'],
+	['unevaluatedProperties', 'state the constraint with `additionalProperties`'],
+])
+
+/**
+ * Every place a schema leaves the intersection, with its exact path.
+ *
+ * Exported so a test can sweep every shipped tool and a driver can assert
+ * rather than hope. The path is the point: the vendor's error names the tool
+ * index and the offending fragment but never where inside the schema it sits.
+ */
+export function findPortableSchemaViolations(
+	schema: unknown,
+	path = '',
+): PortableSchemaViolation[] {
+	if (Array.isArray(schema)) {
+		return schema.flatMap((item, index) => findPortableSchemaViolations(item, `${path}[${index}]`))
+	}
+	if (typeof schema !== 'object' || schema === null) return []
+
+	const found: PortableSchemaViolation[] = []
+	for (const [keyword, value] of Object.entries(schema as Record<string, unknown>)) {
+		const here = path ? `${path}.${keyword}` : keyword
+		const remedy = OUTSIDE_THE_INTERSECTION.get(keyword)
+		if (remedy !== undefined) {
+			found.push({ path: here, keyword, remedy })
+			continue
+		}
+		// The draft-07 tuple. Reported once, at the tuple, rather than once per
+		// positional schema underneath it — one fixable finding, not a list.
+		if (keyword === 'items' && Array.isArray(value)) {
+			found.push({ path: here, keyword, remedy: NO_TUPLES })
+			continue
+		}
+		// A union of types is valid JSON Schema in both dialects, but the
+		// OpenAPI-3.0-shaped wires namzu speaks take a single type name and
+		// either refuse a list or ignore it.
+		if (keyword === 'type' && Array.isArray(value)) {
+			found.push({
+				path: here,
+				keyword,
+				remedy: 'use `anyOf` of single-typed schemas; several wires take one type name only',
+			})
+			continue
+		}
+		found.push(...findPortableSchemaViolations(value, here))
+	}
+	return found
+}
+
+/**
+ * Rewrite what can be rewritten, so a tuple cannot reach a wire.
+ *
+ * Only the tuple spellings and `$schema` are rewritten. The rest of the
+ * deny-list is reported and not repaired on purpose: inlining a `$ref` or
+ * choosing which member of a `type` list the author meant is a guess about
+ * intent, and a guess that silently changes what a tool accepts is worse than
+ * the 400 it avoids. Those are caught by the profile test at the source.
+ *
+ * Returns the input unchanged — the SAME reference — when nothing needs
+ * rewriting, which is the overwhelming common case. The tools block sits at
+ * position 0 of the prompt-cache prefix, so a fresh, equal object per request
+ * would invalidate the cache for the whole run.
+ */
+export function toPortableToolSchema(json: Record<string, unknown>): Record<string, unknown> {
+	return makePortable(json) as Record<string, unknown>
+}
+
+function makePortable(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		let changed = false
+		const out = value.map((item) => {
+			const next = makePortable(item)
+			if (next !== item) changed = true
+			return next
+		})
+		return changed ? out : value
+	}
+	if (typeof value !== 'object' || value === null) return value
+
+	const node = value as Record<string, unknown>
+	const positional = Array.isArray(node.prefixItems)
+		? node.prefixItems
+		: Array.isArray(node.items)
+			? node.items
+			: undefined
+	if (positional) return collapseTuple(node, positional)
+
+	let changed = '$schema' in node
+	const out: Record<string, unknown> = {}
+	for (const [key, child] of Object.entries(node)) {
+		if (key === '$schema') continue
+		const next = makePortable(child)
+		if (next !== child) changed = true
+		out[key] = next
+	}
+	return changed ? out : node
+}
+
+/**
+ * Say a positional array uniformly.
+ *
+ * What is kept: the arity, and every constraint that applies to every member.
+ * What is lost: which member sits where. That loss is real and it is the price
+ * of a shape both dialects read identically — and it costs nothing in practice,
+ * because the tool's Zod schema still parses the call and still refuses a
+ * wrongly-ordered array with a message the model can act on. The wire schema is
+ * a hint to the model; the parser is the contract.
+ */
+function collapseTuple(
+	node: Record<string, unknown>,
+	positional: readonly unknown[],
+): Record<string, unknown> {
+	// The tail rule, in whichever dialect this node happens to be written in:
+	// draft-07 spells it `additionalItems`, 2020-12 spells it `items` and only
+	// calls it a tail when `prefixItems` holds the members.
+	const tail = Array.isArray(node.prefixItems) ? node.items : node.additionalItems
+	const arity = positional.length
+	const members = positional.map(makePortable)
+
+	// A tail that is itself a schema constrains every element past the members,
+	// so those elements join the uniform reading rather than closing it.
+	const tailSchema =
+		tail !== undefined && tail !== true && tail !== false ? makePortable(tail) : undefined
+	// `false` closes the array at the members' length; so does a `maxItems` the
+	// author already pinned there.
+	const closed =
+		tailSchema === undefined &&
+		(tail === false || (typeof node.maxItems === 'number' && node.maxItems <= arity))
+
+	// An open tail with no schema says "anything past the members", which no
+	// single `items` can express alongside the members themselves. Saying
+	// nothing about the elements is the only honest uniform reading; the bounds
+	// below still carry whatever the author pinned.
+	const candidates =
+		tailSchema !== undefined ? dedupe([...members, tailSchema]) : closed ? dedupe(members) : []
+
+	const element =
+		candidates.length === 0
+			? undefined
+			: candidates.length === 1
+				? candidates[0]
+				: { anyOf: candidates }
+
+	const out: Record<string, unknown> = {}
+	for (const [key, child] of Object.entries(node)) {
+		if (key === '$schema') continue
+		if (key === 'additionalItems') continue
+		if (key === 'prefixItems' || (key === 'items' && Array.isArray(child))) {
+			if (element !== undefined) out.items = element
+			continue
+		}
+		// The 2020-12 tail, already folded into `items` above.
+		if (key === 'items' && Array.isArray(node.prefixItems)) continue
+		if (key === 'maxItems' && closed && typeof child === 'number') {
+			out.maxItems = Math.min(child, arity)
+			continue
+		}
+		out[key] = makePortable(child)
+	}
+	// A tuple closed by `additionalItems: false` rather than by a bound loses
+	// its ceiling otherwise: a uniform `items` says nothing about length, so a
+	// schema written to forbid a third element would begin to allow any number.
+	if (closed && out.maxItems === undefined) out.maxItems = arity
+	return out
+}
+
+function dedupe(schemas: readonly unknown[]): unknown[] {
+	const seen = new Set<string>()
+	const out: unknown[] = []
+	for (const schema of schemas) {
+		const key = JSON.stringify(schema) ?? 'undefined'
+		if (seen.has(key)) continue
+		seen.add(key)
+		out.push(schema)
+	}
+	return out
+}

package/src/registry/tool/schema.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod'
 import { zodToJsonSchema } from 'zod-to-json-schema'
+import { toPortableToolSchema } from './portable.js'
 
 /**
  * The single place a tool's Zod schema becomes the JSON Schema that goes on
@@ -50,17 +51,46 @@ export function renderToolSchema(schema: z.ZodType): Record<string, unknown> {
 }
 
 /**
- * Strip what no provider reads.
+ * Make the rendering something every wire reads the same way.
  *
- * Only `$schema` today, and only at the root — `zodToJsonSchema` does not
- * stamp it on nested nodes. Kept as a named function rather than an inline
- * `delete` so the next "providers ignore this" field has an obvious home
- * and a place to be justified.
+ * Two jobs, both at this one boundary:
+ *
+ * 1. **Strip what no provider reads.** `$schema` rides in the tools block,
+ *    which renders at position 0 inside the prompt-cache prefix, once per
+ *    tool, per request, forever — and it asserts a dialect, which is the one
+ *    thing a schema that has to work on every wire must not do.
+ *
+ * 2. **Leave the intersection of draft-07 and 2020-12 intact.** `renderToolSchema`
+ *    emits draft-07, where a tuple is `items: [a, b]`; a 2020-12 wire reads
+ *    that as invalid and rejects the whole request, taking every other tool in
+ *    the call down with it. Five of the ten drivers forward the rendering
+ *    verbatim, so the only place that can be fixed once is here. See
+ *    `portable.ts` for the measurement that put it here.
  */
 export function normalizeToolSchema(json: Record<string, unknown>): Record<string, unknown> {
-	if (!('$schema' in json)) return json
-	const { $schema: _dropped, ...rest } = json
-	return rest
+	return toPortableToolSchema(json)
+}
+
+/**
+ * The schema a tool actually puts on the wire.
+ *
+ * A tool may carry an explicit `modelInputSchema` — hand-written JSON Schema,
+ * not rendered from Zod — and that schema reaches providers through the same
+ * `tools` block as a rendered one. It therefore has to clear the same bar, and
+ * the two call sites that build that block (`ToolRegistry.toLLMTools` and the
+ * toolset catalog) had each spelled the fallback out on their own. Two paths
+ * that agree today are two paths that can disagree tomorrow.
+ *
+ * The clone is deliberate: a caller may edit the parameters it is handed —
+ * `hostModelSchema` does — and the definition's own object must not move
+ * underneath the next call.
+ */
+export function toolWireSchema(tool: {
+	readonly modelInputSchema?: Record<string, unknown>
+	readonly inputSchema: z.ZodType
+}): Record<string, unknown> {
+	if (tool.modelInputSchema) return toPortableToolSchema(structuredClone(tool.modelInputSchema))
+	return renderToolSchema(tool.inputSchema)
 }
 
 /**

package/src/registry/toolset/catalog.ts

@@ -9,7 +9,7 @@ import type {
 	ToolsetDefinition,
 	ToolsetPolicy,
 } from '../../types/toolset/index.js'
-import { renderToolSchema } from '../tool/schema.js'
+import { toolWireSchema } from '../tool/schema.js'
 
 export interface ToolCatalogSearchOptions {
 	readonly loading?: readonly ToolLoadingMode[]
@@ -245,17 +245,16 @@ function toolDefinitionToLLMTool(definition: ToolDefinition | undefined): LLMToo
 		function: {
 			name: definition.name,
 			description: definition.description,
-			// Through `renderToolSchema`, not a second inline conversion. The
+			// Through `toolWireSchema`, not a second inline conversion. The
 			// options were already identical, so this was not a different
 			// rendering — it was the same rendering without the guarantees:
 			// no `$schema` stripping (that key rides in the tools block, which
-			// sits at position 0 inside the prompt-cache prefix), no memoization,
-			// and no freeze. Two paths that agree today are two paths that can
-			// disagree tomorrow, and a tool reaching the wire through the catalog
-			// rather than the registry is not a different tool.
-			parameters:
-				(definition.modelInputSchema ? structuredClone(definition.modelInputSchema) : undefined) ??
-				renderToolSchema(definition.inputSchema),
+			// sits at position 0 inside the prompt-cache prefix), no portability
+			// normalisation, no memoization, and no freeze. Two paths that agree
+			// today are two paths that can disagree tomorrow, and a tool reaching
+			// the wire through the catalog rather than the registry is not a
+			// different tool.
+			parameters: toolWireSchema(definition),
 		},
 	}
 }

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()
+	}
+}