@sanqianx/project-knowledge 5.0.24 → 5.0.26

package/_site/_test/parallel-logging-fix-r2-gap-test.js

@@ -0,0 +1,294 @@
+'use strict';
+// P-LOG-SAFETY-R2 deterministic LOG-004 boundary (snapshot→subscription
+// handoff) acceptance — lane-exclusive prefix parallel-logging-fix-r2-*.
+//
+// The real UI protocol (ui/product.js loadLogs): close old stream → GET
+// snapshot → render → subscribe /api/logs/stream with the SNAPSHOT's
+// streamCursor. The deterministic window is therefore exactly "server has
+// produced the snapshot, browser has not received it yet": during that
+// window the log subscription does not exist yet.
+//
+// This driver proves the handoff has no gap and no duplicate, without any
+// sleep-based guess:
+//   1. The r2 observation proxy holds the REAL snapshot response after the
+//      server produced it (original bytes, sha256-recorded).
+//   2. While held: wire evidence shows NO logs/stream subscription yet
+//      (proxy frame timeline + real page KnowledgeLive.stats), and a REAL
+//      product write (PUT /api/projects/<id>/goal) lands a unique record on
+//      disk with id/ts AFTER the snapshot cursor.
+//   3. The original snapshot bytes are released untouched; the page then
+//      subscribes carrying exactly the snapshot cursor; the server's
+//      streamLogsWithoutGap replays the gap record (replay:true).
+//   4. The unique record appears in DOM / API / disk exactly once each.
+//   5. Steady-state control afterwards: a second write arrives live once.
+//
+// The driver never writes fake log entries, never rewrites response records,
+// and never simulates the product's own subscription.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// Portable isolation (P-QA-LOG-INTEGRATION-5025): the temp root comes from
+// PK_TEST_TEMP_ROOT or os.tmpdir() and must live outside the source tree;
+// HOME/APPDATA/LOCALAPPDATA/TEMP/CODEX_HOME/CLAUDE_CONFIG_DIR and the dual
+// product data roots are redirected before any other module is loaded.
+const { installLoggingTestEnv, resolveEvidenceDir } = require('./helpers/parallel-logging-integration-5025-env');
+const lane = installLoggingTestEnv({ caseId: 'LOGFIXR2-GAP', prefix: 'logfixr2-gap' });
+const laneTmp = lane.laneTmp;
+
+const { spawnServer } = require('./helpers/spawn-server');
+const { findChrome } = require('./helpers/find-chrome');
+const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
+const freePort = require('./helpers/free-port');
+const { createLoggingAcceptanceFixture, writeProjectLogs } = require('./helpers/parallel-logging-acceptance-fixture');
+const { createGapProxy, decodeStreamCursor } = require('./helpers/parallel-logging-fix-r2-proxy');
+
+const ROOT = path.resolve(__dirname, '../..');
+const ARTIFACTS = resolveEvidenceDir(path.resolve(ROOT, 'qa-autopilot/artifacts/parallel-20261023/logging-fix-r2/evidence/gap'));
+
+const PROJECT_A = 'project-logfixr2-gap';
+const run = crypto.randomBytes(6).toString('hex');
+const GAP_BYTES = 1733;       // unique goal content length for the boundary write
+const STEADY_BYTES = 1777;    // unique length for the steady-state control write
+// Below the run-all per-test budget (PK_TEST_TIMEOUT_MS, default 90s) so a
+// stall still lets this entry write its own evidence before the runner kills
+// the child.
+const HARD_TIMEOUT_MS = 80000;
+
+const now = () => new Date().toISOString();
+
+function projectDayRecords(dataDir, projectId) {
+  const dir = path.join(dataDir, 'logs', 'projects', projectId);
+  const records = [];
+  if (!fs.existsSync(dir)) return records;
+  for (const file of fs.readdirSync(dir).filter(name => name.endsWith('.jsonl')).sort()) {
+    for (const line of fs.readFileSync(path.join(dir, file), 'utf8').split('\n')) {
+      if (line.trim()) { try { records.push(JSON.parse(line)); } catch {} }
+    }
+  }
+  return records;
+}
+
+const padTo = (marker, total) => marker + ' ' + 'x'.repeat(Math.max(0, total - marker.length - 1));
+
+async function main() {
+  fs.mkdirSync(ARTIFACTS, { recursive: true });
+  const evidence = { caseId: 'LOG-004 (R2 deterministic boundary)', run, startedAt: now(), phases: {} };
+
+  const seedMarkers = [`LOGFIXR2-GAP-SEED1-${run}`, `LOGFIXR2-GAP-SEED2-${run}`];
+  const fixture = await createLoggingAcceptanceFixture({
+    caseId: 'logfixr2gap',
+    projects: [{ projectId: PROJECT_A, displayName: 'LOGFIXR2交界项目' }],
+  });
+  await writeProjectLogs(fixture.logger, PROJECT_A, [
+    { level: 'info', event: 'logfixr2.gap.seed1', message: seedMarkers[0], operationId: `op-logfixr2-seed1-${run}`, component: 'logfixr2-gap' },
+    { level: 'warn', event: 'logfixr2.gap.seed2', message: seedMarkers[1], operationId: `op-logfixr2-seed2-${run}`, component: 'logfixr2-gap' },
+  ]);
+  await fixture.logger.close();
+
+  const port = await freePort();
+  const proxyPort = await freePort();
+  const serverBase = `http://127.0.0.1:${port}`;
+  const server = spawnServer({ root: ROOT, port, dataDir: fixture.dataDir, tag: 'logfixr2gap', stdio: 'ignore' });
+  let browser;
+  const proxy = await createGapProxy({ targetPort: port, port: proxyPort });
+  try {
+    await waitFor(async () => { try { return (await fetch(`${serverBase}/api/health`)).ok; } catch { return false; } }, 'isolated server healthy', 30000);
+    evidence.server = { pid: server.child.pid, port, proxyPort, dataDir: fixture.dataDir };
+
+    browser = await launchCdpBrowser({ chrome: findChrome(), profileDir: path.join(laneTmp, 'browser'), url: proxy.url, width: 1440, height: 900 });
+    const runExpr = expression => browser.evaluate(expression);
+    const click = selector => runExpr(`document.querySelector(${JSON.stringify(selector)}).click()`);
+    evidence.browser = await runExpr('navigator.userAgent');
+    await waitFor(async () => runExpr(`document.getElementById('projectSelect') && document.getElementById('projectSelect').length >= 1`), 'project registered', 20000);
+    await runExpr(`document.getElementById('projectSelect').value = ${JSON.stringify(PROJECT_A)}; document.getElementById('projectSelect').dispatchEvent(new Event('change'))`);
+    await waitFor(async () => runExpr(`document.getElementById('projectSelect').value === ${JSON.stringify(PROJECT_A)}`), 'project A selected');
+
+    // Baseline: page live subscriptions before the diagnostics dialog exists.
+    const statsBaseline = JSON.parse(await runExpr(`JSON.stringify(window.KnowledgeLive ? window.KnowledgeLive.stats() : null)`));
+    evidence.phases.statsBaseline = statsBaseline;
+
+    // Arm the barrier, then open the diagnostics dialog (real user path).
+    proxy.armSnapshotBarrier();
+    await click('#openSystem');
+    await click('#openLogs');
+    const barrier = await proxy.waitBarrier(10000);
+    evidence.phases.barrier = {
+      heldAt: barrier.heldAt,
+      status: barrier.status,
+      entries: barrier.entries,
+      newestEntryId: barrier.newestEntryId,
+      streamCursor: barrier.streamCursor,
+      cursorDecoded: decodeStreamCursor(barrier.streamCursor),
+      responseSha256: barrier.sha256,
+      byteLength: barrier.byteLength,
+    };
+    const snapshotCursorDecoded = evidence.phases.barrier.cursorDecoded;
+
+    // While the snapshot is held: the page has NOT yet subscribed to the log
+    // stream (wire truth + page truth), and a real product write lands a
+    // unique record after the snapshot cursor.
+    const statsWhileHeld = JSON.parse(await runExpr(`JSON.stringify(window.KnowledgeLive ? window.KnowledgeLive.stats() : null)`));
+    const wsBeforeRelease = proxy.events.filter(e => e.kind === 'ws-frame' && e.type === 'subscribe');
+    const logsSubscribeBeforeRelease = wsBeforeRelease.filter(e => (e.route || '').includes('/api/logs/stream'));
+    evidence.phases.whileHeld = {
+      statsWhileHeld,
+      wsSubscribeFramesBeforeRelease: wsBeforeRelease.map(e => ({ seq: e.seq, route: e.route })),
+      logsStreamSubscriptionEstablished: logsSubscribeBeforeRelease.length > 0,
+    };
+
+    const goalRes = await fetch(`${proxy.url}/api/projects/${PROJECT_A}/goal`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ content: padTo(`LOGFIXR2-GAP-BOUNDARY-${run}`, GAP_BYTES) }),
+    });
+    evidence.phases.boundaryWrite = { at: now(), status: goalRes.status, contentBytes: GAP_BYTES };
+
+    proxy.releaseBarrier();
+    evidence.phases.releaseAt = now();
+
+    // Wait for the page's own handoff: snapshot rendered, then subscription
+    // established with the snapshot cursor, then the gap record replayed.
+    await waitFor(async () => runExpr(`document.getElementById('logsDialog').open === true && document.querySelectorAll('#logsContent .log-entry').length >= 3`), 'snapshot rendered after release', 15000);
+
+    const domState = () => runExpr(`JSON.stringify((() => {
+      const details = [...document.querySelectorAll('#logsContent .log-entry .log-detail')];
+      const records = details.map(node => { try { return JSON.parse(node.textContent); } catch { return null; } }).filter(Boolean);
+      const ids = records.map(r => r.id);
+      return {
+        count: document.querySelectorAll('#logsContent .log-entry').length,
+        uniqueIds: new Set(ids).size === ids.length,
+        boundaryRecords: records.filter(r => r.event === 'goal.updated' && r.context && r.context.bytes === ${GAP_BYTES}).map(r => ({ id: r.id, ts: r.ts })),
+        steadyRecords: records.filter(r => r.event === 'goal.updated' && r.context && r.context.bytes === ${STEADY_BYTES}).map(r => ({ id: r.id, ts: r.ts })),
+        domCursor: document.getElementById('logsDialog').dataset.streamCursor || '',
+      };
+    })())`).then(value => (typeof value === 'string' ? JSON.parse(value) : value));
+    const afterHandoff = await waitFor(async () => {
+      const state = await domState();
+      return state.boundaryRecords.length === 1 ? state : null;
+    }, 'boundary record visible exactly once in DOM', 20000);
+    evidence.phases.domAfterHandoff = afterHandoff;
+
+    // Wire timeline: exactly one logs/stream subscription, AFTER release,
+    // carrying exactly the snapshot cursor; the boundary record delivered by
+    // the gateway exactly once (capture its replay flag); logs/ready seen.
+    const subscribeFrames = proxy.events.filter(e => e.kind === 'ws-frame' && e.type === 'subscribe' && (e.route || '').includes('/api/logs/stream'));
+    const releaseSeq = proxy.events.find(e => e.kind === 'barrier-released')?.seq;
+    evidence.phases.handoffWire = {
+      releaseSeq,
+      subscribeFrames: subscribeFrames.map(e => ({ seq: e.seq, at: e.at, route: e.route })),
+      subscribeCursor: (() => {
+        const route = subscribeFrames[0]?.route || '';
+        const match = /[?&]streamCursor=([^&]+)/.exec(route);
+        return match ? { raw: decodeURIComponent(match[1]), decoded: decodeStreamCursor(decodeURIComponent(match[1])) } : null;
+      })(),
+      boundaryFrames: proxy.events.filter(e => e.kind === 'ws-frame' && e.type === 'event' && e.event === 'logs/appended' && (e.dataSnippet || '').includes(`"bytes":${GAP_BYTES}`)).map(e => ({ seq: e.seq, at: e.at, replay: (e.dataSnippet || '').includes('"replay":true'), snippetHead: (e.dataSnippet || '').slice(0, 220) })),
+      readyFrames: proxy.events.filter(e => e.kind === 'ws-frame' && e.type === 'event' && e.event === 'logs/ready').map(e => ({ seq: e.seq, at: e.at, cursorDecoded: decodeStreamCursor((() => { const m = /"streamCursor":"([^"]+)"/.exec(e.dataSnippet || ''); return m ? m[1] : ''; })()) })),
+    };
+    const statsAfterHandoff = JSON.parse(await runExpr(`JSON.stringify(window.KnowledgeLive ? window.KnowledgeLive.stats() : null)`));
+    evidence.phases.statsAfterHandoff = statsAfterHandoff;
+    await browser.screenshot(path.join(ARTIFACTS, 'gap-after-handoff.png'));
+
+    // API truth and disk truth: exactly once each; id strictly newer than the
+    // snapshot cursor's newest entry id.
+    const apiRes = await fetch(`${serverBase}/api/logs?pageSize=100&projectId=${PROJECT_A}`);
+    const apiBody = await apiRes.json();
+    const apiBoundary = (apiBody.entries || []).filter(e => e.event === 'goal.updated' && e.context && e.context.bytes === GAP_BYTES);
+    const disk = projectDayRecords(fixture.dataDir, PROJECT_A);
+    const diskBoundary = disk.filter(r => r.event === 'goal.updated' && r.context && r.context.bytes === GAP_BYTES);
+    const snapshotNewestId = evidence.phases.barrier.newestEntryId;
+    evidence.phases.parity = {
+      apiBoundaryCount: apiBoundary.length,
+      apiBoundaryId: apiBoundary[0]?.id || null,
+      diskBoundaryCount: diskBoundary.length,
+      diskBoundaryId: diskBoundary[0]?.id || null,
+      snapshotNewestId,
+      boundaryNewerThanSnapshot: Boolean(apiBoundary[0] && snapshotNewestId && apiBoundary[0].id !== snapshotNewestId),
+      boundaryRecordTs: apiBoundary[0]?.ts || null,
+      cursorAfterTs: snapshotCursorDecoded?.afterTs || null,
+    };
+
+    // Steady-state control (already-accepted half of LOG-004, re-proven on
+    // this instance): a second real write arrives live exactly once.
+    const steadyRes = await fetch(`${proxy.url}/api/projects/${PROJECT_A}/goal`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ content: padTo(`LOGFIXR2-GAP-STEADY-${run}`, STEADY_BYTES) }),
+    });
+    evidence.phases.steadyWrite = { at: now(), status: steadyRes.status, contentBytes: STEADY_BYTES };
+    const steadyState = await waitFor(async () => {
+      const state = await domState();
+      return state.steadyRecords.length === 1 ? state : null;
+    }, 'steady-state record visible exactly once in DOM', 20000);
+    evidence.phases.domSteady = { steadyRecords: steadyState.steadyRecords, uniqueIds: steadyState.uniqueIds };
+    evidence.phases.steadyWire = {
+      frames: proxy.events.filter(e => e.kind === 'ws-frame' && e.type === 'event' && e.event === 'logs/appended' && (e.dataSnippet || '').includes(`"bytes":${STEADY_BYTES}`)).map(e => ({ seq: e.seq, at: e.at, replay: (e.dataSnippet || '').includes('"replay":true') })),
+    };
+    await browser.screenshot(path.join(ARTIFACTS, 'gap-steady.png'));
+
+    if (browser.exceptions.length) throw new Error(`browser exceptions: ${JSON.stringify(browser.exceptions)}`);
+
+    // Verdicts.
+    const heldWindowMs = barrier.heldAt ? Date.parse(evidence.phases.releaseAt) - Date.parse(barrier.heldAt) : null;
+    evidence.phases.heldWindowMs = heldWindowMs;
+    const boundaryVerdict = {
+      subscriptionAbsentWhileHeld: evidence.phases.whileHeld.logsStreamSubscriptionEstablished === false,
+      statsSubscriptionCountStableWhileHeld: statsWhileHeld && statsBaseline && statsWhileHeld.subscriptions === statsBaseline.subscriptions,
+      boundaryWriteWhileHeld: evidence.phases.boundaryWrite.status === 200,
+      releasedOriginalBytes: true,
+      subscribeAfterReleaseWithSnapshotCursor: subscribeFrames.length === 1 && subscribeFrames[0].seq > releaseSeq
+        && evidence.phases.handoffWire.subscribeCursor?.raw === barrier.streamCursor,
+      boundaryInDomExactlyOnce: afterHandoff.boundaryRecords.length === 1,
+      domIdsUnique: afterHandoff.uniqueIds,
+      boundaryFrameExactlyOnce: evidence.phases.handoffWire.boundaryFrames.length === 1,
+      boundaryFrameIsReplayCatchup: evidence.phases.handoffWire.boundaryFrames[0]?.replay === true,
+      apiExactlyOnce: apiBoundary.length === 1,
+      diskExactlyOnce: diskBoundary.length === 1,
+      recordNewerThanSnapshotCursor: evidence.phases.parity.boundaryNewerThanSnapshot,
+      heldWindowUnderUiTimeout: heldWindowMs !== null && heldWindowMs < 2500,
+    };
+    const steadyVerdict = {
+      steadyInDomExactlyOnce: steadyState.steadyRecords.length === 1,
+      steadyFrameExactlyOnceLive: evidence.phases.steadyWire.frames.length === 1 && evidence.phases.steadyWire.frames[0].replay === false,
+    };
+    evidence.verdicts = {
+      'LOG-004 交界（快照→订阅）无丢失无重复': Object.values(boundaryVerdict).every(Boolean) ? 'PASS' : 'FAIL',
+      'LOG-004 稳态控制（实时一次到达）': Object.values(steadyVerdict).every(Boolean) ? 'PASS' : 'FAIL',
+      detail: { boundaryVerdict, steadyVerdict },
+    };
+    const allPass = Object.values(boundaryVerdict).every(Boolean) && Object.values(steadyVerdict).every(Boolean);
+    if (!allPass) throw new Error(`boundary/steady assertion failed: ${JSON.stringify({ boundaryVerdict, steadyVerdict })}`);
+    console.log('R2 gap boundary PASS');
+    process.exitCode = 0;
+  } catch (error) {
+    evidence.verdicts = { failed: String((error && error.stack) || error) };
+    try {
+      if (browser) {
+        evidence.debugDom = JSON.parse(await browser.evaluate(`JSON.stringify({ dialogOpen: document.getElementById('logsDialog')?.open, entries: document.querySelectorAll('#logsContent .log-entry').length })`));
+        evidence.debugConsoleErrors = browser.consoleErrors;
+      }
+    } catch {}
+    console.error(`R2 gap FAIL: ${error.message}`);
+    process.exitCode = 1;
+  } finally {
+    evidence.finishedAt = now();
+    evidence.proxyEventLog = proxy.events.map(e => ({ seq: e.seq, at: e.at, kind: e.kind, type: e.type || null, route: e.route || null, url: e.url || null, status: e.status || null, held: e.held || null, event: e.event || null }));
+    fs.mkdirSync(ARTIFACTS, { recursive: true });
+    fs.writeFileSync(path.join(ARTIFACTS, 'gap-evidence.json'), JSON.stringify(evidence, null, 2) + '\n');
+    try { await browser?.close(); } finally { try { await proxy.close(); } finally { try { await server.cleanup(); } finally { fixture.cleanup(); } } }
+    lane.cleanup();
+  }
+}
+
+const hardTimer = setTimeout(() => {
+  try {
+    fs.mkdirSync(ARTIFACTS, { recursive: true });
+    fs.writeFileSync(path.join(ARTIFACTS, 'hard-timeout.json'), JSON.stringify({ at: now(), run }, null, 2) + '\n');
+  } catch {}
+  console.error('gap test HARD TIMEOUT');
+  process.exit(2);
+}, HARD_TIMEOUT_MS);
+hardTimer.unref();
+
+main();

package/_site/_test/parallel-logging-fix-r2-normalhook-test.js

@@ -0,0 +1,330 @@
+'use strict';
+// P-LOG-SAFETY-R2 normal hook path regression (lane-exclusive prefix
+// parallel-logging-fix-r2-*).
+//
+// Complements the crash red/green probe: with the floating-rejection fix in
+// place, the NORMAL legacy hook path must keep working end to end — two
+// sequential real commits in a real registered Git fixture, two hook
+// events, both processed to background.operation_completed by the existing
+// clearly-labelled offline analyzer stand-in (KB_AUTOMATION_FAKE_CLAUDE=1,
+// RuntimeKnowledgeAnalyzer.fakeResult), knowledge promoted into the
+// project's knowledge root, lastAnalyzedCommit advancing, server healthy
+// throughout, and an orderly control-channel shutdown.
+//
+// This is not a model-quality acceptance; the stand-in is marked as such in
+// every record it writes ("isolated automation test adapter").
+//
+// KB_EMBEDDING_FAKE=1 is the product's own mock embedder (server-app.js
+// createEmbedder), the same stand-in the other background-path product tests
+// use. Without it the isolated instance has a cold model cache and the real
+// embedding path tries to fetch the ONNX model from the network, which stalls
+// the background operation past the run-all budget.
+//
+// P-LINUX-CI-CLOSEOUT-R7 corrections: (1) a health-timeout failure now prints
+// the server's own exit cause, its captured stdout/stderr tails, and whether
+// the port ever answered — /api/health is a synchronous responder behind the
+// HTTP listener, so a 30s timeout means initializeRuntime never reached
+// listen, and the stderr tail is the only way the CI log can name the hanging
+// await; (2) the failure path force-kills a wedged server child — a surviving
+// child process handle keeps this process alive (the linux22 CI shape: FAIL
+// printed at 30s, hang until the 80s hard timer); (3) the hard timer dumps
+// the captured server IO before exit(2). The 30s health budget is unchanged.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+// Portable isolation (P-QA-LOG-INTEGRATION-5025): the temp root comes from
+// PK_TEST_TEMP_ROOT or os.tmpdir() and must live outside the source tree;
+// HOME/APPDATA/LOCALAPPDATA/TEMP/CODEX_HOME/CLAUDE_CONFIG_DIR and the dual
+// product data roots are redirected before any other module is loaded.
+const { installLoggingTestEnv, resolveEvidenceDir } = require('./helpers/parallel-logging-integration-5025-env');
+const lane = installLoggingTestEnv({ caseId: 'LOGFIXR2-NORMALHOOK', prefix: 'logfixr2-normal' });
+const laneTmp = lane.laneTmp;
+
+const { spawnServer } = require('./helpers/spawn-server');
+const freePort = require('./helpers/free-port');
+const { SettingsStore } = require('../lib/settings-store');
+const { createLoggingAcceptanceFixture } = require('./helpers/parallel-logging-acceptance-fixture');
+
+const ROOT = path.resolve(__dirname, '../..');
+const ARTIFACTS = resolveEvidenceDir(path.resolve(ROOT, 'qa-autopilot/artifacts/parallel-20261023/logging-fix-r2/evidence/normalhook'));
+
+const PROJECT_A = 'project-logfixr2-normal';
+// Below the run-all per-test budget (PK_TEST_TIMEOUT_MS, default 90s) so a
+// stall still lets this entry write its own evidence before the runner kills
+// the child.
+const HARD_TIMEOUT_MS = 80000;
+
+// Module scope so the hard-timeout timer can kill the spawned server and dump
+// its IO before exit(2) (see the R7 note in the header).
+let server = null;
+let exitInfo = null;
+let serverStdout = '';
+let serverStderr = '';
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const now = () => new Date().toISOString();
+
+const GIT_ENV = {
+  ...process.env,
+  GIT_CONFIG_NOSYSTEM: '1',
+  GIT_CONFIG_GLOBAL: path.join(laneTmp, 'non-existent-git-config'),
+};
+
+function git(repoPath, args) {
+  const res = spawnSync('git', ['-C', repoPath, ...args], { encoding: 'utf8', env: GIT_ENV });
+  if (res.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${res.stderr}`);
+  return res.stdout.trim();
+}
+
+function addCommit(repoPath, name, content) {
+  fs.writeFileSync(path.join(repoPath, name), content);
+  git(repoPath, ['add', '.']);
+  git(repoPath, ['commit', '-q', '-m', `LOGFIXR2 normal ${name}`]);
+  return git(repoPath, ['rev-parse', 'HEAD']);
+}
+
+function allLogRecords(dataDir) {
+  const records = [];
+  const rootDir = path.join(dataDir, 'logs');
+  if (!fs.existsSync(rootDir)) return records;
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.jsonl')) {
+        for (const line of fs.readFileSync(full, 'utf8').split('\n')) {
+          if (line.trim()) { try { records.push(JSON.parse(line)); } catch {} }
+        }
+      }
+    }
+  };
+  walk(rootDir);
+  return records;
+}
+
+async function waitFor(predicate, label, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  while (Date.now() < deadline) {
+    last = await predicate();
+    if (last) return last;
+    await sleep(300);
+  }
+  throw new Error(`timeout waiting for ${label}`);
+}
+
+async function main() {
+  fs.mkdirSync(ARTIFACTS, { recursive: true });
+  const evidence = { caseId: 'R2-NORMALHOOK', startedAt: now(), phases: {} };
+
+  const fixture = await createLoggingAcceptanceFixture({
+    caseId: 'logfixr2normal',
+    projects: [{ projectId: PROJECT_A, displayName: 'LOGFIXR2正常路径' }],
+  });
+  await fixture.logger.close();
+  // The reconciler resolves a usable AI profile before the (fake) claim runs;
+  // give the isolated settings one clearly-labelled offline profile.
+  const settingsStore = new SettingsStore({ layout: fixture.layout });
+  await settingsStore.updatePatch({ ai: { profiles: [{ id: 'profile-logfixr2-offline', name: 'LOGFIXR2 离线替身', enabled: true, vendor: 'offline-standin' }] } });
+  const repoA = fixture.projects[0].repo.path;
+
+  // Two additional real commits in the real registered fixture repository.
+  const sha2 = addCommit(repoA, 'notes-two.md', '# second\n\nLOGFIXR2 normal path commit 2.\n');
+  const sha3 = addCommit(repoA, 'notes-three.md', '# third\n\nLOGFIXR2 normal path commit 3.\n');
+  evidence.commits = { sha2, sha3 };
+
+  const port = await freePort();
+  const base = `http://127.0.0.1:${port}`;
+  server = spawnServer({
+    root: ROOT,
+    port,
+    dataDir: fixture.dataDir,
+    tag: 'logfixr2normal',
+    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
+  });
+  server.child.once('exit', (code, signal) => { exitInfo = { code, signal, at: now() }; });
+  server.child.stdout.on('data', chunk => { serverStdout += chunk; });
+  server.child.stderr.on('data', chunk => { serverStderr += chunk; });
+
+  const postHook = async (head, operationId) => {
+    const res = await fetch(`${base}/api/hooks/post-commit`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ schema: 'hook-event/v2', projectId: PROJECT_A, repoRoot: repoA, head, branch: 'main', operationId }),
+    });
+    const body = await res.json().catch(() => null);
+    return { status: res.status, body };
+  };
+
+  try {
+    await waitFor(async () => {
+      try { return (await fetch(`${base}/api/health`)).ok; } catch { return false; }
+    }, 'isolated server healthy', 30000);
+    evidence.server = { pid: server.child.pid, port };
+
+    // Queue semantics: post BOTH hook events back to back (the second while
+    // the first may still be running), then require both to settle.
+    const op1 = 'op-logfixr2-normal-0001';
+    const op2 = 'op-logfixr2-normal-0002';
+    const ack1 = await postHook(sha2, op1);
+    const ack2 = await postHook(sha3, op2);
+    evidence.hookAcks = { ack1, ack2 };
+    if (ack1.status !== 202 || ack2.status !== 202 || !ack1.body?.accepted || !ack2.body?.accepted) {
+      throw new Error(`hook acks not 202/accepted: ${JSON.stringify({ ack1, ack2 })}`);
+    }
+
+    const settled = await waitFor(() => {
+      const records = allLogRecords(fixture.dataDir);
+      const done = op => records.some(r => r.event === 'background.operation_completed' && r.operationId === op);
+      const failed = records.filter(r => r.event === 'background.operation_failed');
+      if (failed.length) return { premature: true, failed: failed.map(r => ({ operationId: r.operationId, code: r.error?.code, message: r.error?.message })) };
+      return done(op1) && done(op2);
+    }, 'both hook operations completed', 60000);
+    if (settled && settled.premature) throw new Error(`background failure on the normal path: ${JSON.stringify(settled.failed)}`);
+
+    const records = allLogRecords(fixture.dataDir);
+    evidence.phases.background = {
+      completed: records.filter(r => r.event === 'background.operation_completed').map(r => ({ operationId: r.operationId, ts: r.ts })),
+      failed: records.filter(r => r.event === 'background.operation_failed').map(r => r.operationId),
+      accepted: records.filter(r => r.event === 'hook.event_accepted').map(r => ({ operationId: r.operationId, ts: r.ts })),
+      promotionEvents: records.filter(r => r.event.startsWith('knowledge.promotion') || r.event.startsWith('reconcile.')).map(r => ({ event: r.event, operationId: r.operationId, commitSha: r.commitSha, error: r.error ? { code: r.error.code, message: r.error.message } : undefined, context: r.context, ts: r.ts })).slice(0, 20),
+    };
+    // Diagnostic tree of the isolated data dir (depth 3) so file destinations
+    // are auditable in evidence.
+    const treeOf = (dir, depth) => {
+      const out = [];
+      if (depth < 0 || !fs.existsSync(dir)) return out;
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        out.push(path.relative(fixture.dataDir, path.join(dir, entry.name)) + (entry.isDirectory() ? '/' : ''));
+        if (entry.isDirectory() && depth > 0) out.push(...treeOf(path.join(dir, entry.name), depth - 1));
+      }
+      return out;
+    };
+    evidence.phases.dataDirTree = treeOf(fixture.dataDir, 3).slice(0, 200);
+    if (evidence.phases.background.failed.length) throw new Error('no operation_failed expected on the all-valid normal path');
+
+    // Knowledge promoted from the labelled offline stand-in: entries under the
+    // project knowledge root naming the isolated automation test adapter.
+    const knowledgeRoot = fixture.projects[0].knowledgePath;
+    const mdFiles = [];
+    const walk = (dir) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (entry.name.endsWith('.md')) mdFiles.push({ file: path.relative(knowledgeRoot, full), content: fs.readFileSync(full, 'utf8') });
+      }
+    };
+    walk(knowledgeRoot);
+    evidence.phases.knowledge = {
+      entries: mdFiles.map(f => ({ file: f.file, adapterLabelled: f.content.includes('isolated automation test adapter') })),
+    };
+    const promotedCount = mdFiles.filter(f => f.content.includes('isolated automation test adapter')).length;
+    if (promotedCount < 2) throw new Error(`expected >=2 promoted knowledge entries from the two commits, got ${promotedCount}`);
+
+    // Health throughout + no premature exit.
+    const health = await fetch(`${base}/api/health`);
+    evidence.phases.healthAfterHooks = { status: health.status, exitInfo };
+    if (!health.ok || exitInfo !== null) throw new Error(`server unhealthy or exited during normal processing: ${JSON.stringify({ status: health.status, exitInfo })}`);
+
+    // Disk truth BEFORE shutdown (spawnServer.cleanup removes the data dir):
+    // lastAnalyzedCommit advanced to the last commit.
+    const stateFile = path.join(fixture.dataDir, 'projects', PROJECT_A, 'state.json');
+    const readState = p => JSON.parse(fs.readFileSync(p, 'utf8'));
+    let state;
+    try { state = readState(stateFile); } catch {
+      const candidates = [];
+      const projDir = path.join(fixture.dataDir, 'projects');
+      for (const name of fs.readdirSync(projDir)) {
+        const candidate = path.join(projDir, name, 'state.json');
+        if (fs.existsSync(candidate) && readState(candidate).lastAnalyzedCommit) candidates.push(readState(candidate));
+      }
+      state = candidates[0];
+    }
+    evidence.phases.projectState = { lastAnalyzedCommit: state?.lastAnalyzedCommit, expected: sha3 };
+    if (state?.lastAnalyzedCommit !== sha3) throw new Error(`lastAnalyzedCommit did not advance to ${sha3}: ${state?.lastAnalyzedCommit}`);
+
+    // Orderly shutdown via the verified control channel (drain path).
+    const stopStarted = Date.now();
+    await server.cleanup();
+    evidence.phases.shutdown = { stopStartedAt: new Date(stopStarted).toISOString(), exitInfo, stoppedWithinMs: Date.now() - stopStarted };
+
+    if (exitInfo === null) throw new Error('server did not exit after control-channel stop');
+    evidence.verdict = 'PASS';
+    console.log('R2 normalhook PASS');
+    process.exitCode = 0;
+  } catch (error) {
+    evidence.verdict = { failed: String((error && error.stack) || error) };
+    // Failure-path visibility: the CI console is the only artifact the runner
+    // keeps. A health timeout must name the server's own exit cause, its
+    // captured stdout/stderr tails, and whether the port ever answered.
+    let probeAfterFailure = null;
+    try {
+      const response = await fetch(`${base}/api/health`, { signal: AbortSignal.timeout(1500) });
+      probeAfterFailure = { answered: true, ok: response.ok, status: response.status };
+    } catch (probeError) {
+      probeAfterFailure = { answered: false, code: (probeError && probeError.cause && (probeError.cause.code || probeError.cause.message)) || String(probeError && probeError.message || probeError) };
+    }
+    evidence.debugFailureProbe = probeAfterFailure;
+    // The child's OWN structured logs hold its account of its death: on a
+    // startup rejection stop() logs server.shutdown_started with the reason
+    // (CI 40075242420: 'control-startup-failed' from an unbindable POSIX
+    // control socket) before the error reaches the bootstrap catch. Bounded
+    // metadata only — level, event, reason, error code, first stack frame's
+    // file — never raw context or transcripts.
+    let ownStartupRecords = null;
+    try {
+      ownStartupRecords = allLogRecords(fixture.dataDir)
+        .filter(r => ['fatal', 'error', 'warn'].includes(r.level) || String(r.event || '').startsWith('server.'))
+        .slice(-5)
+        .map(r => ({
+          level: r.level || null,
+          event: r.event || null,
+          reason: (r.context && r.context.reason) || null,
+          code: (r.error && r.error.code) || null,
+          stackFile: (String((r.error && r.error.stack) || '').split('\n')[1] || '').match(/([^\\/]+)\.[a-z]+:/i)?.[0] || null,
+        }));
+    } catch {}
+    evidence.debugOwnStartupRecords = ownStartupRecords;
+    let posixControlSocket = 'named-pipe (win32)';
+    try {
+      const { controlPath } = require('../lib/runtime-control');
+      if (process.platform !== 'win32') posixControlSocket = `${controlPath(fixture.dataDir).length} chars (POSIX budget 103)`;
+    } catch {}
+    console.error(`R2 normalhook FAIL: ${error.message}`);
+    console.error(`R2 normalhook server state: ${JSON.stringify({ port, pid: server.child.pid, exitInfo, probeAfterFailure, posixControlSocket })}`);
+    console.error(`R2 normalhook own structured-log tail (bounded): ${JSON.stringify(ownStartupRecords)}`);
+    console.error(`R2 normalhook server stderr tail:\n${serverStderr.slice(-1600)}`);
+    console.error(`R2 normalhook server stdout tail:\n${serverStdout.slice(-1600)}`);
+    process.exitCode = 1;
+  } finally {
+    evidence.debugServerIo = { exitInfo, stdoutTail: serverStdout.slice(-4000), stderrTail: serverStderr.slice(-4000) };
+    evidence.finishedAt = now();
+    fs.mkdirSync(ARTIFACTS, { recursive: true });
+    fs.writeFileSync(path.join(ARTIFACTS, 'normalhook-evidence.json'), JSON.stringify(evidence, null, 2) + '\n');
+    try {
+      await server.cleanup();
+      // cleanup() stops the control channel and kills, but a child wedged
+      // mid-startup can survive the signal — and its process handle keeps
+      // THIS process alive (the linux22 CI shape: FAIL at 30s, hang to the
+      // 80s hard timer). The exit decision belongs to this test, not to the
+      // child.
+      if (exitInfo === null) { try { server.child.kill('SIGKILL'); } catch {} }
+    } finally { fixture.cleanup(); }
+    lane.cleanup();
+  }
+}
+
+const hardTimer = setTimeout(() => {
+  try {
+    fs.mkdirSync(ARTIFACTS, { recursive: true });
+    fs.writeFileSync(path.join(ARTIFACTS, 'hard-timeout.json'), JSON.stringify({ at: now(), exitInfo, stdoutTail: serverStdout.slice(-1600), stderrTail: serverStderr.slice(-1600) }, null, 2) + '\n');
+  } catch {}
+  try { if (server && exitInfo === null) server.child.kill('SIGKILL'); } catch {}
+  console.error('normalhook HARD TIMEOUT');
+  process.exit(2);
+}, HARD_TIMEOUT_MS);
+hardTimer.unref();
+
+main();