@iowarp/clio-coder 0.3.7 → 0.3.9

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

@@ -21,6 +21,7 @@ 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 { claimAssignmentVerdict, recordAssignmentAttempt, settleStoredAssignment } from "./assignment-store.js";
 import { runCodeStep } from "./code-step.js";
 import { codeStepDir, writeCodeStepRecord } from "./code-step-store.js";
 import type { DispatchContract, DispatchRequest } from "./contract.js";
@@ -45,6 +46,7 @@ import {
 import { verifyReceiptIntegrity } from "./receipt-integrity.js";
 import { type FleetRunRecord, writeFleetRun } from "./state.js";
 import type { RunReceipt } from "./types.js";
+import type { WriteBoundaryAttribution } from "./write-boundary.js";
 import { createWriteBoundaryEnforcer } from "./write-boundary-enforcer.js";
 
 /** Owner id for a plan with no model runs; it holds nothing to release. */
@@ -247,13 +249,66 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 		dynamicPlans: [],
 	};
 	await writeFleetRun(fleetRunRecord);
+	// Every step of this run dispatches under `fleetRootId` as its lineage root,
+	// so every agent step also settles the assignment row of that id. One step is
+	// not the run, and letting the last one to finish write the row reported a
+	// green step of a run that aborted at step 2 of 7 as `succeeded`. The run
+	// claims the verdict here and answers for itself at the end.
+	await claimAssignmentVerdict(fleetRootId, "fleet");
+	/** File one step's terminal run id, whichever kind produced it. */
+	const fileStepAttempt = (terminalRunId: string): Promise<unknown> =>
+		recordAssignmentAttempt(fleetRootId, terminalRunId);
+	/**
+	 * The run's own word on its ledger row. A settle that cannot be written
+	 * leaves the row `running`, which startup reconciliation resolves to failed,
+	 * so a lost write never becomes a false success.
+	 */
+	const settleFleetAssignment = (cleanRun: boolean): Promise<unknown> =>
+		settleStoredAssignment(
+			fleetRootId,
+			fleetRunRecord.steps.at(-1)?.result.terminalRunId ?? fleetRootId,
+			cleanRun ? "succeeded" : "failed",
+			"fleet",
+		).catch(() => undefined);
 	const boundaryEnforcer = createWriteBoundaryEnforcer({
 		root: workspaceRoot,
 		rootId: fleetRootId,
 		boundaryFor: (stepId) => livePlan.steps.find((step) => step.id === stepId)?.writes,
+		recordedWritesFor: (stepId) => {
+			const step = livePlan.steps.find((entry) => entry.id === stepId);
+			// A code step runs a registered command in a subprocess. Nothing
+			// enumerates what that command wrote, so the step contributes no record
+			// and its window falls back to blaming the whole diff.
+			if (step === undefined) return null;
+			if (step.kind !== "agent") {
+				return {
+					recorded: [],
+					complete: false,
+					downgrades: [
+						{
+							reason: "code_step_untracked",
+							tool: null,
+							toolCallId: null,
+							runId: null,
+							stepId,
+						},
+					],
+				} satisfies WriteBoundaryAttribution;
+			}
+			const receipt = receiptsByStep.get(stepId);
+			if (receipt === undefined) return null;
+			if (dispatch.observedRunWriteAttribution !== undefined) {
+				return dispatch.observedRunWriteAttribution(receipt.runId);
+			}
+			const recorded = dispatch.observedRunWrites?.(receipt.runId) ?? null;
+			return recorded === null ? null : { recorded, complete: true, downgrades: [] };
+		},
 		onVerdict(verdict, path) {
-			if (verdict.reason === null) return;
-			notice(`write boundary ${verdict.window}: ${verdict.detail ?? verdict.reason} record=${path}`, "write-boundary");
+			// Concurrent changes are reported too. The window did not fail for them
+			// and nothing was touched, and an operator whose file changed under a
+			// running fleet should hear it from the fleet.
+			if (verdict.detail === null) return;
+			notice(`write boundary ${verdict.window}: ${verdict.detail} record=${path}`, "write-boundary");
 		},
 	});
 	const receipts: RunReceipt[] = [];
@@ -285,6 +340,7 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 			costUsd: receiptsByStep.get(stepId)?.costUsd ?? 0,
 			result: replayedResult,
 		});
+		await fileStepAttempt(replayedResult.terminalRunId);
 	}
 	const planStep = (stepId: string) => livePlan.steps.find((entry) => entry.id === stepId);
 
@@ -322,6 +378,9 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 	try {
 		result = await executePlan(livePlan, {
 			preflight(step) {
+				// 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.
 				const request: DispatchRequest = {
 					agentId: step.agentId,
 					executionRole: step.executionRole,
@@ -372,6 +431,9 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 				if (step.planParentId !== undefined && parentReceipt === undefined) {
 					throw new Error(`fleet dynamic step '${step.id}' has no terminal plan-step receipt`);
 				}
+				// 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.
 				const request: DispatchRequest = {
 					agentId: step.agentId,
 					executionRole: step.executionRole,
@@ -662,7 +724,7 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 			cancel: (assignmentId) => dispatch.abort(assignmentId),
 			release: (ownerId) => {
 				if (ownerId === NO_WORKER_RESERVATION) return;
-				dispatch.reservations?.rollbackUnconsumed(ownerId);
+				dispatch.reservations?.release(ownerId);
 			},
 			releaseUnconsumed: (ownerId) => {
 				if (ownerId === NO_WORKER_RESERVATION) return;
@@ -671,6 +733,11 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 			onStepSettled: async (step, stepResult) => {
 				fleetRunRecord.steps.push({ stepId: step.id, result: stepResult });
 				await writeFleetRun(fleetRunRecord);
+				// The scheduler settles both kinds of step here, so this is where a
+				// deterministic step enters the assignment: a code step's `code-*` run
+				// id reads exactly like an agent receipt id, and its evidence sits under
+				// `code-steps/<fleetRootId>/`.
+				await fileStepAttempt(stepResult.terminalRunId);
 			},
 			spliceAfter(currentPlan, step, stepResult) {
 				if (stepResult.delegationPlan === undefined) return null;
@@ -712,6 +779,9 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 	} catch (error) {
 		fleetRunRecord.endedAt = new Date().toISOString();
 		await writeFleetRun(fleetRunRecord);
+		// A run the scheduler could not carry to the end never reached a verdict,
+		// and a fleet that threw is not a fleet that worked.
+		await settleFleetAssignment(false);
 		throw error;
 	}
 	fleetRunRecord.endedAt = new Date().toISOString();
@@ -723,6 +793,10 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 	const required = livePlan.steps.filter((step) => step.loop === undefined && !result.unneeded.includes(step.id));
 	const failedLoops = result.loops.filter((loop) => !loop.resolved);
 	const succeededStepCount = required.filter((step) => result.results.get(step.id)?.succeeded === true).length;
+	// A step a stop policy left unrun is counted but never succeeded, so a run
+	// that halted early can never reach the required count.
+	const cleanRun = failedLoops.length === 0 && result.skipped.length === 0 && succeededStepCount === required.length;
+	await settleFleetAssignment(cleanRun);
 	return {
 		rootId: fleetRootId,
 		planHash: input.plan.hash,
@@ -732,6 +806,6 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 		requiredStepCount: required.length,
 		succeededStepCount,
 		resolvedLoopCount: result.loops.length - failedLoops.length,
-		cleanRun: failedLoops.length === 0 && result.skipped.length === 0 && succeededStepCount === required.length,
+		cleanRun,
 	};
 }

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

@@ -1,5 +1,7 @@
 /** Bounded role prompts shared by dispatch topology construction and ACP admission. */
 
+import { COUNCIL_BALLOT_SHAPE, COUNCIL_BALLOT_VERDICT_MAX_BYTES } from "../agents/result-contract.js";
+
 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.",
@@ -26,6 +28,42 @@ export const COUNCIL_JUDGE_PROMPT = [
 	'End with a JSON object only: {"verdict":"...","text":"the supported synthesis"}.',
 ].join("\n");
 
+/**
+ * What a council member is told when the synthesis is `vote`.
+ *
+ * The tally is a strict majority over the members' `verdict` fields, and until
+ * this directive existed nothing ever asked a member for one (#230). It rides
+ * on the member's task rather than on a system prompt, so the seated recipe
+ * keeps its own persona: a council's point is running *that* agent across
+ * several targets, and replacing its body with a ballot prompt would run a
+ * different agent under the same name. The matching `council-ballot` contract
+ * travels with it as a `resultContractOverride`, so the postcondition the run
+ * seals is the one this text asks for, and a member that answers in its
+ * recipe's shape instead gets the ordinary bounded repair rounds rather than a
+ * silent absence from the tally.
+ *
+ * The precedence line is not decoration. A recipe body states its own result
+ * shape (`researcher` asks for findings), so without it the member holds two
+ * contradictory instructions and small local models resolve the conflict by
+ * burying a verdict inside the recipe's shape, which is exactly what the 0.3.7
+ * release test observed and read as correct behavior.
+ */
+export const COUNCIL_VOTE_MEMBER_DIRECTIVE = [
+	"This council round is a vote. Do the work the task asks for, then cast one ballot on it.",
+	`The verdict is a short comparable token the other members can match exactly, such as "yes", "no", "keep", or the name of an option you were given. It must be a single line of at most ${COUNCIL_BALLOT_VERDICT_MAX_BYTES} bytes and is lower-cased before the tally. Anything longer is reasoning: put that in text, along with the evidence behind it.`,
+	"Your recipe's own result shape does not apply to this run. The council reads the ballot and nothing else.",
+	`End with a JSON object only: ${COUNCIL_BALLOT_SHAPE}`,
+].join("\n");
+
+/**
+ * The task a council member is given under `synthesis: "vote"`. Plan admission
+ * composes it here once, then the runner reuses the task pinned by that plan so
+ * the approval artifact shows the exact ask the member receives.
+ */
+export function renderCouncilVoteMemberTask(originalTask: string): string {
+	return [originalTask, COUNCIL_VOTE_MEMBER_DIRECTIVE].join("\n\n");
+}
+
 /**
  * Posture a compete candidate runs under. Candidates otherwise differ only by
  * worktree, and identical agents produce correlated output, so each candidate

package/src/domains/dispatch/heartbeat.ts

@@ -1,13 +1,13 @@
 /**
  * Pure heartbeat watchdog classifier (Phase 6 slice 3).
  *
- * Maps a last-seen heartbeat timestamp to one of three states. The dispatch
- * domain drives this on each scheduler tick; the orchestrator uses `stale` to
- * surface a warning in the UI and `dead` to reap a subprocess whose event
- * stream has gone quiet for too long.
+ * Maps a last-seen monotonic stamp to one of three states. The dispatch domain
+ * drives this on each scheduler tick; the orchestrator uses `stale` to surface
+ * a warning in the UI and `dead` to reap a subprocess whose event stream has
+ * gone quiet for too long.
  *
- * No I/O, no clocks of its own. Callers pass `now` to keep the function pure
- * and easy to test.
+ * No I/O, no clocks of its own. Callers pass both monotonic values to keep the
+ * function pure and easy to test.
  */
 
 export interface HeartbeatSpec {
@@ -17,10 +17,34 @@ export interface HeartbeatSpec {
 
 export type HeartbeatStatus = "alive" | "stale" | "dead";
 
+/**
+ * Mutable heartbeat facts shared by a transport and the dispatch watchdog.
+ * `current` is an absolute wall-clock instant for display and persistence.
+ * `monotonic` is from this process's monotonic clock and is the only value
+ * liveness code may compare with a later clock read.
+ *
+ * The monotonic field is optional only for injected legacy test handles. Real
+ * transports always provide it. Treating an old handle's `current` as its
+ * monotonic stamp preserves the structural test seam without reintroducing a
+ * subtraction between two wall-clock reads in the product path.
+ */
+export interface HeartbeatStamp {
+	current: number;
+	monotonic?: number;
+}
+
 export const DEFAULT_HEARTBEAT_SPEC: HeartbeatSpec = { windowMs: 5000, graceMs: 10000 };
 
-export function classifyHeartbeat(heartbeatAt: number, now: number, spec: HeartbeatSpec): HeartbeatStatus {
-	const age = now - heartbeatAt;
+export function heartbeatMonotonicAt(heartbeat: HeartbeatStamp): number {
+	return heartbeat.monotonic ?? heartbeat.current;
+}
+
+export function classifyHeartbeat(
+	heartbeatMonotonicAt: number,
+	monotonicNow: number,
+	spec: HeartbeatSpec,
+): HeartbeatStatus {
+	const age = monotonicNow - heartbeatMonotonicAt;
 	if (age <= spec.windowMs) return "alive";
 	if (age <= spec.windowMs + spec.graceMs) return "stale";
 	return "dead";

package/src/domains/dispatch/index.ts

@@ -21,7 +21,7 @@ export type {
 	AttemptRef,
 	DispatchAssignment,
 } from "./assignment.js";
-export type { DurableAssignmentRecord } from "./assignment-store.js";
+export type { AssignmentVerdictOwner, DurableAssignmentRecord } from "./assignment-store.js";
 export type { CodeStepOutcome, CodeStepRecord, CodeStepRunInput } from "./code-step.js";
 export {
 	canonicalCodeReport,
@@ -160,11 +160,16 @@ export {
 } from "./validation.js";
 export type {
 	WorkspaceSnapshot,
+	WriteBoundaryAttribution,
+	WriteBoundaryAttributionDowngrade,
+	WriteBoundaryAttributionDowngradeReason,
 	WriteBoundaryStatus,
 	WriteBoundaryVerdict,
 } from "./write-boundary.js";
 export {
+	assertWriteBoundaryVisibleToGit,
 	captureWorkspaceSnapshot,
+	describeWriteBoundaryAttributionDowngrade,
 	diffWorkspace,
 	enforceWriteBoundary,
 	WRITE_BOUNDARY_VIOLATION_REASON,

package/src/domains/dispatch/intent-requirements.ts

@@ -0,0 +1,40 @@
+import type { DispatchIntent } from "./intent.js";
+
+/** Render intent fields that describe required results rather than observed facts. */
+export function renderDispatchIntentRequirements(intent: DispatchIntent | undefined): string | null {
+	if (intent === undefined || (intent.expectedOutputs.length === 0 && intent.verification.length === 0)) return null;
+	const lines = [
+		"# Declared Result Requirements",
+		"These entries are requirements to satisfy and verify. They are not evidence that an output exists or a check passed.",
+	];
+	if (intent.expectedOutputs.length > 0) {
+		lines.push("", "Expected outputs:", ...intent.expectedOutputs.map((output) => `- ${output}`));
+	}
+	if (intent.verification.length > 0) {
+		lines.push(
+			"",
+			"Verification requirements:",
+			...intent.verification.map(
+				(entry) => `- ${entry.check} must pass within its declared timeout of ${entry.timeoutMs}ms`,
+			),
+		);
+	}
+	return lines.join("\n");
+}
+
+/** Build the reviewer assignment from the same requirements the builder received. */
+export function renderDispatchReviewerTask(
+	originalTask: string,
+	builderRunId: string,
+	cycle: number,
+	intent: DispatchIntent | undefined,
+): string {
+	const requirements = renderDispatchIntentRequirements(intent);
+	return [
+		`Review the work of builder run ${builderRunId} (review cycle ${cycle}).`,
+		"The builder's final answer is provided as input data; verify it against the workspace, do not trust it blindly.",
+		"Original task the builder was given:",
+		originalTask,
+		...(requirements === null ? [] : [requirements]),
+	].join("\n\n");
+}

package/src/domains/dispatch/intent.ts

@@ -1,6 +1,8 @@
 import path from "node:path";
+import { normalizePathBoundaryEntry, PATH_BOUNDARY_MAX_ENTRIES, PathBoundaryError } from "../../core/path-boundary.js";
+import { type DispatchPathProvenanceEntry, declaredIntentPathProvenance } from "./path-scope.js";
 
-export const DISPATCH_INTENT_PATH_LIST_CAP = 32;
+export const DISPATCH_INTENT_PATH_LIST_CAP = PATH_BOUNDARY_MAX_ENTRIES;
 export const DISPATCH_INTENT_PATH_ENTRY_BYTES_CAP = 512;
 export const DISPATCH_INTENT_VERIFICATION_CAP = 8;
 export const DISPATCH_INTENT_TIMEOUT_MIN_MS = 1_000;
@@ -11,10 +13,12 @@ export interface DispatchIntentVerification {
 }
 
 export interface DispatchIntent {
-	version: 1;
+	version: 2;
 	readRoots: string[];
 	writeRoots: string[];
 	relevantPaths: string[];
+	/** Integrity-sealed source and confidence for every policy-bearing path. */
+	pathProvenance: DispatchPathProvenanceEntry[];
 	expectedOutputs: string[];
 	verification: DispatchIntentVerification[];
 }
@@ -42,7 +46,7 @@ function fail(reason: string, message: string): DispatchIntentNormalizationResul
 	return { ok: false, reason, message };
 }
 
-function normalizePathEntry(value: unknown, field: string, index: number): string | DispatchIntentNormalizationResult {
+function checkedPathText(value: unknown, field: string, index: number): string | DispatchIntentNormalizationResult {
 	if (typeof value !== "string" || value.trim().length === 0) {
 		return fail("intent_path_malformed", `${field}[${index}] must be a non-empty repository-relative POSIX path`);
 	}
@@ -53,6 +57,42 @@ function normalizePathEntry(value: unknown, field: string, index: number): strin
 			`${field}[${index}] exceeds the ${DISPATCH_INTENT_PATH_ENTRY_BYTES_CAP}-byte cap`,
 		);
 	}
+	return trimmed;
+}
+
+function normalizeScopePathEntry(
+	value: unknown,
+	field: string,
+	index: number,
+): string | DispatchIntentNormalizationResult {
+	const checked = checkedPathText(value, field, index);
+	if (typeof checked !== "string") return checked;
+	try {
+		return normalizePathBoundaryEntry(checked);
+	} catch (error) {
+		if (error instanceof PathBoundaryError) {
+			if (error.code === "absolute") {
+				return fail("intent_path_absolute", `${field}[${index}] must be a repository-relative POSIX path`);
+			}
+			if (error.code === "parent") {
+				return fail("intent_path_escapes_root", `${field}[${index}] escapes the repository root`);
+			}
+		}
+		return fail(
+			"intent_path_malformed",
+			`${field}[${index}] does not follow the repository path boundary grammar: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+function normalizeExpectedOutputEntry(
+	value: unknown,
+	field: string,
+	index: number,
+): string | DispatchIntentNormalizationResult {
+	const checked = checkedPathText(value, field, index);
+	if (typeof checked !== "string") return checked;
+	const trimmed = checked;
 	if (trimmed.includes("\\") || path.posix.isAbsolute(trimmed) || path.win32.isAbsolute(trimmed)) {
 		return fail("intent_path_absolute", `${field}[${index}] must be a repository-relative POSIX path`);
 	}
@@ -66,7 +106,15 @@ function normalizePathEntry(value: unknown, field: string, index: number): strin
 	return normalized;
 }
 
-function normalizePathList(value: unknown, field: string): string[] | DispatchIntentNormalizationResult {
+function normalizePathList(
+	value: unknown,
+	field: string,
+	normalizeEntry: (
+		value: unknown,
+		field: string,
+		index: number,
+	) => string | DispatchIntentNormalizationResult = normalizeScopePathEntry,
+): string[] | DispatchIntentNormalizationResult {
 	if (value === undefined) return [];
 	if (!Array.isArray(value)) return fail("intent_path_malformed", `${field} must be an array`);
 	if (value.length > DISPATCH_INTENT_PATH_LIST_CAP) {
@@ -74,7 +122,7 @@ function normalizePathList(value: unknown, field: string): string[] | DispatchIn
 	}
 	const normalized: string[] = [];
 	for (const [index, entry] of value.entries()) {
-		const result = normalizePathEntry(entry, field, index);
+		const result = normalizeEntry(entry, field, index);
 		if (typeof result !== "string") return result;
 		normalized.push(result);
 	}
@@ -82,10 +130,26 @@ function normalizePathList(value: unknown, field: string): string[] | DispatchIn
 }
 
 export function isDispatchIntent(value: unknown): value is DispatchIntent {
-	if (!isRecord(value) || value.version !== 1) return false;
+	if (!isRecord(value) || value.version !== 2) return false;
 	for (const field of ["readRoots", "writeRoots", "relevantPaths", "expectedOutputs"] as const) {
 		if (!Array.isArray(value[field]) || !value[field].every((entry) => typeof entry === "string")) return false;
 	}
+	const readRoots = value.readRoots as string[];
+	const writeRoots = value.writeRoots as string[];
+	const relevantPaths = value.relevantPaths as string[];
+	if (
+		!Array.isArray(value.pathProvenance) ||
+		JSON.stringify(value.pathProvenance) !==
+			JSON.stringify(
+				declaredIntentPathProvenance({
+					readRoots,
+					writeRoots,
+					relevantPaths,
+				}),
+			)
+	) {
+		return false;
+	}
 	return (
 		Array.isArray(value.verification) &&
 		value.verification.every(
@@ -115,7 +179,11 @@ export function normalizeDispatchIntent(
 	if (!Array.isArray(writeRoots)) return writeRoots;
 	const relevantPaths = normalizePathList(raw.relevant_paths, "intent.relevant_paths");
 	if (!Array.isArray(relevantPaths)) return relevantPaths;
-	const expectedOutputs = normalizePathList(raw.expected_outputs, "intent.expected_outputs");
+	const expectedOutputs = normalizePathList(
+		raw.expected_outputs,
+		"intent.expected_outputs",
+		normalizeExpectedOutputEntry,
+	);
 	if (!Array.isArray(expectedOutputs)) return expectedOutputs;
 	const rawVerification = raw.verification ?? [];
 	if (!Array.isArray(rawVerification)) {
@@ -154,6 +222,14 @@ export function normalizeDispatchIntent(
 	}
 	return {
 		ok: true,
-		intent: { version: 1, readRoots, writeRoots, relevantPaths, expectedOutputs, verification },
+		intent: {
+			version: 2,
+			readRoots,
+			writeRoots,
+			relevantPaths,
+			pathProvenance: declaredIntentPathProvenance({ readRoots, writeRoots, relevantPaths }),
+			expectedOutputs,
+			verification,
+		},
 	};
 }

package/src/domains/dispatch/orphan-recovery.ts

@@ -172,6 +172,11 @@ function sealedEnvelopeFor(runId: string): RunEnvelope | null {
  * whole orchestrator downtime, which is not a measurement of anything. The
  * last heartbeat is the honest bound; a row that never heartbeat has only its
  * own start, which reads as a zero-length run rather than an invented one.
+ *
+ * A restart has no shared monotonic origin with the process that owned the
+ * worker, so recovery never estimates heartbeat age. It first adjudicates the
+ * host-scoped pid and uses the persisted wall-clock heartbeat only as this
+ * display/evidence bound after that process is known to be gone.
  */
 function closeAbandonedRows(ledger: Ledger): { closed: number; sealed: number } {
 	let closed = 0;