carthagent 1.0.7 → 1.1.0-preview.13

package/docs/help-dispatch-review.md

@@ -0,0 +1,69 @@
+# Natural `/help` dispatch patch review
+
+Standalone upstream patch: `docs/patches/opencode-v2.0.32-help-dispatch.patch`
+
+- Upstream baseline: OpenCode `843a6c514e606b436a7fe713422ace0a93ad3d61` (v2.0.32)
+- Upstream implementation commit: `75fea3b9475da6bbc59c5eeb6461a2994c84341b`
+- Final upstream source including review corrections: `242cbb79cab1b473b63e5abbc29973cf6938ecbc`
+- Patch SHA-256: `c1ce7d983be8ecdd3481b16da103fb32d144b0ec01f894915a110b46acdc6fe5`
+
+The TUI's native `/help` command is a fallback rather than an exclusive
+reservation. Autocomplete presents one `/help` option: the most recently
+registered non-native extension command, or native `help.show` if no extension
+claims the name. Direct Enter dispatch applies the same last-extension-wins
+rule. Other argument-taking slash commands retain their previous first-match
+dispatch behavior. When a plugin is disabled/deactivated, disposing its keymap
+layer removes its claim; autocomplete and Enter then fall back to native help.
+Duplicate extension claims are deterministic: the last registered extension
+owns `/help` until its layer is disposed, then the previous extension (or native
+help) is revealed.
+
+## Focused regression test
+
+Test: `packages/tui/test/plugin-keymap.test.tsx`,
+`a plugin /help overrides native /help for natural autocomplete selection and restores it on disable`.
+
+Run from `packages/tui` with Bun 1.4.2:
+
+```sh
+bun test --timeout 30000 --test-name-pattern 'plugin /help' test/plugin-keymap.test.tsx
+```
+
+Result on final source: focused test **1 passed, 0 failed**; the complete
+`plugin-keymap.test.tsx` file **5 passed, 0 failed**. The fixture types `/help`
+while autocomplete is open and presses Enter once without escaping or
+dismissing it. Two plugin commands claim `/help`; the later handler runs. The
+test verifies no `/session` request was made, disables the plugin through the
+plugin UI, then submits `/help` again and verifies native help appears, also
+without a session request. The fixture uses bare, no-argument `/help`, matching
+the CTG command definition.
+
+## Broader test observations
+
+An intermediate unfiltered run failed the existing test `setup layers before
+and after await reach keyboard, palette, and slash across disable and enable`:
+the new test's `help-override` query had accidentally been applied to that
+existing test even though it registered `setup-keymap`. The query was restored
+to the existing helper default; the help-specific query is used only by the new
+test. The captured full-file run then passed **5/5**. This was an actual test
+regression in the intermediate branch and is corrected in the published head.
+
+Baseline control: the unmodified `843a6c5` worktree ran the existing
+`setup layers before and after await...` test alone and passed (**1 passed, 0
+failed**). Final corrected source ran the entire test file successfully (**5
+passed, 0 failed**).
+
+## Typecheck and fixture limits
+
+`bun run typecheck` from `packages/tui` was attempted using the available shared
+dependencies. It emitted broad unrelated diagnostics across `packages/core`
+and source files resolved from the dirty prototype checkout (including missing
+workspace packages, Node/DOM/Bun globals, and Effect type errors), then exceeded
+the 120-second timeout and was terminated. This environment did not provide a
+valid full-package typecheck result. The autocomplete optional `command.slash`
+access is explicitly guarded before reading `slash.arguments`.
+
+The test runner prints an existing `MaxListenersExceededWarning` for renderer
+resize listeners; it also occurs in the baseline control. No assertions were
+weakened. The final-binary PTY proof is deferred until composition with the
+independently reviewed session-ui and theme patches and the pending glyph work.

package/docs/legacy-cli.md

@@ -0,0 +1,150 @@
+# Current default CLI: install, providers, Ship, and console
+
+> This page documents the **currently-default regular (legacy) CLI** while
+> native OpenCode remains opt-in with `CTG_NATIVE=1`. Its configuration and
+> data paths are not the native OpenCode profile. Keep this guide available
+> until the native default switch is accepted; it can then be archived or
+> retired as part of that migration.
+
+## Install the current CLI
+
+Core CLI requires Node ≥ 22.19. Optional workflows may need Git and an
+authenticated `gh` for PR review, Python and scenario dependencies for game
+graders, and a browser download for real-browser checks. The browser helper
+downloads `chrome-headless-shell` on first use to `~/.carthagent/browser/`; no
+local browser installation is needed. An external WebDriver endpoint is also
+supported.
+
+Install Carthagent:
+
+```sh
+npm install -g carthagent
+ctg
+```
+
+If the shell cannot find `ctg`, restart the terminal and confirm npm's global
+executable directory is on `PATH` (`$(npm prefix -g)/bin` on Linux/macOS; the
+directory shown by `npm prefix -g` on Windows).
+
+If npm reports `ENOTDIR`, `EEXIST`, or `ENOTEMPTY` while replacing
+`node_modules/carthagent`, inspect the global install directory for a stale
+entry from an earlier install or `npm link`. Preserve anything you need before
+moving only the identified stale entries out of the way; then retry:
+
+```sh
+npm root -g
+# After reviewing the exact paths, move the stale carthagent entry/stash aside.
+npm install -g carthagent
+```
+
+The regular CLI's `ctg update` has cleanup-and-retry behavior for these stale
+global-install rename failures. Do not apply that legacy updater behavior to the
+native updater, which has a different contract; see [native upgrade guidance](native-upgrade.md).
+
+For a development checkout:
+
+```sh
+git clone https://github.com/B-icy/Carthagent
+cd Carthagent
+npm ci && npm install -g .    # or run node bin/ctg.mjs directly
+```
+
+## Provider authentication
+
+The regular CLI stores its provider credentials in
+`~/.carthagent/agent/auth.json`; the native preview has a different isolated
+credential store and profile. Do not copy or merge profile files to switch
+runtimes.
+
+Run `ctg login`, or use `/login` (`/auth`) inside the regular console. Carthagent
+Ship is offered as the managed option, while Anthropic, OpenAI, OpenRouter and
+other supported direct providers can also be connected. The login UI handles
+OAuth URLs, device codes, and provider-supported API-key prompts. You can also
+provide a provider key through its environment variable, for example:
+
+```sh
+export ANTHROPIC_API_KEY=...  # or OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, ...
+ctg
+```
+
+Multiple provider credentials can coexist. In the regular console, `^t`
+(settings) has provider and model rows; `←→` changes providers, and the model
+picker is scoped to the selected provider. `/login` can connect another
+provider. Override the model for one run with `--model <id>`; the last choice
+is saved to `~/.carthagent/config.json` for the regular CLI.
+
+### Carthagent Ship
+
+Choosing Ship in the login UI starts browser device authorization. Carthagent
+stores the resulting short-lived access token and rotating refresh token in its
+regular CLI credential store. After signing in:
+
+```sh
+ctg account                    # credit, grants, plan, and CLI sessions
+ctg billing checkout           # checkout URL
+ctg billing portal             # customer portal URL
+ctg logout-cloud [session-id]  # revoke current or named CLI session
+```
+
+The regular console also offers `/account`, `/billing checkout`, `/billing
+portal`, and `/logout-cloud <session-id>`. Direct provider/API-key options
+remain available if managed Ship credit is unavailable. A direct `EXPLABS_API_KEY`
+environment key, where configured by an operator, is separate from the public
+Ship device flow.
+
+`CARTHAGENT_CLOUD_URL` overrides the Carthagent account/control-plane origin.
+`EXP_GATEWAY_URL` specifically overrides the direct upstream model gateway for
+preview or staging. Browser-account requests use the Ship control-plane
+authority; API-key requests use the configured upstream gateway. Model
+identities are discovered from `GET /v1/models`; published operating caps may
+restrict catalog model limits. Pricing metadata is not inferred from that
+endpoint. See the control-plane/operator documentation for hosted request and
+billing behavior.
+
+## Regular console and commands
+
+```sh
+ctg                           # interactive split-terminal console
+ctg "Build a task CLI"        # console with an initial task
+ctg -p "Summarize this repo"  # headless output (also automatic without a TTY)
+ctg demo                      # scripted mock; no provider needed
+ctg status                    # fingerprint, contract, pending checks
+ctg check all                 # run declared checks
+ctg account                   # Ship account details
+ctg billing checkout          # Ship checkout link
+ctg serve                     # web dashboard
+ctg test                      # unit suite
+ctg update --check            # check for a release without installing
+ctg update                    # update using the regular CLI updater
+ctg --help                    # all commands/options
+```
+
+Inside the regular console: `enter` send/steer · `esc` abort (again force-
+restarts the engine) · `^r` session picker · `tab`/`⇧tab` panes · `x` expand
+tool output · `^v` paste · `/copy` copy the full last assistant response · `^t`
+settings · `^c` quit. Drag-select copies text; at the pane edge, continue
+holding to scroll during selection. Clipboard writes use native tools and OSC
+52; remote terminals may need clipboard permission and may impose size limits.
+Regular sessions persist under `~/.carthagent/agent/sessions/`; `ctg -c`
+continues the latest and `ctg -r` opens the picker.
+
+### Themes and useful flags
+
+The regular console provides the `carthage` purple/gold theme, dark themes
+(`opencode`, `tokyonight`, `nebula`, `ember`, `forest`, `mono`, `obsidian`,
+`midnight`, `nord`, `solarized-dark`, `okabe-dark`, `contrast-dark`), light
+themes (`paper`, `daylight`, `solarized-light`, `okabe-light`,
+`contrast-light`), and adaptive `solarized`, `okabe`, `contrast`, and `system`
+themes. Select with `--theme`, `/theme`, or `^t`; the dashboard theme picker
+persists its choice separately in browser `localStorage`.
+
+Common options include `--model`, `--thinking`, `--validators <file>`,
+`--context <file>`, `--bash-cap <sec>`, `--review ask|yes|no`, `--isolate`,
+`--no-delivery`, `--no-guide`, `--ascii`, `--glyphs <mode>`, `-c`, `-r`, and
+`--session`. `--glyphs auto` selects Unicode where supported and otherwise
+falls back to ASCII; set `--ascii`, `--glyphs unicode|ascii`,
+`CARTHAGENT_GLYPHS=unicode|ascii`, or `CARTHAGENT_ASCII=1` to override.
+
+For native preview behavior and its separate paths, see the [native upgrade
+guide](native-upgrade.md). Native migration acceptance remains open; this page
+continues to describe the default until that status changes.

package/docs/live-theme-plugin-api.md

@@ -0,0 +1,18 @@
+# Live theme control for TUI plugins
+
+Reviewable upstream patch: `docs/patches/opencode-v2.0.32-live-theme-api.patch`
+
+Patch SHA-256: `0bcb1462688c00a09564e9874c3e01429baf92fe004bfc6400704fb24133c123`
+
+The narrow host extension is `context.ui.theme.current()` and
+`context.ui.theme.set({ name, mode? })`. It delegates to OpenCode's existing
+reactive theme service, which applies changes in the running TUI and persists
+configuration. It does not edit theme files or signal/restart the process.
+Theme files must be provisioned before TUI startup so the host has discovered
+them. A missing theme or unsupported requested mode returns `false` without
+partially changing the active theme or mode.
+
+Focused coverage: `packages/tui/test/plugin-theme.test.tsx` (2 tests).
+Validation used Bun 1.4.2: focused theme tests pass 2/2 and the plugin package
+typecheck passes. This is a standalone candidate patch; it is not composed into
+the pinned runtime patch and does not update the runtime recipe digest.

package/docs/native-cli.md

@@ -0,0 +1,102 @@
+# Native OpenCode CLI adapter
+
+`lib/opencode/cli.mjs` is the compatibility boundary for the `ctg` command
+surface. It parses aliases and flags, chooses interactive vs headless execution,
+and dispatches to `lib/opencode/cli-runtime.mjs`. `bin/ctg.mjs` selects this route
+only with `CTG_NATIVE=1`; the existing CLI remains the default until integration
+gates pass.
+
+## Runtime integration port
+
+The caller of `runOpenCodeCli()` supplies these concrete capabilities:
+
+| Capability | Request/behavior |
+| --- | --- |
+| `run({ mode, options, prompt, args })` | Launch native OpenCode interactive or headless (`print`/JSONL) session. Honor `--engine-cli`/`--agent-cli` as an explicit executable override and `--isolate` as extension/skill/prompt discovery isolation using a fresh CTG profile, not a worktree. |
+| `listModels({ query })` | Enumerate models from the native provider catalog, filter the optional query, and print the compatible provider/model/context/token/input/output columns. |
+| `login({ args })` | Uses OpenCode 2 integration list/connect/status/complete/cancel APIs. Defaults to Carthagent Ship when available; optional integration and method arguments select another integration. Key-based methods are not prompted in clear text. |
+| `account({ args })` | Uses the profile-owned Ship RPC and active managed OAuth connection; `--json` emits the account response. |
+| `billing({ action })` | Uses the profile-owned Ship RPC to create checkout/portal links and opens the returned URL explicitly. |
+| `logout({ session })` | Uses the profile-owned Ship RPC to revoke a named session or the current session; current logout also removes its native credential. |
+| `archive({ args })` | Uses the profile-owned archive RPC for read-only list/search/read/export of configured legacy transcripts. |
+| `review({ args })` | Uses the shared review facade, whose verdict is bound to the authoritative GitHub PR refs/source or exact local source snapshot. |
+| `domain({ command, args })` | Existing status/hash/check/validate behavior backed by delivery domain modules. |
+| `command({ command, args })` | Existing serve/test/eval/update utility commands; package updates install only the validated release spec. |
+
+Capabilities that are not wired fail with an explicit missing-capability error;
+there are no placeholder success paths. Operations return an integer process
+status (or `undefined` for success). Cancellation from a native session maps to
+130. Headless resume maps the picker request to continuation; headless calls
+without a task fail with an actionable message.
+
+Headless success requires both the assistant's completed `finish: stop` message
+and a terminal `idle` message with `outcome: succeeded`; text output alone is not
+success. Native thinking levels are passed as model variants. The adapter rejects
+`--max-tools`, `--max-seconds`, `--max-repairs`, `--no-delivery`, and `--no-strict`
+unless the active native plugin advertises the matching session-option, budget,
+and policy enforcement capabilities. They fail closed when that contract is
+missing. `--bash-cap` is enforced by the native plugin's shell hooks when the
+active plugin advertises session-option support. `--isolate` uses a fresh CTG
+profile with empty skill, instruction, and command sources, while retaining the
+Carthagent plugin; this disables ambient profile/project discovery without
+creating a worktree.
+`--codegraph-max-files` sets the bounded source-file scan limit for the native
+code navigation index and is resolved per session. `--no-guide` is stored in
+durable `carthagent.options` session metadata and honored by native prompt
+framing; on a resumed session, explicitly supplied options override persisted
+settings for that session only, while unspecified settings are preserved. `demo`
+runs a separately labeled offline Node fixture in a disposable temporary workspace;
+it makes no provider calls, edits no project files, and does not claim evidence for
+the user's project. The shared update operation in `lib/opencode/update.mjs`
+supports npm installs
+and clean source clones; clone updates fetch the selected origin tag into a
+private ref and check out its resolved commit, while dirty clones are refused.
+The native CLI's current `update` command path is separate and refuses to
+checkout into its active source tree; it installs the validated, release-pinned
+package spec for npm installs. Release tag/version validation is required;
+`--force` cannot bypass it. `quit`/`q`/`exit` report that no interactive session
+is active when invoked as standalone commands.
+
+`--json` translates real native session tool lifecycle and completed assistant
+messages into the documented `tool_execution_start`, `tool_execution_end`, and
+`message_end` JSONL records. It filters to the selected session and reconciles
+message history after execution so stream/history projections do not duplicate a
+turn. Failed assistant responses retain their error and stop reason, and terminal
+failure/interruption outcomes are emitted as idle records rather than returning
+an empty JSONL stream.
+Accepted turns that time out or are cancelled keep their captured session and
+tool lifecycle events, but are never reconciled against older session history.
+Pre-admission interruption has no accepted marker and emits no prior-session
+events. OAuth form secret fields are masked in raw terminal input; unsupported
+API-key login methods are rejected before any prompt is displayed.
+
+The disposable real-host adapter smoke is `node tests/native-cli-host-smoke.mjs`.
+It resolves the pinned OpenCode executable through the package-owned native
+runtime resolver and defaults runtime/plugin imports to this package. In a
+source checkout without installed runtime dependencies, set `CTG_OPENCODE_BIN`
+to an installed pinned binary; `CTG_NATIVE_RUNTIME_ROOT` and
+`CTG_NATIVE_PLUGIN_PATH` explicitly override runtime/plugin imports when testing
+another package tree. The smoke creates a disposable
+cross-platform profile (including Windows profile/temp roots), disables project
+configuration loading, and runs a local OpenAI-compatible fixture provider. It
+injects the already-running service through the adapter test seam and verifies
+print, a second print turn in the same session, workspace-scoped continuation
+when a newer foreign-workspace session exists, successful and failing JSONL
+lifecycle events, and explicit rejection of unenforced budget flags. It does
+not verify normal runtime service provisioning/profile isolation or provider
+login/account/billing.
+
+## Migration notes
+
+- `ui` and `interactive` alias `tui`; `sessions` aliases `resume`; `s`, `c`,
+  `fingerprint`, `auth`, `cloud`, `web`, and `start` retain their established
+  command aliases.
+- `--agent-cli` and `--engine-cli` share the explicit native executable
+  override. They must not silently select a legacy Pi executable.
+- `--isolate` describes extension/skill/prompt discovery isolation and never
+  implies worktree creation.
+- Help/output and domain exit behavior remain the CLI contract. PI session
+  stores are archive-only and are not read or continued by this adapter.
+- Activation is intentionally staged: `CTG_NATIVE=1` is opt-in; changing the
+  default still requires parent integration to verify service/auth/model/review
+  behavior, package installation, and no supported default Pi execution path.

package/docs/native-compatibility.md

@@ -61,6 +61,15 @@ bounded cancellation, and a documented JSONL contract for evaluation consumers.
 
 ## Cross-cutting gates
 
+The PR #152 TUI scope owns theme provisioning, workspace presentation, and
+session-scoped host commands. `/login`, `/auth`, `/account`, `/cloud`, `/usage`,
+`/billing`, `/logout-cloud`, `/update`, and `/upgrade` remain CLI-authoritative
+operations and must be integrated through the separate CLI author RPC; this TUI
+must not create a second provider/cloud/update implementation. `/quit`, `/q`,
+and `/exit` remain native host lifecycle commands rather than plugin aliases.
+These responsibilities are not counted as complete by listing them in a command
+manifest.
+
 - 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
@@ -92,6 +101,13 @@ The following probes use a disposable profile and deterministic loopback provide
 package-owned `node_modules/@opencode/cli/bin/opencode.exe`. An optional first
 argument selects an installed plugin directory.
 
+The interactive help command must be checked with both `/help` and `/ctg-help`.
+Strict post-submit probes on the pinned OpenCode 2.0.32 host currently show
+`/help` opening native Help. Earlier positive results could match autocomplete
+text before submission. `/ctg-help` works, but neither that alias nor dismissing
+autocomplete before submitting `/help` satisfies the required command behavior.
+Native command precedence remains an open acceptance gate.
+
 - `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

package/docs/native-daily-quests.md

@@ -0,0 +1,132 @@
+# Native daily coding quests
+
+Open `/quests`, or `/voyages`, then **Daily coding quests**. On a development
+runtime with navigation support, the left rail also has **Projects / Voyages**
+modes. Switching modes does not leave the main page or create, interrupt, or
+close a coding session. The Voyages navigator shows read-only profile and daily
+assignment summaries. Select an entry explicitly to open its detail page;
+opening a quest does not compose evidence or grant consent. **Return to coding**
+opens the selected session, or Home when no session is selected.
+
+The rail keeps each mode's selection and scroll position. Its compact layout
+uses `Q` (quests), `P` (profile), `E` (equipment), `R` (refresh), `S` (sign in),
+and `B` (return to coding); numbered rows are actual assignments. At widths
+that cannot fit the rail, use the command palette, `/voyages`, or `/quests`.
+Badges and friends have no native views yet. The navigator does not invent
+links or data for them. Older released runtimes keep slash-command navigation.
+
+Use the native Carthagent Ship
+device sign-in. The client uses the existing configured Carthagent API and scoped
+bearer connection. Signing in, running Ship, or finishing a local delivery does
+not consent to grading and never automatically uploads evidence.
+
+## Select, edit, preview, consent
+
+1. Refresh and select one of the server's daily assignments. The server supplies
+   the title, kind, rubric, criteria, UTC day and closing time. There are no
+   locally generated objectives or invented completion states.
+2. Choose an actual local Ship report, or a clearly labeled manual claim. Local
+   report access is limited to an owned session and its exact active report.
+   Select individual checks/findings and goal/change text. Nothing is selected
+   by default. Check output and finding text may contain private information.
+3. Edit the evidence JSON. Remove or redact sensitive material yourself. No
+   automatic secret detection is promised. Use **Tab** to switch between the
+   editor and actions, and **Ctrl+P** to validate and preview, never to submit.
+   With the native runtime's default input bindings, **Enter** also previews;
+   **Ctrl+J** inserts a newline (as do **Shift/Ctrl/Alt+Enter**). These follow
+   the runtime's configured input-submit and input-newline shortcuts.
+4. Inspect the complete canonical outbound JSON in the scrollable preview.
+   **Ctrl+U/D** scrolls details and preview. Unknown fields, invalid references,
+   unsupported controls, mismatched passing-check revisions and UTF-8 size
+   violations are rejected before dispatch. Editing invalidates the preview.
+5. Choose **Consent and submit this preview**, then explicitly **Consent and
+   send**. This grants consent for this submission only. Cancel never sends.
+
+Account, connection or location invalidation clears the local draft/preview and
+closes this page's pending dialogs; it never preserves old consent. If evidence
+selection or confirmation was interrupted, a page notice explains the cancellation
+and the actions selection resets to **Refresh**, not Back. Refresh and review
+again before giving fresh consent. No request is resent automatically. A request
+that already started may still have reached the server: check its stable ID in
+the recovery journal rather than assuming cancellation withdrew it.
+
+The report's integer plan revision is not a source revision. The source-backed
+projection uses the actual workspace fingerprint. A current report does not
+retain a complete check history, so failed-before execution is **not recorded**
+and is never inferred. Manual additions and edited text remain user claims.
+Project/outcome/run UUIDs are stable references, not proof of authorship. Keep
+those IDs when revising the same outcome. A separate outcome must describe
+genuinely different work, not evade retained-outcome restrictions.
+
+Every check has `name`, `before` (`failed` or `not_run`), `after` (`passed`,
+`failed`, or `not_run`), `revision` (40/64 hex), and `result`. A passing check's
+revision must equal the evidence revision. Every finding has `issue`,
+`evidence`, and `resolution`. Empty arrays are valid but do not prove criteria.
+Only enter `before: "failed"` if an actual earlier failure was observed.
+There can be at most 12 checks and 5 findings. The complete canonical evidence
+must fit 12,288 UTF-8 bytes, and the request 16,384 bytes. Per-field byte limits
+are enforced before trimming, so shortening/redacting may be necessary.
+
+## Processing and recovery
+
+HTTP acceptance is not completion. **Queued** and **grading** are pending.
+**Graded** has a separate decision: classifier-assessed complete, not met, or
+needs evidence. **Failed** is an operational processing failure, not a negative
+coding assessment. The displayed scores are uncalibrated rubric scores, not
+confidence or probabilities. Only server state determines completion.
+
+The native server persists the exact selected request and submission UUID in a
+private profile-wide journal before sending. An uncertain send must be polled
+by that UUID, or explicitly replayed with the same saved ID and body. Refresh
+and poll are read-only and never replay. A new UUID is not a network retry.
+The saved records remain available after midnight; a job accepted before the
+UTC boundary can finish afterward. Validation/authentication/conflict failures
+are not reasons for blind retries.
+
+Accepted submissions need only their IDs for polling, so local raw payloads are
+erased when acceptance is known. Unknown-send raw payloads are retained for
+exact recovery for up to 24 hours, purged on the next journal access. This is
+not a background deletion timer. **Erase local payload** removes those bytes
+while retaining IDs for read-only status checks. It cannot cancel a backend
+job or withdraw evidence already sent. Corrupt or unwritable journals fail
+closed rather than sending without durable recovery.
+
+## External processing and retention
+
+Carthagent receives the exact selected request. External **JEV** receives the
+revision, goal, change, selected checks/findings and server rubric, not the
+project/outcome/run UUIDs. The flow does not upload a transcript, archive,
+whole project, full review capture, or full check log. Included output tails
+and authored text still require your privacy review.
+
+Backend raw evidence is pending for up to 24 hours and erased on terminal
+processing; outages can delay cleanup. Backend metadata is retained for
+90 days. Provider policy applies. Immediate provider or backup deletion is
+not promised. Local metadata is retained for recovery, with bounded storage
+and expiry applied on journal access.
+
+Assessment is based on submitted evidence, **not independent verification**.
+There are **no coins, XP, distance, inventory, or other rewards** in this flow.
+Editable personal quests remain separate from server daily assignments.
+
+## Validation boundary
+
+Offline contract, persistence, ownership, schema and UI-controller tests do not
+prove production provider accuracy or a live native submission. The backend's
+previous synthetic acceptance submissions were backend tests, not native TUI
+acceptance. Live acceptance requires a dedicated owned QA account, normal
+device sign-in and a separately authorized bounded provider-attempt allowance.
+Do not silently spend that allowance or substitute a mock result for
+production proof.
+
+The navigator's real-component renderer tests run with Bun 1.4.2 through
+`npm run test:native-navigation`. They use isolated, synthetic account summaries
+and do not contact a provider. They cover focus ownership, modal guards,
+compact mode, preserved selection/scroll, and read-only route selection. They
+are not live authentication, grading, or full rebuilt-runtime acceptance.
+
+Run the new boundary on the real pinned native host without external grading:
+`node tools/test-native-daily-quests.mjs`. This checks registration, all six
+declared authentication failures, and actual local source projection through
+the host's output validator. Its constructed report is a schema fixture,
+not evidence that a check ran or a substitute for live submission acceptance.

package/docs/native-glyph-pty.md

@@ -0,0 +1,59 @@
+# Owned OpenCode glyph PTY acceptance
+
+`npm run test:native-glyph-pty` resolves the runtime through CTG's production
+`resolveOpenCode` path, requires its identity to be CTG-owned, and verifies the
+runtime provenance and executable digest before starting a TUI. The packaged
+release manifest is the default trust root. To test an explicitly staged owned
+artifact, provide both a staging root and an independently trusted release
+manifest:
+
+```sh
+CTG_TEST_RUNTIME_ARTIFACT_ROOT=/path/to/owned-runtime \
+CTG_TEST_RUNTIME_RELEASE_MANIFEST=/path/to/trusted-release.json \
+CTG_GLYPH_ARTIFACT=/tmp/glyph-pty.json \
+npm run test:native-glyph-pty
+```
+
+The explicit artifact preflight runs before the production resolver can execute
+it. Do not set `CTG_OPENCODE_BIN` or `CTG_TEST_RUNTIME_SHA256`; either would
+bypass the acceptance trust chain. The runner launches two full TUI sessions in
+real PTYs, with isolated temporary home/config/data/state/cache/database and
+project directories: one with `CTG_TUI_GLYPHS=ascii`, one with
+`CTG_TUI_GLYPHS=unicode`. It stages (but does not submit) the exact text
+`CTG_GLYPH_PAYLOAD 漢字 café → • − …` in the composer. The paired PTY parser
+tracks East Asian wide-cell width and combining marks locally to this probe; it
+requires the entire exact ordered payload on the rendered prompt row. No model
+provider is used.
+
+Assertions cover one known static chrome mapping: the startup logo must be the
+ASCII wordmark in ASCII mode and the block-art wordmark in Unicode mode. The
+complete arbitrary Unicode user payload must independently match, in order, on
+the rendered composer row. The composer row itself is excluded from startup-logo
+classification. This is not coverage of prompt borders, ellipses, bullets,
+separators, other dialogs, shell output, or tool-group disclosure.
+The JSON artifact records the exact runtime version, compatibility version,
+binary SHA-256, source/patch/lock provenance, production resolver identity,
+mode-specific parsed screens, and captured-PTY digests. A PTY pass establishes
+the exercised home composer frame only; it is not a claim that every TUI dialog,
+shell result, tool group, or disclosure state was rendered.
+
+Both spawned processes receive allowlisted environments. The Node resolver may
+use `CTG_RUNTIME_GITHUB_TOKEN` while acquiring an unpublished draft runtime, but
+the Python harness and each OpenCode PTY child receive only PATH/locale plus
+fresh temporary profile paths and the explicit glyph mode. The optional release
+token is never forwarded to the child TUI, model, or tools. No host account,
+provider credential, network provider, performance, memory, or real clipboard
+claim is part of this acceptance test.
+
+The historical negative-control runtime with SHA-256
+`85bb44a65e8c185f4f33d41507d29acc77f2db0cdcb0103a14476021c8e43794` predates the
+glyph patch; it rendered the Unicode startup logo in ASCII mode and was rejected.
+That artifact is no longer available here and its result is not a glyph pass.
+Positive acceptance requires rerunning this harness against the final combined
+runtime artifact and retaining its JSON report.
+
+Pure Unicode cell-width, composer-payload, and child-environment helper code is
+in `tools/native-glyph-helpers.py`, which has no OS-specific PTY imports. Its
+unit tests run on supported platforms when Python is available (select an
+interpreter with `PYTHON`). The actual PTY execution runner remains Unix-only;
+this does not claim Windows PTY acceptance.