@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/tools/task-worktree.ts

@@ -0,0 +1,238 @@
+import { execFileSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+export type TaskWorktreeApply = "merge" | "preserve";
+
+export interface TaskWorktree {
+	root: string;
+	runId: string;
+	path: string;
+	branch: string;
+	base: string;
+	ownerToken: string;
+}
+
+export interface TaskWorktreeReceipt {
+	path: string;
+	branch: string;
+	diffHash: string;
+	apply: TaskWorktreeApply;
+	applied: boolean;
+	reason?: string;
+}
+
+const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const OWNER_FILE_SUFFIX = ".task-owner.json";
+const COMMIT_IDENTITY = "clio-task";
+
+function gitBytes(root: string, args: string[]): Buffer {
+	return execFileSync("git", ["-C", root, ...args], {
+		stdio: ["ignore", "pipe", "pipe"],
+		timeout: 30_000,
+	});
+}
+
+function git(root: string, args: string[]): string {
+	return gitBytes(root, args).toString("utf8").trim();
+}
+
+export function isCanonicalWorktreePathInside(parent: string, candidate: string): boolean {
+	let canonicalParent: string;
+	let canonicalCandidate: string;
+	try {
+		canonicalParent = realpathSync(parent);
+	} catch {
+		canonicalParent = resolve(parent);
+	}
+	try {
+		canonicalCandidate = realpathSync(candidate);
+	} catch {
+		canonicalCandidate = resolve(candidate);
+	}
+	const rel = relative(canonicalParent, canonicalCandidate);
+	return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+export function commitWorktreePath(path: string, identity: string, message: string): boolean {
+	git(path, ["add", "-A"]);
+	if (git(path, ["status", "--porcelain"]).length === 0) return false;
+	git(path, [
+		"-c",
+		`user.name=${identity}`,
+		"-c",
+		`user.email=${identity}@local`,
+		"commit",
+		"-m",
+		message,
+		"--no-verify",
+	]);
+	return true;
+}
+
+export function worktreeBranchDiffStat(root: string, branch: string): string {
+	try {
+		return git(root, ["diff", "--shortstat", `HEAD...${branch}`]) || "no changes";
+	} catch {
+		return "diff unavailable";
+	}
+}
+
+export function protectedPathsChangedByWorktreeBranch(
+	root: string,
+	branch: string,
+	protectedPaths: ReadonlyArray<string>,
+): string[] {
+	const canonical = realpathSync(root);
+	const protectedInside = protectedPaths
+		.map((path) => resolve(path))
+		.filter((path) => {
+			const rel = relative(canonical, path);
+			return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+		});
+	if (protectedInside.length === 0) return [];
+	const changed = git(canonical, ["diff", "--name-only", "-z", "--no-renames", `HEAD...${branch}`])
+		.split("\0")
+		.filter((path) => path.length > 0)
+		.map((path) => resolve(canonical, path));
+	const blocked = new Set<string>();
+	for (const candidate of changed) {
+		for (const protectedPath of protectedInside) {
+			const rel = relative(protectedPath, candidate);
+			if (
+				candidate === protectedPath ||
+				(rel.length > 0 && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+			) {
+				blocked.add(protectedPath);
+			}
+		}
+	}
+	return [...blocked].sort();
+}
+
+export function mergeWorktreeBranch(
+	root: string,
+	branch: string,
+	identity: string,
+): { ok: true } | { ok: false; reason: string } {
+	try {
+		git(root, [
+			"-c",
+			`user.name=${identity}`,
+			"-c",
+			`user.email=${identity}@local`,
+			"merge",
+			"--no-edit",
+			"--no-verify",
+			branch,
+		]);
+		return { ok: true };
+	} catch (error) {
+		try {
+			git(root, ["merge", "--abort"]);
+		} catch {
+			// No merge remains to abort.
+		}
+		return {
+			ok: false,
+			reason: error instanceof Error ? (error.message.split("\n")[0] ?? "merge failed") : String(error),
+		};
+	}
+}
+
+function validateRunId(runId: string): void {
+	if (!SAFE_RUN_ID.test(runId) || runId === "." || runId === "..")
+		throw new Error(`invalid task worktree run id '${runId}'`);
+}
+
+export function gitCheckoutRoot(cwd: string): string | null {
+	try {
+		return realpathSync(git(cwd, ["rev-parse", "--show-toplevel"]));
+	} catch {
+		return null;
+	}
+}
+
+export function createTaskWorktree(root: string, runId: string, base?: string): TaskWorktree {
+	validateRunId(runId);
+	const canonical = realpathSync(root);
+	const resolvedBase = base ?? git(canonical, ["rev-parse", "HEAD"]);
+	const parent = join(canonical, ".clio-coder", "worktrees");
+	const path = join(parent, runId);
+	const branch = `clio/task/${runId}`;
+	mkdirSync(parent, { recursive: true });
+	if (!isCanonicalWorktreePathInside(parent, path))
+		throw new Error(`task worktree path escapes its parent for run ${runId}`);
+	git(canonical, ["worktree", "add", "-b", branch, path, resolvedBase]);
+	const ownerToken = randomBytes(16).toString("hex");
+	writeFileSync(
+		`${path}${OWNER_FILE_SUFFIX}`,
+		`${JSON.stringify({ version: 1, kind: "clio-task-worktree", root: canonical, runId, branch, base: resolvedBase, ownerToken }, null, 2)}\n`,
+		{ encoding: "utf8", flag: "wx" },
+	);
+	return { root: canonical, runId, path, branch, base: resolvedBase, ownerToken };
+}
+
+function assertOwnership(worktree: TaskWorktree): void {
+	const expected = join(worktree.root, ".clio-coder", "worktrees", worktree.runId);
+	if (
+		resolve(worktree.path) !== resolve(expected) ||
+		!isCanonicalWorktreePathInside(join(worktree.root, ".clio-coder", "worktrees"), worktree.path)
+	) {
+		throw new Error(`task worktree ${worktree.runId} has an invalid ownership path`);
+	}
+	if (!existsSync(`${worktree.path}${OWNER_FILE_SUFFIX}`))
+		throw new Error(`task worktree ${worktree.runId} has no ownership file`);
+}
+
+function commitTaskWorktree(worktree: TaskWorktree, message = `Clio task ${worktree.runId}`): boolean {
+	assertOwnership(worktree);
+	return commitWorktreePath(worktree.path, COMMIT_IDENTITY, message);
+}
+
+function taskWorktreeDiffHash(worktree: Pick<TaskWorktree, "root" | "base" | "branch">): string {
+	const bytes = gitBytes(worktree.root, ["diff", `${worktree.base}..${worktree.branch}`]);
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+function protectedPathsChangedByTaskBranch(
+	worktree: Pick<TaskWorktree, "root" | "branch">,
+	protectedPaths: ReadonlyArray<string>,
+): string[] {
+	return protectedPathsChangedByWorktreeBranch(worktree.root, worktree.branch, protectedPaths);
+}
+
+export function applyTaskWorktree(input: {
+	worktree: TaskWorktree;
+	apply: TaskWorktreeApply;
+	protectedPaths?: ReadonlyArray<string>;
+}): TaskWorktreeReceipt {
+	assertOwnership(input.worktree);
+	commitTaskWorktree(input.worktree);
+	const receipt: TaskWorktreeReceipt = {
+		path: input.worktree.path,
+		branch: input.worktree.branch,
+		diffHash: taskWorktreeDiffHash(input.worktree),
+		apply: input.apply,
+		applied: false,
+	};
+	if (input.apply === "preserve") return receipt;
+	const protectedChanges = protectedPathsChangedByTaskBranch(input.worktree, input.protectedPaths ?? []);
+	if (protectedChanges.length > 0) return { ...receipt, reason: "protected_artifact_changed" };
+	const merged = mergeWorktreeBranch(input.worktree.root, input.worktree.branch, COMMIT_IDENTITY);
+	if (!merged.ok) return { ...receipt, reason: "worktree_merge_conflict" };
+	return { ...receipt, applied: true };
+}
+
+export function cleanupTaskWorktree(worktree: TaskWorktree, deleteBranch: boolean): void {
+	assertOwnership(worktree);
+	try {
+		git(worktree.root, ["worktree", "remove", "--force", worktree.path]);
+	} catch {
+		if (existsSync(worktree.path)) rmSync(worktree.path, { recursive: true, force: true });
+		git(worktree.root, ["worktree", "prune"]);
+	}
+	if (deleteBranch) git(worktree.root, ["branch", "-D", worktree.branch]);
+	rmSync(`${worktree.path}${OWNER_FILE_SUFFIX}`, { force: true });
+}

package/src/tools/verify/authoring.ts

@@ -12,6 +12,7 @@ import {
 import path from "node:path";
 import { isMap, isSeq, parseDocument, stringify, type YAMLMap } from "yaml";
 import { resolveSafeCwd, SAFE_EXEC_DEFAULT_TIMEOUT_MS } from "../../core/safe-exec.js";
+import { parseTomlDocument, tomlTableAt } from "../../core/toml.js";
 import { isVerificationScriptName } from "../../core/verification-scripts.js";
 import { compareCodepoints } from "../../domains/evidence/ordering.js";
 import type { ToolResult } from "../registry.js";
@@ -23,7 +24,7 @@ import {
 	parseProjectVerifierCatalogText,
 } from "./catalog.js";
 import { verifyTool } from "./index.js";
-import { discoverDeclaredChecksAtRoot } from "./scripts.js";
+import { discoverDeclaredChecksAtRoot, discoverDeclaredProjectEntriesAtRoot } from "./scripts.js";
 
 export type VerifierProposalAuthority = "project-declared" | "toolchain-defined";
 
@@ -33,6 +34,8 @@ export type VerifierSignalKind =
 	| "cargo"
 	| "cmake-preset"
 	| "python-runner"
+	| "just-recipe"
+	| "make-target"
 	| "go-module"
 	| "validation-contract"
 	| "manual-entry";
@@ -148,6 +151,12 @@ export interface VerifierAuthoringWorkflowOptions {
 	runCheck?: (id: string) => Promise<ToolResult>;
 }
 
+export interface DeclaredProjectCommand {
+	id: string;
+	command: string[];
+	provenance: VerifierProvenance;
+}
+
 interface RawProposal {
 	preferredId: string;
 	description: string;
@@ -288,8 +297,13 @@ function cargoProposals(workspaceRoot: string, diagnostics: string[]): RawPropos
 		diagnostics.push(`${relative}: ${text.message}; Cargo discovery skipped.`);
 		return [];
 	}
-	const workspace = /^\s*\[workspace(?:\]|\.)/mu.test(text);
-	const packageManifest = /^\s*\[package\]/mu.test(text);
+	const document = parseTomlDocument(text);
+	if (document === null) {
+		diagnostics.push(`${relative}: invalid TOML; Cargo discovery skipped.`);
+		return [];
+	}
+	const workspace = tomlTableAt(document, ["workspace"]) !== null;
+	const packageManifest = tomlTableAt(document, ["package"]) !== null;
 	if (!workspace && !packageManifest) {
 		diagnostics.push(`${relative}: no [package] or [workspace] declaration was found; Cargo discovery skipped.`);
 		return [];
@@ -364,73 +378,68 @@ function cmakeProposals(workspaceRoot: string, diagnostics: string[]): RawPropos
 	return proposals;
 }
 
-function tomlSections(text: string): Map<string, string[]> {
-	const sections = new Map<string, string[]>();
-	let active = "";
-	for (const line of text.split(/\r?\n/u)) {
-		const header = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/u.exec(line);
-		if (header?.[1] !== undefined) {
-			active = header[1].trim();
-			if (!sections.has(active)) sections.set(active, []);
-			continue;
-		}
-		if (active.length > 0) sections.get(active)?.push(line);
-	}
-	return sections;
-}
-
-function declaredScriptName(line: string): string | null {
-	const match = /^\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_.:-]+))\s*=\s*(?:"[^"]+"|'[^']+')\s*(?:#.*)?$/u.exec(line);
-	return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
-}
-
 function pythonProposals(workspaceRoot: string, diagnostics: string[]): RawProposal[] {
 	const proposals: RawProposal[] = [];
 	const pyprojectPath = "pyproject.toml";
 	const pyproject = regularFileText(path.join(workspaceRoot, pyprojectPath), workspaceRoot);
 	if (pyproject instanceof Error) diagnostics.push(`${pyprojectPath}: ${pyproject.message}; Python discovery skipped.`);
 	if (typeof pyproject === "string") {
-		const sections = tomlSections(pyproject);
-		for (const [section, module, id, description, tags] of [
-			["tool.pytest.ini_options", "pytest", "python-pytest", "Run the declared pytest suite", ["python", "test"]],
-			["tool.tox", "tox", "python-tox", "Run the declared tox environments", ["python", "test"]],
-			["tool.nox", "nox", "python-nox", "Run the declared nox sessions", ["python", "test"]],
-		] as const) {
-			if (!sections.has(section)) continue;
-			proposals.push({
-				preferredId: id,
-				description,
-				command: ["python", "-m", module],
-				cwd: ".",
-				timeoutMs: SAFE_EXEC_DEFAULT_TIMEOUT_MS,
-				tags: [...tags],
-				provenance: {
-					kind: "python-runner",
-					path: pyprojectPath,
-					detail: `[${section}]`,
-					authority: "toolchain-defined",
-				},
-			});
-		}
-		for (const section of ["project.scripts", "tool.poetry.scripts"]) {
-			for (const line of sections.get(section) ?? []) {
-				const name = declaredScriptName(line);
-				if (name === null || !isVerificationScriptName(name)) continue;
+		const document = parseTomlDocument(pyproject);
+		if (document === null) {
+			diagnostics.push(`${pyprojectPath}: invalid TOML; Python discovery skipped.`);
+		} else {
+			for (const [path, section, module, id, description, tags] of [
+				[
+					["tool", "pytest", "ini_options"],
+					"tool.pytest.ini_options",
+					"pytest",
+					"python-pytest",
+					"Run the declared pytest suite",
+					["python", "test"],
+				],
+				[["tool", "tox"], "tool.tox", "tox", "python-tox", "Run the declared tox environments", ["python", "test"]],
+				[["tool", "nox"], "tool.nox", "nox", "python-nox", "Run the declared nox sessions", ["python", "test"]],
+			] as const) {
+				if (tomlTableAt(document, path) === null) continue;
 				proposals.push({
-					preferredId: `python-${slug(name, "check")}`,
-					description: `Run declared Python entry point '${name}'`,
-					command: [name],
+					preferredId: id,
+					description,
+					command: ["python", "-m", module],
 					cwd: ".",
 					timeoutMs: SAFE_EXEC_DEFAULT_TIMEOUT_MS,
-					tags: [slug(name.split(/[:.-]/u)[0] ?? "python", "python"), "python"],
+					tags: [...tags],
 					provenance: {
 						kind: "python-runner",
 						path: pyprojectPath,
-						detail: `[${section}] entry '${name}'`,
-						authority: "project-declared",
+						detail: `[${section}]`,
+						authority: "toolchain-defined",
 					},
 				});
 			}
+			for (const [path, section] of [
+				[["project", "scripts"], "project.scripts"],
+				[["tool", "poetry", "scripts"], "tool.poetry.scripts"],
+			] as const) {
+				const scripts = tomlTableAt(document, path);
+				if (scripts === null) continue;
+				for (const [name, target] of Object.entries(scripts)) {
+					if (typeof target !== "string" || !isVerificationScriptName(name)) continue;
+					proposals.push({
+						preferredId: `python-${slug(name, "check")}`,
+						description: `Run declared Python entry point '${name}'`,
+						command: [name],
+						cwd: ".",
+						timeoutMs: SAFE_EXEC_DEFAULT_TIMEOUT_MS,
+						tags: [slug(name.split(/[:.-]/u)[0] ?? "python", "python"), "python"],
+						provenance: {
+							kind: "python-runner",
+							path: pyprojectPath,
+							detail: `[${section}] entry '${name}'`,
+							authority: "project-declared",
+						},
+					});
+				}
+			}
 		}
 	}
 
@@ -465,6 +474,58 @@ function pythonProposals(workspaceRoot: string, diagnostics: string[]): RawPropo
 	return proposals;
 }
 
+/**
+ * Discover exact invocation vectors from project declarations for fleet command
+ * authoring. This shares the verifier authoring readers and provenance model,
+ * while retaining entries that are not verification-family names.
+ */
+export function discoverDeclaredProjectCommands(workspaceRoot = process.cwd()): DeclaredProjectCommand[] {
+	const commands: DeclaredProjectCommand[] = [];
+	const add = (id: string, command: string[], pathValue: string, detail: string, kind: VerifierSignalKind): void => {
+		commands.push({
+			id,
+			command,
+			provenance: { kind, path: pathValue, detail, authority: "project-declared" },
+		});
+	};
+	for (const entry of discoverDeclaredProjectEntriesAtRoot(workspaceRoot)) {
+		add(entry.id, entry.command, entry.path, entry.detail, entry.kind);
+	}
+	const pyprojectText = regularFileText(path.join(workspaceRoot, "pyproject.toml"), workspaceRoot);
+	if (typeof pyprojectText === "string") {
+		const document = parseTomlDocument(pyprojectText);
+		if (document !== null) {
+			for (const [tablePath, label] of [
+				[["project", "scripts"], "project.scripts"],
+				[["tool", "poetry", "scripts"], "tool.poetry.scripts"],
+			] as const) {
+				const scripts = tomlTableAt(document, tablePath);
+				if (scripts === null) continue;
+				for (const [name, target] of Object.entries(scripts).sort(([left], [right]) => compareCodepoints(left, right))) {
+					if (typeof target === "string") add(name, [name], "pyproject.toml", `[${label}] entry '${name}'`, "python-runner");
+				}
+			}
+			for (const [tablePath, module, id, label] of [
+				[["tool", "pytest", "ini_options"], "pytest", "pytest", "tool.pytest.ini_options"],
+				[["tool", "tox"], "tox", "tox", "tool.tox"],
+				[["tool", "nox"], "nox", "nox", "tool.nox"],
+			] as const) {
+				if (tomlTableAt(document, tablePath) !== null)
+					add(id, ["python", "-m", module], "pyproject.toml", `[${label}]`, "python-runner");
+			}
+		}
+	}
+	const seen = new Set<string>();
+	return commands.filter((entry) => {
+		let id = slug(entry.id, "command");
+		let suffix = 2;
+		while (seen.has(id)) id = `${slug(entry.id, "command")}-${suffix++}`;
+		seen.add(id);
+		entry.id = id;
+		return true;
+	});
+}
+
 function goProposals(workspaceRoot: string, diagnostics: string[]): RawProposal[] {
 	const relative = "go.mod";
 	const text = regularFileText(path.join(workspaceRoot, relative), workspaceRoot);

package/src/tools/verify/scripts.ts

@@ -21,6 +21,14 @@ import {
 
 export type DeclaredCheckDiscoveryResult = { ok: true; sources: DeclaredCheckSource[] } | { ok: false; reason: string };
 
+export interface DeclaredProjectEntry {
+	id: string;
+	command: string[];
+	path: string;
+	detail: string;
+	kind: "package-script" | "just-recipe" | "make-target";
+}
+
 function repositoryRelativeCwd(workspaceRoot: string, resolved: string): string {
 	const relative = path.relative(workspaceRoot, resolved);
 	return relative.length === 0 ? "." : relative.split(path.sep).join("/");
@@ -43,6 +51,60 @@ function packageCheckSource(packageRoot: string, workspaceRoot: string): Declare
 	return { kind: "package.json", path: packagePath, checks };
 }
 
+/** Discover every exact project-declared entry without promoting it to a verifier check. */
+export function discoverDeclaredProjectEntriesAtRoot(workspaceRoot: string): DeclaredProjectEntry[] {
+	const entries: DeclaredProjectEntry[] = [];
+	const packagePath = path.join(workspaceRoot, "package.json");
+	if (existsSync(packagePath)) {
+		const pkg = parsePackageJson(packagePath);
+		if (pkg.ok) {
+			for (const name of Object.keys(pkg.scripts).sort()) {
+				if (typeof pkg.scripts[name] !== "string") continue;
+				entries.push({
+					id: name,
+					command: ["npm", "run", name],
+					path: "package.json",
+					detail: `package.json script '${name}'`,
+					kind: "package-script",
+				});
+			}
+		}
+	}
+	for (const relative of ["justfile", "Justfile"] as const) {
+		const filePath = path.join(workspaceRoot, relative);
+		if (!existsSync(filePath)) continue;
+		const text = readFileSync(filePath, "utf8");
+		for (const match of text.matchAll(/^([A-Za-z0-9][A-Za-z0-9_-]*)\s*(?:[^:=\n]*)?:\s*(?:#.*)?$/gmu)) {
+			const name = match[1];
+			if (name === undefined || name.startsWith("_")) continue;
+			entries.push({
+				id: name,
+				command: ["just", name],
+				path: relative,
+				detail: `just recipe '${name}'`,
+				kind: "just-recipe",
+			});
+		}
+		break;
+	}
+	const makePath = path.join(workspaceRoot, "Makefile");
+	if (existsSync(makePath)) {
+		const text = readFileSync(makePath, "utf8");
+		for (const match of text.matchAll(/^([A-Za-z0-9][A-Za-z0-9_.-]*)\s*:(?![=])[^\n]*$/gmu)) {
+			const name = match[1];
+			if (name === undefined || name.startsWith(".")) continue;
+			entries.push({
+				id: name,
+				command: ["make", name],
+				path: "Makefile",
+				detail: `Makefile target '${name}'`,
+				kind: "make-target",
+			});
+		}
+	}
+	return entries;
+}
+
 function providerCollision(sources: ReadonlyArray<DeclaredCheckSource>): string | null {
 	const seen = new Map<string, DeclaredCheck>();
 	for (const source of sources) {

package/src/tools/worker-evidence.ts

@@ -1,7 +1,14 @@
 import { mentionsWorkerToolCallCap } from "../core/guardrails.js";
+import {
+	formatBudgetPolicy,
+	formatBudgetReasons,
+	formatBudgetRequest,
+	formatEffectiveBudget,
+} from "../domains/dispatch/budget-envelope.js";
 import type { ReceiptIntegrityResult } from "../domains/dispatch/receipt-integrity.js";
 import type { RunReceipt, RunReceiptVerification } from "../domains/dispatch/types.js";
 import { adaptRunReceiptTrustStatus, type CanonicalTrustStatus } from "../domains/evidence/trust-status.js";
+import { receiptResponseModelIdObservationLabel } from "./dispatch-event-text.js";
 
 /** Matches a source citation the parent can independently spot-check. */
 const SOURCE_CITATION_PATTERN = /([\w./~-]+):(\d+)/g;
@@ -120,7 +127,7 @@ export function receiptEvidenceLabels(
 	verification: RunReceiptVerification,
 	integrity: ReceiptIntegrityResult,
 ): string[] {
-	const status = adaptRunReceiptTrustStatus({ ...receipt, verification }, { integrity });
+	const status = adaptRunReceiptTrustStatus({ ...receipt, verification: verification }, { integrity });
 	const canonical = canonicalTrustLabel(status);
 	if (!integrity.ok) {
 		return [canonical, `receipt_integrity=FAILED reason=${JSON.stringify(integrity.reason)}`];
@@ -136,10 +143,23 @@ export function receiptEvidenceLabels(
 			sections.length > 0 ? ` sections:${[...sections].sort().join(",")}` : ""
 		}${receipt.projectContext.contentHash !== undefined ? ` sha256:${receipt.projectContext.contentHash}` : ""}`;
 	}
+	const responseModelIdObservation = receiptResponseModelIdObservationLabel(receipt);
+	const budget =
+		receipt.budget === undefined
+			? []
+			: [
+					`budget_recipe_policy=${JSON.stringify(formatBudgetPolicy(receipt.budget))}`,
+					`budget_requested=${JSON.stringify(formatBudgetRequest(receipt.budget))}`,
+					`budget_effective=${JSON.stringify(formatEffectiveBudget(receipt.budget))}`,
+					`budget_reason=${JSON.stringify(formatBudgetReasons(receipt.budget))}`,
+				];
 	return [
 		canonical,
 		`receipt_integrity=verified/v${receipt.integrity.version}/${receipt.integrity.algorithm}`,
 		`evidence_verification=${verification.state}/${verification.basis}`,
+		`host_verification=${receipt.hostVerification?.status ?? "not_requested"}`,
+		...(responseModelIdObservation ? [responseModelIdObservation] : []),
+		...budget,
 		...receiptAdmissionLabels(receipt),
 		...receiptActivityLabels(receipt, status),
 		briefing,

package/src/worker/spec-contract.ts

@@ -48,6 +48,11 @@ export interface WorkerProtectedArtifactState {
 }
 
 /** Concrete dispatch-time budget after recipe policy and operator clamping. */
+export interface WorkerBudgetPhase {
+	toolCalls: number;
+	readReserve: number;
+}
+
 export interface WorkerBudget {
 	/** Agent phase boundary before synthesis or bounded termination. */
 	toolCalls: number;
@@ -57,6 +62,8 @@ export interface WorkerBudget {
 	synthesis: boolean;
 	/** Independent operator-owned attempt ceiling; recipes cannot widen it. */
 	hardCap: number;
+	/** Optional ceiling that a bounded result-contract revision may activate. */
+	revision?: WorkerBudgetPhase;
 }
 
 interface WorkerSpecFields {
@@ -218,6 +225,7 @@ const TOOL_PROFILE_NAMES = [
 	"minimal-local",
 	"science-local",
 	"full-agent",
+	"council-read-only",
 ] as const satisfies ReadonlyArray<ToolProfileName>;
 const WORKER_PRODUCTS = ["orientation"] as const satisfies ReadonlyArray<AgentProduct>;
 const TARGET_LIFECYCLES = ["user-managed", "clio-managed"] as const;
@@ -416,10 +424,16 @@ function validateAllowedTools(value: unknown): void {
 
 function validateWorkerBudget(value: unknown): void {
 	const budget = readRecord(value, "WorkerSpec.budget");
-	const expected = ["hardCap", "readReserve", "synthesis", "toolCalls"];
+	const expected = ["hardCap", "readReserve", "revision", "synthesis", "toolCalls"];
 	const actual = Object.keys(budget).sort();
-	if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
-		throw new Error(`WorkerSpec.budget must contain exactly: ${expected.join(", ")}`);
+	if (
+		actual.some((key) => !expected.includes(key)) ||
+		actual.some((key) => key === "revision" && budget.revision === undefined)
+	) {
+		throw new Error(`WorkerSpec.budget may contain only: ${expected.join(", ")}`);
+	}
+	for (const required of ["hardCap", "readReserve", "synthesis", "toolCalls"] as const) {
+		if (!Object.hasOwn(budget, required)) throw new Error(`WorkerSpec.budget.${required} is required`);
 	}
 	for (const key of ["toolCalls", "readReserve", "hardCap"] as const) {
 		const value = budget[key];
@@ -436,6 +450,33 @@ function validateWorkerBudget(value: unknown): void {
 		throw new Error("WorkerSpec.budget.readReserve must be an integer in [0, toolCalls)");
 	}
 	if (typeof budget.synthesis !== "boolean") throw new Error("WorkerSpec.budget.synthesis must be a boolean");
+	if (budget.revision !== undefined) {
+		const revision = readRecord(budget.revision, "WorkerSpec.budget.revision");
+		const revisionKeys = Object.keys(revision).sort();
+		if (revisionKeys.length !== 2 || revisionKeys[0] !== "readReserve" || revisionKeys[1] !== "toolCalls") {
+			throw new Error("WorkerSpec.budget.revision must contain exactly: readReserve, toolCalls");
+		}
+		for (const key of ["toolCalls", "readReserve"] as const) {
+			if (typeof revision[key] !== "number" || !Number.isSafeInteger(revision[key])) {
+				throw new Error(`WorkerSpec.budget.revision.${key} must be a safe integer`);
+			}
+		}
+		if ((revision.toolCalls as number) < (budget.toolCalls as number)) {
+			throw new Error("WorkerSpec.budget.revision.toolCalls must not be smaller than WorkerSpec.budget.toolCalls");
+		}
+		if (
+			(revision.toolCalls as number) === (budget.toolCalls as number) &&
+			(revision.readReserve as number) <= (budget.readReserve as number)
+		) {
+			throw new Error("WorkerSpec.budget.revision must increase toolCalls or readReserve");
+		}
+		if ((revision.toolCalls as number) > (budget.hardCap as number)) {
+			throw new Error("WorkerSpec.budget.revision.toolCalls must not exceed WorkerSpec.budget.hardCap");
+		}
+		if ((revision.readReserve as number) < 0 || (revision.readReserve as number) >= (revision.toolCalls as number)) {
+			throw new Error("WorkerSpec.budget.revision.readReserve must be an integer in [0, toolCalls)");
+		}
+	}
 }
 
 function validateRuntimeCapabilityDecision(value: unknown, source: string): void {