@junghanacs/entwurf 0.21.0 → 0.23.0

package/scripts/check-peer-facts.ts

@@ -0,0 +1,331 @@
+/**
+ * check-peer-facts — deterministic gate for the #116 M2-a observed-peer projection
+ * (`entwurf peer-facts` / scripts/peer-facts.ts).
+ *
+ * Drives the REAL CLI as a subprocess against sandboxed fixtures — every root it can
+ * reach is an explicit mkdtemp dir (store, control-socket dir, HOME, XDG_DATA_HOME, pi
+ * agent dir), so the operator's live store, sockets and markers are never read. What it
+ * proves, and why each claim is its own contract rather than a restatement:
+ *
+ *   - `placement` crosses as the STRUCTURED tagged union, never the human `herdr <pane>`
+ *     string. A machine consumer joins on `paneId`; a string forces it to re-parse a
+ *     presentation decision;
+ *   - the peer keyset is EXACTLY the provider's own facts — no herdr `agent_status` or any
+ *     other display verdict may enter an entwurf payload, because that is the one door
+ *     through which "observed activity" could drift into delivery liveness;
+ *   - no socket coordinate is published: `ENTWURF_DIR` is an INPUT to the probe, never an
+ *     output — #50 C4 retired the legacy listing together with the `controlDir` it exposed;
+ *   - `diagnostics` survive the projection in-band (a readable store with hazards is a fact
+ *     to report, not a reason to emit a clean-looking listing);
+ *   - the control-socket world actually probed is the one `ENTWURF_DIR` names — proved
+ *     BEHAVIOURALLY (a record-less socket in the fixture dir must surface as a diagnostic),
+ *     not by echoing the field back;
+ *   - no observation budget: a rationed row says `unobserved`, which in a machine payload
+ *     is indistinguishable from "no herdr on this host";
+ *   - an unreadable store is exit 3 with NO JSON, a missing store is a readable empty one,
+ *     bad argv is exit 2;
+ *   - the surface is reachable: run.sh dispatches it and the bridge build emits its
+ *     compiled twin (the installed-host fence).
+ *
+ * The placement join itself, the one-read-per-listing rule and the peers payload keyset are
+ * NOT re-proved here — they belong to check-herdr-placement, check-entwurf-fact-provider and
+ * check-entwurf-peers-surface. This gate owns only what this verb adds.
+ *
+ * The gate spawns the CLI rather than importing its pieces because the exit code and stdout
+ * bytes ARE the contract a consumer holds. Every [QK:PF-*] token appears exactly once, on
+ * the assertion that fails for that claim. No herdr binary, no network, no model turn.
+ */
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { type MetaIdentity, serializeMetaIdentity } from "../pi-extensions/lib/meta-session.ts";
+import { reclaimOnExit } from "./lib/reclaim-on-exit.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const REPO = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+
+const GID_PI = "20260611T111111-aaaaaa";
+const GID_CLAUDE = "20260611T222222-bbbbbb";
+/** A garden id no record in any fixture claims — its socket must be DEMOTED to a diagnostic. */
+const GID_ORPHAN_SOCKET = "20260611T333333-cccccc";
+
+function tmp(prefix: string): string {
+	return reclaimOnExit(fs.mkdtempSync(path.join(os.tmpdir(), `entwurf-peer-facts-${prefix}-`)));
+}
+
+function record(gardenId: string, over: Partial<MetaIdentity> = {}): string {
+	return serializeMetaIdentity({
+		schemaVersion: 3,
+		gardenId,
+		backend: "pi",
+		nativeSessionId: `n-${gardenId}`,
+		cwd: "/x",
+		model: "provider/model",
+		transcriptPath: null,
+		createdAt: "2026-06-11T00:00:00.000Z",
+		recordUpdatedAt: "2026-06-11T00:00:00.000Z",
+		...over,
+	});
+}
+
+function store(files: Record<string, string>): string {
+	const dir = tmp("store");
+	for (const [name, body] of Object.entries(files)) fs.writeFileSync(path.join(dir, name), body);
+	return dir;
+}
+
+interface CliRun {
+	status: number | null;
+	stdout: string;
+	stderr: string;
+}
+
+/**
+ * Every ambient root this verb or the provider beneath it could reach is replaced. HOME and
+ * XDG_DATA_HOME move together: moving HOME alone still writes/reads real install-state below
+ * the inherited XDG root, which is exactly how a verification sweep once polluted a live host.
+ */
+function cli(args: string[], env: Record<string, string> = {}): CliRun {
+	const home = tmp("home");
+	const res = spawnSync(process.execPath, ["--experimental-strip-types", "scripts/peer-facts.ts", ...args], {
+		cwd: REPO,
+		encoding: "utf8",
+		env: {
+			...process.env,
+			HOME: home,
+			XDG_DATA_HOME: path.join(home, ".local", "share"),
+			PI_CODING_AGENT_DIR: path.join(home, ".pi", "agent"),
+			ENTWURF_DIR: tmp("control"),
+			// A herdr read here would be a child process and a live-host dependency. The
+			// provider's own gate owns that axis; this one must stay hermetic.
+			HERDR_ENV: "0",
+			...env,
+		},
+	});
+	return { status: res.status, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+interface Placement {
+	kind: string;
+	paneId?: string;
+}
+interface Peer {
+	gardenId: string;
+	backend: string;
+	cwd: string;
+	placement: Placement;
+	transcript: string;
+	[k: string]: unknown;
+}
+interface Projection {
+	schemaVersion: number;
+	storeDir: string;
+	peers: Peer[];
+	diagnostics: { kind: string; message: string }[];
+}
+
+function parseProjection(run: CliRun, label: string): Projection {
+	assert.equal(run.status, 0, `${label}: exit 0 (stderr: ${run.stderr})`);
+	return JSON.parse(run.stdout) as Projection;
+}
+
+// ── the projection carries the provider's facts, addressably ────────────────
+{
+	const transcriptDir = tmp("transcripts");
+	const transcript = path.join(transcriptDir, "live.jsonl");
+	fs.writeFileSync(transcript, "{}\n");
+
+	const dir = store({
+		[`${GID_PI}.meta.json`]: record(GID_PI),
+		[`${GID_CLAUDE}.meta.json`]: record(GID_CLAUDE, {
+			backend: "claude-code",
+			nativeSessionId: "ce224ad7-9e29-41a5-81c3-08e09f017802",
+			transcriptPath: transcript,
+		}),
+	});
+	const facts = parseProjection(cli([dir]), "valid store");
+
+	ok(
+		"projection declares schemaVersion 1 and echoes the store it was told to read",
+		facts.schemaVersion === 1 && facts.storeDir === dir,
+	);
+	// Deliberately does NOT inspect `placement`: the shape of that field is the next
+	// assertion's own claim, and a generic check here would steal its kill.
+	ok(
+		"both citizens cross with the identity fields a renderer needs",
+		facts.peers.length === 2 &&
+			facts.peers.every(
+				(p) => typeof p.gardenId === "string" && typeof p.backend === "string" && typeof p.cwd === "string",
+			),
+	);
+
+	// PLACEMENT STAYS STRUCTURED. `unobserved` is the only value reachable without a herdr
+	// host, and that is enough: the human rendering of THAT value is the bare string
+	// "unobserved", so a projection that stringified it would be caught right here.
+	const placements = facts.peers.map((p) => p.placement);
+	assert.ok(
+		placements.every(
+			(pl) => typeof pl === "object" && pl !== null && !Array.isArray(pl) && typeof pl.kind === "string",
+		),
+		'[QK:PF-PLACEMENT-STRUCTURED] placement crosses as the tagged union object ({kind:…}), never the human "herdr <pane>" / bare-kind string a renderer would have to re-parse',
+	);
+	console.log("  ok    placement crosses as the tagged union object, never the human string");
+	passed++;
+	ok(
+		"no herdr on this host reads as unobserved, not none",
+		placements.every((pl) => pl.kind === "unobserved"),
+	);
+
+	// THE PROMOTION BARRIER. herdr owns idle/working/blocked/done and it is a screen verdict;
+	// the moment one of those words enters an entwurf payload it is one rename away from
+	// being read as delivery liveness. So the keyset is pinned EXACTLY, not by denylist.
+	const PEER_KEYS = [
+		"backend",
+		"createdAt",
+		"cwd",
+		"gardenId",
+		"liveness",
+		"model",
+		"nativeSessionId",
+		"placement",
+		"receiver",
+		"recordUpdatedAt",
+		"transcript",
+	];
+	for (const peer of facts.peers) {
+		assert.deepEqual(
+			Object.keys(peer).sort(),
+			PEER_KEYS,
+			"[QK:PF-PEER-KEYSET-EXACT] a peer row carries exactly the provider's own facts — no herdr agent_status / interactive_ready / screen verdict may enter an entwurf payload, because that is the door observed activity would use to become delivery liveness",
+		);
+	}
+	console.log("  ok    a peer row carries exactly the provider's own facts, with no herdr display verdict");
+	passed++;
+	// FOUR, not five: the control dir is an INPUT to the probe and never an output. #50 C4
+	// retired the legacy projection "with the `controlDir` it exposed" — the record is the
+	// sole address axis and a socket path is dispatch-internal transport. A new verb may not
+	// quietly republish it.
+	assert.deepEqual(
+		Object.keys(facts as unknown as Record<string, unknown>).sort(),
+		["diagnostics", "peers", "schemaVersion", "storeDir"],
+		"[QK:PF-NO-SOCKET-COORDINATE] the projection publishes no socket coordinate — #50 C4 retired the legacy listing WITH the controlDir it exposed, because the record is the sole address axis and a socket path is dispatch-internal transport; a new verb that republishes it undoes that retirement while looking like a convenience",
+	);
+	console.log("  ok    the projection publishes no socket coordinate (four documented fields)");
+	passed++;
+
+	// NO OBSERVATION BUDGET. A rationed row says `unobserved`; in a machine payload that is
+	// indistinguishable from "nobody could look". The live transcript below is the witness:
+	// under a budget it would read `unobserved` instead of `exists`.
+	const claude = facts.peers.find((p) => p.gardenId === GID_CLAUDE);
+	assert.ok(
+		claude !== undefined && claude.transcript === "exists",
+		"[QK:PF-NO-OBSERVATION-BUDGET] every row is observed — a presentation budget would emit `unobserved` for rows nobody chose to skip, which a machine consumer cannot tell apart from `nobody could look`",
+	);
+	console.log("  ok    every row is observed — no presentation budget rations a machine projection");
+	passed++;
+
+	const again = parseProjection(cli([dir]), "re-run");
+	ok("output is byte-deterministic across runs", JSON.stringify(again.peers) === JSON.stringify(facts.peers));
+}
+
+// ── diagnostics ride in-band, they are not a reason to look clean ───────────
+{
+	const dir = store({
+		[`${GID_PI}.meta.json`]: record(GID_PI),
+		[`${GID_CLAUDE}.meta.json`]: "{ not json",
+	});
+	const facts = parseProjection(cli([dir]), "store with a defect");
+	ok("a readable store with an uncertifiable entry still reports its healthy citizen", facts.peers.length === 1);
+	assert.ok(
+		facts.diagnostics.some((d) => d.kind === "meta-record-read-error"),
+		"[QK:PF-DIAGNOSTICS-PRESERVED] the provider's diagnostics cross the projection in-band — dropping them turns a store with hazards into a clean-looking listing at exit 0",
+	);
+	console.log("  ok    the provider's diagnostics cross the projection in-band");
+	passed++;
+}
+
+// ── the socket world probed is the one ENTWURF_DIR names, proved behaviourally ──
+{
+	const dir = store({ [`${GID_PI}.meta.json`]: record(GID_PI) });
+	const control = tmp("control-seeded");
+	// Not a listening socket — a plain file with the socket grammar. The probe fails, the
+	// liveness is `dead`, and the point stands: this path was READ. A verb that ignored
+	// ENTWURF_DIR would probe the sandbox HOME's default dir and report nothing here.
+	fs.writeFileSync(path.join(control, `${GID_ORPHAN_SOCKET}.sock`), "");
+
+	const facts = parseProjection(cli([dir], { ENTWURF_DIR: control }), "seeded control dir");
+	// The proof has to be behavioural precisely BECAUSE the dir is not emitted: there is no
+	// field to read back, so the witness is what the probe found in it.
+	ok(
+		"the probed dir is not echoed into the payload",
+		!Object.hasOwn(facts as unknown as Record<string, unknown>, "controlDir"),
+	);
+	assert.ok(
+		facts.diagnostics.some((d) => d.kind === "record-less-socket" && d.message.length > 0),
+		"[QK:PF-CONTROL-DIR-PROBED] the socket world actually probed is the one ENTWURF_DIR names — the same override the bridge honours, so this verb and entwurf_peers can never answer from two different socket worlds",
+	);
+	console.log("  ok    the socket world probed is the one ENTWURF_DIR names");
+	passed++;
+}
+
+// ── the exit contract ───────────────────────────────────────────────────────
+{
+	const missing = path.join(tmp("absent"), "no-such-store");
+	const run = cli([missing]);
+	const facts = parseProjection(run, "missing store");
+	ok("a store that does not exist is a readable EMPTY store, exit 0", facts.peers.length === 0);
+
+	// An unreadable store must never be mistakable for an empty one, so the refusal is both
+	// a distinct exit code AND an empty stdout — a consumer that only reads stdout still
+	// cannot parse a false success out of it.
+	const unreadable = tmp("unreadable");
+	fs.writeFileSync(path.join(unreadable, "blocker"), "");
+	fs.chmodSync(unreadable, 0o000);
+	const denied = cli([unreadable]);
+	fs.chmodSync(unreadable, 0o700);
+	assert.ok(
+		denied.status === 3 && denied.stdout === "",
+		`[QK:PF-EXIT-UNREADABLE] an unreadable store is exit 3 with no JSON — answering it as exit 0 would make an unreadable host look like an empty one (got ${denied.status}, stdout ${JSON.stringify(denied.stdout.slice(0, 80))})`,
+	);
+	console.log("  ok    an unreadable store is exit 3 with no JSON");
+	passed++;
+
+	const flag = cli(["--help"]);
+	assert.ok(
+		flag.status === 2 && flag.stdout === "",
+		"[QK:PF-USAGE] a dash argv is a flag this command does not have — reading it as a store directory would answer `--help` with `empty store, exit 0`, a silent wrong fact",
+	);
+	console.log("  ok    a dash argv is a usage error, not a store directory");
+	passed++;
+	ok("a second positional is a usage error", cli(["/a", "/b"]).status === 2);
+}
+
+// ── the surface is reachable from an installed host ─────────────────────────
+{
+	const runSh = fs.readFileSync(path.join(REPO, "run.sh"), "utf8");
+	ok(
+		"run.sh dispatches peer-facts through the single run_ts fence",
+		/\n {2}peer-facts\)\n(?:.*\n)*?\s*run_ts scripts\/peer-facts\.ts "\$@"\n/.test(runSh),
+	);
+	ok("run.sh documents peer-facts in its usage block", runSh.includes("./run.sh peer-facts "));
+	const build = fs.readFileSync(path.join(REPO, "mcp/entwurf-bridge/tsconfig.build.json"), "utf8");
+	ok(
+		"the bridge build emits the compiled twin (installed hosts cannot strip-types)",
+		build.includes('"../../scripts/peer-facts.ts"'),
+	);
+	ok(
+		"both pack artifact lists carry the compiled twin",
+		(runSh.match(/"mcp\/entwurf-bridge\/dist\/scripts\/peer-facts\.js"/g) ?? []).length === 2,
+	);
+}
+
+console.log(`\ncheck-peer-facts: ${passed} assertions passed`);

package/scripts/check-release-gate-outcomes.ts

@@ -304,6 +304,18 @@ function runSubcommand(sub: string, env: Record<string, string | undefined>): {
 		// NOT waived: its direct call stays required for a Cortex-rail cut, and running
 		// it without the connection still reports protocol SKIP rather than a pass.
 		"smoke-acp-cortex-live": ["VERIFY.md", "The release aggregate does not re-certify Cortex"],
+		// #116 C4: first evidence precedes promotion. The herdr rail's LIVE acceptance exists and
+		// runs on demand, but a rail whose first real acceptance run is days old has not earned a
+		// place in the aggregate that blocks every cut — and herdr is an OPTIONAL rail, so a cut
+		// on a host without it would block for a capability the product does not require.
+		"smoke-herdr-fresh-call-live": ["VERIFY.md", "The release aggregate does not yet require the herdr rail"],
+		// #116 M3-b3, same rail and the same reason: the plugin build smoke drives a REAL
+		// `herdr plugin install` over the network. herdr is optional, so an aggregate that required it
+		// would block a cut on a host that does not have the rail at all. Its first LIVE acceptance
+		// landed 2026-09-16 (5 assertions, 0 skipped) — one run is evidence the axis works, not the run
+		// history that earns a place in the gate blocking every cut. On-demand, with the exclusion
+		// stated where an operator reads it.
+		"smoke-herdr-plugin-build-live": ["VERIFY.md", "The release aggregate does not require the plugin build smoke"],
 	};
 
 	const allLive = globSync("scripts/smoke-*live*.{ts,sh}", { cwd: REPO_DIR })

package/scripts/check-typing-call-fence.ts

@@ -0,0 +1,296 @@
+/**
+ * check-typing-call-fence — the boundary nobody has broken yet, kept by NAME.
+ *
+ * THE RULE: this product composes ARGUMENTS and LETTERS, never keystrokes. It is written in two
+ * places already — `docs/herdr-launch-rail.md` §3 ("키 입력(`agent prompt`): 터미널 입력이다") and
+ * `pi-extensions/lib/herdr-fresh-call.ts:28` — and until now nothing but prose held it.
+ *
+ * WHY A GATE FOR A RULE NOBODY BROKE `[외부 관측 2026-09-17 19:35]`. An outside reader measured the
+ * tree and found the law perfectly kept and nothing keeping it: zero typing calls across
+ * `pi-extensions/`, and zero checks and zero mutants that would notice one arriving. Gates here grow
+ * on top of incidents, and this boundary was named and refused at DESIGN time, so it never produced
+ * the failure that would have produced a test. A rule kept since day one is the most defenceless
+ * kind: the green that covers it means only "nobody has broken it yet".
+ *
+ * WHAT A TYPING CALL IS. Anything that reaches a sibling by writing into the place a HUMAN types:
+ * tmux `send-keys` / `paste-buffer` / `load-buffer`, and herdr's PTY verbs — `agent.prompt`,
+ * `agent.send_keys`, `pane.send_text`, `pane.input.set`. `[측정 2026-09-18, herdr @ 7505c08]` those
+ * herdr verbs are not an API delivery with an acknowledgement: `src/app/api/agents.rs:195` hands the
+ * text to `encode_api_submission_parts`, `src/app/api_helpers.rs:25-32` wraps it in bracketed paste,
+ * and the bytes go to the child pane's PTY followed 300 ms later by an encoded Enter. What is
+ * acknowledged is that input was written — herdr's own help says it "does not track turns". That is
+ * exactly what Hard Rule 16 keeps out of delivery evidence.
+ *
+ * SCOPE. The production surfaces `pi-extensions/` and `mcp/`, tracked files only (so the gitignored
+ * `mcp/entwurf-bridge/dist/` build output is not scanned twice as its own source). This gate lives
+ * in `scripts/`, which is NOT in scope — a gate that scanned itself could only be made green by
+ * deleting the names it exists to forbid.
+ *
+ * COMMENTS ARE EXEMPT, AND THAT IS LOAD-BEARING. The sentence stating the rule contains the very
+ * names the rule forbids. A scanner that read prose would be red on the rule itself, and the
+ * cheapest way to green would be deleting the sentence — the gate would eat its own law. So every
+ * file is reduced to CODE (string literals kept, comments blanked) before the names are looked for.
+ *
+ *   TYPEFENCE-PRODUCTION-CLEAN  no production module under pi-extensions/ or mcp/ carries a typing
+ *                               call in code. A module that acquires one is refused by name.
+ *
+ * The three assertions before it are this gate's own oracle: the detector is proven to SEE each
+ * forbidden name in planted code, proven NOT to see it in prose, and the scanned inventory is
+ * measured rather than assumed — without those, "zero hits" and "looked at nothing" read the same.
+ *
+ * WHAT THIS GATE DOES NOT CATCH, NAMED RATHER THAN IMPLIED (sol D3, 2026-09-18). It reads SPELLINGS.
+ * A typing call assembled at runtime — `["send", "keys"].join("-")`, a template with the verb in a
+ * variable, an RPC method built from parts — passes it, and no wording of this scanner would change
+ * that without becoming a dataflow analysis.
+ *
+ * That limit is accepted rather than closed, and the reason is what this gate is FOR. It is a
+ * tripwire for the slip: a module that reaches for the vendor's typing verb because the argv route
+ * looked harder that afternoon, written the ordinary way, spelled out. It is not a defence against
+ * somebody deliberately hiding one, and a gate that claimed to be would be the more dangerous
+ * object — the claim above therefore says CARRIES a typing call spelled out, not "composes" one.
+ * The defence against deliberate evasion is review, and the rule it enforces is in
+ * `docs/herdr-launch-rail.md` §3 where a human reads it.
+ */
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+let passed = 0;
+function ok(label: string, cond: boolean, detail = ""): void {
+	assert.ok(cond, detail ? `${label}\n${detail}` : label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+/** Each forbidden name, with the surface it belongs to. A pattern matches CODE only. */
+const TYPING_CALLS: readonly { readonly name: string; readonly pattern: RegExp; readonly surface: string }[] = [
+	{ name: "send-keys", pattern: /send-keys/, surface: "tmux / herdr CLI" },
+	{ name: "send_keys", pattern: /send_keys/, surface: "herdr agent.send_keys" },
+	{ name: "paste-buffer", pattern: /paste-buffer/, surface: "tmux" },
+	{ name: "load-buffer", pattern: /load-buffer/, surface: "tmux (feeds paste-buffer)" },
+	{ name: "send-text / send_text", pattern: /send[-_]text/, surface: "herdr pane.send_text" },
+	{ name: '"agent.prompt"', pattern: /["'`]agent\.prompt["'`]/, surface: "herdr JSON-RPC method" },
+	{ name: '"pane.input.set"', pattern: /["'`]pane\.input\.set["'`]/, surface: "herdr JSON-RPC method" },
+	{ name: '"agent","prompt"', pattern: /["'`]agent["'`]\s*,\s*["'`]prompt["'`]/, surface: "herdr CLI argv" },
+];
+
+type Flavor = "c" | "shell";
+
+/**
+ * Blank every comment, keep every code byte — including string literals, because a typing call
+ * spelled as a string IS the call. Offsets are preserved so a hit still reports its own line.
+ */
+function codeOnly(src: string, flavor: Flavor): string {
+	const out = src.split("");
+	let state: "code" | "line" | "block" | "sq" | "dq" | "tpl" = "code";
+	let i = 0;
+	while (i < src.length) {
+		const c = src[i];
+		const n = src[i + 1];
+		if (state === "code") {
+			if (flavor === "c" && c === "/" && n === "/") {
+				state = "line";
+				out[i] = " ";
+				out[i + 1] = " ";
+				i += 2;
+				continue;
+			}
+			if (flavor === "c" && c === "/" && n === "*") {
+				state = "block";
+				out[i] = " ";
+				out[i + 1] = " ";
+				i += 2;
+				continue;
+			}
+			// POSIX: `#` opens a comment only at the start of a word, so `${VAR#prefix}` is code.
+			if (flavor === "shell" && c === "#" && (i === 0 || /\s/.test(src[i - 1]))) {
+				state = "line";
+				out[i] = " ";
+				i += 1;
+				continue;
+			}
+			if (c === "'") state = "sq";
+			else if (c === '"') state = "dq";
+			else if (c === "`" && flavor === "c") state = "tpl";
+			i += 1;
+			continue;
+		}
+		if (state === "line") {
+			if (c === "\n") state = "code";
+			else out[i] = " ";
+			i += 1;
+			continue;
+		}
+		if (state === "block") {
+			if (c === "*" && n === "/") {
+				out[i] = " ";
+				out[i + 1] = " ";
+				state = "code";
+				i += 2;
+				continue;
+			}
+			if (c !== "\n") out[i] = " ";
+			i += 1;
+			continue;
+		}
+		// inside a string literal: bytes are kept, escapes consume the next byte
+		if (c === "\\") {
+			i += 2;
+			continue;
+		}
+		if ((state === "sq" && c === "'") || (state === "dq" && c === '"') || (state === "tpl" && c === "`")) {
+			state = "code";
+		}
+		i += 1;
+	}
+	return out.join("");
+}
+
+type Hit = { readonly file: string; readonly line: number; readonly name: string; readonly text: string };
+
+function scan(rel: string, src: string, flavor: Flavor): Hit[] {
+	const code = codeOnly(src, flavor);
+	const rawLines = src.split("\n");
+	const hits: Hit[] = [];
+	code.split("\n").forEach((codeLine, idx) => {
+		for (const call of TYPING_CALLS) {
+			if (call.pattern.test(codeLine)) {
+				hits.push({ file: rel, line: idx + 1, name: call.name, text: rawLines[idx].trim() });
+			}
+		}
+	});
+	return hits;
+}
+
+const flavorOf = (rel: string): Flavor => (rel.endsWith(".sh") ? "shell" : "c");
+
+// ── 1. the detector sees a planted typing call in code ──────────────────────
+{
+	const plantedTs = [
+		'const argv = ["send-keys", "-t", pane, text];',
+		'await run(["paste-buffer", "-t", pane]);',
+		'await run(["load-buffer", "-b", buf]);',
+		'const m = "agent.send_keys";',
+		'const t = "pane.send_text";',
+		'const p = "agent.prompt";',
+		'const i = "pane.input.set";',
+		'const cli = ["agent", "prompt", target, text];',
+	].join("\n");
+	const found = new Set(scan("fixture.ts", plantedTs, "c").map((h) => h.name));
+	ok(
+		`the detector names all ${TYPING_CALLS.length} typing calls planted in code (a green scan means it looked, not that it is blind)`,
+		found.size === TYPING_CALLS.length,
+		`missed: ${TYPING_CALLS.map((c) => c.name)
+			.filter((n) => !found.has(n))
+			.join(", ")}`,
+	);
+	ok(
+		"the shell flavor sees a typing call too — a launcher script is production surface",
+		scan("fixture.sh", 'tmux send-keys -t "$PANE" "$TEXT"\n', "shell").length === 1,
+	);
+	ok(
+		"a `${VAR#prefix}` expansion does not blind the shell scan for the rest of its line",
+		scan("fixture.sh", 'name="${PANE#%}"; tmux send-keys -t "$name" x\n', "shell").length === 1,
+	);
+}
+
+// ── 2. prose is exempt — the rule's own sentence must survive its own gate ──
+{
+	const prose = [
+		"// keystrokes (`agent prompt`) are terminal input, which this product does not use to launch.",
+		"/* tmux send-keys and paste-buffer are the shape this fence refuses. */",
+		'const real = "fine";',
+	].join("\n");
+	ok(
+		"a typing call NAMED in a comment is not a violation — otherwise the cheapest green would be deleting the sentence that states the rule",
+		scan("fixture.ts", prose, "c").length === 0,
+	);
+	ok(
+		"the same exemption in shell comments",
+		scan("fixture.sh", "# tmux send-keys is refused here\nexec node x.js\n", "shell").length === 0,
+	);
+	// The live sentence, read from the rail itself rather than quoted here: if it is ever reworded
+	// the exemption must be re-proved against what the file ACTUALLY says. Only the sentence is
+	// scanned — whether the module as a whole is clean is the LAW's claim below, not this one's.
+	const railLine = fs
+		.readFileSync(path.join(REPO, "pi-extensions/lib/herdr-fresh-call.ts"), "utf8")
+		.split("\n")
+		.find((l) => l.includes("keystrokes (`agent prompt`)"));
+	ok(
+		"the launch rail's own written rule names `agent prompt` and is exempt as the prose it is",
+		railLine !== undefined && scan("rail-rule", railLine, "c").length === 0,
+	);
+}
+
+// ── 3. the scanned inventory is MEASURED, never assumed ─────────────────────
+//
+// SCOPE grew on 2026-09-18 (sol D3 / glm #4). `plugins/herdr/` and the four `scripts/herdr-*.mjs`
+// runtime scripts are the code that actually drives the herdr CLI, and they sat OUTSIDE the law
+// that exists because of that CLI. They are clean today — this gate is what keeps them so.
+//
+// AND THE LISTING IS NOT `--cached` ALONE. A brand-new production module is untracked until it is
+// staged, so a fence that read only the index would look at everything except the file most likely
+// to be carrying the mistake. `--others --exclude-standard` adds exactly the untracked files git
+// would offer to add, which leaves the gitignored build output (`mcp/entwurf-bridge/dist/`) out
+// for the reason it always was: it is this source, compiled, and scanning it twice proves nothing.
+const SCOPE = ["pi-extensions", "mcp", "plugins/herdr"] as const;
+const files = [
+	...execFileSync(
+		"git",
+		["ls-files", "--cached", "--others", "--exclude-standard", "--", ...SCOPE.map((s) => `${s}/*`)],
+		{
+			cwd: REPO,
+			encoding: "utf8",
+		},
+	)
+		.split("\n")
+		.filter(Boolean),
+	// The herdr runtime scripts live in `scripts/`, which is NOT in scope as a whole — this gate
+	// is in there, and a gate that scanned itself could only be made green by deleting the names
+	// it exists to forbid. So they are named, one glob, by what they are.
+	...execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "--", "scripts/herdr-*.mjs"], {
+		cwd: REPO,
+		encoding: "utf8",
+	})
+		.split("\n")
+		.filter(Boolean),
+]
+	.filter((f) => /\.(ts|js|mjs|cjs|sh)$/.test(f))
+	.filter((f) => fs.existsSync(path.join(REPO, f)));
+
+{
+	const required = [
+		"pi-extensions/lib/herdr-fresh-call.ts",
+		"pi-extensions/lib/mux-fresh-call.ts",
+		"pi-extensions/lib/fresh-call-composition.ts",
+		"pi-extensions/entwurf-control.ts",
+		"mcp/entwurf-bridge/src/index.ts",
+		// The two surfaces that drive the vendor CLI this law is about — named, so widening the
+		// scope cannot quietly narrow again.
+		"plugins/herdr/lib/build.mjs",
+		"scripts/herdr-runtime.mjs",
+	];
+	const missing = required.filter((r) => !files.includes(r));
+	ok(
+		`scope is non-vacuous: ${files.length} tracked production sources under ${SCOPE.join(" + ")}, both launch rails and the MCP bridge among them`,
+		files.length >= 50 && missing.length === 0,
+		missing.length ? `not scanned: ${missing.join(", ")}` : `only ${files.length} files matched`,
+	);
+}
+
+// ── 4. THE LAW ──────────────────────────────────────────────────────────────
+{
+	const hits = files.flatMap((rel) => scan(rel, fs.readFileSync(path.join(REPO, rel), "utf8"), flavorOf(rel)));
+	ok(
+		`[QK:TYPEFENCE-PRODUCTION-CLEAN] none of the ${files.length} production sources CARRIES a typing call spelled out — this rail builds arguments and letters, and a module that acquires one of these names in code is refused by name`,
+		hits.length === 0,
+		hits.map((h) => `${h.file}:${h.line} carries ${h.name} — ${h.text}`).join("\n"),
+	);
+}
+
+console.log(`\ncheck-typing-call-fence: ${passed} assertions passed over ${files.length} production sources`);