pantheon-opencode 1.6.0-beta.5 → 1.6.0-beta.7

package/CHANGELOG.md

@@ -18,6 +18,136 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.6.0-beta.7] - 2026-10-10
+
+<!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. -->
+
+## 🆕 What's New
+
+- **Simpler agent dispatch:** answer no-change questions directly, send bounded
+  fixes to one specialist, load council instructions on demand, and remove
+  routine per-task KV/cache routing. No token, cost, or latency savings are
+  claimed without live measurements.
+- **V2 install and permissions:** use a versioned package-root plugin pin and
+  migrate V1 `task`/`write` permissions to V2 `subagent`/`edit`, retaining the
+  stricter effect when rules collide.
+- **Release and runtime hardening:** bounded in-process secret scanning,
+  fail-closed V2 registration, TUI timer disposal, truthful doctor reporting,
+  and guarded V2 sandbox prepare/reset.
+
+## 🐞 Fixed
+
+- TUI usage polling now starts only after its optional slot registers and all
+  refresh timers are disposed on shutdown.
+- Doctor detects version drift in string and object V2 package pins, including
+  prerelease versions; checkout installs warn when their exact npm pin is not
+  published yet.
+- V2 permission migration maps `task → subagent` and `write → edit` and
+  preserves the stricter conflicting rule.
+
+## ⚠️ Known Issues
+
+- Live provider E2E is blocked by HTTP 403; an interactive model-backed V2 TUI
+  turn remains unverified.
+- The V2 tool canary targets OpenCode 2.0.22 while the installable CLI differs
+  (issue #216); V1 host end-to-end validation is also deferred.
+- The observed P0-4 tool-catalog oscillation has no reproduced cause; its
+  reproduction harness remains follow-up work.
+- V2 `init` from an unpublished source checkout writes a versioned npm pin that
+  cannot resolve until that version is published; the installer warns.
+## [v1.6.0] - 2026-10-10
+
+This stable candidate consolidates the beta.1–beta.6 changes. The original beta
+entries remain below as historical records so release detail is not discarded.
+
+## 🆕 What's New
+
+- **OpenCode V2 plugin and installer path:** generation detection, V2 plugin
+  registration, three functional V2 tools, read-only enforcement, and explicit
+  reporting of the smaller V2 feature surface. The V1 API path remains in the
+  package, but no V1 host has been exercised end-to-end in this release.
+- **Sandbox validation and release hardening:** fail-closed checks, V2 MCP and
+  hook probes, package/version inventory validation, and reproducible package
+  evidence. The sandbox now generates its runner, isolated TUI launcher, and
+  README during `--prepare`.
+- **Dependency and TUI maintenance:** synchronized release manifests, updated
+  dependency/security overrides, and TUI/runtime consistency checks.
+- **Simpler agent dispatch path:** no-change questions can be answered directly;
+  bounded fixes route to one specialist; council guidance is loaded on demand;
+  and default routing no longer makes per-task KV/cache lookups. Synthetic
+  timeout/session behavior unsupported by the host was removed. These changes
+  simplify the prompt and dispatch path; this release makes no measured token,
+  cost, or latency improvement claim.
+
+## 🐞 Fixed
+
+- `PANTHEON_V2_MCP_LIST_TIMEOUT` now defaults to 15 seconds in both the harness
+  and generated `run-test.sh`, including under `set -u`; the default does not
+  depend on an exported environment variable.
+- `PANTHEON_REPO` is resolved consistently for prepare, generated tests, and
+  reset guards. Relative, dangling, missing, or non-Pantheon paths fail before
+  packaging; `.repo-dir` is atomically written and validated before use.
+- Sandbox prepare/reset reject roots overlapping a checkout or the user's
+  `HOME`. `PANTHEON_V2_PORT` defaults to 49376, is range-checked, and refuses an
+  occupied port without reusing or stopping the existing service.
+- Sandbox `tmp/` is not blanket-deleted: prepare only expires hash-named Node
+  compile-cache files owned by the current user and older than 30 days. Runtime
+  state, unknown entries, and handoff/evidence files remain untouched.
+- **V2 plugin registration is stable across install locations.** `init` now
+  writes the exact `pantheon-opencode@<version>` npm entry and the package root
+  exports the V2 plugin. This replaces absolute paths into a global prefix or
+  transient `npx` cache; `doctor` recognizes the pinned package and reports
+  version drift. A clean production-only package consumer test covers the root
+  export.
+- **V1-to-V2 permissions preserve their intended actions.** Migration maps
+  `task` to V2 `subagent` and `write` to the `edit` action that also governs
+  `write`/`patch`. If V1 `edit` and `write` rules collide on one resource, the
+  more restrictive effect wins. Tests cover global and nested agent rules.
+- **`doctor` distinguishes SQLite readiness from tool registration.** The
+  `node:sqlite` check now says it verifies only the backend prerequisite, not
+  whether `pantheon_cost` registered on the active host.
+- **Release documentation was reconciled with current code.** The V2 caller /
+  target matrix is enforced by `permission.evaluate`; the bridge export is an
+  importable utility but is not wired into production; the V2 event count and
+  package registration format are corrected in both READMEs and the install /
+  upgrade guides.
+
+## ⚠️ Known Issues
+
+- **V1 host canary is deferred.** The tested package dependency pair is
+  `@opencode-ai/plugin@1.18.33` + `@opencode-ai/sdk@1.18.33`; this is not an
+  end-to-end V1 host compatibility claim. No OpenCode `1.18.35` host support is
+  asserted.
+- **V2 support remains partial.** The tool canary was authored against
+  `opencode 2.0.22`; the installable CLI has drifted from that canary contract
+  (tracked in issue #216). See the README compatibility table for the measured
+  evidence and limitations.
+- **Release validation is not complete.** Live provider E2E returned HTTP 403,
+  the interactive V2 TUI/model-backed turn has not been verified, and the
+  previously observed within-session tool-catalog oscillation (P0-4) still has
+  no reproduced cause. This candidate must not be published until the host
+  validation gates are resolved or explicitly waived.
+- **V2 init from an unpublished source checkout cannot bootstrap its own npm
+  pin.** It writes the exact package version and emits a warning; OpenCode
+  cannot resolve that version until it is published. This is limited to
+  running the installer from the repository checkout. After publication, use
+  the npm-installed or `npx` installer for the supported consumer path.
+
+## [v1.6.0-beta.6] - 2026-10-05
+
+&lt;!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. --&gt;
+
+## 🆕 What's New
+
+- **Política de suporte documentada: a linha 1.6.x é a ÚLTIMA compatível com OpenCode 1.X.** A partir de **1.7, toda release é breaking change com alvo em OpenCode 2.** O limite está escrito no `README.md` (seção "Compatibility and support policy", com matriz de suporte) e em `docs/INSTALLATION.md` (seção "OpenCode V1/V2 — contrato de plugin"), não duplicado em um documento novo: os dois arquivos já eram o ponto de entrada do contrato de plugin, e um terceiro documento seria um terceiro lugar para divergir. O texto distingue as duas células da linha 1.6.x — a célula 1.X é o contrato V1 (6 tools, lifecycle do board, hooks V1, compaction V1) e a célula OpenCode 2 é o contrato V2, que é real porém **menor**: 3 tools, sem as `pantheon_goal_*` e sem a matriz de delegação caller→target. **O suporte a OpenCode 2 na linha 1.6 é documentado como parcial, e não como completo**, por duas razões verificadas: (a) o canário de ferramentas V2 foi escrito contra `opencode 2.0.22`, host que não é publicado em nenhum canal npm — contra o `@opencode-ai/cli` instalável o mesmo canário falha 12/12, porque `/api/experimental/session/{id}/wait` foi promovido para `/api/session/{id}/wait` (404 no caminho antigo) e `ctx.tool.list` não existe mais; corrigindo apenas a rota, 10/12 passam no mesmo host, o que caracteriza descasamento canário/host e não regressão medida do plugin (issue #216, PR #213); (b) não existe perna V1 de validação end-to-end — `scripts/test-opencode-v2-sandbox.sh` é V2-only e rejeita `--run v1` — portanto a versão exata de host 1.X exercitada end-to-end pela linha 1.6 fica registrada como **não verificada**, e o caminho 1.X é sustentado pelo pin de dependência (`@opencode-ai/plugin` / `@opencode-ai/sdk` `1.18.33`), pelos testes unitários do gate de geração e pelos testes end-to-end do installer sobre a config emitida.
+
+## 🐞 Fixed
+
+- **Os exemplos de chamada MCP nos arquivos de prompt ensinavam um contrato que não existe no schema real.** Um `pantheon-persistence.kv_get` ao vivo foi rejeitado com `namespace: Missing key`; a linha que o produziu foi `src/agents/zeus.md:189` (`depth = kv_get("deleg:depth") ?? 0`), cuja cópia instalada em `~/.config/opencode/agents/zeus.md` é a que executou. A causa não era o servidor MCP: os arquivos de agente e de instrução ensinavam chamadas posicionais sem `namespace`, enquanto o schema real é `kv_get({ namespace /* obrigatório, sem default */, key, scope? })` — `kv_store.namespace` é igualmente obrigatório e `kv_store.value` é `str`. **A correção está nos docs, e não em adicionar um `namespace` default:** um default escreveria estado de coordenação no namespace errado silenciosamente, então *obrigatório* é o desenho correto. A mesma classe de defeito foi corrigida em `context_save` (posicional, com um helper `json()` inexistente e sem o `session_id` obrigatório → forma por palavra-chave com `content=JSON.stringify(...)`), em `memory_store` (`value` precisa ser uma string JSON codificada → agora iguala o padrão já correto de `metadata`, o que resolveu uma aut contradição no mesmo arquivo), na aritmética de profundidade (envolvida em `String(...)`, porque `kv_store.value` é `str` e não `int`) e em `memory_search(query, ...)` → `query=` em todas as instâncias. `AGENTS.md` é artefato gerado e foi reconstruído, nunca editado à mão.
+- **Um bypass de permissão vivo: `edit: deny` não cobria `hashline_edit`.** A regra `edit: deny` é avaliada por nome de ferramenta, e `hashline_edit` não é `edit` — então os agentes restritos a `edit: deny` (`zeus`, `athena`, `iris`, `nyx`, `themis`) podiam editar arquivos assim mesmo, escrevendo no disco por um caminho que a negação não cobria. `hashline_edit: deny` foi adicionado a esses cinco agentes. **Não era uma condição de corrida nem um erro de configuração: era uma tabela de permissões incompleta**, o que significa que a negação nunca esteve de fato aplicada a quem só deveria ler.
+- **`test:node` reportava sucesso tendo coletado zero testes.** `node --test <glob>` sai com 0 quando o glob não expande (Node >= 22), e foi exatamente o que aconteceu: um glob que nunca expandiu produziu um gate verde que não executou nada. Pior, `tests/` estava ausente da allow-list `files` do pacote, então um consumidor que rodasse `npm test` recebia esse verde. Agora os scripts de teste falham em voz alta quando a coleta é zero, e a guarda tem teste próprio (`tests/run-node-tests.test.mjs`) que a dirige como subprocesso — o contrato é o código de saída, então testá-la em processo não provaria nada.
 ## [v1.6.0-beta.5] - 2026-10-05
 
 &lt;!-- Add new changes here. Running `node scripts/versioning.mjs apply` will

package/README.md

@@ -31,7 +31,9 @@ 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
-22.22.2+ (or 24.15.0+ / 26+).
+22.22.2+ (or 24.15.0+ / 26+). For which OpenCode generation each Pantheon
+release line supports, see
+[Compatibility and support policy](#compatibility-and-support-policy).
 
 Pantheon declares `engines.node` as `^22.22.2 || ^24.15.0 || >=26.0.0`. The
 floor reflects what the dependency tree actually needs — the transitive
@@ -62,6 +64,13 @@ Once OpenCode is running, describe the outcome you want:
 ```
 
 Pantheon helps turn that request into a plan and a sequence of reviewed steps.
+For questions that do not require repository changes, Zeus answers directly;
+small, reversible fixes use one specialist dispatch. Discovery, planning,
+parallel work, and council review are reserved for tasks that benefit from them.
+
+For a tiny, bounded repair, invoke `@talos` directly (for example,
+`@talos fix this typo`). That skips the Zeus orchestration call; use `/pantheon`
+for planning, delegation, multi-file work, or quality gates.
 
 ## Who is it for?
 
@@ -80,15 +89,96 @@ clear handoff between stages of work.
 
 ## Status
 
-Candidate version: the manifests in this checkout express the version being
-prepared, not a confirmed publication. A beta is published only after the
-Release workflow completes successfully. To check which version is actually
-published, consult the npm `beta` dist-tag. Pantheon is designed for OpenCode
+Candidate version: **1.6.0-beta.7**. The manifests in this checkout express a
+beta candidate, not a confirmed publication; beta publication happens only
+after the explicit Release workflow completes successfully. To check the
+published beta, consult the npm `beta` dist-tag. 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.
 
+## Compatibility and support policy
+
+> ### ⚠️ 1.6.x is the LAST line that supports OpenCode 1.X
+>
+> **OpenCode 1.X support ends after the 1.6 line.** From **1.7 onward, every
+> release is a breaking change targeting OpenCode 2.** A 1.6.x install is the
+> last one that runs on an OpenCode 1.X host; do not plan an upgrade across the
+> 1.6 → 1.7 boundary while your host is still on OpenCode 1.X.
+
+| Pantheon line | OpenCode 1.X host | OpenCode 2 host |
+|---|---|---|
+| **1.6.x** (current line) | **Supported.** V1 plugin contract | Supported, reduced surface — V2 contract |
+| **1.7 and later** | **Not supported.** Breaking change | Target of the 1.7+ work |
+
+Both columns of the 1.6.x row are real, and they are not the same claim. Read
+[the plugin contract](#opencode-v1v2--dual-version-160-beta1) for what each
+generation actually registers.
+
+### What "supported on OpenCode 1.X" concretely means
+
+On the 1.6 line, an OpenCode 1.X host gets the **V1 plugin**:
+`src/plugin.ts` plus `src/plugins/pantheon-hooks.ts`, registered under the
+singular `plugin` config key. That surface registers 6 tools
+(`hashline_edit`, the 3 `pantheon_goal_*` tools, `pantheon_cost`,
+`pantheon_model`), the BackgroundJobBoard lifecycle, the V1 event/tool hooks and
+the V1 compaction path. It is selected automatically: the generation gate
+(`--opencode-version`, else `OPENCODE_VERSION`, else a `OPENCODE_BIN` basename of
+`opencode2`, else a `--version` probe where major ≥ 2 selects V2) resolves a 1.X
+host to V1.
+
+The two generations are exclusive. The installer strips Pantheon references from
+both config shapes and registers only the selected one, so a 1.X host never
+loads the V2 plugin and a V2 host never loads the V1 plugin. Forcing V2 on a 1.X
+host is an unsupported mixed/wrong-generation configuration, not a supported mode.
+
+### What the OpenCode 2 path is — and is not
+
+**Not inert.** V2 registers the version-pinned npm package
+`pantheon-opencode@<version>` (pinned to the installed Pantheon version); its
+package-root export points to `src/plugin-v2.ts`.
+It registers real tools with `input`/`output` schemas via
+`ctx.tool.transform()`, five event subscriptions, session hooks, and tool/
+permission hooks for read-only enforcement and the Pantheon caller→target
+delegation matrix. For Pantheon-managed targets, Zeus may delegate to any
+registered agent; Athena and Hermes may target Apollo only; other Pantheon
+callers and unknown callers are denied. Child sessions cannot delegate to
+Pantheon agents. Native/custom targets remain under host permissions. V2 never
+adds an allow grant or overrides an explicit host deny; missing or mismatched
+identity fails closed for a Pantheon delegation. The three goal tools remain
+unsupported and are reported as `goal-tools`.
+
+**Not complete either, and the V2 support claim is currently narrowed.** Two
+facts, both recorded in this repository rather than smoothed over:
+
+- **The host-backed V2 gate is red on the installable OpenCode CLI.** The V2 tool
+  canary (`tests/canary/plugin-v2-tool-canary.test.mjs`) was written against
+  `opencode 2.0.22`, which no npm channel publishes. Against the installable
+  `@opencode-ai/cli` host, `/api/experimental/session/{id}/wait` has been
+  promoted to `/api/session/{id}/wait` (the old path 404s) and `ctx.tool.list`
+  is absent, so the canary fails 12/12 there. That is a canary/host-generation
+  mismatch, not a measured plugin regression — with only the route renamed, 10/12
+  pass on the same host, including the edit being applied and the mutant still
+  caught. Tracked as [issue
+  #216](https://github.com/ils15/pantheon-opencode/issues/216); the fail-closed
+  CI change is [PR #213](https://github.com/ils15/pantheon-opencode/pull/213).
+- **The 2.x host claims in `src/plugin-v2.ts` are measured against `2.0.22`
+  specifically**, not against the current installable CLI. Re-measurement
+  against the current host is outstanding and is tracked in the same issue.
+
+Treat the 1.6 line's OpenCode 2 support as **real but partial**, and do not read
+the 1.6.x row as "OpenCode 2 is finished".
+
+### Verified dependency and host evidence
+
+| What | Verified against | How |
+|---|---|---|
+| V1 plugin API/generation checks | The dependency pair pinned by this release: `@opencode-ai/plugin@1.18.33` + `@opencode-ai/sdk@1.18.33` | `package.json`; generation-gate unit tests over injected host banners; installer end-to-end tests asserting the emitted `opencode.json` shape. This is not a claim that a V1 host was exercised end-to-end. |
+| V2 plugin tool surface | `opencode 2.0.22` (the host the canary was written against) | `tests/canary/plugin-v2-tool-canary.test.mjs`, driving `hashline_edit` through a real `opencode serve` |
+| V2 against the current installable CLI | **Not verified.** Canary fails 12/12; see issue #216 | — |
+| Exact 1.X host version exercised end-to-end | **Unverified; V1 host canary deferred.** The sandbox runner is V2-only and `--run v1` is rejected | — |
+
 ## Delegation (native `task()`)
 
 Pantheon delegates exclusively through OpenCode's native `task()` child-session
@@ -98,6 +188,18 @@ there is no Pantheon-specific delegation tool surface to configure. See
 [ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md) for the
 historical engine contract.
 
+This 1.6.0-beta.7 candidate consolidates the final beta.6 follow-ups: safer
+V2 installation and permission migration, bounded in-process secret scanning,
+sandbox hardening, TUI lifecycle fixes, and a simpler agent dispatch path.
+Zeus answers no-change questions directly and routes bounded fixes once; the
+council procedure is loaded only for a council, without per-task KV/cache
+lookups. Runtime call counts and latency have not been measured. Live provider
+E2E and a model-backed interactive V2 TUI turn remain unverified.
+
+Transient delegation dispatch failures get at most one retry. A refusal or
+failed check is not repeated; after the retry fails, the configured fallback
+chain applies once or Zeus escalates.
+
 ## Cost tool backend
 
 `pantheon_cost` prefers a read-only `node:sqlite` backend against the selected
@@ -187,8 +289,8 @@ per installation; V1 and V2 Pantheon plugins must never be registered together.
 | | V1 | V2 |
 |---|---|---|
 | OpenCode config key | singular `plugin` | plural `plugins` |
-| Pantheon registration | `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts` | `<installed>/src/plugin-v2` directory (`index.ts` re-exports `src/plugin-v2.ts`) |
-| Runtime contract | Pantheon V1 plugin: 6 tools (`hashline_edit`, the 3 goal tools, `pantheon_cost`, `pantheon_model`), event/tool hooks and V1 compaction handling | Full V2 plugin: 3 tools (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 5 event subscriptions, session hooks (`prompt`, `context`), a read-only-enforcing tool `execute.before` hook, plus configuration transforms |
+| Pantheon registration | `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts` | Version-pinned npm package `pantheon-opencode@<version>` (root export loads V2) |
+| Runtime contract | Pantheon V1 plugin: 6 tools (`hashline_edit`, the 3 goal tools, `pantheon_cost`, `pantheon_model`), event/tool hooks and V1 compaction handling | V2 plugin: 3 Pantheon tools when required enforcement registers, 5 event subscriptions, session hooks (`prompt`, `context`), a read-only and secret-scanning `execute.before` hook, plus configuration transforms |
 | V1 APIs | Registered | Own tool definitions via `ctx.tool.transform()` — not the V1 plugin path |
 
 The V2 plugin provides 3 orchestration tools (`hashline_edit`, `pantheon_cost`,
@@ -208,10 +310,16 @@ surface: the host includes the active agent on the event, a read-only agent
 `createEnforcementGuard` throws to deny `edit`, `write`, `bash`, `task`,
 `hashline_edit` and `pantheon_model`. It does **not** rely on the V1
 `tool.execute.before` hook, which lives in `src/plugin.ts` and is not loaded
-when only `plugin-v2` is configured. The companion `execute.after` hook and the
-`permission.evaluate` hook are registration points with no V2-side behaviour,
-and the V1 caller/target delegation matrix for native `task()` is not enforced
-on V2.
+when only `plugin-v2` is configured. The `permission.evaluate` hook enforces
+the V2 caller/target matrix for Pantheon-managed targets across every entry in
+the host's `resources` array. Native-only resources pass through unchanged to
+OpenCode's permission policy; mixed native/Pantheon requests and multi-target
+requests are denied unless every Pantheon target is explicitly allowed for the
+authoritative caller. Explicit host denies remain final, and missing or
+unknown resource data fails closed. If a denied evaluation has no mutable host
+output argument, the hook throws to fail closed rather than silently omitting
+the denial. V2 `execute.after` runs the completed-result chain:
+`task-result-guard` → `context-sandbox` → `read-enhancer`.
 
 Every V2 tool declares an `output` schema. OpenCode 2.0.x requires the
 declaration and the resolved result to agree in both directions, so an
@@ -220,14 +328,41 @@ every call. Unsupported V2 features are `legacy-hooks` (the V1-specific hook
 surface), `catalog-transform`, `integration-transform`, `skill-transform` and
 `goal-tools`.
 
-The package exposes both contracts as importable exports: `pantheon-opencode/plugin`
-(V1), `pantheon-opencode/plugin-v2` (V2) and `pantheon-opencode/v2-bridge`
-(optional interop), so a host can load either contract explicitly.
-
-The V1→V2 bridge (`src/pantheon/v2-bridge.ts`) enables optional interop:
-V1 infrastructure singletons (BackgroundJobBoard, GoalStore,
-TodoEnforcer, VisionHandler) are passed through V2 `ctx.options`. The bridge is
-optional — V2 works standalone with graceful degradation.
+When `init --opencode-version v2` migrates a V1-shaped permission config, it
+translates `task` to the V2 `subagent` action and `write` to `edit` (which also
+covers host `write`/`patch`). If legacy `edit` and `write` rules collide on a
+resource, migration keeps the stricter effect. Hand-edited V2 configs should
+use the native top-level `permissions` array and action/resource/effect form.
+
+### Runtime secret-scanning limit
+
+V1 and V2 use the same in-process scanner on their tool `execute.before` paths.
+The scanner accepts up to **5 MiB (5,242,880 UTF-8 bytes) of serialized hook
+payload**. Larger or malformed payloads are denied fail-closed; the rejected
+payload is not written to the scanner log. This bound applies to the complete
+serialized hook payload, not just one argument field. Before calling
+`JSON.stringify`, the scanner iteratively preflights compact JSON byte size,
+including UTF-8 and JSON escapes, and stops as soon as the limit is exceeded.
+It rejects cycles, enumerable accessors and `toJSON` hooks, proxies, excessive
+nesting, and non-JSON values without serializing or logging them.
+
+V2 registers its required enforcement hook before registering Pantheon tools.
+If the host rejects that hook, startup reports `secret-scan-hook` and
+`pantheon-tools-disabled`, and Pantheon V2 tools are not registered. This does
+not disable or claim scanner coverage for native host built-in tools; those may
+remain available under the host's own policies. The opt-in timing harness is
+reproducible with `npx tsx scripts/bench-secret-scanner.ts`: it runs 3 warmups
+and 15 measured calls per size, reporting median timings for the current
+`scanSecretText` implementation on safe ASCII strings only. It excludes payload
+preflight/serialization and host-hook overhead, is not a historical or
+Bash-versus-TypeScript comparison, and makes no speedup claim. It does not print
+scan input.
+
+The package exposes both contracts as importable exports: the package root and
+`pantheon-opencode/plugin-v2` load V2; `pantheon-opencode/plugin` loads V1.
+`pantheon-opencode/v2-bridge` is currently an importable utility only:
+production setup does not wire it into the V2 plugin, so it does not provide
+runtime interoperability or restore V1 goal/board features.
 
 Select the contract explicitly when installing:
 
@@ -244,8 +379,8 @@ the host in this order: an explicit `OPENCODE_VERSION=v1|v2` wins; otherwise an
 binary is asked for its `--version` and a major of 2 or more selects V2. Every
 other case — an unreadable probe, an unparseable banner, or a banner whose
 version-like tokens contradict each other with no tool name to break the tie —
-warns once and falls back to V1, because a plural `plugins` directory entry on
-an unknown 1.x host loses the plugin entirely.
+warns once and falls back to V1, because the V2-only package export is not a
+valid V1 runtime contract on an unknown 1.x host.
 
 The probe prefers the token that follows the tool name, so a runtime token
 ahead of it (`node v22.1.0 (opencode 1.18.33)`) or a trailing build date
@@ -301,11 +436,17 @@ Key order does not matter.
 
 ## Updating between releases (beta.5+)
 
+> **Read [Compatibility and support policy](#compatibility-and-support-policy)
+> before upgrading across a line boundary.** 1.6.x is the last line that
+> supports an OpenCode 1.X host; 1.7+ is breaking-change territory targeting
+> OpenCode 2. Within the 1.6 line, `update` is the supported path.
+
 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):
+# Without a global install, pin the intended npm dist-tag. The `latest` tag
+# reflects the most recently published stable release, not an unpublished
+# release candidate:
 npx pantheon-opencode@beta update            # npm beta channel + config refresh
 npx pantheon-opencode@beta update --stable   # stable channel instead
 
@@ -391,6 +532,10 @@ Release validation keeps each manifest with its lockfile: the root
 SHA-256 of that same artifact, and binds the tarball and GitHub release to the
 full `TARGET_SHA`; a second pack is not interchangeable.
 
+CI also rebuilds the TUI with `npm run build --prefix src/plugins/tui` and
+checks every packaged `dist` artifact byte-for-byte against its checked-in
+version, including final newlines.
+
 ## Sandbox validation (V2)
 
 `scripts/test-opencode-v2-sandbox.sh` validates the globally installed
@@ -402,10 +547,12 @@ 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.
 
-"V2" here refers only to the hook canary observed against an OpenCode v2.0.18
-host, where at least one tested hook callback fired; it does not establish
-compatibility with the stable `@opencode/plugin@2.0.18` SDK or full 2.x
-contract. This branch still pins transitional `@opencode-ai/plugin@1.18.30`.
+The historical hook canary observed at least one callback on an OpenCode
+v2.0.18 host; the tool canary was written against v2.0.22. Those observations
+do not establish compatibility with the current installable `@opencode-ai/cli@beta`,
+an SDK contract for all of 2.x, or a V1 host. This release pins the V1 plugin
+dependency pair at `@opencode-ai/plugin@1.18.33` and `@opencode-ai/sdk@1.18.33`;
+the V1 host canary remains deferred.
 On hosts where both `opencode` and `opencode2` exist, the latter is typically
 a shim that execs the same binary, so an older side-by-side comparison proved
 nothing about the binary itself. The project is V2-exclusive, so there is a
@@ -418,7 +565,7 @@ scripts/test-opencode-v2-sandbox.sh --prompts     # base validation + prompt bat
 scripts/test-opencode-v2-sandbox.sh --rehydrate   # offline context rehydration/session-summary probe
 scripts/test-opencode-v2-sandbox.sh --hooks       # V2 hook callback canary
 scripts/test-opencode-v2-sandbox.sh --rehydrate --hooks # run both canaries
-scripts/test-opencode-v2-sandbox.sh --reset       # wipe the sandbox root
+scripts/test-opencode-v2-sandbox.sh --reset       # guarded reset of the sandbox root
 ```
 
 Modes are combinable (e.g. `--prepare --run v2 --prompts`). `--rehydrate` runs
@@ -431,8 +578,20 @@ rehydration fails, and the command returns a failing status afterward. These
 are test/sandbox canaries, not proof of Pantheon security enforcement. Binaries
 are resolved strictly inside the sandbox npm prefix — a non-prepared sandbox
 fails fast instead of silently testing the host installation. The sandbox is
-always built from the checkout this script lives in; it never infers a
-repository from a sibling directory.
+always built from the checkout this script lives in unless `PANTHEON_REPO` is
+set to an absolute path for an existing `pantheon-opencode` checkout. The same
+resolved checkout is used by prepare and the generated `run-test.sh`; dangling,
+relative, and non-Pantheon paths fail before packaging. `--prepare` generates
+`run-test.sh`, `start-pantheon.sh`, and a sandbox-local `README.md`.
+
+`PANTHEON_V2_PORT` selects the dedicated loopback port (default `49376`). The
+harness validates the port and refuses an occupied listener without reusing or
+stopping it. `PANTHEON_V2_HOST` defaults to `127.0.0.1` and rejects non-loopback
+addresses. `PANTHEON_V2_MCP_LIST_TIMEOUT` controls each `mcp list` call
+(default `15` seconds). On prepare, only hash-named Node compile-cache files
+owned by the current user and older than 30 days may expire under
+`tmp/node-compile-cache`; runtime state and unrecognized files (including
+handoff evidence) are preserved.
 
 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.
@@ -509,6 +668,22 @@ Ideas, bug reports, documentation improvements, and code contributions are
 welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue
 or pull request.
 
+### Reproducible benchmark evidence
+
+The beta2 benchmark records reported token usage separately from its
+character-based fallback estimate; source bytes and logical line counts remain
+provenance data and are never converted into tokens. Cross-report comparisons
+require matching model/config provenance and reported OpenCode usage. Offline
+fixture responses are mocked: their reported values are labeled separately,
+excluded from `actual` usage, and blocked from comparative metrics and GEPA.
+Fixture quality outcomes test the offline contract; they are not evaluation
+evidence.
+Reproduce the
+checked-in AGENTS.md history manifest with
+`python3 -m benchmarks.beta2.provenance --output benchmarks/beta2/fixtures/agent-baseline-provenance.json`.
+For OpenCode benchmark runs, provide `--model` and `--config-sha256` so reports
+can be compared safely.
+
 ### Project-level `opencode.json`
 
 The published package carries no `opencode.json` template. `init` still writes

package/README.pt-BR.md

@@ -53,6 +53,19 @@ Com o OpenCode em execução, descreva o resultado que você quer:
 ```
 
 O Pantheon ajuda a transformar esse pedido em um plano e em etapas revisadas.
+Perguntas sem mudança no repositório são respondidas diretamente; correções
+pequenas usam uma única delegação. Discovery, planejamento, paralelismo e
+revisão em council ficam para quando o escopo ou o risco justificarem.
+
+Para uma correção pequena e bem delimitada, chame `@talos` diretamente (por
+exemplo, `@talos corrija este typo`). Assim você pula a chamada de orquestração
+do Zeus; use `/pantheon` para planejamento, delegação, mudanças em vários
+arquivos ou gates de qualidade.
+
+O procedimento completo de council só é carregado em `/pantheon` ou quando uma
+decisão material realmente exige perspectivas distintas. Falhas de dispatch
+podem ser tentadas novamente uma vez; testes reprovados e recusas não são
+repetidos automaticamente.
 
 ## Para quem é?
 
@@ -71,11 +84,13 @@ verificações repetíveis e passagens claras entre etapas do trabalho.
 
 ## Status
 
-Versão operacional neste checkout: **v1.6.0-beta.1** (primeira beta compatível
-com OpenCode 2; 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 publicadas.
+Versão candidata neste checkout: **v1.6.0-beta.7** (manifestos preparados;
+publicação ainda não confirmada). Para verificar a beta publicada, consulte a
+dist-tag `beta` do npm. O histórico permanece no [changelog](CHANGELOG.md). 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 publicadas.
 
 
 ## Execução code-mode (opt-in explícito)
@@ -121,13 +136,13 @@ registrados juntos.
 | | V1 | V2 |
 |---|---|---|
 | Chave de config do OpenCode | `plugin` singular | `plugins` plural |
-| Registro Pantheon | `src/plugin.ts` mais `src/plugins/pantheon-hooks.ts` | `pantheon-opencode/plugin-v2` (`src/plugin-v2.ts`) |
-| Contrato de runtime | Plugin Pantheon V1: 6 ferramentas (`hashline_edit`, as 3 ferramentas de goal, `pantheon_cost`, `pantheon_model`), hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 3 ferramentas (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos, session hooks (`prompt`, `context`), um hook de ferramenta `execute.before` que impõe sessões somente-leitura, além de transforms de configuração |
+| Registro Pantheon | `src/plugin.ts` mais `src/plugins/pantheon-hooks.ts` | pacote npm `pantheon-opencode@<versão>` fixado à versão instalada (export raiz aponta para `src/plugin-v2.ts`) |
+| Contrato de runtime | Plugin Pantheon V1: 6 ferramentas (`hashline_edit`, as 3 ferramentas de goal, `pantheon_cost`, `pantheon_model`), hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2: 3 ferramentas (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 5 assinaturas de eventos, session hooks (`prompt`, `context`), hooks de execução/permissão e transforms de configuração |
 | APIs V1 | Registradas | Definições próprias de ferramentas via `ctx.tool.transform()` — não pelo caminho do plugin V1 |
 
 O plugin V2 fornece 3 ferramentas de orquestração (`hashline_edit`,
-`pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos (`session.created`,
-`session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
+`pantheon_cost`, `pantheon_model`), 5 assinaturas de eventos (`session.created`,
+`session.idle`, `session.deleted`, `session.error`, `session.compacted`), session hooks (`prompt`,
 `context`) e um hook de ferramenta `execute.before` que impõe sessões
 somente-leitura. As 3 ferramentas de goal **não** são
 registradas no V2: o goal loop precisa de um `GoalStore`, de um
@@ -141,10 +156,16 @@ dessa superfície: o host inclui o agente ativo no evento, um agente somente-lei
 compartilhado lança para negar `edit`, `write`, `bash`, `task`,
 `hashline_edit` e `pantheon_model`. Ele **não** depende do hook
 `tool.execute.before` do V1, que vive em `src/plugin.ts` e não é carregado
-quando apenas `plugin-v2` está configurado. Os hooks companheiros
-`execute.after` e `permission.evaluate` são pontos de registro sem comportamento
-do lado V2, e a matriz de delegação caller/target da V1 para o `task()` nativo
-não é imposta no V2.
+quando apenas `plugin-v2` está configurado. O hook `permission.evaluate`
+aplica no V2 a matriz caller/target para destinos gerenciados pelo Pantheon,
+considerando todos os itens do array `resources` do host. Recursos
+exclusivamente nativos são repassados sem alteração à política de permissões do
+OpenCode; pedidos mistos (nativos/Pantheon) e com vários destinos são negados,
+a menos que todos os destinos Pantheon sejam explicitamente permitidos para o
+chamador autoritativo. Uma negação explícita do host é final, e dados de
+recursos ausentes ou desconhecidos são negados por padrão. O `execute.after` do
+V2 executa a cadeia de resultados concluídos `task-result-guard` →
+`context-sandbox` → `read-enhancer`; eventos de erro permanecem inalterados.
 
 Toda ferramenta V2 declara um schema `output`. O OpenCode 2.0.x exige que a
 declaração e o resultado resolvido concordem nos dois sentidos, então uma
@@ -153,15 +174,18 @@ toda chamada. Os recursos V2 sem suporte são `legacy-hooks` (a superfície de
 hooks específica do V1), `catalog-transform`, `integration-transform`,
 `skill-transform` e `goal-tools`.
 
-O pacote expõe os dois contratos como exports importáveis:
-`pantheon-opencode/plugin` (V1), `pantheon-opencode/plugin-v2` (V2) e
-`pantheon-opencode/v2-bridge` (interop opcional), para que o host carregue
-explicitamente o contrato desejado.
+Ao migrar uma config V1 com `init --opencode-version v2`, o instalador traduz
+`task` para a ação V2 `subagent` e `write` para `edit` (que também cobre as
+tools host `write`/`patch`). Se regras legadas `edit` e `write` colidirem no
+mesmo recurso, a migração preserva o efeito mais restritivo. Configs V2
+editadas manualmente devem usar o array nativo `permissions` com
+`action`/`resource`/`effect`.
 
-A ponte V1→V2 (`src/pantheon/v2-bridge.ts`) habilita interop opcional:
-singletons de infraestrutura V1 (BackgroundJobBoard,
-GoalStore, TodoEnforcer, VisionHandler) são repassados via `ctx.options` do V2.
-A ponte é opcional — o V2 funciona standalone com degradação graciosa.
+O pacote expõe os dois contratos: a raiz e `pantheon-opencode/plugin-v2`
+carregam V2; `pantheon-opencode/plugin` carrega V1. `pantheon-opencode/v2-bridge`
+é atualmente apenas uma utility importável: o setup de produção não a conecta
+ao plugin V2, então ela não fornece interoperabilidade em runtime nem restaura
+as ferramentas de goal/board do V1.
 
 Selecione o contrato explicitamente na instalação:
 
@@ -238,8 +262,8 @@ pontos. A ordem das chaves não muda o resultado.
 Um comando mantém uma instalação existente em dia:
 
 ```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):
+# Sem instalação global, fixe o dist-tag desejado. `latest` aponta para a
+# release estável publicada mais recente, não para um candidato não publicado:
 npx pantheon-opencode@beta update            # canal beta do npm + refresh do config
 npx pantheon-opencode@beta update --stable   # canal estável