@junghanacs/entwurf 0.12.0 → 0.12.2

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

@@ -0,0 +1,64 @@
+/**
+ * entwurf-v2-mailbox — the 5c-4 meta-mailbox SEND body (0.11 Stage 0 step 5c-4, the
+ * LAST 5c transport slice). It is ENQUEUE-ONLY: render the mailbox body from the plan
+ * the 5b decider ALREADY chose and drop it in the target citizen's meta-bridge mailbox.
+ * It DECIDES NO ROUTING (the dispatch table did) and carries NO release seam — a
+ * meta-mailbox plan is the lock-free path (？7), and even when the 5c-2a send hand calls
+ * this on a re-resolved mailbox fallback (under a still-held control-socket lock),
+ * RELEASE STAYS THE HAND'S SINGLE RESPONSIBILITY. So this module has no `releaseLock`
+ * dep AT ALL — a lock leak from the mailbox body is structurally impossible.
+ *
+ * Two consumers, one body:
+ *   - the 5c-2a send hand's `deps.sendViaMailbox(plan, lock)` fallback seam
+ *     (entwurf-v2-send.ts) — a dead control socket re-resolved into a mailbox plan.
+ *   - the future 5d dispatch runner's direct unsupported-citizen fire-and-forget path
+ *     (the decider hands back a meta-mailbox plan with a NULL lock).
+ * Both call `executeMetaMailboxSend`; the hand reaches it through the async
+ * `sendViaMailbox(plan, lock)` adapter the production factory builds.
+ *
+ * A mailbox has NO in-band refuse — there is no live receiver to answer `success:false`.
+ * An enqueue either succeeds (`{success:true}`) or THROWS (citizen gone / fs / identity).
+ * The body NEVER folds a throw into `{success:false}`: the send hand maps a thrown error
+ * to `failed`+rethrow, which is the honest outcome for a non-delivery. `success:false` is
+ * a control-socket RPC notion (the receiver answered and refused) and would be a lie here.
+ *
+ * ctx-free, dep-injected (the same discipline the other entwurf-v2-* libs keep): the live
+ * sender envelope is built at the wiring site and passed in, so this module never imports
+ * ExtensionContext.
+ */
+import { formatMetaMailboxBody } from "./meta-mailbox-body.js";
+import { enqueueMetaMessage } from "./meta-session.js";
+/**
+ * Render the plan into a mailbox body and enqueue it ONCE. `sender` is the resolved
+ * envelope (built from live ctx at the wiring site — ctx kept OUT of this module); when
+ * it is undefined the raw `plan.message` is enqueued (the same envelope-less fallback the
+ * legacy mailbox path used). `plan.wantsReply` is threaded into the body — v2 carries the
+ * caller's intent, a DELIBERATE divergence from the legacy hard-coded `false`. An enqueue
+ * throw PROPAGATES; it is never converted to `{success:false}`.
+ */
+export function executeMetaMailboxSend(plan, sender, deps) {
+    const body = sender ? formatMetaMailboxBody(sender, plan.message, plan.wantsReply) : plan.message;
+    deps.enqueue({
+        gardenId: plan.targetGardenId,
+        body,
+        sessionsDir: plan.sessionsDir,
+        mailboxDir: plan.mailboxDir,
+    });
+    return { success: true };
+}
+/**
+ * Build the production `sendViaMailbox(plan, lock)` adapter the 5c-2a send hand consumes.
+ * It IGNORES `lock` entirely (release is the hand's job; a mailbox plan is lock-free) and
+ * wraps the sync body in the async dep signature. `senderProvider` is supplied by the
+ * wiring site — it calls the private `buildLocalSenderEnvelope(ctx)` and decorates
+ * origin/replyable — so this module never imports ExtensionContext. `enqueue` defaults to
+ * the real `enqueueMetaMessage`; the gate injects a fake.
+ */
+export function makeProductionSendViaMailbox(opts) {
+    const enqueue = opts.enqueue ?? enqueueMetaMessage;
+    // `_lock` is named in the signature for the send-hand dep contract but is NEVER read:
+    // a mailbox enqueue does not own or release the lock. `async` so a synchronous enqueue
+    // throw surfaces as a REJECTED promise (the async dep contract), not a sync throw — the
+    // send hand's `await` + try/catch handles either, but a rejection is the honest shape.
+    return async (plan, _lock) => executeMetaMailboxSend(plan, opts.senderProvider(), { enqueue });
+}

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

@@ -0,0 +1,218 @@
+/**
+ * entwurf-v2-production — 5d-2b: the ctx-free PRODUCTION assembly of `runEntwurfV2`'s deps.
+ * `makeProductionEntwurfV2Deps(opts)` wires the real 5b decider IO seams + the three 5c
+ * transport hands into one `EntwurfV2RunDeps` (`{decide, executor}`). It touches NO
+ * `ExtensionContext`/`ExtensionAPI` — the wiring SITE (5d-3, entwurf-control.ts) builds the
+ * `senderProvider` from `buildLocalSenderEnvelope(ctx)` and passes it in, so this module
+ * stays in `lib/` with the rest of the gate-/smoke-testable v2 core.
+ *
+ * Three invariants this factory exists to guarantee (each gate-proven):
+ *   - ONE lock domain (Q2/QB3). A single `release` closure bound to `lockDir` is the lock
+ *     authority for EVERY hand: the decider's `releaseLock`, the control-send hand's
+ *     `releaseLock`, AND the spawn watcher's `releaseFn`. The spawn factory's default
+ *     `releaseFn` ignores `lockDir` (it would release into the DEFAULT lock dir) — passing
+ *     `release` explicitly is what closes that split-brain.
+ *   - ONE mailbox sender (Q3). A single `makeProductionSendViaMailbox` instance is the
+ *     top-level meta-mailbox hand AND the control-send dead-fallback's mailbox enqueue, so a
+ *     direct send and a fallback send never drift in sender envelope / dirs.
+ *   - ONE path set (Q5). `sessionsDir`/`mailboxDir`/`lockDir`/`controlSocketDir` are resolved
+ *     ONCE and threaded to the decider, the dead-fallback resolver, and the enqueue, so the
+ *     plan the decider plants and the plan the fallback plants address the same store.
+ *
+ * `resolveTarget` (QB1): a MISSING meta-record is a soft `bad-target` (identity:null); a
+ * PRESENT-but-corrupt record fails LOUD (the read throws drift) — never matched by string.
+ * `preProbeAddressConflict` (QB2): a single record-side `lstat` (NO connect) of the target's
+ * canonical socket path; `indeterminate` (EACCES/unknown) fails loud rather than silently
+ * claiming "no conflict". The decider's later `inspectSocket` probe is a SEPARATE step.
+ */
+import { sendRpcCommand as realSendRpc, } from "./entwurf-control-rpc.js";
+import { mailboxConversationalDeliverable, receiverMarkerMatchesIdentity, } from "./entwurf-deliverability.js";
+import { isNonPiGardenIdSocketConflict } from "./entwurf-facts.js";
+import { isLivenessSupported } from "./entwurf-v2-contract.js";
+import { decideDispatch, } from "./entwurf-v2-decider.js";
+import { ENTWURF_V2_LOCK_DIR, acquireLock as realAcquireLock, releaseLock as realReleaseLock, } from "./entwurf-v2-lock.js";
+import { makeProductionSendViaMailbox } from "./entwurf-v2-mailbox.js";
+import { executeControlSocketSend, } from "./entwurf-v2-send.js";
+import { resolveDeadControlSendFallback } from "./entwurf-v2-send-fallback.js";
+import { executeSpawnBgResume } from "./entwurf-v2-spawn.js";
+import { makeProductionSpawnBgResumeDeps } from "./entwurf-v2-spawn-production.js";
+import { defaultMetaMailboxDir, defaultMetaSessionsDir, enqueueMetaMessage, metaCapabilityFor, metaRecordExistsByGardenId, readMetaIdentityByGardenId, readMetaReceiverMarker, } from "./meta-session.js";
+import { CONTROL_SOCKET_DIR, controlSocketPath, inspectControlSocketPath, inspectTargetControlSocket, isSocketOnlyPiCandidate, } from "./socket-discovery.js";
+import { classifyConnectError, probeSocketLiveness } from "./socket-probe.js";
+/**
+ * 0.12.1 B-2: the production `preflight` seam default. preflight value-imports
+ * `@earendil-works/pi-coding-agent` (ProjectTrustStore), so importing it eagerly
+ * would pull pi into the harness-neutral MCP bridge's boot closure. This wrapper
+ * defers that to a lazy `await import()` reached ONLY on the owned-outcome resume
+ * branch (the decider awaits it). peers/self/list/mailbox-deliver therefore boot
+ * with no pi package present; a pi-less environment that DOES hit a spawn-bg resume
+ * surfaces an honest module-not-found at that point rather than failing boot.
+ */
+async function lazyProductionPreflight(input) {
+    const { preflight } = await import("./entwurf-preflight.js");
+    return preflight(input);
+}
+/** Map a record-side socket inspection to the singleton (socketGids, symlinkedGids) the
+ * `isNonPiGardenIdSocketConflict` predicate consumes. `indeterminate` fails LOUD (QB2): an
+ * unprovable conflict must NOT be folded to "no conflict" — that would silently allow an
+ * unsupported-backend mailbox send onto a quarantined address. */
+function conflictSetsFor(gid, inspection) {
+    switch (inspection.kind) {
+        case "absent":
+            return { socketGids: new Set(), symlinkedGids: new Set() };
+        case "socket-file":
+            return { socketGids: new Set([gid]), symlinkedGids: new Set() };
+        case "address-conflict":
+            // symlink → the symlink axis; not-socket → a non-symlink `.sock` entry, same axis
+            // the fact-provider's `socketGids` carries (NOT only real sockets).
+            return inspection.reason === "symlink"
+                ? { socketGids: new Set(), symlinkedGids: new Set([gid]) }
+                : { socketGids: new Set([gid]), symlinkedGids: new Set() };
+        case "indeterminate":
+            throw new Error(`entwurf-v2-production: cannot resolve target ${gid} — its control socket lstat is indeterminate (${inspection.error}); refusing to claim "no address conflict".`);
+    }
+}
+/**
+ * Assemble the production `runEntwurfV2` deps. See the module header for the three wiring
+ * invariants. The returned `{ decide, executor }` is exactly the shape `runEntwurfV2` joins.
+ */
+export function makeProductionEntwurfV2Deps(opts) {
+    // ── ONE path set (Q5): resolve every dir ONCE ─────────────────────────────
+    const lockDir = opts.lockDir ?? ENTWURF_V2_LOCK_DIR;
+    const sessionsDir = opts.sessionsDir ?? defaultMetaSessionsDir();
+    const mailboxDir = opts.mailboxDir ?? defaultMetaMailboxDir();
+    const controlSocketDir = opts.controlSocketDir ?? CONTROL_SOCKET_DIR;
+    const s = opts.seams ?? {};
+    const io = {
+        metaRecordExists: s.metaRecordExists ?? metaRecordExistsByGardenId,
+        readIdentity: s.readIdentity ?? readMetaIdentityByGardenId,
+        readReceiverMarker: s.readReceiverMarker ?? ((gid) => readMetaReceiverMarker({ gardenId: gid })),
+        inspectPath: s.inspectPath ?? inspectControlSocketPath,
+        acquireLock: s.acquireLock ?? realAcquireLock,
+        releaseLock: s.releaseLock ?? realReleaseLock,
+        inspectSocket: s.inspectSocket ?? inspectTargetControlSocket,
+        probeSocket: s.probeSocket ?? probeSocketLiveness,
+        preflight: s.preflight ?? lazyProductionPreflight,
+        classifyConnect: s.classifyConnect ?? classifyConnectError,
+        sendRpc: s.sendRpc ?? realSendRpc,
+        enqueue: s.enqueue ?? enqueueMetaMessage,
+        spawnOverrides: s.spawnOverrides ?? {},
+    };
+    // ── ONE lock domain (Q2/QB3): a single lockDir-bound release for ALL hands ─
+    const acquire = (gid) => io.acquireLock(gid, { dir: lockDir });
+    const release = (claim) => {
+        io.releaseLock(claim, { dir: lockDir });
+    };
+    // ── ONE mailbox sender (Q3): one instance for the hand AND the dead-fallback ─
+    const sendViaMailbox = makeProductionSendViaMailbox({
+        senderProvider: opts.senderProvider,
+        enqueue: io.enqueue,
+    });
+    // ── ONE deliverability seam (SE-2 2d-3): wake-mode capability AND a live active-
+    // receiver (a presence marker that matches THIS identity). The SAME closure is injected
+    // into the decider AND the dead-fallback, so a direct send and a re-resolved fallback
+    // send can never drift to different deliverability verdicts. recordBacked is true by
+    // construction — resolveTarget already proved the record exists before any unsupported-
+    // backend mailbox route, and the closure is only consulted on that route. A null /
+    // dead-owner / identity-mismatched marker is fail-closed to inactive (SE-2): a reply to a
+    // terminated self-fetch citizen is rejected, not enqueued as mailbox garbage. ──────────
+    const mailboxDeliverabilityFor = (identity) => {
+        const wakeMode = metaCapabilityFor(identity.backend).wakeMode;
+        const marker = io.readReceiverMarker(identity.gardenId);
+        const matched = receiverMarkerMatchesIdentity(marker, identity);
+        return mailboxConversationalDeliverable({
+            wakeMode,
+            recordBacked: true,
+            ownerAlive: matched,
+            watchArmed: matched,
+        });
+    };
+    // ── target resolution (QB1 + QB2) ─────────────────────────────────────────
+    const resolveTarget = async (gid) => {
+        // MISSING record → not a citizen. But a record-LESS, gid-shaped, NON-SYMLINK control
+        // socket means the gid is still an addressable socket-only pi endpoint (A1 narrow,
+        // 0.11.0): entwurf_v2 accepts it as a FIRE-AND-FORGET control-send target only. This is
+        // PROBE-FREE — a single `inspectPath` lstat (NO connect), the SAME seam the pre-probe
+        // conflict uses — and `isSocketOnlyPiCandidate` promotes ONLY a confirmed non-symlink
+        // socket (`socket-file`); symlink/absent/not-socket/indeterminate stay a plain
+        // bad-target. PRESENT record → read (drift/corrupt throws = fail-loud).
+        if (!io.metaRecordExists(gid, sessionsDir)) {
+            const inspection = await io.inspectPath(controlSocketPath(gid, controlSocketDir));
+            return { identity: null, preProbeAddressConflict: false, socketOnlyPi: isSocketOnlyPiCandidate(inspection) };
+        }
+        const identity = io.readIdentity(gid, sessionsDir);
+        // `preProbeAddressConflict` is the record-side NON-PI conflict ONLY (B1). An in-domain
+        // (pi) target's socket lstat/connect MUST run UNDER the lock in the decider's later
+        // `inspectSocket` step (1C: lock BEFORE lstat/connect) — so a pi target short-circuits
+        // here with NO pre-lock lstat. Doing the lstat here would (a) be a needless pre-lock IO
+        // and (b) turn a pi target's `indeterminate` lstat into a top-level throw, stealing it
+        // from the under-lock `inspectSocket → indeterminate → indeterminate-no-spawn` path.
+        if (isLivenessSupported(identity.backend)) {
+            return { identity, preProbeAddressConflict: false };
+        }
+        // Only an unsupported (non-pi) citizen reaches the record-side lstat: a single lstat (no
+        // connect) of the canonical path; `indeterminate` fails loud (QB2 — never "no conflict").
+        const inspection = await io.inspectPath(controlSocketPath(gid, controlSocketDir));
+        const { socketGids, symlinkedGids } = conflictSetsFor(gid, inspection);
+        const preProbeAddressConflict = isNonPiGardenIdSocketConflict(identity.backend, gid, socketGids, symlinkedGids);
+        return { identity, preProbeAddressConflict };
+    };
+    const inspectSocket = (gid) => io.inspectSocket(gid, controlSocketDir);
+    const probeSocket = (socketPath) => io.probeSocket(socketPath);
+    // ── decider deps (5b) ─────────────────────────────────────────────────────
+    const deciderDeps = {
+        resolveTarget,
+        acquireLock: acquire,
+        releaseLock: release,
+        inspectSocket,
+        probeSocket,
+        preflightForCwd: (cwd) => io.preflight({ cwd, agentDir: opts.agentDir, prefixRoots: opts.prefixRoots }),
+        mailboxDeliverabilityFor,
+        mailboxDir,
+        sessionsDir,
+        observeTimeoutMs: opts.observeTimeoutMs,
+    };
+    // ── control-send hand deps (5c-2): the dead-fallback shares resolveTarget /
+    // inspect / probe / dirs with the decider; the mailbox enqueue is the SAME
+    // `sendViaMailbox` instance; the release is the SAME `release` closure. ─────
+    const controlSendDeps = {
+        sendOverSocket: async (plan) => {
+            const { response } = await io.sendRpc(plan.socketPath, {
+                type: "send",
+                message: plan.message,
+                mode: plan.mode,
+                wants_reply: plan.wantsReply,
+                sender: opts.senderProvider(),
+            });
+            return { success: response.success, error: response.error };
+        },
+        classifyConnect: io.classifyConnect,
+        releaseLock: release,
+        deadFallback: (plan, lock) => resolveDeadControlSendFallback(plan, lock, {
+            resolveTarget,
+            inspectSocket,
+            probeSocket,
+            mailboxDeliverabilityFor,
+            mailboxDir,
+            sessionsDir,
+        }),
+        sendViaMailbox,
+    };
+    // ── executor: the three transport hands, each pre-bound ───────────────────
+    const executor = {
+        sendControl: (plan, lock) => executeControlSocketSend(plan, lock, controlSendDeps),
+        resumeSpawnBg: (plan, lock) => executeSpawnBgResume(plan, lock, 
+        // QB3: inject the shared lockDir-bound `release` — never the spawn factory's
+        // default releaseFn (which would release into the DEFAULT lock dir).
+        makeProductionSpawnBgResumeDeps({
+            ...io.spawnOverrides,
+            killGraceMs: opts.killGraceMs ?? io.spawnOverrides.killGraceMs,
+            releaseFn: release,
+        })),
+        sendMailbox: (plan, _lock) => sendViaMailbox(plan, _lock),
+    };
+    return {
+        decide: (input) => decideDispatch(input, deciderDeps),
+        executor,
+    };
+}

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

@@ -0,0 +1,108 @@
+/**
+ * entwurf-v2-release — the PURE release-policy reducer for the 5c transport hand
+ * (0.11 Stage 0 step 5c-1). It answers ONE question with zero IO: given the plan
+ * the 5b decider chose and the lock it handed over, on WHICH execution event may
+ * the transport hand release that lock — and it guarantees the release fires
+ * AT MOST ONCE.
+ *
+ * Why a pure reducer before any transport IO (5b discipline = gate-first →
+ * pure-before-IO → wire): the load-bearing risk of 5c is NOT the spawn/send IO, it
+ * is the RELEASE TIMING (Fable 3, "release-after-observation"). A spawn-bg dispatch
+ * that releases its lock too early — on spawn-started/ack instead of on an observed
+ * liveness transition — reopens the exact double-spawn window 5a's per-gid lock
+ * exists to close. So the timing logic is isolated here as a pure state machine the
+ * gate drives over every event order, and 5c-2/5c-3/5c-4 only WIRE the real
+ * send/spawn/mailbox IO onto it. The hand feeds events; this module decides release.
+ *
+ * The three policies (one per ExecutionPlan transport):
+ *   - no-lock                       — meta-mailbox (？7: no lock was ever held).
+ *     Nothing to release on any event.
+ *   - release-after-send-final      — control-socket send. The lock is held only for
+ *     the at-most-once re-resolve; release once the send reaches a FINAL outcome.
+ *   - release-after-spawn-observation — spawn-bg resume. The lock is held until the
+ *     FIRST observable transition: socket-alive OR child-exited (any code). A
+ *     spawn-started event is explicitly NOT a release trigger (that is the whole
+ *     point). A spawn that never started (spawn-start-failed) has no child to watch,
+ *     so it releases to free the gid — keeping the lock would pin it forever.
+ *
+ * The release authority is ALWAYS the LockClaim the decider handed over (5c wires it
+ * through). This module never re-derives a lock by gid, never re-resolves a path —
+ * it is pure routing logic over opaque events.
+ */
+export function initialReleaseState() {
+    return { released: false };
+}
+/**
+ * An in-domain execute (control-socket / spawn-bg) must hold a lock whose gardenId
+ * IS the plan's target. Both halves are 5b decider-contract invariants, not runtime
+ * conditions: a null lock or a lock paired with the WRONG plan are the same grade of
+ * mis-wiring (a later release would free nothing, or free a DIFFERENT gid's lock), so
+ * both fail loud here rather than silently mis-releasing. Asserts the lock non-null
+ * so the caller may use it as a `LockClaim`.
+ */
+function assertInDomainLock(plan, lock) {
+    if (lock === null) {
+        throw new Error(`entwurf-v2-release: an in-domain (${plan.transport}) execute must hold a lock.`);
+    }
+    if (lock.gardenId !== plan.targetGardenId) {
+        throw new Error(`entwurf-v2-release: lock gardenId (${lock.gardenId}) does not match plan target (${plan.targetGardenId}) — mis-paired plan/lock.`);
+    }
+}
+/**
+ * Derive the release policy from the plan, cross-checking the lock invariants the 5b
+ * decider guarantees: meta-mailbox ⇒ lock null (？7); in-domain (control-socket /
+ * spawn-bg) ⇒ lock non-null AND lock.gardenId === plan.targetGardenId. A mismatch is
+ * a decider contract violation, not a runtime condition — it throws so a mis-wired
+ * hand fails loud instead of silently dropping or mis-releasing a lock.
+ */
+export function decideReleasePolicy(plan, lock) {
+    switch (plan.transport) {
+        case "meta-mailbox":
+            if (lock !== null) {
+                throw new Error("entwurf-v2-release: a meta-mailbox plan must carry no lock (？7 invariant violated).");
+            }
+            return { kind: "no-lock" };
+        case "control-socket":
+            assertInDomainLock(plan, lock);
+            return { kind: "release-after-send-final" };
+        case "spawn-bg":
+            assertInDomainLock(plan, lock);
+            return { kind: "release-after-spawn-observation" };
+    }
+}
+/**
+ * Fold one execution event into the release decision. `shouldRelease` is true
+ * EXACTLY ONCE — on the first event that satisfies the policy's release condition;
+ * every later event (after `state.released`) returns false. The single-release
+ * guarantee is what lets the spawn watcher race socket-alive against child-exit
+ * without a double release: whichever fires first releases, the other is a no-op.
+ */
+export function reduceRelease(policy, state, event) {
+    if (state.released) {
+        return { state, shouldRelease: false };
+    }
+    const release = () => ({ state: { released: true }, shouldRelease: true });
+    const hold = () => ({ state, shouldRelease: false });
+    switch (policy.kind) {
+        case "no-lock":
+            // No lock was ever held → nothing to release on any event.
+            return hold();
+        case "release-after-send-final":
+            // Release once the send reaches a final outcome; hold before that.
+            return event.kind === "send-final" ? release() : hold();
+        case "release-after-spawn-observation":
+            // Fable 3: spawn-started is NOT a release event. Release on the first
+            // observed transition (socket-alive / child-exited, any code), or on a
+            // failed start (no child to watch).
+            switch (event.kind) {
+                case "socket-alive":
+                case "child-exited":
+                case "spawn-start-failed":
+                    return release();
+                case "spawn-started":
+                case "send-final":
+                case "mailbox-enqueued":
+                    return hold();
+            }
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * entwurf-v2-resume-marker — the single source of truth for the env var name that a v2
+ * spawn-bg resume plants on its resume child to authorize it as an Entwurf-child resident.
+ *
+ * Why its own leaf module (no imports): the PRODUCER is `entwurf-v2-spawn-production.ts` (a
+ * lib module that imports siblings with `.ts` extensions, compiled by `scripts/tsconfig.json`
+ * with `allowImportingTsExtensions`), but the CONSUMER is `entwurf-control.ts` (the extension
+ * entry, compiled by the ROOT tsconfig WITHOUT that flag, importing siblings as `.js`).
+ * Importing the const straight from `entwurf-v2-spawn-production.ts` into `entwurf-control.ts`
+ * would drag the whole `.ts`-importing v2 decider/spawn subtree into the root program and
+ * trip TS5097 on every `.ts` extension. A zero-import leaf const is root-safe from either side.
+ *
+ * Meaning: when this env var equals the child's own sessionId, the child is the resume citizen
+ * a v2 spawn-bg resume promoted from a dormant `entwurf`-tagged session to a live
+ * `--entwurf-control` resident (an AUTHORIZED Entwurf child resident — keeps its `entwurf` tag,
+ * stays re-resumable once it dies). A human hand-opening the same session with
+ * `--entwurf-control` carries no marker → still a "corrupt resident session name" crash. The
+ * marker is sessionId-bound (not a generic boolean) so it authorizes only the exact session it
+ * was minted for; it is a wrong-surface crash guard, not a security boundary. See
+ * `entwurf-control.ts` `maybeSetResidentName` (consumer) and `entwurf-v2-spawn-production.ts`
+ * `makeProductionSpawnBgResumeDeps` (producer).
+ */
+export const V2_RESUME_RESIDENT_SESSION_ENV = "ENTWURF_V2_RESUME_RESIDENT_SESSION_ID";
+/**
+ * True when this process is the resume child a v2 spawn-bg resume launched for EXACTLY
+ * `sessionId` — the marker equals the child's own id. The pure SSOT of the authorization
+ * check (`env` is injectable so the guard is gate-provable without touching `process.env`).
+ * The binding is to the exact id, not a generic boolean: a present-but-different marker is
+ * NOT authorized, so the env var cannot be reused to wave a different session past the guard.
+ */
+export function isV2ResumeResidentAuthorized(sessionId, env = process.env) {
+    return env[V2_RESUME_RESIDENT_SESSION_ENV] === sessionId;
+}

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

@@ -0,0 +1,116 @@
+/**
+ * entwurf-v2-runner — the pure EXECUTE-router (5d-1, `executeDispatch`) AND the top-level
+ * decide→execute join (5d-2a, `runEntwurfV2`) for the unified `entwurf_v2` verb, both in
+ * this one file because they share the `EntwurfV2RunResult` vocabulary and neither does IO.
+ * `executeDispatch` takes a `DispatchDecision` the 5b decider ALREADY produced and routes it
+ * to the right 5c transport hand, returning ONE outcome-rich `EntwurfV2RunResult`. It performs
+ * ZERO IO of its own and makes ZERO routing decisions — `decideDispatch` chose the plan,
+ * this only DISPATCHES it. Each hand is an injected dep (the gate fakes them; 5d-2 wires
+ * the production `executeControlSocketSend` / `executeSpawnBgResume` / production
+ * `sendViaMailbox`), so the routing + result mapping is gate-provable without a socket,
+ * spawn, or timer — the same pure-before-IO, IO-via-dep discipline 5b/5c kept.
+ *
+ * Why a result type richer than the receipt: the carry-over contracts from 5c demand it.
+ *   - N3 (5c-2b): a dead-path re-resolve `rejected` carries the resolver's `rejectReason`
+ *     (dormant-fire-forget-unsupported / mailbox-undeliverable / …). The runner carries it
+ *     verbatim so the surface distinguishes "in-band refusal" from "no live route".
+ *   - N1 (5c-2a): a non-`failed` outcome whose `releaseLock` then threw is a
+ *     `SendDeliveredReleaseFailedError` — the delivery HAPPENED, the lock is dirty, a
+ *     re-send would double-deliver. The runner surfaces this as `execution-failed` with
+ *     `finalizedOutcome` + `releaseFailed` so the surface renders "delivered, lock dirty,
+ *     do NOT retry", never "send failed".
+ *   - spawn-bg `lock-retained` is a RETURNED result (fail-closed, not a throw): it rides
+ *     the `executed` branch so 5d's surface can render the retained-lock diagnostic.
+ *
+ * `retrySafe` is conservatively `false` on EVERY `execution-failed`: a thrown send is
+ * never confidently retry-safe (an `indeterminate` connect may have delivered to an
+ * alive-but-stalled socket — the exact double-delivery hazard 5c-2a refuses to gamble on).
+ * The runner never re-judges the lock — it passes `decision.lock` to the hand verbatim and
+ * lets the hand's `decideReleasePolicy` fail loud on a mis-pairing.
+ */
+import { SendDeliveredReleaseFailedError, } from "./entwurf-v2-send.js";
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Route an already-decided `DispatchDecision` to its transport hand. The decider owns the
+ * routing; this owns ONLY the dispatch + the outcome→result mapping (incl. the N1/N3
+ * carry-overs). A `reject` runs no hand. An `execute` switches on `plan.transport`.
+ */
+export async function executeDispatch(decision, deps) {
+    if (decision.kind === "reject") {
+        return { kind: "rejected", receipt: decision.receipt, diagnostic: decision.diagnostic };
+    }
+    const { receipt, plan, lock } = decision;
+    const transport = plan.transport;
+    switch (plan.transport) {
+        case "control-socket": {
+            try {
+                const r = await deps.sendControl(plan, lock);
+                return {
+                    kind: "executed",
+                    receipt,
+                    transport,
+                    outcome: { transport: "control-socket", outcome: r.outcome, rejectReason: r.rejectReason },
+                };
+            }
+            catch (err) {
+                // N1: a delivered/refused send whose release then threw — lock dirty, do NOT retry.
+                if (err instanceof SendDeliveredReleaseFailedError) {
+                    return {
+                        kind: "execution-failed",
+                        receipt,
+                        transport,
+                        error: errorMessage(err),
+                        finalizedOutcome: err.finalizedOutcome,
+                        releaseFailed: true,
+                        retrySafe: false,
+                    };
+                }
+                // A `failed` send rethrows its original transport error (lock already released).
+                return { kind: "execution-failed", receipt, transport, error: errorMessage(err), retrySafe: false };
+            }
+        }
+        case "spawn-bg": {
+            try {
+                // `lock-retained` is a RETURNED result (fail-closed), not a throw — it rides `executed`.
+                const result = await deps.resumeSpawnBg(plan, lock);
+                return { kind: "executed", receipt, transport, outcome: { transport: "spawn-bg", result } };
+            }
+            catch (err) {
+                return { kind: "execution-failed", receipt, transport, error: errorMessage(err), retrySafe: false };
+            }
+        }
+        case "meta-mailbox": {
+            try {
+                // lock is null here (？7) — passed verbatim; the production adapter ignores it.
+                const r = await deps.sendMailbox(plan, lock);
+                // 5c-4 contract: a mailbox enqueue is `{success:true}` OR a throw — there is NO
+                // in-band reject (no live receiver to refuse). A `success:false` is therefore a
+                // CONTRACT VIOLATION, not a soft failure: fail loud rather than silently render it
+                // as a success ("Never warn. Throw."). The catch below folds it to execution-failed.
+                if (r.success !== true) {
+                    throw new Error("entwurf-v2-runner: meta-mailbox send returned success:false (contract violation; a mailbox has no in-band reject).");
+                }
+                return { kind: "executed", receipt, transport, outcome: { transport: "meta-mailbox", success: true } };
+            }
+            catch (err) {
+                return { kind: "execution-failed", receipt, transport, error: errorMessage(err), retrySafe: false };
+            }
+        }
+    }
+}
+/**
+ * The top-level `entwurf_v2` runner: decide → execute, joined. It runs the injected
+ * decider to a `DispatchDecision`, then routes that decision through `executeDispatch`.
+ * That is the WHOLE body — there is no extra branching, lock re-judgement, or transport
+ * decision here (the decider owns routing, `executeDispatch` owns dispatch + the N1/N3
+ * result mapping). A `decide` THROW PROPAGATES untouched: a decision was never produced,
+ * so there is no receipt to wrap and no `EntwurfV2RunResult` to honestly return — the 5d-3
+ * surface top-level catch renders it. A reject/execute decision flows straight into
+ * `executeDispatch`, whose `EntwurfV2RunResult` is returned verbatim.
+ */
+export async function runEntwurfV2(input, deps) {
+    const decision = await deps.decide(input);
+    return executeDispatch(decision, deps.executor);
+}