@junghanacs/entwurf 0.12.0 → 0.12.2

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

@@ -0,0 +1,254 @@
+/**
+ * entwurf-v2-decider — the PURE dispatch decider for the unified `entwurf_v2` verb
+ * (0.11 Stage 0 step 5b). It turns a caller's (target, intent, …) request plus
+ * already-resolvable facts into a single `DispatchDecision`: either a reject
+ * receipt, or an execute receipt + an `ExecutionPlan` + (for in-domain backends) a
+ * held `LockClaim`. It performs NO transport: no send, no enqueue, no spawn, no
+ * release-watcher. Step 5c executes the chosen plan; step 5d registers the MCP
+ * surface. The decider only DECIDES.
+ *
+ * Why a separate pure module (step 4 discipline = gate-first → pure-before-IO →
+ * wire): every IO surface the decision needs — the target lookup, the per-gid lock,
+ * the lstat/connect socket inspection, the trust preflight, the mailbox-deliverability
+ * seam — is INJECTED via `DispatchDeciderDeps`, so the gate drives every branch with
+ * fakes and the live wrappers wire the real fns. The plan is shaped so 5c's
+ * transport hand consumes it WITHOUT re-deriving any path/arg (socketPath,
+ * mailboxDir, sessionsDir, launchArgs are all planted here once — 4c "재유도 금지"):
+ * the hand is a plan-keyed dispatcher, never a second brain. The two deliberate
+ * exceptions (GPT힣 1차 검수): the spawned child's runtime pid is NOT in the plan
+ * (it is born during 5c execution → it is the watcher's release-context, not a plan
+ * input), and the launch identity (provider/model) is read by the 5c launcher from
+ * the saved session JSONL (its existing authority) — putting that read in the
+ * decider would make it impure. So the plan carries no provider/model.
+ *
+ * The frozen 7-step order (NEXT.md "통합 decider 순서"):
+ *   1. requireGardenId   — runtime guard BEFORE any path is built (F2-P1; closes the
+ *      MCP-schema bypass for pi-native/internal callers).
+ *   2. resolveTarget     — no citizen → bad-target; quarantined (non-pi gid sharing
+ *      a socket/symlink) → target-address-conflict. PROBE-FREE.
+ *   3. backend           → isLivenessSupported.
+ *   4. acquireLock       — IN-DOMAIN ONLY (？7), BEFORE lstat/connect, so the probe
+ *      happens under the lock (the TOCTOU 5a's lock closes).
+ *   5. in-domain         — inspectTargetControlSocket (lstat-then-connect, ？2) →
+ *      resolveDispatch → on a resume verdict, preflight the target cwd (1B: deny →
+ *      nonce-owned release → untrusted-fail-fast) → plan.
+ *   6. unsupported       — NO lock; deps.mailboxDeliverabilityFor (REQUIRED seam: wake-mode
+ *      capability AND a live active-receiver, fail-closed) → resolveDispatch → meta-mailbox
+ *      plan or reject. SE-2 2d-3: a terminated/drifted self-fetch citizen is refused, never
+ *      enqueued as mailbox garbage.
+ *   7. send-fail fallback is 5c's job (the decider decides ONCE; the held lock nonce
+ *      is what lets 5c re-resolve at most once under the same claim).
+ *
+ * Every reject is minted through `makeRejectReceipt` (？6 chokepoint) — the decider
+ * never hand-assembles a `{ok:false, …}` literal, so the pre-probe-null rule cannot
+ * be bypassed.
+ */
+import { isNonPiGardenIdSocketConflict } from "./entwurf-facts.js";
+import { isLivenessSupported, makeRejectReceipt, resolveDispatch, } from "./entwurf-v2-contract.js";
+import { defaultMetaMailboxDir, defaultMetaSessionsDir, metaCapabilityFor, } from "./meta-session.js";
+import { isValidSessionId } from "./session-id.js";
+import { controlSocketPath, mapInspectionToLiveness } from "./socket-discovery.js";
+// Re-export the shared conflict predicate so producers of a TargetResolution have a
+// single import site for it (it is the SAME fn the fact-provider listing uses).
+export { isNonPiGardenIdSocketConflict };
+// ── observe timeout (？3) ───────────────────────────────────────────────────
+// The bounded wait 5c's release-watcher gives a spawned child to surface its
+// control socket / exit. Planted into the resume plan so the hand does not invent
+// a timeout. A standalone constant + env override (NOT a multiple of the probe
+// timeout — a different concern); 30s initial, tunable to 45s after live data.
+export const ENTWURF_V2_OBSERVE_TIMEOUT_MS = (() => {
+    const raw = process.env.ENTWURF_V2_OBSERVE_TIMEOUT_MS;
+    const n = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
+    return Number.isFinite(n) && n > 0 ? n : 30_000;
+})();
+export const ENTWURF_V2_MODE_DEFAULT = "follow_up";
+/**
+ * F2-P1 defense in depth: never build a lock/socket path from an unvalidated gid.
+ * The MCP TypeBox pattern guards that one surface; a pi-native / internal caller
+ * bypasses the schema, so the decider re-validates as its very first step.
+ */
+function requireGardenId(target) {
+    if (!isValidSessionId(target)) {
+        throw new Error(`entwurf_v2 decider: refusing to dispatch to an invalid garden id (${JSON.stringify(target)}).`);
+    }
+    return target;
+}
+/**
+ * Mailbox WAKE-MODE capability (？0 frozen): ONLY a self-fetch backend (claude-code) has a
+ * drainable meta-bridge mailbox. direct-inject backends (codex/agy/pi) are fail-closed —
+ * that is intended, not a gap (the 0.10.0 mailbox + doorbell is a self-fetch drain;
+ * direct-inject drain is an unproven capability). Do NOT widen by deliveryLevel — only by
+ * a real per-backend predicate.
+ *
+ * This is the CAPABILITY HALF of deliverability only. Full mailbox deliverability ALSO
+ * requires a live active-receiver (a presence marker matching the identity) — that
+ * conjunction lives in the required `mailboxDeliverabilityFor` seam (SE-2 slice 2d-3). The
+ * decider NEVER calls this helper directly: deliverability flows exclusively through the
+ * seam so the active-receiver axis can never be skipped. Kept as a named, gate-pinned
+ * helper for the production seam to compose and for capability-only call sites.
+ */
+export function resolveMailboxWakeModeCapability(identity, capabilityFor = metaCapabilityFor) {
+    return capabilityFor(identity.backend).wakeMode === "self-fetch";
+}
+/**
+ * The pure dispatch decider. See the module header for the 7-step contract. Async
+ * only because the socket inspection/probe are async; it touches the filesystem
+ * ONLY through injected deps.
+ */
+export async function decideDispatch(input, deps) {
+    const mailboxDir = deps.mailboxDir ?? defaultMetaMailboxDir();
+    const sessionsDir = deps.sessionsDir ?? defaultMetaSessionsDir();
+    const observeTimeoutMs = deps.observeTimeoutMs ?? ENTWURF_V2_OBSERVE_TIMEOUT_MS;
+    const mode = input.mode ?? ENTWURF_V2_MODE_DEFAULT;
+    const wantsReply = input.wantsReply ?? false;
+    const ctx = { mode, wantsReply, observeTimeoutMs };
+    const reject = (receipt, diagnostic) => diagnostic ? { kind: "reject", receipt, diagnostic } : { kind: "reject", receipt };
+    // 1. requireGardenId — BEFORE any path is built.
+    const gardenId = requireGardenId(input.target);
+    // 2. resolveTarget — probe-free. no citizen → bad-target; quarantined → conflict.
+    const resolution = await deps.resolveTarget(gardenId);
+    // 2b. A1 narrow (0.11.0): a record-LESS live pi control socket — a socket-only pi
+    // endpoint (no citizen identity, but an addressable control socket). It is a REAL,
+    // addressable citizen, so it runs the SAME in-domain probe table as a record-backed pi
+    // (lock → inspect → table verdict) under `allowResume:false`. We DELIBERATELY do NOT
+    // short-circuit non-fire-and-forget here: rejecting owned-outcome pre-probe with
+    // `bad-target` would be a category lie (a LIVE, addressable peer classified as
+    // absent/typo). The frozen table is the honest authority instead —
+    //   owned-outcome × live    → `owned-live-no-autosend` (use fire-and-forget for a live peer)
+    //   owned-outcome × dormant → resume verdict, but `allowResume:false` refuses it with
+    //                             `socket-only-no-resume-authority` (no trusted cwd to spawn-bg)
+    //   fire-and-forget × live  → control-socket send (unchanged)
+    // `allowResume:false` is what keeps spawn-bg from EVER opening into a record-less
+    // endpoint, regardless of intent — so routing every intent through is safe.
+    if (resolution.identity === null && resolution.socketOnlyPi === true) {
+        return decideInDomain(gardenId, input, deps, ctx, { allowResume: false });
+    }
+    // 2c. no citizen → bad-target; quarantined → conflict.
+    if (resolution.identity === null) {
+        return reject(makeRejectReceipt("bad-target", null));
+    }
+    if (resolution.preProbeAddressConflict) {
+        return reject(makeRejectReceipt("target-address-conflict", null));
+    }
+    const identity = resolution.identity;
+    // 3. backend.
+    if (!isLivenessSupported(identity.backend)) {
+        // 6. unsupported path — NO lock (？7). Deliverability comes from the REQUIRED seam
+        // (wake-mode capability AND a live active-receiver marker matching this identity),
+        // NOT a wake-mode-only helper — so a terminated self-fetch citizen's mailbox is
+        // fail-closed (SE-2 2d-3). resolveDispatch then routes intent × deliverable.
+        const deliverability = await deps.mailboxDeliverabilityFor(identity);
+        const receipt = resolveDispatch(input.intent, "unsupported", deliverability.deliverable);
+        if (!receipt.ok)
+            return reject(receipt);
+        // the only allow cell here is fire-and-forget → meta-mailbox send.
+        const plan = {
+            transport: "meta-mailbox",
+            action: "send",
+            targetGardenId: gardenId,
+            mailboxDir,
+            sessionsDir,
+            wantsReply,
+            message: input.message,
+        };
+        return { kind: "execute", receipt, plan, lock: null };
+    }
+    // 4-5. in-domain (record-backed pi): lock → inspect → route (resume allowed, cwd from record).
+    return decideInDomain(gardenId, input, deps, ctx, { allowResume: true, cwd: identity.cwd });
+}
+async function decideInDomain(gardenId, input, deps, ctx, resume) {
+    const { acquireLock, releaseLock, inspectSocket, probeSocket } = deps;
+    // 4. acquire the per-gid lock BEFORE lstat/connect.
+    const acq = acquireLock(gardenId);
+    if (!acq.ok) {
+        // B3: carry the lock's holder evidence (pid/host/createdAt + lockPath) as a
+        // diagnostic so a permanently-held gid is observable/clearable. The receipt
+        // stays pre-probe-null; the conflict rides alongside it.
+        return {
+            kind: "reject",
+            receipt: makeRejectReceipt("target-locked", null),
+            diagnostic: { kind: "target-locked", conflict: acq.conflict },
+        };
+    }
+    const lock = acq.claim;
+    const rejectAfterRelease = (receipt) => {
+        releaseLock(lock);
+        return { kind: "reject", receipt };
+    };
+    let retainLock = false;
+    try {
+        // 5. under the lock: inspect the socket (lstat-then-connect), then route.
+        const inspection = await inspectSocket(gardenId);
+        const mapped = await mapInspectionToLiveness(inspection, probeSocket);
+        if ("addressConflict" in mapped) {
+            return rejectAfterRelease(makeRejectReceipt("target-address-conflict", null));
+        }
+        const { liveness, socketPath } = mapped;
+        const receipt = resolveDispatch(input.intent, liveness, false);
+        if (!receipt.ok) {
+            // resolver reject (owned-live-no-autosend / indeterminate-no-spawn / …) — the
+            // lock was for an in-domain probe that yielded no execute, so release it.
+            return rejectAfterRelease(receipt);
+        }
+        if (receipt.action === "resume") {
+            if (!resume.allowResume) {
+                // A1 narrow guard: the resume verdict is owned-outcome × dormant ONLY. A
+                // socket-only pi endpoint now routes ALL intents through here under
+                // `allowResume:false` (2b no longer pre-rejects non-fire-and-forget), so this
+                // guard IS reachable — it is the honest home of "owned-outcome to a DORMANT
+                // record-less socket". REFUSE: a record-less endpoint has no trusted cwd/resume
+                // authority, so spawn-bg must never open into it. This is a POST-probe guard
+                // (we measured `liveness` above), so it carries the honest measured liveness —
+                // NOT the pre-probe `bad-target` lie that would mislabel the citizen absent.
+                return rejectAfterRelease(makeRejectReceipt("socket-only-no-resume-authority", liveness));
+            }
+            // 1B: preflight runs ONLY here (the sole branch that launches a child into a
+            // target cwd). deny → nonce-owned release → untrusted-fail-fast, with the
+            // honest measured liveness (dormant = the `dead` we just probed).
+            const outcome = await deps.preflightForCwd(resume.cwd);
+            if (outcome.kind === "deny") {
+                return rejectAfterRelease(makeRejectReceipt("untrusted-fail-fast", liveness));
+            }
+            const plan = {
+                transport: "spawn-bg",
+                action: "resume",
+                targetGardenId: gardenId,
+                sessionId: gardenId, // D3: gid is the pi resume authority, not nativeSessionId.
+                cwd: resume.cwd,
+                prompt: input.message,
+                launchArgs: outcome.launchArgs,
+                expectedSocketPath: socketPath,
+                observeTimeoutMs: ctx.observeTimeoutMs,
+                releaseWhen: "socket-alive-or-child-exited",
+            };
+            retainLock = true;
+            return { kind: "execute", receipt, plan, lock };
+        }
+        // receipt.action === "send" → control-socket send (lock kept for 5c re-resolve).
+        const plan = {
+            transport: "control-socket",
+            action: "send",
+            targetGardenId: gardenId,
+            socketPath,
+            mode: ctx.mode,
+            wantsReply: ctx.wantsReply,
+            message: input.message,
+        };
+        retainLock = true;
+        return { kind: "execute", receipt, plan, lock };
+    }
+    catch (err) {
+        if (!retainLock) {
+            try {
+                releaseLock(lock);
+            }
+            catch {
+                // best-effort: a release failure must NOT mask the original throw.
+            }
+        }
+        throw err;
+    }
+}
+/** The canonical control-socket path for a target — re-exported so a production
+ * resolveTarget/wrapper plants the SAME path the decider/plan use (no drift). */
+export { controlSocketPath };

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

@@ -0,0 +1,365 @@
+/**
+ * entwurf-v2-lock — the per-gid dispatch lock primitive (0.11 Stage 0 step 5a,
+ * 버킷 B F2). LOAD-BEARING: the guard against a double-spawn of the same dormant
+ * target by two V2 dispatchers that share the substrate through different entry
+ * points. SCOPE (honest): this protects v2/v2 only. The legacy `entwurf_resume`
+ * is unchanged (동결결정 10 scope A) and does NOT take this lock, so v2/legacy
+ * concurrent resume is a KNOWN residual gap (rare — single-orchestrator practice),
+ * closed only at full cut-over. Do not read this header as "v2/legacy is guarded".
+ *
+ * ENVIRONMENT ASSUMPTION (stale reclaim): `hostname` equality is used as the
+ * proxy for "same machine", so a holder pid is reclaim-probed with kill(0) only
+ * when its hostname matches ours. This holds when `~/.pi` is NOT shared across
+ * hosts. If two machines with the same hostname shared `~/.pi` over NFS, a remote
+ * pid could be mis-judged ESRCH and a live remote lock wrongly reclaimed. GLG's
+ * environment (laptop/nuc/oracle = distinct hostnames, non-shared homes) does not
+ * hit this; documented so a future shared-home setup reopens the reclaim axis.
+ *
+ * Why a lockfile and not pi's own guard (검증원장 F2, source-verified): pi
+ * `SessionManager._persist` only takes an `openSync(file,"wx")` on the FIRST
+ * flush of a NEW session (session-manager.js:652/:1146 = a concurrent-CREATE
+ * EEXIST guard). A v2 dispatch always RESUMES an existing citizen, and the
+ * resume path (`setSessionFile` → flushed=true → plain `appendFileSync`, :664)
+ * takes no lock — so pi does NOT self-guard concurrent resume. The per-gid
+ * lockfile here is the only thing standing between two dispatchers and a
+ * duplicated session.
+ *
+ * Invariants (source-verified, frozen — do NOT relax without reopening the
+ * ledger):
+ *  - acquire = `openSync(lockPath, "wx")` — an atomic, OS-level create-exclusive.
+ *    The same primitive pi itself uses; no new direct dependency (proper-lockfile
+ *    avoided — this is a short dispatch claim, not durable state).
+ *  - acquire runs BEFORE any liveness probe (the decider's lock step precedes
+ *    lstat/connect) — the probe must happen UNDER the lock or the TOCTOU it
+ *    closes reopens.
+ *  - release = unlink ONLY when the on-disk nonce is still ours. A reclaimed +
+ *    re-acquired lock carries a different nonce, so a late release can never
+ *    delete a successor's claim.
+ *  - stale reclaim = SAME hostname AND `kill(pid,0) === ESRCH` ONLY. A TTL-only
+ *    steal is forbidden (it would re-admit the double-spawn this primitive
+ *    exists to prevent). EPERM (another user's LIVE pid) is fail-closed: NOT
+ *    reclaimed (F2-P2 — the ESRCH-only branch is easy to drop, so the gate pins
+ *    EPERM/unknown = not-reclaimed explicitly). A different hostname is never
+ *    reclaimed (we cannot reason about a remote pid).
+ *  - PID reuse → a permanently-held lock is the accepted cost of forbidding the
+ *    TTL steal (workshop scale). It is made OBSERVABLE: a `target-locked`
+ *    conflict carries the holder JSON (pid/host/createdAt/lockPath) so a human
+ *    can clear it. An empty/corrupt lockfile (a crash between open-wx and write)
+ *    surfaces through the SAME conflict path — never auto-deleted (it could be
+ *    another acquirer mid-write).
+ *
+ * PURE of dispatch: this module knows nothing about transports, intents, or
+ * liveness routing. It only claims/reclaims/releases a file and reports a
+ * `target-locked` conflict. The decider (5b) decides WHETHER to lock (only for
+ * an in-domain backend — ？7) and the watcher (5c) decides WHEN to release
+ * (after an observable liveness transition — A2). Deps (clock / nonce / pid /
+ * hostname / kill) are injectable so the gate drives content deterministically
+ * over a real temp dir (the `openSync wx` atomicity is the thing under test, so
+ * the dir is real, not faked).
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isValidSessionId } from "./session-id.js";
+/** Canonical lock directory — a SEPARATE dir from the control sockets so the
+ * socket scan (`*.sock`) never sees a `<gid>.lock` and so a lock is never
+ * mistaken for a liveness signal. */
+export const ENTWURF_V2_LOCK_DIR = path.join(os.homedir(), ".pi", "entwurf-v2-locks");
+export const LOCK_SUFFIX = ".lock";
+export const LOCK_OWNER = "entwurf_v2";
+/** The reject reason a lock conflict maps to. Kept as a literal here (the lock
+ * primitive stays decoupled from the full contract); `check-entwurf-v2-lock`
+ * cross-checks it against the contract's ENTWURF_V2_REJECT_REASONS so the two
+ * cannot drift. */
+export const LOCK_CONFLICT_REASON = "target-locked";
+/**
+ * Classify a holder pid for stale reclaim. ONLY `dead` (ESRCH) is reclaimable.
+ * `denied` (EPERM = another user's live pid) and any unknown error fail-closed
+ * to a non-reclaimable state — we never reclaim a lock we cannot prove is dead.
+ */
+export function classifyProcessLiveness(pid, killFn = process.kill) {
+    try {
+        killFn(pid, 0);
+        return "alive";
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return "dead";
+        if (code === "EPERM")
+            return "denied";
+        // Unknown error: fail-closed — treat as not-dead so we never reclaim it.
+        return "alive";
+    }
+}
+export function lockPathFor(gardenId, dir = ENTWURF_V2_LOCK_DIR) {
+    // F2-P1 (defense in depth): never build a filesystem path from an unvalidated
+    // gid. The decider validates first (its step 1), but the lock layer refuses to
+    // be a path-traversal sink on its own — a bad gid throws, it does not write.
+    if (!isValidSessionId(gardenId)) {
+        throw new Error(`entwurf-v2-lock: refusing to build a lock path from an invalid garden id (${JSON.stringify(gardenId)}).`);
+    }
+    return path.join(dir, `${gardenId}${LOCK_SUFFIX}`);
+}
+/**
+ * Parse a lockfile's bytes into a claim, or null when empty/corrupt/wrong-gid.
+ * When `expectedGardenId` is given, a well-formed claim whose `gardenId` does NOT
+ * match is treated as null (→ conflict, never reclaimed): the path authority IS
+ * the garden id (동결결정3), so a `<A>.lock` carrying `gardenId:B` is a corrupt
+ * address, not a holder we may probe-and-reclaim by A's heuristic.
+ */
+function parseLockClaim(raw, lockPath, expectedGardenId) {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== "object" || obj === null)
+        return null;
+    const o = obj;
+    if (typeof o.gardenId !== "string" ||
+        typeof o.pid !== "number" ||
+        typeof o.hostname !== "string" ||
+        typeof o.createdAt !== "string" ||
+        typeof o.nonce !== "string" ||
+        o.owner !== LOCK_OWNER) {
+        return null;
+    }
+    if (expectedGardenId !== undefined && o.gardenId !== expectedGardenId)
+        return null;
+    return {
+        gardenId: o.gardenId,
+        pid: o.pid,
+        hostname: o.hostname,
+        createdAt: o.createdAt,
+        nonce: o.nonce,
+        owner: LOCK_OWNER,
+        lockPath,
+    };
+}
+/** Best-effort lockfile mtime (ISO) for human cleanup evidence — the ONLY age
+ * signal when the body is empty/corrupt (createdAt is then unreadable). */
+function lockMtimeIso(lockPath) {
+    try {
+        return statSync(lockPath).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+function describeHolder(holder, lockPath) {
+    const mtime = lockMtimeIso(lockPath);
+    const age = mtime ? ` (file mtime ${mtime})` : "";
+    if (holder === null) {
+        return `lockfile at ${lockPath} is empty, corrupt, or holds a different garden id${age}; clear it by hand after confirming no dispatcher is mid-spawn`;
+    }
+    return `held by pid ${holder.pid} on host ${holder.hostname} since ${holder.createdAt}${age} (${lockPath}); clear it by hand if that process is gone`;
+}
+/**
+ * Acquire the per-gid dispatch lock. Returns the claim on success, or a
+ * `target-locked` conflict (with the holder evidence) on contention. Stale reclaim
+ * (same host + ESRCH) runs UNDER a `<gid>.lock.reclaim` wx mutex so two
+ * dispatchers can never both reclaim the same dead lock (the F2 double-spawn race
+ * GPT+Fable found). It never loops — a race lost on the re-acquire is an honest
+ * conflict, not a spin.
+ */
+export function acquireLock(gardenId, deps = {}) {
+    const dir = deps.dir ?? ENTWURF_V2_LOCK_DIR;
+    const lockPath = lockPathFor(gardenId, dir); // validates gid (F2-P1)
+    const reclaimMarkerPath = `${lockPath}.reclaim`;
+    const pid = deps.pid ?? process.pid;
+    const hostname = deps.hostname ?? os.hostname();
+    const now = deps.now ?? (() => new Date().toISOString());
+    const nonce = deps.nonce ?? (() => randomBytes(8).toString("hex"));
+    const killFn = deps.killFn ?? process.kill;
+    mkdirSync(dir, { recursive: true });
+    const claim = {
+        gardenId,
+        pid,
+        hostname,
+        createdAt: now(),
+        nonce: nonce(),
+        owner: LOCK_OWNER,
+        lockPath,
+    };
+    const conflict = (holder, detail) => ({
+        ok: false,
+        conflict: { reason: LOCK_CONFLICT_REASON, lockPath, holder, detail: detail ?? describeHolder(holder, lockPath) },
+    });
+    const readHolder = () => {
+        try {
+            return parseLockClaim(readFileSync(lockPath, "utf8"), lockPath, gardenId);
+        }
+        catch {
+            return null;
+        }
+    };
+    // Create the lock and write the claim. write AND close are ONE unit: ENOSPC /
+    // NFS can throw on close (the flush), not just write, so a failure in EITHER
+    // must best-effort unlink our OWN fresh file before rethrowing — otherwise the
+    // transient error leaves a stray lockfile that permanently corrupt-conflicts
+    // the gid (Fable 2 self-harm). The unlink is safe: we hold the file exclusively.
+    const tryCreate = () => {
+        let fd;
+        try {
+            fd = openSync(lockPath, "wx");
+        }
+        catch (err) {
+            return { ok: false, code: err.code };
+        }
+        let closed = false;
+        try {
+            writeSync(fd, `${JSON.stringify(claim)}\n`);
+            closeSync(fd);
+            closed = true;
+            return { ok: true };
+        }
+        catch (err) {
+            if (!closed) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    /* fd may already be unusable */
+                }
+            }
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                /* best-effort; nothing else holds it */
+            }
+            throw new Error(`entwurf-v2-lock: failed to write claim to ${lockPath}: ${err.code ?? "unknown error"}`);
+        }
+    };
+    const first = tryCreate();
+    if (first.ok)
+        return { ok: true, claim };
+    if (first.code !== "EEXIST") {
+        // A non-EEXIST failure (EACCES, ENOSPC, …) is not a lock conflict — it is a
+        // real IO failure the caller must see, not a silent "locked".
+        throw new Error(`entwurf-v2-lock: failed to acquire ${lockPath}: ${first.code ?? "unknown error"}`);
+    }
+    // EEXIST: a lock already exists. Read it and decide reclaim vs conflict.
+    let holder;
+    try {
+        holder = parseLockClaim(readFileSync(lockPath, "utf8"), lockPath, gardenId);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            // The holder released between our open-wx and our read — retry once.
+            const retry = tryCreate();
+            if (retry.ok)
+                return { ok: true, claim };
+            // Someone else re-grabbed it; report the actual winner (not "corrupt").
+            return conflict(readHolder());
+        }
+        throw err;
+    }
+    // Empty/corrupt/wrong-gid lockfile → conflict (NEVER auto-deleted: could be
+    // mid-write, and there is no dead pid to reclaim by).
+    if (holder === null)
+        return conflict(null);
+    // Stale reclaim is allowed ONLY for our own host + a provably-dead pid (ESRCH).
+    const reclaimable = holder.hostname === hostname && classifyProcessLiveness(holder.pid, killFn) === "dead";
+    if (!reclaimable)
+        return conflict(holder);
+    // ── Reclaim under a wx mutex (closes the F2 two-reclaimer race) ────────────
+    // The blind unlink this replaced could delete a SUCCESSOR's fresh lock: two
+    // dispatchers read the same dead holder, the first reclaimed+recreated, the
+    // second's unlink then deleted the first's new lock → both spawned. The mutex
+    // serializes every would-be reclaimer: another reclaimer (or a fresh acquirer
+    // that EEXISTed on the still-present stale lock and re-entered this branch)
+    // loses the marker wx and fails closed. While the stale lock is still present
+    // it therefore cannot change under us; the ONE actor that can appear is a fresh
+    // acquirer winning the unlink→create gap (its wx then succeeds on the absent
+    // path) — handled below as an honest conflict, never a clobber. An EEXIST on
+    // the marker is a fail-closed conflict (a permanent conflict is the accepted
+    // worst case — same grade as a corrupt lockfile — never a double-spawn).
+    let markerFd;
+    try {
+        markerFd = openSync(reclaimMarkerPath, "wx");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST") {
+            const markerMtime = lockMtimeIso(reclaimMarkerPath);
+            const age = markerMtime ? ` (marker mtime ${markerMtime})` : "";
+            return conflict(holder, `reclaim already in progress (or a stale reclaim marker at ${reclaimMarkerPath}${age}); confirm no dispatcher is mid-reclaim, then clear it by hand`);
+        }
+        throw err;
+    }
+    try {
+        deps._test_beforeReread?.();
+        // Re-read UNDER the mutex: the lock must still be the exact dead claim we
+        // judged (Fable's nonce re-compare). If it changed (a normal release +
+        // recreate — impossible for a dead holder, but cheap insurance) abort.
+        const current = readHolder();
+        if (current === null || current.nonce !== holder.nonce)
+            return conflict(current);
+        try {
+            unlinkSync(lockPath);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        deps._test_beforeRecreate?.();
+        const reacquired = tryCreate();
+        if (reacquired.ok)
+            return { ok: true, claim };
+        // A fresh acquirer slipped into the unlink→create gap — honest conflict.
+        return conflict(readHolder());
+    }
+    finally {
+        try {
+            closeSync(markerFd);
+        }
+        catch {
+            /* fd may already be unusable */
+        }
+        try {
+            unlinkSync(reclaimMarkerPath);
+        }
+        catch {
+            /* best-effort; a leftover marker just fail-closes the next reclaim */
+        }
+    }
+}
+/**
+ * Release the lock — unlink ONLY when the on-disk nonce is still ours. A lock
+ * that was reclaimed and re-acquired by a successor carries a different nonce, so
+ * a late release returns `not-owned` and leaves the successor's claim intact. An
+ * already-gone lock returns `absent`. This is the second half of the F2 guard:
+ * without the nonce check a recycled pid or a stale watcher could delete a live
+ * successor's lock. The read passes `claim.gardenId` so a `<A>.lock` carrying a
+ * different gardenId (with a coincidental same nonce) is `not-owned`, never freed
+ * — path authority is the gid all the way through (GPT 4 / 동결결정3).
+ */
+export function releaseLock(claim, deps = {}) {
+    const lockPath = claim.lockPath ?? lockPathFor(claim.gardenId, deps.dir);
+    let onDisk;
+    try {
+        onDisk = parseLockClaim(readFileSync(lockPath, "utf8"), lockPath, claim.gardenId);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "absent";
+        throw err;
+    }
+    if (onDisk === null || onDisk.nonce !== claim.nonce)
+        return "not-owned";
+    try {
+        unlinkSync(lockPath);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "absent";
+        throw err;
+    }
+    return "released";
+}