@junghanacs/entwurf 0.39.0 → 0.41.0

package/docs/setup-clean-host.md

@@ -19,8 +19,7 @@ evidence split, and its three states must not collapse into "macOS is supported"
   unmeasured Darwin doctor reason is per-process environment DISCOVERY
   (start-key is portable).
 - **UNSUPPORTED** — native Windows `setup` and its harness rails. macOS is never this.
-  An experimental native-Windows Pi preview (0.39.0 candidate, not yet released; release
-  and npm publication pending) exists outside `setup`; see [BASELINE](../BASELINE.md#release-host-baseline).
+  An experimental native-Windows Pi preview (core 0.39.0) exists outside `setup`; see [BASELINE](../BASELINE.md#release-host-baseline).
 
 ## Requirements
 
@@ -32,14 +31,14 @@ evidence split, and its three states must not collapse into "macOS is supported"
 | entwurf | global/project-local `@junghanacs/entwurf`, or a source checkout | operator command and garden capability |
 | pi | optional-by-presence, `>=1.3.0 <1.4` — absent is an explicit setup SKIP, below-floor is a named FAIL | ACP provider, control sockets |
 | Native durable (`pi-durable`) | supplied by the Entwurf package (#130): Entwurf's owned app carrier plus the exact 1.3.0 pi SDK set as production dependencies — setup PASS when they verify, a named FAIL otherwise (never SKIP) | the `entwurf pi-durable` contact; native birth/LIVE on this supply surface is a separate release proof (§2b) |
-| Claude Code | optional, **`>=2.1.217`** — the exec-form hook floor | Claude ACP auth/runtime and mailbox-backed native citizen |
+| Claude Code | optional, **`>=2.1.306`** — the exec-form hook floor | Claude ACP auth/runtime and mailbox-backed native citizen |
 | GitHub Copilot CLI | optional-by-presence, operator-installed and authenticated — absent is an explicit setup SKIP; detected composes all four units (birth/MCP/receiver/footer) | self-fetch citizen and visible fresh |
 | OMP (`omp`) | optional-by-presence, operator-installed — absent is an explicit setup SKIP; detected composes all four units (birth/MCP/`tools.xdev` setting/receiver) | self-fetch citizen and visible fresh (accepted on one host — see §4b) |
 | Antigravity `agy` | optional, operator-installed and authenticated | native-push citizen |
 | OpenAI Codex CLI | optional-by-presence, operator-installed and authenticated; detected composes all four operator-owned units (birth/MCP/status-line/terminal-title) and stays non-green until the operator trusts the birth declaration once in a visible Codex; visible fresh also requires the operator-owned app-server, started with `entwurf codex-app-server` in a tmux session of the operator's choosing (#95 D1 retired the fixed `codex` home) | native-push and visible fresh, supported in 0.21.0 |
 | Cortex Code | optional, operator-installed and authenticated | Cortex ACP backend |
 
-Claude Code >=2.1.217 is required for the managed exec-hook lifecycle. The package
+Claude Code >=2.1.306 is required for the managed exec-hook lifecycle and same-id resume. The package
 never supplies or proxies backend credentials.
 
 On a physical Darwin host, `python3` may be the CommandLineTools stub (a
@@ -105,7 +104,7 @@ project-local install, or `./run.sh <command>` from a source checkout. Keep that
 same scope when upgrading and checking; native process restarts are separate (§7).
 
 `check-bridge` is auth-free. It proves the installed prebuilt MCP server boots and
-lists the eight garden tools; it does not prove a backend model turn or native hook.
+lists the nine garden tools (0.41.0); it does not prove a backend model turn, native hook or retirement permission.
 
 Neither npm form installs a harness runtime. `pi`, Claude Code, Copilot CLI, Codex CLI, agy,
 Cortex, and their authentication remain operator-owned optional prerequisites for the
@@ -241,10 +240,18 @@ A plain `pi` can load the package without becoming a citizen.
 In that session ask for `entwurf_self`, then `entwurf_peers`. Pick an existing
 live garden id and ask for `entwurf_v2` with `intent: "fire-and-forget"` and your
 message. These are harness tools, not shell subcommands; pi exposes them through
-Pi's built-in MCP as `mcp__entwurf_bridge__<verb>`. The bridge has eight tools;
-pi hides `entwurf_inbox_read` and `entwurf_register_native`, leaving six active.
+Pi's built-in MCP as `mcp__entwurf_bridge__<verb>`. The 0.41.0 bridge has nine tools;
+pi hides `entwurf_inbox_read` and `entwurf_register_native`, leaving seven active.
+The added `entwurf_retire_call` is only for one target/action explicitly requested by the
+human operator, never autonomous cleanup. Where a host provides or is configured with an approval
+step, that step applies as well; Pi and pi-durable 1.3.0 have no built-in approval prompt by
+default. The configured Claude ACP child is also [set to run without per-call permission prompts](./acp-backend-rail.md#configured-claude-acp-permissions); ACP retirement remains unmeasured.
+Tool availability, annotations and caller identity are not a grant.
+These candidate counts do not claim that an older installed package or running host has rolled
+forward; see [applying new source to a running host](#applying-new-source-to-a-running-host).
 Tool-call ingress is MCP; delivery to a pi citizen is still its record-addressed
-Unix control socket. A boot/listing from `check-bridge` is not a model-turn or
+control address (a Unix socket; a named pipe on the experimental native-Windows Pi
+preview). A boot/listing from `check-bridge` is not a model-turn or
 native-rail acceptance.
 
 To inspect the ACP provider from a project-local package instead of a global one:
@@ -449,6 +456,34 @@ The owned source is formatted at upstream width (`biome.json` override, indentWi
 per-file exception. A formatting change to an owned file changes its emitted bytes. So it is
 re-emitted with `--write`, and its generated digest is reviewed like any other carrier change.
 
+## 2c. Optional remote pair between two hosts (#107)
+
+This lets one declared pair of existing citizens on two hosts reach each other over SSH that you already run. [DELIVERY](../DELIVERY.md#remote-pair-107-one-declared-pair-across-two-hosts) owns the contract. The machine boundary is set by a person, and nothing here is automatic.
+
+1. **Connect the hosts yourself.** Use a private network (Tailscale or similar is recommended) and SSH keys and authorization you already trust. From each host, `ssh -o BatchMode=yes <alias> true` must succeed non-interactively, and the other host's non-interactive `command -v entwurf` must resolve to the installation you intend. Entwurf edits no SSH config, key, known-hosts file or network setting. Whatever SSH itself writes under your own policy, such as host-key updates, stays yours.
+2. **Run the accepted bytes on both hosts, in the processes that matter.** See [applying new source to a running host](#applying-new-source-to-a-running-host). A pulled checkout or a green setup line does not, by itself, show what a running bridge loaded.
+3. **Write one file on each host,** at `remotePairOptInPath()`. That is the pi agent dir unless `ENTWURF_META_SESSIONS_DIR` moves the meta-record store. Check that the sending bridge's environment and the SSH receive environment resolve the same path. Use mode `0600` and never overwrite a file you did not inspect:
+
+   ```json
+   {
+     "remoteGardenId": "<the other host's garden id>",
+     "ssh": "<your existing alias for the other host>",
+     "localGardenId": "<this host's garden id that talks to it>",
+     "remotePairFile": "<absolute path of the other host's own file>"
+   }
+   ```
+
+   The two files mirror each other: one host's `remoteGardenId` is the other's `localGardenId`. The other host's `remotePairFile` must spell this path as it is normalized, not through a symlinked alias.
+
+   To check a file, read it with the repository's internal parser from a source checkout. Use the same agent/store-root settings the bridge runs with. This is a read-only dev-clone check: there is no installed operator validation verb, and it performs no send and no model input.
+
+   ```bash
+   node --experimental-strip-types -e 'import("./pi-extensions/lib/remote-pair-send.ts").then(m=>console.log(m.readRemotePairOptIn(m.remotePairOptInPath())))'
+   ```
+
+   Do not validate the configuration by sending a test message.
+4. **Use it only between siblings you have open.** The measured self-fetch pair must be active and armed, and the target rail's own admission still applies. Delivery never starts, resumes or wakes an OFF citizen. To an active, armed one it rings the normal doorbell, which may start a turn at once in the receiving TUI. Remove the file to switch the pair off; there is nothing to stop or reconnect.
+
 ## 3. Optional Claude Code native citizen
 
 This rail is CERTIFIED on Linux; on macOS it is NOT CERTIFIED — pending physical
@@ -469,7 +504,7 @@ entwurf install-meta-bridge
 entwurf doctor-meta-bridge
 ```
 
-The supported floor `>=2.1.217` is enforced by package metadata through installer
+The supported floor `>=2.1.306` is enforced by package metadata through installer
 and doctor gates. Older Claude versions validate an exec-form hook but silently drop
 its `args` at runtime, so there is no shell-form fallback.
 
@@ -1128,6 +1163,26 @@ run `pnpm install` when the lockfile changed and `pnpm run build-bridge` before
 artifact-consuming checks such as `./run.sh check-bridge-delivery`; ignored dist
 may be missing or stale. Installed mode never bootstraps pnpm in `node_modules`.
 
+### Applying new source to a running host
+
+New source on disk is not a fresh runtime. From a checkout, each surface loads different bytes, and each refreshes differently:
+
+| Surface | Loads | Refreshed by |
+|---|---|---|
+| pi-durable host (contact and bridge) | compiled `mcp/entwurf-bridge/dist/…`, even from a checkout (the bootstrap's `PACKAGED_BRIDGE_ENTRY`) | a build, then a new host process |
+| ordinary Pi's built-in MCP bridge | the same compiled `dist` entry (`entwurfBridgeCompiledEntry`); the Pi extension itself loads from the package source | a build, then a new Pi process |
+| an MCP host registered through `start.sh` (Claude Code, Codex, Copilot, OMP, agy) | the TypeScript source in a checkout (compiled only under `node_modules`) | a new bridge child; no build |
+| installed hook/extension copies (Claude Code meta-bridge, Codex birth, Copilot birth and receive, OMP birth and receive) | their own installed copy, neither `dist` nor the checkout source | that unit's owning installer, then a new vendor session |
+
+An already-running process keeps the modules it loaded, whatever is on disk. So, for a host that has to run new bridge code:
+
+1. Build once from the checkout (`pnpm run build-bridge`, or its body `bash scripts/with-dist-lock.sh bash scripts/build-bridge.sh` when no package lifecycle should run).
+2. Compare the whole compiled output with the accepted candidate's, as a file-set and hash manifest. A hash of the selected entry alone is not enough: the entry can stay identical while a helper it loads differs. Check the pinned SDK set separately, and that the new process started after the build.
+3. Close the visible session and reopen it with its own native same-id resume. Closing a working sibling is an operator decision for that session, not something an agent does because new bytes landed.
+4. Confirm `entwurf_self` names the same garden id, and that the receiver/owner join points at the new process, whose bridge child started after the build.
+
+A per-component setup PASS or a `git pull` does not show which bytes a running bridge loaded. On 2026-10-20 one host of the #107 pair still selected a pre-feature dist after a pull and a green setup. The cause was not traced. A hash check caught it before the first message, and a manual build and visible resume fixed it. Entwurf adds no auto-build, reload or watcher for this.
+
 ## 8. Release acceptance versus host acceptance
 
 - `entwurf check-bridge`: installed MCP bytes boot; no backend auth.

package/mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js

@@ -31,16 +31,18 @@
  *                       seat, #105; nothing is ever created), optionally at ONE literal requested
  *                       cwd (cross-repo fresh, #73); returns a LAUNCH receipt only, and the new
  *                       address arrives later as the sender envelope of the sibling's nonce callback.
- *   - entwurf_resume_call — reopen ONE DORMANT pi citizen under its OWN garden id in a visible
- *                       window; target-only, runs no turn, LAUNCH and OBSERVATION receipts stay
- *                       apart.
+ *   - entwurf_resume_call — reopen ONE DORMANT pi or Claude Code citizen under its OWN garden id
+ *                       in a visible window; target-only, submits no prompt, LAUNCH and OBSERVATION
+ *                       receipts stay apart, the caller is attributed but grants nothing.
+ *   - entwurf_retire_call — one operator-requested target, one retirement attempt; actor is not
+ *                       permission, and action / append-record / lock-release receipts stay separate.
  *   - entwurf_callback — ZERO-ARGUMENT fresh-sibling callback. Reads ENTWURF_CALLBACK_TARGET +
  *                       ENTWURF_CALLBACK_NONCE from this process env (launcher-injected), validates
  *                       grammar, and dispatches through the existing v2 runner. Refuses by name
  *                       when env is absent/malformed or this process is a Codex-provenance bridge.
  *                       No model-supplied target fallback.
  *
- * That list is the WHOLE public surface — eight verbs — and `check-entwurf-bridge-boot`
+ * That list is the WHOLE public surface — nine verbs — and `check-entwurf-bridge-boot`
  * (G1f) holds it as an exact set on the runtime tools/list, so a verb added or dropped
  * here without a decision is red rather than merely undocumented.
  *
@@ -77,6 +79,8 @@ import { ENTWURF_PEERS_RENDER_LIMIT, renderEntwurfPeers } from "../../../pi-exte
 import { computeSelfAddressability } from "../../../pi-extensions/lib/entwurf-self-address.js";
 import { nativePushSupported } from "../../../pi-extensions/lib/entwurf-v2-contract.js";
 import { resolveMailboxWakeModeCapability } from "../../../pi-extensions/lib/entwurf-v2-decider.js";
+import { retireCitizen } from "../../../pi-extensions/lib/entwurf-v2-retire.js";
+import { makeProductionRetireDeps } from "../../../pi-extensions/lib/entwurf-v2-retire-production.js";
 import { runAndRenderEntwurfV2FromSurface } from "../../../pi-extensions/lib/entwurf-v2-surface.js";
 import { makeVisibleResumeDeps, renderVisibleResume, visibleResume, } from "../../../pi-extensions/lib/entwurf-v2-visible-resume.js";
 import { dispatchFreshCall, renderDispatchedFreshCall } from "../../../pi-extensions/lib/fresh-call-dispatch.js";
@@ -84,6 +88,9 @@ import { probeNativeSenderAlive, reconcileSenderIdentityClaims, resolveCodexRequ
 import { applyOmpBridgeChildRootPolicy, defaultMetaMailboxDir, defaultMetaSessionsDir, makeStoreRecordReader, readActiveStoreEntries, readMetaIdentityByGardenId, readMetaInbox, readMetaReceiverMarker, readMetaSenderMarker, requireBackend, } from "../../../pi-extensions/lib/meta-session.js";
 import { RESUME_CALL_REJECT_HINT, resumeCall } from "../../../pi-extensions/lib/mux-resume-call.js";
 import { registerNativeConversation } from "../../../pi-extensions/lib/native-push/register.js";
+import { makeLocalTraceFact, readRemotePairOptIn, remotePairOptInPath, runEntwurfV2WithRemoteRoute, } from "../../../pi-extensions/lib/remote-pair-send.js";
+import { processTransport } from "../../../pi-extensions/lib/remote-pair-transport.js";
+import { CONTROL_SOCKET_DIR } from "../../../pi-extensions/lib/socket-discovery.js";
 import { probeSocketLiveness } from "../../../pi-extensions/lib/socket-probe.js";
 const HOME = os.homedir();
 // ============================================================================
@@ -431,11 +438,22 @@ server.tool("entwurf_v2", "CANONICAL DELIVERY SURFACE for garden ids: message, r
         // Resolved ONCE so the dispatch-moment timestamp is fixed and the control RPC sender
         // + the mailbox body sender share one envelope. No replyability gate (see above).
         const sender = await buildSendSenderEnvelope({ requestMeta: extra._meta });
-        const rendered = await runAndRenderEntwurfV2FromSurface({ target, intent, message, mode, wants_reply }, 
-        // No trust-preflight inputs are passed, and none exist to pass: the preflight on this
-        // path guarded the resume verdict and left with `owned-outcome`. `senderProvider` is
-        // the whole options surface now.
-        { senderProvider: () => sender });
+        // #107: the operator's remote-pair opt-in is read per send. Absent = off and the local
+        // surface below runs exactly as before; a declared target goes over that one route.
+        const rendered = await runEntwurfV2WithRemoteRoute({ target, intent, message, mode, wants_reply }, {
+            senderProvider: () => sender,
+            route: readRemotePairOptIn(remotePairOptInPath()),
+            // The decider's canonical socket dir AND this bridge's ENTWURF_DIR: a trace in either is local.
+            localTrace: makeLocalTraceFact({
+                sessionsDir: defaultMetaSessionsDir(),
+                controlSocketDirs: [CONTROL_SOCKET_DIR, ENTWURF_DIR],
+            }),
+            transport: processTransport,
+            // No trust-preflight inputs are passed, and none exist to pass: the preflight on this
+            // path guarded the resume verdict and left with `owned-outcome`. `senderProvider` is
+            // the whole options surface now.
+            runLocal: (params, opts) => runAndRenderEntwurfV2FromSurface(params, opts),
+        });
         return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
     }
     catch (err) {
@@ -672,7 +690,7 @@ server.tool("entwurf_fresh_call", "Open ONE fresh visible sibling beside you and
         // as an unused suppression while the escape goes back to being fixable.
         // biome-ignore lint/complexity/noUselessEscapeInRegex: emitted to a Rust regex validator, see above
         .regex(/^[A-Za-z0-9][A-Za-z0-9._/:\[\]-]*$/)
-        .describe("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."),
+        .describe("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: z
         .string()
         .min(1)
@@ -749,36 +767,94 @@ server.tool("entwurf_fresh_call", "Open ONE fresh visible sibling beside you and
 // resume` cannot open a window on its own and `mux-resume-call` cannot read a record — that is
 // the import fence in docs/mux-launch-rail.md §11, expressed as a function argument.
 const visibleResumeLaunch = (input) => {
-    const launched = resumeCall({ cwd: input.cwd, runtimeArgs: input.runtimeArgs });
+    const launched = resumeCall({ backend: input.backend, cwd: input.cwd, runtimeArgs: input.runtimeArgs });
     return launched.ok
         ? { ok: true, handle: launched.receipt }
         : { ok: false, reason: launched.reason, hint: RESUME_CALL_REJECT_HINT[launched.reason] };
 };
-server.tool("entwurf_resume_call", "Reopen ONE DORMANT pi citizen under its OWN garden id, in a visible window in the operator's own tmux " +
-    "session. The record supplies everything — which transcript, which model, which provider, which cwd — so " +
-    "the only input is the target id: there is no model override, no task, and no prompt. This runs NO turn: " +
-    "the window comes back with the conversation and waits, and talking to it is still entwurf_v2 " +
-    "fire-and-forget on the socket this call stands up. You get TWO receipts and they mean different things: a " +
-    "LAUNCH receipt (tmux made a window and was asked to start pi) and an OBSERVATION receipt (the control " +
-    "socket answered under the same id, or resume-unobserved). Unobserved is a real outcome, not an error to " +
-    "retry — the window is visible, so read it. A citizen that is already LIVE is refused: address it with " +
-    "entwurf_v2 instead. Only pi citizens have a same-id resume, because only they stand a control socket up. " +
-    "Requires that this agent itself runs inside tmux.", {
+server.tool("entwurf_resume_call", "Reopen ONE DORMANT pi or Claude Code citizen under its OWN garden id, in a visible window in the operator's " +
+    "own tmux session. The record supplies everything — which session, which cwd, and for pi which transcript, " +
+    "model and provider — so the only input is the target id: there is no model override, no task, and no " +
+    "prompt, and a Claude Code session comes back as `claude --resume <its session id>` with none of the model " +
+    "or permission flags it was once started with. This verb submits NO prompt; what the runtime itself does " +
+    "after it comes back (for Claude Code, its hook re-arms the doorbell and unread mail may then wake a turn) " +
+    "is not measured, and talking to it is still entwurf_v2 fire-and-forget. You get TWO receipts and they mean " +
+    "different things: a LAUNCH receipt (tmux made a window and was asked to start the runtime) and an " +
+    "OBSERVATION receipt (pi: the control socket answered under the same id; Claude Code: a NEW live process in " +
+    "the window this call opened re-armed its receiver marker for the same session with a fresh arm binding the " +
+    "record also carries; or resume-unobserved; or record-unreadable with its cause). Unobserved is a real " +
+    "outcome, not an error to retry — the window is visible, so read it. A citizen that is already LIVE is " +
+    "refused: address it with entwurf_v2 instead. A Claude Code citizen is reopened only when the last validated " +
+    "owner the Entwurf hook armed for its session is proven gone AND that arm is still the record's last one; " +
+    "no marker, an unreadable or mismatched one, an inconclusive owner or an unbound one is refused, and a " +
+    "process holding the session without a committed hook attach is invisible to that proof. Other backends " +
+    "have no same-id resume. Requires that this agent itself runs inside tmux (inside herdr it is refused).", {
     target: z
         .string()
         .min(1)
         .regex(/^\d{8}T\d{6}-[0-9a-f]{6}$/)
-        .describe("Garden id of the DORMANT pi citizen to reopen (discover with entwurf_peers)."),
-}, async ({ target }) => {
+        .describe("Garden id of the DORMANT pi or Claude Code citizen to reopen (discover with entwurf_peers)."),
+}, async ({ target }, extra) => {
+    // Who asked, from the same authoritative caller identity fresh_call reads. Attribution only:
+    // an anonymous caller is reported as unattributed, never refused, and a record-backed one is
+    // granted nothing the target's record and live facts do not already decide.
+    let actor = null;
+    try {
+        actor = (await buildAuthoritativeSelfEnvelope({ requestMeta: extra._meta })).envelope.sessionId;
+    }
+    catch (err) {
+        if (!(err instanceof EntwurfEnvelopeWiringError)) {
+            return textErr(`entwurf_resume_call error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     try {
         const result = await visibleResume(target, makeVisibleResumeDeps(visibleResumeLaunch));
-        const rendered = renderVisibleResume(result);
+        const rendered = renderVisibleResume(result, { actor });
         return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
     }
     catch (err) {
         return textErr(`entwurf_resume_call error: ${err instanceof Error ? err.message : String(err)}`);
     }
 });
+server.tool("entwurf_retire_call", "Only when the human operator explicitly requested this particular target/work: make ONE retirement attempt for that request. " +
+    "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. " +
+    "Never use for autonomous cleanup or timers. Never automatically retry an unknown, cancelled or lost result. " +
+    "Target must be an existing Pi or Claude Code garden id; self retirement refuses. Pi shutdown-requested is " +
+    "only an ACK, not process exit, flush or model silence. Claude Code exited means that fd-pinned process only, " +
+    "not conversation end, children or flush. Do not manually /resume or /clear the target during the request. " +
+    "The JSON receipt preserves outcome, record and release separately; returning a receipt does not mean the " +
+    "target exited. Cancellation can suppress the wire response without undoing an action. For plural explicit " +
+    "requests, invoke once for each named target; never infer a roster or expand the request.", {
+    target: z
+        .string()
+        .min(1)
+        .regex(/^\d{8}T\d{6}-[0-9a-f]{6}$/)
+        .describe("Exact garden id of the Pi or Claude Code target the human operator explicitly requested to retire."),
+}, { readOnlyHint: false, destructiveHint: true, idempotentHint: false }, async ({ target }, extra) => {
+    try {
+        const receipt = await retireCitizen(target, makeProductionRetireDeps({
+            resolveCaller: async () => (await resolveAuthoritativeSender({ requestMeta: extra._meta }))?.envelope ?? null,
+            signal: extra.signal,
+        }));
+        // isError reports uncertainty/faults, NOT a common Pi-ACK/CC-exit success boundary.
+        // Named refusals are completed decisions. Always preserve the full three-axis JSON.
+        const outcome = receipt.outcome;
+        const uncertain = outcome.kind === "unknown" ||
+            outcome.kind === "preflight-error" ||
+            (outcome.kind === "pi" && outcome.result.boundary === "unknown") ||
+            (outcome.kind === "claude-code" && outcome.result.outcome === "unknown");
+        const recordFault = receipt.record.status === "requested-append-error" || receipt.record.status === "outcome-append-error";
+        const releaseFault = receipt.release.status !== "released" && receipt.release.status !== "not-acquired";
+        const json = JSON.stringify(receipt);
+        return uncertain || recordFault || releaseFault ? textErr(json) : textOk(json);
+    }
+    catch (err) {
+        return textErr(`entwurf_retire_call error: ${err instanceof Error ? err.message : String(err)}. ` +
+            "The outcome may be unknown; this does not prove no action. Do not automatically retry.");
+    }
+});
 server.tool("entwurf_callback", "ZERO-ARGUMENT callback for a fresh sibling this process was launched as. Reads " +
     "ENTWURF_CALLBACK_TARGET and ENTWURF_CALLBACK_NONCE from this process environment " +
     "(injected by the launcher next to the identity scrub), validates garden-id and nonce " +

package/mcp/entwurf-bridge/dist/pi-extensions/lib/cc-retire-pidfd.py

@@ -0,0 +1,236 @@
+"""cc-retire-pidfd — terminate ONE expected Linux process through a pidfd, or say why not (#147 G3).
+
+A numeric PID names whichever process holds that number NOW. Checking a PID and then signalling
+it leaves a window in which the process can exit and the number be reused, so the signal lands on
+a stranger. A pidfd names the process it was opened on, for as long as the fd is open: a signal
+sent through it can never reach a later holder of the number. This helper closes exactly that
+check -> signal race, and nothing else.
+
+    python3 -I -S cc-retire-pidfd.py <expected-pid> <expected-start-key>
+
+Order, and why each step is where it is:
+
+  1. Validate the inputs: a decimal pid > 1 and a `linux:<starttime>` start key (the scheme
+     `processStartKey` in meta-session.ts mints from /proc/<pid>/stat field 22).
+  2. pidfd_open(pid). From here the fd pins the process the number named at this instant.
+  3. Re-read /proc/<pid>/stat and compare the start key. /proc is a NUMERIC path, so this read
+     could already describe a reused number...
+  4. ...which is why the fd is then asked whether ITS process has exited. Not exited + key match
+     ties the fd and the stat to the same live process.
+  5. Print `{"phase": "ready"}` and wait, bounded, for ONE complete control frame on stdin — at
+     most CONTROL_MAX bytes of ASCII ending in a newline. Only the exact frame `go\n` proceeds;
+     `cancel\n`, EOF (with or without partial bytes), an oversized or non-ASCII frame, any other
+     line, a read failure, or the deadline (which partial input never extends) sends nothing. The caller re-checks its own
+     record/marker binding while the fd is held; this helper reads no record, marker, role or
+     permission and makes no decision of its own about WHETHER to terminate.
+  6. On `go`: ask the fd again (exited -> no signal), then pidfd_send_signal(fd, SIGTERM, None, 0)
+     ONCE, then poll the same fd for its exit within a fixed bound.
+
+What it does NOT do, ever: signal a numeric pid, a process group, any signal but SIGTERM, a second
+signal, an escalation, a retry, or a fallback to os.kill / kill(1) / Node's process.kill. A process
+that ignores SIGTERM is left running and reported as `exit-unobserved`.
+
+What the result does NOT mean:
+  - `signal-requested` means the kernel accepted the signal for that process, nothing more.
+  - `exited` means THAT process exited (its pidfd became readable). It is not its exit code, not
+    proof it flushed anything, and not proof its children are gone.
+  - A pidfd pins a PROCESS, not a conversation: a process that switched its native session after
+    the caller's last check is still the process this terminates.
+  - The start key is the same tick-resolution, same-boot value meta-session.ts compares; it is not
+    a cryptographic identity. The helper, the caller and the target must share one host, one PID
+    namespace and one procfs.
+
+Output: JSON lines on stdout. Every normal protocol end prints `{"outcome": ..., ...}` as its last
+line; a crash or a broken pipe can end without one, and a caller must read a missing outcome as
+unknown — after `signal-requested` it means the signal may have been sent. Exit codes:
+  0  exited          — SIGTERM was requested through the fd and that process's exit was observed
+  2  refused         — nothing was opened or nothing was signalled: bad input, capability absent,
+                       pid not found, permission, /proc unreadable, start-key mismatch, open error
+  3  not-signalled   — the fd was held and NO signal was sent: cancelled, EOF, truncated / oversized
+                       / bad control, control read failure, go deadline, or the process had already
+                       exited
+  4  unknown-after-signal — SIGTERM was requested but the exit was not observed in the bound, or
+                       observing it failed; nothing is retried
+"""
+
+import errno
+import json
+import os
+import re
+import select
+import signal
+import sys
+import time
+
+# Fixed on purpose — no flag or environment knob, so an outcome means the same thing everywhere.
+GO_DEADLINE_S = 10.0
+EXIT_WAIT_S = 5.0
+
+# Linux PID_MAX_LIMIT (2^22): no pid_t a Linux kernel hands out is larger, so anything above it is
+# malformed input, refused before any syscall.
+PID_MAX = 4194304
+# PID_MAX has 7 digits; fullmatch on this bound runs BEFORE int(), so no input reaches int()'s
+# string-length limit and every over-long decimal is the named malformed-pid refusal.
+PID_RE = re.compile(r"[0-9]{1,7}")
+KEY_RE = re.compile(r"linux:[0-9]{1,20}")
+CONTROL_MAX = 16
+
+
+def emit(obj):
+    sys.stdout.write(json.dumps(obj, sort_keys=True) + "\n")
+    sys.stdout.flush()
+
+
+def finish(code, outcome, **facts):
+    emit(dict(outcome=outcome, **facts))
+    sys.exit(code)
+
+
+def start_key(pid):
+    """`linux:<starttime>` from /proc/<pid>/stat, split after the LAST ')' (comm may hold parens)."""
+    with open("/proc/%d/stat" % pid, "r", encoding="ascii", errors="strict") as fh:
+        stat = fh.read()
+    fields = stat[stat.rindex(")") + 1:].split()
+    starttime = fields[19]
+    if not starttime.isdigit():
+        raise ValueError("starttime field is not numeric")
+    return "linux:" + starttime
+
+
+def exited(fd):
+    """True when the pidfd's process has exited (readable); raises when the fd cannot be observed."""
+    poller = select.poll()
+    poller.register(fd, select.POLLIN)
+    events = poller.poll(0)
+    for _, mask in events:
+        if mask & (select.POLLNVAL | select.POLLERR):
+            raise OSError(errno.EBADF, "pidfd not observable")
+        if mask & select.POLLIN:
+            return True
+    return False
+
+
+def read_control(deadline):
+    """ONE complete control frame from stdin before `deadline` (monotonic; partial input does not
+    extend it). Returns (kind, line): ("line", text) for a complete ASCII frame, or one of
+    ("eof",), ("truncated",), ("oversize",), ("bad-encoding",), ("deadline",), ("read-failed",)."""
+    buf = b""
+    stdin = sys.stdin.fileno()
+    while True:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            return ("deadline", None)
+        try:
+            ready, _, _ = select.select([stdin], [], [], remaining)
+            if not ready:
+                continue
+            chunk = os.read(stdin, CONTROL_MAX + 1)
+        except OSError:
+            return ("read-failed", None)
+        if not chunk:
+            return ("eof", None) if not buf else ("truncated", None)
+        buf += chunk
+        if b"\n" in buf:
+            frame = buf.split(b"\n", 1)[0]
+            if len(frame) > CONTROL_MAX:
+                return ("oversize", None)
+            try:
+                return ("line", frame.decode("ascii"))
+            except UnicodeDecodeError:
+                return ("bad-encoding", None)
+        if len(buf) > CONTROL_MAX:
+            return ("oversize", None)
+
+
+def main(argv):
+    if len(argv) != 3:
+        finish(2, "refused", reason="usage")
+    raw_pid, key = argv[1], argv[2]
+    if not PID_RE.fullmatch(raw_pid) or not 1 < int(raw_pid) <= PID_MAX:
+        finish(2, "refused", reason="malformed-pid")
+    if not KEY_RE.fullmatch(key):
+        finish(2, "refused", reason="malformed-start-key")
+    pid = int(raw_pid)
+    if not sys.platform.startswith("linux") or not hasattr(os, "pidfd_open") or not hasattr(signal, "pidfd_send_signal"):
+        finish(2, "refused", reason="capability-unsupported")
+
+    try:
+        fd = os.pidfd_open(pid, 0)
+    except OSError as err:
+        if err.errno == errno.ESRCH:
+            finish(2, "refused", reason="pid-not-found")
+        if err.errno == errno.EPERM:
+            finish(2, "refused", reason="permission-denied")
+        if err.errno in (errno.ENOSYS, errno.EINVAL):
+            finish(2, "refused", reason="capability-unsupported", errno=errno.errorcode.get(err.errno, err.errno))
+        finish(2, "refused", reason="open-failed", errno=errno.errorcode.get(err.errno, err.errno))
+
+    try:
+        try:
+            observed = start_key(pid)
+        except (OSError, ValueError, IndexError, UnicodeError):
+            finish(2, "refused", reason="proc-unreadable")
+        if observed != key:
+            finish(2, "refused", reason="start-key-mismatch")
+        try:
+            if exited(fd):
+                finish(3, "already-exited")
+        except OSError:
+            finish(2, "refused", reason="observe-failed")
+
+        emit({"phase": "ready", "pid": pid})
+        kind, line = read_control(time.monotonic() + GO_DEADLINE_S)
+        if kind == "deadline":
+            finish(3, "go-deadline")
+        if kind == "eof":
+            finish(3, "cancelled-eof")
+        if kind == "truncated":
+            finish(3, "truncated-control")
+        if kind == "oversize":
+            finish(3, "oversize-control")
+        if kind == "read-failed":
+            finish(3, "control-read-failed")
+        if kind != "line":
+            finish(3, "bad-control")
+        if line == "cancel":
+            finish(3, "cancelled")
+        if line != "go":
+            finish(3, "bad-control")
+
+        try:
+            if exited(fd):
+                finish(3, "already-exited")
+        except OSError:
+            finish(3, "observe-failed-before-signal")
+        try:
+            signal.pidfd_send_signal(fd, signal.SIGTERM, None, 0)
+        except OSError as err:
+            if err.errno == errno.ESRCH:
+                finish(3, "already-exited")
+            if err.errno == errno.EPERM:
+                finish(2, "refused", reason="permission-denied")
+            finish(2, "refused", reason="signal-failed", errno=errno.errorcode.get(err.errno, err.errno))
+        emit({"phase": "signal-requested", "signal": "SIGTERM"})
+
+        poller = select.poll()
+        poller.register(fd, select.POLLIN)
+        deadline = time.monotonic() + EXIT_WAIT_S
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                finish(4, "exit-unobserved", waitedS=EXIT_WAIT_S)
+            try:
+                events = poller.poll(int(remaining * 1000) + 1)
+            except OSError:
+                finish(4, "observe-failed")
+            for _, mask in events:
+                if mask & (select.POLLNVAL | select.POLLERR):
+                    finish(4, "observe-failed")
+                if mask & select.POLLIN:
+                    finish(0, "exited")
+    finally:
+        os.close(fd)
+
+
+if __name__ == "__main__":
+    main(sys.argv)