@junghanacs/entwurf 0.20.1 → 0.22.0

package/pi-extensions/lib/entwurf-fact-provider.ts

@@ -32,6 +32,7 @@ import {
 	isOutOfSocketDomainGardenIdConflict,
 	type PeerObserver,
 	resolveFactList,
+	UNOBSERVED_PEER,
 } from "./entwurf-facts.ts";
 import { observePeerFacts } from "./entwurf-peer-observe.ts";
 import { isLivenessSupported } from "./entwurf-v2-contract.ts";
@@ -102,9 +103,12 @@ export interface EntwurfFactsDeps {
 	/** Observation axis (#101): per-citizen receiver + transcript facts. Defaults to the
 	 * REAL measurement — the same seam shape `makeProductionEntwurfV2Deps` uses, so the two
 	 * wiring sites (MCP + pi-native) cannot drift by each passing their own observer, and a
-	 * gate still drives the assembly with a fake and no filesystem. A caller that injects
-	 * nothing gets facts; a caller that injects `() => UNOBSERVED_PEER` says so on every row. */
+	 * gate still drives the assembly with a fake and no filesystem. */
 	observe?: PeerObserver;
+	/** Optional presentation budget. Undefined preserves the generic fact provider's full
+	 * observation contract; peers surfaces pass their shared render limit. Older machine
+	 * payload rows then say `unobserved` rather than fabricating `active` / `exists`. */
+	observationLimit?: number;
 }
 
 function diagnosticSortKey(d: EntwurfDiagnostic): string {
@@ -195,9 +199,31 @@ export async function listEntwurfFacts(deps: EntwurfFactsDeps): Promise<EntwurfF
 	// 4. resolveFactList over CLEAN inputs only. Its throws (duplicate identity /
 	//    unprobed in-domain citizen) are impossible wiring invariants — left to
 	//    fire as the last line of defense, never caught here.
+	//
+	//    A peers surface may bound observation to its SAME newest rendered rows. Receiver
+	//    observation can inspect process state and historical Claude markers, so doing it
+	//    for every retained record made bounded text grow linearly with history. The generic
+	//    provider stays unbounded when no limit is supplied. Either way the full clean
+	//    identity/probe arrays reach the core: certification, duplicate detection,
+	//    diagnostics, liveness, and the machine payload remain complete. Only an observation
+	//    not performed becomes `unobserved`.
 	const cleanIdentities = identities.filter((i) => !conflictGids.has(i.gardenId));
 	const cleanProbes = probes.filter((p) => !conflictGids.has(p.gardenId));
-	const facts: FactList = resolveFactList(cleanIdentities, cleanProbes, deps.observe ?? observePeerFacts);
+	const observe = deps.observe ?? observePeerFacts;
+	let selectedObserve = observe;
+	if (deps.observationLimit !== undefined) {
+		if (!Number.isSafeInteger(deps.observationLimit) || deps.observationLimit < 0) {
+			throw new Error("listEntwurfFacts: observationLimit must be a non-negative safe integer");
+		}
+		const observedGardenIds = new Set(
+			[...cleanIdentities]
+				.sort((a, b) => (a.gardenId < b.gardenId ? -1 : a.gardenId > b.gardenId ? 1 : 0))
+				.slice(Math.max(0, cleanIdentities.length - deps.observationLimit))
+				.map((identity) => identity.gardenId),
+		);
+		selectedObserve = (identity) => (observedGardenIds.has(identity.gardenId) ? observe(identity) : UNOBSERVED_PEER);
+	}
+	const facts: FactList = resolveFactList(cleanIdentities, cleanProbes, selectedObserve);
 
 	// 5. #50 C4 demotion: a record-less socket is a diagnostic, not a listing
 	//    section. One diagnostic per socket (subjects aggregate at render, F8);

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

@@ -39,6 +39,9 @@ export interface EntwurfPeersRender {
 	payload: EntwurfPeersPayload;
 }
 
+/** Human rows and expensive provider observations share this one presentation budget. */
+export const ENTWURF_PEERS_RENDER_LIMIT = 32;
+
 // `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
@@ -124,7 +127,7 @@ function renderDiagnosticLines(diagnostics: EntwurfDiagnostic[]): string[] {
 	return lines;
 }
 
-function compactLines(lines: string[], max: number = 32): string[] {
+function compactLines(lines: string[], max: number = ENTWURF_PEERS_RENDER_LIMIT): string[] {
 	if (lines.length <= max) return lines;
 	const omitted = lines.length - max;
 	return [`  … (${omitted} older entries omitted; showing latest ${max})`, ...lines.slice(-max)];

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

@@ -122,13 +122,12 @@ export function isLivenessSupported(backend: string): boolean {
 
 // ── Native-push backend domain (봉인 2/4) ───────────────────────────────────
 // A backend whose liveness is measured by the SEPARATE native-push adapter rail (a
-// live app-server conversation probe — antigravity's LS gRPC), NOT a control
-// socket. This domain is DISJOINT from LIVENESS_DOMAIN_BACKENDS: an agy session
-// is `unsupported` on the socket FACT axis (entwurf_peers) yet fully
-// measured + deliverable on the native-push axis. The two are separate rails on
-// purpose — check-entwurf-facts pins both sets and asserts their intersection is ∅
-// (a backend can never be in both domains).
-export const NATIVE_PUSH_BACKENDS = ["antigravity"] as const;
+// live vendor app-server target probe), NOT a control socket. This domain is DISJOINT
+// from LIVENESS_DOMAIN_BACKENDS: an Antigravity or Codex session is `unsupported` on
+// the socket FACT axis (entwurf_peers) yet independently measured on the native-push
+// axis. The two are separate rails on purpose — check-entwurf-facts pins both sets
+// and asserts their intersection is ∅ (a backend can never be in both domains).
+export const NATIVE_PUSH_BACKENDS = ["antigravity", "codex"] as const;
 export type NativePushBackend = (typeof NATIVE_PUSH_BACKENDS)[number];
 
 export function nativePushSupported(backend: string): backend is NativePushBackend {

package/pi-extensions/lib/entwurf-v2-native-push.ts

@@ -5,11 +5,10 @@
  * ROUTING (the NATIVE_PUSH_DISPATCH_TABLE did) and carries NO release seam — a native-push
  * plan is the LOCK-FREE path (봉인 4), so a lock leak is structurally impossible here.
  *
- * This is where the 1-shot retry lives — NOT in the adapter leaf (봉인 3). The decider
- * probed a fresh route and planted it in the plan; the executor sends over it, and on a
- * failure it re-probes ONCE (the volatile LS port may have shifted between decide and
- * execute) and re-sends. A second failure is fail-loud (no infinite loop). This mirrors the
- * control-socket send-fallback pattern: the decider stays pure, the hand owns the retry.
+ * Retry is an adapter capability, not a rail-wide assumption. Antigravity re-probes once
+ * because its volatile LS port can shift before send. Codex never retries: `codex queue`
+ * may have accepted the message before its receipt failed, so replay could duplicate it.
+ * The decider stays pure; this hand enforces the adapter's declared policy.
  *
  * A native-push send has NO in-band refuse (there is no live receiver to answer
  * success:false) — like a mailbox enqueue, it either succeeds or THROWS. The hand never
@@ -18,6 +17,7 @@
 
 import type { ExecutionPlan } from "./entwurf-v2-decider.ts";
 import type { LockClaim } from "./entwurf-v2-lock.ts";
+import { formatMetaMailboxBody, type MailboxSenderEnvelope } from "./meta-mailbox-body.ts";
 import { type NativePushAdapter, type NativePushRoute, resolveNativePushAdapter } from "./native-push/adapter.ts";
 
 /** The native-push slice of the ExecutionPlan union (the decider plants it, this consumes it). */
@@ -25,16 +25,14 @@ export type NativePushPlan = Extract<ExecutionPlan, { transport: "native-push" }
 
 export interface NativePushSendResult {
 	success: true;
-	/** Whether the 1-shot re-probe→re-send fired (the first send over the planted route failed). */
+	/** Whether the adapter's one permitted re-probe→re-send fired. */
 	retried: boolean;
 }
 
 /**
- * Deliver `content` into the conversation, owning the 1-shot retry (봉인 3). Send over the
- * planted (decider-probed) route first; on failure re-probe ONCE and re-send over the fresh
- * route; a second failure PROPAGATES (fail-loud). If the re-probe finds the target no longer
- * alive, throw — a failed send into a now-dead conversation is an honest non-delivery, never
- * a silent success. The re-probe is the ONLY re-derivation of the volatile route.
+ * Deliver `content` through the decider-probed route. A non-retriable adapter propagates
+ * the first failure unchanged. A retriable adapter re-probes once and sends once more only
+ * when the target is still alive; no adapter gets a third attempt.
  */
 export async function deliverViaNativePush(
 	adapter: NativePushAdapter,
@@ -46,8 +44,8 @@ export async function deliverViaNativePush(
 		await adapter.send(route, nativeSessionId, content);
 		return { success: true, retried: false };
 	} catch (firstErr) {
-		// 1-shot re-probe → re-send: the volatile LS route may have shifted since the decider
-		// probed it. Re-discover it fresh and retry exactly once.
+		if (!adapter.retriable) throw firstErr;
+		// One re-probe and one retry for adapters whose send boundary is safe to replay.
 		const reprobe = await adapter.probe(nativeSessionId);
 		if (reprobe.status !== "alive") {
 			throw new Error(
@@ -65,22 +63,41 @@ export async function deliverViaNativePush(
  *  registry). Injected so the 5d gate proves the wiring with a fake adapter. */
 export interface NativePushSendDeps {
 	resolveAdapter?: (backend: string) => NativePushAdapter;
+	/** The SAME provider the mailbox hand receives (`makeProductionEntwurfV2Deps` passes one
+	 * `opts.senderProvider` to both). When it yields an envelope, the injected content is the
+	 * mailbox-serialized body — see the render note on `makeNativePushSend`. Absent/undefined
+	 * preserves the raw `plan.message`. */
+	senderProvider?: () => MailboxSenderEnvelope | undefined;
 }
 
 /**
  * Build the production `sendNativePush(plan, lock)` adapter the runner consumes. It IGNORES
- * `lock` entirely (a native-push plan is lock-free, 봉인 4) — the field exists only to match
- * the DispatchExecutorDeps hand signature. It resolves the adapter from the plan's backend
- * and delivers with the 1-shot retry. A delivery throw surfaces as a REJECTED promise (the
- * runner's try/catch maps it to execution-failed).
+ * `lock` entirely (a native-push plan is lock-free, 봉인 4), resolves the adapter, then applies
+ * that adapter's retry policy. A delivery throw surfaces as a REJECTED promise (the runner's
+ * try/catch maps it to execution-failed).
+ *
+ * SENDER ENVELOPE (measured #95). Direct injection used to hand the adapter the raw
+ * `plan.message`, so a native-push citizen received a body with no sender. The #95 A LIVE run
+ * measured what that costs: a fresh Pi's nonce-only callback landed in the Codex thread as
+ * bare text, and Codex could not name who called it — the callback was uncorrelatable. The
+ * control-socket rail carries the envelope in its RPC framing and the mailbox rail serializes
+ * it into the body; this rail has neither, so it renders the SAME `formatMetaMailboxBody` SSOT
+ * the mailbox uses. Rendered ONCE, before `deliverViaNativePush`, so an Antigravity re-probe
+ * retry replays byte-identical content (including its timestamp) instead of a second render.
+ * The adapter stays a dumb pipe — its signature is unchanged and it never learns about senders.
  */
 export function makeNativePushSend(
 	deps: NativePushSendDeps = {},
 ): (plan: NativePushPlan, lock: LockClaim | null) => Promise<NativePushSendResult> {
 	const resolveAdapter = deps.resolveAdapter ?? resolveNativePushAdapter;
+	const senderProvider = deps.senderProvider;
 	// `_lock` is named for the hand contract but NEVER read — native-push owns/releases no lock.
 	return async (plan: NativePushPlan, _lock: LockClaim | null): Promise<NativePushSendResult> => {
+		// Resolve the sender BEFORE the adapter is resolved or touched: a provider throw must
+		// reject this send with nothing injected, not leave a half-delivered conversation.
+		const sender = senderProvider?.();
+		const content = sender ? formatMetaMailboxBody(sender, plan.message, plan.wantsReply) : plan.message;
 		const adapter = resolveAdapter(plan.backend);
-		return deliverViaNativePush(adapter, plan.route, plan.nativeSessionId, plan.message);
+		return deliverViaNativePush(adapter, plan.route, plan.nativeSessionId, content);
 	};
 }

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

@@ -137,8 +137,9 @@ export interface ProductionEntwurfV2Seams {
 export interface ProductionEntwurfV2Opts {
 	/** Built at the wiring site from `buildLocalSenderEnvelope(ctx)`, decorated with its
 	 * HONEST pi-session replyability (SE-1 2e-a: `replyable` reflects whether the canonical
-	 * control socket actually exists, not a hardcoded true). ONE provider feeds the
-	 * control-socket RPC sender AND the meta-mailbox body sender (they share the envelope). */
+	 * control socket actually exists, not a hardcoded true). ONE provider feeds ALL THREE
+	 * rails — the control-socket RPC sender, the meta-mailbox body sender, and the
+	 * native-push injected body sender — so no rail can present a different who-sent-it. */
 	senderProvider: () => SenderEnvelope | undefined;
 	lockDir?: string;
 	sessionsDir?: string;
@@ -339,7 +340,13 @@ export function makeProductionEntwurfV2Deps(opts: ProductionEntwurfV2Opts): Entw
 		sendMailbox: (plan, _lock) => sendViaMailbox(plan as MetaMailboxPlan, _lock as LockClaim),
 		// native-push (봉인 4): the SAME injected adapter resolver drives the executor send,
 		// so the decider's probe and the delivery use one adapter. Lock-free (lock ignored).
-		sendNativePush: makeNativePushSend({ resolveAdapter: io.resolveNativePushAdapter }),
+		// It also receives the SAME `opts.senderProvider` the mailbox hand got — one envelope
+		// source for all three rails, so a native-push citizen can name its sender exactly as
+		// a mailbox citizen does (#95: an envelope-less direct injection is uncorrelatable).
+		sendNativePush: makeNativePushSend({
+			resolveAdapter: io.resolveNativePushAdapter,
+			senderProvider: opts.senderProvider,
+		}),
 	};
 
 	return {

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

@@ -12,8 +12,9 @@
  *
  * Why a result type richer than the receipt: the carry-over contracts from 5c demand it.
  *   - N3 (5c-2b): a dead-path re-resolve `rejected` carries the resolver's `rejectReason`
- *     (dormant-fire-forget-unsupported / mailbox-undeliverable / …). The runner carries it
- *     verbatim so the surface distinguishes "in-band refusal" from "no live route".
+ *     (dormant-fire-forget-unsupported / mailbox-undeliverable / …), while an in-band
+ *     refusal carries its supplied receiver error. The runner carries either verbatim;
+ *     receiver evidence is not reclassified as resolver taxonomy.
  *   - N1 (5c-2a): a non-`failed` outcome whose `releaseLock` then threw is a
  *     `SendDeliveredReleaseFailedError` — the delivery HAPPENED, the lock is dirty, a
  *     re-send would double-deliver. The runner surfaces this as `execution-failed` with

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

@@ -101,12 +101,12 @@ export interface ControlSocketSendDeps {
 
 export interface ControlSocketSendResult {
 	outcome: SendFinalOutcome;
-	/** Present ONLY on a `rejected` outcome that came from the dead-path re-resolve
-	 * (5c-2b): the resolver's machine-readable reason (dormant-fire-forget-unsupported /
-	 * mailbox-undeliverable / indeterminate-no-spawn / bad-target / target-address-conflict).
-	 * An in-band RPC refusal carries NO reason (there is no resolver taxonomy for it). The
-	 * 5d runner carries this verbatim so the surface can tell "in-band refusal" from
-	 * "no live route" — the N3 carry-over the hand boundary used to drop. */
+	/** Present ONLY on a `rejected` outcome. It carries either the dead-path re-resolver's
+	 * machine-readable reason (dormant-fire-forget-unsupported / mailbox-undeliverable /
+	 * indeterminate-no-spawn / bad-target / target-address-conflict), or the non-empty
+	 * error returned by an in-band RPC/mailbox refusal. The latter is receiver evidence,
+	 * not a resolver taxonomy and is never invented when the completed result has no error.
+	 * The 5d runner carries this verbatim to the sender-visible surface. */
 	rejectReason?: string;
 	/** #98 R, fallback leg: the `.msg` a dead-socket re-resolve enqueued. Present ONLY
 	 * when the fallback actually routed to the mailbox and the enqueue succeeded — a
@@ -120,7 +120,7 @@ export interface ControlSocketSendResult {
 
 // A drive step's verdict: the terminal outcome, plus the original error to RETHROW on
 // a `failed` (the hand releases first, then rethrows — never swallows the failure), plus
-// the optional resolver reject reason to carry on a re-resolve `rejected` (N3).
+// the optional resolver or in-band receiver reason to carry on a `rejected` (N3).
 interface SendDrive {
 	outcome: SendFinalOutcome;
 	error?: unknown;
@@ -177,8 +177,9 @@ async function driveSend(plan: ControlSocketPlan, lock: LockClaim, deps: Control
 		// dead ⇒ proven non-delivery ⇒ same-lock one-shot re-resolve (lock still held).
 		return await driveDeadFallback(plan, lock, deps);
 	}
-	// A completed RPC: ack ⇒ sent; in-band refusal ⇒ rejected, NO fallback.
-	return { outcome: result.success ? "sent" : "rejected" };
+	// A completed RPC: ack ⇒ sent; in-band refusal ⇒ rejected, NO fallback. Preserve
+	// its receiver error verbatim when supplied; do not make a reason up when absent.
+	return result.success ? { outcome: "sent" } : inBandRejected(result);
 }
 
 /**
@@ -187,6 +188,10 @@ async function driveSend(plan: ControlSocketPlan, lock: LockClaim, deps: Control
  * re-enter the fallback, it finalizes as failed). The hand only executes; the resolver
  * decided.
  */
+function inBandRejected(result: RpcSendResult): SendDrive {
+	return { outcome: "rejected", rejectReason: result.error === "" ? undefined : result.error };
+}
+
 async function driveDeadFallback(
 	plan: ControlSocketPlan,
 	lock: LockClaim,
@@ -219,7 +224,7 @@ async function driveDeadFallback(
 			// connect failure finalizes as failed (no further fallback).
 			try {
 				const r = await deps.sendOverSocket(rePlan);
-				return { outcome: r.success ? "fallback-sent" : "rejected" };
+				return r.success ? { outcome: "fallback-sent" } : inBandRejected(r);
 			} catch (err) {
 				return { outcome: "failed", error: err };
 			}
@@ -231,7 +236,7 @@ async function driveDeadFallback(
 				// #98 R: this leg writes a `.msg` exactly like the primary mailbox rail, so it
 				// owes the sender the same per-message receipt. Carried only on success — a
 				// `rejected` enqueue wrote no file to name.
-				return r.success ? { outcome: "fallback-sent", messagePath: r.messagePath } : { outcome: "rejected" };
+				return r.success ? { outcome: "fallback-sent", messagePath: r.messagePath } : inBandRejected(r);
 			} catch (err) {
 				return { outcome: "failed", error: err };
 			}

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

@@ -100,11 +100,14 @@ export function actionableRejectHint(reason: string): string | undefined {
 				"that garden id by a session that died without cleaning up."
 			);
 		case "native-push-target-dead":
-			// The adapter probe found no live host process for the conversation.
-			return "native-push conversation is not live (no host process found). Re-open the conversation, then retry — there is nothing to inject into.";
+			// The adapter probe found no live native host serving this conversation/thread. Stays
+			// backend-neutral: agy speaks conversations over an LS port, Codex threads over an
+			// app-server socket, and this hint is read by callers of both.
+			return "the native-push conversation/thread is not live — no native host (harness process or app-server) answered the probe for it. Re-open that conversation/thread in its own harness, then retry; there is nothing to inject into.";
 		case "native-push-probe-indeterminate":
-			// Host up, but no LS port served the conversation — inconclusive, not a hard dead.
-			return "native-push host is up but no port served this conversation (probe inconclusive). Retry once the conversation is loaded, or verify the conversation id.";
+			// Native host up, but nothing served this conversation/thread — inconclusive, not a
+			// hard dead. Backend-neutral for the same reason as the dead cell above.
+			return "the native host (harness process or app-server) is up, but nothing served this conversation/thread, so the probe is INCONCLUSIVE — not a measured death. Retry once it is loaded, or verify the conversation/thread id.";
 		case "record-less-socket":
 			// #50 C4: name the true cause AND the fix — a bare socket is a diagnostic
 			// state, not an addressable citizen (the record is the address).

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

@@ -1,26 +1,33 @@
 /**
  * meta-mailbox-body — the SINGLE source for rendering an entwurf message as a
- * meta-bridge mailbox body. Both transports that can deliver to a garden citizen
- * with no live control socket use this:
+ * meta-bridge mailbox body. Every transport that can deliver to a garden citizen
+ * with no live control socket uses this:
  *   - the MCP bridge entwurf_v2 (mcp/entwurf-bridge) — external/Claude-host sends
  *   - the pi-native entwurf_v2 (pi-extensions/entwurf-control.ts) — pi-session sends
+ *   - the native-push rail (pi-extensions/lib/entwurf-v2-native-push.ts) — direct
+ *     injection into an Antigravity conversation or a loaded Codex thread. Its
+ *     THIRD consumer, added after the #95 A LIVE run measured what an envelope-less
+ *     injection costs: a nonce-only callback arrived in a Codex thread as bare text
+ *     and the receiving citizen could not name who had called it.
  *
  * The control-socket path carries the sender envelope inside its RPC framing; the
- * mailbox path is just a file, so the envelope must be SERIALIZED INTO the body —
- * else a receiver reading entwurf_inbox_read would not know who sent it, whether
- * the sender is replyable (and at which sessionId), or whether a reply was wanted.
- * The render mirrors the live "[entwurf received ⟵]" header so a transcript reads
- * the same whether the message arrived over a socket or a mailbox.
+ * mailbox path is just a file and direct injection is just a string, so for both the
+ * envelope must be SERIALIZED INTO the body —
+ * else a receiver — reading entwurf_inbox_read, or reading an injected turn in its own
+ * conversation — would not know who sent it, whether the sender is replyable (and at
+ * which sessionId), or whether a reply was wanted. The render mirrors the live
+ * "[entwurf received ⟵]" header so a transcript reads the same whether the message
+ * arrived over a socket, a mailbox, or direct injection.
  *
  * No filesystem/network IO and no mutation — the only ambient read is
  * process.env.HOME for display abbreviation (so not strictly referentially pure,
- * but deterministic per environment). Extracted so the two senders cannot drift
- * in how a mailbox message presents who-sent-it — the field that round-trips
- * garden-id replies.
+ * but deterministic per environment). Extracted so the three consumers cannot
+ * drift in how a delivered message presents who-sent-it — the field that
+ * round-trips garden-id replies.
  */
 
-/** The fields a mailbox body needs from a sender. Structurally compatible with
- * the SenderEnvelope of both entwurf_v2 surfaces. */
+/** The fields a sender-envelope presentation needs from a sender. Structurally
+ * compatible with the SenderEnvelope of both entwurf_v2 surfaces. */
 export interface MailboxSenderEnvelope {
 	sessionId: string;
 	agentId: string;
@@ -53,7 +60,9 @@ function formatKstTimestamp(iso: string): string {
 }
 
 /**
- * Render the full mailbox body: header envelope + separator + message. A
+ * Render the full body: header envelope + separator + message. The mailbox writes this
+ * into its message file and the native-push rail injects it directly into a live
+ * conversation; both present the sender identically. A
  * replyable sender (pi-session, or a trusted meta-session) advertises its
  * sessionId as the reply address; a non-replyable sender says so WITHOUT
  * losing its origin — a record-backed meta-session that is currently inactive