Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Picker preview caching — the whole system.
//!
//! This module orchestrates the picker's preview content and sits on top of two
//! cache tiers whose pieces live across several modules; this docstring is the
//! map that ties them together. The disk tiers are in [`super::preview_cache`]
//! and [`crate::summary`], the repaint loop in [`super::preview_notify`], the
//! synchronous read path in [`super::items`], and the cross-spawn lifetime in
//! the picker's `PipelineFactory` (`src/commands/picker/mod.rs`).
//!
//! # Two tiers
//!
//! **In-memory** — [`PreviewCache`], an `Arc<DashMap<(row-key, mode), String>>`.
//! The only *cache tier* `SkimItem::preview` reads (a lock-free `get`; it never
//! touches disk) — a miss renders a loading placeholder. (`preview()` also reads
//! the row's live `pr_status` / `local_content` slots for tab availability and
//! the Pr/Comments panes, but those aren't cache reads.) Session-scoped, and
//! **shared across every
//! `alt-r` spawn** (the one `Arc` is reused). The key is `(row-key, mode)`,
//! where row-key is a canonical Git item identity for a local row or a
//! structured PR/MR reference for a `--prs` row — with **no content hash**.
//! Two consequences: every mode shares one key shape (a `--prs` row's forge
//! fetches and a worktree row's git diffs coexist), and a `git fetch` or new
//! commit that moves a branch does *not* invalidate the entry — the key is
//! unchanged, so a warm entry can outlive the content it was computed from.
//! That staleness is reconciled two ways, both below: per-event invalidation
//! for the PR tabs, and a wholesale clear on refresh.
//! Worktrees key by canonical path, while branch-only rows key by full ref.
//!
//! **On-disk** — content-addressed, cross-session, consulted only on an
//! in-memory miss. [`super::preview_cache`] holds Log / BranchDiff /
//! UpstreamDiff keyed by git SHA(s) + dimensions; [`crate::summary`] holds
//! summaries keyed by a hash of the diff. UnifiedDiff reuses BranchDiff's disk
//! entry for a clean worktree or branch-only row; a dirty UnifiedDiff and every
//! WorkingTree preview are live-only. Pr and Comments have no general disk tier
//! (GitHub comments use their own `updatedAt` cache below). Because the stable
//! keys *are* content-addressed, moved content yields a fresh key and a natural
//! miss — the disk tier is never stale, which is what makes clearing the
//! in-memory tier above it cheap (an unchanged branch re-reads disk; only
//! changed content recomputes).
//!
//! # What backs an in-memory miss, per mode
//!
//! | Mode | Disk tier | Recompute on miss |
//! |------|-----------|-------------------|
//! | UnifiedDiff | BranchDiff cache when clean / branch-only; none when dirty | cached committed diff or live net worktree diff |
//! | WorkingTree | none (a dirty tree has no stable hash) | live `git diff HEAD` |
//! | Log / BranchDiff / UpstreamDiff | [`super::preview_cache`], SHA-keyed | `git`, then write disk |
//! | Summary | [`crate::summary`], diff-hash-keyed | LLM, then write disk |
//! | Pr | none | render from the already-fetched CI/PR data |
//! | Comments | [`super::preview_cache`], `updatedAt`-keyed (GitHub PRs only) | forge fetch, then write disk |
//!
//! # Invalidation
//!
//! - **Pr / Comments** self-invalidate on the CI path: `on_update` drops the
//! `(branch, Pr)` entry when a row's live status changes, `--prs` rows drop
//! theirs on rebuild, and a corrected PR number drops the stale `Comments`
//! thread (see [`super::progressive_handler`]).
//! - **UnifiedDiff / WorkingTree / Log / BranchDiff / UpstreamDiff / Summary**
//! have *no* per-event in-memory invalidation. Within a session they are
//! reconciled with moved content only by a refresh.
//! - **Refresh (`alt-r`)** calls [`PreviewOrchestrator::refresh`] (from
//! `PipelineFactory::spawn`, gated on `rebuild_repo`), which supersedes the
//! prior spawn's producers, rebinds the compute repo to the rebuilt spawn's,
//! and clears the entire in-memory cache — see *Spawn generations* below.
//! The rebuilt inventory gives each row a current `item.head()` and the
//! rebound repo a fresh `RepoCache` (notably the default-branch base SHA for
//! BranchDiff), so recompute sees current state, not session-start state.
//! The disk tiers keep an unchanged branch cheap; only genuinely changed
//! content pays.
//!
//! What's left unrefreshed is only the in-between: content that moves
//! mid-session without an `alt-r` waits for the next refresh (or reopen) by
//! design — the refresh *is* the reconciliation point.
//!
//! # Spawn generations
//!
//! A refresh doesn't wait for the previous spawn's producers — precompute
//! tasks still draining `COLLECT_POOL`, a `--prs` forge call in flight, a
//! demand request parked or mid-compute — and each of those holds a frozen
//! `Arc<ListItem>` whose `head()` the refresh may have made stale. Left
//! alone, such a producer would land its stale content in the just-cleared
//! cache, and the new spawn's own producer would then short-circuit on the
//! entry instead of recomputing. [`SpawnGeneration`] closes this: each
//! pipeline spawn mints a token (`PipelineFactory::spawn`), everything that
//! spawn starts carries it, and [`PreviewOrchestrator::fill`] — the one
//! insert path — drops a write whose token a later
//! [`PreviewOrchestrator::refresh`] superseded. `refresh` bumps the
//! generation *first*, then rebinds the compute repo to the new spawn's (so
//! recompute resolves bases from a fresh `RepoCache`, not session-start
//! state), then clears the cache. `fill` checks the token while holding the
//! key's shard write lock, which makes its check-and-insert atomic against
//! the bump-then-clear: a check that passes happened before the bump, so
//! the clear always lands after (and wipes) that insert, and a check after
//! the bump refuses the write — a stale fill cannot straddle the refresh.
//!
//! The same token gates every other cross-spawn effect, all enforcement
//! secondary to `fill`'s: a superseded row's demand is refused at the
//! channel ([`PreviewDemand::request`]) instead of re-seeding the cache
//! from its frozen item on every repaint; superseded queued tasks skip
//! their git/LLM compute rather than paying for doomed work; a superseded
//! `--prs` batch is dropped whole (row appends re-check inside the
//! `shared_items` lock — see `prs::PrsShared`); and a superseded skeleton
//! neither overwrites the session-shared row list / shortcut table nor
//! seeds summary hints (the one documented `fill` bypass). A superseded
//! handler's `maybe_spawn_comments` is inert for the same reason its fill
//! would drop: its *eviction* of the shared Comments entry would otherwise
//! delete the live spawn's fetch with no producer left to refill it.
//!
//! # Filling and surfacing
//!
//! Every background producer routes through the one [`PreviewOrchestrator::fill`]
//! choke point: it inserts into the cache and pokes [`super::preview_notify`] so a
//! compute that lands after skim already drew the pane repaints without a
//! keystroke. Precompute is tiered — [`PreviewOrchestrator::spawn_initial_precompute`]
//! at skeleton time (item 0 × the five local modes + summary, plus the default
//! tab for cheap branch-only rows) and [`PreviewOrchestrator::spawn_deferred_summaries`]
//! after the row drain (summaries for the remaining rows). Off-screen worktree
//! panes are demand-loaded instead of speculatively duplicating live worktree
//! I/O; Pr and Comments are never precomputed. Both tiers re-run on every spawn,
//! including a refresh (after its clear). `spawn_preview` and
//! `spawn_compute` short-circuit on an in-memory hit, so a refresh must clear
//! first or their recompute is a no-op; `spawn_summary` has no such guard and
//! always recomputes — cheap, since `crate::summary` is gated by its own
//! diff-hash disk cache.
//!
//! Precompute is best-effort background work; the tab the user is *looking
//! at* is served by a third producer, the demand worker ([`PreviewDemand`]):
//! a `preview()` cache miss on a local-git tab posts the row's item to a
//! dedicated thread that computes just that key, off `COLLECT_POOL`, so the
//! selected tab costs its own compute rather than a position in the
//! precompute queue.
//!
//! # Orchestration
//!
//! Routes preview tasks to the dedicated [`COLLECT_POOL`] (shared with the
//! row pipeline) and tracks the in-memory cache. A single pool lets workers
//! prefer whichever workload has dominant pressure: row tasks land on
//! workers' local deques and take priority during drain; preview tasks
//! sit in the pool's injector and pick up workers as they free.
//!
//! `COLLECT_POOL` is deliberately *not* the global pool: skim runs its
//! per-keystroke fuzzy matcher on the global pool, so keeping these blocking
//! git tasks off it is what prevents the picker from freezing on the first
//! keystroke. See [`COLLECT_POOL`] for the full reasoning.
//!
//! Provides a pending-task counter for the dry-run path
//! (`WORKTRUNK_PICKER_DRY_RUN`) and tests, both of which want to wait for
//! all spawned tasks to complete before reading the cache. The picker
//! entry point (`handle_picker`) uses this for its real spawns.
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, Condvar, Mutex, OnceLock};
use std::time::Duration;
use dashmap::DashMap;
use skim::prelude::Event;
use tokio::sync::mpsc::Sender;
use worktrunk::git::Repository;
use super::items::{PickerRow, PickerRowId, PreviewCache, PreviewCacheKey};
use super::preview::{LOCAL_GIT_MODES, PreviewMode};
use super::preview_notify::PreviewNotifier;
use super::summary;
use crate::commands::list::collect::COLLECT_POOL;
use crate::commands::list::model::ListItem;
/// The picker's initial preview tab — `UnifiedDiff`, shown when the picker
/// opens. Precomputed for the landing row and cheap branch-only rows; off-screen
/// worktrees use the dedicated demand worker when selected so an untracked-heavy
/// tree cannot compete with initial row collection. For the landing row, every
/// local mode fires at skeleton time so tab-cycling is responsive immediately.
const INITIAL_MODE: PreviewMode = PreviewMode::UnifiedDiff;
struct PendingGuard(Arc<AtomicUsize>);
impl Drop for PendingGuard {
fn drop(&mut self) {
self.0.fetch_sub(1, Ordering::SeqCst);
}
}
/// Identity of one pipeline spawn, held by everything that spawn starts —
/// precompute tasks, `--prs` fetches, demand requests, the handler, and the
/// skim rows themselves. [`PreviewOrchestrator::refresh`] supersedes all
/// outstanding tokens by bumping the shared counter; a producer whose token
/// is no longer current has its cache write dropped at
/// [`PreviewOrchestrator::fill`], its demand refused at
/// [`PreviewDemand::request`], its queued work skipped before compute, and
/// its writes to the session-shared row list / shortcut table declined — so
/// a refresh can never be undone by a stale straggler. Minted per spawn in
/// `PipelineFactory::spawn` (see the *Spawn generations* section of the
/// module docs).
#[derive(Clone)]
pub(super) struct SpawnGeneration {
current: Arc<AtomicUsize>,
value: usize,
}
impl SpawnGeneration {
/// Whether the spawn this token identifies is still the live one.
pub(super) fn is_current(&self) -> bool {
self.current.load(Ordering::SeqCst) == self.value
}
}
/// A generation with no refresh lifecycle behind it — nothing ever
/// supersedes it, so it is always current. For rows built outside a picker
/// session; tests building skim rows directly use this the way they use
/// [`PreviewDemand::new`].
impl Default for SpawnGeneration {
fn default() -> Self {
Self {
current: Arc::new(AtomicUsize::new(0)),
value: 0,
}
}
}
/// On-demand compute channel for the preview the user is looking at *right
/// now* — a one-slot, latest-wins handoff from skim's UI thread to a
/// dedicated worker thread.
///
/// Precompute alone leaves a gap: `SkimItem::preview` never computes (it only
/// reads the in-memory cache), so a tab without precompute would otherwise sit
/// on its loading placeholder. The demand worker closes the
/// gap: `preview()` routes a cache miss on a local-git tab here
/// ([`PreviewMode::is_local_git`]), and the worker computes exactly that key,
/// off `COLLECT_POOL` entirely — so the looked-at tab costs one disk-cache
/// read (~ms when previously computed) or one git command, not a queue
/// position.
///
/// One slot is the point: `preview()` only ever misses on the *selected*
/// row's current tab, so the newest request supersedes any unserved one and
/// rows skimmed past are never computed. A request whose key a racing pool
/// task already filled is dropped on the worker's `contains_key` check. A
/// simultaneous double-compute — the pool task for the same key mid-flight
/// when the demand is taken — is accepted rather than tracked: it's common
/// exactly once per spawn (the landing row's default tab at first paint,
/// before its skeleton-time precompute lands) and harmless (both producers
/// route through `fill` with identical content); an in-flight key set shared
/// across producers isn't worth that one duplicate `git diff`.
pub(super) struct PreviewDemand {
state: Mutex<DemandState>,
cond: Condvar,
}
/// The slot plus the close flag, under the one mutex the condvar guards.
#[derive(Default)]
struct DemandState {
request: Option<DemandRequest>,
closed: bool,
}
/// One demand: compute `mode` for `item` at the preview pane's `dims`, on
/// behalf of the spawn identified by `spawn_gen`. Self-contained (the row hands
/// over its own `Arc<ListItem>` and spawn token), so the worker needs no item
/// registry that could drift from the rows skim holds.
struct DemandRequest {
item: Arc<ListItem>,
mode: PreviewMode,
dims: (usize, usize),
spawn_gen: SpawnGeneration,
}
impl PreviewDemand {
/// The channel only — the orchestrator spawns the worker that drains it.
/// Tests building skim rows without an orchestrator use this directly:
/// requests are recorded and never served.
pub(super) fn new() -> Arc<Self> {
Arc::new(Self {
state: Mutex::new(DemandState::default()),
cond: Condvar::new(),
})
}
/// Publish the selected row's awaited preview, replacing any unserved
/// request. Called from skim's UI thread on every `preview()` cache miss,
/// so it must stay non-blocking (a brief uncontended lock).
///
/// A request whose spawn a refresh superseded is refused: after `alt-r`
/// clears the cache, the pre-refresh rows keep missing (and posting) on
/// every repaint until the rebuilt skeleton replaces them, and each of
/// those computes would be dropped at `fill` anyway — refusing at the
/// channel keeps the worker free for the live spawn's first demand.
pub(super) fn request(
&self,
item: Arc<ListItem>,
mode: PreviewMode,
dims: (usize, usize),
spawn_gen: SpawnGeneration,
) {
let mut state = self.state.lock().unwrap();
if state.closed || !spawn_gen.is_current() {
return;
}
state.request = Some(DemandRequest {
item,
mode,
dims,
spawn_gen,
});
self.cond.notify_one();
}
/// Close the channel: the worker drains out and releases its captures.
/// Called when the orchestrator drops (the picker is done), so the parked
/// thread doesn't pin the preview cache and repo until process exit.
fn close(&self) {
self.state.lock().unwrap().closed = true;
self.cond.notify_one();
}
/// Worker side: block until a request is available and take it, or
/// return `None` once the channel is closed (a parked request is
/// dropped — the picker is gone, nothing would read the fill).
fn take_blocking(&self) -> Option<DemandRequest> {
let mut state = self.state.lock().unwrap();
loop {
if state.closed {
return None;
}
if let Some(req) = state.request.take() {
return Some(req);
}
state = self.cond.wait(state).unwrap();
}
}
}
pub(super) struct PreviewOrchestrator {
pub(super) cache: PreviewCache,
pending: Arc<AtomicUsize>,
/// Bridges each fill to skim's event loop so a finished compute surfaces
/// without a keystroke (see [`PreviewNotifier`]). Shared with the skim
/// items, which record their awaited preview; every fill site here notifies.
notifier: Arc<PreviewNotifier>,
/// Repository used by preview compute. Bound at construction (unit tests
/// inject a `TestRepo`-rooted `Repository` instead of relying on process
/// CWD) and rebound by [`Self::refresh`] to each rebuilt spawn's repo, so
/// recompute reads a current `RepoCache` rather than session-start state.
///
/// Cloned out of the cell into each spawned task, so one spawn's tasks
/// share the underlying `Arc<RepoCache>` — including the memoized
/// comparison base that [`Repository::branch_diff_spec`] resolves from a
/// single `for-each-ref` scan. That shared cache is how the BranchDiff
/// preview avoids re-scanning refs per item. The lock is held only for
/// the clone, never across a compute.
repo: Arc<Mutex<Repository>>,
/// The live spawn's generation; [`Self::generation`] mints tokens at this
/// value and [`Self::refresh`] bumps it to supersede them. See
/// [`SpawnGeneration`].
generation: Arc<AtomicUsize>,
/// The on-demand channel serving the selected row's awaited tab (see
/// [`PreviewDemand`]). Handed to each worktree-backed row at
/// construction; its worker thread is spawned once here and shared
/// across `alt-r` spawns, like the cache.
demand: Arc<PreviewDemand>,
}
impl PreviewOrchestrator {
pub(super) fn new(repo: Repository, render_tx: Arc<OnceLock<Sender<Event>>>) -> Self {
let cache: PreviewCache = Arc::new(DashMap::new());
let pending = Arc::new(AtomicUsize::new(0));
let notifier = Arc::new(PreviewNotifier::new(render_tx));
let demand = PreviewDemand::new();
let repo = Arc::new(Mutex::new(repo));
{
let demand = Arc::clone(&demand);
let cache = Arc::clone(&cache);
let notifier = Arc::clone(¬ifier);
let pending = Arc::clone(&pending);
let repo = Arc::clone(&repo);
// Detached worker thread: it parks on the condvar between
// requests and exits when the orchestrator's `Drop` closes the
// channel. Spawn failure degrades to the pre-demand behavior —
// the tab fills when precompute reaches it.
let _ = std::thread::Builder::new()
.name("wt-preview-demand".into())
.spawn(move || {
while let Some(req) = demand.take_blocking() {
// Read the repo cell per request, not once at spawn:
// a refresh rebinds it, and a demand from the rebuilt
// spawn must compute against the rebuilt repo.
let repo = repo.lock().unwrap().clone();
Self::serve_demand(&cache, ¬ifier, &pending, &repo, req);
}
});
}
Self {
cache,
pending,
notifier,
repo,
generation: Arc::new(AtomicUsize::new(0)),
demand,
}
}
/// Supersede the previous spawn's producers and rebind compute state to a
/// rebuilt spawn's `repo`. Called from `PipelineFactory::spawn` on every
/// `alt-r` rebuild, before the new spawn starts any producer.
///
/// Order matters: the generation bump comes first, so a stale in-flight
/// fill racing this call either lands before the clear (wiped by it) or
/// after (dropped by [`Self::fill`]'s check) — clear-then-bump would
/// leave a window where a stale fill lands post-clear and survives until
/// the next refresh.
pub(super) fn refresh(&self, repo: Repository) {
self.generation.fetch_add(1, Ordering::SeqCst);
*self.repo.lock().unwrap() = repo;
self.cache.clear();
}
/// Mint a token for the live spawn. Everything the spawn starts carries a
/// clone; a later [`Self::refresh`] invalidates them all at once.
pub(super) fn generation(&self) -> SpawnGeneration {
SpawnGeneration {
current: Arc::clone(&self.generation),
value: self.generation.load(Ordering::SeqCst),
}
}
/// Serve one demand request: compute the awaited preview and fill the
/// cache. The demand worker's whole loop body, factored out so each arm
/// is unit-testable without racing the thread.
///
/// Skips a key a racing pool task already filled, and a request parked
/// across a refresh (posted while its spawn was still current, taken
/// after it was superseded) — computing the latter would make the live
/// spawn's first demand queue behind a git call whose fill is doomed to
/// drop. A panicking compute is contained to its key: on a rayon worker
/// it would abort the process, but here it would only unwind the worker
/// thread — and a dead worker silently regresses every later navigation
/// to queue-wait latency for the rest of the session — so log and keep
/// serving.
fn serve_demand(
cache: &PreviewCache,
notifier: &Arc<PreviewNotifier>,
pending: &Arc<AtomicUsize>,
repo: &Repository,
req: DemandRequest,
) {
if !req.spawn_gen.is_current() {
return;
}
let key = (PickerRowId::local(&req.item), req.mode);
if cache.contains_key(&key) {
return;
}
let (w, h) = req.dims;
let computed = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
PickerRow::compute_and_page_preview(repo, &req.item, req.mode, w, h)
}));
let Ok((value, log_disk_hit)) = computed else {
tracing::debug!(
row = %key.0,
mode = ?key.1,
"preview demand compute panicked; leaving the tab to precompute"
);
return;
};
Self::fill(cache, notifier, &req.spawn_gen, key, value);
if log_disk_hit {
Self::spawn_log_refresh(
cache,
notifier,
pending,
&req.spawn_gen,
req.item,
repo,
(w, h),
);
}
}
/// The shared demand channel, handed to each worktree-backed skim row so
/// its `preview()` can request the awaited tab on a cache miss.
pub(super) fn demand(&self) -> &Arc<PreviewDemand> {
&self.demand
}
/// The repository the live spawn computes previews against (a clone out
/// of the rebindable cell — see the `repo` field).
pub(super) fn repo(&self) -> Repository {
self.repo.lock().unwrap().clone()
}
/// The shared preview notifier, handed to each skim item so its `preview()`
/// can record what it's awaiting (see [`PreviewNotifier`]).
pub(super) fn notifier(&self) -> &Arc<PreviewNotifier> {
&self.notifier
}
/// Insert a computed preview into the cache and surface it if the selected
/// row is awaiting exactly this key. The single fill path: every background
/// producer routes through this so a finished compute can never reach the
/// cache without giving skim the chance to repaint it — and, symmetrically,
/// so a producer whose spawn a refresh superseded can never re-seed the
/// just-cleared cache with stale content (the write is dropped, and nothing
/// notifies).
pub(super) fn fill(
cache: &PreviewCache,
notifier: &PreviewNotifier,
spawn_gen: &SpawnGeneration,
key: PreviewCacheKey,
value: String,
) {
{
// The generation check and the insert hold the key's shard write
// lock together (`entry` acquires it), making them atomic against
// `refresh`'s bump-then-clear: a check that passes here happened
// before the bump, so the clear — which starts after the bump and
// must wait for this shard lock — always runs after the insert
// and wipes it. A plain check-then-insert would leave a third
// interleaving (check passes pre-bump, insert lands post-clear)
// where the stale entry survives. Compute has already finished by
// now, so the lock spans only the check and the insert — never a
// subprocess — keeping skim's UI-thread reads unblocked.
let entry = cache.entry(key.clone());
if !spawn_gen.is_current() {
return;
}
entry.insert(value);
}
notifier.notify_filled(&key);
}
/// Spawn a preview compute task. Returns immediately.
///
/// Idempotent on the cache key: if another task already populated it,
/// this one short-circuits after the `contains_key` check. Compute
/// happens outside any DashMap lock so skim's UI thread (which calls
/// `preview()` synchronously and reads via `DashMap::get`) is never
/// blocked on a shard write held across git/pager subprocesses.
///
/// Log mode that hits the disk cache also enqueues a refresh task to
/// recompute the embedded ref decorations before the next visit (see
/// [`Self::spawn_log_refresh`]).
pub(super) fn spawn_preview(
&self,
spawn_gen: &SpawnGeneration,
item: Arc<ListItem>,
mode: PreviewMode,
dims: (usize, usize),
) {
let cache = Arc::clone(&self.cache);
let notifier = Arc::clone(&self.notifier);
let (w, h) = dims;
let repo = self.repo();
let pending = Arc::clone(&self.pending);
let spawn_gen = spawn_gen.clone();
self.spawn_task(move || {
// A superseded spawn's queued task is doomed — its fill would
// drop — so skip the compute, not just the write. `fill` remains
// the correctness gate; this (and the same check in the other
// task bodies) only stops a refresh from paying for the prior
// spawn's still-queued git/LLM work.
if !spawn_gen.is_current() {
return;
}
let cache_key = (PickerRowId::local(&item), mode);
if cache.contains_key(&cache_key) {
return;
}
let (value, log_disk_hit) =
PickerRow::compute_and_page_preview(&repo, &item, mode, w, h);
Self::fill(&cache, ¬ifier, &spawn_gen, cache_key, value);
if log_disk_hit {
Self::spawn_log_refresh(
&cache,
¬ifier,
&pending,
&spawn_gen,
item,
&repo,
(w, h),
);
}
});
}
/// Enqueue the background re-render that follows a Log disk-cache hit
/// (recomputing the embedded ref decorations — see the `LogCacheEntry`
/// docstring for why the SHA-keyed cache drifts). Lands on
/// `COLLECT_POOL`'s FIFO injector, behind in-flight foreground
/// precompute. Shared by the pool producer (`spawn_preview`) and the
/// demand worker.
fn spawn_log_refresh(
cache: &PreviewCache,
notifier: &Arc<PreviewNotifier>,
pending: &Arc<AtomicUsize>,
spawn_gen: &SpawnGeneration,
item: Arc<ListItem>,
repo: &Repository,
dims: (usize, usize),
) {
pending.fetch_add(1, Ordering::SeqCst);
let guard = PendingGuard(Arc::clone(pending));
let cache = Arc::clone(cache);
let notifier = Arc::clone(notifier);
let repo = repo.clone();
let spawn_gen = spawn_gen.clone();
COLLECT_POOL.spawn_fifo(move || {
let _g = guard;
if !spawn_gen.is_current() {
return;
}
let (w, h) = dims;
let rendered = PickerRow::refresh_log_preview(&repo, &item, w, h);
// Skip empty results so a transient `git log` failure
// doesn't poison the in-memory cache with "" and wipe
// out the value the producer just inserted.
if !rendered.is_empty() {
Self::fill(
&cache,
¬ifier,
&spawn_gen,
(PickerRowId::local(&item), PreviewMode::Log),
rendered,
);
}
});
}
/// Spawn an LLM summary task. Returns immediately.
pub(super) fn spawn_summary(
&self,
spawn_gen: &SpawnGeneration,
item: Arc<ListItem>,
llm_command: String,
) {
let cache = Arc::clone(&self.cache);
let notifier = Arc::clone(&self.notifier);
let repo = self.repo();
let spawn_gen = spawn_gen.clone();
self.spawn_task(move || {
if !spawn_gen.is_current() {
return;
}
let summary = summary::generate_summary_for_item(&item, &llm_command, &repo);
Self::fill(
&cache,
¬ifier,
&spawn_gen,
(PickerRowId::local(&item), PreviewMode::Summary),
summary,
);
});
}
/// Spawn a preview-compute task whose value comes from a caller-supplied
/// closure. Returns immediately.
///
/// The general-purpose companion to [`Self::spawn_preview`]: that method
/// computes a worktree `ListItem`'s preview via the local-git
/// `compute_and_page_preview`, whereas `--prs` rows (no local checkout) have
/// no local worktree, so they fetch their `log` / `comments` panes through a
/// forge CLI and pass that work in as `compute`. Both share the same
/// [`PreviewCache`], the same `COLLECT_POOL` routing, and the same
/// pending-counter accounting (so the dry-run path's `wait_for_idle` and
/// the cache dump cover PR-row fetches too).
///
/// Idempotent on `key` (short-circuits on a cache hit) and runs `compute`
/// outside any DashMap lock, like `spawn_preview`. A `None` or empty result
/// is deliberately NOT cached: the slot stays empty (read as "still
/// loading"), so a later `spawn_compute` with the same key recomputes. The
/// `--prs` callers spawn once per row and never re-invoke, so they convert a
/// failed fetch into a terminal "couldn't load" pane and hand that back as
/// `Some(..)` rather than `None` — an uncached `None` would strand the tab on
/// its loading placeholder until the picker reopens.
pub(super) fn spawn_compute<F>(
&self,
spawn_gen: &SpawnGeneration,
key: PreviewCacheKey,
compute: F,
) where
F: FnOnce(&Repository) -> Option<String> + Send + 'static,
{
let cache = Arc::clone(&self.cache);
let notifier = Arc::clone(&self.notifier);
let repo = self.repo();
let spawn_gen = spawn_gen.clone();
self.spawn_task(move || {
if !spawn_gen.is_current() || cache.contains_key(&key) {
return;
}
if let Some(value) = compute(&repo)
&& !value.is_empty()
{
Self::fill(&cache, ¬ifier, &spawn_gen, key, value);
}
});
}
/// Spawn the skeleton-time pre-compute tier.
///
/// Fires at `on_skeleton`. Two layers of work:
/// - First item × all 5 modes + first item summary — the user lands on
/// row 0 and frequently tab-cycles modes there.
/// - Branch-only items 1..N × [`INITIAL_MODE`] — pre-warms the committed
/// diff they can serve cheaply from the SHA-keyed cache. Off-screen
/// worktrees are demand-loaded when selected: their untracked-inclusive
/// default can require an index copy and full `git add -N` walk.
///
/// Summaries for items 1..N are deferred to
/// [`Self::spawn_deferred_summaries`], which fires after the row pipeline
/// tears down. Their subsidiary local-git modes are demand-loaded.
pub(super) fn spawn_initial_precompute(
&self,
spawn_gen: &SpawnGeneration,
items: &[Arc<ListItem>],
preview_dims: (usize, usize),
llm_command: Option<&str>,
) {
let Some(first) = items.first() else { return };
// First item: all modes + summary.
for mode in LOCAL_GIT_MODES {
self.spawn_preview(spawn_gen, Arc::clone(first), mode, preview_dims);
}
if let Some(llm) = llm_command {
self.spawn_summary(spawn_gen, Arc::clone(first), llm.to_string());
}
// Branch-only items 1..N: default tab only. Worktree-backed rows and
// all other local modes are demand-loaded.
for item in items
.iter()
.skip(1)
.filter(|item| item.worktree_data().is_none())
{
self.spawn_preview(spawn_gen, Arc::clone(item), INITIAL_MODE, preview_dims);
}
}
/// Spawn configured summaries for items 1..N after collection completes.
///
/// Fires from the picker handler's `on_collect_complete` hook — i.e.
/// after `collect::collect`'s drain ends. `COLLECT_POOL` serves
/// both the row pipeline and the preview pipeline. Deferring this
/// tier keeps these submissions out of that pool's injector while
/// row tasks are still landing on workers' local deques. The
/// Each LLM call can take seconds. Called from outside any rayon worker
/// (the picker-collect bg thread), so submissions land on rayon's FIFO
/// injector. Local-git subsidiary modes are served by the demand worker
/// when selected instead of being computed for every unseen row.
pub(super) fn spawn_deferred_summaries(
&self,
spawn_gen: &SpawnGeneration,
rest: &[Arc<ListItem>],
llm_command: Option<&str>,
) {
if let Some(llm) = llm_command {
for item in rest {
self.spawn_summary(spawn_gen, Arc::clone(item), llm.to_string());
}
}
}
/// Seed the Summary cache with a static hint for every item.
///
/// Used when summaries are disabled — gives the Summary tab something
/// useful instead of a perpetual "Generating…" placeholder. Pure
/// synchronous `DashMap::insert` calls (zero CPU, no subprocess), so
/// this runs at skeleton time for every row regardless of position
/// — no contention concern.
pub(super) fn seed_summary_hints(&self, items: &[Arc<ListItem>], hint: &str) {
for item in items {
self.cache.insert(
(PickerRowId::local(item), PreviewMode::Summary),
hint.to_string(),
);
}
}
fn spawn_task<F: FnOnce() + Send + 'static>(&self, task: F) {
self.pending.fetch_add(1, Ordering::SeqCst);
let guard = PendingGuard(Arc::clone(&self.pending));
let wrapped = move || {
// Guard decrements on drop, so a panic inside `task` still
// releases the counter — otherwise `wait_for_idle` hangs
// forever on any panicking preview task.
let _g = guard;
task();
};
// The `pending` counter is independent of which pool the task
// lands on, so routing through `COLLECT_POOL` (shared with the row
// pipeline, off the global pool skim's matcher uses) doesn't change
// `wait_for_idle` semantics in tests or the dry-run path.
COLLECT_POOL.spawn(wrapped);
}
/// Block until all pool-spawned tasks complete.
///
/// Used by the dry-run path and tests; production never waits — tasks
/// are fire-and-forget while skim runs. Polls at 10ms resolution; tasks
/// typically take tens to hundreds of ms, so a condvar isn't worth the
/// complexity.
///
/// Scope: the `pending` counter covers everything spawned through
/// [`Self::spawn_task`] and [`Self::spawn_log_refresh`]. The demand
/// worker's own computes are outside it — they're keystroke-driven, and
/// neither the dry-run path nor `wait_for_idle` callers drive
/// `preview()`; a test exercising the demand path polls the cache
/// instead (see `preview_miss_is_served_by_demand_worker`).
pub(super) fn wait_for_idle(&self) {
while self.pending.load(Ordering::SeqCst) > 0 {
std::thread::sleep(Duration::from_millis(10));
}
}
/// Preview-cache inventory for the dry-run dump: one sorted
/// `{row_id, mode, bytes, content}` object per cached preview. Content is
/// included because dry-run integration tests need to distinguish a real
/// preview from an equally non-empty error pane; the dump is test-only.
pub(super) fn cache_entries_json(&self) -> serde_json::Value {
let mut entries: Vec<_> = self
.cache
.iter()
.map(|e| {
let (row, mode) = e.key();
(
row.to_string(),
*mode as u8,
e.value().len(),
e.value().clone(),
)
})
.collect();
entries.sort();
entries
.into_iter()
.map(|(row, mode, bytes, content)| {
serde_json::json!({
"row_id": row,
"mode": mode,
"bytes": bytes,
"content": content,
})
})
.collect()
}
}
impl Drop for PreviewOrchestrator {
/// Close the demand channel so the worker exits and drops its captures
/// (preview cache, repo) when the picker ends — `wt switch` keeps
/// running (hooks, the switch itself) after the picker returns, and a
/// parked thread would otherwise pin them until process exit.
fn drop(&mut self) {
self.demand.close();
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::commands::list::model::WorktreeData;
use std::fs;
use worktrunk::testing::TestRepo;
fn as_worktree(item: ListItem, path: &std::path::Path, data: WorktreeData) -> ListItem {
let subject = worktrunk::git::WorktreeRef::new(path, item.branch(), item.head());
ListItem::new_worktree(subject, data)
}
fn orch_for(t: &TestRepo) -> PreviewOrchestrator {
// No render_tx published, so fills don't notify — these tests assert on
// the cache, not on skim repaints (see `fill_notifies_only_awaited_key`).
PreviewOrchestrator::new(Repository::at(t.path()).unwrap(), Arc::new(OnceLock::new()))
}
fn item_key(item: &ListItem) -> PickerRowId {
PickerRowId::local(item)
}
fn branch_key(branch: &str) -> PickerRowId {
item_key(&ListItem::new_branch(
"0000000".to_string(),
branch.to_string(),
))
}
fn pr_key(number: u64) -> PickerRowId {
PickerRowId::change_request(crate::commands::list::ci_status::PrRef::pr(number))
}
fn dirty_worktree_item() -> (TestRepo, Arc<ListItem>) {
let t = TestRepo::new();
fs::write(t.path().join("README.md"), "# Project\n").unwrap();
t.repo.run_command(&["add", "README.md"]).unwrap();
t.repo.run_command(&["commit", "-m", "initial"]).unwrap();
// Dirty the working tree so WorkingTree diff has content.
fs::write(t.path().join("README.md"), "# Project\nmore\n").unwrap();
let head = t
.repo
.run_command(&["rev-parse", "HEAD"])
.unwrap()
.trim()
.to_string();
let item = as_worktree(
ListItem::new_branch(head, "main".to_string()),
t.path(),
WorktreeData::default(),
);
(t, Arc::new(item))
}
fn detached_worktree_item(path: &std::path::Path, head: &str) -> Arc<ListItem> {
let item = ListItem::new_worktree(
worktrunk::git::WorktreeRef::new(path, None, head),
WorktreeData {
detached: true,
..Default::default()
},
);
Arc::new(item)
}
/// End-to-end: orchestrator spawns real previews, populates the cache.
/// Regression test for the "previews never load" class of bugs — if the
/// spawn pipeline silently fails, this catches it without needing skim.
#[test]
fn orchestrator_populates_cache_for_real_worktree() {
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
orch.spawn_preview(
&orch.generation(),
Arc::clone(&item),
PreviewMode::WorkingTree,
(80, 24),
);
orch.spawn_preview(
&orch.generation(),
Arc::clone(&item),
PreviewMode::Log,
(80, 24),
);
orch.wait_for_idle();
let row_id = item_key(&item);
let wt_key = (row_id.clone(), PreviewMode::WorkingTree);
let log_key = (row_id, PreviewMode::Log);
assert!(
orch.cache.contains_key(&wt_key),
"WorkingTree preview not cached"
);
assert!(orch.cache.contains_key(&log_key), "Log preview not cached");
assert!(
!orch.cache.get(&wt_key).unwrap().is_empty(),
"WorkingTree preview was empty"
);
}
/// Two detached worktrees can point at the same commit while carrying
/// different mutable state. Visiting the clean one first must not make the
/// dirty one's producer short-circuit against the clean preview.
#[test]
fn detached_worktrees_at_same_commit_have_distinct_preview_ids() {
let t = TestRepo::with_initial_commit();
let linked = worktrunk::testing::tempdir().unwrap();
let clean_path = linked.path().join("clean");
let dirty_path = linked.path().join("dirty");
let clean_arg = clean_path.to_str().unwrap();
let dirty_arg = dirty_path.to_str().unwrap();
t.repo
.run_command(&["worktree", "add", "--detach", clean_arg, "HEAD"])
.unwrap();
t.repo
.run_command(&["worktree", "add", "--detach", dirty_arg, "HEAD"])
.unwrap();
fs::write(dirty_path.join("file.txt"), "hello\nchanged\n").unwrap();
let head = t
.repo
.run_command(&["rev-parse", "HEAD"])
.unwrap()
.trim()
.to_string();
let clean = detached_worktree_item(&clean_path, &head);
let dirty = detached_worktree_item(&dirty_path, &head);
let clean_key = item_key(&clean);
let dirty_key = item_key(&dirty);
assert_ne!(clean_key, dirty_key, "worktree path is part of identity");
let orch = orch_for(&t);
orch.spawn_preview(
&orch.generation(),
Arc::clone(&clean),
PreviewMode::UnifiedDiff,
(80, 24),
);
orch.wait_for_idle();
orch.spawn_preview(
&orch.generation(),
Arc::clone(&dirty),
PreviewMode::UnifiedDiff,
(80, 24),
);
orch.wait_for_idle();
let clean_preview = orch
.cache
.get(&(clean_key, PreviewMode::UnifiedDiff))
.expect("clean preview cached")
.clone();
let dirty_preview = orch
.cache
.get(&(dirty_key, PreviewMode::UnifiedDiff))
.expect("dirty preview cached")
.clone();
assert!(
!clean_preview.contains("changed"),
"clean checkout preview: {clean_preview:?}"
);
assert!(
dirty_preview.contains("file.txt") && dirty_preview.contains("changed"),
"dirty checkout preview: {dirty_preview:?}"
);
}
#[test]
fn duplicate_spawn_short_circuits() {
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
orch.spawn_preview(
&orch.generation(),
Arc::clone(&item),
PreviewMode::WorkingTree,
(80, 24),
);
orch.wait_for_idle();
let key = (item_key(&item), PreviewMode::WorkingTree);
let first = orch.cache.get(&key).unwrap().value().clone();
// Second spawn should hit `contains_key` and skip.
orch.spawn_preview(
&orch.generation(),
Arc::clone(&item),
PreviewMode::WorkingTree,
(80, 24),
);
orch.wait_for_idle();
let second = orch.cache.get(&key).unwrap().value().clone();
assert_eq!(first, second);
}
/// `spawn_summary` delegates to the same spawn-task machinery as
/// `spawn_preview`, but via the LLM summary path. The test uses `/bin/cat`
/// as a fake LLM command (it echoes the prompt back), so the test stays
/// hermetic — no real LLM is invoked, but the cache receives a Summary
/// entry proving the task ran to completion.
#[test]
fn spawn_summary_populates_cache() {
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
orch.spawn_summary(
&orch.generation(),
Arc::clone(&item),
"/bin/cat".to_string(),
);
orch.wait_for_idle();
assert!(
orch.cache
.contains_key(&(item_key(&item), PreviewMode::Summary)),
"Summary entry not cached"
);
}
/// Disk-cache hit on a Log preview enqueues a background refresh that
/// overwrites both the disk file and the in-memory DashMap. Seed the
/// disk cache with a stale `LogCacheEntry` containing a marker —
/// after `spawn_preview` + `wait_for_idle`, neither cache should
/// hold the marker, because the refresh thread re-ran
/// `compute_log_raw_and_stats` and wrote real git-log output.
///
/// `wait_for_idle` covers the refresh thread's task because the
/// producer increments `pending` before sending and the refresh
/// thread decrements via `PendingGuard` after running.
#[test]
fn log_disk_hit_triggers_background_refresh() {
let (t, item) = dirty_worktree_item();
let repo = Repository::at(t.path()).unwrap();
let stale = super::super::preview_cache::LogCacheEntry {
raw_log: "STALE_MARKER\n".to_string(),
stats: std::collections::HashMap::new(),
};
super::super::preview_cache::write_log(&repo, item.head(), 80, 24, &stale);
let orch = orch_for(&t);
orch.spawn_preview(
&orch.generation(),
Arc::clone(&item),
PreviewMode::Log,
(80, 24),
);
orch.wait_for_idle();
let disk = super::super::preview_cache::read_log(&repo, item.head(), 80, 24)
.expect("disk cache present after refresh");
assert!(
!disk.raw_log.contains("STALE_MARKER"),
"refresh should overwrite stale disk entry, got raw_log: {:?}",
disk.raw_log
);
let in_memory = orch
.cache
.get(&(item_key(&item), PreviewMode::Log))
.expect("in-memory entry present")
.clone();
assert!(
!in_memory.contains("STALE_MARKER"),
"refresh should overwrite stale in-memory entry, got: {in_memory:?}"
);
}
/// Non-Log modes have content-addressed cache keys (BranchDiff is
/// `(base_sha, branch_sha, w)`, UpstreamDiff similar) and no
/// decoration drift, so a disk-cache hit on those modes must NOT
/// enqueue a Log refresh. Seed the disk Log cache with stale content
/// and spawn a BranchDiff preview — the disk Log cache must remain
/// stale because the refresh thread never received a task.
#[test]
fn non_log_modes_do_not_trigger_log_refresh() {
let (t, item) = dirty_worktree_item();
let repo = Repository::at(t.path()).unwrap();
let stale = super::super::preview_cache::LogCacheEntry {
raw_log: "STALE_MARKER\n".to_string(),
stats: std::collections::HashMap::new(),
};
super::super::preview_cache::write_log(&repo, item.head(), 80, 24, &stale);
let orch = orch_for(&t);
orch.spawn_preview(
&orch.generation(),
Arc::clone(&item),
PreviewMode::BranchDiff,
(80, 24),
);
orch.wait_for_idle();
let disk = super::super::preview_cache::read_log(&repo, item.head(), 80, 24)
.expect("disk Log cache untouched");
assert_eq!(
disk.raw_log, "STALE_MARKER\n",
"non-Log spawn must not trigger Log refresh"
);
}
/// `spawn_compute` fills the shared cache from a closure, short-circuits a
/// duplicate key, and refuses to cache a `None` or empty result (so a
/// transient forge failure doesn't pin a blank pane). One test covers the
/// belief "the generic spawn path behaves like spawn_preview's caching".
#[test]
fn spawn_compute_fills_caches_once_and_skips_empty() {
let t = TestRepo::new();
let orch = orch_for(&t);
// A populated value lands in the cache under its key.
orch.spawn_compute(&orch.generation(), (pr_key(7), PreviewMode::Log), |_| {
Some("commit list".to_string())
});
orch.wait_for_idle();
assert_eq!(
orch.cache
.get(&(pr_key(7), PreviewMode::Log))
.map(|v| v.clone()),
Some("commit list".to_string())
);
// A second spawn for the same key short-circuits on `contains_key`, so
// the original value survives even though this closure would overwrite.
let replacement = Some("REPLACED".to_string());
let duplicate_key = (pr_key(7), PreviewMode::Log);
orch.spawn_compute(&orch.generation(), duplicate_key, move |_| replacement);
orch.wait_for_idle();
assert_eq!(
orch.cache
.get(&(pr_key(7), PreviewMode::Log))
.map(|v| v.clone()),
Some("commit list".to_string()),
"duplicate key short-circuits"
);
// `None` (forge failure) and `Some("")` both leave the slot empty.
orch.spawn_compute(&orch.generation(), (pr_key(9), PreviewMode::Log), |_| None);
orch.spawn_compute(&orch.generation(), (pr_key(8), PreviewMode::Log), |_| {
Some(String::new())
});
orch.wait_for_idle();
assert!(
!orch.cache.contains_key(&(pr_key(9), PreviewMode::Log)),
"None is not cached"
);
assert!(
!orch.cache.contains_key(&(pr_key(8), PreviewMode::Log)),
"empty string is not cached"
);
}
/// End-to-end demand path: a `preview()` cache miss on a local-git tab is
/// computed by the demand worker and served — without any precompute
/// spawn touching the pool. Pins that demand-loaded subsidiary panes do
/// not depend on speculative bulk precompute.
#[test]
fn preview_miss_is_served_by_demand_worker() {
use super::super::items::{LocalCheckout, LocalContent, PickerRow, PickerRowSubject};
use skim::prelude::{PreviewContext, SkimItem};
use std::sync::Mutex;
use std::sync::atomic::AtomicBool;
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
let row_id = item_key(&item);
let row = PickerRow {
search_base: String::new(),
gutter: '@',
rendered: Arc::new(Mutex::new(String::new())),
branch_name: "main".to_string(),
output_token: "main".to_string(),
subject: PickerRowSubject::Local(LocalCheckout {
item: Arc::clone(&item),
demand: Arc::clone(orch.demand()),
spawn_gen: orch.generation(),
has_upstream: false,
summaries_enabled: false,
local_content: Arc::new(Mutex::new(LocalContent::default())),
morphed: Arc::new(AtomicBool::new(false)),
}),
preview_cache: Arc::clone(&orch.cache),
pr_status: Arc::new(Mutex::new(None)),
notifier: Arc::clone(orch.notifier()),
};
// The picker opens on UnifiedDiff — the process-global default tab,
// which this test deliberately leaves untouched (other tests read
// it). This render misses and posts the demand. No assertion on the
// returned placeholder: the worker races the render's own cache read
// by design, so on a stalled thread the first render could already
// carry the diff.
let ctx = PreviewContext {
query: "",
cmd_query: "",
width: 80,
height: 24,
current_index: 0,
current_selection: "",
selected_indices: &[],
selections: &[],
};
drop(row.preview(ctx));
// The demand worker fills the key with the real diff. Bounded poll so
// a dead worker fails instead of hanging the suite.
let key = (row_id, PreviewMode::UnifiedDiff);
let deadline = std::time::Instant::now() + Duration::from_secs(60);
while !orch.cache.contains_key(&key) {
assert!(
std::time::Instant::now() < deadline,
"demand worker never filled the awaited key"
);
std::thread::sleep(Duration::from_millis(10));
}
let served = orch.cache.get(&key).unwrap().clone();
assert!(
served.contains("README"),
"demand-computed complete diff served: {served:?}"
);
}
#[test]
fn initial_precompute_skips_offscreen_worktrees_but_warms_branches() {
let (t, first) = dirty_worktree_item();
let head = first.head().to_string();
t.repo.run_command(&["branch", "branch-only"]).unwrap();
let offscreen = as_worktree(
ListItem::new_branch(head.clone(), "offscreen".to_string()),
&t.path().join("offscreen"),
WorktreeData::default(),
);
let offscreen = Arc::new(offscreen);
let branch = Arc::new(ListItem::new_branch(head, "branch-only".to_string()));
let orch = orch_for(&t);
orch.spawn_initial_precompute(
&orch.generation(),
&[first, Arc::clone(&offscreen), Arc::clone(&branch)],
(80, 24),
None,
);
orch.wait_for_idle();
assert!(
!orch
.cache
.contains_key(&(item_key(&offscreen), PreviewMode::UnifiedDiff)),
"off-screen worktree should wait for selected-row demand"
);
assert!(
orch.cache
.contains_key(&(item_key(&branch), PreviewMode::UnifiedDiff)),
"branch-only default should be prewarmed from the committed diff"
);
}
/// A key a racing pool task already filled is not recomputed: serve_demand
/// (the worker's loop body, driven directly so nothing races) returns
/// before compute and the existing value survives.
#[test]
fn serve_demand_skips_already_filled_key() {
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
let row_id = item_key(&item);
let key = (row_id.clone(), PreviewMode::WorkingTree);
PreviewOrchestrator::fill(
&orch.cache,
orch.notifier(),
&orch.generation(),
key.clone(),
"already here".to_string(),
);
PreviewOrchestrator::serve_demand(
&orch.cache,
orch.notifier(),
&orch.pending,
&orch.repo(),
DemandRequest {
item,
mode: PreviewMode::WorkingTree,
dims: (80, 24),
spawn_gen: orch.generation(),
},
);
assert_eq!(
orch.cache.get(&key).unwrap().clone(),
"already here",
"a filled key is skipped, not recomputed"
);
}
/// A panicking compute must not unwind out of serve_demand — on the real
/// worker thread that would silently kill demand serving for the rest of
/// the session. `Pr` mode's compute arm is `unreachable!`, a deterministic
/// panic source; the panic is contained and the key stays unfilled.
#[test]
fn serve_demand_contains_a_panicking_compute() {
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
let row_id = item_key(&item);
PreviewOrchestrator::serve_demand(
&orch.cache,
orch.notifier(),
&orch.pending,
&orch.repo(),
DemandRequest {
item,
mode: PreviewMode::Pr,
dims: (80, 24),
spawn_gen: orch.generation(),
},
);
assert!(
!orch.cache.contains_key(&(row_id, PreviewMode::Pr)),
"a panicked compute fills nothing"
);
}
/// A Log disk hit served on demand enqueues the same decoration refresh
/// the pool path does (see `log_disk_hit_triggers_background_refresh`):
/// the stale seeded entry is overwritten once the pending-tracked refresh
/// drains.
#[test]
fn serve_demand_log_disk_hit_enqueues_refresh() {
let (t, item) = dirty_worktree_item();
let repo = Repository::at(t.path()).unwrap();
let stale = super::super::preview_cache::LogCacheEntry {
raw_log: "STALE_MARKER\n".to_string(),
stats: std::collections::HashMap::new(),
};
super::super::preview_cache::write_log(&repo, item.head(), 80, 24, &stale);
let orch = orch_for(&t);
let row_id = item_key(&item);
PreviewOrchestrator::serve_demand(
&orch.cache,
orch.notifier(),
&orch.pending,
&orch.repo(),
DemandRequest {
item,
mode: PreviewMode::Log,
dims: (80, 24),
spawn_gen: orch.generation(),
},
);
orch.wait_for_idle();
let in_memory = orch
.cache
.get(&(row_id, PreviewMode::Log))
.expect("in-memory entry present")
.clone();
assert!(
!in_memory.contains("STALE_MARKER"),
"the demand-served disk hit was refreshed: {in_memory:?}"
);
}
/// A refresh supersedes the prior spawn's producers: every producer path
/// carrying the pre-refresh token — pool preview/summary/compute tasks,
/// the log-refresh follow-up, and the `fill` choke point itself — leaves
/// the cleared cache untouched, while the rebuilt spawn's token fills
/// normally. Pins the fix for the stale-drain race the module docs'
/// *Spawn generations* section describes.
#[test]
fn refresh_supersedes_stale_spawn_fills() {
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
let stale = orch.generation();
let row_id = item_key(&item);
orch.refresh(Repository::at(t.path()).unwrap());
// Queued task bodies drop the doomed work before computing.
orch.spawn_preview(
&stale,
Arc::clone(&item),
PreviewMode::WorkingTree,
(80, 24),
);
orch.spawn_summary(&stale, Arc::clone(&item), "/bin/cat".to_string());
orch.spawn_compute(&stale, (pr_key(1), PreviewMode::Log), |_| {
Some("stale".to_string())
});
PreviewOrchestrator::spawn_log_refresh(
&orch.cache,
orch.notifier(),
&orch.pending,
&stale,
Arc::clone(&item),
&orch.repo(),
(80, 24),
);
orch.wait_for_idle();
// The choke point drops a stale write even when a task slipped past
// the early checks (queued while current, filling after the bump).
PreviewOrchestrator::fill(
&orch.cache,
orch.notifier(),
&stale,
(row_id.clone(), PreviewMode::WorkingTree),
"stale".to_string(),
);
assert!(
orch.cache.is_empty(),
"a superseded spawn must not re-seed the cleared cache"
);
orch.spawn_preview(
&orch.generation(),
Arc::clone(&item),
PreviewMode::WorkingTree,
(80, 24),
);
orch.wait_for_idle();
assert!(
orch.cache.contains_key(&(row_id, PreviewMode::WorkingTree)),
"the live spawn's fill lands"
);
}
/// `refresh` rebinds the compute repo, so post-refresh producers (and the
/// demand worker's per-request read) resolve `RepoCache` values — notably
/// the BranchDiff comparison base — from the rebuilt spawn's repo, not
/// session-start state.
#[test]
fn refresh_rebinds_compute_repo() {
let t = TestRepo::new();
let orch = orch_for(&t);
let t2 = TestRepo::new();
let repo2 = Repository::at(t2.path()).unwrap();
orch.refresh(repo2.clone());
assert_eq!(
orch.repo().discovery_path(),
repo2.discovery_path(),
"repo cell rebound to the rebuilt spawn's repo"
);
}
/// A request from a row a refresh superseded is refused at the channel
/// (its compute would drop at `fill` anyway); the live spawn's request
/// parks. Driven on a worker-less channel so the parked/empty slot can be
/// asserted without racing a serve.
#[test]
fn stale_generation_request_is_refused() {
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
let demand = PreviewDemand::new();
let stale = orch.generation();
orch.refresh(Repository::at(t.path()).unwrap());
demand.request(Arc::clone(&item), PreviewMode::WorkingTree, (80, 24), stale);
assert!(
demand.state.lock().unwrap().request.is_none(),
"a superseded row's request is refused"
);
demand.request(item, PreviewMode::WorkingTree, (80, 24), orch.generation());
assert!(
demand.state.lock().unwrap().request.is_some(),
"the live spawn's request parks"
);
}
/// The one stale demand that can outlive `request`'s check — parked while
/// its spawn was current, taken after a refresh — is dropped before its
/// compute, so the live spawn's first demand never queues behind it and
/// the cleared cache stays untouched.
#[test]
fn parked_request_across_refresh_is_dropped() {
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
let stale = orch.generation();
orch.refresh(Repository::at(t.path()).unwrap());
PreviewOrchestrator::serve_demand(
&orch.cache,
orch.notifier(),
&orch.pending,
&orch.repo(),
DemandRequest {
item,
mode: PreviewMode::WorkingTree,
dims: (80, 24),
spawn_gen: stale,
},
);
assert!(
orch.cache.is_empty(),
"a request parked across a refresh computes but its fill drops"
);
}
/// Rows hold the demand channel beyond the orchestrator's life (skim can
/// still call `preview()` while teardown races), so a request after
/// `Drop` closed the channel must be inert, not parked forever.
#[test]
fn request_after_orchestrator_drop_is_inert() {
let (t, item) = dirty_worktree_item();
let orch = orch_for(&t);
let demand = Arc::clone(orch.demand());
let cache = Arc::clone(&orch.cache);
let spawn_gen = orch.generation();
drop(orch);
demand.request(item, PreviewMode::WorkingTree, (80, 24), spawn_gen);
assert!(
demand.state.lock().unwrap().request.is_none(),
"a closed channel records nothing"
);
assert!(cache.is_empty(), "nothing fills after close");
}
/// A fill injects an `Event::RunPreview` exactly when the selected row is
/// awaiting that key, and nothing otherwise — the "surface a finished
/// compute, but don't thrash off-screen rows" contract. Drives the notifier
/// through a real `tokio` channel as skim's event sender so the assertion is
/// on the injected event, not the cache.
#[test]
fn fill_notifies_only_awaited_key() {
let t = TestRepo::new();
let (tx, mut rx) = tokio::sync::mpsc::channel::<Event>(8);
let render_tx = Arc::new(OnceLock::new());
render_tx.set(tx).unwrap();
let orch = PreviewOrchestrator::new(Repository::at(t.path()).unwrap(), render_tx);
let main = branch_key("main");
let feature = branch_key("feature");
// The selected row is showing main's working-tree diff (a cache miss, so
// it's awaiting that key).
orch.notifier()
.note_awaiting(&main, PreviewMode::WorkingTree);
// The awaited compute lands → skim is poked to repaint.
PreviewOrchestrator::fill(
&orch.cache,
orch.notifier(),
&orch.generation(),
(main.clone(), PreviewMode::WorkingTree),
"diff".to_string(),
);
assert!(
matches!(rx.try_recv(), Ok(Event::RunPreview)),
"the awaited fill injects a RunPreview"
);
// Fills for other rows / other tabs must not poke — no preview thrash.
PreviewOrchestrator::fill(
&orch.cache,
orch.notifier(),
&orch.generation(),
(feature, PreviewMode::WorkingTree),
"x".to_string(),
);
PreviewOrchestrator::fill(
&orch.cache,
orch.notifier(),
&orch.generation(),
(main, PreviewMode::Log),
"y".to_string(),
);
assert!(
rx.try_recv().is_err(),
"an off-screen / other-tab fill injects nothing"
);
}
#[test]
fn cache_entries_json_format() {
let t = TestRepo::new();
let orch = orch_for(&t);
orch.cache.insert(
(branch_key("branch-a"), PreviewMode::WorkingTree),
"x".to_string(),
);
orch.cache
.insert((branch_key("branch-b"), PreviewMode::Log), "xy".to_string());
// Structural assertion — future field additions shouldn't flake the test.
let entries = orch.cache_entries_json();
let entries = entries.as_array().expect("entries array");
assert_eq!(entries.len(), 2);
for e in entries {
assert!(e["row_id"].is_string());
assert!(e["mode"].is_number());
assert!(e["bytes"].is_number());
assert!(e["content"].is_string());
}
}
}