@junghanacs/entwurf 0.25.0 → 0.30.0

package/pi-extensions/lib/acp/backend-adapter.ts

@@ -267,6 +267,18 @@ function resolveClaudeLaunch(): AcpLaunchSpec {
 	return { command: process.execPath, args: [launcher] };
 }
 
+/**
+ * The claude child runs with Claude Code's own background-task switch on (#125): the vendor drops
+ * `run_in_background` from the Bash/Agent schemas it declares to the model and turns off timeout and
+ * turn-abort backgrounding. Without it a vendor-backgrounded command runs in its own session (setsid),
+ * outlives an ACP cancel, and is orphaned to init when the child exits — the process-group teardown
+ * cannot reach it (`[측정 2026-10-02]` claude-agent-sdk 0.3.274 / claude-agent-acp 0.79.0). A process a
+ * command detaches on its own is outside the switch. It rides
+ * the claude adapter's launch env, which backend.ts spreads over `process.env` at spawn, so an
+ * ambient value cannot turn it off. Cortex declares nothing of the kind.
+ */
+export const CLAUDE_FOREGROUND_ONLY_ENV = { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1" } as const;
+
 export const claudeAdapter: AcpBackendAdapter = {
 	backend: "claude",
 
@@ -292,7 +304,7 @@ export const claudeAdapter: AcpBackendAdapter = {
 	},
 
 	launchEnvDefaults() {
-		return claudeLaunchEnvDefaults();
+		return { ...claudeLaunchEnvDefaults(), ...CLAUDE_FOREGROUND_ONLY_ENV };
 	},
 
 	ensureOverlay() {

package/pi-extensions/lib/entwurf-fact-provider.ts

@@ -102,8 +102,8 @@ export interface EntwurfFactsDeps {
 	/** Socket axis: injected into scanSocketProbes (controlDir/readdir/probe). */
 	socket?: Partial<SocketScanDeps>;
 	/** Observation axis (#101): per-citizen receiver + transcript facts. Defaults to the
-	 * REAL measurement — the same seam shape `makeProductionEntwurfV2Deps` uses, so the two
-	 * wiring sites (MCP + pi-native) cannot drift by each passing their own observer, and a
+	 * REAL measurement — the same seam shape `makeProductionEntwurfV2Deps` uses, so a wiring
+	 * site cannot drift by passing its own observer (one site, the bridge, since #125), and a
 	 * gate still drives the assembly with a fake and no filesystem. */
 	observe?: PeerObserver;
 	/** Placement axis (#116 S1): the ONE placement-owner read this listing is allowed.

package/pi-extensions/lib/entwurf-mcp-server.ts

@@ -0,0 +1,74 @@
+/**
+ * entwurf-mcp-server — how a pi citizen hands its Entwurf verbs to Pi's built-in MCP (#125).
+ *
+ * WHY THE VERBS ARE NOT NATIVE TOOLS ANY MORE. Pi 0.99 ships MCP as a built-in extension
+ * (`builtin:mcp`): it spawns stdio servers, owns their lifecycle, and closes them on
+ * `session_shutdown`. The same compiled `entwurf-bridge` every other harness already reaches is
+ * therefore the one surface a pi session needs too — the five hand-written `registerTool` copies
+ * that duplicated it are gone, and so is the drift they invited. Pi, not Entwurf, supervises the
+ * child: nothing here starts, restarts or stops a process.
+ *
+ * WHAT THIS MODULE DECIDES, AND NOTHING ELSE:
+ *   - the server NAME. `entwurf-bridge` is the key every other host already uses. Pi sanitizes it
+ *     into the call name, so a pi model calls `mcp__entwurf_bridge__<verb>` (`[측정 2026-10-01,
+ *     pi 0.99.2]` `extensions/mcp/tools.ts:82-90`: everything outside `[A-Za-z0-9_]` becomes `_`).
+ *     The key itself is unchanged. It is a call-name prefix, never an address: the record is the
+ *     only address axis.
+ *   - the ENTRY. The COMPILED bridge (`scripts/build-bridge.sh` output) that a packaged consumer
+ *     receives next to `pi-extensions/`. There is no TypeScript fallback: a missing build is a
+ *     named failure, not a silent switch to a different artifact.
+ *   - the IDENTITY carrier. `PI_SESSION_ID` / `PI_AGENT_ID` are passed EXPLICITLY in the server
+ *     config from the record this session was just born with. Pi merges a stdio child's env as
+ *     `{...process.env, ...config.env}`, so the explicit value wins over whatever the process
+ *     happens to carry — the carrier is the record-established identity by construction, not by
+ *     the timing of an ambient export.
+ *   - the EXPOSURE. `direct`: the verbs are declared to the model like built-in tools. Two bridge
+ *     tools have no use on a pi host and are hidden: `entwurf_inbox_read` drains a caller-supplied
+ *     mailbox (a pi citizen has no mailbox), and `entwurf_register_native` binds a NATIVE harness
+ *     session (a pi citizen is born by this extension).
+ *
+ * A same-namespace entry in the operator's or a trusted project's `mcp.json` — `entwurf-bridge` or
+ * `entwurf_bridge`, which Pi folds to one namespace — replaces this registration by Pi's own
+ * precedence, and `/mcp` says so. That is the operator's choice and
+ * Pi's contract; this module does not scan config, fight it, or add a second owner.
+ */
+
+import * as path from "node:path";
+import type { McpServerConfig } from "@earendil-works/pi-coding-agent";
+
+/** The built-in MCP server key. Pi sanitizes it into the call name (`mcp__entwurf_bridge__<verb>`); never an address. */
+export const ENTWURF_MCP_SERVER_NAME = "entwurf-bridge";
+
+/** Bridge tools with no use on a pi host (see the module header). */
+export const ENTWURF_MCP_HIDDEN_TOOLS = ["entwurf_inbox_read", "entwurf_register_native"] as const;
+
+/**
+ * The compiled bridge entry, resolved from the directory of the extension file that loads it.
+ * Checkout and packaged install share this layout: `pi-extensions/` beside `mcp/entwurf-bridge/dist/`.
+ */
+export function entwurfBridgeCompiledEntry(extensionDir: string): string {
+	return path.resolve(extensionDir, "..", "mcp", "entwurf-bridge", "dist", "mcp", "entwurf-bridge", "src", "index.js");
+}
+
+export interface EntwurfMcpServerInput {
+	/** The record gardenId this session was just born with. */
+	gardenId: string;
+	/** `<provider>/<model>` of the live session, when known. */
+	agentId: string | undefined;
+	/** Absolute path of the compiled bridge entry. */
+	compiledEntry: string;
+	/** The node binary running pi. */
+	nodePath: string;
+}
+
+/** The one server config a born pi citizen registers. Pure: no IO, no env reads. */
+export function buildEntwurfMcpServerConfig(input: EntwurfMcpServerInput): McpServerConfig {
+	if (!input.gardenId) throw new Error("entwurf-mcp-server: a server config needs the born record's gardenId");
+	return {
+		command: input.nodePath,
+		args: [input.compiledEntry],
+		env: { PI_SESSION_ID: input.gardenId, ...(input.agentId ? { PI_AGENT_ID: input.agentId } : {}) },
+		exposure: "direct",
+		toolExposure: Object.fromEntries(ENTWURF_MCP_HIDDEN_TOOLS.map((tool) => [tool, "hidden"])),
+	};
+}

package/pi-extensions/lib/entwurf-peers-render.ts

@@ -3,7 +3,7 @@
  * surface (0.11 Stage 0 step 4, slice 4c). The MCP handler stays thin: it does IO
  * (readdir the meta-store + probe sockets via `listEntwurfFacts`) and then calls
  * THIS to shape the text + JSON. No IO here, so the gate drives it without a
- * filesystem and the SAME facts can feed pi-native / doctor / v2 dispatch later
+ * filesystem and the SAME facts can feed the bridge / doctor / v2 dispatch
  * (a handler that did its own brain work would deny them that reuse).
  *
  * Two hard rules carried from the frozen contract (동결결정 10 + #50 C4):

package/pi-extensions/lib/entwurf-v2-decider.ts

@@ -22,7 +22,7 @@
  *
  * The frozen 7-step order (NEXT.md "통합 decider 순서"):
  *   1. requireGardenId   — runtime guard BEFORE any path is built (F2-P1; closes the
- *      MCP-schema bypass for pi-native/internal callers).
+ *      MCP-schema bypass for internal callers).
  *   2. resolveTarget     — no citizen → bad-target; a record-less control socket →
  *      record-less-socket (#50 C4: the record is the sole address authority);
  *      quarantined (out-of-socket-domain record sharing a socket/symlink) → target-address-conflict.
@@ -227,7 +227,7 @@ export interface DispatchDeciderDeps {
 
 /**
  * F2-P1 defense in depth: never build a lock/socket path from an unvalidated gid.
- * The MCP TypeBox pattern guards that one surface; a pi-native / internal caller
+ * The MCP schema pattern guards that one surface; an internal caller
  * bypasses the schema, so the decider re-validates as its very first step.
  */
 function requireGardenId(target: string): string {

package/pi-extensions/lib/entwurf-v2-mailbox.ts

@@ -77,8 +77,8 @@ export function executeMetaMailboxSend(
  * Build the production `sendViaMailbox(plan, lock)` adapter the 5c-2a send hand consumes.
  * It IGNORES `lock` entirely (release is the hand's job; a mailbox plan is lock-free) and
  * wraps the sync body in the async dep signature. `senderProvider` is supplied by the
- * wiring site — it calls the private `buildLocalSenderEnvelope(ctx)` and decorates
- * origin/replyable — so this module never imports ExtensionContext. `enqueue` defaults to
+ * wiring site — the bridge's authoritative sender resolution (the one caller-side
+ * surface since #125) — so this module never imports ExtensionContext. `enqueue` defaults to
  * the real `enqueueMetaMessage`; the gate injects a fake.
  */
 export function makeProductionSendViaMailbox(opts: {

package/pi-extensions/lib/entwurf-v2-production.ts

@@ -2,8 +2,8 @@
  * entwurf-v2-production — 5d-2b: the ctx-free PRODUCTION assembly of `runEntwurfV2`'s deps.
  * `makeProductionEntwurfV2Deps(opts)` wires the real 5b decider IO seams + the three 5c
  * transport hands into one `EntwurfV2RunDeps` (`{decide, executor}`). It touches NO
- * `ExtensionContext`/`ExtensionAPI` — the wiring SITE (5d-3, entwurf-control.ts) builds the
- * `senderProvider` from `buildLocalSenderEnvelope(ctx)` and passes it in, so this module
+ * `ExtensionContext`/`ExtensionAPI` — the wiring SITE (the entwurf-bridge `entwurf_v2`
+ * handler; the pi-native one left with #125) builds the `senderProvider` and passes it in, so this module
  * stays in `lib/` with the rest of the gate-/smoke-testable v2 core.
  *
  * Three invariants this factory exists to guarantee (each gate-proven):
@@ -136,7 +136,7 @@ export interface ProductionEntwurfV2Seams {
 }
 
 export interface ProductionEntwurfV2Opts {
-	/** Built at the wiring site from `buildLocalSenderEnvelope(ctx)`, decorated with its
+	/** Built at the wiring site (the bridge's authoritative sender resolution), carrying its
 	 * HONEST pi-session replyability (SE-1 2e-a: `replyable` reflects whether the canonical
 	 * control socket actually exists, not a hardcoded true). ONE provider feeds ALL THREE
 	 * rails — the control-socket RPC sender, the meta-mailbox body sender, and the

package/pi-extensions/lib/entwurf-v2-surface.ts

@@ -1,11 +1,9 @@
 /**
  * entwurf-v2-surface — 5d-3a: the ctx-free SURFACE adapter that joins a surface's raw params
  * to `runEntwurfV2` and renders the outcome-rich result back to a human/tool string. It is the
- * ONE place a surface (pi-native `entwurf_v2` tool now; the MCP `entwurf_v2` verb in 5d-3b)
- * crosses into the v2 fence — so `entwurf-control.ts` (a root-tsc, emit-capable surface that
- * CANNOT statically import the `.ts`-extension fence without TS5097) reaches this via a
- * NON-LITERAL dynamic import, and the MCP bridge (already a `.ts`-import consumer) imports it
- * directly. Either way the ctx binding stays OUT of the fence: the caller builds
+ * ONE place a surface (the MCP `entwurf_v2` verb — the only one since #125 retired the
+ * pi-native copy) crosses into the v2 fence; the MCP bridge (a `.ts`-import consumer) imports
+ * it directly. Either way the ctx binding stays OUT of the fence: the caller builds
  * `senderProvider` from its own envelope source and passes it in `opts`.
  *
  * Three exports:

package/pi-extensions/lib/entwurf-v2-visible-resume.ts

@@ -329,9 +329,9 @@ const REJECT_HINT: Record<VisibleResumeRejectReason, string> = {
 };
 
 /**
- * ONE renderer for both surfaces — the same reason `mux-fresh-call` has one: the two
- * registrations are separate literals, and a shared renderer is what keeps the operator-visible
- * answer from drifting apart between native pi and the MCP bridge.
+ * ONE renderer — the same reason `mux-fresh-call` has one: it keeps the operator-visible answer
+ * out of the registration literal. (Since #125 the MCP bridge is the only registration; the
+ * native pi copy it once had to agree with is retired.)
  *
  * The success text keeps the two receipts visibly apart, including in the good case. A reader
  * who sees "window opened" and "socket alive" as one sentence has been told the resume worked;

package/pi-extensions/lib/fresh-call-composition.ts

@@ -33,9 +33,16 @@ export const FRESH_CALL_BACKENDS = ["pi", "claude-code", "copilot", "omp", "code
 export type FreshCallBackend = (typeof FRESH_CALL_BACKENDS)[number];
 
 /**
- * The callback tool NAME differs per backend and that is not cosmetic: native pi exposes the
- * capability directly (`entwurf_v2`), while an MCP-hosted session reaches it under whatever
- * name that harness composes. Naming the wrong one costs the whole first turn.
+ * The callback tool NAME differs per backend and that is not cosmetic: every session reaches the
+ * capability under whatever name its harness composes for the `entwurf-bridge` MCP server, and
+ * naming the wrong one costs the whole first turn.
+ *
+ * `[측정 2026-10-01, pi 0.99.2]` pi reaches the verbs through its BUILT-IN MCP (#125 — the native
+ * `registerTool` copies are gone), and Pi composes `mcp__<server>__<tool>` replacing everything
+ * outside `[A-Za-z0-9_]` with `_` (`extensions/mcp/tools.ts:82-90`, tag v0.99.2): the server key
+ * stays `entwurf-bridge`, but the model-facing names are `mcp__entwurf_bridge__entwurf_*` — the
+ * same spelling Codex composes, and NOT Claude Code's. 0.99.1 kept the hyphen; the floor moved to
+ * 0.99.2 as a hard cut — one literal pi dialect, chosen over an alias or a version router.
  *
  * `[측정]` Copilot CLI 1.0.80 composes `<mcpServerName>-<mcpToolName>` — NOT Claude Code's
  * `mcp__<server>__<tool>`. Read from two independent sessions' own event logs
@@ -54,7 +61,7 @@ export type FreshCallBackend = (typeof FRESH_CALL_BACKENDS)[number];
  * permission dialect: omp's approval layer consults the same minted string (`source-audit.md`).
  */
 export const FRESH_CALL_CALLBACK_TOOL: Record<FreshCallBackend, string> = {
-	pi: "entwurf_callback",
+	pi: "mcp__entwurf_bridge__entwurf_callback",
 	"claude-code": "mcp__entwurf-bridge__entwurf_callback",
 	copilot: "entwurf-bridge-entwurf_callback",
 	omp: "mcp__entwurf_bridge_entwurf_callback",
@@ -65,7 +72,7 @@ export const FRESH_CALL_CALLBACK_TOOL: Record<FreshCallBackend, string> = {
 
 /** Where a sibling SENDS the task result. Always the delivery verb, never the birth callback. */
 export const FRESH_CALL_DELIVERY_TOOL: Record<FreshCallBackend, string> = {
-	pi: "entwurf_v2",
+	pi: "mcp__entwurf_bridge__entwurf_v2",
 	"claude-code": "mcp__entwurf-bridge__entwurf_v2",
 	copilot: "entwurf-bridge-entwurf_v2",
 	omp: "mcp__entwurf_bridge_entwurf_v",
@@ -87,7 +94,7 @@ export const FRESH_CALL_DELIVERY_TOOL: Record<FreshCallBackend, string> = {
  * SAME rule produces the whole word here.
  */
 export const FRESH_CALL_PEERS_TOOL: Record<FreshCallBackend, string> = {
-	pi: "entwurf_peers",
+	pi: "mcp__entwurf_bridge__entwurf_peers",
 	"claude-code": "mcp__entwurf-bridge__entwurf_peers",
 	copilot: "entwurf-bridge-entwurf_peers",
 	omp: "mcp__entwurf_bridge_entwurf_peers",

package/pi-extensions/lib/meta-mailbox-body.ts

@@ -3,7 +3,7 @@
  * meta-bridge mailbox body. Every transport that can deliver to a garden citizen
  * with no live control socket uses this:
  *   - the MCP bridge entwurf_v2 (mcp/entwurf-bridge) — external/Claude-host sends
- *   - the pi-native entwurf_v2 (pi-extensions/entwurf-control.ts) — pi-session sends
+ *     (pi-session sends included since #125 — a pi session reaches that same verb)
  *   - the native-push rail (pi-extensions/lib/entwurf-v2-native-push.ts) — direct
  *     injection into an Antigravity conversation or a loaded Codex thread. Its
  *     THIRD consumer, added after the #95 A LIVE run measured what an envelope-less

package/pi-extensions/lib/mux-fresh-call.ts

@@ -659,9 +659,9 @@ const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 };
 
 /**
- * ONE renderer for both surfaces. Not a convenience: the two registrations are separate literals
- * (that is this repo's shape), so a shared renderer is what keeps the operator-visible answer
- * from drifting apart between native pi and the MCP bridge.
+ * ONE renderer, outside the registration. Not a convenience: it keeps the operator-visible answer
+ * out of a registration literal. (Since #125 the MCP bridge is the only registration; the native
+ * pi copy it once had to agree with is retired.)
  *
  * The success text states the boundary out loud. A caller that reads "launched" and assumes
  * "delivered" is the exact confusion the two-receipt split exists to prevent, so the text refuses