@junghanacs/entwurf 0.41.2 → 0.45.0

package/pi-extensions/lib/agent-guidance.ts

@@ -0,0 +1,341 @@
+/**
+ * Product-owned natural-language logic, authored only in root ENTWURF.json (#154).
+ * One module-relative file, read once. The compiled layout carries an exact copy at
+ * dist/ENTWURF.json; no cwd/HOME search, override, old-text fallback or hot reload.
+ * Existing operator engraving and user-configuration contracts are unrelated.
+ */
+import { readFileSync } from "node:fs";
+
+const TOOL_SPEC = {
+	entwurf_v2: { durable: true, parameters: ["target", "intent", "message", "mode", "wants_reply"] },
+	entwurf_self: { durable: true, parameters: [] },
+	entwurf_peers: { durable: true, parameters: [] },
+	entwurf_inbox_read: { durable: true, parameters: ["gardenId"] },
+	entwurf_register_native: { durable: false, parameters: ["backend", "nativeSessionId", "cwd"] },
+	entwurf_fresh_call: {
+		durable: true,
+		parameters: ["backend", "model", "task", "cwd", "placement.tmuxSession", "placement"],
+	},
+	entwurf_resume_call: { durable: true, parameters: ["target"] },
+	entwurf_retire_call: { durable: true, parameters: ["target"] },
+	entwurf_callback: { durable: true, parameters: [] },
+} as const;
+
+/** Frozen entwurf_v2 reject wire ids whose static next-step hint text lives in the root file. */
+const REJECT_HINT_REASONS = [
+	"dormant-fire-forget-unsupported",
+	"indeterminate-no-spawn",
+	"native-push-target-dead",
+	"native-push-probe-indeterminate",
+	"native-push-paused",
+] as const;
+
+export type RejectHintReason = (typeof REJECT_HINT_REASONS)[number];
+
+/** Frozen entwurf_resume_call record/liveness reject wire ids whose static hint text lives in the root file. */
+const RESUME_REJECT_HINT_REASONS = [
+	"target-invalid",
+	"target-backend-unsupported",
+	"target-locked",
+	"target-live",
+	"target-indeterminate",
+	"target-receiver-absent",
+	"target-receiver-corrupt",
+	"target-receiver-mismatch",
+	"target-receiver-unbound",
+	"target-address-conflict",
+	"launch-refused",
+] as const;
+
+export type ResumeRejectHintReason = (typeof RESUME_REJECT_HINT_REASONS)[number];
+
+/** Frozen entwurf_fresh_call tmux launch-stage reject wire ids whose static hint text lives in the root file. */
+const FRESH_LAUNCH_REJECT_HINT_REASONS = [
+	"no-tmux-context",
+	"anchor-malformed",
+	"anchor-unresolved",
+	"anchor-mismatch",
+	"caller-identity-unavailable",
+	"cwd-not-absolute",
+	"cwd-format-token",
+	"cwd-missing",
+	"cwd-not-directory",
+	"tmux-session-name-invalid",
+	"tmux-session-missing",
+	"model-empty",
+	"task-empty",
+	"runtime-unresolved",
+	"runtime-not-absolute",
+	"runtime-path-whitespace",
+	"runtime-missing",
+	"runtime-not-regular-file",
+	"runtime-not-executable",
+] as const;
+
+export type FreshLaunchRejectHintReason = (typeof FRESH_LAUNCH_REJECT_HINT_REASONS)[number];
+
+/** Frozen entwurf_resume_call tmux launch-stage reject wire ids whose static hint text lives in the root file. */
+const RESUME_LAUNCH_REJECT_HINT_REASONS = [
+	"no-tmux-context",
+	"anchor-malformed",
+	"anchor-unresolved",
+	"anchor-mismatch",
+	"cwd-not-absolute",
+	"cwd-format-token",
+	"cwd-missing",
+	"cwd-not-directory",
+	"herdr-resume-unsupported",
+	"runtime-unresolved",
+	"runtime-not-absolute",
+	"runtime-path-whitespace",
+	"runtime-missing",
+	"runtime-not-regular-file",
+	"runtime-not-executable",
+] as const;
+
+export type ResumeLaunchRejectHintReason = (typeof RESUME_LAUNCH_REJECT_HINT_REASONS)[number];
+
+/** Frozen keys of the static delivery-result clauses whose text lives in the root file; the
+ * receipts around them (syntax, branch conditions, slots, punctuation) stay code-owned. */
+const DELIVERY_RESULT_CLAUSE_KEYS = [
+	"finalized-rejected",
+	"dirty-lock",
+	"remote-accepted",
+	"remote-reported-error",
+	"remote-indeterminate",
+] as const;
+
+export type DeliveryResultClauseKey = (typeof DELIVERY_RESULT_CLAUSE_KEYS)[number];
+
+/** Frozen wire ids of the reject hints whose authored text sits on either side of ONE code-owned
+ * slot, and each one's exact segment keys. The slot value, the reason branch and the
+ * concatenation stay code-owned; the root file holds only the text around the slot. */
+const SLOTTED_REJECT_HINT_SEGMENTS = {
+	"record-less-socket": ["beforeFreshCutPrescription", "afterFreshCutPrescription"],
+} as const;
+
+export type SlottedRejectHintReason = keyof typeof SLOTTED_REJECT_HINT_SEGMENTS;
+type SlottedRejectHints = {
+	readonly [R in SlottedRejectHintReason]: Readonly<Record<(typeof SLOTTED_REJECT_HINT_SEGMENTS)[R][number], string>>;
+};
+
+type ToolName = keyof typeof TOOL_SPEC;
+type ToolGuidance<K extends ToolName> = {
+	readonly descriptions: (typeof TOOL_SPEC)[K]["durable"] extends true
+		? { readonly mcp: string; readonly durable: string }
+		: { readonly mcp: string };
+	readonly parameters: Readonly<Record<(typeof TOOL_SPEC)[K]["parameters"][number], string>>;
+};
+
+export interface EntwurfGuidance {
+	readonly _about: Readonly<Record<"purpose" | "ownership" | "scope" | "editing", string>>;
+	readonly schemaVersion: 6;
+	readonly revision: number;
+	readonly history: readonly {
+		readonly revision: number;
+		readonly source: string;
+		readonly issue: string;
+		readonly change: string;
+	}[];
+	readonly tools: { readonly [K in ToolName]: ToolGuidance<K> };
+	readonly rejectHints: Readonly<Record<RejectHintReason, string>>;
+	readonly resumeRejectHints: Readonly<Record<ResumeRejectHintReason, string>>;
+	readonly freshLaunchRejectHints: Readonly<Record<FreshLaunchRejectHintReason, string>>;
+	readonly resumeLaunchRejectHints: Readonly<Record<ResumeLaunchRejectHintReason, string>>;
+	readonly deliveryResultClauses: Readonly<Record<DeliveryResultClauseKey, string>>;
+	readonly slottedRejectHints: SlottedRejectHints;
+}
+
+function record(value: unknown, at: string): asserts value is Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error(`ENTWURF.json ${at}: expected an object`);
+	}
+}
+
+function keys(value: Record<string, unknown>, expected: readonly string[], at: string): void {
+	const actual = Object.keys(value).sort();
+	const wanted = [...expected].sort();
+	if (actual.length !== wanted.length || actual.some((key, i) => key !== wanted[i])) {
+		throw new Error(`ENTWURF.json ${at}: keys must be exactly ${wanted.join(", ")}`);
+	}
+}
+
+function text(value: unknown, at: string): void {
+	if (typeof value !== "string" || value.length === 0) {
+		throw new Error(`ENTWURF.json ${at}: expected a non-empty string`);
+	}
+}
+
+/**
+ * JSON.parse owns strict grammar, but its last-key-wins value is never enough.
+ * Walk the ORIGINAL, already grammar-checked tokens and reject duplicate DECODED
+ * object keys before returning data. Object scopes are independent; strings that
+ * are values (including punctuation and escaped quotes) are never key tokens.
+ */
+function rejectDuplicateKeys(source: string): void {
+	let pos = 0;
+	const space = (): void => {
+		while (pos < source.length && /[\x20\t\r\n]/.test(source[pos])) pos++;
+	};
+	const string = (): string => {
+		const start = pos++;
+		while (pos < source.length) {
+			if (source[pos] === "\\") pos += 2;
+			else if (source[pos++] === '"') return JSON.parse(source.slice(start, pos)) as string;
+		}
+		throw new Error("ENTWURF.json: unterminated string");
+	};
+	const value = (): void => {
+		space();
+		if (source[pos] === "{") {
+			pos++;
+			space();
+			const seen = new Set<string>();
+			if (source[pos] !== "}") {
+				for (;;) {
+					space();
+					const key = string();
+					if (seen.has(key)) throw new Error(`ENTWURF.json: duplicate object key ${JSON.stringify(key)}`);
+					seen.add(key);
+					space();
+					pos++; // colon; JSON.parse already certified the grammar
+					value();
+					space();
+					if (source[pos] !== ",") break;
+					pos++;
+				}
+			}
+			pos++;
+		} else if (source[pos] === "[") {
+			pos++;
+			space();
+			if (source[pos] !== "]") {
+				for (;;) {
+					value();
+					space();
+					if (source[pos] !== ",") break;
+					pos++;
+				}
+			}
+			pos++;
+		} else if (source[pos] === '"') {
+			string();
+		} else {
+			while (pos < source.length && !/[\x20\t\r\n,}\]]/.test(source[pos])) pos++;
+		}
+	};
+	value();
+}
+
+function freeze(value: unknown): void {
+	if (value === null || typeof value !== "object") return;
+	for (const child of Object.values(value)) freeze(child);
+	Object.freeze(value);
+}
+
+/** Pure data-validation seam; production always reads the one fixed module URL below. */
+export function parseEntwurfGuidance(source: string): EntwurfGuidance {
+	const data: unknown = JSON.parse(source);
+	rejectDuplicateKeys(source);
+	record(data, "root");
+	if (data.schemaVersion !== 6) throw new Error("ENTWURF.json: unsupported schemaVersion");
+	keys(
+		data,
+		[
+			"_about",
+			"schemaVersion",
+			"revision",
+			"history",
+			"tools",
+			"rejectHints",
+			"resumeRejectHints",
+			"freshLaunchRejectHints",
+			"resumeLaunchRejectHints",
+			"deliveryResultClauses",
+			"slottedRejectHints",
+		],
+		"root",
+	);
+	if (!Number.isSafeInteger(data.revision) || (data.revision as number) < 1) {
+		throw new Error("ENTWURF.json: revision must be a positive safe integer");
+	}
+	record(data._about, "_about");
+	keys(data._about, ["purpose", "ownership", "scope", "editing"], "_about");
+	for (const [key, value] of Object.entries(data._about)) text(value, `_about.${key}`);
+	if (!Array.isArray(data.history) || data.history.length === 0) {
+		throw new Error("ENTWURF.json: history must be a non-empty array");
+	}
+	for (const entry of data.history) {
+		record(entry, "history entry");
+		keys(entry, ["revision", "source", "issue", "change"], "history entry");
+		if (
+			!Number.isSafeInteger(entry.revision) ||
+			(entry.revision as number) < 1 ||
+			(entry.revision as number) > (data.revision as number)
+		) {
+			throw new Error("ENTWURF.json: history revision must name an existing payload revision");
+		}
+		for (const key of ["source", "issue", "change"] as const) text(entry[key], `history.${key}`);
+	}
+	record(data.tools, "tools");
+	keys(data.tools, Object.keys(TOOL_SPEC), "tools");
+	for (const name of Object.keys(TOOL_SPEC) as ToolName[]) {
+		const tool = data.tools[name];
+		record(tool, name);
+		keys(tool, ["descriptions", "parameters"], name);
+		record(tool.descriptions, `${name}.descriptions`);
+		keys(tool.descriptions, TOOL_SPEC[name].durable ? ["mcp", "durable"] : ["mcp"], `${name}.descriptions`);
+		for (const [rail, value] of Object.entries(tool.descriptions)) text(value, `${name}.descriptions.${rail}`);
+		record(tool.parameters, `${name}.parameters`);
+		keys(tool.parameters, TOOL_SPEC[name].parameters, `${name}.parameters`);
+		for (const [field, value] of Object.entries(tool.parameters)) text(value, `${name}.parameters.${field}`);
+	}
+	record(data.rejectHints, "rejectHints");
+	keys(data.rejectHints, REJECT_HINT_REASONS, "rejectHints");
+	for (const [reason, value] of Object.entries(data.rejectHints)) text(value, `rejectHints.${reason}`);
+	record(data.resumeRejectHints, "resumeRejectHints");
+	keys(data.resumeRejectHints, RESUME_REJECT_HINT_REASONS, "resumeRejectHints");
+	for (const [reason, value] of Object.entries(data.resumeRejectHints)) text(value, `resumeRejectHints.${reason}`);
+	record(data.freshLaunchRejectHints, "freshLaunchRejectHints");
+	keys(data.freshLaunchRejectHints, FRESH_LAUNCH_REJECT_HINT_REASONS, "freshLaunchRejectHints");
+	for (const [reason, value] of Object.entries(data.freshLaunchRejectHints))
+		text(value, `freshLaunchRejectHints.${reason}`);
+	record(data.resumeLaunchRejectHints, "resumeLaunchRejectHints");
+	keys(data.resumeLaunchRejectHints, RESUME_LAUNCH_REJECT_HINT_REASONS, "resumeLaunchRejectHints");
+	for (const [reason, value] of Object.entries(data.resumeLaunchRejectHints))
+		text(value, `resumeLaunchRejectHints.${reason}`);
+	record(data.deliveryResultClauses, "deliveryResultClauses");
+	keys(data.deliveryResultClauses, DELIVERY_RESULT_CLAUSE_KEYS, "deliveryResultClauses");
+	for (const [key, value] of Object.entries(data.deliveryResultClauses)) text(value, `deliveryResultClauses.${key}`);
+	record(data.slottedRejectHints, "slottedRejectHints");
+	keys(data.slottedRejectHints, Object.keys(SLOTTED_REJECT_HINT_SEGMENTS), "slottedRejectHints");
+	for (const reason of Object.keys(SLOTTED_REJECT_HINT_SEGMENTS) as SlottedRejectHintReason[]) {
+		const segments = data.slottedRejectHints[reason];
+		record(segments, `slottedRejectHints.${reason}`);
+		keys(segments, SLOTTED_REJECT_HINT_SEGMENTS[reason], `slottedRejectHints.${reason}`);
+		for (const [key, value] of Object.entries(segments)) text(value, `slottedRejectHints.${reason}.${key}`);
+	}
+	freeze(data);
+	return data as unknown as EntwurfGuidance;
+}
+
+const guidance = parseEntwurfGuidance(readFileSync(new URL("../../ENTWURF.json", import.meta.url), "utf8"));
+
+/** Only these exact payload strings enter tool schemas; _about/history never do. */
+export const ENTWURF_TOOL_GUIDANCE = guidance.tools;
+/** Static next-step text appended to these entwurf_v2 rejections; the decider and wire ids stay code-owned. */
+export const ENTWURF_REJECT_HINTS = guidance.rejectHints;
+/** Static next-step text in these entwurf_resume_call record/liveness rejections; the verb and the shared ACP model hint stay code-owned. */
+export const ENTWURF_RESUME_REJECT_HINTS = guidance.resumeRejectHints;
+/** Static tmux launch-stage hints of entwurf_fresh_call; slot-bearing, ACP and preflight-leaf hints stay code-owned. */
+export const ENTWURF_FRESH_LAUNCH_REJECT_HINTS = guidance.freshLaunchRejectHints;
+/** Static tmux launch-stage hints of entwurf_resume_call, kept apart from the fresh verb even where the text matches. */
+export const ENTWURF_RESUME_LAUNCH_REJECT_HINTS = guidance.resumeLaunchRejectHints;
+/** Static delivery-result clauses of the entwurf_v2 dirty-lock and remote-pair receipts; the receipt syntax around them stays code-owned. */
+export const ENTWURF_DELIVERY_RESULT_CLAUSES = guidance.deliveryResultClauses;
+/** Text on either side of one code-owned slot per reject reason; the slot value and the concatenation stay with the consumer. */
+export const ENTWURF_SLOTTED_REJECT_HINTS = guidance.slottedRejectHints;
+export const ENTWURF_GUIDANCE_VERSION = Object.freeze({
+	schemaVersion: guidance.schemaVersion,
+	revision: guidance.revision,
+});

package/pi-extensions/lib/entwurf-v2-surface.ts

@@ -18,6 +18,11 @@
  */
 
 import { basename } from "node:path";
+import {
+	ENTWURF_DELIVERY_RESULT_CLAUSES,
+	ENTWURF_REJECT_HINTS,
+	ENTWURF_SLOTTED_REJECT_HINTS,
+} from "./agent-guidance.ts";
 import type { SenderEnvelope } from "./entwurf-control-rpc.ts";
 import type { DispatchInput, EntwurfV2Mode } from "./entwurf-v2-decider.ts";
 import { makeProductionEntwurfV2Deps, type ProductionEntwurfV2Opts } from "./entwurf-v2-production.ts";
@@ -65,7 +70,9 @@ export function toDispatchInput(params: SurfaceEntwurfV2Params): DispatchInput {
  * Detour B (B-a) — actionable rendering of an honest reject. The decider is UNCHANGED:
  * a reject stays a reject (Hard Rule 3). This only appends a one-line "what to do instead"
  * to the reject TEXT, so an honest reject stops reading as "delivery impossible". Returns
- * undefined for rejects with no useful next step.
+ * undefined for rejects with no useful next step. Hint English is authored in root ENTWURF.json
+ * (#154); the reason switch stays here, and so do the record-less-socket slot value and its
+ * concatenation (#154 E1b).
  */
 export function actionableRejectHint(reason: string): string | undefined {
 	switch (reason) {
@@ -74,13 +81,7 @@ export function actionableRejectHint(reason: string): string | undefined {
 			// state — the citizen exists and is not running — matters more than ever now that
 			// there is no verb behind it: a caller that reads "reject" as "wrong id" goes
 			// looking in the wrong place.
-			return (
-				"this citizen's record is intact but its session is not running, and delivery has no way to wake it. " +
-				"The resume that used to answer here launched a hidden background child and was withdrawn under the " +
-				"visible-first rule; the visible same-id resume is the separate lifecycle verb entwurf_resume_call. " +
-				"Only on an explicit operator request, use entwurf_resume_call {target} for Pi or Claude Code; " +
-				"it submits no prompt. This capability hint is not permission to resume automatically."
-			);
+			return ENTWURF_REJECT_HINTS["dormant-fire-forget-unsupported"];
 		case "indeterminate-no-spawn":
 			// The socket probe did not settle, so liveness is UNKNOWN — an unestablished probe
 			// is not a measured death, and dispatching into it could double-deliver. Say
@@ -91,35 +92,27 @@ export function actionableRejectHint(reason: string): string | undefined {
 			// (never dispatch into an indeterminate target), not a capability that still
 			// exists. So the hint's job is to say plainly what did NOT happen: nothing
 			// delivered, nothing started.
-			return (
-				"the control-socket probe was inconclusive, so the target's liveness is UNKNOWN — this is not a " +
-				"measured death. NOTHING was delivered and NO process was started (the reason id keeps its frozen " +
-				"'-no-spawn' wire spelling from an era when one could be; entwurf_v2 starts nothing on any rail). " +
-				"Re-run entwurf_peers to re-probe; if it stays indeterminate, check for a stale socket file left at " +
-				"that garden id by a session that died without cleaning up."
-			);
+			return ENTWURF_REJECT_HINTS["indeterminate-no-spawn"];
 		case "native-push-target-dead":
 			// The adapter probe found no live native host serving this conversation/thread. Stays
 			// backend-neutral: agy speaks conversations over an LS port, Codex threads over an
 			// app-server socket, and this hint is read by callers of both.
-			return "the native-push conversation/thread is not live — no native host (harness process or app-server) answered the probe for it. Re-open that conversation/thread in its own harness, then retry; there is nothing to inject into.";
+			return ENTWURF_REJECT_HINTS["native-push-target-dead"];
 		case "native-push-probe-indeterminate":
 			// Native host up, but nothing served this conversation/thread — inconclusive, not a
 			// hard dead. Backend-neutral for the same reason as the dead cell above.
-			return "the native host (harness process or app-server) is up, but nothing served this conversation/thread, so the probe is INCONCLUSIVE — not a measured death. Retry once it is loaded, or verify the conversation/thread id.";
+			return ENTWURF_REJECT_HINTS["native-push-probe-indeterminate"];
 		case "native-push-paused":
 			// #152: a policy refusal, not a liveness verdict — this dispatch probed and sent nothing.
-			return "native-push for this backend is paused (#152): its language server refused entwurf's measured external calls for a missing CSRF token, so this dispatch probed and sent nothing. The citizen and its record are kept; reach it from inside its own harness instead.";
-		case "record-less-socket":
+			return ENTWURF_REJECT_HINTS["native-push-paused"];
+		case "record-less-socket": {
 			// #50 C4: name the true cause AND the fix — a bare socket is a diagnostic
-			// state, not an addressable citizen (the record is the address).
-			return (
-				"a control socket exists at this garden id but NO meta-record claims it — the record is the " +
-				"sole address authority, so a bare socket is not an addressable citizen. If a pre-record-era " +
-				"resident owns that socket, restart it under the current runtime (session_start births its " +
-				`record); if the store predates the current generation, quiesce and archive it with ` +
-				`${FRESH_CUT_PRESCRIPTION}. A stale/forged socket should be removed.`
-			);
+			// state, not an addressable citizen (the record is the address). The text on either
+			// side of the fix command is authored in root ENTWURF.json; the command itself stays
+			// with its owner (meta-session.ts), so the root file never copies it.
+			const hint = ENTWURF_SLOTTED_REJECT_HINTS["record-less-socket"];
+			return `${hint.beforeFreshCutPrescription}${FRESH_CUT_PRESCRIPTION}${hint.afterFreshCutPrescription}`;
+		}
 		default:
 			return undefined;
 	}
@@ -221,17 +214,18 @@ export function renderEntwurfV2Result(result: EntwurfV2RunResult): EntwurfV2Surf
 				// the same acceptance vocabulary the ordinary receipt uses is named here too — a
 				// dirty lock is a reason to be MORE precise about what happened, not less, because
 				// the operator is about to decide by hand whether anything needs re-sending.
+				// The two static clauses are authored in root ENTWURF.json (#154 E1a); this receipt's
+				// syntax, branches and slots stay here.
 				const what =
 					result.finalizedOutcome === "rejected"
-						? `rejected${result.finalizedRejectReason ? ` (${result.finalizedRejectReason})` : ""} — the receiver refused it; nothing was accepted`
+						? `rejected${result.finalizedRejectReason ? ` (${result.finalizedRejectReason})` : ""} — ${ENTWURF_DELIVERY_RESULT_CLAUSES["finalized-rejected"]}`
 						: `${result.finalizedBoundary ?? "mailbox-enqueued"}${
 								result.finalizedMessagePath ? ` (enqueued ${basename(result.finalizedMessagePath)})` : ""
 							}`;
 				return {
 					text:
-						`entwurf_v2 ${result.transport} finalized as ${what}, and the lock is DIRTY ` +
-						`(release failed) — do NOT retry, a re-send would double-deliver. Clear the lock by hand.` +
-						`\n  error: ${result.error}`,
+						`entwurf_v2 ${result.transport} finalized as ${what}, and ` +
+						`${ENTWURF_DELIVERY_RESULT_CLAUSES["dirty-lock"]}\n  error: ${result.error}`,
 					isError: true,
 				};
 			}

package/pi-extensions/lib/entwurf-v2-visible-resume.ts

@@ -74,6 +74,7 @@
  */
 
 import { ACP_MODEL_NOT_CURATED_HINT, AcpModelNotCuratedError } from "./acp/model-ids.js";
+import { ENTWURF_RESUME_REJECT_HINTS } from "./agent-guidance.ts";
 import { buildResumePiArgs } from "./entwurf-resume-args.ts";
 import {
 	type AcquireLockResult,
@@ -633,24 +634,22 @@ export async function observeSameGidSocket(
 	}
 }
 
+// The static record/liveness hint text is authored in root ENTWURF.json (#154 C1-C); the reasons,
+// this total table and the renderer stay here. acp-model-not-curated keeps the shared ACP constant,
+// and the launch-stage mux hints folded into `detail` stay behind the mux import fence.
 const REJECT_HINT: Record<VisibleResumeRejectReason, string> = {
-	"target-invalid": "no citizen has that id; discover targets with entwurf_peers",
-	"target-backend-unsupported":
-		"that citizen's backend has no same-id resume (only pi and Claude Code do) — reach it with entwurf_v2, or open a fresh sibling",
+	"target-invalid": ENTWURF_RESUME_REJECT_HINTS["target-invalid"],
+	"target-backend-unsupported": ENTWURF_RESUME_REJECT_HINTS["target-backend-unsupported"],
 	"acp-model-not-curated": ACP_MODEL_NOT_CURATED_HINT,
-	"target-locked": "another resume or dispatch holds this citizen's lock right now",
-	"target-live": "that citizen is already running — this verb only reopens dormant ones",
-	"target-indeterminate":
-		"the citizen could not be proven dormant (an inconclusive socket probe or receiver owner), so nothing was started",
-	"target-receiver-absent":
-		"a Claude Code citizen is proven dormant only by its receiver marker, and it has none — if its window is closed, reopen it yourself",
-	"target-receiver-corrupt": "the citizen's receiver marker cannot be read as a marker, so its owner cannot be judged",
-	"target-receiver-mismatch":
-		"the receiver marker under this garden id names another backend or native session than the record — look at the store before anything reopens",
-	"target-receiver-unbound":
-		"the dead receiver owner is not bound to the record's last arm (none observed, a later attach, or the record moved), so a Claude Code process may still hold the session — if its window is closed, reopen it yourself",
-	"target-address-conflict": "that citizen's control-socket path is corrupt",
-	"launch-refused": "tmux was never asked to open a window",
+	"target-locked": ENTWURF_RESUME_REJECT_HINTS["target-locked"],
+	"target-live": ENTWURF_RESUME_REJECT_HINTS["target-live"],
+	"target-indeterminate": ENTWURF_RESUME_REJECT_HINTS["target-indeterminate"],
+	"target-receiver-absent": ENTWURF_RESUME_REJECT_HINTS["target-receiver-absent"],
+	"target-receiver-corrupt": ENTWURF_RESUME_REJECT_HINTS["target-receiver-corrupt"],
+	"target-receiver-mismatch": ENTWURF_RESUME_REJECT_HINTS["target-receiver-mismatch"],
+	"target-receiver-unbound": ENTWURF_RESUME_REJECT_HINTS["target-receiver-unbound"],
+	"target-address-conflict": ENTWURF_RESUME_REJECT_HINTS["target-address-conflict"],
+	"launch-refused": ENTWURF_RESUME_REJECT_HINTS["launch-refused"],
 };
 
 /**

package/pi-extensions/lib/mux-fresh-call.ts

@@ -87,6 +87,7 @@
  */
 
 import { ACP_MODEL_NOT_CURATED_HINT } from "./acp/model-ids.js";
+import { ENTWURF_FRESH_LAUNCH_REJECT_HINTS } from "./agent-guidance.ts";
 import { callbackEnvAssignments } from "./callback-env.ts";
 import { classifyTmuxCwd, type TmuxCwdRejectReason } from "./classify-tmux-cwd.ts";
 import {
@@ -629,7 +630,9 @@ export function freshCall(
 }
 
 /** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
- * they will guess about. */
+ * they will guess about. The static tmux launch-stage text is authored in root
+ * ENTWURF.json (#154 C1-D) and bound key by key, never spread, so a duplicate or missing reason
+ * still fails typecheck; slot-bearing, ACP and preflight-leaf hints stay code-owned. */
 const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	// The Copilot capability reasons keep their repair text on the leaf that decides them, so
 	// the sentence an operator reads cannot drift away from the predicate that produced it.
@@ -641,34 +644,28 @@ const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	...CODEX_CALLER_PREFLIGHT_HINT,
 	...CODEX_CALLER_SEAT_HINT,
 	...FRESH_CALL_PROVIDER_HINT,
-	"no-tmux-context": "this agent is not running inside tmux, so there is no session to open a sibling beside",
-	"anchor-malformed": "TMUX_PANE is not a native pane id",
-	"anchor-unresolved": "tmux resolved no pane for this agent's anchor",
-	"anchor-mismatch": "tmux answered about a different pane than the one asked about",
-	"caller-identity-unavailable":
-		"this surface has no record-backed garden id for the caller, so the sibling would have no address to call back to",
-	"cwd-not-absolute":
-		"the requested cwd is not an absolute path (the value is taken literally — nothing trims or resolves it)",
-	"cwd-format-token":
-		"the requested cwd contains '#', which tmux expands as a format inside -c — it would silently rewrite the path or run a command",
-	"cwd-missing":
-		"the requested cwd does not exist; tmux would not report this, it would open the window in $HOME and look successful",
-	"cwd-not-directory": "the requested cwd exists but is not a directory",
-	"tmux-session-name-invalid":
-		"the requested tmux session name is outside the shape this rail addresses (start with a letter or digit, then letters, digits, '_' or '-') — some other shapes tmux cannot resolve at all ('#' is expanded when the name is stored; '.' and ':' are its own pane/window separators inside a target; a name like '$0' loses to the session id '$0'), and the rest are declined to keep one narrow grammar, so rename the session or open one whose name fits",
-	"tmux-session-missing":
-		"no session with that exact name answers on this agent's tmux server (or that server stopped answering) — nothing was created, so open the session yourself and call again",
-	"model-empty": "model is empty after trimming; fresh calls require an explicit model",
+	"no-tmux-context": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["no-tmux-context"],
+	"anchor-malformed": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["anchor-malformed"],
+	"anchor-unresolved": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["anchor-unresolved"],
+	"anchor-mismatch": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["anchor-mismatch"],
+	"caller-identity-unavailable": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["caller-identity-unavailable"],
+	"cwd-not-absolute": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["cwd-not-absolute"],
+	"cwd-format-token": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["cwd-format-token"],
+	"cwd-missing": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["cwd-missing"],
+	"cwd-not-directory": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["cwd-not-directory"],
+	"tmux-session-name-invalid": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["tmux-session-name-invalid"],
+	"tmux-session-missing": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["tmux-session-missing"],
+	"model-empty": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["model-empty"],
 	"model-invalid": `model must be one ${MODEL_MAX_CHARS}-character argv-safe id/alias without whitespace or tmux syntax`,
 	"acp-model-not-curated": ACP_MODEL_NOT_CURATED_HINT,
-	"task-empty": "task is empty after trimming",
+	"task-empty": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["task-empty"],
 	"task-too-long": `task exceeds ${TASK_MAX_CHARS} characters`,
-	"runtime-unresolved": "the backend's runtime is not installed on PATH",
-	"runtime-not-absolute": "the resolved runtime path is not absolute",
-	"runtime-path-whitespace": "the resolved runtime path contains whitespace, which tmux would re-split",
-	"runtime-missing": "nothing exists at the resolved runtime path",
-	"runtime-not-regular-file": "the resolved runtime path is not a regular file",
-	"runtime-not-executable": "the resolved runtime path is not executable",
+	"runtime-unresolved": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-unresolved"],
+	"runtime-not-absolute": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-not-absolute"],
+	"runtime-path-whitespace": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-path-whitespace"],
+	"runtime-missing": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-missing"],
+	"runtime-not-regular-file": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-not-regular-file"],
+	"runtime-not-executable": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-not-executable"],
 };
 
 /**

package/pi-extensions/lib/mux-resume-call.ts

@@ -49,6 +49,7 @@
  * to acceptance, not to the product's launch receipt.
  */
 
+import { ENTWURF_RESUME_LAUNCH_REJECT_HINTS } from "./agent-guidance.ts";
 import { classifyTmuxCwd, type TmuxCwdRejectReason } from "./classify-tmux-cwd.ts";
 import {
 	assertLaunchTarget,
@@ -187,24 +188,22 @@ export function resumeCall(
 }
 
 /** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
- * they will guess about. */
+ * they will guess about. The text is authored in root ENTWURF.json (#154 C1-D); each
+ * key is bound explicitly so the reason union stays exhaustive here. */
 export const RESUME_CALL_REJECT_HINT: Record<ResumeCallRejectReason, string> = {
-	"no-tmux-context": "this agent is not running inside tmux, so there is no session to reopen the citizen in",
-	"anchor-malformed": "TMUX_PANE is not a native pane id",
-	"anchor-unresolved": "tmux resolved no pane for this agent's anchor",
-	"anchor-mismatch": "tmux answered about a different pane than the one asked about",
-	"cwd-not-absolute": "the recorded cwd is not an absolute path",
-	"cwd-format-token":
-		"the recorded cwd contains '#', which tmux expands as a format inside -c — it would silently rewrite the path or run a command",
-	"cwd-missing":
-		"the recorded cwd no longer exists; tmux would not report this, it would open the window in $HOME and look successful",
-	"cwd-not-directory": "the recorded cwd exists but is not a directory",
-	"herdr-resume-unsupported":
-		"this agent runs inside herdr, and same-id resume has only a tmux rail — nothing was opened in any ambient tmux session",
-	"runtime-unresolved": "the citizen's runtime (pi or claude) is not installed on PATH",
-	"runtime-not-absolute": "the resolved runtime path is not absolute",
-	"runtime-path-whitespace": "the resolved runtime path contains whitespace, which tmux would re-split",
-	"runtime-missing": "nothing exists at the resolved runtime path",
-	"runtime-not-regular-file": "the resolved runtime path is not a regular file",
-	"runtime-not-executable": "the resolved runtime path is not executable",
+	"no-tmux-context": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["no-tmux-context"],
+	"anchor-malformed": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["anchor-malformed"],
+	"anchor-unresolved": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["anchor-unresolved"],
+	"anchor-mismatch": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["anchor-mismatch"],
+	"cwd-not-absolute": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-not-absolute"],
+	"cwd-format-token": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-format-token"],
+	"cwd-missing": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-missing"],
+	"cwd-not-directory": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-not-directory"],
+	"herdr-resume-unsupported": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["herdr-resume-unsupported"],
+	"runtime-unresolved": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-unresolved"],
+	"runtime-not-absolute": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-not-absolute"],
+	"runtime-path-whitespace": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-path-whitespace"],
+	"runtime-missing": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-missing"],
+	"runtime-not-regular-file": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-not-regular-file"],
+	"runtime-not-executable": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-not-executable"],
 };