@iowarp/clio-coder 0.3.8 → 0.3.9

package/src/domains/context/codewiki/coordinator.ts

@@ -140,8 +140,16 @@ export function coordinateCodewikiWrite(
 	options: CodewikiCoordinateOptions = {},
 ): Promise<CodewikiCoordinatedResult | null> {
 	const workspace = resolve(cwd);
-	return enqueueWorkspace(workspace, () =>
-		withStateFileLock(codewikiPath(workspace), async () => {
+	return enqueueWorkspace(workspace, () => {
+		// Taking the lease creates the lock's parent, so a project that was never
+		// indexed gained an empty `.clio-coder/` from every successful write: the
+		// incremental refresh is contractually a no-op there, and it was
+		// materializing state before it could say so (issue #248). The check runs
+		// inside the queue, so a writer that built the codewiki ahead of this task
+		// has already finished and this one sees it. The recheck under the lock
+		// stays, and is what still decides the race.
+		if (options.requireExisting && !existsSync(codewikiPath(workspace))) return Promise.resolve(null);
+		return withStateFileLock(codewikiPath(workspace), async () => {
 			if (options.requireExisting && !existsSync(codewikiPath(workspace))) return null;
 			const current = options.readCurrent?.(workspace) ?? readCodewiki(workspace);
 			const request = await select(current, workspace);
@@ -152,8 +160,8 @@ export function coordinateCodewikiWrite(
 			if (wrote) writeCodewiki(workspace, worker.codewiki);
 			await options.afterCommit?.(worker, workspace);
 			return { codewiki: !worker.changed && current ? current : worker.codewiki, worker, wrote };
-		}),
-	);
+		});
+	});
 }
 
 /** Serialize a non-build artifact transaction such as reset with every writer. */

package/src/domains/dispatch/admission.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { endpointLabel } from "../providers/endpoint-capacity.js";
 import type { ActionClass } from "../safety/action-classifier.js";
 import type { ScopeSpec } from "../safety/scope.js";
 import { createAdmissionQueue } from "./admission-queue.js";
@@ -7,6 +8,8 @@ import {
 	type CapacityLease,
 	type CapacityLimits,
 	capacityLeaseUsage,
+	describeEndpointCapacityHolders,
+	type EndpointCapacityHolders,
 	heartbeatCapacityLease,
 	releaseCapacityLease,
 	renameCapacityLeaseAssignment,
@@ -41,6 +44,7 @@ export interface CapacityAdmissionController {
 	admit(input: {
 		assignmentId: string;
 		nodeId: string;
+		endpointKey?: string;
 		deadlineAt: number;
 		priority?: number;
 		planId?: string;
@@ -105,13 +109,31 @@ const PUMP_MAX_MS = 500;
 function describeAdmissionFailure(input: {
 	state: "canceled" | "timed_out";
 	nodeId: string;
+	endpointKey?: string;
 	waitedMs: number;
 	overdueAtQueueMs: number;
 	queueDepth: number;
 	limits: CapacityLimits;
-	usage: { global: number; nodes: Readonly<Record<string, number>> };
+	usage: {
+		global: number;
+		nodes: Readonly<Record<string, number>>;
+		endpoints: Readonly<Record<string, number>>;
+		endpointHolders?: Readonly<Record<string, EndpointCapacityHolders>>;
+	};
 }): string {
 	if (input.state === "canceled") return "dispatch: admission canceled before a capacity slot opened";
+	if (input.endpointKey !== undefined) {
+		const endpointLimit = input.limits.endpoints[input.endpointKey];
+		const endpointActive = input.usage.endpoints[input.endpointKey] ?? 0;
+		if (endpointLimit !== undefined && endpointActive >= endpointLimit) {
+			const holders = input.usage.endpointHolders?.[input.endpointKey];
+			const occupancy =
+				holders === undefined
+					? "the supplied capacity snapshot does not attribute the occupied slots"
+					: describeEndpointCapacityHolders(holders);
+			return `dispatch: admission denied: endpoint '${endpointLabel(input.endpointKey)}' capacity reached (${endpointActive}/${endpointLimit} slots): ${occupancy}; collect in-flight runs or point workers at a second server`;
+		}
+	}
 	const nodeLimit = input.limits.nodes[input.nodeId];
 	const nodeActive = input.usage.nodes[input.nodeId] ?? 0;
 	const where =
@@ -142,7 +164,12 @@ function describeAdmissionFailure(input: {
 export function createCapacityAdmissionController(options: {
 	limits: () => CapacityLimits;
 	/** Live lease counts for the timeout message; defaults to the durable state file. */
-	usage?: () => { global: number; nodes: Readonly<Record<string, number>> };
+	usage?: () => {
+		global: number;
+		nodes: Readonly<Record<string, number>>;
+		endpoints: Readonly<Record<string, number>>;
+		endpointHolders?: Readonly<Record<string, EndpointCapacityHolders>>;
+	};
 	now?: () => number;
 	maxQueueSize?: number;
 	queueCeilingMs?: number;
@@ -175,7 +202,14 @@ export function createCapacityAdmissionController(options: {
 					admittedLease = request.value();
 					return true;
 				} catch (error) {
-					// Capacity is a wait, not a failure. Anything else fails the request.
+					// Endpoint saturation is a named refusal because waiting would keep a
+					// model request queued behind the same inference scheduler. Existing
+					// node and global admission retain their bounded wait behavior.
+					if (error instanceof Error && /endpoint '.*' capacity reached/u.test(error.message)) {
+						queue.fail(request.requestId, error);
+						return false;
+					}
+					// Node and global capacity can wait. Anything else fails the request.
 					if (error instanceof Error && /capacity reached/.test(error.message)) return false;
 					queue.fail(request.requestId, error instanceof Error ? error : new Error(String(error)));
 					return false;
@@ -229,12 +263,14 @@ export function createCapacityAdmissionController(options: {
 									memberId: input.reservation.memberId,
 									assignmentId: input.assignmentId,
 									nodeId: input.nodeId,
+									...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
 									limits: options.limits(),
 									nowMs: now(),
 								})
 							: acquireCapacityLease({
 									assignmentId: input.assignmentId,
 									nodeId: input.nodeId,
+									...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
 									limits: options.limits(),
 									nowMs: now(),
 								}),
@@ -246,6 +282,7 @@ export function createCapacityAdmissionController(options: {
 						describeAdmissionFailure({
 							state: outcome.state,
 							nodeId: input.nodeId,
+							...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
 							waitedMs: now() - queuedAt,
 							overdueAtQueueMs: queuedAt - input.deadlineAt,
 							queueDepth: queue.size(),

package/src/domains/dispatch/capacity-lease.ts

@@ -6,6 +6,7 @@ import { BIRTH_TOKEN_SOURCE_AVAILABLE, processAlive, processBirthToken } from ".
 import { FILE_LOCK_ACQUIRE_TIMEOUT_MS, withStateFileLockSync } from "../../core/state-file-lock.js";
 import { clioStateDir } from "../../core/xdg.js";
 import { atomicWrite } from "../../engine/session.js";
+import { endpointLabel, foregroundStreamUsage } from "../providers/endpoint-capacity.js";
 
 export { processBirthToken } from "../../core/process-identity.js";
 
@@ -30,6 +31,8 @@ export interface CapacityLease {
 	leaseId: string;
 	assignmentId: string;
 	nodeId: string;
+	/** Canonical inference endpoint. Absent only on leases written before endpoint capacity existed. */
+	endpointKey?: string;
 	/** Owner host. Absent only on records written before the field existed; those are read as this host. */
 	host?: string;
 	ownerPid: number;
@@ -43,6 +46,7 @@ export interface CapacityLease {
 export interface CapacityLimits {
 	global: number;
 	nodes: Readonly<Record<string, number>>;
+	endpoints: Readonly<Record<string, number>>;
 }
 export interface CapacityDrain {
 	requestedByPid: number;
@@ -81,6 +85,7 @@ function valid(value: unknown): value is CapacityLease {
 		typeof lease.leaseId === "string" &&
 		typeof lease.assignmentId === "string" &&
 		typeof lease.nodeId === "string" &&
+		(lease.endpointKey === undefined || typeof lease.endpointKey === "string") &&
 		(lease.host === undefined || typeof lease.host === "string") &&
 		Number.isInteger(lease.ownerPid) &&
 		typeof lease.processBirthToken === "string" &&
@@ -182,9 +187,14 @@ const MEMBER_STATUSES = new Set(["held", "consumed", "released"]);
  * rejected here as well: silently skipping an unreadable record would under-count
  * capacity and admit past the cap.
  */
-function heldReservationUsage(values: ReadonlyArray<unknown>): { global: number; nodes: Record<string, number> } {
+function heldReservationUsage(values: ReadonlyArray<unknown>): {
+	global: number;
+	nodes: Record<string, number>;
+	endpoints: Record<string, number>;
+} {
 	let global = 0;
 	const nodes: Record<string, number> = {};
+	const endpoints: Record<string, number> = {};
 	for (const value of values) {
 		if (typeof value !== "object" || value === null)
 			throw new Error("dispatch capacity store has invalid reservation records");
@@ -194,10 +204,11 @@ function heldReservationUsage(values: ReadonlyArray<unknown>): { global: number;
 		if (record.status !== "active") continue;
 		const byWave = new Map<number, number>();
 		const byNodeWave = new Map<string, Map<number, number>>();
+		const byEndpointWave = new Map<string, Map<number, number>>();
 		for (const raw of record.members) {
 			if (typeof raw !== "object" || raw === null)
 				throw new Error("dispatch capacity store has invalid reservation records");
-			const member = raw as { status?: unknown; wave?: unknown; nodeId?: unknown };
+			const member = raw as { status?: unknown; wave?: unknown; nodeId?: unknown; endpointKey?: unknown };
 			if (
 				typeof member.status !== "string" ||
 				!MEMBER_STATUSES.has(member.status) ||
@@ -211,13 +222,53 @@ function heldReservationUsage(values: ReadonlyArray<unknown>): { global: number;
 			const nodeWaves = byNodeWave.get(member.nodeId) ?? new Map<number, number>();
 			nodeWaves.set(wave, (nodeWaves.get(wave) ?? 0) + 1);
 			byNodeWave.set(member.nodeId, nodeWaves);
+			if (member.endpointKey !== undefined && typeof member.endpointKey !== "string")
+				throw new Error("dispatch capacity store has invalid reservation records");
+			if (typeof member.endpointKey === "string") {
+				const endpointWaves = byEndpointWave.get(member.endpointKey) ?? new Map<number, number>();
+				endpointWaves.set(wave, (endpointWaves.get(wave) ?? 0) + 1);
+				byEndpointWave.set(member.endpointKey, endpointWaves);
+			}
 		}
 		global += Math.max(0, ...byWave.values());
 		for (const [id, waves] of byNodeWave) nodes[id] = (nodes[id] ?? 0) + Math.max(0, ...waves.values());
+		for (const [key, waves] of byEndpointWave) endpoints[key] = (endpoints[key] ?? 0) + Math.max(0, ...waves.values());
 	}
-	return { global, nodes };
+	return { global, nodes, endpoints };
 }
-function assertCapacity(file: CapacityStateFile, nodeId: string, limits: CapacityLimits): void {
+
+export interface EndpointCapacityHolders {
+	leases: number;
+	reservations: number;
+	foregroundStreams: number;
+}
+
+/** Name the endpoint-capacity addends that are actually nonzero. */
+export function describeEndpointCapacityHolders(holders: EndpointCapacityHolders): string {
+	const parts: string[] = [];
+	const add = (count: number, singular: string, plural: string): void => {
+		if (count > 0) parts.push(`${count} ${count === 1 ? singular : plural}`);
+	};
+	add(holders.leases, "active lease", "active leases");
+	add(holders.reservations, "held reservation", "held reservations");
+	add(holders.foregroundStreams, "foreground stream", "foreground streams");
+	if (parts.length === 0) return "no active lease, held reservation, or foreground stream currently holds a slot";
+	const named =
+		parts.length === 1
+			? parts[0]
+			: parts.length === 2
+				? `${parts[0]} and ${parts[1]}`
+				: `${parts.slice(0, -1).join(", ")}, and ${parts.at(-1)}`;
+	const total = holders.leases + holders.reservations + holders.foregroundStreams;
+	return `${named} ${total === 1 ? "holds" : "hold"} ${total === 1 ? "the slot" : "the slots"}`;
+}
+
+function assertCapacity(
+	file: CapacityStateFile,
+	nodeId: string,
+	endpointKey: string | undefined,
+	limits: CapacityLimits,
+): void {
 	const held = heldReservationUsage(file.reservations);
 	const globalUsed = file.leases.length + held.global;
 	// The denial names the compliant next move, not just the gate. A model told
@@ -235,10 +286,28 @@ function assertCapacity(file: CapacityStateFile, nodeId: string, limits: Capacit
 		if (used >= nodeLimit)
 			throw new Error(`dispatch: admission denied: node '${nodeId}' capacity reached (${used}/${nodeLimit})`);
 	}
+	if (endpointKey !== undefined) {
+		const endpointLimit = limits.endpoints[endpointKey];
+		if (endpointLimit !== undefined) {
+			if (endpointLimit < 1)
+				throw new Error(`dispatch: admission denied: endpoint '${endpointLabel(endpointKey)}' capacity unavailable`);
+			const holders: EndpointCapacityHolders = {
+				leases: file.leases.filter((lease) => lease.endpointKey === endpointKey).length,
+				reservations: held.endpoints[endpointKey] ?? 0,
+				foregroundStreams: foregroundStreamUsage()[endpointKey] ?? 0,
+			};
+			const used = holders.leases + holders.reservations + holders.foregroundStreams;
+			if (used >= endpointLimit)
+				throw new Error(
+					`dispatch: admission denied: endpoint '${endpointLabel(endpointKey)}' capacity reached (${used}/${endpointLimit} slots): ${describeEndpointCapacityHolders(holders)}; collect in-flight runs or point workers at a second server`,
+				);
+		}
+	}
 }
 export function acquireCapacityLease(input: {
 	assignmentId: string;
 	nodeId: string;
+	endpointKey?: string;
 	limits: CapacityLimits;
 	nowMs?: number;
 	ttlMs?: number;
@@ -259,10 +328,12 @@ export function acquireCapacityLease(input: {
 			);
 		const existing = file.leases.find((lease) => lease.assignmentId === input.assignmentId);
 		if (existing) {
-			if (existing.nodeId !== input.nodeId) {
+			if (existing.nodeId !== input.nodeId || existing.endpointKey !== input.endpointKey) {
 				const without = { ...file, leases: file.leases.filter((lease) => lease !== existing) };
-				assertCapacity(without, input.nodeId, input.limits);
+				assertCapacity(without, input.nodeId, input.endpointKey, input.limits);
 				existing.nodeId = input.nodeId;
+				if (input.endpointKey === undefined) delete existing.endpointKey;
+				else existing.endpointKey = input.endpointKey;
 			}
 			existing.heartbeatAt = new Date(nowMs).toISOString();
 			existing.expiresAt = new Date(nowMs + (input.ttlMs ?? DEFAULT_CAPACITY_LEASE_TTL_MS)).toISOString();
@@ -270,7 +341,7 @@ export function acquireCapacityLease(input: {
 			return clone(existing);
 		}
 		input.onAcquiredUnderLock?.(file);
-		assertCapacity(file, input.nodeId, input.limits);
+		assertCapacity(file, input.nodeId, input.endpointKey, input.limits);
 		const token = input.processBirthToken ?? processBirthToken(input.ownerPid ?? process.pid);
 		if (!token) throw new Error("dispatch: cannot establish process birth token");
 		const at = new Date(nowMs).toISOString();
@@ -278,6 +349,7 @@ export function acquireCapacityLease(input: {
 			leaseId: `lease-${nowMs.toString(36)}-${randomBytes(6).toString("hex")}`,
 			assignmentId: input.assignmentId,
 			nodeId: input.nodeId,
+			...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
 			host: hostname(),
 			ownerPid: input.ownerPid ?? process.pid,
 			processBirthToken: token,
@@ -365,11 +437,28 @@ export function capacityDrain(nowMs = Date.now()): CapacityDrain | null {
 export function capacityLeaseUsage(options?: { nowMs?: number; probe?: LeaseOwnerProbe }): {
 	global: number;
 	nodes: Readonly<Record<string, number>>;
+	endpoints: Readonly<Record<string, number>>;
+	endpointHolders: Readonly<Record<string, EndpointCapacityHolders>>;
 } {
 	const leases = listCapacityLeases(options);
 	const nodes: Record<string, number> = {};
-	for (const lease of leases) nodes[lease.nodeId] = (nodes[lease.nodeId] ?? 0) + 1;
-	return { global: leases.length, nodes };
+	const foreground = foregroundStreamUsage();
+	const endpoints: Record<string, number> = { ...foreground };
+	const endpointHolders: Record<string, EndpointCapacityHolders> = Object.fromEntries(
+		Object.entries(foreground).map(([endpointKey, foregroundStreams]) => [
+			endpointKey,
+			{ leases: 0, reservations: 0, foregroundStreams },
+		]),
+	);
+	for (const lease of leases) {
+		nodes[lease.nodeId] = (nodes[lease.nodeId] ?? 0) + 1;
+		if (lease.endpointKey !== undefined) {
+			endpoints[lease.endpointKey] = (endpoints[lease.endpointKey] ?? 0) + 1;
+			const holders = endpointHolders[lease.endpointKey] ?? { leases: 0, reservations: 0, foregroundStreams: 0 };
+			endpointHolders[lease.endpointKey] = { ...holders, leases: holders.leases + 1 };
+		}
+	}
+	return { global: leases.length, nodes, endpoints, endpointHolders };
 }
 
 /**

package/src/domains/dispatch/contract.ts

@@ -13,6 +13,7 @@ import type { ApprovedAssignmentRoute } from "./route-approval.js";
 import type { RouteDecisionV1 } from "./route-decision.js";
 import type { RunEnvelope, RunLineage, RunNodeIdentity, RunPhaseDurations, RunReceipt, RunStatus } from "./types.js";
 import type { DispatchFailoverCandidate, JobSpec } from "./validation.js";
+import type { WriteBoundaryAttribution } from "./write-boundary.js";
 
 export interface DispatchRequest extends JobSpec {
 	/** Coordinator-owned result contract override for a fleet plan step. */
@@ -93,6 +94,8 @@ export interface DispatchPlanTaskResolution {
 	targetId: string;
 	wireModelId: string;
 	runtimeId: string;
+	/** Canonical inference scheduler identity and its independent request-slot bound. */
+	endpoint?: { key: string; label: string; limit: number };
 	node: RunNodeIdentity;
 	/** Effective thinking control for this route; null when the runtime has none. */
 	thinkingLevel: string | null;
@@ -209,6 +212,7 @@ export interface DispatchContract {
 			topology: ReservationTopology;
 			tasks: ReadonlyArray<{ memberId: string; wave: number; resolution: DispatchPlanTaskResolution }>;
 		}): DispatchReservationRecord;
+		release(ownerId: string): DispatchReservationRecord | null;
 		rollback(ownerId: string): DispatchReservationRecord | null;
 		rollbackUnconsumed(ownerId: string): DispatchReservationRecord | null;
 		get(ownerId: string): DispatchReservationRecord | null;
@@ -266,6 +270,13 @@ export interface DispatchContract {
 	 */
 	observedRunWrites?(runId: string): ReadonlyArray<string> | null;
 
+	/**
+	 * Full write-record witness, including durable downgrade causes. New callers
+	 * use this surface; observedRunWrites remains as the closed-list compatibility
+	 * view for integrations that only know paths or null.
+	 */
+	observedRunWriteAttribution?(runId: string): WriteBoundaryAttribution | null;
+
 	/** In-memory logical assignment state and complete finalized-attempt history. */
 	readonly assignments?: {
 		/** Live assignment, including its terminal promise and detailed attempt refs. */

package/src/domains/dispatch/execution-plan.ts

@@ -59,6 +59,8 @@ export interface ExecutionPlanAgentStep {
 	/** Exact per-step route defaults from a version 5 fleet contract. */
 	target?: string;
 	profile?: string;
+	/** Resolved inference scheduler bound used when waves are packed. */
+	endpoint?: { key: string; limit: number; foregroundHeld?: number };
 	/** Version 5 gate authoring and baseline execution facts. */
 	gate?: { path: string; commandId: string };
 	/** Version 5 dynamic planning facts. */
@@ -163,7 +165,12 @@ function canonicalSteps(steps: ReadonlyArray<ExecutionPlanStepInput>): Execution
 }
 
 export function executionPlanWaves(
-	steps: ReadonlyArray<{ id: string; dependencies: ReadonlyArray<string>; kind?: "agent" | "code" }>,
+	steps: ReadonlyArray<{
+		id: string;
+		dependencies: ReadonlyArray<string>;
+		kind?: "agent" | "code";
+		endpoint?: { key: string; limit: number; foregroundHeld?: number };
+	}>,
 	maxWorkers: number,
 ): string[][] {
 	if (!Number.isInteger(maxWorkers) || maxWorkers < 1)
@@ -191,11 +198,24 @@ export function executionPlanWaves(
 		// capacity lease, so they ride the first chunk of their ready set without
 		// displacing an agent step or forcing an extra wave.
 		const codeReady = ready.filter((step) => step.kind === "code").map((step) => step.id);
-		const agentReady = ready.filter((step) => step.kind !== "code").map((step) => step.id);
+		const agentReady = ready.filter((step) => step.kind !== "code");
 		const chunks: string[][] = [];
-		for (let offset = 0; offset < agentReady.length; offset += maxWorkers) {
-			chunks.push(agentReady.slice(offset, offset + maxWorkers));
+		let chunk: string[] = [];
+		let endpointCounts = new Map<string, number>();
+		for (const step of agentReady) {
+			const endpoint = step.endpoint;
+			const endpointLimit =
+				endpoint === undefined ? Number.POSITIVE_INFINITY : Math.max(1, endpoint.limit - (endpoint.foregroundHeld ?? 0));
+			const endpointFull = endpoint !== undefined && (endpointCounts.get(endpoint.key) ?? 0) >= endpointLimit;
+			if (chunk.length >= maxWorkers || endpointFull) {
+				chunks.push(chunk);
+				chunk = [];
+				endpointCounts = new Map<string, number>();
+			}
+			chunk.push(step.id);
+			if (endpoint !== undefined) endpointCounts.set(endpoint.key, (endpointCounts.get(endpoint.key) ?? 0) + 1);
 		}
+		if (chunk.length > 0) chunks.push(chunk);
 		if (chunks.length === 0) chunks.push([]);
 		chunks[0] = [...codeReady, ...(chunks[0] ?? [])];
 		for (const wave of chunks) {
@@ -317,6 +337,26 @@ export function compileExecutionPlan(input: ExecutionPlanInput): ExecutionPlan {
 	return { ...canonical, hash: createHash("sha256").update(JSON.stringify(canonical)).digest("hex") };
 }
 
+/** Recompile one approved graph after route preflight supplies endpoint bounds. */
+export function bindExecutionPlanEndpoints(
+	plan: ExecutionPlan,
+	bindings: Readonly<Record<string, { key: string; limit: number; foregroundHeld?: number } | undefined>>,
+): ExecutionPlan {
+	return compileExecutionPlan({
+		topology: plan.topology,
+		rootTask: plan.rootTask,
+		maxWorkers: plan.maxWorkers,
+		...(plan.writers === 1 ? { writers: 1 as const } : {}),
+		onFailure: plan.onFailure,
+		steps: plan.steps.map((step) => {
+			if (step.kind === "code") return step;
+			const endpoint = bindings[step.id];
+			return endpoint === undefined ? step : { ...step, endpoint: { ...endpoint } };
+		}),
+		loops: plan.loops,
+	});
+}
+
 /** Transitive dependency closure of one plan step. */
 export function executionPlanAncestors(plan: ExecutionPlan, stepId: string): ReadonlySet<string> {
 	const byId = new Map(plan.steps.map((step) => [step.id, step]));