@junghanacs/entwurf 0.22.0 → 0.23.1

package/scripts/check-herdr-sandbox.ts

@@ -0,0 +1,456 @@
+/**
+ * check-herdr-sandbox — REAL herdr acceptance for the #116 launch rail (C2a).
+ *
+ * This is the half `check-herdr-fresh-call` cannot judge. That gate pins argv, encoding,
+ * parsing and the reclaim decision without a binary; here a PRIVATE herdr server creates a real
+ * tab, starts a real blank pi in its initial pane, and the assertions read what herdr and our own
+ * record store actually produced. There is no fake herdr anywhere in this repo, for the same reason there is
+ * no fake tmux (`scripts/check-mux-placement.ts:6-9`): a stand-in authors the contract before
+ * anything is measured.
+ *
+ * ISOLATION IS THE PRECONDITION, AND IT HAS TWO ROOTS. `[측정 2026-09-14]` herdr's integration
+ * and the meta-record store follow `PI_CODING_AGENT_DIR`, while the entwurf control socket
+ * follows `HOME` (`<HOME>/.pi/entwurf-control/`). Sandbox one and the other writes into the
+ * operator's tree, so both are sandboxed here, the child starts from an EXPLICIT environment
+ * (no inherited `PI_SESSION_ID`/`PI_AGENT_ID`/auth), and the operator's own herdr panes are
+ * snapshotted read-only before and after and must be identical.
+ *
+ * WHY `--approve` IS IN THE FIXTURE AND NOT IN THE RAIL. `[측정 2026-09-14]` a fresh HOME has no
+ * `trust.json`, so pi parks on `Trust project folder?` and waits for a KEYSTROKE — which this
+ * product never sends. `pi --approve` ("Trust project-local files for this run") clears that for
+ * one run and `[측정]` writes NO trust file. The gate is the operator of its own sandbox, so it
+ * may authorise its own fixture. Production argv must never carry it: `project-trust-handler.ts`
+ * records "an agent cannot self-promote trust" as an intended security asymmetry, and a launcher
+ * approving on the operator's behalf would quietly take that judgement away from them.
+ *
+ * ADMISSION. herdr is an OPTIONAL rail, so a host without the binary prints a named SKIP and
+ * exits 0 — a deterministic surface has no third outcome, and a silent pass would let green lie.
+ * A host WITH herdr that cannot complete the cell FAILS: absent is optional, broken is not.
+ * `ENTWURF_REQUIRE_HERDR=1` turns absence itself into a failure. C2b is wired: CI installs the
+ * exact asset owned by `scripts/fixtures/herdr-supply.json` through
+ * `scripts/install-herdr-ci.sh` before `check:full`; this gate then makes an absent binary red.
+ *
+ * Each claim carries its QK token on exactly ONE assertion.
+ *
+ *   HS-VERSION-BOUNDARY     the measured herdr compatibility boundary is pinned, not assumed
+ *   HS-SANDBOX-ISOLATED     the private server answers on its own socket and the child's
+ *                           environment carries no operator identity
+ *   HS-ONE-SEED             ONE checkout package registration loads entwurf's pi extension
+ *   HS-NO-TRUST-WRITE       the fixture's `--approve` leaves no trust state behind
+ *   HS-OFFICIAL-TRIPLE      herdr's direct witness carries source+agent+shape, not a bare value
+ *   HS-EXACT-ONE-RECORD     that witness resolves to exactly one sandbox V3 record
+ *   HS-CONTROL-SOCKET-ALIVE the citizen's control socket answers the production probe
+ *   HS-CLOSE-REFUSES-LIVE   the conditional close refuses a pane that has an agent
+ *   HS-CLOSE-RECLAIMS       the same decision closes a pane we own with no agent, and that
+ *                           reclaims the tab it was the whole of
+ *   HS-NO-RESIDUE           server stop leaves no socket, no process and no tree
+ *   HS-OPERATOR-UNTOUCHED   the operator's panes and pi config are identical afterwards
+ */
+
+import assert from "node:assert/strict";
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	buildHerdrPaneCloseArgs,
+	buildHerdrPaneGetArgs,
+	buildHerdrTabCreateArgs,
+	decideConditionalClose,
+	parseHerdrAgentStartResponse,
+	parseHerdrPaneGetResponse,
+	parseHerdrTabCreateResponse,
+} from "../pi-extensions/lib/herdr-fresh-call.ts";
+import { joinKeyOf, parseHerdrPaneList } from "../pi-extensions/lib/herdr-placement.ts";
+import { probeSocketLiveness } from "../pi-extensions/lib/socket-probe.ts";
+
+const LABEL = "check-herdr-sandbox";
+const REPO_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The ONE herdr line this rail has been measured against — READ from the supply manifest, never
+ * spelled here. A constant in this file was the drift hole C2a shipped: CI could install one
+ * version while the gate expected another and nothing would say so. Now the installer and this
+ * boundary read the same file, so they cannot disagree. A different line is not a silent pass and
+ * not a skip: it is a FAILURE that asks for a re-measurement. */
+const SUPPLY_MANIFEST = "scripts/fixtures/herdr-supply.json";
+const OWNING_DOC = "docs/herdr-launch-rail.md";
+
+interface HerdrSupply {
+	readonly version: string;
+	readonly tag: string;
+	readonly assets: Readonly<Record<string, { readonly name: string; readonly sha256: string }>>;
+}
+
+function readSupply(): HerdrSupply {
+	return JSON.parse(fs.readFileSync(path.join(REPO_DIR, SUPPLY_MANIFEST), "utf8")) as HerdrSupply;
+}
+
+/** Absence of an optional rail is not a defect — but it must be visible. */
+const SKIP_MARKER = "[entwurf:herdr-rail-skip]";
+/** How a future CI turns "no herdr here" into red without changing this file. */
+const REQUIRE_ENV = "ENTWURF_REQUIRE_HERDR";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+function skip(reason: string): never {
+	console.log(`${SKIP_MARKER} ${LABEL} — ${reason}`);
+	console.log(
+		`${SKIP_MARKER} herdr is an OPTIONAL rail: this cell did not run. Set ${REQUIRE_ENV}=1 to make its absence a failure.`,
+	);
+	process.exit(0);
+}
+
+function fail(reason: string): never {
+	console.error(`[${LABEL}] FAIL — ${reason}`);
+	process.exit(1);
+}
+
+/** PATH lookup without a shell: the gate's own admission decision must not depend on how a
+ * shell would have quoted anything. */
+function which(bin: string): string | null {
+	for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+		if (dir.length === 0) continue;
+		const candidate = path.join(dir, bin);
+		try {
+			fs.accessSync(candidate, fs.constants.X_OK);
+			if (fs.statSync(candidate).isFile()) return candidate;
+		} catch {
+			// Not here, or not executable by us. Keep walking.
+		}
+	}
+	return null;
+}
+
+interface Sandbox {
+	readonly root: string;
+	readonly agentDir: string;
+	readonly env: NodeJS.ProcessEnv;
+}
+
+/** The child's whole environment, stated rather than inherited. `PATH` and `TERM` are the only
+ * things carried across, and every identity/auth carrier the operator's shell holds is simply
+ * not in this map. */
+function makeSandbox(bin: string): Sandbox {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), "entwurf-herdr-gate."));
+	const agentDir = path.join(root, "pi-agent");
+	for (const dir of [".config", ".state", ".data", ".cache", "pi-agent"]) {
+		fs.mkdirSync(path.join(root, dir), { recursive: true });
+	}
+	// The ONE seed: this checkout, registered as a pi package, so the extension under test is
+	// the source in this working tree and not an installed copy of some other version.
+	fs.writeFileSync(path.join(agentDir, "settings.json"), `${JSON.stringify({ packages: [REPO_DIR] }, null, 2)}\n`);
+	return {
+		root,
+		agentDir,
+		env: {
+			PATH: `${path.dirname(bin)}:${process.env.PATH ?? ""}`,
+			TERM: "xterm-256color",
+			HOME: root,
+			XDG_CONFIG_HOME: path.join(root, ".config"),
+			XDG_STATE_HOME: path.join(root, ".state"),
+			XDG_DATA_HOME: path.join(root, ".data"),
+			XDG_CACHE_HOME: path.join(root, ".cache"),
+			PI_CODING_AGENT_DIR: agentDir,
+		},
+	};
+}
+
+function herdr(
+	bin: string,
+	sandbox: Sandbox,
+	args: readonly string[],
+): { status: number; stdout: string; stderr: string } {
+	const run = spawnSync(bin, [...args], { encoding: "utf8", env: sandbox.env, timeout: 120_000 });
+	return { status: run.status ?? 1, stdout: run.stdout ?? "", stderr: run.stderr ?? "" };
+}
+
+/** The operator's own panes, read WITHOUT the sandbox environment. An operator with no server
+ * running is a valid state — it just has to be the same state afterwards. */
+function operatorPanes(bin: string): string {
+	const run = spawnSync(bin, ["pane", "list"], { encoding: "utf8", timeout: 30_000 });
+	if ((run.status ?? 1) !== 0) return "no-operator-server";
+	const rows = parseHerdrPaneList(run.stdout ?? "");
+	if (rows === null) return "unreadable";
+	return JSON.stringify(rows.map((row) => [row.paneId, row.agent, row.sessionKind, row.sessionValue]).sort());
+}
+
+function sleep(ms: number): void {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function waitForSocket(file: string, timeoutMs: number): boolean {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (fs.existsSync(file)) return true;
+		sleep(100);
+	}
+	return false;
+}
+
+/** Linux-only: a process still holding the sandbox HOME after `server stop`. Elsewhere the
+ * socket/tree checks stand alone and this one reports `null` rather than guessing. */
+function sandboxProcesses(root: string): number | null {
+	if (process.platform !== "linux") return null;
+	let count = 0;
+	for (const entry of fs.readdirSync("/proc")) {
+		if (!/^\d+$/.test(entry)) continue;
+		try {
+			const environ = fs.readFileSync(`/proc/${entry}/environ`, "utf8");
+			if (environ.split("\0").includes(`HOME=${root}`)) count++;
+		} catch {
+			// The process exited while we were reading it, which is the state we wanted anyway.
+		}
+	}
+	return count;
+}
+
+async function main(): Promise<void> {
+	console.log(`[${LABEL}]`);
+	const required = process.env[REQUIRE_ENV] === "1";
+
+	const bin = which("herdr");
+	if (bin === null) {
+		if (required) fail(`${REQUIRE_ENV}=1 but no herdr binary is on PATH`);
+		skip("no herdr binary on PATH");
+	}
+
+	const supply = readSupply();
+	const version = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 30_000 });
+	const versionText = `${version.stdout ?? ""}`.trim();
+	if ((version.status ?? 1) !== 0) fail(`herdr is on PATH at ${bin} but \`herdr --version\` failed: ${version.stderr}`);
+	ok(
+		`[QK:HS-VERSION-BOUNDARY] the herdr under test is the EXACT version the supply manifest pins (${supply.version}) — the gate and the CI installer read that one file, so an installed version and an expected version cannot drift apart silently; ${OWNING_DOC} owns why that version, ${SUPPLY_MANIFEST} owns which`,
+		versionText.includes(`herdr ${supply.version}`),
+	);
+
+	const pi = which("pi");
+	if (pi === null) {
+		// Present-but-incomplete is a failure, not a skip: the rail IS here, and a green run
+		// would claim a cell that never happened.
+		fail(`herdr is installed (${bin}) but pi is not on PATH — the herdr rail is present and incomplete`);
+	}
+
+	const before = operatorPanes(bin);
+	const operatorTrust = path.join(os.homedir(), ".pi", "agent", "trust.json");
+	const operatorTrustBefore = fs.existsSync(operatorTrust) ? fs.statSync(operatorTrust).mtimeMs : null;
+
+	const sandbox = makeSandbox(bin);
+	const serverLog = fs.openSync(path.join(sandbox.root, "server.log"), "a");
+	const server = spawn(bin, ["server"], {
+		cwd: sandbox.root,
+		env: sandbox.env,
+		detached: true,
+		stdio: ["ignore", serverLog, serverLog],
+	});
+	server.unref();
+
+	let cleanupDone = false;
+	const stopServer = (): void => {
+		if (cleanupDone) return;
+		cleanupDone = true;
+		herdr(bin, sandbox, ["server", "stop"]);
+		sleep(2000);
+	};
+
+	try {
+		const socketPath = path.join(sandbox.root, ".config", "herdr", "herdr.sock");
+		if (!waitForSocket(socketPath, 20_000)) fail(`the private herdr server never opened ${socketPath}`);
+
+		const listed = herdr(bin, sandbox, ["pane", "list"]);
+		const sandboxRows = parseHerdrPaneList(listed.stdout);
+		ok(
+			"[QK:HS-SANDBOX-ISOLATED] the private server answers on its OWN socket under the sandbox root, and the operator's panes are not in its listing — two servers, no shared state",
+			listed.status === 0 &&
+				sandboxRows !== null &&
+				fs.existsSync(socketPath) &&
+				!socketPath.startsWith(os.homedir()) &&
+				sandbox.env.PI_SESSION_ID === undefined &&
+				sandbox.env.PI_AGENT_ID === undefined,
+		);
+
+		const install = herdr(bin, sandbox, ["integration", "install", "pi"]);
+		const extension = path.join(sandbox.agentDir, "extensions", "herdr-agent-state.ts");
+		if (install.status !== 0 || !fs.existsSync(extension)) {
+			fail(`\`herdr integration install pi\` did not land in the sandbox (${extension}): ${install.stderr}`);
+		}
+
+		const ws = herdr(bin, sandbox, ["workspace", "create", "--label", "entwurf-gate", "--no-focus", "--cwd", REPO_DIR]);
+		if (ws.status !== 0) fail(`workspace create failed in the sandbox: ${ws.stderr}`);
+
+		// The production placement argv, with the production identity scrub, against a real
+		// server: the workspace comes from herdr's own answer about the pane we are standing in,
+		// exactly as the rail resolves it, never from the `w1:` prefix of an id.
+		const callerGet = herdr(bin, sandbox, buildHerdrPaneGetArgs("w1:p1"));
+		const callerPane = callerGet.status === 0 ? parseHerdrPaneGetResponse(callerGet.stdout) : null;
+		if (callerPane?.workspaceId === undefined) {
+			fail(`pane get of the caller pane failed or carried no workspace: ${callerGet.stderr || callerGet.stdout}`);
+		}
+		const tabRun = herdr(bin, sandbox, buildHerdrTabCreateArgs({ workspaceId: callerPane.workspaceId, cwd: REPO_DIR }));
+		const tab = tabRun.status === 0 ? parseHerdrTabCreateResponse(tabRun.stdout) : null;
+		if (tab === null) fail(`tab create failed or was unreadable: ${tabRun.stderr || tabRun.stdout}`);
+		const tabRootPane = tab.rootPane;
+
+		// `--approve` is the fixture's own one-run authorisation; `--entwurf-control` is the
+		// production citizenship flag. No prompt, no model, no credentials.
+		const start = herdr(bin, sandbox, [
+			"agent",
+			"start",
+			"entwurfgate",
+			"--kind",
+			"pi",
+			"--pane",
+			tabRootPane.paneId,
+			"--",
+			"--approve",
+			"--entwurf-control",
+		]);
+		if (start.status !== 0) fail(`blank pi did not start in the sandbox: ${start.stderr || start.stdout}`);
+
+		const startedPane = parseHerdrAgentStartResponse(start.stdout);
+		const startJson = JSON.parse(start.stdout) as {
+			result?: {
+				argv?: string[];
+				agent?: { agent_session?: { agent?: string; kind?: string; source?: string; value?: string } };
+			};
+		};
+		const session = startJson.result?.agent?.agent_session;
+		const joinKey =
+			session === undefined
+				? null
+				: joinKeyOf({
+						paneId: tabRootPane.paneId,
+						agent: session.agent ?? null,
+						sessionSource: session.source ?? null,
+						sessionKind: session.kind === "id" || session.kind === "path" ? session.kind : null,
+						sessionValue: session.value ?? null,
+					});
+		ok(
+			"[QK:HS-OFFICIAL-TRIPLE] the direct witness is an OFFICIAL herdr report — source, agent and the shape that source is measured to emit — and the production join leaf converts pi's session PATH to the native id rather than accepting a bare value",
+			startedPane !== null &&
+				session !== undefined &&
+				session.source === "herdr:pi" &&
+				session.agent === "pi" &&
+				session.kind === "path" &&
+				joinKey !== null &&
+				joinKey.backend === "pi" &&
+				(session.value ?? "").includes(joinKey.nativeSessionId),
+		);
+		ok(
+			"[QK:HS-ONE-SEED] ONE checkout package registration is the whole seed — entwurf's pi extension loaded from this working tree, and the fixture's argv reached pi byte-identical",
+			JSON.stringify(startJson.result?.argv) === JSON.stringify(["pi", "--approve", "--entwurf-control"]) &&
+				(JSON.parse(fs.readFileSync(path.join(sandbox.agentDir, "settings.json"), "utf8")) as { packages: string[] })
+					.packages.length === 1,
+		);
+
+		const storeDir = path.join(sandbox.agentDir, "meta-sessions");
+		const records = fs.existsSync(storeDir) ? fs.readdirSync(storeDir).filter((f) => f.endsWith(".meta.json")) : [];
+		const holders = records
+			.map((f) => JSON.parse(fs.readFileSync(path.join(storeDir, f), "utf8")) as Record<string, unknown>)
+			.filter((r) => r.nativeSessionId === joinKey?.nativeSessionId);
+		const record = holders[0];
+		ok(
+			"[QK:HS-EXACT-ONE-RECORD] the witness resolves to EXACTLY ONE V3 record in the sandbox store, carrying the backend and cwd it was launched with — no model turn and no credential was needed to mint it",
+			records.length === 1 &&
+				holders.length === 1 &&
+				record?.schemaVersion === 3 &&
+				record?.backend === "pi" &&
+				record?.cwd === REPO_DIR,
+		);
+		ok(
+			"[QK:HS-NO-TRUST-WRITE] the fixture's one-run --approve left NO trust state behind — the sandbox has no trust.json, so this authorisation cannot leak into any later run",
+			!fs.existsSync(path.join(sandbox.agentDir, "trust.json")),
+		);
+
+		const controlSocket = path.join(sandbox.root, ".pi", "entwurf-control", `${String(record?.gardenId)}.sock`);
+		const socketExists = fs.existsSync(controlSocket) && fs.statSync(controlSocket).isSocket();
+		const liveness = socketExists ? await probeSocketLiveness(controlSocket, { timeoutMs: 2000 }) : "dead";
+		ok(
+			"[QK:HS-CONTROL-SOCKET-ALIVE] the citizen's control socket answers the PRODUCTION probe — existence and `stat` are a separate, weaker fact, and only the probe says alive",
+			socketExists && liveness === "alive",
+		);
+
+		// ── the conditional close, against a real server ─────────────────────────────────
+		const liveGet = herdr(bin, sandbox, buildHerdrPaneGetArgs(tabRootPane.paneId));
+		const liveDecision = decideConditionalClose(
+			tabRootPane,
+			liveGet.status === 0 ? parseHerdrPaneGetResponse(liveGet.stdout) : null,
+			liveGet.status !== 0,
+		);
+		// THE REAL SERVER IS WHAT MAKES THIS CELL WORTH RUNNING, and 2026-09-18 is why: the
+		// refusal used to be spelled `agent-session-present`, which only fires once herdr has been
+		// TOLD the pane's session id. On the Claude rail that id arrives through a separate hook the
+		// child makes after it starts, so a pane holding a booted sibling read as empty and was
+		// closed. OCCUPANCY — herdr naming an AGENT in the pane — is the refusal now, and it does
+		// not depend on anybody having reported a session. Both facts are asserted: against a live
+		// pi citizen herdr has both, and the one that must carry the refusal is the first.
+		ok(
+			"[QK:HS-CLOSE-REFUSES-LIVE] the reclaim decision REFUSES a pane that now holds an agent, naming agent-present — occupancy alone, because a sibling whose session id herdr has not been told yet is still a sibling, and a living one is never closed by the path that exists to clean up a failed launch",
+			liveDecision.close === false && liveDecision.reason === "agent-present",
+		);
+		{
+			const live = liveGet.status === 0 ? parseHerdrPaneGetResponse(liveGet.stdout) : null;
+			ok(
+				"a real live citizen gives herdr BOTH facts — the agent label and the session report — and the refusal above is keyed to the one that arrives first",
+				live?.agent !== undefined && live?.hasAgentSession === true,
+			);
+		}
+
+		const spareRun = herdr(bin, sandbox, buildHerdrTabCreateArgs({ workspaceId: callerPane.workspaceId }));
+		const spareTab = spareRun.status === 0 ? parseHerdrTabCreateResponse(spareRun.stdout) : null;
+		if (spareTab === null)
+			fail(`the second tab create failed or was unreadable: ${spareRun.stderr || spareRun.stdout}`);
+		const sparePane = spareTab.rootPane;
+		const spareGet = herdr(bin, sandbox, buildHerdrPaneGetArgs(sparePane.paneId));
+		const spareDecision = decideConditionalClose(
+			sparePane,
+			spareGet.status === 0 ? parseHerdrPaneGetResponse(spareGet.stdout) : null,
+			spareGet.status !== 0,
+		);
+		const closeRun = spareDecision.close ? herdr(bin, sandbox, buildHerdrPaneCloseArgs(sparePane.paneId)) : null;
+		const afterClose = herdr(bin, sandbox, ["pane", "list"]);
+		const remaining = parseHerdrPaneList(afterClose.stdout) ?? [];
+		// `[측정 2026-09-15]` closing the sole pane of a tab takes the tab with it — so the same
+		// pane-level authority the rail already had is enough to reclaim a tab it created, and
+		// `tab close` (a bare tab id, no ownership token) never has to be reached for.
+		const remainingTabs = herdr(bin, sandbox, ["tab", "list"]);
+		ok(
+			"[QK:HS-CLOSE-RECLAIMS] the SAME decision closes a pane we own that has no agent — proof within one server generation, not a bare pane id — and closing that sole pane reclaims the tab it was the whole of, with no `tab close` and no empty tab left behind",
+			spareDecision.close === true &&
+				closeRun !== null &&
+				closeRun.status === 0 &&
+				!remaining.some((row) => row.paneId === sparePane.paneId) &&
+				remainingTabs.status === 0 &&
+				!remainingTabs.stdout.includes(`"${spareTab.tabId}"`),
+		);
+
+		stopServer();
+		ok(
+			"[QK:HS-NO-RESIDUE] stopping the private server reclaims its socket and leaves no process holding the sandbox — the fixture owns its own teardown",
+			!fs.existsSync(socketPath) && (sandboxProcesses(sandbox.root) ?? 0) === 0,
+		);
+	} finally {
+		stopServer();
+		fs.rmSync(sandbox.root, { recursive: true, force: true });
+		try {
+			fs.closeSync(serverLog);
+		} catch {
+			// Already closed with the process; nothing here depends on it.
+		}
+	}
+
+	const operatorTrustAfter = fs.existsSync(operatorTrust) ? fs.statSync(operatorTrust).mtimeMs : null;
+	ok(
+		"[QK:HS-OPERATOR-UNTOUCHED] the operator's herdr panes and pi trust store are byte-identical afterwards — the whole cell happened somewhere else",
+		operatorPanes(bin) === before && operatorTrustAfter === operatorTrustBefore && !fs.existsSync(sandbox.root),
+	);
+
+	console.log(`\n[${LABEL}] ${passed} assertions ok (private ${versionText})`);
+}
+
+await main();

package/scripts/check-herdr-supply.ts

@@ -0,0 +1,184 @@
+/**
+ * check-herdr-supply — the herdr binary CI runs is the one this repository MEASURED (#116 C2b).
+ *
+ * No herdr binary is needed here, and no network: every cell below reads the supply manifest,
+ * the installer and the workflow as text. That is the point — this gate judges the SUPPLY
+ * AUTHORITY (who decides which bytes), while `check-herdr-sandbox` judges what those bytes do.
+ *
+ * WHY A MANIFEST INSTEAD OF A CONSTANT. C2a hardcoded `0.9.` inside the sandbox gate. A CI job
+ * installing some other version would have satisfied the gate's own skip/fail logic while the
+ * boundary check silently compared against a version nobody had installed — a drift with no
+ * observer. One file now owns version, tag and per-architecture digest; the installer and the
+ * gate both read it; and this gate refuses a second copy anywhere else.
+ *
+ * WHAT THE INTEGRITY EVIDENCE ACTUALLY IS, so nobody upgrades the claim later:
+ * `[측정 2026-09-14]` GitHub publishes an IMMUTABLE-RELEASE attestation (in-toto
+ * `release/v0.2`) listing each asset's digest for `pkg:github/herdrdev/herdr@v0.9.0`. That is
+ * GitHub signing "these digests are this tag's assets" — it is NOT a SLSA build provenance
+ * authored by herdr and NOT a reproducible-build proof. `[측정, gh 2.97.0]` `gh attestation
+ * verify` cannot close that predicate, so the installer depends on a pinned sha256 and never on
+ * that CLI. Our own digest is therefore the load-bearing check, with the attestation as
+ * corroboration a human can pull through the REST API.
+ *
+ * Each claim carries its QK token on exactly ONE assertion.
+ *
+ *   HSUP-MANIFEST-SSOT        version/tag/digests exist ONLY in the manifest
+ *   HSUP-DIGEST-SHAPE         every pinned digest is a full sha256 and they are distinct
+ *   HSUP-ARCH-FAIL-CLOSED     an unmeasured architecture is refused, never approximated
+ *   HSUP-VERIFY-BEFORE-CHMOD  the digest is checked while the file is still inert
+ *   HSUP-NO-MUTABLE-SUPPLY    no curl-pipe, no `latest`, no package manager, no global install
+ *   HSUP-NO-ATTESTATION-CLI   the installer does not depend on `gh attestation verify`
+ *   HSUP-CI-INSTALL-BEFORE-FLOOR  CI installs the pinned binary before the floor runs
+ *   HSUP-CI-REQUIRES-HERDR    that floor runs with absence turned red
+ *   HSUP-CI-LINUX-ONLY        only the Linux check job takes this; the other jobs are untouched
+ *   HSUP-SETUP-NEVER-INSTALLS the product's own setup/package never installs herdr (Rule 17)
+ *   HSUP-X86-UNEXECUTED       the x86_64 asset is pinned but recorded as never executed
+ */
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const MANIFEST_PATH = "scripts/fixtures/herdr-supply.json";
+const INSTALLER_PATH = "scripts/install-herdr-ci.sh";
+const CI_PATH = ".github/workflows/ci.yml";
+const SANDBOX_GATE_PATH = "scripts/check-herdr-sandbox.ts";
+
+const read = (rel: string): string => readFileSync(path.join(REPO_DIR, rel), "utf8");
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+interface Supply {
+	version: string;
+	tag: string;
+	tagCommit: string;
+	measuredOn: string;
+	measuredArch: string;
+	releaseUrlPrefix: string;
+	assets: Record<string, { name: string; sha256: string; executed: boolean; executedNote: string }>;
+}
+
+function main(): void {
+	console.log("[check-herdr-supply]");
+
+	const manifestText = read(MANIFEST_PATH);
+	const supply = JSON.parse(manifestText) as Supply;
+	const installer = read(INSTALLER_PATH);
+	const ci = read(CI_PATH);
+	const sandboxGate = read(SANDBOX_GATE_PATH);
+
+	const digests = Object.values(supply.assets).map((a) => a.sha256);
+
+	// ── the manifest is the only copy ────────────────────────────────────────────────────
+	// Searching the whole tree would trip over this gate's own prose, so the set is the
+	// files that could actually ACT on a wrong number: the installer, the workflow, and the
+	// gate whose boundary check reads it.
+	const consumers = [installer, ci, sandboxGate];
+	ok(
+		"[QK:HSUP-MANIFEST-SSOT] the version, the tag and every digest live ONLY in the manifest — the installer, the workflow and the sandbox gate READ it and none of them carries a second copy that could drift",
+		consumers.every((text) => !digests.some((d) => text.includes(d))) &&
+			!installer.includes(supply.version) &&
+			!ci.includes(supply.version) &&
+			!sandboxGate.includes(`"${supply.version}"`) &&
+			installer.includes(MANIFEST_PATH) &&
+			sandboxGate.includes(MANIFEST_PATH),
+	);
+	ok(
+		"[QK:HSUP-DIGEST-SHAPE] every pinned digest is a full lowercase sha256 and no two architectures share one — a truncated or duplicated digest is a check that cannot fail",
+		digests.length >= 2 &&
+			digests.every((d) => /^[0-9a-f]{64}$/.test(d)) &&
+			new Set(digests).size === digests.length &&
+			/^[0-9a-f]{40}$/.test(supply.tagCommit) &&
+			supply.tag === `v${supply.version}`,
+	);
+
+	// ── the installer's own refusals ─────────────────────────────────────────────────────
+	ok(
+		"[QK:HSUP-ARCH-FAIL-CLOSED] an architecture the manifest does not carry is REFUSED by name — there is no nearest-match binary, and a CI runner we have never measured must not silently get one",
+		/if \(!asset\) \{/.test(installer) &&
+			installer.includes("unsupported architecture") &&
+			installer.includes("no measured herdr asset for"),
+	);
+
+	const shaIndex = installer.indexOf("sha256sum");
+	const chmodIndex = installer.indexOf("chmod +x");
+	const curlIndex = installer.indexOf("curl -fsSL");
+	ok(
+		"[QK:HSUP-VERIFY-BEFORE-CHMOD] the digest is verified while the downloaded file is still inert data, and only then is it made executable — a byte we did not choose never becomes something the job can run",
+		curlIndex > 0 && shaIndex > curlIndex && chmodIndex > shaIndex && installer.includes('rm -f "$target"'),
+	);
+	// The installer's comments NAME every rejected supply path, which is the point of them —
+	// so these cells read the code with comments stripped. A guard that banned the words would
+	// have forced the reasons out of the file.
+	const installerCode = installer.replace(/^\s*#.*$/gm, "");
+	ok(
+		"[QK:HSUP-NO-MUTABLE-SUPPLY] the installer's CODE contains no curl-pipe, no `latest`, no package manager and no global install location — each of those would make a green run a claim about a binary nobody chose",
+		!/curl[^\n]*\|\s*(sh|bash)/.test(installerCode) &&
+			!installerCode.includes("/latest/") &&
+			!/\b(brew|mise|nix-env|npm i -g|sudo)\b/.test(installerCode) &&
+			!installerCode.includes(".local/bin") &&
+			installerCode.includes("RUNNER_TEMP"),
+	);
+	ok(
+		"[QK:HSUP-NO-ATTESTATION-CLI] the installer does not depend on `gh attestation verify` — measured on gh 2.97.0 it cannot close herdr's in-toto release predicate, and a check we cannot run is not a check",
+		!installerCode.includes("gh attestation") &&
+			manifestText.includes("in-toto.io/attestation/release/v0.2") &&
+			manifestText.includes("NOT a SLSA build provenance"),
+	);
+
+	// ── the CI wiring ────────────────────────────────────────────────────────────────────
+	const installIndex = ci.indexOf("./scripts/install-herdr-ci.sh");
+	const floorIndex = ci.indexOf("- run: pnpm run check:full");
+	ok(
+		"[QK:HSUP-CI-INSTALL-BEFORE-FLOOR] CI installs the pinned binary BEFORE the deterministic floor — installing after it would leave the herdr cell skipping in the one place it is supposed to be required",
+		installIndex > 0 && floorIndex > installIndex,
+	);
+	const floorStep = ci.slice(floorIndex, floorIndex + 200);
+	ok(
+		"[QK:HSUP-CI-REQUIRES-HERDR] that floor runs with ENTWURF_REQUIRE_HERDR=1, so an absent binary is red in CI while it stays an explicit SKIP on an operator's machine",
+		/ENTWURF_REQUIRE_HERDR:\s*"1"/.test(floorStep),
+	);
+	ok(
+		"[QK:HSUP-CI-LINUX-ONLY] exactly one job installs herdr and it is the Linux check job — the install-surface, artifact-consumer and macOS jobs are unchanged, because this rail is certified on Linux only",
+		ci.split("./scripts/install-herdr-ci.sh").length - 1 === 1 &&
+			ci.slice(0, installIndex).lastIndexOf("runs-on: ubuntu-latest") >
+				ci.slice(0, installIndex).lastIndexOf("\n  check:") - 1 &&
+			installIndex < ci.indexOf("  install-surface:") &&
+			installIndex < ci.indexOf("  macos-install-surface:"),
+	);
+
+	// ── the product never supplies someone else's bytes ──────────────────────────────────
+	const pkg = JSON.parse(read("package.json")) as { scripts: Record<string, string>; bin?: Record<string, string> };
+	const scriptText = Object.values(pkg.scripts).join(" ");
+	ok(
+		"[QK:HSUP-SETUP-NEVER-INSTALLS] no product script and no shipped bin reaches the CI installer — Entwurf supplies Entwurf's bytes, never a placement owner's (Hard Rule 17), and this file is job scaffolding rather than a surface",
+		!scriptText.includes("install-herdr-ci") &&
+			!Object.values(pkg.bin ?? {}).some((p) => p.includes("install-herdr-ci")) &&
+			// run.sh DESCRIBES the supply gate in a comment; what matters is that no dispatch
+			// path runs the installer. Read the code, not the prose — banning the word would
+			// only push the explanation out of the file.
+			!read("run.sh")
+				.replace(/^\s*#.*$/gm, "")
+				.includes("install-herdr-ci"),
+	);
+
+	// ── honesty about what has actually run ──────────────────────────────────────────────
+	ok(
+		"[QK:HSUP-X86-UNEXECUTED] the x86_64 asset is pinned but RECORDED AS NEVER EXECUTED — every measurement in this lane ran on aarch64, so a pinned digest must not read as evidence that the cell passes on the other architecture",
+		supply.assets.x86_64?.executed === false &&
+			supply.assets.aarch64?.executed === true &&
+			supply.measuredArch === "aarch64" &&
+			(supply.assets.x86_64?.executedNote ?? "").length > 0,
+	);
+
+	console.log(`\n[check-herdr-supply] ${passed} assertions ok`);
+}
+
+main();