@junghanacs/entwurf 0.22.0 → 0.23.0

package/scripts/check-codex-birth-hook.ts

@@ -27,6 +27,17 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync
 import { tmpdir } from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+	appendSessionStartGroup,
+	canonicalJson,
+	certifySplice,
+	declarationDigest,
+	entwurfDeclarationGroup,
+	removeEntwurfDescription,
+	removeSessionStartGroup,
+	selectEntwurfDeclaration,
+	trustReceiptKey,
+} from "../pi-extensions/lib/codex-declaration.js";
 import { listAllMetaIdentitiesDir, type MetaIdentity } from "../pi-extensions/lib/meta-session.ts";
 import { reclaimOnExit } from "./lib/reclaim-on-exit.ts";
 
@@ -123,6 +134,182 @@ ok(
 );
 ok("the handler timeout is 30", handler.timeout === 30);
 
+// ── 2. the declaration leaf: what entwurf owns inside a file it SHARES (#117) ─
+// The installer, the inverse, the doctor and the fresh preflight all decide with this leaf, so
+// its two mechanisms are proven here once rather than four times through their shells. The
+// mechanisms are: a NORMALIZED digest (blind to whatever a neighbour's serializer does) and a
+// SPAN SPLICE (so a neighbour's bytes are copied through rather than rewritten).
+{
+	const fakeLauncher = "/opt/entwurf/codex-birth-launch.sh";
+	const ourGroup = entwurfDeclarationGroup(fakeLauncher);
+	const herdrGroup = {
+		hooks: [{ type: "command", command: "bash '/home/op/.codex/herdr-agent-state.sh' session", timeout: 10 }],
+	};
+
+	ok(
+		"[QK:CODEX-DECL-CANONICAL-KEY-ORDER] the canonical form sorts keys recursively, so two documents that differ only in key order digest identically",
+		canonicalJson({ b: 1, a: [{ y: 2, x: 3 }] }) === canonicalJson({ a: [{ x: 3, y: 2 }], b: 1 }),
+	);
+	ok(
+		"[QK:CODEX-DECL-DIGEST-BINDS-LAUNCHER] the digest is sensitive to the launcher path — the one string the vendor keys its trust receipt to",
+		declarationDigest(ourGroup) !== declarationDigest(entwurfDeclarationGroup(`${fakeLauncher}.bak`)),
+	);
+	ok(
+		"[QK:CODEX-DECL-DIGEST-BINDS-EVENT] the digest covers the EVENT as well as the group, so the same group under another event is another identity",
+		declarationDigest(ourGroup) !== declarationDigest(ourGroup, "SubagentStart"),
+	);
+
+	// SELECTION is by the launcher command, at whatever index that command happens to sit.
+	for (const [label, groups, wantIndex] of [
+		["alone", [ourGroup], 0],
+		["after a neighbour", [herdrGroup, ourGroup], 1],
+		["before a neighbour", [ourGroup, herdrGroup], 0],
+		["between neighbours", [herdrGroup, ourGroup, herdrGroup], 1],
+	] as const) {
+		const picked = selectEntwurfDeclaration({ hooks: { SessionStart: groups } }, fakeLauncher);
+		ok(
+			`[QK:CODEX-DECL-SELECT-BY-COMMAND] entwurf's declaration is selected by its command, ${label} (index ${wantIndex})`,
+			picked.ok && picked.groupIndex === wantIndex && picked.handlerIndex === 0,
+		);
+		ok(
+			`the trust key names that measured position, ${label}`,
+			picked.ok &&
+				trustReceiptKey("/h/hooks.json", picked.groupIndex, picked.handlerIndex) ===
+					`/h/hooks.json:session_start:${wantIndex}:0`,
+		);
+		ok(
+			`every other group is reported FOREIGN and none of ours is, ${label}`,
+			picked.ok && picked.foreign.length === groups.length - 1 && !picked.foreign.some((g) => g.index === wantIndex),
+		);
+	}
+
+	// THE HANDLER KEY SET — and this claim is a DIAGNOSIS contract, not an acceptance one. Say it
+	// plainly, because the QK token predates the narrowing and an unchanged name over a changed
+	// meaning is how a mutant stops testing what its claim says (sol, 2026-09-18). ACCEPTANCE is
+	// owned by the normalized digest: a handler carrying `async` digests differently, so the
+	// preflight refuses it whether or not this predicate exists, and the mutant below cannot make
+	// a drifted declaration green. What ONLY this predicate buys is the NAME — "the extra key is
+	// `async`, and every extra key changes the trust identity" — instead of an anonymous digest
+	// mismatch, and an operator repairs those two with different hands. `async: true` is the case
+	// that earns the name: it would let the turn proceed before the record exists.
+	{
+		const extra = selectEntwurfDeclaration(
+			{ hooks: { SessionStart: [{ hooks: [{ ...ourGroup.hooks[0], async: true }] }] } },
+			fakeLauncher,
+		);
+		ok(
+			"[QK:FRESHCALL-CODEX-HOOK-KEYS] a handler carrying `async` — or any key the installer never writes — is NAMED as a shape drift that quotes the extra key; acceptance is the digest's job either way, and what this claim owns is the diagnosis an operator reads",
+			!extra.ok &&
+				extra.code === "declaration-shape-drifted" &&
+				extra.detail.includes("exactly type+command+timeout") &&
+				extra.detail.includes("async"),
+		);
+	}
+
+	for (const [code, document] of [
+		["declaration-absent", { hooks: { SessionStart: [herdrGroup] } }],
+		["declaration-duplicated", { hooks: { SessionStart: [ourGroup, herdrGroup, ourGroup] } }],
+		["declaration-shape-drifted", { hooks: { SessionStart: [{ matcher: "startup", ...ourGroup }] } }],
+		["declaration-shape-drifted", { hooks: { SessionStart: [{ hooks: [{ ...ourGroup.hooks[0], async: true }] }] } }],
+		["declaration-shape-drifted", { hooks: { SessionStart: [{ hooks: [ourGroup.hooks[0], herdrGroup.hooks[0]] }] } }],
+		["hooks-unreadable", { hooks: { SessionStart: "not an array" } }],
+	] as const) {
+		const picked = selectEntwurfDeclaration(document, fakeLauncher);
+		ok(
+			`[QK:CODEX-DECL-NAMED-REFUSALS] ${code} is returned by name rather than as a silent miss (${JSON.stringify(document).slice(0, 60)}…)`,
+			!picked.ok && picked.code === code,
+		);
+	}
+
+	// THE SPLICE. What is asserted is not "the result parses" but "every byte a neighbour owns is
+	// literally still there", because a re-serialize would also parse. So the fixtures below are
+	// deliberately formatted the way NOTHING in this repo serializes — tabs, inline groups, the
+	// neighbour's keys in the order serde emits them — and the assertion is a literal substring.
+	// A fixture written with `JSON.stringify(_, null, 2)` would let a whole-document rewrite pass
+	// unnoticed, which is the one failure this mechanism exists to prevent.
+	const herdrLine = `\t\t\t{"hooks": [{"command": ${JSON.stringify(herdrGroup.hooks[0].command)}, "timeout": 10, "type": "command"}]}`;
+	const ourLine = `\t\t\t{"hooks": [{"type": "command", "command": "'${fakeLauncher}'", "timeout": 30}]}`;
+	const shared = [
+		"{",
+		'\t"description": "entwurf codex-birth 9.9.9 — prose we authored",',
+		'\t"hooks": {',
+		'\t\t"SessionStart": [',
+		`${ourLine},`,
+		herdrLine,
+		"\t\t]",
+		"\t}",
+		"}",
+	].join("\n");
+	ok(
+		"the shared fixture really does hold the neighbour's bytes verbatim, in formatting nothing here would reproduce",
+		shared.includes(herdrLine) && JSON.stringify(JSON.parse(shared), null, 2) !== shared,
+	);
+	const withoutOurs = removeEntwurfDescription(
+		certifySplice(removeSessionStartGroup(shared, 0), { ...JSON.parse(shared), hooks: { SessionStart: [herdrGroup] } }),
+	);
+	ok(
+		"[QK:CODEX-DECL-SPLICE-KEEPS-FOREIGN-BYTES] removing entwurf's group leaves the neighbour's bytes literally untouched",
+		withoutOurs.includes(herdrLine),
+	);
+	ok(
+		"removing entwurf's group also removes entwurf's own description and nothing else",
+		canonicalJson(JSON.parse(withoutOurs)) === canonicalJson({ hooks: { SessionStart: [herdrGroup] } }),
+	);
+	const foreignOnly = ["{", '\t"hooks": {', '\t\t"SessionStart": [', herdrLine, "\t\t]", "\t}", "}"].join("\n");
+	const rejoined = certifySplice(appendSessionStartGroup(foreignOnly, ourGroup), {
+		hooks: { SessionStart: [herdrGroup, ourGroup] },
+	});
+	ok(
+		"[QK:CODEX-DECL-SPLICE-APPENDS-LAST] appending entwurf's group leaves the neighbour at its own index — and therefore at its own trust receipt — with its bytes unchanged",
+		selectEntwurfDeclaration(JSON.parse(rejoined), fakeLauncher).groupIndex === 1 && rejoined.includes(herdrLine),
+	);
+
+	// THE POST-CONDITION IS THE SAFETY. The span reader is the only new way this unit can damage
+	// a file nobody asked it to touch, so no splice is ever trusted on the reader's word.
+	let refused = "";
+	try {
+		certifySplice(rejoined, { hooks: { SessionStart: [herdrGroup] } });
+	} catch (err) {
+		refused = err instanceof Error ? err.message : String(err);
+	}
+	ok(
+		"[QK:CODEX-DECL-SPLICE-CERTIFIED] a splice whose result is not the value the caller intended is REFUSED, never returned",
+		refused.includes("not the value this edit intended"),
+	);
+	refused = "";
+	try {
+		certifySplice("{not json", { hooks: {} });
+	} catch (err) {
+		refused = err instanceof Error ? err.message : String(err);
+	}
+	ok("a splice that does not parse is refused with its own reason", refused.includes("does not parse"));
+
+	// The span reader must find the SAME structure `JSON.parse` does, across the shapes a hooks
+	// file is actually written in. A disagreement here is the reader silently editing the wrong
+	// range, which is exactly what the post-condition above is guarding.
+	for (const [label, text] of [
+		["compact", JSON.stringify({ hooks: { SessionStart: [ourGroup, herdrGroup] } })],
+		["2-space", JSON.stringify({ hooks: { SessionStart: [ourGroup, herdrGroup] } }, null, 2)],
+		["tab", JSON.stringify({ hooks: { SessionStart: [ourGroup, herdrGroup] } }, null, "\t")],
+		[
+			"strings that contain braces and escaped quotes",
+			JSON.stringify({
+				description: 'a } b ] c \\" d',
+				hooks: { SessionStart: [ourGroup, { hooks: [{ type: "command", command: '] } "x"', timeout: 1 }] }] },
+			}),
+		],
+	] as const) {
+		const trimmed = certifySplice(removeSessionStartGroup(text, 0), {
+			...(JSON.parse(text) as Record<string, unknown>),
+			hooks: { SessionStart: [(JSON.parse(text) as { hooks: { SessionStart: unknown[] } }).hooks.SessionStart[1]] },
+		});
+		ok(
+			`[QK:CODEX-DECL-SPAN-READER-EXACT] the span reader agrees with JSON.parse on ${label} formatting`,
+			JSON.parse(trimmed) !== null,
+		);
+	}
+}
+
 // ── 3. FIRE the installed launcher, the way codex fires it ──────────────────
 const MEASURED = {
 	session_id: "01a08147-fbad-78d2-b266-e058f322125e",

package/scripts/check-entwurf-control-rpc.ts

@@ -16,6 +16,11 @@
  *      `sendRpcCommand` reject `connection closed before response` (the 2026-05-18
  *      receiver-stuck backstop the settled-guard preserves).
  *   5. get_info runtime helper parses/formats cwd/model/idle once for every caller.
+ *   7. accepted-connection disconnect policy — a REAL peer that hangs up mid-exchange must not
+ *      reach this process as an uncaught exception (the 2026-09-14 C4 incident: a resident pi died
+ *      writing a late response to a sender that had already timed out), must not be diagnosed, and
+ *      an error that is NOT a disconnect must be diagnosed exactly once without rethrowing.
+ *   8. ordering — the surface installs that policy before setEncoding and before the data handler.
  *
  * No model / auth / pi process — only `net.Server` on a tmp socket, so it rides `pnpm run check:full`.
  */
@@ -27,6 +32,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
+	attachAcceptedSocketDisconnectPolicy,
 	fetchControlSocketRuntimeInfo,
 	formatRuntimeModel,
 	formatSenderInfoBlock,
@@ -217,6 +223,138 @@ async function main(): Promise<void> {
 		ok("6: undefined origin/replyable render nothing", !formatSenderInfoBlock(base).includes("origin"));
 	}
 
+	// ── 7. accepted-connection disconnect policy (the server half of the wire) ──
+	// `[측정 2026-09-14]` a resident pi was killed by a late response written to a socket whose
+	// peer had already timed out and hung up. The EPIPE arrived asynchronously as an `error`
+	// event, and an `error` event with no listener is an uncaught exception. These cells drive a
+	// REAL unix socket to a real peer disconnect — no fake control server, no synthetic stand-in
+	// for the crash itself.
+	{
+		const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rpc-disconnect-"));
+		const socketPath = path.join(dir, "s.sock");
+		const diagnostics: string[] = [];
+		const accepted: net.Socket[] = [];
+		const server = net.createServer((socket) => {
+			// Exactly what the surface does, and the ONLY error listener on this connection: if the
+			// policy stops absorbing, nothing else here is catching it.
+			attachAcceptedSocketDisconnectPolicy(socket, (line) => diagnostics.push(line));
+			accepted.push(socket);
+		});
+		await new Promise<void>((resolve) => server.listen(socketPath, resolve));
+
+		// Record instead of dying, so the crash becomes an assertion we can attribute rather than
+		// a stack trace that kills the gate run itself.
+		const uncaught: Error[] = [];
+		const onUncaught = (err: Error) => uncaught.push(err);
+		process.on("uncaughtException", onUncaught);
+		// Every socket this cell opens, torn down in `finally` — `server.close()` only calls back
+		// once the LAST connection is gone, so a client left open on a failing assertion would turn
+		// a red gate into a hang (which is not a kill: a mutant must fail bounded, with its QK).
+		const opened: net.Socket[] = [];
+		try {
+			const client = net.createConnection(socketPath);
+			opened.push(client);
+			await new Promise<void>((resolve, reject) => {
+				client.once("connect", resolve);
+				client.once("error", reject);
+			});
+			// The sender gives up and hangs up — the C4 shape exactly.
+			client.on("error", () => {});
+			client.destroy();
+
+			// The receiver answers LATE, into a peer that is gone. Bounded: writes until the stream
+			// records an error, never longer.
+			for (let i = 0; i < 200 && accepted[0] !== undefined && accepted[0].errored === null; i++) {
+				try {
+					accepted[0].write(`${"x".repeat(64 * 1024)}\n`);
+				} catch {
+					// A synchronous ERR_STREAM_DESTROYED is the OTHER half — writeResponse's own
+					// try/catch owns it. This loop is hunting the asynchronous one.
+				}
+				await new Promise<void>((resolve) => setTimeout(resolve, 10));
+			}
+
+			// Fixture integrity FIRST: if no peer-disconnect error ever landed, the two cells below
+			// would be vacuously green no matter what the policy did.
+			const errored = accepted[0]?.errored as NodeJS.ErrnoException | null | undefined;
+			ok(
+				"7: fixture — a real peer disconnect produced an async EPIPE/ECONNRESET on the accepted socket",
+				errored != null && (errored.code === "EPIPE" || errored.code === "ECONNRESET"),
+			);
+			ok(
+				"7: [QK:CONTROL-SOCKET-NO-UNCAUGHT] a vanished peer never reaches the process as an uncaught exception " +
+					`(would have killed this resident session) — uncaught=${JSON.stringify(uncaught.map((e) => String(e)))}`,
+				uncaught.length === 0,
+			);
+			ok(
+				"7: [QK:CONTROL-SOCKET-ABSORBS-PEER-DISCONNECT] a vanished peer is absorbed silently, never diagnosed " +
+					`(it describes the client, not our state) — diagnostics=${JSON.stringify(diagnostics)}`,
+				diagnostics.length === 0,
+			);
+
+			// Unexpected code on a REAL accepted socket: diagnosed exactly once, with code AND
+			// message, and the emit must not throw back out of the event callback.
+			const client2 = net.createConnection(socketPath);
+			opened.push(client2);
+			await new Promise<void>((resolve, reject) => {
+				client2.once("connect", resolve);
+				client2.once("error", reject);
+			});
+			client2.on("error", () => {});
+			// The SECOND accepted connection — live, never disconnected, so the diagnosis path is
+			// exercised on a socket in ordinary service rather than on the already-errored one.
+			for (let i = 0; i < 200 && accepted[1] === undefined; i++) {
+				await new Promise<void>((resolve) => setTimeout(resolve, 10));
+			}
+			const live = accepted[1];
+			ok("7: fixture — the second connection was accepted and carries the policy", live !== undefined);
+			const unexpected: NodeJS.ErrnoException = Object.assign(new Error("no space left on device"), {
+				code: "ENOSPC",
+			});
+			const before = diagnostics.length;
+			let threw = false;
+			try {
+				live?.emit("error", unexpected);
+			} catch {
+				threw = true;
+			}
+			const emitted = diagnostics.slice(before);
+			ok(
+				"7: [QK:CONTROL-SOCKET-DIAGNOSES-UNEXPECTED] a non-disconnect error diagnoses EXACTLY once with code and " +
+					`message, and never rethrows from the event callback — threw=${threw} emitted=${JSON.stringify(emitted)}`,
+				threw === false &&
+					emitted.length === 1 &&
+					emitted[0]!.includes("ENOSPC") &&
+					emitted[0]!.includes("no space left on device"),
+			);
+		} finally {
+			process.off("uncaughtException", onUncaught);
+			for (const socket of [...opened, ...accepted]) socket.destroy();
+			await new Promise<void>((resolve) => server.close(() => resolve()));
+			await fs.rm(dir, { recursive: true, force: true });
+		}
+	}
+
+	// ── 8. the surface installs the policy FIRST on every accepted connection ───
+	// Ordering is the contract, not merely presence: a listener attached after setEncoding or
+	// after the data handler leaves a window in which the very first write can still kill us.
+	{
+		const src = await fs.readFile(CONTROL_SRC, "utf8");
+		const accept = src.slice(src.indexOf("const server = net.createServer((socket) => {"));
+		const attachAt = accept.indexOf("attachAcceptedSocketDisconnectPolicy(socket)");
+		const encodingAt = accept.indexOf('socket.setEncoding("utf8")');
+		const dataAt = accept.indexOf('socket.on("data"');
+		ok(
+			"8: [QK:CONTROL-SOCKET-POLICY-FIRST] createServer attaches the disconnect policy before setEncoding and " +
+				`before the data handler — attach=${attachAt} setEncoding=${encodingAt} data=${dataAt}`,
+			attachAt !== -1 && encodingAt !== -1 && dataAt !== -1 && attachAt < encodingAt && attachAt < dataAt,
+		);
+		ok(
+			"8: the surface consumes the shared policy and defines no second error listener of its own",
+			/from "\.\/lib\/entwurf-control-rpc\.js"/.test(src) && !/socket\.on\("error"/.test(src),
+		);
+	}
+
 	console.log(`\ncheck-entwurf-control-rpc: ${passed} checks passed`);
 }
 

package/scripts/check-entwurf-fact-provider.ts

@@ -30,6 +30,7 @@
 import assert from "node:assert/strict";
 import * as path from "node:path";
 import { type EntwurfFactsDeps, listEntwurfFacts } from "../pi-extensions/lib/entwurf-fact-provider.ts";
+import { UNOBSERVED_PLACEMENT } from "../pi-extensions/lib/herdr-placement.ts";
 import { type MetaCitizenBackend, serializeMetaIdentity } from "../pi-extensions/lib/meta-session.ts";
 import { SOCKET_SUFFIX, type SocketDirEntry } from "../pi-extensions/lib/socket-discovery.ts";
 import type { SocketLiveness } from "../pi-extensions/lib/socket-probe.ts";
@@ -83,6 +84,7 @@ function deps(
 		observe: (identity) => ({
 			receiver: identity.backend === "claude-code" ? "inactive" : "n/a",
 			transcript: identity.gardenId === GID_CLAUDE ? "absent" : "exists",
+			placement: UNOBSERVED_PLACEMENT,
 		}),
 		// Kind-carrying entries, like the real bindings: the listing must be able to refuse a
 		// symlinked record without following it. `irregularMeta` names the ones that are not
@@ -186,7 +188,7 @@ async function main(): Promise<void> {
 		const all = deps(meta, {});
 		all.observe = (identity) => {
 			allObserved.push(identity.gardenId);
-			return { receiver: "active", transcript: "exists" };
+			return { receiver: "active", transcript: "exists", placement: UNOBSERVED_PLACEMENT };
 		};
 		await listEntwurfFacts(all);
 		ok("Q112: generic provider without a presentation limit observes all 40 citizens", allObserved.length === 40);
@@ -196,7 +198,7 @@ async function main(): Promise<void> {
 		d.observationLimit = 32;
 		d.observe = (identity) => {
 			observed.push(identity.gardenId);
-			return { receiver: "active", transcript: "exists" };
+			return { receiver: "active", transcript: "exists", placement: UNOBSERVED_PLACEMENT };
 		};
 		const r = await listEntwurfFacts(d);
 		ok("Q112: full machine payload retains all 40 certified citizens", r.facts.peers.length === 40);

package/scripts/check-entwurf-facts.ts

@@ -36,6 +36,7 @@ import {
 	isLivenessSupported,
 	LIVENESS_DOMAIN_BACKENDS,
 } from "../pi-extensions/lib/entwurf-v2-contract.ts";
+import { UNOBSERVED_PLACEMENT } from "../pi-extensions/lib/herdr-placement.ts";
 import {
 	META_CITIZEN_BACKENDS,
 	type MetaCitizenBackend,
@@ -138,7 +139,7 @@ for (const backend of META_CITIZEN_BACKENDS) {
 	ok("passthrough recordUpdatedAt", fact.recordUpdatedAt === id.recordUpdatedAt);
 }
 
-// ── facts-only keyset: identity facts + liveness + the two observed axes, and
+// ── facts-only keyset: identity facts + liveness + the three observed axes, and
 // still NO verb-routing / no transcript PATH ────────────────────────────────
 {
 	const fact = resolvePeerFact(identity("pi"), "alive");
@@ -154,20 +155,25 @@ for (const backend of META_CITIZEN_BACKENDS) {
 		"recordUpdatedAt",
 		"receiver",
 		"transcript",
+		"placement",
 	].sort();
 	assert.deepStrictEqual(keys, expected, `PeerFact keyset drift: got ${keys.join(",")}`);
-	ok("facts-only keyset exact (identity facts + liveness + observed receiver/transcript)", true);
+	ok("facts-only keyset exact (identity facts + liveness + observed receiver/transcript/placement)", true);
 
 	// #101: an unmeasured row says so. `unobserved` is the default for a caller that
 	// injected no observer — never `none`/`absent`, which would be a fabricated fact.
 	ok(
-		"an observer-less composition reports both axes as unobserved (never a default fact)",
-		fact.receiver === "unobserved" && fact.transcript === "unobserved",
+		"an observer-less composition reports all three axes as unobserved (never a default fact)",
+		fact.receiver === "unobserved" && fact.transcript === "unobserved" && fact.placement.kind === "unobserved",
 	);
-	const observed = resolvePeerFact(identity("claude-code"), null, { receiver: "inactive", transcript: "absent" });
+	const observed = resolvePeerFact(identity("claude-code"), null, {
+		receiver: "inactive",
+		transcript: "absent",
+		placement: UNOBSERVED_PLACEMENT,
+	});
 	ok(
 		"an injected observation rides onto the fact verbatim",
-		observed.receiver === "inactive" && observed.transcript === "absent",
+		observed.receiver === "inactive" && observed.transcript === "absent" && observed.placement.kind === "unobserved",
 	);
 
 	const FORBIDDEN = [

package/scripts/check-entwurf-peers-surface.ts

@@ -33,6 +33,7 @@ import { type EntwurfFactsResult, recordLessSocketMessage } from "../pi-extensio
 import type { PeerFact } from "../pi-extensions/lib/entwurf-facts.ts";
 import { ENTWURF_PEERS_RENDER_LIMIT, renderEntwurfPeers } from "../pi-extensions/lib/entwurf-peers-render.ts";
 import type { FactLiveness } from "../pi-extensions/lib/entwurf-v2-contract.ts";
+import { UNOBSERVED_PLACEMENT } from "../pi-extensions/lib/herdr-placement.ts";
 import type { MetaCitizenBackend } from "../pi-extensions/lib/meta-session.ts";
 import type { SocketLiveness } from "../pi-extensions/lib/socket-probe.ts";
 
@@ -51,7 +52,7 @@ function peer(
 	gardenId: string,
 	backend: MetaCitizenBackend,
 	liveness: FactLiveness,
-	observed: Partial<Pick<PeerFact, "receiver" | "transcript">> = {},
+	observed: Partial<Pick<PeerFact, "receiver" | "transcript" | "placement">> = {},
 ): PeerFact {
 	return {
 		gardenId,
@@ -64,6 +65,7 @@ function peer(
 		liveness,
 		receiver: observed.receiver ?? "n/a",
 		transcript: observed.transcript ?? "exists",
+		placement: observed.placement ?? UNOBSERVED_PLACEMENT,
 	};
 }
 

package/scripts/check-entwurf-self-address.ts

@@ -44,6 +44,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
 	computeSelfAddressability,
+	decideUncitizenedNotice,
 	type SelfAddressabilityFacts,
 	type SocketState,
 } from "../pi-extensions/lib/entwurf-self-address.ts";
@@ -512,4 +513,71 @@ ok(
 		!/import[^;]*from\s*"\.\/lib\/entwurf-self-address\.(js|ts)"/.test(nativeSrc),
 );
 
+// ── the other half of the same honesty: a session that is NOT a citizen says so ──
+// This gate exists because a surface must not CLAIM an addressability it does not have. The mirror
+// of that is a surface that has none and says nothing: `[관측: GLG, 날것 PC, 2026-09-17]` a herdr
+// plugin install wires this extension at USER scope, so it loads in every pi on the host while
+// citizenship stays argv-gated — a plain `pi` after a green install is silent, tool-less and
+// indistinguishable from an install that did nothing.
+//
+// WHY THESE THREE CELLS AND NOT ONE REGEX. The first cut pinned "told once, on the UI only" with a
+// source regex that only proved a call existed somewhere. `[측정 2026-09-17, 독립 검수
+// claude-opus-5 + 재현]` two mutants walked through it green: moving the call into the CITIZEN
+// branch, and deleting the once-latch — 51/51 both times. That was a false success, so the
+// conditions moved into a pure decision the truth table below exhausts, and what is left at the
+// call site is narrow enough for a source pin to actually cover.
+{
+	const decide = (controlEnabled: boolean, hasUI: boolean, alreadyShown: boolean): boolean =>
+		decideUncitizenedNotice({ controlEnabled, hasUI, alreadyShown });
+	const table = {
+		citizenFirstUI: decide(true, true, false),
+		citizenNoUI: decide(true, false, false),
+		citizenShown: decide(true, true, true),
+		uncitizenedFirstUI: decide(false, true, false),
+		uncitizenedNoUI: decide(false, false, false),
+		uncitizenedShown: decide(false, true, true),
+		uncitizenedShownNoUI: decide(false, false, true),
+	};
+	ok(
+		"a citizen is never told it is not one, a session with no UI is never told anything, and the " +
+			`answer is true in exactly ONE of the eight states [QK:SELFADDR-UNCITIZENED-DECISION] (${JSON.stringify(table)})`,
+		table.uncitizenedFirstUI === true &&
+			table.citizenFirstUI === false &&
+			table.citizenNoUI === false &&
+			table.citizenShown === false &&
+			table.uncitizenedNoUI === false &&
+			table.uncitizenedShown === false &&
+			table.uncitizenedShownNoUI === false,
+	);
+}
+
+// The call site carries the REAL flag as a fact and is unconditional — there is no branch left for
+// a mutant to move it into, and passing a constant would make the decision above unreachable.
+const noticeBody = nativeSrc.slice(
+	nativeSrc.indexOf("async function noticeUncitizenedSession"),
+	nativeSrc.indexOf("function shouldRegisterControlTools"),
+);
+ok(
+	"pi-native: the not-a-citizen notice is decided from the REAL flag, on the UI only, never on stderr " +
+		"[QK:SELFADDR-UNCITIZENED-NOTICED]",
+	/const enabled = pi\.getFlag\(ENTWURF_FLAG\) === true;\n\t\tawait noticeUncitizenedSession\(ctx, enabled\);/.test(
+		nativeSrc,
+	) &&
+		/decideUncitizenedNotice\(\{ controlEnabled, hasUI: ctx\.hasUI, alreadyShown: uncitizenedNoticeShown \}\)/.test(
+			noticeBody,
+		) &&
+		/--entwurf-control/.test(noticeBody) &&
+		!/process\.stderr/.test(noticeBody),
+);
+
+// The latch is the difference between a hint and a nag: `refreshServer` runs again on session
+// switches, so the line that records "already said it" is load-bearing, not bookkeeping.
+ok(
+	"pi-native: the notice records that it fired, so a session switch does not repeat it " +
+		"[QK:SELFADDR-UNCITIZENED-ONCE]",
+	/let uncitizenedNoticeShown = false;/.test(nativeSrc) &&
+		/uncitizenedNoticeShown = true;/.test(noticeBody) &&
+		noticeBody.indexOf("uncitizenedNoticeShown = true;") < noticeBody.indexOf("ctx.ui.notify("),
+);
+
 console.log(`\ncheck-entwurf-self-address: ${passed} checks passed`);