@junghanacs/entwurf 0.41.2 → 0.50.0

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

@@ -23,7 +23,11 @@
  * This is the tmux rail. A caller inside herdr (`HERDR_ENV=1`, herdr's own marker, read for its
  * exact value as `fresh-call-dispatch` does) is refused by name before anything else: herdr owns
  * placement there, and an ambient `TMUX` that happens to be set would otherwise put the window in
- * a session the operator is not looking at. There is no herdr resume rail yet and no fallback.
+ * a session the operator is not looking at. Since #157 G1a the shared rail root (`fresh-call-dispatch`)
+ * hands a resume inside herdr to the separate herdr rail (`herdr-resume-call.ts`) and never reaches
+ * this leaf there;
+ * this guard stays so that a direct caller still cannot open a tmux window from inside herdr. No
+ * fallback in either direction.
  *
  * ── The cwd is the whole reason this module owns its own tmux argv ──
  *
@@ -48,6 +52,7 @@
  * where the pane actually landed is a separate query against the stable pane id, and it belongs
  * to acceptance, not to the product's launch receipt.
  */
+import { ENTWURF_RESUME_LAUNCH_REJECT_HINTS } from "./agent-guidance.js";
 import { classifyTmuxCwd } from "./classify-tmux-cwd.js";
 import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, SCRUBBED_INHERITED_ENV, } from "./mux-launch.js";
 import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
@@ -55,24 +60,53 @@ import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWin
  * backend boundary is enforced upstream by `resolveResumeLaunchIdentity`, and this is the mux half
  * of the same fact. */
 export const RESUME_CALL_RUNTIME = { pi: "pi", "claude-code": "claude" };
+/**
+ * #157 B3: a pi-durable resume reopens through the MANAGED verb, exactly as its fresh call does —
+ * `entwurf pi-durable` verifies this package's carrier and its SDK set before anything runs, and the
+ * durable app is never started bare. It is its own entry (`resumePiDurableCall`) rather than a row of
+ * the table above, because it is the one resume whose launch also carries an environment.
+ */
+export const RESUME_CALL_PI_DURABLE_RUNTIME = "entwurf";
+/** The five `NAME=value` assignments, in the fixed order, or none. Every value must be an absolute
+ * path: a relative one would resolve against whatever directory the child starts in. */
+function adoptEnvAssignments(adoptEnv) {
+    if (adoptEnv === undefined)
+        return [];
+    const pairs = [
+        ["PI_CODING_AGENT_DIR", adoptEnv.PI_CODING_AGENT_DIR],
+        ["ENTWURF_META_SESSIONS_DIR", adoptEnv.ENTWURF_META_SESSIONS_DIR],
+        ["ENTWURF_META_MAILBOX_DIR", adoptEnv.ENTWURF_META_MAILBOX_DIR],
+        ["ENTWURF_META_SENDERS_DIR", adoptEnv.ENTWURF_META_SENDERS_DIR],
+        ["ENTWURF_META_RECEIVERS_DIR", adoptEnv.ENTWURF_META_RECEIVERS_DIR],
+    ];
+    for (const [name, value] of pairs) {
+        if (typeof value !== "string" || !value.startsWith("/")) {
+            throw new Error(`mux-resume-call: refusing to build argv with a non-absolute ${name}: ${JSON.stringify(value)}`);
+        }
+    }
+    return pairs.map(([name, value]) => `${name}=${value}`);
+}
 /**
  * Launch argv: the leaf's detached-append shape, the fixed identity scrub (`SCRUBBED_INHERITED_ENV`,
- * the same two assignments every fresh window carries), `-c`, the runtime, then the caller's flags.
+ * the same two assignments every fresh window carries), for a pi-durable adoption the five fixed
+ * projection assignments after it (#157 B3), `-c`, the runtime, then the caller's flags.
  * `--` is what keeps tmux from reading the runtime or its flags as tmux options. The scrub is not a
  * carrier: it only empties identity a tmux server may have inherited, and a resumed Claude Code
  * (which, unlike pi, never re-exports its own) would otherwise present a stale one to its bridge.
  */
-export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs) {
+export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs, adoptEnv) {
     assertSelector("session", placement.sessionId);
     assertLaunchTarget(runtimePath);
     const bad = classifyTmuxCwd(cwd);
     if (bad)
         throw new Error(`mux-resume-call: refusing to build argv with an unusable cwd (${bad}): ${cwd}`);
+    const adoptAssignments = adoptEnvAssignments(adoptEnv);
     return [
         "new-window",
         "-d",
         "-a",
         ...SCRUBBED_INHERITED_ENV.flatMap((assignment) => ["-e", assignment]),
+        ...adoptAssignments.flatMap((assignment) => ["-e", assignment]),
         "-t",
         `${placement.sessionId}:{end}`,
         "-c",
@@ -93,6 +127,18 @@ export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs) {
  * `runtimeArgs` is passed through untouched. This module does not know what `--session` means.
  */
 export function resumeCall(params, env = process.env) {
+    return openResumeWindow(RESUME_CALL_RUNTIME[params.backend], params, undefined, env);
+}
+/**
+ * #157 B3: the pi-durable resume window. The same order, refusals and receipt as `resumeCall` — the
+ * runtime is the managed `entwurf`, and the window additionally carries the fixed adopt projection.
+ * `runtimeArgs` (the managed verb and its closed adopt context) is passed through untouched; this
+ * module never decodes it.
+ */
+export function resumePiDurableCall(params, env = process.env) {
+    return openResumeWindow(RESUME_CALL_PI_DURABLE_RUNTIME, params, params.adoptEnv, env);
+}
+function openResumeWindow(runtime, params, adoptEnv, env) {
     if (env.HERDR_ENV === "1")
         return { ok: false, reason: "herdr-resume-unsupported" };
     const badCwd = classifyTmuxCwd(params.cwd);
@@ -100,7 +146,7 @@ export function resumeCall(params, env = process.env) {
         return { ok: false, reason: badCwd };
     let runtimePath;
     try {
-        runtimePath = resolveRuntimeOnPath(RESUME_CALL_RUNTIME[params.backend], env);
+        runtimePath = resolveRuntimeOnPath(runtime, env);
     }
     catch (err) {
         if (err instanceof LaunchPreconditionError)
@@ -112,7 +158,7 @@ export function resumeCall(params, env = process.env) {
         return { ok: false, reason: inspected.reason };
     const placement = inspected.placement;
     requireSameContext("resumeCall", placement, env);
-    const run = runTmux(buildResumeCallArgs(placement, params.cwd, runtimePath, params.runtimeArgs), env);
+    const run = runTmux(buildResumeCallArgs(placement, params.cwd, runtimePath, params.runtimeArgs, adoptEnv), env);
     assertTmuxOk("new-window", run);
     let fields;
     try {
@@ -136,21 +182,22 @@ export function resumeCall(params, env = process.env) {
     };
 }
 /** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
- * they will guess about. */
+ * they will guess about. The text is authored in root ENTWURF.json (#154 C1-D); each
+ * key is bound explicitly so the reason union stays exhaustive here. */
 export const RESUME_CALL_REJECT_HINT = {
-    "no-tmux-context": "this agent is not running inside tmux, so there is no session to reopen the citizen in",
-    "anchor-malformed": "TMUX_PANE is not a native pane id",
-    "anchor-unresolved": "tmux resolved no pane for this agent's anchor",
-    "anchor-mismatch": "tmux answered about a different pane than the one asked about",
-    "cwd-not-absolute": "the recorded cwd is not an absolute path",
-    "cwd-format-token": "the recorded cwd contains '#', which tmux expands as a format inside -c — it would silently rewrite the path or run a command",
-    "cwd-missing": "the recorded cwd no longer exists; tmux would not report this, it would open the window in $HOME and look successful",
-    "cwd-not-directory": "the recorded cwd exists but is not a directory",
-    "herdr-resume-unsupported": "this agent runs inside herdr, and same-id resume has only a tmux rail — nothing was opened in any ambient tmux session",
-    "runtime-unresolved": "the citizen's runtime (pi or claude) is not installed on PATH",
-    "runtime-not-absolute": "the resolved runtime path is not absolute",
-    "runtime-path-whitespace": "the resolved runtime path contains whitespace, which tmux would re-split",
-    "runtime-missing": "nothing exists at the resolved runtime path",
-    "runtime-not-regular-file": "the resolved runtime path is not a regular file",
-    "runtime-not-executable": "the resolved runtime path is not executable",
+    "no-tmux-context": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["no-tmux-context"],
+    "anchor-malformed": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["anchor-malformed"],
+    "anchor-unresolved": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["anchor-unresolved"],
+    "anchor-mismatch": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["anchor-mismatch"],
+    "cwd-not-absolute": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-not-absolute"],
+    "cwd-format-token": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-format-token"],
+    "cwd-missing": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-missing"],
+    "cwd-not-directory": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-not-directory"],
+    "herdr-resume-unsupported": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["herdr-resume-unsupported"],
+    "runtime-unresolved": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-unresolved"],
+    "runtime-not-absolute": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-not-absolute"],
+    "runtime-path-whitespace": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-path-whitespace"],
+    "runtime-missing": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-missing"],
+    "runtime-not-regular-file": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-not-regular-file"],
+    "runtime-not-executable": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-not-executable"],
 };

package/mcp/entwurf-bridge/dist/pi-extensions/lib/pi-durable-fresh-preflight.js

@@ -19,7 +19,7 @@
  *                 `{v:2,task}` payload, whose decoder caps `task` at 16000 characters. A framed
  *                 task over that cap would open a window whose bootstrap refuses its own argv.
  *
- * ── Then the carrier, then the four units ──
+ * ── Then the carrier, then the five units ──
  *
  *   carrier          the package's own pi-durable carrier and its declared SDK set, verified
  *                    (`pi-durable-runtime.ts`); passed in as that check's verdict.
@@ -29,6 +29,9 @@
  *                    it every dispatch to the citizen is the honest `mailbox-undeliverable`.
  *   visible identity the packaged bootstrap — the one that hands the TUI the view whose conversation
  *                    labels carry the garden id.
+ *   owner fence      the compiled owner fence in the same closure — the packaged bootstrap imports it,
+ *                    so without it the bootstrap cannot load. Asked here as a file this package must
+ *                    ship, nothing more; the carrier verdict above does not cover it.
  *
  * ── What this deliberately does NOT claim ──
  *
@@ -78,6 +81,8 @@ export function piDurableFreshPreflight(params) {
         return "pi-durable-receive-unit-missing";
     if (!existsSync(layout.bootstrap))
         return "pi-durable-visible-identity-missing";
+    if (!existsSync(layout.ownerFence))
+        return "pi-durable-owner-fence-missing";
     return null;
 }
 /** Repair text beside the predicate that decides it. The runtime reasons keep theirs on the runtime
@@ -89,4 +94,5 @@ export const PI_DURABLE_PREFLIGHT_HINT = {
     "pi-durable-mcp-hand-missing": "this Entwurf package has no compiled entwurf-bridge entry, so the sibling's callback tool would not exist — reinstall or rebuild Entwurf",
     "pi-durable-receive-unit-missing": "this Entwurf package's compiled owner join does not admit pi-durable-host, so nothing could ever be delivered to the sibling — reinstall or rebuild Entwurf",
     "pi-durable-visible-identity-missing": "this Entwurf package has no packaged pi-durable bootstrap (pi/pi-durable/bootstrap.mjs), so no TUI would carry the garden id — reinstall Entwurf",
+    "pi-durable-owner-fence-missing": "this Entwurf package has no compiled pi-durable owner fence (mcp/entwurf-bridge/dist/pi-extensions/lib/pi-durable-owner-fence.js), which its packaged bootstrap imports — reinstall or rebuild Entwurf",
 };

package/mcp/entwurf-bridge/dist/pi-extensions/lib/pi-durable-location.js

@@ -0,0 +1,347 @@
+/**
+ * pi-durable LOCATION EVIDENCE (#157 B3, C4 locator leaf) — where a pi-durable citizen's native
+ * session directory physically is, written by the durable host's own birth and bound to its
+ * record by the record's `attachIncarnation`.
+ *
+ * WHAT THIS IS. One garden-keyed file per pi-durable citizen, `<locations>/<gardenId>.location.json`,
+ * holding the minimum location + binding evidence its attach already knows: the native session id,
+ * the realpath cwd, `realpath(session.directory)`, the owner pid and its start key, and the
+ * `attachIncarnation` minted in the same record-arm-locked commit as the record's own. The record
+ * stays the SOLE address (AGENTS.md Hard Rule 2): this file is evidence the record points at, keyed
+ * by the record's garden id, and it counts only while the record carries the very binding it copied.
+ *
+ * WHAT THIS IS NOT. Not an address, a registry, a presence marker, a liveness or ownership verdict,
+ * a dormancy proof or a guarded enrollment. A matching pair says ONE thing: the record's last
+ * committed binding named this physical directory and this owner incarnation. A process holding the
+ * session before its own commit (the unbound window from the native lease to this birth) is
+ * invisible here; only an owner claim taken before the lease could see it, and none exists in this
+ * leaf. Public resume of a pi-durable citizen stays refused.
+ *
+ * WHERE. `<dirname(receiversDir)>/meta-pi-durable-locations`: a sibling of the receivers root the
+ * birth actually uses, the same derivation as the record-arm lock dir, so a sandboxed receivers root
+ * sandboxes it too and no new environment carrier exists. It is deliberately NOT inside the record
+ * store (every entry there is certified), the receivers or senders roots (fresh-cut walks every entry
+ * there as a marker) or the mailbox (fresh-cut archives it).
+ *
+ * LIFECYCLE (Rule 8). Written by a pi-durable birth only; never removed by retire, close, the
+ * doorbell or any reader. No reader in this tree enumerates the directory: fresh-cut archives the
+ * store and the mailbox and walks the marker roots, the doctor certifies the store. A carrier whose
+ * record is absent (a cut generation) or whose binding no longer matches is INERT — every read
+ * below refuses it by name. There is no automatic deletion, migration, GC, doctor framework or
+ * recovery verb for it.
+ *
+ * FAILURE STATES OF A BIRTH (all non-green; none is "binding not committed" by fiat):
+ *   (a) arm lock busy, or any failure before the minted upsert: the store keeps whatever pair it
+ *       had — possibly an OLDER matching pair;
+ *   (b) the minted upsert landed but the carrier write failed: record ≠ carrier, a pair mismatch
+ *       every read refuses;
+ *   (c) the pair committed but a later step of the birth failed: a matching pair, and still a failed
+ *       birth. The two files are never one atomic commit.
+ * Calling a cleanup is not a cleanup's success: an arm-lock release that does not answer
+ * `released` is reported, never assumed.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { acquireLock, releaseLock } from "./entwurf-v2-lock.js";
+import { defaultMetaRecordArmLocksDir, findCertifiedIdentityByNativeSessionId, isPlausibleOwnerPid, mintAttachIncarnation, NOT_REGULAR_ENTRY_CODE, processStartKey, readAddressableMetaIdentity, readStoreRecordFile, requireAttachIncarnation, requireGardenId, requireNonEmptyString, UpsertActionMismatchError, upsertMetaSession, } from "./meta-session.js";
+export const PI_DURABLE_LOCATION_DIRNAME = "meta-pi-durable-locations";
+export const PI_DURABLE_LOCATION_SUFFIX = ".location.json";
+export const PI_DURABLE_LOCATION_SCHEMA_VERSION = 1;
+const PI_DURABLE_BACKEND = "pi-durable";
+const LOCATION_KEYS = [
+    "schemaVersion",
+    "gardenId",
+    "backend",
+    "nativeSessionId",
+    "cwd",
+    "nativeDirectory",
+    "ownerPid",
+    "ownerStartKey",
+    "attachIncarnation",
+    "writtenAt",
+];
+/** A birth that could not commit its location binding. Always non-green; see FAILURE STATES. */
+export class PiDurableLocationError extends Error {
+    reason;
+    constructor(reason, detail, options) {
+        super(`pi-durable location (${reason}): ${detail}`, options);
+        this.name = "PiDurableLocationError";
+        this.reason = reason;
+    }
+}
+/** `<dirname(receiversDir)>/meta-pi-durable-locations`, from the receivers root the caller actually uses. */
+export function piDurableLocationDir(receiversDir) {
+    if (!path.isAbsolute(receiversDir)) {
+        throw new Error(`pi-durable location: the receivers root must be absolute (got ${JSON.stringify(receiversDir)})`);
+    }
+    return path.join(path.dirname(receiversDir), PI_DURABLE_LOCATION_DIRNAME);
+}
+export function piDurableLocationPath(gardenId, receiversDir) {
+    return path.join(piDurableLocationDir(receiversDir), `${requireGardenId(gardenId)}${PI_DURABLE_LOCATION_SUFFIX}`);
+}
+function requireAbsolute(value, field) {
+    const text = requireNonEmptyString(value, field);
+    if (!path.isAbsolute(text))
+        throw new Error(`location field "${field}" must be an absolute path`);
+    return text;
+}
+/** Strict parse: exact keyset, live schema version, body garden id equal to the file's. Throws on any drift. */
+export function parsePiDurableLocation(json, expectedGardenId) {
+    const raw = JSON.parse(json);
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("location is not a JSON object");
+    const obj = raw;
+    const stray = Object.keys(obj).filter((key) => !LOCATION_KEYS.includes(key));
+    if (stray.length > 0)
+        throw new Error(`location carries unexpected key(s) ${stray.join(", ")}`);
+    const missing = LOCATION_KEYS.filter((key) => !(key in obj));
+    if (missing.length > 0)
+        throw new Error(`location lacks key(s) ${missing.join(", ")}`);
+    if (obj.schemaVersion !== PI_DURABLE_LOCATION_SCHEMA_VERSION) {
+        throw new Error(`location schemaVersion is ${JSON.stringify(obj.schemaVersion)}, not ${PI_DURABLE_LOCATION_SCHEMA_VERSION}`);
+    }
+    if (obj.backend !== PI_DURABLE_BACKEND)
+        throw new Error(`location backend is ${JSON.stringify(obj.backend)}`);
+    if (!isPlausibleOwnerPid(obj.ownerPid))
+        throw new Error(`location ownerPid ${JSON.stringify(obj.ownerPid)} is not a plausible owner`);
+    const attachIncarnation = requireAttachIncarnation(obj.attachIncarnation);
+    if (attachIncarnation === null)
+        throw new Error("location attachIncarnation is null: a location without a binding is not evidence");
+    const location = {
+        schemaVersion: PI_DURABLE_LOCATION_SCHEMA_VERSION,
+        gardenId: requireGardenId(obj.gardenId),
+        backend: PI_DURABLE_BACKEND,
+        nativeSessionId: requireNonEmptyString(obj.nativeSessionId, "nativeSessionId"),
+        cwd: requireAbsolute(obj.cwd, "cwd"),
+        nativeDirectory: requireAbsolute(obj.nativeDirectory, "nativeDirectory"),
+        ownerPid: obj.ownerPid,
+        ownerStartKey: requireNonEmptyString(obj.ownerStartKey, "ownerStartKey"),
+        attachIncarnation,
+        writtenAt: requireNonEmptyString(obj.writtenAt, "writtenAt"),
+    };
+    if (location.gardenId !== expectedGardenId) {
+        throw new AddressMismatch(`location body names ${location.gardenId}, its file names ${expectedGardenId}`);
+    }
+    return location;
+}
+class AddressMismatch extends Error {
+}
+/**
+ * Atomic private write: an exclusive tmp beside the final name, then rename. A failed write leaves no tmp of its
+ * own; an entry that already held the tmp name (the exclusive create failed) is not this call's and is left as is.
+ */
+function writePiDurableLocation(location, receiversDir) {
+    const dir = piDurableLocationDir(receiversDir);
+    const file = piDurableLocationPath(location.gardenId, receiversDir);
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    // Ownership of the tmp is its creation by THIS call: a `wx` that failed (EEXIST included) made nothing here.
+    let created = false;
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const fd = fs.openSync(tmp, "wx", 0o600);
+        created = true;
+        try {
+            fs.writeFileSync(fd, `${JSON.stringify(location, null, "\t")}\n`);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, file);
+    }
+    catch (error) {
+        let leftover = "";
+        try {
+            if (created)
+                fs.rmSync(tmp, { force: true });
+        }
+        catch (cleanup) {
+            leftover = `; its tmp ${tmp} could not be removed (${cleanup instanceof Error ? cleanup.message : String(cleanup)})`;
+        }
+        throw new PiDurableLocationError("carrier-write-failed", `could not write ${file} (${error instanceof Error ? error.message : String(error)})${leftover}`, { cause: error });
+    }
+    return file;
+}
+/**
+ * The pi-durable birth's record write, in the order the Claude Code hook already uses for its own
+ * binding (`meta-bridge-hook.ts` commitRecord): a read-only certified lookup; a create-only publish
+ * when absent (a create replaces nothing, so it takes no lock); the record-arm lock for the garden id;
+ * the attach upsert minting `attachIncarnation`; the location carrier copying that same value; the
+ * release. Everything that can be refused before a write — the receivers root, the owner pid, the cwd,
+ * the native directory, the owner start key — is checked first. See FAILURE STATES for what each failure leaves behind.
+ */
+export function commitPiDurableBirth(opts) {
+    // A relative receivers root would put the arm lock and the carrier wherever the process happens to be.
+    piDurableLocationDir(opts.receiversDir);
+    // The writer refuses, before the first record write, what the carrier's parser would refuse: no
+    // birth may commit a record whose location evidence could never be read back.
+    if (!isPlausibleOwnerPid(opts.ownerPid)) {
+        throw new PiDurableLocationError("owner-pid-implausible", `owner pid ${JSON.stringify(opts.ownerPid)} is not a plausible owner; nothing was written`);
+    }
+    if (typeof opts.cwd !== "string" || !path.isAbsolute(opts.cwd)) {
+        throw new PiDurableLocationError("cwd-not-absolute", `the durable session cwd ${JSON.stringify(opts.cwd)} is not absolute; nothing was written`);
+    }
+    let nativeDirectory;
+    try {
+        if (!path.isAbsolute(opts.sessionDirectory))
+            throw new Error("not absolute");
+        nativeDirectory = fs.realpathSync(opts.sessionDirectory);
+        if (!fs.statSync(nativeDirectory).isDirectory())
+            throw new Error("not a directory");
+    }
+    catch (error) {
+        throw new PiDurableLocationError("native-directory-invalid", `the durable session directory ${JSON.stringify(opts.sessionDirectory)} is not an existing directory ` +
+            `(${error instanceof Error ? error.message : String(error)}); nothing was written`);
+    }
+    const ownerStartKey = processStartKey(opts.ownerPid);
+    if (ownerStartKey === "") {
+        throw new PiDurableLocationError("owner-start-key-unreadable", `no start key could be read for owner pid ${opts.ownerPid}; nothing was written`);
+    }
+    const input = {
+        backend: PI_DURABLE_BACKEND,
+        nativeSessionId: opts.nativeSessionId,
+        cwd: opts.cwd,
+        model: null,
+        transcriptPath: null,
+    };
+    let action = "attach";
+    let existing = findCertifiedIdentityByNativeSessionId(opts.nativeSessionId, opts.sessionsDir);
+    if (existing === null) {
+        try {
+            existing = upsertMetaSession({ input, expectAction: "create", dir: opts.sessionsDir }).record;
+            action = "create";
+        }
+        catch (error) {
+            if (!(error instanceof UpsertActionMismatchError))
+                throw error;
+            existing = findCertifiedIdentityByNativeSessionId(opts.nativeSessionId, opts.sessionsDir);
+            if (existing === null)
+                throw error;
+        }
+    }
+    const lockDir = defaultMetaRecordArmLocksDir(opts.receiversDir);
+    const acquired = acquireLock(existing.gardenId, { dir: lockDir });
+    if (!acquired.ok) {
+        throw new PiDurableLocationError("record-arm-lock-busy", `${acquired.conflict.detail}; the minted binding was not written, so the store keeps whatever pair it had`);
+    }
+    let result;
+    try {
+        const attachIncarnation = mintAttachIncarnation();
+        const upsert = upsertMetaSession({
+            input: { ...input, attachIncarnation },
+            expectAction: "attach",
+            dir: opts.sessionsDir,
+        });
+        const locationPath = writePiDurableLocation({
+            schemaVersion: PI_DURABLE_LOCATION_SCHEMA_VERSION,
+            gardenId: upsert.record.gardenId,
+            backend: PI_DURABLE_BACKEND,
+            nativeSessionId: upsert.record.nativeSessionId,
+            cwd: upsert.record.cwd,
+            nativeDirectory,
+            ownerPid: opts.ownerPid,
+            ownerStartKey,
+            attachIncarnation,
+            writtenAt: new Date().toISOString(),
+        }, opts.receiversDir);
+        result = { action, record: upsert.record, dir: upsert.dir, path: upsert.path, locationPath };
+    }
+    catch (error) {
+        let released;
+        try {
+            released = releaseLock(acquired.claim);
+        }
+        catch (cleanup) {
+            released = `threw: ${cleanup instanceof Error ? cleanup.message : String(cleanup)}`;
+        }
+        if (released !== "released" && error instanceof Error) {
+            error.message += ` (the record-arm lock release then answered ${released}, not released)`;
+        }
+        throw error;
+    }
+    const released = releaseLock(acquired.claim);
+    if (released !== "released") {
+        throw new PiDurableLocationError("record-arm-lock-release-failed", `the pair for ${result.record.gardenId} was written, but releasing its record-arm lock answered ${released}`);
+    }
+    return result;
+}
+/**
+ * The verification leaf: from a garden id (the address) to location evidence, or a named refusal.
+ * The record is read through the addressable reader; the carrier through the store's no-follow,
+ * regular-file read; nothing in the native directory is opened. A pass means ONLY that the record's
+ * current binding and this carrier agree and the named directory exists as itself — never liveness,
+ * ownership, dormancy or an admission.
+ */
+export function verifyPiDurableLocation(opts) {
+    let record;
+    try {
+        record = readAddressableMetaIdentity(opts.gardenId, opts.sessionsDir);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "record-unaddressable",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (record.backend !== PI_DURABLE_BACKEND) {
+        return { ok: false, reason: "record-not-pi-durable", detail: `${record.gardenId} is a ${record.backend} record` };
+    }
+    if (record.attachIncarnation === null) {
+        return {
+            ok: false,
+            reason: "record-unbound",
+            detail: `${record.gardenId} carries no attachIncarnation: no committed location binding to check`,
+        };
+    }
+    const file = piDurableLocationPath(record.gardenId, opts.receiversDir);
+    let text;
+    try {
+        text = readStoreRecordFile(file);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return { ok: false, reason: "carrier-absent", detail: `${file} does not exist` };
+        if (code === "ELOOP" || code === NOT_REGULAR_ENTRY_CODE) {
+            return {
+                ok: false,
+                reason: "carrier-not-regular",
+                detail: `${file} is not a regular file and is never followed`,
+            };
+        }
+        return { ok: false, reason: "carrier-unreadable", detail: error instanceof Error ? error.message : String(error) };
+    }
+    let location;
+    try {
+        location = parsePiDurableLocation(text, record.gardenId);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        if (error instanceof AddressMismatch)
+            return { ok: false, reason: "carrier-address-mismatch", detail };
+        return { ok: false, reason: "carrier-malformed", detail };
+    }
+    const differs = ["nativeSessionId", "cwd", "attachIncarnation"].filter((field) => location[field] !== record[field]);
+    if (differs.length > 0) {
+        return {
+            ok: false,
+            reason: "binding-mismatch",
+            detail: `the carrier and the record of ${record.gardenId} differ on ${differs.join(", ")}`,
+        };
+    }
+    try {
+        const real = fs.realpathSync(location.nativeDirectory);
+        if (real !== location.nativeDirectory)
+            throw new Error(`it now resolves to ${real}`);
+        if (!fs.statSync(real).isDirectory())
+            throw new Error("it is not a directory");
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "native-directory-invalid",
+            detail: `${location.nativeDirectory}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return { ok: true, record, location };
+}