Keep domain-specific implementations where authority, lifetime or runtime differs.
- Keep the last successful display snapshot while a passive refresh runs.
- Share concurrent reads for the same identity. During a read, coalesce refresh requests into one pending follow-up rather than queueing one request per event.
- Invalidate on relevant events or mutations; an expired TTL only marks data stale for the next demand. Avoid background polling merely to keep a hidden view warm.
- A response must still belong to the current identity/generation before publication. Serialize follow-up reads so an older response cannot overwrite their result.
- Preserve the last good snapshot on refresh failure and permit recovery. Surface failures for explicit operations rather than reporting stale data as success.
- A successful mutation must be visible to its next dependent read. Display-cache policies must not weaken ownership checks or transactional revalidation.
- Treat a background update of a displayed collection as data, never as a user selection: preserve its open state, stable-key keyboard target and inline actions.
Current daily/native-scheduled passages acquire a source identity before slices and reuse the bounded selected-mission inventory owner without directory or finish-counter reads. Body keys include that exact passage source. Owner revision fences publication separately from frozen execution-source identity, preserving unchanged task/body windows through unrelated journal updates. Archive reads retain their exact receipt and one range observation. An outstanding current-body demand retains one 30-second deadline/cancellation lifetime through every semantic slice, automatic restart and revalidation. Fulfillment ends that operation; a later user extension/Retry can admit a fresh budget. Validate assembled content before promoting it, and retain the last good display on expiry.
| Area | Current behaviour | Implementation |
|---|---|---|
| Background Shells | Per instance/Location last-good snapshot; one read with one coalesced trailing invalidation. Visible expanded sections own refresh demand, including tool completion after background admission and reconnect; hiding releases demand. Unchanged records retain row/action DOM. Native job inventory selects background IDs; Shell metadata and session ownership qualify them. | stores/shell-store.ts, shells.ts; server opencode/background-shells.ts, server/routes/background-shells.ts |
| Session catalog | Per-window, per-workspace persistent display metadata for every known root and descendant. Byte-sized native partitions bound it, independently of session count and the draft string budget. Seed titles, ancestry, locations, selection and expansion before HTTP hydration. Cached rows carry unknown runtime status; the selected chain is revalidated directly, while the owned project inventory refreshes asynchronously. Partial/failed/directory-only initial pages never evict saved workspace families; a complete owned inventory reconciles absent rows with concurrent-update fences. | stores/session-catalog-persistence.ts, session-catalog-hydration.ts, client-state-catalog-partitions.ts, session-api.ts |
| Session outline | Structural indexes independent of transcript and excerpts; up to 16 memory snapshots / 200k entries (one larger active index allowed). Restoration persists up to 16 indexes / 200k entries / 16 MiB in optional content-addressed chunks. Saved geometry displays before full checkpoint revalidation; only changed ranges resend entries. The last range grows to 512 rows before another is added. Returning to an unchanged session reuses its index; native message changes revalidate checkpoints. Destructive mutation, generation, location/project and undo boundary fence reuse. Paused scans retain cursors. | packages/ui/src/stores/session-outline.ts, session-outline-persistence.ts, client-state-outline-partitions.ts |
| Timeline previews | At most 512 bounded Markdown excerpts. Visible-nearby batches of 12, hovered ID first; obsolete demand cancels. Thirty-second age prompts on-demand revalidation only. Generation, mutation and undo fence reuse. Previews never load transcript windows or change geometry. | packages/ui/src/stores/timeline-previews.ts |
| Providers/models | Retained signals; shared in-flight catalogue load; dirty-bit trailing refresh; instance, location and request-generation checks. fetchProviders itself reuses only in-flight loads. |
packages/ui/src/stores/session-api.ts |
| Provider Usage | Panel-local snapshot; same-location provider.updated revalidates in place with one in-flight read and coalesced trailing demand. Window-label keys preserve quota DOM across responses. Duplicate transport statuses and instance/status/native-generation snapshots are no-ops. A changed native generation still fences quotas even if the disconnect was missed. Credential/integration/config events, native server.connected, real connection transitions and source changes clear the snapshot immediately and fence old responses/trailing demand. Failures revoke quotas, since the account may have changed. Only a visible panel reads, and quotas stay panel-local. |
components/session/provider-usage-panel.tsx, provider-usage-state.ts |
| Session goal | Per instance/session snapshot of the shown session's /goal. The goal line's demand (Status shown) reads through the secondary budget: one read plus one trailing follow-up. rpc.opencode.goal.changed publishes at once and fences replies requested before it (per-session version); an unreadable change reads again. Plugin activation (plugin.updated) and reconnects (server.connected, connected status, stream open) coalesce reads of demanded sessions; the line's commands read their outcome. A failed read keeps the last goal; deletion and workspace stop drop it. |
stores/session-goal-store.ts, session-goal.ts |
| Integration binding | Demand-only authority for the shown instance/Location/session/integration, shared by the Plugins rows that show it through the secondary budget. Invalidations immediately publish unknown and fence older replies; events coalesce over 300 ms with one trailing follow-up. Reconnect/open reconcile demand, disconnect revokes authority, and read failures publish unknown. Last-demand release aborts and drops state. Every admitted attach or detach invalidates and rereads its captured target in finally while demanded. |
stores/integration-bindings-store.ts, integrations.ts |
| Stats | Backend-owned state.ui.serviceUsage; rules in SETTINGS.md, restoration below. Reads follow explicit demand, terminal hints (shared five-second activity cooldown), reconnect and visibility; never poll. Hiding/disposal fences in-flight publication. |
server opencode/service-usage-cache.ts, service-usage.ts; UI settings/usage-settings-section.tsx |
| Session model selection | Native selection events invalidate the displayed selection and never overwrite it, because SSE echoes can lag successful HTTP writes. Coalesced authoritative reads share the session admission queue with prompts and explicit selections; client/generation and captured-selection checks fence late responses. Catalog merges preserve pending optimistic choices; successful writes publish a fresh model object so pre-confirmation snapshots lose authority. Read failures retain display state until the next event or reconnect refresh. | stores/session-model-reconciliation.ts, stores/session-action-queue.ts, stores/session-generation-recovery.ts |
| OpenCode setup | Shared in-flight status read plus coalesced trailing refresh for focus/visibility/reconnect demand. Executable changes and explicit actions fence old responses. Failed reads retain version/path diagnostics but revoke the connected claim and stale reload/restart controls; Continue checks again before retrying the pending workspace. Activation requires a successful pre-action status read. | UI stores/opencode-setup.ts, components/settings/opencode-setup-panel.tsx |
| Filesystem invalidations | Host directory observations and native filesystem events coalesce before cache publication: 100 ms quiet-case delay, then at most once per five seconds in continuous activity; timers run only during activity. Explicit mutations/recovery invalidate immediately. Workspace versions target the browsing root and listed directory; only changed visible directories reread. Hidden/collapsed caches stay stale until demand. Bounded metadata falls back conservatively to full invalidation. | filesystem-events.ts, useWorkspaceTree.ts, server workspaces/file-watches.ts |
| Git changes | Shared filesystem cache invalidations debounce locally for 100 ms; one passive refresh plus a pending follow-up; hidden project/panel marked stale. Queued reads cancel on deactivation/disposal and request versions fence late status/diff results. Reads share the secondary HTTP budget. Server shares only in-flight status requests and runs status/diff process creation in the Git worker. | useGitChanges.ts, filesystem-events.ts, server workspaces/git-status.ts |
| Worktree display | Last successful server snapshot; demand-driven refresh after 10 s or invalidation; one scan per workspace; obsolete scans discarded and followed by validation; UI display requests coalesce with one trailing demand. Pending recovery can explicitly request ?fresh=true once after a missing/not-owned inventory-only candidate; so does a session move whose destination the display snapshot does not own, before the session leaves the list. Concurrent fresh callers share their fresh read, never a cached completion. Fresh and display outcomes are independent on one serialized read/publication lane: a failed fresh read rejects its callers without dropping queued display demand or leaking freshness into later requests. |
server workspaces/worktree-inventory.ts, UI stores/worktrees.ts |
| Worktree authority | Validated reads await stale-inventory revalidation; family transactions force scans. Ownership misses can bypass a warm inventory once per directory-cache lifetime. Create/remove requires a validated next display read. | server workspaces/worktree-directory.ts, manager.ts |
| Git ownership preflight | Common-directory reads resolve the enclosing checkout's administrative files (.git, commondir, HEAD/objects) directly on every call; concurrent reads share one pending read per directory. Environment overrides, paths inside .git and invalid layouts defer to Git, whose commands run with two process slots in a lazy worker, keeping Windows process creation off the HTTP/SSE thread. Completed/failed reads are removed immediately; a matching identity still requires native inventory validation. |
server workspaces/git-common-directory.ts, git-process.ts, git-worktrees.ts |
| Transcript pages | Session reducer reads and first latest-window loads merge their page with the rows streamed during the fetch; only destructive events (deletion, revert commit, inbox cancellation, compaction boundaries) restart a reducer read. Reloads and history windows keep revision checks. Committed latest pages reseed a reducer that diverged or lacks an open step; live events for rows the reducer lacks owe one coalesced, budgeted repair read in watched sessions only. Event-driven projections coalesce to one pass per animation frame. Rules in TRANSCRIPT.md. | UI stores/opencode-data.ts, opencode-data-divergence.ts, opencode-projection-frame.ts, opencode-data-read-merge.ts, session-api.ts |
| Mission bodies | Display-only content-route reads keyed by workspace, project, mission and selector; continuations pinned to their first slice's digest, read only as far as the shown page needs. One read at a time per body with coalesced demand. The panel's maps are compact: a descriptor in place of each body. A shown body is read again when its map's descriptor names another digest (a map naming no descriptor expects nothing); a plugin update, reconnect or new stream advances the entry's invalidation epoch, so a request sent before it neither settles nor parks the body and one fresh read follows. The last good body stays shown until the newer one covers it; failures (a plugin without content reads included) show beside it and park until demand, an invalidation or Retry. Intents copying inputs (edit prefill, Save configuration) accept only bodies whose digests are their snapshot's descriptors. Unshown bodies stay within 4 MiB / 128 bodies, LRU. Never authority. Rules in MISSIONS.md (Body display, Compact maps). | UI stores/mission-content-store.ts, stores/mission-content.ts, components/mission-target-bodies.ts |
| Mission task pages | A compact map holds a page of its tasks; reads further (loadTasks: a window of 50 or tasks by name) name the map's display order and run in turn per mission, an identical waiting read coalesced and a running one followed by one trailing read. Each read is recorded before it is sent; rows, reports and reads each keep the revision of the page that answered them, so a page vouches only for what it answered. An answer in the shown order merges into the list read's own map (a row it holds stays unless a page answered it later), a refusal or another order reads the list again. List publications keep the rows of the same order (last good display), drop caches of maps no longer listed, and read again each read last answered before the map's revision, from scratch in another order. A failure keeps the rows with Try again and parks its read until a later revision or an explicit retry; it stays shown until a read answers it, whatever else succeeds. Attention windows count as covered only for the attention sequence they answered. A body a row read further describes is expected at that page's revision; an older plugin's undescribed history is read again when its report metadata changes. clear fences reads in flight (epoch and cache identity). Reads share the secondary background budget. Never authority. Rules in MISSIONS.md (Task pages). |
UI stores/mission-store.ts, stores/mission-task-pages.ts |
| Mission panel inventory | Live picker/cleanup discovery uses explicit 50-row logical windows through panelPage. Content digests verify that window; a separate order digest covers the collection's row values and fences further selections. Only selected/reader-wanted missions load bounded headers and task windows; root collection/extension descriptors permit exact field reads. Every window retains its own revision and failed selector. A failed middle window stays failed through unrelated successes; changed cursors park for explicit restart/Retry. Passive refresh reads first windows and wanted headers, preserving expanded displays without replaying every read after unrelated revisions. Initial discovery point-reads the durable finish counter before hints; completion seeding happens once, independently of partial summary maxima. Exact cleanup reconciliation keeps its existing single-mission path. Every transfer retains the shared secondary slot through bounded stream cleanup, with one 30-second logical deadline and source-specific preallocation limits. Hints serialization/order work remains in the append lane and linear in the whole chosen collection per transfer. Event-driven panel refreshes start at least 5 s (native activity) or 1.5 s (journal changes) after the previous read settled; publications keep every unchanged map, row and activity entry. |
UI stores/mission-panel-inventory.ts, stores/missions.ts, lib/structural-share.ts, lib/mission-task-page-read.ts; server missions/mission-panel-page.ts, mission-panel-header.ts, MissionControl.panelPage |
| Opt-in Mission live windows | panelPage activity selects at most 160 actors of one mission; marks select at most 16 hint contexts of 10 actors. Native observation reuses existing budgets and root/connection/deletion fences after the append exclusion. Every continuation re-observes and refuses changed content; zero automatic restarts. Only structure is retained between observations: bounded family trees per daemon client until a structural session event, a stream status change or 20 seconds, and actor roots known deleted; native activity is never retained. Inboxes are read only where queued input decides a state. Partial/unknown family and request coverage stay explicit, including off-page actors. Consumers park failed windows, retain last-good display and restart changed rows from their first piece explicitly. |
server missions/mission-activity-context.ts, mission-panel-observation.ts, activity.ts, activity-cache.ts |
| Mission task transport | One requested window or named read through panelPage, 64 KiB per response and 16 KiB per selector. Each secondary slot covers headers plus bounded body consumption/cancellation; one 30-second deadline starts before the store queue and covers final hash/validation/publication. Window text admits at most 8 Mi UTF-16 units, 24 MiB UTF-8, 64 MiB cumulative wire bodies and bounded JSON structure/nested compact shapes. Digest/length/header, semantic selector/report/counter checks and UTF-16LE SHA-256 precede publication; WebCrypto and the pinned browser-safe fallback cover secure and HTTP-only origins. Partial text is operation-local; failures park with Retry, while supersession stays distinct from empty success. Last-owner release advances a monotonic mission lifetime; concurrent owners preserve it. Live readers own reconnect refresh demand independently of the panel. |
UI lib/mission-task-page-read.ts, mission-task-page-schema.ts, mission-task-window-budget.ts, mission-task-read-lifetime.ts, stores/mission-store.ts |
| Render cache | Explicit versioned values scoped to instance/session, invalidated by version only. | UI lib/global-cache.ts |
| Background HTTP reads | Worktree display, Git status/diffs, project/location/status maps, composer catalogues, Shell lists and pending-request scans share two browser request slots across instances. Queued scans observe cancellation; per-request timeouts start at dispatch. Session/message reads and mutations stay independent so catalogue fan-out cannot occupy all HTTP/1.1 connections. | UI lib/background-read-queue.ts, lib/sdk-manager.ts, stores/instances.ts, stores/worktrees.ts |
| Virtualized lists | Session list, transcript and timeline use virtua/solid; virtualization bounds rendered rows only. |
UI session-list.tsx, virtual-follow-list.tsx, message-timeline.tsx |
Each server status calculation runs five Git commands plus untracked-file processing, and the UI also requests native status. Continuous activity can sustain repeated full calculations and selected-diff reads.
The in-memory worktree cache requires full first and authoritative scans. The event relay isolates waits by entity and recipient; never authorize from stale display data.
Pending recovery's fresh-read and session-family move-hold rules are in
NATIVE_INTERRUPTION_UX.md. worktrees.ts captures
the exact source/target locations before the single move mutation and
session-api.ts releases them; missing/changing project metadata,
directory-only/partial inventories, failed activity and superseded reads never
release a newer move's hold. Notification history keeps its entries when
recovery later succeeds.
use-app-session-capture.ts shares a value-diffed scalar session projection between
capture scheduling and preserved-prompt hydration. It snapshots catalog fields and
runtime/attention inputs even when instance Maps or nested metadata mutate in place.
Only cost/token changes while a session is working or compacting are deferred.
Session membership, metadata, runtime transitions and idle usage still invalidate;
drafts, attachments, selection, expansion, scrolls and outlines retain their triggers.
Capture and explicit flush always read the fresh stores, including deferred counters.
The accepted crash-freshness limit for these display-cache counters is the last successful checkpoint: an uninterrupted run with only usage changes can leave them at its starting checkpoint for the whole run. The next draft/metadata/view checkpoint, runtime transition or explicit navigation/shutdown flush includes the latest counters. Native hydration revalidates restored display data. Persistence retains its complete partition payloads, atomic publication, write-failure dirty state, ownership fences and native shutdown generation/cancellation rules.
Rules: SETTINGS.md (Stats). Storage is the backend
SettingsService UI state owner (also serving Preferences recreation and
browser/remote clients), one document per backend/profile. Only an opaque SHA-256
fingerprint is stored: authenticated config.get global discovery root, host or
WSL distro, authenticated service channel and exact backend opened folder, never
credentials, native paths, PID, transient port or workspace UUID. A changed
channel misses the cache; snapshots never authorize a Location or mutation.
Period and timezone stay separate; corrupt/oversized entries are display misses.
The fast host/channel/folder key restores only the period; reusing metrics
requires the full discovery identity. Late discovery
attaches identity only when its unsaved opaque live connection token matches
the fresh response. Receipt order is assigned before connection acquisition and
admitted only on an owned current connection into a bounded frontier (64
entries, retired-order floor); client from/to never act as freshness.
Optional publication is capped at 32 pending operations, rechecks ownership,
uses the 10-second discovery deadline and drains on backend close. Reconnect
checks host/channel/folder without discovery; a display without a verified
discovery identity is never adopted by a changed live connection, and unknown
observations never relabel old metrics.
Hidden, minimized and occluded native Preferences windows are unqualified:
Electron's Preferences bridge exposes minimize only as an action, and Tauri
exposes no Preferences visibility observation. Native session.stats
re-aggregates the whole range on every GET (31-day windows, compaction events in
batches of 500, even with tools: "none"), so large histories are slow upstream.
Beyond the relay rule in OPENCODE_COMPATIBILITY.md
(server workspaces/instance-events.ts, instance-event-queue.ts): per-session
order includes move/delete, unrelated sessions have no global order, other
scoped events keep FIFO per complete native location and global notifications
have their own lane. server.connected is relayed with a daemon field: an
opaque token held only for the current source by the relay, issued randomly
per source, stable across verified same-source reconnects, rotated when the
source is replaced (the superseded credential-bearing key is dropped with it)
and released when the relay disposes; it is absent from an unattributed
stream. The UI gates reconnect transcript continuity on a matching token and
keeps a hard reset otherwise. Ownership
promises/2 s
results are shared per recipient and full location. Ingestion-time worktree
invalidation and local inventory changes fence pending ownership checks;
stopped/reopened workspaces and disconnected stream generations cannot publish
late work. Budgets: 2,048 retained jobs, 32 MiB conservatively counted serialized
payload, 60 s per routing job including queue wait; a breach fails that
subscriber, clears its queue and emits the normal error/reconnect statuses. Never
silently drop a delta or restart the shared daemon. Rate-limited slow-routing
logs separate event age, location resolution, queue wait and ownership time
(type/recipient metadata only).
lib/server-events.ts restarts the shared UI event stream once a connected
stream has carried no batch, open or ping for 45 s (lib/stream-staleness.ts,
checked every 15 s, once per silent episode); an online event or the page
becoming visible restarts it as soon as that threshold has elapsed. Each
connection attempt starts its own threshold. The restart takes the ordinary
reconnect path, so the reconnect refresh reconciles state. The server pings
every 15 s (server/routes/events.ts): keep the threshold at several ping
intervals.
App-tab records retain identity across metadata refreshes, reordering and restoration of sibling projects. Their payload getters stay reactive; Solid's identity-keyed rendering must not remount existing shells or restart their Git readers on each update. Visible Git panels precede queued bulk scans within the same two-request secondary budget, so inventory/permission fan-out cannot leave an opened panel waiting behind every restored checkout. Deactivation removes queued panel reads. The optional SDK status read propagates cancellation into the transport and has a dispatch-time deadline. Explicit refresh/mutation continuations retain their panel generation and worktree identity; late results cannot reset another draft or launch hidden-panel diffs. The server also bounds untracked-numstat submission and admits worktree authority commands ahead of pending display commands in the Git worker.
Project identity and worktree discovery start independently. The root-directory session page can publish before project identity or checkout discovery finishes; complete project-family reconciliation still waits for verified worktree membership. Metadata-dependent callers retain the combined worktree/project readiness barrier.
The saved session and its last captured catalog are restored together; catalogs
are optional, versioned graph extensions shared by Electron and Tauri. Older
snapshots simply need one successful catalog load before they can offer this
cache. Corrupt catalog chunks discard only display metadata, retaining selected
identity, drafts and other state. Native aggregate byte/partition limits apply
atomically and are the only bound on the catalog. This display cache never
grants directory authorization or persists transcript bodies or permissions.
The saved session and composer catalogues load once the client is ready,
independently of the complete project-family inventory. Supplemental metadata waits for session hydration.
Creation-ownership release starts alongside saved-session hydration; its HTTP
acknowledgement must not gate the visible conversation.
The visible project's first session page, project identity and worktree
membership bypass the secondary budget, as does saved ancestry. Otherwise a slow
Git/permission scan can hide every other-worktree conversation until it finishes.
The first project page publishes verified families additively, without waiting
for the historical cursor traversal. Historical pages and restored chains from
other projects share that budget, so their parallel hydration cannot queue ahead
of the visible transcript.
Before selection is known, root pages also share the secondary budget. Pending
root/ancestry reads observe active selection and leave that queue immediately
when selected, without restarting already dispatched requests (lib/prioritized-read.ts).
Catalogue refreshes recheck client, location and request ownership before dispatch.
The first native connection can supersede an initial HTTP read without passing
through the reconnect recovery gate; session lists and catalogues replace those
obsolete reads unless a newer request, cancellation or disposal owns recovery.
Runtime-status responses cannot block list publication or overwrite newer SSE and local admission state. Pending-request liveness refreshes only the status map, never re-traversing the whole session inventory.
- The browser opens only a few connections to the CodeNomad server. The selected transcript and its metadata read directly; secondary panel and timeline reads (plugin controls, outlines/previews) go through
secondaryReadinlib/api-client.ts, sharing the boundedbackgroundReadsbudget. Provider usage stays direct (superseded reads run to completion and are fenced), and so does the OpenCode status read awaited by Restart/Start, so daemon-bound reads in the shared budget can never hold it. Startup effects must not track app-wide state they only await (untrackreadiness gates), or every restored workspace update restarts and requeues the transcript read. Search visibility must be value-diffed before its close effect: reactive instance metadata can change while search stays closed, and running search cleanup then would cancel the initial transcript read. Restore tests must exercise reactive identity accessors and assert visible messages as well as request counts.