@iowarp/clio-coder 0.3.9 → 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.

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

@@ -2,6 +2,7 @@ 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,
@@ -131,7 +132,12 @@ function describeAdmissionFailure(input: {
 				holders === undefined
 					? "the supplied capacity snapshot does not attribute the occupied slots"
 					: describeEndpointCapacityHolders(holders);
-			return `dispatch: admission denied: endpoint '${endpointLabel(input.endpointKey)}' capacity reached (${endpointActive}/${endpointLimit} slots): ${occupancy}; collect in-flight runs or point workers at a second server`;
+			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];
@@ -202,14 +208,9 @@ export function createCapacityAdmissionController(options: {
 					admittedLease = request.value();
 					return true;
 				} catch (error) {
-					// Endpoint saturation is a named refusal because waiting would keep a
-					// model request queued behind the same inference scheduler. Existing
-					// node and global admission retain their bounded wait behavior.
-					if (error instanceof Error && /endpoint '.*' capacity reached/u.test(error.message)) {
-						queue.fail(request.requestId, error);
-						return false;
-					}
-					// Node and global capacity can wait. 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;
@@ -278,18 +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,
-							...(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() }),
-						}),
-					);
+					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");

package/src/domains/dispatch/capacity-lease.ts

@@ -263,6 +263,26 @@ export function describeEndpointCapacityHolders(holders: EndpointCapacityHolders
 	return `${named} ${total === 1 ? "holds" : "hold"} ${total === 1 ? "the slot" : "the slots"}`;
 }
 
+/**
+ * The ways past a saturated inference endpoint, in the order an operator can
+ * act on them.
+ *
+ * `maxConcurrentRequests` is named because the conservative default of one slot
+ * is a guess about an unprobed server, and on a server started with
+ * `--parallel 4` it is simply wrong. Without that sentence the denial reads as
+ * a hardware limit and the operator has no reason to look for a setting.
+ *
+ * `rosterFloor` is the smallest same-wave width the caller's topology can have.
+ * A council runs its whole roster in one wave, so "dispatch fewer at once" is
+ * not a move it has; saying so keeps the remedy honest.
+ */
+export function endpointCapacityRemedy(input?: { rosterFloor?: number }): string {
+	const ways =
+		"set this target's maxConcurrentRequests to the slot count the server was started with, collect in-flight runs, or point workers at a second server";
+	if (input?.rosterFloor === undefined) return `reduce the same-wave worker count, ${ways}`;
+	return `a council runs its whole roster in one wave and cannot go below ${input.rosterFloor} members, so ${ways}`;
+}
+
 function assertCapacity(
 	file: CapacityStateFile,
 	nodeId: string,
@@ -299,7 +319,7 @@ function assertCapacity(
 			const used = holders.leases + holders.reservations + holders.foregroundStreams;
 			if (used >= endpointLimit)
 				throw new Error(
-					`dispatch: admission denied: endpoint '${endpointLabel(endpointKey)}' capacity reached (${used}/${endpointLimit} slots): ${describeEndpointCapacityHolders(holders)}; collect in-flight runs or point workers at a second server`,
+					`dispatch: admission denied: endpoint '${endpointLabel(endpointKey)}' capacity reached (${used}/${endpointLimit} slots): ${describeEndpointCapacityHolders(holders)}; ${endpointCapacityRemedy()}`,
 				);
 		}
 	}