@junghanacs/entwurf 0.39.0 → 0.41.0

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

@@ -1,6 +1,28 @@
 /**
- * entwurf-v2-visible-resume — stand a dormant pi citizen back up in a window the operator can
- * see, under the same garden id, and say only what was actually observed.
+ * entwurf-v2-visible-resume — stand a dormant pi or Claude Code citizen back up in a window the
+ * operator can see, under the same garden id, and say only what was actually observed.
+ *
+ * ── Two backends, one shape (#147 L2) ──
+ *
+ * Both own their transcript and re-attach to their record when the same native session reopens.
+ * What differs is the rail each one proves itself on, so the dormancy proof and the observation are
+ * per backend and nothing else is:
+ *
+ *   pi           dormant = its control socket is dead; back = that socket answers again.
+ *   claude-code  dormant = the LAST VALIDATED owner the Entwurf hook armed for this session is
+ *                proven gone: the receiver marker names an owner `classifyMarkerOwner` calls DEAD,
+ *                AND the record re-read after that verdict still carries the same non-null
+ *                `attachIncarnation` the marker copied (#147 L2 B1) — so no arm-capable attach
+ *                committed after that owner's. An absent, unreadable, mismatched, live,
+ *                inconclusive or unbound marker proves nothing and refuses. A process that holds
+ *                the session without a committed hook attach (hooks disabled, a record-arm lock
+ *                timeout, a store write failure, a launch after the re-read) is invisible to this
+ *                proof. Back = a NEW live owner, in the pane this call opened, re-armed the marker
+ *                for the same session with a fresh binding the current record also carries (same
+ *                createdAt). The old marker read again is never success.
+ *
+ * Every other backend is the leaf's named refusal. The argv is a fixed table per backend; the caller
+ * supplies only the target.
  *
  * ── Where this sits ──
  *
@@ -41,10 +63,14 @@
  *
  * ── Two receipts, never merged ──
  *
- * `launch` says tmux made a window and was asked to start pi. `observation` says whether the
- * citizen's socket came back under the same id. Neither says the resumed citizen did anything:
- * a resume runs no turn (measured — the transcript stayed byte-identical), so there is no turn
- * outcome for this module to claim.
+ * `launch` says tmux made a window and was asked to start the runtime. `observation` says whether
+ * the citizen came back under the same id (pi: its socket; Claude Code: its receiver marker).
+ * Neither says the resumed citizen did anything. This verb submits no prompt. For pi a resume ran
+ * no turn (measured 2026-08-06, pi only — the transcript stayed byte-identical); for Claude Code
+ * the runtime's own activity after resume (its SessionStart hook re-arms the doorbell, and unread
+ * mail may then wake a turn) is unmeasured, so this module claims no turn outcome either way.
+ * The socket-only description in the observation section above is the pi half; the Claude Code
+ * half reads the receiver marker and the record instead.
  */
 
 import { ACP_MODEL_NOT_CURATED_HINT, AcpModelNotCuratedError } from "./acp/model-ids.js";
@@ -58,7 +84,18 @@ import {
 	releaseLock as realReleaseLock,
 } from "./entwurf-v2-lock.ts";
 import {
+	classifyMarkerOwner,
+	type MarkerOwnerVerdict,
+	metaReceiverMarkerPath,
+	parseMetaReceiverMarker,
+	probePidExistence,
+	processStartKey,
+	readStoreRecordFile,
+} from "./meta-session.ts";
+import {
+	type ClaudeCodeLaunchIdentity,
 	type LaunchIdentity,
+	type ResumeBackend,
 	ResumeBackendUnsupportedError,
 	resolveResumeLaunchIdentity,
 } from "./resume-launch-identity.ts";
@@ -85,18 +122,23 @@ export const RESUME_OBSERVE_INTERVAL_MS = 500;
  * ACP bridge", …), and copying those causes into an enum would duplicate a truth that already
  * fails loud — the second copy is what goes stale.
  *
- * `target-not-pi` IS in here, and the line between it and those throws is worth stating: asking
- * to resume a Claude Code or agy citizen is not a defect at all. Nothing is corrupt, the record
- * is exactly right, and the operator has simply reached past a capability boundary — only pi
- * stands a control socket up, so only pi has a same-id resume. That deserves a named refusal a
- * caller can act on, not an error report about a store that is fine.
+ * `target-backend-unsupported` IS in here, and the line between it and those throws is worth
+ * stating: asking to resume a Codex or agy citizen is not a defect at all. Nothing is corrupt, the
+ * record is exactly right, and the operator has simply reached past a capability boundary — only
+ * pi and Claude Code have a same-id resume. That deserves a named refusal a caller can act on, not
+ * an error report about a store that is fine. The four `target-receiver-*` reasons are the Claude
+ * Code dormancy proof failing: nothing on disk proves the citizen is not running.
  */
 export type VisibleResumeRejectReason =
 	| "target-invalid"
-	| "target-not-pi"
+	| "target-backend-unsupported"
 	| "acp-model-not-curated"
 	| "target-locked"
 	| "target-live"
+	| "target-receiver-absent"
+	| "target-receiver-corrupt"
+	| "target-receiver-mismatch"
+	| "target-receiver-unbound"
 	| "target-indeterminate"
 	| "target-address-conflict"
 	| "launch-refused";
@@ -118,14 +160,12 @@ export type VisibleResumeLaunchOutcome =
 	| { ok: true; handle: VisibleResumeLaunchHandle }
 	| { ok: false; reason: string; hint: string };
 
-/** Fact 1: tmux created a window and was asked to start pi there. `cwd` is the REQUESTED start
- * directory (what tmux was told), the same kind of fact as `runtimePath` — not an observation of
- * where the pane landed. */
-export interface ResumeLaunchReceipt {
-	targetGardenId: string;
-	sessionFile: string;
-	handle: VisibleResumeLaunchHandle;
-}
+/** Fact 1: tmux created a window and was asked to start the citizen's runtime there. `cwd` is the
+ * REQUESTED start directory (what tmux was told), the same kind of fact as `runtimePath` — not an
+ * observation of where the pane landed. */
+export type ResumeLaunchReceipt =
+	| { backend: "pi"; targetGardenId: string; sessionFile: string; handle: VisibleResumeLaunchHandle }
+	| { backend: "claude-code"; targetGardenId: string; nativeSessionId: string; handle: VisibleResumeLaunchHandle };
 
 /** Fact 2: the citizen's control socket came back under the SAME garden id, or it did not. This
  * is the only fact in this module that says a citizen is back. */
@@ -135,8 +175,39 @@ export interface ResumeObservationReceipt {
 	waitedMs: number;
 }
 
+/** Fact 2 for Claude Code: a NEW live owner in the opened pane re-armed the receiver marker for the
+ * same native session with a fresh binding the current record carries, or that was not seen in
+ * time, or the record could not be read (a store defect, reported at once with its cause — the
+ * window stays open). The pid is the new owner's, read from the marker and joined to the pane
+ * this call opened; it is evidence, not an address. */
+export type ReceiverObservationReceipt =
+	| { kind: "receiver-armed"; ownerPid: number; waitedMs: number }
+	| { kind: "resume-unobserved"; waitedMs: number }
+	| { kind: "record-unreadable"; cause: string; waitedMs: number };
+
+/** What the receiver marker under a garden id says, read raw and judged by the shared owner rule. */
+export type ReceiverInspection =
+	| { kind: "absent" }
+	| { kind: "corrupt" }
+	| {
+			kind: "marker";
+			marker: {
+				gardenId: string;
+				backend: string;
+				nativeSessionId: string;
+				ownerPid: number;
+				ownerStartKey: string;
+				attachIncarnation: string | null;
+				/** Already parsed from the same fd; exposed for callers that must join the owner's domain
+				 * (#147 G3 retire). The resume verdict does not read them. */
+				ownerKind: string;
+				armProvenance: string;
+			};
+			owner: MarkerOwnerVerdict;
+	  };
+
 export type VisibleResumeResult =
-	| { ok: true; launch: ResumeLaunchReceipt; observation: ResumeObservationReceipt }
+	| { ok: true; launch: ResumeLaunchReceipt; observation: ResumeObservationReceipt | ReceiverObservationReceipt }
 	| { ok: false; reason: VisibleResumeRejectReason; detail: string };
 
 export interface VisibleResumeDeps {
@@ -145,8 +216,14 @@ export interface VisibleResumeDeps {
 	resolveIdentity: (gardenId: string) => LaunchIdentity;
 	inspectSocket: (gardenId: string) => Promise<TargetSocketInspection>;
 	probeSocket: (socketPath: string) => Promise<SocketLiveness>;
+	/** The Claude Code dormancy proof and observation read this; pi never does. */
+	inspectReceiver: (gardenId: string) => ReceiverInspection;
 	/** The ONLY way this module reaches tmux. The surface supplies it. */
-	launch: (input: { cwd: string; runtimeArgs: readonly string[] }) => VisibleResumeLaunchOutcome;
+	launch: (input: {
+		backend: ResumeBackend;
+		cwd: string;
+		runtimeArgs: readonly string[];
+	}) => VisibleResumeLaunchOutcome;
 	sleep: (ms: number) => Promise<void>;
 	now: () => number;
 }
@@ -163,6 +240,7 @@ export function makeVisibleResumeDeps(
 		resolveIdentity: resolveResumeLaunchIdentity,
 		inspectSocket: (gid) => inspectTargetControlSocket(gid, CONTROL_SOCKET_DIR),
 		probeSocket: (socketPath) => probeSocketLiveness(socketPath),
+		inspectReceiver: (gid) => inspectReceiverMarker(gid),
 		launch,
 		sleep: (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
 		now: () => Date.now(),
@@ -170,6 +248,50 @@ export function makeVisibleResumeDeps(
 	};
 }
 
+/**
+ * The receiver marker under `gardenId`, read RAW (no owner verification inside the reader — the
+ * path reader's `null` folds absent, corrupt and dead into one answer, and only "dead" may permit
+ * a resume) and judged by `classifyMarkerOwner`, the one place a dead verdict is produced. The
+ * bytes come from `readStoreRecordFile` — `O_NOFOLLOW` open, `fstat` kind and read on that one fd
+ * (#147 L2 D3) — so a symlink or a non-regular entry is corrupt and never followed, with no
+ * window between classifying the entry and reading it. `ENOENT` alone is absent.
+ */
+export function inspectReceiverMarker(gardenId: string, receiversDir?: string): ReceiverInspection {
+	const markerPath = metaReceiverMarkerPath(gardenId, receiversDir);
+	let bytes: string;
+	try {
+		bytes = readStoreRecordFile(markerPath);
+	} catch (err) {
+		if ((err as { code?: unknown }).code === "ENOENT") return { kind: "absent" };
+		return { kind: "corrupt" };
+	}
+	let marker: ReturnType<typeof parseMetaReceiverMarker>;
+	try {
+		marker = parseMetaReceiverMarker(bytes);
+	} catch {
+		return { kind: "corrupt" };
+	}
+	if (marker === null) return { kind: "corrupt" };
+	const owner = classifyMarkerOwner(marker.ownerStartKey, {
+		currentStartKey: processStartKey(marker.ownerPid),
+		pidExists: probePidExistence(marker.ownerPid),
+	});
+	return {
+		kind: "marker",
+		marker: {
+			gardenId: marker.gardenId,
+			backend: marker.backend,
+			nativeSessionId: marker.nativeSessionId,
+			ownerPid: marker.ownerPid,
+			ownerStartKey: marker.ownerStartKey,
+			attachIncarnation: marker.attachIncarnation,
+			ownerKind: marker.ownerKind,
+			armProvenance: marker.armProvenance,
+		},
+		owner,
+	};
+}
+
 /**
  * Reopen `targetGardenId` in a visible window.
  *
@@ -230,7 +352,7 @@ export async function visibleResume(targetGardenId: string, deps: VisibleResumeD
 			identity = deps.resolveIdentity(targetGardenId);
 		} catch (err) {
 			// #128: the recorded model is not an exact curated ACP id, so Pi would pick another row
-			// by substring. Same shape as `target-not-pi`: a named refusal matched on its FIELD.
+			// by substring. Same shape as `target-backend-unsupported`: a named refusal matched on its FIELD.
 			if (err instanceof AcpModelNotCuratedError) {
 				return {
 					ok: false,
@@ -243,13 +365,15 @@ export async function visibleResume(targetGardenId: string, deps: VisibleResumeD
 					ok: false,
 					reason: err.reason,
 					detail:
-						`${targetGardenId} is a ${err.backend} citizen; only pi citizens stand a control socket up, ` +
-						`so only they can be reopened under the same garden id`,
+						`${targetGardenId} is a ${err.backend} citizen; only pi and Claude Code citizens can be reopened ` +
+						`under the same garden id`,
 				};
 			}
 			throw err;
 		}
 
+		if (identity.backend === "claude-code") return await resumeClaudeCode(targetGardenId, identity, deps);
+
 		// Liveness preflight, still under the lock. A live citizen is addressed with
 		// `entwurf_v2 fire-and-forget`, not reopened — and refusing here is also what stops two
 		// windows existing for one garden id.
@@ -287,7 +411,7 @@ export async function visibleResume(targetGardenId: string, deps: VisibleResumeD
 			provider: identity.provider,
 			model: identity.model,
 		});
-		const launched = deps.launch({ cwd: identity.cwd, runtimeArgs });
+		const launched = deps.launch({ backend: "pi", cwd: identity.cwd, runtimeArgs });
 		if (!launched.ok) {
 			return { ok: false, reason: "launch-refused", detail: `${launched.reason} — ${launched.hint}` };
 		}
@@ -295,7 +419,7 @@ export async function visibleResume(targetGardenId: string, deps: VisibleResumeD
 		const observation = await observeSameGidSocket(targetGardenId, mapped.socketPath, deps);
 		return {
 			ok: true,
-			launch: { targetGardenId, sessionFile: identity.sessionFile, handle: launched.handle },
+			launch: { backend: "pi", targetGardenId, sessionFile: identity.sessionFile, handle: launched.handle },
 			observation,
 		};
 	} finally {
@@ -303,6 +427,186 @@ export async function visibleResume(targetGardenId: string, deps: VisibleResumeD
 	}
 }
 
+/**
+ * The Claude Code half, still under the caller's lock. Dormancy needs a DEAD owner verdict on the
+ * receiver marker AND the binding: the record re-read AFTER that verdict must still name the same
+ * session and createdAt, and carry the same non-null `attachIncarnation` the marker copied. An
+ * absent marker (never armed, or retired when its process switched session), an unreadable one,
+ * one that names another session, a live owner, an inconclusive one and an unbound one each refuse
+ * by name, with no window. The re-read catches every attach whose atomic record write committed
+ * before it; a launch or attach that begins after it is not predicted. The launch uses the
+ * re-read record (its cwd), never the first read. The marker and the record are never removed or
+ * rewritten here — they are evidence, not something this verb may clear.
+ */
+async function resumeClaudeCode(
+	targetGardenId: string,
+	identity: ClaudeCodeLaunchIdentity,
+	deps: VisibleResumeDeps,
+): Promise<VisibleResumeResult> {
+	const before = deps.inspectReceiver(targetGardenId);
+	if (before.kind === "absent") {
+		return {
+			ok: false,
+			reason: "target-receiver-absent",
+			detail: `no receiver marker names ${targetGardenId}, so nothing proves its Claude Code process is gone`,
+		};
+	}
+	if (before.kind === "corrupt") {
+		return {
+			ok: false,
+			reason: "target-receiver-corrupt",
+			detail: `the receiver marker for ${targetGardenId} is not a readable regular marker, so its owner cannot be judged`,
+		};
+	}
+	const marker = before.marker;
+	if (
+		marker.gardenId !== targetGardenId ||
+		marker.backend !== "claude-code" ||
+		marker.nativeSessionId !== identity.nativeSessionId
+	) {
+		return {
+			ok: false,
+			reason: "target-receiver-mismatch",
+			detail:
+				`the receiver marker for ${targetGardenId} names ${marker.backend}/${marker.nativeSessionId}, not the ` +
+				`record's claude-code/${identity.nativeSessionId}`,
+		};
+	}
+	if (before.owner === "live") {
+		return {
+			ok: false,
+			reason: "target-live",
+			detail: `${targetGardenId}'s Claude Code process (pid ${marker.ownerPid}) is still running — send to it with entwurf_v2 fire-and-forget instead`,
+		};
+	}
+	if (before.owner !== "dead") {
+		return {
+			ok: false,
+			reason: "target-indeterminate",
+			detail:
+				`the receiver marker's owner (pid ${marker.ownerPid}) for ${targetGardenId} could not be proven gone, ` +
+				`and resuming a session that is still open would put two processes on one transcript`,
+		};
+	}
+
+	// The binding, read AFTER the dead verdict. A store or record defect here throws, exactly as
+	// the first read does: no window exists yet.
+	const current = deps.resolveIdentity(targetGardenId);
+	if (
+		current.backend !== "claude-code" ||
+		current.nativeSessionId !== identity.nativeSessionId ||
+		current.createdAt !== identity.createdAt
+	) {
+		return {
+			ok: false,
+			reason: "target-receiver-unbound",
+			detail: `the record under ${targetGardenId} changed between the two reads, so the dead marker cannot be bound to it`,
+		};
+	}
+	if (current.attachIncarnation === null || marker.attachIncarnation === null) {
+		return {
+			ok: false,
+			reason: "target-receiver-unbound",
+			detail:
+				`no arm binding was observed for ${targetGardenId} (record ${current.attachIncarnation === null ? "has none" : "has one"}, ` +
+				`marker ${marker.attachIncarnation === null ? "has none" : "has one"}), so the dead owner is not proven to be the last attach`,
+		};
+	}
+	if (current.attachIncarnation !== marker.attachIncarnation) {
+		return {
+			ok: false,
+			reason: "target-receiver-unbound",
+			detail:
+				`the record of ${targetGardenId} carries a later arm binding than its receiver marker — an attach committed ` +
+				`after the dead owner's, and its process is not proven gone`,
+		};
+	}
+
+	const launched = deps.launch({
+		backend: "claude-code",
+		cwd: current.cwd,
+		runtimeArgs: ["--resume", current.nativeSessionId],
+	});
+	if (!launched.ok) {
+		return { ok: false, reason: "launch-refused", detail: `${launched.reason} — ${launched.hint}` };
+	}
+	const observation = await observeReceiverReattached(
+		targetGardenId,
+		current,
+		{ ownerPid: marker.ownerPid, ownerStartKey: marker.ownerStartKey, attachIncarnation: current.attachIncarnation },
+		launched.handle.panePid,
+		deps,
+	);
+	return {
+		ok: true,
+		launch: {
+			backend: "claude-code",
+			targetGardenId,
+			nativeSessionId: current.nativeSessionId,
+			handle: launched.handle,
+		},
+		observation,
+	};
+}
+
+/**
+ * ONE bounded operation, the Claude Code twin of `observeSameGidSocket`: wait for a NEW live owner
+ * — in the pane this call opened (`panePid`), a join, not an address — to re-arm this garden id's
+ * receiver marker for the same native session with a fresh binding the current record carries
+ * (same createdAt). The dead marker read again is never success: the owner must differ from the one
+ * the dormancy proof judged dead, and the binding from the one it bound. A marker armed by some
+ * other process is simply not-yet, and ends as `resume-unobserved`. A record or store defect is not
+ * a startup state: it stops the wait at once as `record-unreadable`, with its cause.
+ */
+export async function observeReceiverReattached(
+	targetGardenId: string,
+	identity: ClaudeCodeLaunchIdentity,
+	previous: { ownerPid: number; ownerStartKey: string; attachIncarnation: string },
+	panePid: string,
+	deps: Pick<VisibleResumeDeps, "inspectReceiver" | "resolveIdentity" | "sleep" | "now">,
+	timeoutMs: number = RESUME_OBSERVE_TIMEOUT_MS,
+	intervalMs: number = RESUME_OBSERVE_INTERVAL_MS,
+): Promise<ReceiverObservationReceipt> {
+	const started = deps.now();
+	for (;;) {
+		const seen = deps.inspectReceiver(targetGardenId);
+		if (
+			seen.kind === "marker" &&
+			seen.owner === "live" &&
+			seen.marker.gardenId === targetGardenId &&
+			seen.marker.backend === "claude-code" &&
+			seen.marker.nativeSessionId === identity.nativeSessionId &&
+			String(seen.marker.ownerPid) === panePid &&
+			(seen.marker.ownerPid !== previous.ownerPid || seen.marker.ownerStartKey !== previous.ownerStartKey) &&
+			seen.marker.attachIncarnation !== null &&
+			seen.marker.attachIncarnation !== previous.attachIncarnation
+		) {
+			let current: LaunchIdentity;
+			try {
+				current = deps.resolveIdentity(targetGardenId);
+			} catch (err) {
+				return {
+					kind: "record-unreadable",
+					cause: err instanceof Error ? err.message : String(err),
+					waitedMs: deps.now() - started,
+				};
+			}
+			if (
+				current.backend === "claude-code" &&
+				current.nativeSessionId === identity.nativeSessionId &&
+				current.createdAt === identity.createdAt &&
+				current.attachIncarnation === seen.marker.attachIncarnation
+			) {
+				return { kind: "receiver-armed", ownerPid: seen.marker.ownerPid, waitedMs: deps.now() - started };
+			}
+		}
+		if (deps.now() - started >= timeoutMs) {
+			return { kind: "resume-unobserved", waitedMs: deps.now() - started };
+		}
+		await deps.sleep(intervalMs);
+	}
+}
+
 /**
  * ONE bounded operation: wait for the SAME garden id's control socket to answer. Alive is the
  * only early exit — an inspection that comes back absent, corrupt or inconclusive during startup
@@ -331,11 +635,20 @@ export async function observeSameGidSocket(
 
 const REJECT_HINT: Record<VisibleResumeRejectReason, string> = {
 	"target-invalid": "no citizen has that id; discover targets with entwurf_peers",
-	"target-not-pi": "that citizen's backend has no same-id resume — reach it with entwurf_v2, or open a fresh sibling",
+	"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",
 	"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 socket probe could not prove the citizen is dormant, so nothing was started",
+	"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",
 };
@@ -349,7 +662,10 @@ const REJECT_HINT: Record<VisibleResumeRejectReason, string> = {
  * who sees "window opened" and "socket alive" as one sentence has been told the resume worked;
  * a reader who sees them as two facts can tell which one is missing when only one is there.
  */
-export function renderVisibleResume(result: VisibleResumeResult): { text: string; isError: boolean } {
+export function renderVisibleResume(
+	result: VisibleResumeResult,
+	attribution: { actor: string | null } = { actor: null },
+): { text: string; isError: boolean } {
 	if (!result.ok) {
 		return {
 			text:
@@ -359,23 +675,61 @@ export function renderVisibleResume(result: VisibleResumeResult): { text: string
 		};
 	}
 	const h = result.launch.handle;
-	const observed = result.observation.kind === "socket-alive";
+	// Who asked is recorded, and it is not authority: the verb decides from the target's record and
+	// live rail facts alone, whoever the caller is.
+	const actor =
+		attribution.actor === null
+			? `  actor:    unattributed (the caller has no record-backed garden identity)\n`
+			: `  actor:    ${attribution.actor} (record-backed caller; attribution, not authority)\n`;
+	const window =
+		`  runtime:  ${h.runtimePath} (requested start cwd ${h.cwd})\n` +
+		`  window:   ${h.windowId} (index ${h.windowIndex}) in session ${h.sessionId}\n` +
+		`  pane:     ${h.paneId} pid ${h.panePid}\n`;
+	if (result.launch.backend === "claude-code") {
+		const observation = result.observation as ReceiverObservationReceipt;
+		return {
+			text:
+				`[entwurf resume call ↻]\n` +
+				`  target:   ${result.launch.targetGardenId}\n` +
+				`  backend:  claude-code\n` +
+				`  session:  ${result.launch.nativeSessionId}\n` +
+				window +
+				actor +
+				`\n` +
+				`LAUNCH receipt: tmux created that window and was asked to start claude --resume on the session above.\n` +
+				(observation.kind === "receiver-armed"
+					? `OBSERVATION receipt: receiver-armed — a NEW live Claude Code process in the window this call opened ` +
+						`(pid ${observation.ownerPid}) re-armed the receiver marker of ${result.launch.targetGardenId} for the ` +
+						`same session after ${observation.waitedMs}ms, with a fresh arm binding the record also carries ` +
+						`(same createdAt). entwurf_v2 fire-and-forget now reaches its mailbox. This call submitted no ` +
+						`prompt; the runtime's own activity after resume (e.g. a doorbell on unread mail) is unmeasured.`
+					: observation.kind === "record-unreadable"
+						? `OBSERVATION receipt: record-unreadable — the record of ${result.launch.targetGardenId} could not be ` +
+							`read after ${observation.waitedMs}ms: ${observation.cause}. The window is open and visible; the ` +
+							`lock was released, nothing was retried, and nothing was killed.`
+						: `OBSERVATION receipt: resume-unobserved — no new live receiver marker from the window this call ` +
+							`opened, bound to the record, appeared within ${observation.waitedMs}ms. The window is open and ` +
+							`visible; read it directly. The lock was released, nothing was retried, and nothing was killed.`),
+			isError: false,
+		};
+	}
+	const observation = result.observation as ResumeObservationReceipt;
+	const observed = observation.kind === "socket-alive";
 	return {
 		text:
 			`[entwurf resume call ↻]\n` +
 			`  target:   ${result.launch.targetGardenId}\n` +
 			`  session:  ${result.launch.sessionFile}\n` +
-			`  runtime:  ${h.runtimePath} (requested start cwd ${h.cwd})\n` +
-			`  window:   ${h.windowId} (index ${h.windowIndex}) in session ${h.sessionId}\n` +
-			`  pane:     ${h.paneId} pid ${h.panePid}\n` +
+			window +
+			actor +
 			`\n` +
 			`LAUNCH receipt: tmux created that window and was asked to start pi on the transcript above.\n` +
 			(observed
 				? `OBSERVATION receipt: the control socket for ${result.launch.targetGardenId} answered after ` +
-					`${result.observation.waitedMs}ms — that citizen is addressable again, and entwurf_v2 fire-and-forget ` +
+					`${observation.waitedMs}ms — that citizen is addressable again, and entwurf_v2 fire-and-forget ` +
 					`now reaches it. No turn was run by this call.`
 				: `OBSERVATION receipt: resume-unobserved — the control socket did not answer within ` +
-					`${result.observation.waitedMs}ms. The window is open and visible; read it directly. The lock was ` +
+					`${observation.waitedMs}ms. The window is open and visible; read it directly. The lock was ` +
 					`released, nothing was retried, and nothing was killed.`),
 		isError: false,
 	};

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

@@ -526,6 +526,21 @@ export type FreshCallInputRejectReason =
 	| "task-empty"
 	| "task-too-long";
 
+/** #76: the provider a Pi-dialect model string NAMES, refused at the dispatch root before either
+ * rail is asked anything (`fresh-call-dispatch.ts` decides; the words live here so both rails, one
+ * of which admits no other shared module, answer with the same sentence). */
+export type FreshCallProviderRejectReason = "model-openrouter-forbidden" | "pi-model-not-provider-qualified";
+
+/** No model list on purpose: a hand-kept list of "good" ids would be a second catalog that rots
+ * on the next model version. The repair is to name a provider, and both sentences say what the
+ * refusal does NOT prove. */
+export const FRESH_CALL_PROVIDER_HINT: Record<FreshCallProviderRejectReason, string> = {
+	"model-openrouter-forbidden":
+		"OpenRouter is not a sibling rail — name a subscription or direct provider instead. This refuses the provider name written in the request (in any letter case); it does not inspect which endpoint a differently named provider resolves to",
+	"pi-model-not-provider-qualified":
+		"a pi model is `<provider>/<model id>` — a bare alias resolves to whichever row Pi's catalog prefers, which is not a provider you chose. `entwurf_peers` shows the model each running citizen recorded; that is a record fact, not proof of the endpoint that bills it",
+};
+
 export interface FreshCallInputs {
 	readonly callerGardenId: string;
 	readonly model: string;