dsh-session-list-cache
> Retired on 2026-10-05. Do not install it. A controlled benchmark found no measurable gain.
> A private dsh with a copy of 775 real stored sessions was polled like an open page (one
> session/list every 5 seconds), and each phase started dsh fresh with the cache on, off, then on
> again. Median CPU use of one core:
>
> | dsh | cache on | cache off | cache on again |
> |---|---|---|---|
> | 0.1.7-rc.2 | 6.1% | 6.3% | 7.3% |
> | 0.2.0-rc.2 | 6.0% | 5.9% | 6.1% |
> | 0.2.1-alpha.1 | 6.5% | 5.4% | 6.9% |
>
> The "15.2% to 8.1%" figure below came from the busy live dsh it was written on, with other work
> and other plugins running; it did not reproduce in isolation, so it should not be relied on.
> The text below is kept as it was published.
A small DeepSeek Harness (dsh) web plugin
that stops an open dsh web page from costing a steady slice of a CPU core.
> A community plugin from SolidiFact. Not an official DeepSeek product.
The problem
While a dsh web page is open, it refreshes the session list every 5 seconds. Each refresh
rebuilds the list row of every session you have ever kept, from its stored record, and
re-validates every stored value. Nothing about those sessions has changed, but the work is
done again anyway, and it grows with every session you keep.
Measured on one install with 763 stored sessions (dsh 0.1.7-rc.2, Apple M4):
| Processor use with one dsh page open and nothing running | |
|---|---|
| Without this plugin | 15.2% of one core |
| With this plugin | 8.1% of one core |
Each figure is the dsh web process's CPU time over two minutes, taken the same way both
times, with the same pages connected. The rest of the remaining cost is dsh reading the
session headers from disk, which this plugin does not change.
What it does
A stored ("cold") session's row is built from two things: its header and its record in
dsh's projection cache. dsh never edits a stored record in place; every write stores new
objects. So when the header is unchanged and the record's contents are the very same stored
objects as last time, the row cannot have changed, and the row built last time is served
again.
Three safeguards:
- No row is kept longer than a minute. Part of a row is computed from the running dsh,
not the stored record (image limits, and which plugin provides each tool). Right after
dsh starts, plugins are still settling, and rows built then can differ from later ones.
Rebuilding each row at least once a minute bounds that, and still skips 11 of every 12
rebuilds. - It checks itself. One reused row in every 100 is rebuilt anyway and compared. A
difference is counted, the fresh row is served, and the first three are logged. Every 100
list requests it logs one summary line. The first one on the test install:
[session-list-cache] 100 list requests, 76500 rows: 92% reused, 6108 built; 9034 spot-checked, 84 differed; 765 rows kept
(more spot-checks than usual, because every row was checked for a minute while testing;
all 84 differences came from the first minute after startup, while plugins were loading,
and none from the minute-long check of every row afterwards). - It fails safe. It hooks an internal dsh class. If a dsh upgrade moves what it needs,
it logs one warning and leaves dsh untouched. A record it cannot read is never cached.
Sessions that are attached (open and live) are never cached.
It works with or without @michengai/dsh-archive-manager,
which wraps the same projection cache.
Install
Tested with dsh 0.1.7-rc.2. Use the profile you run; these examples use web.
dsh plugin --profile web add @solidifact/dsh-session-list-cache
Restart dsh web. Its log should show
[session-list-cache] unchanged cold sessions reuse their session-list row.
To remove it:
dsh plugin --profile web remove @solidifact/dsh-session-list-cache
Without npm: copy index.mjs into the profile folder as session-list-cache.mjs
(for example ~/.dsh/profiles/web/) and add it to that profile's cordis.patch.yml:
- insert:
- id: session-list-cache
name: './session-list-cache.mjs'
Tuning
createCache() takes checkEvery (default 100), reportEvery (100 list requests) and
maxAgeMs (60000). The defaults are what the numbers above were measured with.
Tests
node --test
The tests include the cases that broke earlier versions during development: a table that
returns a fresh wrapper object on every read, and a row whose live parts change while its
stored record does not.
License
Copyright 2026 SolidiFact. Licensed under the Apache License, Version 2.0; see LICENSE.
