@junghanacs/entwurf 0.12.0

package/scripts/meta-bridge-statusline.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# meta-bridge-statusline — Claude Code native statusline with garden identity.
+#
+# Repo-owned Phase-3 statusline. It preserves GLG's current UX data
+# (device, cwd[branch], model, context usage) while rendering it as a two-row
+# Claude Code status area: row 1 = work context, row 2 = garden identity. The
+# garden id is looked up by scanning meta-record BODIES via the native Claude
+# `session_id`. No cache, no filename authority, no DB.
+#
+# Runtime dependency: python3 (already gated by install-meta-bridge/doctor).
+set -euo pipefail
+
+input=$(cat)
+# The statusline must NEVER error out — Claude renders it every turn, so a broken
+# exit would put a broken line in front of GLG on every prompt. If python3 is gone
+# (e.g. a nix GC between installs) degrade to a quiet minimal line; if the parser
+# itself dies, `|| true` keeps the shell alive with whatever (possibly empty) it
+# wrote. doctor/smoke are the fail-LOUD surfaces; this surface stays silent.
+if ! command -v python3 >/dev/null 2>&1; then
+  device="$(cat "$HOME/.current-device" 2>/dev/null || echo UNKNOWN)"
+  printf '%s ?\n🪛 ? cc' "$device"
+  exit 0
+fi
+STATUSLINE_INPUT="$input" python3 - <<'PY' || true
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+RESET = "\033[0m"
+DIM = "\033[2m"
+CYAN_BOLD = "\033[1;36m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+RED_BOLD = "\033[31;1m"
+
+
+def load_input() -> dict[str, Any]:
+    raw = os.environ.get("STATUSLINE_INPUT", "")
+    try:
+        data = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def dig(obj: Any, *keys: str) -> Any:
+    cur = obj
+    for key in keys:
+        if not isinstance(cur, dict):
+            return None
+        cur = cur.get(key)
+    return cur
+
+
+def device_label() -> str:
+    try:
+        text = Path.home().joinpath(".current-device").read_text(encoding="utf-8").strip()
+        return text or "UNKNOWN"
+    except Exception:
+        return "UNKNOWN"
+
+
+def shorten_home(path_text: str) -> str:
+    home = str(Path.home())
+    if path_text == home:
+        return "~"
+    if path_text.startswith(home + os.sep):
+        return "~" + path_text[len(home) :]
+    return path_text
+
+
+def split_cwd(cwd: str) -> tuple[str, str]:
+    if "/" in cwd:
+        return cwd.rsplit("/", 1)[0] + "/", cwd.rsplit("/", 1)[1]
+    return "", cwd
+
+
+def model_short(model_id: str) -> str:
+    low = model_id.lower()
+    if "opus" in low:
+        return "o"
+    if "sonnet" in low:
+        return "s"
+    if "haiku" in low:
+        return "h"
+    return "?"
+
+
+def git_branch(cwd: str) -> str:
+    real_cwd = os.path.abspath(os.path.expanduser(cwd)) if cwd else os.getcwd()
+    try:
+        subprocess.run(["git", "rev-parse", "--git-dir"], cwd=real_cwd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
+        result = subprocess.run(["git", "branch", "--show-current"], cwd=real_cwd, text=True, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, check=False)
+        branch = result.stdout.strip()
+        return f" [{branch}]" if branch else ""
+    except Exception:
+        return ""
+
+
+def human_tokens(n: int) -> str:
+    return f"{n / 1000:.1f}K" if n >= 1000 else str(n)
+
+
+def limit_label(n: int) -> str:
+    return f"{n / 1000000:.0f}M" if n >= 1000000 else f"{n / 1000:.0f}K"
+
+
+def context_info(data: dict[str, Any]) -> str:
+    ctx = data.get("context_window")
+    if not isinstance(ctx, dict):
+        return ""
+    try:
+        limit = int(ctx.get("context_window_size") or 0)
+        pct = int(float(ctx.get("used_percentage") or 0))
+        usage = ctx.get("current_usage") if isinstance(ctx.get("current_usage"), dict) else {}
+        current = int(usage.get("input_tokens") or 0) + int(usage.get("output_tokens") or 0) + int(usage.get("cache_creation_input_tokens") or 0) + int(usage.get("cache_read_input_tokens") or 0)
+    except Exception:
+        return ""
+    if limit <= 0:
+        return ""
+    color = RED_BOLD if pct >= 85 else YELLOW if pct >= 70 else GREEN
+    return f" | {color}{human_tokens(current)}/{limit_label(limit)} {pct}%{RESET}{DIM}"
+
+
+def meta_sessions_dir() -> Path:
+    override = os.environ.get("ENTWURF_META_SESSIONS_DIR")
+    if override:
+        return Path(override).expanduser().resolve()
+    agent = os.environ.get("PI_CODING_AGENT_DIR")
+    if agent:
+        return Path(agent).expanduser().resolve() / "meta-sessions"
+    return Path.home() / ".pi" / "agent" / "meta-sessions"
+
+
+def garden_lookup(native_session_id: str) -> str:
+    if not native_session_id:
+        return "ready"
+    root = meta_sessions_dir()
+    if not root.exists():
+        return "?"
+    matches: list[str] = []
+    try:
+        entries = sorted(root.glob("*.meta.json"))
+    except Exception:
+        return "?"
+    for file in entries:
+        try:
+            record = json.loads(file.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        if isinstance(record, dict) and record.get("nativeSessionId") == native_session_id:
+            garden = record.get("gardenId")
+            if isinstance(garden, str) and garden:
+                matches.append(garden)
+            else:
+                matches.append("!")
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        return "!"
+    return "?"
+
+
+def main() -> None:
+    data = load_input()
+    raw_cwd = dig(data, "workspace", "current_dir") or data.get("cwd") or "?"
+    cwd = shorten_home(str(raw_cwd))
+    cwd_dir, cwd_tail = split_cwd(cwd)
+
+    model_id = dig(data, "model", "id") or "?"
+    model = model_short(str(model_id))
+    vterm = "v" if os.environ.get("INSIDE_EMACS") == "vterm" else ""
+
+    native_session_id = data.get("session_id")
+    garden = garden_lookup(native_session_id if isinstance(native_session_id, str) else "")
+    line1 = (
+        f"{DIM}{device_label()} {cwd_dir}{RESET}"
+        f"{CYAN_BOLD}{cwd_tail}{RESET}"
+        f"{DIM}{git_branch(str(raw_cwd))}{RESET}"
+    )
+    line2 = f"{DIM}🪛 {garden} cc | {model}{vterm}{context_info(data)}{RESET}"
+    sys.stdout.write(f"{line1}\n{line2}")
+
+
+if __name__ == "__main__":
+    main()
+PY

package/scripts/meta-bridge-store-doctor.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * meta-bridge-store-doctor — fail-loud full scan for meta-session records.
+ *
+ * The store is the authority for native→garden lookup. Doctor must therefore
+ * refuse corrupt records, duplicate nativeSessionId authorities, and body ↔
+ * filename drift instead of auto-pruning or silently picking one.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseMetaIdentity } from "../pi-extensions/lib/meta-session.ts";
+
+const dir = process.argv[2];
+if (!dir) {
+	console.error("usage: node --experimental-strip-types scripts/meta-bridge-store-doctor.ts <meta-sessions-dir>");
+	process.exit(2);
+}
+
+const failures: string[] = [];
+const nativeToFiles = new Map<string, string[]>();
+let scanned = 0;
+
+if (!fs.existsSync(dir)) {
+	console.log(`meta-store scan ok: ${dir} does not exist yet (0 records)`);
+	process.exit(0);
+}
+
+for (const filename of fs.readdirSync(dir).sort()) {
+	if (!filename.endsWith(".meta.json")) continue;
+	scanned += 1;
+	const file = path.join(dir, filename);
+	try {
+		// dual-read (3D-4 commit1): parseMetaIdentity reads v1 AND v2 and normalizes,
+		// so doctor's gardenId/nativeSessionId checks survive the v2 cut.
+		const id = parseMetaIdentity(fs.readFileSync(file, "utf8"));
+		const expectedFilename = `${id.gardenId}.meta.json`;
+		if (filename !== expectedFilename) {
+			failures.push(
+				`${filename}: body/filename drift — body gardenId=${id.gardenId}, expected filename ${expectedFilename}`,
+			);
+		}
+		const files = nativeToFiles.get(id.nativeSessionId) ?? [];
+		files.push(filename);
+		nativeToFiles.set(id.nativeSessionId, files);
+	} catch (err) {
+		failures.push(`${filename}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+
+for (const [nativeSessionId, files] of nativeToFiles.entries()) {
+	if (files.length > 1) {
+		failures.push(
+			`duplicate nativeSessionId ${JSON.stringify(nativeSessionId)} in ${files.join(", ")} — authority ambiguity; prune manually`,
+		);
+	}
+}
+
+if (failures.length > 0) {
+	for (const failure of failures) console.error(`FAIL: ${failure}`);
+	process.exit(1);
+}
+
+console.log(`meta-store scan ok: ${scanned} record(s) scanned, no corrupt/duplicate/drift records`);

package/scripts/meta-bridge-uninstall.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# meta-bridge-uninstall.sh — honest inverse of install-meta-bridge.
+#
+# Uses ${CLAUDE_CONFIG_DIR:-~/.claude}/entwurf.install-state.json to restore
+# exactly the settings/MCP keys Phase 2 install touched. Without that state file,
+# uninstall cannot know whether a scalar false/true/path was user-owned, so it
+# fails instead of guessing.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(cd "$HERE/.." && pwd)"
+MKT_NAME="meta-bridge-local"
+PLUGIN="entwurf-meta-receive"
+
+die() { echo "meta-bridge-uninstall: $*" >&2; exit 1; }
+
+case "$(uname -s)" in
+  Linux | Darwin) ;;
+  *) die "unsupported platform '$(uname -s)'. meta-bridge supports Linux + macOS only (Windows is fail-fast, not silently attempted)." ;;
+esac
+
+command -v python3 >/dev/null || die "'python3' not on PATH. It is required for stateful uninstall."
+
+# Refuse to touch Claude's plugin/MCP registrations until state exists and is
+# valid. Without this preflight, "uninstall without state fails" would still
+# delete live plugin/MCP entries before failing — guessing by side effect.
+python3 "$REPO/scripts/meta-bridge-state.py" preflight-uninstall --repo "$REPO"
+
+if command -v claude >/dev/null; then
+  claude plugin uninstall "$PLUGIN@$MKT_NAME" >/dev/null 2>&1 || true
+  claude plugin marketplace remove "$MKT_NAME" >/dev/null 2>&1 || true
+  claude mcp remove entwurf-bridge -s user >/dev/null 2>&1 || true
+  echo "[meta-bridge-uninstall] removed Claude plugin/marketplace/MCP registrations when present"
+else
+  echo "[meta-bridge-uninstall] WARN: claude CLI not on PATH; restoring JSON state only" >&2
+fi
+
+python3 "$REPO/scripts/meta-bridge-state.py" uninstall --repo "$REPO"
+echo "[meta-bridge-uninstall] DONE"

package/scripts/new-session-id.ts

@@ -0,0 +1,25 @@
+/**
+ * new-session-id — print one fresh garden-native sessionId and exit.
+ *
+ * The garden launcher (operator alias / wrapper) calls this so every
+ * `--entwurf-control` session is born a garden citizen:
+ *
+ *   pi --session-id "$(./run.sh new-session-id)" --entwurf-control \
+ *      --emacs-agent-socket server …
+ *
+ * The id is `generateSessionId()` from entwurf-core — the single SSOT for the
+ * locked `YYYYMMDDTHHMMSS-[0-9a-f]{6}` grammar. Do NOT reimplement the format in
+ * the shell (it would drift from the validator the resident guard enforces).
+ *
+ * Stdout is the id and nothing else (no trailing prose), so `$(…)` captures a
+ * clean value. Errors go to stderr with a nonzero exit.
+ */
+
+import { generateSessionId } from "../pi-extensions/lib/entwurf-core.ts";
+
+try {
+	process.stdout.write(`${generateSessionId()}\n`);
+} catch (err) {
+	process.stderr.write(`new-session-id failed: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+}

package/scripts/postinstall-chmod.cjs

@@ -0,0 +1,58 @@
+// Restore executable bits on shell scripts after install.
+//
+// Why: `pnpm publish` normalizes file modes in the published tarball
+// to 0644, so the registry artifact loses the executable bit that the
+// repo tracks (`git ls-files --stage` shows 100755). README documents
+// running `run.sh install .` directly, and the entwurf-bridge MCP
+// extension spawns `mcp/entwurf-bridge/start.sh` — both break with
+// EACCES on a fresh `pi install npm:@junghanacs/entwurf`.
+//
+// CJS so it runs regardless of the consumer's package "type" and
+// regardless of whether the installed copy includes our package.json
+// (the script is co-located, no resolution needed).
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const root = path.resolve(__dirname, "..");
+
+const targets = [
+	"run.sh",
+	"mcp/entwurf-bridge/start.sh",
+	"mcp/entwurf-bridge/test.sh",
+	"demo/demo.sh",
+	"demo/demo-baseline.sh",
+];
+
+const scriptDirs = ["scripts"];
+
+function chmodIfPresent(rel) {
+	const abs = path.join(root, rel);
+	try {
+		if (!fs.existsSync(abs)) return;
+		fs.chmodSync(abs, 0o755);
+	} catch (err) {
+		// Never fail install on chmod errors (Windows, read-only mount, etc.).
+		console.warn(`[entwurf postinstall] chmod ${rel} skipped: ${err.message}`);
+	}
+}
+
+for (const rel of targets) {
+	chmodIfPresent(rel);
+}
+
+for (const dir of scriptDirs) {
+	const abs = path.join(root, dir);
+	try {
+		if (!fs.existsSync(abs)) continue;
+		for (const entry of fs.readdirSync(abs)) {
+			if (entry.endsWith(".sh")) {
+				chmodIfPresent(path.join(dir, entry));
+			}
+		}
+	} catch (err) {
+		console.warn(`[entwurf postinstall] scan ${dir}/*.sh skipped: ${err.message}`);
+	}
+}

package/scripts/raw-async-delivery/README.md

@@ -0,0 +1,258 @@
+# raw-async-delivery — RAW async message delivery into LIVE Claude Code / agy / Codex sessions
+
+Goal: deliver an async message INTO an already-running **subscription** session,
+free, with no `claude -p` / backend CLI prompt spawn — and in particular wake an
+**IDLE** session with zero typing (agy `send-message` parity).
+
+Codex is split by launch surface:
+
+- standalone **Embedded** Codex TUI: no external socket; not addressable, not
+  retrofittable.
+- **app-server-backed** Codex TUI (`codex --remote unix://` or plain `codex`
+  auto-attached to a default-path app-server): raw `turn/start` over
+  WebSocket-over-UDS wakes the live thread — **demonstrated, no managed
+  standalone, no cloud**.
+
+## TL;DR — three reception paths, ranked
+
+| Path | Self-arms idle watch? | Portable / drop-in | Verdict |
+|------|----------------------|--------------------|---------|
+| **Plugin** (`.claude-plugin` + `hooks/hooks.json`) | ✅ yes | ✅ yes (`--plugin-dir` / install) | **best** — scoped AND works |
+| Global/project `settings.json` hooks | ✅ yes | ⚠️ config edit, not a unit | works; less portable |
+| **Bare skill** (`~/.claude/skills/x/` with `hooks:`) | ❌ **no** | ✅ yes | **structurally unfit for the watch** |
+
+### Why a bare skill cannot arm the idle watch (mechanism, verified)
+
+A bare skill's hooks register only when the model **invokes** the skill
+(`getPromptForCommand` → `mL4(setAppState, …, H.hooks, …)`, 2.1.163). That is
+mid-session — **after** `SessionStart` already fired. A `watchPath` can only be
+emitted from `SessionStart` / `CwdChanged` / `FileChanged` hookSpecificOutput, so
+a skill-declared `SessionStart` hook never runs and the watch is never armed.
+The model may *read* `SKILL.md` and role-play "watching", but no hook is armed —
+a dangerous false-positive for a delivery daemon. Measured: `hook.log` stays
+empty; `loadSkillsAsPlugins` only loads dirs that contain `.claude-plugin`.
+
+> The earlier conclusion "scoped delivery is impossible → use global settings"
+> was only half right. It is true for a **bare skill**. It is **false** for a
+> **plugin**, which is just as portable/drop-in and whose hooks load at startup.
+
+### Why a plugin works
+
+`hooks/hooks.json` inside a plugin is loaded at **startup** (not on invocation),
+so its `SessionStart` hook actually fires and arms the `watchPath`. From there
+`FileChanged(asyncRewake)` wakes the idle session on an external file write.
+Verified live on 2.1.163 / Opus 4.8: idle session, zero typing, ~1–2 s, same
+session + same model.
+
+## Addressed, not broadcast
+
+Delivery is **per-session addressed**: each receiving session arms a watchPath at
+`<root>/<session_id>/inbox.signal` (session_id arrives on the SessionStart hook
+stdin). A sender targets ONE `session_id`; only that session's signal changes, so
+**only that session wakes** — siblings stay idle and undisturbed. This is the
+entwurf sessionId-addressing model: "send to the one you want, only it processes."
+
+```
+$CC_MAILBOX_ROOT/<session_id>/inbox.signal     # watched (poked by the sender)
+$CC_MAILBOX_ROOT/<session_id>/<ts>.msg          # message body (agent self-fetches)
+$CC_MAILBOX_ROOT/<session_id>/hook.log          # per-session hook evidence
+```
+
+`CC_MAILBOX_ROOT` defaults to `~/.claude/mailbox`. Sender and receiver must agree
+on the root. A fixed shared signal would broadcast and bother every session — we
+do not ship that. Proven: deliver to A's sessionId → A wakes (FileChanged), B's
+`hook.log` shows zero FileChanged, B pane unchanged (`repro-addressed-routing.sh`).
+
+## Files
+
+### Plugin (recommended reception unit)
+- `plugin-entwurf-receive/.claude-plugin/plugin.json` — manifest
+- `plugin-entwurf-receive/hooks/hooks.json` — SessionStart(watch) + FileChanged(asyncRewake)
+- `plugin-entwurf-receive/scripts/watch-sessionstart.sh` — arms the **per-session** watchPath (reads session_id from stdin)
+- `plugin-entwurf-receive/scripts/watch-filechanged.sh` — doorbell on external write; mailbox = `dirname(file_path)`, so it reads only its own session
+
+### settings.json reception (alternative; global = every session arms its own watch)
+- `cc-watch-sessionstart.sh` — SessionStart: register per-session watchPath
+- `cc-watch-filechanged.sh` — FileChanged(asyncRewake): active idle-wake doorbell
+- `cc-mailbox-rewake.sh` — Stop(asyncRewake): passive piggyback (next turn boundary), keyed by session_id
+
+### Delivery (sender side, all free file writes, all addressed by sessionId)
+- `cc-enqueue-addressed.sh <session_id> …` — ACTIVE: write `.msg` + poke that session's signal → wakes it from idle
+- `raw-claude-enqueue.sh <session_id> …` — PIGGYBACK: write `.msg` only → delivered at the session's next turn boundary
+- `raw-agy-send.sh <conv_id> …` — agy parity: PUSH into a live Antigravity session (LS gRPC)
+- `raw-codex-ws-turn-start.py <sock> <thread_id> …` — Codex parity (no managed standalone, no cloud): PUSH `turn/start` over WebSocket-over-UDS into a bare `app-server --listen` socket
+- `codex-local-appserver.sh [sock]` — start a bare local app-server so plain `codex` auto-attaches and becomes addressable
+
+### Reproduction drivers
+- `repro-plugin-idle-wake.sh` — single-session smoke.
+  - `probe` — deterministic (no tmux): plugin SessionStart hook fires at startup + arms per-session watch.
+  - `live` — one session idle → addressed external write wakes it, zero typing.
+- `repro-addressed-routing.sh` — **two sessions** A,B → deliver to A only → assert A wakes, B undisturbed.
+
+## Quick start (plugin reception)
+
+```bash
+# 1. open a live receiving session with the plugin loaded
+export CC_MAILBOX_ROOT=/tmp/cc-mbx
+claude --plugin-dir ./plugin-entwurf-receive --dangerously-skip-permissions
+#   (SessionStart hook arms <root>/<session_id>/inbox.signal automatically)
+
+# 2. find the target session's id
+cat ~/.claude/sessions/*.json   # pick the sessionId you want (match by cwd/pid)
+
+# 3. from anywhere else, deliver async to THAT session only (no typing):
+CC_MAILBOX_ROOT=/tmp/cc-mbx ./cc-enqueue-addressed.sh <session_id> "your async message"
+#   -> only that session's FileChanged fires -> asyncRewake doorbell
+#   -> that idle session wakes, self-fetches body; siblings stay idle
+```
+
+## Design notes / invariants
+
+- **Doorbell only.** `asyncRewake` payload rides **stderr** (stdout is ignored).
+  Announce "you have mail" + the body path; never push imperatives — strong
+  models flag hook-injected commands as prompt injection. The agent self-fetches.
+- **Body path in the doorbell.** The hook `mv`s `*.msg` → `*.msg.delivered`
+  before announcing and reports the `.delivered` path, so the agent reads it in
+  one step (measured: removes a filesystem-hunt round-trip).
+- **Free.** Both active and piggyback are file writes + continuation of an
+  already-running subscription session. No `claude -p` spawn for the wake.
+  (`claude -p` spawn is the metered axis from 2026-06-15; delivery is not.)
+- **Same session / same model.** The wake is an in-process continuation; the
+  reply comes from the bound main model (verified `claude-opus-4-8`).
+- **Version-pinned.** Behavior measured on Claude Code **2.1.163**. Re-verify on
+  upgrade (claude ships ~weekly; undocumented fields drift).
+
+## Gotchas — hard-won, do NOT re-debug (삽질 방지)
+
+Each line below cost real debugging time. If you change this code or port it,
+re-read these first. Two of them were flat-out wrong "impossible" conclusions
+that a second pass reversed.
+
+1. **Stop hook CANNOT wake an IDLE session.** `asyncRewake` on `Stop` fires at a
+   *turn boundary*. An idle session has already passed its last `Stop`, so it
+   never re-fires on its own — Stop only delivers *piggyback* at the session's
+   NEXT turn. The idle active-wake path is **`FileChanged` + `watchPaths`**, not
+   `Stop`. (Wrong conclusion #1 was "Claude can't idle-wake" — it was an *event
+   selection* error, not a capability limit.)
+2. **A bare skill cannot arm the watch; a plugin can.** Bare-skill hooks register
+   at skill *invocation* (mid-session, after `SessionStart`); plugin
+   `hooks/hooks.json` loads at *startup*. (Wrong conclusion #2 was "scoped is
+   impossible → global settings only". See top of this file.)
+3. **`asyncRewake` payload channel is `stderr` ONLY.** Anything on `stdout` is
+   dropped and the model sees "No stderr output". The body must go to stderr.
+4. **`asyncRewake` force-prepends `Stop hook feedback:\n[<script>]:`** and
+   **ignores any configured `rewakeMessage`**. You cannot control the exact
+   injected string — so use it as a *doorbell* (notify only) and let the agent
+   self-fetch the body. Do not depend on injecting the literal message.
+5. **Infinite-loop guard is mandatory.** Honor `stop_hook_active` (if `true`,
+   `exit 0` — already continuing, let it stop) or you get a wake loop. The engine
+   also caps re-wakes via `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`.
+6. **`watchPaths` can be emitted from only 3 events:** `SessionStart`,
+   `CwdChanged`, `FileChanged` (hookSpecificOutput). FileChanged/CwdChanged can
+   *dynamically extend* the watch list mid-session; everything else cannot arm a
+   watch. This is the whole reason the SessionStart-timing problem matters.
+7. **Imperatives in an injected message get flagged as prompt injection** by
+   strong models (Opus refused). Doorbell = notification framing only.
+8. **Liveness SSOT is `~/.claude/sessions/<pid>.json`, NOT db-shm/db-wal.** WAL
+   files vanish on SQLite checkpoint while the session is still live, and
+   reappear on activity — a false "dead/alive" signal. See section below.
+9. **Cost line: only `claude -p` *spawn* is metered (from 2026-06-15).** The
+   wake/delivery is a continuation of an already-running subscription session and
+   is free. Don't conflate "launch a new session" with "deliver to a live one".
+10. **Test-harness quirk:** the Claude TUI sometimes needs a second `Enter` to
+    submit a `tmux send-keys` prompt (the first keystroke only fills the input
+    box). The repro drivers send `Enter` twice on purpose — not a bug.
+
+## Codex raw delivery status (0.136.0)
+
+Measured against `@openai/codex` 0.136.0 (source: `~/repos/3rd/codex`). **Codex IS
+breakable for local raw idle-wake — without managed standalone and without cloud.**
+Split by launch mode, not by "Codex".
+
+### Embedded standalone TUI: negative (and not retrofittable)
+
+A plain `codex` TUI launched standalone runs an **Embedded** in-process app-server
+and binds **no external socket** (verified: the live PID has no listening socket;
+its ~2400 inotify watches are project file-tracking for `fs_watch`/`skills_watcher`,
+not a wake trigger). Codex hooks (`SessionStart`, `UserPromptSubmit`, `Pre/PostToolUse`,
+`Pre/PostCompact`, `SubagentStart/Stop`, `Stop`) have **no `FileChanged`/`watchPaths`/
+`asyncRewake`**, so there is no Claude-style filesystem wake either. The
+Embedded/daemon decision is made once at launch (`run_main`), so an already-running
+standalone TUI **cannot be retrofitted**. Identify it via `CODEX_THREAD_ID` /
+`~/.codex/state_5.sqlite` / rollout JSONL, but do not write those as a wake path.
+
+### Local app-server-backed TUI: POSITIVE — D6/D7, DEMONSTRATED
+
+A TUI that is backed by a local app-server control socket **is** addressable. Two
+launch shapes both reach it, neither needs the managed standalone or the cloud:
+
+- `codex --remote unix://PATH` — explicit attach to an app-server on `PATH`.
+- plain `codex` (no `-c` overrides) — auto-attaches to an app-server already
+  listening on the **default** control socket path (`maybe_probe_default_daemon_socket`).
+
+Make sessions addressable (see `codex-local-appserver.sh`):
+
+```bash
+# bare app-server on the default control socket — NO managed standalone, NO cloud
+codex app-server --listen unix://$HOME/.codex/app-server-control/app-server-control.sock &
+codex            # plain launch auto-attaches; its thread is now reachable
+```
+
+Deliver (WebSocket-over-UDS `turn/start`, no auth — the 0700 socket dir is the boundary):
+
+```bash
+# threadId = newest rollout's session_meta id
+tid=$(head -1 "$(ls -t ~/.codex/sessions/**/rollout-*.jsonl | head -1)" \
+      | python3 -c 'import json,sys;print(json.load(sys.stdin)["payload"]["id"])')
+./raw-codex-ws-turn-start.py "$HOME/.codex/app-server-control/app-server-control.sock" \
+    "$tid" "your async message"
+```
+
+Measured (0.136.0, 2026-06-05): idle plain `codex` (auto-attached) woke with **zero
+typing**, the message body was injected, the model replied. `thread/status/changed`
+(`active`→`idle`) notifications give completion observation (D7) on the same socket.
+This is **stronger than Claude Code** — full message injection (like agy), not a
+doorbell + self-fetch.
+
+### Out of scope: the managed-daemon / cloud path
+
+This repo ships only the **bare local** path (`codex app-server --listen` +
+`raw-codex-ws-turn-start.py`). There is a second Codex surface we deliberately do
+**not** use: the managed **daemon** control socket driven via `codex app-server
+proxy` (newline JSON-RPC). It needs the managed standalone install
+(`~/.codex/packages/standalone/current/codex`), and `codex remote-control start`
+additionally enables the **cloud** bridge (ChatGPT app access). For a purely-local,
+no-cloud setup the bare `--listen` socket above is sufficient, so no managed-daemon
+sender is shipped here.
+
+Method notes: `turn/steer` is active-turn steering (needs `expectedTurnId`), not idle
+wake; `thread/inject_items` appends history without starting a turn; `debug app-server
+send-message-v2` spins a fresh thread, not the live one.
+
+### Gotchas (Codex)
+
+1. **Socket dir mode 0700, owner-owned.** `prepare_private_socket_directory()` chmods
+   the socket's parent dir to exactly 0700. Pointing `--listen` at a dir you don't own
+   (e.g. `/tmp` directly, mode 1777) fails with **EPERM** — that is the chmod, not a
+   capability limit. `~/.codex/app-server-control/` (Codex creates it 0700) is fine.
+2. **`-c` overrides disable auto-attach.** `can_reuse_implicit_local_daemon` requires
+   no `-c`, default loader, no `--strict-config`, no bypass-hook-trust. Launch plain
+   `codex` for auto-attach, else use explicit `--remote`.
+3. **Per-folder trust** (`config.toml [projects."<path>"]`) governs whether a thread
+   loads project-local config/hooks/exec-policy — NOT whether it is addressable.
+   Addressability is the app-server socket; trust is orthogonal.
+4. **Unix-socket transport is WebSocket** (tokio-tungstenite), not newline JSON-RPC,
+   and requires **no auth token** on the UDS. A plain WS client suffices.
+
+## Live SSOT for "is the target session alive?"
+
+- Claude Code: `~/.claude/sessions/<pid>.json` (pid, sessionId, cwd, status). NOT
+  db-shm/db-wal — those vanish on WAL checkpoint while the session is still live.
+- agy: `pgrep -x agy` + an LS socket that answers `get-conversation-metadata`.
+- Codex embedded TUI: `CODEX_THREAD_ID` + `~/.codex/state_5.sqlite` +
+  `~/.codex/sessions/**/rollout-*.jsonl` identify the live thread/transcript,
+  but a standalone Embedded TUI exposes no delivery socket.
+- Codex app-server-backed: an app-server listening on
+  `$HOME/.codex/app-server-control/app-server-control.sock` (or any owned 0700
+  socket via `codex app-server --listen unix://PATH`) is the delivery surface.
+  threadId comes from the newest rollout's `session_meta.id`.

package/scripts/raw-async-delivery/cc-enqueue-addressed.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# cc-enqueue-addressed.sh — ADDRESSED async delivery to ONE live Claude Code
+# session, by sessionId. Only that session's per-session watchPath matches, so
+# ONLY that session wakes and processes — siblings stay idle and undisturbed.
+#
+# COST: free (file writes + the target's own subscription-session continuation).
+# LIVE SSOT: ~/.claude/sessions/<pid>.json whose sessionId == <session_id>.
+# PAIRS WITH: watch-sessionstart.sh (per-session watchPath) + watch-filechanged.sh.
+# USAGE: [CC_MAILBOX_ROOT=<root>] cc-enqueue-addressed.sh <session_id> <message...>
+set -euo pipefail
+SID="${1:?session_id (target one specific live session)}"; shift
+CONTENT="${*:?message}"
+ROOT="${CC_MAILBOX_ROOT:-$HOME/.claude/mailbox}"
+
+# Verify the target is a live interactive session and surface its identity.
+LIVE=$(python3 - "$SID" <<'PY'
+import json, glob, os, sys
+sid = sys.argv[1]
+for f in glob.glob(os.path.expanduser("~/.claude/sessions/*.json")):
+    try:
+        d = json.load(open(f))
+    except Exception:
+        continue
+    if d.get("sessionId") == sid:
+        print(f"pid={d['pid']} status={d.get('status')} cwd={d.get('cwd')}")
+        break
+PY
+)
+[ -n "$LIVE" ] || { echo "session $SID not live (no marker in ~/.claude/sessions/)" >&2; exit 1; }
+
+DIR="$ROOT/$SID"; mkdir -p "$DIR"
+TS=$(date -u +%Y%m%dT%H%M%S%N)
+printf '%s\n' "$CONTENT" > "$DIR/$TS.msg"
+printf 'ping %s\n' "$(date -u +%s%N)" >> "$DIR/inbox.signal"   # poke ONLY this session's signal
+echo "delivered -> $SID ($LIVE) :: $DIR/$TS.msg"