carthagent 1.0.7 → 1.1.0-beta.2

package/docs/native-upgrade.md

@@ -0,0 +1,175 @@
+# Native Carthagent beta: upgrade and migration guide
+
+**1.1.0-beta.1** uses the native console by default. `ctg native` is a compatibility
+alias; `CTG_NATIVE` no longer selects a different console. Stable 1.0.7 remains
+the legacy release. Select the beta explicitly through the beta channel or its
+exact published version.
+
+See the [beta.1 release notes](release-notes-beta.1.md) and
+[launch-readiness report](launch-readiness-live-results.md) for current evidence
+and beta limitations.
+
+## Before you try it
+
+- The native route uses a checksum-pinned CTG-owned runtime compatible with OpenCode **2.0.32**. It
+  does not use, install over, update, or borrow authentication from a regular
+  OpenCode installation. Selecting the beta release is explicit; no shell-wide routing toggle is needed.
+- Native OpenCode settings, auth, database/sessions, state, and cache belong to
+  the CTG profile under `~/.carthagent/opencode/`. `CTG_OPENCODE_HOME` can
+  override that profile root. The old CLI's Carthagent data is separate too.
+  Project/worktree delivery reports and native task metadata live in their
+  respective workspaces; task state is recorded in `.harness/`.
+- Existing Pi sessions are **read-only archives**, not native sessions. There
+  is no transcript continuation, conversion, or import. Keep the old
+  installation and source data until you have independently confirmed the
+  archive contains what you need.
+- Read the exact release notes for installed-package acceptance and platform
+  limitations. Earlier migration findings remain in the
+  [migration ledger](opencode-migration.md) and
+  [terminal evidence](native-terminal-semantics.md); they are historical evidence,
+  not a claim that every command or platform has been verified by a live model.
+
+## Try the native route from a checkout
+
+The default resolver acquires only the platform archive pinned by the packaged
+release manifest, validates source/patch/lock and archive/executable checksums,
+and caches it in the private Carthagent profile. It never falls back to a system
+or upstream binary after selecting the owned runtime. An explicit developer
+artifact is a separate, validated staging path—not an end-user update mechanism.
+
+After installing dependencies in a checkout of a published source tag:
+
+```sh
+node bin/ctg.mjs --help
+node bin/ctg.mjs
+node bin/ctg.mjs "Investigate the failing tests"
+```
+
+The native service refreshes after a verified owned runtime or launcher update.
+Sessions and credentials remain in the profile; an unauthenticated or foreign
+process is never stopped just because its registration looks stale.
+
+The native launcher preserves familiar commands and aliases: `tui`/`ui`/
+`interactive`, `resume`/`sessions`, `continue`, `status`/`s`, `check`/`c`,
+`hash`/`fingerprint`, `login`/`auth`, `account`/`cloud`, `serve`/`web`/`start`,
+and `update`/`upgrade`. See [native CLI](native-cli.md) for implemented flags,
+failure behavior, and unsupported options. In particular, do not assume an old
+flag is enforced merely because its name is accepted: unsupported `--bash-cap`
+and `--isolate` fail closed, and policy/budget flags require enforcement
+capabilities advertised by the active plugin.
+
+## Projects, tasks, worktrees, and sessions
+
+The native UI is based on OpenCode's project and session model. A CTG task
+creates an OpenCode worktree and a separate root session located in that
+worktree; CTG stores the task/parent relationship in workspace metadata. It
+does not create a nested OpenCode child session. Worktree separation provides
+independent checkout directories, but do not infer that every host, credential,
+or external process behavior is isolated by a worktree.
+
+Resume and continue operate on native sessions associated with the current
+workspace. A project workspace view may present known task, worktree, and
+session records together. These do not turn legacy transcripts into sessions.
+Normal project discovery, host UI behavior, and complete cross-platform
+interaction remain acceptance items; consult the ledger rather than assuming a
+preview feature is fully supported.
+
+## Legacy archive (read-only)
+
+The archive CLI supports list/search/read/export. Configure or retain the
+legacy session archive at its existing location; the native adapter exposes it
+for reading and does not mutate those transcripts:
+
+```sh
+node bin/ctg.mjs archive list
+node bin/ctg.mjs archive search "query"
+node bin/ctg.mjs archive read <archive-id>
+node bin/ctg.mjs archive export <archive-id> --format jsonl
+```
+
+Archive output is not an import format. Start a new native session and provide
+any context you need yourself; no session identity or execution history is
+carried forward.
+
+## Headless commands and JSONL
+
+`-p`/`--print` runs a headless task and prints assistant text. `--json` emits
+JSONL lifecycle records for the selected native session, including tool starts,
+tool results, completed assistant messages, and a terminal outcome. `ctg status
+--json` is a separate versioned delivery status snapshot, not execution JSONL.
+Headless invocations need a prompt; when stdout is not a TTY the CLI selects
+headless mode automatically. A resume-picker request in headless mode becomes
+continuation of the latest native session for that workspace.
+
+```sh
+node bin/ctg.mjs -p "Summarize this project"
+node bin/ctg.mjs --json -p "Run the declared checks"
+node bin/ctg.mjs status --json
+```
+
+JSONL consumers should use the terminal outcome and exit status, not the
+presence of assistant text alone: successful completion requires the completed
+assistant turn and a successful native terminal outcome. Failed, interrupted,
+and unresolved turns are not success. `-p` text is not a live tool-event stream.
+
+## Release installation and update
+
+Only published releases are installable; a draft is not an update. From an
+installation with channel support:
+
+```sh
+ctg update --channel beta --check
+ctg update --channel beta
+ctg
+```
+
+The exact-version installation form is:
+
+```sh
+npm install -g carthagent@1.1.0-beta.1
+```
+
+`ctg update --check` checks for
+an available release. `lib/opencode/update.mjs` contains the shared,
+release-validated update operation: for npm-installed Carthagent it installs
+the validated exact release spec; for a source clone it requires a clean
+working tree, fetches the selected origin tag into a private ref, resolves that
+fetched tag to a commit, checks out the commit detached, then reinstalls
+dependencies and the global package. It does not overwrite existing local tags
+or proceed with dirty files. The native CLI's current `update` command path is
+separate: it installs the validated release spec for npm installs and refuses
+to check out into its active source tree, including a clean clone. Use the
+non-forced manual procedure below for that source-tree path; do not assume
+uncomposed CLI/UI wiring changes this behavior. Preserve and review local work
+first:
+
+```sh
+git status --short
+git diff                         # review and preserve any edits before proceeding
+git fetch origin --tags
+git checkout --detach v1.1.0-beta.1  # published release; no force option
+npm ci
+```
+
+Do not discard or overwrite local changes to make this procedure succeed. If
+the checkout has work you need, commit it or preserve it outside the checkout
+before changing revisions; resolve conflicts or recovery deliberately rather
+than using a destructive reset. The updater is Carthagent's updater, not a
+regular OpenCode updater. Beta.1 inherits the native-default CLI from the previews.
+Use `ctg update --channel stable` to return to the legacy stable release; neither
+channel switching nor service refresh deletes profiles or legacy transcripts.
+Do not install a moving branch or guess an unpublished version.
+
+## Acceptance status and help
+
+The current acceptance contract and evidence are maintained in:
+
+- [Preview.9 candidate notes and remaining release gates](release-notes-preview.9.md)
+- [Historical migration delivery ledger](opencode-migration.md#delivery-ledger)
+- [Native runtime acceptance matrix](native-compatibility.md)
+- [Terminal probe and evidence caveats](native-terminal-semantics.md)
+- [Historical native migration draft (not current routing/install guidance)](release-notes-native-draft.md)
+
+These documents intentionally distinguish component/test results from complete
+installed-product acceptance. A command's presence, successful unit test, or
+documentation entry does not by itself mark an acceptance gate complete.

package/docs/opencode-composed-source-review.md

@@ -0,0 +1,89 @@
+# Final OpenCode source composition review checkpoint
+
+This review checkpoint composes patches on clean upstream OpenCode `v2.0.32`
+source `843a6c514e606b436a7fe713422ace0a93ad3d61`, in this order:
+
+1. Session/runtime patch (pre-composition SHA-256
+   `36379e0bf4ec0f63929c12b5ac96dfc73df60b124cef9f4adeb36d86287bc92f`).
+2. Approved natural `/help` patch (SHA-256
+   `c1ce7d983be8ecdd3481b16da103fb32d144b0ec01f894915a110b46acdc6fe5`).
+3. Approved live-theme API patch (SHA-256
+   `0bcb1462688c00a09564e9874c3e01429baf92fe004bfc6400704fb24133c123`).
+4. Approved glyph-v4 patch (SHA-256
+   `37d93c0dfd5c52bd4536136fb53618580a29d682644848433f3b2ee4726d98a4`).
+
+The approved base combined source patch is
+`docs/patches/opencode-v2.0.32-session-ui.patch`; its SHA-256 is
+`81e86a4c139e02ebd077e1b635a62ea804ec60b6ae20100893cb6d9f73b06d62`. A
+separate combined candidate is recorded at
+`docs/patches/opencode-v2.0.32-session-ui-combined-v3.patch` with SHA-256
+`75d6484112881481b178bde583f9ff4e5d36cbac2fdf19d000339795b9485ce2`; it adds
+the approved spinner test-isolation and real-provider theme proof patches. The
+candidate recipe and packaged runtime identity both pin this digest; the
+historical base recipe/runtime identity remain recorded in Git, and the base
+patch remains unchanged. Frozen
+lockfile installation, TUI typecheck, and the exact combined glyph/keymap/theme/
+provider run passed (19 tests / 188 assertions in one Bun process with
+`--timeout 60000`). The workflow fixture passed all 6 tests with Node 26 after
+updating its patch-path assertion. Independent review approved corrected head
+`0e38142bff30ca2a8b2a66394e5055d541fce489`, including an isolated Windows-style
+checkout-to-recipe handoff reaching Bun installation and dirty-input rejection.
+These source checks do not establish final-artifact acceptance. The three
+standalone review patches remain
+separately published and unchanged. The base composition was
+applied to a clean detached upstream checkout and its reverse-application check
+and `git diff --check` pass. The glyph patch’s two `/help`-overlapping files
+were integrated by applying `/help` first and glyph v4 afterward; the resulting
+autocomplete/prompt imports and keymap test changes are present once in the
+combined patch.
+
+Source approvals and author test reports are recorded separately: glyph v4
+source approval (11 tests / 146 assertions), `/help` keymap suite (5/5), and
+live-theme focused tests/typecheck. These do not approve the combined patch and
+do not substitute for an independent composition review. This is a source-review
+checkpoint only: do not build until the exact combined patch is independently
+approved. The previous v1 patch was built on Linux x64 before the Linux runner
+marquee assertion was corrected; that binary is historical and is not an
+artifact for this v2 digest. Final v2 binaries and cross-platform prebuilds,
+theme PTY, glyph matrix, `/help`, and title restoration proofs remain outstanding.
+
+The unrelated draft-release asset transport design is intentionally not
+implemented by this composition. A separate review must decide whether a
+repo-scoped, ephemeral CI credential may be used only for authenticated draft
+asset retrieval through the production resolver, preserving the packaged
+manifest/digests and default no-override selection. No credential values or
+transport code were used here.
+
+Reproducible workflow fixture coverage lives in
+`tests/owned-runtime-publish-workflow.test.mjs`. It extracts the literal
+validate, verify, and upload Bash blocks from this workflow YAML and executes
+them with bounded temporary fixtures. It verifies review-branch prebuild SHA
+binding and rejects publish validation from a non-default branch; the positive
+publish path verifies five tiny USTAR archives and the packaged trust root,
+then a fake `gh` captures exactly seven assets for byte comparison. Tampered
+archive and stale annotated-tag cases both assert zero captured uploads. This is
+automated mocked workflow coverage, not a real dispatch or release. Although
+the fixture accepts a reviewed-branch prebuild SHA, GitHub only registers
+`workflow_dispatch` for a workflow file present on the default branch. This
+workflow was subsequently registered by reviewed bootstrap #197, merged as
+`bd1292c8c4` after green CI. Parent dispatched real prebuild run `39089640210`
+against exact source `70882269e25ebcb62c843f9265345342b9e6844d` for planned
+version `1.1.0`. Its build results remain pending.
+
+This focused TUI candidate verification is not the parent repository's full
+quality run and does not include the separate native CLI test-browser isolation
+change `d4983b57328a187e8be6bc0e2c6bd2dda7518920`; apply or merge that change in
+its applicable parent integration lineage before running or claiming parent
+full quality. It is not part of this upstream OpenCode patch.
+
+The release workflow permits a non-publishing prebuild from a reviewed branch
+to avoid requiring product merge before native candidate generation. It binds
+the requested source SHA to that dispatch's exact workflow commit. The publish
+phase remains default-branch-only and compares the candidate with the final
+tagged package trust root; prebuild is not merge or release approval.
+
+The pinned external release generator still reads the legacy patch pathname.
+Both candidate-generation calls therefore copy the candidate patch bytes to
+that pathname only inside the disposable CTG checkout used by the workflow;
+the checked-in base patch remains unchanged. Fixture assertions cover both
+adaptation points.