opencode-extended-sidebar 0.2.90 → 0.2.91

package/src/pware.oc.core/pware.oc.core.layout.ts

@@ -1,234 +1,234 @@
-/**
- * Vertical row budget for the sidebar. Pure — no OpenTUI, unit tested directly.
- * Same idea as `packChips` in pulse.ts, one axis over: under pressure the worst
- * rank gives up rows first, and nothing drops below its `min` until every
- * section has already reached it.
- */
-
-/**
- * Rows OpenCode's own TUI takes around the `sidebar_content` slot. Measured
- * from the opencode TUI source (`packages/tui/src/routes/session/sidebar.tsx`,
- * stable across v1.18.27 = HEAD): the sidebar column has no border — its frame
- * is `paddingTop` 1 + a fixed footer (`sidebar_footer`, outside the scrollbox:
- * 1 spacer + path row + 1 gap + version row) + `paddingBottom` 1.
- */
-const HOST_SIDEBAR_CHROME = 6
-
-/**
- * Rows the host's `sidebar_title` fallback block (same scrollbox, above the
- * content slot) takes before the plugin's first content row: a typical session
- * shows a bold title + workspace (2 rows) plus the 1-row `gap` separator, and
- * a wrapping title or the optional channel/share lines add more. Kept at 4 so
- * `PANEL_CHROME` still covers the old flat-10 headroom.
- */
-const HOST_SIDEBAR_TITLE_RESERVE = 4
-
-/** Fixed chrome the sidebar slot's own host takes above the content rows. */
-const PANEL_CHROME = HOST_SIDEBAR_CHROME + HOST_SIDEBAR_TITLE_RESERVE
-const PANEL_MIN_ROWS = 8
-
-/** Shared right rail for context actions (`switch new`, `view all`, …). */
-export const CONTEXT_ACTION_COL_WIDTH = 10
-
-/**
- * Row width budget before the root box reports its measured layout width.
- * `lineMax` used to be an oes.json option; it is now measured, and this is the
- * pre-layout fallback (matches the old default).
- */
-export const ROW_LINE_FALLBACK = 31
-
-/** Columns subtracted from the measured root width for the scrollbar reserve. */
-export const ROW_LINE_RESERVE = 1
-
-/** Realtime charts link on the OES row (`C` → fullscreen dialog). */
-export const RT_ACTION_COL_WIDTH = 1
-
-/** Compact sparkline body rows — sidebar inline chart removed; kept for docs/tests. */
-export const RT_CHART_ROWS = 3
-
-/** Per-series sparkline body rows in the realtime fullscreen dialog. */
-export const RT_DIALOG_CHART_ROWS = 8
-
-/**
- * Host `api.ui.Dialog` inner box widths (`packages/opencode/.../dialog.tsx`).
- * `maxWidth` is `terminal − 2`. `xlarge` is 116 on hosts that implement it
- * (#44754); older builds only switch `large` (80) vs else (60).
- */
-export const HOST_DIALOG_OUTER_WIDTH = { medium: 60, large: 80, xlarge: 116 } as const
-export type HostDialogSize = keyof typeof HOST_DIALOG_OUTER_WIDTH
-
-/** `maxWidth={dimensions().width - 2}` on the host inner box. */
-const HOST_DIALOG_MAX_INSET = 2
-/** `DialogPad` left + right, matching the host dialog bodies (`paddingLeft/Right 2`). */
-const DIALOG_PAD_X = 4
-
-/**
- * Columns inside the padded dialog body. Subtracts the host box cap, the
- * `maxWidth` inset, and DialogPad — this is the line budget a chart may use,
- * including the asciiTrend min/max labels on the left of each row.
- */
-export function dialogInnerWidth(termWidth: number, size: HostDialogSize): number {
-  const w = Number.isFinite(termWidth) && termWidth > 0 ? Math.floor(termWidth) : 80
-  const outer = Math.min(HOST_DIALOG_OUTER_WIDTH[size], Math.max(1, w - HOST_DIALOG_MAX_INSET))
-  return Math.max(8, outer - DIALOG_PAD_X)
-}
-
-/**
- * One right-aligned action line padded to {@link CONTEXT_ACTION_COL_WIDTH}.
- * Long labels keep their trailing characters so `view all` still fits the rail.
- */
-export function contextActionsLine(labels: readonly string[]): string {
-  const text = labels.join(" ")
-  if (text.length >= CONTEXT_ACTION_COL_WIDTH) return text.slice(-CONTEXT_ACTION_COL_WIDTH)
-  return text.padStart(CONTEXT_ACTION_COL_WIDTH)
-}
-
-/** Usable rows in the sidebar slot for a terminal that tall. */
-export function panelRows(termHeight: number): number {
-  const h = Number.isFinite(termHeight) && termHeight > 0 ? termHeight : 24
-  return Math.max(PANEL_MIN_ROWS, Math.floor(h) - PANEL_CHROME)
-}
-
-/** Rows a section keeps before it is worth folding instead. */
-export const ROW_MIN = {
-  delegates: 2,
-  drafts: 2,
-  files: 3,
-  mywork: 2,
-  tools: 3,
-} as const
-
-/**
- * Higher gives up rows first. Live activity outranks history: on Current the
- * tool feed survives longest. My work is a queue of things awaiting the user,
- * so it ties with the live feed.
- */
-export const ROW_RANK = {
-  delegates: 3,
-  drafts: 3,
-  files: 2,
-  mywork: 1,
-  tools: 1,
-} as const
-
-export type Section<K extends string = string> = {
-  key: K
-  /** Rows the section would like — usually the matching `oes.json` value. */
-  want: number
-  min: number
-  rank: number
-}
-
-/**
- * Split `budget - fixed` rows across the sections. Ties are broken by whoever
- * currently holds the most rows, so equal ranks shrink together. A section that
- * hits `min` while the budget is still short is handed `0` — the caller folds
- * it rather than rendering a stub.
- */
-export function packSections<K extends string>(
-  budget: number,
-  fixed: number,
-  sections: readonly Section<K>[],
-): Record<K, number> {
-  const live = sections.map((s) => {
-    const min = Math.max(0, Math.round(s.min))
-    return { key: s.key, min, rank: s.rank, rows: Math.max(min, Math.max(0, Math.round(s.want))) }
-  })
-  const available = Math.max(0, Math.round(budget) - Math.round(fixed))
-  const total = () => live.reduce((sum, s) => sum + s.rows, 0)
-
-  const worstAbove = (floor: (s: (typeof live)[number]) => number): number => {
-    let worst = -1
-    for (let i = 0; i < live.length; i += 1) {
-      const s = live[i]!
-      if (s.rows <= floor(s)) continue
-      const best = worst < 0 ? null : live[worst]!
-      if (!best || s.rank > best.rank || (s.rank === best.rank && s.rows > best.rows)) worst = i
-    }
-    return worst
-  }
-
-  while (total() > available) {
-    const i = worstAbove((s) => s.min)
-    if (i < 0) break
-    live[i]!.rows -= 1
-  }
-
-  // Everyone is at their minimum and it still does not fit: fold, worst first.
-  while (total() > available) {
-    const i = worstAbove(() => 0)
-    if (i < 0) break
-    live[i]!.rows = 0
-  }
-
-  const out = {} as Record<K, number>
-  for (const s of live) out[s.key] = s.rows
-  return out
-}
-
-/**
- * Look up a packed section. A missing plan (Solid memo still computing,
- * previous compute threw, owner disposed) or a missing / non-finite key
- * returns `fallback` — the sidebar slot must not die on `plan[key]`.
- */
-export function rowsForPlan(
-  plan: Readonly<Record<string, number>> | null | undefined,
-  key: string,
-  fallback: number,
-): number {
-  if (!plan || typeof plan !== "object") return fallback
-  const v = plan[key]
-  return typeof v === "number" && Number.isFinite(v) ? v : fallback
-}
-
-/**
- * Show `shown` rows and report how many a "more" control can still reveal.
- * The expander is a separate clickable line (`RowList`) the caller renders
- * below the list — no row is spent on the note.
- */
-export function sliceShown<T>(
-  rows: readonly T[],
-  shown: number,
-): { rows: T[]; hidden: number } {
-  const s = Math.max(0, Math.round(shown))
-  const kept = rows.slice(0, s)
-  return { rows: kept, hidden: Math.max(0, rows.length - kept.length) }
-}
-
-/**
- * Whether the "… +N more" / "… less" line is drawn at all. The expanded toggle
- * keeps its "… less" line even when nothing is hidden; otherwise the line
- * vanishes the moment there is nothing left to reveal.
- */
-export function moreRevealVisible(hidden: number, expanded?: boolean): boolean {
-  return expanded === true || hidden > 0
-}
-
-/**
- * Clamp a scroll offset into the window a `visible`-row view can show over
- * `total` rows: the offset never goes below 0 or past the last full window.
- */
-export function clampScrollOffset(total: number, visible: number, offset: number): number {
-  const t = Math.max(0, Math.round(total))
-  const v = Math.max(1, Math.round(visible))
-  const max = Math.max(0, t - v)
-  const o = Math.max(0, Math.round(offset))
-  return Math.min(o, max)
-}
-
-/**
- * Move a scroll offset by one wheel `step`. Newest-first lists count the offset
- * from the newest row, so "down" goes toward older rows and "up" back to the
- * newest. The result stays inside the same clamped window as `clampScrollOffset`.
- */
-export function scrollByStep(
-  total: number,
-  visible: number,
-  offset: number,
-  direction: "up" | "down",
-  step: number,
-): number {
-  const s = Math.max(1, Math.round(step))
-  const next = direction === "down" ? offset + s : offset - s
-  return clampScrollOffset(total, visible, next)
-}
+/**
+ * Vertical row budget for the sidebar. Pure — no OpenTUI, unit tested directly.
+ * Same idea as `packChips` in pulse.ts, one axis over: under pressure the worst
+ * rank gives up rows first, and nothing drops below its `min` until every
+ * section has already reached it.
+ */
+
+/**
+ * Rows OpenCode's own TUI takes around the `sidebar_content` slot. Measured
+ * from the opencode TUI source (`packages/tui/src/routes/session/sidebar.tsx`,
+ * stable across v1.18.27 = HEAD): the sidebar column has no border — its frame
+ * is `paddingTop` 1 + a fixed footer (`sidebar_footer`, outside the scrollbox:
+ * 1 spacer + path row + 1 gap + version row) + `paddingBottom` 1.
+ */
+const HOST_SIDEBAR_CHROME = 6
+
+/**
+ * Rows the host's `sidebar_title` fallback block (same scrollbox, above the
+ * content slot) takes before the plugin's first content row: a typical session
+ * shows a bold title + workspace (2 rows) plus the 1-row `gap` separator, and
+ * a wrapping title or the optional channel/share lines add more. Kept at 4 so
+ * `PANEL_CHROME` still covers the old flat-10 headroom.
+ */
+const HOST_SIDEBAR_TITLE_RESERVE = 4
+
+/** Fixed chrome the sidebar slot's own host takes above the content rows. */
+const PANEL_CHROME = HOST_SIDEBAR_CHROME + HOST_SIDEBAR_TITLE_RESERVE
+const PANEL_MIN_ROWS = 8
+
+/** Shared right rail for context actions (`switch new`, `view all`, …). */
+export const CONTEXT_ACTION_COL_WIDTH = 10
+
+/**
+ * Row width budget before the root box reports its measured layout width.
+ * `lineMax` used to be an oes.json option; it is now measured, and this is the
+ * pre-layout fallback (matches the old default).
+ */
+export const ROW_LINE_FALLBACK = 31
+
+/** Columns subtracted from the measured root width for the scrollbar reserve. */
+export const ROW_LINE_RESERVE = 1
+
+/** Realtime charts link on the OES row (`C` → fullscreen dialog). */
+export const RT_ACTION_COL_WIDTH = 1
+
+/** Compact sparkline body rows — sidebar inline chart removed; kept for docs/tests. */
+export const RT_CHART_ROWS = 3
+
+/** Per-series sparkline body rows in the realtime fullscreen dialog. */
+export const RT_DIALOG_CHART_ROWS = 8
+
+/**
+ * Host `api.ui.Dialog` inner box widths (`packages/opencode/.../dialog.tsx`).
+ * `maxWidth` is `terminal − 2`. `xlarge` is 116 on hosts that implement it
+ * (#44754); older builds only switch `large` (80) vs else (60).
+ */
+export const HOST_DIALOG_OUTER_WIDTH = { medium: 60, large: 80, xlarge: 116 } as const
+export type HostDialogSize = keyof typeof HOST_DIALOG_OUTER_WIDTH
+
+/** `maxWidth={dimensions().width - 2}` on the host inner box. */
+const HOST_DIALOG_MAX_INSET = 2
+/** `DialogPad` left + right, matching the host dialog bodies (`paddingLeft/Right 2`). */
+const DIALOG_PAD_X = 4
+
+/**
+ * Columns inside the padded dialog body. Subtracts the host box cap, the
+ * `maxWidth` inset, and DialogPad — this is the line budget a chart may use,
+ * including the asciiTrend min/max labels on the left of each row.
+ */
+export function dialogInnerWidth(termWidth: number, size: HostDialogSize): number {
+  const w = Number.isFinite(termWidth) && termWidth > 0 ? Math.floor(termWidth) : 80
+  const outer = Math.min(HOST_DIALOG_OUTER_WIDTH[size], Math.max(1, w - HOST_DIALOG_MAX_INSET))
+  return Math.max(8, outer - DIALOG_PAD_X)
+}
+
+/**
+ * One right-aligned action line padded to {@link CONTEXT_ACTION_COL_WIDTH}.
+ * Long labels keep their trailing characters so `view all` still fits the rail.
+ */
+export function contextActionsLine(labels: readonly string[]): string {
+  const text = labels.join(" ")
+  if (text.length >= CONTEXT_ACTION_COL_WIDTH) return text.slice(-CONTEXT_ACTION_COL_WIDTH)
+  return text.padStart(CONTEXT_ACTION_COL_WIDTH)
+}
+
+/** Usable rows in the sidebar slot for a terminal that tall. */
+export function panelRows(termHeight: number): number {
+  const h = Number.isFinite(termHeight) && termHeight > 0 ? termHeight : 24
+  return Math.max(PANEL_MIN_ROWS, Math.floor(h) - PANEL_CHROME)
+}
+
+/** Rows a section keeps before it is worth folding instead. */
+export const ROW_MIN = {
+  delegates: 2,
+  drafts: 2,
+  files: 3,
+  mywork: 2,
+  tools: 3,
+} as const
+
+/**
+ * Higher gives up rows first. Live activity outranks history: on Current the
+ * tool feed survives longest. My work is a queue of things awaiting the user,
+ * so it ties with the live feed.
+ */
+export const ROW_RANK = {
+  delegates: 3,
+  drafts: 3,
+  files: 2,
+  mywork: 1,
+  tools: 1,
+} as const
+
+export type Section<K extends string = string> = {
+  key: K
+  /** Rows the section would like — usually the matching `oes.json` value. */
+  want: number
+  min: number
+  rank: number
+}
+
+/**
+ * Split `budget - fixed` rows across the sections. Ties are broken by whoever
+ * currently holds the most rows, so equal ranks shrink together. A section that
+ * hits `min` while the budget is still short is handed `0` — the caller folds
+ * it rather than rendering a stub.
+ */
+export function packSections<K extends string>(
+  budget: number,
+  fixed: number,
+  sections: readonly Section<K>[],
+): Record<K, number> {
+  const live = sections.map((s) => {
+    const min = Math.max(0, Math.round(s.min))
+    return { key: s.key, min, rank: s.rank, rows: Math.max(min, Math.max(0, Math.round(s.want))) }
+  })
+  const available = Math.max(0, Math.round(budget) - Math.round(fixed))
+  const total = () => live.reduce((sum, s) => sum + s.rows, 0)
+
+  const worstAbove = (floor: (s: (typeof live)[number]) => number): number => {
+    let worst = -1
+    for (let i = 0; i < live.length; i += 1) {
+      const s = live[i]!
+      if (s.rows <= floor(s)) continue
+      const best = worst < 0 ? null : live[worst]!
+      if (!best || s.rank > best.rank || (s.rank === best.rank && s.rows > best.rows)) worst = i
+    }
+    return worst
+  }
+
+  while (total() > available) {
+    const i = worstAbove((s) => s.min)
+    if (i < 0) break
+    live[i]!.rows -= 1
+  }
+
+  // Everyone is at their minimum and it still does not fit: fold, worst first.
+  while (total() > available) {
+    const i = worstAbove(() => 0)
+    if (i < 0) break
+    live[i]!.rows = 0
+  }
+
+  const out = {} as Record<K, number>
+  for (const s of live) out[s.key] = s.rows
+  return out
+}
+
+/**
+ * Look up a packed section. A missing plan (Solid memo still computing,
+ * previous compute threw, owner disposed) or a missing / non-finite key
+ * returns `fallback` — the sidebar slot must not die on `plan[key]`.
+ */
+export function rowsForPlan(
+  plan: Readonly<Record<string, number>> | null | undefined,
+  key: string,
+  fallback: number,
+): number {
+  if (!plan || typeof plan !== "object") return fallback
+  const v = plan[key]
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback
+}
+
+/**
+ * Show `shown` rows and report how many a "more" control can still reveal.
+ * The expander is a separate clickable line (`RowList`) the caller renders
+ * below the list — no row is spent on the note.
+ */
+export function sliceShown<T>(
+  rows: readonly T[],
+  shown: number,
+): { rows: T[]; hidden: number } {
+  const s = Math.max(0, Math.round(shown))
+  const kept = rows.slice(0, s)
+  return { rows: kept, hidden: Math.max(0, rows.length - kept.length) }
+}
+
+/**
+ * Whether the "… +N more" / "… less" line is drawn at all. The expanded toggle
+ * keeps its "… less" line even when nothing is hidden; otherwise the line
+ * vanishes the moment there is nothing left to reveal.
+ */
+export function moreRevealVisible(hidden: number, expanded?: boolean): boolean {
+  return expanded === true || hidden > 0
+}
+
+/**
+ * Clamp a scroll offset into the window a `visible`-row view can show over
+ * `total` rows: the offset never goes below 0 or past the last full window.
+ */
+export function clampScrollOffset(total: number, visible: number, offset: number): number {
+  const t = Math.max(0, Math.round(total))
+  const v = Math.max(1, Math.round(visible))
+  const max = Math.max(0, t - v)
+  const o = Math.max(0, Math.round(offset))
+  return Math.min(o, max)
+}
+
+/**
+ * Move a scroll offset by one wheel `step`. Newest-first lists count the offset
+ * from the newest row, so "down" goes toward older rows and "up" back to the
+ * newest. The result stays inside the same clamped window as `clampScrollOffset`.
+ */
+export function scrollByStep(
+  total: number,
+  visible: number,
+  offset: number,
+  direction: "up" | "down",
+  step: number,
+): number {
+  const s = Math.max(1, Math.round(step))
+  const next = direction === "down" ? offset + s : offset - s
+  return clampScrollOffset(total, visible, next)
+}

package/src/pware.oc.core/pware.oc.core.oes.ts

@@ -1,89 +1,99 @@
-/**
- * oes.json — OpenCode Extended Sidebar options.
- * Merge: plugin defaults < ~/.config/opencode/oes.json < <project>/oes.json
- */
-import path from "node:path"
-import { fileStamp, getOpenCodeConfigDir, pluginRoot, readJson } from "./pware.oc.core.paths.js"
-import { createStampCache } from "./pware.oc.core.cache.js"
-
-export type OesOptions = {
-  fileRows: number
-  /** Sessions compared under Perf → History. 0 hides the section. */
-  perfHistory: number
-  /** Rows per Perf section (models, tools, history). */
-  perfRows: number
-  /** How many recent turns Perf scans. Higher = longer history, slower read. */
-  perfTurns: number
-  /** Seconds between full open-question rescans when no event-driven hint arrives. */
-  questionReconcileSec: number
-  /** Sessions fetched for the recent-sessions window. */
-  sessionFetch: number
-  /** Hide Files that match the project's root .gitignore. Off by default. */
-  skipGitignore: boolean
-  toolRows: number
-  /** Tool-call history kept for the feed's `… +N more` revealer. Distinct from `toolRows`. */
-  toolFetch: number
-}
-
-export const OES_DEFAULTS: OesOptions = {
-  fileRows: 8,
-  perfHistory: 3,
-  perfRows: 5,
-  perfTurns: 120,
-  questionReconcileSec: 15,
-  sessionFetch: 20,
-  skipGitignore: false,
-  toolRows: 5,
-  toolFetch: 20,
-}
-
-function pluginOesPath(): string {
-  return path.join(pluginRoot(), "oes.json")
-}
-
-function clamp(n: unknown, min: number, max: number, fallback: number): number {
-  if (typeof n !== "number" || !Number.isFinite(n)) return fallback
-  return Math.round(Math.min(max, Math.max(min, n)))
-}
-
-/** Merge one oes.json object onto a base. Exported for tests. */
-export function pick(raw: Record<string, unknown> | null, base: OesOptions): OesOptions {
-  if (!raw) return base
-  const toolRows = clamp(raw.toolRows, 3, 20, base.toolRows)
-  return {
-    fileRows: clamp(raw.fileRows, 3, 20, base.fileRows),
-    perfHistory: clamp(raw.perfHistory, 0, 10, base.perfHistory),
-    perfRows: clamp(raw.perfRows, 3, 20, base.perfRows),
-    perfTurns: clamp(raw.perfTurns, 20, 500, base.perfTurns),
-    questionReconcileSec: clamp(raw.questionReconcileSec, 5, 300, base.questionReconcileSec),
-    sessionFetch: clamp(raw.sessionFetch, 2, 80, base.sessionFetch),
-    skipGitignore: typeof raw.skipGitignore === "boolean" ? raw.skipGitignore : base.skipGitignore,
-    toolRows,
-    toolFetch: clamp(raw.toolFetch, toolRows, 80, base.toolFetch),
-  }
-}
-
-export function oesPaths(projectRoot?: string | null): string[] {
-  const out = [pluginOesPath(), path.join(getOpenCodeConfigDir(), "oes.json")]
-  if (projectRoot) out.push(path.join(projectRoot, "oes.json"))
-  return out
-}
-
-export function oesStamp(projectRoot?: string | null): string {
-  return oesPaths(projectRoot).map(fileStamp).join("|")
-}
-
-const oesCache = createStampCache<OesOptions>()
-
-/** Drop the merged-options cache so the next getOes re-reads files. */
-export function resetOesCache(): void {
-  oesCache.reset()
-}
-
-export function getOes(projectRoot?: string | null): OesOptions {
-  return oesCache.get(oesStamp(projectRoot), () => {
-    let next = { ...OES_DEFAULTS }
-    for (const p of oesPaths(projectRoot)) next = pick(readJson(p), next)
-    return next
-  })
-}
+/**
+ * oes.json — OpenCode Extended Sidebar options.
+ * Merge: plugin defaults < ~/.config/opencode/oes.json < <project>/oes.json
+ */
+import path from "node:path"
+import { fileStamp, getOpenCodeConfigDir, pluginRoot, readJson } from "./pware.oc.core.paths.js"
+import { createStampCache } from "./pware.oc.core.cache.js"
+
+export type OesOptions = {
+  fileRows: number
+  /** Sessions compared under Perf → History. 0 hides the section. */
+  perfHistory: number
+  /** Rows per Perf section (models, tools, history). */
+  perfRows: number
+  /** How many recent turns Perf scans. Higher = longer history, slower read. */
+  perfTurns: number
+  /** Seconds between full open-question rescans when no event-driven hint arrives. */
+  questionReconcileSec: number
+  /** Sessions fetched for the recent-sessions window. */
+  sessionFetch: number
+  /** How old (in hours) a session can be before it is dimmed in the recent-sessions window. Always ≤ sessionVisibleHours. */
+  sessionDimHours: number
+  /** How old (in hours) a session can be before it is hidden from the recent-sessions window. */
+  sessionVisibleHours: number
+  /** Hide Files that match the project's root .gitignore. Off by default. */
+  skipGitignore: boolean
+  toolRows: number
+  /** Tool-call history kept for the feed's `… +N more` revealer. Distinct from `toolRows`. */
+  toolFetch: number
+}
+
+export const OES_DEFAULTS: OesOptions = {
+  fileRows: 8,
+  perfHistory: 3,
+  perfRows: 5,
+  perfTurns: 120,
+  questionReconcileSec: 15,
+  sessionDimHours: 48,
+  sessionFetch: 10,
+  sessionVisibleHours: 72,
+  skipGitignore: false,
+  toolRows: 5,
+  toolFetch: 20,
+}
+
+function pluginOesPath(): string {
+  return path.join(pluginRoot(), "oes.json")
+}
+
+function clamp(n: unknown, min: number, max: number, fallback: number): number {
+  if (typeof n !== "number" || !Number.isFinite(n)) return fallback
+  return Math.round(Math.min(max, Math.max(min, n)))
+}
+
+/** Merge one oes.json object onto a base. Exported for tests. */
+export function pick(raw: Record<string, unknown> | null, base: OesOptions): OesOptions {
+  if (!raw) return base
+  const toolRows = clamp(raw.toolRows, 3, 20, base.toolRows)
+  const sessionVisibleHours = clamp(raw.sessionVisibleHours, 1, 720, base.sessionVisibleHours)
+  const sessionDimHours = clamp(raw.sessionDimHours, 0, sessionVisibleHours, Math.min(base.sessionDimHours, sessionVisibleHours))
+  return {
+    fileRows: clamp(raw.fileRows, 3, 20, base.fileRows),
+    perfHistory: clamp(raw.perfHistory, 0, 10, base.perfHistory),
+    perfRows: clamp(raw.perfRows, 3, 20, base.perfRows),
+    perfTurns: clamp(raw.perfTurns, 20, 500, base.perfTurns),
+    questionReconcileSec: clamp(raw.questionReconcileSec, 5, 300, base.questionReconcileSec),
+    sessionDimHours,
+    sessionFetch: clamp(raw.sessionFetch, 2, 80, base.sessionFetch),
+    sessionVisibleHours,
+    skipGitignore: typeof raw.skipGitignore === "boolean" ? raw.skipGitignore : base.skipGitignore,
+    toolRows,
+    toolFetch: clamp(raw.toolFetch, toolRows, 80, base.toolFetch),
+  }
+}
+
+export function oesPaths(projectRoot?: string | null): string[] {
+  const out = [pluginOesPath(), path.join(getOpenCodeConfigDir(), "oes.json")]
+  if (projectRoot) out.push(path.join(projectRoot, "oes.json"))
+  return out
+}
+
+export function oesStamp(projectRoot?: string | null): string {
+  return oesPaths(projectRoot).map(fileStamp).join("|")
+}
+
+const oesCache = createStampCache<OesOptions>()
+
+/** Drop the merged-options cache so the next getOes re-reads files. */
+export function resetOesCache(): void {
+  oesCache.reset()
+}
+
+export function getOes(projectRoot?: string | null): OesOptions {
+  return oesCache.get(oesStamp(projectRoot), () => {
+    let next = { ...OES_DEFAULTS }
+    for (const p of oesPaths(projectRoot)) next = pick(readJson(p), next)
+    return next
+  })
+}