@iowarp/clio-coder 0.3.8 → 0.4.0

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

@@ -105,6 +105,15 @@ export interface ResultContractFilesystem {
 	 * calling an unreadable path fabricated.
 	 */
 	pathExists?(path: string): boolean;
+	/**
+	 * Whether this location is a directory. Optional for the same reason as
+	 * `pathExists`: a contract that only needs a file's bytes never asks. A
+	 * Scout citation does, because a survey task cites directories, and a
+	 * directory has no bytes to read and no line to ground. Absent means the
+	 * distinction is unobservable here, so an unreadable location stays
+	 * unreadable rather than being assumed to be a directory.
+	 */
+	isDirectory?(path: string): boolean;
 }
 
 /**
@@ -792,6 +801,41 @@ function parseChecks(value: unknown): VerifierCheck[] | null {
 
 type ScoutCitationEvidence = ScoutCitation & { contentDigest: string };
 
+/**
+ * Where a citation lands relative to the workspace root, after the written form
+ * is normalized away.
+ *
+ * A model writes the same location six ways: `src`, `./src`, `src/`, `./src/`,
+ * and for the root itself `.` or `./`. `path.resolve` collapses every one of
+ * them, so the containment question is answered on the resolved pair and never
+ * on the string the model typed.
+ *
+ * The root is the case that broke. `path.relative(cwd, cwd)` is the empty
+ * string, and the check read empty as "not inside", which is exactly backwards:
+ * the workspace root is the one path guaranteed to be contained. A
+ * directory-survey Scout cites `.` because that is what it surveyed, and four
+ * runs died `result_contract_exhausted` on evidence that never left the
+ * workspace. Containment is unchanged for a real escape, which still resolves
+ * to a `..` segment or an absolute path outside the root.
+ */
+function citationWithinWorkspace(cwd: string, citedPath: string): boolean {
+	const relative = path.relative(cwd, citedPath);
+	if (relative === "") return true;
+	return !(relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative));
+}
+
+/**
+ * A directory citation carries no bytes and no line, so its evidence digest is
+ * bound to the location instead. Prefixed so it can never collide with the
+ * content digest of a file that happens to hold the same text.
+ */
+function directoryCitationDigest(cwd: string, citedPath: string): string {
+	const relative = path.relative(cwd, citedPath);
+	return createHash("sha256")
+		.update(`directory:${relative === "" ? "." : relative}`, "utf8")
+		.digest("hex");
+}
+
 /** One citation against the workspace and, where known, against this run's own reads. */
 function validateScoutCitation(
 	input: ResultContractValidationInput,
@@ -799,10 +843,17 @@ function validateScoutCitation(
 ): { ok: true; evidence: ScoutCitationEvidence } | { ok: false; reason: string } {
 	const cwd = path.resolve(input.cwd);
 	const citedPath = path.resolve(cwd, citation.path);
-	const relative = path.relative(cwd, citedPath);
-	if (relative === "" || relative.startsWith(`..${path.sep}`) || relative === ".." || path.isAbsolute(relative)) {
+	if (!citationWithinWorkspace(cwd, citedPath)) {
 		return { ok: false, reason: `Scout citation path escapes the workspace: ${citation.path}` };
 	}
+	// A directory is a legal reconnaissance location. Existence is the whole
+	// check available: there is no content to digest, no line count to bound the
+	// cited line against, and no read span to ground it in, because a survey
+	// lists a directory rather than reading it. Requiring a live read here would
+	// reject the correct answer to every directory-survey task.
+	if (input.filesystem.isDirectory?.(citedPath) === true) {
+		return { ok: true, evidence: { ...citation, contentDigest: directoryCitationDigest(cwd, citedPath) } };
+	}
 	const content = input.filesystem.readFile(citedPath);
 	if (content === null) return { ok: false, reason: `Scout citation cannot be read: ${citation.path}` };
 	const lineCount = content.split(/\r\n|\r|\n/u).length;
@@ -888,14 +939,57 @@ function groundDegradedScout(
 
 function validateVerifier(contract: ResultContract, output: string | null): ResultContractValidation {
 	const parsed = parseJson(output);
-	if (!parsed.ok) return failure(contract, "fail", parsed.reason);
+	if (!parsed.ok) return failure(contract, "fail", `Verifier result payload failed: ${parsed.reason}`);
 	const value = parsed.value;
-	if (!hasOnlyKeys(value, ["verdict", "checks"]) || (value.verdict !== "pass" && value.verdict !== "fail")) {
-		return failure(contract, "fail", "Verifier result must carry pass or fail verdict and checks");
+	const unknown = Object.keys(value).filter((key) => key !== "verdict" && key !== "checks");
+	if (unknown.length > 0) {
+		return failure(
+			contract,
+			"fail",
+			`Verifier result field${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")} ${unknown.length === 1 ? "is" : "are"} not legal; legal top-level fields are verdict and checks`,
+		);
 	}
-	const checks = parseChecks(value.checks);
-	if (checks === null || (value.verdict === "pass") !== checks.every((check) => check.passed)) {
-		return failure(contract, "fail", "Verifier verdict must agree with every typed check");
+	if (value.verdict !== "pass" && value.verdict !== "fail") {
+		return failure(contract, "fail", 'Verifier field "verdict" must be one of: pass | fail');
+	}
+	if (!Array.isArray(value.checks) || value.checks.length === 0) {
+		return failure(
+			contract,
+			"fail",
+			'Verifier field "checks" must be a non-empty array of {name, passed, evidence}; each checks[].passed value must be one of: true | false',
+		);
+	}
+	const checks: VerifierCheck[] = [];
+	for (const [index, raw] of value.checks.entries()) {
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+			return failure(contract, "fail", `Verifier field "checks[${index}]" must be an object`);
+		}
+		const check = raw as Record<string, unknown>;
+		const checkUnknown = Object.keys(check).filter((key) => key !== "name" && key !== "passed" && key !== "evidence");
+		if (checkUnknown.length > 0) {
+			return failure(
+				contract,
+				"fail",
+				`Verifier field "checks[${index}].${checkUnknown[0]}" is not legal; legal check fields are name, passed, and evidence`,
+			);
+		}
+		if (!string(check.name)) {
+			return failure(contract, "fail", `Verifier field "checks[${index}].name" must be a non-empty string`);
+		}
+		if (typeof check.passed !== "boolean") {
+			return failure(contract, "fail", `Verifier field "checks[${index}].passed" must be one of: true | false`);
+		}
+		if (!string(check.evidence)) {
+			return failure(contract, "fail", `Verifier field "checks[${index}].evidence" must be a non-empty string`);
+		}
+		checks.push({ name: check.name, passed: check.passed, evidence: check.evidence });
+	}
+	if ((value.verdict === "pass") !== checks.every((check) => check.passed)) {
+		return failure(
+			contract,
+			"fail",
+			'Verifier field "verdict" must agree with every checks[].passed value; verdict legal values are pass | fail and checks[].passed legal values are true | false',
+		);
 	}
 	const verifier: VerifierResult = { verdict: value.verdict, checks };
 	return success(contract, value.verdict, verifier, { verifier });
@@ -1086,23 +1180,39 @@ export function resultContractAuthorship(contract: ResultContract, output: strin
 
 function validateDebugger(contract: ResultContract, output: string | null): ResultContractValidation {
 	const parsed = parseJson(output);
-	if (!parsed.ok) return failure(contract, "unmeasured", parsed.reason);
+	if (!parsed.ok) return failure(contract, "unmeasured", `Debugger result payload failed: ${parsed.reason}`);
 	const value = parsed.value;
+	const unknown = Object.keys(value).filter(
+		(key) => key !== "diagnosis" && key !== "reproduction" && key !== "evidence",
+	);
+	if (unknown.length > 0) {
+		return failure(
+			contract,
+			"unmeasured",
+			`Debugger result field${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")} ${unknown.length === 1 ? "is" : "are"} not legal; legal top-level fields are diagnosis, reproduction, and evidence`,
+		);
+	}
+	if (!string(value.diagnosis)) {
+		return failure(contract, "unmeasured", 'Debugger field "diagnosis" must be a non-empty string');
+	}
 	if (
-		!hasOnlyKeys(value, ["diagnosis", "reproduction", "evidence"]) ||
-		!string(value.diagnosis) ||
-		(value.reproduction !== "reproduced" &&
-			value.reproduction !== "not-reproduced" &&
-			value.reproduction !== "unknown") ||
-		!Array.isArray(value.evidence) ||
-		value.evidence.some((entry) => !string(entry))
+		value.reproduction !== "reproduced" &&
+		value.reproduction !== "not-reproduced" &&
+		value.reproduction !== "unknown"
 	) {
 		return failure(
 			contract,
 			"unmeasured",
-			"Debugger result must carry diagnosis, reproduction status, and evidence without a verdict",
+			'Debugger field "reproduction" must be one of: reproduced | not-reproduced | unknown',
 		);
 	}
+	if (!Array.isArray(value.evidence)) {
+		return failure(contract, "unmeasured", 'Debugger field "evidence" must be an array of strings');
+	}
+	const malformedEvidence = value.evidence.findIndex((entry) => !string(entry));
+	if (malformedEvidence >= 0) {
+		return failure(contract, "unmeasured", `Debugger field "evidence[${malformedEvidence}]" must be a non-empty string`);
+	}
 	return success(contract, "unmeasured", value);
 }
 
@@ -1112,29 +1222,47 @@ function validateResearch(
 	networkAllowed: boolean,
 ): ResultContractValidation {
 	const parsed = parseJson(output);
-	if (!parsed.ok) return failure(contract, "unmeasured", parsed.reason);
+	if (!parsed.ok) return failure(contract, "unmeasured", `Research result payload failed: ${parsed.reason}`);
 	const value = parsed.value;
-	if (
-		!hasOnlyKeys(value, ["source", "findings"]) ||
-		(value.source !== "local" && value.source !== "external") ||
-		!Array.isArray(value.findings)
-	) {
+	const unknown = Object.keys(value).filter((key) => key !== "source" && key !== "findings");
+	if (unknown.length > 0) {
 		return failure(
 			contract,
 			"unmeasured",
-			"Research result must distinguish local or external sources and carry findings",
+			`Research result field${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")} ${unknown.length === 1 ? "is" : "are"} not legal; legal top-level fields are source and findings`,
 		);
 	}
+	if (value.source !== "local" && value.source !== "external") {
+		return failure(contract, "unmeasured", 'Research field "source" must be one of: local | external');
+	}
+	if (!Array.isArray(value.findings)) {
+		return failure(contract, "unmeasured", 'Research field "findings" must be an array of {claim, evidence} objects');
+	}
 	if (value.source === "external" && !networkAllowed) {
-		return failure(contract, "unmeasured", "external research requires an allowed network posture");
+		return failure(
+			contract,
+			"unmeasured",
+			'Research field "source" is external but the run has no allowed network posture; legal values are local | external, and use local for workspace-only evidence',
+		);
 	}
-	for (const finding of value.findings) {
+	for (const [index, finding] of value.findings.entries()) {
 		if (finding === null || typeof finding !== "object" || Array.isArray(finding)) {
-			return failure(contract, "unmeasured", "Research findings must be objects");
+			return failure(contract, "unmeasured", `Research field "findings[${index}]" must be an object`);
 		}
 		const record = finding as Record<string, unknown>;
-		if (!hasOnlyKeys(record, ["claim", "evidence"]) || !string(record.claim) || !string(record.evidence)) {
-			return failure(contract, "unmeasured", "Research findings must carry claim and evidence");
+		const findingUnknown = Object.keys(record).filter((key) => key !== "claim" && key !== "evidence");
+		if (findingUnknown.length > 0) {
+			return failure(
+				contract,
+				"unmeasured",
+				`Research field "findings[${index}].${findingUnknown[0]}" is not legal; legal finding fields are claim and evidence`,
+			);
+		}
+		if (!string(record.claim)) {
+			return failure(contract, "unmeasured", `Research field "findings[${index}].claim" must be a non-empty string`);
+		}
+		if (!string(record.evidence)) {
+			return failure(contract, "unmeasured", `Research field "findings[${index}].evidence" must be a non-empty string`);
 		}
 	}
 	return success(contract, "unmeasured", value);
@@ -1415,10 +1543,11 @@ export const RESULT_CONTRACT_ANCHOR_LIMIT = 12;
 
 /**
  * The exact terminal shape each contract accepts, quoted to the model verbatim.
- * This is the one place a contract's wire example is written; agent recipes and
- * repair rounds both cite it, so a prompt cannot drift from its validator.
+ * This is the one place a contract's wire example is written; agent recipes,
+ * repair rounds, and a fleet node's own answer directive all cite it, so a
+ * prompt cannot drift from its validator.
  */
-function resultContractShape(contract: ResultContract): string {
+export function resultContractShape(contract: ResultContract): string {
 	switch (contract.kind) {
 		case "architect-plan":
 			return `a plan artifact written to ${contract.path}, then optionally {"commitMessage":"...","summary":"..."} describing it`;
@@ -1428,15 +1557,15 @@ function resultContractShape(contract: ResultContract): string {
 			// run already failed twice, so it is told the cheaper exit as well.
 			return '{"findings":[{"claim":"what you observed","path":"src/file.ts","line":1}],"needsSplit":false,"proposedSubtasks":[]} or {"findings":[],"needsSplit":true,"proposedSubtasks":[{"id":"inspect","task":"Inspect the boundary","dependencies":[],"expectedResultContract":"scout-report","requestedAuthority":"read-only"}]} or, if you cannot produce a citation you are sure of, at least {"findings":[{"claim":"what you observed"}]}, which is accepted as an ungrounded lead rather than losing the run';
 		case "verifier-report":
-			return '{"verdict":"pass","checks":[{"name":"npm run typecheck","passed":true,"evidence":"exit 0"}]}';
+			return 'one of {"verdict":"pass","checks":[{"name":"npm run typecheck","passed":true,"evidence":"exit 0"}]} or {"verdict":"fail","checks":[{"name":"npm run typecheck","passed":false,"evidence":"exit 1"}]}; verdict legal values are pass | fail and checks[].passed legal values are true | false';
 		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":["..."]}';
+			return 'one of {"diagnosis":"...","reproduction":"reproduced","evidence":["..."]}, {"diagnosis":"...","reproduction":"not-reproduced","evidence":["..."]}, or {"diagnosis":"...","reproduction":"unknown","evidence":["..."]}; reproduction legal values are reproduced | not-reproduced | unknown';
 		case "research-report":
-			return '{"source":"local","findings":[{"claim":"...","evidence":"..."}]}';
+			return 'one of {"source":"local","findings":[{"claim":"...","evidence":"..."}]} or {"source":"external","findings":[{"claim":"...","evidence":"..."}]}; source legal values are local | external';
 		case "mutation-report":
 			return '{"mutatedPaths":["src/file.ts"],"validations":[{"name":"npm test","passed":true,"evidence":"exit 0"}],"commitMessage":"optional: the commit message for this change","summary":"optional: one line"}';
 		case "provenance-report":

package/src/domains/config/classify.ts

@@ -28,6 +28,9 @@ const HOT_RELOAD_FIELDS = new Set<string>([
 	"modelSelector",
 	"terminal.smoothStreaming",
 	"attribution.gitCommits",
+	// The bridge reads these on every explicit open; no mux re-detection is
+	// needed because the host capability rung remains `panes.enabled`.
+	"panes.yazi",
 	// The watchdog registration reads its settings live on every trigger, so
 	// enabling it, retargeting it, or changing its cadence takes effect on the
 	// next turn boundary without a restart or a session-routing patch.
@@ -61,6 +64,9 @@ const NEXT_TURN_FIELDS = new Set<string>([
 	"delegation",
 	"compaction",
 	"context",
+	// The pre-warm reads its setting when a trigger fires, and every trigger sits
+	// on a turn boundary, so a change takes effect before the next turn runs.
+	"prewarm",
 	"retry",
 ]);
 

package/src/domains/context/codewiki/coordinator.ts

@@ -140,8 +140,16 @@ export function coordinateCodewikiWrite(
 	options: CodewikiCoordinateOptions = {},
 ): Promise<CodewikiCoordinatedResult | null> {
 	const workspace = resolve(cwd);
-	return enqueueWorkspace(workspace, () =>
-		withStateFileLock(codewikiPath(workspace), async () => {
+	return enqueueWorkspace(workspace, () => {
+		// Taking the lease creates the lock's parent, so a project that was never
+		// indexed gained an empty `.clio-coder/` from every successful write: the
+		// incremental refresh is contractually a no-op there, and it was
+		// materializing state before it could say so (issue #248). The check runs
+		// inside the queue, so a writer that built the codewiki ahead of this task
+		// has already finished and this one sees it. The recheck under the lock
+		// stays, and is what still decides the race.
+		if (options.requireExisting && !existsSync(codewikiPath(workspace))) return Promise.resolve(null);
+		return withStateFileLock(codewikiPath(workspace), async () => {
 			if (options.requireExisting && !existsSync(codewikiPath(workspace))) return null;
 			const current = options.readCurrent?.(workspace) ?? readCodewiki(workspace);
 			const request = await select(current, workspace);
@@ -152,8 +160,8 @@ export function coordinateCodewikiWrite(
 			if (wrote) writeCodewiki(workspace, worker.codewiki);
 			await options.afterCommit?.(worker, workspace);
 			return { codewiki: !worker.changed && current ? current : worker.codewiki, worker, wrote };
-		}),
-	);
+		});
+	});
 }
 
 /** Serialize a non-build artifact transaction such as reset with every writer. */

package/src/domains/dispatch/admission-error.ts

@@ -0,0 +1,9 @@
+/** A queued assignment was intentionally canceled before it acquired capacity. */
+export class AdmissionCanceledError extends Error {
+	readonly code = "admission_canceled" as const;
+
+	constructor(message = "dispatch: admission canceled before a capacity slot opened") {
+		super(message);
+		this.name = "AdmissionCanceledError";
+	}
+}

package/src/domains/dispatch/admission.ts

@@ -1,12 +1,16 @@
 import { randomBytes } from "node:crypto";
+import { endpointLabel } from "../providers/endpoint-capacity.js";
 import type { ActionClass } from "../safety/action-classifier.js";
 import type { ScopeSpec } from "../safety/scope.js";
+import { AdmissionCanceledError } from "./admission-error.js";
 import { createAdmissionQueue } from "./admission-queue.js";
 import {
 	acquireCapacityLease,
 	type CapacityLease,
 	type CapacityLimits,
 	capacityLeaseUsage,
+	describeEndpointCapacityHolders,
+	type EndpointCapacityHolders,
 	heartbeatCapacityLease,
 	releaseCapacityLease,
 	renameCapacityLeaseAssignment,
@@ -41,6 +45,7 @@ export interface CapacityAdmissionController {
 	admit(input: {
 		assignmentId: string;
 		nodeId: string;
+		endpointKey?: string;
 		deadlineAt: number;
 		priority?: number;
 		planId?: string;
@@ -105,13 +110,36 @@ const PUMP_MAX_MS = 500;
 function describeAdmissionFailure(input: {
 	state: "canceled" | "timed_out";
 	nodeId: string;
+	endpointKey?: string;
 	waitedMs: number;
 	overdueAtQueueMs: number;
 	queueDepth: number;
 	limits: CapacityLimits;
-	usage: { global: number; nodes: Readonly<Record<string, number>> };
+	usage: {
+		global: number;
+		nodes: Readonly<Record<string, number>>;
+		endpoints: Readonly<Record<string, number>>;
+		endpointHolders?: Readonly<Record<string, EndpointCapacityHolders>>;
+	};
 }): string {
 	if (input.state === "canceled") return "dispatch: admission canceled before a capacity slot opened";
+	if (input.endpointKey !== undefined) {
+		const endpointLimit = input.limits.endpoints[input.endpointKey];
+		const endpointActive = input.usage.endpoints[input.endpointKey] ?? 0;
+		if (endpointLimit !== undefined && endpointActive >= endpointLimit) {
+			const holders = input.usage.endpointHolders?.[input.endpointKey];
+			const occupancy =
+				holders === undefined
+					? "the supplied capacity snapshot does not attribute the occupied slots"
+					: describeEndpointCapacityHolders(holders);
+			const queued = input.queueDepth > 0 ? `, ${input.queueDepth} more queued` : "";
+			return [
+				`dispatch: admission timed out after ${Math.round(input.waitedMs)}ms waiting for an endpoint slot`,
+				` on '${endpointLabel(input.endpointKey)}' (${endpointActive}/${endpointLimit} slots${queued}): ${occupancy}.`,
+				" Wait for the running request to settle or dispatch this work again.",
+			].join("");
+		}
+	}
 	const nodeLimit = input.limits.nodes[input.nodeId];
 	const nodeActive = input.usage.nodes[input.nodeId] ?? 0;
 	const where =
@@ -142,7 +170,12 @@ function describeAdmissionFailure(input: {
 export function createCapacityAdmissionController(options: {
 	limits: () => CapacityLimits;
 	/** Live lease counts for the timeout message; defaults to the durable state file. */
-	usage?: () => { global: number; nodes: Readonly<Record<string, number>> };
+	usage?: () => {
+		global: number;
+		nodes: Readonly<Record<string, number>>;
+		endpoints: Readonly<Record<string, number>>;
+		endpointHolders?: Readonly<Record<string, EndpointCapacityHolders>>;
+	};
 	now?: () => number;
 	maxQueueSize?: number;
 	queueCeilingMs?: number;
@@ -175,7 +208,9 @@ export function createCapacityAdmissionController(options: {
 					admittedLease = request.value();
 					return true;
 				} catch (error) {
-					// Capacity is a wait, not a failure. Anything else fails the request.
+					// Saturation at any capacity dimension is transient and keeps its
+					// assignment in the one bounded admission queue. Unavailable capacity,
+					// draining, corrupt state, and every other error still fail immediately.
 					if (error instanceof Error && /capacity reached/.test(error.message)) return false;
 					queue.fail(request.requestId, error instanceof Error ? error : new Error(String(error)));
 					return false;
@@ -229,12 +264,14 @@ export function createCapacityAdmissionController(options: {
 									memberId: input.reservation.memberId,
 									assignmentId: input.assignmentId,
 									nodeId: input.nodeId,
+									...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
 									limits: options.limits(),
 									nowMs: now(),
 								})
 							: acquireCapacityLease({
 									assignmentId: input.assignmentId,
 									nodeId: input.nodeId,
+									...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
 									limits: options.limits(),
 									nowMs: now(),
 								}),
@@ -242,17 +279,18 @@ export function createCapacityAdmissionController(options: {
 				pumpNow();
 				const outcome = await outcomePromise;
 				if (outcome.state !== "admitted") {
-					throw new Error(
-						describeAdmissionFailure({
-							state: outcome.state,
-							nodeId: input.nodeId,
-							waitedMs: now() - queuedAt,
-							overdueAtQueueMs: queuedAt - input.deadlineAt,
-							queueDepth: queue.size(),
-							limits: options.limits(),
-							usage: options.usage?.() ?? capacityLeaseUsage({ nowMs: now() }),
-						}),
-					);
+					const detail = describeAdmissionFailure({
+						state: outcome.state,
+						nodeId: input.nodeId,
+						...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
+						waitedMs: now() - queuedAt,
+						overdueAtQueueMs: queuedAt - input.deadlineAt,
+						queueDepth: queue.size(),
+						limits: options.limits(),
+						usage: options.usage?.() ?? capacityLeaseUsage({ nowMs: now() }),
+					});
+					if (outcome.state === "canceled") throw new AdmissionCanceledError(detail);
+					throw new Error(detail);
 				}
 				const lease = acquired.get(input.assignmentId);
 				if (!lease) throw new Error("dispatch: admitted request has no capacity lease");