@junghanacs/entwurf 0.39.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/remote-pair-receive.js

@@ -0,0 +1,123 @@
+/**
+ * remote-pair-receive — the RECEIVING half of #107's one declared remote pair (rail 1).
+ *
+ * The host that owns the target record runs this once per SSH call. It reads one JSON claim
+ * from stdin, checks it against the operator-written pair declaration, and hands a matching
+ * claim to the existing v2 dispatch. The record, owner and deliverability checks stay the
+ * dispatch's own: nothing here writes a mailbox, resolves a rail, or retries.
+ *
+ * Trust model (GLG, #107 D3 (a)): the boundary is the same operator's SSH account. The pair
+ * check is a SCOPE limit, not authentication: a claim whose `from`/`target` is not the declared
+ * pair is refused before any mutation. It does not detect that same account sending the
+ * declared gid falsely; nothing here claims to.
+ *
+ * Sender: the stdin claim is the only sender input. Ambient carriers (`PI_SESSION_ID`,
+ * `PI_AGENT_ID`, sender markers) in the SSH environment are never consulted, so this module
+ * does not import the authoritative-sender resolver at all.
+ *
+ * Display (rail 2b): the envelope keeps the existing `external-mcp` / non-replyable origin, so no
+ * receiver, control renderer or self-address table learns a new origin value. A `remote` field
+ * carries the route label and whether a route back is declared; the mailbox body renders it as
+ * `remote via <route>; reply route declared, not probed` (or `no reply route declared`), with the
+ * sender's cwd marked as a sender-host path. The pilot's display proof is the self-fetch mailbox
+ * body only: whether another rail (a live control socket, native-push injection) shows the same
+ * label is NOT PROVEN here, and nothing in this lane unifies the display across rails.
+ */
+import { requireGardenId } from "./meta-session.js";
+const MESSAGE_CAP = 16000;
+/** Every Unicode control character (the class herdr-fresh-call.ts refuses). A header field is
+ * rendered unescaped into the body's `[entwurf received]` block, so a newline in one could forge a
+ * `session:` or `wants reply:` line. The message body keeps its newlines. */
+const CONTROL_CHAR = /\p{Cc}/u;
+export class RemotePairInputError extends Error {
+}
+function parseObject(text, what) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new RemotePairInputError(`${what}: not JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new RemotePairInputError(`${what}: must be a JSON object`);
+    }
+    return raw;
+}
+function requireExactKeys(obj, keys, what) {
+    const got = Object.keys(obj).sort();
+    const want = [...keys].sort();
+    if (got.length !== want.length || got.some((k, i) => k !== want[i])) {
+        throw new RemotePairInputError(`${what}: keys must be exactly ${want.join(", ")} (got ${got.join(", ")})`);
+    }
+}
+function requireString(obj, key, what) {
+    const v = obj[key];
+    if (typeof v !== "string" || v.length === 0) {
+        throw new RemotePairInputError(`${what}: "${key}" must be a non-empty string`);
+    }
+    return v;
+}
+/** A field that lands in the rendered sender header: non-empty and free of control characters. */
+function requireHeaderString(obj, key, what) {
+    const v = requireString(obj, key, what);
+    if (CONTROL_CHAR.test(v)) {
+        throw new RemotePairInputError(`${what}: "${key}" must not contain control characters`);
+    }
+    return v;
+}
+export function parseRemoteClaim(text) {
+    const what = "remote claim";
+    const obj = parseObject(text, what);
+    requireExactKeys(obj, ["from", "fromAgentId", "fromCwd", "target", "message", "wantsReply"], what);
+    const message = requireString(obj, "message", what);
+    if (message.length > MESSAGE_CAP) {
+        throw new RemotePairInputError(`${what}: "message" exceeds ${MESSAGE_CAP} chars`);
+    }
+    if (typeof obj.wantsReply !== "boolean") {
+        throw new RemotePairInputError(`${what}: "wantsReply" must be a boolean`);
+    }
+    return {
+        from: requireGardenId(obj.from),
+        fromAgentId: requireHeaderString(obj, "fromAgentId", what),
+        fromCwd: requireHeaderString(obj, "fromCwd", what),
+        target: requireGardenId(obj.target),
+        message,
+        wantsReply: obj.wantsReply,
+    };
+}
+/** The scope check. Null = inside the declared pair. */
+export function checkRemotePair(claim, decl) {
+    if (claim.from !== decl.remoteGardenId) {
+        return {
+            reason: "remote-pair-from-mismatch",
+            detail: `from ${claim.from} is not the declared remote ${decl.remoteGardenId}`,
+        };
+    }
+    if (claim.target !== decl.localGardenId) {
+        return {
+            reason: "remote-pair-target-mismatch",
+            detail: `target ${claim.target} is not the declared local ${decl.localGardenId}`,
+        };
+    }
+    return null;
+}
+export function buildRemoteSenderEnvelope(claim, decl, now, replyRoute = "none") {
+    return {
+        sessionId: claim.from,
+        agentId: claim.fromAgentId,
+        cwd: claim.fromCwd,
+        timestamp: now.toISOString(),
+        origin: "external-mcp",
+        replyable: false,
+        remote: { via: decl.ssh, replyRoute },
+    };
+}
+export async function receiveRemoteClaim(claim, decl, deps) {
+    const mismatch = checkRemotePair(claim, decl);
+    if (mismatch)
+        return { kind: "rejected", ...mismatch };
+    const sender = buildRemoteSenderEnvelope(claim, decl, (deps.now ?? (() => new Date()))(), deps.replyRoute);
+    const rendered = await deps.dispatch({ target: claim.target, intent: "fire-and-forget", message: claim.message, wants_reply: claim.wantsReply }, sender);
+    return { kind: "dispatched", isError: rendered.isError, text: rendered.text };
+}