carthagent 0.0.0-stage → 1.1.0-beta.1

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,277 @@
-# 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.
+
+### Projects sidebar source preview (development only)
+
+The redesigned Projects sidebar (folder card, folder browser, and folder/model
+setup for new sessions) exists only as source. It is **not** in any published
+`ctg` release, and the steps below do not build or update the published native
+runtime. The published runtime stays pinned to
+`docs/patches/opencode-v2.0.32-session-ui-combined-v4.patch` and
+`lib/opencode/runtime-release.json`.
+
+Requirements: Git, a POSIX shell, `sha256sum` or `shasum`, Bun 1.4.2 (the
+OpenCode `packageManager` pin), and this checkout with `npm ci` already run. No
+native compilation is needed. The launcher is a POSIX `sh` script for Linux and
+macOS; native Windows is not supported.
+
+1. Prepare a clean OpenCode checkout at the pinned upstream and apply the
+   development patch (v5 replaces v4 and applies directly to upstream):
+
+   ```sh
+   git clone https://github.com/anomalyco/opencode "$HOME/src/opencode preview"
+   git -C "$HOME/src/opencode preview" checkout 843a6c514e606b436a7fe713422ace0a93ad3d61
+   script/ctg/prepare-development-runtime.sh "$HOME/src/opencode preview"
+   (cd "$HOME/src/opencode preview" && /path/to/bun-1.4.2 install)
+   ```
+
+2. Launch from any directory with explicit paths (spaces are fine):
+
+   ```sh
+   /path/to/carthagent/script/ctg/source-preview.sh \
+     --source "$HOME/src/opencode preview" \
+     --profile "$HOME/.carthagent/source-preview" \
+     --bun /path/to/bun-1.4.2 \
+     --workspace "$HOME/projects/my project"
+   ```
+
+   The launcher runs `bun --no-env-file run src/index.ts --standalone <workspace>`
+   from `packages/cli` with only a private HOME, TMPDIR, XDG and OpenCode config
+   directory inside `--profile`. It disables project config and auto-update and
+   passes no inherited API keys. On first use it creates the profile (mode 0700)
+   with the Carthagent plugin, Carthage theme and CLI theme config. Existing
+   profile files are never rewritten. The private server listens on an ephemeral
+   loopback port and exits when the TUI exits.
+
+3. Sign in once inside the same profile. Enter secrets only at the terminal
+   prompt, never as arguments:
+
+   ```sh
+   script/ctg/source-preview.sh --source ... --profile ... --bun ... -- auth login
+   ```
+
+In the TUI, the folder card at the top of Projects shows the current folder and
+model. Use **Browse** (or `/browse`) to pick a folder and **Ctrl+S** to confirm.
+**New session** (also Ctrl+X N or `/new`) opens folder and model setup; the session is created only when
+you send the first message, with your current agent and the chosen model. If that agent or model is
+unavailable when you send, the send is blocked and your text is kept until you choose another. Leave with `/exit` (or Ctrl+P, “Exit the app”); relaunch with
+the same `--profile` and choose the session in Projects to continue it.
+
+See [source preview](docs/source-preview.md) for testing, patch verification and
+limits.
+
+## 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.13 is the current experimental release. It promotes the
+combined-v5 runtime patch: a directory-first Projects rail with a folder
+browser, shared folder and model setup for new sessions, and an isolated
+source-preview launcher, on top of preview.12's npm-publishable package.
+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.13 release notes](docs/release-notes-preview.13.md),
+[preview.12 notes](docs/release-notes-preview.12.md), and [preview.11 notes](docs/release-notes-preview.11.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/beta-rewards-e2e-plan.md

@@ -0,0 +1,48 @@
+# Beta rewards and new-user acceptance
+
+Owner-approved policy: one eligible `ctg` verified delivery earns **25 coins,
+100 XP and 1 km**, at most three grants per player per UTC day. Daily classifier
+assessment and personal work-log completion do not earn these rewards.
+
+## Execution plan
+
+1. Preserve the current live account and capture its starting profile. Confirm
+   account identity through normal authentication; never select an account by
+   a display name supplied to a public endpoint.
+2. Implement a versioned backend reward receipt and atomic coin/XP/km posting.
+   Derive owner from authentication and amounts from server policy. Retain
+   delivery identity across retries and enforce daily caps under a player lock.
+3. Integrate an explicit native claim action. Require a current required-check
+   verified handoff, fresh source fingerprint, passing check/requirement/review
+   gates and stable project/run identity. Do not reward advisory or blocked work.
+4. Run a disposable real-PostgreSQL lifecycle through normal HTTP/auth routes:
+   new user, one welcome grant, isolation, eligible reward, exact replay,
+   conflicting/parallel claims, daily cap, rollback, level/week boundaries,
+   purchase/equip and application/database reconnect persistence. Exercise
+   rejection paths and reconcile wallet postings against balances.
+5. Run backend checks and native eligibility/RPC/UI checks. Deploy the backend
+   only via reviewed PR, merge and its existing deployment workflow.
+6. On the owner's Beshir Aissi account, claim the existing accepted Ship delivery
+   once; replay it; confirm exactly +25 coins/+100 XP/+1 km, then compare native
+   and web persisted state. Keep test fixtures separate from earned live records.
+7. Record actual results, limitations and exact revisions, then resume beta
+   publication with installed-package and public-runtime acceptance gates.
+
+## Trust boundary
+
+The coding harness verifies local execution and source freshness. An authenticated
+client transmits a bounded receipt; the backend does not independently execute
+the repository. Client attestation is not remote execution attestation or proof
+of authorship. Server amounts, owner isolation, durable deduplication and caps
+must hold even for malformed or replayed clients. Tests must not equate a private
+debug coin grant with an earned coding reward.
+
+## Original baseline
+
+Live profile previously verified: 20 coins, 0 XP, sandals owned/equipped. Current
+backend has no coding-reward path. Quest policy explicitly returns `rewards:false`.
+Beta publication is held until this additional acceptance scope is resolved.
+
+Execution results are recorded in [beta-rewards-e2e-results.md](beta-rewards-e2e-results.md).
+Production earned claim/replay/restart acceptance now passes at 45 coins,
+100 XP and 1 km; live browser and release-package acceptance remain pending.

package/docs/beta-rewards-e2e-results.md

@@ -0,0 +1,84 @@
+# Beta reward acceptance results
+
+## Production earned reward — passed
+
+Tested November 2, 2026 UTC through the normal installed profile, authenticated
+as the owner's Beshir Aissi account. The installation is still preview.13 with
+labelled local launch/reward patches; these results are not installed-beta
+release acceptance.
+
+- Backend PR [#176](https://github.com/B-icy/Carthagent-Backend/pull/176), merged
+  revision `ec40fdb9b053e64b820adb18e7d35da927468149`.
+- [Production deployment](https://github.com/B-icy/Carthagent-Backend/actions/runs/41401836218)
+  passed migration/readiness, public-site and service checks.
+- Native preview accepted the real required-check Ship delivery
+  `903d3ed5-88db-41ca-b72d-f5699fa5ae7f`, source snapshot
+  `cea9b1d71e113d0b876cec4d3a2eef38f16e14decb519d033fb7d9325508b8bb`.
+- Claim receipt `9d44cf4b-0a70-40e5-90ce-d68a7718fe21`, awarded
+  `2026-11-02T06:49:23.538Z`, policy `verified-delivery-beta-v1`.
+
+| Check | Before | After |
+| --- | --- | --- |
+| Coins | 20 | 45 |
+| Total XP | 0 | 100 |
+| Total / weekly km | 0 / 0 | 1 / 1 |
+| Profile version | 14 | 15 |
+| Equipment / inventory | Sandals equipped | Identical, sandals retained |
+
+Immediate replay returned the identical receipt with `replayed:true` and no
+additional grant. After stopping and restarting the registered native service,
+preview, replay and profile all matched the saved post-claim result exactly.
+Sessions and credentials persisted. No debug issuance was used.
+
+The live TUI displayed 45 coins / 100 XP / 1 km, rendered the digest-only claim
+confirmation, accepted cancellation, and then confirmed the existing receipt
+with “This delivery was already rewarded. No duplicate grant.” The wallet and
+version stayed unchanged. Captures: `/tmp/opencode/rewards-ui-preview.txt` and
+`/tmp/opencode/rewards-ui-replayed.txt`.
+
+## Repeatable new-user acceptance — passed locally
+
+Disposable PostgreSQL 17.11: 117 tests passed before the additional bearer
+scenario; the complete six-test bearer group also passed. Backend CI ran the
+updated suite successfully. Backend unit tests: 521 passed, one skipped.
+Syntax, assets and navigation checks passed.
+
+Coverage includes one welcome grant, cookie and device-approved bearer access,
+reward claims and browser/CLI agreement, token refresh/new CLI session, owner
+isolation, concurrent daily caps, run/snapshot deduplication, changed-evidence
+rejection, transaction and wallet-overflow rollback, level/week progression,
+milestone shop/quote/equip agreement, purchase replay, database reconnect and
+restricted deployment/application-role permissions.
+
+Native build/lint and 76 focused tests passed, including explicit confirmation,
+account/session binding, current source gates, privacy of digest-only uploads,
+lost-response recovery, restart and receipt recovery after source changes.
+
+## Remaining acceptance gates
+
+- Live browser comparison awaits normal user sign-in in `voyages-rewards-e2e`.
+- Live terminal rendering, cancellation and confirmed replay passed.
+- Five-platform runtime prebuild 41398315323 succeeded on attempt 2. Exact
+  provenance, all archive checksums, embedded metadata and executable hashes
+  passed the production acquisition parser; regenerating the manifest produced
+  the identical candidate. The packaged beta manifest now matches those bytes.
+  Installed beta acceptance remains pending.
+
+Pre-manifest full native quality run: lint/build passed; 1,124 tests passed, five
+skipped, six failed solely because the package version is beta.1 while the
+runtime manifest still pins preview.13. These remain release-blocking failures
+until the verified beta candidate was integrated. The post-integration quality
+run passed: **1,130 tests passed, five skipped, zero failures**, plus lint,
+typecheck and build. Exact candidate/packaged manifest equality and
+`verify-release-version.mjs v1.1.0-beta.1` also passed. No trust assertion was relaxed.
+
+Native PR CI passed all jobs after retrying one Windows Node 24 process-query
+timeout. Native navigation also passed locally: 12 tests / 65 assertions.
+
+The reward backend relies on authenticated local-harness attestation. It does
+not independently execute repositories or prove authorship. Daily classifier
+assessment and personal quest checkmarks remain unrewarded.
+
+Local evidence: `/tmp/opencode/rewards-live-claimed.json`,
+`/tmp/opencode/rewards-live-restarted.json`, and
+`/tmp/opencode/rewards-installed-backup/provenance.json`.

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.