@sanqianx/project-knowledge 5.0.26 → 5.0.28

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "project-knowledge",
-      "version": "5.0.26",
+      "version": "5.0.28",
       "source": "./plugins/project-knowledge",
       "description": "Search durable project decisions and implementation history through MCP."
     }

package/_modules/knowledge-engine/README.md

@@ -69,6 +69,7 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 | POST | `/api/bridge/notify` | 唤醒 journal 消费；通知丢失仍由轮询恢复 |
 | GET / PATCH | `/api/memories`、`/api/memories/:id` | 按 status/scopeType/scopeId 筛选；一次编辑内容、适用范围和确认状态；来源证据只读 |
 | POST | `/api/memories` | `{ text, brainId?, scopeType?, scopeId? }` → 手动添加已确认记忆；默认全局，领域/项目必须指定已登记目标，不接受伪造来源 |
+| DELETE | `/api/memories/:id` | 软删除为无正文墓碑：默认列表与新任务不再使用，原始对话与知识来源保留；重复删除返回 404；完整契约见下方记忆删除边界 |
 | POST | `/api/scopes` | 外壳投影智脑、领域共享目录；受运行期鉴权保护 |
 | POST | `/api/runtime-config` | 运行期模型配置，仅保留在内存；受鉴权保护 |
 | GET | `/api/runtime-auth` | 本机服务确认运行期鉴权；受鉴权保护，不对浏览器反代 |
@@ -109,6 +110,7 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 - 长期记忆统一保存在已绑定的智脑共享目录：`memories/confirmed.md`（全局）、`memories/domains/<id>.md`、`memories/projects/<id>.md`。不创建第二份项目知识目录。现有 v5 缺少范围字段的记忆仍按全局解释；不读取 pre-v5 状态、不重扫历史。
 - 手动记忆以用户确认作为来源，记录 `sourceType: manual`、`evidence: null`，不伪造提交或分析运行。内容限制为 1–2000 字符，同范围内容去重；创建、编辑、投影与恢复复用引擎受控写入。空项目列表也可添加全局记忆，但必须已绑定共享目录；无需模型分析或 Git 提交，索引状态独立报告。
 - 任务检索只允许当前项目、当前所属领域与全局的已确认记忆，即使检索整个智脑也不放宽专属记忆范围。过滤在排名之前完成，`get` 同样校验；向量旧内容不能绕过当前状态和文件一致性校验。已确认记录修改范围会同步清理旧投影；写入失败显示待同步并自动重试，未同步文件不能进入上下文。
+- 删除记忆写入无正文墓碑记录：删除后默认列表与新任务上下文不再使用该记忆，原始对话与知识来源保持保留；同文本的自动候选按墓碑去重不会复活，同一适用范围仍可手动重加；重复删除返回 404；派生记忆文件写入失败时如实记录待同步并自动重试，不伪造一致状态。
 - 旧格式不读取、不自动迁移。损坏的正式状态不覆盖、不清空。
 - 引擎状态复用受控原子写入：独占随机临时文件、文件同步、Windows 短暂共享冲突有界重试；永久失败保留原状态并清理本次临时文件，绝不先删正式状态。
 

package/_modules/knowledge-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/ai-coding-knowledge-engine",
-  "version": "0.2.7-rc.11",
+  "version": "0.2.7-rc.12",
   "description": "Knowledge engine module for project-knowledge: commit-boundary triggered knowledge analysis/generation (trigger plane) and retrieval for development assistants (retrieval plane).",
   "license": "Apache-2.0",
   "main": "src/server.js",

package/_modules/knowledge-engine/src/memories.js

@@ -96,7 +96,7 @@ class MemoryService {
   }
   list({ brainId, status, scopeType, scopeId } = {}) {
     if (scopeType && !TYPES.includes(scopeType)) throw new DomainError('INVALID_ARGUMENT', '记忆筛选范围无效。');
-    return this.store.state.memories.filter(m => (!brainId || m.brainId === brainId) && (!status || m.status === status) && (!scopeType || this.scopeOf(m).type === scopeType) && (!scopeId || this.scopeOf(m).id === scopeId)).map(m => this.project(m));
+    return this.store.state.memories.filter(m => (m.status !== 'deleted' || status === 'deleted') && (!brainId || m.brainId === brainId) && (!status || m.status === status) && (!scopeType || this.scopeOf(m).type === scopeType) && (!scopeId || this.scopeOf(m).id === scopeId)).map(m => this.project(m));
   }
   capture(run) {
     const report = { accepted: 0, deduplicated: 0, rejected: [] };
@@ -123,7 +123,15 @@ class MemoryService {
       const scopeType = raw.scopeType;
       const scopeId = scopeType === 'global' ? brainId : project.domainId;
       const key = fingerprint(brainId, scopeType, scopeId, text);
-      if (next.some(m => m.captureFingerprint === key || fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key || !m.scopeType && m.evidence?.projectId === project.projectId && normalized(m.originalText || m.text) === normalized(text))) { report.deduplicated++; continue; }
+      // Tombstones never hold text, so they dedup through their fingerprints:
+      // the fresh pair covers the record's last scope and text, while the kept
+      // original capture key still covers a pre-edit/pre-move scope.
+      const duplicateOf = m => {
+        if (m.captureFingerprint === key) return true;
+        if (m.status === 'deleted') return m.fingerprint === key || m.originalCaptureFingerprint === key;
+        return fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key || !m.scopeType && m.evidence?.projectId === project.projectId && normalized(m.originalText || m.text) === normalized(text);
+      };
+      if (next.some(duplicateOf)) { report.deduplicated++; continue; }
       next.push({ id: `memory-${crypto.randomUUID()}`, fingerprint: key, captureFingerprint: key, brainId, domainId: project.domainId || null, scopeType, scopeId, text, originalText: text, status: 'candidate', sourceEventId: provenance.sourceEventId, sourceHash: provenance.sourceHash, eligibility: provenance.eligibility, evidence: { projectId: project.projectId, commitSha: run.commitSha, runId: run.runId, entryId, quote }, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
       report.accepted++;
     }
@@ -145,7 +153,9 @@ class MemoryService {
       this.validateScope(type, targetId, brainId);
       if (!this.brainScope(brainId)) throw new DomainError('INVALID_ARGUMENT', '请先绑定智脑共享目录。', { status: 409 });
       const text = input.text.trim(), key = fingerprint(brainId, type, targetId, text);
-      if (this.store.state.memories.some(m => fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key)) throw new DomainError('MEMORY_DUPLICATE', '该范围内已存在相同记忆。', { status: 409 });
+      // An explicit manual add is the user changing their mind after a delete:
+      // tombstones never block it, only another live record in the same scope does.
+      if (this.store.state.memories.some(m => m.status !== 'deleted' && fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key)) throw new DomainError('MEMORY_DUPLICATE', '该范围内已存在相同记忆。', { status: 409 });
       // User confirmation is the provenance; never invent a model run or Git commit.
       const now = new Date().toISOString();
       const memory = { id: `memory-${crypto.randomUUID()}`, fingerprint: key, brainId, scopeType: type, scopeId: targetId, sourceType: 'manual', text, originalText: text, status: 'confirmed', evidence: null, createdAt: now, updatedAt: now };
@@ -162,7 +172,7 @@ class MemoryService {
     if (Object.keys(input).some(key => !['text', 'status', 'scopeType', 'scopeId'].includes(key))) throw new DomainError('INVALID_ARGUMENT', '来源证据和文件路径不能修改。');
     const job = AtomicFile.withFileLock(this.lock(), async () => {
       const memory = this.store.state.memories.find(m => m.id === id);
-      if (!memory) throw new DomainError('PROJECT_NOT_FOUND', '记忆不存在。', { status: 404 });
+      if (!memory || memory.status === 'deleted') throw new DomainError('PROJECT_NOT_FOUND', '记忆不存在。', { status: 404 });
       if (input.text !== undefined && (typeof input.text !== 'string' || !input.text.trim() || input.text.length > 2000)) throw new DomainError('INVALID_ARGUMENT', '记忆内容必须为 1–2000 个字符。');
       if (input.status !== undefined && !['confirmed', 'ignored'].includes(input.status)) throw new DomainError('INVALID_ARGUMENT', '记忆状态无效。');
       if (memory.status === 'ignored') throw new DomainError('INVALID_ARGUMENT', '该候选已忽略。', { status: 409 });
@@ -172,7 +182,7 @@ class MemoryService {
       if (input.status !== 'ignored' || input.scopeType !== undefined || input.scopeId !== undefined) this.validateScope(type, targetId, brainId);
       if ((input.status || memory.status) === 'confirmed' && !this.brainScope(brainId)) throw new DomainError('INVALID_ARGUMENT', '请先绑定智脑共享目录。', { status: 409 });
       const text = input.text?.trim() || memory.text, key = fingerprint(brainId, type, targetId, text);
-      if (this.store.state.memories.some(m => m.id !== id && fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key)) throw new DomainError('MEMORY_DUPLICATE', '该范围内已存在相同记忆。', { status: 409 });
+      if (this.store.state.memories.some(m => m.id !== id && m.status !== 'deleted' && fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key)) throw new DomainError('MEMORY_DUPLICATE', '该范围内已存在相同记忆。', { status: 409 });
       const next = { ...memory, originalText: memory.originalText || memory.text, captureFingerprint: memory.captureFingerprint || fingerprint(brainId, old.type, old.id, memory.originalText || memory.text), fingerprint: key, scopeType: type, scopeId: targetId, text, status: input.status || memory.status, updatedAt: new Date().toISOString() };
       const before = this.store.state.memories;
       this.store.state.memories = before.map(m => m.id === id ? next : m);
@@ -182,6 +192,41 @@ class MemoryService {
     this.writes.add(job);
     try { return await job; } finally { this.writes.delete(job); }
   }
+  async remove(id) {
+    if (this.closed) throw new DomainError('PROJECT_BUSY', '引擎正在关闭，请稍后重试。', { status: 409 });
+    if (typeof id !== 'string' || !id.trim()) throw new DomainError('INVALID_ARGUMENT', '记忆 ID 无效。');
+    const job = AtomicFile.withFileLock(this.lock(), async () => {
+      const memory = this.store.state.memories.find(m => m.id === id);
+      if (!memory || memory.status === 'deleted') throw new DomainError('PROJECT_NOT_FOUND', '记忆不存在。', { status: 404 });
+      const brainId = memory.brainId || 'brain-default', scope = this.scopeOf(memory);
+      // A tombstone keeps only the dedup fingerprints and audit metadata; the
+      // text and quote are dropped so a deleted memory never returns through
+      // lists, markdown, retrieval or context injection, and the fingerprints
+      // stop the same candidate from coming back on the next capture. Legacy
+      // records may predate originalText/captureFingerprint/createdAt, so both
+      // keys are always computed from the live record, and a stored original
+      // capture key from before an edit or scope move is preserved separately.
+      const now = new Date().toISOString();
+      const captureKey = fingerprint(brainId, scope.type, scope.id, memory.originalText || memory.text);
+      const originalCaptureKey = typeof memory.captureFingerprint === 'string' && /^[a-f0-9]{64}$/.test(memory.captureFingerprint) && memory.captureFingerprint !== captureKey ? memory.captureFingerprint : null;
+      const tombstone = {
+        id: memory.id, brainId, scopeType: scope.type, scopeId: scope.id,
+        ...(memory.sourceType !== undefined ? { sourceType: memory.sourceType } : {}),
+        status: 'deleted',
+        fingerprint: fingerprint(brainId, scope.type, scope.id, memory.text),
+        captureFingerprint: captureKey,
+        ...(originalCaptureKey ? { originalCaptureFingerprint: originalCaptureKey } : {}),
+        evidence: memory.evidence ? { projectId: memory.evidence.projectId, commitSha: memory.evidence.commitSha, runId: memory.evidence.runId || null, entryId: memory.evidence.entryId || '' } : null,
+        createdAt: typeof memory.createdAt === 'string' && Number.isFinite(Date.parse(memory.createdAt)) ? memory.createdAt : now, updatedAt: now, deletedAt: now,
+      };
+      const before = this.store.state.memories;
+      this.store.state.memories = before.map(m => m.id === id ? tombstone : m);
+      try { this.store.save(); } catch (error) { this.store.state.memories = before; throw error; }
+      await this.materialize(); return this.project(tombstone);
+    });
+    this.writes.add(job);
+    try { return await job; } finally { this.writes.delete(job); }
+  }
   content(brainId, entry = 'memories/confirmed.md') {
     return '# 已确认的长期记忆\n\n' + this.confirmed(brainId, entry).map(m => {
       const scope = this.scopeOf(m);

package/_modules/knowledge-engine/src/server.js

@@ -115,6 +115,11 @@ async function api(method, pathname, search, body, store, coordinator, ctx) {
     coordinator.emit('progress', store.addEvent({ type: 'memory.updated', summary: memory.status === 'confirmed' ? '已确认长期记忆' : memory.status === 'ignored' ? '已忽略记忆候选' : '已编辑记忆候选' }));
     return { memory };
   }
+  if (method === 'DELETE' && memoryMatch) {
+    const memory = await coordinator.memories.remove(decodeURIComponent(memoryMatch[1]));
+    coordinator.emit('progress', store.addEvent({ type: 'memory.deleted', summary: '已删除长期记忆' }));
+    return { memory };
+  }
   if (method === 'POST' && pathname === '/api/projects') {
     const result = store.addProject(body);
     if (!result.reused) store.addEvent({ type: 'project.register', projectId: body.projectId, summary: `登记 ${result.project.name}` });

package/_modules/knowledge-engine/src/store.js

@@ -40,8 +40,18 @@ class EngineStore {
       for (const [journalId, sequence] of Object.entries(raw.journalCursors || {})) if (!/^(global|sha256:[a-f0-9]{64})$/.test(journalId) || !Number.isSafeInteger(sequence) || sequence < 0) throw new Error('Invalid journal cursor');
       for (const scope of raw.sharedScopes || []) if (!scope || !['brain', 'domain'].includes(scope.kind) || !path.isAbsolute(scope.knowledgePath || '')) throw new Error('Invalid shared scope');
       for (const memory of raw.memories || []) {
-        if (!memory || !['candidate', 'confirmed', 'ignored'].includes(memory.status) || typeof memory.text !== 'string' || memory.sourceType !== undefined && !['manual', 'agent'].includes(memory.sourceType)) throw new Error('Invalid memory record');
-        if (memory.sourceType === 'manual') {
+        if (!memory || !['candidate', 'confirmed', 'ignored', 'deleted'].includes(memory.status) || memory.sourceType !== undefined && !['manual', 'agent'].includes(memory.sourceType)) throw new Error('Invalid memory record');
+        if (memory.status === 'deleted') {
+          // Tombstones carry no text: the dedup fingerprint and audit metadata
+          // are the whole record, so validate those instead of the live shape.
+          validateProjectId(memory.brainId);
+          // R101: the `memory-` prefix is only a generation convention; records
+          // written before it (any stable non-empty string id, ASCII or
+          // Unicode) load and delete legally, and the id never reaches a file
+          // path — so the tombstone validates the same id contract they had.
+          if (typeof memory.id !== 'string' || !memory.id || typeof memory.fingerprint !== 'string' || !/^[a-f0-9]{64}$/.test(memory.fingerprint) || memory.captureFingerprint !== undefined && !/^[a-f0-9]{64}$/.test(memory.captureFingerprint) || memory.originalCaptureFingerprint !== undefined && !/^[a-f0-9]{64}$/.test(memory.originalCaptureFingerprint) || memory.evidence !== null && (!memory.evidence.projectId || !/^[a-f0-9]{40}$/.test(memory.evidence.commitSha || '')) || !Number.isFinite(Date.parse(memory.createdAt)) || !Number.isFinite(Date.parse(memory.deletedAt))) throw new Error('Invalid deleted memory record');
+        } else if (typeof memory.text !== 'string') throw new Error('Invalid memory record');
+        else if (memory.sourceType === 'manual') {
           validateProjectId(memory.brainId);
           if (memory.status === 'candidate' || !memory.text.trim() || memory.text.length > 2000 || !memory.scopeType || memory.evidence !== null || !Number.isFinite(Date.parse(memory.createdAt)) || !Number.isFinite(Date.parse(memory.updatedAt))) throw new Error('Invalid manual memory record');
         } else if (!memory.evidence?.projectId || !/^[a-f0-9]{40}$/.test(memory.evidence.commitSha || '')) throw new Error('Invalid memory evidence');

package/_site/_test/helpers/qa-r44-env.js

@@ -0,0 +1,418 @@
+'use strict';
+// _site/_test/helpers/qa-r44-env.js
+//
+// The R44 lane isolation helper (WB-006 / WB-007).
+//
+// Contract (from the lane dispatch):
+//   * the driver's FIRST action is to capture the real environment and the
+//     real tool paths, and then to harden the driver's OWN process.env, so
+//     that every child process it spawns inherits the isolation. The product
+//     is never bootstrapped under the real environment first;
+//   * HOME / USERPROFILE / HOMEDRIVE / HOMEPATH / APPDATA / LOCALAPPDATA /
+//     CODEX_HOME / CLAUDE_CONFIG_DIR / TEMP / TMP / TMPDIR are redirected;
+//   * KB_DATA_DIR and KB_KNOWLEDGE_DATA_DIR are redirected;
+//   * the Workbench data dir and the Bridge home are redirected;
+//   * the temp root lives OUTSIDE the repository;
+//   * the ambient module addresses and every ambient model credential are
+//     dropped, so a call can only reach the profile the product resolves
+//     itself, in memory;
+//   * the live product ports are refused.
+//
+// The real Chrome executable and the real Claude Code executable are captured
+// BEFORE the environment is hardened (the R33 lesson: Chrome and the CLI are
+// resolved from LOCALAPPDATA / APPDATA, and those are exactly the variables
+// this lane isolates). They are re-published to the isolated environment as
+// KB_CHROME_PATH and CLAUDE_CODE_EXECPATH, so the isolation never turns into
+// a "tool not found" failure.
+//
+// Credential contract: no credential value is read, copied, logged, written
+// to a fixture or reported. Only variable NAMES are ever recorded.
+//
+// R44C: the lane no longer depends on the older batch fixture. It uses the
+// CANONICAL tracked fixture (helpers/parallel-workbench-integration-5025-
+// fixture.js) — the same one the tracked runtime harness uses — so the lane's
+// layout and the harness' child environment are built by one contract. The two
+// directory-digest helpers the lane needs are implemented here, in the lane's
+// own file, so the old fixture leaves the dependency closure entirely.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const fixture = require('./parallel-workbench-integration-5025-fixture');
+const { findChromeDetailed } = require('./find-chrome');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const LANE_NAME = 'wb-permission-question-r44';
+
+// Ambient module addresses that would point a lane at a live instance.
+const AMBIENT_MODULE_URLS = [
+  'KB_KNOWLEDGE_ENGINE_URL',
+  'KB_VECTORHUB_URL',
+  'KB_TERMINAL_URL',
+  'KB_EVENTBRIDGE_URL',
+  'KB_EVENT_BRIDGE_URL',
+  'KB_WORKBENCH_RUNTIME_TOKEN',
+  'KB_MODULES_AUTOSTART',
+];
+
+// Ambient model credentials. A lane may only use the credential the product
+// resolves from its own read-only profile store, in memory.
+const AMBIENT_MODEL_ENV = [
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_BASE_URL',
+  'ANTHROPIC_MODEL',
+  'ANTHROPIC_DEFAULT_THINKING_MODEL',
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL',
+  'ANTHROPIC_DEFAULT_OPUS_MODEL',
+  'API_TIMEOUT_MS',
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_FOUNDRY',
+];
+
+// The variables this lane redirects. Every one of them must point inside the
+// lane's own run root once the driver is hardened.
+const REDIRECTED_VARS = [
+  'HOME',
+  'USERPROFILE',
+  'HOMEDRIVE',
+  'HOMEPATH',
+  'APPDATA',
+  'LOCALAPPDATA',
+  'CODEX_HOME',
+  'CLAUDE_CONFIG_DIR',
+  'TEMP',
+  'TMP',
+  'TMPDIR',
+  'KB_DATA_DIR',
+  'KB_KNOWLEDGE_DATA_DIR',
+  'AGENT_TERMINAL_DATA_DIR',
+  'CLAUDE_AI_WORKBENCH_DATA_DIR',
+  'AI_CODING_EVENT_BRIDGE_HOME',
+];
+
+function isInside(candidate, parent) {
+  const relative = path.relative(path.resolve(parent), path.resolve(candidate));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+// The real profile store of the product. It is resolved while the REAL
+// environment is still in place: this module is loaded before the driver
+// hardens its own environment, and os.homedir() reads the REDIRECTED
+// USERPROFILE once the isolation is applied. The value is therefore captured
+// at load time and refreshed by the capture, never re-derived later.
+let REAL_PROFILE_DIR = path.join(os.homedir(), '.project-knowledge-v5', 'workbench');
+function realProfileDir() { return REAL_PROFILE_DIR; }
+
+// The lane's own temp root, outside the repository and outside the real
+// home. Portable: it follows the repository location, never a fixed drive.
+function resolveLaneTempRoot() {
+  const override = String(process.env.QA_R44_TEMP_ROOT || '').trim();
+  const base = override
+    ? path.resolve(override)
+    : path.join(path.dirname(REPO_ROOT), '.project-knowledge-test-temp');
+  const root = path.join(base, LANE_NAME);
+  if (isInside(root, REPO_ROOT)) throw new Error(`refusing a lane temp root inside the repository: ${root}`);
+  fs.mkdirSync(root, { recursive: true });
+  return root;
+}
+
+// The real Claude Code executable, resolved the way the product resolves it
+// but WITHOUT loading the product module (loading it would boot its own
+// session housekeeping inside the driver).
+function findClaudeExecutable() {
+  const rejected = [];
+  const push = (file, source) => {
+    if (!file) return;
+    try {
+      if (!fs.statSync(file).isFile()) { rejected.push({ path: file, reason: 'not a file' }); return; }
+    } catch { rejected.push({ path: file, reason: 'missing' }); return; }
+    return { path: path.resolve(file), source };
+  };
+  const override = String(process.env.CLAUDE_CODE_EXECPATH || '').trim();
+  if (override) {
+    const found = push(override, 'environment');
+    if (found) return found;
+  }
+  const packageDirs = [];
+  if (process.env.APPDATA) packageDirs.push(path.join(process.env.APPDATA, 'npm', 'node_modules', '@anthropic-ai', 'claude-code'));
+  for (const dir of packageDirs) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      const bin = typeof pkg.bin === 'string' ? pkg.bin : (pkg.bin && pkg.bin.claude) || null;
+      if (bin) {
+        const entry = path.join(dir, ...String(bin).split(/[\\/]+/).filter(Boolean));
+        const found = push(entry, 'npm-global-package');
+        if (found) return found;
+      }
+    } catch { /* the package is simply not there */ }
+    const found = push(path.join(dir, 'bin', 'claude.exe'), 'npm-global-package');
+    if (found) return found;
+  }
+  const userProfile = process.env.USERPROFILE || '';
+  if (userProfile) {
+    const found = push(path.join(userProfile, '.local', 'bin', 'claude.exe'), 'user-local-bin');
+    if (found) return found;
+  }
+  if (process.env.LOCALAPPDATA) {
+    for (const candidate of [
+      path.join(process.env.LOCALAPPDATA, 'Programs', 'claude-code', 'claude.exe'),
+      path.join(process.env.LOCALAPPDATA, 'claude-code', 'claude.exe'),
+    ]) {
+      const found = push(candidate, 'localappdata');
+      if (found) return found;
+    }
+  }
+  for (const dir of String(process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const found = push(path.join(dir, 'claude.exe'), 'path');
+    if (found) return found;
+  }
+  const whereExe = process.env.WINDIR ? path.join(process.env.WINDIR, 'System32', 'where.exe') : 'where.exe';
+  try {
+    const stdout = execFileSync(whereExe, ['claude'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, timeout: 5000 });
+    for (const hit of String(stdout).split(/\r?\n/).map(entry => entry.trim()).filter(Boolean)) {
+      const found = push(hit, 'where');
+      if (found) return found;
+    }
+  } catch { /* where.exe found nothing */ }
+  throw new Error(`Claude Code executable not found for the ${LANE_NAME} lane; rejected: ${JSON.stringify(rejected)}`);
+}
+
+// The real environment, captured BEFORE anything is hardened.
+function captureRealEnvironment() {
+  const realHome = os.homedir();
+  const realUserProfile = process.env.USERPROFILE || realHome;
+  const chrome = findChromeDetailed();
+  const claude = findClaudeExecutable();
+  const present = (name) => Object.keys(process.env).some(key => key.toUpperCase() === name && String(process.env[key] || '').trim() !== '');
+  REAL_PROFILE_DIR = path.join(realHome, '.project-knowledge-v5', 'workbench');
+  return {
+    realHome,
+    realUserProfile,
+    realProfileDir: REAL_PROFILE_DIR,
+    chrome: { path: chrome.path, source: chrome.source },
+    claude: { path: claude.path, source: claude.source },
+    ambientModuleUrlsPresent: AMBIENT_MODULE_URLS.filter(present),
+    ambientCredentialsPresent: AMBIENT_MODEL_ENV.filter(present),
+  };
+}
+
+// The lane's own isolation layout. It reuses the canonical fixture layout so
+// the frozen host helper can host it unchanged, and adds the directories this
+// lane has to isolate on its own.
+function createLaneLayout() {
+  const laneTempRoot = resolveLaneTempRoot();
+  // The canonical fixture resolves its temp root from this variable, so the
+  // lane root is published BEFORE the layout is created: the whole run then
+  // lives under one lane-owned directory outside the repository.
+  process.env.PK_TEST_TEMP_ROOT = laneTempRoot;
+  const layout = fixture.createIsolationLayout('qa-r44');
+  layout.laneTempRoot = laneTempRoot;
+  layout.logs = path.join(laneTempRoot, 'logs');
+  fs.mkdirSync(layout.logs, { recursive: true });
+  // Chrome refuses remote debugging when the profile root it resolves is
+  // missing, so the empty scaffold is created (the R33 lesson). The canonical
+  // fixture already creates the home-shaped one; the LOCALAPPDATA-shaped one
+  // is kept because the lane redirects LOCALAPPDATA as well.
+  for (const scaffold of [
+    path.join(layout.localAppData, 'Google', 'Chrome', 'User Data'),
+    path.join(layout.home, 'AppData', 'Local', 'Google', 'Chrome', 'User Data'),
+  ]) {
+    fs.mkdirSync(scaffold, { recursive: true });
+  }
+  return layout;
+}
+
+// Harden the DRIVER's own environment. Every child process this driver
+// spawns afterwards inherits it; nothing is bootstrapped under the real
+// environment first.
+function hardenDriverEnv(layout, captured) {
+  const parsed = path.parse(layout.home);
+  const redirected = {
+    HOME: layout.home,
+    USERPROFILE: layout.home,
+    HOMEDRIVE: parsed.root,
+    HOMEPATH: parsed.root === path.sep ? layout.home.slice(1) : layout.home.slice(parsed.root.length),
+    APPDATA: layout.appData,
+    LOCALAPPDATA: layout.localAppData,
+    CODEX_HOME: layout.codexHome,
+    CLAUDE_CONFIG_DIR: layout.claudeConfigDir,
+    TEMP: layout.temp,
+    TMP: layout.temp,
+    TMPDIR: layout.temp,
+    KB_DATA_DIR: layout.knowledgeDataDir,
+    KB_KNOWLEDGE_DATA_DIR: layout.knowledgeDataDir,
+    AGENT_TERMINAL_DATA_DIR: layout.dataDir,
+    CLAUDE_AI_WORKBENCH_DATA_DIR: layout.dataDir,
+    AI_CODING_EVENT_BRIDGE_HOME: layout.bridgeHome,
+  };
+  const droppedModuleUrls = [];
+  const droppedCredentials = [];
+  for (const name of AMBIENT_MODULE_URLS) {
+    if (process.env[name] !== undefined) { delete process.env[name]; droppedModuleUrls.push(name); }
+  }
+  for (const name of AMBIENT_MODEL_ENV) {
+    if (process.env[name] !== undefined) { delete process.env[name]; droppedCredentials.push(name); }
+  }
+  for (const [name, value] of Object.entries(redirected)) process.env[name] = value;
+  // The isolated fixture layout is the temp root of the frozen helper too.
+  process.env.PK_TEST_TEMP_ROOT = layout.laneTempRoot;
+  process.env.KB_MODULES_AUTOSTART = '0';
+  // The real tools are captured before the isolation and re-published as
+  // absolute paths, so isolating APPDATA / LOCALAPPDATA never hides them.
+  process.env.KB_CHROME_PATH = captured.chrome.path;
+  process.env.CLAUDE_CODE_EXECPATH = captured.claude.path;
+  // The canonical harness refuses to discover a browser from an isolated
+  // environment: it wants the path that was captured BEFORE the isolation.
+  // It is published under both names its callers accept.
+  process.env.PK_WB_CHROME = captured.chrome.path;
+  // The product resolves the ORIGINAL profile store from the real home; the
+  // isolated HOME would otherwise hide it. The path is a location, not a
+  // credential: the store itself is opened read-only by the product.
+  process.env.PK_WB_REAL_PROFILE_DIR = captured.realProfileDir;
+  return {
+    redirected: Object.keys(redirected),
+    redirectedValues: redirected,
+    droppedModuleUrls,
+    droppedCredentials,
+    republishedTools: { KB_CHROME_PATH: captured.chrome.path, PK_WB_CHROME: captured.chrome.path, CLAUDE_CODE_EXECPATH: captured.claude.path },
+    preservedRealProfileDir: captured.realProfileDir,
+  };
+}
+
+// Fail-closed check of the hardened environment.
+function assertIsolatedEnv(env, layout, captured) {
+  const problems = [];
+  for (const name of REDIRECTED_VARS) {
+    const value = env[name];
+    if (!value) { problems.push(`${name} is not set`); continue; }
+    // HOMEDRIVE and HOMEPATH are one Windows pair: they are checked as a
+    // whole below, not as two independent directories.
+    if (name === 'HOMEDRIVE' || name === 'HOMEPATH') continue;
+    if (!isInside(value, layout.root)) problems.push(`${name} points outside the lane run root: ${value}`);
+  }
+  if (env.HOMEDRIVE && env.HOMEPATH) {
+    const combined = path.resolve(`${env.HOMEDRIVE}${env.HOMEPATH}`);
+    if (!isInside(combined, layout.root)) problems.push(`HOMEDRIVE+HOMEPATH points outside the lane run root: ${combined}`);
+    else if (env.HOME && path.resolve(combined).toLowerCase() !== path.resolve(env.HOME).toLowerCase()) {
+      problems.push(`HOMEDRIVE+HOMEPATH and HOME disagree: ${combined} vs ${env.HOME}`);
+    }
+  } else {
+    problems.push('HOMEDRIVE and HOMEPATH are not both set');
+  }
+  if (env.USERPROFILE && captured.realUserProfile && path.resolve(env.USERPROFILE).toLowerCase() === path.resolve(captured.realUserProfile).toLowerCase()) {
+    problems.push('USERPROFILE still points at the real user profile');
+  }
+  if (env.HOME && captured.realHome && path.resolve(env.HOME).toLowerCase() === path.resolve(captured.realHome).toLowerCase()) {
+    problems.push('HOME still points at the real home');
+  }
+  for (const name of AMBIENT_MODEL_ENV) {
+    if (env[name] !== undefined && String(env[name] || '').trim() !== '') problems.push(`credential variable survived: ${name}`);
+  }
+  for (const name of AMBIENT_MODULE_URLS) {
+    if (name === 'KB_MODULES_AUTOSTART') continue;
+    if (env[name] !== undefined && String(env[name] || '').trim() !== '') problems.push(`ambient module address survived: ${name}`);
+  }
+  if (path.resolve(env.PK_TEST_TEMP_ROOT || '') === path.resolve(REPO_ROOT)) problems.push('the lane temp root is the repository root');
+  if (isInside(env.PK_TEST_TEMP_ROOT || '', REPO_ROOT)) problems.push('the lane temp root is inside the repository');
+  if (problems.length) throw new Error(`the lane environment is not isolated:\n  - ${problems.join('\n  - ')}`);
+  return true;
+}
+
+// A report-friendly summary. It carries paths and variable NAMES only; no
+// credential value is ever read, copied or printed.
+function isolationContract(layout, captured, hardened) {
+  return {
+    lane: LANE_NAME,
+    repoRoot: REPO_ROOT,
+    runRoot: layout.root,
+    laneTempRoot: layout.laneTempRoot,
+    tempRootOutsideRepository: !isInside(layout.laneTempRoot, REPO_ROOT),
+    redirectedVariables: hardened.redirected,
+    redirectedValues: hardened.redirectedValues,
+    droppedAmbientModuleUrls: hardened.droppedModuleUrls,
+    droppedAmbientCredentials: hardened.droppedCredentials,
+    ambientModuleUrlsPresentBefore: captured.ambientModuleUrlsPresent,
+    ambientCredentialsPresentBefore: captured.ambientCredentialsPresent,
+    republishedTools: hardened.republishedTools,
+    realProfileDirectory: captured.realProfileDir,
+    realProfileOpened: 'read-only by the product; the credential stays in the host process memory',
+    forbiddenPorts: Array.from(fixture.FORBIDDEN_PORTS),
+    realHomeUsed: false,
+  };
+}
+
+// Explicit containment: every path a lane tool touches must live under
+// `root`. No globbing, no traversal, no absolute path outside the root.
+function containedPath(root, rel) {
+  const target = path.resolve(root, ...String(rel).split(/[\\/]+/).filter(Boolean));
+  const relative = path.relative(path.resolve(root), target);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`path escapes its root: ${rel}`);
+  }
+  return target;
+}
+
+// The byte-level digest of every file of a directory. Only the NAMES and the
+// digests are kept; the content is never copied anywhere. The comparison is
+// done in memory and the digests of a real profile store are never printed.
+function digestDirectory(dir) {
+  if (!dir || !fs.existsSync(dir)) return null;
+  const entries = {};
+  for (const name of fs.readdirSync(dir)) {
+    try {
+      const file = path.join(dir, name);
+      if (!fs.statSync(file).isFile()) continue;
+      entries[name] = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    } catch { entries[name] = null; }
+  }
+  return entries;
+}
+
+function compareDigests(before, after) {
+  const names = new Set([...Object.keys(before || {}), ...Object.keys(after || {})]);
+  const changed = [];
+  const added = [];
+  const removed = [];
+  const unreadable = [];
+  for (const name of names) {
+    const a = before ? before[name] : undefined;
+    const b = after ? after[name] : undefined;
+    if (a === undefined && b !== undefined) added.push(name);
+    else if (a !== undefined && b === undefined) removed.push(name);
+    else if (a === null || b === null) unreadable.push(name);
+    else if (a !== b) changed.push(name);
+  }
+  return {
+    count: names.size,
+    byteIdentical: changed.length === 0 && added.length === 0 && removed.length === 0 && unreadable.length === 0,
+    changedFiles: changed,
+    addedFiles: added,
+    removedFiles: removed,
+    unreadableFiles: unreadable,
+  };
+}
+
+module.exports = {
+  LANE_NAME,
+  REPO_ROOT,
+  REDIRECTED_VARS,
+  AMBIENT_MODULE_URLS,
+  AMBIENT_MODEL_ENV,
+  isInside,
+  realProfileDir,
+  resolveLaneTempRoot,
+  captureRealEnvironment,
+  createLaneLayout,
+  hardenDriverEnv,
+  assertIsolatedEnv,
+  isolationContract,
+  containedPath,
+  digestDirectory,
+  compareDigests,
+};