@junghanacs/entwurf 0.12.0

package/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to entwurf
+
+This is a daily-driver bridge. Correctness beats feature breadth. Read this before opening a PR.
+
+## What this repo is
+
+`entwurf` is a **garden-citizen dispatch bridge** — entwurf-core (v2 dispatch) + a meta-bridge + a pi adapter + a **Claude-first ACP plugin** — that lets already-running harnesses address one another by garden id; pi is one adapter, not the subject. The ACP plugin borrows the backend's identity (system prompt preset, model behavior, tool implementations) and shapes the *operating surface* — what tools, MCP, skills, and permissions are visible — to match pi's own policy. Claude is the shipped ACP backend, Codex is a native garden citizen, and the Gemini path is deprecated. That is the entire scope.
+
+If a change moves the bridge toward "second harness" — prompt reconstruction, transcript hydration, ambient discovery, silent fallback — it does not belong here.
+
+## Hard invariants
+
+These are enforced by code, gates, and review. Do not weaken them in a PR; if you want to argue against one, open an issue first.
+
+1. **Bootstrap order**: `resume > load > new`. Always.
+2. **Session persistence**: only `pi:<sessionId>` is persisted. `cwd:<cwd>` is never persisted.
+3. **MCP injection**: only via `entwurfProvider.mcpServers`. No ambient `~/.mcp.json` scanning, no `~/.claude/settings.json` MCP inheritance.
+4. **Operating surface, not config inheritance**: the user's filesystem Claude Code config (`~/.claude/settings.json` hooks, env, plugins, `permissions.defaultMode`) is intentionally *not* inherited. Skills come from `skillPlugins`, permissions from `permissionAllow`, deferred-tool surface from `disallowedTools`. The `CLAUDE_CONFIG_DIR` overlay enforces this even where the SDK reads filesystem independently of `settingSources`.
+5. **Backend-specific knobs stay explicit and namespaced**: Codex/Gemini-era ACP knobs are not part of the current Claude-first shipped path. If a future backend lane reintroduces a sandbox or mode knob, it must use the `ENTWURF_ACP_*` namespace and invalid values must throw, never fall back.
+6. **Bridge does not implement compaction**: When a backend compacts natively, the pi session and mapping survive that. Pi-side JSONL compaction must not be presented as backend-transcript reduction, and backend-specific compaction controls belong to the backend's own native interface. Legacy `PI_SHELL_ACP_*` compaction knobs must not reappear.
+7. **Backend coverage honesty**: changes to operating surface, session lifecycle, or persistence must state which shipped/probed backend surfaces they cover. A claim that silently drops a covered backend is a regression; if one backend is genuinely not covered, record that carve-out explicitly.
+8. **This bridge is not a second harness**: no prompt reconstruction, no transcript hydration, no tool result ledger, no Claude Code emulation.
+
+## Required gate before opening a PR
+
+```bash
+pnpm check
+```
+
+This wraps the entire static-quality surface (biome, tsc, all `check-*` gates including `check-dep-versions`). It is wired into the pre-commit hook (`.husky/pre-commit`), so a clean local commit is the first sign your change holds.
+
+For changes that touch backend launch, session lifecycle, or `_meta` shape, also run:
+
+```bash
+./run.sh smoke-all /path/to/your-fixture-project
+./run.sh verify-resume /path/to/your-fixture-project
+```
+
+These need a real ACP subprocess, so they stay manual — the hook does not run them.
+
+## What gets PRs rejected
+
+- adds ambient MCP discovery (project `.mcp.json`, `~/.mcp.json`, etc.) without an explicit `entwurfProvider.mcpServers` opt-in path
+- inherits user / project / local backend config by default (i.e. flips `settingSources` away from `[]`, drops the `CLAUDE_CONFIG_DIR` overlay, removes the codex `-c` config flags)
+- weakens `resume > load > new` (e.g. silently downgrading to `new` without a logged invalidation reason)
+- introduces `console.warn` / silent fallback where the bridge should `throw` (see `AGENTS.md` "Never warn. Throw.")
+- changes the Claude, Codex, or Gemini operating surface (tools, skills, MCP, permissions, sandbox) without accounting for all three backends or recording an explicit carve-out
+- adds a second transcript ledger, a prompt reconstruction layer, or any state that competes with pi's session as the source of truth
+- skews version pins across `package.json`, `run.sh`, and `README.md` (the `check-dep-versions` gate catches this; if it complains, fix all three)
+
+## Style and code shape
+
+- Read `AGENTS.md` for the full code-shape rules. Highlights:
+  - fail-fast: throw on bad config, never warn-and-continue
+  - no `try/catch` swallowing — `catch {}` is allowed only for environment probing
+  - send-is-throw — messages aren't awaited
+  - one surface name (`entwurf`)
+- Comments explain *why*, not *what*. Reach for them at non-obvious decisions, especially around SDK / claude-agent-acp / codex-rs interaction edges that future maintainers won't know to look up.
+- Keep changes single-responsibility per commit; bundling a refactor with a behavior change makes review and bisect painful.
+
+## When in doubt
+
+Open an issue describing the backend boundary you want to touch and the failure mode you observed. The repo is small; over-coordination is cheap, regression on a daily-driver tool is expensive.

package/DELIVERY.md

@@ -0,0 +1,209 @@
+# DELIVERY.md — Async delivery capability levels
+
+`DELIVERY.md` is the cross-harness yardstick for one question:
+
+> Can an already-running native agent session receive an async message, without
+> pretending that pi owns the backend transcript?
+
+It is **not** a product promise and not a benchmark. It is a diagnostic coordinate
+system. When Claude Code, Antigravity, Codex, pi-native Entwurf, or a future
+harness behaves differently, record the exact delivery level it reaches instead
+of collapsing the result into "works" / "doesn't work".
+
+Companion surfaces:
+
+- [VERIFY.md](./VERIFY.md) — agent-driven bridge verification and evidence quality (`L0–L5`).
+- [BASELINE.md](./BASELINE.md) — operator-driven identity / overlay baseline interviews.
+- [`scripts/raw-async-delivery/`](./scripts/raw-async-delivery/) — reproducible raw delivery probes.
+
+## Scope and non-goals
+
+This document is about **native live-session delivery** for the 0.12.0
+meta-bridge direction: a garden meta-session points at a backend-owned native
+session, and async messages reach that session through the backend's own
+supported surfaces.
+
+Non-goals:
+
+- no tmux / pty `send-keys` as evidence for native delivery;
+- no backend transcript hydration into pi JSONL;
+- no direct writes into backend transcript databases / JSONL / protobuf files;
+- no new prompt spawn (`claude -p`, fresh Codex thread, etc.) masquerading as
+  delivery into an already-running subscription/native session;
+- no fake pi session or tool-result ledger for an external backend.
+
+A backend may use a socket, filesystem watch, JSON-RPC app server, lifecycle
+hook, or another official surface. The transport differs; the levels below keep
+the judgement comparable.
+
+## State vocabulary
+
+Use these words precisely in scripts and docs:
+
+| State | Meaning |
+|---|---|
+| `queued` | Message is durably written to a mailbox / sender queue. The backend has not necessarily seen it. |
+| `triggered` | A backend-supported event fired: socket RPC accepted, hook fired, file watch event observed, etc. |
+| `woke` | An idle interactive session started a new turn without user typing / pty injection. |
+| `injected` | The message or a doorbell pointing at it reached model-visible context through an official channel. |
+| `processed` | The turn ended or the backend acknowledged completion through a supported hook/event. |
+| `replied` | A result returned to the garden/pi side through an explicit reply path (MCP send, outbox, API result). |
+
+Avoid bare `delivered` unless you define it. Preferred decomposition:
+`queued → triggered → woke → injected → processed → replied`.
+
+## Delivery levels (D0–D8)
+
+These are a separate namespace from VERIFY.md evidence levels (`L0–L5`) and
+BASELINE.md overlay layers (`Q-L1` etc.). Mark the highest level reached and any
+partial levels.
+
+| Level | Name | PASS criterion | Typical failure / partial |
+|---|---|---|---|
+| **D0** | Live session identity | Can identify the target live session: native id, cwd/project, backend, and enough liveness metadata to address it. | Only transcript files exist; no live-session join key. |
+| **D1** | Native/free continuation | Delivery targets an already-running native/subscription session; no fresh prompt spawn or metered worker is created for the message. | Uses `claude -p`, a fresh Codex thread, or a new pi child instead of the live session. |
+| **D2** | Receiver armed | The receiving session registers an official receive surface: hook/watch path/socket/app-server subscription. | A mailbox exists but no live session is watching or reachable. |
+| **D3** | Addressed enqueue | Sender can queue a message for exactly one target session id; siblings are not broadcast-woken. | Shared signal wakes every session; no per-session address. |
+| **D4** | Idle active wake | An idle interactive session wakes from an external signal with no user typing and no pty/tmux injection. | Piggyback only: message waits until the next human/user turn. |
+| **D5** | Context injection | A unique token / message body reaches model-visible context via an official hook/API path; the model can acknowledge it. | Hook logs show activity, but the model never sees the message. |
+| **D6** | Same session/model continuity | The response comes from the same native session/conversation and same model/subscription path. | A new conversation/process handles the message; model changed silently. |
+| **D7** | Completion / reply observation | Completion or reply can be observed without transcript scraping: Stop/SessionEnd/PostInvocation, outbox, MCP reply, API result, etc. | Wake and context work, but the garden side cannot know when the turn finished except by watching the UI. |
+| **D8** | Operational robustness | Duplicate suppression, delivery markers, loop guards, level-triggered body drain, ordering policy, stale-session handling, and crash recovery are implemented/tested. | Demo works once but can loop, duplicate, reorder, leave unread backlogs, or lose messages. |
+
+### Script result contract
+
+Raw probes should print a summary block that a human or later parser can compare
+across harnesses:
+
+```text
+DELIVERY_LEVELS:
+harness=claude-code
+transport=filechanged-watchpaths-asyncrewake
+D0 live_session: pass
+D1 native_free_continuation: pass
+D2 receiver_armed: pass
+D3 addressed_enqueue: pass
+D4 idle_active_wake: pass
+D5 context_injection: pass token=AGY-PARITY-3399
+D6 continuity: pass session_id=<native-id> model=claude-opus-4-8
+D7 completion_reply: partial reason="no garden outbox yet"
+D8 robustness: partial reason="loop guard present; crash recovery not tested"
+```
+
+When a level is **not applicable** or **conditional**, say so explicitly. For
+example, Codex app-server delivery is conditional on a loaded thread and control
+socket; direct Codex TUI is a different surface.
+
+## Current capability matrix (2026-06-24)
+
+This matrix is a snapshot of what the raw probes have established. It should be
+updated when a backend version changes the delivery surface.
+
+The **Status** column is the 0.12.0 release framing, kept separate from the
+`D0–D8` capability level:
+
+- **shipped** — a supported entwurf 0.12.0 lane: wired, gated, and addressable through the bridge today.
+- **verified-probe** — async delivery proven by a raw probe, but not yet a shipped/supported lane in 0.12.0 (documented, ships after this cut).
+- **deferred** — not addressable as-is, or needs an extra managed install / cloud surface that is out of 0.12.0 scope.
+
+| Harness / surface | Status | Highest current level | Transport | Notes |
+|---|---|---:|---|---|
+| **pi native Entwurf** | shipped | D7+ | Unix control socket + pi followUp/custom messages | Replyable pi session. This is the resident baseline, not an external meta-session. 0.12.0 `entwurf_v2` treats a record-less but live pi control socket as a socket-only `fire-and-forget` target (addressed by its socket, not a meta-record); record-less *dormant* resume is intentionally not claimed. |
+| **Claude Code interactive 2.1.163** | shipped | D6, D7 partial, D8 partial | Plugin/global `SessionStart` arms `watchPaths`; external write triggers `FileChanged`; `asyncRewake` wakes idle session | Active idle wake proven without pty. `Stop` alone is piggyback-only. `asyncRewake` is a doorbell; body is self-fetched from mailbox. D8 partial: duplicate/read idempotence, honest unread counts, and level-triggered body drain are gated; empirical wake-edge bounds and unread-heartbeat backstop remain open (#34). |
+| **Antigravity / agy** | verified-probe | D6+ | Native LS gRPC `agentapi send-message` | Active push into live conversation. Same judgement levels; transport differs from Claude. Delivery proven; a shipped adapter lane lands after the 0.12.0 doc cut. |
+| **Codex app-server-backed TUI 0.136.0** | verified-probe | D6, D7 (status) | WebSocket-over-UDS `turn/start` into the live `threadId` | **Demonstrated, no managed standalone, no cloud.** `codex app-server --listen unix://<owned 0700 dir>` + plain `codex` auto-attach (or `--remote unix://`). Full message injection (agy-like, not a doorbell); `thread/status/changed` gives completion observation. D8 robustness (dedupe / crash recovery / ordering policy) is not tested. `turn/steer` is active-turn steering, not idle wake. |
+| **Codex embedded TUI 0.136.0** | deferred | D0 partial | Native state DB / rollout transcript only | Standalone Embedded TUI binds no socket; no `FileChanged`/`asyncRewake` in Codex hooks; not retrofittable. Identify-only via state DB / rollout. |
+| **Codex managed-daemon / remote-control 0.136.0** | deferred | D4–D6 conditional | `app-server proxy` newline JSON-RPC over the daemon control socket | Needs the managed standalone install; `remote-control` also enables the **cloud** bridge. Use the bare `--listen` path above for a purely-local setup. |
+| **ACP Claude / Cortex (candidate)** | deferred | — | ACP (via entwurf's pi adapter) | Shipped as an ACP *runtime* lane (you can run Claude through ACP — see VERIFY/README), but **not a native-async-*delivery* target**: ACP sessions are bridge-spawned children, not already-running native sessions to wake, so they fall outside this doc's delivery question. `deferred` here means "no async-delivery lane," not "unsupported." Cortex is the candidate that would land on the ACP path next. |
+
+## Backend notes
+
+### Claude Code — filesystem event wake, not socket push
+
+A missing local listening socket does **not** imply idle wake is impossible.
+Claude Code interactive can be woken by a supported filesystem-event path:
+
+1. a plugin or settings hook runs at `SessionStart`;
+2. it emits `watchPaths` for a per-session signal file;
+3. an external sender writes a per-session message and pokes that signal;
+4. `FileChanged` fires while the session is idle;
+5. the hook exits with `asyncRewake` and writes the doorbell to **stderr**;
+6. the same session/model wakes and self-fetches the message body.
+
+#### D8 partial — signal/body separation is level-triggered
+
+Claude's `FileChanged` signal is an edge: rapid signal writes may coalesce, and a
+true missed edge can leave an idle session with unread mail until another wake or
+backstop occurs. The body is not carried in that edge. Bodies are durable mailbox
+files (`*.msg` before the doorbell, `*.msg.delivered` after the doorbell), and
+`entwurf_inbox_read` drains the whole unread set in one read and archives them as
+`*.read`. Therefore a coalesced doorbell does not drop message bodies: once the
+receiver self-fetches, it consumes all queued bodies, not "one event = one body".
+
+Deterministic gates: `check-meta-session` asserts mixed fresh/delivered bodies are
+drained together and re-read is empty; `smoke-meta-honesty` asserts the doorbell's
+unread count matches what the inbox reader will drain. Remaining D8 work is still
+honest/open in #34: empirical FileChanged coalescing bounds, active-turn arrival,
+watchPath edge cases, compact-window re-arm gaps, and a heartbeat/re-poke backstop
+for live sessions with unread mail.
+
+Important gotchas live in [`scripts/raw-async-delivery/README.md`](./scripts/raw-async-delivery/README.md):
+`Stop` hooks do not wake idle sessions, bare skills cannot arm startup watches,
+plugins can, and imperatives in injected text can be flagged as prompt injection.
+
+### Antigravity / agy — native push
+
+Antigravity reaches the same delivery levels through a different transport:
+`agy agentapi send-message` over the native LS gRPC surface. This is not a reason
+to make the garden layer backend-specific; it is exactly why the adapter contract
+must describe capability (`D0–D8`) separately from transport.
+
+### Codex — split by launch mode, not by "Codex"
+
+Do not describe "Codex" as one delivery shape. The split is the TUI's launch mode:
+
+- **standalone Embedded TUI**: binds no socket, no `FileChanged`/`asyncRewake` in
+  Codex hooks, decision fixed at `run_main` → not addressable, not retrofittable;
+- **app-server-backed TUI**: idle-wake **works**. Run a bare
+  `codex app-server --listen unix://$HOME/.codex/app-server-control/app-server-control.sock`
+  (no managed standalone, no cloud — only the official daemon path needs the
+  managed install). Plain `codex` (no `-c`) auto-attaches to that default socket;
+  an external WebSocket-over-UDS client sends `turn/start` to the live `threadId`.
+  Measured: idle thread woke with zero typing, body injected, model replied,
+  completion observed via `thread/status/changed`.
+
+Sender: `raw-codex-ws-turn-start.py` → bare `--listen` socket (WebSocket, no managed
+standalone, no cloud). A second surface exists but is out of scope here — the managed
+**daemon** control socket (via `codex app-server proxy`) needs the managed standalone
+install, and `remote-control` enables the cloud bridge; we ship only the bare-local
+path. Per-folder `config.toml` `[projects."<path>"]` trust gates project-hook loading,
+not addressability.
+
+A Codex adapter must declare which launch mode + which socket it targets.
+
+## How to use this in 0.12.0 design
+
+For meta-sessions, peer records should expose capability rather than hiding
+backend differences:
+
+```ts
+type WakeMode = "socket" | "file-watch" | "native-push" | "app-server" | "piggyback" | "none";
+
+type DeliveryPeer = {
+  sessionId: string;              // garden id
+  kind: "pi-session" | "meta-session";
+  backend: "pi" | "claude-code" | "agy" | "codex" | string;
+  replyable: boolean;
+  wakeMode: WakeMode;
+  deliveryLevel: "D0" | "D1" | "D2" | "D3" | "D4" | "D5" | "D6" | "D7" | "D8";
+};
+```
+
+MVP rule of thumb:
+
+- expose what is proven;
+- mark partial/conditional honestly;
+- keep transcript ownership native;
+- treat liveness as best-effort hint (`last_seen` + native presence), not as a
+  single authoritative socket/WAL/file check;
+- keep lookup authority in the meta-record scan, not a derived index.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Junghan Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.