@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/domains/dispatch/types.ts

@@ -15,6 +15,7 @@ import type { CostProvenance, RuntimeTargetSnapshot } from "../providers/index.j
 import type { RunToolBudgetEnvelope } from "./budget-envelope.js";
 import type { ExecutionRole, GateTopologyRole } from "./execution-role.js";
 import type { DispatchIntent } from "./intent.js";
+import type { DispatchPathScopeProvenance } from "./path-scope.js";
 import type { RouteDecisionV1 } from "./route-decision.js";
 import type { RoutingIntent } from "./routing-intent.js";
 
@@ -125,12 +126,16 @@ export interface RunPersonaOverride {
 
 /**
  * Effective project-context decision for a run, recorded on every receipt so
- * evidence can prove what a worker saw without rehashing. `tier: "none"` is
- * written explicitly: it distinguishes "policy said none" from a
- * pre-provenance receipt where the whole block is absent. `chars` and
- * `contentHash` describe the rendered dynamic message body when bounded;
- * `sections` lists extra projected sections that actually rendered
- * (currently only "verification-expectations", never for ACP delegation).
+ * evidence can prove what a worker saw without rehashing. `tier` is the
+ * recipe's CLIO-CODER.md handbook policy and is written explicitly: `none`
+ * distinguishes "policy said none" from a pre-provenance receipt where the
+ * whole block is absent. `chars` and `contentHash` describe every structured
+ * message that was actually sent, whatever the tier, and `sections` names
+ * them: `workspace-root` (sent under both tiers, so a none-tier run still
+ * records characters), `clio-md` (bounded only), and
+ * `verification-expectations` (bounded only, never for ACP delegation). A
+ * none-tier block naming only `workspace-root` is a consistent record; the
+ * trust adapter treats any other none-tier content as contradictory.
  */
 export interface RunProjectContextProvenance {
 	tier: "none" | "bounded";
@@ -321,7 +326,7 @@ export interface RunPhaseDurations {
  * bumping one without the other is a compile error.
  */
 export interface RunReceiptIntegrity {
-	version: 19;
+	version: 20;
 	algorithm: "sha256";
 	digest: string;
 }
@@ -714,6 +719,8 @@ export interface RunReceipt {
 	task: string;
 	/** Normalized dispatch intent admitted before worker execution. */
 	intent?: DispatchIntent;
+	/** Resolved policy-bearing paths with field source and confidence, without source prose. */
+	pathScope?: DispatchPathScopeProvenance;
 	/** Integrity-sealed recipe policy, invocation request, effective phase, and admission reasons. */
 	budget?: RunToolBudgetEnvelope;
 	/** Proof of briefing content without copying its prose into the receipt. */

package/src/domains/dispatch/validation.ts

@@ -7,6 +7,7 @@
 
 import path from "node:path";
 import { THINKING_LEVELS, type ThinkingLevel } from "../../core/defaults.js";
+import { asDirectoryPathBoundary, resolvePathBoundary } from "../../core/path-boundary.js";
 import { cloneValidatedResponseSchema } from "../../core/response-schema.js";
 import { isToolProfileName, type ToolProfileName } from "../../tools/profiles.js";
 import type { AgentProduct } from "../agents/spec.js";
@@ -482,8 +483,8 @@ export function validateJobSpec(spec: unknown): Validated {
 	}
 	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();
+		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");
 	}
 
@@ -597,7 +598,9 @@ export function validateJobSpec(spec: unknown): Validated {
 				: undefined;
 	if (effectiveWriteRoots !== undefined) {
 		const jobCwd = typeof spec.cwd === "string" && spec.cwd.length > 0 ? spec.cwd : process.cwd();
-		out.writeRoots = effectiveWriteRoots.map((root) => path.resolve(jobCwd, String(root)));
+		out.writeRoots = isDispatchIntent(spec.intent)
+			? effectiveWriteRoots.map((root) => resolvePathBoundary(jobCwd, String(root)))
+			: effectiveWriteRoots.map((root) => asDirectoryPathBoundary(path.resolve(jobCwd, String(root))));
 	}
 	if (typeof spec.requestOrigin === "string" && VALID_REQUEST_ORIGINS.has(spec.requestOrigin)) {
 		out.requestOrigin = spec.requestOrigin as DispatchRequestOrigin;

package/src/domains/dispatch/worker-spawn.ts

@@ -26,10 +26,12 @@
 
 import { type ChildProcess, spawn } from "node:child_process";
 import { join } from "node:path";
+import { performance } from "node:perf_hooks";
 import { withClioAgentEnvironment } from "../../core/agent-environment.js";
 import { enableClioCompileCache, workerCompileCacheEnvironment } from "../../core/compile-cache.js";
 import { resolvePackageRoot } from "../../core/package-root.js";
 import type { WorkerSpec } from "../../worker/spec-contract.js";
+import type { HeartbeatStamp } from "./heartbeat.js";
 import {
 	type AgentLedgerBody,
 	type ApprovedWorkerIdentity,
@@ -71,7 +73,7 @@ export interface SpawnedWorker {
 	promise: Promise<SpawnedWorkerResult>;
 	events: AsyncIterableIterator<unknown>;
 	abort(): void;
-	heartbeatAt: { current: number };
+	heartbeatAt: HeartbeatStamp;
 	/**
 	 * Write one JSON line to the worker's open stdin (the same line protocol
 	 * that carried the spec). Returns false when the worker has exited, its
@@ -134,15 +136,14 @@ export interface WorkerProcessOptions {
 	/** How long bulk output may precede the announce before the peer is refused. */
 	attestationGraceMs?: number;
 	/**
-	 * Clock behind the heartbeat stamp, defaulting to `Date.now`. The stamp stays
-	 * a wall-clock instant in production because the ledger, the receipt, and the
-	 * evidence record all serialize it as ISO-8601 for an operator to read. That
-	 * leaves a test with no honest way to assert the stamp advanced: comparing
-	 * two wall-clock reads taken either side of an interval orders them backward
-	 * on any host that resyncs its clock in between. A test injects the steppable
-	 * clock from tests/harness/clock.ts here and asserts on that instead.
+	 * Wall clock behind the heartbeat anchor, defaulting to `Date.now`. The
+	 * anchor stays a wall-clock instant because the ledger and evidence record
+	 * serialize the derived heartbeat as ISO-8601 for an operator to read. This
+	 * clock is read once; later heartbeat instants add a monotonic span to it.
 	 */
 	now?: () => number;
+	/** Monotonic clock used for heartbeat spans, defaulting to `performance.now`. */
+	monotonicNow?: () => number;
 }
 
 /**
@@ -192,6 +193,7 @@ export function spawnWorkerProcess(
 	const shutdownGraceMs = opts?.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS;
 	const attestationGraceMs = opts?.attestationGraceMs ?? DEFAULT_ATTESTATION_GRACE_MS;
 	const now = opts?.now ?? Date.now;
+	const monotonicNow = opts?.monotonicNow ?? (() => performance.now());
 	const approved = opts?.approvedIdentity ?? approvedIdentityForSpec(spec);
 
 	const child: ChildProcess = spawn(command, [...args], {
@@ -204,7 +206,19 @@ export function spawnWorkerProcess(
 	});
 	const pid = child.pid ?? null;
 
-	const heartbeatAt = { current: now() };
+	// One wall anchor plus a monotonic span keeps the persisted/display instant
+	// readable without ever asking a later wall-clock read how much time passed.
+	const heartbeatWallAnchor = now();
+	const heartbeatMonotonicAnchor = monotonicNow();
+	const heartbeatAt: HeartbeatStamp = {
+		current: heartbeatWallAnchor,
+		monotonic: heartbeatMonotonicAnchor,
+	};
+	const stampHeartbeat = (): void => {
+		const stamp = monotonicNow();
+		heartbeatAt.monotonic = stamp;
+		heartbeatAt.current = heartbeatWallAnchor + (stamp - heartbeatMonotonicAnchor);
+	};
 
 	const queue = createBoundedEventQueue();
 	const waiters: Array<(r: IteratorResult<unknown>) => void> = [];
@@ -233,7 +247,7 @@ export function spawnWorkerProcess(
 	}
 
 	function push(value: unknown): void {
-		heartbeatAt.current = now();
+		stampHeartbeat();
 		const w = waiters.shift();
 		if (w) {
 			w({ value, done: false });
@@ -378,7 +392,7 @@ export function spawnWorkerProcess(
 			if (!announceAccepted) failAttestation(`Invalid worker attestation: ${frame.reason}`);
 			return;
 		}
-		heartbeatAt.current = now();
+		stampHeartbeat();
 		if (frame.value.kind === "announce") {
 			if (announceAccepted || announceFailed) return;
 			const verdict = verifyWorkerAttestation(frame.value.attestation, approved);

package/src/domains/dispatch/write-boundary-enforcer.ts

@@ -8,6 +8,11 @@
  * a path that changed cannot be pinned on one of them, and the plan compiler
  * has already refused the case where more than one of them was allowed to
  * write. Every step in a violating window fails, and the verdict says why.
+ *
+ * The window also carries what its runs recorded writing, which is what keeps
+ * the checkout diff from being read as authorship. A change nobody in the
+ * window recorded belongs to whoever else has the checkout open, and the
+ * verdict reports it without touching it.
  */
 
 import { existsSync } from "node:fs";
@@ -16,9 +21,12 @@ import type { ExecutionPlan } from "./execution-plan.js";
 import type { ExecutionWriteBoundaryOutcome } from "./execution-scheduler.js";
 import {
 	assertWriteBoundaryInsideRoot,
+	assertWriteBoundaryVisibleToGit,
 	captureWorkspaceSnapshot,
 	enforceWriteBoundary,
 	type WorkspaceSnapshot,
+	type WriteBoundaryAttribution,
+	type WriteBoundaryAttributionDowngrade,
 	type WriteBoundaryVerdict,
 	writeWriteBoundaryVerdict,
 } from "./write-boundary.js";
@@ -30,6 +38,15 @@ export interface WriteBoundaryEnforcerInput {
 	rootId: string;
 	/** Declared allowlist for a step, or undefined when it declares no boundary. */
 	boundaryFor(stepId: string): ReadonlyArray<string> | undefined;
+	/**
+	 * What the step's own run recorded writing, or null when the step has no
+	 * closed write record: a code step running a registered command, a runtime
+	 * that publishes no tool telemetry, a run whose telemetry had holes, or a run
+	 * that shelled out or spawned a worker and could have written a path no
+	 * argument names. Absent entirely means the caller offers no record at all,
+	 * and every change outside the declaration is blamed on the window.
+	 */
+	recordedWritesFor?(stepId: string): ReadonlyArray<string> | WriteBoundaryAttribution | null;
 	/** Called once per closed window with the sealed verdict and where it landed. */
 	onVerdict?(verdict: WriteBoundaryVerdict, path: string): void;
 }
@@ -54,6 +71,9 @@ export function preflightWriteBoundaries(plan: ExecutionPlan, root: string): voi
 		);
 	}
 	for (const step of declared) assertWriteBoundaryInsideRoot(root, step.writes ?? []);
+	// One question over the whole plan: an entry is refused for being invisible
+	// to git whichever step declared it, and the diagnostic names the path.
+	assertWriteBoundaryVisibleToGit(root, [...new Set(declared.flatMap((step) => [...(step.writes ?? [])]))]);
 }
 
 export function createWriteBoundaryEnforcer(input: WriteBoundaryEnforcerInput): WriteBoundaryEnforcer {
@@ -63,10 +83,50 @@ export function createWriteBoundaryEnforcer(input: WriteBoundaryEnforcerInput):
 		for (const stepId of stepIds) for (const entry of input.boundaryFor(stepId) ?? []) allow.add(entry);
 		return [...allow].sort();
 	};
+	/**
+	 * The window's write witness. One step without a record makes the whole
+	 * window's record incomplete: the steps share a checkout, so a change no
+	 * other step wrote could still be the unobserved one's.
+	 */
+	const attributionFor = (stepIds: ReadonlyArray<string>): WriteBoundaryAttribution | undefined => {
+		const recordedWritesFor = input.recordedWritesFor;
+		if (recordedWritesFor === undefined) return undefined;
+		const recorded = new Set<string>();
+		const downgrades: WriteBoundaryAttributionDowngrade[] = [];
+		let complete = true;
+		for (const stepId of stepIds) {
+			const observed = recordedWritesFor(stepId);
+			if (observed === null) {
+				complete = false;
+				downgrades.push({
+					reason: "write_record_unavailable",
+					tool: null,
+					toolCallId: null,
+					runId: null,
+					stepId,
+				});
+				continue;
+			}
+			if (!("recorded" in observed)) {
+				for (const target of observed) recorded.add(target);
+				continue;
+			}
+			for (const target of observed.recorded) recorded.add(target);
+			if (!observed.complete) complete = false;
+			for (const downgrade of observed.downgrades ?? []) {
+				downgrades.push({ ...downgrade, stepId: downgrade.stepId ?? stepId });
+			}
+		}
+		return { recorded: [...recorded].sort(), complete, downgrades };
+	};
 	return {
 		begin(window, stepIds) {
 			const allow = allowFor(stepIds);
 			assertWriteBoundaryInsideRoot(input.root, allow);
+			// Also checked whole-plan at preflight. Repeated here because a
+			// delegation plan splices steps into a running fleet, and their
+			// declarations reach this function without ever passing preflight.
+			assertWriteBoundaryVisibleToGit(input.root, allow);
 			open.set(window, { snapshot: captureWorkspaceSnapshot(input.root), allow });
 		},
 		async verify(window, stepIds) {
@@ -75,11 +135,13 @@ export function createWriteBoundaryEnforcer(input: WriteBoundaryEnforcerInput):
 				throw new Error(`write boundary: window '${window}' was verified without a snapshot`);
 			}
 			open.delete(window);
+			const attribution = attributionFor(stepIds);
 			const verdict = enforceWriteBoundary({
 				snapshot: pending.snapshot,
 				window,
 				stepIds,
 				allow: pending.allow,
+				...(attribution === undefined ? {} : { attribution }),
 			});
 			const path = writeWriteBoundaryVerdict(input.rootId, verdict);
 			input.onVerdict?.(verdict, path);