noteconnection 1.6.3 → 1.6.5

package/README.md

@@ -319,6 +319,13 @@ For developers building from source, NoteConnection offers two build modes:
 - Run mapping validation: `npm run docs:diataxis:check`.
 - Run local docs site preview: `npm run docs:site:serve`.
 - Build static docs site: `npm run docs:site:build`.
+- EdgeOne Docs Portal (MkDocs deploy): `https://noteconnection-docs.edgeone.run`
+  - If you see `401 Authorization Required`, open the latest signed URL printed by deployment as `EDGEONE_DEPLOY_URL`, or disable preset-domain protection in EdgeOne Pages settings.
+- Public mirror (fallback): `https://jacobinwwey.github.io/NoteConnection/`.
+- Recommended lookup entry points:
+  - Users: `/diataxis/zh/tutorials/first-run/` or `/diataxis/en/tutorials/first-run/`
+  - Developers: `/diataxis/en/reference/interfaces-and-runtime/` and `/diataxis/en/reference/release-and-governance/`
+- EdgeOne publish command (MkDocs site): `edgeone pages deploy build/mkdocs-site -n noteconnection-docs -e production -a global`.
 - CI policy gate for docs mapping and site build: `.github/workflows/docs-diataxis-site.yml`.
 
 ## 🛠️ Hardware & Driver Requirements (AMDGPU)
@@ -334,6 +341,13 @@ For optimal performance with "GPU Optimised Rendering", especially on AMD RDNA c
 
 ## 📅 Changelog
 
+### v1.6.5 - Documentation Portal Update (2026-03-26)
+
+- Published MkDocs documentation to EdgeOne Pages project `noteconnection-docs`.
+- Added bilingual README guidance for docs lookup paths (user/tutorial and developer/reference entry points).
+- Standardized docs publish command for maintainers:
+  - `npm run docs:site:build`
+  - `edgeone pages deploy build/mkdocs-site -n noteconnection-docs -e production -a global`
 ### v1.6.0 - Unified Runtime, NoteMD Integration & Release Hardening (2026-03-23)
 
 - **Tag Compare Snapshot (`v1.3.0..v1.6.0`)**:
@@ -1196,6 +1210,13 @@ sync_language = true
 - 映射一致性校验：`npm run docs:diataxis:check`。
 - 本地预览文档站点：`npm run docs:site:serve`。
 - 构建静态文档站点：`npm run docs:site:build`。
+- EdgeOne 文档入口（MkDocs 发布）：`https://noteconnection-docs.edgeone.run`
+  - 若出现 `401 Authorization Required`，请使用最近一次部署输出中的 `EDGEONE_DEPLOY_URL` 签名链接，或在 EdgeOne Pages 项目中关闭预设域名访问保护。
+- 公共镜像（兜底）：`https://jacobinwwey.github.io/NoteConnection/`。
+- 推荐查询入口：
+  - 用户文档：`/diataxis/zh/tutorials/first-run/` 或 `/diataxis/en/tutorials/first-run/`
+  - 开发文档：`/diataxis/en/reference/interfaces-and-runtime/` 与 `/diataxis/en/reference/release-and-governance/`
+- EdgeOne 发布命令（MkDocs 产物）：`edgeone pages deploy build/mkdocs-site -n noteconnection-docs -e production -a global`。
 - CI 文档治理工作流：`.github/workflows/docs-diataxis-site.yml`。
 
 ---
@@ -1204,6 +1225,13 @@ sync_language = true
 
 ## 更新日志 (Changelog)
 
+### v1.6.5 - �ĵ��Ż����£�2026-03-26��
+
+- �ѽ� MkDocs �ĵ������� EdgeOne Pages ��Ŀ `noteconnection-docs`��
+- ���� README ������Ӣ�IJ�ѯָ���������û��̳�����뿪���ο���ڣ���
+- ά���߷�������ͳһΪ��
+  - `npm run docs:site:build`
+  - `edgeone pages deploy build/mkdocs-site -n noteconnection-docs -e production -a global`
 ### v1.6.0 - 单窗口运行时、NoteMD 集成与发布加固 (2026-03-23)
 
 - **Tag 对比快照（`v1.3.0..v1.6.0`）**:

package/dist/src/backend/utils/CrashLogger.js

@@ -38,6 +38,11 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 class CrashLogger {
+    static isIgnorableProcessWriteError(error) {
+        const code = typeof error === 'object' && error ? String(error.code || '') : '';
+        const syscall = typeof error === 'object' && error ? String(error.syscall || '') : '';
+        return code === 'EPIPE' || code === 'ERR_STREAM_DESTROYED' || (code === 'EOF' && syscall === 'write');
+    }
     static log(error, context = 'General') {
         const timestamp = new Date().toISOString();
         const errorMessage = error instanceof Error ? error.stack || error.message : String(error);
@@ -55,12 +60,22 @@ class CrashLogger {
         }
     }
     static initGlobalHandlers() {
+        if (this.globalHandlersInstalled) {
+            return;
+        }
+        this.globalHandlersInstalled = true;
         process.on('uncaughtException', (error) => {
+            if (CrashLogger.isIgnorableProcessWriteError(error)) {
+                return;
+            }
             console.error('Uncaught Exception:', error);
             CrashLogger.log(error, 'UncaughtException');
             process.exit(1); // Exit is mandatory for uncaught exceptions to avoid undefined state
         });
         process.on('unhandledRejection', (reason, promise) => {
+            if (CrashLogger.isIgnorableProcessWriteError(reason)) {
+                return;
+            }
             console.error('Unhandled Rejection at:', promise, 'reason:', reason);
             CrashLogger.log(reason, 'UnhandledRejection');
         });
@@ -68,3 +83,4 @@ class CrashLogger {
 }
 exports.CrashLogger = CrashLogger;
 CrashLogger.logFilePath = path.join(process.cwd(), 'crash.log');
+CrashLogger.globalHandlersInstalled = false;

package/dist/src/crashlogger.contract.test.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const CrashLogger_1 = require("./backend/utils/CrashLogger");
+describe('CrashLogger broken pipe policy', () => {
+    test('treats write-side EPIPE and destroyed stream errors as ignorable process shutdown noise', () => {
+        expect(CrashLogger_1.CrashLogger.isIgnorableProcessWriteError(Object.assign(new Error('write EPIPE'), { code: 'EPIPE', syscall: 'write' }))).toBe(true);
+        expect(CrashLogger_1.CrashLogger.isIgnorableProcessWriteError(Object.assign(new Error('stream destroyed'), { code: 'ERR_STREAM_DESTROYED' }))).toBe(true);
+    });
+    test('does not suppress unrelated runtime exceptions', () => {
+        expect(CrashLogger_1.CrashLogger.isIgnorableProcessWriteError(Object.assign(new Error('permission denied'), { code: 'EACCES', syscall: 'open' }))).toBe(false);
+        expect(CrashLogger_1.CrashLogger.isIgnorableProcessWriteError(new Error('boom'))).toBe(false);
+    });
+});

package/dist/src/frontend/README.md

@@ -319,6 +319,13 @@ For developers building from source, NoteConnection offers two build modes:
 - Run mapping validation: `npm run docs:diataxis:check`.
 - Run local docs site preview: `npm run docs:site:serve`.
 - Build static docs site: `npm run docs:site:build`.
+- EdgeOne Docs Portal (MkDocs deploy): `https://noteconnection-docs.edgeone.run`
+  - If you see `401 Authorization Required`, open the latest signed URL printed by deployment as `EDGEONE_DEPLOY_URL`, or disable preset-domain protection in EdgeOne Pages settings.
+- Public mirror (fallback): `https://jacobinwwey.github.io/NoteConnection/`.
+- Recommended lookup entry points:
+  - Users: `/diataxis/zh/tutorials/first-run/` or `/diataxis/en/tutorials/first-run/`
+  - Developers: `/diataxis/en/reference/interfaces-and-runtime/` and `/diataxis/en/reference/release-and-governance/`
+- EdgeOne publish command (MkDocs site): `edgeone pages deploy build/mkdocs-site -n noteconnection-docs -e production -a global`.
 - CI policy gate for docs mapping and site build: `.github/workflows/docs-diataxis-site.yml`.
 
 ## 🛠️ Hardware & Driver Requirements (AMDGPU)
@@ -334,6 +341,13 @@ For optimal performance with "GPU Optimised Rendering", especially on AMD RDNA c
 
 ## 📅 Changelog
 
+### v1.6.5 - Documentation Portal Update (2026-03-26)
+
+- Published MkDocs documentation to EdgeOne Pages project `noteconnection-docs`.
+- Added bilingual README guidance for docs lookup paths (user/tutorial and developer/reference entry points).
+- Standardized docs publish command for maintainers:
+  - `npm run docs:site:build`
+  - `edgeone pages deploy build/mkdocs-site -n noteconnection-docs -e production -a global`
 ### v1.6.0 - Unified Runtime, NoteMD Integration & Release Hardening (2026-03-23)
 
 - **Tag Compare Snapshot (`v1.3.0..v1.6.0`)**:
@@ -1196,6 +1210,13 @@ sync_language = true
 - 映射一致性校验：`npm run docs:diataxis:check`。
 - 本地预览文档站点：`npm run docs:site:serve`。
 - 构建静态文档站点：`npm run docs:site:build`。
+- EdgeOne 文档入口（MkDocs 发布）：`https://noteconnection-docs.edgeone.run`
+  - 若出现 `401 Authorization Required`，请使用最近一次部署输出中的 `EDGEONE_DEPLOY_URL` 签名链接，或在 EdgeOne Pages 项目中关闭预设域名访问保护。
+- 公共镜像（兜底）：`https://jacobinwwey.github.io/NoteConnection/`。
+- 推荐查询入口：
+  - 用户文档：`/diataxis/zh/tutorials/first-run/` 或 `/diataxis/en/tutorials/first-run/`
+  - 开发文档：`/diataxis/en/reference/interfaces-and-runtime/` 与 `/diataxis/en/reference/release-and-governance/`
+- EdgeOne 发布命令（MkDocs 产物）：`edgeone pages deploy build/mkdocs-site -n noteconnection-docs -e production -a global`。
 - CI 文档治理工作流：`.github/workflows/docs-diataxis-site.yml`。
 
 ---
@@ -1204,6 +1225,13 @@ sync_language = true
 
 ## 更新日志 (Changelog)
 
+### v1.6.5 - �ĵ��Ż����£�2026-03-26��
+
+- �ѽ� MkDocs �ĵ������� EdgeOne Pages ��Ŀ `noteconnection-docs`��
+- ���� README ������Ӣ�IJ�ѯָ���������û��̳�����뿪���ο���ڣ���
+- ά���߷�������ͳһΪ��
+  - `npm run docs:site:build`
+  - `edgeone pages deploy build/mkdocs-site -n noteconnection-docs -e production -a global`
 ### v1.6.0 - 单窗口运行时、NoteMD 集成与发布加固 (2026-03-23)
 
 - **Tag 对比快照（`v1.3.0..v1.6.0`）**:

package/dist/src/notemd.api.contract.test.js

@@ -57,8 +57,10 @@ describe('NoteMD API contract wiring', () => {
             expect(serverSource).toContain(endpoint);
         });
     });
-    test('server persists NoteMD settings in runtime data directory', () => {
-        expect(serverSource).toContain('NOTEMD_CONFIG_FILE_NAME');
+    test('server persists NoteMD settings through app_config.toml helpers', () => {
+        expect(serverSource).toContain("from './notemd/AppConfigToml'");
+        expect(serverSource).toContain('loadAppConfigToml');
+        expect(serverSource).toContain('saveAppConfigToml');
         expect(serverSource).toContain('persistNotemdSettings');
         expect(serverSource).toContain('loadNotemdSettings');
     });

package/dist/src/pkg.snapshot.safety.contract.test.js

@@ -50,11 +50,13 @@ describe('pkg snapshot safety contract', () => {
             expect(source).not.toContain('eval(');
         });
     });
-    test('reader and source manager keep static import fallback paths for packaging', () => {
+    test('reader and source manager keep packaging-safe Mermaid/runtime fallback paths', () => {
         const readerRenderer = fs.readFileSync(runtimeEntryFiles[0], 'utf8');
         const sourceManager = fs.readFileSync(runtimeEntryFiles[2], 'utf8');
         expect(readerRenderer).toContain('loadMermaidModule');
-        expect(readerRenderer).toContain("import('mermaid')");
+        expect(readerRenderer).toContain('MERMAID_BROWSER_BUNDLE_BASE64');
+        expect(readerRenderer).toContain("createElement('script')");
+        expect(readerRenderer).not.toContain("require('mermaid')");
         expect(sourceManager).toContain('parseGraphDataPayload');
         expect(sourceManager).toContain('Fallback for assignment-based payloads without using runtime eval.');
     });

package/dist/src/reader_renderer.js

@@ -1,37 +1,4 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderMathSvg = renderMathSvg;
@@ -51,7 +18,6 @@ const { liteAdaptor } = require('mathjax-full/js/adaptors/liteAdaptor.js');
 const { HandlerList } = require('mathjax-full/js/core/HandlerList.js');
 const { HTMLHandler } = require('mathjax-full/js/handlers/html/HTMLHandler.js');
 const { initWasm, Resvg } = require('@resvg/resvg-wasm');
-const importMermaidModule = () => Promise.resolve().then(() => __importStar(require('mermaid')));
 const MATH_TEXT_COLOR = '#eef4ff';
 const MERMAID_BACKGROUND = 'transparent';
 const MERMAID_PADDING = 28;
@@ -111,7 +77,6 @@ const mathDocument = mathHandlers.document('', {
     OutputJax: svgOutput,
 });
 let mermaidEnvironmentPromise = null;
-let mermaidModulePromise = null;
 let mermaidRenderQueue = Promise.resolve();
 let mermaidRenderCounter = 0;
 let resvgInitPromise = null;
@@ -390,14 +355,9 @@ async function createMermaidEnvironment(theme) {
     };
 }
 async function loadMermaidModule(window) {
-    if (!process.pkg) {
-        if (!mermaidModulePromise) {
-            mermaidModulePromise = (async () => {
-                const mermaidModule = await importMermaidModule();
-                return mermaidModule.default ?? mermaidModule;
-            })();
-        }
-        return mermaidModulePromise;
+    const existingMermaid = window.mermaid;
+    if (existingMermaid) {
+        return existingMermaid;
     }
     const script = window.document.createElement('script');
     script.textContent = Buffer.from(mermaid_runtime_1.MERMAID_BROWSER_BUNDLE_BASE64, 'base64').toString('utf8');

package/dist/src/reader_renderer.test.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = __importDefault(require("node:path"));
 const jsdom_1 = require("jsdom");
@@ -82,6 +83,12 @@ describe('reader_renderer', () => {
             stdio: 'inherit',
         });
     }, 120000);
+    it('keeps the compiled Mermaid loader on the embedded browser runtime path instead of requiring the ESM package directly', () => {
+        const compiledRenderer = node_fs_1.default.readFileSync(distRendererPath, 'utf8');
+        expect(compiledRenderer).not.toContain("require('mermaid')");
+        expect(compiledRenderer).toContain('MERMAID_BROWSER_BUNDLE_BASE64');
+        expect(compiledRenderer).toContain("createElement('script')");
+    });
     it('renders display math to svg', () => {
         const svg = runRenderer('renderMathSvg', 'E = mc^2', { displayMode: true });
         expect(svg.startsWith('<svg')).toBe(true);

package/dist/src/server.js

@@ -39,6 +39,7 @@ exports.executeNotemdCliCommand = executeNotemdCliCommand;
 const http = __importStar(require("http"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const net = __importStar(require("net"));
 const readline = __importStar(require("readline"));
 const events_1 = require("events");
 const index_1 = require("./index");
@@ -52,6 +53,53 @@ const reader_renderer_1 = require("./reader_renderer");
 const native_clipboard_1 = require("./native_clipboard");
 const notemd_1 = require("./notemd");
 const AppConfigToml_1 = require("./notemd/AppConfigToml");
+function installBrokenPipeGuard(stream) {
+    if (!stream || stream.__noteConnectionBrokenPipeGuardInstalled) {
+        return;
+    }
+    stream.__noteConnectionBrokenPipeGuardInstalled = true;
+    stream.on('error', (error) => {
+        if (error?.code === 'EPIPE' || error?.code === 'ERR_STREAM_DESTROYED') {
+            return;
+        }
+        throw error;
+    });
+}
+installBrokenPipeGuard(process.stdout);
+installBrokenPipeGuard(process.stderr);
+const IS_JEST_RUNTIME = String(process.env.JEST_WORKER_ID || '').trim().length > 0;
+function logDiagnostic(...args) {
+    if (IS_JEST_RUNTIME) {
+        return;
+    }
+    console.log(...args);
+}
+function warnDiagnostic(...args) {
+    if (IS_JEST_RUNTIME) {
+        return;
+    }
+    console.warn(...args);
+}
+function installJestSocketBrokenPipeGuard() {
+    if (!IS_JEST_RUNTIME) {
+        return;
+    }
+    const socketPrototype = net.Socket.prototype;
+    if (socketPrototype.__noteConnectionBrokenPipeGuardInstalled) {
+        return;
+    }
+    const originalEmit = socketPrototype.emit;
+    socketPrototype.__noteConnectionBrokenPipeGuardInstalled = true;
+    socketPrototype.emit = function (event, ...args) {
+        if (event === 'error'
+            && CrashLogger_1.CrashLogger.isIgnorableProcessWriteError(args[0])
+            && (this.destroyed || this.writable === false)) {
+            return true;
+        }
+        return originalEmit.call(this, event, ...args);
+    };
+}
+installJestSocketBrokenPipeGuard();
 // Initialize Global Crash Handlers
 CrashLogger_1.CrashLogger.initGlobalHandlers();
 const LOOPBACK_HOST = '127.0.0.1';
@@ -124,16 +172,16 @@ function resolveBoundedMegabytesFromEnv(options) {
     }
     const parsedValue = Number(rawValue);
     if (!Number.isFinite(parsedValue)) {
-        console.warn(`[Config] ${envKey} is not a number ("${rawValue}"). Using default ${defaultMb} MiB.`);
+        warnDiagnostic(`[Config] ${envKey} is not a number ("${rawValue}"). Using default ${defaultMb} MiB.`);
         return defaultMb;
     }
     const normalizedMb = Math.floor(parsedValue);
     if (normalizedMb < minMb) {
-        console.warn(`[Config] ${envKey}=${rawValue} is below minimum ${minMb} MiB. Clamping to ${minMb} MiB.`);
+        warnDiagnostic(`[Config] ${envKey}=${rawValue} is below minimum ${minMb} MiB. Clamping to ${minMb} MiB.`);
         return minMb;
     }
     if (normalizedMb > maxMb) {
-        console.warn(`[Config] ${envKey}=${rawValue} exceeds maximum ${maxMb} MiB. Clamping to ${maxMb} MiB.`);
+        warnDiagnostic(`[Config] ${envKey}=${rawValue} exceeds maximum ${maxMb} MiB. Clamping to ${maxMb} MiB.`);
         return maxMb;
     }
     return normalizedMb;
@@ -385,7 +433,7 @@ async function safeUnlink(filePath) {
     }
     catch (error) {
         if (!isFsNotFoundError(error)) {
-            console.warn('[Sidecar] Failed to clean up temporary request body file:', error);
+            warnDiagnostic('[Sidecar] Failed to clean up temporary request body file:', error);
         }
     }
 }
@@ -710,7 +758,7 @@ async function loadNotemdSettings() {
         cachedNotemdSettings = normalizeNotemdSettings(parsedSettings);
     }
     catch (error) {
-        console.warn('[NoteMD] Failed to read settings from TOML, using defaults:', error);
+        warnDiagnostic('[NoteMD] Failed to read settings from TOML, using defaults:', error);
         cachedNotemdSettings = normalizeNotemdSettings(notemd_1.DEFAULT_SETTINGS);
     }
     return cloneNotemdSettings(cachedNotemdSettings);
@@ -894,7 +942,7 @@ async function writeSidecarRuntimeManifest(finalPort) {
         }, null, 2), 'utf8');
     }
     catch (error) {
-        console.warn('[Sidecar] Failed to write runtime manifest:', error);
+        warnDiagnostic('[Sidecar] Failed to write runtime manifest:', error);
     }
 }
 async function renderMermaidWithPreference(source, options) {
@@ -927,7 +975,7 @@ async function renderMermaidWithPreference(source, options) {
             if (options.rendererPreference === 'frontend') {
                 throw error;
             }
-            console.warn('[Reader] Frontend Mermaid render unavailable, falling back to local resvg:', error);
+            warnDiagnostic('[Reader] Frontend Mermaid render unavailable, falling back to local resvg:', error);
         }
     }
     const localRendered = await (0, reader_renderer_1.renderMermaidPng)(source, {
@@ -1162,7 +1210,7 @@ if (process.env.NOTE_CONNECTION_GPU === 'true' || process.env.NOTE_CONNECTION_GP
     cliOptions.enableGPULayout = true;
 }
 if (process.env.npm_config_static === 'true' || process.env.npm_config_static === '') {
-    console.log('[CLI] Static mode requested (via env).');
+    logDiagnostic('[CLI] Static mode requested (via env).');
 }
 if (process.env.npm_config_workers) {
     cliOptions.maxWorkers = parseInt(process.env.npm_config_workers);
@@ -1183,7 +1231,7 @@ for (let i = 0; i < args.length; i++) {
         cliOptions.enableGPULayout = false;
     }
     else if (arg === '--static') {
-        console.log('[CLI] Static mode requested (Frontend auto-detects large graphs).');
+        logDiagnostic('[CLI] Static mode requested (Frontend auto-detects large graphs).');
     }
     else if (arg === '--workers' && args[i + 1]) {
         cliOptions.maxWorkers = parseInt(args[++i]);
@@ -1204,7 +1252,7 @@ for (let i = 0; i < args.length; i++) {
         }
     }
 }
-console.log('[CLI] Parsed Options:', cliOptions);
+logDiagnostic('[CLI] Parsed Options:', cliOptions);
 function getCliFlagValue(argsList, flagName) {
     const index = argsList.indexOf(flagName);
     if (index < 0 || index + 1 >= argsList.length) {
@@ -1327,7 +1375,7 @@ const startServer = async (options = {}) => {
             hasCliBuild = true;
         }
         else {
-            console.warn("[CLI] Warning: targetPath detected as 'true'. This usually means npm consumed the flag incorrectly. Please check your command syntax.");
+            warnDiagnostic("[CLI] Warning: targetPath detected as 'true'. This usually means npm consumed the flag incorrectly. Please check your command syntax.");
             delete cliOptions.targetPath;
             hasCliBuild = false;
         }
@@ -1352,14 +1400,14 @@ const startServer = async (options = {}) => {
         // If we are required to not block, we should probably default to "Load" if exists, or "Gen" if not.
         const latest = await findLatestCliBuildForKb(kbName);
         if (latest) {
-            console.log(`\n[CLI] Found existing build for '${kbName}': ${latest}`);
+            logDiagnostic(`\n[CLI] Found existing build for '${kbName}': ${latest}`);
             // If specific options passed (embedded mode), default to Load to avoid blocking
             // Otherwise use interactive prompt
             if (options.targetPath) {
                 useExisting = true;
                 const suffix = latest.replace('data_cli_', '').replace('.js', '');
                 cliOptions.outputPrefix = suffix;
-                console.log(`[CLI] Auto-Loading existing data: ${latest}`);
+                logDiagnostic(`[CLI] Auto-Loading existing data: ${latest}`);
             }
             else {
                 const rl = readline.createInterface({
@@ -1378,7 +1426,7 @@ const startServer = async (options = {}) => {
                     // suffix = kbName_time
                     const suffix = latest.replace('data_cli_', '').replace('.js', '');
                     cliOptions.outputPrefix = suffix;
-                    console.log(`[CLI] Loading existing data: ${latest}`);
+                    logDiagnostic(`[CLI] Loading existing data: ${latest}`);
                 }
             }
         }
@@ -1386,10 +1434,10 @@ const startServer = async (options = {}) => {
             const now = new Date();
             const timeStr = now.toISOString().replace(/[-:T]/g, '').slice(0, 15);
             cliOptions.outputPrefix = `${kbName}_${timeStr}`;
-            console.log(`[CLI] Generating new knowledge graph for: ${cliOptions.targetPath}`);
+            logDiagnostic(`[CLI] Generating new knowledge graph for: ${cliOptions.targetPath}`);
             try {
                 await (0, index_1.buildGraph)(cliOptions);
-                console.log('[CLI] Generation complete.');
+                logDiagnostic('[CLI] Generation complete.');
             }
             catch (e) {
                 console.error('[CLI] Build failed:', e);
@@ -1706,7 +1754,7 @@ const startServer = async (options = {}) => {
                     const restoreKey = `restore:${target}`;
                     const now = Date.now();
                     if (lastRestoreKey === restoreKey && (now - lastRestoreTs) < 3000) {
-                        console.log(`[Cache] Duplicate restore suppressed for ${target}`);
+                        logDiagnostic(`[Cache] Duplicate restore suppressed for ${target}`);
                         res.writeHead(200, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({ success: true, deduped: true }));
                         return;
@@ -2554,7 +2602,7 @@ const startServer = async (options = {}) => {
                 try {
                     const payload = await readJsonBody(req);
                     const { target, maxWorkers, enableGPU, enableGPULayout, memorySavingMode, deepDebug } = payload;
-                    console.log('Received build request for:', target, 'maxWorkers:', maxWorkers, 'enableGPU:', enableGPU, 'enableGPULayout:', enableGPULayout, 'memorySavingMode:', memorySavingMode, 'deepDebug:', deepDebug);
+                    logDiagnostic('Received build request for:', target, 'maxWorkers:', maxWorkers, 'enableGPU:', enableGPU, 'enableGPULayout:', enableGPULayout, 'memorySavingMode:', memorySavingMode, 'deepDebug:', deepDebug);
                     const buildKey = JSON.stringify({
                         target,
                         maxWorkers,
@@ -2566,7 +2614,7 @@ const startServer = async (options = {}) => {
                     // De-duplicate accidental double-submit from frontend.
                     if (activeBuildPromise) {
                         if (activeBuildKey === buildKey) {
-                            console.log('[Build] Duplicate request detected. Waiting for in-flight build.');
+                            logDiagnostic('[Build] Duplicate request detected. Waiting for in-flight build.');
                             await activeBuildPromise;
                             res.writeHead(200, { 'Content-Type': 'application/json' });
                             res.end(JSON.stringify({
@@ -2644,7 +2692,7 @@ const startServer = async (options = {}) => {
                             return;
                         }
                         KB_ROOT = resolvedKbPath;
-                        console.log(`[API] Knowledge Base Root updated to: ${KB_ROOT}`);
+                        logDiagnostic(`[API] Knowledge Base Root updated to: ${KB_ROOT}`);
                         res.writeHead(200, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({ success: true, kbPath: KB_ROOT }));
                     }
@@ -2675,11 +2723,11 @@ const startServer = async (options = {}) => {
             runtimePort = resolvedPort;
             await ensureRuntimeDataDir();
             await writeSidecarRuntimeManifest(resolvedPort);
-            console.log(`[Sidecar] Runtime Manifest: ${SIDECAR_RUNTIME_MANIFEST}`);
-            console.log(`Server running at http://${LOOPBACK_HOST}:${resolvedPort}/`);
-            console.log(`Knowledge Base Root: ${KB_ROOT}`);
-            console.log(`Frontend Root: ${FRONTEND_DIR}`);
-            console.log(`Runtime Data Root: ${RUNTIME_DATA_DIR}`);
+            logDiagnostic(`[Sidecar] Runtime Manifest: ${SIDECAR_RUNTIME_MANIFEST}`);
+            logDiagnostic(`Server running at http://${LOOPBACK_HOST}:${resolvedPort}/`);
+            logDiagnostic(`Knowledge Base Root: ${KB_ROOT}`);
+            logDiagnostic(`Frontend Root: ${FRONTEND_DIR}`);
+            logDiagnostic(`Runtime Data Root: ${RUNTIME_DATA_DIR}`);
             // Initialize PathBridge
             try {
                 pathBridge = new PathBridge_1.PathBridge({
@@ -2687,20 +2735,20 @@ const startServer = async (options = {}) => {
                     host: LOOPBACK_HOST,
                     authToken: AUTH_TOKEN,
                 });
-                console.log(`[Sidecar] PathBridge initialized on ws://${LOOPBACK_HOST}:${PATH_BRIDGE_PORT}`);
+                logDiagnostic(`[Sidecar] PathBridge initialized on ws://${LOOPBACK_HOST}:${PATH_BRIDGE_PORT}`);
             }
             catch (e) {
                 console.error(`[Sidecar] Failed to initialize PathBridge:`, e);
             }
             if (hasCliBuild) {
-                console.log('[CLI] Ready.');
+                logDiagnostic('[CLI] Ready.');
             }
         };
         const attachListenHandlers = (targetPort) => {
             const onError = (error) => {
                 server.off('listening', onListening);
                 if (error?.code === 'EADDRINUSE' && allowEphemeralFallback && targetPort === finalPort) {
-                    console.warn(`[Sidecar] Port ${finalPort} is already in use. Retrying with an ephemeral loopback port.`);
+                    warnDiagnostic(`[Sidecar] Port ${finalPort} is already in use. Retrying with an ephemeral loopback port.`);
                     attachListenHandlers(0);
                     return;
                 }

package/dist/src/server.port.fallback.contract.test.js

@@ -144,6 +144,12 @@ describe('server ephemeral port fallback policy contract', () => {
     let tempProject = null;
     let envRestorers = [];
     let originalArgv = [];
+    test('server installs stdio broken-pipe guards before emitting fallback logs', () => {
+        const serverSource = fs.readFileSync(path.join(__dirname, 'server.ts'), 'utf8');
+        expect(serverSource).toContain('installBrokenPipeGuard(process.stdout');
+        expect(serverSource).toContain('installBrokenPipeGuard(process.stderr');
+        expect(serverSource).toContain("error?.code === 'EPIPE'");
+    });
     beforeEach(() => {
         tempProject = makeTempProject('noteconnection-port-policy');
         const projectRoot = path.join(tempProject.root, 'project');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "noteconnection",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "description": "Hierarchical Knowledge Graph Visualization System",
   "main": "dist/src/server.js",
   "bin": {