@junghanacs/entwurf 0.45.0 → 0.51.0

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

@@ -360,9 +360,12 @@ export interface MetaIdentity {
 	 * arm-capable event and writes in the SAME atomic upsert as that attach, then copies into
 	 * the receiver marker it writes under the record-arm lock. A dead marker carrying the
 	 * value the record still carries is evidence that no later arm-capable attach happened;
-	 * one that does not carry it is not. `null` means no binding was ever observed — every
-	 * other backend, a record no arm has touched since this field existed, a create — and
-	 * is never filled by inference. Every writer that does not mint PRESERVES it.
+	 * one that does not carry it is not. The pi-durable birth (#157 B3 C4) mints it the same way
+	 * under the same lock and copies it into its location evidence (`pi-durable-location.ts`)
+	 * instead of a marker; there it binds a location, never a dormancy verdict. `null` means no
+	 * binding was ever observed — every other backend, a pi-durable record no birth has bound,
+	 * a record no arm has touched since this field existed, a create — and is never filled by
+	 * inference. Every writer that does not mint PRESERVES it.
 	 */
 	attachIncarnation: string | null;
 }
@@ -614,10 +617,10 @@ export interface MetaIdentityMintInput {
 	model?: string | null;
 	transcriptPath?: string | null;
 	/**
-	 * The arm binding to commit with this write. ONLY the Claude Code hook passes it, and
-	 * only on an arm-capable event under the record-arm lock; `undefined` (every other
-	 * writer, every UserPromptSubmit) keeps the existing value, and a create without it is
-	 * `null`.
+	 * The arm binding to commit with this write. ONLY the Claude Code hook (on an arm-capable
+	 * event) and the pi-durable birth (#157 B3 C4) pass it, each under the record-arm lock;
+	 * `undefined` (every other writer, every UserPromptSubmit) keeps the existing value, and a
+	 * create without it is `null`.
 	 */
 	attachIncarnation?: string;
 }
@@ -1471,7 +1474,9 @@ export function defaultMetaReceiversDir(): string {
  * sandboxed receivers root sandboxes it too and no new environment carrier exists. It is
  * deliberately NOT the v2 dispatch lock dir — visible resume holds that per-gid lock across
  * its whole launch + observation window, and the relaunched session's own arm must not wait
- * on it. Only the Claude Code hook takes this lock; nothing else reads or writes here.
+ * on it. The Claude Code hook and the pi-durable birth (`pi-durable-location.ts`, #157 B3 C4)
+ * take this lock, each around the upsert that mints `attachIncarnation`; nothing else reads or
+ * writes here.
  */
 export function defaultMetaRecordArmLocksDir(receiversDir: string = defaultMetaReceiversDir()): string {
 	return path.join(path.dirname(receiversDir), "meta-record-arm-locks");

package/pi-extensions/lib/mux-resume-call.ts

@@ -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 ──
  *
@@ -77,6 +81,49 @@ import {
 export const RESUME_CALL_RUNTIME = { pi: "pi", "claude-code": "claude" } as const;
 export type ResumeCallBackend = keyof typeof RESUME_CALL_RUNTIME;
 
+/**
+ * #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 pi-durable adopt launch projection (#157 B3, L3-A1 §1): EXACTLY these five names, each read by
+ * name and emitted in this order — the SDK's own profile input, and the standard children of ONE meta
+ * root. It is a fixed projection of two coordinates the caller derived, not an environment dictionary:
+ * no other name can be expressed through it. The launched child checks the four roots it actually
+ * received against its closed adopt context, and its raw profile against the reservation, before
+ * anything opens, so a value this module mangled would refuse there rather than open something else.
+ */
+export interface ResumeCallPiDurableAdoptEnv {
+	readonly PI_CODING_AGENT_DIR: string;
+	readonly ENTWURF_META_SESSIONS_DIR: string;
+	readonly ENTWURF_META_MAILBOX_DIR: string;
+	readonly ENTWURF_META_SENDERS_DIR: string;
+	readonly ENTWURF_META_RECEIVERS_DIR: string;
+}
+
+/** 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: ResumeCallPiDurableAdoptEnv | undefined): string[] {
+	if (adoptEnv === undefined) return [];
+	const pairs: readonly (readonly [string, string])[] = [
+		["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}`);
+}
+
 /** Why a resume window could not be opened. Every value is a NAMED refusal; this module has no
  * fallback launch and no fallback directory. The cwd members come from the shared classification
  * leaf and their string values are stable contract. */
@@ -97,7 +144,8 @@ export type ResumeCallResult = { ok: true; receipt: ResumeCallReceipt } | { ok:
 
 /**
  * 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.
@@ -107,16 +155,19 @@ export function buildResumeCallArgs(
 	cwd: string,
 	runtimePath: string,
 	runtimeArgs: readonly string[],
+	adoptEnv?: ResumeCallPiDurableAdoptEnv,
 ): string[] {
 	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",
@@ -140,6 +191,28 @@ export function buildResumeCallArgs(
 export function resumeCall(
 	params: { backend: ResumeCallBackend; cwd: string; runtimeArgs: readonly string[] },
 	env: NodeJS.ProcessEnv = process.env,
+): ResumeCallResult {
+	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: { cwd: string; runtimeArgs: readonly string[]; adoptEnv: ResumeCallPiDurableAdoptEnv },
+	env: NodeJS.ProcessEnv = process.env,
+): ResumeCallResult {
+	return openResumeWindow(RESUME_CALL_PI_DURABLE_RUNTIME, params, params.adoptEnv, env);
+}
+
+function openResumeWindow(
+	runtime: string,
+	params: { cwd: string; runtimeArgs: readonly string[] },
+	adoptEnv: ResumeCallPiDurableAdoptEnv | undefined,
+	env: NodeJS.ProcessEnv,
 ): ResumeCallResult {
 	if (env.HERDR_ENV === "1") return { ok: false, reason: "herdr-resume-unsupported" };
 	const badCwd = classifyTmuxCwd(params.cwd);
@@ -147,7 +220,7 @@ export function resumeCall(
 
 	let runtimePath: string;
 	try {
-		runtimePath = resolveRuntimeOnPath(RESUME_CALL_RUNTIME[params.backend], env);
+		runtimePath = resolveRuntimeOnPath(runtime, env);
 	} catch (err) {
 		if (err instanceof LaunchPreconditionError) return { ok: false, reason: err.reason };
 		throw err;
@@ -158,7 +231,7 @@ export function resumeCall(
 	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: ReturnType<typeof parseWindowFields>;

package/pi-extensions/lib/pi-durable-fresh-preflight.ts

@@ -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 ──
  *
@@ -52,7 +55,8 @@ export type PiDurablePreflightRejectReason =
 	| "pi-durable-birth-unit-missing"
 	| "pi-durable-mcp-hand-missing"
 	| "pi-durable-receive-unit-missing"
-	| "pi-durable-visible-identity-missing";
+	| "pi-durable-visible-identity-missing"
+	| "pi-durable-owner-fence-missing";
 
 /** `<provider>/<model id>` at the FIRST `/`, or `null` when either side is empty. */
 export function splitPiDurableModel(model: string): { provider: string; model: string } | null {
@@ -89,6 +93,7 @@ export function piDurableFreshPreflight(params: {
 	if (!existsSync(layout.bridgeEntry)) return "pi-durable-mcp-hand-missing";
 	if (!ownerJoinAdmitsDurableHost(layout.deliverability)) 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;
 }
 
@@ -110,4 +115,6 @@ export const PI_DURABLE_PREFLIGHT_HINT: Record<
 		"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/pi-extensions/lib/pi-durable-location.ts

@@ -0,0 +1,446 @@
+/**
+ * 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.ts";
+import {
+	defaultMetaRecordArmLocksDir,
+	findCertifiedIdentityByNativeSessionId,
+	isPlausibleOwnerPid,
+	type MetaIdentity,
+	mintAttachIncarnation,
+	NOT_REGULAR_ENTRY_CODE,
+	processStartKey,
+	readAddressableMetaIdentity,
+	readStoreRecordFile,
+	requireAttachIncarnation,
+	requireGardenId,
+	requireNonEmptyString,
+	type UpsertAction,
+	UpsertActionMismatchError,
+	upsertMetaSession,
+} from "./meta-session.ts";
+
+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: readonly string[] = [
+	"schemaVersion",
+	"gardenId",
+	"backend",
+	"nativeSessionId",
+	"cwd",
+	"nativeDirectory",
+	"ownerPid",
+	"ownerStartKey",
+	"attachIncarnation",
+	"writtenAt",
+];
+
+/** The location evidence one pi-durable birth commits. Evidence only — see the file header. */
+export interface PiDurableLocation {
+	schemaVersion: typeof PI_DURABLE_LOCATION_SCHEMA_VERSION;
+	gardenId: string;
+	backend: typeof PI_DURABLE_BACKEND;
+	nativeSessionId: string;
+	/** The realpath cwd the record carries (`sessions.ts:42` realpaths it before the attach sees it). */
+	cwd: string;
+	/** `realpath(session.directory)` at the birth: the physical native session directory. */
+	nativeDirectory: string;
+	ownerPid: number;
+	ownerStartKey: string;
+	/** The record's `attachIncarnation` minted in the same arm-locked commit. Never null here. */
+	attachIncarnation: string;
+	writtenAt: string;
+}
+
+/** A birth that could not commit its location binding. Always non-green; see FAILURE STATES. */
+export class PiDurableLocationError extends Error {
+	readonly reason:
+		| "owner-pid-implausible"
+		| "cwd-not-absolute"
+		| "native-directory-invalid"
+		| "owner-start-key-unreadable"
+		| "record-arm-lock-busy"
+		| "record-arm-lock-release-failed"
+		| "carrier-write-failed";
+	constructor(reason: PiDurableLocationError["reason"], detail: string, options?: { cause?: unknown }) {
+		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: string): string {
+	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: string, receiversDir: string): string {
+	return path.join(piDurableLocationDir(receiversDir), `${requireGardenId(gardenId)}${PI_DURABLE_LOCATION_SUFFIX}`);
+}
+
+function requireAbsolute(value: unknown, field: string): string {
+	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: string, expectedGardenId: string): PiDurableLocation {
+	const raw: unknown = JSON.parse(json);
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new Error("location is not a JSON object");
+	const obj = raw as Record<string, unknown>;
+	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: PiDurableLocation = {
+		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: PiDurableLocation, receiversDir: string): string {
+	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;
+}
+
+export interface CommitPiDurableBirthOptions {
+	nativeSessionId: string;
+	/** The realpath cwd the durable session reports (absolute). */
+	cwd: string;
+	/** `session.directory` as the durable runtime reports it; realpath'd and verified here. */
+	sessionDirectory: string;
+	ownerPid: number;
+	sessionsDir: string;
+	/** The receivers root this birth uses (absolute); the arm-lock and location dirs derive from it. */
+	receiversDir: string;
+}
+
+export interface CommitPiDurableBirthResult {
+	/** `create` when THIS birth published the record, else `attach`. */
+	action: UpsertAction;
+	record: MetaIdentity;
+	dir: string;
+	/** Absolute path of the written record. */
+	path: string;
+	locationPath: string;
+}
+
+/**
+ * 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: CommitPiDurableBirthOptions): CommitPiDurableBirthResult {
+	// 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: string;
+	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,
+	} as const;
+
+	let action: UpsertAction = "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: CommitPiDurableBirthResult;
+	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: string;
+		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;
+}
+
+export type PiDurableLocationRefusal =
+	| "record-unaddressable"
+	| "record-not-pi-durable"
+	| "record-unbound"
+	| "carrier-absent"
+	| "carrier-not-regular"
+	| "carrier-unreadable"
+	| "carrier-malformed"
+	| "carrier-address-mismatch"
+	| "binding-mismatch"
+	| "native-directory-invalid";
+
+export type PiDurableLocationVerdict =
+	| { ok: true; record: MetaIdentity; location: PiDurableLocation }
+	| { ok: false; reason: PiDurableLocationRefusal; detail: string };
+
+/**
+ * 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: {
+	gardenId: string;
+	sessionsDir: string;
+	receiversDir: string;
+}): PiDurableLocationVerdict {
+	let record: MetaIdentity;
+	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: string;
+	try {
+		text = readStoreRecordFile(file);
+	} catch (error) {
+		const code = (error as { code?: unknown }).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: PiDurableLocation;
+	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"] as const).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 };
+}