@junghanacs/entwurf 0.39.0 → 0.41.0

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

@@ -2,12 +2,13 @@
  * fresh-call-dispatch — the ONE place that decides which rail opens a sibling, and the only module
  * allowed to know that there are two.
  *
- * WHY A COMPOSITION ROOT AND NOT A BRANCH IN EACH SURFACE. Two surfaces register
+ * WHY A COMPOSITION ROOT AND NOT A BRANCH IN EACH SURFACE. Two surfaces once registered
  * `entwurf_fresh_call`: pi's own extension and the MCP bridge. Before this file each of them
  * carried the Codex preflight ordering and the render call itself, and adding a rail choice to
  * both would have made four places where the wrong one could be picked. A defect planted in one
- * copy survives on the other, which is precisely the shape a mutant proves nothing about. So the
- * surfaces now supply identity and an env, and this module supplies everything else.
+ * copy survives on the other, which is precisely the shape a mutant proves nothing about. Since
+ * #125 the bridge is the only registration, and it still supplies only identity and an env; this
+ * module supplies everything else.
  *
  * THE RAIL IS A CAPABILITY FACT, NOT A PARAMETER. `HERDR_ENV=1` — exactly that value, herdr's own
  * variable — means this process is inside herdr and the herdr rail is the honest placement. Every
@@ -27,7 +28,7 @@
 import { spawn as spawnChildProcess } from "node:child_process";
 import { ACP_MODEL_NOT_CURATED, isCuratedAcpModelId, PROVIDER_ID } from "./acp/model-ids.js";
 import { codexCallerFreshPreflight, codexFreshPreflight } from "./codex-fresh-preflight.ts";
-import { isSafeFreshCallModel, mintNonce } from "./fresh-call-composition.ts";
+import { type FreshCallProviderRejectReason, isSafeFreshCallModel, mintNonce } from "./fresh-call-composition.ts";
 import {
 	createHerdrRunner,
 	type HerdrFreshCallResult,
@@ -38,6 +39,7 @@ import {
 	type SpawnFn,
 } from "./herdr-fresh-call.ts";
 import { type FreshCallResult, freshCall, renderFreshCall } from "./mux-fresh-call.ts";
+import { splitPiDurableModel } from "./pi-durable-fresh-preflight.ts";
 
 export type FreshCallRail = "herdr" | "tmux";
 
@@ -68,6 +70,38 @@ export type DispatchedFreshCall =
 	| { readonly rail: "tmux"; readonly result: FreshCallResult }
 	| { readonly rail: "herdr"; readonly result: HerdrFreshCallResult };
 
+/**
+ * #76: the provider a Pi-dialect model string NAMES. pi passes the string to `--model` and Pi
+ * resolves it; pi-durable splits it at the first `/` into `--provider`. So for those two backends
+ * the segment before the first `/` is a provider choice, and for every other backend it is that
+ * vendor's own model name, which this does not judge (a claude-code `opus` stays an alias).
+ *
+ *   model-openrouter-forbidden        pi or pi-durable names the OpenRouter provider. Compared in
+ *                                     any letter case: whether Pi folds case is not measured here,
+ *                                     so the spelling difference fails closed instead of passing.
+ *   pi-model-not-provider-qualified   pi names no provider at all. The alias leaves the provider
+ *                                     choice to Pi's catalog instead of the caller naming it — a
+ *                                     bare `terra` once opened on an OpenRouter row. pi-durable
+ *                                     already refuses the same shape in its own preflight, by the
+ *                                     same predicate.
+ *
+ * WHAT THIS IS NOT. A call-time input contract only: it checks the string a caller wrote, never a
+ * model version, never a list of known ids, never a resolved row or the endpoint a provider name
+ * reaches. A later model name passes THIS provider check once it is written `<provider>/<id>` —
+ * which says nothing about whether it launches or what #128 decides after it. It does not touch
+ * resume, which reopens from the record, and it proves nothing about billing beyond the name.
+ * Read trimmed, and only once the rails' grammar admits the model, exactly like #128 below.
+ */
+export function freshCallProviderRefusal(backend: string, model: string): FreshCallProviderRejectReason | null {
+	if (backend !== "pi" && backend !== "pi-durable") return null;
+	const trimmed = model.trim();
+	if (!isSafeFreshCallModel(trimmed)) return null;
+	const slash = trimmed.indexOf("/");
+	if (slash >= 0 && trimmed.slice(0, slash).toLowerCase() === "openrouter") return "model-openrouter-forbidden";
+	if (backend === "pi" && splitPiDurableModel(trimmed) === null) return "pi-model-not-provider-qualified";
+	return null;
+}
+
 /**
  * #128: a pi sibling asked for under the `entwurf` provider must name an EXACT curated ACP id. Pi
  * resolves `--model` by substring among that provider's rows, so a retired `entwurf/claude-sonnet-5`
@@ -106,6 +140,13 @@ export async function dispatchFreshCall(
 	spawn?: SpawnFn,
 	nonce: string = mintNonce(),
 ): Promise<DispatchedFreshCall> {
+	// Before either rail is asked anything: both would open a pane on a provider nobody chose.
+	const providerRefusal = freshCallProviderRefusal(request.backend, request.model);
+	if (providerRefusal !== null) {
+		return selectFreshCallRail(env) === "herdr"
+			? { rail: "herdr", result: { ok: false, reason: providerRefusal } }
+			: { rail: "tmux", result: { ok: false, reason: providerRefusal } };
+	}
 	// Before either rail is asked anything: both would open a pane on the wrong row.
 	if (isUncuratedEntwurfPiModel(request.backend, request.model)) {
 		return selectFreshCallRail(env) === "herdr"

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

@@ -50,8 +50,10 @@ import {
 	buildOmpBootstrapPayload,
 	composeBackendArgs,
 	composeFreshCallFraming,
+	FRESH_CALL_PROVIDER_HINT,
 	type FreshCallComposition,
 	type FreshCallInputRejectReason,
+	type FreshCallProviderRejectReason,
 	normalizeFreshCallInputs,
 	TASK_MAX_CHARS,
 } from "./fresh-call-composition.ts";
@@ -119,6 +121,7 @@ export type HerdrFreshCallRejectReason =
 	// The caller-facing input contract, shared with the tmux rail so a mistyped model or an
 	// oversized task is answered with the SAME word on either placement owner.
 	| FreshCallInputRejectReason
+	| FreshCallProviderRejectReason
 	| "acp-model-not-curated"
 	| "herdr-context-missing"
 	| "herdr-caller-pane-missing"
@@ -1099,6 +1102,8 @@ async function reclaim(pane: HerdrPaneFacts, run: HerdrRun): Promise<HerdrRecove
  * they will guess about. The five shared input reasons keep the wording the public verb has always
  * used; the rest are this rail's own. */
 const HERDR_REJECT_HINT: Record<HerdrFreshCallRejectReason | HerdrLaunchFailureReason, string> = {
+	// #76: decided at the dispatch root, worded once in the shared composition leaf.
+	...FRESH_CALL_PROVIDER_HINT,
 	"caller-identity-unavailable":
 		"this surface has no record-backed identity, so a sibling would have nowhere to call home",
 	"model-empty": "pass the model you want the sibling opened with — it is never inherited from this process",

package/pi-extensions/lib/meta-mailbox-body.ts

@@ -35,6 +35,9 @@ export interface MailboxSenderEnvelope {
 	timestamp: string; // ISO 8601 UTC
 	origin?: "pi-session" | "external-mcp" | "meta-session";
 	replyable?: boolean;
+	/** #107: set only by the receiving half of a declared remote pair. `via` is the route label;
+	 * `replyRoute` says whether this host declares a route back. Neither is a probe. */
+	remote?: { via: string; replyRoute: "declared" | "none" };
 }
 
 /** `~`-abbreviate a home-relative cwd for display. Reads process.env.HOME. */
@@ -72,14 +75,20 @@ export function formatMetaMailboxBody(sender: MailboxSenderEnvelope, message: st
 	const replyable = sender.replyable === true;
 	const isMeta = sender.origin === "meta-session";
 	const kind = isMeta ? "meta-session, " : "";
+	// A remote sender is never replyable here: no reply route was probed. Its cwd is a path on the
+	// SENDING host, so it is neither abbreviated against this host's HOME nor shown as a local path.
+	const remote = !replyable ? sender.remote : undefined;
 	const sessionLine = replyable
 		? `${sender.sessionId} (${kind}replyable — reply via entwurf_v2 to this sessionId, intent=fire-and-forget)`
-		: isMeta
-			? `${sender.sessionId} (meta-session, non-replyable)`
-			: `${sender.sessionId} (external, non-replyable)`;
+		: remote
+			? `${sender.sessionId} (remote via ${remote.via}; ${remote.replyRoute === "declared" ? "reply route declared, not probed" : "no reply route declared"})`
+			: isMeta
+				? `${sender.sessionId} (meta-session, non-replyable)`
+				: `${sender.sessionId} (external, non-replyable)`;
+	const where = remote ? `${sender.cwd} (sender-host path)` : abbreviateHome(sender.cwd);
 	return (
 		`[entwurf received ⟵]\n` +
-		`  from:        ${sender.agentId} @ ${abbreviateHome(sender.cwd)}\n` +
+		`  from:        ${sender.agentId} @ ${where}\n` +
 		`  session:     ${sessionLine}\n` +
 		`  at:          ${formatKstTimestamp(sender.timestamp)}\n` +
 		`  wants reply: ${wantsReply ? "yes" : "no"}\n` +

package/pi-extensions/lib/meta-session.ts

@@ -354,6 +354,17 @@ export interface MetaIdentity {
 	transcriptPath: string | null;
 	createdAt: string;
 	recordUpdatedAt: string;
+	/**
+	 * The Claude Code arm binding (#147 L2 B1): a clock-independent 128-bit random value
+	 * (`randomBytes(16)`, {@link mintAttachIncarnation}) the CC hook mints on every
+	 * arm-capable event and writes in the SAME atomic upsert as that attach, then copies into
+	 * the receiver marker it writes under the record-arm lock. A dead marker carrying the
+	 * value the record still carries is evidence that no later arm-capable attach happened;
+	 * one that does not carry it is not. `null` means no binding was ever observed — every
+	 * other backend, a record no arm has touched since this field existed, a create — and
+	 * is never filled by inference. Every writer that does not mint PRESERVES it.
+	 */
+	attachIncarnation: string | null;
 }
 
 export function requireCitizenBackend(value: unknown): MetaCitizenBackend {
@@ -476,8 +487,28 @@ const META_IDENTITY_KEYS: readonly string[] = [
 	"transcriptPath",
 	"createdAt",
 	"recordUpdatedAt",
+	"attachIncarnation",
 ];
 
+/** `attachIncarnation` grammar: 32 lowercase hex characters (`randomBytes(16)`). */
+const ATTACH_INCARNATION_RE = /^[0-9a-f]{32}$/;
+
+/** Validate an `attachIncarnation`: null, or the 32-hex grammar. Throws on anything else. */
+export function requireAttachIncarnation(value: unknown): string | null {
+	if (value === null) return null;
+	if (typeof value !== "string" || !ATTACH_INCARNATION_RE.test(value)) {
+		throw new MetaRecordError(
+			`meta-record field "attachIncarnation" must be null or 32 lowercase hex characters (got ${describe(value)}).`,
+		);
+	}
+	return value;
+}
+
+/** Mint one arm binding value. Clock-independent: 128 random bits, never derived from time. */
+export function mintAttachIncarnation(): string {
+	return crypto.randomBytes(16).toString("hex");
+}
+
 /** Parse + fully validate untrusted JSON into a v3 MetaIdentity. Throws on any drift. */
 export function parseMetaRecordV3(json: string): MetaIdentity {
 	let raw: unknown;
@@ -514,6 +545,10 @@ export function parseMetaRecordV3(json: string): MetaIdentity {
 		transcriptPath: requireNullableString(obj.transcriptPath, "transcriptPath"),
 		createdAt: requireNonEmptyString(obj.createdAt, "createdAt"),
 		recordUpdatedAt: requireNonEmptyString(obj.recordUpdatedAt, "recordUpdatedAt"),
+		// The one key a V3 record may omit: a record nothing has touched since the field
+		// existed reads its absence as null ("no binding observed"). One schema, one reader —
+		// not a legacy alias: every serialize emits the key.
+		attachIncarnation: requireAttachIncarnation(obj.attachIncarnation === undefined ? null : obj.attachIncarnation),
 	};
 }
 
@@ -533,6 +568,7 @@ export function normalizeMetaIdentity(record: MetaIdentity): MetaIdentity {
 		transcriptPath: record.transcriptPath,
 		createdAt: record.createdAt,
 		recordUpdatedAt: record.recordUpdatedAt,
+		attachIncarnation: record.attachIncarnation,
 	};
 }
 
@@ -559,6 +595,7 @@ export function serializeMetaIdentity(identity: MetaIdentity): string {
 		transcriptPath: identity.transcriptPath,
 		createdAt: identity.createdAt,
 		recordUpdatedAt: identity.recordUpdatedAt,
+		attachIncarnation: identity.attachIncarnation,
 	};
 	return `${JSON.stringify(ordered, null, 2)}\n`;
 }
@@ -576,6 +613,13 @@ export interface MetaIdentityMintInput {
 	cwd: string;
 	model?: string | null;
 	transcriptPath?: string | null;
+	/**
+	 * The arm binding to commit with this write. ONLY the Claude Code hook passes it, and
+	 * only on an arm-capable event under the record-arm lock; `undefined` (every other
+	 * writer, every UserPromptSubmit) keeps the existing value, and a create without it is
+	 * `null`.
+	 */
+	attachIncarnation?: string;
 }
 
 /**
@@ -598,6 +642,7 @@ export function mintMetaIdentity(input: MetaIdentityMintInput, now: Date = new D
 		transcriptPath: requireNullableString(input.transcriptPath ?? null, "transcriptPath"),
 		createdAt: ts,
 		recordUpdatedAt: ts,
+		attachIncarnation: input.attachIncarnation === undefined ? null : requireAttachIncarnation(input.attachIncarnation),
 	};
 }
 
@@ -1314,9 +1359,14 @@ export function decideUpsert(
 		input.transcriptPath === undefined
 			? existing.transcriptPath
 			: requireNullableString(input.transcriptPath, "transcriptPath");
+	// The arm binding is not a merge axis: only a mint replaces it, and nothing clears it.
+	const attachIncarnation =
+		input.attachIncarnation === undefined
+			? existing.attachIncarnation
+			: requireAttachIncarnation(input.attachIncarnation);
 	return {
 		action: "attach",
-		record: { ...existing, cwd, model, transcriptPath, recordUpdatedAt: isoNow(now) },
+		record: { ...existing, cwd, model, transcriptPath, recordUpdatedAt: isoNow(now), attachIncarnation },
 	};
 }
 
@@ -1416,6 +1466,17 @@ export function defaultMetaReceiversDir(): string {
 	return path.join(piAgentDir(), "meta-receivers");
 }
 
+/**
+ * The record-arm lock directory (#147 L2 B1): a sibling of the receivers dir, so a
+ * sandboxed receivers root sandboxes it too and no new environment carrier exists. It is
+ * deliberately NOT the v2 dispatch lock dir — visible resume holds that per-gid lock across
+ * its whole launch + observation window, and the relaunched session's own arm must not wait
+ * on it. Only the Claude Code hook takes this lock; nothing else reads or writes here.
+ */
+export function defaultMetaRecordArmLocksDir(receiversDir: string = defaultMetaReceiversDir()): string {
+	return path.join(path.dirname(receiversDir), "meta-record-arm-locks");
+}
+
 // ---------------------------------------------------------------------------
 // OMP meta-root policy (#87 B1) — ADDITIVE, and only for backend `omp`.
 //
@@ -1990,6 +2051,12 @@ export interface MetaReceiverMarker {
 	/** Which arm-capable event wrote this presence (never user-prompt-submit). */
 	armProvenance: MetaReceiverArmProvenance;
 	updatedAt: string;
+	/**
+	 * A copy of the record's `attachIncarnation` this arm committed (#147 L2 B1), written only by
+	 * the Claude Code hook under the record-arm lock. `null` when the writer supplied none (every
+	 * other owner kind, a marker older than the field). Readers that predate the field ignore it.
+	 */
+	attachIncarnation: string | null;
 }
 
 /** `<receiversDir>/<gardenId>.json` — keyed by garden id (the universal address). */
@@ -2003,6 +2070,8 @@ export interface WriteMetaReceiverMarkerOptions {
 	nativeSessionId: string;
 	ownerPid: number;
 	armProvenance: MetaReceiverArmProvenance;
+	/** The record binding this arm committed; only the Claude Code hook passes it. */
+	attachIncarnation?: string;
 	/** Defaults to "claude-code-cli" — the watchPaths subscriber. */
 	ownerKind?: string;
 	receiversDir?: string;
@@ -2025,6 +2094,7 @@ export function writeMetaReceiverMarker(opts: WriteMetaReceiverMarkerOptions): s
 		ownerKind: requireNonEmptyString(opts.ownerKind ?? "claude-code-cli", "ownerKind"),
 		armProvenance: requireArmProvenance(opts.armProvenance),
 		updatedAt: isoNow(opts.now ?? new Date()),
+		attachIncarnation: opts.attachIncarnation === undefined ? null : requireAttachIncarnation(opts.attachIncarnation),
 	};
 	const tmp = `${file}.${crypto.randomBytes(4).toString("hex")}.tmp`;
 	fs.writeFileSync(tmp, `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600 });
@@ -2042,6 +2112,31 @@ export interface ReadMetaReceiverMarkerOptions {
 	verifyOwner?: boolean;
 }
 
+/**
+ * Validate receiver-marker bytes — the one validator, shared by the path reader below and by
+ * the no-follow fd reader visible resume uses (#147 L2 D3). Throws on a malformed marker;
+ * returns null for an IMPLAUSIBLE owner pid. Same rule as the sender marker, and for the same
+ * reason one layer over: an impossible owner is not a live one, so a refuted marker must never
+ * read back as an ACTIVE RECEIVER and pull the mailbox rail into delivering to a void. An
+ * absent `attachIncarnation` reads as null; a present malformed one throws.
+ */
+export function parseMetaReceiverMarker(json: string): MetaReceiverMarker | null {
+	const raw = JSON.parse(json);
+	const marker: MetaReceiverMarker = {
+		gardenId: requireGardenId(raw.gardenId),
+		backend: requireBackend(raw.backend),
+		nativeSessionId: requireNonEmptyString(raw.nativeSessionId, "nativeSessionId"),
+		ownerPid: typeof raw.ownerPid === "number" ? raw.ownerPid : Number.NaN,
+		ownerStartKey: requireNonEmptyString(raw.ownerStartKey, "ownerStartKey"),
+		ownerKind: requireNonEmptyString(raw.ownerKind, "ownerKind"),
+		armProvenance: requireArmProvenance(raw.armProvenance),
+		updatedAt: requireNonEmptyString(raw.updatedAt, "updatedAt"),
+		attachIncarnation: requireAttachIncarnation(raw.attachIncarnation === undefined ? null : raw.attachIncarnation),
+	};
+	if (!isPlausibleOwnerPid(marker.ownerPid)) return null;
+	return marker;
+}
+
 /**
  * Read the receiver presence marker for a garden id. Returns null when absent,
  * corrupt, or (under verifyOwner) the owner pid is no longer the same live process —
@@ -2057,21 +2152,8 @@ export function readMetaReceiverMarker(opts: ReadMetaReceiverMarkerOptions): Met
 	}
 	if (!file || !fs.existsSync(file)) return null;
 	try {
-		const raw = JSON.parse(fs.readFileSync(file, "utf8"));
-		const marker: MetaReceiverMarker = {
-			gardenId: requireGardenId(raw.gardenId),
-			backend: requireBackend(raw.backend),
-			nativeSessionId: requireNonEmptyString(raw.nativeSessionId, "nativeSessionId"),
-			ownerPid: typeof raw.ownerPid === "number" ? raw.ownerPid : Number.NaN,
-			ownerStartKey: requireNonEmptyString(raw.ownerStartKey, "ownerStartKey"),
-			ownerKind: requireNonEmptyString(raw.ownerKind, "ownerKind"),
-			armProvenance: requireArmProvenance(raw.armProvenance),
-			updatedAt: requireNonEmptyString(raw.updatedAt, "updatedAt"),
-		};
-		// Same rule as the sender marker, and for the same reason one layer over: an
-		// impossible owner is not a live one, so a refuted marker must never read back
-		// as an ACTIVE RECEIVER and pull the mailbox rail into delivering to a void.
-		if (!isPlausibleOwnerPid(marker.ownerPid)) return null;
+		const marker = parseMetaReceiverMarker(fs.readFileSync(file, "utf8"));
+		if (marker === null) return null;
 		if (opts.verifyOwner !== false) {
 			const liveKey = processStartKey(marker.ownerPid);
 			if (!liveKey || liveKey !== marker.ownerStartKey) return null;
@@ -2128,6 +2210,13 @@ export function removeMetaReceiverMarker(opts: RemoveMetaReceiverMarkerOptions):
 
 export interface UpsertMetaSessionOptions {
 	input: MetaIdentityMintInput;
+	/**
+	 * Refuse, BEFORE any write, unless the decision is this action. The Claude Code hook
+	 * creates a record it found absent only with `"create"`: if another writer published one
+	 * in between, the decision would silently become an unlocked ATTACH — exactly the write
+	 * the record-arm lock exists to keep out (#147 L2 B1).
+	 */
+	expectAction?: UpsertAction;
 	/** Override the store directory (defaults to {@link defaultMetaSessionsDir}). */
 	dir?: string;
 	now?: Date;
@@ -2175,12 +2264,47 @@ export function upsertMetaSession(opts: UpsertMetaSessionOptions): UpsertMetaSes
 	const target = requireNonEmptyString(opts.input.nativeSessionId, "nativeSessionId");
 	const existing = cert.records.find((record) => record.identity.nativeSessionId === target)?.identity ?? null;
 	const decision = decideUpsert(existing, opts.input, opts.now);
+	if (opts.expectAction !== undefined && decision.action !== opts.expectAction) {
+		throw new UpsertActionMismatchError(opts.expectAction, decision.action, target);
+	}
 	const file = path.join(dir, metaRecordFilename(decision.record));
 	if (decision.action === "create") publishExclusiveIdentity(file, decision.record);
 	else atomicWriteIdentity(file, decision.record);
 	return { action: decision.action, record: decision.record, dir, path: file };
 }
 
+/** The upsert refused before writing because its decision was not the expected action. */
+export class UpsertActionMismatchError extends MetaRecordError {
+	readonly expected: UpsertAction;
+	readonly actual: UpsertAction;
+	constructor(expected: UpsertAction, actual: UpsertAction, nativeSessionId: string) {
+		super(
+			`upsert expected to ${expected} the record for nativeSessionId "${nativeSessionId}" but would ${actual} ` +
+				"it; nothing was written.",
+		);
+		this.expected = expected;
+		this.actual = actual;
+	}
+}
+
+/**
+ * The certified record a native session id already has, READ ONLY — the same certification
+ * {@link upsertMetaSession} runs (a defective store throws the same refusal), with no write.
+ * The Claude Code hook learns the garden id it must lock this way, so no record write ever
+ * happens outside the record-arm lock for an existing record (#147 L2 B1).
+ */
+export function findCertifiedIdentityByNativeSessionId(
+	nativeSessionId: string,
+	dirOverride?: string,
+): MetaIdentity | null {
+	const dir = path.resolve(expandTilde(dirOverride ?? defaultMetaSessionsDir()));
+	if (!fs.existsSync(dir)) return null;
+	const cert = certifyActiveStoreDir(dir);
+	if (cert.defects.length > 0) throw new MetaRecordError(activeStoreRefusal(cert));
+	const target = requireNonEmptyString(nativeSessionId, "nativeSessionId");
+	return cert.records.find((record) => record.identity.nativeSessionId === target)?.identity ?? null;
+}
+
 /**
  * ATTACH replace primitive: tmp-file + rename so a crash never leaves a
  * half-written record (#30 crash-safety). rename(2) REPLACES an existing final

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

@@ -114,9 +114,11 @@ import {
 	FRESH_CALL_BACKENDS,
 	FRESH_CALL_CALLBACK_TOOL,
 	FRESH_CALL_DELIVERY_TOOL,
+	FRESH_CALL_PROVIDER_HINT,
 	type FreshCallBackend,
 	type FreshCallComposition,
 	type FreshCallInputRejectReason,
+	type FreshCallProviderRejectReason,
 	isSafeFreshCallModel,
 	MODEL_MAX_CHARS,
 	mintNonce,
@@ -130,6 +132,7 @@ import {
 	LaunchPreconditionError,
 	type LaunchRejectReason,
 	resolveRuntimeOnPath,
+	SCRUBBED_INHERITED_ENV,
 } from "./mux-launch.ts";
 import {
 	APPEND_FORMAT,
@@ -266,6 +269,7 @@ export type FreshCallRejectReason =
 	| CodexPreflightRejectReason
 	| CodexCallerPreflightRejectReason
 	| CodexCallerSeatRejectReason
+	| FreshCallProviderRejectReason
 	| "acp-model-not-curated"
 	| "caller-identity-unavailable"
 	| "model-empty"
@@ -347,33 +351,8 @@ export interface FreshCallReceipt extends WindowHandle {
 
 export type FreshCallResult = { ok: true; receipt: FreshCallReceipt } | { ok: false; reason: FreshCallRejectReason };
 
-/**
- * The pi identity carrier, scrubbed at the launch seam for EVERY backend (#87 Bundle C).
- *
- * `[측정]` 2026-08-30, private tmux server: a `new-window` pane inherits the tmux SERVER's
- * environment, not the caller's. A server started from a shell that exported `PI_SESSION_ID`
- * hands that value to every window it will ever open — the control run printed
- * `SID=[leaked-uuid]` in a pane the caller never touched. Nothing about the fresh call creates
- * that leak and nothing about it notices: the sibling's own MCP child would read the STALE pair
- * as its authoritative identity and call home as a citizen it is not (`mcp/entwurf-bridge/
- * src/index.ts:692-698` keeps the measured incident — a fresh cell answering with the uuidv7 it
- * found in the environment, confidently and wrong).
- *
- * `-e VAR=` sets the variable EMPTY rather than unsetting it, which tmux has no per-window form
- * for. That is sufficient and not a compromise: every reader of the carrier trims and tests
- * truthiness (`index.ts:212-217`), so empty and absent are the same answer by construction.
- *
- * It is applied to all six backends because the leak is a property of tmux, not of a vendor. A
- * scrub only on the backend whose measurement surfaced it would encode the claim that the other
- * five are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
- * authoritative when the process that owns it exported it ITSELF, and a fresh `pi` sibling does
- * exactly that after this argv has run. This is a fixed seam and deliberately NOT a general env
- * carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping power this
- * rail exists to refuse. Two more `-e` assignments ride beside the scrub: the callback pair
- * (`callback-env.ts`), launcher-computed, so the sibling's first action does not retype an
- * address out of prose.
- */
-const SCRUBBED_INHERITED_ENV = ["PI_SESSION_ID=", "PI_AGENT_ID="] as const;
+// The identity scrub every fresh window carries is `SCRUBBED_INHERITED_ENV` (mux-launch.ts), shared
+// with the resume rail because the leak it closes is a property of tmux, not of either verb.
 
 /** Launch argv: the leaf's detached-append shape, the identity scrub, optionally `-c` at the
  * resume-symmetric token position (after `-t`, before `-P -F`), the runtime, then the backend's
@@ -661,6 +640,7 @@ const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	...CODEX_PREFLIGHT_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",

package/pi-extensions/lib/mux-launch.ts

@@ -71,6 +71,35 @@ import {
  * is a separate ownership decision (docs §11), not a parameter. */
 export const PI_RUNTIME_COMMAND = "pi";
 
+/**
+ * The pi identity carrier, scrubbed at the launch seam for EVERY backend (#87 Bundle C).
+ *
+ * `[측정]` 2026-08-30, private tmux server: a `new-window` pane inherits the tmux SERVER's
+ * environment, not the caller's. A server started from a shell that exported `PI_SESSION_ID`
+ * hands that value to every window it will ever open — the control run printed
+ * `SID=[leaked-uuid]` in a pane the caller never touched. Nothing about the fresh call creates
+ * that leak and nothing about it notices: the sibling's own MCP child would read the STALE pair
+ * as its authoritative identity and call home as a citizen it is not (`mcp/entwurf-bridge/
+ * src/index.ts:692-698` keeps the measured incident — a fresh cell answering with the uuidv7 it
+ * found in the environment, confidently and wrong).
+ *
+ * `-e VAR=` sets the variable EMPTY rather than unsetting it, which tmux has no per-window form
+ * for. That is sufficient and not a compromise: every reader of the carrier trims and tests
+ * truthiness (`index.ts:212-217`), so empty and absent are the same answer by construction.
+ *
+ * It is applied to every fresh backend and to every resumed one (#147 L2) because the leak is a
+ * property of tmux, not of a vendor or a verb. A
+ * scrub only on the backend whose measurement surfaced it would encode the claim that the other
+ * five are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
+ * authoritative when the process that owns it exported it ITSELF, and a fresh `pi` sibling does
+ * exactly that after this argv has run. This is a fixed seam and deliberately NOT a general env
+ * carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping power this
+ * rail exists to refuse. Two more `-e` assignments ride beside the scrub: the callback pair
+ * (`callback-env.ts`), launcher-computed, so the sibling's first action does not retype an
+ * address out of prose.
+ */
+export const SCRUBBED_INHERITED_ENV = ["PI_SESSION_ID=", "PI_AGENT_ID="] as const;
+
 /**
  * Why a launch was refused BEFORE any window was opened. Each is a named refusal, never a
  * fallback — a caller that cannot start the official runtime must not be handed a window.

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

@@ -1,6 +1,6 @@
 /**
  * mux-resume-call — open ONE window in the caller's own tmux session at a cwd this module did
- * not choose, and hand it argv this module did not author.
+ * not choose, start the backend's FIXED runtime there, and hand it argv this module did not author.
  *
  * ── Why this is a module and not a parameter on fresh-call ──
  *
@@ -15,7 +15,15 @@
  *   visible-resume composition → resume-call → placement leaf (unchanged, carrier-free)
  *   resume-call               -X-> garden identity, records, locks, delivery
  *
- * This module never learns which citizen it is reopening. It sees a cwd and an argv tail.
+ * This module never learns which citizen it is reopening. It sees a backend, a cwd and an argv
+ * tail; the backend only selects a runtime from a closed table (#147 L2).
+ *
+ * ── Tmux only, and said so inside herdr ──
+ *
+ * This is the tmux rail. A caller inside herdr (`HERDR_ENV=1`, herdr's own marker, read for its
+ * exact value as `fresh-call-dispatch` does) is refused by name before anything else: herdr owns
+ * placement there, and an ambient `TMUX` that happens to be set would otherwise put the window in
+ * a session the operator is not looking at. There is no herdr resume rail yet and no fallback.
  *
  * ── The cwd is the whole reason this module owns its own tmux argv ──
  *
@@ -47,6 +55,7 @@ import {
 	LaunchPreconditionError,
 	type LaunchRejectReason,
 	resolveRuntimeOnPath,
+	SCRUBBED_INHERITED_ENV,
 } from "./mux-launch.ts";
 import {
 	APPEND_FORMAT,
@@ -61,15 +70,20 @@ import {
 	type WindowHandle,
 } from "./mux-placement.ts";
 
-/** The fixed runtime a resume reopens. Only pi stands a control socket up, so only pi has a
- * same-id resume at all — the backend boundary is enforced upstream by
- * `resolveResumeLaunchIdentity`, and this constant is the mux half of the same fact. */
-export const RESUME_CALL_RUNTIME = "pi";
+/** The fixed runtime each resumable backend reopens with. A closed table, not a command input: the
+ * backend boundary is enforced upstream by `resolveResumeLaunchIdentity`, and this is the mux half
+ * of the same fact. */
+export const RESUME_CALL_RUNTIME = { pi: "pi", "claude-code": "claude" } as const;
+export type ResumeCallBackend = keyof typeof RESUME_CALL_RUNTIME;
 
 /** Why a resume window could not be opened. Every value is a NAMED refusal; this module has no
  * fallback launch and no fallback directory. The cwd members come from the shared classification
  * leaf and their string values are stable contract. */
-export type ResumeCallRejectReason = PlacementRejectReason | LaunchRejectReason | TmuxCwdRejectReason;
+export type ResumeCallRejectReason =
+	| PlacementRejectReason
+	| LaunchRejectReason
+	| TmuxCwdRejectReason
+	| "herdr-resume-unsupported";
 
 /** Coordinates plus what was handed to tmux. `cwd` is the REQUESTED start directory — the same
  * kind of fact as `runtimePath`, namely what tmux was asked for, not an observation. */
@@ -81,8 +95,11 @@ export interface ResumeCallReceipt extends WindowHandle {
 export type ResumeCallResult = { ok: true; receipt: ResumeCallReceipt } | { ok: false; reason: ResumeCallRejectReason };
 
 /**
- * Launch argv: the leaf's detached-append shape plus `-c`, the runtime, then the caller's flags.
- * `--` is what keeps tmux from reading the runtime or its flags as tmux options.
+ * Launch argv: the leaf's detached-append shape, the fixed identity scrub (`SCRUBBED_INHERITED_ENV`,
+ * the same two assignments every fresh window carries), `-c`, the runtime, then the caller's flags.
+ * `--` is what keeps tmux from reading the runtime or its flags as tmux options. The scrub is not a
+ * carrier: it only empties identity a tmux server may have inherited, and a resumed Claude Code
+ * (which, unlike pi, never re-exports its own) would otherwise present a stale one to its bridge.
  */
 export function buildResumeCallArgs(
 	placement: Placement,
@@ -98,6 +115,7 @@ export function buildResumeCallArgs(
 		"new-window",
 		"-d",
 		"-a",
+		...SCRUBBED_INHERITED_ENV.flatMap((assignment) => ["-e", assignment]),
 		"-t",
 		`${placement.sessionId}:{end}`,
 		"-c",
@@ -119,15 +137,16 @@ export function buildResumeCallArgs(
  * `runtimeArgs` is passed through untouched. This module does not know what `--session` means.
  */
 export function resumeCall(
-	params: { cwd: string; runtimeArgs: readonly string[] },
+	params: { backend: ResumeCallBackend; cwd: string; runtimeArgs: readonly string[] },
 	env: NodeJS.ProcessEnv = process.env,
 ): ResumeCallResult {
+	if (env.HERDR_ENV === "1") return { ok: false, reason: "herdr-resume-unsupported" };
 	const badCwd = classifyTmuxCwd(params.cwd);
 	if (badCwd) return { ok: false, reason: badCwd };
 
 	let runtimePath: string;
 	try {
-		runtimePath = resolveRuntimeOnPath(RESUME_CALL_RUNTIME, env);
+		runtimePath = resolveRuntimeOnPath(RESUME_CALL_RUNTIME[params.backend], env);
 	} catch (err) {
 		if (err instanceof LaunchPreconditionError) return { ok: false, reason: err.reason };
 		throw err;
@@ -180,7 +199,9 @@ export const RESUME_CALL_REJECT_HINT: Record<ResumeCallRejectReason, string> = {
 	"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",
-	"runtime-unresolved": "pi is not installed on PATH",
+	"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",