dsh-loci 2.0.3 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from 1.0.0.
 
+## [2.2.0] — 2026-11-15
+
+Four reviewers of an independent blind review named the same risk: `engines.dsh`
+admits the whole `>=0.2.2-rc.1 <0.3.0-0` range, but the only version ever booted was
+`0.2.2-rc.1`. A range is a promise nobody tested.
+
+### Added
+
+- **`scripts/compat-probe.mjs`** — reads the *installed* Host out of its `app.asar`
+  and asserts that every API this plugin touches still exists in the expected shape:
+  the section contract (`interpolate: false`, `order`), the `tools`, `commands` and
+  `connection` services with their registration calls, and the `turn/end` event.
+  Run against the installed **0.2.2-rc.3**: **5/5 passed**. It is not a boot test,
+  and the docs now say exactly which question it answers and which it does not.
+
+- **The store records the Host that opened it.** `DSH_INSTALL_DIR` is read at
+  activation, the version lands in `meta.host_version`, `stats` exposes it, the panel
+  shows it, and `loci doctor` prints
+  `[ok] host: last opened by DeepSeek Harness 0.2.2-rc.3`. Every user install now
+  produces the evidence the next compatibility table needs, instead of leaving the
+  answer to a range in a manifest.
+
+- CI gained a conditional probe step: it runs where a Host is installed and prints a
+  skip notice otherwise (the Host is not published to npm, so a stock runner has
+  nothing to read).
+
+### Changed
+
+- `dshReleases` gained a `0.2.2-rc.3` row with status `api-surface-verified` — a
+  deliberate third status between "verified" (booted) and "untested", so a range
+  entry can never again imply more than was actually checked.
+
+## [2.1.0] — 2026-11-15
+
+Two findings from an independent blind review, where seven reviewers compared this
+plugin against the rest of the field. Two of them caught the same false claim; the
+other had the sharpest product objection, and both are addressed here.
+
+### Fixed
+
+- **The "no network" claim was false.** `README` and the threat-model row both said
+  "no network unless `vectorMode` is http", while `updateCheck` defaulted to `true`
+  and the panel's update route fetched the registry. Rather than reword the claim,
+  the default is now **false**, so the sentence is true: turning the check on is one
+  click, and a disabled check reads "Update check off" instead of looking like a
+  dead button. `test/unit/network-claims.test.mjs` also greps the source, so a new
+  `fetch` outside the two opt-in modules fails CI.
+
+### Added
+
+- **A pending-review line in the injected section.** Verified-only injection has an
+  invisible failure mode: a fact written at midnight is absent at 9 a.m., and "never
+  saved" looks exactly like "saved but gated". When — and only when — something is
+  waiting, the footer now carries one line with the count and says those items are
+  deliberately absent. An empty queue still costs exactly 0 bytes, and the count is
+  part of the render cache key so a new candidate appears on the next request.
+
+- **Per-entry usage counters (schema v2).** `memory_usage` records `inject_count`,
+  `read_count`, `last_injected_at`, `last_read_at` per memory, so "which line spends
+  prompt bytes and is never opened" becomes answerable. The panel's Stats tab lists
+  that dead weight; `loci_get` records a read.
+
+### Migration
+
+Schema v1 → v2 adds one table. It runs through the existing migration runner: a
+`VACUUM INTO` snapshot first, then one immediate transaction, then a row-count guard
+over every pre-existing table. Rollback stays "restore the snapshot". This is the
+first real migration this project has shipped, so `test/integration/migrate.test.mjs`
+now exercises both the rehearsal step and the shipped one.
+
+### Note
+
+The same review found two things worth stating openly rather than burying: the
+plugin is **not yet in the DSH plugin catalog** (the catalog snapshot predates its
+publication), and it has been verified on `0.2.2-rc.1` only, while `engines.dsh`
+admits the whole `0.2.2-rc.1 <0.3.0-0` range. Both are tracked as open work.
+
 ## [2.0.3] — 2026-11-14
 
 ### Fixed

package/README.md

@@ -119,7 +119,7 @@ The settings page writes the fields marked *live* without a restart.
 
 - No model call in any automatic path in v1.0 — capture and summaries are
   deterministic, so the cost is visible and zero.
-- No cloud, no telemetry, no network unless you configure `vectorMode: 'http'`.
+- No cloud, no telemetry. Two optional network paths, both off by default: the update check (`updateCheck`) and the HTTP embedding channel (`vectorMode: 'http'`).
 - No cross-project leakage: reads use an explicit scope-key set, never a wildcard.
 - No physical deletion by default; `purge` needs a config switch, a confirmation,
   and leaves an audit line.

package/README.zh.md

@@ -88,7 +88,7 @@ node "$HOME/.dsh/profiles/<profile>/node_modules/dsh-loci/scripts/cli.mjs" docto
 ## 它明确不做
 
 - v1.0 的自动路径里没有模型调用 —— 捕获与摘要是确定性的，成本可见且为零。
-- 无云、无遥测；除非你配置 `vectorMode: 'http'`，否则不出网。
+- 无云、无遥测。只有两条可选出网路径，**都默认关闭**：更新检查（`updateCheck`）与 HTTP 向量通道（`vectorMode: 'http'`）。
 - 不跨项目串味：读取用显式 scope-key 集合，从不通配。
 - 默认不物理删除；`purge` 需要配置开关 + 确认 + 留审计。
 

package/client.js

@@ -43,6 +43,7 @@ window.__ModuleLoader__.load({
       'card.check': 'Check for updates',
       'card.upToDate': 'Up to date',
       'card.updateTo': 'Update available',
+      'card.checkOff': 'Update check off',
       'card.checking': 'Checking…',
       'card.unknown': 'Version check unavailable',
       'card.unpublished': 'Not on npm yet',
@@ -138,6 +139,9 @@ window.__ModuleLoader__.load({
       'panel.verifyAll': 'Verify all {n}',
       'panel.actionFailed': 'Action failed',
       'panel.injections': 'Recent injections',
+      'panel.deadWeight': 'Injected but never opened',
+      'panel.injected': 'injected',
+      'panel.opened': 'opened',
       'panel.store': 'Store',
       'panel.confirmDelete': 'Soft-delete this entry?',
       'panel.error': 'Request failed',
@@ -160,6 +164,7 @@ window.__ModuleLoader__.load({
       'card.check': '检查更新',
       'card.upToDate': '已是最新',
       'card.updateTo': '有新版本',
+      'card.checkOff': '更新检查已关闭',
       'card.checking': '检查中…',
       'card.unknown': '无法检查版本',
       'card.unpublished': '尚未发布',
@@ -255,6 +260,9 @@ window.__ModuleLoader__.load({
       'panel.verifyAll': '全部核实（{n}）',
       'panel.actionFailed': '操作失败',
       'panel.injections': '最近注入',
+      'panel.deadWeight': '注入了但从未被打开',
+      'panel.injected': '次注入',
+      'panel.opened': '次打开',
       'panel.store': '存储',
       'panel.confirmDelete': '软删除这条记忆？',
       'panel.error': '请求失败',
@@ -483,13 +491,18 @@ window.__ModuleLoader__.load({
       const version = typeof update?.version === 'string' ? update.version.replace(/^v/i, '') : null;
       const hasUpdate = update?.updateAvailable === true;
       const unknown = update !== undefined && update.status === 'unavailable';
+      // The check is opt-in, so "off" is a normal state, not a failure: it must read
+      // as switched off rather than as a button that does nothing.
+      const checkDisabled = update?.checkEnabled === false;
       const text = hasUpdate
         ? `${t('card.updateTo')}${update.latestVersion ? ` · v${update.latestVersion}` : ''}`
         : unknown
           ? t('card.unknown')
-          : update?.status === 'ok'
-            ? t('card.upToDate')
-            : t('card.check');
+          : checkDisabled
+            ? t('card.checkOff')
+            : update?.status === 'ok'
+              ? t('card.upToDate')
+              : t('card.check');
       return h(
         'span',
         { className: 'loci-card-line', style: { gap: '5px' } },
@@ -500,7 +513,7 @@ window.__ModuleLoader__.load({
             type: 'button',
             className: 'loci-btn is-quiet',
             title: text,
-            disabled: checking === true,
+            disabled: checking === true || checkDisabled,
             onClick: (event) => {
               event.stopPropagation();
               onCheck?.();
@@ -1063,6 +1076,7 @@ window.__ModuleLoader__.load({
                 { className: 'loci-kv' },
                 h('dt', null, 'path'), h('dd', null, data.memoryRoot ?? '—'),
                 h('dt', null, 'schema'), h('dd', null, `v${data.schemaVersion}`),
+                h('dt', null, 'host'), h('dd', null, data.hostVersion ?? 'unknown'),
                 h('dt', null, 'vector'), h('dd', null, `${vs.mode ?? 'off'}${vs.healthy ? ' · healthy' : ''}${vs.lastError ? ` · ${vs.lastError}` : ''}`),
                 h('dt', null, 'last injection'),
                 h('dd', null, data.lastInjection ? `${data.lastInjection.bytes} B · ${data.lastInjection.listed} listed · ${data.lastInjection.hidden} hidden` : '—'),
@@ -1077,6 +1091,31 @@ window.__ModuleLoader__.load({
                 ),
               ),
               h('div', { className: 'loci-meta', style: { marginTop: '14px' } }, `${t('panel.version')} v${data.pluginVersion ?? '—'}`),
+              // Which lines spend prompt bytes and are never opened. Sorted host-side,
+              // so the first row is the most expensive and least used.
+              (data.usage ?? []).some((row) => row.injections > 0 && row.reads === 0)
+                ? h(
+                    'div',
+                    null,
+                    h('div', { className: 'loci-section' }, t('panel.deadWeight')),
+                    (data.usage ?? [])
+                      .filter((row) => row.injections > 0 && row.reads === 0)
+                      .slice(0, 8)
+                      .map((row) =>
+                        h(
+                          'div',
+                          { key: row.id, className: 'loci-row' },
+                          h('span', { className: 'loci-id' }, row.id),
+                          h(
+                            'div',
+                            { className: 'loci-main' },
+                            h('div', { className: 'loci-name' }, row.title),
+                            h('div', { className: 'loci-meta' }, `${row.injections}×${t('panel.injected')} · 0×${t('panel.opened')}`),
+                          ),
+                        ),
+                      ),
+                  )
+                : null,
             )
           : null,
       );

package/docs/COMPATIBILITY.md

@@ -8,8 +8,39 @@
 | 0.2.2-rc.1 (host) | **24.22.3** | Ubuntu 24.04 (WSL2) | **verified** — manifest gate, 38/38 tests, coverage 82.93%, benchmark p95 5.28 ms at 2k | `scripts/run-linux-ci.sh` (fetches Node 24, runs the same commands as CI) |
 | 0.2.2-rc.1 (host) | 22.23.0 | Ubuntu 24.04 (WSL2) | **verified** — same suite × 3 consecutive runs | recorded in `docs/ACCEPTANCE.md` §6 |
 | 0.2.2-rc.1 | 24 | Ubuntu (GitHub Actions) | the identical step list runs in `.github/workflows/ci.yml`; the host is not published, so Actions has not run it | `.github/workflows/ci.yml` |
+| **0.2.2-rc.3** | 24.21.0 | Windows 11 | **API surface verified** — the source-signature probe passes 5/5 against the installed `app.asar`; not a boot test | `node scripts/compat-probe.mjs --asar <install>/resources/app.asar` |
 | other 0.2.x | — | — | not verified | — |
 
+### What "API surface verified" does and does not mean
+
+A range in `engines.dsh` is a promise nobody tested. `scripts/compat-probe.mjs`
+reads the **installed** host package out of the shipped `app.asar` and asserts that
+every Host API this plugin touches is still present in the shape it expects:
+
+```text
+host      : 0.2.2-rc.3
+[ok  ] systemPrompt sections        interpolate: false, order, section(
+[ok  ] tools service + register     super(ctx, "tools"), register(
+[ok  ] session turn/end event       "turn/end"
+[ok  ] commands service + register  super(ctx, "commands"), register(
+[ok  ] connection service           super(ctx, "connection")
+5/5 checks passed
+```
+
+It catches a renamed service, a changed section contract, or a moved event — the
+failures that would otherwise show up as "the plugin silently stopped injecting" on
+a version we never booted. It does **not** prove activation, tool registration at
+runtime, or injection on a live session; those still require a real host, and rc.3
+has not had one in this repository yet.
+
+The plugin also records the host version it meets: `DSH_INSTALL_DIR` is read at
+activation, the value lands in `meta.host_version`, and `loci doctor` prints
+`[ok] host: last opened by DeepSeek Harness 0.2.2-rc.3`. That turns every user
+install into evidence for the next compatibility table.
+
+CI runs the probe **when a host is present** and prints a skip notice otherwise
+(the host is not published to npm, so a stock runner has nothing to read).
+
 `scripts/run-linux-ci.sh` exists so the Linux claim is reproducible on any machine
 with WSL: it downloads the newest Node 24 tarball to `/tmp` (nothing is installed
 system-wide), then runs `check-manifest`, the unit+integration suite, the coverage

package/docs/SECURITY.md

@@ -17,7 +17,7 @@ file sandbox, approval policy) are the Harness's and are assumed to work.
 | T6 | The panel API is reachable from another origin | Local admin surface exposed to a web page | exact `connection.fetch` route (owner Peer, same-origin fence), JSON-only writes, 256 KB body cap, no CORS headers |
 | T7 | Data written outside the Harness home | Un-backed-up, un-scoped secrets | single root `$DSH_HOME/memory/loci/`, every path asserted with `assertInside` |
 | T8 | A write blocks the agent loop | Turn hangs | WAL + bounded busy timeout + six retries; transactions are single-digit milliseconds; capture is debounced and never awaited by the turn |
-| T9 | Memory exfiltration over the network | Privacy breach | no network code unless `vectorMode: 'http'`; the endpoint is user-configured; a failure parks the channel |
+| T9 | Memory exfiltration over the network | Privacy breach | two opt-in paths only, both off by default: the update check (`updateCheck`, one `GET` of the package metadata, carries nothing about memory) and the HTTP embedding channel (`vectorMode: 'http'`, endpoint user-configured, failure parks the channel). No other request exists — `docs/PRIVACY.md` §3 lists both |
 | T10 | Unbounded growth | Token cost creep | hard byte budget, pinned/rule caps, soft per-scope cap option |
 
 ## 2. The trust gate, precisely

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-loci",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "description": "Layered long-term memory for DeepSeek Harness: the prompt sees only a stable index, full text is one lookup away. Bi-temporal facts, strict scope isolation, verified-only injection.",
   "type": "module",
   "license": "MIT",
@@ -64,6 +64,15 @@
       ],
       "status": "verified",
       "evidence": "docs/COMPATIBILITY.md#022-rc1"
+    },
+    {
+      "dsh": "0.2.2-rc.3",
+      "node": "24.21.0",
+      "os": [
+        "win32"
+      ],
+      "status": "api-surface-verified",
+      "evidence": "docs/COMPATIBILITY.md#what-api-surface-verified-does-and-does-not-mean"
     }
   ],
   "dependencies": {

package/scripts/cli.mjs

@@ -39,6 +39,9 @@ const PLUGIN_VERSION = JSON.parse(
   readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
 ).version;
 
+/** The shipped manifest, read once: version for reports, engines for the host check. */
+const MANIFEST = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
 const rawArgv = process.argv.slice(2);
 
 /**
@@ -129,7 +132,9 @@ const diagnosticScope = () => {
 
 switch (command) {
   case 'doctor': {
-    const result = await withStore((store) => runDoctor({ store, paths, config: effectiveConfig({ home }) }));
+    const result = await withStore((store) =>
+        runDoctor({ store, paths, config: effectiveConfig({ home }), engines: MANIFEST.engines }),
+      );
     if (json) console.log(JSON.stringify(result, null, 2));
     else console.log(formatDoctor(result));
     process.exitCode = result.status === 'fail' ? 1 : 0;

package/src/host/api/routes.js

@@ -101,6 +101,9 @@ export function registerApiRoutes(ctx, deps) {
       pluginVersion: deps.version ?? '0.0.0',
       injections: store.recentInjections(50),
       audit: store.auditTail(50),
+      // Which entries spend prompt bytes and are never opened. Aggregate request
+      // stats cannot answer this, which is why schema v2 added per-entry counters.
+      usage: store.usageReport({ scopeKeys, limit: 50 }),
     });
   });
 
@@ -347,6 +350,9 @@ function installedOnly(version) {
     updateAvailable: false,
     checkedAt: null,
     status: 'idle',
+    // The card shows a "check" button; without this flag a disabled check looks
+    // broken ("nothing happens") instead of switched off.
+    checkEnabled: false,
   };
 }
 

package/src/host/config.js

@@ -100,8 +100,15 @@ export const DEFAULTS = Object.freeze({
   workingTtlDays: 7,
   /** Allow `op:'purge'` to physically delete revisions. */
   allowHardDelete: false,
-  /** Ask the registry for a newer version when the card is opened. */
-  updateCheck: true,
+  /**
+   * Ask the registry for a newer version when the card is opened.
+   *
+   * Off by default: the whole product claims "no network unless you opt in", and a
+   * default-on version check made that sentence false. A reviewer caught it, and the
+   * claim is worth more than the convenience — turning this on is one click in
+   * Settings, and the request carries nothing about memory.
+   */
+  updateCheck: false,
   /** Registry used by that check; point it at a mirror when npmjs.org is slow. */
   updateRegistry: 'https://registry.npmjs.org',
   /** 'error' | 'info' | 'debug'. */

package/src/host/doctor.js

@@ -21,7 +21,7 @@ function check(name, status, detail) {
  * @returns `{status, checks, summary}` where status is the worst check status.
  */
 export function runDoctor(options) {
-  const { store, paths, config } = options;
+  const { store, paths, config, engines } = options;
   const checks = [];
 
   const health = (() => {
@@ -63,6 +63,19 @@ export function runDoctor(options) {
   const lastMaintenance = Number(health.migration?.to === undefined ? 0 : 0);
   checks.push(check('rows', 'ok', `${health.counts.memory} revisions · ${health.counts.memory_head} entries · ${health.counts.entity} entities`));
 
+  // Which Harness opened this store. A range in engines.dsh is a promise; this row
+  // is what actually happened, and it is the first thing to ask for in a bug report.
+  try {
+    const hostVersion = store.hostVersion ?? null;
+    checks.push(
+      hostVersion === null
+        ? check('host', 'warn', `not recorded yet; this build declares engines.dsh ${engines?.dsh ?? 'unknown'}`)
+        : check('host', 'ok', `last opened by DeepSeek Harness ${hostVersion}`),
+    );
+  } catch (error) {
+    checks.push(check('host', 'warn', `could not read: ${String(error?.message ?? error)}`));
+  }
+
   try {
     accessSync(paths.root, constants.W_OK);
     checks.push(check('data directory', 'ok', paths.root));

package/src/host/host-version.js

@@ -0,0 +1,89 @@
+/**
+ * Which Harness version are we actually running on?
+ *
+ * `engines.dsh` is a range; a range is a promise nobody tested. This module resolves
+ * the *installed* host package at activation time and records it, so the panel and
+ * `doctor` can say "running on 0.2.2-rc.3" instead of leaving the user to guess
+ * which point release the plugin met. It is best-effort by design: a plugin that
+ * refuses to boot because it cannot read someone else's package.json is worse than
+ * one that says "unknown".
+ *
+ * @module dsh-loci/host-version
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const CANDIDATE_PATHS = [
+  // The Host normally resolves as a peer dependency of the profile.
+  '@deepseek-ai/dsh/package.json',
+  // Desktop bundles keep it one level down.
+  'dsh/package.json',
+];
+
+/**
+ * Resolve the installed host version.
+ *
+ * @param from - module URL to resolve relative to (defaults to this module).
+ * @returns `{version, path}` when found, `undefined` otherwise.
+ */
+export function detectHostVersion(from = import.meta.url) {
+  // The Host sets this to its own package directory, and the plugin runs inside the
+  // Host process, where reading an `app.asar/...` path works.
+  const installDir = process.env.DSH_INSTALL_DIR;
+  if (typeof installDir === 'string' && installDir.length > 0) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(installDir, 'package.json'), 'utf8'));
+      if (typeof manifest?.version === 'string' && manifest.version.length > 0) {
+        return { version: manifest.version, path: join(installDir, 'package.json') };
+      }
+    } catch {
+      /* fall through to resolution */
+    }
+  }
+
+  let require;
+  try {
+    require = createRequire(from);
+  } catch {
+    return undefined;
+  }
+  for (const candidate of CANDIDATE_PATHS) {
+    try {
+      const resolved = require.resolve(candidate);
+      const manifest = JSON.parse(readFileSync(resolved, 'utf8'));
+      if (typeof manifest?.version === 'string' && manifest.version.length > 0) {
+        return { version: manifest.version, path: resolved };
+      }
+    } catch {
+      /* try the next candidate */
+    }
+  }
+  // Last resort: a sibling directory named `dsh` next to a cordis install.
+  try {
+    const resolved = require.resolve('@deepseek-ai/cordis/package.json');
+    const sibling = join(dirname(dirname(resolved)), 'dsh', 'package.json');
+    const manifest = JSON.parse(readFileSync(sibling, 'utf8'));
+    if (typeof manifest?.version === 'string') return { version: manifest.version, path: sibling };
+  } catch {
+    /* nothing else to try */
+  }
+  return undefined;
+}
+
+/**
+ * Compare a version against the `engines.dsh` range in one coarse way: does the
+ * major/minor line match what this build declares it supports?
+ *
+ * Deliberately not a semver implementation — the plugin has no dependency on one.
+ * It answers the only question that matters for a support message: "is this an
+ * untested point release inside our declared range, or a different line entirely?"
+ *
+ * @param version - the detected host version.
+ * @returns 'same-line' | 'other-line' | 'unknown'.
+ */
+export function hostLineOf(version) {
+  const match = /^(\d+)\.(\d+)\./.exec(String(version ?? ''));
+  if (match === null) return 'unknown';
+  return `${match[1]}.${match[2]}` === '0.2' ? 'same-line' : 'other-line';
+}

package/src/host/index.js

@@ -18,11 +18,12 @@ import { registerTools } from './tools/tools.js';
 import { registerApiRoutes } from './api/routes.js';
 import { UpdateChecker } from './update.js';
 import { Extractor, completeViaHost } from './extract/extractor.js';
+import { detectHostVersion, hostLineOf } from './host-version.js';
 import { registerCommands } from './commands.js';
 import { runDoctor } from './doctor.js';
 
 /** Version stamped into the database and diagnostics. */
-export const VERSION = '2.0.3';
+export const VERSION = '2.2.0';
 
 /** Optional collaborators; without them the plugin still serves tools. */
 export const inject = ['systemPrompt', 'tools'];
@@ -98,15 +99,30 @@ export function apply(ctx, rawConfig = {}) {
   log.info(`loci: using ${memoryRoot}`);
 
   let capture;
+  // Record which Harness this store is actually running on. `engines.dsh` is a
+  // range; this field is the only one that says which point release met the file,
+  // so a support report can be checked instead of guessed at.
+  const detectedHost = detectHostVersion();
   const store = new Store({
     memoryRoot,
     paths,
     config,
     log,
     pluginVersion: VERSION,
+    hostVersion: detectedHost?.version,
     live: read,
     quoteVerifier: (quote, options) => capture?.verifyQuote(quote, options) ?? false,
   });
+  if (detectedHost !== undefined) {
+    try {
+      store.db
+        .prepare("INSERT INTO meta (key, value) VALUES ('host_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+        .run(detectedHost.version);
+    } catch {
+      /* recording is best effort */
+    }
+    log?.info?.(`loci: host ${detectedHost.version} (${hostLineOf(detectedHost.version)})`);
+  }
 
   const updates = new UpdateChecker({
     currentVersion: VERSION,

package/src/host/inject/index-section.js

@@ -24,8 +24,14 @@ export const INDEX_SECTION_NAME = 'loci:index';
 /** Placement: after MCP servers (3100), before the tools SDK section (5000). */
 export const INDEX_SECTION_ORDER = 4000;
 
-/** Bytes reserved for the closing footer before index lines are admitted. */
-const FOOTER_RESERVE = 240;
+/**
+ * Bytes reserved for the closing footer before index lines are admitted.
+ *
+ * The footer is not fixed: "… +N more" and the pending-review notice grow with the
+ * store, and the shrink loop below would otherwise admit a line and immediately
+ * take it back on every render. 400 bytes covers the worst realistic footer.
+ */
+const FOOTER_RESERVE = 400;
 
 /** Days in milliseconds. */
 export const DAY = 86_400_000;
@@ -64,14 +70,17 @@ export function renderIndexBody(options) {
   const rulesMaxBytes = Math.max(0, Math.min(maxBytes, cfg('rulesMaxBytes')));
   const maxEntries = Math.max(1, Math.min(2000, cfg('indexMaxEntries')));
   const lineChars = Math.max(40, Math.min(400, cfg('indexLineMaxChars')));
-  const empty = { text: '', bytes: 0, listed: 0, total: 0, hidden: 0 };
+  const empty = { text: '', bytes: 0, listed: 0, total: 0, hidden: 0, ids: [] };
 
   const rules = store.ruleEntries({ scopeKeys, now, limit: 24 });
   const entries = store.indexEntries({ scopeKeys, now, limit: maxEntries + 1 });
   const truncatedByCount = entries.length > maxEntries;
   const visible = truncatedByCount ? entries.slice(0, maxEntries) : entries;
   const total = truncatedByCount ? store.countIndex(scopeKeys, now) : visible.length;
-  if (rules.length === 0 && visible.length === 0) return empty;
+  // Counted always, rendered only when it is not zero: an empty queue must cost
+  // exactly zero bytes, or the "0 bytes when empty" promise is a lie.
+  const pending = store.countPending(scopeKeys);
+  if (rules.length === 0 && visible.length === 0 && pending === 0) return empty;
 
   const headLines = [FENCE_OPEN];
   const ruleLines = [];
@@ -95,19 +104,30 @@ export function renderIndexBody(options) {
   // A scope label comes from a directory name, which a user can make contain a
   // newline. Flattening it here is what stops a crafted folder name from writing
   // extra lines into the fence.
-  const indexHeader = `Index — ${renderSafe(indexTitle(scopeLabel, 120))}`;
+  // Only when there is an index to label. A store holding nothing but pending
+  // candidates used to render an empty "Index —" heading, which reads as "memory is
+  // empty" right next to the line saying something is waiting.
+  const indexHeader = visible.length > 0 ? `Index — ${renderSafe(indexTitle(scopeLabel, 120))}` : '';
   const entryLine = (entry) => `- ${entry.id} · ${entry.kind} · ${formatDate(entry.validFrom)} · ${renderSafe(indexTitle(entry.title, lineChars))}`;
 
   const footerFor = (listed) => {
     const hidden = Math.max(0, total - listed);
     const parts = [];
     if (hidden > 0) parts.push(`… +${hidden} more (loci_search finds the rest; this section shows ${listed} of ${total})`);
+    // The one line that makes verified-only injection legible from inside the
+    // conversation. Without it "you never saved that" and "I saved it but it is
+    // waiting for you" are indistinguishable to the model and to the user.
+    if (pending > 0) {
+      parts.push(
+        `${pending} item(s) await review and are deliberately absent here — a person approves them in Memory → Review (/loci review); say so if the user expects them.`,
+      );
+    }
     parts.push(`as of ${formatDate(now)} · ${FULL_TEXT_HINT}`);
     parts.push(FENCE_CLOSE);
     return parts.join('\n');
   };
 
-  const baseBytes = bytes([...headLines, ...ruleLines, indexHeader].join('\n'));
+  const baseBytes = bytes([...headLines, ...ruleLines, ...(indexHeader === '' ? [] : [indexHeader])].join('\n'));
 
   // Admit entries while the reserved footer still fits.
   let admitted = 0;
@@ -123,7 +143,7 @@ export function renderIndexBody(options) {
   let listed = admitted;
   let text = '';
   for (let n = admitted; ; n -= 1) {
-    const lines = [...headLines, ...ruleLines, indexHeader, ...visible.slice(0, n).map(entryLine), footerFor(n)];
+    const lines = [...headLines, ...ruleLines, ...(indexHeader === '' ? [] : [indexHeader]), ...visible.slice(0, n).map(entryLine), footerFor(n)];
     text = lines.join('\n');
     if (bytes(text) <= maxBytes || n === 0) {
       listed = n;
@@ -135,12 +155,23 @@ export function renderIndexBody(options) {
   // lines from the tail rather than ever exceeding the budget.
   while (bytes(text) > maxBytes && ruleLines.length > 0) {
     ruleLines.pop();
-    const lines = [...headLines, ...ruleLines, indexHeader, footerFor(0)];
+    const lines = [...headLines, ...ruleLines, ...(indexHeader === '' ? [] : [indexHeader]), footerFor(0)];
     text = lines.join('\n');
     listed = 0;
   }
 
-  return { text, bytes: bytes(text), listed, total, hidden: Math.max(0, total - listed) };
+  return {
+    text,
+    bytes: bytes(text),
+    listed,
+    total,
+    hidden: Math.max(0, total - listed),
+    // Rule lines are injected too, and they are the ones a person most wants usage
+    // data for, so both blocks report their ids.
+    // Rule lines are injected too, and they are the ones a person most wants usage
+    // data for, so both blocks report their ids. `ruleEntries` is already verified-only.
+    ids: [...rules.slice(0, 12).map((rule) => rule.id), ...visible.slice(0, listed).map((entry) => entry.id)],
+  };
 }
 
 /**
@@ -168,6 +199,7 @@ export function createIndexSection(options) {
         bytes: rendered.bytes,
         listed: rendered.listed,
         hidden: rendered.hidden,
+        ids: rendered.ids ?? [],
       });
     } catch (error) {
       log?.warn?.(`loci: cannot record injection: ${String(error?.message ?? error)}`);
@@ -203,7 +235,11 @@ export function createIndexSection(options) {
     ].join(':');
     const now = Date.now();
     const day = new Date(now).toISOString().slice(0, 10);
-    const key = `${context.scopeKeys.join(',')}|${store.indexRev()}|${configKey}|${day}`;
+    // The pending count is part of the key: if it is not, a newly queued candidate
+    // stays invisible until something else invalidates the cache, which defeats
+    // the whole point of the notice.
+    const pending = store.countPending(context.scopeKeys);
+    const key = `${context.scopeKeys.join(',')}|${store.indexRev()}|${configKey}|${day}|${pending}`;
     const cached = cache.get(key);
     if (cached !== undefined) {
       record(context, cached);

package/src/host/store/migrate.js

@@ -12,6 +12,7 @@
 import { copyFileSync, existsSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { backupTo, tableCounts, withTransaction } from './db.js';
+import { MEMORY_USAGE_DDL } from './schema.js';
 import {
   META_KEYS,
   SCHEMA_VERSION,
@@ -28,7 +29,18 @@ import {
  * drives it with a rehearsal step so the path is never untested.
  * @type {Array<{from:number,to:number,up:(db:import('node:sqlite').DatabaseSync)=>void,verify?:(db:import('node:sqlite').DatabaseSync)=>void}>}
  */
-export const SHIPPED_MIGRATIONS = [];
+export const SHIPPED_MIGRATIONS = [
+  {
+    from: 1,
+    to: 2,
+    // v2 adds per-entry usage counters. The table is new and empty, so the
+    // migration cannot lose a row; the row-count guard in \`migrate()\` still runs
+    // over every existing table and would catch a mistake here.
+    up(db) {
+      db.exec(MEMORY_USAGE_DDL);
+    },
+  },
+];
 
 /**
  * Whether the file already holds the Loci core table.

package/src/host/store/schema.js

@@ -8,7 +8,27 @@
  */
 
 /** Schema version this build writes and expects. */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
+
+/**
+ * DDL for the v2 per-entry usage table.
+ *
+ * Kept as its own constant because two paths must agree on it: a fresh database
+ * (via {@link SCHEMA_SQL}) and an existing one (via the v1→v2 migration). A table
+ * that only exists on new installs is the classic way a feature "works on my
+ * machine".
+ */
+export const MEMORY_USAGE_DDL = `
+CREATE TABLE IF NOT EXISTS memory_usage (
+  id               TEXT PRIMARY KEY,
+  inject_count     INTEGER NOT NULL DEFAULT 0,
+  read_count       INTEGER NOT NULL DEFAULT 0,
+  last_injected_at INTEGER,
+  last_read_at     INTEGER
+);
+CREATE INDEX IF NOT EXISTS ix_memory_usage_inject ON memory_usage (inject_count DESC);
+CREATE INDEX IF NOT EXISTS ix_memory_usage_read ON memory_usage (read_count DESC);
+`;
 
 /** DDL for a fresh database. Order matters: FTS and the head table follow `memory`. */
 export const SCHEMA_SQL = `
@@ -113,6 +133,9 @@ CREATE TABLE IF NOT EXISTS token_stat (
   df    INTEGER NOT NULL DEFAULT 0
 );
 
+${MEMORY_USAGE_DDL}
+
+
 CREATE TABLE IF NOT EXISTS request_stat (
   id             INTEGER PRIMARY KEY AUTOINCREMENT,
   ts             INTEGER NOT NULL,
@@ -137,6 +160,8 @@ export const META_KEYS = Object.freeze({
   createdAt: 'created_at',
   indexRev: 'index_rev',
   lastMaintenance: 'last_maintenance',
+  /** The Harness version this store has been used with, recorded at activation. */
+  hostVersion: 'host_version',
 });
 
 /**

package/src/host/store/store.js

@@ -123,6 +123,8 @@ export class Store {
     this.now = options.now ?? (() => Date.now());
     this.quoteVerifier = options.quoteVerifier ?? (() => false);
     this.pluginVersion = options.pluginVersion ?? '0.0.0';
+    /** Recorded host version, so support can see which point release met this store. */
+    this.hostVersion = options.hostVersion ?? undefined;
     this.readOnly = options.readOnly === true;
     this.db = openDatabase({ file: this.paths.db, readOnly: this.readOnly });
     this.audit = this.readOnly
@@ -829,6 +831,32 @@ export class Store {
     );
   }
 
+  /**
+   * How many entries in these scopes are waiting for a human.
+   *
+   * This is what the injected section reports. Verified-only injection has a
+   * failure mode the user cannot see: a fact the model wrote at midnight is simply
+   * absent at 9 a.m., and "never saved" looks exactly like "saved but gated". One
+   * number in the prompt is enough to tell those apart, and it costs nothing when
+   * the queue is empty.
+   *
+   * @param scopeKeys - explicit scope keys (never a wildcard).
+   * @returns the count of candidate and disputed entries.
+   */
+  countPending(scopeKeys) {
+    if (scopeKeys.length === 0) return 0;
+    const marks = scopeKeys.map(() => '?').join(', ');
+    return Number(
+      this.db
+        .prepare(
+          `SELECT COUNT(*) AS n FROM memory m
+           WHERE m.status IN ('candidate', 'disputed') AND m.deleted_at IS NULL
+             AND m.scope_key IN (${marks})`,
+        )
+        .get(...scopeKeys)?.n ?? 0,
+    );
+  }
+
   /**
    * Verified rules for the rules block, newest last.
    * @param options - `scopeKeys`, `now`, `limit`.
@@ -1033,6 +1061,9 @@ export class Store {
       byStatus,
       byKind,
       byScope,
+      // Which Harness point release this store has met. A range in engines.dsh is a
+      // promise; this is the record of what actually opened the file.
+      hostVersion: this.hostVersion ?? readMeta(this.db, META_KEYS.hostVersion) ?? null,
       pendingCandidates: pending,
       disputed,
       lastInjection:
@@ -1062,6 +1093,20 @@ export class Store {
         'INSERT INTO request_stat (ts, session_id, scope_key, section_bytes, entries_listed, entries_hidden) VALUES (?, ?, ?, ?, ?, ?)',
       )
       .run(this.now(), row.sessionId ?? null, row.scopeKey ?? null, row.bytes, row.listed, row.hidden);
+    // Per-entry counters, so "which line earns its bytes" stays answerable after the
+    // aggregate rows rotate out. A listed entry never fetched by id is the dead
+    // weight this product exists to find.
+    if (Array.isArray(row.ids) && row.ids.length > 0) {
+      const bump = this.db.prepare(
+        `INSERT INTO memory_usage (id, inject_count, read_count, last_injected_at)
+         VALUES (?, 1, 0, ?)
+         ON CONFLICT(id) DO UPDATE SET inject_count = inject_count + 1, last_injected_at = excluded.last_injected_at`,
+      );
+      const now = this.now();
+      withTransaction(this.db, () => {
+        for (const id of row.ids) bump.run(id, now);
+      });
+    }
     this.db.prepare('DELETE FROM request_stat WHERE ts < ?').run(this.now() - 90 * 86_400_000);
     this.audit.append('inject', {
       sessionId: row.sessionId ?? null,
@@ -1072,6 +1117,64 @@ export class Store {
     });
   }
 
+  /**
+   * Record that one entry was fetched by id.
+   *
+   * Injection counts alone cannot tell "the index line was enough" from "the model
+   * opened it": only this counter can.
+   * @param id - memory id.
+   */
+  recordRead(id) {
+    if (typeof id !== 'string' || id.length === 0) return;
+    try {
+      this.db
+        .prepare(
+          `INSERT INTO memory_usage (id, inject_count, read_count, last_read_at)
+           VALUES (?, 0, 1, ?)
+           ON CONFLICT(id) DO UPDATE SET read_count = read_count + 1, last_read_at = excluded.last_read_at`,
+        )
+        .run(id, this.now());
+    } catch {
+      // A counter must never fail a read.
+    }
+  }
+
+  /**
+   * Which entries spend prompt budget without being opened.
+   *
+   * @param options - `scopeKeys`, `limit`.
+   * @returns rows sorted by injections desc, reads asc.
+   */
+  usageReport(options = {}) {
+    const keys = options.scopeKeys ?? [];
+    const limit = Math.max(1, Math.min(200, options.limit ?? 20));
+    const marks = keys.length > 0 ? ` AND m.scope_key IN (${keys.map(() => '?').join(', ')})` : '';
+    const rows = this.db
+      .prepare(
+        `SELECT m.id, m.title, m.kind, h.status,
+                COALESCE(u.inject_count, 0) AS injections,
+                COALESCE(u.read_count, 0) AS reads,
+                u.last_injected_at, u.last_read_at
+         FROM memory m
+         JOIN memory_head h ON h.ord = m.ord
+         LEFT JOIN memory_usage u ON u.id = m.id
+         WHERE m.deleted_at IS NULL${marks}
+         ORDER BY COALESCE(u.inject_count, 0) DESC, COALESCE(u.read_count, 0) ASC
+         LIMIT ?`,
+      )
+      .all(...keys, limit);
+    return rows.map((row) => ({
+      id: row.id,
+      title: row.title,
+      kind: row.kind,
+      status: row.status,
+      injections: Number(row.injections),
+      reads: Number(row.reads),
+      lastInjectedAt: row.last_injected_at === null ? null : Number(row.last_injected_at),
+      lastReadAt: row.last_read_at === null ? null : Number(row.last_read_at),
+    }));
+  }
+
   /**
    * Record one recall.
    * @param row - `query` length, counts, timing, channels.

package/src/host/tools/tools.js

@@ -333,7 +333,17 @@ export function createTools(deps) {
       const id = str(args, 'id', { required: true, maxChars: 64 });
       const revision = int(args, 'revision', { min: 1 });
       const includeHistory = bool(args, 'includeHistory', true);
-      return store.get(id, { revision, includeHistory });
+      const result = store.get(id, { revision, includeHistory });
+      // A read counter is what separates "the index line was enough" from "the model
+      // had to open it". It must never fail the read itself.
+      if (result?.entry !== undefined) {
+        try {
+          store.recordRead(result.entry.id);
+        } catch {
+          /* counting is best effort */
+        }
+      }
+      return result;
     },
   };
 

package/src/mcp/store-facade.js

@@ -36,7 +36,7 @@ export function openFacadeStore(options = {}) {
     memoryRoot: root,
     paths,
     config,
-    pluginVersion: '2.0.3',
+    pluginVersion: '2.2.0',
     readOnly: options.readOnly === true,
   });
   return { store, paths };