@junghanacs/entwurf 0.41.2 → 0.50.0

package/scripts/check-meta-doctor-oracle.sh

@@ -767,7 +767,7 @@ import { pathToFileURL } from "node:url";
 const [modPath, active, backends] = process.argv.slice(2);
 const m = await import(pathToFileURL(modPath).href);
 const states = Object.fromEntries(backends.split(",").map((b) => [b, "active"]));
-m.writeLedger(m.resolveActivationLayout(process.env), m.ledgerBody({
+m.writeLedger(m.resolveActivationLayout(process.env), 2, m.ledgerBody({
 	phase: "active",
 	runtimeRoot: active,
 	artifactIdentity: { kind: "npm", name: "@junghanacs/entwurf", version: "0.34.1", expectedIntegrity: "sha512-fixture", observedDigest: `sha256-${"c".repeat(64)}` },

package/scripts/check-meta-facts.ts

@@ -236,7 +236,26 @@ function parseProjection(run: CliRun, label: string): Projection {
 // ── usage ───────────────────────────────────────────────────────────────────
 {
 	ok("[QK:MF-USAGE] two positional args are a usage error (exit 2)", cli(["/a", "/b"]).status === 2);
-	ok("a dash argv is a usage error, not a store directory", cli(["--help"]).status === 2);
+	// The dash refusal's one line is now only the address of the description (#153). This child gets
+	// its own scratch HOME, XDG roots, PI dir and store, so nothing it prints leans on the operator's.
+	const usageHome = reclaimOnExit(fs.mkdtempSync(path.join(os.tmpdir(), "entwurf-meta-facts-usage-")));
+	const dash = cli(["--help"], {
+		HOME: usageHome,
+		XDG_DATA_HOME: path.join(usageHome, ".local", "share"),
+		XDG_STATE_HOME: path.join(usageHome, ".local", "state"),
+		XDG_CACHE_HOME: path.join(usageHome, ".cache"),
+		XDG_CONFIG_HOME: path.join(usageHome, ".config"),
+		PI_CODING_AGENT_DIR: path.join(usageHome, ".pi", "agent"),
+		ENTWURF_META_SESSIONS_DIR: path.join(usageHome, "store"),
+	});
+	ok("a dash argv is a usage error, not a store directory", dash.status === 2);
+	ok(
+		"[QK:MF-HELP-POINTER] the dash refusal keeps exit 2 and an empty stdout, and its one stderr line points at `entwurf help meta-facts`",
+		dash.status === 2 &&
+			dash.stdout === "" &&
+			dash.stderr ===
+				"meta-facts: see `entwurf help meta-facts` (from that checkout's root: `./run.sh help meta-facts`)\n",
+	);
 }
 
 // ── reachability: dispatch + compiled twin ──────────────────────────────────

package/scripts/check-mux-resume-call.ts

@@ -29,6 +29,10 @@
  *   MUXRESUME-NO-IDENTITY           this module never learns which citizen it is reopening
  *   MUXRESUME-SURFACE-SEAM          both surfaces hand the launcher IN; neither lets the v2
  *                                   composition import mux
+ *   MUXRESUME-V2-NO-HERDR-IMPORT    the v2 composition imports no herdr module either (#157 G1a)
+ *   MUXRESUME-HERDR-COMPOSED        the bridge delegates the resume launch to the shared rail root,
+ *                                   handing it this leaf's mapping, and reads no rail fact itself
+ *                                   (the root's own choice is FCD-RESUME-RAIL-SHARED, beside it)
  */
 
 import assert from "node:assert/strict";
@@ -36,6 +40,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { ENTWURF_RESUME_LAUNCH_REJECT_HINTS, ENTWURF_TOOL_GUIDANCE } from "../pi-extensions/lib/agent-guidance.ts";
 import { classifyTmuxCwd } from "../pi-extensions/lib/classify-tmux-cwd.ts";
 import type { Placement } from "../pi-extensions/lib/mux-placement.ts";
 import {
@@ -216,6 +221,12 @@ function main(): void {
 			"every reject reason has a hint a caller can act on — a reason without one is a reason they will guess about",
 			reasons.every((r) => typeof RESUME_CALL_REJECT_HINT[r] === "string" && RESUME_CALL_REJECT_HINT[r].length > 0),
 		);
+		ok(
+			"[QK:MUXRESUME-LAUNCH-REJECT-HINTS-FROM-ROOT] every launch-stage resume hint is the root ENTWURF.json text for its own reason, and the table names exactly the verb's reasons",
+			reasons.every((r) => RESUME_CALL_REJECT_HINT[r] === ENTWURF_RESUME_LAUNCH_REJECT_HINTS[r]) &&
+				JSON.stringify(Object.keys(RESUME_CALL_REJECT_HINT).sort()) === JSON.stringify([...reasons].sort()) &&
+				JSON.stringify(Object.keys(ENTWURF_RESUME_LAUNCH_REJECT_HINTS).sort()) === JSON.stringify([...reasons].sort()),
+		);
 		ok(
 			"[QK:MUXRESUME-RUNTIME-TABLE] the runtime is a closed per-backend table, pi → pi and claude-code → claude — never a command a caller supplies",
 			JSON.stringify(RESUME_CALL_RUNTIME) === JSON.stringify({ pi: "pi", "claude-code": "claude" }),
@@ -227,9 +238,19 @@ function main(): void {
 			"[QK:MUXRESUME-NO-IDENTITY] the module never mentions a garden id, a record, a lock or a transcript — it opens a place at a directory and knows nothing about whose citizen it is",
 			!/gardenId|readAddressableMetaIdentity|acquireLock|transcriptPath/.test(SRC),
 		);
+		// Every static form (from / bare / export-from) is parsed and dynamic loading is refused, so a
+		// fourth lane cannot enter through a shape the parser does not see. The one non-mux member is the
+		// node:fs-only guidance reader (#154 C1-D), whose own leaf-ness is GUIDANCE-READER-LEAF-IMPORTS.
+		const resumeImports = [
+			...SRC.matchAll(/^\s*(?:import|export)\s[^;]*?\sfrom\s+["']([^"']+)["']/gm),
+			...SRC.matchAll(/^\s*import\s+["']([^"']+)["']/gm),
+		].map((m) => m[1]);
 		ok(
-			"it imports only the mux lane — no entwurf core, no delivery",
-			!/from "\.\/entwurf-/.test(SRC) && !/meta-session/.test(SRC),
+			"[QK:MUXRESUME-IMPORT-SET] it imports exactly the mux lane plus the guidance reader — no entwurf core, no delivery, no dynamic import",
+			JSON.stringify([...resumeImports].sort()) ===
+				JSON.stringify(["./agent-guidance.ts", "./classify-tmux-cwd.ts", "./mux-launch.ts", "./mux-placement.ts"]) &&
+				!/\bimport\s*\(|\brequire\s*\(/.test(SRC) &&
+				!/meta-session/.test(SRC),
 		);
 		ok(
 			"it uses the SHARED APPEND_FORMAT rather than adding a start-path field: `-P -F` prints its row BEFORE the child chdirs (measured — pane_current_path there still reports the CALLER's cwd), so a path field would be both free-form in a `|`-joined row and racy",
@@ -248,6 +269,12 @@ function main(): void {
 			"[QK:MUXRESUME-SURFACE-SEAM] the v2 composition never IMPORTS mux — the launcher is passed IN, which is what keeps docs/mux-launch-rail.md §11 true in both directions",
 			v2ImportSpecifiers.length > 0 && !v2ImportSpecifiers.some((s) => /mux-/.test(s)),
 		);
+		// #157 G1a: the herdr resume launch reaches v2 through the same seam, so the same fence holds
+		// for it. v2 learns which rail ran only from the `rail` its launch handle carries.
+		ok(
+			"[QK:MUXRESUME-V2-NO-HERDR-IMPORT] the v2 composition imports no herdr module either — the herdr resume launch is passed IN through the same seam, so neither rail's CLI enters entwurf core",
+			v2ImportSpecifiers.length > 0 && !v2ImportSpecifiers.some((s) => /herdr-/.test(s)),
+		);
 		ok(
 			"the bridge is the composition root: it imports the mux launcher AND the v2 composition and joins them itself",
 			/mux-resume-call/.test(MCP_SURFACE) && /entwurf-v2-visible-resume/.test(MCP_SURFACE),
@@ -270,10 +297,28 @@ function main(): void {
 			/async \(\{ target \}, extra\) =>/.test(MCP_RESUME_BLOCK) &&
 				/await visibleResume\(target, makeVisibleResumeDeps\(visibleResumeLaunch\)\)/.test(MCP_RESUME_BLOCK),
 		);
+		// #157 G1a: the bridge is still where this leaf meets the v2 composition, but the rail is NOT
+		// chosen here. The shared root (`dispatchResumeLaunch` in fresh-call-dispatch, held there by
+		// FCD-RESUME-RAIL-SHARED) reads the capability fact; the bridge hands it this leaf's fixed
+		// mapping and imports no herdr module (its reading no rail fact is FCD-SURFACE-ROOT-ONLY). The
+		// launchers are closures inside the bridge entry, so their wiring is read from the bridge source.
+		const MCP_IMPORTS = [...MCP_SURFACE.matchAll(/from\s+"([^"]+)"/g)].map((m) => m[1]);
+		const TMUX_RESUME_BLOCK = (MCP_SURFACE.split("const tmuxResumeLaunch")[1] ?? "").split("\n};")[0];
+		ok(
+			"[QK:MUXRESUME-HERDR-COMPOSED] the bridge hands every resume launch to the shared rail root together with this tmux leaf's mapping, and imports no herdr module of its own — a bridge that called this leaf directly would refuse every resume inside herdr, and one that reached a herdr launch itself would be a second copy of the rail choice",
+			/^const visibleResumeLaunch: VisibleResumeDeps\["launch"\] = \(input\) => dispatchResumeLaunch\(input, tmuxResumeLaunch\);$/m.test(
+				MCP_SURFACE,
+			) &&
+				/resumeCall\(\{ backend: input\.backend, cwd: input\.cwd, runtimeArgs: input\.runtimeArgs \}\)/.test(
+					TMUX_RESUME_BLOCK,
+				) &&
+				MCP_IMPORTS.includes("../../../pi-extensions/lib/fresh-call-dispatch.ts") &&
+				!MCP_IMPORTS.some((s) => /herdr-/.test(s)),
+		);
 
 		// ── the description contract ────────────────────────────────────────────────
 		// Not prose parity — three claims an operator acts on, plus the host's own cap.
-		const MCP_DESC = (MCP_SURFACE.split('"entwurf_resume_call",')[1] ?? "").split("{")[0];
+		const MCP_DESC = ENTWURF_TOOL_GUIDANCE.entwurf_resume_call.descriptions.mcp;
 		const statesTheContract = (text: string): boolean =>
 			/dormant/i.test(text) && /submits NO prompt/i.test(text) && /observation/i.test(text) && /launch/i.test(text);
 

package/scripts/check-peer-facts.ts

@@ -300,13 +300,33 @@ function parseProjection(run: CliRun, label: string): Projection {
 	console.log("  ok    an unreadable store is exit 3 with no JSON");
 	passed++;
 
-	const flag = cli(["--help"]);
+	// This child gets its own scratch HOME, XDG roots, PI dir and store on top of cli()'s, so the
+	// refusal it prints leans on nothing of the operator's.
+	const usageHome = tmp("usage");
+	const flag = cli(["--help"], {
+		HOME: usageHome,
+		XDG_DATA_HOME: path.join(usageHome, ".local", "share"),
+		XDG_STATE_HOME: path.join(usageHome, ".local", "state"),
+		XDG_CACHE_HOME: path.join(usageHome, ".cache"),
+		XDG_CONFIG_HOME: path.join(usageHome, ".config"),
+		PI_CODING_AGENT_DIR: path.join(usageHome, ".pi", "agent"),
+		ENTWURF_META_SESSIONS_DIR: path.join(usageHome, "store"),
+	});
 	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++;
+	// The leaf's one stderr line is now only the address of the description (#153); the description
+	// itself is ENTWURF-CLI.json's, which `entwurf peer-facts --help` answers before this leaf runs.
+	ok(
+		"[QK:PF-HELP-POINTER] the dash refusal keeps exit 2 and an empty stdout, and its one stderr line points at `entwurf help peer-facts`",
+		flag.status === 2 &&
+			flag.stdout === "" &&
+			flag.stderr ===
+				"peer-facts: see `entwurf help peer-facts` (from that checkout's root: `./run.sh help peer-facts`)\n",
+	);
 	ok("a second positional is a usage error", cli(["/a", "/b"]).status === 2);
 }
 
@@ -317,7 +337,24 @@ function parseProjection(run: CliRun, label: string): Projection {
 		"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 "));
+	// The description is owned by ENTWURF-CLI.json now, so ask the public surface rather than any
+	// file: what the root help actually prints. Only PATH crosses; the root help runs no command.
+	const rootHelp = spawnSync("bash", [path.join(REPO, "run.sh"), "--help"], {
+		encoding: "utf8",
+		env: { PATH: process.env.PATH ?? "/usr/bin:/bin" },
+	});
+	ok("the root help describes peer-facts", rootHelp.status === 0 && /^ {2}entwurf peer-facts /m.test(rootHelp.stdout));
+	// The scene that opened #153's help work: an agent with no briefing asks `entwurf peer-facts
+	// --help`. run.sh answers it from the description before dispatch, so the store is never read and
+	// the leaf's own dash refusal (PF-USAGE, exit 2) is not what the operator meets.
+	const askHelp = spawnSync("bash", [path.join(REPO, "run.sh"), "peer-facts", "--help"], {
+		encoding: "utf8",
+		env: { PATH: process.env.PATH ?? "/usr/bin:/bin" },
+	});
+	ok(
+		"`entwurf peer-facts --help` is that command's help on stdout, exit 0",
+		askHelp.status === 0 && askHelp.stderr === "" && askHelp.stdout.startsWith("Usage: entwurf peer-facts\n"),
+	);
 	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)",

package/scripts/cli-help.mjs

@@ -0,0 +1,222 @@
+/**
+ * Renders the entwurf command line's own description from root ENTWURF-CLI.json, its one editable
+ * source: the short root page (`entwurf --help`), the full catalog (`entwurf help all`), one
+ * command's page, and one guide topic's page. Plain `node` in every mode (no strip-types, no
+ * compiled twin): it imports node builtins only and reads one module-relative file, never
+ * cwd/HOME/env, so a checkout and an installed package answer from the bytes they carry. The whole
+ * file is checked before the first write in every mode; a missing or malformed source is a named
+ * failure (exit 1) on stderr with nothing on stdout — there is no older text to fall back to.
+ *
+ * argv is exactly one of: nothing (the root page), `--all` (the catalog), `--command <name>` (that
+ * command's page — what `<command> --help` asks), or `--name <name>` (what `entwurf help <name>`
+ * asks: a command's page, else a guide topic's page). A name neither describes is exit 2 with one
+ * stderr line. Anything else is exit 2. A topic is static text: it reads none of the settings it
+ * talks about, and it is never a command, so `<topic> --help` is refused like any undescribed name.
+ *
+ * The root page names catalog entries and prints their synopses from the catalog, so a command it
+ * shows is always one the catalog describes. A command name in the data owns a description, not a
+ * dispatch: run.sh's case and its source-defined gate functions stay the only things that run
+ * anything, and check-install-surface compares the two independently.
+ */
+import { readFileSync } from "node:fs";
+
+const SOURCE = new URL("../ENTWURF-CLI.json", import.meta.url);
+const PREFIX = "  entwurf ";
+
+function fail(detail) {
+	process.stderr.write(`entwurf: ENTWURF-CLI.json ${detail}\n`);
+	process.exit(1);
+}
+
+function refuse(detail) {
+	process.stderr.write(`entwurf: ${detail}\n`);
+	process.exit(2);
+}
+
+function object(value, at, wanted, optional = []) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) fail(`${at}: expected an object`);
+	const got = Object.keys(value)
+		.filter((k) => !optional.includes(k))
+		.sort();
+	const want = [...wanted].sort();
+	if (got.length !== want.length || got.some((k, i) => k !== want[i])) {
+		fail(
+			`${at}: keys must be exactly ${wanted.join(", ")}${optional.length ? ` (optionally ${optional.join(", ")})` : ""}`,
+		);
+	}
+	return value;
+}
+
+function text(value, at, { empty = false } = {}) {
+	if (typeof value !== "string" || (!empty && value.length === 0) || value.includes("\n")) {
+		fail(`${at}: expected a ${empty ? "" : "non-empty "}single-line string`);
+	}
+	return value;
+}
+const line = (value, at) => text(value, at);
+
+function array(value, at) {
+	if (!Array.isArray(value) || value.length === 0) fail(`${at}: expected a non-empty array`);
+	return value;
+}
+
+/** One aligned row: the head, padded to its column, then the text. The column must leave a gap. */
+function aligned(head, column, body, at) {
+	if (!Number.isSafeInteger(column) || column <= head.length) {
+		fail(`${at}: column must be an integer past ${JSON.stringify(head.trim())} (> ${head.length})`);
+	}
+	return `${head.padEnd(column)}${body}`;
+}
+
+const argv = process.argv.slice(2);
+const all = argv.length === 1 && argv[0] === "--all";
+const wanted = argv.length === 2 && (argv[0] === "--command" || argv[0] === "--name") ? argv[1] : undefined;
+// Only `entwurf help <name>` may reach a guide; `<command> --help` asks about something to run.
+const topicsToo = argv[0] === "--name";
+if (argv.length !== 0 && !all && wanted === undefined) {
+	refuse("cli-help.mjs takes nothing, --all, --command <name> or --name <name>");
+}
+
+let raw;
+try {
+	raw = readFileSync(SOURCE, "utf8");
+} catch (err) {
+	fail(`unreadable: ${err.code ?? err.message}`);
+}
+let data;
+try {
+	data = JSON.parse(raw);
+} catch (err) {
+	fail(`is not JSON: ${err.message}`);
+}
+
+object(data, "root", ["_about", "schemaVersion", "root", "topics", "usage"]);
+object(data._about, "_about", ["purpose", "ownership"]);
+line(data._about.purpose, "_about.purpose");
+line(data._about.ownership, "_about.ownership");
+if (data.schemaVersion !== 4) fail("schemaVersion: unsupported");
+
+// ── the catalog: every described command, the page `entwurf help all` prints ──
+const usage = object(data.usage, "usage", ["title", "commandGroups", "notes"]);
+const notes = object(usage.notes, "usage.notes", ["title", "lines"]);
+
+const out = [line(usage.title, "usage.title")];
+const entries = new Map();
+array(usage.commandGroups, "usage.commandGroups").forEach((group, g) => {
+	if (g > 0) out.push("");
+	array(group, `usage.commandGroups[${g}]`).forEach((entry, e) => {
+		const at = `usage.commandGroups[${g}][${e}]`;
+		object(entry, at, ["synopsis", "column", "summary"], ["details"]);
+		const synopsis = line(entry.synopsis, `${at}.synopsis`);
+		const name = synopsis.split(" ", 1)[0];
+		if (!/^[a-z][a-z0-9-]*$/.test(name)) fail(`${at}.synopsis: ${JSON.stringify(name)} is not a command name`);
+		// `all` names the catalog itself (`entwurf help all`), so no command may take it.
+		if (name === "all") fail(`${at}.synopsis: "all" is reserved for \`entwurf help all\``);
+		if (entries.has(name)) fail(`${at}.synopsis: ${name} is described twice`);
+		const head = PREFIX + synopsis;
+		if (!Number.isSafeInteger(entry.column) || entry.column <= head.length) {
+			fail(`${at}.column: must be an integer past the synopsis (> ${head.length})`);
+		}
+		const summary = line(entry.summary, `${at}.summary`);
+		// Details are a command's own longer text, printed only by its help: blank lines separate
+		// its parts, so they may be empty, but the block neither starts nor ends on one.
+		const details =
+			entry.details === undefined
+				? []
+				: array(entry.details, `${at}.details`).map((d, i) => text(d, `${at}.details[${i}]`, { empty: true }));
+		if (details.length > 0 && (details[0] === "" || details.at(-1) === "")) {
+			fail(`${at}.details: must not start or end with an empty line`);
+		}
+		entries.set(name, { synopsis, summary, details });
+		out.push(`${head.padEnd(entry.column)}# ${summary}`);
+	});
+});
+out.push("", line(notes.title, "usage.notes.title"));
+for (const [n, note] of array(notes.lines, "usage.notes.lines").entries()) {
+	out.push(`  - ${line(note, `usage.notes.lines[${n}]`)}`);
+}
+
+// ── the root page: a few commands by task, named from the catalog, then examples ──
+const root = object(data.root, "root", ["title", "usage", "sections", "examples", "footer"]);
+const rootUsage = object(root.usage, "root.usage", ["title", "column", "rows"]);
+const compact = [line(root.title, "root.title"), "", line(rootUsage.title, "root.usage.title")];
+array(rootUsage.rows, "root.usage.rows").forEach((row, r) => {
+	const at = `root.usage.rows[${r}]`;
+	object(row, at, ["form"], ["text"]);
+	const head = PREFIX + line(row.form, `${at}.form`);
+	compact.push(row.text === undefined ? head : aligned(head, rootUsage.column, line(row.text, `${at}.text`), at));
+});
+array(root.sections, "root.sections").forEach((section, s) => {
+	const at = `root.sections[${s}]`;
+	object(section, at, ["title", "column", "rows"]);
+	compact.push("", line(section.title, `${at}.title`));
+	array(section.rows, `${at}.rows`).forEach((row, r) => {
+		const rowAt = `${at}.rows[${r}]`;
+		object(row, rowAt, ["name", "text"]);
+		const entry = entries.get(line(row.name, `${rowAt}.name`));
+		if (entry === undefined) fail(`${rowAt}.name: ${JSON.stringify(row.name)} is not a command the catalog describes`);
+		compact.push(aligned(PREFIX + entry.synopsis, section.column, line(row.text, `${rowAt}.text`), rowAt));
+	});
+});
+const examples = object(root.examples, "root.examples", ["title", "items"]);
+compact.push("", line(examples.title, "root.examples.title"));
+array(examples.items, "root.examples.items").forEach((item, i) => {
+	const at = `root.examples.items[${i}]`;
+	object(item, at, ["comment", "command"]);
+	if (i > 0) compact.push("");
+	compact.push(`  # ${line(item.comment, `${at}.comment`)}`);
+	const command = line(item.command, `${at}.command`);
+	// An example runs a real command: `entwurf <described name> …`, or `entwurf help` (`help`,
+	// `help all`, `help <described name>`). Nothing here parses shell beyond those words.
+	const [lead, first, second] = command.split(" ");
+	if (lead !== "entwurf" || first === undefined) fail(`${at}.command: an example starts with \`entwurf <command>\``);
+	const named = first === "help" && second !== undefined ? second : first;
+	const helpItself = first === "help" && (second === undefined || second === "all");
+	if (!helpItself && !entries.has(named))
+		fail(`${at}.command: ${JSON.stringify(named)} is not a command the catalog describes`);
+	compact.push(`  ${command}`);
+});
+compact.push("");
+for (const [f, footer] of array(root.footer, "root.footer").entries()) compact.push(line(footer, `root.footer[${f}]`));
+
+// ── guide topics: read-only pages `entwurf help <name>` prints; never commands ──
+const topics = new Map();
+array(data.topics, "topics").forEach((topic, t) => {
+	const at = `topics[${t}]`;
+	object(topic, at, ["name", "title", "lines"]);
+	const name = line(topic.name, `${at}.name`);
+	if (!/^[a-z][a-z0-9-]*$/.test(name)) fail(`${at}.name: ${JSON.stringify(name)} is not a topic name`);
+	// A topic shares `entwurf help <name>` with the commands, so one word must answer with one page:
+	// no command's name, not `all`, and no other topic's.
+	if (name === "all" || entries.has(name) || topics.has(name))
+		fail(`${at}.name: ${JSON.stringify(name)} is already a command, \`all\` or another topic`);
+	const title = line(topic.title, `${at}.title`);
+	// Blank lines separate a page's parts, so they may be empty, but the page neither starts nor ends on one.
+	const lines = array(topic.lines, `${at}.lines`).map((l, i) => text(l, `${at}.lines[${i}]`, { empty: true }));
+	if (lines[0] === "" || lines.at(-1) === "") fail(`${at}.lines: must not start or end with an empty line`);
+	topics.set(name, { title, lines });
+});
+
+// A reader that stops early (`entwurf help all | head`) closes the pipe: that ends the page, it is
+// not a failure to report.
+process.stdout.on("error", (err) => {
+	if (err.code === "EPIPE") process.exit(0);
+	throw err;
+});
+if (wanted === undefined) {
+	process.stdout.write(`${(all ? out : compact).join("\n")}\n`);
+} else {
+	const entry = entries.get(wanted);
+	const topic = topicsToo ? topics.get(wanted) : undefined;
+	// JSON quoting keeps any control character in the name on this one line.
+	if (!entry && !topic) {
+		refuse(`no help for ${JSON.stringify(wanted)} — \`entwurf help all\` lists the described commands`);
+	}
+	if (entry) {
+		const page = [`Usage: entwurf ${entry.synopsis}`, "", entry.summary];
+		if (entry.details.length > 0) page.push("", ...entry.details);
+		process.stdout.write(`${page.join("\n")}\n`);
+	} else {
+		process.stdout.write(`${[topic.title, "", ...topic.lines].join("\n")}\n`);
+	}
+}

package/scripts/dev-bin.sh

@@ -15,6 +15,14 @@
 #   entwurf-agy-imprint     -> scripts/agy-imprint.sh         (agy PreInvocation birth hook)
 #   entwurf-copilot-statusline -> scripts/copilot-statusline.sh (copilot settings.statusLine command)
 #
+# SOURCE CHECKOUTS ONLY (#153). expose and remove refuse, exit 4, before their first write —
+# legacy migration included — when THIS script belongs to an installed package: its own physical
+# location (symlinks resolved, as run.sh resolves its own) under */node_modules/*, the same seam
+# run.sh's setup_mode/run_ts branch on. Never cwd, never a target override. An installed package's
+# commands come from its package manager's bin linking; the moved-checkout rule below is a
+# developer's authority over its own checkouts and is not inherited by an installed root.
+# verify and exclusive only read, so they stay available everywhere.
+#
 # Ownership discipline (mirrors the agy adopt/refuse rule, 봉인 7), applied PER BIN:
 #   - create/refresh ONLY a link that is OURS — absent, or a symlink into our target, or the
 #     exact link our state recorded (target may have moved checkouts).
@@ -27,11 +35,13 @@
 # guess). New name appears first (atomic rename), old name is gone after. A re-appearing legacy
 # name on a later expose is re-reported (drift visibility).
 #
-#   expose [name]   create/refresh managed link(s) (idempotent; REFUSE foreign → exit 3).
+#   expose [name]   create/refresh managed link(s) (idempotent; REFUSE foreign → exit 3;
+#                   from an installed package → exit 4, nothing written).
 #                   no name = all managed bins, each attempted INDEPENDENTLY (#86 C1): one
 #                   foreign refusal no longer aborts the loop, the trailing summary reports
 #                   attempted/ok/refused truthfully, and any refusal still exits 3.
-#   remove [name]   honest inverse from state (remove only OUR link; REFUSE if it became foreign).
+#   remove [name]   honest inverse from state (remove only OUR link; REFUSE if it became foreign;
+#                   from an installed package → exit 4, nothing removed).
 #                   no name = all managed bins.
 #   verify <name>   require OUR symlink → target and that exact link as the PATH winner.
 #   exclusive       require that NO other root answers to any package.json bin name — not only
@@ -110,6 +120,31 @@ link_is_ours() {
   return 1                                                      # regular file / dir → foreign
 }
 
+# The package root this script belongs to, by its own physical location: a symlinked script or a
+# directory alias still answers with the tree it actually lives in.
+own_package_root() {
+  local src="${BASH_SOURCE[0]}" dir
+  while [ -L "$src" ]; do
+    dir="$(cd -P -- "$(dirname -- "$src")" && pwd)"
+    src="$(readlink "$src")"
+    case "$src" in /*) ;; *) src="$dir/$src" ;; esac
+  done
+  cd -P -- "$(dirname -- "$src")/.." && pwd
+}
+
+refuse_installed_mutation() {  # $1 = verb; exits 4 when this script lives in an installed package
+  local root
+  root="$(own_package_root)"
+  case "$root" in
+    */node_modules/*)
+      warn "[dev-bin] REFUSE $1: this dev-bin.sh belongs to an installed package ($root)."
+      warn "  dev-bin manages a SOURCE checkout's links only; an installed package's commands come from its package manager's bin linking."
+      warn "  nothing was written or removed (no link, no state, no legacy migration)."
+      exit 4
+      ;;
+  esac
+}
+
 path_has_bindir() { case ":$PATH:" in *":$BIN_DIR:"*) return 0 ;; *) return 1 ;; esac; }
 
 write_state() {  # $1=state_file $2=link $3=target $4=detect
@@ -317,6 +352,7 @@ remove_one() {  # $1 = name
 }
 
 do_expose() {  # $1 = optional bin name
+  refuse_installed_mutation expose
   migrate_legacy
   if [ -n "${1:-}" ]; then expose_one "$1"; return $?; fi
   # No-arg = the setup composition. Attempt EVERY unit independently (#86 C1):
@@ -338,6 +374,7 @@ do_expose() {  # $1 = optional bin name
   log "[dev-bin expose] summary: attempted=$attempted ok=$exposed refused=0"
 }
 do_remove() {  # $1 = optional bin name
+  refuse_installed_mutation remove
   if [ -n "${1:-}" ]; then remove_one "$1"; else for b in $MANAGED_BINS; do remove_one "$b"; done; fi
 }
 

package/scripts/herdr-activation.mjs

@@ -30,8 +30,16 @@ import fs from "node:fs";
 import path from "node:path";
 import { artifactStage, certifyArtifactIdentity, resolveRuntimeLayout, sameArtifactRequest } from "./herdr-runtime.mjs";
 
-/** Ledger format. Bump only with a reader that understands both. */
-export const ACTIVATION_SCHEMA_VERSION = 2;
+/**
+ * Ledger formats this reader admits (#153). The key set is the same for both; 3 is a FLOOR, not a new
+ * shape: a reader that admits only 2 refuses a 3-ledger before its first write, which is how an older
+ * artifact is kept from acting on a host it no longer understands. Add a version only together with a
+ * reader that understands every version already in this set.
+ */
+export const ACTIVATION_SCHEMA_VERSIONS = Object.freeze([2, 3]);
+
+/** The version a ledger is born with. Every later write carries the version it read — never this. */
+export const FRESH_ACTIVATION_SCHEMA_VERSION = 2;
 
 /** Set P, frozen. The ledger may never name anything else. */
 export const ACTIVATABLE_BACKENDS = Object.freeze(["pi", "claude-code"]);
@@ -140,10 +148,24 @@ function certifyRoot(where, value) {
 	}
 }
 
-/** Ledgers are replaced, never patched: write beside, then rename. */
-export function writeLedger(layout, entry) {
+/**
+ * Ledgers are replaced, never patched: write beside, then rename. The version is an explicit
+ * argument and the only one: an entry carrying its own `schemaVersion` is refused rather than
+ * merged, so no spread order can let a body silently raise or lower the floor. Both refusals come
+ * before the first byte.
+ */
+export function writeLedger(layout, version, entry) {
+	if (!ACTIVATION_SCHEMA_VERSIONS.includes(version)) {
+		throw new ActivationError("activation-ledger-version-invalid", `schemaVersion ${JSON.stringify(version)}`);
+	}
+	if (Object.hasOwn(entry, "schemaVersion")) {
+		throw new ActivationError(
+			"activation-ledger-version-invalid",
+			"the entry carries its own schemaVersion; the version is the explicit argument alone",
+		);
+	}
 	fs.mkdirSync(layout.stateRoot, { recursive: true });
-	const body = `${JSON.stringify({ schemaVersion: ACTIVATION_SCHEMA_VERSION, ...entry }, null, 2)}\n`;
+	const body = `${JSON.stringify({ schemaVersion: version, ...entry }, null, 2)}\n`;
 	const tmp = `${layout.ledgerPath}.tmp`;
 	fs.writeFileSync(tmp, body);
 	fs.renameSync(tmp, layout.ledgerPath);
@@ -190,7 +212,7 @@ export function readCertifiedLedger(layout) {
 	if (Object.keys(parsed).sort().join(",") !== [...LEDGER_KEYS].sort().join(",")) {
 		throw new ActivationError("activation-ledger-uncertified", `key set: ${Object.keys(parsed).sort()}`);
 	}
-	if (parsed.schemaVersion !== ACTIVATION_SCHEMA_VERSION) {
+	if (!ACTIVATION_SCHEMA_VERSIONS.includes(parsed.schemaVersion)) {
 		throw new ActivationError("activation-ledger-uncertified", `schemaVersion ${parsed.schemaVersion}`);
 	}
 	if (typeof parsed.runtimeRoot !== "string" || !path.isAbsolute(parsed.runtimeRoot)) {