@junghanacs/entwurf 0.16.1 → 0.17.2

package/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js

@@ -2077,9 +2077,17 @@ export function enqueueMetaMessage(opts) {
  * Drain a garden citizen's mailbox: read every unread message (a fresh `.msg`
  * read before its doorbell, or a doorbell-rung `.msg.delivered`), archive each to
  * `*.read` so a re-read never double-returns, and — only if at least one message
- * was read — stamp `lastReadAt` (NOT `lastDeliveredAt`: the doorbell owns
- * delivery-time, see the stamp-site note below). An empty inbox mutates nothing:
- * reading nothing is not a receipt.
+ * was read — stamp `lastReadAt`. `lastDeliveredAt` stays untouched (see the
+ * stamp-site note below). An empty inbox mutates nothing: reading nothing is not
+ * a receipt.
+ *
+ * WHERE THE PER-MESSAGE TRUTH LIVES (#98 5a, corrected 2026-09-03). The FILE SUFFIX
+ * is the per-message receipt: `.msg` = enqueued, `.msg.delivered` = the doorbell
+ * rang for it, `.msg.delivered.read` = this function handed it to the reader.
+ * `state.json` is NOT that — its three slots are GARDEN-WIDE and overwritten, so
+ * `lastReadAt` says "this citizen last read something at T", never "message X was
+ * read". A sender that quotes `lastReadAt` back as the fate of the letter it just
+ * queued is quoting the PREVIOUS letter's read. That misreading is what opened #98.
  */
 export function readMetaInbox(opts) {
     const now = opts.now ?? new Date();
@@ -2101,10 +2109,18 @@ export function readMetaInbox(opts) {
     if (messages.length === 0) {
         return { gardenId: citizen.gardenId, messages, readAt: null, recordPath: recordFile };
     }
-    // 3D-4 the cut: the read receipt lives SOLELY in the mailbox state store now.
-    // Stamp lastReadAt — the one receipt this layer stamps honestly (it KNOWS the body
-    // reached the reader). lastDeliveredAt is the doorbell's to own; stamping it here
-    // would report read-time as delivery-time, so it is left as the doorbell left it.
+    // 3D-4 the cut: the garden-wide read receipt lives SOLELY in the mailbox state store
+    // now. Stamp lastReadAt — the one slot this layer stamps honestly (it KNOWS a body
+    // reached the reader at this instant). lastDeliveredAt is left alone, and #98 5a
+    // corrects WHY: the old comment said "the doorbell owns it", but the shipped
+    // doorbell.sh (54 lines) writes NOTHING to state.json — measured, zero state writes.
+    // So `lastDeliveredAt` is a RESERVED SLOT nobody stamps, permanently null on all
+    // ~180 on-disk states, while 900+ files carry a `.delivered` suffix. Stamping it
+    // here would still be wrong (it would report read-time as delivery-time), so it
+    // stays null — but do not read "the doorbell will fill it in" into that. The
+    // per-message delivery fact is the `.delivered` SUFFIX. The field is left in place
+    // deliberately: removing it is a migration (the parser rejects unknown keys AND a
+    // bumped schemaVersion, and every stamp re-parses first), tracked as #98 5b.
     // The state stamp returns the updated state, whose lastReadAt IS the D7 read-receipt.
     // Inside the messages.length>0 branch by construction — an empty inbox already
     // early-returned (no .read archive, state untouched), so "read nothing" is no

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.16.1",
+	"version": "0.17.2",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for Claude Code, Codex, Antigravity, and pi harnesses.",
 	"license": "MIT",
 	"author": {
@@ -82,8 +82,8 @@
 		"claudeCodeFloor": ">=2.1.217"
 	},
 	"dependencies": {
-		"@agentclientprotocol/claude-agent-acp": "0.70.0",
-		"@agentclientprotocol/sdk": "1.3.0",
+		"@agentclientprotocol/claude-agent-acp": "0.73.0",
+		"@agentclientprotocol/sdk": "1.4.0",
 		"@anthropic-ai/sdk": "0.100.1",
 		"@modelcontextprotocol/sdk": "^1.12.1",
 		"zod": "^3.25.0 || ^4.0.0"
@@ -165,7 +165,7 @@
 		"check:toolchain": "pnpm lint && pnpm typecheck",
 		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface",
 		"check:contracts": "./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-resume-args && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-entwurf-facts && ./run.sh check-control-socket-path && ./run.sh check-socket-discovery && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment",
-		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex",
+		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-usage-accounting && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex",
 		"check:package": "./run.sh check-install-surface && ./run.sh smoke-meta-install-state && ./run.sh smoke-agy-install-state && ./run.sh smoke-setup-verdict && ./run.sh check-pack-pin-matcher && ./run.sh check-package-source-routing && ./run.sh check-install-preflight && ./run.sh check-pack"
 	},
 	"pi": {

package/pi/meta-bridge/entwurf-meta-receive/hooks/hooks.json

@@ -45,7 +45,9 @@
 						"command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-launch.sh",
 						"args": ["${CLAUDE_PLUGIN_ROOT}/scripts/doorbell.sh"],
 						"asyncRewake": true,
-						"timeout": 20
+						"timeout": 20,
+						"rewakeSummary": "entwurf inbox: sibling mail arrived",
+						"rewakeMessage": "entwurf mailbox notice:"
 					}
 				]
 			}

package/pi/meta-bridge/entwurf-meta-receive/scripts/doorbell.sh

@@ -6,15 +6,20 @@
 # with a doorbell notice. Free: a file write + continuation of an already-running
 # subscription session (no `claude -p` spawn).
 #
-# ADDRESSED by GARDEN ID: the changed path arrives on stdin as `file_path`; its
-# directory IS this session's garden mailbox (<meta-mailbox>/<garden-id>/). So
-# this hook touches ONLY its own mailbox — a sender that pokes one garden id's
-# signal wakes only that session. No node needed here; the dirname is the mailbox.
+# ADDRESSED by GARDEN ID: the changed path arrives on stdin as `file_path` and this
+# hook takes its DIRECTORY as the mailbox to process. No node needed here; the
+# dirname is the mailbox.
 #
-# DOORBELL ONLY: announce "you have mail" + the body path on stderr (the sole
-# asyncRewake payload channel — stdout is dropped). NEVER push imperatives; strong
-# models flag hook-injected commands as prompt injection. The agent self-fetches
-# the body with its own trusted tool, and that inbox-read is the real D7 receipt.
+# Two statements, deliberately kept apart (#98, 2026-09-03 — they used to be one
+# sentence claiming this hook "touches ONLY its own mailbox"):
+#   - PREMISE: under a normal install the only watch this session armed is its own
+#     <garden-id>/inbox.signal, so that is the only file_path that arrives.
+#   - LIMIT: this script does not verify it. It trusts `file_path` and never compares
+#     the dirname against its garden id. Measured — a second FileChanged hook in the
+#     same session made this doorbell process the OTHER mailbox and race it to exit 2,
+#     which is why a second such hook cannot coexist with this one.
+#   Receipt: scripts/raw-async-delivery/README.md, "What the probe session actually
+#   touches". Not a live defect: nothing pokes a signal outside the garden mailbox.
 #
 # RUNTIME DEPS: bash + python3 (the FileChanged stdin JSON is parsed with python3
 # below — robust against escaping, unlike sed/grep). The meta-bridge doctor must

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

@@ -17,14 +17,68 @@
 // smokes both drive ONE adapter — the SDK method-name mapping lives here only,
 // and the backend's orchestration + the gate fakes stay untouched.
 
-import { AGENT_METHODS, CLIENT_METHODS, client, type Stream } from "@agentclientprotocol/sdk";
+import {
+	type Usage as AcpWireUsage,
+	AGENT_METHODS,
+	CLIENT_METHODS,
+	client,
+	type Stream,
+} from "@agentclientprotocol/sdk";
 import type { AcpTextBlock } from "./context.js";
 
+/**
+ * What `session/prompt` answers with — entwurf's own narrow view of the SDK's
+ * `PromptResponse`.
+ *
+ * `stopReason` stays `string | undefined` DELIBERATELY, not the SDK's closed
+ * `StopReason` union: backend.ts's verdict mapping owes an honest answer for an
+ * unknown or absent reason (it seals those as errors), and typing the field as
+ * the closed union would make that branch look unreachable.
+ *
+ * `usage` reuses the SDK's own `Usage` type rather than a hand-copy, so a field
+ * rename upstream is a typecheck failure here instead of a silent zero. It is
+ * marked `@experimental` upstream and its per-field comments say "across all
+ * turns/session" while the outer one says "for this turn" — that contradiction
+ * is why NO common code interprets this shape — and #93 then measured that the
+ * counts are a per-turn ROUND-TRIP AGGREGATE, which is not what any of pi's four
+ * `Usage` fields mean. It is read in exactly ONE place, `sealTurnUsage`, which
+ * relays it verbatim onto `usage.acp` (an accounting key, never a per-request
+ * 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.73.0
+ *  `dist/acp-agent.js:5750-5765`). `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 = {
+	totalTokens?: number | null;
+	inputTokens?: number | null;
+	cachedInputTokens?: number | null;
+	cachedWriteTokens?: number | null;
+	outputTokens?: number | null;
+};
+
+export type AcpPromptResponse = {
+	stopReason?: string;
+	usage?: AcpWireUsage | null;
+	/** 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.73.0 `dist/acp-agent.js:5738-5748`). Read
+	 *  defensively, never structurally required, and re-measure on a pin move. */
+	_meta?: {
+		quota?: {
+			token_count?: AcpQuotaTokenCount | null;
+			model_usage?: ReadonlyArray<{ model?: string; token_count?: AcpQuotaTokenCount | null }> | null;
+		} | null;
+	} | null;
+};
+
 /** The subset of the ACP agent connection the backend drives (real or fake). */
 export interface AcpConnectionLike {
 	initialize(params: unknown): Promise<unknown>;
 	newSession(params: unknown): Promise<{ sessionId?: string }>;
-	prompt(params: { sessionId: string; prompt: AcpTextBlock[] }): Promise<{ stopReason?: string }>;
+	prompt(params: { sessionId: string; prompt: AcpTextBlock[] }): Promise<AcpPromptResponse>;
 	setSessionConfigOption?(params: unknown): Promise<unknown>;
 	/**
 	 * ACP `session/cancel` — the PROTOCOL way to end an in-flight prompt turn.
@@ -84,8 +138,7 @@ export function connectAcpClient(stream: Stream, handlers: AcpClientHandlers): A
 		initialize: (params) => agent.request(AGENT_METHODS.initialize, params as never),
 		newSession: (params) =>
 			agent.request(AGENT_METHODS.session_new, params as never) as Promise<{ sessionId?: string }>,
-		prompt: (params) =>
-			agent.request(AGENT_METHODS.session_prompt, params as never) as Promise<{ stopReason?: string }>,
+		prompt: (params) => agent.request(AGENT_METHODS.session_prompt, params as never) as Promise<AcpPromptResponse>,
 		setSessionConfigOption: (params) => agent.request(AGENT_METHODS.session_set_config_option, params as never),
 		cancel: (params) => {
 			// Notification, not a request: nothing resolves it, and the connection

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

@@ -131,6 +131,30 @@ export interface AcpAdapterSettingsParams {
 	projectPath: string;
 }
 
+/**
+ * NO turn-usage evidence type lives here any more, and its absence is the #93
+ * finding, not an omission.
+ *
+ * ACP reports a turn's tokens ONLY as the SUM OVER THAT TURN'S API ROUND TRIPS
+ * (measured 2026-09-02: one 21-round-trip turn summed to cacheRead 4,185,084
+ * while the context it occupied was 223,516 — the overlay ledger's 21 rows add
+ * up to the four numbers `PromptResponse.usage` reported). pi's four `Usage`
+ * fields are not that quantity: `isContextOverflow` reads `input + cacheRead`
+ * as ONE REQUEST's prompt size (read at pi-ai `dist/utils/overflow.js:132-145`)
+ * and `cache-stats.detectMiss` reads input, cache-read, and cache-write as
+ * one request's prompt shape (read at pi-coding-agent
+ * `dist/core/cache-stats.js:14-37`). Projecting the turn
+ * aggregate into them fired a false overflow that compacted a live 223k session
+ * on a 1M window, invented two phantom cache misses, and SILENCED the one real
+ * 195,177-token miss the operator needed to see.
+ *
+ * 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.73.0 `dist/acp-agent.js:3273-3297`). Until
+ * that partition is carried on the wire, NOTHING honest can go in pi's four
+ * fields, so entwurf writes none of them.
+ */
+
 // ---------------------------------------------------------------------------
 // The adapter interface
 // ---------------------------------------------------------------------------
@@ -193,6 +217,24 @@ export interface AcpBackendAdapter {
 	 *  sorted-stable primitive map (JSON.stringify determinism — no nested objects /
 	 *  non-deterministic order). `backend` + `nativeModelId` are added by backend.ts. */
 	configSignatureFields(adapterSettings: unknown): Record<string, unknown>;
+
+	/** Declares that THIS backend's `usage_update` cost semantics have been
+	 *  MEASURED, so backend.ts may seal its context occupancy and its per-turn
+	 *  cost from the session baseline.
+	 *
+	 *  ABSENT means no measured semantics — permanent and static, not an omission
+	 *  to fill in by symmetry (cortex). backend.ts then seals NOTHING: no
+	 *  occupancy, no cost baseline, no diff. That is what keeps this lane's
+	 *  accounting out of a backend whose wire meaning nobody has measured.
+	 *
+	 *  This is deliberately NOT a method returning token evidence. It was one
+	 *  until #93 measured that ACP's only token carrier is a turn aggregate that
+	 *  pi's four `Usage` fields cannot honestly hold (see the note above
+	 *  `AcpBackendAdapter`). With no token axis left to extract, presence alone
+	 *  carries everything the seal needs, and a flag that gates only the two axes
+	 *  entwurf actually reads from a NOTIFICATION cannot desync from a response
+	 *  shape it never inspects. */
+	sealsTurnAccounting?: true;
 }
 
 // ---------------------------------------------------------------------------
@@ -297,6 +339,14 @@ export const claudeAdapter: AcpBackendAdapter = {
 		// `_adapterSettings` here.
 		return {};
 	},
+
+	// 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.73.0
+	// `dist/acp-agent.js:2918-2924`). 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,
 };
 
 // ---------------------------------------------------------------------------
@@ -456,6 +506,15 @@ export const cortexAdapter: AcpBackendAdapter = {
 		const settings = adapterSettings as CortexAdapterSettings | undefined;
 		return { cortexConnection: settings?.cortexConnection ?? null };
 	},
+
+	// NO sealsTurnAccounting — a DELIBERATE, permanent absence, not an omission to be
+	// filled in later by symmetry with claude. Nobody has measured what cortex's
+	// ACP `usage` (and its usage_update cost, if it sends one) MEAN: whether the
+	// token counts are a turn delta or a session total, and against which price
+	// table. Until that measurement exists, the honest report is no report:
+	// backend.ts seals nothing for a backend without this flag, so cortex's
+	// emitted usage is byte-identical to what it was before #93. Declaring this
+	// with a guess would mint exactly the silent misaccounting #93 exists to end.
 };
 
 const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter, cortexAdapter];