@junghanacs/entwurf 0.39.0 → 0.41.0

package/pi-extensions/meta-bridge-hook.ts

@@ -53,20 +53,38 @@
  * 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 { acquireLock, type LockClaim, releaseLock } from "./lib/entwurf-v2-lock.ts";
 import {
 	defaultMetaMailboxDir,
+	defaultMetaRecordArmLocksDir,
 	defaultMetaSessionsDir,
+	findCertifiedIdentityByNativeSessionId,
 	isPlausibleOwnerPid,
+	type MetaIdentityMintInput,
 	type MetaReceiverArmProvenance,
+	mintAttachIncarnation,
 	readMetaSenderMarker,
 	removeMetaReceiverMarker,
+	UpsertActionMismatchError,
 	upsertMetaSession,
 	writeMetaReceiverMarker,
 	writeMetaSenderMarker,
@@ -97,8 +115,62 @@ function logLine(level: LogLevel, message: string): void {
 	}
 }
 
+/** The record-arm lock this run holds, released on every exit path (see {@link emit}). */
+let heldArmLock: LockClaim | null = 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: number): void {
+	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: string, wait: boolean): { ok: true } | { ok: false; detail: string } {
+	const dir = defaultMetaRecordArmLocksDir();
+	const deadline = Date.now() + (wait ? ARM_LOCK_WAIT_MS : 0);
+	for (;;) {
+		let detail: string;
+		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(): void {
+	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: Record<string, unknown>): never {
+	releaseArmLock();
 	process.stdout.write(`${JSON.stringify(payload)}\n`);
 	process.exit(0);
 }
@@ -174,6 +246,59 @@ function resolveMetaHookOwnerPid(): number | 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: MetaIdentityMintInput,
+	armsWatch: boolean,
+	logContext: string,
+): { gardenId: string; attachIncarnation: string | undefined } {
+	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(): void {
 	let raw: string;
 	try {
@@ -230,16 +355,16 @@ function main(): void {
 		emit({});
 	}
 
+	// Arm-capable events commit a fresh binding; every other event preserves it.
+	const armsWatch = armProvenanceFor(eventName) !== null;
 	let gardenId: string;
+	let attachIncarnation: string | undefined;
 	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
 		// breaking the user's session open. Log and continue with no arm. This is
@@ -362,12 +487,16 @@ function main(): void {
 					nativeSessionId: sessionId,
 					ownerPid,
 					armProvenance,
+					attachIncarnation,
 				});
 				logLine("INFO", `receiver marker ${gardenId} owner=${ownerPid} arm=${eventName} source=${source}`);
 			} catch (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(
-					"WARN",
-					`receiver marker write failed (event=${eventName}, garden=${gardenId}): ${err instanceof Error ? err.message : String(err)}`,
+					"ERROR",
+					`receiver marker write failed — record binding committed, marker not (event=${eventName}, garden=${gardenId}): ${err instanceof Error ? err.message : String(err)}`,
 				);
 			}
 		} else {

package/pi-extensions/meta-bridge-pi-durable.ts

@@ -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
@@ -156,6 +163,8 @@ export const PI_DURABLE_TOOL_NAMES = [
 	"entwurf_inbox_read",
 	"entwurf_callback",
 	"entwurf_fresh_call",
+	"entwurf_resume_call",
+	"entwurf_retire_call",
 ] as const;
 export type PiDurableToolName = (typeof PI_DURABLE_TOOL_NAMES)[number];
 
@@ -164,7 +173,7 @@ 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.
  */
@@ -235,7 +244,7 @@ export const PI_DURABLE_TOOL_SCHEMAS: Readonly<Record<PiDurableToolName, Readonl
 				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.",
+					"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",
@@ -266,6 +275,33 @@ export const PI_DURABLE_TOOL_SCHEMAS: Readonly<Record<PiDurableToolName, Readonl
 		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. */
@@ -748,6 +784,24 @@ const TOOL_DESCRIPTIONS: Record<PiDurableToolName, string> = {
 		"(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. */

package/run.sh

@@ -224,7 +224,7 @@ Usage:
   ./run.sh smoke-agy-native-push-live  # 봉인 8 LIVE acceptance for the native-push (agy) rail — OUT of pnpm check, needs LIVE=1 + AGY_CONVERSATION_ID (a live agy conversation). Drives the REAL antigravity adapter + register core + runEntwurfV2 (production deps): doctor-static preflight (dangling→FAIL, the ③ gate), probe route, register create/attach idempotency, fire→native-push delivered, post-send re-probe (D7 partial), bogus-conv→native-push-probe-indeterminate. Meta-store isolated to a temp dir (only the agy round-trip is real; no real-store residue). COST FENCE: open that agy conversation on gemini-3.6-flash (free account) — never a Pro tier; entwurf never selects the agy model and no assertion reads it. LIVE=1 AGY_CONVERSATION_ID=<convId> ./run.sh smoke-agy-native-push-live
   ./run.sh smoke-codex-native-push-live # on-demand LIVE acceptance for Codex native-push — needs LIVE=1 + CODEX_LIVE_THREAD_ID loaded by a visible TUI attached to the default app-server; probes the real UDS, routes through production runEntwurfV2, queues one exact-token turn without retry, re-probes, and leaves the visible TUI to show the model result
   ./run.sh smoke-codex-fresh-live    # #95 RELEASE MUST: record-backed receipt fixture -> PUBLIC initial Pi fresh/callback in a session S that is NOT the app-server's -> Pi PUBLIC omitted-placement Codex fresh/exact callback, also in S -> Pi-to-Codex addressed native-push v2 -> Codex PUBLIC omitted-placement AND omitted-cwd fresh Pi/exact callback IN S beside its own TUI (lane B claim: the app-server env names another session, so S can only come from the caller's pane title; lane C claim: no cwd was asked for, so the directory can only come from the Codex caller's own record — and the Codex thread's own rollout session_meta.cwd, its pane and its record must all be the requested scratch, not the app-server's repo) -> Codex final v2 evidence. Needs LIVE=1 + ENTWURF_CODEX_APP_SERVER_PID + ENTWURF_CODEX_FRESH_MODEL + ENTWURF_CODEX_FRESH_PI_MODEL, and its ONE stable launch directory answered 'Trust' once in a plain codex -C there: codex records its direct consent per exact directory, so a directory with no answer at all opens a consent screen instead of a first turn. Only THIS gate treats that as a precondition and fails up front as codex-launch-cwd-undecided rather than timing out on a callback — an ordinary entwurf_fresh_call only prints the note and opens the window, because a human can answer the screen. The smoke PRINTS that directory as 'launch-cwd <dir>' and repeats it in the failure as a ready-to-run repair command — do not retype it from memory, and do not write it as \$TMPDIR/... (os.tmpdir() falls back to /tmp when TMPDIR is unset, so that spelling names a different directory in the filesystem root). The PID names the operator-owned app-server, which must sit in a DIFFERENT session from S; the smoke checks/prints all four coordinates, never starts/stops/guesses the app-server/session, never reads screen text, interrupts only its exact still-running Codex turn, and cleans only receipt-named window ids
-  ./run.sh smoke-mux-lifecycle-live  # RELEASE MUST integrated LIVE lifecycle acceptance for mux, through the REAL MCP surface — OUT of pnpm check, needs LIVE=1 and spends model turns (two pi siblings: native + recorded-ACP provider, each resumed once; one Claude Code sibling). tools/call fresh_call -> nonce callback sender envelope -> v2 control send landing in the sibling's own transcript -> resume_call REFUSED while live (window count unchanged) -> stable-handle close (pane gone, socket dead, record kept) -> dormant delivery refused honestly -> public entwurf_resume_call with LAUNCH and OBSERVATION receipts kept apart, same-gid socket alive, zero new citizens, zero lock residue, resumed pane_start_path == RECORD cwd (separate tmux query), transcript byte-identical across the resume -> v2 recall of the pre-close fact. claude-code resume refused target-not-pi, no window opened and no lock residue. LIVE=1 ./run.sh smoke-mux-lifecycle-live
+  ./run.sh smoke-mux-lifecycle-live  # RELEASE MUST integrated LIVE lifecycle acceptance for mux, through the REAL MCP surface — OUT of pnpm check, needs LIVE=1 and spends model turns (two pi siblings: native + recorded-ACP provider, each resumed once; one Claude Code sibling). tools/call fresh_call -> nonce callback sender envelope -> v2 control send landing in the sibling's own transcript -> resume_call REFUSED while live (window count unchanged) -> stable-handle close (pane gone, socket dead, record kept) -> dormant delivery refused honestly -> public entwurf_resume_call with LAUNCH and OBSERVATION receipts kept apart, same-gid socket alive, zero new citizens, zero lock residue, resumed pane_start_path == RECORD cwd (separate tmux query), transcript byte-identical across the resume -> v2 recall of the pre-close fact. claude-code resume of the still-live sibling refused target-live, no window opened and no lock residue (its dormant same-id resume is deterministic-only, #147 L2). LIVE=1 ./run.sh smoke-mux-lifecycle-live
   ./run.sh check-meta-facts            # deterministic gate for the meta-facts projection (#65): drives the REAL CLI — full-record join, parse-before-uniqueness, no-winner duplicates, drift/symlink/invalid-UTF-8 defects in-band, deterministic bytes, exit contract 0/2/3, dispatch+emit reachability
   ./run.sh check-herdr-plugin          # deterministic gate for the #116 M2-b herdr plugin (`plugins/herdr/`): STATIC manifest shape for herdr 0.9.0 + the forbidden sections ([[startup]]/[[events]]/[[actions]]/[[link_handlers]]) asserted absent ([[build]] is check-herdr-plugin-build's subject since #116 M3-b3); BEHAVIOURAL drive of the REAL pane entry against a stub `entwurf` and stub HERDR_BIN_PATH that LOG every call — exactly one `herdr integration status` + one `entwurf peer-facts` + one `herdr agent list` per open, in that order (counted, not claimed), through ONE spawn call site; the four blocks each naming their own owner/observation time with no aggregate verdict; the D3=C fallback reading the activation ledger from the path its WRITER owns (XDG state, never the runtime's data root) and only when the phase is `active`, with ENTWURF_BIN and PATH still winning outright; the citizen axis alone skipping by name when no binary is reachable; every broken-evidence state a named red rather than a crash or an empty table, and a selected herdr atom that is `outdated`/`needs repair` as block [1]'s OWN red (`not installed` stays a reported skip); ambiguous never first-wins, diagnostics shown, activity in its own column, and zero writes to the plugin state/config dirs. No herdr binary, no Entwurf install
   ./run.sh check-herdr-runtime-bootstrap # deterministic gate for the #116 M3-b1 runtime leaf (`plugins/herdr/lib/runtime-bootstrap.mjs`): the Entwurf-owned stable active root as a REAL directory (nothing is put on PATH — the scoped wiring above names ABSOLUTE commands under it), ownership decided BEFORE the first mkdir, disk facts from lstat (a dangling symlink is not 'absent' and a link into another tree is not a directory), exact name@version + compiled entry + all three required bins present AND executable + a real `check-bridge`, the plugin-owned artifact lock coherent with the checkout, the owned npm cache and --ignore-scripts, a CERTIFIED journal (non-object/array/scalar/blank-identity/phase-contradicting-digest all refused) as the only ownership proof, all EIGHT active/staging/previous combinations named, the last good runtime never lost (torn swap AND corrupt-active beside a good backup), prior provenance carried across an install that may not finish, a failed candidate leaving the running runtime byte-identical, idempotent same-spec reinstall, a journal believed only while the disk backs it, a preflight-then-mutate inverse taking runtime last, and the refusal to record Herdr's commit as ours. NETWORK ZERO, npm ZERO — it drives a FIXTURE package, so the ACTUAL package proof lives in check-pack-install
@@ -328,6 +328,9 @@ Usage:
   ./run.sh meta-bridge-prune          # 1.0.0 meta-bridge Phase 4: LISTING-ONLY store hygiene — classify orphan/stale/ambiguous/keep, print manual rm commands, delete NOTHING ([dir] [--ttl-days N])
   ./run.sh meta-bridge-fresh-cut      # the ONE generation verb (the verb every v3-only rejection names): quiesce-check live sockets/markers/native-push conversations (refusing any surface it cannot inspect), archive meta-sessions/ + meta-mailbox/ to `<dir>.archive-<ts>`, clear dead transport residue, open an empty v3 generation. No migration, no restore — the archive is forensic only. EXIT CONTRACT (#54, `--help` prints it): 0 complete / 1 NOTHING MOVED (re-run, do not setup) / 2 usage / 3 cut transition incomplete (inspect) / 4 cut complete but residue cleanup failed (`setup` may run; re-run only before new citizen birth, otherwise remove residue manually)
   ./run.sh meta-facts                 # #65 owner-normalized READ-ONLY store projection: deterministic JSON {schemaVersion:1, storeDir, citizens: full v3 records sorted by gardenId, defects: {filename,message}} — THE listing contract emitted by the owner so consumers stop copying the certification. No liveness/sockets/transcript contents. EXIT: 0 readable (defects in-band; missing store = empty), 2 usage, 3 unreadable ([dir])
+  ./run.sh check-remote-pair-installed # #107 rail 3, CHECKOUT-ONLY: install a caller-supplied candidate tarball (--tgz <abs>) into a sandboxed consumer prefix, check its compiled remote-pair surface, run the installed `entwurf remote-pair-receive` (usage exit 2 = twin reached), run the T2 roundtrip cells against the installed bridge+entry, and audit that the subject processes resolve every module inside the consumer prefix (with a checkout control). Never repacks; no real ssh, no model
+  ./run.sh check-remote-pair-installed-audit # #107 rail 3: the deterministic counterpart of check-remote-pair-installed — its checkout-invisibility acceptance primitive proven on synthetic logs (real path, root boundary). In check:vitest
+  ./run.sh remote-pair-receive        # #107 rail 1: the RECEIVING half of one operator-declared remote pair. Reads ONE JSON claim {from,fromAgentId,fromCwd,target,message,wantsReply} on stdin, refuses a from/target outside the declared pair before any mutation (a scope limit under the same-operator SSH account trust model, not authentication), then hands a match to the existing v2 dispatch. Ambient sender carriers are never read. Installed, run_ts runs its compiled twin (dist/scripts/remote-pair-receive.js). EXIT: 0 dispatched / 4 dispatched, the dispatch reported an error (delivery not inferred) / 3 pair refused / 2 invalid claim or declaration (JSON receipt) or wrong argv (usage on stderr, no receipt) / 1 uncaught dispatch or store throw (no receipt; the sender reads it as indeterminate) (--pair <absolute declaration file>)
   ./run.sh peer-facts                 # #116 M2-a owner-normalized READ-ONLY peer projection: the same listEntwurfFacts provider through the same renderer entwurf_peers uses, emitted as deterministic JSON {schemaVersion:1, storeDir, peers, diagnostics} so a consumer never re-implements the placement join (whose pi half is a measured vendor floor). NOT the same bytes as an entwurf_peers call and deliberately so: that surface is a human listing (observationLimit, text over the wire), this is a machine projection with UNBOUNDED observation, because a rationed row says `unobserved` and a machine cannot tell that from "nobody could look". `placement` stays a STRUCTURED tagged union ({kind:"herdr-pane",paneId} / unobserved / none / ambiguous) — never the human `herdr <pane>` string. Publishes NO socket coordinate (ENTWURF_DIR selects what is PROBED, #50 C4) and NO herdr agent_status / interactive_ready / screen text. One placement read per listing, no watcher. EXIT: 0 readable (diagnostics in-band; missing store = empty), 2 usage, 3 unreadable ([dir])
   ./run.sh meta-bridge-managed-keys   # 0.10.0 meta-bridge: print the SSOT of settings keys entwurf OWNS (consumers read this to stay disjoint — keyset-owner invariant)
   ./run.sh check-keyset-overlap <fragment.json...>  # 0.10.0 meta-bridge: PREVENTIVE keyset guard — fail if a consumer fragment collides with any pi-owned key (cross-repo; not in pnpm check)
@@ -1340,6 +1343,44 @@ check_control_send_receipt() {
   run_vitest pi-extensions/lib/control-send-receipt.test.ts
 }
 
+check_control_retire() {
+  # Mutant execution coordinate only; the existing beside glob owns test discovery.
+  section "Pi idle-only shutdown boundary (mutant execution coordinate)"
+  run_vitest pi-extensions/lib/control-retire.test.ts
+}
+
+check_pi_retire_request() {
+  # Mutant execution coordinate only; the existing beside glob owns test discovery.
+  section "Pi retire request adapter (mutant execution coordinate)"
+  run_vitest pi-extensions/lib/pi-retire-request.test.ts
+}
+
+check_cc_retire_pidfd() {
+  # MUTANT EXECUTION COORDINATE, not a discovery path — check-tests-beside-behavior finds the test
+  # like every other beside lane. This case exists because the #147 G3 CCRETIRE-* mutants name it as
+  # gate argv; it stays in check:contracts for the same reason as check-control-send-receipt.
+  section "Linux pidfd retire helper (mutant execution coordinate)"
+  run_vitest pi-extensions/lib/cc-retire-pidfd.test.ts
+}
+
+check_cc_retire_request() {
+  # Mutant execution coordinate only; the existing beside glob owns test discovery.
+  section "Claude Code retire request adapter (mutant execution coordinate)"
+  run_vitest pi-extensions/lib/cc-retire-request.test.ts
+}
+
+check_retirement_event() {
+  # Mutant execution coordinate only; the existing beside glob owns test discovery.
+  section "Retirement append leaf (mutant execution coordinate)"
+  run_vitest pi-extensions/lib/retirement-event.test.ts
+}
+
+check_entwurf_v2_retire() {
+  # Mutant execution coordinate only; the existing beside glob owns test discovery.
+  section "Requested retirement dispatcher and production binding (mutant execution coordinate)"
+  run_vitest pi-extensions/lib/entwurf-v2-retire.test.ts pi-extensions/lib/entwurf-v2-retire-production.test.ts
+}
+
 check_win32_preview() {
   # MUTANT EXECUTION COORDINATE, not a discovery path — the Windows preview's (#78) loader and
   # platform wiring tests are found by check-tests-beside-behavior like every other beside-behaviour
@@ -1452,6 +1493,15 @@ check_acp_foreground_only() {
   run_vitest pi-extensions/lib/acp/backend-adapter.test.ts
 }
 
+check_fresh_call_provider() {
+  # NOT a discovery path — check-tests-beside-behavior finds the test by glob. This case is the
+  # MUTANT EXECUTION COORDINATE for the #76 provider claims in scripts/mutants/fresh-call-dispatch.json
+  # (same reasoning as check_entwurf_resume_args above): pi and pi-durable refuse a model that names
+  # the openrouter provider, and pi refuses one that names no provider, at the dispatch root.
+  section "fresh-call provider contract (mutant execution coordinate)"
+  run_vitest pi-extensions/lib/fresh-call-dispatch.test.ts
+}
+
 check_acp_set_model_readback() {
   # NOT a discovery path — check-tests-beside-behavior finds the test by glob. This case is the
   # MUTANT EXECUTION COORDINATE for scripts/mutants/acp-set-model-readback.json (#128): the claude
@@ -1667,7 +1717,8 @@ smoke_mux_lifecycle_live() {
   # resumed pane_start_path == the RECORD's cwd (separate tmux query, never pane text), and the
   # transcript byte-identical across the resume itself -> entwurf_v2 recalling the fact from
   # BEFORE the close, which is what proves the same CONVERSATION returned. Claude Code runs the
-  # callback+mailbox half and its resume is refused as target-not-pi with no window opened and no lock residue.
+  # callback+mailbox half and its resume, while that sibling is still live, is refused as target-live with no
+  # window opened and no lock residue (#147 L2: Claude Code's dormant resume is certified deterministically).
   # Fixture-fenced writes (XDG, four meta roots, v2 lock dir, control socket via fixture HOME);
   # the runtime auth roots stay REAL and sibling transcripts remain in the real pi agent dir as
   # evidence. Private tmux server per cell, bounded teardown, operator real-root entry sets
@@ -2728,7 +2779,7 @@ EOF
 check_claude_floor_coherence() {
   # #51 policy A. The Claude Code floor is a THREE-PART version, unlike the Node
   # floor's major lane: the discriminator lives in the patch position (2.1.138 drops
-  # `args`, 2.1.139 introduces the exec form, 2.1.217 is the version actually proven
+  # `args`, 2.1.139 introduces the exec form, 2.1.217 is the version the exec form was proven on
   # in a live session). So it cannot borrow check-node-floor-coherence's major-only
   # comparison and needs its own binding.
   #
@@ -3387,6 +3438,17 @@ check_acp_sdk_surface() {
   run_vitest test/acp-sdk-surface.contract.test.ts
 }
 
+check_remote_pair_installed_audit() {
+  # #107 rail 3. The deterministic counterpart of `check-remote-pair-installed`: that gate needs a
+  # caller-supplied tarball, so it cannot run in the floor or carry mutants, and its
+  # checkout-invisibility verdict rests on one acceptance primitive
+  # (scripts/lib/remote-pair-installed-audit.ts). This proves that primitive on tiny synthetic
+  # logs and files. `test/**` is not discovered by check-tests-beside-behavior, so it needs this
+  # public coordinate. Zero network, zero child process.
+  section "remote-pair installed-closure audit (synthetic logs)"
+  run_vitest test/remote-pair-installed-audit.test.ts
+}
+
 check_pi_queue_oracle() {
   # #120 P2. The PUBLIC execution coordinate for `test/pi-queue.oracle.test.ts`, and the reason it
   # needs one: the discovery door below selects `pi-extensions/**/*.test.ts` and
@@ -3829,6 +3891,12 @@ check_pack() {
     # out: the placement join it emits is the copy a herdr-side consumer would
     # otherwise fork, and such a consumer runs against an installed host.
     "mcp/entwurf-bridge/dist/scripts/peer-facts.js"
+    # #107 — the receiving host's entry the sender's ssh runs (run_ts twin), plus the three
+    # remote-pair libs the bridge's entwurf_v2 handler and that entry import.
+    "mcp/entwurf-bridge/dist/scripts/remote-pair-receive.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-receive.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-send.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-transport.js"
     # #87 Bundle B — omp-receive-doctor drives this operator projection through
     # run.sh, so installed node_modules must have the compiled twin too.
     "mcp/entwurf-bridge/dist/scripts/omp-receive-facts.js"
@@ -4570,6 +4638,12 @@ _check_pack_install_impl() {
     "mcp/entwurf-bridge/dist/scripts/meta-facts.js"
     # #116 M2-a — the owner-normalized peer projection (see check-pack).
     "mcp/entwurf-bridge/dist/scripts/peer-facts.js"
+    # #107 — the receiving host's entry the sender's ssh runs (run_ts twin), plus the three
+    # remote-pair libs the bridge's entwurf_v2 handler and that entry import.
+    "mcp/entwurf-bridge/dist/scripts/remote-pair-receive.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-receive.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-send.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-transport.js"
     # #87 Bundle B — omp-receive-doctor reaches this through the installed dispatcher.
     "mcp/entwurf-bridge/dist/scripts/omp-receive-facts.js"
     # 0.12.5 — node_modules-safe plugin hook + lib (see check-pack). The installed
@@ -5355,7 +5429,7 @@ sys.exit(0 if any(isinstance(s,str) and s.rstrip('/')== '$npm2_pkg' for s in src
 #!/usr/bin/env bash
 printf '%s\n' "$*" >> "${FAKE_CLAUDE_LOG:?}"
 case "$1${2:+ $2}" in
-  "--version") echo "2.1.217 (Claude Code)" ;;
+  "--version") echo "2.1.306 (Claude Code)" ;;
   "plugin validate") : ;;
   "plugin uninstall") : ;;
   "plugin marketplace") : ;;
@@ -5431,6 +5505,8 @@ SH
   mkdir -p "$nm_probe/lib"
   cp "$installed_hook" "$nm_probe/meta-bridge-hook.js"
   cp "$stable_asm/entwurf-meta-receive/lib/meta-session.js" "$nm_probe/lib/meta-session.js"
+  # The real installer already supplies this hook import; the node_modules probe must too.
+  cp "$stable_asm/entwurf-meta-receive/lib/entwurf-v2-lock.js" "$nm_probe/lib/entwurf-v2-lock.js"
   cp "$stable_asm/entwurf-meta-receive/lib/session-id.js" "$nm_probe/lib/session-id.js"
   cp "$stable_asm/entwurf-meta-receive/entwurf-capabilities.json" "$nm_probe/entwurf-capabilities.json"
   local probe_env='{"session_id":"pack-probe","transcript_path":"/tmp/x.jsonl","cwd":"/tmp","hook_event_name":"SessionStart","model":{"id":"probe"}}'
@@ -5669,7 +5745,7 @@ function finish(trimmed) {
   // gate that exists to catch "green clone, dead consumer". Equality also catches the
   // other direction the narrow-surface rule cares about: an extra or duplicated verb
   // reaching hosts without a decision. Written sorted; `names` is sorted above.
-  const EXPECT_TOOLS = ['entwurf_callback', 'entwurf_fresh_call', 'entwurf_inbox_read', 'entwurf_peers', 'entwurf_register_native', 'entwurf_resume_call', 'entwurf_self', 'entwurf_v2'];
+  const EXPECT_TOOLS = ['entwurf_callback', 'entwurf_fresh_call', 'entwurf_inbox_read', 'entwurf_peers', 'entwurf_register_native', 'entwurf_resume_call', 'entwurf_retire_call', 'entwurf_self', 'entwurf_v2'];
   if (names.length !== EXPECT_TOOLS.length || EXPECT_TOOLS.some((n, i) => names[i] !== n)) {
     console.error('installed MCP tool set MISMATCH — want exactly [' + EXPECT_TOOLS.join(',') + '] got [' + names.join(',') + ']');
     process.exit(1);
@@ -6231,12 +6307,12 @@ function finishOk(trimmed) {
   }
   const names = tools.map((t) => t?.name).sort();
   // EXACT set, not a floor. This is the assertion behind the operator-facing claim that
-  // `entwurf check-bridge` proves the installed bytes list the eight garden tools — and
+  // `entwurf check-bridge` proves the installed bytes list the nine garden tools — and
   // under an installed package this launcher IS the dist branch of start.sh, so a subset
   // check here let an artifact missing entwurf_fresh_call / entwurf_resume_call read as a
   // green bridge. Equality also refuses an undecided extra verb. Written sorted; `names`
   // is sorted above.
-  const expected = ['entwurf_callback', 'entwurf_fresh_call', 'entwurf_inbox_read', 'entwurf_peers', 'entwurf_register_native', 'entwurf_resume_call', 'entwurf_self', 'entwurf_v2'];
+  const expected = ['entwurf_callback', 'entwurf_fresh_call', 'entwurf_inbox_read', 'entwurf_peers', 'entwurf_register_native', 'entwurf_resume_call', 'entwurf_retire_call', 'entwurf_self', 'entwurf_v2'];
   if (names.length !== expected.length || expected.some((n, i) => names[i] !== n)) {
     console.error(`MCP tool set MISMATCH — want exactly [${expected.join(',')}] got [${names.join(',')}]`);
     process.exit(1);
@@ -7476,6 +7552,24 @@ case "$cmd" in
   check-control-send-receipt)
     check_control_send_receipt
     ;;
+  check-control-retire)
+    check_control_retire
+    ;;
+  check-pi-retire-request)
+    check_pi_retire_request
+    ;;
+  check-cc-retire-pidfd)
+    check_cc_retire_pidfd
+    ;;
+  check-cc-retire-request)
+    check_cc_retire_request
+    ;;
+  check-retirement-event)
+    check_retirement_event
+    ;;
+  check-entwurf-v2-retire)
+    check_entwurf_v2_retire
+    ;;
   check-win32-preview)
     check_win32_preview
     ;;
@@ -7506,6 +7600,9 @@ case "$cmd" in
   check-acp-foreground-only)
     check_acp_foreground_only
     ;;
+  check-fresh-call-provider)
+    check_fresh_call_provider
+    ;;
   check-acp-set-model-readback)
     check_acp_set_model_readback
     ;;
@@ -8412,6 +8509,21 @@ case "$cmd" in
     shift || true
     run_ts scripts/meta-facts.ts "$@"
     ;;
+  check-remote-pair-installed)
+    # #107 rail 3, CHECKOUT-ONLY install gate: installs a caller-supplied candidate tarball into a
+    # sandboxed consumer prefix and drives that install's bridge and entry through the T2 scene,
+    # auditing that the subject processes resolve nothing outside the prefix. Never repacks.
+    shift || true
+    run_ts scripts/check-remote-pair-installed.ts "$@"
+    ;;
+  remote-pair-receive)
+    # #107 rail 1: the receiving host's entry for one declared remote pair. The pair
+    # check runs before the v2 dispatch, so a claim outside the pair mutates nothing;
+    # a match reaches the same record/owner/deliverability checks every local send does.
+    # Installed, run_ts runs its compiled twin; the sending host's ssh reaches it through the bin.
+    shift || true
+    run_ts scripts/remote-pair-receive.ts "$@"
+    ;;
   peer-facts)
     # #116 M2-a READ-ONLY projection of the OBSERVED peer listing: one provider
     # (`listEntwurfFacts`) through one renderer (`renderEntwurfPeers().payload`), so
@@ -8481,6 +8593,9 @@ case "$cmd" in
   check-pi-queue-oracle)
     check_pi_queue_oracle
     ;;
+  check-remote-pair-installed-audit)
+    check_remote_pair_installed_audit
+    ;;
   check-demo-reproducibility)
     check_demo_reproducibility
     ;;

package/scripts/agy-bridge-config.py

@@ -102,7 +102,7 @@ PERMISSION_STATE_SCHEMA_VERSION = 2
 # EVERY call. The bridge was registered and two thirds of it was unusable — the same failure the
 # doctor already names for entwurf_v2, just never checked for the other two.
 #
-# The four tools deliberately NOT here, because a grant we do not need is a grant we should not take:
+# The five tools deliberately NOT here, because a grant we do not need is a grant we should not take:
 #   entwurf_inbox_read   — native-push has no inbox to drain. An agy citizen has no meta-mailbox
 #                          directory at all (measured), so granting it would pre-approve a rail this
 #                          backend does not have.
@@ -113,6 +113,9 @@ PERMISSION_STATE_SCHEMA_VERSION = 2
 #                          refuse without a pane anchor. An agy conversation is not a tmux client,
 #                          so these are not on its normal path either; the count moved from two to
 #                          four when 0.14 shipped the mux verbs, and the granted set did not.
+#   entwurf_retire_call  — one retirement attempt on a target a human operator explicitly named.
+#                          Pre-approving it would replace that request with an installer grant, so
+#                          it stays at agy's default Ask; the count moved from four to five (#147).
 ALLOW_RULES = tuple(f"mcp({SERVER_KEY}/{tool})" for tool in ("entwurf_v2", "entwurf_peers", "entwurf_self"))
 # Rules that MATCH one of our tools: its exact grant, the server-wide rule, and the action wildcard.
 # Membership here is a statement about agy's matcher, not about which list the rule sits in — the

package/scripts/build-bridge.sh

@@ -36,3 +36,17 @@ TSC="$REPO_DIR/node_modules/.bin/tsc"
 # dependent function called from its own location always resolves).
 cp "$REPO_DIR/pi/entwurf-capabilities.json" \
   "$REPO_DIR/mcp/entwurf-bridge/dist/pi-extensions/entwurf-capabilities.json"
+
+# The Claude Code retire helper must TRAVEL WITH the bundle too (#147 G3).
+#
+# `ccRetireHelperPath()` resolves ONE fixed basename beside its own module, so the emitted
+# dist/pi-extensions/lib/cc-retire-request.js finds the helper only if it sits next to it. The
+# canonical bytes are pi-extensions/lib/cc-retire-pidfd.py; this is a byte copy, never an edit.
+# A missing or non-regular source fails the build — there is no fallback location. Gated by
+# check-capability-bundle-reach (the compiled adapter asks from where it lives, bytes compared).
+CC_RETIRE_HELPER="$REPO_DIR/pi-extensions/lib/cc-retire-pidfd.py"
+if [ ! -f "$CC_RETIRE_HELPER" ] || [ -L "$CC_RETIRE_HELPER" ]; then
+  echo "build-bridge: $CC_RETIRE_HELPER is missing or not a regular file" >&2
+  exit 1
+fi
+cp "$CC_RETIRE_HELPER" "$REPO_DIR/mcp/entwurf-bridge/dist/pi-extensions/lib/cc-retire-pidfd.py"