@iowarp/clio-coder 0.3.6 → 0.3.7

package/src/domains/dispatch/types.ts

@@ -14,6 +14,7 @@ import type { EvidenceTag } from "../evidence/index.js";
 import type { CostProvenance, RuntimeTargetSnapshot } from "../providers/index.js";
 import type { RunToolBudgetEnvelope } from "./budget-envelope.js";
 import type { ExecutionRole, GateTopologyRole } from "./execution-role.js";
+import type { DispatchIntent } from "./intent.js";
 import type { RouteDecisionV1 } from "./route-decision.js";
 import type { RoutingIntent } from "./routing-intent.js";
 
@@ -41,7 +42,8 @@ export type RunOutcomeCode =
 	| "worker_tool_call_cap_exhausted"
 	| "loop_guard_tools_disabled_exhausted"
 	| "result_contract_exhausted"
-	| "worker_final_output_missing";
+	| "worker_final_output_missing"
+	| "host_verification_rejected";
 
 export function isRunOutcomeCode(value: unknown): value is RunOutcomeCode {
 	return (
@@ -49,7 +51,8 @@ export function isRunOutcomeCode(value: unknown): value is RunOutcomeCode {
 		value === "worker_tool_call_cap_exhausted" ||
 		value === "loop_guard_tools_disabled_exhausted" ||
 		value === "result_contract_exhausted" ||
-		value === "worker_final_output_missing"
+		value === "worker_final_output_missing" ||
+		value === "host_verification_rejected"
 	);
 }
 
@@ -238,6 +241,13 @@ export interface RunGateProvenance {
 	verdict?: "pass" | "fail" | "revise";
 }
 
+export interface RunCouncilProvenance {
+	group: string;
+	label: string;
+	color?: string;
+	round: number;
+}
+
 /**
  * Plan-approval provenance for multi-task, compete, or remote dispatch.
  * `approval: "operator"` records that a supervised autonomy level parked the
@@ -248,7 +258,7 @@ export interface RunGateProvenance {
  */
 export interface RunPlanProvenance {
 	hash: string;
-	topology: "parallel" | "sequential" | "pipeline" | "review" | "compete" | "detached" | "fleet";
+	topology: "parallel" | "sequential" | "pipeline" | "review" | "compete" | "council" | "detached" | "fleet";
 	taskCount: number;
 	approval: "operator" | "full-auto";
 	source: null | {
@@ -311,7 +321,7 @@ export interface RunPhaseDurations {
  * bumping one without the other is a compile error.
  */
 export interface RunReceiptIntegrity {
-	version: 15;
+	version: 19;
 	algorithm: "sha256";
 	digest: string;
 }
@@ -449,6 +459,7 @@ export interface RunEnvelope {
 	pipeline?: RunPipelineProvenance;
 	/** Review/compete gate provenance; present only on runs of a gated dispatch. */
 	gate?: RunGateProvenance;
+	council?: RunCouncilProvenance;
 	/** Plan-approval provenance; present only on runs of an approval-gated plan. */
 	plan?: RunPlanProvenance;
 	/** Ad-hoc specialist provenance; present only when a persona override composed the stable prompt. */
@@ -674,6 +685,25 @@ export interface RunReceiptVerification {
 		| "receipt-unavailable";
 }
 
+export interface RunHostVerificationCheck {
+	check: string;
+	argv: string[];
+	cwd: string;
+	exitCode: number;
+	durationMs: number;
+	memo: boolean;
+	outputTail: string;
+	artifactPath?: string;
+	/** Original evidence owner on a memo hit. */
+	evidenceRunId?: string;
+}
+
+export interface RunHostVerification {
+	status: "verified" | "rejected" | "skipped";
+	reason?: string;
+	checks: RunHostVerificationCheck[];
+}
+
 export interface RunReceipt {
 	runId: string;
 	agentId: string;
@@ -682,6 +712,8 @@ export interface RunReceipt {
 	agentAudience?: AgentAudience;
 	requestOrigin?: DispatchRequestOrigin;
 	task: string;
+	/** Normalized dispatch intent admitted before worker execution. */
+	intent?: DispatchIntent;
 	/** Integrity-sealed recipe policy, invocation request, effective phase, and admission reasons. */
 	budget?: RunToolBudgetEnvelope;
 	/** Proof of briefing content without copying its prose into the receipt. */
@@ -714,8 +746,11 @@ export interface RunReceipt {
 	pipeline?: RunPipelineProvenance;
 	/** Review/compete gate provenance; present only on runs of a gated dispatch. */
 	gate?: RunGateProvenance;
+	council?: RunCouncilProvenance;
 	/** Plan-approval provenance; present only on runs of an approval-gated plan. */
 	plan?: RunPlanProvenance;
+	/** Version 5 fleet gate artifact authored by this run. */
+	fleetGate?: { path: string; pathHash: string };
 	/** Ad-hoc specialist provenance; present only when a persona override composed the stable prompt. */
 	personaOverride?: RunPersonaOverride;
 	/** Effective project-context tier for this run; absent on receipts written before this field landed. */
@@ -764,6 +799,17 @@ export interface RunReceipt {
 	toolActivity?: ToolActivitySummary;
 	/** Integrity-sealed evidence confidence. Sealed on every receipt. */
 	verification: RunReceiptVerification;
+	/** Orchestrator-executed declared checks. Worker self-report never populates this field. */
+	hostVerification?: RunHostVerification;
+	/** Isolated writer checkout and its collect-time application result. */
+	worktree?: {
+		path: string;
+		branch: string;
+		diffHash: string;
+		apply: "merge" | "preserve";
+		applied: boolean;
+		reason?: string;
+	};
 	/** Required normalized routing request, sealed without task or prompt data. */
 	routingIntent: RoutingIntent;
 	/** Required routing-quality facts known at receipt finalization. */
@@ -786,8 +832,7 @@ export interface RunReceipt {
 	 * What this run contributed to its dispatch's agent ledger. Optional and
 	 * absent unless the run had a ledger, following validationGrounding and
 	 * capabilityMismatch: receiptDigestFields skips undefined, so a receipt
-	 * without one digests exactly as it did before this landed and
-	 * RUN_RECEIPT_INTEGRITY_VERSION stays where it is.
+	 * without one omits the field from canonical serialization.
 	 */
 	ledgerContribution?: RunLedgerContribution;
 	/**

package/src/domains/dispatch/validation.ts

@@ -19,6 +19,7 @@ import {
 } from "./execution-handoff.js";
 import { isExecutionRole } from "./execution-role.js";
 import { COMPETE_STANCES, type CompeteStance } from "./gate-role-prompts.js";
+import { type DispatchIntent, isDispatchIntent } from "./intent.js";
 import { isRoutingIntent, type RoutingIntent } from "./routing-intent.js";
 import type {
 	DispatchRequestOrigin,
@@ -121,6 +122,10 @@ export interface JobSpec {
 	 */
 	denyTools?: ReadonlyArray<string>;
 	cwd?: string;
+	/** Run this writer in an isolated git worktree. */
+	worktree?: true;
+	/** How a successful isolated writer is applied to its parent checkout. */
+	apply?: "merge" | "preserve";
 	memorySection?: string;
 	noSkills?: boolean;
 	skillPaths?: ReadonlyArray<string>;
@@ -134,6 +139,8 @@ export interface JobSpec {
 	 * per-tool calls (subprocess).
 	 */
 	writeRoots?: ReadonlyArray<string>;
+	/** Normalized model-declared path, output, and host verification intent. */
+	intent?: DispatchIntent;
 	requestOrigin?: DispatchRequestOrigin;
 	/**
 	 * Threaded output from the previous pipeline step. Set only by the dispatch
@@ -159,6 +166,8 @@ export interface JobSpec {
 	autonomy?: AutonomyLevel;
 	/** Review/compete gate provenance sealed into the run's receipt. */
 	gate?: RunGateProvenance;
+	/** Council grouping projected to receipts and fleet surfaces. */
+	council?: { group: string; label: string; color?: string; round: number };
 	/** Plan-approval provenance sealed into the run's receipt. */
 	plan?: RunPlanProvenance;
 	/**
@@ -195,18 +204,22 @@ const KNOWN_KEYS = new Set([
 	"toolProfile",
 	"denyTools",
 	"cwd",
+	"worktree",
+	"apply",
 	"memorySection",
 	"noSkills",
 	"skillPaths",
 	"trustProjectCompatRoots",
 	"responseSchema",
 	"writeRoots",
+	"intent",
 	"requestOrigin",
 	"pipelineInput",
 	"predecessorHandoffs",
 	"lineage",
 	"autonomy",
 	"gate",
+	"council",
 	"plan",
 	"competeStance",
 ]);
@@ -399,7 +412,7 @@ export function validateJobSpec(spec: unknown): Validated {
 
 	if ("toolProfile" in spec && spec.toolProfile !== undefined) {
 		if (typeof spec.toolProfile !== "string" || !isToolProfileName(spec.toolProfile)) {
-			errors.push("toolProfile must be one of: minimal-local|science-local|full-agent");
+			errors.push("toolProfile must be one of: minimal-local|science-local|full-agent|council-read-only");
 		}
 	}
 
@@ -414,6 +427,13 @@ export function validateJobSpec(spec: unknown): Validated {
 			errors.push("cwd must be a non-empty string");
 		}
 	}
+	if ("worktree" in spec && spec.worktree !== undefined && spec.worktree !== true) {
+		errors.push("worktree must be true when present");
+	}
+	if ("apply" in spec && spec.apply !== undefined && spec.apply !== "merge" && spec.apply !== "preserve") {
+		errors.push("apply must be merge or preserve");
+	}
+	if (spec.apply !== undefined && spec.worktree !== true) errors.push("apply requires worktree: true");
 
 	if ("memorySection" in spec && spec.memorySection !== undefined) {
 		if (typeof spec.memorySection !== "string") {
@@ -457,6 +477,15 @@ 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) => path.resolve(jobCwd, String(root))))].sort();
+		const declared = [...new Set(spec.intent.writeRoots.map((root) => path.resolve(jobCwd, root)))].sort();
+		if (JSON.stringify(legacy) !== JSON.stringify(declared)) errors.push("intent_write_roots_contradiction");
+	}
 
 	if ("requestOrigin" in spec && spec.requestOrigin !== undefined) {
 		if (typeof spec.requestOrigin !== "string" || !VALID_REQUEST_ORIGINS.has(spec.requestOrigin)) {
@@ -550,18 +579,25 @@ export function validateJobSpec(spec: unknown): Validated {
 	if (typeof spec.toolProfile === "string" && isToolProfileName(spec.toolProfile)) out.toolProfile = spec.toolProfile;
 	if (Array.isArray(spec.denyTools)) out.denyTools = spec.denyTools.map((tool) => String(tool));
 	if (typeof spec.cwd === "string") out.cwd = spec.cwd;
+	if (spec.worktree === true) out.worktree = true;
+	if (spec.apply === "merge" || spec.apply === "preserve") out.apply = spec.apply;
 	if (typeof spec.memorySection === "string") out.memorySection = spec.memorySection;
 	if (typeof spec.noSkills === "boolean") out.noSkills = spec.noSkills;
 	if (Array.isArray(spec.skillPaths)) out.skillPaths = spec.skillPaths.map((p) => String(p));
 	if (typeof spec.trustProjectCompatRoots === "boolean") out.trustProjectCompatRoots = spec.trustProjectCompatRoots;
 	if (responseSchema) out.responseSchema = responseSchema;
-	if (
+	if (isDispatchIntent(spec.intent)) out.intent = structuredClone(spec.intent);
+	const effectiveWriteRoots =
 		Array.isArray(spec.writeRoots) &&
 		spec.writeRoots.length > 0 &&
 		spec.writeRoots.every((root) => typeof root === "string" && root.length > 0)
-	) {
+			? spec.writeRoots
+			: isDispatchIntent(spec.intent) && spec.intent.writeRoots.length > 0
+				? spec.intent.writeRoots
+				: undefined;
+	if (effectiveWriteRoots !== undefined) {
 		const jobCwd = typeof spec.cwd === "string" && spec.cwd.length > 0 ? spec.cwd : process.cwd();
-		out.writeRoots = spec.writeRoots.map((root) => path.resolve(jobCwd, String(root)));
+		out.writeRoots = effectiveWriteRoots.map((root) => path.resolve(jobCwd, String(root)));
 	}
 	if (typeof spec.requestOrigin === "string" && VALID_REQUEST_ORIGINS.has(spec.requestOrigin)) {
 		out.requestOrigin = spec.requestOrigin as DispatchRequestOrigin;
@@ -572,6 +608,7 @@ export function validateJobSpec(spec: unknown): Validated {
 	if (isValidLineage(spec.lineage)) out.lineage = spec.lineage;
 	if (isAutonomyLevel(spec.autonomy)) out.autonomy = spec.autonomy;
 	if (isValidGate(spec.gate)) out.gate = cloneGate(spec.gate);
+	if (isValidCouncil(spec.council)) out.council = { ...spec.council };
 	if (typeof spec.competeStance === "string" && VALID_COMPETE_STANCES.has(spec.competeStance)) {
 		out.competeStance = spec.competeStance as CompeteStance;
 	}
@@ -654,9 +691,18 @@ function isValidProtectedArtifactRemap(value: unknown): value is ProtectedArtifa
 	);
 }
 
-const VALID_GATE_ROLES = new Set(["builder", "reviewer", "candidate", "judge"]);
+const VALID_GATE_ROLES = new Set(["builder", "reviewer", "candidate", "judge", "member", "synthesis"]);
 const VALID_GATE_VERDICTS = new Set(["pass", "fail", "revise"]);
-const VALID_PLAN_TOPOLOGIES = new Set(["parallel", "sequential", "pipeline", "review", "compete", "detached", "fleet"]);
+const VALID_PLAN_TOPOLOGIES = new Set([
+	"parallel",
+	"sequential",
+	"pipeline",
+	"review",
+	"compete",
+	"council",
+	"detached",
+	"fleet",
+]);
 const VALID_PLAN_APPROVALS = new Set(["operator", "full-auto"]);
 
 function isValidGate(value: unknown): value is RunGateProvenance {
@@ -688,6 +734,20 @@ function cloneGate(gate: RunGateProvenance): RunGateProvenance {
 	};
 }
 
+function isValidCouncil(value: unknown): value is NonNullable<JobSpec["council"]> {
+	return (
+		isPlainObject(value) &&
+		typeof value.group === "string" &&
+		value.group.length > 0 &&
+		typeof value.label === "string" &&
+		value.label.length > 0 &&
+		(value.color === undefined || typeof value.color === "string") &&
+		typeof value.round === "number" &&
+		Number.isInteger(value.round) &&
+		value.round >= 1
+	);
+}
+
 function isValidPlan(value: unknown): value is RunPlanProvenance {
 	if (!isPlainObject(value)) return false;
 	if (typeof value.hash !== "string" || value.hash.length === 0) return false;

package/src/domains/evidence/trust-status.ts

@@ -418,6 +418,7 @@ export type PersistedRunReceiptTrustFacts = Pick<RunReceipt, "runId"> &
 			RunReceipt,
 			| "integrity"
 			| "verification"
+			| "hostVerification"
 			| "quality"
 			| "validationGrounding"
 			| "briefing"
@@ -536,6 +537,12 @@ export function adaptRunReceiptValidationStatus(
 ): ValidationGroundingStatus {
 	if (receipt === null || receipt === undefined) return absentTrustStatus("artifact_missing");
 	const artifacts = validationArtifacts(receipt);
+	if (receipt.hostVerification?.status === "rejected") {
+		return attributed("failed", receiptSource(receipt), { kind: "validator", id: "host-verification" }, artifacts);
+	}
+	if (receipt.hostVerification?.status === "verified") {
+		return attributed("validated", receiptSource(receipt), { kind: "validator", id: "host-verification" }, artifacts);
+	}
 	if (qualityHasFailure(receipt.quality)) {
 		return attributed("failed", receiptSource(receipt), { kind: "validator", id: "receipt-quality" }, artifacts);
 	}
@@ -549,7 +556,9 @@ export function adaptRunReceiptValidationStatus(
 	if (qualityHasValidation(receipt.quality)) {
 		return attributed("validated", receiptSource(receipt), { kind: "validator", id: "receipt-quality" }, artifacts);
 	}
-	if (receipt.verification !== undefined) return verificationStatus(receipt.verification, receipt, artifacts);
+	if (receipt.verification !== undefined) {
+		return verificationStatus(receipt.verification, receipt, artifacts);
+	}
 	return attributed("unknown", compatibilitySource(receipt, "verification"), COMPATIBILITY_AUTHORITY, artifacts);
 }
 

package/src/domains/middleware/index.ts

@@ -152,3 +152,18 @@ export type {
 	MiddlewareValidationIssue,
 } from "./validate.js";
 export { validateMiddlewareEffect, validateMiddlewareRule } from "./validate.js";
+export {
+	coalesceTurnDiff,
+	createWatchdogRegistration,
+	WATCHDOG_DIFF_MAX_BYTES,
+	WATCHDOG_PATHS_MAX,
+	WATCHDOG_REGISTRATION_ID,
+	WATCHDOG_TASK,
+	WATCHDOG_TRUNCATION_MARKER,
+	type WatchdogDeps,
+	type WatchdogRegistration,
+	type WatchdogSettingsView,
+	type WatchdogTrigger,
+	type WatchdogTriggerReason,
+	watchdogBriefing,
+} from "./watchdog.js";

package/src/domains/middleware/watchdog.ts

@@ -0,0 +1,281 @@
+/**
+ * The opt-in turn-end watchdog.
+ *
+ * A long agentic turn can leave the tree in a state nobody looked at: the
+ * model reports success, the operator reads the report, and the drift between
+ * what the board asked for and what the diff actually did stays invisible
+ * until someone reads the diff themselves. When `watchdog.enabled` is on, a
+ * turn that changed the tree is handed to one read-only verifier run briefed
+ * with the turn's coalesced diff and the board's current scope. Its blockers
+ * become one transcript notice and nothing else.
+ *
+ * What it deliberately does not do: it never auto-follows, never carries the
+ * turn onward, never queues a turn, and never mutates. A watchdog that could
+ * start work would be a second agent nobody asked for; this one can only tell
+ * the operator what it saw.
+ *
+ * The registration itself emits no middleware effects. It owns the decision of
+ * when to fire and the coalesced diff it fires with; the caller owns the
+ * dispatch and the notice.
+ */
+
+import { ToolNames } from "../../core/tool-names.js";
+import type { MiddlewareHookRegistration } from "./runtime.js";
+import type { MiddlewareEffect, MiddlewareHookInput } from "./types.js";
+
+export const WATCHDOG_REGISTRATION_ID = "observer.watchdog";
+
+/**
+ * Bound on the coalesced diff a watchdog briefing carries, in UTF-8 bytes. The
+ * run is meant to be cheap enough to spend on every mutating turn, so it is
+ * given the shape of the change rather than every byte of it.
+ */
+export const WATCHDOG_DIFF_MAX_BYTES = 12 * 1024;
+
+/** Bound on how many mutated paths the briefing names before it summarizes the rest. */
+export const WATCHDOG_PATHS_MAX = 40;
+
+export const WATCHDOG_TRUNCATION_MARKER = "\n[diff truncated]";
+
+/** Tools whose successful results carry a file diff worth coalescing. */
+const MUTATING_TOOL_NAMES = new Set<string>([ToolNames.Write, ToolNames.Edit, ToolNames.Artifact]);
+
+const NO_EFFECTS: ReadonlyArray<MiddlewareEffect> = [];
+
+export type WatchdogTriggerReason = "turn_end" | "cadence";
+
+export interface WatchdogTrigger {
+	reason: WatchdogTriggerReason;
+	/** The turn's coalesced diff, one block per mutated path in first-touch order. */
+	diff: string;
+	/** Paths the turn mutated, in first-touch order. */
+	paths: ReadonlyArray<string>;
+	/** The board's current scope, or null when the session has no task board. */
+	scope: string | null;
+	/** Tool calls seen in this turn when the trigger fired. */
+	toolCalls: number;
+}
+
+/** The live settings view the registration reads on every boundary, so a hot reload lands immediately. */
+export interface WatchdogSettingsView {
+	enabled: boolean;
+	target?: string;
+	cadenceToolCalls?: number;
+}
+
+export interface WatchdogDeps {
+	getSettings: () => Readonly<WatchdogSettingsView>;
+	/** The board's current scope line, or null when there is no board. */
+	getScope?: () => string | null;
+	/**
+	 * Dispatch the watchdog run and deliver whatever it found. Resolves when the
+	 * run has settled; the registration awaits only to know the in-flight slot is
+	 * free again, never to hold the turn.
+	 */
+	run: (trigger: WatchdogTrigger) => Promise<void>;
+	/**
+	 * False on a surface that must never fire the watchdog whatever the setting
+	 * says. Headless and ACP runs pass false: neither has an operator watching a
+	 * transcript, so a notice they cannot read is a worker run spent on nothing.
+	 */
+	firesOnThisSurface?: boolean;
+}
+
+export interface WatchdogRegistration extends MiddlewareHookRegistration {
+	/** Triggers dropped because a watchdog run was already in flight. */
+	droppedTriggers(): number;
+	/** True while a watchdog run is outstanding. */
+	runInFlight(): boolean;
+	/** Resolves once no watchdog run is outstanding. */
+	whenIdle(): Promise<void>;
+}
+
+function stringValue(value: unknown): string | null {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function firstPath(details: Readonly<Record<string, unknown>> | undefined): string | null {
+	const paths = details?.paths;
+	if (!Array.isArray(paths)) return null;
+	for (const entry of paths) {
+		const path = stringValue(entry);
+		if (path !== null) return path;
+	}
+	return null;
+}
+
+/**
+ * Coalesce the per-call diffs of one turn into one diff.
+ *
+ * Per-path last-write-wins, in first-touch order. A turn that edited one file
+ * six times produced six diffs against six different base contents; replaying
+ * all of them tells a reviewer the history of the edit rather than its result,
+ * and the result is what the reviewer is being asked about.
+ */
+export function coalesceTurnDiff(
+	byPath: ReadonlyMap<string, string>,
+	maxBytes: number = WATCHDOG_DIFF_MAX_BYTES,
+): string {
+	const blocks: string[] = [];
+	let index = 0;
+	for (const [path, diff] of byPath) {
+		if (index >= WATCHDOG_PATHS_MAX) {
+			blocks.push(`[${byPath.size - WATCHDOG_PATHS_MAX} more changed path(s) omitted]`);
+			break;
+		}
+		blocks.push(`--- ${path}\n${diff}`);
+		index += 1;
+	}
+	const whole = blocks.join("\n\n");
+	if (Buffer.byteLength(whole, "utf8") <= maxBytes) return whole;
+	const room = Math.max(0, maxBytes - Buffer.byteLength(WATCHDOG_TRUNCATION_MARKER, "utf8"));
+	const buffer = Buffer.from(whole, "utf8");
+	let cut = Math.min(room, buffer.byteLength);
+	while (cut > 0) {
+		const next = buffer[cut];
+		if (next === undefined || (next & 0xc0) !== 0x80) break;
+		cut -= 1;
+	}
+	return `${buffer.subarray(0, cut).toString("utf8")}${WATCHDOG_TRUNCATION_MARKER}`;
+}
+
+/** The bounded, fixed task every watchdog run is given. It never varies with the diff. */
+export const WATCHDOG_TASK =
+	"Review the coalesced diff in the briefing against the scope it names. Report one check per concern: " +
+	"a change outside the stated scope, a change the scope required that the diff does not make, or a defect " +
+	"visible in the diff itself. Run no commands and change nothing.";
+
+/** The briefing body a watchdog run receives. Data, never instructions. */
+export function watchdogBriefing(trigger: WatchdogTrigger): string {
+	const scope = trigger.scope === null ? "(no task board; scope is unstated)" : trigger.scope;
+	const paths = trigger.paths.length === 0 ? "(none)" : trigger.paths.join("\n");
+	return [
+		"## Current scope",
+		scope,
+		"",
+		"## Changed paths",
+		paths,
+		"",
+		"## Coalesced diff for this turn",
+		trigger.diff,
+	].join("\n");
+}
+
+/**
+ * Build the registration. It is hooked on `after_tool` and `turn_end`:
+ * `after_tool` is where the diffs and the tool count come from, and `turn_end`
+ * is the boundary a mutating turn fires on.
+ */
+export function createWatchdogRegistration(deps: WatchdogDeps): WatchdogRegistration {
+	const diffByPath = new Map<string, string>();
+	let toolCalls = 0;
+	let dropped = 0;
+	let inFlight = false;
+	let outstanding: Promise<void> = Promise.resolve();
+
+	const active = (): WatchdogSettingsView | null => {
+		if (deps.firesOnThisSurface === false) return null;
+		let settings: Readonly<WatchdogSettingsView>;
+		try {
+			settings = deps.getSettings();
+		} catch {
+			return null;
+		}
+		return settings.enabled ? settings : null;
+	};
+
+	const resetTurn = (): void => {
+		diffByPath.clear();
+		toolCalls = 0;
+	};
+
+	const fire = (reason: WatchdogTriggerReason): void => {
+		if (diffByPath.size === 0) return;
+		// One run at a time. A watchdog slower than the turns that trigger it must
+		// not queue: a queued review describes a tree that has already moved on,
+		// and a backlog of them would outlive the session. The drop is counted so
+		// a starved cadence and a quiet one stay distinguishable.
+		if (inFlight) {
+			dropped += 1;
+			return;
+		}
+		const trigger: WatchdogTrigger = {
+			reason,
+			diff: coalesceTurnDiff(diffByPath),
+			paths: [...diffByPath.keys()].slice(0, WATCHDOG_PATHS_MAX),
+			scope: scopeNow(),
+			toolCalls,
+		};
+		inFlight = true;
+		// Started synchronously, so the in-flight slot is genuinely taken before
+		// this hook returns. Deferring the start to a microtask would let two
+		// triggers in the same tool batch both find the slot free.
+		let started: Promise<void>;
+		try {
+			started = deps.run(trigger);
+		} catch {
+			inFlight = false;
+			return;
+		}
+		outstanding = started
+			.catch(() => {
+				// A failed watchdog run is not a failed turn. The run's own reporting
+				// path already told the operator whatever it could.
+			})
+			.finally(() => {
+				inFlight = false;
+			});
+	};
+
+	const scopeNow = (): string | null => {
+		try {
+			return deps.getScope?.() ?? null;
+		} catch {
+			return null;
+		}
+	};
+
+	return {
+		id: WATCHDOG_REGISTRATION_ID,
+		description: "review a mutating turn's coalesced diff against the board scope with a read-only verifier run",
+		hooks: ["after_tool", "turn_end"],
+		evaluate(input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> {
+			const settings = active();
+			if (settings === null) {
+				// Still clear turn state so a mid-session disable cannot leave a diff
+				// behind that a later enable would fire on.
+				if (input.hook === "turn_end") resetTurn();
+				return NO_EFFECTS;
+			}
+			if (input.hook === "after_tool") {
+				toolCalls += 1;
+				recordMutation(input);
+				const cadence = settings.cadenceToolCalls;
+				// Mid-turn cadence keeps accumulating: turn end still reviews the whole
+				// turn, not just what landed after the last cadence firing.
+				if (cadence !== undefined && cadence >= 1 && toolCalls % cadence === 0) fire("cadence");
+				return NO_EFFECTS;
+			}
+			if (input.hook !== "turn_end") return NO_EFFECTS;
+			// A turn with no file mutations never fires. A middleware continuation
+			// re-evaluates turn_end with the accumulator already cleared, so it
+			// cannot fire a second run for the same change either.
+			fire("turn_end");
+			resetTurn();
+			return NO_EFFECTS;
+		},
+		droppedTriggers: () => dropped,
+		runInFlight: () => inFlight,
+		whenIdle: () => outstanding,
+	};
+
+	function recordMutation(input: MiddlewareHookInput): void {
+		if (input.metadata?.resultKind !== "ok") return;
+		if (input.toolName === undefined || !MUTATING_TOOL_NAMES.has(input.toolName)) return;
+		const diff = stringValue(input.toolResultDetails?.diff);
+		if (diff === null) return;
+		// Map.set on an existing key keeps its insertion position, so the newest
+		// diff for a path wins while the path keeps its first-touch order.
+		diffByPath.set(firstPath(input.toolResultDetails) ?? input.toolName, diff);
+	}
+}

package/src/domains/observability/contract.ts

@@ -2,7 +2,7 @@ import type { ResponseModelIdObservationCounts } from "../../core/response-model
 import type { TargetStatus } from "../providers/contract.js";
 import type { CostProvenance } from "../providers/index.js";
 import type { AccountabilitySummary } from "./accountability.js";
-import type { CostAggregate, CostEntry, UsageBreakdown } from "./cost.js";
+import type { CostAggregate, CostEntry, CostEntryLabel, UsageBreakdown } from "./cost.js";
 import type { MetricsView } from "./metrics.js";
 import type { TelemetrySnapshot } from "./telemetry.js";
 import type { SessionTurnTrace } from "./trace-store.js";
@@ -142,6 +142,8 @@ export interface ObservabilityContract {
 			requestedModelIds: ReadonlyArray<string>;
 			responseModelIdObservationCounts: Readonly<ResponseModelIdObservationCounts>;
 		},
+		/** Marks a priced call that was not an ordinary turn, such as a `/btw` side question. */
+		label?: CostEntryLabel,
 	): void;
 	/** Record final output token throughput for one completed assistant stream. */
 	recordTokenThroughput(snapshot: TokenThroughputSnapshot): void;