@junghanacs/entwurf 0.12.8 → 0.12.10

package/scripts/meta-bridge-fresh-cut.ts

@@ -24,7 +24,8 @@
  *   - meta-sessions/  (identity records)  → ARCHIVED  (`<dir>.archive-<ts>`)
  *   - meta-mailbox/   (messages+receipts) → ARCHIVED  (`<dir>.archive-<ts>`)
  *   - meta-senders/, meta-receivers/ markers → CLEARED (disposable process
- *     state; the quiesce gate has already proven every owner pid is gone)
+ *     state; the quiesce gate has already proven every owner pid is gone — or,
+ *     for a refuted marker, that no such owner could ever have existed)
  *   - control sockets (*.sock)            → CLEARED if probed dead (the GC
  *     rule: only a demonstrably dead socket may be unlinked)
  *   - native transcripts, andenken/embedding axes, install ownership state
@@ -50,6 +51,28 @@
  * Only a marker whose named owner demonstrably no longer holds that pid is dead,
  * and only a dead marker/socket is cleared.
  *
+ * ONE class is neither live, uncertain nor dead: a marker whose `ownerPid` cannot
+ * own anything (`<= 1` — init, or a non-pid number). It is REFUTED BY CONSTRUCTION
+ * rather than proven dead: after #53 A no writer in this tree can mint one
+ * (`isPlausibleOwnerPid` at both writers and at the write boundary), so on a current
+ * install it is LEGACY or CORRUPT residue — a pre-fix writer whose parent had been
+ * reparented to init (the retired shell-form Claude hook; the agy imprint, which
+ * asked only `> 0` until this cut), or a foreign/damaged marker, which is the only
+ * way a non-integer pid can appear at all. The one file actually observed was a
+ * shell-form Claude hook reparented to init.
+ *
+ * Reading it as an owner is not merely wrong, it is a trap: init runs for the whole
+ * boot and its start-key does not change while it does, so `classifyMarkerOwner`
+ * answers `live` and THE ACTION THIS REFUSAL PRESCRIBES CANNOT CHANGE THAT — the
+ * operator quiesces every session, exactly as told, and the cut refuses again.
+ * (Deleting the marker removes the claim rather than refuting the verdict, and a
+ * reboot recomputes the key with no contract either way — neither is a remedy this
+ * cut may lean on.) Meanwhile 0.12.8 names this very cut as the one repair for a
+ * pre-v3 store, so the host was stuck until the file was deleted by hand (#53 A,
+ * measured 2026-07-25). Such a marker is therefore clearable residue, swept with the
+ * dead ones but COUNTED AND REPORTED APART from them, because invalidity and death
+ * are different findings.
+ *
  * THE MARKER WALK IS NOT THE WHOLE WORLD. A native-push (agy) citizen is registered
  * with NO marker of any kind and is dispatched straight off its record, so marker
  * absence is its NORMAL deliverable state — a socket+marker scan would call such a host
@@ -69,6 +92,15 @@
  * renames reports exactly what already moved (`archived so far:`) and a re-run
  * finishes the cut with its own stamp.
  * Running on a clean/empty host just opens a fresh generation and says so.
+ *
+ * EXIT CONTRACT (#54) — `FRESH_CUT_EXIT`, defined beside the verb's own name in
+ * meta-session.ts because a runbook and a gate must read the same numbers:
+ * `0` complete · `1` nothing moved · `2` usage · `3` cut transition incomplete ·
+ * `4` cut complete but marker/socket cleanup incomplete. The three failure states
+ * were all hidden behind one `1` before, which is why the documented `fresh-cut && setup` chain stopped
+ * identically on a refusal that changed nothing and on a cut that had already
+ * unblocked the install. Only `0` is success — #54 asked for the states to become
+ * DISTINGUISHABLE, not for a failed sweep to become a pass.
  */
 
 import * as fs from "node:fs";
@@ -82,7 +114,10 @@ import {
 	defaultMetaReceiversDir,
 	defaultMetaSendersDir,
 	defaultMetaSessionsDir,
+	FRESH_CUT_EXIT,
+	isPlausibleOwnerPid,
 	type MetaIdentity,
+	midCutExit,
 	parseMetaIdentity,
 	probePidExistence,
 	processStartKey,
@@ -104,6 +139,20 @@ function usage(code: number): never {
 			"store   = ENTWURF_META_SESSIONS_DIR || <PI_CODING_AGENT_DIR|~/.pi/agent>/meta-sessions",
 			"mailbox = ENTWURF_META_MAILBOX_DIR  || <PI_CODING_AGENT_DIR|~/.pi/agent>/meta-mailbox",
 			"sockets = ENTWURF_DIR               || ~/.pi/entwurf-control",
+			"",
+			"EXIT CONTRACT (#54) — what already moved, not how bad it was:",
+			`  ${FRESH_CUT_EXIT.COMPLETE}  cut complete: generation archived (or none existed), fresh v3 store open,`,
+			"     residue cleared. `&& setup` is correct here.",
+			`  ${FRESH_CUT_EXIT.NO_MOVE}  NOTHING MOVED: a live/unprovable surface, an occupied archive destination,`,
+			"     an unreadable surface, or a first rename that failed. The host is unchanged —",
+			"     fix the named cause and re-run. Do NOT run setup: the store it refused is still there.",
+			`  ${FRESH_CUT_EXIT.USAGE}  usage.`,
+			`  ${FRESH_CUT_EXIT.HALF_CUT}  CUT TRANSITION INCOMPLETE: at least one archive move happened,`,
+			"     but the fresh generation is not confirmed open. Inspect, or re-run to finish under a new stamp.",
+			`  ${FRESH_CUT_EXIT.CLEANUP_INCOMPLETE}  CUT COMPLETE, CLEANUP INCOMPLETE: the generation IS archived and the fresh`,
+			"     generation IS open — install and citizen birth are unblocked, so setup may run —",
+			"     but marker/socket residue survived. Prefer fixing it and re-running BEFORE setup; after new citizen birth,",
+			"     remove the named residue manually instead of archiving the new generation with another cut.",
 		].join("\n"),
 	);
 	process.exit(code);
@@ -216,18 +265,22 @@ function classifySurfaceDir(dir: string): SurfaceDirState {
  * address out from under it. An unreadable marker at REST is disposable residue; an
  * unreadable marker as EVIDENCE OF QUIESCENCE is no evidence at all.
  */
-function inspectMarkers(dir: string, label: string): { violations: QuiesceViolation[]; deadFiles: string[] } {
+function inspectMarkers(
+	dir: string,
+	label: string,
+): { violations: QuiesceViolation[]; deadFiles: string[]; refutedFiles: string[] } {
 	const violations: QuiesceViolation[] = [];
 	const deadFiles: string[] = [];
+	const refutedFiles: string[] = [];
 	const markerFiles: { file: string; shown: string }[] = [];
 	const uncertain = (shown: string, why: string): void => {
 		violations.push({ surface: label, detail: `${shown} — ${why}`, kind: "uncertain" });
 	};
 	const dirState = classifySurfaceDir(dir);
-	if (dirState.state === "absent") return { violations, deadFiles };
+	if (dirState.state === "absent") return { violations, deadFiles, refutedFiles };
 	if (dirState.state !== "directory") {
 		uncertain(dir, `surface could not be inspected (${dirState.detail}): an unreadable surface is not a quiesced one`);
-		return { violations, deadFiles };
+		return { violations, deadFiles, refutedFiles };
 	}
 	// depth 0 = the marker root, depth 1 = a backend subdir. Nothing deeper is part
 	// of any marker layout, so it is inspected by hand rather than swept.
@@ -263,13 +316,28 @@ function inspectMarkers(dir: string, label: string): { violations: QuiesceViolat
 			uncertain(shown, `unreadable marker (${err instanceof Error ? err.message : String(err)}): owner unprovable`);
 			continue;
 		}
-		const ownerPid =
-			typeof raw.ownerPid === "number" && Number.isInteger(raw.ownerPid) && raw.ownerPid > 0 ? raw.ownerPid : null;
-		const ownerStartKey = typeof raw.ownerStartKey === "string" ? raw.ownerStartKey : "";
-		if (ownerPid === null) {
-			uncertain(shown, "no positive-integer `ownerPid`: owner unprovable");
+		// Two different failures, deliberately kept apart. NO numeric `ownerPid` means the
+		// marker never NAMED an owner — unprovable, so it refuses the cut like every other
+		// unreadable marker. A numeric one that cannot own (`<= 1`, non-integer, unsafe)
+		// IS a claim, and it is refuted BY CONSTRUCTION: no writer in this tree can mint it
+		// any more, and on the axis this repo certifies "this session is owned by init" is
+		// false on its face (a container harness running AS pid 1 is a real but UNSUPPORTED
+		// shape — see isPlausibleOwnerPid; it fails closed at the writers). That is a
+		// proof of INVALIDITY — strictly stronger than the proof of death this loop already
+		// acts on — so it is clearable residue, never `live` and never `uncertain`. Without
+		// this row a single reparented-owner marker left quiescence unprovable by the ONE
+		// action the refusal prescribes, and the repair 0.12.8 names could not run until
+		// the file was deleted by hand (#53 A, measured 2026-07-25).
+		if (typeof raw.ownerPid !== "number") {
+			uncertain(shown, "no numeric `ownerPid`: owner unprovable");
 			continue;
 		}
+		if (!isPlausibleOwnerPid(raw.ownerPid)) {
+			refutedFiles.push(file);
+			continue;
+		}
+		const ownerPid = raw.ownerPid;
+		const ownerStartKey = typeof raw.ownerStartKey === "string" ? raw.ownerStartKey : "";
 		if (ownerStartKey === "") {
 			uncertain(shown, "no `ownerStartKey`: a bare pid cannot distinguish the owner from a reused pid");
 			continue;
@@ -294,7 +362,7 @@ function inspectMarkers(dir: string, label: string): { violations: QuiesceViolat
 			deadFiles.push(file);
 		}
 	}
-	return { violations, deadFiles };
+	return { violations, deadFiles, refutedFiles };
 }
 
 /**
@@ -319,7 +387,8 @@ function inspectMarkers(dir: string, label: string): { violations: QuiesceViolat
  * record this walk skips, and the claim is deliberately narrow: NOT "that native session
  * has exited", only "these bytes are not an address authority in the live runtime, so
  * they front no current-generation garden surface". Every path that ADDRESSES a citizen
- * goes through the live schema — `readMetaIdentityByGardenId`, the v2 `resolveTarget`,
+ * goes through the live schema — `readAddressableMetaIdentity` (v2 `resolveTarget` and
+ * the pi resume), `readMetaIdentityByGardenId` (the relay reads),
  * the sender-marker trust — and each THROWS on a record this parser refuses, so nothing
  * can dispatch to it. (`entwurf_peers` still LISTS it as a diagnostic; a facts surface
  * reporting what it could not read is not an address.) A record we CAN read is the
@@ -402,10 +471,39 @@ async function inspectNativePushCitizens(storeDir: string): Promise<QuiesceViola
 	return violations;
 }
 
+/**
+ * Remove the files a completed cut is contracted to clear, and report what it could
+ * not. ENOENT is the ONLY tolerated failure — the file raced away, which is the goal
+ * state. Every other errno is a real refusal to delete (EACCES, EPERM under a
+ * sticky-bit parent, EROFS, an immutable attribute, an LSM denial), and a bare
+ * `catch {}` here would launder all of them into "raced away" while the command's own
+ * output still said `cleared:`. That is the Crash-Don't-Warn shape this repo removes,
+ * not a shortcut it tolerates — the caller decides what to do with the failures,
+ * because by this point the archive has already moved and throwing would cost the
+ * operator the story of what DID happen.
+ */
+function clearFiles(files: string[]): { cleared: number; failures: { file: string; reason: string }[] } {
+	const failures: { file: string; reason: string }[] = [];
+	let cleared = 0;
+	for (const file of files) {
+		try {
+			fs.unlinkSync(file);
+			cleared += 1;
+		} catch (err) {
+			if ((err as { code?: unknown }).code === "ENOENT") continue; // raced away — already gone is the goal state
+			failures.push({ file, reason: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	return { cleared, failures };
+}
+
+/** Surfaces this process has already renamed into an archive — see the rename loop. */
+let archivedSoFar = 0;
+
 async function main(): Promise<number> {
 	const args = process.argv.slice(2);
-	if (args.includes("-h") || args.includes("--help")) usage(0);
-	if (args.length > 0) usage(2);
+	if (args.includes("-h") || args.includes("--help")) usage(FRESH_CUT_EXIT.COMPLETE);
+	if (args.length > 0) usage(FRESH_CUT_EXIT.USAGE);
 
 	const storeDir = defaultMetaSessionsDir();
 	const mailboxDir = defaultMetaMailboxDir();
@@ -487,7 +585,7 @@ async function main(): Promise<number> {
 				"Quiesce those sessions (close them / let them exit), inspect anything listed UNCERTAIN, " +
 				"then re-run the same command. Nothing was moved.",
 		);
-		return 1;
+		return FRESH_CUT_EXIT.NO_MOVE;
 	}
 
 	// ── the cut: plan the moves, preflight the whole plan, then rename ───────
@@ -536,9 +634,15 @@ async function main(): Promise<number> {
 				"taken (a cut in the same second, or leftovers from an interrupted one). Nothing was moved: " +
 				"wait a second and re-run, or move those directories aside first.",
 		);
-		return 1;
+		return FRESH_CUT_EXIT.NO_MOVE;
 	}
 	const archived: string[] = [];
+	// Mirrored to module scope for the ONE reader that cannot see this array: the
+	// top-level rejection handler. Everything from here on can still throw — the
+	// `mkdirSync` that opens the fresh generation, most obviously — and a handler that
+	// answered a flat `1` there would tell a runbook "nothing moved" about a host whose
+	// generation is already in an archive. A single-shot CLI may hold one fact in module
+	// scope when the alternative is an exit status that lies (#54).
 	for (const { src, dest } of plan) {
 		try {
 			fs.renameSync(src, dest);
@@ -563,19 +667,20 @@ async function main(): Promise<number> {
 						"own stamp — or inspect by hand.",
 				);
 			}
-			return 1;
+			// The prose above already distinguished these two; the STATUS did not, and a
+			// runbook reads the status (#54). `midCutExit` is the SSOT so the words and the
+			// number cannot drift apart.
+			return midCutExit(archived.length);
 		}
 		archived.push(dest);
+		archivedSoFar = archived.length;
 	}
-	let cleared = 0;
-	for (const file of [...senders.deadFiles, ...receivers.deadFiles, ...deadSockets]) {
-		try {
-			fs.unlinkSync(file);
-			cleared += 1;
-		} catch {
-			// raced away — already gone is the goal state
-		}
-	}
+	// Both sweeps go through ONE remover so they cannot drift to different meanings of
+	// "could not remove". Counted APART, because a dead marker is an owner we PROVED
+	// left while a refuted one never named an owner that could exist, and folding the
+	// two would dress a proof of invalidity up as a proof of death.
+	const dead = clearFiles([...senders.deadFiles, ...receivers.deadFiles, ...deadSockets]);
+	const refuted = clearFiles([...senders.refutedFiles, ...receivers.refutedFiles]);
 	fs.mkdirSync(storeDir, { recursive: true });
 	fs.mkdirSync(mailboxDir, { recursive: true });
 
@@ -584,13 +689,40 @@ async function main(): Promise<number> {
 	} else {
 		for (const dir of archived) console.log(`archived: ${dir}`);
 	}
-	if (cleared > 0) console.log(`cleared: ${cleared} dead marker/socket file(s) (disposable process state)`);
+	if (dead.cleared > 0) console.log(`cleared: ${dead.cleared} dead marker/socket file(s) (disposable process state)`);
+	if (refuted.cleared > 0) {
+		console.log(
+			`refuted: ${refuted.cleared} legacy/corrupt marker(s) named an owner pid that cannot own a session ` +
+				"(<= 1, or not a pid at all); REFUTED BY CONSTRUCTION, not proven dead, and cleared. The observed " +
+				"case was a hook reparented to init before it read its own parent.",
+		);
+	}
 	console.log(`fresh generation open: ${storeDir} (empty, v3-only)`);
 	console.log(
 		"untouched: native transcripts, andenken/embedding memory axes, install state. " +
 			"The archive is forensic only — no runtime reads it and there is no restore verb.",
 	);
-	return 0;
+
+	// The generation IS cut by now, so a cleanup failure must not throw away that
+	// story — but it must not be swallowed either: this command's own report claims
+	// the residue was "cleared". Say exactly which files survived and why, keep the
+	// success lines above (this is not a half-cut), and exit nonzero so no caller
+	// reads a partial sweep as a clean one.
+	const cleanupFailures = [...dead.failures, ...refuted.failures];
+	if (cleanupFailures.length > 0) {
+		for (const { file, reason } of cleanupFailures) console.error(`FAIL post-cut cleanup: ${file} — ${reason}`);
+		console.error(
+			`FAIL post-cut cleanup: ${cleanupFailures.length} marker/socket file(s) above could NOT be removed. The ` +
+				"generation was archived and the fresh generation is open — this is not a half-cut, and install/citizen " +
+				"birth are no longer blocked by the store. What survived is disposable process state sitting in the new " +
+				"generation's surfaces, and it will refuse the NEXT cut. Fix the cause (permissions, a read-only mount, " +
+				`an immutable attribute) and re-run the same command BEFORE \`setup\`, or remove those files by hand. EXIT ` +
+				`${FRESH_CUT_EXIT.CLEANUP_INCOMPLETE}: the cut is DONE, so \`setup\` may proceed — but once a new citizen is ` +
+				"born, another fresh-cut would archive that new generation too; repair the named residue manually instead.",
+		);
+		return FRESH_CUT_EXIT.CLEANUP_INCOMPLETE;
+	}
+	return FRESH_CUT_EXIT.COMPLETE;
 }
 
 main().then(
@@ -598,6 +730,10 @@ main().then(
 	(err) => {
 		console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
 		console.error("FAIL: fresh-cut did not complete — the message above names the cause; re-run after fixing it.");
-		process.exit(1);
+		// Not a flat 1: the ONE thing a caller must know from a crash is whether the host
+		// still holds its generation. Every refusal that reaches here from before the first
+		// rename really is a no-op (its own message says so); anything after it is a
+		// an incomplete cut transition and must not be mistaken for a no-op (#54).
+		process.exit(midCutExit(archivedSoFar));
 	},
 );

package/scripts/mutants/acp-augment.json

@@ -0,0 +1,30 @@
+{
+	"schemaVersion": 1,
+	"lane": "acp-augment",
+	"mutants": [
+		{
+			"claim": "AUGMENT-BUDGET-FITS",
+			"title": "shrinking the augment cap re-opens the tail-cut that hid AGENTS rules + cwd from ACP siblings",
+			"subject": "pi-extensions/lib/acp/augment.ts",
+			"find": ["const MAX_AUGMENT_BYTES = 50 * 1024;"],
+			"replace": ["const MAX_AUGMENT_BYTES = 20 * 1024;"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:AUGMENT-BUDGET-FITS]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "AUGMENT-TRUNC-MARKER",
+			"title": "silent truncation: dropping the honest marker leaves a cut augment with no trace",
+			"subject": "pi-extensions/lib/acp/augment.ts",
+			"find": [
+				"\tconst marker = `\\n\\n[entwurf: context augment truncated to ${MAX_AUGMENT_BYTES} bytes; read AGENTS.md files directly if more detail is needed.]`;"
+			],
+			"replace": ["\tconst marker = \"\";"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:AUGMENT-TRUNC-MARKER]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		}
+	]
+}

package/scripts/mutants/agy-permission.json

@@ -0,0 +1,144 @@
+{
+	"schemaVersion": 1,
+	"lane": "agy-permission",
+	"mutants": [
+		{
+			"claim": "AGY-EXACT-RULE-SET",
+			"title": "over-grant: adding entwurf_inbox_read to ALLOW_RULES must die at the independent literal oracle",
+			"subject": "scripts/agy-bridge-config.py",
+			"find": [
+				"ALLOW_RULES = tuple(f\"mcp({SERVER_KEY}/{tool})\" for tool in (\"entwurf_v2\", \"entwurf_peers\", \"entwurf_self\"))"
+			],
+			"replace": [
+				"ALLOW_RULES = tuple(",
+				"    f\"mcp({SERVER_KEY}/{tool})\" for tool in (\"entwurf_v2\", \"entwurf_peers\", \"entwurf_self\", \"entwurf_inbox_read\")",
+				")"
+			],
+			"gate": ["bash", "run.sh", "smoke-agy-install-state"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:AGY-EXACT-RULE-SET]",
+			"signatureSource": "scripts/smoke-agy-install-state.sh"
+		},
+		{
+			"claim": "AGY-INSTALL-MALFORMED-PRIOR",
+			"title": "install reverts to a shallow prior-state check (empty provenance map passes all()) and re-captures",
+			"subject": "scripts/agy-bridge-config.py",
+			"find": [
+				"        try:",
+				"            _prior_rules, prior_existed = _parse_permission_state(prior)",
+				"        except _PermissionStateError as exc:",
+				"            _die(4, f\"agy-bridge: prior permission install-state is unusable — {exc}. Refusing to \"",
+				"                    \"overwrite provenance this entwurf cannot read; inspect it by hand.\")",
+				"        for rule in ALLOW_RULES:",
+				"            if rule in prior_existed:",
+				"                rules_existed[rule] = prior_existed[rule]"
+			],
+			"replace": [
+				"        if prior.get(\"schemaVersion\") == 1:",
+				"            legacy_rule = prior.get(\"rule\")",
+				"            if isinstance(legacy_rule, str) and isinstance(prior.get(\"ruleExistedBefore\"), bool):",
+				"                if legacy_rule in ALLOW_RULES:",
+				"                    rules_existed[legacy_rule] = prior[\"ruleExistedBefore\"]",
+				"        else:",
+				"            prior_existed = prior.get(\"rulesExistedBefore\")",
+				"            if isinstance(prior_existed, dict) and all(isinstance(v, bool) for v in prior_existed.values()):",
+				"                for rule in ALLOW_RULES:",
+				"                    if rule in prior_existed:",
+				"                        rules_existed[rule] = prior_existed[rule]"
+			],
+			"gate": ["bash", "run.sh", "smoke-agy-install-state"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:AGY-INSTALL-MALFORMED-PRIOR]",
+			"signatureSource": "scripts/smoke-agy-install-state.sh"
+		},
+		{
+			"claim": "AGY-UNINSTALL-VALIDATE-FIRST",
+			"title": "uninstall validates the state only inside the settings-exists branch (refusal after mutation)",
+			"subject": "scripts/agy-bridge-config.py",
+			"find": [
+				"    ours = _owned_rules(state)",
+				"",
+				"    if os.path.islink(settings_path):",
+				"        _die(3, f\"agy-bridge: refusing to uninstall — {settings_path} became a symlink since install \"",
+				"                f\"(someone else's SSOT now). Resolve by hand.\")",
+				"",
+				"    if os.path.exists(settings_path):",
+				"        data = _load_config(settings_path)"
+			],
+			"replace": [
+				"    if os.path.islink(settings_path):",
+				"        _die(3, f\"agy-bridge: refusing to uninstall — {settings_path} became a symlink since install \"",
+				"                f\"(someone else's SSOT now). Resolve by hand.\")",
+				"",
+				"    ours = []",
+				"    if os.path.exists(settings_path):",
+				"        data = _load_config(settings_path)",
+				"        ours = _owned_rules(state)"
+			],
+			"gate": ["bash", "run.sh", "smoke-agy-install-state"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:AGY-UNINSTALL-VALIDATE-FIRST]",
+			"signatureSource": "scripts/smoke-agy-install-state.sh"
+		},
+		{
+			"claim": "AGY-DOCTOR-OWNERSHIP-AXIS",
+			"title": "the state-doctor rounds a path-correct but unreadable ownership record up to ok",
+			"subject": "scripts/agy-bridge-config.py",
+			"find": [
+				"    try:",
+				"        rules, _existed = _parse_permission_state(state)",
+				"    except _PermissionStateError as exc:",
+				"        sys.stdout.write(f\"corrupt {exc}\\n\")",
+				"        return",
+				"    sys.stdout.write(f\"ok {len(rules)}\\n\")"
+			],
+			"replace": ["    sys.stdout.write(\"ok 0\\n\")"],
+			"gate": ["bash", "run.sh", "smoke-agy-install-state"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:AGY-DOCTOR-OWNERSHIP-AXIS]",
+			"signatureSource": "scripts/smoke-agy-install-state.sh"
+		},
+		{
+			"claim": "AGY-CROSS-LIST-BROAD-FIRST",
+			"title": "broad-most-covering runs only within each list, so a deny-exact shadows an ask-broad host wrongly",
+			"subject": "scripts/agy-bridge-config.py",
+			"find": [
+				"    for rule_set, scope in ((BROAD_RULES, \"broad\"), (ALLOW_RULES, \"exact\")):",
+				"        for list_name in SHADOWING_LISTS:",
+				"            rules = perms.get(list_name)",
+				"            if not isinstance(rules, list):",
+				"                continue",
+				"            for rule in rules:",
+				"                if rule in rule_set:",
+				"                    sys.stdout.write(f\"shadowed-by-{list_name} {scope} {rule}\\n\")",
+				"                    return"
+			],
+			"replace": [
+				"    for list_name in SHADOWING_LISTS:",
+				"        rules = perms.get(list_name)",
+				"        if not isinstance(rules, list):",
+				"            continue",
+				"        for rule_set, scope in ((BROAD_RULES, \"broad\"), (ALLOW_RULES, \"exact\")):",
+				"            for rule in rules:",
+				"                if rule in rule_set:",
+				"                    sys.stdout.write(f\"shadowed-by-{list_name} {scope} {rule}\\n\")",
+				"                    return"
+			],
+			"gate": ["bash", "run.sh", "check-agy-permission-matrix"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:AGY-CROSS-LIST-BROAD-FIRST]",
+			"signatureSource": "scripts/check-agy-permission-matrix.py"
+		},
+		{
+			"claim": "AGY-SCHEMA-VERSIONS-APART",
+			"title": "re-merging the two state schema constants stamps a lying version onto the MCP install-state",
+			"subject": "scripts/agy-bridge-config.py",
+			"find": ["STATE_SCHEMA_VERSION = 1  # MCP install-state (server key + preimage); shape unchanged"],
+			"replace": ["STATE_SCHEMA_VERSION = 2  # re-merged with the permission version (the schema re-merge defect)"],
+			"gate": ["bash", "run.sh", "smoke-agy-install-state"],
+			"timeoutSeconds": 180,
+			"signature": "[QK:AGY-SCHEMA-VERSIONS-APART]",
+			"signatureSource": "scripts/smoke-agy-install-state.sh"
+		}
+	]
+}

package/scripts/mutants/meta-identity.json

@@ -0,0 +1,17 @@
+{
+	"schemaVersion": 1,
+	"lane": "meta-identity",
+	"mutants": [
+		{
+			"claim": "META-FIFO-NONBLOCK",
+			"title": "removing O_NONBLOCK makes a fifo-shaped record block the open — the 7/26 mutation evidence, committed",
+			"subject": "pi-extensions/lib/meta-session.ts",
+			"find": ["\tconst fd = fs.openSync(file, fs.constants.O_RDONLY | O_NOFOLLOW_FLAG | O_NONBLOCK_FLAG);"],
+			"replace": ["\tconst fd = fs.openSync(file, fs.constants.O_RDONLY | O_NOFOLLOW_FLAG);"],
+			"gate": ["bash", "run.sh", "check-meta-identity-consumers"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:META-FIFO-NONBLOCK]",
+			"signatureSource": "scripts/check-meta-identity-consumers.ts"
+		}
+	]
+}

package/scripts/mutants/self-address.json

@@ -0,0 +1,59 @@
+{
+	"schemaVersion": 1,
+	"lane": "self-address",
+	"mutants": [
+		{
+			"claim": "SELFADDR-RAIL-RENDER",
+			"title": "entwurf_self reverts to an empty self-fetch guard + unconditional mailbox render (ordering-not-containment)",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": [
+				"\t\t\t\tif (rail === \"self-fetch\") {",
+				"\t\t\t\t\tconst mailboxPath = path.join(defaultMetaMailboxDir(), sender.sessionId);",
+				"\t\t\t\t\textra.mailboxPath = mailboxPath;",
+				"\t\t\t\t\tlines.push(`mailboxPath: ${mailboxPath}`);",
+				"\t\t\t\t} else if (rail === \"native-push\") {"
+			],
+			"replace": [
+				"\t\t\t\tif (rail === \"self-fetch\") {",
+				"\t\t\t\t}",
+				"\t\t\t\tconst mailboxPath = path.join(defaultMetaMailboxDir(), sender.sessionId);",
+				"\t\t\t\textra.mailboxPath = mailboxPath;",
+				"\t\t\t\tlines.push(`mailboxPath: ${mailboxPath}`);",
+				"\t\t\t\tif (rail === \"native-push\") {"
+			],
+			"gate": ["bash", "run.sh", "check-entwurf-self-address"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:SELFADDR-RAIL-RENDER]",
+			"signatureSource": "scripts/check-entwurf-self-address.ts"
+		},
+		{
+			"claim": "SELFADDR-NO-HARDCODED-REPLYABLE",
+			"title": "buildStrictPiSenderEnvelope hardcodes replyable: true again (env presence read as reachability)",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": ["\t\torigin: \"pi-session\",", "\t\treplyable: self.replyable,", "\t};", "}"],
+			"replace": ["\t\torigin: \"pi-session\",", "\t\treplyable: true,", "\t};", "}"],
+			"gate": ["bash", "run.sh", "check-entwurf-self-address"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:SELFADDR-NO-HARDCODED-REPLYABLE]",
+			"signatureSource": "scripts/check-entwurf-self-address.ts"
+		},
+		{
+			"claim": "SELFADDR-RAIL-FACT-LEAK",
+			"title": "the native-push predicate lets a mailbox fact (watchArmed) buy replyability — behavioral, not text",
+			"subject": "pi-extensions/lib/entwurf-self-address.ts",
+			"find": [
+				"\t\t\t\t\tconst push = nativePushDeliverable({ recordBacked: facts.recordBacked, probeAlive: facts.probeAlive });"
+			],
+			"replace": [
+				"\t\t\t\t\tconst push = nativePushDeliverable({",
+				"\t\t\t\t\t\trecordBacked: facts.recordBacked,",
+				"\t\t\t\t\t\tprobeAlive: facts.probeAlive === true || facts.watchArmed === true,",
+				"\t\t\t\t\t});"
+			],
+			"gate": ["bash", "run.sh", "check-entwurf-self-address"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:SELFADDR-RAIL-FACT-LEAK]",
+			"signatureSource": "scripts/check-entwurf-self-address.ts"
+		}
+	]
+}

package/scripts/mutants/v2-surface.json

@@ -0,0 +1,87 @@
+{
+	"schemaVersion": 1,
+	"lane": "v2-surface",
+	"mutants": [
+		{
+			"claim": "V2SURF-MCP-LOCK-DOMAIN",
+			"title": "MCP long description reverts to the false \"socket paths take a per-target lock\" claim",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": [
+				"\t\t\"(delivered / rejected / lock-retained / delivered-but-lock-dirty). LOCK POLICY (do not \" +",
+				"\t\t\"over-generalize it): the per-target lock is taken for a control-socket-DOMAIN dispatch, which is \" +",
+				"\t\t\"both the live send AND the dormant cell's spawn-bg resume — spawn-bg is a separate relaunch \" +",
+				"\t\t\"transport yet it still runs under that domain's lock. The mailbox and native-push rails are \" +",
+				"\t\t\"lock-free: the mailbox is guarded instead by active-receiver deliverability, and native-push by \" +",
+				"\t\t\"its adapter probe. The decider — not the \" +"
+			],
+			"replace": [
+				"\t\t\"(delivered / rejected / lock-retained / delivered-but-lock-dirty). LOCK POLICY: socket paths \" +",
+				"\t\t\"take a per-target lock; the mailbox path does not. The decider — not the \" +"
+			],
+			"gate": ["bash", "run.sh", "check-entwurf-v2-surface"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:V2SURF-MCP-LOCK-DOMAIN]",
+			"signatureSource": "scripts/check-entwurf-v2-surface.ts"
+		},
+		{
+			"claim": "V2SURF-PI-MODE-SCOPE",
+			"title": "pi-native mode param reverts to \"Delivery mode for a live send\" (false for native-push)",
+			"subject": "pi-extensions/entwurf-control.ts",
+			"find": [
+				"\t\t\t\tdescription:",
+				"\t\t\t\t\t\"Injection style for a CONTROL-SOCKET send only: steer (immediate) or follow_up (after task). \" +",
+				"\t\t\t\t\t\"The mailbox, native-push, and spawn-bg plans carry no mode, so it has no effect on those rails.\","
+			],
+			"replace": [
+				"\t\t\t\tdescription:",
+				"\t\t\t\t\t\"Delivery mode for a live send: steer (immediate, interrupt the current turn) or follow_up \" +",
+				"\t\t\t\t\t\"(queued after the current task finishes running to completion).\","
+			],
+			"gate": ["bash", "run.sh", "check-entwurf-v2-surface"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:V2SURF-PI-MODE-SCOPE]",
+			"signatureSource": "scripts/check-entwurf-v2-surface.ts"
+		},
+		{
+			"claim": "V2SURF-INBOX-SCOPE-HONESTY",
+			"title": "entwurf_inbox_read reverts to the false \"drains your own inbox\" access claim (SCOPE paragraph gone)",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": [
+				"\t\t\"doorbell is only a wake attempt, not a read. An empty inbox mutates nothing. \" +",
+				"\t\t\"SCOPE — read this literally: the garden id is CALLER-SUPPLIED and is NOT verified against \" +",
+				"\t\t\"your own identity (a host with no garden record of its own can call this too). So passing \" +",
+				"\t\t\"another citizen's garden id drains THEIR mail and stamps THEIR receipt, and they will never \" +",
+				"\t\t\"see those messages. Pass only the id from your own doorbell notice or your own meta-record; \" +",
+				"\t\t\"use entwurf_self if you need to confirm which id that is. \" +"
+			],
+			"replace": [
+				"\t\t\"doorbell is only a wake attempt, not a read. An empty inbox mutates nothing. \" +",
+				"\t\t\"This tool drains your own meta-bridge inbox and stamps the read receipt on your meta-record. \" +"
+			],
+			"gate": ["bash", "run.sh", "check-entwurf-v2-surface"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:V2SURF-INBOX-SCOPE-HONESTY]",
+			"signatureSource": "scripts/check-entwurf-v2-surface.ts"
+		},
+		{
+			"claim": "V2SURF-MERGED-REJECT",
+			"title": "MCP long description merges the two owned rejects back under backend-liveness-unsupported",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": [
+				"\t\t\"owned-outcome is ONLY for waking a DORMANT socket-domain citizen (spawn-bg resume, currently \" +",
+				"\t\t\"backend pi); on a live target it is rejected as owned-live-no-autosend. Neither self-fetch nor \" +",
+				"\t\t\"native-push has resume authority, but they reject under DIFFERENT reasons — self-fetch as \" +",
+				"\t\t\"backend-liveness-unsupported, native-push as native-push-no-resume-authority. \" +"
+			],
+			"replace": [
+				"\t\t\"owned-outcome is ONLY for waking a DORMANT socket-domain citizen (spawn-bg resume, currently \" +",
+				"\t\t\"backend pi); on a live target it is rejected as owned-live-no-autosend, and on self-fetch and \" +",
+				"\t\t\"native-push alike it is rejected as backend-liveness-unsupported. \" +"
+			],
+			"gate": ["bash", "run.sh", "check-entwurf-v2-surface"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:V2SURF-MERGED-REJECT]",
+			"signatureSource": "scripts/check-entwurf-v2-surface.ts"
+		}
+	]
+}