@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/domains/dispatch/extension.ts

@@ -10,7 +10,7 @@
  */
 
 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";
@@ -58,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,
@@ -78,7 +79,7 @@ import {
 	type CapabilityFlags,
 	canonicalizeWireModelId,
 	type EndpointCapacity,
-	endpointCapacitiesForStatuses,
+	endpointCapacityFor,
 	endpointCapacityForStatus,
 	firstRuntimeResolutionError,
 	isDispatchEligibleRuntime,
@@ -86,6 +87,7 @@ import {
 	type ResolvedRuntimeTarget,
 	type RuntimeApiFamily,
 	type RuntimeDescriptor,
+	resolveEndpointCapacities,
 	resolveModelCapabilities,
 	resolveRuntimeTarget,
 	runtimeResolutionWarnings,
@@ -112,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";
@@ -236,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 {
@@ -358,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;
@@ -398,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;
@@ -437,8 +456,8 @@ function calculateUsageCostUsd(meter: RunTokenMeter, pricing: EffectivePricing["
  * admit a route before settings are resolved, and it defers to the one place
  * that owns the default rather than restating the number here.
  */
-export function admissionMaxOutputTokens(settings: EffectiveSettings): number {
-	return settings?.defaults.maxTokens ?? DEFAULT_SETTINGS.defaults.maxTokens;
+function admissionMaxOutputTokens(settings: EffectiveSettings): number {
+	return settings?.chat.maxOutputTokens ?? DEFAULT_SETTINGS.chat.maxOutputTokens;
 }
 
 function conservativeRouteAdmissionEstimateUsd(pricing: EffectivePricing, maxOutputTokens: number): number {
@@ -490,7 +509,7 @@ function eventContainsFirstModelToken(event: Record<string, unknown>): boolean {
 }
 
 function eventStartsTool(event: Record<string, unknown>): boolean {
-	return event.type === "tool_execution_start" || event.type === "clio_tool_start";
+	return event.type === "tool_execution_start" || event.type === "clio_coder_tool_start";
 }
 
 function finitePositive(value: unknown): number | undefined {
@@ -667,7 +686,7 @@ async function awaitEventDrain(drained: Promise<void>, graceMs = DISPATCH_DRAIN_
 function reportDispatchDiagnostic(scope: string, error: unknown): void {
 	const message = error instanceof Error ? error.message : String(error);
 	try {
-		process.stderr.write(`[clio:dispatch] ${scope}: ${message}\n`);
+		process.stderr.write(`[clio-coder:dispatch] ${scope}: ${message}\n`);
 	} catch {
 		// stderr itself is best-effort
 	}
@@ -873,7 +892,7 @@ export interface WorkspaceRootFacts {
  * claimed `npm test` then "validated" in 4ms. None of that is a model failure.
  * The harness knows the cwd exactly and was sending it nowhere.
  */
-export function readWorkspaceRootFacts(
+function readWorkspaceRootFacts(
 	cwd: string,
 	readEntries: (dir: string) => Dirent[] = readDirentsSafely,
 ): WorkspaceRootFacts {
@@ -903,7 +922,7 @@ function readDirentsSafely(dir: string): Dirent[] {
  * projection of CLIO-CODER.md: a read-only scout that cannot afford the handbook read
  * still needs its first shell call to land in the right place.
  */
-export function renderWorkerWorkspaceContext(workspace: WorkspaceRootFacts): string {
+function renderWorkerWorkspaceContext(workspace: WorkspaceRootFacts): string {
 	const lines = ["# Workspace", `Root: ${workspace.root}`, "Your process starts here; relative paths resolve from it."];
 	if (workspace.entries.length > 0) {
 		lines.push(`Top level: ${workspace.entries.join(", ")}${workspace.truncated ? ", …" : ""}`);
@@ -956,7 +975,7 @@ function renderPipelineInput(input: PipelineInput): PipelineInputRender {
  * the command actually printed rather than a summary of it. Like pipeline
  * input, this is data and is never presented as instructions.
  */
-export function renderPredecessorHandoffs(handoffs: ReadonlyArray<ExecutionHandoff>): WorkerPromptMessage | null {
+function renderPredecessorHandoffs(handoffs: ReadonlyArray<ExecutionHandoff>): WorkerPromptMessage | null {
 	if (handoffs.length === 0) return null;
 	const body = [
 		"Outputs from this step's declared predecessors, in dependency order.",
@@ -1086,7 +1105,7 @@ export interface WorkerDynamicContext {
  * the projected "Verification expectations" body (verification-class runs
  * only); when off, output is byte-identical to the historical renderer.
  */
-export function renderWorkerProjectContext(
+function renderWorkerProjectContext(
 	project: ProjectStructuredContext,
 	options: { includeVerification?: boolean } = {},
 ): string {
@@ -1128,7 +1147,7 @@ function workerProjectContextIncludesVerification(body: string): boolean {
 	return body.includes("\nVerification expectations:\n");
 }
 
-export function buildDynamicPromptMessages(
+function buildDynamicPromptMessages(
 	req: DispatchRequest,
 	dynamicContext: WorkerDynamicContext = {},
 ): WorkerPromptMessage[] {
@@ -1336,7 +1355,7 @@ interface DispatchLifecycleStage {
 interface AcpDelegationLifecycleStage {
 	admission: DispatchAdmissionStage;
 	pathScope: DispatchPathScope;
-	agentConfig: ReturnType<ConfigContract["get"]>["delegation"]["agents"][number];
+	agentConfig: ReturnType<ConfigContract["get"]>["integrations"]["externalAgents"]["entries"][number];
 	cwd: string;
 	systemPrompt: string;
 	dynamicPromptMessages: ReadonlyArray<WorkerPromptMessage>;
@@ -1588,7 +1607,7 @@ function workerToolCallHardCap(settings: EffectiveSettings): number {
 	const parsedEnvCap = rawEnvCap && /^[1-9]\d*$/.test(rawEnvCap) ? Number(rawEnvCap) : Number.NaN;
 	return Number.isSafeInteger(parsedEnvCap)
 		? parsedEnvCap
-		: (settings?.guardrails.workerToolCallCap ?? GUARDRAIL_DEFAULTS.workerToolCallCap);
+		: (settings?.fleet.limits.toolCallsPerRun ?? GUARDRAIL_DEFAULTS.workerToolCallCap);
 }
 
 function resolveEffectiveWorkerBudget(input: {
@@ -1716,15 +1735,15 @@ function acpRuntimeLimitations(): string[] {
 }
 
 function readWorkerTargets(settings: ReturnType<ConfigContract["get"]> | undefined): WorkerTargets {
-	const workerDefault = settings?.workers?.default
+	const workerDefault = settings?.fleet?.default
 		? {
-				target: settings.workers.default.target ?? null,
-				model: settings.workers.default.model ?? null,
-				thinkingLevel: (settings.workers.default.thinkingLevel ?? "off") as ThinkingLevel,
+				target: settings.fleet.default.target ?? null,
+				model: settings.fleet.default.model ?? null,
+				thinkingLevel: (settings.fleet.default.thinkingLevel ?? "off") as ThinkingLevel,
 			}
 		: null;
 	const workerProfiles: WorkerProfileMap = {};
-	for (const [name, profile] of Object.entries(settings?.workers?.profiles ?? {})) {
+	for (const [name, profile] of Object.entries(settings?.fleet?.profiles ?? {})) {
 		workerProfiles[name] = {
 			target: profile.target ?? null,
 			model: profile.model ?? null,
@@ -1732,7 +1751,7 @@ function readWorkerTargets(settings: ReturnType<ConfigContract["get"]> | undefin
 		};
 	}
 	const agentBindings: WorkerAgentBindingMap = {};
-	for (const [agentId, profileName] of Object.entries(settings?.workers?.agentBindings ?? {})) {
+	for (const [agentId, profileName] of Object.entries(settings?.fleet?.agentProfiles ?? {})) {
 		const id = agentId.trim();
 		const profile = profileName.trim();
 		if (id.length > 0 && profile.length > 0) agentBindings[id] = profile;
@@ -1909,17 +1928,17 @@ function buildDispatchWorkerSpec(input: DispatchWorkerSpecInput, config?: Config
 	if (input.req.trustProjectCompatRoots !== undefined) {
 		spec.trustProjectCompatRoots = input.req.trustProjectCompatRoots;
 	} else if (settings) {
-		spec.trustProjectCompatRoots = settings.skills.trustProjectCompatRoots === true;
+		spec.trustProjectCompatRoots = settings.integrations.projectResources.trustProjectImports === true;
 	}
-	spec.gitCommitAttribution = settings?.attribution.gitCommits ?? true;
+	spec.gitCommitAttribution = settings?.integrations.git.commitAttribution ?? true;
 	// Non-stall posture (Symphony §10.5): a dispatched worker has no operator
 	// to answer a permission prompt by default, so the resolution policy ships
 	// with the spec and the worker enforces it within bounded time. Under the
 	// escalate posture the configured timeout/fallback bounds ride along so the
 	// worker still cannot hang when no operator resolves the ask.
-	spec.onPermission = settings?.workers.onPermission ?? "deny";
+	spec.onPermission = settings?.fleet.permissions.mode ?? "deny";
 	if (spec.onPermission === "escalate") {
-		const escalation = settings?.workers.escalation;
+		const escalation = settings?.fleet.permissions.escalation;
 		if (escalation) spec.escalation = { timeoutMs: escalation.timeoutMs, fallback: escalation.fallback };
 	}
 	assertRuntimeCanHonorWorkerPermissionMode(input.target.runtime, spec.onPermission);
@@ -2013,7 +2032,7 @@ function autonomyEnforcementForAcpDelegation(
 			dangerousBypass: true,
 		};
 	}
-	// clio-policy applies the exact autonomy mapping to every permission
+	// clio-coder-policy applies the exact autonomy mapping to every permission
 	// request. deny-all is stricter than every autonomy level, but is still a
 	// Clio-mediated upper bound rather than an external approximation.
 	return { grade: "mediated", autonomy, ...authorityEvidence, externalMode: toolGovernance };
@@ -2407,7 +2426,7 @@ export function createDispatchBundle(
 	const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
 	const getResilienceCooldownMs = (): number => {
 		if (options?.resilienceCooldownMs !== undefined) return options.resilienceCooldownMs;
-		const settingsVal = getEffectiveSettings()?.workers?.resilienceCooldownMs;
+		const settingsVal = getEffectiveSettings()?.fleet?.retry.routeCooldownMs;
 		if (settingsVal !== undefined && settingsVal >= 0) return settingsVal;
 		return DEFAULT_RESILIENCE_COOLDOWN_MS;
 	};
@@ -2419,6 +2438,7 @@ export function createDispatchBundle(
 	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>();
 	/**
@@ -2459,19 +2479,37 @@ 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(endpointCapacitiesForStatuses(providers.list())).map(([key, value]) => [key, value.limit]),
-		);
+		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);
-		if (status === undefined) return null;
-		const endpoint = endpointCapacityForStatus(status);
+		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;
-		const configured = endpointCapacitiesForStatuses(providers.list())[endpoint.key];
-		return configured ?? endpoint;
+		return configuredEndpointCapacities()[endpoint.key] ?? endpoint;
 	}
 
 	function reservationCapacitySnapshot(settings: EffectiveSettings): ReservationCapacitySnapshot {
@@ -2560,10 +2598,38 @@ export function createDispatchBundle(
 	}
 
 	function configuredGlobalCapacity(settings: EffectiveSettings): number {
-		const configured = settings?.budget.concurrency;
+		const configured = settings?.fleet.concurrency;
 		return scheduling.maxWorkers?.() ?? (configured === "auto" || configured === undefined ? 4 : Math.max(1, configured));
 	}
 
+	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,
@@ -2572,7 +2638,8 @@ export function createDispatchBundle(
 	) {
 		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);
@@ -2657,7 +2724,7 @@ export function createDispatchBundle(
 	const finalizedCosts: Array<{ usd: number; provenance: import("../providers/index.js").CostProvenance }> = [];
 
 	function workersMaxRetries(settings: EffectiveSettings = getEffectiveSettings()): number {
-		const value = settings?.workers?.maxRetries;
+		const value = settings?.fleet?.retry.maxRetries;
 		return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 2;
 	}
 
@@ -2919,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 {
@@ -3347,11 +3418,11 @@ export function createDispatchBundle(
 			providers,
 		);
 		enforceCapabilityGate(target.target.id, target.modelCapabilities, req.requiredCapabilities);
-		assertRuntimeCanHonorWorkerPermissionMode(target.runtime, settings?.workers.onPermission ?? "deny");
+		assertRuntimeCanHonorWorkerPermissionMode(target.runtime, settings?.fleet.permissions.mode ?? "deny");
 		assertWorkerBudgetEnforceable(target.runtime, spec.budget !== null || req.budget !== undefined);
 
 		const cwd = req.cwd ?? process.cwd();
-		const sessionAutonomy = settings?.autonomy ?? "auto-edit";
+		const sessionAutonomy = settings?.safety.autonomy ?? "auto-edit";
 		const effectiveAutonomy = clampWorkerAutonomy(sessionAutonomy, req.autonomy);
 		const effectiveTools = withLedgerToolNarrowing(
 			effectiveToolNames(admission.allowedTools, target, pathScope.writeBoundaries.length > 0, deniedToolNames(req)),
@@ -3374,7 +3445,7 @@ export function createDispatchBundle(
 				recipe.skills !== undefined &&
 				recipe.skills.length > 0 &&
 				req.noSkills !== true,
-			onPermission: settings?.workers.onPermission ?? "deny",
+			onPermission: settings?.fleet.permissions.mode ?? "deny",
 			persona: {
 				id: `persona.${recipe.id}`,
 				relPath: recipe.filepath,
@@ -3402,7 +3473,7 @@ export function createDispatchBundle(
 			capabilityClass: spec.capabilityClass,
 			projectContextTier: tier,
 			autonomy: effectiveAutonomy,
-			onPermission: settings?.workers.onPermission ?? "deny",
+			onPermission: settings?.fleet.permissions.mode ?? "deny",
 			project,
 			workspace: readWorkspaceRootFacts(cwd),
 		});
@@ -3422,7 +3493,7 @@ export function createDispatchBundle(
 		// Match chat-loop's LOCAL_API_KEY_FALLBACK so dispatch-spawned workers can
 		// reach openai-compat local endpoints (LM Studio, llama.cpp) without
 		// requiring the user to invent a credential.
-		const apiKey = auth?.apiKey ?? (auth === null ? "clio-local-target" : undefined);
+		const apiKey = auth?.apiKey ?? (auth === null ? "clio-coder-local-target" : undefined);
 		const runtimeKind: RunKind = target.runtime.kind;
 		const limitations = runtimeLimitations(runtimeKind, target.runtime.id);
 		return {
@@ -3477,16 +3548,16 @@ export function createDispatchBundle(
 			}
 		}
 		if (!settings) throw new Error("dispatch: effective settings required for ACP delegation");
-		const configured = settings.delegation.agents.find((entry) => entry.id === agentId);
+		const configured = settings.integrations.externalAgents.entries.find((entry) => entry.id === agentId);
 		if (!configured) throw new Error(`dispatch: ACP delegation agent '${agentId}' not configured`);
-		const toolGovernance = configured.toolGovernance ?? "clio-policy";
+		const toolGovernance = configured.toolGovernance ?? "clio-coder-policy";
 		if (options?.autonomyOverride === true && toolGovernance === "agent-managed") {
 			throw new Error(
-				`dispatch: ACP delegation agent '${agentId}' uses toolGovernance='agent-managed', which cannot enforce an explicit one-run autonomy override; choose clio-policy or deny-all governance, or omit --autonomy`,
+				`dispatch: ACP delegation agent '${agentId}' uses toolGovernance='agent-managed', which cannot enforce an explicit one-run autonomy override; choose clio-coder-policy or deny-all governance, or omit --autonomy`,
 			);
 		}
 		const admission = resolveDelegationAdmissionStage(req, safety);
-		const sessionAutonomy = settings.autonomy ?? "auto-edit";
+		const sessionAutonomy = settings.safety.autonomy ?? "auto-edit";
 		const autonomy = clampWorkerAutonomy(sessionAutonomy, req.autonomy);
 		if (toolGovernance === "agent-managed" && autonomy !== sessionAutonomy) {
 			throw new Error(
@@ -3566,7 +3637,29 @@ export function createDispatchBundle(
 
 		assertBudgetAdmitsRoute(req, { rates: null, provenance: "unknown" }, settings);
 
-		const capacityLease = await admitAssignmentCapacity(req, "local", timing, null);
+		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
@@ -3662,15 +3755,15 @@ export function createDispatchBundle(
 				if (eventContainsFirstModelToken(event)) markObservedPhase("firstModelTokenAt");
 				if (eventStartsTool(event)) markObservedPhase("firstToolAt");
 			}
-			if (event.type === "clio_tool_start" && event.payload && typeof event.payload.tool === "string") {
+			if (event.type === "clio_coder_tool_start" && event.payload && typeof event.payload.tool === "string") {
 				recordToolStart(inFlightTools, event.payload);
 			}
 			// ACP is an external protocol peer, never an authority for Clio's
 			// deterministic terminal taxonomy. Ignore even syntactically valid
 			// assertions; only a future coordinator-side classifier may set one.
-			if (event.type === "clio_run_outcome" && !reportedSpoofedOutcome) {
+			if (event.type === "clio_coder_run_outcome" && !reportedSpoofedOutcome) {
 				reportedSpoofedOutcome = true;
-				reportDispatchDiagnostic("ACP outcome event", new Error("ignored untrusted clio_run_outcome assertion"));
+				reportDispatchDiagnostic("ACP outcome event", new Error("ignored untrusted clio_coder_run_outcome assertion"));
 			}
 			if (isRecord(event)) {
 				const finishEntry = appendDispatchFinishContractEntry(finishContractEntries, event);
@@ -3701,7 +3794,7 @@ export function createDispatchBundle(
 					if (message !== null) failureMessage = message;
 				}
 			}
-			if (event.type === "clio_permission_resolved" && event.payload && typeof event.payload.tool === "string") {
+			if (event.type === "clio_coder_permission_resolved" && event.payload && typeof event.payload.tool === "string") {
 				const requestId =
 					typeof event.payload.requestId === "string" ? event.payload.requestId : `delegation-permission-${Date.now()}`;
 				const origin = runIdForPermissionAudit !== null ? `delegation:${runIdForPermissionAudit}` : "delegation:unknown";
@@ -3727,7 +3820,7 @@ export function createDispatchBundle(
 					...(runIdForPermissionAudit !== null ? { requestedBy: runIdForPermissionAudit } : {}),
 				});
 			}
-			if (event.type === "clio_tool_finish" && event.payload && typeof event.payload.tool === "string") {
+			if (event.type === "clio_coder_tool_finish" && event.payload && typeof event.payload.tool === "string") {
 				recordToolCompletion(inFlightTools, event.payload);
 				recordToolFinish(toolStats, event.payload);
 				if (event.payload.decision === "allowed") safetyDecisionCounts.allowed += 1;
@@ -3774,8 +3867,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();
 			}
 			identity = detectRunIdentity();
@@ -3801,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,
@@ -3925,7 +4022,7 @@ export function createDispatchBundle(
 			const finalFailureMessage = result.failureMessage ?? failureMessage;
 			const finalToolStats = snapshotToolStats(toolStats);
 			const unfinished = snapshotUnfinishedTools(inFlightTools);
-			const toolGovernance = lifecycle.agentConfig.toolGovernance ?? "clio-policy";
+			const toolGovernance = lifecycle.agentConfig.toolGovernance ?? "clio-coder-policy";
 			return {
 				runId: envelope.id,
 				agentId: req.agentId,
@@ -3978,7 +4075,7 @@ export function createDispatchBundle(
 				dynamicHash: lifecycle.dynamicHash,
 				promptSignature: lifecycle.promptSignature,
 				toolSignature: lifecycle.toolSignature,
-				clioVersion: readClioVersion(),
+				clioCoderVersion: readClioVersion(),
 				piMonoVersion: readPiMonoVersion(),
 				platform: process.platform,
 				nodeVersion: process.version,
@@ -3992,7 +4089,7 @@ export function createDispatchBundle(
 				quality: createRunReceiptQuality({ runtimeEnforceable: false, enforcementPassed: null, resultContract: null }),
 				autonomyEnforcement: autonomyEnforcementForAcpDelegation(
 					lifecycle.autonomy,
-					lifecycle.agentConfig.toolGovernance ?? "clio-policy",
+					lifecycle.agentConfig.toolGovernance ?? "clio-coder-policy",
 					lifecycle.sessionAutonomy,
 					req.autonomy,
 				),
@@ -4022,7 +4119,7 @@ export function createDispatchBundle(
 					toolCallsRequested: result.delegation.toolCallsRequested,
 					toolCallsApproved: result.delegation.toolCallsApproved,
 					toolCallsDenied: result.delegation.toolCallsDenied,
-					toolGovernance: lifecycle.agentConfig.toolGovernance ?? "clio-policy",
+					toolGovernance: lifecycle.agentConfig.toolGovernance ?? "clio-coder-policy",
 					toolCallLog: acp.toolCallLog(),
 				},
 				sessionId: result.delegation.acpSessionId,
@@ -4257,7 +4354,7 @@ export function createDispatchBundle(
 		const requestedAt = new Date(now()).toISOString();
 		const timing: RunPhaseMarks = { requestedAt, decisionStartedAt: requestedAt };
 		const settings = getEffectiveSettings();
-		const isAcpAgent = settings?.delegation?.agents?.some((entry) => entry.id === req.agentId) ?? false;
+		const isAcpAgent = settings?.integrations.externalAgents?.entries?.some((entry) => entry.id === req.agentId) ?? false;
 		if (isAcpAgent && !req.delegationAgentId) {
 			req.delegationAgentId = req.agentId;
 		}
@@ -4268,12 +4365,16 @@ 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);
 			const activation = consumeActiveRouteApproval({
 				request: req,
-				settings: settings?.routing,
+				settings: settings?.fleet.adaptiveRouting,
 				capabilityClass: recipe === null ? null : normalizeAgentSpec(recipe).capabilityClass,
 				failover: failoverModeFor(req),
 				requestedAt,
@@ -4395,7 +4496,41 @@ export function createDispatchBundle(
 			shadow: () => observeShadowRoute(req, placed, settings),
 		});
 
-		const capacityLease = await admitAssignmentCapacity(req, placement?.node.id ?? "local", timing, endpoint);
+		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 = (() => {
@@ -4533,7 +4668,7 @@ export function createDispatchBundle(
 				context.bus.emit(BusChannels.DispatchProgress, {
 					runId,
 					agentId: req.agentId,
-					event: { type: "clio_write_record_downgraded", payload: downgrade },
+					event: { type: "clio_coder_write_record_downgraded", payload: downgrade },
 				});
 			},
 		});
@@ -4587,8 +4722,8 @@ export function createDispatchBundle(
 					policySource?: string;
 					reason?: string;
 					skillActivation?: unknown;
-					// Worker permission-escalation fields (clio_permission_escalated /
-					// clio_permission_resolved escalate path).
+					// Worker permission-escalation fields (clio_coder_permission_escalated /
+					// clio_coder_permission_resolved escalate path).
 					requestId?: string;
 					summary?: string;
 					target?: string;
@@ -4601,12 +4736,12 @@ export function createDispatchBundle(
 				if (eventContainsFirstModelToken(event)) markObservedPhase("firstModelTokenAt");
 				if (eventStartsTool(event)) markObservedPhase("firstToolAt");
 			}
-			if (event.type === "clio_tool_start" && event.payload && typeof event.payload.tool === "string") {
+			if (event.type === "clio_coder_tool_start" && event.payload && typeof event.payload.tool === "string") {
 				recordToolStart(inFlightTools, event.payload);
 			}
-			if (event.type === "clio_steer_received") acknowledgeSteer(event.payload?.sequence);
+			if (event.type === "clio_coder_steer_received") acknowledgeSteer(event.payload?.sequence);
 			if (
-				event.type === "clio_run_outcome" &&
+				event.type === "clio_coder_run_outcome" &&
 				isRunOutcomeCode(event.payload?.outcomeCode) &&
 				event.payload.outcomeCode !== "worker_final_output_missing" &&
 				event.payload.outcomeCode !== "host_verification_rejected"
@@ -4629,7 +4764,11 @@ export function createDispatchBundle(
 				}
 				recordWorkerRunEffect(runEffects, event);
 			}
-			if (event.type === "clio_permission_escalated" && event.payload && typeof event.payload.requestId === "string") {
+			if (
+				event.type === "clio_coder_permission_escalated" &&
+				event.payload &&
+				typeof event.payload.requestId === "string"
+			) {
 				escalationCounts.requested += 1;
 				const ctx = isRecord(event.payload.decision) ? event.payload.decision : null;
 				const classification = ctx !== null && isRecord(ctx.classification) ? ctx.classification : null;
@@ -4664,6 +4803,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,
 				});
 			}
@@ -4689,7 +4829,7 @@ export function createDispatchBundle(
 					if (message !== null) failureMessage = message;
 				}
 			}
-			if (event.type === "clio_permission_resolved" && event.payload && typeof event.payload.tool === "string") {
+			if (event.type === "clio_coder_permission_resolved" && event.payload && typeof event.payload.tool === "string") {
 				// Escalation resolutions already have a request event. Policy
 				// deny/fail is non-stalling, so dispatch mints the adjacent pair.
 				const source = event.payload.source;
@@ -4738,10 +4878,11 @@ export function createDispatchBundle(
 					decidedBy,
 					actionClass,
 					reason,
+					...(source === "timeout" ? { fallback: spec.escalation?.fallback ?? "deny" } : {}),
 					...(runIdForPermissionAudit !== null ? { requestedBy: runIdForPermissionAudit } : {}),
 				});
 			}
-			if (event.type === "clio_tool_finish" && event.payload && typeof event.payload.tool === "string") {
+			if (event.type === "clio_coder_tool_finish" && event.payload && typeof event.payload.tool === "string") {
 				recordToolCompletion(inFlightTools, event.payload);
 				recordToolFinish(toolStats, event.payload);
 				if (isSkillActivation(event.payload.skillActivation)) {
@@ -4793,8 +4934,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) {
@@ -4855,18 +4998,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,
@@ -5096,7 +5241,7 @@ export function createDispatchBundle(
 				dynamicHash: lifecycle.dynamicHash,
 				promptSignature: lifecycle.promptSignature,
 				toolSignature: lifecycle.toolSignature,
-				clioVersion: readClioVersion(),
+				clioCoderVersion: readClioVersion(),
 				piMonoVersion: readPiMonoVersion(),
 				platform: process.platform,
 				nodeVersion: process.version,
@@ -5121,7 +5266,7 @@ export function createDispatchBundle(
 				...(skillActivations.length > 0 ? { skillActivations: [...skillActivations] } : {}),
 				autonomyEnforcement: autonomyEnforcementForWorkerSpec(
 					spec,
-					lifecycle.settings?.autonomy ?? "auto-edit",
+					lifecycle.settings?.safety.autonomy ?? "auto-edit",
 					req.autonomy,
 				),
 				safety: {
@@ -5295,18 +5440,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") {
@@ -5645,7 +5779,7 @@ export function createDispatchBundle(
 		req: DispatchRequest,
 		settings: EffectiveSettings = getEffectiveSettings(),
 	): DispatchPlanTaskResolution {
-		const isAcpAgent = settings?.delegation?.agents?.some((entry) => entry.id === req.agentId) ?? false;
+		const isAcpAgent = settings?.integrations.externalAgents?.entries?.some((entry) => entry.id === req.agentId) ?? false;
 		if (isAcpAgent && !req.delegationAgentId) req = { ...req, delegationAgentId: req.agentId };
 		const validation = routeValidationProjection(req, true);
 		const validated = validateJobSpec(validation.jobSpec);
@@ -5721,7 +5855,7 @@ export function createDispatchBundle(
 			req,
 		);
 		assertPostRuntimeToolCompatibility(req.agentId, agentSpec, effectiveTools, target);
-		assertRuntimeCanHonorWorkerPermissionMode(target.runtime, settings?.workers.onPermission ?? "deny");
+		assertRuntimeCanHonorWorkerPermissionMode(target.runtime, settings?.fleet.permissions.mode ?? "deny");
 		assertWorkerBudgetEnforceable(target.runtime, agentSpec.budget !== null || req.budget !== undefined);
 		assertResponseSchemaEnforceable(target.runtime, target.modelCapabilities, req.responseSchema, effectiveTools.length);
 		assertWriteRootsEnforceable(target.runtime, pathScope.writeBoundaries);
@@ -5783,7 +5917,7 @@ export function createDispatchBundle(
 			specs,
 			request: req,
 			mode,
-			activeAgentRoles: settings?.routing.agentAutomation.activeAgentRoles ?? [],
+			activeAgentRoles: settings?.fleet.adaptiveRouting.agentRoles ?? [],
 			...(agentIntent === undefined ? {} : { intentOverride: agentIntent }),
 		});
 		const settingsFingerprint = computeSettingsFingerprint(settings ?? null);
@@ -5878,7 +6012,7 @@ export function createDispatchBundle(
 		const recipe = agents.get(req.agentId);
 		return planActiveRoute({
 			request: req,
-			settings: settings?.routing,
+			settings: settings?.fleet.adaptiveRouting,
 			capabilityClass: recipe === null ? null : normalizeAgentSpec(recipe).capabilityClass,
 			failover: failoverModeFor(req),
 			fixed,
@@ -6089,7 +6223,7 @@ export function createDispatchBundle(
 			costProvenance: "unknown",
 			compiledPromptHash: null,
 			staticCompositionHash: null,
-			clioVersion: readClioVersion(),
+			clioCoderVersion: readClioVersion(),
 			piMonoVersion: readPiMonoVersion(),
 			platform: process.platform,
 			nodeVersion: process.version,
@@ -6154,8 +6288,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() });
@@ -6221,6 +6362,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;
 		},
 	};
 
@@ -6248,6 +6393,26 @@ export function createDispatchBundle(
 		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(heartbeatMonotonicAt(run.heartbeatAt))) {
@@ -6426,6 +6591,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);