@junghanacs/entwurf 0.12.0

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

@@ -0,0 +1,1951 @@
+/**
+ * meta-session — 1.0.0 garden-native meta-bridge, step 2: the 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).
+ *
+ * Two layers, clearly sectioned:
+ *   1. RECORD functions + types (mint / serialize / parse / scanByNativeId /
+ *      decideUpsert / read-receipt mutators), the backend-agnostic authority.
+ *      Pure beyond an injected `now`, with ONE exception since 3D-3: mint/parse
+ *      read backend capability (wakeMode/deliveryLevel) from the packaged registry
+ *      via a cached fs read (loadMetaCapabilityRegistry) — see that seam below.
+ *   2. The thin FS-BOUND STORE (step 3): `upsertMetaSession` wraps the pure core
+ *      (readdir → `scanByNativeId` → `decideUpsert` → atomic write) with the real
+ *      filesystem. It lives in this module (not a sibling `*-store.ts`) on purpose:
+ *      the typecheck fence forbids a root-config lib importing another `.ts` lib
+ *      via a `.ts` specifier (tsc-emit) while the same `.js` specifier is
+ *      unresolvable under `node --experimental-strip-types`, so a separate store
+ *      file could not be unit-tested by the deterministic strip-types gate. Only
+ *      node builtins are added here, so `check-meta-session` stays strip-types
+ *      clean. The hook deploy + the thin CLI/argv shell that invokes this is
+ *      step 4 (its stdin contract couples to the Claude `SessionStart` payload).
+ *
+ * Cutting the record/seam FIRST is deliberate ("record authority FIRST, hook
+ * LAST"): the schema and the lookup authority are backend-agnostic, so the
+ * per-backend adapter seam gets cut here, before any "hook = Claude Code"
+ * assumption can ossify.
+ *
+ * Authority rules imported from the 0.9.0 substrate and #30 refinements:
+ *   - garden id = `generateSessionId` (the single SSOT grammar), minted at the
+ *     session's true birth. Reused, never re-derived.
+ *   - lookup authority = SCAN the record bodies by top-level `native_session_id`
+ *     (see scanByNativeId), symmetric with 0.9.0 `findSessionFileById`. Any
+ *     native→garden index is an OPTIONAL derived cache, never the source of
+ *     truth — "needs a DB" is the denote-instinct tripwire.
+ *   - create-vs-attach keys on RECORD EXISTENCE, not the backend `source` field
+ *     (decideUpsert). Idempotent: duplicate hook fires / same-id re-entry are
+ *     absorbed. The CLI is named `upsert` so no one re-introduces `source`
+ *     branching.
+ *   - read-receipt is PRE-DRILLED into the schema now (bbot review #4). The
+ *     mailbox/outbox is post-MVP, but retrofitting the receipt field later would
+ *     touch the schema twice. The "last 1 cm" (did the body reach model-visible
+ *     context?) is kept honest as per-peer metadata, never abstracted away.
+ *
+ * Crash, don't warn: every malformed record / bad id / bad backend throws
+ * `MetaRecordError`. A broken meta-record must surface as a broken meta-record.
+ */
+
+import { execFileSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { generateSessionId, SESSION_ID_RE } from "./session-id.js";
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+/** A meta-record is malformed, or an input violates the record contract. */
+export class MetaRecordError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "MetaRecordError";
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+/** Bump only on a breaking record-shape change; parse refuses other versions. */
+export const META_SCHEMA_VERSION = 1 as const;
+
+/**
+ * The three native meta-bridge backends, declared from the start so the
+ * per-backend adapter seam is forced (a different native layout each — that
+ * difference is the whole reason for a thin adapter). Discriminator field on
+ * every record.
+ */
+export const META_BACKENDS = ["claude-code", "antigravity", "codex"] as const;
+export type MetaBackend = (typeof META_BACKENDS)[number];
+
+/**
+ * How the body reaches model-visible context — the honest "last 1 cm". Claude's
+ * doorbell wakes the model but the body is SELF-FETCHED (the model must
+ * voluntarily call its inbox-read MCP tool); agy/codex DIRECT-INJECT the body
+ * into the turn. This is exposed as peer metadata, never abstracted, so "I sent
+ * it, why didn't it read?" never becomes a debugging hole.
+ */
+export type WakeMode = "self-fetch" | "direct-inject";
+
+/**
+ * Static, backend-derived honesty metadata (the data half of the adapter seam).
+ * `wakeMode` + `deliveryLevel` ride onto each record at mint so the sender
+ * contract can stay uniform on address/queue while being honest on HOW delivery
+ * lands. `deliveryLevel` is a DELIVERY.md D-coordinate (a capability hint, not a
+ * guarantee). `nativeIdLabel` documents what the join key actually is per
+ * backend (Claude sessionId / agy conversationId / codex threadId) — naming, not
+ * behavior; the behavioral half (where sessions live, how to read liveness, hook
+ * deploy unit) lands with the step-4 adapters.
+ */
+export interface MetaBackendDescriptor {
+	backend: MetaBackend;
+	wakeMode: WakeMode;
+	deliveryLevel: string;
+	nativeIdLabel: string;
+}
+
+export const META_BACKEND_DESCRIPTORS: Record<MetaBackend, MetaBackendDescriptor> = {
+	"claude-code": {
+		backend: "claude-code",
+		wakeMode: "self-fetch",
+		deliveryLevel: "D6",
+		nativeIdLabel: "sessionId",
+	},
+	antigravity: {
+		backend: "antigravity",
+		wakeMode: "direct-inject",
+		deliveryLevel: "D6",
+		nativeIdLabel: "conversationId",
+	},
+	codex: {
+		backend: "codex",
+		wakeMode: "direct-inject",
+		deliveryLevel: "D6",
+		nativeIdLabel: "threadId",
+	},
+};
+
+/**
+ * The read-receipt aspect, PRE-DRILLED (bbot review #4). The mailbox/outbox is
+ * post-MVP — these timestamps stay null until that path lands — but the slot is
+ * here so adding it later does not touch the schema twice.
+ *   - lastEnqueuedAt : a sender wrote a message body to this peer's mailbox.
+ *   - lastDeliveredAt: the doorbell rang / the body was injected ("`.delivered`"
+ *     marker). For Claude self-fetch this means "doorbell rang", NOT "model read".
+ *   - lastReadAt     : the inbox-read MCP call — THIS is the real read-receipt
+ *     (makes Claude's D7 observable). For direct-inject backends delivered==read.
+ */
+export interface MetaDelivery {
+	wakeMode: WakeMode;
+	deliveryLevel: string;
+	lastEnqueuedAt: string | null;
+	lastDeliveredAt: string | null;
+	lastReadAt: string | null;
+}
+
+/**
+ * The opaque pointer record. Body is SSOT; the on-disk filename
+ * (`<garden_id>.meta.json`) is only a denote-sortable surface (garden_id leads
+ * with the birth timestamp). NEVER parse the filename for authority.
+ */
+export interface MetaRecord {
+	schemaVersion: typeof META_SCHEMA_VERSION;
+	gardenId: string;
+	backend: MetaBackend;
+	nativeSessionId: string;
+	transcriptPath: string;
+	cwd: string;
+	createdAt: string;
+	lastSeen: string;
+	delivery: MetaDelivery;
+}
+
+/** Fields the caller supplies; garden id + timestamps + delivery are derived. */
+export interface MetaMintInput {
+	backend: MetaBackend;
+	nativeSessionId: string;
+	transcriptPath: string;
+	cwd: string;
+}
+
+// ---------------------------------------------------------------------------
+// Validation helpers (crash, don't warn)
+// ---------------------------------------------------------------------------
+
+function requireNonEmptyString(value: unknown, field: string): string {
+	if (typeof value !== "string" || value.length === 0) {
+		throw new MetaRecordError(`meta-record field "${field}" must be a non-empty string (got ${describe(value)}).`);
+	}
+	return value;
+}
+
+function requireBackend(value: unknown): MetaBackend {
+	if (typeof value !== "string" || !META_BACKENDS.includes(value as MetaBackend)) {
+		throw new MetaRecordError(
+			`meta-record "backend" must be one of ${META_BACKENDS.join(" | ")} (got ${describe(value)}).`,
+		);
+	}
+	return value as MetaBackend;
+}
+
+function requireGardenId(value: unknown): string {
+	const id = requireNonEmptyString(value, "gardenId");
+	if (!SESSION_ID_RE.test(id)) {
+		throw new MetaRecordError(`meta-record "gardenId" must match YYYYMMDDTHHMMSS-[0-9a-f]{6} (got "${id}").`);
+	}
+	return id;
+}
+
+function requireNullableString(value: unknown, field: string): string | null {
+	if (value === null) return null;
+	if (typeof value !== "string" || value.length === 0) {
+		throw new MetaRecordError(
+			`meta-record field "${field}" must be a non-empty string or null (got ${describe(value)}).`,
+		);
+	}
+	return value;
+}
+
+function describe(value: unknown): string {
+	if (value === null) return "null";
+	if (typeof value === "string") return `string ${JSON.stringify(value)}`;
+	return `${typeof value}`;
+}
+
+function isoNow(now: Date): string {
+	return now.toISOString();
+}
+
+// ---------------------------------------------------------------------------
+// Record functions (pure beyond an injected `now`, except mint/parse read the
+// packaged capability registry via the cached metaCapabilityFor seam — 3D-3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a brand-new meta-record at the session's true birth. Generates the garden
+ * id from the SSOT grammar, stamps createdAt == lastSeen, and seeds the
+ * delivery/read-receipt slot from the backend descriptor (timestamps null).
+ */
+export function mintMetaRecord(input: MetaMintInput, now: Date = new Date()): MetaRecord {
+	const backend = requireBackend(input.backend);
+	// 3D-3: backend honesty metadata is sourced from the capability registry, not
+	// META_BACKEND_DESCRIPTORS (which now survives only as the drift-guard reference).
+	const capability = metaCapabilityFor(backend);
+	const ts = isoNow(now);
+	return {
+		schemaVersion: META_SCHEMA_VERSION,
+		gardenId: generateSessionId(now),
+		backend,
+		nativeSessionId: requireNonEmptyString(input.nativeSessionId, "nativeSessionId"),
+		transcriptPath: requireNonEmptyString(input.transcriptPath, "transcriptPath"),
+		cwd: requireNonEmptyString(input.cwd, "cwd"),
+		createdAt: ts,
+		lastSeen: ts,
+		delivery: {
+			wakeMode: capability.wakeMode,
+			deliveryLevel: capability.deliveryLevel,
+			lastEnqueuedAt: null,
+			lastDeliveredAt: null,
+			lastReadAt: null,
+		},
+	};
+}
+
+/**
+ * Canonical serialization: stable key order (object built in order), 2-space
+ * indent, trailing newline. Deterministic — the same record always serializes
+ * byte-identically, so a temp-dir test can assert round-trip stability.
+ */
+export function serializeMetaRecord(record: MetaRecord): string {
+	const ordered = {
+		schemaVersion: record.schemaVersion,
+		gardenId: record.gardenId,
+		backend: record.backend,
+		nativeSessionId: record.nativeSessionId,
+		transcriptPath: record.transcriptPath,
+		cwd: record.cwd,
+		createdAt: record.createdAt,
+		lastSeen: record.lastSeen,
+		delivery: {
+			wakeMode: record.delivery.wakeMode,
+			deliveryLevel: record.delivery.deliveryLevel,
+			lastEnqueuedAt: record.delivery.lastEnqueuedAt,
+			lastDeliveredAt: record.delivery.lastDeliveredAt,
+			lastReadAt: record.delivery.lastReadAt,
+		},
+	};
+	return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+
+/** Parse + fully validate untrusted JSON text into a MetaRecord. Throws on any drift. */
+export function parseMetaRecord(json: string): MetaRecord {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(json);
+	} catch (err) {
+		throw new MetaRecordError(`meta-record is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		throw new MetaRecordError(`meta-record must be a JSON object (got ${describe(raw)}).`);
+	}
+	const obj = raw as Record<string, unknown>;
+	if (obj.schemaVersion !== META_SCHEMA_VERSION) {
+		throw new MetaRecordError(
+			`meta-record "schemaVersion" must be ${META_SCHEMA_VERSION} (got ${describe(obj.schemaVersion)}).`,
+		);
+	}
+	const delivery = obj.delivery;
+	if (typeof delivery !== "object" || delivery === null || Array.isArray(delivery)) {
+		throw new MetaRecordError(`meta-record "delivery" must be an object (got ${describe(delivery)}).`);
+	}
+	const d = delivery as Record<string, unknown>;
+	const backend = requireBackend(obj.backend);
+	const wakeMode = requireNonEmptyString(d.wakeMode, "delivery.wakeMode");
+	if (wakeMode !== "self-fetch" && wakeMode !== "direct-inject") {
+		throw new MetaRecordError(
+			`meta-record "delivery.wakeMode" must be self-fetch | direct-inject (got "${wakeMode}").`,
+		);
+	}
+	// wakeMode is backend-DETERMINED (Claude doorbell = self-fetch; agy/codex =
+	// direct-inject). A record whose stored wakeMode contradicts its backend is
+	// corrupt — a Claude record claiming direct-inject would silently mis-route
+	// the "last 1 cm" delivery contract. Refuse it. 3D-3: the canonical is sourced
+	// from the capability registry, not META_BACKEND_DESCRIPTORS.
+	const canonicalWakeMode = metaCapabilityFor(backend).wakeMode;
+	if (wakeMode !== canonicalWakeMode) {
+		throw new MetaRecordError(
+			`meta-record "delivery.wakeMode" (${wakeMode}) contradicts backend "${backend}" ` +
+				`(canonical ${canonicalWakeMode}). Delivery mode is backend-determined; this record is corrupt.`,
+		);
+	}
+	return {
+		schemaVersion: META_SCHEMA_VERSION,
+		gardenId: requireGardenId(obj.gardenId),
+		backend,
+		nativeSessionId: requireNonEmptyString(obj.nativeSessionId, "nativeSessionId"),
+		transcriptPath: requireNonEmptyString(obj.transcriptPath, "transcriptPath"),
+		cwd: requireNonEmptyString(obj.cwd, "cwd"),
+		createdAt: requireNonEmptyString(obj.createdAt, "createdAt"),
+		lastSeen: requireNonEmptyString(obj.lastSeen, "lastSeen"),
+		delivery: {
+			wakeMode,
+			deliveryLevel: requireNonEmptyString(d.deliveryLevel, "delivery.deliveryLevel"),
+			lastEnqueuedAt: requireNullableString(d.lastEnqueuedAt, "delivery.lastEnqueuedAt"),
+			lastDeliveredAt: requireNullableString(d.lastDeliveredAt, "delivery.lastDeliveredAt"),
+			lastReadAt: requireNullableString(d.lastReadAt, "delivery.lastReadAt"),
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// meta-record v2 — identity-only shape (0.11 Stage 0 step 3A)
+//
+// v2 strips the delivery/read-receipt aspect OUT of the record (it moves to a
+// separate mailbox state file in step 3B) and keeps only IDENTITY: who this
+// citizen is, never its delivery bookkeeping. The deltas vs v1 (verified
+// against the frozen ledger in NEXT.md):
+//   - backend gains `pi` (the 4th meta backend — pi sessions become citizens)
+//   - transcriptPath required → nullable (pi birth may not know it yet)
+//   - new nullable identity fields: model, parentGardenId, isEntwurf
+//   - lastSeen → recordUpdatedAt (a record touch time, NOT liveness)
+//   - delivery{} removed entirely
+//
+// This block is READER + NORMALIZER ONLY. There is deliberately NO v2 writer /
+// serializer / disk upsert here yet: step 3A's gate is "synthetic v1 fixture →
+// normalized v2 identity golden GREEN", and 3A must not introduce a v2 writer
+// before that golden + its GPT review (NEXT.md 끊을 지점 ①).
+// ---------------------------------------------------------------------------
+
+/** Bump only on a breaking v2 identity-shape change; the v2 parser refuses other versions. */
+export const META_SCHEMA_VERSION_V2 = 2 as const;
+
+/** v2 backends = the three v1 backends + `pi` (pi joins as the 4th meta citizen). */
+export const META_BACKENDS_V2 = ["claude-code", "antigravity", "codex", "pi"] as const;
+export type MetaBackendV2 = (typeof META_BACKENDS_V2)[number];
+
+/**
+ * The v2 identity-only record. Field order mirrors the frozen ledger's jsonc so
+ * a future serializer stays byte-stable. No delivery aspect — that is mailbox
+ * state (step 3B), referenced by gardenId, never embedded in identity.
+ */
+export interface MetaIdentity {
+	schemaVersion: typeof META_SCHEMA_VERSION_V2;
+	gardenId: string;
+	backend: MetaBackendV2;
+	nativeSessionId: string;
+	cwd: string;
+	model: string | null;
+	transcriptPath: string | null;
+	parentGardenId: string | null;
+	isEntwurf: boolean;
+	createdAt: string;
+	recordUpdatedAt: string;
+}
+
+function requireBackendV2(value: unknown): MetaBackendV2 {
+	if (typeof value !== "string" || !META_BACKENDS_V2.includes(value as MetaBackendV2)) {
+		throw new MetaRecordError(
+			`meta-record "backend" must be one of ${META_BACKENDS_V2.join(" | ")} (got ${describe(value)}).`,
+		);
+	}
+	return value as MetaBackendV2;
+}
+
+function requireBoolean(value: unknown, field: string): boolean {
+	if (typeof value !== "boolean") {
+		throw new MetaRecordError(`meta-record field "${field}" must be a boolean (got ${describe(value)}).`);
+	}
+	return value;
+}
+
+function requireNullableGardenId(value: unknown, field: string): string | null {
+	if (value === null) return null;
+	const id = requireNonEmptyString(value, field);
+	if (!SESSION_ID_RE.test(id)) {
+		throw new MetaRecordError(
+			`meta-record "${field}" must be null or match YYYYMMDDTHHMMSS-[0-9a-f]{6} (got "${id}").`,
+		);
+	}
+	return id;
+}
+
+/**
+ * Explicit v1 name for the dual-read pair. `parseMetaRecord` predates the v2
+ * split and stays the canonical v1 parser (existing callers untouched); this
+ * alias makes the V1/V2 symmetry legible at call sites.
+ */
+export const parseMetaRecordV1 = parseMetaRecord;
+
+/**
+ * The EXACT key set a v2 identity record may carry. v2 is a fresh schema, so the
+ * parser is strict: any key outside this set — including stale v1 fields like
+ * `delivery` or `lastSeen` — is a half-migrated / corrupt record and must
+ * fail-fast, never be silently normalized away. Frozen against the ledger jsonc.
+ */
+const META_IDENTITY_V2_KEYS: readonly string[] = [
+	"schemaVersion",
+	"gardenId",
+	"backend",
+	"nativeSessionId",
+	"cwd",
+	"model",
+	"transcriptPath",
+	"parentGardenId",
+	"isEntwurf",
+	"createdAt",
+	"recordUpdatedAt",
+];
+
+/** Parse + fully validate untrusted JSON into a v2 MetaIdentity. Throws on any drift. */
+export function parseMetaRecordV2(json: string): MetaIdentity {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(json);
+	} catch (err) {
+		throw new MetaRecordError(`meta-record is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		throw new MetaRecordError(`meta-record must be a JSON object (got ${describe(raw)}).`);
+	}
+	const obj = raw as Record<string, unknown>;
+	if (obj.schemaVersion !== META_SCHEMA_VERSION_V2) {
+		throw new MetaRecordError(
+			`meta-record "schemaVersion" must be ${META_SCHEMA_VERSION_V2} (got ${describe(obj.schemaVersion)}).`,
+		);
+	}
+	// Strict keyset: reject stale v1 fields (delivery/lastSeen) and any unknown
+	// key. A v2 record carrying v1 leftovers is half-migrated/corrupt — surface
+	// it, do not silently drop it during normalize.
+	const stray = Object.keys(obj).filter((k) => !META_IDENTITY_V2_KEYS.includes(k));
+	if (stray.length > 0) {
+		throw new MetaRecordError(
+			`v2 meta-record carries unexpected key(s) ${stray.map((k) => `"${k}"`).join(", ")} ` +
+				`(allowed: ${META_IDENTITY_V2_KEYS.join(", ")}). Stale v1 fields (delivery/lastSeen) or unknown keys are rejected.`,
+		);
+	}
+	return {
+		schemaVersion: META_SCHEMA_VERSION_V2,
+		gardenId: requireGardenId(obj.gardenId),
+		backend: requireBackendV2(obj.backend),
+		nativeSessionId: requireNonEmptyString(obj.nativeSessionId, "nativeSessionId"),
+		cwd: requireNonEmptyString(obj.cwd, "cwd"),
+		model: requireNullableString(obj.model, "model"),
+		transcriptPath: requireNullableString(obj.transcriptPath, "transcriptPath"),
+		parentGardenId: requireNullableGardenId(obj.parentGardenId, "parentGardenId"),
+		isEntwurf: requireBoolean(obj.isEntwurf, "isEntwurf"),
+		createdAt: requireNonEmptyString(obj.createdAt, "createdAt"),
+		recordUpdatedAt: requireNonEmptyString(obj.recordUpdatedAt, "recordUpdatedAt"),
+	};
+}
+
+/**
+ * Lazy-normalize a parsed v1 OR v2 record into the v2 identity shape. The dual-
+ * read seam: consumers read either disk version and normalize to ONE identity
+ * type. Discriminates on `schemaVersion` (TS narrows the union):
+ *   - v1: lastSeen → recordUpdatedAt, delivery dropped, model/parentGardenId
+ *     default null, isEntwurf default false, transcriptPath carried (v1 always
+ *     has one).
+ *   - v2: already identity — returned as a fresh, key-stable copy.
+ * v1 identity is LOSSLESS through this (the golden gate proves it); the only v1
+ * data not carried is delivery, which is intentionally out of identity.
+ */
+export function normalizeMetaIdentity(record: MetaRecord | MetaIdentity): MetaIdentity {
+	if (record.schemaVersion === META_SCHEMA_VERSION_V2) {
+		return {
+			schemaVersion: META_SCHEMA_VERSION_V2,
+			gardenId: record.gardenId,
+			backend: record.backend,
+			nativeSessionId: record.nativeSessionId,
+			cwd: record.cwd,
+			model: record.model,
+			transcriptPath: record.transcriptPath,
+			parentGardenId: record.parentGardenId,
+			isEntwurf: record.isEntwurf,
+			createdAt: record.createdAt,
+			recordUpdatedAt: record.recordUpdatedAt,
+		};
+	}
+	return {
+		schemaVersion: META_SCHEMA_VERSION_V2,
+		gardenId: record.gardenId,
+		backend: record.backend,
+		nativeSessionId: record.nativeSessionId,
+		cwd: record.cwd,
+		model: null,
+		transcriptPath: record.transcriptPath,
+		parentGardenId: null,
+		isEntwurf: false,
+		createdAt: record.createdAt,
+		recordUpdatedAt: record.lastSeen,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// v2 write shape + dual-read dispatcher (0.11 Stage 0 step 3D-1)
+//
+// Pure functions only: the canonical v2 serializer and the version-dispatching
+// reader. NO fs upsert, NO live readMetaInbox/enqueueMetaMessage change, NO
+// record.delivery removal — those are 3D-2/3/4. This step just makes "write a v2
+// identity" and "read any version into an identity" exist + gated, so 3D-4 can
+// wire the FS upsert onto a proven writer.
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical serialization of a v2 identity: stable key order (the frozen ledger
+ * jsonc order), 2-space indent, trailing newline. Deterministic — re-serializing
+ * the same identity is byte-identical, and the output round-trips through
+ * parseMetaRecordV2. This is the v2 WRITE shape; the FS upsert that uses it is
+ * step 3D-4, not here.
+ */
+export function serializeMetaIdentity(identity: MetaIdentity): string {
+	const ordered = {
+		schemaVersion: identity.schemaVersion,
+		gardenId: identity.gardenId,
+		backend: identity.backend,
+		nativeSessionId: identity.nativeSessionId,
+		cwd: identity.cwd,
+		model: identity.model,
+		transcriptPath: identity.transcriptPath,
+		parentGardenId: identity.parentGardenId,
+		isEntwurf: identity.isEntwurf,
+		createdAt: identity.createdAt,
+		recordUpdatedAt: identity.recordUpdatedAt,
+	};
+	return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+
+/**
+ * Fields a v2 caller supplies; garden id + timestamps are derived. The nullable
+ * identity axes (model/transcriptPath/parentGardenId) are OPTIONAL at the input
+ * boundary so attach can distinguish three intents (3D-4 G5): `undefined` = keep
+ * the existing value, `null` = explicit unknown/clear, a string = set/refresh.
+ * mint (create) has no existing value, so undefined collapses to null.
+ */
+export interface MetaIdentityMintInput {
+	backend: MetaBackendV2;
+	nativeSessionId: string;
+	cwd: string;
+	model?: string | null;
+	transcriptPath?: string | null;
+	parentGardenId?: string | null;
+	isEntwurf?: boolean;
+}
+
+/**
+ * Mint a brand-new v2 identity at the session's true birth (3D-4). The v2 analog
+ * of mintMetaRecord — generates the garden id, stamps createdAt == recordUpdatedAt,
+ * and carries identity only (no delivery; the receipt lives in mailbox state).
+ * Omitted nullable axes default to null / isEntwurf false.
+ */
+export function mintMetaIdentity(input: MetaIdentityMintInput, now: Date = new Date()): MetaIdentity {
+	const backend = requireBackendV2(input.backend);
+	const ts = isoNow(now);
+	return {
+		schemaVersion: META_SCHEMA_VERSION_V2,
+		gardenId: generateSessionId(now),
+		backend,
+		nativeSessionId: requireNonEmptyString(input.nativeSessionId, "nativeSessionId"),
+		cwd: requireNonEmptyString(input.cwd, "cwd"),
+		model: requireNullableString(input.model ?? null, "model"),
+		transcriptPath: requireNullableString(input.transcriptPath ?? null, "transcriptPath"),
+		parentGardenId: requireNullableGardenId(input.parentGardenId ?? null, "parentGardenId"),
+		isEntwurf: input.isEntwurf === undefined ? false : requireBoolean(input.isEntwurf, "isEntwurf"),
+		createdAt: ts,
+		recordUpdatedAt: ts,
+	};
+}
+
+/**
+ * Dual-read dispatcher: peek schemaVersion on untrusted JSON and route to the
+ * matching strict parser (v1 record or v2 identity). The lazy-normalize seam — a
+ * consumer reads either on-disk version through ONE call. Returns the parsed
+ * record in its OWN shape (v1 keeps delivery; v2 is identity); compose with
+ * normalizeMetaIdentity, or use parseMetaIdentity, to collapse to identity.
+ */
+export function parseMetaRecordAny(json: string): MetaRecord | MetaIdentity {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(json);
+	} catch (err) {
+		throw new MetaRecordError(`meta-record is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		throw new MetaRecordError(`meta-record must be a JSON object (got ${describe(raw)}).`);
+	}
+	const version = (raw as Record<string, unknown>).schemaVersion;
+	if (version === META_SCHEMA_VERSION) return parseMetaRecordV1(json);
+	if (version === META_SCHEMA_VERSION_V2) return parseMetaRecordV2(json);
+	throw new MetaRecordError(
+		`meta-record "schemaVersion" must be ${META_SCHEMA_VERSION} or ${META_SCHEMA_VERSION_V2} (got ${describe(version)}).`,
+	);
+}
+
+/** Dual-read straight to a normalized v2 identity (parse any version, normalize). */
+export function parseMetaIdentity(json: string): MetaIdentity {
+	return normalizeMetaIdentity(parseMetaRecordAny(json));
+}
+
+// ---------------------------------------------------------------------------
+// capability source — backend capability registry (0.11 Stage 0 step 3C)
+//
+// v2 identity (step 3A) drops the backend honesty metadata (wakeMode /
+// deliveryLevel / nativeIdLabel) out of the per-session record: it is NOT per
+// session, it is per BACKEND. Its new home is a registry data file
+// `pi/entwurf-capabilities.json` (frozen decision 1 — a registry FILE, sibling
+// concern to the launch-allowlist `entwurf-targets.json`). "이 시민은 self-fetch
+// 인가 / pi 는 어떻게 깨우나" is answered by capability, not by identity.
+//
+// This block is the SCHEMA + PARSER + path resolver. As of 3C it did NOT re-wire
+// the live consumers (`META_BACKEND_DESCRIPTORS` was the authority mint/parse read).
+// 3D-3 then cut mint/parse over to this registry via the `metaCapabilityFor` seam
+// (defined below `metaCapabilitiesFilePath`): the registry is now the LIVE source of
+// wakeMode/deliveryLevel, and `META_BACKEND_DESCRIPTORS` survives only as the
+// drift-guard reference. Removing wakeMode from the record itself lands in step 3D-4.
+// The 3C gate (check-entwurf-capabilities) still asserts the JSON AGREES with the
+// const for the three existing backends (the drift guard) and COVERS exactly
+// META_BACKENDS_V2 (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.
+// ---------------------------------------------------------------------------
+
+/** Bump only on a breaking capability-registry shape change; the parser refuses other versions. */
+export const CAPABILITY_SCHEMA_VERSION = 1 as const;
+
+/** One backend's capability — the honesty metadata that leaves the v2 record. */
+export interface MetaCapability {
+	wakeMode: WakeMode;
+	deliveryLevel: string;
+	nativeIdLabel: string;
+}
+
+/** The whole registry: schema version + one capability per v2 backend. */
+export interface MetaCapabilityRegistry {
+	schemaVersion: typeof CAPABILITY_SCHEMA_VERSION;
+	backends: Record<MetaBackendV2, MetaCapability>;
+}
+
+const CAPABILITY_TOP_KEYS: readonly string[] = ["schemaVersion", "backends"];
+const CAPABILITY_ENTRY_KEYS: readonly string[] = ["wakeMode", "deliveryLevel", "nativeIdLabel"];
+
+function requireWakeMode(value: unknown, field: string): WakeMode {
+	if (value !== "self-fetch" && value !== "direct-inject") {
+		throw new MetaRecordError(`capability "${field}" must be self-fetch | direct-inject (got ${describe(value)}).`);
+	}
+	return value;
+}
+
+function parseCapabilityEntry(value: unknown, backend: string): MetaCapability {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new MetaRecordError(`capability for "${backend}" must be an object (got ${describe(value)}).`);
+	}
+	const obj = value as Record<string, unknown>;
+	const stray = Object.keys(obj).filter((k) => !CAPABILITY_ENTRY_KEYS.includes(k));
+	if (stray.length > 0) {
+		throw new MetaRecordError(
+			`capability for "${backend}" carries unexpected key(s) ${stray.map((k) => `"${k}"`).join(", ")} ` +
+				`(allowed: ${CAPABILITY_ENTRY_KEYS.join(", ")}).`,
+		);
+	}
+	return {
+		wakeMode: requireWakeMode(obj.wakeMode, `${backend}.wakeMode`),
+		deliveryLevel: requireNonEmptyString(obj.deliveryLevel, `${backend}.deliveryLevel`),
+		nativeIdLabel: requireNonEmptyString(obj.nativeIdLabel, `${backend}.nativeIdLabel`),
+	};
+}
+
+/**
+ * Parse + fully validate untrusted JSON into a capability registry. Strict:
+ * schemaVersion fence, top-level + per-entry keyset, and COVERAGE — the backend
+ * keys must be exactly META_BACKENDS_V2 (no missing, no extra). A registry that
+ * forgets pi, or smuggles an unknown backend, is rejected.
+ */
+export function parseMetaCapabilityRegistry(json: string): MetaCapabilityRegistry {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(json);
+	} catch (err) {
+		throw new MetaRecordError(
+			`capability registry is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		throw new MetaRecordError(`capability registry must be a JSON object (got ${describe(raw)}).`);
+	}
+	const obj = raw as Record<string, unknown>;
+	if (obj.schemaVersion !== CAPABILITY_SCHEMA_VERSION) {
+		throw new MetaRecordError(
+			`capability registry "schemaVersion" must be ${CAPABILITY_SCHEMA_VERSION} (got ${describe(obj.schemaVersion)}).`,
+		);
+	}
+	const topStray = Object.keys(obj).filter((k) => !CAPABILITY_TOP_KEYS.includes(k));
+	if (topStray.length > 0) {
+		throw new MetaRecordError(
+			`capability registry carries unexpected key(s) ${topStray.map((k) => `"${k}"`).join(", ")} ` +
+				`(allowed: ${CAPABILITY_TOP_KEYS.join(", ")}).`,
+		);
+	}
+	const backends = obj.backends;
+	if (typeof backends !== "object" || backends === null || Array.isArray(backends)) {
+		throw new MetaRecordError(`capability registry "backends" must be an object (got ${describe(backends)}).`);
+	}
+	const present = Object.keys(backends).sort();
+	const expected = [...META_BACKENDS_V2].sort();
+	if (present.length !== expected.length || !expected.every((b, i) => b === present[i])) {
+		throw new MetaRecordError(
+			`capability registry must cover exactly ${expected.join(", ")} (got ${present.join(", ")}).`,
+		);
+	}
+	const entries = backends as Record<string, unknown>;
+	const out = {} as Record<MetaBackendV2, MetaCapability>;
+	for (const backend of META_BACKENDS_V2) {
+		out[backend] = parseCapabilityEntry(entries[backend], backend);
+	}
+	return { schemaVersion: CAPABILITY_SCHEMA_VERSION, backends: out };
+}
+
+/**
+ * The packaged capability registry path. Two layouts resolve:
+ *  - repo / npm package: `pi-extensions/lib/` → `<root>/pi/entwurf-capabilities.json`.
+ *  - bundled meta-bridge plugin: `../../pi` would ESCAPE the plugin dir (the plugin
+ *    is installed under a version dir in the Claude plugin cache), so the registry
+ *    travels AT the plugin root and resolves via `../` from `lib/`.
+ *    meta-bridge-install.sh copies it there; doctor-meta-bridge asserts its presence.
+ * Repo path is tried first, so repo/package behaviour is unchanged; the bundle
+ * fallback only engages where the repo layout is absent.
+ */
+export function metaCapabilitiesFilePath(): string {
+	const repoPath = path.join(import.meta.dirname, "..", "..", "pi", "entwurf-capabilities.json");
+	if (fs.existsSync(repoPath)) return repoPath;
+	return path.join(import.meta.dirname, "..", "entwurf-capabilities.json");
+}
+
+// ---------------------------------------------------------------------------
+// capability live source (0.11 Stage 0 step 3D-3)
+//
+// 3C shipped the registry FILE + parser but left META_BACKEND_DESCRIPTORS as the
+// authority that mint/parse read (3C header: "Cutting the live const over to this
+// registry ... lands in step 3D"). 3D-3 is that cut-over: mint/parse now read
+// backend honesty metadata (wakeMode/deliveryLevel) from the registry via the seam
+// below, NOT from the const. The const survives ONLY as the drift-guard reference
+// in check-entwurf-capabilities (registry ≡ const for the 3 existing backends), so
+// the cut-over is behaviour-preserving. The record.delivery.wakeMode SLOT stays
+// (its removal is 3D-4); only its SOURCE moves.
+// ---------------------------------------------------------------------------
+
+/** Memoized packaged registry; the file is immutable at runtime, so caching is honest (not stateful lying). */
+let cachedMetaCapabilities: MetaCapabilityRegistry | null = null;
+
+/**
+ * Load + memoize the packaged capability registry — the live source of backend
+ * honesty metadata as of 3D-3. A missing/corrupt file throws (the registry is a
+ * packaged invariant; check-pack guarantees its presence).
+ */
+export function loadMetaCapabilityRegistry(): MetaCapabilityRegistry {
+	if (cachedMetaCapabilities === null) {
+		cachedMetaCapabilities = parseMetaCapabilityRegistry(fs.readFileSync(metaCapabilitiesFilePath(), "utf8"));
+	}
+	return cachedMetaCapabilities;
+}
+
+/**
+ * The capability for one backend, from the registry (3D-3 live source). The
+ * optional `registry` injection lets a gate prove the value is registry-DRIVEN
+ * (feed a doctored registry → the lookup follows it), distinguishing "read from
+ * the registry" from "hardcoded off the const". Param is `MetaBackendV2` (all 4):
+ * `backends` is `Record<MetaBackendV2, …>`, so the lookup is total — mint/parse
+ * still pass the 3 `MetaBackend` values (a subset), and the v2 decider's mailbox
+ * deliverability passes the unsupported backends (which are MetaBackendV2 to the
+ * type system even though pi never reaches that call at runtime).
+ */
+export function metaCapabilityFor(
+	backend: MetaBackendV2,
+	registry: MetaCapabilityRegistry = loadMetaCapabilityRegistry(),
+): MetaCapability {
+	return registry.backends[backend];
+}
+
+/** Denote-sortable on-disk filename. Body is SSOT; do NOT parse this for authority. Accepts v1 record or v2 identity. */
+export function metaRecordFilename(record: MetaRecord | MetaIdentity): string {
+	return `${record.gardenId}.meta.json`;
+}
+
+/**
+ * THE lookup authority. Scan the record BODIES in a meta-session directory and
+ * return the one whose top-level `nativeSessionId` matches, or null. This is the
+ * `.meta.json` analog of 0.9.0 `findSessionFileById` (which header-scans pi
+ * JSONLs). NOT a filename parse, NOT an index lookup — those are at best derived
+ * caches. The directory listing + record reading is injected so this stays a
+ * pure function (the step-3 CLI supplies the real fs).
+ *
+ * The scan runs to completion (does NOT stop at the first match): the
+ * native→garden mapping MUST be unique, so two records claiming the same
+ * `nativeSessionId` is an authority ambiguity — `MetaRecordError`, fail-fast,
+ * never silently pick one (that would make `upsert` mint a second id / route a
+ * message to the wrong garden citizen).
+ *
+ * Unreadable / malformed entries are surfaced honestly via `onSkip` (a corrupt
+ * record is a real problem, not something to silently swallow); a throwing
+ * reader for one file does not abort the whole scan.
+ */
+export function scanByNativeId(
+	entries: readonly string[],
+	nativeSessionId: string,
+	readRecord: (filename: string) => string,
+	onSkip?: (filename: string, err: Error) => void,
+): MetaRecord | null {
+	const target = requireNonEmptyString(nativeSessionId, "nativeSessionId");
+	const matches: { filename: string; record: MetaRecord }[] = [];
+	for (const filename of entries) {
+		if (!filename.endsWith(".meta.json")) continue;
+		let record: MetaRecord;
+		try {
+			record = parseMetaRecord(readRecord(filename));
+		} catch (err) {
+			onSkip?.(filename, err instanceof Error ? err : new Error(String(err)));
+			continue;
+		}
+		if (record.nativeSessionId === target) matches.push({ filename, record });
+	}
+	if (matches.length > 1) {
+		throw new MetaRecordError(
+			`ambiguous meta-record authority: nativeSessionId "${target}" matched ${matches.length} records ` +
+				`(${matches.map((m) => m.filename).join(", ")}). The native→garden mapping must be unique — ` +
+				`fail-fast rather than silently picking one. Remove the duplicate(s).`,
+		);
+	}
+	return matches.length === 1 ? (matches[0] as { record: MetaRecord }).record : null;
+}
+
+/**
+ * The dual-read identity scan (0.11 Stage 0 step 3D-4 commit1, additive). Same
+ * lookup authority as scanByNativeId — scan the BODIES, match on top-level
+ * `nativeSessionId`, fail-fast on duplicates — but reads v1 AND v2 records (via
+ * parseMetaIdentity) and returns normalized identity. This is the scan the v2
+ * upsert uses (3D-4): once upsert writes v2, the existence check MUST recognize v2
+ * records or it would mint a duplicate id for an existing citizen (G1). scanByNativeId
+ * remains the v1-only raw scan for v1-fixture gates. Identity-only: it reads
+ * backend/nativeSessionId, never delivery.
+ */
+export function scanIdentityByNativeId(
+	entries: readonly string[],
+	nativeSessionId: string,
+	readRecord: (filename: string) => string,
+	onSkip?: (filename: string, err: Error) => void,
+): MetaIdentity | null {
+	const target = requireNonEmptyString(nativeSessionId, "nativeSessionId");
+	const matches: { filename: string; identity: MetaIdentity }[] = [];
+	for (const filename of entries) {
+		if (!filename.endsWith(".meta.json")) continue;
+		let identity: MetaIdentity;
+		try {
+			identity = parseMetaIdentity(readRecord(filename));
+		} catch (err) {
+			onSkip?.(filename, err instanceof Error ? err : new Error(String(err)));
+			continue;
+		}
+		if (identity.nativeSessionId === target) matches.push({ filename, identity });
+	}
+	if (matches.length > 1) {
+		throw new MetaRecordError(
+			`ambiguous meta-record authority: nativeSessionId "${target}" matched ${matches.length} records ` +
+				`(${matches.map((m) => m.filename).join(", ")}). The native→garden mapping must be unique — ` +
+				`fail-fast rather than silently picking one. Remove the duplicate(s).`,
+		);
+	}
+	return matches.length === 1 ? (matches[0] as { identity: MetaIdentity }).identity : null;
+}
+
+/** One unreadable meta-record, surfaced as an explicit fact — file + message
+ * ONLY, never a half-parsed identity field. A salvaged gid-looking string
+ * presented as a fact is a synthetic backdoor; verbatim-or-nothing. */
+export interface MetaRecordReadError {
+	filename: string;
+	message: string;
+}
+
+export interface ListIdentitiesResult {
+	identities: MetaIdentity[];
+	errors: MetaRecordReadError[];
+}
+
+/**
+ * Scan every meta-record in a store into identities + explicit read errors.
+ * Pure over injected (entries, readRecord) so gates drive it without IO; the
+ * fact-provider (slice 4b) supplies the real readdir/readFile.
+ *
+ * A record that fails to parse — or whose body gardenId drifts from its filename
+ * (the same authority check as `readMetaIdentityByGardenId`) — is NEITHER
+ * silently skipped (that hides a broken citizen = lie by omission) NOR allowed to
+ * throw the whole listing (one corrupt file must not blind `entwurf_peers` — the
+ * 0.10 "corrupt blocks registration forever" lesson). It becomes an explicit
+ * error entry carrying ONLY filename + message. Duplicate gardenId across files
+ * is impossible: the filename IS `<gardenId>.meta.json`, so the filesystem
+ * already enforces uniqueness — only body/filename drift can split authority.
+ *
+ * mode "collect" (default) returns partial results; "strict" throws if ANY
+ * record was unreadable (doctor / gate callers wanting all-or-nothing).
+ */
+export function listAllMetaIdentities(
+	entries: readonly string[],
+	readRecord: (filename: string) => string,
+	opts: { mode?: "collect" | "strict" } = {},
+): ListIdentitiesResult {
+	const identities: MetaIdentity[] = [];
+	const errors: MetaRecordReadError[] = [];
+	for (const filename of entries) {
+		if (!filename.endsWith(".meta.json")) continue;
+		let identity: MetaIdentity;
+		try {
+			identity = parseMetaIdentity(readRecord(filename));
+		} catch (err) {
+			errors.push({ filename, message: err instanceof Error ? err.message : String(err) });
+			continue;
+		}
+		const expected = filename.slice(0, -".meta.json".length);
+		if (identity.gardenId !== expected) {
+			errors.push({
+				filename,
+				message: `body/filename drift: body gardenId "${identity.gardenId}" ≠ filename. The body is the authority; this file is corrupt.`,
+			});
+			continue;
+		}
+		identities.push(identity);
+	}
+	if (opts.mode === "strict" && errors.length > 0) {
+		throw new MetaRecordError(
+			`listAllMetaIdentities(strict): ${errors.length} unreadable meta-record(s): ${errors
+				.map((e) => `${e.filename} (${e.message})`)
+				.join("; ")}`,
+		);
+	}
+	identities.sort((a, b) => (a.gardenId < b.gardenId ? -1 : a.gardenId > b.gardenId ? 1 : 0));
+	errors.sort((a, b) => (a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0));
+	return { identities, errors };
+}
+
+export type UpsertAction = "create" | "attach";
+
+export interface UpsertDecision {
+	action: UpsertAction;
+	record: MetaIdentity;
+}
+
+/**
+ * The pure core of the `upsert` CLI (3D-4: v2 identity). Keyed on RECORD
+ * EXISTENCE, never on a backend `source` field:
+ *   - existing present → ATTACH: keep identity (gardenId, createdAt,
+ *     nativeSessionId), bump recordUpdatedAt, and apply the 3-value merge to the
+ *     nullable axes + always-refresh cwd. Identity drift (a different backend for
+ *     the same nativeSessionId) is corruption → throw.
+ *   - absent → CREATE: mint a fresh v2 identity.
+ *
+ * 3-value attach merge (G5): for model/transcriptPath/parentGardenId an input of
+ * `undefined` KEEPS the existing value (a pi-birth caller that does not know the
+ * transcript must not wipe a previously-recorded one), `null` explicitly clears
+ * it, a string sets it. cwd is required and always refreshed.
+ *
+ * Idempotent by construction: calling it twice with the same input yields one
+ * attach after the first create, never a second id. `existing` is the normalized
+ * identity from scanIdentityByNativeId (dual-read v1+v2).
+ */
+export function decideUpsert(
+	existing: MetaIdentity | null,
+	input: MetaIdentityMintInput,
+	now: Date = new Date(),
+): UpsertDecision {
+	const backend = requireBackendV2(input.backend);
+	const nativeSessionId = requireNonEmptyString(input.nativeSessionId, "nativeSessionId");
+	const cwd = requireNonEmptyString(input.cwd, "cwd");
+
+	if (existing === null) {
+		return { action: "create", record: mintMetaIdentity(input, now) };
+	}
+	if (existing.nativeSessionId !== nativeSessionId) {
+		throw new MetaRecordError(
+			`decideUpsert called with existing record for a different nativeSessionId ` +
+				`(existing="${existing.nativeSessionId}", input="${nativeSessionId}"). ` +
+				`The caller must pass the record found by scanIdentityByNativeId(input.nativeSessionId).`,
+		);
+	}
+	if (existing.backend !== backend) {
+		throw new MetaRecordError(
+			`meta-record identity drift: nativeSessionId "${nativeSessionId}" is bound to backend ` +
+				`"${existing.backend}" but upsert input says "${backend}". A native session cannot change backend.`,
+		);
+	}
+	// 3-value merge (G5): undefined keeps existing, null clears, string sets. The
+	// nullable axes are validated the same way mint validates them.
+	const model = input.model === undefined ? existing.model : requireNullableString(input.model, "model");
+	const transcriptPath =
+		input.transcriptPath === undefined
+			? existing.transcriptPath
+			: requireNullableString(input.transcriptPath, "transcriptPath");
+	const parentGardenId =
+		input.parentGardenId === undefined
+			? existing.parentGardenId
+			: requireNullableGardenId(input.parentGardenId, "parentGardenId");
+	const isEntwurf = input.isEntwurf === undefined ? existing.isEntwurf : requireBoolean(input.isEntwurf, "isEntwurf");
+	return {
+		action: "attach",
+		record: { ...existing, cwd, model, transcriptPath, parentGardenId, isEntwurf, recordUpdatedAt: isoNow(now) },
+	};
+}
+
+// ---------------------------------------------------------------------------
+// read-receipt mutators — V1-RECORD ONLY (3D-4 H3). These mutate record.delivery,
+// which exists only on the v1 schema. The LIVE enqueue/read path no longer calls
+// them (3D-4 the cut: the receipt lives in the mailbox state store, stamped by
+// stampMailboxReceipt). They are retained for the v1-fixture / dual-read gates that
+// still exercise a raw v1 record; do NOT re-wire them into the live path.
+// ---------------------------------------------------------------------------
+
+/** A sender enqueued a body to this peer's mailbox. (v1-record only — see section note.) */
+export function markEnqueued(record: MetaRecord, now: Date = new Date()): MetaRecord {
+	return { ...record, delivery: { ...record.delivery, lastEnqueuedAt: isoNow(now) } };
+}
+
+/** The doorbell rang / body injected ("`.delivered`"). For self-fetch ≠ read. */
+export function markDelivered(record: MetaRecord, now: Date = new Date()): MetaRecord {
+	return { ...record, delivery: { ...record.delivery, lastDeliveredAt: isoNow(now) } };
+}
+
+/** The inbox-read MCP call — the real read-receipt (makes Claude D7 observable). */
+export function markRead(record: MetaRecord, now: Date = new Date()): MetaRecord {
+	return { ...record, delivery: { ...record.delivery, lastReadAt: isoNow(now) } };
+}
+
+// ---------------------------------------------------------------------------
+// FS-bound store (step 3) — the thin real-filesystem wrapper around the pure
+// core. Only node builtins beyond the pure layer, so the deterministic gate
+// stays strip-types clean (see module header for why this is not a sibling file).
+// ---------------------------------------------------------------------------
+
+function expandTilde(p: string): string {
+	if (p === "~") return os.homedir();
+	if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+	return p;
+}
+
+/**
+ * The pi agent dir — the persistence root pi owns. `PI_CODING_AGENT_DIR` lets an
+ * isolated install / test relocate it (symmetric with how pi's own sessions
+ * isolate); otherwise it is the fixed `~/.pi/agent`. A stable `~/` path, so the
+ * meta-bridge hook never needs this baked into config — it resolves at runtime.
+ */
+function piAgentDir(): string {
+	return process.env.PI_CODING_AGENT_DIR
+		? path.resolve(expandTilde(process.env.PI_CODING_AGENT_DIR))
+		: path.join(os.homedir(), ".pi", "agent");
+}
+
+/**
+ * Where meta-records live. Under the pi agent dir (pi owns persistence), so an
+ * isolated install / test that sets `PI_CODING_AGENT_DIR` gets isolated
+ * meta-sessions too — symmetric with how pi's own sessions isolate. A direct
+ * `ENTWURF_META_SESSIONS_DIR` override wins (used by tests / unusual deployments).
+ */
+export function defaultMetaSessionsDir(): string {
+	if (process.env.ENTWURF_META_SESSIONS_DIR) return path.resolve(expandTilde(process.env.ENTWURF_META_SESSIONS_DIR));
+	return path.join(piAgentDir(), "meta-sessions");
+}
+
+/**
+ * Where per-garden-id idle-wake mailboxes live: `<pi-agent-dir>/meta-mailbox`.
+ * Deliberately a SIBLING of meta-sessions, not nested inside it — the record
+ * store is the authority (scanned for identity) while the mailbox is volatile
+ * signal/body traffic; keeping them apart means a mailbox poke never risks a
+ * record-dir readdir picking up a non-record file. The watched signal for a
+ * session is `<this>/<gardenId>/inbox.signal`. Same runtime resolution as
+ * meta-sessions (no config baking); `ENTWURF_META_MAILBOX_DIR` overrides for tests.
+ */
+export function defaultMetaMailboxDir(): string {
+	if (process.env.ENTWURF_META_MAILBOX_DIR) return path.resolve(expandTilde(process.env.ENTWURF_META_MAILBOX_DIR));
+	return path.join(piAgentDir(), "meta-mailbox");
+}
+
+/**
+ * Where native-backend SENDER markers live: `<pi-agent-dir>/meta-senders`.
+ *
+ * The problem this closes: a native Claude Code session that SENDS via the
+ * user-scope entwurf-bridge MCP has no `PI_SESSION_ID` — at tool-call time the
+ * MCP process does not know which garden-id session it belongs to, so the sender
+ * envelope degrades to anonymous `external-mcp` and the receiver has no reply
+ * address. The hook DOES know the garden-id (it just minted the record), and the
+ * hook + the MCP child run under the SAME Claude Code parent process. So the hook
+ * writes a marker keyed by that parent pid; the MCP reads the marker for its OWN
+ * `process.ppid` and promotes itself to a replyable meta-session sender. This
+ * uses process ancestry, NOT cwd inference (same repo / multiple sessions would
+ * make cwd ambiguous). `ENTWURF_META_SENDERS_DIR` overrides for tests.
+ */
+export function defaultMetaSendersDir(): string {
+	if (process.env.ENTWURF_META_SENDERS_DIR) return path.resolve(expandTilde(process.env.ENTWURF_META_SENDERS_DIR));
+	return path.join(piAgentDir(), "meta-senders");
+}
+
+/**
+ * Where native-backend RECEIVER presence markers live: `<pi-agent-dir>/meta-receivers`.
+ *
+ * The problem this closes (SE-2): a meta-record proves a session once EXISTED, not
+ * that it is still a live receiver that a reply could reach. A self-fetch backend
+ * (Claude Code) has no control socket to probe, so "is this receiver active right
+ * now?" needs its own signal. The SessionStart/CwdChanged/FileChanged hook — the
+ * event that actually arms the watchPaths idle-wake — writes a presence marker keyed
+ * by GARDEN id (the universal address a sender targets), carrying the watch owner pid
+ * + its start-key. A reader trusts it only while that pid is still the same live
+ * process (start-key match); a terminated session leaves a marker whose owner is gone,
+ * so it reads as inactive instead of a ghost active-receiver. UNLIKE the sender marker
+ * (keyed by owner pid, a pid→garden hint), this is keyed by garden id because the
+ * deliverability question starts from a target garden id. `ENTWURF_META_RECEIVERS_DIR`
+ * overrides for tests.
+ */
+export function defaultMetaReceiversDir(): string {
+	if (process.env.ENTWURF_META_RECEIVERS_DIR) return path.resolve(expandTilde(process.env.ENTWURF_META_RECEIVERS_DIR));
+	return path.join(piAgentDir(), "meta-receivers");
+}
+
+/**
+ * A boot-unique identity for a live process: pid is reused, but pid + start-time
+ * is unique within a boot. Linux reads `/proc/<pid>/stat` field 22 (starttime in
+ * clock ticks); macOS/BSD falls back to `ps -o lstart=`. Returns "" when the pid
+ * is gone or unreadable — a "" key never matches, so a dead/reused owner fails
+ * the marker check. This is what stops a stale marker (process exited, pid reused
+ * by a new Claude session) from granting the wrong garden-id sender identity.
+ */
+export function processStartKey(pid: number): string {
+	if (!Number.isInteger(pid) || pid <= 0) return "";
+	try {
+		const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+		// comm (field 2) is parenthesized and may contain spaces/parens — split AFTER the last ')'.
+		const fields = stat
+			.slice(stat.lastIndexOf(")") + 1)
+			.trim()
+			.split(/\s+/);
+		// after comm: index 0 = state(f3), 1 = ppid(f4), … 19 = starttime(f22).
+		const starttime = fields[19];
+		if (starttime && /^\d+$/.test(starttime)) return `linux:${starttime}`;
+	} catch {
+		// not Linux / no procfs
+	}
+	try {
+		const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" }).trim();
+		if (out) return `ps:${out}`;
+	} catch {
+		// pid gone or ps unavailable
+	}
+	return "";
+}
+
+/** The parent pid of a pid (one ancestry step), or null when unknown. */
+export function parentPid(pid: number): number | null {
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	try {
+		const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+		const fields = stat
+			.slice(stat.lastIndexOf(")") + 1)
+			.trim()
+			.split(/\s+/);
+		const ppid = Number(fields[1]); // f4
+		if (Number.isInteger(ppid) && ppid > 0) return ppid;
+	} catch {
+		// not Linux
+	}
+	try {
+		const out = execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8" }).trim();
+		const ppid = Number(out);
+		if (Number.isInteger(ppid) && ppid > 0) return ppid;
+	} catch {
+		// pid gone
+	}
+	return null;
+}
+
+export interface MetaSenderMarker {
+	backend: MetaBackend;
+	gardenId: string;
+	nativeSessionId: string;
+	cwd: string;
+	/** The pid this marker is keyed to (the shared native runner / Claude parent). */
+	ownerPid: number;
+	/** processStartKey(ownerPid) at write time — the pid-reuse guard. */
+	ownerStartKey: string;
+	updatedAt: string;
+}
+
+/** `<sendersDir>/<backend>/<ownerPid>.json` — keyed by the shared parent pid. */
+export function metaSenderMarkerPath(
+	backend: MetaBackend,
+	ownerPid: number,
+	sendersDir: string = defaultMetaSendersDir(),
+): string {
+	return path.join(sendersDir, backend, `${ownerPid}.json`);
+}
+
+export interface WriteMetaSenderMarkerOptions {
+	backend: MetaBackend;
+	gardenId: string;
+	nativeSessionId: string;
+	cwd: string;
+	ownerPid: number;
+	sendersDir?: string;
+	now?: Date;
+}
+
+/** Write (atomically) the sender marker for a native session's parent pid. */
+export function writeMetaSenderMarker(opts: WriteMetaSenderMarkerOptions): string {
+	const backend = requireBackend(opts.backend);
+	const gardenId = requireGardenId(opts.gardenId);
+	const file = metaSenderMarkerPath(backend, opts.ownerPid, opts.sendersDir ?? defaultMetaSendersDir());
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const marker: MetaSenderMarker = {
+		backend,
+		gardenId,
+		nativeSessionId: requireNonEmptyString(opts.nativeSessionId, "nativeSessionId"),
+		cwd: requireNonEmptyString(opts.cwd, "cwd"),
+		ownerPid: opts.ownerPid,
+		ownerStartKey: processStartKey(opts.ownerPid),
+		updatedAt: isoNow(opts.now ?? new Date()),
+	};
+	const tmp = `${file}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+	fs.writeFileSync(tmp, `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600 });
+	fs.renameSync(tmp, file);
+	return file;
+}
+
+export interface ReadMetaSenderMarkerOptions {
+	/** Explicit marker file (test / explicit wiring). Wins over backend+ownerPid. */
+	markerPath?: string;
+	backend?: MetaBackend;
+	ownerPid?: number;
+	sendersDir?: string;
+	/** Run the pid-reuse guard (verify the owner pid is still live). Default true —
+	 * set false only for unit assertions that exercise the marker without a live owner. */
+	verifyOwner?: boolean;
+}
+
+/**
+ * Read the sender marker for this MCP process's owner. Returns null when absent
+ * or corrupt — a marker we cannot trust means "no authoritative sender", which
+ * the caller turns into external-non-replyable (or a hard reject under
+ * REQUIRE_META_SENDER). Never throws: an unreadable marker must not break a send.
+ */
+export function readMetaSenderMarker(opts: ReadMetaSenderMarkerOptions): MetaSenderMarker | null {
+	let file = opts.markerPath;
+	if (!file && opts.backend && typeof opts.ownerPid === "number") {
+		file = metaSenderMarkerPath(opts.backend, opts.ownerPid, opts.sendersDir ?? defaultMetaSendersDir());
+	}
+	if (!file || !fs.existsSync(file)) return null;
+	try {
+		const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+		const marker: MetaSenderMarker = {
+			backend: requireBackend(raw.backend),
+			gardenId: requireGardenId(raw.gardenId),
+			nativeSessionId: requireNonEmptyString(raw.nativeSessionId, "nativeSessionId"),
+			cwd: requireNonEmptyString(raw.cwd, "cwd"),
+			ownerPid: typeof raw.ownerPid === "number" ? raw.ownerPid : Number.NaN,
+			ownerStartKey: requireNonEmptyString(raw.ownerStartKey, "ownerStartKey"),
+			updatedAt: requireNonEmptyString(raw.updatedAt, "updatedAt"),
+		};
+		// pid-reuse guard (unless explicitly disabled): the owner pid must STILL be
+		// the same process that wrote the marker. A bare pid is reused; pid+startKey
+		// is boot-unique, so a stale marker from a dead session fails here instead of
+		// granting a wrong-identity send.
+		if (opts.verifyOwner !== false) {
+			if (!Number.isInteger(marker.ownerPid)) return null;
+			const liveKey = processStartKey(marker.ownerPid);
+			if (!liveKey || liveKey !== marker.ownerStartKey) return null;
+		}
+		return marker;
+	} catch {
+		return null;
+	}
+}
+
+// ── meta-receiver presence marker (SE-2 active-receiver signal) ──────────────
+
+/**
+ * The arm-capable hook events. Only these can emit watchPaths (and therefore arm
+ * the idle-wake), so only these write a receiver presence marker. UserPromptSubmit
+ * is deliberately absent: it can backfill the record but cannot re-arm the watch, so
+ * it must NOT mint or refresh an "active receiver" claim it cannot back.
+ */
+export const META_RECEIVER_ARM_PROVENANCES = ["session-start", "cwd-changed", "file-changed"] as const;
+export type MetaReceiverArmProvenance = (typeof META_RECEIVER_ARM_PROVENANCES)[number];
+
+function requireArmProvenance(value: unknown): MetaReceiverArmProvenance {
+	if (typeof value === "string" && (META_RECEIVER_ARM_PROVENANCES as readonly string[]).includes(value)) {
+		return value as MetaReceiverArmProvenance;
+	}
+	throw new Error(
+		`invalid armProvenance: ${JSON.stringify(value)} (expected one of ${META_RECEIVER_ARM_PROVENANCES.join(", ")})`,
+	);
+}
+
+export interface MetaReceiverMarker {
+	gardenId: string;
+	backend: MetaBackend;
+	nativeSessionId: string;
+	/** The pid holding the watchPaths idle-wake subscription (the native CLI = hook's process.ppid). */
+	ownerPid: number;
+	/** processStartKey(ownerPid) at write time — the dead-owner / pid-reuse guard. */
+	ownerStartKey: string;
+	/** The kind of process that owns the watch. Currently always the native CLI, not the plugin host. */
+	ownerKind: string;
+	/** Which arm-capable event wrote this presence (never user-prompt-submit). */
+	armProvenance: MetaReceiverArmProvenance;
+	updatedAt: string;
+}
+
+/** `<receiversDir>/<gardenId>.json` — keyed by garden id (the universal address). */
+export function metaReceiverMarkerPath(gardenId: string, receiversDir: string = defaultMetaReceiversDir()): string {
+	return path.join(receiversDir, `${requireGardenId(gardenId)}.json`);
+}
+
+export interface WriteMetaReceiverMarkerOptions {
+	gardenId: string;
+	backend: MetaBackend;
+	nativeSessionId: string;
+	ownerPid: number;
+	armProvenance: MetaReceiverArmProvenance;
+	/** Defaults to "claude-code-cli" — the watchPaths subscriber. */
+	ownerKind?: string;
+	receiversDir?: string;
+	now?: Date;
+}
+
+/** Write (atomically) the receiver presence marker for a garden id. */
+export function writeMetaReceiverMarker(opts: WriteMetaReceiverMarkerOptions): string {
+	const gardenId = requireGardenId(opts.gardenId);
+	const backend = requireBackend(opts.backend);
+	const file = metaReceiverMarkerPath(gardenId, opts.receiversDir ?? defaultMetaReceiversDir());
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const marker: MetaReceiverMarker = {
+		gardenId,
+		backend,
+		nativeSessionId: requireNonEmptyString(opts.nativeSessionId, "nativeSessionId"),
+		ownerPid: opts.ownerPid,
+		ownerStartKey: processStartKey(opts.ownerPid),
+		ownerKind: requireNonEmptyString(opts.ownerKind ?? "claude-code-cli", "ownerKind"),
+		armProvenance: requireArmProvenance(opts.armProvenance),
+		updatedAt: isoNow(opts.now ?? new Date()),
+	};
+	const tmp = `${file}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+	fs.writeFileSync(tmp, `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600 });
+	fs.renameSync(tmp, file);
+	return file;
+}
+
+export interface ReadMetaReceiverMarkerOptions {
+	/** Explicit marker file (test / explicit wiring). Wins over gardenId. */
+	markerPath?: string;
+	gardenId?: string;
+	receiversDir?: string;
+	/** Run the dead-owner / pid-reuse guard (verify the owner pid is still the same live process).
+	 * Default true — set false only for unit assertions that inspect a marker without a live owner. */
+	verifyOwner?: boolean;
+}
+
+/**
+ * Read the receiver presence marker for a garden id. Returns null when absent,
+ * corrupt, or (under verifyOwner) the owner pid is no longer the same live process —
+ * each means "no active receiver", which the deliverability predicate turns into
+ * not-deliverable. Never throws: an unreadable marker must not break a send path.
+ * Record-backing is NOT checked here (the caller / predicate supplies recordBacked
+ * as an explicit fact, so an absent record and a dead owner stay distinguishable).
+ */
+export function readMetaReceiverMarker(opts: ReadMetaReceiverMarkerOptions): MetaReceiverMarker | null {
+	let file = opts.markerPath;
+	if (!file && opts.gardenId) {
+		file = metaReceiverMarkerPath(opts.gardenId, opts.receiversDir ?? defaultMetaReceiversDir());
+	}
+	if (!file || !fs.existsSync(file)) return null;
+	try {
+		const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+		const marker: MetaReceiverMarker = {
+			gardenId: requireGardenId(raw.gardenId),
+			backend: requireBackend(raw.backend),
+			nativeSessionId: requireNonEmptyString(raw.nativeSessionId, "nativeSessionId"),
+			ownerPid: typeof raw.ownerPid === "number" ? raw.ownerPid : Number.NaN,
+			ownerStartKey: requireNonEmptyString(raw.ownerStartKey, "ownerStartKey"),
+			ownerKind: requireNonEmptyString(raw.ownerKind, "ownerKind"),
+			armProvenance: requireArmProvenance(raw.armProvenance),
+			updatedAt: requireNonEmptyString(raw.updatedAt, "updatedAt"),
+		};
+		if (opts.verifyOwner !== false) {
+			if (!Number.isInteger(marker.ownerPid)) return null;
+			const liveKey = processStartKey(marker.ownerPid);
+			if (!liveKey || liveKey !== marker.ownerStartKey) return null;
+		}
+		return marker;
+	} catch {
+		return null;
+	}
+}
+
+export interface UpsertMetaSessionOptions {
+	input: MetaIdentityMintInput;
+	/** Override the store directory (defaults to {@link defaultMetaSessionsDir}). */
+	dir?: string;
+	/** Override the mailbox dir (defaults to {@link defaultMetaMailboxDir}) — only the v1→v2 receipt migration touches it. */
+	mailboxDir?: string;
+	now?: Date;
+	onSkip?: (filename: string, err: Error) => void;
+}
+
+export interface UpsertMetaSessionResult {
+	action: UpsertAction;
+	record: MetaIdentity;
+	dir: string;
+	/** Absolute path of the written record. */
+	path: string;
+}
+
+/**
+ * Idempotent fs upsert (3D-4: writes v2 identity). Scan the store by
+ * `nativeSessionId` with the dual-read identity scan (sees v1 AND v2, so an
+ * existing citizen is found regardless of schema — never duplicate-mint, G1),
+ * decide create vs attach on EXISTENCE, and write atomically as v2. On attach the
+ * file is the existing garden id's record (same path, rewritten in place, v1→v2);
+ * on create it is a fresh `<gardenId>.meta.json`. A duplicate `nativeSessionId`
+ * throws (via the scan) rather than silently picking one.
+ *
+ * Crash-order (3D-4): when the matched file is still v1, its delivery receipts are
+ * migrated to the mailbox state store BEFORE the v2 rewrite. If the process dies
+ * between the two, the record is still v1 → the next attach re-migrates (state-wins
+ * merge is idempotent), so no receipt is lost. The reverse order would lose the
+ * receipt permanently. The write is tmp-file + rename so a crash never leaves a
+ * half-written record (#30 crash-safety).
+ */
+export function upsertMetaSession(opts: UpsertMetaSessionOptions): UpsertMetaSessionResult {
+	const dir = path.resolve(expandTilde(opts.dir ?? defaultMetaSessionsDir()));
+	fs.mkdirSync(dir, { recursive: true });
+	const entries = fs.readdirSync(dir);
+	const readRaw = (filename: string) => fs.readFileSync(path.join(dir, filename), "utf8");
+	const existing = scanIdentityByNativeId(entries, opts.input.nativeSessionId, readRaw, opts.onSkip);
+
+	// Crash-order: migrate a v1 file's receipts to mailbox state BEFORE rewriting it
+	// as v2. Re-read the matched file raw to see if it is still v1 (carries delivery).
+	if (existing !== null) {
+		const raw = parseMetaRecordAny(readRaw(`${existing.gardenId}.meta.json`));
+		if (raw.schemaVersion === META_SCHEMA_VERSION) {
+			migrateV1DeliveryReceipts({ gardenId: existing.gardenId, delivery: raw.delivery, mailboxDir: opts.mailboxDir });
+		}
+	}
+
+	const decision = decideUpsert(existing, opts.input, opts.now);
+	const file = path.join(dir, metaRecordFilename(decision.record));
+	atomicWriteIdentity(file, decision.record);
+	return { action: decision.action, record: decision.record, dir, path: file };
+}
+
+/** tmp-file + rename so a crash never leaves a half-written record (v2 identity write). */
+function atomicWriteIdentity(file: string, identity: MetaIdentity): void {
+	const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+	fs.writeFileSync(tmp, serializeMetaIdentity(identity), { mode: 0o600 });
+	fs.renameSync(tmp, file);
+}
+
+// ---------------------------------------------------------------------------
+// Mailbox delivery (step 6) — addressed by GARDEN ID. The record store is the
+// authority (a sender may only deliver to a known garden citizen); the mailbox
+// under defaultMetaMailboxDir() carries the volatile signal + message bodies.
+//
+// The honest delivery contract (do not blur these):
+//   - enqueue        : a sender wrote a `.msg` body + poked `inbox.signal`
+//                      (markEnqueued). The poke is what the plugin's FileChanged
+//                      doorbell watches — it wakes an idle session.
+//   - `.msg.delivered`: the doorbell rang (FileChanged moved `.msg` ->
+//                      `.msg.delivered` and announced it). A FILESYSTEM marker =
+//                      WAKE ATTEMPT, NOT a read.
+//   - lastReadAt     : the model called readMetaInbox (the inbox-read tool) and
+//                      the body actually reached model-visible context. THIS is
+//                      the real D7 read-receipt. For Claude self-fetch, delivered
+//                      != read; readMetaInbox is the only thing that sets it.
+// ---------------------------------------------------------------------------
+
+/** Resolve + validate a garden id and return its record file path under a store dir. */
+function recordFileFor(sessionsDir: string, gardenId: string): string {
+	const id = requireGardenId(gardenId);
+	return path.join(path.resolve(expandTilde(sessionsDir)), `${id}.meta.json`);
+}
+
+/**
+ * Read + parse a V1 meta-record by garden id, or throw if unknown (3D-4: renamed
+ * from readMetaRecordByGardenId, demoted to v1-only — it uses the strict v1 parser
+ * and throws on a v2 file). The live path reads identity via
+ * readMetaIdentityByGardenId (dual-read); this stays for v1-fixture / dual-read
+ * gates that need the raw v1 record (with delivery).
+ */
+export function readMetaRecordV1ByGardenId(
+	gardenId: string,
+	sessionsDir: string = defaultMetaSessionsDir(),
+): MetaRecord {
+	const id = requireGardenId(gardenId);
+	const file = recordFileFor(sessionsDir, id);
+	if (!fs.existsSync(file)) {
+		throw new MetaRecordError(
+			`no meta-record for garden id "${id}" under ${path.dirname(file)} — not a garden citizen, cannot deliver.`,
+		);
+	}
+	const record = parseMetaRecord(fs.readFileSync(file, "utf8"));
+	// The record BODY is the SSOT; the filename is only a denote-sortable surface.
+	// A `<id>.meta.json` whose body carries a DIFFERENT gardenId is corrupt (a
+	// renamed/clobbered file) and would misroute delivery — fail-fast, never trust
+	// the filename over the body.
+	if (record.gardenId !== id) {
+		throw new MetaRecordError(
+			`meta-record body/filename drift: ${id}.meta.json contains gardenId "${record.gardenId}". ` +
+				`The body is the authority; this file is corrupt. Remove or fix it.`,
+		);
+	}
+	return record;
+}
+
+/**
+ * The dual-read identity read-by-gardenId (0.11 Stage 0 step 3D-4 commit1,
+ * additive). Same contract as readMetaRecordByGardenId — read the file, body is
+ * SSOT, fail-fast on body/filename gardenId drift — but reads v1 AND v2 (via
+ * parseMetaIdentity) and returns normalized identity. This is what the live path
+ * uses (enqueue/read, the MCP sender-marker check) so it survives the v2 cut;
+ * readMetaRecordV1ByGardenId remains the v1-only raw reader for v1-fixture gates.
+ */
+export function readMetaIdentityByGardenId(
+	gardenId: string,
+	sessionsDir: string = defaultMetaSessionsDir(),
+): MetaIdentity {
+	const id = requireGardenId(gardenId);
+	const file = recordFileFor(sessionsDir, id);
+	if (!fs.existsSync(file)) {
+		throw new MetaRecordError(
+			`no meta-record for garden id "${id}" under ${path.dirname(file)} — not a garden citizen, cannot deliver.`,
+		);
+	}
+	const identity = parseMetaIdentity(fs.readFileSync(file, "utf8"));
+	if (identity.gardenId !== id) {
+		throw new MetaRecordError(
+			`meta-record body/filename drift: ${id}.meta.json contains gardenId "${identity.gardenId}". ` +
+				`The body is the authority; this file is corrupt. Remove or fix it.`,
+		);
+	}
+	return identity;
+}
+
+/**
+ * Probe-free existence check for a garden citizen's meta-record. Used by the 5d
+ * entwurf_v2 production `resolveTarget`: a MISSING record is a soft `bad-target`
+ * (identity:null), but a PRESENT-but-corrupt record must fail loud — so the producer
+ * `existsSync`-checks here FIRST and only calls `readMetaIdentityByGardenId` when this
+ * returns true, leaving drift/corruption as the lone throw (never matched by message
+ * string). Validates the gid (F2-P1) like its read sibling.
+ */
+export function metaRecordExistsByGardenId(gardenId: string, sessionsDir: string = defaultMetaSessionsDir()): boolean {
+	const id = requireGardenId(gardenId);
+	return fs.existsSync(recordFileFor(sessionsDir, id));
+}
+
+export interface EnqueueMetaMessageOptions {
+	gardenId: string;
+	body: string;
+	sessionsDir?: string;
+	mailboxDir?: string;
+	now?: Date;
+}
+
+export interface EnqueueMetaMessageResult {
+	gardenId: string;
+	recordPath: string;
+	messagePath: string;
+	signalPath: string;
+}
+
+/**
+ * Deliver a message body to a garden citizen's mailbox: validate the record
+ * exists, write the `.msg` body FIRST, stamp `lastEnqueuedAt`, then poke
+ * `inbox.signal` LAST so the doorbell that fires on the poke always finds the
+ * body already on disk (no wake-with-empty-mailbox race). Returns the paths so a
+ * sender can show exactly what was queued.
+ */
+export function enqueueMetaMessage(opts: EnqueueMetaMessageOptions): EnqueueMetaMessageResult {
+	const now = opts.now ?? new Date();
+	const sessionsDir = opts.sessionsDir ?? defaultMetaSessionsDir();
+	const recordFile = recordFileFor(sessionsDir, opts.gardenId);
+	// 3D-4: read IDENTITY (dual-read v1+v2) — confirms the citizen exists and
+	// normalizes the gardenId. The record is no longer mutated; the v2 record carries
+	// no delivery, so the enqueue receipt lives SOLELY in the mailbox state store.
+	const citizen = readMetaIdentityByGardenId(opts.gardenId, sessionsDir);
+	if (typeof opts.body !== "string" || opts.body.length === 0) {
+		throw new MetaRecordError("enqueueMetaMessage: body must be a non-empty string.");
+	}
+
+	const dir = path.join(path.resolve(expandTilde(opts.mailboxDir ?? defaultMetaMailboxDir())), citizen.gardenId);
+	fs.mkdirSync(dir, { recursive: true });
+	// Sortable + unique: ISO stamp (colons/dots flattened for a clean filename) +
+	// a short random tag so two sends in the same millisecond never collide.
+	const stamp = `${isoNow(now).replace(/[:.]/g, "-")}-${crypto.randomBytes(3).toString("hex")}`;
+	const messagePath = path.join(dir, `${stamp}.msg`);
+	fs.writeFileSync(messagePath, opts.body, { mode: 0o600 });
+
+	// 3D-4 the cut: the enqueue receipt lives SOLELY in the mailbox state store now
+	// (record.delivery removed from the v2 record). No record write. Stamped before the
+	// signal poke so all state is settled before the watch fires. A state-stamp throw
+	// surfaces fail-loud — no rollback: the `.msg` may already be written, but the
+	// caller never gets a silent success.
+	stampMailboxReceipt({
+		gardenId: citizen.gardenId,
+		mailboxDir: opts.mailboxDir ?? defaultMetaMailboxDir(),
+		field: "lastEnqueuedAt",
+		now,
+	});
+
+	// Poke LAST. Writing the timestamp changes the file's content+mtime, which is
+	// what the plugin's FileChanged watch fires on.
+	const signalPath = path.join(dir, "inbox.signal");
+	fs.writeFileSync(signalPath, `${isoNow(now)}\n`, { mode: 0o600 });
+
+	return { gardenId: citizen.gardenId, recordPath: recordFile, messagePath, signalPath };
+}
+
+export interface MetaInboxMessage {
+	file: string;
+	body: string;
+}
+
+export interface ReadMetaInboxOptions {
+	gardenId: string;
+	sessionsDir?: string;
+	mailboxDir?: string;
+	now?: Date;
+}
+
+export interface ReadMetaInboxResult {
+	gardenId: string;
+	messages: MetaInboxMessage[];
+	/** The D7 read-receipt timestamp stamped on this read, or null if nothing was unread. */
+	readAt: string | null;
+	recordPath: string;
+}
+
+/**
+ * Drain a garden citizen's mailbox: read every unread message (a fresh `.msg`
+ * read before its doorbell, or a doorbell-rung `.msg.delivered`), archive each to
+ * `*.read` so a re-read never double-returns, and — only if at least one message
+ * was read — stamp `lastReadAt` (NOT `lastDeliveredAt`: the doorbell owns
+ * delivery-time, see the stamp-site note below). An empty inbox mutates nothing:
+ * reading nothing is not a receipt.
+ */
+export function readMetaInbox(opts: ReadMetaInboxOptions): ReadMetaInboxResult {
+	const now = opts.now ?? new Date();
+	const sessionsDir = opts.sessionsDir ?? defaultMetaSessionsDir();
+	const recordFile = recordFileFor(sessionsDir, opts.gardenId);
+	// 3D-4: read IDENTITY (dual-read) — citizen-existence + normalized gardenId. The
+	// record is not mutated; the read receipt lives solely in the mailbox state store.
+	const citizen = readMetaIdentityByGardenId(opts.gardenId, sessionsDir);
+
+	const dir = path.join(path.resolve(expandTilde(opts.mailboxDir ?? defaultMetaMailboxDir())), citizen.gardenId);
+	const entries = fs.existsSync(dir) ? fs.readdirSync(dir) : [];
+	// Unread = a body still ending in .msg or .msg.delivered (NOT yet .read).
+	const unread = entries.filter((f) => f.endsWith(".msg") || f.endsWith(".msg.delivered")).sort();
+
+	const messages: MetaInboxMessage[] = [];
+	for (const f of unread) {
+		const full = path.join(dir, f);
+		messages.push({ file: f, body: fs.readFileSync(full, "utf8") });
+		fs.renameSync(full, `${full}.read`); // archive; .read no longer matches the doorbell's *.msg glob
+	}
+
+	if (messages.length === 0) {
+		return { gardenId: citizen.gardenId, messages, readAt: null, recordPath: recordFile };
+	}
+
+	// 3D-4 the cut: the read receipt lives SOLELY in the mailbox state store now.
+	// Stamp lastReadAt — the one receipt this layer stamps honestly (it KNOWS the body
+	// reached the reader). lastDeliveredAt is the doorbell's to own; stamping it here
+	// would report read-time as delivery-time, so it is left as the doorbell left it.
+	// The state stamp returns the updated state, whose lastReadAt IS the D7 read-receipt.
+	// Inside the messages.length>0 branch by construction — an empty inbox already
+	// early-returned (no .read archive, state untouched), so "read nothing" is no
+	// receipt on the state either. A throw surfaces fail-loud — no rollback: the
+	// messages are already archived (.read), but the caller never gets a silent success.
+	const state = stampMailboxReceipt({
+		gardenId: citizen.gardenId,
+		mailboxDir: opts.mailboxDir ?? defaultMetaMailboxDir(),
+		field: "lastReadAt",
+		now,
+	});
+	return { gardenId: citizen.gardenId, messages, readAt: state.lastReadAt, recordPath: recordFile };
+}
+
+// ---------------------------------------------------------------------------
+// mailbox receipt state — the receipt authority's new home (0.11 Stage 0 3B)
+//
+// Today the read-receipt lives at `record.delivery.lastReadAt` (stamped by
+// readMetaInbox). v2 identity (step 3A) drops `delivery{}` out of the record, so
+// the receipt timestamps need a new home BEFORE that removal (NEXT.md 고정순서
+// 4: "delivery 제거 전 mailbox receipt state schema 먼저 못박음 ... 대체 state
+// 없이 제거 금지"). That home is `<meta-mailbox>/<gardenId>/state.json` — a
+// SIBLING of the inbox.signal/.msg traffic it accounts for, so the receipt lives
+// with the mailbox (volatile delivery bookkeeping), not with identity.
+//
+// This block is the SCHEMA + STORE only. It does NOT yet re-wire the live
+// enqueue/read path (that dual-write + the eventual record.delivery removal land
+// in step 3D, behind NEXT.md 끊을 지점 ②, so the "정당한 update vs regression"
+// gate-rewrite stays in one reviewed place). wakeMode/deliveryLevel are NOT here
+// — those are capability, not receipt (step 3C).
+// ---------------------------------------------------------------------------
+
+/** Bump only on a breaking receipt-state shape change; the parser refuses other versions. */
+export const MAILBOX_RECEIPT_SCHEMA_VERSION = 1 as const;
+
+/**
+ * The per-citizen mailbox receipt state. Holds exactly the three delivery
+ * timestamps that move out of `record.delivery` (wakeMode/deliveryLevel are
+ * capability, deliberately absent). Body is SSOT; the on-disk path is derived.
+ */
+export interface MailboxReceiptState {
+	schemaVersion: typeof MAILBOX_RECEIPT_SCHEMA_VERSION;
+	gardenId: string;
+	lastEnqueuedAt: string | null;
+	lastDeliveredAt: string | null;
+	lastReadAt: string | null;
+}
+
+/** The receipt timestamp fields a mutator may stamp (runtime SSOT for validation). */
+export const MAILBOX_RECEIPT_FIELDS = ["lastEnqueuedAt", "lastDeliveredAt", "lastReadAt"] as const;
+export type MailboxReceiptField = (typeof MAILBOX_RECEIPT_FIELDS)[number];
+
+/**
+ * Validate an untrusted field name at runtime. The TS `MailboxReceiptField`
+ * type does not survive a JS call site or an `as` cast — an invalid field would
+ * otherwise create a stray key in memory that `serialize` silently drops. Crash
+ * instead, mirroring the record layer's "crash, don't warn".
+ */
+function requireMailboxReceiptField(value: unknown): MailboxReceiptField {
+	if (typeof value !== "string" || !MAILBOX_RECEIPT_FIELDS.includes(value as MailboxReceiptField)) {
+		throw new MetaRecordError(
+			`stampMailboxReceipt "field" must be one of ${MAILBOX_RECEIPT_FIELDS.join(" | ")} (got ${describe(value)}).`,
+		);
+	}
+	return value as MailboxReceiptField;
+}
+
+/** A fresh, never-touched receipt state for a citizen (all timestamps null). */
+export function emptyMailboxReceiptState(gardenId: string): MailboxReceiptState {
+	return {
+		schemaVersion: MAILBOX_RECEIPT_SCHEMA_VERSION,
+		gardenId: requireGardenId(gardenId),
+		lastEnqueuedAt: null,
+		lastDeliveredAt: null,
+		lastReadAt: null,
+	};
+}
+
+/** Canonical serialization: stable key order, 2-space indent, trailing newline. */
+export function serializeMailboxReceiptState(state: MailboxReceiptState): string {
+	const ordered = {
+		schemaVersion: state.schemaVersion,
+		gardenId: state.gardenId,
+		lastEnqueuedAt: state.lastEnqueuedAt,
+		lastDeliveredAt: state.lastDeliveredAt,
+		lastReadAt: state.lastReadAt,
+	};
+	return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+
+const MAILBOX_RECEIPT_KEYS: readonly string[] = [
+	"schemaVersion",
+	"gardenId",
+	"lastEnqueuedAt",
+	"lastDeliveredAt",
+	"lastReadAt",
+];
+
+/** Parse + fully validate untrusted JSON into a MailboxReceiptState. Throws on any drift. */
+export function parseMailboxReceiptState(json: string): MailboxReceiptState {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(json);
+	} catch (err) {
+		throw new MetaRecordError(
+			`mailbox receipt state is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		throw new MetaRecordError(`mailbox receipt state must be a JSON object (got ${describe(raw)}).`);
+	}
+	const obj = raw as Record<string, unknown>;
+	if (obj.schemaVersion !== MAILBOX_RECEIPT_SCHEMA_VERSION) {
+		throw new MetaRecordError(
+			`mailbox receipt state "schemaVersion" must be ${MAILBOX_RECEIPT_SCHEMA_VERSION} (got ${describe(obj.schemaVersion)}).`,
+		);
+	}
+	const stray = Object.keys(obj).filter((k) => !MAILBOX_RECEIPT_KEYS.includes(k));
+	if (stray.length > 0) {
+		throw new MetaRecordError(
+			`mailbox receipt state carries unexpected key(s) ${stray.map((k) => `"${k}"`).join(", ")} ` +
+				`(allowed: ${MAILBOX_RECEIPT_KEYS.join(", ")}).`,
+		);
+	}
+	return {
+		schemaVersion: MAILBOX_RECEIPT_SCHEMA_VERSION,
+		gardenId: requireGardenId(obj.gardenId),
+		lastEnqueuedAt: requireNullableString(obj.lastEnqueuedAt, "lastEnqueuedAt"),
+		lastDeliveredAt: requireNullableString(obj.lastDeliveredAt, "lastDeliveredAt"),
+		lastReadAt: requireNullableString(obj.lastReadAt, "lastReadAt"),
+	};
+}
+
+/** The on-disk receipt-state path for a citizen: `<mailbox>/<gardenId>/state.json`. */
+export function mailboxReceiptStatePath(mailboxDir: string, gardenId: string): string {
+	return path.join(path.resolve(expandTilde(mailboxDir)), requireGardenId(gardenId), "state.json");
+}
+
+export interface MailboxReceiptOptions {
+	gardenId: string;
+	mailboxDir?: string;
+}
+
+/**
+ * Read a citizen's receipt state from disk, or an empty state if none exists
+ * yet. Reading-nothing is not an error — a citizen that has never had a receipt
+ * stamped simply has all-null timestamps (parallel to readMetaInbox treating an
+ * empty inbox as "no receipt", not a failure).
+ */
+export function readMailboxReceiptState(opts: MailboxReceiptOptions): MailboxReceiptState {
+	const gardenId = requireGardenId(opts.gardenId);
+	const file = mailboxReceiptStatePath(opts.mailboxDir ?? defaultMetaMailboxDir(), gardenId);
+	if (!fs.existsSync(file)) return emptyMailboxReceiptState(gardenId);
+	const state = parseMailboxReceiptState(fs.readFileSync(file, "utf8"));
+	// Body is SSOT, and the body gardenId must agree with the path it was read
+	// from — a state.json whose body claims a different citizen is corruption,
+	// fail-fast (parallel to readMetaRecordByGardenId's body/filename drift rule).
+	if (state.gardenId !== gardenId) {
+		throw new MetaRecordError(
+			`mailbox receipt state body/path gardenId drift — body gardenId=${state.gardenId}, read from <mailbox>/${gardenId}/state.json.`,
+		);
+	}
+	return state;
+}
+
+/**
+ * Stamp ONE receipt field to `now` and atomically persist the state (read-
+ * modify-write; creates the state on first stamp). Returns the updated state.
+ * The atomic tmp+rename mirrors atomicWriteRecord so a concurrent reader never
+ * observes a half-written state.json.
+ */
+export function stampMailboxReceipt(
+	opts: MailboxReceiptOptions & { field: MailboxReceiptField; now?: Date },
+): MailboxReceiptState {
+	const now = opts.now ?? new Date();
+	const field = requireMailboxReceiptField(opts.field);
+	const file = mailboxReceiptStatePath(opts.mailboxDir ?? defaultMetaMailboxDir(), opts.gardenId);
+	const current = readMailboxReceiptState(opts);
+	const updated: MailboxReceiptState = { ...current, [field]: isoNow(now) };
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+	fs.writeFileSync(tmp, serializeMailboxReceiptState(updated), { mode: 0o600 });
+	fs.renameSync(tmp, file);
+	return updated;
+}
+
+/** The v1 delivery receipt timestamps that migrate to mailbox state (the 3 only — wakeMode/deliveryLevel are capability). */
+export interface V1DeliveryReceipts {
+	lastEnqueuedAt: string | null;
+	lastDeliveredAt: string | null;
+	lastReadAt: string | null;
+}
+
+/**
+ * Migrate a v1 record's delivery receipts into the mailbox state store (3D-4),
+ * called by upsert BEFORE it rewrites a v1 file as v2 so a pre-3D-2 receipt is not
+ * lost. Per-field merge, STATE WINS: a v1 timestamp only fills a state field that
+ * is still null (`state[f] ?? v1[f]`); a state value already there is never
+ * overwritten. ONLY the 3 timestamps move — wakeMode/deliveryLevel are capability
+ * (registry), and a stray key would trip the receipt-state strict keyset (H2).
+ *
+ * "Migrating nothing is not a receipt": if no v1 value fills a null state field
+ * (state already wins on every field, or v1 had nothing), this is a NO-OP — no
+ * write, no state.json creation — returning null. Otherwise it writes the merged
+ * state atomically (tmp+rename, mirroring stampMailboxReceipt) and returns it.
+ */
+export function migrateV1DeliveryReceipts(opts: {
+	gardenId: string;
+	delivery: V1DeliveryReceipts;
+	mailboxDir?: string;
+}): MailboxReceiptState | null {
+	const gardenId = requireGardenId(opts.gardenId);
+	const mailboxDir = opts.mailboxDir ?? defaultMetaMailboxDir();
+	const current = readMailboxReceiptState({ gardenId, mailboxDir });
+	const merged: MailboxReceiptState = {
+		...current,
+		lastEnqueuedAt: current.lastEnqueuedAt ?? opts.delivery.lastEnqueuedAt,
+		lastDeliveredAt: current.lastDeliveredAt ?? opts.delivery.lastDeliveredAt,
+		lastReadAt: current.lastReadAt ?? opts.delivery.lastReadAt,
+	};
+	if (
+		merged.lastEnqueuedAt === current.lastEnqueuedAt &&
+		merged.lastDeliveredAt === current.lastDeliveredAt &&
+		merged.lastReadAt === current.lastReadAt
+	) {
+		return null; // no-write / no-create — migrating nothing is not a receipt
+	}
+	const file = mailboxReceiptStatePath(mailboxDir, gardenId);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+	fs.writeFileSync(tmp, serializeMailboxReceiptState(merged), { mode: 0o600 });
+	fs.renameSync(tmp, file);
+	return merged;
+}