pi-crew 0.9.53 → 0.9.55

package/src/runtime/path-overlap.ts

@@ -0,0 +1,150 @@
+/**
+ * path-overlap.ts — write-path overlap detection for sequential scheduling (M5).
+ *
+ * Implements the writes-only path-intersection heuristic (per plan §11 decision
+ * #5). A pair of steps is considered overlapping ONLY when both declare the
+ * same write target (via `step.output`). Reads are intentionally ignored to
+ * avoid false positives (parallel reads are safe).
+ *
+ * Scope:
+ *   - export `detectWriteOverlap(stepA, stepB): boolean` — pair check
+ *   - export `selectNonOverlapping(steps, maxCount): WorkflowStep[]` — greedy
+ *     packer that returns at most `maxCount` steps such that no two returned
+ *     steps have overlapping write paths.
+ *   - export `filterReadyByWriteOverlap(taskIds, tasks, workflow, maxCount)` —
+ *     scheduler-side wrapper that translates TeamTaskState IDs to WorkflowSteps
+ *     and applies the overlap filter.
+ *
+ * Default greedy strategy: preserve declaration order; first step always wins
+ * because (a) deterministic for tests, (b) declaration order typically reflects
+ * author intent, (c) a future PR can swap to priority-based when M5 defaults
+ * flip to `true` in production.
+ *
+ * Out of scope: reads overlap detection (decision #5); deferral cap (decision
+ * #6; M5 first ship treats repeated deferral as best-effort; cap warning logged
+ * but not enforced, since M5 default = false means production isn't gated).
+ */
+
+import type { TeamTaskState } from "../state/types.ts";
+import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+
+/**
+ * Extract the canonical write-target path of a step.
+ *
+ * Returns:
+ *   - `step.output` if it is a non-empty string (the file path produced).
+ *   - `undefined` otherwise (no declared write target → step has no write
+ *     overlap risk).
+ *
+ * `step.output === false` means "explicitly no output"; treated as no write.
+ */
+function extractWritePath(step: WorkflowStep): string | undefined {
+	if (typeof step.output === "string" && step.output.length > 0) return step.output;
+	return undefined;
+}
+
+/**
+ * Pairwise check: do stepA and stepB both write to the same path?
+ *
+ * O(1). Both steps must declare an `output` string; otherwise no overlap.
+ *
+ * Examples:
+ *   detectWriteOverlap({output: 'a.md'}, {output: 'a.md'}) → true
+ *   detectWriteOverlap({output: 'a.md'}, {output: 'b.md'}) → false
+ *   detectWriteOverlap({output: 'a.md'}, {output: false})  → false
+ *   detectWriteOverlap({output: 'a.md'}, {})              → false
+ */
+export function detectWriteOverlap(stepA: WorkflowStep, stepB: WorkflowStep): boolean {
+	const pathA = extractWritePath(stepA);
+	const pathB = extractWritePath(stepB);
+	if (!pathA || !pathB) return false;
+	return pathA === pathB;
+}
+
+/**
+ * Greedy packer: pick up to `maxCount` steps from `steps` such that no two
+ * PICKED steps have overlapping write paths.
+ *
+ * Algorithm:
+ *   - Iterates over `steps` in order.
+ *   - First step is always picked.
+ *   - Each subsequent step is picked iff (a) it doesn't overlap with any
+ *     already-picked step AND (b) we haven't reached `maxCount`.
+ *
+ * Returns the picked subset (a NEW array; does not mutate input).
+ *
+ * Used by scheduler when `limits.serializeOnPathOverlap = true`.
+ */
+export function selectNonOverlapping(steps: WorkflowStep[], maxCount: number): WorkflowStep[] {
+	const picked: WorkflowStep[] = [];
+	if (maxCount <= 0 || steps.length === 0) return picked;
+	for (const step of steps) {
+		if (picked.length >= maxCount) break;
+		let conflict = false;
+		for (const existing of picked) {
+			if (detectWriteOverlap(step, existing)) {
+				conflict = true;
+				break;
+			}
+		}
+		if (!conflict) picked.push(step);
+	}
+	return picked;
+}
+
+/**
+ * Scheduler-side wrapper: given a list of ready task IDs (from the task-graph
+ * ready queue), filter them by write-path overlap using the workflow step
+ * definitions.
+ *
+ * Behavior:
+ *   - Resolves each task ID → `TeamTaskState` → `WorkflowStep` via
+ *     `task.stepId` matching `workflow.steps[i].id`.
+ *   - Tasks whose step is missing from the workflow (e.g. ad-hoc tasks) are
+ *     always included (treated as having no declared write path).
+ *   - Returns the same array (identity-equal) when `enabled` is false, so
+ *     callers can skip the filter cheaply.
+ *
+ * Used by the team-runner scheduler when `limits.serializeOnPathOverlap`
+ * is `true` (per plan §11 decision #6, default is `false` so this is a
+ * no-op in v0.9.17 unless the workflow author opts in).
+ */
+export function filterReadyByWriteOverlap(
+	readyTaskIds: string[],
+	tasks: TeamTaskState[],
+	workflow: WorkflowConfig,
+	maxCount: number,
+	enabled: boolean,
+): string[] {
+	if (!enabled || maxCount <= 0 || readyTaskIds.length === 0) return readyTaskIds;
+	const taskById = new Map<string, TeamTaskState>(tasks.map((task) => [task.id, task]));
+	const stepById = new Map<string, WorkflowStep>(workflow.steps.map((step) => [step.id, step]));
+	const pickedSteps: WorkflowStep[] = [];
+	const pickedTaskIds: string[] = [];
+	for (const taskId of readyTaskIds) {
+		if (pickedTaskIds.length >= maxCount) break;
+		const task = taskById.get(taskId);
+		if (!task?.stepId) {
+			// No step reference: treat as no declared write path → never conflicts.
+			pickedTaskIds.push(taskId);
+			continue;
+		}
+		const step = stepById.get(task.stepId);
+		if (!step) {
+			pickedTaskIds.push(taskId);
+			continue;
+		}
+		let conflict = false;
+		for (const existing of pickedSteps) {
+			if (detectWriteOverlap(step, existing)) {
+				conflict = true;
+				break;
+			}
+		}
+		if (!conflict) {
+			pickedTaskIds.push(taskId);
+			pickedSteps.push(step);
+		}
+	}
+	return pickedTaskIds;
+}

package/src/runtime/peer-dep.ts

@@ -0,0 +1,292 @@
+/**
+ * Robust resolution + async loading of the @earendil-works/pi-coding-agent
+ * peer dependency. Fixes the "Cannot find module '@earendil-works/pi-coding-agent'"
+ * crash that blocks ALL team runs when pi-crew and pi are installed in
+ * SEPARATE node_modules trees.
+ *
+ * PROBLEM (Windows / global installs — reported 2026-06-17)
+ * pi-crew is a pi EXTENSION. pi installs extensions under
+ * `~/.pi/agent/npm/node_modules/<ext>/`, but pi itself (the
+ * @earendil-works/pi-coding-agent package that extensions import from)
+ * usually lives in a DIFFERENT node_modules tree — a global one (nvm,
+ * %APPDATA%\npm, Volta, fnm, pnpm-global). Node's resolver only walks UP
+ * through ancestor `node_modules` of the importing file, so a file under
+ * `~/.pi/agent/npm/node_modules/pi-crew/...` CANNOT resolve a peer dep
+ * installed under `~/.nvm/.../lib/node_modules/`. Every static
+ * `import { X } from "@earendil-works/pi-coding-agent"` that executes inside
+ * a SPAWNED CHILD PROCESS (the detached background team runner started by
+ * async-runner.spawnBackgroundTeamRun) therefore crashes at module load,
+ * leaving all team runs permanently `queued`.
+ *
+ * ADDITIONAL CONSTRAINT (verified empirically 2026-06-17)
+ * pi-coding-agent ships as ESM-only (`"type":"module"`, exports map has only
+ * an `import` condition). CJS `require()` / `createRequire(dir)(name)` fails
+ * with ERR_PACKAGE_PATH_NOT_EXPORTED under plain node AND under jiti/tsx. The
+ * ONLY working load mechanism is a dynamic `import()` of the resolved ESM
+ * entry file URL. Hence: sync resolution of the DIR, async load of the MODULE.
+ *
+ * APPROACH
+ *  - resolvePeerDep()     (sync)  — find the install dir across many layouts.
+ *  - primePeerDep()       (async) — dynamic-import the resolved entry, cache
+ *                                   the module namespace. Memoized. Called
+ *                                   once per process during bootstrap.
+ *  - getAgentDir()        (sync)  — read the cached module's getAgentDir.
+ *                                   Falls back to a computed default if the
+ *                                   cache was never primed, so it NEVER throws.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { resolveNpmGlobalRoot } from "./pi-spawn.ts";
+
+/**
+ * The pi-coding-agent peer dependency package name(s) we can be loaded by.
+ * @earendil-works is the canonical scope; @mariozechner is the historical fork.
+ */
+export const PEER_DEP_NAMES = ["@earendil-works/pi-coding-agent", "@mariozechner/pi-coding-agent"] as const;
+
+/**
+ * Env var a parent pi-crew process sets on spawned children so they can resolve
+ * the peer dep WITHOUT running `npm root -g` (~200ms probe). The resolver
+ * checks this FIRST. Absent (older parent, direct invocation, tests) → falls
+ * through to the probing strategies. Also lets users override the resolution
+ * explicitly as a last-resort fix.
+ */
+export const PEER_DEP_DIR_ENV = "PI_CREW_PEER_DEP_DIR";
+
+type PeerDepModule = typeof import("@earendil-works/pi-coding-agent");
+
+interface ResolvedPeerDep {
+	dir: string;
+	name: string;
+	/** file:// URL of the ESM entry (exports["."].import || main). */
+	mainUrl: string;
+}
+
+let cachedResolve: ResolvedPeerDep | undefined | null = null;
+let cachedModule: PeerDepModule | undefined;
+let primingPromise: Promise<PeerDepModule> | undefined;
+
+/**
+ * Build the ordered list of "resolution bases" — paths to seed
+ * `createRequire(...).resolve()` from. Node walks UP `node_modules` from each
+ * base's directory, so any base inside (or beside) the peer dep's package
+ * tree will find it. Pure given env/process inputs; exported for unit tests.
+ */
+export function peerDepResolutionBases(): string[] {
+	const bases: string[] = [];
+
+	// 0. Parent-provided hint (fastest — no probe). Set by async-runner.
+	const envHint = process.env[PEER_DEP_DIR_ENV]?.trim();
+	if (envHint) bases.push(path.resolve(envHint));
+
+	// 1. This file's location — works when pi-crew and pi-coding-agent share a
+	//    node_modules ancestor (the common co-located install).
+	bases.push(fileURLToPath(import.meta.url));
+
+	// 2. The entry script. In the PARENT (main pi process) argv[1] is pi's CLI
+	//    script, which lives INSIDE pi-coding-agent's package → resolves. In a
+	//    SPAWNED CHILD argv[1] is a pi-crew script → cheap miss, falls through.
+	const argv1 = process.argv[1];
+	if (argv1) bases.push(path.resolve(argv1));
+
+	// 3. The Node binary's global node_modules. Covers nvm / nvm-windows /
+	//    Volta / fnm where pi-coding-agent is `npm i -g`'d: node is at
+	//    <prefix>/bin/node and globals live at <prefix>/lib/node_modules.
+	try {
+		const execDir = path.dirname(fs.realpathSync.native(process.execPath));
+		bases.push(path.join(path.dirname(execDir), "lib", "node_modules"));
+		// Some layouts (Windows global, or a bare node_modules sibling of bin).
+		bases.push(path.join(execDir, "node_modules"));
+	} catch {
+		/* realpath best-effort */
+	}
+
+	// 4. `npm root -g` — the canonical cross-layout global root (memoized in
+	//    pi-spawn.ts, ~200ms once). Derive the scoped package dirs from it.
+	const npmRoot = resolveNpmGlobalRoot();
+	if (npmRoot) {
+		for (const pkgName of PEER_DEP_NAMES) {
+			bases.push(path.join(npmRoot, ...pkgName.split("/")));
+		}
+	}
+
+	// 5. Windows %APPDATA%\npm static layout (legacy npm-global, pre-npm-root-g).
+	if (process.env.APPDATA) {
+		bases.push(path.join(process.env.APPDATA, "npm", "node_modules"));
+	}
+
+	return bases;
+}
+
+/** Pull the ESM entry path out of package.json (exports import || main). */
+function extractEsmMain(pkg: unknown): string | undefined {
+	if (!pkg || typeof pkg !== "object") return undefined;
+	const p = pkg as Record<string, unknown>;
+	const exp = p.exports;
+	if (exp && typeof exp === "object") {
+		const dot = (exp as Record<string, unknown>)["."];
+		if (dot && typeof dot === "object") {
+			const d = dot as Record<string, unknown>;
+			const rel = d.import ?? d.default ?? d.module;
+			if (typeof rel === "string") return rel;
+		} else if (typeof dot === "string") {
+			return dot;
+		}
+	}
+	const main = p.main;
+	return typeof main === "string" ? main : undefined;
+}
+
+/**
+ * Walk the node_modules resolution algorithm MANUALLY from `start` looking for
+ * any of `names`. We do NOT use createRequire/require.resolve here because
+ * pi-coding-agent ships an ESM-only package with a restrictive exports map
+ * (only the `.` import condition) — `require.resolve("<pkg>/package.json")`
+ * and `require.resolve("<pkg>")` both throw ERR_PACKAGE_PATH_NOT_EXPORTED.
+ * Reading package.json directly from the walked dir sidesteps the exports map
+ * entirely (exports only governs subpath IMPORTS, not raw file reads).
+ *
+ * At each directory we check BOTH `<dir>/node_modules/<pkg>` (the standard
+ * container case) AND `<dir>/<pkg>` (handles a base that IS a node_modules
+ * dir, e.g. the output of `npm root -g`), then walk up to root.
+ */
+function findPackageDir(start: string, names: readonly string[]): { dir: string; name: string } | undefined {
+	let dir = path.resolve(start);
+	try {
+		if (fs.statSync(dir).isFile()) dir = path.dirname(dir);
+	} catch {
+		/* treat as directory */
+	}
+	while (true) {
+		for (const name of names) {
+			const segs = name.split("/");
+			const candidates = [path.join(dir, "node_modules", ...segs, "package.json"), path.join(dir, ...segs, "package.json")];
+			for (const pkgJson of candidates) {
+				try {
+					const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+					if (pkg?.name === name) {
+						return { dir: path.dirname(pkgJson), name };
+					}
+				} catch {
+					/* not present at this candidate */
+				}
+			}
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break; // reached filesystem root
+		dir = parent;
+	}
+	return undefined;
+}
+
+function tryResolveFrom(base: string): ResolvedPeerDep | undefined {
+	const found = findPackageDir(base, PEER_DEP_NAMES);
+	if (!found) return undefined;
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(found.dir, "package.json"), "utf-8"));
+		const mainRel = extractEsmMain(pkg);
+		if (!mainRel) return undefined;
+		const mainAbs = path.resolve(found.dir, mainRel);
+		if (!fs.existsSync(mainAbs)) return undefined;
+		return {
+			dir: found.dir,
+			name: found.name,
+			mainUrl: pathToFileURL(mainAbs).href,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/** Resolve the peer dep install dir + ESM entry URL. Memoized (sync). */
+export function resolvePeerDep(): ResolvedPeerDep | undefined {
+	if (cachedResolve !== null) return cachedResolve ?? undefined;
+	for (const base of peerDepResolutionBases()) {
+		const found = tryResolveFrom(base);
+		if (found) {
+			cachedResolve = found;
+			return found;
+		}
+	}
+	cachedResolve = null; // mark attempted-and-failed; don't re-probe per call
+	return undefined;
+}
+
+/** Just the install directory (for env-hint propagation to children). */
+export function resolvePeerDepDir(): string | undefined {
+	return resolvePeerDep()?.dir;
+}
+
+/**
+ * Dynamic-import the peer dep module, caching the namespace. Memoized via a
+ * shared promise so concurrent callers share one load. On failure the promise
+ * is cleared so a later caller can retry. Safe to call repeatedly.
+ */
+export function primePeerDep(): Promise<PeerDepModule> {
+	if (cachedModule) return Promise.resolve(cachedModule);
+	if (primingPromise) return primingPromise;
+	primingPromise = (async () => {
+		const resolved = resolvePeerDep();
+		if (!resolved) {
+			throw new Error(buildMissingMessage());
+		}
+		// LAZY: defer dynamic import of module to its call site.
+		cachedModule = (await import(resolved.mainUrl)) as PeerDepModule;
+		return cachedModule;
+	})();
+	// Clear on failure so a later caller can retry (e.g. after env fix).
+	primingPromise.catch(() => {
+		primingPromise = undefined;
+	});
+	return primingPromise;
+}
+
+/** Async module accessor (primes if needed). */
+export async function loadPeerDep(): Promise<PeerDepModule> {
+	return primePeerDep();
+}
+
+function buildMissingMessage(): string {
+	return (
+		`pi-crew could not resolve the @earendil-works/pi-coding-agent peer dependency.\n` +
+		`This usually means pi-crew and pi are installed in separate node_modules trees\n` +
+		`(e.g. pi-crew under ~/.pi/agent/npm/ but pi under an nvm/Volta/fnm global scope).\n` +
+		`Resolution bases tried:\n` +
+		peerDepResolutionBases()
+			.map((b) => `  - ${b}`)
+			.join("\n") +
+		`\nFix: install pi-crew in the SAME scope as pi, e.g.\n` +
+		`  npm install -g @earendil-works/pi-crew\n` +
+		`or set the env var ${PEER_DEP_DIR_ENV}=<path to the pi-coding-agent package dir>.`
+	);
+}
+
+/**
+ * Read the user agent dir via the REAL peer-dep getAgentDir (fork-aware:
+ * correct for pi, tau, and renamed forks). Sync; reads the primed cache.
+ *
+ * If the cache was never primed (e.g. called before bootstrap completes, or
+ * prime failed), falls back to a computed default so it NEVER throws. The
+ * default matches standard pi (`~/.pi/agent`) and respects the
+ * `PI_CODING_AGENT_DIR` override — correct for the overwhelmingly common
+ * case. Forks rely on the primed real function (register.ts primes at startup).
+ */
+export function getAgentDir(): string {
+	if (cachedModule?.getAgentDir) {
+		try {
+			return cachedModule.getAgentDir();
+		} catch {
+			/* fall through to computed default */
+		}
+	}
+	return process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+}
+
+/** @internal — reset all caches for unit tests. */
+export function __resetPeerDepCacheForTest(): void {
+	cachedResolve = null;
+	cachedModule = undefined;
+	primingPromise = undefined;
+}

package/src/runtime/per-write-validator.ts

@@ -0,0 +1,181 @@
+/**
+ * Per-write validator — real-time feedback on file writes/edits (T5).
+ *
+ * Distilled from pi-lens (apmantza) — the "inline channel": on every
+ * `write`/`edit` tool result, run a CHEAP synchronous validator for the file
+ * type and, on failure, append a `🔴` blocker block to the tool result the
+ * agent sees next. This catches silent-breaking errors (malformed JSON
+ * config) at the moment they're introduced instead of at the next load.
+ *
+ * CRITICAL LATENCY-SAFETY DESIGN (the reason this is a careful slice, not the
+ * full pi-lens pipeline): pi-lens runs LSP servers + linters per write. That
+ * is expensive and would cause latency storms if naively ported (seconds of
+ * spawn per edit, firing in the main session AND every worker). This module's
+ * v1 deliberately ships ONLY zero-cost, zero-spawn, synchronous validators:
+ *
+ *   - `json` → `JSON.parse` (nanoseconds, built-in, no process spawn).
+ *
+ * The registry is extensible — future validators (`.js` → `node --check`,
+ * `.sh` → `bash -n`, `.py` → `py_compile`) are process-spawning and MUST be
+ * added behind an explicit opt-in (never default-on) to preserve the
+ * latency guarantee. A process-spawning validator would also need to be async
+ * and debounced (pi-lens's `inFlightPipelines` / debounce-window pattern),
+ * which the current sync contract intentionally avoids.
+ *
+ * Contract guarantees for v1:
+ *   - Synchronous. No `await`, no `spawn`, no disk write.
+ *   - One disk READ per validated file (after a cheap extension check, so
+ *     non-validated files cost nothing).
+ *   - Dedup by content: the same path+content is validated at most once per
+ *     process (a repeated identical write doesn't re-report).
+ *   - Silent on success; appends exactly one TextContent block on failure.
+ *   - Best-effort: any internal error is swallowed (never breaks a write).
+ *
+ * @module per-write-validator
+ */
+
+import { readFileSync } from "node:fs";
+import { extname as pathExtname } from "node:path";
+
+/** Outcome of validating a file's content. */
+export interface ValidationResult {
+	ok: boolean;
+	/** Human-readable error message when `ok` is false. */
+	error?: string;
+}
+
+/** A synchronous validator: content + path → result. */
+export type PerWriteValidator = (content: string, filePath: string) => ValidationResult;
+
+// ─────────────────────────────────────────────────────────────────────────
+// Validators (zero-cost, synchronous, dependency-free for v1)
+// ─────────────────────────────────────────────────────────────────────────
+
+/** JSON: parse with `JSON.parse`. Catches malformed config/manifests instantly. */
+export function validateJson(content: string, _filePath: string): ValidationResult {
+	if (content.trim() === "") return { ok: true }; // empty file is valid JSON absence, not a parse error
+	try {
+		JSON.parse(content);
+		return { ok: true };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, error: `Invalid JSON: ${message}` };
+	}
+}
+
+/**
+ * Registry of default-on validators, keyed by extension (lowercase, no dot).
+ * ONLY zero-cost synchronous validators belong here. Process-spawning
+ * validators must be registered via a future opt-in path (see module doc).
+ */
+const DEFAULT_VALIDATORS: ReadonlyMap<string, PerWriteValidator> = new Map([["json", validateJson]]);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Dedup cache (path → last-validated content). Bounded; small.
+// ─────────────────────────────────────────────────────────────────────────
+
+const MAX_DEDUP_ENTRIES = 256;
+const seenContent = new Map<string, string>();
+
+function rememberSeen(path: string, content: string): void {
+	if (seenContent.has(path)) seenContent.delete(path); // refresh LRU position
+	seenContent.set(path, content);
+	while (seenContent.size > MAX_DEDUP_ENTRIES) {
+		const oldest = seenContent.keys().next().value;
+		if (oldest === undefined) break;
+		seenContent.delete(oldest);
+	}
+}
+
+/** Test seam: reset the dedup cache between tests. */
+export function resetPerWriteValidatorCache(): void {
+	seenContent.clear();
+}
+
+/**
+ * Replace the validator registry (test seam). Production uses
+ * DEFAULT_VALIDATORS; tests inject a custom map to exercise specific extensions.
+ */
+let validators: ReadonlyMap<string, PerWriteValidator> = DEFAULT_VALIDATORS;
+
+export function setPerWriteValidatorsForTest(map: ReadonlyMap<string, PerWriteValidator> | undefined): void {
+	validators = map ?? DEFAULT_VALIDATORS;
+}
+
+/**
+ * Normalise an extension to the registry key form (lowercase, no leading dot).
+ * "" for files with no extension.
+ */
+export function extensionKey(filePath: string): string {
+	return pathExtname(filePath).replace(/^\./, "").toLowerCase();
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Path extraction from a tool_result event input (defensive — pi-ai types
+// aren't exported here, so accept a record and probe common field names).
+// ─────────────────────────────────────────────────────────────────────────
+
+const PATH_FIELDS = ["filePath", "path", "file"] as const;
+
+/** Extract the written/edited path from a tool result input, if present. */
+export function extractPathFromInput(input: unknown): string | undefined {
+	if (!input || typeof input !== "object") return undefined;
+	const record = input as Record<string, unknown>;
+	for (const field of PATH_FIELDS) {
+		const value = record[field];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return undefined;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Core entry point
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Validate a just-written/edited file. Returns `null` when there is nothing
+ * to report (no validator for the extension, dedup hit, file unreadable, or
+ * the content is valid). Returns a `ValidationResult` with `ok:false` when the
+ * content fails validation.
+ *
+ * Reads the file from disk (it's already written by `tool_result` time) so the
+ * logic is uniform across `write` (full content) and `edit` (patch). The disk
+ * read happens ONLY after a cheap extension check, so non-validated files cost
+ * nothing.
+ */
+export function validateWrittenFile(filePath: string): ValidationResult | null {
+	const key = extensionKey(filePath);
+	const validator = validators.get(key);
+	if (!validator) return null; // cheap skip: no validator for this file type
+	let content: string;
+	try {
+		content = readFileSync(filePath, "utf-8");
+	} catch {
+		// Unreadable / missing / permission denied — can't validate; never block.
+		return null;
+	}
+	// Dedup: identical content already validated this process → don't re-report.
+	if (seenContent.get(filePath) === content) return null;
+	rememberSeen(filePath, content);
+	const result = validator(content, filePath);
+	return result.ok ? null : result;
+}
+
+/**
+ * Build the TextContent block to append to a tool_result on validation failure.
+ * Uses a strong `🔴` prefix so the agent treats it as a real signal and fixes
+ * the file before continuing.
+ */
+export function buildValidationBlocker(filePath: string, error: string): { type: "text"; text: string } {
+	return {
+		type: "text",
+		text: [
+			"",
+			"🔴 pi-crew per-write check FAILED",
+			`   ${filePath}`,
+			`   ${error}`,
+			"   The file you just wrote is malformed. Fix it now — a broken file here will",
+			"   silently fail the next load/parse. Re-write the file with valid content before continuing.",
+		].join("\n"),
+	};
+}