@iowarp/clio-coder 0.3.9 → 0.4.0

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

@@ -0,0 +1,330 @@
+/**
+ * The one migration and refusal policy for typed dispatch intent.
+ *
+ * Typed intent (#155) is authoritative for policy-bearing scope (#158) and the
+ * legacy prose-inference path (#159) survives beside it. Those three landed the
+ * mechanism; this module owns the lifecycle question they left open: for any
+ * dispatch producer, what happens when intent is omitted, partially declared,
+ * carries a version this build does not speak, or contradicts another field on
+ * the same request.
+ *
+ * Every answer here is one of three decisions, and the boundary between them is
+ * the load-bearing rule:
+ *
+ * - `accept`: the request is unambiguous. Nothing is reported.
+ * - `warn`: the request is compatible but its policy-bearing scope was resolved
+ *   from something weaker than a declaration. The dispatch proceeds with the
+ *   authority it would have had anyway; the warning exists so the weaker basis
+ *   is visible before execution and countable afterwards.
+ * - `refuse`: the request states two incompatible things about authority, or
+ *   states one this build cannot interpret. The dispatch never runs.
+ *
+ * A `warn` may never be the difference between a narrow and a wide grant. That
+ * is the invariant every rule below is written to preserve: no path through this
+ * module widens read, write, or verification authority to resolve an ambiguity.
+ * When the compatible reading and the declared reading disagree about what a
+ * worker may touch, the answer is a refusal, never the union.
+ *
+ * The module is pure: no filesystem, no clock, no package-layout lookup. A
+ * source checkout and an installed package classify identical input identically,
+ * which is what makes the version rules verifiable rather than environmental.
+ */
+
+import { pathBoundaryCovers, resolvePathBoundary } from "../../core/path-boundary.js";
+import { type DispatchIntent, isDispatchIntent } from "./intent.js";
+
+/** The intent shape this build speaks. Bump with the `DispatchIntent` interface. */
+export const DISPATCH_INTENT_VERSION = 2;
+
+/**
+ * Every intent version this build accepts. Deliberately not a range: a reader
+ * that accepts "2 or newer" accepts fields it cannot interpret, and a reader
+ * that accepts "2 or older" reads a v1 declaration under v2 rules. Membership in
+ * this list is the whole test.
+ */
+export const DISPATCH_INTENT_SUPPORTED_VERSIONS: ReadonlyArray<number> = [DISPATCH_INTENT_VERSION];
+
+export type DispatchIntentCompatibilityDecision = "accept" | "warn" | "refuse";
+
+/**
+ * Stable reason codes. These are a contract: they appear in refusal messages,
+ * diagnostics, and contract tests, and callers may branch on them. Renaming one
+ * is a breaking change to every surface that reports dispatch admission.
+ */
+export type DispatchIntentCompatibilityCode =
+	/** No typed intent at all; policy-bearing scope came from legacy inference. */
+	| "intent_absent_legacy_inference"
+	/** Typed intent declared paths but no verification requirement. */
+	| "intent_partial_verification_absent"
+	/** `intent.version` names a version this build does not speak. */
+	| "intent_version_unsupported"
+	/** Present but not a normalized intent for a reason other than its version. */
+	| "intent_malformed"
+	/** Declared `intent.write_roots` and legacy `writeRoots` name different trees. */
+	| "intent_write_roots_contradiction"
+	/** A declared expected output lies outside every declared write root. */
+	| "intent_outputs_outside_write_roots"
+	/** Write roots declared on a request whose autonomy cannot write. */
+	| "intent_write_without_authority"
+	/** A narrowed intent reaches outside the intent it is supposed to narrow. */
+	| "intent_scope_widening";
+
+export interface DispatchIntentCompatibilityFinding {
+	code: DispatchIntentCompatibilityCode;
+	decision: DispatchIntentCompatibilityDecision;
+	/** Operator-facing text, prefixed with the code and naming the fix. */
+	message: string;
+}
+
+export interface DispatchIntentCompatibilityInput {
+	/** The request's `intent` field exactly as the producer set it. */
+	intent?: unknown;
+	/** The request's legacy `writeRoots` field exactly as the producer set it. */
+	writeRoots?: unknown;
+	/** Request-level autonomy narrowing, when the producer set one. */
+	autonomy?: unknown;
+	/** Job cwd used to compare the two write declarations on one footing. */
+	cwd?: string;
+}
+
+function finding(
+	code: DispatchIntentCompatibilityCode,
+	decision: DispatchIntentCompatibilityDecision,
+	detail: string,
+): DispatchIntentCompatibilityFinding {
+	return { code, decision, message: `${code}: ${detail}` };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function declaredVersion(value: Record<string, unknown>): number | null {
+	return typeof value.version === "number" && Number.isInteger(value.version) ? value.version : null;
+}
+
+/** Whether an intent-shaped value carries a version this build can interpret. */
+export function isSupportedDispatchIntentVersion(value: unknown): boolean {
+	if (!isRecord(value)) return false;
+	const version = declaredVersion(value);
+	return version !== null && DISPATCH_INTENT_SUPPORTED_VERSIONS.includes(version);
+}
+
+function versionFinding(value: Record<string, unknown>): DispatchIntentCompatibilityFinding {
+	const version = declaredVersion(value);
+	const supported = DISPATCH_INTENT_SUPPORTED_VERSIONS.join(", ");
+	if (version === null) {
+		return finding(
+			"intent_version_unsupported",
+			"refuse",
+			`intent carries no integer version; this build speaks dispatch intent version ${supported}. Re-declare the intent through the dispatch tool rather than replaying a stored object.`,
+		);
+	}
+	return finding(
+		"intent_version_unsupported",
+		"refuse",
+		`intent declares version ${version}; this build speaks dispatch intent version ${supported}. A stored plan or spec at another version is refused rather than migrated: re-declare read_roots, write_roots, relevant_paths, expected_outputs, and verification on a fresh dispatch call.`,
+	);
+}
+
+function legacyWriteRoots(value: unknown): string[] | null {
+	if (!Array.isArray(value)) return null;
+	const roots = value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
+	return roots.length === value.length ? roots : null;
+}
+
+function writeRootsContradiction(
+	intent: DispatchIntent,
+	writeRoots: ReadonlyArray<string>,
+	cwd: string,
+): DispatchIntentCompatibilityFinding | null {
+	const resolve = (roots: ReadonlyArray<string>): string =>
+		JSON.stringify([...new Set(roots.map((root) => resolvePathBoundary(cwd, root)))].sort());
+	if (resolve(writeRoots) === resolve(intent.writeRoots)) return null;
+	return finding(
+		"intent_write_roots_contradiction",
+		"refuse",
+		`legacy writeRoots [${[...writeRoots].sort().join(", ")}] and intent.write_roots [${intent.writeRoots.join(", ")}] name different trees. Neither the union nor the legacy field wins: drop writeRoots and declare the exact write scope once in intent.write_roots.`,
+	);
+}
+
+function outputsOutsideWriteRoots(intent: DispatchIntent): DispatchIntentCompatibilityFinding | null {
+	if (intent.writeRoots.length === 0 || intent.expectedOutputs.length === 0) return null;
+	const outside = intent.expectedOutputs.filter((output) => !pathBoundaryCovers(intent.writeRoots, output));
+	if (outside.length === 0) return null;
+	return finding(
+		"intent_outputs_outside_write_roots",
+		"refuse",
+		`expected_outputs [${outside.join(", ")}] lie outside intent.write_roots [${intent.writeRoots.join(", ")}]. The write boundary would block exactly the outputs the task is required to produce, so add each output's root to write_roots or drop the output from the declaration.`,
+	);
+}
+
+function writeWithoutAuthority(intent: DispatchIntent, autonomy: unknown): DispatchIntentCompatibilityFinding | null {
+	if (intent.writeRoots.length === 0 || autonomy !== "read-only") return null;
+	return finding(
+		"intent_write_without_authority",
+		"refuse",
+		`intent.write_roots [${intent.writeRoots.join(", ")}] was declared on a read-only request. A read-only worker cannot be granted the declared trees and the declaration cannot be silently dropped, because dropping it would leave the request claiming a write scope nothing enforces. Declare write_roots only on a writing request.`,
+	);
+}
+
+/**
+ * Classify one dispatch request's intent against the compatibility rules.
+ *
+ * Findings are returned in a stable order: version and shape first (a value this
+ * build cannot read makes every later question meaningless), then the
+ * contradictions between intent and its neighbouring fields, then the
+ * lower-confidence notices. Callers treat any `refuse` as terminal.
+ */
+export function classifyDispatchIntentCompatibility(
+	input: DispatchIntentCompatibilityInput,
+): DispatchIntentCompatibilityFinding[] {
+	const findings: DispatchIntentCompatibilityFinding[] = [];
+	if (input.intent === undefined) {
+		findings.push(
+			finding(
+				"intent_absent_legacy_inference",
+				"warn",
+				"no typed intent was declared, so policy-bearing scope was resolved from legacy writeRoots plus path-like task and briefing tokens. Inferred paths select project rules and worker context only; they never widen write or verification authority. Declare intent.read_roots, intent.write_roots, and intent.relevant_paths to make the scope exact.",
+			),
+		);
+		return findings;
+	}
+	if (!isRecord(input.intent)) {
+		findings.push(
+			finding(
+				"intent_malformed",
+				"refuse",
+				"intent must be an object carrying normalized read_roots, write_roots, relevant_paths, expected_outputs, and verification.",
+			),
+		);
+		return findings;
+	}
+	if (!isSupportedDispatchIntentVersion(input.intent)) {
+		findings.push(versionFinding(input.intent));
+		return findings;
+	}
+	if (!isDispatchIntent(input.intent)) {
+		findings.push(
+			finding(
+				"intent_malformed",
+				"refuse",
+				`intent declares supported version ${DISPATCH_INTENT_VERSION} but is not a normalized intent: path lists must be deduplicated and sorted, pathProvenance must match the declared fields exactly, and every verification entry must name a declared check with an integer timeout. Re-declare it through the dispatch tool rather than hand-building the normalized object.`,
+			),
+		);
+		return findings;
+	}
+	const intent = input.intent;
+	const cwd = typeof input.cwd === "string" && input.cwd.length > 0 ? input.cwd : process.cwd();
+	const legacy = input.writeRoots === undefined ? null : legacyWriteRoots(input.writeRoots);
+	if (legacy !== null && legacy.length > 0 && intent.writeRoots.length > 0) {
+		const contradiction = writeRootsContradiction(intent, legacy, cwd);
+		if (contradiction !== null) findings.push(contradiction);
+	}
+	const outputs = outputsOutsideWriteRoots(intent);
+	if (outputs !== null) findings.push(outputs);
+	const authority = writeWithoutAuthority(intent, input.autonomy);
+	if (authority !== null) findings.push(authority);
+	if (intent.verification.length === 0 && (intent.writeRoots.length > 0 || intent.expectedOutputs.length > 0)) {
+		findings.push(
+			finding(
+				"intent_partial_verification_absent",
+				"warn",
+				"intent declares work that changes the tree but no verification requirement, so nothing the orchestrator runs proves the change is sound. Add intent.verification entries naming declared check ids from package scripts or .clio-coder/verifiers.yaml.",
+			),
+		);
+	}
+	return findings;
+}
+
+/** Every terminal refusal in a classification, in reporting order. */
+export function dispatchIntentRefusals(
+	findings: ReadonlyArray<DispatchIntentCompatibilityFinding>,
+): DispatchIntentCompatibilityFinding[] {
+	return findings.filter((entry) => entry.decision === "refuse");
+}
+
+/**
+ * Whether a narrowed intent stays inside the intent it narrows.
+ *
+ * Batch tasks, agent profiles, and fleet contracts may all restate scope more
+ * tightly than the call that contains them. Narrowing is monotonic: a per-task
+ * declaration may shrink the ceiling and may never reach outside it. Read scope
+ * is checked against reads plus writes because a declared write root is
+ * necessarily readable; write scope is checked against writes alone.
+ */
+export function dispatchIntentScopeWidening(
+	ceiling: Pick<DispatchIntent, "readRoots" | "writeRoots" | "relevantPaths">,
+	narrowed: Pick<DispatchIntent, "readRoots" | "writeRoots" | "relevantPaths">,
+): DispatchIntentCompatibilityFinding | null {
+	const ceilings = {
+		readRoots: [...ceiling.readRoots, ...ceiling.writeRoots],
+		writeRoots: [...ceiling.writeRoots],
+		relevantPaths: [...ceiling.readRoots, ...ceiling.writeRoots, ...ceiling.relevantPaths],
+	} as const;
+	for (const field of ["readRoots", "writeRoots", "relevantPaths"] as const) {
+		const outside = narrowed[field].find((candidate) => !pathBoundaryCovers(ceilings[field], candidate));
+		if (outside === undefined) continue;
+		return finding(
+			"intent_scope_widening",
+			"refuse",
+			`${field} entry '${outside}' is outside the enclosing intent ceiling [${ceilings[field].join(", ") || "empty"}]. A narrower scope may shrink the ceiling and never reach outside it; add the path to the enclosing declaration or drop it here.`,
+		);
+	}
+	return null;
+}
+
+/**
+ * The retirement criterion for the legacy inference fallback.
+ *
+ * `pathScope.mode` is sealed on every receipt, so the share of dispatches still
+ * resolving policy-bearing scope from prose is measurable from evidence rather
+ * than estimated. Removal stays a separate, explicit issue; this is the gate
+ * that issue has to clear before it can be opened.
+ */
+export const DISPATCH_INTENT_RETIREMENT_MAX_LEGACY_SHARE = 0.02;
+
+/** Receipts below this count cannot decide the criterion either way. */
+export const DISPATCH_INTENT_RETIREMENT_MIN_SAMPLE = 200;
+
+export interface DispatchIntentAdoption {
+	/** Receipts carrying a resolved path scope; receipts without one are not evidence. */
+	measured: number;
+	declared: number;
+	legacyInferred: number;
+	/** `null` when nothing was measured, so an empty window never reads as full adoption. */
+	legacyShare: number | null;
+	/** True only when the sample is large enough and the legacy share is at or under the bound. */
+	retirementReady: boolean;
+}
+
+/**
+ * Measure typed-intent adoption from sealed receipts.
+ *
+ * Reads only `pathScope.mode`. No task text, briefing prose, or declared path
+ * ever enters the aggregate, so the measurement is safe to report from a fleet
+ * whose receipts this caller may count but must not quote.
+ */
+export function dispatchIntentAdoption(
+	receipts: ReadonlyArray<{ pathScope?: { mode: "declared" | "legacy-inferred" } }>,
+): DispatchIntentAdoption {
+	let declared = 0;
+	let legacyInferred = 0;
+	for (const receipt of receipts) {
+		if (receipt.pathScope === undefined) continue;
+		if (receipt.pathScope.mode === "declared") declared += 1;
+		else legacyInferred += 1;
+	}
+	const measured = declared + legacyInferred;
+	const legacyShare = measured === 0 ? null : legacyInferred / measured;
+	return {
+		measured,
+		declared,
+		legacyInferred,
+		legacyShare,
+		retirementReady:
+			measured >= DISPATCH_INTENT_RETIREMENT_MIN_SAMPLE &&
+			legacyShare !== null &&
+			legacyShare <= DISPATCH_INTENT_RETIREMENT_MAX_LEGACY_SHARE,
+	};
+}

package/src/domains/dispatch/intent.ts

@@ -32,7 +32,20 @@ export type DispatchIntentNormalizationResult =
 	| { ok: true; intent: DispatchIntent }
 	| { ok: false; reason: string; message: string };
 
-const RAW_FIELDS = new Set(["read_roots", "write_roots", "relevant_paths", "expected_outputs", "verification"]);
+/**
+ * `version` is accepted on raw model-facing intent so a caller replaying a
+ * declaration it was shown can echo the version back. It is validated, never
+ * trusted: an unsupported value is a terminal refusal rather than a field the
+ * normalizer quietly overwrites with the version this build speaks.
+ */
+const RAW_FIELDS = new Set([
+	"version",
+	"read_roots",
+	"write_roots",
+	"relevant_paths",
+	"expected_outputs",
+	"verification",
+]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -129,6 +142,47 @@ function normalizePathList(
 	return [...new Set(normalized)].sort(compareCodepoints);
 }
 
+/**
+ * Build typed intent from paths a non-model producer already holds.
+ *
+ * Fleet contracts, CLI entry points, and extensions declare repository-relative
+ * scope in their own artifacts long before a dispatch request exists. Without
+ * this they hand the request nothing, and the scope resolver falls back to
+ * reading path-like tokens out of the rendered prompt, which is the exact
+ * ambiguity typed intent removes. The paths go through the same normalization,
+ * caps, and provenance construction as a model-facing declaration, so a
+ * producer cannot mint an intent shape the dispatch tool could not.
+ *
+ * Verification and expected outputs are deliberately not accepted here.
+ * A declared check id has to be resolved against the project's verification
+ * catalog before it means anything, and that resolution belongs to the
+ * admission controller that owns the catalog, not to a scope builder.
+ */
+export function declaredScopeIntent(input: {
+	readRoots?: ReadonlyArray<string>;
+	writeRoots?: ReadonlyArray<string>;
+	relevantPaths?: ReadonlyArray<string>;
+}): DispatchIntentNormalizationResult {
+	const readRoots = normalizePathList(input.readRoots, "intent.read_roots");
+	if (!Array.isArray(readRoots)) return readRoots;
+	const writeRoots = normalizePathList(input.writeRoots, "intent.write_roots");
+	if (!Array.isArray(writeRoots)) return writeRoots;
+	const relevantPaths = normalizePathList(input.relevantPaths, "intent.relevant_paths");
+	if (!Array.isArray(relevantPaths)) return relevantPaths;
+	return {
+		ok: true,
+		intent: {
+			version: 2,
+			readRoots,
+			writeRoots,
+			relevantPaths,
+			pathProvenance: declaredIntentPathProvenance({ readRoots, writeRoots, relevantPaths }),
+			expectedOutputs: [],
+			verification: [],
+		},
+	};
+}
+
 export function isDispatchIntent(value: unknown): value is DispatchIntent {
 	if (!isRecord(value) || value.version !== 2) return false;
 	for (const field of ["readRoots", "writeRoots", "relevantPaths", "expectedOutputs"] as const) {
@@ -164,6 +218,30 @@ export function isDispatchIntent(value: unknown): value is DispatchIntent {
 	);
 }
 
+/**
+ * Project a declared intent onto a run that may not write.
+ *
+ * Council members, reviewers, judges, and any other read-only expansion of a
+ * caller's single task inherit the caller's declared scope. Inheriting
+ * `writeRoots` verbatim would leave the request claiming a write scope the run's
+ * autonomy makes unenforceable, so the write roots become read roots: the same
+ * trees, strictly less authority. Nothing is added, so the projection can only
+ * narrow. Returns the input unchanged when there is no write scope to demote.
+ */
+export function narrowDispatchIntentToReadOnly(intent: DispatchIntent): DispatchIntent {
+	if (intent.writeRoots.length === 0) return intent;
+	const readRoots = [...new Set([...intent.readRoots, ...intent.writeRoots])].sort(compareCodepoints);
+	return {
+		version: 2,
+		readRoots,
+		writeRoots: [],
+		relevantPaths: [...intent.relevantPaths],
+		pathProvenance: declaredIntentPathProvenance({ readRoots, writeRoots: [], relevantPaths: intent.relevantPaths }),
+		expectedOutputs: [...intent.expectedOutputs],
+		verification: intent.verification.map((entry) => ({ ...entry })),
+	};
+}
+
 export function normalizeDispatchIntent(
 	raw: unknown,
 	checks: ReadonlyMap<string, DispatchIntentCheckBound>,
@@ -173,6 +251,12 @@ export function normalizeDispatchIntent(
 		.filter((key) => !RAW_FIELDS.has(key))
 		.sort(compareCodepoints);
 	if (unknown.length > 0) return fail("intent_malformed", `intent contains unknown field '${unknown[0]}'`);
+	if (raw.version !== undefined && raw.version !== 2) {
+		return fail(
+			"intent_version_unsupported",
+			`intent declares version ${JSON.stringify(raw.version)}; this build speaks dispatch intent version 2. A declaration at another version is refused rather than migrated: restate read_roots, write_roots, relevant_paths, expected_outputs, and verification under version 2`,
+		);
+	}
 	const readRoots = normalizePathList(raw.read_roots, "intent.read_roots");
 	if (!Array.isArray(readRoots)) return readRoots;
 	const writeRoots = normalizePathList(raw.write_roots, "intent.write_roots");

package/src/domains/dispatch/reservation-store.ts

@@ -9,14 +9,29 @@ import {
 	type CapacityStateFile,
 	capacityStateLockPath,
 	describeEndpointCapacityHolders,
+	endpointCapacityRemedy,
 	readCapacityStateUnsafe,
 	writeCapacityStateUnsafe,
 } from "./capacity-lease.js";
+import { COUNCIL_MIN_MEMBERS } from "./gate-role-prompts.js";
 
 const MAX_RESERVATION_RECORDS = 500;
 export const DEFAULT_RESERVATION_TTL_MS = 15 * 60_000;
 
-export type ReservationTopology = "parallel" | "detached" | "sequential" | "pipeline" | "review" | "compete";
+/**
+ * `council` is carried rather than flattened into `parallel` because it is the
+ * one topology with a floor on its own width. Every other plan can answer a
+ * capacity denial by dispatching fewer at once; a council of two cannot, and a
+ * denial that tells it to is advice it cannot take.
+ */
+export type ReservationTopology =
+	| "parallel"
+	| "detached"
+	| "sequential"
+	| "pipeline"
+	| "review"
+	| "compete"
+	| "council";
 export type ReservationMemberStatus = "held" | "consumed" | "released";
 export type ReservationStatus = "active" | "released" | "rolled_back" | "expired";
 
@@ -79,8 +94,10 @@ function endpointCapacityDenial(input: {
 	leases: number;
 	reservations: number;
 	foregroundStreams: number;
+	topology?: ReservationTopology;
 }): string {
-	return `dispatch: admission denied: endpoint '${endpointLabel(input.endpointKey)}' capacity exceeded (${input.used + input.requested}/${input.limit} slots): ${describeEndpointCapacityHolders(input)}; reduce the same-wave worker count, collect in-flight runs, or point workers at a second server`;
+	const remedy = endpointCapacityRemedy(input.topology === "council" ? { rosterFloor: COUNCIL_MIN_MEMBERS } : undefined);
+	return `dispatch: admission denied: endpoint '${endpointLabel(input.endpointKey)}' capacity exceeded (${input.used + input.requested}/${input.limit} slots): ${describeEndpointCapacityHolders(input)}; ${remedy}`;
 }
 
 function copyRecord(record: DispatchReservationRecord): DispatchReservationRecord {
@@ -100,7 +117,8 @@ function validRecord(value: unknown): value is DispatchReservationRecord {
 			record.topology === "sequential" ||
 			record.topology === "pipeline" ||
 			record.topology === "review" ||
-			record.topology === "compete") &&
+			record.topology === "compete" ||
+			record.topology === "council") &&
 		(record.status === "active" ||
 			record.status === "released" ||
 			record.status === "rolled_back" ||
@@ -191,6 +209,7 @@ function allocateReservation(
 	tasks: ReadonlyArray<ReservationPlanTask>,
 	existing: ReadonlyArray<DispatchReservationRecord>,
 	capacity: ReservationCapacitySnapshot,
+	topology?: ReservationTopology,
 ): ReservationPlanResult {
 	if (tasks.length === 0) return { ok: false, reason: "reservation requires at least one task" };
 	const duplicate = tasks.find((task, index) => tasks.slice(0, index).some((entry) => entry.memberId === task.memberId));
@@ -230,6 +249,7 @@ function allocateReservation(
 					leases: endpoint.leases ?? endpoint.active - (endpoint.foregroundStreams ?? 0),
 					reservations: heldSlots,
 					foregroundStreams: endpoint.foregroundStreams ?? 0,
+					...(topology === undefined ? {} : { topology }),
 				}),
 			};
 		}
@@ -264,7 +284,7 @@ export function createDispatchReservation(input: {
 				`dispatch: reservation denied: capacity is draining (requested by pid ${drain.requestedByPid} at ${drain.requestedAt})`,
 			);
 		}
-		const planned = allocateReservation(input.tasks, records, input.capacity);
+		const planned = allocateReservation(input.tasks, records, input.capacity, input.topology);
 		if (!planned.ok) {
 			replaceReservations(state, records);
 			writeCapacityStateUnsafe(state);

package/src/domains/dispatch/run-event-journal-bridge.ts

@@ -0,0 +1,149 @@
+/**
+ * Domain-owned writer for the run event journal.
+ *
+ * The journal was originally teed from `createDispatchRunEventRegistry`
+ * (src/tools/dispatch-run-events.ts), the display-tail helper behind the
+ * model-facing `dispatch` tool. That helper is not on the operator paths:
+ * `clio-coder run --agent` (src/cli/run.ts), `clio-coder fleet run`
+ * (src/cli/fleet.ts), and the TUI `/run` slash command each take a handle
+ * straight off `DispatchContract.dispatch` and iterate `handle.events`
+ * themselves, so no registry is ever built and the sink never fired. The
+ * writer had to move to something every dispatch reaches.
+ *
+ * `BusChannels.DispatchProgress` is that thing. The dispatch domain publishes
+ * it from inside the event pump for every consumer-visible event of every run,
+ * "attached, detached, batched, and retry runs, exactly once" (see
+ * src/core/bus-events.ts), whether or not anyone iterates the handle. The
+ * terminal pair `DispatchCompleted`/`DispatchFailed` closes every run the same
+ * way. Subscribing here makes the journal a property of dispatching, not of
+ * which caller happened to build a registry.
+ *
+ * Ownership is explicit rather than ambient: the bridge attaches only when a
+ * composition root asks for it (`DispatchBundleOptions.journalRunEvents`), and
+ * `registerAllTools` hands its registry `journal: null` in that same process.
+ * One writer per file, decided at one place, so a tool-path run in the TUI is
+ * not transcribed twice.
+ *
+ * Every write is best-effort. The sink degrades itself on I/O failure and a
+ * listener that throws is contained by the safe bus, so nothing here can fail a
+ * dispatch.
+ */
+
+import type {
+	DispatchCompletedPayload,
+	DispatchFailedPayload,
+	DispatchProgressPayload,
+} from "../../core/bus-events.js";
+import { BusChannels } from "../../core/bus-events.js";
+import type { SafeEventBus } from "../../core/event-bus.js";
+import { runTailEntryFromEvent } from "../../tools/dispatch-run-events.js";
+import { defaultRunEventJournal, type RunEventJournalSink } from "./run-event-journal.js";
+
+/**
+ * Runs whose `open` line this bridge has already written. Bounded so a
+ * long-lived orchestrator cannot grow it without limit; the journal writer
+ * keeps its own bound for the same reason. Evicting a run only forgets that it
+ * was opened, and a later event for it writes a second `open` line, which the
+ * reader and the writer both tolerate.
+ */
+const OPENED_RUN_LIMIT = 512;
+
+export interface RunEventJournalBridge {
+	/** Unsubscribe from the bus. Idempotent. */
+	stop(): void;
+}
+
+export interface AttachRunEventJournalBridgeOptions {
+	/** Sink override; defaults to the process-wide journal. */
+	journal?: RunEventJournalSink;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function runIdentity(payload: unknown): { runId: string; agentId: string } | null {
+	if (!isRecord(payload)) return null;
+	if (typeof payload.runId !== "string" || payload.runId.length === 0) return null;
+	return { runId: payload.runId, agentId: typeof payload.agentId === "string" ? payload.agentId : "unknown" };
+}
+
+/**
+ * Subscribe the journal to a dispatch bus. Returns a handle whose `stop()` the
+ * owning bundle calls on shutdown so a second bundle in the same process (tests
+ * do this) never inherits the first one's listeners.
+ */
+export function attachRunEventJournalBridge(
+	bus: SafeEventBus,
+	options: AttachRunEventJournalBridgeOptions = {},
+): RunEventJournalBridge {
+	const journal = options.journal ?? defaultRunEventJournal();
+	const opened = new Set<string>();
+
+	const ensureOpen = (runId: string, agentId: string): void => {
+		if (opened.has(runId)) return;
+		opened.add(runId);
+		while (opened.size > OPENED_RUN_LIMIT) {
+			const oldest = opened.values().next();
+			if (oldest.done === true) break;
+			opened.delete(oldest.value);
+		}
+		journal.open(runId, agentId);
+	};
+
+	/**
+	 * Write the receipt facts and close the run. Read defensively for the same
+	 * reason the registry's seal is: a terminal payload that is missing a field
+	 * it is typed to have must degrade the transcript, never throw back into the
+	 * finalizer that emitted it.
+	 */
+	const seal = (outcome: string, detail: string | null | undefined, payload: unknown): void => {
+		const identity = runIdentity(payload);
+		if (identity === null) return;
+		ensureOpen(identity.runId, identity.agentId);
+		const exitCode = isRecord(payload) && typeof payload.exitCode === "number" ? payload.exitCode : null;
+		journal.receipt(identity.runId, { outcome, exitCode });
+		journal.terminal(identity.runId, outcome, detail ?? undefined);
+		opened.delete(identity.runId);
+	};
+
+	const unsubscribes = [
+		bus.on(BusChannels.DispatchProgress, (payload: DispatchProgressPayload) => {
+			const identity = runIdentity(payload);
+			if (identity === null) return;
+			// The display projection decides what a transcript line is; a
+			// heartbeat or a streaming delta is not one. Opening the run only
+			// once an event survives that filter keeps a heartbeat-only run from
+			// creating an empty journal directory.
+			const entry = runTailEntryFromEvent(payload.event);
+			if (entry === null) return;
+			ensureOpen(identity.runId, identity.agentId);
+			// Route resolution warnings use `message`, while worker transcript
+			// events generally project their text through `detail`. Preserve the
+			// warning at this dispatch-owned durability seam so fleet view does not
+			// render a content-free `route_warning` line.
+			const message =
+				isRecord(payload.event) && typeof payload.event.message === "string" ? payload.event.message : undefined;
+			journal.append(
+				identity.runId,
+				entry.detail === undefined && message !== undefined ? { ...entry, detail: message } : entry,
+			);
+		}),
+		bus.on(BusChannels.DispatchCompleted, (payload: DispatchCompletedPayload) => {
+			seal(payload.outcome, payload.outcomeDetail, payload);
+		}),
+		bus.on(BusChannels.DispatchFailed, (payload: DispatchFailedPayload) => {
+			seal(payload.outcome, payload.outcomeDetail, payload);
+		}),
+	];
+
+	let stopped = false;
+	return {
+		stop(): void {
+			if (stopped) return;
+			stopped = true;
+			for (const unsubscribe of unsubscribes) unsubscribe();
+			opened.clear();
+		},
+	};
+}