@junghanacs/entwurf 0.13.0 → 0.14.0

package/docs/acp-backend-rail.md

@@ -0,0 +1,236 @@
+# ACP backend adapter rail
+
+The ACP plugin is one provider with backend adapters behind a common turn loop.
+It is not a second harness and does not create another citizen or socket layer. The
+host pi session already owns the record-backed citizen identity; each backend owns
+its own process, auth, transcript, and native tool surface.
+
+Claude is the reference adapter. Snowflake Cortex Code is the second shipped adapter.
+Implementation history and audit chronology live in CHANGELOG, issues, and git; this
+document keeps the current contract and its open evidence boundary.
+
+## Boundary
+
+| Layer | Owns |
+|---|---|
+| entwurf core | identity, facts, dispatch, rail choice, delivery evidence |
+| ACP common loop | spawn, initialize, new session, model enforcement, prompt, event mapping, teardown |
+| backend adapter | model routing, launch, overlay, carrier, backend settings, model enforcement details |
+| backend runtime | credentials, subscription, transcript, native tools, native configuration semantics |
+
+The common sequence is invariant:
+
+```text
+resolve adapter once
+→ load backend settings and carrier
+→ materialize backend overlay
+→ spawn → initialize → newSession → enforceModel
+→ prompt → event map → retain-or-teardown
+```
+
+No layer reconstructs a backend transcript, proxies credentials, scans ambient MCP
+configuration, or grants tools through prose. Explicit `entwurfProvider.mcpServers`
+and the callable schema are the tool truth.
+
+## Adapter contract
+
+Source of truth: `pi-extensions/lib/acp/backend-adapter.ts`.
+
+| Method | Responsibility |
+|---|---|
+| `routeModel` | Claim a curated id and return the backend-native id. Zero or multiple owners fail loud. |
+| `curatedModels` | Contribute rows to the single `entwurf` provider. Non-Claude backends use a reserved prefix. |
+| `resolveAdapterSettings` | Parse only this backend's settings into an opaque value. |
+| `resolveLaunch` | Return command/argv; honor only the backend's explicit override. |
+| `launchEnvDefaults` | Supply static launch environment defaults. |
+| `ensureOverlay` | Materialize session isolation and return spawn environment overrides. |
+| `loadCarrier` | Return a short operator carrier or `null` when the backend has no carrier. |
+| `buildSessionMeta` | Build optional `newSession._meta` from the already-loaded carrier. |
+| `enforceModel` | Make the requested native model authoritative before the prompt. |
+| `configSignatureFields` | Return a stable primitive map whose changes invalidate reuse. |
+
+`backend.ts` resolves the adapter once at turn entry. Common config never branches on
+backend-specific keys; `adapterSettings` remains opaque until handed back to its owner.
+A connection, model, carrier, MCP declaration, or overlay-relevant setting change must
+change the reuse signature rather than mutate a live incompatible session.
+
+A streaming message begins with `stopReason: "pending"`. ACP's terminal set is mapped
+explicitly: `end_turn → stop`, `max_tokens → length`, `cancelled → aborted`; refusal,
+exhausted turn budget, unknown, and absent reasons end as errors. The original ACP
+reason is preserved in `rawStopReason`. Returning to a default-success branch is a
+contract violation.
+
+### Prompt lifecycle — who may end a turn
+
+Bootstrap (`initialize`, `newSession`, set-model) carries 30s wall-clock bounds: those
+steps make no model progress, so a stuck one is a dead session. **The prompt carries
+none.** A turn ends only on a lifecycle event:
+
+| Ending | Behavior |
+|---|---|
+| the agent answers | mapped through the terminal set above |
+| the operator aborts | ACP `session/cancel` first — the agent closes its own turn (`cancelled → aborted`); process-group teardown only after a bounded grace, so an abort always returns |
+| the child dies / stdio ends | the turn fails naming the exit status and the session-scoped stderr tail, on both the new and the reuse path |
+
+Elapsed time is not evidence of failure, and a silent turn is not a failed turn: tool
+use, reasoning, and provider queueing all legitimately outrun any number we could pick.
+Suspected stalls are handled by exposing progress, never by a killing timer.
+
+A prompt-phase failure message is also part of the contract. pi classifies a failed
+assistant message by matching its text against `RETRYABLE_PROVIDER_ERROR_PATTERN`
+(`@earendil-works/pi-ai` `utils/retry`), and a "transient" verdict makes it replay the
+WHOLE prompt from a cold session up to `retry.maxRetries` times. Our own prompt-phase
+text must never read as transient — that pairing (absolute cutoff × blind retry) is what
+turned one long turn into four in 0.13.0. Gates: `check-acp-prompt-lifecycle` (behavior,
+with pi's own classifier as the oracle), `check-probe-ordering` (no production prompt
+cutoff in source).
+
+## Shipped adapters
+
+| Seam | Claude | Cortex Code |
+|---|---|---|
+| Model ids | unprefixed `claude-sonnet-5`, `claude-opus-5` | `cortex-auto`, `cortex-claude-opus-5`, `cortex-claude-sonnet-5`, `cortex-openai-gpt-5.4`; prefix stripped before set-model |
+| Launch | bundled `claude-agent-acp`; `CLAUDE_AGENT_ACP_COMMAND` override | `cortex acp serve`; optional connection; `CORTEX_ACP_COMMAND` override; never a launch-time `-m` |
+| Model authority | per-turn ACP set-model | per-turn ACP set-model; an unavailable curated id fails before prompt |
+| Carrier | engraving in `_meta.systemPrompt` | no system-prompt carrier; engraving rides the first-user augment |
+| Overlay | `CLAUDE_CONFIG_DIR` whitelist, configured-empty hooks, native memory hidden | session-scoped isolated HOME + `SNOWFLAKE_HOME`, private `cortex/mcp.json`, measured-minimum auth passthrough |
+| MCP | explicit wire `mcpServers` | explicit declarations projected to private `mcp.json` because Cortex ignores the wire field |
+| Backend setting | none | `cortexConnection`; env override wins and participates in the signature |
+
+### Claude
+
+The bundled adapter resolves before any PATH fallback. Its overlay retains only the
+auth/runtime state required by the Claude Agent SDK and hides operator memory, hooks,
+agents, history, and local settings. Rich project/operator context rides the first-user
+augment; the system carrier stays short to avoid changing billing semantics.
+
+The carrier owns its own leading boundary. A string `_meta.systemPrompt` replaces the
+`claude_code` preset, but the SDK still prefixes a fixed identity sentence and joins the
+two with nothing, so the loader opens every rendered carrier with one blank line. The
+template cannot supply it — the render is trimmed so operator whitespace never drifts the
+reuse signature. That same rendered string is what `bridgeConfigSignature` folds and what
+`buildSessionMeta` sends; normalizing it at either hop desynchronizes the wire from the
+signature.
+
+`clientCapabilities` intentionally remains empty. Terminal-output widgets and nested
+subagent transcripts are therefore not requested. Enabling either is a separate
+rendering contract, not a capability bit flip.
+
+### Cortex Code audit (D1–D10)
+
+The original audit labels remain useful coordinates for source comments and gates:
+
+| Audit | Landed contract |
+|---|---|
+| D1–D2 | Isolated HOME hides operator-global Claude/Cortex skills and settings; install-directory plugins remain a host fact. |
+| D3 | Refuse `CORTEX_HOME` whenever present, including empty. |
+| D4 | Author `autoUpdate: false`; launch only `cortex acp serve`. |
+| D5–D6 | Pass through measured-minimum local auth; entwurf never runs or supplies authentication. |
+| D7 | Four curated rows; enforce the stripped native id before prompt. |
+| D8 | Credential boundary is AGENTS Hard Rule 9 and the ACP Plugin Boundary. |
+| D9 | Project explicit MCP declarations into private `cortex/mcp.json`; wire `mcpServers` is ignored upstream. |
+| D10 | Restore real operator HOME only for `entwurf-bridge`, so the isolated child still sees the garden store. |
+
+Cortex containment was measured against the live CLI rather than copied from Claude:
+
+- **Dual HOME:** the child receives an isolated `HOME` and `SNOWFLAKE_HOME`. Global
+  `~/.claude`/`~/.cortex` skills, hooks, settings, and operator `cortex/mcp.json` are
+  outside the session; explicit cwd project scope remains visible.
+- **`CORTEX_HOME` presence refusal:** Cortex gives it precedence over
+  `SNOWFLAKE_HOME`; even an empty ambient value can make ownership ambiguous.
+- **Auth passthrough:** only `connections.toml`, optional `config.toml`, and
+  `cortex/cache/credential_cache` are symlinked through. This narrows reachable paths;
+  it is not a read-only mount and entwurf never supplies the credential.
+- **Launch integrity:** the overlay authors `autoUpdate: false`, preventing a CLI
+  replacement in the middle of a turn. The launch is exactly `cortex acp serve` plus
+  an optional connection; protocol initialization fails loud if a TUI was started.
+- **MCP projection:** Cortex's ACP server ignores wire `mcpServers`, so the adapter
+  exact-writes an overlay-private `cortex/mcp.json`. Non-stdio declarations fail before
+  spawn. Only the `entwurf-bridge` entry receives the real operator HOME required to
+  see the garden store.
+- **Carrier:** Cortex has no `_meta.systemPrompt` contract. The engraving is placed at
+  the head of the first-user augment; claiming a system-prompt engraving is false.
+
+Cortex's bundled install-directory plugins are outside any HOME overlay and remain a
+host fact. Also unclaimed: project-hook behavior on every host, the semantics of its
+caller-session `_meta`, and cross-machine certification.
+
+## 11-7. Readiness boundary
+
+A backend can return `newSession` before its declared MCP server is callable. This was
+observed intermittently on the Claude rail and directly on Cortex's private `mcp.json`
+path. Neither `claude-agent-acp` 0.66.0 nor the Cortex landing adds a client-side
+readiness fence, and `mcpServerStatus()` is not called by the common loop.
+(Re-measured at the 0.65.0 → 0.66.0 bump: the goal extension is not a fence,
+and `mcpServerStatus` appears nowhere in the 0.66.0 adapter source.)
+
+### 11-7-a/b. Instrument and first measurement
+
+The ordering probe is an **instrument**, not a fix. It separates:
+
+1. client request/response ordering;
+2. backend MCP receive/reply markers;
+3. the first prompt/tool decision;
+4. probe admissibility (the test itself did not create the race).
+
+Its first paired measurement was inconclusive. Do not convert that into “no race” or
+“the adapter fixed it.” A green intermittent run measures one sample; a red run proves
+the symptom remains.
+
+### 11-7-c. CLI snapshot producer
+
+The B-name-snapshot producer is admissible only when the run pins the real target
+executable and digest, refuses ambient overrides, preserves argv/stdin/stdout/stderr and
+exit/signal behavior, bounds NDJSON framing, scrubs only the exact probe env allowlist,
+and timestamps snapshot/prompt hand-offs inside the downstream write callback. One
+post-wire init snapshot may support the controlled-absence row; malformed, duplicate,
+pre-wire, unarmed, or target-mismatched snapshots invalidate the run rather than proving
+absence. `check-probe-cli-shim` is the detailed producer oracle: its 20 direct
+`[CHECK:*]` assertions remain, while their verification-infra replants were deliberately
+removed by #70. `probe-ordering.json` retains only the product-subject no-production-prompt-cutoff
+replant consumed by `check-probe-ordering`.
+
+Current probe contract and gates:
+
+- `check-probe-ordering` — interval/envelope and marker ordering;
+- `check-probe-cli-shim` — CLI shim admissibility and environment boundary;
+- `smoke-acp-ordering-probe-live` — opt-in paired observation.
+
+Until a causal fix lands, release gates continue to exercise real MCP availability and
+fail when the callable surface is absent. Do not add sleeps or infer readiness from
+`newSession` latency.
+
+## Verification
+
+Deterministic floor:
+
+```bash
+pnpm run check:full
+./run.sh check-acp-provider-surface
+./run.sh check-acp-sdk-surface
+./run.sh check-acp-session-reuse
+./run.sh check-acp-stop-reason
+./run.sh check-acp-cortex
+./run.sh check-gate-qualification
+```
+
+Live axes:
+
+```bash
+LIVE=1 ./run.sh release-gate /path/to/scratch --cut
+LIVE=1 ENTWURF_ACP_CORTEX_CONNECTION=<conn> \
+  ./run.sh smoke-acp-cortex-live
+```
+
+The aggregate release gate is Claude-backed so a host without Cortex/Snowflake auth
+can run the package floor. That means Cortex is **on demand**, not optional evidence:
+a cut that changes or ships the Cortex rail must run and read its dedicated smoke.
+Per-cut counts, digests, versions, and host observations belong in BASELINE/CHANGELOG,
+not this standing contract.
+
+## Open work
+
+- causal MCP-readiness diagnosis and, only with proof, a backend-invariant fence;
+- broader installed-host and cross-machine Cortex evidence;
+- any future Codex managed native-citizen lane—separate from ACP; 0.14.0 does not ship one;
+- persisted ACP resume/load, which is not implemented by today's in-memory reuse.

package/docs/external-mcp-host.md

@@ -0,0 +1,131 @@
+# Wiring `entwurf-bridge` into an external MCP host
+
+Per-harness registration for Claude Code, Codex CLI, and Antigravity, plus the
+PATH/env boundary and the external vs garden-native semantics. `README.md` keeps only
+the one-line registration; everything an operator needs to actually wire a host is here.
+
+`entwurf-bridge` can also be registered in a separate MCP-aware harness (Claude Code, Codex CLI, Antigravity/`agy`, …). That host does **not** become a pi session and does **not** need to be ACP-backed. There are now two honest cases:
+
+- **plain external MCP host**: no garden meta-record / sender marker. It can call the read surfaces (`entwurf_peers`, `entwurf_inbox_read`), but `entwurf_v2` sends are **refused by default** (#50 C4: "if we don't know who sent it, we don't send it"). The operator may wire the explicit hatch below; the send then goes out external/non-replyable.
+- **garden-native native session**: a trusted lifecycle hook minted a garden id and sender marker — `SessionStart` for Claude Code, `PreInvocation` for agy. It is not a pi control-socket session, but it can be replyable by garden id when its own mailbox/probe rail says so.
+
+**Which verb an external agent should reach for:** to deliver to / reply to a garden id, use **`entwurf_v2`** — it is the canonical delivery surface and the only one that reads whether the target is live pi, dormant pi, mailbox-backed Claude Code, or native-push Antigravity and routes correctly. Discover targets with `entwurf_peers`, confirm your own identity with `entwurf_self`, drain a mailbox with `entwurf_inbox_read`, and use `entwurf_register_native` only as the explicit/manual fallback for binding an already-running agy conversation (normal agy birth is automatic through the installed hook). Open a NEW sibling with **`entwurf_fresh_call`**, and reopen a DORMANT pi citizen under its own garden id with **`entwurf_resume_call {target}`**. Fresh call needs its selected runtime (`pi` or `claude`) on the server's PATH; resume call always needs `pi`. Both start a runtime, while delivery does not. (The old v1 verbs `entwurf` / `entwurf_resume` / `entwurf_send` are gone.)
+
+Observed: Claude Code, Codex CLI, and Antigravity CLI all reach the read surfaces through this MCP bridge from a plain external host — `entwurf_peers` is a pure fact projection, while `entwurf_inbox_read` is a **mutating drain** (it archives the messages and stamps the read-receipt), so "read" here does not mean side-effect-free; **sending** needs an identity lane. Claude becomes symmetric/replyable through its mailbox-backed meta-session; agy becomes symmetric/replyable through its record-backed sender marker plus live native-push probe. Codex has no managed citizen lifecycle yet, so a Codex host cannot send without the explicit anonymous hatch below.
+
+Prerequisites on the host running the external MCP client:
+
+- A live pi session launched with `--entwurf-control` populates `~/.pi/entwurf-control/<gardenId>.sock` — the key is the **record's** garden id, never a transcript/session id (`PI_SESSION_ID` only carries the id record birth already established). Required for `entwurf_v2` control-socket dispatch and `entwurf_peers`.
+
+> **PATH boundary.** MCP servers are often launched by GUI/editor daemons and may not inherit the interactive shell's PATH. No `entwurf_v2` rail launches a process, so this does not affect delivery — but `entwurf_fresh_call` and `entwurf_resume_call` do open a fixed runtime. If that runtime works in your terminal but an external-host call fails with `spawn pi ENOENT` or `spawn claude ENOENT`, pass a full PATH in the MCP server `env`, set `ENTWURF_BRIDGE_ENV_FILE` to a small shell file that exports PATH, or point the host at a wrapper that can find the runtime. `start.sh` sources only the explicit `ENTWURF_BRIDGE_ENV_FILE`; it never reads personal dotfiles automatically.
+
+Example env file:
+
+```bash
+# ~/.config/entwurf-bridge/env.sh
+export PATH="$HOME/.local/share/pnpm:$HOME/.local/bin:$HOME/.nvm/versions/node/v24.15.0/bin:$PATH"
+```
+
+Then add it to the external MCP config:
+
+```json
+{
+  "env": {
+    "ENTWURF_BRIDGE_ENV_FILE": "/home/operator/.config/entwurf-bridge/env.sh",
+    "ENTWURF_BRIDGE_EXTERNAL_AGENT_ID": "external-mcp/claude-code"
+  }
+}
+```
+
+**Anonymous sender hatch (explicit, documented — never a default).** The bridge refuses an `entwurf_v2` send when the process has neither pi-session env (`PI_SESSION_ID` + `PI_AGENT_ID`) nor a trusted meta-sender marker (#50 C4). A deliberately-anonymous external host — e.g. a Codex CLI wiring, which has no managed citizen lifecycle — may opt out by adding `"ENTWURF_BRIDGE_ALLOW_ANONYMOUS_SENDER": "1"` to the MCP server `env`. The cost is honest and fixed: the send lands with `origin: "external-mcp"`, `replyable: false` (there is no reply address), and `wants_reply: true` stays pointless. The retired opt-in `ENTWURF_BRIDGE_REQUIRE_META_SENDER` is no longer read — its demand became the default, so a stale copy in an old install env is inert.
+
+Emergency/manual workaround when the MCP server environment is wrong but an existing entwurf session must be resumed: run `pi --session /path/to/entwurf.jsonl ...` from an interactive shell whose PATH is known-good. Treat this as a debug escape hatch, not a replacement for fixing the MCP launch environment.
+
+External/meta-session semantics:
+
+- `entwurf_v2` from a plain external host is **refused by default** (no authoritative sender — #50 C4). With the explicit `ENTWURF_BRIDGE_ALLOW_ANONYMOUS_SENDER=1` hatch it delivers with `origin: "external-mcp"` / `replyable: false`; there is still no reply address.
+- `entwurf_v2` from a trusted meta-session delivers with `origin: "meta-session"`, and `replyable` is **derived from that sender's own rail — not granted by being trusted**: a self-fetch sender (Claude Code) is replyable only while its receiver is live and armed, and a native-push sender (Antigravity) only while its adapter probe finds the live conversation. Identity survives either way; only `replyable` drops to `false`. When it is `true`, `wants_reply: true` is allowed and the receiver can reply to the sender's garden id.
+- `entwurf_v2` never launches a process, so no delivery path needs `pi` on PATH. A dormant pi target is refused as `dormant-fire-forget-unsupported`: the hidden background resume that used to answer there was withdrawn under the visible-first rule, and re-opening the session is the separate `entwurf_resume_call` verb — which DOES need `pi` on PATH, because it starts one.
+- `entwurf_self` returns the same authoritative identity for pi sessions **and** trusted meta-sessions. A plain external host with no pi env and no trusted sender marker still fails because there is no reply address to report.
+
+#### Claude Code
+
+Plain MCP registration works independently of the native lifecycle. A garden-native
+mailbox citizen requires Claude Code >=2.1.217 plus the managed meta-bridge installer;
+older versions silently drop exec-hook arguments and are refused.
+
+Claude Code supports both CLI registration and a separated global MCP config. The separated file is recommended for dotfile / `agent-config` workflows because `~/.claude.json` also carries OAuth-bearing state.
+
+**Option A — CLI add:**
+
+```bash
+claude mcp add --scope user entwurf-bridge \
+  bash /absolute/path/to/entwurf/mcp/entwurf-bridge/start.sh
+```
+
+This writes the entry into `~/.claude.json`'s top-level `mcpServers`. Good for one-off setup; do not version-control the resulting `~/.claude.json`.
+
+**Option B — separated `~/.mcp.json`:**
+
+```json
+{
+  "mcpServers": {
+    "entwurf-bridge": {
+      "type": "stdio",
+      "command": "bash",
+      "args": [
+        "/absolute/path/to/entwurf/mcp/entwurf-bridge/start.sh"
+      ],
+      "env": {
+        "ENTWURF_BRIDGE_EXTERNAL_AGENT_ID": "external-mcp/claude-code"
+      }
+    }
+  }
+}
+```
+
+Claude Code reads `~/.mcp.json` in addition to `~/.claude.json`'s top-level `mcpServers`. The `env` block identifies the calling host on the receiver render — omit it and `entwurf_v2` shows `external-mcp/unknown-host`. If Claude Code permissions are locked down, allow `mcp__*` or `mcp__entwurf-bridge__*` in `~/.claude/settings.json`.
+
+#### Codex CLI
+
+Add the server to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.entwurf-bridge]
+command = "/absolute/path/to/entwurf/mcp/entwurf-bridge/start.sh"
+```
+
+Codex has no managed citizen lifecycle (no sender marker), so this wiring can read `entwurf_peers`/`entwurf_inbox_read` but `entwurf_v2` sends are refused by default (#50 C4). To send anonymously anyway, add the explicit hatch to the same block: `env = { ENTWURF_BRIDGE_ALLOW_ANONYMOUS_SENDER = "1" }` — the send is then marked external/non-replyable (see the hatch paragraph above).
+
+#### Antigravity CLI (`agy`)
+
+Use the managed install surface rather than editing agy's files by hand:
+
+```bash
+entwurf install-agy-bridge
+entwurf install-agy-statusline
+entwurf install-agy-hooks
+
+entwurf doctor-agy-bridge
+entwurf doctor-agy-statusline
+entwurf doctor-agy-hooks
+```
+
+The three adapters deliberately own different atoms:
+
+- bridge: one `entwurf-bridge` server in `~/.gemini/config/mcp_config.json`, plus one narrow permission string per tool the normal agy workflow calls — `mcp(entwurf-bridge/entwurf_v2)`, `mcp(entwurf-bridge/entwurf_peers)`, `mcp(entwurf-bridge/entwurf_self)` — in `~/.gemini/antigravity-cli/settings.json`. agy defaults every `mcp` action to Ask, so a tool that ships without its own rule stops for a y/n on every call; `entwurf_inbox_read` is deliberately not granted (native-push has no inbox), neither is the manual `entwurf_register_native` fallback, and neither are `entwurf_fresh_call` / `entwurf_resume_call` (both launch into the caller's own tmux session, which an agy conversation is not);
+- statusline: the complete `statusLine` subtree pointing at the bare stable bin `entwurf-agy-statusline`;
+- hooks: one named `PreInvocation` hook pointing at the bare stable bin `entwurf-agy-imprint`.
+
+Unrelated servers, permissions, settings, and hooks are preserved; every adapter has a state-backed honest inverse and refuses symlink-owned SSOTs. The installer never grants broad `command(*)`, `unsandboxed(*)`, or other YOLO policy — those remain operator decisions.
+
+The **global** MCP config live agy reads is `~/.gemini/config/mcp_config.json`. `~/.gemini/antigravity-cli/mcp_config.json` is not the global MCP root; the bridge installer one-way cleans only a stale entwurf-owned entry there. After the first model invocation, the imprint hook binds the native `conversationId` to a garden id, the statusline shows `🪛 <garden-id> agy`, and sends from that MCP child carry `agentId=meta-session/antigravity` with `replyable:true` only when the record exists and the live native-push probe succeeds.
+
+#### External-host skills and commands
+
+MCP registration gives the external harness the tools; the host still needs workflow guidance. Put the Mitsein-over-MCP (cross-harness collaboration) rules in that host's instruction file or, when supported, as a host-native skill. Do not assume pi slash commands are portable across external hosts — if a workflow must work across Claude Code, Codex CLI, Antigravity, and future hosts, make it a skill or MCP tool rather than a command shortcut.
+
+For the maintained multi-harness setup and skill/command packaging details, see
+[agent-config](https://github.com/junghan0611/agent-config). See also the
+[concept primer](../README.md#concept-primer), the sender-envelope contract in
+[AGENTS.md](../AGENTS.md), and [custom skills](../README.md#custom-skills).

package/docs/fresh-cut-policy.md

@@ -0,0 +1,99 @@
+# Fresh-cut policy
+
+The bridge is a call relay, not a memory layer. Meta-records are routing state for
+the **current generation**; native transcripts and external memory stores remain
+owned by their harnesses.
+
+## Generation contract
+
+1. The active citizen store is **V3-only**. Garden addresses and resume authority
+   never continue across generations.
+2. Install and citizen birth certify the active store **before writing**. Any
+   defect refuses the operation and names `entwurf meta-bridge-fresh-cut`.
+3. A fresh cut requires proven quiescence, archives the whole active generation,
+   and opens an empty one. It never closes a session for the operator.
+4. Archives are forensic bytes only. No runtime reads them, no restore verb exists,
+   and native transcripts and memory axes are untouched.
+
+There is no legacy reader or migrator. A native conversation that survives a cut
+receives a new garden id when its next trusted hook or registration births it in
+the new generation.
+
+## What certification checks
+
+`certifyActiveStore` is shared by the doctor and all identity writers: pi birth,
+Claude's `SessionStart`, agy's imprint, and `entwurf_register_native`. Every active
+record must be:
+
+- a regular, non-symlink `.meta.json` file;
+- readable by the live V3 schema;
+- named by the `gardenId` in its body;
+- the unique owner of its `nativeSessionId`.
+
+Previous-generation records, corruption, filename/body drift, duplicate native
+identity, and symlinks all fail certification. Address-bearing reads additionally
+refuse duplicate ownership before a record becomes a dispatch or resume target.
+`entwurf_peers` keeps healthy citizens visible and reports bad entries as diagnostics;
+it never turns an ambiguous record into authority.
+
+Targeted mailbox and sender-marker reads enforce the per-entry half of the same
+contract. They do not rescan the entire store on every relay operation. Record bytes
+are opened without following symlinks; implementation and race proofs live beside
+`readStoreRecordFile` and in the `check-meta-*` gates.
+
+## Running a cut
+
+First close every pi, Claude Code, and agy session that could own a citizen or
+transport artifact. Then run:
+
+```bash
+entwurf meta-bridge-fresh-cut
+```
+
+Quiescence fails closed. A live control socket, a marker with a live owner, a
+probe-alive native-push conversation, or a surface whose state cannot be proved
+all refuse the cut before anything moves. Absence means `ENOENT`; unreadable,
+indeterminate, or symlinked state is not treated as absent.
+
+The one bounded exception is an impossible owner pid (`<=1` or non-integer) on the
+certified Linux desktop/workstation axis. Current writers cannot mint such a marker,
+so it is reported and swept as refuted legacy/corrupt residue. A harness running as
+PID 1 is outside the certified axis and fails closed.
+
+### Exit contract
+
+| Exit | State | Next action |
+|---|---|---|
+| `0` | Cut complete | Run the appropriate installer/setup. |
+| `1` | Nothing moved | Fix the named live, unreadable, or occupied condition and retry. |
+| `2` | Usage error; nothing moved | Fix the command. |
+| `3` | Transition incomplete after at least one archive move | Inspect or rerun to finish under a new stamp. |
+| `4` | Cut complete; stale marker/socket cleanup failed | Setup may proceed, but repair the named residue first when possible. |
+
+Only exit `0` is ordinary success. Exit `4` confirms a new generation is open but
+still reports cleanup debt. Do not rerun an exit-4 cut after new citizens have been
+born: that would archive the new generation too.
+
+For the common path:
+
+```bash
+entwurf meta-bridge-fresh-cut && entwurf setup /path/to/project
+```
+
+## Upgrade order
+
+A checkout-backed host can begin running new code immediately after `git pull`, so
+make the boundary explicit:
+
+```text
+quiesce sessions → update package/checkout → fresh-cut if prescribed → reinstall/setup → reopen
+```
+
+The preflight is not a transaction or a global lock. Concurrent native births can
+race after certification, which is why discovery and address-bearing reads still
+check uniqueness. If a later doctor turns red, stop and preserve the store before
+cutting again.
+
+Source of truth: `pi-extensions/lib/meta-session.ts`, the fresh-cut implementation,
+`check-meta-*`, and `check-fresh-cut-gate`. Historical incidents and defect chronology
+belong in CHANGELOG/issues rather than this operator policy.