Deliver bounded inbox bodies for one-inference DING handling

[schickling]

Problem

A normal st2 DING tells a maintained harness that durable unread work exists, but the delivered model input contains only message metadata. The model must therefore spend one inference deciding to fetch bodies before it can interpret and handle the inbox in a later inference.

This is not a missing settlement protocol. st2 message ls --json --include-body already retrieves all selected bodies in one command, and per-file archive receipts are idempotent. Once bodies are present, one model tool invocation can run the existing exact reply/archive commands.

Reproduction

https://github.com/schickling-repros/2026-08-st2-inbox-settlement-overhead

Exact reproduction head: 718f0a84b58484bb69f8367311924965cebe64b9

ST2_BIN=st2 ./repro.sh

At st2 0.1.0+3e01294, the fixture proves:

metadata DING -> inference 1 -> fetch bodies -> inference 2 -> reply/archive
body DING     -> inference 1 -------------------------------> reply/archive

Both paths use the existing CLI and produce the same durable outcome. The extra inference is caused by metadata-only delivery, not by the number of archive subprocesses.

Minimal contract

Maintained provider delivery should include a bounded, ordered slice of exact message filenames and bodies in the next ordinary model input.

• Keep the durable inbox authoritative; delivery never archives.
• Cap each body-bearing delivery by count and bytes.
• Preserve FIFO order and exact filenames.
• Leave oversized, overflow, and post-slice arrivals unread for later delivery.
• Let the model use the existing message reply and message archive commands in one tool invocation.
• Keep the short metadata notification as the fallback for unknown/custom transports.

Do not add a settle command, batch claim, lease, cursor, CAS, journal, retained/deferred disposition state, or admission rejection solely for this efficiency goal. The prototype comparison found that those designs add state and operations without reducing the one-inference/two-crossing target below body-bearing delivery plus the existing CLI.

Implementation boundary

Define one provider-neutral bounded delivery envelope/renderer. The maintained Codex adapter and Claude channel adapter should implement that contract by default. Provider-specific transport remains in the adapters; message selection, caps, ordering, filename/body shape, and delivery evidence remain provider-neutral.

Keep this slice transplantable into the driver extraction tracked by #162: current adapter placement is temporary, while the envelope and tests should move unchanged into the future driver boundary. Reuse the native-delivery stack (#229, #232, #236, #237) instead of creating a parallel path.

Update generated bus/hook guidance to stop prescribing ls plus one read per message and to document --include-body. A root VRS requirement can be proposed, but docs/vrs/requirements.md remains protected pending Nathan's explicit approval.

Acceptance criteria

• A bounded delivery fixture carries ordered exact filenames and bodies within an explicit count/byte cap.
• Oversized, overflow, and post-slice messages remain unread and are delivered later without loss.
• Codex and Claude maintained-provider traces expose bodies before the handling inference; unknown/custom delivery retains the metadata fallback.
• The handling inference can reply/archive the delivered slice through one tool invocation using existing commands.
• A focused compoundingtech/evals A/B records inference/model calls, tool calls, prompt/token bytes, wall time, exact reply/archive outcomes, versions/hashes, and cleanup for cold backlog, during-turn arrival, bounded burst, and post-slice arrival.
• The candidate requires one handling inference where metadata-only delivery requires a discovery inference plus handling inference.
• No new settlement state machine or automatic archive behavior is introduced.

Related work

• message ls --json omits the body, so any list consumer needs one message read spawn per row #20 supplied the existing body-retrieval primitive.
• Add optional turn-boundary + fresh-idle DING without harness parsing in core #111 covers optional turn-boundary/fresh-idle DING policy, not this payload efficiency contract.
• Define Axe harness drivers and extract all harness-specific behavior from st2 core #162 owns the upcoming provider-driver extraction.
• Model-free A/B: hook-plus-idle DING versus aggressive delivery evals#57 owns the broader PTY idle/draft/collision matrix; the Deliver bounded inbox bodies for one-inference DING handling #238 eval should remain focused on end-to-end message efficiency.

[schickling]

Interview decision q1 - milestone boundary

Answer: B - end-to-end first milestone.

The first accepted slice should include the generic bounded intake/settlement protocol, provider turn-boundary injection, VRS/intent requirements, and skill/tooling adoption. A protocol-only slice is insufficient because the stated outcome is that a DING-triggered inbox can actually be processed and settled within one normal turn.

[schickling]

Interview evidence for q2 - settlement authority

The public repro now includes a current-command benchmark and candidate evaluator at commit 0d33ff09ce2bf254c4eb463d348609642e09d455:

https://github.com/schickling-repros/2026-08-st2-inbox-settlement-overhead/blob/0d33ff09ce2bf254c4eb463d348609642e09d455/EXPERIMENTS.md

Observed current samples confirm that body retrieval is bounded, while settlement remains linear: 20 messages used 1 batched read and 20 archive calls; 100 used 1 batched read and 100 archive calls. This is command-count evidence, not a model-token claim.

The paired candidate analysis keeps the same three exact dispositions in both paths. Direct settlement has two core boundaries (intake, settle) and a 199-byte example payload. VRS-intent plus Stop-hook settlement adds an interpreter boundary, a third cross-boundary state transition, and a 237-byte example envelope.

Source review changes the risk assessment materially: current provider SessionStart/Stop hooks render only message metadata and fail open. They neither inject bodies nor own archive/settlement receipts. Therefore a Stop hook cannot safely infer or authorize settlement from ordinary prose or an arbitrary intent artifact without duplicating the core protocol and adding crash/replay correlation state.

Evidence-backed candidate: hooks inject a bounded immutable intake into the next ordinary turn; the model issues one structured core settle request; core returns durable per-entry receipts. VRS should require citations to consequential intent/outcomes, but should not be the transport authority for moving inbox files.

[schickling]

Correction: VRS is documentation discipline, not runtime settlement

The earlier interview notes incorrectly treated a VRS intent artifact as a possible runtime authority for inbox settlement. That is not the proposal.

For this work, VRS means the PR should state and validate the timeless messaging contract in the normal hierarchy: requirements define the one-turn-capable bounded-reconciliation behavior; the spec defines intake, settlement, receipt, retry, and hook integration; experiments retain the benchmark/eval evidence. The runtime path remains messaging/hook/tooling only:

turn-boundary hook -> bounded inbox batch -> structured settlement -> receipt

Task-specific context or intent is independent of this flow and must neither authorize archive movement nor be required to settle a message. The issue body has been corrected accordingly.

[schickling]

Interview correction: choose the globally minimal slice

The earlier issue body and comments proposed an immutable batch plus settle protocol. Follow-up source review and an exhaustive small-state prototype changed that conclusion.

Across 177,155 enumerated transitions per design through depth 5:

design	added state types	added operations	model/tool crossings	inference rounds
metadata guidance + existing CLI	0	0	4	2
bounded body delivery + existing CLI	0	0	2	1
body delivery + minimal settle	2	1	2	1
claim/journal/defer protocol	7	4	2	1

Bounded body delivery reaches the target without new durable state or operations. Existing archive receipts already provide idempotent durable handling, and an arrival after the delivered slice remains unread. The richer protocols solve stronger, separate semantics but do not improve this issue's turn/crossing metric.

This supersedes the q1/q2 settlement direction and the prior hard-admission idea. The agreed scope is now: bounded body-bearing maintained-provider delivery, existing reply/archive commands in one tool invocation, metadata fallback for custom transports, and no new settlement machinery. The edited issue body is authoritative for the implementation and eval.

[schickling]

Minimal implementation and proof stack

The agreed minimal slice is now reviewable:

• st2 draft PR feat(message): deliver bounded inbox bodies #239 at exact head c1a0f90dd4814ec3ce8067219530d7bd8723e191, stacked on Persist Codex typed delivery receipts #237
• compoundingtech/evals draft PR Make Codex workspace trust opt-in in compile-agent #74 at exact head c0d8d4fd0137cb1bdf6b56b448f502d0f11de8ed
• corrected runnable repro at 718f0a84b58484bb69f8367311924965cebe64b9

#239 adds one provider-neutral 16-message/16-KiB read-only JSON view, consumes it through Codex app-server and Claude SessionStart/UserPromptSubmit, and leaves reply/archive receipts unchanged. It adds no settlement state machine. The adapter consumers are deliberately thin for the #162 driver extraction.

#74 runs one identical mixed-provider cell against exact #237 baseline and #239 candidate binaries. Free gates are green; live provider A/B remains pending the repository-required explicit paid-run approval, so neither PR claims the one-inference result yet.

[schickling]

End-to-end provider A/B complete

The focused proof stack now has a matched real-provider result:

• st2 candidate PR feat(message): deliver bounded inbox bodies #239: c1a0f90dd4814ec3ce8067219530d7bd8723e191
• eval PR eval: prove one-turn inbox delivery evals#74: 0e6b64ebdc652687926d43f4a41a955831ddd846
• tracked receipt: https://github.com/compoundingtech/evals/blob/0e6b64ebdc652687926d43f4a41a955831ddd846/evidence/inbox-one-turn-provider-ab-runs-20260811.json

metric	#237 baseline	#239 candidate	change
held-out outcome	FAIL, 3/4	PASS, 4/4	exact bodies handled
Codex total tokens	535,286	227,871	-57.43%
Codex model-response events	17	7	-58.82%
Codex tool-call boundaries	11	4	-63.64%
Codex wall time	115.367 s	45.676 s	-60.41%
Claude token volume	367,011	319,857	-12.85%
Claude session duration	114.706 s	45.315 s	-60.49%

The candidate handles the two-message cold backlog, Codex three-message active burst, and post-batch arrival using the existing reply/archive authority. No settle/claim/lease/cursor state machine was needed. The canonical Agent Spec fixture and provider-neutral envelope keep the acceptance contract transplantable across the #162 driver refactor.

Evidence caveat: both provider executions completed, but the original judge launcher exited 127 due a relative-path bug. The tracked receipt records that axis explicitly. Corrected held-out graders deterministically return semantic FAIL for the preserved baseline catalog and PASS for the preserved candidate catalog; the original judge invocation is not represented as green.