@junghanacs/entwurf 0.40.0 → 0.41.0

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

@@ -0,0 +1,473 @@
+/**
+ * cc-retire-request — the Node side of retiring ONE Claude Code citizen through the packaged pidfd
+ * helper (#147 G3, core-side leaf).
+ *
+ * NOT an authorization boundary. The caller (a future core verb) owns every decision about WHETHER
+ * this citizen may be retired: who asked, self-retire refusal, and the per-target lock. This leaf
+ * takes no lock of its own, so a caller holding the target lock cannot deadlock against it. It
+ * opens no public tool, reads no role or permission, and never reads a transcript, message body or
+ * credential.
+ *
+ * What it adds over the helper is the binding check while the helper HOLDS the pidfd. The helper
+ * pins a PROCESS; a Claude Code process can switch its native session in place (`/resume`,
+ * `/clear`), after which the same pid is a different citizen. So the record, the receiver marker
+ * and the sender marker the hook moves on every event are read once before the helper starts and
+ * once more after it reports `ready` — the fd is held by then, so the pid the second read names
+ * cannot have been reused. Only when that second read still names the same garden, native
+ * session, binding and owner is `go` written; any other answer writes `cancel`. A switch that
+ * commits AFTER the second read is not covered: nothing here claims to close that window.
+ *
+ * Signals: Node sends none to the target. The only signal Node sends is to its OWN helper child,
+ * by ChildProcess handle, after the helper has gone silent past a fixed bound — and that child is
+ * not yet reaped when it is sent, so its pid cannot have been reused.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { inspectReceiverMarker } from "./entwurf-v2-visible-resume.js";
+import { readAddressableMetaIdentity, readMetaSenderMarker, } from "./meta-session.js";
+export const CC_RETIRE_HELPER_FILE = "cc-retire-pidfd.py";
+/** The owner kind the Claude Code hook's receiver marker carries: `writeMetaReceiverMarker`'s
+ * default (meta-session.ts), which the hook does not override. A marker naming any other owner is
+ * another harness's process, never a Claude Code foreground owner. */
+export const CC_RECEIVER_OWNER_KIND = "claude-code-cli";
+/** The arm provenances the Claude Code hook writes. `extension-join` is Copilot's, not Claude's. */
+export const CC_RECEIVER_ARM_PROVENANCES = [
+    "session-start",
+    "cwd-changed",
+    "file-changed",
+];
+/** Wall-clock bound on the whole helper exchange. The helper bounds itself (10 s for the control
+ * frame, 5 s for the exit); this only catches a helper that stops talking. */
+export const CC_RETIRE_HELPER_WALL_MS = 30_000;
+/** At most this many stdout bytes are accepted from the helper; more is a protocol failure. */
+const STDOUT_MAX = 4096;
+const STDERR_MAX = 4096;
+/**
+ * The packaged helper: the fixed basename BESIDE this module, nowhere else. The canonical file is
+ * `pi-extensions/lib/cc-retire-pidfd.py`, which is beside the source; `build-bridge.sh` byte-copies
+ * it beside the emitted adapter in `mcp/entwurf-bridge/dist/pi-extensions/lib/`, so the same rule
+ * holds at both depths (check-capability-bundle-reach asks the compiled copy from where it lives).
+ * `null` when that entry is not a regular file — a packaging defect, refused by name; no parent
+ * directory, environment path or download is ever consulted.
+ */
+export function ccRetireHelperPath(from = import.meta.dirname) {
+    const candidate = path.join(from, CC_RETIRE_HELPER_FILE);
+    try {
+        return fs.lstatSync(candidate).isFile() ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The exact argv the helper is started with: isolated interpreter, the fixed file, two facts. */
+export function ccRetireHelperArgv(helperPath, pid, startKey) {
+    return ["-I", "-S", helperPath, String(pid), startKey];
+}
+export function makeCcRetireDeps(overrides = {}) {
+    return {
+        readRecord: (gid) => readAddressableMetaIdentity(gid),
+        inspectReceiver: (gid) => inspectReceiverMarker(gid),
+        readSender: (ownerPid) => readMetaSenderMarker({ backend: "claude-code", ownerPid }),
+        helperPath: () => ccRetireHelperPath(),
+        spawnHelper: (argv) => spawn("python3", [...argv], { stdio: ["pipe", "pipe", "pipe"], env: { PATH: process.env.PATH ?? "" } }),
+        ...overrides,
+    };
+}
+const LINUX_KEY = /^linux:[0-9]{1,20}$/;
+function causeOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * One read of the three witnesses, compared against what the caller authorised and against each
+ * other. `pinned` (the second read) also requires the SAME owner as the first, because the helper
+ * is holding that process.
+ */
+export function checkCcRetireBinding(expected, deps, pinned) {
+    const gid = expected.gardenId;
+    let record;
+    try {
+        record = deps.readRecord(gid);
+    }
+    catch (err) {
+        return { ok: false, reason: "record-unreadable", detail: causeOf(err) };
+    }
+    if (record.backend !== "claude-code") {
+        return { ok: false, reason: "target-not-claude-code", detail: `record backend is ${record.backend}` };
+    }
+    if (record.attachIncarnation === null) {
+        return { ok: false, reason: "target-unbound", detail: "record carries no attachIncarnation" };
+    }
+    for (const key of ["gardenId", "backend", "nativeSessionId", "createdAt", "attachIncarnation"]) {
+        if (record[key] !== expected[key]) {
+            return { ok: false, reason: "record-drifted", detail: `record ${key} is not the one the caller authorised` };
+        }
+    }
+    let inspection;
+    try {
+        inspection = deps.inspectReceiver(gid);
+    }
+    catch (err) {
+        return { ok: false, reason: "receiver-unreadable", detail: causeOf(err) };
+    }
+    if (inspection.kind === "absent")
+        return { ok: false, reason: "receiver-absent", detail: "no receiver marker" };
+    if (inspection.kind === "corrupt")
+        return { ok: false, reason: "receiver-corrupt", detail: "receiver marker unreadable" };
+    const marker = inspection.marker;
+    if (marker.gardenId !== gid ||
+        marker.backend !== "claude-code" ||
+        marker.nativeSessionId !== record.nativeSessionId) {
+        return {
+            ok: false,
+            reason: "receiver-drifted",
+            detail: "receiver marker names another garden, backend or session",
+        };
+    }
+    if (marker.ownerKind !== CC_RECEIVER_OWNER_KIND) {
+        return { ok: false, reason: "receiver-foreign-owner", detail: `receiver owner kind is ${marker.ownerKind}` };
+    }
+    if (!CC_RECEIVER_ARM_PROVENANCES.includes(marker.armProvenance)) {
+        return {
+            ok: false,
+            reason: "receiver-foreign-provenance",
+            detail: `receiver arm provenance is ${marker.armProvenance}`,
+        };
+    }
+    if (marker.attachIncarnation === null) {
+        return { ok: false, reason: "receiver-unbound", detail: "receiver marker carries no attachIncarnation" };
+    }
+    if (marker.attachIncarnation !== record.attachIncarnation) {
+        return { ok: false, reason: "receiver-drifted", detail: "receiver binding differs from the record's" };
+    }
+    if (inspection.owner === "dead")
+        return { ok: false, reason: "receiver-dead", detail: `owner ${marker.ownerPid} is gone` };
+    if (inspection.owner !== "live") {
+        return { ok: false, reason: "receiver-uncertain", detail: `owner ${marker.ownerPid} cannot be proven live` };
+    }
+    if (!LINUX_KEY.test(marker.ownerStartKey)) {
+        return { ok: false, reason: "start-key-unsupported", detail: "owner start key is not a linux:<starttime> key" };
+    }
+    if (pinned && (marker.ownerPid !== pinned.pid || marker.ownerStartKey !== pinned.startKey)) {
+        return { ok: false, reason: "receiver-drifted", detail: "receiver owner is not the process the helper holds" };
+    }
+    let sender;
+    try {
+        sender = deps.readSender(marker.ownerPid);
+    }
+    catch (err) {
+        return { ok: false, reason: "sender-unreadable", detail: causeOf(err) };
+    }
+    if (sender === null) {
+        return { ok: false, reason: "sender-absent", detail: `no trusted sender marker for owner ${marker.ownerPid}` };
+    }
+    // The reader is keyed by backend directory but does not compare the body's backend with it.
+    if (sender.backend !== "claude-code") {
+        return { ok: false, reason: "sender-foreign-backend", detail: `sender marker backend is ${sender.backend}` };
+    }
+    if (sender.gardenId !== gid ||
+        sender.nativeSessionId !== record.nativeSessionId ||
+        sender.ownerPid !== marker.ownerPid ||
+        sender.ownerStartKey !== marker.ownerStartKey) {
+        return { ok: false, reason: "sender-drifted", detail: "the owner's sender marker now names another citizen" };
+    }
+    return { ok: true, owner: { pid: marker.ownerPid, startKey: marker.ownerStartKey } };
+}
+function exactKeys(line, keys) {
+    const own = Object.keys(line).sort();
+    const want = [...keys].sort();
+    return own.length === want.length && own.every((k, i) => k === want[i]);
+}
+/** Outcomes the helper may print and the exit code each must come with. */
+const PRE_READY_OUTCOMES = { refused: 2, "already-exited": 3 };
+const CANCEL_OUTCOMES = { cancelled: 3 };
+const AFTER_GO_NO_SIGNAL = {
+    "already-exited": 3,
+    "observe-failed-before-signal": 3,
+    refused: 2,
+};
+const AFTER_SIGNAL = { exited: 0, "exit-unobserved": 4, "observe-failed": 4 };
+/**
+ * The helper's terminal line, closed per outcome (its `finish(...)` calls in cc-retire-pidfd.py):
+ * `refused` carries a `reason` and may carry an `errno` (name or number); `exit-unobserved` carries
+ * `waitedS`; every other outcome carries nothing else. A missing, extra or mistyped key is not that
+ * outcome. The refusal `reason` text is diagnostic and stays open — reported, never branched on.
+ */
+function terminalShapeOk(line) {
+    switch (line.outcome) {
+        case "refused": {
+            const hasErrno = "errno" in line;
+            if (hasErrno && typeof line.errno !== "string" && typeof line.errno !== "number")
+                return false;
+            return (exactKeys(line, hasErrno ? ["outcome", "reason", "errno"] : ["outcome", "reason"]) &&
+                typeof line.reason === "string" &&
+                line.reason.length > 0);
+        }
+        case "exit-unobserved":
+            return exactKeys(line, ["outcome", "waitedS"]) && typeof line.waitedS === "number";
+        default:
+            return exactKeys(line, ["outcome"]);
+    }
+}
+function outcomeLine(line, allowed, code) {
+    if (!line || typeof line.outcome !== "string")
+        return null;
+    const want = allowed[line.outcome];
+    if (want === undefined || want !== code)
+        return null;
+    if (!terminalShapeOk(line))
+        return null;
+    return line.outcome;
+}
+/**
+ * Retire `expected.gardenId` if, and only if, every witness still names the citizen the caller
+ * authorised both before the helper starts and after it holds the pidfd.
+ */
+export async function requestCcRetire(expected, deps = makeCcRetireDeps(), opts = {}) {
+    if (opts.signal?.aborted)
+        return { outcome: "refused", reason: "aborted", detail: "aborted before any check" };
+    const first = checkCcRetireBinding(expected, deps);
+    if (!first.ok)
+        return { outcome: "refused", reason: first.reason, detail: first.detail };
+    const helperPath = deps.helperPath();
+    if (helperPath === null) {
+        return { outcome: "refused", reason: "helper-missing", detail: `packaged ${CC_RETIRE_HELPER_FILE} not found` };
+    }
+    if (opts.signal?.aborted)
+        return { outcome: "refused", reason: "aborted", detail: "aborted before the helper started" };
+    const owner = first.owner;
+    const argv = ccRetireHelperArgv(helperPath, owner.pid, owner.startKey);
+    return await new Promise((resolve) => {
+        let child;
+        try {
+            child = deps.spawnHelper(argv);
+        }
+        catch (err) {
+            resolve({ outcome: "refused", reason: "helper-spawn-failed", detail: causeOf(err) });
+            return;
+        }
+        const lines = [];
+        let buf = "";
+        let stdoutBytes = 0;
+        let stderr = "";
+        let protocolError = null;
+        /** What Node has written: nothing yet, cancel, or go. Decides how every ending is read. */
+        let sent = "none";
+        let cancelReason = null;
+        let settled = false;
+        let spawnError = null;
+        let wallExpired = false;
+        let abortedAfterGo = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(wall);
+            opts.signal?.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
+        const killOwnHelper = () => {
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGKILL");
+        };
+        /** Terminal latch: once a protocol failure, the wall bound, an abort after go or the ending
+         * has been recorded, no frame — above all no `go` — is ever written. Killing the helper is
+         * cleanup; THIS is the guard. */
+        const terminal = () => settled || protocolError !== null || wallExpired || abortedAfterGo;
+        const write = (frame) => {
+            if (terminal() || sent !== "none")
+                return;
+            // Recorded BEFORE the write: a `go` whose write threw may still have reached the pipe.
+            sent = frame;
+            try {
+                child.stdin.end(`${frame}\n`);
+            }
+            catch (err) {
+                protocolError ??= `writing the ${frame} frame threw: ${causeOf(err)}`;
+                killOwnHelper();
+            }
+        };
+        const cancel = (reason, detail) => {
+            if (terminal() || sent !== "none")
+                return;
+            cancelReason = { reason, detail };
+            write("cancel");
+        };
+        const onAbort = () => {
+            if (sent === "none" && lines.length > 0)
+                cancel("aborted-before-go", "the requester aborted while the fd was held");
+            else if (sent === "none") {
+                cancelReason = { reason: "aborted-before-go", detail: "the requester aborted before the helper was ready" };
+                sent = "cancel";
+                try {
+                    child.stdin.end();
+                }
+                catch (err) {
+                    protocolError ??= `closing the control pipe threw: ${causeOf(err)}`;
+                    killOwnHelper();
+                }
+            }
+            else if (sent === "go") {
+                abortedAfterGo = true;
+                killOwnHelper();
+            }
+        };
+        const wall = setTimeout(() => {
+            wallExpired = true;
+            killOwnHelper();
+        }, opts.wallMs ?? CC_RETIRE_HELPER_WALL_MS);
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdin.on("error", () => {
+            // EPIPE: the helper ended first. Its exit and its lines are the evidence, not this.
+        });
+        child.on("error", (err) => {
+            spawnError = causeOf(err);
+            // No pid: the interpreter never started, so nothing can be held or signalled. Do not wait
+            // for a `close` that a failed spawn is not obliged to deliver.
+            if (child.pid === undefined)
+                finish({ outcome: "refused", reason: "helper-spawn-failed", detail: spawnError });
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < STDERR_MAX)
+                stderr += chunk.toString("utf8").slice(0, STDERR_MAX - stderr.length);
+        });
+        child.stdout.on("data", (chunk) => {
+            // After a protocol failure nothing further is read: a buffered `ready` behind a bad line
+            // must not be acted on.
+            if (protocolError !== null || settled)
+                return;
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > STDOUT_MAX) {
+                protocolError ??= "helper printed more than the bounded output";
+                killOwnHelper();
+                return;
+            }
+            buf += chunk.toString("utf8");
+            let nl = buf.indexOf("\n");
+            while (nl >= 0) {
+                const text = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                let line;
+                try {
+                    const parsed = JSON.parse(text);
+                    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+                        throw new Error("not an object");
+                    line = parsed;
+                }
+                catch {
+                    protocolError ??= `helper printed a non-JSON-object line: ${JSON.stringify(text.slice(0, 120))}`;
+                    killOwnHelper();
+                    return;
+                }
+                lines.push(line);
+                onLine(line);
+                if (protocolError !== null)
+                    return;
+                nl = buf.indexOf("\n");
+            }
+        });
+        const onLine = (line) => {
+            if (lines.length !== 1 || !("phase" in line))
+                return;
+            if (!exactKeys(line, ["phase", "pid"]) || line.phase !== "ready" || line.pid !== owner.pid) {
+                protocolError ??= `first phase line is not ready for pid ${owner.pid}`;
+                killOwnHelper();
+                return;
+            }
+            if (sent !== "none")
+                return; // aborted while starting: cancel already written
+            if (opts.signal?.aborted) {
+                cancel("aborted-before-go", "the requester aborted while the fd was held");
+                return;
+            }
+            const second = checkCcRetireBinding(expected, deps, owner);
+            if (!second.ok) {
+                cancel(second.reason, second.detail);
+                return;
+            }
+            write("go");
+        };
+        child.on("close", (code) => {
+            // Incomplete trailing output is not a protocol the helper finished: never success.
+            if (buf.length > 0)
+                protocolError ??= `helper left incomplete trailing output: ${JSON.stringify(buf.slice(0, 120))}`;
+            const helperDetail = (msg) => (stderr ? `${msg}; helper stderr: ${stderr.trim()}` : msg);
+            if (spawnError !== null && lines.length === 0) {
+                finish({ outcome: "refused", reason: "helper-spawn-failed", detail: spawnError });
+                return;
+            }
+            const ready = lines[0]?.phase === "ready";
+            if (sent === "go") {
+                const rest = lines.slice(1);
+                const signalled = rest[0]?.phase === "signal-requested";
+                if (protocolError === null && !wallExpired && !abortedAfterGo) {
+                    if (signalled &&
+                        rest.length === 2 &&
+                        exactKeys(rest[0], ["phase", "signal"]) &&
+                        rest[0].signal === "SIGTERM") {
+                        const out = outcomeLine(rest[1], AFTER_SIGNAL, code);
+                        if (out === "exited" && exactKeys(rest[1], ["outcome"])) {
+                            finish({ outcome: "exited", gardenId: expected.gardenId, pid: owner.pid });
+                            return;
+                        }
+                        if (out !== null && out !== "exited") {
+                            finish({ outcome: "unknown", reason: out, detail: helperDetail(`SIGTERM requested; ${out}`) });
+                            return;
+                        }
+                    }
+                    if (!signalled && rest.length === 1) {
+                        const out = outcomeLine(rest[0], AFTER_GO_NO_SIGNAL, code);
+                        if (out !== null) {
+                            const reason = out === "refused" ? `helper-refused:${String(rest[0].reason)}` : out;
+                            finish({ outcome: "not-signalled", reason, detail: helperDetail(`after go: ${reason}`) });
+                            return;
+                        }
+                    }
+                }
+                const why = abortedAfterGo
+                    ? "aborted-after-go"
+                    : wallExpired
+                        ? "helper-wall-timeout"
+                        : (protocolError ?? `helper ended with code ${code} after go without a valid outcome`);
+                finish({
+                    outcome: "unknown",
+                    reason: abortedAfterGo ? "aborted-after-go" : wallExpired ? "helper-wall-timeout" : "helper-protocol",
+                    detail: helperDetail(`${why}${signalled ? " (signal-requested was reported)" : ""}`),
+                });
+                return;
+            }
+            // No go was written, so the helper cannot have signalled: every ending here is non-success.
+            if (sent === "cancel" && cancelReason !== null) {
+                const r = cancelReason;
+                const confirmed = ready && lines.length === 2 && outcomeLine(lines[1], CANCEL_OUTCOMES, code) !== null;
+                const eofConfirmed = !ready || (lines.length === 2 && lines[1]?.outcome === "cancelled-eof");
+                finish({
+                    outcome: "not-signalled",
+                    reason: r.reason,
+                    detail: helperDetail(confirmed || eofConfirmed ? r.detail : `${r.detail}; helper ending not confirmed`),
+                });
+                return;
+            }
+            if (!ready && protocolError === null && lines.length === 1) {
+                const out = outcomeLine(lines[0], PRE_READY_OUTCOMES, code);
+                if (out === "refused") {
+                    finish({
+                        outcome: "refused",
+                        reason: `helper-refused:${String(lines[0].reason)}`,
+                        detail: helperDetail("helper refused before ready"),
+                    });
+                    return;
+                }
+                if (out === "already-exited") {
+                    finish({ outcome: "not-signalled", reason: "already-exited", detail: helperDetail("target exited") });
+                    return;
+                }
+            }
+            finish({
+                outcome: ready ? "not-signalled" : "refused",
+                reason: wallExpired ? "helper-wall-timeout" : "helper-protocol",
+                detail: helperDetail(protocolError ?? `helper ended with code ${code} before go`),
+            });
+        });
+    });
+}

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

@@ -0,0 +1,125 @@
+/** Production start/rebind seam. Same-path rebind is entirely synchronous and performs NO
+ * listener/path IO. Each accept snapshots the binding via acceptControlConnection below.
+ */
+export async function startOrRebindControlServer(state, ctx, socketPath, gardenId, io) {
+    const binding = { gardenId, nativeSessionId: ctx.sessionManager.getSessionId(), context: ctx };
+    const bind = () => {
+        state.context = ctx;
+        state.binding = binding;
+        state.closing = false;
+        state.retireRequested = false;
+    };
+    if (state.socketPath === socketPath && state.server) {
+        bind();
+        return;
+    }
+    await io.prepare();
+    await io.stop();
+    await io.remove(socketPath);
+    bind();
+    state.socketPath = socketPath;
+    state.server = await io.create(socketPath);
+}
+/** Snapshot exactly once, on accept, NOT when the listener was created or a command arrives. */
+export function acceptControlConnection(state, socket) {
+    state.connections.add(socket);
+    socket.once("close", () => state.connections.delete(socket));
+    return state.binding;
+}
+/** Entire final check + SDK void call is synchronous. Call only AFTER any async preflight.
+ * A returned request receipt proves neither process exit nor persistence/flush completion.
+ * After requested/unknown, unobserved exit can leave a connect-alive socket refusing commands
+ * as target-closing until exit or a new session_start. No same-generation unlatch or retry.
+ */
+export function requestControlRetire(state, serverBinding, residentGardenId, expected) {
+    if (state.closing || state.retireRequested)
+        return { boundary: "refused", reason: "target-closing" };
+    const ctx = state.context;
+    if (!serverBinding ||
+        !ctx ||
+        state.binding !== serverBinding ||
+        ctx !== serverBinding.context ||
+        residentGardenId !== serverBinding.gardenId ||
+        expected.gardenId !== serverBinding.gardenId ||
+        expected.nativeSessionId !== serverBinding.nativeSessionId) {
+        return { boundary: "refused", reason: "target-stale" };
+    }
+    let shutdown;
+    try {
+        if (ctx.sessionManager.getSessionId() !== serverBinding.nativeSessionId) {
+            return { boundary: "refused", reason: "target-stale" };
+        }
+        if (ctx.mode !== "tui")
+            return { boundary: "refused", reason: "target-non-tui" };
+        if (!ctx.isIdle())
+            return { boundary: "refused", reason: "target-busy" };
+        if (ctx.hasPendingMessages())
+            return { boundary: "refused", reason: "target-pending" };
+        shutdown = ctx.shutdown;
+    }
+    catch {
+        // SDK invalidates captured contexts on replacement/reload. Never call through one.
+        return { boundary: "refused", reason: "target-context-unavailable" };
+    }
+    state.retireRequested = true;
+    try {
+        shutdown.call(ctx);
+    }
+    catch {
+        // The call may have started shutdown before throwing. Do not invite a replay.
+        return { boundary: "unknown", reason: "shutdown-call-failed" };
+    }
+    return { boundary: "shutdown-requested" };
+}
+/** Invalidate BEFORE waiting for server.close: accepted old connections must not act. */
+export function invalidateControlBinding(state) {
+    state.closing = true;
+    state.binding = null;
+    state.context = null;
+}
+/** The production receiver's one wire envelope. The RpcResponse import is type-only:
+ * no runtime dependency on the RPC client is introduced. An absent id is omitted by JSON;
+ * error is present only for refused/unknown, matching the strict core-side parser.
+ */
+export function retireResponseEnvelope(result, id) {
+    return {
+        type: "response",
+        command: "retire",
+        id,
+        success: result.boundary === "shutdown-requested",
+        data: result,
+        ...(result.boundary !== "shutdown-requested" ? { error: result.reason } : {}),
+    };
+}
+/** One response, then FIN; never wait for SDK termination to acknowledge its request.
+ * A failed transport leaves the caller with unknown outcome, not retry authority.
+ * The internal client sends one command per connection: concurrent responses on this same
+ * connection can be lost when retire sends FIN. It is not a multiplexed lifecycle protocol.
+ */
+export function endRetireResponse(socket, response) {
+    try {
+        socket.end(`${JSON.stringify(response)}\n`);
+    }
+    catch {
+        socket.destroy();
+    }
+}
+/** Session teardown only: flush accepted writes with FIN, then bound a non-cooperating peer.
+ * This timer exists solely for this server.close operation, not as a resident watcher.
+ * Applied to all session shutdowns: other in-flight replies may become transport-unknown.
+ */
+export async function closeControlConnections(server, sockets) {
+    await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            for (const socket of sockets)
+                socket.destroy();
+        }, 250);
+        timer.unref();
+        server.close(() => {
+            clearTimeout(timer);
+            resolve();
+        });
+        for (const socket of sockets)
+            socket.end();
+    });
+}