# RFD D36: Live Workspace View for Long-Running Plugin Hosts - **Status**: Draft - **Category**: Design - **Authors**: Jean Mertz - **Date**: 2026-05-08 ## Summary Long-running plugin hosts such as `jp serve` return stale conversation data because `Workspace`'s read methods cache aggressively for `jp query`'s read-your-writes semantics, and the cache is never invalidated within the host's lifetime. This RFD introduces `LiveWorkspace<'a>`, a `&mut`-borrowed view over `Workspace` that provides method-level freshness: every read revalidates the index and force-reloads the relevant cell from disk before returning. The plugin runner is plumbed with `&mut LiveWorkspace<'_>` end-to-end, making the cached `Workspace::events()` etc. structurally unreachable from plugin handlers. ## Motivation The `jp-serve-web` plugin from [PR #546] shows stale conversations to the browser even after refresh. The user runs `jp query` in another terminal to add a turn, refreshes the web page, and the new turn is invisible until `jp serve` is restarted. The bug reproduces with any sequence of disk-changing operations from a separate `jp` process. The cause is in the host, not the plugin. Plugin handlers ask the host fresh on every protocol message — `PluginToHost::ListConversations` and `PluginToHost::ReadEvents`. The host's dispatch handlers in `crates/jp_cli/src/cmd/plugin/dispatch.rs` answer them by calling `workspace.conversations()` and `workspace.events(&handle)`, both of which read from `OnceLock>>` cells in `state::State`. These cells are populated on first access and never re-read from disk. The cache is load-bearing for `jp query`. The query loop reads events many times per turn, and reads need to see in-memory writes from `ConversationMut` before they are flushed to disk (see [RFD 069]). The cache is the in-process synchronization mechanism for read-your-writes; we cannot simply remove it. The deeper architectural fact: `Workspace` serves two roles. As a mutable session for `jp query`, it provides read-your-writes through its cache. As a read API for any caller, it provides whatever was on disk at first access. These roles want different freshness semantics, and the current API conflates them. Any long-running plugin reader — not just `jp-serve-web`, but a future TUI dashboard, metrics collector, or chat interface — hits the same bug under the current shape. ## Design ### Goals - **Plugin handlers cannot return stale data.** Type-system enforced; no per-call discipline. - **`jp query`'s hot path is unchanged.** Cache, read-your-writes, and lock semantics are all preserved exactly. - **API parity.** Plugin host code uses the same `acquire_conversation` → handle → read pattern as built-in commands. - **No new traits, no async runtime, no platform-specific code.** Correctness fix without committing to file-watcher infrastructure. ### `LiveWorkspace<'a>` A view type that borrows `&mut Workspace` and exposes the same conversation-reading API as `Workspace`, but with method-level freshness: ```rust pub struct LiveWorkspace<'a> { workspace: &'a mut Workspace, } impl Workspace { pub fn live(&mut self) -> LiveWorkspace<'_> { LiveWorkspace { workspace: self } } } impl LiveWorkspace<'_> { pub fn acquire_conversation( &mut self, id: &ConversationId, ) -> Result; pub fn conversations( &mut self, ) -> Result)>>; pub fn metadata( &mut self, handle: &ConversationHandle, ) -> Result>; pub fn events( &mut self, handle: &ConversationHandle, ) -> Result>; pub fn lock_conversation( &mut self, handle: ConversationHandle, session: Option<&Session>, ) -> Result; } ``` The handle type is unchanged. `ConversationHandle` proves "this id was known to the index at acquire time"; freshness is the receiver's responsibility: - `Workspace::events(handle)` returns cached data (today's behavior). - `LiveWorkspace::events(handle)` revalidates the index and force-reloads the cell from disk, then returns through the same `RwLockReadGuard` shape. Same handle, same return type, different freshness semantics by virtue of which type's method you call. ### Shared private helpers on `Workspace` ```rust impl Workspace { /// Reconcile the in-memory index against disk by **diff**, not reset. /// /// Scan IDs from storage, then: /// - insert empty cells for IDs not yet known, /// - remove cells for IDs no longer present, /// - preserve existing cells (and their `Arc>` identity) for /// IDs that still exist. /// /// This is distinct from `load_conversation_index`, which replaces /// `State` wholesale and is only safe at workspace construction. Calling /// the reset-style loader on a workspace with active `ConversationLock` /// or `ConversationMut` instances would detach their `Arc`s from the /// workspace cache. fn refresh_index(&mut self) -> Result<()>; /// Replace the contents of an existing cell pair with fresh data from /// the loader. The `Arc>` identity is preserved, so anyone /// holding the `Arc` sees the new contents through their existing /// reference. /// /// Atomicity: loads both metadata and events from the loader **before** /// writing either cell. A load failure leaves both cells unchanged. /// This avoids leaving the cell pair in a half-refreshed state where, /// e.g., metadata reflects disk but events still reflect the old /// snapshot. /// /// If a cell is uninitialized (not yet loaded), this initializes it /// with the fresh data. If the ID is not in the refreshed index, /// returns a clean `not_found` error. fn force_reload_conversation(&mut self, id: &ConversationId) -> Result<()>; /// Acquire the cross-process flock without populating cells. Used by /// the live view's lock_conversation, which sequences lock-then-reload /// rather than the cached path's lazy-init-then-lock. fn try_lock_without_reload( &self, handle: ConversationHandle, session: Option<&Session>, ) -> Result; } ``` `LiveWorkspace` methods compose them: ```rust impl LiveWorkspace<'_> { pub fn events( &mut self, handle: &ConversationHandle, ) -> Result> { self.workspace.refresh_index()?; self.workspace.force_reload_conversation(handle.id())?; self.workspace.events(handle) } } ``` The `Workspace::events` call after `force_reload_conversation` returns a guard whose contents were freshly loaded from disk. Same `Arc>`, replaced contents. ### `lock_conversation` flow The locking path is the load-bearing piece for the future chat-UI write path. It preserves `jp query`-style read-your-writes inside the locked operation by revalidating *while the flock is held*: ``` 1. refresh_index() 2. acquire_conversation(id) — verify the id is in the refreshed index 3. try_lock_without_reload() — get the cross-process flock if not acquired: return AlreadyLocked(handle) 4. construct ConversationLock from the existing Arc> cells 5. force_reload_conversation(id) — replace cell contents from disk if this fails: drop the lock, propagate the error 6. return the ConversationLock ``` Steps 3 and 5 are atomic with respect to other processes (we hold the flock). Steps 1–5 are serial within this process. Constructing the lock at step 4 before the force-reload at step 5 is intentional and safe: the lock holds the same `Arc>` instances that step 5 mutates through, so by the time the lock is returned at step 6 its cells reflect disk at the moment of acquisition. Any subsequent `Workspace::events()` call by code holding the lock — including a future chat-UI write handler running its query loop through `ConversationMut` — sees the fresh state and behaves identically to today's `jp query` flow. If step 5 fails, the lock constructed in step 4 is dropped (releasing the flock cleanly) and the loader error propagates to the caller. No partially-handed-out lock; no panic. ### Plugin runner integration `run_plugin` constructs the live view at entry and passes it through: ```rust pub(crate) fn run_plugin( // ... workspace: &mut Workspace, // ... ) -> Result<(), cmd::Error> { let mut live = workspace.live(); message_loop(reader, &stdin, &mut live, &config_json, &shutdown_sent) } fn message_loop( reader: BufReader, stdin: &Mutex, workspace: &mut LiveWorkspace<'_>, // ... ) -> Result<(), cmd::Error> { ... } fn handle_read_events( workspace: &mut LiveWorkspace<'_>, conversation_id: &str, req_id: Option, ) -> HostToPlugin { ... } ``` Plugin handlers receive `&mut LiveWorkspace<'_>` only. `&Workspace` is not in scope anywhere in plugin-host code. New protocol message handlers added later inherit the freshness guarantee structurally; no per-handler discipline is required. ### No persistent cache field `LiveWorkspace` does not hold an internal request cache. Each method call revalidates the index and force-reloads the relevant cell. If repeated reads inside one IPC operation become measurably expensive, an opt-in scoped cache can be added later as a closure-based wrapper: ```rust live.with_operation_cache(|live| handle_message(msg, live)) ``` The closure scope bounds the cache lifetime. **Forgetting `with_operation_cache` makes a handler do extra disk reads but does not return stale data.** The cache is purely a performance optimization; correctness must not depend on it. For v1, even the closure version is YAGNI. Personal-workspace `events.json` reloads are sub-millisecond. The cache lands when measurement shows it pays for itself. ## Drawbacks - **One new public type and one new public method on `Workspace`.** Modest API surface growth. The type is small (5 methods); the method is a one-liner. - **Per-call disk reads.** Every `LiveWorkspace::events()` call reads `events.json` from disk and parses it. At personal-workspace scale this is sub-millisecond per file. For workspaces with very large conversations or very high request rates, the cost grows; the deferred closure-scoped cache is the response. - **`&mut LiveWorkspace<'_>` serializes plugin host operations.** The dispatch loop processes messages serially today, so this is not a current constraint. If the host ever moves to concurrent message handling, the `&mut` borrow becomes a bottleneck — but the same redesign would be required regardless of how freshness is implemented (the dirty-state hazard described under [Risks](#risks-and-open-questions) only arises under concurrent handling). ## Alternatives ### `WorkspaceReader` (read-only sibling type) A separate type holding `Arc` directly, read-only API, used by plugin host code instead of `Workspace`. Rejected because the type becomes useless (or requires an awkward escape hatch back to `Workspace`) when chat UI introduces write operations through the same plugin host. `LiveWorkspace<'a>` borrows the workspace, so it can expose the locking path naturally. ### Mtime-on-read auto-invalidation Cache cells gain a `loaded_mtime` field; each `Workspace::events()` call does a `stat()` and reloads if the file is newer. Single API, single type, no caller discipline. Rejected because every read on the `jp query` hot path pays the `stat()` cost (~1–5 µs per call) for no benefit — `jp query` is the only writer of its conversation, so its cache is always trustworthy. The architectural seam is wrong: freshness shouldn't be a per-read property of the cache; it should be a property of the caller's role. ### File-watcher push notifications (`notify` crate) A background task watches the storage tree and invalidates cells on filesystem events. Cache becomes self-maintaining; reads are cache hits. Strictly more powerful than `LiveWorkspace`, since the same event source could later drive SSE-style live updates without browser refresh. Rejected for v1 because: - Materially more implementation: new `WatchBackend` trait, `notify` dependency, tokio task lifecycle, debouncing, error/restart handling. - Platform-specific quirks: inotify watch limits on Linux, FSEvents coalescing on macOS, no events on NFS. - Coordination with `ConversationMut` requires a dirty-flag mechanism on cells. The watcher is the right answer if/when [RFD D16]'s "no live updates" Non-Goal becomes a real requirement (real-time updates without browser refresh). It composes orthogonally with `LiveWorkspace`: the watcher would drive `force_reload_conversation` from outside the request path. Building it now is YAGNI for the in-scope problem. ### Polling background worker A scheduled task (~1 Hz) reloads cells periodically. Single API, no `notify` dependency, eventually-consistent. Rejected because polling is a probabilistic fix to a synchronous correctness problem — a browser refresh may or may not see fresh data depending on poll-cycle timing. Less predictable than today's "always stale until restart." The watcher (above) is the push-based version of the same idea and is strictly better; if push-based reload is wanted, build the watcher. ### `reload_*` methods on `Workspace` Add `reload_metadata`/`reload_events`/`reload_index` on `Workspace`; callers opt in by calling them before reading. Rejected because correctness depends on every call site remembering to call `reload_*`. New plugin handlers added later have no compile-time signal that they need to opt in. The hazard is exactly the bug class this RFD aims to eliminate. ## Non-Goals - **Real-time live updates.** The browser still has to refresh to see new data. SSE / WebSocket-driven updates are deferred to a future RFD that introduces a watcher or push channel. - **Dirty-state tracking on cells.** Today's dispatch loop processes protocol messages serially (one stdin line at a time), so a `force_reload_conversation` call cannot race with a live `ConversationMut` in the same host process. If we ever introduce concurrent message handling in the host, or expose plugin-side `lock`/`unlock` as separate protocol messages so a plugin can hold a lock across IPC boundaries, the dirty-state hazard becomes real and we need to add tracking. Until then, deferred. - **Changing `jp query`'s behavior.** `Workspace`'s public API is unchanged; the query loop is untouched. - **Fixing every long-running scenario.** This RFD covers plugin hosts. Long-running CLI commands that read conversation data without going through the plugin protocol are not affected (none currently exist). - **The chat-UI write path itself.** This RFD makes the plugin host's write path *possible* via `LiveWorkspace::lock_conversation`, but the chat-UI feature itself is out of scope. ## Risks and Open Questions - **Naming.** `LiveWorkspace` reads as "real-time / push-based" in a UI context, which is the opposite of what this type does. Alternatives considered: `WorkspaceSession`, `FreshWorkspace`, `RevalidatingWorkspace`. Bikeshed; pick a name that doesn't promise features the type doesn't have. - **Dirty-state invariant in rustdoc.** `force_reload_conversation` assumes no live `ConversationMut` exists for the same conversation in this process. Document this as a `# Invariants` section on `LiveWorkspace`'s rustdoc and as `// Invariant:` comments on the helper (not `// SAFETY:`, which is reserved for `unsafe` code by Rust convention). The invariants to spell out: - Plugin message handling is serial; one handler runs at a time. - Plugin-held locks are not exposed across IPC messages. - Within a single handler, callers must not invoke `LiveWorkspace` revalidating reads for a conversation while holding a dirty `ConversationMut` for that same conversation. Once a handler holds a `ConversationLock`, reads must go through `ConversationLock` or `ConversationMut`, not through `LiveWorkspace`. - If the runner ever moves to concurrent message handling, or exposes explicit plugin-side `lock`/`unlock` protocol messages that span IPC boundaries, these invariants are broken and the design must be revisited (likely by adding dirty-state tracking on cells). The serial loop covers the cross-message hazard automatically. The same-handler hazard is not enforced by Rust's borrow checker (a handler could hold a `ConversationLock` and still call `live.events(handle)`), so the rustdoc has to state the rule explicitly. - **Race: conversation deleted between refresh and lock.** `LiveWorkspace::lock_conversation`'s sequence (refresh → acquire → flock → force\_reload) can fail at step 4 if another process removes the conversation directory between steps 1 and 4. The error propagates as `not_found`. Caller handles it. Worth a regression test. - **Lifetime ergonomics.** `LiveWorkspace<'a>` exclusively borrows `&'a mut Workspace`. Code holding `LiveWorkspace` cannot also access `Workspace` directly during that scope. For the plugin runner this is the desired behavior. For any future caller that wants to switch back and forth, they will need to drop `LiveWorkspace` and re-call `Workspace::live()` — cheap (one struct construction), but worth noting in the rustdoc. ## Implementation Plan ### Phase 1: Implementation - Add private helpers to `Workspace`: `refresh_index`, `force_reload_conversation`, `try_lock_without_reload`. Refactor existing `load_conversation_index` to share `refresh_index`'s logic where appropriate (preserve existing cells, diff against disk). - Add `LiveWorkspace<'a>` and `Workspace::live(&mut self)`. - Implement `LiveWorkspace::acquire_conversation`, `conversations`, `metadata`, `events`, `lock_conversation`. - Update `crates/jp_cli/src/cmd/plugin/dispatch.rs`: - `run_plugin` calls `workspace.live()` and passes `&mut LiveWorkspace<'_>` to `message_loop`. - `message_loop` and dispatch handlers (`handle_list_conversations`, `handle_read_events`) take `&mut LiveWorkspace<'_>`. ### Phase 2: Tests Six regression tests, each running two `jp` host processes against a shared workspace unless noted otherwise: 1. **Creation drift.** Writer creates a new conversation; reader sees it via `LiveWorkspace::conversations()` on the next protocol message, and can `acquire_conversation` it. 2. **Deletion drift.** Writer removes a conversation; reader's next `LiveWorkspace::conversations()` no longer lists it. (This test fails if `refresh_index` only adds IDs without removing vanished ones.) 3. **Stale handle after deletion.** Reader holds a `ConversationHandle` acquired before deletion; after the writer removes the conversation, the reader's next `LiveWorkspace::events(&handle)` returns a clean `not_found` error rather than serving stale cached data. 4. **Event drift.** Writer appends a turn to an existing conversation; reader sees the new turn via `LiveWorkspace::events(handle)` on the next protocol message. 5. **Lock force-reload.** Single-process test. Writer-A holds a lock, appends events, releases. Reader (same process, separate `LiveWorkspace` scope) acquires a lock via `LiveWorkspace::lock_conversation` and verifies the resulting `ConversationLock::events()` reflects the appended turn, confirming step 5 of the lock flow ran. 6. **Delete-during-lock-acquisition race.** Writer removes a conversation between the reader's `refresh_index` and `force_reload_conversation`; reader gets a clean `not_found` error and the flock is released, not a panic or a partially-handed-out lock. ### Phase 3 (deferred): operation-scoped cache If measurements show redundant in-handler disk reads becoming expensive, add the closure-scoped `with_operation_cache`. Not part of v1. ## References - [PR #546] — `jp-serve-web` plugin (the reporting context). - [RFD 069] — Guard-scoped persistence; defines the `OnceLock>>` cell structure that this RFD reaches into via `force_reload_conversation`. - [RFD 072] — Command plugin system; defines the JSON-lines protocol that `jp-serve-web` uses. - [RFD 073] — Layered storage backend; defines the `LoadBackend` trait that `force_reload_conversation` calls through. - [RFD D16] — Original read-only web UI draft (predates the plugin extraction in [PR #546]). [PR #546]: https://github.com/dcdpr/jp/pull/546 [RFD 069]: ../069-guard-scoped-persistence-for-conversations.md [RFD 072]: ../072-command-plugin-system.md [RFD 073]: ../073-layered-storage-backend-for-workspaces.md [RFD D16]: D16-read-only-web-ui-for-conversations.md