@junghanacs/entwurf 0.41.2 → 0.50.0

package/scripts/herdr-operator-link.mjs

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+/**
+ * herdr-operator-link — the operator's ONE explicit link to the Herdr runtime's `entwurf` (#153).
+ *
+ * The plugin puts nothing on PATH (`herdr-runtime.mjs` header). This verb is the single exception,
+ * and only on request: `expose --bin-dir <abs>` makes exactly one symlink, `<bin-dir>/entwurf`, to
+ * the stable runtime's `node_modules/.bin/entwurf`; `withdraw` takes exactly that link back. Nothing
+ * else is named, no profile is edited, and no directory is chosen for the operator.
+ *
+ * THE RECEIPT IS THE SUB-OWNER. One file beside the activation ledger records the link — six keys,
+ * three phases — and is the only authority any inverse acts on. A link without a receipt is someone
+ * else's, whatever it points at, and nothing here goes looking along PATH for one.
+ *
+ * THE LEDGER FLOOR COMES FIRST. A receipt may exist only beside a schema-3 ledger: a reader that
+ * admits only 2 refuses that ledger before its first write, so an artifact that does not know this
+ * receipt can never tear down a runtime the link still names. The floor is raised here, and only
+ * here, from a settled host with no receipt; it is never lowered — a withdraw keeps it.
+ *
+ * ORDER IS THE CRASH CONTRACT: floor 3 → receipt `linking` → symlink → receipt `linked`. Each step
+ * is published atomically (write beside, rename) and judged again on the next call, so a process
+ * stopped between any two leaves a state the next call names and continues. Power loss is not
+ * certified (no fsync), as for the ledger itself.
+ *
+ * EVERY IMPORT IS STATIC. `herdr-plugin-deactivate` imports this module and then deletes the runtime
+ * it runs from; a lazy import afterwards would fail.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	ActivationError,
+	certifyLedgerDescribesRuntime,
+	certifyPhaseForInverse,
+	certifyRootsAgainstLedger,
+	readCertifiedLedger,
+	resolveActivationLayout,
+	resolveComponentRoots,
+	runtimeIdentityOnDisk,
+	writeLedger,
+} from "./herdr-activation.mjs";
+import {
+	artifactCompleteness,
+	readCertifiedJournal,
+	resolveRuntimeLayout,
+	verifyInstalledRuntime,
+} from "./herdr-runtime.mjs";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The one name this verb links, and the floor a receipt requires. */
+const LINK_NAME = "entwurf";
+const LEDGER_FLOOR_VERSION = 3;
+
+export const OPERATOR_LINK_SCHEMA_VERSION = 1;
+export const OPERATOR_LINK_KEYS = Object.freeze([
+	"schemaVersion",
+	"phase",
+	"binDir",
+	"linkPath",
+	"target",
+	"runtimeRoot",
+]);
+export const OPERATOR_LINK_PHASES = Object.freeze(["linking", "linked", "unlinking"]);
+
+function refuse(code, detail) {
+	throw new ActivationError(code, detail);
+}
+
+/** The receipt's fixed address: the ledger's own state root, its own file. */
+export function resolveOperatorLinkLayout(env) {
+	const { stateRoot } = resolveActivationLayout(env);
+	return Object.freeze({ stateRoot, receiptPath: path.join(stateRoot, "operator-link.json") });
+}
+
+/** What the link points at: the stable runtime's own `entwurf`, lexically — never a resolved path. */
+export function operatorLinkTarget(activeDir) {
+	return path.join(activeDir, "node_modules", ".bin", LINK_NAME);
+}
+
+/** The receipt, certified, or null when none stands at its address. */
+export function readCertifiedOperatorLink(layout, activeDir) {
+	const kind = fs.lstatSync(layout.receiptPath, { throwIfNoEntry: false });
+	if (kind === undefined) return null;
+	const uncertified = (why) => refuse("operator-link-receipt-uncertified", `${layout.receiptPath}: ${why}`);
+	if (!kind.isFile()) uncertified("only a regular file may stand at the receipt address");
+	let parsed;
+	try {
+		parsed = JSON.parse(fs.readFileSync(layout.receiptPath, "utf8"));
+	} catch (err) {
+		uncertified(err.message);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) uncertified("not a JSON object");
+	if (Object.keys(parsed).sort().join(",") !== [...OPERATOR_LINK_KEYS].sort().join(",")) {
+		uncertified(`key set: ${Object.keys(parsed).sort()}`);
+	}
+	if (parsed.schemaVersion !== OPERATOR_LINK_SCHEMA_VERSION) uncertified(`schemaVersion ${parsed.schemaVersion}`);
+	if (!OPERATOR_LINK_PHASES.includes(parsed.phase)) uncertified(`phase ${JSON.stringify(parsed.phase)}`);
+	for (const key of ["binDir", "linkPath", "target", "runtimeRoot"]) {
+		if (typeof parsed[key] !== "string" || !path.isAbsolute(parsed[key])) uncertified(`${key} is not an absolute path`);
+	}
+	if (parsed.linkPath !== path.join(parsed.binDir, LINK_NAME)) uncertified("linkPath is not <binDir>/entwurf");
+	if (parsed.target !== operatorLinkTarget(activeDir)) uncertified(`target is not ${operatorLinkTarget(activeDir)}`);
+	if (parsed.runtimeRoot !== activeDir) uncertified(`runtimeRoot is not this host's stable root ${activeDir}`);
+	return Object.freeze(parsed);
+}
+
+/** Receipts are replaced, never patched: write beside, then rename. */
+function writeOperatorLink(layout, body) {
+	fs.mkdirSync(layout.stateRoot, { recursive: true });
+	const tmp = `${layout.receiptPath}.tmp`;
+	fs.writeFileSync(tmp, `${JSON.stringify(body, null, 2)}\n`);
+	fs.renameSync(tmp, layout.receiptPath);
+}
+
+/**
+ * A receipt, in any phase, belongs to a certified schema-3 ledger for this runtime and these roots.
+ * Anything else is refused before a byte is written — it is never adopted, and the floor is never
+ * raised to make it fit.
+ */
+function certifyReceiptBinding(receipt, ledger, roots, activeDir) {
+	if (receipt === null) return;
+	if (ledger === null) refuse("operator-link-orphan", "an operator-link receipt stands with no activation ledger");
+	if (ledger.schemaVersion !== LEDGER_FLOOR_VERSION)
+		refuse("operator-link-floor-mismatch", `the ledger is schema ${ledger.schemaVersion}, not ${LEDGER_FLOOR_VERSION}`);
+	certifyRootsAgainstLedger(ledger, roots, activeDir);
+}
+
+/** `real` (a physical directory that is its own realpath), `gone`, or `alias`. */
+function assessBinDir(binDir) {
+	const kind = fs.lstatSync(binDir, { throwIfNoEntry: false });
+	if (kind === undefined) return "gone";
+	if (!kind.isDirectory()) return "alias";
+	if (fs.realpathSync(binDir) !== binDir) return "alias";
+	return "real";
+}
+
+/** `absent`, `ours` (a symlink whose text is exactly the target), or `foreign`. */
+function assessLink(linkPath, target) {
+	const kind = fs.lstatSync(linkPath, { throwIfNoEntry: false });
+	if (kind === undefined) return "absent";
+	if (kind.isSymbolicLink() && fs.readlinkSync(linkPath) === target) return "ours";
+	return "foreign";
+}
+
+function isExecutableFile(file) {
+	try {
+		if (fs.statSync(file).isDirectory()) return false;
+		fs.accessSync(file, fs.constants.X_OK);
+		return true;
+	} catch {
+		// Bounded probe: missing or not executable is simply "not a candidate".
+		return false;
+	}
+}
+
+/**
+ * Where B stands in THIS caller's PATH, judged by path alone — no program is run. An empty entry is
+ * the cwd and a relative one is relative to it, which is why the run.sh arm does not cd. Aliases,
+ * functions, the shell's hash table and other shells' PATHs are outside this judgement.
+ */
+function pathSelection(binDir, { PATH, cwd }) {
+	for (const entry of (PATH ?? "").split(path.delimiter)) {
+		const dir = path.resolve(cwd, entry === "" ? "." : entry);
+		if (dir === binDir) return { onPath: true, shadowedBy: null };
+		const candidate = path.join(dir, LINK_NAME);
+		if (isExecutableFile(candidate)) return { onPath: false, shadowedBy: candidate };
+	}
+	return { onPath: false, shadowedBy: null };
+}
+
+/** A public verb runs only as the active runtime's own package — never from a checkout or a copy. */
+function admitSelf(runtime, verb) {
+	let same = false;
+	try {
+		same =
+			fs.realpathSync(PACKAGE_ROOT) ===
+			fs.realpathSync(path.join(runtime.activeDir, "node_modules", "@junghanacs", "entwurf"));
+	} catch {
+		// Bounded probe: no package at the stable address means this is not it.
+		same = false;
+	}
+	if (!same) {
+		refuse(
+			"operator-link-not-active-package",
+			`${verb} runs only from the Herdr runtime's own package (${runtime.activeDir}); this is ${PACKAGE_ROOT}`,
+		);
+	}
+}
+
+function usage(detail) {
+	refuse(
+		"operator-link-usage",
+		`${detail} — usage: herdr-plugin-expose-operator --bin-dir <absolute dir> | herdr-plugin-withdraw-operator`,
+	);
+}
+
+/** Exactly `--bin-dir <absolute>`; nothing else, in no other order. */
+function parseExposeArgv(argv) {
+	if (argv.length !== 2 || argv[0] !== "--bin-dir")
+		usage(`expose takes exactly --bin-dir <dir>, got ${JSON.stringify(argv)}`);
+	if (!path.isAbsolute(argv[1])) usage(`--bin-dir must be absolute, got ${JSON.stringify(argv[1])}`);
+	return argv[1];
+}
+
+/**
+ * Make the one link, or say by name why not. Every judgement comes before the first write.
+ *
+ * @returns a one-line outcome for the operator.
+ */
+export function expose(env, argv, { cwd }) {
+	const binDir = parseExposeArgv(argv);
+	const runtime = resolveRuntimeLayout(env);
+	const activation = resolveActivationLayout(env);
+	const roots = resolveComponentRoots(env);
+	const layout = resolveOperatorLinkLayout(env);
+	admitSelf(runtime, "expose");
+
+	const journal = readCertifiedJournal(runtime);
+	if (journal === null || journal.phase !== "runtime-ready") {
+		refuse("operator-link-runtime-not-ready", `${runtime.activeDir} has no certified runtime-ready journal behind it`);
+	}
+	verifyInstalledRuntime(runtime.activeDir, artifactCompleteness(journal.artifactIdentity));
+	const ledger = readCertifiedLedger(activation);
+	if (ledger === null || ledger.phase !== "active") {
+		refuse(
+			"operator-link-activation-not-settled",
+			`the activation ledger is ${ledger === null ? "absent" : ledger.phase}, not active`,
+		);
+	}
+	certifyRootsAgainstLedger(ledger, roots, runtime.activeDir);
+	certifyLedgerDescribesRuntime(ledger, runtimeIdentityOnDisk(journal));
+	if (
+		fs.lstatSync(runtime.stagingDir, { throwIfNoEntry: false }) ||
+		fs.lstatSync(runtime.previousDir, { throwIfNoEntry: false })
+	) {
+		refuse(
+			"operator-link-runtime-not-settled",
+			"a staged or backed-up runtime stands beside the active one; finish or recover that install first",
+		);
+	}
+	const target = operatorLinkTarget(runtime.activeDir);
+	if (!isExecutableFile(target)) refuse("operator-link-target-missing", `${target} is not an executable file`);
+	if (assessBinDir(binDir) !== "real") {
+		refuse("operator-link-bin-dir-refused", `${binDir} is not an existing physical directory that is its own realpath`);
+	}
+	const selection = pathSelection(binDir, { PATH: env.PATH, cwd });
+	if (selection.shadowedBy !== null) {
+		refuse(
+			"operator-link-path-shadowed",
+			`${selection.shadowedBy} comes before ${binDir} on PATH; a link there would not be the one that runs`,
+		);
+	}
+	if (!selection.onPath) refuse("operator-link-bin-dir-off-path", `${binDir} is not an entry of the current PATH`);
+
+	const linkPath = path.join(binDir, LINK_NAME);
+	const receipt = readCertifiedOperatorLink(layout, runtime.activeDir);
+	certifyReceiptBinding(receipt, ledger, roots, runtime.activeDir);
+	const link = assessLink(linkPath, target);
+	const body = (phase) => ({
+		schemaVersion: OPERATOR_LINK_SCHEMA_VERSION,
+		phase,
+		binDir,
+		linkPath,
+		target,
+		runtimeRoot: runtime.activeDir,
+	});
+
+	if (receipt === null) {
+		if (link !== "absent")
+			refuse("operator-link-foreign", `${linkPath} exists and no receipt says it is ours; remove it yourself if it is`);
+		const { schemaVersion, ...entry } = ledger;
+		if (schemaVersion !== LEDGER_FLOOR_VERSION) writeLedger(activation, LEDGER_FLOOR_VERSION, entry);
+		writeOperatorLink(layout, body("linking"));
+		fs.symlinkSync(target, linkPath);
+		writeOperatorLink(layout, body("linked"));
+		return `linked ${linkPath} -> ${target}`;
+	}
+	if (receipt.binDir !== binDir) {
+		refuse(
+			"operator-link-other-bin-dir",
+			`the operator link already lives in ${receipt.binDir}; withdraw it before asking for ${binDir}`,
+		);
+	}
+	if (receipt.phase === "unlinking")
+		refuse("operator-link-unlinking", "a withdraw is half done; run herdr-plugin-withdraw-operator to finish it");
+	if (link === "foreign") refuse("operator-link-foreign", `${linkPath} is no longer the link the receipt names`);
+	if (receipt.phase === "linked") {
+		if (link === "absent")
+			refuse("operator-link-drift", `the receipt says ${linkPath} is linked but it is gone; withdraw, then ask again`);
+		return `already linked ${linkPath} -> ${target}`;
+	}
+	// `linking`: a run stopped after recording its intent. Our exact link is published as linked
+	// without being made again; an absent one is made now.
+	if (link === "absent") fs.symlinkSync(target, linkPath);
+	writeOperatorLink(layout, body("linked"));
+	return `linked ${linkPath} -> ${target} (resumed)`;
+}
+
+/**
+ * Before deactivate's first write: the receipt (or null) and every judgement its removal needs.
+ * No self admission here — deactivate's own tail must stay resumable after the runtime is gone.
+ */
+export function preflightOperatorLink(env, ledger, roots, activeDir) {
+	const receipt = readCertifiedOperatorLink(resolveOperatorLinkLayout(env), activeDir);
+	if (receipt === null) return null;
+	certifyReceiptBinding(receipt, ledger, roots, activeDir);
+	assessForRemoval(receipt);
+	return receipt;
+}
+
+/** `ours` or `absent` (B gone counts as absent); a present B that drifted, or a foreign link, refuses. */
+function assessForRemoval(receipt) {
+	const bin = assessBinDir(receipt.binDir);
+	if (bin === "alias")
+		refuse(
+			"operator-link-bin-dir-drifted",
+			`${receipt.binDir} is no longer a physical directory that is its own realpath`,
+		);
+	const link = bin === "gone" ? "absent" : assessLink(receipt.linkPath, receipt.target);
+	if (link === "foreign")
+		refuse("operator-link-foreign", `${receipt.linkPath} is not the link the receipt names; nothing was removed`);
+	return link;
+}
+
+/** Remove exactly the receipt's link, then the receipt. Shared by withdraw and deactivate. */
+export function removeOperatorLink(env, receipt) {
+	const layout = resolveOperatorLinkLayout(env);
+	assessForRemoval(receipt);
+	writeOperatorLink(layout, { ...receipt, phase: "unlinking" });
+	if (assessForRemoval(receipt) === "ours") fs.unlinkSync(receipt.linkPath);
+	fs.rmSync(layout.receiptPath, { force: true });
+}
+
+/** The opt-out. The ledger floor stays where it is. */
+export function withdraw(env, argv) {
+	if (argv.length !== 0) usage(`withdraw takes no arguments, got ${JSON.stringify(argv)}`);
+	const runtime = resolveRuntimeLayout(env);
+	admitSelf(runtime, "withdraw");
+	const receipt = readCertifiedOperatorLink(resolveOperatorLinkLayout(env), runtime.activeDir);
+	if (receipt === null) return "no operator link";
+	const ledger = readCertifiedLedger(resolveActivationLayout(env));
+	certifyReceiptBinding(receipt, ledger, resolveComponentRoots(env), runtime.activeDir);
+	certifyPhaseForInverse(ledger);
+	removeOperatorLink(env, receipt);
+	return `withdrew ${receipt.linkPath}`;
+}
+
+/** Without a ledger: what stands at the receipt address, and — only from a certified receipt — its link. */
+export function operatorLinkLeftovers(env) {
+	const layout = resolveOperatorLinkLayout(env);
+	const kind = fs.lstatSync(layout.receiptPath, { throwIfNoEntry: false });
+	if (kind === undefined) return [];
+	const found = [`operator-link-receipt (${layout.receiptPath})`];
+	let receipt = null;
+	try {
+		receipt = readCertifiedOperatorLink(layout, resolveRuntimeLayout(env).activeDir);
+	} catch {
+		// A damaged receipt names only its own fixed address; no link address is trusted from it.
+		receipt = null;
+	}
+	if (receipt !== null && fs.lstatSync(receipt.linkPath, { throwIfNoEntry: false }) !== undefined) {
+		found.push(`operator-link (${receipt.linkPath})`);
+	}
+	return found;
+}
+
+function sameFile(a, b) {
+	try {
+		return fs.realpathSync(a) === fs.realpathSync(b);
+	} catch {
+		return false;
+	}
+}
+
+if (process.argv[1] && sameFile(process.argv[1], fileURLToPath(import.meta.url))) {
+	const [verb, ...rest] = process.argv.slice(2);
+	try {
+		let outcome;
+		if (verb === "expose") outcome = expose(process.env, rest, { cwd: process.cwd() });
+		else if (verb === "withdraw") outcome = withdraw(process.env, rest);
+		else usage(`unknown verb ${JSON.stringify(verb)}`);
+		process.stdout.write(`[herdr-operator-link] ${outcome}\n`);
+		process.exit(0);
+	} catch (err) {
+		process.stderr.write(`[herdr-operator-link] ${err.code ?? "operator-link-failed"}: ${err.detail ?? err.message}\n`);
+		process.exit(err.code === "operator-link-usage" ? 2 : 1);
+	}
+}

package/scripts/herdr-plugin-activate.mjs

@@ -32,6 +32,7 @@ import {
 	certifyPhaseForForward,
 	certifyRootsAgainstLedger,
 	componentStates,
+	FRESH_ACTIVATION_SCHEMA_VERSION,
 	ledgerBody,
 	piStatePaths,
 	planActivation,
@@ -248,9 +249,13 @@ export function activate(env, requested) {
 	for (const backend of selected) {
 		if (disposition === "rebind" || states[backend] !== "active") states[backend] = "pending";
 	}
+	// The floor this host already carries is kept; only a ledger that does not exist yet is born at
+	// the fresh version. Activation neither raises nor lowers it.
+	const version = ledger?.schemaVersion ?? FRESH_ACTIVATION_SCHEMA_VERSION;
 	const checkpoint = (phase) =>
 		writeLedger(
 			activation,
+			version,
 			ledgerBody({ phase, runtimeRoot: runtime.activeDir, artifactIdentity: current, roots, states }),
 		);
 	checkpoint("activating");

package/scripts/herdr-plugin-deactivate.mjs

@@ -13,8 +13,10 @@
  * ledger unretired, and nothing left to run the rest. So nothing here is loaded late, and the gate
  * asserts there is no dynamic import to defer.
  *
- * PREFLIGHT EVERY AUTHORITY, THEN MUTATE. The ledger, the resolved roots, and BOTH component
- * inverses are asked read-only first. Only when all of them are green does the first byte change.
+ * PREFLIGHT, THEN MUTATE. The ledger, the resolved roots, the operator link and the inverse of every
+ * component still left to undo are asked read-only first; only when all of them are green does the
+ * first byte change. Runtime ownership is not part of that preflight: `removeOwnedRuntime` judges it
+ * at its own step, after the components, and a refusal there stops the run with the ledger kept.
  * A component that then fails stops the run with the runtime and the ledger intact, because the
  * ledger is the retry authority and a teardown that deletes its own record of what is left is one
  * nobody can resume.
@@ -37,6 +39,7 @@ import {
 	resolveComponentRoots,
 	writeLedger,
 } from "./herdr-activation.mjs";
+import { operatorLinkLeftovers, preflightOperatorLink, removeOperatorLink } from "./herdr-operator-link.mjs";
 import { removeOwnedRuntime, resolveRuntimeLayout } from "./herdr-runtime.mjs";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -86,7 +89,7 @@ export function deactivate(env) {
 		// recorded leaves a journal, a runtime or a cache behind, and saying "nothing to undo" over them
 		// was a false success. Without a ledger nothing proves what they belong to or that no harness
 		// wiring names them, so this verb removes nothing: it names what it found and exits non-zero.
-		const leftovers = leftoversAtPluginAddresses(runtime);
+		const leftovers = [...leftoversAtPluginAddresses(runtime), ...operatorLinkLeftovers(env)];
 		if (leftovers.length === 0) {
 			process.stdout.write("[herdr-plugin-deactivate] no certified activation ledger — nothing to undo\n");
 			return 0;
@@ -100,6 +103,9 @@ export function deactivate(env) {
 	}
 	certifyRootsAgainstLedger(ledger, roots, runtime.activeDir);
 	certifyPhaseForInverse(ledger);
+	// The operator link (#153) is judged with everything else, before the first write: a link that is
+	// no longer the receipt's, or a receipt this ledger does not carry, stops the whole teardown here.
+	const operatorReceipt = preflightOperatorLink(env, ledger, roots, runtime.activeDir);
 	// On a RETRY the plan is what is LEFT: a component already recorded `removed` is skipped, because
 	// its inverse has no ownership state to be admitted by any more and re-running it is a permanent
 	// refusal — which is exactly how a half-finished teardown used to become unfinishable.
@@ -107,7 +113,7 @@ export function deactivate(env) {
 	const states = componentStates(ledger);
 	const piState = piStatePaths(env);
 
-	// ── PREFLIGHT: every remaining authority, zero writes ────────────────────
+	// ── PREFLIGHT: every remaining component inverse, zero writes ────────────
 	const preflights = [];
 	if (steps.includes("claude-code")) {
 		preflights.push([
@@ -176,6 +182,7 @@ export function deactivate(env) {
 	const checkpoint = () =>
 		writeLedger(
 			activation,
+			ledger.schemaVersion,
 			ledgerBody({
 				phase: "deactivating",
 				runtimeRoot: runtime.activeDir,
@@ -187,6 +194,12 @@ export function deactivate(env) {
 	checkpoint();
 
 	const done = [];
+	// The link goes FIRST: it names the runtime, so it must be gone before the thing it names. Its
+	// receipt is its own retry authority, so the ledger records nothing new for it.
+	if (operatorReceipt !== null) {
+		removeOperatorLink(env, operatorReceipt);
+		done.push("operator-link");
+	}
 	for (const step of steps) {
 		if (step === "claude-code" || step === "pi") {
 			const verb = step === "pi" ? "remove-user-scope" : "uninstall-meta-bridge";
@@ -195,7 +208,7 @@ export function deactivate(env) {
 				process.stderr.write(`${(r.stderr || r.stdout || "").trim()}\n`);
 				fail(
 					"deactivate-component-failed",
-					`${step} inverse failed — runtime and ledger preserved as retry authority (${done.length} component(s) already removed and recorded)`,
+					`${step} inverse failed — runtime and ledger preserved as retry authority (${done.filter((s) => s === "pi" || s === "claude-code").length} component(s) already removed and recorded)`,
 				);
 			}
 			states[step] = "removed";

package/scripts/herdr-rails.mjs

@@ -31,17 +31,44 @@
  */
 
 /**
- * The closed pilot set for the herdr launch rail. Herdr's own `--kind` enum is much larger and
- * that is not evidence of support: every other backend is a named pre-mutation reject.
+ * The backends the herdr rail opens through `tab create` + `agent start --kind`. Herdr's own
+ * `--kind` enum is much larger and that is not evidence of support. This set alone keys the
+ * agent-start maps (`HERDR_AGENT_KIND`, `HERDR_CANONICAL_EXECUTABLE`): a backend outside it has no
+ * herdr kind, and giving it one would start a different program under its name.
  *
  * The JSDoc cast is what keeps the TYPE half of this single source honest. Without it TypeScript
- * infers `readonly string[]` from a `.mjs` file and `HerdrFreshCallBackend` silently widens to
+ * infers `readonly string[]` from a `.mjs` file and `HerdrAgentStartBackend` silently widens to
  * `string` — the tuple would still be one source at runtime while the compiler had stopped
  * checking anything. A gate pins both halves.
  *
  * @type {readonly ["pi", "claude-code"]}
  */
-export const HERDR_FRESH_CALL_BACKENDS = Object.freeze(["pi", "claude-code"]);
+export const HERDR_AGENT_START_BACKENDS = Object.freeze(["pi", "claude-code"]);
+
+/**
+ * The backends the herdr rail opens through ONE fixed `layout.apply` request on the caller's own
+ * herdr socket (#157 A-L1). pi-durable has no herdr agent kind, so it is launched as the package's
+ * own verified `run.sh pi-durable …` argv vector in a new tab — never disguised as `--kind pi`.
+ *
+ * @type {readonly ["pi-durable"]}
+ */
+export const HERDR_LAYOUT_LAUNCH_BACKENDS = Object.freeze(["pi-durable"]);
+
+/**
+ * Everything `entwurf_fresh_call` actually opens inside herdr: the union of the two launch domains.
+ * Admission and refusal read THIS set, so every backend outside it is a named pre-mutation reject
+ * and no backend is admitted by one domain while another surface says it is refused.
+ *
+ * The status pane's RAILS block renders the two domains as separate groups — agent start, then
+ * layout — over this aggregate (#157 A-L2). The install narration covers only the integrations it
+ * activated, and pi-durable is never one: it has no herdr agent integration to activate.
+ *
+ * @type {readonly ["pi", "claude-code", "pi-durable"]}
+ */
+export const HERDR_FRESH_CALL_BACKENDS = Object.freeze([
+	...HERDR_AGENT_START_BACKENDS,
+	...HERDR_LAYOUT_LAUNCH_BACKENDS,
+]);
 
 /**
  * ONE model string per backend, and it is an example of SYNTAX, never of choice.
@@ -49,13 +76,16 @@ export const HERDR_FRESH_CALL_BACKENDS = Object.freeze(["pi", "claude-code"]);
  * `[관측: GLG, 날것 PC, 2026-09-17]` "일단 정확한 모델명을 모른다" — after a green install the first
  * thing missing is a call that works, and the two runtimes spell a model differently enough that
  * guessing fails: pi wants a provider-qualified path, Claude Code wants the vendor id alone.
- * That difference is the whole content of this map.
+ * That difference is the whole content of this map. pi-durable takes pi's shape — its preflight
+ * refuses a model that is not provider-qualified (`pi-durable-model-not-provider-qualified`) — so its
+ * example is the same shape string, not a choice of model.
  *
- * @type {Readonly<Record<"pi" | "claude-code", string>>}
+ * @type {Readonly<Record<"pi" | "claude-code" | "pi-durable", string>>}
  */
 export const MODEL_SYNTAX_EXAMPLE = Object.freeze({
 	pi: "openai-codex/gpt-5.6-terra",
 	"claude-code": "claude-sonnet-5",
+	"pi-durable": "openai-codex/gpt-5.6-terra",
 });
 
 /**
@@ -67,9 +97,15 @@ export const MODEL_SYNTAX_EXAMPLE = Object.freeze({
  * citizen pi: the install says green, `pi` starts, and nothing is there. Citizenship is argv-gated
  * on purpose, and that gate is invisible unless something says it out loud.
  *
- * @type {Readonly<Record<"pi" | "claude-code", string>>}
+ * pi-durable's note says what it is NOT here as much as how it is reached: it is not an integration
+ * this plugin activates, and herdr has no agent kind for it, so nothing detects it or associates a
+ * session with it.
+ *
+ * @type {Readonly<Record<"pi" | "claude-code" | "pi-durable", string>>}
  */
 export const RAIL_ENTRY_NOTE = Object.freeze({
 	pi: "start it as `pi --entwurf-control` to be a garden citizen — a plain `pi` loads the extension but has no garden id, no control socket and no entwurf tools",
 	"claude-code": "nothing to add — an ordinary `claude` picks up the entwurf tools through MCP",
+	"pi-durable":
+		"not a Herdr integration this plugin activates — inside Herdr, `entwurf_fresh_call` opens it in a new tab through ONE layout request; Herdr has no agent kind for it, so it is neither detected nor associated with a session, and its peers placement reads unobserved",
 });

package/scripts/herdr-runtime.mjs

@@ -998,7 +998,18 @@ export function bootstrapRuntime({
 	checkoutRoot = defaultCheckoutRoot(),
 	acquire = acquireArtifact,
 	resolveCommit = resolveCheckoutCommit,
+	admitCandidate,
 }) {
+	// ADMISSION (#153) is an optional, SYNCHRONOUS observation of the verified candidate, made before
+	// the first rename: return nothing to admit it, throw to refuse it. This module never decides what
+	// is asked — the caller that owns the question supplies it — so it imports nothing to ask it with.
+	// A value that cannot be called is refused here, before the first byte.
+	if (admitCandidate !== undefined && typeof admitCandidate !== "function") {
+		throw new RuntimeBootstrapError(
+			"runtime-candidate-admission-invalid",
+			`admitCandidate is ${typeof admitCandidate}; it is a synchronous function or absent`,
+		);
+	}
 	const requested = requestedArtifactIdentity({ lock, checkoutRoot, resolveCommit });
 	const layout = resolveRuntimeLayout(env);
 
@@ -1114,6 +1125,22 @@ export function bootstrapRuntime({
 		fs.mkdirSync(layout.stagingDir, { recursive: true });
 		acquired = acquire({ identity: requested, prefix: layout.stagingDir, cacheDir: layout.cacheDir, env });
 		verifyInstalledRuntime(layout.stagingDir, completenessOf(requested, acquired));
+		// Inside this try, so a refused candidate is reclaimed exactly like a failed one: staging and
+		// cache go, the active runtime and the `installing` journal (with its carried provenance) stay.
+		// The same-artifact early return above never reaches this line, so it runs no probe. A
+		// recovery's own move (restoring or discarding a tree) happens before it and is not observed;
+		// a new candidate staged afterwards reaches this line like any other.
+		if (admitCandidate !== undefined) {
+			const verdict = admitCandidate(
+				path.join(layout.stagingDir, "node_modules", completenessOf(requested, acquired).name),
+			);
+			if (verdict !== undefined) {
+				throw new RuntimeBootstrapError(
+					"runtime-candidate-admission-invalid",
+					`admitCandidate returned ${typeof verdict}; admission is synchronous: return nothing to admit, throw to refuse`,
+				);
+			}
+		}
 	} catch (err) {
 		removeTree(layout.stagingDir);
 		// A half-fetched tarball left in the cache is the thing a retry would trip over: npm's own

package/scripts/meta-bridge-fresh-cut.ts

@@ -127,33 +127,7 @@ import { probeSocketLiveness } from "../pi-extensions/lib/socket-probe.ts";
 
 function usage(code: number): never {
 	console.error(
-		[
-			"usage: node --experimental-strip-types scripts/meta-bridge-fresh-cut.ts",
-			"       (dev clone: `./run.sh meta-bridge-fresh-cut` · installed package: `entwurf meta-bridge-fresh-cut`)",
-			"",
-			"  Open a fresh meta-bridge generation: quiesce-check every live surface, then",
-			"  archive meta-sessions/ + meta-mailbox/ to `<dir>.archive-<timestamp>` siblings,",
-			"  clear dead sender/receiver markers and dead control sockets, and open empty",
-			"  live dirs. No migration, no restore: the archive is forensic bytes only.",
-			"",
-			"store   = ENTWURF_META_SESSIONS_DIR || <PI_CODING_AGENT_DIR|~/.pi/agent>/meta-sessions",
-			"mailbox = ENTWURF_META_MAILBOX_DIR  || <PI_CODING_AGENT_DIR|~/.pi/agent>/meta-mailbox",
-			"sockets = ENTWURF_DIR               || ~/.pi/entwurf-control",
-			"",
-			"EXIT CONTRACT (#54) — what already moved, not how bad it was:",
-			`  ${FRESH_CUT_EXIT.COMPLETE}  cut complete: generation archived (or none existed), fresh v3 store open,`,
-			"     residue cleared. `&& setup` is correct here.",
-			`  ${FRESH_CUT_EXIT.NO_MOVE}  NOTHING MOVED: a live/unprovable surface, an occupied archive destination,`,
-			"     an unreadable surface, or a first rename that failed. The host is unchanged —",
-			"     fix the named cause and re-run. Do NOT run setup: the store it refused is still there.",
-			`  ${FRESH_CUT_EXIT.USAGE}  usage.`,
-			`  ${FRESH_CUT_EXIT.HALF_CUT}  CUT TRANSITION INCOMPLETE: at least one archive move happened,`,
-			"     but the fresh generation is not confirmed open. Inspect, or re-run to finish under a new stamp.",
-			`  ${FRESH_CUT_EXIT.CLEANUP_INCOMPLETE}  CUT COMPLETE, CLEANUP INCOMPLETE: the generation IS archived and the fresh`,
-			"     generation IS open — install and citizen birth are unblocked, so setup may run —",
-			"     but marker/socket residue survived. Prefer fixing it and re-running BEFORE setup; after new citizen birth,",
-			"     remove the named residue manually instead of archiving the new generation with another cut.",
-		].join("\n"),
+		"meta-bridge-fresh-cut: see `entwurf help meta-bridge-fresh-cut` (from that checkout's root: `./run.sh help meta-bridge-fresh-cut`)",
 	);
 	process.exit(code);
 }

package/scripts/meta-bridge-prune.ts

@@ -31,7 +31,7 @@ function shellQuote(s: string): string {
 
 function usage(code: number): never {
 	console.error(
-		"usage: node --experimental-strip-types scripts/meta-bridge-prune.ts [meta-sessions-dir] [--ttl-days N]",
+		"meta-bridge-prune: see `entwurf help meta-bridge-prune` (from that checkout's root: `./run.sh help meta-bridge-prune`)",
 	);
 	process.exit(code);
 }

package/scripts/meta-facts.ts

@@ -39,7 +39,7 @@ const arg = process.argv[2];
 // A dash argv is a flag this command does not have, not a store directory — treating
 // it as a path would answer `--help` with "empty store, exit 0", a silent wrong fact.
 if (process.argv.length > 3 || (arg !== undefined && arg.startsWith("-"))) {
-	console.error("usage: entwurf meta-facts [meta-sessions-dir]");
+	console.error("meta-facts: see `entwurf help meta-facts` (from that checkout's root: `./run.sh help meta-facts`)");
 	process.exit(2);
 }