@junghanacs/entwurf 0.31.0 → 0.32.0

package/scripts/emit-pi-durable-carrier.ts

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+/**
+ * emit-pi-durable-carrier — the MAINTAINER's one path from upstream source to the pi-durable
+ * carrier (#130). An operator never runs it: an installed package carries the emitted JS and reads
+ * no upstream source.
+ *
+ *   node scripts/emit-pi-durable-carrier.ts --source <git repository holding the pinned commit> --write
+ *   node scripts/emit-pi-durable-carrier.ts --source <git repository holding the pinned commit> --check
+ *
+ * Inputs, and nothing else: the pinned commit's OBJECTS (each declared file and the license, read as
+ * `<commit>:<path>` — never a worktree, so the repository's checkout state cannot enter), the packaged
+ * overlay patch, and this Node's `stripTypeScriptTypes` in strip mode (upstream runs these exact
+ * sources under Node's strip-only TypeScript). The patch is applied by git's own engine to a private
+ * scratch copy; the base blob and the patched result must carry the blob ids the patch's `index` line
+ * names. Each stripped file is then relocated by pi/pi-durable/carrier-relocation.mjs, and the targets
+ * the six files import must equal the pin's declared `distTargets` exactly.
+ *
+ * `--write` emits pi/pi-durable/carrier/{<files>,LICENSE} and fills the pin's generated fields
+ * (source blob ids, emitted sha256s, the Node version). `--check` re-emits in memory and compares:
+ * equal is the rebuild acceptance; any difference, another Node version, or an undeclared file in the
+ * carrier directory is a named FAIL. `--check` without a source holding the commit is a named SKIP —
+ * an unavailable observation, never rebuild acceptance. Read-only against the source repository.
+ *
+ * Exit: 0 written / equal, 1 named refusal or drift, 2 usage, 97 skip (no source).
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import { stripTypeScriptTypes } from "node:module";
+import * as os from "node:os";
+import * as path from "node:path";
+import { relocateCarrierSource } from "../pi/pi-durable/carrier-relocation.mjs";
+import { skipLive } from "./lib/live-skip.ts";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+const DURABLE = path.join(ROOT, "pi", "pi-durable");
+const PIN_PATH = path.join(DURABLE, "overlay", "upstream-pin.json");
+const CARRIER_DIR = path.join(DURABLE, "carrier");
+const LICENSE_NAME = "LICENSE";
+const EMITTER_TOOL = "node:module.stripTypeScriptTypes";
+const EMITTER_MODE = "strip";
+const GIT_TIMEOUT_MS = 30_000;
+
+interface CarrierFile {
+	name: string;
+	source: string;
+	patched: boolean;
+	blob: string;
+	sha256: string;
+}
+
+interface CarrierPin {
+	schemaVersion: number;
+	commit: string;
+	patches: string[];
+	carrier: {
+		emitter: { tool: string; mode: string; node: string };
+		license: { source: string; blob: string; sha256: string };
+		files: CarrierFile[];
+		distTargets: string[];
+	};
+}
+
+class Refusal extends Error {}
+const refuse = (reason: string, detail: string): Refusal => new Refusal(`${reason}: ${detail}`);
+
+const sha256 = (data: Buffer): string => createHash("sha256").update(data).digest("hex");
+/** git's blob id, computed here so no object is ever written into the source repository. */
+const blobId = (data: Buffer): string =>
+	createHash("sha1")
+		.update(Buffer.concat([Buffer.from(`blob ${data.length}\0`), data]))
+		.digest("hex");
+
+/** The environment every git child gets: no inherited repository, index or work-tree redirection. */
+function gitEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
+	const env: NodeJS.ProcessEnv = { GIT_OPTIONAL_LOCKS: "0", ...extra };
+	for (const [key, value] of Object.entries(process.env)) {
+		if (!key.startsWith("GIT_") && env[key] === undefined) env[key] = value;
+	}
+	return env;
+}
+
+/** Every read of the source repository: `--no-replace-objects`, so a `refs/replace/*` entry (or a
+ * replacement reached through alternates) can never stand in for a pinned object. */
+export function sourceGitArgs(source: string, args: readonly string[]): string[] {
+	return ["--no-replace-objects", "-C", source, ...args];
+}
+
+/** One pinned object's bytes, `<commit>:<path>`, as the source repository stores it. */
+export function readSourceObject(source: string, rev: string): Buffer {
+	return git(source, ["cat-file", "blob", rev]);
+}
+
+function git(source: string, args: string[]): Buffer {
+	const run = spawnSync("git", sourceGitArgs(source, args), {
+		env: gitEnv(),
+		maxBuffer: 64 * 1024 * 1024,
+		timeout: GIT_TIMEOUT_MS,
+	});
+	if (run.status !== 0) {
+		throw refuse(
+			"carrier-source-unreadable",
+			`git ${args.join(" ")} in ${source}: ${run.stderr?.toString().trim() || run.error?.message || `status ${run.status}`}`,
+		);
+	}
+	return run.stdout;
+}
+
+function readPin(): CarrierPin {
+	const pin = JSON.parse(fs.readFileSync(PIN_PATH, "utf8")) as CarrierPin;
+	if (pin.schemaVersion !== 2 || !/^[0-9a-f]{40}$/.test(pin.commit) || pin.patches?.length !== 1) {
+		throw refuse("carrier-pin-malformed", `${PIN_PATH}: schemaVersion 2, a full commit and one patch are required`);
+	}
+	if (pin.carrier.emitter.tool !== EMITTER_TOOL || pin.carrier.emitter.mode !== EMITTER_MODE) {
+		throw refuse(
+			"carrier-pin-malformed",
+			`the emitter is ${EMITTER_TOOL} in ${EMITTER_MODE} mode, not ${JSON.stringify(pin.carrier.emitter)}`,
+		);
+	}
+	if (pin.carrier.files.filter((f) => f.patched).length !== 1) {
+		throw refuse("carrier-pin-malformed", "exactly one carrier file carries the overlay patch");
+	}
+	return pin;
+}
+
+/** The overlay patch's one file and the two blob ids its `index` line names. */
+function readPatch(pin: CarrierPin): { bytes: Buffer; file: string; base: string; result: string } {
+	const bytes = fs.readFileSync(path.join(DURABLE, "overlay", pin.patches[0]));
+	const text = bytes.toString("utf8");
+	const files = [...text.matchAll(/^diff --git a\/(\S+) b\/(\S+)$/gm)];
+	const index = [...text.matchAll(/^index ([0-9a-f]+)\.\.([0-9a-f]+) 100644$/gm)];
+	if (files.length !== 1 || files[0][1] !== files[0][2] || index.length !== 1) {
+		throw refuse("carrier-patch-shape", `${pin.patches[0]} must change exactly one existing file`);
+	}
+	return { bytes, file: files[0][1], base: index[0][1], result: index[0][2] };
+}
+
+/** `base` with the patch applied by git, in a private scratch tree outside any repository. */
+function applyPatch(file: string, base: Buffer, patch: Buffer): Buffer {
+	const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "pi-durable-carrier-"));
+	try {
+		const target = path.join(scratch, file);
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		fs.writeFileSync(target, base);
+		const patchFile = path.join(scratch, "overlay.patch");
+		fs.writeFileSync(patchFile, patch);
+		const run = spawnSync("git", ["apply", "--whitespace=nowarn", "overlay.patch"], {
+			cwd: scratch,
+			env: gitEnv({ GIT_CEILING_DIRECTORIES: path.dirname(scratch) }),
+			timeout: GIT_TIMEOUT_MS,
+		});
+		if (run.status !== 0) {
+			throw refuse("carrier-patch-rejected", run.stderr?.toString().trim() || `git apply status ${run.status}`);
+		}
+		return fs.readFileSync(target);
+	} finally {
+		fs.rmSync(scratch, { recursive: true, force: true });
+	}
+}
+
+interface Emission {
+	files: Map<string, Buffer>;
+	generated: {
+		node: string;
+		license: { blob: string; sha256: string };
+		files: Map<string, { blob: string; sha256: string }>;
+	};
+}
+
+function emit(source: string, pin: CarrierPin): Emission {
+	if (git(source, ["cat-file", "-t", pin.commit]).toString().trim() !== "commit") {
+		throw refuse("carrier-source-unreadable", `${pin.commit} is not a commit in ${source}`);
+	}
+	const patch = readPatch(pin);
+	const names = pin.carrier.files.map((f) => f.name);
+	const targets = pin.carrier.distTargets;
+	if (new Set(targets).size !== targets.length) throw refuse("carrier-pin-malformed", "distTargets repeats a path");
+	const files = new Map<string, Buffer>();
+	const generatedFiles = new Map<string, { blob: string; sha256: string }>();
+	const used = new Set<string>();
+	for (const declared of pin.carrier.files) {
+		const original = readSourceObject(source, `${pin.commit}:${declared.source}`);
+		const blob = blobId(original);
+		let text = original;
+		if (declared.patched) {
+			if (declared.source !== patch.file || !blob.startsWith(patch.base)) {
+				throw refuse(
+					"carrier-patch-base",
+					`the patch changes ${patch.file} from ${patch.base}; ${declared.source} is ${blob}`,
+				);
+			}
+			text = applyPatch(declared.source, original, patch.bytes);
+			if (!blobId(text).startsWith(patch.result)) {
+				throw refuse(
+					"carrier-patch-result",
+					`patched ${declared.source} is ${blobId(text)}, the patch names ${patch.result}`,
+				);
+			}
+		}
+		const stripped = stripTypeScriptTypes(text.toString("utf8"), { mode: EMITTER_MODE });
+		const relocated = relocateCarrierSource(declared.name, stripped, { siblings: names, targets });
+		for (const target of relocated.used) used.add(target);
+		const bytes = Buffer.from(relocated.code, "utf8");
+		files.set(declared.name, bytes);
+		generatedFiles.set(declared.name, { blob, sha256: sha256(bytes) });
+	}
+	const unused = targets.filter((t) => !used.has(t));
+	if (unused.length > 0) throw refuse("carrier-targets-differ", `declared but not imported: ${unused.join(", ")}`);
+	const license = readSourceObject(source, `${pin.commit}:${pin.carrier.license.source}`);
+	files.set(LICENSE_NAME, license);
+	return {
+		files,
+		generated: {
+			node: process.version,
+			license: { blob: blobId(license), sha256: sha256(license) },
+			files: generatedFiles,
+		},
+	};
+}
+
+/** Files in the carrier directory that the pin does not declare. */
+function undeclared(pin: CarrierPin): string[] {
+	const declared = new Set([...pin.carrier.files.map((f) => f.name), LICENSE_NAME]);
+	const present = fs.existsSync(CARRIER_DIR) ? fs.readdirSync(CARRIER_DIR) : [];
+	return present.filter((name) => !declared.has(name)).sort();
+}
+
+function write(pin: CarrierPin, emission: Emission): void {
+	const extra = undeclared(pin);
+	if (extra.length > 0) throw refuse("carrier-undeclared-file", `remove ${extra.join(", ")} from ${CARRIER_DIR} first`);
+	fs.mkdirSync(CARRIER_DIR, { recursive: true });
+	for (const [name, bytes] of emission.files) fs.writeFileSync(path.join(CARRIER_DIR, name), bytes);
+	pin.carrier.emitter.node = emission.generated.node;
+	pin.carrier.license.blob = emission.generated.license.blob;
+	pin.carrier.license.sha256 = emission.generated.license.sha256;
+	for (const file of pin.carrier.files) Object.assign(file, emission.generated.files.get(file.name));
+	fs.writeFileSync(PIN_PATH, formatPin(pin));
+}
+
+/** The pin as the repository formatter leaves it (biome, tabs, width 120): JSON.stringify, with an array
+ * of strings that fits on its line written inline. Values are compared field by field, never as text. */
+function formatPin(pin: CarrierPin): string {
+	const text = JSON.stringify(pin, null, "\t").replace(
+		/^(\t*)("[^"\n]+": )\[\n((?:\t+"[^"\n]*",?\n)+)\t*\]/gm,
+		(block: string, indent: string, key: string, items: string) => {
+			const inline = `${key}[${items
+				.trim()
+				.split(/,?\n\t*/)
+				.join(", ")}]`;
+			return indent.length * 2 + inline.length + 1 <= 120 ? `${indent}${inline}` : block;
+		},
+	);
+	return `${text}\n`;
+}
+
+/** Every difference between the committed carrier + pin and a fresh emission. */
+function compare(pin: CarrierPin, emission: Emission): string[] {
+	const drift: string[] = [];
+	if (pin.carrier.emitter.node !== emission.generated.node) {
+		drift.push(
+			`carrier-emitter-node-mismatch: the carrier was emitted by Node ${pin.carrier.emitter.node || "(none)"}, this is ${emission.generated.node}`,
+		);
+	}
+	const license = emission.generated.license;
+	if (pin.carrier.license.blob !== license.blob || pin.carrier.license.sha256 !== license.sha256) {
+		drift.push(`carrier-pin-drift: license is ${license.blob}/${license.sha256}`);
+	}
+	for (const file of pin.carrier.files) {
+		const want = emission.generated.files.get(file.name);
+		if (file.blob !== want?.blob || file.sha256 !== want?.sha256) {
+			drift.push(
+				`carrier-pin-drift: ${file.name} pin records ${file.blob}/${file.sha256}, emission is ${want?.blob}/${want?.sha256}`,
+			);
+		}
+	}
+	for (const [name, bytes] of emission.files) {
+		const onDisk = path.join(CARRIER_DIR, name);
+		if (!fs.existsSync(onDisk)) drift.push(`carrier-file-missing: ${name}`);
+		else if (!fs.readFileSync(onDisk).equals(bytes))
+			drift.push(`carrier-file-drift: ${name} differs from its emission`);
+	}
+	for (const name of undeclared(pin)) drift.push(`carrier-undeclared-file: ${name}`);
+	return drift;
+}
+
+function main(argv: readonly string[]): number {
+	const sourceAt = argv.indexOf("--source");
+	const source = sourceAt === -1 ? undefined : argv[sourceAt + 1];
+	const mode = argv.includes("--write") ? "write" : argv.includes("--check") ? "check" : undefined;
+	if (mode === undefined || argv.length !== (source === undefined ? 1 : 3) || (sourceAt !== -1 && !source)) {
+		console.error(
+			"usage: emit-pi-durable-carrier.ts --source <git repository holding the pinned commit> (--write | --check)",
+		);
+		return 2;
+	}
+	const pin = readPin();
+	if (mode === "check") {
+		const held =
+			source !== undefined &&
+			spawnSync("git", sourceGitArgs(source, ["cat-file", "-e", `${pin.commit}^{commit}`]), {
+				env: gitEnv(),
+				timeout: GIT_TIMEOUT_MS,
+			}).status === 0;
+		if (!held) {
+			skipLive(
+				"emit-pi-durable-carrier --check",
+				`no --source repository holding ${pin.commit} — the rebuild was NOT checked; pass a clone of ${(pin as { repository?: string }).repository ?? "upstream"} that contains it`,
+			);
+		}
+	}
+	if (source === undefined) {
+		console.error("emit-pi-durable-carrier --write needs --source");
+		return 2;
+	}
+	const emission = emit(path.resolve(source), pin);
+	if (mode === "write") {
+		write(pin, emission);
+		console.log(
+			`[emit-pi-durable-carrier] wrote ${emission.files.size} files to ${path.relative(ROOT, CARRIER_DIR)} from ${pin.commit} (${emission.generated.node})`,
+		);
+		return 0;
+	}
+	const drift = compare(pin, emission);
+	if (drift.length > 0) {
+		for (const line of drift) console.error(`[emit-pi-durable-carrier] ${line}`);
+		return 1;
+	}
+	console.log(
+		`[emit-pi-durable-carrier] ok — the carrier is the emission of ${pin.commit} (${emission.generated.node})`,
+	);
+	return 0;
+}
+
+// Run only when this file is the process entry (argv realpath, as the shipped entries decide it);
+// the beside test imports the source-read seam above without emitting anything.
+const invokedDirectly = (() => {
+	const entry = process.argv[1];
+	if (typeof entry !== "string" || entry.length === 0) return false;
+	try {
+		return fs.realpathSync(entry) === fs.realpathSync(import.meta.filename);
+	} catch {
+		// Bounded environment probe: an entry that cannot be resolved is not this file.
+		return false;
+	}
+})();
+if (invokedDirectly) {
+	try {
+		process.exitCode = main(process.argv.slice(2));
+	} catch (error) {
+		if (!(error instanceof Refusal) && !(error instanceof Error && "reason" in error)) throw error;
+		console.error(`[emit-pi-durable-carrier] ${error.message}`);
+		process.exitCode = 1;
+	}
+}

package/scripts/lib/mutation-qualify.ts

@@ -426,50 +426,6 @@ function gitIn(dir: string, args: string[]): string {
 	return r.stdout;
 }
 
-/**
- * Sweep stale snapshot dirs left by a SIGKILLed/powered-off run. Only dirs whose
- * recorded runner pid is dead are removed; a dir with no runner.json is removed only
- * once it is old (another runner may be mid-mkdtemp). Residue is inert tmp garbage —
- * the real checkout was never written — so this is tidiness, not recovery.
- */
-export function sweepStaleSnapshots(tmpRoot: string): string[] {
-	const swept: string[] = [];
-	let entries: string[];
-	try {
-		entries = fs.readdirSync(tmpRoot);
-	} catch {
-		return swept;
-	}
-	for (const name of entries) {
-		if (!name.startsWith(SNAPSHOT_PREFIX)) continue;
-		const dir = path.join(tmpRoot, name);
-		const marker = path.join(dir, "runner.json");
-		let dead = false;
-		try {
-			const rec = JSON.parse(fs.readFileSync(marker, "utf8")) as { pid?: number };
-			if (typeof rec.pid !== "number") dead = true;
-			else if (rec.pid !== process.pid) {
-				try {
-					process.kill(rec.pid, 0);
-				} catch {
-					dead = true;
-				}
-			}
-		} catch {
-			try {
-				dead = Date.now() - fs.statSync(dir).mtimeMs > 60_000;
-			} catch {
-				continue;
-			}
-		}
-		if (dead) {
-			fs.rmSync(dir, { recursive: true, force: true });
-			swept.push(dir);
-		}
-	}
-	return swept;
-}
-
 export interface Snapshot {
 	baseDir: string;
 	repoDir: string;
@@ -488,7 +444,6 @@ export interface Snapshot {
 export function createRepoSnapshot(originDir: string, tmpRoot: string = os.tmpdir()): Snapshot {
 	const baseDir = fs.mkdtempSync(path.join(tmpRoot, SNAPSHOT_PREFIX));
 	fs.chmodSync(baseDir, 0o700);
-	fs.writeFileSync(path.join(baseDir, "runner.json"), JSON.stringify({ pid: process.pid, startedAt: Date.now() }));
 	const repoDir = path.join(baseDir, "repo");
 	fs.mkdirSync(repoDir, { mode: 0o700 });
 
@@ -529,6 +484,27 @@ export function createRepoSnapshot(originDir: string, tmpRoot: string = os.tmpdi
 	return { baseDir, repoDir, fileCount: copied };
 }
 
+/**
+ * The one snapshot lifecycle every real run uses (full body and each group): create
+ * exactly one snapshot, run, then remove exactly the `baseDir` this call created. It
+ * never lists `tmpRoot` and never removes a root it did not create here: a prior run's
+ * snapshot is that run's evidence, whatever its process state, and deleting it is the
+ * operator's decision, never the qualifier's. `tmpRoot` is passed only by self-test
+ * fixtures; real runs leave it undefined (the OS tmp dir).
+ */
+export async function withOwnSnapshot<T>(
+	originDir: string,
+	tmpRoot: string | undefined,
+	run: (snap: Snapshot) => Promise<T>,
+): Promise<T> {
+	const snap = createRepoSnapshot(originDir, tmpRoot);
+	try {
+		return await run(snap);
+	} finally {
+		fs.rmSync(snap.baseDir, { recursive: true, force: true });
+	}
+}
+
 /**
  * Content manifest of the snapshot tree — path+mode+sha256 for files, target for
  * symlinks, bare entries for dirs — excluding .git and node_modules. Porcelain alone

package/scripts/lib/pi-durable-operator-guard.ts

@@ -0,0 +1,89 @@
+/**
+ * The pi-durable checkout gates' coarse operator registration guard (#129; re-scoped by the #130 P1b
+ * review). Shared by check-pi-durable-contact, -send and -receive.
+ *
+ * Subject: a gate run leaves the operator's pi-durable REGISTRATIONS exactly as it found them. Existing
+ * registrations — earlier sessions' records, receivers, sender markers — are ordinary operator state
+ * and never a red by their presence; only a change across the run is. The snapshot holds, under the
+ * operator agent dir:
+ *   - every pi-durable meta record (`meta-sessions/*.meta.json` whose backend is pi-durable) by name
+ *     and sha256 of its bytes, so an edit under the same filename is seen;
+ *   - every pi-durable receiver marker (`meta-receivers/*.json`, same backend filter), likewise;
+ *   - every pi-durable sender marker (`meta-senders/pi-durable/*`), likewise;
+ *   - the entry NAMES two levels into `experimental/durable-sessions` (cwd-hash dirs and their session
+ *     dirs) — never a file inside them.
+ * Scope, stated: a coarse registration guard. It reads no auth, settings, transcript or SQLite/session
+ * content, makes no operator-byte claim beyond the files above, and NEVER deletes or repairs anything.
+ * A concurrent operator session that registers during a run turns it red; that is the coarse guard's
+ * honest answer, not a gate defect to suppress.
+ */
+
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const sha256 = (file: string): string => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+
+function backendOf(file: string): unknown {
+	try {
+		return (JSON.parse(fs.readFileSync(file, "utf8")) as { backend?: unknown }).backend;
+	} catch {
+		// Bounded environment probe: an unreadable or non-JSON file is not a pi-durable registration.
+		return undefined;
+	}
+}
+
+/** `{name: sha256}` for the regular files in `dir` that pass `keep`, in name order; `{}` when absent. */
+function digests(dir: string, keep: (name: string) => boolean): Record<string, string> {
+	if (!fs.existsSync(dir)) return {};
+	const out: Record<string, string> = {};
+	for (const name of fs.readdirSync(dir).sort()) {
+		const file = path.join(dir, name);
+		if (fs.lstatSync(file).isFile() && keep(name)) out[name] = sha256(file);
+	}
+	return out;
+}
+
+/** Entry names one and two levels under `dir` (`a`, `a/b`), sorted; nothing inside is opened. */
+function names(dir: string): string[] {
+	if (!fs.existsSync(dir)) return [];
+	const out: string[] = [];
+	for (const first of fs.readdirSync(dir).sort()) {
+		out.push(first);
+		const at = path.join(dir, first);
+		if (fs.lstatSync(at).isDirectory()) for (const second of fs.readdirSync(at).sort()) out.push(`${first}/${second}`);
+	}
+	return out;
+}
+
+export interface OperatorPiDurableSnapshot {
+	readonly records: Record<string, string>;
+	readonly receivers: Record<string, string>;
+	readonly senders: Record<string, string>;
+	readonly durableSessions: string[];
+}
+
+/** The snapshot of `agentDir` (the operator's `~/.pi/agent`), read-only. */
+export function operatorPiDurableSnapshot(agentDir: string): OperatorPiDurableSnapshot {
+	const sessions = path.join(agentDir, "meta-sessions");
+	const receivers = path.join(agentDir, "meta-receivers");
+	return {
+		records: digests(sessions, (n) => n.endsWith(".meta.json") && backendOf(path.join(sessions, n)) === "pi-durable"),
+		receivers: digests(receivers, (n) => n.endsWith(".json") && backendOf(path.join(receivers, n)) === "pi-durable"),
+		senders: digests(path.join(agentDir, "meta-senders", "pi-durable"), () => true),
+		durableSessions: names(path.join(agentDir, "experimental", "durable-sessions")),
+	};
+}
+
+/** The guard's label body: counts only, so a receipt names the subject without copying operator paths. */
+export function describeOperatorSnapshot(snapshot: OperatorPiDurableSnapshot): string {
+	return `${Object.keys(snapshot.records).length} pi-durable records, ${Object.keys(snapshot.receivers).length} receivers, ${Object.keys(snapshot.senders).length} sender markers, ${snapshot.durableSessions.length} durable session entries`;
+}
+
+/** Unchanged across the run: same names, same bytes, same session entries. */
+export function operatorSnapshotUnchanged(
+	before: OperatorPiDurableSnapshot,
+	after: OperatorPiDurableSnapshot,
+): boolean {
+	return JSON.stringify(before) === JSON.stringify(after);
+}

package/scripts/lib/qualification-receipt.ts

@@ -38,12 +38,12 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import {
-	createRepoSnapshot,
 	type MutantSpec,
 	originHead,
 	originWorkSurfaceSha,
 	qualifyMutants,
 	reportPassed,
+	withOwnSnapshot,
 } from "./mutation-qualify.ts";
 
 export const RECEIPT_SCHEMA = "entwurf.qualification-group-receipt/v0";
@@ -471,16 +471,12 @@ export async function runGroupReceipt(
 	const declaredInputs = declaredInputPaths(repoDir, groupSpecs, gate);
 	const inputsBefore = fileFingerprints(repoDir, declaredInputs);
 
-	const snap = createRepoSnapshot(repoDir, opts.tmpRoot);
-	opts.log(
-		`[gate-qualification --group] PARTIAL: ${groupSpecs.length}/${selected.length} mutants of ${groupKey}; snapshot ${snap.repoDir} (origin HEAD ${headBefore.slice(0, 12)})`,
-	);
-	let report: Awaited<ReturnType<typeof qualifyMutants>>;
-	try {
-		report = await qualifyMutants(snap, groupSpecs, opts.log);
-	} finally {
-		fs.rmSync(snap.baseDir, { recursive: true, force: true });
-	}
+	const report = await withOwnSnapshot(repoDir, opts.tmpRoot, (snap) => {
+		opts.log(
+			`[gate-qualification --group] PARTIAL: ${groupSpecs.length}/${selected.length} mutants of ${groupKey}; snapshot ${snap.repoDir} (origin HEAD ${headBefore.slice(0, 12)})`,
+		);
+		return qualifyMutants(snap, groupSpecs, opts.log);
+	});
 
 	const headAfter = originHead(repoDir);
 	const workSurfaceAfter = originWorkSurfaceSha(repoDir);

package/scripts/mutants/control-send-receipt.json

@@ -181,7 +181,7 @@
 			"claim": "PI-CORE-PIN-TRACKS-FLOOR",
 			"title": "the queue oracle's pi-agent-core pin drifts off the floor the rest of the pi runtime is pinned to, so the oracle keeps answering honestly — about a pi nobody in this repo runs",
 			"subject": "package.json",
-			"find": ["\"@earendil-works/pi-agent-core\": \"1.0.2\","],
+			"find": ["\"@earendil-works/pi-agent-core\": \"1.0.4\","],
 			"replace": ["\"@earendil-works/pi-agent-core\": \"0.87.1\","],
 			"gate": ["bash", "run.sh", "check-dep-versions"],
 			"timeoutSeconds": 300,

package/scripts/mutants/gate-qualification.json

@@ -82,6 +82,19 @@
 			"timeoutSeconds": 120,
 			"signature": "[QK:QUALIFY-BUILD-GROUP-CONSISTENT]",
 			"signatureSource": "scripts/check-gate-qualification.ts"
+		},
+		{
+			"claim": "QUALIFY-PRIOR-RUN-EVIDENCE-KEPT",
+			"title": "the snapshot seam lists its tmp root and removes every snapshot-prefixed root before making its own — the retired ambient sweep is back, and a prior run's evidence is deleted by the qualifier instead of left to the operator (scoped to an explicit tmpRoot, which only self-test fixtures pass, so the defect never reaches the real tmp dir)",
+			"subject": "scripts/lib/mutation-qualify.ts",
+			"find": ["\tconst snap = createRepoSnapshot(originDir, tmpRoot);"],
+			"replace": [
+				"\tif (tmpRoot !== undefined) for (const name of fs.readdirSync(tmpRoot)) if (name.startsWith(SNAPSHOT_PREFIX)) fs.rmSync(path.join(tmpRoot, name), { recursive: true, force: true });\n\tconst snap = createRepoSnapshot(originDir, tmpRoot);"
+			],
+			"gate": ["bash", "run.sh", "check-gate-manifests"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:QUALIFY-PRIOR-RUN-EVIDENCE-KEPT]",
+			"signatureSource": "scripts/check-gate-qualification.ts"
 		}
 	]
 }

package/scripts/mutants/mux-fresh-call.json

@@ -192,17 +192,6 @@
 			"signature": "[QK:PIIMPORT-WORK-SURFACE]",
 			"signatureSource": "run.sh"
 		},
-		{
-			"claim": "PIIMPORT-DURABLE-BOOTSTRAP-EXACT",
-			"title": "the #129 durable exception loses its file scope: the two experimental durable specifiers become allowed in every file, so a new pi private-subpath import elsewhere passes the floor",
-			"subject": "run.sh",
-			"find": ["      | sed -E \"/^pi\\/pi-durable\\/bootstrap\\.mjs:[0-9]+:/ s#"],
-			"replace": ["      | sed -E \"s#"],
-			"gate": ["bash", "run.sh", "check-pi-import-surface"],
-			"timeoutSeconds": 60,
-			"signature": "[QK:PIIMPORT-DURABLE-BOOTSTRAP-EXACT]",
-			"signatureSource": "run.sh"
-		},
 		{
 			"claim": "VITEST-FAILED-TITLE-ATTRIBUTION",
 			"title": "the pilot's kill attribution collects PASSING test titles instead of failed ones, recreating the code-frame false-KILLED hole this lane exists to close",
@@ -725,7 +714,7 @@
 		},
 		{
 			"claim": "FRESHCALL-PI-DURABLE-PREFLIGHT-PREMUTATION",
-			"title": "the pi-durable runtime/unit preflight is skipped, so an absent or drifted operator runtime is discovered only after a window was placed",
+			"title": "the pi-durable preflight (model, framed input cap, carrier, units) is skipped, so a refusal it owns is discovered only after a window was placed",
 			"subject": "pi-extensions/lib/mux-fresh-call.ts",
 			"find": ["\tif (params.backend === \"pi-durable\") {\n"],
 			"replace": ["\tif (false) {\n"],
@@ -736,7 +725,7 @@
 		},
 		{
 			"claim": "FRESHCALL-PI-DURABLE-MANAGED-RUNTIME",
-			"title": "pi-durable opens the bare app instead of the managed `entwurf pi-durable`, so nothing verifies the operator runtime against the pin before its resolver runs",
+			"title": "pi-durable opens the bare app instead of the managed `entwurf pi-durable`, so nothing verifies the carrier and its SDK set before its resolver runs",
 			"subject": "pi-extensions/lib/mux-fresh-call.ts",
 			"find": ["\t\"pi-durable\": \"entwurf\","],
 			"replace": ["\t\"pi-durable\": \"pi\","],
@@ -766,6 +755,17 @@
 			"timeoutSeconds": 120,
 			"signature": "[QK:PD-FRESH-LIVE-FOREIGN-SENDER-REFUSED]",
 			"signatureSource": "test/pi-durable-fresh-live-receipts.test.ts"
+		},
+		{
+			"claim": "PIIMPORT-CARRIER-FENCE",
+			"title": "the carrier fence stops naming bare imports, so a pi-coding-agent specifier or an undeclared package in an emitted carrier file passes the floor",
+			"subject": "run.sh",
+			"find": ["if (name === \"@earendil-works/pi-coding-agent\" || !declared.has(name)) console.log("],
+			"replace": ["if (false) console.log("],
+			"gate": ["bash", "run.sh", "check-pi-import-surface"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:PIIMPORT-CARRIER-FENCE]",
+			"signatureSource": "run.sh"
 		}
 	]
 }

package/scripts/mutants/pack-install.json

@@ -6,7 +6,7 @@
 			"claim": "PACK-INSTALL-PIN-MATCHER-BOUNDED",
 			"title": "the pin-leak matcher loses its version boundary and blesses substring lookalikes — @0.85.10 reads as the pinned 0.85.1 and the gate announces a verified tree it never verified (independent review, 2026-08-25)",
 			"subject": "run.sh",
-			"find": ["  grep '^@earendil-works+' | grep -Ev '@1\\.0\\.2(_|$)' || true"],
+			"find": ["  grep '^@earendil-works+' | grep -Ev '@1\\.0\\.4(_|$)' || true"],
 			"replace": ["  grep '^@earendil-works+' | grep -v '@0\\.87\\.1' || true"],
 			"gate": ["bash", "run.sh", "check-pack-pin-matcher"],
 			"timeoutSeconds": 120,
@@ -17,8 +17,8 @@
 			"claim": "PACK-INSTALL-PIN-MATCHER-COVERS-CLOSURE",
 			"title": "the pin-leak matcher narrows back to the pi-* families and goes blind to a non-pi member of the same runtime closure — @earendil-works/chord (new in pi 0.85.0, a runtime dependency of pi-coding-agent/pi-agent-core/pi-client/pi-protocol) floats unpinned while the gate prints a verified pin (measured 2026-09-06 on a real 0.85.1 install tree)",
 			"subject": "run.sh",
-			"find": ["  grep '^@earendil-works+' | grep -Ev '@1\\.0\\.2(_|$)' || true"],
-			"replace": ["  grep '^@earendil-works+pi-' | grep -Ev '@1\\.0\\.2(_|$)' || true"],
+			"find": ["  grep '^@earendil-works+' | grep -Ev '@1\\.0\\.4(_|$)' || true"],
+			"replace": ["  grep '^@earendil-works+pi-' | grep -Ev '@1\\.0\\.4(_|$)' || true"],
 			"gate": ["bash", "run.sh", "check-pack-pin-matcher"],
 			"timeoutSeconds": 120,
 			"signature": "[QK:PACK-INSTALL-PIN-MATCHER-COVERS-CLOSURE]",