Persistent result cache is CLI-only: the VS Code Caching panel offers a setting that does nothing in the editor

Summary

[tool.basilisk] cache = true turns on the persistent result cache for basilisk check / basilisk analyze only. The language server never reads or writes it, so toggling Project → Caching → "Reuse results between runs" in the VS Code configuration editor has no effect on anything the editor does.

The setting is presented in the editor, in a panel headed Caching, immediately above a read-only panel describing the in-session layer. A user who checks that box reasonably expects the editor to reuse results across sessions. It does not — a cold LSP start re-checks every file, every time.

The split is deliberate and documented today (configuration.md → "What cache does not control"), but documenting a surprising behaviour is not the same as it being the right behaviour. Opening a workspace is exactly the moment a cross-process cache pays off: the process is new, the files are unchanged, and every input the cache keys on is byte-identical to the last run.

Reproduction

# pyproject.toml
[tool.basilisk]
include = ["src"]
extraPaths = ["src"]
cache = true

1. Open the project in VS Code with the Basilisk extension.
2. Open Basilisk Configuration → Project → Caching. "Reuse results between runs" is checked, and "Cache folder" shows <project>/.basilisk/cache/check.
3. Edit files, let diagnostics settle, restart the window — repeat as much as you like.
4. ls .basilisk → the directory is never created.

Then, in the same project:

$ basilisk check --cache-stats
cache: 0 hit / 3 miss
$ basilisk check --cache-stats
cache: 3 hit / 0 miss
$ find .basilisk -type f
.basilisk/cache/check/a5df30c808f089c7.json
.basilisk/cache/check/3e326e829277a4e2.json
.basilisk/cache/check/23211204936349f5.json

The cache itself is healthy. Only the CLI populates it.

Evidence

cache_check is referenced solely within basilisk-cli:

$ grep -rn 'cache_check\|CacheOptions\|cache_directory\|CacheOverride' crates/basilisk-lsp/src/ \
    | grep -v configuration_editor
# (no matches)

The LSP's only relationship with these keys is the configuration editor, which displays them. CacheOptions is constructed in crates/basilisk-cli/src/main.rs:343 and crates/basilisk-cli/src/adopt.rs:199, and nowhere else.

Proposal

Have the language server honour the persistent cache on cold start: replay a file's diagnostics from disk when every cache key matches, and store fresh results on a miss. The existing key already covers what matters — file content, transitive read-set, effective config, resolution environment, typeshed id, and Basilisk version — so correctness does not need new machinery, only a caller.

Worth deciding explicitly as part of this:

• Write policy. Should the LSP write entries, or only read ones the CLI produced? Writing on every keystroke-triggered re-check would be wasteful; writing on initial workspace scan and on save is likely the useful shape.
• Interaction with Salsa. The persistent layer should serve the cold start; Salsa continues to own the in-session incremental path. They are complementary, not alternatives.
• The documented caveat still applies. Installing into a virtualenv without a uv.lock change is undetected, which is why the cache is opt-in. That reasoning is unchanged by this request.

Related: the panel copy is inaccurate regardless

vscode-extension/src/configuration-editor-script-cache.ts:33 currently reads:

Writes cache to pyproject.toml. A cached result is replayed only when the file, everything it imports, the configuration, the typeshed source, and the Basilisk version are all unchanged — otherwise the file is checked in full.

The cache is not written to pyproject.toml — the setting is; entries go to .basilisk/cache/check/. As written it contradicts the "Cache folder" field rendered directly beneath it. The sibling string at line 48 ('Set by cache-dir in pyproject.toml.') is worded correctly and is a good model.

If this issue is resolved as proposed, that string needs rewriting anyway. If it is instead resolved as "working as intended", the string still needs to say that the setting applies to CLI runs rather than to editing — which is the information whose absence produced this report.

Environment

• Basilisk built from main @ 47b71ee4
• macOS (darwin 25.5.0), VS Code extension from the same tree

Start by tracing the LSP cache-related code under crates/basilisk-lsp/src and compare it with CacheOptions construction in crates/basilisk-cli/src/main.rs:343 and adopt.rs:199. Review vscode-extension/src/configuration-editor-script-cache.ts:33 and the configuration documentation. Done means the LSP uses matching persistent cache entries on cold start, stores results according to an agreed policy, and the panel text accurately describes the behavior.