@junghanacs/entwurf 0.12.8 → 0.12.9

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

@@ -195,6 +195,60 @@ export const FRESH_CUT_COMMAND_INSTALLED = "entwurf meta-bridge-fresh-cut";
  * (never replaces) the `FRESH_CUT_COMMAND` substring the gates assert.
  */
 export const FRESH_CUT_PRESCRIPTION = `\`${FRESH_CUT_COMMAND}\` (from an installed package: \`${FRESH_CUT_COMMAND_INSTALLED}\`)`;
+/**
+ * THE fresh-cut EXIT CONTRACT (#54) — the store doctor's `0/1/2/3` has a sibling here.
+ *
+ * The cut used to answer `1` for three world-states that are not each other, and the
+ * documented chain `fresh-cut && setup` therefore stopped on all of them alike. What
+ * distinguishes them is not severity, it is **what already moved**:
+ *
+ *   - `COMPLETE` (0) — the generation is archived (or there was none), the fresh v3
+ *     store is open, and every dead/refuted marker and socket is gone. `&& setup` is
+ *     exactly right here.
+ *   - `NO_MOVE` (1) — the cut REFUSED before touching anything: a live or unprovable
+ *     surface, an occupied archive destination, a surface that could not be read or
+ *     planned, or a first rename that failed. The host is what it was; fix the named
+ *     cause and re-run the same command. Nothing downstream may proceed, because the
+ *     store the install refused is still there.
+ *   - `USAGE` (2) — the operator asked for something this verb does not have. Same
+ *     number the `-h` path and the store doctor use, so a wrapper never has to learn a
+ *     second convention.
+ *   - `HALF_CUT` (3) — a failure arrived AFTER at least one archive move, so the cut
+ *     transition is incomplete and the fresh generation is not confirmed open. This
+ *     state wants inspection before anything else runs; a re-run can finish the cut
+ *     under its own stamp.
+ *   - `CLEANUP_INCOMPLETE` (4) — the cut IS done: the generation moved, the fresh
+ *     generation is open, install and citizen birth are no longer blocked by the
+ *     store. What survived is disposable process state (marker/socket residue) that
+ *     could not be unlinked. A runbook may run `setup` here but may not call the host
+ *     clean. Re-running fresh-cut is safe only before a new citizen is born; after
+ *     that, repair the named residue manually rather than archiving the new generation.
+ *
+ * Still fail-closed: only `COMPLETE` is zero. #54 asked for the states to become
+ * distinguishable, not for cleanup failure to become success.
+ *
+ * Frozen numbers. A caller — a shell runbook, CI, another agent — reads these, so
+ * renumbering is a breaking change to every chain that branches on them.
+ */
+export const FRESH_CUT_EXIT = {
+    COMPLETE: 0,
+    NO_MOVE: 1,
+    USAGE: 2,
+    HALF_CUT: 3,
+    CLEANUP_INCOMPLETE: 4,
+};
+/**
+ * The mid-cut verdict, as a function rather than a branch, so the distinction #54 is
+ * about can be EXECUTED by a gate instead of grepped for.
+ *
+ * A rename that fails is not one event: if nothing had moved yet it is a refusal that
+ * happens to arrive late ({@link FRESH_CUT_EXIT.NO_MOVE} — the host is untouched), and
+ * if something had, it is a genuine {@link FRESH_CUT_EXIT.HALF_CUT}. The old code said
+ * both of those in prose and neither of them in its exit status.
+ */
+export function midCutExit(archivedCount) {
+    return archivedCount === 0 ? FRESH_CUT_EXIT.NO_MOVE : FRESH_CUT_EXIT.HALF_CUT;
+}
 /** The uniform "this record is not a live-generation v3 record" error, naming the fresh-cut fix. */
 function nonV3RecordMessage(version) {
     return (`meta-record "schemaVersion" must be ${META_SCHEMA_VERSION_V3} (got ${describe(version)}). ` +
@@ -594,27 +648,106 @@ export function certifyActiveStore(entries, readRecord) {
  * the doctor and the install preflight call an unreadable host clean (2026-07-25
  * fresh-eyes review; `existsSync` returns false for a directory it merely cannot search,
  * which is the same laundering {@link inspectRecordEntry} refuses on the targeted path).
+ *
+ * Split out of {@link certifyActiveStoreDir} so that EVERY store-wide scan in this repo
+ * — the certification, the `entwurf_peers` listing, the rival scan — gets its entries
+ * from one function that carries the ENTRY KIND. A binding that does its own
+ * `readdir()` gets names only, so the next thing it does is `readFileSync`, and rule 1
+ * ("a symlink is refused, never followed — its bytes live where this store has no
+ * ownership") quietly stops holding on that surface. That is not hypothetical: both
+ * `entwurf_peers` bindings hand-rolled exactly that readdir, and the #52 duplicate pass
+ * then let a symlink pointing at foreign bytes quarantine a healthy regular record.
+ * The rule has to be structural, not remembered at each call site — the same lesson
+ * `pi_settings_io` learned about the settings writers.
  */
-export function certifyActiveStoreDir(dir) {
+export function readActiveStoreEntries(dir) {
     const resolved = path.resolve(expandTilde(dir));
     let dirents;
     try {
         dirents = fs.readdirSync(resolved, { withFileTypes: true });
     }
     catch (err) {
-        if (err.code === "ENOENT") {
-            return { dir: resolved, scanned: 0, records: [], defects: [] };
-        }
+        if (err.code === "ENOENT")
+            return [];
         throw new MetaRecordError(`cannot read the meta-record store ${resolved}: ${err instanceof Error ? err.message : String(err)}. ` +
             "That is a failure to inspect the store, not an empty store — refusing to certify a store this " +
             "process cannot read.");
     }
-    const entries = dirents
+    return dirents
         .sort((a, b) => a.name.localeCompare(b.name))
         .map((entry) => ({ filename: entry.name, regularFile: entry.isFile() }));
+}
+/** The errno {@link readStoreRecordFile} raises for an entry whose OPEN succeeded but
+ * whose file description is not a regular file — a directory, a fifo, a device. There is
+ * no operating-system errno for "you opened the wrong KIND of thing", so this is a
+ * synthesized one; every real errno is passed through untouched. */
+export const NOT_REGULAR_ENTRY_CODE = "ENTWURF_ENOTREG";
+const O_NOFOLLOW_FLAG = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+const O_NONBLOCK_FLAG = typeof fs.constants.O_NONBLOCK === "number" ? fs.constants.O_NONBLOCK : 0;
+/**
+ * Read a record's bytes with the entry KIND decided on the very file description the
+ * read will use.
+ *
+ * `lstat`-then-`readFileSync(path)` classifies one entry and reads another. Between
+ * those two syscalls the final path component can be replaced by a symlink, and the read
+ * then follows it into bytes the store does not own — rule 1 laundered by a race rather
+ * than by a missing check (2026-07-26 cross-review). A path looked up twice cannot hold
+ * the rule; one open file description can:
+ *
+ *   `O_NOFOLLOW` — a symlink at the FINAL component fails the OPEN with `ELOOP`, so
+ *                  foreign bytes are refused before one of them is read. Intermediate
+ *                  components resolve as they always have: the shape of the store
+ *                  DIRECTORY is a separate question, and this seam does not widen into
+ *                  it.
+ *   `O_NONBLOCK` — opening a fifo `O_RDONLY` BLOCKS until some writer appears, so a
+ *                  named pipe dropped in the store would hang every scan on a host where
+ *                  nobody is writing. Classify-then-open never had that window; this flag
+ *                  is what buys it back. It is a no-op for regular files, and it does not
+ *                  decide anything — the fstat below is what refuses the fifo.
+ *   `fstat(fd)`  — the kind of THIS description, not of a name. A directory opens fine on
+ *                  Linux, so without it the refusal would arrive later as a stranger
+ *                  errno from the read.
+ *
+ * Errno is deliberately NOT flattened here. The callers separate raced-away (`ENOENT`)
+ * from unreadable (`EACCES`) from refused (`ELOOP`), and a wrapper that turned all three
+ * into one `MetaRecordError` would silently kill the rival scan's raced-away skip — the
+ * loudest possible regression, since every concurrent birth would then refuse dispatch.
+ * Shaping a message is the job of the caller that knows what the answer is FOR.
+ */
+export function readStoreRecordFile(file) {
+    if (O_NOFOLLOW_FLAG === 0) {
+        throw new MetaRecordError(`cannot read meta-record ${path.basename(file)} safely: this platform exposes no O_NOFOLLOW, so a record ` +
+            "read cannot refuse a symlink swapped in at the final component. entwurf certifies Linux only.");
+    }
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | O_NOFOLLOW_FLAG | O_NONBLOCK_FLAG);
+    try {
+        if (!fs.fstatSync(fd).isFile()) {
+            const err = new Error(`meta-record ${path.basename(file)} is not a regular file (directory/fifo/device) — a record's bytes ` +
+                "must live in the store itself, so this entry is never read.");
+            err.code = NOT_REGULAR_ENTRY_CODE;
+            throw err;
+        }
+        return fs.readFileSync(fd, "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** The reader every store-WIDE scan pairs with {@link readActiveStoreEntries}. The
+ * caller's entry kind decides the POLICY — whether a non-regular entry is a defect
+ * (certification), a diagnostic (listing) or a non-candidate (the rival scan) — because
+ * only the caller knows that. What the caller cannot know is whether the entry is still
+ * that kind at the instant of the read, so {@link readStoreRecordFile} re-decides it on
+ * the fd and refuses there. Snapshot kind for the verdict, fd kind for the bytes. */
+export function makeStoreRecordReader(dir) {
+    const resolved = path.resolve(expandTilde(dir));
+    return (filename) => readStoreRecordFile(path.join(resolved, filename));
+}
+export function certifyActiveStoreDir(dir) {
+    const resolved = path.resolve(expandTilde(dir));
     return {
         dir: resolved,
-        ...certifyActiveStore(entries, (filename) => fs.readFileSync(path.join(resolved, filename), "utf8")),
+        ...certifyActiveStore(readActiveStoreEntries(resolved), makeStoreRecordReader(resolved)),
     };
 }
 /**
@@ -639,6 +772,25 @@ export function activeStoreRefusal(cert, shown = 3) {
         .join("\n  ");
     return (`${headline}\n  ${head}` + (cert.defects.length > shown ? `\n  … and ${cert.defects.length - shown} more` : ""));
 }
+/**
+ * Group already-parsed identities by the id that must be unique across a store.
+ * Insertion-ordered (Map), so every consumer reports rivals in the order it read them.
+ *
+ * Keeps the listing's duplicate pass deterministic and separate from its quarantine
+ * loop. Certification and the addressable read apply the same `nativeSessionId` equality
+ * rule at different granularities, but do not call this listing-specific grouping helper.
+ */
+function groupByNativeSessionId(identities) {
+    const byNative = new Map();
+    for (const identity of identities) {
+        const seen = byNative.get(identity.nativeSessionId);
+        if (seen)
+            seen.push(identity);
+        else
+            byNative.set(identity.nativeSessionId, [identity]);
+    }
+    return byNative;
+}
 /**
  * Scan every meta-record in a store into identities + explicit read errors.
  * Pure over injected (entries, readRecord) so gates drive it without IO; the
@@ -653,15 +805,37 @@ export function activeStoreRefusal(cert, shown = 3) {
  * is impossible: the filename IS `<gardenId>.meta.json`, so the filesystem
  * already enforces uniqueness — only body/filename drift can split authority.
  *
+ * It takes {@link ActiveStoreEntry} — filename PLUS kind — for the same reason the
+ * certification does: rule 1 says a symlinked record is refused and NEVER FOLLOWED, and
+ * a scan handed bare names cannot obey that, because the only thing it can do next is
+ * read the path. Both `entwurf_peers` bindings used to hand-roll a name-only readdir,
+ * so this surface read foreign bytes through a symlink while the doctor refused the
+ * same entry — one store, two contracts again. A non-regular entry is now a diagnostic
+ * whose bytes are never touched.
+ *
+ * Store-wide UNIQUENESS of `nativeSessionId` is enforced here as well (#52) — free,
+ * because this function already reads the whole store. See the loop below for why both
+ * rivals become errors rather than one becoming a winner.
+ *
  * mode "collect" (default) returns partial results; "strict" throws if ANY
  * record was unreadable (doctor / gate callers wanting all-or-nothing).
  */
 export function listAllMetaIdentities(entries, readRecord, opts = {}) {
     const identities = [];
     const errors = [];
-    for (const filename of entries) {
+    for (const entry of entries) {
+        const filename = entry.filename;
         if (!filename.endsWith(".meta.json"))
             continue;
+        if (!entry.regularFile) {
+            errors.push({
+                filename,
+                message: "not a regular file (symlink/directory/special) — a record's bytes must live in the store " +
+                    "itself, so this entry is never followed and cannot name a citizen. Inspect and remove it by " +
+                    `hand, or archive the generation with ${FRESH_CUT_PRESCRIPTION}.`,
+            });
+            continue;
+        }
         let identity;
         try {
             identity = parseMetaIdentity(readRecord(filename));
@@ -682,6 +856,34 @@ export function listAllMetaIdentities(entries, readRecord, opts = {}) {
         }
         identities.push(identity);
     }
+    // Rule 4 of {@link certifyActiveStore}, enforced HERE too (#52). This scan already
+    // holds every record in its hand, so uniqueness costs NOTHING to check — and a
+    // facts surface that reports two records claiming one `nativeSessionId` as two
+    // healthy citizens is describing a store the doctor calls uncertifiable as clean.
+    // That is the sharpest form of the gap: not a missing guard, a WRONG FACT.
+    //
+    // Both rivals leave `identities` and become errors, never one winner: the store
+    // genuinely cannot say which record owns that session, so picking either would
+    // mint the authority the certification refuses to mint. Everyone else keeps
+    // listing — the same rule an unreadable record follows, because one broken pair
+    // must not blind `entwurf_peers` (the 0.10 lesson).
+    for (const [nativeSessionId, holders] of groupByNativeSessionId(identities)) {
+        if (holders.length < 2)
+            continue;
+        const files = holders.map((h) => metaRecordFilename(h));
+        for (const holder of holders) {
+            const index = identities.indexOf(holder);
+            if (index >= 0)
+                identities.splice(index, 1);
+            errors.push({
+                filename: metaRecordFilename(holder),
+                message: `duplicate nativeSessionId ${JSON.stringify(nativeSessionId)} — also claimed by ` +
+                    `${files.filter((f) => f !== metaRecordFilename(holder)).join(", ")}. The native→garden mapping ` +
+                    `must be unique; this store cannot say which record owns that session, so NEITHER is listed as ` +
+                    `a citizen. Archive the generation with ${FRESH_CUT_PRESCRIPTION}.`,
+            });
+        }
+    }
     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})`)
@@ -912,6 +1114,80 @@ export function startKeyScheme(key) {
         return "ps";
     return null;
 }
+/**
+ * CAN this pid own a native session at all? — the question one layer ABOVE
+ * {@link classifyMarkerOwner}, and the one no marker consumer used to ask.
+ *
+ * `classifyMarkerOwner` answers "is the process this marker NAMES still the one
+ * running", and for pid 1 the honest answer is YES: init is up for as long as the
+ * host is, and its start-key does not change while it runs. So an `ownerPid: 1`
+ * marker classifies `live` for the whole boot, and — this is the operational
+ * point — THE ACTION THE REFUSAL PRESCRIBES CANNOT CHANGE THAT. Quiescing every
+ * session leaves init running under the same start-key, so the operator does the
+ * one thing they were told to do and the cut refuses again. (Deleting the marker
+ * removes the CLAIM; it never refutes the verdict — which is exactly why the
+ * affected host's only way out was a hand `rm`.) A reboot is not a dependable
+ * remedy either: pid 1's key is `linux:<starttime in ticks since boot>` and init
+ * starts within a few ticks, so the recorded value can simply come up again —
+ * there is no contract in either direction, and this is not evidence that it must.
+ * What was MEASURED (#53 A, second Linux host, 2026-07-25) is that the cut stayed
+ * blocked until the file was deleted by hand, while `0.12.8` names that same cut
+ * as the one repair for a pre-v3 store: the documented upgrade path had no in-band
+ * exit. The pure rule is not wrong there; the marker's CLAIM is.
+ *
+ * WHERE SUCH A MARKER COMES FROM — stated at the size of the evidence. After this
+ * fix no writer in THIS tree can mint one, so on a current install it is legacy or
+ * corrupt residue. Legacy has more than one source: the retired shell-form Claude
+ * hook (wrapper shell exits first → hook REPARENTED to init → reads `ppid = 1`),
+ * and the agy imprint, which asked only `> 0` until #53 A and could mint the same
+ * shape through the same reparenting. Corrupt is a real class too — this predicate
+ * also refutes non-integer and unsafe-integer pids, which no writer here has ever
+ * produced, so a foreign or damaged marker is the only way they appear. The ONE
+ * file actually observed was a shell-form Claude hook reparented to init. None of
+ * these is a zombie: a zombie is reaped, its pid is freed, the start-key stops
+ * matching, and the marker resolves itself.
+ *
+ * A pid ≤ 1 is refuted BY CONSTRUCTION, which is why this predicate is shared by
+ * both writers and every reader instead of living at one call site: 0 and
+ * negatives address process GROUPS rather than a process (the rule
+ * {@link probePidExistence} already holds), and on the axis this repo certifies no
+ * native session is owned by init.
+ *
+ * THAT LAST CLAUSE IS A POLICY, NOT A LAW OF PROCESSES. The certified axis is a
+ * Linux desktop/workstation host, where init is the service manager and every
+ * native harness is a descendant of a login session. A container that runs the
+ * harness AS pid 1 is a real shape in the world, and there `ownerPid: 1` would name
+ * a genuine owner — so such a host is simply UNSUPPORTED here and fails CLOSED: the
+ * writers refuse to mint the marker, so the session keeps its meta-record but never
+ * claims reply-addressability, which costs a capability instead of granting a false
+ * identity. Do not read this predicate as "pid 1 can never own anything"; read it as
+ * "this repo does not certify a host where it does". Widening the axis means new
+ * evidence and a new contract, not a quiet loosening of the bound.
+ *
+ * Writers refuse to mint it, readers refuse to honor it, and the cut treats it as
+ * clearable residue rather than an owner claim — a proof of INVALIDITY, which is
+ * stronger than the proof of death the cut already acts on.
+ */
+export function isPlausibleOwnerPid(pid) {
+    return Number.isSafeInteger(pid) && pid > 1;
+}
+/**
+ * The write-side half of {@link isPlausibleOwnerPid}. A marker naming an
+ * impossible owner is not a degraded marker, it is a lie that outlives every
+ * process that could refute it — so minting one THROWS rather than warns, and no
+ * future writer can reintroduce #53 A by forgetting the predicate at its own call
+ * site (both current writers still ask it first, and fail closed in their own
+ * words).
+ */
+function requireOwnerPid(ownerPid, kind) {
+    if (!isPlausibleOwnerPid(ownerPid)) {
+        throw new Error(`refusing to write a ${kind} marker for owner pid ${ownerPid}: a pid <= 1 cannot own a native session ` +
+            "(pid 1 is init — a reparented orphan is not an owner). Quiescing the sessions, which is what " +
+            "meta-bridge-fresh-cut asks for when it refuses, would not refute such a marker, so it would keep " +
+            "blocking the cut on this host (#53 A).");
+    }
+    return ownerPid;
+}
 /**
  * THE rule for "is the process this marker names still the one running?" — the one
  * place a `dead` verdict may be produced, so no caller re-derives it from
@@ -983,15 +1259,18 @@ export function metaSenderMarkerPath(backend, ownerPid, sendersDir = defaultMeta
 export function writeMetaSenderMarker(opts) {
     const backend = requireBackend(opts.backend);
     const gardenId = requireGardenId(opts.gardenId);
-    const file = metaSenderMarkerPath(backend, opts.ownerPid, opts.sendersDir ?? defaultMetaSendersDir());
+    // Refused BEFORE the path is built: an impossible owner must not even leave a
+    // backend directory behind, let alone a marker keyed to its pid.
+    const ownerPid = requireOwnerPid(opts.ownerPid, "sender");
+    const file = metaSenderMarkerPath(backend, ownerPid, opts.sendersDir ?? defaultMetaSendersDir());
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const marker = {
         backend,
         gardenId,
         nativeSessionId: requireNonEmptyString(opts.nativeSessionId, "nativeSessionId"),
         cwd: requireNonEmptyString(opts.cwd, "cwd"),
-        ownerPid: opts.ownerPid,
-        ownerStartKey: processStartKey(opts.ownerPid),
+        ownerPid,
+        ownerStartKey: processStartKey(ownerPid),
         updatedAt: isoNow(opts.now ?? new Date()),
     };
     const tmp = `${file}.${crypto.randomBytes(4).toString("hex")}.tmp`;
@@ -1023,13 +1302,19 @@ export function readMetaSenderMarker(opts) {
             ownerStartKey: requireNonEmptyString(raw.ownerStartKey, "ownerStartKey"),
             updatedAt: requireNonEmptyString(raw.updatedAt, "updatedAt"),
         };
+        // Plausibility comes FIRST and is never opt-out: it is a property of the CLAIM,
+        // not of the owner's current state, so `verifyOwner: false` (inspection) does not
+        // reach past it either. An `ownerPid: 1` marker is a reparented orphan's residue
+        // and would otherwise keep granting a dead citizen's sender identity for as long
+        // as the host is up — the pid-reuse guard cannot catch it, because init IS still
+        // the same process (#53 A). This also subsumes the old `Number.isInteger` check.
+        if (!isPlausibleOwnerPid(marker.ownerPid))
+            return null;
         // 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;
@@ -1062,14 +1347,15 @@ export function metaReceiverMarkerPath(gardenId, receiversDir = defaultMetaRecei
 export function writeMetaReceiverMarker(opts) {
     const gardenId = requireGardenId(opts.gardenId);
     const backend = requireBackend(opts.backend);
+    const ownerPid = requireOwnerPid(opts.ownerPid, "receiver");
     const file = metaReceiverMarkerPath(gardenId, opts.receiversDir ?? defaultMetaReceiversDir());
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const marker = {
         gardenId,
         backend,
         nativeSessionId: requireNonEmptyString(opts.nativeSessionId, "nativeSessionId"),
-        ownerPid: opts.ownerPid,
-        ownerStartKey: processStartKey(opts.ownerPid),
+        ownerPid,
+        ownerStartKey: processStartKey(ownerPid),
         ownerKind: requireNonEmptyString(opts.ownerKind ?? "claude-code-cli", "ownerKind"),
         armProvenance: requireArmProvenance(opts.armProvenance),
         updatedAt: isoNow(opts.now ?? new Date()),
@@ -1106,9 +1392,12 @@ export function readMetaReceiverMarker(opts) {
             armProvenance: requireArmProvenance(raw.armProvenance),
             updatedAt: requireNonEmptyString(raw.updatedAt, "updatedAt"),
         };
+        // Same rule as the sender marker, and for the same reason one layer over: an
+        // impossible owner is not a live one, so a refuted marker must never read back
+        // as an ACTIVE RECEIVER and pull the mailbox rail into delivering to a void.
+        if (!isPlausibleOwnerPid(marker.ownerPid))
+            return null;
         if (opts.verifyOwner !== false) {
-            if (!Number.isInteger(marker.ownerPid))
-                return null;
             const liveKey = processStartKey(marker.ownerPid);
             if (!liveKey || liveKey !== marker.ownerStartKey)
                 return null;
@@ -1202,11 +1491,32 @@ function inspectRecordEntry(file) {
     catch (err) {
         if (err.code === "ENOENT")
             return "absent";
-        throw new MetaRecordError(`cannot inspect meta-record ${path.basename(file)} under ${path.dirname(file)}: ` +
-            `${err instanceof Error ? err.message : String(err)}. That is an inspection failure, not an absent ` +
-            `citizen — refusing to report "no record" from a store this process cannot read.`);
+        throw recordInspectionFailure(file, err);
     }
 }
+export function classifyRecordReadFailure(code) {
+    if (code === "ENOENT")
+        return "absent";
+    if (code === "ELOOP" || code === "ENXIO" || code === NOT_REGULAR_ENTRY_CODE)
+        return "irregular";
+    return "unreadable";
+}
+/** The three refusals a targeted read can reach from EITHER layer — the settled
+ * classification or a raced read. One text each, so a race and a quiet store say the same
+ * sentence to the operator. */
+function recordInspectionFailure(file, err) {
+    return new MetaRecordError(`cannot inspect meta-record ${path.basename(file)} under ${path.dirname(file)}: ` +
+        `${err instanceof Error ? err.message : String(err)}. That is an inspection failure, not an absent ` +
+        `citizen — refusing to report "no record" from a store this process cannot read.`);
+}
+function absentRecordRefusal(id, file) {
+    return new MetaRecordError(`no meta-record for garden id "${id}" under ${path.dirname(file)} — not a garden citizen, cannot deliver.`);
+}
+function irregularRecordRefusal(id) {
+    return new MetaRecordError(`meta-record ${id}.meta.json is not a regular file (symlink/directory/special) — a record's bytes must ` +
+        `live in the store itself, so this entry is never followed and cannot address a citizen. ` +
+        `Inspect and remove it by hand, or archive the generation with ${FRESH_CUT_PRESCRIPTION}.`);
+}
 /**
  * The identity read-by-gardenId. Read the file, body is SSOT, fail-fast on
  * body/filename gardenId drift; V3-only via parseMetaIdentity (an unreadable
@@ -1216,22 +1526,48 @@ function inspectRecordEntry(file) {
 export function readMetaIdentityByGardenId(gardenId, sessionsDir = defaultMetaSessionsDir()) {
     const id = requireGardenId(gardenId);
     const file = recordFileFor(sessionsDir, id);
+    // TWO LAYERS, AND THEY ARE NOT THE SAME RULE TWICE.
+    //
+    // Layer 1 — POLICY, on a settled store. Rule 1 of {@link certifyActiveStore}, enforced
+    // HERE too, because this is the one place a live dispatch reads a record. Certifying
+    // the store on WRITE while this read followed the link made the contract true only
+    // where nobody was being addressed: the doctor refused a symlinked entry that v2
+    // dispatch, `entwurf_self` and the sender-marker trust all resolved happily, from bytes
+    // the store does not own (2026-07-25 fresh-eyes review). It classifies WITHOUT OPENING,
+    // which is the point — a socket, a device, a mode-000 directory each earn the
+    // certification's own sentence instead of whatever errno an `open` would have tripped
+    // over (ENXIO, EACCES), and nothing special is opened to find out what it is. Deleting
+    // this layer in favour of the fd alone looked like removing a duplicate enforcement
+    // point and was actually a regression on all three shapes (2026-07-26 cross-review,
+    // round 3 — found by GPT, reproduced here).
+    //
+    // Layer 2 — the RACE, on the bytes actually returned. A verdict about a name stops
+    // being true the moment something replaces what the name points at, so the read
+    // re-decides on its own fd. Its errno verdicts collapse onto layer 1's sentences via
+    // {@link classifyRecordReadFailure}, which is pure so that the branches stay provable:
+    // with layer 1 in front of it, no settled store can reach them.
     const kind = inspectRecordEntry(file);
-    if (kind === "absent") {
-        throw new MetaRecordError(`no meta-record for garden id "${id}" under ${path.dirname(file)} — not a garden citizen, cannot deliver.`);
-    }
-    // Rule 1 of {@link certifyActiveStore}, enforced HERE too — the one place a live
-    // dispatch reads a record. Certifying the store on WRITE while this read followed the
-    // link made the contract true only where nobody was being addressed: the doctor
-    // refused a symlinked entry that v2 dispatch, `entwurf_self` and the sender-marker
-    // trust all resolved happily, from bytes the store does not own (2026-07-25
-    // fresh-eyes review). One contract means both directions hold it.
-    if (kind === "irregular") {
-        throw new MetaRecordError(`meta-record ${id}.meta.json is not a regular file (symlink/directory/special) — a record's bytes must ` +
-            `live in the store itself, so this entry is never followed and cannot address a citizen. ` +
-            `Inspect and remove it by hand, or archive the generation with ${FRESH_CUT_PRESCRIPTION}.`);
-    }
-    const identity = parseMetaIdentity(fs.readFileSync(file, "utf8"));
+    if (kind === "absent")
+        throw absentRecordRefusal(id, file);
+    if (kind === "irregular")
+        throw irregularRecordRefusal(id);
+    let raw;
+    try {
+        raw = readStoreRecordFile(file);
+    }
+    catch (err) {
+        if (err instanceof MetaRecordError)
+            throw err;
+        switch (classifyRecordReadFailure(err.code)) {
+            case "absent":
+                throw absentRecordRefusal(id, file);
+            case "irregular":
+                throw irregularRecordRefusal(id);
+            default:
+                throw recordInspectionFailure(file, err);
+        }
+    }
+    const identity = parseMetaIdentity(raw);
     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 and a garden-id lookup can never reach it. ` +
@@ -1258,6 +1594,119 @@ export function metaRecordExistsByGardenId(gardenId, sessionsDir = defaultMetaSe
     const id = requireGardenId(gardenId);
     return inspectRecordEntry(recordFileFor(sessionsDir, id)) !== "absent";
 }
+/**
+ * Pure: which OTHER records in this store claim `identity`'s `nativeSessionId`.
+ * Returns their filenames, sorted; empty means `identity` holds it alone.
+ *
+ * A RIVAL IS A RECORD THAT COULD BE ADDRESSED INSTEAD. That is the whole test, and it
+ * is narrower than "a file whose bytes mention the same id" — three neighbour shapes
+ * are therefore NOT candidates, and skipping them is a claim about reachability, not
+ * leniency:
+ *
+ *   - NON-REGULAR (symlink/dir/special): rule 1 of {@link certifyActiveStore} says such
+ *     an entry is refused and never followed, because its bytes live where this store
+ *     has no ownership. So it is skipped WITHOUT BEING READ — following it to see
+ *     whether it "counts" would break the rule in the act of enforcing it, and let a
+ *     planted symlink to foreign bytes quarantine a healthy citizen.
+ *   - BODY/FILENAME DRIFT: a record whose body names a different garden id is
+ *     unreachable by garden-id lookup from either name, so it can never be dispatched
+ *     to and cannot compete for an address.
+ *   - UNPARSEABLE by the live schema: same reason — no read path can reach it.
+ *
+ * All three are real certification defects, and the certification and the listing both
+ * say so. What they must not do is blind a healthy citizen, which is the 0.10 "corrupt
+ * blocks registration forever" mistake wearing a new hat.
+ *
+ * A CANDIDATE WE COULD NOT READ IS A DIFFERENT ANSWER AND THROWS. A regular
+ * `.meta.json` this process cannot read might be a genuine duplicate; skipping it would
+ * report "holds it alone" from a scan that never asked, which is exactly the vacuous
+ * pass the store-level readdir guard refuses one level up. ENOENT is the one exception
+ * and the one this repo already recognises everywhere (`inspectRecordEntry`, the cut's
+ * socket walk, `clearFiles`): a file that vanished between the readdir and the read is
+ * not in the store, so it holds nothing.
+ *
+ * The identity's OWN file is excluded by filename, not by identity equality: the caller
+ * has already proven body and filename agree, and a rival is by definition a different
+ * file.
+ */
+export function nativeSessionIdRivals(identity, entries, readRecord) {
+    const own = metaRecordFilename(identity);
+    const rivals = [];
+    for (const entry of entries) {
+        const filename = entry.filename;
+        if (!filename.endsWith(".meta.json") || filename === own)
+            continue;
+        if (!entry.regularFile)
+            continue; // never followed — see rule 1 above
+        let raw;
+        try {
+            raw = readRecord(filename);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue; // raced away — holds nothing
+            throw new MetaRecordError(`cannot read meta-record ${filename} while proving that ${own} holds nativeSessionId ` +
+                `${JSON.stringify(identity.nativeSessionId)} alone: ` +
+                `${err instanceof Error ? err.message : String(err)}. That record may be a duplicate, so this ` +
+                `is an unanswered question, not a clean scan — refusing to dispatch at an address this process ` +
+                `cannot certify.`);
+        }
+        let other;
+        try {
+            other = parseMetaIdentity(raw);
+        }
+        catch {
+            continue; // unreachable by the live schema — not an addressable rival
+        }
+        if (metaRecordFilename(other) !== filename)
+            continue; // drifted — unreachable by garden id
+        if (other.nativeSessionId === identity.nativeSessionId)
+            rivals.push(filename);
+    }
+    return rivals.sort();
+}
+/**
+ * The read a DISPATCH does (#52) — the targeted read PLUS the store-wide half of the
+ * contract that a targeted read cannot see on its own.
+ *
+ * WHY THIS IS A SECOND FUNCTION AND NOT A CHANGE TO {@link readMetaIdentityByGardenId}:
+ * the cost is real and the README says so out loud — a call-relay does not re-scan the
+ * whole store per message, and the mailbox poke, the sender-marker trust and
+ * `entwurf_self` keep the per-entry half exactly as before. What separates the callers
+ * is not how careful they are, it is what they DO with the answer: these two turn
+ * `nativeSessionId` into an ADDRESS — a native-push injection into a live conversation,
+ * a pi resume against a transcript — and each does it ONCE per dispatch, next to a
+ * socket connect and a process spawn. One readdir there is nothing; the same readdir
+ * per relayed message is the design the store deliberately does not have.
+ *
+ * The failure it prevents is not hypothetical corruption. `upsertMetaSession` certifies
+ * and then writes, which is not a transaction: two concurrent births — two SessionStart
+ * hooks, an `entwurf_register_native` racing an agy imprint — can both read one clean
+ * snapshot and mint DIFFERENT garden ids for one native session. Nothing was ever
+ * corrupted on such a host, and yet both ids would direct-inject the same conversation,
+ * or resume one transcript twice under two per-garden-id locks.
+ *
+ * Fails LOUD, never soft: a duplicate is corruption of the address space, and QB1
+ * reserves the soft `bad-target` answer for a record that is simply ABSENT.
+ */
+export function readAddressableMetaIdentity(gardenId, sessionsDir = defaultMetaSessionsDir()) {
+    const identity = readMetaIdentityByGardenId(gardenId, sessionsDir);
+    const dir = path.resolve(expandTilde(sessionsDir));
+    // Entries carry their KIND (readActiveStoreEntries), so the rival scan can refuse a
+    // symlinked neighbour without reading it. A bare-name readdir here would have made
+    // rule 1 unenforceable at exactly the surface that turns a record into an address.
+    // A store that cannot be listed throws from there — answering "unique" from a scan
+    // that never happened is the vacuous pass this whole check exists to refuse.
+    const rivals = nativeSessionIdRivals(identity, readActiveStoreEntries(dir), makeStoreRecordReader(dir));
+    if (rivals.length > 0) {
+        throw new MetaRecordError(`meta-record ${metaRecordFilename(identity)} shares nativeSessionId ` +
+            `${JSON.stringify(identity.nativeSessionId)} with ${rivals.join(", ")} — the native→garden mapping ` +
+            `must be unique, so this store cannot say which record owns that session and dispatching at either ` +
+            `garden id would reach the same native session twice. Archive the generation with ` +
+            `${FRESH_CUT_PRESCRIPTION}.`);
+    }
+    return identity;
+}
 /**
  * Deliver a message body to a garden citizen's mailbox: validate the record
  * exists, write the `.msg` body FIRST, stamp `lastEnqueuedAt`, then poke