@sanqianx/project-knowledge 5.0.19 → 5.0.20-rc.1

package/_site/_test/claude-session-lifecycle-sweep-test.js

@@ -1,252 +1,252 @@
-// Run: node _site/_test/claude-session-lifecycle-sweep-test.js
-//
-// Regression test for the stale-active-session sweep in claude-cli-runner.
-//
-// Without the sweeper, three failure modes leave sessions stuck in
-// state=running forever after the subprocess is gone:
-//   1. dashboard restart kills the SDK parent query; claude.exe becomes
-//      orphaned; on reload the persisted record still says "running"
-//   2. SIGKILL of the dashboard before the SDK for-await loop emits its
-//      terminal message
-//   3. child Claude.exe dies under IPC drop; in-memory session has
-//      subprocess=null while state=running
-//
-// Symptom in production: a project keeps showing the pulsing "running"
-// badge and the embedded terminal view stays empty because no live
-// subprocess streams into it. Until the sweeper ships, the only manual
-// workaround is a dashboard restart that the user has to remember.
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-const TMP_DATA = fs.mkdtempSync(path.join(os.tmpdir(), `kb-sweep-test-${process.pid}-`));
-process.env.KB_DATA_DIR = TMP_DATA;
-process.env.KB_STALE_ACTIVE_MS = '60000';
-require(path.resolve(__dirname, '..', '..', '_site', 'lib', 'data-dir'))._resetCache();
-
-// Seed the v2 registry and per-project config/state before loading the runner.
-const PROJECT_IDS = ['demo-zombie-persisted', 'demo-zombie-memory', 'demo-fresh', 'demo-broadcast', 'demo-callback'];
-const { defaultProjectConfig, defaultProjectState } = require('../lib/project-store');
-const now = new Date().toISOString();
-fs.mkdirSync(path.join(TMP_DATA, 'projects'), { recursive: true });
-for (const projectId of PROJECT_IDS) {
-  const knowledgePath = path.join(TMP_DATA, 'knowledge', projectId);
-  const metadataPath = path.join(TMP_DATA, 'projects', projectId);
-  fs.mkdirSync(knowledgePath, { recursive: true });
-  fs.mkdirSync(metadataPath, { recursive: true });
-  fs.writeFileSync(path.join(metadataPath, 'config.json'), JSON.stringify(defaultProjectConfig(projectId, {
-    displayName: projectId, storageName: projectId, repoPath: TMP_DATA, knowledgePath,
-  }), null, 2) + '\n', 'utf8');
-  fs.writeFileSync(path.join(metadataPath, 'state.json'), JSON.stringify(defaultProjectState(), null, 2) + '\n', 'utf8');
-}
-fs.writeFileSync(path.join(TMP_DATA, 'projects.json'), JSON.stringify({
-  schema: 'project-registry/v2', schemaVersion: 2, projectOrder: PROJECT_IDS,
-  projects: Object.fromEntries(PROJECT_IDS.map(projectId => [projectId, { createdAt: now, displayNameSnapshot: projectId }])),
-  revision: 1, updatedAt: now,
-}, null, 2) + '\n', 'utf8');
-fs.writeFileSync(path.join(TMP_DATA, 'claude-prompts.json'), '{"schema":"prompts/v1","prompts":{}}', 'utf-8');
-
-const runner = require('../lib/claude-cli-runner');
-const {
-  createSession,
-  demoteStaleActiveSessions,
-  ACTIVE_STATES,
-  TERMINAL_STATES,
-  listSessions,
-  subscribeList,
-} = runner;
-
-function assert(cond, msg) { if (!cond) throw new Error('ASSERT: ' + msg); }
-
-function writePersistedRecord(projectSlug, record) {
-  const aiDir = path.join(TMP_DATA, 'runtime', 'claude-sessions', projectSlug);
-  fs.mkdirSync(aiDir, { recursive: true });
-  const target = path.join(aiDir, `${record.sessionId}.json`);
-  // Default updatedAt to the same stale time used for startedAt so the
-  // sweeper treats the record as orphan-aged. Callers can override either.
-  const longAgo = record.startedAt || new Date(Date.now() - 10 * 60 * 1000).toISOString();
-  fs.writeFileSync(target, JSON.stringify({
-    schema: 'claude-workbench-session/v1',
-    updatedAt: record.updatedAt || longAgo,
-    ...record,
-  }, null, 2) + '\n', 'utf-8');
-  return target;
-}
-
-function makeStalePersistedRecord(projectSlug, sessionId, state) {
-  const longAgo = new Date(Date.now() - 10 * 60 * 1000).toISOString();
-  return writePersistedRecord(projectSlug, {
-    sessionId,
-    projectSlug,
-    projectPath: 'D:/proj/' + projectSlug,
-    kbPath: path.join(TMP_DATA, 'knowledge', projectSlug),
-    promptKey: 'post-commit-automation',
-    runner: 'sdk',
-    state,
-    startedAt: longAgo,
-    endedAt: null,
-    exitCode: null,
-    turns: 1,
-    error: null,
-    pendingPermission: null,
-    source: 'git-hook',
-    automation: true,
-    automationRunId: 'auto-test-1',
-    metadata: { source: 'git-hook', automation: true, automationRunId: 'auto-test-1' },
-    permissionMode: 'bypassPermissions',
-    events: [{ type: 'claude/system-prompt', text: 'fake', promptKey: 'post-commit-automation' }],
-  });
-}
-
-(() => {
-  // The sweeper itself is the unit under test.
-  assert(typeof demoteStaleActiveSessions === 'function',
-    'demoteStaleActiveSessions must be exported');
-  assert(ACTIVE_STATES.has('running'),
-    'ACTIVE_STATES must include running');
-  assert(TERMINAL_STATES.has('failed'),
-    'TERMINAL_STATES must include failed');
-
-  // (1) Persisted record that's been "running" for 10 minutes with no live
-  // subprocess — must be demoted. The user's exact scenario: dashboard
-  // restart orphaned the SDK parent query and the record on disk still
-  // says running.
-  {
-    const sessionId = 'sess-zombie-persisted-' + Date.now();
-    makeStalePersistedRecord('demo-zombie-persisted', sessionId, 'running');
-
-    const demoted = demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
-    const hit = demoted.find(d => d.sessionId === sessionId);
-    assert(hit, 'sweeper should have demoted the persisted zombie');
-    assert(hit.source === 'persisted', `expected source=persisted, got ${hit.source}`);
-
-    // The rehydrated session in memory should now show failed + endedAt.
-    const state = runner.getState(sessionId);
-    assert(state.state === 'failed',
-      `expected state=failed after sweep, got ${state.state}`);
-    assert(state.endedAt, 'endedAt should be set after demotion');
-    assert(state.error && /subprocess lost/i.test(state.error),
-      `error message should explain the orphan, got ${state.error}`);
-
-    // Subsequent sweeps should be idempotent — already-failed sessions are
-    // not in ACTIVE_STATES so they don't get touched again.
-    const secondSweep = demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
-    const hitAgain = secondSweep.find(d => d.sessionId === sessionId);
-    assert(!hitAgain,
-      `sweeper must not re-demote already-failed session (hit again: ${JSON.stringify(secondSweep)})`);
-  }
-
-  // (2) In-memory session with state=running AND subprocess=null AND a
-  // stale updatedAt — must be demoted. This is the runtime-orphan case:
-  // SDK query was kicked off, but the subprocess ref was cleared without
-  // a terminal setState (e.g. the dashboard process died between the
-  // subprocess=null assignment and the setState(failed) on the catch path).
-  {
-    const projectSlug = 'demo-zombie-memory';
-    const session = createSession({
-      projectSlug,
-      projectPath: 'D:/proj/' + projectSlug,
-      kbPath: path.join(TMP_DATA, 'knowledge', projectSlug),
-      promptKey: 'post-commit-automation',
-      source: 'git-hook',
-      metadata: { source: 'git-hook', automation: true, automationRunId: 'auto-mem' },
-    });
-    // Force it into the orphan shape: state=running, subprocess=null,
-    // updatedAt way in the past.
-    session.state = 'running';
-    session.subprocess = null;
-    session.updatedAt = new Date(Date.now() - 10 * 60 * 1000).toISOString();
-    session.startedAt = session.updatedAt;
-
-    const demoted = demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
-    const hit = demoted.find(d => d.sessionId === session.sessionId);
-    assert(hit, 'sweeper should have demoted the in-memory zombie');
-    assert(hit.source === 'memory', `expected source=memory, got ${hit.source}`);
-
-    const state = runner.getState(session.sessionId);
-    assert(state.state === 'failed',
-      `expected in-memory session to be failed, got ${state.state}`);
-    assert(state.error && /subprocess exited/i.test(state.error),
-      `expected subprocess-null error, got ${state.error}`);
-  }
-
-  // (3) Fresh session (started 5s ago) must NOT be demoted even if
-  // subprocess happens to be null. Threshold exists exactly to keep
-  // legitimately-thinking sessions from being killed prematurely.
-  {
-    const projectSlug = 'demo-fresh';
-    const session = createSession({
-      projectSlug,
-      projectPath: 'D:/proj/' + projectSlug,
-      kbPath: path.join(TMP_DATA, 'knowledge', projectSlug),
-      promptKey: 'post-commit-automation',
-      source: 'git-hook',
-      metadata: { source: 'git-hook', automation: true, automationRunId: 'auto-fresh' },
-    });
-    session.state = 'running';
-    session.subprocess = null;
-    // updatedAt defaults to createdAt via createSession, well under 60s old.
-
-    const demoted = demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
-    const hit = demoted.find(d => d.sessionId === session.sessionId);
-    assert(!hit,
-      `fresh session (age <60s) must NOT be demoted; demoted list = ${JSON.stringify(demoted)}`);
-
-    // Cleanup so it doesn't leak into the next test.
-    runner.deleteSession(session.sessionId);
-  }
-
-  // (4) Demotion must fire the global SSE broadcast so the UI sees the
-  // running→failed transition. Without this the blue light stays on even
-  // after the in-memory state is wrong.
-  {
-    const projectSlug = 'demo-broadcast';
-    const broadcastEvents = [];
-    subscribeList(ev => broadcastEvents.push(ev));
-
-    const sessionId = 'sess-broadcast-' + Date.now();
-    makeStalePersistedRecord(projectSlug, sessionId, 'running');
-
-    demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
-    const sawTransition = broadcastEvents.some(
-      ev => ev.sessionId === sessionId && ev.state === 'failed' && ev.kind === 'stale-active-sweep'
-    );
-    assert(sawTransition,
-      `expected SSE broadcast for ${sessionId} with state=failed kind=stale-active-sweep; got ${JSON.stringify(broadcastEvents)}`);
-  }
-
-  // (5) The onSessionEnded hook must fire for failed sessions, so the
-  // automation queue (post-commit-automation.js) can promote the next
-  // queued run. Without this, stranded sessions would also strand any
-  // queued successor forever.
-  {
-    const projectSlug = 'demo-callback';
-    const sessionId = 'sess-callback-' + Date.now();
-    makeStalePersistedRecord(projectSlug, sessionId, 'running');
-
-    let endedWithFailed = null;
-    const off = runner.onSessionEnded(s => {
-      if (s.sessionId === sessionId && s.state === 'failed') {
-        endedWithFailed = s;
-      }
-    });
-
-    demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
-    // onSessionEnded fires via setImmediate, so wait one tick.
-    return Promise.resolve()
-      .then(() => new Promise(resolve => setImmediate(resolve)))
-      .then(() => {
-        off();
-        assert(endedWithFailed,
-          `onSessionEnded should have fired for the demoted session`);
-        assert(endedWithFailed.sessionId === sessionId,
-          `wrong sessionId in callback: ${endedWithFailed && endedWithFailed.sessionId}`);
-      });
-  }
-})().then(() => {
-  console.log('claude-session-lifecycle-sweep-test PASS');
-}).catch(e => {
-  console.error(e.stack || e.message);
-  process.exit(1);
-});
+// Run: node _site/_test/claude-session-lifecycle-sweep-test.js
+//
+// Regression test for the stale-active-session sweep in claude-cli-runner.
+//
+// Without the sweeper, three failure modes leave sessions stuck in
+// state=running forever after the subprocess is gone:
+//   1. dashboard restart kills the SDK parent query; claude.exe becomes
+//      orphaned; on reload the persisted record still says "running"
+//   2. SIGKILL of the dashboard before the SDK for-await loop emits its
+//      terminal message
+//   3. child Claude.exe dies under IPC drop; in-memory session has
+//      subprocess=null while state=running
+//
+// Symptom in production: a project keeps showing the pulsing "running"
+// badge and the embedded terminal view stays empty because no live
+// subprocess streams into it. Until the sweeper ships, the only manual
+// workaround is a dashboard restart that the user has to remember.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const TMP_DATA = fs.mkdtempSync(path.join(os.tmpdir(), `kb-sweep-test-${process.pid}-`));
+process.env.KB_DATA_DIR = TMP_DATA;
+process.env.KB_STALE_ACTIVE_MS = '60000';
+require(path.resolve(__dirname, '..', '..', '_site', 'lib', 'data-dir'))._resetCache();
+
+// Seed the v2 registry and per-project config/state before loading the runner.
+const PROJECT_IDS = ['demo-zombie-persisted', 'demo-zombie-memory', 'demo-fresh', 'demo-broadcast', 'demo-callback'];
+const { defaultProjectConfig, defaultProjectState } = require('../lib/project-store');
+const now = new Date().toISOString();
+fs.mkdirSync(path.join(TMP_DATA, 'projects'), { recursive: true });
+for (const projectId of PROJECT_IDS) {
+  const knowledgePath = path.join(TMP_DATA, 'knowledge', projectId);
+  const metadataPath = path.join(TMP_DATA, 'projects', projectId);
+  fs.mkdirSync(knowledgePath, { recursive: true });
+  fs.mkdirSync(metadataPath, { recursive: true });
+  fs.writeFileSync(path.join(metadataPath, 'config.json'), JSON.stringify(defaultProjectConfig(projectId, {
+    displayName: projectId, storageName: projectId, repoPath: TMP_DATA, knowledgePath,
+  }), null, 2) + '\n', 'utf8');
+  fs.writeFileSync(path.join(metadataPath, 'state.json'), JSON.stringify(defaultProjectState(), null, 2) + '\n', 'utf8');
+}
+fs.writeFileSync(path.join(TMP_DATA, 'projects.json'), JSON.stringify({
+  schema: 'project-registry/v2', schemaVersion: 2, projectOrder: PROJECT_IDS,
+  projects: Object.fromEntries(PROJECT_IDS.map(projectId => [projectId, { createdAt: now, displayNameSnapshot: projectId }])),
+  revision: 1, updatedAt: now,
+}, null, 2) + '\n', 'utf8');
+fs.writeFileSync(path.join(TMP_DATA, 'claude-prompts.json'), '{"schema":"prompts/v1","prompts":{}}', 'utf-8');
+
+const runner = require('../lib/claude-cli-runner');
+const {
+  createSession,
+  demoteStaleActiveSessions,
+  ACTIVE_STATES,
+  TERMINAL_STATES,
+  listSessions,
+  subscribeList,
+} = runner;
+
+function assert(cond, msg) { if (!cond) throw new Error('ASSERT: ' + msg); }
+
+function writePersistedRecord(projectSlug, record) {
+  const aiDir = path.join(TMP_DATA, 'runtime', 'claude-sessions', projectSlug);
+  fs.mkdirSync(aiDir, { recursive: true });
+  const target = path.join(aiDir, `${record.sessionId}.json`);
+  // Default updatedAt to the same stale time used for startedAt so the
+  // sweeper treats the record as orphan-aged. Callers can override either.
+  const longAgo = record.startedAt || new Date(Date.now() - 10 * 60 * 1000).toISOString();
+  fs.writeFileSync(target, JSON.stringify({
+    schema: 'claude-workbench-session/v1',
+    updatedAt: record.updatedAt || longAgo,
+    ...record,
+  }, null, 2) + '\n', 'utf-8');
+  return target;
+}
+
+function makeStalePersistedRecord(projectSlug, sessionId, state) {
+  const longAgo = new Date(Date.now() - 10 * 60 * 1000).toISOString();
+  return writePersistedRecord(projectSlug, {
+    sessionId,
+    projectSlug,
+    projectPath: 'D:/proj/' + projectSlug,
+    kbPath: path.join(TMP_DATA, 'knowledge', projectSlug),
+    promptKey: 'post-commit-automation',
+    runner: 'sdk',
+    state,
+    startedAt: longAgo,
+    endedAt: null,
+    exitCode: null,
+    turns: 1,
+    error: null,
+    pendingPermission: null,
+    source: 'git-hook',
+    automation: true,
+    automationRunId: 'auto-test-1',
+    metadata: { source: 'git-hook', automation: true, automationRunId: 'auto-test-1' },
+    permissionMode: 'bypassPermissions',
+    events: [{ type: 'claude/system-prompt', text: 'fake', promptKey: 'post-commit-automation' }],
+  });
+}
+
+(() => {
+  // The sweeper itself is the unit under test.
+  assert(typeof demoteStaleActiveSessions === 'function',
+    'demoteStaleActiveSessions must be exported');
+  assert(ACTIVE_STATES.has('running'),
+    'ACTIVE_STATES must include running');
+  assert(TERMINAL_STATES.has('failed'),
+    'TERMINAL_STATES must include failed');
+
+  // (1) Persisted record that's been "running" for 10 minutes with no live
+  // subprocess — must be demoted. The user's exact scenario: dashboard
+  // restart orphaned the SDK parent query and the record on disk still
+  // says running.
+  {
+    const sessionId = 'sess-zombie-persisted-' + Date.now();
+    makeStalePersistedRecord('demo-zombie-persisted', sessionId, 'running');
+
+    const demoted = demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
+    const hit = demoted.find(d => d.sessionId === sessionId);
+    assert(hit, 'sweeper should have demoted the persisted zombie');
+    assert(hit.source === 'persisted', `expected source=persisted, got ${hit.source}`);
+
+    // The rehydrated session in memory should now show failed + endedAt.
+    const state = runner.getState(sessionId);
+    assert(state.state === 'failed',
+      `expected state=failed after sweep, got ${state.state}`);
+    assert(state.endedAt, 'endedAt should be set after demotion');
+    assert(state.error && /subprocess lost/i.test(state.error),
+      `error message should explain the orphan, got ${state.error}`);
+
+    // Subsequent sweeps should be idempotent — already-failed sessions are
+    // not in ACTIVE_STATES so they don't get touched again.
+    const secondSweep = demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
+    const hitAgain = secondSweep.find(d => d.sessionId === sessionId);
+    assert(!hitAgain,
+      `sweeper must not re-demote already-failed session (hit again: ${JSON.stringify(secondSweep)})`);
+  }
+
+  // (2) In-memory session with state=running AND subprocess=null AND a
+  // stale updatedAt — must be demoted. This is the runtime-orphan case:
+  // SDK query was kicked off, but the subprocess ref was cleared without
+  // a terminal setState (e.g. the dashboard process died between the
+  // subprocess=null assignment and the setState(failed) on the catch path).
+  {
+    const projectSlug = 'demo-zombie-memory';
+    const session = createSession({
+      projectSlug,
+      projectPath: 'D:/proj/' + projectSlug,
+      kbPath: path.join(TMP_DATA, 'knowledge', projectSlug),
+      promptKey: 'post-commit-automation',
+      source: 'git-hook',
+      metadata: { source: 'git-hook', automation: true, automationRunId: 'auto-mem' },
+    });
+    // Force it into the orphan shape: state=running, subprocess=null,
+    // updatedAt way in the past.
+    session.state = 'running';
+    session.subprocess = null;
+    session.updatedAt = new Date(Date.now() - 10 * 60 * 1000).toISOString();
+    session.startedAt = session.updatedAt;
+
+    const demoted = demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
+    const hit = demoted.find(d => d.sessionId === session.sessionId);
+    assert(hit, 'sweeper should have demoted the in-memory zombie');
+    assert(hit.source === 'memory', `expected source=memory, got ${hit.source}`);
+
+    const state = runner.getState(session.sessionId);
+    assert(state.state === 'failed',
+      `expected in-memory session to be failed, got ${state.state}`);
+    assert(state.error && /subprocess exited/i.test(state.error),
+      `expected subprocess-null error, got ${state.error}`);
+  }
+
+  // (3) Fresh session (started 5s ago) must NOT be demoted even if
+  // subprocess happens to be null. Threshold exists exactly to keep
+  // legitimately-thinking sessions from being killed prematurely.
+  {
+    const projectSlug = 'demo-fresh';
+    const session = createSession({
+      projectSlug,
+      projectPath: 'D:/proj/' + projectSlug,
+      kbPath: path.join(TMP_DATA, 'knowledge', projectSlug),
+      promptKey: 'post-commit-automation',
+      source: 'git-hook',
+      metadata: { source: 'git-hook', automation: true, automationRunId: 'auto-fresh' },
+    });
+    session.state = 'running';
+    session.subprocess = null;
+    // updatedAt defaults to createdAt via createSession, well under 60s old.
+
+    const demoted = demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
+    const hit = demoted.find(d => d.sessionId === session.sessionId);
+    assert(!hit,
+      `fresh session (age <60s) must NOT be demoted; demoted list = ${JSON.stringify(demoted)}`);
+
+    // Cleanup so it doesn't leak into the next test.
+    runner.deleteSession(session.sessionId);
+  }
+
+  // (4) Demotion must fire the global SSE broadcast so the UI sees the
+  // running→failed transition. Without this the blue light stays on even
+  // after the in-memory state is wrong.
+  {
+    const projectSlug = 'demo-broadcast';
+    const broadcastEvents = [];
+    subscribeList(ev => broadcastEvents.push(ev));
+
+    const sessionId = 'sess-broadcast-' + Date.now();
+    makeStalePersistedRecord(projectSlug, sessionId, 'running');
+
+    demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
+    const sawTransition = broadcastEvents.some(
+      ev => ev.sessionId === sessionId && ev.state === 'failed' && ev.kind === 'stale-active-sweep'
+    );
+    assert(sawTransition,
+      `expected SSE broadcast for ${sessionId} with state=failed kind=stale-active-sweep; got ${JSON.stringify(broadcastEvents)}`);
+  }
+
+  // (5) The onSessionEnded hook must fire for failed sessions, so the
+  // automation queue (post-commit-automation.js) can promote the next
+  // queued run. Without this, stranded sessions would also strand any
+  // queued successor forever.
+  {
+    const projectSlug = 'demo-callback';
+    const sessionId = 'sess-callback-' + Date.now();
+    makeStalePersistedRecord(projectSlug, sessionId, 'running');
+
+    let endedWithFailed = null;
+    const off = runner.onSessionEnded(s => {
+      if (s.sessionId === sessionId && s.state === 'failed') {
+        endedWithFailed = s;
+      }
+    });
+
+    demoteStaleActiveSessions({ thresholdMs: 60 * 1000 });
+    // onSessionEnded fires via setImmediate, so wait one tick.
+    return Promise.resolve()
+      .then(() => new Promise(resolve => setImmediate(resolve)))
+      .then(() => {
+        off();
+        assert(endedWithFailed,
+          `onSessionEnded should have fired for the demoted session`);
+        assert(endedWithFailed.sessionId === sessionId,
+          `wrong sessionId in callback: ${endedWithFailed && endedWithFailed.sessionId}`);
+      });
+  }
+})().then(() => {
+  console.log('claude-session-lifecycle-sweep-test PASS');
+}).catch(e => {
+  console.error(e.stack || e.message);
+  process.exit(1);
+});

package/_site/_test/cli-instance-management-test.js

@@ -1,62 +1,62 @@
-'use strict';
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const path = require('node:path');
-const os = require('node:os');
-const http = require('node:http');
-const { spawn } = require('node:child_process');
-const endpoint = require('../lib/runtime-endpoint');
-const control = require('../lib/runtime-control');
-const packageRoot = process.env.KB_CLI_TEST_PACKAGE || path.resolve(__dirname, '../..');
-const bin = path.join(packageRoot, 'bin/project-knowledge.js');
-const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-instance-management-'));
-const a = path.join(root, '知识库 A'), b = path.join(root, '知识库 B');
-const temp = path.join(root, 'isolated-temp'); fs.mkdirSync(temp);
-const env = { ...process.env, KB_DATA_DIR: a, TEMP: temp, TMP: temp, KB_MODULES_AUTOSTART: '0', AI_CODING_EVENT_BRIDGE_HOME: path.join(root, 'bridge') };
-const pids = [];
-function run(args) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [bin, ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
-    let stdout = '', stderr = '';
-    const timer = setTimeout(() => { child.kill(); reject(new Error(`CLI timeout: ${stdout} ${stderr}`)); }, 25000);
-    child.stdout.on('data', c => { stdout += c; }); child.stderr.on('data', c => { stderr += c; });
-    child.once('error', reject); child.once('exit', code => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
-  });
-}
-async function usable(port) { try { return (await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(700) })).ok; } catch { return false; } }
-let foreign;
-(async () => {
-  foreign = http.createServer((req, res) => { res.writeHead(404); res.end('not knowledge'); });
-  await new Promise(resolve => foreign.listen(0, '127.0.0.1', resolve));
-  const foreignPort = foreign.address().port;
-  fs.writeFileSync(path.join(temp, '.project-knowledge.pid'), `${process.pid}\n${foreignPort}`);
-  for (const args of [['stoop'], ['STOP', 'unexpected'], ['stop', '--port', '12junk'], ['stop', '--port', '65536'], ['stop', '--port'], ['stop', '--all']]) {
-    const result = await run(args); assert.equal(result.code, 1, JSON.stringify(result));
-    assert(!/Already running|starting in background/.test(result.stdout));
-  }
-  assert.equal(fs.existsSync(a), false, 'invalid commands must not create data or services');
-  const noInstance = await run(['STOP']); assert.equal(noInstance.code, 0); assert.match(noInstance.stdout, /No background/);
-  assert.equal(await usable(foreignPort), false); assert(foreign.listening, 'shared legacy PID must not kill an unrelated process');
-  const launchedA = await run(['START', '--no-open']); assert.equal(launchedA.code, 0, launchedA.stderr);
-  const infoA = endpoint.readEndpoint(a); pids.push(infoA.pid); assert(await usable(infoA.port));
-  const launchedB = await run(['start', '--data', b, '--no-open']); assert.equal(launchedB.code, 0, launchedB.stderr);
-  const infoB = endpoint.readEndpoint(b); pids.push(infoB.pid); assert(await usable(infoB.port)); assert.notEqual(infoA.port, infoB.port);
-  const status = await run(['STATUS']); assert.equal(status.code, 0); assert.match(status.stdout, new RegExp(`PID ${infoA.pid}`));
-  const inventory = await run(['STATUS', '--all']); assert.equal(inventory.code, 0, inventory.stderr);
-  assert.match(inventory.stdout, new RegExp(`PID ${infoA.pid}`)); assert.match(inventory.stdout, new RegExp(`PID ${infoB.pid}`));
-  const wrongPort = await run(['STOP', '--port', String(foreignPort)]); assert.equal(wrongPort.code, 1); assert(foreign.listening);
-  const conflict = await run(['stop', '--data', a, '--port', String(infoB.port)]); assert.equal(conflict.code, 1); assert(await usable(infoB.port));
-  await assert.rejects(() => control.request(a, { action: 'stop', pid: infoA.pid + 1, port: infoA.port, startedAt: infoA.startedAt }), /身份/);
-  assert(await usable(infoA.port));
-  const stoppedA = await run(['STOP']); assert.equal(stoppedA.code, 0, stoppedA.stderr); assert.match(stoppedA.stdout, new RegExp(`:${infoA.port}`));
-  assert.equal(await usable(infoA.port), false); assert(await usable(infoB.port), 'default stop must preserve a different data directory');
-  const stoppedB = await run(['stop', '--port', String(infoB.port)]); assert.equal(stoppedB.code, 0, stoppedB.stderr); assert.equal(await usable(infoB.port), false);
-  assert.equal((await run(['stop'])).code, 0, 'repeated stop is harmless');
-  fs.writeFileSync(path.join(a, 'runtime-endpoint.json'), JSON.stringify({ schema: endpoint.SCHEMA, pid: process.pid, host: '127.0.0.1', port: foreignPort }));
-  const stale = await run(['STOP']); assert.equal(stale.code, 1); assert.match(stale.stderr, /控制通道不可用/); assert(foreign.listening, 'a live but unrelated recorded PID is never signaled');
-  const refused = await run(['start', '--no-open']); assert.equal(refused.code, 1); assert(foreign.listening);
-  console.log('CLI instance management PASS: case, strict arguments, inventory, two directories, targeted stop, spoof protection, stale/shared PID safety');
-})().catch(error => { console.error(error); process.exitCode = 1; }).finally(async () => {
-  foreign?.closeAllConnections(); if (foreign?.listening) await new Promise(resolve => foreign.close(resolve));
-  for (const data of [a, b]) try { const info = await control.request(data, { action: 'status' }, 500); await control.request(data, { action: 'stop', pid: info.instance.pid, port: info.instance.port, startedAt: info.instance.startedAt }); } catch {}
-});
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const http = require('node:http');
+const { spawn } = require('node:child_process');
+const endpoint = require('../lib/runtime-endpoint');
+const control = require('../lib/runtime-control');
+const packageRoot = process.env.KB_CLI_TEST_PACKAGE || path.resolve(__dirname, '../..');
+const bin = path.join(packageRoot, 'bin/project-knowledge.js');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-instance-management-'));
+const a = path.join(root, '知识库 A'), b = path.join(root, '知识库 B');
+const temp = path.join(root, 'isolated-temp'); fs.mkdirSync(temp);
+const env = { ...process.env, KB_DATA_DIR: a, TEMP: temp, TMP: temp, KB_MODULES_AUTOSTART: '0', AI_CODING_EVENT_BRIDGE_HOME: path.join(root, 'bridge') };
+const pids = [];
+function run(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [bin, ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '', stderr = '';
+    const timer = setTimeout(() => { child.kill(); reject(new Error(`CLI timeout: ${stdout} ${stderr}`)); }, 25000);
+    child.stdout.on('data', c => { stdout += c; }); child.stderr.on('data', c => { stderr += c; });
+    child.once('error', reject); child.once('exit', code => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+  });
+}
+async function usable(port) { try { return (await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(700) })).ok; } catch { return false; } }
+let foreign;
+(async () => {
+  foreign = http.createServer((req, res) => { res.writeHead(404); res.end('not knowledge'); });
+  await new Promise(resolve => foreign.listen(0, '127.0.0.1', resolve));
+  const foreignPort = foreign.address().port;
+  fs.writeFileSync(path.join(temp, '.project-knowledge.pid'), `${process.pid}\n${foreignPort}`);
+  for (const args of [['stoop'], ['STOP', 'unexpected'], ['stop', '--port', '12junk'], ['stop', '--port', '65536'], ['stop', '--port'], ['stop', '--all']]) {
+    const result = await run(args); assert.equal(result.code, 1, JSON.stringify(result));
+    assert(!/Already running|starting in background/.test(result.stdout));
+  }
+  assert.equal(fs.existsSync(a), false, 'invalid commands must not create data or services');
+  const noInstance = await run(['STOP']); assert.equal(noInstance.code, 0); assert.match(noInstance.stdout, /No background/);
+  assert.equal(await usable(foreignPort), false); assert(foreign.listening, 'shared legacy PID must not kill an unrelated process');
+  const launchedA = await run(['START', '--no-open']); assert.equal(launchedA.code, 0, launchedA.stderr);
+  const infoA = endpoint.readEndpoint(a); pids.push(infoA.pid); assert(await usable(infoA.port));
+  const launchedB = await run(['start', '--data', b, '--no-open']); assert.equal(launchedB.code, 0, launchedB.stderr);
+  const infoB = endpoint.readEndpoint(b); pids.push(infoB.pid); assert(await usable(infoB.port)); assert.notEqual(infoA.port, infoB.port);
+  const status = await run(['STATUS']); assert.equal(status.code, 0); assert.match(status.stdout, new RegExp(`PID ${infoA.pid}`));
+  const inventory = await run(['STATUS', '--all']); assert.equal(inventory.code, 0, inventory.stderr);
+  assert.match(inventory.stdout, new RegExp(`PID ${infoA.pid}`)); assert.match(inventory.stdout, new RegExp(`PID ${infoB.pid}`));
+  const wrongPort = await run(['STOP', '--port', String(foreignPort)]); assert.equal(wrongPort.code, 1); assert(foreign.listening);
+  const conflict = await run(['stop', '--data', a, '--port', String(infoB.port)]); assert.equal(conflict.code, 1); assert(await usable(infoB.port));
+  await assert.rejects(() => control.request(a, { action: 'stop', pid: infoA.pid + 1, port: infoA.port, startedAt: infoA.startedAt }), /身份/);
+  assert(await usable(infoA.port));
+  const stoppedA = await run(['STOP']); assert.equal(stoppedA.code, 0, stoppedA.stderr); assert.match(stoppedA.stdout, new RegExp(`:${infoA.port}`));
+  assert.equal(await usable(infoA.port), false); assert(await usable(infoB.port), 'default stop must preserve a different data directory');
+  const stoppedB = await run(['stop', '--port', String(infoB.port)]); assert.equal(stoppedB.code, 0, stoppedB.stderr); assert.equal(await usable(infoB.port), false);
+  assert.equal((await run(['stop'])).code, 0, 'repeated stop is harmless');
+  fs.writeFileSync(path.join(a, 'runtime-endpoint.json'), JSON.stringify({ schema: endpoint.SCHEMA, pid: process.pid, host: '127.0.0.1', port: foreignPort }));
+  const stale = await run(['STOP']); assert.equal(stale.code, 1); assert.match(stale.stderr, /控制通道不可用/); assert(foreign.listening, 'a live but unrelated recorded PID is never signaled');
+  const refused = await run(['start', '--no-open']); assert.equal(refused.code, 1); assert(foreign.listening);
+  console.log('CLI instance management PASS: case, strict arguments, inventory, two directories, targeted stop, spoof protection, stale/shared PID safety');
+})().catch(error => { console.error(error); process.exitCode = 1; }).finally(async () => {
+  foreign?.closeAllConnections(); if (foreign?.listening) await new Promise(resolve => foreign.close(resolve));
+  for (const data of [a, b]) try { const info = await control.request(data, { action: 'status' }, 500); await control.request(data, { action: 'stop', pid: info.instance.pid, port: info.instance.port, startedAt: info.instance.startedAt }); } catch {}
+});