@namzu/sdk 52.7.0 → 53.1.0

package/src/authorization/readonly-commands.ts

@@ -1,9 +1,9 @@
 /**
  * Which shell lines only read, so that they run without a prompt.
  *
- * The reference terminal runs `ls`, `cat`, `git status` and `git diff` without
- * asking, because each is on a vetted list and nothing in the line is decided
- * at run time. This is that list and those conditions (version 2.1.302):
+ * `ls`, `cat`, `git status` and `git diff` run without asking, because each is
+ * on a vetted list and nothing in the line is decided at run time. The list and
+ * the conditions are these:
  *
  * - every command of the line is on the list, the line parses completely, and
  *   nothing in it is read at run time: no `$var` outside single quotes, no
@@ -22,7 +22,7 @@
  *
  * Not ported, and so never read-only here: `sed`, `ps`, `lsof`, `ss`, `date`,
  * `man`, `xargs`, `fd`, `gh`, `docker logs|inspect`, `printf`, `[[`, `test`
- * and the shell builtins other than `cd`. The reference's check of the working
+ * and the shell builtins other than `cd`. The check of the working
  * directory for a planted bare repository needs the directory, which the tool
  * predicate does not get; the trusted-project gate is what stands in for it.
  *
@@ -35,7 +35,7 @@ import type { ShellDialect } from '../types/tool/index.js'
 import { FLAG_TABLES, type FlagTable } from './readonly-flags.js'
 import { type ShellWord, lexShellCommandLine } from './shell-lexer.js'
 
-/** Lines longer than this are not analysed (the reference's budget). */
+/** Lines longer than this are not analysed (the budget). */
 const MAX_LINE_LENGTH = 20_000
 
 /** Variables whose value cannot change what a command does. */
@@ -80,7 +80,7 @@ const SAFE_ENVIRONMENT: ReadonlySet<string> = new Set([
 	'GIT_TERMINAL_PROMPT',
 ])
 
-/** Commands that read and print, with any arguments (the reference's bare-safe list). */
+/** Commands that read and print, with any arguments (the bare-safe list). */
 const ANY_ARGUMENTS: ReadonlySet<string> = new Set([
 	'cal',
 	'uptime',
@@ -570,7 +570,7 @@ const GIT_CHECKS: Readonly<Record<string, Dangerous>> = {
 	},
 }
 
-// -- the commands with a regex of their own in the reference ----------------
+// -- the commands with a regex of their own ----------------
 
 function uniqIsReadOnly(args: readonly string[]): boolean {
 	for (let i = 0; i < args.length; i += 1) {

package/src/authorization/readonly-flags.ts

@@ -1,8 +1,7 @@
 /**
  * Per-flag allowlists for the shell commands that may run without a prompt.
  *
- * Read from the reference terminal (version 2.1.302): for each command, the
- * flags it vets and what each takes, `none` (a switch), `string` or `number`.
+ * For each command, the flags it vets and what each takes, `none` (a switch), `string` or `number`.
  * A flag not listed here is not read-only, which is how `git diff --output=f`
  * (writes a file), `git -c`, `--exec-path` and `--config-env` stay out: they
  * are not in any table. Space-separated lists per kind keep the file readable;

package/src/authorization/removal.ts

@@ -7,8 +7,7 @@
  * `rm -rf ~`, `rm -rf $HOME`, `rm -rf "$BUILD/"` (empty variable, so `/`) and
  * `rm -rf ..` all went past it. The flags were never the point. A removal is
  * catastrophic because of WHAT it removes, so this reads the targets of `rm`
- * and `rmdir` whatever the flags, as the reference terminal's dangerous-removal
- * check does (version 2.1.302).
+ * and `rmdir` whatever the flags.
  *
  * A removal is flagged when a target is
  *
@@ -26,7 +25,7 @@
  *
  * The answer is a reason, which the kernel turns into an escalation: asked
  * every time, in every mode, and refused when nobody can be asked. It is not a
- * denial: the reference asks, because there are legitimate removals a person
+ * denial: it asks, because there are legitimate removals a person
  * can approve.
  */
 
@@ -250,7 +249,7 @@ function checkTarget(
 	const expanded = expandTilde(spelled, scope.home)
 	const relative = !isAbsolute(expanded)
 	if (expandsAtRuntime(word) && /[$`]/.test(expanded)) {
-		// A variable the check cannot read: the reference treats it as a relative
+		// A variable the check cannot read: it is treated as a relative
 		// name, which is also what the shell does when the variable is unset and
 		// the rest is a plain name. Nothing more to learn from it.
 		return undefined

package/src/authorization/shell-paths.ts

@@ -6,15 +6,15 @@
  * and `echo x > ~/.profile` carry their paths inside one string, and a
  * boundary that only reads declared arguments let both through.
  *
- * This is the reference terminal's answer, ported: a table of the commands
- * whose positional arguments are paths (its path-command table and
- * per-command extractors, version 2.1.302), the kind of access each makes (read,
- * write or create), and the output redirections of the line. It is a
+ * This reads the paths a shell line touches: a table of the commands whose
+ * positional arguments are paths, with an extractor for each command, the kind
+ * of access each makes (read, write or create), and the output redirections of
+ * the line. It is a
  * reading of the text, not a model of the shell:
  *
  * - a word that expands at runtime (`$VAR`, `$(...)`) has no path to read;
  *   it is reported with `unresolved` so the caller decides what an unreadable
- *   write target is worth (the reference asks);
+ *   write target is worth;
  * - a `cd` earlier in the line moves every relative path after it, which the
  *   reading does not follow, so the caller is told one happened;
  * - a command that is not in the table contributes nothing.
@@ -279,7 +279,7 @@ interface FlagTable {
 	readonly valuedLong: ReadonlySet<string>
 }
 
-/** Operands of a command whose flags are known: an unknown flag stops flag parsing, as in the reference. */
+/** Operands of a command whose flags are known: an unknown flag stops flag parsing. */
 function operandsByTable(table: FlagTable): (args: Args) => ShellWord[] {
 	const kind = (flag: string): 'boolean' | 'valued' | 'attached' | 'unknown' => {
 		if (flag.startsWith('--')) {

package/src/compaction/context-window.ts

@@ -121,7 +121,7 @@ export const MIN_DERIVED_TRIGGER_FRACTION = 0.5
  * The fraction of the window at which older history is summarised.
  *
  * A host that set `triggerThreshold` gets exactly that. Otherwise the
- * trigger is the one Claude Code uses: the window, less room kept for the
+ * trigger is the window, less room kept for the
  * reply (the model's output cap, at most 20,000 tokens), less a 13,000-token
  * buffer. On a 200,000-token window that is 167,000 tokens (83.5%); on a
  * 1,000,000-token window, 967,000 (96.7%).

package/src/compaction/verifier.ts

@@ -255,8 +255,8 @@ async function buildVerifiedSummaryWithProvider(
 		return serialized
 	}
 
-	// The verifier's own request can overflow a small window. The reference
-	// terminal answers that with a ladder: send less, and when nothing is left to
+	// The verifier's own request can overflow a small window. That is answered
+	// with a ladder: send less, and when nothing is left to
 	// cut, work from everything it already has. Here "less" is the older half of
 	// the excerpt dropped behind a placeholder, at most three times, and
 	// "everything it already has" is the extracted state, which the verifier only

package/src/connector/web/page.ts

@@ -16,14 +16,13 @@ export const WEB_PAGE_CACHE_MAX_BYTES = 50 * 1024 * 1024
 export const WEB_PAGE_CONVERT_MAX_CHARS = 1024 * 1024
 /** Most page text a model is asked about in one call. */
 export const WEB_PAGE_MODEL_MAX_CHARS = 100_000
-/** Marker the reference-shaped cuts end with. */
+/** Marker that truncated content ends with. */
 export const WEB_PAGE_TRUNCATED_MARKER = '[Content truncated due to length...]'
 
 /**
  * A redirect stays on the site when only the path or query changes (and
  * `www.` comes or goes). `http:` to `https:` on the same host and default
- * port is the same site too: the reference upgrades every URL to `https:`
- * before it asks, so that hop never reaches it.
+ * port is the same site too.
  */
 export function isSameSiteRedirect(from: URL, to: URL): boolean {
 	const upgrade = from.protocol === 'http:' && to.protocol === 'https:'

package/src/execution/workflow/prelude.ts

@@ -44,6 +44,15 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 		if (t === 'object') return typeof value.then === 'function' ? 'a promise' : 'an object';
 		return 'a ' + t;
 	}
+	function overBudget() {
+		return config.tokenLimit !== null && config.tokenLimit > 0 && spent.tokensUsed >= config.tokenLimit;
+	}
+	function budgetError() {
+		var e = new Error('Workflow token budget exceeded (' + spent.tokensUsed.toLocaleString('en-US') + ' / ' + config.tokenLimit.toLocaleString('en-US') + ' output tokens). Stopping further agent() calls. Agents already running will finish and their results are kept.');
+		e.name = 'WorkflowBudgetExceededError';
+		return e;
+	}
+	function isBudgetError(e) { return !!e && e.name === 'WorkflowBudgetExceededError'; }
 	async function agent(prompt, opts) {
 		if (typeof prompt !== 'string' || prompt.length === 0) {
 			throw new TypeError('agent(prompt, options?): the prompt must be a non-empty string, got ' + kind(prompt));
@@ -52,6 +61,7 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 		if (typeof o !== 'object' || Array.isArray(o)) {
 			throw new TypeError('agent(prompt, options?): options must be an object, got ' + kind(o));
 		}
+		if (overBudget()) throw budgetError();
 		var request = { prompt: prompt, cursor: cursor };
 		if (o.label != null) request.label = clean(o.label, 120);
 		if (o.phase != null) request.phase = clean(o.phase, 120);
@@ -72,12 +82,16 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 				throw new TypeError('parallel(thunks): item ' + (p + 1) + ' must be a function (wrap the work as () => agent(...)), got ' + kind(thunks[p]));
 			}
 		}
-		return Promise.all(thunks.map(function (t, n) {
+		var dropped = 0;
+		var results = await Promise.all(thunks.map(function (t, n) {
 			return Promise.resolve().then(t).catch(function (e) {
-				log('parallel item ' + (n + 1) + ' failed: ' + clean(e && e.message ? e.message : e, 300));
+				if (isBudgetError(e)) { dropped++; return null; }
+				log('Step ' + (n + 1) + ' stopped: ' + clean(e && e.message ? e.message : e, 300));
 				return null;
 			});
 		}));
+		if (dropped > 0) log('parallel: ' + dropped + (dropped === 1 ? ' item' : ' items') + ' dropped because the token budget is spent.');
+		return results;
 	}
 	async function pipeline(items) {
 		if (!Array.isArray(items)) {
@@ -89,21 +103,31 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 				throw new TypeError('pipeline(items, ...stages): stage ' + (s + 1) + ' must be a function, got ' + kind(stages[s]));
 			}
 		}
-		return Promise.all(items.map(async function (item, index) {
+		if (items.length > 0 && overBudget()) throw budgetError();
+		var dropped = 0;
+		var results = await Promise.all(items.map(async function (item, index) {
 			var value = item;
 			for (var i = 0; i < stages.length; i++) {
 				try {
-					value = await stages[i](value, index, item);
+					value = await stages[i](value, item, index);
 				} catch (e) {
-					log('pipeline item ' + (index + 1) + ' stopped at stage ' + (i + 1) + ': ' + clean(e && e.message ? e.message : e, 300));
+					if (isBudgetError(e)) { dropped++; return null; }
+					log('Item ' + (index + 1) + ' stopped at step ' + (i + 1) + ': ' + clean(e && e.message ? e.message : e, 300));
 					return null;
 				}
 				if (value === null || value === undefined) return null;
 			}
 			return value;
 		}));
+		if (dropped > 0) log('pipeline: ' + dropped + (dropped === 1 ? ' item' : ' items') + ' dropped because the token budget is spent.');
+		return results;
 	}
 	var budget = Object.freeze({
+		get total() { return config.tokenLimit; },
+		spent: function () { return spent.tokensUsed; },
+		remaining: function () {
+			return config.tokenLimit === null ? Infinity : Math.max(0, config.tokenLimit - spent.tokensUsed);
+		},
 		get tokensUsed() { return spent.tokensUsed; },
 		get tokenLimit() { return config.tokenLimit === null ? undefined : config.tokenLimit; },
 	});

package/src/execution/workflow/runtime.ts

@@ -46,6 +46,12 @@ const AGENT_CALL_KEYS = new Set([
 	'effort',
 ])
 
+/** The row title of an agent the script did not label: the first 60 characters of its prompt, whitespace squeezed. */
+export function defaultAgentLabel(prompt: string, index: number): string {
+	const label = prompt.slice(0, 60).replace(/\s+/g, ' ').trim()
+	return label.length > 0 ? label : `Agent ${index}`
+}
+
 function integer(name: string, value: number, min: number, max: number): number {
 	if (!Number.isSafeInteger(value) || value < min || value > max) {
 		throw new RangeError(`${name} must be an integer between ${min} and ${max}.`)
@@ -54,10 +60,10 @@ function integer(name: string, value: number, min: number, max: number): number
 }
 
 export function resolveWorkflowLimits(limits: WorkflowLimits = {}): WorkflowResolvedLimits {
-	const defaultConcurrency = Math.min(8, Math.max(1, cpus().length - 2))
+	const defaultConcurrency = Math.min(16, Math.max(2, cpus().length - 2))
 	return {
 		maxConcurrency: integer('maxConcurrency', limits.maxConcurrency ?? defaultConcurrency, 1, 16),
-		maxAgents: integer('maxAgents', limits.maxAgents ?? 200, 1, 1000),
+		maxAgents: integer('maxAgents', limits.maxAgents ?? 1000, 1, 1000),
 		maxSourceBytes: integer(
 			'maxSourceBytes',
 			limits.maxSourceBytes ?? 256 * 1024,
@@ -502,7 +508,7 @@ export class WorkflowRuntime {
 			const queuedAt = now()
 			const agent: AgentRecord = {
 				index,
-				label: call.label || `Agent ${index}`,
+				label: call.label || defaultAgentLabel(call.prompt, index),
 				prompt: call.prompt,
 				...(phase ? { phaseIndex: phase.index, phaseTitle: phase.title } : {}),
 				...(call.agentType !== undefined ? { agentType: call.agentType } : {}),

package/src/execution/workflow/types.ts

@@ -232,9 +232,9 @@ export interface WorkflowJournal {
 }
 
 export interface WorkflowLimits {
-	/** Agents running at once. Default `min(8, cpus - 2)`, at least 1; at most 16. */
+	/** Agents running at once. Default `min(16, cpus - 2)`, at least 2; at most 16. */
 	readonly maxConcurrency?: number
-	/** Agents one run may start. Default 200; at most 1000. */
+	/** Agents one run may start. Default 1000; at most 1000. */
 	readonly maxAgents?: number
 	/** UTF-8 script size. Default 256 KiB. */
 	readonly maxSourceBytes?: number
@@ -242,7 +242,7 @@ export interface WorkflowLimits {
 	readonly memoryLimitBytes?: number
 	/** One value crossing the bridge, either way. Default 1 MiB. */
 	readonly maxValueBytes?: number
-	/** Stop admitting new agents once this many tokens are spent. Default: none. */
+	/** Stop admitting new agents once this many tokens are spent; also the script's `budget.total`. Default: none. */
 	readonly tokenBudget?: number
 	/** Wall clock for the whole run. Default 6 hours. */
 	readonly maxDurationMs?: number

package/src/manager/agent/lifecycle.ts

@@ -348,7 +348,7 @@ export class AgentManager {
 
 	/**
 	 * The refusal for a delegation past the depth limit. It tells the model what
-	 * to do instead (the reference terminal's rule): a bare limit leaves it
+	 * to do instead: a bare limit leaves it
 	 * retrying the same spawn, while an instruction to do the work itself ends the
 	 * attempt. The limit is `AgentManagerConfig.maxDepth`; there is no env override.
 	 */

package/src/plugin/shell-hook.ts

@@ -57,7 +57,7 @@
  * - `systemMessage` — a warning for the operator, reported through the logger.
  * - `suppressOutput` — keep this hook's stdout out of the debug log.
  * - `hookSpecificOutput` with `hookEventName` naming this event (Namzu's
- *   name or the reference spelling `PreToolUse`, `Stop`, ...):
+ *   name or the PascalCase spelling `PreToolUse`, `Stop`, ...):
  *   `permissionDecision` (`allow`, `deny` or `ask`) with
  *   `permissionDecisionReason`, `updatedInput` and `additionalContext` for
  *   `pre_tool_use`; `additionalContext` for `user_prompt_submit`,
@@ -458,8 +458,8 @@ function pathOf(toolInput: unknown): string | undefined {
 	return undefined
 }
 
-/** The reference spelling of each event name, which a hook's JSON may use. */
-const REFERENCE_EVENT_NAMES: Readonly<Partial<Record<ShellHookEvent, string>>> = {
+/** The PascalCase spelling of each event name, which a hook's JSON may use. */
+const PASCAL_EVENT_NAMES: Readonly<Partial<Record<ShellHookEvent, string>>> = {
 	user_prompt_submit: 'UserPromptSubmit',
 	session_start: 'SessionStart',
 	session_end: 'SessionEnd',
@@ -565,7 +565,7 @@ function readShellHookJson(event: ShellHookEvent, stdout: string): ShellHookRead
 	if (typeof named !== 'string') {
 		return { invalid: '`hookSpecificOutput` is missing its `hookEventName`' }
 	}
-	if (named !== event && named !== REFERENCE_EVENT_NAMES[event]) {
+	if (named !== event && named !== PASCAL_EVENT_NAMES[event]) {
 		return {
 			invalid: `\`hookSpecificOutput.hookEventName\` is "${named}" but this hook ran for ${event}`,
 		}

package/src/provider/errors.ts

@@ -260,8 +260,8 @@ const OVERFLOW_BODY_PATTERNS: readonly RegExp[] = [
 	// length" — so a pattern anchored on "exceeded" misses it entirely.
 	/exceeds?\s+(?:the\s+)?(?:model'?s?\s+)?context\s+(?:length|window|size)/i,
 	/context\s+(?:length|window|size)\s+exceed/i,
-	// The reference terminal's own list matches the bare phrase "context
-	// window". Here it must sit next to a verb that says the request did not
+	// The bare phrase "context
+	// window" is too broad on its own. Here it must sit next to a verb that says the request did not
 	// fit ("larger than the model context window of N tokens"), so a 400 that
 	// only names the window ("does not support this parameter with the 1M
 	// context window beta") stays an invalid request. The same pattern lives in

package/src/public-runtime.ts

@@ -722,6 +722,7 @@ export {
 	CompletionInbox,
 	formatCompletionNotification,
 } from './scheduler/completion-inbox.js'
+export type { CompletionInboxOptions } from './scheduler/completion-inbox.js'
 
 // Scheduled jobs: WHEN something is due, and nothing about how a host stores
 // or runs a job. The time engine and the evaluator are pure (`Intl` for time

package/src/runtime/jobs/monitor-stream.ts

@@ -15,8 +15,7 @@
  * work without any injection), which is what lets the tests advance a window
  * by calling a function rather than by waiting for one.
  *
- * The constants and the wording come from the reference implementation of this
- * tool; deviations are named where they are made.
+ * The constants and the wording are fixed here.
  */
 
 /** A longer line keeps its first this-many characters. */

package/src/runtime/jobs/websocket-source.ts

@@ -29,7 +29,7 @@ import type { JobHost, JobSource } from './registry.js'
  * asks a person first (see `tools/builtins/monitor.ts`).
  */
 
-/** The largest frame accepted; a bigger one ends the watch. Same as the reference. */
+/** The largest frame accepted; a bigger one ends the watch. */
 export const WEBSOCKET_MAX_PAYLOAD_BYTES = 1_048_576
 export const WEBSOCKET_HANDSHAKE_TIMEOUT_MS = 15_000
 /** After a polite close, how long a peer gets to answer before the socket is destroyed. */

package/src/runtime/query/checkpoint.ts

@@ -2,6 +2,7 @@ import type { WorkingStateSnapshot } from '../../compaction/wire.js'
 import { type TurnRecorder, readFoldedHistory } from '../../manager/session/turn-recorder.js'
 import type { CheckpointScope, SessionCheckpointStore } from '../../store/checkpoint/index.js'
 import type { SessionLog } from '../../store/session-log/index.js'
+import { restoreSpilledRequestInputs } from '../../store/session-log/spilled-input.js'
 import type { SerializedSpanContext } from '../../telemetry/attributes.js'
 import { NamzuError } from '../../types/errors/index.js'
 import type {
@@ -148,7 +149,11 @@ export async function readParks(
 				decisionId: r.decisionId,
 				turnId: r.turnId as TurnId,
 				checkpointId: r.checkpointId,
-				request: r.request as unknown as HITLDecisionRequest,
+				// A call input too large for a line was spilled; put it back.
+				request: (await restoreSpilledRequestInputs(
+					structuredClone(r.request) as unknown as HITLDecisionRequest & { toolCalls?: unknown },
+					(ref) => log.readSpill(ref),
+				)) as HITLDecisionRequest,
 				parkedAt: Date.parse(r.ts),
 				...(r.deadlineAt !== undefined ? { deadlineAt: Date.parse(r.deadlineAt) } : {}),
 			})

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

@@ -526,7 +526,7 @@ export class IterationOrchestrator {
 		await this.ctx.checkpointMgr.markLoopStart?.(recorder)
 
 		// Context-overflow relief is a two-rung ladder per *stuck point*, not per
-		// turn, as in the reference terminal (at most two reactive compactions per
+		// turn (at most two reactive compactions per
 		// overflow): the first relief, then one deeper pass if the retry still
 		// overflows.
 		//
@@ -2121,7 +2121,7 @@ export class IterationOrchestrator {
 						classifyProviderError(err, this.ctx.provider.id).code === 'context_length_exceeded'
 					) {
 						// The rapid-refill check comes first, before the first reactive relief
-						// of an overflow, as in the reference terminal. A relief that follows
+						// of an overflow. A relief that follows
 						// the previous compaction within the refill window counts toward the
 						// limit, so a tool that re-fills the window every time it is called
 						// stops the turn instead of being cleared and called again without end.
@@ -2155,7 +2155,7 @@ export class IterationOrchestrator {
 							continue
 						}
 						// Out of rungs. The conversation is kept; say why compaction could not
-						// make room when it errored, as the reference does.
+						// make room when it errored.
 						const cause = compactionErrorNote(this.ctx)
 						if (cause !== undefined && err instanceof Error) {
 							try {

package/src/runtime/query/iteration/outstanding-work.ts

@@ -163,7 +163,7 @@ export async function* holdForOutstandingWork(
 	hasToolCalls: boolean,
 	deliverInbound: () => number | Promise<number>,
 ): AsyncGenerator<SessionEvent, boolean> {
-	const inbox = ctx.completionInbox?.hasPendingWork ? ctx.completionInbox : undefined
+	const inbox = ctx.completionInbox?.holdsTurn ? ctx.completionInbox : undefined
 	const jobs = ctx.awaitedJobs?.hasPendingWork ? ctx.awaitedJobs : undefined
 	if (!inbox && !jobs) return false
 
@@ -370,7 +370,14 @@ export function settleOutstandingWork(ctx: IterationContext): void {
 /** Work this turn walked away from. See {@link settleOutstandingWork}. */
 export function recordAbandonedWork(ctx: IterationContext): void {
 	const abandoned = ctx.completionInbox?.outstandingTaskIds ?? []
-	if (abandoned.length > 0) {
+	if (abandoned.length > 0 && ctx.completionInbox?.holdsTurnOpen === false) {
+		// Handed over on purpose: the host keeps these running and tells the
+		// model when they end, so the turn did not walk away from them.
+		ctx.log.info('Turn ended with delegated work left running in the background', {
+			[NAMZU.TURN_ID]: ctx.recorder.turnId,
+			'namzu.runtime.tasks': abandoned,
+		})
+	} else if (abandoned.length > 0) {
 		ctx.log.warn('Turn ended with delegated work still running', {
 			[NAMZU.TURN_ID]: ctx.recorder.turnId,
 			'namzu.runtime.tasks': abandoned,

package/src/runtime/query/iteration/phases/compaction-breaker.ts

@@ -30,8 +30,8 @@ export const COMPACTION_REFILL_LIMIT = 3
 
 /**
  * One short line, shown once, when the turn stops on refills. It names the
- * cause and a step that keeps the conversation: the reference terminal also
- * offers to start over here, and Namzu never does.
+ * cause and a step that keeps the conversation: starting over is never
+ * offered here.
  */
 export const COMPACTION_REFILL_MESSAGE =
 	'The context filled up again right after being compacted, three times in a row. A file being read or a tool output is probably too large for the context window. Try reading it in smaller parts.'

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

@@ -221,8 +221,7 @@ export function measureContext(ctx: IterationContext): {
 }
 
 /**
- * Reactive compactions allowed for one overflow, as in the reference
- * terminal: the first relief, then at most one deeper pass.
+ * Reactive compactions allowed for one overflow: the first relief, then at most one deeper pass.
  */
 export const OVERFLOW_RELIEF_LIMIT = 2
 
@@ -350,8 +349,8 @@ export async function relieveOverflow(
 
 /**
  * Why the last compaction attempt errored, kept for the turn so that when
- * relief runs out the failure it ends on can say so, as the reference
- * terminal's " · automatic compaction failed: <cause>" does.
+ * relief runs out the failure it ends on can say so, and it reads
+ * " · automatic compaction failed: <cause>".
  */
 const compactionErrors = new WeakMap<object, string>()
 const MAX_COMPACTION_CAUSE_CHARS = 300
@@ -430,9 +429,8 @@ async function declined(
 /**
  * The third refill in a row: stop the turn instead of compacting again.
  * Returns true when this pass must not run. Only with `circuitBreaker`.
- * The loop also asks it before the first reactive relief of an overflow, as
- * the reference terminal does (`rhr` runs first in its withheld-overflow
- * handling), so a re-read loop made only of overflows is counted too.
+ * The loop also asks it before the first reactive relief of an overflow, so a re-read loop made
+ * only of overflows is counted too.
  */
 export async function stopOnRefill(ctx: IterationContext): Promise<boolean> {
 	const breaker = compactionBreaker(ctx)
@@ -721,7 +719,7 @@ async function runCompactionCheckInner(
 	const breaker = compactionBreaker(ctx)
 	if (breaker?.failuresOpen && !options?.force) {
 		if (breaker.takeFailureNotice()) {
-			// Silent for the person, as in the reference terminal: a log line and the
+			// Silent for the person: a log line and the
 			// event for a host that wants it, but no sentence to show. Only the
 			// proactive pass stops; a real overflow still runs the reactive ladder.
 			ctx.log.warn('Compaction failed three times in a row — switched off for this turn', {

package/src/runtime/query/iteration/request-repair.ts

@@ -21,7 +21,7 @@ import { isProviderRejectedImageError } from './provider-rejected-image.js'
  * Repair-and-retry for a request a provider rejects as invalid (a 400 that is
  * not a context overflow), so a conversation does not dead-end on it.
  *
- * Mirrors the reference terminal's table of silent 400 recoveries: pair tool
+ * The silent 400 recoveries, in order: pair tool
  * calls with results before a send, strip rejected reasoning, drop a
  * parameter the model refuses, and take rejected media out of the OUTGOING
  * request. Stored history is never edited.
@@ -77,7 +77,7 @@ type Rejection =
 /** Most repair resends for one original request, across every send it makes. */
 export const MAX_REPAIRS_PER_REQUEST = 5
 const MAX_STRIPS_PER_INDEX = 3
-/** The reference drops media in these steps for an unprocessable request. */
+/** Media is dropped in these steps for an unprocessable request. */
 const GENERIC_MEDIA_LIMITS: readonly number[] = [510, 255, 127]
 
 const PARAMETER_CODES: ReadonlySet<string> = new Set([
@@ -608,7 +608,7 @@ export class RequestRepair {
 				victims = slots.filter((slot) => slot.messageIndex === newest.messageIndex)
 			}
 		} else {
-			// The reference's steps, then halving for smaller requests, down to
+			// The media steps, then halving for smaller requests, down to
 			// none: each step keeps fewer than the request held, newest first.
 			const limit =
 				GENERIC_MEDIA_LIMITS.find((candidate) => candidate < slots.length) ??

package/src/runtime/query/path-escalation.ts

@@ -46,8 +46,7 @@ export interface PathEscalationContext {
  * a root that itself sits under a protected name is not a reason to ask about
  * every file in it. The case that matters is the managed worktree a sub-agent
  * runs in, `~/.namzu/projects/<slug>/worktrees/<name>`, which lies under
- * `.namzu` by construction; the reference terminal makes the same exception
- * for its own worktrees directory. A path in no root is looked at whole.
+ * `.namzu` by construction. A path in no root is looked at whole.
  */
 function protectedScope(absolute: string, roots: readonly string[]): string {
 	let best: string | undefined
@@ -194,7 +193,7 @@ export async function shellEscalations(
 				if (!context.reviewOutside) continue
 				if (unresolved) {
 					// A write whose target is decided at runtime cannot be checked; a
-					// read of one is left, as the reference leaves it.
+					// read of one is left alone.
 					if (use.access === 'write') outside.add(spelled)
 					continue
 				}

package/src/scheduler/completion-inbox.ts

@@ -43,6 +43,11 @@ const UNOWNED_BUFFER_LIMIT = 32
  */
 const OWNED_WORK_DISPLAY_LIMIT = 16
 
+export interface CompletionInboxOptions {
+	/** See {@link CompletionInbox.holdsTurnOpen}. Default `true`. */
+	readonly holdsTurnOpen?: boolean
+}
+
 /**
  * Completions that finished with nobody left to hear them.
  *
@@ -151,7 +156,23 @@ export class CompletionInbox {
 	 * `log` is optional and unresolved until it is actually needed (the
 	 * eviction-warning path in `hold()`), same reason as `LocalTaskScheduler`.
 	 */
-	constructor(private readonly log?: Logger) {}
+	constructor(
+		private readonly log?: Logger,
+		options: CompletionInboxOptions = {},
+	) {
+		this.holdsTurnOpen = options.holdsTurnOpen !== false
+	}
+
+	/**
+	 * Whether a turn about to end waits here for the tasks still running.
+	 *
+	 * `true` (the default) is the original contract: the turn parks at its settle
+	 * point until the tasks it launched report back, so their results enter the
+	 * same turn. `false` lets the turn end with them still running; the host owns
+	 * their completion from then on (it keeps them alive and wakes the model when
+	 * they end). Completions that have already arrived are delivered either way.
+	 */
+	readonly holdsTurnOpen: boolean
 
 	/**
 	 * Start listening.
@@ -349,6 +370,15 @@ export class CompletionInbox {
 		return this.unheard.size > 0 || this.outstanding.size > 0
 	}
 
+	/**
+	 * Whether the turn has a reason to wait at its settle point: anything
+	 * pending when it {@link holdsTurnOpen}, else only a completion already in
+	 * hand (waiting for its persistence gate).
+	 */
+	get holdsTurn(): boolean {
+		return this.holdsTurnOpen ? this.hasPendingWork : this.unheard.size > 0
+	}
+
 	/**
 	 * Wait for the next completion, deadline or abort, whichever comes first.
 	 * Aborting releases only this waiter; work and undelivered results remain owned.

package/src/session/workspace/driver.ts

@@ -22,7 +22,7 @@ export interface CreateWorkspaceParams {
 	/**
 	 * Traceable name below the configured workspace root. Nested names are
 	 * accepted; absolute paths, traversal, and paths rewritten by a filesystem
-	 * link are refused by the reference Git driver.
+	 * link are refused by the Git driver.
 	 */
 	label?: string
 }

package/src/store/checkpoint/memory.ts

@@ -26,7 +26,7 @@ export interface InMemorySessionCheckpointStoreOptions {
  *
  * It keeps the serialised bytes rather than the object, so `restore` hashes
  * exactly what `write` hashed and refuses exactly what the disk store
- * refuses. It is the parity partner of the disk store and the store an
+ * refuses. It is the counterpart of the disk store and the store an
  * in-memory session keeps its checkpoints in.
  */
 export class InMemorySessionCheckpointStore implements SessionCheckpointStore {

package/src/store/memory/markdown-format.ts

@@ -249,7 +249,7 @@ export interface MemoryFileFields {
 /**
  * The file for one memory. Fields that repeat another are left out — a title
  * equal to the name, a summary equal to the description, the default format —
- * so an ordinary file carries the reference shape and nothing else.
+ * so an ordinary file carries the canonical shape and nothing else.
  */
 export function formatMemoryFile(fields: MemoryFileFields, body: string): string {
 	const lines: string[] = ['---']