@iowarp/clio-coder 0.3.8 → 0.4.0

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.
+ */
+export 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-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,9 +45,11 @@ 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";
+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. */
@@ -82,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. */
@@ -191,7 +204,18 @@ export interface FleetRunOutcome {
 	planHash: string;
 	result: ExecutionPlanResult;
 	receipts: ReadonlyArray<RunReceipt>;
+	/**
+	 * The bare sum of every receipt's `costUsd`, which adds unpriced zeros to
+	 * priced dollars and so cannot be rendered on its own. Retained for the
+	 * interactive fleet overlay, which still reads it. Render `totalCost`.
+	 */
 	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;
@@ -216,6 +240,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));
 }
@@ -278,10 +320,29 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 			// 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 || step.kind !== "agent") return null;
+			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;
-			return dispatch.observedRunWrites?.(receipt.runId) ?? 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) {
 			// Concurrent changes are reported too. The window did not fail for them
@@ -318,6 +379,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);
@@ -414,11 +478,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: {
@@ -571,11 +648,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,
@@ -638,6 +716,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,
 				});
@@ -704,7 +784,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;
@@ -783,6 +863,9 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 		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");
 }

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.",

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

@@ -0,0 +1,289 @@
+/**
+ * Read-only projection of the durable coordinator gate decisions.
+ *
+ * Unlike a council, a gate has a record of its own. A reviewer verdict and a
+ * judge's winner cannot be written back into the subject receipts without
+ * invalidating them, so the coordinator seals a separate integrity-covered
+ * artifact per decision that links the decider receipt to every subject
+ * receipt. {@link gate-decisions.ts} owns writing and verifying those; this
+ * module reads a bounded newest-first window of them and projects the shape.
+ *
+ * Two things stay behind. The decision `detail` is free prose that interpolates
+ * a thrown message, a pipeline failure reason, a protected artifact list, or a
+ * plan hash, so it is classified against a closed set and never quoted. And the
+ * receipt digests are omitted outright: a verified artifact carries one per
+ * subject by construction, so repeating them would be a fingerprint that tells
+ * a reader nothing the run id does not.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { clioStateDir } from "../../core/xdg.js";
+import type { GateRouteCorrelation } from "./execution-role.js";
+import {
+	type GateDecisionArtifact,
+	type GateDecisionOutcome,
+	gateDecisionsDirectory,
+	verifyGateDecisionArtifact,
+} from "./gate-decisions.js";
+
+/** How many decisions one projection reports, newest first. */
+export const GATE_TOPOLOGY_MAX_DECISIONS = 8;
+
+/** Subject receipts named per decision. A compete gate judges at most four. */
+export const GATE_TOPOLOGY_MAX_SUBJECTS = 6;
+
+/**
+ * How many artifact files one listing will open.
+ *
+ * The directory is unbounded and a decision id sorts by its group before its
+ * timestamp, so the newest decision is only discoverable by reading each file's
+ * `createdAt`. The cap keeps the scan proportional on an installation that has
+ * accumulated gates for months, at the cost of missing a decision older than
+ * the cap. That is the right trade here, the same one {@link listFleetRuns}
+ * takes, because this window only ever wants the recent end.
+ */
+export const GATE_TOPOLOGY_MAX_SCAN = 128;
+
+/**
+ * Why a gate ended the way it did, as a closed set.
+ *
+ * Every member is the coordinator's own classification of its own branch. The
+ * durable `detail` string those branches write is not repeated: several
+ * interpolate a receipt's failure reason, the names of protected artifacts a
+ * candidate touched, or an approval request id, and any of the three would
+ * carry prose across a boundary that exists to stop exactly that. Anything this
+ * classifier does not recognise becomes `unclassified` rather than crossing.
+ */
+export type GateDecisionReason =
+	| "all-candidates-failed"
+	| "builder-run-failed"
+	| "reviewer-run-failed"
+	| "reviewer-checks-failed"
+	| "reviewer-report-invalid"
+	| "judge-run-failed"
+	| "judge-result-invalid"
+	| "judge-winner-out-of-range"
+	| "judge-picked-failed-candidate"
+	| "winner-touches-protected-artifact"
+	| "operator-confirmed-winner"
+	| "full-auto-applied-winner"
+	| "unclassified";
+
+export const GATE_DECISION_REASONS: ReadonlyArray<GateDecisionReason> = [
+	"all-candidates-failed",
+	"builder-run-failed",
+	"reviewer-run-failed",
+	"reviewer-checks-failed",
+	"reviewer-report-invalid",
+	"judge-run-failed",
+	"judge-result-invalid",
+	"judge-winner-out-of-range",
+	"judge-picked-failed-candidate",
+	"winner-touches-protected-artifact",
+	"operator-confirmed-winner",
+	"full-auto-applied-winner",
+	"unclassified",
+];
+
+/**
+ * Prefix rules, first match wins, ordered so no rule shadows another.
+ *
+ * These are matched against the exact strings the coordinator writes. A rule
+ * failing to match costs its decision the specific reason and nothing else,
+ * because `unclassified` is a real answer here: the operator still learns that
+ * the gate ended and how, just not which branch produced the text.
+ */
+const REASON_RULES: ReadonlyArray<readonly [string, GateDecisionReason]> = [
+	["every candidate builder failed", "all-candidates-failed"],
+	["builder ended ", "builder-run-failed"],
+	["reviewer ended ", "reviewer-run-failed"],
+	["reviewer reported ", "reviewer-checks-failed"],
+	["reviewer did not return a valid verifier report", "reviewer-report-invalid"],
+	["judge ended ", "judge-run-failed"],
+	["judge result must", "judge-result-invalid"],
+	["judge result has unknown fields", "judge-result-invalid"],
+	["judge winner must be an integer", "judge-winner-out-of-range"],
+	["judge picked failed or missing candidate", "judge-picked-failed-candidate"],
+	["judge-selected candidate ", "winner-touches-protected-artifact"],
+	["operator confirmation ", "operator-confirmed-winner"],
+	["full-auto applied ", "full-auto-applied-winner"],
+];
+
+/**
+ * The identifier shape the decision store already guarantees for both its ids
+ * and, transitively, its groups.
+ *
+ * A decision id is minted from a sanitized group plus a timestamp and random
+ * suffix, and a group is a coordinator-minted gate id. Re-enforcing the shape
+ * here means whatever wrote the file, the identifiers this projection reports
+ * can carry no separator, space, quote, or control byte.
+ */
+const SAFE_GATE_IDENTIFIER = /^[A-Za-z0-9._:-]{1,128}$/u;
+
+/** The independence facts sealed on the decision, exactly as the artifact holds them. */
+export type GateDecisionCorrelationFacts = Pick<
+	GateRouteCorrelation,
+	"agent" | "target" | "modelFamily" | "runtime" | "node" | "independent"
+>;
+
+export interface GateTopologyWinner {
+	/** 1-based candidate ordinal the judge picked. */
+	readonly index: number;
+	readonly runId: string;
+}
+
+export interface GateTopologyDecision {
+	readonly id: string;
+	readonly group: string;
+	readonly topology: "review" | "compete";
+	readonly cycle: number;
+	readonly outcome: GateDecisionOutcome;
+	readonly decidedAt: string;
+	/** Runs this decision graded, in the order the coordinator sealed them. */
+	readonly subjects: readonly string[];
+	readonly subjectsTruncated: boolean;
+	/** The run that produced the verdict, or null when none ran. */
+	readonly decider: string | null;
+	/** Present exactly when a decider ran; the store requires the pair. */
+	readonly correlation: GateDecisionCorrelationFacts | null;
+	readonly winner: GateTopologyWinner | null;
+	/** A prior judge decision this one confirmed, by id. */
+	readonly confirms: string | null;
+	readonly reason: GateDecisionReason | null;
+}
+
+export interface GateTopologyResult {
+	/**
+	 * Whether this installation has a decision store at all.
+	 *
+	 * An installation that has never run a gate and one whose gates all aged out
+	 * both report no decisions, and they are different operator states, so the
+	 * fact is read rather than inferred from an empty list.
+	 */
+	readonly present: boolean;
+	readonly decisions: readonly GateTopologyDecision[];
+	/** True when the scanned window held decisions older than the reported ones. */
+	readonly truncated: boolean;
+	/**
+	 * Files in the scanned window whose integrity did not verify.
+	 *
+	 * The store's own read API drops these silently, which is right for a
+	 * consumer that must not act on untrusted evidence and wrong for an operator
+	 * surface: a gate artifact that no longer authenticates is exactly the thing
+	 * worth knowing about. Counted, never opened for content.
+	 */
+	readonly unverifiable: number;
+}
+
+function classifyReason(detail: unknown): GateDecisionReason | null {
+	if (typeof detail !== "string" || detail.length === 0) return null;
+	return REASON_RULES.find(([prefix]) => detail.startsWith(prefix))?.[1] ?? "unclassified";
+}
+
+function safeIdentifier(value: unknown): string | null {
+	return typeof value === "string" && SAFE_GATE_IDENTIFIER.test(value) ? value : null;
+}
+
+/** Newest decision first. An unparseable stamp sorts oldest rather than throwing. */
+function byNewest(a: GateDecisionArtifact, b: GateDecisionArtifact): number {
+	return (Date.parse(b.createdAt) || 0) - (Date.parse(a.createdAt) || 0);
+}
+
+/**
+ * Read a bounded window of verified decision artifacts, counting the rest.
+ *
+ * Reads defensively per file for the same reason the ledger scan does: one
+ * artifact written by another build, half-written, or removed between the
+ * listing and the open must cost that decision its row, never the whole
+ * listing. A file that parses but fails its own integrity check is a different
+ * state and is counted rather than dropped.
+ */
+function readDecisionWindow(stateDir: string): {
+	present: boolean;
+	artifacts: GateDecisionArtifact[];
+	unverifiable: number;
+} {
+	const directory = gateDecisionsDirectory(stateDir);
+	if (!existsSync(directory)) return { present: false, artifacts: [], unverifiable: 0 };
+	let entries: string[];
+	try {
+		entries = readdirSync(directory).filter((name) => name.endsWith(".json"));
+	} catch {
+		// The directory is there and unreadable, which is not the same as absent.
+		return { present: true, artifacts: [], unverifiable: 0 };
+	}
+	const artifacts: GateDecisionArtifact[] = [];
+	let unverifiable = 0;
+	for (const name of entries.slice(0, GATE_TOPOLOGY_MAX_SCAN)) {
+		let artifact: GateDecisionArtifact;
+		try {
+			artifact = JSON.parse(readFileSync(join(directory, name), "utf8")) as GateDecisionArtifact;
+		} catch {
+			unverifiable += 1;
+			continue;
+		}
+		if (verifyGateDecisionArtifact(artifact).ok) artifacts.push(artifact);
+		else unverifiable += 1;
+	}
+	artifacts.sort(byNewest);
+	return { present: true, artifacts, unverifiable };
+}
+
+function projectDecision(artifact: GateDecisionArtifact): GateTopologyDecision | null {
+	const id = safeIdentifier(artifact.id);
+	const group = safeIdentifier(artifact.group);
+	// The store mints both and already refuses either outside this shape, so a
+	// stored value failing it means something else wrote the file. A decision
+	// this projection cannot name is one it will not report.
+	if (id === null || group === null) return null;
+	const allSubjects = artifact.subjects.map((subject) => safeIdentifier(subject.runId));
+	if (allSubjects.some((runId) => runId === null)) return null;
+	const subjects = (allSubjects as string[]).slice(0, GATE_TOPOLOGY_MAX_SUBJECTS);
+	const decider = artifact.decider === undefined ? null : safeIdentifier(artifact.decider.runId);
+	if (artifact.decider !== undefined && decider === null) return null;
+	let winner: GateTopologyWinner | null = null;
+	if (artifact.winner !== undefined) {
+		const runId = safeIdentifier(artifact.winner.subject.runId);
+		if (runId === null) return null;
+		winner = { index: artifact.winner.index, runId };
+	}
+	return {
+		id,
+		group,
+		topology: artifact.topology,
+		cycle: artifact.cycle,
+		outcome: artifact.outcome,
+		decidedAt: new Date(artifact.createdAt).toISOString(),
+		subjects,
+		subjectsTruncated: allSubjects.length > subjects.length,
+		decider,
+		correlation: artifact.correlation === undefined ? null : { ...artifact.correlation },
+		winner,
+		confirms: artifact.confirmation === undefined ? null : safeIdentifier(artifact.confirmation.id),
+		reason: classifyReason(artifact.detail),
+	};
+}
+
+/**
+ * Bounded newest-first coordinator gate decisions.
+ *
+ * Selected by this function, never by a caller's argument, so a host that
+ * invokes the command behind it knows the process cannot be steered into a
+ * different window.
+ */
+export function gateTopology(stateDir: string = clioStateDir()): GateTopologyResult {
+	const { present, artifacts, unverifiable } = readDecisionWindow(stateDir);
+	const window = artifacts.slice(0, GATE_TOPOLOGY_MAX_DECISIONS);
+	const decisions: GateTopologyDecision[] = [];
+	for (const artifact of window) {
+		const decision = projectDecision(artifact);
+		if (decision !== null) decisions.push(decision);
+	}
+	return {
+		present,
+		decisions,
+		truncated: artifacts.length > window.length || decisions.length !== window.length,
+		unverifiable,
+	};
+}

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";