@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/dispatch/extension.ts

@@ -10,8 +10,9 @@
  */
 
 import { createHash, randomBytes } from "node:crypto";
-import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
+import { type Dirent, readdirSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve as resolvePath, sep } from "node:path";
+import { performance } from "node:perf_hooks";
 import { BusChannels, type DispatchCompletedPayload, type DispatchRunIdentity } from "../../core/bus-events.js";
 import { DEFAULT_SETTINGS, type DelegationToolGovernance } from "../../core/defaults.js";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
@@ -57,6 +58,7 @@ import {
 import type { AgentsContract } from "../agents/contract.js";
 import type { AgentRecipe } from "../agents/recipe.js";
 import { validateRecipeResult } from "../agents/result-contract.js";
+import { nodeResultContractFilesystem } from "../agents/result-contract-filesystem.js";
 import {
 	type AgentAudience,
 	type AgentCapabilityClass,
@@ -76,12 +78,16 @@ import { type EffectivePricing, resolveEffectivePricing } from "../providers/cat
 import {
 	type CapabilityFlags,
 	canonicalizeWireModelId,
+	type EndpointCapacity,
+	endpointCapacityFor,
+	endpointCapacityForStatus,
 	firstRuntimeResolutionError,
 	isDispatchEligibleRuntime,
 	type ProvidersContract,
 	type ResolvedRuntimeTarget,
 	type RuntimeApiFamily,
 	type RuntimeDescriptor,
+	resolveEndpointCapacities,
 	resolveModelCapabilities,
 	resolveRuntimeTarget,
 	runtimeResolutionWarnings,
@@ -108,6 +114,7 @@ import {
 	routeValidationProjection,
 } from "./active-route-planner.js";
 import { admit, createCapacityAdmissionController, createLeaseSlotGuard } from "./admission.js";
+import { AdmissionCanceledError } from "./admission-error.js";
 import { agentRouteCandidates } from "./agent-candidates.js";
 import { AGENT_LEDGER_PROMPT_MAX_CHARS, renderAgentLedger } from "./agent-ledger.js";
 import { publishAgentLedgerEntry, subscribeAgentLedger } from "./agent-ledger-hub.js";
@@ -166,7 +173,14 @@ import {
 } from "./failure-classification.js";
 import { routeFactVerdict } from "./fleet-preflight.js";
 import { competeStanceLiner, isBoundedGateRolePrompt } from "./gate-role-prompts.js";
-import { classifyHeartbeat, DEFAULT_HEARTBEAT_SPEC, type HeartbeatSpec, type HeartbeatStatus } from "./heartbeat.js";
+import {
+	classifyHeartbeat,
+	DEFAULT_HEARTBEAT_SPEC,
+	type HeartbeatSpec,
+	type HeartbeatStamp,
+	type HeartbeatStatus,
+	heartbeatMonotonicAt,
+} from "./heartbeat.js";
 import { hostVerificationRejection, runHostVerification } from "./host-verification.js";
 import { renderDispatchIntentRequirements } from "./intent-requirements.js";
 import { adaptJointRouteInput } from "./joint-route-adapter.js";
@@ -205,6 +219,7 @@ import {
 	planQueueSlot,
 	type ReservationCapacitySnapshot,
 	rebindDispatchReservationMember,
+	releaseDispatchReservation,
 	releaseDispatchReservationMember,
 	reservedBudgetUsd,
 	reservedPlanPeakSlots,
@@ -224,6 +239,7 @@ import {
 import { createRouteObserver, type RouteObservationHandle, type RouteObserver } from "./route-observer.js";
 import { reduceRouteQuality } from "./route-quality.js";
 import { defaultRoutingIntent } from "./routing-intent.js";
+import { attachRunEventJournalBridge, type RunEventJournalBridge } from "./run-event-journal-bridge.js";
 import { detectRunIdentity } from "./run-identity.js";
 import { type Ledger, newRunId, openLedger } from "./state.js";
 import {
@@ -286,6 +302,7 @@ import {
 	type SpawnOptions as WorkerSpawnOptions,
 	type WorkerSpec,
 } from "./worker-spawn.js";
+import type { WriteBoundaryAttribution, WriteBoundaryAttributionDowngrade } from "./write-boundary.js";
 
 interface RunTokenMeter {
 	inputTokens: number;
@@ -337,7 +354,7 @@ interface ActiveRun {
 	/** ACP event-inactivity window; null for native runs (heartbeat spec governs those). */
 	stallTimeoutMs: number | null;
 	lineage: RunLineage;
-	heartbeatAt: { current: number } | null;
+	heartbeatAt: HeartbeatStamp | null;
 	heartbeatStatus: HeartbeatStatus;
 	meter: RunTokenMeter;
 	pricing: EffectivePricing["rates"];
@@ -345,6 +362,12 @@ interface ActiveRun {
 	finalPromise: Promise<RunReceipt>;
 }
 
+interface PendingCapacityAdmission {
+	identity: DispatchRunIdentity & { requestOrigin: DispatchRequestOrigin };
+	timing: RunPhaseMarks;
+	node: RunNodeIdentity | null;
+}
+
 interface DispatchFinishContractSnapshot {
 	assessment: FinishContractAssessment;
 	rigor: Rigor;
@@ -373,6 +396,8 @@ export interface DispatchBundleOptions {
 	heartbeatIntervalMs?: number;
 	resilienceCooldownMs?: number;
 	now?: () => number;
+	/** Monotonic clock for heartbeat age and ACP event-inactivity spans. */
+	monotonicNow?: () => number;
 	/** Immutable per-attempt session settings view; falls back to the shared snapshot. */
 	getSettings?: () => EffectiveSettings;
 	/** Live hard-block state cloned into each mediated worker spec. */
@@ -383,6 +408,15 @@ export interface DispatchBundleOptions {
 	collectReproducibility?: typeof collectReproducibilityMetadata;
 	/** Observer injection seam. Production constructs the durable observer. */
 	routeObserver?: RouteObserver;
+	/**
+	 * Write the durable run event journal for every run this bundle dispatches.
+	 * Off by default and turned on by the three composition roots
+	 * (src/entry/orchestrator.ts, src/cli/run.ts, src/cli/fleet.ts), because the
+	 * process that owns a bundle also decides who owns the journal file: a
+	 * composed process routes `registerAllTools`' event registry to
+	 * `journal: null` so a tool-path run is transcribed once, not twice.
+	 */
+	journalRunEvents?: boolean;
 }
 
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 1000;
@@ -2397,18 +2431,20 @@ export function createDispatchBundle(
 		return DEFAULT_RESILIENCE_COOLDOWN_MS;
 	};
 	const now = options?.now ?? (() => Date.now());
+	const monotonicNow = options?.monotonicNow ?? (() => performance.now());
 	// Durable evidence owner used by shadow observation and active readiness.
 	const routeObserver: RouteObserver = options?.routeObserver ?? createRouteObserver({});
 
 	let ledger: Ledger | null = null;
 	let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
 	const active = new Map<string, ActiveRun>();
+	const pendingCapacity = new Map<string, PendingCapacityAdmission>();
 	const targetCooldowns = new Map<string, { until: number; reason: string }>();
 	const ownedReservations = new Set<string>();
 	/**
-	 * Paths each finalized run's own tool calls aimed a successful mutation at,
-	 * newest last. `null` records a run whose write record is unusable, which is
-	 * a different answer from an empty list and has to survive as one.
+	 * Attribution from each finalized run's successful tool calls, newest last.
+	 * An incomplete record retains its paths as a lower bound beside the reasons
+	 * it cannot be read as a closed list.
 	 *
 	 * Held in memory rather than sealed into the receipt: the only reader is the
 	 * write boundary closing a window seconds later in this process, and a
@@ -2416,13 +2452,13 @@ export function createDispatchBundle(
 	 * Bounded because a long session finalizes many runs and none of this is
 	 * needed once its window has closed.
 	 */
-	const runWriteTargets = new Map<string, ReadonlyArray<string> | null>();
-	const recordRunWriteTargets = (runId: string, paths: ReadonlyArray<string> | null): void => {
-		runWriteTargets.set(runId, paths);
-		while (runWriteTargets.size > RUN_WRITE_TARGET_HISTORY) {
-			const oldest = runWriteTargets.keys().next();
+	const runWriteAttributions = new Map<string, WriteBoundaryAttribution>();
+	const recordRunWriteAttribution = (runId: string, attribution: WriteBoundaryAttribution): void => {
+		runWriteAttributions.set(runId, attribution);
+		while (runWriteAttributions.size > RUN_WRITE_TARGET_HISTORY) {
+			const oldest = runWriteAttributions.keys().next();
 			if (oldest.done === true) break;
-			runWriteTargets.delete(oldest.value);
+			runWriteAttributions.delete(oldest.value);
 		}
 	};
 	const capacityAdmission = createCapacityAdmissionController({
@@ -2430,7 +2466,7 @@ export function createDispatchBundle(
 			const settings = getEffectiveSettings();
 			const nodes: Record<string, number> = { local: configuredGlobalCapacity(settings) };
 			for (const node of settings?.fleet?.nodes ?? []) nodes[node.id] = node.maxWorkers;
-			return { global: configuredGlobalCapacity(settings), nodes };
+			return { global: configuredGlobalCapacity(settings), nodes, endpoints: configuredEndpointLimits() };
 		},
 		now,
 		reservedPlanPeak: (planId) =>
@@ -2443,6 +2479,39 @@ export function createDispatchBundle(
 		}),
 	);
 
+	/**
+	 * Every endpoint the configured fleet can reach.
+	 *
+	 * Deliberately resolved from the configured targets as well as the probed
+	 * statuses. A target whose status has not been built yet contributed no key,
+	 * an absent key carries no limit, and reservation planning skips a dimension
+	 * it has no limit for, so admission against a single-slot server used to fail
+	 * open for whoever asked first after boot.
+	 */
+	function configuredEndpointCapacities(): Readonly<Record<string, EndpointCapacity>> {
+		return resolveEndpointCapacities({
+			statuses: providers.list(),
+			targets: getEffectiveSettings()?.targets ?? [],
+			runtimeFor: (runtimeId) => providers.getRuntime(runtimeId),
+		});
+	}
+
+	function configuredEndpointLimits(): Readonly<Record<string, number>> {
+		return Object.fromEntries(Object.entries(configuredEndpointCapacities()).map(([key, value]) => [key, value.limit]));
+	}
+
+	function endpointCapacityForTarget(targetId: string): EndpointCapacity | null {
+		const status = providers.list().find((entry) => entry.target.id === targetId);
+		const target = status?.target ?? providers.getTarget(targetId);
+		if (target === null || target === undefined) return null;
+		const endpoint =
+			status === undefined
+				? endpointCapacityFor({ target, runtime: providers.getRuntime(target.runtime) })
+				: endpointCapacityForStatus(status);
+		if (endpoint === null) return null;
+		return configuredEndpointCapacities()[endpoint.key] ?? endpoint;
+	}
+
 	function reservationCapacitySnapshot(settings: EffectiveSettings): ReservationCapacitySnapshot {
 		const preflight = scheduling.preflight();
 		// Reservation planning compares against a fresh read, never the display cache.
@@ -2452,9 +2521,21 @@ export function createDispatchBundle(
 		};
 		for (const node of settings?.fleet?.nodes ?? [])
 			nodes[node.id] = { active: usage.nodes[node.id] ?? 0, limit: node.maxWorkers };
+		const endpoints = Object.fromEntries(
+			Object.entries(configuredEndpointLimits()).map(([key, limit]) => [
+				key,
+				{
+					active: usage.endpoints[key] ?? 0,
+					limit,
+					leases: usage.endpointHolders[key]?.leases ?? 0,
+					foregroundStreams: usage.endpointHolders[key]?.foregroundStreams ?? 0,
+				},
+			]),
+		);
 		return {
 			global: { active: usage.global, limit: configuredGlobalCapacity(settings) },
 			nodes,
+			endpoints,
 			budget: { currentUsd: preflight.currentUsd, ceilingUsd: preflight.ceilingUsd },
 		};
 	}
@@ -2466,6 +2547,7 @@ export function createDispatchBundle(
 				memberId: task.memberId,
 				wave: task.wave,
 				nodeId: task.resolution.node.id,
+				...(task.resolution.endpoint !== undefined ? { endpointKey: task.resolution.endpoint.key } : {}),
 				costUpperBoundUsd: task.resolution.routeApproval?.totalCostUpperBoundUsd ?? task.resolution.costUpperBoundUsd,
 			})),
 			capacity: reservationCapacitySnapshot(getEffectiveSettings()),
@@ -2520,10 +2602,44 @@ export function createDispatchBundle(
 		return scheduling.maxWorkers?.() ?? (configured === "auto" || configured === undefined ? 4 : Math.max(1, configured));
 	}
 
-	async function admitAssignmentCapacity(req: DispatchRequest, nodeId: string, timing: RunPhaseMarks) {
+	function publishCapacityQueued(
+		identity: DispatchRunIdentity & { requestOrigin: DispatchRequestOrigin },
+		timing: RunPhaseMarks,
+		node: RunNodeIdentity | null,
+	): void {
+		pendingCapacity.set(identity.runId, { identity, timing, node });
+		context.bus.emit(BusChannels.DispatchEnqueued, identity);
+	}
+
+	function publishCapacityAdmissionFailure(
+		identity: DispatchRunIdentity & { requestOrigin: DispatchRequestOrigin },
+		error: unknown,
+	): void {
+		const detail = error instanceof Error ? error.message : String(error);
+		const outcome: RunOutcome =
+			error instanceof AdmissionCanceledError
+				? "canceled"
+				: /admission timed out/u.test(detail)
+					? "timed_out"
+					: "denied_by_policy";
+		context.bus.emit(BusChannels.DispatchFailed, {
+			...identity,
+			outcome,
+			outcomeDetail: detail,
+			reason: outcome,
+		});
+	}
+
+	async function admitAssignmentCapacity(
+		req: DispatchRequest,
+		nodeId: string,
+		timing: RunPhaseMarks,
+		endpoint?: EndpointCapacity | null,
+	) {
 		const queuedAt = now();
 		timing.queuedAt = new Date(queuedAt).toISOString();
-		const assignmentId = req.lineage?.rootRunId ?? `pending-${queuedAt.toString(36)}-${randomBytes(6).toString("hex")}`;
+		const assignmentId =
+			req.lineage?.rootRunId ?? req.runIdHint ?? `pending-${queuedAt.toString(36)}-${randomBytes(6).toString("hex")}`;
 		const requestedAt = Date.parse(timing.requestedAt ?? timing.queuedAt);
 		const deadlineAt = req.assignmentDeadlineAt ?? requestedAt + (req.routingIntent?.deadlineMs ?? 60_000);
 		if (req.lineage === undefined) await registerAssignment(assignmentId);
@@ -2538,9 +2654,16 @@ export function createDispatchBundle(
 			const admitted = await capacityAdmission.admit({
 				assignmentId,
 				nodeId,
+				...(endpoint !== null && endpoint !== undefined ? { endpointKey: endpoint.key } : {}),
 				deadlineAt,
 				...plan,
-				...(req.reservation !== undefined && req.lineage === undefined ? { reservation: req.reservation } : {}),
+				// A fleet's first attempt carries lineage and still owns the held
+				// reservation member that admission must transfer into its lease.
+				// Retries carry the same reservation identity after that member was
+				// consumed, so they reacquire/rebind the assignment lease normally.
+				...(req.reservation !== undefined && (req.lineage === undefined || req.lineage.attempt === 0)
+					? { reservation: req.reservation }
+					: {}),
 			});
 			timing.admittedAt = new Date(admitted.admittedAt).toISOString();
 			return admitted.lease;
@@ -2557,6 +2680,7 @@ export function createDispatchBundle(
 	function rebindReservationSlot(
 		req: DispatchRequest,
 		nodeId: string,
+		endpoint: EndpointCapacity | null,
 		costUsd: number,
 		settings: EffectiveSettings,
 	): void {
@@ -2565,6 +2689,7 @@ export function createDispatchBundle(
 		const rebind = {
 			...req.reservation,
 			nodeId,
+			...(endpoint !== null ? { endpointKey: endpoint.key } : {}),
 			costUpperBoundUsd: req.routeApproval?.totalCostUpperBoundUsd ?? costUsd,
 			capacity,
 			nowMs: now(),
@@ -2672,6 +2797,21 @@ export function createDispatchBundle(
 
 	type RetryScheduleResult = { scheduled: true } | { scheduled: false; settlementDetail?: string };
 
+	/** A reserved plan member owns its retry chain independently of the shared fleet root assignment. */
+	function retryChainIsLive(run: ActiveRun): boolean {
+		if (run.aborted) return false;
+		const reservation = run.req.reservation;
+		if (reservation === undefined) return assignments.get(run.lineage.rootRunId)?.status === "running";
+		try {
+			const record = getDispatchReservation(reservation.ownerId);
+			const member = record?.members.find((entry) => entry.memberId === reservation.memberId);
+			return record?.status === "active" && member !== undefined && member.status !== "released";
+		} catch (error) {
+			reportDispatchDiagnostic(`read retry liveness for reservation member ${reservation.memberId}`, error);
+			return false;
+		}
+	}
+
 	function maybeScheduleRetry(
 		run: ActiveRun,
 		outcome: RunOutcome,
@@ -2681,7 +2821,7 @@ export function createDispatchBundle(
 	): RetryScheduleResult {
 		if (draining) return { scheduled: false };
 		const rootRunId = run.lineage.rootRunId;
-		if (assignments.get(rootRunId)?.status !== "running") return { scheduled: false };
+		if (!retryChainIsLive(run)) return { scheduled: false };
 		if (!RETRYABLE_OUTCOMES.has(outcome)) {
 			retryBackoff.delete(rootRunId);
 			return { scheduled: false };
@@ -2828,7 +2968,7 @@ export function createDispatchBundle(
 		reason = "retry",
 		decision: RetryDecision = decideRetry("internal", run.lineage.attempt, assignmentPolicyFor(run.req).maxRetries),
 	): Promise<void> {
-		if (draining || assignments.get(run.lineage.rootRunId)?.status !== "running") return;
+		if (draining || !retryChainIsLive(run)) return;
 		const excludesNode = decision.excludedRouteParts.includes("node");
 		// Record the failed node so placement can choose an eligible survivor.
 		const rerouteHops =
@@ -2846,6 +2986,10 @@ export function createDispatchBundle(
 				depth: run.lineage.depth,
 			},
 		};
+		// A run-id hint names only the first attempt (and, for task worktrees,
+		// the worktree it created). A retry shares the assignment lineage but
+		// must receive its own ledger/run identity.
+		delete retryReq.runIdHint;
 		const reasonKey = retryReasonKey(run.lineage.rootRunId, attempt);
 		retryReasons.set(reasonKey, reason);
 		try {
@@ -3010,8 +3154,8 @@ export function createDispatchBundle(
 		}
 	}
 
-	function heartbeatIso(heartbeatMs: number): string {
-		return new Date(heartbeatMs).toISOString();
+	function heartbeatIso(heartbeat: HeartbeatStamp): string {
+		return new Date(heartbeat.current).toISOString();
 	}
 
 	function heartbeatRunStatus(status: HeartbeatStatus): RunStatus {
@@ -3032,7 +3176,7 @@ export function createDispatchBundle(
 			event: {
 				type: "heartbeat_status",
 				status,
-				heartbeatAt: run.heartbeatAt ? heartbeatIso(run.heartbeatAt.current) : null,
+				heartbeatAt: run.heartbeatAt ? heartbeatIso(run.heartbeatAt) : null,
 			},
 		});
 	}
@@ -3050,16 +3194,16 @@ export function createDispatchBundle(
 	 */
 	function checkActiveHeartbeats(): void {
 		if (!ledger) return;
-		const tickNow = now();
+		const tickMonotonic = monotonicNow();
 		for (const run of active.values()) {
 			if (run.aborted || run.stallKilled || !run.heartbeatAt) continue;
-			const heartbeatMs = run.heartbeatAt.current;
-			if (!Number.isFinite(heartbeatMs)) continue;
+			const heartbeatMonotonic = heartbeatMonotonicAt(run.heartbeatAt);
+			if (!Number.isFinite(heartbeatMonotonic) || !Number.isFinite(run.heartbeatAt.current)) continue;
 			if (run.runtimeKind === "acp-delegation") {
-				ledger.update(run.runId, { heartbeatAt: heartbeatIso(heartbeatMs) });
+				ledger.update(run.runId, { heartbeatAt: heartbeatIso(run.heartbeatAt) });
 				const stallMs = run.stallTimeoutMs;
 				if (stallMs === null || stallMs <= 0) continue;
-				if (tickNow - heartbeatMs <= stallMs) continue;
+				if (tickMonotonic - heartbeatMonotonic <= stallMs) continue;
 				run.stallKilled = true;
 				run.heartbeatStatus = "dead";
 				emitHeartbeatStatus(run, "dead");
@@ -3070,10 +3214,10 @@ export function createDispatchBundle(
 				}
 				continue;
 			}
-			const status = classifyHeartbeat(heartbeatMs, tickNow, heartbeatSpec);
+			const status = classifyHeartbeat(heartbeatMonotonic, tickMonotonic, heartbeatSpec);
 			const patch: Partial<RunEnvelope> = {
 				status: heartbeatRunStatus(status),
-				heartbeatAt: heartbeatIso(heartbeatMs),
+				heartbeatAt: heartbeatIso(run.heartbeatAt),
 			};
 			ledger.update(run.runId, patch);
 			// Node staleness display feeds off the freshest worker heartbeat.
@@ -3493,7 +3637,29 @@ export function createDispatchBundle(
 
 		assertBudgetAdmitsRoute(req, { rates: null, provenance: "unknown" }, settings);
 
-		const capacityLease = await admitAssignmentCapacity(req, "local", timing);
+		const queuedIdentity =
+			req.lineage === undefined && req.runIdHint !== undefined
+				? {
+						runId: req.runIdHint,
+						agentId: req.agentId,
+						task: req.task,
+						requestOrigin: lifecycle.requestOrigin,
+						targetId,
+						wireModelId,
+						runtimeId,
+						runtimeKind: "acp-delegation" as const,
+					}
+				: null;
+		if (queuedIdentity !== null) publishCapacityQueued(queuedIdentity, timing, null);
+		let capacityLease: Awaited<ReturnType<typeof admitAssignmentCapacity>>;
+		try {
+			capacityLease = await admitAssignmentCapacity(req, "local", timing, null);
+		} catch (error) {
+			if (queuedIdentity !== null) publishCapacityAdmissionFailure(queuedIdentity, error);
+			throw error;
+		} finally {
+			if (queuedIdentity !== null) pendingCapacity.delete(queuedIdentity.runId);
+		}
 		const leaseSlot = createLeaseSlotGuard(capacityAdmission, capacityLease.leaseId, req.lineage !== undefined);
 
 		// Resolve the ledger before starting the ACP process: an external agent
@@ -3519,6 +3685,8 @@ export function createDispatchBundle(
 				safety,
 				autonomy: lifecycle.autonomy,
 				clientVersion: readClioVersion(),
+				now,
+				monotonicNow,
 			});
 		} catch (error) {
 			leaseSlot.release();
@@ -3699,15 +3867,17 @@ export function createDispatchBundle(
 			runIdForPermissionAudit = envelope.id;
 			lineage = lineageFor(req, envelope.id);
 			if (req.lineage === undefined) {
-				capacityAdmission.rename(capacityLease.leaseId, lineage.rootRunId);
-				await renameStoredAssignment(capacityLease.assignmentId, lineage.rootRunId);
+				if (capacityLease.assignmentId !== lineage.rootRunId) {
+					capacityAdmission.rename(capacityLease.leaseId, lineage.rootRunId);
+					await renameStoredAssignment(capacityLease.assignmentId, lineage.rootRunId);
+				}
 				leaseSlot.transferToAssignment();
 			}
 			identity = detectRunIdentity();
 			ledgerRef.update(envelope.id, {
 				status: "running",
 				pid: acp.pid,
-				heartbeatAt: heartbeatIso(acp.heartbeatAt.current),
+				heartbeatAt: heartbeatIso(acp.heartbeatAt),
 				lineage,
 				identity,
 				node: LOCAL_RUN_NODE,
@@ -3726,16 +3896,18 @@ export function createDispatchBundle(
 			// One durable write at start so sibling processes (clio-coder fleet status)
 			// can observe the running row; finalization persists the terminal state.
 			await ledgerRef.persist();
-			context.bus.emit(BusChannels.DispatchEnqueued, {
-				runId: envelope.id,
-				agentId: req.agentId,
-				task: req.task,
-				requestOrigin: lifecycle.requestOrigin,
-				targetId,
-				wireModelId,
-				runtimeId,
-				runtimeKind: "acp-delegation",
-			});
+			if (req.lineage !== undefined) {
+				context.bus.emit(BusChannels.DispatchEnqueued, {
+					runId: envelope.id,
+					agentId: req.agentId,
+					task: req.task,
+					requestOrigin: lifecycle.requestOrigin,
+					targetId,
+					wireModelId,
+					runtimeId,
+					runtimeKind: "acp-delegation",
+				});
+			}
 			context.bus.emit(BusChannels.DispatchStarted, {
 				runId: envelope.id,
 				agentId: req.agentId,
@@ -4104,7 +4276,7 @@ export function createDispatchBundle(
 					cacheReadTokenCount: receiptDraft.cacheReadTokenCount ?? 0,
 					cacheWriteTokenCount: receiptDraft.cacheWriteTokenCount ?? 0,
 					reasoningTokenCount: receiptDraft.reasoningTokenCount ?? 0,
-					heartbeatAt: heartbeatIso(acp.heartbeatAt.current),
+					heartbeatAt: heartbeatIso(acp.heartbeatAt),
 				};
 				ledgerRef.update(envelope.id, ledgerPatch);
 				const receipt = ledgerRef.recordReceipt(envelope.id, sealRouteDecision(receiptDraft, routeDecision));
@@ -4193,6 +4365,10 @@ export function createDispatchBundle(
 			throw new Error(`dispatch: invalid spec: ${validated.errors.join("; ")}`);
 		}
 		req = validation.restore(validated.spec);
+		// A top-level run needs its stable identity before it can wait for
+		// capacity. The board can then render the assignment as queued and the
+		// same id becomes the ledger row once its slot opens.
+		if (req.lineage === undefined && req.runIdHint === undefined) req = { ...req, runIdHint: newRunId() };
 		let activeRouteObservation: RouteObservationHandle | null = null;
 		if (req.delegationAgentId === undefined) {
 			const recipe = agents.get(req.agentId);
@@ -4262,7 +4438,7 @@ export function createDispatchBundle(
 					"dispatch: writeRoots cannot be enforced on an ACP delegation target; the external agent runs its own tool surface. Dispatch to a native or claude-sdk worker.",
 				);
 			}
-			rebindReservationSlot(req, "local", UNKNOWN_PRICING_ADMISSION_ESTIMATE_USD, settings);
+			rebindReservationSlot(req, "local", null, UNKNOWN_PRICING_ADMISSION_ESTIMATE_USD, settings);
 			routeObservation = observeShadowRoute(req, undefined, settings);
 			return attachRouteObservation({
 				...(await dispatchAcpDelegation(req, settings, timing, routeObservation.decision, observer)),
@@ -4296,10 +4472,12 @@ export function createDispatchBundle(
 			model: lifecycle.target.wireModelId,
 			node: placement?.node?.id ?? "local",
 		};
+		const endpoint = endpointCapacityForTarget(lifecycle.target.target.id);
 		assertRouteWithinApprovedEnvelope(req, effectiveRoute);
 		rebindReservationSlot(
 			req,
 			effectiveRoute.node,
+			endpoint,
 			conservativeRouteAdmissionEstimateUsd(lifecycle.target.effectivePricing, admissionMaxOutputTokens(settings)),
 			settings,
 		);
@@ -4318,7 +4496,41 @@ export function createDispatchBundle(
 			shadow: () => observeShadowRoute(req, placed, settings),
 		});
 
-		const capacityLease = await admitAssignmentCapacity(req, placement?.node.id ?? "local", timing);
+		const queuedIdentity =
+			req.lineage === undefined && req.runIdHint !== undefined
+				? {
+						runId: req.runIdHint,
+						agentId: req.agentId,
+						task: req.task,
+						agentAudience: lifecycle.agentAudience,
+						requestOrigin: lifecycle.requestOrigin,
+						targetId: lifecycle.target.target.id,
+						wireModelId: lifecycle.target.wireModelId,
+						runtimeId: lifecycle.target.runtime.id,
+						runtimeKind: lifecycle.runtimeKind,
+						budget: lifecycle.budgetEnvelope,
+						...(endpoint !== null ? { endpoint: { key: endpoint.key, label: endpoint.label, limit: endpoint.limit } } : {}),
+						...(placement !== null ? { node: placement.node.id } : {}),
+						...(req.gate !== undefined ? { gate: { role: req.gate.role, cycle: req.gate.cycle } } : {}),
+						...(req.council !== undefined ? { council: req.council } : {}),
+						...(req.reroutes !== undefined && req.reroutes.length > 0 ? { rerouteCount: req.reroutes.length } : {}),
+						...(lifecycle.target.modelCapabilities !== undefined &&
+						lifecycle.target.modelCapabilities !== null &&
+						lifecycle.target.modelCapabilities.contextWindow > 0
+							? { contextWindow: lifecycle.target.modelCapabilities.contextWindow }
+							: {}),
+					}
+				: null;
+		if (queuedIdentity !== null) publishCapacityQueued(queuedIdentity, timing, placement?.node ?? null);
+		let capacityLease: Awaited<ReturnType<typeof admitAssignmentCapacity>>;
+		try {
+			capacityLease = await admitAssignmentCapacity(req, placement?.node.id ?? "local", timing, endpoint);
+		} catch (error) {
+			if (queuedIdentity !== null) publishCapacityAdmissionFailure(queuedIdentity, error);
+			throw error;
+		} finally {
+			if (queuedIdentity !== null) pendingCapacity.delete(queuedIdentity.runId);
+		}
 		const leaseSlot = createLeaseSlotGuard(capacityAdmission, capacityLease.leaseId, req.lineage !== undefined);
 
 		const ledgerRef = (() => {
@@ -4387,6 +4599,8 @@ export function createDispatchBundle(
 		try {
 			worker = (placement?.spawn ?? spawnWorker)(spec, {
 				cwd: lifecycle.cwd,
+				now,
+				monotonicNow,
 				...(agentLedgerId !== null ? { onLedgerPost } : {}),
 			});
 		} catch (error) {
@@ -4443,10 +4657,21 @@ export function createDispatchBundle(
 		const upstreamResponses: RunReceiptUpstreamResponse[] = [];
 		const skillActivations: SkillActivation[] = [];
 		const finishContractEntries: unknown[] = [];
+		let runIdForPermissionAudit: string | null = null;
 		// The worker's own tool calls, folded into what this run changed and what
 		// it validated. The sealed mutation-report contract is measured against
 		// this, so a reported path the run never touched cannot seal as fact.
-		const runEffects = createRunEffectsRecorder(lifecycle.cwd);
+		const runEffects = createRunEffectsRecorder(lifecycle.cwd, {
+			onWriteRecordDowngraded(downgrade) {
+				const runId = runIdForPermissionAudit;
+				if (runId === null) return;
+				context.bus.emit(BusChannels.DispatchProgress, {
+					runId,
+					agentId: req.agentId,
+					event: { type: "clio_write_record_downgraded", payload: downgrade },
+				});
+			},
+		});
 		let finishContractAssistantText = "";
 		let finishContractAssistantTurnId: string | null = null;
 		let failureMessage: string | undefined;
@@ -4456,7 +4681,6 @@ export function createDispatchBundle(
 		const acceptsOutcomeCodeEvents =
 			lifecycle.runtimeKind === "http" ||
 			(lifecycle.runtimeKind === "sdk" && lifecycle.target.runtime.id === "claude-sdk");
-		let runIdForPermissionAudit: string | null = null;
 		let workerPolicyPermissionCounter = 0;
 		const outputCapture = createWorkerOutputCapture();
 		const markObservedPhase = (field: "firstModelTokenAt" | "firstToolAt"): void => {
@@ -4575,6 +4799,7 @@ export function createDispatchBundle(
 					...(ruleId !== null ? { ruleId } : {}),
 					...(policySource !== null ? { policySource } : {}),
 					...(typeof event.payload.timeoutMs === "number" ? { timeoutMs: event.payload.timeoutMs } : {}),
+					fallback: spec.escalation?.fallback ?? "deny",
 					escalation: true,
 				});
 			}
@@ -4649,6 +4874,7 @@ export function createDispatchBundle(
 					decidedBy,
 					actionClass,
 					reason,
+					...(source === "timeout" ? { fallback: spec.escalation?.fallback ?? "deny" } : {}),
 					...(runIdForPermissionAudit !== null ? { requestedBy: runIdForPermissionAudit } : {}),
 				});
 			}
@@ -4704,8 +4930,10 @@ export function createDispatchBundle(
 			runIdForPermissionAudit = envelope.id;
 			lineage = lineageFor(req, envelope.id);
 			if (req.lineage === undefined) {
-				capacityAdmission.rename(capacityLease.leaseId, lineage.rootRunId);
-				await renameStoredAssignment(capacityLease.assignmentId, lineage.rootRunId);
+				if (capacityLease.assignmentId !== lineage.rootRunId) {
+					capacityAdmission.rename(capacityLease.leaseId, lineage.rootRunId);
+					await renameStoredAssignment(capacityLease.assignmentId, lineage.rootRunId);
+				}
 				leaseSlot.transferToAssignment();
 			}
 			if (agentLedgerId !== null) {
@@ -4739,7 +4967,7 @@ export function createDispatchBundle(
 				...(req.council !== undefined ? { council: req.council } : {}),
 				...(req.plan !== undefined ? { plan: req.plan } : {}),
 				...(lifecycle.personaOverride ? { personaOverride: lifecycle.personaOverride } : {}),
-				...(heartbeatAt ? { heartbeatAt: heartbeatIso(heartbeatAt.current) } : {}),
+				...(heartbeatAt ? { heartbeatAt: heartbeatIso(heartbeatAt) } : {}),
 			});
 			observer?.onAdmitted({
 				runId: envelope.id,
@@ -4755,6 +4983,7 @@ export function createDispatchBundle(
 			// per-worker meter. All optional so consumers degrade to local/plain.
 			const fleetIdentity = {
 				budget: lifecycle.budgetEnvelope,
+				...(endpoint !== null ? { endpoint: { key: endpoint.key, label: endpoint.label, limit: endpoint.limit } } : {}),
 				...(placement !== undefined && placement !== null ? { node: placement.node.id } : {}),
 				...(req.gate !== undefined ? { gate: { role: req.gate.role, cycle: req.gate.cycle } } : {}),
 				...(req.council !== undefined ? { council: req.council } : {}),
@@ -4765,18 +4994,20 @@ export function createDispatchBundle(
 					? { contextWindow: lifecycle.target.modelCapabilities.contextWindow }
 					: {}),
 			};
-			context.bus.emit(BusChannels.DispatchEnqueued, {
-				runId: envelope.id,
-				agentId: req.agentId,
-				task: req.task,
-				agentAudience: lifecycle.agentAudience,
-				requestOrigin: lifecycle.requestOrigin,
-				targetId: lifecycle.target.target.id,
-				wireModelId: lifecycle.target.wireModelId,
-				runtimeId: lifecycle.target.runtime.id,
-				runtimeKind: lifecycle.runtimeKind,
-				...fleetIdentity,
-			});
+			if (req.lineage !== undefined) {
+				context.bus.emit(BusChannels.DispatchEnqueued, {
+					runId: envelope.id,
+					agentId: req.agentId,
+					task: req.task,
+					agentAudience: lifecycle.agentAudience,
+					requestOrigin: lifecycle.requestOrigin,
+					targetId: lifecycle.target.target.id,
+					wireModelId: lifecycle.target.wireModelId,
+					runtimeId: lifecycle.target.runtime.id,
+					runtimeKind: lifecycle.runtimeKind,
+					...fleetIdentity,
+				});
+			}
 			context.bus.emit(BusChannels.DispatchStarted, {
 				runId: envelope.id,
 				agentId: req.agentId,
@@ -5205,18 +5436,7 @@ export function createDispatchBundle(
 					cwd: lifecycle.cwd,
 					networkAllowed: lifecycle.admission.allowedTools.includes(ToolNames.WebFetch),
 					observedRunEffects,
-					filesystem: {
-						readFile(filePath) {
-							try {
-								return readFileSync(filePath, "utf8");
-							} catch {
-								return null;
-							}
-						},
-						pathExists(filePath) {
-							return existsSync(filePath);
-						},
-					},
+					filesystem: nodeResultContractFilesystem(),
 				});
 				const resultValidation = resultContract?.applicable === true ? resultContract.validation : null;
 				if (finalOutcome === "succeeded" && resultValidation?.conformance === "fail") {
@@ -5331,7 +5551,7 @@ export function createDispatchBundle(
 					...(receiptDraft.cacheWriteTokenCount !== undefined
 						? { cacheWriteTokenCount: receiptDraft.cacheWriteTokenCount }
 						: {}),
-					...(activeRun.heartbeatAt ? { heartbeatAt: heartbeatIso(activeRun.heartbeatAt.current) } : {}),
+					...(activeRun.heartbeatAt ? { heartbeatAt: heartbeatIso(activeRun.heartbeatAt) } : {}),
 				};
 				if (receiptDraft.reasoningTokenCount !== undefined) {
 					ledgerPatch.reasoningTokenCount = receiptDraft.reasoningTokenCount;
@@ -5354,9 +5574,28 @@ export function createDispatchBundle(
 				// the set. That run's window keeps today's blame-the-whole-diff
 				// behaviour; a run that never touched such a tool keeps the
 				// protection.
-				const writeRecordUsable =
-					receipt.safety?.toolTelemetry?.coverage === "complete" && observedRunEffects.writeRecordComplete;
-				recordRunWriteTargets(envelope.id, writeRecordUsable ? [...observedRunEffects.mutatedPaths] : null);
+				const toolTelemetryComplete = receipt.safety?.toolTelemetry?.coverage === "complete";
+				const downgrades: WriteBoundaryAttributionDowngrade[] = observedRunEffects.writeRecordDowngrades.map((entry) => ({
+					reason: entry.reason,
+					tool: entry.tool,
+					toolCallId: entry.toolCallId,
+					runId: envelope.id,
+					stepId: null,
+				}));
+				if (!toolTelemetryComplete) {
+					downgrades.push({
+						reason: "incomplete_tool_telemetry",
+						tool: null,
+						toolCallId: null,
+						runId: envelope.id,
+						stepId: null,
+					});
+				}
+				recordRunWriteAttribution(envelope.id, {
+					recorded: [...observedRunEffects.mutatedPaths],
+					complete: toolTelemetryComplete && observedRunEffects.writeRecordComplete,
+					downgrades,
+				});
 				await ledgerRef.persist();
 				if (worktreeReceipt?.applied === true && req.taskWorktree !== undefined) {
 					try {
@@ -5628,12 +5867,14 @@ export function createDispatchBundle(
 			allowedTools: effectiveTools,
 			settings,
 		});
+		const endpoint = endpointCapacityForTarget(target.target.id);
 		return {
 			agentId: req.agentId,
 			specFingerprint: agentSpecFingerprint(agentSpec),
 			targetId: target.target.id,
 			wireModelId: target.wireModelId,
 			runtimeId: target.runtime.id,
+			...(endpoint !== null ? { endpoint: { key: endpoint.key, label: endpoint.label, limit: endpoint.limit } } : {}),
 			node: previewNode(req).node,
 			thinkingLevel: target.thinkingLevel,
 			toolSignature: toolSignature(effectiveTools),
@@ -6043,8 +6284,15 @@ export function createDispatchBundle(
 		return receipt;
 	}
 
+	let journalBridge: RunEventJournalBridge | null = null;
+
 	const extension: DomainExtension = {
 		async start() {
+			// The journal subscribes before anything can dispatch. It rides the
+			// domain's own progress and terminal channels, so it covers a run
+			// whose caller iterates the handle itself (every operator path) as
+			// well as one drained by the dispatch tool's event registry.
+			if (options?.journalRunEvents === true) journalBridge = attachRunEventJournalBridge(context.bus);
 			// No in-memory executor survives a process restart, so every active
 			// side-store lease from an earlier bundle is orphaned and must expire.
 			cleanupDispatchReservations({ startup: true, nowMs: now() });
@@ -6110,6 +6358,10 @@ export function createDispatchBundle(
 			for (const ownerId of ownedReservations) rollbackDispatchReservation(ownerId, now());
 			ownedReservations.clear();
 			await Promise.allSettled([...assignmentWrites]);
+			// After drain(), so the last run's terminal line is written before the
+			// bridge stops listening.
+			journalBridge?.stop();
+			journalBridge = null;
 		},
 	};
 
@@ -6133,19 +6385,41 @@ export function createDispatchBundle(
 	 */
 	function snapshot(): DispatchSnapshot {
 		const tickNow = now();
+		const tickMonotonic = monotonicNow();
 		const running: DispatchSnapshot["running"] = [];
 		const totals = { ...finalizedTotals };
 		const costAmounts = [...finalizedCosts];
+		for (const pending of pendingCapacity.values()) {
+			const startedAt = pending.timing.queuedAt ?? pending.timing.requestedAt ?? new Date(tickNow).toISOString();
+			running.push({
+				runId: pending.identity.runId,
+				agentId: pending.identity.agentId,
+				...(pending.identity.task !== undefined ? { task: pending.identity.task } : {}),
+				...(pending.identity.budget !== undefined ? { budget: pending.identity.budget } : {}),
+				runtimeKind: pending.identity.runtimeKind,
+				outcomePhase: "queued",
+				heartbeat: "n/a",
+				lineage: { parentRunId: null, rootRunId: pending.identity.runId, attempt: 0, depth: 0 },
+				startedAt,
+				elapsedMs: 0,
+				timing: deriveRunPhaseDurations(pending.timing, startedAt, new Date(tickNow).toISOString()),
+				tokens: { input: 0, output: 0, total: 0 },
+				costUsd: 0,
+				costProvenance: "unknown",
+				node: pending.node === null ? null : { ...pending.node },
+			});
+		}
 		for (const run of active.values()) {
 			let heartbeat: "alive" | "stale" | "dead" | "n/a" = "n/a";
-			if (run.heartbeatAt && Number.isFinite(run.heartbeatAt.current)) {
+			if (run.heartbeatAt && Number.isFinite(heartbeatMonotonicAt(run.heartbeatAt))) {
+				const heartbeatMonotonic = heartbeatMonotonicAt(run.heartbeatAt);
 				if (run.runtimeKind === "acp-delegation") {
 					const stallMs = run.stallTimeoutMs;
 					if (stallMs !== null && stallMs > 0) {
-						heartbeat = tickNow - run.heartbeatAt.current > stallMs ? "dead" : "alive";
+						heartbeat = tickMonotonic - heartbeatMonotonic > stallMs ? "dead" : "alive";
 					}
 				} else {
-					heartbeat = classifyHeartbeat(run.heartbeatAt.current, tickNow, heartbeatSpec);
+					heartbeat = classifyHeartbeat(heartbeatMonotonic, tickMonotonic, heartbeatSpec);
 				}
 			}
 			const meter = run.meter;
@@ -6271,6 +6545,7 @@ export function createDispatchBundle(
 		routeCandidates,
 		reservations: {
 			prepare: prepareReservation,
+			release: (ownerId) => releaseDispatchReservation(ownerId, now()),
 			rollback: (ownerId) => rollbackDispatchReservation(ownerId, now()),
 			rollbackUnconsumed: (ownerId) => rollbackUnconsumedDispatchReservation(ownerId, now()),
 			get: getDispatchReservation,
@@ -6291,7 +6566,17 @@ export function createDispatchBundle(
 		observedRunWrites(runId) {
 			// A run this process never finalized, or finalized long enough ago to
 			// have been evicted, is unknown rather than silent, so both answer null.
-			return runWriteTargets.get(runId) ?? null;
+			const attribution = runWriteAttributions.get(runId);
+			return attribution?.complete === true ? [...attribution.recorded] : null;
+		},
+		observedRunWriteAttribution(runId) {
+			const attribution = runWriteAttributions.get(runId);
+			if (attribution === undefined) return null;
+			return {
+				recorded: [...attribution.recorded],
+				complete: attribution.complete,
+				downgrades: attribution.downgrades?.map((entry) => ({ ...entry })) ?? [],
+			};
 		},
 		assignments: {
 			get: (id) => assignments.get(id),
@@ -6302,6 +6587,17 @@ export function createDispatchBundle(
 		},
 		abort(runId, reason) {
 			const rootRunId = assignmentRootFor(runId);
+			const queued = pendingCapacity.get(rootRunId);
+			if (queued !== undefined && capacityAdmission.cancel(rootRunId)) {
+				persistAssignment(cancelStoredAssignment(rootRunId), `${rootRunId}:cancel-queued`);
+				context.bus.emit(BusChannels.RunAborted, {
+					source: "dispatch_abort",
+					runId: rootRunId,
+					startedAt: null,
+					elapsedMs: null,
+					reason: reason?.detail ?? "operator abort while waiting for an endpoint slot",
+				});
+			}
 			const assignment = assignments.get(rootRunId);
 			if (assignment?.status === "running") {
 				assignments.cancel(assignment.id);