mind-cli 0.39.0

//! Data load and poll layer for the TUI.
//!
//! The only module in the TUI that acquires the global lock for reads.
//! Uses a non-blocking shared acquire for the poll tick (TUI-15, TUI-25)
//! so the UI never freezes behind a writer.
//!
//! Change detection: the source-set and manifest are compared across polls,
//! and the freshly built snapshot is compared by value against the last
//! applied one so an unchanged tick skips the rebuild (TUI-15). A source's
//! catalog is re-scanned only when its registry record changes, or for a
//! linked source on the on-screen schedule (TUI-85, TUI-87, [`SCAN_CACHE`]);
//! the item list is still
//! complete on every load, which is what lets `load_inner` size the hash memo
//! to the current catalog before any staleness check reads it.

use std::path::PathBuf;

use cached::Cached as _;

use crate::catalog;
use crate::config::Config;
use crate::error::{ItemKind, Result};
use crate::lock;
use crate::manifest::Manifest;
use crate::paths::Paths;
use crate::sanitize::strip_ansi;
use crate::source::Registry;

/// A snapshot of the TUI's data, built from registry + manifest + catalog.
///
/// Change detection is by VALUE (`PartialEq`), not by a counter: the poll tick
/// compares the freshly loaded snapshot against the last applied one and skips
/// the rebuild when they are equal (TUI-15). An earlier `generation` counter was
/// minted fresh on every load, so it always compared unequal and the gate never
/// fired -- every tick rebuilt the tree even when nothing had changed.
// spec: TUI-15
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Snapshot {
    pub installed: Vec<SnapshotInstalled>,
    pub available: Vec<SnapshotAvailable>,
    /// Unmanaged lobe items: skills/agents/rules present in a configured agent
    /// home that `mind` did not install (UNM-6).
    // spec: UNM-6
    pub unmanaged: Vec<SnapshotUnmanaged>,
    /// Names of all melded sources (for change detection in future: TUI-15).
    #[allow(dead_code)]
    pub source_names: Vec<String>,
    /// Not-yet-melded sources from the suggested registry (TUI-31).
    pub suggestions: Vec<crate::tui::preview::RegistrySuggestion>,
    /// Configured agent homes (lobes) from config.toml (TUI-23).
    // spec: TUI-23
    pub lobes: Vec<String>,
    /// Effective namespace prefix for each melded source (NS-1). The key is the
    /// source name; the value is the effective prefix (`Some(p)`) or `None` when
    /// the source has no prefix. Derived in priority order: consumer alias, then
    /// `[source].prefix` from mind.toml, then none.
    // spec: TUI-53
    pub source_namespaces: std::collections::HashMap<String, Option<String>>,
    /// Declared and enabled profiles per melded source (TUI-78, PROF-29). A
    /// source with no `[profiles]` (or an unreadable table) has no entry.
    // spec: TUI-78
    pub source_profiles: std::collections::HashMap<String, SourceProfiles>,
    /// The hook history (HOOK-163), oldest first, for each dialog's last hook
    /// result (TUI-83). Empty when there is none or it cannot be read.
    // spec: TUI-83
    pub hook_results: Vec<crate::hook_log::HookRecord>,
}

/// One source's profiles for the details dialog (TUI-78).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SourceProfiles {
    /// Declared profile names, sorted (the table's key order).
    pub declared: Vec<String>,
    /// The recorded enabled set (PROF-19); empty when untracked.
    pub enabled: Vec<String>,
}

/// One installed item in the snapshot.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapshotInstalled {
    /// Identity, NOT display: drives TUI action dispatch (`ActionKind::Forget
    /// { item_key }`, `upgrade_keys`, tree.rs node ids) and the manifest/store
    /// path lookup. The name is source-derived (a directory name, or a
    /// `[[items]] name`) and can carry ANSI/control/bidi code points, so it is
    /// NEVER rendered directly -- see [`Self::display_key`] for the sanitized
    /// counterpart (H1/TUI-75).
    pub key: String,
    /// The sanitized form of `key` (`ItemKey::display`, DSC-95): the ONLY
    /// reading of this item's key that may reach a confirm-modal description,
    /// dependents list, or any other terminal/`--json` print site (TUI-75).
    // spec: TUI-75
    pub display_key: String,
    pub name: String,
    pub source: String,
    pub kind: ItemKind,
    pub commit: String,
    pub description: Option<String>,
    /// Direct dependency keys (`kind:name`) for TUI-50 dependency subtree.
    // spec: TUI-50
    pub deps: Vec<String>,
    /// Whether `upgrade` would act on this item: its source content hash has
    /// drifted from the recorded manifest hash, or its effective name has
    /// changed (a rename, e.g. a prefix change). Mirrors the CLI-75 outdated
    /// check (commands.rs, three call sites) at the TUI snapshot boundary so
    /// the browse tree and item dialog can show the same drift a user would
    /// see from `recall`, without re-deriving the comparison at draw time.
    // spec: TUI-63
    pub stale: bool,
    /// The item's live catalog path as of the last load/poll, or `None` when
    /// it currently has no matching catalog entry (its source was unmelded,
    /// or the item was removed upstream) -- the same condition under which
    /// `stale` is false above. Carried on the snapshot itself (not a
    /// thread-local side index) so the "never staler than `last_snapshot`"
    /// property `is_actually_stale` relies on holds by construction: it is
    /// set in the same `load_inner` pass that computes every other field on
    /// this struct, from the exact same snapshot generation.
    pub path: Option<PathBuf>,
    /// The recorded manifest hash for this item as of the last load/poll,
    /// paired with `path` above for the TUI-74 authoritative recompute
    /// (`hash_path_ignoring(path, ignore) != recorded_hash`).
    pub recorded_hash: String,
    /// The item's effective ignore patterns (IGN-1) as of the last load/poll,
    /// carried alongside `path`/`recorded_hash` so the TUI-74 authoritative
    /// recompute can build the SAME ignore set the recorded hash was computed
    /// with (`CatalogItem::ignore_set`), not an empty one (H1): comparing
    /// `hash_path` (zero rules, not even the IGN-2 built-ins) against a
    /// manifest hash computed with the item's ignores applied reports
    /// permanent, unfixable drift for any item with declared ignores, and for
    /// every `path = "."` item (which always has a `.git` dir). Kept as
    /// `Vec<String>` (the raw, uncompiled patterns) rather than a compiled
    /// `IgnoreSet` so this struct's `PartialEq`/`Eq` derives stay intact.
    // spec: TUI-74 IGN-10
    pub ignore: Vec<String>,
    /// The profiles this item was installed for (PROF-20); empty for an item
    /// installed by name or before profiles existed (TUI-78).
    pub profiles: Vec<String>,
    /// Asked for by name on top of its profile reasons (PROF-20).
    pub explicit: bool,
}

/// One available (catalog) item in the snapshot.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapshotAvailable {
    /// Identity, NOT display: see the identical note on
    /// [`SnapshotInstalled::key`].
    pub key: String,
    /// The sanitized form of `key` (TUI-75); see
    /// [`SnapshotInstalled::display_key`].
    // spec: TUI-75
    pub display_key: String,
    pub name: String,
    pub source: String,
    pub kind: ItemKind,
    pub description: Option<String>,
    pub path: PathBuf,
    /// Direct dependency keys (`kind:name`) for TUI-50 dependency subtree.
    // spec: TUI-50
    pub deps: Vec<String>,
}

/// One unmanaged lobe item in the snapshot (UNM-6). Its `key` is the
/// `kind:name` form so the `forget` action resolves it like a managed ref.
// spec: UNM-6
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapshotUnmanaged {
    /// Identity, NOT display: see the identical note on
    /// [`SnapshotInstalled::key`]. Unmanaged names come straight off the
    /// filesystem (a lobe directory/file entry) with NO validation gate
    /// equivalent to DSC-96's catalog-scan rejection (H1/TUI-75) -- the one
    /// name class where a hostile value is guaranteed to reach this struct.
    pub key: String,
    /// The sanitized form of `key` (TUI-75); see
    /// [`SnapshotInstalled::display_key`].
    // spec: TUI-75
    pub display_key: String,
    pub name: String,
    pub kind: ItemKind,
    pub paths: Vec<PathBuf>,
}

/// Memo of item content hashes for the TUI's staleness check, keyed on the
/// pair (item path, cheap stat fingerprint).
///
/// The poll tick runs about once a second and computes TUI-63 staleness for
/// every installed item, which means a full content hash of every item's source
/// tree. For a markdown skill that is trivial; for a `tool` directory carrying a
/// vendored binary it is tens of megabytes re-read per second. The cheap stat
/// fingerprint (`hash::stat_fingerprint_ignoring`: `mtime`, `size`, and -- under
/// `cfg(unix)` -- `ctime` and inode number) stands in for the content: it is
/// part of the KEY, not a token stored beside the value and compared by hand,
/// so a tree that changed simply misses and re-reads. There is no validity
/// check to get wrong, and no way to serve a value whose fingerprint does not
/// match the one asked for.
///
/// The ignore set is deliberately NOT part of the key. A changed set changes
/// which entries the fingerprint walk sees, so it already moves the
/// fingerprint; and two sets that walk the identical files agree on the content
/// hash too, so they are interchangeable here (IGN-10).
///
/// Sized and pruned by [`fit_hash_memo`] on every full load rather than held at
/// a fixed capacity. Capacity is a runtime value for a reason: `load_inner`
/// hashes every installed item once per tick in a stable order, which is a
/// cyclic sequential scan, the worst case for LRU. At N items and capacity C
/// the hit rate is ~100% while N <= C and collapses to ~0% the moment N > C,
/// because each tick evicts exactly the entries the next tick reaches for
/// first. That is a cliff, not a slope, and past it the memo costs a full
/// re-read of every item tree every second: precisely what it exists to
/// prevent. Deriving C from the catalog keeps N below it by construction.
///
/// Display-side only (TUI-72): `upgrade`/`introspect`/`recall` all call
/// `CatalogItem::content_hash` directly, never this memo, so a missed
/// fingerprint change can never change what a verb ACTS on -- at most it makes
/// the TUI-63 confirm modal list fewer stale items than the no-sync apply
/// (TUI-73) then acts on, since that apply always re-hashes for real. A miss is
/// NOT bounded to "one tick": with no TTL it is served until the entry is
/// pruned or evicted. `stat_fingerprint`'s `ctime`/inode fields close the
/// realistic miss case -- a same-size, mtime-preserving replace (`cp -p`,
/// `rsync -a`, `tar -p`, `touch -r`) -- but the fingerprint is still not a
/// content hash and must never be compared against a recorded manifest hash.
static HASH_MEMO: std::sync::LazyLock<
    cached::sync_sync::RwLock<cached::LruCache<(PathBuf, String), String>>,
> = std::sync::LazyLock::new(|| cached::sync_sync::RwLock::new(new_hash_memo(HASH_MEMO_FLOOR)));

/// The capacity the memo starts at and never drops below, covering the load
/// before the first [`fit_hash_memo`] call and every install smaller than it.
const HASH_MEMO_FLOOR: usize = 1024;

/// Entries per catalog item. One holds the item's current fingerprint; the
/// spare covers items that SHARE a path: two `[[items]]` may declare the same
/// `path` with different `ignore` lists, which walk different file sets and so
/// hold different keys under one path. An in-flight edit needs no headroom of
/// its own, contrary to what this said before: at a miss the least-recently
/// used entry is the item's OWN superseded one, since every item ahead of it
/// this tick has already been touched, so the edit evicts its own dead entry
/// rather than a neighbour.
const HASH_MEMO_PER_ITEM: usize = 2;

fn new_hash_memo(capacity: usize) -> cached::LruCache<(PathBuf, String), String> {
    cached::LruCache::builder()
        .max_size(capacity.max(1))
        .build()
        .expect("a non-zero max_size is the only failure mode")
}

/// The capacity that fits `item_count` catalog items, never below the floor.
/// Counts ITEMS rather than distinct paths: items sharing a path still need an
/// entry each, so the deduped path count can under-size the memo.
fn hash_memo_capacity_for(item_count: usize) -> usize {
    (item_count * HASH_MEMO_PER_ITEM).max(HASH_MEMO_FLOOR)
}

/// Drop entries whose path left the catalog, and grow the memo if the current
/// catalog no longer fits. Called once per full load with the freshly scanned
/// item paths.
///
/// This is what keeps the LRU bound from becoming a cliff (see [`HASH_MEMO`]):
/// capacity tracks the workload instead of a constant chosen in advance, so the
/// N > C regime is not reachable by installing more items. The prune half also
/// keeps a dead path (its source unmelded, or the item removed upstream) from
/// occupying capacity that live items need, which a bare LRU would let it do
/// until it aged out on its own.
fn fit_hash_memo(live_paths: &std::collections::HashSet<PathBuf>, item_count: usize) {
    fit_memo(&mut HASH_MEMO.write(), live_paths, item_count);
}

/// The prune-and-resize logic behind [`fit_hash_memo`], split out so it can be
/// unit-tested against a local cache rather than the process-global
/// `HASH_MEMO`. Every test in this module shares that static, so a test that
/// pruned the real one would evict a concurrently running test's entries: the
/// live set it prunes to is its own, and every other test's paths are absent
/// from it.
fn fit_memo(
    memo: &mut cached::LruCache<(PathBuf, String), String>,
    live_paths: &std::collections::HashSet<PathBuf>,
    item_count: usize,
) {
    memo.retain(|(path, _), _| live_paths.contains(path));
    // Resizes in place, evicting least-recently-used entries when the new bound
    // is smaller, so an install set that shrank gives its capacity back instead
    // of holding it for the rest of the session.
    memo.set_max_size(hash_memo_capacity_for(item_count));
}

/// Test-only: seed `HASH_MEMO` with the entry `memoized_hash` would look up
/// for `path` under `ignore`, but carrying an arbitrary (possibly wrong)
/// `fake_hash`. This simulates "the memo believes this path is clean"
/// independent of whatever `path`'s real content hash is right now.
///
/// Needed because `stat_fingerprint_ignoring` folds in `ctime`/inode under
/// `cfg(unix)` (a prior commit closed the mtime-preserving blind spot), so a
/// real on-disk edit always moves the fingerprint and the memo always
/// recomputes -- there is no longer a realistic sequence of filesystem calls
/// that reproduces "memo says clean, real content differs". Poisoning the
/// memo directly is the only way to construct that condition in a test, to
/// prove the display-only `stale` flag `load_inner` computes via
/// `memoized_hash` really can lag reality (TUI-72).
///
/// Takes the SAME `ignore` the matching `memoized_hash` call will pass, and
/// builds the key the same way it does. The two must not diverge: the
/// fingerprint is half the key now, so a helper that computed it from a
/// different ignore set would seed an entry nothing ever looks up, and the
/// test would fail reporting "served the real hash" rather than naming the
/// mismatch.
///
/// A caller must assert directly against [`memoized_hash`], never through a
/// full `load`/`try_poll` with other work interleaved between the poison and
/// the read. `HASH_MEMO` is one `static` shared by the whole test binary, and
/// the dominant hazard is the PRUNE, not LRU pressure: any concurrently
/// running test that reaches `load_inner` calls [`fit_memo`], which retains
/// only ITS OWN catalog's paths and so drops every foreign entry
/// (`load_returns_empty_snapshot_on_fresh_home` prunes to an empty set and
/// clears the memo outright). The shorter the gap between poisoning and
/// reading, the smaller that window, but it cannot be closed while this drives
/// the global memo.
#[cfg(test)]
pub(crate) fn poison_memo_for_test(
    path: &std::path::Path,
    ignore: &crate::ignore::IgnoreSet,
    fake_hash: &str,
) {
    if let Ok(fp) = crate::hash::stat_fingerprint_ignoring(path, ignore) {
        HASH_MEMO
            .write()
            .cache_set((path.to_path_buf(), fp), fake_hash.to_string());
    }
}

/// The content hash of `path`, served from [`HASH_MEMO`] when
/// the tree's cheap stat fingerprint is one already seen. `None` on any hash
/// failure, which callers treat as drift (matching `content_hash().ok()`, the
/// CLI-75 rule). When the fingerprint itself cannot be computed, this falls back
/// to hashing every time and caches nothing, so an unsupported-mtime platform
/// behaves exactly as before the memo existed.
///
/// spec: IGN-10 -- both the fingerprint and the hash take the ITEM's ignore
/// set, so the memo measures the same tree the install wrote and the recorded
/// manifest hash was computed from. A set that changes (the source edited its
/// `ignore` list) also changes the fingerprint, since the newly excluded
/// entries' stats were part of it, so the memo misses and re-hashes.
fn memoized_hash(path: &std::path::Path, ignore: &crate::ignore::IgnoreSet) -> Option<String> {
    // No fingerprint (an unsupported-mtime platform): hash every time and cache
    // nothing, exactly as before the memo existed.
    let Ok(fingerprint) = crate::hash::stat_fingerprint_ignoring(path, ignore) else {
        return crate::hash::hash_path_ignoring(path, ignore).ok();
    };

    let key = (path.to_path_buf(), fingerprint);
    if let Some(hit) = HASH_MEMO.write().cache_get(&key) {
        return Some(hit.clone());
    }
    // A failure is not stored, so it is retried on the next tick rather than
    // remembered for the life of the entry.
    let hash = crate::hash::hash_path_ignoring(path, ignore).ok()?;
    HASH_MEMO.write().cache_set(key, hash.clone());
    Some(hash)
}

/// The catalog-derived part of the snapshot for one source: its scanned items,
/// each item's sanitized direct dependency keys (same index), and its
/// `available` rows. Dependency edges never leave a source (DEP-2), so this is
/// complete on its own.
struct SourceScan {
    items: Vec<catalog::CatalogItem>,
    deps: Vec<Vec<String>>,
    available: Vec<SnapshotAvailable>,
}

/// How long a poll may reuse a linked source's scan, or an installed item's
/// stale flag, when the source is not on screen (TUI-87).
pub const OFF_SCREEN_REFRESH: std::time::Duration = std::time::Duration::from_secs(10);

/// What a load must read fresh (TUI-87).
#[derive(Debug, Clone, Copy)]
pub enum Refresh<'a> {
    /// Everything: the initial load and an action's reload.
    All,
    /// A poll: the named (sanitized) sources, the ones on screen, are read
    /// fresh; any other source's live parts are reused until they are
    /// [`OFF_SCREEN_REFRESH`] old.
    Focused(&'a std::collections::HashSet<String>),
}

impl Refresh<'_> {
    /// Whether a live result for `source` (a raw registry name) last computed
    /// at `at` must be recomputed now.
    fn due(&self, source: &str, at: std::time::Instant, now: std::time::Instant) -> bool {
        match self {
            Refresh::All => true,
            Refresh::Focused(names) => {
                names.contains(strip_ansi(source).as_str())
                    || now.saturating_duration_since(at) >= OFF_SCREEN_REFRESH
            }
        }
    }
}

/// A cached [`SourceScan`] and when it was taken.
struct CachedScan {
    scan: std::sync::Arc<SourceScan>,
    at: std::time::Instant,
}

/// What an installed item's stale flag was computed from: its manifest
/// identity and recorded hash and name, and the catalog path and effective
/// name it was compared against. Any change recomputes it.
type StaleKey = (String, String, String, PathBuf, String);

/// Per-source [`SourceScan`]s kept across polls, so a tick re-scans only what
/// may have changed (TUI-15). Keyed on the source's serialized registry record,
/// which carries the recorded commit and every discovery setting: a `sync` that
/// moved the commit, a namespace change, or a re-meld changes the key and so
/// re-scans. A linked source (CLI-27) is read live from the user's working tree,
/// which can change without touching its record, so its scan is reused only
/// while it is off screen and younger than [`OFF_SCREEN_REFRESH`] (TUI-87).
///
/// `stale` holds each installed item's TUI-63 flag on the same schedule.
///
/// One slot per process, tagged with the `mind_home` it was built for, so a
/// load against a different home (tests run many in one process) starts empty
/// rather than serving another home's catalog.
struct ScanCache {
    mind_home: PathBuf,
    by_record: std::collections::HashMap<String, CachedScan>,
    stale: std::collections::HashMap<StaleKey, (bool, std::time::Instant)>,
}

static SCAN_CACHE: std::sync::Mutex<Option<ScanCache>> = std::sync::Mutex::new(None);

fn build_source_scan(items: Vec<catalog::CatalogItem>) -> SourceScan {
    let dep_index = crate::deps::DepIndex::new(&items);
    // spec: TUI-50 TUI-60 - dep keys are catalog-derived `kind:name` keys,
    // sanitized at the model boundary like every sibling field.
    let deps: Vec<Vec<String>> = (0..items.len())
        .map(|node| sanitize_dep_keys(dep_index.direct_keys(node, &read_item_text)))
        .collect();
    // De-dup vs installed happens in tree.rs.
    let available = items
        .iter()
        .zip(&deps)
        .map(|(it, deps)| SnapshotAvailable {
            // See the identical `key` note on `SnapshotInstalled`.
            key: it.key().into(),
            // spec: TUI-75
            display_key: it.display_key(),
            name: strip_ansi(&it.effective_name()),
            source: strip_ansi(&it.source),
            kind: it.kind,
            // spec: WF-51
            description: it.display_description().as_deref().map(strip_ansi),
            path: it.path.clone(),
            deps: deps.clone(),
        })
        .collect();
    SourceScan {
        items,
        deps,
        available,
    }
}

/// Scan every melded source against an explicit cache slot (tests drive one
/// that concurrently running tests do not share), reusing a cached
/// [`SourceScan`] for each clone-backed source whose registry record is
/// unchanged, and for a linked source that `refresh` does not make due. The
/// slot is left holding a cache for `paths`, with the previous stale flags.
// spec: TUI-15 TUI-85 TUI-87
fn scan_catalog_with(
    slot: &mut Option<ScanCache>,
    paths: &Paths,
    registry: &Registry,
    refresh: Refresh<'_>,
    now: std::time::Instant,
) -> Result<Vec<std::sync::Arc<SourceScan>>> {
    let (mut prev, stale) = match slot.take() {
        Some(c) if c.mind_home == paths.mind_home => (c.by_record, c.stale),
        _ => Default::default(),
    };
    let mut next = std::collections::HashMap::new();
    let mut scans = Vec::with_capacity(registry.sources.len());
    for source in &registry.sources {
        let record = serde_json::to_string(source).ok();
        let cached = record
            .as_ref()
            .and_then(|r| prev.remove(r))
            .filter(|c| !source.is_linked() || !refresh.due(&source.name, c.at, now));
        let cached = match cached {
            Some(c) => c,
            None => match catalog::scan_one(paths, source) {
                Ok(items) => CachedScan {
                    scan: std::sync::Arc::new(build_source_scan(items)),
                    at: now,
                },
                Err(e) => {
                    // Keep every other source's scan: one broken source must
                    // not make each later tick re-scan the rest.
                    next.extend(prev);
                    *slot = Some(ScanCache {
                        mind_home: paths.mind_home.clone(),
                        by_record: next,
                        stale,
                    });
                    return Err(e);
                }
            },
        };
        scans.push(cached.scan.clone());
        if let Some(r) = record {
            next.insert(r, cached);
        }
    }
    // Records no longer in the registry are dropped with `prev`.
    *slot = Some(ScanCache {
        mind_home: paths.mind_home.clone(),
        by_record: next,
        stale,
    });
    Ok(scans)
}

/// Load the initial snapshot under a blocking shared lock (called once at
/// startup). Returns an error if the lock cannot be acquired.
// spec: TUI-25
pub fn load(paths: &Paths) -> Result<Snapshot> {
    let lock = lock::open(paths)?;
    let _guard = lock.read()?;
    load_inner(paths, Refresh::All)
}

/// Try to load a refreshed snapshot under a NON-BLOCKING shared lock.
/// Returns `None` if the lock is held exclusively (e.g. a mutation is in
/// progress). Reads everything fresh; the poll thread uses
/// [`try_poll_focused`].
// spec: TUI-15 TUI-25
pub fn try_poll(paths: &Paths) -> Option<Snapshot> {
    try_poll_with(paths, Refresh::All)
}

/// [`try_poll`] for the poll tick: only the sources in `on_screen` are read
/// fresh (TUI-87).
// spec: TUI-15 TUI-25 TUI-87
pub fn try_poll_focused(
    paths: &Paths,
    on_screen: &std::collections::HashSet<String>,
) -> Option<Snapshot> {
    try_poll_with(paths, Refresh::Focused(on_screen))
}

fn try_poll_with(paths: &Paths, refresh: Refresh<'_>) -> Option<Snapshot> {
    let lock = lock::open(paths).ok()?;
    let _guard = lock.try_read()?;
    load_inner(paths, refresh).ok()
}

/// Sanitize a set of dependency keys (`kind:name`) through the same TUI-60
/// model boundary as the sibling `name`/`source`/`description` fields on
/// `SnapshotInstalled`/`SnapshotAvailable` -- L15: dep keys were the only
/// source-derived strings on those structs that skipped `strip_ansi`.
/// `catalog::scan` already rejects an unsafe item NAME outright (a control
/// character or bidi/zero-width code point never survives into a `CatalogItem`
/// in the first place), so today this is defense-in-depth rather than a live
/// path: it closes the gap the moment a label reaches a non-ratatui sink, or a
/// future dep-key source that is not name-gated the same way.
fn sanitize_dep_keys(keys: Vec<String>) -> Vec<String> {
    keys.iter().map(|k| strip_ansi(k)).collect()
}

/// Read all of a catalog item's token-expanding text files into one buffer,
/// for dependency detection. Mirrors `commands::read_item_text`: narrowed to
/// the files install actually expands tokens in
/// (`namespace::item_expands_tokens`, NS-53/NS-57/WF-25), so a `{{ns:sibling}}`
/// token in a file install never expands does not draw a dependency edge here
/// that install would never create either. Kept local (rather than shared with
/// `commands.rs`) so data.rs stays independent of that module.
fn read_item_text(item: &catalog::CatalogItem) -> String {
    let mut buf = String::new();
    for file in crate::review::item_files(item) {
        if !crate::namespace::item_expands_tokens(item, &item.path, &file) {
            continue;
        }
        if let Ok(content) = std::fs::read_to_string(&file) {
            buf.push_str(&content);
            buf.push('\n');
        }
    }
    buf
}

/// Previous and next stale flags, as [`ScanCache::stale`] holds them.
type StaleFlags<'a> = (
    &'a mut std::collections::HashMap<StaleKey, (bool, std::time::Instant)>,
    &'a mut std::collections::HashMap<StaleKey, (bool, std::time::Instant)>,
);

/// An installed item's stale flag: the previous one while `refresh` does not
/// make `source` due, else `compute()`. Either way it is carried into `next`.
// spec: TUI-87
fn tiered_stale(
    (prev, next): StaleFlags<'_>,
    key: StaleKey,
    refresh: Refresh<'_>,
    source: &str,
    now: std::time::Instant,
    compute: impl FnOnce() -> bool,
) -> bool {
    let (stale, at) = match prev.remove(&key) {
        Some((stale, at)) if !refresh.due(source, at, now) => (stale, at),
        _ => (compute(), now),
    };
    next.insert(key, (stale, at));
    stale
}

/// Load registry, manifest, and catalog without acquiring the lock (the
/// caller must already hold an appropriate guard).
fn load_inner(paths: &Paths, refresh: Refresh<'_>) -> Result<Snapshot> {
    let registry = Registry::load(paths)?;
    let manifest = Manifest::load(paths)?;
    let now = std::time::Instant::now();
    let mut slot = SCAN_CACHE.lock().unwrap_or_else(|e| e.into_inner());
    let scans = scan_catalog_with(&mut slot, paths, &registry, refresh, now)?;
    let cache = slot.as_mut().expect("scan_catalog_with fills the slot");
    // Stale flags not carried into `next_stale` (items no longer installed or
    // no longer matching their key) are dropped with `prev_stale`.
    let mut prev_stale = std::mem::take(&mut cache.stale);
    let mut next_stale = std::collections::HashMap::with_capacity(manifest.items.len());
    let catalog_items: Vec<&catalog::CatalogItem> =
        scans.iter().flat_map(|s| s.items.iter()).collect();

    // spec: TUI-72 -- size the memo to this catalog and drop entries whose path
    // has left it, before it is consulted below.
    let live_paths: std::collections::HashSet<PathBuf> =
        catalog_items.iter().map(|c| c.path.clone()).collect();
    fit_hash_memo(&live_paths, catalog_items.len());

    // Each catalog item and its dep keys by stable identity (source, kind,
    // bare name), for matching manifest entries. The first match wins, as the
    // linear search this replaces did.
    let mut by_identity: std::collections::HashMap<
        (&str, ItemKind, &str),
        (&catalog::CatalogItem, &Vec<String>),
    > = std::collections::HashMap::with_capacity(catalog_items.len());
    for scan in &scans {
        for (ci, deps) in scan.items.iter().zip(&scan.deps) {
            by_identity
                .entry((ci.source.as_str(), ci.kind, ci.name.as_str()))
                .or_insert((ci, deps));
        }
    }

    // spec: TUI-60 - source names are source-controlled and must be sanitized.
    let source_names: Vec<String> = registry
        .sources
        .iter()
        .map(|s| strip_ansi(&s.name))
        .collect();

    // Build installed list.
    // spec: TUI-50 - compute direct dep keys for each installed item so the
    // TUI can render the dependency subtree without extra I/O at display time.
    // spec: TUI-60 - all source-derived strings are sanitized through strip_ansi
    // at the model boundary to prevent terminal injection from catalog-controlled
    // content (consistent with the CLI's DSC-69 / MKT-9 call sites).
    // spec: TUI-63 - out-of-date detection mirrors the CLI's CLI-75 check:
    // hash drift (the source content changed) or a rename (effective name
    // no longer matches the recorded manifest name), computed against the
    // matching catalog item.
    let mut installed: Vec<SnapshotInstalled> = Vec::with_capacity(manifest.items.len());
    for it in manifest.items.values() {
        // Find the matching catalog item to get direct deps + drift.
        let entry = by_identity.get(&(it.source.as_str(), it.kind, it.bare_name.as_str()));
        let matched = entry.map(|(ci, _)| *ci);
        // spec: TUI-60 - dep keys were sanitized when the source was scanned
        // (`build_source_scan`).
        let deps: Vec<String> = entry.map(|(_, d)| (*d).clone()).unwrap_or_default();
        // spec: TUI-74 IGN-10 - compiled once per item per load pass (L7),
        // not inside the per-tick fast path the memo exists to keep cheap.
        // The raw (uncompiled) patterns are taken straight from `ci.ignore`
        // below for the snapshot field, so this is the only compile.
        let ignore_set = matched.and_then(|ci| ci.ignore_set().ok());
        let stale = matched.is_some_and(|ci| {
            let effective = ci.effective_name();
            let key: StaleKey = (
                it.key().into(),
                it.hash.clone(),
                it.name.clone(),
                ci.path.clone(),
                effective.clone(),
            );
            let flags = (&mut prev_stale, &mut next_stale);
            tiered_stale(flags, key, refresh, &ci.source, now, || {
                // Memoized on the cheap stat fingerprint: the poll tick would
                // otherwise re-read every installed item's content every second.
                let cur = ignore_set
                    .as_ref()
                    .and_then(|ig| memoized_hash(&ci.path, ig));
                let hash_drift = cur.as_deref().is_none_or(|h| h != it.hash);
                let rename_drift = effective != it.name;
                hash_drift || rename_drift
            })
        });
        installed.push(SnapshotInstalled {
            // `key` is identity, not display: it drives TUI action dispatch
            // (learn/forget refs), tree.rs node ids, and `manifest`/store
            // lookups, all keyed on the raw string. It is NEVER rendered
            // directly -- `display_key` below is the sanitized reading a
            // confirm-modal description or any other print site must use
            // instead (H1/TUI-75).
            key: it.key().into(),
            // spec: TUI-75
            display_key: it.display_key(),
            name: strip_ansi(&it.name),
            source: strip_ansi(&it.source),
            kind: it.kind,
            commit: it.commit.clone(),
            description: it.description.as_deref().map(strip_ansi),
            deps,
            stale,
            // spec: TUI-72 TUI-73 TUI-74 - carried on the snapshot itself
            // (M10), not a side thread-local index, so `is_actually_stale`'s
            // "never staler than `last_snapshot`" property holds by
            // construction: both are set in this same `load_inner` pass.
            path: matched.map(|ci| ci.path.clone()),
            recorded_hash: it.hash.clone(),
            // spec: TUI-74 IGN-10 - the item's effective (resolved) ignore
            // patterns, so `is_actually_stale` (app.rs) can rebuild the SAME
            // ignore set the recorded hash was computed with instead of
            // comparing against a `hash_path` result computed with none (H1).
            ignore: matched
                .map(|ci| ci.ignore.clone().unwrap_or_default())
                .unwrap_or_default(),
            // spec: TUI-78 - profile names pass PROF-2's grammar, so they
            // need no sanitizing.
            profiles: it.profiles.clone(),
            explicit: it.explicit,
        });
    }
    cache.stale = next_stale;
    drop(slot);

    // Available list: all catalog items, built per source in `build_source_scan`.
    let available: Vec<SnapshotAvailable> = scans
        .iter()
        .flat_map(|s| s.available.iter().cloned())
        .collect();

    // Unmanaged lobe items (UNM-6): kind-dir entries in a configured agent home
    // that mind did not install. A scan failure is non-fatal: the rest of the
    // TUI stays usable, the unmanaged group is simply empty.
    // spec: UNM-6
    // spec: TUI-60 - strip_ansi on name (unmanaged item names come from lobe filenames).
    let unmanaged: Vec<SnapshotUnmanaged> = crate::unmanaged::scan(paths, &manifest)
        .unwrap_or_default()
        .into_iter()
        .map(|u| SnapshotUnmanaged {
            // See the identical `key` note on `SnapshotInstalled` above.
            key: u.key().into(),
            // spec: TUI-75
            display_key: u.display_key(),
            name: strip_ansi(&u.name),
            kind: u.kind,
            paths: u.paths,
        })
        .collect();

    // Build the suggested registry (TUI-31). Failures are silently ignored
    // so a bad mind.toml in a melded source does not break the whole TUI.
    let suggestions = crate::tui::preview::suggested_registry(paths).unwrap_or_default();

    // Load configured lobes for TUI-23. Falls back to empty (default lobe used).
    // spec: TUI-23
    let lobes = Config::load(paths)
        .map(|c| c.lobes.iter().map(|e| e.path().to_string()).collect())
        .unwrap_or_default();

    // Build source namespace map (TUI-53, NS-1): effective prefix per source.
    // All catalog items from the same source share the same prefix (set in
    // catalog::scan), so the first item's prefix is the effective prefix.
    // For sources with no catalog items, fall back to the raw alias.
    // spec: TUI-53
    let source_namespaces: std::collections::HashMap<String, Option<String>> = {
        let mut m = std::collections::HashMap::new();
        for item in catalog_items.iter() {
            m.entry(item.source.clone())
                .or_insert_with(|| item.prefix.clone());
        }
        for source in &registry.sources {
            m.entry(source.name.clone())
                .or_insert_with(|| source.alias.clone().filter(|p| !p.is_empty()));
        }
        m
    };

    // Declared and enabled profiles per source (TUI-78). A table that fails
    // to load is left out rather than failing the poll, like the suggested
    // registry above; `review` and the CLI report it.
    // spec: TUI-78 PROF-29
    let source_profiles: std::collections::HashMap<String, SourceProfiles> = registry
        .sources
        .iter()
        .filter_map(|s| {
            let table = crate::commands::source_profile_table(paths, s).ok()??;
            Some((
                s.name.clone(),
                SourceProfiles {
                    declared: table.keys().cloned().collect(),
                    enabled: s.profiles.clone().unwrap_or_default(),
                },
            ))
        })
        .collect();

    Ok(Snapshot {
        installed,
        available,
        unmanaged,
        source_names,
        suggestions,
        lobes,
        source_namespaces,
        source_profiles,
        // spec: TUI-83
        hook_results: crate::hook_log::read_history(&crate::hook_log::history_file(
            &paths.mind_home,
        ))
        .unwrap_or_default(),
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::hash::hash_path;
    use crate::paths::Paths;
    use std::sync::atomic::{AtomicU32, Ordering};
    use std::time::Instant;

    #[test]
    fn an_off_screen_stale_flag_is_reused_until_the_slow_interval() {
        // spec: TUI-87
        let key: StaleKey = (
            "skill:a".into(),
            "h".into(),
            "a".into(),
            PathBuf::from("/x"),
            "a".into(),
        );
        let (mut prev, mut next) = Default::default();
        let t0 = Instant::now();
        let none = std::collections::HashSet::new();
        let off = Refresh::Focused(&none);
        let shown = std::collections::HashSet::from(["src".to_string()]);
        let on = Refresh::Focused(&shown);
        let mut run = |refresh, now, value: bool| {
            let prev_map: &mut std::collections::HashMap<_, _> = &mut prev;
            let next_map: &mut std::collections::HashMap<_, _> = &mut next;
            let got = tiered_stale(
                (prev_map, next_map),
                key.clone(),
                refresh,
                "src",
                now,
                || value,
            );
            std::mem::swap(prev_map, next_map);
            next_map.clear();
            got
        };
        assert!(!run(off, t0, false), "no previous flag: computed");
        let soon = t0 + std::time::Duration::from_secs(1);
        assert!(!run(off, soon, true), "off screen: reused");
        assert!(run(on, soon, true), "on screen: recomputed");
        let later = soon + OFF_SCREEN_REFRESH;
        assert!(run(off, soon, false), "off screen: reused again");
        assert!(
            !run(off, later, false),
            "off screen, interval passed: recomputed"
        );
        assert!(run(Refresh::All, later, true), "a full load recomputes");
    }

    static COUNTER: AtomicU32 = AtomicU32::new(0);

    fn temp_paths() -> (Paths, std::path::PathBuf) {
        let n = COUNTER.fetch_add(1, Ordering::SeqCst);
        let base = std::env::temp_dir().join(format!("mind-tui-data-{}-{n}", std::process::id()));
        let paths = Paths {
            mind_home: base.join("mind"),
            claude_home: base.join("claude"),
        };
        (paths, base)
    }

    /// Write `files` (relative path, content) into a fresh git repo under
    /// `base`, commit it, and meld it into `paths`. Returns the repo dir.
    fn meld_fixture(paths: &Paths, base: &std::path::Path, files: &[(&str, &str)]) -> PathBuf {
        meld_fixture_pinned(paths, base, files, crate::commands::PinRequest::None)
    }

    /// [`meld_fixture`] with a pin. `PinRequest::None` leaves the local source
    /// linked (CLI-27); `Freeze(None)` clones it.
    fn meld_fixture_pinned(
        paths: &Paths,
        base: &std::path::Path,
        files: &[(&str, &str)],
        pin: crate::commands::PinRequest,
    ) -> PathBuf {
        use std::process::Command;

        let src = base.join("fixture-source");
        for (rel, content) in files {
            let file = src.join(rel);
            std::fs::create_dir_all(file.parent().unwrap()).unwrap();
            std::fs::write(&file, content).unwrap();
        }
        let git = |args: &[&str]| {
            Command::new("git")
                .args(args)
                .current_dir(&src)
                .output()
                .expect("git");
        };
        git(&["-c", "init.defaultBranch=main", "init", "-q"]);
        git(&["config", "user.email", "t@t"]);
        git(&["config", "user.name", "t"]);
        git(&["add", "-A"]);
        git(&["commit", "-qm", "initial"]);

        crate::commands::meld(
            paths,
            src.to_str().unwrap(),
            None,
            vec![],
            vec![],
            false,
            pin,
            None,
            crate::hook::Accept::default(),
            None,
        )
        .expect("meld");
        src
    }

    /// A full load's scan pass ([`Refresh::All`]) against `slot`.
    fn scan_all(
        slot: &mut Option<ScanCache>,
        paths: &Paths,
        registry: &Registry,
    ) -> Result<Vec<std::sync::Arc<SourceScan>>> {
        scan_catalog_with(slot, paths, registry, Refresh::All, Instant::now())
    }

    fn skill_names(scans: &[std::sync::Arc<SourceScan>]) -> Vec<String> {
        let mut names: Vec<String> = scans
            .iter()
            .flat_map(|s| s.items.iter().map(|i| i.name.clone()))
            .collect();
        names.sort();
        names
    }

    #[test]
    fn a_cloned_source_is_rescanned_only_when_its_record_changes() {
        // spec: TUI-85 TUI-15
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        meld_fixture_pinned(
            &paths,
            &base,
            &[("skills/a/SKILL.md", "---\ndescription: a\n---\n# a\n")],
            crate::commands::PinRequest::Freeze(None),
        );
        let mut registry = Registry::load(&paths).unwrap();
        assert!(!registry.sources[0].is_linked(), "fixture must be a clone");
        let mut slot = None;
        let first = scan_all(&mut slot, &paths, &registry).unwrap();
        assert_eq!(skill_names(&first), ["a"]);

        // A skill appearing in the clone without a registry change is not
        // picked up: the cached scan is served as-is.
        let clone = registry.sources[0].clone_dir(&paths);
        std::fs::create_dir_all(clone.join("skills/b")).unwrap();
        std::fs::write(clone.join("skills/b/SKILL.md"), "# b\n").unwrap();
        let second = scan_all(&mut slot, &paths, &registry).unwrap();
        assert!(std::sync::Arc::ptr_eq(&first[0], &second[0]));
        assert_eq!(skill_names(&second), ["a"]);

        // A changed record (what a sync that moved the commit writes) re-scans.
        registry.sources[0].commit = Some("0".repeat(40));
        let third = scan_all(&mut slot, &paths, &registry).unwrap();
        assert_eq!(skill_names(&third), ["a", "b"]);

        // A different home never reuses another home's scans: it scans its own
        // (empty) sources tree, which here fails, instead of serving `third`.
        let (other, other_base) = temp_paths();
        let fourth = scan_all(&mut slot, &other, &registry);
        assert!(!fourth.is_ok_and(|s| std::sync::Arc::ptr_eq(&s[0], &third[0])));
        cleanup(&base);
        cleanup(&other_base);
    }

    #[test]
    fn a_source_that_fails_to_scan_keeps_the_others_cached() {
        // spec: TUI-85
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        meld_fixture_pinned(
            &paths,
            &base,
            &[("skills/a/SKILL.md", "---\ndescription: a\n---\n# a\n")],
            crate::commands::PinRequest::Freeze(None),
        );
        let registry = Registry::load(&paths).unwrap();
        let mut slot = None;
        let first = scan_all(&mut slot, &paths, &registry).unwrap();

        // A second, cloned source whose clone is missing fails the load.
        let mut broken = Registry::load(&paths).unwrap();
        let mut missing = broken.sources[0].clone();
        missing.name = format!("{}-missing", missing.name);
        missing.repo = format!("{}-missing", missing.repo);
        assert!(!missing.clone_dir(&paths).exists());
        broken.sources.push(missing);
        assert!(scan_all(&mut slot, &paths, &broken).is_err());

        let again = scan_all(&mut slot, &paths, &registry).unwrap();
        assert!(
            std::sync::Arc::ptr_eq(&first[0], &again[0]),
            "the healthy source's scan must survive the failed load"
        );
        cleanup(&base);
    }

    #[test]
    fn a_linked_source_is_rescanned_on_every_full_load() {
        // spec: TUI-85
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        let src = meld_fixture(
            &paths,
            &base,
            &[("skills/a/SKILL.md", "---\ndescription: a\n---\n# a\n")],
        );
        let registry = Registry::load(&paths).unwrap();
        assert!(registry.sources[0].is_linked(), "fixture must be linked");
        let mut slot = None;
        let first = scan_all(&mut slot, &paths, &registry).unwrap();
        assert_eq!(skill_names(&first), ["a"]);

        std::fs::create_dir_all(src.join("skills/b")).unwrap();
        std::fs::write(src.join("skills/b/SKILL.md"), "# b\n").unwrap();
        let second = scan_all(&mut slot, &paths, &registry).unwrap();
        assert_eq!(skill_names(&second), ["a", "b"]);
        cleanup(&base);
    }

    #[test]
    fn a_linked_source_off_screen_is_rescanned_on_the_slow_interval() {
        // spec: TUI-87
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        let src = meld_fixture(
            &paths,
            &base,
            &[("skills/a/SKILL.md", "---\ndescription: a\n---\n# a\n")],
        );
        let registry = Registry::load(&paths).unwrap();
        let name = registry.sources[0].name.clone();
        let add = |n: &str| {
            std::fs::create_dir_all(src.join("skills").join(n)).unwrap();
            std::fs::write(src.join("skills").join(n).join("SKILL.md"), "# x\n").unwrap();
        };
        let t0 = Instant::now();
        let mut slot = None;
        scan_catalog_with(&mut slot, &paths, &registry, Refresh::All, t0).unwrap();
        add("b");

        // Off screen and younger than the interval: the scan is reused.
        let none = std::collections::HashSet::new();
        let off = Refresh::Focused(&none);
        let early = t0 + OFF_SCREEN_REFRESH - std::time::Duration::from_millis(1);
        let s = scan_catalog_with(&mut slot, &paths, &registry, off, early).unwrap();
        assert_eq!(skill_names(&s), ["a"]);

        // On screen: re-scanned at once.
        let shown = std::collections::HashSet::from([name]);
        let on = Refresh::Focused(&shown);
        let s = scan_catalog_with(&mut slot, &paths, &registry, on, early).unwrap();
        assert_eq!(skill_names(&s), ["a", "b"]);

        // Off screen again: due once the interval has passed since the last
        // scan, not since the first.
        add("c");
        let s =
            scan_catalog_with(&mut slot, &paths, &registry, off, t0 + OFF_SCREEN_REFRESH).unwrap();
        assert_eq!(
            skill_names(&s),
            ["a", "b"],
            "the on-screen scan restarted the clock"
        );
        let late = early + OFF_SCREEN_REFRESH;
        let s = scan_catalog_with(&mut slot, &paths, &registry, off, late).unwrap();
        assert_eq!(skill_names(&s), ["a", "b", "c"]);
        cleanup(&base);
    }

    fn cleanup(base: &std::path::Path) {
        let _ = std::fs::remove_dir_all(base);
    }

    #[test]
    fn load_returns_empty_snapshot_on_fresh_home() {
        // spec: TUI-12 TUI-13 TUI-15
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        let snap = load(&paths).expect("load should succeed on fresh home");
        assert!(snap.installed.is_empty(), "fresh home: no installed items");
        assert!(snap.available.is_empty(), "fresh home: no available items");
        assert!(snap.unmanaged.is_empty(), "fresh home: no unmanaged items");
        assert!(snap.source_names.is_empty(), "fresh home: no sources");
        cleanup(&base);
    }

    #[test]
    fn snapshot_carries_declared_and_enabled_profiles() {
        // spec: TUI-78 PROF-29 - each source declaring `[profiles]` gets its
        // declared names and its recorded enabled set; a source without
        // profiles gets no entry.
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        meld_fixture(
            &paths,
            &base,
            &[
                ("skills/a/SKILL.md", "---\ndescription: a\n---\n# a\n"),
                ("skills/b/SKILL.md", "---\ndescription: b\n---\n# b\n"),
                (
                    "mind.toml",
                    "[profiles]\nfull = [\"skill:b\"]\ndefault = [\"skill:a\"]\n",
                ),
            ],
        );
        let name = Registry::load(&paths).unwrap().sources[0].name.clone();
        let snap = load(&paths).unwrap();
        assert_eq!(
            snap.source_profiles.get(&name),
            Some(&SourceProfiles {
                declared: vec!["default".to_string(), "full".to_string()],
                enabled: vec![],
            })
        );

        let mut reg = Registry::load(&paths).unwrap();
        reg.sources[0].profiles = Some(vec!["full".to_string()]);
        reg.save(&paths).unwrap();
        let snap = load(&paths).unwrap();
        assert_eq!(
            snap.source_profiles[&name].enabled,
            vec!["full".to_string()]
        );
        cleanup(&base);
    }

    #[test]
    fn snapshot_has_no_profiles_entry_for_a_plain_source() {
        // spec: TUI-78 - no `[profiles]`, no entry.
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        meld_fixture(
            &paths,
            &base,
            &[("skills/a/SKILL.md", "---\ndescription: a\n---\n# a\n")],
        );
        assert!(load(&paths).unwrap().source_profiles.is_empty());
        cleanup(&base);
    }

    #[test]
    fn try_poll_succeeds_when_no_exclusive_lock_held() {
        // spec: TUI-15 TUI-25
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        let snap = try_poll(&paths);
        assert!(
            snap.is_some(),
            "try_poll should succeed when no exclusive lock is held"
        );
        cleanup(&base);
    }

    #[test]
    fn try_poll_returns_none_when_exclusive_lock_held() {
        // spec: TUI-25 (non-blocking poll skips while mutation holds exclusive lock)
        use fd_lock::RwLock;
        use std::fs::OpenOptions;

        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();

        // Hold an exclusive lock on the lock file directly.
        let lock_path = paths.lock_file();
        std::fs::write(&lock_path, b"").unwrap();
        let f = OpenOptions::new()
            .read(true)
            .write(true)
            .open(&lock_path)
            .unwrap();
        let mut raw_lock = RwLock::new(f);
        let _excl = raw_lock.write().expect("acquire exclusive lock");

        // try_poll must return None (non-blocking, skips under exclusive lock).
        let snap = try_poll(&paths);
        assert!(
            snap.is_none(),
            "try_poll must return None when exclusive lock is held"
        );
        drop(_excl);
        cleanup(&base);
    }

    // spec: TUI-72
    #[test]
    fn memoized_hash_matches_hash_path_and_refreshes_on_change() {
        // The memo must be transparent: the value it returns is always the value
        // `hash_path` would return, both on the cold path and on a memo hit, and
        // it must pick up a content change rather than serving a stale hash.
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        let item = base.join("item");
        crate::paths::mkdir_p(&item).unwrap();
        std::fs::write(item.join("SKILL.md"), b"v1").unwrap();

        // Cold: computes and caches.
        let first = memoized_hash(&item, &crate::ignore::IgnoreSet::default()).expect("hash");
        assert_eq!(
            first,
            hash_path(&item).unwrap(),
            "cold value must be correct"
        );
        // Warm: served from the memo, same value.
        let second = memoized_hash(&item, &crate::ignore::IgnoreSet::default()).expect("hash");
        assert_eq!(second, first, "a memo hit must return the same hash");

        // Content change (also a size change): the fingerprint moves, so the
        // memo must recompute rather than serve the cached value.
        std::fs::write(item.join("SKILL.md"), b"v2 is longer than v1").unwrap();
        let after = memoized_hash(&item, &crate::ignore::IgnoreSet::default()).expect("hash");
        assert_ne!(after, first, "a content change must invalidate the memo");
        assert_eq!(
            after,
            hash_path(&item).unwrap(),
            "the refreshed value must equal a direct hash_path"
        );

        cleanup(&base);
    }

    // spec: TUI-72
    #[test]
    fn memoized_hash_detects_same_size_content_change() {
        // M3(d): the test above only edits content in a way that also changes
        // SIZE. A same-size rewrite (mtime advances, size does not) exercises
        // the other half of the fingerprint and must still invalidate the memo.
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        let item = base.join("item-same-size");
        crate::paths::mkdir_p(&item).unwrap();
        std::fs::write(item.join("SKILL.md"), b"aaaaa").unwrap();

        let first = memoized_hash(&item, &crate::ignore::IgnoreSet::default()).expect("hash");
        std::fs::write(item.join("SKILL.md"), b"bbbbb").unwrap();
        let after = memoized_hash(&item, &crate::ignore::IgnoreSet::default()).expect("hash");
        assert_ne!(
            first, after,
            "a same-size content rewrite must invalidate the memo"
        );
        assert_eq!(
            after,
            hash_path(&item).unwrap(),
            "the refreshed memo value must equal a direct hash_path"
        );

        cleanup(&base);
    }

    // spec: TUI-72
    #[test]
    fn fitting_the_memo_grows_capacity_past_a_large_catalog() {
        // The property that matters is that capacity TRACKS the catalog, not
        // that it equals any particular number. `load_inner` hashes every
        // installed item once per tick in a stable order, so the memo sees a
        // cyclic sequential scan: at N items over capacity C the LRU evicts
        // exactly what the next tick wants first and the hit rate goes to ~0,
        // re-reading every tree every second. A fixed capacity makes that
        // regime reachable by installing more items; deriving it from the live
        // set does not.
        let mut memo = new_hash_memo(HASH_MEMO_FLOOR);
        let many: std::collections::HashSet<PathBuf> = (0..5000)
            .map(|i| PathBuf::from(format!("/fake/item-{i}")))
            .collect();
        fit_memo(&mut memo, &many, many.len());

        let capacity = memo.capacity();
        assert!(
            capacity >= many.len(),
            "capacity must cover the catalog ({} items), got {capacity}: below \
             it the memo does not degrade, it stops working",
            many.len()
        );

        // Shrinking back gives the capacity up rather than holding a peak for
        // the rest of the session, and still never drops below the floor.
        fit_memo(&mut memo, &std::collections::HashSet::new(), 0);
        let shrunk = memo.capacity();
        assert_eq!(
            shrunk, HASH_MEMO_FLOOR,
            "an empty catalog must return the memo to the floor, not keep the \
             capacity a since-uninstalled set once needed"
        );
        assert!(
            shrunk < capacity,
            "the shrink must actually reduce the bound ({capacity} -> {shrunk})"
        );
    }

    // spec: TUI-72
    #[test]
    fn fitting_the_memo_drops_entries_whose_path_left_the_catalog() {
        // A dead path (its source unmelded, or the item removed upstream)
        // otherwise sits in the memo occupying capacity that live items need,
        // until it happens to age out on its own.
        let live = PathBuf::from("/fake/still-in-catalog");
        let dead = PathBuf::from("/fake/dropped-from-catalog");
        let mut memo = new_hash_memo(HASH_MEMO_FLOOR);
        memo.cache_set((live.clone(), "fp".into()), "hash-live".into());
        memo.cache_set((dead.clone(), "fp".into()), "hash-dead".into());

        let mut live_paths = std::collections::HashSet::new();
        live_paths.insert(live.clone());
        fit_memo(&mut memo, &live_paths, live_paths.len());

        assert!(
            memo.cache_get(&(live, "fp".to_string())).is_some(),
            "a path still in the catalog must survive the prune"
        );
        assert!(
            memo.cache_get(&(dead, "fp".to_string())).is_none(),
            "a path no longer in the catalog must be dropped, not retained"
        );
    }

    // spec: TUI-72
    #[test]
    fn fitting_the_memo_prunes_before_it_resizes() {
        // The order is load-bearing and both statements are one line apart, so
        // it is easy to swap them. Resizing FIRST applies the smaller bound
        // while the dead entries are still present, and LRU evicts by recency
        // rather than by liveness, so live entries get pushed out to make room
        // for entries the prune was about to delete anyway. Pruning first means
        // the resize only ever sees entries worth keeping.
        let live: Vec<PathBuf> = (0..40)
            .map(|i| PathBuf::from(format!("/live/{i}")))
            .collect();
        let mut memo = new_hash_memo(HASH_MEMO_FLOOR);

        // Dead entries are the MOST recently used, so a resize-first
        // implementation keeps them and evicts the live ones.
        for path in &live {
            memo.cache_set((path.clone(), "fp".into()), "live".into());
        }
        for i in 0..200 {
            memo.cache_set(
                (PathBuf::from(format!("/dead/{i}")), "fp".into()),
                "dead".into(),
            );
        }

        let live_paths: std::collections::HashSet<PathBuf> = live.iter().cloned().collect();
        // A bound far below the pre-prune entry count, so the ordering decides
        // which entries survive.
        fit_memo(&mut memo, &live_paths, 1);

        let survivors = live
            .iter()
            .filter(|p| memo.cache_get(&((*p).clone(), "fp".to_string())).is_some())
            .count();
        assert_eq!(
            survivors,
            live.len(),
            "every live entry must survive: pruning the dead ones first leaves \
             the resize nothing worth evicting"
        );
    }

    // spec: TUI-72
    #[cfg(unix)]
    #[test]
    fn a_failed_hash_is_not_cached_and_is_retried() {
        // The failure has to happen with the FINGERPRINT intact, or the test
        // proves nothing: a path that does not exist fails at
        // `stat_fingerprint_ignoring` and takes `memoized_hash`'s
        // no-fingerprint early return, never reaching the memo at all. An
        // unreadable file is the reachable case, because `collect_stats` only
        // stats each entry while `collect_files` reads it, so mode 000 fails
        // the hash and not the fingerprint.
        use std::os::unix::fs::PermissionsExt as _;

        let (_paths, base) = temp_paths();
        let item = base.join("unreadable-item");
        crate::paths::mkdir_p(&item).unwrap();
        let file = item.join("SKILL.md");
        std::fs::write(&file, b"unreadable").unwrap();
        std::fs::set_permissions(&file, std::fs::Permissions::from_mode(0o000)).unwrap();
        let ignore = crate::ignore::IgnoreSet::default();

        // Skip rather than assert a false pass: root reads a mode-000 file
        // regardless, so this cannot fail the hash when the suite runs as root.
        if crate::hash::hash_path_ignoring(&item, &ignore).is_ok() {
            std::fs::set_permissions(&file, std::fs::Permissions::from_mode(0o644)).unwrap();
            cleanup(&base);
            return;
        }

        let key_before = crate::hash::stat_fingerprint_ignoring(&item, &ignore)
            .expect("the fingerprint must still succeed: only the read fails");
        assert!(
            memoized_hash(&item, &ignore).is_none(),
            "an unreadable file must fail the hash"
        );
        assert!(
            HASH_MEMO
                .write()
                .cache_get(&(item.clone(), key_before))
                .is_none(),
            "a failed hash must leave NO entry under the key it failed at: a \
             stored failure would be served instead of being retried"
        );

        // Make it readable again and re-ask. Restoring the mode moves ctime, so
        // re-derive the key rather than assuming it held.
        std::fs::set_permissions(&file, std::fs::Permissions::from_mode(0o644)).unwrap();
        assert!(
            memoized_hash(&item, &ignore).is_some(),
            "the next poll must recompute rather than serve a remembered failure"
        );

        cleanup(&base);
    }

    // spec: TUI-72
    #[test]
    fn poisoned_memo_serves_the_seeded_hash_instead_of_the_real_one() {
        // This asserts `poison_memo_for_test`'s effect DIRECTLY against
        // `memoized_hash`, with no intervening `load`/`try_poll` call between
        // the poison and the read. `HASH_MEMO` is one `static` shared by every
        // concurrently running test in this binary, so a sibling inserting
        // enough entries could evict this one under LRU pressure. Keeping the
        // gap between poisoning and reading to exactly these two calls (no
        // catalog scan, no meld/learn I/O) minimizes that window; a full
        // `load()` round trip (the pattern this replaces, formerly in
        // `app.rs`) held it open far longer.
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        let item = base.join("poison-target");
        crate::paths::mkdir_p(&item).unwrap();
        std::fs::write(item.join("SKILL.md"), b"v1").unwrap();

        // A real edit, so the poisoned value and the real value are provably
        // different (not just "the memo returned SOMETHING").
        std::fs::write(item.join("SKILL.md"), b"v2 is longer than v1").unwrap();
        let real_hash = hash_path(&item).expect("real hash");

        let fake_hash = "0000000000000000000000000000000000000000000000000000000000000000";
        poison_memo_for_test(&item, &crate::ignore::IgnoreSet::default(), fake_hash);
        let served = memoized_hash(&item, &crate::ignore::IgnoreSet::default())
            .expect("memoized_hash after poisoning");

        assert_eq!(
            served, fake_hash,
            "a poisoned memo must serve the seeded fake hash, not recompute"
        );
        assert_ne!(
            served, real_hash,
            "the seeded fake hash must differ from the item's real current hash \
             -- otherwise this test cannot distinguish 'served from memo' from \
             'recomputed and happened to match'"
        );

        cleanup(&base);
    }

    #[test]
    fn two_loads_with_no_change_produce_equal_snapshots() {
        // spec: TUI-15 - change detection is by VALUE, so two loads over
        // unchanged state must compare equal; otherwise the poll tick's
        // `apply_snapshot_if_changed` gate can never fire and every tick
        // rebuilds the tree. (The previous `generation` counter was minted
        // fresh per load, which is exactly the bug this pins against.)
        //
        // M-test5: a fresh, empty MIND_HOME makes every snapshot vector empty,
        // so the comparison would pass trivially even if `installed`/
        // `available` ordering were nondeterministic (a future switch away
        // from the current BTreeMap/sorted-scan ordering would silently
        // reinstate the "every tick rebuilds" bug with no failing test). Seed
        // a melded source (with an installed AND an uninstalled item, so both
        // `installed` and `available` are non-empty) before comparing.
        use std::process::Command;

        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        crate::config::Config {
            lobes: vec![crate::config::LobeEntry::bare(
                paths.claude_home.to_str().unwrap(),
            )],
            ..Default::default()
        }
        .save(&paths)
        .unwrap();

        let src = base.join("determinism-source");
        std::fs::create_dir_all(src.join("skills/review")).unwrap();
        std::fs::write(
            src.join("skills/review/SKILL.md"),
            "---\ndescription: review skill\n---\n# review\n",
        )
        .unwrap();
        std::fs::create_dir_all(src.join("skills/extra")).unwrap();
        std::fs::write(
            src.join("skills/extra/SKILL.md"),
            "---\ndescription: extra skill\n---\n# extra\n",
        )
        .unwrap();
        let git = |args: &[&str]| {
            Command::new("git")
                .args(args)
                .current_dir(&src)
                .output()
                .expect("git");
        };
        git(&["-c", "init.defaultBranch=main", "init", "-q"]);
        git(&["config", "user.email", "t@t"]);
        git(&["config", "user.name", "t"]);
        git(&["add", "-A"]);
        git(&["commit", "-qm", "initial"]);

        crate::commands::meld(
            &paths,
            src.to_str().unwrap(),
            None,
            vec![],
            vec![],
            false,
            crate::commands::PinRequest::None,
            None,
            crate::hook::Accept::default(),
            None,
        )
        .expect("meld");
        crate::commands::learn(
            &paths,
            "skill:review",
            false,
            crate::commands::InstallFlow {
                yes: true,
                clobber: crate::commands::Clobber::Force,
                accept: crate::hook::Accept::ALL,
            },
        )
        .expect("learn");

        let snap1 = load(&paths).unwrap();
        let snap2 = load(&paths).unwrap();
        assert!(
            !snap1.installed.is_empty(),
            "fixture must have an installed item for this test to be meaningful"
        );
        assert!(
            !snap1.available.is_empty(),
            "fixture must have an available item for this test to be meaningful"
        );
        assert_eq!(
            snap1, snap2,
            "two loads over unchanged state (melded source + installed item) must be \
             equal so the poll gate can skip the rebuild"
        );
        cleanup(&base);
    }

    /// ANSI escapes and bidi-override code points in source-derived strings
    /// must be stripped before they enter the TUI snapshot model (TUI-60).
    ///
    /// Builds a manifest.json with ANSI color escapes in name/source and a
    /// bidi-override (U+202E) in description, loads the snapshot, and asserts
    /// every model field is clean. The bidi character is injected via format!
    /// to avoid triggering the text_direction_codepoint_in_literal lint.
    #[test]
    fn snapshot_installed_strips_ansi_from_source_derived_strings() {
        // spec: TUI-60
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();

        // U+202E RIGHT-TO-LEFT OVERRIDE injected at runtime to avoid lint.
        let bidi = '\u{202E}';
        let manifest_json = format!(
            concat!(
                "{{\n",
                "  \"items\": {{\n",
                "    \"skill:\\u001b[31mevil\\u001b[0m\": {{\n",
                "      \"kind\": \"skill\",\n",
                "      \"name\": \"\\u001b[31mevil\\u001b[0m\",\n",
                "      \"bare_name\": \"evil\",\n",
                "      \"source\": \"\\u001b[32msrc\\u001b[0m\",\n",
                "      \"commit\": \"abc1234\",\n",
                "      \"hash\": \"deadbeef\",\n",
                "      \"store\": \"store/skill/evil\",\n",
                "      \"links\": [],\n",
                "      \"description\": \"\\u001b[1mbold\\u001b[0m with {}bidi\"\n",
                "    }}\n",
                "  }}\n",
                "}}"
            ),
            bidi
        );
        std::fs::write(paths.manifest_file(), manifest_json).unwrap();

        let snap = load(&paths).expect("load should succeed");

        assert_eq!(snap.installed.len(), 1, "one installed item");
        let item = &snap.installed[0];

        assert_eq!(
            item.name, "evil",
            "ANSI escapes must be stripped from name; got: {:?}",
            item.name
        );
        assert_eq!(
            item.source, "src",
            "ANSI escapes must be stripped from source; got: {:?}",
            item.source
        );
        let desc = item.description.as_deref().unwrap_or("");
        assert!(
            !desc.contains('\x1b'),
            "ANSI escapes must be stripped from description; got: {:?}",
            desc
        );
        assert!(
            !desc.contains('\u{202E}'),
            "bidi-override must be stripped from description; got: {:?}",
            desc
        );
        assert_eq!(item.kind, ItemKind::Skill, "kind field must be preserved");

        cleanup(&base);
    }

    // spec: TUI-60
    #[test]
    fn sanitize_dep_keys_strips_ansi_and_bidi() {
        // L15: dep keys were the only source-derived strings on
        // SnapshotInstalled/SnapshotAvailable that skipped strip_ansi, unlike
        // the sibling name/source/description fields on the same structs.
        // `catalog::scan` already rejects an unsafe item NAME outright, so a
        // full end-to-end reproduction through a real catalog scan can no
        // longer smuggle an escape into a dep key; test the mapping function
        // itself (what `load_inner` actually calls) directly instead.
        let bidi = '\u{202E}';
        let raw = vec![
            // Not `format!`: there is nothing to interpolate here, and clippy's
            // `useless_format` (a hard error under `-D warnings`) rejects it.
            // The sibling below keeps `format!` because it interpolates `bidi`.
            "skill:re\x1b[31mview".to_string(),
            format!("agent:d{bidi}ev"),
            "rule:clean".to_string(),
        ];
        let sanitized = sanitize_dep_keys(raw);
        assert_eq!(
            sanitized,
            vec![
                "skill:review".to_string(),
                "agent:dev".to_string(),
                "rule:clean".to_string(),
            ]
        );
        assert!(
            sanitized
                .iter()
                .all(|s| !s.contains('\x1b') && !s.contains(bidi)),
            "no dep key may retain a raw ANSI escape or bidi override: {sanitized:?}"
        );
    }

    /// M2/TUI-63: `SnapshotInstalled.stale` mirrors the CLI's CLI-75 outdated
    /// check. A local-path source is read live from its working tree (no
    /// separate clone step), so editing the item file in place changes its
    /// content hash while the recorded commit stays put -- exactly the CLI-75
    /// scenario (`recall_marks_item_outdated_after_in_place_content_edit`).
    #[test]
    fn snapshot_installed_marks_stale_after_in_place_content_edit() {
        // spec: TUI-63
        use std::process::Command;

        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        crate::config::Config {
            lobes: vec![crate::config::LobeEntry::bare(
                paths.claude_home.to_str().unwrap(),
            )],
            ..Default::default()
        }
        .save(&paths)
        .unwrap();

        let src = base.join("stale-source");
        std::fs::create_dir_all(src.join("skills/review")).unwrap();
        std::fs::write(
            src.join("skills/review/SKILL.md"),
            "---\ndescription: review skill\n---\n# review\noriginal content\n",
        )
        .unwrap();
        let git = |args: &[&str]| {
            Command::new("git")
                .args(args)
                .current_dir(&src)
                .output()
                .expect("git");
        };
        git(&["-c", "init.defaultBranch=main", "init", "-q"]);
        git(&["config", "user.email", "t@t"]);
        git(&["config", "user.name", "t"]);
        git(&["add", "-A"]);
        git(&["commit", "-qm", "initial"]);

        crate::commands::meld(
            &paths,
            src.to_str().unwrap(),
            None,
            vec![],
            vec![],
            false,
            crate::commands::PinRequest::None,
            None,
            crate::hook::Accept::default(),
            None,
        )
        .expect("meld");
        crate::commands::learn(
            &paths,
            "skill:review",
            false,
            crate::commands::InstallFlow {
                yes: true,
                clobber: crate::commands::Clobber::Force,
                accept: crate::hook::Accept::ALL,
            },
        )
        .expect("learn");

        let snap = load(&paths).expect("load should succeed");
        assert_eq!(snap.installed.len(), 1, "one installed item");
        assert!(
            !snap.installed[0].stale,
            "a freshly installed item must not be marked stale"
        );

        // Edit the item source file in place without committing (mirrors the
        // CLI-75 test): content hash changes, commit does not.
        std::fs::write(
            src.join("skills/review/SKILL.md"),
            "---\ndescription: review skill\n---\n# review\nmodified content\n",
        )
        .unwrap();

        let snap2 = load(&paths).expect("load should succeed after edit");
        assert_eq!(snap2.installed.len(), 1, "still one installed item");
        assert!(
            snap2.installed[0].stale,
            "an in-place content edit must mark the item stale (TUI-63)"
        );

        cleanup(&base);
    }

    /// `load_inner`'s `available` list must read a workflow's description
    /// through `CatalogItem::display_description` (WF-51: `<description> -
    /// <whenToUse>`), not the bare `description` field. This regresses
    /// silently if the `available` row built in `load_inner` from
    /// `display_description()` is ever swapped back for `it.description`,
    /// since both are `Option<String>` and the code still compiles either
    /// way. The TUI keeps the joined human form (WF-51); `--json` emits the
    /// pair separately (WF-62).
    #[test]
    fn available_workflow_description_is_composed_with_when_to_use() {
        // spec: WF-51
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();

        meld_fixture(
            &paths,
            &base,
            &[(
                "workflows/review.js",
                "export const meta = {\n  name: 'review-changes',\n  \
                 description: 'Review changed files',\n  whenToUse: 'before a PR',\n}\n",
            )],
        );

        let snap = load(&paths).expect("load should succeed");
        let wf = snap
            .available
            .iter()
            .find(|a| a.kind == ItemKind::Workflow)
            .expect("the melded workflow item must appear in `available`");
        assert_eq!(
            wf.description.as_deref(),
            Some("Review changed files - before a PR"),
            "an available workflow's description must be the composed \
             \"description - whenToUse\" pair (display_description, WF-51), \
             not the bare `meta.description` alone: {:?}",
            wf.description
        );

        cleanup(&base);
    }

    /// The WF-51 split is by DATA SOURCE, not by surface, and both halves of it
    /// are visible in one snapshot: the `available` row is catalog-derived and
    /// so carries the composed `<description> - <whenToUse>` pair, while the
    /// `installed` row for that same workflow is manifest-derived
    /// (`install.rs` records `item.description`, never `when_to_use`) and so
    /// carries the bare description. Documented on
    /// `CatalogItem::display_description`, but nothing pinned it: the
    /// `installed` row is built from the manifest's `description` where the
    /// `available` row is built in `load_inner` from `display_description()`,
    /// and "fixing" the inconsistency in either direction compiles clean.
    /// The TUI keeps the joined human form (WF-51) while `--json` emits the
    /// pair separately (WF-62). Recording
    /// `whenToUse` in the manifest is a deliberate deferral, so this test is
    /// the one that should fail and be rewritten when that changes.
    #[test]
    fn an_installed_workflow_row_is_bare_where_the_available_row_composes() {
        // spec: WF-51
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();
        crate::config::Config {
            lobes: vec![crate::config::LobeEntry::bare(
                paths.claude_home.to_str().unwrap(),
            )],
            ..Default::default()
        }
        .save(&paths)
        .unwrap();

        meld_fixture(
            &paths,
            &base,
            &[(
                "workflows/review.js",
                "export const meta = {\n  name: 'review',\n  \
                 description: 'Review changed files',\n  whenToUse: 'before a PR',\n}\n",
            )],
        );
        crate::commands::learn(
            &paths,
            "workflow:review",
            false,
            crate::commands::InstallFlow {
                yes: true,
                clobber: crate::commands::Clobber::Force,
                accept: crate::hook::Accept::ALL,
            },
        )
        .expect("learn");

        let snap = load(&paths).expect("load should succeed");
        let installed = snap
            .installed
            .iter()
            .find(|i| i.kind == ItemKind::Workflow)
            .expect("the learned workflow must appear in `installed`");
        assert_eq!(
            installed.description.as_deref(),
            Some("Review changed files"),
            "an INSTALLED workflow row is manifest-derived, and the manifest \
             never records `whenToUse` (WF-51), so its description must be the \
             bare one: {:?}",
            installed.description
        );
        let available = snap
            .available
            .iter()
            .find(|a| a.kind == ItemKind::Workflow)
            .expect("the same workflow must still appear in `available`");
        assert_eq!(
            available.description.as_deref(),
            Some("Review changed files - before a PR"),
            "the AVAILABLE row for the same workflow is catalog-derived, so it \
             must still compose the pair even once the item is installed: {:?}",
            available.description
        );

        cleanup(&base);
    }

    /// A workflow whose `meta` gives a `whenToUse` and no `description` is
    /// malformed by the harness's own rules (WF-30 reports it), but the TUI
    /// still shows what it has: `display_description`'s `(None, Some(w))` arm
    /// returns the `whenToUse` alone rather than `None`. That arm had no test
    /// at any layer -- only the `(Some, Some)` and `(None, None)` pairs did --
    /// so collapsing it to `None` (an easy "simplify the match" edit) would
    /// have silently blanked the row and left search with nothing to match on.
    #[test]
    fn an_available_workflow_with_only_when_to_use_shows_it_as_the_description() {
        // spec: WF-51
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();

        meld_fixture(
            &paths,
            &base,
            &[(
                "workflows/review.js",
                "export const meta = {\n  name: 'review',\n  whenToUse: 'before a PR',\n}\n",
            )],
        );

        let snap = load(&paths).expect("load should succeed");
        let wf = snap
            .available
            .iter()
            .find(|a| a.kind == ItemKind::Workflow)
            .expect("the melded workflow item must appear in `available`");
        assert_eq!(
            wf.description.as_deref(),
            Some("before a PR"),
            "a workflow with a `whenToUse` and no `description` must show the \
             `whenToUse` alone, not nothing and not a dangling \" - \" \
             separator: {:?}",
            wf.description
        );

        cleanup(&base);
    }

    /// `read_item_text` must mirror `commands::read_item_text`'s item-aware
    /// gate (`namespace::item_expands_tokens`, NS-53/NS-57/WF-25): a
    /// `{{ns:sibling}}` token sitting in a non-markdown, non-`expand:`-listed
    /// bundled file draws no TUI-50 dependency edge, since install never
    /// expands it there either. A sibling skill whose SKILL.md carries the
    /// same token IS an edge, so the negative case is not just an always-empty
    /// dep list.
    // spec: TUI-50
    #[test]
    fn a_token_in_an_unlisted_bundled_file_draws_no_tui_dependency_edge() {
        let (paths, base) = temp_paths();
        crate::paths::mkdir_p(&paths.mind_home).unwrap();

        meld_fixture(
            &paths,
            &base,
            &[
                (
                    "skills/review/SKILL.md",
                    "---\ndescription: review skill\n---\n# review\nsee {{self}}\n",
                ),
                ("skills/review/resources/pr.py", "# {{ns:helper}}\n"),
                (
                    "skills/linked/SKILL.md",
                    "---\ndescription: linked skill, references {{ns:helper}} in prose\n---\n# linked\n",
                ),
                (
                    "skills/helper/SKILL.md",
                    "---\ndescription: helper skill\n---\n# helper\n",
                ),
            ],
        );

        let snap = load(&paths).expect("load should succeed");
        let review = snap
            .available
            .iter()
            .find(|a| a.kind == ItemKind::Skill && a.name == "review")
            .expect("the review skill must appear in `available`");
        assert!(
            !review.deps.iter().any(|d| d.contains("helper")),
            "a {{{{ns:helper}}}} token in a non-markdown, non-expand-listed \
             bundled file must not draw a dependency edge (install never \
             expands it there either): {:?}",
            review.deps
        );

        let linked = snap
            .available
            .iter()
            .find(|a| a.kind == ItemKind::Skill && a.name == "linked")
            .expect("the linked skill must appear in `available`");
        assert!(
            linked.deps.iter().any(|d| d.contains("helper")),
            "a {{{{ns:helper}}}} token in SKILL.md itself must still draw a \
             dependency edge, proving the negative case above is a real gate \
             and not an always-empty dep list: {:?}",
            linked.deps
        );

        cleanup(&base);
    }
}