pantheon-opencode 1.5.0-beta.1 → 1.5.0-beta.10

package/README.md

@@ -8,7 +8,7 @@ want useful structure without giving up control of their code.
 [Português (Brasil)](README.pt-BR.md) ·
 [Repository](https://github.com/ils15/pantheon-opencode) · [MIT License](LICENSE)
 
-[![Version](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=version)](https://github.com/ils15/pantheon-opencode/releases/tag/v1.5.0)
+[![Version](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=version)](https://github.com/ils15/pantheon-opencode/releases/latest)
 [![CI](https://img.shields.io/github/actions/workflow/status/ils15/pantheon-opencode/ci.yml?branch=main&label=CI)](https://github.com/ils15/pantheon-opencode/actions)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22306637.svg)](https://doi.org/10.5281/zenodo.22306637)
 
@@ -30,7 +30,7 @@ way to plan work, make progress, check results, and keep useful project context.
 
 ## Start in 2 minutes
 
-Requirements: [OpenCode 1.18.4+](https://opencode.ai/docs/) and Node.js 18+.
+Requirements: [OpenCode 1.18.4+](https://opencode.ai/docs/) and Node.js 22+.
 
 From the project where you want to use Pantheon:
 
@@ -70,13 +70,94 @@ clear handoff between stages of work.
 
 ## Status
 
-Current release: **v1.5.0**. Pantheon is designed for OpenCode and depends on
-the availability and configuration of OpenCode and any optional services you
-choose to use. Check the [releases](https://github.com/ils15/pantheon-opencode/releases)
-and [changelog](CHANGELOG.md) for the latest changes.
+Operational checkout version: **v1.5.0-beta.2** (candidate; publication is not
+asserted here). Pantheon is designed for OpenCode and depends on the
+availability and configuration of OpenCode and any optional services you choose
+to use. Check the [releases](https://github.com/ils15/pantheon-opencode/releases)
+and [changelog](CHANGELOG.md) for the latest published changes.
+
+## Delegation engines (legacy default, native opt-in)
+
+Pantheon exposes two delegation engines behind one tool surface:
+
+- **Legacy (default)** — `pantheon_delegate`, the original engine registered by
+  the V1 plugin. No configuration is required.
+- **Native (opt-in, experimental)** — OpenCode's native `task()` child-session
+  engine, selected with `PANTHEON_DELEGATE_MODE=native`. Native is strict: it
+  does not use foreground fallback, model failover, or retry; it performs a
+  lazy capability probe on the first dispatch and includes the resulting
+  status in the delegation receipt.
+
+Legacy stays the default for v1.5.x; native is not promoted to default until
+v1.6. See [ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md)
+(Proposed) for the engine contract, rationale, and migration prerequisites.
+
+**Kill-switch:** set `PANTHEON_DELEGATION=off` (case-insensitive) to disable
+delegation entirely. The switch covers **both** engines — the legacy
+`pantheon_delegate`/read/list tools throw, and the native manager throws too.
+
+## Cost tool backend
+
+`pantheon_cost` prefers a read-only `node:sqlite` backend against the selected
+`opencode.db`. When `node:sqlite` is unavailable in the host runtime (for
+example under Bun), the tool falls back to spawning `node scripts/cost.mjs` as
+a read-only subprocess. The fallback resolves a real Node.js binary —
+`PANTHEON_NODE` first, then `node` on `PATH` — verifies it supports
+`node:sqlite` (Node.js >= 22.5), and runs the script with an argument array,
+never a shell. If neither source resolves, the tool returns `status:
+UNSUPPORTED`. Database failures return a contract status such as `UNAVAILABLE`
+or `CORRUPT_DATA` and include diagnostic detail, including captured stderr when
+available.
 
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `PANTHEON_NODE` | `node` from `PATH` | Path to a Node.js >= 22.5 binary used by the CLI fallback; an explicit path must exist and be executable, otherwise the tool fails fast instead of ignoring the override |
+
+
+## Code-mode execution (explicit opt-in)
+
+Scripts run through the `pantheon-code-mode` MCP server (`execute_code_script`)
+only when they are explicitly approved. Approval is recorded in
+`.pantheon/code-mode/manifest.json` with the SHA-256 of each script:
+
+```json
+{
+  "version": 1,
+  "scripts": {
+    "example-sync.sh": "<sha256>"
+  }
+}
+```
+
+- **No manifest → nothing executes.** A missing manifest returns
+  `INVALID_STATE`; scripts are never run implicitly.
+- **Not listed → `CONFLICT`.** The script must be approved first.
+- **Hash mismatch → `CORRUPT_DATA`.** The SHA-256 of the file on disk must
+  match the manifest entry, so edits after approval are detected.
+
+Approve or re-approve a script with the `approve_code_script` MCP tool:
+
+```
+approve_code_script("checkpoint-session.sh")
+```
+
+The installer seeds the manifest with the SHA-256 of every bundled script, so
+shipped scripts stay approved across installs. Re-run `approve_code_script`
+after intentionally editing a script. Status codes follow the shared nine-code
+contract (`OK`, `UNSUPPORTED`, `UNAVAILABLE`, `INVALID_INPUT`, `INVALID_STATE`,
+`CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`, `ESCALATE`); with `json_output=true`,
+results carry a `status` field.
 
-## What's new in 1.5.0
+Code-mode resolves project-first: `.opencode/.pantheon/code-mode` is preferred,
+then `.pantheon/code-mode`. `PANTHEON_PROJECT` overrides the working directory,
+and the installed MCP uses `cwd: "."` so OpenCode supplies the workspace. A
+global directory is used only when no usable project directory is available;
+once a project directory is selected, a missing or corrupt manifest fails
+closed instead of falling back. `doctor` validates the manifest and every
+script's SHA-256 without regenerating it.
+
+
+## What's new in 1.5.0-beta.2
 
 - OpenCode-only installer: platform guides consolidated into a single
   [OpenCode guide](docs/platforms/opencode.md).
@@ -90,9 +171,12 @@ and [changelog](CHANGELOG.md) for the latest changes.
 - Sandbox validator for global installs (`scripts/test-opencode-v1-v2-sandbox.sh`)
   covering OpenCode V1/V2 side by side — see
   [Sandbox validation](#sandbox-validation-v1v2).
+- Beta2 agent-economy policy: direct native delegation, bounded compaction
+  carry-forward, compact context encoding, and quality floors — see
+  [Beta2 agent economy policy](docs/ws3-token-opt-measurements.md#beta2-agent-economy-policy).
 - A `--prompts` installer flag is planned for a future release.
 
-## OpenCode V1/V2 — Dual Version (1.5.0)
+## OpenCode V1/V2 — Dual Version (1.5.0-beta.2)
 
 Pantheon has two **exclusive** OpenCode plugin contracts. Ordinary OpenCode
 configuration may be shared, but the Pantheon plugin registration is selected
@@ -150,9 +234,56 @@ The installer still writes the compatibility settings required by the selected
 OpenCode host, such as `experimental.subagent_depth`; this does not convert a
 V1 plugin into V2 or provide V2 with V1 hooks.
 
-## Beta releases
+## Updating between releases (beta.5+)
+
+One command keeps an existing installation current:
+
+```bash
+# Without a global install, ALWAYS pin the dist-tag — plain `npx
+# pantheon-opencode` resolves `latest`, which is the stable release (1.4.3):
+npx pantheon-opencode@beta update            # npm beta channel + config refresh
+npx pantheon-opencode@beta update --stable   # stable channel instead
+
+# With a global install, use the global bin (defaults to the beta channel):
+pantheon-opencode update
+```
 
-A pull request labeled exactly `release:beta` triggers the beta release path. See [docs/RELEASING.md](docs/RELEASING.md) for validation and recovery details.
+`update` compares your installed version with the npm dist-tag, runs
+`npm install -g pantheon-opencode@<channel>`, then re-runs `init --yes
+--headless` so config merges, the venv and MCP entries match the new package.
+Two freshness guarantees back it up:
+
+- **Postinstall artifact sync** — after any `npm install`, copy-only artifacts
+  (agents, skills, AGENTS.md, commands, MCP scripts, code-mode payload) are
+  refreshed into the existing config dir automatically; you never have to
+  re-run `init` just for file copies.
+- **Drift detection** — the installer stamps the installed version in
+  `.pantheon/install-state.json` and `doctor` warns when the package is newer
+  than the last sync, pointing at `update`.
+
+`init` also gained `--components agents,skills,...` (narrow install),
+`--clean` (alias of `--force`), `--opencode-version auto`, atomic config
+writes with an `opencode.json.bak` backup, preflight checks for python3/npm
+before any file is written, and a non-fatal Python runtime: if the venv fails,
+the install completes but MCP entries are omitted (with a warning) instead of
+pointing at a broken interpreter. Installer messages auto-detect pt-BR via
+`LANG`/`LC_ALL`.
+
+## Releases
+
+Publication is authorized **only** by an explicit `workflow_dispatch` of the
+`Release` workflow (`release_channel` input selects beta or stable). PR labels,
+pushes, merges, and tags never publish anything, and every validation gate is
+fail-closed: only an explicit PASS authorizes release evidence. See
+[docs/RELEASING.md](docs/RELEASING.md) for validation and recovery details.
+
+Release validation keeps each manifest with its lockfile: the root
+`package.json` + `package-lock.json` and the TUI
+`src/plugins/tui/package.json` + `src/plugins/tui/package-lock.json`. Both use
+`npm ci --ignore-scripts`; an `npm ci` failure blocks the run and there is no
+`npm install` fallback. A release carries one `.tgz` tarball, computes the
+SHA-256 of that same artifact, and binds the tarball and GitHub release to the
+full `TARGET_SHA`; a second pack is not interchangeable.
 
 ## Sandbox validation (V1/V2)
 
@@ -161,9 +292,9 @@ package as a real user inside an isolated sandbox (own `HOME`, npm prefix and
 venv) — never the dev environment. It checks OpenCode V1 (`opencode`) and V2
 (`opencode2`) side by side: binaries, MCP connectivity, `doctor`, and — with
 `--prompts` — a prompt battery covering the `pantheon://agents` resource,
-memory store/recall, filesystem writes and agent delegation. Environmental
-failures (network, provider auth, Docker) are classified as `AMBIENTAL` and
-never fail the run; only real failures do.
+memory store/recall, filesystem writes and agent delegation. The gate is
+fail-closed: every required check must return an explicit PASS; timeouts,
+auth/network/provider failures and missing prerequisites block the run.
 
 ```bash
 scripts/test-opencode-v1-v2-sandbox.sh --prepare          # tarball + install + init in the sandbox
@@ -177,6 +308,9 @@ Modes are combinable (e.g. `--prepare --run v1 --prompts`). Binaries are
 resolved strictly inside the sandbox npm prefix — a non-prepared sandbox fails
 fast instead of silently testing the host installation.
 
+This validates the prepared isolated sandbox only. A PASS is not proof of
+support for every real host or for host configurations that were not exercised.
+
 Env overrides:
 
 | Variable | Default | Purpose |
@@ -190,6 +324,26 @@ Env overrides:
 Exit codes: `0` no real failures · `1` real failure (see `prompts-report.md`
 in the sandbox root) · `2` usage error · `3` sandbox not prepared.
 
+### Intentional memory MCP divergence
+
+`scripts/memory_mcp_server.py` and `src/mcp/memory_mcp_server.py` are
+intentionally different. The standalone `scripts/` copy keeps the lightweight
+`memory_*` contract; the installed `src/mcp/` copy additionally exposes the
+optional codemap schema and `code_index`, `code_query`, and `code_neighbors`.
+The other shared MCP copies remain identical. Do not overwrite one memory copy
+with the other.
+
+### Task-result guard
+
+A `task-result-guard` intercepts calls to the native `task()` tool where the
+child session returns an empty or missing result. Instead of surfacing a silent
+`completed` with no payload (which confuses the orchestrator), the guard now
+raises an explicit error. This catches the common free-tier failure mode where a
+child session exceeds the uncached-prefill token budget (`BackendAdmissionRejected`)
+and returns nothing. For large payloads, prefer `pantheon_delegate` over native
+`task()` — the delegation layer has better timeout and error handling.
+
+
 ## Documentation
 
 - [Installation](docs/INSTALLATION.md) · [Quick start](docs/QUICKSTART.md)
@@ -207,9 +361,10 @@ or pull request.
 
 ## Citation and DOI
 
-Pantheon is released under the [MIT License](LICENSE). For the published v1.4.3
-record, use the [Zenodo DOI](https://doi.org/10.5281/zenodo.22306637); citation
-metadata is also available in [CITATION.cff](CITATION.cff).
+Pantheon is released under the [MIT License](LICENSE). For the historical
+published v1.4.3 record only, use the [Zenodo DOI](https://doi.org/10.5281/zenodo.22306637);
+it is not the current operational version. Citation metadata is also available
+in [CITATION.cff](CITATION.cff).
 
 Canonical repository: <https://github.com/ils15/pantheon-opencode>
 

package/README.pt-BR.md

@@ -8,7 +8,7 @@ e equipes que querem mais estrutura sem perder o controle do próprio código.
 [English](README.md) ·
 [Repositório](https://github.com/ils15/pantheon-opencode) · [Licença MIT](LICENSE)
 
-[![Versão](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=versão)](https://github.com/ils15/pantheon-opencode/releases/tag/v1.5.0)
+[![Versão](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=versão)](https://github.com/ils15/pantheon-opencode/releases/latest)
 [![CI](https://img.shields.io/github/actions/workflow/status/ils15/pantheon-opencode/ci.yml?branch=main&label=CI)](https://github.com/ils15/pantheon-opencode/actions)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22306637.svg)](https://doi.org/10.5281/zenodo.22306637)
 
@@ -71,13 +71,39 @@ verificações repetíveis e passagens claras entre etapas do trabalho.
 
 ## Status
 
-Versão atual: **v1.5.0**. O Pantheon foi feito para OpenCode e depende da
+Versão operacional neste checkout: **v1.5.0-beta.2** (candidata; esta página
+não afirma publicação). O Pantheon foi feito para OpenCode e depende da
 disponibilidade e da configuração do OpenCode e dos serviços opcionais que você
 escolher. Veja as [releases](https://github.com/ils15/pantheon-opencode/releases)
-e o [changelog](CHANGELOG.md) para acompanhar as mudanças.
+e o [changelog](CHANGELOG.md) para acompanhar as mudanças publicadas.
 
 
-## Novidades da 1.5.0
+## Execução code-mode (opt-in explícito)
+
+Scripts executados pelo MCP server `pantheon-code-mode` (`execute_code_script`)
+só rodam quando aprovados explicitamente. A aprovação fica em
+`.pantheon/code-mode/manifest.json` com o SHA-256 de cada script.
+
+- **Sem manifest → nada executa** (`INVALID_STATE`); nunca há execução implícita.
+- **Script fora do manifest → `CONFLICT`**; é preciso aprovar antes.
+- **Hash divergente → `CORRUPT_DATA`**; edições após a aprovação são detectadas.
+
+Aprove (ou reaprove) um script com a tool `approve_code_script`. O instalador
+semeia o manifest com o hash de todos os scripts empacotados. Os resultados
+seguem o contrato de nove códigos (`OK`, `UNSUPPORTED`, `UNAVAILABLE`,
+`INVALID_INPUT`, `INVALID_STATE`, `CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`,
+`ESCALATE`) e, com `json_output=true`, incluem o campo `status`.
+
+O code-mode resolve primeiro o projeto: `.opencode/.pantheon/code-mode` vem
+antes de `.pantheon/code-mode`. `PANTHEON_PROJECT` sobrescreve o diretório de
+trabalho, e o MCP instalado usa `cwd: "."` para receber o workspace do
+OpenCode. O diretório global só é usado sem um diretório de projeto utilizável;
+depois de selecionar um diretório de projeto, manifest ausente ou corrompido
+falha fechado, sem fallback silencioso. O `doctor` valida o manifest e o
+SHA-256 de cada script sem regenerá-lo.
+
+
+## Novidades da 1.5.0-beta.2
 
 - Instalador exclusivo para OpenCode: guias de plataformas consolidados em um
   único [guia OpenCode](docs/platforms/opencode.md).
@@ -93,7 +119,7 @@ e o [changelog](CHANGELOG.md) para acompanhar as mudanças.
   lado — veja [Validação em sandbox](#validação-em-sandbox-v1v2).
 - A flag `--prompts` do instalador está planejada para uma release futura.
 
-## OpenCode V1/V2 — Versão dupla (1.5.0)
+## OpenCode V1/V2 — Versão dupla (1.5.0-beta.2)
 
 O Pantheon tem dois contratos de plugin OpenCode **exclusivos**. A configuração
 comum do OpenCode pode ser compartilhada, mas o registro do plugin Pantheon é
@@ -141,7 +167,7 @@ instalador remove referências Pantheon das duas formas de config antes de
 gravar apenas o registro Pantheon selecionado. Entradas de terceiros não são
 convertidas nem reivindicadas por essa regra.
 
-O relatório `pantheon_cost` (apenas V1) pode selecionar o banco com
+O relatório `pantheon_cost`, disponível nos plugins V1 e V2, pode selecionar o banco com
 `PANTHEON_OPENCODE_VERSION=v1` ou `v2` (`opencode.db` ou `opencode-v2.db`).
 `PANTHEON_COST_DB=/caminho/absoluto/para/opencode.db` tem precedência sobre o
 seletor de versão, e um `dbPath` explícito fornecido pelo chamador da
@@ -153,9 +179,55 @@ O instalador continua gravando as configurações de compatibilidade exigidas
 pelo host OpenCode selecionado, como `experimental.subagent_depth`; isso não
 converte um plugin V1 em V2 nem dá hooks V1 ao V2.
 
-## Releases beta
+## Atualizando entre releases (beta.5+)
+
+Um comando mantém uma instalação existente em dia:
 
-Um pull request com o label exato `release:beta` aciona o fluxo de release beta. Consulte [docs/RELEASING.md](docs/RELEASING.md) para detalhes de validação e recuperação.
+```bash
+# Sem instalação global, SEMPRE fixe o dist-tag — `npx pantheon-opencode`
+# puro resolve a tag `latest`, que é o release estável (1.4.3):
+npx pantheon-opencode@beta update            # canal beta do npm + refresh do config
+npx pantheon-opencode@beta update --stable   # canal estável
+
+# Com instalação global, use o bin global (o padrão é o canal beta):
+pantheon-opencode update
+```
+
+O `update` compara a versão instalada com o dist-tag do npm, roda
+`npm install -g pantheon-opencode@<canal>` e re-executa `init --yes
+--headless` para alinhar merge de config, venv e entradas de MCP com o novo
+pacote. Duas garantias de freshness sustentam isso:
+
+- **Sync de artifacts no postinstall** — depois de qualquer `npm install`, os
+  artefatos de cópia (agents, skills, AGENTS.md, commands, scripts MCP,
+  payload code-mode) são atualizados automaticamente no config dir existente;
+  você nunca precisa re-rodar `init` só para atualizar arquivos.
+- **Detecção de drift** — o instalador grava a versão instalada em
+  `.pantheon/install-state.json` e o `doctor` avisa quando o pacote é mais
+  novo que o último sync, apontando para o `update`.
+
+O `init` também ganhou `--components agents,skills,...` (instalação enxuta),
+`--clean` (alias de `--force`), `--opencode-version auto`, escrita atômica do
+config com backup em `opencode.json.bak`, pré-checagens de python3/npm antes
+de escrever qualquer arquivo e runtime Python não-fatal: se a venv falha, a
+instalação completa mas as entradas MCP ficam de fora (com aviso) em vez de
+apontar para um interpretador quebrado.
+
+## Releases
+
+A publicação é autorizada **somente** por um `workflow_dispatch` explícito do
+workflow `Release` (o input `release_channel` escolhe beta ou stable). Labels
+de PR, push, merge e tag nunca publicam nada, e todos os gates de validação são
+fail-closed: somente um PASS explícito autoriza release evidence. Consulte
+[docs/RELEASING.md](docs/RELEASING.md) para detalhes de validação e recuperação.
+
+A validação mantém cada manifest junto do seu lockfile: o root
+`package.json` + `package-lock.json` e o TUI
+`src/plugins/tui/package.json` + `src/plugins/tui/package-lock.json`. Ambos usam
+`npm ci --ignore-scripts`; uma falha em `npm ci` bloqueia a execução e não há
+fallback para `npm install`. Uma release carrega um único tarball `.tgz`, calcula
+o SHA-256 desse mesmo artefato e vincula o tarball e o GitHub Release ao
+`TARGET_SHA` completo; um segundo pack não é intercambiável.
 
 ## Validação em sandbox (V1/V2)
 
@@ -165,8 +237,9 @@ prefix npm e venv próprios) — nunca o ambiente de desenvolvimento. Ele verifi
 OpenCode V1 (`opencode`) e V2 (`opencode2`) lado a lado: binários, conectividade
 MCP, `doctor` e — com `--prompts` — uma bateria de prompts cobrindo o recurso
 `pantheon://agents`, memory store/recall, escrita no filesystem e delegação de
-agente. Falhas ambientais (rede, auth de provider, Docker) são classificadas
-como `AMBIENTAL` e nunca falham a execução; apenas falhas reais falham.
+agente. O gate é fail-closed: todo check obrigatório precisa terminar em PASS
+explícito; timeout, falha de auth/rede/provider e pré-requisitos ausentes
+bloqueiam a execução.
 
 ```bash
 scripts/test-opencode-v1-v2-sandbox.sh --prepare          # tarball + install + init no sandbox
@@ -180,6 +253,9 @@ Os modos são combináveis (ex.: `--prepare --run v1 --prompts`). Os binários s
 resolvidos estritamente dentro do prefix npm do sandbox — um sandbox não
 preparado falha rápido em vez de testar silenciosamente a instalação do host.
 
+Isso valida somente o sandbox isolado e preparado. Um PASS não prova suporte
+para todo host real nem para configurações de host que não foram exercitadas.
+
 Variáveis de ambiente:
 
 | Variável | Padrão | Finalidade |
@@ -194,6 +270,15 @@ Códigos de saída: `0` sem falhas reais · `1` falha real (veja
 `prompts-report.md` na raiz do sandbox) · `2` erro de uso · `3` sandbox não
 preparado.
 
+### Divergência intencional do memory MCP
+
+`scripts/memory_mcp_server.py` e `src/mcp/memory_mcp_server.py` são
+intencionalmente diferentes. A cópia independente em `scripts/` mantém o
+contrato leve de `memory_*`; a cópia instalada em `src/mcp/` também expõe o
+schema opcional de codemap e `code_index`, `code_query` e `code_neighbors`. As
+outras cópias compartilhadas permanecem idênticas. Não sobrescreva uma cópia de
+memória com a outra.
+
 ## Documentação
 
 - [Instalação](docs/INSTALLATION.md) · [Início rápido](docs/QUICKSTART.md)
@@ -211,9 +296,10 @@ uma issue ou pull request.
 
 ## Citação e DOI
 
-O Pantheon é distribuído sob a [Licença MIT](LICENSE). Para o registro publicado
-da v1.4.3, use o [DOI do Zenodo](https://doi.org/10.5281/zenodo.22306637); os
-metadados de citação também estão em [CITATION.cff](CITATION.cff).
+O Pantheon é distribuído sob a [Licença MIT](LICENSE). Para o registro histórico
+publicado da v1.4.3 apenas, use o [DOI do Zenodo](https://doi.org/10.5281/zenodo.22306637);
+essa não é a versão operacional atual. Os metadados de citação também estão em
+[CITATION.cff](CITATION.cff).
 
 Repositório canônico: <https://github.com/ils15/pantheon-opencode>