pantheon-opencode 1.5.0-beta.1 → 1.5.0-beta.11

package/src/pantheon/file-persistence.ts

@@ -1,91 +1,238 @@
 /**
  * File-based persistence adapter for the BackgroundJobBoard.
  *
- * Stores all jobs in a single `state.json` file using atomic writes
- * (write to `state.json.tmp` then rename) to prevent partial writes
- * from crashes.
+ * Stores all jobs in a single `state.json` file. Writes are crash-safe:
+ * the payload is written to a UNIQUE temp file, fsynced, then renamed over
+ * the destination. Writes to the same path are serialized through an
+ * in-process queue so two logical writers (plugin × native) cannot
+ * interleave and corrupt the JSON or race the rename.
+ *
+ * Reads are corruption-tolerant: a malformed `state.json` is moved aside to
+ * `<state>.corrupt-<ts>`, a clear log is emitted, and whatever complete
+ * records can be salvaged from the array are returned — never a throw, so
+ * callers (delete/prune/recover) cannot get stuck in a retry loop.
  *
  * @module file-persistence
  */
 
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
-import { dirname } from 'node:path'
+import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
 
 import type { BackgroundJobRecord, PersistenceAdapter } from './background-job-board.ts'
+import { salvageRecords } from './file-persistence-salvage.ts'
+import { createPantheonLogger } from './logger.ts'
+
+export { salvageRecords } from './file-persistence-salvage.ts'
+
+const log = createPantheonLogger({ module: 'FilePersistence' })
 
 /** Default path for the state file. */
 const DEFAULT_STATE_PATH = '.pantheon/board/state.json'
 
+/** Max rename attempts after an ENOENT before giving up (dir/tmp recreated each try). */
+const RENAME_MAX_ATTEMPTS = 3
+
+/** Minimal file handle surface used to fsync the temp file before rename. */
+export interface PersistenceFileHandle {
+  writeFile(data: string, encoding: 'utf-8'): Promise<void>
+  sync(): Promise<void>
+  close(): Promise<void>
+}
+
+/**
+ * Filesystem operations used by the adapter. Injectable so tests can fault
+ * inject a failing `rename` (ENOENT) deterministically.
+ */
+export interface PersistenceFsOps {
+  mkdir(dir: string): Promise<void>
+  readFile(path: string, encoding: 'utf-8'): Promise<string>
+  rename(from: string, to: string): Promise<void>
+  openForWrite(path: string): Promise<PersistenceFileHandle>
+  unlink(path: string): Promise<void>
+}
+
+/** Real Node.js filesystem implementation (the default). */
+const defaultFsOps: PersistenceFsOps = {
+  mkdir: async (dir) => {
+    await mkdir(dir, { recursive: true })
+  },
+  readFile: (path, encoding) => readFile(path, encoding),
+  rename: (from, to) => rename(from, to),
+  openForWrite: (path) => open(path, 'w'),
+  unlink: (path) => unlink(path),
+}
+
+function isEnoent(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT'
+}
+
+/**
+ * In-process write queues keyed by absolute state path. Shared across
+ * adapter INSTANCES so a plugin adapter and a native adapter pointing at the
+ * same file serialize their read-modify-write cycles.
+ */
+const writeQueues = new Map<string, Promise<unknown>>()
+
+function enqueueWrite<T>(key: string, task: () => Promise<T>): Promise<T> {
+  const previous = writeQueues.get(key) ?? Promise.resolve()
+  const run = previous.then(task, task)
+  writeQueues.set(
+    key,
+    run.then(
+      () => undefined,
+      () => undefined,
+    ),
+  )
+  return run
+}
+
 /**
  * File-based persistence adapter.
  *
- * All jobs are stored in a single JSON array in `statePath`.
- * Writes are atomic: content is written to a `.tmp` file, then renamed.
- *
- * The board's in-memory `this.jobs` Map is the source of truth —
- * this file is a crash-recovery snapshot. `deleteJob()` removes the
- * record from the snapshot so pruned/reconciled jobs don't resurface
- * after a restart.
+ * All jobs are stored in a single JSON array in `statePath`. Writes are
+ * atomic and serialized (unique tmp + fsync + rename, with ENOENT retry).
+ * Corrupt state is backed up and salvaged instead of throwing.
  */
 export class FilePersistenceAdapter implements PersistenceAdapter {
   private readonly statePath: string
   private readonly dir: string
+  private readonly ops: PersistenceFsOps
+  private readonly lockKey: string
+  private tmpCounter = 0
 
   /**
    * @param statePath  Path to the state JSON file (default: `.pantheon/board/state.json`)
+   * @param ops        Filesystem operations (defaults to real Node.js fs; injectable for tests)
    */
-  constructor(statePath?: string) {
+  constructor(statePath?: string, ops: PersistenceFsOps = defaultFsOps) {
     this.statePath = statePath ?? DEFAULT_STATE_PATH
     this.dir = dirname(this.statePath)
+    this.ops = ops
+    this.lockKey = resolve(this.statePath)
   }
 
   /** Ensure the parent directory exists. */
   private async ensureDir(): Promise<void> {
-    await mkdir(this.dir, { recursive: true })
+    await this.ops.mkdir(this.dir)
   }
 
-  /** Path to the atomic-write temp file. */
-  private get tmpPath(): string {
-    return this.statePath + '.tmp'
+  /** Unique temp path per write — prevents two writers racing the same tmp. */
+  private makeTmpPath(): string {
+    this.tmpCounter += 1
+    const unique = `${process.pid}.${this.tmpCounter}.${Math.random().toString(36).slice(2, 8)}`
+    return `${this.statePath}.${unique}.tmp`
   }
 
   /**
    * Read all jobs from the state file.
-   * Returns `null` if the file doesn't exist (first run / no jobs yet).
+   *
+   * Return contract distinguishes three failure modes:
+   * - absent file (ENOENT) → `[]` (first run / no jobs yet);
+   * - corrupt content → quarantine + `salvageRecords()` (best-effort recovery);
+   * - non-ENOENT IO error (e.g. EIO) → `null`, signalling the read failed.
+   *
+   * Callers doing read-modify-write MUST abort on `null` so a failed read
+   * cannot overwrite the on-disk state with a partial snapshot.
    */
   private async readState(): Promise<BackgroundJobRecord[] | null> {
+    let content: string
     try {
-      const content = await readFile(this.statePath, 'utf-8')
-      return JSON.parse(content) as BackgroundJobRecord[]
+      content = await this.ops.readFile(this.statePath, 'utf-8')
     } catch (err: unknown) {
-      if (
-        err instanceof Error &&
-        'code' in err &&
-        (err as NodeJS.ErrnoException).code === 'ENOENT'
-      ) {
-        return null
+      if (isEnoent(err)) return []
+      log.error(`[FilePersistence] Failed to read ${this.statePath}:`, err)
+      return null
+    }
+
+    try {
+      const parsed: unknown = JSON.parse(content)
+      if (!Array.isArray(parsed)) {
+        throw new Error('state.json is not a JSON array')
       }
-      throw err
+      return parsed as BackgroundJobRecord[]
+    } catch (err: unknown) {
+      await this.quarantineCorrupt(err)
+      const salvaged = salvageRecords(content)
+      log.warn(
+        `[FilePersistence] Corrupt ${this.statePath} — recovered ${salvaged.length} record(s)`,
+      )
+      return salvaged
+    }
+  }
+
+  /** Move a corrupt state.json aside so the next write starts from a clean file. */
+  private async quarantineCorrupt(cause: unknown): Promise<void> {
+    const backupPath = `${this.statePath}.corrupt-${Date.now()}`
+    try {
+      await this.ops.rename(this.statePath, backupPath)
+      log.error(`[FilePersistence] Corrupt ${this.statePath} backed up to ${backupPath}:`, cause)
+    } catch (err: unknown) {
+      log.error(
+        `[FilePersistence] Could not back up corrupt ${this.statePath} — continuing with salvaged state:`,
+        err,
+      )
     }
   }
 
-  /** Write the full state array atomically (tmp + rename). */
+  /** Write the full state array: unique tmp + fsync + rename (with ENOENT retry). */
   private async writeState(records: BackgroundJobRecord[]): Promise<void> {
-    await this.ensureDir()
     const content = JSON.stringify(records, null, 2)
-    await writeFile(this.tmpPath, content, 'utf-8')
-    await rename(this.tmpPath, this.statePath)
+    const tmpPath = this.makeTmpPath()
+    let lastError: unknown
+
+    for (let attempt = 1; attempt <= RENAME_MAX_ATTEMPTS; attempt++) {
+      try {
+        await this.ensureDir()
+        const handle = await this.ops.openForWrite(tmpPath)
+        try {
+          await handle.writeFile(content, 'utf-8')
+          await handle.sync()
+        } finally {
+          await handle.close()
+        }
+        await this.ops.rename(tmpPath, this.statePath)
+        return
+      } catch (err: unknown) {
+        lastError = err
+        if (!isEnoent(err)) break
+        log.warn(
+          `[FilePersistence] rename ENOENT for ${this.statePath} ` +
+            `(attempt ${attempt}/${RENAME_MAX_ATTEMPTS}) — recreating dir and retrying`,
+        )
+        await this.safeUnlink(tmpPath)
+      }
+    }
+
+    await this.safeUnlink(tmpPath)
+    throw lastError instanceof Error ? lastError : new Error(String(lastError))
   }
 
-  async saveJob(record: BackgroundJobRecord): Promise<void> {
-    const records = (await this.readState()) ?? []
-    const idx = records.findIndex((r) => r.taskID === record.taskID)
-    if (idx >= 0) {
-      records[idx] = record
-    } else {
-      records.push(record)
+  private async safeUnlink(path: string): Promise<void> {
+    try {
+      await this.ops.unlink(path)
+    } catch {
+      // Best-effort temp cleanup — absent file is fine.
     }
-    await this.writeState(records)
+  }
+
+  async saveJob(record: BackgroundJobRecord): Promise<void> {
+    await enqueueWrite(this.lockKey, async () => {
+      const records = await this.readState()
+      if (records === null) {
+        log.error(
+          `[FilePersistence] Aborting saveJob(${record.taskID}): could not read ` +
+            `${this.statePath} — refusing to overwrite state with a partial snapshot`,
+        )
+        return
+      }
+      const idx = records.findIndex((r) => r.taskID === record.taskID)
+      if (idx >= 0) {
+        records[idx] = record
+      } else {
+        records.push(record)
+      }
+      await this.writeState(records)
+    })
   }
 
   async loadAllJobs(): Promise<BackgroundJobRecord[]> {
@@ -93,11 +240,13 @@ export class FilePersistenceAdapter implements PersistenceAdapter {
   }
 
   async deleteJob(taskID: string): Promise<void> {
-    const records = await this.readState()
-    if (!records) return
-    const idx = records.findIndex((r) => r.taskID === taskID)
-    if (idx < 0) return
-    records.splice(idx, 1)
-    await this.writeState(records)
+    await enqueueWrite(this.lockKey, async () => {
+      const records = await this.readState()
+      if (!records) return
+      const idx = records.findIndex((r) => r.taskID === taskID)
+      if (idx < 0) return
+      records.splice(idx, 1)
+      await this.writeState(records)
+    })
   }
 }

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