@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/domains/dispatch/fleet-node-prompt.ts

@@ -0,0 +1,62 @@
+/**
+ * What one fleet node is told about its own answer.
+ *
+ * A fleet contract renders a single prompt body and the plan compiler gives it
+ * to every agent node, because the body describes the whole chain and each node
+ * does one part of it. That is fine for the work description and wrong for the
+ * answer: nodes in the same chain hold different result contracts, so a body
+ * that names one contract names the wrong one for every other node. A loop's
+ * check node is where the mismatch is fatal rather than merely untidy. It is
+ * dispatched with `verifier-report` as its expected contract, and in
+ * `build-review` and `build-test` it received a body ending in "Answer with
+ * your `mutation-report`". The verifier complied with the instruction it was
+ * given, the gate held it to the schema that instruction never mentioned, and
+ * both were behaving correctly: every review cycle in those two fleets ended in
+ * `review gate produced no structured verdict` and the bounded revise loop was
+ * unresolvable by construction.
+ *
+ * So each node states its own contract, appended to the shared body, and the
+ * precedence line settles the conflict explicitly rather than leaving it to the
+ * model to guess which of two shapes the run will actually validate. This is
+ * the same remedy `COUNCIL_VOTE_MEMBER_DIRECTIVE` applies to a voting council
+ * member, for the same reason and with the same shape of failure behind it
+ * (#230): a run whose postcondition differs from the shape its prompt names
+ * fails on every input, not intermittently.
+ *
+ * The shape itself is quoted from `resultContractShape`, the one place a
+ * contract's wire example is written, so this directive cannot drift from the
+ * validator that judges the answer.
+ */
+
+import { type ResultContract, resultContractShape } from "../agents/result-contract.js";
+
+/**
+ * The answer directive for a node holding this contract, or null when the kind
+ * alone does not fix the shape.
+ *
+ * `architect-plan` names the path it must write, and a plan compiler resolving
+ * agents holds only the contract's kind. Inventing a path to render would state
+ * a location the validator does not check, so that kind gets no directive and
+ * its recipe keeps sole authority over the shape. Every other kind is fully
+ * determined by its kind and can be quoted exactly.
+ */
+function fleetNodeAnswerDirective(kind: ResultContract["kind"]): string | null {
+	if (kind === "architect-plan") return null;
+	return [
+		`Your result contract for this step is \`${kind}\`.`,
+		"The task above describes the whole chain. Any result shape it states belongs to the step that produces it, and does not apply to you.",
+		`End with exactly this shape and nothing else: ${resultContractShape({ kind })}`,
+		// The wire example carries literal names and evidence, and a small model
+		// handed one on a first attempt copies them: the first run of this
+		// directive came back claiming `npm run typecheck` / `exit 0` in the same
+		// breath as admitting it could not run a command. The fields are the
+		// contract; the values in the example are not.
+		"Its field values are an example. Fill them with what this run actually produced or observed, and never report a name or evidence you did not.",
+	].join("\n");
+}
+
+/** The shared body plus the node's own answer directive. */
+export function renderFleetNodeTask(task: string, kind: ResultContract["kind"]): string {
+	const directive = fleetNodeAnswerDirective(kind);
+	return directive === null ? task : `${task}\n\n${directive}`;
+}

package/src/domains/dispatch/fleet-plan.ts

@@ -32,6 +32,7 @@ import {
 	type ExecutionPlanStepInput,
 } from "./execution-plan.js";
 import type { ExecutionRole } from "./execution-role.js";
+import { renderFleetNodeTask } from "./fleet-node-prompt.js";
 
 /** Where an agent node sits, so the caller can resolve its role and authority. */
 export interface FleetPlanAgentContext {
@@ -58,7 +59,11 @@ export interface FleetPlanAgentResolution {
 
 export interface CompileFleetPlanInput {
 	contract: FleetContract;
-	/** Rendered prompt body; every agent node carries it as its task. */
+	/**
+	 * Rendered prompt body. It describes the whole chain, so every agent node
+	 * carries it, followed by that node's own answer directive: the nodes hold
+	 * different result contracts and the body can only ever name one of them.
+	 */
 	task: string;
 	resolveAgent(context: FleetPlanAgentContext): FleetPlanAgentResolution;
 }
@@ -143,7 +148,7 @@ export function compileFleetExecutionPlan(input: CompileFleetPlanInput): Executi
 			agentId: context.agentId,
 			scope: context.scope,
 			dependencies: [...dependencies],
-			task,
+			task: renderFleetNodeTask(task, resolved.expectedResultContract),
 			expectedResultContract: resolved.expectedResultContract,
 			requestedAuthority: resolved.requestedAuthority,
 			approvedAuthority: resolved.approvedAuthority,

package/src/domains/dispatch/fleet-preflight.ts

@@ -18,7 +18,6 @@ import { performance } from "node:perf_hooks";
 import { readClioVersion } from "../../core/package-root.js";
 import { shellQuote } from "../../core/shell-quote.js";
 import { clioStateDir } from "../../core/xdg.js";
-import { atomicWrite } from "../../engine/session.js";
 import {
 	evaluateRouteFacts,
 	type FactState,
@@ -92,16 +91,6 @@ export function readFleetPreflightRecords(): FleetPreflightRecord[] {
 	}
 }
 
-/** Upsert records keyed by (nodeId, projectRoot). */
-export function recordFleetPreflight(records: ReadonlyArray<FleetPreflightRecord>): void {
-	const existing = readFleetPreflightRecords();
-	const merged = new Map<string, FleetPreflightRecord>();
-	for (const record of existing) merged.set(`${record.nodeId}\0${record.projectRoot}`, record);
-	for (const record of records) merged.set(`${record.nodeId}\0${record.projectRoot}`, record);
-	const file: FleetPreflightStoreFile = { version: 2, records: [...merged.values()] };
-	atomicWrite(storePath(), JSON.stringify(file, null, 2));
-}
-
 export interface FleetPreflightVerdict {
 	ok: boolean;
 	reason: string | null;
@@ -164,7 +153,8 @@ export function routeFactVerdict(
 	return evaluateRouteFacts(targets, resources, requirement, options);
 }
 
-const PREFLIGHT_MARKER = "clio-preflight/1";
+const PREFLIGHT_MARKER = "clio-coder-preflight/1";
+const LEGACY_PREFLIGHT_MARKER = "clio-preflight/1";
 const DEFAULT_PREFLIGHT_TIMEOUT_MS = 20_000;
 
 /**
@@ -187,8 +177,8 @@ function buildPreflightScript(
 	const cliBase = entry.endsWith(" worker") ? entry.slice(0, -" worker".length) : null;
 	const versionProbe =
 		cliBase !== null
-			? `v=$(${cliBase} --version 2>/dev/null | head -n 1); if [ -n "$v" ]; then echo "clio=$v"; else echo clio=missing; fi`
-			: `echo clio=custom-entry`;
+			? `v=$(${cliBase} --version 2>/dev/null | head -n 1); if [ -n "$v" ]; then echo "clioCoder=$v"; else echo clioCoder=missing; fi`
+			: `echo clioCoder=custom-entry`;
 	const lines = [
 		`echo ${shellQuote(PREFLIGHT_MARKER)}`,
 		`if cd ${shellQuote(projectRoot)} 2>/dev/null; then echo cwd=ok; else echo cwd=missing; fi`,
@@ -342,7 +332,7 @@ export async function runFleetNodePreflight(
 	// Probe latency is durable eligibility evidence compared across nodes and
 	// across passes, so it is measured on the monotonic clock.
 	const probeDurationMs = Math.round(performance.now() - probeStartedAt);
-	if (!result.stdout.includes(PREFLIGHT_MARKER)) {
+	if (!result.stdout.includes(PREFLIGHT_MARKER) && !result.stdout.includes(LEGACY_PREFLIGHT_MARKER)) {
 		const stderr = result.stderr.trim().split("\n").slice(-1)[0] ?? "";
 		record.detail = `unreachable (ssh exit ${result.code}${stderr.length > 0 ? `: ${stderr}` : ""})`;
 		return record;
@@ -364,8 +354,9 @@ export async function runFleetNodePreflight(
 	};
 	checks.pathParity = lines.includes("cwd=ok");
 	checks.stateDirWritable = lines.includes("state=ok");
-	const clioLine = lines.find((line) => line.startsWith("clio="));
-	const clioValue = clioLine?.slice("clio=".length) ?? "missing";
+	const clioCoderLine = lines.find((line) => line.startsWith("clioCoder="));
+	const legacyClioLine = lines.find((line) => line.startsWith("clio="));
+	const clioValue = clioCoderLine?.slice("clioCoder=".length) ?? legacyClioLine?.slice("clio=".length) ?? "missing";
 	if (clioValue === "custom-entry") {
 		// A custom clioCoderEntry that is not `<cli> worker` cannot be version-probed;
 		// the operator vouches for it. Presence is asserted, match is assumed.

package/src/domains/dispatch/fleet-run.ts

@@ -21,6 +21,8 @@ import type { FleetCommandRegistry } from "../agents/fleet-commands.js";
 import type { FleetContract } from "../agents/fleet-contract.js";
 import { resultContractAuthorship } from "../agents/result-contract.js";
 import type { AgentSpec } from "../agents/spec.js";
+import { aggregateCostAmounts, type CostAggregate, renderCostAmount } from "../observability/cost.js";
+import type { CostProvenance } from "../providers/index.js";
 import { claimAssignmentVerdict, recordAssignmentAttempt, settleStoredAssignment } from "./assignment-store.js";
 import { runCodeStep } from "./code-step.js";
 import { codeStepDir, writeCodeStepRecord } from "./code-step-store.js";
@@ -43,6 +45,7 @@ import {
 	materializePendingGateDecision,
 	stagePendingGateDecision,
 } from "./gate-decisions.js";
+import { type DispatchIntent, declaredScopeIntent } from "./intent.js";
 import { verifyReceiptIntegrity } from "./receipt-integrity.js";
 import { type FleetRunRecord, writeFleetRun } from "./state.js";
 import type { RunReceipt } from "./types.js";
@@ -83,6 +86,15 @@ export interface FleetRunStepOutcome extends FleetRunStepEvent {
 	/** Terminal run id, which is the receipt id for an agent step. */
 	terminalRunId: string;
 	costUsd: number;
+	/**
+	 * Where the number in `costUsd` came from, carried beside it because the two
+	 * are one fact. A gateway-routed run seals `costUsd: 0` with `unknown`: its
+	 * tokens were measured and nobody priced them. A renderer that reads the
+	 * amount without this prints `$0.0000` and turns unpriced work into a
+	 * measured zero. `known_free` on a deterministic step is the honest reading:
+	 * no model ran, so the zero is something code observed rather than missed.
+	 */
+	costProvenance: CostProvenance;
 	/** The sealed agent receipt when this was an agent step. */
 	receipt?: RunReceipt;
 	/** The durable code-step record when this was a deterministic step. */
@@ -192,7 +204,12 @@ export interface FleetRunOutcome {
 	planHash: string;
 	result: ExecutionPlanResult;
 	receipts: ReadonlyArray<RunReceipt>;
-	totalCostUsd: number;
+	/**
+	 * The fold that keeps unpriced calls distinguishable from priced ones, so a
+	 * run whose every receipt came back `unknown` renders as not measured rather
+	 * than as a total of zero dollars.
+	 */
+	totalCost: CostAggregate;
 	/** Steps that ran unconditionally, excluding nodes a resolved loop skipped. */
 	requiredStepCount: number;
 	succeededStepCount: number;
@@ -217,6 +234,24 @@ function fleetGateCorrelation(subject: RunReceipt, decider: RunReceipt): GateDec
 	return { agent, target, modelFamily, runtime, node, independent };
 }
 
+/**
+ * Typed scope for one fleet step, drawn from the boundary its contract already
+ * declared. Returns null when the contract declared nothing for this position,
+ * which is every step of a pre-v4 contract and every readonly step: those keep
+ * the legacy inference path rather than being handed an empty declaration that
+ * would silently switch off path-scoped rule selection for them.
+ *
+ * A contract whose declared paths do not survive the boundary grammar is a
+ * compile-time authoring bug, not a dispatch-time one, so a malformed entry
+ * falls back to inference here rather than aborting a run mid-wave; the
+ * contract loader is the surface that refuses it.
+ */
+function fleetStepIntent(writes: ReadonlyArray<string> | undefined): DispatchIntent | null {
+	if (writes === undefined || writes.length === 0) return null;
+	const built = declaredScopeIntent({ relevantPaths: writes });
+	return built.ok ? built.intent : null;
+}
+
 export function fleetPlanWaveIndex(plan: ExecutionPlan, stepId: string): number {
 	return plan.waves.findIndex((wave) => wave.includes(stepId));
 }
@@ -338,6 +373,9 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 			succeeded: true,
 			terminalRunId: replayedResult.terminalRunId,
 			costUsd: receiptsByStep.get(stepId)?.costUsd ?? 0,
+			// A replay whose receipt no longer exists on disk has no cost claim at
+			// all, which is `unknown` rather than a zero the projection invented.
+			costProvenance: receiptsByStep.get(stepId)?.costProvenance ?? "unknown",
 			result: replayedResult,
 		});
 		await fileStepAttempt(replayedResult.terminalRunId);
@@ -434,11 +472,24 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 				// The fleet write boundary is deliberately enforced after the step. The enforcer in
 				// write-boundary-enforcer.ts snapshots and verifies the step window. Pre-emptive
 				// confinement for declared commands would require a command sandbox, which does not exist.
+				//
+				// That enforcement split is exactly why a step's declared `writes:` reaches
+				// typed intent as `relevant_paths` rather than as `write_roots`. The
+				// contract already said what this position may change and the enforcer
+				// already holds it; restating it as intent write roots would mint a second
+				// grant enforced at the per-tool worker seam, which refuses outright on the
+				// subprocess and ACP runtimes a fleet may legitimately route a step to.
+				// Carrying it as declared scope changes no authority and gets the
+				// contract's own paths into project-rule selection and worker context,
+				// where prose tokens scraped from the rendered prompt were standing in for
+				// a declaration the contract had already made.
+				const stepIntent = fleetStepIntent(step.writes);
 				const request: DispatchRequest = {
 					agentId: step.agentId,
 					executionRole: step.executionRole,
 					task: step.task,
 					cwd: workspaceRoot,
+					...(stepIntent === null ? {} : { intent: stepIntent }),
 					predecessorHandoffs: handoffs,
 					requestOrigin: "user",
 					lineage: {
@@ -591,11 +642,12 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 							succeeded: stepSucceeded,
 							terminalRunId: receipt.runId,
 							costUsd: receipt.costUsd,
+							costProvenance: receipt.costProvenance,
 							receipt,
 							...(failureReason !== undefined ? { failureReason } : {}),
 						});
 						notice(
-							`step ${step.id} ${step.agentId}: ${stepSucceeded ? "succeeded" : "failed"}${failureReason !== undefined ? ` reason=${failureReason}` : ""} assignment=${handle.runId} terminal-run=${receipt.runId} cost=$${receipt.costUsd.toFixed(4)}`,
+							`step ${step.id} ${step.agentId}: ${stepSucceeded ? "succeeded" : "failed"}${failureReason !== undefined ? ` reason=${failureReason}` : ""} assignment=${handle.runId} terminal-run=${receipt.runId} cost=${renderCostAmount(receipt.costUsd, receipt.costProvenance)}`,
 						);
 						return {
 							stepId: step.id,
@@ -658,6 +710,8 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 					succeeded: outcome.report.passed,
 					terminalRunId: outcome.record.runId,
 					costUsd: 0,
+					// No model ran, so nothing needed pricing. This zero was observed.
+					costProvenance: "known_free",
 					codeStep: outcome.record,
 					recordPath,
 				});
@@ -802,7 +856,9 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 		planHash: input.plan.hash,
 		result,
 		receipts,
-		totalCostUsd: receipts.reduce((sum, receipt) => sum + receipt.costUsd, 0),
+		totalCost: aggregateCostAmounts(
+			receipts.map((receipt) => ({ usd: receipt.costUsd, provenance: receipt.costProvenance })),
+		),
 		requiredStepCount: required.length,
 		succeededStepCount,
 		resolvedLoopCount: result.loops.length - failedLoops.length,

package/src/domains/dispatch/gate-decisions.ts

@@ -298,10 +298,20 @@ export interface StagePendingGateDecisionOptions {
 	stateDir?: string;
 }
 
-function decisionsDirectory(stateDir = clioStateDir()): string {
+/**
+ * Where the durable decision artifacts live.
+ *
+ * Exported so a read-only projection can bound its own scan without duplicating
+ * the layout. Nothing outside this module may compose an artifact path from it.
+ */
+export function gateDecisionsDirectory(stateDir = clioStateDir()): string {
 	return join(stateDir, "gate-decisions");
 }
 
+function decisionsDirectory(stateDir = clioStateDir()): string {
+	return gateDecisionsDirectory(stateDir);
+}
+
 function pendingDecisionsDirectory(stateDir = clioStateDir()): string {
 	return join(decisionsDirectory(stateDir), "pending");
 }
@@ -370,7 +380,8 @@ function semanticError(value: unknown): string | null {
 			value.winner.index < 1 ||
 			!isSubjectRef(value.winner.subject) ||
 			typeof value.winner.branch !== "string" ||
-			value.winner.branch !== `clio/compete/${value.group}/${value.winner.index}`
+			(value.winner.branch !== `clio-coder/compete/${value.group}/${value.winner.index}` &&
+				value.winner.branch !== `clio/compete/${value.group}/${value.winner.index}`)
 		) {
 			return "gate decision winner invalid";
 		}
@@ -423,9 +434,12 @@ function pendingDecisionPath(id: string, stateDir = clioStateDir()): string {
 	return join(pendingDecisionsDirectory(stateDir), `${id}.json`);
 }
 
-function decisionPayload(decision: Omit<GateDecisionArtifact, "integrity">): Record<string, unknown> {
+function decisionPayload(
+	decision: Omit<GateDecisionArtifact, "integrity">,
+	legacyNaming = false,
+): Record<string, unknown> {
 	return {
-		contract: "clio.gateDecision.integrity",
+		contract: legacyNaming ? "clio.gateDecision.integrity" : "clio-coder.gateDecision.integrity",
 		version: decision.version,
 		id: decision.id,
 		group: decision.group,
@@ -457,9 +471,9 @@ function decisionPayload(decision: Omit<GateDecisionArtifact, "integrity">): Rec
 	};
 }
 
-function decisionDigest(decision: Omit<GateDecisionArtifact, "integrity">): string {
+function decisionDigest(decision: Omit<GateDecisionArtifact, "integrity">, legacyNaming = false): string {
 	return createHash("sha256")
-		.update(JSON.stringify(decisionPayload(decision)), "utf8")
+		.update(JSON.stringify(decisionPayload(decision, legacyNaming)), "utf8")
 		.digest("hex");
 }
 
@@ -492,7 +506,9 @@ export function verifyGateDecisionArtifact(artifact: GateDecisionArtifact): Gate
 	const invalid = semanticError(artifact);
 	if (invalid !== null) return { ok: false, reason: invalid };
 	if (!/^[0-9a-f]{64}$/.test(artifact.integrity.digest)) return { ok: false, reason: "gate decision integrity invalid" };
-	return decisionDigest(artifactWithoutIntegrity(artifact)) === artifact.integrity.digest
+	const withoutIntegrity = artifactWithoutIntegrity(artifact);
+	return decisionDigest(withoutIntegrity) === artifact.integrity.digest ||
+		decisionDigest(withoutIntegrity, true) === artifact.integrity.digest
 		? { ok: true }
 		: { ok: false, reason: "gate decision integrity mismatch" };
 }
@@ -587,10 +603,13 @@ function cloneGateDecisionArtifact(artifact: GateDecisionArtifact): GateDecision
 	};
 }
 
-function pendingRecordPayload(record: PendingGateRecordWithoutIntegrity): Record<string, unknown> {
+function pendingRecordPayload(
+	record: PendingGateRecordWithoutIntegrity,
+	legacyNaming = false,
+): Record<string, unknown> {
 	if (record.kind === "output") {
 		return {
-			contract: "clio.gateDecision.pending",
+			contract: legacyNaming ? "clio.gateDecision.pending" : "clio-coder.gateDecision.pending",
 			version: record.version,
 			kind: record.kind,
 			id: record.id,
@@ -607,12 +626,12 @@ function pendingRecordPayload(record: PendingGateRecordWithoutIntegrity): Record
 	}
 	const decisionWithoutIntegrity = artifactWithoutIntegrity(record.decision);
 	return {
-		contract: "clio.gateDecision.pending",
+		contract: legacyNaming ? "clio.gateDecision.pending" : "clio-coder.gateDecision.pending",
 		version: record.version,
 		kind: record.kind,
 		id: record.id,
 		decision: {
-			...decisionPayload(decisionWithoutIntegrity),
+			...decisionPayload(decisionWithoutIntegrity, legacyNaming),
 			integrity: { ...record.decision.integrity },
 		},
 		...(record.finalOutput !== undefined ? { finalOutput: record.finalOutput } : {}),
@@ -621,9 +640,9 @@ function pendingRecordPayload(record: PendingGateRecordWithoutIntegrity): Record
 	};
 }
 
-function pendingRecordDigest(record: PendingGateRecordWithoutIntegrity): string {
+function pendingRecordDigest(record: PendingGateRecordWithoutIntegrity, legacyNaming = false): string {
 	return createHash("sha256")
-		.update(JSON.stringify(pendingRecordPayload(record)), "utf8")
+		.update(JSON.stringify(pendingRecordPayload(record, legacyNaming)), "utf8")
 		.digest("hex");
 }
 
@@ -711,10 +730,12 @@ function pendingSemanticError(value: unknown): string | null {
 }
 
 /** Verify both the pending envelope and its nested final artifact, when resolved. */
-export function verifyPendingGateDecisionRecord(record: PendingGateDecisionRecord): GateDecisionVerification {
+function verifyPendingGateDecisionRecord(record: PendingGateDecisionRecord): GateDecisionVerification {
 	const invalid = pendingSemanticError(record);
 	if (invalid !== null) return { ok: false, reason: invalid };
-	return pendingRecordDigest(pendingRecordWithoutIntegrity(record)) === record.integrity.digest
+	const withoutIntegrity = pendingRecordWithoutIntegrity(record);
+	return pendingRecordDigest(withoutIntegrity) === record.integrity.digest ||
+		pendingRecordDigest(withoutIntegrity, true) === record.integrity.digest
 		? { ok: true }
 		: { ok: false, reason: "pending gate decision integrity mismatch" };
 }

package/src/domains/dispatch/gate-role-prompts.ts

@@ -2,6 +2,15 @@
 
 import { COUNCIL_BALLOT_SHAPE, COUNCIL_BALLOT_VERDICT_MAX_BYTES } from "../agents/result-contract.js";
 
+/**
+ * Roster bounds for a council. Two is the point of the topology: one seated
+ * agent is a plain dispatch, and there is nothing to compare. Capacity denials
+ * quote the floor because it is the reason a council cannot answer saturation
+ * by dispatching fewer members.
+ */
+export const COUNCIL_MIN_MEMBERS = 2;
+export const COUNCIL_MAX_MEMBERS = 5;
+
 export const REVIEWER_GATE_PROMPT = [
 	"You are a strict, read-only reviewer of one implementation run.",
 	"Inspect the supplied result and repository state with read-only tools.",