pantheon-opencode 1.3.3 → 1.3.5-beta.52.c75b04d

package/src/pantheon/plugin-once.ts

@@ -0,0 +1,76 @@
+/**
+ * Runtime double-registration guard for the Pantheon opencode plugins.
+ *
+ * PROBLEM (2026-08-12, live logs — duplicate toasts + duplicate task_ids in
+ * ONE process): opencode MERGES the global `~/.config/opencode/opencode.json`
+ * (which points at the INSTALLED npm package's plugin paths) with the project
+ * `opencode.json` (which points at the REPO source paths). Both list the SAME
+ * two plugins — `src/plugin.ts` and `src/plugins/pantheon-hooks.ts` — so each
+ * module is LOADED TWICE from two different filesystem paths in the same
+ * process. Each load is a separate module instance with its own module scope;
+ * the plugin factory then runs twice, registering every hook twice (duplicate
+ * toasts, duplicate delegation correlation, duplicated tool registrations).
+ *
+ * FIX: claim a stable per-plugin key on a process-global Set
+ * (`globalThis.__pantheonPluginsLoaded`). The second factory invocation sees
+ * its key already claimed and returns an empty hooks object — a no-op — so
+ * hooks register exactly once. The guard is PROCESS-global BY DESIGN: only a
+ * shared global can dedupe two separate module instances.
+ *
+ * Fail-safe: access to globalThis is wrapped — if the runtime ever lacks it
+ * (never in bun/node), the helper returns false and the plugin always runs
+ * (double registration returns, but the plugin never breaks startup).
+ *
+ * TEST ESCAPE HATCH: set PANTHEON_PLUGIN_ONCE=off to disable the guard. The
+ * multi-phase regression suites (pantheon-hooks-chat.test.mjs,
+ * plugin-log-policy.test.mjs) deliberately invoke the hooks factory once per
+ * phase in the SAME process via cache-busted imports, and the process-global
+ * guard would turn every phase after the first into a no-op. Production
+ * never sets this — the guard stays active and dedupes the npm-package +
+ * repo double load.
+ *
+ * USAGE — at the TOP of the plugin factory:
+ *
+ *   const plugin: Plugin = async (input: PluginInput) => {
+ *     if (pantheonPluginOnce('pantheon:plugin')) return {}
+ *     ... // full factory body — runs exactly once per process
+ *   }
+ *
+ * NOTE: this module is imported (never re-exported) by the plugin modules —
+ * the opencode legacy loader invokes every FUNCTION-valued export of a plugin
+ * module as a plugin factory, so helpers must live in a separate module.
+ */
+const GLOBAL_KEY = '__pantheonPluginsLoaded'
+
+/** Read (or lazily create) the shared guard Set. Null on any failure. */
+function guardSet(): Set<string> | null {
+  try {
+    const g = globalThis as Record<string, unknown>
+    if (g[GLOBAL_KEY] === undefined) {
+      g[GLOBAL_KEY] = new Set<string>()
+    }
+    const set = g[GLOBAL_KEY]
+    return set instanceof Set ? (set as Set<string>) : null
+  } catch {
+    return null // fail-open: no globalThis support — see header
+  }
+}
+
+/**
+ * Claim `key` for this process. Returns TRUE when the key was ALREADY claimed
+ * by another module instance — the caller MUST become a no-op (return an
+ * empty hooks object). Returns FALSE on the FIRST claim — the caller runs its
+ * full factory body. Fail-open: without globalThis support every call returns
+ * false, so the plugin always runs (never breaks startup).
+ */
+export function pantheonPluginOnce(key: string): boolean {
+  // Test escape hatch (see header): the multi-phase regression suites invoke
+  // the factory once per phase in one process — the dedup must not apply.
+  // Production never sets it, so the npm+repo double load stays deduped.
+  if (process.env.PANTHEON_PLUGIN_ONCE === 'off') return false
+  const set = guardSet()
+  if (set === null) return false
+  if (set.has(key)) return true
+  set.add(key)
+  return false
+}

package/src/pantheon/preemptive-compact.ts

@@ -0,0 +1,76 @@
+/**
+ * Preemptive Compaction Check (release-134 Phase 5) — dormant, ready-to-wire.
+ *
+ * WHY: the SDK 1.18.x exposes NO runtime source of context-usage percentage,
+ * so there is nothing to observe at runtime yet. This module is the pure
+ * decision core that warns the model BEFORE the context fills up — ready to
+ * be wired to a future usage source, but deliberately NOT wired today.
+ *
+ * HOW: `preemptiveCompactCheck` is a pure function: given the current usage
+ * fraction and the last fraction at which a warning was emitted, it decides
+ * whether to warn again (threshold + re-warn step) and returns the effective
+ * `lastWarnedPct`. The `enqueue` callback is INJECTED by the caller — this
+ * module stays standalone and does NOT import the shared chat-reminders
+ * buffer.
+ *
+ * YAGNI: no background timers, no polling, no plugin wiring. When (if) the
+ * SDK exposes a usage source, the caller wires it into this check.
+ *
+ * FAIL-OPEN: the whole check is wrapped — an enqueue failure returns the
+ * previous state and never throws.
+ *
+ * @module preemptive-compact
+ */
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/** Warn when context usage reaches this fraction (78%). */
+export const PREEMPTIVE_COMPACTION_THRESHOLD = 0.78
+
+/** Re-warn only when usage rose at least this much since the last warning (5pp). */
+export const PREEMPTIVE_REWARN_STEP = 0.05
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Dependencies threaded to preemptiveCompactCheck (wired from plugin.ts). */
+export interface PreemptiveCompactDeps {
+  /** The session whose context usage is being checked. */
+  sessionID: string
+  /** Current context usage as a fraction (0..1). */
+  usagePct: number
+  /** Last fraction at which a warning was emitted (undefined = never). */
+  lastWarnedPct: number | undefined
+  /** Injectable enqueue (testable). The module stays standalone. */
+  enqueue: (text: string) => void
+}
+
+// ─── Decision ──────────────────────────────────────────────────────────
+
+/**
+ * Pure decision: should a warning be emitted at the given usage?
+ * True when usage is at/above the threshold AND either no warning was
+ * emitted yet or usage rose by at least the re-warn step since the last one.
+ */
+export function shouldWarn(usagePct: number, lastWarnedPct: number | undefined): boolean {
+  if (usagePct < PREEMPTIVE_COMPACTION_THRESHOLD) return false
+  if (lastWarnedPct === undefined) return true
+  return usagePct >= lastWarnedPct + PREEMPTIVE_REWARN_STEP
+}
+
+/**
+ * Preemptive compaction check: when a warning should fire, enqueue the
+ * reminder and return the usage fraction as the new `lastWarnedPct`.
+ * Otherwise (or on any failure) return the previous `lastWarnedPct`.
+ * NEVER throws — the hook must never break the session.
+ */
+export function preemptiveCompactCheck(deps: PreemptiveCompactDeps): number | undefined {
+  try {
+    if (!shouldWarn(deps.usagePct, deps.lastWarnedPct)) return deps.lastWarnedPct
+    deps.enqueue(
+      `context usage at ${Math.round(deps.usagePct * 100)}% — consider compacting before continuing`,
+    )
+    return deps.usagePct
+  } catch {
+    return deps.lastWarnedPct
+  }
+}

package/src/pantheon/presets.d.mts

@@ -84,6 +84,20 @@ export declare function visionBrokenOnGateway(model: string, providerID: string)
 
 export declare function loadPresetDefs(routingPath?: string): Record<string, PresetDef>
 
+export interface RoutingAgentModelsOptions {
+  routingPath?: string
+  logger?: { warn?: (msg: string) => void }
+}
+
+/**
+ * Lowercase agent → "provider/model" mapping from routing.yml's FIRST
+ * (default) preset — the static source for the delegation toolset's
+ * options.agentModels. Fail-open: missing/corrupt routing.yml → {}.
+ */
+export declare function loadRoutingAgentModels(
+  options?: RoutingAgentModelsOptions,
+): Record<string, string>
+
 export declare function resolveActivePreset(options?: ResolveOptions): ResolvedPreset | null
 
 export declare function applyActivePresetToConfig<C extends object>(
@@ -91,6 +105,23 @@ export declare function applyActivePresetToConfig<C extends object>(
   options?: ResolveOptions & { env?: Record<string, string | undefined> },
 ): ResolvedPreset | null
 
+export interface ProviderKeyOptions {
+  env?: Record<string, string | undefined>
+  routingPath?: string
+}
+
+/** Name of the env var whose value is missing for a provider, or undefined when usable. */
+export declare function missingProviderKeyEnv(
+  providerID: string,
+  options?: ProviderKeyOptions,
+): string | undefined
+
+/** Whether the provider's API key is configured (apiKeyEnv set + non-empty, or no gate). */
+export declare function providerKeyConfigured(
+  providerID: string,
+  options?: ProviderKeyOptions,
+): boolean
+
 export interface MissingApiKeyError extends Error {
   code: 'PANTHEON_MISSING_API_KEY'
   envVar: string

package/src/pantheon/presets.mjs

@@ -210,6 +210,49 @@ export function loadPresetDefs(routingPath) {
   return (routing && typeof routing === 'object' && routing.presets) || {}
 }
 
+/**
+ * Load the DEFAULT agent → model mapping from routing.yml for the delegation
+ * toolset (Fase 6 — wiring agentModels).
+ *
+ * routing.yml keeps per-agent models ONLY inside presets
+ * (`presets.<name>.agents.<agent>.model`) — the top-level `agents:` section
+ * carries no model field. The FIRST-listed preset is the static default
+ * (go-deepseek today): a mapping INDEPENDENT of the active preset, so a
+ * delegated child always gets a sane per-agent model even when no preset is
+ * active — delegation no longer depends 100% on the active preset (branch (b)
+ * of resolveChildModel, which outranks the active-preset branch (c)).
+ *
+ * Fail-open: a missing or unparseable routing.yml yields {} (the caller keeps
+ * the previous behavior — active preset / opencode default) and warns via the
+ * optional logger; it NEVER throws at startup.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.routingPath]
+ * @param {{warn?: Function}} [opts.logger]
+ * @returns {Record<string, string>} lowercase agent → "provider/model"
+ */
+export function loadRoutingAgentModels({ routingPath, logger = console } = {}) {
+  let defs
+  try {
+    defs = loadPresetDefs(routingPath)
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    logger.warn?.(
+      `presets: routing.yml agent models unavailable (${reason}) — delegation falls back to the active preset/default`,
+    )
+    return {}
+  }
+  const names = Object.keys(defs)
+  if (names.length === 0) return {}
+  const models = {}
+  for (const [agent, spec] of Object.entries(defs[names[0]]?.agents ?? {})) {
+    if (spec && typeof spec === 'object' && typeof spec.model === 'string' && spec.model !== '') {
+      models[agent.toLowerCase()] = spec.model
+    }
+  }
+  return models
+}
+
 /**
  * Resolve the active preset: env PANTHEON_MODEL_PRESET > first existing
  * candidate file > null. "none" disables. Unknown names warn and return null
@@ -326,6 +369,66 @@ function buildResolved(defs, name, source, rawFile) {
   return { name, source, agents, providers, overrides, vision }
 }
 
+/**
+ * Whether a single provider DEF has its API key configured: no apiKeyEnv
+ * (native provider, no external key gate) → always configured; otherwise the
+ * env var must be set and non-empty. Shared by applyPreset (startup config
+ * path) and providerKeyConfigured / missingProviderKeyEnv (delegate dispatch).
+ *
+ * @param {object|null|undefined} provider provider def ({baseURL, apiKeyEnv})
+ * @param {Record<string, string|undefined>} env
+ * @returns {boolean}
+ */
+function providerDefKeyConfigured(provider, env) {
+  if (!provider || typeof provider !== 'object') return true
+  const envVar = provider.apiKeyEnv
+  if (typeof envVar !== 'string' || envVar === '') return true
+  const key = env[envVar]
+  return typeof key === 'string' && key.trim() !== ''
+}
+
+/**
+ * Name of the env var whose value is missing for a provider, or undefined
+ * when the provider is usable. A provider is usable when it declares no
+ * apiKeyEnv (native providers like opencode Zen) or its apiKeyEnv env var is
+ * set and non-empty. Provider defs come from routing.yml preset definitions —
+ * the SAME source applyPreset enforces at startup, so the delegate dispatch
+ * path and the config path can never disagree.
+ *
+ * @param {string} providerID e.g. 'openai' | 'opencode' | 'opencode-go'
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts.env]
+ * @param {string} [opts.routingPath]
+ * @returns {string|undefined} missing env var name, or undefined when usable
+ */
+export function missingProviderKeyEnv(providerID, { env = process.env, routingPath } = {}) {
+  const defs = loadPresetDefs(routingPath)
+  for (const def of Object.values(defs)) {
+    const provider = def?.providers?.[providerID]
+    if (provider === undefined) continue
+    if (providerDefKeyConfigured(provider, env)) return undefined
+    return provider.apiKeyEnv
+  }
+  // Provider not declared in any preset → no external key gate (opencode
+  // manages its own auth) → usable.
+  return undefined
+}
+
+/**
+ * Whether the given provider's API key is configured (see
+ * missingProviderKeyEnv). Convenience boolean for callers that only need the
+ * yes/no answer.
+ *
+ * @param {string} providerID
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts.env]
+ * @param {string} [opts.routingPath]
+ * @returns {boolean}
+ */
+export function providerKeyConfigured(providerID, opts) {
+  return missingProviderKeyEnv(providerID, opts) === undefined
+}
+
 /**
  * Apply a resolved preset to an opencode config object (mutates `config`).
  * - Providers: config.provider[id].options.baseURL + apiKey (env-gated).
@@ -339,8 +442,7 @@ export function applyPreset(config, resolved, { env = process.env } = {}) {
   if (!resolved) return config
 
   for (const [id, provider] of Object.entries(resolved.providers ?? {})) {
-    const apiKey = env[provider.apiKeyEnv]
-    if (!apiKey) {
+    if (!providerDefKeyConfigured(provider, env)) {
       const err = new Error(`presets: provider "${id}" requires env var ${provider.apiKeyEnv}`)
       err.code = 'PANTHEON_MISSING_API_KEY'
       err.envVar = provider.apiKeyEnv
@@ -350,7 +452,7 @@ export function applyPreset(config, resolved, { env = process.env } = {}) {
     config.provider[id] ??= {}
     config.provider[id].options ??= {}
     config.provider[id].options.baseURL = provider.baseURL
-    config.provider[id].options.apiKey = apiKey
+    config.provider[id].options.apiKey = env[provider.apiKeyEnv]
   }
 
   for (const [agent, spec] of Object.entries(resolved.agents ?? {})) {

package/src/pantheon/todo-enforcer.ts

@@ -13,11 +13,17 @@
  *      `userActivityQuietMs` is being driven interactively → skip;
  *   2. board-running — a session with a running background job is skipped
  *      (the parent is busy; the child session itself is never routed here);
- *   3. native-children — opencode `task(background=true)` children are NOT on
- *      our board, so `session.children()` is checked: an active child (its
- *      `time.updated` newer than `childActiveMs`) means the parent is still
- *      waiting on a native background task → skip. Throws fail open (log +
- *      inject) so version-sensitive APIs never break the enforcer;
+ *   3. children — `session.children()` is checked: a delegated child's
+ *      session ID IS its board task ID, so `board.get(child.id)` resolves
+ *      and the board state machine is authoritative — the child is active
+ *      ONLY while the job is `running`; terminal jobs (completed/error/
+ *      cancelled/reconciled) never suppress. Native children (opencode
+ *      `task(background=true)`, NOT on our board) fall back to the
+ *      `time.updated` heuristic (`childActiveMs`). The cross-ref fixes the
+ *      T6 bug: a completed delegation's frozen `time.updated` looked "still
+ *      running" for `childActiveMs` and suppressed every injection in that
+ *      window. Throws fail open (log + inject) so version-sensitive APIs
+ *      never break the enforcer;
  *   4. in-flight — one injection per idle, never concurrent;
  *   5. cooldown — exponential per-session backoff `cooldownBaseMs *
  *      2^min(failures, max)`, failures increment when an injection does not
@@ -42,6 +48,12 @@
  */
 
 import type { BackgroundJobBoard } from './background-job-board.ts'
+import { createPantheonLogger } from './logger.ts'
+
+// Silence-by-default TUI policy (pantheon-hooks L42-58): the default warn
+// fallback logs to .pantheon/logs/hooks.log; console echo is opt-in via
+// PANTHEON_HOOKS_LOG=1. `deps.logger` injection stays for tests.
+const log = createPantheonLogger({ module: 'pantheon-todo' })
 
 // ─── Constants ─────────────────────────────────────────────────────────
 
@@ -49,8 +61,7 @@ import type { BackgroundJobBoard } from './background-job-board.ts'
  * Version-controlled continuation text injected into the idle session.
  * Exported for tests and so the routing.yml comment stays in sync.
  */
-export const TODO_CONTINUATION_PROMPT =
-  'Incomplete tasks remain in your todo list. Continue working on them. Do not stop until all are done. If you believe all work is complete, critically re-examine whether the completion claim is verifiable.'
+export const TODO_CONTINUATION_PROMPT = 'Continue: pending todos remain — review and proceed.'
 
 /** Defaults matching routing.yml `todo_enforcer`. */
 export const TODO_ENFORCER_DEFAULTS = {
@@ -60,7 +71,7 @@ export const TODO_ENFORCER_DEFAULTS = {
   failureResetMs: 300000,
   /** Skip injection this long after a user message in the session. */
   userActivityQuietMs: 30000,
-  /** A native child whose `time.updated` is newer than this is still running. */
+  /** A native (non-board) child whose `time.updated` is newer than this is still running. */
   childActiveMs: 120000,
 } as const
 
@@ -140,16 +151,16 @@ export interface TodoEnforcerOptions {
   failureResetMs?: number
   /** Skip injection while a user message is more recent than this. */
   userActivityQuietMs?: number
-  /** Native child sessions newer than this are considered active/running. */
+  /** Native (non-board) child sessions newer than this are considered active/running. */
   childActiveMs?: number
   /** Injectable clock (testable), defaults to `Date.now`. */
   now?: () => number
 }
 
-/** Dependencies threaded to the enforcer (structural board — list only). */
+/** Dependencies threaded to the enforcer (structural board — list + get). */
 export interface TodoEnforcerDeps {
   client: TodoEnforcerClient
-  board: Pick<BackgroundJobBoard, 'list'>
+  board: Pick<BackgroundJobBoard, 'list' | 'get'>
   options?: TodoEnforcerOptions
   logger?: { warn: (message: string) => void }
 }
@@ -170,7 +181,7 @@ type InheritedContext = {
  */
 export class TodoEnforcer {
   private readonly client: TodoEnforcerClient
-  private readonly board: Pick<BackgroundJobBoard, 'list'>
+  private readonly board: Pick<BackgroundJobBoard, 'list' | 'get'>
   private readonly options: Required<TodoEnforcerOptions>
   private readonly warn: (message: string) => void
 
@@ -201,8 +212,7 @@ export class TodoEnforcer {
       childActiveMs: opts.childActiveMs ?? TODO_ENFORCER_DEFAULTS.childActiveMs,
       now: opts.now ?? Date.now,
     }
-    this.warn =
-      deps.logger?.warn ?? ((message: string) => console.warn(`[pantheon-todo] ${message}`))
+    this.warn = deps.logger?.warn ?? ((message: string) => log.warn(message))
   }
 
   /**
@@ -214,6 +224,25 @@ export class TodoEnforcer {
     this.lastUserMessageAt.set(sessionID, this.options.now())
   }
 
+  /**
+   * List the session's PENDING todos (not completed/cancelled) — the same
+   * incomplete filter as the idle continuation, exposed for the compaction
+   * context builder. Returns [] when the enforcer is disabled or the todo
+   * API fails (fail-open: the compaction hook must never break the
+   * session).
+   */
+  async listPendingTodos(sessionID: string): Promise<TodoLike[]> {
+    if (!this.options.enabled) return []
+    try {
+      const todos = await this.client.session.todo({ path: { id: sessionID } })
+      return todos.filter((todo) => todo.status !== 'completed' && todo.status !== 'cancelled')
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      this.warn(`todo list failed for session ${sessionID}: ${reason}`)
+      return []
+    }
+  }
+
   /**
    * Handle a `session.idle` event for a non-board session. Evaluates the
    * previous injection's outcome, applies the guards, and injects the
@@ -245,8 +274,10 @@ export class TodoEnforcer {
     // Guard 2: a session with a running board job is busy — skip.
     if (this.board.list(sessionID).some((job) => job.state === 'running')) return
 
-    // Guard 3: native background task() children are NOT on our board — an
-    // active child means the parent is still waiting on it, so skip.
+    // Guard 3: children — a delegated child (session ID == board task ID) is
+    // active only while its job is `running`; a native child is active while
+    // its time.updated is fresh. Either active child means the parent is
+    // still waiting on it, so skip.
     if ((await this.activeChildren(sessionID, now)) > 0) return
 
     const todos = await this.client.session.todo({ path: { id: sessionID } })
@@ -317,21 +348,29 @@ export class TodoEnforcer {
   }
 
   /**
-   * Count active native child sessions. opencode `task(background=true)`
-   * children are NOT registered on our board, so the only way to see them is
-   * `session.children()`. A child is active while its `time.updated` is newer
-   * than `childActiveMs` — a running background task keeps updating its
-   * session while streaming; a completed one freezes. Fail-open: when the
-   * children API is unavailable (older opencode / permission), log and return
-   * 0 so the enforcer still works on version-sensitive runtimes.
+   * Count active child sessions. Children fall into two classes:
+   *
+   *  - BOARD children (delegated via the toolset): the child session ID IS
+   *    the board task ID, so `board.get(child.id)` resolves. The board state
+   *    machine is authoritative — active ONLY while `state === 'running'`;
+   *    a terminal job (completed/error/cancelled/reconciled) is NOT active,
+   *    even though its `time.updated` froze at completion (the frozen
+   *    timestamp is exactly the T6 bug that made a finished delegation look
+   *    "still running" for `childActiveMs`).
+   *  - NATIVE children (opencode `task(background=true)`, NOT on our board):
+   *    `board.get(child.id)` is undefined, so the heuristic applies — active
+   *    while its `time.updated` is newer than `childActiveMs` (a running
+   *    native task keeps updating its session while streaming; a completed
+   *    one freezes).
+   *
+   * Fail-open: when the children API is unavailable (older opencode /
+   * permission), log and return 0 so the enforcer still works on
+   * version-sensitive runtimes.
    */
   private async activeChildren(sessionID: string, now: number): Promise<number> {
     try {
       const children = await this.client.session.children({ path: { id: sessionID } })
-      return children.filter((child) => {
-        const updated = child.time?.updated
-        return typeof updated === 'number' && now - updated < this.options.childActiveMs
-      }).length
+      return children.filter((child) => this.isChildActive(child, now)).length
     } catch (err: unknown) {
       const reason = err instanceof Error ? err.message : String(err)
       this.warn(`todo children check failed for session ${sessionID}: ${reason}`)
@@ -339,6 +378,19 @@ export class TodoEnforcer {
     }
   }
 
+  /**
+   * Whether a single child counts as active. Board children (the child's
+   * session ID matches a board task ID) are active only while the job is
+   * `running` — terminal board states never suppress. Native children
+   * (no board job) use the `time.updated` freshness heuristic.
+   */
+  private isChildActive(child: TodoEnforcerChild, now: number): boolean {
+    const job = this.board.get(child.id)
+    if (job !== undefined) return job.state === 'running'
+    const updated = child.time?.updated
+    return typeof updated === 'number' && now - updated < this.options.childActiveMs
+  }
+
   /**
    * Inherit the agent (or model) from the LAST assistant message so the
    * continuation runs in the same context as the session's last turn. Returns