@tangle-network/agent-runtime 0.190.0 → 0.191.0

package/dist/{coordination-driver-Da1IGdTP.js → coordination-driver-Bw0Prnim.js}

@@ -4,7 +4,7 @@ import { t as detachedFrozen } from "./snapshot-CTAf4uuA.js";
 import { b as workerTraceAnalysisStore, i as InMemorySpawnJournal, n as FileSpawnJournal, r as InMemoryResultBlobStore, t as FileResultBlobStore, y as parseWorkerToolTraceArtifact } from "./spawn-journal-B9eTmVAn.js";
 import { r as chargedTokens, u as promptCacheTokenClasses, v as unmeteredSpend } from "./util-mCNUeboW.js";
 import { i as writeAllBytes, n as parseCommittedJsonLines, r as prepareJsonlAppend, t as isNoEntError } from "./jsonl-file-CDfsCI5s.js";
-import { Dt as createPeerMailbox, J as assertValidBudget, Kt as runBrainLoop, Mt as isTerminalNodeStatus, St as createInbox, U as freeSlots, c as pickBestDelivered, f as withDriverExecutor, g as meterRuntimeOwnedProviderAttempt, jt as isLiveNodeStatus, l as runFinalizer, o as bestDelivered, ot as createExecutorRegistry, u as runTree } from "./supervisor-CqJW4qap.js";
+import { At as createPeerMailbox, Ft as isTerminalNodeStatus, K as freeSlots, Pt as isLiveNodeStatus, Tt as createInbox, Yt as runBrainLoop, Z as assertValidBudget, d as pickBestDelivered, f as runFinalizer, h as withDriverExecutor, l as bestDelivered, lt as createExecutorRegistry, p as runTree, r as resolveRedactor, y as meterRuntimeOwnedProviderAttempt } from "./redact-BP8Xn2A3.js";
 import { A as writeWorkerCancellation, M as writeWorkerSteerAcknowledgement, c as readWorkerCancelRequests, d as readWorkerSteerRequests, k as writeRunCancellation, l as readWorkerCancellation, o as readRunCancelRequest, r as claimWorkerSteerDelivery, s as readRunCancellation, u as readWorkerSteerAcknowledgement } from "./run-layout-B8I_LXN-.js";
 import { agentProfileSchema, canonicalCandidateDigest } from "@tangle-network/agent-interface";
 import { argHash, errorStreakDetector, observeAll, repeatedActionDetector } from "@tangle-network/agent-eval";
@@ -139,6 +139,50 @@ function createEventBus(now = Date.now) {
 *  nothing else, so the decision type states them and nothing else. */
 const questionEscalationTargets = ["parent", "user"];
 const isQuestionEscalationTarget = (value) => questionEscalationTargets.includes(value);
+/**
+* The trace-tool sets a DEFINED analyst may ask for — the exact group names agent-eval's
+* `buildTraceToolsForGroup` accepts, restated here so the `define_analyst` JSON Schema can
+* enumerate them for the model that writes one. Named, not free-form, because the group is the
+* lens's cost ceiling: `all` grants seven trace tools, `discovery` grants three and no deep reads.
+* A name eval does not know throws at registration, which is where the two lists are held together.
+*/
+const analystToolGroupNames = [
+	"all",
+	"discovery",
+	"discoveryAndRead",
+	"discoveryAndSearch",
+	"targeted",
+	"singleTrace"
+];
+/** Every bound `define_analyst` enforces before a definition reaches a registry.
+*
+*  MOTIVE, stated as numbers, because a fence whose motive cannot be stated is over-engineering:
+*  a defined lens spends real model calls from the run's own account on every settle it is routed
+*  over, and its `instructions` are re-sent on every one of them. So the two fields that multiply
+*  — `instructions` bytes and `maxLlmCalls` — are the ones with hard ceilings, and the ceilings are
+*  twice agent-eval's own defaults (`maxIterations` 12, `maxLlmCalls` 8, `maxToolCalls` 48,
+*  `maxOutputChars` 10_000): enough headroom for a deeper question than the shipped lenses ask,
+*  not enough for one definition to become the dominant cost of a run. */
+const ANALYST_DEFINITION_BOUNDS = Object.freeze({
+	idPattern: /^[a-z0-9][a-z0-9-]{1,63}$/,
+	maxDescriptionChars: 300,
+	maxAreaChars: 64,
+	maxQuestionChars: 1e3,
+	maxInstructionsChars: 2e4,
+	maxModelChars: 128,
+	maxIterations: 24,
+	maxLlmCalls: 16,
+	maxToolCalls: 96,
+	maxOutputChars: 2e4,
+	maxEvidenceCitations: 10,
+	/** Lenses ONE manager may define, counting those it defined in a PRIOR process of a durable run.
+	*  This bounds MENU GROWTH, not spend: a definition costs nothing until `run_analyst` is called,
+	*  so the failure it stops is a manager that keeps re-authoring a lens instead of running one —
+	*  each definition adds a line every later `list_analysts` re-reads. Eight is more than the five
+	*  calibrated lenses agent-eval ships. Per-run analyst SPEND is bounded by the conserved pool the
+	*  engine draws from, not here. */
+	maxDefinitionsPerManager: 8
+});
 /** Producer-side cleanliness for the `finding` event. The findings payload is arbitrary analyst
 *  output, the digest a subscriber computes (RFC 8785) throws on ANY `undefined` value — nested
 *  included — and a throwing subscriber leaves the event invisible to EVERY subscriber. The
@@ -164,10 +208,163 @@ function canonicalFindingEvent(finding) {
 		};
 	}
 }
+/**
+* Validate and BOUND one `define_analyst` argument.
+*
+* Every reason is collected, never short-circuited: a manager re-authoring from a partial list of
+* complaints spends a turn per complaint. Numeric limits are CLAMPED rather than rejected — asking
+* for 200 tool calls is a mis-estimate, not a malformed definition, and the accepted value is
+* returned so the manager reads the ceiling it actually got.
+*/
+function parseAuthoredAnalystDefinition(raw) {
+	const issues = [];
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { issues: [{
+		path: "definition",
+		message: "must be an object"
+	}] };
+	const o = raw;
+	const bounds = ANALYST_DEFINITION_BOUNDS;
+	const text = (field, max) => {
+		const value = o[field];
+		if (typeof value !== "string" || value.trim().length === 0) {
+			issues.push({
+				path: field,
+				message: "is required and must be a non-empty string"
+			});
+			return "";
+		}
+		const trimmed = value.trim();
+		if (trimmed.length > max) {
+			issues.push({
+				path: field,
+				message: `must be at most ${max} characters (received ${trimmed.length})`
+			});
+			return "";
+		}
+		return trimmed;
+	};
+	const id = text("id", 64);
+	if (id.length > 0 && !bounds.idPattern.test(id)) issues.push({
+		path: "id",
+		message: "must be 2-64 characters of lowercase letters, digits and hyphens, starting with a letter or digit"
+	});
+	const description = text("description", bounds.maxDescriptionChars);
+	const area = text("area", bounds.maxAreaChars);
+	const question = text("question", bounds.maxQuestionChars);
+	const instructions = text("instructions", bounds.maxInstructionsChars);
+	const toolGroup = o.toolGroup;
+	if (!analystToolGroupNames.includes(toolGroup)) issues.push({
+		path: "toolGroup",
+		message: `must be one of ${analystToolGroupNames.join(", ")}`
+	});
+	let model;
+	if (o.model !== void 0) if (typeof o.model !== "string" || o.model.trim().length === 0) issues.push({
+		path: "model",
+		message: "must be a non-empty string when present"
+	});
+	else if (o.model.length > bounds.maxModelChars) issues.push({
+		path: "model",
+		message: `must be at most ${bounds.maxModelChars} characters`
+	});
+	else model = o.model.trim();
+	const clampedLimit = (field, max, source) => {
+		const value = source[field];
+		if (value === void 0) return void 0;
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+			issues.push({
+				path: `limits.${field}`,
+				message: "must be a positive integer"
+			});
+			return;
+		}
+		return Math.min(value, max);
+	};
+	let limits;
+	if (o.limits !== void 0) if (!o.limits || typeof o.limits !== "object" || Array.isArray(o.limits)) issues.push({
+		path: "limits",
+		message: "must be an object"
+	});
+	else {
+		const source = o.limits;
+		const knownLimits = /* @__PURE__ */ new Set([
+			"maxIterations",
+			"maxLlmCalls",
+			"maxToolCalls",
+			"maxOutputChars"
+		]);
+		for (const key of Object.keys(source)) if (!knownLimits.has(key)) issues.push({
+			path: `limits.${key}`,
+			message: `is not an investigation limit (accepted: ${[...knownLimits].join(", ")})`
+		});
+		const maxIterations = clampedLimit("maxIterations", bounds.maxIterations, source);
+		const maxLlmCalls = clampedLimit("maxLlmCalls", bounds.maxLlmCalls, source);
+		const maxToolCalls = clampedLimit("maxToolCalls", bounds.maxToolCalls, source);
+		const maxOutputChars = clampedLimit("maxOutputChars", bounds.maxOutputChars, source);
+		const present = {
+			...maxIterations === void 0 ? {} : { maxIterations },
+			...maxLlmCalls === void 0 ? {} : { maxLlmCalls },
+			...maxToolCalls === void 0 ? {} : { maxToolCalls },
+			...maxOutputChars === void 0 ? {} : { maxOutputChars }
+		};
+		if (Object.keys(present).length > 0) limits = present;
+	}
+	let minimumEvidenceCitations;
+	if (o.minimumEvidenceCitations !== void 0) {
+		const value = o.minimumEvidenceCitations;
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 1) issues.push({
+			path: "minimumEvidenceCitations",
+			message: "must be a positive integer"
+		});
+		else minimumEvidenceCitations = Math.min(value, bounds.maxEvidenceCitations);
+	}
+	const known = /* @__PURE__ */ new Set([
+		"id",
+		"description",
+		"area",
+		"question",
+		"instructions",
+		"toolGroup",
+		"model",
+		"limits",
+		"minimumEvidenceCitations"
+	]);
+	for (const key of Object.keys(o)) if (!known.has(key)) issues.push({
+		path: key,
+		message: `is not part of an authored analyst definition (accepted: ${[...known].join(", ")})`
+	});
+	if (issues.length > 0) return { issues };
+	return { definition: Object.freeze({
+		id,
+		description,
+		area,
+		question,
+		instructions,
+		toolGroup,
+		...model === void 0 ? {} : { model },
+		...limits === void 0 ? {} : { limits: Object.freeze(limits) },
+		...minimumEvidenceCitations === void 0 ? {} : { minimumEvidenceCitations }
+	}) };
+}
 /** Normalize the two spellings of an analyst-on-settle entry to the route form. */
 function normalizeAnalyzeOnSettle(entry) {
 	return typeof entry === "string" ? { kind: entry } : entry;
 }
+/**
+* Why one parent→child delivery did not land, in the words the MANAGER needs.
+*
+* `DownMessageDeliveryOutcome` is the machine code; this is the sentence beside it. A code alone
+* left the manager to guess whether to retry, spawn, or give up — `already-settled` and
+* `scope-stopped` look alike and need opposite moves. Every refusal a coordination verb returns
+* carries a sentence like these, because the manager cannot see the state that produced it.
+*/
+const downMessageRefusalReasons = Object.freeze({
+	delivered: "the message reached the worker",
+	"unknown-worker": "no worker of this manager has that id — check observe_agent for the live ids",
+	"already-settled": "that worker already settled, so nothing can reach it — spawn a fresh worker for the follow-up work",
+	"runtime-has-no-inbox": "that worker runs on an executor with no inbox, so it can never receive a message — re-spawn it on a steerable executor if it must be corrected mid-run",
+	"scope-stopped": "this manager’s scope has stopped, so no further message may be sent from it",
+	"runtime-error": "the executor threw while accepting the message; the worker may or may not have received it"
+});
 /** Every cause at zero — a pre-flight publishes its whole ledger from the first read. */
 function emptyPreflightCounts() {
 	return {
@@ -180,6 +377,29 @@ function emptyPreflightCounts() {
 *  MCP client request timeout so the call returns a `pending` liveness snapshot instead of erroring;
 *  the supervisor re-polls until the worker settles. */
 const DEFAULT_AWAIT_EVENT_TIMEOUT_MS = 15e3;
+/** Default and maximum bounds for one {@link CoordinationTools} journal read. The defaults are
+*  sized for a driver turn (a page a model can read and still have room to act on); the maxima
+*  bound what a single tool result may cost even when the caller asks for everything. */
+const JOURNAL_READ_BOUNDS = Object.freeze({
+	defaultLimit: 50,
+	maxLimit: 500,
+	defaultMaxBytes: 16384,
+	maxMaxBytes: 262144
+});
+/** Every `CoordinationEvent` kind `read_journal` can return — the tool advertises this list in its
+*  JSON Schema AND filters on it, so the schema cannot promise a kind the filter drops. */
+const journalEventKinds = [
+	"question",
+	"settled",
+	"finding",
+	"steer",
+	"answer",
+	"instruction",
+	"delivery-attempt",
+	"mail",
+	"escalation",
+	"analyst-defined"
+];
 /** The reserved coordination verb names — the complete set `createCoordinationTools` can emit
 *  (the analyst pair is conditional but still reserved). A driver's extra WORK tools must not
 *  collide with any of these, or it could no longer coordinate; callers validate eagerly against
@@ -202,8 +422,10 @@ const coordinationVerbNames = [
 	"ask_parent",
 	"submit_result",
 	"stop",
+	"read_journal",
 	"list_analysts",
-	"run_analyst"
+	"run_analyst",
+	"define_analyst"
 ];
 /**
 * The `CoordinationEvent` kinds a driver may name in `await_event`. The pull queue carries the
@@ -969,6 +1191,14 @@ function createCoordinationTools(opts) {
 			type: "mail",
 			...ev.mail
 		};
+		if (ev.type === "escalation") return {
+			type: "escalation",
+			...ev.escalation
+		};
+		if (ev.type === "analyst-defined") return {
+			type: "analyst-defined",
+			...ev.analyst
+		};
 		return {
 			type: ev.type,
 			...ev.down
@@ -1032,6 +1262,13 @@ function createCoordinationTools(opts) {
 		}, { priority: urgencyPriority(record.question.urgency) });
 		return record.question;
 	};
+	/** The refusal every `answer_question` path returns for an id this manager has no question for.
+	*  A THROW here reaches the manager as a transport error with no vocabulary it can act on, and
+	*  this is the verb the `no-parent` guidance tells it to use — so it names the condition. */
+	const unknownQuestion = (questionId) => ({
+		error: "unknown-question",
+		reason: `this manager has no question with the id ${JSON.stringify(questionId)}; call list_questions for the ids you may decide`
+	});
 	const decideQuestion = (questionId, decision) => {
 		const idx = questions.findIndex((q) => q.id === questionId);
 		if (idx < 0) throw new Error(`unknown questionId ${JSON.stringify(questionId)}`);
@@ -1045,6 +1282,36 @@ function createCoordinationTools(opts) {
 		questions[idx] = next;
 		return next;
 	};
+	const escalations = [...opts.priorEscalations ?? []];
+	const escalate = async (question) => {
+		let outcome;
+		if (opts.escalateQuestion === void 0) outcome = {
+			delivered: false,
+			reason: "this manager has no parent inbox in this run, so nothing above it can receive the question"
+		};
+		else try {
+			outcome = await opts.escalateQuestion(question);
+		} catch (error) {
+			outcome = {
+				delivered: false,
+				reason: `the parent channel refused the question: ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+		const record = Object.freeze({
+			questionId: question.id,
+			from: question.from,
+			urgency: question.urgency,
+			delivered: outcome.delivered,
+			...outcome.delivered ? { to: outcome.to } : { reason: outcome.reason },
+			at: Date.now()
+		});
+		escalations.push(record);
+		await bus.publish({
+			type: "escalation",
+			escalation: record
+		}, { queue: false });
+		return record;
+	};
 	const blockingQuestionsForStop = () => {
 		if (questionPolicy === "auto" || questionPolicy === "bubble") return [];
 		return questions.filter((q) => {
@@ -1053,6 +1320,165 @@ function createCoordinationTools(opts) {
 			return q.status !== "answered" && q.status !== "deferred";
 		});
 	};
+	const redactJournalEvent = resolveRedactor(opts.redactJournal);
+	const clampBound = (raw, field, fallback, max) => {
+		if (raw === void 0) return fallback;
+		if (typeof raw !== "number" || !Number.isInteger(raw)) throw new Error(`coordination tools: "${field}" must be an integer`);
+		return Math.min(Math.max(raw, 1), max);
+	};
+	const journalKinds = (raw) => {
+		if (raw === void 0) return void 0;
+		if (!Array.isArray(raw)) throw new Error("coordination tools: \"kinds\" must be an array of event kinds");
+		for (const kind of raw) if (!journalEventKinds.includes(kind)) throw new Error(`coordination tools: "kinds" accepts ${journalEventKinds.join(", ")}; received ${JSON.stringify(kind)}`);
+		return new Set(raw);
+	};
+	const redactedRow = (record) => {
+		try {
+			return redactJournalEvent(detachedFrozen(record.event));
+		} catch (error) {
+			return {
+				type: record.event.type,
+				redactionFailed: error instanceof Error ? error.message : String(error)
+			};
+		}
+	};
+	const priorJournal = opts.priorJournal ?? [];
+	const journalRows = () => {
+		const rows = [];
+		let row = 0;
+		for (const record of priorJournal) rows.push({
+			row: row++,
+			seq: record.seq,
+			at: record.at,
+			priority: record.priority,
+			prior: true,
+			event: void 0,
+			record
+		});
+		for (const record of bus.history()) rows.push({
+			row: row++,
+			seq: record.seq,
+			at: record.at,
+			priority: record.priority,
+			event: void 0,
+			record
+		});
+		return rows;
+	};
+	const readJournal = (raw) => {
+		const a = raw === void 0 ? {} : obj(raw);
+		const sinceRow = a.sinceRow === void 0 ? 0 : typeof a.sinceRow === "number" && Number.isInteger(a.sinceRow) && a.sinceRow >= 0 ? a.sinceRow : (() => {
+			throw new Error("coordination tools: \"sinceRow\" must be a non-negative integer");
+		})();
+		const limit = clampBound(a.limit, "limit", JOURNAL_READ_BOUNDS.defaultLimit, JOURNAL_READ_BOUNDS.maxLimit);
+		const maxBytes = clampBound(a.maxBytes, "maxBytes", JOURNAL_READ_BOUNDS.defaultMaxBytes, JOURNAL_READ_BOUNDS.maxMaxBytes);
+		const kinds = journalKinds(a.kinds);
+		const matching = journalRows().filter((candidate) => candidate.row >= sinceRow && (!kinds || kinds.has(candidate.record.event.type)));
+		const entries = [];
+		let usedBytes = 2;
+		let index = 0;
+		let bounded = false;
+		for (; index < matching.length; index++) {
+			if (entries.length >= limit) {
+				bounded = true;
+				break;
+			}
+			const { record, event: _placeholder, ...stamp } = matching[index];
+			const row = {
+				...stamp,
+				event: redactedRow(record)
+			};
+			const bytes = Buffer.byteLength(safeJsonText(row), "utf8") + (entries.length === 0 ? 0 : 1);
+			if (usedBytes + bytes > maxBytes) {
+				bounded = true;
+				if (entries.length > 0) break;
+				const marker = {
+					...stamp,
+					event: { type: record.event.type },
+					oversize: {
+						type: record.event.type,
+						bytes
+					}
+				};
+				entries.push(marker);
+				usedBytes += Buffer.byteLength(safeJsonText(marker), "utf8");
+				index++;
+				break;
+			}
+			entries.push(row);
+			usedBytes += bytes;
+		}
+		const last = entries[entries.length - 1];
+		return {
+			entries,
+			nextRow: last === void 0 ? sinceRow : last.row + 1,
+			remaining: matching.length - index,
+			truncated: bounded,
+			bounds: {
+				sinceRow,
+				limit,
+				maxBytes,
+				usedBytes
+			},
+			priorRows: priorJournal.length
+		};
+	};
+	const definedAnalysts = [...opts.priorAnalystDefinitions ?? []];
+	const analystMenu = () => [...opts.analysts?.kinds ?? [], ...definedAnalysts.map((record) => record.kind)];
+	const maxDefinedAnalysts = opts.maxDefinedAnalysts ?? ANALYST_DEFINITION_BOUNDS.maxDefinitionsPerManager;
+	const defineAnalyst = async (raw) => {
+		const register = opts.analysts?.register;
+		if (register === void 0) return {
+			error: "authoring-unavailable",
+			reason: "this run's analyst registry admits no authored lens"
+		};
+		if (maxDefinedAnalysts > 0 && definedAnalysts.length >= maxDefinedAnalysts) return {
+			error: "max-defined-analysts",
+			reason: `you have defined ${definedAnalysts.length} lenses, the cap for this manager; run the ones you have instead of defining more`,
+			defined: definedAnalysts.map((record) => record.kind.id)
+		};
+		const parsed = parseAuthoredAnalystDefinition(raw);
+		if ("issues" in parsed) return {
+			error: "invalid-definition",
+			reason: parsed.issues.map((issue) => `${issue.path} ${issue.message}`).join("; "),
+			issues: parsed.issues
+		};
+		const { definition } = parsed;
+		const taken = analystMenu().find((kind) => kind.id === definition.id);
+		if (taken !== void 0) return {
+			error: "duplicate-analyst",
+			reason: `the lens id ${JSON.stringify(definition.id)} is already on the menu (${taken.description}); choose a different id or run the existing lens`
+		};
+		let kind;
+		try {
+			kind = await register(definition);
+		} catch (error) {
+			return {
+				error: "register-refused",
+				reason: error instanceof Error ? error.message : String(error)
+			};
+		}
+		const record = Object.freeze({
+			definition,
+			kind: Object.freeze({
+				id: kind.id,
+				description: kind.description,
+				area: kind.area
+			}),
+			digest: canonicalCandidateDigest(definition),
+			definedAt: Date.now()
+		});
+		definedAnalysts.push(record);
+		await bus.publish({
+			type: "analyst-defined",
+			analyst: record
+		}, { queue: false });
+		return {
+			analyst: record.kind,
+			digest: record.digest,
+			defined: definedAnalysts.length
+		};
+	};
 	const maxLiveWorkers = opts.maxLiveWorkers;
 	const localLiveWorkerCount = () => opts.scope.view.nodes.filter((n) => isLiveNodeStatus(n.status)).length;
 	const sharedWorkerCapacity = () => {
@@ -1207,14 +1633,16 @@ function createCoordinationTools(opts) {
 			handler: async (raw) => {
 				const a = obj(raw);
 				const key = a.key === void 0 ? void 0 : str(a.key, "key");
-				if (!(key !== void 0 && completedKeys.has(key)) && !usesTreeWideLimit() && maxLiveWorkers !== void 0 && maxLiveWorkers > 0 && liveWorkerCount() >= maxLiveWorkers) return Promise.resolve({
+				if (!(key !== void 0 && completedKeys.has(key)) && !usesTreeWideLimit() && maxLiveWorkers !== void 0 && maxLiveWorkers > 0 && liveWorkerCount() >= maxLiveWorkers) return Promise.resolve(((live) => ({
 					error: "max-live-workers",
-					live: liveWorkerCount(),
+					reason: `${live} worker${live === 1 ? " is" : "s are"} already live, which is this manager's ceiling — await_event until one settles, then spawn`,
+					live,
 					freeSlots: freeWorkerSlots()
-				});
+				}))(liveWorkerCount()));
 				const parsedProfile = agentProfileSchema.safeParse(a.profile);
 				if (!parsedProfile.success) return Promise.resolve({
 					error: "invalid-profile",
+					reason: `the profile you wrote is not a valid AgentProfile: ${parsedProfile.error.issues.map((issue) => `${issue.path.join(".") || "profile"} ${issue.message}`).join("; ")}`,
 					issues: parsedProfile.error.issues.map((issue) => ({
 						path: issue.path.join("."),
 						message: issue.message
@@ -1224,6 +1652,7 @@ function createCoordinationTools(opts) {
 				const continuity = resolveContinuity(parseContinuity(a.continuity), profile.name, key);
 				if ("error" in continuity) return Promise.resolve({
 					error: continuity.error,
+					reason: continuity.hint,
 					hint: continuity.hint,
 					live: liveWorkerCount(),
 					freeSlots: freeWorkerSlots()
@@ -1241,6 +1670,7 @@ function createCoordinationTools(opts) {
 						preflightCounts[refusal.cause] += 1;
 						return {
 							error: "preflight-refused",
+							reason: `the spawn pre-flight refused this profile (${refusal.cause}): ${refusal.detail}`,
 							cause: refusal.cause,
 							detail: refusal.detail,
 							live: liveWorkerCount(),
@@ -1306,6 +1736,7 @@ function createCoordinationTools(opts) {
 					...priorHistory
 				} : {
 					error: res.reason,
+					reason: res.reason === "usd-unbudgeted" ? "this run's root budget declares no maxUsd, so a child budget naming maxUsd can never be admitted at any amount — spawn with a budget that omits maxUsd" : `the conserved pool refused this spawn (${String(res.reason)}); the run has no allocation left to give this worker`,
 					...res.reason === "usd-unbudgeted" ? { hint: "This run's root budget declares no maxUsd, so a child budget naming maxUsd can never be admitted — at any amount. Retrying with a smaller maxUsd will fail identically. Spawn with a budget that omits maxUsd, or ask the caller to give the run a root maxUsd." } : {},
 					live: liveWorkerCount(),
 					freeSlots: freeWorkerSlots()
@@ -1325,7 +1756,10 @@ function createCoordinationTools(opts) {
 				const node = opts.scope.view.nodes.find((n) => n.id === id);
 				if (!node) {
 					const resumed = opts.scope.resume?.view.nodes.find((n) => n.id === id);
-					if (!resumed) return { error: `unknown workerId ${JSON.stringify(id)}` };
+					if (!resumed) return {
+						error: "unknown-worker",
+						reason: `no worker of this manager has the id ${JSON.stringify(id)}; spawn_worker returns the ids you may observe`
+					};
 					const output = resumed.outRef ? await opts.blobs.get(resumed.outRef) : void 0;
 					return {
 						...projectNodeEvidence(resumed, true),
@@ -1373,7 +1807,8 @@ function createCoordinationTools(opts) {
 				};
 				return {
 					delivered: false,
-					reason: delivery.outcome,
+					outcome: delivery.outcome,
+					reason: downMessageRefusalReasons[delivery.outcome],
 					progress: readProgress(workerId) ?? null
 				};
 			}
@@ -1453,7 +1888,7 @@ function createCoordinationTools(opts) {
 				if (typeof a.answer === "string" && a.answer.length > 0) {
 					const answer = a.answer;
 					const pendingQuestion = questions.find((question) => question.id === questionId);
-					if (pendingQuestion === void 0) throw new Error(`unknown questionId ${JSON.stringify(questionId)}`);
+					if (pendingQuestion === void 0) return unknownQuestion(questionId);
 					const interrupt = pendingQuestion.urgency === "blocks-run" || pendingQuestion.urgency === "blocks-step";
 					const authorized = authorizeInstruction("answer", pendingQuestion.from, answer, interrupt, questionId);
 					await recordInstruction(authorized);
@@ -1469,23 +1904,44 @@ function createCoordinationTools(opts) {
 							by: typeof a.by === "string" && a.by.length > 0 ? a.by : "user"
 						}) : pendingQuestion,
 						delivered: delivery.delivered,
-						...delivery.delivered ? {} : { reason: delivery.outcome }
+						...delivery.delivered ? {} : {
+							outcome: delivery.outcome,
+							reason: downMessageRefusalReasons[delivery.outcome]
+						}
 					};
 				}
-				if (typeof a.deferReason === "string" && a.deferReason.length > 0) return Promise.resolve({ question: decideQuestion(questionId, {
-					kind: "defer",
-					reason: a.deferReason
-				}) });
+				if (typeof a.deferReason === "string" && a.deferReason.length > 0) {
+					if (!questions.some((question) => question.id === questionId)) return Promise.resolve(unknownQuestion(questionId));
+					return Promise.resolve({ question: decideQuestion(questionId, {
+						kind: "defer",
+						reason: a.deferReason
+					}) });
+				}
 				if (typeof a.escalateTo === "string" && a.escalateTo.length > 0) {
-					if (!isQuestionEscalationTarget(a.escalateTo)) throw new Error(`answer_question: escalateTo must be one of ${questionEscalationTargets.join(", ")}; received ${JSON.stringify(a.escalateTo)}`);
+					if (!isQuestionEscalationTarget(a.escalateTo)) return Promise.resolve({
+						error: "invalid-escalation-target",
+						reason: `escalateTo must be one of ${questionEscalationTargets.join(", ")}; received ${JSON.stringify(a.escalateTo)}`
+					});
+					if (!questions.some((question) => question.id === questionId)) return Promise.resolve(unknownQuestion(questionId));
 					const escalateReason = typeof a.escalateReason === "string" && a.escalateReason.length > 0 ? a.escalateReason : "driver escalated";
-					return Promise.resolve({ question: decideQuestion(questionId, {
+					const decided = decideQuestion(questionId, {
 						kind: "escalate",
 						to: a.escalateTo,
 						reason: escalateReason
-					}) });
+					});
+					if (a.escalateTo !== "parent") return Promise.resolve({ question: decided });
+					return escalate(decided).then((escalation) => ({
+						question: decided,
+						escalated: escalation.delivered,
+						outcome: escalation.delivered ? "queued-for-parent" : "no-parent",
+						reason: escalation.delivered ? `the question is held by ${escalation.to}` : escalation.reason,
+						...escalation.delivered ? {} : { guidance: "No inbox above this manager is configured to receive it, so nothing will route an answer back to you. The question stays on the run record for anyone watching. Do not BLOCK on it: answer_question it yourself, or answer_question with deferReason to record that it stays open." }
+					}));
 				}
-				throw new Error("answer_question: provide answer, deferReason, or escalateTo");
+				return Promise.resolve({
+					error: "no-decision",
+					reason: "a decision is required: pass `answer` to answer the question, `deferReason` to record that it stays open, or `escalateTo` to hand it further up"
+				});
 			}
 		},
 		{
@@ -1525,7 +1981,7 @@ function createCoordinationTools(opts) {
 			handler: async (raw) => {
 				const a = obj(raw);
 				const from = str(a.from, "from");
-				return { question: await emitNewQuestion(addQuestion({
+				const q = await emitNewQuestion(addQuestion({
 					from,
 					level: level(a.level),
 					question: str(a.question, "question"),
@@ -1535,7 +1991,15 @@ function createCoordinationTools(opts) {
 					kind: "escalate",
 					to: "parent",
 					reason: "asked parent"
-				})) };
+				}));
+				const escalation = await escalate(q);
+				return {
+					question: q,
+					escalated: escalation.delivered,
+					outcome: escalation.delivered ? "queued-for-parent" : "no-parent",
+					reason: escalation.delivered ? `the question is held by ${escalation.to}` : escalation.reason,
+					...escalation.delivered ? {} : { guidance: "Nobody above this manager received the question. It is journaled for the operator, and YOU are the last decider: answer_question it yourself, or answer_question with deferReason to record that it stays open. Do not wait for an answer." }
+				};
 			}
 		},
 		...deliverable ? [{
@@ -1561,14 +2025,17 @@ function createCoordinationTools(opts) {
 				if (!Object.hasOwn(a, "result")) throw new Error("submit_result: \"result\" is required");
 				const result = structuredClone(a.result);
 				let accepted = false;
+				let thrown;
 				try {
 					accepted = await deliverable.check(result) === true;
-				} catch {
+				} catch (error) {
 					accepted = false;
+					thrown = error instanceof Error ? error.message : String(error);
 				}
 				if (!accepted) return {
 					accepted: false,
-					stop: false
+					stop: false,
+					reason: thrown === void 0 ? `the independent check did not pass on this result${deliverable.describe ? `. Expected: ${deliverable.describe}` : ""}` : `the independent check THREW, so nothing was accepted: ${thrown}. This is a fault in the check, not necessarily in your result — report it rather than resubmitting unchanged`
 				};
 				if (submitted) return {
 					accepted: true,
@@ -1598,28 +2065,73 @@ function createCoordinationTools(opts) {
 			},
 			handler: (raw) => {
 				const blocking = blockingQuestionsForStop();
-				if (blocking.length) return Promise.resolve({
-					stopped: false,
-					error: "unresolved-blocking-questions",
-					questions: blocking
-				});
+				if (blocking.length) {
+					const unheard = blocking.filter((question) => escalations.some((record) => record.questionId === question.id && record.delivered === false));
+					return Promise.resolve({
+						stopped: false,
+						error: "unresolved-blocking-questions",
+						reason: `${blocking.length} blocking question${blocking.length === 1 ? "" : "s"} ${blocking.length === 1 ? "is" : "are"} still undecided` + (unheard.length > 0 ? `, and ${unheard.length} of them reached no parent — nothing above this manager will answer ${unheard.length === 1 ? "it" : "them"}. Decide ${unheard.length === 1 ? "it" : "them"} with answer_question (answer, or deferReason to record that it stays open) and stop again.` : ". Decide each with answer_question (answer, deferReason, or escalateTo) and stop again."),
+						questions: blocking,
+						...unheard.length > 0 ? { unheardQuestionIds: unheard.map((q) => q.id) } : {}
+					});
+				}
 				stopped = true;
 				const r = obj(raw).reason;
 				reason = typeof r === "string" ? r : void 0;
 				notifyStop();
 				return Promise.resolve({ stopped: true });
 			}
+		},
+		{
+			name: "read_journal",
+			description: [
+				"Re-read YOUR OWN coordination journal: every spawn you made, every worker that settled,",
+				"every question raised or decided, every steer you authorized, and every analyst finding —",
+				"oldest first, on this node only, including what you did before a restart. Read it before",
+				"deciding what to do next, so you can see what you already tried. Bounded: page with the",
+				"returned `nextRow`, and check `truncated` before concluding you have read everything."
+			].join(" "),
+			inputSchema: {
+				type: "object",
+				properties: {
+					sinceRow: {
+						type: "integer",
+						minimum: 0,
+						description: "First journal row to return (inclusive, 0 = the first record of the run). Pass the previous call’s `nextRow` to continue."
+					},
+					kinds: {
+						type: "array",
+						items: {
+							type: "string",
+							enum: [...journalEventKinds]
+						},
+						description: "Return only these event kinds. Omit for every kind."
+					},
+					limit: {
+						type: "integer",
+						minimum: 1,
+						description: `Maximum rows to return. Default ${JOURNAL_READ_BOUNDS.defaultLimit}; anything above ${JOURNAL_READ_BOUNDS.maxLimit} is clamped to it.`
+					},
+					maxBytes: {
+						type: "integer",
+						minimum: 1,
+						description: `Byte budget for the returned rows. Default ${JOURNAL_READ_BOUNDS.defaultMaxBytes}; anything above ${JOURNAL_READ_BOUNDS.maxMaxBytes} is clamped to it.`
+					}
+				},
+				additionalProperties: false
+			},
+			handler: async (raw) => readJournal(raw)
 		}
 	];
 	if (opts.analysts) {
 		tools.push({
 			name: "list_analysts",
-			description: "List trace-analyst lenses available to run over a settled worker.",
+			description: "List trace-analyst lenses available to run over a settled worker — the ones this run was given plus any you defined with define_analyst.",
 			inputSchema: {
 				type: "object",
 				properties: {}
 			},
-			handler: () => Promise.resolve({ analysts: opts.analysts?.kinds })
+			handler: () => Promise.resolve({ analysts: analystMenu() })
 		});
 		tools.push({
 			name: "run_analyst",
@@ -1639,8 +2151,14 @@ function createCoordinationTools(opts) {
 				const a = obj(raw);
 				const id = str(a.workerId, "workerId");
 				const node = nodeForWorker(id);
-				if (!node) return { error: `unknown workerId ${JSON.stringify(id)}` };
-				if (isLiveNodeStatus(node.status)) return { error: `worker ${JSON.stringify(id)} has not settled — no trace to analyze yet` };
+				if (!node) return {
+					error: "unknown-worker",
+					reason: `no worker of this manager has the id ${JSON.stringify(id)}; spawn_worker returns the ids you may analyze`
+				};
+				if (isLiveNodeStatus(node.status)) return {
+					error: "worker-not-settled",
+					reason: `worker ${JSON.stringify(id)} has not settled, so it has no trace to analyze yet — await_event until it settles, then run the lens`
+				};
 				const trace = ledger.find((worker) => worker.id === id)?.trace ?? node.trace ?? {
 					status: "unavailable",
 					reason: "legacy-settlement-without-trace-evidence"
@@ -1650,13 +2168,105 @@ function createCoordinationTools(opts) {
 					store = await workerTraceAnalysisStore(trace, opts.blobs);
 				} catch (error) {
 					return {
-						error: error instanceof Error ? error.message : String(error),
+						error: "trace-unreadable",
+						reason: `the settled worker's trace evidence could not be read: ${error instanceof Error ? error.message : String(error)}`,
 						trace
 					};
 				}
-				return { findings: await opts.analysts?.run(str(a.kind, "kind"), store) };
+				const kind = str(a.kind, "kind");
+				if (!analystMenu().some((entry) => entry.id === kind)) return {
+					error: "unknown-analyst",
+					reason: `no lens named ${JSON.stringify(kind)} is on this manager's menu; call list_analysts to see what you may run`
+				};
+				return { findings: await opts.analysts?.run(kind, store) };
 			}
 		});
+		if (opts.analysts.register) tools.push({
+			name: "define_analyst",
+			description: [
+				"Define a NEW trace-analyst lens for this run, then run it with run_analyst like any",
+				"other. You write the research question, the policy for answering it, which trace tools",
+				"it may use, and the model seat — data only, never code. The definition is journaled, so",
+				"the lens you invented is reproducible and attributed to you."
+			].join(" "),
+			inputSchema: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						description: "Stable lens id: lowercase letters, digits and hyphens, 2-64 characters. It is the `kind` you pass to run_analyst and the analyst_id on every finding."
+					},
+					description: {
+						type: "string",
+						description: `One line naming what this lens looks for. At most ${ANALYST_DEFINITION_BOUNDS.maxDescriptionChars} characters.`
+					},
+					area: {
+						type: "string",
+						description: "The finding area this lens reports under, e.g. coordination, tool-use, cost."
+					},
+					question: {
+						type: "string",
+						description: `The research question, in your own words. At most ${ANALYST_DEFINITION_BOUNDS.maxQuestionChars} characters.`
+					},
+					instructions: {
+						type: "string",
+						description: `How to answer it: evidence rules, what counts as a finding, what to refuse to infer. At most ${ANALYST_DEFINITION_BOUNDS.maxInstructionsChars} characters.`
+					},
+					toolGroup: {
+						type: "string",
+						enum: [...analystToolGroupNames],
+						description: "Smallest trace-tool set that can answer the question. discovery = overview/query/count only; discoveryAndRead adds deep reads; discoveryAndSearch adds regex; targeted and singleTrace narrow further; all grants every trace tool."
+					},
+					model: {
+						type: "string",
+						description: "The model seat this lens should run on. Omit for the run default. It is a request: registration may refuse a seat this run cannot serve."
+					},
+					limits: {
+						type: "object",
+						properties: {
+							maxIterations: {
+								type: "integer",
+								minimum: 1,
+								maximum: ANALYST_DEFINITION_BOUNDS.maxIterations
+							},
+							maxLlmCalls: {
+								type: "integer",
+								minimum: 1,
+								maximum: ANALYST_DEFINITION_BOUNDS.maxLlmCalls
+							},
+							maxToolCalls: {
+								type: "integer",
+								minimum: 1,
+								maximum: ANALYST_DEFINITION_BOUNDS.maxToolCalls
+							},
+							maxOutputChars: {
+								type: "integer",
+								minimum: 1,
+								maximum: ANALYST_DEFINITION_BOUNDS.maxOutputChars
+							}
+						},
+						additionalProperties: false,
+						description: "Investigation ceilings. Values above the maximum are clamped, not refused."
+					},
+					minimumEvidenceCitations: {
+						type: "integer",
+						minimum: 1,
+						maximum: ANALYST_DEFINITION_BOUNDS.maxEvidenceCitations,
+						description: "Distinct evidence citations required per finding. Default 1."
+					}
+				},
+				required: [
+					"id",
+					"description",
+					"area",
+					"question",
+					"instructions",
+					"toolGroup"
+				],
+				additionalProperties: false
+			},
+			handler: async (raw) => defineAnalyst(raw)
+		});
 	}
 	const abortWorker = (ref, reason) => {
 		const live = opts.scope.view.nodes.filter((node) => isLiveNodeStatus(node.status));
@@ -1688,6 +2298,8 @@ function createCoordinationTools(opts) {
 		submittedResult: () => submitted,
 		settled: () => ledger,
 		questions: () => questions,
+		escalations: () => escalations,
+		definedAnalysts: () => definedAnalysts,
 		drainResolved,
 		abortWorker,
 		...peerMail ? { peerMail } : {}
@@ -1785,6 +2397,8 @@ var FileCoordinationLog = class {
 		}
 		const byId = /* @__PURE__ */ new Map();
 		const findings = [];
+		const escalations = [];
+		const analystDefinitions = [];
 		const continuations = [];
 		const deliveryEvidence = [];
 		const mail = [];
@@ -1822,11 +2436,15 @@ var FileCoordinationLog = class {
 				});
 			} else if (ev.type === "instruction") continuations.push(ev.instruction);
 			else if (ev.type === "mail") mail.push(ev.mail);
+			else if (ev.type === "escalation") escalations.push(ev.escalation);
+			else if (ev.type === "analyst-defined") analystDefinitions.push(ev.analyst);
 		}
 		return {
 			...ownerId !== void 0 ? { ownerId } : {},
 			questions: [...byId.values()],
 			findings,
+			escalations,
+			analystDefinitions,
 			continuations,
 			deliveryEvidence,
 			mail,
@@ -1839,6 +2457,8 @@ function emptyPriorCoordination(ownerId) {
 		...ownerId !== void 0 ? { ownerId } : {},
 		questions: [],
 		findings: [],
+		escalations: [],
+		analystDefinitions: [],
 		continuations: [],
 		deliveryEvidence: [],
 		mail: [],
@@ -2447,6 +3067,15 @@ function createSteerAcknowledger(deps) {
 		}
 	} };
 }
+/**
+* The OPERATOR-facing sentence for a steer outcome, written into the durable acknowledgement file.
+*
+* Deliberately separate from `downMessageRefusalReasons`, which is the MANAGER-facing sentence: one
+* says what happened for someone reading the run afterwards, the other tells a model what to do
+* next, and merging them would make one audience read the other's copy. They must nonetheless cover
+* the SAME outcomes, so `tests/kernel/refusal-reasons.test.ts` holds both maps total over
+* `DownMessageDeliveryOutcome` — a new code cannot land in only one.
+*/
 function steerAcknowledgementDetail(outcome) {
 	switch (outcome.outcome) {
 		case "delivered": return "the owning manager delivered the steer to the exact live worker";
@@ -2753,9 +3382,13 @@ function driverAgent(opts) {
 				...opts.continuityByProfile ? { continuityByProfile: opts.continuityByProfile } : {},
 				...opts.preflightSpawn ? { preflightSpawn: opts.preflightSpawn } : {},
 				...opts.resolveSpawnProfile ? { resolveSpawnProfile: opts.resolveSpawnProfile } : {},
+				...opts.escalateQuestion ? { escalateQuestion: opts.escalateQuestion } : {},
 				...opts.onEvent ? { onEvent: opts.onEvent } : {},
 				...opts.replaySettlements ? { replaySettlements: true } : {},
-				...opts.priorCoordination?.questions.length ? { priorQuestions: opts.priorCoordination.questions } : {}
+				...opts.priorCoordination?.questions.length ? { priorQuestions: opts.priorCoordination.questions } : {},
+				...opts.priorCoordination?.escalations?.length ? { priorEscalations: opts.priorCoordination.escalations } : {},
+				...opts.priorCoordination?.records.length ? { priorJournal: opts.priorCoordination.records } : {},
+				...opts.priorCoordination?.analystDefinitions?.length ? { priorAnalystDefinitions: opts.priorCoordination.analystDefinitions } : {}
 			});
 			await coord.ready();
 			opts.onCoordinationTools?.(coord.tools);
@@ -3066,6 +3699,6 @@ function errMessage(e) {
 	return e instanceof Error ? e.message : String(e);
 }
 //#endregion
-export { coordinationVerbNames as C, createEventBus as D, questionEscalationTargets as E, defaultToolDetectors as O, canonicalFindingEvent as S, normalizeAnalyzeOnSettle as T, renderAnytimeTable as _, allOf as a, FileCoordinationLog as b, createProgressTracker as c, progressStop as d, sampleFromSettled as f, plateauLength as g, bestSoFar as h, finalizeBestDelivered as i, watchTrace as k, noProgressFor as l, areaUnderCurve as m, createSteerAcknowledger as n, allWorkersStalled as o, anytimeReport as p, driverAgent as r, anyOf as s, createCancelAcknowledger as t, plateau as u, createFileRunContext as v, createCoordinationTools as w, DEFAULT_AWAIT_EVENT_TIMEOUT_MS as x, createInMemoryRunContext as y };
+export { questionEscalationTargets as A, analystToolGroupNames as C, downMessageRefusalReasons as D, createCoordinationTools as E, defaultToolDetectors as M, watchTrace as N, normalizeAnalyzeOnSettle as O, DEFAULT_AWAIT_EVENT_TIMEOUT_MS as S, coordinationVerbNames as T, renderAnytimeTable as _, allOf as a, FileCoordinationLog as b, createProgressTracker as c, progressStop as d, sampleFromSettled as f, plateauLength as g, bestSoFar as h, finalizeBestDelivered as i, createEventBus as j, parseAuthoredAnalystDefinition as k, noProgressFor as l, areaUnderCurve as m, createSteerAcknowledger as n, allWorkersStalled as o, anytimeReport as p, driverAgent as r, anyOf as s, createCancelAcknowledger as t, plateau as u, createFileRunContext as v, canonicalFindingEvent as w, ANALYST_DEFINITION_BOUNDS as x, createInMemoryRunContext as y };
 
-//# sourceMappingURL=coordination-driver-Da1IGdTP.js.map
+//# sourceMappingURL=coordination-driver-Bw0Prnim.js.map