@junghanacs/entwurf 0.22.0 → 0.23.1

package/pi-extensions/lib/codex-fresh-preflight.ts

@@ -3,6 +3,15 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { parse } from "smol-toml";
 
+import {
+	CODEX_BIRTH_EVENT,
+	classifyOwnedPath,
+	entwurfDeclarationCommand,
+	selectEntwurfDeclaration,
+	statOwnedPath,
+	trustReceiptKey,
+} from "./codex-declaration.js";
+
 import {
 	type CodexProtocolOpener,
 	type CodexRpcProtocol,
@@ -65,6 +74,16 @@ export const CODEX_CALLER_PREFLIGHT_HINT: Record<CodexCallerPreflightRejectReaso
 		"this Codex caller's tui.terminal_title does not include thread-id, so the multiplexer reports no pane title naming this thread and there is no caller seat to open the sibling beside; run `entwurf install-codex-terminal-title`, then `entwurf doctor-codex-terminal-title` (an explicit placement.tmuxSession skips this check entirely, because it never needs the seat)",
 };
 
+/**
+ * What `codex-birth-install-state/v2` records ABOUT the declaration — the normalized digest of
+ * entwurf's own `SessionStart` group and the command string that selects it. Never a file digest:
+ * hooks.json is shared, and its bytes are not this unit's to certify.
+ */
+interface RecordedDeclaration {
+	command: string;
+	sha256: string;
+}
+
 export interface CodexUnitPaths {
 	hooksFile: string;
 	helperDir: string;
@@ -108,28 +127,22 @@ const CODEX_MCP_ENV_VARS = [
 	"TMUX_PANE",
 ] as const;
 
+/**
+ * ONE POLICY, FOUR SURFACES. The predicate itself lives in `codex-declaration.js` (sol B3,
+ * 2026-09-18) because the installer, the inverse and the doctor decide about the SAME shared
+ * hooks.json and used to decide differently: they checked symlink-and-regular, this checked owner
+ * and mode as well, and the doctor checked neither. That split let an install and a doctor say yes
+ * about bytes every fresh call then refused. The executable bit stays HERE — it is this rail's
+ * question about the launcher codex is going to exec, not a fact about shared ownership.
+ */
 function isSafeOwnedFile(file: string, expectedUid: number, executable = false): boolean {
-	try {
-		const stat = fs.lstatSync(file);
-		return (
-			stat.isFile() &&
-			!stat.isSymbolicLink() &&
-			stat.uid === expectedUid &&
-			(stat.mode & 0o022) === 0 &&
-			(!executable || (stat.mode & 0o111) !== 0)
-		);
-	} catch {
-		return false;
-	}
+	const stat = statOwnedPath(fs, file);
+	if (classifyOwnedPath(stat, expectedUid) !== "ok") return false;
+	return !executable || (stat.mode & 0o111) !== 0;
 }
 
 function isSafeOwnedDir(dir: string, expectedUid: number): boolean {
-	try {
-		const stat = fs.lstatSync(dir);
-		return stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === expectedUid && (stat.mode & 0o022) === 0;
-	} catch {
-		return false;
-	}
+	return classifyOwnedPath(statOwnedPath(fs, dir), expectedUid, { kind: "directory" }) === "ok";
 }
 
 /**
@@ -137,21 +150,37 @@ function isSafeOwnedDir(dir: string, expectedUid: number): boolean {
  * EXIST prove nothing: the launcher codex is about to exec must be the one this unit
  * published, so every recorded member is compared to its recorded digest before a sibling
  * is opened. No digest is computed for the VENDOR here — that is a different axis below.
+ *
+ * WHAT THIS NO LONGER READS (#117): a WHOLE-FILE `hooksSha256`. `codex-birth-install-state/v2`
+ * records the normalized digest of entwurf's own declaration instead, because hooks.json is a
+ * file this unit SHARES — a neighbouring integration appending its own `SessionStart` group
+ * changes every byte of that file and none of our declaration's meaning. The declaration axis
+ * lives in `birthDeclaration` below, which needs the live document anyway to find where our group
+ * currently sits.
  */
-function closureDriftedFromState(paths: CodexUnitPaths, expectedUid: number): boolean {
+function certifiedState(paths: CodexUnitPaths, expectedUid: number): RecordedDeclaration | null {
 	// The directory holding the state carries the state's authority: anyone who can write it
 	// can replace the inventory every digest below is compared against.
-	if (!isSafeOwnedDir(path.dirname(paths.stateFile), expectedUid)) return true;
-	if (!isSafeOwnedDir(path.dirname(path.dirname(paths.stateFile)), expectedUid)) return true;
-	if (!isSafeOwnedFile(paths.stateFile, expectedUid)) return true;
+	if (!isSafeOwnedDir(path.dirname(paths.stateFile), expectedUid)) return null;
+	if (!isSafeOwnedDir(path.dirname(path.dirname(paths.stateFile)), expectedUid)) return null;
+	if (!isSafeOwnedFile(paths.stateFile, expectedUid)) return null;
 	let state: Record<string, unknown>;
 	try {
 		state = JSON.parse(fs.readFileSync(paths.stateFile, "utf8")) as Record<string, unknown>;
 	} catch {
-		return true;
+		return null;
 	}
-	if (state.schema !== "codex-birth-install-state/v1" || state.status !== "installed") return true;
-	if (state.hooksFile !== paths.hooksFile || state.helperDir !== paths.helperDir) return true;
+	// v2 ONLY, and a v1 state is refused rather than read leniently: v1 recorded a whole-file
+	// digest, so a reader that tolerated it would be certifying an authority nobody holds any
+	// more. `entwurf install-codex-birth` supersedes it — that is the one forward path.
+	if (state.schema !== "codex-birth-install-state/v2" || state.status !== "installed") return null;
+	if (state.hooksFile !== paths.hooksFile || state.helperDir !== paths.helperDir) return null;
+	const declaration = state.declaration;
+	if (declaration === null || typeof declaration !== "object" || Array.isArray(declaration)) return null;
+	const recorded = declaration as Record<string, unknown>;
+	if (recorded.event !== CODEX_BIRTH_EVENT) return null;
+	if (typeof recorded.command !== "string" || typeof recorded.sha256 !== "string") return null;
+	if (!/^[0-9a-f]{64}$/.test(recorded.sha256)) return null;
 	const digest = (file: string): string | null => {
 		try {
 			return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
@@ -159,9 +188,8 @@ function closureDriftedFromState(paths: CodexUnitPaths, expectedUid: number): bo
 			return null;
 		}
 	};
-	if (typeof state.hooksSha256 !== "string" || digest(paths.hooksFile) !== state.hooksSha256) return true;
 	const members = state.helperFiles;
-	if (!Array.isArray(members)) return true;
+	if (!Array.isArray(members)) return null;
 	// Exactly the closure the installer publishes: a short inventory would leave a member
 	// nothing compares, which is the same hole as not checking digests at all.
 	const named = members.map((raw) => (raw as Record<string, unknown>)?.path);
@@ -173,21 +201,38 @@ function closureDriftedFromState(paths: CodexUnitPaths, expectedUid: number): bo
 		"lib/session-id.js",
 		"entwurf-capabilities.json",
 	];
-	if (named.length !== expected.length) return true;
-	if (expected.some((name) => !named.includes(name))) return true;
-	if (named.some((name, index) => named.indexOf(name) !== index)) return true;
+	if (named.length !== expected.length) return null;
+	if (expected.some((name) => !named.includes(name))) return null;
+	if (named.some((name, index) => named.indexOf(name) !== index)) return null;
 	for (const raw of members) {
 		const member = raw as Record<string, unknown>;
 		const rel = member.path;
 		if (typeof rel !== "string" || rel.length === 0 || rel.startsWith("/") || rel.split("/").includes("..")) {
-			return true;
+			return null;
 		}
-		if (typeof member.sha256 !== "string" || digest(path.join(paths.helperDir, rel)) !== member.sha256) return true;
+		if (typeof member.sha256 !== "string" || digest(path.join(paths.helperDir, rel)) !== member.sha256) return null;
 	}
-	return false;
+	return { command: recorded.command, sha256: recorded.sha256 };
 }
 
-function birthMissing(paths: CodexUnitPaths, expectedUid: number): boolean {
+/**
+ * WHERE ENTWURF'S DECLARATION CURRENTLY SITS, or nothing.
+ *
+ * `null` here means the SAME reject as before — `codex-birth-unit-missing` — but the question
+ * it answers is narrower than it used to be (#117). It no longer asks "is hooks.json exactly the
+ * file we wrote"; it asks "is entwurf's own `SessionStart` group present exactly once, shaped the
+ * way the operator approved, and still the declaration this unit recorded". A Herdr (or any
+ * other) integration declaring its own group beside ours changes neither answer.
+ *
+ * The POSITION is the return value rather than a side note because the vendor keys its trust
+ * receipt by index: a declaration that has been renumbered by a neighbour's install needs its
+ * receipt read at the new index, and reading the old one would report a NEIGHBOUR's approval as
+ * our own.
+ */
+function birthDeclaration(
+	paths: CodexUnitPaths,
+	expectedUid: number,
+): { groupIndex: number; handlerIndex: number } | null {
 	const launcher = path.join(paths.helperDir, "codex-birth-launch.sh");
 	const directories = [
 		path.dirname(paths.hooksFile),
@@ -195,8 +240,8 @@ function birthMissing(paths: CodexUnitPaths, expectedUid: number): boolean {
 		path.join(paths.helperDir, "lib"),
 		path.join(paths.helperDir, "lib", "native-push"),
 	];
-	if (directories.some((dir) => !isSafeOwnedDir(dir, expectedUid))) return true;
-	if (!isSafeOwnedFile(paths.hooksFile, expectedUid)) return true;
+	if (directories.some((dir) => !isSafeOwnedDir(dir, expectedUid))) return null;
+	if (!isSafeOwnedFile(paths.hooksFile, expectedUid)) return null;
 	const closure = [
 		[launcher, true],
 		[path.join(paths.helperDir, "meta-bridge-hook-codex.ts"), false],
@@ -205,20 +250,23 @@ function birthMissing(paths: CodexUnitPaths, expectedUid: number): boolean {
 		[path.join(paths.helperDir, "lib", "session-id.js"), false],
 		[path.join(paths.helperDir, "entwurf-capabilities.json"), false],
 	] as const;
-	if (closure.some(([file, executable]) => !isSafeOwnedFile(file, expectedUid, executable))) return true;
+	if (closure.some(([file, executable]) => !isSafeOwnedFile(file, expectedUid, executable))) return null;
+	const recorded = certifiedState(paths, expectedUid);
+	if (recorded === null) return null;
+	// The state's own account of what it certified must be the declaration these paths produce;
+	// a receipt bound to a different launcher is a receipt for a different unit.
+	if (recorded.command !== entwurfDeclarationCommand(launcher)) return null;
+	let selected: ReturnType<typeof selectEntwurfDeclaration>;
 	try {
-		const parsed = JSON.parse(fs.readFileSync(paths.hooksFile, "utf8")) as Record<string, unknown>;
-		const events = (parsed.hooks as Record<string, unknown> | undefined)?.SessionStart;
-		if (!Array.isArray(events) || events.length !== 1) return true;
-		const group = events[0] as Record<string, unknown>;
-		if ("matcher" in group || !Array.isArray(group.hooks) || group.hooks.length !== 1) return true;
-		const hook = group.hooks[0] as Record<string, unknown>;
-		if (Object.keys(hook).sort().join(",") !== "command,timeout,type") return true;
-		if (hook.type !== "command" || hook.command !== `'${launcher}'` || hook.timeout !== 30) return true;
+		selected = selectEntwurfDeclaration(JSON.parse(fs.readFileSync(paths.hooksFile, "utf8")), launcher);
 	} catch {
-		return true;
+		return null;
 	}
-	return closureDriftedFromState(paths, expectedUid);
+	if (!selected.ok) return null;
+	// The NORMALIZED digest, so a neighbour re-serializing the document (measured: Herdr does)
+	// cannot make our intact declaration look edited — and an edit to our own handler still can.
+	if (selected.digest !== recorded.sha256) return null;
+	return { groupIndex: selected.groupIndex, handlerIndex: selected.handlerIndex };
 }
 
 /**
@@ -227,13 +275,19 @@ function birthMissing(paths: CodexUnitPaths, expectedUid: number): boolean {
  * `trusted_hash` of the shape `sha256:<64 hex>`. What this asserts is that a receipt EXISTS
  * for our declaration identity — never that the hash is correct, which only the vendor can
  * say, and never by launching Codex to find out.
+ *
+ * THE KEY IS MEASURED, NOT ASSUMED (#117). It used to be spelled `…:session_start:0:0`, which
+ * was true only while entwurf was the sole declaration in the file. With a neighbour at index 0
+ * that constant reads THEIR receipt and calls it ours — a false green for a hook the vendor has
+ * never been asked to run. The caller passes the key built from the position our declaration was
+ * just found at.
  */
-function trustReceiptMissing(config: Record<string, unknown>, hooksFile: string): boolean {
+function trustReceiptMissing(config: Record<string, unknown>, key: string): boolean {
 	const hooks = config.hooks;
 	if (hooks == null || typeof hooks !== "object" || Array.isArray(hooks)) return true;
 	const state = (hooks as Record<string, unknown>).state;
 	if (state == null || typeof state !== "object" || Array.isArray(state)) return true;
-	const entry = (state as Record<string, unknown>)[`${hooksFile}:session_start:0:0`];
+	const entry = (state as Record<string, unknown>)[key];
 	if (entry == null || typeof entry !== "object" || Array.isArray(entry)) return true;
 	const digest = (entry as Record<string, unknown>).trusted_hash;
 	return typeof digest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(digest);
@@ -558,14 +612,16 @@ export async function codexFreshPreflight(
 	if (!path.isAbsolute(paths.hooksFile) || !path.isAbsolute(paths.helperDir) || !path.isAbsolute(paths.stateFile)) {
 		return "codex-birth-unit-missing";
 	}
-	if (birthMissing(paths, deps.operatorUid ?? process.getuid?.() ?? -1)) {
+	const declaration = birthDeclaration(paths, deps.operatorUid ?? process.getuid?.() ?? -1);
+	if (declaration === null) {
 		return "codex-birth-unit-missing";
 	}
 	const config = readConfig(env);
 	// The vendor receipt is a SEPARATE reject from our bytes: perfect bytes the vendor will
 	// not run and absent bytes are two different repairs, and folding them would send the
 	// operator to the installer for something only they can answer in their own Codex.
-	if (config === null || trustReceiptMissing(config, paths.hooksFile)) return "codex-birth-trust-missing";
+	const key = trustReceiptKey(paths.hooksFile, declaration.groupIndex, declaration.handlerIndex);
+	if (config === null || trustReceiptMissing(config, key)) return "codex-birth-trust-missing";
 	if (mcpMissing(config)) return "codex-mcp-hand-missing";
 	if (visibleIdentityMissing(config)) return "codex-visible-identity-missing";
 	const socketPath = resolveCodexDefaultSocketPath(env);

package/pi-extensions/lib/entwurf-control-rpc.ts

@@ -102,6 +102,52 @@ export interface RpcGetInfoCommand {
 
 export type RpcCommand = RpcSendCommand | RpcGetMessageCommand | RpcClearCommand | RpcAbortCommand | RpcGetInfoCommand;
 
+// ============================================================================
+// Accepted-connection disconnect policy (server half of the same wire)
+// ============================================================================
+
+/** The two codes that mean THE PEER WENT AWAY, and nothing else. `EPIPE` is a write to a pipe the
+ * far side already closed; `ECONNRESET` is the far side resetting it. Both describe the client, not
+ * this process's state, which is why they are absorbed rather than diagnosed. */
+const PEER_DISCONNECT_CODES = new Set(["EPIPE", "ECONNRESET"]);
+
+export function isPeerDisconnect(error: NodeJS.ErrnoException): boolean {
+	return typeof error.code === "string" && PEER_DISCONNECT_CODES.has(error.code);
+}
+
+/**
+ * Install the disconnect policy on a connection this process ACCEPTED. Must run before any data
+ * handler and before any response can be written back.
+ *
+ * `[측정 2026-09-14, .agent-reports/116-c4-live-blocker-20260914.md]` a resident pi DIED without
+ * this. A sibling's control-socket send timed out while the receiving session was mid-turn, the
+ * sender closed its end, and the server then wrote its late response to a socket whose peer was
+ * gone. That EPIPE does NOT arrive as a throw — `writeResponse`'s synchronous try/catch cannot see
+ * it — it arrives asynchronously as an `error` event, and an `error` event with no listener is an
+ * uncaught exception, so Node terminated the whole session. The citizen then simply read as `dead`
+ * and the stale socket it left behind was the only trace.
+ *
+ * A client that went away is a BOUNDED environment condition, not invalid state: Rule 15's "crash,
+ * don't warn" governs states we cannot reason about, and losing an entire resident session because
+ * someone hung up is itself the silent failure. Same policy the MCP probe already carries for an
+ * async EPIPE on a child's stdin (`scripts/probe-bridge-command.ts:88-97`).
+ *
+ * Anything that is NOT a peer hanging up is diagnosed exactly once with its code and message and
+ * then served on. Swallowing every error would hide the class this listener is not here to absorb;
+ * rethrowing from an event callback would be the crash this whole function exists to prevent.
+ *
+ * `diagnose` is injected so a gate can count diagnostics without capturing global stderr.
+ */
+export function attachAcceptedSocketDisconnectPolicy(
+	socket: net.Socket,
+	diagnose: (line: string) => void = (line) => console.error(line),
+): void {
+	socket.on("error", (error: NodeJS.ErrnoException) => {
+		if (isPeerDisconnect(error)) return;
+		diagnose(`[entwurf-control] control socket error (${error.code ?? "no code"}): ${error.message}`);
+	});
+}
+
 export interface RpcClientOptions {
 	timeout?: number;
 }

package/pi-extensions/lib/entwurf-fact-provider.ts

@@ -34,8 +34,9 @@ import {
 	resolveFactList,
 	UNOBSERVED_PEER,
 } from "./entwurf-facts.ts";
-import { observePeerFacts } from "./entwurf-peer-observe.ts";
+import { makeObservePeerFacts, readHerdrPlacementIndex } from "./entwurf-peer-observe.ts";
 import { isLivenessSupported } from "./entwurf-v2-contract.ts";
+import type { HerdrPlacementIndex } from "./herdr-placement.ts";
 import {
 	type ActiveStoreEntry,
 	FRESH_CUT_PRESCRIPTION,
@@ -105,6 +106,12 @@ export interface EntwurfFactsDeps {
 	 * wiring sites (MCP + pi-native) cannot drift by each passing their own observer, and a
 	 * gate still drives the assembly with a fake and no filesystem. */
 	observe?: PeerObserver;
+	/** Placement axis (#116 S1): the ONE placement-owner read this listing is allowed.
+	 * Injected so a gate drives the whole assembly with no herdr binary and no child
+	 * process. `undefined` uses the real read; a reader that returns `null` is the
+	 * no-herdr host and every row then says `unobserved`. Deliberately a READ, not a
+	 * per-citizen lookup: a per-citizen hook would invite one child process per record. */
+	readPlacementIndex?: () => HerdrPlacementIndex | null;
 	/** Optional presentation budget. Undefined preserves the generic fact provider's full
 	 * observation contract; peers surfaces pass their shared render limit. Older machine
 	 * payload rows then say `unobserved` rather than fabricating `active` / `exists`. */
@@ -209,7 +216,11 @@ export async function listEntwurfFacts(deps: EntwurfFactsDeps): Promise<EntwurfF
 	//    not performed becomes `unobserved`.
 	const cleanIdentities = identities.filter((i) => !conflictGids.has(i.gardenId));
 	const cleanProbes = probes.filter((p) => !conflictGids.has(p.gardenId));
-	const observe = deps.observe ?? observePeerFacts;
+	// The placement owner is read EXACTLY ONCE per listing, before any row is shaped, and
+	// never again for this call. That single read is the anti-watcher rule in code: herdr
+	// publishes no "the session reference landed" event, and a retry loop around that gap
+	// is the discovery watcher `docs/mux-launch-rail.md` §7 refuses by name.
+	const observe = deps.observe ?? makeObservePeerFacts((deps.readPlacementIndex ?? readHerdrPlacementIndex)());
 	let selectedObserve = observe;
 	if (deps.observationLimit !== undefined) {
 		if (!Number.isSafeInteger(deps.observationLimit) || deps.observationLimit < 0) {

package/pi-extensions/lib/entwurf-facts.ts

@@ -31,6 +31,7 @@
  */
 
 import { type FactLiveness, factLivenessOf, isLivenessSupported } from "./entwurf-v2-contract.ts";
+import { type PlacementObservation, UNOBSERVED_PLACEMENT } from "./herdr-placement.ts";
 import type { MetaCitizenBackend, MetaIdentity } from "./meta-session.ts";
 import type { SocketLiveness } from "./socket-probe.ts";
 
@@ -57,6 +58,12 @@ export interface PeerFact {
 	//   "the newest record in this cwd" picked the phantom as often as the real one.
 	receiver: ReceiverObservation;
 	transcript: TranscriptObservation;
+	// — the third observed axis (#116 S1): WHERE a citizen is visible, when a
+	//   placement owner reported it on a key we independently own. A pane is an
+	//   ephemeral view (Hard Rule 16), so this sits beside `receiver`/`transcript`
+	//   as evidence and never beside `liveness` as a claim about being alive: a
+	//   pane can outlive its process and a process can outlive its pane.
+	placement: PlacementObservation;
 }
 
 /**
@@ -79,11 +86,16 @@ export type TranscriptObservation = "exists" | "absent" | "unobserved";
 export interface PeerObservations {
 	receiver: ReceiverObservation;
 	transcript: TranscriptObservation;
+	placement: PlacementObservation;
 }
 
 /** What a caller that measured nothing must say. Explicit and greppable — a row that
  * silently defaulted to `none`/`absent` would be a fabricated fact. */
-export const UNOBSERVED_PEER: PeerObservations = { receiver: "unobserved", transcript: "unobserved" };
+export const UNOBSERVED_PEER: PeerObservations = {
+	receiver: "unobserved",
+	transcript: "unobserved",
+	placement: UNOBSERVED_PLACEMENT,
+};
 
 /** Measure the two observed axes for one citizen. Injected, so this module stays pure. */
 export type PeerObserver = (identity: MetaIdentity) => PeerObservations;
@@ -116,6 +128,7 @@ export function resolvePeerFact(
 		liveness: factLivenessOf(identity.backend, socket),
 		receiver: observations.receiver,
 		transcript: observations.transcript,
+		placement: observations.placement,
 	};
 }
 

package/pi-extensions/lib/entwurf-peer-observe.ts

@@ -13,6 +13,13 @@
  * about it: no `sendable`, no `deliverable`, no transport. The listing stays a listing —
  * dispatch still computes routing at call time from the same underlying markers.
  *
+ * THE PLACEMENT AXIS IS MEASURED ONCE, NOT PER CITIZEN (#116 S1). `receiver` and
+ * `transcript` are per-citizen filesystem questions; placement is one question asked of
+ * one placement owner about every pane it has. So the herdr read happens ABOVE this
+ * module (the provider does it once) and arrives here as an already-built index. That
+ * is also the anti-watcher shape: one read per listing, no retry, no wait for a pane
+ * whose session reference has not landed yet.
+ *
  * ONE MEASUREMENT, TWO WORDS. `receiver` is derived from the SAME
  * `resolveMailboxReceiverFacts` composition the v2 dispatch seam and `entwurf_self` use.
  * The surfaces are allowed to phrase it differently — a listing wants an enum, a reject
@@ -20,9 +27,16 @@
  * rather than a second opinion about the same markers.
  */
 
+import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import { resolveMailboxReceiverFacts } from "./entwurf-deliverability.ts";
 import type { PeerObservations, ReceiverObservation, TranscriptObservation } from "./entwurf-facts.ts";
+import {
+	buildPlacementIndex,
+	type HerdrPlacementIndex,
+	parseHerdrPaneList,
+	resolvePlacement,
+} from "./herdr-placement.ts";
 import {
 	type MetaBackend,
 	type MetaIdentity,
@@ -71,7 +85,63 @@ function observeTranscript(identity: MetaIdentity): TranscriptObservation {
 	}
 }
 
-/** The production observer: both axes, measured for one citizen. */
+/** How long the one placement read may take before we stop waiting for it. A listing
+ * must not hang on a placement owner: the column is a convenience and `unobserved` is
+ * a complete answer. */
+const HERDR_READ_TIMEOUT_MS = 2000;
+
+/**
+ * Read the placement owner ONCE, or decline to.
+ *
+ * TWO ENV FACTS DECIDE, AND BOTH ARE HERDR'S OWN (measured, herdr 0.9.0). `HERDR_ENV=1`
+ * is how herdr tells a process it is running inside herdr, and `HERDR_BIN_PATH` is the
+ * invocation path herdr's own plugin contract tells callers to use. Neither is
+ * discovered: if herdr did not put them in this process's environment we are not inside
+ * herdr and we make no claim. There is no path guess, no socket scan, and no PATH
+ * lookup — this must stay as explicit as Hard Rule 6 wants configuration to be.
+ *
+ * EVERY FAILURE IS `null`, NEVER AN EMPTY INDEX. A missing binary, a timeout, a nonzero
+ * exit or a payload we cannot parse all mean nobody measured. An empty index would say
+ * something much stronger — "herdr was read and has none of your citizens" — about a
+ * read that did not happen.
+ */
+export function readHerdrPlacementIndex(env: NodeJS.ProcessEnv = process.env): HerdrPlacementIndex | null {
+	if (env.HERDR_ENV !== "1") return null;
+	const bin = env.HERDR_BIN_PATH;
+	if (typeof bin !== "string" || bin.length === 0) return null;
+	let stdout: string;
+	try {
+		stdout = execFileSync(bin, ["pane", "list"], {
+			encoding: "utf8",
+			timeout: HERDR_READ_TIMEOUT_MS,
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+	} catch {
+		// Bounded environment probe: a placement owner that did not answer is a citizen
+		// column that reads `unobserved`, not a listing that fails.
+		return null;
+	}
+	const rows = parseHerdrPaneList(stdout);
+	return rows === null ? null : buildPlacementIndex(rows);
+}
+
+/**
+ * Build the production observer over an already-resolved placement index.
+ *
+ * `null` means no placement owner was read on this host — every citizen then reads
+ * `unobserved`, which is the only honest answer when nobody looked. It is NOT `none`:
+ * that word is reserved for a herdr that WAS read and does not have this citizen.
+ */
+export function makeObservePeerFacts(placementIndex: HerdrPlacementIndex | null) {
+	return (identity: MetaIdentity): PeerObservations => ({
+		receiver: observeReceiver(identity),
+		transcript: observeTranscript(identity),
+		placement: resolvePlacement(placementIndex, identity),
+	});
+}
+
+/** The production observer with no placement owner read — the shape every caller that
+ * has not resolved an index gets, and the default on a host with no herdr. */
 export function observePeerFacts(identity: MetaIdentity): PeerObservations {
-	return { receiver: observeReceiver(identity), transcript: observeTranscript(identity) };
+	return makeObservePeerFacts(null)(identity);
 }

package/pi-extensions/lib/entwurf-peers-render.ts

@@ -25,6 +25,7 @@
 
 import type { EntwurfDiagnostic, EntwurfFactsResult } from "./entwurf-fact-provider.ts";
 import type { PeerFact } from "./entwurf-facts.ts";
+import { renderPlacement } from "./herdr-placement.ts";
 
 /** The full `entwurf_peers` JSON payload: citizens + diagnostics, nothing else.
  * NO verb-routing field anywhere (the gate enforces this by deep key scan) and
@@ -50,11 +51,18 @@ export const ENTWURF_PEERS_RENDER_LIMIT = 32;
 // be indistinguishable here. `receiver=active|inactive|none|n/a` is a projection of the
 // same measurement dispatch uses; `transcript=exists|absent` is the record's transcript,
 // existence only, never the path.
+//
+// `placement` (#116 S1) is the third observed fact and the one most likely to be
+// MISREAD, so it is placed at the END of the row — away from `liveness` — and printed
+// as `herdr <pane>` rather than a bare pane id. A pane says where a citizen was last
+// SEEN by a placement owner; it says nothing about whether that citizen is running, and
+// nothing about how to reach it. `unobserved` = nobody looked (no herdr here), `none` =
+// herdr was read and does not have this one, `ambiguous` = more than one pane claimed it.
 function renderPeerLine(p: PeerFact): string {
 	const model = p.model ?? "(unknown)";
 	return (
 		`- ${p.gardenId}  backend=${p.backend}  liveness=${p.liveness}  receiver=${p.receiver}  ` +
-		`transcript=${p.transcript}  cwd=${p.cwd}  model=${model}`
+		`transcript=${p.transcript}  cwd=${p.cwd}  model=${model}  placement=${renderPlacement(p.placement)}`
 	);
 }
 

package/pi-extensions/lib/entwurf-self-address.ts

@@ -168,3 +168,36 @@ export function computeSelfAddressability(facts: SelfAddressabilityFacts): SelfA
 		}
 	}
 }
+
+/** Facts the uncitizened-notice decision is made from. Nothing is read here — all three are given. */
+export interface UncitizenedNoticeFacts {
+	/** Did this session get `--entwurf-control`? A citizen is never told it is not one. */
+	controlEnabled: boolean;
+	/** Is there a human surface to say it on? `pi -p …` has none, and neither does any pipeline. */
+	hasUI: boolean;
+	/** Has this process already said it? `refreshServer` runs again on session switches. */
+	alreadyShown: boolean;
+}
+
+/**
+ * The mirror of `computeSelfAddressability`, as a decision rather than a claim.
+ *
+ * That function exists so a surface never CLAIMS an addressability it lacks. This one exists so a
+ * surface does not stay SILENT about lacking one: `[관측: 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 on purpose — and a plain `pi` after a green install is therefore silent,
+ * tool-less and indistinguishable from an install that did nothing.
+ *
+ * WHY THIS IS A FUNCTION AND NOT THREE `if`s AT THE CALL SITE. It was three `if`s, and its gate was
+ * a source regex asserting the call existed. `[측정 2026-09-17, 독립 검수 claude-opus-5 + 재현]` two
+ * mutants walked straight through that green: moving the call into the CITIZEN branch (so citizens
+ * are told they are not citizens and plain pi stays silent), and deleting the once-latch (so the
+ * line repeats on every session switch). A regex can see that a call exists; it cannot see which
+ * branch it is in or how often it fires. Those are properties of FACTS, so the facts are now
+ * arguments and the answer is a value a truth table can exhaust.
+ */
+export function decideUncitizenedNotice(facts: UncitizenedNoticeFacts): boolean {
+	if (facts.controlEnabled) return false;
+	if (!facts.hasUI) return false;
+	return !facts.alreadyShown;
+}

package/pi-extensions/lib/entwurf-v2-contract.ts

@@ -111,7 +111,7 @@ export type DispatchLiveness = (typeof DISPATCH_LIVENESSES)[number];
 // unreachable (the native-push rail measures it — entwurf-v2-decider.ts). Widening
 // THIS set is a deliberate future decision, gated by a real compatible
 // control-socket predicate — never by silently mapping sessions to dead/indeterminate
-// (R1 핵심). check-entwurf-facts pins this == ["pi"] and asserts the native-push
+// (R1 핵심). pi-extensions/lib/entwurf-facts.test.ts pins this == ["pi"] and asserts the native-push
 // domain is disjoint from it.
 export const LIVENESS_DOMAIN_BACKENDS = ["pi"] as const;
 export type LivenessDomainBackend = (typeof LIVENESS_DOMAIN_BACKENDS)[number];
@@ -125,7 +125,7 @@ export function isLivenessSupported(backend: string): boolean {
 // live vendor app-server target probe), NOT a control socket. This domain is DISJOINT
 // from LIVENESS_DOMAIN_BACKENDS: an Antigravity or Codex session is `unsupported` on
 // the socket FACT axis (entwurf_peers) yet independently measured on the native-push
-// axis. The two are separate rails on purpose — check-entwurf-facts pins both sets
+// axis. The two are separate rails on purpose — pi-extensions/lib/entwurf-facts.test.ts pins both sets
 // and asserts their intersection is ∅ (a backend can never be in both domains).
 export const NATIVE_PUSH_BACKENDS = ["antigravity", "codex"] as const;
 export type NativePushBackend = (typeof NATIVE_PUSH_BACKENDS)[number];

package/pi-extensions/lib/entwurf-v2-lock.ts

@@ -82,7 +82,7 @@ export const LOCK_SUFFIX = ".lock";
 export const LOCK_OWNER = "entwurf_v2" as const;
 
 /** The reject reason a lock conflict maps to. Kept as a literal here (the lock
- * primitive stays decoupled from the full contract); `check-entwurf-v2-lock`
+ * primitive stays decoupled from the full contract); `pi-extensions/lib/entwurf-v2-lock.test.ts`
  * cross-checks it against the contract's ENTWURF_V2_REJECT_REASONS so the two
  * cannot drift. */
 export const LOCK_CONFLICT_REASON = "target-locked" as const;

package/pi-extensions/lib/entwurf-v2-runner.ts

@@ -201,7 +201,7 @@ export async function executeDispatch(
 /**
  * 5d-2a: the deps `runEntwurfV2` joins. `decide` is the WHOLE decider as ONE injected
  * function — NOT `DispatchDeciderDeps`. The runner does not re-validate the 5b decider
- * logic (that is `check-entwurf-v2-decider`'s job); it proves only the decide→execute
+ * logic (that is `pi-extensions/lib/entwurf-v2-decider.test.ts`'s job); it proves only the decide→execute
  * COMPOSITION contract over a fake `decide`. Production wraps the real decider as
  * `decide: (input) => decideDispatch(input, productionDeciderDeps)` (assembled in 5d-2b),
  * so the runner stays gate-provable without any decider IO seam leaking in.