@junghanacs/entwurf 0.41.1 → 0.45.0

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/fresh-call-composition.ts

@@ -67,7 +67,7 @@ export const FRESH_CALL_CALLBACK_TOOL: Record<FreshCallBackend, string> = {
 	copilot: "entwurf-bridge-entwurf_callback",
 	omp: "mcp__entwurf_bridge_entwurf_callback",
 	// Codex's tool process is the operator app-server, not the pane: the no-arg
-	// verb refuses there by name. First action stays the delivery verb with args.
+	// verb refuses there by name. Its callback stays the delivery verb with args.
 	codex: "mcp__entwurf_bridge__entwurf_v2",
 	// The durable contact registers the bridge verbs as its OWN tools under their bare names, and the
 	// app offers a tool to the model by its registered name (`durable/harness/registry.ts:99`
@@ -381,8 +381,8 @@ export function composeBackendArgs(
  * PLACEMENT SENTENCE. The first line names where the sibling was opened, and only the RAIL knows
  * that — "the operator's tmux session" is true of a `new-window` launch and false of a herdr
  * pane. It is therefore supplied by the caller rather than composed here. Everything BELOW that
- * line is rail-independent and stays the contract: the callback is the first action, the task
- * follows it, and the three prohibitions are measured rather than polite.
+ * line is rail-independent and stays the contract: the callback comes before the task, an optional
+ * read-only check of the caller may come before the callback, and the steering is stated as fact.
  */
 /**
  * The first-turn framing, WITHOUT the task.
@@ -394,8 +394,13 @@ export function composeBackendArgs(
  * the halves separate is what lets the framing stay plain prose on both rails while the operator's
  * task text keeps every byte it was written with.
  *
- * Order is the contract: the callback is the FIRST action and the task follows it, so a sibling
- * that gets stuck in the task has already told the caller who it is.
+ * Order is the contract: the callback comes BEFORE THE TASK, so a sibling that gets stuck in the
+ * task has already told the caller who it is. It is not the literal first tool call. `[GLG 직접,
+ * 2026-10-24]` checking the caller and then calling back is the right order, and the framing used
+ * to say both "FIRST ACTION … call back" and "you can corroborate the caller first" — two
+ * sentences that cannot both be obeyed. What may come before the callback is the one read-only
+ * check offered below (and, where a dialect needs it, loading the tools); reading files, running
+ * commands or starting the task may not.
  *
  * WHAT THIS SAYS AND WHY IT STOPPED SAYING THE REST (#116). Until 2026-09-17 this framing carried
  * three prohibitions, including "Do not inspect environment variables, do not call entwurf_self".
@@ -433,7 +438,7 @@ export function composeFreshCallFraming(params: {
 	const firstAction =
 		params.backend === "codex"
 			? [
-					`FIRST ACTION, before reading files or anything else: call ${birthTool} with ` +
+					`BEFORE THE TASK, and before reading files or running commands: call ${birthTool} with ` +
 						`target=${params.callerGardenId}, intent=fire-and-forget, wants_reply=false, and ` +
 						`message set to exactly ${params.nonce} — that string alone, nothing added.`,
 					`${params.nonce} is a correlation tag this caller minted for this one launch: it names no`,
@@ -443,7 +448,7 @@ export function composeFreshCallFraming(params: {
 					"entwurf_callback is refused on this rail: the tool process is the operator app-server, not this pane.",
 				]
 			: [
-					`FIRST ACTION, before reading files or anything else: call ${birthTool} with no arguments.`,
+					`BEFORE THE TASK, and before reading files or running commands: call ${birthTool} with no arguments.`,
 					"That call is how the caller learns the garden id you were born with. There are no",
 					"parameters: a target or message you type would be a second address axis.",
 					"Your own record does not carry the caller's address, so reporting your identity here does not reach it — that tool call does.",
@@ -453,9 +458,15 @@ export function composeFreshCallFraming(params: {
 		"",
 		...firstAction,
 		"",
-		`You can corroborate the caller first if you want to: ${peersTool} is a read-only listing of`,
-		`this garden's citizens and ${params.callerGardenId} is one of them. That listing is capped, so`,
-		"a caller you do not happen to see in it is not a reason to skip the callback.",
+		// THE CHECK IS THE SIBLING'S, AND SO IS ITS VERDICT. `[GLG 직접, 2026-10-24]` a capped listing that
+		// does not show the caller proves nothing about the caller, but a sibling whose check does not hold
+		// up may say so and hold back. Entwurf decides nothing here — no trust store, no fallback, no
+		// watcher — and the cost of holding back is stated, not hidden: no callback, no address.
+		`You may corroborate the caller before that call: ${peersTool} is a read-only listing of`,
+		`this garden's citizens and ${params.callerGardenId} is one of them. That listing is capped, so not`,
+		"seeing the caller in it does not show the caller is absent. If what you can check is not enough,",
+		"or it conflicts with this message, you may say so here and hold the callback and the task; the",
+		"caller then has no address for you.",
 		...hintBlock,
 		"",
 		// WHERE THE RESULT GOES, said once, as topology. `[GLG 직접, 2026-09-18]` a Sonnet sibling

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

@@ -1232,10 +1232,12 @@ export function renderHerdrFreshCall(result: HerdrFreshCallResult): { text: stri
 			`mean the sibling is running, that its first turn ran, or that the task was delivered. The tab and pane ` +
 			`coordinates are a view and can change under the sibling — they are not an address and nothing may be ` +
 			`dispatched to them.\n` +
-			`The sibling's garden id arrives separately — its first action is the zero-argument callback verb, and ` +
+			`The sibling's garden id arrives separately — before its task it calls the zero-argument callback verb ` +
+			`(a read-only look at the caller may come first), and ` +
 			`the sender envelope of THAT message is the address. The nonce above is the correlation tag it carries; ` +
 			`the sibling reads it from its own launch env, never from this receipt. Nothing is polling for it; if it ` +
-			`never comes, the pane is visible and can be read directly.`,
+			`never comes — not started, stuck, or held back after its check; this receipt cannot tell which — the ` +
+			`pane is visible and can be read directly.`,
 		isError: false,
 	};
 }

package/pi-extensions/lib/meta-sender-identity.ts

@@ -47,6 +47,7 @@
  * a backend listed there is one whose hook writes a pid marker, and codex birth writes none.
  */
 
+import { nativePushPaused } from "./entwurf-v2-contract.ts";
 import {
 	defaultMetaSessionsDir,
 	describe,
@@ -229,6 +230,9 @@ export async function probeNativeSenderAlive(
 	identity: Pick<MetaIdentity, "backend" | "nativeSessionId">,
 	deps: { resolveAdapter?: (id: string) => Pick<NativePushAdapter, "probe"> } = {},
 ): Promise<boolean> {
+	// #152: a paused native-push backend cannot receive a reply, so its `replyable` is false by
+	// POLICY — no adapter is resolved or probed. This is not a liveness verdict about the citizen.
+	if (nativePushPaused(identity.backend)) return false;
 	const resolveAdapter = deps.resolveAdapter ?? resolveNativePushAdapter;
 	const probe = await resolveAdapter(identity.backend).probe(identity.nativeSessionId);
 	return probe.status === "alive";

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"],
 };
 
 /**
@@ -709,11 +706,13 @@ export function renderFreshCall(result: FreshCallResult): { text: string; isErro
 			`\n` +
 			`This is a LAUNCH receipt: tmux created that window and was asked to start the runtime with the model above. It does ` +
 			`NOT mean the sibling is running, that its first turn ran, or that the task was delivered.\n` +
-			`The sibling's garden id arrives separately — its first action is the zero-argument callback verb ` +
-			`(codex is the one arm that still sends the nonce as arguments), and the sender envelope of THAT ` +
+			`The sibling's garden id arrives separately — before its task it calls the zero-argument callback verb ` +
+			`(codex is the one arm that still sends the nonce as arguments; a read-only look at the caller may come ` +
+			`first), and the sender envelope of THAT ` +
 			`message is the address. The nonce above is the correlation tag it carries; the sibling reads it ` +
-			`from its own launch env, never from this receipt. Nothing is polling for it; if it never comes, ` +
-			`the window is visible and can be read directly.`,
+			`from its own launch env, never from this receipt. Nothing is polling for it; if it never comes — ` +
+			`not started, stuck, or held back after its check; this receipt cannot tell which — the window is visible ` +
+			`and can be read directly.`,
 		isError: false,
 	};
 }

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"],
 };

package/pi-extensions/lib/native-push/register.ts

@@ -19,10 +19,12 @@
  * deliverability semantics. `check-native-push-register` asserts this file references no
  * receiver-marker writer. (A dedicated register-provenance slot is a future concern.)
  *
- * LEAF-adjacent + pi-free: imports only the native-push adapter (pi-free) and the meta-session
- * upsert (pi-free), so the harness-neutral MCP bridge can reach it at boot.
+ * LEAF-adjacent + pi-free: imports only the native-push adapter (pi-free), the meta-session
+ * upsert (pi-free) and the pure v2 contract's paused-backend policy, so the harness-neutral MCP
+ * bridge can reach it at boot.
  */
 
+import { nativePushPaused } from "../entwurf-v2-contract.ts";
 import { type MetaCitizenBackend, type UpsertAction, upsertMetaSession } from "../meta-session.ts";
 import { type NativePushAdapter, resolveNativePushAdapter } from "./adapter.ts";
 
@@ -62,6 +64,19 @@ export async function registerNativeConversation(
 	input: RegisterNativeConversationInput,
 	deps: RegisterNativeConversationDeps = {},
 ): Promise<RegisterNativeConversationResult> {
+	// #152: a paused native-push backend is refused by name BEFORE any adapter is resolved or
+	// probed — registration would otherwise reach a language server that refused the measured
+	// external calls (missing CSRF token).
+	// Nothing is probed and no record is written.
+	if (nativePushPaused(input.backend)) {
+		throw new Error(
+			`entwurf_register_native: refusing to register ${input.backend} conversation ${JSON.stringify(
+				input.nativeSessionId,
+			)} — native-push for ${input.backend} is paused (#152: its language server refused ` +
+				"entwurf's measured external calls for a missing CSRF token). Nothing was probed and no garden id was minted; " +
+				"existing records stay readable.",
+		);
+	}
 	const resolveAdapter = deps.resolveAdapter ?? resolveNativePushAdapter;
 	const adapter = resolveAdapter(input.backend);
 	const probe = await adapter.probe(input.nativeSessionId);

package/pi-extensions/lib/omp-fresh-preflight.ts

@@ -20,8 +20,8 @@
  *   callback callable — THE OMP-SPECIFIC ONE. `tools.xdev` defaults to TRUE, which mounts MCP
  *                      tools as `xd://` devices whose schemas never reach the prompt. The tool
  *                      would be configured, the bridge would be running, and the model still
- *                      could not call `mcp__entwurf_bridge_entwurf_v`. Step 9 clause 5 makes the
- *                      callback the FIRST action, so a fresh call onto a default-config host
+ *                      could not call `mcp__entwurf_bridge_entwurf_v`. Step 9 clause 5 puts the
+ *                      callback before the task, so a fresh call onto a default-config host
  *                      opens a window that can never name itself. `[측정]` #87 A-lane: the
  *                      vendor default wrapped the send tool and produced a false delivery report.
  *

package/pi-extensions/lib/pi-durable-fresh-preflight.ts

@@ -15,7 +15,7 @@
  *                 provider spelled out (the bootstrap refuses a model resolved by inference), so
  *                 the model here is `<provider>/<model id>` split at the FIRST `/` — a catalog id
  *                 that itself contains `/` keeps it. A model with no provider part is refused.
- *   first input   the whole framing (callback first, then the task) rides the bootstrap's closed
+ *   first input   the whole framing (callback before the task) rides the bootstrap's closed
  *                 `{v:2,task}` payload, whose decoder caps `task` at 16000 characters. A framed
  *                 task over that cap would open a window whose bootstrap refuses its own argv.
  *

package/pi-extensions/lib/remote-pair-receive.ts

@@ -1,15 +1,16 @@
 /**
- * remote-pair-receive — the RECEIVING half of #107's one declared remote pair (rail 1).
+ * remote-pair-receive — the RECEIVING half of the declared remote pairs (#107 rail 1, #149 routes).
  *
  * The host that owns the target record runs this once per SSH call. It reads one JSON claim
- * from stdin, checks it against the operator-written pair declaration, and hands a matching
+ * from stdin, checks it against the operator-written pair declarations, and hands a matching
  * claim to the existing v2 dispatch. The record, owner and deliverability checks stay the
  * dispatch's own: nothing here writes a mailbox, resolves a rail, or retries.
  *
  * Trust model (GLG, #107 D3 (a)): the boundary is the same operator's SSH account. The pair
- * check is a SCOPE limit, not authentication: a claim whose `from`/`target` is not the declared
- * pair is refused before any mutation. It does not detect that same account sending the
- * declared gid falsely; nothing here claims to.
+ * check is a SCOPE limit, not authentication: a claim whose `from`/`target` is not one declared
+ * pair is refused before any mutation. Both ends are matched in the SAME route (#149), so a sender
+ * declared in one route cannot address the local citizen of another. It does not detect that same
+ * account sending a declared gid falsely; nothing here claims to.
  *
  * Sender: the stdin claim is the only sender input. Ambient carriers (`PI_SESSION_ID`,
  * `PI_AGENT_ID`, sender markers) in the SSH environment are never consulted, so this module
@@ -29,7 +30,7 @@ import type { EntwurfV2SurfaceRendered, SurfaceEntwurfV2Params } from "./entwurf
 import type { MailboxSenderEnvelope } from "./meta-mailbox-body.ts";
 import { requireGardenId } from "./meta-session.ts";
 
-/** One operator-declared pair, as written on the RECEIVING host. */
+/** One operator-declared pair (one route), as written on the RECEIVING host. */
 export interface RemotePairDeclaration {
 	/** The sender's garden id on the other host. */
 	remoteGardenId: string;
@@ -131,24 +132,31 @@ export function parseRemoteClaim(text: string): RemoteClaim {
 	};
 }
 
-/** The scope check. Null = inside the declared pair. */
-export function checkRemotePair(
+/**
+ * The scope check: the one declared pair whose two ends are the claim's `from` and `target`, or a
+ * refusal. The two reasons are the ones every sender already reads (#107), so a sender on another
+ * release still classifies them: an undeclared `from` is a from-mismatch; a declared `from` with a
+ * target that is not ITS declared local (another route's local included) is a target-mismatch.
+ */
+export function selectRemotePair(
 	claim: RemoteClaim,
-	decl: RemotePairDeclaration,
-): { reason: RemotePairRejectReason; detail: string } | null {
-	if (claim.from !== decl.remoteGardenId) {
+	decls: readonly RemotePairDeclaration[],
+): { decl: RemotePairDeclaration } | { reason: RemotePairRejectReason; detail: string } {
+	const fromRoutes = decls.filter((d) => d.remoteGardenId === claim.from);
+	if (fromRoutes.length === 0) {
 		return {
 			reason: "remote-pair-from-mismatch",
-			detail: `from ${claim.from} is not the declared remote ${decl.remoteGardenId}`,
+			detail: `from ${claim.from} is not a declared remote (${decls.map((d) => d.remoteGardenId).join(", ")})`,
 		};
 	}
-	if (claim.target !== decl.localGardenId) {
+	const decl = fromRoutes.find((d) => d.localGardenId === claim.target);
+	if (!decl) {
 		return {
 			reason: "remote-pair-target-mismatch",
-			detail: `target ${claim.target} is not the declared local ${decl.localGardenId}`,
+			detail: `target ${claim.target} is not a declared local for remote ${claim.from} (${fromRoutes.map((d) => d.localGardenId).join(", ")})`,
 		};
 	}
-	return null;
+	return { decl };
 }
 
 export function buildRemoteSenderEnvelope(
@@ -170,12 +178,12 @@ export function buildRemoteSenderEnvelope(
 
 export async function receiveRemoteClaim(
 	claim: RemoteClaim,
-	decl: RemotePairDeclaration,
+	decls: readonly RemotePairDeclaration[],
 	deps: RemoteReceiveDeps,
 ): Promise<RemoteReceiveReceipt> {
-	const mismatch = checkRemotePair(claim, decl);
-	if (mismatch) return { kind: "rejected", ...mismatch };
-	const sender = buildRemoteSenderEnvelope(claim, decl, (deps.now ?? (() => new Date()))(), deps.replyRoute);
+	const picked = selectRemotePair(claim, decls);
+	if (!("decl" in picked)) return { kind: "rejected", ...picked };
+	const sender = buildRemoteSenderEnvelope(claim, picked.decl, (deps.now ?? (() => new Date()))(), deps.replyRoute);
 	const rendered = await deps.dispatch(
 		{ target: claim.target, intent: "fire-and-forget", message: claim.message, wants_reply: claim.wantsReply },
 		sender,