@junghanacs/entwurf 0.22.0 → 0.23.1

package/mcp/entwurf-bridge/dist/scripts/peer-facts.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * peer-facts — the read-only JSON projection of the OBSERVED peer listing (#116 M2-a).
+ *
+ * `meta-facts` (#65) emits what the meta-record STORE owns. This emits what the fact
+ * PROVIDER owns: the same `listEntwurfFacts` assembly `entwurf_peers` renders, serialized
+ * instead of drawn. It exists for the same reason #65 exists — so a consumer stops
+ * carrying a decaying copy of a join it does not own.
+ *
+ * THE COPY THIS REFUSES. The placement axis joins a herdr pane to a citizen on
+ * `nativeSessionId`, and on the pi side that key is recovered from a session FILENAME by a
+ * strict conversion measured against one vendor floor (`herdr-placement.ts`
+ * piNativeSessionIdFromPath). A consumer that re-implements that join forks a vendor floor
+ * into a file no gate covers and no document owns (`docs/mux-launch-rail.md` §7). With this
+ * verb the consumer's whole join becomes ONE opaque pane-id string equality, which is a
+ * thing a shell script may correctly do.
+ *
+ * ONE PROVIDER, ONE RENDERER, NO SECOND JOIN. The payload is `renderEntwurfPeers().payload`
+ * — the same provider (`listEntwurfFacts`) through the same renderer the MCP `entwurf_peers`
+ * surface uses, so the SHAPE is that surface's payload shape and each row is a `PeerFact`
+ * whose keyset `check-entwurf-peers-surface` pins to `{peers, diagnostics}`. Nothing here
+ * recomputes, filters, re-sorts or re-words a provider fact, and nothing here re-implements
+ * the join.
+ *
+ * It is NOT the same bytes as an `entwurf_peers` call, and the difference is deliberate, not
+ * a drift: that surface is a human listing, so it passes `observationLimit` and returns only
+ * rendered TEXT over the wire. This is a machine projection, so its observation is
+ * UNBOUNDED — a rationed row would say `unobserved`, which a machine consumer cannot tell
+ * apart from "nobody could look". Older rows can therefore read `exists`/`active` here where
+ * the human surface says `unobserved`. Same facts, measured for more rows.
+ *
+ * `placement` STAYS STRUCTURED. The human surface prints `herdr <pane>` so a reader never
+ * mistakes a pane id for one of ours; a machine consumer needs the tagged union itself
+ * (`{kind:"herdr-pane",paneId}` / `unobserved` / `none` / `ambiguous`), so `renderPlacement`
+ * is NOT applied here. A pane is an ephemeral view (Hard Rule 16), never an address.
+ *
+ * WHAT IS DELIBERATELY ABSENT. No herdr `agent_status`, no `interactive_ready`, no screen
+ * text: those are herdr's own display verdicts, they are not delivery evidence
+ * (`docs/herdr-launch-rail.md` §9), and keeping them out of every entwurf payload is what
+ * makes "observed activity" unable to drift into delivery liveness. A consumer that wants
+ * to show them reads herdr itself and labels them as herdr's report.
+ *
+ * ONE PLACEMENT READ. `readPlacementIndex` is left undefined, so the provider performs its
+ * own single read per listing — the anti-watcher shape `entwurf-fact-provider.ts` documents.
+ * This verb never loops, retries, or waits for a pane whose session reference has not landed.
+ *
+ * NO SOCKET COORDINATE LEAVES THIS VERB. `ENTWURF_DIR` selects the socket world that is
+ * PROBED, and that is all it does: the control dir is never emitted. #50 C4 retired the
+ * legacy `sessions` projection "with the `controlDir` it exposed" because the record is the
+ * sole address axis and socket paths are dispatch-internal transport
+ * (`entwurf-peers-render.ts` header). Re-publishing that path under a new verb would undo
+ * that retirement, and no renderer needs it.
+ *
+ * stdout (deterministic, 2-space indent, trailing newline):
+ *   {
+ *     "schemaVersion": 1,        // of THIS projection
+ *     "storeDir":    "/abs",     // the meta-record store that was read
+ *     "peers":       [ <PeerFact, verbatim, provider order> ],
+ *     "diagnostics": [ <EntwurfDiagnostic, verbatim> ]
+ *   }
+ *
+ * EXIT CONTRACT — identical in shape to meta-facts, for the same reason:
+ *   0 — the store was readable; the JSON above is on stdout (diagnostics in-band).
+ *       A store that does not exist is a readable EMPTY store (ENOENT only).
+ *   2 — usage error (bad argv).
+ *   3 — the store could not be READ. No JSON is emitted: an unreadable host must
+ *       never look like an empty one.
+ * A provider wiring invariant (duplicate identity / unprobed in-domain citizen) is left to
+ * THROW. It is not an unreadable store and must not be dressed as one (Hard Rule 15).
+ */
+import os from "node:os";
+import { defaultControlSocketDir } from "../pi-extensions/lib/control-socket-path.js";
+import { listEntwurfFacts } from "../pi-extensions/lib/entwurf-fact-provider.js";
+import { renderEntwurfPeers } from "../pi-extensions/lib/entwurf-peers-render.js";
+import { defaultMetaSessionsDir, makeStoreRecordReader, readActiveStoreEntries, } from "../pi-extensions/lib/meta-session.js";
+const arg = process.argv[2];
+// A dash argv is a flag this command does not have, not a store directory — treating it as
+// a path would answer `--help` with "empty store, exit 0", a silent wrong fact.
+if (process.argv.length > 3 || (arg !== undefined && arg.startsWith("-"))) {
+    console.error("usage: entwurf peer-facts [meta-sessions-dir]");
+    process.exit(2);
+}
+const storeDir = arg ?? defaultMetaSessionsDir();
+// The SAME override the bridge honours (`mcp/entwurf-bridge/src/index.ts` ENTWURF_DIR), so
+// this verb and `entwurf_peers` probe one socket world. The pi side has no such override;
+// the path grammar is the shared leaf either way. This value is an INPUT to the probe and
+// never an output — see NO SOCKET COORDINATE LEAVES THIS VERB above.
+const controlDir = process.env.ENTWURF_DIR ?? defaultControlSocketDir(os.homedir());
+let metaEntries;
+try {
+    // Entries WITH their kind, never bare names: the listing must be able to refuse a
+    // symlinked record without following it (Hard Rule 7). ENOENT is the empty store.
+    metaEntries = readActiveStoreEntries(storeDir);
+}
+catch (err) {
+    console.error(`FAIL: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(3); // see the EXIT CONTRACT above: 3 = unreadable store, never an empty one
+}
+const result = await listEntwurfFacts({
+    metaEntries,
+    readRecord: makeStoreRecordReader(storeDir),
+    socket: { dir: controlDir },
+    // No `observationLimit`: a budget would emit `unobserved` for rows nobody chose to
+    // skip, and in a machine payload that is indistinguishable from "no herdr here". The
+    // human surface may ration its own rows; a projection may not ration its facts.
+});
+const { payload } = renderEntwurfPeers(result);
+const projection = { schemaVersion: 1, storeDir, ...payload };
+process.stdout.write(`${JSON.stringify(projection, null, 2)}\n`);

package/mcp/entwurf-bridge/src/index.ts

@@ -65,7 +65,6 @@ import * as process from "node:process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { codexCallerFreshPreflight, codexFreshPreflight } from "../../../pi-extensions/lib/codex-fresh-preflight.ts";
 import { controlSocketPathIn, defaultControlSocketDir } from "../../../pi-extensions/lib/control-socket-path.js";
 import { resolveMailboxReceiverFacts } from "../../../pi-extensions/lib/entwurf-deliverability.ts";
 import { listEntwurfFacts } from "../../../pi-extensions/lib/entwurf-fact-provider.ts";
@@ -80,6 +79,7 @@ import {
 	type VisibleResumeDeps,
 	visibleResume,
 } from "../../../pi-extensions/lib/entwurf-v2-visible-resume.ts";
+import { dispatchFreshCall, renderDispatchedFreshCall } from "../../../pi-extensions/lib/fresh-call-dispatch.ts";
 import {
 	type CodexRequestSender,
 	probeNativeSenderAlive,
@@ -99,7 +99,6 @@ import {
 	readMetaSenderMarker,
 	requireBackend,
 } from "../../../pi-extensions/lib/meta-session.ts";
-import { freshCall, renderFreshCall } from "../../../pi-extensions/lib/mux-fresh-call.ts";
 import { RESUME_CALL_REJECT_HINT, resumeCall } from "../../../pi-extensions/lib/mux-resume-call.ts";
 import { registerNativeConversation } from "../../../pi-extensions/lib/native-push/register.ts";
 
@@ -716,30 +715,32 @@ server.tool(
 // against that answer would call home to a garden id nobody holds.
 server.tool(
 	"entwurf_fresh_call",
-	"Open ONE fresh visible sibling in the operator's tmux and hand it a first task. Five fixed " +
-		"backends only: pi, claude-code, copilot, omp, codex. The sibling's FIRST action is a callback to you carrying a nonce, and the " +
-		"sender envelope of that callback is its garden id — that is how you learn the address of something that " +
-		"did not exist a moment ago. This returns a LAUNCH receipt (tmux window/pane plus that nonce) and nothing " +
-		"else: it does NOT mean the runtime started, the first turn ran, or the task was delivered. Nothing polls " +
-		"for the callback; if it never arrives the window is visible. For EXISTING " +
-		"citizens use entwurf_v2 — this tool only creates, and entwurf_peers only reports. Model is REQUIRED and " +
-		"is passed to the chosen runtime CLI (`provider/model` for pi; model id/alias for Claude Code; a model name " +
-		"or `auto` for copilot; a fuzzy model pattern for omp or codex). Copilot, omp, and codex are refused BEFORE " +
-		"any window opens when their required birth, MCP, receive/delivery, or visible-identity units are absent; " +
-		"Codex also requires the operator-owned default app-server socket, which entwurf never starts. An optional " +
-		"cwd starts the sibling in ONE literal absolute existing directory (cross-repo fresh) — never pick resume " +
-		"for a dormant record's cwd. Omitted/empty cwd means the caller's own directory. " +
-		"An optional placement.tmuxSession is an expert override naming ONE EXISTING session on this agent's own " +
-		"tmux server, and it ALWAYS wins. Omitted, the seat follows the CALLER: a CODEX CALLER opens beside its own " +
-		"TUI pane (matched by thread-id in that pane's title; 0 or 2+ matches REFUSE, never fall back), and every " +
-		"other caller opens in its own session. " +
-		"A missing named session is tmux-session-missing and NOTHING is created. " +
-		"There are no arbitrary command/env knobs. Do not put secrets in the task — model and task argv are visible to " +
-		"same-user processes on this host. Requires that this agent itself runs inside tmux.",
+	"Open ONE fresh visible sibling beside you and hand it a first task. WHERE it opens is decided by where THIS " +
+		"agent runs, never by a parameter: inside herdr (HERDR_ENV=1) it opens a NEW UNFOCUSED TAB in your own " +
+		"herdr workspace, pi and claude-code " +
+		"only; everywhere else it opens in the operator's tmux with all five backends (pi, " +
+		"claude-code, copilot, omp, codex). No fallback: an incomplete herdr context is refused by name, " +
+		"never by a tmux window you cannot see from herdr. The sibling's FIRST action " +
+		"is a callback to you carrying a nonce, whose sender envelope is its garden id — that is how you learn the " +
+		"address of a thing that did not exist a moment ago. This returns a LAUNCH receipt (the owner's " +
+		"coordinates plus that nonce): it does NOT mean the runtime started, the first turn ran, or " +
+		"the task was delivered. Those coordinates are a VIEW, never an address — a herdr tab/pane id can change under " +
+		"a running sibling. Nothing polls. " +
+		"For EXISTING citizens use entwurf_v2 — this tool only creates, and entwurf_peers only reports. Model is REQUIRED and passed to the chosen " +
+		"runtime CLI (`provider/model` for pi, an id/alias for Claude Code, a pattern for the rest). On tmux, copilot/omp/codex are refused BEFORE any window " +
+		"opens when their birth, MCP, receive or visible-identity units are absent, and codex also needs the " +
+		"operator-owned app-server socket entwurf never starts; in herdr they are refused by name first. " +
+		"Optional placement.tmuxSession is a TMUX-ONLY seat naming ONE EXISTING session and " +
+		"ALWAYS wins; omitted, the seat follows the CALLER, never the backend opened: a CODEX CALLER opens beside " +
+		"its own TUI pane, every other caller in its own session; a missing one is tmux-session-missing and " +
+		"NOTHING is created. In herdr the field is refused by name. Do not put secrets in the task — model and task argv are visible to same-user " +
+		"processes.",
 	{
 		backend: z
 			.enum(["pi", "claude-code", "copilot", "omp", "codex"])
-			.describe("Which fixed runtime to open. Only these five; there is no arbitrary command."),
+			.describe(
+				"Which fixed runtime to open. Only these five, and only pi/claude-code when this agent runs inside herdr; there is no arbitrary command.",
+			),
 		model: z
 			.string()
 			.min(1)
@@ -767,7 +768,7 @@ server.tool(
 			.string()
 			.optional()
 			.describe(
-				"Optional literal ABSOLUTE path of an existing directory to start the sibling in (cross-repo fresh). Taken exactly as given — no trim, no realpath, no project-name resolution; '#' is refused (tmux format expansion). Omit or pass \"\" to start where the CALLER is: its own directory, or for a Codex caller its own record directory, because this bridge is the app-server's child and that process's directory is not the caller's. The receipt echoes the directory that was REQUESTED or the caller record it came from, never an observation of where the pane landed.",
+				"Optional literal ABSOLUTE path of an existing directory to start the sibling in (cross-repo fresh). Omit or pass \"\" to start where the CALLER is — this agent's own cwd on BOTH rails, or for a Codex caller its own record directory, because this bridge is the app-server's child and that process's directory is not the caller's. Taken exactly as given: no trim, no realpath, no project-name resolution. '#' is refused on the tmux rail only, because tmux format-expands a start directory; inside herdr it is an ordinary path character. The receipt echoes the directory that was REQUESTED or the caller record it came from, never an observation of where the pane landed.",
 			),
 		placement: z
 			.object({
@@ -779,7 +780,7 @@ server.tool(
 			})
 			.optional()
 			.describe(
-				"Optional expert seat override: open the sibling in ONE EXISTING tmux session of this agent's own server, and it always wins. When omitted the seat follows the CALLER, never the backend being opened: a Codex CALLER opens beside its own TUI pane, matched by thread-id in that pane's terminal title (0 or 2+ matching panes refuse, never fall back); every other caller opens in its own session. A pane title is a placement input only — never an address, liveness or delivery fact. Nothing is ever created. Independent of cwd; neither is inferred from the other. The receipt reports the selected name (absent for the caller-pane rule, which observed a session rather than requesting a name), its source, and resolved target session id.",
+				"Optional expert seat override, TMUX ONLY: open the sibling in ONE EXISTING tmux session of this agent's own server, and it always wins. When omitted the seat follows the CALLER, never the backend being opened: a Codex CALLER opens beside its own TUI pane, matched by thread-id in that pane's terminal title (0 or 2+ matching panes refuse, never fall back); every other caller opens in its own session. A pane title is a placement input only — never an address, liveness or delivery fact. Nothing is ever created. Inside herdr this field is refused by name — placement there belongs to herdr, and a tmux session name would silently place the sibling somewhere else. Independent of cwd; neither is inferred from the other. The receipt reports the selected name (absent for the caller-pane rule, which observed a session rather than requesting a name), its source, and resolved target session id.",
 			),
 	},
 	async ({ backend, model, task, cwd, placement }, extra) => {
@@ -813,22 +814,21 @@ server.tool(
 			callerGardenId = null;
 		}
 		try {
-			// TWO capability axes, in this order, both pre-mutation and neither standing in for
-			// the other. The TARGET axis first — "entwurf cannot open a Codex sibling here at
-			// all" is the more fundamental answer than "and it would not know where to put it".
-			// The CALLER axis second, and only when the seat anchor will actually be consulted:
-			// a codex caller that named an explicit placement never reads a pane title, so
-			// refusing it for a missing `thread-id` would refuse an unused capability.
-			const targetMissing = backend === "codex" ? await codexFreshPreflight(process.env) : null;
-			const callerMissing =
-				targetMissing === null && callerNativeSessionId !== undefined && placement === undefined
-					? codexCallerFreshPreflight(process.env)
-					: null;
-			const missing = targetMissing ?? callerMissing;
-			const result = missing
-				? ({ ok: false, reason: missing } as const)
-				: freshCall({ backend, model, task, cwd, placement, callerGardenId, callerNativeSessionId, callerCwd });
-			const rendered = renderFreshCall(result);
+			// Rail choice, Codex preflight ordering and rendering all live in the composition root,
+			// so this surface and pi's own cannot drift apart on any of them. The two caller-derived
+			// codex inputs ride with the request: the root consults them only on the tmux rail,
+			// which is where #95 lane B/C measured them.
+			const dispatched = await dispatchFreshCall({
+				backend,
+				model,
+				task,
+				cwd,
+				placement,
+				callerGardenId,
+				callerNativeSessionId,
+				callerCwd,
+			});
+			const rendered = renderDispatchedFreshCall(dispatched);
 			return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
 		} catch (err) {
 			return textErr(`entwurf_fresh_call error: ${err instanceof Error ? err.message : String(err)}`);

package/mcp/entwurf-bridge/tsconfig.build.json

@@ -142,6 +142,7 @@
 		"../../scripts/meta-bridge-prune.ts",
 		"../../scripts/meta-bridge-fresh-cut.ts",
 		"../../scripts/meta-facts.ts",
+		"../../scripts/peer-facts.ts",
 		"../../scripts/omp-receive-facts.ts",
 		"../../scripts/codex-socket-path.ts",
 		"../../pi-extensions/meta-bridge-hook.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.22.0",
+	"version": "0.23.1",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for pi, Claude Code, Copilot CLI, OMP, Antigravity, and Codex CLI; Claude and Snowflake Cortex Code ACP backends.",
 	"license": "MIT",
 	"author": {
@@ -73,7 +73,8 @@
 		"CONTRIBUTING.md",
 		"CHANGELOG.md",
 		"!**/__pycache__",
-		"!**/*.pyc"
+		"!**/*.pyc",
+		"!pi-extensions/**/*.test.ts"
 	],
 	"engines": {
 		"node": ">=24.0.0"
@@ -82,7 +83,7 @@
 		"claudeCodeFloor": ">=2.1.217"
 	},
 	"dependencies": {
-		"@agentclientprotocol/claude-agent-acp": "0.76.0",
+		"@agentclientprotocol/claude-agent-acp": "0.79.0",
 		"@agentclientprotocol/sdk": "1.4.0",
 		"@anthropic-ai/sdk": "0.100.1",
 		"@modelcontextprotocol/sdk": "^1.12.1",
@@ -107,7 +108,7 @@
 		"vitest": "4.1.9"
 	},
 	"scripts": {
-		"prepare": "husky 2>/dev/null || true; npm run --silent build-bridge",
+		"prepare": "husky 1>&2 || true; npm run --silent build-bridge 1>&2",
 		"postinstall": "node scripts/postinstall-chmod.cjs",
 		"build-bridge": "bash scripts/with-dist-lock.sh bash scripts/build-bridge.sh",
 		"prepack": "pnpm --silent run build-bridge",
@@ -127,7 +128,6 @@
 		"check-meta-capability-source": "./run.sh check-meta-capability-source",
 		"check-socket-probe": "./run.sh check-socket-probe",
 		"check-project-trust-handler": "./run.sh check-project-trust-handler",
-		"check-entwurf-v2-lock": "./run.sh check-entwurf-v2-lock",
 		"check-model-lock": "./run.sh check-model-lock",
 		"check-dep-versions": "./run.sh check-dep-versions",
 		"check-node-floor-coherence": "./run.sh check-node-floor-coherence",
@@ -135,6 +135,7 @@
 		"check-copilot-birth-hook": "./run.sh check-copilot-birth-hook",
 		"check-copilot-statusline": "./run.sh check-copilot-statusline",
 		"check-copilot-launch": "./run.sh check-copilot-launch",
+		"check-pi-launch": "./run.sh check-pi-launch",
 		"smoke-copilot-statusline-state": "./run.sh smoke-copilot-statusline-state",
 		"smoke-copilot-mcp-state": "./run.sh smoke-copilot-mcp-state",
 		"smoke-omp-bridge-state": "./run.sh smoke-omp-bridge-state",
@@ -173,9 +174,9 @@
 		"check:full": "bash scripts/check-elapsed.sh check:full check:core check:hermetic check:package",
 		"check:core": "pnpm run check:toolchain && pnpm run check:vitest && pnpm run check:contracts",
 		"check:toolchain": "pnpm lint && pnpm typecheck",
-		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface",
-		"check:contracts": "./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-resume-args && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-entwurf-facts && ./run.sh check-control-socket-path && ./run.sh check-socket-discovery && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push",
-		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-meta-hook-session-switch && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-codex-app-server-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-birth-hook && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-usage-accounting && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-gate-manifests && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex && ./run.sh check-codex-bridge-identity && ./run.sh check-codex-birth-hook && ./run.sh smoke-codex-config-state && ./run.sh smoke-codex-birth",
+		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-tests-beside-behavior",
+		"check:contracts": "./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push",
+		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-meta-hook-session-switch && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-pi-launch && ./run.sh check-codex-app-server-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-birth-hook && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-peer-facts && ./run.sh check-herdr-plugin && ./run.sh check-herdr-plugin-profile && ./run.sh check-herdr-plugin-build && ./run.sh check-herdr-runtime-bootstrap && ./run.sh check-herdr-activation && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-usage-accounting && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-typing-call-fence && ./run.sh check-gate-manifests && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex && ./run.sh check-codex-bridge-identity && ./run.sh check-codex-birth-hook && ./run.sh smoke-codex-config-state && ./run.sh smoke-codex-birth && ./run.sh check-herdr-sandbox",
 		"check:package": "./run.sh check-install-surface && ./run.sh smoke-meta-install-state && ./run.sh smoke-agy-install-state && ./run.sh smoke-setup-verdict && ./run.sh check-pack-pin-matcher && ./run.sh check-package-source-routing && ./run.sh check-install-preflight && ./run.sh check-pack"
 	},
 	"pi": {

package/pi-extensions/entwurf-control.ts

@@ -90,6 +90,7 @@ import {
 } from "./lib/compaction-send-guard.js";
 import { CONTROL_SOCKET_SUFFIX, controlSocketPathIn, defaultControlSocketDir } from "./lib/control-socket-path.js";
 import {
+	attachAcceptedSocketDisconnectPolicy,
 	formatSenderInfoBlock,
 	type RpcCommand,
 	type RpcResponse,
@@ -220,7 +221,11 @@ function writeResponse(socket: net.Socket, response: RpcResponse): void {
 	try {
 		socket.write(`${JSON.stringify(response)}\n`);
 	} catch {
-		// Socket may be closed
+		// SYNCHRONOUS throws only — a destroyed stream lands here. This catch CANNOT see an
+		// asynchronous stream error: an EPIPE on a peer that hung up arrives as an `error` event,
+		// and `attachAcceptedSocketDisconnectPolicy`, installed on every accepted connection in
+		// `createServer`, is what carries that half of the contract. Reading this catch as full
+		// coverage is what let a late response kill a resident session.
 	}
 }
 
@@ -841,6 +846,10 @@ async function handleCommand(
 
 async function createServer(pi: ExtensionAPI, state: SocketState, socketPath: string): Promise<net.Server> {
 	const server = net.createServer((socket) => {
+		// FIRST — before setEncoding, before the data handler, and before any response can be
+		// written back. The policy itself (and why this process died without it) lives with the
+		// rest of the wire protocol in lib/entwurf-control-rpc.ts.
+		attachAcceptedSocketDisconnectPolicy(socket);
 		socket.setEncoding("utf8");
 		let buffer = "";
 		socket.on("data", (chunk) => {
@@ -1032,6 +1041,43 @@ function applyEmacsAgentSocketEnv(pi: ExtensionAPI): void {
 	}
 }
 
+/**
+ * The one-line answer to "I installed entwurf, why is nothing here?" (#116 M3-b3 F).
+ *
+ * `[관측: GLG, 날것 PC, 2026-09-17]` a herdr plugin install wires this extension into pi at USER
+ * scope, so it loads in EVERY pi session on the host — but citizenship is argv-gated on purpose, so
+ * a plain `pi` has no garden id, no socket and no tools. From the outside those two facts are
+ * indistinguishable from "the install did nothing", and the operator has no reason to guess at a
+ * flag nobody showed them. This says it once, at exactly the moment they are looking at the wrong
+ * thing.
+ *
+ * UI ONLY, AND THAT IS THE CONTRACT. The refusal path below writes stderr ALWAYS because a control
+ * surface that failed to come up is a durable fault. This is not that: it is an ordinary,
+ * deliberate state. Writing it to stderr would put a sentence into every `pi -p …` pipeline and
+ * every script on the host to tell a human something no human is reading there.
+ *
+ * WHETHER TO SPEAK IS NOT DECIDED HERE. It is `decideUncitizenedNotice` in the self-address fence,
+ * reached by the same non-literal dynamic import as its sibling — and that placement is a repair,
+ * not taste. `[측정 2026-09-17, 독립 검수 + 재현]` while the three conditions were `if`s at this
+ * call site and the gate pinned them with a source regex, two mutants walked through green: moving
+ * the call into the CITIZEN branch, and deleting the once-latch. A regex sees that a call exists;
+ * it cannot see which branch it sits in or how often it fires. So the call is now UNCONDITIONAL and
+ * carries `controlEnabled` as a fact — the branch is gone, and what is left is a truth table.
+ */
+let uncitizenedNoticeShown = false;
+async function noticeUncitizenedSession(ctx: ExtensionContext, controlEnabled: boolean): Promise<void> {
+	const self = (await import(ENTWURF_SELF_ADDRESS_MODULE)) as unknown as EntwurfSelfAddressModule;
+	if (!self.decideUncitizenedNotice({ controlEnabled, hasUI: ctx.hasUI, alreadyShown: uncitizenedNoticeShown })) {
+		return;
+	}
+	uncitizenedNoticeShown = true;
+	ctx.ui.notify(
+		"🪛 entwurf is installed here, but this session is not a garden citizen — start pi with " +
+			"--entwurf-control for a garden id, a control socket and the entwurf tools.",
+		"info",
+	);
+}
+
 function shouldRegisterControlTools(pi: ExtensionAPI): boolean {
 	return pi.getFlag(ENTWURF_FLAG) === true || wasBooleanFlagPassed(ENTWURF_FLAG);
 }
@@ -1106,6 +1152,7 @@ export default function (pi: ExtensionAPI) {
 		// non-control session.
 		applyEmacsAgentSocketEnv(pi);
 		const enabled = pi.getFlag(ENTWURF_FLAG) === true;
+		await noticeUncitizenedSession(ctx, enabled);
 		if (!enabled) {
 			await stopControlServer(state);
 			residentGardenId = null;
@@ -1279,6 +1326,7 @@ type SelfAddressabilityFn = (facts: {
 
 interface EntwurfSelfAddressModule {
 	computeSelfAddressability: SelfAddressabilityFn;
+	decideUncitizenedNotice: (facts: { controlEnabled: boolean; hasUI: boolean; alreadyShown: boolean }) => boolean;
 }
 
 /**
@@ -1371,8 +1419,8 @@ A peer entwurf_peers shows as liveness=alive → fire-and-forget. A citizen with
 (liveness=unsupported) is ALSO fire-and-forget — unsupported means only "no control-socket probe" — and the
 decider picks its own rail: a self-fetch backend (e.g. Claude Code) gets the mailbox, a native-push backend
 (e.g. Antigravity) gets direct injection and has NO mailbox at all. THERE IS A THIRD RESULT: the mailbox
-delivers only to a DELIVERABLE citizen, so a terminated session, or a backend with no adapter here (e.g.
-codex), is mailbox-undeliverable, not queued for an inbox nobody drains. The native-push probe is 3-valued:
+delivers only to a DELIVERABLE citizen, so a terminated self-fetch session is mailbox-undeliverable
+rather than queued for an inbox nobody drains. The native-push probe is 3-valued:
 alive → injected; dead → native-push-target-dead; indeterminate → native-push-probe-indeterminate
 (unestablished ≠ gone). DORMANT IS UNREACHABLE: a socket-domain citizen that is not running gets
 dormant-fire-forget-unsupported — same receiver rule as the mailbox, no active drainer means no
@@ -1530,16 +1578,15 @@ function registerListSessionsTool(pi: ExtensionAPI): void {
 // Tool: entwurf_fresh_call
 // ============================================================================
 
-const MUX_FRESH_CALL_MODULE = "./lib/mux-fresh-call.ts";
-const CODEX_FRESH_PREFLIGHT_MODULE = "./lib/codex-fresh-preflight.ts";
-
-interface CodexFreshPreflightModule {
-	codexFreshPreflight(env: NodeJS.ProcessEnv): Promise<string | null>;
-}
+// ONE dynamic import, and it resolves the composition root rather than a rail: which rail opens
+// the sibling, when the Codex preflight runs, and how the receipt renders are decisions this
+// surface must not own a second copy of (#116 C3). The import stays non-literal-free and lazy for
+// the same startup-fence reason it always was.
+const FRESH_CALL_DISPATCH_MODULE = "./lib/fresh-call-dispatch.ts";
 
-interface MuxFreshCallModule {
-	freshCall(
-		params: {
+interface FreshCallDispatchModule {
+	dispatchFreshCall(
+		request: {
 			backend: "pi" | "claude-code" | "copilot" | "omp" | "codex";
 			model: string;
 			task: string;
@@ -1548,8 +1595,11 @@ interface MuxFreshCallModule {
 			callerGardenId: string | null;
 		},
 		env?: NodeJS.ProcessEnv,
-	): { ok: boolean };
-	renderFreshCall(result: { ok: boolean }): { text: string; isError: boolean };
+	): Promise<{ rail: "herdr" | "tmux"; result: { ok: boolean } }>;
+	renderDispatchedFreshCall(dispatched: { rail: "herdr" | "tmux"; result: { ok: boolean } }): {
+		text: string;
+		isError: boolean;
+	};
 }
 
 /**
@@ -1570,27 +1620,25 @@ function registerFreshCallTool(pi: ExtensionAPI): void {
 	registerTool({
 		name: "entwurf_fresh_call",
 		label: "Open Fresh Sibling",
-		description: `Open ONE fresh visible sibling in the operator's tmux and hand it a first task. Five fixed
-backends only: pi, claude-code, copilot, omp, codex. The sibling's FIRST action is a callback to you carrying a nonce, and the
-sender envelope of that callback is its garden id — that is how you learn the address of something that did
-not exist a moment ago. This returns a LAUNCH receipt (tmux window/pane plus that nonce) and nothing else:
-it does NOT mean the runtime started, the first turn ran, or the task was delivered. Nothing polls for the
-callback; if it never arrives the window is visible and can be read directly. For EXISTING citizens use
-entwurf_v2 — this tool only creates, and entwurf_peers only reports. Model is REQUIRED and passed to the
-chosen runtime CLI (provider/model for pi; model id/alias for Claude Code; a Copilot, OMP, or Codex model
-name). Copilot, omp, and codex are refused BEFORE any window opens when their required birth, MCP,
-receive/delivery, or visible-identity units are absent. Codex additionally requires the operator-owned
-default app-server socket; entwurf never starts or supervises it. An optional cwd starts the
-sibling in ONE literal absolute existing directory (cross-repo fresh) — never pick resume for a dormant
-record's cwd; resume is continuity-only. Omitted/empty cwd means the caller's own directory. An optional
-placement.tmuxSession is an expert override naming ONE EXISTING session on this agent's own tmux server and
-ALWAYS wins. Omitted, the seat follows the CALLER, never the backend being opened: every caller on this
-surface opens in its own session. A missing named session is tmux-session-missing and NOTHING is created. There are no
-arbitrary command/env knobs. Do not put secrets in the task — model and task argv are visible to same-user
-processes on this host.`,
+		description: `Open ONE fresh visible sibling beside you and hand it a first task. WHERE it opens is decided by
+where THIS agent runs, never by a parameter: inside herdr (HERDR_ENV=1) it opens a NEW UNFOCUSED TAB in your own
+herdr workspace and only pi and claude-code may be opened; everywhere else it opens in the operator's tmux with all five backends (pi, claude-code,
+copilot, omp, codex). There is no fallback — an incomplete herdr context is refused by name rather than opening a tmux
+window you cannot see from in herdr. The sibling's FIRST action is a callback to you carrying a nonce, whose sender
+envelope is its garden id — that is how you learn the address of a thing that did not exist a moment ago. This returns
+a LAUNCH receipt (the owner's coordinates plus that nonce) and nothing else: it does NOT mean the runtime started, the
+first turn ran, or the task was delivered. Those coordinates are a VIEW, never an address — a herdr tab/pane id can
+change under a running sibling. Nothing polls; if the callback never arrives the tab is visible. For EXISTING citizens use entwurf_v2 — this tool only creates, and entwurf_peers only reports. Model is REQUIRED and passed to the chosen runtime CLI (provider/model for pi, an id/alias for Claude Code, a name or pattern
+for the rest). On tmux, copilot/omp/codex are refused BEFORE any window opens when their birth, MCP, receive or
+visible-identity units are absent, and codex also needs the operator-owned app-server socket entwurf never starts; in
+herdr those three are refused by name first. Optional
+placement.tmuxSession is a TMUX-ONLY seat naming ONE EXISTING session and ALWAYS wins; omitted, the seat
+follows the CALLER, and on this surface that is always your own session — a missing one is
+tmux-session-missing and NOTHING is created. In herdr the field is refused by name. Do not put secrets in the task — model and task argv are visible to same-user processes.`,
 		parameters: Type.Object({
 			backend: StringEnum(["pi", "claude-code", "copilot", "omp", "codex"], {
-				description: "Which fixed runtime to open. Only these five; there is no arbitrary command.",
+				description:
+					"Which fixed runtime to open. Only these five, and only pi/claude-code when this agent runs inside herdr; there is no arbitrary command.",
 			}),
 			model: Type.String({
 				minLength: 1,
@@ -1608,7 +1656,7 @@ processes on this host.`,
 			cwd: Type.Optional(
 				Type.String({
 					description:
-						"Optional literal ABSOLUTE path of an existing directory to start the sibling in (cross-repo fresh). Omit or pass \"\" to start in this agent's own cwd. Taken exactly as given — no trim, no realpath, no project-name resolution; '#' is refused (tmux format expansion). The receipt echoes what was REQUESTED, never an observation.",
+						"Optional literal ABSOLUTE path of an existing directory to start the sibling in (cross-repo fresh). Omit or pass \"\" to start in this agent's own cwd — on BOTH rails. Taken exactly as given: no trim, no realpath, no project-name resolution. '#' is refused on the tmux rail only, because tmux format-expands a start directory; inside herdr it is an ordinary path character. The receipt echoes what was REQUESTED, never an observation.",
 				}),
 			),
 			placement: Type.Optional(
@@ -1621,7 +1669,7 @@ processes on this host.`,
 					},
 					{
 						description:
-							"Optional expert seat override: open the sibling in ONE EXISTING tmux session of this agent's own server, and it always wins. When omitted the seat follows the CALLER, never the backend being opened: every caller on THIS surface opens in its own session (a pi session is never a Codex citizen, so the Codex caller-pane rule the MCP bridge carries cannot arise here). Nothing is ever created. Independent of cwd; neither is inferred from the other. The receipt reports the selected name, its source, and resolved target session id.",
+							"Optional expert seat override, TMUX ONLY: open the sibling in ONE EXISTING tmux session of this agent's own server, and it always wins. When omitted the seat follows the CALLER, never the backend being opened: every caller on THIS surface opens in its own session (a pi session is never a Codex citizen, so the Codex caller-pane rule the MCP bridge carries cannot arise here). Nothing is ever created. Inside herdr this field is refused by name — placement there belongs to herdr, and a tmux session name would silently place the sibling somewhere else. Independent of cwd; neither is inferred from the other. The receipt reports the selected name, its source, and resolved target session id.",
 					},
 				),
 			),
@@ -1640,29 +1688,20 @@ processes on this host.`,
 			_ctx: ExtensionContext,
 		) {
 			try {
-				const mux = (await import(MUX_FRESH_CALL_MODULE)) as unknown as MuxFreshCallModule;
-				// ONE input object for ONE composition call. The codex branch differs only by the
-				// capability preflight that must answer BEFORE any mutation; duplicating the call
-				// would put the caller-identity contract in two places, which is how a mutant that
-				// plants a defect in one of them survives on the other.
-				const call = {
+				const dispatch = (await import(FRESH_CALL_DISPATCH_MODULE)) as unknown as FreshCallDispatchModule;
+				// ONE input object for ONE dispatch call. Rail selection and the Codex preflight
+				// ordering live behind it: duplicating either here would put the same decision in
+				// two places, which is how a mutant that plants a defect in one of them survives
+				// on the other.
+				const dispatched = await dispatch.dispatchFreshCall({
 					backend: params.backend,
 					model: params.model,
 					task: params.task,
 					cwd: params.cwd,
 					placement: params.placement,
 					callerGardenId: residentGardenId,
-				};
-				const result =
-					params.backend === "codex"
-						? await (async () => {
-								const preflight = (await import(CODEX_FRESH_PREFLIGHT_MODULE)) as unknown as CodexFreshPreflightModule;
-								const missing = await preflight.codexFreshPreflight(process.env);
-								if (missing) return { ok: false as const, reason: missing };
-								return mux.freshCall(call);
-							})()
-						: mux.freshCall(call);
-				const rendered = mux.renderFreshCall(result);
+				});
+				const rendered = dispatch.renderDispatchedFreshCall(dispatched);
 				return {
 					content: [{ type: "text", text: rendered.text }],
 					isError: rendered.isError,