dsh-memu-memory 1.1.3 → 1.2.1

package/lib/graph.js

@@ -1,6 +1,6 @@
 import path from 'node:path'
-import { indexDir, readJsonStrict, writeJson, withFileLock, stamp } from './paths.js'
-import { loadPrivateIndex, updatePrivateIndex, newMemoryId } from './state.js'
+import { indexDir, readJsonStrict, writeJson, withFileLock, stamp, warn } from './paths.js'
+import { loadPrivateIndex, updatePrivateIndex, newMemoryId, listLibraries } from './state.js'
 import { resolveLibrary, sessionIdOf, visibleToSession, isMemoryEligible, decayStrength } from './memory.js'
 
 export const LINK_KINDS = ['relation', 'commitment', 'event', 'person', 'conflict']
@@ -60,6 +60,16 @@ export function restoreGraphData(libraryId, data, memoryIdMap) {
     if (!evidenceIds.length) continue
     updateRelationship({ libraryId, fromId: entityMap[relationship.fromId], toId: entityMap[relationship.toId], state: relationship.state, evidenceIds, reason: relationship.reason || 'Imported relationship with explicit evidence.' })
   }
+  // A backup carries the whole entity store, but only the memories that made it
+  // through the export/import mapping come back, so entities nothing points at
+  // any more would sit in the file forever as invisible weight. Collect them
+  // once the remap is done; a prune failure must not fail a restore that
+  // already succeeded, and the startup sweep would catch it on the next launch.
+  try {
+    pruneOrphanEntities(scope.libraryId)
+  } catch (error) {
+    warn(`orphan entity prune after graph restore skipped: ${error?.message || error}`)
+  }
 }
 
 export function createEntity({ exec, libraryId, name, kind = 'person', aliases = [] }) {
@@ -102,6 +112,119 @@ export function renameEntity({ libraryId, entityId, name, aliases = [] }) {
   })
 }
 
+// What keeps an entity alive. Edges only live in one direction: an entry's
+// links[] names the entity, the entity stores nothing back. On top of that,
+// relationship snapshots (same file, keyed by the endpoint pair) describe the
+// pair with history and evidence that outlive the individual entries — deleting
+// an endpoint would leave a snapshot whose endpoints no longer resolve, so a
+// snapshot counts as a reference too. An entity referenced by neither is an
+// *orphan*: unreachable except as a graph placeholder, and safe to collect.
+// Orphans come from old builds whose permanent delete dropped the memory row
+// without cascading, and from partial backups.
+
+/**
+ * Remove every entity in one library that no entry links to and no relationship
+ * snapshot references. Idempotent: on healthy data it writes nothing. Returns
+ * `{ removed, total }` with the removed entity ids.
+ */
+export function pruneOrphanEntities(libraryId) {
+  const scope = scopeFor({ libraryId })
+  const file = entitiesPath(scope.libraryId)
+  return withFileLock(file, () => {
+    const store = readEntities(scope.libraryId)
+    const ids = Object.keys(store.entities)
+    if (!ids.length) return { removed: [], total: 0 }
+    const referenced = new Set()
+    for (const entry of Object.values(loadPrivateIndex(scope.libraryId).entries || {})) {
+      for (const link of entry.links || []) referenced.add(link.to)
+    }
+    for (const relationship of Object.values(store.relationships || {})) {
+      referenced.add(relationship.fromId)
+      referenced.add(relationship.toId)
+    }
+    const removed = ids.filter(id => !referenced.has(id))
+    // Write only when something actually goes, so the common case never touches
+    // the file (mtime-based caches, backups and concurrent readers all benefit).
+    if (removed.length) {
+      for (const id of removed) delete store.entities[id]
+      writeJson(file, store)
+    }
+    return { removed, total: ids.length }
+  })
+}
+
+/**
+ * The startup sweep: run pruneOrphanEntities over every active library. One
+ * corrupt store must not stop the rest, so per-library failures are collected
+ * instead of thrown; the caller decides how to log them. Archived libraries are
+ * deliberately left alone (frozen user data — restoring one runs the prune via
+ * restoreGraphData anyway). Returns `{ scanned, removed, failed }`.
+ */
+export function pruneOrphanEntitiesAll() {
+  const libraries = listLibraries()
+  const result = { scanned: libraries.length, removed: 0, failed: [] }
+  for (const library of libraries) {
+    try {
+      result.removed += pruneOrphanEntities(library.id).removed.length
+    } catch (error) {
+      result.failed.push({ libraryId: library.id, error: String(error?.message || error) })
+    }
+  }
+  return result
+}
+
+/**
+ * Delete an entity. This is graph bookkeeping, not a memory write: the entity
+ * row goes, no memory text is touched. An entity still referenced by links or
+ * relationship snapshots is refused by default — silently deleting it would
+ * turn every one of those edges into a `[deleted]` placeholder and rewrite what
+ * those memories are *about*. `force` deletes through that: inbound links are
+ * removed from every entry (not session-filtered — a link left behind in an
+ * entry this conversation cannot see would dangle exactly the way this guard
+ * exists to prevent, and the entry text itself is untouched) and relationship
+ * snapshots on the endpoints are dropped with their history, which is the loss
+ * `force` is asking for. Index links are cleaned before the entity row so a
+ * crash between the two writes leaves at worst a collectable orphan, never a
+ * link to an entity that is already gone.
+ */
+export function deleteEntity({ exec, libraryId, entityId, force = false }) {
+  const scope = scopeFor({ exec, libraryId })
+  if (!entityId || typeof entityId !== 'string') throw new Error('entityId is required')
+  const file = entitiesPath(scope.libraryId)
+  return withFileLock(file, () => {
+    const store = readEntities(scope.libraryId)
+    if (!store.entities[entityId]) throw new Error('unknown entity')
+    const index = loadPrivateIndex(scope.libraryId)
+    let inbound = 0
+    for (const entry of Object.values(index.entries || {})) {
+      for (const link of entry.links || []) if (link.to === entityId) inbound += 1
+    }
+    const relationshipKeys = Object.keys(store.relationships || {})
+      .filter(key => { const [from, to] = JSON.parse(key); return from === entityId || to === entityId })
+    if ((inbound || relationshipKeys.length) && !force) {
+      const parts = []
+      if (inbound) parts.push(`${inbound} link(s) point at it`)
+      if (relationshipKeys.length) parts.push(`${relationshipKeys.length} relationship snapshot(s) reference it`)
+      throw new Error(`entity is still referenced: ${parts.join(' and ')}; remove the links first or pass force to delete the entity with them`)
+    }
+    let removedLinks = 0
+    if (inbound) {
+      updatePrivateIndex(scope.libraryId, fresh => {
+        for (const entry of Object.values(fresh.entries)) {
+          if (!Array.isArray(entry.links) || !entry.links.some(link => link.to === entityId)) continue
+          const kept = entry.links.filter(link => link.to !== entityId)
+          removedLinks += entry.links.length - kept.length
+          entry.links = kept
+        }
+      })
+    }
+    for (const key of relationshipKeys) delete store.relationships[key]
+    delete store.entities[entityId]
+    writeJson(file, store)
+    return { entityId, deleted: true, removedLinks, removedRelationships: relationshipKeys.length }
+  })
+}
+
 export function linkEntries({ exec, libraryId, fromId, toId, kind, note, confidence = 0.7 }) {
   const scope = scopeFor({ exec, libraryId })
   if (!LINK_KINDS.includes(kind)) throw new Error(`link kind must be ${LINK_KINDS.join(', ')}`)
@@ -145,7 +268,7 @@ export function unlinkEntry({ libraryId, fromId, toId, kind }) {
   return { removed }
 }
 
-export function getGraph({ exec, libraryId, focusId = null, depth = 1, limit = 200 }) {
+export function getGraph({ exec, libraryId, focusId = null, depth = 1, limit = 200, includeOrphans = false }) {
   const scope = scopeFor({ exec, libraryId })
   const index = loadPrivateIndex(scope.libraryId)
   const entities = readEntities(scope.libraryId).entities
@@ -181,9 +304,16 @@ export function getGraph({ exec, libraryId, focusId = null, depth = 1, limit = 2
       frontier = next
     }
   } else {
+    // Orphan entities — no edge from any visible entry — are hidden by default.
+    // After the permanent-delete cascade and pruneOrphanEntities they should not
+    // exist on disk at all; a leftover from old data is invisible weight, and a
+    // session-scoped viewer already never saw them (the check below). Pass
+    // includeOrphans to see what an old entities.json still holds. An explicit
+    // focusId always wins: asking for a node by id is intent, not browsing.
     for (const id of [...visible, ...Object.keys(entities), ...adjacency.keys()]) {
       if (selected.size >= cap) break
       if (sessionIdOf(exec) && !visible.has(id) && !adjacency.has(id)) continue
+      if (!includeOrphans && entities[id] && !adjacency.has(id)) continue
       selected.add(id)
     }
   }
@@ -207,8 +337,12 @@ export function recallRelations(libraryId, index, id, sessionId) {
       const to = from === id ? link.to : from
       const target = index.entries[to]
       if (target && (!isMemoryEligible(target, { automatic: true }) || !visibleToSession(target, sessionId))) continue
-      if (!target && !entities[to]) continue
-      out.push({ id: to, title: target?.title || entities[to]?.name, kind: link.kind, note: String(link.note || '').slice(0, 80), confidence: link.confidence ?? 0.7 })
+      // A dangling edge (entry and entity both gone) used to be dropped here
+      // while getGraph rendered the same disk state as a [deleted] placeholder —
+      // the two views disagreed. Both now report the edge and mark it `missing`;
+      // the caller filters if it wants the old silence back.
+      const missing = !target && !entities[to]
+      out.push({ id: to, title: target?.title || entities[to]?.name || '[deleted]', kind: link.kind, note: String(link.note || '').slice(0, 80), confidence: link.confidence ?? 0.7, missing })
     }
   }
   return out.sort((a, b) => b.confidence - a.confidence).slice(0, 2)

package/lib/index.js

@@ -5,7 +5,8 @@ import { registerRpc } from './rpc.js'
 import { registerCycle } from './cycle.js'
 import { syncPromptDefaults } from './prompts.js'
 import { ensureEngine, engineStatus, ENGINE_VERSION } from './engine.js'
-import { getSettings, getMemoryBackend, backupDatabases, flushState } from './state.js'
+import { getSettings, getMemoryBackend, backupDatabases, flushState, listLibraries } from './state.js'
+import { pruneOrphanEntitiesAll } from './graph.js'
 import { closeEmbeddingWorkers } from './local-embedding-manager.js'
 import { bootstrapLocalVector } from './local-vector-service.js'
 import { vectorStatus } from './vector-profile.js'
@@ -62,6 +63,35 @@ function startEngineBootstrap(ctx) {
   }
 }
 
+// 兜底扫描（老数据升级）：旧版本的永久删除只删条目本身，别的条目 links 里指向它的
+// 入边和 entities.json 里的实体节点会留下来，restoreGraphData 的部分恢复也会。这里在
+// 启动后延迟跑一次全库 pruneOrphanEntitiesAll。选「每次启动延迟扫」而不是「首次
+// getGraph + 持久化已清理标记」：扫描只是对小 JSON 文件的读 + 偶尔一次原子写，健康
+// 数据零写入（no-op），幂等且能在任何一次删除路径将来回归时自愈；持久化标记省不下
+// 多少成本，反而多一个「标记存在但数据又坏了」的状态要维护。延迟 4 秒（在 1.5s 引擎
+// 引导与 2.5s 向量引导之后）让激活路径零阻塞；新安装没有库、没有实体，扫描直接 no-op。
+// 单库失败只收集不抛出，整段失败只 warn —— 加载绝不能被一次清理绊倒。
+function startOrphanEntitySweep(ctx) {
+  try {
+    const timer = setTimeout(() => {
+      try {
+        const result = pruneOrphanEntitiesAll()
+        for (const failure of result.failed) {
+          try { ctx.logger?.warn?.(`dsh-memu-memory: orphan entity sweep skipped ${failure.libraryId}: ${failure.error}`) } catch {}
+        }
+        if (result.removed > 0) {
+          try { ctx.logger?.info?.(`dsh-memu-memory: orphan entity sweep collected ${result.removed} node(s) across ${result.scanned} library(ies)`) } catch {}
+        }
+      } catch (error) {
+        try { ctx.logger?.warn?.(`dsh-memu-memory: orphan entity sweep failed: ${error?.message || error}`) } catch {}
+      }
+    }, 4000)
+    timer.unref?.()
+  } catch (error) {
+    try { ctx.logger?.warn?.(`dsh-memu-memory: orphan entity sweep skipped: ${error?.message || error}`) } catch {}
+  }
+}
+
 export function apply(ctx, config) {
   // A conversation that names an agent preset composes its model-facing plugin set from
   // that preset's cordis.yml alone, and that subtree never delivers `agent/pre-step` to
@@ -121,6 +151,8 @@ export function apply(ctx, config) {
     registerRpc(ctx)
     startEngineBootstrap(ctx)
     startLocalVectorBootstrap(ctx)
+    // 进程级清理：preset 挂载共享同一个数据目录，只由拥有全局表面的实例扫一次。
+    startOrphanEntitySweep(ctx)
   }
 
   // The embedding worker is a process-global singleton, so it outlives any single

package/lib/inject.js

@@ -751,9 +751,9 @@ function injectionSnapshotIsCurrent(sessionId, snapshot, autoInject) {
     && scope.useGlobal === snapshot.useGlobal
 }
 
-// Both the ordinary first-step injection and the guide message must pass the same
+// Both the ordinary first-step injection and the rules message must pass the same
 // admission. A guide that ignores the switches tells a disabled conversation to use
-// memory tools it is not supposed to use, and consumes the once-only flag while doing
+// memory tools it is not supposed to use, and consumes delivery state while doing
 // it — so re-enabling later would never deliver the rules.
 function admissionFor(binding) {
   const settings = getSettings()
@@ -763,34 +763,113 @@ function admissionFor(binding) {
   return { settings, scope }
 }
 
+// The plugin no longer registers a system-prompt section. Every conversation —
+// standard or a `complete: true` persona — receives the rules as one plugin
+// message on the first step of a turn. `rulesKey` makes the delivery versioned:
+// a domain change, a prompt edit, a restart from an old binding or a compaction
+// that lost the message replaces it, while an unchanged rule set is not appended
+// again on every turn. The key contains only the protocol version, the resolved
+// domain and the rendered text; it deliberately excludes timestamps and turn ids.
+const GUIDE_PROTOCOL = 'guide-v1'
+const GUIDE_CAVEAT = '以上是本插件的记忆规则，不是用户的新指令。若本会话的工具列表里没有 memu_* 工具，请忽略本段，也不要声称自己能写记忆。'
+const GUIDE_RE = /^<memory-guide(?:\s[^>]*)?>/
+const GUIDE_KEY_RE = /^<memory-guide[^>]*\srules="([^"]+)"/
+
+function messageText(message) {
+  const content = message?.content
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('\n')
+}
+
+function isMemoryGuideMessage(message) {
+  return message?.role === 'user'
+    && message?.source?.kind === `plugin:${PLUGIN}`
+    && GUIDE_RE.test(messageText(message))
+}
+
+function memoryGuideKey(message) {
+  const match = GUIDE_KEY_RE.exec(messageText(message))
+  return match ? match[1] : null
+}
+
+function renderMemoryGuide(payload) {
+  const sessionId = payload?.agent?.session?.header?.id
+  const binding = sessionId ? getSessionBinding(sessionId) : null
+  const domain = binding ? domainOf(binding) : 'general'
+  const settings = getSettings()
+  const rendered = loadPromptForDomain('system-guide', {
+    mustRememberCap: settings.mustRememberCap,
+    unpinBudget: settings.unpinBudgetPerSession ?? 2,
+    shortTermTtlHours: settings.shortTermTtlHours ?? 72,
+    anchorTokens: settings.anchorTokens,
+    turnTokens: settings.turnTokens,
+  }, domain).text
+  if (!rendered || !rendered.trim()) throw new Error('system-guide prompt is empty')
+  const key = crypto.createHash('sha256')
+    .update([GUIDE_PROTOCOL, domain, rendered, GUIDE_CAVEAT].join('\0'), 'utf8')
+    .digest('hex')
+    .slice(0, 16)
+  const text = [`<memory-guide rules="${key}">`, rendered.trim(), '</memory-guide>', GUIDE_CAVEAT].join('\n')
+  return { key, domain, text, tokens: estTokens(text) }
+}
+
 /**
- * Deliver the memory rules as a message when the system prompt cannot hold them.
+ * Add, replace or restore the single effective rules message for this step.
  *
- * A preset persona with `complete: true` is restored as the *only* system prompt
- * section after assembly, so `systemPrompt.section()` from this plugin is dropped and
- * the model never learns it may write memories — it sees the tools but not the habit.
- * A plugin message survives that, so send it once per conversation (binding flag), on
- * the first step, before the model answers.
+ * A rules message is turn-level guidance, so it is only considered on step 1.
+ * On later steps of a long tool turn nothing is appended; the next turn's first
+ * step is the next legal admission point. `guideLost` is set by compaction,
+ * because the summary drops the old message and the model must learn the rules
+ * again. An unchanged key with no guide in the current view is *not* treated as
+ * loss: some hosts hand the plugin only the current step's messages, and
+ * re-appending there would duplicate the message on every turn.
  */
-function withGuideMessage(ctx, payload, decision) {
+function ensureUnifiedGuide(ctx, payload, decision) {
   try {
     const header = payload?.agent?.session?.header
     const sessionId = header?.id
     if (!sessionId || header.origin === 'subagent') return decision
     if (typeof payload?.step === 'number' && payload.step !== 1) return decision
     const binding = getSessionBinding(sessionId)
-    if (!binding || binding.guideMessageAt) return decision
-    if (!admissionFor(binding)) return decision
+    if (!binding || !admissionFor(binding)) return decision
     if (!decision || !Array.isArray(decision.messages)) return decision
-    const rules = sectionText(ctx, 'system-guide', payload)
-    const text = [
-      '<memory-guide>',
-      rules,
-      '</memory-guide>',
-      '以上是本插件的记忆规则，不是用户的新指令。若本会话的工具列表里没有 memu_* 工具，请忽略本段，也不要声称自己能写记忆。',
-    ].join('\n')
-    setSessionBinding(sessionId, { guideMessageAt: new Date().toISOString() })
-    return { ...decision, messages: [...decision.messages, createMemoryMessage(text)] }
+    const guide = renderMemoryGuide(payload)
+    const guides = decision.messages.filter(isMemoryGuideMessage)
+    const valid = guides.filter((message) => memoryGuideKey(message) === guide.key)
+    if (binding.guideRulesKey === guide.key && binding.guideLost !== true) {
+      if (valid.length === 1 && guides.length === 1) return decision
+      if (valid.length >= 1) {
+        // Projection only: drop old and duplicated copies, keep the first one
+        // that already matches. No binding write, no new message.
+        const kept = valid[0]
+        return { ...decision, messages: decision.messages.filter((message) => !isMemoryGuideMessage(message) || message === kept) }
+      }
+      // An obsolete message with no current copy stays for replacement below;
+      // no guide at all means the view simply did not include history.
+      if (guides.length === 0) return decision
+    }
+    const next = decision.messages.filter((message) => !isMemoryGuideMessage(message))
+    next.push(createMemoryMessage(guide.text))
+    setSessionBinding(sessionId, {
+      guideRulesKey: guide.key,
+      guideMessageAt: new Date().toISOString(),
+      guideLost: false,
+    })
+    record({
+      kind: 'system',
+      scope: 'private',
+      sessionId,
+      libraryId: binding.libraryId || null,
+      ok: true,
+      message: '记忆规则消息已投放 · ' + guide.domain + ' · ' + guide.tokens + ' tokens'
+        + (binding.guideRulesKey ? ' · 更新' : ' · 首次'),
+      detail: { rulesKey: guide.key, domain: guide.domain, tokens: guide.tokens, replaced: guides.length },
+    })
+    return { ...decision, messages: next }
   } catch (error) {
     try { ctx.logger?.warn?.(`dsh-memu-memory: guide message skipped: ${error?.message || error}`) } catch {}
     return decision
@@ -1083,62 +1162,8 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
   return { ...decision, messages: rewritten }
 }
 
-/**
- * Section text must never throw. A missing default prompt file or an unknown key
- * would otherwise break setPrompt assembly for *every* conversation, which takes
- * the whole harness down rather than just memory. Fall back variant -> base ->
- * one line, and log.
- */
-function sectionText(ctx, key, context) {
-  try {
-    const sessionId = context?.agent?.session?.header?.id || context?.session?.header?.id || null
-    const binding = sessionId ? getSessionBinding(sessionId) : null
-    return loadPromptForDomain(key, {
-      mustRememberCap: getSettings().mustRememberCap,
-      unpinBudget: getSettings().unpinBudgetPerSession ?? 2,
-      shortTermTtlHours: getSettings().shortTermTtlHours ?? 72,
-      // the coding variants talk about the anchor budget in tokens, so the number
-      // has to come from the live settings and not from a literal in the prompt
-      anchorTokens: getSettings().anchorTokens,
-      turnTokens: getSettings().turnTokens,
-    }, binding ? domainOf(binding) : 'general').text
-  } catch (error) {
-    try { ctx.logger?.warn?.(`dsh-memu-memory: ${key} prompt unavailable: ${error?.message || error}`) } catch {}
-    return '（记忆规则暂时不可用：插件内部错误，不要向用户提及这一段。）'
-  }
-}
-
-export function registerInjection(ctx, options = {}) {
+export function registerInjection(ctx) {
   const disposers = []
-  // `guide: false` is how a *preset* conversation gets the memory anchor without being
-  // told about tools its preset never mounted — the guide text references memu_* tools,
-  // and a preset that does not list this plugin has no such tools.
-  const wantGuide = options.guide !== false
-  // `guideMessage` exists for conversations whose preset persona uses `complete: true`:
-  // that flag makes the persona the only system prompt section, so a section injected
-  // here is discarded before the model ever sees it. A plugin message still arrives, so
-  // the rules are delivered once per conversation as text instead of as a section.
-  const guideInMessage = options.guideMessage === true
-  if (wantGuide) {
-    try {
-      ctx.inject(['systemPrompt'], (sctx) => {
-        sctx.effect(() => sctx.systemPrompt.section({
-          name: 'dsh-memu-memory:guide',
-          order: 320,
-          interpolate: false,
-          text: (context) => sectionText(sctx, 'system-guide', context),
-        }), 'dsh-memu-memory: guide prompt')
-        sctx.effect(() => sctx.systemPrompt.section({
-          name: 'dsh-memu-memory:private-policy',
-          order: 321,
-          interpolate: false,
-          text: (context) => sectionText(sctx, 'private-policy', context),
-        }), 'dsh-memu-memory: private policy prompt')
-      })
-    } catch (e) {
-      try { ctx.logger?.warn?.(`dsh-memu-memory: systemPrompt guide unavailable: ${e?.message || e}`) } catch {}
-    }
-  }
 
   const offPre = ctx.on('agent/pre-step', async (payload, next) => {
     const decision = await next()
@@ -1149,7 +1174,7 @@ export function registerInjection(ctx, options = {}) {
         ctx,
         log: (message) => { try { ctx.logger?.warn?.(`dsh-memu-memory: ${message}`) } catch {} },
       })
-      return guideInMessage ? withGuideMessage(ctx, payload, injected) : injected
+      return ensureUnifiedGuide(ctx, payload, injected)
     } catch (error) {
       try { setRecallError(payload?.agent?.session?.header?.id, `injection failed: ${error?.message || error}`) } catch {}
       try { ctx.logger?.warn?.(`dsh-memu-memory: pre-step injection failed (fail-open): ${error?.stack || error}`) } catch {}
@@ -1173,6 +1198,9 @@ export function registerInjection(ctx, options = {}) {
             .slice(-REPLAY_MAX)
           releaseInjected(sessionId)
           markReinjectPending(sessionId)
+          // The compaction summary drops the plugin's rules message. Flag it so the
+          // next turn's first step replaces it even though guideRulesKey still matches.
+          if (before) setSessionBinding(sessionId, { guideLost: true })
           if (recent.length > 0) {
             setSessionBinding(sessionId, { replayIds: recent, replayAt: new Date().toISOString() })
           }

package/lib/local-embedding-manager.js

@@ -3,6 +3,7 @@ import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { assertProfileVerified } from './vector-profile.js'
 import { manifestModelId } from './local-embedding-worker.js'
+import { windowsSystemEnv } from './paths.js'
 
 const entry = fileURLToPath(new URL('./local-embedding-entry.js', import.meta.url))
 const failure = (code, message) => Object.assign(new Error(message), { code, fallback: 'lexical' })
@@ -21,16 +22,23 @@ const DEFAULT_WINDOW_MS = 60_000
 const DENIED_ENV_NAMES = Object.freeze(['http_proxy', 'https_proxy', 'all_proxy', 'no_proxy', 'node_options'])
 const DENIED_ENV_PREFIXES = Object.freeze(['memu_', 'dsh_memu_embed_', 'openai_', 'azure_openai_', 'anthropic_', 'gemini_', 'google_', 'cohere_'])
 
-function childEnvironment(extra) {
-  const env = {}
-  for (const [name, value] of Object.entries(process.env)) {
+// The system-variable overlay goes in *first* so a real host value always wins, and
+// only after it does the filtered copy of the host environment. The host can hand a
+// tool-spawned process an empty environment (docs/env-and-commands.md §9.1), and a
+// child that then resolves `%SystemDrive%\ProgramData\...` literally writes that
+// junk into its own cwd — which is how this repo once grew a "%SystemDrive%" folder.
+// The worker loads ONNX/DirectML and tokenizer native libraries from exactly that
+// kind of path, so it is the site that can least afford to miss the overlay.
+export function childEnvironment(extra, { platform = process.platform, env = process.env } = {}) {
+  const inherited = {}
+  for (const [name, value] of Object.entries(env || {})) {
     if (typeof value !== 'string') continue
     const lower = name.toLowerCase()
     if (DENIED_ENV_NAMES.includes(lower) || lower.includes('proxy')) continue
     if (DENIED_ENV_PREFIXES.some(prefix => lower.startsWith(prefix))) continue
-    env[name] = value
+    inherited[name] = value
   }
-  return { ...env, ...extra }
+  return { ...windowsSystemEnv(platform, env || {}), ...inherited, ...extra }
 }
 
 // One isolated native process per immutable profile. Tokens live only in memory and
@@ -125,8 +133,13 @@ export function createEmbeddingWorkerManager({ spawnImpl = spawn, executable = p
         abort(code, message)
         stopChild(record)
       }
+      // This timer is the only thing that turns "never reported ready" into the typed
+      // lexical fallback, so nothing may depend on the event loop being held open for
+      // another reason: an unconditional unref let acquire() stay pending forever whenever
+      // the child contributed no libuv handle of its own (a spawn stand-in, N2). It is
+      // dereferenced below only once the spawn proves a real child holds the process open,
+      // which is the sole case where this timer would merely delay shutdown.
       timer = setTimeout(() => fail('LOCAL_VECTOR_START_TIMEOUT', 'the local embedding worker did not become ready in time'), timeoutMs)
-      timer.unref?.()
       let child = null
       try {
         child = spawnImpl(executable, [entry], {
@@ -150,6 +163,11 @@ export function createEmbeddingWorkerManager({ spawnImpl = spawn, executable = p
         return
       }
       record.child = child
+      // A real child holds the process open by itself (stdio pipes and its own handle), so
+      // its boot timer need not; a stand-in without a pid holds nothing, and dereferencing
+      // the timer there would leave the timeout unable to fire. A spawn that fails reaches
+      // fail() through 'error'/'close' and clears the timer either way.
+      if (Number.isInteger(child?.pid) && child.pid > 0) timer.unref?.()
       // A worker that died turns the next stdin write into EPIPE. An unhandled 'error'
       // event on a child pipe is an uncaught exception in the host process, so every
       // pipe gets a sink: semantic recall degrades, the host does not go down with it.