@junghanacs/entwurf 0.17.2 → 0.18.1

package/pi-extensions/lib/entwurf-peer-observe.ts

@@ -0,0 +1,77 @@
+/**
+ * entwurf-peer-observe — the IO half of the two OBSERVED peer facts (#101).
+ *
+ * `entwurf_peers` used to answer a claude-code citizen with `liveness=unsupported` and
+ * nothing else, because the control-socket probe genuinely does not apply to a self-fetch
+ * backend. Two same-cwd rows — one a live conversation, one an abandoned startup session
+ * whose transcript was never written — were therefore byte-identical in the listing, and
+ * a caller picking "the newest record in this cwd" (the natural heuristic, and the one the
+ * surface encourages) picked the phantom as often as the real one. Both halves of the
+ * distinction were already on disk; nothing read them.
+ *
+ * FACTS, NOT VERBS. `receiver` and `transcript` say what was found, never what to do
+ * about it: no `sendable`, no `deliverable`, no transport. The listing stays a listing —
+ * dispatch still computes routing at call time from the same underlying markers.
+ *
+ * ONE MEASUREMENT, TWO WORDS. `receiver` is derived from the SAME
+ * `resolveMailboxReceiverFacts` composition the v2 dispatch seam and `entwurf_self` use.
+ * The surfaces are allowed to phrase it differently — a listing wants an enum, a reject
+ * wants a sentence — but they may not disagree, so the enum is a projection of that atom
+ * rather than a second opinion about the same markers.
+ */
+
+import * as fs from "node:fs";
+import { resolveMailboxReceiverFacts } from "./entwurf-deliverability.ts";
+import type { PeerObservations, ReceiverObservation, TranscriptObservation } from "./entwurf-facts.ts";
+import {
+	type MetaBackend,
+	type MetaIdentity,
+	metaCapabilityFor,
+	metaReceiverMarkerPath,
+	readMetaReceiverMarker,
+	readMetaSenderMarker,
+	requireBackend,
+} from "./meta-session.ts";
+
+/**
+ * The mailbox receiver axis for one citizen.
+ *
+ * `n/a` is not a failure: a backend with no mailbox (pi's control socket, antigravity's
+ * native push) has no receiver marker to be right or wrong about, and printing `none`
+ * there would invent a missing thing. The `inactive` / `none` split is what a reader
+ * needs to tell "a watch was armed and is no longer valid" from "no watch was ever
+ * armed here", so it is taken from the marker FILE's existence rather than from the
+ * reader's null — the reader folds absent, corrupt and dead-owner into one null.
+ */
+function observeReceiver(identity: MetaIdentity): ReceiverObservation {
+	if (metaCapabilityFor(identity.backend).wakeMode !== "self-fetch") return "n/a";
+	const facts = resolveMailboxReceiverFacts(identity, {
+		readReceiverMarker: (gardenId: string) => readMetaReceiverMarker({ gardenId }),
+		readSenderMarker: (backend: string, ownerPid: number) =>
+			readMetaSenderMarker({ backend: requireBackend(backend) as MetaBackend, ownerPid }),
+	});
+	if (facts.ownerAlive && facts.watchArmed) return "active";
+	return fs.existsSync(metaReceiverMarkerPath(identity.gardenId)) ? "inactive" : "none";
+}
+
+/**
+ * Does the recorded transcript exist? A record is minted at SessionStart, but a harness
+ * that writes its transcript lazily (Claude Code writes on the first turn) leaves a
+ * citizen with no conversation behind it until someone actually says something. The PATH
+ * stays private — only its existence crosses to the listing.
+ */
+function observeTranscript(identity: MetaIdentity): TranscriptObservation {
+	try {
+		// A record with no recorded transcript path has nothing to stat — that is the same
+		// observable state as a path that is not there, and neither is an `exists` claim.
+		return identity.transcriptPath && fs.existsSync(identity.transcriptPath) ? "exists" : "absent";
+	} catch {
+		// A transcript we cannot stat is not a transcript we can claim exists.
+		return "absent";
+	}
+}
+
+/** The production observer: both axes, measured for one citizen. */
+export function observePeerFacts(identity: MetaIdentity): PeerObservations {
+	return { receiver: observeReceiver(identity), transcript: observeTranscript(identity) };
+}

package/pi-extensions/lib/entwurf-peers-render.ts

@@ -39,9 +39,20 @@ export interface EntwurfPeersRender {
 	payload: EntwurfPeersPayload;
 }
 
+// `receiver` and `transcript` are OBSERVED facts, not routing (#101): they say what was
+// found on disk for this citizen, and a caller still asks entwurf_v2 what may be done
+// about it. They earn a column because for every claude-code row `liveness` reads
+// `unsupported` — the socket probe does not apply — so two rows in one cwd, a live
+// conversation and an abandoned startup session whose transcript was never written, used to
+// be indistinguishable here. `receiver=active|inactive|none|n/a` is a projection of the
+// same measurement dispatch uses; `transcript=exists|absent` is the record's transcript,
+// existence only, never the path.
 function renderPeerLine(p: PeerFact): string {
 	const model = p.model ?? "(unknown)";
-	return `- ${p.gardenId}  backend=${p.backend}  liveness=${p.liveness}  cwd=${p.cwd}  model=${model}`;
+	return (
+		`- ${p.gardenId}  backend=${p.backend}  liveness=${p.liveness}  receiver=${p.receiver}  ` +
+		`transcript=${p.transcript}  cwd=${p.cwd}  model=${model}`
+	);
 }
 
 function renderDiagnosticLine(d: EntwurfDiagnostic): string {

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

@@ -128,13 +128,24 @@ export type ExecutionPlan =
 // claim so 5c's at-most-once re-resolve runs under the same nonce) and null for the
 // lock-free meta-mailbox path (？7).
 //
-// A reject's optional machine-readable diagnostic. Only `target-locked` carries one:
-// the `LockConflict` (holder pid/host/createdAt, lockPath, human detail) the lock
-// primitive produced on contention. It rides ALONGSIDE the receipt — the receipt
-// schema is unchanged; 5d's surface renders it onto the reject. (B3: without this the
-// holder evidence was dropped at the decider boundary, so a PID-reuse permanent lock
-// could not be observed/cleared — F2-P2 "관측 가능해야 수용".)
-export type RejectDiagnostic = { kind: "target-locked"; conflict: LockConflict };
+// A reject's optional machine-readable diagnostic, riding ALONGSIDE the receipt — the
+// receipt schema is unchanged and 5d's surface renders the diagnostic onto the reject.
+// Two kinds, both here for the same reason: the evidence that decided the reject was
+// produced one layer down and would otherwise be dropped at this boundary, leaving the
+// caller a verdict with no way to see or clear its cause (F2-P2 "관측 가능해야 수용").
+//
+//   target-locked         the `LockConflict` (holder pid/host/createdAt, lockPath, human
+//                         detail) the lock primitive produced on contention. B3: without
+//                         it a PID-reuse permanent lock could not be observed/cleared.
+//   mailbox-undeliverable WHICH receiver axis failed, in the deliverability predicate's own
+//                         words — no backing record vs. a dead owner vs. a watch that is no
+//                         longer armed are three different situations with three different
+//                         fixes, and the bare `mailbox-undeliverable` reason told a caller
+//                         none of them (#101 갭 C). The predicate already computes the
+//                         sentence; this carries it instead of discarding it.
+export type RejectDiagnostic =
+	| { kind: "target-locked"; conflict: LockConflict }
+	| { kind: "mailbox-undeliverable"; reason: string };
 
 export type DispatchDecision =
 	| { kind: "reject"; receipt: RejectReceipt; diagnostic?: RejectDiagnostic }
@@ -327,7 +338,14 @@ export async function decideDispatch(input: DispatchInput, deps: DispatchDecider
 		// fail-closed (SE-2 2d-3). resolveDispatch then routes intent × deliverable.
 		const deliverability = await deps.mailboxDeliverabilityFor(identity);
 		const receipt = resolveDispatch(input.intent, "unsupported", deliverability.deliverable);
-		if (!receipt.ok) return reject(receipt);
+		// The predicate's reason travels with the reject (#101 갭 C). It is attached only when
+		// undeliverability is what produced the reject — an intent-shaped refusal on a
+		// DELIVERABLE target must not be dressed up as a receiver problem.
+		if (!receipt.ok) {
+			return deliverability.deliverable
+				? reject(receipt)
+				: reject(receipt, { kind: "mailbox-undeliverable", reason: deliverability.reason });
+		}
 		// the only allow cell here is fire-and-forget → meta-mailbox send.
 		const plan: ExecutionPlan = {
 			transport: "meta-mailbox",

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

@@ -39,7 +39,7 @@ import {
 import {
 	type MailboxDeliverabilityResult,
 	mailboxConversationalDeliverable,
-	receiverMarkerMatchesIdentity,
+	resolveMailboxReceiverFacts,
 } from "./entwurf-deliverability.ts";
 import { isOutOfSocketDomainGardenIdConflict } from "./entwurf-facts.ts";
 import { isLivenessSupported } from "./entwurf-v2-contract.ts";
@@ -75,10 +75,13 @@ import {
 	enqueueMetaMessage,
 	type MetaIdentity,
 	type MetaReceiverMarker,
+	type MetaSenderMarker,
 	metaCapabilityFor,
 	metaRecordExistsByGardenId,
 	readAddressableMetaIdentity,
 	readMetaReceiverMarker,
+	readMetaSenderMarker,
+	requireBackend,
 } from "./meta-session.ts";
 import {
 	type NativePushAdapter,
@@ -111,6 +114,10 @@ export interface ProductionEntwurfV2Seams {
 	 * SE-2 2d-3 active-receiver source; the factory's `mailboxDeliverabilityFor` closure verifies
 	 * its identity match. */
 	readReceiverMarker: (gardenId: string) => MetaReceiverMarker | null;
+	/** Read the sender marker keyed to a receiver's owner pid — the "which garden does this
+	 * process serve NOW?" fact the #101 watch-owner join reads. Null = absent / dead owner /
+	 * corrupt, which the join treats as a retired watch inside its scope. */
+	readSenderMarker: (backend: string, ownerPid: number) => MetaSenderMarker | null;
 	/** Record-side lstat of the EXACT target socket path (no connect) for the pre-probe conflict. */
 	inspectPath: (socketPath: string) => Promise<TargetSocketInspection>;
 	acquireLock: (gid: string, deps: { dir?: string }) => AcquireLockResult;
@@ -183,6 +190,9 @@ export function makeProductionEntwurfV2Deps(opts: ProductionEntwurfV2Opts): Entw
 		metaRecordExists: s.metaRecordExists ?? metaRecordExistsByGardenId,
 		readIdentity: s.readIdentity ?? readAddressableMetaIdentity,
 		readReceiverMarker: s.readReceiverMarker ?? ((gid: string) => readMetaReceiverMarker({ gardenId: gid })),
+		readSenderMarker:
+			s.readSenderMarker ??
+			((backend: string, ownerPid: number) => readMetaSenderMarker({ backend: requireBackend(backend), ownerPid })),
 		inspectPath: s.inspectPath ?? inspectControlSocketPath,
 		acquireLock: s.acquireLock ?? realAcquireLock,
 		releaseLock: s.releaseLock ?? realReleaseLock,
@@ -207,22 +217,32 @@ export function makeProductionEntwurfV2Deps(opts: ProductionEntwurfV2Opts): Entw
 	});
 
 	// ── ONE deliverability seam (SE-2 2d-3): wake-mode capability AND a live active-
-	// receiver (a presence marker that matches THIS identity). The SAME closure is injected
-	// into the decider AND the dead-fallback, so a direct send and a re-resolved fallback
-	// send can never drift to different deliverability verdicts. recordBacked is true by
-	// construction — resolveTarget already proved the record exists before any unsupported-
-	// backend mailbox route, and the closure is only consulted on that route. A null /
-	// dead-owner / identity-mismatched marker is fail-closed to inactive (SE-2): a reply to a
-	// terminated self-fetch citizen is rejected, not enqueued as mailbox garbage. ──────────
+	// receiver. The SAME closure is injected into the decider AND the dead-fallback, so a
+	// direct send and a re-resolved fallback send can never drift to different deliverability
+	// verdicts. recordBacked is true by construction — resolveTarget already proved the record
+	// exists before any unsupported-backend mailbox route, and the closure is only consulted on
+	// that route. A null / dead-owner / identity-mismatched marker is fail-closed to inactive
+	// (SE-2): a reply to a terminated self-fetch citizen is rejected, not enqueued as mailbox
+	// garbage.
+	//
+	// The two receiver facts come from the SHARED composition (#101 결함 B), never from one
+	// value copied into both slots. `ownerAlive` is the marker↔identity match on a live owner;
+	// `watchArmed` is the separate measurement that this owner is STILL serving this garden.
+	// They were the same expression until a Claude session switch inside one pid left a retired
+	// garden's marker reading as an armed doorbell and a real message rotted unread in its
+	// mailbox. `entwurf_self` calls the same composition, so a citizen's own replyability can
+	// never disagree with what dispatch decided about it. ──────────
 	const mailboxDeliverabilityFor = (identity: MetaIdentity): MailboxDeliverabilityResult => {
 		const wakeMode = metaCapabilityFor(identity.backend).wakeMode;
-		const marker = io.readReceiverMarker(identity.gardenId);
-		const matched = receiverMarkerMatchesIdentity(marker, identity);
+		const { ownerAlive, watchArmed } = resolveMailboxReceiverFacts(identity, {
+			readReceiverMarker: io.readReceiverMarker,
+			readSenderMarker: io.readSenderMarker,
+		});
 		return mailboxConversationalDeliverable({
 			wakeMode,
 			recordBacked: true,
-			ownerAlive: matched,
-			watchArmed: matched,
+			ownerAlive,
+			watchArmed,
 		});
 	};
 

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

@@ -138,6 +138,12 @@ export function renderEntwurfV2Result(result: EntwurfV2RunResult): EntwurfV2Surf
 					`\n  ${c.detail}` +
 					(c.holder ? `\n  holder: pid ${c.holder.pid} on ${c.holder.hostname} since ${c.holder.createdAt}` : "");
 			}
+			// #101 갭 C: name WHICH receiver axis failed. "mailbox-undeliverable" alone sent a
+			// caller looking for a dead session when the session was alive and had simply
+			// switched to another garden — the predicate knew that and the surface threw it away.
+			if (result.diagnostic?.kind === "mailbox-undeliverable") {
+				text += `\n  mailbox-undeliverable: ${result.diagnostic.reason}`;
+			}
 			return { text, isError: true };
 		}
 		case "executed": {

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

@@ -2017,6 +2017,50 @@ export function readMetaReceiverMarker(opts: ReadMetaReceiverMarkerOptions): Met
 	}
 }
 
+export interface RemoveMetaReceiverMarkerOptions {
+	gardenId: string;
+	/** Only remove a marker this pid owns — a retirement must never reach another process's watch. */
+	ownerPid: number;
+	receiversDir?: string;
+}
+
+/**
+ * Retire a receiver presence marker THIS owner pid wrote (#101 결함 A).
+ *
+ * A native process that switches sessions in place — an in-session `/resume` or `/clear`
+ * fires a second SessionStart inside the same pid under a new native session id — leaves
+ * the previous garden's marker behind, naming a live owner whose watch is gone. Measured
+ * on oracle 2026-09-04: one pid (143742) held two gardens' markers four seconds apart, and
+ * mail sent to the retired one sat unread.
+ *
+ * ONLY THE MARKER. The meta-record stays: records are identity, and deleting one
+ * outside `meta-bridge-fresh-cut` would fight store certification (Hard Rule 7/8).
+ * A retired citizen keeps its record, its transcript and its listing — it loses only
+ * the claim that a doorbell is armed for it, which is exactly the claim that stopped
+ * being true.
+ *
+ * Fail-closed the other way too: the marker is read back first and removed ONLY when its
+ * `ownerPid` field equals the one passed here — pid equality, which is what a caller can
+ * actually check; it does not prove the same PROCESS wrote it (a reused pid compares equal),
+ * and the reader-side start-key guard is where that finer distinction lives. It is enough for
+ * the rule this serves: a hook never retires a watch some other pid is holding. Returns whether a marker was actually removed. Never throws — a retirement
+ * that cannot happen is a log line, not a broken session start.
+ */
+export function removeMetaReceiverMarker(opts: RemoveMetaReceiverMarkerOptions): boolean {
+	try {
+		const receiversDir = opts.receiversDir ?? defaultMetaReceiversDir();
+		const file = metaReceiverMarkerPath(opts.gardenId, receiversDir);
+		// verifyOwner:false — the point is the OWNERSHIP field, not the owner's liveness;
+		// a marker whose owner already died is still this pid's to clean up when it names it.
+		const marker = readMetaReceiverMarker({ markerPath: file, verifyOwner: false });
+		if (!marker || marker.ownerPid !== opts.ownerPid) return false;
+		fs.unlinkSync(file);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 export interface UpsertMetaSessionOptions {
 	input: MetaIdentityMintInput;
 	/** Override the store directory (defaults to {@link defaultMetaSessionsDir}). */

package/pi-extensions/meta-bridge-hook.ts

@@ -28,6 +28,20 @@
  * a UserPromptSubmit fire does a degraded RECORD backfill (upsert) but cannot
  * re-arm the idle watch — the record's address is restored, the wake is not.
  *
+ * SESSION SWITCH (#101). One Claude process serves one session at a time, but it can
+ * change which. Measured on oracle 2026-09-04 (raw lab S1-S6, Claude Code 2.1.260): a bare
+ * `claude` mints a NEW session (`source=startup`), and an in-session `/resume` or `/clear`
+ * then fires a SECOND SessionStart under the SAME pid for a DIFFERENT native id
+ * (`source=resume` / `source=clear`). The first garden is left behind — in the #101 field
+ * case its transcript was never written at all — while its receiver marker still names a
+ * LIVE owner, so a sender reads an armed doorbell nobody holds. This hook therefore reads
+ * the sender marker BEFORE overwriting it and retires the previous garden's receiver marker
+ * (marker only — records are identity and are never deleted here; and only a marker this
+ * pid owns). Compaction (`source=compact`) re-fires SessionStart for the SAME native id, so
+ * the same rule retires nothing there — measured, not assumed. The envelope's `source` is
+ * logged beside all of it and decides nothing: the switch is settled by what is on disk,
+ * which holds on every host and vendor version.
+ *
  * LAUNCH: never invoked directly by Claude. `hooks.json` declares the EXEC form
  * (`command` = `<plugin-root>/scripts/hook-launch.sh`, `args` = [node, this file]),
  * and the launcher `exec`s that argv — so this process inherits the launcher's pid
@@ -51,6 +65,8 @@ import {
 	defaultMetaSessionsDir,
 	isPlausibleOwnerPid,
 	type MetaReceiverArmProvenance,
+	readMetaSenderMarker,
+	removeMetaReceiverMarker,
 	upsertMetaSession,
 	writeMetaReceiverMarker,
 	writeMetaSenderMarker,
@@ -191,6 +207,13 @@ function main(): void {
 				? env.model_id
 				: undefined;
 	const eventName = typeof env.hook_event_name === "string" ? env.hook_event_name : "SessionStart";
+	// `source` (startup | resume | clear | compact) is Claude's own word for WHY this
+	// SessionStart fired. It is logged on every line below and decides nothing: a session
+	// switch is settled by what is on disk (the sender marker's garden), which is true on
+	// every host and every vendor version. Logging it is how this host finally gets a
+	// receipt for the envelope order the #101 diagnosis could only read from vendor docs —
+	// and the raw lab (scripts/raw-claude-session-switch) reads these lines, not a guess.
+	const source = typeof env.source === "string" && env.source.length > 0 ? env.source : "(unset)";
 
 	if (!sessionId || !transcriptPath) {
 		// A degraded envelope: cannot mint an honest reference record. Log + no-op
@@ -213,7 +236,10 @@ function main(): void {
 			input: { backend: "claude-code", nativeSessionId: sessionId, transcriptPath, cwd, model },
 		});
 		gardenId = result.record.gardenId;
-		logLine("INFO", `${result.action} record ${path.basename(result.path)} (event=${eventName}, native=${sessionId})`);
+		logLine(
+			"INFO",
+			`${result.action} record ${path.basename(result.path)} (event=${eventName}, source=${source}, native=${sessionId})`,
+		);
 	} catch (err) {
 		// Best-effort: a broken record store must surface via the doctor, not by
 		// breaking the user's session open. Log and continue with no arm. This is
@@ -241,9 +267,52 @@ function main(): void {
 	// an env var. Missing launcher provenance or an implausible parent yields no marker.
 	const ownerPid = resolveMetaHookOwnerPid();
 	if (ownerPid !== null) {
+		// SESSION SWITCH RETIREMENT (#101 결함 A). One Claude process serves ONE session at a
+		// time, but it can switch which: an in-session `/resume` or `/clear` fires a second
+		// SessionStart under the same pid for a different native id, leaving the session the
+		// process started with behind (measured on oracle, meta-bridge-hook.log 2026-09-04
+		// 13:13:04 `source=startup` → 13:13:37 `source=resume`; the field case at 09:31:35 →
+		// 09:31:39 is the same shape). Whatever it was serving before is no longer being
+		// drained, so the marker advertising its doorbell has to go.
+		//
+		// The evidence is the sender marker as it stands RIGHT NOW — pid → the garden this
+		// process serves — which is why this reads it BEFORE the write below overwrites it with
+		// the new garden. No vendor field is consulted: `source` is logged, not branched on, so
+		// a host or version that words it differently changes nothing here. A same-garden
+		// re-registration (every UserPromptSubmit, a CwdChanged, a re-fired SessionStart) finds
+		// an equal garden id and retires NOTHING — the marker it would remove is the live one.
+		//
+		// Only the marker, never the record (see removeMetaReceiverMarker), and only a marker
+		// this pid owns.
+		//
+		// AND ONLY ON AN EVENT THAT CAN ARM THE REPLACEMENT (cross-review, 2026-09-04). This
+		// block sits before the UserPromptSubmit early-return, and UPS cannot emit watchPaths —
+		// so a retirement reached from there would take a doorbell down with nothing in the same
+		// run able to put one back. A watch is retired only by a run that arms one; that is the
+		// whole rule. `armProvenanceFor` is the same predicate the arm block below uses, so the
+		// two can never disagree about which events those are.
+		//
+		// It is NOT a defence against a keystroke from a session this pid has left: measured on
+		// oracle 2026-09-04 (raw lab S1-S6, meta-bridge-hook.log), every UserPromptSubmit named
+		// the native id its own pid's preceding SessionStart had established — 8 of 8, none
+		// otherwise. The hook runs synchronously inside the session's own process, so a UPS
+		// envelope is that session speaking, and the sender pointer it moves is authoritative.
+		const previous =
+			armProvenanceFor(eventName) !== null
+				? readMetaSenderMarker({ backend: "claude-code", ownerPid, verifyOwner: false })
+				: null;
+		if (previous && previous.gardenId !== gardenId) {
+			const retired = removeMetaReceiverMarker({ gardenId: previous.gardenId, ownerPid });
+			logLine(
+				"INFO",
+				retired
+					? `retired receiver marker ${previous.gardenId} — owner pid ${ownerPid} switched to ${gardenId} (event=${eventName}, source=${source})`
+					: `no receiver marker to retire for ${previous.gardenId} — owner pid ${ownerPid} switched to ${gardenId} (event=${eventName}, source=${source})`,
+			);
+		}
 		try {
 			writeMetaSenderMarker({ backend: "claude-code", gardenId, nativeSessionId: sessionId, cwd, ownerPid });
-			logLine("INFO", `sender marker ${ownerPid} -> ${gardenId} (event=${eventName})`);
+			logLine("INFO", `sender marker ${ownerPid} -> ${gardenId} (event=${eventName}, source=${source})`);
 		} catch (err) {
 			logLine(
 				"WARN",
@@ -294,7 +363,7 @@ function main(): void {
 					ownerPid,
 					armProvenance,
 				});
-				logLine("INFO", `receiver marker ${gardenId} owner=${ownerPid} arm=${eventName}`);
+				logLine("INFO", `receiver marker ${gardenId} owner=${ownerPid} arm=${eventName} source=${source}`);
 			} catch (err) {
 				logLine(
 					"WARN",