@sanqianx/project-knowledge 4.6.1

package/_site/_test/cross-repo-isolation-e2e-test.js

@@ -0,0 +1,187 @@
+// Run: node _site/_test/cross-repo-isolation-e2e-test.js
+//
+// GATE CROSS-REPO-001 end to end with real Git workspaces and the real
+// Bridge journal: CCS imported / CCB unimported, commit boundary ordering
+// (append -> drainThrough -> writeBoundary -> bind), no CCB substitution.
+// Also covers CROSS-REPO-002 (same remote, different clones), WORKTREE-001
+// and NESTED-CWD-001 at the consumer level.
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { ConversationStore } = require('../lib/conversation-store');
+const { BridgeAdapter } = require('../lib/bridge-adapter');
+const { BridgeConsumerService } = require('../lib/bridge-consumer-service');
+const { CommitConversationBinder } = require('../lib/commit-conversation-binder');
+const claudeConnector = require('@sanqianx/ai-coding-event-bridge').claudeHookEntry;
+const bridgeModule = require('@sanqianx/ai-coding-event-bridge');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-cross-repo-e2e-${process.pid}-`));
+const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+const registry = new ProjectRegistryStore({ layout });
+const projects = new ProjectStore({ layout });
+const bridgeHome = path.join(temp, 'bridge-home');
+const adapter = new BridgeAdapter({ dataDir: layout.dataDir, bridgeModule, bridgeHomeDir: bridgeHome });
+const store = new ConversationStore({ layout, projectStore: projects, logger: null });
+const service = new BridgeConsumerService({
+  bridgeAdapter: adapter, conversationStore: store, registryStore: registry, projectStore: projects, logger: null,
+});
+
+function git(dir, args) {
+  execSync(`git ${args.map(value => `"${value.replace(/"/g, '\\"')}"`).join(' ')}`, { cwd: dir, stdio: 'ignore' });
+}
+
+function makeRepo(name, origin) {
+  const dir = path.join(temp, name);
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, ['init', '-q']);
+  git(dir, ['config', 'user.email', 'e2e@example.test']);
+  git(dir, ['config', 'user.name', 'E2E Test']);
+  if (origin) git(dir, ['remote', 'add', 'origin', origin]);
+  fs.writeFileSync(path.join(dir, 'README.md'), `# ${name}\n`);
+  git(dir, ['add', '.']);
+  git(dir, ['commit', '-q', '-m', 'init']);
+  return dir;
+}
+
+function commitFile(repo, name, content) {
+  fs.writeFileSync(path.join(repo, `${name}.txt`), `${content}\n`);
+  git(repo, ['add', '.']);
+  git(repo, ['commit', '-q', '-m', name]);
+  return execSync('git rev-parse HEAD', { cwd: repo, encoding: 'utf8' }).trim();
+}
+
+// External Claude session in a workspace: UserPromptSubmit + Stop payloads.
+async function externalClaudeTurn(repoDir, sessionId, prompt, reply) {
+  const user = await claudeConnector.main({
+    home: bridgeHome,
+    payload: { hookName: 'UserPromptSubmit', session_id: sessionId, cwd: repoDir, prompt },
+  });
+  const assistant = await claudeConnector.main({
+    home: bridgeHome,
+    payload: { hookName: 'Stop', session_id: sessionId, cwd: repoDir, last_assistant_message: reply },
+  });
+  return { user, assistant };
+}
+
+async function importProject(projectId, repoDir) {
+  const identity = (await bridgeModule.resolveRepoContext(repoDir)).repoIdentity;
+  const watermark = await adapter.getHighWatermark({});
+  await projects.create(projectId, {
+    storageName: projectId, displayName: projectId,
+    repoPath: repoDir, knowledgePath: path.join(temp, 'knowledge', projectId),
+    repoIdentity: identity,
+  }, { conversationBaselineCursor: watermark.status === 'captured' ? watermark.cursor : null });
+  await registry.add(projectId, { displayName: projectId });
+  return identity;
+}
+
+// T13 ordering for one commit: boundary append -> drainThrough -> project
+// boundary freeze -> binder bind (the reconcile/analyzer tail is owned by the
+// hook path and covered by full-integration-e2e-test).
+async function boundaryAndBind(projectId, repoDir, commitSha, identity) {
+  const boundaryResult = await adapter.appendCommitBoundary({
+    projectId,
+    repoIdentity: identity,
+    commitSha,
+    parentShas: [],
+    branch: 'main',
+    committedAt: new Date().toISOString(),
+    operationId: `op-e2e-${commitSha.slice(0, 8)}`,
+  });
+  assert.strictEqual(boundaryResult.status, 'captured');
+  const boundary = boundaryResult.boundary;
+  await service.drainThrough(boundary.journalSequence, 'commit-boundary');
+  store.writeBoundary(projectId, boundary);
+  const binder = new CommitConversationBinder({ layout, projectStore: projects, conversationStore: store });
+  return binder.bind({ projectId, commitSha });
+}
+
+(async () => {
+  await registry.initialize();
+  const ccs = makeRepo('CCS', 'git@github.com:acme/ccs.git');
+  const ccb = makeRepo('CCB', 'git@github.com:acme/ccb.git');
+
+  const ccsIdentity = await importProject('project-ccs', ccs);
+  const ccbIdentity = (await bridgeModule.resolveRepoContext(ccb)).repoIdentity;
+  assert.notStrictEqual(ccsIdentity.workspaceId, ccbIdentity.workspaceId);
+  await service.start();
+
+  // Phase A — develop in unimported CCB.
+  await externalClaudeTurn(ccb, 'ccb-session-1', 'Modify CCB parser', 'CCB parser modified');
+  await service.drain('notify');
+  assert.deepStrictEqual(store.readEvents('project-ccs'), [], 'CCS ConversationStore stays empty');
+  assert.ok(!fs.existsSync(path.dirname(layout.getProjectConversationEventsPath('project-ccb'))),
+    'no Project-Knowledge CCB conversation store is created merely because Bridge observed CCB');
+  const consumerAfterCcb = await adapter.getConsumer('project-knowledge');
+  assert.ok(consumerAfterCcb.consumer.ack > 0, 'consumer ACK advanced through the deterministically skipped CCB events');
+
+  // Phase B — develop in imported CCS (from a nested directory: NESTED-CWD-001).
+  fs.mkdirSync(path.join(ccs, 'modules', 'foo'), { recursive: true });
+  const nestedTurn = await externalClaudeTurn(path.join(ccs, 'modules', 'foo'), 'ccs-session-1', 'Modify CCS autofocus', 'CCS autofocus modified');
+  await service.drain('notify');
+  const ccsEvents = store.readEvents('project-ccs');
+  assert.strictEqual(ccsEvents.length, 2, 'exactly the CCS turn is projected');
+  assert.ok(ccsEvents.every(event => event.repoIdentity.workspaceId === ccsIdentity.workspaceId),
+    'nested-cwd conversation resolves to the CCS workspace');
+  assert.strictEqual(ccsEvents[0].turnId, nestedTurn.user.turnId, 'user + assistant share one durable turnId');
+  assert.ok(!ccsEvents.some(event => event.content.includes('CCB')), 'no CCB content leaked into CCS');
+
+  // Phase C — commit CCS and freeze the snapshot.
+  const commitC = commitFile(ccs, 'ccs-change', 'autofocus fix');
+  const snapshotC = await boundaryAndBind('project-ccs', ccs, commitC, ccsIdentity);
+  assert.strictEqual(snapshotC.projectId, 'project-ccs');
+  assert.strictEqual(snapshotC.repoIdentity.workspaceId, ccsIdentity.workspaceId);
+  assert.ok(JSON.stringify(snapshotC).includes('Modify CCS autofocus'), 'snapshot contains the CCS turn');
+  assert.ok(!JSON.stringify(snapshotC).includes('Modify CCB parser'), 'snapshot never contains the CCB conversation');
+  assert.ok(snapshotC.turns.some(turn => turn.userEvents.length === 1 && turn.assistantEvents.length === 1),
+    'full turn (user + assistant) bound inside the boundary');
+
+  // Phase D — second CCS commit right after fresh CCB conversation.
+  await externalClaudeTurn(ccb, 'ccb-session-2', 'Another CCB task', 'CCB task done');
+  const commitD = commitFile(ccs, 'ccs-second', 'unrelated change');
+  const snapshotD = await boundaryAndBind('project-ccs', ccs, commitD, ccsIdentity);
+  assert.strictEqual(snapshotD.status, 'no-new-user-prompt', 'deterministic no-evidence status');
+  assert.ok(!JSON.stringify(snapshotD).includes('Another CCB task'), 'recent CCB conversation is never substituted');
+
+  // CROSS-REPO-002 — same remote, different clones.
+  const cloneA = makeRepo('clone-a', 'git@github.com:acme/ccs.git');
+  const cloneB = makeRepo('clone-b', 'git@github.com:acme/ccs.git');
+  const identityA = (await bridgeModule.resolveRepoContext(cloneA)).repoIdentity;
+  const identityB = (await bridgeModule.resolveRepoContext(cloneB)).repoIdentity;
+  assert.strictEqual(identityA.remote, ccsIdentity.remote, 'remotes are equal');
+  assert.notStrictEqual(identityA.workspaceId, identityB.workspaceId, 'workspace identity differs');
+  await importProject('project-clone-a', cloneA);
+  await externalClaudeTurn(cloneB, 'clone-b-session', 'work in clone B', 'clone B reply');
+  await service.drain('notify');
+  assert.deepStrictEqual(store.readEvents('project-clone-a'), [], 'clone B conversation never enters the clone A project');
+  assert.ok(!fs.existsSync(layout.getProjectConversationEventsPath('project-clone-b')) || store.readEvents('project-clone-b').length === 0,
+    'unimported clone B has no projected conversation');
+
+  // WORKTREE-001 — shared commonDir, distinct workspaceIds, no cross-binding.
+  const wtMain = makeRepo('wt-main', 'git@github.com:acme/wt.git');
+  fs.mkdirSync(path.join(temp, 'wt-holder'), { recursive: true });
+  const wtA = path.join(temp, 'wt-holder', 'wt-a');
+  const wtB = path.join(temp, 'wt-holder', 'wt-b');
+  git(wtMain, ['worktree', 'add', '-q', wtA, 'HEAD']);
+  git(wtMain, ['worktree', 'add', '-q', wtB, 'HEAD']);
+  const wtMainIdentity = (await bridgeModule.resolveRepoContext(wtMain)).repoIdentity;
+  const wtAIdentity = (await bridgeModule.resolveRepoContext(wtA)).repoIdentity;
+  const wtBIdentity = (await bridgeModule.resolveRepoContext(wtB)).repoIdentity;
+  assert.strictEqual(wtAIdentity.commonDir, wtMainIdentity.commonDir, 'worktrees share commonDir');
+  assert.notStrictEqual(wtAIdentity.workspaceId, wtBIdentity.workspaceId);
+  await importProject('project-wt-a', wtA);
+  await externalClaudeTurn(wtB, 'wt-b-session', 'work in worktree B', 'worktree B reply');
+  await service.drain('notify');
+  assert.deepStrictEqual(store.readEvents('project-wt-a'), [], 'worktree B conversation is not auto-bound to worktree A');
+
+  console.log('cross-repo-isolation-e2e-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/data-dir-migration-test.js

@@ -0,0 +1,77 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const dataDir = require('../lib/data-dir');
+const { LEGACY_ASSETS } = require('../lib/legacy-data-manifest');
+
+function temp(name) { return fs.mkdtempSync(path.join(os.tmpdir(), `pk-data-dir-${name}-`)); }
+function clean(dir) { fs.rmSync(dir, { recursive: true, force: true }); }
+function write(file, value = '{}') { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, value); }
+
+(() => {
+  // Resolution must be diagnostic-safe: resolving never creates the candidate.
+  const missing = path.join(temp('resolve'), 'not-created');
+  try {
+    assert.equal(dataDir.resolveDataDirPath({ dataDir: missing }), path.resolve(missing));
+    assert.equal(fs.existsSync(missing), false);
+    dataDir.ensureDataDir(missing);
+    assert.equal(fs.existsSync(missing), true);
+  } finally { clean(path.dirname(missing)); }
+
+  const legacy = temp('legacy');
+  const target = temp('target');
+  const saved = process.env.KB_DATA_DIR;
+  try {
+    write(path.join(legacy, 'projects.json'), JSON.stringify({ old: { repoPath: 'C:/legacy' } }));
+    write(path.join(legacy, 'ai-profiles.json'), JSON.stringify({ profiles: [{ id: 'primary', apiKey: 'test-secret' }] }));
+    write(path.join(legacy, 'knowledge-store.json'), JSON.stringify({ rootPath: 'C:/knowledge' }));
+    write(path.join(legacy, 'embedding-config.json'), JSON.stringify({ modelId: 'model', localModelPath: 'C:/models', localFilesOnly: true }));
+    write(path.join(legacy, 'knowledge-scopes.json'), JSON.stringify({ scopes: ['p'] }));
+    write(path.join(legacy, 'models', 'nested', 'model.onnx'), 'model-bytes');
+    // An empty target registry is non-authoritative and must not suppress legacy data.
+    write(path.join(target, 'projects.json'), '{}');
+    process.env.KB_DATA_DIR = target;
+    dataDir._resetCache();
+    const result = dataDir.migrateFromLegacy({ legacyRoot: legacy });
+    assert.equal(result.ok, true);
+    assert.equal(result.migrated, true);
+    assert.equal(JSON.parse(fs.readFileSync(path.join(target, 'projects.json'))).old.repoPath, 'C:/legacy');
+    assert.equal(JSON.parse(fs.readFileSync(path.join(target, 'ai-profiles.json'))).profiles.length, 1);
+    assert.equal(JSON.parse(fs.readFileSync(path.join(target, 'embedding-config.json'))).modelId, 'model');
+    assert.equal(fs.readFileSync(path.join(target, 'models', 'nested', 'model.onnx'), 'utf8'), 'model-bytes');
+    assert(LEGACY_ASSETS.some(asset => asset.source === 'embedding-config.json'));
+    assert(LEGACY_ASSETS.some(asset => asset.source === 'models'));
+  } finally { process.env.KB_DATA_DIR = saved; dataDir._resetCache(); clean(legacy); clean(target); }
+
+  const source = temp('conflict-source');
+  const destination = temp('conflict-destination');
+  try {
+    write(path.join(source, 'projects.json'), JSON.stringify({ old: { repoPath: 'C:/old' } }));
+    write(path.join(destination, 'projects.json'), JSON.stringify({ newer: { repoPath: 'C:/new' } }));
+    process.env.KB_DATA_DIR = destination;
+    dataDir._resetCache();
+    const result = dataDir.migrateFromLegacy({ legacyRoot: source });
+    assert.equal(result.ok, false);
+    assert.equal(result.requiresManualRecovery, true);
+    assert.equal(JSON.parse(fs.readFileSync(path.join(destination, 'projects.json'))).newer.repoPath, 'C:/new');
+  } finally { process.env.KB_DATA_DIR = saved; dataDir._resetCache(); clean(source); clean(destination); }
+
+  // The installed package can contain empty scaffolding directories (for
+  // example projects/) while the user data directory contains real projects.
+  // Empty package scaffolding is not a legacy source and must not block startup.
+  const packageRoot = temp('empty-package-root');
+  const userData = temp('existing-user-data');
+  try {
+    fs.mkdirSync(path.join(packageRoot, 'projects'), { recursive: true });
+    write(path.join(userData, 'projects', 'project-real', 'config.json'), JSON.stringify({ id: 'project-real' }));
+    process.env.KB_DATA_DIR = userData;
+    dataDir._resetCache();
+    const result = dataDir.migrateFromLegacy({ legacyRoot: packageRoot });
+    assert.equal(result.ok, true, 'empty package scaffolding must not be a migration conflict');
+    assert.equal(result.migrated, false);
+    assert.equal(result.reason, 'no legacy assets found');
+    assert.equal(fs.existsSync(path.join(userData, 'projects', 'project-real', 'config.json')), true);
+  } finally { process.env.KB_DATA_DIR = saved; dataDir._resetCache(); clean(packageRoot); clean(userData); }
+  console.log('data-dir-migration-test PASS');
+})();

package/_site/_test/desktop-browser-compat-test.js

@@ -0,0 +1,28 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const ui = fs.readFileSync(path.join(ROOT, 'ui', 'index.html'), 'utf8');
+const app = fs.readFileSync(path.join(ROOT, 'ui', 'app.js'), 'utf8');
+const css = fs.readFileSync(path.join(ROOT, 'ui', 'app.css'), 'utf8');
+const preload = fs.readFileSync(path.join(ROOT, 'desktop', 'preload.cjs'), 'utf8');
+const main = fs.readFileSync(path.join(ROOT, 'desktop', 'main.cjs'), 'utf8');
+const runtime = require(path.join(ROOT, 'desktop', 'lib', 'backend-runtime.cjs'));
+
+assert(ui.includes('<script src="/app.js"></script>'), 'product shell script is missing');
+assert.doesNotThrow(() => new Function(app), 'product shell must parse in the desktop Chromium runtime');
+assert(!app.includes('window.open('), 'product shell must not open untrusted browser windows');
+assert(!(ui + app).includes('file://'), 'product shell must not expose local file URLs');
+assert(app.includes('URL.createObjectURL(blob)') && app.includes('URL.revokeObjectURL(url)'), 'diagnostic export must use a bounded blob URL');
+assert(app.includes('navigator.clipboard') && app.includes("document.execCommand('copy')"), 'copy must have a desktop-compatible fallback');
+assert(css.includes('@media(prefers-reduced-motion:reduce)'), 'reduced-motion compatibility is required');
+assert(css.includes('@media(max-width:760px)'), 'desktop narrow-window layout is required');
+
+assert(preload.includes('project-knowledge:open-external') && preload.includes('openExternal:'), 'desktop preload bounded external-link bridge regressed');
+assert(main.includes('externalLink.registerExternalLink'), 'desktop main external-link policy regressed');
+assert(runtime.isAllowedExternalUrl('https://github.com/login/device'), 'HTTPS authorization URL policy regressed');
+assert(!runtime.isAllowedExternalUrl('file:///C:/Users/test/token.txt'), 'local files must not cross the desktop boundary');
+assert(!runtime.isAllowedExternalUrl('javascript:alert(1)'), 'script URLs must not cross the desktop boundary');
+
+console.log('desktop browser compatibility test PASS');

package/_site/_test/desktop-hook-runtime-regression-test.js

@@ -0,0 +1,204 @@
+// _site/_test/desktop-hook-runtime-regression-test.js
+//
+// Characterization harness for the post-commit hook runtime contract.
+// The current regression (RC-01) is that buildHookBody defaults
+// nodeExecutable to process.execPath, which in Desktop mode points at the
+// Electron executable rather than a real Node binary. When Git invokes the
+// hook from a normal shell, the script therefore launches Electron instead
+// of executing hook-trigger.js.
+//
+// These tests must:
+//   - PASS for healthy CLI installs with an explicit Node executable;
+//   - EXPOSE the regression when the default is left to process.execPath in a
+//     simulated Desktop environment.
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const {
+  buildHookBody,
+  installHook,
+  readHookStatus,
+  parseManagedMarker,
+  HOOK_MARKER,
+} = require('../lib/hook-manager');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TRIGGER = path.join(ROOT, '_site', 'scripts', 'hook-trigger.js');
+
+function git(repo, args) {
+  const result = spawnSync('git', ['-C', repo, ...args], {
+    encoding: 'utf8',
+    windowsHide: true,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed: ${result.status}`);
+  return String(result.stdout || '').trim();
+}
+
+function makeRepo() {
+  const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-desktop-hook-'));
+  git(repo, ['init', '-q', '-b', 'main']);
+  git(repo, ['config', 'user.email', 'desktop-hook@example.local']);
+  git(repo, ['config', 'user.name', 'Desktop Hook Test']);
+  fs.writeFileSync(path.join(repo, 'README.md'), '# desktop hook\n');
+  git(repo, ['add', 'README.md']);
+  git(repo, ['commit', '-q', '-m', 'initial']);
+  return repo;
+}
+
+(async () => {
+  // ---- Case 1: explicit real Node executable must be persisted verbatim ----
+  {
+    const repo = makeRepo();
+    const projectId = 'project-desktop-hook';
+    const fakeNode = path.join(ROOT, '_site', '_test', 'fixtures', 'fake-browser-exit.js');
+    const body = buildHookBody({
+      projectId,
+      triggerScriptPath: TRIGGER,
+      nodeExecutable: fakeNode,
+    });
+    assert(body.includes(fakeNode.replace(/\\/g, '/')), 'explicit Node executable must be embedded in hook body');
+    assert(body.includes('ELECTRON_RUN_AS_NODE=1'), 'T02 contract: hook body must prefix ELECTRON_RUN_AS_NODE=1 so Desktop packaging runs as Node');
+    fs.rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ---- Case 2: installHook must accept an explicit nodeExecutable ----
+  {
+    const repo = makeRepo();
+    const projectId = 'project-desktop-hook-install';
+    const fakeNode = path.join(ROOT, '_site', '_test', 'fixtures', 'fake-browser-exit.js');
+    const installed = installHook({
+      repoPath: repo,
+      projectId,
+      triggerScriptPath: TRIGGER,
+      nodeExecutable: fakeNode,
+    });
+    assert.strictEqual(installed.ok, true);
+    const hookBody = fs.readFileSync(installed.hookPath, 'utf8');
+    assert(hookBody.includes(fakeNode.replace(/\\/g, '/')), 'installed hook body must embed the explicit Node executable');
+    assert.strictEqual(parseManagedMarker(hookBody).projectId, projectId);
+    fs.rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ---- Case 3: CHARACTERIZATION — Desktop executable prefix ----
+  // The Desktop backend launches the core CLI through the Electron executable
+  // with ELECTRON_RUN_AS_NODE=1 in the backend child environment. A Git
+  // post-commit hook does NOT inherit that env var, so the hook body must
+  // explicitly set ELECTRON_RUN_AS_NODE=1 before invoking the executable,
+  // even when the executable is Electron (Desktop packaging).
+  {
+    const fakeElectron = path.join(os.tmpdir(), `fake-electron-${process.pid}.exe`);
+    const body = buildHookBody({
+      projectId: 'project-desktop-hook-default',
+      triggerScriptPath: TRIGGER,
+      nodeExecutable: fakeElectron,
+    });
+    assert(body.includes('ELECTRON_RUN_AS_NODE=1'),
+      'T02 contract: hook body must prefix ELECTRON_RUN_AS_NODE=1 so a Desktop Electron binary executes as Node');
+    assert(body.includes(fakeElectron.replace(/\\/g, '/')),
+      'hook body must embed the resolved executable verbatim');
+    assert(typeof body === 'string' && body.length > 0, 'hook body must be non-empty');
+  }
+
+  // ---- Case 4: hook runtime contract — trigger must run even with weird paths ----
+  // The hook body must work when the project path contains spaces. We install
+  // into a path that includes a literal space and confirm installHook + readback
+  // round-trip without escaping failures.
+  {
+    const base = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-desktop-hook-spaces-'));
+    const repo = path.join(base, 'project with spaces');
+    fs.mkdirSync(repo, { recursive: true });
+    git(repo, ['init', '-q', '-b', 'main']);
+    git(repo, ['config', 'user.email', 'spaces@example.local']);
+    git(repo, ['config', 'user.name', 'Spaces Test']);
+    fs.writeFileSync(path.join(repo, 'README.md'), '# spaces\n');
+    git(repo, ['add', 'README.md']);
+    git(repo, ['commit', '-q', '-m', 'initial']);
+    const fakeNode = path.join(ROOT, '_site', '_test', 'fixtures', 'fake-browser-exit.js');
+    const installed = installHook({
+      repoPath: repo,
+      projectId: 'project-spaces',
+      triggerScriptPath: TRIGGER,
+      nodeExecutable: fakeNode,
+    });
+    assert.strictEqual(installed.ok, true);
+    const status = readHookStatus({ repoPath: repo, projectId: 'project-spaces' });
+    assert.strictEqual(status.kbManaged, true);
+    fs.rmSync(base, { recursive: true, force: true });
+  }
+
+  // ---- Case 5: missing required args must still produce a valid hook body ----
+  // This guards the "fail-open" property required by I-12 (Git commit must
+  // never fail because Project-Knowledge is unavailable).
+  {
+    let threw = false;
+    try {
+      buildHookBody({ projectId: '', triggerScriptPath: TRIGGER, nodeExecutable: process.execPath });
+    } catch (error) { threw = true; }
+    assert.strictEqual(threw, true, 'empty projectId must be rejected by buildHookBody');
+  }
+
+  // ---- Case 6: end-to-end execution — hook body actually runs the trigger ----
+  // Build a tiny "trigger" that records its argv + ELECTRON_RUN_AS_NODE env
+  // to a journal, install the hook pointing at it, then exec the installed
+  // hook via sh and assert the journal was written. This proves the hook
+  // body resolves the executable correctly and that ELECTRON_RUN_AS_NODE=1
+  // is set before the trigger runs (so a Desktop Electron binary would
+  // execute as Node instead of launching as a GUI).
+  {
+    const repo = makeRepo();
+    const journal = path.join(os.tmpdir(), `pk-desktop-hook-journal-${process.pid}.json`);
+    const triggerBody = `#!/usr/bin/env node
+const fs = require('fs');
+fs.writeFileSync(${JSON.stringify(journal)}, JSON.stringify({
+  argv: process.argv.slice(2),
+  electronRunAsNode: process.env.ELECTRON_RUN_AS_NODE || null,
+  execPath: process.execPath,
+}, null, 2));
+process.exit(0);
+`;
+    const fakeTrigger = path.join(os.tmpdir(), `pk-fake-trigger-${process.pid}.js`);
+    fs.writeFileSync(fakeTrigger, triggerBody);
+    const projectId = 'project-hook-exec';
+    const fakeNode = process.execPath; // real Node in the test env
+    const installed = installHook({
+      repoPath: repo,
+      projectId,
+      triggerScriptPath: fakeTrigger,
+      nodeExecutable: fakeNode,
+    });
+    assert.strictEqual(installed.ok, true);
+    // Execute with Git for Windows' own POSIX shell. A bare `bash` can resolve
+    // to WSL, which cannot consume a Windows hook path.
+    let sh = 'sh';
+    if (process.platform === 'win32') {
+      const where = spawnSync('where.exe', ['git'], { encoding: 'utf8', windowsHide: true });
+      const gitPath = String(where.stdout || '').split(/\r?\n/).find(Boolean);
+      const candidate = gitPath && path.join(path.dirname(path.dirname(gitPath)), 'bin', 'sh.exe');
+      sh = candidate && fs.existsSync(candidate) ? candidate : 'bash';
+    }
+    const result = spawnSync(sh, [installed.hookPath], {
+      encoding: 'utf8',
+      windowsHide: true,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    assert.strictEqual(result.status, 0, `hook must exit 0 even when Project-Knowledge is unavailable; got ${result.status}\n${result.stderr || ''}`);
+    assert(fs.existsSync(journal), 'fake trigger must be executed by the hook body');
+    const recorded = JSON.parse(fs.readFileSync(journal, 'utf8'));
+    assert.strictEqual(recorded.electronRunAsNode, '1', 'ELECTRON_RUN_AS_NODE=1 must be set before the trigger runs');
+    assert(recorded.argv.includes('--project-id'), 'trigger argv must include --project-id');
+    assert(recorded.argv.includes(projectId), 'trigger argv must include the project id');
+    fs.rmSync(repo, { recursive: true, force: true });
+    fs.rmSync(fakeTrigger, { force: true });
+    fs.rmSync(journal, { force: true });
+  }
+
+  console.log('desktop-hook-runtime-regression-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});

package/_site/_test/embedding-config-test.js

@@ -0,0 +1,32 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { SettingsStore } = require('../lib/settings-store');
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'embedding-config-test-'));
+  const layout = new StorageLayout({ dataDir: temp });
+  const store = new SettingsStore({ layout });
+  try {
+    const defaults = await store.initialize();
+    assert.deepStrictEqual(defaults.embedding, {});
+    const saved = await store.updatePatch({
+      embedding: {
+        modelId: 'Xenova/all-MiniLM-L6-v2',
+        remoteHost: 'https://model-mirror.example/',
+        localModelPath: 'D:\\models',
+        localFilesOnly: true,
+      },
+    });
+    assert.equal(saved.embedding.remoteHost, 'https://model-mirror.example/');
+    assert.equal(store.read().embedding.localModelPath, 'D:\\models');
+    assert.equal(store.read().embedding.localFilesOnly, true);
+    assert.strictEqual(fs.existsSync(path.join(temp, 'embedding-config.json')), false, 'embedding settings must not use a second live config file');
+    assert.strictEqual(fs.existsSync(layout.getSettingsPath()), true);
+    console.log('embedding-config-test: PASS');
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/explicit-commit-processor-test.js

@@ -0,0 +1,37 @@
+const assert = require('assert');
+const { CommitReconciler } = require('../lib/commit-reconciler');
+
+const sha = suffix => `${'a'.repeat(39)}${suffix}`;
+const calls = [];
+let active = 0;
+let maxActive = 0;
+const completed = new Set();
+const projectStore = { readConfig: id => ({ projectId: id, enabled: true, repoPath: 'C:/fixture', knowledgePath: 'C:/knowledge' }) };
+const reconciler = new CommitReconciler({ projectStore, registryStore: {}, requireAiProfile: false });
+reconciler.processingLedger = {
+  read: (projectId, commitSha) => completed.has(`${projectId}:${commitSha}`) ? { status: 'completed' } : null,
+  complete: (projectId, commitSha) => { completed.add(`${projectId}:${commitSha}`); return { status: 'completed' }; },
+};
+reconciler.processCommit = async (projectId, _trigger, _operationId, _config, _branch, commitSha) => {
+  active += 1; maxActive = Math.max(maxActive, active); calls.push(`${projectId}:${commitSha}`);
+  await new Promise(resolve => setTimeout(resolve, 20));
+  active -= 1;
+  return { ok: true, commitSha, runId: `run-${commitSha.slice(-1)}`, claimFingerprint: `fp-${commitSha.slice(-1)}` };
+};
+
+(async () => {
+  const d = sha('d'); const e = sha('e'); const f = sha('f');
+  const duplicateA = reconciler.processCommitEvent({ projectId: 'project-a', commitSha: d, branch: 'main' });
+  const duplicateB = reconciler.processCommitEvent({ projectId: 'project-a', commitSha: d, branch: 'main' });
+  const next = reconciler.processCommitEvent({ projectId: 'project-a', commitSha: e, branch: 'main' });
+  const other = reconciler.processCommitEvent({ projectId: 'project-b', commitSha: f, branch: 'main' });
+  const [first, second, third, fourth] = await Promise.all([duplicateA, duplicateB, next, other]);
+  assert.equal(first.status, 'completed'); assert.equal(second.status, 'completed');
+  assert.equal(third.status, 'completed'); assert.equal(fourth.status, 'completed');
+  assert.deepEqual(calls.filter(value => value.startsWith('project-a:')), [`project-a:${d}`, `project-a:${e}`]);
+  assert.equal(calls.filter(value => value === `project-a:${d}`).length, 1, 'duplicate explicit Hook event must join');
+  assert(maxActive >= 2, 'different projects may process in parallel');
+  const repeated = await reconciler.processCommitEvent({ projectId: 'project-a', commitSha: d, branch: 'main' });
+  assert.equal(repeated.status, 'already-completed');
+  console.log('explicit-commit-processor-test PASS');
+})().catch(error => { console.error(error.stack || error.message); process.exit(1); });

package/_site/_test/fixtures/fake-browser-exit.js

@@ -0,0 +1,10 @@
+// Deterministic fake browser: writes its pid to KB_FAKE_BROWSER_PIDFILE,
+// prints a marker to stderr, then exits immediately without exposing CDP.
+const fs = require('fs');
+
+const pidFile = process.env.KB_FAKE_BROWSER_PIDFILE;
+if (pidFile) {
+  try { fs.writeFileSync(pidFile, String(process.pid)); } catch {}
+}
+process.stderr.write('fake-browser-exit stderr: simulated browser crash before CDP\n');
+process.exit(3);

package/_site/_test/fixtures/fake-browser-hang.js

@@ -0,0 +1,10 @@
+// Deterministic fake browser: writes its pid to KB_FAKE_BROWSER_PIDFILE,
+// stays alive forever, and never exposes a CDP endpoint.
+const fs = require('fs');
+
+const pidFile = process.env.KB_FAKE_BROWSER_PIDFILE;
+if (pidFile) {
+  try { fs.writeFileSync(pidFile, String(process.pid)); } catch {}
+}
+process.stderr.write('fake-browser-hang stderr: alive but CDP never starts\n');
+setInterval(() => {}, 60000);