@sanqianx/project-knowledge 4.6.1

package/_site/_test/refactor-characterization-test.js

@@ -0,0 +1,36 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const read = relative => fs.readFileSync(path.join(ROOT, relative), 'utf8');
+const serverEntry = read('_site/server.js');
+const server = read('_site/lib/server-app.js');
+const automation = read('_site/lib/post-commit-automation.js');
+const reconciler = read('_site/lib/commit-reconciler.js');
+const contracts = read('_site/lib/contracts.js');
+const logger = read('_site/lib/structured-logger.js');
+const ui = read('ui/index.html');
+
+assert(serverEntry.includes("require('./lib/server-app')"), 'server entry should remain thin');
+for (const removed of ['/automation/simulate', '/automation/init', '/hook-install', '/hook-uninstall', '/api/raw', "'Access-Control-Allow-Origin': '*'"]) {
+  assert(!server.includes(removed), `legacy server capability must be absent: ${removed}`);
+}
+for (const removed of ['dispatchProjectInit', 'renderProjectInitPrompt', 'DEFAULT_INIT_PROMPT_TEMPLATE', 'dispatchAutomation']) {
+  assert(!automation.includes(removed), `legacy automation symbol must be absent: ${removed}`);
+}
+assert.strictEqual((automation.match(/handlePostCommitEvent/g) || []).length >= 1, true);
+assert(reconciler.includes('validateTrigger(trigger)'));
+assert(contracts.includes("Object.freeze(['git-hook'])"), 'git-hook must be the only analysis trigger');
+assert(!server.includes("reconcileProjectCommits(projectId, 'startup'"), 'startup must not submit commit analysis');
+assert(!automation.includes('dispatchPendingAutomations'), 'pending startup dispatcher must be deleted');
+assert(reconciler.includes('processCommitEvent'), 'Hook events must have an explicit commit processor');
+assert(!reconciler.includes('this.scanner.scan('), 'knowledge analysis must not scan baseline..HEAD');
+assert(logger.includes('LOG_LEVELS,') && logger.includes('new Set(LOG_LEVELS)'), 'the v2 logger must use the shared six-level contract');
+assert(logger.includes('class LogRepository'));
+assert(!ui.includes('tailwindcss.com'));
+assert(!ui.includes('vue.global'));
+assert.strictEqual((ui.match(/class="shell"/g) || []).length, 1, 'production must contain one full product shell');
+assert.strictEqual((ui.match(/id="settings-logs"/g) || []).length, 1, 'production must contain one Settings logs view');
+
+console.log('refactor-characterization-test PASS');

package/_site/_test/release-version-sync-test.js

@@ -0,0 +1,98 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const SCRIPT = path.join(ROOT, '_site', 'scripts', 'sync-release-version.js');
+const TEMP = fs.mkdtempSync(path.join(os.tmpdir(), `project-knowledge-release-version-${process.pid}-`));
+const FILES = [
+  'package.json',
+  'package-lock.json',
+  'desktop/package.json',
+  'desktop/package-lock.json',
+  'plugins/project-knowledge/.claude-plugin/plugin.json',
+  'plugins/project-knowledge/.codex-plugin/plugin.json',
+  '.claude-plugin/marketplace.json',
+  'plugins/project-knowledge/.mcp.json',
+];
+
+function copyFixture() {
+  for (const relative of FILES) {
+    const destination = path.join(TEMP, relative);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.copyFileSync(path.join(ROOT, relative), destination);
+  }
+}
+
+function run(args) {
+  return spawnSync(process.execPath, [SCRIPT, '--root', TEMP, ...args], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+}
+
+function git(args) {
+  const result = spawnSync('git', args, { cwd: TEMP, encoding: 'utf8', windowsHide: true });
+  assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+  return result;
+}
+
+try {
+  copyFixture();
+  git(['init', '-q']);
+  git(['config', 'user.email', 'release-test@example.local']);
+  git(['config', 'user.name', 'Release Test']);
+  git(['add', '.']);
+  git(['commit', '-q', '-m', 'fixture']);
+  const rootPackage = path.join(TEMP, 'package.json');
+  const value = JSON.parse(fs.readFileSync(rootPackage, 'utf8'));
+  value.version = '9.8.7';
+  fs.writeFileSync(rootPackage, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+
+  const before = run(['--check']);
+  assert.notStrictEqual(before.status, 0, 'check must fail before derived version files are synchronized');
+  assert.match(before.stderr, /out of sync/);
+
+  const sync = run(['--stage']);
+  assert.strictEqual(sync.status, 0, sync.stderr || sync.stdout);
+  const check = run(['--check']);
+  assert.strictEqual(check.status, 0, check.stderr || check.stdout);
+  const matchingTag = run(['--check', '--tag', 'v9.8.7']);
+  assert.strictEqual(matchingTag.status, 0, matchingTag.stderr || matchingTag.stdout);
+  const mismatchedTag = run(['--check', '--tag', 'v9.8.8']);
+  assert.notStrictEqual(mismatchedTag.status, 0, 'check must reject a tag that does not match package.json');
+  assert.match(mismatchedTag.stderr, /must match package version/);
+
+  const claude = JSON.parse(fs.readFileSync(path.join(TEMP, 'plugins/project-knowledge/.claude-plugin/plugin.json'), 'utf8'));
+  const codex = JSON.parse(fs.readFileSync(path.join(TEMP, 'plugins/project-knowledge/.codex-plugin/plugin.json'), 'utf8'));
+  const marketplace = JSON.parse(fs.readFileSync(path.join(TEMP, '.claude-plugin/marketplace.json'), 'utf8'));
+  const mcp = JSON.parse(fs.readFileSync(path.join(TEMP, 'plugins/project-knowledge/.mcp.json'), 'utf8'));
+  const desktopLock = JSON.parse(fs.readFileSync(path.join(TEMP, 'desktop/package-lock.json'), 'utf8'));
+  assert.strictEqual(claude.version, '9.8.7');
+  assert.strictEqual(codex.version, '9.8.7');
+  assert.strictEqual(marketplace.plugins[0].version, '9.8.7');
+  assert(mcp.mcpServers['project-knowledge'].args.includes('project-knowledge@9.8.7'));
+  assert.strictEqual(desktopLock.version, '9.8.7');
+  assert.strictEqual(desktopLock.packages[''].version, '9.8.7');
+  const staged = git(['diff', '--cached', '--name-only']);
+  const stagedFiles = staged.stdout.split(/\r?\n/).filter(Boolean).sort();
+  assert.deepStrictEqual(stagedFiles, [
+    '.claude-plugin/marketplace.json',
+    'desktop/package-lock.json',
+    'desktop/package.json',
+    'package-lock.json',
+    'plugins/project-knowledge/.claude-plugin/plugin.json',
+    'plugins/project-knowledge/.codex-plugin/plugin.json',
+    'plugins/project-knowledge/.mcp.json',
+  ]);
+  const scripts = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).scripts;
+  assert.strictEqual(scripts.preversion, 'npm run release:verify');
+  assert.strictEqual(scripts.version, 'node _site/scripts/sync-release-version.js --stage');
+  assert.strictEqual(scripts.postversion, 'npm run release:verify');
+  console.log('release-version-sync-test PASS');
+} finally {
+  fs.rmSync(TEMP, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+}

package/_site/_test/requirement-binding-test.js

@@ -0,0 +1,113 @@
+// Run: node _site/_test/requirement-binding-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { SCHEMAS } = require('../lib/contracts');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { RequirementBinder } = require('../lib/requirement-binder');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-requirement-binding-${process.pid}-`));
+const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+const registry = new ProjectRegistryStore({ layout });
+const projects = new ProjectStore({ layout });
+const commit = 'c'.repeat(40);
+
+function record(id, projectId, sessionId, head, options = {}) {
+  return {
+    schema: SCHEMAS.requirement,
+    id,
+    ts: options.ts || '2026-08-17T00:00:00.000Z',
+    projectId,
+    client: options.client || 'codex',
+    sessionId,
+    conversationId: null,
+    branch: options.branch || 'main',
+    headAtRecord: head,
+    requirement: `Requirement ${id}`,
+    requirementHash: `sha256:${id}`,
+    explicitCommit: options.explicitCommit || null,
+  };
+}
+
+(async () => {
+  await registry.initialize();
+  for (const projectId of ['project-a', 'project-b']) {
+    const repoPath = path.join(temp, projectId);
+    fs.mkdirSync(repoPath, { recursive: true });
+    await projects.create(projectId, {
+      storageName: projectId,
+      displayName: projectId,
+      repoPath,
+      knowledgePath: path.join(temp, 'knowledge', projectId),
+    });
+    await registry.add(projectId, { displayName: projectId });
+  }
+  await projects.appendRequirement('project-a', record('req-a1', 'project-a', 'session-one', 'a'.repeat(40), { ts: '2026-08-17T00:00:01.000Z' }));
+  await projects.appendRequirement('project-a', record('req-a2', 'project-a', 'session-one', 'b'.repeat(40), { ts: '2026-08-17T00:00:02.000Z' }));
+  await projects.appendRequirement('project-a', record('req-a3', 'project-a', 'session-two', 'd'.repeat(40)));
+  await projects.appendRequirement('project-a', record('req-branch', 'project-a', 'session-one', 'e'.repeat(40), { branch: 'feature' }));
+  await projects.appendRequirement('project-a', record('req-future', 'project-a', 'session-one', 'f'.repeat(40)));
+  await projects.appendRequirement('project-a', record('req-explicit-commit', 'project-a', 'session-three', '9'.repeat(40), { explicitCommit: '8'.repeat(40) }));
+  await projects.appendRequirement('project-b', record('req-other-project', 'project-b', 'session-one', 'a'.repeat(40)));
+
+  const ancestry = new Set(['a'.repeat(40), 'b'.repeat(40), 'd'.repeat(40), 'e'.repeat(40)]);
+  const binder = new RequirementBinder({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    gitReader: { isAncestor: async (_repoPath, headAtRecord, target) => target === commit && ancestry.has(headAtRecord) },
+  });
+
+  const sameSession = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'main', client: 'codex', sessionId: 'session-one' });
+  assert.deepStrictEqual(sameSession.requirementIds, ['req-a1', 'req-a2'], 'same session and ancestry should bind its ordered unclaimed sequence');
+  assert.strictEqual(sameSession.requirementBinding, 'session-ancestry');
+
+  const ambiguous = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'main' });
+  assert.strictEqual(ambiguous.requirementBinding, 'unavailable');
+  assert.strictEqual(ambiguous.reason, 'ambiguous-sessions', 'multiple candidate sessions must never use most-recent guessing');
+
+  const wrongSession = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'main', client: 'codex', sessionId: 'unknown' });
+  assert.strictEqual(wrongSession.reason, 'no-reliable-requirement');
+  const changedBranch = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'release', client: 'codex', sessionId: 'session-one' });
+  assert.strictEqual(changedBranch.requirementBinding, 'unavailable', 'branch changes should lower confidence to unavailable');
+
+  const explicit = await binder.bind({ projectId: 'project-a', commitSha: commit, requirementId: 'req-a1' });
+  assert.deepStrictEqual(explicit.requirementIds, ['req-a1']);
+  assert.strictEqual(explicit.requirementBinding, 'explicit');
+  await assert.rejects(
+    binder.bind({ projectId: 'project-a', commitSha: commit, requirementId: 'req-other-project' }),
+    error => error.code === 'INVALID_ARGUMENT' && /different project/.test(error.message),
+  );
+
+  const unclaimed = await binder.bind({
+    projectId: 'project-a', commitSha: commit, branch: 'main', client: 'codex', sessionId: 'session-one', claimedRequirementIds: ['req-a1'],
+  });
+  assert.deepStrictEqual(unclaimed.requirementIds, ['req-a2'], 'already advanced requirements should be excluded from a later claim');
+
+  const explicitCommit = await binder.bind({ projectId: 'project-a', commitSha: '8'.repeat(40), branch: 'main' });
+  assert.deepStrictEqual(explicitCommit.requirementIds, ['req-explicit-commit']);
+  assert.strictEqual(explicitCommit.reason, 'explicit-commit');
+
+  const claim = {
+    schema: SCHEMAS.commitClaim,
+    projectId: 'project-a',
+    commitSha: commit,
+    requirementIds: ['req-a1'],
+    requirementBinding: 'session-ancestry',
+  };
+  await projects.appendRequirement('project-a', record('req-recorded-after-claim', 'project-a', 'session-one', 'a'.repeat(40), { ts: '2026-08-17T00:00:03.000Z' }));
+  const retry = await binder.bind({ projectId: 'project-a', commitSha: commit, claim });
+  assert.deepStrictEqual(retry.requirementIds, ['req-a1'], 'retry must reuse frozen IDs and ignore future records');
+  assert.strictEqual(retry.frozen, true);
+
+  console.log('requirement-binding-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});

package/_site/_test/requirement-recorder-test.js

@@ -0,0 +1,173 @@
+// Run: node _site/_test/requirement-recorder-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { FIELD_LIMITS, SCHEMAS, DomainError } = require('../lib/contracts');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { RequirementRecorder } = require('../lib/requirement-recorder');
+const { ConversationStore } = require('../lib/conversation-store');
+const { createRequirementMetadataAdapter } = require('../lib/requirement-adapters');
+const { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
+const claudeRunner = require('../lib/claude-cli-runner');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-requirement-recorder-${process.pid}-`));
+const dataDir = path.join(temp, 'data');
+
+function git(repo, args) {
+  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
+  return String(result.stdout || '').trim();
+}
+
+function createRepo(name) {
+  const repo = path.join(temp, name);
+  fs.mkdirSync(repo, { recursive: true });
+  git(repo, ['init']);
+  git(repo, ['config', 'user.email', 'requirements@example.test']);
+  git(repo, ['config', 'user.name', 'Requirement Test']);
+  fs.writeFileSync(path.join(repo, 'README.md'), `# ${name}\n`, 'utf8');
+  git(repo, ['add', 'README.md']);
+  git(repo, ['commit', '-m', 'initial']);
+  return repo;
+}
+
+async function addProject(registry, projects, projectId, repoPath) {
+  await projects.create(projectId, {
+    displayName: projectId,
+    storageName: projectId,
+    repoPath,
+    knowledgePath: path.join(temp, 'knowledge', projectId),
+  }, { trackingStartCommit: git(repoPath, ['rev-parse', 'HEAD']) });
+  await registry.add(projectId, { displayName: projectId });
+}
+
+(async () => {
+  const layout = new StorageLayout({ dataDir });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await registry.initialize();
+  const repoA = createRepo('repo-a');
+  const repoB = createRepo('repo-b');
+  await addProject(registry, projects, 'project-a', repoA);
+  await addProject(registry, projects, 'project-b', repoB);
+
+  const recorder = new RequirementRecorder({ layout, registryStore: registry, projectStore: projects });
+  const conversations = new ConversationStore({ layout, projectStore: projects });
+  assert.strictEqual(fs.existsSync(layout.getProjectRequirementsPath('project-a')), false, 'requirements should be lazy-created');
+  assert.strictEqual(fs.existsSync(layout.getProjectRequirementsPath('project-b')), false, 'unused project should not have an empty requirements file');
+
+  const clients = ['claude', 'codex', 'opencode'];
+  const records = [];
+  for (const client of clients) {
+    const adapter = createRequirementMetadataAdapter(recorder, client);
+    records.push(await adapter({
+      projectId: 'project-a',
+      repoPath: repoA,
+      sessionId: `session-${client}`,
+      conversationId: `conversation-${client}`,
+      text: `Implement API key validation for ${client}.`,
+      apiKey: 'must-not-be-copied-from-metadata',
+    }));
+  }
+  const schemaKeys = Object.keys(records[0]).sort();
+  for (const record of records) {
+    assert.strictEqual(record.schema, SCHEMAS.requirement);
+    assert.deepStrictEqual(Object.keys(record).sort(), schemaKeys, 'all clients should produce the same requirement schema');
+    assert.strictEqual(record.projectId, 'project-a');
+    assert(record.requirementHash.startsWith('sha256:'), 'record should include a body hash');
+    assert(record.headAtRecord && record.branch, 'trusted Git metadata should be captured when available');
+  }
+  const serialized = fs.readFileSync(layout.getProjectConversationEventsPath('project-a'), 'utf8');
+  assert(!serialized.includes('must-not-be-copied-from-metadata'), 'credential-like adapter metadata must not be persisted');
+  assert.strictEqual(fs.existsSync(layout.getProjectRequirementsPath('project-a')), false, 'new explicit adapters must not create a second requirement store');
+  assert.strictEqual(fs.existsSync(layout.getProjectRequirementsPath('project-b')), false, 'recording project A must not touch project B');
+  assert.strictEqual(projects.readState('project-a').lastAnalyzedCommit, null, 'recording must not dispatch or advance analysis');
+  assert.strictEqual(fs.existsSync(path.join(temp, 'knowledge', 'project-a')), false, 'recording must not create knowledge content');
+
+  const resolvedByRoot = await recorder.recordRequirement({
+    repoPath: path.join(repoA, 'README.md'),
+    client: 'codex',
+    sessionId: 'root-resolved',
+    text: 'Resolve only from the current Git root.',
+  });
+  assert.strictEqual(resolvedByRoot.projectId, 'project-a');
+  await assert.rejects(
+    recorder.recordRequirement({ projectId: 'project-a', repoPath: repoB, client: 'codex', sessionId: 'wrong-root', text: 'Wrong repository.' }),
+    error => error.code === 'PROJECT_NOT_FOUND',
+  );
+
+  const concurrent = await Promise.all(Array.from({ length: 32 }, (_, index) => recorder.recordRequirement({
+    projectId: 'project-a',
+    client: 'codex',
+    sessionId: 'concurrent-session',
+    text: `Concurrent requirement ${index}`,
+  })));
+  assert.strictEqual(new Set(concurrent.map(item => item.id)).size, 32, 'concurrent records should have unique ids');
+  assert.strictEqual(conversations.readEvents('project-a').length, 36, 'every concurrent append should remain parseable in ConversationStore');
+
+  await assert.rejects(
+    recorder.recordRequirement({ projectId: 'project-a', client: 'codex', sessionId: 'oversized', text: 'x'.repeat(FIELD_LIMITS.requirement + 1) }),
+    error => error.code === 'INVALID_ARGUMENT' && /exceeds/.test(error.message),
+  );
+
+  // T14 / I-02: the Workbench itself never appends Development Conversation
+  // events; explicit record_requirement keeps working for Workbench sessions.
+  const chat = claudeRunner.startChatSession({
+    slug: 'project-a', projectPath: repoA, kbPath: path.join(temp, 'knowledge', 'project-a'),
+    aiProfile: { id: 'test-profile', implementation: 'claude-code-agent', mainModel: 'test-model' },
+  });
+  // T15: every internal SDK session carries the Bridge capture-disable markers.
+  const chatEnv = claudeRunner.getSession(chat.sessionId).claudeEnv || {};
+  assert.strictEqual(chatEnv.AI_CODING_EVENT_BRIDGE_CAPTURE, '0', 'internal SDK sessions disable Bridge capture');
+  assert.strictEqual(chatEnv.AI_CODING_EVENT_ORIGIN, 'project-knowledge-internal', 'internal SDK sessions are marked as Project-Knowledge internal');
+  const beforeWorkbench = conversations.readEvents('project-a').length;
+  const explicitRecord = await recorder.recordRequirement({
+    projectId: 'project-a', repoPath: repoA, client: 'claude', sessionId: chat.sessionId, text: 'Explicit MCP requirement for a Workbench session.',
+  });
+  const explicitUser = conversations.readEvents('project-a').find(event => event.legacyRequirementId === explicitRecord.id);
+  assert(explicitUser, 'explicit record_requirement still persists for Workbench sessions');
+  for (const listener of claudeRunner.getSession(chat.sessionId).listeners) listener({ type: 'claude/result', result: 'Workbench reply must NOT be captured.', isError: false });
+  await new Promise(resolve => setTimeout(resolve, 100));
+  const afterWorkbench = conversations.readEvents('project-a');
+  assert.strictEqual(afterWorkbench.length, beforeWorkbench + 1, 'only the explicit requirement was appended');
+  assert(!afterWorkbench.some(event => String(event.content || '').includes('Workbench reply must NOT be captured.')), 'no embedded assistant capture exists');
+  assert(!afterWorkbench.some(event => event.rawEventType === 'embedded-claude-result'), 'the embedded capture path is gone');
+  claudeRunner.deleteSession(chat.sessionId);
+
+  const failingRecorder = new RequirementRecorder({
+    layout,
+    projectStore: projects,
+    conversationStore: { appendEvent: async () => { throw new Error('disk full'); } },
+    resolver: { resolve: () => ({ projectId: 'project-a', config: { repoPath: repoA } }) },
+    gitReader: { currentContext: () => ({ branch: null, headAtRecord: null }) },
+  });
+  await assert.rejects(
+    failingRecorder.recordRequirement({ projectId: 'project-a', client: 'codex', sessionId: 'failure', text: 'Durability failure.', operationId: 'op-test-failure' }),
+    error => error.operationId === 'op-test-failure' && error.retryable === true,
+  );
+
+  const runtime = new KnowledgeToolRuntime({ dataDir, cwd: repoA });
+  const toolResult = await runtime.recordRequirement({
+    projectId: 'project-b',
+    repoPath: repoB,
+    client: 'opencode',
+    sessionId: 'mcp-session',
+    text: 'MCP metadata write only.',
+  });
+  assert(toolResult.requirementId && !Object.hasOwn(toolResult, 'requirement'), 'MCP result should return an id without echoing private text');
+  assert.strictEqual(conversations.readEvents('project-b').length, 1, 'MCP runtime should append to the shared ConversationStore');
+  assert.strictEqual(fs.existsSync(layout.getProjectRequirementsPath('project-b')), false, 'MCP must not create legacy requirements.jsonl');
+  await runtime.close();
+
+  console.log('requirement-recorder-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});

package/_site/_test/run-all-tests.js

@@ -0,0 +1,156 @@
+// _site/_test/run-all-tests.js
+//
+// Single-command regression suite runner. Iterates the canonical test files
+// under _site/_test/ (everything matching *-test.js) and runs each one in a
+// separate child process, capturing exit code, duration, and the last few
+// lines of output. Writes a Markdown report to TEST-REPORT.md.
+//
+// Usage:
+//   node _site/_test/run-all-tests.js                  # run all *-test.js
+//   node _site/_test/run-all-tests.js --no-report      # do not write report
+//
+// Exit code is 0 only if every test passes.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TEST_DIR = __dirname;
+const REPORT_PATH = path.join(TEST_DIR, 'TEST-REPORT.md');
+
+const args = process.argv.slice(2);
+const WRITE_REPORT = !args.includes('--no-report');
+const PER_TEST_TIMEOUT_MS = Number(process.env.PK_TEST_TIMEOUT_MS || 90_000);
+
+function listTestFiles() {
+  return fs.readdirSync(TEST_DIR)
+    .filter(file => file.endsWith('-test.js'))
+    .filter(file => file !== 'run-all-tests.js')
+    .sort();
+}
+
+function tail(text, lines = 12) {
+  const arr = String(text || '').split(/\r?\n/).filter(Boolean);
+  return arr.slice(-lines).join('\n');
+}
+
+function classifyFailure(result) {
+  if (result.status !== null) {
+    return { kind: 'exit', label: `FAIL (exit ${result.status})` };
+  }
+  if (result.error && result.error.code === 'ETIMEDOUT') {
+    return { kind: 'timeout', label: `TIMEOUT (killed after ${PER_TEST_TIMEOUT_MS}ms, signal ${result.signal || 'none'})` };
+  }
+  const code = result.error && result.error.code ? result.error.code : 'unknown';
+  return { kind: 'error', label: `FAIL (spawn error ${code}, signal ${result.signal || 'none'})` };
+}
+
+function runOne(file) {
+  const start = Date.now();
+  // Every test child gets its own Bridge journal sandbox so hook-trigger /
+  // server runtimes never touch the developer's ~/.ai-coding-event-bridge.
+  const bridgeHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-bridge-${process.pid}-`));
+  const result = spawnSync(process.execPath, [path.join(TEST_DIR, file)], {
+    cwd: ROOT,
+    encoding: 'utf-8',
+    timeout: PER_TEST_TIMEOUT_MS,
+    env: { ...process.env, FORCE_COLOR: '0', AI_CODING_EVENT_BRIDGE_HOME: bridgeHome, KB_MODULES_AUTOSTART: '0' },
+  });
+  try { fs.rmSync(bridgeHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
+  const failure = result.status === 0 ? null : classifyFailure(result);
+  return {
+    file,
+    passed: result.status === 0,
+    failureKind: failure ? failure.kind : null,
+    failureLabel: failure ? failure.label : null,
+    exitCode: result.status,
+    signal: result.signal,
+    spawnErrorCode: result.error && result.error.code ? result.error.code : null,
+    durationMs: Date.now() - start,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    outputTail: tail(`${result.stdout || ''}\n${result.stderr || ''}`.trim()),
+  };
+}
+
+(async () => {
+  const files = listTestFiles();
+  console.log(`Running ${files.length} test file(s)...\n`);
+
+  const results = [];
+  let totalDuration = 0;
+  for (const file of files) {
+    process.stdout.write(`> ${file} ... `);
+    const result = runOne(file);
+    totalDuration += result.durationMs;
+    results.push(result);
+
+    if (result.passed) {
+      console.log(`PASS (${result.durationMs}ms)`);
+    } else {
+      console.log(`${result.failureLabel}, ${result.durationMs}ms`);
+      if (result.outputTail) {
+        console.log('--- tail ---');
+        console.log(result.outputTail);
+        console.log('--- end tail ---');
+      }
+    }
+  }
+
+  const passed = results.filter(result => result.passed).length;
+  const failed = results.length - passed;
+  console.log('\n=========================================');
+  console.log(`Regression suite: ${passed} passed, ${failed} failed (${totalDuration}ms total)`);
+  console.log('=========================================\n');
+
+  if (WRITE_REPORT) {
+    const lines = [];
+    lines.push('# KB Management Site Regression Test Report');
+    lines.push('');
+    lines.push(`**Generated**: ${new Date().toISOString()}`);
+    lines.push(`**Node**: ${process.version}`);
+    lines.push('**Runner**: node _site/_test/run-all-tests.js');
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`**Per-test timeout**: ${PER_TEST_TIMEOUT_MS}ms (override with PK_TEST_TIMEOUT_MS)`);
+    lines.push('');
+    lines.push('| # | File | Status | Exit | Duration |');
+    lines.push('|--:|------|:------:|-----:|---------:|');
+    results.forEach((result, index) => {
+      const status = result.passed ? 'PASS' : (result.failureKind === 'timeout' ? 'TIMEOUT' : 'FAIL');
+      const exit = result.passed
+        ? String(result.exitCode)
+        : `${result.exitCode}${result.signal ? `, signal ${result.signal}` : ''}${result.spawnErrorCode ? `, error ${result.spawnErrorCode}` : ''}`;
+      lines.push(`| ${index + 1} | \`${result.file}\` | ${status} | ${exit} | ${result.durationMs}ms |`);
+    });
+    lines.push('');
+    lines.push(`**Total**: ${results.length} | **Passed**: ${passed} | **Failed**: ${failed} | **Time**: ${totalDuration}ms`);
+    lines.push('');
+
+    const failures = results.filter(result => !result.passed);
+    if (failures.length) {
+      lines.push('## Failures');
+      lines.push('');
+      for (const result of failures) {
+        lines.push(`### ${result.file}`);
+        lines.push('');
+        lines.push('```');
+        lines.push(result.outputTail);
+        lines.push('```');
+        lines.push('');
+      }
+    }
+
+    try {
+      fs.writeFileSync(REPORT_PATH, lines.join('\n'), 'utf-8');
+      console.log(`Report written to: ${REPORT_PATH}`);
+    } catch (e) {
+      console.error(`Failed to write report: ${e.message}`);
+    }
+  }
+
+  process.exit(failed > 0 ? 1 : 0);
+})();

package/_site/_test/runtime-endpoint-test.js

@@ -0,0 +1,64 @@
+// Run: node _site/_test/runtime-endpoint-test.js
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const runtime = require('../lib/runtime-endpoint');
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runtime-endpoint-${process.pid}-`));
+
+try {
+  assert(runtime.readEndpoint(dataDir) === null, 'missing endpoint should read as null');
+
+  const written = runtime.writeEndpoint(dataDir, {
+    pid: process.pid,
+    host: '127.0.0.1',
+    port: 5761,
+    mode: 'desktop',
+  });
+  assert(written.schema === runtime.SCHEMA, 'endpoint schema should be current');
+  assert(written.mode === 'desktop', 'endpoint should preserve runtime mode');
+  assert(runtime.readLiveEndpoint(dataDir).pid === process.pid, 'current process endpoint should be live');
+
+  runtime.clearEndpoint(dataDir, { pid: process.pid + 1 });
+  assert(runtime.readEndpoint(dataDir) !== null, 'a different process must not clear the endpoint');
+  runtime.clearEndpoint(dataDir, { pid: process.pid });
+  assert(runtime.readEndpoint(dataDir) === null, 'owner should clear the endpoint');
+
+  const claim = runtime.claimEndpoint(dataDir, {
+    pid: process.pid,
+    host: '127.0.0.1',
+    port: 5762,
+    mode: 'cli',
+  });
+  assert(claim.claimed === true, 'first process should claim an empty endpoint');
+  const duplicate = runtime.claimEndpoint(dataDir, {
+    pid: process.pid + 1,
+    host: '127.0.0.1',
+    port: 5763,
+    mode: 'desktop',
+  });
+  assert(duplicate.claimed === false, 'second process must not replace a live endpoint');
+  assert(duplicate.endpoint.pid === process.pid, 'duplicate should discover the owner');
+  runtime.clearEndpoint(dataDir, { pid: process.pid });
+
+  runtime.writeEndpoint(dataDir, { pid: 2147483646, host: 'localhost', port: 5757 });
+  assert(runtime.readLiveEndpoint(dataDir) === null, 'dead process endpoint should be rejected');
+  assert(!fs.existsSync(runtime.endpointPath(dataDir)), 'dead process endpoint should be removed');
+
+  fs.writeFileSync(runtime.endpointPath(dataDir), JSON.stringify({
+    schema: runtime.SCHEMA,
+    pid: process.pid,
+    host: 'example.com',
+    port: 5757,
+  }), 'utf-8');
+  assert(runtime.readEndpoint(dataDir) === null, 'remote hosts must never be accepted');
+
+  console.log('runtime-endpoint-test PASS');
+} finally {
+  fs.rmSync(dataDir, { recursive: true, force: true });
+}