@cruxy/cli 1.3.0 → 1.5.0

package/dist/onboarding/detect.js

@@ -1,36 +1,122 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { ONBOARDING_FILE_NAME } from "../constants.js";
 import { globalDir, resolveApiKey } from "../config/index.js";
+import { ONBOARDING_VERSION, OnboardingStateSchema, } from "./types.js";
 /**
  * First-run detection + onboarding-state persistence (U.6). "First run" is
  * deliberately derived from observable facts (no key + no completion marker)
  * rather than a flag, and is **TTY-gated** so a non-interactive run never
  * branches into an interactive flow.
  */
-const ONBOARDING_VERSION = 1;
 /** `~/.cruxy/onboarding.json` */
 export function onboardingStatePath() {
     return join(globalDir(), ONBOARDING_FILE_NAME);
 }
-/** Read persisted onboarding state, or `null` if absent/unreadable. */
+/**
+ * Read persisted onboarding state, or `null` if absent, unreadable, or not the
+ * shape this file is supposed to hold.
+ *
+ * VALIDATED, not cast. `as OnboardingState` accepted any object at all, so a
+ * truncated write or a hand-edit could hand the flow a `completedAt` that was a
+ * number — and the completion marker is the one fact that decides whether a
+ * user is walked through setup again or silently isn't.
+ *
+ * An invalid file reads as ABSENT rather than throwing, which is the same
+ * treatment corrupt JSON already got: the worst outcome of re-onboarding is one
+ * extra prompt, and the worst outcome of a hard error is a CLI that won't start
+ * because of a file that only exists to say "you've done this before".
+ */
 export function readOnboardingState(file = onboardingStatePath()) {
     if (!existsSync(file))
         return null;
+    let parsed;
     try {
-        const parsed = JSON.parse(readFileSync(file, "utf8"));
-        if (parsed && typeof parsed === "object")
-            return parsed;
+        parsed = JSON.parse(readFileSync(file, "utf8"));
     }
     catch {
         // A corrupt marker is treated as absent — onboarding can rewrite it.
+        return null;
     }
-    return null;
+    const result = OnboardingStateSchema.safeParse(parsed);
+    return result.success ? migrateState(result.data) : null;
+}
+/**
+ * The version branch the file has been writing a number for since U.6 and
+ * nothing has ever read.
+ *
+ * OLDER than this build: bring it forward. There is exactly one version today,
+ * so this is a re-stamp and nothing else — the point is that the next bump has
+ * one obvious place to add its step, instead of discovering at that moment that
+ * every reader assumed v1.
+ *
+ * NEWER than this build: return it untouched and keep trusting `completedAt`.
+ * Both alternatives are worse. Discarding it re-runs onboarding for someone who
+ * has plainly finished it, every time they use the older binary — running two
+ * cruxy versions against one home directory is ordinary, and being re-prompted
+ * for a key you already saved is not a reasonable punishment for it. Rewriting
+ * it down to our shape would destroy state we don't understand. `completedAt`
+ * is the marker in every version that has one; reading it across a version we
+ * don't know is a smaller assumption than either.
+ */
+function migrateState(state) {
+    if (state.version >= ONBOARDING_VERSION)
+        return state;
+    return { ...state, version: ONBOARDING_VERSION };
 }
-/** Persist onboarding state (creates `~/.cruxy` if needed). */
+/**
+ * Persist onboarding state (creates `~/.cruxy` if needed), owner-only.
+ *
+ * MERGED over what is on disk, not written over it. The schema passes unknown
+ * keys through, so a field a newer cruxy wrote survives a run of an older one
+ * — tolerating it on read and then flattening it on the next write would lose
+ * the data anyway, just one write later.
+ *
+ * The version is the MAX of the two for the same reason `migrateState` doesn't
+ * discard a future file: this build preserved the newer keys, so stamping our
+ * own lower number over them would tell the newer cruxy that its migration
+ * hasn't run when its data is in fact all still there.
+ */
 export function writeOnboardingState(state, file = onboardingStatePath()) {
+    const existing = readOnboardingState(file);
+    const merged = {
+        ...existing,
+        ...state,
+        version: Math.max(existing?.version ?? 0, state.version),
+    };
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, JSON.stringify(state, null, 2) + "\n", "utf8");
+    writeFileSync(file, JSON.stringify(merged, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    restrictToOwner(file);
+}
+/**
+ * Make the marker owner-only. It was the one store under `~/.cruxy` still at
+ * `0644` — usage, memory trust, MCP trust and hook trust are all `0600` — and
+ * while it holds no secret, it does record that this machine's user has a cruxy
+ * key configured and when they set it up. That is nobody else's business on a
+ * shared box, and "every file cruxy writes to your home directory is yours
+ * alone" is a rule worth being able to state without an exception.
+ *
+ * The `mode` on the write above only applies when the file is CREATED, so it
+ * does nothing for the `0644` files already out there; this fixes those on the
+ * next write. Best-effort and non-fatal, deliberately: unlike the credential
+ * store — which refuses to persist a secret it cannot secure — refusing to
+ * write this one would mean re-running onboarding forever on a filesystem
+ * without modes. Windows is skipped because POSIX modes are meaningless there
+ * (see `config/owner-only.ts`), and an `icacls` edit is more than a marker
+ * warrants.
+ */
+function restrictToOwner(file) {
+    if (process.platform === "win32")
+        return;
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // A filesystem that can't do modes still gets a working marker.
+    }
 }
 /** A fresh state object. */
 export function newOnboardingState() {

package/dist/onboarding/types.js

@@ -1,6 +1,34 @@
+import { z } from "zod";
 /**
  * Types for the first-run onboarding flow (U.6). The flow is built from injected
  * dependencies (validation, persistence, the first-win runner) so every step is
  * unit-testable with scripted IO and no real network or filesystem.
  */
-export {};
+/**
+ * Bump when the on-disk onboarding state shape changes. The number is only
+ * worth writing if something READS it — see `migrateState` in `detect.ts`,
+ * which is where the branch it enables lives.
+ */
+export const ONBOARDING_VERSION = 1;
+/**
+ * The persisted state (`~/.cruxy/onboarding.json`), as a schema rather than a
+ * cast. It was read with `as OnboardingState` — a cast validates nothing, so
+ * `{"completedAt": 42}` or a JSON array parsed clean and the completion marker
+ * became whatever the file happened to contain.
+ *
+ * `.passthrough()`, for the reason `usage/types.ts` sets out at length: a read
+ * that can't validate is a read that discards, and a store hostile to its own
+ * future silently drops what a newer cruxy wrote the moment an older one runs
+ * against the same home directory. Passthrough both TOLERATES an unknown key
+ * and PRESERVES it, so `writeOnboardingState`'s merge hands it back intact.
+ */
+export const OnboardingStateSchema = z
+    .object({
+    /** Shape version — see {@link ONBOARDING_VERSION}. */
+    version: z.number().int().nonnegative(),
+    /** ISO timestamp; **its presence is the completion marker**. */
+    completedAt: z.string().min(1).optional(),
+    /** Whether a key has been successfully configured at least once. */
+    keyConfigured: z.boolean().optional(),
+})
+    .passthrough();

package/dist/render/diff.js

@@ -99,7 +99,13 @@ export function previewStats(preview) {
     }
     return [];
 }
-/** `+12/-3`, `~+1/-1`, `+8` — omitting a side the preview cannot count. */
+/**
+ * `+12/-3`, `~+1/-1`, `+8` — omitting a side the preview cannot count.
+ *
+ * Takes only the three fields it reads rather than a whole {@link DiffFileStat},
+ * so P7's git-status changes render through this same formatter instead of a
+ * second one that would eventually disagree with it about what `null` means.
+ */
 export function formatStat(stat, c) {
     const parts = [];
     if (stat.added !== null && stat.added > 0)

package/dist/render/status-view.js

@@ -1,9 +1,55 @@
+import { capacityLevel, formatCapacity, } from "../utils/disk.js";
 import { fit } from "./layout.js";
 import { formatTokens } from "./state.js";
 /** `key  value`, aligned on a fixed gutter so the column is scannable. */
 function row(key, value, t) {
     return `  ${t.muted(key.padEnd(11))} ${value}`;
 }
+/**
+ * Collapse locations that report identical figures into one row, naming all of
+ * them.
+ *
+ * A project under `~` and `~/.cruxy` are usually the same filesystem, and two
+ * rows saying `54% free · 251 GiB of 465 GiB` twice is noise dressed as detail.
+ * Grouping is on the RENDERED numbers rather than on mount identity because
+ * `statfs` gives no filesystem id to compare — and grouping on the numbers is
+ * the honest test anyway: if two locations report the same total and the same
+ * free bytes, either they are one filesystem or they are two the reader has no
+ * way to tell apart, and in both cases one row is the whole of what's known.
+ */
+function groupLocations(locations) {
+    const groups = new Map();
+    for (const loc of locations) {
+        const key = `${loc.capacity.totalBytes}:${loc.capacity.freeBytes}`;
+        const existing = groups.get(key);
+        if (existing)
+            existing.labels.push(loc.label);
+        else
+            groups.set(key, { labels: [loc.label], capacity: loc.capacity });
+    }
+    return [...groups.values()];
+}
+/**
+ * The disk rows: `disk  cli, ~/.cruxy  54% free · 251 GiB of 465 GiB`.
+ *
+ * Coloured by {@link capacityLevel}, which judges absolute bytes — so a nearly
+ * full 4 TB disk with plenty left in it is not dressed up as an emergency, and
+ * a small VM disk with 800 MB left is, whatever percentage that happens to be.
+ * Only the first row carries the key; the rest align under it, because a `disk`
+ * label repeated down the column reads as several different facts.
+ */
+function diskLines(locations, t) {
+    return groupLocations(locations).map((group, i) => {
+        const text = formatCapacity(group.capacity);
+        const level = capacityLevel(group.capacity);
+        const value = level === "critical"
+            ? t.danger(text)
+            : level === "low"
+                ? t.warning(text)
+                : t.muted(text);
+        return row(i === 0 ? "disk" : "", `${group.labels.join(", ")}  ${value}`, t);
+    });
+}
 /** The full `/status` block as lines to print. */
 export function sessionStatusLines(status, t, width = Infinity) {
     const lines = [t.heading("status")];
@@ -33,6 +79,12 @@ export function sessionStatusLines(status, t, width = Infinity) {
     lines.push(row("checkpoints", status.checkpoints
         ? t.muted("on — `cruxy rollback` can undo a run's file changes")
         : t.warning("off — file changes are not restorable"), t));
+    // Next to checkpoints, the feature that turns a turn into a shadow copy of
+    // the tree: the two rows answer one question between them — will this
+    // session's writes land.
+    if (status.disk && status.disk.length > 0) {
+        lines.push(...diskLines(status.disk, t));
+    }
     if (status.jobs) {
         const { total, running, needingApproval } = status.jobs;
         const detail = total === 0
@@ -50,12 +102,12 @@ export function sessionStatusLines(status, t, width = Infinity) {
     lines.push(t.strong(status.roots.length === 1 ? "root" : "roots"));
     for (const r of status.roots) {
         const mark = r.primary ? t.accent(t.glyph.pointer) : " ";
-        const git = r.branch === undefined
-            ? t.muted("not a git repo")
-            : `${t.strong(r.branch)} ${r.changed === undefined
-                ? ""
-                : r.changed > 0
-                    ? t.warning(`${r.changed} changed`)
+        const git = r.git === undefined
+            ? t.muted(`checking${t.glyph.ellipsis}`)
+            : r.git === null
+                ? t.muted("not a git repo")
+                : `${t.strong(r.git.branch)} ${r.git.changed > 0
+                    ? t.warning(`${r.git.changed} changed`)
                     : t.success("clean")}`;
         lines.push(`${mark} ${r.name.padEnd(12)} ${git}`);
         lines.push(`  ${t.muted(r.path)}`);

package/dist/theme/tokens.js

@@ -22,6 +22,8 @@ export const UNICODE_GLYPHS = {
     caretDown: "↓",
     cached: "↻",
     cursorBar: "▏",
+    barFilled: "█",
+    barEmpty: "░",
     bullet: "•",
     sep: "·",
     ellipsis: "…",
@@ -45,6 +47,8 @@ export const ASCII_GLYPHS = {
     caretDown: "v",
     cached: "",
     cursorBar: "|",
+    barFilled: "#",
+    barEmpty: ".",
     bullet: "*",
     sep: "-",
     ellipsis: "...",
@@ -72,6 +76,9 @@ export const SCREEN_READER_GLYPHS = {
     caretDown: "down",
     cached: "",
     cursorBar: "",
+    // A bar announces as nothing; the percentage beside it says everything.
+    barFilled: "",
+    barEmpty: "",
     bullet: "-",
     sep: "-",
     ellipsis: "...",

package/dist/tui/app.js

@@ -2,6 +2,7 @@ import { DEFAULT_MODE, MODE_LABELS, modeAutoApproves, } from "../agent/index.js"
 import { completeLine } from "../components/autocomplete.js";
 import { SHARED_COMMANDS, SHARED_HELP, announceMode, dispatchCommand, } from "../cli/session-commands.js";
 import { selectList } from "../components/select.js";
+import { viewLabel, viewOrder } from "./views.js";
 import { canOverlay, createKeyLease, createOverlayIO, } from "./overlay.js";
 import { openPalette } from "./palette.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
@@ -41,6 +42,7 @@ export const TUI_COMMANDS = [
     ...SHARED_COMMANDS,
     "/close",
     "/open",
+    "/view",
 ].sort();
 const HELP = [
     "commands:",
@@ -48,9 +50,12 @@ const HELP = [
     "  /close <panel>   hide a panel (sidebar | context | model | git | tools)",
     "                   or a whole column (rail = all four rail panels)",
     "  /open <panel>    show a hidden panel",
+    "  /view [name]     show a main-pane view, or list them",
     "  Tab              complete a slash command",
     "  Ctrl+K           open the command palette",
+    "  Ctrl+B           focus the sidebar nav (arrows switch view, Esc leaves)",
     "  Shift+Tab        cycle mode (manual · auto-approve · plan · full-auto)",
+    "  PgUp / PgDn      scroll the pane; Esc returns to the live view",
     "  Ctrl+D           leave cruxy",
 ];
 /**
@@ -98,6 +103,43 @@ function panelArg(input, command) {
     const match = CLOSABLE_PANELS.find((p) => p === arg);
     return match ? { label: PANEL_LABELS[match], panels: [match] } : null;
 }
+/**
+ * Keys the focused sidebar nav claims (P7 track 2). Returns whether it took
+ * the key — anything it declines falls through to the input line untouched.
+ *
+ * The set is deliberately small. Up/down move the selection and Enter is not
+ * needed to commit it: selecting a view IS the action, and a two-step
+ * move-then-confirm would make the arrows do nothing visible on their own.
+ * Esc and Ctrl+B both hand the keyboard back, so the way out is whichever of
+ * the two the user reaches for first.
+ *
+ * A PRINTABLE CHARACTER RETURNS FOCUS AND IS NOT SWALLOWED. Someone who starts
+ * typing has stopped navigating, and losing the first letter of a prompt to a
+ * focus mode they forgot they were in is the failure that makes people stop
+ * using the binding.
+ */
+function handleNavKey(key, renderer) {
+    switch (key.kind) {
+        case "up":
+            renderer.cycleView(-1);
+            return true;
+        case "down":
+            renderer.cycleView(1);
+            return true;
+        case "escape":
+        case "ctrl-b":
+        case "enter":
+            renderer.focusSidebar(false);
+            return true;
+        case "char":
+            // Claim the focus change only; the character itself falls through to the
+            // editor on this same keypress.
+            renderer.focusSidebar(false);
+            return false;
+        default:
+            return false;
+    }
+}
 /**
  * Read one line from the TUI's input row. Takes raw stdin for the duration and
  * always releases it. Resolves `null` on Ctrl+D / EOF.
@@ -110,11 +152,27 @@ async function readLine(keys, renderer, hooks) {
     try {
         for (;;) {
             const key = await keys.read();
+            // FOCUS IS A ROUTING DECISION, resolved before the editor sees anything
+            // (P7 track 2). While the sidebar holds the keyboard the arrows move the
+            // view selection instead of the cursor — but only the keys that mean
+            // something there are claimed, so scrolling, the palette and the mode ring
+            // keep working exactly as they do at the input line. A view is persistent
+            // and NON-EXCLUSIVE; this is not a modal, and nothing here blocks.
+            if (renderer.sidebarHasFocus() && handleNavKey(key, renderer)) {
+                paint();
+                continue;
+            }
             switch (key.kind) {
                 case "enter": {
                     const text = editor.text;
                     editor.text = "";
                     editor.cursor = 0;
+                    // Submitting returns to the live view (P7 track 1). Scrollback holds
+                    // its position against output arriving on its own, which is the point
+                    // — but the user asking for that output is not "on its own", and
+                    // answering into a pane they cannot see is the one case where holding
+                    // still is wrong.
+                    renderer.scrollToLive();
                     paint();
                     return text;
                 }
@@ -205,9 +263,37 @@ async function readLine(keys, renderer, hooks) {
                     hooks.cycleMode();
                     paint();
                     break;
+                case "page-up":
+                case "page-down":
+                    // Scroll the conversation (P7 track 1). Like Shift+Tab, this leaves
+                    // the line being typed completely alone: reading back over what was
+                    // said is the most ordinary thing to do WHILE composing a reply, and
+                    // a scroll that cost the draft would be unusable for exactly that.
+                    //
+                    // No `paint()`: the input row has not changed, and the renderer
+                    // schedules its own repaint for the rows that did.
+                    renderer.scrollPage(key.kind === "page-up" ? 1 : -1);
+                    break;
+                case "escape":
+                    // Esc leaves the scrolled view — a mode needs a visible exit, and the
+                    // notice names this key. It stays inert at the live tail rather than
+                    // being claimed unconditionally, so the binding remains free for
+                    // whatever a later track wants Esc to mean when nothing is scrolled.
+                    renderer.scrollToLive();
+                    break;
+                case "ctrl-b":
+                    // Take the keyboard to the sidebar nav (P7 track 2). Refused when the
+                    // sidebar is closed or dropped for width, and SAID rather than
+                    // silently ignored: focus the user cannot see would make the arrows
+                    // change meaning with nothing on screen to account for it.
+                    if (!renderer.focusSidebar(true)) {
+                        renderer.println(renderer.theme.muted("(no sidebar to focus — /open sidebar, or widen the terminal)"));
+                    }
+                    paint();
+                    break;
                 default:
-                    // escape / arrows up-down / ctrl-k: no binding yet, deliberately
-                    // inert rather than leaking a control char into the buffer.
+                    // arrows: no binding yet, deliberately inert rather than leaking a
+                    // control char into the buffer.
                     break;
             }
         }
@@ -255,6 +341,10 @@ async function dispatch(input, session, renderer, out, slashCommands, checkpoint
         handlePanel(trimmed, "/open", true, renderer);
         return null;
     }
+    if (trimmed === "/view" || trimmed.startsWith("/view ")) {
+        handleView(trimmed, renderer);
+        return null;
+    }
     // Everything else is the SHARED implementation (P5 track 5). P1 forked this
     // loop out of `repl.ts` and left every one of these behind — including
     // `/plan`, which was then the only way to reach plan mode at all.
@@ -281,6 +371,39 @@ async function dispatch(input, session, renderer, out, slashCommands, checkpoint
     }
     return null;
 }
+/**
+ * `/view [name]` — select a main-pane view, or list what there is (P7 track 2).
+ *
+ * Exists so switching views never depends on the sidebar. The nav is the
+ * discoverable path, but it can be closed or dropped for width, and a UI whose
+ * only route to a surface can vanish is one that strands people. This is also
+ * the scriptable path, which is what makes the register testable end to end.
+ */
+function handleView(input, renderer) {
+    const t = renderer.theme;
+    const sources = renderer.viewSources();
+    const arg = input.slice("/view".length).trim().toLowerCase();
+    const ids = viewOrder(sources);
+    if (arg === "") {
+        renderer.println(t.muted("views:"));
+        for (const id of ids) {
+            const mark = id === renderer.view() ? t.glyph.pointer : " ";
+            renderer.println(t.muted(`  ${mark} ${viewLabel(id, sources)}`));
+        }
+        return;
+    }
+    // Matched on the id AND the label, because the sidebar shows the label and
+    // that is what a user will type back. They are the same string for every
+    // view so far; keeping both accepted means they can diverge without the
+    // command quietly becoming wrong.
+    const target = ids.find((id) => id === arg || viewLabel(id, sources).toLowerCase() === arg);
+    if (target === undefined || !renderer.setView(target)) {
+        renderer.println(t.muted(`unknown view: ${arg}`));
+        renderer.println(t.muted(`try: ${ids.map((id) => viewLabel(id, sources)).join(" | ")}`));
+        return;
+    }
+    renderer.println(t.muted(`showing ${viewLabel(target, sources)}`));
+}
 /** `/close <panel>` and `/open <panel>` share everything but the target state. */
 function handlePanel(input, command, open, renderer) {
     const t = renderer.theme;

package/dist/tui/disk-status.js

@@ -0,0 +1,47 @@
+import { readDiskCapacity } from "../utils/disk.js";
+export class WorkspaceDiskCache {
+    paths;
+    probe;
+    values = new Map();
+    /** The refresh in flight, so concurrent triggers share one pass. */
+    inFlight = null;
+    constructor(paths, probe = readDiskCapacity) {
+        // Deduplicated: the same path twice would be the same syscall twice for the
+        // same answer. Two DIFFERENT paths on one filesystem are NOT collapsed here
+        // — that is a question about the numbers, and it is answered where they are
+        // rendered (see `status-view.ts`), not by guessing at mount identity.
+        this.paths = [...new Set(paths)];
+        this.probe = probe;
+    }
+    /**
+     * The last known capacity for one path — a map read, safe from the paint
+     * path. `undefined` means not probed yet, probed and unreadable, or a path
+     * this cache was never given; every one of those renders as nothing, so they
+     * do not need telling apart the way the git tri-state does.
+     */
+    current(path) {
+        return this.values.get(path);
+    }
+    /** Re-probe every path, concurrently, and resolve when all have settled. */
+    async refresh() {
+        if (this.inFlight)
+            return this.inFlight;
+        this.inFlight = this.run();
+        try {
+            await this.inFlight;
+        }
+        finally {
+            this.inFlight = null;
+        }
+    }
+    async run() {
+        await Promise.all(this.paths.map(async (path) => {
+            const value = await this.probe(path);
+            // A failed probe keeps the last good reading rather than blanking the
+            // row. A transient failure is not evidence that the disk changed, and a
+            // figure that flickers in and out is read as a bug in the tool.
+            if (value)
+                this.values.set(path, value);
+        }));
+    }
+}

package/dist/tui/git-status.js

@@ -1,4 +1,4 @@
-import { getGitInfoAsync } from "../utils/git.js";
+import { getGitInfoAsync, getGitTreeAsync, } from "../utils/git.js";
 export class GitStatusCache {
     cwd;
     probe;
@@ -61,3 +61,48 @@ export class GitStatusCache {
         }
     }
 }
+/**
+ * The same discipline across every declared root (P7 track 3).
+ *
+ * The rail names ONE branch because it has one line to do it in; the Overview
+ * view reports every root, because writes fan across all of them when
+ * checkpoints are on and a primary-only answer would under-report what a turn
+ * touched. That is more subprocesses, not a different rule — so this is a fan
+ * over {@link GitStatusCache} rather than a second implementation of it, and
+ * `current` stays the pure field read the paint path is allowed to call.
+ *
+ * Probes run CONCURRENTLY. They are independent processes against independent
+ * working trees, and serialising them would make a four-root workspace four
+ * times slower to settle for no gain.
+ */
+export class WorkspaceGitCache {
+    caches = new Map();
+    /**
+     * Probes with {@link getGitTreeAsync} by default, not the rail's cheaper
+     * {@link getGitInfoAsync} (P7 track 4): its consumers are the Overview and
+     * Git views, and the Git view needs the per-file list. The rail keeps the two
+     * -subprocess probe, because one line of branch-and-count has no use for a
+     * third.
+     */
+    constructor(paths, probe = getGitTreeAsync) {
+        for (const p of paths)
+            this.caches.set(p, new GitStatusCache(p, probe));
+    }
+    /**
+     * Last known state for one root — a field read, safe from the paint path.
+     * An unknown path reads as unprobed rather than throwing: the workspace can
+     * gain a root (`/add-root`) between this cache being built and a paint.
+     */
+    current(absPath) {
+        return this.caches.get(absPath)?.current();
+    }
+    /** Mark every root as possibly changed. Cheap and idempotent. */
+    invalidate() {
+        for (const c of this.caches.values())
+            c.invalidate();
+    }
+    /** Re-probe every stale root, in parallel, and resolve when all have settled. */
+    async refresh() {
+        await Promise.all([...this.caches.values()].map((c) => c.refresh()));
+    }
+}