@iowarp/clio-coder 0.3.6 → 0.3.8

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";
@@ -19,6 +20,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 +123,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 +140,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 +167,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 +205,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 +413,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 +428,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 +478,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) => 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");
+	}
 
 	if ("requestOrigin" in spec && spec.requestOrigin !== undefined) {
 		if (typeof spec.requestOrigin !== "string" || !VALID_REQUEST_ORIGINS.has(spec.requestOrigin)) {
@@ -550,18 +580,27 @@ 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 = 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;
@@ -572,6 +611,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 +694,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 +737,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/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,11 @@ import type { ExecutionPlan } from "./execution-plan.js";
 import type { ExecutionWriteBoundaryOutcome } from "./execution-scheduler.js";
 import {
 	assertWriteBoundaryInsideRoot,
+	assertWriteBoundaryVisibleToGit,
 	captureWorkspaceSnapshot,
 	enforceWriteBoundary,
 	type WorkspaceSnapshot,
+	type WriteBoundaryAttribution,
 	type WriteBoundaryVerdict,
 	writeWriteBoundaryVerdict,
 } from "./write-boundary.js";
@@ -30,6 +37,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> | null;
 	/** Called once per closed window with the sealed verdict and where it landed. */
 	onVerdict?(verdict: WriteBoundaryVerdict, path: string): void;
 }
@@ -54,6 +70,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 +82,34 @@ 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>();
+		let complete = true;
+		for (const stepId of stepIds) {
+			const observed = recordedWritesFor(stepId);
+			if (observed === null) {
+				complete = false;
+				continue;
+			}
+			for (const target of observed) recorded.add(target);
+		}
+		return { recorded: [...recorded].sort(), complete };
+	};
 	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 +118,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);

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

@@ -21,18 +21,27 @@
  * Everything is pinned to the baseline commit recorded at snapshot time, so a
  * commit step that moves HEAD without touching the working tree reads as "no
  * change" instead of as a wholesale rewrite.
+ *
+ * A window's diff answers "what changed", never "who changed it". An operator
+ * editing the checkout while a fleet runs produces changes inside the window
+ * that no step made, and rolling those back to the baseline destroys work
+ * nobody asked Clio to touch. So a change is blamed on the window only when it
+ * intersects what the window's own runs recorded writing; everything else is
+ * reported as an unattributed concurrent change and left exactly as it is.
  */
 
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { asDirectoryPathBoundary, pathBoundaryEntryCovers } from "../../core/path-boundary.js";
 import { clioStateDir } from "../../core/xdg.js";
 import { atomicWrite } from "../../engine/session.js";
 import { isGitRepository } from "../../tools/compete-worktrees.js";
 import {
 	describeWriteBoundary,
 	normalizeWriteBoundary,
+	normalizeWriteBoundaryEntry,
 	type WriteBoundary,
 	writeBoundaryCovers,
 } from "../agents/write-boundary.js";
@@ -71,10 +80,15 @@ function gitBytes(root: string, args: ReadonlyArray<string>): Buffer {
  *
  * Enforcement sees exactly what git sees, so an ignored path is outside it: a
  * repository decides what counts as its own content, and this is not the place
- * to overrule that. The one thing subtracted is Clio's own state directory when
- * an operator has placed it inside the workspace. Receipts, code-step logs, and
- * boundary verdicts are the orchestrator writing its journal while the step
- * runs, and blaming the step for them would make every window a violation.
+ * to overrule that. The consequence is that a boundary declared over an ignored
+ * path could never be verified, which is why `assertWriteBoundaryVisibleToGit`
+ * refuses that declaration before anything runs rather than letting this
+ * function certify an unobserved window as clean.
+ *
+ * The one thing subtracted is Clio's own state directory when an operator has
+ * placed it inside the workspace. Receipts, code-step logs, and boundary
+ * verdicts are the orchestrator writing its journal while the step runs, and
+ * blaming the step for them would make every window a violation.
  */
 function dirtyPaths(root: string): string[] {
 	const raw = git(root, ["status", "--porcelain=v1", "-z", "-uall", "--no-renames"]);
@@ -222,14 +236,55 @@ export interface WriteBoundaryUnrecoverable {
 }
 
 /**
- * `clean` means nothing outside the allowlist changed. `rolled-back` means
- * something did and the repository now looks as it did before. Anything else is
- * `rollback-incomplete`: the working tree is left exactly as the step made it
- * and handed to the operator with the list, because a rollback that guesses at
- * content it never recorded destroys work.
+ * `clean` means no change outside the allowlist is attributable to this
+ * window's steps. `rolled-back` means one was and the repository now looks as
+ * it did before. Anything else is `rollback-incomplete`: the working tree is
+ * left exactly as the step made it and handed to the operator with the list,
+ * because a rollback that guesses at content it never recorded destroys work.
+ *
+ * A `clean` verdict can still carry `unattributed` paths. Those changed inside
+ * the window and no run in it recorded writing them, so they are the
+ * operator's, another process's, or a build artifact's, and nothing here may
+ * touch them.
  */
 export type WriteBoundaryStatus = "clean" | "rolled-back" | "rollback-incomplete";
 
+/**
+ * What the window's own runs recorded aiming a successful mutation at.
+ *
+ * This is the write-side witness the diff cannot be: the checkout says a path
+ * changed, and only the run's own tool-call record says whether the run is what
+ * changed it. The record comes from the same fold that grounds a sealed
+ * mutation report, so the boundary and the result contract judge one set of
+ * facts.
+ *
+ * A run can write through a channel no tool event enumerates, and then its path
+ * set is a lower bound rather than the whole list. That is not silently
+ * tolerated: the recorder knows which tools can do it (bash, verify, dispatch,
+ * steer, and any tool this process has no schema for) and reports the record
+ * open, which arrives here as `complete: false`. So the set is only ever read
+ * as a closed list for a run that could not have written outside it, and
+ * enforcement over a run that could stays exactly as strong as it was before
+ * attribution existed.
+ */
+export interface WriteBoundaryAttribution {
+	/**
+	 * Paths the window's runs aimed a successful mutation at. Absolute, or
+	 * relative to the workspace root; anything resolving outside the workspace is
+	 * dropped, because git could not have reported it as a change either.
+	 */
+	recorded: ReadonlyArray<string>;
+	/**
+	 * False when at least one step in the window has no closed write record: a
+	 * code step running a registered command, a runtime that publishes no tool
+	 * telemetry, a run whose telemetry came back with holes, or a run that
+	 * called a tool able to write a path its arguments do not name. An open
+	 * record cannot clear anybody, so the window falls back to blaming every
+	 * change outside the allowlist, and the verdict says it did.
+	 */
+	complete: boolean;
+}
+
 export interface WriteBoundaryVerdict {
 	version: 1;
 	/** Which scheduling window this covers, e.g. `wave-2` or `revalidate-suite.check.1`. */
@@ -243,12 +298,25 @@ export interface WriteBoundaryVerdict {
 	checkedAt: string;
 	changedPaths: ReadonlyArray<string>;
 	violations: ReadonlyArray<string>;
+	/**
+	 * Paths outside the allowlist that changed inside the window and that no run
+	 * in it recorded writing. Recorded so the operator can see them, never rolled
+	 * back: the window did not make them, so the baseline commit is not their
+	 * prior content.
+	 */
+	unattributed: ReadonlyArray<string>;
+	/** Whether every step in the window offered an enumerable write record. */
+	attributionComplete: boolean;
 	rolledBack: ReadonlyArray<WriteBoundaryRollback>;
 	unrecoverable: ReadonlyArray<WriteBoundaryUnrecoverable>;
 	status: WriteBoundaryStatus;
 	/** Typed failure reason, or null when the window stayed inside its boundary. */
 	reason: typeof WRITE_BOUNDARY_VIOLATION_REASON | null;
-	/** Operator-facing message naming the offending paths and the declaration. */
+	/**
+	 * Operator-facing message naming the offending paths and the declaration, or
+	 * naming the concurrent changes the window saw but did not cause. Null only
+	 * when neither happened.
+	 */
 	detail: string | null;
 	digest: string;
 }
@@ -258,6 +326,12 @@ export interface EnforceWriteBoundaryInput {
 	window: string;
 	stepIds: ReadonlyArray<string>;
 	allow: WriteBoundary;
+	/**
+	 * What the window's runs recorded writing. Absent means no caller offered a
+	 * record, which reads the same as an incomplete one: every change outside the
+	 * allowlist is blamed on the window.
+	 */
+	attribution?: WriteBoundaryAttribution;
 }
 
 function canonicalVerdict(verdict: Omit<WriteBoundaryVerdict, "digest">): string {
@@ -317,6 +391,22 @@ function rollbackPath(
 	return { rolledBack: { path: change.path, action: "restored", restoredFrom: `${snapshot.head}:${change.path}` } };
 }
 
+/**
+ * Whether one changed path falls inside what a run recorded writing.
+ *
+ * A recorded target is usually the exact file a write or edit named, but a
+ * command's delete target can be a directory, so a change under a recorded
+ * prefix counts as the same write. Matching is on segment boundaries: `work`
+ * does not cover `workspace/a.txt`.
+ */
+function withinRecordedWrite(recorded: ReadonlySet<string>, path: string): boolean {
+	if (recorded.has(path)) return true;
+	for (const target of recorded) {
+		if (path.startsWith(`${target}/`)) return true;
+	}
+	return false;
+}
+
 /**
  * Compare, roll back, and return the verdict. Never throws for a violation: a
  * violation is evidence the caller records and acts on, not an exception that
@@ -325,7 +415,21 @@ function rollbackPath(
 export function enforceWriteBoundary(input: EnforceWriteBoundaryInput): WriteBoundaryVerdict {
 	const allow = normalizeWriteBoundary(input.allow);
 	const changes = diffWorkspace(input.snapshot);
-	const violations = changes.filter((change) => !writeBoundaryCovers(allow, change.path));
+	const outside = changes.filter((change) => !writeBoundaryCovers(allow, change.path));
+	const attributionComplete = input.attribution?.complete === true;
+	const recorded = new Set<string>();
+	for (const target of input.attribution?.recorded ?? []) {
+		const relativeTarget = repoRelative(input.snapshot.root, target);
+		if (relativeTarget !== null) recorded.add(relativeTarget);
+	}
+	// Without a complete record nothing can be cleared, so the window keeps the
+	// whole diff. With one, only what the runs actually wrote is theirs.
+	const violations = attributionComplete
+		? outside.filter((change) => withinRecordedWrite(recorded, change.path))
+		: outside;
+	const unattributed = attributionComplete
+		? outside.filter((change) => !withinRecordedWrite(recorded, change.path))
+		: [];
 	const rolledBack: WriteBoundaryRollback[] = [];
 	const unrecoverable: WriteBoundaryUnrecoverable[] = [];
 	for (const change of violations) {
@@ -335,15 +439,15 @@ export function enforceWriteBoundary(input: EnforceWriteBoundaryInput): WriteBou
 	}
 	const status: WriteBoundaryStatus =
 		violations.length === 0 ? "clean" : unrecoverable.length === 0 ? "rolled-back" : "rollback-incomplete";
-	const attribution =
+	const who =
 		input.stepIds.length === 1
 			? `step '${input.stepIds[0]}'`
 			: `steps ${input.stepIds.map((id) => `'${id}'`).join(", ")} ran concurrently in one checkout, so the write cannot be attributed to one of them`;
-	const detail =
+	const violationDetail =
 		violations.length === 0
-			? null
+			? []
 			: [
-					`${attribution} wrote outside its declared boundary.`,
+					`${who} wrote outside its declared boundary.`,
 					`Unauthorized paths: ${violations.map((change) => change.path).join(", ")}.`,
 					`Declared writes: ${describeWriteBoundary(allow)}.`,
 					status === "rolled-back"
@@ -351,8 +455,21 @@ export function enforceWriteBoundary(input: EnforceWriteBoundaryInput): WriteBou
 						: `Rollback is incomplete; the working tree is left as the step made it. Unrestorable: ${unrecoverable
 								.map((entry) => `${entry.path} (${entry.reason})`)
 								.join("; ")}.`,
+					attributionComplete
+						? "Each was blamed on this window because a run in it recorded writing that path."
+						: "This window had no complete write record, so every change outside the declaration was blamed on it.",
 					"If the change was legitimate, widen the step's `writes:` declaration to cover it.",
-				].join(" ");
+				];
+	const concurrentDetail =
+		unattributed.length === 0
+			? []
+			: [
+					`Concurrent changes were seen in this window that no run in it recorded writing: ${unattributed
+						.map((change) => change.path)
+						.join(", ")}.`,
+					"They were left untouched, because a path this window did not write is not this window's to restore.",
+				];
+	const detail = [...violationDetail, ...concurrentDetail];
 	const body: Omit<WriteBoundaryVerdict, "digest"> = {
 		version: 1,
 		window: input.window,
@@ -363,11 +480,13 @@ export function enforceWriteBoundary(input: EnforceWriteBoundaryInput): WriteBou
 		checkedAt: new Date().toISOString(),
 		changedPaths: changes.map((change) => change.path),
 		violations: violations.map((change) => change.path),
+		unattributed: unattributed.map((change) => change.path),
+		attributionComplete,
 		rolledBack,
 		unrecoverable,
 		status,
 		reason: violations.length === 0 ? null : WRITE_BOUNDARY_VIOLATION_REASON,
-		detail,
+		detail: detail.length === 0 ? null : detail.join(" "),
 	};
 	return { ...body, digest: createHash("sha256").update(canonicalVerdict(body), "utf8").digest("hex") };
 }
@@ -387,16 +506,76 @@ export function assertWriteBoundaryInsideRoot(root: string, allow: WriteBoundary
 		// path a step is about to create.
 		while (probe !== realRoot && !existsSync(probe)) probe = dirname(probe);
 		const resolved = realpathSync(probe);
-		if (resolved !== realRoot && !resolved.startsWith(realRoot + sep)) {
+		// The root is inside itself. The prefix walk above stops at the root when
+		// a declared directory does not exist yet, and `pathBoundaryEntryCovers`
+		// answers a different question: it asks whether a changed path falls under
+		// a declaration, where the directory entry itself is not a change git ever
+		// reports. Asking it about the root would refuse every boundary naming a
+		// path the step is about to create.
+		if (resolved !== realRoot && !pathBoundaryEntryCovers(asDirectoryPathBoundary(realRoot), resolved)) {
 			throw new Error(`write boundary: entry '${entry}' resolves to ${resolved}, outside the workspace at ${realRoot}`);
 		}
 	}
 }
 
-/** Repo-relative form of an absolute path, or null when it is outside. */
+/**
+ * Refuse a declaration git will never report on.
+ *
+ * `git status` does not list an ignored path, so a boundary entry the
+ * repository ignores names a region enforcement is blind to: every window over
+ * it is certified clean without a single observation, which is a stronger claim
+ * than "nothing was checked" and reads as a passing one. That is the same
+ * defect `assertWriteBoundaryInsideRoot` refuses for an entry that leaves the
+ * workspace through a symlink, so it is refused in the same place and at the
+ * same time, before anything runs.
+ *
+ * A tracked path is reportable whatever the ignore rules say, and git's own
+ * index-aware check is what decides that, so this never refuses a path the
+ * repository is actually following.
+ */
+export function assertWriteBoundaryVisibleToGit(root: string, allow: WriteBoundary): void {
+	// Entry by entry rather than through `normalizeWriteBoundary`, whose 32-entry
+	// cap is a per-step declaration limit. A caller may legitimately ask this
+	// question about every entry a whole plan declared.
+	const entries = [...new Set(allow.map(normalizeWriteBoundaryEntry))].sort();
+	if (entries.length === 0) return;
+	const absolute = resolve(root);
+	let raw: string;
+	try {
+		raw = git(absolute, ["check-ignore", "-v", "-z", "--stdin"], `${entries.join("\0")}\0`);
+	} catch (error) {
+		// `check-ignore` exits 1 when nothing matched, which is the common answer
+		// and not a failure. Any other exit is a real inability to decide, and
+		// enforcement fails closed rather than assuming visibility.
+		const status = (error as { status?: number }).status;
+		if (status === 1) return;
+		throw new Error(
+			`write boundary: could not determine whether ${describeWriteBoundary(entries)} is ignored by git in ${absolute}: ${(error as Error).message}`,
+		);
+	}
+	const fields = raw.split("\0");
+	const refusals: string[] = [];
+	// `-v -z` emits source, line number, pattern, and pathname per match.
+	for (let index = 0; index + 3 < fields.length; index += 4) {
+		const [source, line, pattern, path] = fields.slice(index, index + 4);
+		if (path === undefined || path.length === 0) continue;
+		refusals.push(`'${path}' is ignored by ${source}:${line}:${pattern}`);
+	}
+	if (refusals.length === 0) return;
+	throw new Error(
+		`write boundary: ${refusals.join(", ")}. git status never reports an ignored path, so a boundary declared over one is verified against nothing and every window would be certified clean without an observation. Declare a path the repository tracks, or stop ignoring this one.`,
+	);
+}
+
+/**
+ * Workspace-relative form of a path, or null when it resolves outside. A
+ * relative input is taken as already workspace-relative, which is how a
+ * recorded write target and an absolute state directory both normalize here.
+ */
 function repoRelative(root: string, path: string): string | null {
-	const rel = relative(resolve(root), resolve(path));
-	if (rel.length === 0 || rel.startsWith("..") || rel.startsWith(`..${sep}`)) return null;
+	const base = resolve(root);
+	const rel = relative(base, resolve(base, path));
+	if (rel.length === 0 || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
 	return rel.split(sep).join("/");
 }