@iowarp/clio-coder 0.3.7 → 0.3.9

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

@@ -0,0 +1,370 @@
+import {
+	asDirectoryPathBoundary,
+	normalizePathBoundaryEntry,
+	PathBoundaryError,
+	pathBoundaryCovers,
+	resolvePathBoundary,
+} from "../../core/path-boundary.js";
+import type { DispatchRequest } from "./contract.js";
+
+/** Path-like tokens retained for requests that do not carry typed intent. */
+const DISPATCH_PATH_TOKEN_RE = /(?:[\w.-]+\/)+[\w.-]+|\b[\w-]+\.[A-Za-z0-9]{1,8}\b/g;
+const HTTP_URL_RE = /\bhttps?:\/\/\S+/gu;
+const POSIX_ABSOLUTE_TOKEN_RE = /(?:^|[\s("'])((?:\/[\w.~+-]+)+)/gu;
+const WINDOWS_ABSOLUTE_TOKEN_RE = /(?:^|[\s("'])([A-Za-z]:[\\/][^\s"']+)/gu;
+const BACKSLASH_PATH_RE = /\b[A-Za-z_.-][\w.-]*\\(?:(?:[\w.-]+\\)+[\w.-]+|[\w-]+\.[A-Za-z0-9]{1,8})\b/gu;
+const DOUBLE_SEPARATOR_PATH_RE = /\b[\w.-]+\/\/[\w./-]+/gu;
+
+export type DispatchPathProvenanceKind = "declared" | "derived" | "inferred";
+export type DispatchPathConfidence = "certain" | "high" | "medium" | "low";
+export type DispatchPathProvenanceSource =
+	| "intent.read_roots"
+	| "intent.write_roots"
+	| "intent.relevant_paths"
+	| "writeRoots"
+	| "task"
+	| "briefing";
+export type DispatchPathProvenanceReason =
+	| "explicit_intent"
+	| "legacy_write_roots"
+	| "task_path_token"
+	| "briefing_path_token";
+
+export interface DispatchPathProvenanceEvidence {
+	provenance: DispatchPathProvenanceKind;
+	source: DispatchPathProvenanceSource;
+	confidence: DispatchPathConfidence;
+	reason: DispatchPathProvenanceReason;
+}
+
+export interface DispatchPathProvenanceEntry {
+	path: string;
+	evidence: DispatchPathProvenanceEvidence[];
+}
+
+export interface DispatchPathScopeProvenance {
+	version: 1;
+	mode: "declared" | "legacy-inferred";
+	workingContextPaths: DispatchPathProvenanceEntry[];
+	writeBoundaries: DispatchPathProvenanceEntry[];
+}
+
+export interface DispatchPathScope {
+	source: "declared" | "inferred";
+	workingContextPaths: ReadonlyArray<string>;
+	writeBoundaries: ReadonlyArray<string>;
+	inferredOnlyPaths: ReadonlyArray<string>;
+	provenance: DispatchPathScopeProvenance;
+}
+
+export interface DeclaredScopeReplacementNotice {
+	code: "typed_scope_replaced_inferred_paths";
+	level: "warning";
+	omittedPaths: ReadonlyArray<string>;
+	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 {
+	readonly code: DispatchPathScopeInferenceErrorCode;
+	readonly source: "task" | "briefing";
+	readonly token: string;
+
+	constructor(code: DispatchPathScopeInferenceErrorCode, source: "task" | "briefing", token: string, detail: string) {
+		super(`${code}: ${source} contains ${detail} '${token}'; declare intent explicitly`);
+		this.name = "DispatchPathScopeInferenceError";
+		this.code = code;
+		this.source = source;
+		this.token = token;
+	}
+}
+
+const DECLARED_EVIDENCE = {
+	readRoots: {
+		provenance: "declared",
+		source: "intent.read_roots",
+		confidence: "certain",
+		reason: "explicit_intent",
+	},
+	writeRoots: {
+		provenance: "declared",
+		source: "intent.write_roots",
+		confidence: "certain",
+		reason: "explicit_intent",
+	},
+	relevantPaths: {
+		provenance: "declared",
+		source: "intent.relevant_paths",
+		confidence: "certain",
+		reason: "explicit_intent",
+	},
+} as const satisfies Record<"readRoots" | "writeRoots" | "relevantPaths", DispatchPathProvenanceEvidence>;
+
+function cloneEvidence(evidence: DispatchPathProvenanceEvidence): DispatchPathProvenanceEvidence {
+	return { ...evidence };
+}
+
+function addProvenance(
+	entries: Map<string, DispatchPathProvenanceEntry>,
+	path: string,
+	evidence: DispatchPathProvenanceEvidence,
+): void {
+	const current = entries.get(path);
+	if (current === undefined) {
+		entries.set(path, { path, evidence: [cloneEvidence(evidence)] });
+		return;
+	}
+	if (!current.evidence.some((entry) => entry.source === evidence.source)) {
+		current.evidence.push(cloneEvidence(evidence));
+	}
+}
+
+function sortedEntries(entries: Map<string, DispatchPathProvenanceEntry>): DispatchPathProvenanceEntry[] {
+	return [...entries.values()]
+		.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0))
+		.map((entry) => ({ path: entry.path, evidence: entry.evidence.map(cloneEvidence) }));
+}
+
+/** Build the required field-level provenance for normalized declared intent. */
+export function declaredIntentPathProvenance(input: {
+	readRoots: ReadonlyArray<string>;
+	writeRoots: ReadonlyArray<string>;
+	relevantPaths: ReadonlyArray<string>;
+}): DispatchPathProvenanceEntry[] {
+	const entries = new Map<string, DispatchPathProvenanceEntry>();
+	for (const path of input.readRoots) addProvenance(entries, path, DECLARED_EVIDENCE.readRoots);
+	for (const path of input.writeRoots) addProvenance(entries, path, DECLARED_EVIDENCE.writeRoots);
+	for (const path of input.relevantPaths) addProvenance(entries, path, DECLARED_EVIDENCE.relevantPaths);
+	return sortedEntries(entries);
+}
+
+function inferredPaths(req: Pick<DispatchRequest, "task" | "briefing">): string[] {
+	const paths = new Set<string>();
+	const text = `${req.task}\n${req.briefing ?? ""}`;
+	for (const match of text.matchAll(DISPATCH_PATH_TOKEN_RE)) {
+		const token = inferredPathToken(match[0]);
+		if (token.startsWith("http://") || token.startsWith("https://")) continue;
+		paths.add(token);
+	}
+	return [...paths];
+}
+
+function inferredPathToken(token: string): string {
+	return token.replace(/\.+$/u, "");
+}
+
+function failMalformedText(text: string, source: "task" | "briefing"): void {
+	const withoutUrls = text.replace(HTTP_URL_RE, (url) => " ".repeat(url.length));
+	const absolute = POSIX_ABSOLUTE_TOKEN_RE.exec(withoutUrls)?.[1];
+	POSIX_ABSOLUTE_TOKEN_RE.lastIndex = 0;
+	if (absolute !== undefined) {
+		throw new DispatchPathScopeInferenceError("legacy_scope_path_absolute", source, absolute, "an absolute path token");
+	}
+	const windowsAbsolute = WINDOWS_ABSOLUTE_TOKEN_RE.exec(withoutUrls)?.[1];
+	WINDOWS_ABSOLUTE_TOKEN_RE.lastIndex = 0;
+	if (windowsAbsolute !== undefined) {
+		throw new DispatchPathScopeInferenceError(
+			"legacy_scope_path_absolute",
+			source,
+			windowsAbsolute,
+			"an absolute path token",
+		);
+	}
+	for (const pattern of [BACKSLASH_PATH_RE, DOUBLE_SEPARATOR_PATH_RE]) {
+		const malformed = pattern.exec(withoutUrls)?.[0];
+		pattern.lastIndex = 0;
+		if (malformed !== undefined) {
+			throw new DispatchPathScopeInferenceError(
+				"legacy_scope_path_malformed",
+				source,
+				malformed,
+				"a malformed path token",
+			);
+		}
+	}
+}
+
+function strictInferredPaths(
+	text: string,
+	source: "task" | "briefing",
+): Array<{ path: string; evidence: DispatchPathProvenanceEvidence }> {
+	failMalformedText(text, source);
+	const withoutUrls = text.replace(HTTP_URL_RE, (url) => " ".repeat(url.length));
+	const evidence: DispatchPathProvenanceEvidence =
+		source === "task"
+			? { provenance: "inferred", source, confidence: "medium", reason: "task_path_token" }
+			: { provenance: "inferred", source, confidence: "low", reason: "briefing_path_token" };
+	const result: Array<{ path: string; evidence: DispatchPathProvenanceEvidence }> = [];
+	for (const match of withoutUrls.matchAll(DISPATCH_PATH_TOKEN_RE)) {
+		const token = inferredPathToken(match[0]);
+		try {
+			result.push({ path: normalizePathBoundaryEntry(token), evidence });
+		} catch (error) {
+			const code =
+				error instanceof PathBoundaryError && error.code === "absolute"
+					? "legacy_scope_path_absolute"
+					: "legacy_scope_path_malformed";
+			throw new DispatchPathScopeInferenceError(
+				code,
+				source,
+				token,
+				code === "legacy_scope_path_absolute" ? "an absolute path token" : "a malformed path token",
+			);
+		}
+	}
+	return result;
+}
+
+function legacyPathScope(req: DispatchRequest, cwd: string): DispatchPathScope {
+	const workingEntries = new Map<string, DispatchPathProvenanceEntry>();
+	const writeEntries = new Map<string, DispatchPathProvenanceEntry>();
+	const writeEvidence: DispatchPathProvenanceEvidence = {
+		provenance: "derived",
+		source: "writeRoots",
+		confidence: "high",
+		reason: "legacy_write_roots",
+	};
+	for (const root of req.writeRoots ?? []) {
+		addProvenance(workingEntries, root, writeEvidence);
+		addProvenance(writeEntries, asDirectoryPathBoundary(resolvePathBoundary(cwd, root)), writeEvidence);
+	}
+	for (const candidate of strictInferredPaths(req.task, "task")) {
+		addProvenance(workingEntries, candidate.path, candidate.evidence);
+	}
+	if (req.briefing !== undefined) {
+		for (const candidate of strictInferredPaths(req.briefing, "briefing")) {
+			addProvenance(workingEntries, candidate.path, candidate.evidence);
+		}
+	}
+	const workingContext = [...workingEntries.values()].map((entry) => ({
+		path: entry.path,
+		evidence: entry.evidence.map(cloneEvidence),
+	}));
+	const writeBoundaries = [...writeEntries.values()].map((entry) => ({
+		path: entry.path,
+		evidence: entry.evidence.map(cloneEvidence),
+	}));
+	return {
+		source: "inferred",
+		workingContextPaths: workingContext.map((entry) => entry.path),
+		writeBoundaries: writeBoundaries.map((entry) => entry.path),
+		inferredOnlyPaths: [],
+		provenance: {
+			version: 1,
+			mode: "legacy-inferred",
+			workingContextPaths: workingContext,
+			writeBoundaries,
+		},
+	};
+}
+
+/** Resolve every policy-bearing path projection for one dispatch request. */
+export function resolveDispatchPathScope(req: DispatchRequest): DispatchPathScope {
+	const cwd = req.cwd ?? process.cwd();
+	if (req.intent === undefined) return legacyPathScope(req, cwd);
+
+	const declaredProvenance = declaredIntentPathProvenance(req.intent);
+	const declaredPaths = declaredProvenance.map((entry) => entry.path);
+	const inferredOnlyPaths = inferredPaths(req).filter((candidate) => !pathBoundaryCovers(declaredPaths, candidate));
+	const writeEvidence = DECLARED_EVIDENCE.writeRoots;
+	const writeBoundaries = req.intent.writeRoots.map((root) => ({
+		path: resolvePathBoundary(cwd, root),
+		evidence: [cloneEvidence(writeEvidence)],
+	}));
+	return {
+		source: "declared",
+		workingContextPaths: declaredPaths,
+		writeBoundaries: writeBoundaries.map((entry) => entry.path),
+		inferredOnlyPaths,
+		provenance: {
+			version: 1,
+			mode: "declared",
+			workingContextPaths: declaredProvenance,
+			writeBoundaries,
+		},
+	};
+}
+
+/** Render the named diagnostic for the declared-scope replacement tradeoff. */
+export function declaredScopeReplacementDiagnostic(scope: DispatchPathScope): string | null {
+	if (scope.source !== "declared" || scope.inferredOnlyPaths.length === 0) return null;
+	return `typed_scope_replaced_inferred_paths: typed intent omitted prose-inferred paths ${scope.inferredOnlyPaths.join(
+		", ",
+	)}; those paths did not select project rules or expand worker authority`;
+}
+
+/** Render the interactive warning for the declared-scope replacement tradeoff. */
+export function declaredScopeReplacementNotice(scope: DispatchPathScope): DeclaredScopeReplacementNotice | null {
+	if (scope.source !== "declared" || scope.inferredOnlyPaths.length === 0) return null;
+	const omittedPaths = [...scope.inferredOnlyPaths];
+	return {
+		code: "typed_scope_replaced_inferred_paths",
+		level: "warning",
+		omittedPaths,
+		message: `[dispatch scope] typed intent replaced prose path inference; omitted paths: ${omittedPaths.join(
+			", ",
+		)}. 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/receipt-integrity.ts

@@ -10,7 +10,7 @@ import type { RunEnvelope, RunReceipt, RunReceiptDraft, RunReceiptIntegrity, Run
  * base, so there are no historical receipts to keep verifying: a receipt is
  * either this version or it is not a receipt.
  */
-export const RUN_RECEIPT_INTEGRITY_VERSION: RunReceiptIntegrity["version"] = 19;
+export const RUN_RECEIPT_INTEGRITY_VERSION: RunReceiptIntegrity["version"] = 20;
 export type ReceiptIntegrityVersion = RunReceiptIntegrity["version"];
 export type ReceiptIntegrityField = keyof RunReceiptDraft;
 export const RUN_RECEIPT_INTEGRITY_ALGORITHM = "sha256";
@@ -77,6 +77,7 @@ export const RECEIPT_INTEGRITY_FIELD_COVERAGE = {
 	requestOrigin: true,
 	task: true,
 	intent: true,
+	pathScope: true,
 	// Historical receipts omit this field, so their receipt and ledger payloads remain unchanged.
 	budget: true,
 	targetId: true,

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

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { withStateFileLockSync } from "../../core/state-file-lock.js";
+import { endpointLabel } from "../providers/endpoint-capacity.js";
 import {
 	acquireCapacityLease,
 	activeCapacityDrainUnsafe,
@@ -7,6 +8,7 @@ import {
 	type CapacityLimits,
 	type CapacityStateFile,
 	capacityStateLockPath,
+	describeEndpointCapacityHolders,
 	readCapacityStateUnsafe,
 	writeCapacityStateUnsafe,
 } from "./capacity-lease.js";
@@ -19,9 +21,10 @@ export type ReservationMemberStatus = "held" | "consumed" | "released";
 export type ReservationStatus = "active" | "released" | "rolled_back" | "expired";
 
 /**
- * A reservation holds three scarce things and nothing else: a global
- * concurrency slot, a per-node slot, and a budget upper bound. Node identity
- * matters only because slots are per-node. Agent, target, model, and runtime
+ * A reservation holds four scarce things and nothing else: a global
+ * concurrency slot, a per-node slot, an inference-endpoint slot, and a budget
+ * upper bound. Node and endpoint identity matter only because slots bind on
+ * those dimensions. Agent, target, model, and runtime
  * identity are route identity, which the failover envelope owns
  * (`assertRouteWithinApprovedEnvelope`); pinning them here made a
  * plan-approved dispatch unable to fail over at all.
@@ -30,6 +33,7 @@ export interface ReservationPlanTask {
 	memberId: string;
 	wave: number;
 	nodeId: string;
+	endpointKey?: string;
 	costUpperBoundUsd: number;
 }
 
@@ -54,17 +58,31 @@ export interface DispatchReservationRecord {
 export interface ReservationCapacitySnapshot {
 	global: { active: number; limit: number };
 	nodes: Readonly<Record<string, { active: number; limit: number }>>;
+	endpoints: Readonly<Record<string, { active: number; limit: number; leases?: number; foregroundStreams?: number }>>;
 	budget: { currentUsd: number; ceilingUsd: number };
 }
 
 export interface ReservationAllocation {
 	globalSlots: number;
 	nodeSlots: Readonly<Record<string, number>>;
+	endpointSlots: Readonly<Record<string, number>>;
 	budgetUsd: number;
 }
 
 export type ReservationPlanResult = { ok: true; allocation: ReservationAllocation } | { ok: false; reason: string };
 
+function endpointCapacityDenial(input: {
+	endpointKey: string;
+	limit: number;
+	used: number;
+	requested: number;
+	leases: number;
+	reservations: number;
+	foregroundStreams: number;
+}): 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`;
+}
+
 function copyRecord(record: DispatchReservationRecord): DispatchReservationRecord {
 	return { ...record, members: record.members.map((member) => ({ ...member })) };
 }
@@ -96,6 +114,7 @@ function validRecord(value: unknown): value is DispatchReservationRecord {
 				typeof member.memberId === "string" &&
 				Number.isInteger(member.wave) &&
 				typeof member.nodeId === "string" &&
+				(member.endpointKey === undefined || typeof member.endpointKey === "string") &&
 				typeof member.costUpperBoundUsd === "number" &&
 				Number.isFinite(member.costUpperBoundUsd) &&
 				member.costUpperBoundUsd >= 0 &&
@@ -145,9 +164,13 @@ function reservationAllocation(tasks: ReadonlyArray<ReservationPlanTask>): Reser
 		),
 	);
 	const nodeSlots = peakBy(tasks.map((task) => ({ wave: task.wave, key: task.nodeId })));
+	const endpointSlots = peakBy(
+		tasks.flatMap((task) => (task.endpointKey === undefined ? [] : [{ wave: task.wave, key: task.endpointKey }])),
+	);
 	return {
 		globalSlots,
 		nodeSlots,
+		endpointSlots,
 		budgetUsd: tasks.reduce((sum, task) => sum + task.costUpperBoundUsd, 0),
 	};
 }
@@ -191,6 +214,26 @@ function allocateReservation(
 			return { ok: false, reason: `node '${nodeId}' capacity exceeded (${used + slots}/${node.limit})` };
 		}
 	}
+	for (const [endpointKey, slots] of Object.entries(requested.endpointSlots)) {
+		const endpoint = capacity.endpoints[endpointKey];
+		if (!endpoint || !Number.isFinite(endpoint.limit)) continue;
+		const heldSlots = held.reduce((sum, allocation) => sum + (allocation.endpointSlots[endpointKey] ?? 0), 0);
+		const used = endpoint.active + heldSlots;
+		if (used + slots > endpoint.limit) {
+			return {
+				ok: false,
+				reason: endpointCapacityDenial({
+					endpointKey,
+					limit: endpoint.limit,
+					used,
+					requested: slots,
+					leases: endpoint.leases ?? endpoint.active - (endpoint.foregroundStreams ?? 0),
+					reservations: heldSlots,
+					foregroundStreams: endpoint.foregroundStreams ?? 0,
+				}),
+			};
+		}
+	}
 	const existingBudget = activeRecords.reduce((sum, record) => sum + outstandingBudget(record), 0);
 	const projected = capacity.budget.currentUsd + existingBudget + requested.budgetUsd;
 	if (projected >= capacity.budget.ceilingUsd) {
@@ -225,7 +268,9 @@ export function createDispatchReservation(input: {
 		if (!planned.ok) {
 			replaceReservations(state, records);
 			writeCapacityStateUnsafe(state);
-			throw new Error(`dispatch: reservation denied: ${planned.reason}`);
+			throw new Error(
+				planned.reason.startsWith("dispatch:") ? planned.reason : `dispatch: reservation denied: ${planned.reason}`,
+			);
 		}
 		const createdAt = new Date(nowMs).toISOString();
 		const record: DispatchReservationRecord = {
@@ -250,6 +295,7 @@ export function transferDispatchReservationToLease(input: {
 	memberId: string;
 	assignmentId: string;
 	nodeId: string;
+	endpointKey?: string;
 	limits: CapacityLimits;
 	nowMs?: number;
 	ttlMs?: number;
@@ -258,6 +304,7 @@ export function transferDispatchReservationToLease(input: {
 	return acquireCapacityLease({
 		assignmentId: input.assignmentId,
 		nodeId: input.nodeId,
+		...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
 		limits: input.limits,
 		nowMs,
 		...(input.ttlMs !== undefined ? { ttlMs: input.ttlMs } : {}),
@@ -290,6 +337,7 @@ export function rebindDispatchReservationMember(input: {
 	ownerId: string;
 	memberId: string;
 	nodeId: string;
+	endpointKey?: string;
 	costUpperBoundUsd: number;
 	capacity: ReservationCapacitySnapshot;
 	nowMs?: number;
@@ -304,11 +352,42 @@ export function rebindDispatchReservationMember(input: {
 		if (member.status === "released") {
 			throw new Error(`dispatch: reservation member '${input.memberId}' was already released`);
 		}
-		if (member.nodeId === input.nodeId && member.costUpperBoundUsd === input.costUpperBoundUsd) {
+		if (
+			member.nodeId === input.nodeId &&
+			member.endpointKey === input.endpointKey &&
+			member.costUpperBoundUsd === input.costUpperBoundUsd
+		) {
 			return copyRecord(record);
 		}
-
 		const others = records.filter((entry) => entry.status === "active" && entry.ownerId !== input.ownerId);
+		if (member.endpointKey !== input.endpointKey && input.endpointKey !== undefined) {
+			const endpointKey = input.endpointKey;
+			const endpoint = input.capacity.endpoints[endpointKey];
+			if (endpoint !== undefined && Number.isFinite(endpoint.limit)) {
+				const siblingSlots = record.members.filter(
+					(entry) => entry !== member && entry.status !== "released" && entry.endpointKey === endpointKey,
+				).length;
+				const otherHeld = others.reduce(
+					(sum, entry) => sum + (reservationAllocation(outstandingTasks(entry)).endpointSlots[endpointKey] ?? 0),
+					0,
+				);
+				const used = endpoint.active + otherHeld + siblingSlots;
+				if (used + 1 > endpoint.limit) {
+					throw new Error(
+						endpointCapacityDenial({
+							endpointKey,
+							limit: endpoint.limit,
+							used,
+							requested: 1,
+							leases: endpoint.leases ?? endpoint.active - (endpoint.foregroundStreams ?? 0),
+							reservations: otherHeld + siblingSlots,
+							foregroundStreams: endpoint.foregroundStreams ?? 0,
+						}),
+					);
+				}
+			}
+		}
+
 		if (member.nodeId !== input.nodeId) {
 			const node = input.capacity.nodes[input.nodeId];
 			if (node !== undefined && Number.isFinite(node.limit)) {
@@ -342,6 +421,8 @@ export function rebindDispatchReservationMember(input: {
 		}
 
 		member.nodeId = input.nodeId;
+		if (input.endpointKey === undefined) delete member.endpointKey;
+		else member.endpointKey = input.endpointKey;
 		member.costUpperBoundUsd = Math.max(0, input.costUpperBoundUsd);
 		writeStore(records);
 		return copyRecord(record);
@@ -370,6 +451,26 @@ export function releaseDispatchReservationMember(
 	});
 }
 
+/** Settle every member after the scheduler has finished the reserved plan. */
+export function releaseDispatchReservation(ownerId: string, nowMs = Date.now()): DispatchReservationRecord | null {
+	return withStateFileLockSync(capacityStateLockPath(), () => {
+		const records = readStore();
+		const record = records.find((entry) => entry.ownerId === ownerId);
+		if (!record) return null;
+		if (record.status !== "active") return copyRecord(record);
+		const settledAt = new Date(nowMs).toISOString();
+		for (const member of record.members) {
+			if (member.status === "released") continue;
+			member.status = "released";
+			member.releasedAt = settledAt;
+		}
+		record.status = "released";
+		record.settledAt = settledAt;
+		writeStore(records);
+		return copyRecord(record);
+	});
+}
+
 export function rollbackDispatchReservation(ownerId: string, nowMs = Date.now()): DispatchReservationRecord | null {
 	return withStateFileLockSync(capacityStateLockPath(), () => {
 		const records = readStore();
@@ -488,14 +589,21 @@ export function reservedBudgetUsd(): number {
 		.reduce((sum, record) => sum + outstandingBudget(record), 0);
 }
 
-export function reservedCapacity(): { globalSlots: number; nodeSlots: Readonly<Record<string, number>> } {
+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 };
+	return { globalSlots, nodeSlots, endpointSlots };
 }

package/src/domains/dispatch/state.ts

@@ -107,6 +107,10 @@ export async function writeFleetRun(record: FleetRunRecord): Promise<void> {
 	await atomicWrite(fleetRunPath(record.id), `${JSON.stringify(record, null, 2)}\n`);
 }
 
+// `RunEnvelope.heartbeatAt` deliberately persists only the absolute wall-clock
+// anchor used for operator display and crash recovery. The monotonic heartbeat
+// stamp belongs to the live transport in this process; serializing it would
+// give a restarted process a number from an origin it cannot share.
 function readRuns(): RunEnvelope[] {
 	const path = runsPath();
 	if (!existsSync(path)) return [];