@cratis/pi 7.1.0 → 7.1.2

package/package/corpus/harnesses/pi/extensions/cratis-hooks/index.ts

@@ -9,7 +9,17 @@
  *   Claude PreToolUse  (Write|Edit)  →  Pi `tool_call`      →  cratis-guard-writes.sh  (exit 2 = block)
  *   Claude PreToolUse  (Bash)        →  Pi `tool_call`      →  cratis-guard-store-mutations.sh  (exit 2 = block)
  *   Claude PostToolUse (Write|Edit)  →  Pi `tool_result`    →  cratis-pattern-scan.sh  (advisory context)
- *   Claude Stop                       →  Pi `agent_settled`  →  cratis-quality-gate.sh  (exit 2 = keep going)
+ *   Explicit Pi `cratis_quality_gate` tool → cratis-quality-gate.sh  (exit 2 = failed)
+ *
+ * The quality gate is the one deliberate difference from Claude. It builds and tests the repository, which can
+ * take many minutes, and Pi awaits `agent_settled` handlers while deferring the next prompt — so a gate run there
+ * froze the session between prompts, invisibly and with no way to cancel it. Here the gate is an explicit tool
+ * the model runs in the foreground: it shows progress, Escape cancels it, it stops at a deadline
+ * (CRATIS_HOOKS_GATE_TIMEOUT_SECONDS, default 5 minutes, maximum 10 minutes). A timeout or cancellation
+ * is reported as "not verified", never as a pass. It never runs in the background, where it would race the agent's next edits.
+ * It is not invoked at every prompt boundary: use affected-project checks while iterating, then run the
+ * repository's full CI-equivalent checks before declaring completion or pushing/opening a PR. The explicit tool
+ * selects gates for all current working-tree changes; it is not a substitute for the full CI gate.
  *
  * Nothing here duplicates corpus content: it is adapter machinery, the Pi peer of the Claude
  * `hooks` block in `.claude/settings.json`. Every environment escape hatch the scripts honor
@@ -25,7 +35,27 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	gateLogDirectory,
+	gateTimeoutSeconds,
+	latestGateLog,
+	MAX_GATE_TIMEOUT_SECONDS,
+	MIN_GATE_TIMEOUT_SECONDS,
+	parseGatePlan,
+	PLAN_TIMEOUT_MS,
+	FINGERPRINT_TIMEOUT_MS,
+	runBounded,
+	tailLines,
+	workingTreeFingerprint,
+} from "./quality-gate.ts";
+
+export const QUALITY_GATE_TOOL_NAME = "cratis_quality_gate";
+const HEARTBEAT_MS = 10_000;
+const TAIL_LINES = 60;
+// runBounded escalates after 5s and settles within another 2s if a child holds its pipes.
+const SHUTDOWN_CLEANUP_MS = 8_000;
 
 const extensionPath = fileURLToPath(import.meta.url);
 const bundledCorpusRoot = path.resolve(path.dirname(extensionPath), "..", "..", "..", "..");
@@ -149,11 +179,21 @@ export default function (pi: ExtensionAPI) {
 	const patternScan = path.join(scriptsDir, "cratis-pattern-scan.sh");
 	const qualityGate = path.join(scriptsDir, "cratis-quality-gate.sh");
 
-	// Mirrors Claude's `stop_hook_active`: true only while the model is continuing because the
-	// gate already blocked once this user turn, so the gate never blocks twice in a row (no loop).
-	let gateActive = false;
-	pi.on("input", async (event) => {
-		if (event.source !== "extension") gateActive = false; // a fresh user turn resets the guard
+	// The explicit gate owns its subprocesses; shutdown also cancels a still-running tool.
+	const activeGateRuns = new Map<AbortController, Promise<void>>();
+	pi.on("session_shutdown", async () => {
+		const runs = [...activeGateRuns];
+		for (const [controller] of runs) controller.abort();
+		// Pi exits when shutdown handlers return. Let cancelled runs escalate to SIGKILL first.
+		let timer: NodeJS.Timeout | undefined;
+		try {
+			await Promise.race([
+				Promise.allSettled(runs.map(([, cleanup]) => cleanup)),
+				new Promise<void>((resolve) => { timer = setTimeout(resolve, SHUTDOWN_CLEANUP_MS); }),
+			]);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
 	});
 
 	// ── PreToolUse → guard writes and store-mutating cratis commands (blocking) ──
@@ -214,31 +254,149 @@ export default function (pi: ExtensionAPI) {
 		return { content: [...existing, { type: "text", text: `\n\n[cratis-hooks]\n${reminder.trim()}` }] };
 	});
 
-	// ── Stop → quality gate (re-runs the gates the change touched; keeps the model going on failure) ──
-	pi.on("agent_settled", async (_event, ctx) => {
-		if (ctx.mode === "print" || ctx.mode === "json") return;
-		if (!isInstalled(qualityGate)) return;
-		const payload = JSON.stringify({
-			session_id: ctx.sessionManager.getSessionId?.() ?? "nosession",
-			stop_hook_active: gateActive,
+	// The quality gate is only run by its explicit tool, never by a turn-end handler.
+	const sessionIdOf = (ctx: ExtensionContext) => ctx.sessionManager.getSessionId?.() ?? "nosession";
+	const gatePayload = (sessionId: string) => JSON.stringify({ session_id: sessionId, stop_hook_active: false });
+
+	/** The gates the current changes would run, from the script's own dry run. Bounded; never runs a gate. */
+	async function planGates(ctx: ExtensionContext, root: string, signal?: AbortSignal): Promise<{ gates: string[]; problem?: string }> {
+		const run = await runBounded("bash", [qualityGate], {
+			cwd: ctx.cwd,
+			stdin: gatePayload(sessionIdOf(ctx)),
+			timeoutMs: PLAN_TIMEOUT_MS,
+			signal,
+			env: { ...process.env, CLAUDE_PROJECT_DIR: root, CRATIS_HOOKS_GATE_DRYRUN: "1" },
 		});
-		const run = await runScript(qualityGate, payload, ctx.cwd);
-
-		// A gate that cannot run has not passed. Say so rather than letting the turn end quietly,
-		// but only once per user turn, on the same re-entry guard a real gate failure uses.
-		if (run.failed && !gateActive) {
-			gateActive = true;
-			pi.sendUserMessage(
-				`The Cratis quality gate is installed at ${qualityGate} but could not be run, so nothing was verified this turn.` +
-					`${run.stderr.trim() ? `\n\n${run.stderr.trim()}` : ""}`,
-				{ deliverAs: "followUp" },
-			);
-			return;
-		}
-		if (run.code === 2 && !gateActive) {
-			gateActive = true; // don't block again until the next user turn resets it
-			const message = run.stderr.trim() || "A Cratis quality gate failed. Fix it and re-run the gate.";
-			pi.sendUserMessage(message, { deliverAs: "followUp" });
-		}
+		const gates = parseGatePlan(run.stderr);
+		if (run.aborted) return { gates: [], problem: "its dry run was cancelled" };
+		if (run.timedOut) return { gates, problem: `its dry run did not finish within ${PLAN_TIMEOUT_MS / 1000}s` };
+		if (run.failed || run.code !== 0) return { gates, problem: `its dry run could not be completed (exit ${run.code ?? "none"})` };
+		return { gates };
+	}
+
+	// ── The quality gate itself: explicit, foreground, bounded, cancellable ──
+	pi.registerTool({
+		name: QUALITY_GATE_TOOL_NAME,
+		label: "Cratis quality gate",
+		description:
+			"Run the Cratis quality gate (.cratis/ai/hooks/scripts/cratis-quality-gate.sh): the build, spec and lint gates the current " +
+			"working-tree changes touch, configured in quality-gates.json. Runs in the foreground with a deadline and can be cancelled. " +
+			"A failure, a timeout or a cancellation is returned as an error and means the change is NOT verified. " +
+			"Run it explicitly at a verification checkpoint, not after every prompt. It selects gates for all current " +
+			"working-tree changes, not the complete CI matrix; run CI-equivalent gates before claiming completion or pushing/opening a PR. " +
+			"Tracked-file stability is Git-visible, not byte-exact: lossy clean/EOL conversion and assume-unchanged/skip-worktree " +
+			"can hide raw disk changes. Verify raw content independently or remove those settings before relying on this check.",
+		promptSnippet: "Run the Cratis quality gate for the current changes (bounded, cancellable)",
+		parameters: Type.Object({
+			timeoutSeconds: Type.Optional(
+				Type.Integer({
+					minimum: MIN_GATE_TIMEOUT_SECONDS,
+					maximum: MAX_GATE_TIMEOUT_SECONDS,
+					description:
+						"Stop the gate after this many seconds (default 300; maximum 600). Raise it only for a concrete reason within the authorized execution budget.",
+				}),
+			),
+		}),
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			if (!isInstalled(qualityGate)) {
+				return { content: [{ type: "text", text: `No Cratis quality gate is installed (${qualityGate}), so nothing was checked.` }], details: { status: "not-installed" } };
+			}
+			if (process.env.CRATIS_HOOKS_SKIP_GATE === "1") {
+				return { content: [{ type: "text", text: "CRATIS_HOOKS_SKIP_GATE=1 is set, so the Cratis quality gate was skipped and nothing was verified." }], details: { status: "skipped" } };
+			}
+			if (process.env.CRATIS_HOOKS_GATE_DRYRUN === "1") {
+				return { content: [{ type: "text", text: "CRATIS_HOOKS_GATE_DRYRUN=1 is set: this is a dry run, NOT VERIFIED. No gates were executed." }], details: { status: "dry-run" } };
+			}
+
+			const timeoutSeconds = gateTimeoutSeconds(params.timeoutSeconds);
+			const sessionId = sessionIdOf(ctx);
+			const started = Date.now();
+			const deadline = started + timeoutSeconds * 1000;
+			const cancel = new AbortController();
+			const expired = new AbortController();
+			const deadlineTimer = setTimeout(() => expired.abort(), timeoutSeconds * 1000);
+			const operationSignal = AbortSignal.any([...(signal ? [signal] : []), cancel.signal, expired.signal]);
+			let completed!: () => void;
+			const cleanup = new Promise<void>((resolve) => { completed = resolve; });
+			activeGateRuns.set(cancel, cleanup);
+			try {
+			const reportTimedOut = () => {
+				const last = latestGateLog(gateLogDirectory(sessionId), started);
+				const tail = last ? tailLines(last.file, TAIL_LINES) : "";
+				throw new Error(`The Cratis quality gate TIMED OUT after ${duration(timeoutSeconds * 1000)}${last ? ` while running '${last.gate}'` : ""}. This is not a pass: nothing was verified.` +
+					(last ? `\n\nGate log: ${last.file}` : "") +
+					(tail ? `\n\n--- last ${TAIL_LINES} lines ---\n${tail}\n--- end ---` : ""));
+			};
+			const reportInterrupted = () => {
+				if (expired.signal.aborted) reportTimedOut();
+				if (operationSignal.aborted) throw new Error("The Cratis quality gate was cancelled. Nothing was verified.");
+			};
+			const remaining = () => Math.max(1, deadline - Date.now());
+			const logDirectory = gateLogDirectory(sessionId);
+			onUpdate?.({ content: [{ type: "text", text: `Planning Cratis quality gate (${duration(timeoutSeconds * 1000)} deadline). Escape cancels.` }], details: { status: "planning", timeoutSeconds } });
+			reportInterrupted();
+			const before = await workingTreeFingerprint(ctx.cwd, Math.min(FINGERPRINT_TIMEOUT_MS, remaining()), operationSignal);
+			reportInterrupted();
+			if (before.kind === "not-repository") throw new Error("The Cratis quality gate is not in a Git repository; nothing was verified.");
+			if (before.kind === "unknown") throw new Error(`The working tree could not be checked before the Cratis quality gate${before.reason ? `: ${before.reason}` : ""}. Nothing was verified.`);
+			const plan = await planGates(ctx, before.root, operationSignal);
+			reportInterrupted();
+			if (plan.problem) throw new Error(`The Cratis quality gate plan could not be completed: ${plan.problem}. Nothing was verified.`);
+			const planned = plan.gates.length > 0 ? plan.gates.join(", ") : "none planned";
+			const progress = (elapsedMs: number) => {
+				const current = latestGateLog(logDirectory, started)?.gate;
+				onUpdate?.({
+					content: [
+						{
+							type: "text",
+							text: `Cratis quality gate running${current ? ` ${current}` : ""}: ${duration(elapsedMs)} of ${duration(timeoutSeconds * 1000)} (gates: ${planned}). Escape cancels.`,
+						},
+					],
+					details: { status: "running", gates: plan.gates, current, elapsedMs, timeoutSeconds },
+				});
+			};
+			progress(Date.now() - started);
+
+			const run = await runBounded("bash", [qualityGate], {
+				cwd: ctx.cwd,
+				stdin: gatePayload(sessionId),
+				timeoutMs: remaining(),
+				signal: operationSignal,
+				env: { ...process.env, CLAUDE_PROJECT_DIR: before.root },
+				onHeartbeat: () => progress(Date.now() - started),
+				heartbeatMs: HEARTBEAT_MS,
+			});
+			// Cancellation never starts another Git process. Only a successful gate needs a post-run fingerprint.
+			if (run.aborted || operationSignal.aborted) reportInterrupted();
+			if (run.timedOut) reportTimedOut();
+			const notes = run.stderr.trim() ? `\n\n${run.stderr.trim()}` : "";
+			if (run.failed) {
+				throw new Error(`The Cratis quality gate is installed at ${qualityGate} but could not be run, so nothing was verified.${notes}`);
+			}
+			if (run.code === 2) throw new Error(run.stderr.trim() || "A Cratis quality gate failed. Fix it and re-run the gate.");
+			if (run.code !== 0) throw new Error(`The Cratis quality gate exited unexpectedly with code ${run.code ?? "none"}; treat the change as not verified.${notes}`);
+			const after = await workingTreeFingerprint(ctx.cwd, Math.min(FINGERPRINT_TIMEOUT_MS, remaining()), operationSignal);
+			reportInterrupted();
+			if (before.kind !== "ok" || after.kind !== "ok" || before.value !== after.value) {
+				throw new Error("The working tree changed while the Cratis quality gate ran (or could not be checked afterward). The gate tested an older tree; this tree is NOT VERIFIED. Re-run after changes settle.");
+			}
+			const summary =
+				plan.gates.length > 0
+					? `The Cratis quality gate passed in ${duration(run.durationMs)} (gates: ${planned}).`
+					: "No Cratis quality gate was planned for the current changes; nothing was verified by this tool.";
+			return { content: [{ type: "text", text: `${summary}${notes}` }], details: { status: plan.gates.length > 0 ? "passed" : "no-applicable-gates", gates: plan.gates, durationMs: run.durationMs } };
+			} finally {
+				clearTimeout(deadlineTimer);
+				activeGateRuns.delete(cancel);
+				completed();
+			}
+		},
 	});
 }
+
+function duration(ms: number): string {
+	const seconds = Math.round(ms / 1000);
+	return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, "0")}s`;
+}

package/package/corpus/harnesses/pi/extensions/cratis-hooks/quality-gate.ts

@@ -0,0 +1,358 @@
+/**
+ * Bounded, cancellable process execution for the Cratis quality gate in Pi.
+ *
+ * The gate builds and tests the repository, which can take many minutes and, when a test host
+ * hangs, never finish at all. Everything here exists so that a gate run is always bounded: it
+ * stops at a deadline or when its caller cancels, the whole process tree is stopped (not just the
+ * `bash` running the script), and the caller learns which of those happened rather than seeing a
+ * bare exit code. A gate that timed out or was cancelled verified nothing, and is reported as such.
+ */
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+/** How long one explicit gate run may take before it is stopped and reported as timed out. */
+export const DEFAULT_GATE_TIMEOUT_SECONDS = 300;
+export const MIN_GATE_TIMEOUT_SECONDS = 1;
+export const MAX_GATE_TIMEOUT_SECONDS = 600;
+/** The dispatch plan is `git diff` plus `jq`; anything slower than this is itself a problem. */
+export const PLAN_TIMEOUT_MS = 30_000;
+export const FINGERPRINT_TIMEOUT_MS = 15_000;
+
+const OUTPUT_CAP = 256 * 1024;
+const KILL_GRACE_MS = 5_000;
+const CLOSE_GRACE_MS = 2_000;
+
+export interface BoundedRun {
+	/** Exit code, or null when the process was stopped by a signal or never started. */
+	code: number | null;
+	stdout: string;
+	/** True when stdout exceeded the retained output cap; never interpret a partial Git status. */
+	stdoutTruncated: boolean;
+	stderr: string;
+	/** Stopped because the deadline passed. */
+	timedOut: boolean;
+	/** Stopped because the caller's signal aborted. */
+	aborted: boolean;
+	/** Could not be started at all (or bash could not find the script: exit 127). */
+	failed: boolean;
+	durationMs: number;
+}
+
+export interface BoundedRunOptions {
+	cwd: string;
+	stdin?: string;
+	timeoutMs: number;
+	signal?: AbortSignal;
+	env?: NodeJS.ProcessEnv;
+	/** Receives raw stdout chunks, for callers that hash output instead of keeping it. */
+	onStdout?: (chunk: Buffer) => void;
+	/** Called every `heartbeatMs` while the process runs. */
+	onHeartbeat?: (elapsedMs: number) => void;
+	heartbeatMs?: number;
+	killGraceMs?: number;
+}
+
+function appendCapped(current: string, chunk: string): string {
+	const next = current + chunk;
+	return next.length > OUTPUT_CAP ? next.slice(next.length - OUTPUT_CAP) : next;
+}
+
+/**
+ * Run a command with a hard deadline. Never throws and always settles.
+ *
+ * On POSIX the command runs in its own process group, so stopping it also stops what it started —
+ * `dotnet test` and its test hosts, not only the `bash` that launched them. Stopping sends SIGTERM,
+ * then SIGKILL after a grace period, and the promise settles even if a descendant keeps a pipe open.
+ */
+export function runBounded(command: string, args: string[], options: BoundedRunOptions): Promise<BoundedRun> {
+	const started = Date.now();
+	return new Promise<BoundedRun>((resolve) => {
+		const useGroup = process.platform !== "win32";
+		let proc: ReturnType<typeof spawn>;
+		try {
+			proc = spawn(command, args, {
+				cwd: options.cwd,
+				env: options.env ?? process.env,
+				stdio: ["pipe", "pipe", "pipe"],
+				detached: useGroup,
+			});
+		} catch (error) {
+			resolve({ code: null, stdout: "", stdoutTruncated: false, stderr: String(error), timedOut: false, aborted: false, failed: true, durationMs: 0 });
+			return;
+		}
+
+		let stdout = "";
+		let stdoutBytes = 0;
+		let stderr = "";
+		const stdoutDecoder = new StringDecoder("utf8");
+		const stderrDecoder = new StringDecoder("utf8");
+		let timedOut = false;
+		let aborted = false;
+		let exitCode: number | null = null;
+		let settled = false;
+		let stopping = false;
+		let closed = false;
+		const timers: NodeJS.Timeout[] = [];
+
+		const signalTree = (signal: NodeJS.Signals) => {
+			try {
+				if (useGroup && proc.pid !== undefined) process.kill(-proc.pid, signal);
+				else proc.kill(signal);
+			} catch {
+				try {
+					proc.kill(signal);
+				} catch {
+					/* already gone */
+				}
+			}
+		};
+		const stop = () => {
+			stopping = true;
+			signalTree("SIGTERM");
+			// The parent may close immediately while its children ignore TERM. Never finish before escalation.
+			timers.push(setTimeout(() => {
+				signalTree("SIGKILL");
+				if (closed) finish();
+			}, options.killGraceMs ?? KILL_GRACE_MS));
+			// Settle even if a descendant holds a pipe open after escalation.
+			timers.push(setTimeout(() => finish(), (options.killGraceMs ?? KILL_GRACE_MS) + CLOSE_GRACE_MS));
+		};
+		const onAbort = () => {
+			if (settled || timedOut || aborted) return;
+			aborted = true;
+			stop();
+		};
+		const finish = (failed = false) => {
+			if (settled) return;
+			settled = true;
+			stdout = appendCapped(stdout, stdoutDecoder.end());
+			stderr = appendCapped(stderr, stderrDecoder.end());
+			for (const timer of timers) clearTimeout(timer);
+			options.signal?.removeEventListener("abort", onAbort);
+			resolve({
+				code: exitCode,
+				stdout,
+				stdoutTruncated: stdoutBytes > OUTPUT_CAP,
+				stderr,
+				timedOut,
+				aborted,
+				failed: failed || exitCode === 127,
+				durationMs: Date.now() - started,
+			});
+		};
+
+		proc.stdout?.on("data", (chunk: Buffer) => {
+			options.onStdout?.(chunk);
+			stdoutBytes += chunk.length;
+			stdout = appendCapped(stdout, stdoutDecoder.write(chunk));
+		});
+		proc.stderr?.on("data", (chunk: Buffer) => (stderr = appendCapped(stderr, stderrDecoder.write(chunk))));
+		proc.on("error", (error) => {
+			stderr = appendCapped(stderr, String(error));
+			finish(true);
+		});
+		proc.on("exit", (code) => {
+			exitCode = code;
+			// A descendant that inherited stdout/stderr can keep 'close' from ever firing.
+			if (!stopping) timers.push(setTimeout(() => { if (!stopping) finish(); }, CLOSE_GRACE_MS));
+		});
+		proc.on("close", () => {
+			closed = true;
+			if (!stopping) finish();
+		});
+
+		timers.push(
+			setTimeout(() => {
+				if (settled || aborted) return;
+				timedOut = true;
+				stop();
+			}, options.timeoutMs),
+		);
+		if (options.onHeartbeat && options.heartbeatMs) {
+			const heartbeat = setInterval(() => {
+				if (!settled) options.onHeartbeat?.(Date.now() - started);
+			}, options.heartbeatMs);
+			timers.push(heartbeat);
+		}
+		if (options.signal) {
+			if (options.signal.aborted) onAbort();
+			else options.signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		proc.stdin?.on("error", () => {
+			/* the command may exit without reading stdin */
+		});
+		try {
+			proc.stdin?.end(options.stdin ?? "");
+		} catch {
+			/* ignore */
+		}
+	});
+}
+
+/** Resolve the timeout for one run: explicit request, then the environment, then the default — clamped. */
+export function gateTimeoutSeconds(requested?: number, environment = process.env.CRATIS_HOOKS_GATE_TIMEOUT_SECONDS): number {
+	const fromEnvironment = environment !== undefined && environment.trim() !== "" ? Number(environment) : undefined;
+	const candidate = requested ?? fromEnvironment ?? DEFAULT_GATE_TIMEOUT_SECONDS;
+	if (!Number.isFinite(candidate)) return DEFAULT_GATE_TIMEOUT_SECONDS;
+	return Math.min(MAX_GATE_TIMEOUT_SECONDS, Math.max(MIN_GATE_TIMEOUT_SECONDS, Math.round(candidate)));
+}
+
+/** The gate ids a `CRATIS_HOOKS_GATE_DRYRUN=1` run says it would execute, in order. */
+export function parseGatePlan(dryRunStderr: string): string[] {
+	return [...dryRunStderr.matchAll(/^cratis-quality-gate: RUN\s+(\S+)/gm)].map((match) => match[1]);
+}
+
+/** Where cratis-quality-gate.sh writes each gate's full log for a session (mirrors hook_state_dir in hook-lib.sh). */
+export function gateLogDirectory(sessionId: string, environment = process.env): string {
+	const session = sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "nosession";
+	const base = (environment.TMPDIR || "/tmp").replace(/\/+$/, "");
+	return path.join(base, "cratis-hooks", session, "gate-logs");
+}
+
+/** The gate log written most recently since `sinceMs` — the gate that is running, or was when it stopped. */
+export function latestGateLog(directory: string, sinceMs: number): { gate: string; file: string } | undefined {
+	let latest: { gate: string; file: string; mtime: number } | undefined;
+	try {
+		for (const name of fs.readdirSync(directory)) {
+			if (!name.endsWith(".log")) continue;
+			const file = path.join(directory, name);
+			const mtime = fs.statSync(file).mtimeMs;
+			if (mtime + 1000 < sinceMs) continue;
+			if (!latest || mtime > latest.mtime) latest = { gate: name.slice(0, -".log".length), file, mtime };
+		}
+	} catch {
+		return undefined;
+	}
+	return latest && { gate: latest.gate, file: latest.file };
+}
+
+const MAX_LOG_TAIL_BYTES = 64 * 1024;
+
+export function tailLines(file: string, lines: number): string {
+	if (lines <= 0) return "";
+	let descriptor: number | undefined;
+	try {
+		descriptor = fs.openSync(file, "r");
+		const size = fs.fstatSync(descriptor).size;
+		const chunks: Buffer[] = [];
+		let position = size;
+		let newlines = 0;
+		while (position > 0 && size - position < MAX_LOG_TAIL_BYTES && newlines <= lines) {
+			const length = Math.min(4096, position, MAX_LOG_TAIL_BYTES - (size - position));
+			const chunk = Buffer.allocUnsafe(length);
+			const read = fs.readSync(descriptor, chunk, 0, length, position - length);
+			if (!read) break;
+			position -= read;
+			const data = chunk.subarray(0, read);
+			chunks.unshift(data);
+			for (const byte of data) if (byte === 10) newlines++;
+		}
+		const text = Buffer.concat(chunks).toString("utf8");
+		const tail = text.split("\n").slice(-lines - 1).join("\n").trim();
+		return position > 0 && newlines <= lines ? `[earlier log output truncated]\n${tail}` : tail;
+	} catch {
+		return "";
+	} finally {
+		if (descriptor !== undefined) fs.closeSync(descriptor);
+	}
+}
+
+export type Fingerprint = { kind: "ok"; value: string; root: string } | { kind: "not-repository" } | { kind: "unknown"; reason?: string };
+
+/** Digest the working tree; a Git failure or deadline is unknown, never proof that no gate applies. */
+export async function workingTreeFingerprint(cwd: string, timeoutMs = FINGERPRINT_TIMEOUT_MS, signal?: AbortSignal): Promise<Fingerprint> {
+	const hash = createHash("sha256");
+	const deadline = Date.now() + timeoutMs;
+	// Read-only: never take the index lock, so this can never make the agent's own git commands fail.
+	const env = { ...process.env, GIT_OPTIONAL_LOCKS: "0" };
+	const git = async (args: string[], onStdout?: (chunk: Buffer) => void) => {
+		if (signal?.aborted || Date.now() >= deadline) return undefined;
+		return runBounded("git", args, { cwd, timeoutMs: Math.max(1, deadline - Date.now()), env, signal, onStdout });
+	};
+	const root = await git(["rev-parse", "--show-toplevel"]);
+	if (!root || root.aborted || root.timedOut || root.failed) return { kind: "unknown" };
+	if (root.code !== 0) return root.stderr.includes("not a git repository (or any of the parent directories)") ? { kind: "not-repository" } : { kind: "unknown" };
+	const status = await git(["status", "--porcelain=v2", "-z", "--untracked-files=all", "--ignore-submodules=none"]);
+	if (!status || status.code !== 0 || status.aborted || status.timedOut || status.failed || status.stdoutTruncated) return { kind: "unknown" };
+	const head = await git(["rev-parse", "--verify", "-q", "HEAD"]);
+	if (!head || head.aborted || head.timedOut || head.failed || (head.code !== 0 && head.code !== 1)) return { kind: "unknown" };
+	// Without an initial commit, porcelain status alone does not reflect changes to already-added files.
+	if (head.code === 1) return { kind: "unknown", reason: "HEAD has no initial commit" };
+	// In porcelain v2 the third field of a tracked entry is Git's submodule state (S<c><m><u>).
+	// A dirty gitlink's HEAD and diff can stay identical while its nested content changes.
+	// A rename (type 2) has an extra NUL-delimited old path; never parse it as another status record.
+	const untracked: string[] = [];
+	const entries = status.stdout.split("\0");
+	for (let index = 0; index < entries.length; index++) {
+		const entry = entries[index];
+		if (entry.startsWith("u ")) return { kind: "unknown", reason: "unmerged paths; resolve conflicts before verifying" };
+		if (entry.startsWith("? ")) untracked.push(entry.slice(2));
+		if (!entry.startsWith("1 ") && !entry.startsWith("2 ")) continue;
+		const submoduleState = entry.split(" ", 4)[2];
+		if (submoduleState?.startsWith("S") && (submoduleState[2] === "M" || submoduleState[3] === "U")) return { kind: "unknown", reason: "dirty tracked submodule" };
+		if (entry.startsWith("2 ")) index++;
+	}
+	hash.update(`head:${head.stdout.trim()}\0status:${status.stdout}\0`);
+	const diff = await git(["diff", "HEAD", "--no-relative", "--no-ext-diff", "--no-textconv", "--binary", "--ignore-submodules=none"], (chunk) => hash.update(chunk));
+	if (!diff || diff.code !== 0 || diff.aborted || diff.timedOut || diff.failed) return { kind: "unknown" };
+	const top = path.resolve(root.stdout.trim());
+	const sameFile = (left: fs.Stats, right: fs.Stats) =>
+		left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+		left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+	for (const file of untracked) {
+		if (signal?.aborted || Date.now() >= deadline) return { kind: "unknown" };
+		const parts = file.split("/");
+		if (parts.some((part) => !part || part === "." || part === "..")) return { kind: "unknown", reason: `unsupported untracked entry ${JSON.stringify(file)}` };
+		const fullPath = path.resolve(top, file);
+		const relative = path.relative(top, fullPath);
+		if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return { kind: "unknown" };
+		try {
+			// Never traverse an untracked symlink directory to read a file outside this repository.
+			let directory = top;
+			for (const part of parts.slice(0, -1)) {
+				if (signal?.aborted || Date.now() >= deadline) return { kind: "unknown" };
+				directory = path.join(directory, part);
+				const parent = await fs.promises.lstat(directory);
+				if (!parent.isDirectory() || parent.isSymbolicLink()) return { kind: "unknown" };
+			}
+			const before = await fs.promises.lstat(fullPath);
+			hash.update(`untracked:${file}:${before.mode}:${before.size}\0`);
+			if (before.isSymbolicLink()) {
+				// Hash the link text, not the bytes of its target (which may be outside the repository).
+				hash.update(`link:${await fs.promises.readlink(fullPath)}\0`);
+			} else if (before.isFile() && typeof fs.constants.O_NOFOLLOW === "number") {
+				// O_NOFOLLOW and O_NONBLOCK refuse a last-moment symlink or FIFO replacement.
+				const handle = await fs.promises.open(fullPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+				try {
+					const opened = await handle.stat();
+					if (!opened.isFile() || !sameFile(before, opened)) return { kind: "unknown" };
+					const buffer = Buffer.allocUnsafe(64 * 1024);
+					let offset = 0;
+					while (offset < opened.size) {
+						if (signal?.aborted || Date.now() >= deadline) return { kind: "unknown" };
+						const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, opened.size - offset), offset);
+						if (!bytesRead) return { kind: "unknown" };
+						hash.update(buffer.subarray(0, bytesRead));
+						offset += bytesRead;
+					}
+					// A file that grew during reading was not fully fingerprinted.
+					if ((await handle.stat()).size !== offset) return { kind: "unknown" };
+				} finally {
+					await handle.close();
+				}
+				hash.update("\0");
+			} else {
+				return { kind: "unknown" };
+			}
+			if (signal?.aborted || Date.now() >= deadline || !sameFile(before, await fs.promises.lstat(fullPath))) return { kind: "unknown" };
+		} catch {
+			return { kind: "unknown" };
+		}
+	}
+	return signal?.aborted || Date.now() >= deadline ? { kind: "unknown" } : { kind: "ok", value: hash.digest("hex"), root: top };
+}

package/package/corpus/hooks/README.md

@@ -11,7 +11,8 @@ Three layers:
 | Pattern pass | `PostToolUse` on a write | `scripts/cratis-pattern-scan.sh` | zero tokens until a match | appends a one-line reminder to context, never blocks |
 | Hard block | `PreToolUse` on a write | `scripts/cratis-guard-writes.sh` | zero | exits **2** — the write does not happen |
 | Hard block | `PreToolUse` on `Bash` | `scripts/cratis-guard-store-mutations.sh` | zero; parses only commands that mention `cratis` | exits **2** — the store-changing `cratis chronicle` command does not run |
-| Quality gate | `Stop` | `scripts/cratis-quality-gate.sh` | one build/test run, only when relevant files changed | exits **2** — the turn does not end |
+| Quality gate (Claude) | `Stop` | `scripts/cratis-quality-gate.sh` | one build/test run, only when relevant files changed | exits **2** — the turn does not end |
+| Quality gate (Pi) | explicit `cratis_quality_gate` tool | same script | only at a requested verification checkpoint | error on failure; no turn-end hook |
 
 The Claude Code wiring that fires them is tracked here, in
 [`settings.template.json`](./settings.template.json). Claude reads `.claude/settings.json`. In a
@@ -36,6 +37,25 @@ they describe what a hook should do for tools that have no wiring yet.
 > extension under `../harnesses/pi/extensions/` (its `bash` tool feeds the store-mutation guard, its
 > `write` and `edit` tools the write guard); Copilot would read `.github/hooks/*.json`, and no
 > Copilot wiring ships yet.
+>
+> In Pi the quality gate is not run at the end of a turn. Pi waits for end-of-turn handlers before it
+> starts the next prompt, so a gate run there froze the session for as long as the build and tests took.
+> Instead the bridge registers a `cratis_quality_gate` tool that runs the same script in the foreground:
+> it shows which gate is running, Escape cancels it, and it stops after
+> `CRATIS_HOOKS_GATE_TIMEOUT_SECONDS` (default 300 seconds, capped at 600), including planning and working-tree checks.
+> A timeout or a cancellation is reported as an error that says nothing was verified, never as a pass.
+> An inherited dry-run setting cannot produce a verified result, and a passing gate checks that the
+> working tree stayed unchanged in the content it can observe during the run. Pi does **not** invoke or request this tool
+> at the end of each prompt: an edit or a read-only turn is not task completion. Run affected-project
+> checks while iterating, and run the full CI-equivalent gates before claiming completion or
+> pushing/opening a PR (Tier 1/2 where required). The explicit tool selects gates from **all** current
+> working-tree changes, not just the last turn, and does not replace the repository's full CI matrix.
+> The gate never runs in the background, where it would race the agent's next edits.
+
+Tracked-file stability follows Git-visible contents, not byte-exact disk contents: lossy clean/EOL
+conversion and Git's assume-unchanged or skip-worktree settings can hide raw disk changes. If you
+use those settings, independently verify raw file contents or remove the hiding settings before
+relying on this check.
 
 ## What is enforced
 
@@ -363,6 +383,7 @@ Each is an explicit, auditable opt-out — none of them is a default.
 | `CRATIS_HOOKS_SKIP_SCAN=1` | disables the pattern pass |
 | `CRATIS_HOOKS_SKIP_GATE=1` | disables the quality gate |
 | `CRATIS_HOOKS_GATE_DRYRUN=1` | prints which gates would run, and why, then exits 0 |
+| `CRATIS_HOOKS_GATE_TIMEOUT_SECONDS=<n>` | Pi only: stops a `cratis_quality_gate` run after `n` seconds (default 300, maximum 600) and reports it as timed out |
 | `CRATIS_HOOKS_PATTERNS=<path>` | replaces the pattern file |
 | `CRATIS_HOOKS_GATES=<path>` | replaces the gate file (the project override still merges over it) |
 | `CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1` | allows `cratis chronicle` commands that change a live store; set by the person who authorized the mutation, in the environment the harness was started from |

package/package/corpus/rules/general.md

@@ -94,7 +94,7 @@ the plugin marketplaces) are in [ai-distribution.md](./ai-distribution.md):
 A claim is only as good as the signal behind it — a build result, a test run, a lint pass, observed app behavior — not the model's own confidence. Internal reasoning *plans* the work; external signals *confirm* it.
 
 - **Confirm "done"/"fixed"/"correct" against a fresh signal — never self-assessment.** Run the relevant gate and observe it pass *this time*.
-- **After a fix, re-run the gate that failed.** Don't argue yourself to green.
+- **Check at the right frequency.** Run affected-project checks while iterating; a prompt ending is not task completion. Before claiming a task complete or pushing/opening a PR, run the full CI-equivalent gates required for that repository (including its Tier 1/2 policy where applicable). A change-selected hook gate is not a substitute for the repository's full CI matrix. After a fix, re-run the gate that failed. Don't argue yourself to green.
 - **A green build is not behavioral correctness.** Compilation proves it builds, not that the slice does the right thing — that's what specs and exercising the UI are for.
 - **Report the conclusion and what you didn't verify, in a line or two.** Show the output when asked, when a claim is contested, or when the check failed — see [verification-discipline.md](./verification-discipline.md).
 

package/package/corpus/rules/verification-discipline.md

@@ -9,7 +9,10 @@ paths:
 Verification answers whether changed behavior works. It does not establish who
 authored a file or preserve a chain of evidence about how it arrived.
 
-- Run the narrowest relevant build, type check, lint, and specifications.
+- Run the narrowest relevant build, type check, lint, and specifications while iterating; explain when a wider gate is required before completion or push/PR.
+- Run one phase per command with its real exit status. Budget targeted checks around 120 seconds and build/test phases around 300 seconds; explain any longer budget first, and obtain explicit approval before a phase exceeds 600 seconds. Stop on a failure; do not blindly retry or repeat passing tests on unchanged inputs without a flaky-test hypothesis or required matrix.
+- Separate status/fetch from builds, Debug from Release, each test project, and frontend lint/compile/test/build. Do not combine these into an opaque command with a large outer timeout. Expose progress and cancellation; report the precise failed or timed-out phase and do not continue dependent phases after failure.
+- Never use `build/test | grep | sort/head/tail` as gate evidence. Capture the producer's exit status before summarising output; `pipefail` alone is insufficient with early-closing consumers such as `head`. Printed zero-error counts are not proof of success. Preserve needed full diagnostics in task-scoped `.ai-work/` logs rather than hiding them in `/tmp`.
 - Add a focused specification for every behavior or rejection rule you change.
 - Keep each check deterministic and runnable locally and in CI.
 - Never replace a real behavior check with a checksum, inventory, generated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.1.0",
+  "version": "7.1.2",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [