@junghanacs/entwurf 0.30.0 → 0.30.1

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

@@ -21,6 +21,7 @@
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { RequestError } from "@agentclientprotocol/sdk";
 
 import type { AcpConnectionLike } from "./acp-client.js";
 import { enrichMcpServersWithEnvelope, type ResolvedAcpConfig } from "./config.js";
@@ -235,14 +236,73 @@ export interface AcpBackendAdapter {
 	 *  entwurf actually reads from a NOTIFICATION cannot desync from a response
 	 *  shape it never inspects. */
 	sealsTurnAccounting?: true;
+
+	/** OPTIONAL capability (#127): recognise a typed vendor rejection of `session/prompt`
+	 *  whose raw text must not become pi's `errorMessage`. pi decides a whole-prompt replay
+	 *  from `errorMessage` alone, and a vendor's "Internal error" — or any digit run in the
+	 *  ids it carries — reads as transient, so a turn whose tools already ran would be resent
+	 *  from a cold session. A recognised rejection returns a fixed, authored verdict for
+	 *  `errorMessage`; backend.ts keeps the raw rejection as a pi diagnostic instead.
+	 *
+	 *  ABSENT means every failure of this backend keeps the verbatim-first `errorMessage`.
+	 *  The vocabulary is the vendor's, so only the adapter that speaks it may declare it. */
+	readPromptRejection?(err: unknown): AcpPromptRejection | undefined;
+}
+
+/** A vendor rejection an adapter recognised (`readPromptRejection`). */
+export interface AcpPromptRejection {
+	/** The vendor's own failure kind, as it named it on the wire. */
+	errorKind: string;
+	/** Entwurf-authored and fixed — no vendor text, ids or numbers: this is what pi classifies. */
+	verdict: string;
+	/** The JSON-RPC `data`, re-serialized as evidence (it arrived as parsed JSON). */
+	dataJson: string;
 }
 
+/** The pi diagnostic type under which backend.ts preserves a recognised rejection verbatim. */
+export const ACP_PROMPT_REJECTION_DIAGNOSTIC = "entwurf_acp_prompt_rejection";
+
+/** The verdict for claude-agent-acp's `incomplete_tool_call` (#127; upstream #1212, 0.85.0+). */
+export const INCOMPLETE_TOOL_CALL_VERDICT =
+	"ACP turn failed because foreground tool results are incomplete. Some tools may already have run; automatic replay is unsafe. Inspect the preserved vendor rejection before continuing.";
+
 // ---------------------------------------------------------------------------
 // claude adapter — the first implementation (the rail's reference backend)
 // ---------------------------------------------------------------------------
 
 const SUPPORTED_CLAUDE_IDS: ReadonlySet<string> = new Set(SUPPORTED_ANTHROPIC_MODEL_IDS);
 
+/** JSON-RPC internal error — the code claude-agent-acp rejects an unfinished-tool turn with. */
+const JSONRPC_INTERNAL_ERROR = -32603;
+/** claude-agent-acp's own kind for a turn that hit `end_turn` with foreground tools unanswered
+ *  (read at v0.85.1 `src/acp-agent.ts:4286-4340`, `errorKindData("incomplete_tool_call")`). */
+const CLAUDE_INCOMPLETE_TOOL_CALL = "incomplete_tool_call";
+
+/**
+ * The claude reader for `readPromptRejection` (#127). Only the root wire SDK's own decode
+ * counts: its client rejects a JSON-RPC error response with `new RequestError(code, message,
+ * data)`, `data` being the parsed `error.data` (sdk 1.4.0 `dist/jsonrpc.js:842-844`). A
+ * look-alike object, another code, or another `errorKind` is not this failure and keeps the
+ * verbatim-first path.
+ */
+function readClaudePromptRejection(err: unknown): AcpPromptRejection | undefined {
+	if (!(err instanceof RequestError) || err.code !== JSONRPC_INTERNAL_ERROR) return undefined;
+	const data = err.data;
+	if (typeof data !== "object" || data === null || !("errorKind" in data)) return undefined;
+	if (data.errorKind !== CLAUDE_INCOMPLETE_TOOL_CALL) return undefined;
+	return { errorKind: CLAUDE_INCOMPLETE_TOOL_CALL, verdict: INCOMPLETE_TOOL_CALL_VERDICT, dataJson: jsonText(data) };
+}
+
+/** Evidence text for a wire value. A value that came off the wire serializes; one that cannot
+ *  (a hand-built fake) is named as such, so recording evidence never breaks the turn's seal. */
+function jsonText(value: unknown): string {
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch (err) {
+		return `[unserializable: ${err instanceof Error ? err.name : typeof err}]`;
+	}
+}
+
 /**
  * Resolve the claude launch — an ENTWURF-OWNED launcher, or the env override for debug.
  * This is the single source for the claude launch spec; backend.ts holds no private copy.
@@ -359,6 +419,10 @@ export const claudeAdapter: AcpBackendAdapter = {
 	// The token partition is NOT declared here: ACP's only token carrier is a
 	// per-turn round-trip aggregate, which is not what pi's four fields mean.
 	sealsTurnAccounting: true,
+
+	// #127: claude-agent-acp 0.85.0+ rejects an `end_turn` with unanswered foreground tools as
+	// -32603 `incomplete_tool_call` (upstream #1212). Its raw text reads as transient to pi.
+	readPromptRejection: readClaudePromptRejection,
 };
 
 // ---------------------------------------------------------------------------
@@ -527,6 +591,10 @@ export const cortexAdapter: AcpBackendAdapter = {
 	// backend.ts seals nothing for a backend without this flag, so cortex's
 	// emitted usage is byte-identical to what it was before #93. Declaring this
 	// with a guess would mint exactly the silent misaccounting #93 exists to end.
+
+	// NO readPromptRejection — also deliberate. Nobody has read which failures cortex's ACP
+	// server rejects a prompt with, so every cortex failure keeps the verbatim-first
+	// errorMessage. Borrowing claude's `incomplete_tool_call` reader would be a guess.
 };
 
 const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter, cortexAdapter];

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

@@ -45,7 +45,12 @@ import { readFileSync } from "node:fs";
 import { Readable, Writable } from "node:stream";
 import { ndJsonStream, PROTOCOL_VERSION } from "@agentclientprotocol/sdk";
 import type { Api, AssistantMessage, Model, SimpleStreamOptions, TranscriptContext } from "@earendil-works/pi-ai";
-import { createAssistantMessageEventStream, getCurrentTools } from "@earendil-works/pi-ai";
+import {
+	appendAssistantMessageDiagnostic,
+	createAssistantMessageDiagnostic,
+	createAssistantMessageEventStream,
+	getCurrentTools,
+} from "@earendil-works/pi-ai";
 import {
 	type AcpClientHandlers,
 	type AcpConnectionLike,
@@ -53,7 +58,11 @@ import {
 	connectAcpClient,
 } from "./acp-client.js";
 import { prependNewPromptAugment } from "./augment.js";
-import { type AcpBackendAdapter, resolveAcpBackendAdapter } from "./backend-adapter.js";
+import {
+	ACP_PROMPT_REJECTION_DIAGNOSTIC,
+	type AcpBackendAdapter,
+	resolveAcpBackendAdapter,
+} from "./backend-adapter.js";
 import {
 	enrichMcpServersWithEnvelope,
 	mcpServerNames,
@@ -1435,13 +1444,18 @@ export function streamAcpTurn(
 		stderrTail?: string[],
 		lifecycle?: string,
 		launchObservation?: AcpLaunchObservation,
+		/** Passed only from the two prompt-phase catches, where the turn's adapter is resolved. */
+		adapter?: AcpBackendAdapter,
 	): void {
 		finalizeAcpStreamState(state);
 		state.output.stopReason = aborted ? "aborted" : "error";
 		const base = err instanceof Error ? err.message : String(err);
 		// The FIRST failure stays first and verbatim (it is what the backend
 		// actually said); the lifecycle line is added, never substituted, so a
-		// reader can still match the transport's own text.
+		// reader can still match the transport's own text. One typed exception
+		// below: a vendor rejection the adapter recognises keeps that verbatim text
+		// as a pi diagnostic instead, because pi reads errorMessage to decide a
+		// whole-prompt replay (#127).
 		const withLifecycle = lifecycle ? `${base}\n${lifecycle}` : base;
 		// Its OWN line, above the vendor tail: an entwurf-owned observation must not
 		// have to be recovered by reading vendor prose.
@@ -1453,7 +1467,28 @@ export function streamAcpTurn(
 		// overflow gets an actionable hint appended, so "API Error" stops hiding
 		// the turn-scoped full-transcript-replay cause.
 		const hint = aborted ? undefined : actionableAcpBackendHint(full);
-		state.output.errorMessage = hint ? `${full}\n\n${hint}` : full;
+		// #127: pi's retry and overflow classifiers read `errorMessage` ALONE, and a
+		// vendor's "Internal error" or any digit run in its ids/stderr reads as transient
+		// — a replay of a turn whose tools already ran. A rejection the adapter names gets
+		// its fixed verdict there; every raw part rides one diagnostic, appended after any
+		// existing ones. An abort keeps the abort path.
+		const rejection = aborted ? undefined : adapter?.readPromptRejection?.(err);
+		if (rejection) {
+			appendAssistantMessageDiagnostic(
+				state.output,
+				createAssistantMessageDiagnostic(ACP_PROMPT_REJECTION_DIAGNOSTIC, err, {
+					errorKind: rejection.errorKind,
+					dataJson: rejection.dataJson,
+					...(lifecycle ? { lifecycle } : {}),
+					...(observed ? { launchSignal: observed } : {}),
+					...(tail ? { stderrTail: tail } : {}),
+					...(hint ? { hint } : {}),
+				}),
+			);
+			state.output.errorMessage = rejection.verdict;
+		} else {
+			state.output.errorMessage = hint ? `${full}\n\n${hint}` : full;
+		}
 		stream.push({ type: "error", reason: aborted ? "aborted" : "error", error: state.output });
 		stream.end();
 	}
@@ -1915,6 +1950,7 @@ export function streamAcpTurn(
 				session?.stderrTail ?? stderrTail,
 				lifecycle,
 				session?.launchObservation ?? launchObservation,
+				adapter,
 			);
 			// error/abort → drop the (uncertain) session and close its child; an
 			// uncertain connection must never be reused (GPT ④).
@@ -1982,7 +2018,7 @@ export function streamAcpTurn(
 			// Without the session-scoped tail a mid-turn child death on a resident
 			// session surfaced as a bare "ACP connection closed" with nothing to read
 			// it by.
-			finishError(err, aborted, session.stderrTail, lifecycle, session.launchObservation);
+			finishError(err, aborted, session.stderrTail, lifecycle, session.launchObservation, adapter);
 			// error/abort on a reused session → drop it and close the child (GPT ④).
 			session.retiring = true;
 			retainedChildren.delete(session.child);

package/run.sh

@@ -1348,6 +1348,14 @@ check_acp_foreground_only() {
   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,
+  # and keep run_vitest's failed-title attribution for qualification.
+  section "ACP vendor rejection admission (mutant execution coordinate)"
+  run_vitest pi-extensions/lib/acp/backend-adapter.test.ts pi-extensions/lib/acp/backend.vendor-rejection.test.ts
+}
+
 check_pi_mcp_register() {
   # NOT a discovery path — check-tests-beside-behavior finds the test by glob. This case is the
   # MUTANT EXECUTION COORDINATE for scripts/mutants/pi-mcp-register.json (same reasoning as
@@ -1622,9 +1630,9 @@ smoke_acp_session_reuse_live() {
   # needs LIVE=1. Forces process-scoped (pushes --entwurf-control into argv) and
   # drives TWO real ACP turns over ONE reused claude-agent-acp child via the real
   # streamShellAcp: turn 1 introduces a codeword (full transcript), turn 2 sends
-  # ONLY the latest user delta and must recall the codeword — proving the child
-  # was reused and the live ACP session kept turn-1 history (a respawn-per-turn
-  # backend would forget it). The one-shot exit0 half is owned by
+  # ONLY the latest user delta. The REUSE lifecycle notice, with no new bootstrap,
+  # 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).
   #   LIVE=1 ./run.sh smoke-acp-session-reuse-live
@@ -7716,6 +7724,9 @@ case "$cmd" in
   check-acp-prompt-lifecycle)
     check_acp_prompt_lifecycle
     ;;
+  check-acp-vendor-rejection)
+    check_acp_vendor_rejection
+    ;;
   check-acp-launch-namespace)
     check_acp_launch_namespace
     ;;

package/scripts/check-gate-qualification.ts

@@ -3328,6 +3328,7 @@ let manifestCount: number;
 		"acp-stop-reason": 6,
 		"acp-stream-hooks": 10,
 		"acp-usage-accounting": 12,
+		"acp-vendor-rejection": 4,
 		"agy-permission": 6,
 		"bridge-boot-resume": 5,
 		"bridge-command-boot": 12,
@@ -3354,7 +3355,7 @@ let manifestCount: number;
 		"herdr-plugin": 25,
 		"herdr-plugin-profile": 14,
 		"herdr-activation": 25,
-		"herdr-plugin-build": 13,
+		"herdr-plugin-build": 14,
 		"herdr-runtime-bootstrap": 31,
 		"herdr-fresh-call": 38,
 		"herdr-supply": 11,

package/scripts/check-herdr-plugin-build.ts

@@ -53,6 +53,20 @@ const COMPILED_ENTRY = path.join("mcp", "entwurf-bridge", "dist", "mcp", "entwur
 const COMMIT_A = "a".repeat(40);
 const COMMIT_B = "b".repeat(40);
 
+// Fixture inputs, not registry assertions. The npm coherence check reads this checkout's
+// package.json, so its version is input; neither an unpublished version nor the committed
+// carrier may choose which source these deterministic cells exercise. No network is used.
+const FIXTURE_VERSION = (JSON.parse(fs.readFileSync(path.join(REPO, "package.json"), "utf8")) as { version: string })
+	.version;
+const FIXTURE_NPM_LOCK = Object.freeze({
+	source: "npm",
+	name: PACKAGE,
+	version: FIXTURE_VERSION,
+	integrity: `sha512-${createHash("sha512").update("hpb-npm-fixture").digest("base64")}`,
+});
+const FIXTURE_OTHER_INTEGRITY = `sha512-${createHash("sha512").update("hpb-npm-other-fixture").digest("base64")}`;
+const FIXTURE_CHECKOUT_LOCK = Object.freeze({ source: "herdr-checkout", repository: "junghan0611/entwurf" });
+
 interface SpawnResult {
 	status: number | null;
 	stdout: string;
@@ -175,9 +189,10 @@ function tree(root: string): string[] {
  */
 function fixtureAcquire(opts: { activate: "absent" | "incapable" | "recorder"; log?: string; fail?: boolean }) {
 	return ({ identity, prefix }: AcquireArgs) => {
+		const version = identity.version ?? FIXTURE_VERSION;
 		const root = path.join(prefix, "node_modules", PACKAGE);
 		fs.mkdirSync(path.join(root, path.dirname(COMPILED_ENTRY)), { recursive: true });
-		fs.writeFileSync(path.join(root, "package.json"), `${JSON.stringify({ name: PACKAGE, version: "0.21.0" })}\n`);
+		fs.writeFileSync(path.join(root, "package.json"), `${JSON.stringify({ name: PACKAGE, version })}\n`);
 		fs.writeFileSync(path.join(root, COMPILED_ENTRY), "// compiled entry fixture\n");
 		const bin = path.join(prefix, "node_modules", ".bin");
 		fs.mkdirSync(bin, { recursive: true });
@@ -208,7 +223,7 @@ function fixtureAcquire(opts: { activate: "absent" | "incapable" | "recorder"; l
 				.update(identity.commit ?? "x")
 				.digest("hex")}`,
 			packageName: PACKAGE,
-			packageVersion: "0.21.0",
+			packageVersion: version,
 		};
 	};
 }
@@ -249,6 +264,9 @@ function drive(
 			spawn,
 			write: (t: string) => (out += t),
 			progress,
+			// Existing gate-only seam. Production still reads the committed lock, and its
+			// real source/coherence is independently checked by check-herdr-runtime-bootstrap.
+			readRuntimeLock: () => FIXTURE_NPM_LOCK,
 			...deps,
 		});
 		return { code, refusal: null, out, progress: progressLines };
@@ -408,57 +426,121 @@ function drive(
 
 // ── 6. the two-stage journey, as the RUNNER composes it ────────────────────────
 {
-	const env = world("two-stage");
+	// Declared axes: both closed sources × {initial A, widened A, changed B, repeated B}.
+	// npm identity is the unchanged lock, not a commit; checkout identity IS the commit.
+	const cells = [FIXTURE_NPM_LOCK, FIXTURE_CHECKOUT_LOCK].map((lock) => {
+		const env = world(`two-stage-${lock.source}`);
+		const log = path.join(env.HOME as string, "argv.log");
+		let acquisitions = 0;
+		const counted = (args: AcquireArgs) => {
+			acquisitions++;
+			return fixtureAcquire({ activate: "recorder", log })(args);
+		};
+		const stages = [COMMIT_A, COMMIT_A, COMMIT_B, COMMIT_B].map((commit, index) => {
+			const rows: Record<string, string> = { pi: "current (v8) (/home/u/.pi)" };
+			if (index > 0) rows.claude = "current (v5) (/home/u/.claude)";
+			const result = drive(env, listing(rows), {
+				acquire: counted,
+				readRuntimeLock: () => lock,
+				resolveCommit: () => commit,
+			});
+			return { code: result.code, acquisitions };
+		});
+		const calls = fs.readFileSync(log, "utf8").trim().split("\n");
+		const { artifactIdentity: identity } = JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as {
+			artifactIdentity: Record<string, string>;
+		};
+		const expectedCounts = lock.source === "npm" ? [1, 1, 1, 1] : [1, 1, 2, 2];
+		const exactIdentity =
+			lock.source === "npm"
+				? identity.name === PACKAGE &&
+					identity.version === FIXTURE_VERSION &&
+					identity.expectedIntegrity === FIXTURE_NPM_LOCK.integrity
+				: identity.repository === FIXTURE_CHECKOUT_LOCK.repository &&
+					identity.commit === COMMIT_B &&
+					identity.packageName === PACKAGE &&
+					identity.packageVersion === FIXTURE_VERSION;
+		return {
+			source: lock.source,
+			stages,
+			calls,
+			identity,
+			passed:
+				stages.every((stage) => stage.code === 0) &&
+				JSON.stringify(stages.map((stage) => stage.acquisitions)) === JSON.stringify(expectedCounts) &&
+				JSON.stringify(calls) === JSON.stringify(["pi", "pi,claude-code", "pi,claude-code", "pi,claude-code"]) &&
+				identity.kind === lock.source &&
+				exactIdentity,
+		};
+	});
+	ok(
+		"[QK:HPB-SEQUENTIAL-TWO-STAGE] both closed sources hand down `{pi}` then the widened `{pi, claude-code}` " +
+			"on every reinstall, never OpenCode. An unchanged npm lock acquires once; checkout acquires again ONLY " +
+			"when A becomes B, and repeated B acquires nothing. Counts are exact at EACH step, not an aggregate lower " +
+			"bound. Installed identity must retain the input kind and its exact version/integrity or commit/completeness. " +
+			"The real writer bytes are HAC-TWO-STAGE-ADD-ONLY; this cell owns runner composition. " +
+			`Fixture identities do not claim registry acceptance (cells=${JSON.stringify(cells)})`,
+		cells.length === 2 && cells.every((cell) => cell.passed),
+	);
+}
+
+// ── 5b. the production default reader composes with the committed lock ─────────
+{
+	// Independent input oracle: read the committed JSON directly, not the runtime reader
+	// whose invocation this cell certifies. All acquisition/activation bytes remain fixture.
+	const committed = JSON.parse(fs.readFileSync(path.join(PLUGIN_DIR, "runtime-lock.json"), "utf8")) as
+		| { source: "npm"; name: string; version: string; integrity: string }
+		| { source: "herdr-checkout"; repository: string };
+	const env = world("default-lock-reader");
 	const log = path.join(env.HOME as string, "argv.log");
 	let acquisitions = 0;
-	const counted = (args: AcquireArgs) => {
-		acquisitions++;
-		return fixtureAcquire({ activate: "recorder", log })(args);
-	};
-	const stage1 = drive(env, listing({ pi: "current (v8) (/home/u/.pi)" }), {
-		acquire: counted,
-		resolveCommit: () => COMMIT_A,
-	});
-	const stage2 = drive(env, listing({ pi: "current (v8) (/home/u/.pi)", claude: "current (v5) (/home/u/.claude)" }), {
-		acquire: counted,
+	const acquire = fixtureAcquire({ activate: "recorder", log });
+	const result = drive(env, listing({ pi: "current (v8) (/home/u/.pi)" }), {
+		readRuntimeLock: undefined,
 		resolveCommit: () => COMMIT_A,
+		acquire: (args: AcquireArgs) => {
+			acquisitions++;
+			return acquire(args);
+		},
 	});
-	const stage3 = drive(env, listing({ pi: "current (v8) (/home/u/.pi)", claude: "current (v5) (/home/u/.claude)" }), {
-		acquire: counted,
-		resolveCommit: () => COMMIT_B,
-	});
-	const calls = fs.readFileSync(log, "utf8").trim().split("\n");
-	const journal = JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as {
-		artifactIdentity: { commit: string };
-	};
+	const journal = fs.existsSync(journalPathOf(env))
+		? (JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as { artifactIdentity: Record<string, string> })
+		: null;
+	const identity = journal?.artifactIdentity;
+	const exactIdentity =
+		identity !== undefined &&
+		identity.kind === committed.source &&
+		(committed.source === "npm"
+			? identity.name === committed.name &&
+				identity.version === committed.version &&
+				identity.expectedIntegrity === committed.integrity
+			: identity.repository === committed.repository &&
+				identity.commit === COMMIT_A &&
+				identity.packageName === PACKAGE &&
+				identity.packageVersion === FIXTURE_VERSION);
 	ok(
-		"[QK:HPB-SEQUENTIAL-TWO-STAGE] the sequence a real operator performs, as the runner composes it: `{pi}` first, " +
-			"then `{pi, claude-code}` after they integrated Claude Code, then a NEW commit of the same package version. " +
-			"The unchanged commit acquires nothing while still reconciling the widened set; the new commit reinstalls. " +
-			"OpenCode is present in every listing and appears in NO activation argv — the bytes those activations write " +
-			"are `check-herdr-activation`'s HAC-TWO-STAGE-ADD-ONLY, which drives the real Pi writers; what this cell owns " +
-			`is what the runner hands down (codes=${stage1.code}/${stage2.code}/${stage3.code} acquisitions=${acquisitions} calls=${JSON.stringify(calls)} commit=${journal.artifactIdentity.commit.slice(0, 8)})`,
-		stage1.code === 0 &&
-			stage2.code === 0 &&
-			stage3.code === 0 &&
-			acquisitions === 2 &&
-			JSON.stringify(calls) === JSON.stringify(["pi", "pi,claude-code", "pi,claude-code"]) &&
-			!calls.some((c) => c.includes("opencode")) &&
-			journal.artifactIdentity.commit === COMMIT_B,
+		"[QK:HPB-DEFAULT-LOCK-READ] without a reader override, runBuild reads this plugin's committed lock " +
+			"from PLUGIN_DIR, not the repository root or a synthetic fixture. The acquired identity retains the " +
+			"independently read source and exact artifact fields; installed activation still runs once for pi. " +
+			`This is composition proof, not registry acquisition (code=${result.code} refusal=${result.refusal} acquisitions=${acquisitions} identity=${JSON.stringify(identity)})`,
+		result.code === 0 &&
+			acquisitions === 1 &&
+			exactIdentity &&
+			fs.existsSync(log) &&
+			fs.readFileSync(log, "utf8") === "pi\n",
 	);
 }
 
 // ── 6a. the authority check happens BEFORE any runtime work ───────────────────
 {
-	const IDENTITY = (commit: string) => ({
-		kind: "herdr-checkout",
-		repository: "junghan0611/entwurf",
-		commit,
-		packageName: PACKAGE,
-		packageVersion: "0.21.0",
-		observedDigest: `sha256-${createHash("sha256").update(commit).digest("hex")}`,
+	const IDENTITY = (seed: string) => ({
+		kind: "npm",
+		name: PACKAGE,
+		version: FIXTURE_VERSION,
+		expectedIntegrity: FIXTURE_NPM_LOCK.integrity,
+		observedDigest: `sha256-${createHash("sha256").update(seed).digest("hex")}`,
 	});
-	/** A host that already has a runtime at commit A and a ledger that says so. */
+	/** A host with the explicit npm fixture installed and a ledger describing it. */
 	const seeded = (tag: string, backends: string[]): NodeJS.ProcessEnv => {
 		const env = world(tag);
 		const log = path.join(env.HOME as string, "argv.log");
@@ -468,12 +550,17 @@ function drive(
 		});
 		const states: Record<string, string> = {};
 		for (const b of backends) states[b] = "active";
+		const artifactIdentity = (
+			JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as {
+				artifactIdentity: Record<string, unknown>;
+			}
+		).artifactIdentity;
 		activation.writeLedger(
 			activation.resolveActivationLayout(env),
 			activation.ledgerBody({
 				phase: "active",
 				runtimeRoot: activeDirOf(env),
-				artifactIdentity: IDENTITY(COMMIT_A),
+				artifactIdentity,
 				roots: activation.resolveComponentRoots(env),
 				states,
 			}),
@@ -518,21 +605,22 @@ function drive(
 	const emptiedDirSeen = treeDigest(oracleRoot) !== oracleBase;
 	const oracleHonest = sameTree && sameLengthEditSeen && restored && modeSeen && emptiedDirSeen;
 
-	// (a) a SOURCE switch: the committed lock would now name npm over a checkout-sourced activation.
+	// (a) a SOURCE switch: the committed lock would name checkout over the active npm runtime.
 	// (a) is asked of the SHARED authority directly: the runner reads its lock from the committed
 	// file, and this gate does not add a seam that would let any caller choose the source.
 	const src = seeded("plan-source", ["pi"]);
 	const srcBefore = snapshot(src);
 	const srcRefusal = refusalOf(() =>
 		runner.certifyActivationPlan(src, {
-			lock: { source: "npm", name: PACKAGE, version: "0.21.0", integrity: "sha512-x" },
+			lock: { source: "herdr-checkout", repository: "junghan0611/entwurf" },
 			checkoutRoot: fixtureCheckoutRoot(),
 			requested: ["pi"],
+			resolveCommit: () => COMMIT_A,
 		}),
 	);
 	const srcUnchanged = unchanged(src, srcBefore);
 
-	// (b) a new commit whose request DROPS a backend the ledger holds.
+	// (b) a changed npm integrity whose request DROPS a backend the ledger holds.
 	const drop = seeded("plan-drop", ["pi", "claude-code"]);
 	const dropBefore = snapshot(drop);
 	let dropAcquired = 0;
@@ -541,6 +629,7 @@ function drive(
 			dropAcquired++;
 			return fixtureAcquire({ activate: "recorder", log: path.join(drop.HOME as string, "argv.log") })(args);
 		},
+		readRuntimeLock: () => ({ ...FIXTURE_NPM_LOCK, integrity: FIXTURE_OTHER_INTEGRITY }),
 		resolveCommit: () => COMMIT_B,
 	});
 
@@ -549,7 +638,17 @@ function drive(
 	const tornLedger = activation.resolveActivationLayout(torn).ledgerPath;
 	fs.writeFileSync(
 		tornLedger,
-		`${JSON.stringify({ ...(JSON.parse(fs.readFileSync(tornLedger, "utf8")) as Record<string, unknown>), artifactIdentity: IDENTITY(COMMIT_B) }, null, 2)}\n`,
+		`${JSON.stringify(
+			{
+				...(JSON.parse(fs.readFileSync(tornLedger, "utf8")) as Record<string, unknown>),
+				artifactIdentity: {
+					...IDENTITY(COMMIT_B),
+					expectedIntegrity: FIXTURE_OTHER_INTEGRITY,
+				},
+			},
+			null,
+			2,
+		)}\n`,
 	);
 	const tornBefore = snapshot(torn);
 	let tornAcquired = 0;
@@ -561,14 +660,13 @@ function drive(
 		resolveCommit: () => COMMIT_A,
 	});
 
-	// (d) the LEGAL case still passes: same source, new commit, request covers the ledger. The
-	// authority is asked on the PRE-install state, which is the only state it is ever asked about.
+	// (d) the LEGAL case still passes: same exact npm source and lock, request covers the ledger.
+	// The authority is asked on the PRE-install state, which is the only state it is ever asked about.
 	const legal = seeded("plan-legal", ["pi"]);
 	const legalPlan = runner.certifyActivationPlan(legal, {
-		lock: { source: "herdr-checkout", repository: "junghan0611/entwurf" },
-		checkoutRoot: fixtureCheckoutRoot(),
+		lock: FIXTURE_NPM_LOCK,
+		checkoutRoot: REPO,
 		requested: ["pi"],
-		resolveCommit: () => COMMIT_B,
 	});
 	const legalDrive = drive(legal, listing({ pi: "current (v8) (/home/u/.pi)" }), {
 		acquire: fixtureAcquire({ activate: "recorder", log: path.join(legal.HOME as string, "argv.log") }),
@@ -577,7 +675,7 @@ function drive(
 
 	ok(
 		"[QK:HPB-PRE-BOOTSTRAP-AUTHORITY] the activation authority is asked BEFORE any runtime work, through the SAME " +
-			"shipped functions the installed verb runs: a source switch, a new commit whose request drops an activated " +
+			"shipped functions the installed verb runs: a source switch, a request that drops an activated " +
 			"backend, and a ledger that already disagrees with the runtime standing there are each refused with the " +
 			"runtime tree, its journal, our cache, the ledger and the activation log ALL byte-identical and the " +
 			"acquisition never called. The first cut bootstrapped first and let the installed verb refuse afterwards, " +
@@ -596,7 +694,7 @@ function drive(
 			tornAcquired === 0 &&
 			unchanged(torn, tornBefore) &&
 			legalDrive.code === 0 &&
-			legalPlan.disposition === "rebind",
+			legalPlan.disposition === "match",
 	);
 }
 
@@ -607,15 +705,19 @@ function drive(
 	const commits = [COMMIT_A, COMMIT_B, COMMIT_B];
 	let call = 0;
 	const moving = () => commits[Math.min(call++, commits.length - 1)] as string;
+	// Candidate source is a closed, retained branch. This test seam does not expose a caller input:
+	// production `runBuild` reads only the committed lock, while the gate drives the branch whose
+	// identity can move between D1 and D2.
 	const drifted = drive(env, listing({ pi: "current (v8) (/home/u/.pi)" }), {
 		acquire: fixtureAcquire({ activate: "recorder", log }),
+		readRuntimeLock: () => FIXTURE_CHECKOUT_LOCK,
 		resolveCommit: moving,
 	});
 	const journal = JSON.parse(fs.readFileSync(journalPathOf(env), "utf8")) as { artifactIdentity: { commit: string } };
 	const activated = fs.existsSync(log) ? fs.readFileSync(log, "utf8").trim() : "";
 	ok(
 		"[QK:HPB-BOOTSTRAP-IDENTITY-EXACT] the artifact that lands must be EXACTLY the one the authority check admitted: " +
-			"when the source moves between the judgement and the install, the run refuses by name instead of handing the " +
+			"when the candidate source moves between the judgement and the install, the run refuses by name instead of handing the " +
 			"installed activation verb a different artifact than the one this build was cleared to place — the verb would " +
 			"then re-judge, and pass or fail on a question nobody asked. The refusal is honest about what did happen: the " +
 			`runtime was replaced, and NO activation ran (refusal=${drifted.refusal} landed=${journal.artifactIdentity.commit.slice(0, 8)} admitted=${COMMIT_A.slice(0, 8)} activations=${JSON.stringify(activated)})`,
@@ -709,7 +811,7 @@ function drive(
 	ok(
 		"[QK:HPB-PROGRESS-NAMED-SEQUENCE] a build narrates the five steps IN ORDER and names the long one — herdr pipes " +
 			"both of this process's streams into a buffer it DISCARDS on success (`src/cli/plugin.rs:1328-1373` @ c77af189), " +
-			"so an operator who has just answered the install prompt sees nothing at all through a multi-minute `npm pack` " +
+			"so an operator who has just answered the install prompt sees nothing at all through a multi-minute registry fetch " +
 			"and reads it as a hang. The sequence is reported, not logged: each step names the work about to start, the " +
 			"acquisition step says out loud that silence is expected and which source it is reaching for, and a run with " +
 			"nothing to activate takes exactly ONE step and then closes — it must not narrate work it never did. " +
@@ -721,7 +823,7 @@ function drive(
 			full.progress[0].includes("integration status") &&
 			full.progress[1].includes("pi, claude-code") &&
 			longStep.includes("long step") &&
-			longStep.includes(COMMIT_A.slice(0, 8)) &&
+			longStep.includes(`${PACKAGE}@${FIXTURE_VERSION}`) &&
 			full.progress[3].includes("what landed") &&
 			full.progress[4].includes("wiring pi, claude-code") &&
 			full.progress[5].startsWith("done: ") &&

package/scripts/fixtures/herdr-supply.json

@@ -1,10 +1,10 @@
 {
 	"$comment": "SSOT for the herdr binary this repository has MEASURED against. Nothing else may carry a version or a digest: the CI installer, the sandbox gate's boundary check and the launch-rail document all read or cite this file. Re-measuring a new herdr means running check-herdr-sandbox against it FIRST, then editing this file, then repairing the measured sentences in docs/herdr-launch-rail.md in the same commit — miss one and the gate fails on version mismatch, which is the point.",
-	"version": "0.9.1",
-	"tag": "v0.9.1",
-	"tagCommit": "065ef9d6a531c49fb8bee7e818ef837065b21ee9",
+	"version": "0.9.3",
+	"tag": "v0.9.3",
+	"tagCommit": "7b116c05bfda646af39d2524c54e70c751f57ee8",
 	"socketProtocol": 22,
-	"measuredOn": "2026-09-17",
+	"measuredOn": "2026-10-03",
 	"measuredArch": "aarch64",
 	"releaseUrlPrefix": "https://github.com/herdrdev/herdr/releases/download",
 	"integrity": {
@@ -15,15 +15,15 @@
 	"assets": {
 		"x86_64": {
 			"name": "herdr-linux-x86_64",
-			"sha256": "2a02fed16beb651ef006e1d43f048f652ca4dc58ad053cd2d44450563d5c54b7",
+			"sha256": "18a8dc65f1c2fa485884344356dea1cfd911c6f06cf46fa78e193f4087f4dba7",
 			"executed": false,
-			"executedNote": "pending the first CI run on an x86_64 runner — the digest is pinned, but no cell of this rail has ever run on this binary"
+			"executedNote": "pending the first CI run on an x86_64 runner — the digest is pinned (and named by GitHub's release attestation for pkg:github/herdrdev/herdr@v0.9.3), but no cell of this rail has ever run on this binary"
 		},
 		"aarch64": {
 			"name": "herdr-linux-aarch64",
-			"sha256": "f4ccf4de745f2cb9a39a983e9ba3703dad50ec2a58dea83026ceab721bbd8d9e",
+			"sha256": "4de7aa3e25678812e92960de64f7c2aaa1bca1f0f80a3c5e559837e231e1f5c0",
 			"executed": true,
-			"executedNote": "the #116 rail was re-measured on this exact binary on 2026-09-17: `check-herdr-sandbox` green, `herdr status client` reports protocol 22 (unchanged from 0.9.0), and `integration status` adds exactly one row — `letta (experimental)` — with every other row byte-identical to 0.9.0. The operator host still runs the 0.9.0 asset at that date; the binary measured here was fetched by digest into a temp dir"
+			"executedNote": "the #116 rail was re-measured on this exact binary on 2026-10-03 (#126), fetched by digest through scripts/install-herdr-ci.sh into a temp dir and run from an isolated snapshot whose manifest named it: `check-herdr-sandbox` green (12 assertions, private server), `herdr status client` reports protocol 22 (unchanged from 0.9.1), and `integration status` prints the same 18 rows as 0.9.1 in a sandbox HOME once that root path is normalized; pi (v9) and claude (v10) integrations installed by 0.9.1 read `current` under 0.9.3 and a 0.9.3 reinstall leaves their bytes identical. The operator host still runs the 0.9.1 asset at that date and was not touched. The 0.9.1 receipt (2026-09-17) stays dated in docs/herdr-launch-rail.md"
 		}
 	}
 }