@junghanacs/entwurf 0.39.0 → 0.41.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/retirement-event.js

@@ -0,0 +1,211 @@
+/**
+ * retirement-event — the #106 B machine-readable retirement record's APPEND leaf (#147).
+ *
+ * One target-gid-keyed append-only sidecar per citizen: `<retirementsDir>/<targetGardenId>.jsonl`,
+ * one closed v1 JSON line per event. The event body names both ends explicitly
+ * (`actorGardenId` / `targetGardenId`) — the filename is never the only carrier.
+ *
+ * What this leaf is NOT:
+ *   - not an identity field, liveness fact, dormancy proof, permission or grant. Nothing that
+ *     decides dispatch, facts, peers or resume reads it; there is no production reader at all.
+ *   - not a receipt framework. It appends exactly the event it is handed; minting `eventId`/`at`,
+ *     mapping a dispatch outcome to a summary and the requested/outcome ordering belong to the
+ *     caller's join.
+ *   - not a retention, GC or scanning surface. Absence of a line is `unknown`, never "no retire".
+ *
+ * Path: the directory is an explicit argument. The composition computes it ONCE from its own
+ * fixed sessions directory with `retirementsDirBesideSessions`; this module reads no environment
+ * and resolves no home directory.
+ *
+ * IO boundary (Linux-certified, same stance as `readStoreRecordFile` in meta-session.ts):
+ *   - the directory is created 0700 if absent (parent must exist); an existing entry must be a
+ *     real directory, never a symlink.
+ *   - the file is opened O_WRONLY|O_APPEND|O_CREAT|O_NOFOLLOW|O_NONBLOCK, 0600 on create. A final
+ *     symlink fails (ELOOP), a directory fails (EISDIR), a FIFO never blocks (ENXIO without a
+ *     reader; with one, the fstat check below refuses it).
+ *   - the OPENED fd must be a regular file with exactly one link (a hardlink is not appended to).
+ *   - the whole line is ONE writeSync; a short write is an error. A short write can leave a
+ *     partial tail line in the file — that is reported, never hidden or repaired here.
+ *   - fsyncSync, then close. fsync is a flush request to this file, not a power-loss or
+ *     multi-file transaction guarantee.
+ * Residual, outside this leaf: ancestors of the directory are not checked; an existing file's
+ * mode is not changed; a same-user process that can rename entries in the directory can swap the
+ * name after open (the write still lands on the inode that was checked). The threat model is the
+ * same-user store every other meta sidecar shares.
+ *
+ * Errors: an invalid event or a refused entry throws `RetirementEventError`; a native fs error
+ * (ELOOP, EISDIR, ENXIO, EIO, …) is thrown as it is. Either way the append fails ONCE — no retry.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isValidSessionId } from "./session-id.js";
+export const RETIREMENT_EVENT_VERSION = 1;
+export const RETIREMENTS_DIR_NAME = "meta-retirements";
+export const RETIREMENT_EVENT_SUFFIX = ".jsonl";
+/**
+ * Which outcome statuses each backend can truthfully report: Pi's request boundaries
+ * (`shutdown-requested` is a request ACK, never an exit) and the Claude Code adapter's outcomes
+ * (`exited` is that fd-pinned process only). A cross-domain pair — Pi `exited`, Claude Code
+ * `shutdown-requested` — is refused, so it can never become a durable line. A dispatch-level
+ * unknown is `unknown` on either side.
+ */
+export const RETIREMENT_OUTCOME_STATUSES_BY_BACKEND = {
+    pi: ["shutdown-requested", "refused", "unknown"],
+    "claude-code": ["exited", "refused", "not-signalled", "unknown"],
+};
+export class RetirementEventError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RetirementEventError";
+    }
+}
+const EVENT_ID_RE = /^[0-9a-f]{32}$/;
+/** The shape of `Date#toISOString()` output; calendar validity is the round-trip below. */
+const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const REASON_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const BASE_KEYS = ["v", "kind", "eventId", "at", "actorGardenId", "targetGardenId", "targetBackend"];
+const OUTCOME_KEYS = ["status", "reason"];
+/**
+ * Read a plain object's own DATA properties exactly once. A foreign prototype (and with it an
+ * inherited `toJSON`), an accessor or a symbol key refuses, so what is validated is what is
+ * written: serialization only ever sees the fresh object built from these values.
+ */
+function snapshotPlain(value, what) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new RetirementEventError(`${what} must be an object`);
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        throw new RetirementEventError(`${what} must be a plain object`);
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const fields = new Map();
+    for (const key of Reflect.ownKeys(descriptors)) {
+        if (typeof key !== "string")
+            throw new RetirementEventError(`${what} must not carry symbol keys`);
+        const descriptor = descriptors[key];
+        if (!("value" in descriptor))
+            throw new RetirementEventError(`${what}.${key} must be a data property`);
+        fields.set(key, descriptor.value);
+    }
+    return fields;
+}
+function requireExactKeys(fields, keys, what) {
+    const extra = [...fields.keys()].filter((key) => !keys.includes(key));
+    const missing = keys.filter((key) => !fields.has(key));
+    if (extra.length > 0 || missing.length > 0) {
+        throw new RetirementEventError(`${what} keyset is closed: missing [${missing.join(", ")}], not allowed [${extra.join(", ")}]`);
+    }
+}
+/** Exactly `Date#toISOString()` of a real instant: 2026-02-30 or 24:00 does not round-trip. */
+function isIsoInstant(value) {
+    if (typeof value !== "string" || !AT_RE.test(value))
+        return false;
+    const ms = Date.parse(value);
+    return !Number.isNaN(ms) && new Date(ms).toISOString() === value;
+}
+/**
+ * Validate ONE snapshot of the event and return its exact on-disk bytes (canonical key order, one
+ * UTF-8 line) together with the target id taken from that same snapshot. The append routes the
+ * file by this id, never by re-reading the caller's object.
+ */
+function validateRetirementEvent(event) {
+    const f = snapshotPlain(event, "retirement event");
+    const kind = f.get("kind");
+    if (kind !== "retirement-requested" && kind !== "retirement-outcome") {
+        throw new RetirementEventError(`unknown retirement event kind: ${String(kind)}`);
+    }
+    requireExactKeys(f, kind === "retirement-outcome" ? [...BASE_KEYS, "outcome"] : BASE_KEYS, `${kind} event`);
+    const v = f.get("v");
+    const eventId = f.get("eventId");
+    const at = f.get("at");
+    const actorGardenId = f.get("actorGardenId");
+    const targetGardenId = f.get("targetGardenId");
+    const targetBackend = f.get("targetBackend");
+    if (v !== RETIREMENT_EVENT_VERSION)
+        throw new RetirementEventError(`unsupported event version: ${String(v)}`);
+    if (typeof eventId !== "string" || !EVENT_ID_RE.test(eventId)) {
+        throw new RetirementEventError("eventId must be 32 lowercase hex characters");
+    }
+    if (!isIsoInstant(at))
+        throw new RetirementEventError("at must be a valid Date#toISOString() instant");
+    if (!isValidSessionId(actorGardenId))
+        throw new RetirementEventError("actorGardenId is not a garden id");
+    if (!isValidSessionId(targetGardenId))
+        throw new RetirementEventError("targetGardenId is not a garden id");
+    if (targetBackend !== "pi" && targetBackend !== "claude-code") {
+        throw new RetirementEventError(`unsupported targetBackend: ${String(targetBackend)}`);
+    }
+    const base = { v, kind, eventId, at, actorGardenId, targetGardenId, targetBackend };
+    const line = (body) => ({ bytes: Buffer.from(`${JSON.stringify(body)}\n`, "utf8"), targetGardenId });
+    if (kind === "retirement-requested")
+        return line(base);
+    const o = snapshotPlain(f.get("outcome"), "outcome summary");
+    requireExactKeys(o, OUTCOME_KEYS, "outcome summary");
+    const status = o.get("status");
+    const reason = o.get("reason");
+    const allowed = RETIREMENT_OUTCOME_STATUSES_BY_BACKEND[targetBackend];
+    if (!allowed.includes(status)) {
+        throw new RetirementEventError(`outcome status ${String(status)} is not a ${targetBackend} outcome`);
+    }
+    if (reason !== null && (typeof reason !== "string" || !REASON_RE.test(reason))) {
+        throw new RetirementEventError("outcome reason must be null or a short lowercase token");
+    }
+    return line({ ...base, outcome: { status, reason } });
+}
+/** Validate one event and return its exact on-disk bytes: canonical key order, one UTF-8 line. */
+export function serializeRetirementEvent(event) {
+    return validateRetirementEvent(event).bytes;
+}
+/** Pure path: the sidecar directory beside a FIXED sessions directory. */
+export function retirementsDirBesideSessions(sessionsDir) {
+    if (!path.isAbsolute(sessionsDir))
+        throw new RetirementEventError("sessionsDir must be an absolute path");
+    return path.join(path.dirname(path.resolve(sessionsDir)), RETIREMENTS_DIR_NAME);
+}
+export function retirementEventFile(retirementsDir, targetGardenId) {
+    if (!path.isAbsolute(retirementsDir))
+        throw new RetirementEventError("retirementsDir must be an absolute path");
+    if (!isValidSessionId(targetGardenId))
+        throw new RetirementEventError("targetGardenId is not a garden id");
+    return path.join(retirementsDir, `${targetGardenId}${RETIREMENT_EVENT_SUFFIX}`);
+}
+function ensureRealDirectory(dir) {
+    try {
+        fs.mkdirSync(dir, { mode: 0o700 });
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) {
+        throw new RetirementEventError(`${path.basename(dir)} is not a real directory; refusing to append`);
+    }
+}
+/** Append ONE validated event line to the target's sidecar. Throws once on any failure. */
+export function appendRetirementEvent(retirementsDir, event) {
+    const { bytes, targetGardenId } = validateRetirementEvent(event);
+    const file = retirementEventFile(retirementsDir, targetGardenId);
+    const { O_WRONLY, O_APPEND, O_CREAT, O_NOFOLLOW, O_NONBLOCK } = fs.constants;
+    if (!O_NOFOLLOW || !O_NONBLOCK) {
+        throw new RetirementEventError("this platform exposes no O_NOFOLLOW/O_NONBLOCK, so the append cannot refuse a symlink or FIFO");
+    }
+    ensureRealDirectory(retirementsDir);
+    const fd = fs.openSync(file, O_WRONLY | O_APPEND | O_CREAT | O_NOFOLLOW | O_NONBLOCK, 0o600);
+    try {
+        const st = fs.fstatSync(fd);
+        if (!st.isFile())
+            throw new RetirementEventError(`${path.basename(file)} is not a regular file`);
+        if (st.nlink !== 1)
+            throw new RetirementEventError(`${path.basename(file)} has ${st.nlink} links; refusing`);
+        const written = fs.writeSync(fd, bytes, 0, bytes.length);
+        if (written !== bytes.length) {
+            throw new RetirementEventError(`short write: ${written} of ${bytes.length} bytes; the file may now end in a partial line`);
+        }
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return { bytes: bytes.length };
+}

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

@@ -53,13 +53,26 @@
  * closure (build-bridge → dist), because Node REFUSES strip-types on a `.ts` below
  * node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). The installer picks
  * the artifact by layout (0.12.5), mirroring start.sh / store-doctor.
- * Imports `./lib/meta-session.ts` (+ `./lib/session-id.js`); `rewriteRelativeImportExtensions`
- * rewrites that to `./lib/meta-session.js` in the emitted closure. The installer
- * copies the lib dir alongside this file so `${CLAUDE_PLUGIN_ROOT}` self-locates it.
+ * Imports `./lib/meta-session.ts` and `./lib/entwurf-v2-lock.ts` (+ `./lib/session-id.js`);
+ * `rewriteRelativeImportExtensions` rewrites those to `.js` in the emitted closure. The
+ * installer copies exactly those lib files alongside this file so `${CLAUDE_PLUGIN_ROOT}`
+ * self-locates them.
+ *
+ * RECORD-ARM LOCK (#147 L2 B1). Every write this hook makes to an EXISTING record happens
+ * under a per-gid lock (`defaultMetaRecordArmLocksDir`, the shared `acquireLock` primitive in
+ * its own directory — never the v2 dispatch lock dir, which visible resume holds across its
+ * observation). The garden id is learned by a READ-ONLY certified lookup; a record found
+ * absent is published create-only. On an arm-capable event the lock is held from the upsert
+ * that commits a fresh `attachIncarnation` through the receiver marker that copies it, so two
+ * normal arms (or an arm and a UserPromptSubmit) always finish as a matching record/marker
+ * pair. An arm that cannot take the lock within its bound writes NOTHING and logs ERROR: that
+ * attach is not committed, and a live native process may then exist that no record names — a
+ * boundary, not a refusal. A UserPromptSubmit that finds the lock busy skips its backfill.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { defaultMetaMailboxDir, defaultMetaSessionsDir, isPlausibleOwnerPid, readMetaSenderMarker, removeMetaReceiverMarker, upsertMetaSession, writeMetaReceiverMarker, writeMetaSenderMarker, } from "./lib/meta-session.js";
+import { acquireLock, releaseLock } from "./lib/entwurf-v2-lock.js";
+import { defaultMetaMailboxDir, defaultMetaRecordArmLocksDir, defaultMetaSessionsDir, findCertifiedIdentityByNativeSessionId, isPlausibleOwnerPid, mintAttachIncarnation, readMetaSenderMarker, removeMetaReceiverMarker, UpsertActionMismatchError, upsertMetaSession, writeMetaReceiverMarker, writeMetaSenderMarker, } from "./lib/meta-session.js";
 function logLine(level, message) {
     try {
         // dirname(meta-sessions) == the pi agent dir — no extra resolver export needed.
@@ -71,8 +84,59 @@ function logLine(level, message) {
         /* logging is best-effort; a broken log must not break the session */
     }
 }
+/** The record-arm lock this run holds, released on every exit path (see {@link emit}). */
+let heldArmLock = null;
+/** Arm-capable events wait this long for the record-arm lock; the critical section is a few file writes. */
+const ARM_LOCK_WAIT_MS = 2_000;
+const ARM_LOCK_POLL_MS = 25;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Take the record-arm lock for `gardenId`: ONE attempt, or (arm-capable events) polled up to
+ * {@link ARM_LOCK_WAIT_MS}. A throw from the primitive (its claim could not be written) is
+ * the same answer as busy — the caller writes nothing.
+ */
+function takeArmLock(gardenId, wait) {
+    const dir = defaultMetaRecordArmLocksDir();
+    const deadline = Date.now() + (wait ? ARM_LOCK_WAIT_MS : 0);
+    for (;;) {
+        let detail;
+        try {
+            const acquired = acquireLock(gardenId, { dir });
+            if (acquired.ok) {
+                heldArmLock = acquired.claim;
+                return { ok: true };
+            }
+            detail = acquired.conflict.detail;
+        }
+        catch (err) {
+            detail = err instanceof Error ? err.message : String(err);
+        }
+        if (Date.now() >= deadline)
+            return { ok: false, detail };
+        sleepSync(ARM_LOCK_POLL_MS);
+    }
+}
+function releaseArmLock() {
+    const claim = heldArmLock;
+    if (claim === null)
+        return;
+    heldArmLock = null;
+    try {
+        const outcome = releaseLock(claim, { dir: defaultMetaRecordArmLocksDir() });
+        if (outcome !== "released")
+            logLine("WARN", `record-arm lock release for ${claim.gardenId}: ${outcome}`);
+    }
+    catch (err) {
+        // The holder pid is this short-lived hook, so a lock it failed to unlink is reclaimed
+        // by the next acquirer once this process is gone (same host + ESRCH).
+        logLine("WARN", `record-arm lock release failed for ${claim.gardenId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 /** Emit a hook response on stdout and exit 0. `{}` means "did nothing, do not block startup". */
 function emit(payload) {
+    releaseArmLock();
     process.stdout.write(`${JSON.stringify(payload)}\n`);
     process.exit(0);
 }
@@ -149,6 +213,53 @@ function resolveMetaHookOwnerPid() {
         return null;
     return ownerPid;
 }
+/**
+ * Commit this event's record write and return the garden id (#147 L2 B1). The garden id to
+ * lock is learned READ ONLY; a record found absent is published create-only (a create needs no
+ * lock: its exclusive publish cannot replace anything, and a concurrent publisher turns the
+ * create into a refusal here, never into an unlocked attach). Every write to an EXISTING
+ * record then happens under the record-arm lock, which the caller keeps through the receiver
+ * marker write (released by {@link emit}). An arm-capable event mints its binding in that same
+ * atomic upsert. Lock busy: an arm writes nothing and logs ERROR (admission failure — not a
+ * committed attach, not an armed watch); any other event skips its backfill with a WARN.
+ * Throws on a store defect, exactly as the upsert does.
+ */
+function commitRecord(input, armsWatch, logContext) {
+    let existing = findCertifiedIdentityByNativeSessionId(input.nativeSessionId);
+    if (existing === null) {
+        try {
+            const created = upsertMetaSession({ input, expectAction: "create" });
+            logLine("INFO", `create record ${path.basename(created.path)} (${logContext})`);
+            // Nothing to bind and nothing older to preserve: the create is the whole write.
+            if (!armsWatch)
+                return { gardenId: created.record.gardenId, attachIncarnation: undefined };
+            existing = created.record;
+        }
+        catch (err) {
+            if (!(err instanceof UpsertActionMismatchError))
+                throw err;
+            existing = findCertifiedIdentityByNativeSessionId(input.nativeSessionId);
+            if (existing === null)
+                throw err;
+        }
+    }
+    const locked = takeArmLock(existing.gardenId, armsWatch);
+    if (!locked.ok) {
+        if (armsWatch) {
+            // Admission failure: NOTHING is written, so the store keeps whatever pair it had. This
+            // attach is not committed, and a live process may now hold this session unseen.
+            logLine("ERROR", `record-arm lock busy — attach NOT committed, watch not armed (garden=${existing.gardenId}, ${logContext}): ${locked.detail}`);
+        }
+        else {
+            logLine("WARN", `record-arm lock busy — backfill skipped (garden=${existing.gardenId}, ${logContext}): ${locked.detail}`);
+        }
+        emit({});
+    }
+    const attachIncarnation = armsWatch ? mintAttachIncarnation() : undefined;
+    const result = upsertMetaSession({ input: { ...input, attachIncarnation }, expectAction: "attach" });
+    logLine("INFO", `${result.action} record ${path.basename(result.path)} (${logContext})`);
+    return { gardenId: result.record.gardenId, attachIncarnation };
+}
 function main() {
     let raw;
     try {
@@ -200,13 +311,12 @@ function main() {
         logLine(degradedLevel, `degraded envelope (event=${eventName}, session_id=${sessionId ? "set" : "MISSING"}, transcript_path=${transcriptPath ? "set" : "MISSING"})`);
         emit({});
     }
+    // Arm-capable events commit a fresh binding; every other event preserves it.
+    const armsWatch = armProvenanceFor(eventName) !== null;
     let gardenId;
+    let attachIncarnation;
     try {
-        const result = upsertMetaSession({
-            input: { backend: "claude-code", nativeSessionId: sessionId, transcriptPath, cwd, model },
-        });
-        gardenId = result.record.gardenId;
-        logLine("INFO", `${result.action} record ${path.basename(result.path)} (event=${eventName}, source=${source}, native=${sessionId})`);
+        ({ gardenId, attachIncarnation } = commitRecord({ backend: "claude-code", nativeSessionId: sessionId, transcriptPath, cwd, model }, armsWatch, `event=${eventName}, source=${source}, native=${sessionId}`));
     }
     catch (err) {
         // Best-effort: a broken record store must surface via the doctor, not by
@@ -318,11 +428,15 @@ function main() {
                     nativeSessionId: sessionId,
                     ownerPid,
                     armProvenance,
+                    attachIncarnation,
                 });
                 logLine("INFO", `receiver marker ${gardenId} owner=${ownerPid} arm=${eventName} source=${source}`);
             }
             catch (err) {
-                logLine("WARN", `receiver marker write failed (event=${eventName}, garden=${gardenId}): ${err instanceof Error ? err.message : String(err)}`);
+                // ERROR, after `INFO armed watch` so the hook-log doctor does not read a later arm as
+                // recovery: the record already carries this arm's binding, the marker does not, so the
+                // garden is undeliverable AND a later resume refuses it as unbound.
+                logLine("ERROR", `receiver marker write failed — record binding committed, marker not (event=${eventName}, garden=${gardenId}): ${err instanceof Error ? err.message : String(err)}`);
             }
         }
         else {

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

@@ -98,6 +98,13 @@
  * operator host started outside tmux gets the bridge's named `no-tmux-context` refusal. Exposing the
  * tool is not a caller LIVE proof.
  *
+ * CALLER RESUME (the seventh tool, #147 L1). `entwurf_resume_call` lets this durable citizen reopen a
+ * DORMANT pi or Claude Code citizen under its own garden id (#147 L2), under the bridge's own
+ * single-`target` schema (pinned below). The bridge decides everything else from the target's record,
+ * exactly as for any other caller: other backends have no same-id resume, a live target is refused,
+ * and the window opens in the tmux session this host was launched in. Exposing the tool names no new authority and is not a caller LIVE
+ * proof; it never resumes this durable host itself.
+ *
  * NOT HERE: crash-safe receive. `entwurf_inbox_read` archives a body before the durable tool
  * result commits, so a crash between the two loses that body to the model; recovery settles the
  * call as interrupted and no doorbell rings again. A drain that fails part-way has archived the
@@ -135,12 +142,14 @@ export const PI_DURABLE_TOOL_NAMES = [
     "entwurf_inbox_read",
     "entwurf_callback",
     "entwurf_fresh_call",
+    "entwurf_resume_call",
+    "entwurf_retire_call",
 ];
 const DRAFT_07 = "http://json-schema.org/draft-07/schema#";
 /**
  * The bridge's `tools/list` inputSchemas for the exposed tools (`mcp/entwurf-bridge/src/index.ts`
  * `entwurf_v2` 456-507, `entwurf_self`, `entwurf_peers`, `entwurf_inbox_read`, `entwurf_callback`,
- * `entwurf_fresh_call`),
+ * `entwurf_fresh_call`, `entwurf_resume_call`, `entwurf_retire_call`),
  * as the bridge serialises them.
  * `attach` compares the live list against these and refuses on any difference.
  */
@@ -205,7 +214,7 @@ export const PI_DURABLE_TOOL_SCHEMAS = {
                 minLength: 1,
                 maxLength: 200,
                 pattern: "^[A-Za-z0-9][A-Za-z0-9._/:\\[\\]-]*$",
-                description: "Required runtime model: canonical provider/model for pi, provider/<exact catalog model id> for pi-durable, a Claude Code model id/alias, or a Copilot/OMP/Codex model name.",
+                description: "Required runtime model: canonical provider/model for pi (a bare alias is refused), provider/<exact catalog model id> for pi-durable, a Claude Code model id/alias, or a Copilot/OMP/Codex model name. Neither pi nor pi-durable may name the openrouter provider.",
             },
             task: {
                 type: "string",
@@ -232,6 +241,32 @@ export const PI_DURABLE_TOOL_SCHEMAS = {
         required: ["backend", "model", "task"],
         $schema: DRAFT_07,
     },
+    entwurf_resume_call: {
+        type: "object",
+        properties: {
+            target: {
+                type: "string",
+                minLength: 1,
+                pattern: "^\\d{8}T\\d{6}-[0-9a-f]{6}$",
+                description: "Garden id of the DORMANT pi or Claude Code citizen to reopen (discover with entwurf_peers).",
+            },
+        },
+        required: ["target"],
+        $schema: DRAFT_07,
+    },
+    entwurf_retire_call: {
+        type: "object",
+        properties: {
+            target: {
+                type: "string",
+                minLength: 1,
+                pattern: "^\\d{8}T\\d{6}-[0-9a-f]{6}$",
+                description: "Exact garden id of the Pi or Claude Code target the human operator explicitly requested to retire.",
+            },
+        },
+        required: ["target"],
+        $schema: DRAFT_07,
+    },
 };
 /** Key-order-insensitive JSON, for comparing a schema copy against the bridge's own. */
 function canonicalJson(value) {
@@ -438,6 +473,22 @@ const TOOL_DESCRIPTIONS = {
         "(backend, model and task required; optional cwd and placement). Returns the bridge's LAUNCH receipt or its " +
         "named refusal — not a started runtime, a delivered task or a reply; the sibling's callback names it. Opening " +
         "beside this host needs the tmux pane this host itself was launched in.",
+    entwurf_resume_call: "Reopen ONE dormant pi or Claude Code citizen under its own garden id in a visible tmux window through the " +
+        "entwurf-bridge (target required; the record supplies the session and cwd — no task, no prompt, no turn). " +
+        "Returns the bridge's LAUNCH and OBSERVATION receipts or its named refusal: a live target, another backend, " +
+        "or a Claude Code citizen not proven dormant is refused by name, and opening the window needs the tmux " +
+        "session this host itself was launched in.",
+    entwurf_retire_call: "Only when the human operator explicitly requested this particular target/work: make ONE retirement attempt for that request " +
+        "through the bridge (target only, Pi or Claude Code; self retirement refuses). Development work, a role or " +
+        "a record-backed actor is NOT a grant. Use host approval where provided/configured; " +
+        "Pi and pi-durable have no built-in per-call approval prompt by default. An explicit operator request and " +
+        "agent operating policy are required; attribution and MCP annotations are hints, not grants or proof of approval. " +
+        "No autonomous cleanup, timers or automatic " +
+        "retry of unknown, cancelled or lost results. Do not manually /resume or /clear the target during the request. " +
+        "Pi shutdown-requested is only an ACK, not process exit, flush or model silence. Claude Code exited is that " +
+        "fd-pinned process only, not conversation end, children or flush. The JSON receipt keeps outcome, record and " +
+        "release separate; receipt return does not mean exit, and cancellation does not undo an action. Invoke once " +
+        "per explicitly named target, never infer a roster. This contact does not turn hints into authorization.",
 };
 /** Announce, never push: the notice names the garden and the tool, never the body. */
 function doorbellNotice(gardenId, unread) {

package/mcp/entwurf-bridge/dist/scripts/meta-facts.js

@@ -15,7 +15,7 @@
  *   {
  *     "schemaVersion": 1,          // of THIS projection, not of the records
  *     "storeDir": "/abs/path",
- *     "citizens": [ <full verbatim strict 9-field v3 records, sorted by gardenId> ],
+ *     "citizens": [ <full verbatim strict v3 records, sorted by gardenId> ],
  *     "defects":  [ { "filename", "message" }, … sorted by filename ]
  *   }
  *

package/mcp/entwurf-bridge/dist/scripts/probe-bridge-command.js

@@ -42,6 +42,7 @@ export const EXPECTED_TOOLS = [
     "entwurf_register_native",
     "entwurf_fresh_call",
     "entwurf_resume_call",
+    "entwurf_retire_call",
     "entwurf_callback",
 ];
 const DEFAULT_TIMEOUT_MS = 10_000;

package/mcp/entwurf-bridge/dist/scripts/remote-pair-receive.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * remote-pair-receive — `entwurf remote-pair-receive --pair <absolute file>` (#107 rail 1).
+ *
+ * The receiving host's entry for one declared remote pair. The sending host runs it over one
+ * SSH call and writes one JSON claim to stdin. This entry reads the operator-named pair
+ * declaration once, applies the pair scope check, and hands a matching claim to the existing
+ * v2 dispatch. The scope and trust model are in pi-extensions/lib/remote-pair-receive.ts.
+ *
+ * Scope: `--pair` must name THIS host's own opt-in file (`remotePairOptInPath()`), absolute and
+ * normalized-equal; any other path — even a valid declaration — is exit 2. That one file is the pair
+ * this host accepts and, because it names the sender's host as its route, the declared route back.
+ * The sender's declaration carries the path only so the argv shape is explicit; it selects nothing.
+ *
+ * EXIT CONTRACT (stdout carries a JSON receipt line only where named):
+ *   0 dispatched, the dispatch did not report an error — receipt on stdout
+ *   4 dispatched, the dispatch reported an error (its text says what is known, e.g. a
+ *     rejection or `retry-safe: false` after a possible write) — receipt
+ *   3 refused by the pair scope check, no dispatch ran — receipt
+ *   2 --pair is not this host's opt-in, the opt-in is absent/broken, or the claim is invalid; no
+ *     dispatch ran — `{kind:"invalid"}` receipt;
+ *     wrong argv is ALSO 2 but prints usage on stderr only, with no receipt
+ *   1 an uncaught dispatch/store throw (crash, don't warn) — no receipt; stderr carries the
+ *     error. The sending host reads that as indeterminate.
+ */
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { runAndRenderEntwurfV2FromSurface } from "../pi-extensions/lib/entwurf-v2-surface.js";
+import { parseRemoteClaim, receiveRemoteClaim, } from "../pi-extensions/lib/remote-pair-receive.js";
+import { readRemotePairOptIn, remotePairOptInPath } from "../pi-extensions/lib/remote-pair-send.js";
+function emit(receipt, code) {
+    process.stdout.write(`${JSON.stringify(receipt)}\n`);
+    process.exit(code);
+}
+const args = process.argv.slice(2);
+if (args.length !== 2 || args[0] !== "--pair") {
+    console.error("usage: entwurf remote-pair-receive --pair <this host's opt-in file>  (claim JSON on stdin)");
+    process.exit(2);
+}
+const pairFile = args[1];
+let decl;
+let claim;
+try {
+    // The scope is THIS host's own opt-in, never a file the sender picks: `--pair` must name it
+    // exactly (absolute, normalized), and that one file is read for this receive.
+    const own = remotePairOptInPath();
+    if (!path.isAbsolute(pairFile) || path.normalize(pairFile) !== own) {
+        throw new Error(`--pair must be this host's opt-in file ${own} (got ${pairFile})`);
+    }
+    const route = readRemotePairOptIn(own);
+    if (route === null)
+        throw new Error(`this host has no remote pair opt-in (${own} is absent)`);
+    decl = { remoteGardenId: route.remoteGardenId, ssh: route.ssh, localGardenId: route.localGardenId };
+    claim = parseRemoteClaim(readFileSync(0, "utf8"));
+}
+catch (err) {
+    emit({ kind: "invalid", detail: err instanceof Error ? err.message : String(err) }, 2);
+}
+const receipt = await receiveRemoteClaim(claim, decl, {
+    dispatch: (params, sender) => runAndRenderEntwurfV2FromSurface(params, { senderProvider: () => sender }),
+    // The scope file IS this host's own opt-in, and it names the sender's host as its route: a
+    // matching claim always has a declared route back. Declared, not probed.
+    replyRoute: "declared",
+});
+emit(receipt, receipt.kind === "rejected" ? 3 : receipt.isError ? 4 : 0);