opencode-extended-sidebar 0.2.90

package/src/pware.oc.runtime/pware.oc.runtime.monitor.ts

@@ -0,0 +1,142 @@
+/**
+ * Watch boulder.json + poll SQLite stamps. Invokes onChange when fingerprint changes.
+ */
+import fs from "node:fs"
+import path from "node:path"
+import type { PwareEvent } from "../pware.oc.core/pware.oc.core.bus.js"
+import { EV_OES_SNAPSHOT } from "../pware.oc.core/constants/pware.oc.core.constants.eventName.js"
+import { EV_OMO_BOULDER_CHANGED } from "../pware.oc.omo/constants/pware.oc.omo.constants.eventName.js"
+import { findBoulder } from "../pware.oc.omo/resolver/index.js"
+import { computeFingerprint, type RuntimeSnapshot } from "./resolver/index.js"
+import { readRuntimeSnapshotAsync } from "./pware.oc.runtime.snapshotClient.js"
+import { getOpenCodeDbPath } from "../pware.oc.core/pware.oc.core.paths.js"
+import { MONITOR_POLL_MS, MONITOR_WATCH_DEBOUNCE_MS } from "../pware.oc.core/pware.oc.core.timing.js"
+import { dbg, profile } from "../pware.oc.core/pware.oc.core.debug.js"
+
+export type MonitorOptions = {
+  sessionId: string
+  projectRoot: string | null
+  dbPath?: string
+  pollMs?: number
+  onChange?: (snap: RuntimeSnapshot) => void
+  emit?: (evt: PwareEvent) => void
+}
+
+export type MonitorHandle = {
+  stop: () => void
+  refresh: () => void
+  question: (sessionId: string) => void
+}
+
+export function startMonitor(opts: MonitorOptions): MonitorHandle {
+  const dbPath = opts.dbPath || getOpenCodeDbPath(process.env, undefined, opts.projectRoot)
+  dbg("monitor", "start", { dbPath, sessionId: opts.sessionId, projectRoot: opts.projectRoot ?? null })
+  const pollMs = opts.pollMs ?? MONITOR_POLL_MS
+  let lastFp = ""
+  let stopped = false
+  let emitGen = 0
+  let debounce: ReturnType<typeof setTimeout> | null = null
+  let pendingQuestionHint: string | null = null
+  const watchers: fs.FSWatcher[] = []
+
+  const emit = (force = false) =>
+    profile("monitor.emit", () => {
+      if (stopped) return
+      const fp = computeFingerprint({
+        dbPath,
+        projectRoot: opts.projectRoot,
+        sessionId: opts.sessionId,
+      })
+      if (!force && fp === lastFp) return
+      dbg("monitor", "emit", { force, fp: fp.slice(0, 40) })
+      lastFp = fp
+      const gen = ++emitGen
+      const questionHint = pendingQuestionHint ?? undefined
+      pendingQuestionHint = null
+      void readRuntimeSnapshotAsync({
+        sessionId: opts.sessionId,
+        projectRoot: opts.projectRoot,
+        dbPath,
+        questionHint,
+      }).then((snapshot) => {
+        if (stopped || gen !== emitGen) return
+        opts.onChange?.(snapshot)
+        opts.emit?.({
+          type: EV_OES_SNAPSHOT,
+          ts: Date.now(),
+          data: { snapshot },
+        })
+      })
+    })
+
+  const schedule = () => {
+    if (stopped) return
+    if (debounce) clearTimeout(debounce)
+    debounce = setTimeout(() => {
+      debounce = null
+      emit()
+    }, MONITOR_WATCH_DEBOUNCE_MS)
+  }
+
+  // Initial
+  emit(true)
+
+  const interval = setInterval(schedule, pollMs)
+
+  const root = opts.projectRoot
+  if (root) {
+    const boulderPath = findBoulder(root)
+    if (boulderPath) {
+      try {
+        watchers.push(
+          fs.watch(boulderPath, { persistent: false }, () => {
+            opts.emit?.({
+              type: EV_OMO_BOULDER_CHANGED,
+              ts: Date.now(),
+              data: {},
+            })
+            schedule()
+          }),
+        )
+      } catch {
+        // poll covers it
+      }
+    }
+  }
+
+  // SQLite: watching the file is flaky under WAL — poll stamps instead.
+  // Still try a non-recursive watch on the data dir for companions.
+  try {
+    const dataDir = path.dirname(dbPath)
+    if (fs.existsSync(dataDir)) {
+      watchers.push(
+        fs.watch(dataDir, { persistent: false }, (event, filename) => {
+          const name = filename?.toString() || ""
+          if (!name || name.includes("opencode.db")) schedule()
+        }),
+      )
+    }
+  } catch {
+    // poll only
+  }
+
+  return {
+    refresh: () => emit(true),
+    question: (sessionId: string) => {
+      pendingQuestionHint = sessionId
+      emit(true)
+    },
+    stop: () => {
+      stopped = true
+      if (debounce) clearTimeout(debounce)
+      clearInterval(interval)
+      for (const w of watchers) {
+        try {
+          w.close()
+        } catch {
+          // ignore
+        }
+      }
+    },
+  }
+}

package/src/pware.oc.runtime/pware.oc.runtime.mywork-enrich.ts

@@ -0,0 +1,79 @@
+/**
+ * pware.oc.runtime.mywork-enrich
+ *
+ * Enriches the OMO approval queue with the writer session's activity state:
+ * builds the plan-file → writer-session index once, then per item resolves the
+ * writer via `basenameOf(item.rel)` and asks `sessionActivityState` (SQLite
+ * freshness + the omo `.omo/run-continuation` marker). Soft-fails to
+ * `sessionState: null` per item — never throws. This is the runtime layer's
+ * job: it composes omo (`.omo/run-continuation`) with opencode (SQLite session
+ * activity).
+ */
+import fs from "node:fs"
+import {
+  sessionActivityState,
+  type SessionActivityState,
+} from "../pware.oc.opencode/resolver/pware.oc.opencode.resolver.session.js"
+import { listTodos } from "../pware.oc.opencode/resolver/pware.oc.opencode.resolver.todo.js"
+import { planSessionIndex } from "../pware.oc.omo/resolver/index.js"
+import { openReadonlyDb, withDbRead, type SqlDb } from "../pware.oc.core/pware.oc.core.sqlite.js"
+import { profile } from "../pware.oc.core/pware.oc.core.debug.js"
+import { basenameOf } from "../pware.oc.core/pware.oc.core.paths.js"
+import { readRunContinuationState } from "../pware.oc.omo/resolver/pware.oc.omo.resolver.approvalState.js"
+import { BACKGROUND_TASK_ACTIVE } from "../pware.oc.omo/constants/pware.oc.omo.constants.backgroundTask.js"
+import { STATUS_COMPLETED } from "../pware.oc.core/constants/pware.oc.core.constants.status.js"
+import type { ApprovalItem } from "../pware.oc.omo/resolver/pware.oc.omo.resolver.plan.js"
+
+/**
+ * An approval item with its planner-session activity attached. `sessionState`
+ * is a runtime enrichment: it lives here on the runtime layer's enriched type,
+ * not on omo's base `ApprovalItem` (omo must not import the opencode session type).
+ */
+export type EnrichedApproval = ApprovalItem & {
+  sessionState: SessionActivityState | null
+  /** Writer session's todos all completed (and at least one present). */
+  todosDone: boolean
+}
+
+function blank(items: readonly ApprovalItem[]): EnrichedApproval[] {
+  return items.map((item) => ({ ...item, sessionState: null, todosDone: false }))
+}
+
+function sessionTodosDone(db: SqlDb, sessionId: string): boolean {
+  const todos = listTodos(db, sessionId)
+  return todos.length > 0 && todos.every((t) => t.status === STATUS_COMPLETED)
+}
+
+export function enrichApprovalSessionStates(
+  items: readonly ApprovalItem[],
+  opts: { dbPath: string | null | undefined; projectRoot: string | null | undefined; now?: number },
+): EnrichedApproval[] {
+  if (items.length === 0) return []
+  const dbPath = opts.dbPath
+  const projectRoot = opts.projectRoot
+  if (!dbPath || !projectRoot || !fs.existsSync(dbPath)) return blank(items)
+  return profile("mywork.approvals", () =>
+    withDbRead(
+      () => {
+        const db = openReadonlyDb(dbPath)
+        if (!db) return blank(items)
+        // Index once; match writers by basename across all sessions (no
+        // projectId in the opts shape — same scope as sessionForPlanFile).
+        const index = planSessionIndex(db, null, projectRoot)
+        return items.map((item) => {
+          const sessionId = index.fileWriter.get(basenameOf(item.rel))?.sessionId ?? null
+          const sessionState = sessionId
+            ? sessionActivityState(db, sessionId, {
+                backgroundTaskActive:
+                  readRunContinuationState(projectRoot, sessionId) === BACKGROUND_TASK_ACTIVE,
+                now: opts.now,
+              })
+            : null
+          const todosDone = sessionId ? sessionTodosDone(db, sessionId) : false
+          return { ...item, sessionState, todosDone }
+        })
+      },
+      () => blank(items),
+    ),
+  )
+}

package/src/pware.oc.runtime/pware.oc.runtime.mywork.ts

@@ -0,0 +1,253 @@
+/**
+ * pware.oc.core.mywork.resolver
+ *
+ * The "My work" queue — one list of things awaiting the user's action, from
+ * two sources: an open OpenCode `question` (core, always) and an OMO plan
+ * awaiting approval (optional, only when `.omo/` is present).
+ */
+import type { OpenQuestion } from "../pware.oc.opencode/resolver/pware.oc.opencode.resolver.question.js"
+import type {
+  AgentStatus,
+  SessionActivityState,
+} from "../pware.oc.opencode/resolver/pware.oc.opencode.resolver.session.js"
+import type { ReviewState } from "../pware.oc.omo/resolver/pware.oc.omo.resolver.plan.js"
+import type { EnrichedApproval } from "./pware.oc.runtime.mywork-enrich.js"
+import {
+  MY_WORK_GROUP_DISMISSED,
+  MY_WORK_GROUP_DRAFT_DOCS,
+  MY_WORK_GROUP_DRAFTING,
+  MY_WORK_GROUP_FINISHED,
+  MY_WORK_GROUP_PINNED,
+  MY_WORK_GROUP_PLANS,
+  MY_WORK_GROUP_READY_REVIEW,
+  MY_WORK_GROUP_READY_START,
+  MY_WORK_GROUP_SESSIONS,
+  type ApprovalGroupKind,
+} from "../pware.oc.core/constants/pware.oc.core.constants.myWork.js"
+import { isDraftOf, resolveApprovalGroup } from "../pware.oc.omo/resolver/pware.oc.omo.resolver.approvalGroup.js"
+import {
+  QUESTION_KIND_ERROR,
+  QUESTION_KIND_INTERRUPTED,
+  QUESTION_KIND_QUESTION,
+  type OpenQuestionKind,
+} from "../pware.oc.opencode/constants/pware.oc.opencode.constants.questionKind.js"
+import {
+  START_WORK_MAKE_PR,
+  START_WORK_PLAIN,
+  START_WORK_SHIP,
+  type StartWorkMode,
+} from "../pware.oc.omo/constants/pware.oc.omo.constants.startWork.js"
+
+export type { ApprovalGroupKind, OpenQuestionKind, StartWorkMode }
+
+export type QuestionGroupKind = OpenQuestionKind | typeof MY_WORK_GROUP_DISMISSED
+
+export type MyWorkItem =
+  | {
+      kind: QuestionGroupKind
+      partId: string
+      sessionId: string
+      title: string
+      startedAt: number | null
+      /** `state.error` text for interrupted/error rows; null for an open question. */
+      reason: string | null
+    }
+  | {
+      kind: ApprovalGroupKind
+      name: string
+      rel: string
+      pendingAction: string | null
+      updatedAt: number | null
+      sessionState: SessionActivityState | null
+      review: ReviewState | null
+    }
+  | {
+      kind: typeof MY_WORK_GROUP_SESSIONS
+      sessionId: string
+      title: string
+      status: AgentStatus
+      timeUpdated: number | null
+    }
+  | {
+      kind: typeof MY_WORK_GROUP_PINNED
+      sessionId: string
+      title: string
+      status: AgentStatus
+      timeUpdated: number | null
+    }
+  | {
+      kind: typeof MY_WORK_GROUP_DRAFT_DOCS
+      name: string
+      rel: string
+      updatedAt: number | null
+    }
+  | {
+      kind: typeof MY_WORK_GROUP_PLANS
+      name: string
+      rel: string
+      updatedAt: number | null
+    }
+
+export type MyWorkKind = MyWorkItem["kind"]
+
+export const MY_WORK_ORDER: readonly MyWorkKind[] = [
+  MY_WORK_GROUP_PINNED,
+  QUESTION_KIND_QUESTION,
+  QUESTION_KIND_INTERRUPTED,
+  QUESTION_KIND_ERROR,
+  MY_WORK_GROUP_SESSIONS,
+  MY_WORK_GROUP_READY_REVIEW,
+  MY_WORK_GROUP_READY_START,
+  MY_WORK_GROUP_FINISHED,
+  MY_WORK_GROUP_DRAFTING,
+  MY_WORK_GROUP_DRAFT_DOCS,
+  MY_WORK_GROUP_PLANS,
+  MY_WORK_GROUP_DISMISSED,
+]
+
+const MY_WORK_LABELS: Record<MyWorkKind, string> = {
+  [MY_WORK_GROUP_PINNED]: "Pinned",
+  [QUESTION_KIND_QUESTION]: "Awaiting answer",
+  [QUESTION_KIND_INTERRUPTED]: "Interrupted",
+  [QUESTION_KIND_ERROR]: "Errors",
+  [MY_WORK_GROUP_SESSIONS]: "Sessions",
+  [MY_WORK_GROUP_READY_REVIEW]: "Ready to review",
+  [MY_WORK_GROUP_READY_START]: "Ready to start",
+  [MY_WORK_GROUP_FINISHED]: "Finished",
+  [MY_WORK_GROUP_DISMISSED]: "Dismissed questions",
+  [MY_WORK_GROUP_DRAFTING]: "Drafting",
+  [MY_WORK_GROUP_DRAFT_DOCS]: "Draft docs",
+  [MY_WORK_GROUP_PLANS]: "Plans",
+}
+
+export function myWorkLabel(kind: MyWorkKind): string {
+  return MY_WORK_LABELS[kind]
+}
+
+/**
+ * Why "Navigate to session" is unavailable for an approval: no writer session
+ * was found in the database, or the database itself could not be opened. Null
+ * when navigation is actionable.
+ */
+export function approvalContinueHint(
+  sessionId: string | null | undefined,
+  dbAvailable: boolean,
+): string | null {
+  if (sessionId) return null
+  return dbAvailable ? "No session wrote this plan" : "Database unavailable"
+}
+
+/** The exact "start work" command text for a delivery mode and optional plan name. */
+export function startWorkCommand(mode: StartWorkMode, planName?: string | null): string {
+  const name = typeof planName === "string" ? planName.trim() : ""
+  const base = name ? `start work ${name}` : "start work"
+  if (mode === START_WORK_MAKE_PR) return `${base} --make-pr`
+  if (mode === START_WORK_SHIP) return `${base} --ship`
+  return base
+}
+
+export function groupMyWork(
+  items: readonly MyWorkItem[],
+): { kind: MyWorkKind; items: MyWorkItem[] }[] {
+  const out: { kind: MyWorkKind; items: MyWorkItem[] }[] = []
+  for (const kind of MY_WORK_ORDER) {
+    const bucket = items.filter((i) => i.kind === kind)
+    if (bucket.length > 0) out.push({ kind, items: bucket })
+  }
+  return out
+}
+
+/** Build the question items from an open-question read (title comes from the row). */
+export function toQuestionItems(questions: readonly OpenQuestion[]): MyWorkItem[] {
+  return questions.map((q) => ({
+    kind: q.kind,
+    partId: q.partId,
+    sessionId: q.sessionId,
+    title: q.title,
+    startedAt: q.startedAt,
+    reason: q.reason,
+  }))
+}
+
+/** Build the approval items from a pending-approval read, dropping superseded plans. */
+export function toApprovalItems(approvals: readonly EnrichedApproval[]): MyWorkItem[] {
+  const out: MyWorkItem[] = []
+  for (const a of approvals) {
+    const kind = resolveApprovalGroup(a.status, isDraftOf(a.rel), a.workState, a.todosDone)
+    if (!kind) continue
+    out.push({
+      kind,
+      name: a.name,
+      rel: a.rel,
+      pendingAction: a.pendingAction,
+      updatedAt: a.updatedAt,
+      sessionState: a.sessionState,
+      review: a.review,
+    })
+  }
+  return out
+}
+
+/** Build the Draft docs items — drafts no action group covers, browsed as files. */
+export function toDraftDocItems(
+  docs: readonly { name: string; rel: string; updatedAt: number | null }[],
+): MyWorkItem[] {
+  return docs.map((d) => ({ kind: MY_WORK_GROUP_DRAFT_DOCS, name: d.name, rel: d.rel, updatedAt: d.updatedAt }))
+}
+
+/** Build the Plans items — plan files no action group covers, browsed as files. */
+export function toPlanItems(
+  docs: readonly { name: string; rel: string; updatedAt: number | null }[],
+): MyWorkItem[] {
+  return docs.map((d) => ({ kind: MY_WORK_GROUP_PLANS, name: d.name, rel: d.rel, updatedAt: d.updatedAt }))
+}
+
+/** Build the sessions group from recent main sessions — every session, live or idle. */
+export function toSessionItems(
+  sessions: readonly {
+    id: string
+    title: string
+    status: AgentStatus
+    timeUpdated: number | null
+  }[],
+): MyWorkItem[] {
+  return sessions.map((s) => ({
+    kind: MY_WORK_GROUP_SESSIONS,
+    sessionId: s.id,
+    title: s.title,
+    status: s.status,
+    timeUpdated: s.timeUpdated,
+  }))
+}
+
+/** Parse the persisted dismissed-question set (a JSON array of part ids) from the kv store. */
+export function parseDismissed(raw: string | null | undefined): ReadonlySet<string> {
+  if (!raw) return new Set()
+  try {
+    const value = JSON.parse(raw)
+    if (!Array.isArray(value)) return new Set()
+    return new Set(value.filter((x): x is string => typeof x === "string" && x.length > 0))
+  } catch {
+    return new Set()
+  }
+}
+
+/** Serialize a dismissed-question id set back to the JSON string the kv store holds. */
+export function formatDismissed(ids: ReadonlySet<string>): string {
+  return JSON.stringify([...ids])
+}
+
+export function dropDismissed(
+  items: readonly MyWorkItem[],
+  dismissed: ReadonlySet<string>,
+): MyWorkItem[] {
+  return items.map((i) => {
+    if (!("partId" in i)) return i
+    const byId = dismissed.has(i.partId)
+    const byReason = i.kind === QUESTION_KIND_ERROR
+      && typeof i.reason === "string"
+      && i.reason.toLowerCase().includes("dismissed this question")
+    if (!byId && !byReason) return i
+    return { ...i, kind: MY_WORK_GROUP_DISMISSED }
+  })
+}

package/src/pware.oc.runtime/pware.oc.runtime.questions.ts

@@ -0,0 +1,95 @@
+/**
+ * pware.oc.runtime.questions
+ *
+ * In-memory, per-session cache of open questions for the "My work" queue. A
+ * later wiring task feeds it from cheap host-event hints (targeted
+ * `listSessionQuestions` on the session a `message.part.updated` just touched)
+ * and a periodic `listOpenQuestions` backstop, replacing the expensive
+ * project-wide scan that used to run on every snapshot.
+ *
+ * `createQuestionCache()` returns a fresh instance — no module-level mutable
+ * singleton — so tests build their own and the wiring task owns the one real
+ * instance. State is `bySession`, a Map keyed by `sessionId`; `get` flattens
+ * and dedupes it. The two read functions below already soft-fail to `[]`, so
+ * this cache only holds/merges their results and needs no try/catch of its own.
+ */
+import {
+  listOpenQuestions,
+  listSessionQuestions,
+  type OpenQuestion,
+} from "../pware.oc.opencode/resolver/pware.oc.opencode.resolver.question.js"
+
+export type QuestionCache = {
+  /** Project-wide open questions, deduped by partId, sorted `startedAt` DESC (nulls last). */
+  get: () => OpenQuestion[]
+  /** Full `listOpenQuestions` scan; replaces the whole map (drop gone sessions). */
+  seed: (dbPath: string, projectId: string | null) => void
+  /** One session's `listSessionQuestions`; merges in, or removes on empty. */
+  touch: (dbPath: string, projectId: string | null, sessionId: string) => void
+  /** Full `listOpenQuestions` scan — semantic alias of `seed` for the backstop call site. */
+  reconcile: (dbPath: string, projectId: string | null) => void
+  /** Drop every cached session. */
+  reset: () => void
+}
+
+/**
+ * Flatten all per-session slices, dedupe by `partId` (a question may briefly
+ * appear in two sessions' slices — keep the first), and sort by `startedAt`
+ * descending with nulls last. Pure — never mutates its input.
+ */
+export function mergeQuestions(
+  bySession: ReadonlyMap<string, readonly OpenQuestion[]>,
+): OpenQuestion[] {
+  const seen = new Set<string>()
+  const out: OpenQuestion[] = []
+  for (const list of bySession.values()) {
+    for (const q of list) {
+      if (seen.has(q.partId)) continue
+      seen.add(q.partId)
+      out.push(q)
+    }
+  }
+  out.sort((a, b) => {
+    const x = a.startedAt
+    const y = b.startedAt
+    if (x === y) return 0
+    if (x == null) return 1
+    if (y == null) return -1
+    return y - x
+  })
+  return out
+}
+
+export function createQuestionCache(): QuestionCache {
+  let bySession = new Map<string, OpenQuestion[]>()
+
+  function refill(dbPath: string, projectId: string | null): void {
+    const next = new Map<string, OpenQuestion[]>()
+    for (const q of listOpenQuestions({ dbPath, projectId })) {
+      const bucket = next.get(q.sessionId)
+      if (bucket) bucket.push(q)
+      else next.set(q.sessionId, [q])
+    }
+    bySession = next
+  }
+
+  return {
+    get() {
+      return mergeQuestions(bySession)
+    },
+    seed(dbPath, projectId) {
+      refill(dbPath, projectId)
+    },
+    touch(dbPath, projectId, sessionId) {
+      const result = listSessionQuestions({ dbPath, sessionId, projectId })
+      if (result.length > 0) bySession.set(sessionId, result)
+      else bySession.delete(sessionId)
+    },
+    reconcile(dbPath, projectId) {
+      refill(dbPath, projectId)
+    },
+    reset() {
+      bySession = new Map()
+    },
+  }
+}

package/src/pware.oc.runtime/pware.oc.runtime.snapshotClient.ts

@@ -0,0 +1,129 @@
+/**
+ * pware.oc.runtime.snapshotClient
+ *
+ * Async facade over the snapshot worker. `readRuntimeSnapshotAsync` posts a
+ * snapshot request and resolves with the composed snapshot; when the worker
+ * cannot be spawned, errors, or fails to answer within the timeout it falls
+ * back to the synchronous `readRuntimeSnapshot` — so the panel never hard
+ * depends on worker availability.
+ */
+import { dbg } from "../pware.oc.core/pware.oc.core.debug.js"
+import { readRuntimeSnapshot, type RuntimeSnapshot } from "./resolver/index.js"
+
+export type SnapshotRequestOpts = {
+  sessionId: string
+  projectRoot: string | null
+  dbPath?: string
+  questionHint?: string
+}
+
+type SnapshotDoneMessage = {
+  type: "snapshot:done"
+  id: number
+  ok: boolean
+  snap?: RuntimeSnapshot
+  error?: string
+}
+
+/** Bound on a single worker round-trip before the sync path takes over. */
+const WORKER_TIMEOUT_MS = 4_000
+
+type PendingEntry = {
+  opts: SnapshotRequestOpts
+  resolve: (snap: RuntimeSnapshot) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+let worker: Worker | null = null
+let workerFailed = false
+let nextId = 0
+const pending = new Map<number, PendingEntry>()
+
+function syncFallback(opts: SnapshotRequestOpts): RuntimeSnapshot {
+  return readRuntimeSnapshot(opts)
+}
+
+function settle(id: number, snap: RuntimeSnapshot): void {
+  const entry = pending.get(id)
+  if (!entry) return
+  pending.delete(id)
+  clearTimeout(entry.timer)
+  entry.resolve(snap)
+}
+
+function failAll(reason: string): void {
+  dbg("snapshot.worker", "failed", { reason })
+  workerFailed = true
+  for (const id of [...pending.keys()]) {
+    const entry = pending.get(id)
+    if (entry) settle(id, syncFallback(entry.opts))
+  }
+}
+
+function ensureWorker(): Worker | null {
+  if (workerFailed) return null
+  if (worker) return worker
+  try {
+    const w = new Worker(new URL("./pware.oc.runtime.worker.ts", import.meta.url), { type: "module" })
+    w.onmessage = (event: MessageEvent<SnapshotDoneMessage>) => {
+      const msg = event.data
+      if (!msg || msg.type !== "snapshot:done") return
+      const entry = pending.get(msg.id)
+      if (!entry) return
+      settle(msg.id, msg.ok && msg.snap ? msg.snap : syncFallback(entry.opts))
+    }
+    w.onerror = (event) => {
+      const message =
+        typeof event === "object" && event !== null && "message" in event
+          ? String((event as { message: unknown }).message)
+          : String(event)
+      failAll(message)
+      try {
+        w.terminate()
+      } catch {
+        // ignore
+      }
+      worker = null
+    }
+    worker = w
+    dbg("snapshot.worker", "spawned", {})
+    return w
+  } catch (err) {
+    dbg("snapshot.worker", "spawn failed", { error: err instanceof Error ? err.message : String(err) })
+    workerFailed = true
+    return null
+  }
+}
+
+/** Off-main-thread snapshot read, falling back to the sync path on any failure. */
+export function readRuntimeSnapshotAsync(opts: SnapshotRequestOpts): Promise<RuntimeSnapshot> {
+  const w = ensureWorker()
+  if (!w) return Promise.resolve(syncFallback(opts))
+  const id = ++nextId
+  return new Promise<RuntimeSnapshot>((resolve) => {
+    const timer = setTimeout(() => settle(id, syncFallback(opts)), WORKER_TIMEOUT_MS)
+    pending.set(id, { opts, resolve, timer })
+    try {
+      w.postMessage({ type: "snapshot", id, opts })
+    } catch (err) {
+      dbg("snapshot.worker", "post failed", { error: err instanceof Error ? err.message : String(err) })
+      settle(id, syncFallback(opts))
+    }
+  })
+}
+
+/** Terminate the shared worker (idempotent). Safe to call on plugin shutdown. */
+export function shutdownSnapshotWorker(): void {
+  if (!worker) return
+  try {
+    worker.postMessage({ type: "shutdown" })
+  } catch {
+    // ignore
+  }
+  try {
+    worker.terminate()
+  } catch {
+    // ignore
+  }
+  worker = null
+}