carthagent 0.0.0-stage → 1.0.7

package/docs/jev-repository-pilot-results.md

@@ -0,0 +1,79 @@
+# Integrated Jev repository pilot — results
+
+## Executive finding
+
+**Plain pi completed both Fastify feature tickets and passed all measured behavior/type/regression checks. No Carthagent treatment completed a feature. The experiment does not establish Jev effectiveness: neither scored Jev cell reached plan inspection, so neither called Jev.** Three treatment runs ended on provider deadlines, one on a curl receive error. Treat those as unavailable/infrastructure outcomes, not comparative semantic quality scores.
+
+The clear workflow observation is that treatment discovery consumed 19–54 tool starts without creating a plan. New compact delivery projections cannot help before a plan exists. Native compaction worked but repeatedly summarized growing discovery history. The next fix should target bounded discovery/plan startup and compaction reliability, not another larger task matrix or relaxed approval gates.
+
+## Delivered implementation
+
+- Built-in automatic Jev critic on successful plan inspection, explicit `--delivery-jev` opt-in, OpenRouter/direct TypeSafe choice, fixed endpoints or explicit loopback broker.
+- Durable identity-bound reuse, <=3 attempts/run, sanitized unavailable mode, compact findings in recovery/status. No approval, finding-resolution or requirement authority.
+- First-class production integration exercised via a live isolated smoke; not the old benchmark-only advisor extension.
+- `docs/jev.md` configuration/disclosure; plan/protocol saved before execution.
+- Quality: **355/355 repository tests**, lint/typecheck/build; six focused real-wire transport/gateway tests. Author validation, not independent review or remote CI/merge.
+- Commits: `52d3c3f` implementation/protocol, `602e6b6` sandbox hostname repair. Earlier context efficiency `93b5c5f`.
+
+## Tasks and conditions
+
+Pinned [Fastify v5.6.2](https://github.com/fastify/fastify/tree/f15d4eaba03d86786bec2de7aed1236718c813f9), SHA `f15d4eaba03d86786bec2de7aed1236718c813f9`,384 tracked files,72,231 tracked JS/TS lines including tests. Add `reply.appendHeader` and `reply.vary`: atomic validation, raw/Fastify header precedence, HTTP behavior, types, documentation, tests. More realistic than greenfield single-file tasks, but **not** a large commerce application/browser feature benchmark.
+
+Same pi0.85.1/Node26.7.0/DeepSeek v4.1 flash/high across arms; native compaction enabled (30k threshold,6k recent). Same900s/120 tool/$2.30 per cell,400KB request ceiling,16,384 output tokens. One replicate/task/arm. Network-isolated bubblewrap namespaces, read-only harness/dependencies/references, hidden supervisor evaluators not mounted during generation. Documentation was downloaded/frozen equally: [Node HTTP22.19](https://raw.githubusercontent.com/nodejs/node/v22.19.0/doc/api/http.md), [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.txt). **No live web search or browser UI comparison** occurred; do not claim otherwise.
+
+Provider endpoints varied: AtlasCloud, Together, Relace, InferenceNet. No candidate repair/retry after evaluator feedback. All artifacts retained.
+
+## Corrected-environment six-cell results
+
+| Task | Arm | Terminal outcome | Runtime | Tool starts | External behavior | External types | Original94 regressions | Known bill |
+|---|---|---|---:|---:|---:|---|---|---:|
+| appendHeader | Plain pi | Completed |162.660s|61|7/7|Pass|Pass|$0.0338129304|
+| appendHeader | Carthagent | Provider180s deadline during compaction |284.627s|35|1/7*|Missing API|Pass unchanged base|$0.0282421188 +$0.15 hold|
+| appendHeader | Carthagent+Jev | Provider180s deadline after earlier compactions |279.450s|38|1/7*|Missing API|Pass unchanged base|$0.0322767560 +$0.15 hold|
+| vary | Plain pi | Completed |204.847s|43|7/7|Pass|Pass|$0.0201047092|
+| vary | Carthagent | Provider180s deadline during compaction |368.284s|54|1/7*|Missing API|Pass unchanged base|$0.0248195060 +$0.15 hold|
+| vary | Carthagent+Jev | Transport receive error `CURL_56` |35.843s|19|1/7*|Missing API|Pass unchanged base|$0.0036290660 +$0.15 hold|
+
+`*` Unmodified base passes the negative-invalid-input category because calling a missing method raises TypeError. This is a known partial-credit limitation detected by base selftest; **1/7 is not implemented functionality**. Positive tests require actual methods. All four treatment product diffs empty; no plan/review/approval/finish receipt. Do not aggregate their incomplete artifacts into a causal '14/14 vs2/14' quality claim.
+
+Two plain runs produced final explanations, declarations, docs and new tests. Supervisor reran their candidate tests independently: append100/100; vary109/109 (94 original+15 new). Both complete tsd suites passed. Protected external type tests include readonly arrays, chaining and invalid type rejections. Original94 regressions were mounted from base, not candidate-editable versions. Full upstream runtime suite/browser/security audit not performed; finite green checks do not prove universal correctness. `git diff --stat` omits untracked files; vary's new `test/reply-vary.test.js` exists and was separately run.
+
+## Jev finding
+
+Scored Jev calls: **zero**. Both cells were interrupted before `delivery_design inspect`, so Jev cannot have affected those trajectories. Live integration smoke successfully called returned model `typesafe/jev-1.13-20260917`, srp.12/di.28/tests.29, no >=.5 flags, authority none. Expected blocked infrastructure handoff. This demonstrates connectivity/integration, **not efficacy**.
+
+## Context and discovery findings
+
+- Plain completed with one successful native compaction per task.
+- append/harness, append/Jev and vary/harness each had two successful native compactions before their later failure; vary/Jev had none.
+- append/harness and vary/harness failed additional compaction requests; append/Jev's final timeout was an ordinary generation request following successful compactions. Earlier chat progress overgeneralized all three as compaction failures; this report corrects that distinction based on event ordering.
+- No corrected cell reached400KB or16,384 output-token stop. This does **not** demonstrate context growth is solved: earlier stops and different tasks prevent that inference.
+- Repeated discovery and docs reads occurred before any delivery plan. 2/4/3/5 shell attempts were blocked in append/harness, append/Jev, vary/harness, vary/Jev respectively. Read-only discovery remained available; do not introduce a shell-regex permission bypass to solve it.
+- The schema document is repeatedly read and summaries grow. A focused preplanning schema guide, explicit discovery budget/checkpoint and plan skeleton authoring should be evaluated in unscored fixtures. Do not weaken exact acceptance or replace scenario reasoning with empty boilerplate.
+
+## Infrastructure deviations and preserved history
+
+Initial root `/home/baissi/benchmarks/jev-repo-pilot`: missing `/etc/hosts` meant localhost-based protected regressions failed even though numeric-address external tests worked. Initial plain append completed7/7/types with$0.0724732348 and340.232s. Initial harness append manually stopped after157.869s/$0.0415978068 with$0.15 unresolved hold. Four cells unstarted. Baseline had initially run only on host: readiness gap. Two incorrect tap-path setup commands also retained; actual repository uses Node test runner.
+
+Repair added minimal hosts/nsswitch and proved94 original tests pass **inside** namespace. Uniform fresh-root restart `/home/baissi/benchmarks/jev-repo-pilot-v2`; no first-root candidate reused/repaired. Old freeze retained separately. Same tasks/evaluators/budgets; new freeze bound mounted engine/dependencies/binary/system config. Post-run manifest verification passed before report additions.
+
+Matrix stops on infrastructure error. Supervisor inspected receipts and continued **only unstarted cells** in saved continuation scripts, without changing frozen source, request deadline or candidate outputs. Each interruption retained its unknown charge. This is a disclosed exploratory continuation, not a pristine uninterrupted randomized experiment. No extra paid diagnostic replays. Native engine attempted further requests after some failed compactions, but gateway rejected them locally after the unknown-billing stop; no additional dispatch for those rejected requests.
+
+## Accounting
+
+- Corrected six cells known **$0.1428850864**, unresolved reservations **$0.60**.
+- Initial interrupted environment known **$0.1140710416**, unresolved **$0.15**.
+- Live preflight known **$0.0113118196**, no outstanding smoke holds.
+- **Total known$0.2682679476 + unresolved$0.75 = conservative$1.0182679476**, within the newly announced$15 ceiling.
+
+Holds are not confirmed charges and may not be assumed free. No vendor account cap guarantee. Durable shared accounting `/home/baissi/benchmarks/jev-repo-pilot/campaign.json`; old$27 campaign untouched.
+
+## Recommendation
+
+Keep Jev built in and opt-in; do not advertise it as validated benefit. Pause broader paid benchmarking until an offline/cheap end-to-end fixture reliably goes from bounded discovery to plan approval, implementation, checks and final review with compaction. Investigate provider summarization deadlines without silently retrying unknown bills. Then run different held-out tickets with repetitions and the same compaction/network settings; add actual browser/API and permissioned live-research tracks on suitable infrastructure.
+
+Practical observed outcome: **plain pi delivered both changes; Carthagent is not yet reliably reaching implementation on this setup.** Provider failures block a clean quality comparison, but they do not erase the costly pre-plan discovery behavior observed before failure.
+
+## Artifacts
+
+Both roots retain raw events, sessions, invocation, gateway receipts, workspace, evaluation/type/regression/candidate-check logs, freeze manifests and continuation logs. Corrected `summary.json` is numeric overview. Setup reference/mutant results and initial failed evaluator selftest retained. No upstream pull request, deployment, primary-checkout changes, independent review or remote merge claimed.

package/docs/jev.md

@@ -0,0 +1,32 @@
+# Built-in Jev planning critic
+
+Jev is built into the delivery extension. On Carthagent Ship (managed cloud) it is **on by default** — advice rides the managed `/v1/jev` endpoint, which the backend proxies to Experiential's free System One endpoint (`jev-latest`) outside the billing gateway, so it never draws on managed usage. Presence of a credential alone never triggers paid calls on BYOK providers.
+
+```
+# Carthagent Ship: enabled automatically; opt out with a literal false value
+node bin/ctg.mjs --delivery-jev=false
+
+# BYOK providers still require explicit opt-in:
+OPENROUTER_API_KEY=... node bin/ctg.mjs --delivery-jev
+# Or with direct TypeSafe credentials:
+TYPESAFE_API_KEY=... node bin/ctg.mjs --delivery-jev --delivery-jev-provider typesafe
+```
+
+Flags must be passed to the pi/delivery session (CLI forwarding depends on invocation; `pi -e /absolute/path/extensions/delivery.ts --delivery-jev` is the direct form). Do not put keys in command arguments or project files.
+
+Schema repair is deterministic and free of advisor calls: use `delivery_design action=guide`, validate and repair references first. Invalid inspection neither dispatches Jev nor consumes an advice attempt.
+
+The disclosed semantic input includes goal, exact acceptance, **check definitions (including executable argv), outputs and assumptions**, design and workflow. These additional fields let Jev assess scenario-to-check links and promised-output coverage; they can contain confidential paths/arguments and are sent to the chosen provider only while advice is enabled (automatic on Ship). The 64KB bound still applies; larger input becomes unavailable rather than silently truncated. Commands are declarations, not proof of execution.
+
+After successful `delivery_design inspect`, the enabled critic automatically assesses the captured plan for SRP, DI seams and missing test assertions/boundaries. Ship calls go to `POST {control-plane}/v1/jev` with the session OAuth token — no provider key needed. OpenRouter uses `typesafe/jev-1.13` at its Decisions endpoint, not a chat/router model. The direct TypeSafe adapter retains its existing model configuration.
+
+- At most **three attempts per delivery run**, reserved in the report before network dispatch.
+- Identical run/revision/digest/source inspections reuse a receipt, including unavailable/interrupted attempts. Changed plans/source get fresh identities, subject to the cap.
+- Advice and its identity survive report/session restore and appear in status/recovery. Old receipts remain history, not fresh approval.
+- Probabilities >=0.5 identify investigation topics; lower scores are not flags. The model is asked to record dispositions in ordinary adversarial review. No flags does not mean correct.
+- Missing credentials, timeout and invalid data report unavailable. They do not grant approval or prevent normal review. No retries.
+- Advice cannot alter requirements, resolve blockers, authorize execution, or replace checks/final review.
+- Input max64KB, response max64KiB, OpenRouter deadline15s; direct TypeSafe retains3s default. Calls/unknown cost are visible but the normal adapter does not enforce an account-level dollar ceiling. Use provider limits or a trusted billing broker when needed.
+- An explicit `--delivery-jev-broker http://127.0.0.1:PORT/jev` uses a trusted local supervisor without sending a provider key. Non-loopback and arbitrary endpoints are rejected. This is host configuration, not a model tool parameter.
+
+Plan text is disclosed to the chosen external provider when enabled. It may contain confidential source information; no universal secret scrubber or zero-retention claim. Transport/provider failures are sanitized in reports. Jev is an additional fallible critic, not independent proof of delivery quality.

package/docs/model-registry.md

@@ -0,0 +1,25 @@
+# Carthagent model registry
+
+Carthagent discovers Claude and ChatGPT models directly from their provider
+endpoints. It does not use pi.dev's version-gated remote model catalog.
+The forked engine remains the inference/session implementation; this change
+does not replace that engine or its protocol-compatible OAuth integrations.
+
+`lib/providers/model-catalog.json` is the versioned, offline metadata catalog
+for these providers. Initial definitions were migrated from the bundled engine
+to preserve existing compatibility and pricing; future changes are reviewed
+here, independently of engine upgrades. Opus 5.5 has a 1M context window and
+128K output limit. Its price is intentionally omitted until verified, rather
+than assuming an earlier model's price. Unknown discovered models still use
+conservative provider defaults, so discovery is not a claim of verified limits.
+
+Direct discovery merges account-visible IDs with known metadata and stores a
+last-known-good discovery in `subscription-models.json`. Failed discovery does
+not replace that snapshot. The TUI reads the live registry on picker open,
+direct model selection and thinking checks. While an overlay is open, its
+existing 2.5-second state poll also refreshes the model list (local RPC only).
+
+After replacing vendor/agent, reapply `node tools/patch-model-catalog.mjs`
+alongside the compaction patch. The patch fails if its anchor changes; the
+runtime regression test rejects pi.dev requests. Other engine providers retain
+their bundled offline definitions and any native provider discovery hooks.

package/docs/native-compatibility.md

@@ -0,0 +1,117 @@
+# Native runtime acceptance matrix
+
+This is the compatibility inventory for the migration from baseline
+`599a8ad`. A name appearing in a command registry is not evidence that its
+behavior works. Default-switch approval requires the following checks against
+the installed native package.
+
+## Terminal commands
+
+| Command | Aliases / arguments | Required behavior |
+| --- | --- | --- |
+| `/help` | | CTG commands, arguments and actual native shortcuts |
+| `/resume` | `/sessions`, `[id\|name]` | Search and open native sessions; legacy results explicitly archive-only |
+| `/new` | | New independent native session, without deleting current work |
+| `/restart` | `/kill` | Interrupt/recover the selected session without restarting other sessions |
+| `/theme` | `[name]` | Native theme picker; explicit name applies; confirmation commits selection |
+| `/model` | `[name]` | Provider-aware search/selection; explicit name actually selects a model |
+| `/thinking` | | Supported variant selection, honest errors for unsupported levels |
+| `/compact` | `[notes]` | Await or report admitted compaction correctly; notes reach summary context |
+| `/autocompact` | `[on\|off]` | Preserve the requested session policy, not a misleading UI-only switch |
+| `/review` | `/review-mode`, `[ask\|yes\|no\|status]` | Persist review default/override; fresh reviewer with bounded admission |
+| `/export` | `[file]` | Complete HTML transcript, escaped content, explicit output location |
+| `/copy` | | Full last assistant response, including content beyond visible viewport |
+| `/stats` | | Actual usage/cost; unknown prices remain unknown |
+| `/clear` | | Clear presentation without deleting durable transcript |
+| `/abort` | | Stop selected session and underlying cancellable work |
+| `/raw` | `<prompt>` | Bypass framing for that prompt; keep execution policy enforced |
+| `/guide` | `[task]` | Toggle framing or send a framed task |
+| `/login` | `/auth` | Native CTG-scoped provider connection |
+| `/account` | `/cloud` | Ship credit, plan, grants, sessions |
+| `/usage` | | Recent Ship usage from the control plane |
+| `/billing` | `[checkout [plan]\|portal]` | Open the authenticated billing destination |
+| `/logout-cloud` | `[session-id]` | Revoke/remove current connection or revoke specified Ship session |
+| `/update` | `/upgrade`, `[check]` | Check/update CTG without upgrading regular OpenCode |
+| `/quit` | `/q`, `/exit` | Clean shutdown of TUI resources and terminal restoration |
+| `/workflow` | | Show authoritative execution workflow |
+| `/architecture` | | Show current architecture view |
+| `/evidence` | | Show check receipts and freshness |
+
+Delivery extension commands, including budget inspection/reset, must be listed
+by the native delivery adapter and included in the installed-host test as well.
+Built-in OpenCode command collisions must be tested through actual typed input.
+
+## Launcher
+
+Preserve `tui/ui/interactive`, `resume/sessions`, `continue`, `demo`, `status/s`,
+`check/c`, `hash/fingerprint`, `validate`, `login/auth`, `account/cloud`,
+`billing`, `logout-cloud`, `serve/web/start`, `test`, `eval`, `review`, `update`,
+`help/--help/-h`, `--version/-v`, `--list-models`, and bare/prompt invocation.
+
+Preserve provider/model/thinking/theme, engine executable override aliases,
+session selection, validators/context, shell and session budgets, review mode,
+extension/skill isolation, strict/standard workflow, framing, glyph tier,
+codegraph cap, demo, print and JSON flags. Validate before starting work.
+The `--` separator must allow literal prompts beginning with a dash.
+
+Headless output needs real terminal success/error/cancel classification,
+bounded cancellation, and a documented JSONL contract for evaluation consumers.
+`ctg review` preserves exits 0 (approve), 1 (changes requested), and 2
+(inconclusive/infrastructure failure). Admission limits do not reset on restart.
+
+## Cross-cutting gates
+
+- Two simultaneous tasks in different worktrees cannot share active contracts,
+  budget counters, Ship telemetry identities, or review receipts.
+- Normal OpenCode configuration, credentials, service and sessions remain
+  separate. Project/ancestor/home discovery and inherited environment settings
+  must be probed, not inferred from XDG paths alone.
+- Workspace tools retain the intended user environment; host isolation must not
+  redirect unrelated tools' config/cache/credentials.
+- Reconnect restores snapshots after lost events. Cached stale data cannot
+  produce a verified/reviewed state.
+- Unicode/large paste, selection, clipboard, terminal title restoration, narrow
+  layout, picker keyboard navigation and cancellation work under a real PTY.
+- Package-owned runtime resolves from a fresh production-only install on the
+  supported platforms. Package contents exclude workspace dependency folders.
+- Deterministic software-engineering fixtures execute native tools, edit code,
+  run failing/passing checks, and exercise recovery. Mocks alone do not prove
+  runtime integration.
+
+## Performance measurements
+
+Targets remain input p95 at most 50 ms, warm session switch p95 at most 150 ms,
+cached workspace load at most 300 ms, bounded plugin memory and no plugin-owned
+idle redraw loop. Startup time in the bootstrap PTY smoke includes intentional
+input delays and must not be reported as a performance measurement.
+
+## Executable native-host evidence
+
+The following probes use a disposable profile and deterministic loopback provider.
+`CTG_OPENCODE_BIN` can select an explicit test binary; the default is the pinned
+package-owned `node_modules/@opencode/cli/bin/opencode.exe`. An optional first
+argument selects an installed plugin directory.
+
+- `node tools/test-native-controls.mjs`: concurrent framing/raw admission,
+  persisted launcher settings and framing overrides, compaction notes reaching
+  the summary request, cross-location RPC rejection, and whole-service restart
+  with authoritative session snapshots.
+- `node tools/test-native-outcomes.mjs`: provider rejection produces a failed
+  outcome; interrupt closes an in-flight provider request; a neighboring session
+  succeeds; the interrupted session recovers with its history preserved.
+- `node tools/test-native-delivery-host.mjs <plugin-dir>` loads the production
+  `setupCarthagent(..., { delivery: true })` composition, not the isolated test
+  plugin. Scenarios cover standard/strict delivery, explicit `delivery:false`,
+  configured budget interruption (`resume:false`), mixed session settings, and
+  simultaneous identical shell commands in one worktree with per-session counts.
+- `npm run test:native-package` repeats those probes against the packed,
+  production-only installed artifact. In OpenCode 2.0.32, `ShellCreateBefore`
+  lacks session/call identity, so it is never used for attribution or charging;
+  the authoritative `tool:execute.before` event supplies session/call identity.
+
+Native `session.wait()` can resolve before the durable session projection exposes
+its terminal outcome. Consumers must reconcile within a bounded deadline and
+treat a missing outcome as unresolved. Assistant errors appear as `finish: error`
+with error details; terminal outcomes are recorded by the final `idle` message.
+These probes establish host behavior; delivery adapters, CLI output and installed
+UI integration still require their own acceptance checks above.

package/docs/opencode-archive.md

@@ -0,0 +1,9 @@
+# Native legacy archive RPC
+
+`carthagent.archive` exposes the old Pi session JSONL transcripts as an explicitly read-only archive. It never writes to them and never treats an archive as a live OpenCode session. Clients call `list`, `search`, `read`, or `export` using an opaque SHA-256 transcript ID returned by `list`/`search`; filesystem paths are not part of the RPC contract. Export returns JSON or original JSONL content to the client. Any HTML rendering or save destination is a client responsibility.
+
+## Root configuration and limits
+
+The host registers the RPC with trusted server-side options: `registerArchive(ctx, { archiveRoots: ['/absolute/path', ...] })`, or the legacy single `archiveDir`. Caller-supplied roots and paths are never accepted. Native hosts should pass the archive directory resolved from the user's original profile/home; if no option is configured, the server falls back to `~/.carthagent/agent/sessions` under the plugin process home. No shared environment discovery is performed. Roots must be normalized absolute paths using the current platform's path rules. Symlinks are skipped and canonical file paths are checked against their configured root.
+
+Directory scanning uses streaming `opendir` traversal, checks cancellation throughout async enumeration and descriptor reads, and rejects more than 10,000 entries (including directories) or 2,000 transcripts. Before reading bytes, the server opens the leaf with no-follow semantics, resolves the current path and checks the opened descriptor's `fstat` device/inode against the resolved path's stat, and confirms the resolved target remains under the canonical configured root. This rejects an ancestor directory replaced by an escaping symlink between enumeration and open. Node does not provide portable `openat`/directory-handle-relative traversal, so this is a point-in-time path/descriptor verification rather than an atomic guarantee against a privileged concurrent actor repeatedly renaming ancestors after verification; reads stay bound to the already-verified descriptor. File sizes are obtained from `fstat` immediately before reads, with a 4,000,000-byte per-file cap and 50,000,000-byte total cap. Reads are chunked and enforce the cap independently of enumeration. Parsed JSONL retains valid records and reports bounded malformed-line diagnostics; response parsing is limited to 10,000 rows. List/search pages contain at most 100 items; search queries are limited to 200 characters and excerpts to 400 characters. `archiveOnly: true` marks non-live status. Each method declares `archive_error` with `invalid_request`, `not_found`, `limit_exceeded`, and `archive_io` codes; request schema violations are rejected by the RPC layer as invalid input.

package/docs/opencode-migration.md

@@ -0,0 +1,115 @@
+# Native OpenCode migration
+
+## Product contract
+
+Carthagent is moving to OpenCode 2's native terminal host and agent runtime.
+The supported workflow is CTG-only and local: project, task, worktree, session,
+evidence, independent review. Agent of Empires informs the workspace workflow;
+its Rust/tmux runtime is not a dependency. Existing Pi sessions are read-only
+archives. New sessions use a CTG-owned OpenCode service and state namespace.
+
+The delivery contract, required validators, fingerprints, check evidence,
+standard/strict workflow distinctions, budget admission and review receipts
+remain Carthagent domain behavior. A completed model response is not a verified
+delivery. Events invalidate cached state; snapshots restore authoritative state
+after reconnect.
+
+## Baseline
+
+- Source baseline: `599a8ad19836788a6aaa8a4ce24865e20c211388`.
+- Development package: 1.0.3; local installed package at discovery: 1.0.1.
+- Target host: OpenCode 2.0.32.
+- Authoring/client packages: `@opencode/plugin` and `@opencode/client` 2.0.32.
+- Runtime package: pinned `@opencode/cli` 2.0.32. Its platform-specific optional
+  package is installed/materialized by npm postinstall; CTG must invoke this
+  package-owned binary, never replace or upgrade a user's global OpenCode.
+- Authoring renderer peer baseline: OpenTUI 0.5.17, Solid 1.9.12 (the exact
+  Solid peer required by the published OpenTUI package). The host owns runtime
+  module resolution; installed-package tests must prove compatibility. The npm
+  lock pins transitive `seroval` to patched 1.6.9 (compatible with Solid's
+  `^1.0` range) while the required Solid peer is still 1.9.12.
+- The user's original checkout contains unrelated in-progress work and is not
+  the integration checkout. Title and copy/paste fixes are in the baseline.
+- Baseline quality passed: lint, typecheck, syntax build, 474/474 tests.
+- Executable host probe: `npm run test:native-host` launches a disposable,
+  authenticated 2.0.32 server, loads CTG, validates its health RPC and tears down
+  the owned process. It does not test complete product isolation or native UI.
+- Local directories on 2.0.32 require root `index.ts` and `tui.ts` entrypoints;
+  package `exports` alone did not load. Keep both forms for packaged/local use.
+- Plugin inventory can initially be empty during activation. Readiness must
+  wait for the actual CTG plugin, not just a healthy HTTP listener.
+- Packaged-artifact probe passed after `npm pack` and a clean
+  `npm install <tarball> --omit=dev`: server plugin discovery, authenticated RPC,
+  rejection of unauthenticated requests and invalid RPC input. The TUI feature
+  is discoverable; rendering and interaction still need their separate gate.
+- `npm run test:native-package` verifies the npm tarball excludes `node_modules`,
+  contains the server and TUI entrypoints, installs with production dependencies
+  into a clean prefix, resolves the platform binary from
+  `node_modules/@opencode/cli/bin/opencode.exe`, and starts the isolated server
+  using that exact binary. CI also runs the owned binary server test on each
+  supported OS/Node matrix row; the PTY check is explicitly Unix-only.
+- Linux PTY diagnostic passed with the native `/ctg-status` command rendering
+  its RPC result. Global commands need `mode: 'global'` in the keymap layer;
+  omitting it registered a plugin but left its slash command undiscoverable.
+  This is a bootstrap test, not approval of the upcoming full product UI.
+- `node tools/test-native-controls.mjs` exercises two concurrent sessions through
+  a local deterministic provider on the real 2.0.32 host: delivery framing,
+  explicit raw bypass, successful terminal outcomes and compaction notes in the
+  actual summary request. Compaction notes use a queued synthetic message because
+  the native compact API has no notes parameter; the host can process that
+  message in a primary turn before summarizing it.
+
+## Delivery ledger
+
+Each row requires executable evidence, independent review and an exact-head
+integration check before its PR merges. In-progress does not mean shipped.
+
+| Workstream | State | Acceptance |
+| --- | --- | --- |
+| Baseline/build contracts | In progress | Existing checks recorded; new TS/TSX included in checks |
+| Runtime/isolation | In progress | CTG and normal OpenCode coexist; authenticated persistent service |
+| Native plugin host | In progress | Installed package loads server and TUI entrypoints |
+| Providers/auth/telemetry | In progress | Concurrent requests/refreshes maintain credential and session identity |
+| Delivery/policy/budgets | In progress | Native execution preserves evidence, validators and recovery |
+| Native theme/commands/panels | In progress | CTG commands work; host owns input/rendering; semantic themes |
+| Workspace/worktrees | In progress | Independent worktrees and durable task/session mappings |
+| Review | In progress | Fresh-context findings bound to source and PR head; bounded admission |
+| Legacy archive | In progress | Read-only searchable transcripts; no implicit continuation |
+| CLI/headless/dashboard | Pending | Output/exit/locking behavior verified against native runtime |
+| Packaging/upgrade | Pending | Fresh installation and migration tested from packaged artifact |
+| Terminal/performance | Pending | PTY, interaction, streaming and reconnect evidence |
+| Default switch/retirement | Pending | No supported default execution path depends on Pi |
+
+## Review workflow
+
+Implementation uses `lattice/gpt-6-luna#high` in separate worktrees. A different
+fresh-context Luna session reviews each PR. The parent integrator checks the
+actual diff, tests, integration contracts and exact head before merging. New
+commits invalidate the previous head's approval. No implementation agent merges
+its own work. Required CI remains authoritative; failures are not converted to
+success by documentation or model verdicts.
+
+## Important compatibility decisions
+
+- Preserve CTG slash names, aliases and arguments through one command manifest.
+- `/raw` bypasses prompt framing, not execution policy.
+- `/restart` must not restart every session's shared service.
+- `/clear` must not delete durable transcript history.
+- Existing `--isolate` means extension/skill discovery isolation, not a worktree.
+- `.harness` state remains per worktree; project views aggregate it.
+- Independent worktree tasks use explicitly located sessions. Native child
+  sessions inherit their parent's location and are not assumed isolated.
+- Ship telemetry must be request/session scoped, never one process-global
+  current session. Rotating credentials require serialized atomic refresh.
+- CTG runtime XDG overrides must not leak into workspace command environments.
+- Theme names remain compatible; V1 token objects must be converted to V2.
+- Legacy transcripts are archives. No experimental transcript import is needed.
+
+## Evidence policy
+
+Use deterministic offline provider fixtures for automated integration and PTY
+tests. External repository fixtures are pinned and isolated. Paid model
+comparisons require a separately recorded spending cap and are not necessary to
+prove deterministic runtime integration. Record native terminal/platform gaps
+explicitly. Saved screenshots or recordings are not visual approval by
+themselves.

package/docs/opencode-runtime.md

@@ -0,0 +1,94 @@
+# CTG native OpenCode runtime
+
+CTG runs the package-owned native OpenCode v2.0.32 CLI from the pinned
+`@opencode/cli` dependency. It never downloads, replaces, or implicitly uses a
+user installation. An explicitly supplied `CTG_OPENCODE_BIN` is accepted only
+when its version is exactly 2.0.32.
+
+## Isolation and persistence
+
+The default CTG profile is `~/.carthagent/opencode`. `CTG_OPENCODE_HOME` (or a
+`root` argument in the runtime API) can select another profile. CTG applies
+private `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, and
+`XDG_CACHE_HOME`, plus `OPENCODE_DB`, to native child processes. Config,
+database, credentials, service registration, and cache therefore do not touch
+the normal OpenCode service/profile. Profile directories are mode 0700 and
+generated config is mode 0600. It also sets a private `HOME`,
+`OPENCODE_TEST_HOME`, and `OPENCODE_CONFIG_DIR`, and uses OpenCode 2.0.32's
+supported `OPENCODE_CONFIG_PROJECT_DISABLE` switch to disable project config
+discovery. All inherited `OPENCODE_*` variables are removed before setting
+CTG-owned profile values. It never copies user credentials. Authenticate with
+the CTG-owned service to keep credentials independent. Workspace-local tool execution uses OpenCode's
+session environment endpoint and retains the caller's existing environment.
+
+The normal subprocess environment remains unchanged in the workspace. Use
+`workspaceEnvironment(workspace, env)` to prepare the workspace process
+environment; it adds the workspace marker but deliberately does not override
+host XDG values. `setSessionEnvironment(service, sessionID, env, { location })`
+applies it to native shell commands for that OpenCode session. TUI launch retains
+the isolated OpenCode configuration while inheriting the workspace's actual
+credentials through its normal parent environment.
+
+## Runtime API
+
+`lib/opencode/runtime.mjs` exports `runtimePaths`, `runtimeEnvironment`,
+`provisionRuntime`, `resolveOpenCode`, `runCapture`, and
+`workspaceEnvironment`. Provision with `pluginPath` pointing to the absolute
+CTG plugin entry path (`plugins/carthagent`); this runtime does not bundle or
+resolve the plugin on behalf of the CLI integration.
+
+`lib/opencode/service.mjs` exports `ensureService`, `serviceRequest`,
+`createSession`, `getSession`, `promptSession`, `cancelSession`, `sessionMessages`,
+`setSessionEnvironment`, `stopService`, and `launchTui`. `ensureService({ root, pluginPath, profile, startupTimeout })`
+returns the isolated service URL, auth headers, registration metadata, paths,
+and executable after a health/version/PID check. Startup is bounded (20s by
+default), concurrent ensure/stop calls serialize on one profile lifecycle lock,
+and no normal OpenCode service is stopped or restarted. Use `launchTui` to open the
+native OpenCode TUI pointed at CTG's environment, preserving workspace cwd and
+native session flags.
+The TUI attaches with the native CLI `--server` option and CTG service password;
+it does not discover or start another background service. `runHeadless` accepts
+an optional `timeout` in milliseconds (120 seconds by default), aborts the wait
+request and interrupts the session on timeout/cancellation, and returns message
+history in chronological order with the latest assistant result reconciled to
+the newly accepted prompt.
+`stopService({ root })` stops only the healthy process identified by that
+profile's private registration. If a registered process is alive but unhealthy,
+the registration is retained and an error is reported rather than orphaning or
+duplicating the daemon. Lock recovery removes only dead-owner or sufficiently
+old incomplete lock files. A persistent recovery marker causes bounded failure
+with manual lock-file recovery guidance; CTG does not guess whether another
+recovery owner is still active.
+
+`lib/opencode/headless.mjs` exports `runHeadless` and the session helpers. It
+uses native `/api/session`, `/prompt`, `/message`, `/interrupt`, environment,
+and wait APIs. It polls the session projection and returns the refreshed session,
+terminal outcome (`succeeded`, `failed`, `interrupted`, or `timed-out`), accepted
+input, chronological messages, and the assistant result. Provider failures and
+missing terminal outcomes are never reported as success. Polling handles transient
+503 responses within the configured timeout; cancellation uses `resume=false`
+and bounded requests. Slash templates
+can be mapped through `nativeCommandConfig` in `compatibility.mjs` into native
+OpenCode `commands` configuration. A real-host check is available via
+`npm run test:native-host`; it uses disposable roots and validates native plugin
+activation, RPC execution/result, and schema failures against v2.0.32.
+
+The native CLI integration can use these signatures directly:
+
+```js
+const service = await ensureService({ root, pluginPath, profile });
+const session = await createSession(service, workspace, { body: { title } });
+await setSessionEnvironment(service, session.id, process.env, { location: workspace });
+const result = await runHeadless(service, workspace, prompt, { signal, env: process.env });
+const tui = launchTui(service, workspace, { sessionID: session.id, env: process.env });
+await stopService({ root });
+```
+
+`runHeadless` returns `{ session, accepted, messages, result, outcome, terminal,
+error, reason, budgetReason }`; `result` may be absent if the turn produced no
+assistant message. Supply `location` to session helpers when the session's
+workspace differs from the default.
+
+Legacy CTG sessions are intentionally not imported into OpenCode. Keep any
+archive/recovery policy in CTG's existing session store; this runtime only
+creates native OpenCode sessions in the isolated profile.

package/docs/opencode-workspace.md

@@ -0,0 +1,31 @@
+# CTG native OpenCode orchestration
+
+CTG's native workflow treats a task, worktree, and session as a durable logical unit. New task sessions are independent root sessions created with an explicit `location.directory`; CTG deliberately does not create OpenCode child sessions because native children inherit the parent's location. Each native worktree keeps its own `.harness` evidence naturally, while the project-level canonical checkout stores `.harness/opencode-tasks.json` as the task relationship and operation journal.
+
+The `carthagent.workspace` RPC bridge runs inside the actual OpenCode plugin `Context`. The plugin API has no session-list operation: the server can inventory durable task sessions from task records and in-flight operation journals, then fetch each through native `session.get` and retain it only when its native project ID and location match the project root or that task's recorded worktree. This means the plugin RPC cannot enumerate untracked UI-created sessions; the native TUI client can and should combine its own global session list with this durable server snapshot. Session execution state is `running`, a native terminal outcome, `unknown` (no authoritative lifecycle information), or `unavailable` (the native record could not be fetched); task status never guesses idle from an absent outcome. The UI should use its native session status for ordinary sessions.
+
+Delivery status reads `.harness/active.json` rather than selecting a report by modification time, validates the selected report, verifies that its run directory belongs to the requested session, and evaluates check receipts against the current source fingerprint and plan identity. Review is reported unavailable/stale when appropriate; starting a local review rechecks session ownership, snapshots exact local source, launches a location-bound reviewer, and persists the source-bound result. Native session status and execution lifecycle events emit the shared `updated` RPC event; only project-root and recorded task-worktree locations are accepted. Registration is awaited before the event listener starts, and cleanup aborts the stream and disposes the RPC. Legacy transcript import/export is not part of this RPC contract yet; the existing archive helpers are read-only and can be exposed after the shared contract is extended.
+
+The native API requires `projectID` for worktree create/list/refresh/remove. Use `ctx.location.project.id` and `ctx.location.project.canonical`, the latter as the canonical plugin/configuration root. Live `session.*` and `worktree.updated` events are invalidation hints only: re-fetch native and CTG task state; do not treat events as durable state or replay missed events.
+
+## Durable operations
+
+Each create intent is persisted before calling the OpenCode APIs. Successful worktree + root session creation completes the journal entry and records the task. If the operation fails between native API calls, its intent remains `recovery-required`; reconciliation only repairs outcomes that can be verified and never blindly retries a worktree/session create. The JSON state is atomically replaced, and a cooperative exclusive lock serializes local CTG writers. A leftover lock is an explicit recovery condition, not an invitation to steal it automatically.
+
+## Legacy Pi archive
+
+Pi JSONL files are read-only archive inputs. Listing, searching, transcript display, and JSON/JSONL export are supported; malformed lines are reported with line numbers and valid records remain available. This code does not import, migrate, mutate, or resume archived sessions. All new work starts in a fresh OpenCode session.
+
+## Reviews
+
+Local delivery review and remote PR review are separate modes. Local delivery review snapshots the exact local diff and HEAD, opens a fresh explicitly located reviewer session, validates only the final assistant text plus a successful session outcome, and rechecks that both source and HEAD remain unchanged before admitting the result. Reviewer sessions use the registered native `build` agent by default with deny-all permissions followed by explicit read/glob/grep allows, blocking shell execution, edits, Code Mode, subagents, and skills. Review waits are abortable and default to a bounded five-minute timeout; cancellation uses the native `continue: false` interruption input and reports if interruption was not confirmed. Structured, validated findings are persisted in the review receipt. PR review queries GitHub via authenticated `gh api`, fetches the authoritative head/base refs into dedicated local refs, derives source from those exact Git objects, and re-fetches metadata and objects after review before recording a verdict. The repository and PR number are inputs; refs/source are never caller-supplied. GitHub CLI authentication is required. Existing `.harness/reviews` state via `lib/review-state.mjs` enforces the three-attempt limit. Neither mode pushes or merges. The default reviewer model is `lattice/gpt-6-luna` variant `high`, configurable by the service. No automatic merge permission is granted.
+
+## Reusable module contracts
+
+- `createTask({ ctx, projectID, canonical, task, from?, branch?, model?, agent? })` returns a persisted `{ id, task, projectID, canonical, worktree, sessionID, parentTaskID, status, createdAt }` task record.
+- `listTasks({ canonical, includeOperations? })` returns the records, optionally with the operation journal.
+- `listNativeSessions({ ctx, canonical, projectID })` verifies journaled root sessions using the supported `ctx.session.get` API; the plugin `Context` does not expose a session-list method. `listNativeWorktrees({ ctx, canonical, projectID })` uses only native `ctx.worktree.list({ projectID })` inventory.
+- `reconcileTasks({ canonical, projectID, sessionIDs, worktreeDirectories })` returns `{ tasks, operations }` without retrying APIs, scoped to the native project ID. In-process pending operations remain pending during concurrent reconciliation; restart-interrupted operations are adopted only when both the native session and worktree inventories prove their completion.
+- Archive exports: `listLegacyArchive({ roots })`, `searchLegacyArchive({ roots, query })`, `readLegacyTranscript({ path, roots })`, and `exportLegacyTranscript({ path, format?, roots })`. Reads require configured archive roots; symlink files/directories and real paths escaping roots are excluded or rejected.
+- Review exports: `startReview({ ctx, cwd, identity?, model?, agent?, signal?, timeoutMs? })`, `startPullRequestReview({ ctx, cwd, repository, prNumber, model?, agent?, signal?, timeoutMs? })`, `createReviewSnapshot({ source, head })`, and `verifyPullRequestHeads({ localHead, remoteHead, pullRequestHead })`. PR metadata/source commands run via the real `gh` and `git` executables; there is no injectable production command runner. Reviewer agent defaults to the registered native `build` agent and is checked before session creation. Timeout defaults to 300000 ms (maximum 300000); caller cancellation and timeout abort native requests and attempt a bounded interrupt of an already-created reviewer.
+- `registerOrchestration(ctx, options?)` in `plugins/carthagent/src/server/orchestration.ts` returns these operations in a server-oriented facade and an event `watch(signal)` invalidation stream.

package/docs/owned-runtime-workflow-registration.md

@@ -0,0 +1,17 @@
+# Owned-runtime workflow registration bootstrap
+
+This PR registers `.github/workflows/publish-owned-opencode-runtime.yml` on
+`main` so GitHub can expose its `workflow_dispatch` entry point. The workflow
+was copied byte-for-byte from reviewed source candidate
+`70882269e25ebcb62c843f9265345342b9e6844d`; its checkout and build inputs are
+selected by explicit reviewed source SHA, so this registration PR does not
+include or imply approval of the product candidate.
+
+After this bootstrap is independently reviewed and approved/merged, a
+non-publishing prebuild may be dispatched against the reviewed source branch
+only after that exact source candidate receives independent approval. The
+workflow binds the requested source SHA to the dispatch commit. Publish mode
+remains restricted to the default branch and revalidates the exact final
+package manifest and immutable candidate bytes. This PR does not authorize a
+dispatch, build, publish, or release upload; each requires its own review and
+approval.

package/docs/plan-advisor-evaluation.md

@@ -0,0 +1,38 @@
+# Optional plan advisor: evaluation, not approval
+
+The deterministic planning gate works without Jev, credentials or network access. `lib/plan-advisor.mjs` defines an injected classifier port; `lib/jev-advisor.mjs` adapts the documented TypeSafe Noul API. Neither imports approval policy or mutates delivery state. Suggestions route SRP, DI and test-gap concerns to adversarial review; a probability is not a defect receipt or permission to implement.
+
+## Explicit opt-in
+
+```sh
+# No network, no credentials: no-advisor baseline
+node tools/evaluate-plan-advisor.mjs tests/fixtures/plan-advisor-corpus.json
+
+# Optional live evaluation: explicitly transmits design/acceptance/workflow to TypeSafe
+TYPESAFE_API_KEY=... node tools/evaluate-plan-advisor.mjs your-reviewed-corpus.json --jev
+```
+
+Do not put secrets or private source into planning artifacts sent to an external provider without authorization. Only goal, acceptance, design and workflow are transmitted, not arbitrary top-level state, but those fields may themselves contain sensitive data. The adapter does not claim automatic redaction or default zero retention. No live request was made during this implementation. The default provider model is pinned to `jev-1.13.0`; the adapter accepts an explicitly configured model for later evaluation.
+
+The adapter has a 3-second default deadline, no retries, a conservative 64KB request cap and 64KB streamed response cap, rejects redirects, malformed probabilities, missing model identity and provider errors. Failure returns `unavailable` with `authority:none` and cannot weaken deterministic gates. Unknown cost is `null`, not zero. Optional injected input pricing yields an estimate, not billing evidence.
+
+## What was actually evaluated
+
+- **Local quality: 348 tests**, including no-key operation, injected classifier immutability, typed HTTP request/response contract, timeout even for an uncooperative fake, invalid/oversized response, missing key, HTTP errors and sanitized failure output. A real loopback HTTP server exercises the fetch/streaming adapter and cancellation of a delayed body; no external service is used.
+- **Three-case, supervisor-authored illustrative corpus**: cohesive pure policy, mixed policy/hidden network, and missing parser failure cases. This is neither blind nor representative. Labels are judgments, not independently adjudicated truth. The corpus tests evaluation plumbing, not production readiness.
+- No-advisor baseline: 9 category decisions, 4 false negatives, 5 true negatives, no positive alerts, undefined precision/Brier score and unknown cost. This is an intentionally silent baseline, **not a comparison against Carthagent's deterministic validator or generative review**.
+- Injected probability fixture: one true positive, one false positive, one false negative, Brier score approximately 0.4467. These values test metric calculations only; they are not Jev measurements.
+- **No live Jev accuracy, calibration, latency, cost or net-value claim.** The adapter remains off the normal delivery path until a properly labeled comparison establishes useful additional findings over deterministic + generative review, with acceptable missed defects, false alarms and privacy/cost trade-offs.
+
+The evaluator reports TP/FP/FN/TN, precision, recall, Brier score, availability failures, measured local request duration and known/unknown cost separately. Brier score on a tiny corpus is not evidence of general calibration. Future evaluations should retain raw outputs, provenance, human adjudication, false-negative examples, domain strata and a no-Jev generative-review baseline.
+
+## Primary API sources
+
+The request and response contracts were verified against retrieved primary documentation (not merely search snippets):
+
+- [TypeSafe API](https://docs.typesafe.ai/api): `POST /v1/systemone`, typed questions, Noul answers and usage fields.
+- [Model documentation](https://docs.typesafe.ai/models): model identities and vendor-listed pricing/limits.
+- [Known weaknesses](https://docs.typesafe.ai/model-jaggedness/jev-1.13): numeric, multi-hop and cross-question consistency limitations.
+- [Confidence](https://docs.typesafe.ai/confidence): confidence is not an independent correctness oracle.
+
+Vendor performance claims are not independently replicated here. Optional integration is deliberately an evaluation boundary, not a mandatory dependency or an approval authority.

package/docs/planning-startup-fix-plan.md

@@ -0,0 +1,23 @@
+# Planning startup repair — design and author challenge
+
+Reconstructed after the temporary worktree disappeared. Committed benchmark evidence remains unchanged. New persistent worktree: `/home/baissi/ctg-planning-startup`.
+
+## Goal and scope
+
+Pilot treatments consumed19–54 tools in discovery without a plan. Guide the model into an accurate initial contract sooner without dropping requirements or weakening gates. Provider timeouts remain a separate unresolved problem. No paid benchmark or automatic retry in this change.
+
+## Design
+
+- Pure `planning-guide.mjs`: short exact field guide, illustrative example tested with production validators, actionable reference diagnostics. Never synthesize/approve a user's plan.
+- Pure `planning-discovery.mjs`: numeric branch-restored pre-plan checkpoint. After8 completed discovery results or2 blocked implementation attempts, recommend first plan or ONE focused unresolved question; after16 reads emphasize expanding discovery. Advisory only; necessary reads always remain available. Restore bounded numeric fields defensively. New user prompt starts a checkpoint; existing/informational plans suppress it.
+- Extension composition: `delivery_design action=guide` works without plan, source fingerprint or workspace mutation. Short startup guidance replaces blanket instructions to read long docs. Checkpoints injected outbound only and persisted as numeric custom entries; no approvals/secrets/requirements stored there. Successful plan suppresses reminders.
+- Deterministic validation: offending component/check/requirement references reported alongside allowed IDs. Preserve finding codes/severity, exact acceptance, user validators, blockers and approval policy.
+- Jev semantic context: include existing check definitions, outputs and assumptions in both built-in adapters; judge scenario-to-check adequacy, not syntax. Same bounded input/output, opt-in, identity-bound3-attempt cap. Invalid plans cannot inspect or invoke Jev; schema repair costs zero calls. Document added external disclosure.
+
+## Challenge (author review, not independent approval)
+
+Hard discovery cutoff could force guessed designs: rejected. Automatic boilerplate scenarios could launder semantic quality: rejected. Probabilistic schema validation is unnecessary/unsafe: rejected. Do not expand a mandatory schema or repeat full examples each turn. Checkpoint classification is heuristic and cannot authorize anything. Restored state must come from active branch, not an unrelated newer branch. No reapproval on normal implementation edits. Advice bounds/timeouts/gates remain unchanged. More Jev context can hit64KB earlier; report unavailable rather than truncate exact obligations or retry. No claims these changes fix provider reliability or prove model improvement.
+
+## Acceptance/tests
+
+Guide example passes real validators and stays small. Unknown references remain blocking and actionable. Checkpoints survive compaction/restoration, reset on input, stop on plan, do not nag questions or block reads. Full extension loop guide -> bad schema -> repair -> captured valid plan -> local mock Jev -> self-review -> approval -> edit -> real check -> final diff review -> verified; assert no Jev before valid inspect and preserved exact obligations. Existing stale-source/blocker/user-validator suites remain green. Both adapters send new context unchanged, preserve no-mutation/bounds. Scripted installed-engine offline smoke if available verifies guide/checkpoint/tool pairing, not model efficacy. Focused tests then full quality; preserve all historical artifacts.