pantheon-opencode 1.5.0-beta.4 → 1.5.0-beta.6

package/scripts/install/strings.mjs

@@ -0,0 +1,129 @@
+/**
+ * strings.mjs — installer strings with locale auto-detection.
+ *
+ * LANG/LC_ALL/LC_MESSAGES starting with "pt" selects the PT-BR table;
+ * everything else (and the absence of a locale) selects EN. A plain string
+ * table — deliberately no i18n framework (YAGNI).
+ *
+ * Scope: the user journey (banner → install steps → health → summary →
+ * next steps). Deep diagnostics (per-file copy detail, doctor output) and
+ * the model-picker wizard remain single-language by design.
+ */
+
+const TABLE = {
+  en: {
+    installing: 'Installing...',
+    dryRun: 'DRY RUN',
+    canceled: 'Installation canceled — nothing was broken; run init again anytime.',
+    canceledShort: 'Installation canceled.',
+    installFailed: (msg) => `❌ Installation failed: ${msg}`,
+    failHintNoMcp:
+      '   Run with --no-mcp to skip Python dependencies:\n     npx pantheon-opencode init --no-mcp',
+    failHintForce:
+      '   Or retry with --force to recreate the venv:\n     npx pantheon-opencode init --force',
+    runningHealthCheck: 'Running health check...',
+    installedTitle: (v) => `✅ Pantheon OpenCode v${v} installed!`,
+    nextSteps: 'Next steps:',
+    nextVerify: '1. Verify installation:\n     npx pantheon-opencode doctor',
+    nextLaunch: '2. Launch OpenCode',
+    nextAgents: '3. Invoke agents with @agent-name in chat',
+    nextProject: '4. For project-local install:\n     npx pantheon-opencode init --project',
+    // install steps
+    globalLayout:
+      'Global config directory detected — using flat layout (agents/, skills/, commands/)',
+    installingAgents: 'Installing agents',
+    installingSkills: 'Installing skills',
+    installingInstructions: 'Installing instructions',
+    installingPrompts: 'Installing prompts',
+    installingCommands: 'Installing commands',
+    installingPlugins: 'Installing plugins',
+    settingUpRuntime: 'Setting up Python virtual environment',
+    healthSection: 'Health Check',
+    runningHealthChecks: 'Running health checks',
+    runtimeFailed: (msg) => `Python runtime setup failed: ${msg}`,
+    runtimeSkippedMcp:
+      'MCP servers were NOT configured because the Python runtime is unavailable. ' +
+      'Fix python3 (or free disk space) and re-run init to add them; everything else was installed.',
+    prereqMissing:
+      'runtime prerequisites missing — install the tools above, or re-run with --no-mcp to install without Python MCP servers',
+    v2Migrating: 'Migrating config to V2 native format...',
+    // summary (printSummary)
+    summaryInstalled: (target) => `OpenCode installed in ${target}`,
+    summaryWithErrors: (target) => `Installation finished WITH ERRORS in ${target}`,
+    summaryComponents: (created, skipped) =>
+      `  Components:\t${created} installed, ${skipped} skipped`,
+    summaryErrors: (n) => `  ${n} error(s) found`,
+    summaryWarnings: (n) => `  ${n} warning(s) — run 'doctor' for details`,
+    summaryNext: '  Next steps:',
+    summaryNextAgents: '   • Configure your agents in opencode.json',
+    summaryNextMcp: '   • Add MCP servers in opencode.json (mcp section)',
+    summaryNextDoctor: "   • Run 'opencode doctor' to verify the installation",
+  },
+  pt: {
+    installing: 'Instalando...',
+    dryRun: 'SIMULAÇÃO',
+    canceled: 'Instalação cancelada — nada foi quebrado; rode init de novo quando quiser.',
+    canceledShort: 'Instalação cancelada.',
+    installFailed: (msg) => `❌ Instalação falhou: ${msg}`,
+    failHintNoMcp:
+      '   Rode com --no-mcp para pular dependências Python:\n     npx pantheon-opencode init --no-mcp',
+    failHintForce:
+      '   Ou tente de novo com --force para recriar a venv:\n     npx pantheon-opencode init --force',
+    runningHealthCheck: 'Rodando verificação de saúde...',
+    installedTitle: (v) => `✅ Pantheon OpenCode v${v} instalado!`,
+    nextSteps: 'Próximos passos:',
+    nextVerify: '1. Verifique a instalação:\n     npx pantheon-opencode doctor',
+    nextLaunch: '2. Abra o OpenCode',
+    nextAgents: '3. Invoc agentes com @nome-do-agente no chat',
+    nextProject: '4. Para instalar no projeto:\n     npx pantheon-opencode init --project',
+    // install steps
+    globalLayout:
+      'Diretório de config global detectado — layout plano (agents/, skills/, commands/)',
+    installingAgents: 'Instalando agentes',
+    installingSkills: 'Instalando skills',
+    installingInstructions: 'Instalando instruções',
+    installingPrompts: 'Instalando prompts',
+    installingCommands: 'Instalando comandos',
+    installingPlugins: 'Instalando plugins',
+    settingUpRuntime: 'Configurando ambiente virtual Python',
+    healthSection: 'Verificação de saúde',
+    runningHealthChecks: 'Rodando verificações de saúde',
+    runtimeFailed: (msg) => `Falha ao configurar o runtime Python: ${msg}`,
+    runtimeSkippedMcp:
+      'Os servidores MCP NÃO foram configurados porque o runtime Python está indisponível. ' +
+      'Corrija o python3 (ou libere espaço em disco) e rode init de novo para adicioná-los; todo o resto foi instalado.',
+    prereqMissing:
+      'pré-requisitos do runtime ausentes — instale as ferramentas acima, ou rode de novo com --no-mcp para instalar sem os MCPs Python',
+    v2Migrating: 'Migrando config para o formato nativo V2...',
+    // summary (printSummary)
+    summaryInstalled: (target) => `OpenCode instalado em ${target}`,
+    summaryWithErrors: (target) => `Instalação concluída COM ERROS em ${target}`,
+    summaryComponents: (created, skipped) =>
+      `  Componentes:\t${created} instalados, ${skipped} pulados`,
+    summaryErrors: (n) => `  ${n} erro(s) encontrados`,
+    summaryWarnings: (n) => `  ${n} aviso(s) — rode 'doctor' para detalhes`,
+    summaryNext: '  Próximos passos:',
+    summaryNextAgents: '   • Configure seus agentes em opencode.json',
+    summaryNextMcp: '   • Adicione MCP servers em opencode.json (seção mcp)',
+    summaryNextDoctor: "   • Rode 'opencode doctor' para verificar a instalação",
+  },
+}
+
+/** Pure locale resolution (exported for tests). */
+export function detectLocale(env = process.env) {
+  const raw = env.LC_ALL ?? env.LC_MESSAGES ?? env.LANG ?? ''
+  return /^pt/i.test(raw) ? 'pt' : 'en'
+}
+
+/** Pure table access (exported for tests and explicit-locale callers). */
+export function stringsFor(locale) {
+  return TABLE[locale] ?? TABLE.en
+}
+
+let cached = null
+
+/** Locale-resolved string table for the current process. */
+export function strings(env = process.env) {
+  if (cached === null) cached = stringsFor(detectLocale(env))
+  return cached
+}

package/scripts/install-mcp.mjs

@@ -221,6 +221,7 @@ export const MCPS = {
         type: 'local',
         command: VENV_PYTHON,
         args: [CODE_MODE_SERVER],
+        cwd: '.',
       },
     },
     env: [],

package/scripts/release-beta-version.mjs

@@ -14,18 +14,13 @@
  * compatibility only; it is no longer generated.
  */
 
-import {
-  SEMVER_PATTERN,
-  validateInventory,
-  writeInventoryVersion,
-} from './manifest-inventory.mjs'
+import { SEMVER_PATTERN, validateInventory, writeInventoryVersion } from './manifest-inventory.mjs'
 
 const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
 // Current committed sequential beta line.
 const BETA_LINE = /^(\d+\.\d+\.\d+)-beta\.(\d+)$/
 // Legacy PR+SHA beta scheme, accepted for recovery only.
-const LEGACY_BETA =
-  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-beta\.[1-9]\d*\.[0-9a-f]{7}$/
+const LEGACY_BETA = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-beta\.[1-9]\d*\.[0-9a-f]{7}$/
 const BETA_RELEASE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-beta\.[1-9]\d*$/
 
 export function nextStableVersion(latest, intent = 'patch') {

package/scripts/sync-artifacts.mjs

@@ -0,0 +1,169 @@
+/**
+ * sync-artifacts.mjs — postinstall freshness sync for copy-only artifacts.
+ *
+ * Guarantees that an `npm install -g pantheon-opencode` (or npx cache
+ * refresh) brings an EXISTING installation up to date for everything that is
+ * a pure byte-compare copy: agents + routing.yml, skills, AGENTS.md,
+ * commands, the runtime MCP scripts, the code-mode payload and tiers.json.
+ *
+ * Deliberately NOT done here (they belong to `pantheon-opencode init` /
+ * `update`, which the doctor points at when versions drift):
+ *   - opencode.json merge (config keys, plugin registration, MCP entries)
+ *   - venv/pip setup
+ *   - tui.json registration changes
+ *
+ * The user's opencode.json already references the installed package root for
+ * plugins, so after a package update those references hit the NEW code
+ * automatically; this sync refreshes the COPIES that would otherwise stay
+ * stale until the next manual init.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  collectSkillNames,
+  copyFiles,
+  installSkills,
+  ROOT,
+  syncDir,
+  writeIfChanged,
+} from './install/shared.mjs'
+
+/** Canonical MCP script sources — mirrors installOpenCode phase 2.10. */
+const MCP_SCRIPTS = {
+  'mcp_resources_server.py': () => join(ROOT, 'src', 'mcp', 'mcp_resources_server.py'),
+  'code_mode_server.py': () => join(ROOT, 'src', 'mcp', 'code_mode_server.py'),
+  'memory_mcp_server.py': () => join(ROOT, 'src', 'mcp', 'memory_mcp_server.py'),
+  'mcp_persistence_server.py': () => join(ROOT, 'src', 'mcp', 'mcp_persistence_server.py'),
+  '_pantheon_paths.py': () => join(ROOT, 'src', 'mcp', '_pantheon_paths.py'),
+  'mcp_codemap_module.py': () => join(ROOT, 'src', 'mcp', 'mcp_codemap_module.py'),
+  'pantheon_vision_server.py': () => join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py'),
+  'eval_store.py': () => join(ROOT, 'src', 'mcp', 'eval_store.py'),
+  'scrub-secrets.py': () => join(ROOT, 'scripts', 'scrub-secrets.py'),
+}
+
+/**
+ * Sync all copy-only artifacts from the installed package into configDir
+ * (the GLOBAL OpenCode config dir). Byte-compare idempotent; never throws.
+ * @returns {{ created: number, skipped: number, errors: string[] }}
+ */
+export function syncCopyArtifacts(configDir) {
+  const result = { created: 0, skipped: 0, errors: [] }
+  const bump = (r) => {
+    result.created += r.created
+    result.skipped += r.skipped
+  }
+
+  // ── agents + routing.yml ──
+  try {
+    const dstAgents = join(configDir, 'agents')
+    if (existsSync(join(ROOT, 'src', 'agents'))) {
+      mkdirSync(dstAgents, { recursive: true })
+      bump(copyFiles(join(ROOT, 'src', 'agents'), dstAgents, false))
+      const routing = join(ROOT, 'src', 'routing.yml')
+      if (existsSync(routing)) {
+        if (
+          writeIfChanged(join(configDir, 'routing.yml'), readFileSync(routing, 'utf8'), false) ===
+          'created'
+        ) {
+          result.created++
+        } else result.skipped++
+      }
+    }
+  } catch (err) {
+    result.errors.push(`agents: ${err.message}`)
+  }
+
+  // ── skills ──
+  try {
+    const names = collectSkillNames()
+    if (names.length > 0) bump(installSkills(names, configDir, false, ''))
+  } catch (err) {
+    result.errors.push(`skills: ${err.message}`)
+  }
+
+  // ── instructions (AGENTS.md) ──
+  try {
+    const src = join(ROOT, 'AGENTS.md')
+    if (existsSync(src)) {
+      if (
+        writeIfChanged(join(configDir, 'AGENTS.md'), readFileSync(src, 'utf8'), false) === 'created'
+      ) {
+        result.created++
+      } else result.skipped++
+    }
+  } catch (err) {
+    result.errors.push(`instructions: ${err.message}`)
+  }
+
+  // ── commands (*.md) ──
+  try {
+    const srcCmds = join(ROOT, 'commands')
+    if (existsSync(srcCmds)) {
+      bump(syncDir(srcCmds, join(configDir, 'commands'), false, false, (f) => f.endsWith('.md')))
+    }
+  } catch (err) {
+    result.errors.push(`commands: ${err.message}`)
+  }
+
+  // ── runtime payload (MCP scripts, code-mode, tiers) ──
+  try {
+    const dstScripts = join(configDir, 'scripts')
+    mkdirSync(dstScripts, { recursive: true })
+    for (const [name, srcFn] of Object.entries(MCP_SCRIPTS)) {
+      const src = srcFn()
+      if (!existsSync(src)) continue
+      const content = readFileSync(src, 'utf8')
+      const dst = join(dstScripts, name)
+      if (writeIfChanged(dst, content, false) === 'created') {
+        statSync(dst)
+        result.created++
+      } else result.skipped++
+    }
+
+    const req = join(ROOT, 'src', 'mcp', 'requirements-vision.txt')
+    if (existsSync(req)) {
+      if (
+        writeIfChanged(
+          join(configDir, 'requirements-vision.txt'),
+          readFileSync(req, 'utf8'),
+          false,
+        ) === 'created'
+      ) {
+        result.created++
+      } else result.skipped++
+    }
+
+    const srcCodeMode = join(ROOT, '.pantheon', 'code-mode')
+    const dstCodeMode = join(configDir, '.pantheon', 'code-mode')
+    if (existsSync(srcCodeMode)) {
+      bump(syncDir(srcCodeMode, dstCodeMode, false, false))
+    }
+
+    const srcTiers = join(ROOT, '.pantheon', 'tiers.json')
+    const dstTiers = join(configDir, '.pantheon', 'tiers.json')
+    if (existsSync(srcTiers)) {
+      if (writeIfChanged(dstTiers, readFileSync(srcTiers, 'utf8'), false) === 'created')
+        result.created++
+      else result.skipped++
+    }
+  } catch (err) {
+    result.errors.push(`runtime: ${err.message}`)
+  }
+
+  return result
+}
+
+/** Drop stale entries in dst that no longer exist in src (agents/skills dirs). */
+export function pruneMissing(srcDir, dstDir) {
+  if (!existsSync(srcDir) || !existsSync(dstDir)) return 0
+  const src = new Set(readdirSync(srcDir))
+  let removed = 0
+  for (const entry of readdirSync(dstDir)) {
+    if (!src.has(entry)) {
+      rmSync(join(dstDir, entry), { recursive: true, force: true })
+      removed++
+    }
+  }
+  return removed
+}

package/scripts/sync-tui.mjs

@@ -138,7 +138,7 @@ export function sanitizeNpmEnv(env = process.env) {
 
 // ── Main ───────────────────────────────────────────────────────────────
 
-function main() {
+async function main() {
   try {
     const configDir = resolveConfigDir()
     if (!configDir) {
@@ -148,8 +148,17 @@ function main() {
 
     const tuiCopyDir = join(configDir, 'plugins', 'pantheon-tui')
     if (!existsSync(tuiCopyDir)) {
-      // TUI plugin not installed — silent exit
-      process.exit(0)
+      // beta.5: no TUI install (plugins component omitted) — skip the TUI
+      // sync but STILL refresh the copy-only artifacts below.
+      const { syncCopyArtifacts } = await import('./sync-artifacts.mjs')
+      const synced = syncCopyArtifacts(configDir)
+      if (synced.errors.length > 0) {
+        for (const e of synced.errors) console.error(`  ⚠️  artifact sync: ${e}`)
+      }
+      console.log(
+        `  Artifacts synced: ${synced.created} updated, ${synced.skipped} already current`,
+      )
+      return
     }
 
     // Source: TUI plugin inside the installed package
@@ -181,6 +190,38 @@ function main() {
         `  TUI plugin updated to v${sourceVersion || 'latest'}${installedVersion ? ` (was v${installedVersion})` : ''}`,
       )
     }
+
+    // ── beta.5 freshness guarantee: refresh ALL copy-only artifacts ──
+    // Agents, skills, AGENTS.md, commands, MCP scripts, code-mode payload.
+    // The plugin references in opencode.json already point INTO this package,
+    // so only the copies would go stale after a package update.
+    const { syncCopyArtifacts } = await import('./sync-artifacts.mjs')
+    const { readState, writeState } = await import('./install/state.mjs')
+    const pkgVersion = readVersion(join(ROOT, 'package.json')) ?? 'unknown'
+    const synced = syncCopyArtifacts(configDir)
+    if (synced.errors.length > 0) {
+      for (const e of synced.errors) console.error(`  ⚠️  artifact sync: ${e}`)
+    }
+    console.log(`  Artifacts synced: ${synced.created} updated, ${synced.skipped} already current`)
+
+    // Version marker so doctor can detect a stale installation and point the
+    // user at `pantheon-opencode update` for the full refresh (config merge,
+    // venv, MCP entries).
+    try {
+      const previous = readState(configDir)
+      writeState(configDir, {
+        pantheon_version: pkgVersion,
+        previous_version: previous?.pantheon_version ?? null,
+      })
+      if (previous?.pantheon_version && previous.pantheon_version !== pkgVersion) {
+        console.log(
+          `  ⚠️  Installation moved ${previous.pantheon_version} → ${pkgVersion}. ` +
+            'Run `npx pantheon-opencode init` to refresh config/venv/MCP entries.',
+        )
+      }
+    } catch {
+      // Marker is best-effort — never fail the postinstall over it.
+    }
   } catch (err) {
     console.error(`❌ TUI sync failed: ${err.message}`)
     process.exitCode = 1
@@ -192,4 +233,9 @@ function main() {
 const isDirectRun =
   Boolean(process.argv[1]) && pathToFileURL(process.argv[1]).href === import.meta.url
 
-if (isDirectRun) main()
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error(`❌ TUI sync failed: ${err.message}`)
+    process.exitCode = 1
+  })
+}

package/src/mcp/code_mode_server.py

@@ -157,12 +157,9 @@ def _detect_prlimit() -> str | None:
 
 
 # ── Scripts Directory Resolution ─────────────────────────────────────────────
-# Priority:
-# 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/**)
+# Project directories are selected before global directories.  Once a usable
+# project directory is selected, manifest errors are deliberately fail-closed;
+# execution must never silently cross the project/global trust boundary.
 
 
 def _is_within(path: Path, root: Path) -> bool:
@@ -229,25 +226,38 @@ def _packaged_scripts_dir() -> Path | None:
     return None
 
 
-def _resolve_scripts_dir(candidates: list[Path]) -> Path | None:
-    """Select the first usable candidate, then try the packaged fallback."""
+def _resolve_scripts_dir(candidates: list[Path], *, allow_packaged: bool = True) -> Path | None:
+    """Select the first usable candidate, optionally trying the package copy."""
     for candidate in candidates:
         if _has_usable_scripts(candidate):
             return candidate
-    return _packaged_scripts_dir()
+    return _packaged_scripts_dir() if allow_packaged else None
+
+
+def _resolve_code_mode_dir() -> Path:
+    """Resolve code-mode scripts project-first, with a global-only fallback.
+
+    A project directory is a trust boundary: if one is selected, callers use
+    its manifest even when that manifest is missing or corrupt.  Global users
+    retain the packaged/global fallback when no usable project directory is
+    available.
+    """
+    project = pantheon_project()
+    if project is not None:
+        project_candidates = [
+            project / ".opencode" / ".pantheon" / "code-mode",
+            project / ".pantheon" / "code-mode",
+        ]
+        selected = _resolve_scripts_dir(project_candidates, allow_packaged=False)
+        if selected is not None:
+            return selected
+
+    global_dir = pantheon_home() / ".pantheon" / "code-mode"
+    return _resolve_scripts_dir([global_dir]) or global_dir
 
 
 _PANTHEON_HOME: Path = pantheon_home()
-_SCRIPTS_DIR_CANDIDATES: list[Path] = []
-_proj = pantheon_project()
-if _proj is not None:
-    _SCRIPTS_DIR_CANDIDATES.append(_proj / ".opencode" / ".pantheon" / "code-mode")
-    _SCRIPTS_DIR_CANDIDATES.append(_proj / ".pantheon" / "code-mode")
-_SCRIPTS_DIR_CANDIDATES.append(_PANTHEON_HOME / ".pantheon" / "code-mode")
-
-SCRIPTS_DIR: Path = _resolve_scripts_dir(_SCRIPTS_DIR_CANDIDATES) or (
-    _PANTHEON_HOME / ".pantheon" / "code-mode"
-)
+SCRIPTS_DIR: Path = _resolve_code_mode_dir()
 
 # ── FastMCP App ───────────────────────────────────────────────────────────────
 mcp = FastMCP(
@@ -371,6 +381,11 @@ def _load_manifest(scripts_dir: Path | None = None) -> dict[str, str]:
             "CORRUPT_DATA", "Code-mode manifest must be a JSON object."
         )
 
+    if data.get("version") != 1:
+        raise ManifestError(
+            "CORRUPT_DATA", "Code-mode manifest malformed: version must be 1."
+        )
+
     scripts = data.get("scripts")
     if not isinstance(scripts, dict):
         raise ManifestError(
@@ -384,6 +399,7 @@ def _load_manifest(scripts_dir: Path | None = None) -> dict[str, str]:
             not isinstance(name, str)
             or not isinstance(digest, str)
             or len(digest) != _SHA256_HEX_LEN
+            or any(char not in "0123456789abcdefABCDEF" for char in digest)
         ):
             raise ManifestError(
                 "CORRUPT_DATA",
@@ -877,4 +893,3 @@ def _cli() -> int:
 
 if __name__ == "__main__":
     raise SystemExit(_cli())
-

package/src/pantheon/auto-wake.ts

@@ -78,11 +78,7 @@ export async function consumeWakeSignals(signalDir?: string): Promise<WakeSignal
 
       // Step 3: Only add to results after successful rename
       signals.push(data)
-    } catch {
-      // Rename failed (another consumer got there first) or file is corrupted.
-      // Skip silently in either case.
-      continue
-    }
+    } catch {}
   }
 
   return signals

package/src/pantheon/shared-board.ts

@@ -0,0 +1,37 @@
+/**
+ * Process-wide BackgroundJobBoard singleton shared by every Pantheon plugin
+ * surface (src/plugin.ts V1, src/plugins/pantheon-hooks.ts).
+ *
+ * WHY globalThis and not a module-level `const`: opencode loads each plugin
+ * TWICE from two different filesystem paths (the installed npm package AND
+ * the repo source — see src/pantheon/plugin-once.ts). Each load is a separate
+ * module instance, so a plain ESM singleton would yield TWO boards: the
+ * native-task mirror in pantheon-hooks would register jobs on one instance
+ * while the finalize path (session.idle + idle scan in plugin.ts) listens on
+ * the other, and the job would never finalize. A globalThis-anchored value is
+ * process-global by construction, deduping both module copies.
+ *
+ * The persistence file and signal dir are RELATIVE paths — the board operates
+ * against the opencode project root (the cwd of the plugin process), matching
+ * the pre-existing plugin.ts wiring exactly.
+ */
+import { BackgroundJobBoard } from './background-job-board.ts'
+import { FilePersistenceAdapter } from './file-persistence.ts'
+
+const BOARD_KEY = '__pantheonSharedBoard'
+
+/** Construction inputs mirror the original plugin.ts module-scope board. */
+const BOARD_OPTIONS = {
+  maxConcurrentPerAgent: 3,
+  signalDir: '.pantheon/deepwork/board-signals',
+} as const
+
+export function getSharedBoard(): BackgroundJobBoard {
+  const host = globalThis as { [BOARD_KEY]?: BackgroundJobBoard }
+  const existing = host[BOARD_KEY]
+  if (existing instanceof BackgroundJobBoard) return existing
+  const board = new BackgroundJobBoard(BOARD_OPTIONS)
+  board.setPersistence(new FilePersistenceAdapter('.pantheon/board/state.json'))
+  host[BOARD_KEY] = board
+  return board
+}

package/src/plugin.ts

@@ -2,7 +2,6 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Plugin, PluginInput } from '@opencode-ai/plugin'
 import type { PluginConfig } from 'opencode'
-import { BackgroundJobBoard } from './pantheon/background-job-board.ts'
 import { createCommandNormalizer } from './pantheon/command-normalizer.ts'
 import {
   type ContextSandboxConfig,
@@ -30,7 +29,6 @@ import {
 } from './pantheon/delegation-enforce.ts'
 import { handleDelegationEvent } from './pantheon/delegation-notify.ts'
 import { showDelegationTerminalToast, type ToastClient } from './pantheon/delegation-toast.ts'
-import { FilePersistenceAdapter } from './pantheon/file-persistence.ts'
 import { GOAL_LOOP_DEFAULTS, GoalLoop, GoalStore } from './pantheon/goal-loop.ts'
 import { createReadEnhancer } from './pantheon/hashline/read-enhancer.ts'
 import { createHashlineEditTool } from './pantheon/hashline/tool.ts'
@@ -45,6 +43,7 @@ import {
   loadRoutingPermissionTask,
 } from './pantheon/presets.mjs'
 import { safeSessionPath } from './pantheon/session-guard.ts'
+import { getSharedBoard } from './pantheon/shared-board.ts'
 import { StepCapTracker } from './pantheon/step-cap.ts'
 import { createTaskResultGuard } from './pantheon/task-result-guard.ts'
 import {
@@ -77,12 +76,11 @@ const stepCapTracker = new StepCapTracker(loadRoutingMaxSteps({ logger: log }))
 // (fail-open → undefined = existing runtime matrix only).
 const routingPermissionTask = loadRoutingPermissionTask({ logger: log })
 
-const board = new BackgroundJobBoard({
-  maxConcurrentPerAgent: 3,
-  signalDir: '.pantheon/deepwork/board-signals',
-})
-const persistence = new FilePersistenceAdapter('.pantheon/board/state.json')
-board.setPersistence(persistence)
+// beta.5: the board is a PROCESS-wide singleton (getSharedBoard) shared with
+// src/plugins/pantheon-hooks.ts, whose native-task mirror registers children
+// here; the finalize path below (session.idle + idle scan) must observe the
+// SAME instance. globalThis anchoring dedupes the npm+repo double load.
+const board = getSharedBoard()
 let terminalToastClient: ToastClient = {}
 board
   .recoverRunningJobs()

package/src/plugins/pantheon-hooks.ts

@@ -177,6 +177,7 @@ import { appendFile, mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Plugin, PluginInput } from '@opencode-ai/plugin'
 import { pantheonPluginOnce } from '../pantheon/plugin-once.ts'
+import { getSharedBoard } from '../pantheon/shared-board.ts'
 import { type HookPayload, type HookResult, runHook } from './hook-runner.ts'
 
 /** Tools that represent a subagent delegation (opencode `task` tool etc.). */
@@ -775,6 +776,51 @@ function delegationAgent(tool: string, args?: unknown): string {
   return tool
 }
 
+/**
+ * beta.5: mirror a native background task dispatch onto the SHARED board
+ * (getSharedBoard) so the existing finalize path in plugin.ts (session.idle
+ * event + 30s idle scan) writes the terminal report and the TUI delegation
+ * panel tracks the child end-to-end. Fire-and-forget and silent: a mirror
+ * failure must never surface into the tool call or the transcript.
+ * registerLaunchIfAbsent keeps it idempotent against any other dispatcher
+ * (v2-events, plugin double-load, repeated after-hook firings).
+ */
+function mirrorNativeBackgroundDispatch(
+  input: { tool: string; sessionID: string },
+  args: unknown,
+  result: ToolExecuteAfterResult | null,
+): void {
+  const taskID = extractTaskId(result)
+  if (taskID === '' || typeof input.sessionID !== 'string' || input.sessionID === '') return
+  const description = trim(delegationDescription(args) ?? `native ${input.tool} dispatch`, 200)
+  try {
+    getSharedBoard()
+      .registerLaunchIfAbsent({
+        taskID,
+        parentSessionID: input.sessionID,
+        agent: delegationAgent(input.tool, args),
+        description,
+      })
+      .catch(() => {
+        // Mirror is best-effort — never surface into the tool call.
+      })
+  } catch {
+    // Never let the mirror take down the tool call.
+  }
+}
+
+/** Task description from task-tool args (description ?? prompt); undefined when absent. */
+function delegationDescription(args: unknown): string | undefined {
+  try {
+    const a = (args ?? {}) as Record<string, unknown>
+    const raw = a.description ?? a.prompt
+    if (typeof raw === 'string' && raw.trim() !== '') return raw
+  } catch {
+    // Malformed args — fall through to the generic description.
+  }
+  return undefined
+}
+
 /** 🚀 delegation-started toast (variant 'info', 2500ms), deduped per agent. */
 async function delegationStartedToast(ctx: HookContext, agent: string): Promise<void> {
   await throttledToast(ctx, {
@@ -1311,6 +1357,11 @@ const plugin: Plugin = async ({ client, directory }) => {
             // NOT a completion: do not mark the group done and do not fire ✅
             // — that would corrupt olympians aggregation. Real completion of
             // background tasks is unobservable on 1.18.13 (see header).
+            // beta.5: mirror the native background child onto the SHARED
+            // board so the existing finalize path (session.idle + idle scan
+            // in plugin.ts) writes the terminal report and the TUI
+            // delegation panel tracks the child end-to-end. Fire-and-forget.
+            mirrorNativeBackgroundDispatch(input, args, result)
           } else {
             const handledByOlympians = handleOlympiansCompletion(ctx, agent)
             if (!handledByOlympians) void delegationDoneToast(ctx, agent)

package/src/plugins/tui/dist/server.d.ts

@@ -14,4 +14,4 @@
 declare function server(): {};
 //#endregion
 export { server as default };
-//# sourceMappingURL=server.d.ts.map
+//# sourceMappingURL=server.d.ts.map