@iowarp/clio-coder 0.4.2 → 0.4.4

package/src/domains/dispatch/admission.ts

@@ -107,6 +107,27 @@ const PUMP_MAX_MS = 500;
  * waiting or dispatching fewer runs is the way past it, so it retries the same
  * shape and burns the deadline again.
  */
+export function foregroundEndpointBlock(input: {
+	endpointKey?: string;
+	limits: CapacityLimits;
+	usage: {
+		endpoints: Readonly<Record<string, number>>;
+		endpointHolders?: Readonly<Record<string, EndpointCapacityHolders>>;
+	};
+}): string | null {
+	if (input.endpointKey === undefined) return null;
+	const limit = input.limits.endpoints[input.endpointKey];
+	const active = input.usage.endpoints[input.endpointKey] ?? 0;
+	const holders = input.usage.endpointHolders?.[input.endpointKey];
+	if (limit === undefined || active < limit || !holders || holders.foregroundStreams < 1) return null;
+	return [
+		`dispatch: admission denied: endpoint '${endpointLabel(input.endpointKey)}' cannot open a worker slot`,
+		` while ${describeEndpointCapacityHolders(holders)} (${active}/${limit} slots).`,
+		" The foreground agent cannot release its slot until this tool call returns, so waiting here would deadlock.",
+		" Point workers at a second endpoint or raise this target's maxConcurrentRequests to the server's actual slot count.",
+	].join("");
+}
+
 function describeAdmissionFailure(input: {
 	state: "canceled" | "timed_out";
 	nodeId: string;
@@ -245,6 +266,14 @@ export function createCapacityAdmissionController(options: {
 	const controller: CapacityAdmissionController = {
 		async admit(input) {
 			if (draining) throw new Error("dispatch: admission denied: this process is shutting down");
+			const limits = options.limits();
+			const usage = options.usage?.() ?? capacityLeaseUsage({ nowMs: now() });
+			const foregroundBlock = foregroundEndpointBlock({
+				...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
+				limits,
+				usage,
+			});
+			if (foregroundBlock !== null) throw new Error(foregroundBlock);
 			const queuedAt = now();
 			const requestId = `admit-${queuedAt.toString(36)}-${randomBytes(5).toString("hex")}`;
 			pending.set(input.assignmentId, requestId);

package/src/domains/dispatch/agent-candidates.ts

@@ -32,6 +32,7 @@ export type AgentTaskType =
 	| "docs"
 	| "config"
 	| "research"
+	| "world_knowledge"
 	| "unknown";
 export type AgentTaskComplexity = "trivial" | "simple" | "moderate" | "complex";
 export type AgentTaskDomain = "frontend" | "backend" | "infra" | "data" | "security" | "general";
@@ -53,6 +54,10 @@ const TASK_TYPE_RULES: ReadonlyArray<readonly [AgentTaskType, RegExp]> = [
 	["debug", /\b(debug|fix|bug|crash|failure|broken|regression)\b/i],
 	["refactor", /\b(refactor|clean ?up|restructure|rename|extract|simplify)\b/i],
 	["config", /\b(config|configuration|settings|setup|install|ci pipeline|workflow file)\b/i],
+	[
+		"world_knowledge",
+		/\b(?:open[- ]world|ecosystem landscape|industry landscape|state of (?:the )?art|current alternatives|latest alternatives|advisory second opinion)\b/i,
+	],
 	["research", /\b(research|investigate|explore|survey|compare|find out)\b/i],
 	["code_read", /\b(read|explain|understand|summarize|describe|walk through|map|locate|trace)\b/i],
 	["code_write", /\b(write|implement|add|create|build|develop|introduce)\b/i],
@@ -202,6 +207,11 @@ const TASK_SIGNALS: Readonly<
 > = {
 	code_read: { ids: ["scout"], tags: ["reconnaissance", "symbols", "codewiki"], contracts: ["scout-report"] },
 	research: { ids: ["researcher"], tags: ["sources", "external-context", "papers"], contracts: ["research-report"] },
+	world_knowledge: {
+		ids: ["world-knowledge"],
+		tags: ["open-world", "ecosystem", "current-context", "second-opinion"],
+		contracts: ["world-knowledge-report"],
+	},
 	code_review: { ids: ["verifier"], tags: ["review", "verification"], contracts: ["verifier-report"] },
 	debug: { ids: ["debugger"], tags: ["debugging", "root-cause"], contracts: ["debugger-report"] },
 	test: { ids: ["verifier", "tester"], tags: ["tests", "validation", "regression"], contracts: ["verifier-report"] },

package/src/domains/dispatch/budget-envelope.ts

@@ -28,6 +28,17 @@ export interface BudgetEnvelopeReason {
 
 export interface RunToolBudgetEnvelope {
 	version: 1;
+	enforcement:
+		| {
+				classification: "native-per-tool";
+				perTool: "enforced";
+				clioControls: ReadonlyArray<"tool-calls" | "read-reserve" | "synthesis" | "attempt-cap">;
+		  }
+		| {
+				classification: "external-one-shot";
+				perTool: "unobserved-not-enforced";
+				clioControls: ReadonlyArray<"single-launch" | "wall-clock" | "output-cap" | "cancellation" | "result-contract">;
+		  };
 	policy: {
 		recipeId: string;
 		default: AgentBudgetPhase & { synthesis: boolean };
@@ -39,6 +50,15 @@ export interface RunToolBudgetEnvelope {
 	reasons: ReadonlyArray<BudgetEnvelopeReason>;
 }
 
+const NATIVE_CLIO_CONTROLS = ["tool-calls", "read-reserve", "synthesis", "attempt-cap"] as const;
+const EXTERNAL_CLIO_CONTROLS = [
+	"single-launch",
+	"wall-clock",
+	"output-cap",
+	"cancellation",
+	"result-contract",
+] as const;
+
 export type BudgetAdmissionDenialCode =
 	| "exact-recipe-policy"
 	| "recipe-maximum"
@@ -94,6 +114,8 @@ export function cloneDispatchBudgetRequest(value: unknown, prefix = "budget"): D
 }
 
 function freezeEnvelope(envelope: RunToolBudgetEnvelope): RunToolBudgetEnvelope {
+	Object.freeze(envelope.enforcement.clioControls);
+	Object.freeze(envelope.enforcement);
 	Object.freeze(envelope.policy.default);
 	Object.freeze(envelope.policy.maximum);
 	Object.freeze(envelope.policy);
@@ -172,6 +194,7 @@ export interface ResolveToolBudgetEnvelopeInput {
 	hasReadTool: boolean;
 	retry: boolean;
 	revision: boolean;
+	enforcement?: "native-per-tool" | "external-one-shot";
 }
 
 /** Resolve the one immutable envelope used by admission, enforcement, and evidence. */
@@ -253,6 +276,18 @@ export function resolveToolBudgetEnvelope(input: ResolveToolBudgetEnvelopeInput)
 	const authoredMaximum = input.policy.maximum ?? input.policy;
 	return freezeEnvelope({
 		version: 1,
+		enforcement:
+			input.enforcement === "external-one-shot"
+				? {
+						classification: "external-one-shot",
+						perTool: "unobserved-not-enforced",
+						clioControls: [...EXTERNAL_CLIO_CONTROLS],
+					}
+				: {
+						classification: "native-per-tool",
+						perTool: "enforced",
+						clioControls: [...NATIVE_CLIO_CONTROLS],
+					},
 		policy: {
 			recipeId: input.recipeId,
 			default: {
@@ -297,7 +332,11 @@ export function formatEffectiveBudget(envelope: RunToolBudgetEnvelope): string {
 	const revision = budget.revision
 		? `, result revision ${budget.revision.toolCalls}/${budget.revision.readReserve}`
 		: "";
-	return `${budget.toolCalls}/${budget.readReserve}${revision}, lifetime cap ${budget.hardCap}, synthesis=${budget.synthesis ? "on" : "off"}`;
+	const enforcement =
+		envelope.enforcement.classification === "external-one-shot"
+			? "external one-shot; per-tool unobserved/not enforced"
+			: "native per-tool enforced";
+	return `${budget.toolCalls}/${budget.readReserve}${revision}, lifetime cap ${budget.hardCap}, synthesis=${budget.synthesis ? "on" : "off"}; ${enforcement}`;
 }
 
 export function formatBudgetReasons(envelope: RunToolBudgetEnvelope): string {
@@ -314,6 +353,10 @@ const BUDGET_REASON_CODES: ReadonlySet<string> = new Set<BudgetEnvelopeReasonCod
 	"revision-growth-denied",
 ]);
 
+function isExactStringArray(value: unknown[], expected: readonly string[]): boolean {
+	return value.length === expected.length && value.every((item, index) => item === expected[index]);
+}
+
 /** Safely project an envelope that crossed a persistence or event boundary. */
 export function cloneRunToolBudgetEnvelope(value: unknown): RunToolBudgetEnvelope | undefined {
 	try {
@@ -373,8 +416,50 @@ export function cloneRunToolBudgetEnvelope(value: unknown): RunToolBudgetEnvelop
 			}
 			reasons.push({ code: reason.code as BudgetEnvelopeReasonCode, detail: reason.detail });
 		}
+		const enforcement = (() => {
+			if (value.enforcement === undefined) {
+				return {
+					classification: "native-per-tool" as const,
+					perTool: "enforced" as const,
+					clioControls: [...NATIVE_CLIO_CONTROLS],
+				};
+			}
+			if (!isRecord(value.enforcement) || !Array.isArray(value.enforcement.clioControls)) return null;
+			if (
+				Object.keys(value.enforcement).some(
+					(key) => key !== "classification" && key !== "perTool" && key !== "clioControls",
+				)
+			) {
+				return null;
+			}
+			if (
+				value.enforcement.classification === "external-one-shot" &&
+				value.enforcement.perTool === "unobserved-not-enforced" &&
+				isExactStringArray(value.enforcement.clioControls, EXTERNAL_CLIO_CONTROLS)
+			) {
+				return {
+					classification: "external-one-shot" as const,
+					perTool: "unobserved-not-enforced" as const,
+					clioControls: [...EXTERNAL_CLIO_CONTROLS],
+				};
+			}
+			if (
+				value.enforcement.classification === "native-per-tool" &&
+				value.enforcement.perTool === "enforced" &&
+				isExactStringArray(value.enforcement.clioControls, NATIVE_CLIO_CONTROLS)
+			) {
+				return {
+					classification: "native-per-tool" as const,
+					perTool: "enforced" as const,
+					clioControls: [...NATIVE_CLIO_CONTROLS],
+				};
+			}
+			return null;
+		})();
+		if (enforcement === null) return undefined;
 		return freezeEnvelope({
 			version: 1,
+			enforcement,
 			policy: {
 				recipeId,
 				default: { ...defaultPhase, synthesis: value.policy.default.synthesis },

package/src/domains/dispatch/capability-match.ts

@@ -76,6 +76,7 @@ const REPORTING_CONTRACT_KINDS: ReadonlySet<ResultContract["kind"]> = new Set([
 	"scout-report",
 	"verifier-report",
 	"research-report",
+	"world-knowledge-report",
 	"provenance-report",
 	"debugger-report",
 	"oracle-report",

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

@@ -481,6 +481,23 @@ export function capacityLeaseUsage(options?: { nowMs?: number; probe?: LeaseOwne
 	return { global: leases.length, nodes, endpoints, endpointHolders };
 }
 
+/** Coherent current endpoint occupancy, including held reservation waves.
+ * The caller still owns admission; process-local streams are not global leases.
+ */
+export function endpointCapacityUsage(): Readonly<Record<string, number>> {
+	return withStateFileLockSync(capacityStateLockPath(), () => {
+		const file = readCapacityStateUnsafe();
+		reclaim(file, Date.now(), defaultProbe);
+		const held = heldReservationUsage(file.reservations);
+		const usage: Record<string, number> = { ...foregroundStreamUsage() };
+		for (const [key, count] of Object.entries(held.endpoints)) usage[key] = (usage[key] ?? 0) + count;
+		for (const lease of file.leases) {
+			if (lease.endpointKey !== undefined) usage[lease.endpointKey] = (usage[lease.endpointKey] ?? 0) + 1;
+		}
+		return usage;
+	});
+}
+
 /**
  * Per-node lease counts for display and for advisory placement spreading. Every
  * read takes the admission state lock, so a render loop or a multi-node

package/src/domains/dispatch/code-step.ts

@@ -107,6 +107,8 @@ export interface CodeStepRecord {
 export interface CodeStepOutcome {
 	report: CodeReportResult;
 	record: CodeStepRecord;
+	/** Stdout retained within the shared capture cap, for structured command judgments. */
+	stdout: string;
 	/** Canonical JSON of the report; this is the text that crosses plan edges. */
 	output: string;
 }
@@ -210,6 +212,7 @@ interface SpawnOutcome {
 	signal: string | null;
 	timedOut: boolean;
 	captured: Buffer;
+	stdout: Buffer;
 	outputBytes: number;
 	spawnError: string | null;
 }
@@ -226,6 +229,7 @@ async function spawnCommand(input: CodeStepRunInput, cwd: string, argv: Readonly
 		});
 		reportCommitAttributionDiagnostic(attribution.diagnostic);
 		const chunks: Buffer[] = [];
+		const stdoutChunks: Buffer[] = [];
 		let outputBytes = 0;
 		let captured = 0;
 		let settled = false;
@@ -239,16 +243,17 @@ async function spawnCommand(input: CodeStepRunInput, cwd: string, argv: Readonly
 			// whole tree rather than orphaning a test runner's children.
 			detached: process.platform !== "win32",
 		});
-		const collect = (chunk: Buffer): void => {
+		const collect = (chunk: Buffer, stdout: boolean): void => {
 			outputBytes += chunk.length;
 			if (captured >= CODE_STEP_CAPTURE_MAX_BYTES) return;
 			const room = CODE_STEP_CAPTURE_MAX_BYTES - captured;
 			const slice = chunk.length <= room ? chunk : chunk.subarray(0, room);
 			chunks.push(slice);
+			if (stdout) stdoutChunks.push(slice);
 			captured += slice.length;
 		};
-		child.stdout?.on("data", collect);
-		child.stderr?.on("data", collect);
+		child.stdout?.on("data", (chunk: Buffer) => collect(chunk, true));
+		child.stderr?.on("data", (chunk: Buffer) => collect(chunk, false));
 		const kill = (): void => {
 			if (child.pid === undefined) return;
 			try {
@@ -276,6 +281,7 @@ async function spawnCommand(input: CodeStepRunInput, cwd: string, argv: Readonly
 				signal,
 				timedOut,
 				captured: Buffer.concat(chunks),
+				stdout: Buffer.concat(stdoutChunks),
 				outputBytes,
 				spawnError,
 			});
@@ -317,6 +323,7 @@ export async function runCodeStep(input: CodeStepRunInput): Promise<CodeStepOutc
 				signal: null,
 				timedOut: false,
 				captured: Buffer.from(`${CODE_STEP_EMPTY_DIFF_MESSAGE}\n`, "utf8"),
+				stdout: Buffer.alloc(0),
 				outputBytes: 0,
 				spawnError: null,
 			}
@@ -383,5 +390,5 @@ export async function runCodeStep(input: CodeStepRunInput): Promise<CodeStepOutc
 		artifactPaths,
 		reportDigest: codeReportDigest(report),
 	};
-	return { report, record, output: canonicalCodeReport(report) };
+	return { report, record, stdout: spawned.stdout.toString("utf8"), output: canonicalCodeReport(report) };
 }

package/src/domains/dispatch/contract.ts

@@ -1,4 +1,7 @@
 import type { SafeEventBus } from "../../core/event-bus.js";
+import type { DeclaredCheckKind } from "../../tools/verify/catalog.js";
+import type { NumericTolerance } from "../../tools/verify/numeric.js";
+import type { PerfBudgetSpec } from "../../tools/verify/perf.js";
 import type { ResultContract } from "../agents/result-contract.js";
 import type { AgentAutomationAuthority, AgentSpec } from "../agents/spec.js";
 import type { CostProvenance } from "../providers/index.js";
@@ -15,6 +18,19 @@ import type { RunEnvelope, RunLineage, RunNodeIdentity, RunPhaseDurations, RunRe
 import type { DispatchFailoverCandidate, JobSpec } from "./validation.js";
 import type { WriteBoundaryAttribution } from "./write-boundary.js";
 
+export interface ResolvedVerificationCheck {
+	check: string;
+	argv: ReadonlyArray<string>;
+	cwd: string;
+	timeoutMs: number;
+	/** Absent means `command`, the exit-code check every receipt carried before kinds existed. */
+	kind?: DeclaredCheckKind;
+	/** Sealed at admission with the reference as an absolute path. */
+	numeric?: { reference: string; tolerance: NumericTolerance };
+	/** Sealed at admission with the baseline as an absolute path. */
+	perf?: { budget?: PerfBudgetSpec; baseline?: string; tolerance?: { relative?: number } };
+}
+
 export interface DispatchRequest extends JobSpec {
 	/** Coordinator-owned result contract override for a fleet plan step. */
 	resultContractOverride?: ResultContract;
@@ -33,13 +49,13 @@ export interface DispatchRequest extends JobSpec {
 	runIdHint?: string;
 	/** Parent checkout frozen by plan approval for task worktree application. */
 	taskWorktreeDestination?: string;
-	/** Admission-resolved commands. Model text never enters these argv vectors. */
-	resolvedVerification?: ReadonlyArray<{
-		check: string;
-		argv: ReadonlyArray<string>;
-		cwd: string;
-		timeoutMs: number;
-	}>;
+	/**
+	 * Admission-resolved commands. Model text never enters these argv vectors.
+	 * A numeric-compare or perf-budget check also seals its kind and the
+	 * absolute reference or baseline path it will judge against, so host
+	 * verification runs exactly the check the catalog declared at admission.
+	 */
+	resolvedVerification?: ReadonlyArray<ResolvedVerificationCheck>;
 	/**
 	 * Semantic role this request's first attempt runs under. Derived once by
 	 * `execution-role.ts` at request construction, never authored by a model, and
@@ -79,6 +95,14 @@ export interface DispatchRequest extends JobSpec {
 	 * validation projection strips it like the reservation and ledger refs.
 	 */
 	parentToolCallId?: string;
+	/**
+	 * Decision refs (`<interviewId>/<key>`) active on the parent session's
+	 * decision board when this request was built. Sealed by the orchestrator
+	 * from the board snapshot, never by model arguments: the validation
+	 * projection strips it like `reservation` and `ledger`. Copied onto the run
+	 * envelope and receipt so a receipt names the decisions it worked under.
+	 */
+	decisionRefs?: ReadonlyArray<string>;
 }
 
 /** Internal, non-serializable admission hook for transactional resource owners. */
@@ -86,6 +110,12 @@ export interface DispatchAdmissionObserver {
 	onAdmitted(run: { runId: string; pid: number | null; runtimeKind: RunEnvelope["runtimeKind"] }): void;
 }
 
+/** Invocation-owned admission bounds; never serialized into model-authored requests. */
+export interface DispatchPreparationOptions {
+	signal?: AbortSignal;
+	deadlineAt?: number;
+}
+
 /** Side-effect-free effective routing used to construct a dispatch approval artifact. */
 export interface DispatchPlanTaskResolution {
 	agentId: string;
@@ -225,6 +255,7 @@ export interface DispatchContract {
 	dispatch(
 		req: DispatchRequest,
 		observer?: DispatchAdmissionObserver,
+		preparation?: DispatchPreparationOptions,
 	): Promise<{
 		runId: string;
 		events: AsyncIterableIterator<unknown>;
@@ -232,7 +263,10 @@ export interface DispatchContract {
 	}>;
 
 	/** Spawn a group of dispatches and expose one merged batch event stream. */
-	dispatchBatch(reqs: ReadonlyArray<DispatchRequest>): Promise<{
+	dispatchBatch(
+		reqs: ReadonlyArray<DispatchRequest>,
+		preparation?: DispatchPreparationOptions,
+	): Promise<{
 		batchId: string;
 		/** Logical work ids, one per request in admission order. */
 		assignmentIds: ReadonlyArray<string>;

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

@@ -13,6 +13,8 @@ import {
 export interface ExecutionStepResult extends ExecutionHandoff {
 	succeeded: boolean;
 	integrityValid: boolean;
+	/** Decision refs the step's sealed receipt was made under; absent for code steps and decision-free runs. */
+	decisionRefs?: ReadonlyArray<string>;
 	/**
 	 * The step changed the workspace outside its declared boundary. Sealed by
 	 * the orchestrator after the fact, never by the step: a run that reports on