@avantf/dsh-mem 0.8.1 → 0.9.0

package/lib/index.js

@@ -12,9 +12,9 @@ import { createHash, randomBytes } from "node:crypto";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { brotliCompressSync, brotliDecompressSync, constants, gunzipSync, gzipSync } from "node:zlib";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import { fileURLToPath, pathToFileURL } from "node:url";
 //#region ../contract/lib/types.js
 /** Shared domain types for avantf-mem. Single source of truth in @avantf/mem-contract. */
 /**
@@ -174,6 +174,186 @@ const DEGRADED_LEG_NOTE = "本次仅词法腿，语义腿未就绪（语义后
 * with no error, so the adapter bounds the text first and warns once (DESIGN §20).
 */
 const maxInputTokens = z.number().int().nonnegative().default(0);
+/**
+* One registry/cache endpoint a self-heal section's attempts may name.
+*
+* SHARED by `semantic.self_heal` (transformers.js) and `semantic.native_self_heal` (the native
+* packages): the base `runtime-deps` provider takes ONE source vocabulary, and two spellings of it
+* would be two ways to get the same install wrong.
+*
+* Mirrors the provider's `DependencySource` (interface v5) without importing it: this package is
+* also used by the CLI/MCP processes, which never load the base. An empty `cache` on a source with
+* no registry means "the family root's npm cache" — the plugin fills in `<home>/cache/npm` when it
+* builds the item, because this schema does not know the family root.
+*/
+const selfHealSourceSchema = z.object({
+	id: z.string().min(1),
+	registry: z.string().default(""),
+	cache: z.string().default("")
+});
+/**
+* One install attempt, in the base provider's vocabulary. SHARED by both self-heal sections.
+*
+* `env` exists mainly for `ONNXRUNTIME_NODE_INSTALL=skip`: `onnxruntime-node`'s postinstall download
+* returns 302 on some mirrors, and skipping that check is enough for transformers.js to load its
+* WASM/CPU fallback.
+*
+* `allowScripts` is explicit in this plugin's defaults: the base provider defaults it to `false`
+* (lifecycle scripts from a registry package are a caller decision), and `onnxruntime-node` needs its
+* postinstall unless the attempt sets `ONNXRUNTIME_NODE_INSTALL=skip`. Leaving it unset here would
+* turn every default attempt into an `--ignore-scripts` install and break the native binary. The same
+* holds — more strongly — for the native section: `nodejieba` and `hnswlib-node` are node-gyp builds
+* whose ONLY artefact is produced by the install script.
+*/
+const selfHealAttemptSchema = z.object({
+	source: z.string().min(1),
+	manager: z.enum(["npm", "pnpm"]).optional(),
+	env: z.record(z.string(), z.string()).default({}),
+	allowScripts: z.boolean().optional()
+});
+/**
+* One entry of the STARTUP DEPENDENCY AUDIT (`audit:` in `res/runtime-deps.yaml`): what to observe,
+* how loud to say it, and under which condition — a session notice, plus the probe that decides
+* whether it is due.
+*
+* WHY IT IS DATA, NOT CODE. The interesting question at the end of a mount is "which of the optional
+* things this build is made of can this process actually load?" — and the set differs per RELEASE (a
+* native binding added or dropped, a mirror changed, a sentence reworded). Writing those names and
+* sentences in code would make the implementation carry a deployment's vocabulary. So the plugin
+* implements two GENERIC probe kinds, and the shipped declaration says which pieces exist and what a
+* session is told about them. No package name, body, severity or condition is written in code.
+*
+* `kind` selects the probe:
+*
+*  - `module` — resolve AND LOAD `specifier` (a `require`/`import`, so a native addon's binding is
+*    really loaded, not just found), from a ready self-heal root first and from this tree otherwise.
+*    States: `available` (loaded), `failed` (resolved, but loading it threw — the classic node-gyp
+*    build that exists and does not work), `missing` (nothing resolved).
+*  - `runtime-deps` — the STATE of the named `item` (`mem:semantic-deps`, `mem:native-deps`, or any
+*    other runtime-deps item): `available` (ready), `failed`, `missing`, `skipped`, `pending`.
+*
+* `when` is matched against that state, and the word means the same thing for both kinds:
+* `failed` → `failed`; `missing` → `missing` or `skipped`; `degraded` → any of the three. An entry
+* that is `pending` matches NOTHING: a line latched while a background install is still running would
+* outlive the success it is waiting for. (`pending` only occurs for `runtime-deps`, whose item may be
+* mid-install; a `module` probe is a single synchronous load and cannot be pending.)
+*
+* `min_vectors` (optional, `0`/omitted = every corpus) holds the line back until the live vector
+* index reaches that size — the corpus-size knob an ANN entry needs (below the switch-over point the
+* brute-force store is the intended backend, so a missing ANN binding is not a defect). It is a
+* literal in the declaration, deliberately not derived from `vectorStore.auto_thresholds.hnswlib`:
+* code that computed it would be branching on a package, which is what this section exists to avoid.
+*
+* `id` must be namespaced (`mem:…`) — it is the unit of the once-per-session latch, so an id shared
+* with another plugin would silently suppress one of the two lines. The base registry warns and
+* ignores a malformed one instead of throwing, and so this schema rejects it up front.
+*/
+const dependencyAuditFields = {
+	id: z.string().min(1),
+	severity: z.enum([
+		"info",
+		"warning",
+		"degraded"
+	]),
+	when: z.enum([
+		"failed",
+		"missing",
+		"degraded"
+	]),
+	min_vectors: z.number().int().nonnegative().optional(),
+	body: z.string().min(1)
+};
+/** One audit entry. `kind` decides which probe runs, and which of `specifier`/`item` is required. */
+const DependencyAuditEntrySchema = z.discriminatedUnion("kind", [z.object({
+	kind: z.literal("module"),
+	/** The npm specifier to load (`nodejieba`, `hnswlib-node`, `@huggingface/transformers`, …). */
+	specifier: z.string().min(1),
+	...dependencyAuditFields
+}), z.object({
+	kind: z.literal("runtime-deps"),
+	/** The runtime-deps item whose state is observed (`mem:semantic-deps`, `mem:native-deps`, …). */
+	item: z.string().min(1),
+	...dependencyAuditFields
+})]);
+/**
+* One `runtime-deps` declaration as SHIPPED WITH THE PLUGIN (`packages/plugin/res/runtime-deps.yaml`).
+*
+* WHY IT IS A RESOURCE AND NOT USER CONFIG. The package set, the sources, the attempts, the verify
+* list and the audit sentences are facts about THIS BUILD: which module the local backend imports,
+* which native bindings this release looks for, what a session should be told when one of them is
+* absent. Leaving them to `configs/common.yaml` made every deployment responsible for keeping that
+* list correct — a stale copy would install a module no code loads, or silently drop the audit — and
+* the shipped defaults were only ever the plugin's own declaration anyway. The operator keeps the one
+* thing that really is a per-deployment decision (the two `enabled` switches); the DATA travels in the
+* package, next to the code that reads it.
+*
+* Validation is strict on purpose: the file is read from the INSTALL directory at mount, and a
+* malformed one is a packaging bug. The plugin logs it and degrades (no self-heal item, no audit)
+* rather than throwing out of the mount — see `packages/plugin/src/runtime_deps_resource.ts`.
+*
+* The schema is the SINGLE definition of the file's shape: the loader validates with it, and the
+* plugin maps it to the base provider's objects field by field (the base never reads YAML).
+*/
+const RuntimeDepsResourceSchema = z.object({
+	/** Format version, so a future shape can be recognized instead of misread. */
+	version: z.literal(1),
+	/** `@huggingface/transformers` — the semantic leg's optional module. */
+	semantic: z.object({
+		packages: z.record(z.string(), z.string()),
+		sources: z.array(selfHealSourceSchema),
+		attempts: z.array(selfHealAttemptSchema),
+		verify: z.array(z.string())
+	}),
+	/** The native optional dependencies (`nodejieba`, `hnswlib-node`). */
+	native: z.object({
+		packages: z.record(z.string(), z.string()),
+		sources: z.array(selfHealSourceSchema),
+		attempts: z.array(selfHealAttemptSchema),
+		verify: z.array(z.string())
+	}),
+	/**
+	* What the startup dependency audit observes, and what a session is told. Each entry is one probe
+	* (`kind`) plus its delivery decision — see {@link DependencyAuditEntrySchema}.
+	*/
+	audit: z.array(DependencyAuditEntrySchema)
+});
+/**
+* Semantic dependency self-heal (`@huggingface/transformers` + transitive `onnxruntime-node`).
+*
+* **OFF by default** on purpose: enabling it means the plugin may run a package-manager install at
+* startup, i.e. network access before anyone asked for it. A profile that wants the repair opts in
+* (`semantic.self_heal.enabled: true`); without it the runtime keeps its existing optional-dependency
+* resolution and degrades to FTS+entity when the package is absent.
+*
+* The SPEC itself (packages / sources / attempts / verify) is NOT here: it ships in
+* `res/runtime-deps.yaml` (`RuntimeDepsResourceSchema`). This section is the operator's policy — the
+* only per-deployment decision left, because it costs a startup install.
+*/
+const semanticSelfHealSchema = z.object({ enabled: z.boolean().default(false) });
+/**
+* NATIVE dependency self-heal (`nodejieba`, `hnswlib-node`) — the optional npm dependencies whose
+* absence degrades a FEATURE rather than the plugin:
+*
+*  - `nodejieba` → POS tagging; without it entity/relation extraction falls back to a regex pass
+*    (weaker entity + jaccard legs, still functional),
+*  - `hnswlib-node` → the ANN vector index; without it queries stay on the brute-force store (exact,
+*    slower once the corpus grows).
+*
+* Both are node-gyp packages, so their shipped `attempts` allow install scripts (see
+* `res/runtime-deps.yaml`): an `--ignore-scripts` install of either produces a `require()` that fails
+* at run time, which is the one outcome a "self-heal" must not produce.
+*
+* One item, two packages, ONE store root per spec: the base's `runtime-deps` item is
+* content-addressed, so this spec (a different package set from the semantic one) lands in a
+* DIFFERENT immutable root under `<home>/deps/runtime/<key>/` — never the transformers root, whose
+* `node_modules` does not carry either native build.
+*
+* OFF by default, for the same reason as `self_heal`: enabling it means a package-manager install
+* (and a native compile) at startup. What a session is told about a missing package is an `audit`
+* entry in the same resource file, judged on the package itself and therefore working with or without
+* a repair.
+*/
+const nativeSelfHealSchema = z.object({ enabled: z.boolean().default(false) });
 const semanticSchema = z.object({
 	backend: z.string().default("local_bge"),
 	local_model: z.string().default("Xenova/bge-base-zh-v1.5"),
@@ -193,7 +373,14 @@ const semanticSchema = z.object({
 	* stay, but nothing re-encodes on its own. Set to `false` on a metered/embedded host that must not
 	* spend CPU on background re-encoding.
 	*/
-	auto_migrate: z.boolean().default(true)
+	auto_migrate: z.boolean().default(true),
+	/** Repair a missing `@huggingface/transformers` install through the base's shared runtime store. */
+	self_heal: semanticSelfHealSchema.prefault({}),
+	/**
+	* Repair a missing NATIVE optional dependency (`nodejieba` / `hnswlib-node`) through the same
+	* base mechanism, in its OWN store root (see {@link nativeSelfHealSchema}).
+	*/
+	native_self_heal: nativeSelfHealSchema.prefault({})
 });
 const vectorStoreSchema = z.object({
 	backend: z.string().default("auto"),
@@ -731,9 +918,13 @@ const NULLABLE_HIT_FIELDS = /* @__PURE__ */ new Set([
 ]);
 /**
 * The envelope a recall result carries besides its rows. Two of these are only meaningful in one
-* mode — `total`/`offset`/`limit`/`truncated` describe an EXACT page, `degraded` describes a fuzzy
-* pass — and the projection keeps whichever are present, so one function serves both shapes
-* (RECALL_INTERFACE §5).
+* mode — `total`/`offset`/`limit`/`remaining`/`truncated` describe a paged answer (`remaining` only
+* exists on a pure time window, which pages at 50), `degraded` describes a fuzzy pass — and the
+* projection keeps whichever are present, so one function serves every shape (RECALL_INTERFACE §5).
+*
+* `remaining` is here for a specific reason: "how much of the window did I not see" is a fact the
+* model must act on (narrow the window, or page on), and leaving it out left only `truncated: true`
+* with the size of the gap to be guessed.
 *
 * `weights`, `floors`, `dropped_by_floor` and `used_tokens` are the operator's diagnostics: a
 * threshold the caller cannot set and a drop count it cannot act on are pure tokens in the model's
@@ -744,6 +935,7 @@ const RESULT_ENVELOPE_FIELDS = [
 	"total",
 	"offset",
 	"limit",
+	"remaining",
 	"truncated"
 ];
 /** Copy the envelope fields a payload actually carries, in a fixed order. */
@@ -1068,9 +1260,16 @@ const TITLE_INCLUDE_EXCERPT_DESCRIPTION = "是否返回内容摘要（可选，
 * The exact page's own field descriptions. Their numbers are the documented ones (page 10, cap 50)
 * and they apply ONLY to an exact result — the fuzzy pass is a fixed shortlist of five, so a caller
 * that got no exact hit cannot page it.
+*
+* `limit`'s DEFAULT is the one place the pure time window differs: a window is a LIST, so it is
+* paged at the contract's maximum (50) instead of the exact page's ten (core `timePage`,
+* `TIME_DEFAULT_LIMIT`), and its result reports `remaining` — how much of the window the page does
+* not show. The schema's `.max(50)` is unchanged: an omitted `limit` never goes through it, so the
+* default is a number the ENGINE picks, not a value the caller could send. `titles` keeps its own
+* description (unchanged).
 */
 const SEARCH_OFFSET_DESCRIPTION = "分页偏移（从 0 开始）；可选，默认 0。只作用于分页类结果（search 的 exact/time/facts）；模糊检索不接受分页。";
-const SEARCH_LIMIT_DESCRIPTION = "返回条数上限（1-50）；可选，默认 10。只作用于分页类结果（search 的 exact/time/facts）；模糊检索固定返回 5 条。";
+const SEARCH_LIMIT_DESCRIPTION = "返回条数上限（1-50）；可选，默认 10（纯时间召回即只给 `time` 时默认 50；该方法的结果另带 `remaining`＝窗口内还有多少条未显示）。只作用于分页类结果（search 的 exact/time/facts）；模糊检索固定返回 5 条。";
 const TITLES_LIMIT_DESCRIPTION = "返回条数上限（1-50）；可选，默认 10。只作用于标题完整相等的精确结果；模糊标题检索固定返回 5 条。";
 const SEARCH_QUERY_DESCRIPTION = "检索文本（1–" + String(MAX_QUERY_CHARS) + " 字符）。已给 `time` 时可省略——只给 `time` 就是纯时间召回（`mode=time`：按 `time.field` 从新到旧，不再做字面/事实/关系/模糊检索）。";
 /**
@@ -1089,7 +1288,7 @@ const SearchRequestSchema = z.object({
 	source: z.string().optional().describe("限定来源（`fact_sources.ref`）：来源等于该值的事实才参与本次检索；可选，不参与打分（未给 = 不过滤）。"),
 	offset: z.number().int().nonnegative().optional().describe(SEARCH_OFFSET_DESCRIPTION),
 	limit: z.number().int().positive().max(50).optional().describe(SEARCH_LIMIT_DESCRIPTION),
-	max_tokens: z.number().int().nonnegative().optional().describe("本次结果的总 token 上限；0=不限制。缺省用配置 retrieval.max_output_tokens。"),
+	max_tokens: z.number().int().nonnegative().optional().describe("本次结果的总 token 上限；0=不限制。缺省：exact/facts/模糊用配置 retrieval.max_output_tokens；纯时间召回不套预算。"),
 	floors: z.enum(FLOOR_PROFILES).optional().describe(FLOORS_FIELD_DESCRIPTION),
 	include_scores: z.boolean().optional().describe(INCLUDE_SCORES_DESCRIPTION),
 	time: TimeFilterSchema.optional().describe("时间过滤（可选）：内容 ∩ 时间。硬过滤——窗口内的事实不会被窗口外的高分结果挤掉；给了它就按它，不再叠隐式时间窗。没给 `query` 时必填：时间窗就是整个问题（纯时间召回）。")
@@ -1743,7 +1942,7 @@ function warn$1(log, message) {
 		log?.warn(message);
 	} catch {}
 }
-function reasonOf$1(error) {
+function reasonOf$3(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 /**
@@ -1775,7 +1974,7 @@ async function loadGuarded(options, loadOnce, log, words) {
 	try {
 		return await loadOnce(options);
 	} catch (error) {
-		warn$1(log, `${words.prefix} WARNING — environment initialisation failed (${reasonOf$1(error)}); ${words.loadFailure}`);
+		warn$1(log, `${words.prefix} WARNING — environment initialisation failed (${reasonOf$3(error)}); ${words.loadFailure}`);
 		return;
 	}
 }
@@ -1844,6 +2043,12 @@ function stillActive(ctx) {
 * `agent/pre-step` listener), and the harness shows such a message in the trace as coming from the
 * user. Without an author, a line like "记忆里有相关内容" reads as something the user said. The
 * `[avantf-mem]` prefix is what keeps the provenance honest.
+*
+* The step's injection is not only this hint: the plugin's DEPENDENCY NOTICES (the `audit` entries of
+* the shipped `res/runtime-deps.yaml`) ride in the same message ({@link stepInjection}). They are a
+* different producer of text with the same delivery rule — at most once per owner session, only on a
+* step that already carried a user message — so merging them keeps ONE message per step instead of
+* two competing ones.
 */
 const RELEVANCE_HINT = "[avantf-mem] 记忆里有与上条用户消息相关的内容；需要时用 `mem_recall` 检索。";
 /**
@@ -1879,6 +2084,92 @@ function messageText(message) {
 		return b?.type === "text" && typeof b.text === "string" ? b.text : "";
 	}).filter(Boolean).join("\n");
 }
+/**
+* The text of the ONE message this step injects: the session notices, then the memory hint.
+*
+* `''` means "inject nothing" — the loop's turn-end guard is `decision.messages.length === 0`, so an
+* empty injection has to stay empty rather than become an empty user message.
+*
+* Order: notices first. They report a capability that is not working (a repair the operator asked for
+* did not finish), which is the louder statement; the hint is an invitation. Neither repeats within a
+* session: the notice registry latches per session id, and the hint is one line by construction.
+*
+* Each body is used AS CONFIGURED, with one exception that is about YAML and not about editing: a
+* block scalar (`body: |`) ends with a newline, and keeping it would insert a blank line between the
+* notice and the hint. Trailing whitespace is therefore dropped; nothing else is rewritten, and a
+* whitespace-only body is skipped rather than rendered as an empty paragraph.
+*/
+function stepInjection(hint, notices) {
+	const lines = [];
+	for (const line of notices) {
+		if (typeof line !== "string") continue;
+		const body = line.trimEnd();
+		if (body.trim() === "") continue;
+		lines.push(body);
+	}
+	if (hint) lines.push(RELEVANCE_HINT);
+	return lines.join("\n");
+}
+/**
+* The session-notice lines for this step, or `[]` when there are none to deliver.
+*
+* Three rules, all of them the caller's to make and this plugin's to keep:
+*
+*  1. **`ownerOnly` is a CLAIM, not a lookup.** The base registry cannot know which session owns the
+*     plugin, so it serves only a call that claims it ({@link isOwnerSession} decides), and a
+*     non-claiming call latches nothing — a worker/subagent session therefore never consumes the line
+*     out from under the owner session.
+*  2. **Nothing is cached here.** `consume()` re-reads the item's real state on every step, so a
+*     dependency that healed stops matching and a NEW session simply sees nothing — "fixed ⇒ silent"
+*     needs no invalidation of its own.
+*  3. **Never throws.** This runs on the prompt path of a live agent: a hostile/mismatched registry
+*     costs one skipped line, never the step.
+*/
+function noticeLines(registry, sessionId, owner) {
+	if (registry === void 0 || sessionId === "") return [];
+	try {
+		const lines = registry.consume(sessionId, { ownerOnly: owner });
+		if (!Array.isArray(lines)) return [];
+		return lines.filter((line) => typeof line === "string");
+	} catch {
+		return [];
+	}
+}
+/**
+* Whether `sessionId` is the OWNER session — a TOP-LEVEL agent, not a worker/subagent.
+*
+* Read STRUCTURALLY off the host's agent registry (`ctx.agents`), deliberately without a dependency
+* on `@deepseek-ai/dsh-agent`: the only question is "is this id one of the roots", and the answer
+* decides a claim the base registry would otherwise have to invent a role for. A subagent session is
+* created under its parent's context, so it is never a root — and a mission executor is a subagent
+* too. Those sessions keep working (memory tools, retrieval), they just do not receive the owner's
+* repair notice.
+*
+* "Cannot tell" DELIVERS (`true`): a host with no agent registry, an older registry without `roots()`,
+* a throwing read — none of those prove the session is a worker, and swallowing a real notice on a
+* guess would be the worse failure. This mirrors the family rule that only a PROVEN condition may
+* take a capability away.
+*/
+function isOwnerSession(agents, sessionId) {
+	if (sessionId === "") return false;
+	let roots;
+	try {
+		roots = agents?.roots;
+	} catch {
+		return true;
+	}
+	if (typeof roots !== "function") return true;
+	try {
+		const list = roots.call(agents);
+		if (!Array.isArray(list)) return true;
+		return list.some((agent) => {
+			const id = agent?.id;
+			return id !== void 0 && id !== null && String(id) === sessionId;
+		});
+	} catch {
+		return true;
+	}
+}
 //#endregion
 //#region ../core/lib/config/paths.js
 /**
@@ -1966,6 +2257,11 @@ const DEFAULT_COMMON_CONFIG = `# avantf-mem 公共配置（分层第②层）。
 #   dim: 768
 #   auto_download: true
 #   auto_migrate: true                # 换模型/宽度后自动分批重算旧空间的向量（默认开）；关掉只剩启动告警 + vectors --fix
+#   self_heal:                        # 语义依赖自愈（默认关）：允许启动期安装缺失的 @huggingface/transformers
+#     enabled: false                  # 打开后走底座 runtime-deps 共享根（base ≥ 0.7.0 / interface v6）；失败只降级到 FTS+实体
+#                                     # 装哪个包 / 从哪装 / 提示说什么：见插件自带的 res/runtime-deps.yaml（随包发布）
+#   native_self_heal:                 # 原生可选依赖自愈：nodejieba / hnswlib-node（默认关）
+#     enabled: false                  # 装哪个包、从哪装、提示说什么，都由插件自带的 res/runtime-deps.yaml 决定
 #   ⚠️ cache_dir / mirror 由家族底座 @avantf/dsh-plugin-base 管理：写在这里会被忽略并告警。
 #      缓存目录用环境变量 AVANTF_MEM_MODEL_CACHE，镜像用 AVANTF_MEM_MODEL_MIRROR（或 HF_ENDPOINT）。
 
@@ -2688,6 +2984,49 @@ function ensureAllAsync(options) {
 //#endregion
 //#region ../core/lib/entities/extract.js
 /**
+* Entity extraction: POS tagging and the noun-ish names that become `entities` rows.
+*
+* Uses nodejieba (optional dependency) for POS; degrades gracefully to a character/regex fallback
+* when unavailable, exactly like the `jieba_available()` guard.
+*
+* Note: nodejieba's `tag()` returns `{ word, tag }` objects, and its POS flag set
+* differs from Python jieba (e.g. proper nouns → `nr`, 名动词 → `vn`).
+*
+* WHAT THIS MODULE IS NOT. It owns what is an entity NAME — nothing about relations. The relation
+* half (SVO candidate triples, explicit patterns, the name/statement/confidence gates and the
+* predicate vocabulary) lives in `relations/`; the two halves share exactly one thing, the tagging
+* pass ({@link tagText}), so a write pays for the dictionary once and drives both.
+*
+* WHERE THE MODULE COMES FROM. `nodejieba` is an optional npm dependency, so it is normally resolved
+* from this tree. A host that provisions it instead (the DSH plugin's `runtime-deps` self-heal) sets
+* the shared root with {@link useTokenizerModuleDir}; the load then resolves from THAT root first and
+* falls back to this tree, which is the pre-existing behaviour and also the recovery path for a root
+* that was garbage-collected or damaged. Nothing here decides whether a root should exist.
+*/
+/**
+* The shared module root the tokenizer should be loaded from, when the caller provisioned one.
+*
+* `undefined` (the default, and every CLI/MCP/test caller) = this tree's own optional dependency.
+* Set by {@link useTokenizerModuleDir} from the DSH plugin once the native self-heal item is READY;
+* a failed resolution from it falls back to this tree rather than degrading the tokenizer.
+*/
+let moduleRoot$1;
+/**
+* Point the optional tokenizer at a shared module root (the base `runtime-deps` handle's directory).
+*
+* The memo follows the ROOT: changing it forgets whatever the previous root produced, so the next
+* load resolves from the new one — that is the whole point of setting a root. The cost is at most one
+* extra dictionary parse (~1 s, once) when a root arrives after a lazily loaded copy from this tree;
+* Node's own module cache keeps the import itself cheap. The plugin only sets this once, when its
+* native self-heal item settles.
+*/
+function useTokenizerModuleDir(dir) {
+	const next = dir === "" ? void 0 : dir;
+	if (next === moduleRoot$1) return;
+	moduleRoot$1 = next;
+	jiebaLoad = void 0;
+}
+/**
 * The load, memoized as a PROMISE — not as its result.
 *
 * `mod.load()` parses nodejieba's dictionary synchronously on the main thread (~1 s measured), and
@@ -2698,28 +3037,67 @@ function ensureAllAsync(options) {
 * time — measured 2143 ms for two concurrent callers against 1000 ms for one.
 *
 * A FAILED load is cached too (the same one-attempt policy as before): a process whose jieba cannot
-* be imported uses the regex fallback for its lifetime rather than retrying on every write.
+* be imported uses the regex fallback for its lifetime rather than retrying on every write. The one
+* exception is a module root that arrives afterwards — see {@link useTokenizerModuleDir}.
 */
 let jiebaLoad;
 /** How many times the dictionary was actually parsed in this process (see `jiebaLoadAttempts`). */
 let jiebaAttempts = 0;
+/** The root the LAST attempt resolved from (`undefined` = this tree); reported by {@link jiebaStatus}. */
+let jiebaAttemptedRoot;
+/** Why the last attempt failed, one short line — what makes an "unavailable" log line diagnosable. */
+let jiebaError;
 function loadJieba() {
 	jiebaLoad ??= loadJiebaOnce();
 	return jiebaLoad;
 }
+/**
+* Import `nodejieba` from the shared root, else from this tree.
+*
+* The shared root's own `package.json` is the resolution anchor (the same rule the semantic adapter
+* uses for transformers.js): its `node_modules` is what the provider installed, and importing by FILE
+* URL means this root's copy is the one loaded even when this tree also carries the package. A root
+* that no longer resolves is not an error to report here — the fallback below is the behaviour, and
+* the caller's dependency audit is what tells an operator about it.
+*/
+async function importTokenizer(root) {
+	if (root !== void 0) try {
+		return await import(pathToFileURL(createRequire(join(root, "package.json")).resolve("nodejieba")).href);
+	} catch {}
+	return await import("nodejieba");
+}
+/** nodejieba's export shape, normalised (CJS through `import()` may land on `default`). */
+function tokenizerOf(raw) {
+	const mod = typeof raw?.tag === "function" ? raw : raw?.default ?? raw;
+	return mod !== null && typeof mod?.tag === "function" ? mod : null;
+}
 async function loadJiebaOnce() {
 	jiebaAttempts += 1;
+	const root = moduleRoot$1;
+	jiebaAttemptedRoot = root;
 	try {
-		const raw = await import("nodejieba");
-		const mod = typeof raw.tag === "function" ? raw : raw.default ?? raw;
+		const mod = tokenizerOf(await importTokenizer(root));
+		if (mod === null) throw new Error("nodejieba 的 tag() 不可用");
 		if (typeof mod.load === "function") mod.load();
+		jiebaError = void 0;
 		return mod;
-	} catch {
+	} catch (error) {
+		jiebaError = error instanceof Error ? error.message : String(error);
+		if (moduleRoot$1 !== root) jiebaLoad = void 0;
 		return null;
 	}
 }
-async function jiebaAvailable() {
-	return await loadJieba() !== null;
+/** The status of the memoized load, starting one only when none has run yet. */
+async function jiebaProbe() {
+	await loadJieba();
+	const load = jiebaLoad;
+	return {
+		available: load !== void 0 && await load !== null,
+		attempts: jiebaAttempts,
+		attemptedRoot: jiebaAttemptedRoot,
+		root: moduleRoot$1,
+		error: jiebaError
+	};
 }
 const NOUN_FLAGS = /* @__PURE__ */ new Set([
 	"n",
@@ -2899,6 +3277,32 @@ async function awaitStartupGate(options = {}) {
 	return await whenEventLoopIdle();
 }
 /**
+* The line one tokenizer observation deserves.
+*
+* `previous` is what makes the pair readable: a `ready` after a `degraded` is a RECOVERY (the
+* earlier probe ran before a loadable copy existed — the provisioned root had not been handed over,
+* or the package was not installed yet), not a change of story. A `degraded` line never claims more
+* than it knows: it names the reason and the two ways to fix it, and says that a loadable copy
+* arriving later is picked up automatically.
+*
+* Exported for the test that pins those transitions; it has no side effects.
+*/
+function tokenizerReport(status, elapsedMs, previous) {
+	if (status.available) return {
+		level: "info",
+		message: `model bootstrap: tokenizer ready in ${elapsedMs}ms (nodejieba${status.attemptedRoot === void 0 ? "" : ", provisioned root"})${previous === "degraded" ? " — recovered: the earlier \"unavailable\" line described a probe that ran before a loadable copy existed, not this state" : ""}`,
+		next: "ready"
+	};
+	const reason = status.error === void 0 || status.error === "" ? "nodejieba could not be loaded" : status.error;
+	return {
+		level: "warn",
+		message: `model bootstrap: nodejieba unavailable in ${elapsedMs}ms — ${status.attemptedRoot === void 0 ? `no loadable nodejieba in this tree (${reason})` : `the provisioned root ${status.attemptedRoot} cannot load nodejieba (${reason})`}${previous === "ready" ? " (the copy that was loadable earlier is no longer resolvable — a provisioned root replaced it, or it was removed)" : ""}; entity/triple extraction runs on the regex path (weaker entity + jaccard legs) until a loadable copy exists — install nodejieba, or enable semantic.native_self_heal to have the native item provision it (a provisioned root that arrives later is picked up automatically)`,
+		next: "degraded"
+	};
+}
+/** The last verdict reported in THIS process; see {@link TokenizerVerdict}. */
+let tokenizerVerdict = "unknown";
+/**
 * Warm ONLY the tokenizer, after the host-readiness signal and (when asked) an idle event loop.
 *
 * nodejieba loads its dictionary lazily on the FIRST `tag()` (measured ~950 ms, after which a call
@@ -2914,8 +3318,10 @@ async function warmTokenizer(rt, options = {}) {
 	const waited = await awaitStartupGate(options);
 	if (options.deferTokenizerUntilIdle === true && waited >= 200) rt.logger.info(`model bootstrap: tokenizer warm waited ${waited}ms for an idle event loop`);
 	const jiebaStarted = Date.now();
-	if (await jiebaAvailable()) rt.logger.info(`model bootstrap: tokenizer ready in ${Date.now() - jiebaStarted}ms (nodejieba)`);
-	else rt.logger.warn(`model bootstrap: nodejieba unavailable in ${Date.now() - jiebaStarted}ms — entity/triple extraction falls back to the regex path (weaker entity + jaccard legs)`);
+	const report = tokenizerReport(await jiebaProbe(), Date.now() - jiebaStarted, tokenizerVerdict);
+	tokenizerVerdict = report.next;
+	if (report.level === "warn") rt.logger.warn(report.message);
+	else rt.logger.info(report.message);
 }
 /**
 * Non-blocking embedding warm, for a caller that knows the model files are already on disk.
@@ -3525,6 +3931,69 @@ function truncateToTokens(text, maxTokens, opts = {}) {
 	};
 }
 /**
+* Slice `text` into windows of at most `maxTokens` estimated tokens instead of truncating it.
+*
+* WHY THIS EXISTS. The window belongs to the loaded model and the call site cannot widen it, so a
+* text past it has exactly one of two fates: cut (what {@link truncateToTokens} does, and what
+* transformers.js does silently on its own) or split. A knowledge chunk of ~1000 characters against
+* a 512-token model lost half its content from the vector that way — measured in production as
+* "503 tokens dropped here". Splitting keeps every token in the representation; the adapter that
+* can only return ONE vector then pools the window vectors (`LocalBgeBackend.encode`).
+*
+* Every returned window satisfies `estimate(window) <= maxTokens` (a one-character window is the
+* floor; the estimator cannot exceed a limit of 1 token for a single character). Cuts land on a
+* sentence/clause boundary when one is in the window's final quarter, so a window does not start or
+* end mid-word.
+*
+* @param text - the input.
+* @param maxTokens - the per-window budget (already net of special tokens, as the adapter computes it).
+* @param opts - estimator override (tests use a flat one); defaults to {@link estimateTokens}.
+*/
+function splitToWindows(text, maxTokens, opts = {}) {
+	const estimate = opts.estimate ?? estimateTokens;
+	const limit = Math.max(1, Math.floor(maxTokens));
+	const tokens = estimate(text);
+	const chars = Array.from(text);
+	if (chars.length === 0) return {
+		windows: [text],
+		tokens,
+		windowTokens: [tokens]
+	};
+	if (tokens <= limit) return {
+		windows: [text],
+		tokens,
+		windowTokens: [tokens]
+	};
+	const windows = [];
+	const windowTokens = [];
+	let start = 0;
+	while (start < chars.length) {
+		let used = 0;
+		let end = start;
+		while (end < chars.length) {
+			const cost = CJK.test(chars[end]) ? 1 : chars[end].trim() === "" ? 0 : .25;
+			if (used + cost > limit && end > start) break;
+			used += cost;
+			end += 1;
+		}
+		const floor = start + Math.floor((end - start) * .75);
+		for (let i = end - 1; i >= floor; i--) if (BREAK.has(chars[i])) {
+			end = i + 1;
+			break;
+		}
+		while (end - start > 1 && estimate(chars.slice(start, end).join("")) > limit) end -= 1;
+		const window = chars.slice(start, end).join("");
+		windows.push(window);
+		windowTokens.push(estimate(window));
+		start = end;
+	}
+	return {
+		windows,
+		tokens,
+		windowTokens
+	};
+}
+/**
 * Resolve the effective input window for a loaded model.
 *
 * @param configured - `0` (or negative) means "auto: use the model's declared window".
@@ -3548,6 +4017,14 @@ function declaredWindowOf(pipe) {
 	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > SENTINEL_WINDOW) return void 0;
 	return Math.floor(value);
 }
+/**
+* Characters of a chunk that fit the window for `window` tokens, minus the per-chunk
+* overhead (`specialTokens` for CLS/SEP). Used to derive `knowledge.chunk_size` so the
+* default chunking is justified by the shipped model's window instead of by feel.
+*/
+function windowChars(window, specialTokens = 2) {
+	return Math.max(1, Math.floor((window - specialTokens) / 1));
+}
 //#endregion
 //#region ../retrieval-core/lib/budget.js
 /**
@@ -3760,6 +4237,10 @@ var LocalBgeBackend = class {
 		};
 		return this._representation;
 	}
+	/** Point the loader at a shared runtime-dependency root before the first warmup. */
+	useModuleDir(dir) {
+		this.env.moduleDir = dir;
+	}
 	/**
 	* Fire-and-forget retry for call sites that only observe availability. No-op
 	* while the model is ready or an attempt is already in flight; otherwise
@@ -3808,42 +4289,118 @@ var LocalBgeBackend = class {
 		return this._window;
 	}
 	/**
-	* Bound `text` to the window BEFORE it reaches transformers.js.
+	* The window-sized slices `text` is encoded in (see `text_budget.splitToWindows`).
 	*
-	* This is the only place the guard can live: the feature-extraction pipeline's `_call`
-	* accepts `{pooling, normalize, quantize, precision}` and nothing else, so `max_length`
-	* cannot be raised or lowered from the call site — past `model_max_length` the tokenizer
-	* truncates and says nothing.
+	* WHERE THE BOUNDARY CAN LIVE. The feature-extraction pipeline's `_call` accepts
+	* `{pooling, normalize, quantize, precision}` and nothing else, so `max_length` cannot be raised
+	* from the call site — past `model_max_length` transformers.js truncates and says nothing. This
+	* adapter is therefore the only place that can apply the model's own window, and it SPLITS rather
+	* than cuts: a text past the window is a document chunk (or a long fact) whose tail is content,
+	* and cutting it dropped 503 of ~1015 tokens out of the vector in production.
 	*/
-	bound(text) {
-		const out = truncateToTokens(text, Math.max(1, this.window() - SPECIAL_TOKENS));
-		if (out.truncated) {
-			recordTruncation("embedding");
-			if (!this._lengthWarned) {
-				this._lengthWarned = true;
-				retrievalLogger().warn(`semantic: input exceeded the ${this.window()}-token window of ${this.model} — text is truncated before encoding (${out.omittedTokens} tokens dropped here); check knowledge.chunk_size and semantic.max_input_tokens`);
-			}
-		}
-		return out;
+	windows(text) {
+		return splitToWindows(text, Math.max(1, this.window() - SPECIAL_TOKENS));
 	}
-	async encode(text) {
-		await this.warmUp();
-		if (!this._available || !this._pipe) throw new Error("local_bge：语义后端不可用（请安装 @huggingface/transformers 并等模型下载完成）");
-		const bounded = this.bound(text);
-		const out = await this._pipe(bounded.text, {
-			pooling: this.pooling,
-			normalize: this.normalize
-		});
-		const arr = Array.from(out.data);
-		if (arr.length !== this.dim && !this._dimWarned) {
+	/**
+	* Report an input that needed more than one window — once per process, and as an INFO line.
+	*
+	* Not a warning any more: nothing is lost (every window is pooled into the one vector), so the
+	* line is a tuning hint, not a degradation. It carries the actionable number: `chunk_size` is
+	* measured in CHARACTERS and {@link windowChars} converts the model's token window into exactly
+	* that, which is the thing an operator (or a chunker's default) has to change to keep one window
+	* per input. `semantic.max_input_tokens` is deliberately NOT suggested: `resolveWindow` clamps it
+	* to the model's declared window, so raising it cannot buy a single extra token.
+	*/
+	reportSplit(count, tokens) {
+		recordTruncation("embedding");
+		if (this._lengthWarned) return;
+		this._lengthWarned = true;
+		retrievalLogger().info(`semantic: input of ~${tokens} tokens exceeds the ${this.window()}-token window of ${this.model} — encoded as ${count} windows and pooled, nothing dropped (one pass per input needs knowledge.chunk_size within ${windowChars(this.window())} characters for this model)`);
+	}
+	/** The configured width's vector: model output padded/truncated, with the one-shot dim warning. */
+	toVector(values) {
+		if (values.length !== this.dim && !this._dimWarned) {
 			this._dimWarned = true;
-			retrievalLogger().warn(`semantic: model ${this.model} outputs dim=${arr.length} but config semantic.dim=${this.dim} — vectors are truncated/padded; set semantic.dim to ${arr.length} and reindex`);
+			retrievalLogger().warn(`semantic: model ${this.model} outputs dim=${values.length} but config semantic.dim=${this.dim} — vectors are truncated/padded; set semantic.dim to ${values.length} and reindex`);
 		}
 		const vec = new Float32Array(this.dim);
-		for (let i = 0; i < this.dim && i < arr.length; i++) vec[i] = arr[i];
+		for (let i = 0; i < this.dim && i < values.length; i++) vec[i] = values[i];
 		return vec;
 	}
 	/**
+	* ONE vector for several windows: token-weighted mean of the window vectors, re-normalized when the
+	* representation normalizes.
+	*
+	* Weighted rather than a plain mean because the last window is usually short, and a plain mean
+	* would over-represent a fragment. Mean-of-normalized-vectors then re-normalized is the mean
+	* DIRECTION of the windows — the same coordinate space the model's own mean pooling produces, so
+	* `representationKey` (`pooling`/`normalize`/window) does not move and stored vectors stay
+	* comparable with the ones this writes.
+	*/
+	pool(vectors, weights) {
+		const width = vectors[0]?.length ?? 0;
+		if (width === 0 || vectors.length === 0) return new Float32Array(this.dim);
+		const total = weights.reduce((sum, w) => sum + Math.max(0, w), 0);
+		const out = new Float64Array(width);
+		for (let i = 0; i < vectors.length; i++) {
+			const weight = total > 0 ? Math.max(0, weights[i] ?? 0) / total : 1 / vectors.length;
+			const vec = vectors[i];
+			for (let d = 0; d < width; d++) out[d] += (vec[d] ?? 0) * weight;
+		}
+		if (this.normalize) {
+			let norm = 0;
+			for (let d = 0; d < width; d++) norm += out[d] * out[d];
+			norm = Math.sqrt(norm);
+			if (norm > 0) for (let d = 0; d < width; d++) out[d] /= norm;
+		}
+		return this.toVector(Array.from(out));
+	}
+	/** Encode the windows of one text in ONE model call, falling back to one call per window. */
+	async encodeWindows(pipe, windows, weights) {
+		const opts = {
+			pooling: this.pooling,
+			normalize: this.normalize
+		};
+		try {
+			const out = await pipe(windows, opts);
+			const rows = out.dims?.[0];
+			const flat = out.data;
+			if (rows === windows.length) {
+				const width = Math.floor(flat.length / rows);
+				if (width > 0) {
+					const vecs = [];
+					for (let i = 0; i < rows; i++) vecs.push(Array.from(flat.slice(i * width, (i + 1) * width), Number));
+					return this.pool(vecs, weights);
+				}
+			}
+		} catch {}
+		const vecs = [];
+		for (const window of windows) {
+			const out = await pipe(window, opts);
+			vecs.push(Array.from(out.data));
+		}
+		return this.pool(vecs, weights);
+	}
+	/** Encode one plan: a single window verbatim, several pooled. */
+	async encodePlan(pipe, plan) {
+		const first = plan.windows[0];
+		if (plan.windows.length <= 1) {
+			const out = await pipe(first ?? "", {
+				pooling: this.pooling,
+				normalize: this.normalize
+			});
+			return this.toVector(Array.from(out.data));
+		}
+		this.reportSplit(plan.windows.length, plan.tokens);
+		return await this.encodeWindows(pipe, plan.windows, plan.windowTokens);
+	}
+	async encode(text) {
+		await this.warmUp();
+		const pipe = this._pipe;
+		if (!this._available || pipe === null) throw new Error("local_bge：语义后端不可用（请安装 @huggingface/transformers 并等模型下载完成）");
+		return await this.encodePlan(pipe, this.windows(text));
+	}
+	/**
 	* Encode several texts in ONE model call.
 	*
 	* This used to be a serial loop over `encode()`, and production code never called it — so
@@ -3856,11 +4413,22 @@ var LocalBgeBackend = class {
 		if (texts.length === 0) return [];
 		if (texts.length === 1) return [await this.encode(texts[0])];
 		await this.warmUp();
-		if (!this._available || !this._pipe) throw new Error("local_bge：语义后端不可用（请安装 @huggingface/transformers 并等模型下载完成）");
-		const sorted = texts.map((text, index) => ({
-			text,
-			index
-		})).sort((a, b) => a.text.length - b.text.length);
+		const pipe = this._pipe;
+		if (!this._available || pipe === null) throw new Error("local_bge：语义后端不可用（请安装 @huggingface/transformers 并等模型下载完成）");
+		const plans = texts.map((text) => this.windows(text));
+		const singles = [];
+		const longs = [];
+		plans.forEach((plan, index) => {
+			if (plan.windows.length <= 1) singles.push({
+				text: plan.windows[0] ?? texts[index],
+				index
+			});
+			else longs.push({
+				plan,
+				index
+			});
+		});
+		const sorted = singles.sort((a, b) => a.text.length - b.text.length);
 		const result = new Array(texts.length);
 		for (let i = 0; i < sorted.length; i += BATCH_WINDOW) {
 			const group = sorted.slice(i, i + BATCH_WINDOW);
@@ -3869,15 +4437,15 @@ var LocalBgeBackend = class {
 				result[g.index] = vecs[j];
 			});
 		}
+		for (const { plan, index } of longs) result[index] = await this.encodePlan(pipe, plan);
 		return result;
 	}
 	/** One model call for a length-homogeneous group; falls back to per-text calls on failure. */
 	async encodeGroup(texts) {
 		const pipe = this._pipe;
 		if (pipe === null) throw new Error("local_bge：语义后端不可用");
-		const bounded = texts.map((t) => this.bound(t).text);
 		try {
-			const out = await pipe(bounded, {
+			const out = await pipe(texts, {
 				pooling: this.pooling,
 				normalize: this.normalize
 			});
@@ -3904,12 +4472,32 @@ var LocalBgeBackend = class {
 	}
 };
 async function createFeatureExtraction(model, env) {
-	const mod = await import("@huggingface/transformers");
+	const mod = await loadTransformers(env.moduleDir);
 	if (!mod.pipeline) throw new Error("transformers.js 的 pipeline 不可用");
 	applyModelEnv(mod, env);
 	return await mod.pipeline("feature-extraction", model);
 }
 /**
+* Load transformers.js from the shared runtime-dependency root, else from this tree.
+*
+* The shared root is the base provider's content-addressed install (`<home>/deps/runtime/<key>`), and
+* its `package.json` is the anchor `createRequire` needs: resolving `@huggingface/transformers` from
+* there picks the copy the provider verified, together with its transitive `onnxruntime-node` — no
+* second copy, and no dependence on this bundle's own node_modules. The import is by file URL because
+* the resolved entry is an ESM file inside the root, not a bare specifier this module could resolve.
+*
+* A root that no longer resolves (GC, damaged tree, a package whose entry moved) is a WARNING and the
+* pre-existing optional resolution: a broken self-heal must not be worse than no self-heal.
+*/
+async function loadTransformers(moduleDir) {
+	if (moduleDir !== void 0 && moduleDir.trim() !== "") try {
+		return await import(pathToFileURL(createRequire(join(moduleDir, "package.json")).resolve("@huggingface/transformers")).href);
+	} catch (error) {
+		retrievalLogger().warn(`semantic: could not load @huggingface/transformers from the shared runtime root ${moduleDir} (${describeError$1(error)}); falling back to this tree's optional dependency`);
+	}
+	return await import("@huggingface/transformers");
+}
+/**
 * Apply this project's cache/mirror policy to transformers.js.
 *
 * `mod.env` is PROCESS-GLOBAL and last-writer-wins. Setting the keys from a single place is what
@@ -4007,6 +4595,60 @@ function dot(a, b) {
 //#region ../retrieval-core/lib/adapters/hnswlib.js
 const require = createRequire(import.meta.url);
 /**
+* The shared module root `hnswlib-node` should be loaded from, when the caller provisioned one.
+*
+* `undefined` (every CLI/MCP/direct caller) = this tree's own optional dependency. The DSH plugin
+* sets it from the native self-heal item's `handle.dir` once that item is ready; a root that no
+* longer resolves falls back to this tree, which is the pre-existing behaviour and must never be
+* worse than no self-heal.
+*/
+let moduleRoot;
+/**
+* The loaded binding, memoized (`undefined` = not attempted, `null` = the last attempt failed).
+*
+* Native addons are expensive to `dlopen` and there is exactly one per process; memoizing also makes
+* every store in the process shares one load. The cache follows the ROOT (see
+* {@link useHnswlibModuleDir}), because a root that arrives later is the one event that can turn a
+* failed load into a working index.
+*/
+let loaded;
+/**
+* Point the loader at a shared module root (the base `runtime-deps` handle's directory).
+*
+* The cache follows the ROOT: a change forgets what was loaded, because the next `require` must come
+* from the new root (that is the whole point of setting one). It costs nothing in practice — Node's
+* own `require` cache makes re-entering the same file cheap, and a live native index is untouched
+* (see `HnswlibVectorStore.useModuleDir`, which only rebuilds when it has no native index at all).
+*/
+function useHnswlibModuleDir(dir) {
+	const next = dir === "" ? void 0 : dir;
+	if (next === moduleRoot) return;
+	moduleRoot = next;
+	loaded = void 0;
+}
+/** Does this module actually carry the constructor this adapter needs? */
+function usable(mod) {
+	return typeof mod?.HierarchicalNSW === "function";
+}
+/** `require('hnswlib-node')` from the shared root, else from this tree; `null` when neither works. */
+function loadHnswlib() {
+	if (loaded !== void 0) return loaded;
+	let mod = null;
+	if (moduleRoot !== void 0) try {
+		const entry = createRequire(join(moduleRoot, "package.json")).resolve("hnswlib-node");
+		const candidate = require(entry);
+		if (usable(candidate)) mod = candidate;
+	} catch {}
+	if (mod === null) try {
+		const candidate = require("hnswlib-node");
+		mod = usable(candidate) ? candidate : null;
+	} catch {
+		mod = null;
+	}
+	loaded = mod;
+	return mod;
+}
+/**
 * When to COMPACT tombstones away, as a fraction of the live count.
 *
 * Deleted points stay in the graph (excluded from results, but still traversed), so they cost
@@ -4065,15 +4707,41 @@ var HnswlibVectorStore = class {
 		this.dim = dim;
 		this.efSearch = Math.max(16, Math.floor(efSearch));
 		this.fallback = new LocalNumpyVectorStore(dim);
+		this.lib = this.openNative(Math.max(1024, dim * 2));
+	}
+	/**
+	* Build a native index at `max` capacity, or `null` when the binding cannot be loaded.
+	*
+	* One place for "make an index": the constructor, `reindex()` and `rebuild()` each used to spell
+	* the `require` out themselves, which is how a module root set after construction could never
+	* reach them. `null` is the caller's signal to serve from {@link fallback} — a missing binding
+	* degrades, it never throws.
+	*/
+	openNative(max) {
+		const mod = loadHnswlib();
+		if (mod === null) return null;
 		try {
-			const { HierarchicalNSW } = require("hnswlib-node");
-			const lib = new HierarchicalNSW("cosine", dim);
-			lib.initIndex(Math.max(1024, dim * 2), 16, 100);
-			this.lib = lib;
+			const lib = new mod.HierarchicalNSW("cosine", this.dim);
+			lib.initIndex(Math.max(1024, max), 16, 100);
+			return lib;
 		} catch {
-			this.lib = null;
+			return null;
 		}
 	}
+	/**
+	* Point this store's native side at a shared module root and, when the binding was unavailable
+	* until now, rebuild the index from the tracked vectors under it.
+	*
+	* This is the case the whole hook exists for: `mem` builds its vector store during mount, while the
+	* native self-heal item is still installing, so the constructor may have fallen back. When the item
+	* settles, the plugin calls this — and a store that already serves natively is left alone (the
+	* binding is the same one).
+	*/
+	useModuleDir(dir) {
+		useHnswlibModuleDir(dir);
+		if (this.lib !== null) return;
+		this.rebuild(this.liveRows());
+	}
 	add(id, vec) {
 		if (vec.length !== this.dim) throw new Error(`向量维度不匹配：得到 ${vec.length}，需要 ${this.dim}`);
 		if (this.lib) try {
@@ -4229,10 +4897,8 @@ var HnswlibVectorStore = class {
 	/** Recreate the serving index (native when possible) from the tracked vectors. */
 	reindex() {
 		const stored = [...this.vectors.entries()];
-		if (this.lib) try {
-			const { HierarchicalNSW } = require("hnswlib-node");
-			const lib = new HierarchicalNSW("cosine", this.dim);
-			lib.initIndex(Math.max(1024, (stored.length || 1) * 2), 16, 100);
+		const lib = this.openNative(Math.max(1024, (stored.length || 1) * 2));
+		if (lib !== null) {
 			this.lib = lib;
 			this.efOn = null;
 			for (const [i, v] of stored) this.lib.addPoint(Array.from(v), i, false);
@@ -4240,9 +4906,8 @@ var HnswlibVectorStore = class {
 			this.rebuilds += 1;
 			this.persist();
 			return;
-		} catch {
-			this.lib = null;
 		}
+		this.lib = null;
 		this.fallback = new LocalNumpyVectorStore(this.dim);
 		for (const [i, v] of stored) this.fallback.add(i, v);
 		this.graphElements = stored.length;
@@ -4268,15 +4933,8 @@ var HnswlibVectorStore = class {
 			for (const r of list) this.vectors.set(r.id, r.vec);
 			return;
 		}
-		if (this.lib) try {
-			const { HierarchicalNSW } = require("hnswlib-node");
-			const lib = new HierarchicalNSW("cosine", this.dim);
-			lib.initIndex(Math.max(1024, (list.length || 1) * 2), 16, 100);
-			this.lib = lib;
-			this.efOn = null;
-		} catch {
-			this.lib = null;
-		}
+		this.lib = this.openNative(Math.max(1024, (list.length || 1) * 2));
+		if (this.lib !== null) this.efOn = null;
 		for (const r of list) this.add(r.id, r.vec);
 		this.rebuilds += 1;
 		this.persist();
@@ -4454,6 +5112,19 @@ var AutoVectorStore = class {
 		this.pendingPersistence = path;
 		this.delegate.attachPersistence?.(path);
 	}
+	/**
+	* Point the ANN side at a shared module root (the plugin's native self-heal item) — for THIS store
+	* when it already migrated, and for the one it may migrate to later.
+	*
+	* The delegate call covers the first case; the module-level root (set by
+	* `HnswlibVectorStore.useModuleDir` / `useHnswlibModuleDir`) is what a FUTURE
+	* `new HnswlibVectorStore` in `maybeUpgrade` reads. Below the threshold nothing changes: an
+	* unmigrated store keeps serving from brute force, which is the intended backend at that size.
+	*/
+	useModuleDir(dir) {
+		if (this.delegate.useModuleDir !== void 0) this.delegate.useModuleDir(dir);
+		else useHnswlibModuleDir(dir);
+	}
 	flush() {
 		this.delegate.flush?.();
 	}
@@ -9795,7 +10466,7 @@ function pathRecency(path) {
 	for (const edge of path.edges) newest = Math.max(newest, edgeTime(edge));
 	return newest;
 }
-/** Dedup key of a path: the ordered edge ids (§5 "路径去重按 (edge ids)"). */
+/** Dedup key of a path: the ordered edge ids ("路径去重按 (edge ids)"). */
 function pathKey(path) {
 	return path.edges.map((edge) => edge.id).join("\0");
 }
@@ -16194,6 +16865,36 @@ var MemoryStore = class {
 		await (this.semantic.warmUp?.() ?? Promise.resolve());
 		return this.semantic.isAvailable();
 	}
+	/**
+	* Point the semantic backend at a shared runtime-dependency root (the base provider's
+	* `runtime-deps` handle) before it warms. Best-effort by contract: a backend without external
+	* module resolution ignores it, and a missing root is reported by the backend itself.
+	*/
+	useSemanticModuleDir(dir) {
+		this.semantic.useModuleDir?.(dir);
+	}
+	/**
+	* Point the vector store at a shared runtime-dependency root for its NATIVE binding
+	* (`hnswlib-node`), after the DSH plugin's native self-heal item is ready.
+	*
+	* Same best-effort contract as {@link useSemanticModuleDir}: a store with no native binding (the
+	* brute-force backend, or an `auto` store still on it) ignores it, and a store that already fell
+	* back to brute force rebuilds its tracked vectors under the new root. Nothing here decides whether
+	* a root should exist — the caller's dependency audit does.
+	*/
+	useNativeModuleDir(dir) {
+		this.vstore.useModuleDir?.(dir);
+	}
+	/**
+	* Vectors currently in the LIVE index (sync, one map read).
+	*
+	* Exposed for the plugin's dependency audit: an `hnswlib-node` notice is conditioned on the corpus
+	* actually being large enough for an ANN index to matter (`min_vectors`), and a session line that
+	* asks "how big is the store right now" must not run a database query to answer.
+	*/
+	liveVectorCount() {
+		return this.vstore.count();
+	}
 	/** List contradiction candidates (`resolved` 0 = open, 1 = closed with a recorded verdict). */
 	async listContradictions(opts) {
 		return await this.contradictions.list(opts?.resolved ?? 0, opts?.kind, opts?.threshold, opts?.limit ?? 10);
@@ -16632,7 +17333,10 @@ var MemoryStore = class {
 	* The exact, facts and relation passes reinforce the facts they return, exactly like the fuzzy
 	* pass does for its hits: all are recalls the caller actually reads. A caller that must stay
 	* read-only passes `track: false` (the conditional hint's probe does). Exact, facts, relation and
-	* time also honour the caller's output budget (their text is the caller's to bound).
+	* time also honour the caller's output budget (their text is the caller's to bound). The one
+	* difference is the DEFAULT: a time window applies no budget unless the caller names one — its
+	* page size (`limit`) is what bounds the list, and the budget would only rewrite rows the caller
+	* asked for (see {@link timePage}).
 	*
 	* It does NOT emit a retrieval-health event. Those counters describe the retrieval PIPELINE
 	* (legs, fusion, semantic-live rate); none of an exact, facts, relation or time answer ran a leg,
@@ -16678,32 +17382,46 @@ var MemoryStore = class {
 	* happened that day" reads in the order it happened; `score` is the constant 1 exactly like the
 	* exact page's, because there is no relevance number here for the model to compare.
 	*
-	* It honours `kind`/`source`, pages with the same `offset`/`limit` (default 10, cap 50) and the
-	* same `max_tokens` budget as every other recall, and reinforces the rows it returns unless
-	* `track: false` — a window the caller reads is a recall like any other.
+	* The PAGE is the contract's, not the caller's guess: `limit` omitted means one page of
+	* {@link TIME_DEFAULT_LIMIT} rows (the same 50 the contract caps an explicit page at), and an
+	* explicit `limit` (1-50) still wins. A window that holds more than one page is the normal case
+	* for a busy day, so the envelope does not leave the caller to infer the shortfall: it reports
+	* `remaining = total - (offset + hits.length)`, the count still unseen.
+	*
+	* The output budget is honoured only when the caller names it (`max_tokens`). Falling back to the
+	* configured `retrieval.max_output_tokens` here would rewrite the text of a window's rows behind a
+	* page the caller already bounded with `limit` — the page size is the knob for "how much of the
+	* list", and the budget stays a knob for a RANKED result (exact/facts/relation/hybrid unchanged).
+	* `max_tokens` (including the contract's `0` = unlimited) is passed through unchanged.
+	*
+	* It honours `kind`/`source`, and reinforces the rows it returns unless `track: false` — a window
+	* the caller reads is a recall like any other.
 	*/
 	async timePage(input) {
 		if (input.time === void 0) throw new Error("mem_recall.search 需要 `query`，或只给 `time`（纯时间召回）；两者都没有时无法检索。");
 		const time = normalizeTimeFilter(input.time);
-		const { offset, limit } = exactPage(input.offset, input.limit);
+		const page = exactPage(input.offset, input.limit);
 		const filters = {
 			time,
 			...input.kind === void 0 ? {} : { kind: input.kind },
 			...input.source === void 0 ? {} : { source: input.source }
 		};
 		const total = await this.searchIndex.countInTimeWindow(filters);
+		const limit = input.limit === void 0 ? 50 : page.limit;
+		const offset = page.offset;
 		const ids = total === 0 ? [] : await this.searchIndex.timeWindowRows({
 			...filters,
 			limit,
 			offset
 		});
-		const { kept } = applyOutputBudget(this.config, await this.factHits(ids, () => 1), input.maxTokens);
+		const { kept } = applyOutputBudget(this.config, await this.factHits(ids, () => 1), input.maxTokens ?? 0);
 		if (input.track !== false) await this.reinforce(kept.map((hit) => hit.ref_id));
 		return {
 			mode: "time",
 			total,
 			offset,
 			limit,
+			remaining: Math.max(0, total - (offset + kept.length)),
 			truncated: offset + kept.length < total,
 			hits: kept
 		};
@@ -19254,7 +19972,7 @@ const VERSION_PACKAGES = [
 /** This plugin's npm package id, which names the probe and verification keys. */
 const PACKAGE_ID = String(hostContribution.package ?? "@avantf/dsh-mem");
 /** Best-effort one-line reason for a caught value. */
-function reasonOf(error) {
+function reasonOf$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 /** Emit a warning without ever letting the logger turn it into a crash. */
@@ -19294,7 +20012,7 @@ function runtimeFromCompat(module) {
 }
 /** The "the check itself failed" outcome: keep loading, say why. */
 function cannotDetermine(error, log, prefix) {
-	const message = `${prefix} WARNING — the compatibility check itself failed (${reasonOf(error)}); loading anyway`;
+	const message = `${prefix} WARNING — the compatibility check itself failed (${reasonOf$2(error)}); loading anyway`;
 	warn(log, message);
 	return { verdict: {
 		load: true,
@@ -19378,6 +20096,290 @@ function verifyRegisteredFaces(input) {
 		toolNames: input.toolNames
 	});
 }
+//#endregion
+//#region lib/types/deps_audit.js
+/**
+* The STARTUP DEPENDENCY AUDIT: one cached, synchronous answer per CONFIGURED entry to "can this
+* process actually load that piece right now?", recorded at the end of the mount and refreshed when a
+* self-heal item settles.
+*
+* WHY IT EXISTS. A session notice is the last step of the fallback chain
+* `npm optional → self-heal → notice`, and the decision "is this really missing?" cannot be made on
+* the prompt path: `pre-step` runs on every user message, and resolving a package there would be a
+* filesystem hit (and, for a native addon, a `dlopen`) per step. So the expensive half happens ONCE,
+* off the mount path, and `pre-step` only consumes the registry, whose predicates read this snapshot.
+*
+* CONFIG-DRIVEN, NOT PACKAGE-DRIVEN. This module knows two probe KINDS and nothing about which
+* packages exist:
+*
+*  - {@link moduleProbe} — resolve AND load one specifier (a real `require`/`import`, so a native
+*    addon's binding is loaded rather than merely found), trying the ready shared roots first and
+*    this tree last;
+*  - {@link itemProbe} — the state of one runtime-deps item, through a caller-supplied lookup (the
+*    provisioner's own `resolve`, with the "declared but not settled" gate on top).
+*
+* Which entries exist, how loud each one is, and what it says come from the plugin's SHIPPED
+* `res/runtime-deps.yaml` (`RuntimeDepsResourceSchema` in the contract). No package name, sentence or
+* severity is written here.
+*
+* WHAT IT IS NOT:
+*
+*  - **Not a retry loop.** `run()` at startup, `run()` again when a self-heal item settles. A package
+*    installed by hand afterwards is picked up on the next restart, not polled for.
+*  - **Not throwing.** It runs beside a live host: a probe that fails is a recorded state plus a log
+*    line, never an exception out of the mount.
+*  - **Not a second source of truth about an item.** `itemProbe` ASKS the caller; the states here are
+*    only a cache of that answer, refreshed on every settlement.
+*/
+/** The states this build understands (a JS caller can hand over anything). */
+const STATES = [
+	"available",
+	"failed",
+	"missing",
+	"skipped",
+	"pending",
+	"unknown"
+];
+/** Reason text for a thrown value, without trusting it. */
+function reasonOf$1(error) {
+	try {
+		if (error instanceof Error && typeof error.message === "string" && error.message !== "") return error.message;
+		return String(error);
+	} catch {
+		return "unknown";
+	}
+}
+/**
+* Build the audit.
+*
+* Every configured entry starts `unknown`; nothing is assumed about an entry that has not been
+* checked. The caller runs it once (fire-and-forget) and again for the entries a settlement could
+* change — that ordering is what makes a session line appear only after there is an observation.
+*/
+function createDependencyAudit(options) {
+	const states = /* @__PURE__ */ new Map();
+	const pending = /* @__PURE__ */ new Map();
+	const probes = /* @__PURE__ */ new Map();
+	for (const probe of options.probes) {
+		probes.set(probe.id, probe);
+		states.set(probe.id, "unknown");
+	}
+	const warn = (message) => {
+		try {
+			options.logger?.warn(message);
+		} catch {}
+	};
+	const info = (message) => {
+		try {
+			options.logger?.info(message);
+		} catch {}
+	};
+	const runId = (id) => {
+		const running = pending.get(id);
+		if (running !== void 0) return running;
+		const probe = probes.get(id);
+		if (probe === void 0) return Promise.resolve();
+		const task = (async () => {
+			let next;
+			try {
+				next = await probe.check();
+			} catch (error) {
+				warn(`deps audit: probing ${id} failed (${reasonOf$1(error)}); its state stays unknown`);
+				next = "unknown";
+			}
+			if (!STATES.includes(next)) next = "unknown";
+			const before = states.get(id);
+			states.set(id, next);
+			if (before !== next) info(`deps audit: ${id} is ${next}`);
+		})().finally(() => {
+			pending.delete(id);
+		});
+		pending.set(id, task);
+		return task;
+	};
+	return {
+		state(id) {
+			return states.get(id) ?? "unknown";
+		},
+		vectors() {
+			try {
+				return options.vectors();
+			} catch {
+				return 0;
+			}
+		},
+		async run() {
+			await Promise.all([...probes.keys()].map((id) => runId(id)));
+		},
+		runId
+	};
+}
+/**
+* Resolve and LOAD one specifier, from the first root that can serve it and then from this tree.
+*
+* The `createRequire(<root>/package.json)` anchor is the same rule the semantic adapter uses: a
+* shared runtime-deps root's `package.json` is what makes `resolve` look in THAT root's
+* `node_modules`, so the audit observes the copy the runtime would load. The import is by FILE URL
+* because the resolved entry is inside the root, not a bare specifier this module could resolve.
+*
+* The three answers are deliberately distinct, because they lead to different repairs:
+*
+*  - `available` — it loaded;
+*  - `failed` — something RESOLVED but loading it threw (the node-gyp build that exists and does not
+*    work: the case a bare `resolve()` check would report as healthy);
+*  - `missing` — nothing resolved anywhere.
+*
+* A root that cannot serve the specifier is not an error: the next candidate is tried, which is what
+* makes a garbage-collected store no worse than no self-heal. Never throws.
+*/
+async function moduleProbe(id, specifier, roots) {
+	const candidates = [];
+	for (const root of roots()) {
+		if (root === "") continue;
+		try {
+			candidates.push(createRequire(join(root, "package.json")).resolve(specifier));
+		} catch {}
+	}
+	try {
+		candidates.push(createRequire(import.meta.url).resolve(specifier));
+	} catch {}
+	if (candidates.length === 0) return "missing";
+	let resolvedButBroken = false;
+	for (const entry of candidates) try {
+		await import(pathToFileURL(entry).href);
+		return "available";
+	} catch {
+		resolvedButBroken = true;
+	}
+	return resolvedButBroken ? "failed" : "missing";
+}
+/**
+* Observe one runtime-deps ITEM's state through the caller's own lookup.
+*
+* The caller owns the mapping (its provisioner's `resolve` plus the "declared but not settled" gate),
+* so this probe adds nothing but a defensive boundary: a throwing lookup is `unknown`, not a failure
+* claim. `pending` is passed through because it is a MEANINGFUL state — an install in flight — and the
+* notice predicate treats it as "not reportable yet".
+*/
+function itemProbe(id, itemId, stateOf) {
+	return {
+		id,
+		check: async () => {
+			try {
+				return stateOf(itemId);
+			} catch {
+				return "unknown";
+			}
+		}
+	};
+}
+//#endregion
+//#region lib/types/runtime_deps_resource.js
+/**
+* The plugin's OWN dependency declaration: `res/runtime-deps.yaml`, read from the INSTALL directory.
+*
+* WHY A SHIPPED RESOURCE. The package set, the sources, the attempts, the verify list and the audit
+* sentences describe THIS BUILD — which module the local backend imports, which native bindings this
+* release looks for, what a session should be told when one of them is missing. Keeping them in a
+* user's `configs/common.yaml` made every deployment responsible for a list only the package can know
+* (and made a stale copy install a module no code loads). The operator keeps the one real policy
+* decision — the two `enabled` switches — and the DATA travels with the code that depends on it.
+*
+* WHERE IT IS READ FROM. `<package>/res/runtime-deps.yaml`, located from `import.meta.url`:
+* `lib/index.js` (bundled) and `src/*.ts` (tests, dev) are both one level below the package root, so
+* the same relative URL resolves to the SAME file in the checkout and in an installed tarball. It is
+* deliberately NOT resolved through `node_modules` lookups, `~/.avantf`, or the cwd: a host may mount
+* the plugin from a linked checkout, a global install or a packed tarball, and all three must read
+* their own copy.
+*
+* FAILURE IS EXPLICIT AND NON-FATAL. A missing/unreadable/malformed file is a PACKAGING bug, not an
+* environment one, so the answer is a structured failure with the path and the reason — never a
+* throw out of the mount and never a silent "no dependencies declared". The caller logs it as an
+* ERROR and degrades (no self-heal item, no audit): the plugin keeps its tools, service, prompt and
+* Remote face, and the runtime stays on its optional-dependency resolution.
+*
+* The base never sees this file: `envinit` maps the validated object onto the provider's own
+* `RuntimeDepsSpec` field by field (see `runtimeDepsSpecOf`).
+*/
+/**
+* `res/runtime-deps.yaml` next to the package that owns this module.
+*
+* `import.meta.url` is the anchor (not `process.cwd()`, not a config path): the file ships beside the
+* code, and an installed plugin must read the copy its own package manager put there.
+*/
+function runtimeDepsResourceUrl() {
+	return new URL("../res/runtime-deps.yaml", import.meta.url);
+}
+/** Reason text for a thrown value, without trusting it. */
+function reasonOf(error) {
+	try {
+		if (error instanceof Error && typeof error.message === "string" && error.message !== "") return error.message;
+		return String(error);
+	} catch {
+		return "unknown";
+	}
+}
+/**
+* Read and validate the shipped declaration.
+*
+* Synchronous on purpose: it is a few kilobytes next to the entry module, read once at mount, and the
+* caller's plan (the item specs and the audit entries) has to exist before anything is declared.
+*
+* `url` is injectable so a test can point at a scratch install directory; production always uses
+* {@link runtimeDepsResourceUrl}.
+*/
+function loadRuntimeDepsResource(url = runtimeDepsResourceUrl()) {
+	let path;
+	try {
+		path = fileURLToPath(url);
+	} catch (error) {
+		return {
+			ok: false,
+			path: String(url),
+			reason: `不是可读的文件 URL（${reasonOf(error)}）`
+		};
+	}
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		return {
+			ok: false,
+			path,
+			reason: `无法读取（${reasonOf(error)}）`
+		};
+	}
+	let raw;
+	try {
+		raw = parse(text);
+	} catch (error) {
+		return {
+			ok: false,
+			path,
+			reason: `YAML 解析失败（${reasonOf(error)}）`
+		};
+	}
+	if (raw === null || raw === void 0) return {
+		ok: false,
+		path,
+		reason: "文件是空的（没有任何声明）"
+	};
+	const parsed = RuntimeDepsResourceSchema.safeParse(raw);
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		const where = issue === void 0 ? "" : `${issue.path.join(".") === "" ? "" : `${issue.path.join(".")}: `}`;
+		return {
+			ok: false,
+			path,
+			reason: `声明不符合 RuntimeDepsResourceSchema（${where}${issue?.message ?? "invalid"}）`
+		};
+	}
+	return {
+		ok: true,
+		path,
+		resource: parsed.data
+	};
+}
 const PACKAGE = "@avantf/dsh-plugin-base";
 function parseVersion(input) {
 	const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(input.trim());
@@ -19761,6 +20763,25 @@ function rangeOf(value) {
 *      models elsewhere (`AVANTF_MEM_MODEL_CACHE`) — that would install a second, never-read copy.
 *      A model that cannot be fetched is a WARNING: the semantic path degrades to FTS+entity, it
 *      never refuses the mount.
+*   3. **`mem:semantic-deps`** (`runtime-deps`, `startup: 'background'`) — optional: repair a missing
+*      `@huggingface/transformers` install through the base's shared runtime-dependency store. It is
+*      OFF unless `semantic.self_heal.enabled` says otherwise (that is a network decision, not a
+*      startup default), needs base >= 0.7.0 / interface v6 (the `createRuntimeDeps` helper), and is
+*      declared against the SAME content-addressed root any other family plugin would reuse. The
+*      item, the shared root handle and the operator's configured session notices all come from that
+*      one handle. The handle directory is handed back to the caller, which points the embedding
+*      backend at it before the semantic warm.
+*   4. **`mem:native-deps`** (`runtime-deps`, `startup: 'background'`) — optional: repair the NATIVE
+*      optional dependencies (`nodejieba`, `hnswlib-node`) when `semantic.native_self_heal.enabled`
+*      is on. A SEPARATE item on purpose: a different package set is a different content key, so the
+*      base's store gives it its own immutable root instead of mixing two node-gyp builds into the
+*      transformers install. The handle directory is handed back to the caller, which points the
+*      tokenizer and the vector store's ANN binding at it.
+*
+* Sessions are told about a missing package by NOTICES, and a notice is judged on two observations
+* that this module neither owns alone: the item's live state (below) and the startup dependency
+* audit's cached answer (`deps_audit.ts`, supplied in the plan). A repair that is still installing
+* matches nothing, and a failed repair whose package is loadable stays silent.
 *
 * Two hard rules:
 *
@@ -19783,6 +20804,26 @@ const PLUGIN = "mem";
 */
 const MODEL_ITEM = "mem:model";
 /**
+* The shared runtime-dependency item: `@huggingface/transformers` repaired through the base's
+* content-addressed store when `semantic.self_heal.enabled` is on. Same root as every other family
+* plugin's item for the same package set.
+*/
+const SEMANTIC_DEPS_ITEM = "mem:semantic-deps";
+/**
+* The NATIVE runtime-dependency item: `nodejieba` + `hnswlib-node`, repaired through the same base
+* mechanism when `semantic.native_self_heal.enabled` is on.
+*
+* A SEPARATE item, not a third package in {@link SEMANTIC_DEPS_ITEM}, for two reasons that both
+* matter:
+*
+*  - the store is content-addressed, so this spec's package set (two node-gyp builds) keys a
+*    DIFFERENT immutable root under `<home>/deps/runtime/` — these packages are never installed into
+*    the transformers root, and vice versa;
+*  - the two have independent failure modes and independent consequences (semantic leg vs.
+*    entity/jaccard legs vs. ANN index), so one install failing must not report the other as broken.
+*/
+const NATIVE_DEPS_ITEM = "mem:native-deps";
+/**
 * The default ONNX embedding repository — the one `semantic.local_model` defaults to and the one
 * {@link MODEL_FILES} describes. A DIFFERENT repo is a different file set, which is why the item
 * omits `spec.files` for it (see {@link managedModelSpec}).
@@ -19824,6 +20865,23 @@ const DEADLINE_MS = 15e3;
 * rather than ship the inversion.
 */
 const MODEL_REQUEST_TIMEOUT_MS = 3e5;
+/**
+* Per-attempt budget for the `mem:semantic-deps` install. A package-manager install of
+* transformers.js + onnxruntime-node is tens of MB; the base's 30 s network default would time out on
+* a slow link and report a failure the next attempt could have avoided. The item is `background`, so
+* this budget spends none of the startup allowance; it only bounds one attempt.
+*/
+const SEMANTIC_DEPS_ATTEMPT_TIMEOUT_MS = 6e5;
+/**
+* Per-attempt budget for the `mem:native-deps` install.
+*
+* Longer than the semantic one on purpose: `nodejieba` and `hnswlib-node` are node-gyp packages, so
+* the attempt includes downloading a toolchain-compatible source tree and COMPILING it — measured
+* minutes on a cold cache, and slower on a laptop that is also running the host. A budget that
+* expires mid-compile would report a failure the very next attempt (with the compiler cache warm)
+* would have avoided, and the item is `background`, so this spends no startup allowance.
+*/
+const NATIVE_DEPS_ATTEMPT_TIMEOUT_MS = 9e5;
 /** This module's warning token, so one grep finds every environment-initialisation line. */
 const OWN_PREFIX = "envinit:";
 /**
@@ -19858,6 +20916,104 @@ function sameDir(a, b) {
 	return resolve(expandHome$1(a)) === resolve(expandHome$1(b));
 }
 /**
+* The `runtime-deps` spec the base's shared store should own, or `undefined` when it should not.
+*
+* Refused when:
+*
+*   1. **self-heal is off** — the shipped default. Enabling it is a network decision the operator
+*      makes (`semantic.self_heal.enabled`), never a startup surprise.
+*   2. **the backend is not `local_bge`** — this item repairs the module the local ONNX adapter
+*      loads; a third-party backend owns its own dependencies.
+*   3. **no package was declared** — `spec.packages` must be non-empty (the base rejects an empty
+*      map); declaring nothing is cleaner than a guaranteed `invalid-option`.
+*
+* The config layers are copied field by field, not passed through: the schema's defaults include an
+* empty `cache` placeholder that has to become the family root here (`<home>/cache/npm`), because
+* the schema cannot know which family root the host will resolve. An explicitly configured cache is
+* `~`-expanded, exactly like every other path in this plugin.
+*/
+function managedSemanticDepsSpec(semantic, declaration, home) {
+	if (!semantic.self_heal.enabled) return void 0;
+	if (semantic.backend !== "local_bge") return void 0;
+	if (Object.keys(declaration.packages).length === 0) return void 0;
+	return runtimeDepsSpecOf(declaration, home);
+}
+/**
+* The `runtime-deps` spec for the NATIVE packages, or `undefined` when nothing should be declared.
+*
+* Refused only when `semantic.native_self_heal.enabled` is off or the package map is empty. There is
+* no backend condition here (unlike the semantic spec): the tokenizer and the vector store are used
+* by every backend, and a `vectorStore.backend: local_numpy` deployment still pays for `nodejieba`.
+*/
+function managedNativeDepsSpec(semantic, declaration, home) {
+	if (!semantic.native_self_heal.enabled) return void 0;
+	if (Object.keys(declaration.packages).length === 0) return void 0;
+	return runtimeDepsSpecOf(declaration, home);
+}
+/**
+* The shared shape of both `runtime-deps` specs: packages, sources, attempts, verify.
+*
+* One implementation, because the two sections use ONE provider vocabulary — a second copy of the
+* cache/`~` rules is how a private registry ends up working in one section and not the other. The
+* config layers are copied field by field, not passed through: the schema's defaults include an empty
+* `cache` placeholder that has to become the family root here (`<home>/cache/npm`), because the
+* schema cannot know which family root the host will resolve.
+*/
+function runtimeDepsSpecOf(heal, home) {
+	const packages = {};
+	for (const [name, range] of Object.entries(heal.packages)) packages[name] = range;
+	return {
+		packages,
+		sources: heal.sources.map((source) => {
+			const registry = source.registry.trim();
+			const configuredCache = source.cache.trim();
+			const cache = registry === "" && configuredCache === "" ? join(home, "cache", "npm") : configuredCache === "" ? "" : expandHome$1(configuredCache);
+			return {
+				id: source.id,
+				...registry === "" ? {} : { registry },
+				...cache === "" ? {} : { cache }
+			};
+		}),
+		attempts: heal.attempts.map((attempt) => ({
+			source: attempt.source,
+			...attempt.manager === void 0 ? {} : { manager: attempt.manager },
+			...Object.keys(attempt.env).length === 0 ? {} : { env: { ...attempt.env } },
+			...attempt.allowScripts === void 0 ? {} : { allowScripts: attempt.allowScripts }
+		})),
+		verify: [...heal.verify]
+	};
+}
+/**
+* The configured dependency-audit entries, copied field by field and resolved for execution.
+*
+* Why this is not part of a self-heal spec: the spec is what the base INSTALLS (and part of the shared
+* root's content key, so it has to be exactly the provider's vocabulary), while an audit entry is a
+* PROMPT line plus the observation behind it. Two consumers, two lifetimes — editing a sentence must
+* not look like a new dependency set.
+*
+* The entries are returned VERBATIM (text, severity, condition) and no default is invented: the
+* config's default is the empty array, so a profile that never wrote one gets no injection at all.
+* `min_vectors` is defaulted to `0` here, and to nothing else — this section names no package, so it
+* also invents no package-specific threshold.
+*/
+function managedDependencyAudit(audit) {
+	if (!Array.isArray(audit)) return [];
+	return audit.map((entry) => ({
+		id: entry.id,
+		severity: entry.severity,
+		when: entry.when,
+		minVectors: entry.min_vectors ?? 0,
+		body: entry.body,
+		probe: entry.kind === "module" ? {
+			kind: "module",
+			specifier: entry.specifier
+		} : {
+			kind: "runtime-deps",
+			item: entry.item
+		}
+	}));
+}
+/**
 * The family root: `$AVANTF_HOME`, else `~/.avantf/env`.
 *
 * `AVANTF_HOME` is the same variable the engine uses for its DATA home (`memory/`),
@@ -19947,6 +21103,121 @@ function modelItem(framework, model) {
 	};
 }
 /**
+* A `runtime-deps` item with the DELIVERY policy this plugin owns (the helper supplies only the
+* shape): both `onMissing` axes `degrade` — a failed install may not refuse the mount — `background`
+* (an install may take minutes and spends no startup budget), and the caller's per-attempt budget.
+*
+* `target.root: 'deps/runtime'` is the base's canonical store, already set by the helper. Two items
+* with different package sets are different content keys and therefore different immutable roots
+* inside it, which is what keeps `mem:semantic-deps` and `mem:native-deps` from sharing an install.
+*/
+function runtimeDepsItem(item, timeoutMs) {
+	return {
+		...item,
+		onMissing: {
+			atStartup: "degrade",
+			atUse: "degrade"
+		},
+		startup: "background",
+		policy: { timeoutMs }
+	};
+}
+/** The provisioner's five states in the audit's vocabulary. */
+function dependencyStateOf(state) {
+	switch (state?.state) {
+		case "ready": return "available";
+		case "failed": return "failed";
+		case "missing": return "missing";
+		case "skipped": return "skipped";
+		case "pending": return "pending";
+		default: return "unknown";
+	}
+}
+/**
+* Which observed audit state one configured `when` covers.
+*
+* The same word means the same thing for both probe KINDS, so one mapping serves both:
+* `failed` → a load that threw / an item that failed; `missing` → nothing resolved, or the item is
+* missing/skipped; `degraded` → any of those three. `available`, `pending` and `unknown` match
+* NOTHING: a background install still in flight and an unobserved entry are both "not reportable
+* yet", and a healthy dependency is not a finding.
+*/
+function matchesWhen(when, state) {
+	switch (when) {
+		case "failed": return state === "failed";
+		case "missing": return state === "missing" || state === "skipped";
+		case "degraded": return state === "failed" || state === "missing" || state === "skipped";
+	}
+}
+/**
+* Register one session notice per configured audit entry, judged on the AUDIT's cached state.
+*
+* The predicate is a pure read of two snapshots (`state()` is a map read, `vectors()` is the live
+* index count), so the prompt path never probes anything — the expensive half ran once at startup and
+* again on each settlement (`startDependencyAudit` / the `onSettled` path). A line is delivered when:
+*
+*  - the entry's recorded state matches the configured `when` (see {@link matchesWhen}), and
+*  - the live vector index has reached `minVectors` (0 = no threshold).
+*
+* Registration itself is total: the base registry warns and ignores a duplicate/malformed id, and an
+* id that is already taken costs one line, never the step.
+*/
+function registerDependencyNotices(input) {
+	for (const notice of input.notices) input.registry.register({
+		id: notice.id,
+		severity: notice.severity,
+		when: notice.when,
+		body: notice.body
+	}, () => matchesWhen(notice.when, input.audit.state(notice.id)) && input.audit.vectors() >= notice.minVectors);
+}
+/** Build the probes an audit entry needs — one per configured KIND, no package named here. */
+function probesOf(notices, roots, itemState) {
+	return notices.map((notice) => {
+		switch (notice.probe.kind) {
+			case "module": {
+				const { specifier } = notice.probe;
+				return {
+					id: notice.id,
+					check: () => moduleProbe(notice.id, specifier, roots)
+				};
+			}
+			case "runtime-deps": {
+				const { item } = notice.probe;
+				return itemProbe(notice.id, item, itemState);
+			}
+		}
+	});
+}
+/**
+* Whether the loaded base can serve the shared `runtime-deps` item AND observe it.
+*
+* Three members are required, and all three are one capability here: `RUNTIME_DEPS_KIND` /
+* `runtimeDepsProvider` (interface v5, base 0.6.0) install the root, and `createRuntimeDeps`
+* (interface v6, base 0.7.0) is what DECLARES the item and binds the notices to its state. Since the
+* item is now built by that helper, a base with the provider but not the helper cannot serve this
+* plugin at all — so the predicate answers the caller's real question ("may I declare, wait for and
+* translate this item?") instead of a narrower one that would let a half-wired declaration through.
+*
+* An OLDER generation does not normally reach this point — the interface gate withholds the whole
+* base first (`gateOrDegrade`), so the plugin takes its legacy path. This guard covers the remaining
+* shape: a module that reports a current generation but does not actually carry the members (a
+* partial/hostile module, or a packaging mistake). Enabling self-heal must then degrade to the
+* runtime's optional-dependency path, not throw from `declare`. It is also what lets the fake
+* framework in the tests exercise that degradation instead of a TypeError.
+*
+* Exported because the startup caller asks the same question: a skipped item will never settle, so
+* `startManagedResources` must not wait for it (see `packages/plugin/src/index.ts`). One predicate,
+* two readers — the loader's skip and the caller's "do not wait" can never disagree.
+*
+* `undefined` (the test seam's partial framework, or no module at all) answers `false`: nothing is
+* served, so nothing may be awaited.
+*/
+function supportsRuntimeDeps(framework) {
+	if (framework === void 0) return false;
+	const candidate = framework;
+	return typeof candidate.RUNTIME_DEPS_KIND === "string" && typeof candidate.runtimeDepsProvider === "function" && typeof candidate.createRuntimeDeps === "function";
+}
+/**
 * The plugin-specific halves of the shared loader's sentences: mem says the FRAMEWORK is skipped and
 * names the legacy provisioning path among the withheld capabilities. The mechanism is the shim's
 * (`interface_gate.ts`), the wording is this plugin's.
@@ -19980,6 +21251,8 @@ function loadEnvinit(options = {}) {
 /** The body of {@link loadEnvinit}; the cache above makes it run at most once per process. */
 async function loadOnce(options) {
 	const home = options.home ?? resolveHome();
+	const declaration = loadRuntimeDepsResource(options.depsResourceUrl);
+	if (!declaration.ok) options.log?.error(`${OWN_PREFIX} ERROR — ${declaration.path} is unusable (${declaration.reason}); self-heal and the startup dependency audit are SKIPPED for this run (the plugin mounts, and every optional dependency keeps its own fallback)`);
 	const range = await readDependencyRange(fileURLToPath(import.meta.url));
 	const autoDownload = options.autoDownload ?? envDownloadsAllowed();
 	const deadlineMs = options.deadlineMs ?? DEADLINE_MS;
@@ -20001,9 +21274,15 @@ async function loadOnce(options) {
 	try {
 		compat = runtimeFromCompat(options.compatModule ?? framework);
 	} catch (error) {
-		warn(options.log, `${OWN_PREFIX} WARNING — the ${COMPAT_PACKAGE} compatibility gate could not be initialised (${reasonOf(error)}); the compatibility gate is SKIPPED and the plugin will mount anyway`);
+		warn(options.log, `${OWN_PREFIX} WARNING — the ${COMPAT_PACKAGE} compatibility gate could not be initialised (${reasonOf$2(error)}); the compatibility gate is SKIPPED and the plugin will mount anyway`);
 	}
 	let disposed = false;
+	/** The shared `runtime-deps` handles: set when `provisionResources` declares each item. */
+	let deps;
+	let native;
+	/** The startup dependency audit and its notice registry; both exist once `provisionResources` ran. */
+	let audit;
+	let noticeRegistry;
 	return {
 		home,
 		kit: framework,
@@ -20012,40 +21291,148 @@ async function loadOnce(options) {
 			tools: join(home, "tools"),
 			models: join(home, "models")
 		},
-		provisionResources(plan, onSettled) {
+		runtimeDeps() {
+			return deps;
+		},
+		nativeDeps() {
+			return native;
+		},
+		depsResource() {
+			return declaration;
+		},
+		notices() {
+			return noticeRegistry;
+		},
+		async startDependencyAudit() {
+			if (audit === void 0) return;
+			try {
+				await audit.run();
+			} catch (error) {
+				warn(options.log, `${OWN_PREFIX} WARNING — the dependency audit failed (${reasonOf$2(error)}); notices stay silent`);
+			}
+		},
+		provisionResources(plan, onSettled, onFailure) {
 			if (disposed) return;
+			const canServe = supportsRuntimeDeps(framework);
+			const wantedDeps = plan.semanticDeps;
+			const wantedNative = plan.nativeDeps;
+			if (wantedDeps !== void 0 && !canServe) warn(options.log, `${OWN_PREFIX} WARNING — semantic self-heal is enabled but the loaded ${FRAMEWORK_PACKAGE} has no runtime-deps helper (it needs base >= 0.7.0 / interface v6); the item is SKIPPED and the plugin will mount anyway`);
+			if (wantedNative !== void 0 && !canServe) warn(options.log, `${OWN_PREFIX} WARNING — native self-heal is enabled but the loaded ${FRAMEWORK_PACKAGE} has no runtime-deps helper (it needs base >= 0.7.0 / interface v6); the item is SKIPPED and the plugin will mount anyway`);
 			const items = [];
 			if (plan.model !== void 0) items.push(modelItem(framework, plan.model));
-			if (items.length === 0) return;
+			/**
+			* Declare one shared item through the helper.
+			*
+			* The spec fields are forwarded verbatim (the helper copies them, so the content key cannot
+			* move under a mutating caller). Notices are NOT passed in: the helper's registry binds a line
+			* to its ITEM's state alone, while an audit entry may observe a package that no item
+			* of ours installs — so every notice is registered below, on one registry, from the audit.
+			*/
+			const declare = (itemId, spec, timeoutMs, label) => {
+				try {
+					const handle = framework.createRuntimeDeps({
+						namespace: PLUGIN,
+						itemId,
+						...spec
+					});
+					items.push(runtimeDepsItem(handle.item, timeoutMs));
+					return handle;
+				} catch (error) {
+					warn(options.log, `${OWN_PREFIX} WARNING — the shared ${label} runtime-deps item could not be declared (${reasonOf$2(error)}); self-heal for it is SKIPPED and the plugin will mount anyway`);
+					return;
+				}
+			};
+			if (wantedDeps !== void 0 && canServe) deps = declare(SEMANTIC_DEPS_ITEM, wantedDeps.spec, SEMANTIC_DEPS_ATTEMPT_TIMEOUT_MS, "semantic");
+			if (wantedNative !== void 0 && canServe) native = declare(NATIVE_DEPS_ITEM, wantedNative.spec, NATIVE_DEPS_ATTEMPT_TIMEOUT_MS, "native");
+			const handles = [deps, native].filter((handle) => handle !== void 0);
 			const maxItemTimeoutMs = items.reduce((max, item) => Math.max(max, item.policy?.timeoutMs ?? 0), 0);
-			const resources = framework.createProvisioner({
-				home,
-				envinitRange: range,
-				logger: provisionLogger(options.log),
-				policy: {
-					autoDownload: autoDownload ? { [framework.MODEL_CACHE_KIND]: plan.modelAutoDownload } : false,
-					deadlineMs: Math.max(deadlineMs, maxItemTimeoutMs),
-					mirrors: { archive: [...plan.archiveMirrors] }
+			/** The shared roots a module probe may resolve from, in declaration order (ready ones only). */
+			const roots = () => handles.map((handle) => handle.resolve()?.dir).filter((dir) => dir !== void 0 && dir !== "");
+			let resources;
+			if (items.length > 0) {
+				resources = framework.createProvisioner({
+					home,
+					envinitRange: range,
+					logger: provisionLogger(options.log),
+					policy: {
+						autoDownload: autoDownload ? {
+							[framework.MODEL_CACHE_KIND]: plan.modelAutoDownload,
+							...handles.length === 0 ? {} : { [framework.RUNTIME_DEPS_KIND]: true }
+						} : false,
+						deadlineMs: Math.max(deadlineMs, maxItemTimeoutMs),
+						mirrors: { archive: [...plan.archiveMirrors] }
+					}
+				});
+				resources.register(framework.binaryArchiveProvider());
+				resources.register(framework.modelCacheProvider());
+				if (handles.length > 0) resources.register(framework.runtimeDepsProvider());
+				resources.declare({
+					plugin: PLUGIN,
+					items
+				});
+				disposers.push(resources);
+			}
+			const inflight = new Set(items.map((item) => item.id));
+			const itemState = (id) => {
+				if (inflight.has(id)) return "pending";
+				if (resources === void 0) return "missing";
+				return dependencyStateOf(resources.resolve(id));
+			};
+			const notices = plan.dependencyAudit ?? [];
+			if (notices.length > 0) {
+				const createRegistry = framework.createSessionNotices;
+				if (typeof createRegistry !== "function") warn(options.log, `${OWN_PREFIX} WARNING — ${notices.length} dependency-audit entr(y/ies) are declared but the loaded ${FRAMEWORK_PACKAGE} has no session-notice registry (it needs base >= 0.7.0 / interface v6); no notice will be delivered`);
+				audit = createDependencyAudit({
+					probes: probesOf(notices, roots, itemState),
+					vectors: plan.vectorCount ?? (() => 0),
+					logger: {
+						info: (message) => {
+							options.log?.info(`${OWN_PREFIX} ${message}`);
+						},
+						warn: (message) => {
+							options.log?.warn(`${OWN_PREFIX} ${message}`);
+						}
+					}
+				});
+				if (typeof createRegistry === "function") {
+					noticeRegistry = createRegistry.call(framework, provisionLogger(options.log));
+					registerDependencyNotices({
+						registry: noticeRegistry,
+						notices,
+						audit
+					});
 				}
+			}
+			if (resources === void 0) return;
+			for (const handle of handles) handle.ensure(resources).catch((error) => {
+				warn(options.log, `${OWN_PREFIX} WARNING — the shared runtime-deps item could not be dispatched (${reasonOf$2(error)}); the plugin continues`);
 			});
-			resources.register(framework.binaryArchiveProvider());
-			resources.register(framework.modelCacheProvider());
-			resources.declare({
-				plugin: PLUGIN,
-				items
-			});
-			disposers.push(resources);
 			resources.ensure({
 				only: items.map((item) => item.id),
 				onSettled: (entry) => {
 					try {
-						onSettled(entry);
+						inflight.delete(entry.id);
+						const shared = handles.find((handle) => handle.item.id === entry.id)?.resolve();
+						const state = resources.resolve(entry.id);
+						onSettled(entry, shared !== void 0 ? shared.dir : state !== void 0 && state.state === "ready" ? state.handle.dir : void 0);
+						if (audit !== void 0) audit.run().catch((error) => {
+							warn(options.log, `${OWN_PREFIX} WARNING — the dependency audit after ${entry.id} failed (${reasonOf$2(error)})`);
+						});
 					} catch (error) {
-						warn(options.log, `${OWN_PREFIX} WARNING — the onSettled callback failed (${reasonOf(error)})`);
+						warn(options.log, `${OWN_PREFIX} WARNING — the onSettled callback failed (${reasonOf$2(error)})`);
 					}
 				}
 			}).catch((error) => {
-				warn(options.log, `${OWN_PREFIX} WARNING — declaring the background resources failed (${reasonOf(error)}); the plugin continues (tools stay registered)`);
+				warn(options.log, `${OWN_PREFIX} WARNING — declaring the background resources failed (${reasonOf$2(error)}); the plugin continues (tools stay registered)`);
+				inflight.clear();
+				if (audit !== void 0) audit.run().catch((auditError) => {
+					warn(options.log, `${OWN_PREFIX} WARNING — the dependency audit after a dispatch failure failed (${reasonOf$2(auditError)})`);
+				});
+				try {
+					onFailure?.(error);
+				} catch (callbackError) {
+					warn(options.log, `${OWN_PREFIX} WARNING — the onFailure callback failed (${reasonOf$2(callbackError)})`);
+				}
 			});
 		},
 		dispose() {
@@ -20682,6 +22069,26 @@ function degradedLegNote(value) {
 	const result = value?.result;
 	return result !== null && typeof result === "object" && result.degraded === true ? DEGRADED_LEG_NOTE : void 0;
 }
+/**
+* The paging sentence of a PURE TIME window (`mode:"time"`, RECALL_INTERFACE §2.4), as one line the
+* model can read without doing arithmetic: 「共 N 条，已显示 M 条，还有 K 条未显示」.
+*
+* The fields it spells out (`total` / `hits.length` / `remaining`) are already in the JSON block; the
+* sentence exists because a page of 50 out of a 286-row day otherwise looks like the whole day unless
+* the reader stops to compare four numbers. Emitted ONLY when something is left unseen — a window that
+* fits on its page needs no note, and `remaining` is 0 exactly then.
+*
+* Same rules as {@link degradedLegNote}: a SECOND block, appended after the parseable JSON one, and
+* absent whenever the payload is not a time result (including older hosts, which send no `remaining`).
+*/
+function timePageNote(value) {
+	const result = value?.result;
+	if (result === null || typeof result !== "object" || result.mode !== "time") return void 0;
+	const { total, remaining, hits } = result;
+	if (typeof total !== "number" || typeof remaining !== "number" || remaining <= 0) return void 0;
+	if (!Array.isArray(hits)) return void 0;
+	return `时间窗口共 ${String(total)} 条，已显示 ${String(hits.length)} 条，还有 ${String(remaining)} 条未显示。`;
+}
 /** The tool output spec registered on every mem tool. */
 const OUTPUT = {
 	schema: {
@@ -20693,10 +22100,15 @@ const OUTPUT = {
 			type: "text",
 			text: JSON.stringify(toWellFormedDeep(value), null, 2)
 		}];
-		const note = degradedLegNote(value);
-		if (note !== void 0) blocks.push({
+		const degraded = degradedLegNote(value);
+		if (degraded !== void 0) blocks.push({
 			type: "text",
-			text: note
+			text: degraded
+		});
+		const paging = timePageNote(value);
+		if (paging !== void 0) blocks.push({
+			type: "text",
+			text: paging
 		});
 		return blocks;
 	}
@@ -20954,6 +22366,22 @@ function hostLogger(ctx) {
 	};
 }
 /**
+* The host's agent registry (`ctx.agents`), read defensively.
+*
+* It is the one place this plugin learns whether a session is a top-level (owner) agent or a
+* worker/subagent, and that decision only decides whether a session NOTICE is delivered. The read is
+* deliberately structural ({@link isOwnerSession} takes `unknown`): a host may not load the agent
+* registry at all, and `agent/pre-step` itself is emitted by the agent loop, so an absent registry is
+* "cannot tell" — never a reason to throw on the prompt path.
+*/
+function agentRegistry(ctx) {
+	try {
+		return ctx.agents;
+	} catch {
+		return;
+	}
+}
+/**
 * Declare the expensive resources through the family framework, warm the tokenizer and the embedding
 * model, and continue initialisation as each item settles.
 *
@@ -20970,12 +22398,37 @@ function hostLogger(ctx) {
 * — `managedModelSpec` decides): the framework's root would then collect a copy nothing reads. In
 * that case, and whenever no item will warm the model, the warm is started here directly.
 *
+* **Optional dependency repair.** `mem:semantic-deps` (shared `runtime-deps` store) is declared only
+* when `semantic.self_heal.enabled` is on (`managedSemanticDepsSpec` decides). When it is present, the
+* semantic warm waits for BOTH items: the shared root has to exist before the backend chooses it, and
+* the model files have to be on disk before the pipeline opens them. On success the handle directory
+* is handed to the backend (`useSemanticModuleDir`) so the import comes from the verified shared root;
+* on failure the backend keeps its own optional-dependency resolution.
+*
+* SESSION NOTICES are NOT carried by these handles: they are the `audit` entries of the plugin's own
+* `res/runtime-deps.yaml`, registered on one registry (`env.notices()`) whose predicates read the
+* startup dependency audit's cached state (`deps_audit.ts`). That is why a repair that is still
+* installing cannot be reported as a failure, and why an entry about a PACKAGE (rather than an item)
+* can be delivered at all.
+*
+* **NATIVE optional dependency repair.** `mem:native-deps` (a SEPARATE `runtime-deps` item: different
+* package set ⇒ different content-addressed root) repairs `nodejieba` and `hnswlib-node` when
+* `semantic.native_self_heal.enabled` is on. When it is present the TOKENIZER warm is deferred to its
+* settlement: the dictionary parse (~1 s, synchronous) has to happen once, from the root the process
+* will actually use, not from a tree that is about to be superseded. On success both module roots are
+* handed to their loaders (`useTokenizerModuleDir`, `MemoryStore.useNativeModuleDir`).
+*
 * Outcomes handled below:
 *
 *   - `mem:model` settles (present/installed) → warm the semantic path from the managed root, now
 *     that the files are on disk. That ordering is the whole point: the runtime's constructor warm is
 *     deferred while the framework is up (`deferWarm`), so nothing can race the install, and the
 *     explicit warm here is what starts the model.
+*   - `mem:semantic-deps` settles (present/installed) → point the backend at the shared root, then
+*     warm. failed/skipped → keep the optional path and still warm. Either way the package's audit
+*     entry is refreshed, because the notice's other half is "is it loadable NOW".
+*   - `mem:native-deps` settles → hand both module roots over, refresh the two native audit entries,
+*     then warm the tokenizer (or retry it, when an earlier lazy write already failed).
 *   - `mem:model` failed/skipped → one WARNING, then STILL warm: with `semantic.auto_download` on the
 *     runtime takes its own download path, and with it off the semantic leg degrades to FTS+entity.
 *     Either way the mount is untouched.
@@ -20989,20 +22442,65 @@ function hostLogger(ctx) {
 function startManagedResources(env, rt, logger, waitFor) {
 	const { semantic, tools } = rt.config.common;
 	const model = managedModelSpec(semantic, env.roots.models);
+	const loaded = env.depsResource();
+	const spec = loaded.ok ? loaded.resource : void 0;
+	const depsSpec = spec === void 0 ? void 0 : managedSemanticDepsSpec(semantic, spec.semantic, env.home);
+	const semanticDeps = depsSpec === void 0 ? void 0 : { spec: depsSpec };
+	const nativeSpec = spec === void 0 ? void 0 : managedNativeDepsSpec(semantic, spec.native, env.home);
+	const nativeDeps = nativeSpec === void 0 ? void 0 : { spec: nativeSpec };
 	const plan = {
 		archiveMirrors: tools.mirror,
 		modelAutoDownload: semantic.auto_download,
-		model
+		model,
+		semanticDeps,
+		nativeDeps,
+		dependencyAudit: managedDependencyAudit(spec?.audit),
+		vectorCount: () => rt.memory.liveVectorCount()
+	};
+	const waitsForNative = nativeDeps !== void 0 && supportsRuntimeDeps(env.kit);
+	let tokenizerWarmStarted = false;
+	const warmTokenizer = () => {
+		if (tokenizerWarmStarted) return;
+		tokenizerWarmStarted = true;
+		warmTokenizerAsync(rt, { ...waitFor === void 0 ? {} : { waitFor } });
 	};
-	warmTokenizerAsync(rt, { ...waitFor === void 0 ? {} : { waitFor } });
-	if (model === void 0 && semantic.backend === "local_bge") warmSemanticAsync(rt);
-	env.provisionResources(plan, (entry) => {
-		if (entry.id === "mem:model") warmSemanticAsync(rt);
+	if (!waitsForNative) warmTokenizer();
+	const pending = /* @__PURE__ */ new Set();
+	if (model !== void 0) pending.add(MODEL_ITEM);
+	if (semanticDeps !== void 0 && supportsRuntimeDeps(env.kit)) pending.add(SEMANTIC_DEPS_ITEM);
+	const warmOnce = () => {
+		if (pending.size === 0) warmSemanticAsync(rt);
+	};
+	if (pending.size === 0 && semantic.backend === "local_bge") warmSemanticAsync(rt);
+	env.provisionResources(plan, (entry, handleDir) => {
+		if (entry.id === "mem:model" || entry.id === "mem:semantic-deps") {
+			if (entry.id === "mem:semantic-deps" && handleDir !== void 0) {
+				rt.memory.useSemanticModuleDir(handleDir);
+				logger.info(`envinit: semantic deps root ${handleDir}`);
+			}
+			pending.delete(entry.id);
+			warmOnce();
+		}
+		if (entry.id === "mem:native-deps") {
+			if (handleDir !== void 0) {
+				useTokenizerModuleDir(handleDir);
+				rt.memory.useNativeModuleDir(handleDir);
+				logger.info(`envinit: native deps root ${handleDir}`);
+			}
+			warmTokenizer();
+		}
 		if (entry.action === "failed" || entry.action === "skipped") {
 			logger.warn(`envinit: ${entry.id} is ${entry.action} (${String(entry.code)}${entry.reason === void 0 ? "" : ` — ${entry.reason}`})`);
+			if (entry.id === "mem:semantic-deps") logger.warn("envinit: semantic self-heal did not complete — the runtime keeps its own optional-dependency resolution, and retrieval degrades to FTS+entity if that is absent too");
+			if (entry.id === "mem:native-deps") logger.warn("envinit: native self-heal did not complete — the runtime keeps its own optional-dependency resolution; entity/triple extraction falls back to the regex path and the vector store stays brute-force");
 			return;
 		}
 		logger.info(`envinit: ${entry.id} ${entry.action} (${entry.source}${entry.version === void 0 ? "" : ` ${entry.version}`})`);
+	}, (error) => {
+		logger.warn(`envinit: dispatching the background resources failed (${describeError$1(error)}); warming from the runtime's own paths`);
+		pending.clear();
+		warmOnce();
+		warmTokenizer();
 	});
 }
 async function apply(ctx, config) {
@@ -21130,7 +22628,7 @@ async function apply(ctx, config) {
 	}
 	for (const warning of promptTextWarnings(promptSections)) logger.warn(`prompt text: ${warning}`);
 	logger.info(`prompt files: ${promptDir} (${loadedPrompts.map((entry) => `${entry.file}:${entry.source}`).join(", ")})`);
-	ctx.on("agent/pre-step", async ({ signal }, next) => {
+	ctx.on("agent/pre-step", async ({ agent, signal }, next) => {
 		const decision = await next();
 		if (decision.kind === "reject" || signal.aborted) return decision;
 		const text = freshUserText(decision.messages);
@@ -21141,18 +22639,22 @@ async function apply(ctx, config) {
 		} catch {
 			hit = false;
 		}
-		if (!hit) return decision;
+		const sessionId = String(agent.id);
+		const owner = isOwnerSession(agentRegistry(ctx), sessionId);
+		const notices = noticeLines(env?.notices(), sessionId, owner);
+		const injection = stepInjection(hit, notices);
+		if (injection === "") return decision;
 		return {
 			...decision,
 			messages: [...decision.messages, createUserMessage({
 				content: [{
 					type: "text",
-					text: RELEVANCE_HINT
+					text: injection
 				}],
 				source: {
 					kind: "mem-hint",
 					form: "notice",
-					summary: RELEVANCE_HINT
+					summary: injection
 				}
 			})]
 		};
@@ -21179,6 +22681,7 @@ async function apply(ctx, config) {
 		log: logger,
 		compat
 	});
+	env?.startDependencyAudit();
 	ctx.effect(() => async () => {
 		logger.info("plugin unmount: disposing runtime (closing databases)");
 		await rt.shutdown();