carthagent 1.0.7 → 1.1.0-beta.2

package/README.md

@@ -1,51 +1,143 @@
 # Carthagent
 
-> **Evidence-driven software delivery, from plan to proof.**
-
-Carthagent is a delivery-focused AI coding console and CLI built on a bundled delivery engine. It turns “here’s my code, trust me” into an auditable delivery: the agent declares an acceptance contract, runs real checks, and re-proves them whenever source changes.
-
-`docs/workflow.svg` shows the flow; `docs/evaluation.md` has the honest trial history, failures included.
+Carthagent checks software work against real acceptance tests and re-proves it whenever source changes.
 
 ## Install
 
-Core CLI requires Node ≥ 22.19. Optional workflows need additional tools: Git and authenticated `gh` for PR review, and Python with the scenario dependencies for game graders. Real-browser checks use a bundled lightweight headless browser (`chrome-headless-shell`, auto-downloaded on first use to `~/.carthagent/browser/`) — no local browser install needed; an external WebDriver endpoint remains supported. The engine is bundled inside the package.
-
-Install directly from GitHub:
-
 ```sh
-npm install -g --install-links=true github:B-icy/Carthagent
-ctg
+curl -fsSL https://carthagent.xyz/install | sh
+irm https://carthagent.xyz/install.ps1 | iex
+npm install -g carthagent
 ```
 
-With npm 11, `--install-links=true` is required for this `github:` global install. Without it, npm can leave `ctg` linked to a temporary clone that is deleted after installation. To make the setting persistent for future GitHub installs:
-
-```sh
-npm config set install-links true --location=user
-npm install -g github:B-icy/Carthagent
-ctg
-```
+Node.js 22.19+ is required for the npm install. From source: `npm install -g --install-links=true github:B-icy/Carthagent#vX.Y.Z` (replace with a published tag).
 
-If installation succeeds but your shell cannot find `ctg`, restart the terminal and confirm that npm's global executable directory is on `PATH` (`$(npm prefix -g)/bin` on Linux/macOS; the directory shown by `npm prefix -g` on Windows).
+See [workflow.svg](docs/workflow.svg) for the flow and [evaluation history](docs/evaluation.md) for trials, including failures.
 
-If `npm install -g` fails with `ENOTDIR`/`EEXIST` while renaming `…/node_modules/carthagent`, a stale entry from an earlier install (or an `npm link`) is in the way. Remove it and retry:
+## Native CLI
 
 ```sh
-rm -rf "$(npm root -g)/carthagent" "$(npm root -g)"/.carthagent-*
-npm install -g --install-links=true github:B-icy/Carthagent
+ctg
+ctg --help
+ctg native  # compatibility alias
 ```
 
-`ctg update` performs this cleanup automatically and retries.
+The old `CTG_NATIVE` toggle no longer changes routing. The native route launches the checksum-pinned CTG-owned runtime (compatibility 2.0.32) and uses a separate Carthagent-owned profile beneath `~/.carthagent/opencode/` (override with `CTG_OPENCODE_HOME`). Its config, database, sessions, auth, state, and cache are separate from other coding-tool profiles. It does not install, upgrade, or reuse credentials from other coding-tool profiles. Project files and native task metadata/worktrees are separate again: task records live in each project’s `.harness/opencode-tasks.json`.
 
-Or install from a clone:
+Native projects use the native project/session model. CTG task creation associates a task with an independent native session and native worktree; task relations are CTG metadata, not parent/child native sessions. Native session resume/continue is scoped to the active workspace. Legacy Pi transcripts can be listed, searched, read, and exported with `ctg archive`; they are **read-only archives** and cannot be resumed or imported as native sessions. See the [native upgrade and migration guide](docs/native-upgrade.md) before switching workflows.
+
+The native TUI exposes CTG workspace/task actions such as `/ctg-workspace`, `/ctg-open`, `/ctg-worktree`, and `/ctg-task`, alongside delivery and session commands. The native runtime owns the terminal renderer and lifecycle. Do not assume a listed command overrides a built-in host command: submitted `/help` precedence is a known unresolved acceptance gate.
 
 ```sh
-git clone https://github.com/B-icy/Carthagent && cd Carthagent
-npm ci && npm install -g .    # gives you `ctg`; or run `node bin/ctg.mjs`
+node bin/ctg.mjs                         # native interactive TUI
+node bin/ctg.mjs "Build a task CLI"      # task in the TUI
+node bin/ctg.mjs resume                  # native session picker
+node bin/ctg.mjs continue                # latest native session here
+node bin/ctg.mjs -p "Summarize this repo" # headless text
+node bin/ctg.mjs --json -p "Run checks" # native lifecycle JSONL
+node bin/ctg.mjs status --json           # delivery status JSON
+node bin/ctg.mjs archive list            # legacy archive (read-only)
 ```
 
-## Update
-
-`ctg update` resolves the latest release (the Carthagent control plane first, GitHub releases as fallback) and reinstalls it the way you installed: checkout the tag + `npm ci` in a clone install, or `npm install -g --install-links=true github:B-icy/Carthagent#<tag>` for a `github:` install. `ctg update --check` reports without installing. The console also prints a notice once a day when a newer release exists — set `CARTHAGENT_NO_UPDATE_CHECK=1` to opt out.
+The native CLI retains command aliases such as `ui`/`interactive`, `sessions`, `s`, `c`, `fingerprint`, `auth`, `cloud`, `web`, `start`, and `upgrade`. `--json` with a headless prompt emits JSONL records for native tool start/end, assistant message completion, and terminal outcome; it is not the text `-p` stream. Headless success requires the native completed assistant turn and successful terminal outcome. Options whose enforcement is not advertised by the active native plugin fail closed; in particular `--bash-cap` and `--isolate` are currently unsupported. Refer to [native CLI compatibility details](docs/native-cli.md).
+
+### Voyages in the native TUI
+
+`/voyages` opens the account's live Voyages profile, coin wallet, equipment and
+shop. Use the normal `/login` browser device approval and choose Carthagent;
+Voyages uses the approving browser user's existing player, not a separate CLI
+wallet. Older account-only Ship sessions may require a new device sign-in.
+Voyages does not require a paid model call or award coins for coding.
+
+Customization and equipment changes require confirmation. Paid items require a
+server quote showing the coin price and expiry, followed by explicit purchase
+confirmation. Cancel does not purchase. The server validates funds, ownership,
+eligibility and profile version; refresh after a conflict rather than silently
+overwriting another client. Equip a purchased item separately.
+
+If a purchase response is lost, the TUI keeps a pending request across restart.
+Use its recovery action to retry the same quote and request key, not to create
+a second purchase. Do not delete profile state to resolve an uncertain debit.
+The server remains authoritative; unavailable or signed-out state must not be
+treated as a saved balance. Browser cookies are never imported into CLI auth.
+
+Native Voyages landed in PR #225. Live development-runtime testing exercised
+browser device approval, name cancel/save, owned Beanie equip, restart and web
+persistence, expiry recovery, and revocation. The approving web player remains
+authoritative. The tested wallet had 10 coins and no affordable paid quote:
+no live paid debit or replay was proven. These are historical, bounded source/runtime
+results, not preview.10 installed-package acceptance. Subsequent development-runtime
+testing completed one explicitly authorized 40-coin purchase and restart
+persistence; see the [preview.10 candidate notes](docs/release-notes-preview.10.md)
+for its limits. Published preview.9 remains immutable and does not acquire
+changes from current main.
+
+### Projects sidebar source preview (development only)
+
+The redesigned Projects sidebar (folder card, folder browser, and folder/model
+setup for new sessions) exists only as source. It is **not** in any published
+`ctg` release, and the steps below do not build or update the published native
+runtime. The published runtime stays pinned to
+`docs/patches/opencode-v2.0.32-session-ui-combined-v4.patch` and
+`lib/opencode/runtime-release.json`.
+
+Requirements: Git, a POSIX shell, `sha256sum` or `shasum`, Bun 1.4.2 (the
+OpenCode `packageManager` pin), and this checkout with `npm ci` already run. No
+native compilation is needed. The launcher is a POSIX `sh` script for Linux and
+macOS; native Windows is not supported.
+
+1. Prepare a clean OpenCode checkout at the pinned upstream and apply the
+   development patch (v5 replaces v4 and applies directly to upstream):
+
+   ```sh
+   git clone https://github.com/anomalyco/opencode "$HOME/src/opencode preview"
+   git -C "$HOME/src/opencode preview" checkout 843a6c514e606b436a7fe713422ace0a93ad3d61
+   script/ctg/prepare-development-runtime.sh "$HOME/src/opencode preview"
+   (cd "$HOME/src/opencode preview" && /path/to/bun-1.4.2 install)
+   ```
+
+2. Launch from any directory with explicit paths (spaces are fine):
+
+   ```sh
+   /path/to/carthagent/script/ctg/source-preview.sh \
+     --source "$HOME/src/opencode preview" \
+     --profile "$HOME/.carthagent/source-preview" \
+     --bun /path/to/bun-1.4.2 \
+     --workspace "$HOME/projects/my project"
+   ```
+
+   The launcher runs `bun --no-env-file run src/index.ts --standalone <workspace>`
+   from `packages/cli` with only a private HOME, TMPDIR, XDG and OpenCode config
+   directory inside `--profile`. It disables project config and auto-update and
+   passes no inherited API keys. On first use it creates the profile (mode 0700)
+   with the Carthagent plugin, Carthage theme and CLI theme config. Existing
+   profile files are never rewritten. The private server listens on an ephemeral
+   loopback port and exits when the TUI exits.
+
+3. Sign in once inside the same profile. Enter secrets only at the terminal
+   prompt, never as arguments:
+
+   ```sh
+   script/ctg/source-preview.sh --source ... --profile ... --bun ... -- auth login
+   ```
+
+In the TUI, the folder card at the top of Projects shows the current folder and
+model. Use **Browse** (or `/browse`) to pick a folder and **Ctrl+S** to confirm.
+**New session** (also Ctrl+X N or `/new`) opens folder and model setup; the session is created only when
+you send the first message, with your current agent and the chosen model. If that agent or model is
+unavailable when you send, the send is blocked and your text is kept until you choose another. Leave with `/exit` (or Ctrl+P, “Exit the app”); relaunch with
+the same `--profile` and choose the session in Projects to continue it.
+
+See [source preview](docs/source-preview.md) for testing, patch verification and
+limits.
+
+## Install and update
+
+The installer selects an exact published release and acquires its pinned native runtime; it never falls back to an unrelated system binary. See the [native upgrade guide](docs/native-upgrade.md) for source-checkout and profile-preservation instructions, or [legacy CLI instructions](docs/legacy-cli.md) for stable 1.0.7.
+
+`ctg update --check` checks for a published release without installing. Select `--channel experimental` to include published previews; drafts are never installed. The legacy stable updater can update a clean source clone. The native updater differs: it refuses to check out a release into any active source clone, including a clean one; it installs package releases only from an npm installation. Preserve local changes and use the manual exact-tag checkout procedure in the [native upgrade guide](docs/native-upgrade.md) when updating a development checkout. Published previews are immutable. See the [preview.11 release notes](docs/release-notes-preview.11.md); the older [native migration draft](docs/release-notes-native-draft.md) is historical, not current installation guidance.
+
+## Update channels
 
 Starting with 1.0.7, update channels are an explicit opt-in:
 
@@ -71,66 +163,31 @@ a downgrade, so recovery from an experimental build does not require `--force`.
 Your sessions and provider credentials are not deleted by switching channels.
 Experimental software may still contain bugs; read its release notes first.
 
-**Releasing:** bump `version` in `package.json` and `package-lock.json`, merge, then tag `vX.Y.Z` on main and push. The `Release` workflow publishes the manifest to the control plane (`POST /v1/cli/releases`), making the tag resolvable by `ctg update` and the dashboard badge. It needs the `CARTHAGENT_CLI_RELEASE_TOKEN` repository secret set to the backend's `CARTHAGENT_CLI_RELEASE_ADMIN_TOKEN`; `CARTHAGENT_CLOUD_URL` can override the API origin as a repository variable.
-
-## Connect a provider
-
-First run needs AI credentials. One store (`~/.carthagent/agent/auth.json`) covers the console, headless runs, and the dashboard.
-
-Run `ctg login`, or use `/login` (`/auth`) inside the console. All three entry points open the same provider picker. Carthagent Ship appears first as the recommended managed option, while Anthropic, OpenAI, OpenRouter, and the other direct providers remain immediately selectable. Connected providers are marked without changing the stable ordering.
-
-The popup handles OAuth URLs, device codes, and API-key prompts inline. An in-session login returns to the active workspace and refreshes the agent without discarding the transcript or editor state.
+## Release status
 
-**Carthagent Ship** — choosing the recommended Ship row starts browser device authorization. Carthagent stores only the resulting short-lived access token and rotating refresh token in its isolated credential store; it does not ask users to paste a long-lived managed gateway key. After signing in:
+1.1.0-preview.13 is the current experimental release. It promotes the
+combined-v5 runtime patch: a directory-first Projects rail with a folder
+browser, shared folder and model setup for new sessions, and an isolated
+source-preview launcher, on top of preview.12's npm-publishable package.
+Native remains the default `ctg` interface. Ship retains approval, checks,
+review, repair, recovery, and resume; Lite remains direct execution.
+Published previews are immutable. Experimental installation is explicit and
+selects published releases only; stable 1.0.7 retains the legacy console.
 
-```sh
-ctg account                    # credit, grants, plan, and CLI sessions
-ctg billing checkout           # Builder subscription checkout URL
-ctg billing portal             # Stripe customer portal URL
-ctg logout-cloud [session-id]  # revoke the current or a named CLI session
-```
-
-Inside the console, `/account`, `/billing checkout`, `/billing portal`, and `/logout-cloud <session-id>` provide the same account controls without leaving the workspace. If Ship credit is exhausted, the console offers billing and `/login`; direct Anthropic, OpenAI, OpenRouter, custom, and other BYOK providers remain available without an upsell.
-
-Operators and internal pilots may still provide `EXPLABS_API_KEY` through the environment for direct upstream access; that key path remains separate from the public device flow. `CARTHAGENT_CLOUD_URL` may override the Carthagent account/control-plane origin, while `EXP_GATEWAY_URL` specifically overrides the direct upstream model gateway origin for preview or staging. Browser-account requests use the Ship authority at the control-plane origin; API-key requests continue to use the configured upstream gateway directly. Carthagent discovers model identities from `GET /v1/models`; the endpoint may also publish each alias's operating caps (`contextWindow`, `maxTokens`), which managed models adopt when they are stricter than the catalogued model profile. The endpoint does not provide pricing metadata, so Carthagent does not infer that field.
-
-The embeddable Cloud service also includes a hosted request authority for `GET /v1/models`, `POST /v1/chat/completions`, and `POST /v1/responses`. Operators publish immutable customer-pricing versions and versioned Carthagent aliases in the control plane. Every request receives a bounded output limit and atomically reserves its maximum customer charge before upstream dispatch. Settlement requires authoritative gateway request and physical-attempt identities plus measured token usage; known pre-dispatch failures release the hold, while ambiguous transport or accounting outcomes retain it for reconciliation instead of guessing a charge.
-
-**Direct provider API key** — export the provider's env var, or choose it in the shared login picker to store it:
-
-```sh
-export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, ...
-ctg
-```
-
-Multiple providers can be connected at once — credentials coexist in `~/.carthagent/agent/auth.json`. In the console, `^t` (settings) has a **provider** row above **model**: `←→` switches providers (and selects that provider's first model), while the model picker stays scoped to the chosen provider. `/login` adds another provider at any time.
-
-Full provider list: [provider docs](https://github.com/earendil-works/pi-coding-agent/blob/main/docs/providers.md). Override the default model with `--model <id>` (e.g. `ctg --model sonnet`). Your last model choice (via `--model`, `/model`, or the `^t` settings picker) is saved to `~/.carthagent/config.json` and reused on the next launch — pass a flag to override it for that run.
-
-## Use it
-
-```sh
-ctg                           # interactive console (persistent engine session)
-ctg "Build a task CLI"        # console, with a task
-ctg -p "..."                  # headless run (auto when stdout isn't a TTY)
-ctg demo                      # scripted mock run — no provider needed
-ctg status                    # fingerprint, contract, pending checks
-ctg check all                 # run declared checks
-ctg account                   # Ship balance, plan, grants, and sessions
-ctg billing checkout          # Ship Builder checkout URL
-ctg serve                     # web dashboard (127.0.0.1, authenticated URL)
-ctg test                      # unit suite
-ctg update                    # install the latest release (--check to peek)
-ctg --help                    # everything else
-```
+Each experimental release must pass its exact installed-package gate before
+publication. See the [preview.13 release notes](docs/release-notes-preview.13.md),
+[preview.12 notes](docs/release-notes-preview.12.md), and [preview.11 notes](docs/release-notes-preview.11.md); earlier migration findings and remaining platform caveats
+are in the [Native migration ledger](docs/opencode-migration.md#delivery-ledger),
+[native compatibility matrix](docs/native-compatibility.md), and [terminal
+evidence status](docs/native-terminal-semantics.md#evidence-status-pr-162).
 
-Inside the console: `enter` send/steer · `esc` abort (again = force-restart the engine, nothing is lost) · `^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; hold at the top or bottom of the message pane to scroll while selecting. Clipboard writes use native tools and OSC 52 (remote terminals must allow clipboard access and may impose size limits). Sessions persist under `~/.carthagent/agent/sessions/`; `ctg -c` continues the last one, `-r` opens the picker.
+## Regular CLI
 
-**Themes:** 22 AA-contrast-verified options — the default purple-and-gold `carthage` palette; dark (`opencode`, `tokyonight`, `nebula`, `ember`, `forest`, `mono`, `obsidian`, `midnight`, `nord`, `solarized-dark`, `okabe-dark`, `contrast-dark`); light (`paper`, `daylight`, `solarized-light`, `okabe-light`, `contrast-light`); and adaptive (`solarized`, `okabe`, `contrast`, `system`) themes that follow `COLORFGBG` or `CARTHAGENT_THEME_MODE=light|dark`. Pick via `--theme`, `/theme`, or `^t`; moving through the picker previews each colorway before Enter commits it. The choice is saved to `~/.carthagent/config.json` and reused on the next launch. The dashboard picker also previews themes on hover and persists the selected theme in `localStorage`. `okabe-*` uses the colorblind-safe Okabe-Ito palette.
+The split-terminal console remains available in stable 1.0.7, not as an alternate route inside the native-default experimental package. To return to stable, use `ctg update --channel stable`. Its legacy data and provider setup remain distinct from the native profile; existing transcripts remain available through the read-only archive commands.
 
-Useful flags: `--model`, `--thinking`, `--validators <file>`, `--context <file>`, `--bash-cap <sec>`, `--review ask|yes|no`, `--isolate`, `--no-delivery`, `--no-guide`, `--ascii`, `--glyphs <mode>`, `-c`/`-r`/`--session`.
+## Delivery engine and existing CLI
 
-**Glyphs:** icons, status dots, spinners and the D2 graph adapt to your terminal. `--glyphs auto` (default) keeps the Unicode set on terminals known to render it and falls back to an ASCII icon tier everywhere else, so tool icons, status marks and spinners never show up as `?` on limited fonts. Force one with `--ascii`, `--glyphs unicode|ascii`, or `CARTHAGENT_GLYPHS=unicode|ascii` / `CARTHAGENT_ASCII=1`.
+The following delivery-engine documentation describes Carthagent's shared delivery concepts and the existing CLI behavior. Native-preview coverage and compatibility are tracked separately in the [native CLI guide](docs/native-cli.md) and [migration ledger](docs/opencode-migration.md); feature parity must not be inferred from the presence of a shared delivery module.
 
 ## How it works