@junghanacs/entwurf 0.12.9 → 0.13.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-resume-args.js

@@ -1,59 +1,49 @@
 /**
  * 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.
  */
 /**
- * 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) {
     const args = ["--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 ?? []));
-    }
-    // Shared suffix — identical identity layout in both variants.
+    // 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 ?? []));
+    // Suffix — the fixed identity layout.
     args.push(...input.explicitExtensionArgs);
     args.push("--session", input.sessionFile);
     if (input.provider)

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-self-address.js

@@ -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/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-contract.js

@@ -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).
@@ -58,16 +61,16 @@ export const FACT_LIVENESSES = ["alive", "dead", "indeterminate", "unsupported"]
 // handled by the domain guard before the table is consulted.
 export const DISPATCH_LIVENESSES = ["live", "dormant", "indeterminate"];
 // ── 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.
@@ -77,12 +80,12 @@ export function isLivenessSupported(backend) {
 }
 // ── 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"];
 export function nativePushSupported(backend) {
     return NATIVE_PUSH_BACKENDS.includes(backend);
@@ -202,14 +205,18 @@ export const ENTWURF_V2_ACTIONS = ["send", "resume"];
 export const ENTWURF_V2_OWNERSHIPS = ["ack-only", "owned"];
 // 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"];
 // ── The FROZEN decision table ──────────────────────────────────────────────
 // 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 = {
     "fire-and-forget": {
         live: { action: "send", transport: "control-socket", ownership: "ack-only" },

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-decider.js

@@ -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
@@ -45,14 +45,14 @@
  * never hand-assembles a `{ok:false, …}` literal, so the pre-probe-null rule cannot
  * be bypassed.
  */
-import { isNonPiGardenIdSocketConflict } from "./entwurf-facts.js";
+import { isOutOfSocketDomainGardenIdConflict } from "./entwurf-facts.js";
 import { isLivenessSupported, makeRejectReceipt, nativePushSupported, resolveDispatch, resolveNativePushDispatch, } from "./entwurf-v2-contract.js";
 import { defaultMetaMailboxDir, defaultMetaSessionsDir, metaCapabilityFor, } from "./meta-session.js";
 import { isValidSessionId } from "./session-id.js";
 import { controlSocketPath, mapInspectionToLiveness } from "./socket-discovery.js";
 // 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
 // control socket / exit. Planted into the resume plan so the hand does not invent
@@ -178,7 +178,7 @@ export async function decideDispatch(input, deps) {
         };
         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);
 }
 async function decideInDomain(gardenId, input, deps, ctx, cwd) {

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-lock.js

@@ -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/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-production.js

@@ -30,7 +30,7 @@
  */
 import { formatSenderInfoBlock, sendRpcCommand as realSendRpc, } from "./entwurf-control-rpc.js";
 import { mailboxConversationalDeliverable, receiverMarkerMatchesIdentity, } from "./entwurf-deliverability.js";
-import { isNonPiGardenIdSocketConflict } from "./entwurf-facts.js";
+import { isOutOfSocketDomainGardenIdConflict } from "./entwurf-facts.js";
 import { isLivenessSupported } from "./entwurf-v2-contract.js";
 import { decideDispatch, } from "./entwurf-v2-decider.js";
 import { ENTWURF_V2_LOCK_DIR, acquireLock as realAcquireLock, releaseLock as realReleaseLock, } from "./entwurf-v2-lock.js";
@@ -68,7 +68,7 @@ async function lazyProductionPreflight(input) {
     return preflight(input);
 }
 /** 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(gid, inspection) {
@@ -162,20 +162,18 @@ export function makeProductionEntwurfV2Deps(opts) {
             };
         }
         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 };
     };
     const inspectSocket = (gid) => io.inspectSocket(gid, controlSocketDir);

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-spawn-production.js

@@ -90,7 +90,9 @@ function requireProductionChild(child) {
 export function resolveResumeLaunchIdentity(plan) {
     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.`);
+        throw new Error(`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;
     if (!sessionFile) {

package/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js

@@ -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 /
@@ -58,7 +58,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) {
         super(message);
@@ -106,8 +106,9 @@ export function requireNonEmptyString(value, field) {
 }
 /** 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) {
     if (typeof value !== "string" || !META_BACKENDS.includes(value)) {
         throw new MetaRecordError(`meta-record "backend" must be one of ${META_BACKENDS.join(" | ")} (got ${describe(value)}).`);
@@ -164,7 +165,7 @@ function isoNow(now) {
 // ---------------------------------------------------------------------------
 /** The one live identity schema number. */
 export const META_SCHEMA_VERSION_V3 = 3;
-/** 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"];
 export function requireCitizenBackend(value) {
     if (typeof value !== "string" || !META_CITIZEN_BACKENDS.includes(value)) {
@@ -407,15 +408,11 @@ export function parseMetaIdentity(json) {
 // 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. */
 export const CAPABILITY_SCHEMA_VERSION = 1;