@junghanacs/entwurf 0.12.8 → 0.12.10

package/pi-extensions/entwurf-control.ts

@@ -61,7 +61,7 @@
  *    Send-is-throw cleanup; see note above.)
  */
 
-import { existsSync, promises as fs, readFileSync } from "node:fs";
+import { existsSync, promises as fs } from "node:fs";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -108,9 +108,10 @@ const SESSION_MESSAGE_TYPE = "entwurf-message";
 // with the receive-side [entwurf received ⟵] box. The provider-level context
 // filter in index.ts drops this customType before the LLM sees it — colocated
 // with the emitter so sessions without --entwurf-control are still protected.
-// Layer A (native path) reuses the same Box builder via renderSentMessage() but
-// does NOT emit a CustomMessage; the native tool result already lives in the
-// toolResult role and never enters LLM context as a user message.
+// There is no second emitter: the v1 native send path ("Layer A") that also drew
+// this box through renderSentMessage() was removed in the 0.12 cutover, and
+// renderSentMessage is now registered for exactly one customType (see
+// registerMessageRenderer below). Do not describe a native sender-side box.
 const SENDER_INFO_PATTERN = /<sender_info>[\s\S]*?<\/sender_info>/g;
 
 // ============================================================================
@@ -509,8 +510,8 @@ const renderSessionMessage: MessageRenderer = (message, { expanded }, theme) =>
 };
 
 // Sender-side payload — what renderSentMessage needs to draw the [entwurf sent →]
-// box. Carried verbatim by both Layer A (native renderResult) and Layer B
-// (CustomMessage details for ACP path). All four envelope fields are intentionally
+// box. Carried by the ACP path's CustomMessage `details` — the ONLY carrier since
+// the v1 native renderResult path was removed (0.12 cutover). All four envelope fields are intentionally
 // echoed in the box even though the sender is "this same session" — operators
 // reading a busy multi-session transcript should be able to verify at a glance
 // which 담당자 is on the wire (cwd) and which model identity (agentId) actually
@@ -520,12 +521,13 @@ const renderSessionMessage: MessageRenderer = (message, { expanded }, theme) =>
 // re-renders (resize, expand toggle) keep showing the moment the message was
 // actually delivered rather than drifting forward to "now".
 //
-// wants_reply mirrors the receive-side etiquette badge. Native schema does not
-// yet expose it (see registerSessionTool's entwurfSendParameters); leave undefined
-// from the native call site until the schema grows the field.
+// wants_reply mirrors the receive-side etiquette badge. It stays optional because
+// the box is drawn from a CustomMessage whose `details` may predate the field; the
+// v1 `registerSessionTool` / `entwurfSendParameters` schema this note used to point
+// at is gone (0.12 cutover), so there is no native call site left to grow.
 interface SentBoxData {
 	to: string; // target sessionId
-	from?: string; // sender agentId, e.g. "entwurf/claude-opus-4-8"
+	from?: string; // sender agentId, e.g. "entwurf/claude-opus-5"
 	cwd?: string; // sender cwd (raw, abbreviateHome applied at render)
 	timestamp?: string; // ISO 8601 UTC; rendered in KST
 	mode?: string; // "steer" | "follow_up" | string passed through
@@ -1274,9 +1276,18 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		target: Type.String({ description: "Target garden id (use entwurf_peers to discover)" }),
 		intent: StringEnum(["fire-and-forget", "owned-outcome"] as const, {
 			description:
-				"fire-and-forget = send/reply/hand-off to a LIVE or meta-session target (set wants_reply for an answer); " +
-				"owned-outcome = wake a DORMANT pi via spawn-bg resume ONLY — on a live target it is rejected " +
-				"(owned-live-no-autosend) and never auto-converted",
+				"fire-and-forget = send/reply/hand-off to a LIVE socket target (currently backend pi) or to any " +
+				"citizen with no socket liveness — the decider picks that citizen's rail, and a rail can also " +
+				"REJECT: self-fetch (e.g. Claude Code) → meta-bridge mailbox while that mailbox is DELIVERABLE, " +
+				"else rejected as mailbox-undeliverable; native-push (e.g. Antigravity) → direct injection into " +
+				"its live conversation, which has NO mailbox, and its probe is three-valued — alive: injected, " +
+				"dead: native-push-target-dead, indeterminate: native-push-probe-indeterminate (two rejects, " +
+				"not one). " +
+				"Set wants_reply for an answer. " +
+				"owned-outcome = wake a DORMANT socket-domain citizen via spawn-bg resume ONLY — on a live target " +
+				"rejected as owned-live-no-autosend, on self-fetch as backend-liveness-unsupported, on " +
+				"native-push as native-push-no-resume-authority (both lack resume authority, but the reasons " +
+				"differ because native-push IS probe-measured), and never auto-converted",
 		}),
 		message: Type.String({
 			description:
@@ -1285,7 +1296,9 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		}),
 		mode: Type.Optional(
 			StringEnum(["steer", "follow_up"] as const, {
-				description: "Delivery mode for a live send: steer (immediate) or follow_up (after task)",
+				description:
+					"Injection style for a CONTROL-SOCKET send only: steer (immediate) or follow_up (after task). " +
+					"The mailbox, native-push, and spawn-bg plans carry no mode, so it has no effect on those rails.",
 			}),
 		),
 		wants_reply: Type.Optional(Type.Boolean({ description: "Human-conversation reply hint (default false)" })),
@@ -1299,6 +1312,11 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		wants_reply?: boolean;
 	};
 
+	// TS2589 ("type instantiation is excessively deep") workaround: pi's registerTool
+	// generic infers the handler signature from the TypeBox schema, and this schema is
+	// deep enough to blow the instantiation budget. Casting the FUNCTION (not the
+	// argument) keeps the schema itself typed while stopping the inference walk.
+	// Revisit when pi's registerTool takes an explicit params type parameter.
 	const registerTool = pi.registerTool as (def: any) => void;
 
 	registerTool({
@@ -1306,28 +1324,51 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		label: "Dispatch (v2)",
 		description: `CANONICAL delivery surface for a garden id. When you have a garden id and want to
 reach whoever it names — message / reply / hand-off — use THIS verb. A garden id alone does not
-reveal whether the target is a live pi session, a dormant pi session, or a Claude Code meta-session,
+reveal which rail that citizen answers on — a live socket session, a dormant one, a mailbox-backed
+self-fetch session, or a native-push session —
 and entwurf_v2 is the one surface that reads that and routes correctly (so "when unsure which
 transport, use entwurf_v2"). It dispatches to EXISTING targets; brand-new sibling creation is deferred
 to a later v2 lane. Dispatch to a garden citizen through the unified entwurf_v2 verb: the 5b decider
-picks the transport (live control-socket send / spawn-bg resume / meta-mailbox enqueue) from the
-target's liveness + your intent, runs it under the v2 lock policy (pi paths take a per-target lock;
-the mailbox path is lock-free, guarded by active-receiver deliverability), and reports one outcome
-(delivered / rejected / lock-retained / delivered-but-lock-dirty).
+picks the transport (live control-socket send / spawn-bg resume / meta-mailbox enqueue / native-push
+direct injection) from the target's liveness + your intent, runs it under the v2 lock policy, and reports
+one outcome (delivered / rejected / lock-retained / delivered-but-lock-dirty).
+
+LOCK POLICY (do not over-generalize it): the per-target lock is taken for a control-socket-DOMAIN
+dispatch, which is BOTH the live send AND the dormant cell's spawn-bg resume — spawn-bg is a separate
+relaunch transport yet it still runs under that domain's lock. The mailbox and native-push rails are
+lock-free: the mailbox is guarded instead by active-receiver deliverability, and native-push by its
+adapter probe.
 
 - target: the garden id of the citizen to reach (required).
 - intent: fire-and-forget (a send with no owned result) or owned-outcome (you own the result).
 - message: the message/prompt to dispatch (required).
-- mode: steer or follow_up for a live send (optional).
-- wants_reply: reply hint for a live send (optional, default false).
+- mode: steer or follow_up for a CONTROL-SOCKET send (optional). The mailbox, native-push, and
+  spawn-bg plans carry no mode, so it has no effect on those rails — a native-push send IS live and
+  still ignores it.
+- wants_reply: reply hint; it rides every rail (optional, default false).
 
 CHOOSING INTENT (picking wrong is rejected, never auto-fixed): to message / reply / hand off a peer
-that entwurf_peers shows as liveness=alive (a live pi citizen), use intent: fire-and-forget
-— it routes to the live control-socket; set wants_reply:true if you need an answer (wants_reply is NOT
-owned-outcome). For a meta-session (liveness=unsupported, e.g. Claude Code), replies are ALSO
-fire-and-forget (→ mailbox). owned-outcome is ONLY for waking a DORMANT pi citizen (spawn-bg resume);
-on a live target it is rejected as owned-live-no-autosend, on an unsupported backend as
-backend-liveness-unsupported, and is NEVER auto-converted — so pick the right intent up front.
+that entwurf_peers shows as liveness=alive (a live socket citizen, currently backend pi), use intent:
+fire-and-forget — it routes to the live control-socket; set wants_reply:true if you need an answer
+(wants_reply is NOT owned-outcome). Replies to a citizen with NO socket liveness
+(liveness=unsupported) are ALSO fire-and-forget, and the decider picks that citizen's own rail: a
+self-fetch backend (e.g. Claude Code) gets the meta-bridge mailbox, while a native-push backend
+(e.g. Antigravity) gets direct injection into its live conversation and has NO mailbox at all — do
+not assume mailbox semantics for every unsupported citizen. A native-push target IS measured by its
+own adapter probe, and that probe is THREE-valued, so the send is never silently queued: alive →
+injected; dead → rejected as native-push-target-dead; indeterminate → rejected as
+native-push-probe-indeterminate. Those last two stay separate on purpose — "we could not establish
+it" is not "it is gone". THERE IS A THIRD RESULT, so do not read
+liveness=unsupported as "reachable by some rail": the mailbox path delivers only to a DELIVERABLE
+citizen (a self-fetch backend whose receiver is live and armed), so a terminated Claude Code session —
+and any record whose backend has no adapter on this lane, e.g. codex — is rejected as
+mailbox-undeliverable rather than queued into an inbox nobody drains. unsupported means only "this
+backend has no control-socket probe".
+owned-outcome is ONLY for waking a DORMANT socket-domain citizen (spawn-bg resume, currently backend
+pi); on a live target it is rejected as owned-live-no-autosend. Neither self-fetch nor native-push
+has resume authority, but they reject under DIFFERENT reasons — self-fetch as
+backend-liveness-unsupported, native-push as native-push-no-resume-authority.
+It is NEVER auto-converted — so pick the right intent up front.
 
 The decider — not this surface — chooses the transport.`,
 		parameters: entwurfV2Parameters,
@@ -1396,7 +1437,7 @@ The decider — not this surface — chooses the transport.`,
 
 interface EntwurfFactProviderModule {
 	listEntwurfFacts(params: {
-		metaEntries: readonly string[];
+		metaEntries: readonly { filename: string; regularFile: boolean }[];
 		readRecord: (filename: string) => string;
 		socket: { dir: string };
 	}): Promise<unknown>;
@@ -1408,22 +1449,22 @@ interface EntwurfPeersRenderModule {
 
 interface MetaSessionModule {
 	defaultMetaSessionsDir(): string;
+	readActiveStoreEntries(dir: string): { filename: string; regularFile: boolean }[];
+	makeStoreRecordReader(dir: string): (filename: string) => string;
 }
 
 async function renderEntwurfPeersForSurface(): Promise<{ text: string; payload: unknown }> {
 	const meta = (await import(META_SESSION_MODULE)) as unknown as MetaSessionModule;
 	const sessionsDir = meta.defaultMetaSessionsDir();
-	let metaEntries: string[] = [];
-	try {
-		metaEntries = (await fs.readdir(sessionsDir)).filter((name) => name.endsWith(".meta.json"));
-	} catch (err) {
-		if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") throw err;
-	}
-
+	// Entries carry their KIND. The name-only readdir this used to do left `readRecord`
+	// free to follow a symlinked `.meta.json` into bytes the store does not own — rule 1
+	// held in the doctor and not on the surface operators actually read (pre-existing;
+	// surfaced by the #52 duplicate pass, which would let such a symlink quarantine the
+	// healthy record it shadowed).
 	const provider = (await import(ENTWURF_FACT_PROVIDER_MODULE)) as unknown as EntwurfFactProviderModule;
 	const result = await provider.listEntwurfFacts({
-		metaEntries,
-		readRecord: (filename) => readFileSync(path.join(sessionsDir, filename), "utf8"),
+		metaEntries: meta.readActiveStoreEntries(sessionsDir),
+		readRecord: meta.makeStoreRecordReader(sessionsDir),
 		// Same socket axis as the legacy live-session scan, but merged with the
 		// meta-record rail by listEntwurfFacts so meta-mailbox citizens are discoverable too.
 		socket: { dir: ENTWURF_DIR },
@@ -1433,8 +1474,9 @@ async function renderEntwurfPeersForSurface(): Promise<{ text: string; payload:
 }
 
 function registerListSessionsTool(pi: ExtensionAPI): void {
-	// Same TS2589 workaround as registerSessionTool — see the comment block
-	// in that function for the revisit conditions.
+	// Same TS2589 workaround as registerEntwurfV2Tool — see the comment block there
+	// for the revisit conditions. (It used to point at registerSessionTool, which was
+	// removed in the 0.12 cutover, so the pointer dangled.)
 	const registerTool = pi.registerTool as (def: any) => void;
 	registerTool({
 		name: "entwurf_peers",

package/pi-extensions/lib/acp/models.ts

@@ -18,14 +18,14 @@
 // Why `/compat` and NOT the 0.80 provider-factory subpath (the pi-ai
 // providers/anthropic subpath): this file is loaded by pi's
 // EXTENSION loader (pi-coding-agent `core/extensions/loader.ts`), whose jiti
-// alias map resolves ONLY three pi-ai specifiers for extensions — the bare root,
-// `/compat`, and `/oauth` — all to `ai/dist/compat.js`. A `providers/*` subpath
-// is NOT in that map: jiti prefix-matches the bare `@earendil-works/pi-ai` alias
-// and appends the remainder, yielding the unresolvable
-// `…/dist/compat.js/providers/anthropic` (verified live: extension load crash,
-// invisible to static typecheck which resolves against node_modules `exports`).
-// So `/compat` is the SINGLE sanctioned extension entrypoint for the old global
-// model-catalog API, and the SINGLE allowlisted exception in
+// alias map resolves FOUR pi-ai specifiers for extensions — the bare root,
+// `/compat`, `/oauth`, and (since pi 0.81) `/providers/all`. Other `providers/*`
+// subpaths are NOT in that map: jiti prefix-matches the bare
+// `@earendil-works/pi-ai` alias and appends the remainder, yielding the
+// unresolvable `…/dist/compat.js/providers/anthropic` (verified live: extension
+// load crash, invisible to static typecheck which resolves against node_modules
+// `exports`). So `/compat` remains the SINGLE sanctioned extension entrypoint
+// this repo uses for the old global model-catalog API, and the SINGLE allowlisted exception in
 // `run.sh check-pi-import-surface`. `getModels` here is compat's deprecated
 // re-export of `getBuiltinModels`. When pi removes compat we migrate to whatever
 // the loader then exposes.
@@ -50,13 +50,13 @@ export const ENTWURF_ACP_NO_AUTH_SENTINEL = "entwurf-no-auth";
 // both axes (protocol smoke + agent interview) — do not extend casually.
 // Exported so the claude backend adapter (backend-adapter.ts) can answer
 // `routeModel` without re-deriving the set from curatedClaudeModels().
-export const SUPPORTED_ANTHROPIC_MODEL_IDS = ["claude-sonnet-5", "claude-opus-4-8"] as const;
+export const SUPPORTED_ANTHROPIC_MODEL_IDS = ["claude-sonnet-5", "claude-opus-5"] as const;
 
 /** The anchor model whose absence is a hard registry regression, not a soft skip. */
-export const CURATED_ANCHOR_MODEL_ID = "claude-opus-4-8";
+export const CURATED_ANCHOR_MODEL_ID = "claude-opus-5";
 
-// Anthropic's registry reports 1M for both Sonnet 5 and Opus 4.8, and the
-// entwurf surface now exposes the full 1M for BOTH. Sonnet 5's 1M window is the
+// Anthropic's registry reports 1M for both Sonnet 5 and Opus 5, and the
+// entwurf surface exposes the full 1M for BOTH. Sonnet 5's 1M window is the
 // whole point of the 0.12.3 bump — it is the compact-free long-context floor the
 // earlier 200K Sonnet cap could not provide. We still clamp to a 1M ceiling so a
 // future registry value can't silently inflate the surface past what we verify.

package/pi-extensions/lib/acp/overlay.ts

@@ -9,9 +9,11 @@
 // operator entries a backend needs (credentials, caches, built-in skills)
 // reachable through a TIGHT symlink whitelist — nothing else.
 //
-// Scope (NEXT §스코프 / §S2-scout 핀3): Claude-only on this lane. Codex/Gemini
-// overlays (CODEX_HOME / admin.toml) are 0.11.0 behavior-oracle territory and
-// out of scope — the bridge backends are not in v2 yet.
+// Scope (NEXT §스코프 / §S2-scout 핀3): Claude-only on this lane. Claude is the one
+// shipped ACP backend, so this materializer is written for its config surface alone.
+// Codex/Gemini overlays (CODEX_HOME / admin.toml) are behavior-oracle territory and
+// out of scope here; a SECOND ACP backend enters only once the entry conditions in
+// docs/acp-backend-rail.md are met, and it brings its own overlay.
 //
 // Two deliberate divergences from the literal 0.11.0 illustrative comment block
 // (the 0.11.0 CODE already does both — only its top doc-comment drew projects/

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

@@ -1,14 +1,29 @@
 /**
  * entwurf-core — sync entwurf execution, host-agnostic.
  *
- * Single implementation shared by:
- *   - pi-extensions/entwurf.ts (pi native tool surface)
- *   - mcp/entwurf-bridge/src/index.ts (MCP tool surface for ACP hosts)
+ * DIRECT importers, MEASURED from the import graph (2026-07-27) — not from memory:
+ *   - pi-extensions/entwurf-control.ts (the pi adapter)
+ *   - pi-extensions/lib/entwurf-v2-spawn-production.ts (v2 spawn-bg launch identity)
+ *   - pi-extensions/lib/project-trust-handler.ts · lib/acp/augment.ts ·
+ *     lib/native-push/adapter.ts
+ *   - plus gates/smokes (check-shell-quote, check-package-source-routing, …)
+ *
+ * The MCP bridge is a TRANSITIVE consumer, not a direct one, and the distinction is the
+ * whole point: `mcp/entwurf-bridge/src/index.ts → entwurf-v2-surface.ts →
+ * entwurf-v2-production.ts → entwurf-v2-spawn-production.ts → entwurf-core.ts`. So the old
+ * header's claim — that the bridge imports this shared implementation the way a v1 tool
+ * surface did — was false, but so is "the bridge does not reach it": it reaches it at
+ * runtime, only for spawn-bg production.
+ *
+ * NOT consumers on any path: `pi-extensions/entwurf.ts` (the v1 pi native tool surface) and
+ * `pi-extensions/lib/entwurf-async.ts` were REMOVED in the 0.12 cutover. Do not reintroduce
+ * either as a live consumer.
  *
  * This module MUST NOT import anything from @earendil-works/pi-coding-agent or any
- * other pi runtime API. It is pure Node + @sinclair/typebox-free.  Anything that
- * requires pi's ExtensionAPI (sendMessage, appendEntry, sessionManager) belongs
- * in the async entwurf path, which stays in pi-extensions/entwurf.ts for now.
+ * other pi runtime API. It is pure Node + @sinclair/typebox-free. Anything that
+ * requires pi's ExtensionAPI (sendMessage, appendEntry, sessionManager) belongs to a
+ * pi-adapter surface, never here — the v1 async entwurf path that used to hold that
+ * work went away with `pi-extensions/entwurf.ts`.
  *
  * Scope:
  *   - sync execution (spawn pi, collect message_end events, return summary)
@@ -67,9 +82,11 @@ const PI_SETTINGS_PATH = process.env.PI_SETTINGS_PATH
 	: path.join(AGENT_DIR, "settings.json");
 export const ENTWURF_CODEX_ACP_ENV = "ENTWURF_ACP_FOR_CODEX";
 
-// Currently unused: remote/SSH entwurf is fail-fast in 0.9.0 (garden-native
-// identity is local-FS only). Retained for #11 remote revival; parity-gated by
-// scripts/check-shell-quote.ts across entwurf.ts / entwurf-core.ts / entwurf-async.ts.
+// Currently unused: remote/SSH entwurf is fail-fast (garden-native identity is
+// local-FS only). Retained for #11 remote revival and pinned by
+// scripts/check-shell-quote.ts, whose SOURCE_SITES is now THIS FILE ALONE — the
+// entwurf.ts / entwurf-async.ts halves of that former parity check were removed
+// with those files, so there is no cross-file parity left to assert.
 // biome-ignore lint/correctness/noUnusedVariables: retained for #11 remote revival; parity-gated.
 function shellQuote(value: string): string {
 	return `'${value.replace(/'/g, `'\\''`)}'`;

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

@@ -18,9 +18,10 @@
  *    drains its own inbox on wake. A DIRECT-INJECT backend (pi / codex / antigravity)
  *    has no mailbox drain at all — enqueuing for it is the SE-1 false success
  *    ("✓ delivered" into a void). So deliverable = wakeMode === "self-fetch" AND the
- *    receiver is active. This is the guard that the v1 fallback, MCP v1, pi-native v1,
- *    and the v2 decider/send-fallback enqueue sites must all pass before writing a
- *    .msg (slice 2d).
+ *    receiver is active. Every enqueue site must pass this guard before writing a .msg
+ *    (slice 2d). The shipped sites are the v2 decider and its send-fallback re-resolve;
+ *    the v1 fallback / MCP v1 / pi-native v1 sites this once also listed were removed in
+ *    the 0.12 cutover — do not read them as live.
  *
  *  - nativePushDeliverable(facts): the SEPARATE deliverability predicate for a
  *    NATIVE-PUSH backend (antigravity). A native-push citizen has no mailbox and no
@@ -89,9 +90,12 @@ export interface ReceiverIdentityFacts {
  * Does this presence marker actually belong to the target identity? A marker that is
  * absent, or whose garden id / backend / native session id has drifted from the record,
  * is NOT this receiver — fail-closed (a stale/foreign marker must never raise a dead
- * target to "active"). The single source of truth for "marker ↔ identity match" shared
- * by the v1 mailbox guard (gatherMailboxDeliverabilityFacts) and the v2 production
- * `mailboxDeliverabilityFor` seam, so the two paths cannot drift to different meanings.
+ * target to "active"). The single source of truth for "marker ↔ identity match". Its
+ * PRODUCTION consumers are the v2 `mailboxDeliverabilityFor` seam and the MCP bridge's
+ * `entwurf_self`. There is no second implementation: `entwurf-mailbox-guard.ts` used to
+ * wrap this atom with its own enqueue orchestration, had ZERO production importers (import
+ * graph measured 2026-07-27), and was DELETED rather than left as a green gate proving only
+ * retired behaviour. A new enqueue site consults this predicate through that seam.
  */
 export function receiverMarkerMatchesIdentity(
 	marker: ReceiverIdentityFacts | null | undefined,

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

@@ -5,8 +5,8 @@
  * (one-way: provider → facts / socket-discovery / meta-session) — no import cycle
  * with `entwurf-facts.ts` (which owns `SocketProbe`/`resolveFactList`).
  *
- *   listAllMetaIdentities → pi gid 추출 → scanSocketProbes(piGids)
- *     → pre-quarantine non-pi/socket conflicts → resolveFactList(clean)
+ *   listAllMetaIdentities → socket-domain gid extraction → scanSocketProbes
+ *     → pre-quarantine out-of-domain/socket conflicts → resolveFactList(clean)
  *     → { facts, diagnostics }
  *
  * Two throw-vs-diagnostics policies, kept distinct (GPT힣 C-원칙):
@@ -20,16 +20,21 @@
  *     — that is not a re-implementation of the collision rule, it is input
  *     sanitation that leaves the pure-core invariant intact.
  *
- * The non-pi+socket collision quarantines BOTH sides (the PeerFact AND the
- * socket): gardenId is the universal address and a send path reads the socket
+ * An out-of-socket-domain record/socket collision quarantines BOTH sides (the
+ * PeerFact AND the socket): gardenId is the universal address and a send path
  * first, so surfacing the record alone (as a clean `unsupported` PeerFact) while
  * a same-gid socket exists would be half a lie. Both leave the normal output;
  * one diagnostic carries the fact. (pi + same-gid socket = the normal merge.)
  */
 
-import { type FactList, isNonPiGardenIdSocketConflict, resolveFactList } from "./entwurf-facts.ts";
+import { type FactList, isOutOfSocketDomainGardenIdConflict, resolveFactList } from "./entwurf-facts.ts";
 import { isLivenessSupported } from "./entwurf-v2-contract.ts";
-import { FRESH_CUT_PRESCRIPTION, listAllMetaIdentities, type MetaCitizenBackend } from "./meta-session.ts";
+import {
+	type ActiveStoreEntry,
+	FRESH_CUT_PRESCRIPTION,
+	listAllMetaIdentities,
+	type MetaCitizenBackend,
+} from "./meta-session.ts";
 import { type SocketScanDeps, scanSocketProbes } from "./socket-discovery.ts";
 import type { SocketLiveness } from "./socket-probe.ts";
 
@@ -82,7 +87,9 @@ export interface EntwurfFactsResult {
 
 export interface EntwurfFactsDeps {
 	/** Meta-store axis: the `.meta.json` entry names + a record reader. */
-	metaEntries: readonly string[];
+	/** Store entries WITH their kind (`readActiveStoreEntries`), never bare names: the
+	 * listing must be able to refuse a symlinked record without following it. */
+	metaEntries: readonly ActiveStoreEntry[];
 	readRecord: (filename: string) => string;
 	/** Socket axis: injected into scanSocketProbes (controlDir/readdir/probe). */
 	socket?: Partial<SocketScanDeps>;
@@ -123,8 +130,8 @@ export async function listEntwurfFacts(deps: EntwurfFactsDeps): Promise<EntwurfF
 	// 2. socket axis — probe (dir sockets) ∪ (in-domain citizen canonical paths).
 	//    Its three hazards (symlink forgery / malformed name / dir-read error) are
 	//    folded into diagnostics here so the listing survives but never lies.
-	const piGids = identities.filter((i) => isLivenessSupported(i.backend)).map((i) => i.gardenId);
-	const scan = await scanSocketProbes(piGids, deps.socket ?? {});
+	const socketDomainGids = identities.filter((i) => isLivenessSupported(i.backend)).map((i) => i.gardenId);
+	const scan = await scanSocketProbes(socketDomainGids, deps.socket ?? {});
 	const probes = scan.probes;
 	const socketGids = new Set(probes.map((p) => p.gardenId));
 	const symlinkedGids = new Set(scan.symlinkedGardenIds);
@@ -151,24 +158,22 @@ export async function listEntwurfFacts(deps: EntwurfFactsDeps): Promise<EntwurfF
 		});
 	}
 
-	// 3. pre-quarantine non-pi citizens that collide with a control socket. The
-	//    predicate is SHARED with the v2 decider (isNonPiGardenIdSocketConflict) so
-	//    listing and dispatch cannot drift, and it unions socketGids with the
-	//    symlinkedGids: a symlinked socket is never probed (absent from socketGids),
-	//    so the old socketGids-only check let a non-pi citizen with a forged
-	//    (symlinked) socket survive as a clean PeerFact while the legacy send path
-	//    still followed the symlink — the gap this closes.
+	// 3. Pre-quarantine citizens outside the control-socket capability domain that
+	//    collide with a control socket. The predicate is SHARED with v2 dispatch so
+	//    listing and dispatch cannot drift. It unions real and symlinked socket gids:
+	//    the earlier real-socket-only check let an out-of-domain record survive as a
+	//    clean PeerFact beside a forged symlink receiver.
 	const conflictGids = new Set<string>();
 	for (const id of identities) {
-		if (isNonPiGardenIdSocketConflict(id.backend, id.gardenId, socketGids, symlinkedGids)) {
+		if (isOutOfSocketDomainGardenIdConflict(id.backend, id.gardenId, socketGids, symlinkedGids)) {
 			conflictGids.add(id.gardenId);
 			diagnostics.push({
 				kind: "garden-id-socket-conflict",
 				gardenId: id.gardenId,
 				backend: id.backend,
 				message:
-					`non-pi citizen (${id.backend}) shares its gardenId with a control socket (real or symlinked) — address ` +
-					"ambiguity; both the citizen and the socket are quarantined from the listing.",
+					`out-of-socket-domain citizen (${id.backend}) shares its gardenId with a control socket ` +
+					"(real or symlinked) — address ambiguity; both sides are quarantined from the listing.",
 			});
 		}
 	}

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

@@ -75,27 +75,27 @@ export function resolvePeerFact(identity: MetaIdentity, socket: SocketLiveness |
 }
 
 /**
- * A non-pi RECORD whose gardenId collides with a control socket — a real (probed)
- * one OR a symlinked/forged one. The gardenId is the universal address (동결결정3),
- * so a non-pi citizen sharing it with a socket means a send-path that reaches the
- * socket first hits a DIFFERENT receiver than the record names — an address split.
+ * An OUT-OF-SOCKET-DOMAIN record whose gardenId collides with a control socket —
+ * a real (probed) one OR a symlinked/forged one. The gardenId is the universal
+ * address, so a citizen without socket capability sharing it with a socket means
+ * the socket reaches a DIFFERENT receiver than the record names — an address split.
  * Both the citizen and the socket are quarantined from the facts listing.
  *
  * The union `socketGids ∪ symlinkedGardenIds` is load-bearing: `socketGids` are
  * gids with a real probed `*.sock`, but `symlinkedGardenIds` are NEVER probed (P1)
  * and so are absent from `socketGids`. Looking at `socketGids` alone (the
- * fact-provider:125 gap this closes) let a non-pi citizen with a *symlinked* socket
+ * fact-provider:125 gap this closes) let an out-of-domain citizen with a *symlinked* socket
  * survive as a clean PeerFact while the legacy send path still followed the symlink
  * to a forged receiver. Both axes claim the gid → both must quarantine it.
  *
- * SCOPE: this is the RECORD-side, non-pi conflict only — shared by the fact-provider
- * (listing) and the v2 decider (dispatch) so the two cannot drift (4c "재유도 금지"
- * 동형; only the observation-bit source is parameterized). A pi citizen whose own
- * canonical socket is a symlink is NOT this predicate's concern — that is a
+ * SCOPE: this is the record-side, out-of-socket-domain conflict only — shared by
+ * listing and dispatch so they cannot drift; only the observation-bit source is
+ * parameterized. A citizen IN the socket domain whose own canonical socket is a
+ * symlink is NOT this predicate's concern — that is a
  * target-specific lstat conflict the decider's `inspectTargetControlSocket` raises
  * as `address-conflict`, kept deliberately separate (GPT 1차 검수 C).
  */
-export function isNonPiGardenIdSocketConflict(
+export function isOutOfSocketDomainGardenIdConflict(
 	backend: string,
 	gardenId: string,
 	socketGids: ReadonlySet<string>,
@@ -163,8 +163,8 @@ export interface FactList {
  *     `indeterminate` and strand a dormant citizen as un-resumable); a dormant
  *     citizen's absent socket file is probed to `dead` (ENOENT) by the wiring and
  *     arrives here AS `dead` → dormant → resumable.
- *   - out-of-domain citizen WITH a control socket at its gardenId → fail-loud
- *     (address ambiguity; a non-pi citizen must not own a pi control socket).
+ *   - out-of-socket-domain citizen WITH a control socket at its gardenId → fail-loud
+ *     (address ambiguity; a backend without socket capability cannot own that rail).
  *   - out-of-domain citizen without a socket → `unsupported` (via resolvePeerFact).
  *   - a probed gardenId with NO citizen → `RecordLessSocketFact` (#50 C4: a
  *     diagnostic subject the provider folds into a `record-less-socket`
@@ -202,7 +202,7 @@ export function resolveFactList(identities: MetaIdentity[], socketProbes: Socket
 			if (probeMap.has(gid)) {
 				throw new Error(
 					`resolveFactList: out-of-domain citizen ${gid} (${identity.backend}) has a control socket — ` +
-						"address ambiguity (a non-pi citizen must not own a pi control socket)",
+						"address ambiguity (an out-of-socket-domain citizen cannot own a control socket)",
 				);
 			}
 			socket = null;