dsh-engram 0.9.0 → 0.9.1

package/README.md

@@ -1269,9 +1269,12 @@ Defaults are token-conscious; override any key via the profile patch
 ## Development
 
 ```sh
-npm test            # 381 tests: core + web API + GC + usage-observability + Context GC + ESR triggers + BoundaryPrune + preference learning + Context Ledger + JIT push (node:test)
+npm test            # 532 tests: core + web API + GC + usage-observability + Context GC + ESR triggers + BoundaryPrune + preference learning + Context Ledger + JIT push (node:test)
 npm run eval        # offline recall + structure benchmark (deterministic)
 npm run build:client
+npm run host:probe  # boot a throwaway real dsh host and assert the compaction engine's
+                    # pressure path end to end (no model call; --gc for GC mode, --tgz <old>
+                    # for the regression control) — issues #12/#13
 ```
 
 ### Testing & evaluation (two layers of real testing)

package/docs/RELEASE-NOTES-v0.9.1.md

@@ -0,0 +1,112 @@
+# dsh-engram v0.9.1
+
+**两个「自己说自己活着」的部件：一个在 Windows 上从第一次启动起就没亮过，一个接管了
+本机 compaction 却一次也没压缩过。**
+
+从 `v0.9.0` 到这里只有两个 commit，修的是同一类故障——**状态面显示正常，功能面从未发生**。
+这类故障单测抓不到，因为它不是逻辑错了，而是两个面用的键、或者两个面用的上下文不一致：
+写的时候用了一套，读/挂的时候用了另一套。两次都是先有人在真实环境里看见「那个东西没出现」，
+才回头找到这条缝。
+
+## 修复
+
+### 1. `[ENGRAM]` 块在 Windows 上恒为空（issue #10）
+
+`blockFor` / `esrBlockFor` 用裸 `path.resolve(cwd)` 推会话工作区，而所有写入路径——以及
+渲染调用下面两行的账本——用的是 `workspaceKey()`。win32 上写入端会把整个 key 小写
+（盘符默认大写），于是原始 key 匹配到 0 行：`[ENGRAM]` 渲染成空串，`sessionCache` 再把
+空串冻住整场会话，看起来像「记忆库是空的」。
+
+`[RESUME]` 与 `[ESR]` 快照/冻结块是同一个第二 key 派生，一起修。三处调用点现在共用
+`wk(cwd)`，`lib/index.js` 不再 import `node:path`——没有第二条派生路可走。
+`test/workspace-key.test.mjs` 不依赖 Windows 主机也能复现这对键，另外用源码不变量把调用点
+锁住。
+
+### 2. 宿主面 compaction 引擎从未真正挂上（issues #12 / #13）
+
+`BasicCompactionEngine` 声明 `static inject = ["llm", "tokenMeter", "sessions"]`，但
+`static inject` 只有被 loader **当插件加载**时才转成供给好的依赖图。`mountCompactionEngine`
+用的是 `new Engine(ctx)`，而且这个 `ctx` 来自 engram 自己那条 `inject = ["tools"]` 的 fiber，
+于是 `compactIfNeeded()` 的第一句 `this.ctx.tokenMeter` 直接从 ctx 代理里抛
+`cannot get property "tokenMeter" without inject`——可选链救不了，getter 本身在抛。
+
+两个后端把同一条错误吞成了两种表情：
+
+- 注册 `agent/request(prepend)` 的后端 → 错误冒到模型切换上，界面提示
+  "select a model with a larger context window"（误导，跟模型大小无关）；
+- 在 `agent/pre-step` 里读的后端 → 被 catch 成 `step compaction failed … continuing the turn`，
+  引擎挂着、`context-gc.status.json` 一直写着 `host: "context-gc"`、却从不压缩。
+
+现在 `mountCompactionEngine` 改为 `ctx.plugin(Engine)`，两个子类都接
+`constructor(engineCtx = ctx)`，loader 在引擎自己的 fiber 上供给三个服务；engram 自身仍只
+inject `["tools"]`，minimal/headless profile 不因此多背依赖。
+
+顺手处理的三个坑（都有测试钉住）：
+
+- **`fiber.await()` 不是就绪信号**：inject 缺失时 fiber 从不启动，`await()` 立即 resolve
+  且 resolve 的是 undefined。改成等引擎自身构造的回调；宿主永不供给服务时挂载保持 pending，
+  `lib/index.js` 用 15s 上界把 `host: "unavailable"` 写进 status 并 warn 一行，不再静默。
+- **重复 provider 必须在挂载前拦**（`ctx.get("compaction") !== undefined` → 抛）。否则 cordis
+  从 fiber 内部拒绝并 `logger.error` 打栈，而「base 的 `compaction-basic` 行还启用着」本是
+  设计内的情况，不是事故。
+- **错误路径**：`MountedEngine` 里 `try { super() } catch (e) { settle.reject(e); throw e }`，
+  否则构造失败会让挂载静默挂死（内部 `catch {}` 把异常吃了）。
+
+## 这次怎么验的
+
+单测跑的是真 cordis + 真 backend（`test/compaction-mount.test.mjs`，含两个反向对照：
+一个断言 `compactIfNeeded()` 确实经注入的 meter 实测，一个保留 `new` 的做法仍复现原报错）。
+但「真 backend」还不是「真宿主」，所以补了一次真机探针：
+
+**做法** —— 把本仓库 `npm pack` 成 tarball，在 `/tmp` 里起一个一次性 `DSH_HOME`，用
+`dsh --from-default-profile web` 造 profile，`dsh plugin --profile probe add <tgz>` 装上，
+再用一份 overlay patch 插一个只做一件事的探针插件：启动 8 秒后调
+`ctx.compaction.compactIfNeeded(agent, "pressure")`，把结果写进文件；`dsh --port 3199 web`
+起真宿主，读文件。这套流程已固化成 `npm run host:probe`（`scripts/host-mount-probe.mjs`，
+`--gc` 切 GC 模式、`--tgz <old.tgz>` 当对照；不联网、不调模型，退出码 0 = 通 / 1 = 引擎报错）——
+下面这张表的每一行都能用一条命令重跑。
+
+**读数**（`dsh 0.2.1-rc.2`，本机）：
+
+| 装上的是 | `status.host` | `compactIfNeeded("pressure")` |
+|---|---|---|
+| 本版（fixed，默认配置） | `default` | `ok: true`，`null`（空会话无需压缩） |
+| 本版（fixed，`gcReplacesCompaction: true`） | `context-gc` | `ok: true`，`null` |
+| 父提交 `42a9552`（对照） | `default` | `ok: false` —— `cannot get property "tokenMeter" without inject` |
+
+第三行是关键：同一套探针、同一个宿主，把插件换回父提交的 tarball，原报错原样复现。也就是说
+前两行的绿不是「没测到那条路」，是那条路真的通了。
+
+## 其他
+
+- 贡献者 PR #11（客户端 i18n + 俄语目录，457 条）已在本机全量验证（合并无冲突、`build:client`
+  与提交产物逐字节一致、527/525 只有本机 fence 失败），但**不在本版**：它改的是 `client/`，
+  等 review 合并后再发。
+- 配置键与数据格式与 `0.9.0` / `0.8.8` 完全一致，**无需迁移**。
+
+## DSH 版本支持
+
+- **支持的 DSH 范围**：`>=0.1.2-alpha.2 <0.3.0-0`
+- **peer 声明**：
+  - `@deepseek-ai/dsh-compaction`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-compaction-basic`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-llm`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-settings`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-storage-domain`: `>=0.1.2-alpha.2 <0.3.0-0`
+- **验证版本**：`dsh 0.2.1-rc.2`（本机 CLI + web；宿主面 compaction 挂载另用一次性 profile 实测，
+  见上）
+- **最后验证日期**：2026-11-09
+- **安装方式已验证**：`dsh plugin --profile <name> add <tgz|dsh-engram>`
+
+## 验证
+
+```
+npm test          → 532 tests, 530 pass
+                    （2 个失败仅 test/g6-sandbox.test.mjs：需要 OS 级 fence，本机没有，
+                      父提交上同样失败）
+npm run typecheck → ok
+npm run build:client → 无 diff（bundle 新鲜）
+npm run prepublishOnly → packed tarball 里 host + client bundle 双入口 import OK
+npm pack          → 476.8 kB / 96 files（client bundle 298476 bytes）
+npm run host:probe → exit 0（`--tgz <父提交 tarball>` 复跑：exit 1，原报错）
+```

package/lib/context-gc.js

@@ -660,6 +660,25 @@ export function buildContextGcSummary(report, context, { turns, narrative }) {
   return parts.join("\n");
 }
 
+/**
+ * Services `BasicCompactionEngine` reads straight off `this.ctx`:
+ * `tokenMeter.measure()` on every pressure check, `sessions.flush()` on a manual
+ * compaction, `llm.resolveModelInfo()` for the model's context window.
+ *
+ * These are declared by the backend's own `static inject`, and that static only
+ * takes effect when the class is loaded as a PLUGIN. Until this fix the mount
+ * used `new Engine(ctx)` — no loader, no fiber, no provisioning — so the first
+ * `this.ctx.tokenMeter` threw `cannot get property "tokenMeter" without inject`
+ * out of cordis's context proxy. The engine's own
+ * `ctx?.on(...)` listeners kept working (events are root-wide), which is why the
+ * breakage looked like "compaction silently does nothing" on one backend
+ * version and "model switch rejected" on another (issues #12/#13).
+ *
+ * Mounted through `ctx.plugin(Engine)` the loader provisions exactly this list
+ * on the engine's own fiber, so the reads resolve for real.
+ */
+const ENGINE_INJECT = ["llm", "tokenMeter", "sessions"];
+
 /**
  * Load a mountable compaction engine CLASS for the host/preset plane.
  *
@@ -669,6 +688,11 @@ export function buildContextGcSummary(report, context, { turns, narrative }) {
  * base `compaction-basic` row was disabled by the profile patch, so the
  * `compaction` service never disappears while dsh-engram is installed.
  *
+ * Both subclasses take the ctx they are given (a plugin mount passes the
+ * fiber's own context — the one with {@link ENGINE_INJECT} provisioned) and
+ * fall back to the captured `ctx` so a plain `new Engine()` still works where
+ * no loader is available.
+ *
  * Returns `null` when `@deepseek-ai/dsh-compaction-basic` is not importable
  * (graceful — the host keeps whatever compaction it still has).
  */
@@ -680,14 +704,61 @@ export async function loadCompactionEngine(ctx, config = {}, deps = {}, { mode =
     // the shipped default LLM summarizer), so when the base row was disabled
     // by the profile patch the `compaction` service still exists.
     return class DefaultCompactionEngine extends mod.BasicCompactionEngine {
-      constructor() {
-        super(ctx, { auto: true, ...config });
+      static inject = [...ENGINE_INJECT];
+      constructor(engineCtx = ctx) {
+        super(engineCtx, { auto: true, ...config });
       }
     };
   }
   return loadContextGcEngine(ctx, config, deps);
 }
 
+/**
+ * Start the engine as a cordis PLUGIN, so the loader provisions the injects its
+ * backend declared (`llm`/`tokenMeter`/`sessions`) on a fiber of its own.
+ *
+ * A ctx without `plugin` (unit-test fakes, vendored hosts) gets the direct
+ * construction fallback: the engine then only sees what that ctx already
+ * exposes — the shape the unit-test fakes still construct directly.
+ */
+async function mountEngine(ctx, Engine) {
+  if (typeof ctx?.plugin !== "function") {
+    new Engine();
+    return;
+  }
+  // Refuse a second provider up front. cordis would reject it too, but only
+  // from inside the fiber — which logs a startup error for a case this module
+  // handles by design (the base `compaction-basic` row still enabled).
+  if (ctx.get?.("compaction") !== void 0) {
+    throw new Error('service "compaction" has already been registered — keeping the existing compaction service');
+  }
+  // The loader activates the fiber asynchronously, and `fiber.await()` is NOT a
+  // readiness signal: with an inject still missing the fiber never starts, yet
+  // await() resolves immediately (no in-flight lifecycle work). So the engine
+  // itself reports construction — which is exactly when the injects were
+  // provisioned and the `compaction` service registered. A rejected inject set
+  // leaves this pending, the honest state for a host that lacks the services.
+  let settle;
+  const mounted = new Promise((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  class MountedEngine extends Engine {
+    constructor(engineCtx) {
+      try {
+        super(engineCtx);
+      } catch (error) {
+        // Construction refused (duplicate provider, bad config): surface it to
+        // the caller and rethrow so cordis marks the fiber failed.
+        settle.reject(error);
+        throw error;
+      }
+      settle.resolve(true);
+    }
+  }
+  ctx.plugin(MountedEngine);
+  await mounted;
+}
+
 /**
  * Mount the compaction engine onto `ctx` — THE shared entry both planes use
  * (host plane: the main engram plugin's `apply`; preset plane: the
@@ -700,9 +771,17 @@ export async function loadCompactionEngine(ctx, config = {}, deps = {}, { mode =
  * reaches engram/ESR state for pointer classification — the caller supplies
  * its own lazy-domain binding.
  *
- * Fully contained: an unimportable backend or a duplicate `compaction`
- * provider (cordis refuses second registration) only warns and returns null —
- * the host keeps whatever compaction it already has, never a crash.
+ * The engine is mounted AS A PLUGIN (`ctx.plugin(Engine)`), never with
+ * `new Engine(ctx)`: only the loader creates the fiber that provisions the
+ * backend's `llm`/`tokenMeter`/`sessions` injects. The host plane mounts from a
+ * fiber that injects just `tools`, so constructing directly left the engine
+ * reading services its ctx was not allowed to see (issues #12/#13).
+ *
+ * Fully contained: an unimportable backend, a missing service, or a duplicate
+ * `compaction` provider (cordis refuses second registration) only warns and
+ * returns null — the host keeps whatever compaction it already has, never a
+ * crash. A host that never provides the three services leaves the mount fiber
+ * pending, so callers that report status must bound their own wait.
  *
  * @returns {Promise<Function|null>} the mounted engine class, or null.
  */
@@ -723,10 +802,11 @@ export async function mountCompactionEngine(ctx, config = {}, deps = {}) {
     return null;
   }
   try {
-    new Engine();
+    await mountEngine(ctx, Engine);
   } catch (error) {
-    // Duplicate `compaction` provider (base row not disabled) or constructor
-    // refusal: keep whatever is already registered, never crash the host.
+    // Duplicate `compaction` provider (base row not disabled), a rejected
+    // plugin load, or constructor refusal: keep whatever is already
+    // registered, never crash the host.
     ctx?.logger?.warn?.(
       `engram context-gc mount skipped (${error instanceof Error ? error.message : String(error)}) — keeping the existing compaction service`,
     );
@@ -767,8 +847,11 @@ export async function loadContextGcEngine(ctx, config = {}, deps = {}) {
   const engineConfig = { auto: true, ...config };
 
   return class ContextGcEngine extends Basic {
-    constructor() {
-      super(ctx, engineConfig);
+    /** Declared for the loader: these are read as `this.ctx.<name>` below. */
+    static inject = [...ENGINE_INJECT];
+    /** `ctx.plugin(Engine)` passes the fiber's ctx; `new Engine()` uses the captured one. */
+    constructor(engineCtx = ctx) {
+      super(engineCtx, engineConfig);
       this.gcDeps = deps;
       /** Last credit computed by `_contextGc`, surfaced in the attempt log. */
       this.gcLastCredit = void 0;

package/lib/index.js

@@ -18,7 +18,6 @@
  * `search_sessions` FTS fallback.
  */
 
-import { resolve as resolvePath } from "node:path";
 import { openEngramDomain } from "./store.js";
 import { registerTools } from "./tools.js";
 import { makeCaptureHandler } from "./capture.js";
@@ -561,7 +560,12 @@ export function apply(ctx, config) {
     let block = "";
     let pendingRecall = false;
     try {
-      const workspace = resolvePath(cwd);
+      // Read paths MUST key the store exactly like the write paths do — on
+      // win32 `workspaceKey` lowercases the whole key (drive letters are
+      // uppercase by default), so a raw `resolve(cwd)` here finds zero rows
+      // and freezes an empty [ENGRAM]/[RESUME] block for the whole session
+      // (issue #10, and the missing [RESUME] in #9).
+      const workspace = wk(cwd);
       // Anchor revalidation (v0.7-C): a bounded stat pass at session start.
       // Stale rows are tagged (for the GUI/GC) and excluded from the render
       // below via memoryIsStale — never deleted, still re-fetchable.
@@ -659,7 +663,7 @@ export function apply(ctx, config) {
     let snapshot = esrSnapshotCache.get(session);
     if (snapshot === void 0) {
       try {
-        snapshot = buildEsrSnapshot(opened, resolvePath(cwd), resolved, { sessionId: session.id });
+        snapshot = buildEsrSnapshot(opened, wk(cwd), resolved, { sessionId: session.id });
       } catch (error) {
         log?.warn?.(`engram esr render failed: ${String(error)}`);
         return "";
@@ -673,7 +677,7 @@ export function apply(ctx, config) {
     }
     let block = "";
     try {
-      block = buildFrozenEsrBlock(opened, resolvePath(cwd), resolved, {
+      block = buildFrozenEsrBlock(opened, wk(cwd), resolved, {
         recorder,
         sessionId: session.id,
         holder,
@@ -792,6 +796,22 @@ export function apply(ctx, config) {
         service.compactionStatus.host = "unavailable";
         flushStatus();
       });
+    // The engine is mounted as a plugin so the loader provisions its
+    // `llm`/`tokenMeter`/`sessions` injects (issues #12/#13). A host that never
+    // provides them leaves that fiber pending forever, which would keep
+    // `hostSettled` false and the status file unwritten — the same "wiring run
+    // that never finished" the web plane's timer below exists to avoid. Bound
+    // the wait and report the missing deps instead of staying silent.
+    const hostStatusTimer = setTimeout(() => {
+      if (hostSettled) return;
+      hostSettled = true;
+      service.compactionStatus.host = "unavailable";
+      ctx?.logger?.warn?.(
+        "engram context-gc: compaction mount still pending after 15s — this host does not provide llm/tokenMeter/sessions to the engine; the host keeps its own compaction",
+      );
+      flushStatus();
+    }, 15_000);
+    hostStatusTimer.unref?.();
 
     // Web-plane auto-wiring (Context GC): web sessions resolve `compaction`
     // inside the agent preset's own realm, which a profile patch cannot reach.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-engram",
   "description": "Minimalist long-term memory for DeepSeek Harness, distilling symbolic-index + pi-esr ideas: zero-LLM auto-capture, a symbolic [ENGRAM] index with progressive disclosure, and an ESR-lite evidence-closure protocol (esr_task / esr_node / esr_close / esr_link). Real agent-behaviour telemetry (usage rollup + /stats) and a deterministic offline recall benchmark (npm run eval). Hot path is model-free; storage on ctx.storageDomain; web memory viewer, observability panel and config card through DSH's native settings slots.",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "packageManager": "pnpm@11.22.0",
   "license": "MIT",
   "repository": {
@@ -46,6 +46,7 @@
     "dsh-engram:doctor": "node scripts/dsh-engram.mjs doctor",
     "eval": "node eval/recall-bench.mjs",
     "gate:audit": "node eval/gate-audit.mjs",
+    "host:probe": "node scripts/host-mount-probe.mjs",
     "playbook:audit": "node eval/playbook-audit.mjs",
     "prepublishOnly": "node scripts/prepublish-check.mjs",
     "quality:ab": "node eval/quality-ab.mjs",

package/scripts/host-mount-probe.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * 宿主面 compaction 挂载的真机探针（issues #12/#13 的回归证据）。
+ *
+ * 单测的「真 cordis + 真 backend」已经能复现那条缝，但它证明不了「真 dsh 宿主会把
+ * llm/tokenMeter/sessions 供给到引擎自己的 fiber 上」。这个脚本把那次一次性验证
+ * 固化成一条命令：
+ *
+ *   1. `npm pack` 本仓库（或 --tgz 指定的 tarball）
+ *   2. 在 mkdtemp 出来的 DSH_HOME 里，用 `--from-default-profile web` 造一个一次性
+ *      profile，`dsh plugin add` 装上被测 tarball
+ *   3. 再装一个只做一件事的探针插件：boot 后 8s 调
+ *      `ctx.compaction.compactIfNeeded(agent, "pressure")`，把结果写进 JSON
+ *   4. `dsh --profile probe --patch <overlay> --port <n> --no-open` 起真宿主
+ *   5. 读 JSON、杀进程、按结果给退出码
+ *
+ * 用法：
+ *   node scripts/host-mount-probe.mjs                 # 本仓库，默认配置
+ *   node scripts/host-mount-probe.mjs --gc            # gcReplacesCompaction: true
+ *   node scripts/host-mount-probe.mjs --tgz old.tgz   # 对照：装上旧 tarball 应复现报错
+ *   node scripts/host-mount-probe.mjs --port 3199 --keep
+ *
+ * 退出码：0 = pressure 路径跑通；1 = 引擎报了 inject 错；2 = 没拿到读数（boot 失败）。
+ * 不联网、不调模型：只 boot 宿主，不跑任何会话。
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DSH_BIN = process.env.PROBE_DSH_BIN || "dsh";
+
+function arg(name, fallback = undefined) {
+  const i = process.argv.indexOf(name);
+  return i === -1 ? fallback : process.argv[i + 1] ?? fallback;
+}
+const GC_MODE = process.argv.includes("--gc");
+const KEEP = process.argv.includes("--keep");
+const PORT = Number(arg("--port", "3199"));
+const TGZ = arg("--tgz");
+const WAIT_MS = Number(arg("--wait", "60000"));
+
+function sh(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...opts });
+}
+
+function packRepo(dest) {
+  mkdirSync(dest, { recursive: true });
+  const out = sh("npm", ["pack", "--pack-destination", dest], { cwd: ROOT });
+  const name = out.trim().split("\n").at(-1).trim();
+  return join(dest, name);
+}
+
+/** The probe plugin: no config, no deps, one timer, one write. */
+const PROBE_SOURCE = `import fs from "node:fs";
+export const name = "engram-host-probe";
+export const inject = ["compaction"];
+const OUT = process.env.PROBE_OUT;
+export function apply(ctx) {
+  const timer = setTimeout(async () => {
+    const result = { at: new Date().toISOString(), pid: process.pid };
+    try {
+      const status = JSON.parse(fs.readFileSync(process.env.DSH_HOME + "/engram/context-gc.status.json", "utf8"));
+      result.host = status.host;
+      result.config = status.config;
+    } catch (error) { result.statusError = String(error?.message ?? error); }
+    try {
+      const agent = {
+        session: {
+          id: "probe-session",
+          header: { cwd: "/tmp" },
+          messages: [],
+          events: [],
+          requestHeader: () => ({ config: { provider: "deepseek-official", model: "deepseek-flash" } }),
+        },
+        options: {},
+      };
+      const out = await ctx.compaction.compactIfNeeded(agent, "pressure", new AbortController().signal);
+      result.pressure = { ok: true, result: out ?? null };
+    } catch (error) {
+      result.pressure = { ok: false, error: String(error?.message ?? error) };
+    }
+    fs.writeFileSync(OUT, JSON.stringify(result, null, 1));
+  }, 8000);
+  ctx.effect(() => () => clearTimeout(timer));
+}
+`;
+
+const PROBE_PKG = JSON.stringify(
+  { name: "dsh-engram-host-probe", version: "1.0.0", private: true, type: "module", main: "index.js", files: ["index.js"] },
+  null,
+  1,
+);
+
+function packProbe(dest) {
+  const src = join(dest, "probe-src");
+  mkdirSync(src, { recursive: true });
+  writeFileSync(join(src, "index.js"), PROBE_SOURCE);
+  writeFileSync(join(src, "package.json"), PROBE_PKG);
+  const out = sh("npm", ["pack", "--pack-destination", dest], { cwd: src });
+  return join(dest, out.trim().split("\n").at(-1).trim());
+}
+
+function overlay(file, gc) {
+  writeFileSync(
+    file,
+    [
+      "# one-off overlay: the probe row, plus the GC-mode config when asked",
+      gc ? "- id: engram\n  config:\n    gcReplacesCompaction: true" : "# (default config)",
+      "- insert:\n    - id: engram-host-probe\n      name: dsh-engram-host-probe",
+      "",
+    ].join("\n"),
+  );
+}
+
+const home = mkdtempSync(join(tmpdir(), "engram-host-probe-"));
+const outFile = join(home, "probe.json");
+const env = { ...process.env, DSH_HOME: home, PROBE_OUT: outFile };
+let child;
+let exitCode = 2;
+
+try {
+  const tgz = TGZ ? resolve(TGZ) : packRepo(join(home, "pkg"));
+  if (!existsSync(tgz)) throw new Error(`tarball not found: ${tgz}`);
+  console.log(`plugin: ${tgz}`);
+
+  sh(DSH_BIN, ["--profile", "probe", "--from-default-profile", "web", "--dump-config"], { env });
+  sh(DSH_BIN, ["plugin", "--profile", "probe", "add", tgz], { env, stdio: ["ignore", "pipe", "inherit"] });
+  sh(DSH_BIN, ["plugin", "--profile", "probe", "add", packProbe(join(home, "probe-tgz"))], {
+    env,
+    stdio: ["ignore", "pipe", "inherit"],
+  });
+
+  const patch = join(home, "probe.patch.yml");
+  overlay(patch, GC_MODE);
+
+  console.log(`booting dsh ${GC_MODE ? "(gcReplacesCompaction: true) " : ""}on :${PORT} …`);
+  child = spawn(
+    DSH_BIN,
+    ["--profile", "probe", "--patch", patch, "--port", String(PORT), "--no-open"],
+    { env, detached: true, stdio: ["ignore", "pipe", "pipe"] },
+  );
+  let log = "";
+  child.stdout.on("data", (d) => (log += d));
+  child.stderr.on("data", (d) => (log += d));
+
+  const deadline = Date.now() + WAIT_MS;
+  while (Date.now() < deadline && !existsSync(outFile)) {
+    await new Promise((r) => setTimeout(r, 1500));
+  }
+
+  if (!existsSync(outFile)) {
+    console.error(`no reading after ${WAIT_MS}ms — host log tail:\n${log.slice(-2000)}`);
+  } else {
+    const result = JSON.parse(readFileSync(outFile, "utf8"));
+    console.log(JSON.stringify(result, null, 1));
+    exitCode = result.pressure?.ok === true ? 0 : 1;
+  }
+} finally {
+  if (child?.pid) {
+    try {
+      process.kill(-child.pid, "SIGTERM");
+    } catch {}
+  }
+  if (!KEEP) rmSync(home, { recursive: true, force: true });
+  else console.log(`kept ${home}`);
+}
+
+process.exit(exitCode);