Configuration and operation

Measured results live only in the consolidated report.

Run

bun install
# For a new setup only; preserve an existing .env and its credentials.
cp .env.example .env
bun run start

Set AI_GATEWAY_API_KEY in .env to enable Jev. Existing installations should compare their policy overrides with .env.example; the key does not need to change. Without a key, a fresh session forwards unchanged; existing sticky omissions still replay. YOSHI_DRY_RUN=1 evaluates and logs decisions but leaves requests unchanged.

Point a separate Claude Code session at the loopback proxy:

ANTHROPIC_BASE_URL=http://127.0.0.1:8790 claude

The default is sticky arrival selection, with YOSHI_CONTEXT_SCOPE=conversation and YOSHI_CONTEXT_LIFECYCLE=sticky. Decisions are made once, before a new span is forwarded. Every later request replays the same omission. Human instructions, assistant notes and completed call/result envelopes stay present. Native client compaction remains available.

YOSHI_MIN_CONTEXT_TOKENS=50000 skips new judgments below a heuristic size gate (UTF-8 request bytes divided by four). It is not a provider token count or a model-window percentage. Set it for the deployment; 0 disables the gate for diagnostics. Cached omissions still replay below the gate. Below-gate, oversized, over-budget, failed and dry-run spans are frozen as retained, not reconsidered later.

Completed inputs and reports use complete-line spans targeting 1,200 characters. Each input judgment includes its paired result; the result is then protected from concurrent pruning. All calls include a chronological role/tool/path/completion skeleton under the 24,000-byte guard. Unshown content never proves coverage. Results keep the prior Atomic operating point: relevance <= 0.2 or coverage >= 0.7, with conflict <= 0.2. Inputs/reports require both missing-information and missing-constraint probabilities <= 0.2.

For the historical experiments only, use YOSHI_CONTEXT_LIFECYCLE=snapshot. Mixed histories may then be reclassified and rewritten retroactively, and Fable may be sent a reasoning-drop policy. This bypasses the new size gate. YOSHI_CONTEXT_SCOPE=tools selects the earlier tool-only implementation, also outside the sticky lifecycle; its Atomic/Choice/legacy controls retain their prior behavior. Neither option has the default's prefix-stability contract.

The earlier deterministic behavior is still available:

YOSHI_JUDGE=0 YOSHI_COMPACT_JSONL=1 YOSHI_DEDUPLICATE=1 bun run start

That is a separate mechanism. Historical deterministic results and Headroom research remain for comparison.

Lifecycle and reasoning

1. Resolve unique completed pairs. Protect errors, pending calls, unknown metadata and opaque blocks. Only the latest arriving tool cycle or report can receive a new judgment; imported older history stays intact.
2. Hash the original prefix, authentication identity, model, system, tools and policy. Append-only human follow-ups do not invalidate prior decisions. Changed source bytes branch the decision namespace. Moving cache markers and request telemetry do not expire decisions.
3. Replay earlier omissions first, then build the new judge state from what the model actually receives. Hidden original text cannot become a witness for deleting new evidence.
4. Freeze keeps and omissions, including timeout, work-budget, size-gate and dry-run outcomes. Concurrent identical requests serialize decision commits. Ordinary logs contain metadata only; the decision store persists hashes and verdicts, never raw source or credentials.
5. Preserve every signed/opaque block and protect content at or before the newest such block from new edits. Reapply known earlier omissions exactly. The default never adds drop_block, changes a caller's thinking controls or adds a beta header. Provider transformations remain observable in logs.
6. Receipts identify sticky-arrival and include the estimated size, gate state, reused verdict count, reasoning boundary, per-kind changes, Jev calls/usage and provider usage.

The store retains at most 10,000 entries for seven days; active replay refreshes a verdict's age. Restart continuity requires the same YOSHI_DECISIONS file, policy and prefix. Expiry, eviction, loss of the store, an upstream/model/system/tool change or switching lifecycle modes can restore original content and invalidate provider caches or signed reasoning. Use a fresh or natively compacted session across such resets. This POC does not promise durable session migration. Client changes to old messages are outside the proxy's append-only guarantee.

Originals remain with the client, but sticky mode deliberately does not restore old omissions when the user changes topic. A future exact quote may therefore require source recovery; external files may have changed. The judge cannot read encrypted reasoning or predict future instructions. No automatic retroactive break-even rule is enabled: future session length is unknown, and a cache-cost estimate alone cannot justify losing reasoning. Native context management is the explicit comparator for historical clearing.

Transport, privacy and optional transforms

The server binds 127.0.0.1. Authentication and protocol headers pass through; upstream response bytes stream unchanged. POST /v1/messages and Responses creation requests use their respective adapters; auxiliary routes pass through, including token counts and Responses compaction. Client-only system-role messages remain present. The proxy has no independent authentication.

Jev-enabled requests send candidate text and selected user/assistant context to TypeSafe through Vercel. No ZDR option is requested. Ordinary logs and the decision store contain metadata only. The explicit benchmark additionally saves raw local traces in ignored .yoshi/ directories, including incoming and forwarded requests. These may contain private client hints and must not be published wholesale. Credentials are never logged. History fixtures are a reviewed subset of public-research tool outputs, not a bulk upload of ~/.claude.

Optional JSONL compaction preserves every source record, value and order and requires an exact byte round trip. Exact duplicate removal references an earliest full copy. Both operate independently of Jev and have separate counters. They are disabled in the current default and all Jev-only comparisons.