@junghanacs/entwurf 0.25.1 → 0.30.1

package/scripts/check-herdr-plugin-build.ts

@@ -53,6 +53,20 @@ const COMPILED_ENTRY = path.join("mcp", "entwurf-bridge", "dist", "mcp", "entwur
 const COMMIT_A = "a".repeat(40);
 const COMMIT_B = "b".repeat(40);
 
+// Fixture inputs, not registry assertions. The npm coherence check reads this checkout's
+// package.json, so its version is input; neither an unpublished version nor the committed
+// carrier may choose which source these deterministic cells exercise. No network is used.
+const FIXTURE_VERSION = (JSON.parse(fs.readFileSync(path.join(REPO, "package.json"), "utf8")) as { version: string })
+	.version;
+const FIXTURE_NPM_LOCK = Object.freeze({
+	source: "npm",
+	name: PACKAGE,
+	version: FIXTURE_VERSION,
+	integrity: `sha512-${createHash("sha512").update("hpb-npm-fixture").digest("base64")}`,
+});
+const FIXTURE_OTHER_INTEGRITY = `sha512-${createHash("sha512").update("hpb-npm-other-fixture").digest("base64")}`;
+const FIXTURE_CHECKOUT_LOCK = Object.freeze({ source: "herdr-checkout", repository: "junghan0611/entwurf" });
+
 interface SpawnResult {
 	status: number | null;
 	stdout: string;
@@ -175,9 +189,10 @@ function tree(root: string): string[] {
  */
 function fixtureAcquire(opts: { activate: "absent" | "incapable" | "recorder"; log?: string; fail?: boolean }) {
 	return ({ identity, prefix }: AcquireArgs) => {
+		const version = identity.version ?? FIXTURE_VERSION;
 		const root = path.join(prefix, "node_modules", PACKAGE);
 		fs.mkdirSync(path.join(root, path.dirname(COMPILED_ENTRY)), { recursive: true });
-		fs.writeFileSync(path.join(root, "package.json"), `${JSON.stringify({ name: PACKAGE, version: "0.21.0" })}\n`);
+		fs.writeFileSync(path.join(root, "package.json"), `${JSON.stringify({ name: PACKAGE, version })}\n`);
 		fs.writeFileSync(path.join(root, COMPILED_ENTRY), "// compiled entry fixture\n");
 		const bin = path.join(prefix, "node_modules", ".bin");
 		fs.mkdirSync(bin, { recursive: true });
@@ -208,7 +223,7 @@ function fixtureAcquire(opts: { activate: "absent" | "incapable" | "recorder"; l
 				.update(identity.commit ?? "x")
 				.digest("hex")}`,
 			packageName: PACKAGE,
-			packageVersion: "0.21.0",
+			packageVersion: version,
 		};
 	};
 }
@@ -249,6 +264,9 @@ function drive(
 			spawn,
 			write: (t: string) => (out += t),
 			progress,
+			// Existing gate-only seam. Production still reads the committed lock, and its
+			// real source/coherence is independently checked by check-herdr-runtime-bootstrap.
+			readRuntimeLock: () => FIXTURE_NPM_LOCK,
 			...deps,
 		});
 		return { code, refusal: null, out, progress: progressLines };
@@ -408,57 +426,121 @@ function drive(
 
 // ── 6. the two-stage journey, as the RUNNER composes it ────────────────────────
 {
-	const env = world("two-stage");
+	// Declared axes: both closed sources × {initial A, widened A, changed B, repeated B}.
+	// npm identity is the unchanged lock, not a commit; checkout identity IS the commit.
+	const cells = [FIXTURE_NPM_LOCK, FIXTURE_CHECKOUT_LOCK].map((lock) => {
+		const env = world(`two-stage-${lock.source}`);
+		const log = path.join(env.HOME as string, "argv.log");
+		let acquisitions = 0;
+		const counted = (args: AcquireArgs) => {
+			acquisitions++;
+			return fixtureAcquire({ activate: "recorder", log })(args);
+		};
+		const stages = [COMMIT_A, COMMIT_A, COMMIT_B, COMMIT_B].map((commit, index) => {
+			const rows: Record<string, string> = { pi: "current (v8) (/home/u/.pi)" };
+			if (index > 0) rows.claude = "current (v5) (/home/u/.claude)";
+			const result = drive(env, listing(rows), {
+				acquire: counted,
+				readRuntimeLock: () => lock,
+				resolveCommit: () => commit,
+			});
+			return { code: result.code, acquisitions };
+		});
+		const calls = fs.readFileSync(log, "utf8").trim().split("\n");
+		const { artifactIdentity: identity } = JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as {
+			artifactIdentity: Record<string, string>;
+		};
+		const expectedCounts = lock.source === "npm" ? [1, 1, 1, 1] : [1, 1, 2, 2];
+		const exactIdentity =
+			lock.source === "npm"
+				? identity.name === PACKAGE &&
+					identity.version === FIXTURE_VERSION &&
+					identity.expectedIntegrity === FIXTURE_NPM_LOCK.integrity
+				: identity.repository === FIXTURE_CHECKOUT_LOCK.repository &&
+					identity.commit === COMMIT_B &&
+					identity.packageName === PACKAGE &&
+					identity.packageVersion === FIXTURE_VERSION;
+		return {
+			source: lock.source,
+			stages,
+			calls,
+			identity,
+			passed:
+				stages.every((stage) => stage.code === 0) &&
+				JSON.stringify(stages.map((stage) => stage.acquisitions)) === JSON.stringify(expectedCounts) &&
+				JSON.stringify(calls) === JSON.stringify(["pi", "pi,claude-code", "pi,claude-code", "pi,claude-code"]) &&
+				identity.kind === lock.source &&
+				exactIdentity,
+		};
+	});
+	ok(
+		"[QK:HPB-SEQUENTIAL-TWO-STAGE] both closed sources hand down `{pi}` then the widened `{pi, claude-code}` " +
+			"on every reinstall, never OpenCode. An unchanged npm lock acquires once; checkout acquires again ONLY " +
+			"when A becomes B, and repeated B acquires nothing. Counts are exact at EACH step, not an aggregate lower " +
+			"bound. Installed identity must retain the input kind and its exact version/integrity or commit/completeness. " +
+			"The real writer bytes are HAC-TWO-STAGE-ADD-ONLY; this cell owns runner composition. " +
+			`Fixture identities do not claim registry acceptance (cells=${JSON.stringify(cells)})`,
+		cells.length === 2 && cells.every((cell) => cell.passed),
+	);
+}
+
+// ── 5b. the production default reader composes with the committed lock ─────────
+{
+	// Independent input oracle: read the committed JSON directly, not the runtime reader
+	// whose invocation this cell certifies. All acquisition/activation bytes remain fixture.
+	const committed = JSON.parse(fs.readFileSync(path.join(PLUGIN_DIR, "runtime-lock.json"), "utf8")) as
+		| { source: "npm"; name: string; version: string; integrity: string }
+		| { source: "herdr-checkout"; repository: string };
+	const env = world("default-lock-reader");
 	const log = path.join(env.HOME as string, "argv.log");
 	let acquisitions = 0;
-	const counted = (args: AcquireArgs) => {
-		acquisitions++;
-		return fixtureAcquire({ activate: "recorder", log })(args);
-	};
-	const stage1 = drive(env, listing({ pi: "current (v8) (/home/u/.pi)" }), {
-		acquire: counted,
-		resolveCommit: () => COMMIT_A,
-	});
-	const stage2 = drive(env, listing({ pi: "current (v8) (/home/u/.pi)", claude: "current (v5) (/home/u/.claude)" }), {
-		acquire: counted,
+	const acquire = fixtureAcquire({ activate: "recorder", log });
+	const result = drive(env, listing({ pi: "current (v8) (/home/u/.pi)" }), {
+		readRuntimeLock: undefined,
 		resolveCommit: () => COMMIT_A,
+		acquire: (args: AcquireArgs) => {
+			acquisitions++;
+			return acquire(args);
+		},
 	});
-	const stage3 = drive(env, listing({ pi: "current (v8) (/home/u/.pi)", claude: "current (v5) (/home/u/.claude)" }), {
-		acquire: counted,
-		resolveCommit: () => COMMIT_B,
-	});
-	const calls = fs.readFileSync(log, "utf8").trim().split("\n");
-	const journal = JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as {
-		artifactIdentity: { commit: string };
-	};
+	const journal = fs.existsSync(journalPathOf(env))
+		? (JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as { artifactIdentity: Record<string, string> })
+		: null;
+	const identity = journal?.artifactIdentity;
+	const exactIdentity =
+		identity !== undefined &&
+		identity.kind === committed.source &&
+		(committed.source === "npm"
+			? identity.name === committed.name &&
+				identity.version === committed.version &&
+				identity.expectedIntegrity === committed.integrity
+			: identity.repository === committed.repository &&
+				identity.commit === COMMIT_A &&
+				identity.packageName === PACKAGE &&
+				identity.packageVersion === FIXTURE_VERSION);
 	ok(
-		"[QK:HPB-SEQUENTIAL-TWO-STAGE] the sequence a real operator performs, as the runner composes it: `{pi}` first, " +
-			"then `{pi, claude-code}` after they integrated Claude Code, then a NEW commit of the same package version. " +
-			"The unchanged commit acquires nothing while still reconciling the widened set; the new commit reinstalls. " +
-			"OpenCode is present in every listing and appears in NO activation argv — the bytes those activations write " +
-			"are `check-herdr-activation`'s HAC-TWO-STAGE-ADD-ONLY, which drives the real Pi writers; what this cell owns " +
-			`is what the runner hands down (codes=${stage1.code}/${stage2.code}/${stage3.code} acquisitions=${acquisitions} calls=${JSON.stringify(calls)} commit=${journal.artifactIdentity.commit.slice(0, 8)})`,
-		stage1.code === 0 &&
-			stage2.code === 0 &&
-			stage3.code === 0 &&
-			acquisitions === 2 &&
-			JSON.stringify(calls) === JSON.stringify(["pi", "pi,claude-code", "pi,claude-code"]) &&
-			!calls.some((c) => c.includes("opencode")) &&
-			journal.artifactIdentity.commit === COMMIT_B,
+		"[QK:HPB-DEFAULT-LOCK-READ] without a reader override, runBuild reads this plugin's committed lock " +
+			"from PLUGIN_DIR, not the repository root or a synthetic fixture. The acquired identity retains the " +
+			"independently read source and exact artifact fields; installed activation still runs once for pi. " +
+			`This is composition proof, not registry acquisition (code=${result.code} refusal=${result.refusal} acquisitions=${acquisitions} identity=${JSON.stringify(identity)})`,
+		result.code === 0 &&
+			acquisitions === 1 &&
+			exactIdentity &&
+			fs.existsSync(log) &&
+			fs.readFileSync(log, "utf8") === "pi\n",
 	);
 }
 
 // ── 6a. the authority check happens BEFORE any runtime work ───────────────────
 {
-	const IDENTITY = (commit: string) => ({
-		kind: "herdr-checkout",
-		repository: "junghan0611/entwurf",
-		commit,
-		packageName: PACKAGE,
-		packageVersion: "0.21.0",
-		observedDigest: `sha256-${createHash("sha256").update(commit).digest("hex")}`,
+	const IDENTITY = (seed: string) => ({
+		kind: "npm",
+		name: PACKAGE,
+		version: FIXTURE_VERSION,
+		expectedIntegrity: FIXTURE_NPM_LOCK.integrity,
+		observedDigest: `sha256-${createHash("sha256").update(seed).digest("hex")}`,
 	});
-	/** A host that already has a runtime at commit A and a ledger that says so. */
+	/** A host with the explicit npm fixture installed and a ledger describing it. */
 	const seeded = (tag: string, backends: string[]): NodeJS.ProcessEnv => {
 		const env = world(tag);
 		const log = path.join(env.HOME as string, "argv.log");
@@ -468,12 +550,17 @@ function drive(
 		});
 		const states: Record<string, string> = {};
 		for (const b of backends) states[b] = "active";
+		const artifactIdentity = (
+			JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as {
+				artifactIdentity: Record<string, unknown>;
+			}
+		).artifactIdentity;
 		activation.writeLedger(
 			activation.resolveActivationLayout(env),
 			activation.ledgerBody({
 				phase: "active",
 				runtimeRoot: activeDirOf(env),
-				artifactIdentity: IDENTITY(COMMIT_A),
+				artifactIdentity,
 				roots: activation.resolveComponentRoots(env),
 				states,
 			}),
@@ -518,21 +605,22 @@ function drive(
 	const emptiedDirSeen = treeDigest(oracleRoot) !== oracleBase;
 	const oracleHonest = sameTree && sameLengthEditSeen && restored && modeSeen && emptiedDirSeen;
 
-	// (a) a SOURCE switch: the committed lock would now name npm over a checkout-sourced activation.
+	// (a) a SOURCE switch: the committed lock would name checkout over the active npm runtime.
 	// (a) is asked of the SHARED authority directly: the runner reads its lock from the committed
 	// file, and this gate does not add a seam that would let any caller choose the source.
 	const src = seeded("plan-source", ["pi"]);
 	const srcBefore = snapshot(src);
 	const srcRefusal = refusalOf(() =>
 		runner.certifyActivationPlan(src, {
-			lock: { source: "npm", name: PACKAGE, version: "0.21.0", integrity: "sha512-x" },
+			lock: { source: "herdr-checkout", repository: "junghan0611/entwurf" },
 			checkoutRoot: fixtureCheckoutRoot(),
 			requested: ["pi"],
+			resolveCommit: () => COMMIT_A,
 		}),
 	);
 	const srcUnchanged = unchanged(src, srcBefore);
 
-	// (b) a new commit whose request DROPS a backend the ledger holds.
+	// (b) a changed npm integrity whose request DROPS a backend the ledger holds.
 	const drop = seeded("plan-drop", ["pi", "claude-code"]);
 	const dropBefore = snapshot(drop);
 	let dropAcquired = 0;
@@ -541,6 +629,7 @@ function drive(
 			dropAcquired++;
 			return fixtureAcquire({ activate: "recorder", log: path.join(drop.HOME as string, "argv.log") })(args);
 		},
+		readRuntimeLock: () => ({ ...FIXTURE_NPM_LOCK, integrity: FIXTURE_OTHER_INTEGRITY }),
 		resolveCommit: () => COMMIT_B,
 	});
 
@@ -549,7 +638,17 @@ function drive(
 	const tornLedger = activation.resolveActivationLayout(torn).ledgerPath;
 	fs.writeFileSync(
 		tornLedger,
-		`${JSON.stringify({ ...(JSON.parse(fs.readFileSync(tornLedger, "utf8")) as Record<string, unknown>), artifactIdentity: IDENTITY(COMMIT_B) }, null, 2)}\n`,
+		`${JSON.stringify(
+			{
+				...(JSON.parse(fs.readFileSync(tornLedger, "utf8")) as Record<string, unknown>),
+				artifactIdentity: {
+					...IDENTITY(COMMIT_B),
+					expectedIntegrity: FIXTURE_OTHER_INTEGRITY,
+				},
+			},
+			null,
+			2,
+		)}\n`,
 	);
 	const tornBefore = snapshot(torn);
 	let tornAcquired = 0;
@@ -561,14 +660,13 @@ function drive(
 		resolveCommit: () => COMMIT_A,
 	});
 
-	// (d) the LEGAL case still passes: same source, new commit, request covers the ledger. The
-	// authority is asked on the PRE-install state, which is the only state it is ever asked about.
+	// (d) the LEGAL case still passes: same exact npm source and lock, request covers the ledger.
+	// The authority is asked on the PRE-install state, which is the only state it is ever asked about.
 	const legal = seeded("plan-legal", ["pi"]);
 	const legalPlan = runner.certifyActivationPlan(legal, {
-		lock: { source: "herdr-checkout", repository: "junghan0611/entwurf" },
-		checkoutRoot: fixtureCheckoutRoot(),
+		lock: FIXTURE_NPM_LOCK,
+		checkoutRoot: REPO,
 		requested: ["pi"],
-		resolveCommit: () => COMMIT_B,
 	});
 	const legalDrive = drive(legal, listing({ pi: "current (v8) (/home/u/.pi)" }), {
 		acquire: fixtureAcquire({ activate: "recorder", log: path.join(legal.HOME as string, "argv.log") }),
@@ -577,7 +675,7 @@ function drive(
 
 	ok(
 		"[QK:HPB-PRE-BOOTSTRAP-AUTHORITY] the activation authority is asked BEFORE any runtime work, through the SAME " +
-			"shipped functions the installed verb runs: a source switch, a new commit whose request drops an activated " +
+			"shipped functions the installed verb runs: a source switch, a request that drops an activated " +
 			"backend, and a ledger that already disagrees with the runtime standing there are each refused with the " +
 			"runtime tree, its journal, our cache, the ledger and the activation log ALL byte-identical and the " +
 			"acquisition never called. The first cut bootstrapped first and let the installed verb refuse afterwards, " +
@@ -596,7 +694,7 @@ function drive(
 			tornAcquired === 0 &&
 			unchanged(torn, tornBefore) &&
 			legalDrive.code === 0 &&
-			legalPlan.disposition === "rebind",
+			legalPlan.disposition === "match",
 	);
 }
 
@@ -607,15 +705,19 @@ function drive(
 	const commits = [COMMIT_A, COMMIT_B, COMMIT_B];
 	let call = 0;
 	const moving = () => commits[Math.min(call++, commits.length - 1)] as string;
+	// Candidate source is a closed, retained branch. This test seam does not expose a caller input:
+	// production `runBuild` reads only the committed lock, while the gate drives the branch whose
+	// identity can move between D1 and D2.
 	const drifted = drive(env, listing({ pi: "current (v8) (/home/u/.pi)" }), {
 		acquire: fixtureAcquire({ activate: "recorder", log }),
+		readRuntimeLock: () => FIXTURE_CHECKOUT_LOCK,
 		resolveCommit: moving,
 	});
 	const journal = JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as { artifactIdentity: { commit: string } };
 	const activated = fs.existsSync(log) ? fs.readFileSync(log, "utf8").trim() : "";
 	ok(
 		"[QK:HPB-BOOTSTRAP-IDENTITY-EXACT] the artifact that lands must be EXACTLY the one the authority check admitted: " +
-			"when the source moves between the judgement and the install, the run refuses by name instead of handing the " +
+			"when the candidate source moves between the judgement and the install, the run refuses by name instead of handing the " +
 			"installed activation verb a different artifact than the one this build was cleared to place — the verb would " +
 			"then re-judge, and pass or fail on a question nobody asked. The refusal is honest about what did happen: the " +
 			`runtime was replaced, and NO activation ran (refusal=${drifted.refusal} landed=${journal.artifactIdentity.commit.slice(0, 8)} admitted=${COMMIT_A.slice(0, 8)} activations=${JSON.stringify(activated)})`,
@@ -709,7 +811,7 @@ function drive(
 	ok(
 		"[QK:HPB-PROGRESS-NAMED-SEQUENCE] a build narrates the five steps IN ORDER and names the long one — herdr pipes " +
 			"both of this process's streams into a buffer it DISCARDS on success (`src/cli/plugin.rs:1328-1373` @ c77af189), " +
-			"so an operator who has just answered the install prompt sees nothing at all through a multi-minute `npm pack` " +
+			"so an operator who has just answered the install prompt sees nothing at all through a multi-minute registry fetch " +
 			"and reads it as a hang. The sequence is reported, not logged: each step names the work about to start, the " +
 			"acquisition step says out loud that silence is expected and which source it is reaching for, and a run with " +
 			"nothing to activate takes exactly ONE step and then closes — it must not narrate work it never did. " +
@@ -721,7 +823,7 @@ function drive(
 			full.progress[0].includes("integration status") &&
 			full.progress[1].includes("pi, claude-code") &&
 			longStep.includes("long step") &&
-			longStep.includes(COMMIT_A.slice(0, 8)) &&
+			longStep.includes(`${PACKAGE}@${FIXTURE_VERSION}`) &&
 			full.progress[3].includes("what landed") &&
 			full.progress[4].includes("wiring pi, claude-code") &&
 			full.progress[5].startsWith("done: ") &&

package/scripts/check-install-surface.ts

@@ -260,8 +260,9 @@ const operatorCmds = [...targets].filter(([cmd, ts]) => !isDevGate(cmd) && ts.le
 			.replace(/'(?:[^'\\]|\\.)*'/g, "''");
 	const RUNSH_DRIVE = /(?:\$\{?RUN\}?|run\.sh)\s+(install|setup|remove-user-scope|remove)\b/;
 	// install/setup write the operator's REAL user-scope surfaces under "$HOME"
-	// (user settings.json registration ignores PI_CODING_AGENT_DIR), so sandboxing
-	// the agent dir is not isolation for them; only HOME is. (setup:links died with
+	// (settings.json registration follows PI_CODING_AGENT_DIR when set, but provider
+	// state and the rest stay HOME/XDG-rooted), so sandboxing the agent dir alone is not
+	// isolation for them; HOME is required. (setup:links died with
 	// the target registry — #50 C3.)
 	const HOME_ROOTED = new Set(["install", "setup"]);
 

package/scripts/check-mux-resume-call.ts

@@ -212,6 +212,7 @@ function main(): void {
 
 		const PI_SURFACE = read("pi-extensions/entwurf-control.ts");
 		const MCP_SURFACE = read("mcp/entwurf-bridge/src/index.ts");
+		const PI_CODE = PI_SURFACE.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
 		const V2_RESUME = read("pi-extensions/lib/entwurf-v2-visible-resume.ts");
 		// IMPORTS, not mentions: the module header names the mux side deliberately (that is the
 		// architecture being documented), so an assertion on prose would forbid the explanation
@@ -222,55 +223,43 @@ function main(): void {
 			v2ImportSpecifiers.length > 0 && !v2ImportSpecifiers.some((s) => /mux-/.test(s)),
 		);
 		ok(
-			"both surfaces are the composition root: each imports the mux launcher AND the v2 composition and joins them itself",
-			/mux-resume-call/.test(PI_SURFACE) &&
-				/entwurf-v2-visible-resume/.test(PI_SURFACE) &&
-				/mux-resume-call/.test(MCP_SURFACE) &&
-				/entwurf-v2-visible-resume/.test(MCP_SURFACE),
+			"the bridge is the composition root: it imports the mux launcher AND the v2 composition and joins them itself",
+			/mux-resume-call/.test(MCP_SURFACE) && /entwurf-v2-visible-resume/.test(MCP_SURFACE),
 		);
-
-		// ── the NATIVE PI registration, judged as a registration ─────────────────────
-		// The MCP half is judged on the real runtime tools/list by check-entwurf-bridge-boot.
-		// Native pi has no equivalent boot oracle here, so its registration is read from source —
-		// but narrowly, on the block itself, because "the module is imported" would stay true with
-		// the tool deleted.
-		const PI_BLOCK = (PI_SURFACE.split('name: "entwurf_resume_call",')[1] ?? "").split("\n}")[0];
+		// #125: pi reaches entwurf_resume_call through Pi's built-in MCP — the bridge above IS its
+		// surface. The native pi registration, its target-only TypeBox schema and its description are
+		// retired with it (registration and target-only are held on the runtime tools/list by
+		// BRIDGEBOOT-RESUME-CALL-REGISTERED / -TARGET-ONLY, the description by DESC-CONTRACT-MCP below).
+		// What is left to say about the pi file is that it does not come back as a second root.
 		ok(
-			"[QK:MUXRESUME-PI-SURFACE-REGISTERED] the native pi surface REGISTERS entwurf_resume_call and calls that registration during setup — an imported-but-unregistered verb is invisible to the operator while every import assertion stays green",
-			PI_SURFACE.includes('name: "entwurf_resume_call"') && /registerResumeCallTool\(pi\);/.test(PI_SURFACE),
+			"the pi extension no longer joins the resume halves itself — no second composition root beside the bridge",
+			!/mux-resume-call/.test(PI_CODE) && !/entwurf-v2-visible-resume/.test(PI_CODE),
 		);
+		// The pass-through half the native claim used to carry, now on the one surface that has it:
+		// the handler hands the validated target to the v2 composition UNCHANGED. The schema proves the
+		// input is target-only; this proves the value that reaches the record lookup is that input.
+		const MCP_RESUME_BLOCK = (MCP_SURFACE.split('"entwurf_resume_call",')[1] ?? "").split("\n);")[0];
 		ok(
-			"[QK:MUXRESUME-PI-SURFACE-TARGET-ONLY] the native schema is target-only and the handler passes params.target straight through — a model, task or prompt knob would be a second way to decide what a resumed citizen is, when the record already decided",
-			/Type\.Object\(\{\s*target: Type\.String\(/.test(PI_BLOCK) &&
-				/visibleResume\(params\.target,/.test(PI_BLOCK) &&
-				!/model|task|prompt/.test(PI_BLOCK.split("parameters:")[1]?.split("async execute")[0] ?? ""),
+			"[QK:MUXRESUME-MCP-TARGET-PASSTHROUGH] the bridge handler passes its target straight to visibleResume — a rewritten, defaulted or substituted id would reopen a DIFFERENT citizen than the one the caller named",
+			/async \(\{ target \}\) =>/.test(MCP_RESUME_BLOCK) &&
+				/await visibleResume\(target, makeVisibleResumeDeps\(visibleResumeLaunch\)\)/.test(MCP_RESUME_BLOCK),
 		);
 
-		// ── the description contract, both surfaces ──────────────────────────────────
+		// ── the description contract ────────────────────────────────────────────────
 		// Not prose parity — three claims an operator acts on, plus the host's own cap.
-		const PI_DESC = (PI_BLOCK.split("description: `")[1] ?? "").split("`,")[0];
 		const MCP_DESC = (MCP_SURFACE.split('"entwurf_resume_call",')[1] ?? "").split("{")[0];
 		const statesTheContract = (text: string): boolean =>
 			/dormant/i.test(text) && /no turn/i.test(text) && /observation/i.test(text) && /launch/i.test(text);
 
-		for (const [which, text] of [
-			["native pi", PI_DESC],
-			["MCP bridge", MCP_DESC],
-		] as const) {
-			ok(
-				`${which}: the resume description fits the host's 2048-char tool-description cap`,
-				text.length > 0 && text.length <= 2048,
-			);
-		}
-		// The two claim tokens are written OUT, not interpolated: qualification requires each
-		// `[QK:…]` to appear literally exactly once in its gate source, so a token assembled at
-		// runtime names a claim no manifest can bind to.
 		ok(
-			"[QK:MUXRESUME-DESC-CONTRACT-PI] native pi: the description states the three things a caller acts on — DORMANT targets only, no turn is run, and TWO receipts of which the observation is the one that says the citizen is back",
-			statesTheContract(PI_DESC),
+			"MCP bridge: the resume description fits the host's 2048-char tool-description cap",
+			MCP_DESC.length > 0 && MCP_DESC.length <= 2048,
 		);
+		// The claim token is written OUT, not interpolated: qualification requires each `[QK:…]` to
+		// appear literally exactly once in its gate source, so a token assembled at runtime names a
+		// claim no manifest can bind to.
 		ok(
-			"[QK:MUXRESUME-DESC-CONTRACT-MCP] MCP bridge: the description states the same three things — DORMANT targets only, no turn is run, and TWO receipts whose observation is the fact that matters",
+			"[QK:MUXRESUME-DESC-CONTRACT-MCP] MCP bridge: the description states the three things a caller acts on — DORMANT targets only, no turn is run, and TWO receipts whose observation is the fact that matters",
 			statesTheContract(MCP_DESC),
 		);
 	} finally {

package/scripts/check-pi-bridge-sender.ts

@@ -0,0 +1,130 @@
+/**
+ * check-pi-bridge-sender — the pi-session carrier is backed by a pi RECORD before the bridge uses it (#125).
+ *
+ * Since #125 a pi session reaches every Entwurf verb through the compiled entwurf-bridge (Pi's built-in
+ * MCP spawns it with the born gardenId as an explicit `PI_SESSION_ID`), so the bridge's pi-session
+ * rail is the main road. `resolveAuthoritativeSender` now checks, after the claims reconcile and
+ * before returning the pi branch, that the carrier names an existing, readable pi record — through
+ * the same per-entry targeted reader the sender/self policy already uses.
+ *
+ * WHY A SCRIPTS GATE AND NOT A BESIDE TEST: the subject is the bridge PROCESS answering a real
+ * `tools/call` over stdio (the same shape as check-codex-bridge-identity beside it); a vitest lane
+ * would have to boot that subprocess anyway. The store is a throwaway `ENTWURF_META_SESSIONS_DIR`, the
+ * control-socket dir a throwaway HOME: nothing on the operator host is read or written.
+ *
+ * Cells, in order (node:assert stops at the first failure, so each mutant dies at its own claim):
+ *   RECORD-BACKED       a pi record with NO control socket: identity is kept, replyable:false — the
+ *                       socket is replyability, never admission.
+ *   MISSING-REFUSED     a well-formed carrier with no record refuses loud; no anonymous/other-rail answer.
+ *   BACKEND-REFUSED     a carrier naming a record of ANOTHER backend refuses by name.
+ *   UNREADABLE-CAUSE    a record file that cannot be parsed refuses with ITS cause, not as "absent".
+ */
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+import { upsertMetaSession } from "../pi-extensions/lib/meta-session.ts";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "entwurf-pi-bridge-sender-"));
+const home = path.join(tmp, "home");
+const sessionsDir = path.join(tmp, "meta-sessions");
+fs.mkdirSync(home, { recursive: true });
+
+function born(backend: "pi" | "claude-code", nativeSessionId: string): string {
+	return upsertMetaSession({
+		input: { backend, nativeSessionId, cwd: "/gate/pi-bridge-sender", model: "gate/model" },
+		dir: sessionsDir,
+	}).record.gardenId;
+}
+
+async function selfAs(gardenId: string): Promise<{ text: string; isError: boolean }> {
+	const child = spawn("bash", [path.join(ROOT, "mcp/entwurf-bridge/start.sh")], {
+		cwd: ROOT,
+		env: {
+			PATH: process.env.PATH,
+			HOME: home,
+			PI_CODING_AGENT_DIR: path.join(home, ".pi", "agent"),
+			ENTWURF_META_SESSIONS_DIR: sessionsDir,
+			PI_SESSION_ID: gardenId,
+			PI_AGENT_ID: "gate/pi-bridge-sender",
+		},
+		stdio: ["pipe", "pipe", "pipe"],
+	});
+	let stderr = "";
+	child.stderr.setEncoding("utf8");
+	child.stderr.on("data", (chunk) => {
+		stderr += chunk;
+	});
+	const lines = createInterface({ input: child.stdout });
+	const timer = setTimeout(() => child.kill("SIGKILL"), 10_000);
+	try {
+		const reply = await new Promise<unknown>((resolve, reject) => {
+			lines.on("line", (line) => {
+				const value = JSON.parse(line) as { id?: unknown };
+				if (value.id === 2) resolve(value);
+			});
+			child.once("error", reject);
+			child.once("exit", (code) => reject(new Error(`bridge exited ${code} before replying: ${stderr}`)));
+			const send = (msg: unknown): void => {
+				child.stdin.write(`${JSON.stringify(msg)}\n`);
+			};
+			send({
+				jsonrpc: "2.0",
+				id: 1,
+				method: "initialize",
+				params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "gate", version: "0" } },
+			});
+			send({ jsonrpc: "2.0", method: "notifications/initialized", params: {} });
+			send({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "entwurf_self", arguments: {} } });
+		});
+		const result = (reply as { result?: { content?: Array<{ text?: string }>; isError?: boolean } }).result;
+		assert.ok(result, `tools/call returned no result object (stderr: ${stderr})`);
+		return { text: result.content?.[0]?.text ?? "", isError: result.isError === true };
+	} finally {
+		clearTimeout(timer);
+		lines.close();
+		child.kill("SIGTERM");
+	}
+}
+
+try {
+	const piId = born("pi", "01900000-0000-7000-8000-00000000a001");
+	const self = await selfAs(piId);
+	assert.ok(
+		!self.isError && new RegExp(`sessionId:\\s+${piId}`).test(self.text) && /replyable:\s+false/.test(self.text),
+		`[QK:PI-BRIDGE-SENDER-RECORD-BACKED] a pi record with no control socket keeps its identity and answers replyable:false — the socket is replyability, never admission (got: ${self.text})`,
+	);
+
+	const absentId = "20991231T235959-a0a0a0";
+	const absent = await selfAs(absentId);
+	assert.ok(
+		absent.isError && /no meta-record for garden id "20991231T235959-a0a0a0"/.test(absent.text),
+		`[QK:PI-BRIDGE-SENDER-MISSING-REFUSED] a well-formed PI_SESSION_ID with no record refuses loud, naming the absent record — no anonymous or other-rail answer (got: ${absent.text})`,
+	);
+
+	const claudeId = born("claude-code", "00000000-0000-4000-8000-00000000c001");
+	const foreign = await selfAs(claudeId);
+	assert.ok(
+		foreign.isError && /names a claude-code record, not a pi citizen/.test(foreign.text),
+		`[QK:PI-BRIDGE-SENDER-BACKEND-REFUSED] a PI_SESSION_ID naming another backend's record refuses by name (got: ${foreign.text})`,
+	);
+
+	const brokenId = born("pi", "01900000-0000-7000-8000-00000000a002");
+	fs.writeFileSync(path.join(sessionsDir, `${brokenId}.meta.json`), "{ not json");
+	const broken = await selfAs(brokenId);
+	assert.ok(
+		broken.isError && !/no meta-record for garden id/.test(broken.text) && /not valid JSON/.test(broken.text),
+		`[QK:PI-BRIDGE-SENDER-UNREADABLE-CAUSE] an unreadable pi record refuses with ITS own cause, never flattened into "absent" (got: ${broken.text})`,
+	);
+
+	console.log(
+		"check-pi-bridge-sender: a pi-session carrier is served only when it names a readable pi record; missing, foreign-backend and unreadable records each refuse with their own cause, and socket absence stays replyability",
+	);
+} finally {
+	fs.rmSync(tmp, { recursive: true, force: true });
+}