@junghanacs/entwurf 0.39.0 → 0.41.0

package/scripts/check-remote-pair-installed.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * check-remote-pair-installed — #107 rail 3: the remote pair on an INSTALLED package.
+ *
+ * `./run.sh check-remote-pair-installed --tgz <absolute candidate tarball>`
+ *
+ * Why this is a scripts/ gate and not a source-adjacent vitest test: its subject is an ARTIFACT.
+ * It installs a caller-supplied tarball into a fresh consumer prefix with npm and then drives
+ * that install's own processes (its bridge `start.sh` → compiled dist, its `run.sh` → run_ts →
+ * compiled entry). A test beside the source can only reach the source.
+ *
+ * What it does, once, with every writable root (HOME, npm cache/userconfig, XDG, PI agent dir)
+ * inside one temp sandbox:
+ *   1. copies the given tarball into the sandbox and installs THAT copy (never repacks; the copy's
+ *      sha256 is printed). npm reads the package's declared dependencies from the registry into the
+ *      sandbox cache — a network read, but no model, no operator config and no ssh;
+ *   2. checks the installed package carries the receive entry's compiled twin and the remote libs;
+ *   3. runs the installed `entwurf remote-pair-receive` with wrong argv: usage on stderr, exit 2 —
+ *      the compiled twin was reached through run_ts, not a TS crossing;
+ *   4. runs the existing T2 scene (pi-extensions/lib/remote-pair-roundtrip.test.ts) with its subject
+ *      switched to this install: real installed bridge, stand-in ssh → installed run.sh → installed
+ *      entry → production dispatch, with the same mailbox/provenance/receipt/reverse-dispatch oracles;
+ *   5. audits checkout invisibility: a preload resolve hook records every module each SUBJECT
+ *      process resolves; every file must sit (by real path) inside the consumer prefix. The
+ *      orchestrator (vitest + its fixture writer) is this checkout and is not audited;
+ *   6. control: the same hook on this checkout's own `run.sh remote-pair-receive` must report a
+ *      checkout path, so the audit can see the thing it refuses.
+ *
+ * The subject switch (ENTWURF_REMOTE_PAIR_INSTALLED_PKG and the resolve-hook variables) is set
+ * here and only here: it changes what the T2 cells measure, so it must not be set ambiently.
+ *
+ * Mutation proof covers only the audit's acceptance primitive (scripts/lib/remote-pair-installed-audit.ts);
+ * the install, compiled-surface, twin and roundtrip cells are actual-runtime evidence with the
+ * checkout control, not mutation-qualified.
+ *
+ * Not claimed: the published npm artifact (this is whatever tarball the caller passes), real sshd,
+ * a real remote host, a durable host reading or replying, or the check-pack/check-pack-install floor.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { filesOutsideRoot as outside } from "./lib/remote-pair-installed-audit.ts";
+
+const LABEL = "check-remote-pair-installed";
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const args = process.argv.slice(2);
+if (args.length !== 2 || args[0] !== "--tgz" || !path.isAbsolute(args[1])) {
+	console.error(`usage: ./run.sh ${LABEL} --tgz <absolute candidate tarball>`);
+	process.exit(2);
+}
+const tgz = args[1];
+if (!fs.lstatSync(tgz).isFile()) {
+	console.error(`${LABEL}: --tgz must be a regular file (${tgz})`);
+	process.exit(2);
+}
+
+let passed = 0;
+let failed = 0;
+function ok(label: string, cond: boolean, detail = ""): void {
+	if (cond) {
+		passed++;
+		console.log(`  ok    ${label}`);
+	} else {
+		failed++;
+		console.log(`  FAIL  ${label}${detail ? `\n        ${detail}` : ""}`);
+	}
+}
+
+const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), "entwurf-remote-pair-installed-"));
+const consumer = path.join(sandbox, "consumer");
+const npmHome = path.join(sandbox, "npm-home");
+const logs = path.join(sandbox, "resolve-logs");
+const hook = path.join(sandbox, "resolve-hook.mjs");
+for (const d of [consumer, npmHome, logs]) fs.mkdirSync(d, { recursive: true });
+
+function sandboxEnv(home: string): NodeJS.ProcessEnv {
+	return {
+		PATH: process.env.PATH ?? "",
+		HOME: home,
+		XDG_CONFIG_HOME: path.join(home, ".config"),
+		XDG_DATA_HOME: path.join(home, ".local", "share"),
+		XDG_STATE_HOME: path.join(home, ".local", "state"),
+		XDG_CACHE_HOME: path.join(home, ".cache"),
+		PI_CODING_AGENT_DIR: path.join(home, ".pi", "agent"),
+	};
+}
+
+fs.writeFileSync(
+	hook,
+	[
+		'import { appendFileSync } from "node:fs";',
+		'import { registerHooks } from "node:module";',
+		"const log = process.env.ENTWURF_REMOTE_PAIR_RESOLVE_LOG;",
+		"if (log) {",
+		"\tregisterHooks({",
+		"\t\tresolve(specifier, context, next) {",
+		"\t\t\tconst r = next(specifier, context);",
+		'\t\t\tappendFileSync(log, r.url + "\\n");',
+		"\t\t\treturn r;",
+		"\t\t},",
+		"\t});",
+		"}",
+		"",
+	].join("\n"),
+);
+
+function hookEnv(label: string): NodeJS.ProcessEnv {
+	return { NODE_OPTIONS: `--import=${hook}`, ENTWURF_REMOTE_PAIR_RESOLVE_LOG: path.join(logs, `${label}.log`) };
+}
+
+// The artifact is a snapshot: copy the caller's file into the sandbox once, then hash and install
+// THAT copy, so what is measured is exactly what is installed. Never repacked.
+const snapshot = path.join(sandbox, "artifact", path.basename(tgz));
+fs.mkdirSync(path.dirname(snapshot), { recursive: true });
+fs.copyFileSync(tgz, snapshot);
+const sha = createHash("sha256").update(fs.readFileSync(snapshot)).digest("hex");
+console.log(
+	`[${LABEL}] caller tarball ${tgz}\n[${LABEL}] snapshot ${snapshot}\n[${LABEL}] snapshot sha256 ${sha}\n[${LABEL}] sandbox ${sandbox}`,
+);
+
+try {
+	// 1. Install as-is.
+	fs.writeFileSync(
+		path.join(consumer, "package.json"),
+		JSON.stringify({ name: "remote-pair-consumer", private: true }),
+	);
+	const npm = spawnSync("npm", ["install", snapshot, "--no-audit", "--no-fund"], {
+		cwd: consumer,
+		encoding: "utf8",
+		env: {
+			...sandboxEnv(npmHome),
+			npm_config_cache: path.join(sandbox, "npm-cache"),
+			npm_config_userconfig: path.join(npmHome, ".npmrc"),
+		},
+	});
+	ok(
+		"[QK:RPI-INSTALLED] npm installs the given tarball into a fresh consumer prefix",
+		npm.status === 0,
+		npm.stderr.slice(-800),
+	);
+	const pkg = path.join(consumer, "node_modules", "@junghanacs", "entwurf");
+	const pkgStat = fs.existsSync(pkg) ? fs.lstatSync(pkg) : null;
+	ok(
+		"[QK:RPI-INSTALLED] the package is a real directory inside the consumer (not a link to a checkout)",
+		pkgStat !== null && pkgStat.isDirectory() && !pkgStat.isSymbolicLink(),
+	);
+	if (failed) throw new Error("install failed; later cells would not measure the artifact");
+
+	// 2. The compiled surface is in the package.
+	for (const rel of [
+		"mcp/entwurf-bridge/dist/scripts/remote-pair-receive.js",
+		"mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-receive.js",
+		"mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-send.js",
+		"mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-transport.js",
+	]) {
+		ok(`[QK:RPI-COMPILED-SURFACE] the installed package carries ${rel}`, fs.existsSync(path.join(pkg, rel)));
+	}
+
+	// 3. The installed bin reaches the compiled twin.
+	const home = path.join(sandbox, "usage-home");
+	const usage = spawnSync(path.join(pkg, "run.sh"), ["remote-pair-receive"], {
+		encoding: "utf8",
+		env: { ...sandboxEnv(home), ...hookEnv("installed-usage") },
+	});
+	ok(
+		"[QK:RPI-INSTALLED-ENTRY-TWIN] the installed `entwurf remote-pair-receive` answers wrong argv with usage on stderr, exit 2, no receipt",
+		usage.status === 2 && /usage: entwurf remote-pair-receive/.test(usage.stderr) && usage.stdout === "",
+		`status=${usage.status} stdout=${usage.stdout.slice(0, 200)} stderr=${usage.stderr.slice(0, 300)}`,
+	);
+
+	// 4. The T2 scene against the install.
+	const vitest = spawnSync(
+		path.join(REPO, "node_modules", ".bin", "vitest"),
+		["run", "pi-extensions/lib/remote-pair-roundtrip.test.ts"],
+		{
+			cwd: REPO,
+			encoding: "utf8",
+			env: {
+				...process.env,
+				ENTWURF_REMOTE_PAIR_INSTALLED_PKG: pkg,
+				ENTWURF_REMOTE_PAIR_RESOLVE_HOOK: hook,
+				ENTWURF_REMOTE_PAIR_RESOLVE_LOG_DIR: logs,
+			},
+		},
+	);
+	const summary = (vitest.stdout.match(/Tests\s+.*$/m) ?? [""])[0].trim();
+	ok(
+		"[QK:RPI-ROUNDTRIP-ON-INSTALL] the T2 cells (A→B, reverse dispatch, opt-in absent off, other host refuses, both socket dirs) pass against the installed bridge and entry",
+		vitest.status === 0 && /^Tests\s+5 passed\b/.test(summary),
+		`${summary}\n${vitest.stdout
+			.split("\n")
+			.filter((l) => /×|FAIL|Error/.test(l))
+			.slice(0, 10)
+			.join("\n")}`,
+	);
+
+	// 5. Checkout invisibility of the subject processes.
+	const all = fs.readdirSync(logs).map((n) => path.join(logs, n));
+	const bridgeLogs = all.filter((f) => path.basename(f).startsWith("bridge-"));
+	const entryLogs = all.filter((f) => path.basename(f).startsWith("entry-"));
+	const subjectLogs = [...bridgeLogs, ...entryLogs, ...all.filter((f) => path.basename(f) === "installed-usage.log")];
+	ok(
+		"[QK:RPI-AUDIT-SAW-SUBJECTS] the resolve hook recorded the installed bridge processes and the installed entry processes",
+		bridgeLogs.some((f) => fs.statSync(f).size > 0) && entryLogs.some((f) => fs.statSync(f).size > 0),
+		`bridge logs=${bridgeLogs.length} entry logs=${entryLogs.length}`,
+	);
+	const audit = outside(subjectLogs, consumer);
+	ok(
+		`[QK:RPI-CHECKOUT-INVISIBLE] every module the installed subject processes resolved (${audit.total}) sits inside the consumer prefix`,
+		audit.total > 0 && audit.outside.length === 0,
+		audit.outside.slice(0, 10).join("\n        "),
+	);
+
+	// 6. Control: the audit sees a checkout when there is one.
+	const control = spawnSync(path.join(REPO, "run.sh"), ["remote-pair-receive"], {
+		encoding: "utf8",
+		env: { ...sandboxEnv(path.join(sandbox, "control-home")), ...hookEnv("control-checkout") },
+	});
+	const controlAudit = outside([path.join(logs, "control-checkout.log")], consumer);
+	const realRepo = fs.realpathSync(REPO);
+	ok(
+		"[QK:RPI-AUDIT-CONTROL] the same audit on this checkout's own entry reports checkout paths (the detector is live)",
+		control.status === 2 && controlAudit.outside.some((p) => p.startsWith(`${realRepo}${path.sep}`)),
+		`status=${control.status} outside=${controlAudit.outside.length}`,
+	);
+} catch (err) {
+	ok(`[${LABEL}] gate ran to completion`, false, err instanceof Error ? err.message : String(err));
+} finally {
+	// Synthetic fixture data only. Kept on failure so the resolve logs and npm output can be read.
+	if (failed === 0) fs.rmSync(sandbox, { recursive: true, force: true });
+	else console.log(`[${LABEL}] kept the sandbox for diagnosis: ${sandbox}`);
+}
+
+console.log(
+	`\n${LABEL}: ${passed} passed, ${failed} failed — installed artifact ${sha.slice(0, 12)}; no real ssh, no model`,
+);
+process.exit(failed === 0 ? 0 : 1);

package/scripts/check-resume-launch-identity.ts

@@ -1,12 +1,10 @@
 /**
  * check-resume-launch-identity — deterministic gate for `resume-launch-identity.ts`, the
- * record-authoritative leaf preserved when the visible-first cut deleted `spawn-bg` and every
- * caller it had.
+ * record-authoritative leaf of a visible same-id resume (its consumer is `entwurf-v2-visible-resume`).
  *
- * WHY A GATE FOR A CONSUMER-ZERO MODULE. Identity authority is a fail-closed risk class: this
- * leaf's whole job is deciding WHICH being a resume turn lands in. A preserved leaf whose only
- * guarantee is its own header comment is exactly the rot preservation was meant to prevent — it
- * would be re-adopted, months later, by a visible-resume composition that trusts prose. The cells
+ * WHY A GATE FOR AN IDENTITY LEAF. Identity authority is a fail-closed risk class: this leaf's whole
+ * job is deciding WHICH being a resume lands in. A leaf whose only guarantee is its own header
+ * comment would be trusted as prose by every composition that calls it. The cells
  * below are transplanted from the deleted `check-entwurf-v2-spawn-production` §9 (the plan
  * parameter became a bare garden id; nothing else about the identity contract changed), plus one
  * new cell for the #52 read the leaf's header claims and the deleted gate never isolated.
@@ -25,14 +23,18 @@
  *      backend, no recorded transcript, recorded-but-missing file, no model, headerless file. The
  *      missing-file cell is a regression pin: before the existence check that case fell through
  *      `readSessionIdentity`'s ENOENT swallow and lied "no recorded model".
- *   4b. THE ONE EXPECTED REFUSAL — a backend with no same-id resume is not a defect at all: the
- *      record is fine and the operator reached past a capability boundary. It alone carries a
- *      TYPED reason (`target-not-pi`) so the visible-resume composition can match a FIELD instead
- *      of parsing a sentence or re-reading the record. Everything else here stays a bare throw.
+ *   4b. THE ONE EXPECTED REFUSAL — a backend with no same-id resume (since #147 L2: anything but pi
+ *      and claude-code) is not a defect at all: the record is fine and the operator reached past a
+ *      capability boundary. It alone carries a TYPED reason (`target-backend-unsupported`) so the
+ *      visible-resume composition can match a FIELD instead of parsing a sentence or re-reading the
+ *      record. Everything else here stays a bare throw.
+ *   4e. CLAUDE CODE (#147 L2) — a claude-code record resolves to its own session id, the record's
+ *      cwd and createdAt, reading no transcript; a session id outside the lowercase-UUID grammar and
+ *      a recorded transcript that is not a file on disk are each refused with their own cause.
  *   4c. ABSOLUTE TRANSCRIPT — a relative recorded path would resolve against the WINDOW's own cwd
  *      at launch, not against this process's, so it names a different file than the one checked
  *      here. Refused before anything opens.
- *   5. SSOT — the module header names THIS gate, so the preserved leaf cannot advertise a
+ *   5. SSOT — the module header names THIS gate and its consumer, so the leaf cannot advertise a
  *      certification that does not exist.
  *
  * No spawn, no socket, no timer: the launch this identity feeds is deliberately not in scope.
@@ -91,12 +93,49 @@ function main(): void {
 			ok(label, msg.includes(needle));
 		};
 
+		// ── 4e. CLAUDE CODE (#147 L2) ─────────────────────────────────────────────────
+		{
+			const native = "0b5e2a4c-1f3d-4e8a-9c7b-2d6f8e1a3c5d";
+			const transcript = writeTranscript("cc-session.jsonl", "vendor-owned bytes this leaf never parses\n");
+			const gidCc = mintRecord(native, transcript, "claude-code");
+			const raw = JSON.parse(fs.readFileSync(path.join(storeDir, `${gidCc}.meta.json`), "utf8")) as {
+				createdAt: string;
+			};
+			let cc: ReturnType<typeof resolveResumeLaunchIdentity> | null = null;
+			try {
+				cc = resolveResumeLaunchIdentity(gidCc);
+			} catch {
+				cc = null;
+			}
+			ok(
+				"4e: a claude-code record resolves to its own session id, the record's cwd and createdAt [QK:RESUME-ID-CC-RESOLVES]",
+				cc?.backend === "claude-code" &&
+					cc.nativeSessionId === native &&
+					cc.cwd === cwd &&
+					cc.createdAt === raw.createdAt,
+			);
+			rejects(
+				mintRecord("--dangerously-skip-permissions", transcript, "claude-code"),
+				"is not a Claude Code session id",
+				"4e: a recorded session id outside the UUID grammar is refused before it can become a claude flag [QK:RESUME-ID-CC-SESSION-GRAMMAR]",
+			);
+			rejects(
+				mintRecord("0b5e2a4c-1f3d-4e8a-9c7b-2d6f8e1a3c5e", path.join(world, "gone.jsonl"), "claude-code"),
+				"is not a file on disk",
+				"4e: a recorded transcript that is gone is refused — claude --resume would open nothing [QK:RESUME-ID-CC-TRANSCRIPT-PRESENT]",
+			);
+		}
+
 		// ── 1. HAPPY ──────────────────────────────────────────────────────────────
 		const nativeOk = "0199aaaa-1111-4222-8333-444455556666";
 		const fileOk = writeTranscript("own.jsonl", sessionLine(nativeOk) + modelLine);
 		const gidOk = mintRecord(nativeOk, fileOk);
 		const launch = resolveResumeLaunchIdentity(gidOk);
-		ok("1: record-backed resume resolves the recorded transcript", launch.sessionFile === fileOk);
+		assert.ok(launch.backend === "pi", "1: a pi record resolves as pi");
+		ok(
+			"1: record-backed resume resolves the recorded transcript",
+			launch.backend === "pi" && launch.sessionFile === fileOk,
+		);
 		ok("1: resume cwd = transcript header authority (#9 cold-resume)", launch.cwd === cwd);
 		ok(
 			"1: resume model/provider = first model_change",
@@ -122,29 +161,29 @@ function main(): void {
 		// ── 4. CAUSE FIDELITY ─────────────────────────────────────────────────────
 		rejects("20260101T000000-facade", "not a garden citizen", "4: recordless gid → not a citizen");
 
-		const gidClaude = mintRecord("claude-native-1", null, "claude-code");
+		const gidCodex = mintRecord("codex-thread-1", null, "codex");
 		rejects(
-			gidClaude,
-			"is a claude-code citizen",
+			gidCodex,
+			"is a codex citizen",
 			"4: out-of-domain citizen → refused as a capability-domain miss, not as citizen rank",
 		);
 		// This one refusal is EXPECTED, not a defect: the record is perfectly good and the operator
 		// has reached past a capability boundary. So it is the only failure here that carries a
 		// typed `reason` a caller can match on a FIELD — the visible-resume composition turns it
-		// into `target-not-pi`, and if it degraded to a bare Error that caller would either parse
+		// into `target-backend-unsupported`, and if it degraded to a bare Error that caller would either parse
 		// this sentence or read the record a second time to ask which backend it was.
 		{
 			let caught: Error | null = null;
 			try {
-				resolveResumeLaunchIdentity(gidClaude);
+				resolveResumeLaunchIdentity(gidCodex);
 			} catch (err) {
 				caught = err as Error;
 			}
 			ok(
 				"4: the backend miss is a TYPED refusal carrying reason + backend, not a bare Error [QK:RESUME-ID-BACKEND-TYPED-REFUSAL]",
 				caught instanceof ResumeBackendUnsupportedError &&
-					caught.reason === "target-not-pi" &&
-					caught.backend === "claude-code",
+					caught.reason === "target-backend-unsupported" &&
+					caught.backend === "codex",
 			);
 		}
 
@@ -195,7 +234,8 @@ function main(): void {
 					retired.err.model === "claude-sonnet-5" &&
 					routed.err instanceof AcpModelNotCuratedError &&
 					routed.err.model === "claude-opus-5" &&
-					current.identity?.provider === "entwurf" &&
+					current.identity?.backend === "pi" &&
+					current.identity.provider === "entwurf" &&
 					current.identity.model === "claude-sonnet-5-5",
 			);
 		}
@@ -243,6 +283,7 @@ function main(): void {
 				transcriptPath: fileOk,
 				createdAt: "2026-03-01T12:00:00.000Z",
 				recordUpdatedAt: "2026-03-01T12:30:00.000Z",
+				attachIncarnation: null,
 			}),
 		);
 		// The happy-path id resolved a moment ago; the ONLY thing that changed is a second record
@@ -271,9 +312,7 @@ function main(): void {
 			"5: the leaf's header names check-resume-launch-identity (no certification it does not have) [QK:RESUME-ID-GATE-SSOT]",
 			src.includes("`check-resume-launch-identity`"),
 		);
-		// The preservation is deliberate and stated: a reader who finds an uncalled export must
-		// be able to tell "kept on purpose, for the visible lane" from "forgotten".
-		ok("5: the leaf states it is preserved with no consumer, on purpose", /no consumer in the shipped tree/.test(src));
+		ok("5: the leaf names its consumer", /`entwurf-v2-visible-resume` is its consumer/.test(src));
 	}
 
 	console.log(`\ncheck-resume-launch-identity: ${passed} checks passed`);

package/scripts/lib/meta-hook-bundle.ts

@@ -0,0 +1,72 @@
+/**
+ * meta-hook-bundle — the Claude Code hook bundle a gate stages, derived from the hook's OWN
+ * import graph rather than from a hand-kept file list (#147 L2 B1).
+ *
+ * The installed bundle is the entry plus exactly the `lib/` files `meta-bridge-install.sh`
+ * copies. A gate that hand-copies its own list can pass while the installer misses a file the
+ * hook now imports — the false green this module exists to remove. So a staged bundle carries
+ * the entry's import closure, and `installerCopiedLibFiles` reads what the installer actually
+ * copies, for the gate to compare the two.
+ *
+ * SCOPE, deliberately narrow: only static `from "./…"` / `from "../…"` specifiers in DOUBLE
+ * quotes — the one form the hook's closure (entry, meta-session, entwurf-v2-lock, session-id)
+ * uses today. A side-effect `import "./x"`, a dynamic `import("./x")`, a `require`, or a
+ * single-quoted specifier is NOT followed, so the comparison says nothing about them; this is
+ * not a general module resolver and must not grow into one. `meta-session`'s win32 addon is
+ * one such unfollowed load (`createRequire`, win32 only, outside the Linux/macOS bundle). The
+ * independent proof that the closure is complete is the gate RUNNING the staged compiled hook.
+ */
+
+import { chmodSync, copyFileSync, mkdirSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+
+const IMPORT_RE = /\bfrom\s+"(\.{1,2}\/[^"]+)"/g;
+
+/**
+ * The entry's relative-import closure, as paths relative to the entry's directory
+ * (`lib/meta-session.ts`, …). The entry itself is not included.
+ */
+export function hookImportClosure(entryFile: string): string[] {
+	const root = path.dirname(entryFile);
+	const seen = new Set<string>();
+	const visit = (file: string): void => {
+		const source = readFileSync(file, "utf8");
+		for (const match of source.matchAll(IMPORT_RE)) {
+			const target = path.resolve(path.dirname(file), match[1] as string);
+			const rel = path.relative(root, target);
+			if (seen.has(rel)) continue;
+			seen.add(rel);
+			visit(target);
+		}
+	};
+	visit(entryFile);
+	return [...seen].sort();
+}
+
+/** The `lib/<name>` destinations `meta-bridge-install.sh` copies into the assembled plugin. */
+export function installerCopiedLibFiles(installerText: string): string[] {
+	const out = new Set<string>();
+	for (const match of installerText.matchAll(/^cp\s.*"\$ASM\/\$PLUGIN\/lib\/([^"]+)"\s*$/gm)) {
+		out.add(match[1] as string);
+	}
+	return [...out].sort();
+}
+
+/**
+ * Stage entry + its import closure + the launcher under `root`, exactly as installed. `entryFile`
+ * is the source (`pi-extensions/meta-bridge-hook.ts`) or the compiled entry
+ * (`mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-hook.js`); the closure follows whichever.
+ */
+export function stageMetaHookBundle(root: string, entryFile: string, launcher: string): string[] {
+	const closure = hookImportClosure(entryFile);
+	mkdirSync(path.join(root, "scripts"), { recursive: true });
+	copyFileSync(entryFile, path.join(root, path.basename(entryFile)));
+	for (const rel of closure) {
+		mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+		copyFileSync(path.join(path.dirname(entryFile), rel), path.join(root, rel));
+	}
+	const staged = path.join(root, "scripts", "hook-launch.sh");
+	copyFileSync(launcher, staged);
+	chmodSync(staged, 0o755);
+	return closure;
+}

package/scripts/lib/remote-pair-installed-audit.ts

@@ -0,0 +1,25 @@
+/**
+ * The acceptance primitive of `check-remote-pair-installed`'s checkout-invisibility cell (#107 rail 3),
+ * as a pure function over resolve-hook logs so it can be proven on tiny synthetic files
+ * (test/remote-pair-installed-audit.test.ts). Each log line is one URL a subject process resolved.
+ * A `file:` URL counts and is judged by its REAL path; anything else (node: builtins) is ignored.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Every file the logs name that is NOT inside `root` (both compared by real path), and how many file URLs were read. */
+export function filesOutsideRoot(logFiles: readonly string[], root: string): { total: number; outside: string[] } {
+	const realRoot = fs.realpathSync(root);
+	const out = new Set<string>();
+	let total = 0;
+	for (const f of logFiles) {
+		for (const url of fs.readFileSync(f, "utf8").split("\n").filter(Boolean)) {
+			if (!url.startsWith("file:")) continue;
+			total++;
+			const real = fs.realpathSync(fileURLToPath(url));
+			if (real !== realRoot && !real.startsWith(`${realRoot}${path.sep}`)) out.add(real);
+		}
+	}
+	return { total, outside: [...out].sort() };
+}

package/scripts/meta-bridge-claude-floor.sh

@@ -6,7 +6,8 @@
 #
 # The floor is a full three-part version, not a major lane: the discriminator sits
 # in the PATCH position (2.1.138 drops `args`, 2.1.139 introduced the exec form,
-# 2.1.217 is the version this repo actually proved in a live session). A major-only
+# 2.1.217 is the version this repo proved the exec form on in a live session, 2.1.223
+# is where `--resume <id>` started finding a session outside the current project). A major-only
 # comparison like the Node floor's `-lt 24` cannot express it, so a real semver
 # compare has to exist — and it must exist exactly ONCE. Two hand-rolled compares in
 # two shell scripts is how "the installer blessed a version the doctor refuses"
@@ -16,15 +17,18 @@
 # `entwurf.claudeCodeFloor` is the SSOT and everything here reads it. There is one
 # number to move. `check-claude-floor-coherence` binds every other spelling of it.
 #
-# WHY THE FLOOR IS 2.1.217 AND NOT 2.1.139
+# WHY THE FLOOR IS 2.1.306
 #
-# 2.1.139 is where the exec-form strings enter the binary, but no session was ever
-# run on it — the floor would have been an inference. 2.1.217 is the version whose
-# runtime behavior was actually observed end to end (#51 B2: `args` honored per
-# element, no shell on the launch path, `asyncRewake` exit 2 waking an idle session).
-# GLG's decision (2026-07-22): Claude Code auto-updates, so entwurf does not carry
-# back-compat for versions it never verified. Declare the proven floor, not the
-# earliest plausible one.
+# 2.1.217 is the version whose exec-form runtime behavior was observed end to end
+# (#51 B2: `args` honored per element, no shell on the launch path, `asyncRewake` exit 2
+# waking an idle session); those observations stand. #147 added same-id visible resume
+# of a Claude Code citizen, which runs `claude --resume <nativeSessionId>` from the
+# record's LAST OBSERVED cwd. The vendor CLI reference (code.claude.com cli-reference,
+# read 2026-10-21, unversioned page) says the session-id search covers every project on
+# the machine only from v2.1.223; below it a session whose cwd moved may not be found.
+# GLG's decision (2026-10-21): the floor follows what the direction needs, with no
+# back-compat — 2.1.306, the version GLG relayed as running here. That number is a
+# declared floor: no LIVE receipt has been taken at it yet.
 #
 # Requires: python3 (already a hard dependency of both callers).
 

package/scripts/meta-bridge-doctor.sh

@@ -53,8 +53,10 @@ esac
 # a second derivation is a second thing to forget when the layout moves.
 if [ "$LIB_EXT" = "js" ]; then
   SRC_MS="$REPO/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js"
+  SRC_LOCK="$REPO/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-lock.js"
 else
   SRC_MS="$REPO/pi-extensions/lib/meta-session.ts"
+  SRC_LOCK="$REPO/pi-extensions/lib/entwurf-v2-lock.ts"
 fi
 # shellcheck source=scripts/meta-bridge-hook-log.sh
 source "$REPO/scripts/meta-bridge-hook-log.sh"
@@ -1276,6 +1278,21 @@ fi
 if [ -f "$ASM_MS" ] && [ "$asm_h" != "$src_h" ]; then
   warn "assembled bundle differs from source ($asm_v vs $src_v) — stale .assembled; install re-assembles it"
 fi
+# The hook's record-arm lock (#147 L2 B1) is part of the same writer closure: a writer that
+# commits an arm binding without the lock module it imports cannot load at all, and a stale one
+# serializes against a different contract. Same authority as the writer: the INSTALLED bundle.
+src_lock_h="$(hash12 "$SRC_LOCK")"
+if [ -n "${INST_MS:-}" ]; then
+  INST_LOCK="$(dirname "$INST_MS")/entwurf-v2-lock.$LIB_EXT"
+  inst_lock_h="$(hash12 "$INST_LOCK")"
+  if [ ! -f "$INST_LOCK" ]; then
+    bad "deployed hook lock module MISSING ($INST_LOCK) — the hook imports it, so the installed writer cannot load. Run ./run.sh install-meta-bridge to redeploy."
+  elif [ "$inst_lock_h" != "$src_lock_h" ]; then
+    bad "deployed hook lock module STALE: installed=$inst_lock_h vs source=$src_lock_h ($INST_LOCK). Run ./run.sh install-meta-bridge to redeploy."
+  else
+    ok "deployed hook lock module matches source ($inst_lock_h)"
+  fi
+fi
 
 # Identity-writer dependency: loadMetaCapabilityRegistry reads
 # entwurf-capabilities.json at runtime. In the bundle layout it must sit at the

package/scripts/meta-bridge-install.sh

@@ -58,11 +58,13 @@ case "$REPO" in
     HOOK_ENTRY="meta-bridge-hook.js"
     HOOK_SRC="$REPO/mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-hook.js"
     LIB_SRC="$REPO/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js"
+    LOCK_SRC="$REPO/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-lock.js"
     LIB_EXT="js" ;;
   *)
     HOOK_ENTRY="meta-bridge-hook.ts"
     HOOK_SRC="$REPO/pi-extensions/meta-bridge-hook.ts"
     LIB_SRC="$REPO/pi-extensions/lib/meta-session.ts"
+    LOCK_SRC="$REPO/pi-extensions/lib/entwurf-v2-lock.ts"
     LIB_EXT="ts" ;;
 esac
 
@@ -187,9 +189,13 @@ cp -r "$SRC/$PLUGIN" "$ASM/$PLUGIN"
 # Installed → tsc-emitted JS (dist, node_modules-safe); dev clone → strip-types .ts.
 [ -f "$HOOK_SRC" ] || die "hook artifact missing: $HOOK_SRC (installed package ships it via prepack build-bridge → dist; reinstall @junghanacs/entwurf, or run 'pnpm run build-bridge' in a dev clone)."
 [ -f "$LIB_SRC" ]  || die "hook lib artifact missing: $LIB_SRC (same build-bridge dist closure)."
+[ -f "$LOCK_SRC" ] || die "hook lock artifact missing: $LOCK_SRC (same build-bridge dist closure)."
 cp "$HOOK_SRC" "$ASM/$PLUGIN/$HOOK_ENTRY"
 mkdir -p "$ASM/$PLUGIN/lib"
 cp "$LIB_SRC" "$ASM/$PLUGIN/lib/meta-session.$LIB_EXT"
+# The record-arm lock (#147 L2 B1): the hook imports the shared per-gid lock primitive, so it
+# travels in the same closure. The doctor's writer-version parity hashes it beside the writer.
+cp "$LOCK_SRC" "$ASM/$PLUGIN/lib/entwurf-v2-lock.$LIB_EXT"
 cp "$REPO/pi-extensions/lib/session-id.js" "$ASM/$PLUGIN/lib/session-id.js"
 # v2 writer (3D-3+) reads the capability registry at runtime
 # (loadMetaCapabilityRegistry). It MUST travel at the plugin ROOT — meta-session's

package/scripts/meta-facts.ts

@@ -15,7 +15,7 @@
  *   {
  *     "schemaVersion": 1,          // of THIS projection, not of the records
  *     "storeDir": "/abs/path",
- *     "citizens": [ <full verbatim strict 9-field v3 records, sorted by gardenId> ],
+ *     "citizens": [ <full verbatim strict v3 records, sorted by gardenId> ],
  *     "defects":  [ { "filename", "message" }, … sorted by filename ]
  *   }
  *

package/scripts/mutants/bridge-boot-resume.json

@@ -19,9 +19,12 @@
 			"claim": "BRIDGEBOOT-RESUME-CALL-TARGET-ONLY",
 			"title": "a model knob is added to the resume schema, giving the caller a second way to decide what a resumed citizen is after the record already decided",
 			"subject": "mcp/entwurf-bridge/src/index.ts",
-			"find": ["\t\t\t.describe(\"Garden id of the DORMANT pi citizen to reopen (discover with entwurf_peers).\"),"],
+			"find": [
+				"\t\t\t.describe(\"Garden id of the DORMANT pi or Claude Code citizen to reopen (discover with entwurf_peers).\"),"
+			],
 			"replace": [
-				"\t\t\t.describe(\"Garden id of the DORMANT pi citizen to reopen (discover with entwurf_peers).\"),\n\t\tmodel: z.string().optional().describe(\"Override the recorded model.\"),"
+				"\t\t\t.describe(\"Garden id of the DORMANT pi or Claude Code citizen to reopen (discover with entwurf_peers).\"),",
+				"\t\tmodel: z.string().optional().describe(\"Override the recorded model.\"),"
 			],
 			"gate": ["bash", "run.sh", "check-entwurf-bridge-boot"],
 			"timeoutSeconds": 120,