@junghanacs/entwurf 0.40.0 → 0.41.0

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

@@ -0,0 +1,149 @@
+/**
+ * entwurf-v2-retire-production — the ctx-free PRODUCTION assembly of `retireCitizen`'s deps
+ * (#147). `makeProductionRetireDeps(opts)` binds the existing owning APIs — the v2 target lock,
+ * the meta-session readers, the control-socket inspection and probe, and the two internal
+ * retire adapters — into one `RetireDispatcherDeps`. Same shape as `makeProductionEntwurfV2Deps`:
+ * leaf IO seams are overridable for tests; which closure reaches which seam is not.
+ *
+ * Wiring, not a grant. Building or holding these deps confers no permission to retire anyone.
+ * `resolveCaller` is the trusted host's own caller resolution, injected at the wiring site (the
+ * bridge's private resolver, passed through unchanged); the dispatcher uses it for attribution
+ * and the self-target refusal only. No tool, index entry or annotation is registered here.
+ *
+ * ONE path set, from two sources. The lock and control-socket directories default to
+ * module-load constants (`ENTWURF_V2_LOCK_DIR`, `CONTROL_SOCKET_DIR`, HOME-derived when their
+ * modules load); this factory does not re-derive them. The sessions, receivers and senders
+ * directories default to an environment read made ONCE, at construction. Every closure uses
+ * that one set — including the Claude Code adapter's own record / receiver / sender witnesses,
+ * whose defaults would otherwise resolve their directories again on every call and could read
+ * a different store than the dispatcher. The capture covers these five directories (and the
+ * sidecar directory derived from the sessions one) only; the runtime environment below them
+ * (the CC helper's interpreter lookup, for one) is the adapter's own and is not frozen here.
+ * The CC helper path and spawn stay the adapter's defaults.
+ *
+ * `signal` is request-scoped: build these deps for ONE retire request. It is captured once and
+ * handed both to the dispatcher's own cancellation checks and, unchanged, to the CC adapter's
+ * abort checks; it is not an approval, and the Pi rail takes none.
+ *
+ * Recording: the #106 B sidecar directory is derived ONCE from the captured sessions directory
+ * (`retirementsDirBesideSessions`), never from a sixth path or environment knob. The two record
+ * callbacks are synchronous: each mints its event (random 128-bit id, ISO UTC `at`) and appends
+ * it once through the `append` seam; the requested callback returns the id only after its append
+ * returned. The outcome summary is a closed semantic code, never a cause, detail or stderr: Pi
+ * keeps its own closed reason code, a CC reason is always null (its status is kept; the full
+ * result stays on the wire receipt), an adapter throw is `unknown/adapter-threw` and a
+ * post-request cancellation `refused/request-aborted`. Nothing here mutates the identity store.
+ */
+import { randomBytes } from "node:crypto";
+import { makeCcRetireDeps, requestCcRetire, } from "./cc-retire-request.js";
+import { ENTWURF_V2_LOCK_DIR, acquireLock as realAcquireLock, releaseLock as realReleaseLock, } from "./entwurf-v2-lock.js";
+import { inspectReceiverMarker } from "./entwurf-v2-visible-resume.js";
+import { defaultMetaReceiversDir, defaultMetaSendersDir, defaultMetaSessionsDir, metaRecordExistsByGardenId, readAddressableMetaIdentity, readMetaSenderMarker, } from "./meta-session.js";
+import { requestPiRetire } from "./pi-retire-request.js";
+import { appendRetirementEvent, RETIREMENT_EVENT_VERSION, retirementsDirBesideSessions, } from "./retirement-event.js";
+import { CONTROL_SOCKET_DIR, inspectControlSocketPath } from "./socket-discovery.js";
+import { probeSocketLiveness } from "./socket-probe.js";
+/** Pi's closed reason union, exhaustively (a Record keyed by it fails to type if one is added or
+ * removed). Only these codes reach the sidecar; anything else becomes null. */
+const PI_REASON_CODES = {
+    "target-backend-unsupported": true,
+    "target-identity-mismatch": true,
+    "target-closing": true,
+    "target-stale": true,
+    "target-context-unavailable": true,
+    "target-non-tui": true,
+    "target-busy": true,
+    "target-pending": true,
+    "malformed-response": true,
+    "transport-error": true,
+    "shutdown-call-failed": true,
+};
+/** The closed summary of an attempt that was recorded as requested. Any other outcome kind is a
+ * composition fault and throws, which the dispatcher reports as an outcome-record failure. */
+function summarizeAttempt(backend, outcome) {
+    if (outcome.kind === "pi" && backend === "pi") {
+        const { result } = outcome;
+        const reason = "reason" in result && Object.hasOwn(PI_REASON_CODES, result.reason) ? result.reason : null;
+        return { status: result.boundary, reason };
+    }
+    if (outcome.kind === "claude-code" && backend === "claude-code")
+        return { status: outcome.result.outcome, reason: null };
+    if (outcome.kind === "unknown" && outcome.backend === backend)
+        return { status: "unknown", reason: "adapter-threw" };
+    if (outcome.kind === "refused" && outcome.reason === "request-aborted") {
+        return { status: "refused", reason: "request-aborted" };
+    }
+    throw new Error(`no retirement summary for a ${outcome.kind} outcome on ${backend}`);
+}
+export function makeProductionRetireDeps(opts) {
+    // ── ONE path set: two module-load constants, three construction-time reads ──
+    const lockDir = opts.lockDir ?? ENTWURF_V2_LOCK_DIR;
+    const sessionsDir = opts.sessionsDir ?? defaultMetaSessionsDir();
+    const receiversDir = opts.receiversDir ?? defaultMetaReceiversDir();
+    const sendersDir = opts.sendersDir ?? defaultMetaSendersDir();
+    const controlSocketDir = opts.controlSocketDir ?? CONTROL_SOCKET_DIR;
+    const retirementsDir = retirementsDirBesideSessions(sessionsDir);
+    const signal = opts.signal;
+    const s = opts.seams ?? {};
+    const io = {
+        acquireLock: s.acquireLock ?? realAcquireLock,
+        releaseLock: s.releaseLock ?? realReleaseLock,
+        metaRecordExists: s.metaRecordExists ?? metaRecordExistsByGardenId,
+        readIdentity: s.readIdentity ?? readAddressableMetaIdentity,
+        inspectPath: s.inspectPath ?? ((socketPath) => inspectControlSocketPath(socketPath)),
+        probeSocket: s.probeSocket ?? probeSocketLiveness,
+        inspectReceiver: s.inspectReceiver ?? inspectReceiverMarker,
+        readSender: s.readSender ?? readMetaSenderMarker,
+        requestPi: s.requestPi ?? requestPiRetire,
+        requestCc: s.requestCc ?? ((expected, deps, options) => requestCcRetire(expected, deps, options)),
+        append: s.append ?? appendRetirementEvent,
+    };
+    const attribution = (context) => ({
+        actorGardenId: context.actorGardenId,
+        targetGardenId: context.targetGardenId,
+        targetBackend: context.targetBackend,
+    });
+    // The CC adapter's three witnesses, closed over the SAME directories as the dispatcher's own
+    // reads. Its helper path and spawn are left to the adapter's defaults.
+    const ccDeps = makeCcRetireDeps({
+        readRecord: (gid) => io.readIdentity(gid, sessionsDir),
+        inspectReceiver: (gid) => io.inspectReceiver(gid, receiversDir),
+        readSender: (ownerPid) => io.readSender({ backend: "claude-code", ownerPid, sendersDir }),
+    });
+    return {
+        resolveCaller: opts.resolveCaller,
+        // ONE lock domain: acquire and release are bound to the same directory.
+        acquireLock: (gid) => io.acquireLock(gid, { dir: lockDir }),
+        releaseLock: (claim) => io.releaseLock(claim, { dir: lockDir }),
+        recordExists: (gid) => io.metaRecordExists(gid, sessionsDir),
+        readIdentity: (gid) => io.readIdentity(gid, sessionsDir),
+        controlSocketDir,
+        inspectPath: (socketPath) => io.inspectPath(socketPath),
+        probeSocket: (socketPath) => io.probeSocket(socketPath),
+        requestPi: (target, expected, options) => io.requestPi(target, expected, { controlSocketDir: options.controlSocketDir }),
+        requestCc: (expected) => io.requestCc(expected, ccDeps, { signal }),
+        recordRequested: (context) => {
+            const eventId = randomBytes(16).toString("hex");
+            io.append(retirementsDir, {
+                v: RETIREMENT_EVENT_VERSION,
+                kind: "retirement-requested",
+                eventId,
+                at: new Date().toISOString(),
+                ...attribution(context),
+            });
+            return eventId;
+        },
+        recordOutcome: (eventId, context, outcome) => {
+            io.append(retirementsDir, {
+                v: RETIREMENT_EVENT_VERSION,
+                kind: "retirement-outcome",
+                eventId,
+                at: new Date().toISOString(),
+                ...attribution(context),
+                outcome: summarizeAttempt(context.targetBackend, outcome),
+            });
+            return undefined;
+        },
+        signal,
+    };
+}

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

@@ -0,0 +1,158 @@
+import { controlSocketPathIn } from "./control-socket-path.js";
+import { isOutOfSocketDomainGardenIdConflict } from "./entwurf-facts.js";
+import { isValidSessionId } from "./session-id.js";
+import { isRecordLessSocketCandidate, mapInspectionToLiveness, } from "./socket-discovery.js";
+const EVENT_ID_RE = /^[0-9a-f]{32}$/;
+function causeOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export async function retireCitizen(targetGardenId, deps) {
+    let actor = null;
+    const beforeLock = (outcome) => ({
+        targetGardenId,
+        actor,
+        outcome,
+        record: { status: "not-attempted" },
+        release: { status: "not-acquired" },
+    });
+    const aborted = () => deps.signal?.aborted === true;
+    if (!isValidSessionId(targetGardenId))
+        return beforeLock({ kind: "refused", reason: "target-invalid" });
+    let acquired;
+    try {
+        actor = await deps.resolveCaller();
+        if (!actor || !isValidSessionId(actor.sessionId) || actor.origin === "external-mcp") {
+            return beforeLock({ kind: "refused", reason: "caller-unavailable" });
+        }
+        if (actor.sessionId === targetGardenId)
+            return beforeLock({ kind: "refused", reason: "self-target" });
+        if (aborted())
+            return beforeLock({ kind: "refused", reason: "request-aborted" });
+        acquired = deps.acquireLock(targetGardenId);
+    }
+    catch (error) {
+        return beforeLock({ kind: "preflight-error", cause: causeOf(error) });
+    }
+    if (!acquired.ok)
+        return beforeLock({ kind: "refused", reason: "target-locked", detail: acquired.conflict.detail });
+    const claim = acquired.claim;
+    const actorGardenId = actor.sessionId;
+    let enteredBackend = null;
+    // Assigned inside runLocked; the cast keeps control flow from narrowing it to null here.
+    let attempt = null;
+    let record = { status: "not-attempted" };
+    let outcome;
+    let release;
+    /** The last step before ONE adapter: cancellation, requested record, cancellation again.
+     * Returns the outcome that replaces the adapter, or null to enter it. */
+    const admit = (targetBackend) => {
+        if (aborted())
+            return { kind: "refused", reason: "request-aborted" };
+        const context = { actorGardenId, targetGardenId, targetBackend };
+        let eventId;
+        try {
+            eventId = deps.recordRequested(context);
+        }
+        catch (error) {
+            record = { status: "requested-append-error", cause: causeOf(error) };
+            return { kind: "refused", reason: "retirement-record-unavailable" };
+        }
+        if (typeof eventId !== "string" || !EVENT_ID_RE.test(eventId)) {
+            record = { status: "requested-append-error", cause: "recorder returned no event id" };
+            return { kind: "refused", reason: "retirement-record-unavailable" };
+        }
+        attempt = { eventId, context };
+        if (aborted())
+            return { kind: "refused", reason: "request-aborted" };
+        enteredBackend = targetBackend;
+        return null;
+    };
+    const runLocked = async () => {
+        const socketPath = controlSocketPathIn(deps.controlSocketDir, targetGardenId);
+        if (!deps.recordExists(targetGardenId)) {
+            const inspection = await deps.inspectPath(socketPath);
+            return {
+                kind: "refused",
+                reason: isRecordLessSocketCandidate(inspection) ? "record-less-socket" : "target-not-found",
+            };
+        }
+        const identity = deps.readIdentity(targetGardenId);
+        if (identity.gardenId !== targetGardenId)
+            throw new Error("addressable target read returned a different garden id");
+        if (identity.backend !== "pi" && identity.backend !== "claude-code") {
+            return { kind: "refused", reason: "target-backend-unsupported" };
+        }
+        const inspection = await deps.inspectPath(socketPath);
+        if (identity.backend === "pi") {
+            const live = await mapInspectionToLiveness(inspection, deps.probeSocket);
+            if ("addressConflict" in live)
+                return { kind: "refused", reason: "target-address-conflict" };
+            if (live.liveness === "dead")
+                return { kind: "refused", reason: "target-dead" };
+            if (live.liveness !== "alive")
+                return { kind: "refused", reason: "target-indeterminate" };
+            // Fresh after awaited lstat/connect; timestamps are metadata, not birth identity.
+            const current = deps.readIdentity(targetGardenId);
+            if (["gardenId", "backend", "nativeSessionId", "createdAt"].some((key) => current[key] !== identity[key])) {
+                return { kind: "refused", reason: "target-drifted" };
+            }
+            const replaced = admit("pi");
+            if (replaced)
+                return replaced;
+            const result = await deps.requestPi(current, { gardenId: current.gardenId, nativeSessionId: current.nativeSessionId }, {
+                controlSocketDir: deps.controlSocketDir,
+            });
+            return { kind: "pi", result };
+        }
+        // Same out-of-socket-domain conflict policy as entwurf-v2-production. Non-socket
+        // regular entries do not claim a garden address; symlinks/socket entries do.
+        if (inspection.kind === "indeterminate")
+            throw new Error(`control address inspection indeterminate: ${inspection.error}`);
+        const sockets = new Set(inspection.kind === "socket-file" ? [targetGardenId] : []);
+        const symlinks = new Set(inspection.kind === "address-conflict" && inspection.reason === "symlink" ? [targetGardenId] : []);
+        if (isOutOfSocketDomainGardenIdConflict(identity.backend, targetGardenId, sockets, symlinks)) {
+            return { kind: "refused", reason: "target-address-conflict" };
+        }
+        const replaced = admit("claude-code");
+        if (replaced)
+            return replaced;
+        const { gardenId, backend, nativeSessionId, createdAt, attachIncarnation } = identity;
+        const result = await deps.requestCc({ gardenId, backend, nativeSessionId, createdAt, attachIncarnation });
+        return { kind: "claude-code", result };
+    };
+    try {
+        try {
+            outcome = await runLocked();
+        }
+        catch (error) {
+            outcome =
+                enteredBackend === null
+                    ? { kind: "preflight-error", cause: causeOf(error) }
+                    : { kind: "unknown", backend: enteredBackend, cause: causeOf(error) };
+        }
+        // An attempt that was recorded as requested gets ONE outcome record, before release.
+        if (attempt) {
+            const { eventId, context } = attempt;
+            try {
+                const returned = deps.recordOutcome(eventId, context, outcome);
+                record =
+                    returned === undefined
+                        ? { status: "complete", eventId }
+                        : { status: "outcome-append-error", eventId, cause: "recorder returned a value" };
+            }
+            catch (error) {
+                record = { status: "outcome-append-error", eventId, cause: causeOf(error) };
+            }
+        }
+    }
+    finally {
+        // One acquired claim, one release attempt. No throw here may overwrite outcome.
+        try {
+            release = { status: deps.releaseLock(claim) };
+        }
+        catch (error) {
+            release = { status: "error", cause: causeOf(error) };
+        }
+    }
+    return { targetGardenId, actor, outcome, record, release };
+}

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

@@ -48,7 +48,8 @@ export function actionableRejectHint(reason) {
             return ("this citizen's record is intact but its session is not running, and delivery has no way to wake it. " +
                 "The resume that used to answer here launched a hidden background child and was withdrawn under the " +
                 "visible-first rule; the visible same-id resume is the separate lifecycle verb entwurf_resume_call. " +
-                "Reopen the citizen with entwurf_resume_call {target} (pi targets only; it runs no turn), then dispatch again.");
+                "Only on an explicit operator request, use entwurf_resume_call {target} for Pi or Claude Code; " +
+                "it submits no prompt. This capability hint is not permission to resume automatically.");
         case "indeterminate-no-spawn":
             // The socket probe did not settle, so liveness is UNKNOWN — an unestablished probe
             // is not a measured death, and dispatching into it could double-deliver. Say