@iowarp/clio-coder 0.3.9 → 0.4.1

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/joint-route-resolver.ts

@@ -76,7 +76,7 @@ export interface JointAgentDimension {
 }
 
 /** A single truthful role-quality label retires task-feature priors for this tuple. */
-export function routePriorForAgentEvidence(
+function routePriorForAgentEvidence(
 	agent: JointAgentDimension,
 	observations: ReadonlyArray<RouteObservation>,
 ): RoutePrior {

package/src/domains/dispatch/path-scope.ts

@@ -64,19 +64,6 @@ export interface DeclaredScopeReplacementNotice {
 	message: string;
 }
 
-export interface LegacyScopeInferenceNotice {
-	code: "legacy_scope_inferred" | "legacy_scope_empty";
-	level: "warning";
-	paths: ReadonlyArray<{
-		path: string;
-		policy: "working-context" | "write-boundary";
-		provenance: DispatchPathProvenanceKind;
-		source: DispatchPathProvenanceSource;
-		confidence: DispatchPathConfidence;
-	}>;
-	message: string;
-}
-
 export type DispatchPathScopeInferenceErrorCode = "legacy_scope_path_absolute" | "legacy_scope_path_malformed";
 
 export class DispatchPathScopeInferenceError extends Error {
@@ -320,51 +307,3 @@ export function declaredScopeReplacementNotice(scope: DispatchPathScope): Declar
 		)}. Those paths did not select project rules or expand worker authority.`,
 	};
 }
-
-function legacyNoticePaths(scope: DispatchPathScope): LegacyScopeInferenceNotice["paths"] {
-	const paths: Array<LegacyScopeInferenceNotice["paths"][number]> = [];
-	for (const [policy, entries] of [
-		["working-context", scope.provenance.workingContextPaths],
-		["write-boundary", scope.provenance.writeBoundaries],
-	] as const) {
-		for (const entry of entries) {
-			for (const evidence of entry.evidence) {
-				paths.push({
-					path: entry.path,
-					policy,
-					provenance: evidence.provenance,
-					source: evidence.source,
-					confidence: evidence.confidence,
-				});
-			}
-		}
-	}
-	return paths;
-}
-
-/** Render the operator-visible warning for a legacy scope resolution. */
-export function legacyScopeInferenceNotice(scope: DispatchPathScope): LegacyScopeInferenceNotice | null {
-	if (scope.source !== "inferred") return null;
-	const paths = legacyNoticePaths(scope);
-	if (paths.length === 0) {
-		return {
-			code: "legacy_scope_empty",
-			level: "warning",
-			paths,
-			message:
-				"[dispatch scope] legacy dispatch has no declared intent and inferred no policy-bearing paths. Path-scoped rules received no inferred match input, and worker authority did not expand.",
-		};
-	}
-	const rendered = paths
-		.map(
-			(entry) =>
-				`${entry.policy} ${entry.path} (provenance=${entry.provenance} source=${entry.source} confidence=${entry.confidence})`,
-		)
-		.join("; ");
-	return {
-		code: "legacy_scope_inferred",
-		level: "warning",
-		paths,
-		message: `[dispatch scope] legacy dispatch resolved policy-bearing scope without declared intent: ${rendered}. Review this scope before execution.`,
-	};
-}

package/src/domains/dispatch/placement.ts

@@ -61,9 +61,9 @@ function completedReroutes(
 
 function requestedNodeId(req: DispatchRequest, settings: Readonly<ClioSettings> | undefined): string | null {
 	if (req.node !== undefined && req.node.trim().length > 0) return req.node.trim();
-	const workers = settings?.workers;
+	const workers = settings?.fleet;
 	if (!workers) return null;
-	const profileName = req.workerProfile ?? workers.agentBindings?.[req.agentId];
+	const profileName = req.workerProfile ?? workers.agentProfiles?.[req.agentId];
 	if (!profileName) return null;
 	const pin = workers.profiles?.[profileName]?.node;
 	return pin !== undefined && pin.trim().length > 0 ? pin.trim() : null;

package/src/domains/dispatch/receipt-findings.ts

@@ -49,7 +49,7 @@ function canonicalJson(value: unknown): string {
 	throw new Error(`response schema digest cannot represent ${typeof value}`);
 }
 
-export function canonicalResponseSchemaDigest(schema: Record<string, unknown>): string {
+function canonicalResponseSchemaDigest(schema: Record<string, unknown>): string {
 	return createHash("sha256").update(canonicalJson(schema), "utf8").digest("hex");
 }
 

package/src/domains/dispatch/receipt-integrity.ts

@@ -123,7 +123,7 @@ export const RECEIPT_INTEGRITY_FIELD_COVERAGE = {
 	dynamicHash: true,
 	promptSignature: true,
 	toolSignature: true,
-	clioVersion: true,
+	clioCoderVersion: true,
 	piMonoVersion: true,
 	platform: true,
 	nodeVersion: true,
@@ -172,8 +172,14 @@ function selectedReceiptFields(
 	return result;
 }
 
-function receiptDigestFields(receipt: RunReceipt | RunReceiptDraft): Record<string, unknown> {
+function receiptDigestFields(receipt: RunReceipt | RunReceiptDraft, legacyNaming = false): Record<string, unknown> {
 	const result = selectedReceiptFields(receipt, RECEIPT_FIELDS);
+	if (legacyNaming) {
+		const source = receipt as unknown as Record<string, unknown>;
+		const version = source.clioVersion ?? source.clioCoderVersion;
+		delete result.clioCoderVersion;
+		if (version !== undefined) result.clioVersion = version;
+	}
 	result.briefing = receipt.briefing ?? null;
 	result.outcomeCode = receipt.outcomeCode ?? null;
 	result.steering = receipt.steering ?? null;
@@ -227,24 +233,29 @@ function ledgerDigestFields(envelope: RunEnvelope): Record<string, unknown> {
 	};
 }
 
-function integrityPayload(receipt: RunReceipt | RunReceiptDraft, envelope: RunEnvelope): Record<string, unknown> {
+function integrityPayload(
+	receipt: RunReceipt | RunReceiptDraft,
+	envelope: RunEnvelope,
+	legacyNaming = false,
+): Record<string, unknown> {
 	return {
-		contract: "clio.runReceipt.integrity",
+		contract: legacyNaming ? "clio.runReceipt.integrity" : "clio-coder.runReceipt.integrity",
 		version: RUN_RECEIPT_INTEGRITY_VERSION,
 		sources: ["receipt", "run-ledger"],
-		receipt: receiptDigestFields(receipt),
+		receipt: receiptDigestFields(receipt, legacyNaming),
 		ledger: ledgerDigestFields(envelope),
 	};
 }
 
-export function computeReceiptIntegrity(
+function computeReceiptIntegrity(
 	receipt: RunReceipt | RunReceiptDraft,
 	envelope: RunEnvelope,
+	legacyNaming = false,
 ): RunReceiptIntegrity {
 	return {
 		version: RUN_RECEIPT_INTEGRITY_VERSION,
 		algorithm: RUN_RECEIPT_INTEGRITY_ALGORITHM,
-		digest: sha256(canonicalJson(integrityPayload(receipt, envelope))),
+		digest: sha256(canonicalJson(integrityPayload(receipt, envelope, legacyNaming))),
 	};
 }
 
@@ -385,7 +396,8 @@ export function verifyReceiptIntegrity(receipt: RunReceipt, envelope: RunEnvelop
 		return { ok: false, reason: `ledger mismatch: ${mismatch}` };
 	}
 	const expected = computeReceiptIntegrity(receipt, envelope);
-	if (expected.digest !== receipt.integrity.digest) {
+	const legacyExpected = computeReceiptIntegrity(receipt, envelope, true);
+	if (expected.digest !== receipt.integrity.digest && legacyExpected.digest !== receipt.integrity.digest) {
 		return { ok: false, reason: "integrity mismatch" };
 	}
 	return { ok: true };

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);
@@ -579,31 +599,8 @@ export function getDispatchReservation(ownerId: string): DispatchReservationReco
 	return record ? copyRecord(record) : null;
 }
 
-export function listDispatchReservations(): ReadonlyArray<DispatchReservationRecord> {
-	return readStore();
-}
-
 export function reservedBudgetUsd(): number {
 	return readStore()
 		.filter((record) => record.status === "active")
 		.reduce((sum, record) => sum + outstandingBudget(record), 0);
 }
-
-export function reservedCapacity(): {
-	globalSlots: number;
-	nodeSlots: Readonly<Record<string, number>>;
-	endpointSlots: Readonly<Record<string, number>>;
-} {
-	let globalSlots = 0;
-	const nodeSlots: Record<string, number> = {};
-	const endpointSlots: Record<string, number> = {};
-	for (const record of readStore().filter((entry) => entry.status === "active")) {
-		const allocation = reservationAllocation(outstandingTasks(record));
-		globalSlots += allocation.globalSlots;
-		for (const [nodeId, count] of Object.entries(allocation.nodeSlots))
-			nodeSlots[nodeId] = (nodeSlots[nodeId] ?? 0) + count;
-		for (const [endpointKey, count] of Object.entries(allocation.endpointSlots))
-			endpointSlots[endpointKey] = (endpointSlots[endpointKey] ?? 0) + count;
-	}
-	return { globalSlots, nodeSlots, endpointSlots };
-}

package/src/domains/dispatch/route-decision.ts

@@ -597,7 +597,7 @@ function readinessHashProjection(report: RouteReadinessReport): readonly [boolea
  * `decisionDurationMs`, which is a measurement of the decision rather than an
  * input to it, so a replay on a faster machine still reproduces the hash.
  */
-export function routeDecisionHash(input: RouteDecisionInput): string {
+function routeDecisionHash(input: RouteDecisionInput): string {
 	// Arrays give every field an explicit position, so native JSON serialization
 	// is deterministic without recursively sorting hundreds of short-lived
 	// objects at the maximum universe bound. Candidate identity uses the same

package/src/domains/dispatch/route-history.ts

@@ -137,7 +137,7 @@ function retireHistory(path: string, version: unknown): void {
 	const retired = `${path}.v${String(version)}.${stamp}.retired`;
 	renameSync(path, retired);
 	process.stderr.write(
-		`[clio:dispatch] route history v${String(version)} is retired; starting empty at v${ROUTE_HISTORY_VERSION}. Prior observations: ${retired}\n`,
+		`[clio-coder:dispatch] route history v${String(version)} is retired; starting empty at v${ROUTE_HISTORY_VERSION}. Prior observations: ${retired}\n`,
 	);
 }
 

package/src/domains/dispatch/route-policy.ts

@@ -146,7 +146,7 @@ function rate(values: ReadonlyArray<boolean>, fallback = 0): number {
 }
 
 /** Conservative 95% Wilson lower confidence bound for a Bernoulli success rate. */
-export function wilsonLowerBound(successes: number, observations: number, z = 1.96): number {
+function wilsonLowerBound(successes: number, observations: number, z = 1.96): number {
 	if (observations <= 0) return 0;
 	const proportion = successes / observations;
 	const z2 = z * z;

package/src/domains/dispatch/route-readiness.ts

@@ -90,31 +90,3 @@ export function evaluateRouteReadiness(input: RouteReadinessInput): RouteReadine
 		labelsNeeded: Math.max(0, MINIMUM_ACTIVE_QUALITY_LABELS - estimate.qualityLabeledCount),
 	};
 }
-
-/**
- * Human-readable one-liners for a refusal message. The wording names the
- * missing evidence, so an operator who sees an active refusal can tell whether
- * to wait for measurements or to fix a stale fact.
- */
-export function describeReadinessGap(gap: ReadinessGap): string {
-	switch (gap) {
-		case "hard-constraint-validity-below-one":
-			return "hard-constraint evaluation was not consistently valid over the retained window";
-		case "integrity-failures-in-window":
-			return "the retained window contains receipt or source integrity failures";
-		case "insufficient-quality-labels":
-			return `fewer than ${MINIMUM_ACTIVE_QUALITY_LABELS} quality-labeled outcomes for this route and role`;
-		case "quality-lower-bound-below-posture-floor":
-			return "the conservative quality lower bound is below the posture floor";
-		case "quality-lower-bound-below-requested-minimum":
-			return "the conservative quality lower bound is below the request's minimumQuality";
-		case "reliability-below-posture-floor":
-			return "route-attributable reliability is below the posture floor";
-		case "cost-upper-bound-unknown":
-			return "the route has no conservative cost upper bound";
-		case "route-facts-stale":
-			return "node, endpoint, resource, capacity, or settings facts are stale";
-		case "decision-latency-above-budget":
-			return `shadow decision p95 exceeds ${DECISION_LATENCY_BUDGET_MS} ms at the configured universe bound`;
-	}
-}

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();
+		},
+	};
+}