@junghanacs/entwurf 0.13.0 → 0.13.1

package/VERIFY.md

@@ -1,10 +1,17 @@
 # VERIFY.md
 
-Agent-driven verification guide for the `entwurf` surface as it stands in the working tree — the last **released** line is 0.12.x, and the tree is the **prepared 0.13.0 cut** (its tag, GitHub release, and publication are separate authorizations that have not run). The cut carries more than one change (the probe/ordering lane sits in it too); the change relevant to *this guide* is the second ACP backend. Rows below marked 0.12 are the released baseline; where 0.13.0 differs, it says so.
+Agent-driven verification guide for the current `entwurf` surface. Machine-checkable
+invariants live in gates; this file defines evidence strength, release acceptance,
+and the manual judgements a gate cannot make.
 
-> **Current surface.** The bundled MCP server, `entwurf-bridge`, exposes five tools: `entwurf_v2`, `entwurf_peers`, `entwurf_self`, `entwurf_inbox_read`, and `entwurf_register_native` (an explicit/manual fallback for binding an already-running native conversation). The ACP backends are **Claude** (the reference, 0.12) and, as of **0.13.0**, **Snowflake Cortex Code** (`cortex-` prefixed ids; deterministic axis `check-acp-cortex` in `pnpm check`, LIVE axis `smoke-acp-cortex-live` on demand — see [docs/acp-backend-rail.md](./docs/acp-backend-rail.md) §11-8 for the measured contract and its limits). Antigravity (`agy`) is a separate shipped **native-push citizen** lane, not an ACP backend: automatic `PreInvocation` birth + sender identity + live probe/direct injection. Codex is pi-native by default and has native delivery probe evidence; Gemini is a non-goal/historical ACP probe on 0.12. The 0.4.x `session-bridge` adapter, the 0.11.0 fat-bridge (`acp-bridge.ts` / `ensureBridgeSession`), and the v1 `entwurf` / `entwurf_resume` / `entwurf_send` verbs are **retired** — rows mentioning them survive in CHANGELOG/git as historical baseline, never as a runnable recipe.
+> **Current surface.** `entwurf-bridge` exposes `entwurf_v2`, `entwurf_peers`,
+> `entwurf_self`, `entwurf_inbox_read`, and `entwurf_register_native`. The ACP
+> backends are Claude and Snowflake Cortex Code. Antigravity is a separate shipped
+> native-push citizen lane; Codex has delivery-probe evidence but no managed citizen
+> lane. Retired v1 verbs and bridge implementations belong only in CHANGELOG/git.
 
-This is a **working document, not a metrics document**. The deterministic and live gates carry the machine-checkable invariants; this file carries only what a gate cannot judge — the human/agent reading of *whether the bridge is honestly itself*. Where a former manual procedure is now a gate, it is named as a pointer rather than re-spelled as a runnable script.
+This is a working protocol, not a metrics ledger. Per-run counts, digests, and release
+chronology belong in [BASELINE.md](./BASELINE.md), CHANGELOG, and release artifacts.
 
 VERIFY.md is the **agent-driven** surface; [BASELINE.md](./BASELINE.md) is the operator-driven one. One ACP-bridged model runs the checks against another and writes down what it sees — if the bridge is faithful, two replicants looking at the same mirror describe the mirror the same way. This is in-bridge cross-validation, not external evidence: verifier and subject share the same bridge, MCP servers, and overlay, so a uniform corruption of those would not surface here (that gap is what the L3+ rungs close).
 
@@ -35,78 +42,39 @@ Verification here is not a benchmark. In production we exchange short turns and
 
 - **Deterministic floor:** `pnpm check` — the full `check-*` gate set (the `check` script in `package.json` is the SSOT for what runs). Run first; it is the offline, machine-checkable layer.
 - **Discriminating power of that floor:** `./run.sh check-gate-qualification` (inside `pnpm check`) re-plants committed defect mutants (`scripts/mutants/*.json`, one per closed defect class) in an isolated snapshot repo and requires each to turn its gate red **bounded and at its claimed `[QK:<claim>]` signature** — a wrong-reason red fails, a baseline-red control voids the whole group, and the runner is negative-controlled on every run (zero-match/multi-match/survived/wrong-reason/hang/control-red/impurity). This measures whether the deterministic gates still *block* what they claim to block; it is **not a new evidence level** (L0–L5 are untouched) and never substitutes for LIVE evidence. Per-cut records cite claim IDs + killed mutant IDs — "N checks passed" alone is not evidence. `check-agy-permission-matrix` complements it with the enumerated permission contract space (literal cells + stated exclusion rules, oracle independent of the SUT).
-- **Live floor:** `LIVE=1 ./run.sh release-gate <scratch-project-dir>` — `pnpm check` + the v2-native live gates + the ACP plugin acceptance floor. It reports a **two-tier summary**:
-  - **MUST tier** (release-blocking — owns the exit code; "green" applies only here): `pnpm check`, `smoke-entwurf-v2-spawn-resume-live`, `smoke-entwurf-v2-matrix-live`, `check-bridge`, the resident-garden-guard zero-token half (record birth / record-keyed socket / attach-on-reopen), and the `smoke-acp-*-live` ACP plugin smokes (socket-citizen / raw-turn / overlay / provider / session-reuse / carrier-augment / memory-containment / rgg / mcp / skill / bundled-mcp / v2-send). (`smoke-session-id-name` is gone — #50 C3: its `--session-id`/`--name` substrate has no entwurf consumer anymore.)
+- **Live floor:** `LIVE=1 ./run.sh release-gate <scratch-project-dir> --cut` — `pnpm check` + the v2-native live gates + the ACP plugin acceptance floor. It reports a **two-tier summary**:
+  - **MUST tier** (release-blocking — owns the exit code; "green" applies only here): `pnpm check`, `smoke-entwurf-v2-spawn-resume-live`, `smoke-entwurf-v2-matrix-live`, `check-bridge`, the resident-garden-guard zero-token half (record birth / record-keyed socket / attach-on-reopen), the `smoke-acp-*-live` ACP plugin smokes (socket-citizen / raw-turn / overlay / provider / session-reuse / carrier-augment / memory-containment / rgg / mcp / skill / bundled-mcp / v2-send), the two axes wired in on 2026-07-31 that the aggregate had simply never listed (`smoke-entwurf-v2-spawn-live`, `smoke-claude-native-resume-live`), and `smoke-entwurf-chain-live` — the cross-harness delivery chain (native Claude Code → pi GPT → pi ACP Sonnet → mailbox terminus) proving sender identity and replyability at every hop plus a real read receipt at the end. (`smoke-session-id-name` is gone — #50 C3: its `--session-id`/`--name` substrate has no entwurf consumer anymore.)
   - **BEHAVIOR tier** (advisory, non-blocking): the resident-garden-guard positive (a model-in-loop `entwurf_self` turn). A BEHAVIOR FAIL is surfaced with its artifact path but **never blocks the cut**. The lane holds what the model *chooses*, never what our wiring fails to deliver — a gate that TELLS the model which tool to call stays MUST, because its failure is ours — measured 2026-07-24, when the tool turned out to be absent from the session schema in both observed failures (the bundled-MCP readiness gap recorded in `scripts/smoke-acp-v2-send-live.ts`).
-  - LIVE-gated MUST steps honest-skip when `LIVE!=1`; a real cut needs `LIVE=1` with `SKIP=0`. A green MUST gate is **necessary, not sufficient** — GLG authorizes the cut.
+  - **Every MUST step is invoked and reports its own outcome** (P1 STEP OUTCOME protocol, `scripts/lib/step-outcome.sh`): exit 0 = PASS, exit 97 = SKIP (a prerequisite the step does not have, printed as an `[entwurf:skip]` line), anything else = FAIL. A skip is never counted as a pass — that hole is what let a cortex-less host read as cortex acceptance. Without `--cut` this is the unattended diagnostic: SKIPs are reported and the run still exits 0. **`--cut` makes it acceptance and any MUST SKIP is red**, which is how "a real cut needs `LIVE=1` with `SKIP=0`" stopped being prose. A green MUST gate is **necessary, not sufficient** — GLG authorizes the cut.
   - **When cost-bearing MUST gates run (fixed 2026-07-23, the F6/F7 lesson):** a commit that touches a rail a MUST-tier live gate covers runs that gate **before cross-review is requested** — never parked behind "run it at approval time". Deferring a wired gate to a human decision is what let F6/F7 ship reviewed-and-approved; the wiring exists so the verdict never depends on who pressed enter. "배선이 없어 못 한 것은 OK, 배선이 있는데 안 돌린 것은 우리가 남긴 구멍이다." Model-in-loop cost is spent via the subscription-backed `entwurf` provider where the gate allows it, a free-tier native model otherwise; cost is a reason to pick the cheap target, not to skip the gate.
 
+> **Cortex is an on-demand axis, not an aggregate one.** Its rail needs an external Snowflake connection and login that the host owns, not the repo — so wiring it into the aggregate would block every cut taken on a host without that account. **The 0.13.1 aggregate does not re-certify Cortex**; `LIVE=1 ENTWURF_ACP_CORTEX_CONNECTION=<conn> ./run.sh smoke-acp-cortex-live` stays a required direct call whenever a cut changes Cortex rail code or an operator elects to certify that host. Its honest-skip behaviour is unchanged: run it without the connection and it reports protocol SKIP, never a pass.
+>
+> A cut that touches the prompt-lifecycle contract (no wall clock on a running turn) owes one long-turn acceptance the aggregate floor is too short to carry: `LIVE=1 ./run.sh smoke-acp-long-turn-live` drives a real turn whose tool work outlasts the retired 600s cutoff and requires exactly one cold ACP bootstrap in the transcript. It takes >12 minutes by construction and is on-demand, not part of `release-gate`.
+>
 > The aggregate release gate does not own a live agy conversation id, so agy's real native-push round trip is a separate acceptance axis: three fail-loud doctors plus `LIVE=1 AGY_CONVERSATION_ID=<id> ./run.sh smoke-agy-native-push-live`, followed by a fresh-conversation sender/reply check after package install. Its deterministic install/sender gates are already inside `pnpm check`; do not misreport the aggregate gate as live agy evidence.
 >
-> The authoritative per-cut counts live in BASELINE.md's HISTORY and CHANGELOG/git, not inline here (they drift against `run.sh`). Most recent recorded aggregate: **2026-07-24 (night) — MUST 16/1/0 + BEHAVIOR 1/0, EXIT=1** at `cbda097` — the single FAIL is the known bundled-MCP readiness race (ROADMAP 「🔴 OPEN」, observe-don't-fix; isolated re-runs pass). Most recent all-green floor: **2026-07-30 — MUST 17/0/0 + BEHAVIOR 1/0, EXIT=0** on the prepared 0.13.0 tree (parent landing HEAD `9f1c7dc`, scratch `/tmp/entwurf-release-gate-0.13.0.drnRyR`) — the first aggregate completion carrying the cortex adapter and the probe lane; the step count did not move, because the cortex LIVE axis is deliberately outside this aggregate and is run on demand. Before it: **2026-07-24 — MUST 17/0/0 + BEHAVIOR 1/0, EXIT=0** at `7cbeb29b6afcfbaf4fc28da3b7929037c339113d` (the dependency-uplift HEAD: pi 0.82.0 + claude-agent-acp 0.61.0 / ACP SDK 1.3.0). The step count moved 16→17 with `smoke-acp-v2-send-live`; earlier that day it had moved 17→16 with the v2-cutover smoke retirements. A release cut requires the aggregate red to be resolved or explicitly ruled by GLG.
+> Authoritative per-cut counts and digests live in BASELINE/CHANGELOG, not inline
+> here; embedding them in the protocol makes a correct guide stale after every cut.
 
-### Artifact / host certification matrix — #51 repair line → 0.12.8 stable
+### Release acceptance axes
 
-Do not collapse package evidence, fixture evidence, and a certified native host into
-one word such as “green.” They answer different questions.
+Do not collapse source, package, fixture, and native-host evidence into one “green.”
 
-| Axis | Current evidence | Level / limit | Release reading |
-|---|---|---|---|
-| Source checkout | `pnpm check` on Node 24 Linux | Deterministic source floor; not an installed artifact | Necessary; cannot certify a consumer install. |
-| Project-local tarball | `check-pack-install` | Real `.tgz`, but checkout-visible, operator-owned, project-local | Installed-shape evidence; still maintainer-shaped. |
-| Linux artifact consumer | `check-install-container` in the required `artifact-consumer` CI job | **L3 package evidence:** one read-only candidate `.tgz`; checkout/repo `node_modules` invisible; non-root `npm install -g`; PATH shims; frozen package root; regular-file path+sha256 fence; canonical artifact path+sha256 and Node 24 image identity printed. Default CI packs once; `ENTWURF_CANDIDATE_TGZ` consumes a preserved caller artifact without re-pack. | Certifies the Linux package-consumer shape. Its fake Claude, planted plugin cache, stand-in owner, and `/proc` bridge are explicitly **fixtures**: they do not prove Claude installed the cache or that a real native Claude session woke. |
-| Direct Claude negative (B) | Claude Code 2.1.138 actual session | **L4 direct-native**, one NixOS host: fixture loaded (shell canary), `args` dropped, hook reported `exit_code: 0, outcome: success` | Justifies entwurf-side fail-loud and no old-version fallback. It did not run the final production argv shape. |
-| Direct Claude positive (B2) | Claude Code 2.1.217 actual session | **L4 direct-native**, one NixOS host: per-element args, literal `${HOME}`, direct parent join, FileChanged exit 2 → idle wake | Justifies the proven floor and exec-form contract. It is not a second-OS acceptance run. |
-| Linux installed host | `doctor-meta-bridge` after package install, a **new** Claude session, and a live MCP child | **L3 host corroboration:** installed artifact + live `/proc` owner join | Published `0.12.8-repair.1` passed on maintainer + secondary Linux hosts on 2026-07-25 (BASELINE HISTORY). Missing live evidence is still `NOT CERTIFIED`; stable `0.12.8` earns its own package/CI/LIVE evidence. |
-| macOS Claude meta-bridge | New install is refused: strict live-owner certification cannot yet discover the MCP process without `/proc` | **Not yet verified/certified for this repair cut**; doctor nonzero | Linux is the only current certified axis. Darwin uninstall remains the honest inverse for older installs; the neutral package has no `os` restriction. This is not a permanent impossibility claim—future native validation may reopen macOS. |
-| WSL2 / Windows | No release lane | Unverified | Not supported by this cut. |
-
-The artifact-consumer run prints both the tarball sha256 and container image
-identity. Preserve those in the cut record. A synthetic doctor PASS proves the
-oracle can recognize a fully supplied fixture; only the installed doctor against a
-new native session proves that a real host supplied those layers.
-
-### Stable 0.12.8 order (current execution; authority is mode-specific)
-
-The repo-local `entwurf-release` skill is a checkpointed state machine. Each mode
-is a separate authorization; one mode never implies the next. The repair history
-remains in CHANGELOG: repair.0 was field-broken, repair.1 restored delivery, and
-on 2026-07-25 its installed artifact passed the real native doctor on maintainer
-and secondary Linux hosts. That closed the explicit prerequisite for promoting
-this line to stable `0.12.8`; it does not transfer CI/LIVE/candidate evidence to
-the new stable bytes.
-
-1. `land 0.12.8` pushes only the clean **pre-version landing HEAD** and requires
-   a push-triggered `ci.yml` run whose `headSha` is exactly that commit. Current
-   accepted landing: `1345688001ed6629bd0f58996a36134e7b7874bc`, run
-   [30150824225](https://github.com/junghan0611/entwurf/actions/runs/30150824225),
-   with `check`, `install-surface`, and `artifact-consumer` all success.
-2. `prepare 0.12.8` promotes the changelog, sets the package version, reruns the
-   deterministic and LIVE gates, and creates the release-prep commit. It never
-   pushes, tags, creates a candidate, or publishes.
-3. `make 0.12.8` pushes that clean prepared HEAD and requires the same three jobs
-   on that exact version commit. Only after the second exact-SHA CI is green does
-   it preserve and accept one candidate without repacking:
-
-   ```bash
-   ARTIFACT_DIR=$(mktemp -d /tmp/entwurf-release-candidate-0.12.8.XXXXXX)
-   bash scripts/with-dist-lock.sh npm pack --dry-run=false --pack-destination "$ARTIFACT_DIR"
-   CANDIDATE="$(realpath "$ARTIFACT_DIR/junghanacs-entwurf-0.12.8.tgz")"
-   sha256sum "$CANDIDATE"
-   ENTWURF_REQUIRE_DOCKER=1 ENTWURF_CANDIDATE_TGZ="$CANDIDATE" \
-     ./run.sh check-install-container | tee "$ARTIFACT_DIR/acceptance.log"
-   ```
-
-   The gate must print caller-preserved candidate mode, the same canonical path
-   and SHA-256, and the image identity. `make` then tags the exact prepared SHA
-   and creates the GitHub release. Never repack accepted bytes.
-4. Only an explicit `publish 0.12.8 <absolute-candidate> latest` may publish the
-   accepted file. Registry proof requires `latest=0.12.8` while preserving
-   `repair=0.12.8-repair.1`, followed by the registry-installed smoke.
-
-Invoking `land`, `prepare`, `make`, or `publish` grants only that named mode's
-authority. `prepare` stops at a local commit; `make` and `publish` remain separate
-GLG decisions.
+| Axis | Required proof | Limit |
+|---|---|---|
+| Source | `pnpm check` | Does not prove an installed consumer. |
+| Packed install | `check-pack-install` | Real tarball, but checkout-visible. |
+| Linux artifact consumer | required `check-install-container` CI job against one preserved candidate | Fixtures prove package/oracle shape, not a real Claude lifecycle. |
+| Exact release commit | all required CI jobs green at the exact SHA | A different green SHA is not transferable evidence. |
+| LIVE runtime | `LIVE=1 ./run.sh release-gate <scratch> --cut` plus any shipped on-demand backend axis | `--cut` enforces `SKIP=0`; a red wired gate blocks the cut. |
+| Native Claude host | installed strict doctor against a new real session | Missing live join is `NOT CERTIFIED`, not a fixture PASS. |
+| Native agy host | three doctors plus conversation-id-gated native-push round trip | Aggregate release-gate does not own an agy conversation id. |
+
+The repo-local `entwurf-release` skill owns the `land → prepare → make → publish`
+state machine. Each mode is a separate GLG authorization. Preserve one candidate,
+accept and publish those exact bytes without repacking, and record its digest and
+consumer image outside this standing protocol.
 
 ### Verifying the two capabilities a gate cannot fully judge
 
@@ -136,7 +104,7 @@ When injecting a fact for a continuity check, use **plaintext that does not trig
 
 ### bridge continuity vs semantic continuity
 
-- **bridge continuity:** same `sessionKey` / same `acpSessionId` via in-memory reuse or persisted resume/load (bootstrap `path=reuse|resume|load`).
+- **bridge continuity:** same `sessionKey` / same `acpSessionId` through in-memory process-scoped reuse. Persisted session records are written for a future resume/load lane but are not consumed today.
 - **semantic continuity:** a fact from a prior turn is retrievable in a later turn.
 
 Either can be alive while the other looks dead (the wording case above is bridge-alive / semantic-looks-dead). When in doubt, change the wording and retry once, and check the `[entwurf:bootstrap]` lines in bridge stderr. No automated smoke separates these yet.
@@ -145,7 +113,7 @@ Either can be alive while the other looks dead (the wording case above is bridge
 
 The goal is not merely "invoke Claude Code." We want:
 
-1. **Session continuity at the agent-shell level** — through ACP session resume/load/new, not re-throwing a text blob.
+1. **Session continuity at the agent-shell level** — process-scoped turns reuse one live ACP session; fresh/turn-scoped paths open a new one rather than reconstructing a transcript inside entwurf.
 2. **Preservation of pi harness semantics** — pi session files / transcripts / memory pipeline stay a shared axis.
 3. **restart-hygienic** — process-scoped reuse continues the same ACP session across turns inside a long-lived resident; persisted records are written/validated for the future resume-load lane, not the live continuity path today.
 4. **Thin bridge** — no second harness built inside this repo.
@@ -185,7 +153,7 @@ cd "$REPO_DIR" && ./run.sh setup "$PROJECT_DIR"
 ### 1.2 Live acceptance (optional)
 
 ```bash
-LIVE=1 ./run.sh release-gate /path/to/consumer-project
+LIVE=1 ./run.sh release-gate /path/to/consumer-project --cut
 pi --provider entwurf --model claude-sonnet-5 -p "reply with ok only"   # one-turn smoke
 ```
 
@@ -197,13 +165,18 @@ addressable sends require `--entwurf-control` (measured 2026-07-24: the same
 one-shot with that flag returns its own gid and delivers `entwurf_v2` to a peer
 mailbox with `origin=pi-session`, `replyable=true`).
 
-`setup` runs `pnpm install` + project/user-scope install + detected native-harness wiring (Claude and/or agy) + the v2 install smoke. A green setup proves the required core path and reports optional-harness degradation; it does **not** replace the native-harness doctors. The full aggregate live floor is still `LIVE=1 ./run.sh release-gate`, with agy's conversation-id-gated round trip verified separately.
+`setup` runs `pnpm install` + project/user-scope install + detected native-harness wiring (Claude and/or agy) + the v2 install smoke. A green setup proves the required core path and reports optional-harness degradation; it does **not** replace the native-harness doctors. The full aggregate live floor is still `LIVE=1 ./run.sh release-gate <scratch> --cut` — without `--cut` it is a diagnostic pass, not acceptance — with agy's conversation-id-gated round trip verified separately.
 
 ### 1.4 Cross-install / cross-backend parity (optional, high-value)
 
-Compare a fresh self-awareness report across axes: (1) same backend, different install path — answer must be path-invariant; (2) same backend, different machine — identical native tool list + MCP server/tool set; (3) different backend, same bridge — same garden capability but **different** native tool surface (a Claude session reporting another backend's native tools is a fail); (4) native pi routing vs ACP-bridged, same model — the native target reports no `entwurf-bridge` MCP (capability via pi's extension surface), while the ACP target reports it as the single MCP server. Honest "native: I cannot tell" hedging is PASS on the native side. Claude axes 1–4 are closed. agy is graded by the separate native-citizen checklist above, not by pretending it has Claude's ACP overlay. Gemini remains probe-only on 0.12.
+Compare a fresh self-awareness report across axes: (1) same backend, different install path — answer must be path-invariant; (2) same backend, different machine — identical native tool list + MCP server/tool set; (3) different backend, same bridge — same garden capability but **different** native tool surface (a Claude session reporting another backend's native tools is a fail); (4) native pi routing vs ACP-bridged, same model — the native target reports no `entwurf-bridge` MCP (capability via pi's extension surface), while the ACP target reports it as the single MCP server. Honest "native: I cannot tell" hedging is PASS on the native side. agy is graded by its native-citizen checklist, not by pretending it has an ACP overlay.
 
-**Cortex (0.13.0) on axis 3.** Cortex is the first real *different backend, same bridge* subject, and it is the sharpest form of this axis: a cortex session must report the garden capability (`entwurf-bridge` reachable, record-backed peers) while its native tool surface is cortex's own, never Claude's — a cortex session listing Claude's built-ins is a fail. Two contract facts to grade against rather than re-derive: the callable identifier shape is the same `mcp__<server>__<tool>` convention as Claude (**measured**, §11-8), and cortex is **system-prompt-carrier-less**, so the operator engraving arrives at the head of the first-user augment instead of in a system prompt — a cortex session claiming a system-prompt engraving is reporting something it does not have. Axis 1 (install-path invariance) is split as of 0.13.0: the **deterministic** half is closed — `check-pack-install` enumerates the exact six curated rows out of the installed package's own model list — while the **live** half is a release-blocking `make` tag gate (the preserved exact candidate installed into a fresh temporary root driving one cold `entwurf/cortex-claude-sonnet-5` turn from those installed bytes). Until that gate runs, installed-artifact evidence and real-Cortex evidence have never met in one execution. Axis 2 (second machine) is unrun.
+**Cortex on axis 3.** A cortex session must expose the same garden capability
+while keeping cortex's own native tool surface. Its callable MCP identifier shape is
+the same as Claude's, but it has no system-prompt carrier: engraving is prepended to
+the first user augment. Installed-model enumeration is deterministic; candidate-installed
+LIVE Cortex acceptance and its remaining host limits are recorded per cut rather than
+frozen here.
 
 ---
 
@@ -243,8 +216,9 @@ The single-turn / multi-turn / cross-process / persistence-boundary / shutdown i
 | Single-turn prompt extraction, SessionStart hook not mistaken for prompt | `smoke-acp-raw-turn-live`, `check-acp-prompt-builder` |
 | Multi-turn continuity + recall (process-scoped reuse) | `smoke-acp-session-reuse-live`, `check-acp-session-reuse` |
 | Cross-process continuity / cache before-after | `check-acp-session-store` (signature, decideBootstrap, persist/parse) |
-| Lifecycle policy — a turn-scoped `cwd:` fallback is never a persisted resume/load path; process-scoped records are hashed-`sessionKey` records | `check-acp-session-store` (`resolveLifecyclePolicy` turn-scoped→always-new, `decideBootstrap`, sha256 `SessionRecord` build/parse/roundtrip) — the former inline `acp-bridge.ts` repro is retired with the fat-bridge |
+| Lifecycle policy — turn-scoped is always new; process-scoped may reuse only the live in-memory session; persisted records are not a resume/load path today | `check-acp-session-store`, `check-acp-session-reuse` |
 | Tool-call / event mapping | `check-acp-event-mapper`, `smoke-acp-provider-live` |
+| Prompt lifecycle — no wall-clock cutoff on a running turn; abort ends it by ACP `session/cancel` with bounded cleanup; a child death is reported with exit status + stderr on new AND reuse turns; our prompt-phase error text is not classified transient by pi | `check-acp-prompt-lifecycle`, `check-probe-ordering` |
 | Operator mcpServers / skills reach the live session | `smoke-acp-mcp-live`, `smoke-acp-skill-live`, `check-acp-config` |
 | Overlay isolation + memory containment | `check-acp-overlay`, `smoke-acp-memory-containment-live`, `check-acp-tool-surface` |
 
@@ -252,18 +226,16 @@ The single-turn / multi-turn / cross-process / persistence-boundary / shutdown i
 
 The literal callable identifier differs per backend — probe by asking the agent to print it **verbatim** (do not ask "hyphen or underscore" — ambiguous between outer separator and inner server name):
 
-| Backend | Literal identifier | Outer sep | Inner server name |
-|---|---|---|---|
-| Claude | `mcp__entwurf-bridge__entwurf_v2` | `__` | `entwurf-bridge` (hyphen) |
-| Cortex *(0.13.0)* | `mcp__entwurf-bridge__entwurf_v2` | `__` | `entwurf-bridge` (hyphen) — same shape as Claude, **measured** (§11-8) |
-| Codex | `mcp__entwurf_bridge__.entwurf_v2` | `__` | `entwurf_bridge` (underscore) + **literal dot** |
-| Gemini *(probe)* | `mcp_entwurf-bridge_entwurf_v2` | `_` (single) | `entwurf-bridge`, no dot |
+| Backend | Literal identifier | Boundary |
+|---|---|---|
+| Claude | `mcp__entwurf-bridge__entwurf_v2` | native Claude tool surface + explicit MCP server |
+| Cortex | `mcp__entwurf-bridge__entwurf_v2` | same identifier shape, different native tool surface |
 
-A Claude session reporting the underscore form, or any cross-shape leak, is a backend-identification leak. Released 0.12 baseline is Claude; cortex joins it in 0.13.0 and is the one row whose shape had to be *measured* rather than assumed (identical to Claude's — so this row cannot discriminate Claude from Cortex, and the tool-surface axis in §1.4 is what does). The Codex/Gemini rows are reference for the probe lanes.
+The identifier cannot distinguish Claude from Cortex; native tools and carrier facts must.
 
-### 2.2 MCP injection visibility — equal across resume/load/new
+### 2.2 MCP injection visibility
 
-The sole MCP responsibility of `entwurf` is to inject `entwurfProvider.mcpServers` equally into `newSession` / `resumeSession` / `loadSession`. Ask "list the visible MCP server names": the registered `entwurf-bridge` appears, unregistered MCPs do not (no automatic `~/.mcp.json` loading); the list is identical every turn; changing `entwurfProvider.mcpServers` changes `bridgeConfigSignature` and forces a new session. `check-acp-config` + `smoke-acp-mcp-live` pin this; the manual check is an honesty corroboration.
+The sole MCP responsibility of `entwurf` is to project explicit `entwurfProvider.mcpServers` into every newly opened backend session. Ask for visible MCP server names: `entwurf-bridge` appears, ambient servers do not, and changing the declaration changes `bridgeConfigSignature` so a live incompatible session is replaced rather than silently reused. `check-acp-config` and `smoke-acp-mcp-live` pin this; the manual check is honesty corroboration.
 
 ### 2.3 Process / cache hygiene — the orphan bound (§gate-external judgement)
 
@@ -274,7 +246,7 @@ AFTER_<BACKEND> ≤ BEFORE_<BACKEND> + (distinct alive
   (sessionKey, backend, modelId, bridgeConfigSignature) tuples this run holds open)
 ```
 
-An **upper bound**, not an equation: child reuse (one `entwurf` + N resumes share one child → delta 0 is expected) and idle reaping push `AFTER` below it; a config-signature or `(provider, model)` switch pushes it up by 1. `AFTER > BEFORE + alive_tuples` is the actionable signal — an unexpected child appeared. Walk the parent chain (`pgrep -af 'claude-agent-acp|codex-acp'` → `ps -o ppid=`); any ACP child whose parent `pi` has exited is an **orphan** — flag and preserve as evidence.
+An **upper bound**, not an equation: child reuse and idle reaping may keep the delta below it; a config-signature or `(provider, model)` switch may add one. `AFTER > BEFORE + alive_tuples` is actionable. Walk the backend process parent chain; any ACP child whose parent `pi` has exited is an orphan—preserve it as evidence.
 
 ### 2.4 pi session record as a shared memory axis
 
@@ -289,13 +261,13 @@ Pass: user/assistant turns accumulate normally; the transcript is not broken/emp
 
 ---
 
-## 3. Pass criteria — the 0.12 release floor
+## 3. Pass criteria — current release floor
 
 The minimum passing bar:
 
 1. **Deterministic floor green:** `pnpm check` passes (lint + typecheck + the `check-*` gate set + `check-pack`).
 2. **All three CI jobs green on the exact release commit:** `check`, `install-surface`, and the required Linux `artifact-consumer`; preserve the latter's tarball digest and image identity.
-3. **Live floor MUST green:** `LIVE=1 ./run.sh release-gate <dir>` reports `MUST PASS=N FAIL=0 SKIP=0`; a BEHAVIOR FAIL is advisory, not blocking.
+3. **Live floor MUST green:** `LIVE=1 ./run.sh release-gate <dir> --cut` exits 0 reporting `MUST PASS=N FAIL=0 SKIP=0`; with `--cut` a single SKIP is red, so the exit code itself now carries this condition. A BEHAVIOR FAIL is advisory, not blocking.
 4. **Native-host doctor green where the Claude meta-bridge is claimed:** a new post-install Claude session exists, live evidence is present, and the installed `doctor-meta-bridge` exits 0. `NOT CERTIFIED` is a release failure for that host, not a skip.
 5. **Honest self-recognition:** the bridged model identifies its actual harness/backend, lists `entwurf-bridge` as the single MCP server with its five current tools, and presents a backend-native (not normalized) tool surface.
 6. **Carrier separation honored:** engraving vs pi-context-augment kept distinct (§1A.0); no bridge-identity narrative attributed to the engraving carrier.
@@ -315,7 +287,6 @@ Passing establishes a **release verification floor**, not an 8-hour/day operatio
 - **Retired dedicated smokes, live code invariants** (manual/troubleshooting only — *not* part of the release floor):
   - *Model-switch lock* — entwurf sessions are locked to their starting model. Gate: `check-model-lock` (in `pnpm check`). The dedicated live `smoke-model-switch` was retired in v2; the invariant lives in `pi-extensions/model-lock.ts` (extension guard) + `session-store.ts` `SessionModelLockedError` (the `decideBootstrap` fail-loud model lock).
   - *Cancel / abort cleanup* — `onAbort` → `cancelActivePrompt()` (session stays reusable); the stream catch closes the bridge only on `stopReason === "error"`. Dedicated `smoke-cancel` retired; invariant in code.
-  - *Transcript-poison invalidation (#12)* — **historical (0.11):** a poisoned backend transcript (empty text block ± `cache_control`) returned the same Anthropic 400 forever, handled by a dedicated classifier + `verify-transcript-poison` smoke. Both were retired in the 0.12 cutover; there is **no dedicated classifier or gate on the current surface** — recorded only so the failure mode is not forgotten.
 
 ### Evidence preservation when a problem occurs
 

package/demo/README.md

@@ -137,7 +137,7 @@ SCENE_DELAY=30 FINAL_PAUSE=10 bash demo.sh
 
 ## Prerequisites
 
-- `pi` on PATH (current floor 0.82.1)
+- `pi` on PATH (current floor 0.83.0)
 - `entwurf` provider configured + auth ready for the selected sender/peer models
 - `asciinema` installed
 - `agg` installed (optional — only for GIF conversion)

package/docs/acp-backend-rail.md

@@ -0,0 +1,231 @@
+# 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.64.0 nor the Cortex landing adds a client-side
+readiness fence, and `mcpServerStatus()` is not called by the common loop.
+
+### 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. The deterministic mutants in `probe-ordering.json` are the detailed oracle.
+
+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 check
+./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;
+- Codex managed native-citizen work on the reserved 0.14.0 lane—separate from ACP;
+- persisted ACP resume/load, which is not implemented by today's in-memory reuse.