@iowarp/clio-coder 0.3.7 → 0.3.8

package/src/core/path-boundary.ts

@@ -0,0 +1,100 @@
+import path from "node:path";
+
+export const PATH_BOUNDARY_MAX_ENTRIES = 32;
+
+export type PathBoundary = ReadonlyArray<string>;
+
+type PathBoundaryErrorCode = "empty" | "separator" | "glob" | "absolute" | "parent" | "dot";
+
+export class PathBoundaryError extends Error {
+	readonly code: PathBoundaryErrorCode;
+
+	constructor(code: PathBoundaryErrorCode, message: string) {
+		super(message);
+		this.name = "PathBoundaryError";
+		this.code = code;
+	}
+}
+
+const GLOB_CHARACTERS = /[*?[\]{}]/u;
+
+/** Normalize one repository-relative boundary entry. */
+export function normalizePathBoundaryEntry(entry: string): string {
+	const raw = entry.trim();
+	if (raw.length === 0) throw new PathBoundaryError("empty", "write boundary: entry must be a non-empty path");
+	if (raw.includes("\\")) {
+		throw new PathBoundaryError("separator", `write boundary: entry '${entry}' must use '/' separators`);
+	}
+	if (GLOB_CHARACTERS.test(raw)) {
+		throw new PathBoundaryError("glob", `write boundary: entry '${entry}' looks like a glob, which v1 does not support`);
+	}
+	if (raw.startsWith("/") || /^[A-Za-z]:/u.test(raw)) {
+		throw new PathBoundaryError("absolute", `write boundary: entry '${entry}' must be repository-relative, not absolute`);
+	}
+	const subtree = raw.endsWith("/");
+	const segments = raw.split("/").filter((segment) => segment.length > 0);
+	if (segments.length === 0) {
+		throw new PathBoundaryError("empty", `write boundary: entry '${entry}' must name a path inside the repository`);
+	}
+	for (const segment of segments) {
+		if (segment === "..") {
+			throw new PathBoundaryError("parent", `write boundary: entry '${entry}' must not contain '..'`);
+		}
+		if (segment === ".") {
+			throw new PathBoundaryError("dot", `write boundary: entry '${entry}' must not contain '.' segments`);
+		}
+	}
+	const joined = segments.join("/");
+	return subtree ? `${joined}/` : joined;
+}
+
+/** Normalize, deduplicate, and sort a boundary declaration. */
+export function normalizePathBoundary(entries: ReadonlyArray<string>): string[] {
+	if (entries.length > PATH_BOUNDARY_MAX_ENTRIES) {
+		throw new Error(`write boundary: at most ${PATH_BOUNDARY_MAX_ENTRIES} entries may be declared`);
+	}
+	return [...new Set(entries.map(normalizePathBoundaryEntry))].sort();
+}
+
+function toPosixBoundaryPath(value: string): string {
+	return value.split("\\").join("/");
+}
+
+function isDirectoryPathBoundary(entry: string): boolean {
+	return toPosixBoundaryPath(entry).endsWith("/");
+}
+
+/** Convert a path to the subtree form spoken by the boundary grammar. */
+export function asDirectoryPathBoundary(entry: string): string {
+	const normalized = toPosixBoundaryPath(entry);
+	return normalized.endsWith("/") ? normalized : `${normalized}/`;
+}
+
+/** Resolve a repository-relative boundary while retaining exact or subtree meaning. */
+export function resolvePathBoundary(cwd: string, entry: string): string {
+	const directory = isDirectoryPathBoundary(entry);
+	const withoutMarker = directory ? entry.slice(0, -1) : entry;
+	const resolved = toPosixBoundaryPath(path.resolve(cwd, withoutMarker));
+	return directory ? asDirectoryPathBoundary(resolved) : resolved;
+}
+
+/** Whether one boundary entry contains another exact path or subtree. */
+export function pathBoundaryEntryCovers(outer: string, inner: string): boolean {
+	const normalizedOuter = toPosixBoundaryPath(outer);
+	const normalizedInner = toPosixBoundaryPath(inner);
+	return normalizedOuter.endsWith("/")
+		? normalizedInner.startsWith(normalizedOuter)
+		: !normalizedInner.endsWith("/") && normalizedInner === normalizedOuter;
+}
+
+/** Whether any entry in a boundary contains the candidate. */
+export function pathBoundaryCovers(boundary: PathBoundary, candidate: string): boolean {
+	return boundary.some((entry) => pathBoundaryEntryCovers(entry, candidate));
+}
+
+/** Whether two boundary declarations share any possible path. */
+export function pathBoundariesOverlap(left: PathBoundary, right: PathBoundary): boolean {
+	return left.some((entry) =>
+		right.some((other) => pathBoundaryEntryCovers(entry, other) || pathBoundaryEntryCovers(other, entry)),
+	);
+}

package/src/domains/agents/extension.ts

@@ -1,12 +1,9 @@
-import path from "node:path";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
-import { resolvePackageRoot } from "../../core/package-root.js";
-import { clioConfigDir } from "../../core/xdg.js";
 import { assertAgentIdNamespace } from "../config/agent-namespace.js";
 import type { ConfigContract } from "../config/contract.js";
 import type { AgentsContract } from "./contract.js";
 import type { AgentRecipe } from "./recipe.js";
-import { type AgentRecipeDiagnostic, loadRecipesFromDir, mergeRecipes } from "./registry.js";
+import { type AgentRecipeDiagnostic, discoverAgentRecipes } from "./registry.js";
 import { type AgentSpec, normalizeAgentSpec } from "./spec.js";
 
 export function createAgentsBundle(_context: DomainContext): DomainBundle<AgentsContract> {
@@ -15,14 +12,8 @@ export function createAgentsBundle(_context: DomainContext): DomainBundle<Agents
 	let diagnostics: ReadonlyArray<AgentRecipeDiagnostic> = [];
 
 	function discover(): void {
-		const builtinDir = path.join(resolvePackageRoot(), "src", "domains", "agents", "builtins");
-		const userDir = path.join(clioConfigDir(), "agents");
-		const projectDir = path.join(process.cwd(), ".clio-coder", "agents");
 		const nextDiagnostics: AgentRecipeDiagnostic[] = [];
-		const builtin = loadRecipesFromDir({ dir: builtinDir, source: "builtin" }, nextDiagnostics);
-		const user = loadRecipesFromDir({ dir: userDir, source: "user" }, nextDiagnostics);
-		const project = loadRecipesFromDir({ dir: projectDir, source: "project" }, nextDiagnostics);
-		const merged = mergeRecipes(builtin, user, project);
+		const merged = discoverAgentRecipes(process.cwd(), nextDiagnostics);
 		const config = _context.getContract<ConfigContract>("config");
 		assertAgentIdNamespace(merged, config?.get()?.delegation?.agents ?? []);
 		recipes = merged;

package/src/domains/agents/fleet-contract.ts

@@ -16,6 +16,7 @@ import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { resolvePackageRoot } from "../../core/package-root.js";
 import { clioConfigDir } from "../../core/xdg.js";
+import { enabledExtensionResourceRoots } from "../extensions/index.js";
 import { type FleetCommandRegistry, loadFleetCommands } from "./fleet-commands.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { normalizeWriteBoundary, WRITE_BOUNDARY_MAX_ENTRIES } from "./write-boundary.js";
@@ -198,7 +199,7 @@ export interface FleetContract {
 	path: string;
 }
 
-export type FleetContractSource = "builtin" | "user" | "project";
+export type FleetContractSource = "builtin" | "extension" | "user" | "project";
 
 export interface FleetContractListing {
 	name: string;
@@ -758,6 +759,7 @@ export function parseFleetContract(raw: string, sourcePath: string): FleetContra
 	}
 	if (version < FLEET_WRITE_BOUNDARY_VERSION) assertNoWritesBefore(frontmatter, sourcePath, version);
 	if (version < FLEET_DYNAMIC_STEP_VERSION) assertNoV5FieldsBefore(frontmatter, sourcePath, version);
+	if (version >= FLEET_DYNAMIC_STEP_VERSION) assertNoGateWrites(frontmatter, sourcePath);
 	const schemaError = firstSchemaError(frontmatter, version);
 	if (schemaError !== null) {
 		throw new Error(`fleet contract ${sourcePath}: ${schemaError}`);
@@ -849,6 +851,17 @@ function assertNoWritesBefore(frontmatter: Record<string, unknown>, sourcePath:
 	}
 }
 
+function assertNoGateWrites(frontmatter: Record<string, unknown>, sourcePath: string): void {
+	for (const value of Array.isArray(frontmatter.steps) ? frontmatter.steps : []) {
+		if (typeof value !== "object" || value === null) continue;
+		const step = value as Record<string, unknown>;
+		if (step.kind !== "gate" || typeof step.id !== "string" || step.id.length === 0 || !("writes" in step)) continue;
+		throw new Error(
+			`fleet contract ${sourcePath}: gate step '${step.id}' must not declare 'writes'; its write boundary is derived from 'path'`,
+		);
+	}
+}
+
 function assertNoV5FieldsBefore(frontmatter: Record<string, unknown>, sourcePath: string, version: number): void {
 	const forbidden = ["target", "profile"] as const;
 	if ("writers" in frontmatter) {
@@ -958,13 +971,22 @@ function builtinFleetsDir(): string {
 	return join(resolvePackageRoot(), "src", "domains", "agents", "fleets");
 }
 
+function fleetSources(cwd: string): ReadonlyArray<{ dir: string; source: FleetContractSource }> {
+	return [
+		{ dir: builtinFleetsDir(), source: "builtin" },
+		...enabledExtensionResourceRoots("fleets", cwd)
+			.sort((left, right) => left.source.localeCompare(right.source))
+			.map((root) => ({ dir: root.path, source: "extension" as const })),
+		{ dir: join(clioConfigDir(), "fleets"), source: "user" },
+		{ dir: fleetsDir(cwd), source: "project" },
+	];
+}
+
 function fleetContractPath(cwd: string, name: string): { path: string; source: FleetContractSource } | null {
-	const projectPath = join(fleetsDir(cwd), `${name}.md`);
-	if (existsSync(projectPath)) return { path: projectPath, source: "project" };
-	const userPath = join(clioConfigDir(), "fleets", `${name}.md`);
-	if (existsSync(userPath)) return { path: userPath, source: "user" };
-	const builtinPath = join(builtinFleetsDir(), `${name}.md`);
-	if (existsSync(builtinPath)) return { path: builtinPath, source: "builtin" };
+	for (const source of [...fleetSources(cwd)].reverse()) {
+		const candidate = join(source.dir, `${name}.md`);
+		if (existsSync(candidate)) return { path: candidate, source: source.source };
+	}
 	return null;
 }
 
@@ -1004,11 +1026,7 @@ export function listFleetContracts(cwd: string): FleetContractListing[] {
 		registryError = err instanceof Error ? err.message : String(err);
 	}
 	const listings = new Map<string, FleetContractListing>();
-	const sources: ReadonlyArray<{ dir: string; source: FleetContractSource }> = [
-		{ dir: builtinFleetsDir(), source: "builtin" },
-		{ dir: join(clioConfigDir(), "fleets"), source: "user" },
-		{ dir: fleetsDir(cwd), source: "project" },
-	];
+	const sources = fleetSources(cwd);
 	for (const { dir, source } of sources) {
 		for (const file of listDirectory(dir)) {
 			const path = join(dir, file);

package/src/domains/agents/recipe.ts

@@ -131,7 +131,7 @@ export interface AgentRecipe {
 	resultContract: ResultContract;
 	product?: AgentProduct;
 	tags: ReadonlyArray<string>;
-	source: "builtin" | "user" | "project";
+	source: "builtin" | "extension" | "user" | "project";
 	filepath: string;
 	/** Persona prompt body. */
 	body: string;
@@ -140,6 +140,12 @@ export interface AgentRecipe {
 export interface RecipeSource {
 	dir: string;
 	source: AgentRecipe["source"];
+	/** Project root whose extension and skill resources are being discovered. */
+	cwd?: string;
+	/** Stable provenance used to correlate resources from one extension. */
+	origin?: string;
+	/** The declaring extension's skill root; extension agents may bind only here. */
+	skillRoot?: string;
 }
 
 export function recipeIdFromPath(absPath: string, rootDir: string): string {

package/src/domains/agents/registry.ts

@@ -1,5 +1,8 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { clioConfigDir } from "../../core/xdg.js";
+import { enabledExtensionResourceRoots } from "../extensions/index.js";
 import { loadSkills } from "../resources/skills/loader.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { type AgentRecipe, type RecipeSource, recipeIdFromPath } from "./recipe.js";
@@ -20,10 +23,29 @@ function resolveBoundSkills(recipe: AgentRecipe, source: RecipeSource): AgentRec
 	// only the operator's discovered skill roots; a recipe cannot smuggle an
 	// arbitrary filesystem path into worker context through a skill name.
 	const packageSkills = path.resolve(source.dir, "..", "..", "..", "..", "skills");
-	const skills = loadSkills({
-		cwd: process.cwd(),
-		...(source.source === "builtin" && existsSync(packageSkills) ? { explicitSkillPaths: [packageSkills] } : {}),
-	});
+	if (source.source === "extension" && source.skillRoot === undefined) {
+		throw new Error(`agent recipe: ${recipe.filepath}: extension declares bound skills but no skills resource root`);
+	}
+	const skills =
+		source.source === "extension"
+			? loadSkills({
+					cwd: source.cwd ?? process.cwd(),
+					disableDiscovery: true,
+					explicitSkillPaths: source.skillRoot === undefined ? [] : [source.skillRoot],
+				})
+			: loadSkills({
+					cwd: source.cwd ?? process.cwd(),
+					...(source.source === "builtin" && existsSync(packageSkills) ? { explicitSkillPaths: [packageSkills] } : {}),
+				});
+	if (source.source === "extension" && source.skillRoot !== undefined) {
+		const canonicalRoot = realpathSync(source.skillRoot);
+		for (const skill of skills.items) {
+			const relative = path.relative(canonicalRoot, realpathSync(skill.filePath));
+			if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+				throw new Error(`agent recipe: ${recipe.filepath}: bound skill escapes its extension: ${skill.filePath}`);
+			}
+		}
+	}
 	const byName = new Map(skills.items.map((skill) => [skill.name, skill.filePath]));
 	const missing = recipe.skills.filter((skill) => !byName.has(skill));
 	if (missing.length > 0) {
@@ -95,6 +117,10 @@ export function mergeRecipes(...sources: ReadonlyArray<ReadonlyArray<AgentRecipe
 				continue;
 			}
 			const builtin = builtinById.get(recipe.id);
+			if (recipe.source === "extension" && builtin) {
+				process.stderr.write(`[clio:agents] ignore override id=${recipe.id} by=extension reason=reserved-builtin\n`);
+				continue;
+			}
 			if (recipe.source === "user" && builtin && isShadowAgent(normalizeAgentSpec(builtin))) {
 				process.stderr.write(`[clio:agents] ignore override id=${recipe.id} by=user reason=reserved-shadow\n`);
 				continue;
@@ -109,3 +135,45 @@ export function mergeRecipes(...sources: ReadonlyArray<ReadonlyArray<AgentRecipe
 	}
 	return Array.from(byId.values()).sort((left, right) => left.id.localeCompare(right.id));
 }
+
+/**
+ * Discover the one native-agent catalog used by listing, fleet admission, and
+ * dispatch. Extension recipes occupy the same precedence slot as extension
+ * fleets: after builtins and before operator/user and project recipes. Their
+ * skill bindings remain constrained to the declaring extension's skill root.
+ */
+export function discoverAgentRecipes(
+	cwd = process.cwd(),
+	diagnostics: AgentRecipeDiagnostic[] = [],
+): ReadonlyArray<AgentRecipe> {
+	const builtin = loadRecipesFromDir(
+		{
+			dir: path.join(resolvePackageRoot(), "src", "domains", "agents", "builtins"),
+			source: "builtin",
+			cwd,
+		},
+		diagnostics,
+	);
+	const skillRoots = new Map(enabledExtensionResourceRoots("skills", cwd).map((root) => [root.source, root.path]));
+	const extensionRecipes = enabledExtensionResourceRoots("agents", cwd)
+		.sort((left, right) => left.source.localeCompare(right.source))
+		.map((root) => {
+			const skillRoot = skillRoots.get(root.source);
+			return loadRecipesFromDir(
+				{
+					dir: root.path,
+					source: "extension",
+					cwd,
+					origin: root.source,
+					...(skillRoot === undefined ? {} : { skillRoot }),
+				},
+				diagnostics,
+			);
+		});
+	const user = loadRecipesFromDir({ dir: path.join(clioConfigDir(), "agents"), source: "user", cwd }, diagnostics);
+	const project = loadRecipesFromDir(
+		{ dir: path.join(cwd, ".clio-coder", "agents"), source: "project", cwd },
+		diagnostics,
+	);
+	return mergeRecipes(builtin, ...extensionRecipes, user, project);
+}

package/src/domains/agents/result-contract.ts

@@ -8,6 +8,27 @@ export type ResultContract =
 	| { kind: "scout-report" }
 	| { kind: "verifier-report" }
 	| { kind: "council-report" }
+	/**
+	 * One council member's ballot under `synthesis: "vote"`.
+	 *
+	 * The vote is a strict majority over the members' `verdict` fields, computed
+	 * by the coordinator with no model call. Nothing asked a member for that
+	 * field before this kind existed, and nothing could: an unnamed council
+	 * seats the builtin `researcher`, whose `research-report` accepts only
+	 * `source` and `findings`, so a member that emitted a verdict failed its own
+	 * postcondition and a member that obeyed its postcondition emitted no
+	 * verdict. Every vote therefore resolved to `no_verdict_field` with an empty
+	 * tally, on every input (#230).
+	 *
+	 * The ballot is the coordinator's postcondition for that slot, not the
+	 * recipe's, in the same way `reviewer` and the compete `judge` answer the
+	 * gate that dispatched them. It rides in as a `resultContractOverride` on
+	 * the member request, so the seated recipe keeps its persona and any recipe
+	 * can be voted with. No recipe may declare it: `parseResultContract` rejects
+	 * the kind, and a Scout subtask may not request it, because it is a
+	 * topology's ballot rather than an agent's work product.
+	 */
+	| { kind: "council-ballot" }
 	| { kind: "debugger-report" }
 	| { kind: "research-report" }
 	| { kind: "mutation-report" }
@@ -273,6 +294,67 @@ export function parseDelegationPlanResult(output: string | null): DelegationPlan
 	return { tasks };
 }
 
+/**
+ * Longest verdict token a ballot may cast, in bytes.
+ *
+ * A tally groups members by their exact verdict string, so a verdict that is a
+ * sentence can only ever tie with itself and a council of any size reports
+ * `no_majority`. The bound is what makes a majority reachable: it forces the
+ * decision into a token members can match (`yes`, `no`, `keep`, an option
+ * name) and pushes the reasoning into `text`, where the report already reads
+ * it. A newline is refused for the same reason.
+ */
+export const COUNCIL_BALLOT_VERDICT_MAX_BYTES = 64;
+
+/**
+ * The ballot's wire shape, quoted verbatim to the member that must cast it and
+ * by the repair round that corrects it. Exported because the council composes
+ * the member's ask from it, which is the rule this module already states: a
+ * contract's example is written once so a prompt cannot drift from its
+ * validator.
+ */
+export const COUNCIL_BALLOT_SHAPE = '{"verdict":"yes","text":"the answer and the evidence behind it"}';
+
+interface CouncilBallot {
+	/** The comparable token the tally counts. */
+	verdict: string;
+	/** The member's answer in prose, which is what the council report shows. */
+	text: string;
+}
+
+/**
+ * Read a council member's ballot. The council reads a verdict out of the
+ * member's terminal text with its own reader, because the judge synthesis
+ * carries the same two fields under no contract at all; this one is what
+ * decides whether the member is allowed to seal that text as its result.
+ */
+function parseCouncilBallot(output: string | null): CouncilBallot | null {
+	const parsed = parseJson(output);
+	if (!parsed.ok) return null;
+	const value = parsed.value;
+	if (!hasOnlyKeys(value, ["verdict", "text"]) || !string(value.verdict) || !string(value.text)) return null;
+	const verdict = value.verdict.trim();
+	if (verdict.includes("\n") || Buffer.byteLength(verdict, "utf8") > COUNCIL_BALLOT_VERDICT_MAX_BYTES) return null;
+	return { verdict, text: value.text.trim() };
+}
+
+function validateCouncilBallot(contract: ResultContract, output: string | null): ResultContractValidation {
+	const parsed = parseJson(output);
+	if (!parsed.ok) return failure(contract, "unmeasured", parsed.reason);
+	const ballot = parseCouncilBallot(output);
+	if (ballot === null) {
+		return failure(
+			contract,
+			"unmeasured",
+			`A council ballot must carry only verdict and text, both non-empty strings, with verdict a single line of at most ${COUNCIL_BALLOT_VERDICT_MAX_BYTES} bytes so the tally can match it against the other members`,
+		);
+	}
+	// Unmeasured, like every other contract whose shape carries no correctness
+	// claim: casting a well-formed ballot says nothing about whether the member
+	// was right, and the tally is a count of opinions rather than a check.
+	return success(contract, "unmeasured", ballot);
+}
+
 export interface CouncilReportMember {
 	label: string;
 	runId: string;
@@ -1249,6 +1331,8 @@ export function validateResultContract(input: ResultContractValidationInput): Re
 				? failure(input.contract, "fail", "council-report is malformed")
 				: success(input.contract, "unmeasured", { council: report });
 		}
+		case "council-ballot":
+			return validateCouncilBallot(input.contract, input.output);
 		case "debugger-report":
 			return validateDebugger(input.contract, input.output);
 		case "research-report":
@@ -1347,6 +1431,8 @@ function resultContractShape(contract: ResultContract): string {
 			return '{"verdict":"pass","checks":[{"name":"npm run typecheck","passed":true,"evidence":"exit 0"}]}';
 		case "council-report":
 			return '{"members":[{"label":"alpha","runId":"run-1","round":1,"answer":"..."}],"synthesis":{"kind":"none"}}';
+		case "council-ballot":
+			return COUNCIL_BALLOT_SHAPE;
 		case "debugger-report":
 			return '{"diagnosis":"...","reproduction":"reproduced","evidence":["..."]}';
 		case "research-report":
@@ -1463,8 +1549,31 @@ export function resultContractRepairMessages(
 	] as const;
 }
 
-/** Strict frontmatter parser for the one recipe result-contract schema. */
-export function parseResultContract(value: unknown, sourcePath: string): ResultContract {
+/** Kinds an agent recipe may declare in its frontmatter. */
+const RECIPE_DECLARABLE_KINDS = [
+	"scout-report",
+	"verifier-report",
+	"council-report",
+	"debugger-report",
+	"research-report",
+	"mutation-report",
+	"provenance-report",
+	"oracle-report",
+	"external-delegation",
+	"artifact-report",
+	"context-handbook",
+	"delegation-plan",
+] as const;
+
+/**
+ * Kinds the coordinator authors and hands to a worker on the wire, which no
+ * recipe may declare. A council ballot is the topology's postcondition for a
+ * vote member's slot, so it arrives as a `resultContractOverride` on the
+ * request and never out of frontmatter.
+ */
+const COORDINATOR_AUTHORED_KINDS = ["council-ballot"] as const;
+
+function parseContract(value: unknown, sourcePath: string, kinds: ReadonlyArray<string>): ResultContract {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) {
 		throw new Error(`agent recipe: ${sourcePath}: resultContract must be an object`);
 	}
@@ -1481,22 +1590,24 @@ export function parseResultContract(value: unknown, sourcePath: string): ResultC
 		}
 		return { kind: "architect-plan", path: record.path };
 	}
-	const kinds = [
-		"scout-report",
-		"verifier-report",
-		"council-report",
-		"debugger-report",
-		"research-report",
-		"mutation-report",
-		"provenance-report",
-		"oracle-report",
-		"external-delegation",
-		"artifact-report",
-		"context-handbook",
-		"delegation-plan",
-	] as const;
-	if (!(kinds as ReadonlyArray<string>).includes(record.kind) || !only("kind")) {
+	if (!kinds.includes(record.kind) || !only("kind")) {
 		throw new Error(`agent recipe: ${sourcePath}: resultContract.kind is unsupported or has unknown keys`);
 	}
 	return { kind: record.kind as Exclude<ResultContract["kind"], "architect-plan"> };
 }
+
+/** Strict frontmatter parser for the one recipe result-contract schema. */
+export function parseResultContract(value: unknown, sourcePath: string): ResultContract {
+	return parseContract(value, sourcePath, RECIPE_DECLARABLE_KINDS);
+}
+
+/**
+ * The same parser for a contract that arrived on a WorkerSpec. It admits what a
+ * recipe may declare plus what the coordinator may author, because a dispatch
+ * request can override the seated recipe's postcondition and the worker has to
+ * be able to read the contract it will be validated against. Keeping the recipe
+ * parser strict is the point: a recipe still cannot claim a coordinator's kind.
+ */
+export function parseWorkerResultContract(value: unknown, sourcePath: string): ResultContract {
+	return parseContract(value, sourcePath, [...RECIPE_DECLARABLE_KINDS, ...COORDINATOR_AUTHORED_KINDS]);
+}

package/src/domains/agents/write-boundary.ts

@@ -1,3 +1,12 @@
+import {
+	normalizePathBoundary,
+	normalizePathBoundaryEntry,
+	PATH_BOUNDARY_MAX_ENTRIES,
+	type PathBoundary,
+	pathBoundariesOverlap,
+	pathBoundaryCovers,
+} from "../../core/path-boundary.js";
+
 /**
  * Declared write boundaries: the repo paths a fleet step is allowed to change.
  *
@@ -30,37 +39,14 @@
  * a step that needs more of the tree than that should say `workspace` and mean
  * it in a contract that does not claim a boundary.
  */
-export const WRITE_BOUNDARY_MAX_ENTRIES = 32;
+export const WRITE_BOUNDARY_MAX_ENTRIES = PATH_BOUNDARY_MAX_ENTRIES;
 
 /** A normalized allowlist. Empty means "changes nothing", which is `readonly`. */
-export type WriteBoundary = ReadonlyArray<string>;
-
-const GLOB_CHARACTERS = /[*?[\]{}]/u;
+export type WriteBoundary = PathBoundary;
 
 /** Normalize one declared entry, or throw explaining exactly what is wrong. */
 export function normalizeWriteBoundaryEntry(entry: string): string {
-	const raw = entry.trim();
-	if (raw.length === 0) throw new Error("write boundary: entry must be a non-empty path");
-	if (raw.includes("\\")) {
-		throw new Error(`write boundary: entry '${entry}' must use '/' separators`);
-	}
-	if (GLOB_CHARACTERS.test(raw)) {
-		throw new Error(`write boundary: entry '${entry}' looks like a glob, which v1 does not support`);
-	}
-	if (raw.startsWith("/") || /^[A-Za-z]:/u.test(raw)) {
-		throw new Error(`write boundary: entry '${entry}' must be repository-relative, not absolute`);
-	}
-	const subtree = raw.endsWith("/");
-	const segments = raw.split("/").filter((segment) => segment.length > 0);
-	if (segments.length === 0) {
-		throw new Error(`write boundary: entry '${entry}' must name a path inside the repository`);
-	}
-	for (const segment of segments) {
-		if (segment === "..") throw new Error(`write boundary: entry '${entry}' must not contain '..'`);
-		if (segment === ".") throw new Error(`write boundary: entry '${entry}' must not contain '.' segments`);
-	}
-	const joined = segments.join("/");
-	return subtree ? `${joined}/` : joined;
+	return normalizePathBoundaryEntry(entry);
 }
 
 /**
@@ -69,38 +55,17 @@ export function normalizeWriteBoundaryEntry(entry: string): string {
  * and a sealed verdict can both carry.
  */
 export function normalizeWriteBoundary(entries: ReadonlyArray<string>): string[] {
-	if (entries.length > WRITE_BOUNDARY_MAX_ENTRIES) {
-		throw new Error(`write boundary: at most ${WRITE_BOUNDARY_MAX_ENTRIES} entries may be declared`);
-	}
-	const normalized = new Set(entries.map(normalizeWriteBoundaryEntry));
-	// A file entry covered by a declared subtree is redundant, not an error: the
-	// operator said the directory, and saying one of its files again changes
-	// nothing about what is allowed.
-	return [...normalized].sort();
-}
-
-/** Repo-relative path with the separators this grammar speaks. */
-function toRepoRelativePosix(path: string): string {
-	return path.split("\\").join("/");
+	return normalizePathBoundary(entries);
 }
 
 /** Whether the boundary permits a change to one repo-relative path. */
 export function writeBoundaryCovers(boundary: WriteBoundary, path: string): boolean {
-	const candidate = toRepoRelativePosix(path);
-	return boundary.some((entry) => (entry.endsWith("/") ? candidate.startsWith(entry) : candidate === entry));
-}
-
-/** Whether two declared entries can describe the same path. */
-function entriesOverlap(left: string, right: string): boolean {
-	if (left === right) return true;
-	if (left.endsWith("/") && right.startsWith(left)) return true;
-	if (right.endsWith("/") && left.startsWith(right)) return true;
-	return false;
+	return pathBoundaryCovers(boundary, path);
 }
 
 /** Whether two boundaries share any path. Empty boundaries never overlap. */
 export function writeBoundariesOverlap(left: WriteBoundary, right: WriteBoundary): boolean {
-	return left.some((entry) => right.some((other) => entriesOverlap(entry, other)));
+	return pathBoundariesOverlap(left, right);
 }
 
 /** Operator-facing rendering, used verbatim in violation messages. */