@junghanacs/entwurf 0.40.0 → 0.41.0

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

@@ -396,7 +396,23 @@ const META_IDENTITY_KEYS = [
     "transcriptPath",
     "createdAt",
     "recordUpdatedAt",
+    "attachIncarnation",
 ];
+/** `attachIncarnation` grammar: 32 lowercase hex characters (`randomBytes(16)`). */
+const ATTACH_INCARNATION_RE = /^[0-9a-f]{32}$/;
+/** Validate an `attachIncarnation`: null, or the 32-hex grammar. Throws on anything else. */
+export function requireAttachIncarnation(value) {
+    if (value === null)
+        return null;
+    if (typeof value !== "string" || !ATTACH_INCARNATION_RE.test(value)) {
+        throw new MetaRecordError(`meta-record field "attachIncarnation" must be null or 32 lowercase hex characters (got ${describe(value)}).`);
+    }
+    return value;
+}
+/** Mint one arm binding value. Clock-independent: 128 random bits, never derived from time. */
+export function mintAttachIncarnation() {
+    return crypto.randomBytes(16).toString("hex");
+}
 /** Parse + fully validate untrusted JSON into a v3 MetaIdentity. Throws on any drift. */
 export function parseMetaRecordV3(json) {
     let raw;
@@ -432,6 +448,10 @@ export function parseMetaRecordV3(json) {
         transcriptPath: requireNullableString(obj.transcriptPath, "transcriptPath"),
         createdAt: requireNonEmptyString(obj.createdAt, "createdAt"),
         recordUpdatedAt: requireNonEmptyString(obj.recordUpdatedAt, "recordUpdatedAt"),
+        // The one key a V3 record may omit: a record nothing has touched since the field
+        // existed reads its absence as null ("no binding observed"). One schema, one reader —
+        // not a legacy alias: every serialize emits the key.
+        attachIncarnation: requireAttachIncarnation(obj.attachIncarnation === undefined ? null : obj.attachIncarnation),
     };
 }
 /**
@@ -450,6 +470,7 @@ export function normalizeMetaIdentity(record) {
         transcriptPath: record.transcriptPath,
         createdAt: record.createdAt,
         recordUpdatedAt: record.recordUpdatedAt,
+        attachIncarnation: record.attachIncarnation,
     };
 }
 // ---------------------------------------------------------------------------
@@ -474,6 +495,7 @@ export function serializeMetaIdentity(identity) {
         transcriptPath: identity.transcriptPath,
         createdAt: identity.createdAt,
         recordUpdatedAt: identity.recordUpdatedAt,
+        attachIncarnation: identity.attachIncarnation,
     };
     return `${JSON.stringify(ordered, null, 2)}\n`;
 }
@@ -497,6 +519,7 @@ export function mintMetaIdentity(input, now = new Date()) {
         transcriptPath: requireNullableString(input.transcriptPath ?? null, "transcriptPath"),
         createdAt: ts,
         recordUpdatedAt: ts,
+        attachIncarnation: input.attachIncarnation === undefined ? null : requireAttachIncarnation(input.attachIncarnation),
     };
 }
 /**
@@ -1097,9 +1120,13 @@ export function decideUpsert(existing, input, now = new Date()) {
     const transcriptPath = input.transcriptPath === undefined
         ? existing.transcriptPath
         : requireNullableString(input.transcriptPath, "transcriptPath");
+    // The arm binding is not a merge axis: only a mint replaces it, and nothing clears it.
+    const attachIncarnation = input.attachIncarnation === undefined
+        ? existing.attachIncarnation
+        : requireAttachIncarnation(input.attachIncarnation);
     return {
         action: "attach",
-        record: { ...existing, cwd, model, transcriptPath, recordUpdatedAt: isoNow(now) },
+        record: { ...existing, cwd, model, transcriptPath, recordUpdatedAt: isoNow(now), attachIncarnation },
     };
 }
 // ---------------------------------------------------------------------------
@@ -1196,6 +1223,16 @@ export function defaultMetaReceiversDir() {
         return path.resolve(expandTilde(process.env.ENTWURF_META_RECEIVERS_DIR));
     return path.join(piAgentDir(), "meta-receivers");
 }
+/**
+ * The record-arm lock directory (#147 L2 B1): a sibling of the receivers dir, so a
+ * sandboxed receivers root sandboxes it too and no new environment carrier exists. It is
+ * deliberately NOT the v2 dispatch lock dir — visible resume holds that per-gid lock across
+ * its whole launch + observation window, and the relaunched session's own arm must not wait
+ * on it. Only the Claude Code hook takes this lock; nothing else reads or writes here.
+ */
+export function defaultMetaRecordArmLocksDir(receiversDir = defaultMetaReceiversDir()) {
+    return path.join(path.dirname(receiversDir), "meta-record-arm-locks");
+}
 /**
  * The exact provenance label the omp-native MCP entry carries
  * (`scripts/omp-mcp-config.py` `EXTERNAL_AGENT_ID`). It is what lets a bridge CHILD know
@@ -1652,12 +1689,38 @@ export function writeMetaReceiverMarker(opts) {
         ownerKind: requireNonEmptyString(opts.ownerKind ?? "claude-code-cli", "ownerKind"),
         armProvenance: requireArmProvenance(opts.armProvenance),
         updatedAt: isoNow(opts.now ?? new Date()),
+        attachIncarnation: opts.attachIncarnation === undefined ? null : requireAttachIncarnation(opts.attachIncarnation),
     };
     const tmp = `${file}.${crypto.randomBytes(4).toString("hex")}.tmp`;
     fs.writeFileSync(tmp, `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600 });
     fs.renameSync(tmp, file);
     return file;
 }
+/**
+ * Validate receiver-marker bytes — the one validator, shared by the path reader below and by
+ * the no-follow fd reader visible resume uses (#147 L2 D3). Throws on a malformed marker;
+ * returns null for an IMPLAUSIBLE owner pid. Same rule as the sender marker, and for the same
+ * reason one layer over: an impossible owner is not a live one, so a refuted marker must never
+ * read back as an ACTIVE RECEIVER and pull the mailbox rail into delivering to a void. An
+ * absent `attachIncarnation` reads as null; a present malformed one throws.
+ */
+export function parseMetaReceiverMarker(json) {
+    const raw = JSON.parse(json);
+    const marker = {
+        gardenId: requireGardenId(raw.gardenId),
+        backend: requireBackend(raw.backend),
+        nativeSessionId: requireNonEmptyString(raw.nativeSessionId, "nativeSessionId"),
+        ownerPid: typeof raw.ownerPid === "number" ? raw.ownerPid : Number.NaN,
+        ownerStartKey: requireNonEmptyString(raw.ownerStartKey, "ownerStartKey"),
+        ownerKind: requireNonEmptyString(raw.ownerKind, "ownerKind"),
+        armProvenance: requireArmProvenance(raw.armProvenance),
+        updatedAt: requireNonEmptyString(raw.updatedAt, "updatedAt"),
+        attachIncarnation: requireAttachIncarnation(raw.attachIncarnation === undefined ? null : raw.attachIncarnation),
+    };
+    if (!isPlausibleOwnerPid(marker.ownerPid))
+        return null;
+    return marker;
+}
 /**
  * Read the receiver presence marker for a garden id. Returns null when absent,
  * corrupt, or (under verifyOwner) the owner pid is no longer the same live process —
@@ -1674,21 +1737,8 @@ export function readMetaReceiverMarker(opts) {
     if (!file || !fs.existsSync(file))
         return null;
     try {
-        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
-        const marker = {
-            gardenId: requireGardenId(raw.gardenId),
-            backend: requireBackend(raw.backend),
-            nativeSessionId: requireNonEmptyString(raw.nativeSessionId, "nativeSessionId"),
-            ownerPid: typeof raw.ownerPid === "number" ? raw.ownerPid : Number.NaN,
-            ownerStartKey: requireNonEmptyString(raw.ownerStartKey, "ownerStartKey"),
-            ownerKind: requireNonEmptyString(raw.ownerKind, "ownerKind"),
-            armProvenance: requireArmProvenance(raw.armProvenance),
-            updatedAt: requireNonEmptyString(raw.updatedAt, "updatedAt"),
-        };
-        // Same rule as the sender marker, and for the same reason one layer over: an
-        // impossible owner is not a live one, so a refuted marker must never read back
-        // as an ACTIVE RECEIVER and pull the mailbox rail into delivering to a void.
-        if (!isPlausibleOwnerPid(marker.ownerPid))
+        const marker = parseMetaReceiverMarker(fs.readFileSync(file, "utf8"));
+        if (marker === null)
             return null;
         if (opts.verifyOwner !== false) {
             const liveKey = processStartKey(marker.ownerPid);
@@ -1774,6 +1824,9 @@ export function upsertMetaSession(opts) {
     const target = requireNonEmptyString(opts.input.nativeSessionId, "nativeSessionId");
     const existing = cert.records.find((record) => record.identity.nativeSessionId === target)?.identity ?? null;
     const decision = decideUpsert(existing, opts.input, opts.now);
+    if (opts.expectAction !== undefined && decision.action !== opts.expectAction) {
+        throw new UpsertActionMismatchError(opts.expectAction, decision.action, target);
+    }
     const file = path.join(dir, metaRecordFilename(decision.record));
     if (decision.action === "create")
         publishExclusiveIdentity(file, decision.record);
@@ -1781,6 +1834,33 @@ export function upsertMetaSession(opts) {
         atomicWriteIdentity(file, decision.record);
     return { action: decision.action, record: decision.record, dir, path: file };
 }
+/** The upsert refused before writing because its decision was not the expected action. */
+export class UpsertActionMismatchError extends MetaRecordError {
+    expected;
+    actual;
+    constructor(expected, actual, nativeSessionId) {
+        super(`upsert expected to ${expected} the record for nativeSessionId "${nativeSessionId}" but would ${actual} ` +
+            "it; nothing was written.");
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+/**
+ * The certified record a native session id already has, READ ONLY — the same certification
+ * {@link upsertMetaSession} runs (a defective store throws the same refusal), with no write.
+ * The Claude Code hook learns the garden id it must lock this way, so no record write ever
+ * happens outside the record-arm lock for an existing record (#147 L2 B1).
+ */
+export function findCertifiedIdentityByNativeSessionId(nativeSessionId, dirOverride) {
+    const dir = path.resolve(expandTilde(dirOverride ?? defaultMetaSessionsDir()));
+    if (!fs.existsSync(dir))
+        return null;
+    const cert = certifyActiveStoreDir(dir);
+    if (cert.defects.length > 0)
+        throw new MetaRecordError(activeStoreRefusal(cert));
+    const target = requireNonEmptyString(nativeSessionId, "nativeSessionId");
+    return cert.records.find((record) => record.identity.nativeSessionId === target)?.identity ?? null;
+}
 /**
  * ATTACH replace primitive: tmp-file + rename so a crash never leaves a
  * half-written record (#30 crash-safety). rename(2) REPLACES an existing final

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-fresh-call.js

@@ -91,8 +91,8 @@ import { classifyTmuxCwd } from "./classify-tmux-cwd.js";
 import { CODEX_CALLER_SEAT_HINT, resolveCodexCallerSeat, } from "./codex-caller-seat.js";
 import { CODEX_CALLER_PREFLIGHT_HINT, CODEX_LAUNCH_CWD_PREFLIGHT_HINT, CODEX_PREFLIGHT_HINT, codexLaunchCwdFreshPreflight, } from "./codex-fresh-preflight.js";
 import { COPILOT_PREFLIGHT_HINT, copilotFreshPreflight, } from "./copilot-fresh-preflight.js";
-import { buildOmpBootstrapPayload, composeBackendArgs, composeFreshCallPrompt, FRESH_CALL_BACKENDS, FRESH_CALL_CALLBACK_TOOL, FRESH_CALL_DELIVERY_TOOL, isSafeFreshCallModel, MODEL_MAX_CHARS, mintNonce, normalizeFreshCallInputs, OMP_BOOTSTRAP_FLAG, OMP_BOOTSTRAP_VERSION, TASK_MAX_CHARS, } from "./fresh-call-composition.js";
-import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, } from "./mux-launch.js";
+import { buildOmpBootstrapPayload, composeBackendArgs, composeFreshCallPrompt, FRESH_CALL_BACKENDS, FRESH_CALL_CALLBACK_TOOL, FRESH_CALL_DELIVERY_TOOL, FRESH_CALL_PROVIDER_HINT, isSafeFreshCallModel, MODEL_MAX_CHARS, mintNonce, normalizeFreshCallInputs, OMP_BOOTSTRAP_FLAG, OMP_BOOTSTRAP_VERSION, TASK_MAX_CHARS, } from "./fresh-call-composition.js";
+import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, SCRUBBED_INHERITED_ENV, } from "./mux-launch.js";
 import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
 import { resolveCodexDefaultSocketPath } from "./native-push/codex-ws-client.js";
 import { OMP_PREFLIGHT_HINT, ompFreshPreflight } from "./omp-fresh-preflight.js";
@@ -188,33 +188,8 @@ export function selectFreshCallSeat(placement) {
         return { tmuxSession: placement.tmuxSession, source: "requested" };
     return null;
 }
-/**
- * The pi identity carrier, scrubbed at the launch seam for EVERY backend (#87 Bundle C).
- *
- * `[측정]` 2026-08-30, private tmux server: a `new-window` pane inherits the tmux SERVER's
- * environment, not the caller's. A server started from a shell that exported `PI_SESSION_ID`
- * hands that value to every window it will ever open — the control run printed
- * `SID=[leaked-uuid]` in a pane the caller never touched. Nothing about the fresh call creates
- * that leak and nothing about it notices: the sibling's own MCP child would read the STALE pair
- * as its authoritative identity and call home as a citizen it is not (`mcp/entwurf-bridge/
- * src/index.ts:692-698` keeps the measured incident — a fresh cell answering with the uuidv7 it
- * found in the environment, confidently and wrong).
- *
- * `-e VAR=` sets the variable EMPTY rather than unsetting it, which tmux has no per-window form
- * for. That is sufficient and not a compromise: every reader of the carrier trims and tests
- * truthiness (`index.ts:212-217`), so empty and absent are the same answer by construction.
- *
- * It is applied to all six backends because the leak is a property of tmux, not of a vendor. A
- * scrub only on the backend whose measurement surfaced it would encode the claim that the other
- * five are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
- * authoritative when the process that owns it exported it ITSELF, and a fresh `pi` sibling does
- * exactly that after this argv has run. This is a fixed seam and deliberately NOT a general env
- * carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping power this
- * rail exists to refuse. Two more `-e` assignments ride beside the scrub: the callback pair
- * (`callback-env.ts`), launcher-computed, so the sibling's first action does not retype an
- * address out of prose.
- */
-const SCRUBBED_INHERITED_ENV = ["PI_SESSION_ID=", "PI_AGENT_ID="];
+// The identity scrub every fresh window carries is `SCRUBBED_INHERITED_ENV` (mux-launch.ts), shared
+// with the resume rail because the leak it closes is a property of tmux, not of either verb.
 /** Launch argv: the leaf's detached-append shape, the identity scrub, optionally `-c` at the
  * resume-symmetric token position (after `-t`, before `-P -F`), the runtime, then the backend's
  * dialect. An omitted cwd adds no `-c` carrier at all.
@@ -478,6 +453,7 @@ const REJECT_HINT = {
     ...CODEX_PREFLIGHT_HINT,
     ...CODEX_CALLER_PREFLIGHT_HINT,
     ...CODEX_CALLER_SEAT_HINT,
+    ...FRESH_CALL_PROVIDER_HINT,
     "no-tmux-context": "this agent is not running inside tmux, so there is no session to open a sibling beside",
     "anchor-malformed": "TMUX_PANE is not a native pane id",
     "anchor-unresolved": "tmux resolved no pane for this agent's anchor",

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-launch.js

@@ -59,6 +59,34 @@ import { APPEND_FORMAT, assertSelector, assertTmuxOk, parseWindowFields, require
 /** The official runtime this rail opens. FIXED: there is no command carrier, and adding one
  * is a separate ownership decision (docs §11), not a parameter. */
 export const PI_RUNTIME_COMMAND = "pi";
+/**
+ * The pi identity carrier, scrubbed at the launch seam for EVERY backend (#87 Bundle C).
+ *
+ * `[측정]` 2026-08-30, private tmux server: a `new-window` pane inherits the tmux SERVER's
+ * environment, not the caller's. A server started from a shell that exported `PI_SESSION_ID`
+ * hands that value to every window it will ever open — the control run printed
+ * `SID=[leaked-uuid]` in a pane the caller never touched. Nothing about the fresh call creates
+ * that leak and nothing about it notices: the sibling's own MCP child would read the STALE pair
+ * as its authoritative identity and call home as a citizen it is not (`mcp/entwurf-bridge/
+ * src/index.ts:692-698` keeps the measured incident — a fresh cell answering with the uuidv7 it
+ * found in the environment, confidently and wrong).
+ *
+ * `-e VAR=` sets the variable EMPTY rather than unsetting it, which tmux has no per-window form
+ * for. That is sufficient and not a compromise: every reader of the carrier trims and tests
+ * truthiness (`index.ts:212-217`), so empty and absent are the same answer by construction.
+ *
+ * It is applied to every fresh backend and to every resumed one (#147 L2) because the leak is a
+ * property of tmux, not of a vendor or a verb. A
+ * scrub only on the backend whose measurement surfaced it would encode the claim that the other
+ * five are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
+ * authoritative when the process that owns it exported it ITSELF, and a fresh `pi` sibling does
+ * exactly that after this argv has run. This is a fixed seam and deliberately NOT a general env
+ * carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping power this
+ * rail exists to refuse. Two more `-e` assignments ride beside the scrub: the callback pair
+ * (`callback-env.ts`), launcher-computed, so the sibling's first action does not retype an
+ * address out of prose.
+ */
+export const SCRUBBED_INHERITED_ENV = ["PI_SESSION_ID=", "PI_AGENT_ID="];
 /** A named precondition failure. Callers surface `reason`; they never soften it into a
  * fallback launch of something else. */
 export class LaunchPreconditionError extends Error {

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-resume-call.js

@@ -1,6 +1,6 @@
 /**
  * mux-resume-call — open ONE window in the caller's own tmux session at a cwd this module did
- * not choose, and hand it argv this module did not author.
+ * not choose, start the backend's FIXED runtime there, and hand it argv this module did not author.
  *
  * ── Why this is a module and not a parameter on fresh-call ──
  *
@@ -15,7 +15,15 @@
  *   visible-resume composition → resume-call → placement leaf (unchanged, carrier-free)
  *   resume-call               -X-> garden identity, records, locks, delivery
  *
- * This module never learns which citizen it is reopening. It sees a cwd and an argv tail.
+ * This module never learns which citizen it is reopening. It sees a backend, a cwd and an argv
+ * tail; the backend only selects a runtime from a closed table (#147 L2).
+ *
+ * ── Tmux only, and said so inside herdr ──
+ *
+ * This is the tmux rail. A caller inside herdr (`HERDR_ENV=1`, herdr's own marker, read for its
+ * exact value as `fresh-call-dispatch` does) is refused by name before anything else: herdr owns
+ * placement there, and an ambient `TMUX` that happens to be set would otherwise put the window in
+ * a session the operator is not looking at. There is no herdr resume rail yet and no fallback.
  *
  * ── The cwd is the whole reason this module owns its own tmux argv ──
  *
@@ -41,15 +49,18 @@
  * to acceptance, not to the product's launch receipt.
  */
 import { classifyTmuxCwd } from "./classify-tmux-cwd.js";
-import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, } from "./mux-launch.js";
+import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, SCRUBBED_INHERITED_ENV, } from "./mux-launch.js";
 import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
-/** The fixed runtime a resume reopens. Only pi stands a control socket up, so only pi has a
- * same-id resume at all — the backend boundary is enforced upstream by
- * `resolveResumeLaunchIdentity`, and this constant is the mux half of the same fact. */
-export const RESUME_CALL_RUNTIME = "pi";
+/** The fixed runtime each resumable backend reopens with. A closed table, not a command input: the
+ * backend boundary is enforced upstream by `resolveResumeLaunchIdentity`, and this is the mux half
+ * of the same fact. */
+export const RESUME_CALL_RUNTIME = { pi: "pi", "claude-code": "claude" };
 /**
- * Launch argv: the leaf's detached-append shape plus `-c`, the runtime, then the caller's flags.
- * `--` is what keeps tmux from reading the runtime or its flags as tmux options.
+ * Launch argv: the leaf's detached-append shape, the fixed identity scrub (`SCRUBBED_INHERITED_ENV`,
+ * the same two assignments every fresh window carries), `-c`, the runtime, then the caller's flags.
+ * `--` is what keeps tmux from reading the runtime or its flags as tmux options. The scrub is not a
+ * carrier: it only empties identity a tmux server may have inherited, and a resumed Claude Code
+ * (which, unlike pi, never re-exports its own) would otherwise present a stale one to its bridge.
  */
 export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs) {
     assertSelector("session", placement.sessionId);
@@ -61,6 +72,7 @@ export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs) {
         "new-window",
         "-d",
         "-a",
+        ...SCRUBBED_INHERITED_ENV.flatMap((assignment) => ["-e", assignment]),
         "-t",
         `${placement.sessionId}:{end}`,
         "-c",
@@ -81,12 +93,14 @@ export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs) {
  * `runtimeArgs` is passed through untouched. This module does not know what `--session` means.
  */
 export function resumeCall(params, env = process.env) {
+    if (env.HERDR_ENV === "1")
+        return { ok: false, reason: "herdr-resume-unsupported" };
     const badCwd = classifyTmuxCwd(params.cwd);
     if (badCwd)
         return { ok: false, reason: badCwd };
     let runtimePath;
     try {
-        runtimePath = resolveRuntimeOnPath(RESUME_CALL_RUNTIME, env);
+        runtimePath = resolveRuntimeOnPath(RESUME_CALL_RUNTIME[params.backend], env);
     }
     catch (err) {
         if (err instanceof LaunchPreconditionError)
@@ -132,7 +146,8 @@ export const RESUME_CALL_REJECT_HINT = {
     "cwd-format-token": "the recorded cwd contains '#', which tmux expands as a format inside -c — it would silently rewrite the path or run a command",
     "cwd-missing": "the recorded cwd no longer exists; tmux would not report this, it would open the window in $HOME and look successful",
     "cwd-not-directory": "the recorded cwd exists but is not a directory",
-    "runtime-unresolved": "pi is not installed on PATH",
+    "herdr-resume-unsupported": "this agent runs inside herdr, and same-id resume has only a tmux rail — nothing was opened in any ambient tmux session",
+    "runtime-unresolved": "the citizen's runtime (pi or claude) is not installed on PATH",
     "runtime-not-absolute": "the resolved runtime path is not absolute",
     "runtime-path-whitespace": "the resolved runtime path contains whitespace, which tmux would re-split",
     "runtime-missing": "nothing exists at the resolved runtime path",

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

@@ -0,0 +1,76 @@
+/** Pi core-side request adapter, not a public tool or authorization boundary.
+ * The caller supplies a CERTIFIED MetaIdentity and owns authorization, self-retire refusal,
+ * target locking and record freshness. No second lock, record scan or receiver admission
+ * implementation lives here. The receiver owns generation/TUI/idle/pending validation.
+ */
+import * as os from "node:os";
+import { controlSocketPathIn, defaultControlSocketDir } from "./control-socket-path.js";
+import { sendRpcCommand } from "./entwurf-control-rpc.js";
+import { SESSION_ID_RE } from "./session-id.js";
+const RECEIVER_REFUSALS = [
+    "target-closing",
+    "target-stale",
+    "target-context-unavailable",
+    "target-non-tui",
+    "target-busy",
+    "target-pending",
+];
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, keys) {
+    const actual = Object.keys(value);
+    return actual.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+/** Closed wire combinations only. A malformed answer AFTER sending cannot prove no action.
+ * SDK request acceptance is not exit, persistence/flush, or no-further-model-activity evidence.
+ */
+export function parsePiRetireResponse(response) {
+    const malformed = { boundary: "unknown", reason: "malformed-response" };
+    if (!object(response) || response.type !== "response" || response.command !== "retire")
+        return malformed;
+    if (Object.keys(response).some((key) => !["type", "command", "success", "data", "error", "id"].includes(key))) {
+        return malformed;
+    }
+    if (Object.hasOwn(response, "id") && typeof response.id !== "string")
+        return malformed;
+    const data = response.data;
+    if (!object(data))
+        return malformed;
+    if (response.success === true && data.boundary === "shutdown-requested") {
+        if (!exactKeys(data, ["boundary"]) || Object.hasOwn(response, "error"))
+            return malformed;
+        return { boundary: "shutdown-requested" };
+    }
+    if (response.success !== false || !exactKeys(data, ["boundary", "reason"]) || response.error !== data.reason) {
+        return malformed;
+    }
+    if (data.boundary === "refused" && RECEIVER_REFUSALS.includes(data.reason)) {
+        return { boundary: "refused", phase: "receiver", reason: data.reason };
+    }
+    if (data.boundary === "unknown" && data.reason === "shutdown-call-failed") {
+        return { boundary: "unknown", reason: "shutdown-call-failed" };
+    }
+    return malformed;
+}
+export async function requestPiRetire(target, expected, options = {}) {
+    if (target.backend !== "pi") {
+        return { boundary: "refused", phase: "preflight", reason: "target-backend-unsupported" };
+    }
+    if (target.gardenId !== expected.gardenId ||
+        target.nativeSessionId !== expected.nativeSessionId ||
+        !SESSION_ID_RE.test(target.gardenId) ||
+        target.nativeSessionId.length === 0) {
+        return { boundary: "refused", phase: "preflight", reason: "target-identity-mismatch" };
+    }
+    const socketPath = controlSocketPathIn(options.controlSocketDir ?? defaultControlSocketDir(os.homedir()), target.gardenId);
+    try {
+        const { response } = await (options.sendRpc ?? sendRpcCommand)(socketPath, { type: "retire", gardenId: target.gardenId, nativeSessionId: target.nativeSessionId }, { timeout: options.timeoutMs ?? 5000 });
+        return parsePiRetireResponse(response);
+    }
+    catch {
+        // The RPC API does not expose whether bytes were written. Even connection errors
+        // are conservatively unknown here; do not infer a safe pre-send refusal or retry.
+        return { boundary: "unknown", reason: "transport-error" };
+    }
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/resume-launch-identity.js

@@ -1,27 +1,33 @@
 /**
- * resume-launch-identity — the RECORD-AUTHORITATIVE half of resuming a pi citizen,
- * kept after the visible-first cut removed everything that used to call it.
+ * resume-launch-identity — the RECORD-AUTHORITATIVE half of a visible same-id resume: garden id →
+ * the meta-record → which native session is this citizen's, and where it lives.
  *
- * It was the preamble of the `spawn-bg` watcher's `spawnChild` (entwurf-v2-spawn-production.ts,
- * deleted with that transport): garden id → the meta-record → the transcript that record
- * claims → the provider/model/cwd that transcript's own header carries. None of that is
- * about being hidden or visible. It is the answer to "which being is this, and which
- * conversation is theirs", and it is the same answer a VISIBLE resume will need.
+ * It began as the preamble of the retired `spawn-bg` watcher (garden id → the meta-record → the
+ * transcript that record claims → the provider/model/cwd that transcript's own header carries).
+ * None of that is about being hidden or visible; it is the answer to "which being is this, and
+ * which conversation is theirs". `entwurf-v2-visible-resume` is its consumer, and
+ * `check-resume-launch-identity` holds the record-integrity rules below — the transcript header id
+ * must equal `record.nativeSessionId`, an addressable read (#52) rather than a plain targeted one,
+ * a recorded ACP provider must resolve its bridge.
  *
- * So this leaf is preserved deliberately, with no consumer in the shipped tree today.
- * `check-resume-launch-identity` holds its contract so the record-integrity rules below —
- * the transcript header id must equal `record.nativeSessionId`, an addressable read
- * (#52) rather than a plain targeted one, a recorded ACP provider must resolve its
- * bridge — cannot rot while they wait.
+ * The domain is pi and claude-code (#147 L2). Both own their transcript and re-attach to the same
+ * record when their native session reopens; this leaf only names that session. For pi it reads
+ * the transcript header (the launch needs its provider/model/cwd). For claude-code it reads no
+ * transcript at all — the vendor owns it, and `claude --resume <id>` needs nothing from it — and
+ * checks only that the recorded path is an absolute file that still exists. Every other backend
+ * is a named refusal: native-push citizens have no resume authority (AGENTS Hard Rule 10), and a
+ * durable host is not reopened through Entwurf.
  *
  * It takes a bare garden id, not a plan: the plan type it used to destructure belonged to
  * the removed transport, and the identity question never needed the rest of it.
  */
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import path from "node:path";
 import { AcpModelNotCuratedError, isCuratedAcpModelId, PROVIDER_ID } from "./acp/model-ids.js";
 import { getEntwurfExplicitExtensions, readSessionIdentity } from "./entwurf-core.js";
 import { readAddressableMetaIdentity } from "./meta-session.js";
+/** The backends with a visible same-id resume. A closed set: nothing outside it is reopened. */
+export const RESUME_BACKENDS = ["pi", "claude-code"];
 /**
  * One of the TWO expected refusals on this leaf: the target is a citizen of a backend that has no
  * same-id resume at all. The other is `AcpModelNotCuratedError` (#128, `acp/model-ids.js`).
@@ -31,23 +37,64 @@ import { readAddressableMetaIdentity } from "./meta-session.js";
  * bridge — and those keep their bare cause-rich `Error`, because a caller cannot act on them
  * except by looking. A Claude Code or agy garden id is different in kind: nothing is broken,
  * the operator simply asked a capability boundary to do something it does not cover, and the
- * honest answer is a named refusal rather than an error report about a store that is fine.
+ * honest answer is a named refusal rather than an error report about a store that is fine. Since
+ * #147 L2 the boundary is `RESUME_BACKENDS`; a Codex, agy, Copilot, OMP or pi-durable garden id is
+ * this refusal.
  *
  * It carries a `reason` so the caller matches on a FIELD. Parsing the message string would make
  * the wording load-bearing, and re-reading the record to ask "was it pi?" would read an address
  * twice and could answer differently the second time.
  */
 export class ResumeBackendUnsupportedError extends Error {
-    reason = "target-not-pi";
+    reason = "target-backend-unsupported";
     backend;
     constructor(gardenId, backend) {
         super(`resume-launch-identity: ${gardenId} is a ${backend} citizen — same-id resume is a host-adapter relaunch ` +
-            `capability, and its domain currently contains backend pi only (only pi stands a control socket up). ` +
-            `This is a capability boundary, not the control-socket rail and not citizen rank.`);
+            `capability, and its domain is ${RESUME_BACKENDS.join(" and ")}. ` +
+            `This is a capability boundary, not citizen rank.`);
         this.name = "ResumeBackendUnsupportedError";
         this.backend = backend;
     }
 }
+/**
+ * Claude Code's session id grammar: a lowercase UUID. The value becomes an argv token after
+ * `--resume`, so anything else — a leading `-`, whitespace, a path — is refused as a bad record
+ * rather than handed to the vendor CLI as something it would parse differently.
+ */
+const CLAUDE_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** A claude-code record → its resume facts. Throws, with its own cause, on a record that cannot be resumed. */
+function resolveClaudeCodeLaunchIdentity(gardenId, record) {
+    if (!CLAUDE_SESSION_ID.test(record.nativeSessionId)) {
+        throw new Error(`resume-launch-identity: ${gardenId} records nativeSessionId ${JSON.stringify(record.nativeSessionId)}, ` +
+            `which is not a Claude Code session id (lowercase UUID) — refusing to hand it to claude --resume.`);
+    }
+    const transcript = record.transcriptPath;
+    if (!transcript || !path.isAbsolute(transcript)) {
+        throw new Error(`resume-launch-identity: ${gardenId} records no absolute transcriptPath (${JSON.stringify(transcript)}) — ` +
+            `the birth hook writes one for every Claude Code session, so this record cannot name a session to resume.`);
+    }
+    let isFile = false;
+    try {
+        isFile = statSync(transcript).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    if (!isFile) {
+        throw new Error(`resume-launch-identity: ${gardenId} recorded transcriptPath "${transcript}" is not a file on disk — ` +
+            `the session's transcript is gone, so claude --resume would open nothing.`);
+    }
+    if (!path.isAbsolute(record.cwd)) {
+        throw new Error(`resume-launch-identity: ${gardenId} records a relative cwd ${JSON.stringify(record.cwd)}.`);
+    }
+    return {
+        backend: "claude-code",
+        nativeSessionId: record.nativeSessionId,
+        cwd: record.cwd,
+        createdAt: record.createdAt,
+        attachIncarnation: record.attachIncarnation,
+    };
+}
 /**
  * Resolve launch identity for a resume. The TARGET is now resolved through the
  * meta-record (#50 C2): `gardenId → record.transcriptPath`. It used to be a global
@@ -79,6 +126,8 @@ export class ResumeBackendUnsupportedError extends Error {
  */
 export function resolveResumeLaunchIdentity(gardenId) {
     const record = readAddressableMetaIdentity(gardenId);
+    if (record.backend === "claude-code")
+        return resolveClaudeCodeLaunchIdentity(gardenId, record);
     if (record.backend !== "pi") {
         throw new ResumeBackendUnsupportedError(gardenId, record.backend);
     }
@@ -136,6 +185,7 @@ export function resolveResumeLaunchIdentity(gardenId) {
     if (provider === PROVIDER_ID && !isCuratedAcpModelId(model))
         throw new AcpModelNotCuratedError(model);
     return {
+        backend: "pi",
         sessionFile,
         cwd: identity.cwd,
         explicitExtensionArgs: explicitExtensions.args,