pantheon-opencode 1.4.3 → 1.5.0-beta.2

package/README.pt-BR.md

@@ -0,0 +1,222 @@
+# Pantheon
+
+**Uma forma mais clara de trabalhar com OpenCode em projetos reais.** O
+Pantheon reúne planejamento, implementação, revisão e documentação em uma
+experiência guiada. É um plugin e instalador para OpenCode, feito para pessoas
+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)
+[![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)
+
+## O que é?
+
+O Pantheon é um companheiro para o [OpenCode](https://opencode.ai/) que ajuda a
+transformar uma ideia em uma alteração revisada. Ele oferece uma forma comum
+de planejar o trabalho, avançar, conferir resultados e preservar o contexto
+útil do projeto.
+
+## Por que usar?
+
+- **Menos troca de contexto:** planeje e construa no mesmo fluxo.
+- **Alterações mais conscientes:** peça revisões e verificações antes de
+  considerar o trabalho concluído.
+- **Um ponto de partida repetível:** use a mesma configuração em projetos e
+  com colaboradores diferentes.
+- **Você continua no comando:** o Pantheon apoia suas decisões, mas não
+  substitui seu julgamento nem a revisão do código gerado.
+
+## Comece em 2 minutos
+
+Requisitos: [OpenCode 1.18.4+](https://opencode.ai/docs/) e Node.js 18+.
+
+No projeto em que você quer usar o Pantheon:
+
+```bash
+npx pantheon-opencode init
+opencode
+```
+
+O instalador orienta você pelas opções disponíveis. Para servidores MCP
+opcionais, instalação local no projeto ou uso sem perguntas, consulte o
+[guia de instalação](docs/INSTALLATION.md).
+
+## Um exemplo simples
+
+Com o OpenCode em execução, descreva o resultado que você quer:
+
+```text
+/pantheon Adicione exportação CSV à página de relatórios, com testes e revisão.
+```
+
+O Pantheon ajuda a transformar esse pedido em um plano e em etapas revisadas.
+
+## Para quem é?
+
+Para desenvolvedores, mantenedores e equipes que usam OpenCode e querem uma
+forma mais consistente de lidar com correções pequenas e mudanças maiores. É
+especialmente útil quando o projeto se beneficia de decisões registradas,
+verificações repetíveis e passagens claras entre etapas do trabalho.
+
+## O que inclui?
+
+- Um instalador guiado para disponibilizar o Pantheon no OpenCode.
+- Instruções e comandos reutilizáveis para planejar, construir, revisar e
+  documentar o trabalho.
+- Memória de projeto para preservar contexto relevante entre sessões.
+- Integrações opcionais para tarefas comuns de desenvolvimento.
+
+## Status
+
+Versão atual: **v1.5.0**. 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.
+
+
+## Novidades da 1.5.0
+
+- Instalador exclusivo para OpenCode: guias de plataformas consolidados em um
+  único [guia OpenCode](docs/platforms/opencode.md).
+- Novo CLI `uninstall` com escopos project/global e checagem de ownership:
+  `node scripts/uninstall.mjs --project|--global [--dry-run] [--force]`.
+- Recursos MCP endurecidos: correção do `pantheon://agents` e proteção contra
+  symlink/traversal nos caminhos de recursos.
+- Compatibilidade com OpenCode V2: merge de configuração `plugins` /
+  `mcp.servers.enabled` e launch stdio MCP com PWD correto.
+- `doctor` e health checks de instalação expandidos.
+- Validador de sandbox para instalações globais
+  (`scripts/test-opencode-v1-v2-sandbox.sh`) cobrindo OpenCode V1/V2 lado a
+  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)
+
+O Pantheon tem dois contratos de plugin OpenCode **exclusivos**. A configuração
+comum do OpenCode pode ser compartilhada, mas o registro do plugin Pantheon é
+selecionado por instalação; os plugins Pantheon V1 e V2 nunca devem ser
+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 legado, incluindo `pantheon_delegate`, ferramentas read/list, hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 9 ferramentas de orquestração, 4 assinaturas de eventos, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), além de 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 9 ferramentas de orquestração (`pantheon_delegate`,
+`pantheon_delegation_read`, `pantheon_delegation_list`, `hashline_edit`,
+`pantheon_goal_create`, `pantheon_goal_get`, `pantheon_goal_update`,
+`pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos (`session.created`,
+`session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
+`context`) e tool hooks (`execute.before`, `execute.after`). O único recurso V2
+sem suporte é `legacy-hooks` (a superfície de API de delegate específica do V1).
+
+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.
+
+A ponte V1→V2 (`src/pantheon/v2-bridge.ts`) habilita interop opcional:
+singletons de infraestrutura V1 (BackgroundJobBoard, DelegationClient,
+GoalStore, TodoEnforcer, VisionHandler) são repassados via `ctx.options` do V2.
+A ponte é opcional — o V2 funciona standalone com degradação graciosa.
+
+Selecione o contrato explicitamente na instalação:
+
+```bash
+npx pantheon-opencode init --opencode-version v1
+npx pantheon-opencode init --opencode-version v2
+npx pantheon-opencode init --opencode-version auto
+```
+
+`--version v1|v2|auto` é aceito como a grafia antiga do seletor quando usado
+depois de `init`. `auto` é conservador, não uma autodetecção geral de
+plataforma: `OPENCODE_VERSION=v1|v2` vence; caso contrário, um `OPENCODE_BIN`
+terminando em `opencode2` seleciona V2; qualquer outro caso seleciona V1. O
+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
+`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
+ferramenta tem precedência sobre ambos. O resolver nunca consulta o banco da
+outra versão e reporta um erro acionável quando o banco selecionado está
+ausente ou com schema incompatível.
+
+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
+
+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.
+
+## Validação em sandbox (V1/V2)
+
+O `scripts/test-opencode-v1-v2-sandbox.sh` valida o pacote instalado
+globalmente como um usuário real dentro de um sandbox isolado (com `HOME`,
+prefix npm e venv próprios) — nunca o ambiente de desenvolvimento. Ele verifica
+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.
+
+```bash
+scripts/test-opencode-v1-v2-sandbox.sh --prepare          # tarball + install + init no sandbox
+scripts/test-opencode-v1-v2-sandbox.sh --run v1 --prompts # validação base + bateria de prompts (V1)
+scripts/test-opencode-v1-v2-sandbox.sh --run v2           # apenas validação base (V2)
+scripts/test-opencode-v1-v2-sandbox.sh --prompts          # bateria de prompts para as duas versões
+scripts/test-opencode-v1-v2-sandbox.sh --reset            # limpa a raiz do sandbox
+```
+
+Os modos são combináveis (ex.: `--prepare --run v1 --prompts`). Os binários são
+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.
+
+Variáveis de ambiente:
+
+| Variável | Padrão | Finalidade |
+|----------|---------|---------|
+| `PANTHEON_SANDBOX_ROOT` | `~/pantheon-sandbox` | Raiz do sandbox (recusada se insegura para `--reset`) |
+| `OPENCODE_V1_SPEC` | `opencode-ai@1.18.18` | Spec npm que fornece o binário `opencode` |
+| `OPENCODE_V2_SPEC` | `@opencode-ai/cli@beta` | Spec npm que fornece o binário `opencode2` |
+| `PANTHEON_SANDBOX_MODEL` | `opencode-go/mimo-v2.5` | Modelo usado pelo init e pelos prompts |
+| `PANTHEON_PROMPT_TIMEOUT` | `300` | Timeout por prompt em segundos |
+
+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.
+
+## Documentação
+
+- [Instalação](docs/INSTALLATION.md) · [Início rápido](docs/QUICKSTART.md)
+- [Arquitetura](docs/ARCHITECTURE.md) · [Ferramentas MCP](docs/mcp-tools.md)
+- [Plataformas](docs/PLATFORMS.md) · [Atualização](docs/UPGRADING.pt-BR.md)
+- [Referência de agentes](docs/agents/README.md) · [Referência de skills](src/skills/README.md)
+- [Processo de release](docs/RELEASING.md) · [Contribuição](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+## Contribua
+
+Ideias, relatos de problemas, melhorias na documentação e contribuições de
+código são bem-vindos. Leia [CONTRIBUTING.md](CONTRIBUTING.md) antes de abrir
+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).
+
+Repositório canônico: <https://github.com/ils15/pantheon-opencode>
+
+---
+
+[Read in English](README.md)

package/bin/pantheon-init.mjs

@@ -14,10 +14,10 @@
  * install for the operator; state isolation is a runtime concern
  * (OPENCODE_DB ~/.local/share/opencode/opencode-v2.db, service port 49375).
  */
-import fs from 'fs'
-import os from 'os'
-import path from 'path'
-import { fileURLToPath } from 'url'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const ROOT = path.resolve(__dirname, '..')
@@ -50,7 +50,7 @@ function printUsage() {
   console.log('  npx pantheon-opencode init --interactive  # Force interactive TUI mode')
   console.log('  npx pantheon-opencode init --headless     # Force non-interactive mode')
   console.log('  npx pantheon-opencode init -y             # Skip confirmations, use defaults')
-  console.log('  npx pantheon-opencode init --version v2    # Label install for OpenCode V2 (beta)')
+  console.log('  npx pantheon-opencode init --opencode-version v1|v2|auto')
   console.log('  npx pantheon-opencode init --preset <name> # Install and activate model preset')
   console.log('  npx pantheon-opencode set-tier <name>      # Set active model preset (global)')
   console.log(
@@ -59,6 +59,8 @@ function printUsage() {
   console.log('  npx pantheon-opencode prune               # List legacy artifacts (dry-run)')
   console.log('  npx pantheon-opencode prune --apply       # Remove stale backups')
   console.log('  npx pantheon-opencode doctor [--profile]  # Run health check')
+  console.log('  npx pantheon-opencode uninstall --project   # Remove project artifacts safely')
+  console.log('  npx pantheon-opencode uninstall --global    # Remove global artifacts safely')
   console.log('  npx pantheon-opencode --version, -v       # Print version and exit')
   console.log('  npx pantheon-opencode --help              # Show this help')
 }
@@ -78,11 +80,21 @@ async function main() {
   // prune handles its own --help (delegated to scripts/prune.mjs), so its
   // dispatch must run BEFORE the generic --help check.
   if (command === 'prune') {
-    const { spawnSync } = await import('child_process')
+    const { spawnSync } = await import('node:child_process')
     const pruneScript = path.join(ROOT, 'scripts', 'prune.mjs')
     const result = spawnSync(process.execPath, [pruneScript, ...args.slice(1)], {
       stdio: 'inherit',
-      cwd: ROOT,
+      cwd: process.cwd(),
+    })
+    process.exit(result.status ?? 1)
+  }
+
+  if (command === 'uninstall') {
+    const { spawnSync } = await import('node:child_process')
+    const uninstallScript = path.join(ROOT, 'scripts', 'uninstall.mjs')
+    const result = spawnSync(process.execPath, [uninstallScript, ...args.slice(1)], {
+      stdio: 'inherit',
+      cwd: process.cwd(),
     })
     process.exit(result.status ?? 1)
   }
@@ -91,7 +103,7 @@ async function main() {
   // Forwarding the FULL args (profile, target, --fix, ...) keeps the packaged
   // CLI a thin wrapper; the doctor banner reports the resolved profile.
   if (command === 'doctor') {
-    const { spawnSync } = await import('child_process')
+    const { spawnSync } = await import('node:child_process')
     const doctorScript = path.join(ROOT, 'scripts', 'doctor.mjs')
     const result = spawnSync(process.execPath, [doctorScript, ...args.slice(1)], {
       stdio: 'inherit',
@@ -198,7 +210,14 @@ async function main() {
     // --version v1|v2 labels the install target (informational; the config is
     // shared and V1-shaped under both versions). Invalid values fail fast.
     const versionIndex = args.indexOf('--version')
-    const versionOpt = versionIndex >= 0 ? (args[versionIndex + 1] ?? null) : null
+    const legacyVersionIndex = args.indexOf('--opencode-version')
+    const inlineVersion = args.find((arg) => arg.startsWith('--opencode-version='))
+    const versionOpt =
+      versionIndex >= 0
+        ? (args[versionIndex + 1] ?? null)
+        : legacyVersionIndex >= 0
+          ? (args[legacyVersionIndex + 1] ?? null)
+          : (inlineVersion?.split('=', 2)[1] ?? null)
     if (versionOpt !== null && versionOpt !== 'v1' && versionOpt !== 'v2') {
       console.error(`❌ Invalid --version "${versionOpt}" — expected v1 or v2`)
       process.exit(1)
@@ -239,7 +258,7 @@ async function main() {
       console.log('')
       console.log('  Running health check...')
       try {
-        const { spawnSync } = await import('child_process')
+        const { spawnSync } = await import('node:child_process')
         const doctorScript = path.join(ROOT, 'scripts', 'doctor.mjs')
         spawnSync(process.execPath, [doctorScript], { stdio: 'inherit', cwd: ROOT })
       } catch {
@@ -255,7 +274,7 @@ async function main() {
     console.log('  Next steps:')
     console.log('  1. Verify installation:')
     console.log('     npx pantheon-opencode doctor')
-    console.log('  2. Launch your AI coding tool (OpenCode, Claude Code, Cursor, etc.)')
+    console.log('  2. Launch OpenCode')
     console.log('  3. Invoke agents with @agent-name in chat')
     console.log('  4. For project-local install:')
     console.log('     npx pantheon-opencode init --project')

package/opencode.json

@@ -11,6 +11,7 @@
     }
   },
   "default_agent": "zeus",
+  "plugins": ["src/plugin-v2"],
   "experimental": {
     "subagent_depth": 2
   },

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.4.3",
+  "version": "1.5.0-beta.2",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
+  "type": "module",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "exports": {
+    "./plugin": "./src/plugin.ts",
+    "./plugin-v2": "./src/plugin-v2.ts",
+    "./v2-bridge": "./src/pantheon/v2-bridge.ts"
+  },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs && node scripts/sync-tui.mjs",
     "prepare": "husky",
@@ -32,7 +38,7 @@
     "hooks:update": "pre-commit autoupdate",
     "test:security": "npm run secret-scan && node tests/test_install_mcp_vision.mjs && node tests/test_doctor_layers.mjs",
     "test:node": "node --test tests/*.mjs tests/pantheon/*.mjs",
-    "test:ts": "for f in tests/pantheon/*.test.ts; do npx tsx \"$f\" || exit 1; done",
+    "test:ts": "for f in tests/pantheon/*.test.ts; do if [ \"$f\" = tests/pantheon/plugin-v2-contract.test.ts ]; then NODE_OPTIONS=--conditions=import npx tsx \"$f\"; else npx tsx \"$f\"; fi || exit 1; done",
     "test": "python3 -m pytest tests/ -q 2>&1; status=$?; if [ \"$status\" -eq 5 ]; then echo \"No tests found\"; fi; exit \"$status\"",
     "test:ci": "python3 -m pytest tests/ -q --tb=short 2>&1"
   },
@@ -41,9 +47,13 @@
   },
   "files": [
     "LICENSE",
+    "plugin.json",
     "scripts/install/*.mjs",
     "scripts/*.py",
     "src/plugin.ts",
+    "src/plugin-v2.ts",
+    "src/plugin-v2",
+    "src/pantheon/v2-bridge.ts",
     "README.md",
     "src/mcp/*.txt",
     "commands/*.md",
@@ -62,6 +72,7 @@
     "src/mcp/*.sh",
     "src/routing.yml",
     "src/pantheon/**",
+    ".pantheon/code-mode/**",
     "src/plugins/**",
     "scripts/hooks/**",
     "src/mcp/requirements*",
@@ -72,13 +83,13 @@
     "!**/*.pyc"
   ],
   "dependencies": {
+    "@opencode-ai/plugin": "1.18.18",
     "js-yaml": "^4.3.0",
     "zod": "4.1.8"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.8.0",
     "@commitlint/config-conventional": "^19.8.0",
-    "@opencode-ai/plugin": "1.18.11",
     "husky": "^9.1.7"
   },
   "repository": {

package/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "pantheon",
+  "publisher": "ils15",
+  "version": "1.5.0",
+  "displayName": "Pantheon",
+  "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 21 skills, and OpenCode support.",
+  "agents": "./src/agents",
+  "skills": "./src/skills",
+  "instructions": "./src/instructions",
+  "prompts": "./prompts",
+  "repository": "https://github.com/ils15/pantheon-opencode",
+  "exports": {
+    ".": "./src/routing.yml"
+  }
+}

package/scripts/_pantheon_paths.py

@@ -34,11 +34,11 @@ def pantheon_home() -> Path:
     """
     env = os.environ.get("PANTHEON_HOME")
     if env:
-        return Path(env).expanduser().resolve()
+        return Path(env).expanduser().absolute()
 
     xdg = os.environ.get("XDG_CONFIG_HOME")
     if xdg:
-        return Path(xdg).expanduser().resolve() / "opencode"
+        return Path(xdg).expanduser().absolute() / "opencode"
 
     return Path.home() / ".config" / "opencode"
 
@@ -48,7 +48,8 @@ def pantheon_project() -> Path | None:
 
     Resolution priority:
     1. $PANTHEON_PROJECT env var (explicit override)
-    2. Current working directory (set by MCP client's cwd in opencode.json)
+    2. The validated logical ``$PWD`` supplied by the launcher
+    3. Current working directory (set by MCP client's cwd in opencode.json)
 
     Returns:
         Absolute Path to the project root, or None if neither is available
@@ -56,10 +57,50 @@ def pantheon_project() -> Path | None:
     """
     env = os.environ.get("PANTHEON_PROJECT")
     if env:
-        return Path(env).expanduser().resolve()
-
-    cwd = os.getcwd()
+        return Path(env).expanduser().absolute()
+
+    logical_cwd = os.environ.get("PWD")
+    try:
+        cwd = os.getcwd()
+    except OSError:
+        cwd = ""
+    if logical_cwd and _is_valid_logical_cwd(logical_cwd, cwd):
+        return Path(logical_cwd).expanduser().absolute()
     if cwd:
-        return Path(cwd).resolve()
+        return Path(cwd).absolute()
 
     return None
+
+
+def _is_valid_logical_cwd(logical_cwd: str, physical_cwd: str) -> bool:
+    """Validate a launcher-provided logical cwd without resolving its result.
+
+    ``PWD`` is trusted only when it is an existing directory naming the same
+    inode as the process cwd.  This preserves symlink spelling while rejecting
+    forged or stale environment values.
+    """
+    logical = Path(logical_cwd).expanduser()
+    if not logical.is_absolute() or not logical.is_dir():
+        return False
+    try:
+        return os.path.samefile(logical, physical_cwd)
+    except (OSError, ValueError):
+        return False
+
+
+def has_symlink_component(path: Path) -> bool:
+    """Return whether any existing lexical component of ``path`` is a symlink.
+
+    The lexical path is intentionally inspected before ``resolve()`` so a
+    symlink cannot be hidden by resolving to an otherwise trusted directory.
+    Missing trailing components are allowed; this keeps normal project paths
+    usable while still checking every existing ancestor.
+    """
+    current = Path(path.anchor) if path.is_absolute() else Path.cwd()
+    for component in path.parts[1:] if path.is_absolute() else path.parts:
+        if component in {"", "."}:
+            continue
+        current /= component
+        if current.is_symlink():
+            return True
+    return False

package/scripts/ci-validate-yaml.py

@@ -1,12 +1,17 @@
 #!/usr/bin/env python3
 """Validate agent YAML frontmatter in CI."""
-import os, re, yaml, sys
+import os
+import re
+import sys
+
+import yaml
 
 errors = 0
 for f in sorted(os.listdir('src/agents')):
     if not f.endswith('.md'):
         continue
-    content = open(f'src/agents/{f}').read()
+    with open(f"src/agents/{f}", encoding="utf-8") as agent_file:
+        content = agent_file.read()
     match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
     if match:
         try:

package/scripts/code_mode_server.py

@@ -18,8 +18,8 @@ from __future__ import annotations
 import asyncio
 import logging
 import os
-import signal
 import shutil
+import signal
 import stat
 import sys
 import time
@@ -28,7 +28,6 @@ from pathlib import Path
 from typing import Any
 
 import yaml
-
 from _pantheon_paths import pantheon_home, pantheon_project
 from mcp.server.fastmcp import FastMCP
 
@@ -133,6 +132,34 @@ def _detect_prlimit() -> str | None:
 # 1. /.opencode/.pantheon/code-mode/  (project install)
 # 2. /.pantheon/code-mode/            (legacy fallback)
 # 3. /.pantheon/code-mode/               (global fallback)
+# 4. .pantheon/code-mode/ shipped inside the installed package (tarball
+#    fallback — package.json `files` includes .pantheon/code-mode/**)
+
+
+def _packaged_scripts_dir() -> Path | None:
+    """Return the code-mode dir shipped inside the installed package, if any.
+
+    Walks up from this file looking for a `.pantheon/code-mode/` directory
+    (e.g. `<pkg>/.pantheon/code-mode` when installed from the tarball).
+    Returns None when no packaged copy exists.
+    """
+    try:
+        here = Path(__file__).resolve()
+    except Exception:
+        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
+    return None
+
+
 _PANTHEON_HOME: Path = pantheon_home()
 _SCRIPTS_DIR_CANDIDATES: list[Path] = []
 _proj = pantheon_project()
@@ -146,6 +173,10 @@ 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
 
 # ── FastMCP App ───────────────────────────────────────────────────────────────
 mcp = FastMCP(

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))