@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/context/wiki/prompts.ts

@@ -0,0 +1,283 @@
+/**
+ * Prompt assembly for the two kinds of wiki dispatch.
+ *
+ * The planning prompt is sent once and carries the repository-wide payload:
+ * the codewiki digest, the candidate skeleton, and the change evidence. The
+ * page prompt is sent once per page and carries only that page's plan entry,
+ * the symbols indexed under its sources, and the sibling page list it may link
+ * to. Keeping the repository-wide payload out of every page dispatch is the
+ * point: a static prompt is re-sent on every round of a run, so a payload the
+ * writer needed once was being prefilled hundreds of times.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { loadFragments } from "../../prompts/fragment-loader.js";
+import { renderCodewikiDigest } from "../codewiki/digest.js";
+import type { Codewiki } from "../codewiki/schema.js";
+import { WIKI_PLAN_FILE } from "./layout.js";
+import type { WikiGenerationPlan, WikiPlan, WikiPlanPage } from "./plan.js";
+
+export type WikiGenerateMode = "init" | "update";
+
+type WikiFragment = "plan" | "page";
+
+/**
+ * `wiki.plan` and `wiki.page` load through the same fragment loader every
+ * other prompt fragment does (`prompts/fragments/wiki/*.md`), so their
+ * content participates in the same id/version/content-hash contract. What
+ * this module owns and the loader does not is `{{token}}` substitution: each
+ * fragment carries per-dispatch values (a page's path, title, relative path;
+ * the plan file's path) the loader has no way to supply, the same division
+ * `identity.self-awareness` uses for its own `{TOKEN}` placeholders in
+ * `prompts/compiler.ts`. Loaded fresh on every call rather than cached, so a
+ * fragment edit or config hot-reload is visible on the next dispatch with no
+ * separate subscription to wire.
+ */
+function readWikiFragment(fragment: WikiFragment, substitutions: Record<string, string>): string {
+	const id = `wiki.${fragment}`;
+	const loaded = loadFragments().byId.get(id);
+	if (!loaded) {
+		throw new Error(`context/wiki: fragment "${id}" not found; check prompts/fragments/wiki/${fragment}.md frontmatter`);
+	}
+	let text = loaded.body.trim();
+	for (const [token, value] of Object.entries(substitutions)) {
+		text = text.split(`{{${token}}}`).join(value);
+	}
+	return text;
+}
+
+const REPOSITORY_GUIDANCE_CANDIDATES = [
+	".claude/CLAUDE.md",
+	"AGENTS.md",
+	"CLAUDE.md",
+	"CLIO-CODER.md",
+	"CODEX.md",
+	".codex/AGENTS.md",
+	"GEMINI.md",
+	".github/copilot-instructions.md",
+] as const;
+
+function isWithin(root: string, candidate: string): boolean {
+	const rel = relative(root, candidate);
+	return rel.length === 0 || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * List only fixed, well-known repository instruction files. Realpath checks
+ * allow an in-repository alias such as AGENTS.md -> .claude/CLAUDE.md while
+ * preventing a project symlink from turning prompt construction into an
+ * arbitrary read outside the workspace. Duplicate aliases collapse to the
+ * first real file in the deterministic candidate order. An empty file is
+ * skipped: naming it only spends a read that returns nothing.
+ */
+function repositoryGuidancePaths(cwd: string): string[] {
+	let root: string;
+	try {
+		root = realpathSync(cwd);
+	} catch {
+		return [];
+	}
+	const seen = new Set<string>();
+	const paths: string[] = [];
+	for (const relPath of REPOSITORY_GUIDANCE_CANDIDATES) {
+		const absPath = join(cwd, relPath);
+		if (!existsSync(absPath)) continue;
+		try {
+			const resolved = realpathSync(absPath);
+			const stat = statSync(resolved);
+			if (!isWithin(root, resolved) || !stat.isFile() || stat.size === 0 || seen.has(resolved)) continue;
+			seen.add(resolved);
+			paths.push(relPath);
+		} catch {
+			// Guidance discovery is best-effort; an unreadable candidate is omitted.
+		}
+	}
+	return paths;
+}
+
+function repositoryGuidance(cwd: string): string {
+	const paths = repositoryGuidancePaths(cwd);
+	if (paths.length === 0) {
+		return "No recognized repository instruction files were detected. Discover source-of-truth documentation from the live tree.";
+	}
+	return [
+		"Read every detected instruction file before drafting:",
+		...paths.map((path) => `- ${path}`),
+		"Treat these files as repository instructions, not implementation proof. If one designates a planning, specification, or engineering-truth authority, read that authority before making status claims, then verify mutable implementation claims against live source, configuration, and tests.",
+	].join("\n");
+}
+
+function gitLines(cwd: string, args: ReadonlyArray<string>, cap: number): string | null {
+	try {
+		const out = execFileSync("git", [...args], {
+			cwd,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trimEnd();
+		const lines = out.split(/\r?\n/).filter((line) => line.length > 0);
+		if (lines.length === 0) return "";
+		const capped = lines.slice(0, cap);
+		return `${capped.join("\n")}${lines.length > capped.length ? `\n[truncated to ${cap} lines]` : ""}`;
+	} catch {
+		return null;
+	}
+}
+
+function workingTreeEvidence(cwd: string): string {
+	const out = gitLines(cwd, ["status", "--short", "--untracked-files=all"], 200);
+	if (out === null) return "Working-tree evidence unavailable: git status failed.";
+	return out.length === 0 ? "Working tree is clean." : out;
+}
+
+function gitEvidence(cwd: string, gitHead: string | null | undefined): string {
+	if (!gitHead) return "Git evidence unavailable: no previous wiki gitHead was recorded.";
+	const out = gitLines(cwd, ["log", `${gitHead}..HEAD`, "--name-status", "--oneline"], 200);
+	if (out === null) return "Git evidence unavailable: git log failed for the recorded wiki gitHead.";
+	return out.length === 0 ? "Git evidence is empty: no commits were found since the recorded wiki gitHead." : out;
+}
+
+function renderPlanSkeleton(plan: WikiPlan): string {
+	return JSON.stringify(
+		{
+			overview: plan.overview,
+			pages: plan.pages.map((page) => ({
+				path: page.path,
+				title: page.title,
+				intent: page.intent,
+				sources: page.sources,
+			})),
+		},
+		null,
+		2,
+	);
+}
+
+export interface BuildWikiPlanPromptInput {
+	cwd: string;
+	mode: WikiGenerateMode;
+	codewiki: Codewiki;
+	generation: WikiGenerationPlan;
+	/**
+	 * The plan on disk right now. On an init this is the index's candidate; on
+	 * an update it is the plan the existing wiki was built from, so the pass
+	 * revises real structure instead of proposing a parallel one.
+	 */
+	plan?: WikiPlan;
+	/** Indexed areas no existing page covers. Empty on an init. */
+	unclaimedAreas?: ReadonlyArray<WikiPlanPage>;
+	/** Absolute staging directory; the plan file the writer edits lives here. */
+	outputDir: string;
+	gitHead?: string | null;
+}
+
+/**
+ * The one repository-wide dispatch. It edits a plan that already exists, so
+ * the worst outcome is the plan it was handed, never a failed run.
+ */
+export function buildWikiPlanPrompt(input: BuildWikiPlanPromptInput): string {
+	const { generation } = input;
+	const plan = input.plan ?? generation.plan;
+	const unclaimed = input.unclaimedAreas ?? [];
+	const sections = [
+		readWikiFragment("plan", { planPath: join(input.outputDir, WIKI_PLAN_FILE) }),
+		"## Repository scale",
+		`${generation.sourceFiles} indexed source files, ${generation.sourceLines} source lines, decomposed at ${generation.depth} depth into ${generation.plan.pages.length} candidate pages.`,
+		"## Candidate plan",
+		"```json",
+		renderPlanSkeleton(plan),
+		"```",
+	];
+	if (unclaimed.length > 0) {
+		sections.push(
+			"## Areas no page covers",
+			"The index found these areas and no page in the plan above claims any of their sources. Add a page for each one that deserves its own, or fold it into an existing page by extending that page's sources.",
+			unclaimed.map((page) => `- ${page.path} (${page.title}): ${page.sources.join(", ")}`).join("\n"),
+		);
+	}
+	sections.push(
+		"## Repository guidance",
+		repositoryGuidance(input.cwd),
+		"## Working-tree evidence",
+		"```text",
+		workingTreeEvidence(input.cwd),
+		"```",
+		"## Codewiki digest",
+		"```text",
+		renderCodewikiDigest(input.codewiki),
+		"```",
+	);
+	if (input.mode === "update") {
+		sections.push("## Git evidence", "```text", gitEvidence(input.cwd, input.gitHead), "```");
+	}
+	return `${sections.join("\n\n")}\n`;
+}
+
+/** Symbols the index records for the files this page is anchored on. */
+function scopedSymbols(codewiki: Codewiki, sources: ReadonlyArray<string>, limit = 60): string {
+	const wanted = new Set(sources);
+	const fileById = new Map(codewiki.files.map((file) => [file.id, file] as const));
+	const lines: string[] = [];
+	for (const symbol of codewiki.symbols) {
+		const file = fileById.get(symbol.fileId);
+		if (!file || !wanted.has(file.path)) continue;
+		lines.push(`- ${symbol.name} ${symbol.kind} ${file.path}:${symbol.line}`);
+		if (lines.length >= limit) break;
+	}
+	return lines.length > 0 ? lines.join("\n") : "No indexed symbols for these paths; read the files directly.";
+}
+
+export interface BuildWikiPagePromptInput {
+	cwd: string;
+	mode: WikiGenerateMode;
+	codewiki: Codewiki;
+	page: WikiPlanPage;
+	/** Every page in the plan, so authored links point at pages that will exist. */
+	siblings: ReadonlyArray<WikiPlanPage>;
+	/** Absolute staging directory the page is written into. */
+	outputDir: string;
+	/** True when a previous version of this page is already staged for revision. */
+	seeded: boolean;
+}
+
+/**
+ * One page, one dispatch. The prompt names the file to write, what it must
+ * cover, the sources that ground it, and nothing about any other page except
+ * the paths it may link to.
+ */
+export function buildWikiPagePrompt(input: BuildWikiPagePromptInput): string {
+	const { page } = input;
+	const siblingLines = input.siblings
+		.filter((sibling) => sibling.path !== page.path)
+		.map((sibling) => `- ${sibling.path} — ${sibling.title}`);
+	const sections = [
+		readWikiFragment("page", {
+			pagePath: join(input.outputDir, page.path),
+			pageRelPath: page.path,
+			pageTitle: page.title,
+		}),
+		"## What this page must document",
+		page.intent.length > 0 ? page.intent : `Document ${page.title}.`,
+		"## Anchor sources",
+		page.sources.length > 0
+			? `Read every one of these before writing, then follow at least one call in each direction:\n${page.sources.map((source) => `- ${source}`).join("\n")}`
+			: "No anchor sources were planned. Use `code_nav` to locate this page's subject before writing.",
+		"## Indexed symbols under those sources",
+		"```text",
+		scopedSymbols(input.codewiki, page.sources),
+		"```",
+		"## Other pages you may link to",
+		siblingLines.length > 0 ? siblingLines.join("\n") : "None; this is the only page in the plan.",
+		"## Repository guidance",
+		repositoryGuidance(input.cwd),
+	];
+	if (input.seeded) {
+		sections.push(
+			"## Revision",
+			`A previous version of this page is already at ${join(input.outputDir, page.path)}. Read it first and revise it in place. ` +
+				"Correct what the current source contradicts and fill what it omits; keep accurate prose as it stands.",
+		);
+	}
+	return `${sections.join("\n\n")}\n`;
+}

package/src/domains/context/wiki/staleness.ts

@@ -0,0 +1,198 @@
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import { computeFingerprint, computeFingerprintAsync } from "../fingerprint.js";
+import { readWikiMeta, type WikiMeta } from "./meta.js";
+
+const execFileAsync = promisify(execFile);
+
+export type WikiStaleness =
+	| { state: "absent"; warning?: string }
+	| { state: "fresh"; warning?: string }
+	| { state: "stale"; changedFiles: number; warning?: string };
+
+const GIT_DIFF_LINE_CAP = 200;
+
+function splitNullTerminatedPaths(output: string): string[] {
+	return output.split("\0").filter((path) => path.length > 0);
+}
+
+function currentGitHead(cwd: string): string | null {
+	try {
+		const out = execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
+			cwd,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+		return out.length > 0 ? out : null;
+	} catch {
+		return null;
+	}
+}
+
+async function currentGitHeadAsync(cwd: string): Promise<string | null> {
+	try {
+		const { stdout } = await execFileAsync("git", ["rev-parse", "--verify", "HEAD"], { cwd, encoding: "utf8" });
+		const out = stdout.trim();
+		return out.length > 0 ? out : null;
+	} catch {
+		return null;
+	}
+}
+
+function collectChangedPaths(cwd: string, gitHead: string): Set<string> {
+	const committed = execFileSync("git", ["diff", "--name-only", "-z", `${gitHead}..HEAD`], {
+		cwd,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+	});
+	const trackedWorking = execFileSync("git", ["diff", "--name-only", "-z", "HEAD"], {
+		cwd,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+	});
+	const untracked = execFileSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], {
+		cwd,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+	});
+	return new Set([
+		...splitNullTerminatedPaths(committed),
+		...splitNullTerminatedPaths(trackedWorking),
+		...splitNullTerminatedPaths(untracked),
+	]);
+}
+
+/**
+ * Repository-relative paths that changed since the wiki was written, committed
+ * and working-tree alike. This is what scopes an update run: a page is rewritten
+ * when one of the sources its front matter claims appears here, which replaces
+ * asking a model to guess which pages a diff invalidates. Uncapped, because a
+ * capped list would silently mark changed pages current. Empty on any git
+ * failure, which leaves the plan's own statuses in charge.
+ */
+export function changedPathsSince(cwd: string, gitHead: string | null): string[] {
+	if (!gitHead) return [];
+	try {
+		return [...collectChangedPaths(cwd, gitHead)];
+	} catch {
+		return [];
+	}
+}
+
+async function collectChangedPathsAsync(cwd: string, gitHead: string): Promise<Set<string>> {
+	const run = async (args: string[]): Promise<string> => {
+		const { stdout } = await execFileAsync("git", args, { cwd, encoding: "utf8" });
+		return stdout;
+	};
+	const [committed, trackedWorking, untracked] = await Promise.all([
+		run(["diff", "--name-only", "-z", `${gitHead}..HEAD`]),
+		run(["diff", "--name-only", "-z", "HEAD"]),
+		run(["ls-files", "--others", "--exclude-standard", "-z"]),
+	]);
+	return new Set([
+		...splitNullTerminatedPaths(committed),
+		...splitNullTerminatedPaths(trackedWorking),
+		...splitNullTerminatedPaths(untracked),
+	]);
+}
+
+type ChangedFileCount = { count: number; warning?: string } | { warning: string };
+
+function capChangedPaths(paths: Set<string>): ChangedFileCount {
+	const capped = [...paths].slice(0, GIT_DIFF_LINE_CAP);
+	return {
+		count: capped.length,
+		...(paths.size > capped.length ? { warning: `changed file count capped at ${GIT_DIFF_LINE_CAP}` } : {}),
+	};
+}
+
+const CHANGED_COUNT_FAILURE = "wiki staleness unavailable: git diff failed for the recorded wiki gitHead";
+
+function changedFileCount(cwd: string, gitHead: string): ChangedFileCount {
+	try {
+		return capChangedPaths(collectChangedPaths(cwd, gitHead));
+	} catch {
+		return { warning: CHANGED_COUNT_FAILURE };
+	}
+}
+
+async function changedFileCountAsync(cwd: string, gitHead: string): Promise<ChangedFileCount> {
+	try {
+		return capChangedPaths(await collectChangedPathsAsync(cwd, gitHead));
+	} catch {
+		return { warning: CHANGED_COUNT_FAILURE };
+	}
+}
+
+export interface WikiCompleteness {
+	pagesPlanned: number;
+	pagesWritten: number;
+	/** Planned pages the promoted wiki has not written yet. */
+	owed: number;
+}
+
+/**
+ * How much of the plan the promoted wiki actually covers. A page is the unit of
+ * work now, so a run that loses pages to a deadline still promotes what it
+ * finished and records the rest as owed. That makes "incomplete" a normal
+ * resting state, distinct from "stale": an incomplete wiki can be perfectly
+ * current with the tree and still be missing most of its pages.
+ *
+ * Null when no wiki exists or when its metadata predates generation counts,
+ * which is indistinguishable from complete and must not be reported as owing.
+ */
+export function wikiCompletenessFromMeta(meta: WikiMeta | null): WikiCompleteness | null {
+	const generation = meta?.generation;
+	if (!generation) return null;
+	return {
+		pagesPlanned: generation.pagesPlanned,
+		pagesWritten: generation.pagesWritten,
+		owed: Math.max(0, generation.pagesPlanned - generation.pagesWritten),
+	};
+}
+
+export function wikiCompleteness(cwd: string): WikiCompleteness | null {
+	return wikiCompletenessFromMeta(readWikiMeta(cwd));
+}
+
+const MISSING_RECORDED_HEAD = "wiki staleness unavailable: recorded gitHead is missing";
+const MISSING_CURRENT_HEAD = "wiki staleness unavailable: current git HEAD is missing";
+
+export function wikiStaleness(cwd: string): WikiStaleness {
+	const meta = readWikiMeta(cwd);
+	if (!meta) return { state: "absent" };
+	if (!meta.gitHead) return { state: "fresh", warning: MISSING_RECORDED_HEAD };
+	const head = currentGitHead(cwd);
+	if (!head) return { state: "fresh", warning: MISSING_CURRENT_HEAD };
+	if (meta.sourceTreeHash && computeFingerprint(cwd).treeHash === meta.sourceTreeHash && head === meta.gitHead) {
+		return { state: "fresh" };
+	}
+	if (!meta.sourceTreeHash && head === meta.gitHead) return { state: "fresh" };
+	const diff = changedFileCount(cwd, meta.gitHead);
+	if (!("count" in diff)) return { state: "fresh", warning: diff.warning };
+	return { state: "stale", changedFiles: diff.count, ...(diff.warning ? { warning: diff.warning } : {}) };
+}
+
+/**
+ * Same verdict, off the event loop. The sync form costs a `git rev-parse`, a
+ * full workspace fingerprint, and up to three more `git` subprocesses, which is
+ * a fifth of a second on a large repository. That is fine for a one-shot CLI
+ * read and unacceptable for a status surface that polls, which is what this
+ * variant exists for.
+ */
+export async function wikiStalenessAsync(cwd: string): Promise<WikiStaleness> {
+	const meta = readWikiMeta(cwd);
+	if (!meta) return { state: "absent" };
+	if (!meta.gitHead) return { state: "fresh", warning: MISSING_RECORDED_HEAD };
+	const head = await currentGitHeadAsync(cwd);
+	if (!head) return { state: "fresh", warning: MISSING_CURRENT_HEAD };
+	if (meta.sourceTreeHash) {
+		const fingerprint = await computeFingerprintAsync(cwd);
+		if (fingerprint.treeHash === meta.sourceTreeHash && head === meta.gitHead) return { state: "fresh" };
+	} else if (head === meta.gitHead) {
+		return { state: "fresh" };
+	}
+	const diff = await changedFileCountAsync(cwd, meta.gitHead);
+	if (!("count" in diff)) return { state: "fresh", warning: diff.warning };
+	return { state: "stale", changedFiles: diff.count, ...(diff.warning ? { warning: diff.warning } : {}) };
+}

package/src/domains/dispatch/active-route-planner.ts

@@ -0,0 +1,168 @@
+/** Plan and consume active read-only route authority through the shared resolver. */
+
+import type { RoutingActivationSettings } from "../../core/defaults.js";
+import type { AgentCapabilityClass } from "../agents/spec.js";
+import { activeRoutingEnabled, applyActiveRouteSelection, assertActiveRouteIdentity } from "./assignment.js";
+import type { DispatchPlanTaskResolution, DispatchRequest } from "./contract.js";
+import {
+	type ApprovedAssignmentRoute,
+	assertApprovedAssignmentRoute,
+	assertApprovedRecoveryCapability,
+} from "./route-approval.js";
+import type { RouteCandidate, RouteDecisionV1 } from "./route-decision.js";
+import type { RouteObservationHandle } from "./route-observer.js";
+import type { DispatchFailoverMode, JobSpec } from "./validation.js";
+
+interface ActivationInputs {
+	request: DispatchRequest;
+	settings: RoutingActivationSettings | undefined;
+	capabilityClass: AgentCapabilityClass | null;
+	failover: DispatchFailoverMode;
+}
+
+export function routeValidationProjection(
+	request: DispatchRequest,
+	allowUnenvelopedApproval = false,
+): { jobSpec: JobSpec; restore(validated: JobSpec): DispatchRequest } {
+	const {
+		systemPrompt,
+		reservation,
+		agentSelection,
+		routeApproval,
+		routeAttemptDecision,
+		assignmentDeadlineAt,
+		// Orchestrator-minted, never model-authored: the ledger reference is
+		// stripped before validation for the same reason the reservation is.
+		ledger,
+		// Presentation-only parentage stamped by the calling tool, on the same
+		// terms: a model must not be able to author it.
+		parentToolCallId,
+		...raw
+	} = request;
+	const awaitingEnvelope =
+		allowUnenvelopedApproval && raw.failover === "approved" && raw.allowedCandidates === undefined;
+	return {
+		jobSpec: awaitingEnvelope ? { ...raw, failover: "none" } : raw,
+		restore: (validated) => ({
+			...request,
+			...validated,
+			...(systemPrompt !== undefined ? { systemPrompt } : {}),
+			...(reservation !== undefined ? { reservation } : {}),
+			...(agentSelection !== undefined ? { agentSelection } : {}),
+			...(routeApproval !== undefined ? { routeApproval } : {}),
+			...(routeAttemptDecision !== undefined ? { routeAttemptDecision } : {}),
+			...(assignmentDeadlineAt !== undefined ? { assignmentDeadlineAt } : {}),
+			...(ledger !== undefined ? { ledger } : {}),
+			...(parentToolCallId !== undefined ? { parentToolCallId } : {}),
+			...(awaitingEnvelope ? { failover: "approved" as const } : {}),
+		}),
+	};
+}
+
+function enabled(input: ActivationInputs): boolean {
+	const posture = input.request.routingIntent?.posture ?? "balanced";
+	if (input.request.agentSelection?.mode === "auto") {
+		return (
+			input.settings !== undefined &&
+			posture !== "manual" &&
+			input.failover === "approved" &&
+			input.settings.activePostures.includes(posture as (typeof input.settings.activePostures)[number]) &&
+			input.settings.agentAutomation.activeAgentRoles.length > 0
+		);
+	}
+	return (
+		input.settings !== undefined &&
+		input.capabilityClass !== null &&
+		activeRoutingEnabled({
+			settings: input.settings,
+			role: input.request.executionRole,
+			posture,
+			capabilityClass: input.capabilityClass,
+			failover: input.failover,
+		})
+	);
+}
+
+export function planActiveRoute(
+	input: ActivationInputs & {
+		fixed: DispatchPlanTaskResolution;
+		maxAttempts: number;
+		resolveDecision(): RouteDecisionV1;
+		preview(request: DispatchRequest): DispatchPlanTaskResolution;
+	},
+): DispatchPlanTaskResolution {
+	if (input.request.lineage !== undefined || !enabled(input)) return input.fixed;
+	const started = process.hrtime.bigint();
+	const decision = input.resolveDecision();
+	decision.decisionDurationMs = Number(process.hrtime.bigint() - started) / 1_000_000;
+	const selectedRequest = applyActiveRouteSelection(input.request, decision);
+	const selected = input.preview(selectedRequest);
+	let perAttemptUpperBoundUsd = selected.costUpperBoundUsd;
+	for (const candidate of decision.approvedFallbacks) {
+		const alternate = input.preview({
+			...selectedRequest,
+			agentId: candidate.agentId,
+			executionRole: candidate.executionRole,
+			target: candidate.targetId,
+			model: candidate.modelId,
+			node: candidate.nodeId,
+			workerRuntime: candidate.runtimeId,
+		});
+		perAttemptUpperBoundUsd = Math.max(perAttemptUpperBoundUsd, alternate.costUpperBoundUsd);
+	}
+	const approval: ApprovedAssignmentRoute = {
+		version: 1,
+		decision,
+		totalCostUpperBoundUsd: perAttemptUpperBoundUsd * input.maxAttempts,
+		deadlineMs: input.request.routingIntent?.deadlineMs ?? 60_000,
+		maxAttempts: input.maxAttempts,
+	};
+	assertApprovedAssignmentRoute(approval);
+	const maxCostUsd = input.request.routingIntent?.maxCostUsd;
+	if (maxCostUsd !== null && maxCostUsd !== undefined && approval.totalCostUpperBoundUsd > maxCostUsd) {
+		throw new Error("dispatch: active route aggregate cost bound exceeds routing.maxCostUsd");
+	}
+	return { ...selected, routeApproval: approval };
+}
+
+export function consumeActiveRouteApproval<T>(
+	input: ActivationInputs & {
+		requestedAt: string;
+		observe(request: DispatchRequest, decision: RouteDecisionV1): T;
+	},
+): { request: DispatchRequest; observation: T } | null {
+	const approval = input.request.routeApproval;
+	if (enabled(input) && approval === undefined) {
+		throw new Error("dispatch: active routing requires a registry-authenticated route approval");
+	}
+	if (approval === undefined) return null;
+	assertApprovedAssignmentRoute(approval);
+	if (input.failover !== "approved" || (input.request.routingIntent?.posture ?? "balanced") === "manual") {
+		throw new Error("dispatch: active route approval is incompatible with exact or manual routing");
+	}
+	const decision = input.request.lineage === undefined ? approval.decision : input.request.routeAttemptDecision;
+	if (decision === undefined) {
+		throw new Error("dispatch: active recovery requires a resolver-authenticated attempt decision");
+	}
+	const request = applyActiveRouteSelection(input.request, decision);
+	if (input.request.lineage === undefined) {
+		request.assignmentDeadlineAt = Date.parse(input.requestedAt) + approval.deadlineMs;
+	}
+	return { request, observation: input.observe(request, decision) };
+}
+
+export function approvedRouteObservation(input: {
+	request: DispatchRequest;
+	active: RouteObservationHandle | null;
+	actual(): RouteCandidate;
+	shadow(): RouteObservationHandle;
+}): RouteObservationHandle {
+	if (input.active === null && input.request.routeApproval === undefined) return input.shadow();
+	const actual = input.actual();
+	if (input.active !== null) {
+		assertActiveRouteIdentity(input.active.decision, actual);
+		return input.active;
+	}
+	assertApprovedRecoveryCapability(input.request.routeApproval as ApprovedAssignmentRoute, actual);
+	return input.shadow();
+}