@junghanacs/entwurf 0.12.0

package/scripts/check-meta-session.ts

@@ -0,0 +1,673 @@
+/**
+ * check-meta-session — deterministic gate for the 1.0.0 meta-bridge record
+ * authority (step 2). Pure functions + a real temp-dir scan; no backend, no
+ * network, no hook. Safe in the `pnpm check` static floor.
+ *
+ * Proves the contract the later hook/CLI/mailbox steps build on:
+ *   - mint stamps a valid garden id + seeded read-receipt slot;
+ *   - serialize is deterministic and round-trips through parse;
+ *   - parse crashes (not warns) on every malformed shape;
+ *   - scanByNativeId is the lookup AUTHORITY by record BODY, never by filename;
+ *   - decideUpsert keys on record existence (idempotent), refuses identity drift;
+ *   - the pre-drilled read-receipt mutators touch only their own field.
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+	decideUpsert,
+	defaultMetaMailboxDir,
+	defaultMetaSessionsDir,
+	enqueueMetaMessage,
+	META_BACKEND_DESCRIPTORS,
+	META_SCHEMA_VERSION,
+	META_SCHEMA_VERSION_V2,
+	type MetaMintInput,
+	MetaRecordError,
+	markDelivered,
+	markEnqueued,
+	markRead,
+	metaRecordFilename,
+	mintMetaRecord,
+	parseMetaIdentity,
+	parseMetaRecord,
+	readMailboxReceiptState,
+	readMetaInbox,
+	readMetaRecordV1ByGardenId,
+	scanByNativeId,
+	serializeMetaRecord,
+	upsertMetaSession,
+} from "../pi-extensions/lib/meta-session.ts";
+
+const SESSION_ID_RE = /^\d{8}T\d{6}-[0-9a-f]{6}$/;
+const T0 = new Date("2026-06-05T05:00:00.000Z");
+const T1 = new Date("2026-06-05T06:30:00.000Z");
+
+let assertions = 0;
+function check(label: string, fn: () => void): void {
+	fn();
+	assertions += 1;
+	process.stdout.write(`[check-meta-session] ${label}: ok\n`);
+}
+
+function claudeInput(overrides: Partial<MetaMintInput> = {}): MetaMintInput {
+	return {
+		backend: "claude-code",
+		nativeSessionId: "11111111-1111-4111-8111-111111111111",
+		transcriptPath: "/home/u/.claude/projects/-home-u-proj/11111111.jsonl",
+		cwd: "/home/u/proj",
+		...overrides,
+	};
+}
+
+function expectThrows(label: string, fn: () => void): void {
+	check(label, () => {
+		assert.throws(fn, MetaRecordError, `${label}: expected MetaRecordError`);
+	});
+}
+
+// ---------------------------------------------------------------- mint
+check("mint: garden id matches the SSOT grammar", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	assert.match(r.gardenId, SESSION_ID_RE);
+});
+
+check("mint: createdAt == lastSeen at birth, ISO from `now`", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	assert.equal(r.createdAt, T0.toISOString());
+	assert.equal(r.lastSeen, T0.toISOString());
+});
+
+check("mint: delivery slot seeded from backend descriptor, receipts null", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const d = META_BACKEND_DESCRIPTORS["claude-code"];
+	assert.equal(r.delivery.wakeMode, d.wakeMode);
+	assert.equal(r.delivery.wakeMode, "self-fetch");
+	assert.equal(r.delivery.deliveryLevel, d.deliveryLevel);
+	assert.equal(r.delivery.lastEnqueuedAt, null);
+	assert.equal(r.delivery.lastDeliveredAt, null);
+	assert.equal(r.delivery.lastReadAt, null);
+	assert.equal(r.schemaVersion, META_SCHEMA_VERSION);
+});
+
+check("mint: agy/codex direct-inject descriptors differ from claude self-fetch", () => {
+	const agy = mintMetaRecord(claudeInput({ backend: "antigravity", nativeSessionId: "agy-conv-1" }), T0);
+	const codex = mintMetaRecord(claudeInput({ backend: "codex", nativeSessionId: "codex-thread-1" }), T0);
+	assert.equal(agy.delivery.wakeMode, "direct-inject");
+	assert.equal(codex.delivery.wakeMode, "direct-inject");
+});
+
+expectThrows("mint: empty nativeSessionId throws", () => mintMetaRecord(claudeInput({ nativeSessionId: "" }), T0));
+expectThrows("mint: empty transcriptPath throws", () => mintMetaRecord(claudeInput({ transcriptPath: "" }), T0));
+expectThrows("mint: empty cwd throws", () => mintMetaRecord(claudeInput({ cwd: "" }), T0));
+expectThrows("mint: bad backend throws", () =>
+	mintMetaRecord(claudeInput({ backend: "gemini" as unknown as MetaMintInput["backend"] }), T0),
+);
+
+// ---------------------------------------------------------------- serialize / parse
+check("serialize: deterministic (same record → byte-identical)", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	assert.equal(serializeMetaRecord(r), serializeMetaRecord(r));
+});
+
+check("serialize → parse round-trips to a deep-equal record", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	assert.deepEqual(parseMetaRecord(serializeMetaRecord(r)), r);
+});
+
+check("serialize: trailing newline, 2-space indent, stable key order", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const text = serializeMetaRecord(r);
+	assert.ok(text.endsWith("}\n"));
+	const keys = Object.keys(JSON.parse(text));
+	assert.deepEqual(keys, [
+		"schemaVersion",
+		"gardenId",
+		"backend",
+		"nativeSessionId",
+		"transcriptPath",
+		"cwd",
+		"createdAt",
+		"lastSeen",
+		"delivery",
+	]);
+});
+
+expectThrows("parse: invalid JSON throws", () => parseMetaRecord("{not json"));
+expectThrows("parse: array (non-object) throws", () => parseMetaRecord("[]"));
+expectThrows("parse: wrong schemaVersion throws", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const bad = JSON.parse(serializeMetaRecord(r));
+	bad.schemaVersion = 2;
+	parseMetaRecord(JSON.stringify(bad));
+});
+expectThrows("parse: malformed gardenId throws", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const bad = JSON.parse(serializeMetaRecord(r));
+	bad.gardenId = "not-a-garden-id";
+	parseMetaRecord(JSON.stringify(bad));
+});
+expectThrows("parse: unknown backend throws", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const bad = JSON.parse(serializeMetaRecord(r));
+	bad.backend = "openai";
+	parseMetaRecord(JSON.stringify(bad));
+});
+expectThrows("parse: missing nativeSessionId throws", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const bad = JSON.parse(serializeMetaRecord(r));
+	delete bad.nativeSessionId;
+	parseMetaRecord(JSON.stringify(bad));
+});
+expectThrows("parse: bad delivery.wakeMode throws", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const bad = JSON.parse(serializeMetaRecord(r));
+	bad.delivery.wakeMode = "magic";
+	parseMetaRecord(JSON.stringify(bad));
+});
+expectThrows("parse: delivery not an object throws", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const bad = JSON.parse(serializeMetaRecord(r));
+	bad.delivery = "nope";
+	parseMetaRecord(JSON.stringify(bad));
+});
+expectThrows("parse: backend↔wakeMode contradiction throws (claude record claiming direct-inject)", () => {
+	const r = mintMetaRecord(claudeInput(), T0); // claude-code → self-fetch
+	const bad = JSON.parse(serializeMetaRecord(r));
+	bad.delivery.wakeMode = "direct-inject"; // valid mode, wrong for this backend
+	parseMetaRecord(JSON.stringify(bad));
+});
+check("parse: matching backend↔wakeMode round-trips (codex direct-inject)", () => {
+	const r = mintMetaRecord(claudeInput({ backend: "codex", nativeSessionId: "codex-thread-X" }), T0);
+	assert.deepEqual(parseMetaRecord(serializeMetaRecord(r)), r);
+});
+
+// ---------------------------------------------------------------- filename
+check("metaRecordFilename: <gardenId>.meta.json", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	assert.equal(metaRecordFilename(r), `${r.gardenId}.meta.json`);
+});
+
+// ---------------------------------------------------------------- scanByNativeId (in-memory)
+check("scanByNativeId: ignores non-.meta.json entries", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const reader = (f: string) => {
+		if (f === "x.meta.json") return serializeMetaRecord(r);
+		throw new Error(`unexpected read ${f}`);
+	};
+	const found = scanByNativeId(["README.md", "notes.txt", "x.meta.json"], r.nativeSessionId, reader);
+	assert.deepEqual(found, r);
+});
+
+check("scanByNativeId: returns null when no body matches", () => {
+	const r = mintMetaRecord(claudeInput(), T0);
+	const found = scanByNativeId(["a.meta.json"], "no-such-native-id", () => serializeMetaRecord(r));
+	assert.equal(found, null);
+});
+
+check("scanByNativeId: malformed entry is skipped via onSkip, scan continues", () => {
+	const good = mintMetaRecord(claudeInput(), T0);
+	const skipped: string[] = [];
+	const reader = (f: string) => (f === "bad.meta.json" ? "{broken" : serializeMetaRecord(good));
+	const found = scanByNativeId(["bad.meta.json", "good.meta.json"], good.nativeSessionId, reader, (f) =>
+		skipped.push(f),
+	);
+	assert.deepEqual(found, good);
+	assert.deepEqual(skipped, ["bad.meta.json"]);
+});
+
+expectThrows("scanByNativeId: duplicate nativeSessionId is authority ambiguity → throws", () => {
+	// Two records (different garden ids) claiming the SAME nativeSessionId. The
+	// native→garden mapping must be unique; the scan must fail-fast, not pick one.
+	const a = mintMetaRecord(claudeInput({ nativeSessionId: "dup-native" }), T0);
+	const b = mintMetaRecord(claudeInput({ nativeSessionId: "dup-native" }), T1);
+	assert.notEqual(a.gardenId, b.gardenId);
+	const reader = (f: string) => (f === "a.meta.json" ? serializeMetaRecord(a) : serializeMetaRecord(b));
+	scanByNativeId(["a.meta.json", "b.meta.json"], "dup-native", reader);
+});
+
+// ---------------------------------------------------------------- decideUpsert
+check("decideUpsert: absent → create, fresh garden id", () => {
+	const dec = decideUpsert(null, claudeInput(), T0);
+	assert.equal(dec.action, "create");
+	assert.match(dec.record.gardenId, SESSION_ID_RE);
+});
+
+check("decideUpsert: present → attach, identity preserved, recordUpdatedAt refreshed (v2)", () => {
+	const created = decideUpsert(null, claudeInput(), T0).record;
+	const moved = claudeInput({ transcriptPath: "/new/path.jsonl", cwd: "/new/cwd" });
+	const dec = decideUpsert(created, moved, T1);
+	assert.equal(dec.action, "attach");
+	assert.equal(dec.record.schemaVersion, META_SCHEMA_VERSION_V2); // v2 identity
+	assert.equal(dec.record.gardenId, created.gardenId); // same id
+	assert.equal(dec.record.createdAt, created.createdAt); // birth preserved
+	assert.equal(dec.record.recordUpdatedAt, T1.toISOString()); // refreshed (NOT lastSeen)
+	assert.equal(dec.record.transcriptPath, "/new/path.jsonl"); // string set
+	assert.equal(dec.record.cwd, "/new/cwd");
+});
+
+check("decideUpsert: 3-value attach merge — undefined keeps, null clears, string sets (G5)", () => {
+	const created = decideUpsert(null, claudeInput({ transcriptPath: "/orig.jsonl" }), T0).record;
+	assert.equal(created.transcriptPath, "/orig.jsonl");
+	// undefined transcriptPath → KEEP existing (a pi-birth caller must not wipe it)
+	const kept = decideUpsert(
+		created,
+		{ backend: "claude-code", nativeSessionId: created.nativeSessionId, cwd: "/c" },
+		T1,
+	);
+	assert.equal(kept.record.transcriptPath, "/orig.jsonl", "undefined keeps existing");
+	// explicit null → CLEAR
+	const cleared = decideUpsert(
+		created,
+		{ backend: "claude-code", nativeSessionId: created.nativeSessionId, cwd: "/c", transcriptPath: null },
+		T1,
+	);
+	assert.equal(cleared.record.transcriptPath, null, "explicit null clears");
+});
+
+expectThrows("decideUpsert: non-boolean isEntwurf throws (runtime guard, not coerced)", () => {
+	decideUpsert(null, { ...claudeInput(), isEntwurf: "yes" as unknown as boolean }, T0);
+});
+
+check("decideUpsert: idempotent — create then attach never mints a 2nd id", () => {
+	const first = decideUpsert(null, claudeInput(), T0).record;
+	const second = decideUpsert(first, claudeInput(), T1);
+	assert.equal(second.action, "attach");
+	assert.equal(second.record.gardenId, first.gardenId);
+});
+
+expectThrows("decideUpsert: nativeSessionId mismatch throws (wrong scan key)", () => {
+	const created = decideUpsert(null, claudeInput(), T0).record;
+	decideUpsert(created, claudeInput({ nativeSessionId: "different-id" }), T1);
+});
+
+expectThrows("decideUpsert: backend drift for same native id throws", () => {
+	const created = decideUpsert(null, claudeInput(), T0).record;
+	// same nativeSessionId, different backend → corruption
+	decideUpsert(created, claudeInput({ backend: "codex" }), T1);
+});
+
+// ---------------------------------------------------------------- read-receipt mutators
+check("read-receipt mutators touch only their own field", () => {
+	const base = mintMetaRecord(claudeInput(), T0);
+	const enq = markEnqueued(base, T1);
+	assert.equal(enq.delivery.lastEnqueuedAt, T1.toISOString());
+	assert.equal(enq.delivery.lastDeliveredAt, null);
+	assert.equal(enq.delivery.lastReadAt, null);
+
+	const del = markDelivered(enq, T1);
+	assert.equal(del.delivery.lastDeliveredAt, T1.toISOString());
+	assert.equal(del.delivery.lastReadAt, null);
+
+	const read = markRead(del, T1);
+	assert.equal(read.delivery.lastReadAt, T1.toISOString());
+	// original untouched (pure)
+	assert.equal(base.delivery.lastEnqueuedAt, null);
+});
+
+// ---------------------------------------------------------------- temp-dir: authority = body, not filename
+check("temp-dir scan: authority is record BODY, not filename", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-session-scan-"));
+	try {
+		const a = mintMetaRecord(claudeInput({ nativeSessionId: "native-A" }), T0);
+		const b = mintMetaRecord(claudeInput({ backend: "codex", nativeSessionId: "native-B" }), T1);
+		// Write A under its honest filename, but B under a DECOY filename whose
+		// garden id does not match B's body — a filename-parser would be fooled.
+		fs.writeFileSync(path.join(dir, metaRecordFilename(a)), serializeMetaRecord(a));
+		const decoyName = "19990101T000000-deadbe.meta.json";
+		assert.notEqual(decoyName, metaRecordFilename(b));
+		fs.writeFileSync(path.join(dir, decoyName), serializeMetaRecord(b));
+		fs.writeFileSync(path.join(dir, "unrelated.txt"), "noise");
+
+		const entries = fs.readdirSync(dir);
+		const reader = (f: string) => fs.readFileSync(path.join(dir, f), "utf8");
+
+		const foundA = scanByNativeId(entries, "native-A", reader);
+		assert.ok(foundA && foundA.gardenId === a.gardenId);
+		// B is found by BODY nativeSessionId despite the decoy filename.
+		const foundB = scanByNativeId(entries, "native-B", reader);
+		assert.ok(foundB && foundB.gardenId === b.gardenId && foundB.backend === "codex");
+		assert.equal(scanByNativeId(entries, "native-Z", reader), null);
+	} finally {
+		fs.rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+// ---------------------------------------------------------------- upsertMetaSession (real fs, step 3)
+check("upsertMetaSession: first call creates a record on disk", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-session-store-"));
+	try {
+		const res = upsertMetaSession({ dir, input: claudeInput(), now: T0 });
+		assert.equal(res.action, "create");
+		assert.equal(res.record.schemaVersion, META_SCHEMA_VERSION_V2); // writes v2
+		assert.equal(res.path, path.join(dir, `${res.record.gardenId}.meta.json`));
+		assert.ok(fs.existsSync(res.path));
+		// on-disk bytes parse back (dual-read) to the same v2 identity
+		assert.deepEqual(parseMetaIdentity(fs.readFileSync(res.path, "utf8")), res.record);
+	} finally {
+		fs.rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+check("upsertMetaSession: second call attaches — same file/id, recordUpdatedAt refreshed, no 2nd file", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-session-store-"));
+	try {
+		const first = upsertMetaSession({ dir, input: claudeInput(), now: T0 });
+		const moved = claudeInput({ transcriptPath: "/moved/path.jsonl", cwd: "/moved/cwd" });
+		const second = upsertMetaSession({ dir, input: moved, now: T1 });
+		assert.equal(second.action, "attach");
+		assert.equal(second.record.gardenId, first.record.gardenId); // same id
+		assert.equal(second.path, first.path); // same file, rewritten in place
+		assert.equal(second.record.createdAt, T0.toISOString()); // birth preserved
+		assert.equal(second.record.recordUpdatedAt, T1.toISOString()); // refreshed (NOT lastSeen)
+		assert.equal(second.record.transcriptPath, "/moved/path.jsonl");
+		// exactly ONE .meta.json on disk (idempotent — no shadow record)
+		const metas = fs.readdirSync(dir).filter((f) => f.endsWith(".meta.json"));
+		assert.deepEqual(metas, [`${first.record.gardenId}.meta.json`]);
+	} finally {
+		fs.rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+check("upsertMetaSession: creates the store dir if absent; leaves no .tmp residue", () => {
+	const base = fs.mkdtempSync(path.join(os.tmpdir(), "meta-session-store-"));
+	const dir = path.join(base, "nested", "meta-sessions"); // does not exist yet
+	try {
+		const res = upsertMetaSession({ dir, input: claudeInput(), now: T0 });
+		assert.ok(fs.existsSync(res.path));
+		const residue = fs.readdirSync(dir).filter((f) => f.includes(".tmp-"));
+		assert.deepEqual(residue, []); // atomic write cleaned up
+	} finally {
+		fs.rmSync(base, { recursive: true, force: true });
+	}
+});
+
+expectThrows("upsertMetaSession: duplicate nativeSessionId in the store throws (fail-fast)", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "meta-session-store-"));
+	try {
+		// Two records sharing a nativeSessionId already on disk → ambiguous authority.
+		const a = mintMetaRecord(claudeInput({ nativeSessionId: "dup" }), T0);
+		const b = mintMetaRecord(claudeInput({ nativeSessionId: "dup" }), T1);
+		fs.writeFileSync(path.join(dir, metaRecordFilename(a)), serializeMetaRecord(a));
+		fs.writeFileSync(path.join(dir, metaRecordFilename(b)), serializeMetaRecord(b));
+		upsertMetaSession({ dir, input: claudeInput({ nativeSessionId: "dup" }), now: T1 });
+	} finally {
+		fs.rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+check("defaultMetaSessionsDir: honors ENTWURF_META_SESSIONS_DIR then PI_CODING_AGENT_DIR", () => {
+	const saved = { m: process.env.ENTWURF_META_SESSIONS_DIR, a: process.env.PI_CODING_AGENT_DIR };
+	try {
+		process.env.ENTWURF_META_SESSIONS_DIR = "/explicit/meta";
+		assert.equal(defaultMetaSessionsDir(), "/explicit/meta");
+		process.env.ENTWURF_META_SESSIONS_DIR = "";
+		delete process.env.ENTWURF_META_SESSIONS_DIR;
+		process.env.PI_CODING_AGENT_DIR = "/iso/agent";
+		assert.equal(defaultMetaSessionsDir(), path.join("/iso/agent", "meta-sessions"));
+	} finally {
+		if (saved.m === undefined) delete process.env.ENTWURF_META_SESSIONS_DIR;
+		else process.env.ENTWURF_META_SESSIONS_DIR = saved.m;
+		if (saved.a === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = saved.a;
+	}
+});
+
+// ---------------------------------------------------------------- mailbox delivery (step 6)
+// A self-contained store+mailbox fixture: mint one citizen, return its dirs + garden id.
+function mailboxFixture(): { sessionsDir: string; mailboxDir: string; gardenId: string; cleanup: () => void } {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), "meta-mailbox-"));
+	const sessionsDir = path.join(root, "meta-sessions");
+	const mailboxDir = path.join(root, "meta-mailbox");
+	const up = upsertMetaSession({ dir: sessionsDir, input: claudeInput({ nativeSessionId: "mbx-native" }), now: T0 });
+	return {
+		sessionsDir,
+		mailboxDir,
+		gardenId: up.record.gardenId,
+		cleanup: () => fs.rmSync(root, { recursive: true, force: true }),
+	};
+}
+
+check("enqueueMetaMessage: writes a .msg, pokes inbox.signal, stamps lastEnqueuedAt", () => {
+	const fx = mailboxFixture();
+	try {
+		const r = enqueueMetaMessage({
+			gardenId: fx.gardenId,
+			body: "hello",
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: T1,
+		});
+		assert.ok(fs.existsSync(r.messagePath) && r.messagePath.endsWith(".msg"), "a .msg body is written");
+		assert.ok(fs.existsSync(r.signalPath) && r.signalPath.endsWith("inbox.signal"), "inbox.signal is poked");
+		const st = readMailboxReceiptState({ gardenId: fx.gardenId, mailboxDir: fx.mailboxDir });
+		assert.equal(st.lastEnqueuedAt, T1.toISOString(), "lastEnqueuedAt stamped in mailbox state at enqueue time");
+		assert.equal(st.lastReadAt, null, "not read yet");
+	} finally {
+		fx.cleanup();
+	}
+});
+
+check("readMetaInbox: drains a fresh .msg, returns the body, stamps lastReadAt (D7 receipt)", () => {
+	const fx = mailboxFixture();
+	try {
+		enqueueMetaMessage({
+			gardenId: fx.gardenId,
+			body: "drain me",
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: T1,
+		});
+		const read = readMetaInbox({
+			gardenId: fx.gardenId,
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: T1,
+		});
+		assert.equal(read.messages.length, 1, "one message read");
+		assert.equal(read.messages[0]?.body, "drain me", "body intact");
+		assert.equal(read.readAt, T1.toISOString(), "readAt returned");
+		const st = readMailboxReceiptState({ gardenId: fx.gardenId, mailboxDir: fx.mailboxDir });
+		assert.equal(st.lastReadAt, T1.toISOString(), "lastReadAt stamped in mailbox state = the honest read receipt");
+		// #5 honesty: lastDeliveredAt is the doorbell's to stamp; readMetaInbox must NOT invent it.
+		assert.equal(st.lastDeliveredAt, null, "lastDeliveredAt left null (read does not record a delivery time)");
+	} finally {
+		fx.cleanup();
+	}
+});
+
+check("readMetaInbox: drains a doorbell-rung .msg.delivered too", () => {
+	const fx = mailboxFixture();
+	try {
+		const dir = path.join(fx.mailboxDir, fx.gardenId);
+		fs.mkdirSync(dir, { recursive: true });
+		fs.writeFileSync(path.join(dir, "x.msg.delivered"), "via doorbell");
+		const read = readMetaInbox({
+			gardenId: fx.gardenId,
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: T1,
+		});
+		assert.equal(read.messages.length, 1, "the .msg.delivered is read");
+		assert.equal(read.messages[0]?.body, "via doorbell");
+	} finally {
+		fx.cleanup();
+	}
+});
+
+check("readMetaInbox: ONE drain returns ALL queued bodies in order (level-triggered body state; #34 D8 basis)", () => {
+	const fx = mailboxFixture();
+	try {
+		// Three messages land while the session is idle. The wake SIGNAL
+		// (inbox.signal) is edge-triggered and can coalesce N rapid pokes into a
+		// single FileChanged. Each BODY is a separate level-state file on disk, so
+		// a later wake/read drains the whole directory instead of trusting the number
+		// of signal edges. A fully lost doorbell can still leave an idle-forever
+		// unread backlog; #34 tracks that heartbeat/re-poke backstop separately.
+		// This gate asserts the deterministic robustness basis: once the receiver
+		// self-fetches, it gets every queued body, including both fresh .msg and
+		// doorbell-rung .msg.delivered files.
+		const t1 = new Date("2026-06-05T06:30:00.000Z");
+		const t2 = new Date("2026-06-05T06:31:00.000Z");
+		const t3 = new Date("2026-06-05T06:32:00.000Z");
+		const t4 = new Date("2026-06-05T06:33:00.000Z");
+		enqueueMetaMessage({
+			gardenId: fx.gardenId,
+			body: "first",
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: t1,
+		});
+		enqueueMetaMessage({
+			gardenId: fx.gardenId,
+			body: "second",
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: t2,
+		});
+		// The third one's doorbell DID ring: FileChanged moved .msg -> .msg.delivered.
+		const third = enqueueMetaMessage({
+			gardenId: fx.gardenId,
+			body: "third",
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: t3,
+		});
+		fs.renameSync(third.messagePath, `${third.messagePath}.delivered`);
+
+		const read = readMetaInbox({
+			gardenId: fx.gardenId,
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: t4,
+		});
+		assert.equal(read.messages.length, 3, "a single read drains all three queued bodies");
+		assert.deepEqual(
+			read.messages.map((m) => m.body),
+			["first", "second", "third"],
+			"timestamp-distinct bodies drain in deterministic filename order",
+		);
+		// One batch, one honest receipt — NOT one-per-message.
+		const st = readMailboxReceiptState({ gardenId: fx.gardenId, mailboxDir: fx.mailboxDir });
+		assert.equal(st.lastReadAt, t4.toISOString(), "a single lastReadAt receipt for the whole batch");
+		// Every body archived to .read; nothing unread remains; re-read is empty.
+		const dir = path.join(fx.mailboxDir, fx.gardenId);
+		const stillUnread = fs.readdirSync(dir).filter((f) => f.endsWith(".msg") || f.endsWith(".msg.delivered"));
+		assert.equal(stillUnread.length, 0, "no unread body remains after the batch drain (all archived to .read)");
+		assert.equal(
+			readMetaInbox({ gardenId: fx.gardenId, sessionsDir: fx.sessionsDir, mailboxDir: fx.mailboxDir, now: t4 }).messages
+				.length,
+			0,
+			"re-read after the batch drain is empty (idempotent consume)",
+		);
+	} finally {
+		fx.cleanup();
+	}
+});
+
+check("readMetaInbox: empty inbox returns nothing AND mutates no receipt; re-read after drain is empty", () => {
+	const fx = mailboxFixture();
+	try {
+		// empty read: no message, no receipt
+		const empty = readMetaInbox({
+			gardenId: fx.gardenId,
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: T1,
+		});
+		assert.equal(empty.messages.length, 0, "empty inbox: no messages");
+		assert.equal(empty.readAt, null, "empty inbox: no receipt stamped");
+		assert.equal(
+			readMailboxReceiptState({ gardenId: fx.gardenId, mailboxDir: fx.mailboxDir }).lastReadAt,
+			null,
+			"empty read leaves lastReadAt null (state.json not created)",
+		);
+		// enqueue + drain, then re-read must be empty (archived to .read, not double-returned)
+		enqueueMetaMessage({
+			gardenId: fx.gardenId,
+			body: "once",
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: T1,
+		});
+		assert.equal(
+			readMetaInbox({ gardenId: fx.gardenId, sessionsDir: fx.sessionsDir, mailboxDir: fx.mailboxDir, now: T1 }).messages
+				.length,
+			1,
+			"first drain returns it",
+		);
+		assert.equal(
+			readMetaInbox({ gardenId: fx.gardenId, sessionsDir: fx.sessionsDir, mailboxDir: fx.mailboxDir, now: T1 }).messages
+				.length,
+			0,
+			"re-read is empty",
+		);
+	} finally {
+		fx.cleanup();
+	}
+});
+
+expectThrows("enqueueMetaMessage: unknown garden id fails loud (not a citizen)", () => {
+	const fx = mailboxFixture();
+	try {
+		enqueueMetaMessage({
+			gardenId: "20200101T000000-aaaaaa",
+			body: "x",
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: T1,
+		});
+	} finally {
+		fx.cleanup();
+	}
+});
+
+expectThrows("enqueueMetaMessage: empty body fails loud", () => {
+	const fx = mailboxFixture();
+	try {
+		enqueueMetaMessage({
+			gardenId: fx.gardenId,
+			body: "",
+			sessionsDir: fx.sessionsDir,
+			mailboxDir: fx.mailboxDir,
+			now: T1,
+		});
+	} finally {
+		fx.cleanup();
+	}
+});
+
+expectThrows("readMetaRecordV1ByGardenId: body/filename gardenId drift is corruption (body is SSOT)", () => {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), "meta-drift-"));
+	try {
+		const sessionsDir = path.join(root, "meta-sessions");
+		fs.mkdirSync(sessionsDir, { recursive: true });
+		// A record whose BODY gardenId differs from the <id>.meta.json filename it lives in.
+		const rec = mintMetaRecord(claudeInput({ nativeSessionId: "drift" }), T0);
+		const wrongName = "20200101T000000-bbbbbb.meta.json"; // filename id != rec.gardenId
+		fs.writeFileSync(path.join(sessionsDir, wrongName), serializeMetaRecord(rec));
+		readMetaRecordV1ByGardenId("20200101T000000-bbbbbb", sessionsDir);
+	} finally {
+		fs.rmSync(root, { recursive: true, force: true });
+	}
+});
+
+check("defaultMetaMailboxDir: sibling of meta-sessions under the pi agent dir", () => {
+	const saved = { m: process.env.ENTWURF_META_MAILBOX_DIR, a: process.env.PI_CODING_AGENT_DIR };
+	try {
+		process.env.ENTWURF_META_MAILBOX_DIR = "/explicit/mbx";
+		assert.equal(defaultMetaMailboxDir(), "/explicit/mbx");
+		delete process.env.ENTWURF_META_MAILBOX_DIR;
+		process.env.PI_CODING_AGENT_DIR = "/iso/agent";
+		assert.equal(defaultMetaMailboxDir(), path.join("/iso/agent", "meta-mailbox"));
+	} finally {
+		if (saved.m === undefined) delete process.env.ENTWURF_META_MAILBOX_DIR;
+		else process.env.ENTWURF_META_MAILBOX_DIR = saved.m;
+		if (saved.a === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = saved.a;
+	}
+});
+
+process.stdout.write(`[check-meta-session] ${assertions} assertions ok\n`);