pantheon-opencode 1.5.0-beta.7 → 1.5.0-beta.8

package/CHANGELOG.md

@@ -18,6 +18,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.5.0-beta.8] - 2026-09-13
+
+<!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. -->
+
+## 🐞 Fixed
+
+- **Board persistence is corruption- and concurrency-safe:** state writes now go
+  through a UNIQUE temp file (per-process, per-write counter + random suffix), are
+  `fsync`ed, then renamed over the destination with bounded ENOENT retries, and
+  read-modify-write cycles on the same state path are serialized. This closes the
+  window where two writers could interleave and corrupt `state.json` or race the
+  rename.
+- **Corrupt board state is quarantined and salvaged:** a malformed `state.json` is
+  moved aside to `<state>.corrupt-<ts>`, a clear error is logged, and every complete
+  record that can be parsed is salvaged and returned instead of throwing — so
+  delete/prune/recover callers cannot get stuck in a retry loop.
+- **P1-1 — no orphan `.signal.json` on reconcile:** reconcile now deletes any
+  still-pending wake signal instead of re-writing it. Reconcile is an
+  acknowledgment, not a new terminal transition, so the finalize→reconcile cycle
+  no longer leaves a stale `<alias>.signal.json` with `state:"reconciled"` behind.
+- **Unresolved `{sessionID}` template guard:** the TUI/runtime can hand the plugin
+  the unsubstituted literal `{sessionID}` (or `%7BsessionID%7D`) when no session is
+  focused; the plugin now refuses placeholder session ids at the delegation,
+  bootstrap-probe, and activity-sample boundaries instead of forwarding them to the
+  session API (which rejected every call).
+- **Delegation lookup scoped to the calling session:** `pantheon_delegation_read`
+  resolves exact task IDs first (must belong to the caller's session), then alias
+  matches within that session (exactly one required). Cross-session and ambiguous
+  aliases now return explicit errors instead of the generic "Unknown delegation".
+
+
 ## [v1.5.0-beta.7] - 2026-09-13
 
 &lt;!-- Add new changes here. Running `node scripts/versioning.mjs apply` will

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.5.0-beta.7",
+  "version": "1.5.0-beta.8",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "publishConfig": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon",
   "publisher": "ils15",
-  "version": "1.5.0-beta.7",
+  "version": "1.5.0-beta.8",
   "displayName": "Pantheon",
   "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 21 skills, and OpenCode support.",
   "agents": "./src/agents",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
 
 [project]
 name = "pantheon"
-version = "1.5.0-beta.7"
+version = "1.5.0-beta.8"
 description = "Multi-agent orchestration framework"
 requires-python = ">=3.11"
 dependencies = []

package/src/pantheon/background-job-board.ts

@@ -457,7 +457,12 @@ export class BackgroundJobBoard {
     job.terminalUnreconciled = false
 
     await this.persistRecord(job)
-    await this.writeSignal(job)
+    // P1-1: reconcile is an acknowledgment, NOT a new terminal transition
+    // (onTerminal does not re-fire). Re-writing a `.signal.json` here leaked
+    // orphan signals with `state:"reconciled"` after the finalize→reconcile
+    // cycle deleted them. Instead, remove any still-pending wake signal so
+    // reconcile leaves no `<alias>.signal.json` behind.
+    await this.deleteSignal(job.alias)
 
     return job
   }

package/src/pantheon/delegation.ts

@@ -61,6 +61,7 @@ import {
 import { finalizeIdleChildrenWithoutMd } from './delegation-notify.ts'
 import { createPantheonLogger } from './logger.ts'
 import { buildAgentListDescription } from './permission-globs.ts'
+import { safeSessionPath } from './session-guard.ts'
 import { buildStopInstruction, cappedSummary, DEFAULT_MAX_STEPS } from './step-cap.ts'
 
 export type {
@@ -96,6 +97,40 @@ function readIntegerEnv(
   return Number.isSafeInteger(value) && value >= minimum ? value : fallback
 }
 
+// ─── B1: unresolved session template guard ─────────────────────────────
+//
+// The TUI/runtime can hand a plugin surface the UNSUBSTITUTED template literal
+// `{sessionID}` (URL-encoded `%7BsessionID%7D`) when no session is focused.
+// Forwarding it to a session API makes the opencode server reject every call
+// (`Expected a string starting with "ses", got "%7BsessionID%7D"`), which the
+// beta.7 E2E recorded at ~1k errors/s. The delegation layer is a defensive
+// choke point too: it is downstream of the plugin adapter in production, but
+// tests, older hosts, and direct embedders can inject a raw client.
+//
+// This guard targets the placeholder ONLY. It is deliberately NOT the full
+// `isValidSessionId` contract: structural test hosts use non-"ses" ids on
+// purpose (delegation-bootstrap.test.ts), and rejecting those would be a
+// behavior change unrelated to this bug. `session-guard.ts` remains the
+// strict choke point for the plugin adapters.
+const UNRESOLVED_SESSION_TEMPLATE = /(?:\{sessionID\}|%7BsessionID%7D)/i
+
+/** True when a session id is an unresolved `{sessionID}` template placeholder. */
+export function isUnresolvedSessionTemplate(id: unknown): boolean {
+  return typeof id === 'string' && UNRESOLVED_SESSION_TEMPLATE.test(id)
+}
+
+/**
+ * Refuse a placeholder session id before it reaches a session API. Returns
+ * true (and logs a clear warning) when the caller must skip the operation.
+ */
+function refuseUnresolvedSessionTemplate(id: unknown, operation: string): boolean {
+  if (!isUnresolvedSessionTemplate(id)) return false
+  log.warn(
+    `[pantheon-delegate] ${operation} skipped: unresolved session template "${String(id)}" — the host did not substitute the session id`,
+  )
+  return true
+}
+
 type BootstrapOutcome =
   | { status: 'started'; elapsedMs: number; reason: string }
   | { status: 'startup_failed' | 'bootstrap_unknown'; elapsedMs: number; reason: string }
@@ -115,6 +150,9 @@ async function promptWithTimeout(
   input: Parameters<DelegationClient['session']['promptAsync']>[0],
   timeoutMs: number,
 ): Promise<PromptOutcome> {
+  if (refuseUnresolvedSessionTemplate(input.path.id, 'promptAsync')) {
+    return { status: 'rejected', reason: `invalid sessionID: ${input.path.id}` }
+  }
   const controller = new AbortController()
   let timer: NodeJS.Timeout | undefined
   const operation = client.session.promptAsync({ ...input, signal: controller.signal }).then(
@@ -190,6 +228,14 @@ async function bootstrapChild(
   const hasStatusAPI = typeof client.session.get === 'function'
   const acceptedRunning = isRunningSession(accepted)
 
+  if (refuseUnresolvedSessionTemplate(childSessionID, 'bootstrap probe')) {
+    return {
+      status: 'bootstrap_unknown',
+      elapsedMs: 0,
+      reason: `invalid child sessionID "${childSessionID}"`,
+    }
+  }
+
   if (!hasMessagesAPI && !hasStatusAPI) {
     return acceptedRunning
       ? {
@@ -403,6 +449,72 @@ function stateLabel(state: BackgroundJobRecord['state']): string {
   }
 }
 
+// ─── B2: session-scoped delegation target resolution ───────────────────
+//
+// Board aliases restart per parent session (apo-1 in every root), so an alias
+// lookup MUST be scoped to the calling session. `pantheon_delegation_read`
+// previously delegated to the board's first-match resolver and, when the id
+// was not found in the current session, the generic "Unknown delegation"
+// message hid the real cause (the alias belonged to another session). This
+// helper makes the scoping explicit and returns a CLEAR error for each
+// cross-session / ambiguous case.
+
+/** Resolution outcome for a delegation read by task ID or alias. */
+export type DelegationTargetResolution =
+  | { kind: 'found'; job: BackgroundJobRecord }
+  | { kind: 'error'; message: string }
+
+/**
+ * Resolve a `pantheon_delegation_read` target with strict session scoping:
+ *   - exact task-ID match first (must belong to `sessionID`);
+ *   - then alias matches WITHIN `sessionID` (exactly one required);
+ *   - an alias that exists only in another session → clear cross-session
+ *     error (never another session's job);
+ *   - two matches in this session → clear ambiguity error.
+ */
+export function resolveDelegationTarget(
+  board: Pick<BackgroundJobBoard, 'list'>,
+  sessionID: string,
+  idOrAlias: string,
+): DelegationTargetResolution {
+  const jobs = board.list()
+
+  const byTaskID = jobs.find((job) => job.taskID === idOrAlias)
+  if (byTaskID !== undefined) {
+    if (byTaskID.parentSessionID === sessionID) return { kind: 'found', job: byTaskID }
+    return {
+      kind: 'error',
+      message:
+        `Delegation "${idOrAlias}" belongs to a different session ` +
+        `(${byTaskID.parentSessionID}) and cannot be read from ${sessionID}.`,
+    }
+  }
+
+  const aliasMatches = jobs.filter((job) => job.alias === idOrAlias)
+  const inSession = aliasMatches.filter((job) => job.parentSessionID === sessionID)
+  if (inSession.length === 1) return { kind: 'found', job: inSession[0]! }
+  if (inSession.length > 1) {
+    return {
+      kind: 'error',
+      message:
+        `Delegation alias "${idOrAlias}" is ambiguous in session ${sessionID} ` +
+        `(${inSession.length} matches); read it by task ID instead.`,
+    }
+  }
+  if (aliasMatches.length > 0) {
+    return {
+      kind: 'error',
+      message:
+        `Delegation alias "${idOrAlias}" belongs to a different session — ` +
+        'aliases are session-scoped. Use pantheon_delegation_list in the session that created it.',
+    }
+  }
+  return {
+    kind: 'error',
+    message: `Unknown delegation "${idOrAlias}" for this session. Use pantheon_delegation_list to see active delegations.`,
+  }
+}
+
 /** Normalize the SDK-provided caller agent without inventing an identity. */
 const normalizeToolAgent = normalizeDelegationAgent
 
@@ -509,6 +621,7 @@ async function sampleChildActivity(
   collector: ActivityCollector,
 ): Promise<void> {
   if (typeof client.session.messages !== 'function') return
+  if (refuseUnresolvedSessionTemplate(childSessionID, 'activity sample')) return
   try {
     const bundles = await client.session.messages({ path: { id: childSessionID } })
     if (!Array.isArray(bundles)) return
@@ -534,6 +647,7 @@ async function lastChildActivity(
   childSessionID: string,
 ): Promise<string | undefined> {
   if (typeof client.session.messages !== 'function') return undefined
+  if (refuseUnresolvedSessionTemplate(childSessionID, 'last activity fetch')) return undefined
   try {
     const bundles = await client.session.messages({ path: { id: childSessionID } })
     if (!Array.isArray(bundles)) return undefined
@@ -775,8 +889,13 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
       delete?: (input: { path: { id: string } }) => Promise<unknown>
     }
     if (typeof session.delete !== 'function') return
+    const sessionPath = safeSessionPath(childSessionID)
+    if (sessionPath === null) {
+      log.warn(`[pantheon-delegate] session.delete skipped: invalid sessionID "${childSessionID}"`)
+      return
+    }
     try {
-      await session.delete({ path: { id: childSessionID } })
+      await session.delete(sessionPath)
     } catch (err: unknown) {
       const reason = err instanceof Error ? err.message : String(err)
       log.warn(`[pantheon-delegate] failed to delete orphan session ${childSessionID}: ${reason}`)
@@ -899,6 +1018,18 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
         return `pantheon_delegate failed to create child session: ${reason}`
       }
       const childSessionID = created.id
+      // B1: a host that passes through the unresolved template must never
+      // produce a board job / bootstrap poll — reject it here with a clear
+      // message and refund the reserved budget (no child was started).
+      if (isUnresolvedSessionTemplate(childSessionID)) {
+        if (budgetReserved && budgetKey !== undefined) {
+          budgetUsage.set(budgetKey, Math.max(0, (budgetUsage.get(budgetKey) ?? 1) - 1))
+        }
+        log.warn(
+          `[pantheon-delegate] session.create returned unresolved session template "${childSessionID}" — child ignored`,
+        )
+        return `pantheon_delegate failed: host returned an unresolved child session template ("${childSessionID}"); expected an id starting with "ses".`
+      }
       knownChildren.add(childSessionID)
       options.registerChildSession?.(childSessionID, ctx.sessionID)
 
@@ -1024,6 +1155,12 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
         return `[STARTUP FAILED] ${bootstrap.status}: ${bootstrap.reason}; retry creation failed: ${reason}`
       }
       const retryID = retry.id
+      if (isUnresolvedSessionTemplate(retryID)) {
+        log.warn(
+          `[pantheon-delegate] retry session.create returned unresolved session template "${retryID}" — retry ignored`,
+        )
+        return `[STARTUP FAILED] ${bootstrap.status}: ${bootstrap.reason}; host returned an unresolved retry session template ("${retryID}")`
+      }
       knownChildren.add(retryID)
       options.registerChildSession?.(retryID, ctx.sessionID)
 
@@ -1115,10 +1252,9 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
     args: readArgs,
     execute: async (args, ctx) => {
       guardEnabled()
-      const job = board.resolve(ctx.sessionID, args.id)
-      if (!job) {
-        return `Unknown delegation "${args.id}" for this session. Use pantheon_delegation_list to see active delegations.`
-      }
+      const resolution = resolveDelegationTarget(board, ctx.sessionID, args.id)
+      if (resolution.kind === 'error') return resolution.message
+      const job = resolution.job
 
       // Sample the child's messages while waiting so the caller sees what the
       // agent is doing — fail-open: no messages support → report as before.

package/src/pantheon/file-persistence-salvage.ts

@@ -0,0 +1,64 @@
+/**
+ * Best-effort salvage of complete top-level JSON objects from a corrupt
+ * `state.json`. The file is normally a JSON array; a torn write can leave a
+ * truncated tail (or interleaved NUL bytes). We scan for balanced `{…}`
+ * objects, parsing each independently, so every intact record survives.
+ *
+ * Extracted from file-persistence.ts to keep that module within the 300-line
+ * ceiling. Exported for tests.
+ */
+import type { BackgroundJobRecord } from './background-job-board.ts'
+
+export function salvageRecords(content: string): BackgroundJobRecord[] {
+  const records: BackgroundJobRecord[] = []
+  let depth = 0
+  let start = -1
+  let inString = false
+  let escaped = false
+
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i]
+
+    if (inString) {
+      if (escaped) {
+        escaped = false
+      } else if (ch === '\\') {
+        escaped = true
+      } else if (ch === '"') {
+        inString = false
+      }
+      continue
+    }
+
+    if (ch === '"') {
+      inString = true
+      continue
+    }
+    if (ch === '{') {
+      if (depth === 0) start = i
+      depth++
+      continue
+    }
+    if (ch === '}') {
+      if (depth > 0) depth--
+      if (depth === 0 && start >= 0) {
+        const candidate = content.slice(start, i + 1)
+        try {
+          const parsed: unknown = JSON.parse(candidate)
+          if (
+            parsed !== null &&
+            typeof parsed === 'object' &&
+            typeof (parsed as BackgroundJobRecord).taskID === 'string'
+          ) {
+            records.push(parsed as BackgroundJobRecord)
+          }
+        } catch {
+          // Incomplete/partial object — skip it, keep scanning.
+        }
+        start = -1
+      }
+    }
+  }
+
+  return records
+}

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/plugins/tui/dist/tui.js

@@ -164,7 +164,7 @@ async function detectVersion(api) {
 			if (ver) return ver;
 		}
 	} catch {}
-	return "1.5.0-beta.7";
+	return "1.5.0-beta.8";
 }
 /**
 * usage-bar — AI subscription usage gauge for the opencode TUI.

package/src/plugins/tui/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pantheon-tui",
-  "version": "1.5.0-beta.7",
+  "version": "1.5.0-beta.8",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pantheon-tui",
-      "version": "1.5.0-beta.7",
+      "version": "1.5.0-beta.8",
       "license": "MIT",
       "dependencies": {
         "@opencode-ai/plugin": ">=1.14.0",

package/src/plugins/tui/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon-tui",
   "type": "module",
-  "version": "1.5.0-beta.7",
+  "version": "1.5.0-beta.8",
   "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": {