@junghanacs/entwurf 0.12.8 → 0.12.9

package/scripts/check-meta-listing.ts

@@ -16,11 +16,19 @@
  *   - mode "strict" throws on any error; "collect" (default) returns partial,
  *   - errors sorted by filename.
  *
+ * #52 adds the store-WIDE half this listing can afford (it already holds every
+ * record): two records claiming one `nativeSessionId` are not two citizens. NEITHER
+ * is listed — a facts surface may not mint the ownership the certification refuses
+ * to mint — both become errors naming each other, and every unrelated citizen keeps
+ * listing. Before this, `entwurf_peers` reported a store the doctor calls
+ * uncertifiable as clean, which is a wrong FACT, not merely a missing guard.
+ *
  * Pure; entries/readRecord injected, no IO.
  */
 
 import assert from "node:assert/strict";
 import {
+	type ActiveStoreEntry,
 	listAllMetaIdentities,
 	type MetaCitizenBackend,
 	type MetaIdentity,
@@ -61,10 +69,17 @@ function reader(map: Record<string, string>): (filename: string) => string {
 	};
 }
 
+/** Store entries from a fixture map — every name a REGULAR file unless `irregular` says
+ * otherwise. The listing takes kind, not bare names, so rule 1 (a symlinked record is
+ * refused and never followed) is enforceable on this surface too. */
+function entries(map: Record<string, string>, irregular: readonly string[] = []): ActiveStoreEntry[] {
+	return Object.keys(map).map((filename) => ({ filename, regularFile: !irregular.includes(filename) }));
+}
+
 // ── valid records → identities, sorted ──────────────────────────────────────
 {
 	const map = { [`${GID_B}.meta.json`]: rec(GID_B), [`${GID_A}.meta.json`]: rec(GID_A) };
-	const { identities, errors } = listAllMetaIdentities(Object.keys(map), reader(map));
+	const { identities, errors } = listAllMetaIdentities(entries(map), reader(map));
 	ok("2 valid → 2 identities, 0 errors", identities.length === 2 && errors.length === 0);
 	ok("identities sorted by gardenId", identities[0]?.gardenId === GID_A);
 }
@@ -72,7 +87,7 @@ function reader(map: Record<string, string>): (filename: string) => string {
 // ── corrupt record does NOT blind the listing ───────────────────────────────
 {
 	const map = { [`${GID_A}.meta.json`]: rec(GID_A), [`${GID_B}.meta.json`]: "{ broken json" };
-	const { identities, errors } = listAllMetaIdentities(Object.keys(map), reader(map));
+	const { identities, errors } = listAllMetaIdentities(entries(map), reader(map));
 	ok("corrupt 1 → valid still listed (not blinded)", identities.length === 1 && identities[0]?.gardenId === GID_A);
 	ok("corrupt → exactly 1 error", errors.length === 1);
 	ok("error names the corrupt file", errors[0]?.filename === `${GID_B}.meta.json`);
@@ -81,7 +96,7 @@ function reader(map: Record<string, string>): (filename: string) => string {
 // ── body/filename drift → error, excluded ───────────────────────────────────
 {
 	const map = { [`${GID_A}.meta.json`]: rec(GID_B) }; // filename A, body claims B
-	const { identities, errors } = listAllMetaIdentities(Object.keys(map), reader(map));
+	const { identities, errors } = listAllMetaIdentities(entries(map), reader(map));
 	ok("drift → excluded from identities", identities.length === 0);
 	ok("drift → 1 error mentioning drift", errors.length === 1 && /drift/.test(errors[0]?.message ?? ""));
 }
@@ -92,21 +107,27 @@ function reader(map: Record<string, string>): (filename: string) => string {
 		if (f === `${GID_B}.meta.json`) throw new Error("ENOENT mid-scan");
 		return rec(GID_A);
 	};
-	const { identities, errors } = listAllMetaIdentities([`${GID_A}.meta.json`, `${GID_B}.meta.json`], read);
+	const { identities, errors } = listAllMetaIdentities(
+		[
+			{ filename: `${GID_A}.meta.json`, regularFile: true },
+			{ filename: `${GID_B}.meta.json`, regularFile: true },
+		],
+		read,
+	);
 	ok("reader throw → error, valid still listed", identities.length === 1 && errors.length === 1);
 }
 
 // ── non-.meta.json ignored ──────────────────────────────────────────────────
 {
 	const map = { [`${GID_A}.meta.json`]: rec(GID_A), "README.txt": "x", "inbox.signal": "y" };
-	const { identities, errors } = listAllMetaIdentities(Object.keys(map), reader(map));
+	const { identities, errors } = listAllMetaIdentities(entries(map), reader(map));
 	ok("non-.meta.json entries ignored", identities.length === 1 && errors.length === 0);
 }
 
 // ── verbatim-or-nothing: error keyset = {filename, message} ─────────────────
 {
 	const map = { [`${GID_A}.meta.json`]: "{ broken" };
-	const { errors } = listAllMetaIdentities(Object.keys(map), reader(map));
+	const { errors } = listAllMetaIdentities(entries(map), reader(map));
 	const keys = Object.keys(errors[0] ?? {}).sort();
 	assert.deepStrictEqual(keys, ["filename", "message"], `error keyset drift: ${keys.join(",")}`);
 	ok("error verbatim-or-nothing (filename + message only, no identity field)", true);
@@ -117,20 +138,81 @@ function reader(map: Record<string, string>): (filename: string) => string {
 	const map = { [`${GID_A}.meta.json`]: rec(GID_A), [`${GID_B}.meta.json`]: "{ broken" };
 	let threw = false;
 	try {
-		listAllMetaIdentities(Object.keys(map), reader(map), { mode: "strict" });
+		listAllMetaIdentities(entries(map), reader(map), { mode: "strict" });
 	} catch {
 		threw = true;
 	}
 	ok("mode strict → throw if any record unreadable", threw);
-	const { identities } = listAllMetaIdentities(Object.keys(map), reader(map), { mode: "collect" });
+	const { identities } = listAllMetaIdentities(entries(map), reader(map), { mode: "collect" });
 	ok("mode collect (default) → partial, no throw", identities.length === 1);
 }
 
 // ── errors sorted by filename ───────────────────────────────────────────────
 {
 	const map = { [`${GID_B}.meta.json`]: "{ x", [`${GID_A}.meta.json`]: "{ y" };
-	const { errors } = listAllMetaIdentities(Object.keys(map), reader(map));
+	const { errors } = listAllMetaIdentities(entries(map), reader(map));
 	ok("errors sorted by filename", errors[0]?.filename === `${GID_A}.meta.json`);
 }
 
+// ── #52: duplicate nativeSessionId is not two citizens ──────────────────────
+{
+	const shared = "n-shared-conversation";
+	const map = {
+		[`${GID_A}.meta.json`]: rec(GID_A, { nativeSessionId: shared }),
+		[`${GID_B}.meta.json`]: rec(GID_B, { nativeSessionId: shared }),
+	};
+	const { identities, errors } = listAllMetaIdentities(entries(map), reader(map));
+	ok("duplicate nativeSessionId → NEITHER record is listed as a citizen", identities.length === 0);
+	ok("duplicate → one error per rival (both are told)", errors.length === 2);
+	ok(
+		"each error names the OTHER holder, so the pair is debuggable from either side",
+		(errors[0]?.message ?? "").includes(`${GID_B}.meta.json`) &&
+			(errors[1]?.message ?? "").includes(`${GID_A}.meta.json`),
+	);
+	ok(
+		"the duplicate error names the fresh-cut verb (one prescription, as everywhere else)",
+		errors.every((e) => e.message.includes("meta-bridge-fresh-cut")),
+	);
+}
+
+// ── #52: a duplicate must not blind the citizens around it ──────────────────
+{
+	const shared = "n-shared-conversation";
+	const GID_C = "20260611T333333-cccccc";
+	const map = {
+		[`${GID_A}.meta.json`]: rec(GID_A, { nativeSessionId: shared }),
+		[`${GID_B}.meta.json`]: rec(GID_B, { nativeSessionId: shared }),
+		[`${GID_C}.meta.json`]: rec(GID_C),
+	};
+	const { identities, errors } = listAllMetaIdentities(entries(map), reader(map));
+	ok(
+		"an unrelated citizen still lists beside a duplicate pair (0.10 lesson holds)",
+		identities.length === 1 && identities[0]?.gardenId === GID_C,
+	);
+	ok("only the two rivals become errors", errors.length === 2);
+}
+
+// ── #52: strict mode refuses a store with a duplicate ───────────────────────
+{
+	const shared = "n-shared-conversation";
+	const map = {
+		[`${GID_A}.meta.json`]: rec(GID_A, { nativeSessionId: shared }),
+		[`${GID_B}.meta.json`]: rec(GID_B, { nativeSessionId: shared }),
+	};
+	let threw = false;
+	try {
+		listAllMetaIdentities(entries(map), reader(map), { mode: "strict" });
+	} catch {
+		threw = true;
+	}
+	ok("mode strict → a duplicate throws like any other unreadable store", threw);
+}
+
+// ── #52: one holder is not a duplicate (no false positive) ──────────────────
+{
+	const map = { [`${GID_A}.meta.json`]: rec(GID_A), [`${GID_B}.meta.json`]: rec(GID_B) };
+	const { identities, errors } = listAllMetaIdentities(entries(map), reader(map));
+	ok("distinct nativeSessionIds are untouched by the uniqueness pass", identities.length === 2 && errors.length === 0);
+}
+
 console.log(`\n[check-meta-listing] ${passed} assertions ok`);

package/scripts/check-meta-receiver-marker.ts

@@ -107,6 +107,60 @@ ok(
 	readMetaReceiverMarker({ gardenId: ghostGarden, receiversDir: DIR, verifyOwner: false }) !== null,
 );
 
+// ── the owner CLAIM, one layer above liveness (#53 A) ───────────────────────
+// A marker naming pid 1 passes the pid-reuse guard on a running Linux host: init is
+// still the very process the marker named, so its start-key matches. The claim is
+// what is false — init owns no Claude session. Such a marker is legacy or corrupt
+// residue (any pre-fix writer that was reparented to init; a foreign/damaged file);
+// the one observed was a shell-form hook. Honoring it made a dead garden id read as
+// an ACTIVE RECEIVER and, one surface over, left meta-bridge-fresh-cut unable to be
+// unblocked by the action it prescribes (#53 A).
+const initGarden = "20260614T130000-cccccc";
+const initKey = processStartKey(1);
+ok("this host CAN read a start key for pid 1 (the residue cells are not vacuous)", initKey !== "");
+writeFileSync(
+	metaReceiverMarkerPath(initGarden, DIR),
+	`${JSON.stringify({
+		gardenId: initGarden,
+		backend: "claude-code",
+		nativeSessionId: "n-init",
+		ownerPid: 1,
+		ownerStartKey: initKey, // the REAL key: the pid-reuse guard would pass
+		ownerKind: "claude-code-cli",
+		armProvenance: "session-start",
+		updatedAt: "2026-06-10T16:03:10.000Z",
+	})}\n`,
+);
+ok(
+	"an init-owned marker reads as null — pid 1 cannot own a session, however live init is",
+	readMetaReceiverMarker({ gardenId: initGarden, receiversDir: DIR }) === null,
+);
+ok(
+	"the classifier itself still says LIVE for it — the refusal is a CLAIM rule, not a liveness one",
+	classifyMarkerOwner(initKey, { currentStartKey: processStartKey(1), pidExists: probePidExistence(1) }) === "live",
+);
+ok(
+	"verifyOwner:false does NOT reach past plausibility (it opts out of liveness, not of validity)",
+	readMetaReceiverMarker({ gardenId: initGarden, receiversDir: DIR, verifyOwner: false }) === null,
+);
+let initWriteRejected = false;
+try {
+	writeMetaReceiverMarker({
+		gardenId: initGarden,
+		backend: "claude-code",
+		nativeSessionId: "n-init",
+		ownerPid: 1,
+		armProvenance: "session-start",
+		receiversDir: DIR,
+	});
+} catch {
+	initWriteRejected = true;
+}
+ok(
+	"minting an init-owned receiver marker THROWS at the write boundary (no writer can reintroduce it)",
+	initWriteRejected,
+);
+
 // ── armProvenance constraint ────────────────────────────────────────────────
 ok(
 	"arm provenances are exactly the arm-capable events",

package/scripts/check-model-lock.ts

@@ -211,7 +211,7 @@ async function makeHarness(opts: MakeHarnessOpts = {}): Promise<Harness> {
 const NATIVE_A: ModelLike = { provider: "openai-codex", id: "gpt-5.4" };
 const NATIVE_B: ModelLike = { provider: "openai-codex", id: "gpt-5.5" };
 const PSA_SONNET: ModelLike = { provider: "entwurf", id: "claude-sonnet-5" };
-const PSA_OPUS: ModelLike = { provider: "entwurf", id: "claude-opus-4-8" };
+const PSA_OPUS: ModelLike = { provider: "entwurf", id: "claude-opus-5" };
 
 let passed = 0;
 let failed = 0;

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/pi_settings_io.py

@@ -0,0 +1,65 @@
+"""pi_settings_io — the shared serializer for the pi settings.json files this repo WRITES.
+
+Both Python writers touch the SAME file (`<repo>/.pi/settings.json` at project scope,
+`~/.pi/agent/settings.json` at user scope):
+
+  - register-pi-package.py   → packages[]
+  - register-pi-provider.py  → entwurfProvider.mcpServers.entwurf-bridge
+
+A settings file can be tracked and owned by a formatter (this repo's own is: tab
+indented, biome-governed, pinned byte-for-byte by check-install-surface S7b–S7d), so a
+writer that re-serializes it in its own house style turns `install` into a source edit.
+#53 B closed that for the packages writer and left the provider writer open — the same
+file, the same defect, one function call away. The rules therefore live HERE rather than
+in either script, because a rule that has to be remembered at each call site is exactly
+what shipped the bug twice:
+
+  1. NO WRITE WHEN NOTHING CHANGES. The strongest idempotence is an untouched file —
+     same bytes, same mtime. Compare the mutated document to the one that was loaded and
+     skip the write when they are equal; only the caller knows what "changed" means, so
+     each one asks `unchanged` and decides.
+  2. A GENUINE REWRITE KEEPS THE FILE'S OWN INDENT UNIT. Narrower than it sounds: this
+     preserves the indent UNIT, not a formatter's line-collapsing decisions, so a rewrite
+     is NOT guaranteed to come back formatter-clean. Byte identity comes from rule 1.
+
+Ships inside `scripts/` (package.json `files` carries the directory whole, with
+`__pycache__`/`*.pyc` excluded), and both importers add their own directory to sys.path
+so the import holds however they are invoked.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+# The first indented line's leading whitespace is the file's unit. `\S` so a blank or
+# whitespace-only line never answers for the document.
+_INDENT = re.compile(r"\n([ \t]+)\S")
+
+
+def detect_indent(text: str | None) -> str | int:
+    """The file's own indent unit — a tab, or N spaces. Defaults to 2 for a new/one-line
+    file, which is what both writers produced before they knew to ask."""
+    if not text:
+        return 2
+    m = _INDENT.search(text)
+    if not m:
+        return 2
+    unit = m.group(1)
+    return "\t" if unit[0] == "\t" else len(unit)
+
+
+def dumps(data: dict, indent: str | int) -> str:
+    """Serialize with the given unit and exactly one trailing newline."""
+    return json.dumps(data, indent=indent) + "\n"
+
+
+def unchanged(before: dict, after: dict) -> bool:
+    """Would writing `after` change what the file MEANS?
+
+    Value equality, not byte equality, and deliberately so: dict `==` ignores key ORDER,
+    so a document whose keys merely moved is reported unchanged and the operator's own
+    ordering survives. The caller must pass a `before` taken BEFORE any mutation — both
+    writers mutate in place, so they parse the raw text twice rather than aliasing it.
+    """
+    return before == after