@junghanacs/entwurf 0.21.0 → 0.23.0

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-runner.ts

@@ -12,8 +12,9 @@
  *
  * Why a result type richer than the receipt: the carry-over contracts from 5c demand it.
  *   - N3 (5c-2b): a dead-path re-resolve `rejected` carries the resolver's `rejectReason`
- *     (dormant-fire-forget-unsupported / mailbox-undeliverable / …). The runner carries it
- *     verbatim so the surface distinguishes "in-band refusal" from "no live route".
+ *     (dormant-fire-forget-unsupported / mailbox-undeliverable / …), while an in-band
+ *     refusal carries its supplied receiver error. The runner carries either verbatim;
+ *     receiver evidence is not reclassified as resolver taxonomy.
  *   - N1 (5c-2a): a non-`failed` outcome whose `releaseLock` then threw is a
  *     `SendDeliveredReleaseFailedError` — the delivery HAPPENED, the lock is dirty, a
  *     re-send would double-deliver. The runner surfaces this as `execution-failed` with

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

@@ -101,12 +101,12 @@ export interface ControlSocketSendDeps {
 
 export interface ControlSocketSendResult {
 	outcome: SendFinalOutcome;
-	/** Present ONLY on a `rejected` outcome that came from the dead-path re-resolve
-	 * (5c-2b): the resolver's machine-readable reason (dormant-fire-forget-unsupported /
-	 * mailbox-undeliverable / indeterminate-no-spawn / bad-target / target-address-conflict).
-	 * An in-band RPC refusal carries NO reason (there is no resolver taxonomy for it). The
-	 * 5d runner carries this verbatim so the surface can tell "in-band refusal" from
-	 * "no live route" — the N3 carry-over the hand boundary used to drop. */
+	/** Present ONLY on a `rejected` outcome. It carries either the dead-path re-resolver's
+	 * machine-readable reason (dormant-fire-forget-unsupported / mailbox-undeliverable /
+	 * indeterminate-no-spawn / bad-target / target-address-conflict), or the non-empty
+	 * error returned by an in-band RPC/mailbox refusal. The latter is receiver evidence,
+	 * not a resolver taxonomy and is never invented when the completed result has no error.
+	 * The 5d runner carries this verbatim to the sender-visible surface. */
 	rejectReason?: string;
 	/** #98 R, fallback leg: the `.msg` a dead-socket re-resolve enqueued. Present ONLY
 	 * when the fallback actually routed to the mailbox and the enqueue succeeded — a
@@ -120,7 +120,7 @@ export interface ControlSocketSendResult {
 
 // A drive step's verdict: the terminal outcome, plus the original error to RETHROW on
 // a `failed` (the hand releases first, then rethrows — never swallows the failure), plus
-// the optional resolver reject reason to carry on a re-resolve `rejected` (N3).
+// the optional resolver or in-band receiver reason to carry on a `rejected` (N3).
 interface SendDrive {
 	outcome: SendFinalOutcome;
 	error?: unknown;
@@ -177,8 +177,9 @@ async function driveSend(plan: ControlSocketPlan, lock: LockClaim, deps: Control
 		// dead ⇒ proven non-delivery ⇒ same-lock one-shot re-resolve (lock still held).
 		return await driveDeadFallback(plan, lock, deps);
 	}
-	// A completed RPC: ack ⇒ sent; in-band refusal ⇒ rejected, NO fallback.
-	return { outcome: result.success ? "sent" : "rejected" };
+	// A completed RPC: ack ⇒ sent; in-band refusal ⇒ rejected, NO fallback. Preserve
+	// its receiver error verbatim when supplied; do not make a reason up when absent.
+	return result.success ? { outcome: "sent" } : inBandRejected(result);
 }
 
 /**
@@ -187,6 +188,10 @@ async function driveSend(plan: ControlSocketPlan, lock: LockClaim, deps: Control
  * re-enter the fallback, it finalizes as failed). The hand only executes; the resolver
  * decided.
  */
+function inBandRejected(result: RpcSendResult): SendDrive {
+	return { outcome: "rejected", rejectReason: result.error === "" ? undefined : result.error };
+}
+
 async function driveDeadFallback(
 	plan: ControlSocketPlan,
 	lock: LockClaim,
@@ -219,7 +224,7 @@ async function driveDeadFallback(
 			// connect failure finalizes as failed (no further fallback).
 			try {
 				const r = await deps.sendOverSocket(rePlan);
-				return { outcome: r.success ? "fallback-sent" : "rejected" };
+				return r.success ? { outcome: "fallback-sent" } : inBandRejected(r);
 			} catch (err) {
 				return { outcome: "failed", error: err };
 			}
@@ -231,7 +236,7 @@ async function driveDeadFallback(
 				// #98 R: this leg writes a `.msg` exactly like the primary mailbox rail, so it
 				// owes the sender the same per-message receipt. Carried only on success — a
 				// `rejected` enqueue wrote no file to name.
-				return r.success ? { outcome: "fallback-sent", messagePath: r.messagePath } : { outcome: "rejected" };
+				return r.success ? { outcome: "fallback-sent", messagePath: r.messagePath } : inBandRejected(r);
 			} catch (err) {
 				return { outcome: "failed", error: err };
 			}