@sanqianx/project-knowledge 5.0.24 → 5.0.26

package/_site/_test/helpers/parallel-workbench-source-map.js

@@ -0,0 +1,196 @@
+'use strict';
+// Lane-owned helpers for the Workbench provenance batch (WB001).
+//
+// They answer one question with bytes, never with version strings:
+//   module-runtime-manifest.json  <->  the currently installed package
+//   module-runtime-manifest.json  <->  the Workbench source checkout
+//
+// A file is compared three ways, in this order:
+//   identical   the raw sha256 equals the manifest hash
+//   eolOnly     the sha256 differs but the CRLF-normalised content matches
+//               (npm tarballs ship LF, a Windows checkout carries CRLF)
+//   different   the content really differs
+//
+// Every path is resolved from the repository location or from an explicit
+// environment override, so nothing here depends on a developer directory.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const MANIFEST_FILE = path.join(REPO_ROOT, 'module-runtime-manifest.json');
+
+function sha256Buffer(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+// The same content with the line endings normalised to LF.
+function normalizedSha256(value) {
+  return sha256Buffer(Buffer.from(value.toString('utf8').replace(/\r\n/g, '\n'), 'utf8'));
+}
+
+function sha256File(filePath) {
+  return fs.existsSync(filePath) ? sha256Buffer(fs.readFileSync(filePath)) : null;
+}
+
+function loadManifest() {
+  if (!fs.existsSync(MANIFEST_FILE)) throw new Error(`module manifest is missing: ${MANIFEST_FILE}`);
+  const manifest = JSON.parse(fs.readFileSync(MANIFEST_FILE, 'utf8'));
+  const terminal = manifest.modules && manifest.modules.terminal;
+  if (!terminal || !terminal.files || typeof terminal.files !== 'object') {
+    throw new Error('module manifest has no modules.terminal.files');
+  }
+  return {
+    file: MANIFEST_FILE,
+    schema: manifest.schema,
+    terminal,
+    files: terminal.files,
+    count: Object.keys(terminal.files).length,
+  };
+}
+
+function packageIdentity(root) {
+  const packageFile = path.join(root, 'package.json');
+  if (!fs.existsSync(packageFile)) return null;
+  const pkg = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+  return { root, packageFile, name: pkg.name, version: pkg.version };
+}
+
+// Classify every manifest file against a candidate tree.
+function compareTree(manifestFiles, root) {
+  const identical = [];
+  const eolOnly = [];
+  const different = [];
+  const missing = [];
+  for (const [relative, expected] of Object.entries(manifestFiles)) {
+    const target = path.join(root, relative);
+    if (!fs.existsSync(target)) { missing.push(relative); continue; }
+    const content = fs.readFileSync(target);
+    if (sha256Buffer(content) === expected) { identical.push(relative); continue; }
+    if (normalizedSha256(content) === expected) { eolOnly.push(relative); continue; }
+    different.push(relative);
+  }
+  return {
+    root,
+    total: Object.keys(manifestFiles).length,
+    identical,
+    eolOnly,
+    different,
+    missing,
+    identicalCount: identical.length,
+    eolOnlyCount: eolOnly.length,
+    differentCount: different.length,
+    missingCount: missing.length,
+  };
+}
+
+// The package the repository pins: node_modules/claude-ai-workbench.
+function resolveRepoTargetPackage() {
+  return path.join(REPO_ROOT, 'node_modules', 'claude-ai-workbench');
+}
+
+// The package the installed product (5.0.24) actually ships.
+function resolveInstalledProductPackage() {
+  const override = String(process.env.PK_WB_INSTALLED_PRODUCT_MODULE || '').trim();
+  if (override) return fs.existsSync(override) ? override : null;
+  const appData = String(process.env.APPDATA || '').trim();
+  if (!appData) return null;
+  const candidate = path.join(appData, 'npm', 'node_modules', '@sanqianx', 'project-knowledge', 'node_modules', 'claude-ai-workbench');
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+function resolveInstalledProductRoot() {
+  const override = String(process.env.PK_WB_INSTALLED_PRODUCT_ROOT || '').trim();
+  if (override) return fs.existsSync(override) ? override : null;
+  const appData = String(process.env.APPDATA || '').trim();
+  if (!appData) return null;
+  const candidate = path.join(appData, 'npm', 'node_modules', '@sanqianx', 'project-knowledge');
+  return fs.existsSync(path.join(candidate, 'package.json')) ? candidate : null;
+}
+
+// The Workbench source checkout: an explicit override, or a sibling of this
+// repository.
+function resolveSourceCheckout() {
+  const override = String(process.env.PK_WB_SOURCE_DIR || '').trim();
+  const candidates = override ? [override] : [path.join(path.dirname(REPO_ROOT), 'claude-ai-workbench')];
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, 'packages', 'server', 'package.json'))) return path.resolve(candidate);
+  }
+  return null;
+}
+
+// The commit the checkout currently stands on. This reads the working state
+// of the checkout, never a historical object.
+function sourceCommitId(root) {
+  if (!root) return null;
+  try {
+    const out = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, windowsHide: true, encoding: 'utf8' });
+    return out.trim();
+  } catch {
+    return null;
+  }
+}
+
+function sourceWorkingTreeClean(root) {
+  if (!root) return null;
+  try {
+    const out = execFileSync('git', ['status', '--porcelain'], { cwd: root, windowsHide: true, encoding: 'utf8' });
+    return out.trim().length === 0;
+  } catch {
+    return null;
+  }
+}
+
+// Provenance trace against a historical commit of the source checkout.
+// This reads Git objects and is therefore NOT part of the canonical test:
+// it is evidence for the report, and it fails loudly when the commit or the
+// Git history is unavailable.
+function traceAgainstCommit(sourceRoot, commit, manifestFiles, packageRoot) {
+  if (!sourceRoot) throw new Error('source checkout is required to trace a commit');
+  const identical = [];
+  const different = [];
+  const absent = [];
+  for (const relative of Object.keys(manifestFiles)) {
+    let committed;
+    try {
+      committed = execFileSync('git', ['show', `${commit}:${relative}`], { cwd: sourceRoot, windowsHide: true, maxBuffer: 1 << 26 });
+    } catch {
+      absent.push(relative);
+      continue;
+    }
+    const shipped = fs.readFileSync(path.join(packageRoot, relative));
+    if (normalizedSha256(committed) === normalizedSha256(shipped)) identical.push(relative);
+    else different.push(relative);
+  }
+  return { commit, identical, different, absent, identicalCount: identical.length, differentCount: different.length, absentCount: absent.length };
+}
+
+// Which commits of the source checkout touch a given file, newest first.
+function commitsTouchingFile(sourceRoot, relative, limit = 8) {
+  try {
+    const out = execFileSync('git', ['log', `--format=%h %s`, `-${limit}`, '--', relative], { cwd: sourceRoot, windowsHide: true, encoding: 'utf8' });
+    return out.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+module.exports = {
+  REPO_ROOT,
+  MANIFEST_FILE,
+  sha256Buffer,
+  normalizedSha256,
+  sha256File,
+  loadManifest,
+  packageIdentity,
+  compareTree,
+  resolveRepoTargetPackage,
+  resolveInstalledProductPackage,
+  resolveInstalledProductRoot,
+  resolveSourceCheckout,
+  sourceCommitId,
+  sourceWorkingTreeClean,
+  traceAgainstCommit,
+  commitsTouchingFile,
+};

package/_site/_test/helpers/spawn-server.js

@@ -0,0 +1,106 @@
+// _site/_test/helpers/spawn-server.js
+//
+// Test helper: spawn _site/server.js with an isolated KB_DATA_DIR so each
+// regression test runs against a fresh, empty user-data location. Without
+// this, server.js would default to ~/.project-knowledge/ and tests would
+// pollute (or read from) the real user data.
+//
+// Usage:
+//   const { server, dataDir, cleanup } = require('./helpers/spawn-server');
+//   const { server, dataDir, cleanup } = spawnServer({
+//     root: ROOT,
+//     port: 7891,
+//     extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1' },
+//     tag: 'hook-trigger',
+//   });
+//   ...
+//   cleanup();   // kills server + removes temp dataDir
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+const runtimeControl = require('../../lib/runtime-control');
+const runtimeEndpoint = require('../../lib/runtime-endpoint');
+
+function defaultDataDir(tag) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `kb-data-${tag || 'test'}-${process.pid}-`));
+}
+
+function spawnServer({ root, port, host = '127.0.0.1', dataDir, extraEnv = {}, tag, analysisOwner = 'legacy', stdio = ['ignore', 'pipe', 'pipe'], cwd }) {
+  const dir = dataDir || defaultDataDir(tag);
+  // Isolate the Bridge journal home too: the runtime registers a
+  // 'project-knowledge' consumer at startup, and without this the test
+  // server would write into the developer's real ~/.ai-coding-event-bridge.
+  const bridgeHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-bridge-${tag || 'test'}-${process.pid}-`));
+  // The knowledge root is a second product-owned location. A test must never
+  // inherit the developer's real knowledge directory through the environment,
+  // so give every isolated instance its own one.
+  const knowledgeDir = fs.mkdtempSync(path.join(os.tmpdir(), `kb-knowledge-${tag || 'test'}-${process.pid}-`));
+  // Legacy behavior tests characterize the retired writer in isolation. The
+  // production entry point still defaults to engine ownership; product tests
+  // explicitly request it and run the real module services.
+  const entry = path.join(root, '_site', 'lib', 'server-app.js');
+  // CI 40075242420 (normalhook, linux24): a startup rejection used to vanish —
+  // exit 1 with empty stdout/stderr — because this catch swallowed the reason.
+  // The failure path below prints the child's stderr tail, so emit one bounded
+  // JSON line of own metadata (code / message head / first stack frame's file
+  // only; never logs, keys or transcripts) and keep exit 1.
+  const bootstrap = `const {startServer,installProcessHandlers}=require(${JSON.stringify(entry)});const instance=startServer({analysisOwner:${JSON.stringify(analysisOwner)}});installProcessHandlers(instance);instance.then(s=>process.stdout.write('Project Knowledge listening on http://'+s.host+':'+s.port+'\\n')).catch(e=>{const frame=String(e&&e.stack||'').split('\\n')[1]||'';const fm=/([^\\\\/]+\\.[a-z]+):/i.exec(frame);process.stderr.write(JSON.stringify({event:'server.startup-fatal',code:e&&e.code||null,message:String(e&&e.message||e).slice(0,300),stackFile:fm?fm[1]:null})+'\\n');process.exitCode=1});`;
+  const child = spawn(process.execPath, ['-e', bootstrap], {
+    cwd: cwd || root,
+    env: {
+      ...process.env,
+      KB_SITE_PORT: String(port),
+      KB_SITE_HOST: host,
+      KB_DATA_DIR: dir,
+      KB_KNOWLEDGE_DATA_DIR: knowledgeDir,
+      KB_CLAUDE_RULES_DIR: dir,
+      KB_SKIP_MIGRATION: '1',
+      // 测试隔离：禁止测试服务器向真实模块（terminal/vector-hub）登记项目
+      KB_MODULES_REGISTER: '0',
+      KB_MODULES_AUTOSTART: '0',
+      // Disabling registration does not disable status/profile reads. Never
+      // let an isolated legacy test consult the developer's live modules.
+      // A test needing real modules supplies its own URLs in extraEnv below.
+      KB_TERMINAL_URL: 'http://127.0.0.1:0',
+      KB_VECTORHUB_URL: 'http://127.0.0.1:0',
+      KB_EVENTBRIDGE_URL: 'http://127.0.0.1:0',
+      KB_KNOWLEDGE_ENGINE_URL: 'http://127.0.0.1:0',
+      AI_CODING_EVENT_BRIDGE_HOME: bridgeHome,
+      ...extraEnv,
+    },
+    stdio,
+    windowsHide: true,
+  });
+  return {
+    child,
+    dataDir: dir,
+    bridgeHome,
+    knowledgeDir,
+    cleanup: async () => {
+      // On Windows SIGTERM is a force kill. Drain owned background work via
+      // the verified control channel first, so Git/Agent children release cwd.
+      const live = runtimeEndpoint.readEndpoint(dir);
+      if (live?.pid === child.pid && child.exitCode === null) {
+        try { await runtimeControl.request(dir, { action: 'stop', pid: live.pid, port: live.port, startedAt: live.startedAt }, 10000); } catch {}
+        await new Promise(resolve => {
+          const timer = setTimeout(resolve, 1500);
+          child.once('close', () => { clearTimeout(timer); resolve(); });
+          if (child.exitCode !== null) { clearTimeout(timer); resolve(); }
+        });
+      }
+      if (child.exitCode === null) try { child.kill(); } catch {}
+      await new Promise(resolve => {
+        const timer = setTimeout(resolve, 5000);
+        child.once('close', () => { clearTimeout(timer); resolve(); });
+        if (child.exitCode !== null) { clearTimeout(timer); resolve(); }
+      });
+      await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+      await fs.promises.rm(bridgeHome, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+      await fs.promises.rm(knowledgeDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    },
+  };
+}
+
+module.exports = { spawnServer, defaultDataDir };

package/_site/_test/helpers/version-visibility-fixture.js

@@ -0,0 +1,251 @@
+'use strict';
+// FEATURE-VERSIONS-01-R2 fixture — the version-visibility lane's own isolation
+// contract, borrowed from the accepted drafts-r5 fixture (read-only reuse of
+// its patterns; that file stays untouched):
+//   * every directory lives under a repo-external temp root (PK_TEST_TEMP_ROOT
+//     → repo-parent shared root when it exists → TEMP/TMP/TMPDIR → os.tmpdir),
+//     never inside the repository, never on a hardcoded drive/user dir;
+//   * the full env whitelist (HOME/USERPROFILE/HOMEDRIVE/HOMEPATH/CODEX_HOME/
+//     CLAUDE_CONFIG_DIR/APPDATA/LOCALAPPDATA/TEMP/TMP/TMPDIR/双 KB_DATA_DIR/
+//     Bridge home/Workbench data) is absolute-pathed into one per-run layout
+//     root; ambient module addresses and Anthropic credentials are stripped;
+//   * the live product ports 5757/5760/5789/5790/8787/8790 are refused;
+//   * Chrome is resolved from the REAL machine before any isolation is applied
+//     (find-chrome reads the real environment), then run with an isolated
+//     --user-data-dir plus the Chrome>=136 empty-default-dir scaffold under the
+//     isolated home so remote debugging is accepted.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const net = require('node:net');
+const { findChromeDetailed } = require('./find-chrome');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const FORBIDDEN_PORTS = new Set([5757, 5760, 5789, 5790, 8787, 8790]);
+
+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',
+];
+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_OP_MODEL', 'API_TIMEOUT_MS', 'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY',
+];
+
+const ISOLATION_PATH_KEYS = [
+  'HOME', 'USERPROFILE', 'CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'APPDATA', 'LOCALAPPDATA',
+  'TEMP', 'TMP', 'TMPDIR', 'KB_DATA_DIR', 'KB_KNOWLEDGE_DATA_DIR',
+  'AI_CODING_EVENT_BRIDGE_HOME', 'AGENT_TERMINAL_DATA_DIR', 'CLAUDE_AI_WORKBENCH_DATA_DIR',
+];
+
+// Captured at module load, BEFORE any isolation could hide the real machine:
+// the browser binary this lane's UI acceptance will drive.
+const CHROME_PATH = findChromeDetailed().path;
+
+function isInside(candidate, parent) {
+  const relative = path.relative(parent, candidate);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function resolveTempRoot() {
+  const sharedRoot = path.join(path.dirname(REPO_ROOT), '.project-knowledge-test-temp');
+  const candidates = [process.env.PK_TEST_TEMP_ROOT, fs.existsSync(sharedRoot) ? sharedRoot : null, process.env.TEMP, process.env.TMP, process.env.TMPDIR];
+  const chosen = candidates.find(value => value && String(value).trim());
+  const root = path.resolve(chosen ? String(chosen).trim() : os.tmpdir());
+  if (isInside(root, REPO_ROOT)) throw new Error(`refusing to use a temp root inside the repository: ${root}`);
+  return root;
+}
+
+function makeTempDir(prefix = 'version-visibility') {
+  const root = resolveTempRoot();
+  fs.mkdirSync(root, { recursive: true });
+  const dir = fs.mkdtempSync(path.join(root, `${prefix}-`));
+  if (isInside(dir, REPO_ROOT)) throw new Error(`refusing to create a fixture inside the repository: ${dir}`);
+  return dir;
+}
+
+function removeTree(dir) {
+  if (!dir) return;
+  fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+}
+
+async function freePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      server.close(() => {
+        if (FORBIDDEN_PORTS.has(Number(port))) { reject(new Error(`refusing to use the live port ${port}`)); return; }
+        resolve(Number(port));
+      });
+    });
+  });
+}
+
+function assertAllowedEndpoint(url, what = 'endpoint') {
+  const parsed = new URL(String(url));
+  const port = parsed.port ? Number(parsed.port) : (parsed.protocol === 'https:' ? 443 : 80);
+  if (FORBIDDEN_PORTS.has(port)) throw new Error(`refusing to contact the live ${what} ${url}`);
+  return url;
+}
+
+async function waitForHttp(url, timeoutMs = 45000) {
+  assertAllowedEndpoint(url, 'service');
+  const until = Date.now() + timeoutMs;
+  let lastError = null;
+  while (Date.now() < until) {
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(2000) });
+      if (response.ok) return true;
+      lastError = new Error(`HTTP ${response.status}`);
+    } catch (error) { lastError = error; }
+    await new Promise(resolve => setTimeout(resolve, 120));
+  }
+  throw new Error(`Timed out waiting for ${url}: ${lastError && lastError.message}`);
+}
+
+function sanitizedEnv(extra = {}, source = process.env) {
+  const env = {};
+  const systemKey = /^(?:PATH|PATHEXT|SYSTEMROOT|WINDIR|SYSTEMDRIVE|COMSPEC|OS|PROCESSOR_ARCHITECTURE|PROCESSOR_IDENTIFIER|PROCESSOR_LEVEL|PROCESSOR_REVISION|NUMBER_OF_PROCESSORS|PROGRAMFILES(?:\(X86\))?|PROGRAMW6432|PROGRAMDATA|LANG|LC_ALL|LC_CTYPE|TERM)$/i;
+  for (const [key, value] of Object.entries(source)) {
+    if (systemKey.test(key)) env[key] = value;
+  }
+  // Only the inherited environment is filtered. Explicit lane URLs and the
+  // disabled autostart flag must survive, or the server uses live defaults.
+  return { ...env, ...extra };
+}
+
+function spawnNode(args, env = {}) {
+  const { spawn } = require('node:child_process');
+  const child = spawn(process.execPath, args, { env: sanitizedEnv(env), windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  const output = { stdout: '', stderr: '' };
+  child.stdout.on('data', chunk => { output.stdout += chunk; });
+  child.stderr.on('data', chunk => { output.stderr += chunk; });
+  const exited = new Promise(resolve => child.once('close', code => resolve({ code, ...output })));
+  return { child, exited, output };
+}
+
+function createIsolationLayout(prefix = 'version-visibility') {
+  const root = makeTempDir(prefix);
+  const layout = {
+    root,
+    dataDir: path.join(root, 'kb-data'),
+    knowledgeDataDir: path.join(root, 'knowledge-data'),
+    bridgeHome: path.join(root, 'bridge-home'),
+    workbenchDataDir: path.join(root, 'workbench-data'),
+    home: path.join(root, 'home'),
+    claudeConfigDir: path.join(root, 'claude-config'),
+    codexHome: path.join(root, 'codex-home'),
+    appData: path.join(root, 'appdata'),
+    localAppData: path.join(root, 'localappdata'),
+    temp: path.join(root, 'temp'),
+  };
+  for (const dir of Object.values(layout)) fs.mkdirSync(dir, { recursive: true });
+  // Chrome >= 136 gate: an empty default-shaped "User Data" scaffold under the
+  // ISOLATED home lets the default-dir resolution succeed, so the separate
+  // --user-data-dir browser profile below this layout is accepted. Nothing of
+  // the real machine is touched.
+  fs.mkdirSync(path.join(layout.home, 'AppData', 'Local', 'Google', 'Chrome', 'User Data'), { recursive: true });
+  fs.mkdirSync(path.join(layout.home, 'AppData', 'Roaming'), { recursive: true });
+  return layout;
+}
+
+function isolationEnvMap(layout, extraPaths = {}) {
+  const parsed = path.parse(layout.home);
+  return {
+    HOME: layout.home,
+    USERPROFILE: layout.home,
+    HOMEDRIVE: parsed.root,
+    HOMEPATH: parsed.root === path.sep ? layout.home.slice(1) : layout.home.slice(parsed.root.length),
+    CODEX_HOME: layout.codexHome,
+    CLAUDE_CONFIG_DIR: layout.claudeConfigDir,
+    APPDATA: layout.appData,
+    LOCALAPPDATA: layout.localAppData,
+    TEMP: layout.temp,
+    TMP: layout.temp,
+    TMPDIR: layout.temp,
+    PSModuleAnalysisCachePath: path.join(layout.temp, 'powershell-module-cache'),
+    KB_DATA_DIR: layout.dataDir,
+    KB_KNOWLEDGE_DATA_DIR: layout.knowledgeDataDir,
+    AI_CODING_EVENT_BRIDGE_HOME: layout.bridgeHome,
+    AGENT_TERMINAL_DATA_DIR: layout.workbenchDataDir,
+    CLAUDE_AI_WORKBENCH_DATA_DIR: layout.workbenchDataDir,
+    KB_MODULES_AUTOSTART: '0',
+    ...extraPaths,
+  };
+}
+
+function hostEnv(layout, extra = {}) {
+  return sanitizedEnv(isolationEnvMap(layout, extra));
+}
+
+function applyIsolationEnv(layout) {
+  const env = hostEnv(layout);
+  for (const key of Object.keys(process.env)) delete process.env[key];
+  Object.assign(process.env, env);
+}
+
+// The product server under test: real _site/server.js, fully isolated, with
+// every module address explicitly held on this run's own free ports (so the
+// process can never reach for the live defaults 5760/8787/8790/5790).
+async function startRootServer(layout, options = {}) {
+  const port = options.port || await freePort();
+  const [terminalPort, vectorHubPort, eventBridgePort, enginePort] = await Promise.all([freePort(), freePort(), freePort(), freePort()]);
+  const env = hostEnv(layout, {
+    KB_SITE_PORT: String(port),
+    KB_SITE_HOST: '127.0.0.1',
+    KB_TERMINAL_URL: `http://127.0.0.1:${terminalPort}`,
+    KB_VECTORHUB_URL: `http://127.0.0.1:${vectorHubPort}`,
+    KB_EVENTBRIDGE_URL: `http://127.0.0.1:${eventBridgePort}`,
+    KB_KNOWLEDGE_ENGINE_URL: `http://127.0.0.1:${enginePort}`,
+  });
+  const runner = spawnNode([path.join(REPO_ROOT, '_site', 'server.js')], env);
+  const base = `http://127.0.0.1:${port}`;
+  await waitForHttp(`${base}/api/system/version`);
+  return { layout, port, base, runner, modulePorts: { terminalPort, vectorHubPort, eventBridgePort, enginePort } };
+}
+
+async function stopRootServer(server) {
+  if (!server || !server.runner) return;
+  server.runner.child.kill();
+  await server.runner.exited;
+}
+
+// The honest-unknown branch: serve the REAL ui/ assets from disk, but fail the
+// version GET — the tooltip must then say 版本未知 instead of inventing one.
+async function startVersionBrokenUiServer(layout, options = {}) {
+  const port = options.port || await freePort();
+  const uiRoot = path.join(REPO_ROOT, 'ui');
+  const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml' };
+  const http = require('node:http');
+  const server = http.createServer((req, res) => {
+    const pathname = new URL(req.url, 'http://127.0.0.1').pathname;
+    if (pathname === '/api/system/version') {
+      res.writeHead(503, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false }));
+      return;
+    }
+    const rel = pathname === '/' ? 'index.html' : pathname.replace(/^\//, '');
+    const file = path.join(uiRoot, rel);
+    if (!isInside(path.resolve(file), uiRoot) || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end('Not found');
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': types[path.extname(file)] || 'application/octet-stream' });
+    res.end(fs.readFileSync(file));
+  });
+  await new Promise(resolve => server.listen(port, '127.0.0.1', resolve));
+  return { layout, port, base: `http://127.0.0.1:${port}`, server };
+}
+
+module.exports = {
+  REPO_ROOT, FORBIDDEN_PORTS, AMBIENT_MODULE_URLS, AMBIENT_MODEL_ENV, ISOLATION_PATH_KEYS,
+  CHROME_PATH, resolveTempRoot, makeTempDir, removeTree, freePort, assertAllowedEndpoint,
+  waitForHttp, sanitizedEnv, spawnNode, createIsolationLayout, isolationEnvMap, hostEnv, applyIsolationEnv,
+  startRootServer, stopRootServer, startVersionBrokenUiServer,
+};