@junghanacs/entwurf 0.12.0

package/pi-extensions/meta-bridge-hook.ts

@@ -0,0 +1,250 @@
+/**
+ * meta-bridge-hook — the Claude Code native-session entry shell (1.0.0 step 4).
+ *
+ * THE load-bearing hook. Shipped inside a plugin bundle whose `hooks/hooks.json`
+ * wires it to `SessionStart` (and `CwdChanged` / `UserPromptSubmit`). Because a
+ * plugin's hooks load at STARTUP (a bare skill's load only on invocation, after
+ * SessionStart has passed), this fires on every native Claude Code open and makes
+ * that session a garden citizen WITHOUT any pi JSONL of its own:
+ *
+ *   stdin {session_id, transcript_path, cwd}  (Claude hook envelope)
+ *     -> upsertMetaSession(claude-code)        idempotent create/attach the record
+ *        -> gardenId                           the session's garden address
+ *     -> arm watchPath <mailbox>/<gardenId>/inbox.signal   idle-wake doorbell
+ *     -> stdout hookSpecificOutput.watchPaths  (SessionStart / CwdChanged only)
+ *
+ * The record is keyed/looked-up by `native_session_id` (THE authority,
+ * scanByNativeId); the idle-wake mailbox is keyed by GARDEN id — that is the
+ * whole point of the meta-bridge over the raw per-session prototype: one garden
+ * address a sender can target, decoupled from the backend's native id grammar.
+ *
+ * FAILURE POLICY (decided, see NEXT.md step 4): the runtime hook is
+ * BEST-EFFORT + LOG. It never screams into the user's terminal and never blocks
+ * startup — on any error it appends a line to `<pi-agent-dir>/meta-bridge-hook.log`
+ * and emits an empty `{}` (no arm). The fail-LOUD surface is the doctor
+ * (step 5), which reads that log + the meta-record dir to catch a silent miss.
+ *
+ * watchPaths can be emitted only from SessionStart / CwdChanged / FileChanged, so
+ * a UserPromptSubmit fire does a degraded RECORD backfill (upsert) but cannot
+ * re-arm the idle watch — the record's address is restored, the wake is not.
+ *
+ * Run: `<node> --experimental-strip-types <plugin-root>/meta-bridge-hook.ts`.
+ * Imports `./lib/meta-session.ts` (+ `./lib/session-id.js`); the installer copies
+ * that lib dir alongside this file so `${CLAUDE_PLUGIN_ROOT}` self-locates it.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+	defaultMetaMailboxDir,
+	defaultMetaSessionsDir,
+	type MetaReceiverArmProvenance,
+	upsertMetaSession,
+	writeMetaReceiverMarker,
+	writeMetaSenderMarker,
+} from "./lib/meta-session.ts";
+
+/**
+ * Append a best-effort diagnostic line; swallow even its own failure (never throw
+ * from the hook). Every line carries a LEVEL token so the doctor — the fail-loud
+ * surface — can mechanically tell a silent miss from routine noise:
+ *   - ERROR: this session did NOT become a garden citizen (or lost its wake).
+ *            The doctor must treat a recent ERROR as a failure (blocker #2).
+ *   - WARN : the session registered, but something nearby is off (a corrupt
+ *            neighbour record skipped during scan, or a degraded UserPromptSubmit
+ *            backfill — note a degraded SessionStart/CwdChanged is ERROR, since
+ *            those are the events that actually establish/refresh citizenship).
+ *   - INFO : normal create/attach/arm.
+ * The token sits right after the ISO timestamp, so ` ERROR ` is a clean grep.
+ */
+type LogLevel = "INFO" | "WARN" | "ERROR";
+function logLine(level: LogLevel, message: string): void {
+	try {
+		// dirname(meta-sessions) == the pi agent dir — no extra resolver export needed.
+		const file = path.join(path.dirname(defaultMetaSessionsDir()), "meta-bridge-hook.log");
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		fs.appendFileSync(file, `${new Date().toISOString()} ${level} ${message}\n`);
+	} catch {
+		/* logging is best-effort; a broken log must not break the session */
+	}
+}
+
+/** Emit a hook response on stdout and exit 0. `{}` means "did nothing, do not block startup". */
+function emit(payload: Record<string, unknown>): never {
+	process.stdout.write(`${JSON.stringify(payload)}\n`);
+	process.exit(0);
+}
+
+/**
+ * Map the hook event to a receiver-marker arm provenance. ONLY the genuinely
+ * arm-capable events map; any other (a future/unknown hook event) returns null so we
+ * never mint an "active receiver" presence we cannot back — fail-closed, not an
+ * optimistic session-start. UserPromptSubmit never reaches here (it early-returns
+ * before the arm block).
+ */
+function armProvenanceFor(eventName: string): MetaReceiverArmProvenance | null {
+	if (eventName === "SessionStart") return "session-start";
+	if (eventName === "CwdChanged") return "cwd-changed";
+	if (eventName === "FileChanged") return "file-changed";
+	return null;
+}
+
+function main(): void {
+	let raw: string;
+	try {
+		raw = fs.readFileSync(0, "utf8"); // fd 0 = stdin (the Claude hook envelope)
+	} catch (err) {
+		logLine("ERROR", `stdin read failed: ${err instanceof Error ? err.message : String(err)}`);
+		emit({});
+	}
+
+	let env: Record<string, unknown>;
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) throw new Error("envelope is not an object");
+		env = parsed as Record<string, unknown>;
+	} catch (err) {
+		logLine("ERROR", `envelope parse failed: ${err instanceof Error ? err.message : String(err)}`);
+		emit({});
+	}
+
+	const sessionId = typeof env.session_id === "string" ? env.session_id : "";
+	const transcriptPath = typeof env.transcript_path === "string" ? env.transcript_path : "";
+	// cwd: prefer the envelope's, fall back to the process cwd (the hook runs in the session's cwd).
+	const cwd = typeof env.cwd === "string" && env.cwd.length > 0 ? env.cwd : process.cwd();
+	const modelEnvelope = env.model;
+	const model =
+		typeof modelEnvelope === "object" &&
+		modelEnvelope !== null &&
+		typeof (modelEnvelope as { id?: unknown }).id === "string"
+			? (modelEnvelope as { id: string }).id
+			: typeof env.model_id === "string"
+				? env.model_id
+				: undefined;
+	const eventName = typeof env.hook_event_name === "string" ? env.hook_event_name : "SessionStart";
+
+	if (!sessionId || !transcriptPath) {
+		// A degraded envelope: cannot mint an honest reference record. Log + no-op
+		// rather than write a half-record or guess a transcript path. LEVEL depends
+		// on the event: a degraded SessionStart / CwdChanged means the session FAILED
+		// to become (or refresh) a garden citizen — that is the silent registration
+		// miss the doctor must catch (blocker #2), so ERROR. UserPromptSubmit only
+		// ever does a best-effort record backfill, so a degraded one is just WARN.
+		const degradedLevel = eventName === "UserPromptSubmit" ? "WARN" : "ERROR";
+		logLine(
+			degradedLevel,
+			`degraded envelope (event=${eventName}, session_id=${sessionId ? "set" : "MISSING"}, transcript_path=${transcriptPath ? "set" : "MISSING"})`,
+		);
+		emit({});
+	}
+
+	let gardenId: string;
+	try {
+		const result = upsertMetaSession({
+			input: { backend: "claude-code", nativeSessionId: sessionId, transcriptPath, cwd, model },
+			onSkip: (filename, e) => logLine("WARN", `scan skipped ${filename}: ${e.message}`),
+		});
+		gardenId = result.record.gardenId;
+		logLine("INFO", `${result.action} record ${path.basename(result.path)} (event=${eventName}, native=${sessionId})`);
+	} catch (err) {
+		// Best-effort: a broken record store must surface via the doctor, not by
+		// breaking the user's session open. Log and continue with no arm. This is
+		// the silent-registration-miss (blocker #2): the session opened fine but is
+		// NOT a garden citizen — the doctor catches it via this ERROR line.
+		logLine(
+			"ERROR",
+			`upsert failed (event=${eventName}, native=${sessionId}): ${err instanceof Error ? err.message : String(err)}`,
+		);
+		emit({});
+	}
+
+	// Sender marker, keyed by the shared Claude Code parent pid: the user-scope
+	// MCP child (same parent) reads it at entwurf_v2 send time to promote this
+	// session from anonymous external-mcp to a REPLYABLE meta-session sender —
+	// process ancestry, not cwd inference (same repo + multiple sessions would be
+	// ambiguous). Best-effort: a failed marker only costs reply-addressability
+	// (WARN), it does not break the session or the receiver path.
+	//
+	// SE-1/SE-2 (dual-owner fix): write ONLY for the direct parent (process.ppid =
+	// the Claude CLI that ran this hook, verified the native tree is direct — the
+	// plugin host is not in between). The old code ALSO wrote a marker for the
+	// grandparent. That grandparent is the login shell (e.g. bash under ghostty/i3),
+	// which OUTLIVES the Claude session: when Claude exits, the grandparent marker's
+	// ownerStartKey still matches a live pid, so it passes readMetaSenderMarker's
+	// reuse guard and the dead session keeps looking like a live, replyable receiver
+	// — a false-positive "active receiver" leak. The owner must be the watchPaths
+	// subscriber (the Claude CLI), nothing higher. If a stray topology means the MCP
+	// child's shared ancestor is not process.ppid, that resolves to "no marker"
+	// (fail-closed, honest) rather than a wrong-but-live grandparent identity.
+	const ownerPid = process.ppid;
+	if (typeof ownerPid === "number" && ownerPid > 0) {
+		try {
+			writeMetaSenderMarker({ backend: "claude-code", gardenId, nativeSessionId: sessionId, cwd, ownerPid });
+			logLine("INFO", `sender marker ${ownerPid} -> ${gardenId} (event=${eventName})`);
+		} catch (err) {
+			logLine(
+				"WARN",
+				`sender marker write failed (event=${eventName}, pid=${ownerPid}, garden=${gardenId}): ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	}
+
+	// watchPaths is emittable only from SessionStart / CwdChanged / FileChanged.
+	// UserPromptSubmit reaches here only to backfill the record above; it must NOT
+	// claim to arm a watch it cannot (decided).
+	if (eventName === "UserPromptSubmit") {
+		emit({});
+	}
+
+	try {
+		const mailbox = path.join(defaultMetaMailboxDir(), gardenId);
+		fs.mkdirSync(mailbox, { recursive: true });
+		const signal = path.join(mailbox, "inbox.signal");
+		if (!fs.existsSync(signal)) fs.writeFileSync(signal, "", { mode: 0o600 });
+		logLine("INFO", `armed watch ${signal}`);
+		// Receiver presence marker (SE-2): written on the arm-capable hook path that
+		// emits watchPaths, keyed by garden id with the watch owner pid (= the Claude
+		// CLI, process.ppid — same single owner as the sender marker, never the
+		// grandparent). It records that a LIVE owner reached the watch-arm emit; it is
+		// not proof the host ack'd the watch registration. This is what lets a sender
+		// tell a live receiver from a terminated one whose record still lingers.
+		// Best-effort: a failed/skipped marker only costs deliverability detection
+		// (WARN), it does not break the arm. An unknown event maps to null provenance →
+		// no marker (fail-closed: never claim an active receiver we cannot back).
+		const ownerPid = process.ppid;
+		const armProvenance = armProvenanceFor(eventName);
+		if (armProvenance === null) {
+			logLine("WARN", `receiver marker skipped — non-arm event ${eventName} (garden=${gardenId})`);
+		} else if (typeof ownerPid === "number" && ownerPid > 0) {
+			try {
+				writeMetaReceiverMarker({
+					gardenId,
+					backend: "claude-code",
+					nativeSessionId: sessionId,
+					ownerPid,
+					armProvenance,
+				});
+				logLine("INFO", `receiver marker ${gardenId} owner=${ownerPid} arm=${eventName}`);
+			} catch (err) {
+				logLine(
+					"WARN",
+					`receiver marker write failed (event=${eventName}, garden=${gardenId}): ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+		emit({
+			hookSpecificOutput: {
+				hookEventName: eventName,
+				watchPaths: [signal],
+			},
+		});
+	} catch (err) {
+		logLine(
+			"ERROR",
+			`arm failed (event=${eventName}, garden=${gardenId}): ${err instanceof Error ? err.message : String(err)}`,
+		);
+		emit({}); // record landed; only the arm failed — the doctor will flag the missing watch.
+	}
+}
+
+main();

package/pi-extensions/model-lock.ts

@@ -0,0 +1,235 @@
+/**
+ * model-lock — entwurf session model lock (extension-side revert).
+ *
+ * ⚠️ v2-only status (doc-truth): the "A (bridge-side)" companion described below
+ * — `acp-bridge.ts` / `ensureBridgeSession` — was removed in the ACP purge, so
+ * only this B-side hook remains. The `entwurf` provider it guards against is
+ * itself routing residue (Phase B: decide remove-vs-redefine model-lock; see
+ * NEXT--v2-only.md § Phase B 잔여). The A/B narrative below is retained as
+ * historical context pending that decision — read "A" as removed.
+ *
+ * Companion to the bridge-side guard in `acp-bridge.ts` (ensureBridgeSession
+ * reuse-path `ModelSwitchLockedError`). The two work as a pair:
+ *
+ *   - A (bridge-side): live reuse-path mismatch inside a entwurf
+ *     bridge session is refused at `ensureBridgeSession`. This is the
+ *     fallback/direct-call boundary: it prevents silent backend handoff
+ *     and MCP identity drift if the extension hook is absent, disabled,
+ *     or fails before the revert lands.
+ *
+ *   - B (this hook): cross-provider departure (entwurf/X → native) AND
+ *     cross-provider entry (native → entwurf/X) — both touch the
+ *     entwurf boundary and are refused by reverting to the previous
+ *     model via `pi.setModel(previousModel)`. This is NOT a clean refusal:
+ *     pi-core has already mutated `agent.state.model` and appended
+ *     `model_change` to the JSONL before emitting `model_select`. We
+ *     observe the after-event and revert, which adds a second
+ *     `model_change` entry (X → Y → X).
+ *
+ * Why both surfaces (B fires first, A is the fallback):
+ *   - B observes `model_select` immediately when pi-core emits it,
+ *     which happens during `AgentSession.setModel()` BEFORE the next
+ *     prompt reaches any provider. So for the entwurf →
+ *     entwurf case (and every other touches-entwurf case), B
+ *     reverts the model first and the next prompt then enters the
+ *     bridge under the ORIGINAL model. A's reuse-path mismatch check
+ *     therefore does not fire on the happy path — there is no mismatch
+ *     left to catch. A only matters if B fails to register, throws
+ *     before `pi.setModel(from)` completes, or is disabled by an
+ *     operator overriding the extensions list.
+ *   - cross-provider departure (entwurf → native) and cross-provider
+ *     entry (native → entwurf) NEVER reach A at all — the next
+ *     prompt routes to a different provider, so `ensureBridgeSession`
+ *     is not called. B is the only surface for those cases.
+ *   - Wire-evidence captured during the issue #14 investigation: in a
+ *     native → entwurf entry, pi JSONL continued (hi1, hi2, ...)
+ *     but a fresh ACP backend session was bootstrapped and the model
+ *     could not see the pre-switch turn (model replied "현재 세션에서
+ *     hi2만 보입니다"). Same failure mode as entwurf → native
+ *     departure, mirrored.
+ *
+ * Policy:
+ *   - A entwurf session is locked to its starting model.
+ *   - Native-to-native switching is free. Once a native session is
+ *     anchored, switching INTO entwurf is refused because it would
+ *     create a fresh ACP backend behind a continuous pi transcript.
+ *   - The lock fires for any in-session `model_select` event whose
+ *     transition touches the entwurf boundary
+ *     (`from.provider === "entwurf" || to.provider === "entwurf"`)
+ *     and whose source is "set" or "cycle" (not "restore").
+ *
+ * Honest limits:
+ *   - This is NOT a transcript-clean refusal. The first `model_change`
+ *     entry (X → Y) is already in the JSONL by the time we observe the
+ *     event. Our `pi.setModel(from)` adds a second entry (Y → X). For a
+ *     fully clean refusal, pi-core would need a cancellable
+ *     `before_model_select` hook that this repo intentionally does not
+ *     patch (entwurf does not send PRs to pi-core).
+ *   - On the happy path B is a strict superset of A's coverage. A is the
+ *     fallback for cases where B did not run (handler registration
+ *     missing, thrown before the revert lands, extension disabled by an
+ *     operator override of the extensions list). Smoke `check-model-lock`
+ *     verifies B's policy logic; `smoke-model-switch` continues to
+ *     verify A's bridge-side throw as the fallback contract.
+ *
+ * References:
+ *   - pi-core setModel: pi-mono/packages/coding-agent/src/core/agent-session.ts:1416
+ *   - ModelSelectEvent: pi-mono/packages/coding-agent/src/core/extensions/types.ts:711-719
+ *   - ExtensionAPI.setModel: types.ts:1228 (returns Promise<boolean>; false = auth missing)
+ *   - ExtensionUIContext.notify: types.ts:135 (sync void)
+ *   - Wire evidence native → entwurf entry failure mode: GLG live test
+ *     2026-05-14 ~13:30 KST, session pi:019e24c0-1251-...
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const ENTWURF_PROVIDER = "entwurf";
+
+/**
+ * Module-level reentry guard.
+ *
+ * When our handler calls `pi.setModel(from)` to revert, pi-core's
+ * `AgentSession.setModel()` mutates state and emits another `model_select`
+ * event (with `source: "set"`). Without this flag, our hook would observe
+ * the synthetic emit and try to revert again — infinite recursion. The
+ * flag is set BEFORE `pi.setModel` and cleared in a `finally` so any
+ * exception path still releases it.
+ *
+ * Why module-level (not closure-local in the handler): the handler is
+ * registered once and shared. A handler-local `let reverting = false` is
+ * also module-scoped in practice but module-level makes the lifetime
+ * explicit. ctx-local is unavailable — ExtensionContext has no mutable
+ * scratch space we are supposed to use.
+ */
+let reverting = false;
+
+/**
+ * Module-level "session has started" gate.
+ *
+ * Before the operator commits to a turn, model changes are configuration
+ * (CLI `--model`, settings.json default, pre-turn model selector) and the
+ * lock must NOT fire — locking pre-turn would defeat legitimate setup.
+ * Once the session has anchored a model identity (an existing conversation
+ * is loaded, or the first agent_start fires), the lock becomes active.
+ *
+ * The flag is consulted by `model_select` and set by:
+ *   - `session_start`: per-reason policy (see below)
+ *   - `agent_start`:   always true (first turn = identity anchored)
+ *
+ * session_start reason behavior:
+ *   - resume / fork:        immediately true (inherited identity)
+ *   - reload:               preserved OR refreshed via getEntries() —
+ *                           guards against module re-import during
+ *                           extension reload that would reset the flag
+ *   - startup / new (default): true IFF entries already contain a message
+ *                              (saved-session-on-startup path is rare
+ *                              today since pi-mono distinguishes
+ *                              resume/new explicitly, but this is a
+ *                              future-proof guard)
+ */
+let sessionLocked = false;
+
+/**
+ * Probe whether the session has at least one conversational message.
+ *
+ * `entry.type === "message"` matches `SessionMessageEntry` (real user /
+ * assistant / tool-result messages). Other entry types — `model_change`,
+ * `thinking_level_change`, `label`, `custom`, `session_info`,
+ * `compaction`, `branch_summary` — are not conversational, so our own
+ * revert-induced `model_change` entries do NOT register as "started".
+ *
+ * Defensive false-positive: if `getEntries()` throws at a reload /
+ * teardown boundary, we treat the session as started and engage the
+ * lock. This is the conservative side because failing-open would let a
+ * race window break the lock. The repo's general "throw, don't warn"
+ * rule yields here because this is a lock-state probe, not config
+ * validation — silent fall-through to "locked" preserves safety.
+ */
+function hasStartedConversation(ctx: ExtensionContext): boolean {
+	try {
+		return ctx.sessionManager.getEntries().some((entry) => entry.type === "message");
+	} catch {
+		return true;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", (event, ctx) => {
+		if (event.reason === "resume" || event.reason === "fork") {
+			// Resumed/forked sessions inherit a model identity from the
+			// session being resumed/forked. Lock immediately.
+			sessionLocked = true;
+			return;
+		}
+		if (event.reason === "reload") {
+			// Reload happens in-process (extension/settings reattach).
+			// If the module was re-imported during reload, our `sessionLocked`
+			// resets to false — recover via getEntries(). If the module
+			// survived, preserve the existing flag.
+			sessionLocked = sessionLocked || hasStartedConversation(ctx);
+			return;
+		}
+		// startup / new — empty session: pre-turn model changes are free.
+		// Non-empty session (rare today, but possible if pi-mono ever
+		// loads a saved session under `reason: "startup"`): lock.
+		sessionLocked = hasStartedConversation(ctx);
+	});
+
+	pi.on("agent_start", () => {
+		// First prompt has triggered the agent loop. Model identity is
+		// now anchored for this session — lock from here on.
+		sessionLocked = true;
+	});
+
+	pi.on("model_select", async (event, ctx) => {
+		// Reentry: our own revert call. Skip to avoid infinite loop.
+		if (reverting) return;
+
+		// "restore" fires when pi reloads a saved session's model on
+		// startup. Refusing that would either loop or block a legitimate
+		// resume. "set" (explicit /model, model selector, Ctrl+P) and
+		// "cycle" (next/prev) both reach the user-initiated switch path
+		// and are the cases we want to lock.
+		if (event.source === "restore") return;
+
+		// Session not yet started — pre-turn model changes are operator
+		// configuration, not a lock violation. CLI --model override,
+		// settings.json default load, and pre-turn model selector all
+		// reach here under the unlocked state.
+		if (!sessionLocked) return;
+
+		const from = event.previousModel;
+		const to = event.model;
+
+		// First model selection has no previous model to revert to.
+		// Lock only applies to in-session switches.
+		if (!from) return;
+
+		// Same model picked again (id + provider identical). Not a switch,
+		// just a no-op state set. Skip.
+		if (from.provider === to.provider && from.id === to.id) return;
+
+		// Only act when the transition touches the entwurf boundary.
+		// Covers:
+		//   entwurf → entwurf (id different)    — B primary, A fallback
+		//   entwurf → native                         — B only (A out of flow)
+		//   native       → entwurf                   — B only (A not yet engaged)
+		// Skips:
+		//   native       → native                         — out of scope, free
+		const touchesEntwurf = from.provider === ENTWURF_PROVIDER || to.provider === ENTWURF_PROVIDER;
+		if (!touchesEntwurf) return;
+
+		reverting = true;
+		try {
+			const ok = await pi.setModel(from);
+			ctx.ui.notify(
+				ok
+					? `Session is locked to ${from.provider}/${from.id}; reverted attempted switch to ${to.provider}/${to.id}.`
+					: `Session is locked to ${from.provider}/${from.id}; failed to revert from ${to.provider}/${to.id} (auth missing for original model?).`,
+				ok ? "warning" : "error",
+			);
+		} finally {
+			reverting = false;
+		}
+	});
+}

package/prompts/engraving.md

@@ -0,0 +1,27 @@
+<!-- ═══════════════════════════════════════════════════════════════════════
+     SAMPLE — operator engraving carrier (entwurf)
+
+     What this is: the markdown body below this comment is loaded VERBATIM
+     into the backend's identity slot (Claude `_meta.systemPrompt`). It is
+     the one place an operator stamps a short identity onto every entwurf
+     ACP turn — replacing Claude's `claude_code` preset (which also strips
+     the preset's auto-memory advertisement, the memory-containment lever).
+
+     Where it loads from:
+       • Runtime default = pi-extensions/lib/acp/prompts/engraving.md
+         (ships as the minimal `# Engraving Here` placeholder; a gate pins
+         it non-empty so the containment lever stays ON).
+       • THIS root copy is a documented sample / starting point. Point the
+         runtime at your own file with
+         ENTWURF_ACP_ENGRAVING_PATH=/path/to/your.md — it is NOT loaded by
+         default (the lib copy above is).
+
+     Rules:
+       • Template variables: {{backend}}, {{mcp_servers}}.
+       • Keep it TINY. Do NOT paste AGENTS.md, the bridge narrative, or
+         tool catalogs here — a large Claude carrier can route OAuth
+         sessions to metered "extra usage" billing.
+       • An empty or missing file = opt-out (no engraving). That is fine.
+     ═══════════════════════════════════════════════════════════════════════ -->
+
+# Engraving Here

package/protocol.js

@@ -0,0 +1,31 @@
+/**
+ * Shared wire-format constants for entwurf surfaces that must agree
+ * across the root bridge and pi-extension / MCP helper code.
+ *
+ * Keep this file dependency-free. Single source for both runtime paths:
+ *   - tsc-emit path: typechecked under root tsconfig.json (allowJs: true)
+ *     and copied through to the .tmp-verify directories by tsc emit.
+ *   - Node --experimental-strip-types path (mcp bridges): resolves explicit
+ *     .js imports literally to this file on disk.
+ *
+ * Why .js and not .ts: strip-types does not substitute .ts source for a
+ * literal .js import specifier, and the root config cannot enable
+ * allowImportingTsExtensions without losing tsc emit (which check-models
+ * relies on). Authoring as .js side-steps the whole drift surface.
+ */
+
+/**
+ * Opening marker for the project-context block inserted by entwurf's
+ * `enrichTaskWithProjectContext`. The ACP bridge uses the same marker to
+ * detect entwurf-spawned first prompts and remove only the duplicate cwd
+ * AGENTS.md section from its own pi-context augment.
+ */
+export const ENTWURF_PROJECT_CONTEXT_OPEN_TAG = "<project-context";
+
+/**
+ * Sender-side UI echo custom message type for successful entwurf_v2 send calls.
+ * The bridge emits it, the control renderer draws it, and the provider-level
+ * context filter removes it before LLM conversion. Keep as one SSOT: a typo
+ * here otherwise becomes a silent UI/context split.
+ */
+export const ENTWURF_SENT_MESSAGE_TYPE = "entwurf-sent";