@tangle-network/agent-runtime 0.105.0 → 0.106.0

package/dist/structural-rollout-IXUEplky.js

@@ -0,0 +1,1445 @@
+import { i as InMemorySpawnJournal, r as InMemoryResultBlobStore } from "./spawn-journal-CwPvKUTa.js";
+import { C as routerToolLoop, i as withDriverExecutor, t as createSupervisor } from "./supervisor-DTKhF-RV.js";
+import { createChatClient, estimateCost, isModelPriced, makeFinding } from "@tangle-network/agent-eval";
+import { randomBytes } from "node:crypto";
+//#region src/improvement/optimizer-prompt.ts
+/**
+* The senior scientific-method optimizer doctrine — the ONE substantial prompt
+* core shared by every builder/author surface (tool build, MCP build, codebase
+* improvement, strategy authoring) and by the driver that steers build workers
+* (`driverLoopGenerator`).
+*
+* Seeded from the proven senior prompts rather than invented: GEPA's
+* `REFLECTION_SYSTEM` (localize → diagnose → minimal generalizable fix →
+* preserve what works), the /evolve loop (one hypothesis with a mechanism and a
+* falsifiable prediction; attack the largest measured gap first), /pursue (one
+* coherent change set, no partial scaffolding), and the self-improving-loop /
+* supervisor doctrine (a keep is decided by a real check, never by the author;
+* observe → rate → decide). Generalized from "mutate a prompt string" to
+* "build a code surface a held-out measurement will grade".
+*/
+/**
+* The shared method block every build/author prompt embeds. Domain framing
+* (what a tool/MCP/codebase-edit deliverable looks like) wraps around it; this
+* is the process itself.
+*/
+const optimizerMethod = [
+	"THE METHOD — you are a senior engineer-scientist improving a measured system, not a code",
+	"generator. Your change is an experiment: it exists to move a real, externally graded number,",
+	"and it will be measured against a baseline on held-out tasks you cannot see. Work in this order:",
+	"",
+	"1. DIAGNOSE FIRST. Read every finding before touching anything — findings are ranked evidence",
+	"   from real failed runs. Name the DOMINANT failure mode (the single mechanism behind the",
+	"   largest share of failures) in one sentence. Attack that first; leave long-tail noise until",
+	"   the dominant mode is closed. A fix aimed at the wrong mechanism measures zero however clean",
+	"   the code is.",
+	"2. STATE A HYPOTHESIS WITH A PREDICTED LIFT. Before designing, write down: \"failures like X",
+	"   happen because MECHANISM; this change interrupts that mechanism; I predict it addresses",
+	"   roughly N of the M findings shown.\" A change you cannot connect to a mechanism is a guess,",
+	"   not an experiment.",
+	"3. DECOMPOSE INTO SUB-GOALS. Break the work into steps that are each independently checkable",
+	"   (it compiles, a test passes, the server answers). Sequence them so the riskiest assumption",
+	"   is tested first — if the hypothesis is wrong, find out on step 1, not step 5.",
+	"4. DESIGN TO ISOLATE THE MECHANISM. Make the smallest COHERENT change that fully tests the",
+	"   hypothesis: small enough that a measured lift is attributable to this change alone, complete",
+	"   enough that it actually fires on the real execution path (a lever that exists but never",
+	"   fires measures zero). No drive-by refactors, no unrelated cleanup, no speculative scope —",
+	"   anything changed alongside confounds the measurement.",
+	"5. GENERALIZE, NEVER MEMORIZE. Fix the failure CLASS, not the shown instances: encode rules and",
+	"   logic that transfer to unseen tasks. A patch memorized to the quoted examples will not",
+	"   survive the held-out measurement — that is overfitting, and the gate will catch it.",
+	"6. PRESERVE WHAT WORKS. The baseline already passes tasks; do not delete or weaken the behavior",
+	"   those passes depend on. A fix that trades one failure class for a new one measures as noise.",
+	"7. VERIFY FOR REAL, THEN REFLECT. Run the verification you were given and make it genuinely",
+	"   pass — never weaken a check, stub the thing it exercises, or special-case its inputs; a",
+	"   gamed check delivers nothing because promotion is decided by a separate measurement you",
+	"   never see. Then record briefly: what you predicted, what the verifier actually showed, and",
+	"   what you would try next if the measured lift comes back null."
+].join("\n");
+/**
+* The driver's stance for `driverLoopGenerator` — the build-domain instance of
+* the supervisor doctrine (observe → rate → decide; refine / re-scope /
+* decompose; the check decides delivery, never the driver's prose).
+*/
+const buildDriverSystem = [
+	"You are the DRIVER of a build loop: a senior engineering lead steering a coding WORKER inside",
+	"an isolated git worktree toward a verified artifact. You never edit files yourself — your only",
+	"levers are the tools below. Your intelligence goes into three places: how you AUTHOR each",
+	"worker instruction, how you OBSERVE and RATE what a session actually produced, and what you",
+	"DECIDE next.",
+	"",
+	"TOOLS",
+	"- run_worker{instruction}: one full coding-harness session in the worktree, with your",
+	"  instruction as its entire goal. Sessions are expensive and capped — author each one well.",
+	"  The worktree PERSISTS between sessions: a later worker resumes on top of earlier edits.",
+	"- inspect_worktree{}: current git status + diff — what has actually changed so far.",
+	"- read_file{path,maxBytes?}: read one file from the worktree (new untracked files do not show",
+	"  in the diff — read them to rate the work).",
+	"- run_verifier{}: the intrinsic check of the surface (compile+tests for a tool, boot-and-probe",
+	"  for an MCP server). Its exit decides what counts as delivered — your opinion does not.",
+	"",
+	"AUTHOR RICHLY. A worker handed a one-line label will flail. Each instruction must carry: the",
+	"outcome in concrete terms; the hypothesis and sub-goal it serves; what already exists in the",
+	"tree that it must build on, not duplicate; where the deliverable must land; and the exact check",
+	"it will be held to. The worker sees NOTHING you were given (no findings, no method, no prior",
+	"session context) unless you fold it into the instruction.",
+	"",
+	"THE LOOP — every turn: observe, rate, decide.",
+	"- OBSERVE: after each session, inspect the worktree and run the verifier. Read WHAT failed and",
+	"  WHY — \"it failed\" alone tells you nothing.",
+	"- RATE: judge with a reason. Verified and complete → stop. Close, one correctable fault →",
+	"  REFINE: author \"continue from the current tree; the check fails because X; fix X\" (depth,",
+	"  not a fresh start — never let a worker revert its own near-miss). Empty tree, or it solved a",
+	"  different problem → RE-SCOPE: re-author narrower and more concrete; a second identical",
+	"  instruction fails identically. Too big for one session → DECOMPOSE: author the first",
+	"  self-contained slice, verify it, then author the next on top.",
+	"- DECIDE: exactly one move per turn, with the reason stated in one line.",
+	"",
+	"STOP when the verifier passes — reply with no tool call and a short reflection: what you",
+	"predicted, what the verifier showed, what you would try next if the measured lift comes back",
+	"null. If the session budget runs out first, say plainly what remains and why. An honest",
+	"no-winner is a real result; a claimed success is not — the final keep/discard decision is made",
+	"by code from the verifier exit and the tree state, never from your words."
+].join("\n");
+/**
+* The driver's ADOPT-not-build doctrine, appended to `buildDriverSystem` when
+* a `research` tool is wired into the loop (`DriverLoopGeneratorOptions.
+* research`). Kept separate so a driver WITHOUT the tool is never told to
+* call a tool it does not have.
+*/
+const researchDriverNote = [
+	"RESEARCH — ADOPT BEFORE BUILD. A research{query} tool is provisioned for this run. Before",
+	"authoring a from-scratch build, spend one turn researching whether an EXISTING external MCP",
+	"server already provides the missing capability — registries and vendor docs list maintained",
+	"servers for most common gaps (web search, fetch, GitHub, filesystems, databases).",
+	"- If a maintained server fits, ADOPT it: report in your final reflection its endpoint or",
+	"  launch command and the API key it needs BY NAME (e.g. EXA_API_KEY) — never a key value —",
+	"  so the dispatch can emit a connection candidate with provisioned secrets. Adopting a fit",
+	"  server beats rebuilding it: less code to verify, maintained upstream, same measured gate.",
+	"- If nothing fits (unmaintained, wrong tool surface, heavier than the gap), build — and state",
+	"  in one line why adoption lost."
+].join("\n");
+/**
+* The senior authoring process for `authorStrategy` — the same method, shaped
+* to the strategy contract (author-blind, conserved budget, one module out).
+*/
+const strategyAuthorMethod = [
+	"Work as a senior researcher, in this order:",
+	"1. DIAGNOSE: read the per-task losses above and name the DOMINANT failure mode in one sentence",
+	"   — the single mechanism behind the largest share of lost score (e.g. first attempts near-miss",
+	"   and never get corrected; fresh retries discard progress; one persona plateaus).",
+	"2. HYPOTHESIS + PREDICTED LIFT: state \"these losses happen because MECHANISM; the composition",
+	"   below interrupts it; I predict roughly +N on this environment at the same budget.\"",
+	"3. DESIGN TO ISOLATE THE MECHANISM: change ONE coordination mechanism relative to the baselines",
+	"   (carry vs fresh, where the critique lands, a persona split, a tool restriction) so any",
+	"   measured lift is attributable to it. Do not stack three clever ideas — a tangled win teaches",
+	"   nothing and a tangled loss cannot be debugged.",
+	"4. DECOMPOSE THE BUDGET: plan how the shots divide across explore / attempt / critique / repair",
+	"   before writing code, and spend the whole budget — an early stop on a mid score is a loss.",
+	"5. GENERALIZE: the strategy runs on unseen tasks from this environment. Read tools via",
+	"   listTools(handle), never hardcode task specifics from the losses shown.",
+	"6. PREDICT, THEN REFLECT: put the hypothesis, the mechanism, and the predicted lift in a",
+	"   comment at the top of the module — the holdout verdict will be read against it."
+].join("\n");
+//#endregion
+//#region src/runtime/observe.ts
+/**
+* The third-person observer — the connective tissue that closes the loop.
+*
+* A driver spawns a worker; the worker can't see itself. `observe` reads the
+* worker's TRACE (what it actually did — every tool call, cost, failure) and
+* produces two streams:
+*   - `findings` / `report` — fed back DOWN (a steer for the next attempt) and
+*     OUT (the operator-facing "what I noticed + what to change").
+*   - `learned` — durable facts written to the cross-run `Corpus` so the NEXT
+*     run starts smarter (the continuous half of "continuous self-improvement").
+*
+* Findings are TRACE-derived, never JUDGE-derived (`derived_from_judge:false`):
+* the observer reads behavior, never the acceptance verdict — the selector≠judge
+* firewall (docs/learning-flywheel.md). The observer is harness-agnostic: it
+* reads a trace + an output, so it watches opencode, codex, hermes, or a BYO
+* agent identically.
+*/
+const observerId = "observe/trace";
+/** The default observer instruction — exported so an optimizer can seed its population. */
+const defaultAnalystInstruction = "You are a third-person OBSERVER watching an AI agent work. You see its TRACE (what it did), not its grader. From the trace, name SPECIFIC, behavior-grounded findings: wasted/duplicated tool calls, thrash/retries, token/cost waste, missing verification, failure patterns. For each, a concrete recommended_action, and whether the AGENT (fix its skills/prompt/tools) or the OPERATOR (fix framing/decomposition/config) should act. Only claim what the trace shows. No findings if the run was clean.";
+/** Compact the trace into the lines the observer reasons over — tool calls,
+*  errors, and statuses, in order. Keeps the model call bounded + grounded. */
+function summarizeTrace(trace, maxLines) {
+	const lines = [];
+	for (const ev of trace) {
+		const e = ev;
+		const t = (e.type ?? "").toLowerCase();
+		const d = e.data ?? {};
+		const part = d.part ?? {};
+		if (part.type === "tool") lines.push(`tool:${part.tool}${part.state?.status ? `(${part.state.status})` : ""}`);
+		else if (t.includes("error")) lines.push(`ERROR: ${String(d.message ?? d.detail ?? "").slice(0, 200)}`);
+		else if (t === "status" && typeof d.status === "string") lines.push(`status:${d.status}`);
+		else if (t.includes("tool")) lines.push(`tool-event:${t}`);
+	}
+	const out = [];
+	for (const ln of lines) {
+		const m = out[out.length - 1]?.match(/^(.*?)(?: x(\d+))?$/);
+		if (m && m[1] === ln) out[out.length - 1] = `${ln} x${(Number(m[2]) || 1) + 1}`;
+		else out.push(ln);
+	}
+	return out.slice(0, maxLines).join("\n") || "(no tool/error events in trace)";
+}
+const findingsSchema = {
+	name: "observer_findings",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { findings: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					area: {
+						type: "string",
+						description: "tool-use | cost | verification | process | failure | latency"
+					},
+					severity: {
+						type: "string",
+						enum: [
+							"critical",
+							"high",
+							"medium",
+							"low",
+							"info"
+						]
+					},
+					claim: {
+						type: "string",
+						description: "what you OBSERVED in the trace (a fact, with the evidence)"
+					},
+					recommended_action: {
+						type: "string",
+						description: "the concrete change for the agent or operator"
+					},
+					audience: {
+						type: "string",
+						enum: ["agent", "operator"],
+						description: "who should act on this"
+					},
+					confidence: { type: "number" }
+				},
+				required: [
+					"area",
+					"severity",
+					"claim",
+					"recommended_action",
+					"audience",
+					"confidence"
+				]
+			}
+		} },
+		required: ["findings"]
+	}
+};
+/** The third-person trace analyst: read a worker's trace and produce steer findings for the next attempt plus durable `learned` facts for the cross-run corpus. */
+async function observe(input, opts) {
+	const traceSummary = summarizeTrace(input.trace, opts.maxTraceLines ?? 80);
+	const parsed = parseFindings((await opts.chat.chat({
+		...opts.model ? { model: opts.model } : {},
+		jsonSchema: findingsSchema,
+		messages: [{
+			role: "system",
+			content: opts.analystInstruction ?? "You are a third-person OBSERVER watching an AI agent work. You see its TRACE (what it did), not its grader. From the trace, name SPECIFIC, behavior-grounded findings: wasted/duplicated tool calls, thrash/retries, token/cost waste, missing verification, failure patterns. For each, a concrete recommended_action, and whether the AGENT (fix its skills/prompt/tools) or the OPERATOR (fix framing/decomposition/config) should act. Only claim what the trace shows. No findings if the run was clean."
+		}, {
+			role: "user",
+			content: `TASK: ${input.task}\n\nOUTCOME: ${input.outcome ?? "unknown"}\n\nFINAL OUTPUT (truncated):\n${input.output.slice(0, 1200)}\n\nTRACE (in order; "xN" = repeated):\n${traceSummary}`
+		}]
+	}, { ...opts.signal ? { signal: opts.signal } : {} })).content);
+	const producedAt = input.runId ? `${input.runId}` : observerId;
+	const findings = parsed.map((f) => makeFinding({
+		analyst_id: observerId,
+		area: `${f.area}`,
+		severity: f.severity,
+		claim: f.claim,
+		recommended_action: f.recommended_action,
+		confidence: typeof f.confidence === "number" ? f.confidence : .5,
+		evidence_refs: [],
+		derived_from_judge: false,
+		metadata: { audience: f.audience },
+		...input.runId ? { subject: input.runId } : {}
+	}));
+	const learned = [];
+	if (opts.corpus) for (const f of findings) {
+		const record = {
+			schemaVersion: "1.0.0",
+			id: f.finding_id,
+			runId: input.runId ?? observerId,
+			producedAt: f.produced_at ?? producedAt,
+			area: f.area,
+			claim: f.recommended_action ?? f.claim,
+			...f.claim ? { rationale: f.claim } : {},
+			tags: [...opts.tags ?? [], `audience:${f.metadata?.audience ?? "agent"}`],
+			confidence: f.confidence,
+			evidence: [{
+				kind: "finding",
+				uri: f.finding_id
+			}]
+		};
+		if ((await opts.corpus.append(record)).succeeded) learned.push(record);
+	}
+	return {
+		findings,
+		learned,
+		report: renderReport(findings)
+	};
+}
+function parseFindings(content) {
+	let obj;
+	try {
+		obj = JSON.parse(content);
+	} catch {
+		const m = content.match(/\{[\s\S]*\}/);
+		obj = m ? JSON.parse(m[0]) : { findings: [] };
+	}
+	const arr = obj.findings;
+	return Array.isArray(arr) ? arr : [];
+}
+/** Operator-facing report, split by who should act. The agent block is the
+*  steer; the operator block is the advice. */
+function renderReport(findings) {
+	if (findings.length === 0) return "✓ clean run — the observer found nothing to change.";
+	const audience = (f) => f.metadata?.audience ?? "agent";
+	const forAgent = findings.filter((f) => audience(f) === "agent");
+	const forOperator = findings.filter((f) => audience(f) === "operator");
+	const block = (title, fs) => fs.length === 0 ? "" : `**${title}**\n${fs.map((f) => `- [${f.severity}] ${f.claim}\n  → ${f.recommended_action ?? ""}`).join("\n")}\n`;
+	return [block("For the agent (fix skills / prompt / tools)", forAgent), block("For you (the operator)", forOperator)].filter(Boolean).join("\n");
+}
+//#endregion
+//#region src/runtime/strategy.ts
+/**
+* The general agentic primitive — sequential (depth) and parallel (breadth) over a shared,
+* checkable artifact, driven through the keystone Supervisor as one recursive `Agent.act`.
+*
+* The domain lives behind ONE seam — `AgenticSurface` (open an artifact, list tools, call a tool,
+* score the artifact, close it). EnterpriseOps implements it (seed a gym DB, MCP tools, SQL
+* verifier); Commit0/AppWorld/terminal-bench implement it the same way (a repo workspace, shell
+* tools, the test suite). The drivers below are domain-blind: they run over any surface.
+*
+* Two shapes, the agent's POMDP rollout as the unit:
+*  - DEPTH   one persistent artifact carried across shots. Each shot the agent works the tool loop;
+*            between shots a trace-analyst (selector≠judge: reads the trajectory, never the score)
+*            steers the resumed session toward what's unfinished. shot n stands on shot n-1's
+*            artifact state + history. This is continuation — long-horizon, same artifact.
+*  - BREADTH K independent artifacts, each a fresh rollout, the deployable verifier picks the best.
+*
+* Both are an `Agent` whose `act` spawns leaf shots through `scope.spawn` and reacts via
+* `scope.next()` — so the conserved budget pool meters them (equal-k by construction), the journal
+* records the tree, and the same primitive nests. `runAgentic` runs the chosen driver through
+* `createSupervisor().run`. The leaf (one shot over a handle) is resolved per-spawn from a
+* surface-closed registry — the open `Executor` seam, not bespoke per-benchmark glue.
+*/
+const taskNudge = "Use the available tools to bring the artifact to the required final state. Address EVERY distinct change the request implies. After each tool result, check what remains and continue. Re-read the values you set to confirm they took. Reply DONE only once every required change is made and verified.";
+/** One shot: run the agent's tool loop (≤ innerTurns) over the handle, mutating the artifact via
+*  `surface.call`, carrying `messages`. Returns the updated conversation + counts. */
+async function runShot(surface, _task, handle, tools, messages, opts, modelOverride) {
+	let toolErrors = 0;
+	const execute = async (name, args) => {
+		try {
+			const out = await surface.call(handle, name, args);
+			if (out.startsWith("ERROR:")) toolErrors += 1;
+			return out;
+		} catch (e) {
+			toolErrors += 1;
+			return `ERROR: ${e instanceof Error ? e.message : String(e)}`;
+		}
+	};
+	const r = await routerToolLoop({
+		routerBaseUrl: opts.routerBaseUrl,
+		routerKey: opts.routerKey,
+		model: modelOverride ?? opts.model,
+		...opts.complete ? { complete: opts.complete } : {}
+	}, "", "", tools, execute, {
+		maxTurns: opts.innerTurns ?? 4,
+		temperature: opts.temperature ?? .7,
+		initialMessages: messages,
+		...opts.maxTokens ? { maxTokens: opts.maxTokens } : {}
+	});
+	return {
+		messages: r.messages,
+		completions: r.turns,
+		toolCalls: r.toolCalls,
+		toolErrors,
+		tokens: r.usage
+	};
+}
+/** The firewall's input shape: the trajectory as compacted text — calls, results,
+*  assistant text. NEVER scores, NEVER check internals. Shared by both analyst channels. */
+function compactTrajectory(messages) {
+	return messages.filter((m) => m.role === "assistant" || m.role === "tool").map((m) => {
+		if (m.role === "tool") return `RESULT ${String(m.content).slice(0, 280)}`;
+		const calls = m.tool_calls?.map((c) => `${c.function.name}(${c.function.arguments})`).join(", ");
+		return calls ? `CALL ${calls}` : `SAY ${String(m.content).slice(0, 200)}`;
+	}).join("\n").slice(0, 7e3);
+}
+/** The analyst's chat seam: the live router by default, or — when a `complete` transport is
+*  injected — that SAME transport, so an offline run drives the critic with no network too (the
+*  worker and the analyst share the one injected responder, exactly as a localhost mock would
+*  serve both). The critic speaks the OpenAI request shape; we forward it to `complete` and lift
+*  the parsed `/chat/completions` JSON back into a `ChatResponse`. */
+function analystChat(opts, defaultModel) {
+	if (!opts.complete) return createChatClient({
+		transport: "router",
+		apiKey: opts.routerKey,
+		baseUrl: opts.routerBaseUrl,
+		defaultModel
+	});
+	const complete = opts.complete;
+	return createChatClient({
+		transport: "mock",
+		defaultModel,
+		handler: async (req) => {
+			const raw = await complete({
+				model: req.model ?? defaultModel,
+				messages: req.messages,
+				...req.temperature !== void 0 ? { temperature: req.temperature } : {},
+				...req.maxTokens !== void 0 ? { max_tokens: req.maxTokens } : {}
+			});
+			const content = raw.choices?.[0]?.message?.content ?? "";
+			const promptTokens = raw.usage?.prompt_tokens ?? 0;
+			const completionTokens = raw.usage?.completion_tokens ?? 0;
+			return {
+				content,
+				usage: {
+					promptTokens,
+					completionTokens,
+					totalTokens: promptTokens + completionTokens
+				},
+				costUsd: null,
+				model: req.model ?? defaultModel,
+				durationMs: 0,
+				finishReason: raw.choices?.[0]?.finish_reason ?? null,
+				contentEmpty: content.trim().length === 0,
+				raw
+			};
+		}
+	});
+}
+/** The RAW analyst channel: the firewalled critic answers `instruction` over the
+*  trajectory directly — no findings schema, no recommended-action extraction. The
+*  channel for verdict-shaped steering (budget controllers, calibrated predictions)
+*  whose output format the findings protocol would strip. Same firewall as analyze():
+*  trajectory in, never scores. */
+async function consultAnalyst(task, messages, instruction, opts) {
+	const trajectory = compactTrajectory(messages);
+	const analystModel = opts.analystModel ?? opts.model;
+	const chat = analystChat(opts, analystModel);
+	const consultMessages = trajectory ? [{
+		role: "system",
+		content: instruction
+	}, {
+		role: "user",
+		content: `TASK: ${task.userPrompt.slice(0, 1500)}\n\nTRAJECTORY:\n${trajectory}`
+	}] : [{
+		role: "user",
+		content: `${instruction}\n\nTASK:\n${task.userPrompt.slice(0, 1500)}`
+	}];
+	const res = await chat.chat({
+		model: analystModel,
+		temperature: .2,
+		maxTokens: 1024,
+		messages: consultMessages
+	});
+	const usage = res.usage;
+	return {
+		steer: res.content.trim(),
+		tokens: {
+			input: usage?.promptTokens ?? usage?.prompt_tokens ?? 0,
+			output: usage?.completionTokens ?? usage?.completion_tokens ?? 0
+		}
+	};
+}
+async function analyze(task, messages, opts) {
+	const trajectory = compactTrajectory(messages);
+	const analystModel = opts.analystModel ?? opts.model;
+	const inner = analystChat(opts, analystModel);
+	const tokens = {
+		input: 0,
+		output: 0
+	};
+	const chat = {
+		...inner,
+		chat: async (req, callOpts) => {
+			const res = await inner.chat(req, callOpts);
+			const u = res.usage;
+			if (u) {
+				tokens.input += u.promptTokens ?? u.prompt_tokens ?? 0;
+				tokens.output += u.completionTokens ?? u.completion_tokens ?? 0;
+			}
+			return res;
+		}
+	};
+	return {
+		steer: (await observe({
+			task: task.userPrompt,
+			output: trajectory,
+			trace: messages,
+			outcome: "failed",
+			runId: task.id
+		}, {
+			chat,
+			model: analystModel,
+			...opts.analystInstruction ? { analystInstruction: opts.analystInstruction } : {},
+			...opts.corpus ? {
+				corpus: opts.corpus,
+				tags: opts.corpusTags ?? []
+			} : {}
+		})).findings.map((f) => f.recommended_action).filter((a) => typeof a === "string" && a.trim().length > 0).join("\n").trim() || "COMPLETE",
+		tokens
+	};
+}
+async function renderCorpusReadback(opts) {
+	if (!opts.corpus || !opts.corpusReadback) return "";
+	const maxFacts = opts.corpusReadback.maxFacts ?? 3;
+	if (!Number.isInteger(maxFacts) || maxFacts < 0) throw new Error(`corpusReadback.maxFacts must be a non-negative integer, got ${maxFacts}`);
+	if (maxFacts === 0) return "";
+	const tags = [
+		...opts.corpusTags ?? [],
+		...opts.corpusReadback.tags ?? [],
+		...opts.corpusReadback.includeOperatorFacts ? [] : ["audience:agent"]
+	];
+	const facts = await opts.corpus.query({
+		...tags.length > 0 ? { tags } : {},
+		minConfidence: opts.corpusReadback.minConfidence ?? .7,
+		limit: maxFacts
+	});
+	if (facts.length === 0) return "";
+	return `Relevant learned facts from prior attempts:\n${facts.map((fact) => fact.rationale ? `- ${fact.claim} (${fact.rationale})` : `- ${fact.claim}`).join("\n")}`;
+}
+/** Resolve a shot: if `handle` given, operate on the SHARED artifact (depth); else open+score+close
+*  an OWN artifact (breadth). Always scores the artifact's final state as the deployable verdict. */
+function shotExecutor(surface, opts) {
+	let artifact;
+	return {
+		runtime: "agentic-shot",
+		async execute(task) {
+			const t = task;
+			const own = !t.handle;
+			const handle = t.handle ?? await surface.open(t.task);
+			try {
+				const allTools = await surface.tools(t.task, handle);
+				let tools = allTools;
+				if (t.tools) {
+					const known = new Set(allTools.map((tool) => tool.function.name));
+					const unknown = t.tools.filter((name) => !known.has(name));
+					if (unknown.length > 0) throw new Error(`shot tools: unknown tool name(s) ${unknown.join(", ")} — domain offers: ${[...known].join(", ")}`);
+					const want = new Set(t.tools);
+					tools = allTools.filter((tool) => want.has(tool.function.name));
+				}
+				const messages = t.messages?.length ? t.messages : [{
+					role: "system",
+					content: t.persona?.systemPrompt ?? t.task.systemPrompt
+				}, {
+					role: "user",
+					content: `${t.task.userPrompt}\n\n${taskNudge}`
+				}];
+				if (t.messages?.length && t.persona?.systemPrompt) messages.push({
+					role: "user",
+					content: `[hand-off] You are now acting as: ${t.persona.systemPrompt}`
+				});
+				if (t.steer) messages.push({
+					role: "user",
+					content: t.steer
+				});
+				const shot = await runShot(surface, t.task, handle, tools, messages, opts, t.persona?.model);
+				const s = await surface.score(t.task, handle);
+				const score = s.total > 0 ? s.passes / s.total : 0;
+				const out = {
+					messages: shot.messages,
+					score,
+					passes: s.passes,
+					total: s.total,
+					completions: shot.completions,
+					toolErrors: shot.toolErrors
+				};
+				artifact = {
+					outRef: `shot:${handle.id}:${shot.completions}:${s.passes}/${s.total}`,
+					out,
+					verdict: {
+						valid: s.total > 0 && s.passes === s.total,
+						score
+					},
+					spent: {
+						iterations: shot.completions,
+						tokens: shot.tokens,
+						usd: isModelPriced(opts.model) ? estimateCost(shot.tokens.input, shot.tokens.output, opts.model) : 0,
+						ms: 0
+					}
+				};
+				return artifact;
+			} finally {
+				if (own) await surface.close(handle);
+			}
+		},
+		teardown: () => Promise.resolve({ destroyed: true }),
+		resultArtifact() {
+			if (!artifact) throw new Error("shotExecutor: resultArtifact before execute");
+			return artifact;
+		}
+	};
+}
+function analystExecutor(opts) {
+	let artifact;
+	return {
+		runtime: "agentic-analyst",
+		async execute(task) {
+			const t = task;
+			const { steer, tokens } = t.rawInstruction ? await consultAnalyst(t.task, t.messages, t.rawInstruction, opts) : await analyze(t.task, t.messages, opts);
+			const analystModel = opts.analystModel ?? opts.model;
+			artifact = {
+				outRef: `analyst:${steer.length}`,
+				out: steer,
+				spent: {
+					iterations: 1,
+					tokens,
+					usd: isModelPriced(analystModel) ? estimateCost(tokens.input, tokens.output, analystModel) : 0,
+					ms: 0
+				}
+			};
+			return artifact;
+		},
+		teardown: () => Promise.resolve({ destroyed: true }),
+		resultArtifact() {
+			if (!artifact) throw new Error("analystExecutor: resultArtifact before execute");
+			return artifact;
+		}
+	};
+}
+/**
+* Registry dispatching on the child's role tag — fresh executor per spawn (no
+* shared-instance race). `withDriverExecutor` wraps it so a `role:'driver'` child resolves
+* to the recursive driver-executor (a child that drives its OWN children — agents drive
+* agents) before this leaf dispatch; `shot`/`analyst` children resolve to their leaf
+* executors here unchanged.
+*/
+function agenticRegistry(surface, opts) {
+	return withDriverExecutor({
+		register() {
+			throw new Error("agenticRegistry: register unsupported");
+		},
+		resolve(spec) {
+			const role = spec.profile.metadata?.role;
+			const factory = (_s, _ctx) => role === "analyst" ? analystExecutor(opts) : shotExecutor(surface, opts);
+			return {
+				succeeded: true,
+				value: factory
+			};
+		}
+	});
+}
+function leaf(name, role) {
+	return {
+		name,
+		executorSpec: {
+			profile: {
+				name,
+				metadata: { role }
+			},
+			harness: null
+		},
+		act() {
+			throw new Error(`agentic: spawned child "${name}" was run directly (the executor drives it)`);
+		}
+	};
+}
+/** Drain exactly one settlement (the just-spawned child). */
+async function drainOne(scope) {
+	const s = await scope.next();
+	if (!s) throw new Error("agentic: spawned child never settled");
+	return s;
+}
+const perChild = (innerTurns) => ({
+	maxIterations: innerTurns + 1,
+	maxTokens: 1e6
+});
+/** DEPTH: one persistent artifact, carried across analyst-steered shots. */
+function depthStrategy(surface, task, opts, cfg) {
+	const innerTurns = opts.innerTurns ?? 4;
+	let pendingSteer;
+	return {
+		name: "depth",
+		async act(_t, scope) {
+			const handle = await surface.open(task);
+			const progression = [];
+			let messages;
+			let completions = 0;
+			let shots = 0;
+			try {
+				for (shots = 0; shots < cfg.maxShots; shots += 1) {
+					const child = leaf(`shot:${shots}`, "shot");
+					const memorySteer = await renderCorpusReadback(opts);
+					const steer = [shots === 0 ? void 0 : pendingSteer, memorySteer].filter((part) => typeof part === "string" && part.trim().length > 0).join("\n\n");
+					if (!scope.spawn(child, {
+						task,
+						handle,
+						messages,
+						steer
+					}, {
+						budget: perChild(innerTurns),
+						label: `shot:${shots}`
+					}).ok) break;
+					const settled = await drainOne(scope);
+					if (settled.kind === "down") break;
+					const out = settled.out;
+					messages = out.messages;
+					completions += out.completions;
+					progression.push(out.score);
+					if (out.score >= 1 || shots === cfg.maxShots - 1) break;
+					const aChild = leaf(`analyst:${shots}`, "analyst");
+					if (!scope.spawn(aChild, {
+						task,
+						messages
+					}, {
+						budget: perChild(1),
+						label: `analyst:${shots}`
+					}).ok) break;
+					const aSettled = await drainOne(scope);
+					completions += 1;
+					if (aSettled.kind === "down") break;
+					const findings = aSettled.out;
+					if (/^\s*COMPLETE\b/i.test(findings)) break;
+					pendingSteer = `A reviewer flagged unfinished items:\n${findings}\n\nAddress each with the tools, verify they took, then continue.`;
+				}
+				const final = await surface.score(task, handle);
+				return {
+					kind: "done",
+					deliverable: {
+						mode: "depth",
+						score: final.total > 0 ? final.passes / final.total : 0,
+						resolved: final.total > 0 && final.passes === final.total,
+						completions,
+						progression,
+						shots: shots + 1
+					}
+				};
+			} finally {
+				await surface.close(handle);
+			}
+		}
+	};
+}
+/** BREADTH: K independent rollouts (each own artifact), verifier picks the best. */
+function breadthStrategy(_surface, task, opts, cfg) {
+	const innerTurns = opts.innerTurns ?? 4;
+	return {
+		name: "breadth",
+		async act(_t, scope) {
+			let opened = 0;
+			for (let k = 0; k < cfg.width; k += 1) if (scope.spawn(leaf(`rollout:${k}`, "shot"), { task }, {
+				budget: perChild(innerTurns),
+				label: `rollout:${k}`
+			}).ok) opened += 1;
+			if (opened === 0) return {
+				kind: "blocked",
+				blockers: ["breadth: pool admitted no rollout"]
+			};
+			let best = -1;
+			let bestResolved = false;
+			let completions = 0;
+			const progression = [];
+			for (let s = await scope.next(); s !== null; s = await scope.next()) {
+				if (s.kind === "down") continue;
+				const out = s.out;
+				completions += out.completions;
+				if (out.score > best) best = out.score;
+				if (out.total > 0 && out.passes === out.total) bestResolved = true;
+				progression.push(best);
+			}
+			if (best < 0) return {
+				kind: "blocked",
+				blockers: ["breadth: every rollout went down"]
+			};
+			return {
+				kind: "done",
+				deliverable: {
+					mode: "breadth",
+					score: best,
+					resolved: bestResolved,
+					completions,
+					progression,
+					shots: opened
+				}
+			};
+		}
+	};
+}
+/** Built-in `Strategy`: K independent attempts, keep the best-verifying (best-of-N / resample). */
+const sample = {
+	name: "sample",
+	driver: (surface, task, opts, budget) => breadthStrategy(surface, task, opts, { width: budget })
+};
+/** Built-in `Strategy`: attempt → `observe()` reads the trace → steer the next attempt → repeat (deepen one lineage). */
+const refine = {
+	name: "refine",
+	driver: (surface, task, opts, budget) => depthStrategy(surface, task, opts, { maxShots: budget })
+};
+/** Author a Strategy from the composable steps — the open, compact way. */
+function defineStrategy(name, run) {
+	return {
+		name,
+		driver: (surface, task, opts, budget) => ({
+			name,
+			async act(_t, scope) {
+				let seq = 0;
+				const innerTurns = opts.innerTurns ?? 4;
+				let verifiedBest = 0;
+				let verifiedResolved = false;
+				const openHandles = /* @__PURE__ */ new Set();
+				const r = await run({
+					surface: {
+						name: surface.name,
+						open: async (t) => {
+							const h = await surface.open(t);
+							openHandles.add(h.id);
+							return h;
+						},
+						close: async (h) => {
+							if (!h || !openHandles.has(h.id)) return;
+							openHandles.delete(h.id);
+							await surface.close(h);
+						}
+					},
+					task,
+					opts,
+					budget,
+					scope,
+					async shot(spec) {
+						const child = leaf(`shot:${seq}`, "shot");
+						seq += 1;
+						if (!scope.spawn(child, {
+							task,
+							handle: spec?.handle,
+							messages: spec?.messages,
+							steer: spec?.steer,
+							persona: spec?.persona,
+							tools: spec?.tools
+						}, {
+							budget: perChild(innerTurns),
+							label: child.name
+						}).ok) return null;
+						const settled = await drainOne(scope);
+						if (settled.kind === "down") return null;
+						const out = settled.out;
+						if (out.score > verifiedBest) verifiedBest = out.score;
+						if (out.total > 0 && out.passes === out.total) verifiedResolved = true;
+						return out;
+					},
+					async listTools(handle) {
+						return (await surface.tools(task, handle)).map((t) => ({
+							name: t.function.name,
+							...t.function.description ? { description: t.function.description } : {}
+						}));
+					},
+					async critique(messages) {
+						const child = leaf(`analyst:${seq}`, "analyst");
+						seq += 1;
+						if (!scope.spawn(child, {
+							task,
+							messages
+						}, {
+							budget: perChild(1),
+							label: child.name
+						}).ok) return null;
+						const settled = await drainOne(scope);
+						if (settled.kind === "down") return null;
+						const findings = settled.out;
+						return /^\s*COMPLETE\b/i.test(findings) ? null : findings;
+					},
+					async consult(messages, instruction) {
+						const child = leaf(`analyst:${seq}`, "analyst");
+						seq += 1;
+						if (!scope.spawn(child, {
+							task,
+							messages,
+							rawInstruction: instruction
+						}, {
+							budget: perChild(1),
+							label: child.name
+						}).ok) return null;
+						const settled = await drainOne(scope);
+						if (settled.kind === "down") return null;
+						return settled.out;
+					}
+				});
+				return {
+					kind: "done",
+					deliverable: {
+						mode: name,
+						...r,
+						progression: Array.isArray(r.progression) ? r.progression : [],
+						completions: typeof r.completions === "number" ? r.completions : 0,
+						shots: typeof r.shots === "number" ? r.shots : 0,
+						score: verifiedBest,
+						resolved: verifiedResolved
+					}
+				};
+			}
+		})
+	};
+}
+/** A NEW strategy, authored from the steps (~20 lines): refine, but when a steered shot
+*  fails to improve the score it ABANDONS that line and restarts fresh (branch-when-stuck)
+*  — the widen/MCTS idea the depth-stuck failure motivated. Scored keep-best (the best
+*  checkpoint across all lines), the deployable metric. This is the "experts build BETTER
+*  optimizations" path: a new technique, compact, with zero Supervisor ceremony. */
+const adaptiveRefine = defineStrategy("adaptiveRefine", async ({ surface, task, budget, shot, critique }) => {
+	let handle = await surface.open(task);
+	const progression = [];
+	let messages;
+	let steer;
+	let completions = 0;
+	let best = -1;
+	let shots = 0;
+	try {
+		for (shots = 0; shots < budget; shots += 1) {
+			const out = await shot({
+				handle,
+				messages,
+				steer
+			});
+			if (!out) break;
+			completions += out.completions;
+			progression.push(out.score);
+			if (out.score >= 1) break;
+			if (out.score <= best) {
+				await surface.close(handle);
+				handle = await surface.open(task);
+				messages = void 0;
+				steer = void 0;
+				continue;
+			}
+			best = out.score;
+			messages = out.messages;
+			const findings = await critique(out.messages);
+			completions += 1;
+			if (!findings) break;
+			steer = `A reviewer flagged unfinished items:\n${findings}\n\nAddress each with the tools, verify they took, then continue.`;
+		}
+		const score = progression.length ? Math.max(...progression) : 0;
+		return {
+			score,
+			resolved: score >= 1,
+			completions,
+			progression,
+			shots
+		};
+	} finally {
+		await surface.close(handle);
+	}
+});
+/** The explore-then-exploit MIX: spend ⌈budget/2⌉ on independent samples (kept open),
+*  then refine the best-verifying line with the remaining budget. Sample's basin escape +
+*  refine's accumulation — the third built-in, authored from the public steps. */
+const sampleThenRefine = defineStrategy("sampleThenRefine", async ({ surface, task, budget, shot, critique }) => {
+	const explore = Math.max(1, Math.ceil(budget / 2));
+	const open = /* @__PURE__ */ new Set();
+	const progression = [];
+	let completions = 0;
+	let shots = 0;
+	try {
+		let best;
+		for (let i = 0; i < explore; i += 1) {
+			const handle = await surface.open(task);
+			open.add(handle);
+			const out = await shot({ handle });
+			if (!out) continue;
+			shots += 1;
+			completions += out.completions;
+			progression.push(out.score);
+			if (!best || out.score > best.out.score) best = {
+				handle,
+				out
+			};
+			if (out.score >= 1) break;
+		}
+		if (!best) return {
+			score: 0,
+			resolved: false,
+			completions,
+			progression,
+			shots
+		};
+		for (const h of [...open]) if (h !== best.handle) {
+			await surface.close(h);
+			open.delete(h);
+		}
+		let messages = best.out.messages;
+		let topScore = best.out.score;
+		for (let i = explore; i < budget && topScore < 1; i += 1) {
+			const findings = await critique(messages);
+			completions += 1;
+			if (!findings) break;
+			const out = await shot({
+				handle: best.handle,
+				messages,
+				steer: `A reviewer flagged unfinished items:\n${findings}\n\nAddress each with the tools, verify they took, then continue.`
+			});
+			if (!out) break;
+			shots += 1;
+			completions += out.completions;
+			progression.push(out.score);
+			messages = out.messages;
+			if (out.score > topScore) topScore = out.score;
+		}
+		const score = progression.length ? Math.max(...progression) : 0;
+		return {
+			score,
+			resolved: score >= 1,
+			completions,
+			progression,
+			shots
+		};
+	} finally {
+		for (const h of open) await surface.close(h);
+	}
+});
+/** Run a Strategy through the keystone Supervisor — `Agent.act` over a conserved-budget Scope. */
+async function runAgentic(opts) {
+	const strategy = opts.strategy ?? (opts.mode === "breadth" ? sample : refine);
+	const driver = strategy.driver(opts.surface, opts.task, opts, opts.budget);
+	const supervisor = createSupervisor();
+	const root = opts.rootBudget ?? {
+		maxIterations: opts.budget * ((opts.innerTurns ?? 4) + 2),
+		maxTokens: 1e9
+	};
+	const started = Date.now();
+	const result = await supervisor.run(driver, void 0, {
+		budget: root,
+		runId: `agentic:${strategy.name}:${opts.task.id}`,
+		journal: new InMemorySpawnJournal(),
+		blobs: new InMemoryResultBlobStore(),
+		executors: agenticRegistry(opts.surface, opts),
+		maxDepth: 3,
+		...opts.hooks ? { hooks: opts.hooks } : {}
+	});
+	if (result.kind !== "winner" || result.out.kind !== "done") {
+		const reason = result.kind === "winner" ? `blocked: ${result.out.blockers?.join("; ")}` : `no-winner: ${result.reason}`;
+		throw new Error(`runAgentic(${strategy.name}) produced no result — ${reason}`);
+	}
+	return {
+		...result.out.deliverable,
+		usd: result.spentTotal.usd,
+		tokens: result.spentTotal.tokens,
+		ms: Date.now() - started
+	};
+}
+//#endregion
+//#region src/runtime/structural-rollout.ts
+/**
+* structuralRollout — the measured structural lever as a fourth member of the
+* sample/refine/sampleThenRefine strategy family: k independent samples, selection by
+* TASK-VISIBLE checks only, then a guarded self-repair loop steered by the checks'
+* failure output. Design: docs/design/structural-rollout-integration.md; measured basis
+* (bench/src/hev-structural.mts, bench/src/mbpp-structural.mts): +8.5..+21.3pp hidden-test
+* lift across Llama-3-8B/Qwen2.5-7B × HumanEval/MBPP, null only at saturation.
+*
+* Honesty invariants carried over from the proven rigs:
+*  - Visible checks are generated from task-visible information only, BEFORE any
+*    candidate exists, and FROZEN for every sample and repair round of the task.
+*  - OFFICIAL checks (shown in the task itself) rank lexicographically above
+*    model-AUTHORED guesses. This ordering is measured, not stylistic: authored guesses
+*    run 17–70% wrong depending on model × spec richness, and unweighted they flipped
+*    selection NEGATIVE on MBPP (6 noisy guesses outvoting the one reliable check).
+*  - A candidate that crashed before the checks could run ranks below one that ran and
+*    failed everything.
+*  - Repair sees ONLY the checks' failure output, and never displaces a candidate that
+*    passes more official checks with one that passes fewer (wrong visible examples
+*    poison repair at saturation — the glm /47,/116 regressions).
+*
+* Placement rule: this is an INFERENCE-TIME capability (it wraps the model call via the
+* strategy seam). It does not belong in `improve()` (training-time); `improve()`
+* may later tune `StructuralRolloutPolicy` as an optimizable surface.
+*/
+/** The measured default recipe: 5 samples, 2 guarded repair rounds, 6 authored checks. */
+const defaultStructuralRolloutPolicy = {
+	k: 5,
+	repairRounds: 2,
+	testgen: 6
+};
+function resolvePolicy(overrides) {
+	const policy = {
+		...defaultStructuralRolloutPolicy,
+		...overrides
+	};
+	if (!Number.isInteger(policy.k) || policy.k < 1) throw new Error(`structuralRollout: policy.k must be an integer >= 1, got ${policy.k}`);
+	if (!Number.isInteger(policy.repairRounds) || policy.repairRounds < 0) throw new Error(`structuralRollout: policy.repairRounds must be an integer >= 0, got ${policy.repairRounds}`);
+	if (!Number.isInteger(policy.testgen) || policy.testgen < 0) throw new Error(`structuralRollout: policy.testgen must be an integer >= 0, got ${policy.testgen}`);
+	return policy;
+}
+const authorInstruction = (count, entry) => `Read the task below. Write exactly ${count} single-line assert statements that test the function \`${entry}\`, based ONLY on the behavior the task itself describes. Each assert must be one physical line of the form \`assert ${entry}(...) == expected\` (or a True/False check). Do NOT implement the function. Do NOT copy shown examples verbatim if you can test other cases too. Output ONLY the assert lines inside a single \`\`\`python code block.`;
+/** The proven authored-assert filter (lifted from the rigs' generateTests): keep only
+*  single-line, paren-balanced asserts that reference the entry symbol — malformed lines
+*  are dropped here rather than poisoning every candidate's score identically. */
+function filterAuthoredAsserts(reply, entrySymbol, count) {
+	const fences = [...reply.matchAll(/```(?:python|py)?\s*\n([\s\S]*?)```/gi)].map((m) => (m[1] ?? "").trim());
+	const block = fences.length > 0 ? fences.join("\n") : reply;
+	const balanced = (s) => {
+		let d = 0;
+		for (const ch of s) {
+			if (ch === "(" || ch === "[" || ch === "{") d += 1;
+			else if (ch === ")" || ch === "]" || ch === "}") d -= 1;
+			if (d < 0) return false;
+		}
+		return d === 0;
+	};
+	return block.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("assert ") && l.includes(entrySymbol) && balanced(l)).slice(0, count);
+}
+/** Default authored-check source: one metered LLM call per task, before sampling,
+*  filtered through `filterAuthoredAsserts`. Returns [] (no signal, never a fabricated
+*  check) when the budget is 0, no entry symbol resolves, or the channel went down. */
+function modelAuthoredChecks(overrides = {}) {
+	return { async generate(_task, ctx) {
+		const count = overrides.count ?? ctx.count;
+		if (count <= 0 || !ctx.entrySymbol) return [];
+		const entry = ctx.entrySymbol;
+		const reply = await ctx.consult(authorInstruction(count, entry));
+		if (!reply) return [];
+		return filterAuthoredAsserts(reply, entry, count).map((code) => ({
+			code,
+			kind: "authored"
+		}));
+	} };
+}
+/** Official checks the surface stashed on the task (e.g. MBPP's shown assert). Reads
+*  `task.meta[key]` as a string array; anything else means no official checks. */
+function officialChecksFromMeta(key = "visibleChecks") {
+	return { async generate(task) {
+		const raw = task.meta?.[key];
+		if (!Array.isArray(raw)) return [];
+		return raw.filter((c) => typeof c === "string" && c.trim().length > 0).map((code) => ({
+			code,
+			kind: "official"
+		}));
+	} };
+}
+/** Concatenate check sources (official first by convention — ordering does not affect
+*  scoring, which reads each check's `kind`). */
+function composeCheckSources(...sources) {
+	return { async generate(task, ctx) {
+		const all = [];
+		for (const source of sources) all.push(...await source.generate(task, ctx));
+		return all;
+	} };
+}
+/** The symbol authored checks are pinned to: `task.meta.entryPoint` when the surface
+*  provides it, else the LAST `def name(` in the visible prompt (a code-completion stub
+*  lists helpers first, the entry stub last). Undefined ⇒ authoring is skipped. */
+function resolveEntrySymbol(task) {
+	const meta = task.meta?.entryPoint;
+	if (typeof meta === "string" && meta.trim().length > 0) return meta.trim();
+	const defs = [...task.userPrompt.matchAll(/(?:^|\n)\s*def\s+([A-Za-z_]\w*)\s*\(/g)];
+	return defs[defs.length - 1]?.[1];
+}
+/** The check program (mirrors the rigs' visible-check judge): candidate executes at
+*  module level, then each check runs INDIVIDUALLY in try/except so one malformed line
+*  cannot zero the rest; the summary line carries a per-call NONCE so a candidate
+*  printing a forged summary cannot be parsed as the verdict. */
+function buildCheckProgram(candidate, official, authored, nonce) {
+	return `${candidate}\n
+import base64 as _b64, json as _json, sys as _sys
+_official = _json.loads(_b64.b64decode("${Buffer.from(JSON.stringify(official), "utf8").toString("base64")}").decode("utf8"))
+_authored = _json.loads(_b64.b64decode("${Buffer.from(JSON.stringify(authored), "utf8").toString("base64")}").decode("utf8"))
+_lines = []
+def _run(_tests):
+    _att, _fail = 0, 0
+    for _t in _tests:
+        _att += 1
+        try:
+            exec(_t, dict(globals()))
+        except Exception as _e:
+            _fail += 1
+            _lines.append("CHECK FAILED: %s -> %s: %s" % (_t.strip()[:200], type(_e).__name__, str(_e)[:200]))
+    return _att, _fail
+_o_att, _o_fail = _run(_official)
+_a_att, _a_fail = _run(_authored)
+print("SRCK-${nonce} official=%d/%d authored=%d/%d" % (_o_att - _o_fail, _o_att, _a_att - _a_fail, _a_att))
+_sys.stdout.write("\\n".join(_lines)[-1500:])
+_sys.exit(0 if (_o_fail + _a_fail) == 0 and (_o_att + _a_att) > 0 else 1)
+`;
+}
+/** Default CheckRunner backend: pipes the check program into `python3` over the sandbox
+*  exec channel (`ctx.box`, or one bound at construction). Never shells out to docker
+*  itself — the jail is the sandbox's concern. No channel ⇒ throws; it must never
+*  silently score 0. Empty check sets short-circuit to a no-signal outcome (nothing to
+*  execute, so no channel is required). */
+function sandboxCheckRunner(options = {}) {
+	const python = options.python ?? "python3";
+	const timeoutMs = options.timeoutMs ?? 2e4;
+	return { async run(candidate, checks, ctx) {
+		if (checks.length === 0) return {
+			passedOfficial: 0,
+			totalOfficial: 0,
+			passedAuthored: 0,
+			totalAuthored: 0,
+			failureOutput: ""
+		};
+		const box = ctx.box ?? options.box;
+		if (!box) throw new Error("sandboxCheckRunner: no execution channel — bind one via sandboxCheckRunner({ box }) or CheckRunContext.box (ValidationCtx.box / a sandbox instance). Refusing to score without executing: a silent 0 would poison selection.");
+		const nonce = randomBytes(8).toString("hex");
+		const program = buildCheckProgram(candidate, checks.filter((c) => c.kind === "official").map((c) => c.code), checks.filter((c) => c.kind === "authored").map((c) => c.code), nonce);
+		const b64 = Buffer.from(program, "utf8").toString("base64");
+		const r = await box.exec(`printf '%s' '${b64}' | base64 -d | ${python} -`, { timeoutMs });
+		const summary = new RegExp(`SRCK-${nonce} official=(\\d+)/(\\d+) authored=(\\d+)/(\\d+)`).exec(r.stdout);
+		if (!summary) return {
+			passedOfficial: 0,
+			totalOfficial: 0,
+			passedAuthored: 0,
+			totalAuthored: 0,
+			failureOutput: (r.stderr || r.stdout).slice(-1500) || "no output (crashed or timed out before the checks could run)",
+			crashed: true
+		};
+		const failureOutput = r.stdout.replace(summary[0], "").slice(-1500).trim();
+		return {
+			passedOfficial: Number(summary[1]),
+			totalOfficial: Number(summary[2]),
+			passedAuthored: Number(summary[3]),
+			totalAuthored: Number(summary[4]),
+			failureOutput
+		};
+	} };
+}
+const frac = (passed, total) => total > 0 ? passed / total : 0;
+/** The selection order: crash < ran; then official pass-fraction; authored guesses only
+*  break ties. Returns > 0 when `a` outranks `b`. Strictly lexicographic — on MBPP,
+*  letting 6 noisy guesses outvote the one official check flipped selection negative. */
+function compareCheckOutcomes(a, b) {
+	const aCrashed = a.crashed === true;
+	if (aCrashed !== (b.crashed === true)) return aCrashed ? -1 : 1;
+	if (aCrashed) return 0;
+	const official = frac(a.passedOfficial, a.totalOfficial) - frac(b.passedOfficial, b.totalOfficial);
+	if (official !== 0) return official;
+	return frac(a.passedAuthored, a.totalAuthored) - frac(b.passedAuthored, b.totalAuthored);
+}
+/** Display scalar for receipts/reports (the rigs' `visibleScore` shape): crash = -1,
+*  else official fraction + 0.001 × authored fraction. Selection itself uses the exact
+*  lexicographic comparator, never this scalar. */
+function visibleCheckScore(o) {
+	if (o.crashed) return -1;
+	return frac(o.passedOfficial, o.totalOfficial) + .001 * frac(o.passedAuthored, o.totalAuthored);
+}
+/** Argmax by `compareCheckOutcomes`, FIRST index wins ties (deterministic; with zero
+*  visible coverage every candidate ties at no-signal and index 0 is the blind pick). */
+function selectBestIndex(outcomes) {
+	let best = 0;
+	for (let i = 1; i < outcomes.length; i += 1) if (compareCheckOutcomes(outcomes[i], outcomes[best]) > 0) best = i;
+	return best;
+}
+/** The repair keep-best guard: a challenger displaces the incumbent only when it is
+*  strictly better in the selection order AND passes at least as many official checks.
+*  The raw-count clause is deliberate belt-and-braces over the comparator (a custom
+*  runner can report shifted totals): repair must NEVER replace a candidate that passes
+*  more official checks with one that passes fewer. */
+function canDisplace(challenger, incumbent) {
+	if (challenger.crashed === true) return false;
+	if (challenger.passedOfficial < incumbent.passedOfficial) return false;
+	return compareCheckOutcomes(challenger, incumbent) > 0;
+}
+const totalChecks = (o) => o.totalOfficial + o.totalAuthored;
+const passesAllChecks = (o) => o.crashed !== true && totalChecks(o) > 0 && o.passedOfficial === o.totalOfficial && o.passedAuthored === o.totalAuthored;
+/** The candidate a shot produced, read from its conversation: the LAST `submit_answer`
+*  tool-call argument (verifier environments submit the artifact explicitly), else the
+*  latest assistant reply's fenced code block — preferring a block containing a `def`,
+*  because repair replies echo the failure report in a bare fence BEFORE the fixed code
+*  (the rigs' extractRepairCode lesson) — else the latest non-empty assistant text. */
+function defaultExtractCandidate(messages) {
+	for (let i = messages.length - 1; i >= 0; i -= 1) {
+		const calls = messages[i]?.tool_calls;
+		if (!calls) continue;
+		for (let j = calls.length - 1; j >= 0; j -= 1) {
+			const call = calls[j];
+			if (call?.function?.name !== "submit_answer") continue;
+			try {
+				const args = JSON.parse(call.function.arguments ?? "{}");
+				if (typeof args.answer === "string" && args.answer.trim()) return args.answer.trim();
+			} catch {}
+		}
+	}
+	const contents = [];
+	for (const m of messages) if (m.role === "assistant" && typeof m.content === "string" && m.content.trim()) contents.push(m.content);
+	const fencesOf = (text) => [...text.matchAll(/```(?:python|py)?\s*\n([\s\S]*?)```/gi)].map((m) => (m[1] ?? "").trim());
+	for (let i = contents.length - 1; i >= 0; i -= 1) {
+		const fences = fencesOf(contents[i]);
+		for (let j = fences.length - 1; j >= 0; j -= 1) if (/(^|\n)\s*def\s+\w+/.test(fences[j])) return fences[j];
+	}
+	for (let i = contents.length - 1; i >= 0; i -= 1) {
+		const fences = fencesOf(contents[i]);
+		if (fences.length > 0) return fences[fences.length - 1];
+	}
+	return (contents[contents.length - 1] ?? "").trim();
+}
+/** Per-slot approach lenses for `diverse` mode — copied from bench/src/directives.ts
+*  (the measured rig plumbing; a paired null there, kept as an optional knob). */
+const DIVERSE_LENSES = [
+	"Answer directly and decisively from what you already know. State the single best answer without hedging.",
+	"Decompose the question into the sub-facts it depends on. Establish each sub-fact explicitly, then compose them into the answer.",
+	"Reason from first principles. Ignore the most obvious or popular guess; derive the answer from underlying facts and relationships.",
+	"Name the most plausible WRONG answer and the trap that makes it tempting. Rule it out, then commit to the answer that survives."
+];
+function slotLens(slot) {
+	return `${DIVERSE_LENSES[slot % DIVERSE_LENSES.length]}${slot < DIVERSE_LENSES.length ? "" : ` (variant ${Math.floor(slot / DIVERSE_LENSES.length) + 1})`}`;
+}
+function repairSteer(outcome) {
+	return [
+		"Your latest solution failed some of the task-visible checks.",
+		"Result of running the visible checks against it:",
+		"```",
+		outcome.failureOutput.trim() || "(the code crashed before the checks could run)",
+		"```",
+		"Fix the solution so the visible checks pass. Provide the COMPLETE corrected solution the",
+		"same way you provided the original (same tool or format) — not a fragment or a diff."
+	].join("\n");
+}
+function describeOutcome(label, o) {
+	if (o.crashed) return `${label}: crashed before the checks could run`;
+	return `${label}: official ${o.passedOfficial}/${o.totalOfficial}, authored ${o.passedAuthored}/${o.totalAuthored}`;
+}
+/**
+* Build the structuralRollout `Strategy`: k shots → score each by the frozen visible
+* checks (official above authored, crash lowest) → argmax with first-index tie-break →
+* up to `repairRounds` repair shots steered by the failure output, keep-best under the
+* official-check guard. Authored via `defineStrategy`, so the deliverable score stays
+* harness-verified and every shot is metered by the conserved pool.
+*
+* Budget note: `runAgentic`'s `budget` sizes the pool — pass at least
+* `k + repairRounds + 1` so the samples, repairs, and the check-author consult all admit.
+*/
+function structuralRollout(config = {}) {
+	const policy = resolvePolicy(config.policy);
+	const checkSource = config.checkSource ?? composeCheckSources(officialChecksFromMeta(), modelAuthoredChecks());
+	const checkRunner = config.checkRunner ?? sandboxCheckRunner();
+	const extract = config.extractCandidate ?? defaultExtractCandidate;
+	const inner = defineStrategy("structuralRollout", async (ctx) => {
+		const { task, shot } = ctx;
+		const progression = [];
+		const receipts = [];
+		let completions = 0;
+		let shots = 0;
+		const consult = async (instruction) => {
+			const reply = await ctx.consult([], instruction);
+			completions += 1;
+			return reply;
+		};
+		const entrySymbol = resolveEntrySymbol(task);
+		const checks = await checkSource.generate(task, {
+			count: policy.testgen,
+			...entrySymbol ? { entrySymbol } : {},
+			consult
+		});
+		const officialChecks = checks.filter((c) => c.kind === "official").length;
+		const authoredChecks = checks.length - officialChecks;
+		const runCtx = {
+			task,
+			...config.box ? { box: config.box } : {}
+		};
+		const candidates = [];
+		for (let i = 0; i < policy.k; i += 1) {
+			const out = await shot(policy.diverse ? { steer: slotLens(i) } : void 0);
+			if (!out) break;
+			shots += 1;
+			completions += out.completions;
+			progression.push(out.score);
+			const artifact = extract(out.messages);
+			const outcome = await checkRunner.run(artifact, checks, runCtx);
+			candidates.push({
+				index: candidates.length,
+				messages: out.messages,
+				artifact,
+				outcome,
+				shotScore: out.score,
+				shotResolved: out.total > 0 && out.passes === out.total
+			});
+		}
+		if (candidates.length === 0) return {
+			score: 0,
+			resolved: false,
+			completions,
+			progression,
+			shots,
+			artifact: null,
+			selection: receipts,
+			repairStop: "no-candidates",
+			officialChecks,
+			authoredChecks
+		};
+		let best = candidates[selectBestIndex(candidates.map((c) => c.outcome))];
+		for (const c of candidates) receipts.push({
+			candidateIndex: c.index,
+			selected: false,
+			score: visibleCheckScore(c.outcome),
+			reason: describeOutcome("sample", c.outcome),
+			selector: "driver"
+		});
+		let seq = candidates.length;
+		let repairStop = "already-passing";
+		if (!passesAllChecks(best.outcome)) if (best.outcome.crashed !== true && totalChecks(best.outcome) === 0) repairStop = "no-signal";
+		else {
+			repairStop = "rounds-exhausted";
+			for (let r = 0; r < policy.repairRounds; r += 1) {
+				const out = await shot({
+					messages: best.messages,
+					steer: repairSteer(best.outcome)
+				});
+				if (!out) break;
+				shots += 1;
+				completions += out.completions;
+				progression.push(out.score);
+				const artifact = extract(out.messages);
+				const outcome = await checkRunner.run(artifact, checks, runCtx);
+				const displaced = canDisplace(outcome, best.outcome);
+				const label = displaced ? "repair (displaced the incumbent)" : outcome.crashed !== true && outcome.passedOfficial < best.outcome.passedOfficial ? "repair (held out: passes fewer official checks than the incumbent)" : "repair (held out: no improvement)";
+				receipts.push({
+					candidateIndex: seq,
+					selected: false,
+					score: visibleCheckScore(outcome),
+					reason: describeOutcome(label, outcome),
+					selector: "driver"
+				});
+				if (displaced) best = {
+					index: seq,
+					messages: out.messages,
+					artifact,
+					outcome,
+					shotScore: out.score,
+					shotResolved: out.total > 0 && out.passes === out.total
+				};
+				seq += 1;
+				if (passesAllChecks(best.outcome)) {
+					repairStop = "repaired-pass";
+					break;
+				}
+			}
+		}
+		const winner = receipts.find((r) => r.candidateIndex === best.index);
+		if (winner) winner.selected = true;
+		return {
+			score: best.shotScore,
+			resolved: best.shotResolved,
+			completions,
+			progression,
+			shots,
+			artifact: best.artifact,
+			selection: receipts,
+			repairStop,
+			officialChecks,
+			authoredChecks
+		};
+	});
+	if (policy.temperature === void 0) return inner;
+	return {
+		name: inner.name,
+		driver: (surface, task, opts, budget) => inner.driver(surface, task, {
+			...opts,
+			temperature: policy.temperature
+		}, budget)
+	};
+}
+//#endregion
+export { observe as C, researchDriverNote as D, optimizerMethod as E, strategyAuthorMethod as O, defaultAnalystInstruction as S, buildDriverSystem as T, depthStrategy as _, defaultStructuralRolloutPolicy as a, sample as b, officialChecksFromMeta as c, selectBestIndex as d, structuralRollout as f, defineStrategy as g, breadthStrategy as h, defaultExtractCandidate as i, resolveEntrySymbol as l, adaptiveRefine as m, compareCheckOutcomes as n, filterAuthoredAsserts as o, visibleCheckScore as p, composeCheckSources as r, modelAuthoredChecks as s, canDisplace as t, sandboxCheckRunner as u, refine as v, renderReport as w, sampleThenRefine as x, runAgentic as y };
+
+//# sourceMappingURL=structural-rollout-IXUEplky.js.map