Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(chat): gate opencode exports on a db stat, space live refreshes, honour page size
review9827f3ffaf1b
diff --git a/CLAUDE.md b/CLAUDE.mdindex f7547f9dd..64b355494 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1882,15 +1882,26 @@ else, and its context links must keep classifying across restarts).`Error: …` on a failed call), `[name] message` for an errored turn, compaction/subtask chips,`at` from `time.created`, `model`/`effort` from the newest assistant's `modelID`/`variant`.Reasoning, `synthetic`/`ignored` text, file/agent parts and step bookkeeping are dropped;- unmappable shapes are skipped and counted. **One page, always** (`olderCursor: null`, newest- messages within 5 MB): there are no byte offsets to page by. Refusals: no/unsafe session id runs+ unmappable shapes are skipped and counted. **One page, always** (`olderCursor: null`): there are+ no byte offsets to page by. The page honours the caller's `maxBytes` (the phone asks 256 KB),+ grows ×4 up to 5 MB like claude's reader when it holds no whole message, and shows a newest+ message larger than 5 MB TRUNCATED (with a note) rather than as an empty conversation. Refusals: no/unsafe session id runsnothing (a bare `opencode export` opens a picker over the NEWEST sessions — someone else's); anexport whose `info.id` is another session is `unreadable`; only `Session not found: <id>` withexit 1 and empty stdout is a clean miss. **Remote (SSH) nodes are refused** (`unreadable`, noexport runs) — their sessions are in the host's database and there is no remote leg yet; thepanel's copy names both causes an opencode `unreadable` can have. One export costs 1.0–1.7 s and- ~320 MB, so `createOpencodeExportGate` runs at most one per session (starts ≥ 2 s apart, a caller- arriving mid-run gets a FRESH export, never a cached one) and two in total. Plan/question answer+ ~320 MB, so `createOpencodeExportGate` runs at most one per session (a caller arriving mid-run+ gets a FRESH export) and two in total; the panel's hook-driven refreshes are marked+ `page.background` and spaced ≥ 5 s per session, while an open / ↻ / Retry is immediate (and wakes+ a sleeping background one). A **change gate** in front of it `stat`s (never opens) opencode's+ `opencode*.db` + `-wal` in `$XDG_DATA_HOME/opencode` (else `~/.local/share/opencode`, opencode's+ own xdg-basedir rule) BEFORE exporting, and an unchanged fingerprint answers from a 4-session LRU+ of parsed exports; no db file found, or `OPENCODE_DB` set, means no caching. The export runs with+ `cwd: os.tmpdir()` (from a repo cwd opencode writes `<repo>/.git/opencode`; sessions resolve by+ global id). **It inherits the APP's `process.env`, not the node's shell env**: a user who+ relocates opencode's data via `XDG_DATA_HOME` / `OPENCODE_*` only in their shell rc gets+ "Session not found" — an honest miss, not a bug in the reader. Plan/question answercards stay claude-only (no `body`/`questions` on opencode's `question` tool). Desktop and ServerEdition both serve it (core handler); the phone gets it over the relay `chat.page` for free.Fixtures + the exact rules for the iOS port: `src/shared/chat-fixtures/opencode/README.md`.diff --git a/src/core/opencode-chat-cache.test.ts b/src/core/opencode-chat-cache.test.tsnew file mode 100644index 000000000..b9a15e1fa--- /dev/null+++ b/src/core/opencode-chat-cache.test.ts@@ -0,0 +1,246 @@+// Review fixes for the opencode ⌘M reader: the stat change gate + bounded parsed cache, the+// background-refresh spacing, and the page-size contract (`page.maxBytes`, an oversized newest+// message). Synthetic data only.+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import fs from 'fs'+import os from 'os'+import path from 'path'+import {+ createOpencodeChatCache,+ createOpencodeExportGate,+ opencodeDataDir,+ opencodeDbFingerprint,+ readOpencodeChat+} from './opencode-chat'+import { normalizeChatPage } from '../shared/chat-page'+import type { OpencodeExportOutcome } from './opencode-export'+import type { ChatMessage } from '../shared/types'++const SID = 'ses_0a1b2c3d4ffeSynthetic000001'+const doc = (messages: unknown[]): string =>+ JSON.stringify({ info: { id: SID }, messages }, null, 2) + '\n'+const msg = (i: number, role: 'user' | 'assistant', t: string) => ({+ info: { id: `msg_${i}`, sessionID: SID, role, time: { created: i } },+ parts: [{ id: `prt_${i}`, type: 'text', text: t }]+})+const textOf = (m: ChatMessage) => (m.parts[0] as { text: string }).text++describe('opencodeDataDir — the same resolution opencode uses (xdg-basedir)', () => {+ it('XDG_DATA_HOME wins, else ~/.local/share; "opencode" under it', () => {+ expect(opencodeDataDir({ XDG_DATA_HOME: '/x/data' }, '/home/u')).toBe(path.join('/x/data', 'opencode'))+ expect(opencodeDataDir({}, '/home/u')).toBe(path.join('/home/u', '.local', 'share', 'opencode'))+ expect(opencodeDataDir({ XDG_DATA_HOME: '' }, '/home/u')).toBe(path.join('/home/u', '.local', 'share', 'opencode'))+ })+})++describe('opencodeDbFingerprint — stat, never open', () => {+ let dir: string+ beforeEach(() => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-oc-fp-'))+ })+ afterEach(() => fs.rmSync(dir, { recursive: true, force: true }))++ it('changes when the WAL changes, and is stable otherwise', async () => {+ fs.writeFileSync(path.join(dir, 'opencode.db'), 'a')+ fs.writeFileSync(path.join(dir, 'opencode.db-wal'), 'w')+ const a = await opencodeDbFingerprint(dir, {})+ expect(a).not.toBeNull()+ expect(await opencodeDbFingerprint(dir, {})).toBe(a)+ fs.appendFileSync(path.join(dir, 'opencode.db-wal'), 'more')+ expect(await opencodeDbFingerprint(dir, {})).not.toBe(a)+ })++ it('a missing WAL is a state, not a failure; the db changing changes it', async () => {+ fs.writeFileSync(path.join(dir, 'opencode.db'), 'a')+ const a = await opencodeDbFingerprint(dir, {})+ expect(a).not.toBeNull()+ fs.appendFileSync(path.join(dir, 'opencode.db'), 'b')+ expect(await opencodeDbFingerprint(dir, {})).not.toBe(a)+ })++ it('covers a channel-named database too (opencode-<channel>.db)', async () => {+ fs.writeFileSync(path.join(dir, 'opencode-dev.db'), 'a')+ const a = await opencodeDbFingerprint(dir, {})+ expect(a).not.toBeNull()+ fs.writeFileSync(path.join(dir, 'opencode-dev.db-wal'), 'w')+ expect(await opencodeDbFingerprint(dir, {})).not.toBe(a)+ })++ it('cannot gate (null) with no database, an unreadable dir, or an OPENCODE_DB override', async () => {+ expect(await opencodeDbFingerprint(dir, {})).toBeNull()+ expect(await opencodeDbFingerprint(path.join(dir, 'nope'), {})).toBeNull()+ fs.writeFileSync(path.join(dir, 'opencode.db'), 'a')+ expect(await opencodeDbFingerprint(dir, { OPENCODE_DB: '/elsewhere.db' })).toBeNull()+ })+})++describe('readOpencodeChat — the change gate', () => {+ const page = normalizeChatPage({ maxBytes: 262144 })+ const OK = doc([msg(1, 'user', 'hi'), msg(2, 'assistant', 'yo')])++ it('an unchanged database answers from the cache: no second export', async () => {+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout: OK }))+ const cache = createOpencodeChatCache({ fingerprint: async () => 'fp1', maxSessions: 4 })+ const a = await readOpencodeChat({ sessionId: SID }, page, run, cache)+ const b = await readOpencodeChat({ sessionId: SID }, page, run, cache)+ expect(b).toStrictEqual(a)+ expect(a.messages).toHaveLength(2)+ expect(run).toHaveBeenCalledTimes(1)+ })++ it('a changed database exports again', async () => {+ let fp = 'fp1'+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout: OK }))+ const cache = createOpencodeChatCache({ fingerprint: async () => fp, maxSessions: 4 })+ await readOpencodeChat({ sessionId: SID }, page, run, cache)+ fp = 'fp2'+ await readOpencodeChat({ sessionId: SID }, page, run, cache)+ expect(run).toHaveBeenCalledTimes(2)+ })++ it('the fingerprint is taken BEFORE the export (a write during it forces the next export)', async () => {+ const order: string[] = []+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => {+ order.push('export')+ return { ok: true, stdout: OK }+ })+ const cache = createOpencodeChatCache({+ fingerprint: async () => {+ order.push('stat')+ return 'fp'+ },+ maxSessions: 4+ })+ await readOpencodeChat({ sessionId: SID }, page, run, cache)+ expect(order).toEqual(['stat', 'export'])+ })++ it('no fingerprint (cannot gate) never caches; a failure is never cached', async () => {+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout: OK }))+ const nullCache = createOpencodeChatCache({ fingerprint: async () => null, maxSessions: 4 })+ await readOpencodeChat({ sessionId: SID }, page, run, nullCache)+ await readOpencodeChat({ sessionId: SID }, page, run, nullCache)+ expect(run).toHaveBeenCalledTimes(2)++ const flaky = vi+ .fn<() => Promise<OpencodeExportOutcome>>()+ .mockResolvedValueOnce({ ok: false })+ .mockResolvedValueOnce({ ok: true, stdout: OK })+ const cache = createOpencodeChatCache({ fingerprint: async () => 'fp', maxSessions: 4 })+ expect((await readOpencodeChat({ sessionId: SID }, page, flaky, cache)).found).toBe(false)+ expect((await readOpencodeChat({ sessionId: SID }, page, flaky, cache)).found).toBe(true)+ expect(flaky).toHaveBeenCalledTimes(2)+ })++ it('is bounded: least-recently-used session evicted', async () => {+ const ids = ['ses_a', 'ses_b', 'ses_c']+ const run = vi.fn(async (id: string): Promise<OpencodeExportOutcome> => ({+ ok: true,+ stdout: JSON.stringify({ info: { id }, messages: [] })+ }))+ const cache = createOpencodeChatCache({ fingerprint: async () => 'fp', maxSessions: 2 })+ await readOpencodeChat({ sessionId: ids[0] }, page, run, cache)+ await readOpencodeChat({ sessionId: ids[1] }, page, run, cache)+ await readOpencodeChat({ sessionId: ids[0] }, page, run, cache) // hit; a is now most recent+ await readOpencodeChat({ sessionId: ids[2] }, page, run, cache) // evicts b+ expect(run).toHaveBeenCalledTimes(3)+ await readOpencodeChat({ sessionId: ids[0] }, page, run, cache)+ expect(run).toHaveBeenCalledTimes(3)+ await readOpencodeChat({ sessionId: ids[1] }, page, run, cache)+ expect(run).toHaveBeenCalledTimes(4)+ })++ it('passes background to the runner so the gate can space live refreshes', async () => {+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout: OK }))+ await readOpencodeChat({ sessionId: SID }, normalizeChatPage({ maxBytes: 262144, background: true }), run, null)+ await readOpencodeChat({ sessionId: SID }, page, run, null)+ expect(run.mock.calls).toEqual([+ [SID, { background: true }],+ [SID, { background: false }]+ ])+ })+})++describe('normalizeChatPage — background', () => {+ it('only a literal true marks a read as background', () => {+ expect(normalizeChatPage({ background: true })?.background).toBe(true)+ expect(normalizeChatPage({ background: 'yes' })).not.toHaveProperty('background')+ expect(normalizeChatPage({})).not.toHaveProperty('background')+ })+})++describe('createOpencodeExportGate — background spacing', () => {+ const flush = () => new Promise((r) => setTimeout(r, 0))++ it('a background refresh waits the background spacing; an explicit read does not wait', async () => {+ let t = 10_000+ const sleeps: number[] = []+ const run = vi.fn(async () => ({ ok: true as const, stdout: 'x' }))+ const gate = createOpencodeExportGate(run, {+ minSpacingMs: 0,+ backgroundSpacingMs: 5000,+ maxConcurrent: 2,+ now: () => t,+ sleep: async (ms) => {+ sleeps.push(ms)+ t += ms+ }+ })+ await gate(SID)+ t += 1000+ await gate(SID, { background: true })+ expect(sleeps).toEqual([4000])+ t += 1000+ await gate(SID)+ expect(sleeps).toEqual([4000])+ expect(run).toHaveBeenCalledTimes(3)+ })++ it('an explicit read joining a sleeping background refresh wakes it', async () => {+ const run = vi.fn(async () => ({ ok: true as const, stdout: 'x' }))+ const never = new Promise<void>(() => {})+ const gate = createOpencodeExportGate(run, {+ minSpacingMs: 0,+ backgroundSpacingMs: 5000,+ maxConcurrent: 2,+ sleep: () => never+ })+ await gate(SID)+ const bg = gate(SID, { background: true })+ await flush()+ expect(run).toHaveBeenCalledTimes(1)+ const explicit = gate(SID)+ expect(await explicit).toEqual({ ok: true, stdout: 'x' })+ expect(await bg).toEqual({ ok: true, stdout: 'x' })+ expect(run).toHaveBeenCalledTimes(2)+ })+})++describe('readOpencodeChat — page size', () => {+ const run = (stdout: string) => async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout })++ it('honours a smaller page.maxBytes (the phone asks for 256 KB)', async () => {+ const stdout = doc([1, 2, 3, 4].map((i) => msg(i, 'assistant', String(i).repeat(100 * 1024))))+ const res = await readOpencodeChat({ sessionId: SID }, normalizeChatPage({ maxBytes: 262144 }), run(stdout), null)+ expect(res.messages.map((m) => textOf(m)[0])).toEqual(['3', '4'])+ })++ it('a newest message bigger than the page grows the window like claude (×4 up to 5 MB)', async () => {+ const stdout = doc([1, 2, 3].map((i) => msg(i, 'assistant', String(i).repeat(400 * 1024))))+ const res = await readOpencodeChat({ sessionId: SID }, normalizeChatPage({ maxBytes: 262144 }), run(stdout), null)+ // 256 KB holds none; 1 MB holds the two newest.+ expect(res.messages.map((m) => textOf(m)[0])).toEqual(['2', '3'])+ expect(textOf(res.messages[1])).toHaveLength(400 * 1024)+ })++ it('a newest message bigger than 5 MB is shown TRUNCATED, never as an empty conversation', async () => {+ const stdout = doc([msg(1, 'user', 'q'), msg(2, 'assistant', 'z'.repeat(6 * 1024 * 1024))])+ const res = await readOpencodeChat({ sessionId: SID }, normalizeChatPage({ maxBytes: 262144 }), run(stdout), null)+ expect(res.found).toBe(true)+ expect(res.messages).toHaveLength(1)+ const t = textOf(res.messages[0])+ expect(t.startsWith('zzz')).toBe(true)+ expect(t).toMatch(/truncated/)+ expect(Buffer.byteLength(JSON.stringify(res.messages[0]))).toBeLessThanOrEqual(5 * 1024 * 1024)+ })+})diff --git a/src/core/opencode-chat.test.ts b/src/core/opencode-chat.test.tsindex 6db647d83..0aac21073 100644--- a/src/core/opencode-chat.test.ts+++ b/src/core/opencode-chat.test.ts@@ -416,7 +416,7 @@ describe('readChatTranscript — opencode', () => {model: 'm1',effort: 'low'})- expect(opencodeExport).toHaveBeenCalledWith(SID)+ expect(opencodeExport).toHaveBeenCalledWith(SID, { background: false })})it('an unpaged read keeps the legacy shape exactly', async () => {@@ -486,11 +486,15 @@ describe('readChatTranscript — opencode', () => {}})- it('keeps a page within the legacy 5 MB cap: the newest messages, in order', async () => {+ it('a page too small for one message grows like claude\'s (×4); the legacy read keeps 5 MB', async () => {const big = (i: number) => asst(`msg_${i}`, [text(String(i).repeat(1024 * 1024))])const stdout = doc([1, 2, 3, 4, 5, 6].map(big))- const res = await read({ sessionId: SID, agentId: 'opencode' }, { maxBytes: 262144 }, { opencodeExport: exportOf({ ok: true, stdout }) })- expect(res.messages.map((m) => (m.parts[0] as { text: string }).text[0])).toEqual(['3', '4', '5', '6'])+ const first = (r: { messages: ChatMessage[] }) => r.messages.map((m) => (m.parts[0] as { text: string }).text[0])+ // 256 KB and 1 MB hold no whole ~1 MB message; 4 MB holds three.+ const paged = await read({ sessionId: SID, agentId: 'opencode' }, { maxBytes: 262144 }, { opencodeExport: exportOf({ ok: true, stdout }) })+ expect(first(paged)).toEqual(['4', '5', '6'])+ const legacy = await read({ sessionId: SID, agentId: 'opencode' }, undefined, { opencodeExport: exportOf({ ok: true, stdout }) })+ expect(first(legacy)).toEqual(['3', '4', '5', '6'])})it('an OLDER-page request has nothing older to give, and costs no export', async () => {diff --git a/src/core/opencode-chat.ts b/src/core/opencode-chat.tsindex c91af8946..9698856e4 100644--- a/src/core/opencode-chat.ts+++ b/src/core/opencode-chat.ts@@ -28,6 +28,9 @@//// Every mapping rule is written down in `src/shared/chat-fixtures/opencode/README.md` for the iOS// port, and pinned by the golden fixtures there.+import fs from 'fs'+import os from 'os'+import path from 'path'import type { ChatMessage, ChatPart, ChatTranscriptResult } from '../shared/types'import { CHAT_TOOL_ARG_MAX } from '../shared/chat-command'import { CHAT_PAGE_MAX_BYTES, type ChatTranscriptPage } from '../shared/chat-page'@@ -222,9 +225,8 @@ export function parseOpencodeExport(raw: string, sessionId: string): OpencodeChareturn out}-/** The newest messages whose JSON fits in `maxBytes` (UTF-8), in order. One export is one page,- * and a page stays within the legacy read's cap (`CHAT_PAGE_MAX_BYTES`) — it crosses the relay- * to a phone. Like grok's capped tail, the cut is not announced (`olderCursor` stays null). */+/** The newest messages whose JSON fits in `maxBytes` (UTF-8), in order. Like grok's capped tail,+ * the cut is not announced (`olderCursor` stays null). */export function newestWithinBytes(messages: ChatMessage[], maxBytes: number): ChatMessage[] {let total = 0let i = messages.length@@ -237,13 +239,159 @@ export function newestWithinBytes(messages: ChatMessage[], maxBytes: number): Chreturn messages.slice(i)}+/** Same growth as claude's paged reader (`parseGrowingWindow`): a page that holds no whole message+ * is re-evaluated at ×4 the size, up to the legacy 5 MB cap. */+const PAGE_GROWTH = 4++const TRUNCATED_NOTE = (droppedBytes: number) =>+ `\n\n[… truncated: ${Math.ceil(droppedBytes / 1024)} KB more of this message is only in opencode]`++/** `text` cut to at most `maxBytes` UTF-8 bytes, never splitting a surrogate pair. */+function cutToBytes(text: string, maxBytes: number): string {+ if (maxBytes <= 0) return ''+ if (Buffer.byteLength(text) <= maxBytes) return text+ let lo = 0+ let hi = Math.min(text.length, maxBytes)+ while (lo < hi) {+ const mid = Math.ceil((lo + hi) / 2)+ if (Buffer.byteLength(text.slice(0, mid)) <= maxBytes) lo = mid+ else hi = mid - 1+ }+ let out = text.slice(0, lo)+ const last = out.charCodeAt(out.length - 1)+ if (last >= 0xd800 && last <= 0xdbff) out = out.slice(0, -1)+ return out+}++/**+ * One message too big for the largest page: its text parts cut (largest first) until its JSON fits+ * `maxBytes`, each cut announced in the text itself. Better than the alternative the byte budget+ * leaves — `messages: []` with `found: true`, which reads as an empty conversation. Tool chips are+ * already bounded (arg 200, result 500 units), so text is the only thing that can be this big.+ */+export function truncateMessage(m: ChatMessage, maxBytes: number): ChatMessage {+ const parts = m.parts.map((p) => ({ ...p }))+ const size = () => Buffer.byteLength(JSON.stringify({ ...m, parts }))+ // JSON escaping can make a text's serialized form larger than its UTF-8 bytes, so iterate.+ for (let guard = 0; guard < 8 && size() > maxBytes; guard++) {+ let idx = -1+ for (let i = 0; i < parts.length; i++) {+ const p = parts[i]+ if (p.kind === 'text' && (idx < 0 || p.text.length > (parts[idx] as { text: string }).text.length)) idx = i+ }+ if (idx < 0) break+ const p = parts[idx] as Extract<ChatPart, { kind: 'text' }>+ const over = size() - maxBytes+ const full = Buffer.byteLength(p.text)+ const note = TRUNCATED_NOTE(full)+ const keep = Math.max(0, full - over - Buffer.byteLength(JSON.stringify(note)) - 64 * (guard + 1))+ const kept = cutToBytes(p.text, keep)+ p.text = kept + TRUNCATED_NOTE(full - Buffer.byteLength(kept))+ }+ return { ...m, parts }+}++/**+ * The messages a page answers with. `maxBytes` is the caller's own window (the panel's tail read,+ * the phone's 256 KB) and is honoured; when it holds no whole message the window grows exactly as+ * claude's does (×4, up to 5 MB); a newest message bigger even than that is shown truncated.+ */+export function opencodePageMessages(messages: ChatMessage[], maxBytes: number): ChatMessage[] {+ if (!messages.length) return []+ let bytes = Math.min(maxBytes, CHAT_PAGE_MAX_BYTES)+ for (;;) {+ const out = newestWithinBytes(messages, bytes)+ if (out.length) return out+ if (bytes >= CHAT_PAGE_MAX_BYTES) break+ bytes = Math.min(CHAT_PAGE_MAX_BYTES, bytes * PAGE_GROWTH)+ }+ return [truncateMessage(messages[messages.length - 1], CHAT_PAGE_MAX_BYTES)]+}++// ── The change gate: stat opencode's database, never open it ─────────────────────────────────++/** opencode's data directory, resolved the way opencode resolves it (xdg-basedir's `xdgData`:+ * `$XDG_DATA_HOME`, else `~/.local/share` — on every platform) plus `opencode`. */+export function opencodeDataDir(env: NodeJS.ProcessEnv = process.env, home: string = os.homedir()): string {+ const base = env.XDG_DATA_HOME ? env.XDG_DATA_HOME : path.join(home, '.local', 'share')+ return path.join(base, 'opencode')+}++/** `opencode.db`, a channel build's `opencode-<channel>.db`, and their WALs. */+const OPENCODE_DB_FILE = /^opencode(-[A-Za-z0-9._-]+)?\.db(-wal)?$/++/**+ * A fingerprint of opencode's session store: size, mtime (ns), ctime and inode of every database+ * and WAL file in `dir`, from `readdir` + `stat` — the database itself is never opened (it also+ * holds opencode's account tokens). `null` = we cannot vouch for the store, so nothing is cached:+ * no database file found (a relocated store we would otherwise see as "never changes"), the+ * directory unreadable, or `OPENCODE_DB` pointing opencode somewhere else.+ */+export async function opencodeDbFingerprint(+ dir: string = opencodeDataDir(),+ env: NodeJS.ProcessEnv = process.env+): Promise<string | null> {+ if (env.OPENCODE_DB) return null+ try {+ const names = (await fs.promises.readdir(dir)).filter((n) => OPENCODE_DB_FILE.test(n)).sort()+ if (!names.some((n) => n.endsWith('.db'))) return null+ const rows = await Promise.all(+ names.map(async (n) => {+ const st = await fs.promises.stat(path.join(dir, n), { bigint: true })+ return `${n}:${st.size}:${st.mtimeNs}:${st.ctimeNs}:${st.ino}`+ })+ )+ return rows.join('|')+ } catch {+ return null+ }+}++export interface OpencodeChatCache {+ fingerprint(): Promise<string | null>+ get(sessionId: string, fingerprint: string): OpencodeChatParse | undefined+ set(sessionId: string, fingerprint: string, parsed: OpencodeChatParse): void+}++/** A few sessions' parsed exports, keyed by the store fingerprint taken BEFORE their export, LRU. */+export function createOpencodeChatCache(opts: {+ fingerprint: () => Promise<string | null>+ maxSessions: number+}): OpencodeChatCache {+ const entries = new Map<string, { fingerprint: string; parsed: OpencodeChatParse }>()+ return {+ fingerprint: opts.fingerprint,+ get(sessionId, fingerprint) {+ const e = entries.get(sessionId)+ if (!e || e.fingerprint !== fingerprint) return undefined+ entries.delete(sessionId)+ entries.set(sessionId, e)+ return e.parsed+ },+ set(sessionId, fingerprint, parsed) {+ entries.delete(sessionId)+ entries.set(sessionId, { fingerprint, parsed })+ while (entries.size > opts.maxSessions) entries.delete(entries.keys().next().value as string)+ }+ }+}++let defaultCache: OpencodeChatCache | undefined+export function defaultOpencodeChatCache(): OpencodeChatCache {+ defaultCache ??= createOpencodeChatCache({ fingerprint: () => opencodeDbFingerprint(), maxSessions: 4 })+ return defaultCache+}+// ── The export gate ─────────────────────────────────────────────────────────────────────────────-export type OpencodeExportRun = (sessionId: string) => Promise<OpencodeExportOutcome>+export type OpencodeExportRun = (sessionId: string, opts?: { background?: boolean }) => Promise<OpencodeExportOutcome>export interface OpencodeExportGateOptions {- /** Minimum time between two export STARTS for one session. */+ /** Minimum time between two export STARTS for one session, for a read the user asked for. */minSpacingMs: number+ /** The same, for a BACKGROUND live refresh (hook-driven, while the agent works). Defaults to+ * `minSpacingMs`. An explicit read joining a background refresh still sleeping wakes it. */+ backgroundSpacingMs?: number/** Most exports running at once, across sessions. */maxConcurrent: numbernow?: () => number@@ -257,14 +405,23 @@ export interface OpencodeExportGateOptions {* - joins a caller to an export that has not STARTED yet (its answer is still fresh for them);* - gives a caller arriving while one RUNS a new export started after it — never a stale answer,* which would leave the panel's final turn-end read one turn behind — shared by every such caller;- * - spaces starts for one session by `minSpacingMs`, and caps exports running at once;- * - caches nothing: a failure is answered once and the next call runs again.+ * - spaces starts for one session by `minSpacingMs` (an explicit read) or `backgroundSpacingMs`+ * (a live refresh), and caps exports running at once;+ * - caches nothing itself: a failure is answered once and the next call runs again. Answering an+ * UNCHANGED store without exporting is the change gate's job (`opencodeDbFingerprint`).*/export function createOpencodeExportGate(run: OpencodeExportRun, opts: OpencodeExportGateOptions): OpencodeExportRun {const now = opts.now ?? Date.nowconst sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))+ const bgSpacing = opts.backgroundSpacingMs ?? opts.minSpacingMs+ const longest = Math.max(opts.minSpacingMs, bgSpacing)+ interface Waiting {+ job: Promise<OpencodeExportOutcome>+ background: boolean+ wake: () => void+ }interface Session {- waiting?: Promise<OpencodeExportOutcome>+ waiting?: Waitingrunning?: Promise<OpencodeExportOutcome>lastStart: number}@@ -286,11 +443,11 @@ export function createOpencodeExportGate(run: OpencodeExportRun, opts: OpencodeEconst prune = (): void => {const t = now()for (const [id, s] of sessions) {- if (!s.waiting && !s.running && t - s.lastStart > opts.minSpacingMs) sessions.delete(id)+ if (!s.waiting && !s.running && t - s.lastStart > longest) sessions.delete(id)}}- return (sessionId) => {+ return (sessionId, callOpts) => {prune()let s = sessions.get(sessionId)if (!s) {@@ -298,16 +455,26 @@ export function createOpencodeExportGate(run: OpencodeExportRun, opts: OpencodeEsessions.set(sessionId, s)}const st = s- if (st.waiting) return st.waiting+ const background = callOpts?.background === true+ if (st.waiting) {+ // An open or Retry the user asked for is not held behind a background refresh's spacing.+ if (!background && st.waiting.background) {+ st.waiting.background = false+ st.waiting.wake()+ }+ return st.waiting.job+ }+ let wake!: () => void+ const woken = new Promise<void>((r) => (wake = r))+ const w = { background, wake } as Waiting// Assigned before its body's first `await` returns, so the body can recognise itself.- let job!: Promise<OpencodeExportOutcome>- job = (async () => {+ w.job = (async () => {if (st.running) await st.running- const wait = st.lastStart + opts.minSpacingMs - now()- if (wait > 0) await sleep(wait)+ const wait = st.lastStart + (w.background ? bgSpacing : opts.minSpacingMs) - now()+ if (wait > 0) await Promise.race([sleep(wait), woken])await acquire()// Started: later callers get the NEXT export, not this one.- if (st.waiting === job) st.waiting = undefined+ if (st.waiting === w) st.waiting = undefinedst.lastStart = now()const running = (async (): Promise<OpencodeExportOutcome> => {try {@@ -323,8 +490,8 @@ export function createOpencodeExportGate(run: OpencodeExportRun, opts: OpencodeEif (st.running === running) st.running = undefinedreturn out})()- st.waiting = job- return job+ st.waiting = w+ return w.job}}@@ -340,7 +507,9 @@ export function defaultOpencodeExport(): OpencodeExportRun {const bin = await findInLoginPath('opencode')return bin ? runOpencodeExportAt(bin, sessionId, OPENCODE_CHAT_EXPORT_TIMEOUT_MS) : { ok: false }},- { minSpacingMs: 2000, maxConcurrent: 2 }+ // A read the user asked for (open, ↻, Retry) is immediate; the panel's hook-driven refreshes+ // during a turn are spaced to one export per 5 s per session.+ { minSpacingMs: 0, backgroundSpacingMs: 5000, maxConcurrent: 2 })return defaultExport}@@ -362,8 +531,12 @@ export function defaultOpencodeExport(): OpencodeExportRun {export async function readOpencodeChat(q: { sessionId?: string; remoteOnly?: boolean },page: ChatTranscriptPage | null,- run: OpencodeExportRun = defaultOpencodeExport()+ run?: OpencodeExportRun,+ cache?: OpencodeChatCache | null): Promise<ChatTranscriptResult> {+ // An injected runner (a test seam) gets no cache unless one is passed with it.+ const exportRun = run ?? defaultOpencodeExport()+ const store = cache === undefined ? (run ? null : defaultOpencodeChatCache()) : cacheconst notFound = (): ChatTranscriptResult =>page ? { messages: [], found: false, olderCursor: null, unmatchedResults: [] } : { messages: [], found: false }const unreadable = (): ChatTranscriptResult => (page ? { ...notFound(), unreadable: true } : notFound())@@ -371,11 +544,19 @@ export async function readOpencodeChat(if (page && page.before !== null) return { messages: [], found: true, olderCursor: null, unmatchedResults: [] }const sessionId = q.sessionIdif (!sessionId || !isSafeOpencodeSessionId(sessionId)) return notFound()- const out = await run(sessionId)- if (!out.ok) return out.absent ? notFound() : unreadable()- const parsed = parseOpencodeExport(out.stdout, sessionId)- if (!parsed) return unreadable()- const messages = newestWithinBytes(parsed.messages, CHAT_PAGE_MAX_BYTES)+ // Taken BEFORE the export: a write that lands while it runs changes the next fingerprint, so the+ // next read exports again rather than serving this (possibly older) answer.+ const fingerprint = store ? await store.fingerprint() : null+ let parsed = fingerprint !== null && store ? store.get(sessionId, fingerprint) : undefined+ if (!parsed) {+ const out = await exportRun(sessionId, { background: page?.background === true })+ if (!out.ok) return out.absent ? notFound() : unreadable()+ const fresh = parseOpencodeExport(out.stdout, sessionId)+ if (!fresh) return unreadable()+ parsed = fresh+ if (fingerprint !== null && store) store.set(sessionId, fingerprint, fresh)+ }+ const messages = opencodePageMessages(parsed.messages, page ? page.maxBytes : CHAT_PAGE_MAX_BYTES)if (!page) return { messages, found: true }return {messages,diff --git a/src/core/opencode-export.test.ts b/src/core/opencode-export.test.tsindex 2c13f7b5f..a6bede7d8 100644--- a/src/core/opencode-export.test.ts+++ b/src/core/opencode-export.test.ts@@ -84,6 +84,14 @@ describe('runOpencodeExportAt — the tri-state', () => {expect(Date.now() - t0).toBeLessThan(10_000)})+ it('runs outside the app cwd (os.tmpdir), so opencode never bootstraps inside a repo', async () => {+ // Run from inside a repo, an export writes `<repo>/.git/opencode`. Sessions resolve by their+ // global id, so the cwd carries no meaning for the read.+ const bin = writeFakeOpencode(dir, 'process.stdout.write(process.cwd())\n')+ const out = await runOpencodeExportAt(bin, SID, 10_000)+ expect(out.ok && fs.realpathSync(out.stdout)).toBe(fs.realpathSync(os.tmpdir()))+ })+it('a binary that does not exist is a failure', async () => {expect(await runOpencodeExportAt(path.join(dir, 'nope'), SID, 10_000)).toEqual({ ok: false })})diff --git a/src/core/opencode-export.ts b/src/core/opencode-export.tsindex e29a42fbf..86a768f92 100644--- a/src/core/opencode-export.ts+++ b/src/core/opencode-export.ts@@ -11,6 +11,7 @@// option exits 1 (yargs strict), so no flag is passed that an older CLI might not know. One export// costs 1.0–1.7 s wall and ~320 MB peak RSS on this host, which is why the chat view gates it// (`createOpencodeExportGate`).+import os from 'os'import { directExecutableInvocation } from './exec-path'/** An export names ONE provider session. The id reaches us from a hook payload, so it is re-checked@@ -53,6 +54,10 @@ export async function runOpencodeExportAt(invocation.args,{...invocation.options,+ // Never the app's cwd: opencode bootstraps a project for its cwd and, inside a git repo,+ // writes `<repo>/.git/opencode`. An export resolves the session by its GLOBAL id, so a+ // neutral directory changes nothing about what is read.+ cwd: os.tmpdir(),encoding: 'utf-8',maxBuffer: OPENCODE_EXPORT_MAX_BYTES,timeout: timeoutMsdiff --git a/src/renderer/nodes/ChatPanel.live.test.tsx b/src/renderer/nodes/ChatPanel.live.test.tsxindex 3711a1108..33d68064e 100644--- a/src/renderer/nodes/ChatPanel.live.test.tsx+++ b/src/renderer/nodes/ChatPanel.live.test.tsx@@ -147,7 +147,7 @@ describe('ChatPanel live progress', () => {expect(pending).toHaveLength(1)await advance(CHAT_LIVE_RELOAD_MIN_MS)expect(pending).toHaveLength(2)- expect(pending[1].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES })+ expect(pending[1].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES, background: true })// A burst while that read is in flight: held, never overlapped…await hook('working')@@ -185,7 +185,7 @@ describe('ChatPanel live progress', () => {await settle(1, { messages: [say(0, 'older')], olderCursor: null })expect(bubbles()).toEqual(['older', 'tail'])expect(pending).toHaveLength(3) // …then served once it landed- expect(pending[2].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES })+ expect(pending[2].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES, background: true })})it('the live read the send itself triggers does not erase the prompt the transcript lacks yet', async () => {@@ -232,7 +232,7 @@ describe('ChatPanel live progress', () => {await hook('working')await advance(CHAT_LIVE_RELOAD_MIN_MS)expect(pending).toHaveLength(3)- expect(pending[2].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES })+ expect(pending[2].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES, background: true })expect(host.querySelector('.term-chat__older--error')).not.toBeNull()await settle(2, { messages: [say(1000, 'tail'), say(2000, 'more')], olderCursor: 1000 })expect(host.querySelector('.term-chat__older--error')).not.toBeNull()@@ -365,7 +365,7 @@ describe('ChatPanel — a sent local command', () => {expect(pending.length).toBe(1)await advance(1)expect(pending.length).toBe(2)- expect(pending[1].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES })+ expect(pending[1].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES, background: true })await settle(1, { messages: [say(0, 'hello'), cmd(100, '/model')], olderCursor: 0 })expect(activity()).toBeNull()// Exactly one read: nothing else is scheduled.diff --git a/src/renderer/nodes/ChatPanel.tsx b/src/renderer/nodes/ChatPanel.tsxindex 579b572b3..2f5e243a8 100644--- a/src/renderer/nodes/ChatPanel.tsx+++ b/src/renderer/nodes/ChatPanel.tsx@@ -330,7 +330,10 @@ export function ChatPanel({// presenting itself as an empty conversation. Only the newest TAIL window is read — older// history pages in on scroll-up, and a reload merges by key instead of discarding it.void api.chat.readTranscript(sessionId, cwd, accountId, nodeId, agentId, {- maxBytes: CHAT_TAIL_PAGE_BYTES+ maxBytes: CHAT_TAIL_PAGE_BYTES,+ // A hook-driven refresh the user did not ask for: an expensive reader (opencode's export) may+ // space these out. An open, ↻, Retry or a held-request rebind is never marked.+ ...(live && !rebind ? { background: true } : {})}).then((res) => {if (token !== reqRef.current) returndiff --git a/src/shared/chat-fixtures/opencode/README.md b/src/shared/chat-fixtures/opencode/README.mdindex f9203aa97..128a70b4f 100644--- a/src/shared/chat-fixtures/opencode/README.md+++ b/src/shared/chat-fixtures/opencode/README.md@@ -28,7 +28,11 @@ strict and exits 1 on an option an older build does not know). Measured on 1.18.coloured) — the only answer read as a clean miss (`found: false`); every other failure is afailed read (`unreadable: true`);- one export costs 1.0–1.7 s and ~320 MB peak RSS, so the desktop runs at most one per session at a- time (starts spaced 2 s apart) and two in total.+ time and two in total; the panel's background refreshes are spaced 5 s, and an unchanged+ database (stat of `opencode*.db` + `-wal`, never opened) is answered from a small cache.+- a page honours the request's `maxBytes`, grows ×4 up to 5 MB when it holds no whole message (as+ claude's reader does), and a newest message above 5 MB is served truncated with a note, never as+ an empty page. The phone should expect that note in the text, not a separate field.The reader never runs an export without a session id (a bare `opencode export` opens a picker overthe newest sessions), never for an id outside `^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$`, and never for adiff --git a/src/shared/chat-page.ts b/src/shared/chat-page.tsindex 73b82563f..e4185ceac 100644--- a/src/shared/chat-page.ts+++ b/src/shared/chat-page.ts@@ -18,12 +18,18 @@ export const CHAT_PAGE_DEFAULT_BYTES = 256 * 1024export interface ChatTranscriptPageRequest {before?: numbermaxBytes?: number+ /** A live refresh the panel issued on its own (a hook event), not an open or a Retry the user+ * asked for. Readers whose read is expensive (opencode's `export`) may space these out; a+ * reader that ignores it answers exactly as before. */+ background?: boolean}/** A validated page: `before: null` = end of file. */export interface ChatTranscriptPage {before: number | nullmaxBytes: number+ /** Present (and `true`) only for a background live refresh — see the request field. */+ background?: true}/**@@ -51,5 +57,6 @@ export function normalizeChatPage(page: unknown): ChatTranscriptPage | null {if (typeof maxBytes === 'number' && Number.isFinite(maxBytes)) {m = Math.min(CHAT_PAGE_MAX_BYTES, Math.max(CHAT_PAGE_MIN_BYTES, Math.floor(maxBytes)))}- return { before: b, maxBytes: m }+ const { background } = page as { background?: unknown }+ return background === true ? { before: b, maxBytes: m, background: true } : { before: b, maxBytes: m }}