@junghanacs/entwurf 0.35.0 → 0.35.1

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

@@ -58,6 +58,24 @@
  * vanished signal, a failed ring, a rejected admission or close retires the doorbell — watch
  * closed, our own marker removed, the reason kept by name — and nothing retries it.
  *
+ * WITHDRAW (#140). Each notice is a native `followUp`, placed one per run; a read drains EVERY
+ * unread body. So after a read the notices still queued for that mail would each cost a turn and an
+ * empty read. The contact keeps the native `Submission` handle of each notice it admitted, with the
+ * `.msg` names that notice announced, only while that mail is unread. After every
+ * `entwurf_inbox_read` attempt — whatever its garden id or outcome — it lists its OWN mailbox once
+ * and withdraws, through the native `Submission.abort` and the read's own invocation Context, each
+ * notice none of whose names is still `.msg.delivered`. That per-notice file predicate is the only
+ * authority: no garden-id guard, no requestId lookup, no queue of our own, no rewritten text. A placed
+ * or settled notice answers so and is let go; a withdraw that fails is let go too, named in one
+ * stderr line and on the receiver report, never retried and never retiring the doorbell; a mailbox
+ * that cannot be listed proves nothing absent, so every notice is kept and that is named the same
+ * way. The read's own result or error is returned unchanged — no diagnostic joins it. Ring passes
+ * and reads share one gate: a read waits for an admission in flight (else its drain could beat the
+ * handle it must withdraw), and an arrival during a read is rung once the read lets go. The count
+ * in a notice is its admission-time snapshot. Not covered: notices admitted before a restart (no
+ * handle), mail drained by another process (until this contact's next read), and operator abort,
+ * which natively withdraws queued notices while their mail stays unread.
+ *
  * VISIBLE IDENTITY (a static projection). `withGardenIdentity` hands the native TUI a view whose
  * every conversation label carries this citizen's garden id, so the footer the TUI keeps on screen
  * names the citizen; the bootstrap composes it only after birth succeeded. That is evidence of what
@@ -79,7 +97,8 @@
  *
  * NOT HERE: crash-safe receive. `entwurf_inbox_read` archives a body before the durable tool
  * result commits, so a crash between the two loses that body to the model; recovery settles the
- * call as interrupted and no doorbell rings again. No resume.
+ * call as interrupted and no doorbell rings again. A drain that fails part-way has archived the
+ * bodies before it (the bridge returns its error), and those too never reach the model. No resume.
  */
 
 import * as fs from "node:fs";
@@ -530,9 +549,14 @@ export interface DurableDoorbellDraft {
 	readonly requestId: string;
 }
 
-/** The part of the native `Submission` handle a doorbell records; admission is not completion. */
+/** What the native `Submission.abort` answers: only a still-queued input is withdrawn. */
+export type DurableWithdrawal = "aborted" | "already_placed" | "settled";
+
+/** The part of the native `Submission` handle a doorbell keeps; admission is not completion. */
 export interface DurableAdmittedSubmission {
 	readonly id: unknown;
+	/** Native `Submission.abort(context)`, handed the read's own invocation Context unchanged. */
+	abort(context: DurableCallContext | undefined): Promise<DurableWithdrawal>;
 }
 
 /** The overlay's `OpenDurableResult.submitToRoot`. */
@@ -562,21 +586,40 @@ export interface PiDurableDoorbellAdmission {
 	unread: number;
 }
 
+/**
+ * The LATEST notice withdrawal that failed. `inspection-failed`: the own mailbox could not be listed,
+ * so no notice was judged and every one is kept. `abort-failed`: the native withdraw of the notice
+ * named by `requestId` rejected; that notice is let go, not retried.
+ */
+export interface PiDurableWithdrawalFailure {
+	reason: "inspection-failed" | "abort-failed";
+	requestId?: string;
+	detail: string;
+}
+
 /**
  * The receiver's diagnostic. `admissions` is the LATEST successful admission only — an empty array
  * before the first ring, then exactly one entry, replaced by each later success; a retirement keeps
  * the last one. It is a diagnostic, not a history: it never grows with the host's lifetime, and its
  * length is no count of how often the root was asked (the root's own submissions are that record).
+ * `withdrawalFailure`, present only once a withdrawal failed, is likewise the latest one only.
  */
 export type PiDurableReceiverReport =
 	| { status: "off" }
-	| { status: "armed"; gardenId: string; markerPath: string; admissions: PiDurableDoorbellAdmission[] }
+	| {
+			status: "armed";
+			gardenId: string;
+			markerPath: string;
+			admissions: PiDurableDoorbellAdmission[];
+			withdrawalFailure?: PiDurableWithdrawalFailure;
+	  }
 	| {
 			status: "retired";
 			gardenId: string;
 			reason: PiDurableReceiverRetirement;
 			detail: string;
 			admissions: PiDurableDoorbellAdmission[];
+			withdrawalFailure?: PiDurableWithdrawalFailure;
 	  };
 
 export interface PiDurableAttachment {
@@ -641,6 +684,13 @@ interface ArmedDoorbell {
 	submitToRoot: DurableSubmitToRoot;
 }
 
+/** One admitted notice: its native handle and the `.msg` names it announced. */
+interface HeldNotice {
+	readonly requestId: string;
+	readonly fresh: readonly string[];
+	readonly submission: DurableAdmittedSubmission;
+}
+
 const TOOL_DESCRIPTIONS: Record<PiDurableToolName, string> = {
 	entwurf_self:
 		"Return this durable host's garden identity envelope (sessionId = garden id, agentId, cwd, replyable, rail) " +
@@ -730,7 +780,8 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				throw new Error(`${name} arguments must be an object`);
 			}
 			const client = await waitReady(context?.abortSignal);
-			const result = await client.callTool(name, (args ?? {}) as Record<string, unknown>, context?.abortSignal);
+			const call = () => client.callTool(name, (args ?? {}) as Record<string, unknown>, context?.abortSignal);
+			const result = name === "entwurf_inbox_read" ? await readInbox(call, context) : await call();
 			if (result.isError) throw new Error(result.text || `${name} failed`);
 			return { content: [{ type: "text", text: result.text }] };
 		},
@@ -745,8 +796,34 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 	let doorbell: ArmedDoorbell | null = null;
 	let report: PiDurableReceiverReport = { status: "off" };
 	const admissions: PiDurableDoorbellAdmission[] = [];
-	let ringing = false;
+	/** The armed mailbox, kept past a retirement so notices admitted before it can still be judged. */
+	let inbox: string | null = null;
+	/** Every admitted notice still owed a withdraw judgement, oldest first. */
+	const notices: HeldNotice[] = [];
+	let withdrawalFailure: PiDurableWithdrawalFailure | undefined;
+	// One gate for ring passes and inbox reads; `pending` is a signal that landed while it was held.
+	let gated = false;
 	let pending = false;
+	const gateWaiters: (() => void)[] = [];
+
+	const enterGate = (): Promise<void> => {
+		if (!gated) {
+			gated = true;
+			return Promise.resolve();
+		}
+		return new Promise<void>((resolve) => gateWaiters.push(resolve));
+	};
+
+	/** Hand the gate to the next waiting read, else open it — and ring once for a signal that landed meanwhile. */
+	const leaveGate = (): void => {
+		const next = gateWaiters.shift();
+		if (next !== undefined) {
+			next();
+			return;
+		}
+		gated = false;
+		if (pending) void ring("signal");
+	};
 
 	/**
 	 * Give the doorbell back: close the watch and remove the marker, in one step, because a
@@ -791,19 +868,19 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 	/**
 	 * One contract with the other self-fetch doorbells: a fresh `*.msg` is the trigger, it is
 	 * stamped `.msg.delivered` before the announce, and the announced count is every
-	 * `.msg.delivered`. Events that land while an admission is in flight coalesce into one more
-	 * pass. A failed pass retires the doorbell; it is not retried. Only a fresh `.msg` rings —
-	 * the startup pass included — so a `.msg.delivered` left undrained by an earlier host is not
-	 * announced again on its own; it shows only in the count of the next fresh arrival.
+	 * `.msg.delivered`. Events that land while an admission or an inbox read holds the gate coalesce
+	 * into one more pass. A failed pass retires the doorbell; it is not retried. Only a fresh `.msg`
+	 * rings — the startup pass included — so a `.msg.delivered` left undrained by an earlier host is
+	 * not announced again on its own; it shows only in the count of the next fresh arrival.
 	 */
 	const ring = async (why: PiDurableDoorbellAdmission["why"]): Promise<void> => {
 		const armed = doorbell;
 		if (armed === null) return;
-		if (ringing) {
+		if (gated) {
 			pending = true;
 			return;
 		}
-		ringing = true;
+		gated = true;
 		try {
 			do {
 				pending = false;
@@ -836,11 +913,71 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				}
 				// Latest only: the diagnostic names the LAST success and never grows with the host's lifetime.
 				admissions.splice(0, admissions.length, { why, requestId, submissionId: submission.id, fresh, unread });
+				notices.push({ requestId, fresh, submission });
 			} while (pending && doorbell === armed);
 		} catch (error) {
 			retire("doorbell-failed", describeError(error));
 		} finally {
-			ringing = false;
+			leaveGate();
+		}
+	};
+
+	/**
+	 * One named stderr line per failed withdrawal — stderr ALWAYS, as `entwurf-control` does, since
+	 * nothing in the native app reads the receiver report — and the report keeps the latest one.
+	 */
+	const noteWithdrawalFailure = (failure: PiDurableWithdrawalFailure): void => {
+		withdrawalFailure = failure;
+		const subject = failure.requestId === undefined ? "" : ` ${failure.requestId}`;
+		const detail = failure.detail.replace(/\s+/g, " ");
+		process.stderr.write(`[entwurf pi-durable] notice withdrawal ${failure.reason}${subject}: ${detail}\n`);
+	};
+
+	/**
+	 * Withdraw every held notice none of whose announced `.msg` names is still `.msg.delivered` in the
+	 * armed mailbox, listed once. A mailbox that cannot be listed proves nothing absent: every notice
+	 * is kept and that is named. A judged notice is let go whatever the native withdraw answers — or
+	 * when it rejects, which is named and never retried — so no handle outlives its mail by more
+	 * than one read. Never throws: the read's own answer is what the caller gets.
+	 */
+	const withdrawDrained = async (context: DurableCallContext | undefined): Promise<void> => {
+		if (inbox === null || notices.length === 0) return;
+		let unread: Set<string>;
+		try {
+			unread = new Set(fs.readdirSync(inbox).filter((name) => name.endsWith(".msg.delivered")));
+		} catch (error) {
+			noteWithdrawalFailure({ reason: "inspection-failed", detail: `${inbox}: ${describeError(error)}` });
+			return;
+		}
+		for (const notice of [...notices]) {
+			if (notice.fresh.some((name) => unread.has(`${name}.delivered`))) continue;
+			notices.splice(notices.indexOf(notice), 1);
+			try {
+				await notice.submission.abort(context);
+			} catch (error) {
+				noteWithdrawalFailure({ reason: "abort-failed", requestId: notice.requestId, detail: describeError(error) });
+			}
+		}
+	};
+
+	/**
+	 * An inbox read under the doorbell's gate, then the withdrawal its drain made due — after a
+	 * failed read too, whose partial drain may already have archived mail. The bridge's own answer,
+	 * result or rejection, is returned unchanged.
+	 */
+	const readInbox = async (
+		call: () => Promise<BridgeCallResult>,
+		context: DurableCallContext | undefined,
+	): Promise<BridgeCallResult> => {
+		await enterGate();
+		try {
+			return await call();
+		} finally {
+			try {
+				await withdrawDrained(context);
+			} finally {
+				leaveGate();
+			}
 		}
 	};
 
@@ -893,6 +1030,7 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				receiversDir: roots.receiversDir,
 			});
 			doorbell = { gardenId, ownerPid, mailbox, signal, markerPath, watcher, submitToRoot };
+			inbox = mailbox;
 			report = { status: "armed", gardenId, markerPath, admissions };
 			return markerPath;
 		} catch (error) {
@@ -1011,13 +1149,15 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 			settleFailed(describeError(error));
 		},
 		receiver() {
-			return report;
+			return withdrawalFailure === undefined || report.status === "off" ? report : { ...report, withdrawalFailure };
 		},
 		async close() {
 			const previous = state;
 			settleFailed("the contact closed before attach completed");
 			state = { kind: "closed" };
 			const client = previous.kind === "ready" ? previous.client : undefined;
+			// Queued notices stay native (a continued session places them); this contact judges no more.
+			notices.length = 0;
 			await closeAll(disarmOnClose, async () => {
 				await client?.close();
 			});

package/run.sh

@@ -2,10 +2,10 @@
 #
 # Model id convention (see AGENTS.md Hard Rule #1):
 #   - User-facing examples use the qualified form `entwurf/<backend-model>`
-#     (e.g. `entwurf/claude-sonnet-5`); the prefix routes to this provider
+#     (e.g. `entwurf/claude-sonnet-5-5`); the prefix routes to this provider
 #     so `--provider` is redundant and is dropped in docs.
 #   - Smoke helpers that feed `ensureBridgeSession({modelId})` directly (cancel,
-#     model-switch) pass BARE backend ids (`claude-sonnet-5`, `gpt-5.4`)
+#     model-switch) pass BARE backend ids (`claude-sonnet-5-5`, `gpt-5.4`)
 #     because the bridge library contract is bare. Smoke helpers that invoke pi
 #     via the CLI still pin `--provider entwurf` and can accept either
 #     bare or qualified model, but we keep bare here to match the bridge-level
@@ -32,7 +32,7 @@ TARGET_PROJECT_DIR=${2:-$PROJECT_DIR_DEFAULT}
 # and install path against the same scope for traceability.
 PACKAGE_NAME="@junghanacs/entwurf"
 # Runtime provider id — DO NOT change. Embedded in model strings
-# (`entwurf/claude-sonnet-5`), settings keys (`entwurfProvider`),
+# (`entwurf/claude-sonnet-5-5`), settings keys (`entwurfProvider`),
 # log prefixes (`[entwurf:bootstrap]`), and the `--provider entwurf`
 # CLI surface. Renaming this would break every consumer transcript and every
 # saved session anchor.
@@ -116,9 +116,55 @@ run_vitest() {
   (cd "$REPO_DIR" && "$bin" run "$@")
 }
 
+# A source-only UI over the existing owned developer-return procedure. No second
+# installer, npm acquisition, automatic mode switch or ownership writer lives here.
+developer_menu() {
+  [ "$#" -eq 0 ] || { echo 'usage: ./run.sh menu' >&2; return 2; }
+  if [ ! -d "$REPO_DIR/.git" ] || [ ! -f "$REPO_DIR/plugins/herdr/use-dev-checkout.sh" ]; then
+    echo '[menu] developer-checkout-source-only — run ./run.sh menu from the prepared source checkout, not the npm installation.' >&2
+    return 1
+  fi
+  if [ ! -t 0 ]; then
+    echo '[menu] menu-tty-required — interactive stdin is required; nothing was changed.' >&2
+    return 2
+  fi
+  local choice confirm
+  printf '\nHerdr — npm installation check → developer board (local checkout)\n'
+  printf 'Checkout: %s\n' "$REPO_DIR"
+  printf '  1) Readiness check — read-only (not a full certificate of installation prerequisites)\n'
+  printf '  2) Switch to the developer board — Pi / Claude Code / Herdr local link\n'
+  printf '  0) Quit — nothing is changed\n'
+  if ! IFS= read -r -p 'Choose [0/1/2]: ' choice; then
+    echo '[menu] menu-input-closed — nothing was changed.' >&2
+    return 2
+  fi
+  case "$choice" in
+    0) return 0 ;;
+    1) bash "$REPO_DIR/plugins/herdr/use-dev-checkout.sh" --check ;;
+    2)
+      # Show the real owner's readiness first. Busy sessions or bad ownership
+      # stop here; confirmation grants no authority to bypass those guards.
+      bash "$REPO_DIR/plugins/herdr/use-dev-checkout.sh" --check || return $?
+      printf '\nClose the affected sessions yourself, and start no new session while switching.\n'
+      printf 'The currently owned installation is deactivated, then this checkout is linked. There is no automatic recovery or retry.\n'
+      if ! IFS= read -r -p 'Type DEV to switch (anything else cancels): ' confirm; then
+        echo '[menu] menu-input-closed — apply was not called.' >&2
+        return 2
+      fi
+      if [ "$confirm" != DEV ]; then
+        echo '[menu] menu-cancelled — installation wiring is unchanged.'
+        return 0
+      fi
+      bash "$REPO_DIR/plugins/herdr/use-dev-checkout.sh" --apply
+      ;;
+    *) echo '[menu] invalid-menu-choice — choose 0, 1 or 2; nothing was changed.' >&2; return 2 ;;
+  esac
+}
+
 usage() {
   cat <<'EOF'
 Usage:
+  ./run.sh menu                       # source-only Herdr developer board: read-only readiness check or explicitly confirmed return to checkout wiring; never closes sessions or acquires npm artifacts
   ./run.sh setup [project-dir]        # ONE presence-driven composition (#86): per-component PASS/SKIP/FAIL for pi/claude/agy/copilot/omp/codex + stable dev bins + v2 install smoke. Codex birth/MCP/status-line atoms are composed at user scope; setup stays non-green until the operator trusts the birth declaration once in visible Codex. Absent harness = zero-state SKIP, detected-incomplete = named FAIL + nonzero exit. Never installs a harness, starts a daemon, touches credentials, or writes the vendor trust receipt
   ./run.sh release-gate [project-dir] [--cut] [--allow-skip-gemini]  # SINGLE release gate: full static (pnpm run check:full) + the v2-native live gates (v2 matrix-live, check-bridge, doctor-pi-provider, RGG) + the ACP plugin acceptance floor (12 LIVE smokes: socket-citizen/raw-turn/overlay/provider/session-reuse/carrier-augment/memory-containment/rgg/mcp/skill/bundled-mcp/v2-send) + the one surviving axis the aggregate used to omit silently (claude-native-resume; Cortex stays a documented on-demand direct call) + the cross-harness delivery chain (smoke-entwurf-chain-live) + the Codex Pi -> visible Codex -> visible Pi receipt chain (smoke-codex-fresh-live; initial Pi and the Codex it opens in one session S, explicit operator-owned app-server PID in a DIFFERENT session — that separation is the lane B claim). TWO-TIER summary: MUST (release-blocking, owns the exit code — "green" applies here) + BEHAVIOR (advisory, non-blocking: RGG positives model-in-loop turn). STEP OUTCOME protocol: every step is INVOKED and reports its own PASS / SKIP (exit 97, a prerequisite it does not have) / FAIL — a skip is never counted as a pass. Without --cut this is the unattended diagnostic (SKIPs reported, exit 0). WITH --cut it is read as release acceptance and ANY MUST SKIP is red, which is what makes "a CUT needs LIVE=1, SKIP=0" executable instead of prose. --allow-skip-gemini accepted-but-ignored (back-compat). final cut authorization is GLG's.
   ./run.sh check-bridge               # entwurf-bridge direct MCP smoke + protocol/negative-path test.sh (live substrate = v2 live smokes)
@@ -223,7 +269,7 @@ Usage:
   ./run.sh check-meta-manifest-schema # 0.12.2 meta-bridge: CLI-version-INDEPENDENT static guard — plugin manifests pinned to the minimal keyset that validates on the lowest supported Claude (closed-schema regression that broke 0.12.1 install on floor) + desired_mcp installed-vs-clone dual-mode. Offline (deps: python3)
   ./run.sh smoke-claude-native-resume-live # LIVE-only: Claude Code native fresh→--resume continuity + meta-record uniqueness; proves meta-bridge records identity without touching the backend resume path
 
-  ./run.sh install-meta-bridge        # INTERNAL part of `setup` (native-harness plugin) + doctor recovery path — prefer `setup`; stateful GLOBAL install (plugin + USER MCP + settings keyset, honest uninstall state)
+  ./run.sh install-meta-bridge        # INTERNAL wiring leaf: setup, the source-only developer menu and doctor recovery compose it; stateful GLOBAL install (plugin + USER MCP + settings keyset, honest uninstall state)
   ./run.sh uninstall-meta-bridge      # 1.0.0 meta-bridge Phase 2: stateful GLOBAL uninstall (restore only keys/items captured in install-state)
   ./run.sh doctor-meta-bridge         # THE RELEASE ORACLE (#51, Linux-certified repair axis). exit 0 = every required layer was MEASURED on this Linux host: toolchain + state + plugin/MCP + resolved-artifact launch-form classification (all 3 owner hooks + doorbell static contract) + synthetic owner join + store scan + hook errors + SessionStart evidence + REQUIRED live MCP↔marker join + writer-version parity. Missing live evidence is NOT CERTIFIED (open a Claude session and re-run), never a pass; Darwin is NOT CERTIFIED and stays nonzero, on ONE narrowed reason — start-key and ppid are portable there (`ps` fallback, same string the TS core mints), so what holds the lane closed is per-process environment DISCOVERY alone, pending physical-host evidence. Detection power is held by check-meta-doctor-oracle
   ./run.sh copilot [args...]          # #82 RAIL 7: the MANAGED Copilot launch. exec()s the vendor CLI in THIS terminal (cwd/pid/exit preserved) with COPILOT_CLI_ENABLED_FEATURE_FLAGS=EXTENSIONS set for that one invocation — entwurf owns no part of your shell and writes nothing to it, but it owns the process it is about to become. Without that flag Copilot skips the extension scan SILENTLY. Refuses to launch unless the receiver unit is actually installed. Injects `--model auto` when no --model was given and `--yolo` when no explicit permission/surface policy flag was given, both BEFORE any `--`; every argument you pass is forwarded byte-identical. RUNNING THIS IS YOUR CONSENT to that profile — use plain `copilot` for stock vendor behaviour. Not tmux, not fresh-call, mints no citizen (birth is still the first prompt)
@@ -291,7 +337,7 @@ Usage:
   ./run.sh check-fresh-cut-gate       # SOURCE cell of the generation-boundary proof (IN pnpm run check:full): drives real install/setup/fresh-cut in a sandbox; certification refusal is pre-write, quiescence is fail-closed, archives preserve bytes, and the #54 exit matrix distinguishes complete / no-move / usage / incomplete transition / complete-with-cleanup-residue. No model/network/cost
   ./run.sh check-pack-install         # heavy publish gate (prepublishOnly): actual npm pack + tar -tf + fresh-temp install smoke + the #116 M3-b1 herdr-plugin RUNTIME VERIFIER run against that actual installed tarball (the focused check-herdr-runtime-bootstrap drives a fixture; THIS is where the real package is proven) with the pinned pi SDK (pins derived from the package.json exact production dependency; check-dep-versions binds them) + the npm-installed bridge BOOTS (tools/list) and DELIVERS (tools/call entwurf_v2 → .msg lands) + the installed all-absent and copilot-present (four-unit fake-vendor) `entwurf setup` rows + the INSTALLED generation lifecycle on a seeded previous-generation host (REFUSE before activation writes / zero Claude invocations → installed fresh-cut archives + opens empty → install-meta-bridge PASSES) + the INSTALLED-PACKAGE branch of the Copilot and OMP birth installers actually RUN (compiled entry selected, no raw .ts, and a real birth edge mints a citizen — the half a required-artifact list can never stand in for) + the INSTALLED #129 durable bootstrap (pi/pi-durable/bootstrap.mjs) imported from node_modules: main/openDurableCitizen exported and PACKAGED_BRIDGE_ENTRY = the installed package's own dist entry — import only, no runtime/TUI/birth/bridge started + the #130 pi-durable CARRIER on actual npm consumers (Entwurf-only / aligned host / isolated global): the installed verifier, a consumer-contained resolution oracle with a same-sandbox neighbour control, every physical SDK edge at the pin, a mixed tree refused as pi-durable-sdk-mismatch though it still imports, and the public `entwurf pi-durable` reaching the app's own explicit-model refusal before any birth, also with one explicit `--native-module` (the synthetic fixture, initialized first; a reserved extension name refused before anything opens) (offline, sandbox HOME)
   ./run.sh check-install-container    # 0.12.8 (#51 C): Linux artifact-CONSUMER gate — one candidate .tgz handed read-only to a checkout-invisible node:<engines-major>-bookworm cell. Default packs once to temp; ENTWURF_CANDIDATE_TGZ=/absolute/preserved.tgz consumes those exact bytes with no re-pack and prints canonical path+sha256 for release. Non-root global PATH install, frozen package, MCP tools/list, fake-Claude install-meta-bridge, path+sha256 fence, strict doctor, and the GENERATION host-state matrix (clean / v3-only store bytes unchanged / previous-generation REFUSE→fresh-cut→retry PASS) seeded inline. Docker missing = honest SKIP; ENTWURF_REQUIRE_DOCKER=1 makes that RED (required CI)
-  ./run.sh install [project-dir]      # INTERNAL part of `setup` (project .pi/settings.json wiring) + npm-consumer entry — prefer `setup`, don't call directly for dev
+  ./run.sh install [project-dir]      # INTERNAL wiring leaf: setup/npm-consumer entry and the source-only developer menu compose it; prefer those owning procedures
   ./run.sh remove [project-dir]       # remove entwurf entries from project .pi/settings.json (project scope only; global user-scope citizen left intact)
   ./run.sh install-user-scope [--plugin-runtime <root>]  # #116 M3-b2 PLUGIN-ONLY forward seam: compose ONLY the global pi citizen (user-scope packages[] + provider), never a project `.pi/settings.json` — a Herdr plugin activation has no project and must not invent one. With --plugin-runtime the provider's managed command becomes the absolute bridge under that certified stable runtime (a clean host has nothing entwurf on PATH); without it every byte is the historical bare-bin install. Inverse: remove-user-scope
   ./run.sh herdr-plugin-activate <backend...>  # #116 M3-b2 public forward activation. Takes a subset of {pi, claude-code} and NOTHING else — the stable runtime root is DERIVED from XDG here and handed down, and both harness writers accept a named root only when it IS that derived one. Certifies the runtime-ready journal AND the installed tree, certifies the existing ledger and its recorded harness roots, plans ADD-ONLY (a backend absent from this request is retained, never removed), preflights every selected component before the first byte, then writes each component `pending` BEFORE mutating and checkpoints `active` the moment its writer returns — so a run that dies halfway leaves a record of how far it got. Which backends is M3-b3's question: this verb is handed the answer, it does not read Herdr's integration status
@@ -1395,6 +1441,14 @@ check_acp_foreground_only() {
   run_vitest pi-extensions/lib/acp/backend-adapter.test.ts
 }
 
+check_acp_set_model_readback() {
+  # NOT a discovery path — check-tests-beside-behavior finds the test by glob. This case is the
+  # MUTANT EXECUTION COORDINATE for scripts/mutants/acp-set-model-readback.json (#128): the claude
+  # adapter refuses a set-model answer that does not name the requested model, before the prompt.
+  section "claude ACP set-model readback (mutant execution coordinate)"
+  run_vitest pi-extensions/lib/acp/backend-adapter.test.ts
+}
+
 check_acp_vendor_rejection() {
   # Behaviour-adjacent tests are discovered by the glob lane. This narrow case is the
   # mutant execution coordinate: include the adapter admission and real turn pipeline,
@@ -1603,12 +1657,12 @@ check_mux_launch_tmux() {
 smoke_acp_socket_citizen_live() {
   # S1 acceptance smoke (ACP plugin on v2) — OUT of pnpm check, needs LIVE=1.
   # Spawns a REAL `pi --entwurf-control` resident on an ACP model
-  # (entwurf/claude-opus-5) and proves it is a first-class socket-citizen:
+  # (entwurf/claude-opus-5-5) and proves it is a first-class socket-citizen:
   # the control socket stands up, get_info answers with the ACP model (model-lock
   # did NOT revert — QM1), idle/cwd are reported, and the fail-loud streamSimple
   # stub never fires (turn-free launch — QM2). No prompt is sent: S1 proves
   # citizenship, never a backend turn (that is S2). Honest skip when LIVE!=1.
-  # Model override: ENTWURF_S1_MODEL (default claude-opus-5).
+  # Model override: ENTWURF_S1_MODEL (default claude-opus-5-5).
   #   LIVE=1 ./run.sh smoke-acp-socket-citizen-live
   run_ts scripts/smoke-acp-socket-citizen-live.ts
 }
@@ -1622,7 +1676,7 @@ smoke_acp_raw_turn_live() {
   # plus captured raw NDJSON bytes. NO provider/overlay/streamSimple/_meta — the
   # raw backend pipe only. Launch source must be the package bin (PATH fallback
   # fails acceptance unless ENTWURF_ACP_RAW_TURN_ALLOW_PATH_FALLBACK=1, debug).
-  # Model override: ENTWURF_ACP_RAW_TURN_MODEL (default claude-sonnet-5).
+  # Model override: ENTWURF_ACP_RAW_TURN_MODEL (default claude-sonnet-5-5).
   #   LIVE=1 ./run.sh smoke-acp-raw-turn-live
   run_ts scripts/smoke-acp-raw-turn-live.ts
 }
@@ -1640,7 +1694,7 @@ smoke_acp_overlay_live() {
   # meta-store for mailbox absence (flaky — concurrent sessions); the honest
   # claim is overlay-supplies-hooks:{}. Launch must be the package bin (PATH
   # fallback fails acceptance unless ENTWURF_ACP_OVERLAY_ALLOW_PATH_FALLBACK=1).
-  # Model override: ENTWURF_ACP_OVERLAY_MODEL (default claude-sonnet-5).
+  # Model override: ENTWURF_ACP_OVERLAY_MODEL (default claude-sonnet-5-5).
   #   LIVE=1 ./run.sh smoke-acp-overlay-live
   run_ts scripts/smoke-acp-overlay-live.ts
 }
@@ -1655,7 +1709,7 @@ smoke_acp_memory_containment_live() {
   # can stop a memory write is the lever — not us. Fails loud if engraving.md is
   # empty (carrier OFF = no containment). Launch must be the package bin (PATH
   # fallback fails acceptance unless ENTWURF_ACP_MEMORY_ALLOW_PATH_FALLBACK=1).
-  # Model override: ENTWURF_ACP_MEMORY_MODEL (default claude-sonnet-5).
+  # Model override: ENTWURF_ACP_MEMORY_MODEL (default claude-sonnet-5-5).
   #   LIVE=1 ./run.sh smoke-acp-memory-containment-live
   run_ts scripts/smoke-acp-memory-containment-live.ts
 }
@@ -1682,7 +1736,7 @@ smoke_acp_provider_live() {
   # assistant reply (live model proof) + the removed S0 stub error never appears
   # (provider path actually opened) + pi exits 0. Tool-free prompt; the
   # event-mapper gate owns the tool→notice contract.
-  # Model override: ENTWURF_ACP_PROVIDER_MODEL (default claude-sonnet-5).
+  # Model override: ENTWURF_ACP_PROVIDER_MODEL (default claude-sonnet-5-5).
   #   LIVE=1 ./run.sh smoke-acp-provider-live
   run_ts scripts/smoke-acp-provider-live.ts
 }
@@ -1696,7 +1750,7 @@ smoke_acp_session_reuse_live() {
   # is the verdict; codeword recall is supporting only (a rebuilt full transcript
   # could recall it too). The one-shot exit0 half is owned by
   # smoke-acp-provider-live.
-  # Model override: ENTWURF_ACP_PROVIDER_MODEL (default claude-sonnet-5).
+  # Model override: ENTWURF_ACP_PROVIDER_MODEL (default claude-sonnet-5-5).
   #   LIVE=1 ./run.sh smoke-acp-session-reuse-live
   run_ts scripts/smoke-acp-session-reuse-live.ts
 }
@@ -1708,7 +1762,7 @@ smoke_acp_carrier_augment_live() {
   # secret (the augment rode the wire to the model) and the EMPTY default carrier
   # must bill clean (exit 0, no HTTP-400 canary — 핀1 live). Optional tiny carrier
   # check via SMOKE_ACP_CARRIER_PRESENT=1 (non-blocking).
-  # Model override: ENTWURF_ACP_PROVIDER_MODEL (default claude-sonnet-5).
+  # Model override: ENTWURF_ACP_PROVIDER_MODEL (default claude-sonnet-5-5).
   #   LIVE=1 ./run.sh smoke-acp-carrier-augment-live
   run_ts scripts/smoke-acp-carrier-augment-live.ts
 }
@@ -1794,9 +1848,9 @@ smoke_acp_rgg_live() {
   # birth, record-keyed socket, attach-on-reopen, no pi-session-id socket) holds
   # under the ACP provider too — the logic is provider-agnostic. The POSITIVE cell
   # (one real turn completing transcriptPath/model) is the only model-in-loop part.
-  # Target override: ENTWURF_RGG_TARGET (default entwurf/claude-sonnet-5).
+  # Target override: ENTWURF_RGG_TARGET (default entwurf/claude-sonnet-5-5).
   #   ./run.sh smoke-acp-rgg-live
-  local target="${ENTWURF_RGG_TARGET:-entwurf/claude-sonnet-5}"
+  local target="${ENTWURF_RGG_TARGET:-entwurf/claude-sonnet-5-5}"
   (cd "$REPO_DIR" && ENTWURF_LIVE_TARGET="$target" SMOKE_RGG_POSITIVE=0 bash scripts/smoke-resident-garden-guard.sh)
 }
 
@@ -3646,7 +3700,7 @@ check_pack() {
     "package.json" "README.md" "LICENSE" "CHANGELOG.md"
     "protocol.js" "run.sh"
     "pi-extensions/acp-provider.ts"
-    "pi-extensions/lib/acp/models.ts" "pi-extensions/lib/acp/backend.ts"
+    "pi-extensions/lib/acp/models.ts" "pi-extensions/lib/acp/model-ids.js" "pi-extensions/lib/acp/backend.ts"
     "pi-extensions/lib/acp/overlay.ts" "pi-extensions/lib/acp/tool-surface.ts"
     "pi-extensions/lib/acp/event-mapper.ts" "pi-extensions/lib/acp/context.ts"
     "pi-extensions/entwurf-control.ts"
@@ -4294,7 +4348,7 @@ _check_pack_install_impl() {
     "package.json" "README.md" "LICENSE" "CHANGELOG.md"
     "protocol.js" "run.sh"
     "pi-extensions/acp-provider.ts"
-    "pi-extensions/lib/acp/models.ts" "pi-extensions/lib/acp/backend.ts"
+    "pi-extensions/lib/acp/models.ts" "pi-extensions/lib/acp/model-ids.js" "pi-extensions/lib/acp/backend.ts"
     "pi-extensions/lib/acp/overlay.ts" "pi-extensions/lib/acp/tool-surface.ts"
     "pi-extensions/lib/acp/event-mapper.ts" "pi-extensions/lib/acp/context.ts"
     "pi-extensions/entwurf-control.ts"
@@ -4720,8 +4774,8 @@ _check_pack_install_impl() {
   loader_ids=$(awk '$1 == "entwurf" { print $2 }' <<<"$loader_out" | LC_ALL=C sort)
   loader_expected=$(printf '%s\n' \
     claude-fable-5-1 \
-    claude-opus-5 \
-    claude-sonnet-5 \
+    claude-opus-5-5 \
+    claude-sonnet-5-5 \
     cortex-auto \
     cortex-claude-opus-5 \
     cortex-claude-sonnet-5 \
@@ -4830,7 +4884,7 @@ sys.exit(0 if any(isinstance(s,str) and s.endswith('/node_modules/@junghanacs/en
     echo "$foreign_out" | tail -10 | sed 's/^/    /' >&2
     return 1
   }
-  if grep -qi "Unknown option" <<<"$foreign_out" || ! grep -q "claude-opus-5" <<<"$foreign_out"; then
+  if grep -qi "Unknown option" <<<"$foreign_out" || ! grep -q "claude-opus-5-5" <<<"$foreign_out"; then
     fail "[check-pack-install] foreign-cwd --entwurf-control did not load the entwurf extension from user scope:"
     echo "$foreign_out" | tail -10 | sed 's/^/    /' >&2
     return 1
@@ -7069,6 +7123,10 @@ release_gate() {
 
 cmd=${1:-}
 case "$cmd" in
+  menu)
+    shift
+    developer_menu "$@"
+    ;;
   setup)
     setup_all "$TARGET_PROJECT_DIR"
     ;;
@@ -7243,6 +7301,9 @@ case "$cmd" in
   check-acp-foreground-only)
     check_acp_foreground_only
     ;;
+  check-acp-set-model-readback)
+    check_acp_set_model_readback
+    ;;
   check-resume-launch-identity)
     check_resume_launch_identity
     ;;

package/scripts/check-acp-backend-preflight.ts

@@ -16,13 +16,13 @@
 
 import { strict as assert } from "node:assert";
 import { execFileSync } from "node:child_process";
-import { readdirSync, readFileSync, rmSync } from "node:fs";
+import { readdirSync, readFileSync, rmdirSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import type { Api, AssistantMessageEvent, Model, TranscriptContext } from "@earendil-works/pi-ai";
 import { normalizeContext } from "@earendil-works/pi-ai";
 
-const model = { id: "claude-sonnet-5" } as unknown as Model<Api>;
+const model = { id: "claude-sonnet-5-5" } as unknown as Model<Api>;
 
 // Declared tools exclude `read`, but the Claude child always exposes Read →
 // declared != actual → the preflight must reject before spawning.
@@ -157,6 +157,14 @@ try {
 	);
 } finally {
 	rmSync(TMP_EMIT, { recursive: true, force: true });
+	try {
+		// Same as check-acp-cortex: the emit created `.tmp-verify/` as TMP_EMIT's parent, and
+		// check-gate-qualification's snapshot manifest walks ignored paths, so a leftover empty
+		// parent reads as a dirty tree. Remove it when empty; a sibling's emit keeps it alive.
+		rmdirSync(".tmp-verify");
+	} catch {
+		// non-empty or already gone — fine either way
+	}
 }
 
 // ---------------------------------------------------------------------------

package/scripts/check-acp-cortex.ts

@@ -53,11 +53,11 @@ import {
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { getModels } from "@earendil-works/pi-ai/compat";
 import { buildPiContextAugment } from "../pi-extensions/lib/acp/augment.ts";
 import type { AcpMcpServer } from "../pi-extensions/lib/acp/config.ts";
 import {
 	CORTEX_MODEL_PREFIX,
-	curatedClaudeModels,
 	curatedCortexModels,
 	SUPPORTED_CORTEX_MODEL_IDS,
 } from "../pi-extensions/lib/acp/models.ts";
@@ -87,12 +87,13 @@ const cortexRowIds = cortexRows.map((m) => m.id);
 assert.deepEqual(cortexRowIds, [...SUPPORTED_CORTEX_MODEL_IDS], "curated cortex rows must match the supported id set");
 // The two Claude rows ride their OWN registry bases (a fabricated row would
 // drift from the pi-ai catalog); auto/gpt ride the sonnet base as a floor.
-const claudeRows = curatedClaudeModels();
+// Cortex retains its own native 5 ids even when Claude's curated set moves to 5.5.
+const claudeRows = getModels("anthropic");
 const sonnetBase = claudeRows.find((m) => m.id === "claude-sonnet-5");
 const opusBase = claudeRows.find((m) => m.id === "claude-opus-5");
 // Plain throw (not assert.ok): an asserts-function premise makes tsc report the
 // downstream `base` const as circularly-typed (TS7022).
-if (!sonnetBase || !opusBase) throw new Error("test premise: sonnet-5/opus-5 present in curated claude surface");
+if (!sonnetBase || !opusBase) throw new Error("test premise: sonnet-5/opus-5 present in pi-ai registry");
 for (const row of cortexRows) {
 	// Explicit annotation: node:assert's asserts-typed helpers otherwise make tsc
 	// flag this flow-dependent const as circularly typed (TS7022).
@@ -480,7 +481,7 @@ try {
 	// throwing IS the anti-collision proof; we also assert the rows are present.
 	const registered = mod.allCuratedModels().map((m) => m.id);
 	for (const want of [
-		"claude-sonnet-5",
+		"claude-sonnet-5-5",
 		"cortex-auto",
 		"cortex-claude-opus-5",
 		"cortex-claude-sonnet-5",
@@ -494,12 +495,12 @@ try {
 	assert.equal(routedSonnet.adapter.backend, "cortex", "cortex-claude-sonnet-5 must route to the cortex adapter");
 	assert.equal(routedSonnet.nativeModelId, "claude-sonnet-5", "prefix strip must recover the native model id");
 	assert.equal(
-		mod.resolveAcpBackendAdapter("claude-sonnet-5").adapter.backend,
+		mod.resolveAcpBackendAdapter("claude-sonnet-5-5").adapter.backend,
 		"claude",
 		"the unprefixed claude id must still route to claude (prefix keeps the namespaces apart)",
 	);
 	assert.equal(
-		mod.cortexAdapter.routeModel("claude-sonnet-5"),
+		mod.cortexAdapter.routeModel("claude-sonnet-5-5"),
 		undefined,
 		"cortex must NOT claim the unprefixed claude id",
 	);

package/scripts/check-acp-prompt-lifecycle.ts

@@ -40,7 +40,7 @@ import type { Api, AssistantMessageEvent, Message, Model, TranscriptContext } fr
 import { normalizeContext } from "@earendil-works/pi-ai";
 import { isRetryableAssistantError } from "@earendil-works/pi-ai/compat";
 
-const sonnet = { id: "claude-sonnet-5" } as unknown as Model<Api>;
+const sonnet = { id: "claude-sonnet-5-5" } as unknown as Model<Api>;
 
 type Stream = AsyncIterable<AssistantMessageEvent>;
 
@@ -151,7 +151,7 @@ function makeHarness(recordDir: string) {
 	const makeConnection = (handlers: any) => ({
 		initialize: async () => ({ agentCapabilities: {} }),
 		newSession: async () => ({ sessionId: "ACP-1" }),
-		setSessionConfigOption: async () => ({}),
+		setSessionConfigOption: async (p: any) => ({ configOptions: [{ id: "model", currentValue: p.value }] }),
 		prompt: ({ sessionId }: any) => {
 			promptCount++;
 			notifier = (update) => handlers.sessionUpdate({ update, sessionId });

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

@@ -123,7 +123,7 @@ try {
 	assert.equal(cap.cfg.apiKey, ENTWURF_ACP_NO_AUTH_SENTINEL, "entry apiKey is not the no-auth sentinel");
 	assert.equal(cap.cfg.api, "entwurf", "entry api field drifted");
 	const capIds = (cap.cfg.models ?? []).map((m) => m.id);
-	for (const want of ["claude-sonnet-5", CURATED_ANCHOR_MODEL_ID]) {
+	for (const want of ["claude-sonnet-5-5", CURATED_ANCHOR_MODEL_ID]) {
 		assert.ok(capIds.includes(want), `entry model surface missing ${want} (got: ${capIds.join(", ") || "none"})`);
 	}