@junghanacs/entwurf 0.13.1 → 0.14.1

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

@@ -0,0 +1,256 @@
+/**
+ * entwurf-v2-visible-resume — stand a dormant pi citizen back up in a window the operator can
+ * see, under the same garden id, and say only what was actually observed.
+ *
+ * ── Where this sits ──
+ *
+ *   surface (entwurf-control.ts · mcp bridge index.ts)   composition root: supplies `launch`
+ *     └─ entwurf-v2-visible-resume  (this file)          v2 leaves ONLY: lock, record, socket
+ *          └─ deps.launch(argv, cwd)  ── INJECTED SEAM ──→ mux-resume-call → placement leaf
+ *
+ * The seam is what keeps `docs/mux-launch-rail.md` §11 intact in both directions: v2 never
+ * imports mux, mux never imports entwurf core. This module cannot open a window; it can only
+ * ask whoever wired it to. That is deliberate — it means the delivery fence stays exactly where
+ * `check-mux-launch` scans for it.
+ *
+ * ── Why a resume is structurally SMALLER than a fresh call on identity, and LARGER on the lock ──
+ *
+ * `mux-fresh-call` mints no identity: the sibling calls back and its envelope IS the address.
+ * A resume already knows the address — that is what "same-id" means — so there is no nonce, no
+ * callback, and no correlation receipt. What it gains instead is the lock: two visible resumes
+ * of one garden id would put two processes on one transcript, and `entwurf_v2`'s in-domain
+ * dispatch takes the SAME per-gid lock, so a resume and a live send serialise against each other
+ * for free. The lock is consistency, not defence — there is no watcher behind it.
+ *
+ * ── The observation is a startup wait, not supervision ──
+ *
+ * Measured 2026-08-06: the resumed control socket appeared ~2s (ACP) and ~4s (native) after the
+ * window opened. A single immediate probe would therefore have observed `dead` and reported a
+ * successful resume as unobserved. So the observation is ONE bounded operation with a short
+ * interval, and everything that would make it supervision is deliberately absent:
+ *
+ *   - no relaunch, ever. A refused or dead launch is a result, not a retry trigger.
+ *   - no pane watcher. Until the deadline this module looks at ONE thing: the socket.
+ *   - no env knob on the timeout. A tunable would make "unobserved" mean different things on
+ *     different hosts, and the receipt would stop being comparable.
+ *
+ * On timeout the lock is RELEASED and the window is LEFT OPEN. That is the same rule fresh-call
+ * already ships ("a launch with no callback is a real outcome"): the window is visible, the
+ * operator can look, and a retained lock on a visible artifact is the worse failure — it would
+ * have to be cleared by hand on every slow host.
+ *
+ * ── Two receipts, never merged ──
+ *
+ * `launch` says tmux made a window and was asked to start pi. `observation` says whether the
+ * citizen's socket came back under the same id. Neither says the resumed citizen did anything:
+ * a resume runs no turn (measured — the transcript stayed byte-identical), so there is no turn
+ * outcome for this module to claim.
+ */
+import { buildResumePiArgs } from "./entwurf-resume-args.js";
+import { ENTWURF_V2_LOCK_DIR, acquireLock as realAcquireLock, releaseLock as realReleaseLock, } from "./entwurf-v2-lock.js";
+import { ResumeBackendUnsupportedError, resolveResumeLaunchIdentity, } from "./resume-launch-identity.js";
+import { isValidSessionId } from "./session-id.js";
+import { CONTROL_SOCKET_DIR, inspectTargetControlSocket, mapInspectionToLiveness, } from "./socket-discovery.js";
+import { probeSocketLiveness } from "./socket-probe.js";
+/** How long ONE observation operation waits for the resumed citizen's socket. Fixed on purpose:
+ * see the module header on why this is not an env knob. */
+export const RESUME_OBSERVE_TIMEOUT_MS = 30_000;
+/** How often that one operation re-inspects. Short enough that a 2s startup is reported as the
+ * success it is, long enough that a 30s wait is ~60 lstats and not a spin. */
+export const RESUME_OBSERVE_INTERVAL_MS = 500;
+/** Production wiring for everything except the launch seam — the surface owns that, because it
+ * is the only layer allowed to know both halves. */
+export function makeVisibleResumeDeps(launch, overrides = {}) {
+    return {
+        acquireLock: (gid) => realAcquireLock(gid, { dir: ENTWURF_V2_LOCK_DIR }),
+        releaseLock: (claim) => realReleaseLock(claim, { dir: ENTWURF_V2_LOCK_DIR }),
+        resolveIdentity: resolveResumeLaunchIdentity,
+        inspectSocket: (gid) => inspectTargetControlSocket(gid, CONTROL_SOCKET_DIR),
+        probeSocket: (socketPath) => probeSocketLiveness(socketPath),
+        launch,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        ...overrides,
+    };
+}
+/**
+ * Reopen `targetGardenId` in a visible window.
+ *
+ * Order is the safety argument. The lock is taken FIRST, before the liveness question, so the
+ * answer cannot change under us between reading it and acting on it — a competing resume would
+ * otherwise pass its own `dead` check while ours was launching. Identity is resolved under that
+ * lock and BEFORE any window opens, so a citizen with no transcript (measured: a pi that never
+ * took a turn has a socket and a record but no transcriptPath) fails loud with its own cause and
+ * leaves nothing behind.
+ */
+export async function visibleResume(targetGardenId, deps) {
+    // The address grammar is `session-id.js`'s, not a local copy. The socket filename, the lock
+    // path and the record key are all keyed on that SAME id, so a second regex here could drift
+    // into accepting an id one of those three would reject — and this value becomes a lock path
+    // and a socket path a few lines down.
+    if (!isValidSessionId(targetGardenId)) {
+        return {
+            ok: false,
+            reason: "target-invalid",
+            detail: `${JSON.stringify(targetGardenId)} is not a garden id (YYYYMMDDTHHMMSS-xxxxxx)`,
+        };
+    }
+    const acquired = deps.acquireLock(targetGardenId);
+    if (!acquired.ok) {
+        return { ok: false, reason: "target-locked", detail: acquired.conflict.detail };
+    }
+    const claim = acquired.claim;
+    let released = false;
+    /** Release exactly once, and never let a failed release read as success. A lock this module
+     * took and could not give back is a fact the operator has to know about — the next resume or
+     * send against that citizen will be refused, and silence would send them looking at the wrong
+     * layer. */
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        const outcome = deps.releaseLock(claim);
+        if (outcome !== "released") {
+            throw new Error(`entwurf-v2-visible-resume: attempted to release the lock for ${targetGardenId}; the release returned ` +
+                `"${outcome}" instead of "released" (${claim.lockPath}) — the per-gid lock may still be held; clear ` +
+                `it by hand before resuming or dispatching to that citizen again.`);
+        }
+    };
+    try {
+        // Record authority, under the lock, before any window. Every failure here is a cause-rich
+        // throw from the leaf (foreign transcript, relative or deleted session file, no recorded
+        // model, unresolvable bridge) and is deliberately NOT re-typed into a reject — with ONE
+        // exception, matched on the error's own `reason` FIELD rather than its wording: a citizen
+        // of a backend that has no same-id resume. That is a capability boundary, not a defect, so
+        // it is a named refusal. The record is not read a second time to ask which backend it was;
+        // the error already carries it.
+        let identity;
+        try {
+            identity = deps.resolveIdentity(targetGardenId);
+        }
+        catch (err) {
+            if (err instanceof ResumeBackendUnsupportedError) {
+                return {
+                    ok: false,
+                    reason: err.reason,
+                    detail: `${targetGardenId} is a ${err.backend} citizen; only pi citizens stand a control socket up, ` +
+                        `so only they can be reopened under the same garden id`,
+                };
+            }
+            throw err;
+        }
+        // Liveness preflight, still under the lock. A live citizen is addressed with
+        // `entwurf_v2 fire-and-forget`, not reopened — and refusing here is also what stops two
+        // windows existing for one garden id.
+        const inspection = await deps.inspectSocket(targetGardenId);
+        const mapped = await mapInspectionToLiveness(inspection, deps.probeSocket);
+        if ("addressConflict" in mapped) {
+            return {
+                ok: false,
+                reason: "target-address-conflict",
+                detail: `the control-socket path for ${targetGardenId} is a symlink or not a socket — that address is ` +
+                    `corrupt, and resuming would stand a citizen up behind it`,
+            };
+        }
+        if (mapped.liveness === "alive") {
+            return {
+                ok: false,
+                reason: "target-live",
+                detail: `${targetGardenId} is already live at ${mapped.socketPath} — send to it with entwurf_v2 fire-and-forget instead`,
+            };
+        }
+        if (mapped.liveness === "indeterminate") {
+            return {
+                ok: false,
+                reason: "target-indeterminate",
+                detail: `the control-socket probe for ${targetGardenId} was inconclusive — it is not provably dormant, ` +
+                    `and resuming a citizen that is actually running would put two processes on one transcript`,
+            };
+        }
+        const runtimeArgs = buildResumePiArgs({
+            sessionFile: identity.sessionFile,
+            explicitExtensionArgs: identity.explicitExtensionArgs,
+            provider: identity.provider,
+            model: identity.model,
+        });
+        const launched = deps.launch({ cwd: identity.cwd, runtimeArgs });
+        if (!launched.ok) {
+            return { ok: false, reason: "launch-refused", detail: `${launched.reason} — ${launched.hint}` };
+        }
+        const observation = await observeSameGidSocket(targetGardenId, mapped.socketPath, deps);
+        return {
+            ok: true,
+            launch: { targetGardenId, sessionFile: identity.sessionFile, handle: launched.handle },
+            observation,
+        };
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * ONE bounded operation: wait for the SAME garden id's control socket to answer. Alive is the
+ * only early exit — an inspection that comes back absent, corrupt or inconclusive during startup
+ * is a normal intermediate state, not a verdict, so it is simply not-yet.
+ */
+export async function observeSameGidSocket(targetGardenId, socketPath, deps, timeoutMs = RESUME_OBSERVE_TIMEOUT_MS, intervalMs = RESUME_OBSERVE_INTERVAL_MS) {
+    const started = deps.now();
+    for (;;) {
+        const inspection = await deps.inspectSocket(targetGardenId);
+        const mapped = await mapInspectionToLiveness(inspection, deps.probeSocket);
+        if (!("addressConflict" in mapped) && mapped.liveness === "alive") {
+            return { kind: "socket-alive", socketPath: mapped.socketPath, waitedMs: deps.now() - started };
+        }
+        if (deps.now() - started >= timeoutMs) {
+            return { kind: "resume-unobserved", socketPath, waitedMs: deps.now() - started };
+        }
+        await deps.sleep(intervalMs);
+    }
+}
+const REJECT_HINT = {
+    "target-invalid": "no citizen has that id; discover targets with entwurf_peers",
+    "target-not-pi": "that citizen's backend has no same-id resume — reach it with entwurf_v2, or open a fresh sibling",
+    "target-locked": "another resume or dispatch holds this citizen's lock right now",
+    "target-live": "that citizen is already running — this verb only reopens dormant ones",
+    "target-indeterminate": "the socket probe could not prove the citizen is dormant, so nothing was started",
+    "target-address-conflict": "that citizen's control-socket path is corrupt",
+    "launch-refused": "tmux was never asked to open a window",
+};
+/**
+ * ONE renderer for both surfaces — the same reason `mux-fresh-call` has one: the two
+ * registrations are separate literals, and a shared renderer is what keeps the operator-visible
+ * answer from drifting apart between native pi and the MCP bridge.
+ *
+ * The success text keeps the two receipts visibly apart, including in the good case. A reader
+ * who sees "window opened" and "socket alive" as one sentence has been told the resume worked;
+ * a reader who sees them as two facts can tell which one is missing when only one is there.
+ */
+export function renderVisibleResume(result) {
+    if (!result.ok) {
+        return {
+            text: `entwurf_resume_call rejected: ${result.reason} — ${REJECT_HINT[result.reason]}. ` +
+                `${result.detail}. No window was opened.`,
+            isError: true,
+        };
+    }
+    const h = result.launch.handle;
+    const observed = result.observation.kind === "socket-alive";
+    return {
+        text: `[entwurf resume call ↻]\n` +
+            `  target:   ${result.launch.targetGardenId}\n` +
+            `  session:  ${result.launch.sessionFile}\n` +
+            `  runtime:  ${h.runtimePath} (requested start cwd ${h.cwd})\n` +
+            `  window:   ${h.windowId} (index ${h.windowIndex}) in session ${h.sessionId}\n` +
+            `  pane:     ${h.paneId} pid ${h.panePid}\n` +
+            `\n` +
+            `LAUNCH receipt: tmux created that window and was asked to start pi on the transcript above.\n` +
+            (observed
+                ? `OBSERVATION receipt: the control socket for ${result.launch.targetGardenId} answered after ` +
+                    `${result.observation.waitedMs}ms — that citizen is addressable again, and entwurf_v2 fire-and-forget ` +
+                    `now reaches it. No turn was run by this call.`
+                : `OBSERVATION receipt: resume-unobserved — the control socket did not answer within ` +
+                    `${result.observation.waitedMs}ms. The window is open and visible; read it directly. The lock was ` +
+                    `released, nothing was retried, and nothing was killed.`),
+        isError: false,
+    };
+}

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

@@ -411,7 +411,7 @@ export function parseMetaIdentity(json) {
 // `wakeMode` describes the last centimetre, not citizen rank. The control-socket
 // adapter injects the body into a pi turn, so backend `pi` is `direct-inject`;
 // Claude's mailbox is `self-fetch`; native-push adapters are direct injection.
-// Dormant spawn-bg resume is a separate transport/ownership decision and does not
+// Resuming a dormant citizen is a separate lifecycle capability and does not
 // turn the pi record into a mailbox citizen.
 // ---------------------------------------------------------------------------
 /** Bump only on a breaking capability-registry shape change; the parser refuses other versions. */
@@ -890,6 +890,21 @@ export function listAllMetaIdentities(entries, readRecord, opts = {}) {
     errors.sort((a, b) => (a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0));
     return { identities, errors };
 }
+/**
+ * The fs-bound listing — the same binding shape {@link certifyActiveStoreDir} gives the
+ * certification: one resolved dir, kind-carrying entries, the fd-guarded record reader.
+ * Exists so an in-repo facts surface (`meta-facts`, #65) reuses THE listing contract
+ * instead of re-binding readdir/read by hand — the exact drift that made external
+ * consumers carry a decaying copy of the certification. No semantics of its own:
+ * everything it returns is {@link listAllMetaIdentities} over the real store.
+ */
+export function listAllMetaIdentitiesDir(dir) {
+    const resolved = path.resolve(expandTilde(dir));
+    return {
+        dir: resolved,
+        ...listAllMetaIdentities(readActiveStoreEntries(resolved), makeStoreRecordReader(resolved)),
+    };
+}
 /**
  * The pure core of the `upsert` CLI (3D-4; v3 identity since the #50 cut). Keyed
  * on RECORD EXISTENCE, never on a backend `source` field:
@@ -1423,8 +1438,13 @@ export function readMetaReceiverMarker(opts) {
  * A narrower scan is not a smaller version of this: asking only about MY
  * `nativeSessionId` writes happily beside a drifted or duplicated record that the
  * doctor refuses, which is how a host ends up certified by one surface and not
- * the other. The write is tmp-file + rename so a crash never leaves a
- * half-written record (#30 crash-safety).
+ * the other.
+ *
+ * The write is split by ACTION (#66): ATTACH rewrites its OWN record atomically
+ * in place (tmp + rename, #30 crash-safety); CREATE publishes exclusively
+ * (tmp + link) and fails loud if the minted garden id's final path already
+ * exists — certification cannot see a future minted gid, so replacement-free
+ * publish is the only collision safety a create has.
  */
 export function upsertMetaSession(opts) {
     const dir = path.resolve(expandTilde(opts.dir ?? defaultMetaSessionsDir()));
@@ -1436,15 +1456,81 @@ export function upsertMetaSession(opts) {
     const existing = cert.records.find((record) => record.identity.nativeSessionId === target)?.identity ?? null;
     const decision = decideUpsert(existing, opts.input, opts.now);
     const file = path.join(dir, metaRecordFilename(decision.record));
-    atomicWriteIdentity(file, decision.record);
+    if (decision.action === "create")
+        publishExclusiveIdentity(file, decision.record);
+    else
+        atomicWriteIdentity(file, decision.record);
     return { action: decision.action, record: decision.record, dir, path: file };
 }
-/** tmp-file + rename so a crash never leaves a half-written record (v3 identity write). */
+/**
+ * ATTACH replace primitive: tmp-file + rename so a crash never leaves a
+ * half-written record (#30 crash-safety). rename(2) REPLACES an existing final
+ * path, which is exactly right for attach (the record being rewritten is the
+ * caller's own) and exactly wrong for create — a freshly minted garden id must
+ * never land on this path (#66).
+ */
 function atomicWriteIdentity(file, identity) {
     const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
     fs.writeFileSync(tmp, serializeMetaIdentity(identity), { mode: 0o600 });
     fs.renameSync(tmp, file);
 }
+/**
+ * CREATE publish primitive: same-directory tmp + `link(2)` to the final path.
+ * link fails with EEXIST when the final path already exists — the kernel makes
+ * the existence check and the publish one atomic step, so there is no
+ * check-then-rename TOCTOU window and a same-second 24-bit garden-id suffix
+ * collision can never silently replace whatever already holds the final path
+ * (#66). The occupied entry's bytes are untouched on refusal; tmp cleanup is
+ * attempted on every path, and a published-with-residue state fails loud.
+ *
+ * @internal Exported only as the production subject for the meta-session gate's
+ * deterministic collision oracle (the minted suffix is random, so the public
+ * upsert seam cannot force a collision deterministically). Not an
+ * operator/package API.
+ */
+export function publishExclusiveIdentity(file, identity) {
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, serializeMetaIdentity(identity), { mode: 0o600 });
+    try {
+        fs.linkSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch (cleanupErr) {
+            // The primary link error stays the truth of this publish; a cleanup errno
+            // never masks it. ENOENT is silent (no residue = desired state); any other
+            // cleanup failure is an operator diagnostic on stderr, then the primary throws.
+            if (cleanupErr.code !== "ENOENT") {
+                process.stderr.write(`[meta-session] tmp cleanup after a failed CREATE publish also failed (${tmp}): ` +
+                    `${cleanupErr.message}\n`);
+            }
+        }
+        if (err.code === "EEXIST") {
+            throw new MetaRecordError(`meta-record CREATE collision: garden id "${identity.gardenId}" already has an entry at ` +
+                `${file}. Exclusive publish refused to replace it — the occupied final-path entry was ` +
+                `not modified and no ACTIVE record was published for nativeSessionId ` +
+                `"${identity.nativeSessionId}".`);
+        }
+        throw err;
+    }
+    try {
+        fs.unlinkSync(tmp);
+    }
+    catch (err) {
+        // ENOENT is the goal state, not a failure: the record is published and no
+        // tmp remains, so there is nothing left to clean.
+        if (err.code === "ENOENT")
+            return;
+        // Never roll the final back: the record IS published (link succeeded).
+        throw new MetaRecordError(`meta-record CREATE for garden id "${identity.gardenId}" is already published at ${file}, ` +
+            `but temp cleanup failed (${tmp}): ${err.message}. The caller aborts here, so ` +
+            `it received no successful birth/registration receipt; remove the temp file and retry — ` +
+            `a retry with the same nativeSessionId will ATTACH to the published record, not mint a ` +
+            `second identity.`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Mailbox delivery (step 6) — addressed by GARDEN ID. The record store is the
 // authority (a sender may only deliver to a known garden citizen); the mailbox