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

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)
 
@@ -70,13 +70,14 @@ 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.
 
 
-## What's new in 1.5.0
+## 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 +91,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 +154,21 @@ 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
+## Releases
 
-A pull request labeled exactly `release:beta` triggers the beta release path. See [docs/RELEASING.md](docs/RELEASING.md) for validation and recovery details.
+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 +177,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 +193,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 +209,15 @@ 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.
+
 ## Documentation
 
 - [Installation](docs/INSTALLATION.md) · [Quick start](docs/QUICKSTART.md)
@@ -207,9 +235,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,14 @@ 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
+## 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 +94,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 é
@@ -153,9 +154,21 @@ 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
+## Releases
 
-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.
+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 +178,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 +194,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 +211,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 +237,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>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.5.0-beta.1",
+  "version": "1.5.0-beta.3",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "publishConfig": {
@@ -28,7 +28,9 @@
     "version:status": "node scripts/versioning.mjs status",
     "version:apply": "node scripts/versioning.mjs apply",
     "version:check": "node scripts/version-check.mjs",
-    "release:dry-run": "node scripts/versioning.mjs status && node scripts/release-notes.mjs && npm pack --dry-run",
+    "release:dry-run": "node scripts/versioning.mjs status && node scripts/release-notes.mjs && node scripts/package-evidence.mjs",
+    "package:evidence": "node scripts/package-evidence.mjs",
+    "package:validate": "node scripts/validate-package.mjs",
     "publish:next": "npm publish --tag next --access public",
     "lint": "npx biome ci .",
     "typecheck": "npx tsc --noEmit",
@@ -47,7 +49,9 @@
   },
   "files": [
     "LICENSE",
+    "package-lock.json",
     "plugin.json",
+    "pyproject.toml",
     "scripts/install/*.mjs",
     "scripts/*.py",
     "src/plugin.ts",
@@ -84,7 +88,7 @@
   ],
   "dependencies": {
     "@opencode-ai/plugin": "1.18.18",
-    "js-yaml": "^4.3.0",
+    "js-yaml": "^4.3.2",
     "zod": "4.1.8"
   },
   "devDependencies": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon",
   "publisher": "ils15",
-  "version": "1.5.0-beta.1",
+  "version": "1.5.0-beta.3",
   "displayName": "Pantheon",
   "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 21 skills, and OpenCode support.",
   "agents": "./src/agents",

package/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.backends._legacy:_Backend"
+
+[project]
+name = "pantheon"
+version = "1.5.0-beta.3"
+description = "Multi-agent orchestration framework"
+requires-python = ">=3.11"
+dependencies = []
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-v --tb=short"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "PL", "RUF", "C901"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+# Legacy command-line scripts intentionally use hyphenated filenames.
+"scripts/ci-validate-yaml.py" = ["N999"]
+"scripts/scrub-secrets.py" = ["N999"]
+# These modules defer optional/heavy imports until the corresponding command is used.
+"scripts/vector_memory/*.py" = ["PLC0415"]
+"tests/test_code_mode_args.py" = ["PLC0415"]
+"tests/test_code_mode_sandbox.py" = ["PLC0415", "N806"]
+"tests/test_code_mode_server.py" = ["PLC0415"]
+"tests/test_eval_store.py" = ["PLC0415", "PLR2004"]
+"tests/test_memory_mcp_server.py" = ["PLC0415", "PLR2004"]
+# Existing public APIs and test fixtures are intentionally broad/simple; refactoring
+# them would be behavior-affecting rather than a mechanical lint correction.
+"scripts/code_mode_server.py" = ["PLR0913"]
+"src/mcp/code_mode_server.py" = ["PLR0913"]
+"scripts/mcp_persistence_server.py" = ["PLR0913"]
+"src/mcp/mcp_persistence_server.py" = ["PLR0913"]
+"scripts/memory_mcp_server.py" = ["C901"]
+"scripts/vector_memory/index.py" = ["C901", "PLR0913", "PLR2004", "PLW0603", "PLW2901"]
+"scripts/vector_memory/cli.py" = ["PLR2004"]
+"scripts/vector_memory/query.py" = ["PLR0913"]
+"src/mcp/eval_store.py" = ["PLR2004"]
+"tests/test_code_mode_frontmatter.py" = ["PLR2004"]
+"tests/test_eval_judge.py" = ["PLR2004"]
+"tests/test_eval_static.py" = ["PLR2004"]
+"tests/test_mcp_persistence_server.py" = ["PLR2004"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+disallow_untyped_defs = true

package/scripts/code_mode_server.py

@@ -41,18 +41,20 @@ MAX_SCRIPT_TIMEOUT: int = 300
 # ── Env Allowlist ──────────────────────────────────────────────────────────────
 # Only these variables are passed to script subprocesses.  Everything else
 # (secrets, cloud credentials, etc.) is stripped to limit blast radius.
-_CODE_MODE_ENV_ALLOWLIST: frozenset[str] = frozenset({
-    "PATH",
-    "HOME",
-    "LANG",
-    "PANTHEON_HOME",
-    "PANTHEON_PROJECT",
-    "OPENAI_API_KEY",
-    "OPENAI_BASE_URL",
-    "EVAL_JUDGE_MODEL",
-    "SHELL",
-    "USER",
-})
+_CODE_MODE_ENV_ALLOWLIST: frozenset[str] = frozenset(
+    {
+        "PATH",
+        "HOME",
+        "LANG",
+        "PANTHEON_HOME",
+        "PANTHEON_PROJECT",
+        "OPENAI_API_KEY",
+        "OPENAI_BASE_URL",
+        "EVAL_JUDGE_MODEL",
+        "SHELL",
+        "USER",
+    }
+)
 
 # Optional extra vars that callers may opt-in to pass through.  Populate
 # this set at startup if needed (e.g. ``CODE_MODE_EXTRA_ENV.add("MY_VAR")``).
@@ -127,6 +129,7 @@ def _detect_prlimit() -> str | None:
         return None
     return shutil.which("prlimit")
 
+
 # ── Scripts Directory Resolution ─────────────────────────────────────────────
 # Priority:
 # 1. /.opencode/.pantheon/code-mode/  (project install)
@@ -136,6 +139,49 @@ def _detect_prlimit() -> str | None:
 #    fallback — package.json `files` includes .pantheon/code-mode/**)
 
 
+def _is_within(path: Path, root: Path) -> bool:
+    """Return whether a resolved *path* is contained by a resolved *root*."""
+    try:
+        return os.path.commonpath((str(root), str(path))) == str(root)
+    except (OSError, ValueError):
+        return False
+
+
+def _has_usable_scripts(scripts_dir: Path) -> bool:
+    """Return whether *scripts_dir* contains an executable code-mode target.
+
+    A directory is only a valid resolver candidate when it contains a regular
+    ``.py`` or ``.sh`` file that can pass the same direct-child and path
+    containment rules used by script execution.  This prevents an empty
+    project overlay (or a directory containing only metadata) from masking a
+    lower-priority installation.
+    """
+    try:
+        if scripts_dir.is_symlink():
+            return False
+        resolved_dir = scripts_dir.resolve(strict=True)
+        if not resolved_dir.is_dir():
+            return False
+        for script_path in scripts_dir.iterdir():
+            if script_path.name.startswith("."):
+                continue
+            if script_path.suffix.lower() not in ALLOWED_EXTENSIONS:
+                continue
+            try:
+                resolved_script = script_path.resolve(strict=True)
+            except (OSError, RuntimeError):
+                continue
+            if (
+                resolved_script.is_file()
+                and resolved_script.parent == resolved_dir
+                and _is_within(resolved_script, resolved_dir)
+            ):
+                return True
+    except (OSError, RuntimeError):
+        return False
+    return False
+
+
 def _packaged_scripts_dir() -> Path | None:
     """Return the code-mode dir shipped inside the installed package, if any.
 
@@ -144,22 +190,27 @@ def _packaged_scripts_dir() -> Path | None:
     Returns None when no packaged copy exists.
     """
     try:
-        here = Path(__file__).resolve()
-    except Exception:
+        here = Path(__file__).resolve(strict=True)
+    except (OSError, RuntimeError):
         return None
     for parent in [here.parent, *here.parents]:
         try:
             candidate = parent / ".pantheon" / "code-mode"
         except Exception:
             continue
-        try:
-            if candidate.is_dir():
-                return candidate
-        except OSError:
-            continue
+        if _has_usable_scripts(candidate):
+            return candidate
     return None
 
 
+def _resolve_scripts_dir(candidates: list[Path]) -> Path | None:
+    """Select the first usable candidate, then try the packaged fallback."""
+    for candidate in candidates:
+        if _has_usable_scripts(candidate):
+            return candidate
+    return _packaged_scripts_dir()
+
+
 _PANTHEON_HOME: Path = pantheon_home()
 _SCRIPTS_DIR_CANDIDATES: list[Path] = []
 _proj = pantheon_project()
@@ -168,15 +219,9 @@ if _proj is not None:
     _SCRIPTS_DIR_CANDIDATES.append(_proj / ".pantheon" / "code-mode")
 _SCRIPTS_DIR_CANDIDATES.append(_PANTHEON_HOME / ".pantheon" / "code-mode")
 
-SCRIPTS_DIR: Path = _PANTHEON_HOME / ".pantheon" / "code-mode"  # default
-for _candidate in _SCRIPTS_DIR_CANDIDATES:
-    if _candidate.is_dir():
-        SCRIPTS_DIR = _candidate
-        break
-else:
-    _packaged = _packaged_scripts_dir()
-    if _packaged is not None:
-        SCRIPTS_DIR = _packaged
+SCRIPTS_DIR: Path = _resolve_scripts_dir(_SCRIPTS_DIR_CANDIDATES) or (
+    _PANTHEON_HOME / ".pantheon" / "code-mode"
+)
 
 # ── FastMCP App ───────────────────────────────────────────────────────────────
 mcp = FastMCP(
@@ -208,11 +253,21 @@ def _validate_script_name(script_name: str) -> Path:
         allowed = ", ".join(sorted(ALLOWED_EXTENSIONS))
         raise ValueError(f"Extension '{ext}' not allowed. Allowed: {allowed}")
 
-    script_path = (SCRIPTS_DIR / name).resolve()
-    if not str(script_path).startswith(str(SCRIPTS_DIR.resolve())):
+    if SCRIPTS_DIR.is_symlink():
+        raise ValueError(f"Invalid script name: '{script_name}'")
+
+    try:
+        scripts_root = SCRIPTS_DIR.resolve(strict=True)
+        script_path = (SCRIPTS_DIR / name).resolve(strict=True)
+    except (FileNotFoundError, OSError, RuntimeError):
+        raise ValueError(f"Script '{script_name}' not found") from None
+
+    if (
+        not _is_within(script_path, scripts_root)
+        or script_path.parent != scripts_root
+        or not script_path.is_file()
+    ):
         raise ValueError(f"Invalid script name: '{script_name}'")
-    if not script_path.exists():
-        raise ValueError(f"Script '{script_name}' not found")
 
     return script_path
 
@@ -286,7 +341,9 @@ def _parse_frontmatter(script_path: Path) -> dict[str, Any]:
             break
         if not stripped.startswith("#"):
             return {}  # non-comment line inside the block → not frontmatter
-        body_lines.append(stripped[1:].lstrip() if stripped.startswith("# ") else stripped[1:])
+        body_lines.append(
+            stripped[1:].lstrip() if stripped.startswith("# ") else stripped[1:]
+        )
     else:
         return {}  # no closing delimiter
 
@@ -378,7 +435,9 @@ async def list_code_mode_scripts() -> str:
 
 @mcp.resource(
     "pantheon://code-mode/scripts/{script_name}",
-    description="Content of a code-mode script by name, with parsed frontmatter metadata",
+    description=(
+        "Content of a code-mode script by name, with parsed frontmatter metadata"
+    ),
 )
 async def get_code_mode_script(script_name: str) -> str:
     """Return the source content of a code-mode script plus its metadata."""
@@ -486,8 +545,14 @@ async def execute_code_script(
             await proc.wait()
             duration_ms = int((time.monotonic() - started) * 1000)
             return _build_result(
-                "", "", -1, timed_out=True, duration_ms=duration_ms,
-                metadata=metadata, json_output=json_output, timeout_s=timeout_s,
+                "",
+                "",
+                -1,
+                timed_out=True,
+                duration_ms=duration_ms,
+                metadata=metadata,
+                json_output=json_output,
+                timeout_s=timeout_s,
             )
     except FileNotFoundError:
         return _build_result(

package/scripts/cost.mjs

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 /**
- * cost.mjs — read-only cost aggregation from opencode.db (Wave 4, PR #46).
+ * cost.mjs — read-only token aggregation from opencode.db.
  *
- * Fallback for the `pantheon_cost` tool when node:sqlite is unavailable in
- * the plugin process (node < 22.5). Uses node:sqlite itself and prints a
- * single JSON object to stdout:
- *   { ok: true,  days, rows: [{agent, costUsd, tokensInput, tokensOutput}] }
+ * CLI fallback for the `pantheon_cost` tool when node:sqlite is unavailable
+ * in the plugin process. Uses node:sqlite itself and prints a single JSON
+ * object to stdout:
+ *   { ok: true, days, rows: [{agent, phase, tokensInput, tokensOutput, tokensTotal}] }
  *   { ok: false, error: "<message>" }          (exit code 1)
  *
  * NEVER writes to the database — opened read-only. Malformed rows are
- * skipped; assistant messages carry the authoritative cost + tokens.
+ * skipped; assistant messages carry the authoritative token usage.
  *
- * Usage: node scripts/cost.mjs <dbPath> <days>
+ * Usage: node scripts/cost.mjs --db-path <dbPath> --days <days>
  */
 import { existsSync } from 'node:fs'
 import { DatabaseSync } from 'node:sqlite'
@@ -43,8 +43,13 @@ function assertCompatibleSchema(db) {
 }
 
 function main() {
-  const [, , dbPath, daysArg] = process.argv
-  const days = Number(daysArg ?? '7')
+  const argv = process.argv.slice(2)
+  const valueFor = (name) => {
+    const index = argv.indexOf(name)
+    return index >= 0 ? argv[index + 1] : undefined
+  }
+  const dbPath = valueFor('--db-path')
+  const days = Number(valueFor('--days') ?? '7')
 
   if (!dbPath) return fail('missing <dbPath> argument')
   if (!existsSync(dbPath)) return fail(`database not found: ${dbPath}`)
@@ -64,19 +69,30 @@ function main() {
         if (info.role !== 'assistant') continue
         const agent = typeof info.agent === 'string' && info.agent !== '' ? info.agent : null
         if (!agent) continue
-        const costUsd = Number(info.cost) || 0
+        const metadata = info.metadata
+        const phase =
+          (typeof info.phase === 'string' && info.phase) ||
+          (typeof metadata?.phase === 'string' && metadata.phase) ||
+          'unknown'
         const tokensInput = Number(info.tokens?.input) || 0
         const tokensOutput = Number(info.tokens?.output) || 0
-        const acc = byAgent.get(agent) ?? { agent, costUsd: 0, tokensInput: 0, tokensOutput: 0 }
-        acc.costUsd += costUsd
+        const key = `${agent}\u0000${phase}`
+        const acc = byAgent.get(key) ?? {
+          agent,
+          phase,
+          tokensInput: 0,
+          tokensOutput: 0,
+          tokensTotal: 0,
+        }
         acc.tokensInput += tokensInput
         acc.tokensOutput += tokensOutput
-        byAgent.set(agent, acc)
+        acc.tokensTotal += tokensInput + tokensOutput
+        byAgent.set(key, acc)
       } catch {
         // Skip malformed rows — a partial ledger never breaks the report.
       }
     }
-    const result = [...byAgent.values()].sort((a, b) => b.costUsd - a.costUsd)
+    const result = [...byAgent.values()].sort((a, b) => b.tokensTotal - a.tokensTotal)
     process.stdout.write(JSON.stringify({ ok: true, days, rows: result }))
   } catch (err) {
     fail(err instanceof Error ? err.message : String(err))

package/scripts/install/opencode.mjs

@@ -1207,4 +1207,10 @@ export async function installOpenCode(
     const { writeActivePreset } = await import('./model-picker.mjs')
     writeActivePreset(target, opts.preset, { source: 'cli' })
   }
+
+  // Fail-closed: accumulated stats.errors (bad sources, missing requirements,
+  // failed health checks) must never masquerade as a successful installation.
+  if (stats.errors > 0) {
+    throw new Error(`installation completed with ${stats.errors} error(s); see output above`)
+  }
 }