claude-mem-lite 6.1.0 → 6.3.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.1.0",
+      "version": "6.3.0",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -134,16 +134,23 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 
 | Platform | Status | Notes |
 |----------|--------|-------|
-| **Linux** | Supported | Primary development and testing platform |
+| **Linux** | Supported | Primary development and testing platform; the whole CI matrix runs here |
 | **macOS** | Supported | Fully compatible (Intel and Apple Silicon) |
-| **Windows** | Not supported | Uses POSIX shell scripts (`post-tool-use.sh`, `setup.sh`) and Unix file locking; WSL2 may work but is untested |
+| **Windows** | Installs, not CI-covered | The MCP server, the CLI and the `node` hooks work (`better-sqlite3` ships `win32-x64` and `win32-arm64` prebuilds, so nothing is compiled). **Three hook commands run under `bash`** — `setup.sh`, `post-tool-use.sh`, `pre-agent-inject.sh` — and need Git for Windows or WSL on `PATH`; `claude-mem-lite doctor` reports it when `bash` cannot be found. No GitHub Actions runner exercises Windows, so this rests on user reports ([#28](https://github.com/sdsrss/claude-mem-lite/issues/28)), not on a green pipeline |
+| **WSL2** | Untested | Linux under the hood, so it should behave as the Linux row; nobody has reported either way |
+
+From v5.1.0 through v6.1.0, `package.json` declared `os: ["darwin", "linux"]`. That is an npm *install*
+gate, not a runtime check: on Windows it made `npm install` exit `EBADPLATFORM`, which the
+plugin launcher runs on the first MCP start after every plugin update — so the server never
+came up and `/mcp` reported `CONNECTION_CLOSED`. `win32` is now in the list. A platform that
+is still outside it gets a message naming both sides of the mismatch instead of a guess.
 
 ## Requirements
 
 - **Node.js** >= 22
 - **Claude Code** CLI installed and configured (`claude` command available)
-- **SQLite3** support (provided by `better-sqlite3`, compiled on install)
-- **Platform**: Linux or macOS (see [Platform Support](#platform-support))
+- **SQLite3** support (provided by `better-sqlite3` 13, which ships prebuilt binaries for 8 platforms — no compiler needed on any of them; a platform it has no prebuild for falls back to building from source)
+- **Platform**: Linux or macOS; Windows installs and runs but is not CI-covered and needs Git Bash or WSL for three hooks (see [Platform Support](#platform-support))
 
 ## Installation
 

package/README.zh-CN.md

@@ -100,16 +100,22 @@
 
 | 平台 | 状态 | 说明 |
 |------|------|------|
-| **Linux** | 支持 | 主要开发和测试平台 |
+| **Linux** | 支持 | 主要开发和测试平台；整个 CI 矩阵都跑在这里 |
 | **macOS** | 支持 | 完全兼容（Intel 和 Apple Silicon） |
-| **Windows** | 暂不支持 | 使用 POSIX shell 脚本（`post-tool-use.sh`、`setup.sh`）和 Unix 文件锁；WSL2 可能可用但未经测试 |
+| **Windows** | 可安装，但无 CI 覆盖 | MCP server、CLI 和 `node` 类 hook 均可用（`better-sqlite3` 自带 `win32-x64` / `win32-arm64` 预编译产物，无需编译）。**有三个 hook 命令走 `bash`** —— `setup.sh`、`post-tool-use.sh`、`pre-agent-inject.sh` —— 需要 PATH 上有 Git for Windows 或 WSL；`bash` 找不到时 `claude-mem-lite doctor` 会报出来。GitHub Actions 没有 Windows runner，所以这一行依据的是用户报告（[#28](https://github.com/sdsrss/claude-mem-lite/issues/28)）而不是绿色流水线 |
+| **WSL2** | 未测试 | 底层就是 Linux，预期与 Linux 行一致；但无人报告过实际结果 |
+
+v5.1.0 到 v6.1.0 之间，`package.json` 声明的是 `os: ["darwin", "linux"]`。那是 npm 的**安装**门禁，不是运行时检查：
+在 Windows 上它让 `npm install` 以 `EBADPLATFORM` 退出，而插件启动器每次插件更新后的首次 MCP 启动都要跑这条
+安装 —— 于是 server 起不来，`/mcp` 报 `CONNECTION_CLOSED`。现在 `win32` 已加入该列表。仍不在列表内的平台会拿到
+一条同时点明“声明了什么”和“当前是什么”的消息，而不是一句猜测。
 
 ## 环境要求
 
 - **Node.js** >= 22（v4.0.0 起：better-sqlite3 13 要求 >=22，Node 20 已于 2026-04 EOL；`package.json` 的 `engines` 是唯一事实来源）
 - **Claude Code** CLI 已安装并配置（`claude` 命令可用）
-- **SQLite3** 支持（由 `better-sqlite3` 提供，安装时编译）
-- **平台**：Linux 或 macOS（参见[平台支持](#平台支持)）
+- **SQLite3** 支持（由 `better-sqlite3` 13 提供，它自带 8 个平台的预编译产物，这些平台上都不需要编译器；没有对应预编译产物的平台才会回退到源码编译）
+- **平台**：Linux 或 macOS；Windows 可安装运行，但无 CI 覆盖，且三个 hook 需要 Git Bash 或 WSL（参见[平台支持](#平台支持)）
 
 ## 安装
 

package/hook-shared.mjs

@@ -22,6 +22,12 @@ import { resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
 // Pure-`node:`/local module (it imports only binding-probe + native-binding-hint, and
 // neither imports this file) — no cycle.
 import { recordHookError } from './lib/hook-telemetry.mjs';
+import {
+  isSchemaSkewError,
+  schemaSkewFromError,
+  shouldRecordSkew,
+  SKEW_MARKER_PREFIX,
+} from './lib/schema-skew.mjs';
 // Audit 2026-09-05 P1-2 (carried from 2026-09-02 P2-9): `callLLM`, the quiet/adoption
 // predicates and the handoff constants moved into `lib/` because two lib modules
 // imported them from here and dragged this file's whole import graph — haiku-client,
@@ -237,6 +243,7 @@ export const GC_PROJECT_MARKER_PREFIXES = Object.freeze([
   // forever. `.skill-cooldown-` / `.skill-reco-cooldown-` left with the skill registry in
   // v5.0.0; a prefix for files nothing writes any more is dead weight in a hot-path loop.
   'last-mark-compressible-', // per-project auto-compress 24h gate
+  SKEW_MARKER_PREFIX, // per-project schema-skew log dedup; regenerated on the next skewed open
 ]);
 
 // Records of a completed side effect — never age out. `ep-`/`ep-flush-`/
@@ -382,12 +389,58 @@ export function createSessionId() {
 
 // ─── Database ────────────────────────────────────────────────────────────────
 
+// Last forward-incompat ("the DB is newer than me") failure seen in THIS process, or null.
+// SessionStart needs the two version numbers to render its notice and openDb has just been
+// handed them, so this beats a second DB open — and on a skew there may be no working
+// binding to open with anyway.
+let lastSkew = null;
+
+/**
+ * The schema skew that made the most recent openDb() return null, or null.
+ * Cleared by any successful open, so a heal mid-session stops the notice.
+ *
+ * @returns {{dbVersion: number|null, binaryVersion: number|null}|null}
+ */
+export function lastSchemaSkew() {
+  return lastSkew;
+}
+
 export function openDb() {
   try {
     // WAL-corruption self-heal (was server.mjs-only): without it, hooks stayed
     // silently dead (null DB) on a corrupt WAL until the next MCP server start.
-    return ensureDbWithWalRecovery();
+    const db = ensureDbWithWalRecovery();
+    lastSkew = null;
+    return db;
   } catch (e) {
+    // Forward-incompat is its own family: it cannot be healed by anything this process can
+    // do, it repeats on every single open, and it is the one failure the USER has to act on.
+    // Record it once and hand the numbers to SessionStart, which is the surface that speaks.
+    // Forward-incompat is its own family: nothing this process can do heals it, it repeats on
+    // every single open, and it is the one failure the USER has to act on. Dedup lives in
+    // lib/schema-skew.mjs so the `ups` face — which opens the DB itself and logged its own 15
+    // of the day's 727 lines — shares one implementation instead of drifting from this one.
+    //
+    // shouldRecordSkew is TOTAL by contract. Nothing in this catch may throw: the first cut
+    // called getSessionId() here, which MINTS and writes a session id, so an unwritable
+    // runtime dir turned openDb() itself into a thrower. All 13 call sites are written to
+    // no-op on null and none of them expects an exception.
+    if (isSchemaSkewError(e)) {
+      lastSkew = schemaSkewFromError(e) || { dbVersion: null, binaryVersion: null };
+      // Guarded even though inferProject() reads env and cwd: "the only statement in this
+      // catch cannot throw" was true of the original one-line body and stopped being true
+      // the moment anything was added. An unscoped marker is a worse dedup, not a crash.
+      let project = '';
+      try {
+        project = inferProject();
+      } catch {
+        /* total: the marker degrades to one shared file */
+      }
+      if (shouldRecordSkew(RUNTIME_DIR, project, lastSkew)) {
+        recordHookError('hook-shared:db-open', e, RUNTIME_DIR);
+      }
+      return null;
+    }
     // Still null, still no throw — a hook must never crash the host session, and all
     // eight call sites in hook.mjs are written to no-op on null. But "returned null"
     // used to be the ONLY trace: nothing reached runtime/hook-errors/, so `stats`

package/hook-update.mjs

@@ -228,7 +228,11 @@ function isPluginMode() {
 }
 
 // ── Dev Mode Detection ─────────────────────────────────────
-function isDevMode() {
+// Exported since the schema-skew notice needs it: a dev checkout must be told `git pull`,
+// never a command that would overwrite its working tree. Re-implementing the check at the
+// call site would make it the second copy of a predicate this file has already had to get
+// right twice (whole-dir symlink, then per-file drift) — the twin-drift class.
+export function isDevMode() {
   try {
     // A dev checkout always carries a .git dir. This catches a whole-directory
     // symlink (~/.claude-mem-lite -> /repo): lstat on server.mjs there follows the

package/hook.mjs

@@ -60,7 +60,9 @@ import {
   episodeHasSignificantContent,
   explainSignificance,
 } from './hook-episode.mjs';
-import { DB_DIR } from './schema.mjs';
+// CODE_DIR, not DB_DIR: the schema-skew notice asks which CODE homes exist, and those are
+// always homedir-rooted even when CLAUDE_MEM_DIR relocates the data.
+import { DB_DIR, CODE_DIR } from './schema.mjs';
 import { cleanupClaudeMdLegacyBlock, buildSessionContextLines } from './hook-context.mjs';
 import { entry as preCompactEntry } from './hook-precompact.mjs';
 import {
@@ -82,6 +84,7 @@ import {
   spawnBackground,
   sweepOrphanEpisodeFiles,
   sweepStaleProjectMarkers,
+  lastSchemaSkew,
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveEpisodeImmediate } from './hook-llm.mjs';
 import { readFastSummarySource, insertFastSummary, FAST_SUMMARY_LIMITS } from './lib/fast-summary.mjs';
@@ -2290,6 +2293,67 @@ async function buildStartupDashboardText(db, project) {
   }
 }
 
+/**
+ * Tell the user their memory is version-skewed, on the one surface they read.
+ *
+ * Only fires when openDb() failed for THIS reason — hook-shared records the two version
+ * numbers as it catches, so nothing is re-derived and no second DB open is attempted (on a
+ * skew there may be no usable binding to open with).
+ *
+ * Everything is dynamically imported: this is a cold path that must not cost the healthy
+ * SessionStart an install-shape scan. And it goes through the queue helpers, never a bare
+ * console.log — SessionStart merges three would-be stdout contributors into ONE envelope,
+ * and writing raw prose alongside it once made the host deliver the whole JSON object to
+ * the model as literal text (tests/session-start-stdout-envelope.test.mjs).
+ */
+async function emitSchemaSkewNotice() {
+  try {
+    const skew = lastSchemaSkew();
+    if (!skew) return;
+    const [shapeMod, updateMod, skewMod] = await Promise.all([
+      import('./lib/install-shape.mjs'),
+      import('./hook-update.mjs'),
+      import('./lib/schema-skew.mjs'),
+    ]);
+    const shape = shapeMod.detectInstallShape({ installDir: CODE_DIR });
+    // WHICH tree is running this hook, not which trees exist. CLAUDE_PLUGIN_ROOT is set in
+    // every hook process Claude Code spawns, so on a machine holding BOTH a managed install
+    // and a plugin cache it is the only thing that knows which one is behind. Deciding from
+    // the machine's global shape printed `claude-mem-lite self-update` beneath a line naming
+    // the plugin cache — a repair that cannot advance the tree it had just named.
+    const runningRoot = process.env.CLAUDE_PLUGIN_ROOT || CODE_DIR;
+    const remedy = skewMod.schemaSkewRemedy({
+      managed: shape.managed,
+      activePluginVersion: shape.activePluginVersion,
+      dev: updateMod.isDevMode(),
+      root: runningRoot,
+    });
+    const notice = skewMod.formatSchemaSkewNotice({
+      dbVersion: skew.dbVersion,
+      binaryVersion: skew.binaryVersion,
+      remedy,
+      // Name the home only when the remedy is about that home, so the two can never disagree.
+      codeHome:
+        remedy.kind === 'plugin' && shape.activePluginVersion
+          ? `plugin cache v${shape.activePluginVersion.version}`
+          : undefined,
+    });
+    // BOTH channels, and the HUMAN one is the point. queueHookContext reaches the model;
+    // lib/hook-stdout.mjs's queueHookSystemMessage is documented "for the HUMAN, not the
+    // model" and names v3.70.0 for making exactly this mistake — folding a banner into
+    // additionalContext "kept its content and lost its audience". A notice whose whole job is
+    // to hand the user a command must not depend on the assistant volunteering it.
+    // flushHookStdout merges both into one envelope, so this is additive: the model learns
+    // memory is unavailable, the user gets the repair.
+    queueHookSystemMessage(notice);
+    queueHookContext('SessionStart', notice);
+  } catch (e) {
+    // A hook must never crash the host session, and a notice that cannot render is still
+    // better handled by staying quiet than by taking SessionStart down with it.
+    debugCatch(e, 'session-start-schema-skew');
+  }
+}
+
 async function handleSessionStart() {
   // GC stale per-session cooldown files. Cheap (<5ms typical) and idempotent;
   // moved here from pre-tool-recall.js's hot path.
@@ -2471,7 +2535,16 @@ async function handleSessionStart() {
   const project = inferProject();
 
   const db = openDb();
-  if (!db) return;
+  if (!db) {
+    // A null DB used to end SessionStart in total silence. For most causes that is right —
+    // they are transient, or a repair path is already running. Forward-incompat is neither:
+    // it persists until the user installs newer code, it disables every write path, and the
+    // only other signal it produces is a `-32000 Connection closed` from the MCP host, which
+    // names nothing. Measured 2026-09-08: a whole day of it, >=648 log lines, zero words to
+    // the user. This is the surface the user actually reads.
+    await emitSchemaSkewNotice();
+    return;
+  }
 
   try {
     const now = new Date();

package/install.mjs

@@ -61,6 +61,7 @@ import {
   scanPluginCacheHookPollution,
   hasInstallManagedHooks,
   pluginCacheHookEvents,
+  settingsHookCommands,
 } from './plugin-cache-guard.mjs';
 import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
 import {
@@ -69,6 +70,7 @@ import {
   nativeBindingRepairHint,
 } from './lib/binding-probe.mjs';
 import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
+import { probeSchemaCompat, schemaSkewRemedy } from './lib/schema-skew.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
 import { ORPHAN_EPISODE_AGE_MS } from './lib/time-constants.mjs';
@@ -266,6 +268,59 @@ export function buildDoctorSummary(issues, warnings) {
   return `${issues} issue(s) found.${warnSuffix}`;
 }
 
+/**
+ * How many LIVE hook commands invoke `bash`, and which scripts they are.
+ *
+ * There are two hook registrations and only one is live per install shape, which is what
+ * the first cut of doctor's interpreter check got wrong (pre-ship review P1-1). The plugin
+ * shape reads `hooks/hooks.json` out of the plugin cache. The npm / npx / `git clone` shape
+ * has no such file — `hooks/hooks.json` is in RELEASE_SIGNED_FILES but NOT in SOURCE_FILES,
+ * so nothing deploys it to ~/.claude-mem-lite/ — and registers its hooks in settings.json
+ * instead. Reading only the manifest therefore answered "zero bash hooks" on the one shape
+ * where two of them are live.
+ *
+ * Returns THREE outcomes, never two. `count: null` means no registration could be read, and
+ * that is deliberately distinct from a count of zero: zero is an answer, null is the absence
+ * of one, and a diagnostic that reports them identically tells the reader to stop looking.
+ *
+ * @param {{manifestPath: string, settingsCommands?: string[], installDir: string}} opts
+ * @returns {{count: number|null, source: 'manifest'|'settings'|null, scripts: string[]}}
+ */
+export function resolveBashHookCount({ manifestPath, settingsCommands = [], installDir }) {
+  const basenames = (commands) =>
+    commands
+      .map((c) => {
+        const m = c.match(/([^/"\s]+\.sh)/);
+        return m ? m[1] : c;
+      })
+      .sort();
+
+  if (existsSync(manifestPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      const commands = [];
+      for (const matchers of Object.values(parsed?.hooks || {})) {
+        for (const m of matchers || []) {
+          for (const h of m?.hooks || []) commands.push(String(h?.command || ''));
+        }
+      }
+      const bash = commands.filter((c) => c.startsWith('bash '));
+      return { count: bash.length, source: 'manifest', scripts: basenames(bash) };
+    } catch {
+      // A torn manifest is not evidence of zero bash hooks. Fall through to settings.json,
+      // and if that says nothing about us either, the caller gets null.
+    }
+  }
+  // Only OUR entries: settings.json is shared with every other tool the user installs, so a
+  // foreign `bash "…"` line is not ours to report on, and — the discriminating half — a
+  // settings.json that names nothing of ours is not evidence that no hook needs bash. It is
+  // evidence we are reading the wrong registration.
+  const ours = settingsCommands.filter((c) => c.includes(installDir));
+  if (ours.length === 0) return { count: null, source: null, scripts: [] };
+  const bash = ours.filter((c) => c.startsWith('bash '));
+  return { count: bash.length, source: 'settings', scripts: basenames(bash) };
+}
+
 // Dev installs symlink server.mjs → the project's source file. Used to suppress
 // misleading "first run" messages since hook-update.mjs skips state-writes in
 // this mode (see hook-update.mjs isDevMode).
@@ -1425,6 +1480,73 @@ async function doctor() {
     }
   }
 
+  // Can each code home actually OPEN this database? A binding that loads is not the same
+  // question: better-sqlite3 can be perfect and the store still unreadable, because
+  // schema.mjs refuses a DB written by a newer claude-mem-lite (correctly — replaying old
+  // migrations over a newer layout would corrupt it). That is a one-way ratchet, and on a
+  // plugin install it is REACHED ROUTINELY: the cache only advances when Claude Code's
+  // marketplace updater advances it, so anything else that opens the DB — an npm-global
+  // CLI, a dev checkout — can leave the cache locked out. Measured 2026-09-08: DB v49 vs a
+  // live 5.6.0 cache supporting v48, >=648 identical hook errors in one day, and the only
+  // user-visible signal was `-32000 Connection closed` from the MCP host.
+  //
+  // Probed per root, out of process, exactly like the binding check above and for the same
+  // reason: this is the check that has to survive answering the question, and importing
+  // another tree's schema.mjs would poison the process that must report the answer. It is
+  // also why this check is USEFUL TODAY rather than only after the next upgrade — doctor
+  // runs from whichever tree the user invoked, so new code here can diagnose an old cache.
+  if (!existsSync(DB_PATH)) {
+    ok('DB schema: no database yet — nothing to compare');
+  } else if (rootProbes.length === 0) {
+    // The fourth outcome the first cut had and did not print. The `fail` above already tells
+    // the reader no install owns a binding, but a block whose stated design point is "three
+    // outcomes, never two" must not answer a fourth case with silence.
+    dwarn('DB schema: not checked — no install on this machine owns a native binding to read it with');
+  } else {
+    const compat = probeSchemaCompat(shape.runtimeRoots, DB_PATH);
+    const behind = compat.filter((c) => c.status === 'skew');
+    const unknown = compat.filter((c) => c.status === 'unknown');
+    if (behind.length === 0 && unknown.length === 0) {
+      ok(`DB schema: v${compat[0]?.dbVersion} — readable by all ${compat.length} install(s)`);
+    }
+    if (behind.length > 0) {
+      // Dynamic: only a skewed machine pays for it, and it reuses hook-update's isDevMode
+      // rather than re-deriving "is this a checkout", which that file has already had to
+      // correct twice (whole-dir symlink, then per-file drift).
+      let dev = false;
+      try {
+        const { isDevMode } = await import('./hook-update.mjs');
+        dev = isDevMode();
+      } catch {
+        /* unreadable → the initialiser stands: a non-dev install gets the common remedy */
+      }
+      for (const b of behind) {
+        // PER ROOT, inside the loop. Computing one remedy for every skewed tree printed the
+        // machine's global answer beneath a label naming a different tree — on a mixed
+        // managed+plugin install that meant `self-update` under "plugin cache v5.6.0",
+        // which advances nothing. b.root is the tree that is actually behind.
+        const remedy = schemaSkewRemedy({
+          managed: shape.managed,
+          activePluginVersion: shape.activePluginVersion,
+          dev,
+          root: b.root,
+        });
+        // fail, not warn: every write path is dead in this state and only the user can fix it.
+        fail(`DB schema v${b.dbVersion} is newer than ${b.label}, which supports up to v${b.supported}`);
+        for (const c of remedy.commands) log(`    ${c}`);
+        if (remedy.note) log(`    ${remedy.note}`);
+        issues++;
+      }
+    }
+    for (const u of unknown) {
+      // Deliberately its own outcome. "I could not determine what this install supports"
+      // printed as a green line is the defect the v6.2.0 round wrote and its pre-ship review
+      // caught before the tag — a check that says "nothing to check" and "I could not look"
+      // in the same voice ends the reader's search instead of directing it.
+      dwarn(`DB schema: could not determine compatibility for ${u.label} (${u.error})`);
+    }
+  }
+
   try {
     await import('@modelcontextprotocol/sdk/server/mcp.js');
     ok('@modelcontextprotocol/sdk: verified (import OK)');
@@ -1865,6 +1987,68 @@ async function doctor() {
     dwarn('Hook scripts: check failed — ' + e.message);
   }
 
+  // Hook interpreter. Some hook commands are `bash "<script>"` (the PostToolUse and
+  // Agent prefilters, plus setup.sh in the plugin manifest) — the rest are `node`. If bash
+  // cannot run, those commands fail and nothing says so; the check above grades whether the
+  // FILES are present, which they are.
+  //
+  // Keyed on whether bash runs, not on process.platform === 'win32'. A Windows user with
+  // Git for Windows on PATH — the normal case, since Claude Code shells out to bash for its
+  // own Bash tool — has a working configuration and must not be warned; a stripped
+  // container with no bash has a broken one and must be, whatever its platform. This is
+  // also what issue #28's P3-19 intent asked for: `os: [darwin, linux]` was added so a
+  // Windows user "should be told rather than handed a string of silent catch blocks", and
+  // blocking the install told them nothing. This is the telling.
+  try {
+    const {
+      count: bashCommands,
+      source: countSource,
+      scripts: bashScripts,
+    } = resolveBashHookCount({
+      manifestPath: join(PROJECT_DIR, 'hooks', 'hooks.json'),
+      settingsCommands: settingsHookCommands(homedir()),
+      installDir: INSTALL_DIR,
+    });
+    if (bashCommands === null) {
+      // NOT `ok`. Pre-ship review (P1-1) found the first cut printing "no hook command needs
+      // bash" here, on a shape where two of them are registered — a green line that ends the
+      // reader's search is worse than the silence this check exists to remove.
+      dwarn(
+        'Hook interpreter: could not read either hook registration — neither ' +
+          `${join(PROJECT_DIR, 'hooks', 'hooks.json')} nor a claude-mem-lite entry in ` +
+          `${join(homedir(), '.claude', 'settings.json')} — so whether any hook needs bash is unknown.`,
+      );
+    } else if (bashCommands === 0) {
+      ok(`Hook interpreter: no hook command needs bash (per the ${countSource})`);
+    } else {
+      let bashOk = false;
+      try {
+        execFileSync('bash', ['-c', 'exit 0'], { stdio: 'ignore', timeout: 5000 });
+        bashOk = true;
+      } catch {
+        /* not resolvable, or not runnable — either way the hooks that need it cannot fire */
+      }
+      if (bashOk) {
+        ok(`Hook interpreter: bash present (${bashCommands} hook command(s) need it)`);
+      } else {
+        // dwarn, not an issue: everything else works. Saying "broken" about an install
+        // whose MCP server and node hooks are fine would be the mirror of the defect that
+        // sent this round's reporter looking at their disk and their network.
+        // The scripts are NAMED from the live registration rather than described from
+        // memory — the first cut wrote "(episode Read-tracking and the subagent prefilter)",
+        // a two-item gloss on a count of three (P3-1).
+        dwarn(
+          `Hook interpreter: bash not found on PATH — the ${bashCommands} hook command(s) that ` +
+            `invoke it cannot fire (${bashScripts.join(', ')}). The MCP server and the node ` +
+            'hooks are unaffected. On Windows, install Git for Windows or use WSL; elsewhere ' +
+            'this means a stripped PATH.',
+        );
+      }
+    }
+  } catch (e) {
+    dwarn('Hook interpreter: check failed — ' + e.message);
+  }
+
   // Stale temp files
   try {
     // hook-update + the episode workers write runtime/ + staging under DB_DIR

package/lib/platform-gate.mjs

@@ -0,0 +1,87 @@
+// lib/platform-gate.mjs — is THIS platform inside the `os` list package.json declares?
+//
+// Why this is a module and not four lines inside scripts/launch.mjs, which is its only
+// consumer: launch.mjs cannot be imported. Its top level installs dependencies, probes the
+// native binding and then imports the MCP server, so a test that imported it would start a
+// server. The alternative to a real import is a source-text scan of launch.mjs, which this
+// repo has repeatedly found to be walkable — a guard that greps for a string passes for a
+// change that keeps the string and deletes the behaviour. So the predicate lives here where
+// tests can drive it, and launch.mjs keeps the wording and the exit.
+//
+// `os` is an npm INSTALL GATE, evaluated against the ROOT package being installed. npm
+// rejects with EBADPLATFORM before it resolves anything, which is why a platform left off
+// the list does not degrade — it fails the install outright, and in plugin mode that install
+// is on the path of every first MCP launch after an update (issue #28).
+//
+// Node built-ins only: this runs BEFORE `npm install`, so node_modules may not exist yet.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * npm's own `checkList` from npm-install-checks, reproduced rather than approximated.
+ *
+ * The rule is not "is it in the list": an entry may be NEGATED with `!`, and a list of
+ * nothing but negations allows every platform it does not name. `list.includes(platform)`
+ * agrees with npm on the simple case and disagrees on `["!win32"]` — where it would tell a
+ * linux user their platform is unsupported while npm installs happily. A diagnostic that is
+ * wrong in that direction is worse than none.
+ *
+ * @param {string[]|string} list The `os` value as declared.
+ * @param {string} platform A `process.platform` value.
+ * @returns {boolean} True when npm would allow the install.
+ */
+export function platformAllowed(list, platform) {
+  const entries = typeof list === 'string' ? [list] : list;
+  if (!Array.isArray(entries)) return true;
+  if (entries.length === 1 && entries[0] === 'any') return true;
+  let negated = 0;
+  let match = false;
+  for (const entry of entries) {
+    const negate = typeof entry === 'string' && entry.startsWith('!');
+    const test = negate ? entry.slice(1) : entry;
+    if (negate) {
+      negated++;
+      if (platform === test) return false;
+    } else if (platform === test) {
+      match = true;
+    }
+  }
+  // An all-negation list (and, by the same arithmetic, an empty one) allows anything it
+  // has not vetoed above.
+  return match || negated === entries.length;
+}
+
+/**
+ * The `os` list `<root>/package.json` declares, or null when there is nothing to enforce.
+ *
+ * Fails OPEN on every error. A missing or torn package.json is the incomplete-install case
+ * that launch-preflight.mjs already diagnoses with a repair command; turning it into a
+ * platform complaint here would replace a good message with a wrong one.
+ *
+ * @param {string} root Directory holding package.json.
+ * @returns {string[]|null}
+ */
+export function readDeclaredPlatforms(root) {
+  const p = join(root, 'package.json');
+  if (!existsSync(p)) return null;
+  try {
+    const os = JSON.parse(readFileSync(p, 'utf8'))?.os;
+    if (typeof os === 'string') return [os];
+    return Array.isArray(os) ? os : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Would npm refuse to install this package on this platform?
+ *
+ * @param {{root: string, platform?: string}} opts
+ * @returns {{blocked: boolean, declared: string[]|null, platform: string}}
+ */
+export function platformGate({ root, platform = process.platform }) {
+  const declared = readDeclaredPlatforms(root);
+  if (declared === null) return { blocked: false, declared: null, platform };
+  return { blocked: !platformAllowed(declared, platform), declared, platform };
+}