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

package/src/pantheon/delegate-manager.ts

@@ -31,6 +31,8 @@ import {
   type DelegationClient,
   readDelegationReport,
 } from './delegation-finalize.ts'
+import { createNativeProbe, type NativeProbeFn, type ProbeClient } from './native-probe.ts'
+import { classifyNativeResult, type NativeTaskStatus } from './native-task-status.ts'
 import {
   buildStopInstruction,
   cappedSummary,
@@ -66,6 +68,7 @@ export interface ManagerReceipt {
   id: string
   agent: string
   state: 'reconciled' | 'error'
+  status: NativeTaskStatus
   line: string
 }
 
@@ -102,10 +105,15 @@ export interface DelegateManagerOptions {
   keepCompleted?: number
   /** Per-agent step budgets (routing.yml max_steps). */
   stepCap?: StepCapTracker
+  /** Lazy capability probe, invoked once before the first native dispatch. */
+  nativeProbe?: NativeProbeFn
+  /** V1 client used by the lazy capability probe. */
+  probeClient?: ProbeClient
 }
 
 export interface DelegateManager {
   launch(args: LaunchArgs): Promise<ManagerReceipt>
+  ensureNativeAvailable(): Promise<NativeTaskStatus | undefined>
   read(idOrAlias: string): Promise<string>
   list(): Promise<string[]>
   recover(): Promise<void>
@@ -131,9 +139,29 @@ export function resolveDelegateMode(
 
 const LINE_MAX = 160
 
+/** Remove terminal escapes and control characters from untrusted child output. */
+export function sanitizeReceiptText(text: string): string {
+  let clean = ''
+  let skippingAnsi = false
+  for (const char of text) {
+    const code = char.charCodeAt(0)
+    if (skippingAnsi) {
+      if (code === 0x5b) continue
+      if (code >= 0x40 && code <= 0x7e) skippingAnsi = false
+      continue
+    }
+    if (code === 0x1b) {
+      skippingAnsi = true
+      continue
+    }
+    if (char === '\n' || char === '\t' || (code >= 0x20 && code <= 0x7e)) clean += char
+  }
+  return clean
+}
+
 function firstLine(text: string, max = 80): string {
   const line =
-    (text ?? '')
+    sanitizeReceiptText(text ?? '')
       .split('\n')
       .map((l) => l.trim())
       .find((l) => l !== '') ?? ''
@@ -182,21 +210,30 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     task,
     parentSessionID,
     env = process.env,
-    models = [],
+    models: modelsOpt = [],
     timeoutMs = 120_000,
     readTimeoutMs = 60_000,
-    foregroundFallback = true,
+    foregroundFallback: fgFallbackOpt = true,
     maxEntries = 50,
     keepCompleted = 10,
     stepCap,
+    nativeProbe,
+    probeClient,
   } = options
 
+  // Strict native mode: foregroundFallback and models are overridden.
+  // The user-facing options are ignored when PANTHEON_DELEGATE_MODE=native.
+  const isNativeMode = resolveDelegateMode(env) === 'native'
+  const foregroundFallback = isNativeMode ? false : fgFallbackOpt
+  const models = isNativeMode ? [] : modelsOpt
+
   // Synchronous in-flight reservations per agent: launch() must decide
   // background vs foreground BEFORE its first await, otherwise concurrent
   // launches without interleaved awaits would all see an empty board.
   const pendingByAgent = new Map<string, number>()
   let seq = 0
   const foregroundRecent: { agent: string; line: string; at: number }[] = []
+  let probeResult: Awaited<ReturnType<NativeProbeFn>> | null = null
 
   function pending(agent: string): number {
     return pendingByAgent.get(agent.toLowerCase()) ?? 0
@@ -208,6 +245,12 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     }
   }
 
+  async function ensureNativeAvailable(): Promise<NativeTaskStatus | undefined> {
+    if (!isNativeMode || nativeProbe === undefined || probeClient === undefined) return undefined
+    probeResult ??= await nativeProbe({ client: probeClient, parentSessionID })
+    return probeResult.status === 'AVAILABLE' ? undefined : probeResult.status
+  }
+
   async function runTask(
     agent: string,
     prompt: string,
@@ -253,6 +296,7 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     // acknowledgment that the result was consumed.
     const terminalState = job.state
     const failed = verifyError !== undefined || terminalState === 'error'
+    const status = classifyNativeResult(job, verifyError)
     // Auto-reconcile + delete the signal file on the spot.
     if (job.state !== 'reconciled') await board.markReconciled(taskID)
     await board.deleteSignal(alias)
@@ -266,7 +310,7 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
           LINE_MAX,
         )
       : boardLine(settled ?? job)
-    return { id: taskID, agent: job.agent, state: failed ? 'error' : 'reconciled', line }
+    return { id: taskID, agent: job.agent, state: failed ? 'error' : 'reconciled', status, line }
   }
 
   /** Apply a terminal transition best-effort: a racing hook may have gotten there first. */
@@ -333,7 +377,33 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     )
     foregroundRecent.push({ agent: args.agent, line, at: Date.now() })
     if (foregroundRecent.length > 20) foregroundRecent.splice(0, foregroundRecent.length - 20)
-    return { id, agent: args.agent, state: ok ? 'reconciled' : 'error', line }
+    const status = classifyNativeResult(
+      {
+        taskID: id,
+        parentSessionID,
+        agent: args.agent,
+        description: args.description ?? firstLine(args.prompt, 120),
+        state: ok ? 'completed' : 'error',
+        timedOut: false,
+        alias: id,
+        launchedAt: Date.now(),
+        updatedAt: Date.now(),
+        totalErrors: 0,
+        timeoutCount: 0,
+        terminalUnreconciled: false,
+        contextFiles: [],
+        ...(ok
+          ? {
+              resultSummary: firstLine(
+                (outcome as { ok: true; result: NativeTaskResult }).result.content ?? '',
+                500,
+              ),
+            }
+          : {}),
+      },
+      ok ? undefined : (outcome as { ok: false; error?: string }).error,
+    )
+    return { id, agent: args.agent, state: ok ? 'reconciled' : 'error', status, line }
   }
 
   return {
@@ -346,13 +416,31 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
         const maxSteps = stepCap.maxStepsFor(args.agent)
         if (stepCap.isCapped(args.agent)) {
           const line = cappedSummary(args.agent, maxSteps ?? DEFAULT_MAX_STEPS).slice(0, LINE_MAX)
-          return { id: `cap-${Date.now()}`, agent: args.agent, state: 'reconciled', line }
+          return {
+            id: `cap-${Date.now()}`,
+            agent: args.agent,
+            state: 'reconciled',
+            status: 'ESCALATE',
+            line,
+          }
         }
         const rec = stepCap.recordStep(args.agent)
         if (rec.capped && rec.maxSteps !== undefined) {
           prompt = `${args.prompt}${buildStopInstruction(args.agent, rec.maxSteps)}`
         }
       }
+      if (isNativeMode) {
+        const unavailableStatus = await ensureNativeAvailable()
+        if (unavailableStatus !== undefined) {
+          return {
+            id: `probe-${parentSessionID}`,
+            agent: args.agent,
+            state: 'error',
+            status: unavailableStatus,
+            line: `[native] ${args.agent} — native API ${unavailableStatus.toLowerCase()} — ERR`,
+          }
+        }
+      }
       // Synchronous routing decision: background when a slot is free,
       // foreground fallback when full, clean rejection otherwise.
       const free =
@@ -363,6 +451,7 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
         `pantheon_delegate rejected: concurrency limit reached for agent "${args.agent}"`,
       )
     },
+    ensureNativeAvailable,
 
     async read(idOrAlias: string): Promise<string> {
       guardEnabled()
@@ -376,11 +465,11 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
       if (terminal.state !== 'reconciled') await board.markReconciled(terminal.taskID)
       await board.deleteSignal(terminal.alias)
       if (terminal.state === 'error' && !terminal.resultSummary) {
-        return `# Delegation Report — ${terminal.alias}\n\nERROR: ${terminal.lastStatusError ?? 'failed'}\n`
+        return `# Delegation Report — ${terminal.alias}\n\nERROR: ${sanitizeReceiptText(terminal.lastStatusError ?? 'failed')}\n`
       }
       return (
         `# Delegation Report — ${terminal.alias}\n\n` +
-        `${terminal.resultSummary ?? terminal.lastStatusError ?? terminal.state}\n`
+        `${sanitizeReceiptText(terminal.resultSummary ?? terminal.lastStatusError ?? terminal.state)}\n`
       )
     },
 
@@ -524,7 +613,7 @@ export interface NativeDelegateToolset {
 }
 function shortFirstLine(text: string, max = 60): string {
   const line =
-    text
+    sanitizeReceiptText(text)
       .split('\n')
       .map((item) => item.trim())
       .find(Boolean) ?? ''
@@ -555,6 +644,7 @@ export function createNativeDelegateTools(wiring: NativeDelegateWiring): NativeD
   const managerFor = (parentSessionID: string): DelegateManager => {
     const existing = managers.get(parentSessionID)
     if (existing !== undefined) return existing
+    const nativeProbe = createNativeProbe()
     const manager = createDelegateManager({
       ...managerOptions,
       board,
@@ -562,6 +652,8 @@ export function createNativeDelegateTools(wiring: NativeDelegateWiring): NativeD
       parentSessionID,
       env,
       ...(stepCap === undefined ? {} : { stepCap }),
+      nativeProbe,
+      probeClient: client,
     })
     managers.set(parentSessionID, manager)
     return manager
@@ -577,6 +669,11 @@ export function createNativeDelegateTools(wiring: NativeDelegateWiring): NativeD
           throw new Error(
             `pantheon_delegate rejected: session ${ctx.sessionID} is a sub-session — only root sessions can delegate`,
           )
+        const manager = managerFor(ctx.sessionID)
+        const unavailableStatus = await manager.ensureNativeAvailable()
+        if (unavailableStatus !== undefined) {
+          return `status: ${unavailableStatus}\n[native] ${args.agent} — native API ${unavailableStatus.toLowerCase()} — ERR`
+        }
         const model = args.model ?? agentModel?.(args.agent)
         let childID: string
         try {
@@ -590,7 +687,7 @@ export function createNativeDelegateTools(wiring: NativeDelegateWiring): NativeD
           })
           childID = created.id
         } catch (error) {
-          return `pantheon_delegate failed: session.create rejected: ${error instanceof Error ? error.message : String(error)}`
+          return `pantheon_delegate failed: session.create rejected: ${sanitizeReceiptText(error instanceof Error ? error.message : String(error))}`
         }
         registerChildSession?.(childID, ctx.sessionID)
         if (args.read_only === true || isReadOnlyAgent?.(args.agent) === true)
@@ -598,14 +695,14 @@ export function createNativeDelegateTools(wiring: NativeDelegateWiring): NativeD
             agent: args.agent,
             ...(args.read_only === undefined ? {} : { readOnlyFlag: args.read_only }),
           })
-        const receipt = await managerFor(ctx.sessionID).launch({
+        const receipt = await manager.launch({
           agent: args.agent,
           prompt: args.prompt,
           ...(args.description === undefined ? {} : { description: args.description }),
           ...(args.model === undefined ? {} : { model: args.model }),
           taskID: childID,
         })
-        return receipt.line
+        return `status: ${receipt.status}\n${receipt.line}`
       },
     },
     pantheon_delegation_read: {

package/src/pantheon/native-probe.ts

@@ -0,0 +1,234 @@
+/**
+ * Native Probe — lazy capability detection for native task() delegation.
+ *
+ * The probe is invoked on the FIRST native delegation of a session (not at
+ * startup). It creates a child session with a minimal "ping" prompt, waits
+ * for idle, and classifies the output.
+ *
+ * Results are cached per probe instance (singleton guard):
+ *   - UNAVAILABLE is TERMINAL — no retry.
+ *   - AVAILABLE is also cached — no re-probe.
+ *
+ * Uses the OpenCode V1 session API (session.create + promptAsync) injected via
+ * the parent context.
+ *
+ * @module native-probe
+ */
+
+import { createPantheonLogger } from './logger.ts'
+
+const log = createPantheonLogger({ module: 'native-probe' })
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Possible outcomes of a native capability probe. */
+export type NativeProbeResult = {
+  status: 'AVAILABLE' | 'UNAVAILABLE' | 'UNSUPPORTED'
+}
+
+/** Minimal V1 client shape needed by the probe (session.create + promptAsync). */
+export interface ProbeClient {
+  session: {
+    create: (input: { body: { parentID: string } }) => Promise<{ id: string }>
+    promptAsync: (input: {
+      path: { id: string }
+      body: { agent: string; parts: Array<{ type: 'text'; text: string }> }
+    }) => Promise<unknown>
+  }
+}
+
+/** Context injected into the probe function. */
+export interface NativeProbeContext {
+  client: ProbeClient
+  parentSessionID: string
+}
+
+/** Options for a single probe invocation. */
+export interface NativeProbeOptions {
+  /** Timeout in milliseconds. Default: 30000. */
+  timeoutMs?: number
+}
+
+/** The probe function signature. */
+export type NativeProbeFn = (
+  ctx: NativeProbeContext,
+  options?: NativeProbeOptions,
+) => Promise<NativeProbeResult>
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+/** Default timeout for the probe. */
+const DEFAULT_TIMEOUT_MS = 30_000
+
+/** Sentinel value indicating a timeout occurred. */
+const TIMEOUT_SENTINEL = Symbol('timeout')
+
+/**
+ * Wrap a promise with a timeout.
+ * Returns the value on success, throws the original error on rejection,
+ * or returns TIMEOUT_SENTINEL if the timeout fires first.
+ */
+async function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+): Promise<T | typeof TIMEOUT_SENTINEL> {
+  return new Promise<T | typeof TIMEOUT_SENTINEL>((resolve, reject) => {
+    const timer = setTimeout(() => resolve(TIMEOUT_SENTINEL), ms)
+    void promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (err: unknown) => {
+        clearTimeout(timer)
+        reject(err)
+      },
+    )
+  })
+}
+
+/**
+ * Extract text content from a promptAsync response.
+ * Returns empty string if no recognizable content found.
+ */
+function extractOutput(result: unknown): string {
+  if (result == null) return ''
+  if (typeof result === 'string') return result
+  if (typeof result === 'object') {
+    const obj = result as Record<string, unknown>
+    // Check common shapes: { output }, { content }, { text }
+    if (typeof obj.output === 'string') return obj.output
+    if (typeof obj.content === 'string') return obj.content
+    if (typeof obj.text === 'string') return obj.text
+  }
+  // Non-empty object → treat as content (accepted message, etc.)
+  if (typeof result === 'object' && result !== null) {
+    return 'acknowledged'
+  }
+  return ''
+}
+
+function isUnsupportedError(message: string): boolean {
+  const lower = message.toLowerCase()
+  return (
+    lower.includes('not available') ||
+    lower.includes('not supported') ||
+    lower.includes('unsupported') ||
+    lower.includes('method not found')
+  )
+}
+
+// ─── Implementation ────────────────────────────────────────────────────
+
+/**
+ * Create a native probe function with per-instance caching.
+ *
+ * The probe is LAZY: it does not run at startup. Call it on the first
+ * native delegation of the session. The result is cached — subsequent
+ * calls return the cached value without re-probing.
+ *
+ * @returns A probe function that caches results per instance.
+ */
+export function createNativeProbe(): NativeProbeFn {
+  let cachedResult: NativeProbeResult | null = null
+  let inFlight: Promise<NativeProbeResult> | null = null
+
+  return async (
+    ctx: NativeProbeContext,
+    options?: NativeProbeOptions,
+  ): Promise<NativeProbeResult> => {
+    // Return cached result if available (singleton guard)
+    if (cachedResult !== null) {
+      return cachedResult
+    }
+    // Concurrent first dispatches share one probe instead of creating multiple
+    // child sessions. The promise is cleared only after a terminal result.
+    if (inFlight !== null) return inFlight
+
+    inFlight = probe(ctx, options)
+    try {
+      return await inFlight
+    } finally {
+      inFlight = null
+    }
+  }
+
+  async function probe(
+    ctx: NativeProbeContext,
+    options?: NativeProbeOptions,
+  ): Promise<NativeProbeResult> {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+    // ── Phase 1: create child session ──────────────────────────────
+    let childID: string
+    try {
+      const createResult = await withTimeout(
+        ctx.client.session.create({ body: { parentID: ctx.parentSessionID } }),
+        timeoutMs,
+      )
+      if (createResult === TIMEOUT_SENTINEL) {
+        // Timeout during session.create → UNAVAILABLE
+        log.warn('[Native Probe] session.create timed out after', timeoutMs, 'ms')
+        const result: NativeProbeResult = { status: 'UNAVAILABLE' }
+        cachedResult = result
+        return result
+      }
+      childID = createResult.id
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err)
+      log.error('[Native Probe] session.create failed:', msg)
+      // Check for unsupported API patterns
+      if (isUnsupportedError(msg)) {
+        const result: NativeProbeResult = { status: 'UNSUPPORTED' }
+        cachedResult = result
+        return result
+      }
+      // Other creation failures → UNAVAILABLE
+      const result: NativeProbeResult = { status: 'UNAVAILABLE' }
+      cachedResult = result
+      return result
+    }
+
+    // ── Phase 2: send probe prompt ─────────────────────────────────
+    let promptResult: unknown
+    try {
+      const raw = await withTimeout(
+        ctx.client.session.promptAsync({
+          path: { id: childID },
+          body: { agent: 'probe', parts: [{ type: 'text', text: 'Reply with PONG.' }] },
+        }),
+        timeoutMs,
+      )
+      if (raw === TIMEOUT_SENTINEL) {
+        // Timeout during promptAsync → UNAVAILABLE
+        log.warn('[Native Probe] promptAsync timed out after', timeoutMs, 'ms')
+        const result: NativeProbeResult = { status: 'UNAVAILABLE' }
+        cachedResult = result
+        return result
+      }
+      promptResult = raw
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err)
+      log.error('[Native Probe] promptAsync failed:', msg)
+      if (isUnsupportedError(msg)) {
+        const result: NativeProbeResult = { status: 'UNSUPPORTED' }
+        cachedResult = result
+        return result
+      }
+      // promptAsync error → UNAVAILABLE
+      const result: NativeProbeResult = { status: 'UNAVAILABLE' }
+      cachedResult = result
+      return result
+    }
+
+    // ── Phase 3: classify output ───────────────────────────────────
+    const output = extractOutput(promptResult)
+    const hasContent = output.trim() !== ''
+
+    const result: NativeProbeResult = {
+      status: hasContent ? 'AVAILABLE' : 'UNAVAILABLE',
+    }
+    cachedResult = result
+    return result
+  }
+}

package/src/pantheon/native-task-status.ts

@@ -0,0 +1,139 @@
+/**
+ * Native Task Status — classifies BackgroundJobRecord results from native
+ * task() delegation into actionable status codes.
+ *
+ * Pure module — zero external dependencies. Consumed by native-probe.ts
+ * and the delegation manager to decide retry/skip/escalate strategy.
+ *
+ * @module native-task-status
+ */
+
+import type { BackgroundJobRecord } from './background-job-board.ts'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Actionable status for a native task() delegation result. */
+export type NativeTaskStatus =
+  | 'OK'
+  | 'UNSUPPORTED'
+  | 'UNAVAILABLE'
+  | 'INVALID_INPUT'
+  | 'INVALID_STATE'
+  | 'CONFLICT'
+  | 'CORRUPT_DATA'
+  | 'TIMEOUT'
+  | 'ESCALATE'
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+/** Check if a string contains any of the given substrings (case-insensitive). */
+function containsAny(text: string | undefined, patterns: readonly string[]): boolean {
+  if (text == null) return false
+  const lower = text.toLowerCase()
+  return patterns.some((p) => lower.includes(p.toLowerCase()))
+}
+
+/** Check if a job's output is empty or whitespace-only. */
+function isOutputEmpty(job: BackgroundJobRecord): boolean {
+  const summary = job.resultSummary
+  if (summary == null) return true
+  if (typeof summary !== 'string') return true
+  return summary.trim() === ''
+}
+
+// ─── Implementation ────────────────────────────────────────────────────
+
+/**
+ * Classify a BackgroundJobRecord result into a NativeTaskStatus.
+ *
+ * Priority order (first match wins):
+ * 1. verifyError and lastStatusError patterns → UNSUPPORTED, CONFLICT,
+ *    INVALID_INPUT, INVALID_STATE, CORRUPT_DATA, ESCALATE
+ * 2. state === startup_failed or timedOut → TIMEOUT
+ * 3. state === completed + non-empty output → OK
+ * 4. state === completed + empty output → UNAVAILABLE (silent failure / admission rejection)
+ * 5. state === error → UNAVAILABLE (safe default for provider/infra errors)
+ * 6. Fallback → UNAVAILABLE
+ */
+export function classifyNativeResult(
+  job: BackgroundJobRecord,
+  verifyError?: string,
+): NativeTaskStatus {
+  const statusError = [verifyError, job.lastStatusError]
+    .filter((value): value is string => value != null && value.length > 0)
+    .join(' ')
+
+  // A missing native task API is terminal and must not be retried or sent
+  // through a fallback model. Provider/transport failures remain unavailable.
+  if (
+    containsAny(statusError, [
+      'api unavailable',
+      'api not available',
+      'api missing',
+      'method not found',
+      'unknown method',
+      'not supported',
+      'unsupported',
+      'does not support',
+      'task() is not available',
+    ])
+  ) {
+    return 'UNSUPPORTED'
+  }
+
+  // ── Phase 1: verifyError explicit signals (highest priority) ───────
+
+  if (verifyError != null && verifyError.length > 0) {
+    // CONFLICT: canDispatch=false or concurrency exceeded
+    if (containsAny(verifyError, ['canDispatch', 'concurrency', 'conflict'])) {
+      return 'CONFLICT'
+    }
+
+    // INVALID_INPUT: agent not recognized / invalid
+    if (containsAny(verifyError, ['invalid agent', 'agent not found', 'unknown agent'])) {
+      return 'INVALID_INPUT'
+    }
+
+    // INVALID_STATE: child already in terminal state
+    if (containsAny(verifyError, ['already terminal', 'already in terminal', 'invalid state'])) {
+      return 'INVALID_STATE'
+    }
+
+    // CORRUPT_DATA: output can't be parsed / corrupted
+    if (containsAny(verifyError, ['corrupt', 'parse failed', 'malformed', 'invalid format'])) {
+      return 'CORRUPT_DATA'
+    }
+
+    // ESCALATE: unrecoverable failure
+    if (containsAny(verifyError, ['unrecoverable', 'fatal', 'max retries exceeded'])) {
+      return 'ESCALATE'
+    }
+  }
+
+  // ── Phase 2: state-based classification ────────────────────────────
+
+  // TIMEOUT: startup failure or timed out
+  if (job.state === 'startup_failed' || job.state === 'startup_unknown' || job.timedOut) {
+    return 'TIMEOUT'
+  }
+
+  // ── Phase 3: output-based classification ───────────────────────────
+
+  if (job.state === 'completed') {
+    if (!isOutputEmpty(job)) {
+      return 'OK'
+    }
+    // completed but empty → silent failure (BackendAdmissionRejected pattern)
+    return 'UNAVAILABLE'
+  }
+
+  // ── Phase 4: error state fallback ──────────────────────────────────
+
+  if (job.state === 'error') {
+    return 'UNAVAILABLE'
+  }
+
+  // ── Fallback ───────────────────────────────────────────────────────
+
+  return 'UNAVAILABLE'
+}

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
+}