@junghanacs/entwurf 0.40.0 → 0.41.1

package/docs/setup-clean-host.md

@@ -23,22 +23,26 @@ evidence split, and its three states must not collapse into "macOS is supported"
 
 ## Requirements
 
+This table is this source candidate's, which moves the Pi SDK set to 1.4.0 and is **not published
+to npm yet**. The newest published package, `@junghanacs/entwurf@0.41.0`, ships the Pi 1.3.0 SDK
+set and requires Pi 1.3.x; the setup guide inside that tarball is its contract.
+
 | Component | Requirement | Needed for |
 |---|---|---|
 | Node | **`>=24.0.0`** | package and bridge runtime |
 | npm/pnpm | npm is bundled with Node; pnpm is required for source setup | package or source installation |
 | Python 3 | required by `setup`/`install` (project-path normalization + settings writers); `--help`/`check-bridge` stay Python-free | pi/Claude/agy/Copilot/Codex wiring writers |
 | 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 |
+| pi | optional-by-presence, `>=1.4.0 <1.5` — 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.4.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.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
@@ -79,11 +83,15 @@ node --version
 npm --version
 ```
 
+The two npm forms below install the **published** package, `0.41.0` (Pi 1.3.x, the Pi 1.3.0 SDK
+set), not this candidate. This candidate (Pi 1.4) installs only from a source checkout of its
+commit, further down this section; it has no npm install command until it is released.
+
 Global install is simplest when native harnesses should find stable bins from every
 working directory:
 
 ```bash
-npm install -g @junghanacs/entwurf
+npm install -g @junghanacs/entwurf@0.41.0
 entwurf --help
 entwurf setup /path/to/your-project
 entwurf check-bridge
@@ -94,7 +102,7 @@ A project-local installation is also supported:
 ```bash
 mkdir -p ~/entwurf-smoke && cd ~/entwurf-smoke
 npm init -y
-npm install --save-dev @junghanacs/entwurf
+npm install --save-dev @junghanacs/entwurf@0.41.0
 npx entwurf setup .
 npx entwurf check-bridge
 ```
@@ -104,7 +112,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
@@ -119,9 +127,15 @@ with a nonzero setup result):
 ```bash
 git clone https://github.com/junghan0611/entwurf ~/repos/gh/entwurf
 cd ~/repos/gh/entwurf
+git checkout "$CANDIDATE_REF"   # set it first to the commit you mean to run; a bare clone gives the default branch
 ./run.sh setup /path/to/consumer-project
 ```
 
+Set `CANDIDATE_REF` explicitly to a published branch or tag that carries the commit you mean;
+a bare clone selects the default branch, not a promised candidate. A validation branch is not a
+release acceptance. A checkout that already holds the intended commit skips the clone and the
+`git checkout`.
+
 This owns `~/.local/bin/entwurf` as a symlink to that checkout's `run.sh` and fails if the
 link is foreign, outside PATH, or shadowed by another command. It detects and wires
 pi/Claude/agy/Copilot/OMP/Codex by presence and prints a computed per-component
@@ -207,18 +221,21 @@ physical-Darwin receipt. `entwurf install` may write `.pi/settings.json`
 on Darwin; that is wiring, not a rail receipt. If `pi` is on PATH,
 `setup` names the pi row FAIL with the §1 Darwin wording.
 
-Install the exact release floor, then wire the project:
+Install this candidate's exact Pi floor, then wire the project from the candidate's source
+checkout (§1; `entwurf` is the link `./run.sh setup` made to it). The published 0.41.0 instead
+takes the Pi 1.3.x its own setup guide names and the global package root,
+`$(npm root -g)/@junghanacs/entwurf`, in place of the checkout:
 
 ```bash
-npm install -g @earendil-works/pi-coding-agent@1.3.0
+npm install -g @earendil-works/pi-coding-agent@1.4.0
 pi --version
 
 cd ~/entwurf-smoke
 entwurf install .
-pi -e "$(npm root -g)/@junghanacs/entwurf" --list-models entwurf
+pi -e ~/repos/gh/entwurf --list-models entwurf
 ```
 
-The supported range is `>=1.3.0 <1.4`. It is a hard minimum: installing this
+The supported range is `>=1.4.0 <1.5`. It is a hard minimum: installing this
 release onto a 0.83.x pi host upgrades the runtime rather than keeping the older
 minor. A host using only the external MCP bridge can skip pi until it needs a
 control socket; no delivery rail launches a pi process.
@@ -240,8 +257,15 @@ 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
 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
@@ -315,7 +339,7 @@ by `entwurf pi` or by registering ordinary Pi's adapter.
 What the Entwurf package supplies:
 
 1. **The pi SDK set** — `@earendil-works/{pi-coding-agent, pi-ai, pi-tui, pi-agent-core,
-   pi-durable, chord, pi-mcp, pi-codemode, pi-telemetry}` at exactly `1.3.0`, plus
+   pi-durable, chord, pi-mcp, pi-codemode, pi-telemetry}` at exactly `1.4.0`, plus
    `proper-lockfile`, as Entwurf's own production dependencies (declared once in
    `pi/pi-durable/overlay/upstream-pin.json` `sdk`). Model data rides the published
    `pi-ai`; there is no catalog copy.
@@ -328,7 +352,7 @@ What the Entwurf package supplies:
    (`pi/pi-durable/carrier-resolver.mjs`), which maps them to the published package's
    own `dist/` as installed — never through a source checkout.
 
-The upstream [library guide](https://github.com/earendil-works/pi/blob/v1.3.0/packages/durable/README.md)
+The upstream [library guide](https://github.com/earendil-works/pi/blob/v1.4.0/packages/durable/README.md)
 and the [experimental app guide](https://github.com/earendil-works/pi/blob/v1.1.0/packages/coding-agent/src/experimental/durable/README.md)
 (last published at v1.1.0) describe what the carrier is. Running the bare upstream app does not attach Entwurf's
 garden contact. Entwurf does not rebuild the controller/model/auth/storage system or
@@ -413,7 +437,7 @@ tree (for example an override that binds pi-durable's `pi-ai` to an older publis
   manifest field; it is a known constraint of supplying both from one package, accepted for 0.32,
   not a claim that every load path is harmless.
 
-The ordinary Pi CLI on PATH is a separate subject (§2, range `>=1.3.0 <1.4`): a host Pi is
+The ordinary Pi CLI on PATH is a separate subject (§2, range `>=1.4.0 <1.5`): a host Pi is
 not needed to run pi-durable, and a host inside the range need not be the same copy as the
 carrier's. Native Pi owns credentials, model settings and durable SQLite sessions; keep them
 in place rather than copying credentials or migrating ordinary Pi transcripts. Native
@@ -424,6 +448,29 @@ to the app's own model resolution; the checkout contact/send/receive gates run t
 with scripted S plus native H; Pi ↔ pi-durable LIVE on this supply surface is a separate release
 proof ([#130](https://github.com/junghan0611/entwurf/issues/130)).
 
+### Moving durable sessions from the Pi 1.3 SDK to 1.4
+
+This candidate is unpublished, and moving a live host onto it is a separate operator decision. When
+you do:
+
+1. **Confirm the old owner is gone.** Close the 0.41 (SDK 1.3) durable session normally and check
+   that its process has exited. A stale session lock alone is not proof.
+2. **Back up first.** Before the first 1.4 open, copy the target session directory whole
+   (`session.sqlite` with any `-wal`/`-shm`) as one consistent set.
+3. **Choose the session by name.** Reopen with the `--resume` picker and pick the entry you mean;
+   do not use `--continue` on a host with more than one session.
+4. **Package downgrade is not data rollback.** The first 1.4 open migrates SQLite storage to
+   schema 2, which SDK 1.3 (Entwurf 0.41) refuses to open. Reinstalling the old package does not
+   undo that. Restoring the backup does, and work done after the 1.4 open is not in the backup.
+5. **Inspect parked work before retrying.** On its first open, 1.4 counts a task that SDK 1.3 left
+   running as one restart, and after repeated cut-offs it parks the task (`restart_limit`). Read
+   what the task already did before you resend anything: recovery of a parked model turn is not
+   measured, and its side effects or outcome may be unknown. The existing conversation abort is
+   cancellation, not retry; it need not affect background tasks.
+
+The measurements behind these points, and what they do not cover, are in the
+[#148 checkpoint](https://github.com/junghan0611/entwurf/issues/148#issuecomment-6339048361).
+
 ### Maintainer: re-emitting the carrier
 
 Only a maintainer changing the pi-durable app runs `scripts/emit-pi-durable-carrier.ts`. Its
@@ -497,7 +544,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.
 
@@ -640,7 +687,7 @@ as a note rather than a fault.
 
 **entwurf sets no OMP version floor in code, and will not grow one on schedule.** Detection is
 presence-only (`command -v "${OMP_BIN:-omp}"`); there is no `entwurf.ompFloor`, no coherence
-gate, and no exact pin — unlike Node (`engines.node`), pi (`>=1.3.0 <1.4`) and Claude Code
+gate, and no exact pin — unlike Node (`engines.node`), pi (`>=1.4.0 <1.5`) and Claude Code
 (`entwurf.claudeCodeFloor`), each of which has an enforcement point. That asymmetry is a
 decision, not an omission. A floor is the answer to a vendor that fails SILENTLY — Claude Code
 earned one because an older binary validates the exec manifest, drops `args` at runtime, and
@@ -1158,11 +1205,20 @@ 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. A pi-durable host spawns the compiled bridge `mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js` even from a checkout (the bootstrap's `PACKAGED_BRIDGE_ENTRY`). Ordinary `start.sh` in a checkout runs the TypeScript source instead. An already-running bridge keeps the modules it loaded. So, for a host that has to run new bridge code:
+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.
+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.

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";
@@ -686,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)
@@ -763,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)