@junghanacs/entwurf 0.13.0 → 0.14.0

package/pi-extensions/lib/acp/event-mapper.ts

@@ -39,7 +39,6 @@ export interface AcpStreamIdentity {
 type ObservedToolState = {
 	title: string;
 	status?: string;
-	notifiedRunning?: boolean;
 };
 
 export type AcpPiStreamState = {
@@ -81,7 +80,12 @@ export function createAcpStreamState(
 		provider: identity.provider,
 		model: identity.model,
 		usage: zeroUsage(),
-		stopReason: "stop",
+		// Seed, not a verdict. pi 0.83 added "pending" for exactly this: a partial
+		// streaming message has not observed a terminal reason yet, and every pi
+		// provider seeds it here and treats a stream that ENDS still-pending as an
+		// error rather than a successful stop. Seeding "stop" instead would
+		// pre-claim success for the whole time the turn is in flight.
+		stopReason: "pending",
 		timestamp: opts?.timestamp ?? Date.now(),
 	};
 	return {
@@ -221,22 +225,21 @@ function renderToolUpdate(state: AcpPiStreamState, update: Record<string, unknow
 	const title = titleForTool(update, previous?.title);
 	const status = typeof update?.status === "string" ? (update.status as string) : previous?.status;
 	const updateContent = Array.isArray(update?.content) ? (update.content as unknown[]) : undefined;
-	const meta = update?._meta as { terminal_output?: unknown } | undefined;
-
-	let notifiedRunning = previous?.notifiedRunning;
 
 	if (update.sessionUpdate === "tool_call") {
-		observedTools.set(toolCallId, { title, status, notifiedRunning });
+		observedTools.set(toolCallId, { title, status });
 		pushNotice(state, `\n[tool:start] ${sanitizeNoticeFragment(title, NOTICE_TITLE_MAX)}\n`);
 		return;
 	}
 
-	// tool_call_update
-	if (meta?.terminal_output && !notifiedRunning) {
-		notifiedRunning = true;
-		pushNotice(state, `\n[tool:running] ${sanitizeNoticeFragment(title, NOTICE_TITLE_MAX)}\n`);
-	}
-
+	// tool_call_update. There is deliberately no mid-flight `[tool:running]`
+	// notice: it would have to be driven by the adapter's `_meta.terminal_output`,
+	// and that meta is gated upstream on `clientCapabilities._meta.terminal_output
+	// === true` while backend.ts initializes with `clientCapabilities: {}`. So the
+	// branch could never fire for any backend we ship — it claimed a transcript
+	// line the operator was never going to see. Declaring the terminal capability
+	// is a separate axis, not a one-line re-enable: the adapter would then send
+	// terminal widgets/metas this mapper cannot render honestly into a transcript.
 	if (status && status !== previous?.status) {
 		const summary = firstTextContent(update?.rawOutput) ?? firstTextContent(updateContent);
 		const suffix = summary ? ` — ${sanitizeNoticeFragment(summary, NOTICE_SUMMARY_MAX)}` : "";
@@ -250,7 +253,7 @@ function renderToolUpdate(state: AcpPiStreamState, update: Record<string, unknow
 		}
 	}
 
-	observedTools.set(toolCallId, { title, status, notifiedRunning });
+	observedTools.set(toolCallId, { title, status });
 }
 
 /** Push a permission-decision notice (informational text, not a tool call). */

package/pi-extensions/lib/acp/models.ts

@@ -9,8 +9,8 @@
 // Two curated sets live here, one per adapter on the rail
 // (backend-adapter.ts): the unprefixed Claude ids (the reference backend) and
 // the `cortex-` prefixed Snowflake Cortex Code ids (the second backend, landed
-// 0.13.0 — docs/acp-backend-rail.md §6/§11-8). Codex is already a native garden
-// citizen and Gemini/major tools use native, so neither is an ACP backend here.
+// 0.13.0 — docs/acp-backend-rail.md “Cortex Code audit”). Codex has native
+// delivery-probe evidence but no managed citizen lane; neither it nor Gemini is an ACP backend here.
 // A third governed backend EXTENDS this file the same way — it does not change
 // the pattern.
 
@@ -87,9 +87,9 @@ function claudeContextWindow(model: { id: string; contextWindow: number }): numb
 // ── Cortex (Snowflake Cortex Code) curated surface ──────────────────────────
 //
 // entwurf's ACP rail is backend-extensible: Cortex is the first NON-claude
-// backend to land through it (docs/acp-backend-rail.md §6). pi-ai carries no
+// backend to land through it (docs/acp-backend-rail.md, “Shipped adapters”). pi-ai carries no
 // snowflake/cortex model source, so this surface is HAND-CURATED. Every id
-// carries the reserved `cortex-` prefix (§9-1): the prefix is the SINGLE routing
+// carries the reserved `cortex-` prefix: the prefix is the SINGLE routing
 // authority (backend-adapter.ts `routeModel`) and keeps the ids off the Claude
 // native ids Cortex routes to (`cortex-claude-sonnet-5` vs the unprefixed
 // `claude-sonnet-5` the claude adapter owns). `routeModel` strips the prefix to

package/pi-extensions/lib/acp/overlay.ts

@@ -2,8 +2,8 @@
 //
 // claude-agent-acp's SettingsManager loads the operator's `~/.claude/settings.json`
 // DIRECTLY (CLAUDE_CONFIG_DIR is the only knob that redirects that read). So the
-// operator's native `permissions.defaultMode` ("auto"), hooks, plugins, and
-// per-cwd memory/projects state would otherwise leak into entwurf ACP
+// operator's native `permissions.defaultMode` (whatever its current value), hooks,
+// plugins, and per-cwd memory/projects state would otherwise leak into entwurf ACP
 // sessions. The overlay redirects SettingsManager at a pi-owned directory whose
 // `settings.json` WE author (minimal, `hooks:{}`), while keeping exactly the
 // operator entries a backend needs (credentials, caches, built-in skills)
@@ -15,7 +15,7 @@
 // materializer, and cortex did: `ensureCortexDualHomeOverlay` (+ projectCortexMcpJson /
 // sweepDeadCortexOverlays / cortexOverlayScopeId) lives further down this file with its
 // own D-number rationale — an isolated HOME rather than a redirect knob, because cortex
-// has no CLAUDE_CONFIG_DIR equivalent (§11-8 D2). The two share the module, never the
+// has no CLAUDE_CONFIG_DIR equivalent (ACP rail Cortex audit D2). The two share the module, never the
 // strategy. Codex/Gemini overlays (CODEX_HOME / admin.toml) remain behavior-oracle
 // territory and are out of scope here.
 //
@@ -105,9 +105,11 @@ export const OVERLAY_BINARY_OWNED: ReadonlySet<string> = new Set([".claude.json"
 
 /**
  * Minimal overlay settings.json. Only fields with a reason to pin:
- *   - `permissions.defaultMode: "default"` neutralizes the operator's native
- *     "auto"; combined with the explicit `tools`/`permissionAllow` surface,
- *     "default" auto-passes every tool we expose without prompts.
+ *   - `permissions.defaultMode: "bypassPermissions"` is deliberate unattended
+ *     ACP operation: a tool call must never suspend a model turn on an interactive
+ *     permission prompt. This does not widen the callable surface — explicit
+ *     `tools`/`disallowedTools` still shape it, and `permissionAllow` still rides
+ *     the inline Claude settings — or bypass backend authentication.
  *   - `autoMemoryEnabled: false` — SDK opt-out for auto-memory (defense in
  *     depth; the tiny non-empty engraving/preset replacement is the primary
  *     write-containment lever for Claude ACP).
@@ -117,7 +119,7 @@ export const OVERLAY_BINARY_OWNED: ReadonlySet<string> = new Set([".claude.json"
 export function overlaySettingsJson(): string {
 	return `${JSON.stringify(
 		{
-			permissions: { defaultMode: "default" },
+			permissions: { defaultMode: "bypassPermissions" },
 			autoMemoryEnabled: false,
 			hooks: {},
 		},
@@ -230,11 +232,11 @@ export function ensureClaudeConfigOverlay(
 
 // ============================================================================
 // Cortex dual-HOME overlay — the as-measured containment for `cortex acp serve`
-// (CP0 audit 2026-07-29, Cortex Code v1.1.52; docs/acp-backend-rail.md §4/§11-8).
+// (CP0 audit 2026-07-29, Cortex Code v1.1.52; docs/acp-backend-rail.md “Cortex Code audit”).
 // ============================================================================
 //
 // Why this is NOT the claude-shaped `SNOWFLAKE_HOME`-only overlay PR #40 shipped
-// (each point is a measured defect, not a preference — §11-8 D-numbers):
+// (each point is a measured defect, not a preference — Cortex audit D-numbers):
 //
 //   - D2: cortex reads `CONFIG_DIRS = [".claude", ".cortex"]` at `homedir()` and
 //     `~/.claude/skills` — a SNOWFLAKE_HOME redirect cannot move that axis. An

package/pi-extensions/lib/entwurf-control-rpc.ts

@@ -37,12 +37,14 @@ export interface SenderEnvelope {
 
 /**
  * THE `<sender_info>` synthesis — the one place the sender envelope becomes
- * message text. Two consumers, one shape (#50 C3):
+ * message text. ONE consumer since the visible-first cut (#50 C3):
  *   - the live socket rail's RECEIVER (entwurf-control handleCommand("send")
- *     appends it to the delivered customMessage);
- *   - the dormant spawn-resume rail's SENDER (entwurf-v2-production appends it
- *     to the resume prompt, so a resumed citizen wakes knowing who called in
- *     exactly the shape a live delivery would have rendered).
+ *     appends it to the delivered customMessage).
+ *
+ * The second consumer was the dormant spawn-resume rail's SENDER, which appended
+ * the same shape to a resume prompt so a resumed citizen woke knowing who called.
+ * That rail is gone. The shape stays single-sourced here so a future VISIBLE
+ * resume renders an identical envelope rather than inventing a second one.
  * `wants_reply` is emitted only when explicitly true — an unset/false marker
  * renders nothing (etiquette marker, not transport contract).
  */

package/pi-extensions/lib/entwurf-core.ts

@@ -1,19 +1,18 @@
 /**
  * entwurf-core — sync entwurf execution, host-agnostic.
  *
- * DIRECT importers, MEASURED from the import graph (2026-07-27) — not from memory:
+ * DIRECT importers, RE-MEASURED from the import graph (2026-08-06) — not from memory:
  *   - pi-extensions/entwurf-control.ts (the pi adapter)
- *   - pi-extensions/lib/entwurf-v2-spawn-production.ts (v2 spawn-bg launch identity)
- *   - pi-extensions/lib/project-trust-handler.ts · lib/acp/augment.ts ·
- *     lib/native-push/adapter.ts
- *   - plus gates/smokes (check-shell-quote, check-package-source-routing, …)
+ *   - pi-extensions/lib/resume-launch-identity.ts (record-authoritative launch identity,
+ *     itself consumer-zero since the visible-first cut — see its header)
+ *   - plus gates/smokes (check-shell-quote, check-package-source-routing,
+ *     check-entwurf-session-identity, new-session-id, resolve-acp-bridge)
  *
- * The MCP bridge is a TRANSITIVE consumer, not a direct one, and the distinction is the
- * whole point: `mcp/entwurf-bridge/src/index.ts → entwurf-v2-surface.ts →
- * entwurf-v2-production.ts → entwurf-v2-spawn-production.ts → entwurf-core.ts`. So the old
- * header's claim — that the bridge imports this shared implementation the way a v1 tool
- * surface did — was false, but so is "the bridge does not reach it": it reaches it at
- * runtime, only for spawn-bg production.
+ * The MCP bridge does NOT reach this module on any path, and that changed with the cut:
+ * its one edge ran `index.ts → entwurf-v2-surface.ts → entwurf-v2-production.ts →
+ * entwurf-v2-spawn-production.ts → entwurf-core.ts`, and the spawn-production link was
+ * deleted with the `spawn-bg` transport. Do not restate the old "transitive consumer,
+ * for spawn-bg production" line; re-measure before claiming either way.
  *
  * NOT consumers on any path: `pi-extensions/entwurf.ts` (the v1 pi native tool surface) and
  * `pi-extensions/lib/entwurf-async.ts` were REMOVED in the 0.12 cutover. Do not reintroduce
@@ -131,9 +130,9 @@ export function normalizeCodexEntwurfModelForAcp(model?: string): string | undef
 // The Entwurf Target Registry is GONE (#50 C3). `pi/entwurf-targets.json` and its
 // reader chain (loadEntwurfTargets / resolveEntwurfTarget / EntwurfRegistryError +
 // the ~/.pi/agent symlink machinery) were the v1 "narrow door" for spawn-model
-// policy — but v2 never spawns from a model tuple: entwurf_v2 resumes an
-// already-identified record-backed citizen, and the model axis is the citizen's
-// own (Identity Preservation Rule). The last readers were the RT-dead
+// policy — but v2 never spawns at all, from a model tuple or otherwise: entwurf_v2
+// addresses an already-identified record-backed citizen, and the model axis is the
+// citizen's own (Identity Preservation Rule). The last readers were the RT-dead
 // buildSessionName mirror and the v1 spawn guard, both swept with this cut.
 // Bridge-extension routing for provider=entwurf survives below (getRegistryRouting
 // ← scripts/resolve-acp-bridge.ts) and takes a caller-supplied target — no file.
@@ -211,7 +210,8 @@ const SESSION_READ_CHUNK_BYTES = 64 * 1024;
  *     old name-mirror integrity check and the `requireEntwurf` name-tag
  *     authorization are gone (#50 C3): resume authorization is record existence,
  *     and transcript integrity is the caller's header-id ↔ record.nativeSessionId
- *     check (entwurf-v2-spawn-production.resolveResumeLaunchIdentity).
+ *     check (resume-launch-identity.resolveResumeLaunchIdentity — the leaf that
+ *     outlived the spawn-bg factory it used to sit in).
  */
 export interface RecordedSessionIdentity {
 	/** JSONL header `id` (pi's own session id — the record's `nativeSessionId`). */

package/pi-extensions/lib/entwurf-resume-args.ts

@@ -1,41 +1,43 @@
 /**
- * entwurf-resume-args — the SINGLE source of truth for the `pi` argv a resume spawn is
- * launched with (0.11 Stage 0 step 5c-3b). One place owns the
- * `--no-extensions` / `--entwurf-control` decision so the launch shape cannot drift.
+ * entwurf-resume-args — the SINGLE source of truth for the `pi` argv that reopens a dormant
+ * citizen, MEASURED against the runtime rather than inherited from the removed transport.
  *
- * The shipped posture (A1): a RESIDENT, addressable garden citizen. The resume turn runs via
- * `-p <prompt>` (the prompt-as-turn authority), and the child is launched WITH
- * `--entwurf-control` and WITHOUT `--no-extensions` — the keep-alive is the GOAL here: the
- * resumed session stands its control socket up and stays addressable. The 5c-3a watcher's
- * `socket-alive` is exactly that "resumed citizen is up" observation (→ release the per-gid
- * lock, child lives on); `child-exited` is the early-exit/failure observation.
- * `plan.launchArgs` (`--approve` or empty, from the decider's preflight) rides along as pi
- * flags before the prompt.
+ * ── What changed, and why the old shape was not reusable ──
  *
- * A second `legacy` one-shot posture (`--no-extensions`, no control socket, so `pi -p` could
- * exit) lived here until 2026-07-27 and was removed with its launcher and the v1 verbs.
+ * Until the visible-first cut this builder emitted `--mode json -p … <prompt>`: a headless JSON
+ * child running one prompt-as-turn, which is what `spawn-bg`'s detached `defaultSpawnChild`
+ * needed. The design notes carried that argv forward as "visibility-neutral, reuse verbatim".
+ * It is not. Measured 2026-08-06 (private tmux + fixture, `pi --help`: `--print, -p` =
+ * *non-interactive mode*): dropped into a tmux window, the headless prefix produces a JSON
+ * stream and a turn, not a window an operator can type into. The visible dialect is the one
+ * `mux-fresh-call` already measured for a fresh sibling — no `--mode`, no `-p`.
  *
- * Provider/model identity is the caller's existing authority (readSessionIdentity /
- * getEntwurfExplicitExtensions) — this builder only LAYS OUT argv, it never resolves
- * identity. `explicitExtensionArgs` is preserved verbatim: a recorded `provider=entwurf`
- * resume needs the bridge re-injected to resolve the provider, and dropping it would
- * re-introduce the "Unknown provider" footgun (#29). (A future slice may dedup against
- * settings-loaded extensions; not here.)
+ * So the shipped posture is now one shape, and it is the only one:
  *
- * This module is import-free on purpose: the v2 adapter and the gate import the same source,
- * and a self-contained string builder keeps both tsconfigs happy.
+ *   pi --entwurf-control [-e <bridge> …] --session <file> [--provider <p>] --model <m>
+ *
+ * There is deliberately NO prompt and no `launchArgs`. A resume opens the window; talking to the
+ * citizen afterwards is `entwurf_v2`'s job on the socket this launch stands up. That split is
+ * what makes the resumed turn free: measured, a promptless resume left the transcript
+ * byte-identical (1666 → 1666) and started no model turn at all.
+ *
+ * The one-shot `legacy` variant (removed 2026-07-27) and the headless prefix (removed here) are
+ * not kept behind a variant flag for compatibility. An exported branch no product path takes is
+ * exactly what let this module's prose claim a live consumer for months.
+ *
+ * Provider/model identity is the caller's authority (`resolveResumeLaunchIdentity`) — this
+ * builder only LAYS OUT argv, it never resolves identity. `explicitExtensionArgs` is preserved
+ * verbatim: a recorded `provider=entwurf` resume needs the bridge re-injected or pi cannot
+ * resolve the provider (#29). Measured on that axis: the resolver emits
+ * `["-e", "<bridge>"]`, and the argv carries it exactly once, between `--entwurf-control` and
+ * `--session`.
+ *
+ * The runtime path itself is NOT here. Resolving `pi` on PATH and proving it launchable belongs
+ * to the mux lane (`mux-launch`), so this module emits the flags after the runtime and nothing
+ * more — which is also why it stays import-free and can be read by both tsconfigs.
  */
 
-/** The one shipped launch posture: a resident citizen (`--entwurf-control`, extensions
- * loaded). The `legacy` one-shot variant was removed with its launcher (2026-07-27) — an
- * exported branch no product path took was what let this module's prose claim a second
- * live consumer for months. Reviving a one-shot posture means adding it back deliberately,
- * with a consumer, not un-deleting a dead enum member. */
-export type ResumeArgsVariant = "v2-control";
-
 export interface ResumePiArgsInput {
-	/** v2-control = resident citizen (`--entwurf-control`, extensions loaded). */
-	variant: ResumeArgsVariant;
 	/** ABSOLUTE path of the session JSONL to resume — pi's `--session <path>` (#50 C2).
 	 * It replaced `--session-id <gardenId>`, which did two jobs that are no longer the
 	 * same string: it named the session to reopen AND fixed the control-socket key. The
@@ -52,37 +54,24 @@ export interface ResumePiArgsInput {
 	provider: string | null | undefined;
 	/** The resolved launch model (caller applies `modelOverride ?? resumeModel`). */
 	model: string;
-	/** The resume prompt — the final positional, run as the model turn under `-p`. */
-	prompt: string;
-	/** The decider's `plan.launchArgs` (`["--approve"]` or `[]`). */
-	launchArgs?: readonly string[];
 }
 
 /**
- * Build the `pi` argv for a resume spawn. The prefix is `--mode json -p` (headless JSON
- * child, prompt-as-turn); then the resident posture; then
- * `[…ext args] --session <file> [--provider <p>] --model <m> <prompt>`.
+ * Build the `pi` flags for a VISIBLE resume, in the measured order.
  *
  * Invariants the gate pins:
- *   - v2-control carries `--entwurf-control` and NO `--no-extensions`, plus `-p` + prompt.
- *   - `explicitExtensionArgs` appears exactly once.
- *   - `launchArgs` is included before the suffix.
- *   - provider/model/prompt identity layout is fixed.
+ *   - `--entwurf-control` is FIRST: the resumed session must stand its control socket up, or
+ *     the transcript comes back with no address and the citizen is still unreachable.
+ *   - no `--mode`, no `-p`, no positional prompt — the window is interactive and no turn runs.
+ *   - `explicitExtensionArgs` appears exactly once, after the control flag and before
+ *     `--session`.
+ *   - provider is emitted only when recorded; `--model <m>` is the tail.
  */
 export function buildResumePiArgs(input: ResumePiArgsInput): string[] {
-	const args: string[] = ["--mode", "json", "-p"];
-
-	// Resident citizen: stand the control socket up (A1) and keep extensions loaded. The
-	// keep-alive the removed one-shot launcher had to avoid is precisely the goal here —
-	// the resumed session must stay addressable. `--approve`/launchArgs ride along.
-	args.push("--entwurf-control");
-	args.push(...(input.launchArgs ?? []));
-
-	// Suffix — the fixed identity layout.
+	const args: string[] = ["--entwurf-control"];
 	args.push(...input.explicitExtensionArgs);
 	args.push("--session", input.sessionFile);
 	if (input.provider) args.push("--provider", input.provider);
-	args.push("--model", input.model, input.prompt);
-
+	args.push("--model", input.model);
 	return args;
 }

package/pi-extensions/lib/entwurf-v2-contract-schema.ts

@@ -46,7 +46,7 @@ export const EntwurfV2InputSchema = Type.Object(
 		}),
 		intent: StringEnum(ENTWURF_INTENTS, {
 			description:
-				"caller's declared outcome contract (F1): fire-and-forget = ack only, owned-outcome = caller owns completion.",
+				"caller's declared outcome contract (F1). ONE member since the visible-first cut: fire-and-forget = ack only. The second, owned-outcome (caller owns completion), resumed a dormant citizen by launching a hidden background child and was withdrawn — a dormant citizen is currently unreachable by this verb.",
 		}),
 		mode: Type.Optional(
 			StringEnum(ENTWURF_V2_MODES, {