@junghanacs/entwurf 0.20.0 → 0.21.0

package/pi-extensions/entwurf-control.ts

@@ -81,6 +81,13 @@ import type {
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import { Box, type Component, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { ENTWURF_SENT_MESSAGE_TYPE } from "../protocol.js";
+import {
+	type CompactionGuard,
+	compactionSendReject,
+	createCompactionGuard,
+	noteCompactionBefore,
+	noteCompactionTerminal,
+} from "./lib/compaction-send-guard.js";
 import { CONTROL_SOCKET_SUFFIX, controlSocketPathIn, defaultControlSocketDir } from "./lib/control-socket-path.js";
 import {
 	formatSenderInfoBlock,
@@ -126,6 +133,7 @@ interface SocketState {
 	server: net.Server | null;
 	socketPath: string | null;
 	context: ExtensionContext | null;
+	compaction: CompactionGuard;
 }
 
 // The resident's GARDEN ADDRESS (#50 C2) — minted by this session's meta-record at
@@ -754,6 +762,15 @@ async function handleCommand(
 			}
 		}
 
+		const compactionReject = compactionSendReject(state.compaction, {
+			idle: ctx.isIdle(),
+			hasAgentSignal: ctx.signal !== undefined,
+		});
+		if (compactionReject) {
+			respond(false, "send", undefined, compactionReject);
+			return;
+		}
+
 		// wants_reply defaults to false (etiquette marker, not transport contract).
 		// It surfaces a "(wants reply)" badge on the receiver render so the
 		// human/agent at either end sees that the sender wants a conversational
@@ -1036,6 +1053,7 @@ export default function (pi: ExtensionAPI) {
 		server: null,
 		socketPath: null,
 		context: null,
+		compaction: createCompactionGuard(),
 	};
 
 	pi.registerMessageRenderer(SESSION_MESSAGE_TYPE, renderSessionMessage);
@@ -1152,15 +1170,27 @@ export default function (pi: ExtensionAPI) {
 	// were dead. The typecheck-exclude on this file kept that decay invisible.
 	// Don't reintroduce them without first confirming the events exist.
 	pi.on("session_start", async (_event, ctx) => {
+		noteCompactionTerminal(state.compaction);
 		await refreshServer(ctx);
 	});
 
+	pi.on("session_before_compact", () => {
+		noteCompactionBefore(state.compaction);
+	});
+	pi.on("session_compact", () => {
+		noteCompactionTerminal(state.compaction);
+	});
+	pi.on("session_compact_failed", () => {
+		noteCompactionTerminal(state.compaction);
+	});
+
 	// No session_before_switch / session_before_fork guards: `/new`, `/fork`, `/clone`
 	// and RPC session replacement are pi's own again (#50 C2). Each replacement fires
 	// session_start, which attaches the new pi session to its own record — the socket
 	// simply rebinds to the new address. There is no id to police at the pre-event.
 
 	pi.on("session_shutdown", async () => {
+		noteCompactionTerminal(state.compaction);
 		updateStatus(state.context, false, null);
 		updateSessionEnv(state.context, false, null);
 		residentGardenId = null;
@@ -1423,10 +1453,12 @@ interface EntwurfFactProviderModule {
 		metaEntries: readonly { filename: string; regularFile: boolean }[];
 		readRecord: (filename: string) => string;
 		socket: { dir: string };
+		observationLimit: number;
 	}): Promise<unknown>;
 }
 
 interface EntwurfPeersRenderModule {
+	ENTWURF_PEERS_RENDER_LIMIT: number;
 	renderEntwurfPeers(result: unknown): { text: string; payload: unknown };
 }
 
@@ -1445,14 +1477,17 @@ async function renderEntwurfPeersForSurface(): Promise<{ text: string; payload:
 	// surfaced by the #52 duplicate pass, which would let such a symlink quarantine the
 	// healthy record it shadowed).
 	const provider = (await import(ENTWURF_FACT_PROVIDER_MODULE)) as unknown as EntwurfFactProviderModule;
+	const render = (await import(ENTWURF_PEERS_RENDER_MODULE)) as unknown as EntwurfPeersRenderModule;
 	const result = await provider.listEntwurfFacts({
 		metaEntries: meta.readActiveStoreEntries(sessionsDir),
 		readRecord: meta.makeStoreRecordReader(sessionsDir),
 		// Same socket axis as the legacy live-session scan, but merged with the
 		// meta-record rail by listEntwurfFacts so meta-mailbox citizens are discoverable too.
 		socket: { dir: ENTWURF_DIR },
+		// #112: observation follows the human render budget. The full machine payload
+		// and every authority/diagnostic pass above remain complete.
+		observationLimit: render.ENTWURF_PEERS_RENDER_LIMIT,
 	});
-	const render = (await import(ENTWURF_PEERS_RENDER_MODULE)) as unknown as EntwurfPeersRenderModule;
 	return render.renderEntwurfPeers(result);
 }
 
@@ -1496,11 +1531,16 @@ function registerListSessionsTool(pi: ExtensionAPI): void {
 // ============================================================================
 
 const MUX_FRESH_CALL_MODULE = "./lib/mux-fresh-call.ts";
+const CODEX_FRESH_PREFLIGHT_MODULE = "./lib/codex-fresh-preflight.ts";
+
+interface CodexFreshPreflightModule {
+	codexFreshPreflight(env: NodeJS.ProcessEnv): Promise<string | null>;
+}
 
 interface MuxFreshCallModule {
 	freshCall(
 		params: {
-			backend: "pi" | "claude-code" | "copilot" | "omp";
+			backend: "pi" | "claude-code" | "copilot" | "omp" | "codex";
 			model: string;
 			task: string;
 			cwd?: string;
@@ -1530,35 +1570,34 @@ function registerFreshCallTool(pi: ExtensionAPI): void {
 	registerTool({
 		name: "entwurf_fresh_call",
 		label: "Open Fresh Sibling",
-		description: `Open ONE fresh visible sibling in the operator's tmux and hand it a first task. Four fixed
-backends only: pi, claude-code, copilot, omp. The sibling's FIRST action is a callback to you carrying a nonce, and the
+		description: `Open ONE fresh visible sibling in the operator's tmux and hand it a first task. Five fixed
+backends only: pi, claude-code, copilot, omp, codex. The sibling's FIRST action is a callback to you carrying a nonce, and the
 sender envelope of that callback is its garden id — that is how you learn the address of something that did
 not exist a moment ago. This returns a LAUNCH receipt (tmux window/pane plus that nonce) and nothing else:
 it does NOT mean the runtime started, the first turn ran, or the task was delivered. Nothing polls for the
 callback; if it never arrives the window is visible and can be read directly. For EXISTING citizens use
 entwurf_v2 — this tool only creates, and entwurf_peers only reports. Model is REQUIRED and passed to the
-chosen runtime CLI (provider/model for pi; model id/alias for Claude Code; a Copilot model name or auto; a
-fuzzy model pattern for omp). A copilot launch goes through entwurf's own managed invocation and is refused
-BEFORE any window opens if this host lacks the Copilot birth, MCP, receiver or visible-footer units; an omp
-launch is refused the same way if this host lacks the OMP birth, MCP, receiver or visible-status units, or if
-omp's tools.xdev is not false (the vendor default hides MCP tool schemas from the prompt, so the sibling
-could not call you back at all). An optional cwd starts the
+chosen runtime CLI (provider/model for pi; model id/alias for Claude Code; a Copilot, OMP, or Codex model
+name). Copilot, omp, and codex are refused BEFORE any window opens when their required birth, MCP,
+receive/delivery, or visible-identity units are absent. Codex additionally requires the operator-owned
+default app-server socket; entwurf never starts or supervises it. An optional cwd starts the
 sibling in ONE literal absolute existing directory (cross-repo fresh) — never pick resume for a dormant
 record's cwd; resume is continuity-only. Omitted/empty cwd means the caller's own directory. An optional
-placement.tmuxSession opens it in ONE EXISTING session of this agent's own tmux server; an absent SESSION is
-tmux-session-missing and NOTHING is created. Omit placement for the caller's own session. There are no
+placement.tmuxSession is an expert override naming ONE EXISTING session on this agent's own tmux server.
+When placement is omitted, Codex targets the exact existing \`codex\` home session; other backends target the
+caller's session. A missing named/home session is tmux-session-missing and NOTHING is created. There are no
 arbitrary command/env knobs. Do not put secrets in the task — model and task argv are visible to same-user
 processes on this host.`,
 		parameters: Type.Object({
-			backend: StringEnum(["pi", "claude-code", "copilot", "omp"], {
-				description: "Which fixed runtime to open. Only these four; there is no arbitrary command.",
+			backend: StringEnum(["pi", "claude-code", "copilot", "omp", "codex"], {
+				description: "Which fixed runtime to open. Only these five; there is no arbitrary command.",
 			}),
 			model: Type.String({
 				minLength: 1,
 				maxLength: 200,
 				pattern: "^[A-Za-z0-9][A-Za-z0-9._/:\\[\\]-]*$",
 				description:
-					"Required runtime model: canonical provider/model for pi, a Claude Code model id/alias, or a Copilot model name (or auto).",
+					"Required runtime model: canonical provider/model for pi, a Claude Code model id/alias, or a Copilot/OMP/Codex model name.",
 			}),
 			task: Type.String({
 				minLength: 1,
@@ -1582,7 +1621,7 @@ processes on this host.`,
 					},
 					{
 						description:
-							"Optional project seat: open the sibling in ONE EXISTING tmux session of this agent's own server instead of the caller's session. Nothing is ever created — an absent session is a refusal, not a new session. Independent of cwd; neither is inferred from the other. The receipt echoes the REQUESTED name and reports the resolved target session id.",
+							"Optional expert seat override: open the sibling in ONE EXISTING tmux session of this agent's own server. When omitted, Codex selects the exact existing `codex` home session; other backends use the caller's session. Nothing is ever created. Independent of cwd; neither is inferred from the other. The receipt reports the selected name, its source, and resolved target session id.",
 					},
 				),
 			),
@@ -1590,7 +1629,7 @@ processes on this host.`,
 		async execute(
 			_toolCallId: string,
 			params: {
-				backend: "pi" | "claude-code" | "copilot" | "omp";
+				backend: "pi" | "claude-code" | "copilot" | "omp" | "codex";
 				model: string;
 				task: string;
 				cwd?: string;
@@ -1602,14 +1641,27 @@ processes on this host.`,
 		) {
 			try {
 				const mux = (await import(MUX_FRESH_CALL_MODULE)) as unknown as MuxFreshCallModule;
-				const result = mux.freshCall({
+				// ONE input object for ONE composition call. The codex branch differs only by the
+				// capability preflight that must answer BEFORE any mutation; duplicating the call
+				// would put the caller-identity contract in two places, which is how a mutant that
+				// plants a defect in one of them survives on the other.
+				const call = {
 					backend: params.backend,
 					model: params.model,
 					task: params.task,
 					cwd: params.cwd,
 					placement: params.placement,
 					callerGardenId: residentGardenId,
-				});
+				};
+				const result =
+					params.backend === "codex"
+						? await (async () => {
+								const preflight = (await import(CODEX_FRESH_PREFLIGHT_MODULE)) as unknown as CodexFreshPreflightModule;
+								const missing = await preflight.codexFreshPreflight(process.env);
+								if (missing) return { ok: false as const, reason: missing };
+								return mux.freshCall(call);
+							})()
+						: mux.freshCall(call);
 				const rendered = mux.renderFreshCall(result);
 				return {
 					content: [{ type: "text", text: rendered.text }],

package/pi-extensions/lib/acp/acp-client.ts

@@ -46,8 +46,8 @@ import type { AcpTextBlock } from "./context.js";
  * shape) and never onto those four. A field rename upstream fails the typecheck
  * here rather than silently zeroing the operator's cache-effect badge.
  */
-/** One `_meta.quota.token_count` row (claude-agent-acp 0.75.1
- *  `dist/acp-agent.js:6493-6502`). `cachedInputTokens` is cache READS — the name
+/** One `_meta.quota.token_count` row (claude-agent-acp 0.76.0
+ *  `dist/acp-agent.js:6566-6575`). `cachedInputTokens` is cache READS — the name
  *  differs from `usage.cachedReadTokens` because the shape is shared with
  *  codex-acp; `cachedWriteTokens` is Claude's extra sibling. */
 export type AcpQuotaTokenCount = {
@@ -64,7 +64,7 @@ export type AcpPromptResponse = {
 	/** Vendor-private, version-pinned. `_meta` is a standard ACP extension slot
 	 *  whose values a client may not assume, and `quota` is NOT in
 	 *  claude-agent-acp's exported types — it is produced by the private
-	 *  `turnQuotaMeta()` (read at 0.75.1 `dist/acp-agent.js:6476-6485`). Read
+	 *  `turnQuotaMeta()` (read at 0.76.0 `dist/acp-agent.js:6549-6558`). Read
 	 *  defensively, never structurally required, and re-measure on a pin move. */
 	_meta?: {
 		quota?: {

package/pi-extensions/lib/acp/backend-adapter.ts

@@ -150,7 +150,7 @@ export interface AcpAdapterSettingsParams {
  *
  * During stream handling the vendor keeps a per-message snapshot in
  * `lastAssistantUsage`, but its `usage_update` publishes only the scalar `used`
- * value (read at claude-agent-acp 0.75.1 `dist/acp-agent.js:3853-3878`). Until
+ * value (read at claude-agent-acp 0.76.0 `dist/acp-agent.js:3857-3882`). Until
  * that partition is carried on the wire, NOTHING honest can go in pi's four
  * fields, so entwurf writes none of them.
  */
@@ -342,8 +342,8 @@ export const claudeAdapter: AcpBackendAdapter = {
 
 	// MEASURED (2026-09-02, #93): claude-agent-acp's `usage_update` carries a
 	// session-cumulative ESTIMATED cost (`cost.amount = message.total_cost_usd`)
-	// and a context-occupancy scalar (`used`; both read at 0.75.1
-	// `dist/acp-agent.js:3467-3482`). Both are measured, so backend.ts seals them.
+	// and a context-occupancy scalar (`used`; both read at 0.76.0
+	// `dist/acp-agent.js:3471-3486`). Both are measured, so backend.ts seals them.
 	// The token partition is NOT declared here: ACP's only token carrier is a
 	// per-turn round-trip aggregate, which is not what pi's four fields mean.
 	sealsTurnAccounting: true,

package/pi-extensions/lib/acp/backend.ts

@@ -137,7 +137,7 @@ function finiteOrZero(value: unknown): number {
  * "the accounting-grade figure per the SDK" — it also counts Task subagents,
  * sidechains, and INTERNAL CALLS SUCH AS COMPACTION, so its rows "can total more
  * than `token_count`" and are "the fuller picture, not a decomposition of it"
- * (read at claude-agent-acp 0.75.1 `dist/acp-agent.js:6465-6485`). The narrower
+ * (read at claude-agent-acp 0.76.0 `dist/acp-agent.js:6538-6558`). The narrower
  * `PromptResponse.usage` (== `quota.token_count`) is the MAIN AGENT LOOP only.
  *
  * The wider one is the right numerator because the denominator already has that
@@ -1237,7 +1237,7 @@ export function streamAcpTurn(
 		// Writing zeros is not a placeholder for a better number we could compute:
 		// the per-request partition is genuinely absent from the wire. The vendor
 		// builds it in `lastAssistantUsage` and sends only its scalar sum (read at
-		// claude-agent-acp 0.75.1 `dist/acp-agent.js:3853-3878`) — #96.
+		// claude-agent-acp 0.76.0 `dist/acp-agent.js:3857-3882`) — #96.
 		//
 		// But silence is NOT the resting state. A cache miss the operator never sees
 		// is a false reading, not a modest one: a session can run for hours believing
@@ -1356,7 +1356,7 @@ export function streamAcpTurn(
 				// between them is exactly why the notice below names a MECHANISM and
 				// never a cause: claude-agent-acp's `conversation_reset` handler only
 				// switches the SDK to a fresh conversation and touches no cost at all
-				// (read at 0.75.1 `dist/acp-agent.js:4282-4289`), while claude-agent-sdk
+				// (read at 0.76.0 `dist/acp-agent.js:4286-4293`), while claude-agent-sdk
 				// separately documents that "a mid-session /clear resets the running
 				// total" (read at 0.3.257 `sdk.d.ts:4884`). A reset therefore PLAUSIBLY
 				// explains a backwards total, but nothing here has MEASURED that it did,

package/pi-extensions/lib/acp/event-mapper.ts

@@ -60,8 +60,8 @@ export type AcpPiStreamState = {
 	 *
 	 * Last write wins, never a sum: both are latest session-level observations, and
 	 * one turn can legitimately see several (claude emits one per `result` message,
-	 * including a sub-agent's own — read at claude-agent-acp 0.75.1
-	 * `dist/acp-agent.js:3467-3482`), each carrying that result's current values.
+	 * including a sub-agent's own — read at claude-agent-acp 0.76.0
+	 * `dist/acp-agent.js:3471-3486`), each carrying that result's current values.
 	 */
 	observedSessionCostUsd?: number;
 	observedContextOccupancyTokens?: number;
@@ -346,8 +346,8 @@ export function applyAcpSessionUpdate(
 		case "usage_update": {
 			// `used` is OCCUPANCY-shaped — the backend's post-turn context size, not
 			// the prompt response's turn aggregate. Claude sends `lastAssistantTotalUsage`
-			// as `used` (read at claude-agent-acp 0.75.1
-			// `dist/acp-agent.js:3867-3878`), after constructing that scalar from the
+			// as `used` (read at claude-agent-acp 0.76.0
+			// `dist/acp-agent.js:3871-3882`), after constructing that scalar from the
 			// latest assistant snapshot (`:3853-3866`). pi reads `usage.totalTokens` as
 			// exactly that occupancy (`calculateContextTokens(usage) = usage.totalTokens
 			// || input + output + cacheRead + cacheWrite`, read at pi-coding-agent

package/pi-extensions/lib/acp/tool-surface.ts

@@ -150,6 +150,12 @@ export function buildClaudeSessionMeta(
 		...(params.modelId ? { model: params.modelId } : {}),
 		tools: [...params.tools],
 		settingSources: [...params.settingSources],
+		// `settings` is an OBJECT here, and that is a contract, not a convenience.
+		// claude-agent-acp also accepts a STRING PATH, and at 0.76.0 the readFile +
+		// JSON.parse for that form moved out of `resolvedProvider` up onto the
+		// unconditional `session/new` path — a shape that WOULD reach us, and does not,
+		// only because we never hand it a path. Keep it inline: a path would put file
+		// IO, and its failure modes, inside every session creation.
 		settings: {
 			permissions: {
 				allow: [...params.permissionAllow],