@junghanacs/entwurf 0.12.9 → 0.13.0

package/pi-extensions/lib/entwurf-resume-args.ts

@@ -1,40 +1,40 @@
 /**
  * entwurf-resume-args — the SINGLE source of truth for the `pi` argv a resume spawn is
- * launched with (0.11 Stage 0 step 5c-3b). Two variants share this builder so the legacy
- * async-entwurf worker and the v2 spawn-bg resident citizen can NEVER drift in their launch
- * shape — the one place the `--no-extensions` / `--entwurf-control` decision lives.
+ * launched with (0.11 Stage 0 step 5c-3b). One place owns the
+ * `--no-extensions` / `--entwurf-control` decision so the launch shape cannot drift.
  *
- * The load-bearing difference (A1):
- *   - legacy — a one-shot async worker. `pi -p <prompt>` runs the resume turn and EXITS;
- *     `proc.on('close')` then delivers the followUp. It is launched `--no-extensions` AND
- *     WITHOUT `--entwurf-control` precisely BECAUSE a control-socket server would keep
- *     `pi -p` from exiting (entwurf.ts:22 — that keep-alive was a bug for a one-shot worker).
- *   - v2-control — a RESIDENT, addressable garden citizen. The resume turn STILL runs via
- *     `-p <prompt>` (the prompt-as-turn authority is unchanged), but the child is launched
- *     WITH `--entwurf-control` and WITHOUT `--no-extensions`, so the very keep-alive legacy
- *     avoided is now the GOAL: the resumed session stands its control socket up and stays
- *     live. The 5c-3a watcher's `socket-alive` is exactly that "resumed citizen is up and
- *     addressable" observation (→ release the per-gid lock, child lives on); `child-exited`
- *     is the early-exit/failure observation. `plan.launchArgs` (`--approve` or empty, from
- *     the decider's preflight) rides along as pi flags before the prompt.
+ * The shipped posture (A1): a RESIDENT, addressable garden citizen. The resume turn runs via
+ * `-p <prompt>` (the prompt-as-turn authority), and the child is launched WITH
+ * `--entwurf-control` and WITHOUT `--no-extensions` — the keep-alive is the GOAL here: the
+ * resumed session stands its control socket up and stays addressable. The 5c-3a watcher's
+ * `socket-alive` is exactly that "resumed citizen is up" observation (→ release the per-gid
+ * lock, child lives on); `child-exited` is the early-exit/failure observation.
+ * `plan.launchArgs` (`--approve` or empty, from the decider's preflight) rides along as pi
+ * flags before the prompt.
+ *
+ * A second `legacy` one-shot posture (`--no-extensions`, no control socket, so `pi -p` could
+ * exit) lived here until 2026-07-27 and was removed with its launcher and the v1 verbs.
  *
  * Provider/model identity is the caller's existing authority (readSessionIdentity /
  * getEntwurfExplicitExtensions) — this builder only LAYS OUT argv, it never resolves
- * identity. `explicitExtensionArgs` is preserved verbatim in BOTH variants: a recorded
- * `provider=entwurf` resume needs the bridge re-injected to resolve the provider, and
- * dropping it when `--no-extensions` is removed would re-introduce the "Unknown provider"
- * footgun (#29). (A future slice may dedup against settings-loaded extensions; not here.)
+ * identity. `explicitExtensionArgs` is preserved verbatim: a recorded `provider=entwurf`
+ * resume needs the bridge re-injected to resolve the provider, and dropping it would
+ * re-introduce the "Unknown provider" footgun (#29). (A future slice may dedup against
+ * settings-loaded extensions; not here.)
  *
- * This module is import-free on purpose: the legacy launcher (entwurf-async.ts) is
- * root-typechecked and imports it as `./entwurf-resume-args.js`, while the v2 adapter and
- * the gate import the same source — a self-contained string builder keeps both configs happy.
+ * This module is import-free on purpose: the v2 adapter and the gate import the same source,
+ * and a self-contained string builder keeps both tsconfigs happy.
  */
 
-export type ResumeArgsVariant = "legacy" | "v2-control";
+/** The one shipped launch posture: a resident citizen (`--entwurf-control`, extensions
+ * loaded). The `legacy` one-shot variant was removed with its launcher (2026-07-27) — an
+ * exported branch no product path took was what let this module's prose claim a second
+ * live consumer for months. Reviving a one-shot posture means adding it back deliberately,
+ * with a consumer, not un-deleting a dead enum member. */
+export type ResumeArgsVariant = "v2-control";
 
 export interface ResumePiArgsInput {
-	/** legacy = one-shot worker (`--no-extensions`, no control socket); v2-control =
-	 * resident citizen (`--entwurf-control`, extensions loaded). */
+	/** v2-control = resident citizen (`--entwurf-control`, extensions loaded). */
 	variant: ResumeArgsVariant;
 	/** ABSOLUTE path of the session JSONL to resume — pi's `--session <path>` (#50 C2).
 	 * It replaced `--session-id <gardenId>`, which did two jobs that are no longer the
@@ -46,7 +46,7 @@ export interface ResumePiArgsInput {
 	 * instead of resuming one. A path cannot do that. */
 	sessionFile: string;
 	/** The explicit `--extension …` re-injection (ACP bridge / provider resolution).
-	 * Preserved verbatim in BOTH variants — load-bearing for a entwurf resume. */
+	 * Preserved verbatim — load-bearing for a entwurf resume. */
 	explicitExtensionArgs: readonly string[];
 	/** Recorded provider (may be null/undefined — then no `--provider` flag is emitted). */
 	provider: string | null | undefined;
@@ -54,37 +54,31 @@ export interface ResumePiArgsInput {
 	model: string;
 	/** The resume prompt — the final positional, run as the model turn under `-p`. */
 	prompt: string;
-	/** v2-control ONLY: the decider's `plan.launchArgs` (`["--approve"]` or `[]`). Ignored
-	 * for legacy (the legacy path computes its own preflight elsewhere). */
+	/** The decider's `plan.launchArgs` (`["--approve"]` or `[]`). */
 	launchArgs?: readonly string[];
 }
 
 /**
- * Build the `pi` argv for a resume spawn. The SHARED prefix is `--mode json -p` (headless
- * JSON child, prompt-as-turn); the variant then chooses the extension/socket posture; the
- * SHARED suffix is `[…ext args] --session <file> [--provider <p>] --model <m> <prompt>`.
+ * Build the `pi` argv for a resume spawn. The prefix is `--mode json -p` (headless JSON
+ * child, prompt-as-turn); then the resident posture; then
+ * `[…ext args] --session <file> [--provider <p>] --model <m> <prompt>`.
  *
  * Invariants the gate pins:
- *   - legacy  carries `--no-extensions` and NO `--entwurf-control`.
  *   - v2-control carries `--entwurf-control` and NO `--no-extensions`, plus `-p` + prompt.
- *   - `explicitExtensionArgs` appears exactly once in both.
- *   - `launchArgs` is included for v2-control (before the suffix) and ignored for legacy.
- *   - provider/model/prompt identity is laid out identically in both.
+ *   - `explicitExtensionArgs` appears exactly once.
+ *   - `launchArgs` is included before the suffix.
+ *   - provider/model/prompt identity layout is fixed.
  */
 export function buildResumePiArgs(input: ResumePiArgsInput): string[] {
 	const args: string[] = ["--mode", "json", "-p"];
 
-	if (input.variant === "legacy") {
-		// One-shot worker: no extensions, no control socket (so `pi -p` can exit).
-		args.push("--no-extensions");
-	} else {
-		// Resident citizen: stand the control socket up (A1) and keep extensions loaded.
-		// The keep-alive legacy avoided is the goal here. `--approve`/launchArgs ride along.
-		args.push("--entwurf-control");
-		args.push(...(input.launchArgs ?? []));
-	}
+	// Resident citizen: stand the control socket up (A1) and keep extensions loaded. The
+	// keep-alive the removed one-shot launcher had to avoid is precisely the goal here —
+	// the resumed session must stay addressable. `--approve`/launchArgs ride along.
+	args.push("--entwurf-control");
+	args.push(...(input.launchArgs ?? []));
 
-	// Shared suffix — identical identity layout in both variants.
+	// Suffix — the fixed identity layout.
 	args.push(...input.explicitExtensionArgs);
 	args.push("--session", input.sessionFile);
 	if (input.provider) args.push("--provider", input.provider);

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

@@ -3,14 +3,13 @@
  *
  * "Can a reply to THIS session actually land where its model will see it?"
  *
- * Today both the MCP bridge (buildStrictPiSenderEnvelope /
- * buildTrustedMetaSenderEnvelope / entwurf_self) and pi-native answer that from env
- * presence alone and hardcode `replyable: true`: a pi session with no
- * --entwurf-control socket, or a meta citizen whose owner has exited / whose
- * idle-watch was never armed, all claim replyable while delivery silently fails
- * (SE-1: "all layers say yes, only delivery says no" = a Crash-Don't-Warn
- * violation). This module is the single truth-table both surfaces compute from,
- * with every fact INJECTED (no IO) so the gate can pin each row.
+ * This module closed the former split where the MCP and native pi surfaces inferred
+ * `replyable: true` from identity-carrier presence alone. Identity and reachability
+ * are separate: pi's env carries the garden id established by record birth, while
+ * replyability requires its control socket; a native marker must be record-backed,
+ * while replyability additionally requires its own rail's live facts. This is the
+ * single truth-table both surfaces compute from, with every fact INJECTED (no IO) so
+ * the gate can pin each row.
  *
  * Axes by origin:
  *  - pi-session:  replyable ⟺ a live control socket exists at the canonical path.
@@ -33,7 +32,7 @@
  *                 — which never arms a watch — would report replyable:false forever.
  *  - external-mcp: never replyable — no authoritative reply address.
  *
- * `origin` stays identity PROVENANCE (where the sender identity came from), never a rail.
+ * `origin` stays sender-carrier PROVENANCE, never the citizen identity authority and never a rail.
  * Which rail a meta citizen's reply rides is a SECOND axis — `metaDeliveryDomain`, derived
  * by the caller from `nativePushSupported(backend)`, not from `wakeMode` (direct-inject also
  * covers codex/pi, which have no native-push adapter). Fail-closed: an unsupplied domain is

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

@@ -9,7 +9,12 @@
  * from the bridge boot closure would re-couple the harness-neutral meta-bridge to
  * pi (the `check-entwurf-bridge-pi-free` gate fails if it does). The bridge needs
  * the contract CONSTANTS + `resolveDispatch` (pi-free core), never these schemas.
- * Consumers: the pi MCP-tool param surface and `check-entwurf-v2-contract`.
+ * Consumer: `check-entwurf-v2-contract` ONLY. This is a gate-side REPRESENTATION of the
+ * frozen contract, not a shipped tool schema — measured 2026-07-27, nothing else in the
+ * import graph reaches it. The two surfaces a model actually reads build their own:
+ * `pi-extensions/entwurf-control.ts` (TypeBox `entwurfV2Parameters` + tool description) and
+ * `mcp/entwurf-bridge/src/index.ts` (Zod). Change a model-facing description THERE; changing
+ * it here reaches no model, and `check-entwurf-v2-surface` is what pins those two.
  *
  * StringEnum (typebox 1.x) inside Type.Object (typebox 0.34) — the same mix the
  * existing entwurf tools use. The logic types in the core are hand-written unions,
@@ -37,7 +42,7 @@ export const EntwurfV2InputSchema = Type.Object(
 		target: Type.String({
 			pattern: SESSION_ID_RE.source,
 			description:
-				"garden-id of an EXISTING citizen (pattern-enforced). spawn-new is out of v2 scope (legacy entwurf keeps it); a malformed/typo gid is bad-target.",
+				"garden-id of an EXISTING citizen (pattern-enforced). Fresh sibling creation is out of scope on every current surface — there is no fallback verb that still spawns. A malformed/typo gid is bad-target, never a new spawn.",
 		}),
 		intent: StringEnum(ENTWURF_INTENTS, {
 			description:

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

@@ -7,25 +7,28 @@
  * `entwurf-v2-contract-schema.ts` (0.12.1 B-1) so this module — which the
  * harness-neutral MCP bridge reaches at boot — carries no pi dependency.
  *
- * Why a frozen contract BEFORE the fact-provider (step 4): with the legacy
- * 3-verb surface (`entwurf`/`entwurf_resume`/`entwurf_send`) still live, building
- * discovery first bakes verb-routing into the fact layer and `entwurf_peers`
- * goes wrong (동결결정 10 순서 근거). So the SHAPE is locked here; the facts read
- * it; dispatch computes from facts at call time (step 5). The legacy 3-verb
- * surface is untouched — this is purely additive (동결결정 10 scope A).
+ * Why a frozen contract BEFORE the fact-provider (step 4): the legacy 3-verb
+ * surface (`entwurf`/`entwurf_resume`/`entwurf_send`) was still live when this
+ * was written, and building discovery first would have baked verb-routing into
+ * the fact layer, taking `entwurf_peers` wrong (동결결정 10 순서 근거). So the
+ * SHAPE is locked here; the facts read it; dispatch computes from facts at call
+ * time (step 5). Those v1 verbs were REMOVED in the 0.12 cutover — the ordering
+ * argument is history, but the layering it produced is the live design.
  *
  * Source-verified invariants folded in (Opus 실측 + GPT 보정 + Fable R1-R5, 2026-06-11):
  *  - F1: caller intent is DECLARED in the input, so the contract a caller
  *    receives is deterministic — never computed from liveness at call time.
  *    `owned-outcome` (caller owns completion) ≠ `fire-and-forget` (ack only).
- *  - R1: the liveness predicate is defined PER-BACKEND. Only pi (direct-inject,
- *    control-socket) has one initially; claude-code is self-fetch with no socket,
- *    so its liveness is `unsupported`, NOT folded into dead/indeterminate — that
- *    fold is the identity-split trap. `unsupported` is a 4th FACT value, not a
- *    4th dispatch column: an out-of-domain backend rejects before the table.
+ *  - R1: liveness is defined PER CAPABILITY DOMAIN. The control-socket domain
+ *    currently contains backend `pi`; claude-code is self-fetch with no socket,
+ *    so its socket liveness is `unsupported`, NOT folded into dead/indeterminate.
+ *    This is transport capability, not identity rank: every target is first a
+ *    record citizen. `unsupported` is a 4th FACT value, not a 4th table column.
  *  - R2: `target` is the garden-id of an EXISTING citizen. spawn-new is out of
- *    v2 scope (legacy `entwurf` keeps it; additive later). Absent/typo gid =
- *    `bad-target` (so F6 "오타 gid가 신규 spawn 사고 막기" holds automatically).
+ *    v2 scope — it was the legacy `entwurf` verb's, and since that verb's removal
+ *    fresh creation is a deferred capability with NO surface, not a fallback that
+ *    still exists elsewhere. Absent/typo gid = `bad-target` (so F6 "오타 gid가
+ *    신규 spawn 사고 막기" holds automatically).
  *  - N1/F3: an `indeterminate` target never spawns. N2: `fire-and-forget` to a
  *    `dormant` target is "reject for now" (mailbox-wake lacks a reply-correlation
  *    id in the substrate; an additive extension later, not a permanent no).
@@ -67,16 +70,16 @@ export const DISPATCH_LIVENESSES = ["live", "dormant", "indeterminate"] as const
 export type DispatchLiveness = (typeof DISPATCH_LIVENESSES)[number];
 
 // ── Backend liveness domain (R1 + F4) ──────────────────────────────────────
-// Backends whose SOCKET liveness predicate is DEFINED — the pi control-socket
-// domain ONLY (connect + RPC `get_info`, entwurf-control.ts). It stays ["pi"].
+// Backends whose SOCKET liveness predicate is DEFINED. The control-socket
+// capability domain currently contains `pi` (connect + RPC `get_info`).
 // claude-code (self-fetch, no socket) has no liveness predicate at all → `unsupported`.
 // codex/antigravity are direct-inject; antigravity's liveness IS measured, but by the
 // SEPARATE native-push adapter rail (a live app-server conversation probe), NOT this
 // pi-socket domain — so it must NEVER be added here. Adding it would pull agy into the
-// pi socket table (inspectSocket/probeSocket are socket-only); the fact layer keeps
-// reporting agy `unsupported` = "outside the pi-socket liveness domain", NOT
+// control-socket table (inspectSocket/probeSocket are socket-only); the fact layer keeps
+// reporting agy `unsupported` = "outside the control-socket liveness domain", NOT
 // unreachable (the native-push rail measures it — entwurf-v2-decider.ts). Widening
-// THIS set is a deliberate future decision (Stage 1+), gated by a REAL pi-shaped
+// 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
 // domain is disjoint from it.
@@ -89,12 +92,12 @@ export function isLivenessSupported(backend: string): boolean {
 
 // ── Native-push backend domain (봉인 2/4) ───────────────────────────────────
 // A backend whose liveness is measured by the SEPARATE native-push adapter rail (a
-// live app-server conversation probe — antigravity's LS gRPC), NOT the pi control
-// socket. This domain is DISJOINT from LIVENESS_DOMAIN_BACKENDS (pi socket): an agy
-// session is `unsupported` at the pi-socket FACT level (entwurf_peers) yet fully
+// live app-server conversation probe — antigravity's LS gRPC), NOT a control
+// socket. This domain is DISJOINT from LIVENESS_DOMAIN_BACKENDS: an agy session
+// is `unsupported` on the socket FACT axis (entwurf_peers) yet fully
 // measured + deliverable on the native-push axis. The two are separate rails on
 // purpose — check-entwurf-facts pins both sets and asserts their intersection is ∅
-// (a backend can never be in both a socket-liveness domain and a native-push domain).
+// (a backend can never be in both domains).
 export const NATIVE_PUSH_BACKENDS = ["antigravity"] as const;
 export type NativePushBackend = (typeof NATIVE_PUSH_BACKENDS)[number];
 
@@ -239,8 +242,9 @@ export const ENTWURF_V2_ACTIONS = ["send", "resume"] as const;
 export const ENTWURF_V2_OWNERSHIPS = ["ack-only", "owned"] as const;
 // Delivery mode of the message to the target (how it is injected) — steer =
 // interrupt the current turn, follow_up = queue after it. A SEPARATE axis from
-// both the intent/ownership axis (F1) and the liveness-routing axis; the legacy
-// entwurf_send carries the same steer|follow_up surface.
+// both the intent/ownership axis (F1) and the liveness-routing axis. The removed
+// v1 `entwurf_send` carried the same steer|follow_up surface, so this axis is
+// inherited vocabulary, not a second live delivery verb.
 export const ENTWURF_V2_MODES = ["steer", "follow_up"] as const;
 
 export type DispatchVerdict =
@@ -252,7 +256,10 @@ export type DispatchVerdict =
 // intent × dispatch-liveness → exactly one verdict (Q2). v2-initial ALLOWS
 // exactly two cells (fire-and-forget+live = send; owned-outcome+dormant =
 // resume); the other four reject. The reject cells are honest "지금은 없음"
-// locks (N2) — the legacy 3-verb surface still covers those flows unchanged.
+// locks (N2). They were written while the legacy 3-verb surface still covered
+// those flows; that surface is GONE, so a reject cell is now a real absence with
+// no fallback verb behind it — reopening one takes a new contract, never a
+// quiet re-admission.
 export const DISPATCH_TABLE: Record<EntwurfIntent, Record<DispatchLiveness, DispatchVerdict>> = {
 	"fire-and-forget": {
 		live: { action: "send", transport: "control-socket", ownership: "ack-only" },

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

@@ -26,7 +26,7 @@
  *      MCP-schema bypass for pi-native/internal callers).
  *   2. resolveTarget     — no citizen → bad-target; a record-less control socket →
  *      record-less-socket (#50 C4: the record is the sole address authority);
- *      quarantined (non-pi gid sharing a socket/symlink) → target-address-conflict.
+ *      quarantined (out-of-socket-domain record sharing a socket/symlink) → target-address-conflict.
  *      PROBE-FREE.
  *   3. backend           → isLivenessSupported.
  *   4. acquireLock       — IN-DOMAIN ONLY (？7), BEFORE lstat/connect, so the probe
@@ -47,7 +47,7 @@
  */
 
 import type { MailboxDeliverabilityResult } from "./entwurf-deliverability.ts";
-import { isNonPiGardenIdSocketConflict } from "./entwurf-facts.ts";
+import { isOutOfSocketDomainGardenIdConflict } from "./entwurf-facts.ts";
 import type { PreflightOutcome } from "./entwurf-preflight.ts";
 import {
 	type EntwurfIntent,
@@ -75,7 +75,7 @@ import type { SocketLiveness } from "./socket-probe.ts";
 
 // Re-export the shared conflict predicate so producers of a TargetResolution have a
 // single import site for it (it is the SAME fn the fact-provider listing uses).
-export { isNonPiGardenIdSocketConflict };
+export { isOutOfSocketDomainGardenIdConflict };
 
 // ── observe timeout (？3) ───────────────────────────────────────────────────
 // The bounded wait 5c's release-watcher gives a spawned child to surface its
@@ -172,8 +172,8 @@ export type DispatchDecision =
 
 // ── target resolution (E: single-target, not a whole-store scan) ────────────
 // A non-null identity is an existing citizen. `preProbeAddressConflict` is the
-// PROBE-FREE, record-side conflict (non-pi gid sharing a real/symlinked socket —
-// isNonPiGardenIdSocketConflict). The production wrapper computes it with a single
+// PROBE-FREE record-side conflict: a backend outside the control-socket domain
+// sharing a real/symlinked socket (`isOutOfSocketDomainGardenIdConflict`). Production uses one
 // readMetaIdentityByGardenId + a target socket/symlink check; the gate injects it.
 // Do NOT call listEntwurfFacts here to find the target — its socket probe would run
 // before the lock (the 1C TOCTOU). The shared predicate is the only thing the
@@ -377,12 +377,12 @@ export async function decideDispatch(input: DispatchInput, deps: DispatchDecider
 		return { kind: "execute", receipt, plan, lock: null };
 	}
 
-	// 4-5. in-domain (record-backed pi): lock → inspect → route (cwd from the record).
+	// 4-5. control-socket domain (currently backend pi): lock → inspect → route.
 	return decideInDomain(gardenId, input, deps, ctx, identity.cwd);
 }
 
-// ── in-domain probe (steps 4-5) — record-backed pi ONLY (#50 C4: a record-less
-// socket rejects pre-probe and never reaches here) ──────────────────────────────
+// ── control-socket-domain probe (steps 4-5; currently backend pi). Every target
+// is record-backed; a record-less socket rejects before this branch. ────────────
 // The lock lifecycle (B2) lives here: acquire BEFORE lstat/connect, every reject path
 // releases explicitly (rejectAfterRelease), every execute path that keeps the lock sets
 // retainLock=true, and a thrown IO error releases the still-held lock before rethrowing so

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

@@ -2,10 +2,11 @@
  * entwurf-v2-lock — the per-gid dispatch lock primitive (0.11 Stage 0 step 5a,
  * 버킷 B F2). LOAD-BEARING: the guard against a double-spawn of the same dormant
  * target by two V2 dispatchers that share the substrate through different entry
- * points. SCOPE (honest): this protects v2/v2 only. The legacy `entwurf_resume`
- * is unchanged (동결결정 10 scope A) and does NOT take this lock, so v2/legacy
- * concurrent resume is a KNOWN residual gap (rare — single-orchestrator practice),
- * closed only at full cut-over. Do not read this header as "v2/legacy is guarded".
+ * points. SCOPE (honest): this protects v2/v2 only. It was written while the legacy
+ * `entwurf_resume` still ran unchanged (동결결정 10 scope A) without taking this
+ * lock, which left a v2/legacy concurrent-resume gap. That verb was REMOVED in the
+ * 0.12 cutover, so the gap is closed by subtraction — not by this lock growing to
+ * cover it. Any NEW resume entry point must take this lock or the gap reopens.
  *
  * ENVIRONMENT ASSUMPTION (stale reclaim): `hostname` equality is used as the
  * proxy for "same machine", so a holder pid is reclaim-probed with kill(0) only

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

@@ -42,7 +42,7 @@ import {
 	mailboxConversationalDeliverable,
 	receiverMarkerMatchesIdentity,
 } from "./entwurf-deliverability.ts";
-import { isNonPiGardenIdSocketConflict } from "./entwurf-facts.ts";
+import { isOutOfSocketDomainGardenIdConflict } from "./entwurf-facts.ts";
 // 0.12.1 B-2: TYPE-ONLY import — `entwurf-preflight.ts` value-imports
 // `@earendil-works/pi-coding-agent` (ProjectTrustStore), so a static value-import
 // here would re-couple the harness-neutral MCP bridge to pi at boot
@@ -189,7 +189,7 @@ async function lazyProductionPreflight(input: PreflightInput): Promise<Preflight
 }
 
 /** Map a record-side socket inspection to the singleton (socketGids, symlinkedGids) the
- * `isNonPiGardenIdSocketConflict` predicate consumes. `indeterminate` fails LOUD (QB2): an
+ * `isOutOfSocketDomainGardenIdConflict` predicate consumes. `indeterminate` fails LOUD (QB2): an
  * unprovable conflict must NOT be folded to "no conflict" — that would silently allow an
  * unsupported-backend mailbox send onto a quarantined address. */
 function conflictSetsFor(
@@ -294,20 +294,23 @@ export function makeProductionEntwurfV2Deps(opts: ProductionEntwurfV2Opts): Entw
 			};
 		}
 		const identity = io.readIdentity(gid, sessionsDir);
-		// `preProbeAddressConflict` is the record-side NON-PI conflict ONLY (B1). An in-domain
-		// (pi) target's socket lstat/connect MUST run UNDER the lock in the decider's later
-		// `inspectSocket` step (1C: lock BEFORE lstat/connect) — so a pi target short-circuits
-		// here with NO pre-lock lstat. Doing the lstat here would (a) be a needless pre-lock IO
-		// and (b) turn a pi target's `indeterminate` lstat into a top-level throw, stealing it
-		// from the under-lock `inspectSocket → indeterminate → indeterminate-no-spawn` path.
+		// This pre-probe conflict applies only OUTSIDE the control-socket capability domain.
+		// An in-domain target's lstat/connect MUST run under the later per-target lock, so it
+		// short-circuits here with no pre-lock IO. Otherwise an indeterminate lstat would be
+		// stolen from the under-lock `inspectSocket → indeterminate-no-spawn` path.
 		if (isLivenessSupported(identity.backend)) {
 			return { identity, preProbeAddressConflict: false };
 		}
-		// Only an unsupported (non-pi) citizen reaches the record-side lstat: a single lstat (no
-		// connect) of the canonical path; `indeterminate` fails loud (QB2 — never "no conflict").
+		// Only a citizen outside the control-socket domain reaches this record-side lstat;
+		// `indeterminate` fails loud (QB2 — never silently "no conflict").
 		const inspection = await io.inspectPath(controlSocketPath(gid, controlSocketDir));
 		const { socketGids, symlinkedGids } = conflictSetsFor(gid, inspection);
-		const preProbeAddressConflict = isNonPiGardenIdSocketConflict(identity.backend, gid, socketGids, symlinkedGids);
+		const preProbeAddressConflict = isOutOfSocketDomainGardenIdConflict(
+			identity.backend,
+			gid,
+			socketGids,
+			symlinkedGids,
+		);
 		return { identity, preProbeAddressConflict };
 	};
 

package/pi-extensions/lib/entwurf-v2-spawn-production.ts

@@ -135,7 +135,9 @@ export function resolveResumeLaunchIdentity(plan: SpawnBgPlan): LaunchIdentity {
 	const record = readAddressableMetaIdentity(plan.sessionId);
 	if (record.backend !== "pi") {
 		throw new Error(
-			`entwurf-v2-spawn-production: ${plan.sessionId} is a ${record.backend} citizen — spawn-bg resume is the pi rail.`,
+			`entwurf-v2-spawn-production: ${plan.sessionId} is a ${record.backend} citizen — ` +
+				`spawn-bg resume is a host-adapter capability, and its domain currently contains backend pi only. ` +
+				`This is a relaunch capability, not the control-socket rail and not citizen rank.`,
 		);
 	}
 	const sessionFile = record.transcriptPath;

package/pi-extensions/lib/meta-session.ts

@@ -1,12 +1,12 @@
 /**
- * meta-session — 1.0.0 garden-native meta-bridge, step 2: the RECORD AUTHORITY.
+ * meta-session — the shared V3 garden-citizen RECORD AUTHORITY.
  *
- * Backend-agnostic garden layer (#30). A *meta-session* is the bib card for a
- * native backend session (Claude Code / Antigravity / Codex) that has NO pi
- * JSONL of its own: an opaque pointer record that makes the native session a
- * garden citizen — addressable + wakeable by a garden id — WITHOUT pretending pi
- * owns its transcript (Hard Rule #8: reference the backend transcript, never
- * hydrate or replay it).
+ * This module entered through the native meta-bridge (#30), then became the one
+ * identity store for every addressable citizen, including `backend:"pi"` (#50).
+ * A record is a backend-owned-session bib card: it binds the backend's native id
+ * and transcript pointer to a garden id without taking over that backend's runtime,
+ * auth, or transcript. The module name is history; the live identity schema is not
+ * a native-only or pi-exception axis.
  *
  * Two layers, clearly sectioned:
  *   1. RECORD functions + types (mint / serialize / parse / certifyActiveStore /
@@ -61,7 +61,7 @@ import { generateSessionId, SESSION_ID_RE } from "./session-id.js";
 // Errors
 // ---------------------------------------------------------------------------
 
-/** A meta-record is malformed, or an input violates the record contract. */
+/** A garden-citizen record is malformed, or an input violates the record contract. */
 export class MetaRecordError extends Error {
 	constructor(message: string) {
 		super(message);
@@ -142,8 +142,9 @@ export function requireNonEmptyString(value: unknown, field: string): string {
 
 /** Validate the 3-backend NATIVE bridge axis (sender/receiver markers, capability
  * drift guard). Not a record-schema validator: identity records take
- * `requireCitizenBackend` (which admits `pi`); markers stay native-3 because a pi
- * session's sender identity is env-authored, never marker-authored. */
+ * `requireCitizenBackend` (which admits `pi`). Markers stay native-3 because the
+ * pi adapter carries its record-established garden id into children via env rather
+ * than using the native-hook pid marker rail. */
 export function requireBackend(value: unknown): MetaBackend {
 	if (typeof value !== "string" || !META_BACKENDS.includes(value as MetaBackend)) {
 		throw new MetaRecordError(
@@ -208,7 +209,7 @@ function isoNow(now: Date): string {
 /** The one live identity schema number. */
 export const META_SCHEMA_VERSION_V3 = 3 as const;
 
-/** The 4 record-citizen backends: the three native backends + `pi` itself. */
+/** Every backend admitted by the one V3 record-citizen schema. */
 export const META_CITIZEN_BACKENDS = ["claude-code", "antigravity", "codex", "pi"] as const;
 export type MetaCitizenBackend = (typeof META_CITIZEN_BACKENDS)[number];
 
@@ -510,15 +511,11 @@ export function parseMetaIdentity(json: string): MetaIdentity {
 // const for the three existing backends (the drift guard) and COVERS exactly
 // META_CITIZEN_BACKENDS (pi included).
 //
-// pi's wakeMode = direct-inject (NOT self-fetch): pi's live wake path is the
-// entwurf-control socket — `pi.sendMessage(... triggerTurn ...)` injects the
-// body straight into the model-visible turn, which is direct-inject by the
-// WakeMode definition (the last-1cm: who puts the body in front of the model).
-// self-fetch is Claude's mailbox path (the model must call its inbox-read MCP).
-// pi's dormant→resume→mailbox path is self-fetch-shaped, so pi is really
-// BIMODAL; a single wakeMode field cannot express both. Splitting it
-// (mailboxWakeMode vs controlSocketWakeMode) is out of 3C scope — for now the
-// single field reports pi's primary live capability (direct-inject) honestly.
+// `wakeMode` describes the last centimetre, not citizen rank. The control-socket
+// adapter injects the body into a pi turn, so backend `pi` is `direct-inject`;
+// Claude's mailbox is `self-fetch`; native-push adapters are direct injection.
+// Dormant spawn-bg resume is a separate transport/ownership decision and does not
+// turn the pi record into a mailbox citizen.
 // ---------------------------------------------------------------------------
 
 /** Bump only on a breaking capability-registry shape change; the parser refuses other versions. */