@iowarp/clio-coder 0.3.0 → 0.3.2

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

@@ -0,0 +1,66 @@
+import type { EvalArtifactV4 } from "../schema/artifact.js";
+import type { EvalMetricAssertion, EvalSuiteThresholdsV2 } from "../schema/suite.js";
+import { resolveMetricAssertion } from "./thresholds.js";
+
+export interface EvalGateFailure {
+	assertion: EvalMetricAssertion;
+	actual: number | string | boolean | null;
+	/** True when the metric could not be resolved from the artifact. */
+	unresolved: boolean;
+	/** The run this failure was read from; absent for whole-artifact readings. */
+	taskId?: string;
+	repeatIndex?: number;
+}
+
+export interface EvalGateResult {
+	pass: boolean;
+	failures: EvalGateFailure[];
+}
+
+/**
+ * A gate fails closed: a fail threshold whose condition holds is a failure,
+ * and so is a threshold whose metric the artifact cannot resolve. A typoed or
+ * uncollected metric must never let a release gate pass silently.
+ *
+ * Whole-artifact metrics (`result.pass`, `latency.wallMs`, `tokens.total`,
+ * `summary.*`) are read once. Everything else is a per-run reading, and the
+ * gate covers every run: one run that trips the condition fails the gate, and
+ * so does one run the metric could not be read from. Reading them per run is
+ * what lets the failure name the offending run and its value instead of
+ * collapsing the matrix into a single aggregate nobody can act on.
+ */
+export function evaluateGate(artifact: EvalArtifactV4, thresholds: EvalSuiteThresholdsV2): EvalGateResult {
+	const failures: EvalGateFailure[] = [];
+	for (const assertion of thresholds.fail) {
+		const whole = resolveMetricAssertion(assertion, {}, artifact);
+		if (!whole.unresolved) {
+			if (whole.holds) failures.push({ assertion, actual: whole.actual, unresolved: false });
+			continue;
+		}
+		if (artifact.results.length === 0) {
+			failures.push({ assertion, actual: null, unresolved: true });
+			continue;
+		}
+		for (const result of artifact.results) {
+			const perRun = resolveMetricAssertion(assertion, result.metrics);
+			if (!perRun.unresolved && !perRun.holds) continue;
+			failures.push({
+				assertion,
+				actual: perRun.actual,
+				unresolved: perRun.unresolved,
+				taskId: result.taskId,
+				repeatIndex: result.repeatIndex,
+			});
+		}
+	}
+	return { pass: failures.length === 0, failures };
+}
+
+/** One operator-facing line per gate failure, naming the run when there is one. */
+export function renderGateFailure(failure: EvalGateFailure): string {
+	const run = failure.taskId === undefined ? "" : ` [${failure.taskId}#${failure.repeatIndex ?? 0}]`;
+	const { metric, op, value } = failure.assertion;
+	return failure.unresolved
+		? `  ${metric}${run}: unresolved metric (fail closed)\n`
+		: `  ${metric} ${op} ${JSON.stringify(value)}${run}: actual ${JSON.stringify(failure.actual)}\n`;
+}

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

@@ -0,0 +1,92 @@
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import type { EvalArtifactV4 } from "../schema/artifact.js";
+import type { EvalMetricAssertion, EvalSuiteThresholdsV2 } from "../schema/suite.js";
+
+export function loadThresholds(path: string): EvalSuiteThresholdsV2 {
+	const parsed = parseYaml(readFileSync(path, "utf8")) as unknown;
+	if (isRecord(parsed) && Array.isArray(parsed.fail)) return { fail: parsed.fail as EvalMetricAssertion[] };
+	if (isRecord(parsed) && isRecord(parsed.thresholds) && Array.isArray(parsed.thresholds.fail)) {
+		return { fail: parsed.thresholds.fail as EvalMetricAssertion[] };
+	}
+	throw new Error(`invalid thresholds file: ${path}`);
+}
+
+export interface EvalAssertionResolution {
+	actual: number | string | boolean | null;
+	/** True when neither the metric map nor the artifact carries a value for this metric. */
+	unresolved: boolean;
+	/** True when the comparison holds against the resolved value. */
+	holds: boolean;
+}
+
+/**
+ * Resolve one assertion against a metric map, keeping "the metric was missing"
+ * distinct from "the comparison did not hold". Both readings fail closed, but
+ * they fail for different reasons and a report that conflates them tells an
+ * operator nothing about whether the check ran.
+ */
+export function resolveMetricAssertion(
+	assertion: EvalMetricAssertion,
+	metrics: Readonly<Record<string, unknown>>,
+	artifact?: EvalArtifactV4,
+): EvalAssertionResolution {
+	const actual = metricValue(assertion.metric, metrics, artifact);
+	return { actual, unresolved: actual === null, holds: comparisonHolds(assertion, actual) };
+}
+
+export function evaluateMetricAssertion(
+	assertion: EvalMetricAssertion,
+	metrics: Readonly<Record<string, unknown>>,
+	artifact?: EvalArtifactV4,
+): boolean {
+	return comparisonHolds(assertion, metricValue(assertion.metric, metrics, artifact));
+}
+
+function comparisonHolds(assertion: EvalMetricAssertion, actual: number | string | boolean | null): boolean {
+	switch (assertion.op) {
+		case "lt":
+			return typeof actual === "number" && typeof assertion.value === "number" && actual < assertion.value;
+		case "lte":
+			return typeof actual === "number" && typeof assertion.value === "number" && actual <= assertion.value;
+		case "gt":
+			return typeof actual === "number" && typeof assertion.value === "number" && actual > assertion.value;
+		case "gte":
+			return typeof actual === "number" && typeof assertion.value === "number" && actual >= assertion.value;
+		case "eq":
+			return actual === assertion.value;
+		case "neq":
+			return actual !== assertion.value;
+	}
+}
+
+export function metricValue(
+	metric: string,
+	metrics: Readonly<Record<string, unknown>>,
+	artifact?: EvalArtifactV4,
+): number | string | boolean | null {
+	if (metric in metrics) return metrics[metric] as number | string | boolean | null;
+	if (artifact !== undefined) {
+		if (metric === "result.pass") return artifact.summary.failed === 0;
+		if (metric === "latency.wallMs") return artifact.summary.wallTimeMs;
+		// An unmeasured artifact answers null rather than 0, so a numeric
+		// threshold on token spend fails closed instead of passing on absence.
+		if (metric === "tokens.total") return artifact.summary.tokens.measured ? artifact.summary.tokens.total : null;
+		if (metric.startsWith("summary.")) return summaryValue(artifact, metric.slice("summary.".length));
+	}
+	return null;
+}
+
+/** Resolve a dotted path under artifact.summary to a scalar, else null. */
+function summaryValue(artifact: EvalArtifactV4, path: string): number | string | boolean | null {
+	let current: unknown = artifact.summary;
+	for (const segment of path.split(".")) {
+		if (!isRecord(current) || !(segment in current)) return null;
+		current = current[segment];
+	}
+	return typeof current === "number" || typeof current === "string" || typeof current === "boolean" ? current : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/domains/eval/harness-metrics.ts

@@ -0,0 +1,62 @@
+import type { RunReceipt } from "../dispatch/types.js";
+import type { EvalCommandResult, EvalHarnessMetrics, EvalRunRecord } from "./types.js";
+
+export const ZERO_EVAL_HARNESS_METRICS: EvalHarnessMetrics = {
+	receiptCount: 0,
+	toolCalls: 0,
+	retries: 0,
+	safetyBlocks: 0,
+	correctionLatencyMs: 0,
+	validationEvidence: 0,
+};
+
+export function evalHarnessMetricsFromCommands(commands: ReadonlyArray<EvalCommandResult>): EvalHarnessMetrics {
+	return {
+		...ZERO_EVAL_HARNESS_METRICS,
+		validationEvidence: commands.filter(
+			(command) => command.phase === "verifier" && command.exitCode === 0 && !command.timedOut,
+		).length,
+	};
+}
+
+export function evalHarnessMetricsFromReceipt(
+	receipt: RunReceipt,
+	extras: Partial<Pick<EvalHarnessMetrics, "retries" | "correctionLatencyMs" | "validationEvidence">> = {},
+): EvalHarnessMetrics {
+	return {
+		receiptCount: 1,
+		toolCalls: receipt.toolCalls,
+		retries: extras.retries ?? 0,
+		safetyBlocks: receipt.safety?.decisions.blocked ?? 0,
+		correctionLatencyMs: extras.correctionLatencyMs ?? 0,
+		validationEvidence: extras.validationEvidence ?? 0,
+	};
+}
+
+export function sumEvalHarnessMetrics(records: ReadonlyArray<EvalRunRecord>): EvalHarnessMetrics {
+	return records.reduce((total, record) => addEvalHarnessMetrics(total, record.harness), {
+		...ZERO_EVAL_HARNESS_METRICS,
+	});
+}
+
+export function addEvalHarnessMetrics(left: EvalHarnessMetrics, right: EvalHarnessMetrics): EvalHarnessMetrics {
+	return {
+		receiptCount: left.receiptCount + right.receiptCount,
+		toolCalls: left.toolCalls + right.toolCalls,
+		retries: left.retries + right.retries,
+		safetyBlocks: left.safetyBlocks + right.safetyBlocks,
+		correctionLatencyMs: left.correctionLatencyMs + right.correctionLatencyMs,
+		validationEvidence: left.validationEvidence + right.validationEvidence,
+	};
+}
+
+export function subtractEvalHarnessMetrics(left: EvalHarnessMetrics, right: EvalHarnessMetrics): EvalHarnessMetrics {
+	return {
+		receiptCount: left.receiptCount - right.receiptCount,
+		toolCalls: left.toolCalls - right.toolCalls,
+		retries: left.retries - right.retries,
+		safetyBlocks: left.safetyBlocks - right.safetyBlocks,
+		correctionLatencyMs: left.correctionLatencyMs - right.correctionLatencyMs,
+		validationEvidence: left.validationEvidence - right.validationEvidence,
+	};
+}

package/src/domains/eval/index.ts

@@ -0,0 +1,66 @@
+export {
+	addEvalHarnessMetrics,
+	evalHarnessMetricsFromCommands,
+	evalHarnessMetricsFromReceipt,
+	subtractEvalHarnessMetrics,
+	sumEvalHarnessMetrics,
+	ZERO_EVAL_HARNESS_METRICS,
+} from "./harness-metrics.js";
+export {
+	PROACTIVE_MEMORY_EVAL_TASKS,
+	PROACTIVE_MEMORY_EVAL_VARIANTS,
+	type ProactiveMemoryEvalReport,
+	type ProactiveMemoryEvalRunner,
+	type ProactiveMemoryEvalRunOutput,
+	type ProactiveMemoryEvalRunRequest,
+	type ProactiveMemoryEvalTarget,
+	type ProactiveMemoryEvalTask,
+	type ProactiveMemoryEvalTrial,
+	type ProactiveMemoryEvalVariant,
+	type ProactiveMemoryEvalVariantSummary,
+	type RunProactiveMemoryEvalOptions,
+	renderProactiveMemoryEvalReport,
+	runProactiveMemoryEval,
+	summarizeProactiveMemoryEval,
+} from "./proactive-memory.js";
+export { evalClioProvenance, evalEnvironmentProvenance } from "./provenance.js";
+export { renderEvalReport, renderSummaryLines, renderSweJsonl } from "./report.js";
+export type {
+	EvalCompareDeltas,
+	EvalCompareMatchedChange,
+	EvalCompareResultRef,
+	EvalCompareTotals,
+	EvalComparisonSummary,
+} from "./run-compare.js";
+export { compareEvalArtifacts, EVAL_COMPARE_MATCHING_RULE, renderEvalComparison } from "./run-compare.js";
+export { runEvalTasks, summarizeEvalResults } from "./runner.js";
+export { linkEvalArtifactRuntimePaths } from "./runtime-paths.js";
+export {
+	createEvalId,
+	evalArtifactPath,
+	evalRoot,
+	loadEvalArtifact,
+	writeEvalArtifact,
+} from "./store.js";
+export {
+	EvalTaskFileError,
+	loadEvalTaskFile,
+	parseEvalTaskFileYaml,
+	validateEvalTaskFile,
+} from "./task-file.js";
+export type {
+	EvalCommandPhase,
+	EvalCommandResult,
+	EvalFailureClass,
+	EvalFailureClassCount,
+	EvalHarnessMetrics,
+	EvalResult,
+	EvalRunArtifact,
+	EvalRunRecord,
+	EvalSummary,
+	EvalTask,
+	EvalTaskFile,
+	EvalTaskFileValidationResult,
+	EvalValidationIssue,
+	LoadedEvalTaskFile,
+} from "./types.js";

package/src/domains/eval/metrics/chaos-stream.ts

@@ -0,0 +1,93 @@
+export interface EvalChaosMarker {
+	seed: number;
+	faultInjected: boolean;
+	exitCode: number;
+	orphanedChildren: number;
+}
+
+export interface EvalChaosObservation {
+	markerCount: number;
+	marker: EvalChaosMarker | null;
+}
+
+export interface EvalChaosFold {
+	/** Feed a raw stdout chunk; partial trailing lines are held until completed. */
+	push(chunk: string): void;
+	observation(): EvalChaosObservation;
+}
+
+export const EMPTY_CHAOS_OBSERVATION: EvalChaosObservation = { markerCount: 0, marker: null };
+
+/** Fold the SIGINT harness marker from stdout before bounded artifact truncation can erase it. */
+export function createChaosFold(): EvalChaosFold {
+	let markerCount = 0;
+	let marker: EvalChaosMarker | null = null;
+	let pending = "";
+
+	const consume = (line: string): void => {
+		if (line.trim().length === 0) return;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line) as unknown;
+		} catch {
+			return;
+		}
+		if (!isRecord(parsed) || parsed.type !== "clio_soak_chaos") return;
+		markerCount += 1;
+		marker = parseChaosMarker(parsed);
+	};
+
+	return {
+		push(chunk: string): void {
+			pending += chunk;
+			for (;;) {
+				const newline = pending.indexOf("\n");
+				if (newline === -1) break;
+				consume(pending.slice(0, newline).replace(/\r$/u, ""));
+				pending = pending.slice(newline + 1);
+			}
+		},
+		observation(): EvalChaosObservation {
+			if (pending.length > 0) {
+				consume(pending.replace(/\r$/u, ""));
+				pending = "";
+			}
+			return { markerCount, marker: marker === null ? null : { ...marker } };
+		},
+	};
+}
+
+export function addChaosObservations(left: EvalChaosObservation, right: EvalChaosObservation): EvalChaosObservation {
+	const markerCount = left.markerCount + right.markerCount;
+	return {
+		markerCount,
+		marker: markerCount === 1 ? (left.marker ?? right.marker) : null,
+	};
+}
+
+/** Emit canonical metrics only for one fully valid marker; every other shape is unmeasured. */
+export function chaosMetricEntries(observation: EvalChaosObservation): Record<string, number | boolean> {
+	if (observation.markerCount !== 1 || observation.marker === null) return {};
+	return {
+		"chaos.seed": observation.marker.seed,
+		"chaos.faultInjected": observation.marker.faultInjected,
+		"chaos.exitCode": observation.marker.exitCode,
+		"process.orphanedChildren": observation.marker.orphanedChildren,
+	};
+}
+
+export function parseChaosMarker(event: Record<string, unknown>): EvalChaosMarker | null {
+	if (event.type !== "clio_soak_chaos") return null;
+	const { seed, faultInjected, exitCode, orphanedChildren } = event;
+	if (!isFiniteInteger(seed) || typeof faultInjected !== "boolean" || !isFiniteInteger(exitCode)) return null;
+	if (!isFiniteInteger(orphanedChildren) || orphanedChildren < 0) return null;
+	return { seed, faultInjected, exitCode, orphanedChildren };
+}
+
+function isFiniteInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/domains/eval/metrics/context.ts

@@ -0,0 +1,34 @@
+import { enumerateWorkspaceFiles } from "../../../core/workspace-files.js";
+import { readCodewiki, structuralCodewikiHash } from "../../context/codewiki/artifact.js";
+import { renderCodewikiDigest } from "../../context/codewiki/digest.js";
+import { detectProjectProfile } from "../../session/workspace/project-type.js";
+
+export function collectContextMetrics(cwd: string): Record<string, number | string | null> {
+	try {
+		const codewiki = readCodewiki(cwd);
+		if (!codewiki) throw new Error("codewiki unavailable");
+		const visiblePaths = new Set(enumerateWorkspaceFiles(cwd));
+		const artifactSourceFiles = codewiki.files.filter((file) => file.lang !== "config");
+		const indexedFiles = artifactSourceFiles.filter((file) => visiblePaths.has(file.path)).length;
+		const staleFiles = artifactSourceFiles.length - indexedFiles;
+		const sourceFiles = detectProjectProfile(cwd).sourceFiles;
+		const digest = renderCodewikiDigest(codewiki);
+		return {
+			"context.indexedFiles": indexedFiles,
+			"context.artifactFiles": artifactSourceFiles.length,
+			"context.staleFiles": staleFiles,
+			"context.coverage": sourceFiles === 0 ? (artifactSourceFiles.length === 0 ? 1 : 0) : indexedFiles / sourceFiles,
+			"context.structuralHash": structuralCodewikiHash(codewiki),
+			"context.digestTokens": Math.ceil(digest.length / 4),
+		};
+	} catch {
+		return {
+			"context.indexedFiles": 0,
+			"context.artifactFiles": 0,
+			"context.staleFiles": 0,
+			"context.coverage": 0,
+			"context.structuralHash": null,
+			"context.digestTokens": 0,
+		};
+	}
+}

package/src/domains/eval/metrics/coverage.ts

@@ -0,0 +1,21 @@
+import type { EvalArtifactResultV4 } from "../schema/artifact.js";
+
+export interface EvalTokenCoverage {
+	total: number;
+	measured: number;
+}
+
+/**
+ * How many of an artifact's runs carry observed token accounting. A runner
+ * that saw no usage sets `tokens.measured` false and emits no counts, so a
+ * summary total is only meaningful next to this coverage.
+ */
+export function tokenMeasurementCoverage(
+	results: ReadonlyArray<Pick<EvalArtifactResultV4, "metrics">>,
+): EvalTokenCoverage {
+	let measured = 0;
+	for (const result of results) {
+		if (result.metrics["tokens.measured"] === true) measured += 1;
+	}
+	return { total: results.length, measured };
+}

package/src/domains/eval/metrics/evidence.ts

@@ -0,0 +1,182 @@
+/**
+ * Receipt-derived evidence metrics for the eval bridge. The sealed receipt is
+ * the only source of truth here: dispatch/monitor prose labels are rendering
+ * and are never parsed. Every reader is total and fails closed; a missing or
+ * malformed receipt yields no metric, so gates on `evidence.*` fail rather
+ * than silently pass.
+ */
+
+import type { RunReceipt } from "../../dispatch/types.js";
+
+/**
+ * Extract the sealed RunReceipt that `clio-coder run --agent … --json` prints after
+ * its single-line JSONL event stream. The receipt is the only multi-line,
+ * pretty-printed JSON block in that output, so the last parseable block that
+ * carries the receipt's load-bearing fields wins. Returns null (never throws)
+ * when no such block exists.
+ */
+export function receiptFromRunJsonStdout(stdout: string): RunReceipt | null {
+	let searchEnd = stdout.length;
+	while (searchEnd > 0) {
+		const start = stdout.lastIndexOf("\n{", searchEnd - 1);
+		if (start === -1) break;
+		const candidate = stdout.slice(start + 1);
+		try {
+			const parsed: unknown = JSON.parse(candidate);
+			if (isReceiptShaped(parsed)) return parsed;
+		} catch {
+			// A JSONL event line or truncated block; keep scanning earlier starts.
+		}
+		// lastIndexOf clamps a negative fromIndex to 0, so a match at offset 0
+		// would repeat forever without this explicit stop.
+		if (start === 0) break;
+		searchEnd = start;
+	}
+	return null;
+}
+
+function isReceiptShaped(value: unknown): value is RunReceipt {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value as Record<string, unknown>;
+	return (
+		typeof record.runId === "string" &&
+		typeof record.agentId === "string" &&
+		typeof record.exitCode === "number" &&
+		typeof record.integrity === "object" &&
+		record.integrity !== null
+	);
+}
+
+/**
+ * Evidence metrics for one sealed receipt. `evidence.verification` is read
+ * strictly from `receipt.verification.state`. `evidence.firstPassSuccess`
+ * mirrors the durable findings summary and is omitted when that summary is
+ * absent, so a gate on the metric fails closed instead of inventing a value.
+ */
+export function evidenceMetricsFromReceipt(receipt: RunReceipt): Record<string, string | boolean | number> {
+	return {
+		"evidence.verification": receipt.verification.state,
+		...(receipt.findingsSummary === undefined
+			? {}
+			: { "evidence.firstPassSuccess": receipt.findingsSummary.firstPassSuccess === true }),
+		"evidence.quality.typedValidationCount": receipt.quality.typedValidations.length,
+		"evidence.responseSchema.digest": receipt.quality.responseSchema.schemaDigest ?? "none",
+		...(typeof receipt.costUsd === "number" && Number.isFinite(receipt.costUsd) ? { "cost.usd": receipt.costUsd } : {}),
+	};
+}
+
+/**
+ * Count terminal dispatch tool calls in a `clio-coder run --json` stream: the
+ * decomposition checkpoint. Mirrors the dedup rules of the tool-call metric
+ * fold (canonical clio finishes win over pi execution ends when both exist).
+ * An absent or eventless stream counts zero.
+ */
+export function dispatchCountFromJsonl(stdout: string): number {
+	let executionEnds = 0;
+	let canonicalFinishes = 0;
+	const seenExecutionEnds = new Set<string>();
+	const seenCanonicalFinishes = new Set<string>();
+	let sawCanonicalFinishEvent = false;
+	for (const event of jsonlEvents(stdout)) {
+		if (event.type === "tool_execution_end") {
+			if (stringField(event, "toolName") !== "dispatch") continue;
+			const callId = stringField(event, "toolCallId");
+			if (callId !== undefined) {
+				if (seenExecutionEnds.has(callId)) continue;
+				seenExecutionEnds.add(callId);
+			}
+			executionEnds += 1;
+			continue;
+		}
+		if (event.type !== "clio_tool_finish" || !isRecord(event.payload)) continue;
+		sawCanonicalFinishEvent = true;
+		if (stringField(event.payload, "tool") !== "dispatch") continue;
+		const callId = stringField(event.payload, "toolCallId") ?? stringField(event, "toolCallId");
+		if (callId !== undefined) {
+			if (seenCanonicalFinishes.has(callId)) continue;
+			seenCanonicalFinishes.add(callId);
+		}
+		canonicalFinishes += 1;
+	}
+	return sawCanonicalFinishEvent ? canonicalFinishes : executionEnds;
+}
+
+/** Count model-authored dispatch calls whose normalized task set includes Scout. */
+export function scoutDispatchCountFromJsonl(stdout: string): number {
+	const seen = new Set<string>();
+	let count = 0;
+	for (const event of jsonlEvents(stdout)) {
+		if (event.type !== "tool_execution_start" || stringField(event, "toolName") !== "dispatch") continue;
+		if (!isRecord(event.args) || !dispatchArgsIncludeAgent(event.args, "scout")) continue;
+		const callId = stringField(event, "toolCallId");
+		if (callId !== undefined) {
+			if (seen.has(callId)) continue;
+			seen.add(callId);
+		}
+		count += 1;
+	}
+	return count;
+}
+
+function dispatchArgsIncludeAgent(args: Record<string, unknown>, expectedAgent: string): boolean {
+	const sharedAgent = stringField(args, "agent") ?? stringField(args, "agent_id") ?? stringField(args, "agentId");
+	let tasks: unknown = args.tasks;
+	if (typeof tasks === "string") {
+		const trimmed = tasks.trim();
+		if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+			try {
+				tasks = JSON.parse(trimmed) as unknown;
+			} catch {
+				// A plain task string keeps using the shared agent below.
+			}
+		}
+	}
+	const taskList: unknown[] = Array.isArray(tasks) ? tasks : tasks === undefined ? [{ task: args.task }] : [tasks];
+	return taskList.some((task: unknown) => {
+		if (typeof task === "string") return sharedAgent?.toLowerCase() === expectedAgent;
+		if (!isRecord(task)) return false;
+		const agent =
+			stringField(task, "agent") ?? stringField(task, "agent_id") ?? stringField(task, "agentId") ?? sharedAgent;
+		return agent?.toLowerCase() === expectedAgent;
+	});
+}
+
+/**
+ * Stale-wiki behavioral checkpoint: true when the stream shows a live source
+ * read (read/grep start) AFTER a `code_nav mode=wiki` start, i.e. the model
+ * did not answer from the wiki alone. Absent either half → false.
+ */
+export function wikiStaleAcknowledgedFromJsonl(stdout: string): boolean {
+	let sawWikiLookup = false;
+	for (const event of jsonlEvents(stdout)) {
+		if (event.type !== "tool_execution_start") continue;
+		const toolName = stringField(event, "toolName");
+		if (toolName === "code_nav" && isRecord(event.args) && event.args.mode === "wiki") {
+			sawWikiLookup = true;
+			continue;
+		}
+		if (sawWikiLookup && (toolName === "read" || toolName === "grep")) return true;
+	}
+	return false;
+}
+
+function* jsonlEvents(stdout: string): Generator<Record<string, unknown>> {
+	for (const line of stdout.split(/\r?\n/)) {
+		if (line.trim().length === 0) continue;
+		try {
+			const parsed: unknown = JSON.parse(line);
+			if (isRecord(parsed)) yield parsed;
+		} catch {
+			// Non-JSON noise (including the pretty receipt tail) is not an event.
+		}
+	}
+}
+
+function stringField(record: Record<string, unknown>, field: string): string | undefined {
+	const value = record[field];
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}