pantheon-opencode 1.3.6 → 1.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",

package/scripts/sync-tui.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * sync-tui.mjs — Postinstall hook: sync TUI plugin to user's OpenCode config
+ *
+ * Runs automatically after `npm install pantheon-opencode@latest`. Detects the
+ * user's OpenCode config directory and, if the TUI plugin was previously
+ * installed (via `npx pantheon-opencode init`), copies fresh files from the
+ * installed package and refreshes dependencies.
+ *
+ * If the user hasn't initialized yet → do nothing (silent exit).
+ */
+import { execSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const ROOT = join(__dirname, '..')
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Write content to filePath only if it differs from what's on disk.
+ * @returns {boolean} true if file was written (changed), false if skipped
+ */
+function writeIfChanged(filePath, content) {
+  const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : null
+  if (existing === content) return false
+  writeFileSync(filePath, content, 'utf8')
+  return true
+}
+
+/**
+ * Read the `version` field from a package.json, or null on failure.
+ */
+function readVersion(pkgPath) {
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Resolve the user's OpenCode config directory.
+ * Priority: $XDG_CONFIG_HOME/opencode → ~/.opencode → null (not initialized)
+ */
+function resolveConfigDir() {
+  const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  const xdgDir = join(xdgConfig, 'opencode')
+  if (existsSync(xdgDir)) return xdgDir
+
+  const homeDir = join(homedir(), '.opencode')
+  if (existsSync(homeDir)) return homeDir
+
+  return null
+}
+
+/**
+ * Copy plugin runtime files (dist/*, package.json, src/index.tsx) from srcDir
+ * to dstDir. Skips files that are byte-identical.
+ * @returns {{ created: number, skipped: number }}
+ */
+function copyPluginFiles(srcDir, dstDir) {
+  const result = { created: 0, skipped: 0 }
+
+  mkdirSync(dstDir, { recursive: true })
+  mkdirSync(join(dstDir, 'dist'), { recursive: true })
+
+  // src/index.tsx → index.tsx
+  const srcIdx = join(srcDir, 'src', 'index.tsx')
+  if (existsSync(srcIdx)) {
+    const content = readFileSync(srcIdx, 'utf8')
+    if (writeIfChanged(join(dstDir, 'index.tsx'), content)) result.created++
+    else result.skipped++
+  }
+
+  // dist/*
+  const distSrc = join(srcDir, 'dist')
+  if (existsSync(distSrc)) {
+    for (const f of readdirSync(distSrc)) {
+      const content = readFileSync(join(distSrc, f), 'utf8')
+      if (writeIfChanged(join(dstDir, 'dist', f), content)) result.created++
+      else result.skipped++
+    }
+  }
+
+  // package.json
+  const pkgSrc = join(srcDir, 'package.json')
+  if (existsSync(pkgSrc)) {
+    const content = readFileSync(pkgSrc, 'utf8')
+    if (writeIfChanged(join(dstDir, 'package.json'), content)) result.created++
+    else result.skipped++
+  }
+
+  return result
+}
+
+// ── Main ───────────────────────────────────────────────────────────────
+
+try {
+  const configDir = resolveConfigDir()
+  if (!configDir) {
+    // User hasn't run init yet — silent exit, no error
+    process.exit(0)
+  }
+
+  const tuiCopyDir = join(configDir, 'plugins', 'pantheon-tui')
+  if (!existsSync(tuiCopyDir)) {
+    // TUI plugin not installed — silent exit
+    process.exit(0)
+  }
+
+  // Source: TUI plugin inside the installed package
+  const tuiSrcDir = join(ROOT, 'src', 'plugins', 'tui')
+  if (!existsSync(tuiSrcDir)) {
+    // Source not found (shouldn't happen in a proper install)
+    process.exit(0)
+  }
+
+  // Compare versions before copy
+  const installedVersion = readVersion(join(tuiCopyDir, 'package.json'))
+  const sourceVersion = readVersion(join(tuiSrcDir, 'package.json'))
+
+  // Copy fresh files
+  const { created, skipped } = copyPluginFiles(tuiSrcDir, tuiCopyDir)
+
+  // Refresh dependencies in the copy
+  try {
+    execSync('npm install --omit=dev --no-audit', { cwd: tuiCopyDir, stdio: 'pipe' })
+  } catch {
+    // Non-fatal — deps may already be current
+  }
+
+  // Log result
+  if (installedVersion && sourceVersion && installedVersion === sourceVersion && created === 0) {
+    console.log(`  TUI plugin already up to date (v${sourceVersion})`)
+  } else {
+    console.log(
+      `  TUI plugin updated to v${sourceVersion || 'latest'}${installedVersion ? ` (was v${installedVersion})` : ''}`,
+    )
+  }
+} catch (err) {
+  // Postinstall scripts must never break npm install
+  console.warn(`⚠️  TUI sync skipped: ${err.message}`)
+  process.exit(0)
+}

package/src/pantheon/delegation-notify.ts

@@ -21,6 +21,11 @@
  * acknowledgment, not a completion), so every job gets exactly ONE terminal
  * transition — never a reconciled echo. Unknown sessions are ignored.
  *
+ * `finalizeIdleChildrenWithoutMd` proactively finalizes children that are
+ * idle on the board but have no MD report on disk — eliminates the phantom
+ * "running" window during `pullOutput` (Fix 2 for the TUI stale-running bug).
+ * Wired into a periodic scan via `startIdleChildScan` (default 30 s cadence).
+ *
  * Pure TypeScript — zero runtime dependencies beyond the board types.
  *
  * Follow-up (Themis review, Phase 5): `extractErrorMessage` handles the two
@@ -38,6 +43,9 @@ import type { FinalizeInput } from './delegation-finalize.ts'
 
 export type { FinalizeInput } from './delegation-finalize.ts'
 
+/** Default cadence for the proactive idle-child scan (30 s). */
+export const IDLE_SCAN_INTERVAL_MS = 30_000
+
 // ─── Types ─────────────────────────────────────────────────────────────
 
 /** Structural view of the event payload the `event` hook receives. */
@@ -98,3 +106,92 @@ export async function handleDelegationEvent(
   }
   return true
 }
+
+// ─── Proactive finalize (Fix 2) ────────────────────────────────────────
+
+/** Dependencies for idle-child scanning. */
+export interface IdleChildScanDeps {
+  /** Look up a board job by session ID (child session IDs are task IDs). */
+  board: {
+    get(taskID: string): BackgroundJobRecord | undefined
+    list(parentSessionID?: string): BackgroundJobRecord[]
+  }
+  /** Bound Phase 2 finalize — clears the timeout timer + writes the report. */
+  finalize: (childSessionID: string, opts: FinalizeInput) => Promise<unknown>
+  /**
+   * Check whether an MD report exists for the given board job.
+   * Receives the full job record so the caller can construct the report
+   * path from `job.parentSessionID` + `job.alias`.
+   * If the function throws, the scan skips that child (fail-open).
+   */
+  hasReport: (job: BackgroundJobRecord) => boolean
+  /** Optional logger for diagnostic messages. */
+  logger?: { info?: (msg: string) => void; warn?: (msg: string) => void }
+}
+
+/**
+ * Scan running board jobs for children whose sessions are idle but have no MD
+ * report on disk, and proactively finalize them. This eliminates the phantom
+ * "running" window that occurs between `session.idle` firing and the
+ * `pullOutput`→`writeDelegationReport` cycle completing.
+ *
+ * Called from the periodic idle-child scan (`startIdleChildScan`, default 30 s).
+ * The scan is O(N) where N = number of running jobs (typically < 10).
+ *
+ * Each child is finalized exactly once — the board's same-terminal idempotency
+ * ensures repeated scans are harmless. Errors are caught per-child so one
+ * failure never blocks the rest.
+ *
+ * @returns Number of children finalized (for diagnostics).
+ */
+export async function finalizeIdleChildrenWithoutMd(
+  deps: IdleChildScanDeps,
+): Promise<number> {
+  const runningJobs = deps.board
+    .list()
+    .filter((j: BackgroundJobRecord) => j.state === 'running')
+
+  let finalized = 0
+  for (const job of runningJobs) {
+    try {
+      // If the child already has an MD report, finalize was already handled
+      // by handleDelegationEvent — skip.
+      if (deps.hasReport(job)) continue
+      // Child is idle on the board but has no report — proactively finalize.
+      await deps.finalize(job.taskID, { state: 'completed' })
+      finalized++
+    } catch (err) {
+      deps.logger?.warn?.(
+        `[delegation-notify] proactive finalize failed for ${job.taskID}: ${err}`,
+      )
+    }
+  }
+  return finalized
+}
+
+// ─── Periodic scan launcher ─────────────────────────────────────────────
+
+/**
+ * Start a periodic scan that proactively finalizes idle board children
+ * without MD reports. The scan runs every `intervalMs` (default 30 s) and
+ * is **unref'd** so it never holds the process open on its own.
+ *
+ * The timer is idempotent — calling this function multiple times is safe
+ * (each call creates an independent timer, but the underlying finalize
+ * operation is itself idempotent due to the board's same-terminal guard).
+ *
+ * @returns A `NodeJS.Timeout` handle that can be cleared with
+ *   `clearInterval(handle)` to stop the scan.
+ */
+export function startIdleChildScan(
+  deps: IdleChildScanDeps,
+  intervalMs: number = IDLE_SCAN_INTERVAL_MS,
+): NodeJS.Timeout {
+  const timer = setInterval(() => {
+    void finalizeIdleChildrenWithoutMd(deps).catch((err) => {
+      deps.logger?.warn?.(`[delegation-notify] periodic idle scan failed: ${err}`)
+    })
+  }, intervalMs)
+  timer.unref()
+  return timer
+}

package/src/pantheon/delegation.ts

@@ -58,6 +58,11 @@ import {
   finalizeDelegation as finalizeDelegationReport,
   readDelegationReport,
 } from './delegation-finalize.ts'
+import {
+  type IdleChildScanDeps,
+  finalizeIdleChildrenWithoutMd,
+  startIdleChildScan,
+} from './delegation-notify.ts'
 import { createPantheonLogger } from './logger.ts'
 import { buildAgentListDescription } from './permission-globs.ts'
 import { missingProviderKeyEnv, resolveActivePreset } from './presets.mjs'
@@ -71,6 +76,8 @@ export type {
   FinalizeInput,
 } from './delegation-finalize.ts'
 export { DELEGATION_DEFAULTS } from './delegation-finalize.ts'
+export type { IdleChildScanDeps } from './delegation-notify.ts'
+export { finalizeIdleChildrenWithoutMd, startIdleChildScan } from './delegation-notify.ts'
 
 // Fase B3: these are runtime controls, not routing/frontmatter fields. The
 // plugin reads them from the environment, while tests and embedders can pass
@@ -326,6 +333,8 @@ export interface DelegationToolset {
     childSessionID: string,
     opts: FinalizeInput,
   ) => Promise<BackgroundJobRecord | undefined>
+  /** Proactive finalize for idle children without MD reports (Fix 2). */
+  finalizeIdleChildrenWithoutMd: typeof finalizeIdleChildrenWithoutMd
 }
 
 /** Input for createDelegationTools(). */
@@ -1182,5 +1191,6 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
     pantheon_delegation_read,
     pantheon_delegation_list,
     finalizeDelegation: finalize,
+    finalizeIdleChildrenWithoutMd,
   }
 }

package/src/pantheon/tui-version-check.ts

@@ -0,0 +1,72 @@
+/**
+ * tui-version-check.ts — Runtime staleness check for the TUI plugin copy
+ *
+ * Compares the version in the user's copied TUI plugin package.json against
+ * the version of the installed pantheon-opencode package. If mismatched,
+ * logs a one-time warning. Does NOT auto-sync (safety first).
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const ROOT = join(__dirname, '..', '..')
+
+/**
+ * Detect the user's OpenCode config directory (same logic as sync-tui.mjs).
+ * Priority: $XDG_CONFIG_HOME/opencode → ~/.opencode → null
+ */
+function resolveConfigDir(): string | null {
+  const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  const xdgDir = join(xdgConfig, 'opencode')
+  if (existsSync(xdgDir)) return xdgDir
+
+  const homeDir = join(homedir(), '.opencode')
+  if (existsSync(homeDir)) return homeDir
+
+  return null
+}
+
+/**
+ * Read the `version` field from a package.json, or null on failure.
+ */
+function readVersion(pkgPath: string): string | null {
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Run the TUI version staleness check. Call once at plugin init.
+ *
+ * @param logger - Logging function (defaults to console.warn)
+ */
+export function checkTuiVersionStaleness(
+  logger: (msg: string) => void = console.warn,
+): void {
+  try {
+    const configDir = resolveConfigDir()
+    if (!configDir) return // Not initialized — nothing to check
+
+    const tuiCopyDir = join(configDir, 'plugins', 'pantheon-tui')
+    if (!existsSync(tuiCopyDir)) return // TUI not installed
+
+    const copyVersion = readVersion(join(tuiCopyDir, 'package.json'))
+    if (!copyVersion) return // Can't read version — skip
+
+    // Read the installed package version from the repo root's package.json
+    const currentVersion = readVersion(join(ROOT, 'package.json'))
+    if (!currentVersion) return // Can't determine current version — skip
+
+    if (copyVersion !== currentVersion) {
+      logger(
+        `⚠️  TUI plugin v${copyVersion} is outdated. Current: v${currentVersion}. Run: npx pantheon-opencode init`,
+      )
+    }
+  } catch {
+    // Fail-open — version check must never block plugin initialization
+  }
+}

package/src/plugin.ts

@@ -1,5 +1,7 @@
 import type { Plugin, PluginInput } from '@opencode-ai/plugin'
 import type { PluginConfig } from 'opencode'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
 import { BackgroundJobBoard } from './pantheon/background-job-board.ts'
 import { reassertAfterCompaction } from './pantheon/compaction-assert.ts'
 import { createCostCommand } from './pantheon/cost-command.ts'
@@ -9,6 +11,7 @@ import {
   type DelegationClient,
   resolveDelegationBudgets,
   resolveDelegationTimeoutMs,
+  startIdleChildScan,
 } from './pantheon/delegation.ts'
 import { buildCompactionContext } from './pantheon/delegation-compaction.ts'
 import {
@@ -40,6 +43,7 @@ import {
   todoEnforcerEnabledFromEnv,
 } from './pantheon/todo-enforcer.ts'
 import { TodoPreserver } from './pantheon/todo-preserve.ts'
+import { checkTuiVersionStaleness } from './pantheon/tui-version-check.ts'
 import { activePresetCandidates, createVisionHandler } from './pantheon/vision.ts'
 
 // ─── Background Job Board Singleton ────────────────────────────────────
@@ -334,6 +338,9 @@ const plugin: Plugin = async (input: PluginInput) => {
   if (pantheonPluginOnce('pantheon:plugin')) {
     return {}
   }
+  // Runtime TUI version staleness check — warns if the copied TUI plugin
+  // is older than the installed package. Runs once, fail-open, no auto-sync.
+  checkTuiVersionStaleness((msg) => log.warn(msg))
   const vision = createVisionHandler(input)
   // Phase 2/3: background delegation toolset + the bound finalize lifecycle
   // hook. Completion is observed through the event hook below
@@ -363,6 +370,28 @@ const plugin: Plugin = async (input: PluginInput) => {
     },
   })
 
+  // Proactive idle-child scan (Fix 2): finalize children that are idle on the
+  // board but have no MD report on disk — eliminates the phantom "running"
+  // window. Runs every 30s (configurable via PANTHEON_IDLE_SCAN_INTERVAL_MS),
+  // unref'd so it never holds the process open. Fail-open by design.
+  const idleScanIntervalMs = Number(process.env.PANTHEON_IDLE_SCAN_INTERVAL_MS) || undefined
+  startIdleChildScan(
+    {
+      board,
+      finalize: (childSessionID, opts) => delegation.finalizeDelegation(childSessionID, opts),
+      hasReport: (job) => {
+        try {
+          const filePath = join('.pantheon/delegations', job.parentSessionID, `${job.alias}.md`)
+          return existsSync(filePath)
+        } catch {
+          return false
+        }
+      },
+      logger: log,
+    },
+    idleScanIntervalMs,
+  )
+
   // Wave 1 (PR #46): TODO continuation enforcer for root/non-board sessions.
   // Mirrors routing.yml `todo_enforcer` (plugin scope has no routing.yml
   // access — COMPACTION_MAX_ITEMS pattern). The event hook routes non-board

package/src/plugins/tui/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon-tui",
   "type": "module",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "Pantheon TUI plugin — sidebar (version, preset, sessions, real-time delegations) + AI subscription usage gauges incl. OpenCode Go/Zen dollar limits (vendored, MIT)",
   "license": "MIT",
   "exports": {

package/src/plugins/tui/src/index.tsx

@@ -942,7 +942,14 @@ export type DelegationEntry = {
   taskID?: string
   /** Agent name, e.g. "apollo". */
   agent: string
-  state: 'running' | 'completed' | 'error' | 'startup_failed' | 'startup_unknown' | 'cancelled'
+  state:
+    | 'running'
+    | 'completed'
+    | 'error'
+    | 'startup_failed'
+    | 'startup_unknown'
+    | 'cancelled'
+    | 'stale-running'
   /** Epoch ms of the `Started` header. */
   startedAt: number
   /** Epoch ms of the `Finalized` header — null while still running. */
@@ -1048,8 +1055,10 @@ export function parseDelegationMarkdown(
   const startedAt = started !== undefined ? Date.parse(started) : NaN
   if (agent === undefined || state === undefined || Number.isNaN(startedAt)) return null
   const normalized = state.toLowerCase()
+  // Running state should only come from live channels, never from persisted
+  // reports. A stale "running" MD artifact contaminates the panel — skip it.
+  if (normalized === 'running') return null
   if (
-    normalized !== 'running' &&
     normalized !== 'completed' &&
     normalized !== 'error' &&
     normalized !== 'startup_failed' &&
@@ -1171,8 +1180,8 @@ export function tuiLogPath(projectRoot: string): string {
  *  falling back to startedAt, descending). Shared by the md reader and
  *  mergeDelegationSources. */
 export function compareDelegationEntries(a: DelegationEntry, b: DelegationEntry): number {
-  const aRun = a.state === 'running' ? 1 : 0
-  const bRun = b.state === 'running' ? 1 : 0
+  const aRun = a.state === 'running' || a.state === 'stale-running' ? 1 : 0
+  const bRun = b.state === 'running' || b.state === 'stale-running' ? 1 : 0
   if (aRun !== bRun) return bRun - aRun
   return (b.updatedAt ?? b.startedAt) - (a.updatedAt ?? a.startedAt)
 }
@@ -1184,12 +1193,45 @@ export function compareDelegationEntries(a: DelegationEntry, b: DelegationEntry)
 export function visibleDelegationList(
   all: readonly DelegationEntry[],
   maxTerminal = 8,
+  now = Date.now(),
+  staleThresholdMs = 30 * 60 * 1000, // 30 minutes
 ): DelegationEntry[] {
-  const running = all.filter((d) => d.state === 'running')
+  const running = all
+    .filter((d) => d.state === 'running')
+    .map((d) => markStaleIfRunning(d, now, staleThresholdMs))
   const terminal = all.filter((d) => d.state !== 'running').slice(0, maxTerminal)
   return [...running, ...terminal]
 }
 
+/** Default stale-running threshold: 30 minutes. */
+export const STALE_RUNNING_THRESHOLD_MS = 30 * 60 * 1000
+
+/** Idle silence window: if no updatedAt change in this window, the entry is
+ *  considered stale. Combined with the stale-running threshold to produce the
+ *  display-only `stale-running` state. */
+export const IDLE_SILENCE_MS = 60 * 1000
+
+/**
+ * Mark a running entry as `stale-running` if it has been running longer than
+ * the threshold AND has no recent activity (no `updatedAt` change in the last
+ * `IDLE_SILENCE_MS`). This is DISPLAY-ONLY — the board state is unchanged.
+ *
+ * A `stale-running` entry renders with a warning indicator but the underlying
+ * delegation is still treated as running by the backend.
+ */
+export function markStaleIfRunning(
+  entry: DelegationEntry,
+  now: number,
+  thresholdMs = STALE_RUNNING_THRESHOLD_MS,
+): DelegationEntry {
+  if (entry.state !== 'running') return entry
+  const elapsed = now - entry.startedAt
+  if (elapsed < thresholdMs) return entry
+  // If updatedAt exists and is recent, entry is still active — not stale.
+  if (entry.updatedAt !== null && now - entry.updatedAt < IDLE_SILENCE_MS) return entry
+  return { ...entry, state: 'stale-running' as const }
+}
+
 /** Compact elapsed-time label: "5m 12s", "1h 30m", "2d 4h" — ticks every
  *  second for running jobs. */
 export function fmtElapsed(ms: number): string {
@@ -1207,7 +1249,8 @@ export function fmtElapsed(ms: number): string {
 /** Elapsed label for one entry: running → ticks `now - startedAt`, terminal
  *  → fixed `updatedAt - startedAt` (em dash when no finalized timestamp). */
 export function delegationElapsed(entry: DelegationEntry, now: number): string {
-  if (entry.state === 'running') return fmtElapsed(now - entry.startedAt)
+  if (entry.state === 'running' || entry.state === 'stale-running')
+    return fmtElapsed(now - entry.startedAt)
   return entry.updatedAt !== null ? fmtElapsed(entry.updatedAt - entry.startedAt) : '\u2014'
 }
 
@@ -1874,7 +1917,9 @@ export function childrenToDelegationEntries(
       agent: mdEntry?.agent ?? child.agent ?? 'agent',
       state,
       startedAt: mdEntry?.startedAt ?? child.time?.created ?? now,
-      updatedAt: mdEntry?.updatedAt ?? (state === 'running' ? null : (child.time?.updated ?? null)),
+      updatedAt:
+        mdEntry?.updatedAt ??
+        (state === 'running' || state === 'stale-running' ? null : (child.time?.updated ?? null)),
       timedOut: mdEntry?.timedOut ?? false,
       description:
         mdEntry !== undefined && mdEntry.description !== ''
@@ -2008,6 +2053,8 @@ function DelegationRow(props: {
     switch (props.job.state) {
       case 'running':
         return t.warning
+      case 'stale-running':
+        return t.error // warning color for stale delegations
       case 'completed':
         return t.success
       case 'error':
@@ -2019,6 +2066,7 @@ function DelegationRow(props: {
 
   const marker = createMemo(() => {
     if (props.job.state === 'running') return `${delegationSpinnerFrame(props.animationNow)} `
+    if (props.job.state === 'stale-running') return '\u26a0 ' // warning triangle
     switch (props.job.state) {
       case 'completed':
         return '\u2713 '