@iowarp/clio-coder 0.3.9 → 0.4.1

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":
@@ -1472,7 +1601,7 @@ export interface ResultContractRepairInput {
  * One repair directive. It states the validator's reason and exact shape. Tool
  * use remains closed unless dispatch preauthorized a larger revision phase.
  */
-export function resultContractRepairMessage(input: ResultContractRepairInput): string {
+function resultContractRepairMessage(input: ResultContractRepairInput): string {
 	const last = input.attempt >= RESULT_CONTRACT_REPAIR_LIMIT;
 	const lines = [
 		last

package/src/domains/agents/spec.ts

@@ -137,17 +137,6 @@ export function isAgentProduct(value: unknown): value is AgentProduct {
 	return includes(AGENT_PRODUCTS, value);
 }
 
-/**
- * Default tier per capability class. Reproduces the historical dispatch
- * allowlist byte-for-byte: workers that act on the workspace get the bounded
- * projection; read-only, orchestration, and internal classes get none.
- */
-export function defaultProjectContextTier(capability: AgentCapabilityClass): AgentProjectContextTier {
-	return capability === "workspace-edit" || capability === "verification" || capability === "artifact-write"
-		? "bounded"
-		: "none";
-}
-
 function actionClassesForTools(tools: ReadonlyArray<ToolName>): ReadonlySet<ActionClass> {
 	const actions = new Set<ActionClass>();
 	for (const tool of tools) actions.add(classify({ tool }).actionClass);

package/src/domains/config/classify.ts

@@ -1,13 +1,10 @@
 import type { ClioSettings } from "../../core/config.js";
 
 /**
- * Classifies a settings change into one of three buckets per spec §13:
- *   - hotReload   : theme, keybindings, safety rules, prompt fragments,
- *                   audit verbosity. Apply immediately (≤100ms).
- *   - nextTurn    : model selection, thinking level, budget ceiling. Apply before the
- *                   next turn starts.
- *   - restartRequired : provider credentials, active provider list, runtime enable/disable,
- *                       engine settings. Needs a restart nudge.
+ * Classifies a version-2 settings change into one of three effect buckets:
+ *   - hotReload: a live reader observes the value without rebuilding runtime state.
+ *   - nextTurn: the next request, dispatch, or explicit open observes the value.
+ *   - restartRequired: process or pane-host setup must be rebuilt.
  *
  * Output is an exhaustive per-bucket list. A single patch can touch multiple buckets;
  * the caller emits the event(s) for every non-empty bucket.
@@ -22,56 +19,50 @@ export interface ConfigDiff {
 }
 
 const HOT_RELOAD_FIELDS = new Set<string>([
-	"theme",
-	"keybindings",
-	"autonomy",
-	"modelSelector",
-	"terminal.smoothStreaming",
-	"attribution.gitCommits",
+	"interface.keybindings",
+	"safety.autonomy",
+	"chat.modelPicker",
+	"interface.smoothStreaming",
+	"interface.panes.notifications",
+	"integrations.git.commitAttribution",
+	// The bridge reads these on every explicit open; no mux re-detection is
+	// needed because the host capability rung remains `panes.enabled`.
+	"interface.panes.files",
 	// 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.
-	"watchdog",
+	"safety.review",
 ]);
 
 const NEXT_TURN_FIELDS = new Set<string>([
-	"identity",
 	"targets",
-	"orchestrator.target",
-	"orchestrator.model",
-	"orchestrator.thinkingLevel",
-	"background.target",
-	"background.model",
-	"background.thinkingLevel",
-	"memory",
-	"workers.default.target",
-	"workers.default.model",
-	"workers.default.thinkingLevel",
-	"workers.profiles",
-	"workers.agentBindings",
-	"workers.maxRetries",
-	"workers.onPermission",
-	"fleet",
-	"routing",
-	"scope",
-	"budget.sessionCeilingUsd",
-	"defaults",
-	"terminal",
-	"skills",
-	"delegation",
-	"compaction",
+	"chat",
+	"fleet.default",
+	"fleet.profiles",
+	"fleet.rosters",
+	"fleet.agentProfiles",
+	"fleet.adaptiveRouting",
+	"fleet.nodes",
+	"fleet.permissions",
+	"fleet.retry",
+	"fleet.limits",
+	"fleet.history",
 	"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",
+	"safety.limits",
+	"interface.outputDetail",
+	"interface.terminalProgress",
+	"interface.desktopNotifications",
+	"integrations.projectResources",
+	"integrations.externalAgents",
+	"integrations.library",
 ]);
 
 const RESTART_REQUIRED_FIELDS = new Set<string>([
-	"budget.concurrency",
-	"runtimePlugins",
-	"terminal.tuiMode",
-	"terminal.fullscreenScrollbar",
+	"fleet.concurrency",
+	"interface.mode",
+	"interface.fullscreenScrollbar",
+	"interface.panes.enabled",
+	"integrations.runtimePlugins",
 ]);
 
 function matchesPrefix(path: string, fields: Set<string>): boolean {

package/src/domains/config/extension.ts

@@ -29,7 +29,7 @@ export function createConfigBundle(
 
 	function assertAgentNamespace(settings: Readonly<ClioSettings>): void {
 		const agents = context.getContract<NativeAgentNamespace>("agents");
-		if (agents) assertAgentIdNamespace(agents.list(), settings.delegation.agents);
+		if (agents) assertAgentIdNamespace(agents.list(), settings.integrations.externalAgents.entries);
 	}
 
 	function dispatch(kind: ChangeKind, payload: ConfigChangePayload): void {
@@ -45,7 +45,7 @@ export function createConfigBundle(
 			try {
 				listener(payload);
 			} catch (err) {
-				console.error(`[clio:config] listener for ${kind} threw:`, err);
+				console.error(`[clio-coder:config] listener for ${kind} threw:`, err);
 			}
 		}
 	}
@@ -84,7 +84,7 @@ export function createConfigBundle(
 		}
 		publishReloadFailure(null);
 		snapshot = next;
-		setGitCommitAttributionEnabled(next.attribution.gitCommits);
+		setGitCommitAttributionEnabled(next.integrations.git.commitAttribution);
 		if (!prev) return;
 		const diff = diffSettings(prev, next);
 		if (diff.hotReload.length > 0) dispatch("hotReload", { diff, settings: next });
@@ -96,7 +96,7 @@ export function createConfigBundle(
 		async start() {
 			if (initialSettings) snapshot = structuredClone(initialSettings);
 			else snapshot = readStrictLayeredSettings(process.cwd()).settings;
-			setGitCommitAttributionEnabled(snapshot.attribution.gitCommits);
+			setGitCommitAttributionEnabled(snapshot.integrations.git.commitAttribution);
 			watcher = startConfigWatcher(() => onWatcherFire());
 		},
 		async stop() {
@@ -124,7 +124,7 @@ export function createConfigBundle(
 			// a route may name a target supplied only by this workspace.
 			const normalized = updateLayeredSettings(process.cwd(), mutate);
 			snapshot = normalized;
-			setGitCommitAttributionEnabled(normalized.attribution.gitCommits);
+			setGitCommitAttributionEnabled(normalized.integrations.git.commitAttribution);
 			const diff = diffSettings(previous, normalized);
 			if (diff.hotReload.length > 0) dispatch("hotReload", { diff, settings: normalized });
 			if (diff.nextTurn.length > 0) dispatch("nextTurn", { diff, settings: normalized });