@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/domains/dispatch/validation.ts

@@ -21,6 +21,7 @@ import {
 import { isExecutionRole } from "./execution-role.js";
 import { COMPETE_STANCES, type CompeteStance } from "./gate-role-prompts.js";
 import { type DispatchIntent, isDispatchIntent } from "./intent.js";
+import { classifyDispatchIntentCompatibility, dispatchIntentRefusals } from "./intent-compatibility.js";
 import { isRoutingIntent, type RoutingIntent } from "./routing-intent.js";
 import type {
 	DispatchRequestOrigin,
@@ -478,14 +479,21 @@ export function validateJobSpec(spec: unknown): Validated {
 			errors.push("writeRoots must be a non-empty array of non-empty strings");
 		}
 	}
-	if ("intent" in spec && spec.intent !== undefined && !isDispatchIntent(spec.intent)) {
-		errors.push("intent must be a normalized dispatch intent");
-	}
-	if (isDispatchIntent(spec.intent) && spec.intent.writeRoots.length > 0 && Array.isArray(spec.writeRoots)) {
-		const jobCwd = typeof spec.cwd === "string" && spec.cwd.length > 0 ? spec.cwd : process.cwd();
-		const legacy = [...new Set(spec.writeRoots.map((root) => resolvePathBoundary(jobCwd, String(root))))].sort();
-		const declared = [...new Set(spec.intent.writeRoots.map((root) => resolvePathBoundary(jobCwd, root)))].sort();
-		if (JSON.stringify(legacy) !== JSON.stringify(declared)) errors.push("intent_write_roots_contradiction");
+	// One owner for the typed-intent migration rules (#163). Every dispatch
+	// producer reaches a worker through this validator, so classifying here is
+	// what makes the compatibility table true of the fleet, CLI, ACP, and
+	// extension paths rather than only of the model-facing tool.
+	if ("intent" in spec) {
+		for (const refusal of dispatchIntentRefusals(
+			classifyDispatchIntentCompatibility({
+				intent: spec.intent,
+				...(spec.writeRoots !== undefined ? { writeRoots: spec.writeRoots } : {}),
+				...(spec.autonomy !== undefined ? { autonomy: spec.autonomy } : {}),
+				...(typeof spec.cwd === "string" && spec.cwd.length > 0 ? { cwd: spec.cwd } : {}),
+			}),
+		)) {
+			errors.push(refusal.message);
+		}
 	}
 
 	if ("requestOrigin" in spec && spec.requestOrigin !== undefined) {
@@ -696,6 +704,8 @@ function isValidProtectedArtifactRemap(value: unknown): value is ProtectedArtifa
 
 const VALID_GATE_ROLES = new Set(["builder", "reviewer", "candidate", "judge", "member", "synthesis"]);
 const VALID_GATE_VERDICTS = new Set(["pass", "fail", "revise"]);
+const VALID_WORKTREE_BACKENDS = new Set(["herdr", "native"]);
+const VALID_WORKTREE_FALLBACKS = new Set(["mux-unavailable", "mux-operation-failed"]);
 const VALID_PLAN_TOPOLOGIES = new Set([
 	"parallel",
 	"sequential",
@@ -724,6 +734,20 @@ function isValidGate(value: unknown): value is RunGateProvenance {
 	if (value.verdict !== undefined && (typeof value.verdict !== "string" || !VALID_GATE_VERDICTS.has(value.verdict))) {
 		return false;
 	}
+	if (value.worktree !== undefined) {
+		if (!isPlainObject(value.worktree)) return false;
+		if (typeof value.worktree.backend !== "string" || !VALID_WORKTREE_BACKENDS.has(value.worktree.backend)) return false;
+		if (typeof value.worktree.path !== "string" || !path.isAbsolute(value.worktree.path)) return false;
+		if (typeof value.worktree.branch !== "string" || value.worktree.branch.length === 0) return false;
+		if (value.worktree.workspaceId !== undefined && typeof value.worktree.workspaceId !== "string") return false;
+		if (
+			value.worktree.fallback !== undefined &&
+			(typeof value.worktree.fallback !== "string" || !VALID_WORKTREE_FALLBACKS.has(value.worktree.fallback))
+		) {
+			return false;
+		}
+		if (value.worktree.backend === "herdr" && typeof value.worktree.workspaceId !== "string") return false;
+	}
 	return true;
 }
 
@@ -734,6 +758,7 @@ function cloneGate(gate: RunGateProvenance): RunGateProvenance {
 		cycle: gate.cycle,
 		...(gate.subjects !== undefined ? { subjects: gate.subjects.map((subject) => ({ ...subject })) } : {}),
 		...(gate.verdict !== undefined ? { verdict: gate.verdict } : {}),
+		...(gate.worktree !== undefined ? { worktree: { ...gate.worktree } } : {}),
 	};
 }
 

package/src/domains/eval/compare/compare.ts

@@ -3,6 +3,7 @@ import { assertComparableTrackedMetricSources } from "../run-compare.js";
 import type { EvalArtifactV4 } from "../schema/artifact.js";
 import {
 	type EvalServingConfigurationV1,
+	evalServingConfigurationOf,
 	renderEvalServingConfiguration,
 	sameEvalServingConfiguration,
 } from "../schema/serving.js";
@@ -90,8 +91,8 @@ export function compareEvalArtifactsV4(
 ): EvalCompareV4Summary {
 	const baselineTokens = baseline.summary.tokens;
 	const candidateTokens = candidate.summary.tokens;
-	const baselineServing = servingConfigurationOf(baseline);
-	const candidateServing = servingConfigurationOf(candidate);
+	const baselineServing = evalServingConfigurationOf(baseline);
+	const candidateServing = evalServingConfigurationOf(candidate);
 	const configDrift = !sameEvalServingConfiguration(baselineServing, candidateServing);
 	if (configDrift && options.allowConfigDrift !== true) {
 		throw new EvalServingConfigurationDriftError(baselineServing, candidateServing);
@@ -330,20 +331,6 @@ function metricComparison(
 	};
 }
 
-function servingConfigurationOf(artifact: EvalArtifactV4): EvalServingConfigurationV1 {
-	return (
-		artifact.servingConfiguration ?? {
-			targetId: artifact.matrix.target,
-			runtimeId: null,
-			modelId: artifact.matrix.model,
-			serverBuild: null,
-			total_slots: null,
-			thinkingLevel: artifact.matrix.thinking,
-			compiledPromptHash: null,
-		}
-	);
-}
-
 function normalizeMetricFilter(metric: string | undefined): string | undefined {
 	if (metric === undefined) return undefined;
 	const trimmed = metric.trim();

package/src/domains/eval/inventory.ts

@@ -0,0 +1,113 @@
+/**
+ * Bounded newest-first listing of the eval reports this installation stored.
+ *
+ * The store has always been addressed by id: `eval report <evalId>` and
+ * `eval compare <a> <b>` both require the operator to already know which report
+ * they want. Nothing enumerated the directory, so a surface that wants to offer
+ * the choice had to invent the enumeration. This is that enumeration, and it is
+ * a store concern rather than a wire concern: it decides which files are in the
+ * window and hands back parsed artifacts, and says nothing about which of their
+ * fields may leave the host.
+ */
+
+import { readdir } from "node:fs/promises";
+import { loadEvalArtifactV4 } from "./artifacts/store.js";
+import type { EvalArtifactV4 } from "./schema/artifact.js";
+import { evalRoot } from "./store.js";
+
+/**
+ * The exact shape `createEvalId` mints: an ISO stamp with its separators
+ * stripped, the first eight characters of the suite hash, and a random suffix.
+ */
+const EVAL_ID_PATTERN = /^eval-(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(\d{3})Z-([0-9a-f]{8})-([0-9a-f]{12})$/u;
+
+export interface EvalStoredReport {
+	readonly evalId: string;
+	/**
+	 * The instant the run started, read back out of the id.
+	 *
+	 * Null unless the id is one this harness minted and its embedded suite-hash
+	 * prefix agrees with the suite the artifact names. An artifact has no
+	 * timestamp field of its own, so the id is the only record of when it ran,
+	 * and a stamp read off an id that does not otherwise match its contents is
+	 * not a fact worth reporting.
+	 */
+	readonly startedAt: string | null;
+	readonly artifact: EvalArtifactV4;
+}
+
+export interface EvalStoreListing {
+	/** False when the installation has no eval store at all, which reads differently from an empty one. */
+	readonly available: boolean;
+	/** Reports on disk before the window bound. */
+	readonly stored: number;
+	readonly reports: readonly EvalStoredReport[];
+	/**
+	 * Files inside the window the current parser refused.
+	 *
+	 * Counted rather than dropped silently. Routing accepts artifact v4 only, so
+	 * a retired shape still on disk is a real thing in this store, and a listing
+	 * that quietly skipped it would report a smaller store than the operator has.
+	 */
+	readonly unreadable: number;
+}
+
+/** The stamp an id carries, without checking it against anything. */
+function idStamp(evalId: string): { startedAt: string; suiteHashPrefix: string } | null {
+	const match = EVAL_ID_PATTERN.exec(evalId);
+	if (match === null) return null;
+	const [, year, month, day, hour, minute, second, millisecond, suiteHashPrefix] = match;
+	const startedAt = `${year}-${month}-${day}T${hour}:${minute}:${second}.${millisecond}Z`;
+	const parsed = new Date(startedAt);
+	if (Number.isNaN(parsed.getTime()) || parsed.toISOString() !== startedAt) return null;
+	return { startedAt, suiteHashPrefix: suiteHashPrefix as string };
+}
+
+/** Newest first. An id this harness did not mint sorts oldest rather than throwing. */
+function byNewest(left: string, right: string): number {
+	const leftStamp = idStamp(left)?.startedAt ?? "";
+	const rightStamp = idStamp(right)?.startedAt ?? "";
+	if (leftStamp !== rightStamp) return leftStamp < rightStamp ? 1 : -1;
+	return left < right ? 1 : -1;
+}
+
+export async function listEvalReports(dataDir: string, limit: number): Promise<EvalStoreListing> {
+	let entries: string[];
+	try {
+		entries = await readdir(evalRoot(dataDir));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return { available: false, stored: 0, reports: [], unreadable: 0 };
+		}
+		throw error;
+	}
+	const ids = entries
+		.filter((entry) => entry.endsWith(".json"))
+		.map((entry) => entry.slice(0, -".json".length))
+		.sort(byNewest);
+	const reports: EvalStoredReport[] = [];
+	let unreadable = 0;
+	for (const evalId of ids.slice(0, limit)) {
+		let artifact: EvalArtifactV4;
+		try {
+			artifact = await loadEvalArtifactV4(dataDir, evalId);
+		} catch {
+			unreadable += 1;
+			continue;
+		}
+		// The id inside the file is authoritative. A file whose stem disagrees with
+		// it was renamed or copied in, and the two names it now answers to are not
+		// the same report.
+		if (artifact.evalId !== evalId) {
+			unreadable += 1;
+			continue;
+		}
+		const stamp = idStamp(evalId);
+		reports.push({
+			evalId,
+			startedAt: stamp !== null && artifact.suite.hash.startsWith(stamp.suiteHashPrefix) ? stamp.startedAt : null,
+			artifact,
+		});
+	}
+	return { available: true, stored: ids.length, reports, unreadable };
+}

package/src/domains/eval/schema/serving.ts

@@ -30,6 +30,37 @@ export function parseEvalServingConfigurationV1(value: unknown, source: string):
 	};
 }
 
+/**
+ * The serving facts an artifact was produced under.
+ *
+ * An artifact written before the observation existed has no record of its own,
+ * so the matrix it declared is the best available reading and the missing
+ * fields stay null rather than being invented. This lives beside
+ * `sameEvalServingConfiguration` because the two are one rule: what a
+ * comparison reads, and when it decides two readings agree. Anything asking
+ * whether two eval runs are comparable must go through both, or it is answering
+ * a different question from the one `eval compare` answers.
+ *
+ * The parameter is structural rather than `EvalArtifactV4` so this module stays
+ * free of an import cycle through `schema/artifact.ts`.
+ */
+export function evalServingConfigurationOf(artifact: {
+	readonly servingConfiguration?: EvalServingConfigurationV1;
+	readonly matrix: { readonly target: string; readonly model: string | null; readonly thinking: string | null };
+}): EvalServingConfigurationV1 {
+	return (
+		artifact.servingConfiguration ?? {
+			targetId: artifact.matrix.target,
+			runtimeId: null,
+			modelId: artifact.matrix.model,
+			serverBuild: null,
+			total_slots: null,
+			thinkingLevel: artifact.matrix.thinking,
+			compiledPromptHash: null,
+		}
+	);
+}
+
 export function sameEvalServingConfiguration(
 	left: EvalServingConfigurationV1,
 	right: EvalServingConfigurationV1,

package/src/domains/evidence/store.ts

@@ -205,6 +205,11 @@ function parseOverview(value: unknown, source: string): EvidenceOverview {
 	const totals = readTotals(value.totals, `${source}.totals`);
 	const tags = readStringArray(value, source, "tags") as EvidenceOverview["tags"];
 	const files = readStringArray(value, source, "files");
+	// Additive since the redaction pass landed, so a bundle written before it
+	// simply has no count. Reading it optionally is what keeps the declared
+	// field reachable: it was written to disk and then dropped on the way back.
+	const redactionCount =
+		typeof value.redactionCount === "number" && Number.isFinite(value.redactionCount) ? value.redactionCount : undefined;
 	return {
 		version: 1,
 		evidenceId,
@@ -224,6 +229,7 @@ function parseOverview(value: unknown, source: string): EvidenceOverview {
 		totals,
 		tags,
 		files,
+		...(redactionCount === undefined ? {} : { redactionCount }),
 	};
 }
 

package/src/domains/memory/index.ts

@@ -91,7 +91,6 @@ export {
 	runTaskMemoryPolicy,
 	TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS,
 	TASK_MEMORY_POLICY_MAX_OPERATIONS,
-	TASK_MEMORY_POLICY_MODEL_MAX_OUTPUT_TOKENS,
 	type TaskMemoryEnvelope,
 	type TaskMemoryModelClient,
 	type TaskMemoryModelRequest,

package/src/domains/memory/task-memory-policy.ts

@@ -17,15 +17,7 @@ export const TASK_MEMORY_POLICY_MAX_OPERATIONS = 8;
  * test pins the pair. Two numbers for one setting means any path that misses
  * the settings object silently gets the one nobody chose.
  */
-export const TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS = 30_000;
-/**
- * The envelope itself needs a few hundred tokens. The rest is headroom for a
- * model that reasons despite thinking being requested off: measured preambles on
- * a 9B local route ran past 1,800 tokens before the first `<operations>` byte,
- * and a budget that runs out mid-thought yields an empty response, no bank
- * writes, and no way for the operator to tell that from a deliberate silence.
- */
-export const TASK_MEMORY_POLICY_MODEL_MAX_OUTPUT_TOKENS = 4_000;
+export const TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS = 60_000;
 
 export interface TaskMemoryTrajectoryStep {
 	step: number;
@@ -142,6 +134,8 @@ export type TaskMemoryPolicyReason =
 	| "no_consumer"
 	/** A step was already in flight, so this boundary's triggers stayed pending. */
 	| "step_in_flight"
+	/** Consecutive model deadlines degraded this session to the free rules tier. */
+	| "llm_timeout_backoff"
 	/** Rules tier: the turn ended with no repeated failure worth reporting. */
 	| "no_repeated_failure"
 	/** Rules tier: compaction reactivation found no knowledge entries to restore. */
@@ -171,6 +165,8 @@ export interface TaskMemoryPolicyInput {
 	trajectory: ReadonlyArray<TaskMemoryTrajectoryStep>;
 	deterministicTrigger: boolean;
 	maxTokens: number;
+	/** Capability-derived completion budget; defaults to the visible reminder budget. */
+	modelMaxTokens?: number;
 	timeoutMs?: number;
 	/** Phase one still applies; phase two is suppressed when another memory reminder already won this boundary. */
 	suppressIntervention?: boolean;
@@ -297,7 +293,7 @@ export async function runTaskMemoryPolicy(
 		const completion = client.complete({
 			systemPrompt: MEMORY_INTERVENTION_SYSTEM_PROMPT,
 			userPrompt,
-			maxTokens: TASK_MEMORY_POLICY_MODEL_MAX_OUTPUT_TOKENS,
+			maxTokens: positiveInteger(input.modelMaxTokens, input.maxTokens),
 			signal: controller.signal,
 		});
 		const timeout = new Promise<typeof timeoutMarker>((resolve) => {

package/src/domains/memory/task-memory-telemetry.ts

@@ -226,6 +226,7 @@ const REASONS = new Set<TaskMemoryPolicyReason>([
 	"no_client",
 	"no_consumer",
 	"step_in_flight",
+	"llm_timeout_backoff",
 	"no_repeated_failure",
 	"bank_empty",
 ]);

package/src/domains/middleware/memory-intervention.ts

@@ -31,8 +31,10 @@ import type { MiddlewareEffect, MiddlewareHookInput } from "./types.js";
 
 export const MEMORY_INTERVENTION_REGISTRATION_ID = "observer.memory-intervention";
 export const MEMORY_INTERVENTION_DEFAULT_WINDOW_STEPS = 8;
-export const MEMORY_INTERVENTION_DEFAULT_MAX_TOKENS = 400;
+export const MEMORY_INTERVENTION_DEFAULT_MAX_TOKENS = 2_000;
 export const MEMORY_INTERVENTION_DEFAULT_EVERY_N_TOOLS = 10;
+/** Two full deadlines are enough evidence to stop spending this session's endpoint. */
+export const MEMORY_INTERVENTION_TIMEOUT_BACKOFF_THRESHOLD = 2;
 
 export const MEMORY_INTERVENTION_ACTIVITY_LIMIT = 20;
 
@@ -76,6 +78,8 @@ export interface MemoryInterventionDeps {
 	everyNTools?: number;
 	/** Lazily resolves the explicitly configured background role. Null means rules-only. */
 	getModelClient?: () => TaskMemoryModelClient | null;
+	/** Completion budget derived from the resolved background model capability. */
+	getModelMaxTokens?: (configuredMaxTokens: number) => number;
 	/**
 	 * True when the background target's inference endpoint is already serving the
 	 * chat target's stream. A memory step then either queues behind the operator's
@@ -187,6 +191,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	let outstandingStep: Promise<void> = Promise.resolve();
 	let rulesInjectedSincePromptedStep = false;
 	let annotatedSinceTurnEnd = false;
+	let consecutiveLlmTimeouts = 0;
 
 	return {
 		id: MEMORY_INTERVENTION_REGISTRATION_ID,
@@ -388,27 +393,32 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		// produced and the policy vocabulary has no value for a step that never ran.
 		let telemetryDecision: TaskMemoryTelemetryDecision | null = null;
 		try {
-			const client = deps.getModelClient?.() ?? null;
-			if (client === null) {
-				promptedResult = silent("no_client");
-			} else if (deps.backgroundEndpointBusy?.() === true) {
-				tier = "llm";
-				promptedStepTier = tier;
-				promptedResult = silent("endpoint_busy");
-				telemetryDecision = "dropped";
+			if (consecutiveLlmTimeouts >= MEMORY_INTERVENTION_TIMEOUT_BACKOFF_THRESHOLD) {
+				promptedResult = silent("llm_timeout_backoff");
 			} else {
-				tier = "llm";
-				promptedStepTier = tier;
-				promptedResult = await runTaskMemoryPolicy(deps.bank, client, {
-					task: input.task?.trim() || currentTask,
-					trajectory: [...trajectory],
-					deterministicTrigger: input.deterministicTrigger,
-					maxTokens: live.maxTokens,
-					...(input.suppressIntervention === undefined ? {} : { suppressIntervention: input.suppressIntervention }),
-					previousReminder: lastInjectedMessage,
-					timeoutMs: live.timeoutMs,
-					...(deps.onEnvelope === undefined ? {} : { onEnvelope: deps.onEnvelope }),
-				});
+				const client = deps.getModelClient?.() ?? null;
+				if (client === null) {
+					promptedResult = silent("no_client");
+				} else if (deps.backgroundEndpointBusy?.() === true) {
+					tier = "llm";
+					promptedStepTier = tier;
+					promptedResult = silent("endpoint_busy");
+					telemetryDecision = "dropped";
+				} else {
+					tier = "llm";
+					promptedStepTier = tier;
+					promptedResult = await runTaskMemoryPolicy(deps.bank, client, {
+						task: input.task?.trim() || currentTask,
+						trajectory: [...trajectory],
+						deterministicTrigger: input.deterministicTrigger,
+						maxTokens: live.maxTokens,
+						modelMaxTokens: positiveInteger(deps.getModelMaxTokens?.(live.maxTokens), live.maxTokens),
+						...(input.suppressIntervention === undefined ? {} : { suppressIntervention: input.suppressIntervention }),
+						previousReminder: lastInjectedMessage,
+						timeoutMs: live.timeoutMs,
+						...(deps.onEnvelope === undefined ? {} : { onEnvelope: deps.onEnvelope }),
+					});
+				}
 			}
 		} catch (error) {
 			// runTaskMemoryPolicy resolves its own failures, so reaching here means
@@ -426,6 +436,8 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 				error: error instanceof Error ? error.message : "resolving the background model client failed",
 			});
 		}
+		if (tier === "llm" && promptedResult.decision === "timeout") consecutiveLlmTimeouts += 1;
+		else if (tier === "llm" && telemetryDecision !== "dropped") consecutiveLlmTimeouts = 0;
 		lastDecision = promptedResult.decision;
 		if (promptedResult.usage !== null) {
 			try {