@junghanacs/entwurf 0.40.0 → 0.41.0

package/scripts/check-meta-hook-session-switch.ts

@@ -47,8 +47,8 @@
  */
 
 import assert from "node:assert/strict";
-import { spawnSync } from "node:child_process";
-import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -56,10 +56,12 @@ import { resolveMailboxReceiverFacts } from "../pi-extensions/lib/entwurf-delive
 import { listEntwurfFacts } from "../pi-extensions/lib/entwurf-fact-provider.ts";
 import { renderEntwurfPeers } from "../pi-extensions/lib/entwurf-peers-render.ts";
 import type { DispatchDecision } from "../pi-extensions/lib/entwurf-v2-decider.ts";
+import { acquireLock, releaseLock } from "../pi-extensions/lib/entwurf-v2-lock.ts";
 import { makeProductionEntwurfV2Deps } from "../pi-extensions/lib/entwurf-v2-production.ts";
 import { runEntwurfV2 } from "../pi-extensions/lib/entwurf-v2-runner.ts";
 import { renderEntwurfV2Result } from "../pi-extensions/lib/entwurf-v2-surface.ts";
 import {
+	defaultMetaRecordArmLocksDir,
 	listAllMetaIdentitiesDir,
 	type MetaIdentity,
 	makeStoreRecordReader,
@@ -70,6 +72,7 @@ import {
 	upsertMetaSession,
 	writeMetaReceiverMarker,
 } from "../pi-extensions/lib/meta-session.ts";
+import { hookImportClosure, installerCopiedLibFiles, stageMetaHookBundle } from "./lib/meta-hook-bundle.ts";
 import { reclaimOnExit } from "./lib/reclaim-on-exit.ts";
 
 let passed = 0;
@@ -91,17 +94,9 @@ const sessionStartLeaf = manifest.hooks.SessionStart?.[0]?.hooks[0] ?? {};
 
 /** Stage a plugin bundle: entry + lib closure + the launcher, exactly as installed. */
 function makeBundle(root: string): void {
-	mkdirSync(path.join(root, "lib"), { recursive: true });
-	mkdirSync(path.join(root, "scripts"), { recursive: true });
-	copyFileSync(path.join(REPO_DIR, "pi-extensions", "meta-bridge-hook.ts"), path.join(root, "meta-bridge-hook.ts"));
-	copyFileSync(
-		path.join(REPO_DIR, "pi-extensions", "lib", "meta-session.ts"),
-		path.join(root, "lib", "meta-session.ts"),
-	);
-	copyFileSync(path.join(REPO_DIR, "pi-extensions", "lib", "session-id.js"), path.join(root, "lib", "session-id.js"));
-	const launcher = path.join(root, "scripts", "hook-launch.sh");
-	copyFileSync(LAUNCHER, launcher);
-	chmodSync(launcher, 0o755);
+	// Entry + its OWN import closure + the launcher (scripts/lib/meta-hook-bundle.ts): a hand-kept
+	// list here could stay green while the installer missed a file the hook now imports.
+	stageMetaHookBundle(root, path.join(REPO_DIR, "pi-extensions", "meta-bridge-hook.ts"), LAUNCHER);
 }
 
 /** Resolve one manifest element the way Claude does: plain-string substitution, no shell. */
@@ -558,4 +553,226 @@ ok(
 	);
 }
 
+// ── E. the record-arm binding (#147 L2 B1) ────────────────────────────────────
+// An arm-capable event commits a fresh `attachIncarnation` in the record and copies the SAME
+// value into the receiver marker, under the record-arm lock; every other event preserves it. A
+// dead marker is resume evidence only while those two agree, so every path where the marker was
+// NOT rewritten has to leave them disagreeing, and a normal arm must never leave them so.
+{
+	const BIND_NATIVE = "b1b1b1b1-arm-binding-session";
+	const BIND_TRANSCRIPT = path.join(CWD, `${BIND_NATIVE}.jsonl`);
+	writeFileSync(BIND_TRANSCRIPT, "");
+	const drive = (event: string, source = "startup") =>
+		driveHook({ event, nativeSessionId: BIND_NATIVE, source, transcriptPath: BIND_TRANSCRIPT });
+	const pair = (gid: string) => ({
+		record: identityFor(gid).attachIncarnation,
+		marker: readMetaReceiverMarker({ gardenId: gid, receiversDir: ROOTS.receiversDir })?.attachIncarnation ?? null,
+	});
+	const recordBytes = (gid: string) => readFileSync(path.join(ROOTS.sessionsDir, `${gid}.meta.json`), "utf8");
+	const armLocks = defaultMetaRecordArmLocksDir(ROOTS.receiversDir);
+	const envelope = (event: string) =>
+		JSON.stringify({
+			hook_event_name: event,
+			session_id: BIND_NATIVE,
+			transcript_path: BIND_TRANSCRIPT,
+			cwd: CWD,
+			source: "startup",
+		});
+
+	drive("SessionStart");
+	const BIND_GID = gardenIdFor(BIND_NATIVE);
+	const first = pair(BIND_GID);
+	ok(
+		"a first SessionStart (create, then the locked arm) commits a fresh 32-hex binding in the record [QK:MHSS-ARM-RECORD-BOUND]",
+		typeof first.record === "string" && /^[0-9a-f]{32}$/.test(first.record),
+	);
+	ok(
+		"…and the receiver marker that arm wrote carries the SAME value [QK:MHSS-ARM-BINDING-PAIRED]",
+		first.marker === first.record,
+	);
+
+	drive("UserPromptSubmit");
+	const afterUps = pair(BIND_GID);
+	ok(
+		"a UserPromptSubmit backfill PRESERVES the binding — a keystroke is not a new incarnation [QK:MHSS-UPS-PRESERVES-BINDING]",
+		afterUps.record === first.record && afterUps.marker === first.record,
+	);
+
+	drive("SessionStart", "compact");
+	const reminted = pair(BIND_GID);
+	ok(
+		"every arm-capable event mints a NEW binding and the pair still agrees [QK:MHSS-ARM-REMINTS-PAIRED]",
+		reminted.record !== first.record && reminted.marker === reminted.record,
+	);
+
+	// An arm whose owner cannot be proven (no launcher provenance): the record commits a new
+	// binding, the marker is not rewritten — so they disagree, and a later resume refuses.
+	{
+		const direct = spawnSync(process.execPath, [path.join(PLUGIN_ROOT, "meta-bridge-hook.ts")], {
+			encoding: "utf8",
+			input: envelope("SessionStart"),
+			env: hookEnv(),
+		});
+		assert.equal(direct.status, 0, `direct hook drive exited ${direct.status}: ${direct.stderr}`);
+		const unproven = pair(BIND_GID);
+		ok(
+			"an arm with no validated owner commits a new record binding and leaves the marker's old one — never a matching stale pair [QK:MHSS-UNPROVEN-OWNER-UNBINDS]",
+			unproven.record !== null &&
+				unproven.record !== reminted.record &&
+				readMetaReceiverMarker({ gardenId: BIND_GID, receiversDir: ROOTS.receiversDir, verifyOwner: false })
+					?.attachIncarnation === reminted.record,
+		);
+	}
+	drive("SessionStart", "resume"); // back to a matching pair for the lock cells
+
+	// The lock held by someone else: an arm waits its bound and then writes NOTHING (ERROR); a
+	// keystroke skips its backfill (WARN). Held by THIS gate's live pid, so it cannot be reclaimed.
+	{
+		const held = acquireLock(BIND_GID, { dir: armLocks });
+		assert.ok(held.ok, "the gate could not take the record-arm lock it plants");
+		const before = recordBytes(BIND_GID);
+		const markerBefore = pair(BIND_GID).marker;
+		const logBefore = readFileSync(HOOK_LOG, "utf8").length;
+		drive("SessionStart", "resume");
+		const armDelta = readFileSync(HOOK_LOG, "utf8").slice(logBefore);
+		ok(
+			"an arm that cannot take the record-arm lock writes NOTHING and says so as ERROR (attach not committed) [QK:MHSS-ARM-LOCK-BUSY-NO-WRITE]",
+			recordBytes(BIND_GID) === before &&
+				pair(BIND_GID).marker === markerBefore &&
+				/ERROR record-arm lock busy — attach NOT committed, watch not armed/.test(armDelta) &&
+				!/armed watch/.test(armDelta),
+		);
+		const upsBefore = readFileSync(HOOK_LOG, "utf8").length;
+		drive("UserPromptSubmit");
+		ok(
+			"a keystroke that finds the lock busy skips its backfill, writing nothing [QK:MHSS-UPS-LOCK-BUSY-SKIPS]",
+			recordBytes(BIND_GID) === before &&
+				/WARN record-arm lock busy — backfill skipped/.test(readFileSync(HOOK_LOG, "utf8").slice(upsBefore)),
+		);
+		if (held.ok) releaseLock(held.claim, { dir: armLocks });
+	}
+
+	// The lock released inside the bound: the arm waits, then commits a matching pair.
+	{
+		const held = acquireLock(BIND_GID, { dir: armLocks });
+		assert.ok(held.ok, "the gate could not take the record-arm lock it plants");
+		const before = pair(BIND_GID).record;
+		const exe = resolveEl(sessionStartLeaf.command ?? "", PLUGIN_ROOT);
+		const argv = (sessionStartLeaf.args ?? []).map((a) => resolveEl(a, PLUGIN_ROOT));
+		const child = spawn(exe, argv, { env: hookEnv(), stdio: ["pipe", "ignore", "pipe"] });
+		// The close listener is registered at spawn, so a child that exits early is still observed.
+		const closed = new Promise<number | null>((resolve) => child.on("close", resolve));
+		child.stdin.end(envelope("SessionStart"));
+		await new Promise((resolve) => setTimeout(resolve, 300));
+		if (held.ok) releaseLock(held.claim, { dir: armLocks });
+		const code = await closed;
+		const waited = pair(BIND_GID);
+		ok(
+			"an arm that finds the lock held waits within its bound and, once released, commits a NEW matching pair [QK:MHSS-ARM-WAITS-FOR-LOCK]",
+			code === 0 && waited.record !== before && waited.marker === waited.record,
+		);
+	}
+
+	// TWO SUCCESSFUL OVERLAPPING SCHEDULES (Astra D4): the cells above hold the lock in the
+	// gate and run one child at a time; these put two real hook processes in flight at once and
+	// require BOTH to succeed, then the pair to agree. The lock is held by the gate only to make
+	// the overlap certain (both children start while it is held), never as a substitute writer.
+	// SUPPORTING SCHEDULE CELLS, not the lock proof: they carry no mutant, because a kill here
+	// would rest on process timing. The deterministic lock proof is the three busy cells above
+	// (MHSS-ARM-LOCK-BUSY-NO-WRITE, MHSS-UPS-LOCK-BUSY-SKIPS, MHSS-ARM-WAITS-FOR-LOCK). Schedule 2's
+	// order (arm before keystroke) relies on the keystroke's node startup outlasting the arm's
+	// few-ms critical section; it is asserted, never retried or slept into green.
+	const launch = (event: string) => {
+		const exe = resolveEl(sessionStartLeaf.command ?? "", PLUGIN_ROOT);
+		const argv = (sessionStartLeaf.args ?? []).map((a) => resolveEl(a, PLUGIN_ROOT));
+		const child = spawn(exe, argv, { env: hookEnv(), stdio: ["pipe", "ignore", "pipe"] });
+		child.stdin.end(envelope(event));
+		return new Promise<number | null>((resolve) => child.on("close", resolve));
+	};
+	const count = (text: string, re: RegExp) => (text.match(re) ?? []).length;
+
+	// Schedule 1 — arm × arm: both arms are waiting when the lock frees, so they contend.
+	{
+		const held = acquireLock(BIND_GID, { dir: armLocks });
+		assert.ok(held.ok, "the gate could not take the record-arm lock it plants");
+		const before = pair(BIND_GID).record;
+		const logBefore = readFileSync(HOOK_LOG, "utf8").length;
+		const a = launch("SessionStart");
+		const b = launch("CwdChanged");
+		await new Promise((resolve) => setTimeout(resolve, 300));
+		if (held.ok) releaseLock(held.claim, { dir: armLocks });
+		const codes = await Promise.all([a, b]);
+		const delta = readFileSync(HOOK_LOG, "utf8").slice(logBefore);
+		const end = pair(BIND_GID);
+		ok(
+			"two arms in flight at once BOTH commit (two attaches, two markers, no busy) and end as one matching pair [QK:MHSS-OVERLAP-ARM-ARM-PAIRED]",
+			codes.every((c) => c === 0) &&
+				count(delta, new RegExp(`INFO attach record ${BIND_GID}\\.meta\\.json`, "g")) === 2 &&
+				count(delta, new RegExp(`INFO receiver marker ${BIND_GID} `, "g")) === 2 &&
+				!/record-arm lock busy/.test(delta) &&
+				end.record !== before &&
+				end.marker === end.record,
+		);
+	}
+
+	// Schedule 2 — arm + UserPromptSubmit: the arm is waiting on the lock when the keystroke
+	// starts; the arm takes the freed lock first, and the keystroke's backfill commits after it.
+	// Both succeed, the keystroke preserves the arm's binding, and the pair agrees.
+	{
+		const held = acquireLock(BIND_GID, { dir: armLocks });
+		assert.ok(held.ok, "the gate could not take the record-arm lock it plants");
+		const before = pair(BIND_GID).record;
+		const logBefore = readFileSync(HOOK_LOG, "utf8").length;
+		const arm = launch("SessionStart");
+		await new Promise((resolve) => setTimeout(resolve, 300));
+		const keystroke = launch("UserPromptSubmit");
+		if (held.ok) releaseLock(held.claim, { dir: armLocks });
+		const codes = await Promise.all([arm, keystroke]);
+		const delta = readFileSync(HOOK_LOG, "utf8").slice(logBefore);
+		const end = pair(BIND_GID);
+		ok(
+			"an arm and a keystroke in flight at once BOTH commit, the keystroke preserves the arm's new binding, and the pair agrees [QK:MHSS-OVERLAP-ARM-UPS-PAIRED]",
+			codes.every((c) => c === 0) &&
+				count(delta, new RegExp(`INFO attach record ${BIND_GID}\\.meta\\.json \\(event=SessionStart`, "g")) === 1 &&
+				count(delta, new RegExp(`INFO attach record ${BIND_GID}\\.meta\\.json \\(event=UserPromptSubmit`, "g")) === 1 &&
+				delta.search(new RegExp(`INFO attach record ${BIND_GID}\\.meta\\.json \\(event=SessionStart`)) <
+					delta.search(new RegExp(`INFO attach record ${BIND_GID}\\.meta\\.json \\(event=UserPromptSubmit`)) &&
+				!/record-arm lock busy/.test(delta) &&
+				end.record !== before &&
+				end.marker === end.record,
+		);
+	}
+
+	ok(
+		"the record-arm lock lives beside the receivers dir, never in the v2 dispatch lock dir resume holds [QK:MHSS-ARM-LOCK-OWN-DIR]",
+		armLocks === path.join(AGENT_ROOT, "meta-record-arm-locks") &&
+			armLocks !== ROOTS.locksDir &&
+			!/ENTWURF_V2_LOCK_DIR/.test(readFileSync(path.join(REPO_DIR, "pi-extensions", "meta-bridge-hook.ts"), "utf8")),
+	);
+}
+
+// ── F. the installed closure IS the hook's static `from` import closure ───────
+// The installer copies a fixed set of lib files; the hook imports whatever it imports. If those
+// drift, the installed hook cannot load — and a gate that hand-copied its own list would still be
+// green. SOURCE form only: this gate runs in the source-only qualification snapshot, which has no
+// dist. The compiled-form comparison and the staged compiled-hook run live with the dist consumer,
+// check-capability-bundle-reach ([QK:BUNDLE-REACH-COMPILED-HOOK-CLOSURE] /
+// [QK:BUNDLE-REACH-COMPILED-HOOK-RUNS]; the latter was MHSS-COMPILED-CLOSURE-RUNS here).
+{
+	const installer = readFileSync(path.join(REPO_DIR, "scripts", "meta-bridge-install.sh"), "utf8");
+	const copied = installerCopiedLibFiles(installer);
+	// The installer names each mode-switched module `<name>.$LIB_EXT`; `session-id.js` ships as itself.
+	const asInstalled = (closure: string[]) =>
+		closure
+			.map((rel) => path.basename(rel))
+			.map((base) => (base === "session-id.js" ? base : base.replace(/\.(ts|js)$/, ".$LIB_EXT")))
+			.sort();
+	const sourceClosure = hookImportClosure(path.join(REPO_DIR, "pi-extensions", "meta-bridge-hook.ts"));
+	ok(
+		"the installer copies exactly the hook's static double-quoted `from` import closure, in source form [QK:MHSS-BUNDLE-CLOSURE-INSTALLED]",
+		sourceClosure.includes("lib/entwurf-v2-lock.ts") &&
+			JSON.stringify(asInstalled(sourceClosure)) === JSON.stringify(copied),
+	);
+}
+
 console.log(`\ncheck-meta-hook-session-switch: ${passed} assertions passed`);

package/scripts/check-meta-identity-consumers.ts

@@ -76,6 +76,7 @@ const identity = (gardenId: string, nativeSessionId: string): MetaIdentity => ({
 	transcriptPath: null,
 	createdAt: "2026-03-01T12:00:00.000Z",
 	recordUpdatedAt: "2026-03-01T12:30:00.000Z",
+	attachIncarnation: null,
 });
 
 const GID_A = "20260301T120000-aaaaaa";

package/scripts/check-meta-listing.ts

@@ -57,6 +57,7 @@ function rec(gardenId: string, over: Partial<MetaIdentity> = {}): string {
 		transcriptPath: null,
 		createdAt: "2026-06-11T00:00:00.000Z",
 		recordUpdatedAt: "2026-06-11T00:00:00.000Z",
+		attachIncarnation: null,
 		...over,
 	});
 }

package/scripts/check-meta-manifest-schema.py

@@ -109,7 +109,7 @@ if hooks is not None:
                 # the array at runtime and reports the hook as `exit_code: 0,
                 # outcome: success`. So the minimal keyset never bought protection from
                 # that version — it only kept us on a launch form whose topology no host
-                # could guarantee. The real defenses are the `>=2.1.217` floor
+                # could guarantee. The real defenses are the `>=2.1.306` floor
                 # (check-claude-floor-coherence) and hook-launch.sh refusing an empty
                 # argv. The marketplace/plugin manifests below stay minimal: the closed-
                 # schema lesson that produced this gate was about a DECORATIVE key

package/scripts/check-meta-session.ts

@@ -22,6 +22,7 @@ import {
 	defaultMetaMailboxDir,
 	defaultMetaSessionsDir,
 	enqueueMetaMessage,
+	findCertifiedIdentityByNativeSessionId,
 	META_SCHEMA_VERSION_V3,
 	type MetaIdentityMintInput,
 	MetaRecordError,
@@ -32,6 +33,7 @@ import {
 	readMailboxReceiptState,
 	readMetaInbox,
 	serializeMetaIdentity,
+	UpsertActionMismatchError,
 	upsertMetaSession,
 } from "../pi-extensions/lib/meta-session.ts";
 
@@ -155,6 +157,35 @@ check("upsertMetaSession: second call attaches — same file/id, recordUpdatedAt
 	}
 });
 
+check(
+	"upsertMetaSession expectAction refuses BEFORE any write when the decision is not that action (#147 L2 B1)",
+	() => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-session-store-"));
+		try {
+			assert.throws(
+				() => upsertMetaSession({ dir, input: claudeInput(), now: T0, expectAction: "attach" }),
+				(err: unknown) => err instanceof UpsertActionMismatchError && err.actual === "create",
+				"expectAction refuses before any write when the decision differs [QK:META-UPSERT-EXPECT-ACTION]",
+			);
+			assert.deepEqual(fs.readdirSync(dir), []); // nothing published
+			const first = upsertMetaSession({ dir, input: claudeInput(), now: T0, expectAction: "create" });
+			const bytes = fs.readFileSync(first.path, "utf8");
+			assert.throws(
+				() => upsertMetaSession({ dir, input: claudeInput({ cwd: "/raced" }), now: T1, expectAction: "create" }),
+				(err: unknown) => err instanceof UpsertActionMismatchError && err.actual === "attach",
+			);
+			assert.equal(fs.readFileSync(first.path, "utf8"), bytes); // a raced create never became an attach
+			assert.equal(
+				findCertifiedIdentityByNativeSessionId(claudeInput().nativeSessionId, dir)?.gardenId,
+				first.record.gardenId,
+			);
+			assert.equal(fs.readFileSync(first.path, "utf8"), bytes); // the lookup is read-only
+		} finally {
+			fs.rmSync(dir, { recursive: true, force: true });
+		}
+	},
+);
+
 check("upsertMetaSession: creates the store dir if absent; leaves no .tmp residue", () => {
 	const base = fs.mkdtempSync(path.join(os.tmpdir(), "meta-session-store-"));
 	const dir = path.join(base, "nested", "meta-sessions"); // does not exist yet

package/scripts/check-meta-v3-record.ts

@@ -16,11 +16,15 @@
  *     showing the actual rejected version value, and unknown/missing versions
  *     crash,
  *   - strict keyset: a body carrying any retired or unknown field is rejected
- *     as stray, never coerced.
+ *     as stray, never coerced,
+ *   - `attachIncarnation` (#147 L2 B1) is the one key a body may omit (absent reads
+ *     as null), is always emitted, is grammar-checked, and survives every attach
+ *     that does not mint a new one.
  */
 
 import assert from "node:assert/strict";
 import {
+	decideUpsert,
 	FRESH_CUT_COMMAND,
 	type MetaIdentity,
 	MetaRecordError,
@@ -64,6 +68,7 @@ const V3_IDENTITY: MetaIdentity = {
 	transcriptPath: "/synthetic/project/.transcript.jsonl",
 	createdAt: "2026-01-01T00:00:00.000Z",
 	recordUpdatedAt: "2026-01-02T03:04:05.000Z",
+	attachIncarnation: null,
 };
 
 const V3_PI_IDENTITY: MetaIdentity = {
@@ -76,6 +81,7 @@ const V3_PI_IDENTITY: MetaIdentity = {
 	transcriptPath: null,
 	createdAt: "2026-03-01T12:00:00.000Z",
 	recordUpdatedAt: "2026-03-01T12:30:00.000Z",
+	attachIncarnation: null,
 };
 
 const V1_BODY = JSON.stringify({
@@ -191,4 +197,52 @@ throws("parseMetaRecordV3 rejects an unknown backend", () =>
 	parseMetaRecordV3(JSON.stringify({ ...V3_IDENTITY, backend: "gemini" })),
 );
 
+// --- attachIncarnation: the one key a V3 record may omit (#147 L2 B1) ---------
+// One schema, one reader: absent reads as null ("no binding observed"), every serialize emits
+// the key, a present value must be 32 lowercase hex, and only a mint replaces it — every other
+// attach preserves it, and nothing infers one.
+{
+	const BIND = "0123456789abcdef0123456789abcdef";
+	const { attachIncarnation: _omit, ...withoutKey } = V3_IDENTITY;
+	// Evaluated inside the assertion: a parser that REFUSES the absent key throws, and that refusal is
+	// exactly this claim failing, so it must land on this label rather than escape before it.
+	ok(
+		"a V3 body without attachIncarnation reads it as null — not a stray, not a defect [QK:META-V3-INCARNATION-ABSENT-NULL]",
+		(() => {
+			try {
+				return parseMetaRecordV3(JSON.stringify(withoutKey)).attachIncarnation === null;
+			} catch {
+				return false;
+			}
+		})(),
+	);
+	throws("a malformed attachIncarnation (not 32 lowercase hex) is refused [QK:META-V3-INCARNATION-MALFORMED]", () =>
+		parseMetaRecordV3(JSON.stringify({ ...V3_IDENTITY, attachIncarnation: "ABCDEF" })),
+	);
+	throws("a non-string attachIncarnation is refused", () =>
+		parseMetaRecordV3(JSON.stringify({ ...V3_IDENTITY, attachIncarnation: 7 })),
+	);
+	ok(
+		"serialize always emits the key (null included) and a bound value round-trips [QK:META-V3-INCARNATION-ALWAYS-EMITTED]",
+		serializeMetaIdentity(V3_IDENTITY).includes('"attachIncarnation": null') &&
+			parseMetaRecordV3(serializeMetaIdentity({ ...V3_IDENTITY, attachIncarnation: BIND })).attachIncarnation === BIND,
+	);
+	const bound = { ...V3_IDENTITY, attachIncarnation: BIND };
+	const input = {
+		backend: "claude-code" as const,
+		nativeSessionId: V3_IDENTITY.nativeSessionId,
+		cwd: "/synthetic/moved",
+	};
+	const preserved = decideUpsert(bound, input);
+	const reminted = decideUpsert(bound, { ...input, attachIncarnation: "f".repeat(32) });
+	ok(
+		"an attach without a value PRESERVES the binding; a mint replaces it; a create without one is null [QK:META-UPSERT-PRESERVES-INCARNATION]",
+		preserved.action === "attach" &&
+			preserved.record.attachIncarnation === BIND &&
+			preserved.record.cwd === "/synthetic/moved" &&
+			reminted.record.attachIncarnation === "f".repeat(32) &&
+			decideUpsert(null, input).record.attachIncarnation === null,
+	);
+}
+
 console.log(`[check-meta-v3-record] ${passed} assertions ok`);

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

@@ -21,7 +21,11 @@
  *   MUXRESUME-ARGV-HAS-CWD          the `-c` actually reaches tmux, after the append shape
  *   MUXRESUME-ARGV-RUNTIME-AFTER-DASHDASH  the runtime and its flags are exec'd, never parsed as
  *                                   tmux options or run through a shell
- *   MUXRESUME-ARGV-CARRIER-FREE     nothing beyond append + `-c` + runtime + the caller's flags
+ *   MUXRESUME-ARGV-CARRIER-FREE     nothing beyond append + the fixed scrub + `-c` + runtime + flags
+ *   MUXRESUME-ARGV-IDENTITY-SCRUB   the tmux half empties exactly the two pi identity carriers a tmux
+ *                                   server may have inherited — the same scrub fresh-call carries
+ *   MUXRESUME-RUNTIME-TABLE         the runtime is a closed per-backend table: pi → pi, claude-code → claude
+ *   MUXRESUME-HERDR-REFUSED         inside herdr the tmux resume rail refuses by name, opening nothing
  *   MUXRESUME-NO-IDENTITY           this module never learns which citizen it is reopening
  *   MUXRESUME-SURFACE-SEAM          both surfaces hand the launcher IN; neither lets the v2
  *                                   composition import mux
@@ -131,9 +135,16 @@ function main(): void {
 		// whole line would be green only because this fixture has no extensions, and would go red
 		// on the recorded-ACP shape that actually ships.
 		const tmuxPrefix = args.slice(0, args.indexOf("--"));
+		const envAssignments = tmuxPrefix.flatMap((token, at) => (token === "-e" ? [tmuxPrefix[at + 1]] : []));
 		ok(
-			"[QK:MUXRESUME-ARGV-CARRIER-FREE] the TMUX half of the argv is exactly the append shape plus -c — no -n window name, no -e env carrier, no -b; the runtime's own flags live after `--` and are not tmux's business",
-			!tmuxPrefix.includes("-n") && !tmuxPrefix.includes("-e") && !tmuxPrefix.includes("-b"),
+			"[QK:MUXRESUME-ARGV-CARRIER-FREE] the TMUX half of the argv is exactly the append shape plus the fixed scrub and -c — no -n window name, no -b, and every -e only EMPTIES an identity carrier; the runtime's own flags live after `--` and are not tmux's business",
+			!tmuxPrefix.includes("-n") &&
+				!tmuxPrefix.includes("-b") &&
+				envAssignments.every((assignment) => assignment === "PI_SESSION_ID=" || assignment === "PI_AGENT_ID="),
+		);
+		ok(
+			"[QK:MUXRESUME-ARGV-IDENTITY-SCRUB] the TMUX half empties exactly PI_SESSION_ID and PI_AGENT_ID — a tmux server started from a pi shell hands its window a stale identity, and a resumed Claude Code, which never re-exports its own, would present it to its bridge",
+			JSON.stringify(envAssignments) === JSON.stringify(["PI_SESSION_ID=", "PI_AGENT_ID="]),
 		);
 		ok(
 			"a cwd that classification refuses can never be built into argv either — the builder re-checks rather than trusting its caller",
@@ -161,19 +172,31 @@ function main(): void {
 		// ── refusals happen BEFORE any mutation ───────────────────────────────────────
 		// No tmux context at all: a bad cwd must still be the reason, because it is decided first
 		// and nothing may reach tmux while it is wrong.
-		const noTmux = resumeCall({ cwd: path.join(tmp, "gone"), runtimeArgs: [] }, {});
+		const noTmux = resumeCall({ backend: "pi", cwd: path.join(tmp, "gone"), runtimeArgs: [] }, {});
 		ok(
 			"an unusable cwd refuses even outside tmux — the cwd question is settled before placement, so no window can exist by the time it is answered",
 			!noTmux.ok && noTmux.reason === "cwd-missing",
 		);
-		const outsideTmux = resumeCall({ cwd: realDir, runtimeArgs: [] }, { PATH: "/nonexistent" });
+		const outsideTmux = resumeCall({ backend: "pi", cwd: realDir, runtimeArgs: [] }, { PATH: "/nonexistent" });
 		ok(
 			"with a good cwd and no runtime on PATH, the refusal is the runtime — preconditions are proven before placement is even read",
 			!outsideTmux.ok && outsideTmux.reason === "runtime-unresolved",
 		);
 
+		// Inside herdr the rail is refused FIRST and by name: a good cwd, a runtime on PATH and no TMUX
+		// at all would otherwise reach the placement question and answer something about tmux.
+		const insideHerdr = resumeCall(
+			{ backend: "pi", cwd: realDir, runtimeArgs: [] },
+			{ HERDR_ENV: "1", PATH: runtimeDir },
+		);
+		ok(
+			"[QK:MUXRESUME-HERDR-REFUSED] inside herdr (HERDR_ENV=1) the tmux resume rail refuses as herdr-resume-unsupported before anything else — an ambient TMUX would otherwise open the window somewhere the operator is not looking",
+			!insideHerdr.ok && insideHerdr.reason === "herdr-resume-unsupported",
+		);
+
 		// ── every reason is answerable ────────────────────────────────────────────────
 		const reasons: ResumeCallRejectReason[] = [
+			"herdr-resume-unsupported",
 			"no-tmux-context",
 			"anchor-malformed",
 			"anchor-unresolved",
@@ -193,7 +216,10 @@ function main(): void {
 			"every reject reason has a hint a caller can act on — a reason without one is a reason they will guess about",
 			reasons.every((r) => typeof RESUME_CALL_REJECT_HINT[r] === "string" && RESUME_CALL_REJECT_HINT[r].length > 0),
 		);
-		ok("the fixed runtime is pi — only a control-socket backend has a same-id resume", RESUME_CALL_RUNTIME === "pi");
+		ok(
+			"[QK:MUXRESUME-RUNTIME-TABLE] the runtime is a closed per-backend table, pi → pi and claude-code → claude — never a command a caller supplies",
+			JSON.stringify(RESUME_CALL_RUNTIME) === JSON.stringify({ pi: "pi", "claude-code": "claude" }),
+		);
 
 		// ── boundaries, asserted on source ────────────────────────────────────────────
 		const SRC = read("pi-extensions/lib/mux-resume-call.ts");
@@ -241,7 +267,7 @@ function main(): void {
 		const MCP_RESUME_BLOCK = (MCP_SURFACE.split('"entwurf_resume_call",')[1] ?? "").split("\n);")[0];
 		ok(
 			"[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) &&
+			/async \(\{ target \}, extra\) =>/.test(MCP_RESUME_BLOCK) &&
 				/await visibleResume\(target, makeVisibleResumeDeps\(visibleResumeLaunch\)\)/.test(MCP_RESUME_BLOCK),
 		);
 
@@ -249,7 +275,7 @@ function main(): void {
 		// Not prose parity — three claims an operator acts on, plus the host's own cap.
 		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);
+			/dormant/i.test(text) && /submits NO prompt/i.test(text) && /observation/i.test(text) && /launch/i.test(text);
 
 		ok(
 			"MCP bridge: the resume description fits the host's 2048-char tool-description cap",
@@ -259,7 +285,7 @@ function main(): void {
 		// 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 three things a caller acts on — 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 prompt is submitted, and TWO receipts whose observation is the fact that matters",
 			statesTheContract(MCP_DESC),
 		);
 	} finally {

package/scripts/check-peer-facts.ts

@@ -73,6 +73,7 @@ function record(gardenId: string, over: Partial<MetaIdentity> = {}): string {
 		transcriptPath: null,
 		createdAt: "2026-06-11T00:00:00.000Z",
 		recordUpdatedAt: "2026-06-11T00:00:00.000Z",
+		attachIncarnation: null,
 		...over,
 	});
 }

package/scripts/check-pi-durable-contact.ts

@@ -586,7 +586,7 @@ async function birthCell(
 		report.hostPid === host.pid,
 	);
 	ok(
-		`[QK:PDC-TOOLS] the registered extension exposes exactly entwurf_self, entwurf_peers, entwurf_v2, entwurf_inbox_read, entwurf_callback, entwurf_fresh_call, in that order (${report.toolNames.join(", ")})`,
+		`[QK:PDC-TOOLS] the registered extension exposes exactly entwurf_self, entwurf_peers, entwurf_v2, entwurf_inbox_read, entwurf_callback, entwurf_fresh_call, entwurf_resume_call, entwurf_retire_call, in that order (${report.toolNames.join(", ")})`,
 		JSON.stringify(report.toolNames) ===
 			JSON.stringify([
 				"entwurf_self",
@@ -595,6 +595,8 @@ async function birthCell(
 				"entwurf_inbox_read",
 				"entwurf_callback",
 				"entwurf_fresh_call",
+				"entwurf_resume_call",
+				"entwurf_retire_call",
 			]),
 	);
 

package/scripts/check-pi-durable-send.ts

@@ -154,7 +154,7 @@ const NATIVE_CALLS = [
 	{ id: "call_pdm_2", name: "bash", arguments: { command: 'printf %s "$MOCK_NATIVE_MARK"' } },
 	{ id: "call_pdm_3", name: "entwurf_self", arguments: {} },
 ];
-/** The contact's six tool names, typed here (this gate imports no adapter constant). */
+/** The contact's eight tool names, typed here (this gate imports no adapter constant). */
 const CONTACT_TOOLS = [
 	"entwurf_self",
 	"entwurf_peers",
@@ -162,6 +162,8 @@ const CONTACT_TOOLS = [
 	"entwurf_inbox_read",
 	"entwurf_callback",
 	"entwurf_fresh_call",
+	"entwurf_resume_call",
+	"entwurf_retire_call",
 ];
 const IMPORT_OBSERVER = `data:text/javascript,${encodeURIComponent(
 	[
@@ -1729,7 +1731,7 @@ function finalWireNative(ctx: NativeContext): void {
 		(t) => t.function?.name ?? "",
 	);
 	ok(
-		`[QK:PDM-WIRE-TOOLS-OFFERED] the app's first model request offers the module's tool, the native bash and all six contact tools together (offered: ${offered.join(", ")})`,
+		`[QK:PDM-WIRE-TOOLS-OFFERED] the app's first model request offers the module's tool, the native bash and all eight contact tools together (offered: ${offered.join(", ")})`,
 		["mock_native_echo", "bash", ...CONTACT_TOOLS].every((name) => offered.includes(name)),
 	);
 	ok(

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

@@ -59,6 +59,7 @@ const DECLARED = [
 	"entwurf_fresh_call",
 	"entwurf_peers",
 	"entwurf_resume_call",
+	"entwurf_retire_call",
 	"entwurf_self",
 	"entwurf_v2",
 ];