@junghanacs/entwurf 0.13.0 → 0.13.1

package/scripts/check-acp-sdk-surface.ts

@@ -4,23 +4,62 @@
 // the peer-resolution that makes the Claude ACP adapter satisfiable:
 //
 //   @agentclientprotocol/sdk              1.3.0    wire SDK (acp-bridge import source)
-//   @agentclientprotocol/claude-agent-acp 0.62.0   Claude adapter (spawn binary)
+//   @agentclientprotocol/claude-agent-acp 0.64.0   Claude adapter (spawn binary)
 //   @anthropic-ai/sdk                     0.100.1  peer-resolution pin ONLY (see below)
 //
-// 2026-07-27 bump 0.61.0 → 0.62.0: the adapter's own `dist/` is byte-identical
-// across the two releases; 0.62.0 moves only its declared deps
-// (claude-agent-sdk 0.3.217 → 0.3.219; its devDep anthropic sdk, which does not
-// reach us). So this bump is a dependency refresh that carries NO adapter-code
-// change — and specifically NOT a fix for the bundled-MCP readiness race
-// (ROADMAP 🔴): 0.62.0 adds no explicit readiness fence. Effective runtime
-// behavior is NOT claimed identical: the transitive SDK moved, and MCP startup
-// lives inside it, so timing may differ — what is established is only that no
-// new fence was added.
+// 2026-07-31 bump 0.63.0 → 0.64.0 — a ONE-FEATURE adapter release. Measured
+// against the upstream checkout (release commit 9cc5a09): the entire functional
+// delta is `src/elicitation.ts` +14 lines (commit d7a65ce), which stamps the
+// AskUserQuestion form's "Other" free-text field with a shared
+// `_meta._askUserQuestionCustomAnswer` marker so ACP clients can recognize a
+// custom-answer companion across Codex/Claude bridges. Published package:
+// unpackedSize 529,638 → 530,740 B, fileCount 24 → 24. Runtime deps are
+// IDENTICAL (`@agentclientprotocol/sdk` 1.3.0, `@anthropic-ai/claude-agent-sdk`
+// 0.3.220) — the upstream lock's `@modelcontextprotocol/sdk` 1.29.0 → 1.30.0 is
+// THEIR dev tree; our resolution stays 1.29.0 because our runtime dep set did
+// not move. Re-measured: the anthropic peer still resolves 0.100.1.
+//
+// Reachability is STRONGER than "off by default", and it is measured, not
+// assumed. `backend.ts` sends `clientCapabilities: {}` — a hardcoded literal with
+// no operator-config seam — so upstream computes `elicitationSupport.form =
+// false`. Two independent upstream gates then close the new marker off:
+// `acp-agent.ts:5358` disallows `AskUserQuestion` outright, and `:5449` composes
+// the final list by CONCATENATION (`[...userProvidedOptions.disallowedTools,
+// ...disallowedTools]`), so no operator `disallowedTools` can remove it; and the
+// form-elicitation emission branch at `:4558` is gated on the same flag. The only
+// lever is `clientCapabilities`, which entwurf does not expose to configuration —
+// so this marker cannot reach our wire without an entwurf SOURCE change. That is
+// the honest claim for THIS delta; do not generalize it to other axes.
+//
+// HISTORY — 2026-07-30 bump 0.62.0 → 0.63.0 — an ADAPTER-CODE release, not a dependency
+// refresh. Measured on the packed tarballs: 137,294 → 142,084 bytes, with
+// `dist/acp-agent.js`, `dist/tools.js` and the `dist/acp-agent.d.ts` surface all
+// moved. Three upstream fixes ride it (#923 denied-tool resolution, #916
+// tool_progress heartbeat keying, #917 Bash terminal metas keyed off the
+// announced tool_use id) plus claude-agent-sdk 0.3.219 → 0.3.220.
+//
+// Reachability onto OUR surface is narrower than that list, and is measured, not
+// assumed: `backend.ts` sends `clientCapabilities: {}`, and the adapter gates
+// terminal metas on `clientCapabilities?._meta?.["terminal_output"] === true`
+// and subagent transcript on the matching capability — so both stay off for
+// every backend we ship. What CAN still reach the wire is opt-in-free metadata
+// (`_meta.claudeCode.title` / `.subagent`) and #916's re-keyed heartbeats; the
+// mapper ignores those, so no visible state changes. Do not write this up as
+// "0.63.0 does not reach us" — write what each axis was measured to do.
+//
+// HISTORY — 2026-07-27 bump 0.61.0 → 0.62.0: that one WAS a pure dependency
+// refresh; the adapter's `dist/` was byte-identical across the two releases and
+// only its declared deps moved (claude-agent-sdk 0.3.217 → 0.3.219). It was
+// specifically NOT a fix for the bundled-MCP readiness race (ROADMAP 🔴), and
+// 0.63.0 adds no explicit readiness fence either. Effective runtime behavior is
+// NOT claimed identical across either bump: the transitive SDK moved both times,
+// and MCP startup lives inside it, so timing may differ — what is established is
+// only that no new fence was added.
 //
 // The anthropic SDK is NOT an API client / auth surface here. It is a direct
-// dep solely to satisfy @anthropic-ai/claude-agent-sdk@0.3.219's peer floor
-// (>=0.93.0 — re-measured at 0.3.219, unchanged from 0.3.217, so the 0.100.1
-// pin stands rather than rising mechanically); drop it and the tree resolves a stale 0.91.1 so the peer goes
+// dep solely to satisfy @anthropic-ai/claude-agent-sdk@0.3.220's peer floor
+// (>=0.93.0 — re-measured at 0.3.220, unchanged from 0.3.219 and 0.3.217, so the
+// 0.100.1 pin stands rather than rising mechanically); drop it and the tree resolves a stale 0.91.1 so the peer goes
 // unmet — a failure that would only surface at the first raw turn. The
 // lockfile proves the same shape. Source-level import / API-client
 // instantiation / credential use stays forbidden — asserted in layer (4).
@@ -54,7 +93,7 @@ const pkg = JSON.parse(read("package.json")) as { dependencies?: Record<string,
 const deps = pkg.dependencies ?? {};
 const PINS: Record<string, string> = {
 	"@agentclientprotocol/sdk": "1.3.0",
-	"@agentclientprotocol/claude-agent-acp": "0.62.0",
+	"@agentclientprotocol/claude-agent-acp": "0.64.0",
 	[ANTHROPIC_SDK]: "0.100.1",
 };
 for (const [name, ver] of Object.entries(PINS)) {
@@ -74,13 +113,13 @@ for (const [name, ver] of Object.entries(PINS)) {
 const lock = read("pnpm-lock.yaml");
 assert.match(
 	lock,
-	/@agentclientprotocol\/claude-agent-acp@0\.62\.0\(@anthropic-ai\/sdk@0\.100\.1/,
-	"pnpm-lock: claude-agent-acp@0.62.0 must peer-resolve @anthropic-ai/sdk@0.100.1 (peer-pin), not the stale 0.91.1",
+	/@agentclientprotocol\/claude-agent-acp@0\.64\.0\(@anthropic-ai\/sdk@0\.100\.1/,
+	"pnpm-lock: claude-agent-acp@0.64.0 must peer-resolve @anthropic-ai/sdk@0.100.1 (peer-pin), not the stale 0.91.1",
 );
 assert.match(
 	lock,
-	/@anthropic-ai\/claude-agent-sdk@0\.3\.219\(@anthropic-ai\/sdk@0\.100\.1/,
-	"pnpm-lock: claude-agent-sdk@0.3.219 must peer-resolve @anthropic-ai/sdk@0.100.1 — else its >=0.93.0 peer floor is unmet",
+	/@anthropic-ai\/claude-agent-sdk@0\.3\.220\(@anthropic-ai\/sdk@0\.100\.1/,
+	"pnpm-lock: claude-agent-sdk@0.3.220 must peer-resolve @anthropic-ai/sdk@0.100.1 — else its >=0.93.0 peer floor is unmet",
 );
 
 // ---------------------------------------------------------------------------
@@ -119,8 +158,8 @@ const casEntry = adapterRequire.resolve("@anthropic-ai/claude-agent-sdk");
 const casInfo = pkgInfoFromEntry(casEntry);
 assert.equal(
 	casInfo.version,
-	"0.3.219",
-	`@anthropic-ai/claude-agent-sdk must runtime-resolve to 0.3.219 from the adapter context (got ${casInfo.version})`,
+	"0.3.220",
+	`@anthropic-ai/claude-agent-sdk must runtime-resolve to 0.3.220 from the adapter context (got ${casInfo.version})`,
 );
 const casRequire = createRequire(resolve(casInfo.dir, "package.json"));
 const sdkEntry = casRequire.resolve(ANTHROPIC_SDK);
@@ -163,7 +202,7 @@ const mcpEntry = casRequire.resolve("@modelcontextprotocol/sdk/server/index.js")
 const mcpInfo = pkgInfoFromEntry(mcpEntry);
 assert.ok(
 	mcpInfo.version.startsWith("1.29."),
-	`@modelcontextprotocol/sdk must runtime-resolve to 1.29.x from the claude-agent-sdk context (got ${mcpInfo.version}) — claude-agent-sdk 0.3.219 declares a ^1.29.0 peer`,
+	`@modelcontextprotocol/sdk must runtime-resolve to 1.29.x from the claude-agent-sdk context (got ${mcpInfo.version}) — claude-agent-sdk 0.3.220 declares a ^1.29.0 peer`,
 );
 
 // ---------------------------------------------------------------------------

package/scripts/check-acp-stop-reason.ts

@@ -0,0 +1,342 @@
+// Deterministic gate for the ACP stop-reason contract (backend.ts + event-mapper.ts).
+//
+// WHAT THIS EXISTS TO STOP. `mapPromptStopReason` used to be a bare
+// `switch` returning a StopReason with `default: return "stop"`. The ACP terminal
+// set is closed — `@agentclientprotocol/sdk` 1.3.0 `schema/types.gen` declares
+// `end_turn | max_tokens | max_turn_requests | refusal | cancelled` — so that
+// default silently collapsed THREE distinct non-success outcomes into a clean
+// successful turn:
+//
+//   refusal            the model declined; the answer is absent
+//   max_turn_requests  the backend's per-turn budget ran out; the answer is cut
+//   <anything new>     a reason this build has never seen
+//
+// plus a fourth: a prompt result carrying NO stopReason at all. pi rendered all
+// four as a finished assistant message. pi 0.83 closed the identical hole in its
+// own providers (#7272 — unmapped terminal reasons surface as provider errors,
+// never successful stops) and added `AssistantMessage.rawStopReason` so the wire
+// value survives mapping; this gate pins our side of that same contract.
+//
+// A pure-function check of the mapper is NOT enough — the defect people actually
+// feel is "pi showed a truncated answer as done". So every cell is driven
+// BEHAVIORALLY through `streamAcpTurn` against a fake ACP connection, and each
+// asserts all four observable facts together:
+//
+//   (a) the emitted event KIND      done vs error
+//   (b) the emitted event REASON    stop / length / aborted / error
+//   (c) the final message stopReason
+//   (d) rawStopReason + errorMessage on that same final message
+//
+// SEED CLAIM (separate, and deliberately not folded into the cells above).
+// `createAcpStreamState` seeds `stopReason: "pending"` — pi 0.83's sentinel for
+// "no terminal reason observed yet". Seeding "stop" would pre-claim success for
+// the entire in-flight turn. That claim is asserted on the value returned by
+// `createAcpStreamState` DIRECTLY: `state.output` is a mutable object that every
+// terminal path overwrites, so reading it after a turn would only ever show the
+// terminal value and could never fail. Reading it late is how this assertion
+// would quietly stop testing anything.
+//
+// backend.ts imports its siblings with `.js` suffixes (the root/jiti runtime
+// convention), so — like check-acp-session-reuse — we tsc-emit the project and
+// import the COMPILED backend.js whose `.js` imports resolve to real siblings.
+
+import { strict as assert } from "node:assert";
+import { execFileSync } from "node:child_process";
+import { copyFileSync, mkdirSync, mkdtempSync, rmdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { Api, AssistantMessageEvent, Context, Model } from "@earendil-works/pi-ai";
+
+const sonnet = { id: "claude-sonnet-5" } as unknown as Model<Api>;
+
+type Stream = AsyncIterable<AssistantMessageEvent> & {
+	result: () => Promise<{ stopReason: string; errorMessage?: string }>;
+};
+
+async function collect(stream: Stream): Promise<AssistantMessageEvent[]> {
+	const events: AssistantMessageEvent[] = [];
+	for await (const ev of stream) events.push(ev);
+	return events;
+}
+
+function makeFakeChild() {
+	const pipe = () => ({ destroy() {}, unref() {} });
+	return {
+		pid: undefined as number | undefined,
+		exitCode: null as number | null,
+		signalCode: null as NodeJS.Signals | null,
+		stdin: pipe(),
+		stdout: pipe(),
+		stderr: { on() {}, destroy() {}, unref() {} },
+		kill() {
+			return true;
+		},
+		unref() {},
+		once() {},
+	};
+}
+
+const EMPTY_MCP_HASH = "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945";
+const DEFAULT_RESOLVED_CONFIG: any = {
+	settingSources: [],
+	strictMcpConfig: true,
+	showToolNotifications: true,
+	mcpServers: [],
+	mcpServersHash: EMPTY_MCP_HASH,
+	tools: ["Read"],
+	skillPlugins: [],
+	permissionAllow: ["Read(*)"],
+	disallowedTools: [],
+};
+
+/**
+ * A harness whose fake ACP `prompt` resolves with EXACTLY the terminal shape the
+ * cell is about. `wireReason === null` models a result object with no stopReason
+ * key at all (the "absent" cell) rather than a literal `undefined` value.
+ */
+function makeHarness(recordDir: string, wireReason: string | null) {
+	return {
+		resolveLaunch: () => ({ command: "node", args: ["fake"] }),
+		ensureOverlay: () => {},
+		spawnChild: () => makeFakeChild(),
+		createConnection: (_child: any, handlers: any) => ({
+			initialize: async () => ({ agentCapabilities: {} }),
+			newSession: async () => ({ sessionId: "ACP-1" }),
+			setSessionConfigOption: async () => ({}),
+			prompt: async ({ sessionId }: any) => {
+				await handlers.sessionUpdate({
+					update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "PARTIAL" } },
+					sessionId,
+				});
+				return wireReason === null ? {} : { stopReason: wireReason };
+			},
+		}),
+		lifecyclePolicy: () => "process-scoped",
+		loadConfig: () => DEFAULT_RESOLVED_CONFIG,
+		now: () => "2026-07-30T00:00:00Z",
+		sessionDir: recordDir,
+	};
+}
+
+const TMP_EMIT = ".tmp-verify/acp-stop-reason";
+rmSync(TMP_EMIT, { recursive: true, force: true });
+const recordDir = mkdtempSync(resolve(tmpdir(), "acp-stop-rec-"));
+
+/**
+ * One driven turn, described by everything an operator could observe.
+ *
+ * `claim` is the qualification token this cell's SEALING assertions carry. The
+ * mutant harness does not accept "the gate went red" — it requires the gate to
+ * go red *at the token of the claim under test*, so a cell that guards a claim
+ * must print that claim's `[QK:…]` in the very assertion the mutant trips.
+ * Cells whose sealing no mutant targets carry no token.
+ */
+type Cell = {
+	wire: string | null;
+	kind: "done" | "error";
+	reason: string;
+	stopReason: string;
+	rawStopReason?: string;
+	/** Substring the errorMessage must carry; absent = there must be no errorMessage. */
+	errorContains?: string;
+	claim?: string;
+	why: string;
+};
+
+/** Qualification token for the claim that the raw ACP reason survives mapping. */
+const RAW_CLAIM = "[QK:STOP-RAW-PRESERVED]";
+
+/** Prefix an assertion message with a claim token when the cell guards one. */
+function tag(cell: Cell, message: string): string {
+	return cell.claim ? `${cell.claim} ${message}` : message;
+}
+
+const CELLS: Cell[] = [
+	{
+		wire: "end_turn",
+		kind: "done",
+		reason: "stop",
+		stopReason: "stop",
+		rawStopReason: "end_turn",
+		why: "a normal completion is the only clean success",
+	},
+	{
+		wire: "max_tokens",
+		kind: "done",
+		reason: "length",
+		stopReason: "length",
+		rawStopReason: "max_tokens",
+		why: "output-cap truncation is honestly reported as length, not stop",
+	},
+	{
+		wire: "cancelled",
+		kind: "error",
+		reason: "aborted",
+		stopReason: "aborted",
+		rawStopReason: "cancelled",
+		why: "a cancelled turn is an abort, never a done",
+	},
+	{
+		wire: "refusal",
+		kind: "error",
+		reason: "error",
+		stopReason: "error",
+		rawStopReason: "refusal",
+		errorContains: "refusal",
+		claim: "[QK:STOP-REFUSAL-NOT-SUCCESS]",
+		why: "a model refusal has no answer to show — reporting it as done is the original defect",
+	},
+	{
+		wire: "max_turn_requests",
+		kind: "error",
+		reason: "error",
+		stopReason: "error",
+		rawStopReason: "max_turn_requests",
+		errorContains: "max_turn_requests",
+		claim: "[QK:STOP-TURNBUDGET-NOT-SUCCESS]",
+		why: "an exhausted per-turn request budget leaves the answer cut short",
+	},
+	{
+		wire: "teapot",
+		kind: "error",
+		reason: "error",
+		stopReason: "error",
+		rawStopReason: "teapot",
+		errorContains: "teapot",
+		claim: "[QK:STOP-UNKNOWN-NOT-SUCCESS]",
+		why: "a reason this build has never seen must fail loud, carrying the raw value",
+	},
+	{
+		wire: null,
+		kind: "error",
+		reason: "error",
+		stopReason: "error",
+		errorContains: "without a stop reason",
+		claim: "[QK:STOP-ABSENT-NOT-SUCCESS]",
+		why: "a prompt result with no stopReason at all is not a successful turn",
+	},
+];
+
+try {
+	execFileSync("node_modules/.bin/tsc", ["--outDir", TMP_EMIT, "--rootDir", ".", "--noEmit", "false"], {
+		stdio: "pipe",
+	});
+	const promptsOut = resolve(TMP_EMIT, "pi-extensions/lib/acp/prompts");
+	mkdirSync(promptsOut, { recursive: true });
+	copyFileSync("pi-extensions/lib/acp/prompts/engraving.md", resolve(promptsOut, "engraving.md"));
+
+	const backendUrl = pathToFileURL(resolve(TMP_EMIT, "pi-extensions/lib/acp/backend.js")).href;
+	const eventUrl = pathToFileURL(resolve(TMP_EMIT, "pi-extensions/lib/acp/event-mapper.js")).href;
+	const backend = (await import(backendUrl)) as any;
+	const eventMod = (await import(eventUrl)) as any;
+
+	// ----------------------------------------------------------------------
+	// (1) SEED — asserted on the freshly returned state, never after a turn.
+	// ----------------------------------------------------------------------
+	{
+		const seeded = eventMod.createAcpStreamState(
+			{ push() {}, end() {} },
+			{
+				api: "entwurf",
+				provider: "entwurf",
+				model: sonnet.id,
+			},
+		);
+		assert.equal(
+			seeded.output.stopReason,
+			"pending",
+			"[QK:STOP-PENDING-SEED] a freshly created ACP stream state must seed stopReason 'pending' (pi 0.83's " +
+				"no-terminal-reason-yet sentinel) — seeding 'stop' pre-claims success for the whole in-flight turn",
+		);
+	}
+
+	// ----------------------------------------------------------------------
+	// (2) The seven terminal cells, driven end to end. Each cell's qualification
+	//     token lives in its `claim` field above — exactly one occurrence per
+	//     token in this file, which is what the mutant manifest requires.
+	// ----------------------------------------------------------------------
+	for (const cell of CELLS) {
+		const label = cell.wire === null ? "<absent>" : cell.wire;
+		const events = await collect(
+			backend.streamAcpTurn(
+				sonnet,
+				{ messages: [{ role: "user", content: `drive ${label}`, timestamp: 0 }] } as Context,
+				{ sessionId: `stop-${label}` },
+				makeHarness(recordDir, cell.wire),
+			) as Stream,
+		);
+
+		const done = events.find((e) => e.type === "done") as any;
+		const errored = events.find((e) => e.type === "error") as any;
+
+		if (cell.kind === "done") {
+			assert.ok(done, tag(cell, `[${label}] must seal as a done event — ${cell.why}`));
+			assert.ok(!errored, tag(cell, `[${label}] must not also emit an error event`));
+		} else {
+			assert.ok(errored, tag(cell, `[${label}] must seal as an ERROR event, not a done — ${cell.why}`));
+			assert.ok(
+				!done,
+				tag(cell, `[${label}] must NOT emit a done event — that is exactly the collapse this gate forbids`),
+			);
+		}
+
+		const sealed = cell.kind === "done" ? done : errored;
+		assert.equal(sealed.reason, cell.reason, tag(cell, `[${label}] sealed event reason must be "${cell.reason}"`));
+
+		const final = cell.kind === "done" ? sealed.message : sealed.error;
+		assert.equal(
+			final.stopReason,
+			cell.stopReason,
+			tag(cell, `[${label}] final message stopReason must be "${cell.stopReason}"`),
+		);
+		// Deliberately carries no claim token: the seed mutant is caught by the
+		// direct assertion in (1), and this one is the standing guarantee that no
+		// terminal path ever leaks the sentinel out to a consumer.
+		assert.notEqual(
+			final.stopReason,
+			"pending",
+			`[${label}] the seed must never survive a sealed turn — every terminal path overwrites it`,
+		);
+		assert.equal(
+			final.rawStopReason,
+			cell.rawStopReason,
+			`${RAW_CLAIM} [${label}] rawStopReason must preserve the wire value (${cell.rawStopReason ?? "absent"}) so ` +
+				"the raw ACP reason survives the mapping",
+		);
+
+		if (cell.errorContains) {
+			assert.ok(
+				typeof final.errorMessage === "string" && final.errorMessage.includes(cell.errorContains),
+				tag(
+					cell,
+					`[${label}] errorMessage must name the reason (expected to contain "${cell.errorContains}", got ` +
+						`${JSON.stringify(final.errorMessage)})`,
+				),
+			);
+		} else {
+			assert.equal(final.errorMessage, undefined, tag(cell, `[${label}] a clean end must not carry an errorMessage`));
+		}
+	}
+} finally {
+	rmSync(TMP_EMIT, { recursive: true, force: true });
+	try {
+		// The qualification harness's work-surface hash walks ignored paths too, so
+		// a leftover EMPTY parent dir reads as IMPURE tree drift even though git
+		// porcelain is clean. Remove it when empty; a concurrent sibling gate's
+		// emit keeps it alive and this rmdir simply fails.
+		rmdirSync(".tmp-verify");
+	} catch {
+		// non-empty or already gone — fine either way
+	}
+	rmSync(recordDir, { recursive: true, force: true });
+}
+
+console.log(
+	"[check-acp-stop-reason] ok — the ACP terminal set is driven end to end through streamAcpTurn: end_turn→done/stop " +
+		"and max_tokens→done/length are the only clean seals; cancelled→error/aborted; refusal, max_turn_requests, an " +
+		"unrecognized reason, and an ABSENT reason each seal as an ERROR event with no done (the collapse-to-stop defect " +
+		"pi 0.83 #7272 closed on its own providers); rawStopReason preserves the wire value on every cell that carried " +
+		"one; and the stream state seeds 'pending' (asserted on the fresh state, not after a turn) so no in-flight turn " +
+		"pre-claims success",
+);

package/scripts/check-entwurf-v2-surface.ts

@@ -162,6 +162,45 @@ function assertRailSemantics(tag: string, longDescRaw: string, intentDescRaw: st
  * parameter marker in the long-description slice: if the slice ever swallows the schema
  * again, this fails instead of silently satisfying the schema's own text.
  */
+/**
+ * HOST TRUNCATION CAP. Measured 2026-07-30 on both Claude ACP and stock Claude Code: a tool
+ * description longer than this is cut mid-sentence and the tail is replaced with `… [truncated]`.
+ * The shipped entwurf_v2 text was 4,022 chars, so everything from the INTENT contract onward —
+ * the reject taxonomy, the three-valued probe, the lock scope — never reached the model that had
+ * to choose an intent. Every other assertion in this file checks that a sentence is PRESENT in
+ * source; none of them can see that the host threw half of it away. This one can.
+ *
+ * Judged on `modelText` (the rendered string), not the source slice: pi-native wraps inside one
+ * template literal and the MCP surface `+`-concatenates, so only the normalized text has the
+ * length the host actually measures.
+ */
+const HOST_DESCRIPTION_CAP = 2048;
+
+/**
+ * The string the HOST measures, recovered from either surface's source scaffolding: drop the
+ * `description:` key and the outer template-literal / string-literal fence, and unescape `\"`.
+ * Counting the raw slice instead would charge the text for punctuation the model never sees —
+ * and the two surfaces carry DIFFERENT punctuation, so the cap would mean two different things.
+ */
+function renderedDescription(raw: string): string {
+	const flat = modelText(raw);
+	// Anchor on the description's own first word rather than on scaffolding: the two surfaces put
+	// DIFFERENT preludes in front of it (the MCP slice starts at the tool name), and counting those
+	// would report a number the host never measures — a cap gate that cites the wrong length gets
+	// quoted as if it were the real one.
+	const from = flat.indexOf("CANONICAL");
+	return (from >= 0 ? flat.slice(from) : flat).replace(/[`"],?$/, "").replace(/\\"/g, '"');
+}
+
+function assertDescriptionFitsHostCap(tag: string, longDescRaw: string): void {
+	const rendered = renderedDescription(longDescRaw);
+	ok(
+		`${tag} — long description fits the host's ${HOST_DESCRIPTION_CAP}-char cap (${rendered.length}) ` +
+			"[QK:V2SURF-DESC-FITS-HOST-CAP]",
+		rendered.length <= HOST_DESCRIPTION_CAP,
+	);
+}
+
 function assertLongDescExcludesParams(tag: string, longDesc: string, markers: readonly string[]): void {
 	for (const marker of markers) {
 		ok(`${tag} — long description slice excludes the \`${marker}\` parameter marker`, !longDesc.includes(marker));
@@ -551,6 +590,7 @@ async function main(): Promise<void> {
 		]);
 		const piModeDesc = sliceDescription(piV2Block, "mode: Type.Optional(", "wants_reply:");
 		assertRailSemantics("4: pi-native", piLongDesc, piIntentDesc, piModeDesc);
+		assertDescriptionFitsHostCap("4: pi-native", piLongDesc);
 	}
 
 	// ── 5: MCP bridge wiring guard ────────────────────────────────────────────
@@ -635,6 +675,7 @@ async function main(): Promise<void> {
 		assertLongDescExcludesParams("5: MCP", mcpLongDesc, ["target: z", "intent: z", "mode: z", "wants_reply: z"]);
 		const mcpModeDesc = sliceDescription(v2Block, "mode: z", "wants_reply: z");
 		assertRailSemantics("5: MCP", mcpLongDesc, mcpIntentDesc, mcpModeDesc);
+		assertDescriptionFitsHostCap("5: MCP", mcpLongDesc);
 
 		// entwurf_peers is a FACT surface, but it still told the model what `unsupported` means —
 		// and "does NOT mean unreachable" is false for a record whose backend has no adapter on

package/scripts/check-gate-qualification.ts

@@ -718,13 +718,16 @@ console.log(`\n[gate-qualification] self-test: ${passed} checks passed`);
 	// manifest lost in a merge must name itself here — "0/0 killed" is not a pass.
 	// Extend this inventory and the manifests TOGETHER, never silently.
 	const EXPECTED_LANE_MUTANTS: Record<string, number> = {
-		"acp-augment": 2,
+		"acp-augment": 10,
 		"acp-cortex": 12,
+		"acp-prompt-lifecycle": 8,
+		"acp-stop-reason": 6,
 		"agy-permission": 6,
 		"meta-identity": 1,
-		"probe-ordering": 83,
+		"probe-ordering": 85,
+		"release-gate": 8,
 		"self-address": 3,
-		"v2-surface": 4,
+		"v2-surface": 5,
 	};
 	const laneTally: Record<string, number> = {};
 	for (const man of manifests) laneTally[man.lane] = (laneTally[man.lane] ?? 0) + man.mutants.length;

package/scripts/check-probe-ordering.ts

@@ -94,6 +94,7 @@ import { terminateChild } from "./lib/acp-child-cleanup.ts";
 import {
 	driveProbeTurn,
 	PROBE_PHASE_TIMEOUTS,
+	PROBE_PROMPT_OBSERVATION_MS,
 	type ProbeAdapterSeam,
 	type ProbeMcpEnricher,
 	ProbePhaseError,
@@ -290,7 +291,7 @@ function makeRecordingConnection(calls: RecordedCall[]): AcpConnectionLike {
 		`set-model start/end are marked between newSession end and prompt start (got ${eventOrder.join(",")})`,
 	);
 
-	// §9-4 shape: an undefined session meta omits the `_meta` KEY entirely.
+	// Carrier-less shape: an undefined session meta omits the `_meta` KEY entirely.
 	const calls2: RecordedCall[] = [];
 	await driveProbeTurn(makeRecordingConnection(calls2), {
 		cwd: "/scratch/gate2",
@@ -305,7 +306,7 @@ function makeRecordingConnection(calls: RecordedCall[]): AcpConnectionLike {
 	});
 	assert.ok(
 		!Object.hasOwn(calls2.find((c) => c.method === "newSession")?.params as object, "_meta"),
-		"undefined session meta omits the _meta KEY entirely (§9-4)",
+		"undefined session meta omits the _meta KEY entirely (carrier-less shape)",
 	);
 
 	// --- production source pins ---------------------------------------------
@@ -319,15 +320,37 @@ function makeRecordingConnection(calls: RecordedCall[]): AcpConnectionLike {
 			initializeMs: PROBE_PHASE_TIMEOUTS.initializeMs,
 			newSessionMs: PROBE_PHASE_TIMEOUTS.newSessionMs,
 			setModelMs: PROBE_PHASE_TIMEOUTS.setModelMs,
-			promptMs: PROBE_PHASE_TIMEOUTS.promptMs,
 		},
 		{
 			initializeMs: timeoutOf("INITIALIZE_TIMEOUT_MS"),
 			newSessionMs: timeoutOf("NEW_SESSION_TIMEOUT_MS"),
 			setModelMs: timeoutOf("SET_MODEL_TIMEOUT_MS"),
-			promptMs: timeoutOf("PROMPT_TIMEOUT_MS"),
 		},
-		"probe phase timeouts EQUAL backend.ts's — D is only readable against production boundaries [QK:PROBE-TIMEOUTS-MATCH-PRODUCTION]",
+		"probe BOOTSTRAP timeouts EQUAL backend.ts's — a bootstrap-phase D is only readable against production " +
+			"boundaries [QK:PROBE-BOOTSTRAP-TIMEOUTS-MATCH-PRODUCTION]",
+	);
+
+	// --- the prompt phase has NO production boundary to match --------------
+	//
+	// backend.ts ends a prompt on lifecycle events only. The probe still needs a
+	// bounded observation horizon so a measurement RUN cannot hang forever, but
+	// that horizon is the harness's own: pinning it to a production number (or
+	// letting production grow one back) would make the probe report a
+	// harness-invented cutoff as if it were the turn contract.
+	const promptCutoffTraces = [/\bPROMPT_TIMEOUT_MS\b/, /withTimeout\(\s*\n?\s*"prompt"/].filter((re) =>
+		re.test(BACKEND_SRC),
+	);
+	assert.equal(
+		promptCutoffTraces.length,
+		0,
+		"[QK:NO-PRODUCTION-PROMPT-CUTOFF] backend.ts carries NO prompt wall-clock — neither a PROMPT_TIMEOUT_MS constant " +
+			'nor a withTimeout("prompt", …) race. A running turn is not a failed turn for being long, and the old 600s ' +
+			`cutoff also fed pi's transient-retry dictionary. Found: ${promptCutoffTraces.join(", ")}`,
+	);
+	assert.ok(
+		PROBE_PROMPT_OBSERVATION_MS > 0 && !("promptMs" in PROBE_PHASE_TIMEOUTS),
+		"[QK:PROMPT-HORIZON-NOT-PRODUCTION] the prompt horizon lives OUTSIDE the production-pinned bootstrap set — it is " +
+			"the harness's own observation bound, and folding it back in would report a harness number as the turn contract",
 	);
 
 	const idx = (needle: string): number => {
@@ -338,11 +361,19 @@ function makeRecordingConnection(calls: RecordedCall[]): AcpConnectionLike {
 	const iInit = idx("connection.initialize({");
 	const iNew = idx("connection.newSession(newSessionArgs)");
 	const iEnforce = idx("adapter.enforceModel({");
-	const iPrompt = BACKEND_SRC.indexOf("connection.prompt({", iEnforce);
+	// The prompt no longer sits inline: runNewTurn hands the wire call to
+	// awaitAcpPromptTurn (the lifecycle-bounded driver), so the ordering pin
+	// follows the dispatch, and the driver's own `session.connection.prompt(...)`
+	// is the single place the wire call lives.
+	const iPrompt = BACKEND_SRC.indexOf("await awaitAcpPromptTurn(", iEnforce);
 	assert.ok(
 		iInit < iNew && iNew < iEnforce && iEnforce < iPrompt && iPrompt !== -1,
 		"backend.ts runNewTurn keeps initialize → newSession → enforceModel → prompt; the probe mirrors THIS sequence",
 	);
+	assert.ok(
+		BACKEND_SRC.includes("await Promise.race([session.connection.prompt(promptArgs), lifecycle])"),
+		"the prompt driver races the wire call against LIFECYCLE endings only — the probe mirrors that same wire call",
+	);
 	assert.ok(
 		BACKEND_SRC.includes('clientInfo: { name: "entwurf", version: "s2d" }'),
 		"backend.ts still sends the clientInfo the probe mirrors",
@@ -490,7 +521,8 @@ function makeRecordingConnection(calls: RecordedCall[]): AcpConnectionLike {
 		await driveProbeTurn(makeRecordingConnection(calls), {
 			...base,
 			adapter: { buildSessionMeta: () => undefined, enforceModel: () => new Promise<never>(() => {}) },
-			timeouts: { initializeMs: 1000, newSessionMs: 1000, setModelMs: 50, promptMs: 1000 },
+			timeouts: { initializeMs: 1000, newSessionMs: 1000, setModelMs: 50 },
+			promptObservationMs: 1000,
 		});
 		assert.fail("hung set-model must time the turn out");
 	} catch (err) {