@junghanacs/entwurf 0.16.1 → 0.17.2

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

@@ -61,12 +61,17 @@ export interface DispatchExecutorDeps {
 }
 
 /** The per-transport success outcome, discriminated by transport so the surface renders
- * each without guessing. `control-socket` carries the optional N3 `rejectReason`;
+ * each without guessing. `control-socket` carries the optional N3 `rejectReason` and,
+ * when a dead-socket re-resolve fell back to the mailbox, that leg's #98 R `messagePath`;
  * `meta-mailbox` is always `success:true` (enqueue has no in-band refuse — a failure is
- * a throw, handled as `execution-failed`). */
+ * a throw, handled as `execution-failed`) and carries the #98 R send receipt: the path of
+ * the `.msg` the enqueue actually wrote. OPTIONAL because a fake/legacy `sendMailbox` dep
+ * may omit it — a missing receipt must degrade the rendered line, never fail the delivery,
+ * and it is the ONLY enqueue-side datum carried (never a read timestamp; see
+ * `RpcSendResult`). */
 export type ExecutedOutcome =
-	| { transport: "control-socket"; outcome: SendFinalOutcome; rejectReason?: string }
-	| { transport: "meta-mailbox"; success: true }
+	| { transport: "control-socket"; outcome: SendFinalOutcome; rejectReason?: string; messagePath?: string }
+	| { transport: "meta-mailbox"; success: true; messagePath?: string }
 	// native-push carries `retried` so the surface can note the 1-shot re-probe retry fired.
 	| { transport: "native-push"; success: true; retried: boolean };
 
@@ -118,7 +123,12 @@ export async function executeDispatch(
 					kind: "executed",
 					receipt,
 					transport,
-					outcome: { transport: "control-socket", outcome: r.outcome, rejectReason: r.rejectReason },
+					outcome: {
+						transport: "control-socket",
+						outcome: r.outcome,
+						rejectReason: r.rejectReason,
+						messagePath: r.messagePath,
+					},
 				};
 			} catch (err) {
 				// N1: a delivered/refused send whose release then threw — lock dirty, do NOT retry.
@@ -150,7 +160,14 @@ export async function executeDispatch(
 						"entwurf-v2-runner: meta-mailbox send returned success:false (contract violation; a mailbox has no in-band reject).",
 					);
 				}
-				return { kind: "executed", receipt, transport, outcome: { transport: "meta-mailbox", success: true } };
+				return {
+					kind: "executed",
+					receipt,
+					transport,
+					// #98 R: carry the enqueue receipt verbatim. `undefined` stays `undefined` —
+					// the runner never substitutes a guessed path for a missing one.
+					outcome: { transport: "meta-mailbox", success: true, messagePath: r.messagePath },
+				};
 			} catch (err) {
 				return { kind: "execution-failed", receipt, transport, error: errorMessage(err), retrySafe: false };
 			}

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

@@ -52,10 +52,20 @@ export type MetaMailboxPlan = Extract<ExecutionPlan, { transport: "meta-mailbox"
 export type SendFinalOutcome = "sent" | "fallback-sent" | "rejected" | "failed";
 
 /** What a single RPC / mailbox enqueue reports. `success:false` is an in-band reject
- * (the receiver answered and refused) — distinct from a thrown connect error. */
+ * (the receiver answered and refused) — distinct from a thrown connect error.
+ *
+ * `messagePath` is the SEND-side receipt (#98 R) and is OPTIONAL because only the
+ * mailbox rail has one: an enqueue writes a file, so there is a per-message artifact
+ * to name. A control-socket RPC hands the body to a live receiver and produces no
+ * file, so it leaves this undefined rather than inventing one. It carries the ENQUEUED
+ * path and NOTHING about reading: `lastReadAt` at enqueue time is the PREVIOUS
+ * message's read stamp, so surfacing it here would read as "my message was read" —
+ * the exact misreading #98 opened on. The per-message read receipt is the `.read`
+ * suffix on this very file, never a state.json slot. */
 export interface RpcSendResult {
 	success: boolean;
 	error?: string;
+	messagePath?: string;
 }
 
 /** The same-lock one-shot re-resolve result (5c-2b implements the resolver; 5c-2a
@@ -98,6 +108,14 @@ export interface ControlSocketSendResult {
 	 * 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. */
 	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
+	 * control-socket retry hands the body to a live receiver and writes no file, so it
+	 * leaves this undefined rather than inventing one. Same rule as `RpcSendResult`: the
+	 * ENQUEUED path and nothing about reading. Without it a `fallback-sent` is the one
+	 * mailbox delivery whose sender gets no per-message identifier — the same letter the
+	 * primary mailbox rail names. */
+	messagePath?: string;
 }
 
 // A drive step's verdict: the terminal outcome, plus the original error to RETHROW on
@@ -107,6 +125,8 @@ interface SendDrive {
 	outcome: SendFinalOutcome;
 	error?: unknown;
 	rejectReason?: string;
+	/** #98 R receipt from the mailbox fallback leg (see `ControlSocketSendResult`). */
+	messagePath?: string;
 }
 
 /**
@@ -139,7 +159,7 @@ export async function executeControlSocketSend(
 		drive = { outcome: "failed", error: err };
 	}
 	finalizeRelease(policy, deps, held, drive);
-	return { outcome: drive.outcome, rejectReason: drive.rejectReason };
+	return { outcome: drive.outcome, rejectReason: drive.rejectReason, messagePath: drive.messagePath };
 }
 
 /** Drive the 1차 send and route a connect failure through the F3 split. */
@@ -208,7 +228,10 @@ async function driveDeadFallback(
 			// hand never reaches for the mailbox on its own; only the resolver routes here.
 			try {
 				const r = await deps.sendViaMailbox(rePlan, lock);
-				return { outcome: r.success ? "fallback-sent" : "rejected" };
+				// #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" };
 			} catch (err) {
 				return { outcome: "failed", error: err };
 			}

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

@@ -19,6 +19,7 @@
  *     surface never needs to name the `EntwurfV2RunResult` union (it only sees `{text,isError}`).
  */
 
+import { basename } from "node:path";
 import type { SenderEnvelope } from "./entwurf-control-rpc.ts";
 import type { DispatchInput, EntwurfV2Mode } from "./entwurf-v2-decider.ts";
 import { makeProductionEntwurfV2Deps, type ProductionEntwurfV2Opts } from "./entwurf-v2-production.ts";
@@ -144,8 +145,13 @@ export function renderEntwurfV2Result(result: EntwurfV2RunResult): EntwurfV2Surf
 			if (o.transport === "control-socket") {
 				const delivered = o.outcome === "sent" || o.outcome === "fallback-sent";
 				const reason = o.rejectReason ? ` (reason: ${o.rejectReason})` : "";
+				// #98 R, fallback leg: a dead socket that re-resolved to the mailbox wrote a
+				// `.msg` — name it, exactly as the primary mailbox rail does. Absent on a
+				// socket-to-socket retry (no file) and on every non-mailbox outcome, so the
+				// line degrades to the bare outcome rather than printing "undefined".
+				const enqueued = o.messagePath ? ` (enqueued ${basename(o.messagePath)})` : "";
 				return {
-					text: `entwurf_v2 control-socket → ${o.outcome}${reason}`,
+					text: `entwurf_v2 control-socket → ${o.outcome}${reason}${enqueued}`,
 					isError: !delivered,
 				};
 			}
@@ -156,8 +162,17 @@ export function renderEntwurfV2Result(result: EntwurfV2RunResult): EntwurfV2Surf
 					isError: false,
 				};
 			}
-			// meta-mailbox
-			return { text: "entwurf_v2 meta-mailbox → enqueued", isError: false };
+			// meta-mailbox. #98 R: name the FILE that was enqueued, so the sender's transcript
+			// carries a per-message identifier instead of a bare literal. Only the basename —
+			// the directory is `<meta-mailbox>/<target garden id>/`, which the caller already
+			// typed. Deliberately NOT a read stamp: at enqueue time `lastReadAt` belongs to the
+			// PREVIOUS message, so printing it would claim a read that has not happened.
+			// A dep that omits the receipt falls back to the old literal rather than printing
+			// "undefined" — the delivery still happened.
+			return {
+				text: `entwurf_v2 meta-mailbox → enqueued${o.messagePath ? ` (${basename(o.messagePath)})` : ""}`,
+				isError: false,
+			};
 		}
 		case "execution-failed": {
 			if (result.releaseFailed && result.finalizedOutcome) {

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

@@ -2532,9 +2532,17 @@ export interface ReadMetaInboxResult {
  * 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: ReadMetaInboxOptions): ReadMetaInboxResult {
 	const now = opts.now ?? new Date();
@@ -2560,10 +2568,18 @@ export function readMetaInbox(opts: ReadMetaInboxOptions): ReadMetaInboxResult {
 		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
@@ -2603,6 +2619,15 @@ export const MAILBOX_RECEIPT_SCHEMA_VERSION = 1 as const;
  * The per-citizen mailbox receipt state. Holds exactly the three delivery
  * timestamps that move out of `record.delivery` (wakeMode/deliveryLevel are
  * capability, deliberately absent). Body is SSOT; the on-disk path is derived.
+ *
+ * SCOPE (#98 5a): these are GARDEN-WIDE "last activity" slots, single-valued and
+ * overwritten — NOT per-message receipts. Per message, the receipt is the file
+ * suffix in the same directory (`.msg` → `.msg.delivered` → `.msg.delivered.read`).
+ * `lastEnqueuedAt`/`lastReadAt` are stamped by `enqueueMetaMessage`/`readMetaInbox`.
+ * `lastDeliveredAt` is stamped by NOBODY: the doorbell does not write state.json, so
+ * it is a reserved slot that is null everywhere. Kept rather than removed because the
+ * parser is doubly strict (exact schemaVersion + no unknown keys) and every stamp
+ * re-parses, so dropping it is a migration over the existing on-disk v1 files (#98 5b).
  */
 export interface MailboxReceiptState {
 	schemaVersion: typeof MAILBOX_RECEIPT_SCHEMA_VERSION;

package/run.sh

@@ -2700,6 +2700,24 @@ check_acp_event_mapper() {
   run_ts scripts/check-acp-event-mapper.ts
 }
 
+check_acp_usage_accounting() {
+  # Deterministic gate for the ACP USAGE ACCOUNTING contract (#93). A long-lived
+  # Claude ACP session's dashboard read 10-18x high on three live ledgers,
+  # because the per-turn token partition was dropped at the type boundary while
+  # the backend's RUNNING SESSION TOTAL was assigned to a per-turn cost field pi
+  # then summed. Drives streamAcpTurn against a fake ACP child + connection whose
+  # turns are scripted (usage_update notification + PromptResponse.usage) for
+  # five cells: the four-way token partition reaches the pi message; per-turn
+  # costs are adjacent diffs of the running total and sum back to it across a
+  # reused session; a turn with no cost notification attributes $0 and HOLDS the
+  # baseline; a decreasing total rebaselines, attributes $0 and tells the
+  # operator; totalTokens stays CONTEXT OCCUPANCY (asserted through pi's own
+  # calculateContextTokens) and carries forward; and cortex — no measured
+  # extractor — keeps its pre-#93 output untouched.
+  section "ACP usage accounting (turn partition + adjacent-diff cost)"
+  run_ts scripts/check-acp-usage-accounting.ts
+}
+
 check_acp_stop_reason() {
   # Deterministic gate for the ACP stop-reason contract. Drives every member of
   # the closed ACP terminal set (end_turn / max_tokens / max_turn_requests /
@@ -6520,6 +6538,9 @@ case "$cmd" in
   check-acp-event-mapper)
     check_acp_event_mapper
     ;;
+  check-acp-usage-accounting)
+    check_acp_usage_accounting
+    ;;
   check-acp-stop-reason)
     check_acp_stop_reason
     ;;

package/scripts/check-acp-stop-reason.ts

@@ -2,8 +2,14 @@
 //
 // WHAT THIS EXISTS TO STOP. `mapPromptStopReason` used to be a bare
 // `switch` returning a StopReason with `default: return "stop"`. The ACP terminal
-// set is closed — `@agentclientprotocol/sdk` 1.3.0 `schema/types.gen` declares
-// `end_turn | max_tokens | max_turn_requests | refusal | cancelled` — so that
+// set is closed — `@agentclientprotocol/sdk` 1.4.0 `dist/schema/types.gen.d.ts:3001`
+// declares `end_turn | max_tokens | max_turn_requests | refusal | cancelled`, with
+// no `| string` arm. Re-measured at the 1.3.0 → 1.4.0 bump rather than inherited,
+// because 1.4.0 also ships a SECOND, OPEN union at `dist/v2/schema/types.gen.d.ts:3607`
+// (`… | "cancelled" | string`). That one is reachable only through the
+// `./experimental/v2` export; entwurf imports the BARE specifier, which the package
+// `exports` map sends to `./dist/acp.js` — the closed v1 surface. The claim holds
+// only while that import stays bare, so a move to the v2 export retires it — so that
 // default silently collapsed THREE distinct non-success outcomes into a clean
 // successful turn:
 //