@junghanacs/entwurf 0.41.2 → 0.45.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/agent-guidance.js

@@ -0,0 +1,299 @@
+/**
+ * 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: [] },
+};
+/** 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",
+];
+/** 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",
+];
+/** 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",
+];
+/** 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",
+];
+/** 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",
+];
+/** 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"],
+};
+function record(value, at) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`ENTWURF.json ${at}: expected an object`);
+    }
+}
+function keys(value, expected, at) {
+    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, at) {
+    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) {
+    let pos = 0;
+    const space = () => {
+        while (pos < source.length && /[\x20\t\r\n]/.test(source[pos]))
+            pos++;
+    };
+    const string = () => {
+        const start = pos++;
+        while (pos < source.length) {
+            if (source[pos] === "\\")
+                pos += 2;
+            else if (source[pos++] === '"')
+                return JSON.parse(source.slice(start, pos));
+        }
+        throw new Error("ENTWURF.json: unterminated string");
+    };
+    const value = () => {
+        space();
+        if (source[pos] === "{") {
+            pos++;
+            space();
+            const seen = new Set();
+            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) {
+    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) {
+    const data = 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 < 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 < 1 ||
+            entry.revision > data.revision) {
+            throw new Error("ENTWURF.json: history revision must name an existing payload revision");
+        }
+        for (const key of ["source", "issue", "change"])
+            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)) {
+        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)) {
+        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;
+}
+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/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-surface.js

@@ -17,6 +17,7 @@
  *     surface never needs to name the `EntwurfV2RunResult` union (it only sees `{text,isError}`).
  */
 import { basename } from "node:path";
+import { ENTWURF_DELIVERY_RESULT_CLAUSES, ENTWURF_REJECT_HINTS, ENTWURF_SLOTTED_REJECT_HINTS, } from "./agent-guidance.js";
 import { makeProductionEntwurfV2Deps } from "./entwurf-v2-production.js";
 import { runEntwurfV2 } from "./entwurf-v2-runner.js";
 import { FRESH_CUT_PRESCRIPTION } from "./meta-session.js";
@@ -36,7 +37,9 @@ export function toDispatchInput(params) {
  * 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) {
     switch (reason) {
@@ -45,11 +48,7 @@ export function actionableRejectHint(reason) {
             // 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
@@ -60,31 +59,27 @@ export function actionableRejectHint(reason) {
             // (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;
     }
@@ -185,13 +180,14 @@ export function renderEntwurfV2Result(result) {
                 // 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}`,
+                    text: `entwurf_v2 ${result.transport} finalized as ${what}, and ` +
+                        `${ENTWURF_DELIVERY_RESULT_CLAUSES["dirty-lock"]}\n  error: ${result.error}`,
                     isError: true,
                 };
             }

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-visible-resume.js

@@ -73,6 +73,7 @@
  * half reads the receiver marker and the record instead.
  */
 import { ACP_MODEL_NOT_CURATED_HINT, AcpModelNotCuratedError } from "./acp/model-ids.js";
+import { ENTWURF_RESUME_REJECT_HINTS } from "./agent-guidance.js";
 import { buildResumePiArgs } from "./entwurf-resume-args.js";
 import { ENTWURF_V2_LOCK_DIR, acquireLock as realAcquireLock, releaseLock as realReleaseLock, } from "./entwurf-v2-lock.js";
 import { classifyMarkerOwner, metaReceiverMarkerPath, parseMetaReceiverMarker, probePidExistence, processStartKey, readStoreRecordFile, } from "./meta-session.js";
@@ -441,19 +442,22 @@ export async function observeSameGidSocket(targetGardenId, socketPath, deps, tim
         await deps.sleep(intervalMs);
     }
 }
+// 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 = {
-    "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"],
 };
 /**
  * ONE renderer — the same reason `mux-fresh-call` has one: it keeps the operator-visible answer

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-fresh-call.js

@@ -86,6 +86,7 @@
  *     there is no "session created" field because nothing here creates one.
  */
 import { ACP_MODEL_NOT_CURATED_HINT } from "./acp/model-ids.js";
+import { ENTWURF_FRESH_LAUNCH_REJECT_HINTS } from "./agent-guidance.js";
 import { callbackEnvAssignments } from "./callback-env.js";
 import { classifyTmuxCwd } from "./classify-tmux-cwd.js";
 import { CODEX_CALLER_SEAT_HINT, resolveCodexCallerSeat, } from "./codex-caller-seat.js";
@@ -442,7 +443,9 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
     };
 }
 /** 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 = {
     // 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.
@@ -454,28 +457,28 @@ const REJECT_HINT = {
     ...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"],
 };
 /**
  * ONE renderer, outside the registration. Not a convenience: it keeps the operator-visible answer

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-resume-call.js

@@ -48,6 +48,7 @@
  * where the pane actually landed is a separate query against the stable pane id, and it belongs
  * to acceptance, not to the product's launch receipt.
  */
+import { ENTWURF_RESUME_LAUNCH_REJECT_HINTS } from "./agent-guidance.js";
 import { classifyTmuxCwd } from "./classify-tmux-cwd.js";
 import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, SCRUBBED_INHERITED_ENV, } from "./mux-launch.js";
 import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
@@ -136,21 +137,22 @@ export function resumeCall(params, env = process.env) {
     };
 }
 /** 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 = {
-    "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"],
 };

package/mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-send.js

@@ -25,6 +25,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { ENTWURF_DELIVERY_RESULT_CLAUSES } from "./agent-guidance.js";
 import { controlSocketPathIn } from "./control-socket-path.js";
 import { defaultMetaSessionsDir, metaRecordExistsByGardenId, requireGardenId } from "./meta-session.js";
 import { inspectControlSocketPath } from "./socket-discovery.js";
@@ -204,13 +205,15 @@ export function classifyRemoteReceipt(r) {
     }
     return indeterminate(`exit ${r.exitCode} disagrees with its receipt`);
 }
+// The three static explanatory clauses are authored in root ENTWURF.json (#154 E1a); the receipt
+// syntax, the route label, the slots and the refused/invalid lines stay here.
 function render(route, o) {
     const via = `via ${route.ssh}`;
     switch (o.kind) {
         case "remote-accepted":
             return {
                 isError: false,
-                text: `entwurf_v2 remote ${via} → accepted by the other host (its fact; read/answer unknown until a reply arrives; paths below are on the other host)\n${o.text}`,
+                text: `entwurf_v2 remote ${via} → ${ENTWURF_DELIVERY_RESULT_CLAUSES["remote-accepted"]}\n${o.text}`,
             };
         case "remote-reported-error":
             // The other host's dispatch returned isError. That can follow a write (an enqueue whose
@@ -218,7 +221,7 @@ function render(route, o) {
             // non-delivery nor safety to resend: the other host's own text below is the fact.
             return {
                 isError: true,
-                text: `entwurf_v2 remote ${via} → the other host reported an error while processing; read its receipt below, delivery is not inferred from this line; not retried (paths below are on the other host)\n${o.text}`,
+                text: `entwurf_v2 remote ${via} → ${ENTWURF_DELIVERY_RESULT_CLAUSES["remote-reported-error"]}\n${o.text}`,
             };
         case "remote-pair-refused":
             return {
@@ -230,8 +233,8 @@ function render(route, o) {
         case "remote-indeterminate":
             return {
                 isError: true,
-                text: `entwurf_v2 remote ${via} → indeterminate: ${o.why}. The other host may or may not have enqueued; ` +
-                    `not retried.${o.stderrTail ? `\n${o.stderrTail}` : ""}`,
+                text: `entwurf_v2 remote ${via} → indeterminate: ${o.why}. ` +
+                    `${ENTWURF_DELIVERY_RESULT_CLAUSES["remote-indeterminate"]}${o.stderrTail ? `\n${o.stderrTail}` : ""}`,
             };
     }
 }