@junghanacs/entwurf 0.12.0 → 0.12.2

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

@@ -0,0 +1,216 @@
+/**
+ * entwurf-v2-spawn — the 5c-3a spawn-bg RESUME watcher hand (0.11 Stage 0 step 5c-3a).
+ * It WIRES the real spawn + socket-observe IO onto the pure release reducer (5c-1):
+ * launch the resume child, watch for the FIRST observable liveness transition, feed
+ * that observation to `reduceRelease`, and release the held lock EXACTLY ONCE — or, if
+ * NO observation can be obtained, RETAIN the lock and surface the evidence rather than
+ * release blind. Every IO seam is an injected dep (the gate fakes it with controlled
+ * promises), so the spawn→observe→release ORDERING is gate-provable without a real
+ * child, socket, or timer — the same "pure-before-IO, IO-via-dep" discipline 5b/5c-2
+ * used.
+ *
+ * The load-bearing contract (Fable 3, the whole reason 5c is sliced pure-before-IO):
+ *   TIMEOUT IS NOT A RELEASE EVENT. A spawn-bg dispatch holds its per-gid lock until an
+ *   OBSERVED transition — `socket-alive` (the resumed child stood its control socket up)
+ *   or `child-exited` (any code, incl. null = killed by signal). A bare `observeTimeoutMs`
+ *   expiry proves NOTHING (the child may stand its socket up a moment later), so releasing
+ *   on it would reopen the exact double-spawn window 5a's lock exists to close. Instead the
+ *   timeout RESOLVES BY OBSERVATION: kill the child, then wait a BOUNDED `killGraceMs` for
+ *   the kill to produce a real `child-exited` (or a racing `socket-alive`). Only THAT
+ *   observation releases. If even the grace elapses with no observation, the hand does NOT
+ *   release — it returns a `lock-retained` diagnostic (released:false, with pid / socket /
+ *   lockPath / timeouts) so an operator can SEE the long-held lock, exactly as F2-P2
+ *   ("관측 가능해야 수용") demands. The function always returns BOUNDED — it never hangs.
+ *
+ * Post-spawn unexpected dep failure follows the SAME rule (GPT 5c-3a correction): once a
+ * child exists, an observation-less release is forbidden. A watch/timer/kill dep that
+ * throws is handled by best-effort kill → bounded attempt to OBSERVE the exit → release
+ * if observed, else `lock-retained` fail-closed. There is NO direct-release escape hatch:
+ * `deps.releaseLock` is reached ONLY through `reduceRelease` on a real observation event.
+ *
+ * Release authority is ALWAYS the LockClaim the decider handed over; the watcher reads
+ * ONLY `plan.expectedSocketPath` and never re-derives a socket path or a lock by gid.
+ */
+import { decideReleasePolicy, initialReleaseState, reduceRelease, } from "./entwurf-v2-release.js";
+function tagSocket(p) {
+    return p.then(() => ({ tag: "socket" }));
+}
+function tagExit(p) {
+    return p.then((code) => ({ tag: "exit", code }));
+}
+function tagTimeout(p) {
+    return p.then(() => ({ tag: "timeout" }));
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Swallow a watcher promise's eventual rejection when it is abandoned without a race
+ * handler (the S1 sync-throw path tears down before the race attaches one), so an aborted
+ * loser cannot surface as an unhandledRejection. A no-op when the promise never started. */
+function defuse(p) {
+    if (p)
+        void p.catch(() => { });
+}
+/**
+ * Launch a spawn-bg resume child and watch for the first observable liveness transition,
+ * releasing the held lock EXACTLY ONCE on that observation — or RETAINING the lock (with
+ * surfaced evidence) if no observation can be obtained. `lock` MUST be the in-domain claim
+ * the decider handed over — `decideReleasePolicy` throws if it is null or paired with the
+ * wrong gid (a mis-wire is fail-loud, not a runtime branch). Always returns bounded.
+ *
+ * A `releaseLock` throw on a RELEASED path propagates honestly (the observation already
+ * happened, so the caller must NOT re-spawn; the lock is dirty and needs manual cleanup —
+ * 5b masking direction). Such a throw is the ONE non-result exit; every other terminal
+ * state is a returned `SpawnBgResumeResult`.
+ */
+export async function executeSpawnBgResume(plan, lock, deps) {
+    // Throws on a null / mis-paired lock (？7 + gid invariants). After this the spawn-bg
+    // policy is release-after-spawn-observation and the lock is non-null.
+    const policy = decideReleasePolicy(plan, lock);
+    const held = lock;
+    let state = initialReleaseState();
+    // The ONLY path to deps.releaseLock: fold a real observation event through the reducer
+    // and release iff (and exactly once) the reducer says so. No direct-release hatch.
+    const fire = (event) => {
+        const r = reduceRelease(policy, state, event);
+        state = r.state;
+        if (r.shouldRelease)
+            deps.releaseLock(held);
+    };
+    // Spawn. A throw here means NO child exists → spawn-start-failed releases (nothing to
+    // watch; keeping the lock would pin the gid forever). No child means no lock-leak risk.
+    let child;
+    try {
+        child = await deps.spawnChild(plan);
+    }
+    catch (err) {
+        fire({ kind: "spawn-start-failed", error: errMsg(err) });
+        return { kind: "spawn-start-failed", released: true, error: errMsg(err) };
+    }
+    const controller = new AbortController();
+    const { signal } = controller;
+    // Created ONCE and reused across the primary race and the kill-grace race; in the
+    // timeout branch both are still pending (timeout won), so re-racing them is safe.
+    //
+    // S1 (Fable 2차): the creation is in its OWN try because a watch dep can throw
+    // SYNCHRONOUSLY (a buggy dep that throws where it must RETURN a Promise — the same grade
+    // the send hand's case-13 backstop covers). The child already exists, so this is a
+    // post-spawn failure and the SAME rule applies: an observation-less release is forbidden.
+    // Best-effort kill, defuse any watcher that DID start (so its later rejection is not
+    // unhandled), tear down, and fail-closed to a retained diagnostic. We do NOT try to
+    // observe the exit — awaitChildExit may itself be the thrower; retained is the honest
+    // floor. (The async-rejection path is handled later by the race catch → backstop.)
+    let socketP;
+    let exitP;
+    try {
+        socketP = tagSocket(deps.awaitSocketAlive(plan.expectedSocketPath, signal));
+        exitP = tagExit(deps.awaitChildExit(child, signal));
+    }
+    catch (err) {
+        try {
+            deps.killChild(child);
+        }
+        catch {
+            // best-effort
+        }
+        controller.abort();
+        defuse(socketP);
+        defuse(exitP);
+        return retained(plan, child, "observe-failed", deps.killGraceMs, held.lockPath, errMsg(err));
+    }
+    try {
+        // Primary observation race. `timeout` participates but is NEVER a release event.
+        let first;
+        try {
+            const timeoutP = tagTimeout(deps.awaitTimeout(plan.observeTimeoutMs, signal));
+            first = await Promise.race([socketP, exitP, timeoutP]);
+        }
+        catch (err) {
+            // A watch/timer dep rejected BEFORE any observation → post-spawn backstop.
+            return await backstop(plan, deps, child, held.lockPath, exitP, signal, fire, errMsg(err));
+        }
+        if (first.tag === "socket") {
+            fire({ kind: "socket-alive" });
+            return { kind: "socket-alive", released: true, pid: child.pid };
+        }
+        if (first.tag === "exit") {
+            fire({ kind: "child-exited", code: first.code });
+            return { kind: "child-exited", released: true, exitCode: first.code, pid: child.pid };
+        }
+        // first.tag === "timeout": NOT a release. Escalate to a kill, then wait a BOUNDED
+        // grace for the kill to produce a real child-exited (or a racing socket-alive).
+        try {
+            deps.killChild(child);
+        }
+        catch {
+            // kill itself threw — still try to observe within the grace; if nothing, retain.
+        }
+        let second;
+        try {
+            const graceP = tagTimeout(deps.awaitTimeout(deps.killGraceMs, signal));
+            second = await Promise.race([socketP, exitP, graceP]);
+        }
+        catch (err) {
+            // A dep rejected during the grace → cannot confirm; retain the lock, surface it.
+            return retained(plan, child, "kill-unconfirmed", deps.killGraceMs, held.lockPath, errMsg(err));
+        }
+        if (second.tag === "socket") {
+            fire({ kind: "socket-alive" });
+            return { kind: "socket-alive", released: true, pid: child.pid };
+        }
+        if (second.tag === "exit") {
+            fire({ kind: "child-exited", code: second.code });
+            return { kind: "child-exited", released: true, exitCode: second.code, pid: child.pid };
+        }
+        // Grace elapsed with NO observation → the kill is unconfirmed. Do NOT release blind;
+        // retain the lock and surface the evidence (bounded return, never a hang).
+        return retained(plan, child, "kill-unconfirmed", deps.killGraceMs, held.lockPath, undefined);
+    }
+    finally {
+        // Tear down the losing watchers (their timers / FS watches) on every exit.
+        controller.abort();
+    }
+}
+/**
+ * Post-spawn backstop (GPT 5c-3a correction): a child exists but a watch/timer dep threw
+ * before any observation. An observation-less release is forbidden (it reopens the
+ * double-spawn window), so: best-effort kill → BOUNDED attempt to OBSERVE the exit →
+ * release iff observed, else `lock-retained` fail-closed. We race ONLY the exit (not the
+ * already-suspect socket watcher) plus a fresh grace timer.
+ */
+async function backstop(plan, deps, child, lockPath, exitP, signal, fire, originalError) {
+    try {
+        deps.killChild(child);
+    }
+    catch {
+        // best-effort
+    }
+    try {
+        const graceP = tagTimeout(deps.awaitTimeout(deps.killGraceMs, signal));
+        const obs = await Promise.race([exitP, graceP]);
+        if (obs.tag === "exit") {
+            fire({ kind: "child-exited", code: obs.code });
+            return { kind: "child-exited", released: true, exitCode: obs.code, pid: child.pid };
+        }
+    }
+    catch {
+        // exit watcher itself was the failing dep (or threw again) → fall through to retain.
+    }
+    return retained(plan, child, "observe-failed", deps.killGraceMs, lockPath, originalError);
+}
+function retained(plan, child, reason, killGraceMs, lockPath, error) {
+    return {
+        kind: "lock-retained",
+        released: false,
+        reason,
+        error,
+        diagnostic: {
+            targetGardenId: plan.targetGardenId,
+            pid: child.pid,
+            expectedSocketPath: plan.expectedSocketPath,
+            lockPath,
+            observeTimeoutMs: plan.observeTimeoutMs,
+            killGraceMs,
+        },
+    };
+}

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

@@ -0,0 +1,164 @@
+/**
+ * entwurf-v2-surface — 5d-3a: the ctx-free SURFACE adapter that joins a surface's raw params
+ * to `runEntwurfV2` and renders the outcome-rich result back to a human/tool string. It is the
+ * ONE place a surface (pi-native `entwurf_v2` tool now; the MCP `entwurf_v2` verb in 5d-3b)
+ * crosses into the v2 fence — so `entwurf-control.ts` (a root-tsc, emit-capable surface that
+ * CANNOT statically import the `.ts`-extension fence without TS5097) reaches this via a
+ * NON-LITERAL dynamic import, and the MCP bridge (already a `.ts`-import consumer) imports it
+ * directly. Either way the ctx binding stays OUT of the fence: the caller builds
+ * `senderProvider` from its own envelope source and passes it in `opts`.
+ *
+ * Three exports:
+ *   - `toDispatchInput` — surface params → `DispatchInput` (the `wants_reply`→`wantsReply`
+ *     snake→camel bridge; `intent` is REQUIRED and passed through verbatim, never inferred
+ *     from mode/action — that would blur the F1 ownership contract).
+ *   - `renderEntwurfV2Result` — the result union → `{ text, isError }`, surfacing the carry-overs
+ *     the surface must NOT drop: a reject's reason+diagnostic, a control `rejectReason` (N3), a
+ *     spawn `lock-retained` diagnostic, and the N1 delivered+lock-dirty `execution-failed`.
+ *   - `runAndRenderEntwurfV2FromSurface` — assemble production deps + run + render, so the root
+ *     surface never needs to name the `EntwurfV2RunResult` union (it only sees `{text,isError}`).
+ */
+import * as path from "node:path";
+import { makeProductionEntwurfV2Deps } from "./entwurf-v2-production.js";
+import { runEntwurfV2 } from "./entwurf-v2-runner.js";
+/** The operator-policy SSOT for v2 dispatch's preflight prefix-auto-approve roots (5d-4b).
+ * ONE shared env var feeds BOTH surfaces (pi-native + MCP) — a pi session and an MCP child
+ * both inherit it, so there is no per-surface config fork. `prefixRoots` is operator policy,
+ * not session-local UX, so it is an env var, not a pi flag. */
+export const ENTWURF_PREFIX_ROOTS_ENV = "ENTWURF_PREFIX_ROOTS";
+/** Parse `ENTWURF_PREFIX_ROOTS` into the preflight's `prefixRoots`. `path.delimiter`-
+ * separated (`:` on Linux/macOS); entries are trimmed, empty segments dropped. Unset / empty
+ * / delimiters-only ⇒ `[]` (no prefix promotion — frozen decision 7, no package default).
+ * It does NOT throw on a nonexistent/typo path: `preflight`'s normalize keeps an absolute
+ * fallback, so a bad root simply never matches (a typo must not broaden approve, and must not
+ * turn every owned-outcome dispatch into a loud failure). `~` is left for preflight to expand. */
+export function parseEntwurfPrefixRootsEnv(raw = process.env[ENTWURF_PREFIX_ROOTS_ENV]) {
+    if (!raw)
+        return [];
+    return raw
+        .split(path.delimiter)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** Surface params → the runner's `DispatchInput`. `wants_reply`→`wantsReply`; `intent` and
+ * `message` pass through; `mode`/`wantsReply` are left undefined when absent so the decider's
+ * own defaults (follow_up / false) apply — no double-default. */
+export function toDispatchInput(params) {
+    return {
+        target: params.target,
+        intent: params.intent,
+        message: params.message,
+        mode: params.mode,
+        wantsReply: params.wants_reply,
+    };
+}
+/**
+ * Detour B (B-a) — actionable rendering of an honest reject. The decider is UNCHANGED:
+ * a reject stays a reject (Hard Rule 3), and intent is NEVER auto-converted (Hard Rule 2 —
+ * owned→fire-and-forget mailbox fallback would break the F1 ownership contract). This only
+ * appends a one-line "what to do instead" to the reject TEXT, so an honest reject stops
+ * reading as "delivery impossible". Returns undefined for rejects with no useful next step.
+ */
+export function actionableRejectHint(reason) {
+    switch (reason) {
+        case "backend-liveness-unsupported":
+            // A meta-session backend (e.g. claude-code self-fetch) has no liveness predicate, so
+            // owned-outcome has nothing to own. Replies go to the mailbox via fire-and-forget.
+            return ("meta-session backend has no liveness predicate → owned-outcome is unsupported. " +
+                "To reply, dispatch with intent: fire-and-forget — it routes to the meta-mailbox when a " +
+                "deliverable/active receiver is armed (else it fail-closes as mailbox-undeliverable). " +
+                "(Intent is not auto-converted; you choose it.)");
+        case "owned-live-no-autosend":
+            // A live target is reachable, but owned-outcome is not an auto-send (Q2/F1).
+            return "target is live — owned-outcome never auto-sends. Use intent: fire-and-forget (with wants_reply if you need a reply).";
+        default:
+            return undefined;
+    }
+}
+/** Render the outcome-rich result to `{ text, isError }`. A reject or a thrown/failed/dirty
+ * delivery is `isError:true`; a sent/fallback-sent/enqueued/observed delivery is `isError:false`.
+ * A control in-band `rejected` is a non-delivery (isError:true) and carries N3 `rejectReason`
+ * when present; a spawn `lock-retained` is fail-closed (isError:true) with its diagnostic. */
+export function renderEntwurfV2Result(result) {
+    switch (result.kind) {
+        case "rejected": {
+            const r = result.receipt;
+            let text = `entwurf_v2 rejected: ${r.reason} (observed liveness: ${r.observedLiveness ?? "n/a"})`;
+            const hint = actionableRejectHint(r.reason);
+            if (hint)
+                text += `\n  → ${hint}`;
+            if (result.diagnostic?.kind === "target-locked") {
+                const c = result.diagnostic.conflict;
+                text +=
+                    `\n  target-locked: ${c.lockPath}` +
+                        `\n  ${c.detail}` +
+                        (c.holder ? `\n  holder: pid ${c.holder.pid} on ${c.holder.hostname} since ${c.holder.createdAt}` : "");
+            }
+            return { text, isError: true };
+        }
+        case "executed": {
+            const o = result.outcome;
+            if (o.transport === "control-socket") {
+                const delivered = o.outcome === "sent" || o.outcome === "fallback-sent";
+                const reason = o.rejectReason ? ` (reason: ${o.rejectReason})` : "";
+                return {
+                    text: `entwurf_v2 control-socket → ${o.outcome}${reason}`,
+                    isError: !delivered,
+                };
+            }
+            if (o.transport === "spawn-bg") {
+                const res = o.result;
+                if (res.kind === "lock-retained") {
+                    const d = res.diagnostic;
+                    return {
+                        text: `entwurf_v2 spawn-bg LOCK RETAINED (${res.reason}) — lock NOT released, operator must clear:` +
+                            `\n  target: ${d.targetGardenId}` +
+                            `\n  lockPath: ${d.lockPath}` +
+                            `\n  expectedSocketPath: ${d.expectedSocketPath}` +
+                            `\n  observeTimeoutMs: ${d.observeTimeoutMs}, killGraceMs: ${d.killGraceMs}` +
+                            (res.error ? `\n  error: ${res.error}` : ""),
+                        isError: true,
+                    };
+                }
+                if (res.kind === "spawn-start-failed") {
+                    return { text: `entwurf_v2 spawn-bg failed to start: ${res.error}`, isError: true };
+                }
+                const pid = "pid" in res && res.pid !== undefined ? ` (pid ${res.pid})` : "";
+                const exit = res.kind === "child-exited" ? ` exitCode=${res.exitCode}` : "";
+                return { text: `entwurf_v2 spawn-bg → ${res.kind}${pid}${exit}, lock released`, isError: false };
+            }
+            // meta-mailbox
+            return { text: "entwurf_v2 meta-mailbox → enqueued", isError: false };
+        }
+        case "execution-failed": {
+            if (result.releaseFailed && result.finalizedOutcome) {
+                // N1: the delivery/refusal reached a terminal outcome but releaseLock then threw.
+                return {
+                    text: `entwurf_v2 ${result.transport} DELIVERED (${result.finalizedOutcome}) but the lock is DIRTY ` +
+                        `(release failed) — do NOT retry, a re-send would double-deliver. Clear the lock by hand.` +
+                        `\n  error: ${result.error}`,
+                    isError: true,
+                };
+            }
+            return {
+                text: `entwurf_v2 ${result.transport} execution failed: ${result.error} (retry-safe: ${result.retrySafe})`,
+                isError: true,
+            };
+        }
+    }
+}
+/**
+ * Assemble production deps, run the v2 dispatch, and render the result. The root surface only
+ * ever sees `{ text, isError }` — it never names the `EntwurfV2RunResult` union — so the v2
+ * fence types stay behind this one entry point.
+ */
+export async function runAndRenderEntwurfV2FromSurface(params, opts) {
+    const prodOpts = {
+        senderProvider: opts.senderProvider,
+        agentDir: opts.agentDir,
+        // Explicit opts win (test / future surface override); otherwise the shared env SSOT.
+        prefixRoots: opts.prefixRoots ?? parseEntwurfPrefixRootsEnv(),
+    };
+    const result = await runEntwurfV2(toDispatchInput(params), makeProductionEntwurfV2Deps(prodOpts));
+    return renderEntwurfV2Result(result);
+}

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

@@ -0,0 +1,66 @@
+/**
+ * meta-mailbox-body — the SINGLE source for rendering an entwurf message as a
+ * meta-bridge mailbox body. Both transports that can deliver to a garden citizen
+ * with no live control socket use this:
+ *   - the MCP bridge entwurf_v2 (mcp/entwurf-bridge) — external/Claude-host sends
+ *   - the pi-native entwurf_v2 (pi-extensions/entwurf-control.ts) — pi-session sends
+ *
+ * The control-socket path carries the sender envelope inside its RPC framing; the
+ * mailbox path is just a file, so the envelope must be SERIALIZED INTO the body —
+ * else a receiver reading entwurf_inbox_read would not know who sent it, whether
+ * the sender is replyable (and at which sessionId), or whether a reply was wanted.
+ * The render mirrors the live "[entwurf received ⟵]" header so a transcript reads
+ * the same whether the message arrived over a socket or a mailbox.
+ *
+ * No filesystem/network IO and no mutation — the only ambient read is
+ * process.env.HOME for display abbreviation (so not strictly referentially pure,
+ * but deterministic per environment). Extracted so the two senders cannot drift
+ * in how a mailbox message presents who-sent-it — the field that round-trips
+ * garden-id replies.
+ */
+/** `~`-abbreviate a home-relative cwd for display. Reads process.env.HOME. */
+function abbreviateHome(cwd) {
+    const home = process.env.HOME;
+    if (!home)
+        return cwd;
+    if (cwd === home)
+        return "~";
+    if (cwd.startsWith(`${home}/`))
+        return `~${cwd.slice(home.length)}`;
+    return cwd;
+}
+/** Format a UTC ISO timestamp as `YYYY-MM-DD HH:MM:SS KST` (UTC+9, no DST).
+ * Returns the raw input when it does not parse. Pure. */
+function formatKstTimestamp(iso) {
+    const ms = Date.parse(iso);
+    if (Number.isNaN(ms))
+        return iso;
+    const kst = new Date(ms + 9 * 60 * 60 * 1000);
+    const pad = (n) => n.toString().padStart(2, "0");
+    return (`${kst.getUTCFullYear()}-${pad(kst.getUTCMonth() + 1)}-${pad(kst.getUTCDate())} ` +
+        `${pad(kst.getUTCHours())}:${pad(kst.getUTCMinutes())}:${pad(kst.getUTCSeconds())} KST`);
+}
+/**
+ * Render the full mailbox body: header envelope + separator + message. A
+ * replyable sender (pi-session, or a trusted meta-session) advertises its
+ * sessionId as the reply address; a non-replyable sender says so WITHOUT
+ * losing its origin — a record-backed meta-session that is currently inactive
+ * renders as `(meta-session, non-replyable)`, not degraded to `external`.
+ */
+export function formatMetaMailboxBody(sender, message, wantsReply) {
+    const replyable = sender.replyable === true;
+    const isMeta = sender.origin === "meta-session";
+    const kind = isMeta ? "meta-session, " : "";
+    const sessionLine = replyable
+        ? `${sender.sessionId} (${kind}replyable — reply via entwurf_v2 to this sessionId, intent=fire-and-forget)`
+        : isMeta
+            ? `${sender.sessionId} (meta-session, non-replyable)`
+            : `${sender.sessionId} (external, non-replyable)`;
+    return (`[entwurf received ⟵]\n` +
+        `  from:        ${sender.agentId} @ ${abbreviateHome(sender.cwd)}\n` +
+        `  session:     ${sessionLine}\n` +
+        `  at:          ${formatKstTimestamp(sender.timestamp)}\n` +
+        `  wants reply: ${wantsReply ? "yes" : "no"}\n` +
+        `────────────────────────────────────────\n` +
+        `${message}\n`);
+}