@iowarp/clio-coder 0.4.4 → 0.4.6

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

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { BIRTH_TOKEN_SOURCE_AVAILABLE, processAlive, processBirthToken } from "../../core/process-identity.js";
-import { FILE_LOCK_ACQUIRE_TIMEOUT_MS, withStateFileLockSync } from "../../core/state-file-lock.js";
+import { FILE_LOCK_ACQUIRE_TIMEOUT_MS, withStateFileLock, 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";
@@ -187,7 +187,10 @@ 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>): {
+function heldReservationUsage(
+	values: ReadonlyArray<unknown>,
+	transferring?: { ownerId: string; memberId: string },
+): {
 	global: number;
 	nodes: Record<string, number>;
 	endpoints: Record<string, number>;
@@ -198,13 +201,24 @@ function heldReservationUsage(values: ReadonlyArray<unknown>): {
 	for (const value of values) {
 		if (typeof value !== "object" || value === null)
 			throw new Error("dispatch capacity store has invalid reservation records");
-		const record = value as { status?: unknown; members?: unknown };
+		const record = value as { ownerId?: unknown; status?: unknown; members?: unknown };
 		if (typeof record.status !== "string" || !RESERVATION_STATUSES.has(record.status) || !Array.isArray(record.members))
 			throw new Error("dispatch capacity store has invalid reservation records");
 		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>>();
+		let transferringWave: number | undefined;
+		if (transferring !== undefined && record.ownerId === transferring.ownerId) {
+			const member = record.members.find(
+				(raw) => typeof raw === "object" && raw !== null && raw.memberId === transferring.memberId,
+			);
+			// Transfer validates and consumes the member under this same lock.
+			// A retry's existing lease also carries that validated identity.
+			if (member?.status !== "consumed" || !Number.isInteger(member.wave))
+				throw new Error("dispatch: capacity transfer requires a consumed reservation member");
+			transferringWave = member.wave;
+		}
 		for (const raw of record.members) {
 			if (typeof raw !== "object" || raw === null)
 				throw new Error("dispatch capacity store has invalid reservation records");
@@ -218,12 +232,16 @@ function heldReservationUsage(values: ReadonlyArray<unknown>): {
 				throw new Error("dispatch capacity store has invalid reservation records");
 			if (member.status !== "held") continue;
 			const wave = member.wave as number;
+			if (member.endpointKey !== undefined && typeof member.endpointKey !== "string")
+				throw new Error("dispatch capacity store has invalid reservation records");
+			// Waves reuse the owner's reserved slots. Only its same-wave peers
+			// compete with this lease; other waves stay held in durable state and
+			// still count at their full peak against every other owner.
+			if (transferringWave !== undefined && wave !== transferringWave) continue;
 			byWave.set(wave, (byWave.get(wave) ?? 0) + 1);
 			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);
@@ -288,8 +306,9 @@ function assertCapacity(
 	nodeId: string,
 	endpointKey: string | undefined,
 	limits: CapacityLimits,
+	transferring?: { ownerId: string; memberId: string },
 ): void {
-	const held = heldReservationUsage(file.reservations);
+	const held = heldReservationUsage(file.reservations, transferring);
 	const globalUsed = file.leases.length + held.global;
 	// The denial names the compliant next move, not just the gate. A model told
 	// only that it is full re-dispatches with a different agent; the work it is
@@ -350,7 +369,15 @@ export function acquireCapacityLease(input: {
 		if (existing) {
 			if (existing.nodeId !== input.nodeId || existing.endpointKey !== input.endpointKey) {
 				const without = { ...file, leases: file.leases.filter((lease) => lease !== existing) };
-				assertCapacity(without, input.nodeId, input.endpointKey, input.limits);
+				assertCapacity(
+					without,
+					input.nodeId,
+					input.endpointKey,
+					input.limits,
+					existing.reservationOwnerId !== null && existing.reservationMemberId !== null
+						? { ownerId: existing.reservationOwnerId, memberId: existing.reservationMemberId }
+						: undefined,
+				);
 				existing.nodeId = input.nodeId;
 				if (input.endpointKey === undefined) delete existing.endpointKey;
 				else existing.endpointKey = input.endpointKey;
@@ -361,7 +388,7 @@ export function acquireCapacityLease(input: {
 			return clone(existing);
 		}
 		input.onAcquiredUnderLock?.(file);
-		assertCapacity(file, input.nodeId, input.endpointKey, input.limits);
+		assertCapacity(file, input.nodeId, input.endpointKey, input.limits, input.reservation);
 		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();
@@ -454,13 +481,34 @@ export function capacityDrain(nowMs = Date.now()): CapacityDrain | null {
 		return drain;
 	});
 }
+/** Synchronous usage read for admission planners whose host API cannot yield. */
 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);
+	return withStateFileLockSync(capacityStateLockPath(), () => capacityLeaseUsageUnsafe(options));
+}
+
+/** Fresh usage for async admission: wait for the same lock without blocking callbacks. */
+export function capacityLeaseUsageAsync(options?: {
+	nowMs?: number;
+	probe?: LeaseOwnerProbe;
+}): Promise<ReturnType<typeof capacityLeaseUsage>> {
+	return withStateFileLock(capacityStateLockPath(), () => capacityLeaseUsageUnsafe(options));
+}
+
+/** The caller holds the capacity state lock for this read and any reclamation write. */
+function capacityLeaseUsageUnsafe(options?: {
+	nowMs?: number;
+	probe?: LeaseOwnerProbe;
+}): ReturnType<typeof capacityLeaseUsage> {
+	const file = readCapacityStateUnsafe();
+	const before = file.leases.length;
+	reclaim(file, options?.nowMs ?? Date.now(), options?.probe ?? defaultProbe);
+	if (before !== file.leases.length) writeCapacityStateUnsafe(file);
+	const leases = file.leases;
 	const nodes: Record<string, number> = {};
 	const foreground = foregroundStreamUsage();
 	const endpoints: Record<string, number> = { ...foreground };
@@ -524,13 +572,3 @@ export function createNodeLeaseUsageReader(options: {
 		return cache.nodes[nodeId] ?? 0;
 	};
 }
-
-function listCapacityLeases(options?: { nowMs?: number; probe?: LeaseOwnerProbe }): ReadonlyArray<CapacityLease> {
-	return withStateFileLockSync(capacityStateLockPath(), () => {
-		const file = readCapacityStateUnsafe();
-		const before = file.leases.length;
-		reclaim(file, options?.nowMs ?? Date.now(), options?.probe ?? defaultProbe);
-		if (before !== file.leases.length) writeCapacityStateUnsafe(file);
-		return file.leases.map(clone);
-	});
-}

package/src/domains/dispatch/contract.ts

@@ -10,7 +10,7 @@ import type { AssignmentId, DispatchAssignment } from "./assignment.js";
 import type { DurableAssignmentRecord } from "./assignment-store.js";
 import type { DetachedBatchRecord, RegisterDetachedBatchInput } from "./batch-store.js";
 import type { RunToolBudgetEnvelope } from "./budget-envelope.js";
-import type { ExecutionRole } from "./execution-role.js";
+import type { DispatchResultSummaryAllowance, ExecutionRole } from "./execution-role.js";
 import type { DispatchReservationRecord, ReservationTopology } from "./reservation-store.js";
 import type { ApprovedAssignmentRoute } from "./route-approval.js";
 import type { RouteDecisionV1 } from "./route-decision.js";
@@ -34,6 +34,12 @@ export interface ResolvedVerificationCheck {
 export interface DispatchRequest extends JobSpec {
 	/** Coordinator-owned result contract override for a fleet plan step. */
 	resultContractOverride?: ResultContract;
+	/**
+	 * Caller's inline-summary allowance for a mutation-report worker, applied
+	 * by `dispatchResultContract`. Parsed and range-checked at the tool
+	 * boundary; never model-authored past that point.
+	 */
+	resultSummary?: DispatchResultSummaryAllowance;
 	/** Gate path whose post-run hash is sealed into this step's receipt. */
 	fleetGateReceipt?: { path: string };
 	/** Orchestrator-prepared task worktree state. Model arguments cannot author it. */
@@ -84,7 +90,7 @@ export interface DispatchRequest extends JobSpec {
 	 * strips the ledger tool from this run's admitted surface.
 	 */
 	ledger?: { id: string; sequence: number };
-	/** Absolute root-assignment deadline derived once from the approved duration. */
+	/** Explicit absolute root-assignment deadline, preserved through retries; absent for advisory estimates. */
 	assignmentDeadlineAt?: number;
 	/**
 	 * Tool call the caller was executing when it built this request. Stamped by
@@ -112,6 +118,8 @@ export interface DispatchAdmissionObserver {
 
 /** Invocation-owned admission bounds; never serialized into model-authored requests. */
 export interface DispatchPreparationOptions {
+	/** Host ancestry for publication; kept separate from logical assignment/retry identity. */
+	hostRun?: { readonly runId: string; readonly lineage: Readonly<RunLineage> };
 	signal?: AbortSignal;
 	deadlineAt?: number;
 }

package/src/domains/dispatch/event-pump.ts

@@ -17,6 +17,7 @@
  */
 
 import { truncateUtf8 } from "../../tools/truncate-utf8.js";
+import { type ResultContract, resultContractOutputBytes } from "../agents/result-contract.js";
 import type { RunReceiptOutput } from "./types.js";
 
 /** Bounded replay capacity for the external consumer tee. */
@@ -137,15 +138,33 @@ export function startDispatchEventPump(
  * Byte bound on the assistant output text sealed into a receipt. Large enough
  * for a substantive final answer, small enough that receipts stay cheap to
  * read and render; overflow is recorded explicitly via `truncated`/`bytes`.
+ * A run whose result contract implies a larger conforming result raises its
+ * own bound through `workerOutputCaptureBytes`; this is the floor.
  */
 export const WORKER_OUTPUT_MAX_BYTES = 8192;
 const WORKER_OUTPUT_TRUNCATION_MARKER = "\n[worker output truncated]";
 
+/**
+ * The capture bound for one run. A mutation report with a 16 KB summary
+ * allowance cannot be sealed in 8 KB, and clipping it produced a receipt whose
+ * only readable fact was "result must be valid JSON" for a result that was
+ * valid (#350). The contract's own whole-result bound wins when it is larger;
+ * every other contract keeps the floor.
+ */
+export function workerOutputCaptureBytes(contract: ResultContract | null | undefined): number {
+	return Math.max(WORKER_OUTPUT_MAX_BYTES, resultContractOutputBytes(contract) ?? 0);
+}
+
 export interface WorkerOutputCapture {
 	observe(event: unknown): void;
 	snapshot(): RunReceiptOutput | undefined;
 }
 
+export interface WorkerOutputCaptureOptions {
+	/** Byte bound for the sealed text; defaults to WORKER_OUTPUT_MAX_BYTES. */
+	maxBytes?: number;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -184,9 +203,9 @@ export function durableAssistantTextFromEvent(event: unknown): string {
 	return assistantTextFromContent(event.message.content);
 }
 
-function boundedOutput(state: RunReceiptOutput["state"], text: string): RunReceiptOutput {
+function boundedOutput(state: RunReceiptOutput["state"], text: string, maxBytes: number): RunReceiptOutput {
 	const bytes = Buffer.byteLength(text, "utf8");
-	const bounded = truncateUtf8(text, WORKER_OUTPUT_MAX_BYTES, WORKER_OUTPUT_TRUNCATION_MARKER);
+	const bounded = truncateUtf8(text, maxBytes, WORKER_OUTPUT_TRUNCATION_MARKER);
 	return { state, text: bounded, bytes, truncated: bounded !== text };
 }
 
@@ -199,9 +218,11 @@ function boundedOutput(state: RunReceiptOutput["state"], text: string): RunRecei
  * partial and are discarded when their message completes. A run that ends
  * with unflushed deltas (abort, stall, kill mid-message) therefore snapshots
  * as `partial`, never as final. Accumulation is bounded in memory by the same
- * byte cap the receipt uses; overflow only marks truncation.
+ * byte cap the receipt uses; overflow only marks truncation. The cap is the
+ * run's own (`workerOutputCaptureBytes`), never below the module floor.
  */
-export function createWorkerOutputCapture(): WorkerOutputCapture {
+export function createWorkerOutputCapture(options: WorkerOutputCaptureOptions = {}): WorkerOutputCapture {
+	const maxBytes = Math.max(WORKER_OUTPUT_MAX_BYTES, Math.floor(options.maxBytes ?? WORKER_OUTPUT_MAX_BYTES));
 	let finalText: string | null = null;
 	let partialText = "";
 	let partialBytes = 0;
@@ -229,14 +250,14 @@ export function createWorkerOutputCapture(): WorkerOutputCapture {
 			const delta = assistantEvent.delta;
 			if (typeof delta !== "string" || delta.length === 0) return;
 			partialBytes += Buffer.byteLength(delta, "utf8");
-			if (partialStored < WORKER_OUTPUT_MAX_BYTES) {
+			if (partialStored < maxBytes) {
 				partialText += delta;
 				partialStored += Buffer.byteLength(delta, "utf8");
 			}
 		},
 		snapshot(): RunReceiptOutput | undefined {
 			if (partialBytes > 0 && partialText.trim().length > 0) {
-				const bounded = truncateUtf8(partialText.trim(), WORKER_OUTPUT_MAX_BYTES, WORKER_OUTPUT_TRUNCATION_MARKER);
+				const bounded = truncateUtf8(partialText.trim(), maxBytes, WORKER_OUTPUT_TRUNCATION_MARKER);
 				return {
 					state: "partial",
 					text: bounded,
@@ -244,7 +265,7 @@ export function createWorkerOutputCapture(): WorkerOutputCapture {
 					truncated: bounded !== partialText.trim() || partialBytes > partialStored,
 				};
 			}
-			if (finalText !== null) return boundedOutput("final", finalText);
+			if (finalText !== null) return boundedOutput("final", finalText, maxBytes);
 			return undefined;
 		},
 	};

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

@@ -14,7 +14,7 @@
  * clock, no engine state.
  */
 
-import type { ResultContract } from "../agents/result-contract.js";
+import { type ResultContract, withResultSummaryAllowance } from "../agents/result-contract.js";
 import type { AgentCapabilityClass } from "../agents/spec.js";
 
 /**
@@ -181,10 +181,57 @@ export function gateDeciderAgentId(requested: string | undefined): string {
  * the recipe postcondition on the slot sealed a contract failure on every
  * correct synthesis and burned the configured retries reproducing it.
  */
-export function appliesRecipeResultContract(gateRole: GateTopologyRole | undefined): boolean {
+function appliesRecipeResultContract(gateRole: GateTopologyRole | undefined): boolean {
 	return gateRole !== "reviewer" && gateRole !== "judge" && gateRole !== "synthesis";
 }
 
+/** A caller's summary allowance for one dispatch, with where it was set. */
+export interface DispatchResultSummaryAllowance {
+	maxBytes: number;
+	/**
+	 * `task` is an explicit setting on this one assignment; `batch` is the
+	 * shared default every member of a batch or pipeline inherits. Only the
+	 * explicit form can be a caller error on a recipe with no summary field.
+	 */
+	scope: "task" | "batch";
+}
+
+/** The request fields the applied result contract is resolved from. */
+export interface DispatchResultContractRequest {
+	agentId: string;
+	gate?: { role?: GateTopologyRole } | undefined;
+	resultContractOverride?: ResultContract;
+	resultSummary?: DispatchResultSummaryAllowance;
+}
+
+/**
+ * The one resolution of the contract a run is validated and sealed against.
+ * Every reader (the worker spec, the capture bound, the seal) calls this so
+ * the worker repairs against exactly the contract the receipt will name.
+ *
+ * Precedence: a gate role that answers its topology has no recipe contract at
+ * all; otherwise the coordinator's override, else the seated recipe's. A
+ * caller's summary allowance then applies to a mutation report only. A
+ * topology-owned override (ballot, plan, artifact) and a batch-level default
+ * inherited by a non-mutation step ignore it, because the allowance was never
+ * about that step. An explicit per-task allowance on a recipe with no summary
+ * field is a caller error and fails here, before any model boots.
+ */
+export function dispatchResultContract(
+	req: DispatchResultContractRequest,
+	recipe: { resultContract: ResultContract } | null | undefined,
+): ResultContract | undefined {
+	if (!appliesRecipeResultContract(req.gate?.role)) return undefined;
+	const base = req.resultContractOverride ?? recipe?.resultContract;
+	const allowance = req.resultSummary;
+	if (allowance === undefined) return base;
+	if (base?.kind === "mutation-report") return withResultSummaryAllowance(base, allowance.maxBytes);
+	if (req.resultContractOverride !== undefined || allowance.scope === "batch") return base;
+	throw new Error(
+		`dispatch: result_summary_max_bytes applies only to a mutation-report result contract; agent '${req.agentId}' declares ${base === undefined ? "no result contract" : base.kind}`,
+	);
+}
+
 /** The route dimensions a gate correlation is measured across. */
 export interface RouteCorrelationFacts {
 	agentId: string;

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

@@ -11,6 +11,8 @@ import {
 } from "./execution-plan.js";
 
 export interface ExecutionStepResult extends ExecutionHandoff {
+	/** Coordinator-owned immutable recovery reference captured before loop repair. */
+	workspaceCheckpoint?: string;
 	succeeded: boolean;
 	integrityValid: boolean;
 	/** Decision refs the step's sealed receipt was made under; absent for code steps and decision-free runs. */