@junghanacs/entwurf 0.30.1 → 0.31.0

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

@@ -76,7 +76,7 @@ export class MetaRecordError extends Error {
  * every write, including its own. `./run.sh doctor-meta-bridge` already flags a
  * stale deployed writer — run it after the change.
  */
-export const META_BACKENDS = ["claude-code", "antigravity", "codex", "copilot", "omp"];
+export const META_BACKENDS = ["claude-code", "antigravity", "codex", "copilot", "omp", "pi-durable"];
 export const META_BACKEND_DESCRIPTORS = {
     "claude-code": {
         backend: "claude-code",
@@ -189,6 +189,24 @@ export const META_BACKEND_DESCRIPTORS = {
         deliveryLevel: "D6",
         nativeIdLabel: "sessionId",
     },
+    // The long-running durable app (#129). Graded only as far as its RECORDED receipts reach.
+    //   sessionId the durable session directory name `<13-digit ms>-<uuid>` that
+    //             `selectSession` creates and `--continue` reopens
+    //             (`experimental/durable/sessions.ts:18-55` @cd32f77), surfaced as
+    //             `view.current().session.id`. Not `pi.provider.sessionId`, which a
+    //             fork changes.
+    //   D2        receiver armed: the contact mints the record, names the host as sender, and arms
+    //             a root doorbell (the receiver marker is owned by the host pid as `pi-durable-host`,
+    //             which the owner join admits). The addressed-enqueue → idle-wake → root-notice → drain
+    //             chain has ONE recorded receipt, on the scripted-model + native-harness lab cell
+    //             (`check-pi-durable-receive`, S+H, V not run) — lab evidence, not a vendor-turn D4–D6
+    //             acceptance, and no sibling-isolation (D3) or LIVE fresh receipt exists yet.
+    "pi-durable": {
+        backend: "pi-durable",
+        wakeMode: "self-fetch",
+        deliveryLevel: "D2",
+        nativeIdLabel: "sessionId",
+    },
 };
 // ---------------------------------------------------------------------------
 // Validation helpers (crash, don't warn)
@@ -261,7 +279,15 @@ function isoNow(now) {
 /** The one live identity schema number. */
 export const META_SCHEMA_VERSION_V3 = 3;
 /** Every backend admitted by the one V3 record-citizen schema. */
-export const META_CITIZEN_BACKENDS = ["claude-code", "antigravity", "codex", "copilot", "omp", "pi"];
+export const META_CITIZEN_BACKENDS = [
+    "claude-code",
+    "antigravity",
+    "codex",
+    "copilot",
+    "omp",
+    "pi-durable",
+    "pi",
+];
 export function requireCitizenBackend(value) {
     if (typeof value !== "string" || !META_CITIZEN_BACKENDS.includes(value)) {
         throw new MetaRecordError(`meta-record "backend" must be one of ${META_CITIZEN_BACKENDS.join(" | ")} (got ${describe(value)}).`);

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

@@ -95,6 +95,8 @@ import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, } fr
 import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
 import { resolveCodexDefaultSocketPath } from "./native-push/codex-ws-client.js";
 import { OMP_PREFLIGHT_HINT, ompFreshPreflight } from "./omp-fresh-preflight.js";
+import { PI_DURABLE_PREFLIGHT_HINT, piDurableFreshPreflight, } from "./pi-durable-fresh-preflight.js";
+import { checkPiDurableRuntime, PI_DURABLE_RUNTIME_HINT, piDurablePackageLayout } from "./pi-durable-runtime.js";
 import { classifyTmuxSessionName, resolveTmuxSessionId } from "./resolve-tmux-session.js";
 /**
  * THE COMPOSITION MOVED, THE RAIL DID NOT (#116 S2-a). Backend argv, the first-turn framing and
@@ -154,6 +156,10 @@ export const FRESH_CALL_RUNTIME = {
     copilot: "entwurf",
     omp: "omp",
     codex: "codex",
+    // #129: like copilot, a MANAGED verb and never the bare app. The durable app is source-only
+    // and runs under the operator-provided runtime's own resolver; `entwurf pi-durable` is the one
+    // fixed invocation that verifies that runtime against the pin and execs the packaged bootstrap.
+    "pi-durable": "entwurf",
 };
 /**
  * WHICH RULE PICKS THE TARGET SESSION. Three in strict order, and the order is the contract:
@@ -197,9 +203,9 @@ export function selectFreshCallSeat(placement) {
  * for. That is sufficient and not a compromise: every reader of the carrier trims and tests
  * truthiness (`index.ts:212-217`), so empty and absent are the same answer by construction.
  *
- * It is applied to all five backends because the leak is a property of tmux, not of a vendor. A
+ * It is applied to all six backends because the leak is a property of tmux, not of a vendor. A
  * scrub only on the backend whose measurement surfaced it would encode the claim that the other
- * four are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
+ * five are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
  * authoritative when the process that owns it exported it ITSELF, and a fresh `pi` sibling does
  * exactly that after this argv has run. This is a fixed seam and deliberately NOT a general env
  * carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping power this
@@ -337,6 +343,26 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
         if (missing)
             return { ok: false, reason: missing };
     }
+    if (params.backend === "pi-durable") {
+        // The framed first input is computed here only to MEASURE it against the bootstrap payload
+        // cap; the same pure function composes it again below. The runtime is located and verified
+        // with THIS process's env, before anything is placed. That is the bridge's env, not
+        // necessarily the window's: a new-window pane inherits the tmux SERVER's environment
+        // (measured, see SCRUBBED_INHERITED_ENV), and the window runs whatever `entwurf` PATH names.
+        // The managed verb re-verifies with its own env before it execs anything, so the window never
+        // runs an unverified runtime — but when HOME/XDG_DATA_HOME or the package closure differ, this
+        // verdict and the window's can disagree, and the window is left showing its own refusal.
+        const layout = piDurablePackageLayout();
+        const runtime = layout === null ? null : checkPiDurableRuntime(env, layout);
+        const missing = piDurableFreshPreflight({
+            model,
+            firstInput: buildFreshCallPrompt({ backend: params.backend, task, callerGardenId, nonce }),
+            layout,
+            runtime: runtime === null || runtime.ok ? null : runtime.reason,
+        });
+        if (missing)
+            return { ok: false, reason: missing };
+    }
     const inspected = inspectPlacement(env);
     if (!inspected.ok)
         return { ok: false, reason: inspected.reason };
@@ -448,6 +474,8 @@ const REJECT_HINT = {
     // the sentence an operator reads cannot drift away from the predicate that produced it.
     ...COPILOT_PREFLIGHT_HINT,
     ...OMP_PREFLIGHT_HINT,
+    ...PI_DURABLE_RUNTIME_HINT,
+    ...PI_DURABLE_PREFLIGHT_HINT,
     ...CODEX_PREFLIGHT_HINT,
     ...CODEX_CALLER_PREFLIGHT_HINT,
     ...CODEX_CALLER_SEAT_HINT,

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

@@ -0,0 +1,92 @@
+/**
+ * pi-durable-fresh-preflight — the pre-mutation check a pi-durable fresh call needs (#129 W, L6;
+ * `docs/adding-a-harness.md` step 9 clauses 2, 3 and 5).
+ *
+ * Same question as `omp-fresh-preflight.ts`, at the same moment: before `mux-fresh-call` mutates the
+ * operator's tmux session, is everything the fresh contract needs actually in place? A refusal HERE,
+ * before placement, leaves no window behind. A pass here does not promise the window's own pass: the
+ * managed verb re-verifies inside the window, whose env is the tmux SERVER's and whose `entwurf` is
+ * whatever PATH names, so under env or package-closure skew it can still refuse after the window
+ * exists — and that refusal is left showing in it.
+ *
+ * ── The inputs, first ──
+ *
+ *   model         the fresh-call model grammar already admits `/`, and a durable launch needs the
+ *                 provider spelled out (the bootstrap refuses a model resolved by inference), so
+ *                 the model here is `<provider>/<model id>` split at the FIRST `/` — a catalog id
+ *                 that itself contains `/` keeps it. A model with no provider part is refused.
+ *   first input   the whole framing (callback first, then the task) rides the bootstrap's closed
+ *                 `{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 runtime, then the four units ──
+ *
+ *   runtime          operator-provided at the fixed locator and verified against the pin
+ *                    (`pi-durable-runtime.ts`); passed in as that check's verdict.
+ *   birth            the compiled contact in this package's closure — it mints the record.
+ *   MCP hand         the compiled entwurf-bridge entry in the same closure — the contact spawns it.
+ *   receive          the compiled owner join in the same closure admits `pi-durable-host`; without
+ *                    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.
+ *
+ * ── What this deliberately does NOT claim ──
+ *
+ * Filesystem truth about ONE package closure and ONE runtime directory. It does not prove the durable
+ * app opens, the bridge connects, the doorbell arms or a garden id renders — that is runtime truth for
+ * the clause 7 LIVE receipt. No spawn, no network, no mutation; every path arrives as an argument, so
+ * this leaf imports nothing but types.
+ */
+import { existsSync, readFileSync } from "node:fs";
+/** The bootstrap decoder's task cap (`meta-bridge-omp.ts` OMP_BOOTSTRAP_TASK_MAX_CHARS); the beside
+ * test holds the two equal. */
+export const PI_DURABLE_FIRST_INPUT_MAX_CHARS = 16000;
+/** `<provider>/<model id>` at the FIRST `/`, or `null` when either side is empty. */
+export function splitPiDurableModel(model) {
+    const at = model.indexOf("/");
+    if (at <= 0 || at === model.length - 1)
+        return null;
+    return { provider: model.slice(0, at), model: model.slice(at + 1) };
+}
+/** The compiled owner join, read from the emitted bytes the bridge actually loads. */
+function ownerJoinAdmitsDurableHost(file) {
+    try {
+        const join = /SENDER_JOINED_RECEIVER_OWNER_KINDS\s*=\s*(\[[^\]]*\])/.exec(readFileSync(file, "utf8"))?.[1];
+        return join?.includes('"pi-durable-host"') ?? false;
+    }
+    catch {
+        // Bounded environment probe: an unreadable file is a missing unit.
+        return false;
+    }
+}
+/** The FIRST missing thing, in repair order, or `null` when a fresh launch may proceed. */
+export function piDurableFreshPreflight(params) {
+    if (splitPiDurableModel(params.model) === null)
+        return "pi-durable-model-not-provider-qualified";
+    if (params.firstInput.length > PI_DURABLE_FIRST_INPUT_MAX_CHARS)
+        return "pi-durable-first-input-too-long";
+    if (params.layout === null)
+        return "pi-durable-package-incomplete";
+    if (params.runtime !== null)
+        return params.runtime;
+    const layout = params.layout;
+    if (!existsSync(layout.adapter))
+        return "pi-durable-birth-unit-missing";
+    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";
+    return null;
+}
+/** Repair text beside the predicate that decides it. The runtime reasons keep theirs on the runtime
+ * leaf; `mux-fresh-call` spreads both tables. */
+export const PI_DURABLE_PREFLIGHT_HINT = {
+    "pi-durable-model-not-provider-qualified": "a pi-durable model is `<provider>/<model id>` — the durable bootstrap resolves no provider by inference",
+    "pi-durable-first-input-too-long": "the framed first input exceeds the 16000-character bootstrap payload cap — shorten the task",
+    "pi-durable-birth-unit-missing": "this Entwurf package has no compiled pi-durable contact (mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-pi-durable.js), so the sibling would mint no record — reinstall or rebuild Entwurf",
+    "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",
+};

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

@@ -0,0 +1,288 @@
+/**
+ * pi-durable-runtime — where the operator-provided durable runtime lives, and whether it is the pin
+ * (#129 W, L3).
+ *
+ * The experimental durable app is SOURCE-ONLY upstream: the published Pi CLI ships no
+ * `dist/experimental`, and `@earendil-works/pi-durable` on npm is the library, not this app. So its
+ * runtime is a checkout the OPERATOR provides — the pinned commit plus this package's overlay patch
+ * and the pinned model data — and Entwurf never downloads, installs, moves or deletes it. This leaf
+ * only DETECTS it, at ONE fixed place:
+ *
+ *   $XDG_DATA_HOME/entwurf/pi-durable/runtime   (an absolute XDG_DATA_HOME; else ~/.local/share)
+ *
+ * There is no public path override. `ENTWURF_PI_DURABLE_RUNTIME` stays the CHECKOUT-ONLY input of
+ * the `check-pi-durable-*` gates; nothing here reads it.
+ *
+ * A present runtime counts as the pin only when HEAD equals the pinned commit, the index equals HEAD
+ * (nothing staged), `git diff --binary` equals the overlay patch bytes exactly, no non-ignored file is
+ * untracked, the experimental source resolver is there, and the git-ignored model data matches the
+ * pin's recorded digests. Anything else is present-but-wrong, a named refusal — never a guess and
+ * never a repair. The index term is not optional: `git diff` compares the worktree to the INDEX, so a
+ * staged edit to any other tracked file — or a staged new file, which is not "untracked" either —
+ * would otherwise leave the diff equal to the patch.
+ *
+ * The diff bytes are compared, so the configuration knobs known to move them are pinned on the
+ * command line to the form the packaged patch is in: abbreviation length, prefixes, colour,
+ * external/textconv drivers, hunk algorithm and context, relative paths, and blank-context spacing
+ * (`diff.suppressBlankEmpty`; the packaged patch has blank context lines). That is a bounded list,
+ * not every knob git has: e.g. `diff.orderFile` (multi-file order) and line-ending conversion
+ * (`core.autocrlf`/`core.eol`) are not neutralized, and a byte change they cause reads as pin drift.
+ * Configuration is not disabled wholesale — `safe.directory` lives in global/system config.
+ *
+ * The overlay data (pin + patch) ships IN this package and is found relative to this module, at the
+ * two depths the module is shipped at: the source checkout (`<root>/pi-extensions/lib/`) and the
+ * compiled bridge closure (`<root>/mcp/entwurf-bridge/dist/pi-extensions/lib/`) — the same two-depth
+ * arithmetic `metaCapabilitiesFilePath` answers. The compiled durable units are named from that same
+ * root, so a launcher, a preflight and the bootstrap all read ONE package closure.
+ *
+ * Read-only: `git diff` and `git ls-files` run against a private COPY of the runtime's index
+ * (`GIT_INDEX_FILE`), with GIT_OPTIONAL_LOCKS=0. The copy is not ceremony: `git diff` was measured
+ * to refresh and rewrite a stat-dirty index even with optional locks off, so asking the operator's
+ * own index would mutate their checkout. No network, no install, no credential, settings or session read.
+ * Each `git` is a direct child with a wall-clock bound; one that does not answer in time is unverifiable.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** The fixed locator under the data home. Not configurable. */
+export const PI_DURABLE_RUNTIME_SEGMENTS = ["entwurf", "pi-durable", "runtime"];
+/** The upstream source resolver the durable app runs under, inside the runtime checkout. */
+export const PI_DURABLE_RESOLVER_RELATIVE = path.join("packages", "coding-agent", "src", "experimental", "source-resolver.ts");
+/** The layout rooted at `root`, as plain paths. */
+export function piDurableLayoutAt(root) {
+    const dist = path.join(root, "mcp", "entwurf-bridge", "dist");
+    return {
+        root,
+        overlayDir: path.join(root, "pi", "pi-durable", "overlay"),
+        bootstrap: path.join(root, "pi", "pi-durable", "bootstrap.mjs"),
+        adapter: path.join(dist, "pi-extensions", "meta-bridge-pi-durable.js"),
+        bridgeEntry: path.join(dist, "mcp", "entwurf-bridge", "src", "index.js"),
+        deliverability: path.join(dist, "pi-extensions", "lib", "entwurf-deliverability.js"),
+    };
+}
+/**
+ * The package closure, found from where THIS module lives: the source depth first, then the compiled
+ * depth. `null` when neither carries the overlay pin — a packaging defect, refused by name.
+ */
+export function piDurablePackageLayout(from = import.meta.dirname) {
+    for (const up of [
+        ["..", ".."],
+        ["..", "..", "..", "..", ".."],
+    ]) {
+        const root = path.resolve(from, ...up);
+        const layout = piDurableLayoutAt(root);
+        if (fs.existsSync(path.join(layout.overlayDir, "upstream-pin.json")))
+            return layout;
+    }
+    return null;
+}
+/** The fixed runtime location for this environment, or `null` when neither an absolute
+ * XDG_DATA_HOME nor HOME exists to anchor it. A relative XDG_DATA_HOME is ignored (XDG spec). */
+export function piDurableRuntimeDir(env) {
+    const xdg = env.XDG_DATA_HOME;
+    if (typeof xdg === "string" && xdg.length > 0 && path.isAbsolute(xdg)) {
+        return path.join(xdg, ...PI_DURABLE_RUNTIME_SEGMENTS);
+    }
+    const home = env.HOME;
+    if (typeof home === "string" && home.length > 0 && path.isAbsolute(home)) {
+        return path.join(home, ".local", "share", ...PI_DURABLE_RUNTIME_SEGMENTS);
+    }
+    return null;
+}
+/** The packaged pin and its one patch. A malformed pin throws (crash, don't warn). */
+export function readPiDurablePin(overlayDir) {
+    const pin = JSON.parse(fs.readFileSync(path.join(overlayDir, "upstream-pin.json"), "utf8"));
+    if (typeof pin.commit !== "string" || !/^[0-9a-f]{40}$/.test(pin.commit)) {
+        throw new Error(`pi-durable pin: commit is not a full sha (${JSON.stringify(pin.commit)})`);
+    }
+    if (!Array.isArray(pin.patches) || pin.patches.length !== 1 || typeof pin.patches[0] !== "string") {
+        throw new Error("pi-durable pin: exactly one overlay patch is expected");
+    }
+    const md = pin.modelData;
+    if (typeof md !== "object" ||
+        md === null ||
+        typeof md.path !== "string" ||
+        typeof md.files !== "number" ||
+        typeof md.aggregateSha256 !== "string" ||
+        typeof md.manifestSha256 !== "string") {
+        throw new Error("pi-durable pin: modelData is malformed");
+    }
+    return { pin, patchBytes: fs.readFileSync(path.join(overlayDir, pin.patches[0])) };
+}
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+/** The patch shape the packaged patch is in, fixed on the command line for the knobs the header lists:
+ * git's default output with 8-hex `index` abbreviations. Two of those knobs are config-only and ride
+ * beside these as `-c` at the call: `core.abbrev=8` ("auto" scales with the clone's object count) and
+ * `diff.suppressBlankEmpty=false` (true drops the space before an empty context line). */
+export const PI_DURABLE_DIFF_SHAPE = [
+    "--binary",
+    "--no-ext-diff",
+    "--no-color",
+    "--no-textconv",
+    "--src-prefix=a/",
+    "--dst-prefix=b/",
+    "--no-relative",
+    "--diff-algorithm=myers",
+    "--indent-heuristic",
+    "-U3",
+    "--inter-hunk-context=0",
+];
+/** Wall-clock bound for each local `git` the verifier runs (it also runs inside the bridge process). */
+export const PI_DURABLE_GIT_TIMEOUT_MS = 30_000;
+export function inspectPiDurableRuntime(runtimeDir, overlayDir) {
+    const { pin, patchBytes } = readPiDurablePin(overlayDir);
+    const present = (() => {
+        try {
+            return fs.statSync(runtimeDir).isDirectory();
+        }
+        catch {
+            // Bounded environment probe (Hard Rule 15's stated exception): absence is the answer.
+            return false;
+        }
+    })();
+    const base = { ...process.env, GIT_OPTIONAL_LOCKS: "0" };
+    const git = (args, env = base) => spawnSync("git", ["-C", runtimeDir, ...args], {
+        maxBuffer: 64 * 1024 * 1024,
+        env,
+        timeout: PI_DURABLE_GIT_TIMEOUT_MS,
+    });
+    const headRun = present ? git(["rev-parse", "HEAD"]) : undefined;
+    // A private copy of the index, so the refresh `git diff` performs lands in a file this process owns.
+    let scratch;
+    let cachedRun;
+    let diffRun;
+    let untrackedRun;
+    try {
+        const indexPath = present ? git(["rev-parse", "--git-path", "index"]) : undefined;
+        const index = indexPath?.status === 0 ? path.resolve(runtimeDir, indexPath.stdout.toString().trim()) : undefined;
+        if (index !== undefined && fs.existsSync(index)) {
+            scratch = fs.mkdtempSync(path.join(os.tmpdir(), "pi-durable-index-"));
+            const copy = path.join(scratch, "index");
+            fs.copyFileSync(index, copy);
+            const onCopy = { ...base, GIT_INDEX_FILE: copy };
+            // HEAD → index: exit 0 = nothing staged, 1 = something staged; anything else is no answer.
+            cachedRun = git(["diff", "--cached", "--quiet", "--no-ext-diff", "--no-relative"], onCopy);
+            diffRun = git(["-c", "core.abbrev=8", "-c", "diff.suppressBlankEmpty=false", "diff", ...PI_DURABLE_DIFF_SHAPE], onCopy);
+            untrackedRun = git(["ls-files", "--others", "--exclude-standard"], onCopy);
+        }
+    }
+    finally {
+        if (scratch !== undefined)
+            fs.rmSync(scratch, { recursive: true, force: true });
+    }
+    const gitAnswered = headRun?.status === 0 &&
+        (cachedRun?.status === 0 || cachedRun?.status === 1) &&
+        diffRun?.status === 0 &&
+        untrackedRun?.status === 0;
+    const dataDir = path.join(runtimeDir, pin.modelData.path);
+    const dataFiles = (() => {
+        try {
+            return fs
+                .readdirSync(dataDir)
+                .filter((n) => n.endsWith(".json") && !n.startsWith("."))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    })();
+    const manifest = path.join(dataDir, ".manifest.json");
+    return {
+        runtimeDir,
+        present,
+        gitAnswered,
+        head: headRun?.stdout?.toString().trim() ?? "",
+        indexMatchesHead: cachedRun?.status === 0,
+        diffEqualsPatch: diffRun?.status === 0 && Buffer.isBuffer(diffRun.stdout) && diffRun.stdout.equals(patchBytes),
+        untracked: untrackedRun?.stdout?.toString().trim() ?? "",
+        resolverPresent: present && fs.existsSync(path.join(runtimeDir, PI_DURABLE_RESOLVER_RELATIVE)),
+        modelDataFiles: dataFiles.length,
+        modelDataAggregate: sha256(dataFiles.map((n) => `${sha256(fs.readFileSync(path.join(dataDir, n)))}  ${n}\n`).join("")),
+        manifestSha256: fs.existsSync(manifest) ? sha256(fs.readFileSync(manifest)) : "absent",
+    };
+}
+/** The verdict over those facts against the pin: `null` is "this is the pin". */
+export function piDurableRuntimeVerdict(facts, pin) {
+    if (!facts.present)
+        return "pi-durable-runtime-absent";
+    if (!facts.gitAnswered)
+        return "pi-durable-runtime-unverifiable";
+    if (!facts.indexMatchesHead)
+        return "pi-durable-runtime-pin-drift";
+    if (facts.head !== pin.commit || !facts.diffEqualsPatch || facts.untracked !== "" || !facts.resolverPresent) {
+        return "pi-durable-runtime-pin-drift";
+    }
+    if (facts.modelDataFiles !== pin.modelData.files ||
+        facts.modelDataAggregate !== pin.modelData.aggregateSha256 ||
+        facts.manifestSha256 !== pin.modelData.manifestSha256) {
+        return "pi-durable-runtime-modeldata-drift";
+    }
+    return null;
+}
+/** Locate and verify, in that order. The launcher, setup and the fresh preflight all ask this. */
+export function checkPiDurableRuntime(env, layout) {
+    if (layout === null)
+        return { ok: false, reason: "pi-durable-package-incomplete", runtimeDir: null };
+    const runtimeDir = piDurableRuntimeDir(env);
+    if (runtimeDir === null)
+        return { ok: false, reason: "pi-durable-runtime-locator-unset", runtimeDir: null };
+    const { pin } = readPiDurablePin(layout.overlayDir);
+    const reason = piDurableRuntimeVerdict(inspectPiDurableRuntime(runtimeDir, layout.overlayDir), pin);
+    if (reason !== null)
+        return { ok: false, reason, runtimeDir };
+    return { ok: true, runtimeDir, resolver: path.join(runtimeDir, PI_DURABLE_RESOLVER_RELATIVE) };
+}
+export const PI_DURABLE_RUNTIME_HINT = {
+    "pi-durable-package-incomplete": "this Entwurf package carries no pi-durable overlay pin next to its code — reinstall Entwurf; the package itself is incomplete",
+    "pi-durable-runtime-locator-unset": "neither an absolute XDG_DATA_HOME nor HOME is set, so the fixed runtime location cannot be named",
+    "pi-durable-runtime-absent": "no operator-provided durable runtime at the fixed location — Entwurf never installs it: provide the pinned upstream checkout plus the overlay patch and model data there (docs/setup-clean-host.md)",
+    "pi-durable-runtime-unverifiable": "the runtime location exists but git could not read it as a checkout, so it cannot be proven to be the pin",
+    "pi-durable-runtime-pin-drift": "the runtime is not the pin: HEAD, the overlay patch bytes, an untracked file or the source resolver differs from the packaged pi/pi-durable/overlay/upstream-pin.json — re-provision it at the pinned commit with exactly the packaged patch",
+    "pi-durable-runtime-modeldata-drift": "the runtime's git-ignored model data is not the pinned bytes — restore the model data the pin records",
+};
+/** Exit codes of the CLI below, read by `run.sh`: 0 verified, 4 absent (setup SKIP), 3 anything else. */
+export const PI_DURABLE_RUNTIME_EXIT = { verified: 0, absent: 4, refused: 3 };
+/**
+ * `resolve`: print the verified runtime's source-resolver path (stdout) and exit 0, or print
+ * `<reason>: <hint>` (stderr) and exit 4 for an absent runtime / 3 for every other refusal.
+ * The launcher execs node under that resolver; setup maps the three codes to PASS / SKIP / FAIL.
+ */
+export function runPiDurableRuntimeCli(argv, env, layout, out) {
+    if (argv.length !== 1 || argv[0] !== "resolve") {
+        out.stderr("usage: pi-durable-runtime resolve");
+        return 2;
+    }
+    const checked = checkPiDurableRuntime(env, layout);
+    if (checked.ok) {
+        out.stdout(checked.resolver);
+        return PI_DURABLE_RUNTIME_EXIT.verified;
+    }
+    out.stderr(`${checked.reason}${checked.runtimeDir === null ? "" : ` (${checked.runtimeDir})`}: ${PI_DURABLE_RUNTIME_HINT[checked.reason]}`);
+    return checked.reason === "pi-durable-runtime-absent"
+        ? PI_DURABLE_RUNTIME_EXIT.absent
+        : PI_DURABLE_RUNTIME_EXIT.refused;
+}
+// RUN AS THE CLI ONLY WHEN THIS FILE IS THE PROCESS ENTRY. Decided by an argv comparison, as in
+// meta-bridge-hook-codex.ts, and not by the `main` flag on import.meta: that flag landed in Node 24.2.0
+// and the package floor is major 24, so on 24.0/24.1 it is undefined — `resolve` would exit 0 having
+// printed nothing, which setup reads as PASS and the launcher as a resolver.
+const invokedDirectly = (() => {
+    const entry = process.argv[1];
+    if (typeof entry !== "string" || entry.length === 0)
+        return false;
+    try {
+        return fs.realpathSync(entry) === fs.realpathSync(import.meta.filename);
+    }
+    catch {
+        // Bounded environment probe: an entry that cannot be resolved is not this file.
+        return false;
+    }
+})();
+if (invokedDirectly) {
+    process.exitCode = runPiDurableRuntimeCli(process.argv.slice(2), process.env, piDurablePackageLayout(), {
+        stdout: (line) => process.stdout.write(`${line}\n`),
+        stderr: (line) => process.stderr.write(`${line}\n`),
+    });
+}