@junghanacs/entwurf 0.13.1 → 0.14.0

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

@@ -14,33 +14,13 @@
  *     from mode/action — that would blur the F1 ownership contract).
  *   - `renderEntwurfV2Result` — the result union → `{ text, isError }`, surfacing the carry-overs
  *     the surface must NOT drop: a reject's reason+diagnostic, a control `rejectReason` (N3), a
- *     spawn `lock-retained` diagnostic, and the N1 delivered+lock-dirty `execution-failed`.
+ *     and the N1 delivered+lock-dirty `execution-failed`.
  *   - `runAndRenderEntwurfV2FromSurface` — assemble production deps + run + render, so the root
  *     surface never needs to name the `EntwurfV2RunResult` union (it only sees `{text,isError}`).
  */
-import * as path from "node:path";
 import { makeProductionEntwurfV2Deps } from "./entwurf-v2-production.js";
 import { runEntwurfV2 } from "./entwurf-v2-runner.js";
 import { FRESH_CUT_PRESCRIPTION } from "./meta-session.js";
-/** The operator-policy SSOT for v2 dispatch's preflight prefix-auto-approve roots (5d-4b).
- * ONE shared env var feeds BOTH surfaces (pi-native + MCP) — a pi session and an MCP child
- * both inherit it, so there is no per-surface config fork. `prefixRoots` is operator policy,
- * not session-local UX, so it is an env var, not a pi flag. */
-export const ENTWURF_PREFIX_ROOTS_ENV = "ENTWURF_PREFIX_ROOTS";
-/** Parse `ENTWURF_PREFIX_ROOTS` into the preflight's `prefixRoots`. `path.delimiter`-
- * separated (`:` on Linux/macOS); entries are trimmed, empty segments dropped. Unset / empty
- * / delimiters-only ⇒ `[]` (no prefix promotion — frozen decision 7, no package default).
- * It does NOT throw on a nonexistent/typo path: `preflight`'s normalize keeps an absolute
- * fallback, so a bad root simply never matches (a typo must not broaden approve, and must not
- * turn every owned-outcome dispatch into a loud failure). `~` is left for preflight to expand. */
-export function parseEntwurfPrefixRootsEnv(raw = process.env[ENTWURF_PREFIX_ROOTS_ENV]) {
-    if (!raw)
-        return [];
-    return raw
-        .split(path.delimiter)
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0);
-}
 /** Surface params → the runner's `DispatchInput`. `wants_reply`→`wantsReply`; `intent` and
  * `message` pass through; `mode`/`wantsReply` are left undefined when absent so the decider's
  * own defaults (follow_up / false) apply — no double-default. */
@@ -55,27 +35,36 @@ export function toDispatchInput(params) {
 }
 /**
  * Detour B (B-a) — actionable rendering of an honest reject. The decider is UNCHANGED:
- * a reject stays a reject (Hard Rule 3), and intent is NEVER auto-converted (Hard Rule 2 —
- * owned→fire-and-forget mailbox fallback would break the F1 ownership contract). This only
- * appends a one-line "what to do instead" to the reject TEXT, so an honest reject stops
- * reading as "delivery impossible". Returns undefined for rejects with no useful next step.
+ * a reject stays a reject (Hard Rule 3). This only appends a one-line "what to do instead"
+ * to the reject TEXT, so an honest reject stops reading as "delivery impossible". Returns
+ * undefined for rejects with no useful next step.
  */
 export function actionableRejectHint(reason) {
     switch (reason) {
-        case "backend-liveness-unsupported":
-            // A meta-session backend (e.g. claude-code self-fetch) has no liveness predicate, so
-            // owned-outcome has nothing to own. Replies go to the mailbox via fire-and-forget.
-            return ("meta-session backend has no liveness predicate → owned-outcome is unsupported. " +
-                "To reply, dispatch with intent: fire-and-forget — it routes to the meta-mailbox when a " +
-                "deliverable/active receiver is armed (else it fail-closes as mailbox-undeliverable). " +
-                "(Intent is not auto-converted; you choose it.)");
-        case "owned-live-no-autosend":
-            // A live target is reachable, but owned-outcome is not an auto-send (Q2/F1).
-            return "target is live — owned-outcome never auto-sends. Use intent: fire-and-forget (with wants_reply if you need a reply).";
-        case "native-push-no-resume-authority":
-            // A native-push backend (antigravity) has no pi-child to own, so owned-outcome has
-            // nothing to own. Delivery is a direct inject via fire-and-forget.
-            return "native-push target (e.g. antigravity) has no resume/spawn authority → owned-outcome is unsupported. Use intent: fire-and-forget to direct-inject into the live conversation.";
+        case "dormant-fire-forget-unsupported":
+            // The cell that carries the whole cost of the visible-first cut. Naming the real
+            // state — the citizen exists and is not running — matters more than ever now that
+            // there is no verb behind it: a caller that reads "reject" as "wrong id" goes
+            // looking in the wrong place.
+            return ("this citizen's record is intact but its session is not running, and delivery has no way to wake it. " +
+                "The resume that used to answer here launched a hidden background child and was withdrawn under the " +
+                "visible-first rule; the visible same-id resume is the separate lifecycle verb entwurf_resume_call. " +
+                "Reopen the citizen with entwurf_resume_call {target} (pi targets only; it runs no turn), then dispatch again.");
+        case "indeterminate-no-spawn":
+            // The socket probe did not settle, so liveness is UNKNOWN — an unestablished probe
+            // is not a measured death, and dispatching into it could double-deliver. Say
+            // "the PROBE was inconclusive", never "the socket answered inconclusively":
+            // `indeterminate` also covers a probe that got no answer at all, was refused by
+            // permissions, or timed out, and "answered" claims a reply that may never have
+            // existed. The wire id is FROZEN and still spells "-no-spawn"; it names the rule
+            // (never dispatch into an indeterminate target), not a capability that still
+            // exists. So the hint's job is to say plainly what did NOT happen: nothing
+            // delivered, nothing started.
+            return ("the control-socket probe was inconclusive, so the target's liveness is UNKNOWN — this is not a " +
+                "measured death. NOTHING was delivered and NO process was started (the reason id keeps its frozen " +
+                "'-no-spawn' wire spelling from an era when one could be; entwurf_v2 starts nothing on any rail). " +
+                "Re-run entwurf_peers to re-probe; if it stays indeterminate, check for a stale socket file left at " +
+                "that garden id by a session that died without cleaning up.");
         case "native-push-target-dead":
             // The adapter probe found no live host process for the conversation.
             return "native-push conversation is not live (no host process found). Re-open the conversation, then retry — there is nothing to inject into.";
@@ -97,7 +86,7 @@ export function actionableRejectHint(reason) {
 /** Render the outcome-rich result to `{ text, isError }`. A reject or a thrown/failed/dirty
  * delivery is `isError:true`; a sent/fallback-sent/enqueued/observed delivery is `isError:false`.
  * A control in-band `rejected` is a non-delivery (isError:true) and carries N3 `rejectReason`
- * when present; a spawn `lock-retained` is fail-closed (isError:true) with its diagnostic. */
+ * when present. */
 export function renderEntwurfV2Result(result) {
     switch (result.kind) {
         case "rejected": {
@@ -125,27 +114,6 @@ export function renderEntwurfV2Result(result) {
                     isError: !delivered,
                 };
             }
-            if (o.transport === "spawn-bg") {
-                const res = o.result;
-                if (res.kind === "lock-retained") {
-                    const d = res.diagnostic;
-                    return {
-                        text: `entwurf_v2 spawn-bg LOCK RETAINED (${res.reason}) — lock NOT released, operator must clear:` +
-                            `\n  target: ${d.targetGardenId}` +
-                            `\n  lockPath: ${d.lockPath}` +
-                            `\n  expectedSocketPath: ${d.expectedSocketPath}` +
-                            `\n  observeTimeoutMs: ${d.observeTimeoutMs}, killGraceMs: ${d.killGraceMs}` +
-                            (res.error ? `\n  error: ${res.error}` : ""),
-                        isError: true,
-                    };
-                }
-                if (res.kind === "spawn-start-failed") {
-                    return { text: `entwurf_v2 spawn-bg failed to start: ${res.error}`, isError: true };
-                }
-                const pid = "pid" in res && res.pid !== undefined ? ` (pid ${res.pid})` : "";
-                const exit = res.kind === "child-exited" ? ` exitCode=${res.exitCode}` : "";
-                return { text: `entwurf_v2 spawn-bg → ${res.kind}${pid}${exit}, lock released`, isError: false };
-            }
             if (o.transport === "native-push") {
                 // direct-inject succeeded; note if the 1-shot re-probe retry fired.
                 return {
@@ -179,12 +147,7 @@ export function renderEntwurfV2Result(result) {
  * fence types stay behind this one entry point.
  */
 export async function runAndRenderEntwurfV2FromSurface(params, opts) {
-    const prodOpts = {
-        senderProvider: opts.senderProvider,
-        agentDir: opts.agentDir,
-        // Explicit opts win (test / future surface override); otherwise the shared env SSOT.
-        prefixRoots: opts.prefixRoots ?? parseEntwurfPrefixRootsEnv(),
-    };
+    const prodOpts = { senderProvider: opts.senderProvider };
     const result = await runEntwurfV2(toDispatchInput(params), makeProductionEntwurfV2Deps(prodOpts));
     return renderEntwurfV2Result(result);
 }

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

@@ -0,0 +1,256 @@
+/**
+ * entwurf-v2-visible-resume — stand a dormant pi citizen back up in a window the operator can
+ * see, under the same garden id, and say only what was actually observed.
+ *
+ * ── Where this sits ──
+ *
+ *   surface (entwurf-control.ts · mcp bridge index.ts)   composition root: supplies `launch`
+ *     └─ entwurf-v2-visible-resume  (this file)          v2 leaves ONLY: lock, record, socket
+ *          └─ deps.launch(argv, cwd)  ── INJECTED SEAM ──→ mux-resume-call → placement leaf
+ *
+ * The seam is what keeps `docs/mux-launch-rail.md` §11 intact in both directions: v2 never
+ * imports mux, mux never imports entwurf core. This module cannot open a window; it can only
+ * ask whoever wired it to. That is deliberate — it means the delivery fence stays exactly where
+ * `check-mux-launch` scans for it.
+ *
+ * ── Why a resume is structurally SMALLER than a fresh call on identity, and LARGER on the lock ──
+ *
+ * `mux-fresh-call` mints no identity: the sibling calls back and its envelope IS the address.
+ * A resume already knows the address — that is what "same-id" means — so there is no nonce, no
+ * callback, and no correlation receipt. What it gains instead is the lock: two visible resumes
+ * of one garden id would put two processes on one transcript, and `entwurf_v2`'s in-domain
+ * dispatch takes the SAME per-gid lock, so a resume and a live send serialise against each other
+ * for free. The lock is consistency, not defence — there is no watcher behind it.
+ *
+ * ── The observation is a startup wait, not supervision ──
+ *
+ * Measured 2026-08-06: the resumed control socket appeared ~2s (ACP) and ~4s (native) after the
+ * window opened. A single immediate probe would therefore have observed `dead` and reported a
+ * successful resume as unobserved. So the observation is ONE bounded operation with a short
+ * interval, and everything that would make it supervision is deliberately absent:
+ *
+ *   - no relaunch, ever. A refused or dead launch is a result, not a retry trigger.
+ *   - no pane watcher. Until the deadline this module looks at ONE thing: the socket.
+ *   - no env knob on the timeout. A tunable would make "unobserved" mean different things on
+ *     different hosts, and the receipt would stop being comparable.
+ *
+ * On timeout the lock is RELEASED and the window is LEFT OPEN. That is the same rule fresh-call
+ * already ships ("a launch with no callback is a real outcome"): the window is visible, the
+ * operator can look, and a retained lock on a visible artifact is the worse failure — it would
+ * have to be cleared by hand on every slow host.
+ *
+ * ── Two receipts, never merged ──
+ *
+ * `launch` says tmux made a window and was asked to start pi. `observation` says whether the
+ * citizen's socket came back under the same id. Neither says the resumed citizen did anything:
+ * a resume runs no turn (measured — the transcript stayed byte-identical), so there is no turn
+ * outcome for this module to claim.
+ */
+import { buildResumePiArgs } from "./entwurf-resume-args.js";
+import { ENTWURF_V2_LOCK_DIR, acquireLock as realAcquireLock, releaseLock as realReleaseLock, } from "./entwurf-v2-lock.js";
+import { ResumeBackendUnsupportedError, resolveResumeLaunchIdentity, } from "./resume-launch-identity.js";
+import { isValidSessionId } from "./session-id.js";
+import { CONTROL_SOCKET_DIR, inspectTargetControlSocket, mapInspectionToLiveness, } from "./socket-discovery.js";
+import { probeSocketLiveness } from "./socket-probe.js";
+/** How long ONE observation operation waits for the resumed citizen's socket. Fixed on purpose:
+ * see the module header on why this is not an env knob. */
+export const RESUME_OBSERVE_TIMEOUT_MS = 30_000;
+/** How often that one operation re-inspects. Short enough that a 2s startup is reported as the
+ * success it is, long enough that a 30s wait is ~60 lstats and not a spin. */
+export const RESUME_OBSERVE_INTERVAL_MS = 500;
+/** Production wiring for everything except the launch seam — the surface owns that, because it
+ * is the only layer allowed to know both halves. */
+export function makeVisibleResumeDeps(launch, overrides = {}) {
+    return {
+        acquireLock: (gid) => realAcquireLock(gid, { dir: ENTWURF_V2_LOCK_DIR }),
+        releaseLock: (claim) => realReleaseLock(claim, { dir: ENTWURF_V2_LOCK_DIR }),
+        resolveIdentity: resolveResumeLaunchIdentity,
+        inspectSocket: (gid) => inspectTargetControlSocket(gid, CONTROL_SOCKET_DIR),
+        probeSocket: (socketPath) => probeSocketLiveness(socketPath),
+        launch,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        ...overrides,
+    };
+}
+/**
+ * Reopen `targetGardenId` in a visible window.
+ *
+ * Order is the safety argument. The lock is taken FIRST, before the liveness question, so the
+ * answer cannot change under us between reading it and acting on it — a competing resume would
+ * otherwise pass its own `dead` check while ours was launching. Identity is resolved under that
+ * lock and BEFORE any window opens, so a citizen with no transcript (measured: a pi that never
+ * took a turn has a socket and a record but no transcriptPath) fails loud with its own cause and
+ * leaves nothing behind.
+ */
+export async function visibleResume(targetGardenId, deps) {
+    // The address grammar is `session-id.js`'s, not a local copy. The socket filename, the lock
+    // path and the record key are all keyed on that SAME id, so a second regex here could drift
+    // into accepting an id one of those three would reject — and this value becomes a lock path
+    // and a socket path a few lines down.
+    if (!isValidSessionId(targetGardenId)) {
+        return {
+            ok: false,
+            reason: "target-invalid",
+            detail: `${JSON.stringify(targetGardenId)} is not a garden id (YYYYMMDDTHHMMSS-xxxxxx)`,
+        };
+    }
+    const acquired = deps.acquireLock(targetGardenId);
+    if (!acquired.ok) {
+        return { ok: false, reason: "target-locked", detail: acquired.conflict.detail };
+    }
+    const claim = acquired.claim;
+    let released = false;
+    /** Release exactly once, and never let a failed release read as success. A lock this module
+     * took and could not give back is a fact the operator has to know about — the next resume or
+     * send against that citizen will be refused, and silence would send them looking at the wrong
+     * layer. */
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        const outcome = deps.releaseLock(claim);
+        if (outcome !== "released") {
+            throw new Error(`entwurf-v2-visible-resume: attempted to release the lock for ${targetGardenId}; the release returned ` +
+                `"${outcome}" instead of "released" (${claim.lockPath}) — the per-gid lock may still be held; clear ` +
+                `it by hand before resuming or dispatching to that citizen again.`);
+        }
+    };
+    try {
+        // Record authority, under the lock, before any window. Every failure here is a cause-rich
+        // throw from the leaf (foreign transcript, relative or deleted session file, no recorded
+        // model, unresolvable bridge) and is deliberately NOT re-typed into a reject — with ONE
+        // exception, matched on the error's own `reason` FIELD rather than its wording: a citizen
+        // of a backend that has no same-id resume. That is a capability boundary, not a defect, so
+        // it is a named refusal. The record is not read a second time to ask which backend it was;
+        // the error already carries it.
+        let identity;
+        try {
+            identity = deps.resolveIdentity(targetGardenId);
+        }
+        catch (err) {
+            if (err instanceof ResumeBackendUnsupportedError) {
+                return {
+                    ok: false,
+                    reason: err.reason,
+                    detail: `${targetGardenId} is a ${err.backend} citizen; only pi citizens stand a control socket up, ` +
+                        `so only they can be reopened under the same garden id`,
+                };
+            }
+            throw err;
+        }
+        // Liveness preflight, still under the lock. A live citizen is addressed with
+        // `entwurf_v2 fire-and-forget`, not reopened — and refusing here is also what stops two
+        // windows existing for one garden id.
+        const inspection = await deps.inspectSocket(targetGardenId);
+        const mapped = await mapInspectionToLiveness(inspection, deps.probeSocket);
+        if ("addressConflict" in mapped) {
+            return {
+                ok: false,
+                reason: "target-address-conflict",
+                detail: `the control-socket path for ${targetGardenId} is a symlink or not a socket — that address is ` +
+                    `corrupt, and resuming would stand a citizen up behind it`,
+            };
+        }
+        if (mapped.liveness === "alive") {
+            return {
+                ok: false,
+                reason: "target-live",
+                detail: `${targetGardenId} is already live at ${mapped.socketPath} — send to it with entwurf_v2 fire-and-forget instead`,
+            };
+        }
+        if (mapped.liveness === "indeterminate") {
+            return {
+                ok: false,
+                reason: "target-indeterminate",
+                detail: `the control-socket probe for ${targetGardenId} was inconclusive — it is not provably dormant, ` +
+                    `and resuming a citizen that is actually running would put two processes on one transcript`,
+            };
+        }
+        const runtimeArgs = buildResumePiArgs({
+            sessionFile: identity.sessionFile,
+            explicitExtensionArgs: identity.explicitExtensionArgs,
+            provider: identity.provider,
+            model: identity.model,
+        });
+        const launched = deps.launch({ cwd: identity.cwd, runtimeArgs });
+        if (!launched.ok) {
+            return { ok: false, reason: "launch-refused", detail: `${launched.reason} — ${launched.hint}` };
+        }
+        const observation = await observeSameGidSocket(targetGardenId, mapped.socketPath, deps);
+        return {
+            ok: true,
+            launch: { targetGardenId, sessionFile: identity.sessionFile, handle: launched.handle },
+            observation,
+        };
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * ONE bounded operation: wait for the SAME garden id's control socket to answer. Alive is the
+ * only early exit — an inspection that comes back absent, corrupt or inconclusive during startup
+ * is a normal intermediate state, not a verdict, so it is simply not-yet.
+ */
+export async function observeSameGidSocket(targetGardenId, socketPath, deps, timeoutMs = RESUME_OBSERVE_TIMEOUT_MS, intervalMs = RESUME_OBSERVE_INTERVAL_MS) {
+    const started = deps.now();
+    for (;;) {
+        const inspection = await deps.inspectSocket(targetGardenId);
+        const mapped = await mapInspectionToLiveness(inspection, deps.probeSocket);
+        if (!("addressConflict" in mapped) && mapped.liveness === "alive") {
+            return { kind: "socket-alive", socketPath: mapped.socketPath, waitedMs: deps.now() - started };
+        }
+        if (deps.now() - started >= timeoutMs) {
+            return { kind: "resume-unobserved", socketPath, waitedMs: deps.now() - started };
+        }
+        await deps.sleep(intervalMs);
+    }
+}
+const REJECT_HINT = {
+    "target-invalid": "no citizen has that id; discover targets with entwurf_peers",
+    "target-not-pi": "that citizen's backend has no same-id resume — reach it with entwurf_v2, or open a fresh sibling",
+    "target-locked": "another resume or dispatch holds this citizen's lock right now",
+    "target-live": "that citizen is already running — this verb only reopens dormant ones",
+    "target-indeterminate": "the socket probe could not prove the citizen is dormant, so nothing was started",
+    "target-address-conflict": "that citizen's control-socket path is corrupt",
+    "launch-refused": "tmux was never asked to open a window",
+};
+/**
+ * ONE renderer for both surfaces — the same reason `mux-fresh-call` has one: the two
+ * registrations are separate literals, and a shared renderer is what keeps the operator-visible
+ * answer from drifting apart between native pi and the MCP bridge.
+ *
+ * The success text keeps the two receipts visibly apart, including in the good case. A reader
+ * who sees "window opened" and "socket alive" as one sentence has been told the resume worked;
+ * a reader who sees them as two facts can tell which one is missing when only one is there.
+ */
+export function renderVisibleResume(result) {
+    if (!result.ok) {
+        return {
+            text: `entwurf_resume_call rejected: ${result.reason} — ${REJECT_HINT[result.reason]}. ` +
+                `${result.detail}. No window was opened.`,
+            isError: true,
+        };
+    }
+    const h = result.launch.handle;
+    const observed = result.observation.kind === "socket-alive";
+    return {
+        text: `[entwurf resume call ↻]\n` +
+            `  target:   ${result.launch.targetGardenId}\n` +
+            `  session:  ${result.launch.sessionFile}\n` +
+            `  runtime:  ${h.runtimePath} (requested start cwd ${h.cwd})\n` +
+            `  window:   ${h.windowId} (index ${h.windowIndex}) in session ${h.sessionId}\n` +
+            `  pane:     ${h.paneId} pid ${h.panePid}\n` +
+            `\n` +
+            `LAUNCH receipt: tmux created that window and was asked to start pi on the transcript above.\n` +
+            (observed
+                ? `OBSERVATION receipt: the control socket for ${result.launch.targetGardenId} answered after ` +
+                    `${result.observation.waitedMs}ms — that citizen is addressable again, and entwurf_v2 fire-and-forget ` +
+                    `now reaches it. No turn was run by this call.`
+                : `OBSERVATION receipt: resume-unobserved — the control socket did not answer within ` +
+                    `${result.observation.waitedMs}ms. The window is open and visible; read it directly. The lock was ` +
+                    `released, nothing was retried, and nothing was killed.`),
+        isError: false,
+    };
+}

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

@@ -411,7 +411,7 @@ export function parseMetaIdentity(json) {
 // `wakeMode` describes the last centimetre, not citizen rank. The control-socket
 // adapter injects the body into a pi turn, so backend `pi` is `direct-inject`;
 // Claude's mailbox is `self-fetch`; native-push adapters are direct injection.
-// Dormant spawn-bg resume is a separate transport/ownership decision and does not
+// Resuming a dormant citizen is a separate lifecycle capability and does not
 // turn the pi record into a mailbox citizen.
 // ---------------------------------------------------------------------------
 /** Bump only on a breaking capability-registry shape change; the parser refuses other versions. */
@@ -890,6 +890,21 @@ export function listAllMetaIdentities(entries, readRecord, opts = {}) {
     errors.sort((a, b) => (a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0));
     return { identities, errors };
 }
+/**
+ * The fs-bound listing — the same binding shape {@link certifyActiveStoreDir} gives the
+ * certification: one resolved dir, kind-carrying entries, the fd-guarded record reader.
+ * Exists so an in-repo facts surface (`meta-facts`, #65) reuses THE listing contract
+ * instead of re-binding readdir/read by hand — the exact drift that made external
+ * consumers carry a decaying copy of the certification. No semantics of its own:
+ * everything it returns is {@link listAllMetaIdentities} over the real store.
+ */
+export function listAllMetaIdentitiesDir(dir) {
+    const resolved = path.resolve(expandTilde(dir));
+    return {
+        dir: resolved,
+        ...listAllMetaIdentities(readActiveStoreEntries(resolved), makeStoreRecordReader(resolved)),
+    };
+}
 /**
  * The pure core of the `upsert` CLI (3D-4; v3 identity since the #50 cut). Keyed
  * on RECORD EXISTENCE, never on a backend `source` field:
@@ -1423,8 +1438,13 @@ export function readMetaReceiverMarker(opts) {
  * A narrower scan is not a smaller version of this: asking only about MY
  * `nativeSessionId` writes happily beside a drifted or duplicated record that the
  * doctor refuses, which is how a host ends up certified by one surface and not
- * the other. The write is tmp-file + rename so a crash never leaves a
- * half-written record (#30 crash-safety).
+ * the other.
+ *
+ * The write is split by ACTION (#66): ATTACH rewrites its OWN record atomically
+ * in place (tmp + rename, #30 crash-safety); CREATE publishes exclusively
+ * (tmp + link) and fails loud if the minted garden id's final path already
+ * exists — certification cannot see a future minted gid, so replacement-free
+ * publish is the only collision safety a create has.
  */
 export function upsertMetaSession(opts) {
     const dir = path.resolve(expandTilde(opts.dir ?? defaultMetaSessionsDir()));
@@ -1436,15 +1456,81 @@ export function upsertMetaSession(opts) {
     const existing = cert.records.find((record) => record.identity.nativeSessionId === target)?.identity ?? null;
     const decision = decideUpsert(existing, opts.input, opts.now);
     const file = path.join(dir, metaRecordFilename(decision.record));
-    atomicWriteIdentity(file, decision.record);
+    if (decision.action === "create")
+        publishExclusiveIdentity(file, decision.record);
+    else
+        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 (v3 identity write). */
+/**
+ * ATTACH replace primitive: tmp-file + rename so a crash never leaves a
+ * half-written record (#30 crash-safety). rename(2) REPLACES an existing final
+ * path, which is exactly right for attach (the record being rewritten is the
+ * caller's own) and exactly wrong for create — a freshly minted garden id must
+ * never land on this path (#66).
+ */
 function atomicWriteIdentity(file, identity) {
     const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
     fs.writeFileSync(tmp, serializeMetaIdentity(identity), { mode: 0o600 });
     fs.renameSync(tmp, file);
 }
+/**
+ * CREATE publish primitive: same-directory tmp + `link(2)` to the final path.
+ * link fails with EEXIST when the final path already exists — the kernel makes
+ * the existence check and the publish one atomic step, so there is no
+ * check-then-rename TOCTOU window and a same-second 24-bit garden-id suffix
+ * collision can never silently replace whatever already holds the final path
+ * (#66). The occupied entry's bytes are untouched on refusal; tmp cleanup is
+ * attempted on every path, and a published-with-residue state fails loud.
+ *
+ * @internal Exported only as the production subject for the meta-session gate's
+ * deterministic collision oracle (the minted suffix is random, so the public
+ * upsert seam cannot force a collision deterministically). Not an
+ * operator/package API.
+ */
+export function publishExclusiveIdentity(file, identity) {
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, serializeMetaIdentity(identity), { mode: 0o600 });
+    try {
+        fs.linkSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch (cleanupErr) {
+            // The primary link error stays the truth of this publish; a cleanup errno
+            // never masks it. ENOENT is silent (no residue = desired state); any other
+            // cleanup failure is an operator diagnostic on stderr, then the primary throws.
+            if (cleanupErr.code !== "ENOENT") {
+                process.stderr.write(`[meta-session] tmp cleanup after a failed CREATE publish also failed (${tmp}): ` +
+                    `${cleanupErr.message}\n`);
+            }
+        }
+        if (err.code === "EEXIST") {
+            throw new MetaRecordError(`meta-record CREATE collision: garden id "${identity.gardenId}" already has an entry at ` +
+                `${file}. Exclusive publish refused to replace it — the occupied final-path entry was ` +
+                `not modified and no ACTIVE record was published for nativeSessionId ` +
+                `"${identity.nativeSessionId}".`);
+        }
+        throw err;
+    }
+    try {
+        fs.unlinkSync(tmp);
+    }
+    catch (err) {
+        // ENOENT is the goal state, not a failure: the record is published and no
+        // tmp remains, so there is nothing left to clean.
+        if (err.code === "ENOENT")
+            return;
+        // Never roll the final back: the record IS published (link succeeded).
+        throw new MetaRecordError(`meta-record CREATE for garden id "${identity.gardenId}" is already published at ${file}, ` +
+            `but temp cleanup failed (${tmp}): ${err.message}. The caller aborts here, so ` +
+            `it received no successful birth/registration receipt; remove the temp file and retry — ` +
+            `a retry with the same nativeSessionId will ATTACH to the published record, not mint a ` +
+            `second identity.`);
+    }
+}
 // ---------------------------------------------------------------------------
 // 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