@junghanacs/entwurf 0.30.1 → 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-fresh-live-receipts.ts

@@ -0,0 +1,139 @@
+/**
+ * The oracles of `smoke-pi-durable-fresh-live`, as pure functions over raw evidence, so the same code
+ * that judges a live run can re-judge its saved raw (Pi's JSONL and the pd native-store snapshot).
+ *
+ * Pi side: a message lands only as an exact payload with ONE anchored terminal sender envelope —
+ * `piCallbackSenders` already decides that shape; this adds the expected sender and returns the row.
+ * A body that merely MENTIONS the token and the sender's id (the fixture's own instruction did) is
+ * not a delivery.
+ *
+ * pd side: the native store's ROOT conversation only (no owner conversation or task), read through
+ * its entry kinds — `pi.system` (tool offering, applied as toolsAdded/toolsRemoved in order),
+ * `pi.assistant` (the model that answered, and the tool calls in order) and `pi.tool-result` (each
+ * call's settled result, joined by toolCallId).
+ */
+import { piCallbackSenders } from "./codex-fresh-source-receipts.ts";
+
+/** The one Pi transcript row whose exact payload arrived from `expectedSender`, or null. */
+export function piExactDeliveryRow(
+	entries: readonly unknown[],
+	payload: string,
+	expectedSender: string,
+): { row: unknown; index: number } | null {
+	const hits: { row: unknown; index: number }[] = [];
+	entries.forEach((row, index) => {
+		const senders = piCallbackSenders([row], payload);
+		if (senders.length === 1 && senders[0] === expectedSender) hits.push({ row, index });
+	});
+	return hits.length === 1 ? (hits[0] as { row: unknown; index: number }) : null;
+}
+
+export interface PdNativeRow {
+	id: number;
+	conversation_id: number;
+	record: string;
+}
+export interface PdNativeSubmissionRow {
+	conversation_id: number;
+	status: string;
+	record: string;
+}
+export interface PdToolCall {
+	id: string;
+	name: string;
+	arguments: Record<string, unknown>;
+	result: { text: string; isError: boolean } | null;
+}
+export interface PdRootView {
+	offering: string[];
+	models: string[];
+	calls: PdToolCall[];
+}
+
+interface Message {
+	role?: unknown;
+	provider?: unknown;
+	model?: unknown;
+	content?: unknown;
+	toolsAdded?: unknown;
+	toolsRemoved?: unknown;
+	toolCallId?: unknown;
+	isError?: unknown;
+}
+
+function messagesOf(record: Record<string, unknown>): Message[] {
+	return Array.isArray(record.model) ? (record.model as Message[]) : [];
+}
+function names(list: unknown): string[] {
+	return Array.isArray(list)
+		? list.flatMap((t) =>
+				t !== null && typeof t === "object" && typeof (t as { name?: unknown }).name === "string"
+					? [(t as { name: string }).name]
+					: [],
+			)
+		: [];
+}
+
+/** The root conversation's offering, models and tool calls, from its own entries in id order. */
+export function pdRootView(entries: readonly PdNativeRow[], rootConversationId: number): PdRootView {
+	let offering: string[] = [];
+	const models = new Set<string>();
+	const calls: PdToolCall[] = [];
+	const byId = new Map<string, PdToolCall>();
+	for (const row of [...entries].sort((a, b) => a.id - b.id)) {
+		if (row.conversation_id !== rootConversationId) continue;
+		const record = JSON.parse(row.record) as Record<string, unknown>;
+		for (const message of messagesOf(record)) {
+			if (record.kind === "pi.system") {
+				const removed = new Set(names(message.toolsRemoved));
+				offering = [...offering.filter((n) => !removed.has(n)), ...names(message.toolsAdded)];
+			} else if (record.kind === "pi.assistant" && message.role === "assistant") {
+				if (typeof message.provider === "string" && typeof message.model === "string")
+					models.add(`${message.provider}/${message.model}`);
+				for (const block of Array.isArray(message.content) ? message.content : []) {
+					const b = block as { type?: unknown; id?: unknown; name?: unknown; arguments?: unknown };
+					if (b.type !== "toolCall" || typeof b.id !== "string" || typeof b.name !== "string") continue;
+					const call: PdToolCall = {
+						id: b.id,
+						name: b.name,
+						arguments: (b.arguments ?? {}) as Record<string, unknown>,
+						result: null,
+					};
+					calls.push(call);
+					byId.set(b.id, call);
+				}
+			} else if (
+				record.kind === "pi.tool-result" &&
+				message.role === "toolResult" &&
+				typeof message.toolCallId === "string"
+			) {
+				const call = byId.get(message.toolCallId);
+				if (call === undefined) continue;
+				const text = (Array.isArray(message.content) ? message.content : [])
+					.map((c) =>
+						(c as { type?: unknown; text?: unknown }).type === "text" ? String((c as { text: unknown }).text) : "",
+					)
+					.join("");
+				call.result = { text, isError: message.isError === true };
+			}
+		}
+	}
+	return { offering, models: [...models], calls };
+}
+
+/** The doorbell submission for exactly this mailbox message, on the root conversation. */
+export function pdDoorbellSubmission(
+	submissions: readonly PdNativeSubmissionRow[],
+	rootConversationId: number,
+	requestId: string,
+): { status: string; record: Record<string, unknown> } | null {
+	const hits = submissions
+		.map((s) => ({ s, record: JSON.parse(s.record) as Record<string, unknown> }))
+		.filter(({ s, record }) => s.conversation_id === rootConversationId && record.requestId === requestId);
+	return hits.length === 1
+		? {
+				status: (hits[0] as { s: PdNativeSubmissionRow }).s.status,
+				record: (hits[0] as { record: Record<string, unknown> }).record,
+			}
+		: null;
+}

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);
+}