carthagent 0.0.0-stage → 1.1.0-preview.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 B-icy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,221 @@
-# Temporary Holding Version
+# Carthagent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Carthagent checks software work against real acceptance tests and re-proves it whenever source changes.
+
+## Install
+
+```sh
+curl -fsSL https://carthagent.xyz/install | sh
+irm https://carthagent.xyz/install.ps1 | iex
+npm install -g carthagent
+```
+
+Node.js 22.19+ is required for the npm install. From source: `npm install -g --install-links=true github:B-icy/Carthagent#vX.Y.Z` (replace with a published tag).
+
+See [workflow.svg](docs/workflow.svg) for the flow and [evaluation history](docs/evaluation.md) for trials, including failures.
+
+## Native CLI
+
+```sh
+ctg
+ctg --help
+ctg native  # compatibility alias
+```
+
+The old `CTG_NATIVE` toggle no longer changes routing. The native route launches the checksum-pinned CTG-owned runtime (compatibility 2.0.32) and uses a separate Carthagent-owned profile beneath `~/.carthagent/opencode/` (override with `CTG_OPENCODE_HOME`). Its config, database, sessions, auth, state, and cache are separate from other coding-tool profiles. It does not install, upgrade, or reuse credentials from other coding-tool profiles. Project files and native task metadata/worktrees are separate again: task records live in each project’s `.harness/opencode-tasks.json`.
+
+Native projects use the native project/session model. CTG task creation associates a task with an independent native session and native worktree; task relations are CTG metadata, not parent/child native sessions. Native session resume/continue is scoped to the active workspace. Legacy Pi transcripts can be listed, searched, read, and exported with `ctg archive`; they are **read-only archives** and cannot be resumed or imported as native sessions. See the [native upgrade and migration guide](docs/native-upgrade.md) before switching workflows.
+
+The native TUI exposes CTG workspace/task actions such as `/ctg-workspace`, `/ctg-open`, `/ctg-worktree`, and `/ctg-task`, alongside delivery and session commands. The native runtime owns the terminal renderer and lifecycle. Do not assume a listed command overrides a built-in host command: submitted `/help` precedence is a known unresolved acceptance gate.
+
+```sh
+node bin/ctg.mjs                         # native interactive TUI
+node bin/ctg.mjs "Build a task CLI"      # task in the TUI
+node bin/ctg.mjs resume                  # native session picker
+node bin/ctg.mjs continue                # latest native session here
+node bin/ctg.mjs -p "Summarize this repo" # headless text
+node bin/ctg.mjs --json -p "Run checks" # native lifecycle JSONL
+node bin/ctg.mjs status --json           # delivery status JSON
+node bin/ctg.mjs archive list            # legacy archive (read-only)
+```
+
+The native CLI retains command aliases such as `ui`/`interactive`, `sessions`, `s`, `c`, `fingerprint`, `auth`, `cloud`, `web`, `start`, and `upgrade`. `--json` with a headless prompt emits JSONL records for native tool start/end, assistant message completion, and terminal outcome; it is not the text `-p` stream. Headless success requires the native completed assistant turn and successful terminal outcome. Options whose enforcement is not advertised by the active native plugin fail closed; in particular `--bash-cap` and `--isolate` are currently unsupported. Refer to [native CLI compatibility details](docs/native-cli.md).
+
+### Voyages in the native TUI
+
+`/voyages` opens the account's live Voyages profile, coin wallet, equipment and
+shop. Use the normal `/login` browser device approval and choose Carthagent;
+Voyages uses the approving browser user's existing player, not a separate CLI
+wallet. Older account-only Ship sessions may require a new device sign-in.
+Voyages does not require a paid model call or award coins for coding.
+
+Customization and equipment changes require confirmation. Paid items require a
+server quote showing the coin price and expiry, followed by explicit purchase
+confirmation. Cancel does not purchase. The server validates funds, ownership,
+eligibility and profile version; refresh after a conflict rather than silently
+overwriting another client. Equip a purchased item separately.
+
+If a purchase response is lost, the TUI keeps a pending request across restart.
+Use its recovery action to retry the same quote and request key, not to create
+a second purchase. Do not delete profile state to resolve an uncertain debit.
+The server remains authoritative; unavailable or signed-out state must not be
+treated as a saved balance. Browser cookies are never imported into CLI auth.
+
+Native Voyages landed in PR #225. Live development-runtime testing exercised
+browser device approval, name cancel/save, owned Beanie equip, restart and web
+persistence, expiry recovery, and revocation. The approving web player remains
+authoritative. The tested wallet had 10 coins and no affordable paid quote:
+no live paid debit or replay was proven. These are historical, bounded source/runtime
+results, not preview.10 installed-package acceptance. Subsequent development-runtime
+testing completed one explicitly authorized 40-coin purchase and restart
+persistence; see the [preview.10 candidate notes](docs/release-notes-preview.10.md)
+for its limits. Published preview.9 remains immutable and does not acquire
+changes from current main.
+
+## Install and update
+
+The installer selects an exact published release and acquires its pinned native runtime; it never falls back to an unrelated system binary. See the [native upgrade guide](docs/native-upgrade.md) for source-checkout and profile-preservation instructions, or [legacy CLI instructions](docs/legacy-cli.md) for stable 1.0.7.
+
+`ctg update --check` checks for a published release without installing. Select `--channel experimental` to include published previews; drafts are never installed. The legacy stable updater can update a clean source clone. The native updater differs: it refuses to check out a release into any active source clone, including a clean one; it installs package releases only from an npm installation. Preserve local changes and use the manual exact-tag checkout procedure in the [native upgrade guide](docs/native-upgrade.md) when updating a development checkout. Published previews are immutable. See the [preview.11 release notes](docs/release-notes-preview.11.md); the older [native migration draft](docs/release-notes-native-draft.md) is historical, not current installation guidance.
+
+## Update channels
+
+Starting with 1.0.7, update channels are an explicit opt-in:
+
+```sh
+ctg update --channel experimental --check  # preview; installs/persists nothing
+ctg update --channel experimental          # install and remember the experimental channel
+ctg update --channel beta                  # stable + beta/RC releases only
+ctg update --channel stable                # leave previews; downgrade to stable if necessary
+ctg update                                # follow the channel you last installed successfully
+```
+
+Stable is the default and never selects a prerelease, even if a remote manifest
+mislabels it. Beta accepts published `-beta` and `-rc` tags; experimental also
+accepts alpha, preview, and other published prerelease tags. Both opt-in channels
+include stable releases. Selection uses semantic version order, not release date;
+drafts are never installable. Prereleases are read directly from GitHub and never
+advance the stable control-plane pointer.
+
+A successful explicit switch is saved in `~/.carthagent/update-channel.json`;
+`--check` and failed installs do not change it. `CARTHAGENT_UPDATE_CHANNEL_FILE`
+can isolate this preference for testing. `--channel stable` explicitly authorizes
+a downgrade, so recovery from an experimental build does not require `--force`.
+Your sessions and provider credentials are not deleted by switching channels.
+Experimental software may still contain bugs; read its release notes first.
+
+## Release status
+
+1.1.0-preview.12 is the current experimental release. It republishes
+preview.11 with an npm package that keeps the `ctg` command, plus a release
+check that blocks manifests npm would rewrite. Preview.11 added a Projects /
+Voyages mode switch to the native left rail, with read-only Voyages profile and
+daily assignment summaries, on top of preview.10's native daily coding quests
+(selected evidence, exact-payload preview, fresh per-submission consent, and
+durable recovery; assessments do not award rewards). Native remains the default
+`ctg` interface. Ship retains approval, checks, review, repair, recovery, and
+resume; Lite remains direct execution. Published previews are immutable.
+Experimental installation is explicit and selects published releases only;
+stable 1.0.7 retains the legacy console.
+
+Each experimental release must pass its exact installed-package gate before
+publication. See the [preview.12 release notes](docs/release-notes-preview.12.md),
+[preview.11 notes](docs/release-notes-preview.11.md), and [preview.10 notes](docs/release-notes-preview.10.md); earlier migration findings and remaining platform caveats
+are in the [Native migration ledger](docs/opencode-migration.md#delivery-ledger),
+[native compatibility matrix](docs/native-compatibility.md), and [terminal
+evidence status](docs/native-terminal-semantics.md#evidence-status-pr-162).
+
+## Regular CLI
+
+The split-terminal console remains available in stable 1.0.7, not as an alternate route inside the native-default experimental package. To return to stable, use `ctg update --channel stable`. Its legacy data and provider setup remain distinct from the native profile; existing transcripts remain available through the read-only archive commands.
+
+## Delivery engine and existing CLI
+
+The following delivery-engine documentation describes Carthagent's shared delivery concepts and the existing CLI behavior. Native-preview coverage and compatibility are tracked separately in the [native CLI guide](docs/native-cli.md) and [migration ledger](docs/opencode-migration.md); feature parity must not be inferred from the presence of a shared delivery module.
+
+## How it works
+
+`extensions/delivery.ts` wires eight tools into the engine (`lib/delivery.mjs` has the mechanics):
+
+| Tool | What it does |
+|---|---|
+| `delivery_plan` | Goal, steps, artifact roots, acceptance criteria → check mapping; `verification: required|advisory|none`; writes `plan.d2` |
+| `delivery_design` | Validate SRP/DI contracts and scenarios, record adversarial review, approve the exact revision/snapshot before code |
+| `delivery_revise` | Reason + partial plan patch; preserves valid evidence and stable progress, records revision history |
+| `delivery_check` | Runs check argv with deadlines; `all` collects ordinary failures across suites; records exit codes, logs, workspace SHA-256 |
+| `delivery_status` | Contract + evidence state (missing/failed/stale) |
+| `delivery_progress` | Step progress for the plan panel |
+| `delivery_review` | Captures the actual diff; records per-requirement assertions, boundary probes and limitations against the unchanged snapshot |
+| `delivery_finish` | `verified` requires fresh checks, new-requirement executions, existing artifacts/output files, completed structured steps and a review receipt; otherwise `blocked` |
+
+The discipline: evidence is bound to the run, contract revision, executable check definition and workspace source fingerprint. Source edits invalidate evidence; dependency, cache and generated-output exclusions mean this is not a hash of every file. `verified` means declared required checks passed with current evidence—not independent proof of task completeness or correctness. Checks are real subprocesses (`argv`, no implicit shell), FIFO-queued, 1–300 s deadlines, logs under `.harness/`. Failed or missing checks get at most two automatic repair nudges per prompt. This is a workflow guardrail, not a security sandbox — for untrusted code use a container.
+
+`extensions/codegraph.ts` adds a `code_nav` tool: a deterministic tree-sitter index of the workspace (JS/TS/Python/Rust) with ops `definition`, `symbols`, `callers`, `callees`, `imports`, `importers`, `outline`, `status`. It parses lazily on first call and re-parses only files whose mtime changed; `--codegraph-max-files N` caps the scan (default 8000).
+
+Structural navigation is available before plan approval. Results report total/returned matches, `nextOffset` pagination and current coverage; `path`/`container` narrow candidates. Call matches are name-based, not resolved runtime bindings. Use graph discovery followed by targeted source reads. Delivery guidance is phase-specific and recovery uses exact-obligation checkpoints plus current evidence; see [graph/context optimization](docs/graph-context-optimization.md) for behavior and pilot limitations.
+
+**Choose the workflow.** The CLI defaults to `--workflow standard`: declare a complete acceptance contract and executable checks, implement, then run fresh checks and record a final snapshot review before finishing. `--workflow strict` additionally requires architecture/injection contracts, scenarios and tested-design approval before implementation; revisions relock that mode. Existing sessions keep their recorded mode, and direct extension hosts default to strict for compatibility. `delivery_probe` offers bounded Node/npm version discovery. This is a participating-tool boundary, not an OS sandbox. See [workflow modes and benchmark findings](docs/workflow-modes.md) and [strict design contracts](docs/tested-planning.md).
+
+**Optional advisory research.** A dependency-injected Jev adapter and shadow evaluator are available off the normal delivery path. No credentials or provider call are required; classifier outputs cannot approve plans. See [measured fixture results and live-evaluation limits](docs/plan-advisor-evaluation.md).
+
+**Adaptive plans.** Steps can be legacy strings or `{id,title,dependsOn:[],checks:[]}`. Structured steps use stable IDs, enforce dependency order, and require mapped checks before completion. `delivery_revise({reason,patch})` keeps omitted fields and replaces supplied arrays; unchanged checks retain fresh evidence only on unchanged source. New/remapped requirements still need new suite executions; old command evidence cannot automatically cover newly stated behavior. Intentionally-red regression milestones use `kind:"regression",checks:[]`, keeping green suites on final acceptance. Structured required plans must inspect/record a final diff-linked review. Changed source still invalidates all workspace evidence. Revisions preserve failure history and acceptance criteria rather than resetting the contract. See [medium/large-codebase workflows and limits](docs/planning.md).
+
+**Headless monitoring.** `ctg --json -p "task"` streams engine JSONL events, including tool activity; `ctg status --json` returns a versioned report/fingerprint/completion snapshot. Text `-p` alone is not a live tool stream. Review receipts are traceable self-reports, not independent correctness proof.
+
+**Informational vs delivery asks.** Every plan declares a verification classification. `required` (the default) is the delivery contract above. `advisory` retains optional informational evidence without a repair loop; it does not authorize new arbitrary command execution. New commands require a tested, approved `required` plan. `none` is a pure question/explanation with no checks at all. Informational plans finish with `delivery_finish` once (recorded as `advisory: true`) and never receive repair nudges; user-owned required validators always force `required`, and a `required` plan can only be reclassified before any check has run.
+
+## Self-review
+
+When a run finishes a substantial change (a verified delivery or file edits), Carthagent can offer a review loop: the agent pushes a branch, opens a PR, and a **detached fresh-context reviewer** (`ctg review <pr>` — a separate engine process with no shared context) inspects it. Findings come back to the working agent, which fixes, pushes, and re-reviews — stopping after 3 admitted attempts per PR in this workspace or `VERDICT: APPROVE`. The CLI persists round admission and structured snapshot-bound findings, excludes concurrent reviewers, and escalates exhausted attempts. Review commands reject malformed verdicts and changed source/PR-head snapshots, but read-only behavior is an instruction, not isolation. See [review guarantees and limits](docs/review-assurance.md).
+
+It's opt-in and tri-state, resolved as `--review <mode>` flag → `~/.carthagent/config.json` → `ask`:
+
+| Mode | Behavior |
+|---|---|
+| `ask` (default) | Offer the loop at the end of a major change (`^y` accepts, `esc` skips) |
+| `yes` | Start the loop automatically — no prompt |
+| `no` | Never offer |
+
+```sh
+ctg review                   # show the effective default
+ctg review yes               # persist a default for all sessions
+ctg review 14                # run the fresh-context reviewer over a PR directly
+ctg --review no              # per-launch override
+```
+
+Inside a session, `/review` starts a loop immediately and `/review ask|yes|no|status` manages the same default. The loop needs `git` + an authenticated `gh` — without them the agent reports and skips instead of simulating a review.
+
+## Make it yours
+
+Everything below is config, not code:
+
+- **Required validators** — your tests, not the model's. `.carthagent/delivery.json` (trusted project) or `--validators file.json`: `{"version":1,"checks":[{"id":"acceptance","kind":"test","argv":["pytest","-q"],"timeoutSeconds":90}]}`. They can't be omitted or overridden.
+- **Domain guidance** — add a JSON profile to `guidance/profiles/` (keywords/deps → planning/check/review requirements) and matching requests pick it up automatically.
+- **Extra context** — `--delivery-context notes.md` injects project/benchmark-specific instructions.
+- **Scenarios** — `scenarios/<name>/scenario.json` defines an evaluation domain; `node evaluate.mjs --task <name> --allow-live` runs it (dry-run with `--dry-run`; spends API credit otherwise).
+
+See [extending Carthagent](docs/extending.md) for how to author guidance profiles, prompt templates, skills, providers, and extensions.
+
+## Bounded runs and browser evidence
+
+```sh
+ctg -p --max-tools 100 --max-seconds 900 --max-repairs 2 "Implement the requested change"
+```
+
+Limits are opt-in, session-persistent cooperative controls—not dollar/token caps or hard process deadlines. Inspect with `/delivery-budget-status`; only an explicit `/delivery-budget-reset` starts a fresh allowance in the same session. See [session budgets](docs/budgets.md).
+
+Browser evidence has two tiers: jsdom for DOM/unit checks (module scripts are rejected when execution is requested), and a real headless browser (bundled `chrome-headless-shell` over CDP, or an external WebDriver endpoint) for application modules and interactions. Browser checks subscribe to console errors before navigation and fail on unexpected console errors, exceptions and rejected promises. Screenshots are evidence to inspect, not automatic visual approval. See [browser setup and checks](docs/webdriver.md).
+
+## Development
+
+```sh
+npm ci && npm run quality                  # lint, typecheck, build and tests; no model calls
+npm run test:browser                       # bundled headless browser (auto-downloads on first use)
+python3 -m pip install -r scenarios/game/requirements.txt && npm run test:python   # game graders
+# Only with explicit spending authorization and a cap:
+node evaluate.mjs --task cli --mode both --allow-live   # live A/B eval — spends API credit
+```
+
+Tests cover contract validation, stale evidence, required validators, timeouts/cancellation, compaction, actual-engine session budgets, report conflicts, and dashboard auth. Native CI covers Windows/macOS/Linux on Node 22/24; a separate Linux job runs the bundled real-browser suite. WSL JS/browser evidence is local and separate; WSL Python validation remains unperformed successfully. This does not establish all terminals or browsers as supported/tested. `PI_CLI` points the suite at a non-standard engine location.
+
+See [repository quality gates](docs/quality.md) and [controlled evaluation readiness](docs/evaluation-readiness.md). Review admission is persistently bounded locally; delivery operations now share a workspace lock and explicit active-run pointer with same-run live reconciliation. See [coordination and recovery](docs/workspace-coordination.md) for limits and interrupted-lock handling. No controlled paid comparison yet establishes lower cost or fewer interventions for complete web deliveries.

package/bin/ctg.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { runOpenCodeCli } from '../lib/opencode/cli.mjs';
+import { createOpenCodeCliRuntime } from '../lib/opencode/cli-runtime.mjs';
+
+const argv = process.argv.slice(2);
+if (argv[0] === 'native') argv.shift();
+process.env.CTG_NODE_EXECUTABLE ??= process.execPath;
+
+try {
+  const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  const runtime = await createOpenCodeCliRuntime();
+  const code = await runOpenCodeCli({ argv, runtime, version, stdoutIsTTY: Boolean(process.stdout.isTTY) });
+  process.exitCode = Number.isInteger(code) ? code : 0;
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = Number.isInteger(error.exitCode) ? error.exitCode : 1;
+}

package/docs/budgets.md

@@ -0,0 +1,72 @@
+# Session delivery budgets
+
+The delivery extension supports opt-in execution limits on Windows, macOS,
+Linux and WSL. These are agent orchestration controls, not a security sandbox
+or a dollar/token billing cap.
+
+Normal `ctg` launches accept `--max-tools`, `--max-seconds`, and `--max-repairs`
+for both TUI and headless mode. For example:
+
+```text
+node bin/ctg.mjs -p --max-tools 100 --max-seconds 900 --max-repairs 2 "Implement the requested change"
+```
+
+Invalid or missing values, and budget options combined with `--no-delivery`,
+fail before launching the engine. Use `/delivery-budget-status` to inspect
+usage, remaining allowance (null means unlimited), and stop reason without
+spending a tool call. The command displays a JSON status message.
+
+Alternatively launch the bundled engine directly with the extension and flags
+(from the repository root; works in PowerShell and POSIX shells):
+
+```text
+node vendor/agent/cli.js -e extensions/delivery.ts --delivery-max-tools 100 --delivery-max-seconds 900 --delivery-max-repairs 2
+```
+
+Each flag accepts an integer from 0 to 1000000. Zero disables that dimension;
+all default to zero. The existing maximum of two automatic repair nudges per
+user input still applies. The new repair limit additionally caps nudges over
+the entire budget, including across user follow-ups.
+
+- Tool calls count at admission, including status calls and subsequently blocked
+  calls. Exactly N calls may be admitted; the next attempt stops the agent.
+- Seconds measure wall time from budget creation, including idle time and time
+  while the process is closed. An active turn has a timer that requests abort
+  even if no tools are invoked. An idle expired session stops on its next run.
+- Repair rounds count automatic delivery follow-ups, not arbitrary model turns.
+- Limits and counters are stored as session entries independently of plans.
+  Replanning, input, compaction and same-session tree navigation do not reset
+  them. Restoration reads all session entries, not only the selected branch.
+  Existing saved limits remain authoritative until reset.
+
+When exhausted, the extension blocks tools, requests engine abort, suppresses
+repair follow-ups, and emits a `delivery-budget-stop` JSON message containing
+its reason, counters, requirements and last recorded evidence. That evidence
+is a snapshot, **not a fresh verification**. The delivery report is not falsely
+marked verified or overwritten; unfinished work remains unfinished.
+
+To authorize more work, explicitly run `/delivery-budget-reset` while the agent
+is idle. In headless mode a command-only invocation on a previously failed
+session may still exit 1 because the engine prints its last assistant error;
+the command's persisted reset is applied. Our offline subprocess regression
+checks the saved reset and subsequent tool execution rather than treating that
+exit code as proof that reset failed. It creates a fresh budget using the current launch flags. This is a
+user command, not a model tool. A genuinely new session also starts a new budget.
+Separate processes/sessions do not share a workspace-wide quota, and deliberate
+session-file edits or extension removal can bypass the limits.
+
+Cancellation is cooperative: engine/provider/tools must honor abort signals.
+Detached subprocesses, uninterruptible synchronous code, and requests already
+billed by a provider cannot be undone. Time limits are not hard OS process
+termination deadlines. No paid-provider cancellation guarantee is implied.
+
+The bundled engine's headless print-mode finalizer also destroys its captured
+Undici dispatcher, but only if that dispatcher is still the process-global
+dispatcher. This releases sockets left open by aborted provider requests without
+destroying a dispatcher that another runtime installed later. After refreshing the
+vendored engine, run `node tools/patch-print-shutdown.mjs`; the patcher fails
+closed if the expected print-mode anchors have changed.
+
+Native Windows/macOS/Linux CI runs the regression suite on Node 22 and 24;
+WSL is validated separately locally. This does not establish every terminal,
+OS version, browser or processor architecture as tested.

package/docs/compaction.md

@@ -0,0 +1,34 @@
+# Bounded context compaction
+
+Both vendored engine compaction paths use `vendor/agent/bounded-summary.mjs`.
+After refreshing the engine bundle, run `node tools/patch-compaction.mjs`. The
+patcher validates its anchors and fails rather than guessing at changed code.
+
+Compaction starts at the earlier of 70% of the context window or the configured
+reserve boundary. Context estimates take the maximum of usage-based tokens and
+serialized UTF-8 bytes divided by four, including when cache usage is available.
+This is conservative for the managed gateway, whose current catalog advertises
+its serialized byte cap divided by four as the usable context window.
+
+Summary requests use half the catalog-derived byte cap (or half an explicit
+`maxRequestBytes`, if stricter), measured against their serialized context.
+The remaining space allows for transport encoding, provider fields, and output.
+This is a conservative bound, not an exact tokenizer or wire-payload measurement.
+Provider size rejections halve the budget and retry with smaller fragments.
+
+Oversized history is split at Unicode-safe boundaries. Every fragment includes
+instructions to preserve constraints, paths, unresolved failures, and next steps.
+Ordered fragment summaries are recursively combined into one checkpoint. No raw
+history is silently truncated. Prior summaries and custom instructions are part
+of the input being reduced. Each subrequest has a distinct session/operation seed;
+all returned usage is accumulated. Output is capped at 4096 tokens per request.
+
+Aborts, non-size failures, empty/tool-call/truncated responses, non-converging
+reduction, and the 128-request/eight-level limits fail compaction rather than
+persisting an incomplete checkpoint. The UI labels this as a failure, not success.
+There is no guarantee of lossless semantic compression: summaries remain model
+generated. Tests use deterministic transports and cover bytes, chunk coverage,
+adaptive rejection recovery, cancellation, failure states, and UI notices.
+
+Restart CTG after updating to load the new engine and UI. Existing session logs
+and working files are not rewritten by this update.

package/docs/context-efficiency-plan.md

@@ -0,0 +1,24 @@
+# Context efficiency implementation plan
+
+Saved before implementation. Based on nine-cell v4 evidence: five harness cells exceeded the local input-byte envelope; one hit output length. Preserve all v1–v4 evidence. No paid benchmark rerun or production repository change is authorized by this implementation stage.
+
+## Boundaries and invariants
+
+1. `lib/delivery-context.mjs` pure projections own compact recovery/status/review receipts, byte accounting and conservative history selection. They cannot mutate lifecycle, acceptance, checks, evidence or approval. Exact active acceptance text, validator argv, outputs, progress and all unresolved blockers remain in recovery; size is measured, never silently trimmed to a hard cap.
+2. Extension owns archive persistence and event integration. Superseded successful **delivery-only, fully paired** tool turns can become archive receipts in outbound context; original session/report are untouched. Failed results, user messages, mixed coding batches, incomplete pairing, and recent delivery turns remain verbatim. Do not archive captures during pending design review. Receipts link to immutable content-addressed archives; archive failure retains original messages.
+3. Compact normal status and review responses stop serializing nested planning history/capture/revisions. Inspection must remain available in full; large inspection output must have a real complete artifact, not the current misleading generic truncation notice. Reading/semantic review remains model-authored. Any paging is explicit, with digest/source/capture identity retained; large captures are not considered read because a pointer exists.
+4. Compaction integration uses pi's documented lifecycle, not a second summarizer. Refresh active run before restoring a deterministic recovery record. No model summary can create approval, erase blockers or certify freshness. Do not silently enable paid compaction or override user settings. Add explicit pressure advice/telemetry and document conservative native compaction settings; automatic byte-triggered compaction remains gated on tested engine support.
+5. Metrics contain numeric category byte counts (system/schema/messages/reasoning/tool classes), no message bodies. Token estimates are labeled estimates, not tokenizer guarantees. A useful large-fixture test must show meaningful reduction while retaining exact obligations.
+
+## Challenges and validation before delivery
+
+- Restore after compaction, revision, source edits and branch switching: approval still locked when stale; exact validators/acceptance/outputs and failed evidence remain visible.
+- Old tool-call batches: never orphan IDs or merge tool results across user messages; preserve every failed result. Retained provider reasoning signatures untouched; archived whole turns remove their replay metadata together.
+- Full capture >48KB: parseable response, real retrievable archive, no mutation of capture, missing sections explicitly disclosed. Small-capture compatibility retained.
+- Archive corruption/symlinks/write failure fail conservatively; do not prune data without a verified archive. Session files and reports remain unchanged by projection.
+- Metric category totals, multibyte strings, no prompt/key leakage. Context pressure must not initiate paid retries/compaction unexpectedly.
+- Pure tests + real extension integration + repository quality; benchmark manifests and historic result documents remain preserved. No benchmark superiority claim from synthetic byte savings.
+
+## Subsequent repository benchmark design
+
+After implementation, design a preregistered suite, not tasks selected because baseline pi failed. Use realistic feature additions across pinned existing repositories: authorization/migrations, cross-layer optimistic updates, third-party API integration, background jobs and compatibility changes. Separate offline hermetic and authorized online documentation tracks. Specify pristine base SHAs, dependencies/services, network rules, protected tests, held-out probes, paired budgets, common compaction settings and >=3 repetitions. Include old/new harness ablation and Jev separately. Publish development pilots separately from untouched test tasks. Actual expensive runs require a separate frozen manifest and cost authorization.

package/docs/context-efficiency-review.md

@@ -0,0 +1,27 @@
+# Context-efficiency author review and validation
+
+This is an **author review**, not independent approval.
+
+## Challenged risks and dispositions
+
+1. **Summaries laundering authorization:** recovery is a read-only projection with explicit non-authority text; existing `planningStatus`/tool gate still fingerprints source and binds run/revision/digest. Extension regression changes source after approval and emits compaction notification: mutation remains blocked.
+2. **Losing exact requirements or negative evidence:** recovery retains acceptance/check argv/outputs, open blockers, validation and review findings, review limitations, failed check status and excerpt. Pure regression asserts exact equality and unchanged durable state across projection/revision. Original evidence/history remain in report/session. Extremely large status/finding responses still encounter the existing presentation limit; not represented as universally bounded lossless responses.
+3. **Provider-invalid orphan tool results or altered reasoning signatures:** only a complete contiguous assistant plus all its matching unique successful delivery-only results is replaceable. Never alter an assistant's reasoning field in place; preserve mixed code turns, failures and the newest eligible exchanges. No claim of compatibility with every provider cache/continuation API; live provider smoke remains needed for a new campaign.
+4. **Pointer pretending inspection occurred:** oversized captures include explicit full paged-read instruction and immutable identity, with full artifact on disk. A pointer is not a reading certificate. Existing review capture match/scenario requirements remain in effect; actual comprehension still unprovable. Trusted advisor receives full capture through tool details.
+5. **Archive corruption/write failure:** verify stored bytes on every archive substitution. Any storage failure conservatively retains original history. Tests cover corrupt artifact and symlinked root rejection. Atomic content-addressed create is not an OS sandbox or crash-proof disk guarantee.
+6. **Compaction resetting budgets or selecting another run:** compaction hook refreshes the same selected run only; it does not call session restore, reset timers or clear counters. Branch/session restore retains existing behavior. No automatic paid summarizer is introduced.
+7. **Telemetry leaking source:** only numerical sizes/categories/growth/time written. No prompt snippets or content hashes that imply semantic reading. Categories are coarse wire-JSON attribution; bytes/4 explicitly heuristic.
+8. **Overclaiming savings:** offline historical potential message savings 26–51% assume archive eligibility and simulated references. Not proof of better live completion, not actual serialized-provider request savings. Full design remains retrievable and exact obligations can still be large.
+9. **Benchmark integrity:** no historical candidate/evaluator/receipt edited. Adapter source change requires a new manifest/root; old freeze no longer validates this changed checkout and must not be overwritten.
+10. **Research claims:** repository API/README retrieved directly; identify unstable branches, licensing boundaries and unresolved Cal.com/Cal.diy identity. No claim that proposed tickets or containers are ready.
+
+## Results
+
+- `npm run quality`: lint, typecheck, build, **352/352 tests passed**; log `/tmp/context-quality-final.log`.
+- `node --test tools/benchmark/advisor.test.mjs tools/benchmark/runner.test.mjs`: **5/5 passed**, including actual installed pi offline discovery/guard and advisor integration; log `/tmp/context-installed-engine.log`.
+- `git diff --check`: clean.
+- No new paid model calls, no browser/Python suite run in this change, no independent review, no remote CI/PR/merge claimed.
+
+## Follow-ups, not implemented claims
+
+Byte-triggered automatic native-compaction scheduling; incremental section/patch design tools; pagination for every unusually large findings/status response; live context+compaction completion validation; new repository containers/reference patches/held-out evaluators; repeated online/offline paid comparisons. Native compaction is user-configured, with deterministic recovery already integrated.

package/docs/context-efficiency.md

@@ -0,0 +1,49 @@
+# Delivery context: compact projections, durable obligations
+
+## Implemented
+
+`lib/delivery-context.mjs` owns pure recovery/status/review projections, context byte metrics and conservative archival selection. `lib/context-archive.mjs` owns immutable content-addressed storage. The extension composes these without changing approval or verification policy.
+
+- `delivery_status` no longer echoes full `state.plan.design`, capture, planning history or revision snapshots. It returns exact active acceptance, checks (including argv), outputs, progress, current findings and compact evidence, plus report location and freshness/next-action fields.
+- Successful plan-review responses return counts instead of repeating every walkthrough/challenge. Findings, limitations, identity and provenance stay visible; full reviews remain in reports/session entries.
+- Large `delivery_design inspect` responses return a **complete capture archive path**, ID/digest/source identity and explicit instruction to read the entire artifact in pages. Small captures retain the previous shape. Full large capture remains in tool `details.deliveryCapture` for trusted advisor consumers; it is not automatically placed into model text.
+- After recorded approval, older successful **delivery-only** paired exchanges can become outbound archive references. Keep the two newest eligible exchanges. Failed tool results, reported blocking findings/failed checks, user messages, mixed/code tool turns, unmatched pairs and pending unapproved review contexts stay verbatim. Original session messages and full report history are not rewritten. Archive originals are verified before any replacement; failure retains messages.
+- Context rebuild injects a deterministic recovery record. It preserves exact acceptance, required check definitions, outputs, progress, all persistent open blockers and failed check status. It is explicitly **not authority**. Source freshness, approval and completion remain checked by existing policy immediately before execution/finish.
+- Native `session_compact` refreshes the same selected run without resetting timers, budget, repair counts or planning state. Branch/session restoration continues through the existing reconciliation logic. A generated summary cannot revive approval.
+- `before_provider_request` records numeric category bytes, growth, and labeled bytes/4 token estimate to `.harness/.../context-metrics.jsonl`. No message text is copied. Categories: system, schemas, planning calls, tool results, code calls, reasoning fields, remaining conversation, serialization envelope. Wire formats without messages are conservatively measured as envelope; this is not universal provider tokenizer accounting.
+- Above 240KB in the previously observed payload, inject a pressure warning to reserve room for verification/handoff. It does not silently trigger paid calls or change acceptance.
+
+## Compaction: explicit configuration, not a hidden new model call
+
+Native pi compaction remains controlled by the user's engine settings. **This change does not turn it on behind the user's back**, and does not add a second summarizing model. Future comparison runs must enable the same native policy in all arms and charge summarization tokens/time to each cell.
+
+For a 100k-token engine configuration, an initial development setting to validate is:
+
+```json
+{"compaction":{"enabled":true,"reserveTokens":40000,"keepRecentTokens":12000}}
+```
+
+That requests native compaction around 60k estimated tokens while keeping recent work. These are tuning starting points, **not** a guarantee against a 400KB byte ceiling: escaping, schemas, reasoning metadata and long Unicode/tool results can break bytes/token heuristics. Use the numeric metrics and a preflight that exercises real tool history and compaction before freezing a paid test. A byte-triggered automatic compaction scheduler and incremental plan-authoring APIs remain follow-up work; no implementation or success claim for them is made here.
+
+## Measured offline savings
+
+Applying eligible archive substitutions to the final saved v4 message histories (assuming approved state, with simulated compact archive references) reduced serialized **message-history** bytes by:
+
+| Task | Carthagent | Carthagent + Jev |
+|---|---:|---:|
+| Voxel | 26.4% | 27.6% |
+| Shop | 29.6% | 38.7% |
+| Ledger | 48.4% | 50.9% |
+
+Artifact `/home/baissi/benchmarks/context-efficiency/historical-projection.json`. This is an offline potential-savings measurement, not replayed paid runs, live provider tokens, improved correctness, or proof that the old runs would have finished. Post-revision pending review disables archival, so the final-history eligibility assumption can overestimate savings in an actual state. The smaller status/review responses are additional unquantified changes.
+
+## Limits and compatibility
+
+- Exact requirements/checks/blockers are not silently trimmed to a fixed recovery size. A huge contract can still be huge.
+- Archive files and reports may contain secrets already present in planning/tool data; no default redaction or zero retention. Archives use 0600 for new files. Same-user access and symlink races against a hostile host are outside the participating-tool boundary.
+- Archive pointer/read receipts never certify actual reading or semantic review. The model must explicitly retrieve large captures; all review and approval obligations remain unchanged.
+- The ordinary response truncation helper still applies to extremely large non-inspection responses; this change fixes large inspection retrieval specifically, not every possible result. Review/validation finding-list pagination is future work.
+- Benchmark advisor now accepts large captures from trusted tool details as well as small capture text. This invalidates historic source manifests for rerun; existing freezes/results remain unchanged evidence.
+- No code/test output or user messages are compressed by the deterministic archive selection. Native compaction handles general conversation growth, with the recovery record protecting harness obligations.
+
+Validation includes pure size/invariant tests, real extension gate/restore tests, large-capture retrieval, failure-preserving history projection, numeric telemetry redaction-by-design and repository quality. Native compaction's model-generated summary quality and a paid completion-rate improvement remain unmeasured.

package/docs/deepseek-jev-benchmark-plan.md

@@ -0,0 +1,70 @@
+# Three-task DeepSeek / Jev benchmark — protocol v1
+
+Status: design challenged before benchmark implementation; candidates have not run.
+
+## Question and experimental arms
+
+Does Carthagent improve externally measured task delivery over plain pi, and does advisory Jev add value above the same harness? All arms use the same installed pi engine and pinned `deepseek/deepseek-v4.1-flash` via OpenRouter, high reasoning, identical task text, initial workspace, tool availability and resource ceilings. The harness arms explicitly load this repository's delivery extension/skill; the plain arm has no extensions, skills, context files or prompt templates. This controls engine version rather than conflating vendored-engine differences with harness value. Record exact engine and harness versions.
+
+A: plain pi. B: pi + Carthagent, no Jev. C: pi + Carthagent + Jev advisory feedback on the first successful design inspection per revision (at most 3 calls/run). No Jev router: it could choose a different generator and confound the ablation. Jev cannot approve or weaken deterministic gates. Probabilities >=0.5 flag review topics, not proven defects. Use OpenRouter `typesafe/jev-1.13` Decisions API, preserving returned snapshot/provider/cost.
+
+Initial exploratory matrix: **3 tasks × 3 arms × 1 independent run = 9 runs**. Balanced task-specific arm order; no selective retries or supervisor repairs. One replicate per cell is exploratory, not statistically conclusive. Infrastructure smoke tests are separate and are never counted as task successes. If infrastructure fails, preserve results and explicitly document any protocol revision before restarting any affected comparisons.
+
+## Tasks and external acceptance
+
+1. **Rust voxel sandbox (small Minecraft-like clone)**: actual Rust gameplay/voxel state and software-rendered first-person view, deterministic terrain, collision/gravity, block remove/place with bounded reach, save/reload and malformed-save rejection. Browser input/display may be a thin JS frontend to the Rust server. Test Rust compilation and headless scenarios, then real browser controls/rendering and screenshot. Not a Minecraft-complete game: no crafting, mobs, infinite streaming or multiplayer.
+2. **Sales website**: responsive local outdoor-products storefront, search/category/sort, stock-aware persistent cart, exact-cent totals, discount/shipping rules, validated checkout, idempotent order submission, persisted orders and stock, accessible status/error UI. Evaluate API contracts and real browser add/update/reload/checkout at desktop/mobile widths. No real payments/deployment.
+3. **Exact-money transfer ledger**: Node JSONL service/CLI, signed decimal parsing without float rounding, integer-cent balance invariants at large magnitudes, atomic insufficient-funds rejection, idempotent retries/conflict rejection, persistence/restart and malformed log handling. Evaluate ordinary, adversarial and deterministic seeded metamorphic cases. This targets defects that screenshots and agent-owned tests miss.
+
+Each task gets a frozen public prompt with observable interfaces and detailed requirements. External tests are written and hashed before candidates start; evaluator files are outside candidate workspaces and never sent to models. They are **withheld, not OS-isolated secrets**: same-host shell access is not a security sandbox. Do not claim blind testing if a trace shows evaluator access. Public API specifications are not hidden-test leakage. No candidate receives external scores or repairs during its initial run.
+
+Score separate behavioral categories; report missing/unbuildable/unlaunchable as failures, not missing rows. Collect agent-authored tests separately. Capture visual artifacts but do not pretend pixel existence proves playability or subjective design quality. Report browser/runtime infrastructure failures separately from candidate failures.
+
+## Budgets and measurement
+
+- Per candidate: 15 minutes wall time, 120 observed tool starts, at most 100 paid generation requests, 16,384 generated tokens per request, 100,000-token engine context setting and 402,000-byte serialized request cap (conservative <=412,000-token reservation envelope including protocol overhead; actual token count is recorded).
+- Provider proxy enforces max input/output prices of $0.30/$1.20 per million for DeepSeek, $0.15 generation-request reservation (covering <=412k input tokens and 16,384 output tokens at these rates) and **$3 maximum reserved spend per candidate**. Stop on unknown/invalid billing instead of interpreting missing cost as free; reconcile `usage.cost` when available. Jev max 3 requests, <=64KB request, $0.01 reservation each, included in candidate ceiling. Overall candidate ceiling $27; smoke/provisioning API calls separately capped at $0.10. No automatic escalation.
+- Track external score, completion/false-completion, all failures, wall time, requests/tool calls, input/output/cache/reasoning token usage, actual provider cost, Jev latency/probabilities and model snapshots. Local provisioning/build time is recorded separately. Missing cost is unknown, not zero.
+- One bounded infrastructure retry only for connection failure before generation, never candidate retries that erase failures. Sequential paid requests per candidate; overlapping tasks may be scheduled for practicality, with hardware contention disclosed.
+
+## SRP / DI design
+
+- Frozen protocol/task specs: own task meaning and scoring weights, no execution.
+- `gateway`: owns outbound model authentication, model allowlist, bounded requests and spend reservation, sanitized usage receipts. Inject fetch/key/clock; candidates receive a dummy local credential, never the real key. Never log authorization headers. Restrict listening to loopback.
+- `runner`: owns workspace/process lifecycle, resource deadline, JSON event logging, immutable invocation/results; no scoring or model-written repairs. Inject engine path, process environment and gateway address.
+- `advisor`: owns extracting an inspection result, typed Jev rubric and attaching advisory feedback to the corresponding generator tool result; no approval or execution permission. Exactly the same Carthagent policy in B/C.
+- `evaluators`: own independently specified functional oracles and browser checks, no candidate prompts or automatic repair. Real subprocess/HTTP/browser boundaries, not fake-only tests.
+- `report`: joins immutable receipts and scores; missing data stays missing; no synthetic statistical certainty.
+
+## Preimplementation challenges / scenario walkthroughs
+
+- Availability: OpenRouter's ordinary chat catalog lists DeepSeek and Jev Router, but Jev itself is a separate Decisions API. Verified primary Jev docs before choosing endpoint; never substitute router results for a Jev ablation.
+- Key confidentiality: parent reads only OpenRouter auth; child uses dummy proxy credential and a clean config/environment. Shell can still read host files absent OS isolation, so never represent this as protection against a malicious candidate. No real secrets in prompts, saved configs or request logs.
+- Fairness: same engine/tool set/settings and unmodified public task prompts. Harness guidance and Jev feedback are intentional treatment differences. Tool-budget overhead is part of harness cost; also report generation/request/time overhead so quality is not cherry-picked.
+- Failure: invalid model response, no billing, timeout, exhausted budget, compiler failure and no rendered UI stay visible. Missing Jev is an unavailable treatment, not a successful Jev run.
+- Oracle adequacy: test mutant behaviors (float money, duplicate application, ignored stock, no voxel change) to show evaluators detect meaningful failures before running candidates. Real browser checks complement API/headless checks.
+- Persistence: restart after state changes, then retry same operation; require exactly-once state. Malformed state must reject without overwriting valid state.
+- Visual scope: require a rendered scene plus controls/state transitions; do not award a playable-clone score to only a data structure or screenshot.
+- Environment: Rust is not installed on PATH; provision an isolated toolchain before candidates. Firefox exists but snap cannot use /tmp worktrees; use benchmark runtime under the home directory with an explicit writable profile root.
+- Provenance: generative/model-authored planning reviews are not independent; external tests are supervisor-authored with published limitations. Historical earlier trials remain untouched.
+
+Outcome: protocol ready for tooling/evaluator implementation. Freeze implementation hashes before any task candidate. Adjustments needed after infrastructure probes must be logged, not silently retrofitted to favor an arm.
+
+## Pre-candidate infrastructure findings and protocol v1.1
+
+- Rust 1.98.1/cargo 1.98.1 were already installed under `~/.cargo/bin`; only PATH composition was needed.
+- The first plain smoke preserved a genuine budget-stop: its $0.05 total could not reserve a second $0.05 generation request after the first bill. A separate harness smoke with $0.08 total completed tool use and `SMOKE_OK`. No task candidate ran during these corrections. Paid smoke actual costs: $0.0007059 + $0.0041763 + $0.000019278 (Jev) = $0.004901478, below the $0.10 ceiling.
+- Real Firefox initially exposed two supervisor fixture defects (missing HTML content type; missing WebDriver return). Both were repaired before candidate evaluation and original failing logs retained. Native click + screenshot now pass under home-directory profiles.
+- Jev live endpoint smoke returned valid typed answers and billing. Inspection of the real delivery tool showed an outer `{result,planningStatus}` wrapper; the benchmark adapter now reads `result`. A real loopback integration test reproduces this exact envelope, verifies once-per-revision feedback and proves the adapter leaves the original tool result unchanged. The initial synthetic smoke did not use the real wrapper; it established API connectivity, not end-to-end harness integration.
+- Initial 95KB generation body cap would unnecessarily truncate longer coding contexts. Before all candidates, increased to 402KB after serialization, with $0.15 reservation rather than $0.05. Reservation uses a deliberately conservative byte/token envelope, not a claim that bytes/4 is a guaranteed tokenizer bound. Provider billing remains the external source of truth; unexpected billing stops further requests, not a vendor-enforced account cap.
+- Gateway buffers bounded upstream SSE until billing arrives; all arms have the same buffering and 180-second per-request transport deadline. This delays visible token streaming, not the model's generation. There are no automatic gateway retries. No OS sandbox or absolute account-level spending guarantee is claimed.
+- Evaluator self-tests include a separately authored ledger reference process and float/idempotency mutant processes. Shop quote and voxel-state/change oracles have component-level mutant assertions, not complete reference applications; their full candidate HTTP/browser suites have not been validated against independently built passing apps. Report that limitation. Browser infrastructure uses actual Firefox and native input.
+- Scores are unweighted category pass counts with the complete assertions published afterward; categories are not equal complexity. Visual screenshots support inspection but there is no invented quantitative aesthetic score.
+
+## Verified primary references
+
+- https://openrouter.ai/api/v1/models (retrieved 2026-09-28): DeepSeek model ID and $0.30/M input, $1.20/M output, $0.006/M cache-read listing.
+- https://openrouter.ai/docs/guides/community/jev : Jev available with OpenRouter key, distinct Decisions/System One endpoints.
+- https://openrouter.ai/docs/guides/community/jev-tutorial : typed answers and `usage.cost`, pinned `typesafe/jev-1.13` resolving to dated snapshot.
+
+The full API catalog and primary documentation snapshots were retained under `/tmp/ctg-benchmark-discovery/`. Search snippets were discovery aids, not the basis for endpoint selection.

package/docs/deepseek-jev-benchmark-repair-plan.md

@@ -0,0 +1,20 @@
+# Benchmark readiness repair (v3)
+
+User requested all fixes needed to make the tests runnable. Preserve v1/v2 and their reports. Do not change candidate code or interpret transport failures as model failures.
+
+## Design before implementation
+
+1. Transport adapter owns HTTPS/process I/O only: use a fresh system-curl process (system OpenSSL, HTTP/1.1, no shared TLS session/pool) per upstream request, with normal certificate/hostname validation. No `-k`, relaxed ciphers, credential argv, redirects, implicit curl config, or automatic POST retry. Fixed gateway endpoints remain authoritative. Bound body, deadline and subprocess lifetime. Return a fetch-compatible buffered response; gateway owns envelope and billing. TLS root cause remains unproven; this is a separately tested avoidance path.
+2. Shared runtime adapter owns explicit sanitized environment, copied offline fd/rg binaries, process cleanup and engine paths. Verify actual pi read/ls/find/grep in an empty isolated config, not merely `--version`. Same tool/guard setup for every arm; planning gates unchanged.
+3. Durable campaign accounting owns exclusive locking, atomic snapshots, reservation before process/request dispatch and conservative crash recovery (holds remain). Seed previous candidate spending plus unresolved holds and smoke spending. No automatic retries, reset, or account-level cap claim.
+4. Freeze owns source/engine/tool hashes and readiness receipts. Runner verifies actual hashes before any candidate, rejects existing directories, classifies terminal assistant errors separately from exit status, records tool attempts/admitted calls and structured infrastructure failures. Pre-execution extension blocks beyond 120 attempts; observed `tool_execution_start` may include blocked calls and is not execution proof.
+5. Evaluation keeps original contracts, sanitizes child environments, bounds process groups and browser waits, uses fresh output directories. Browser waits honor the public 2s UI update allowance rather than fixed subsecond assumptions; reference fixtures and mutants exercise the real HTTP/browser paths. Old evaluator hashes/results remain historical; v3 changes require a new freeze.
+
+## Challenges / tests
+
+- Malformed HTTP/SSE, wrong model, split Unicode, stalled/chunked/oversized response, TLS self-signed rejection, trusted local TLS, redirects, abort, missing curl, secret-in-argv/log and concurrent body-read races.
+- Unknown billing is not replay-safe: retain reservation and stop campaign rather than retry a paid POST. Reconciled invalid response can stop without labeling its cost unknown.
+- Concurrent processes cannot both spend the same campaign balance; crash leaves a hold. Existing state cannot be silently reset. Freeze modification blocks before paid calls.
+- Installed pi scripted local provider completes discovery, sees missing tools as failure, reaches real plan validation/inspection and Jev hook, respects preapproval mutation lock and preventive tool budget. Exit 0 + terminal error must fail readiness.
+- Reference shop real API/native Firefox controls must pass, deliberate pricing/idempotency mutants must fail. Voxel previous candidate is a retained regression fixture only, not an independent reference; evaluator logic invariants/mutants complement it. Do not fix candidates to satisfy evaluators.
+- No paid candidate matrix until offline readiness and bounded TLS/live connectivity checks pass. Live readiness expenses share the remaining original smoke allowance. A finite soak is evidence, not proof TLS can never fail.

package/docs/deepseek-jev-benchmark-restart.md

@@ -0,0 +1,9 @@
+# Uniform infrastructure restart (v2)
+
+Original frozen tasks and evaluators: original-freeze.json, commit 7087423. No task/evaluator changes between attempts. All v1 runs are retained at ../deepseek-jev-v1, including the partial plain voxel candidate and eight zero-tool failures. The initial gateway hid the root cause behind its sanitized generic failure. Separate tiny diagnostic requests succeeded afterward; no candidate repair or external scores were returned to a generator.
+
+Restart announced to user before beginning. Changes are runner root v2, candidate ceiling $2.84 (was $3), extra sanitized error class/code/stage receipts, and stop-the-matrix on the first gateway stopped condition instead of spending startup requests on the remaining arms. Full matrix order is unchanged. The first v2 run is launched individually for early diagnosis; subsequent runs only proceed if infrastructure remains healthy. No copying v1 candidate files into v2.
+
+Worst-case accounting for v1: known actual $0.048990234 plus 9 unresolved $0.15 reservations = $1.398990234. Nine v2 ceilings of $2.84 = $25.56. Combined $26.958990234 <= original $27 candidate ceiling. Tiny diagnostic calls are separate smoke expense, within the original $0.10 allowance. Reservations are conservative local limits, not an OpenRouter account-level cap.
+
+This is a transparent all-arm infrastructure restart, not another statistically independent replicate or a discarded bad model result. Retain both attempts and report v1 failures. No further automatic restarts authorized by this protocol.