noteconnection 1.8.0 → 1.9.0

package/dist/src/server.js

@@ -39,12 +39,14 @@ exports.executeNotemdCliCommand = executeNotemdCliCommand;
 const http = __importStar(require("http"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const os = __importStar(require("os"));
 const net = __importStar(require("net"));
 const readline = __importStar(require("readline"));
 const events_1 = require("events");
 const child_process_1 = require("child_process");
 const index_1 = require("./index");
 const CrashLogger_1 = require("./backend/utils/CrashLogger");
+const ResourceIdentity_1 = require("./backend/ResourceIdentity");
 const PathBridge_1 = require("./core/PathBridge");
 const GraphMetrics_1 = require("./backend/GraphMetrics");
 const LayoutEngine_1 = require("./backend/algorithms/LayoutEngine");
@@ -54,11 +56,18 @@ 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");
-const providerTemplates_1 = require("./notemd/providerTemplates");
 const MarkdownGateway_1 = require("./markdown/MarkdownGateway");
 const learning_1 = require("./learning");
+const requestNormalization_1 = require("./learning/requestNormalization");
+const agentConversationSerialization_1 = require("./learning/agentConversationSerialization");
+const agentConversationExecution_1 = require("./learning/agentConversationExecution");
+const agentResponseBudget_1 = require("./learning/agentResponseBudget");
+const SseResponseWriter_1 = require("./middleware/SseResponseWriter");
+const mobileAnswerProjection_1 = require("./learning/mobileAnswerProjection");
+const workspaceHydration_1 = require("./learning/workspaceHydration");
 const routes_1 = require("./routes");
 const runtimeRunbookRouteOps_1 = require("./routes/runtimeRunbookRouteOps");
+const auth_1 = require("./middleware/auth");
 const domains_1 = require("./learning/domains");
 function installBrokenPipeGuard(stream) {
     if (!stream || stream.__noteConnectionBrokenPipeGuardInstalled) {
@@ -184,6 +193,9 @@ const AGENT_WORKSPACE_DIAGNOSTICS_TRIAGE_TOP_LIMIT = 5;
 const AGENT_WORKSPACE_DIAGNOSTICS_TRIAGE_TOP_LIMIT_MIN = 1;
 const AGENT_WORKSPACE_DIAGNOSTICS_TRIAGE_TOP_LIMIT_MAX = 10;
 const REQUEST_BODY_SPOOL_DIR = path.join(runtimePaths.projectRoot, 'tmp', 'request-bodies');
+const KNOWLEDGE_WORKSPACE_TITLE_PREVIEW_BYTES = 16 * 1024;
+const KNOWLEDGE_WORKSPACE_LARGE_TARGET_FILE_THRESHOLD = 100;
+const KNOWLEDGE_WORKSPACE_MAX_SELECTIVE_HYDRATION_FILES = 32;
 let KB_ROOT = runtimePaths.kbRoot;
 let activeBuildKey = null;
 let activeBuildPromise = null;
@@ -191,7 +203,7 @@ let ACTIVE_GRAPH_TARGET = 'ALL_FOLDERS';
 let lastRestoreKey = null;
 let lastRestoreTs = 0;
 const activeKnowledgeWorkspaceSyncs = new Map();
-const SIDECAR_RUNTIME_MANIFEST = path.join(runtimePaths.projectRoot, 'tmp', 'active-sidecar-runtime.json');
+const SIDECAR_RUNTIME_MANIFEST = runtimePaths.runtimeManifestPath;
 const notemdService = new notemd_1.NotemdService();
 const notemdLlmClient = new notemd_1.LlmProviderClient();
 const API_REQUEST_TRACE_MAX_RECORDS = 400;
@@ -4808,12 +4820,22 @@ const knowledgeGraphStore = (0, learning_1.createKnowledgeGraphStore)({
     backend: KNOWLEDGE_GRAPH_STORE_BACKEND,
     filePath: KNOWLEDGE_GRAPH_STORE_PATH,
     graphDbAdapter: KNOWLEDGE_GRAPHDB_ADAPTER,
+    graphDbRequestedProvider: KNOWLEDGE_GRAPHDB_ADAPTER_PROVIDER,
     graphDbFallbackEnabled: KNOWLEDGE_GRAPHDB_FALLBACK_ENABLED,
     graphDbOperationMode: KNOWLEDGE_GRAPHDB_OPERATION_MODE,
 });
 const defaultLocalTutorAdapter = createNotemdTutorAdapter('local');
 const defaultCloudTutorAdapter = createNotemdTutorAdapter('cloud');
+const SERVER_RESPONSE_LOW_MEMORY_BYTES = 4 * 1024 ** 3;
+const SERVER_RESPONSE_HIGH_MEMORY_BYTES = 8 * 1024 ** 3;
+const serverResponseMemoryBytes = os.totalmem();
+const SERVER_RESPONSE_BUDGET_CAPABILITY = {
+    memoryClass: serverResponseMemoryBytes < SERVER_RESPONSE_LOW_MEMORY_BYTES ? 'low'
+        : serverResponseMemoryBytes >= SERVER_RESPONSE_HIGH_MEMORY_BYTES ? 'high' : 'standard',
+    workload: 'max',
+};
 const knowledgeLearningPlatform = (0, learning_1.createKnowledgeLearningPlatform)({
+    responseBudgetHostCapability: SERVER_RESPONSE_BUDGET_CAPABILITY,
     store: knowledgeGraphStore,
     learningQualityThresholds: LEARNING_QUALITY_THRESHOLDS,
     studySessionPlanQualityAdaptiveThresholdsEnabled: STUDY_SESSION_PLAN_QUALITY_ADAPTIVE_THRESHOLDS_ENABLED,
@@ -4964,7 +4986,6 @@ const markdownGateway = new MarkdownGateway_1.MarkdownGateway({
         warn: (...args) => warnDiagnostic(...args),
     },
 });
-const NOTEMD_ACTIVE_OPERATIONS = new Map();
 const AGENT_CONVERSATION_TURN_CACHE = new Map();
 const AGENT_CONVERSATION_TURN_CACHE_COUNTERS = {
     cacheHitCount: 0,
@@ -6557,19 +6578,6 @@ function getRawRequestPathname(rawUrl) {
     }
     return requestTarget || '/';
 }
-function extractRequestToken(req) {
-    const headerToken = typeof req.headers['x-noteconnection-token'] === 'string'
-        ? req.headers['x-noteconnection-token'].trim()
-        : '';
-    if (headerToken) {
-        return headerToken;
-    }
-    const authHeader = typeof req.headers.authorization === 'string' ? req.headers.authorization.trim() : '';
-    if (authHeader.toLowerCase().startsWith('bearer ')) {
-        return authHeader.slice(7).trim();
-    }
-    return '';
-}
 function createRequestId() {
     return `req-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -6597,7 +6605,7 @@ function isAuthorizedRequest(req) {
     if (!AUTH_TOKEN || !isProtectedRequest(req)) {
         return true;
     }
-    return extractRequestToken(req) === AUTH_TOKEN;
+    return (0, auth_1.isRequestTokenAuthorized)(req, AUTH_TOKEN);
 }
 function isGeneratedGraphAsset(filename) {
     return (filename === 'data.js' ||
@@ -6907,6 +6915,18 @@ function classifyApiInputValidationError(error) {
     return null;
 }
 function writeApiErrorResponse(res, error, options) {
+    if (res.destroyed || res.writableEnded)
+        return;
+    if (res.headersSent) {
+        res.destroy();
+        return;
+    }
+    if (error instanceof agentConversationExecution_1.AgentConversationExecutionError || error instanceof agentConversationSerialization_1.AgentConversationSerializationError) {
+        setApiErrorCodeHeader(res, error.code);
+        res.writeHead(error.statusCode, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(createApiErrorEnvelope({ error: error.message, errorCode: error.code, requestId: options.requestId })));
+        return;
+    }
     if (writeBodyParseErrorResponse(res, error, { requestId: options.requestId })) {
         return;
     }
@@ -7139,22 +7159,6 @@ function normalizeKnowledgeQueryRequestPayload(payload) {
             : undefined,
     };
 }
-function normalizeAgentConversationRequestPayload(payload) {
-    const record = isObjectRecord(payload) ? payload : {};
-    const topKValue = parsePositiveIntegerValue(readFirstPresentValue(record, ['topK', 'k', 'limit']));
-    const normalizedQueryRequest = normalizeKnowledgeQueryRequestPayload(payload);
-    return {
-        userId: String(readFirstPresentValue(record, ['userId', 'user_id', 'learnerId']) || '').trim(),
-        sessionId: readFirstNonEmptyString(record, ['sessionId', 'session_id']),
-        activeTarget: readFirstNonEmptyString(record, ['activeTarget', 'active_target', 'target']),
-        message: readFirstNonEmptyString(record, ['message', 'prompt', 'query', 'q', 'text']) || '',
-        topK: topKValue > 0 ? topKValue : undefined,
-        asOf: readFirstNonEmptyString(record, ['asOf', 'as_of', 'timestamp', 'now']),
-        persistMemory: readFirstPresentValue(record, ['persistMemory', 'persist_memory']) !== false,
-        memoryNamespace: readFirstNonEmptyString(record, ['memoryNamespace', 'memory_namespace']),
-        scope: normalizedQueryRequest.scope,
-    };
-}
 function requestAcceptsEventStream(req) {
     const acceptHeader = String(req.headers.accept || '').toLowerCase();
     return acceptHeader.includes('text/event-stream');
@@ -7199,11 +7203,43 @@ function normalizeAgentConversationTopK(value) {
     return Math.max(1, Math.floor(numeric));
 }
 function buildAgentConversationRequestFingerprint(requestPayload) {
+    const scope = requestPayload.scope;
+    const normalizedScope = scope
+        ? {
+            workspaceId: String(scope.workspaceId || '').trim(),
+            corpusId: String(scope.corpusId || '').trim(),
+            documentIds: Array.from(new Set(scope.documentIds || [])).sort(),
+            atomIds: Array.from(new Set(scope.atomIds || [])).sort(),
+            sourcePathPrefixes: Array.from(new Set(scope.sourcePathPrefixes || [])).sort(),
+            languages: Array.from(new Set(scope.languages || [])).sort(),
+        }
+        : null;
     return JSON.stringify({
         userId: String(requestPayload.userId || '').trim(),
+        sessionId: String(requestPayload.sessionId || '').trim(),
+        activeTarget: String(requestPayload.activeTarget || '').trim(),
         message: String(requestPayload.message || '').trim(),
+        answerLanguage: String(requestPayload.answerLanguage || 'auto').trim(),
+        responseMode: String(requestPayload.responseMode || 'slim').trim(),
+        responseBudgetMode: String(requestPayload.responseBudgetMode || 'adaptive').trim(),
+        responseBudgetCapability: requestPayload.responseBudgetCapability
+            ? {
+                memoryClass: String(requestPayload.responseBudgetCapability.memoryClass || '').trim(),
+                workload: String(requestPayload.responseBudgetCapability.workload || '').trim(),
+                maxReportCharsHint: Number.isFinite(Number(requestPayload.responseBudgetCapability.maxReportCharsHint))
+                    ? Math.floor(Number(requestPayload.responseBudgetCapability.maxReportCharsHint))
+                    : null,
+                maxSerializedBytesHint: Number.isFinite(Number(requestPayload.responseBudgetCapability.maxSerializedBytesHint))
+                    ? Math.floor(Number(requestPayload.responseBudgetCapability.maxSerializedBytesHint))
+                    : null,
+            }
+            : null,
+        responseProfile: String(requestPayload.responseProfile || 'default').trim(),
         topK: normalizeAgentConversationTopK(requestPayload.topK),
         asOf: String(requestPayload.asOf || '').trim(),
+        persistMemory: requestPayload.persistMemory !== false,
+        memoryNamespace: String(requestPayload.memoryNamespace || '').trim(),
+        scope: normalizedScope,
     });
 }
 function pruneAgentConversationTurnCache(nowMs = Date.now()) {
@@ -7253,8 +7289,13 @@ function getOrCreateAgentConversationTurnCacheRecord(turnId, requestFingerprint)
         return existing;
     }
     AGENT_CONVERSATION_TURN_CACHE_COUNTERS.cacheMissCount += 1;
+    const runningTurns = Array.from(AGENT_CONVERSATION_TURN_CACHE.values()).filter(record => record.status === 'running').length;
+    if (runningTurns >= agentConversationExecution_1.DEFAULT_AGENT_CONVERSATION_EXECUTION_POLICY.maxPendingTurns)
+        throw new agentConversationExecution_1.AgentConversationExecutionError('runtime_turn_capacity');
     const nowMs = Date.now();
     const record = {
+        controller: new AbortController(),
+        consumers: 0,
         turnId,
         requestFingerprint,
         createdAtMs: nowMs,
@@ -7266,6 +7307,31 @@ function getOrCreateAgentConversationTurnCacheRecord(turnId, requestFingerprint)
     pruneAgentConversationTurnCache(nowMs);
     return record;
 }
+function attachAgentConversationClient(record, req, res) {
+    record.consumers++;
+    let attached = true;
+    const release = () => {
+        if (!attached)
+            return;
+        attached = false;
+        record.consumers--;
+        req.removeListener('aborted', release);
+        res.removeListener('close', release);
+        if (record.status === 'running' && record.consumers === 0) {
+            record.controller.abort(new agentConversationExecution_1.AgentConversationExecutionError('runtime_cancelled'));
+            if (!record.inFlight) {
+                record.status = 'failed';
+                record.failure = { error: 'runtime_cancelled', errorCode: 'runtime_cancelled' };
+                appendAgentConversationTurnCacheEvent(record, { type: 'turn_failed', turnId: record.turnId, emittedAt: new Date().toISOString(), ...record.failure });
+            }
+        }
+    };
+    req.once('aborted', release);
+    res.once('close', release);
+    if (req.aborted || res.destroyed)
+        release();
+    return release;
+}
 function appendAgentConversationTurnCacheEvent(record, event) {
     if (record.events.length >= AGENT_CONVERSATION_TURN_CACHE_MAX_EVENTS_PER_TURN) {
         record.events.shift();
@@ -7273,12 +7339,58 @@ function appendAgentConversationTurnCacheEvent(record, event) {
     record.events.push(event);
     record.updatedAtMs = Date.now();
 }
-function replayAgentConversationTurnEvents(res, record) {
+function replayAgentConversationTurnEvents(res, record, requestPayload) {
     AGENT_CONVERSATION_TURN_CACHE_COUNTERS.replayResponseCount += 1;
     AGENT_CONVERSATION_TURN_CACHE_COUNTERS.replayedEventCount += record.events.length;
     for (const event of record.events) {
-        writeSseEvent(res, event.type, event);
+        writeSseEvent(res, event.type, projectAgentConversationTurnEvent(event, requestPayload));
+    }
+}
+function buildMobileAgentConversationResponse(result) {
+    const projection = result.mobileProjection || (0, mobileAnswerProjection_1.projectAnswerForMobile)(result);
+    const summary = result.summary || {
+        generatedAt: new Date().toISOString(),
+        topK: 0,
+        queryEvidenceCoverageRatioPct: 0,
+    };
+    return {
+        userId: result.userId,
+        sessionId: result.sessionId,
+        assistantMessage: projection.directAnswer,
+        answer: projection.directAnswer,
+        message: projection.directAnswer,
+        responseMode: 'slim',
+        responseProfile: 'mobile_compact',
+        mobileProjection: projection,
+        assistantBlocks: [],
+        knowledgePoints: [],
+        citations: [],
+        recalledMemories: [],
+        memoryActions: [],
+        summary: {
+            generatedAt: summary.generatedAt,
+            topK: summary.topK,
+            returnedKnowledgePoints: projection.route.length,
+            returnedCitations: projection.citations.length,
+            recalledMemoryCount: 0,
+            appliedMemoryCount: 0,
+            queryEvidenceCoverageRatioPct: summary.queryEvidenceCoverageRatioPct,
+            responseBudgetMode: 'adaptive',
+            responseBudgetTier: 'standard',
+            responseTruncated: false,
+        },
+    };
+}
+function projectAgentConversationTurnEvent(event, requestPayload) {
+    if (requestPayload?.responseProfile !== 'mobile_compact'
+        || event.type !== 'turn_completed'
+        || !event.result) {
+        return event;
     }
+    return {
+        ...event,
+        result: buildMobileAgentConversationResponse(event.result),
+    };
 }
 function buildAgentConversationInitialTurnEvents(params) {
     return [
@@ -7289,6 +7401,10 @@ function buildAgentConversationInitialTurnEvents(params) {
             request: {
                 userId: params.requestPayload.userId,
                 topK: params.topK,
+                responseMode: params.requestPayload.responseMode === 'full' ? 'full' : 'slim',
+                responseBudgetMode: params.requestPayload.responseBudgetMode === 'unbounded'
+                    ? 'unbounded'
+                    : 'adaptive',
             },
         },
         {
@@ -7341,7 +7457,12 @@ async function ensureAgentConversationTurnExecution(record, requestPayload, opti
     const emit = (event) => {
         appendAgentConversationTurnCacheEvent(record, event);
         if (emitLiveEvent) {
-            emitLiveEvent(event);
+            try {
+                emitLiveEvent(event);
+            }
+            catch (error) {
+                console.warn('[SSE] Live delivery ended:', error.message);
+            }
         }
     };
     const nowIso = () => new Date().toISOString();
@@ -7355,51 +7476,64 @@ async function ensureAgentConversationTurnExecution(record, requestPayload, opti
             writeLiveEvent: emitLiveEvent,
         });
         try {
-            const hydration = await ensureLearningWorkspaceHydratedForConversationRequest(requestPayload);
-            emit({
-                type: 'capability_result',
-                turnId: record.turnId,
-                emittedAt: nowIso(),
-                stage: 'workspace_readiness_gate',
-                summary: {
-                    hydrated: hydration.hydrated,
-                    target: hydration.target,
-                    reason: hydration.reason,
-                    workspaceId: hydration.scope?.workspaceId || null,
-                    corpusId: hydration.scope?.corpusId || null,
-                },
-            });
-            const result = await knowledgeLearningPlatform.runAgentConversation(requestPayload);
-            record.status = 'completed';
-            record.result = result;
-            record.failure = undefined;
-            AGENT_CONVERSATION_TURN_CACHE_COUNTERS.executionSuccessCount += 1;
-            emit({
-                type: 'capability_result',
-                turnId: record.turnId,
-                emittedAt: nowIso(),
-                stage: 'query_local_knowledge',
-                summary: {
-                    returnedKnowledgePoints: Number(result.summary.returnedKnowledgePoints || 0),
-                    queryEvidenceCoverageRatioPct: Number(result.summary.queryEvidenceCoverageRatioPct || 0),
-                },
-            });
-            emit({
-                type: 'turn_completed',
-                turnId: record.turnId,
-                emittedAt: nowIso(),
-                result,
+            await agentConversationExecution_1.AgentConversationExecution.run({
+                budget: (0, agentResponseBudget_1.resolveHostedAgentResponseBudget)({
+                    responseMode: requestPayload.responseMode,
+                    responseBudgetMode: requestPayload.responseBudgetMode,
+                    capability: requestPayload.responseBudgetCapability,
+                    mobile: requestPayload.responseProfile === 'mobile_compact',
+                }, SERVER_RESPONSE_BUDGET_CAPABILITY),
+                policy: agentConversationExecution_1.DEFAULT_AGENT_CONVERSATION_EXECUTION_POLICY,
+                signal: record.controller.signal,
+            }, async () => {
+                const hydration = await ensureLearningWorkspaceHydratedForConversationRequest(requestPayload);
+                emit({
+                    type: 'capability_result',
+                    turnId: record.turnId,
+                    emittedAt: nowIso(),
+                    stage: 'workspace_readiness_gate',
+                    summary: {
+                        hydrated: hydration.hydrated,
+                        target: hydration.target,
+                        reason: hydration.reason,
+                        workspaceId: hydration.scope?.workspaceId || null,
+                        corpusId: hydration.scope?.corpusId || null,
+                    },
+                });
+                const rawResult = await knowledgeLearningPlatform.runAgentConversation(requestPayload, record.controller.signal);
+                const result = (0, agentConversationSerialization_1.serializeAgentConversationResponse)(rawResult).result;
+                record.status = 'completed';
+                record.result = result;
+                record.failure = undefined;
+                AGENT_CONVERSATION_TURN_CACHE_COUNTERS.executionSuccessCount += 1;
+                emit({
+                    type: 'capability_result',
+                    turnId: record.turnId,
+                    emittedAt: nowIso(),
+                    stage: 'query_local_knowledge',
+                    summary: {
+                        returnedKnowledgePoints: Number(result.summary.returnedKnowledgePoints || 0),
+                        queryEvidenceCoverageRatioPct: Number(result.summary.queryEvidenceCoverageRatioPct || 0),
+                    },
+                });
+                emit({
+                    type: 'turn_completed',
+                    turnId: record.turnId,
+                    emittedAt: nowIso(),
+                    result,
+                });
             });
         }
         catch (executionError) {
             const validation = classifyApiInputValidationError(executionError);
+            const runtimeError = executionError instanceof agentConversationExecution_1.AgentConversationExecutionError || executionError instanceof agentConversationSerialization_1.AgentConversationSerializationError;
             const failure = {
                 error: validation?.error || String(executionError?.message
                     || executionError
                     || 'unknown_error'),
-                errorCode: validation?.errorCode || 'internal_error',
+                errorCode: runtimeError ? executionError.code : validation?.errorCode || 'internal_error',
             };
-            if (!validation) {
+            if (!validation && !runtimeError) {
                 console.error(executionError);
                 CrashLogger_1.CrashLogger.log(executionError, 'API:POST /api/knowledge/conversation [turn-cache]');
             }
@@ -7436,6 +7570,10 @@ function throwAgentConversationCachedFailure(failureLike) {
         error: 'conversation_turn_failed',
         errorCode: 'internal_error',
     };
+    if (failure.errorCode === 'runtime_serialized_bytes_limit')
+        throw new agentConversationSerialization_1.AgentConversationSerializationError();
+    if (failure.errorCode?.startsWith('runtime_'))
+        throw new agentConversationExecution_1.AgentConversationExecutionError(failure.errorCode);
     if (failure.errorCode && failure.errorCode !== 'internal_error') {
         throw new learning_1.InvalidRequestError(failure.error, {
             errorCode: failure.errorCode,
@@ -7620,12 +7758,18 @@ function normalizeKnowledgeDocumentInputPayload(payload) {
         : String(contentRaw ?? '');
     const language = readFirstNonEmptyString(record, ['language', 'lang', 'locale']);
     const updatedAt = readFirstNonEmptyString(record, ['updatedAt', 'updated_at', 'timestamp', 'now']);
+    const sourceUri = readFirstNonEmptyString(record, ['sourceUri', 'source_uri', 'uri']);
+    const revision = readFirstNonEmptyString(record, ['revision', 'sourceRevision', 'source_revision']);
+    const identityAliases = normalizeStringArrayValue(readFirstPresentValue(record, ['identityAliases', 'identity_aliases', 'aliases']));
     if (!documentId && !sourcePath && !content.trim()) {
         return null;
     }
     return {
         documentId,
         sourcePath: sourcePath || '',
+        sourceUri,
+        revision,
+        identityAliases: identityAliases.length > 0 ? identityAliases : undefined,
         content,
         language,
         updatedAt,
@@ -7642,12 +7786,16 @@ function normalizeKnowledgeDocumentDeletePayload(payload) {
         'filepath',
         'file',
     ]);
-    if (!documentId && !sourcePath) {
+    const sourceUri = readFirstNonEmptyString(record, ['sourceUri', 'source_uri', 'uri']);
+    const identityAliases = normalizeStringArrayValue(readFirstPresentValue(record, ['identityAliases', 'identity_aliases', 'aliases']));
+    if (!documentId && !sourcePath && !sourceUri && identityAliases.length === 0) {
         return null;
     }
     return {
         documentId,
         sourcePath,
+        sourceUri,
+        identityAliases: identityAliases.length > 0 ? identityAliases : undefined,
     };
 }
 function normalizeKnowledgeIngestOperationPayload(payload) {
@@ -7656,6 +7804,33 @@ function normalizeKnowledgeIngestOperationPayload(payload) {
     const normalizedOp = String(opRaw || '').trim().toLowerCase();
     const documentRaw = readFirstPresentValue(record, ['document', 'payload', 'item']);
     const operationPayload = typeof documentRaw !== 'undefined' ? documentRaw : payload;
+    if (normalizedOp === 'move'
+        || normalizedOp === 'rename') {
+        const moveRecord = isObjectRecord(operationPayload) ? operationPayload : {};
+        const toSourcePath = readFirstNonEmptyString(moveRecord, [
+            'toSourcePath',
+            'to_source_path',
+            'destinationPath',
+            'destination_path',
+        ]);
+        if (!toSourcePath) {
+            return null;
+        }
+        return {
+            op: 'move',
+            document: {
+                documentId: readFirstNonEmptyString(moveRecord, ['documentId', 'docId', 'id']),
+                fromSourcePath: readFirstNonEmptyString(moveRecord, ['fromSourcePath', 'from_source_path', 'sourcePath', 'source_path']),
+                fromSourceUri: readFirstNonEmptyString(moveRecord, ['fromSourceUri', 'from_source_uri', 'sourceUri', 'source_uri']),
+                fromIdentityAliases: normalizeStringArrayValue(readFirstPresentValue(moveRecord, ['fromIdentityAliases', 'from_identity_aliases', 'fromAliases'])),
+                toSourcePath,
+                toSourceUri: readFirstNonEmptyString(moveRecord, ['toSourceUri', 'to_source_uri', 'destinationUri', 'destination_uri']),
+                toIdentityAliases: normalizeStringArrayValue(readFirstPresentValue(moveRecord, ['toIdentityAliases', 'to_identity_aliases', 'aliases'])),
+                revision: readFirstNonEmptyString(moveRecord, ['revision', 'sourceRevision', 'source_revision']),
+                updatedAt: readFirstNonEmptyString(moveRecord, ['updatedAt', 'updated_at', 'timestamp', 'now']),
+            },
+        };
+    }
     if (normalizedOp === 'delete'
         || normalizedOp === 'remove'
         || normalizedOp === 'del') {
@@ -8848,56 +9023,6 @@ async function persistNotemdSettings(settingsLike) {
     cachedNotemdSettings = cloneNotemdSettings(normalized);
     return cloneNotemdSettings(normalized);
 }
-function extractNotemdWorkspaceState(settings) {
-    return {
-        filePath: String(settings.workspaceFilePath || '').trim(),
-        folderPath: String(settings.workspaceFolderPath || '').trim(),
-        outputFilePath: String(settings.workspaceOutputFilePath || '').trim(),
-        outputFolderPath: String(settings.workspaceOutputFolderPath || '').trim(),
-    };
-}
-function normalizeWorkspaceField(source, keys, fallback) {
-    for (const key of keys) {
-        if (!Object.prototype.hasOwnProperty.call(source, key)) {
-            continue;
-        }
-        return String(source[key] || '').trim();
-    }
-    return fallback;
-}
-function applyWorkspacePatchToSettings(settings, workspacePatch) {
-    const next = cloneNotemdSettings(settings);
-    if (!isObjectRecord(workspacePatch)) {
-        return next;
-    }
-    next.workspaceFilePath = normalizeWorkspaceField(workspacePatch, ['filePath', 'file_path', 'workspaceFilePath', 'workspace_file_path'], next.workspaceFilePath);
-    next.workspaceFolderPath = normalizeWorkspaceField(workspacePatch, ['folderPath', 'folder_path', 'workspaceFolderPath', 'workspace_folder_path'], next.workspaceFolderPath);
-    next.workspaceOutputFilePath = normalizeWorkspaceField(workspacePatch, ['outputFilePath', 'output_file_path', 'workspaceOutputFilePath', 'workspace_output_file_path'], next.workspaceOutputFilePath);
-    next.workspaceOutputFolderPath = normalizeWorkspaceField(workspacePatch, ['outputFolderPath', 'output_folder_path', 'workspaceOutputFolderPath', 'workspace_output_folder_path'], next.workspaceOutputFolderPath);
-    return next;
-}
-async function persistNotemdWorkspacePatch(workspacePatch) {
-    const settings = await loadNotemdSettings();
-    const nextSettings = applyWorkspacePatchToSettings(settings, workspacePatch);
-    const persisted = await persistNotemdSettings(nextSettings);
-    return extractNotemdWorkspaceState(persisted);
-}
-async function ensureNotemdProviderTemplatesPersisted() {
-    const appConfig = await (0, AppConfigToml_1.loadAppConfigToml)();
-    const currentNotemdSection = isObjectRecord(appConfig.notemd) ? appConfig.notemd : {};
-    const nextNotemdSection = (0, providerTemplates_1.mergeProviderTemplatesIntoNotemdSection)(currentNotemdSection);
-    const persisted = JSON.stringify(currentNotemdSection) !== JSON.stringify(nextNotemdSection);
-    if (persisted) {
-        await (0, AppConfigToml_1.saveAppConfigToml)({
-            ...appConfig,
-            notemd: nextNotemdSection,
-        });
-    }
-    return {
-        configPath: (0, AppConfigToml_1.resolveAppConfigPath)(),
-        persisted,
-    };
-}
 function clonePathModeSettings(settings) {
     return JSON.parse(JSON.stringify(settings));
 }
@@ -8942,74 +9067,25 @@ async function persistFrontendSettings(settingsLike) {
     cachedFrontendSettings = cloneFrontendSettings(persisted);
     return cloneFrontendSettings(persisted);
 }
-function generateNotemdOperationId() {
-    return `notemd-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`;
-}
-function createNotemdOperation(operationIdCandidate) {
-    const requestedId = String(operationIdCandidate || '').trim();
-    const operationId = requestedId || generateNotemdOperationId();
-    const state = {
-        id: operationId,
-        controller: new AbortController(),
-        status: 'running',
-        createdAt: Date.now(),
-        updatedAt: Date.now(),
-        logs: [],
-    };
-    NOTEMD_ACTIVE_OPERATIONS.set(operationId, state);
-    return state;
-}
-function finalizeNotemdOperation(state, status) {
-    state.status = status;
-    state.updatedAt = Date.now();
-    setTimeout(() => {
-        const current = NOTEMD_ACTIVE_OPERATIONS.get(state.id);
-        if (current === state && current.status !== 'running') {
-            NOTEMD_ACTIVE_OPERATIONS.delete(state.id);
-        }
-    }, 60000);
-}
+const sseResponseWriters = new WeakMap();
 function writeSseEvent(res, eventType, payload) {
     if (res.writableEnded || res.destroyed) {
         return;
     }
-    try {
-        res.write(`event: ${eventType}\n`);
-        res.write(`data: ${JSON.stringify(payload)}\n\n`);
-    }
-    catch (_error) {
-        // Ignore stream write failures when client disconnected mid-stream.
+    let writer = sseResponseWriters.get(res);
+    if (!writer) {
+        writer = new SseResponseWriter_1.SseResponseWriter(res);
+        sseResponseWriters.set(res, writer);
     }
+    const serialized = (0, agentConversationSerialization_1.serializeAgentConversationTurnEvent)(eventType, payload);
+    writer.write(`event: ${eventType}\ndata: ${serialized.json}\n\n`);
 }
-function createNotemdReporter(state, res) {
-    return {
-        report: (eventLike) => {
-            const event = {
-                ...eventLike,
-                operationId: state.id,
-                timestamp: Date.now(),
-            };
-            state.logs.push(event);
-            state.updatedAt = event.timestamp;
-            if (res) {
-                writeSseEvent(res, event.type, event);
-            }
-        },
-        isCancelled: () => state.controller.signal.aborted,
-    };
-}
-function shouldStreamNotemdResponse(req) {
-    const acceptHeader = typeof req.headers.accept === 'string' ? req.headers.accept : '';
-    if (acceptHeader.includes('text/event-stream')) {
-        return true;
-    }
-    try {
-        const urlObj = new URL(req.url || '/', `http://${LOOPBACK_HOST}:${PORT}`);
-        return urlObj.searchParams.get('stream') === '1';
-    }
-    catch (_error) {
-        return false;
-    }
+async function finishSseResponse(res) {
+    const writer = sseResponseWriters.get(res);
+    if (writer)
+        await writer.finish();
+    else
+        res.end();
 }
 async function resolveNearestExistingAncestor(candidatePath) {
     let current = path.resolve(candidatePath);
@@ -9317,7 +9393,8 @@ async function writeSidecarRuntimeManifest(finalPort) {
             runtimeDataDir: RUNTIME_DATA_DIR,
             generatedAt: new Date().toISOString(),
             pid: process.pid,
-        }, null, 2), 'utf8');
+        }, null, 2), { encoding: 'utf8', mode: 0o600 });
+        await fs.promises.chmod(SIDECAR_RUNTIME_MANIFEST, 0o600);
     }
     catch (error) {
         warnDiagnostic('[Sidecar] Failed to write runtime manifest:', error);
@@ -9518,15 +9595,21 @@ function resolveKnowledgeWorkspaceTargetFromConversationRequest(requestPayload)
     return activeTarget;
 }
 function buildKnowledgeDocumentPayloadFromFile(file) {
-    const relativePath = path.relative(KB_ROOT, file.filepath).replace(/\\/g, '/');
-    const sourcePath = `Knowledge_Base/${relativePath}`.replace(/\/{2,}/g, '/');
+    const sourcePath = buildKnowledgeSourcePathFromFilePath(file.filepath);
     const language = /[\u4e00-\u9fff]/.test(file.content) ? 'zh' : 'en';
     return {
         sourcePath,
+        sourceUri: file.sourceUri,
+        revision: file.revision,
+        identityAliases: file.identityAliases,
         content: file.content,
         language,
     };
 }
+function buildKnowledgeSourcePathFromFilePath(filePath) {
+    const relativePath = path.relative(KB_ROOT, filePath).replace(/\\/g, '/');
+    return `Knowledge_Base/${relativePath}`.replace(/\/{2,}/g, '/');
+}
 async function collectMarkdownFilePaths(targetPath) {
     const collected = [];
     const scan = async (currentPath) => {
@@ -9554,26 +9637,7 @@ function normalizeKnowledgeTargetLookupQuery(value) {
         .toLowerCase();
 }
 function deriveKnowledgeTargetLookupQueries(query) {
-    const normalized = normalizeKnowledgeTargetLookupQuery(query);
-    if (!normalized) {
-        return [];
-    }
-    const candidates = new Set([normalized]);
-    const stripped = normalized
-        .replace(/^(what is|what are|define|explain|tell me about|what's)\s+/i, '')
-        .replace(/^(什么是|解释一下|介绍一下|请解释|请介绍)\s*/i, '')
-        .trim();
-    if (stripped) {
-        candidates.add(stripped);
-        candidates.add(stripped.replace(/\s+/g, ''));
-    }
-    if (normalized.includes('water glass') || stripped === 'waterglass') {
-        candidates.add('water glass');
-        candidates.add('waterglass');
-        candidates.add('水玻璃');
-        candidates.add('水杯');
-    }
-    return Array.from(candidates.values()).filter(Boolean);
+    return (0, workspaceHydration_1.deriveKnowledgeTargetLookupQueries)(query);
 }
 async function findKnowledgeFilesByTitleLikeQueries(targetPath, titleLikeQueries) {
     if (titleLikeQueries.length <= 0) {
@@ -9588,16 +9652,50 @@ async function findKnowledgeFilesByTitleLikeQueries(targetPath, titleLikeQueries
     if (exactMatches.length > 0) {
         return exactMatches;
     }
-    return markdownFiles.filter((filePath) => {
+    const fuzzyBasenameMatches = markdownFiles.filter((filePath) => {
         const normalizedBaseName = normalizeKnowledgeTargetLookupQuery(path.basename(filePath, path.extname(filePath)));
         return normalizedQueries.some((query) => normalizedBaseName.includes(query));
     });
+    if (fuzzyBasenameMatches.length > 0) {
+        return fuzzyBasenameMatches;
+    }
+    const previewMatches = [];
+    for (const filePath of markdownFiles) {
+        const preview = await readMarkdownTitlePreview(filePath);
+        if ((0, workspaceHydration_1.markdownPreviewMatchesTitleLikeQueries)({
+            sourcePath: buildKnowledgeSourcePathFromFilePath(filePath),
+            preview,
+            titleLikeQueries: normalizedQueries,
+        })) {
+            previewMatches.push(filePath);
+        }
+    }
+    return previewMatches;
+}
+async function readMarkdownTitlePreview(filePath) {
+    const handle = await fs.promises.open(filePath, 'r');
+    try {
+        const buffer = Buffer.allocUnsafe(KNOWLEDGE_WORKSPACE_TITLE_PREVIEW_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        return buffer.subarray(0, bytesRead).toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
 }
 async function buildKnowledgeDocumentPayloadsFromPaths(filePaths) {
     const documents = [];
     for (const filePath of filePaths) {
-        const content = await fs.promises.readFile(filePath, 'utf8');
-        documents.push(buildKnowledgeDocumentPayloadFromFile({ filepath: filePath, content }));
+        const execution = agentConversationExecution_1.AgentConversationExecution.current();
+        const content = execution ? await execution.readSourceFile(filePath) : await fs.promises.readFile(filePath, 'utf8');
+        if (content === null)
+            continue;
+        const identity = (0, ResourceIdentity_1.createResourceIdentity)(path.relative(KB_ROOT, filePath).replace(/\\/g, '/'), path.basename(filePath, path.extname(filePath)), content);
+        documents.push(buildKnowledgeDocumentPayloadFromFile({
+            filepath: filePath,
+            content,
+            ...identity,
+        }));
     }
     return documents;
 }
@@ -9606,6 +9704,7 @@ async function syncLearningWorkspaceForDocumentPaths(params) {
     const result = await knowledgeLearningPlatform.ingestKnowledge({
         incremental: true,
         documents,
+        deletedDocuments: params.deletedDocuments,
         ingestedAt: new Date().toISOString(),
         relationRecomputeMode: 'incremental',
     });
@@ -9613,6 +9712,7 @@ async function syncLearningWorkspaceForDocumentPaths(params) {
         target: params.target,
         reason: params.reason,
         documentCount: documents.length,
+        deletedDocumentCount: params.deletedDocuments?.length || 0,
         changedDocuments: result.summary.changedDocuments,
         activeAtoms: result.summary.activeAtoms,
     });
@@ -9666,15 +9766,8 @@ async function ensureLearningWorkspaceHydratedForConversationRequest(requestPayl
     const readinessBeforeSync = await knowledgeLearningPlatform.inspectKnowledgeWorkspaceRequest({
         query: requestPayload.message,
         scope: derivedScope,
+        includeSourceInventory: true,
     });
-    if (readinessBeforeSync.readiness.status === 'ready') {
-        return {
-            hydrated: false,
-            target,
-            scope: derivedScope,
-            reason: 'existing_store_ready',
-        };
-    }
     if (!target || target === 'ALL_FOLDERS') {
         const explicitAllFoldersTarget = String(requestPayload.activeTarget || '').trim().toUpperCase() === 'ALL_FOLDERS';
         if (explicitAllFoldersTarget) {
@@ -9693,26 +9786,91 @@ async function ensureLearningWorkspaceHydratedForConversationRequest(requestPayl
             reason: readinessBeforeSync.readiness.status,
         };
     }
-    const targetPath = path.join(KB_ROOT, target);
+    const availableTargets = await collectAvailableTargetsFromPath(KB_ROOT);
+    const resolvedTarget = availableTargets.find((entry) => entry.toLowerCase() === target.toLowerCase()) || target;
+    const targetPath = path.join(KB_ROOT, resolvedTarget);
+    const targetPathExists = await pathExists(targetPath);
+    const targetFiles = await collectMarkdownFilePaths(targetPath);
+    const diskSourcePaths = targetFiles.map(buildKnowledgeSourcePathFromFilePath);
+    const indexedSourcePaths = readinessBeforeSync.sourceInventory?.sourcePaths || [];
+    const inventoryDiff = (0, workspaceHydration_1.buildKnowledgeSourceInventoryDiff)({
+        diskSourcePaths,
+        indexedSourcePaths,
+    });
+    const indexedItemsByPath = new Map((readinessBeforeSync.sourceInventory?.items || []).map((item) => [
+        (0, workspaceHydration_1.normalizeKnowledgeSourcePath)(item.sourcePath),
+        item,
+    ]));
+    // A missing target directory is an unavailable filesystem boundary, not an
+    // authoritative empty corpus. API/mobile callers may legitimately ingest a
+    // document before its host materializes the directory, and deleting those
+    // indexed projections would make the next conversation observe an empty store.
+    const deletedDocuments = targetPathExists
+        ? inventoryDiff.removedSourcePaths
+            .map((sourcePath) => indexedItemsByPath.get((0, workspaceHydration_1.normalizeKnowledgeSourcePath)(sourcePath)))
+            .filter((item) => Boolean(item))
+            .map((item) => ({
+            documentId: item.documentId,
+            sourcePath: item.sourcePath,
+        }))
+        : [];
+    if (readinessBeforeSync.readiness.status === 'ready'
+        && inventoryDiff.addedSourcePaths.length <= 0
+        && deletedDocuments.length <= 0) {
+        return {
+            hydrated: false,
+            target: resolvedTarget,
+            scope: derivedScope,
+            reason: 'existing_store_ready',
+        };
+    }
     const titleLikeQueries = deriveKnowledgeTargetLookupQueries(String(requestPayload.message || ''));
     const candidateFiles = await findKnowledgeFilesByTitleLikeQueries(targetPath, titleLikeQueries);
     if (candidateFiles.length > 0) {
         await syncLearningWorkspaceForDocumentPaths({
-            target,
-            filePaths: candidateFiles,
+            target: resolvedTarget,
+            filePaths: candidateFiles.slice(0, KNOWLEDGE_WORKSPACE_MAX_SELECTIVE_HYDRATION_FILES),
+            deletedDocuments,
             reason: 'conversation_selective_title_hydration',
         });
         return {
             hydrated: true,
-            target,
+            target: resolvedTarget,
             scope: derivedScope,
             reason: 'conversation_selective_title_hydration',
         };
     }
-    await syncLearningWorkspaceForTarget(target, 'conversation_auto_hydration');
+    if (deletedDocuments.length > 0 && readinessBeforeSync.readiness.status === 'ready') {
+        await syncLearningWorkspaceForDocumentPaths({
+            target: resolvedTarget,
+            filePaths: [],
+            deletedDocuments,
+            reason: 'conversation_stale_source_reconciliation',
+        });
+        return {
+            hydrated: true,
+            target: resolvedTarget,
+            scope: derivedScope,
+            reason: 'conversation_stale_source_reconciliation',
+        };
+    }
+    if (targetFiles.length > KNOWLEDGE_WORKSPACE_LARGE_TARGET_FILE_THRESHOLD) {
+        return {
+            hydrated: false,
+            target: resolvedTarget,
+            scope: derivedScope,
+            reason: 'conversation_hydration_deferred_large_target',
+        };
+    }
+    await syncLearningWorkspaceForDocumentPaths({
+        target: resolvedTarget,
+        filePaths: targetFiles,
+        deletedDocuments,
+        reason: 'conversation_auto_hydration',
+    });
     return {
         hydrated: true,
-        target,
+        target: resolvedTarget,
         scope: derivedScope,
         reason: 'conversation_auto_hydration',
     };
@@ -10130,15 +10288,12 @@ const startServer = async (options = {}) => {
             }
         }
     }
-    // --- Strict Registry Mode ---
-    // Why: The inline notemd handlers (~1,147 lines) are a legacy fallback from
-    // the pre-modularization era. The route registry intercepts all covered routes
-    // first (line ~13170), making the inline handlers unreachable in production.
-    // This flag lets us verify 100% coverage in CI before safe deletion.
-    // Conditional (off by default): integration tests start the server without
-    // full registry init and depend on the inline fallback. Once all tests use
-    // the registry, this becomes default and inline handlers can be deleted.
-    const STRICT_REGISTRY = process.env.NOTE_CONNECTION_STRICT_REGISTRY === '1';
+    const ROUTE_DISPATCH_MODE = String(process.env.NOTE_CONNECTION_ROUTE_DISPATCH_MODE || 'registry')
+        .trim()
+        .toLowerCase() === 'legacy'
+        ? 'legacy'
+        : 'registry';
+    const USE_REGISTRY_DISPATCH = ROUTE_DISPATCH_MODE === 'registry';
     // --- Route Registry (modular dispatch for extracted route groups) ---
     const runtimeRunbookOps = (0, runtimeRunbookRouteOps_1.createRuntimeRunbookRouteOps)({
         buildRuntimePayload: buildKnowledgeRuntimePayload,
@@ -10184,6 +10339,24 @@ const startServer = async (options = {}) => {
         memoryPolicyManager,
         notemdService,
         loadNotemdSettings,
+        notemdHttp: { readJsonBody, writeBodyParseErrorResponse, writeApiErrorResponse, resolvePathWithinKnowledgeBase, writeSseEvent, finishSseResponse, llmClient: notemdLlmClient },
+        executeQueryBackendConfigUpdate: async (payload) => {
+            const requestPayload = normalizeQueryBackendConfigRequestPayload(payload);
+            const result = await knowledgeLearningPlatform.updateQueryBackendConfig(requestPayload);
+            ACTIVE_KNOWLEDGE_QUERY_BACKEND = result.configuredBackend;
+            const baseDiagnostics = knowledgeLearningPlatform.getQueryBackendDiagnostics();
+            const graphvizRuntimeAvailability = await getGraphvizDotRuntimeAvailability();
+            const diagnostics = enrichQueryBackendDiagnosticsWithRendererRuntime(baseDiagnostics, graphvizRuntimeAvailability);
+            return {
+                result,
+                diagnostics,
+                configuredVectorAccelerationProvider: QUERY_VECTOR_ACCELERATION_PROVIDER,
+                configuredVectorAccelerationFailureMode: QUERY_VECTOR_ACCELERATION_FAILURE_MODE,
+                configuredVectorAccelerationRepresentationStrict: QUERY_VECTOR_ACCELERATION_REPRESENTATION_STRICT_ENABLED,
+                queryVectorAnnPrefilterEnabled: QUERY_VECTOR_ANN_PREFILTER_ENABLED,
+                rolloutProfile: buildKnowledgeRuntimeRolloutProfile(),
+            };
+        },
         persistNotemdSettings,
         loadFrontendSettings,
         markdownGateway,
@@ -10199,6 +10372,63 @@ const startServer = async (options = {}) => {
         runtimeRunbookOps,
         getPathBridge: () => pathBridge,
     };
+    // These routes keep their complete state/I/O operation in this server.
+    const serverOwnedApiPaths = new Set([
+        '/api/available-targets',
+        '/api/build',
+        '/api/check-cache',
+        '/api/clipboard/image',
+        '/api/clipboard/image-binary',
+        '/api/content',
+        '/api/folders',
+        '/api/frontend/settings',
+        '/api/kb-path',
+        '/api/knowledge/conversation',
+        '/api/knowledge/conversation-memory/add',
+        '/api/knowledge/conversation-memory/delete',
+        '/api/knowledge/conversation-memory/feedback',
+        '/api/knowledge/conversation-memory/search',
+        '/api/knowledge/conversation/turn-cache/diagnostics',
+        '/api/knowledge/conversation/turn-cache/diagnostics/trend',
+        '/api/knowledge/conversation/turn-cache/diagnostics/trend/export',
+        '/api/knowledge/conversation/turn-cache/diagnostics/trend/index',
+        '/api/knowledge/ingest/guardrails/evaluate',
+        '/api/knowledge/mastery/diagnose',
+        '/api/knowledge/mastery/misconceptions',
+        '/api/knowledge/memory/policy',
+        '/api/knowledge/path',
+        '/api/knowledge/quality/evaluate',
+        '/api/knowledge/quality/snapshot',
+        '/api/knowledge/query',
+        '/api/knowledge/query-backend-config',
+        '/api/knowledge/query/compare-backends',
+        '/api/knowledge/runtime-capability-runbook/remediation-event',
+        '/api/knowledge/runtime-capability-runbook/remediation-event/replay',
+        '/api/knowledge/runtime-capability-runbook/remediation-event/replay-schedule',
+        '/api/knowledge/runtime-capability-runbook/remediation-event/replay-schedule/tick',
+        '/api/knowledge/session/action',
+        '/api/knowledge/session/execute',
+        '/api/knowledge/session/history',
+        '/api/knowledge/session/orchestration/config',
+        '/api/knowledge/session/plan',
+        '/api/knowledge/session/plan/evaluate',
+        '/api/knowledge/staleness/rebuild',
+        '/api/knowledge/store/reload',
+        '/api/knowledge/tutor/action',
+        '/api/markdown/chunk',
+        '/api/markdown/index',
+        '/api/markdown/resolve-node',
+        '/api/markdown/resolve-wiki',
+        '/api/path-mode/settings',
+        '/api/render/graphviz',
+        '/api/render/math',
+        '/api/render/mermaid',
+        '/api/restore-cache',
+        '/api/runtime-diagnostics',
+        '/api/runtime-request-trace',
+    ]);
+    let intentionalInlineHits = 0;
+    const inlineFallbacksByFamily = {};
     // Route migration tracking
     let routeRegistryHits = 0;
     let routeInlineFallbacks = 0;
@@ -10217,9 +10447,8 @@ const startServer = async (options = {}) => {
     }
     const routeMigrationStats = {
         totalModularRoutes: allRoutes.length,
-        totalInlineRoutes: 7, // terminal routes (meta/diagnostics/static-serve) — intentionally kept inline
-        // notemd inline block (~1,147 lines) is 100% registry-covered (30 registry routes > 16 inline).
-        // Pending safe deletion after integration test; set NOTE_CONNECTION_STRICT_REGISTRY=1 to skip inline.
+        totalInlineRoutes: [...serverOwnedApiPaths].filter(pathname => !allRoutes.some(route => route.path === pathname)).length,
+        dispatchMode: ROUTE_DISPATCH_MODE,
         registryHits: () => routeRegistryHits,
         inlineFallbacks: () => routeInlineFallbacks,
         registryHitRate: () => {
@@ -10227,9 +10456,9 @@ const startServer = async (options = {}) => {
             return total === 0 ? '0.0%' : (routeRegistryHits / total * 100).toFixed(1) + '%';
         },
         migrationProgress: () => {
-            const covered = allRoutes.length;
-            const total = covered + 7; // 7 terminal routes intentionally kept inline
-            return (covered / total * 100).toFixed(1) + '%';
+            const registeredPaths = new Set(allRoutes.map(route => route.path));
+            const supportedPaths = new Set([...registeredPaths, ...serverOwnedApiPaths]);
+            return (registeredPaths.size / supportedPaths.size * 100).toFixed(1) + '%';
         },
     };
     const server = http.createServer(async (req, res) => {
@@ -10285,113 +10514,57 @@ const startServer = async (options = {}) => {
             res.end(JSON.stringify({ error: 'Unauthorized sidecar request.' }));
             return;
         }
-        // Route Registry Dispatch: try modular routes first, fall through to legacy inline chain
-        const methodMap = routeMap.get(req.method || 'GET');
-        if (methodMap) {
-            const exactRoute = methodMap.get(requestPath);
-            if (exactRoute) {
-                routeRegistryHits++;
-                await exactRoute.handler(req, res, routeContext);
-                return;
+        const methodMap = routeMap.get(requestMethod);
+        const registeredRoute = methodMap?.get(requestPath)
+            || prefixRoutes.find(route => requestPath.startsWith(route.path) && route.method === requestMethod);
+        if (registeredRoute && (USE_REGISTRY_DISPATCH || requestPath.startsWith('/api/notemd/'))) {
+            routeRegistryHits++;
+            try {
+                await registeredRoute.handler(req, res, routeContext);
             }
-            for (const prefixRoute of prefixRoutes) {
-                if (requestPath.startsWith(prefixRoute.path) && prefixRoute.method === (req.method || 'GET')) {
-                    routeRegistryHits++;
-                    await prefixRoute.handler(req, res, routeContext);
-                    return;
-                }
+            catch (error) {
+                writeApiErrorResponse(res, error, { context: requestMethod + ' ' + requestPath, requestId });
             }
+            return;
+        }
+        if (requestPath.startsWith('/api/notemd/')) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'NoteMD route not found' }));
+            return;
         }
-        if (requestPath.startsWith('/api/')) {
+        if (serverOwnedApiPaths.has(requestPath))
+            intentionalInlineHits++;
+        else if (requestPath.startsWith('/api/')) {
             routeInlineFallbacks++;
+            const family = requestPath.split('/')[2] || 'unknown';
+            inlineFallbacksByFamily[family] = (inlineFallbacksByFamily[family] || 0) + 1;
         }
-        // ── Inline Chain (Legacy) ──────────────────────────────────
-        // Route distribution:
-        //   Registry-covered: ~80 routes (knowledge:36G+28P, notemd:2G+16P, + data/render)
-        //   Terminal inline:  ~7 routes intentionally kept inline:
-        //     - runtime-diagnostics, runtime-request-trace (meta: report server state)
-        //     - static file serving (requires FRONTEND_DIR + MIME resolution)
-        //     - graph asset serving (requires cliOptions + generated asset paths)
-        //     - generated asset resolution (requires CLI build output paths)
-        //   These are terminal — they require deep server state that can't be
-        //   cleanly exposed through ServerContext without circular dependencies.
-        //   Total:            ~105 route patterns
-        //
-        // The registry dispatch (above) intercepts covered routes first.
-        // Tag [REGISTRY_COVERED] marks routes already handled by registry.
-        // Migration metrics: GET /api/runtime-diagnostics → routeMigration
+        // Server-owned operations retain their validation, state and native I/O boundaries.
         if (req.method === 'GET') {
             const getPathname = getRawRequestPathname(req.url);
-            // ── Notemd routes (covered by routes/notemd.ts) ──
-            // [REGISTRY_COVERED: routes/notemd.ts]
-            if (STRICT_REGISTRY && getPathname.startsWith('/api/notemd/')) {
-                res.writeHead(501, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: 'strict_registry: route must be handled by modular registry', path: getPathname }));
-                routeInlineFallbacks++;
+            if (getPathname === '/api/knowledge/conversation/turn-cache/diagnostics') {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: true, result: getAgentConversationTurnCacheDiagnostics() }));
                 return;
             }
-            if (getPathname === '/api/notemd/settings') {
-                try {
-                    const settings = await loadNotemdSettings();
-                    const activeOperationCount = Array.from(NOTEMD_ACTIVE_OPERATIONS.values()).filter((operation) => operation.status === 'running').length;
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        success: true,
-                        settings,
-                        operationSummary: {
-                            total: NOTEMD_ACTIVE_OPERATIONS.size,
-                            running: activeOperationCount,
-                        },
-                    }));
-                }
-                catch (error) {
-                    writeApiErrorResponse(res, error, {
-                        context: 'API:GET /api/notemd/settings',
-                        requestId,
-                    });
-                }
+            if (getPathname === '/api/knowledge/conversation/turn-cache/diagnostics/trend') {
+                getAgentConversationTurnCacheDiagnostics();
+                const request = normalizeAgentConversationTurnCacheAlertTrendRequestFromQuery(new URL(req.url, `http://${LOOPBACK_HOST}`).searchParams);
+                const result = queryAgentConversationTurnCacheAlertTrend(request);
+                appendRuntimeRunbookVerificationHistoryFromConversationTurnCacheAlertTrend(result);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: true, result }));
                 return;
             }
-            if (getPathname === '/api/notemd/provider-templates') {
-                try {
-                    const urlObj = new URL(req.url || '/', `http://${LOOPBACK_HOST}:${finalPort}`);
-                    const persistTemplates = ['1', 'true', 'yes'].includes(String(urlObj.searchParams.get('persist') || '').trim().toLowerCase());
-                    let persistence = { configPath: (0, AppConfigToml_1.resolveAppConfigPath)(), persisted: false };
-                    if (persistTemplates) {
-                        persistence = await ensureNotemdProviderTemplatesPersisted();
-                    }
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        success: true,
-                        templates: providerTemplates_1.NOTEMD_PROVIDER_TEMPLATES,
-                        configPath: persistence.configPath,
-                        persisted: persistence.persisted,
-                    }));
-                }
-                catch (error) {
-                    writeApiErrorResponse(res, error, {
-                        context: 'API:GET /api/notemd/provider-templates',
-                        requestId,
-                    });
-                }
+            if (getPathname === '/api/knowledge/conversation/turn-cache/diagnostics/trend/index') {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: true, result: snapshotAgentConversationTurnCacheAlertHistoryStorageIndex() }));
                 return;
             }
-            if (getPathname === '/api/notemd/workspace') {
-                try {
-                    const settings = await loadNotemdSettings();
-                    const workspace = extractNotemdWorkspaceState(settings);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        success: true,
-                        workspace,
-                    }));
-                }
-                catch (error) {
-                    writeApiErrorResponse(res, error, {
-                        context: 'API:GET /api/notemd/workspace',
-                        requestId,
-                    });
-                }
+            if (getPathname === '/api/knowledge/conversation/turn-cache/diagnostics/trend/export') {
+                const request = normalizeAgentConversationTurnCacheAlertTrendRequestFromQuery(new URL(req.url, `http://${LOOPBACK_HOST}`).searchParams);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: true, result: queryAgentConversationTurnCacheAlertTrendExport(request) }));
                 return;
             }
             if (getPathname === '/api/path-mode/settings') {
@@ -10467,6 +10640,9 @@ const startServer = async (options = {}) => {
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({
                         runtime: {
+                            nodeVersion: process.version,
+                            platform: process.platform,
+                            arch: process.arch,
                             host: LOOPBACK_HOST,
                             port: runtimePort,
                             bridgePort: effectivePathBridgePort,
@@ -10515,10 +10691,13 @@ const startServer = async (options = {}) => {
                             totalModularRoutes: routeMigrationStats.totalModularRoutes,
                             registryHits: routeMigrationStats.registryHits(),
                             inlineFallbacks: routeMigrationStats.inlineFallbacks(),
+                            intentionalInlineHits,
+                            inlineFallbacksByFamily: { ...inlineFallbacksByFamily },
                             registryHitRate: routeMigrationStats.registryHitRate(),
                             migrationProgress: routeMigrationStats.migrationProgress(),
                             modularRoutes: routeMigrationStats.totalModularRoutes,
                             inlineOnlyRoutes: routeMigrationStats.totalInlineRoutes,
+                            dispatchMode: routeMigrationStats.dispatchMode,
                         },
                         domains: {
                             ingest: knowledgeIngestor.getDiagnostics(),
@@ -11006,24 +11185,12 @@ const startServer = async (options = {}) => {
             if (postPathname === '/api/knowledge/query-backend-config') {
                 try {
                     const payload = await readJsonBody(req);
-                    const requestPayload = normalizeQueryBackendConfigRequestPayload(payload);
-                    const result = await knowledgeLearningPlatform.updateQueryBackendConfig(requestPayload);
-                    ACTIVE_KNOWLEDGE_QUERY_BACKEND = result.configuredBackend;
-                    const baseDiagnostics = knowledgeLearningPlatform.getQueryBackendDiagnostics();
-                    const graphvizRuntimeAvailability = await getGraphvizDotRuntimeAvailability();
-                    const diagnostics = enrichQueryBackendDiagnosticsWithRendererRuntime(baseDiagnostics, graphvizRuntimeAvailability);
-                    const rolloutProfile = buildKnowledgeRuntimeRolloutProfile();
+                    const responsePayload = await routeContext.executeQueryBackendConfigUpdate?.(payload);
+                    if (!responsePayload) {
+                        throw new Error('Query backend config operation is unavailable.');
+                    }
                     res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        success: true,
-                        result,
-                        diagnostics,
-                        configuredVectorAccelerationProvider: QUERY_VECTOR_ACCELERATION_PROVIDER,
-                        configuredVectorAccelerationFailureMode: QUERY_VECTOR_ACCELERATION_FAILURE_MODE,
-                        configuredVectorAccelerationRepresentationStrict: QUERY_VECTOR_ACCELERATION_REPRESENTATION_STRICT_ENABLED,
-                        queryVectorAnnPrefilterEnabled: QUERY_VECTOR_ANN_PREFILTER_ENABLED,
-                        rolloutProfile,
-                    }));
+                    res.end(JSON.stringify({ success: true, ...responsePayload }));
                 }
                 catch (error) {
                     writeApiErrorResponse(res, error, {
@@ -11069,13 +11236,15 @@ const startServer = async (options = {}) => {
                 return;
             }
             if (postPathname === '/api/knowledge/conversation') {
+                let releaseClient;
                 try {
                     const payload = await readJsonBody(req);
-                    const requestPayload = normalizeAgentConversationRequestPayload(payload);
+                    const requestPayload = (0, requestNormalization_1.normalizeAgentConversationRequestPayload)(payload);
                     const streamRequested = requestAcceptsEventStream(req);
                     const turnId = resolveAgentConversationTurnId(req, requestId);
                     const requestFingerprint = buildAgentConversationRequestFingerprint(requestPayload);
                     const turnRecord = getOrCreateAgentConversationTurnCacheRecord(turnId, requestFingerprint);
+                    releaseClient = attachAgentConversationClient(turnRecord, req, res);
                     if (!streamRequested) {
                         const wasCompletedBeforeExecution = turnRecord.status === 'completed';
                         await ensureAgentConversationTurnExecution(turnRecord, requestPayload);
@@ -11086,7 +11255,10 @@ const startServer = async (options = {}) => {
                             res.setHeader('X-Agent-Conversation-Turn-Id', turnId);
                             res.setHeader('X-Agent-Conversation-Replay', wasCompletedBeforeExecution ? 'hit' : 'miss');
                             res.writeHead(200, { 'Content-Type': 'application/json' });
-                            res.end(JSON.stringify({ success: true, result: turnRecord.result }));
+                            const responseResult = requestPayload.responseProfile === 'mobile_compact'
+                                ? buildMobileAgentConversationResponse(turnRecord.result)
+                                : turnRecord.result;
+                            res.end((0, agentConversationSerialization_1.serializeAgentConversationHttpResponse)(responseResult).json);
                             return;
                         }
                         throwAgentConversationCachedFailure(turnRecord.failure);
@@ -11118,15 +11290,15 @@ const startServer = async (options = {}) => {
                         await new Promise((resolve) => setImmediate(resolve));
                         await ensureAgentConversationTurnExecution(turnRecord, requestPayload, {
                             emitLiveEvent: (event) => {
-                                writeSseEvent(res, event.type, event);
+                                writeSseEvent(res, event.type, projectAgentConversationTurnEvent(event, requestPayload));
                             },
                         });
                     }
                     else {
                         await ensureAgentConversationTurnExecution(turnRecord, requestPayload);
-                        replayAgentConversationTurnEvents(res, turnRecord);
+                        replayAgentConversationTurnEvents(res, turnRecord, requestPayload);
                     }
-                    res.end();
+                    await finishSseResponse(res);
                 }
                 catch (error) {
                     writeApiErrorResponse(res, error, {
@@ -11135,6 +11307,9 @@ const startServer = async (options = {}) => {
                         enableValidationStatus: true,
                     });
                 }
+                finally {
+                    releaseClient?.();
+                }
                 return;
             }
             if (postPathname === '/api/knowledge/mastery/diagnose') {
@@ -11453,125 +11628,43 @@ const startServer = async (options = {}) => {
                 }
                 return;
             }
-            // ── Notemd POST routes (covered by routes/notemd.ts) ──
-            // [REGISTRY_COVERED: routes/notemd.ts]
-            if (STRICT_REGISTRY && postPathname.startsWith('/api/notemd/')) {
-                res.writeHead(501, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: 'strict_registry: route must be handled by modular registry', path: postPathname }));
-                routeInlineFallbacks++;
-                return;
-            }
-            if (postPathname === '/api/notemd/settings') {
+            if (postPathname === '/api/path-mode/settings') {
                 try {
                     const payload = await readJsonBody(req);
                     const settingsCandidate = isObjectRecord(payload) && payload.settings !== undefined
                         ? payload.settings
                         : payload;
-                    const settings = await persistNotemdSettings(settingsCandidate);
+                    const settings = await persistPathModeSettings(settingsCandidate);
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ success: true, settings }));
                 }
                 catch (error) {
                     writeApiErrorResponse(res, error, {
-                        context: 'API:POST /api/notemd/settings',
+                        context: 'API:POST /api/path-mode/settings',
                         requestId,
                     });
                 }
                 return;
             }
-            if (postPathname === '/api/notemd/provider-templates/apply') {
+            if (postPathname === '/api/frontend/settings') {
                 try {
                     const payload = await readJsonBody(req);
-                    const rawTemplateId = isObjectRecord(payload)
-                        ? String(payload.templateId || payload.template_id || '').trim()
-                        : '';
-                    if (!rawTemplateId) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: 'Missing templateId.' }));
-                        return;
-                    }
-                    const template = (0, providerTemplates_1.getNotemdProviderTemplate)(rawTemplateId);
-                    if (!template) {
-                        res.writeHead(404, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: `Unknown provider template: ${rawTemplateId}` }));
-                        return;
-                    }
-                    const settings = await loadNotemdSettings();
-                    const updatedSettings = (0, providerTemplates_1.applyProviderTemplateToSettings)(settings, rawTemplateId);
-                    const persistedSettings = await persistNotemdSettings(updatedSettings);
-                    const persistence = await ensureNotemdProviderTemplatesPersisted();
+                    const settingsCandidate = isObjectRecord(payload) && payload.settings !== undefined
+                        ? payload.settings
+                        : payload;
+                    const settings = await persistFrontendSettings(settingsCandidate);
                     res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        success: true,
-                        template,
-                        settings: persistedSettings,
-                        configPath: persistence.configPath,
-                        persistedTemplates: persistence.persisted,
-                    }));
+                    res.end(JSON.stringify({ success: true, settings }));
                 }
                 catch (error) {
                     writeApiErrorResponse(res, error, {
-                        context: 'API:POST /api/notemd/provider-templates/apply',
+                        context: 'API:POST /api/frontend/settings',
                         requestId,
                     });
                 }
                 return;
             }
-            if (postPathname === '/api/notemd/workspace') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const workspaceCandidate = isObjectRecord(payload) && payload.workspace !== undefined
-                        ? payload.workspace
-                        : payload;
-                    const workspace = await persistNotemdWorkspacePatch(workspaceCandidate);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, workspace }));
-                }
-                catch (error) {
-                    writeApiErrorResponse(res, error, {
-                        context: 'API:POST /api/notemd/workspace',
-                        requestId,
-                    });
-                }
-                return;
-            }
-            if (postPathname === '/api/path-mode/settings') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const settingsCandidate = isObjectRecord(payload) && payload.settings !== undefined
-                        ? payload.settings
-                        : payload;
-                    const settings = await persistPathModeSettings(settingsCandidate);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, settings }));
-                }
-                catch (error) {
-                    writeApiErrorResponse(res, error, {
-                        context: 'API:POST /api/path-mode/settings',
-                        requestId,
-                    });
-                }
-                return;
-            }
-            if (postPathname === '/api/frontend/settings') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const settingsCandidate = isObjectRecord(payload) && payload.settings !== undefined
-                        ? payload.settings
-                        : payload;
-                    const settings = await persistFrontendSettings(settingsCandidate);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, settings }));
-                }
-                catch (error) {
-                    writeApiErrorResponse(res, error, {
-                        context: 'API:POST /api/frontend/settings',
-                        requestId,
-                    });
-                }
-                return;
-            }
-            if (postPathname === '/api/markdown/index') {
+            if (postPathname === '/api/markdown/index') {
                 try {
                     const payload = await readJsonBody(req);
                     const requestBody = isObjectRecord(payload) ? payload : {};
@@ -11789,645 +11882,6 @@ const startServer = async (options = {}) => {
                 }
                 return;
             }
-            if (postPathname === '/api/notemd/cancel') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const operationId = String(payload.operationId || '').trim();
-                    if (!operationId) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: 'Missing operationId' }));
-                        return;
-                    }
-                    const operation = NOTEMD_ACTIVE_OPERATIONS.get(operationId);
-                    if (!operation) {
-                        res.writeHead(404, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: 'Operation not found' }));
-                        return;
-                    }
-                    if (operation.status !== 'running') {
-                        res.writeHead(200, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({
-                            success: false,
-                            operationId,
-                            status: operation.status,
-                            message: 'Operation is not running.',
-                        }));
-                        return;
-                    }
-                    operation.controller.abort();
-                    finalizeNotemdOperation(operation, 'cancelled');
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, operationId, status: 'cancelled' }));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/cancel');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/test-llm') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const settings = await loadNotemdSettings();
-                    const providerName = String(payload.providerName || settings.activeProvider).trim();
-                    const provider = settings.providers.find((item) => item.name === providerName);
-                    if (!provider) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: `Unknown provider: ${providerName}` }));
-                        return;
-                    }
-                    const result = await notemdLlmClient.testConnection(provider);
-                    const statusCode = result.success ? 200 : 400;
-                    res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify(result));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/test-llm');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/process-file') {
-                const streamEnabled = shouldStreamNotemdResponse(req);
-                let operation = null;
-                try {
-                    const payload = await readJsonBody(req);
-                    const settings = await loadNotemdSettings();
-                    operation = createNotemdOperation(payload.operationId);
-                    const reporter = createNotemdReporter(operation, streamEnabled ? res : undefined);
-                    if (streamEnabled) {
-                        res.writeHead(200, {
-                            'Content-Type': 'text/event-stream',
-                            'Cache-Control': 'no-cache',
-                            Connection: 'keep-alive',
-                        });
-                        writeSseEvent(res, 'operation', {
-                            operationId: operation.id,
-                            status: operation.status,
-                        });
-                    }
-                    const resolvedFilePath = await resolvePathWithinKnowledgeBase(payload.filePath, {
-                        expectedType: 'file',
-                    });
-                    const resolvedOutputPath = payload.outputPath
-                        ? await resolvePathWithinKnowledgeBase(payload.outputPath, {
-                            expectedType: 'any',
-                            allowMissing: true,
-                        })
-                        : undefined;
-                    const result = await notemdService.processFile({
-                        filePath: resolvedFilePath,
-                        outputPath: resolvedOutputPath,
-                        createConceptNotes: payload.createConceptNotes === true,
-                        dryRun: payload.dryRun === true,
-                    }, settings, reporter, operation.controller.signal);
-                    void persistNotemdWorkspacePatch({
-                        filePath: resolvedFilePath,
-                        folderPath: path.dirname(resolvedFilePath),
-                        outputFilePath: resolvedOutputPath || result.outputPath || '',
-                        outputFolderPath: path.dirname(resolvedOutputPath || result.outputPath || resolvedFilePath),
-                    }).catch((workspaceError) => {
-                        warnDiagnostic('[NoteMD] Failed to persist workspace state after process-file.', workspaceError);
-                    });
-                    finalizeNotemdOperation(operation, 'done');
-                    if (streamEnabled) {
-                        writeSseEvent(res, 'done', {
-                            success: true,
-                            operationId: operation.id,
-                            result,
-                        });
-                        res.end();
-                    }
-                    else {
-                        res.writeHead(200, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({
-                            success: true,
-                            operationId: operation.id,
-                            result,
-                            logs: operation.logs,
-                        }));
-                    }
-                }
-                catch (error) {
-                    if (operation) {
-                        finalizeNotemdOperation(operation, operation.controller.signal.aborted ? 'cancelled' : 'error');
-                    }
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        const statusCode = operation?.controller.signal.aborted ? 499 : 403;
-                        const payload = { success: false, error: String(error.message || 'Access denied') };
-                        if (streamEnabled) {
-                            writeSseEvent(res, 'error', payload);
-                            res.end();
-                        }
-                        else {
-                            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-                            res.end(JSON.stringify(payload));
-                        }
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/process-file');
-                    const payload = { success: false, error: String(error) };
-                    if (streamEnabled) {
-                        writeSseEvent(res, 'error', payload);
-                        res.end();
-                    }
-                    else {
-                        res.writeHead(500, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify(payload));
-                    }
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/process-folder') {
-                const streamEnabled = shouldStreamNotemdResponse(req);
-                let operation = null;
-                try {
-                    const payload = await readJsonBody(req);
-                    const settings = await loadNotemdSettings();
-                    operation = createNotemdOperation(payload.operationId);
-                    const reporter = createNotemdReporter(operation, streamEnabled ? res : undefined);
-                    if (streamEnabled) {
-                        res.writeHead(200, {
-                            'Content-Type': 'text/event-stream',
-                            'Cache-Control': 'no-cache',
-                            Connection: 'keep-alive',
-                        });
-                        writeSseEvent(res, 'operation', {
-                            operationId: operation.id,
-                            status: operation.status,
-                        });
-                    }
-                    const resolvedFolderPath = await resolvePathWithinKnowledgeBase(payload.folderPath, {
-                        expectedType: 'directory',
-                    });
-                    const resolvedOutputFolderPath = payload.outputFolderPath
-                        ? await resolvePathWithinKnowledgeBase(payload.outputFolderPath, {
-                            expectedType: 'any',
-                            allowMissing: true,
-                        })
-                        : undefined;
-                    const result = await notemdService.processFolder({
-                        folderPath: resolvedFolderPath,
-                        outputFolderPath: resolvedOutputFolderPath,
-                        createConceptNotes: payload.createConceptNotes === true,
-                        dryRun: payload.dryRun === true,
-                    }, settings, reporter, operation.controller.signal);
-                    void persistNotemdWorkspacePatch({
-                        folderPath: resolvedFolderPath,
-                        outputFolderPath: resolvedOutputFolderPath || '',
-                    }).catch((workspaceError) => {
-                        warnDiagnostic('[NoteMD] Failed to persist workspace state after process-folder.', workspaceError);
-                    });
-                    finalizeNotemdOperation(operation, 'done');
-                    if (streamEnabled) {
-                        writeSseEvent(res, 'done', {
-                            success: true,
-                            operationId: operation.id,
-                            result,
-                        });
-                        res.end();
-                    }
-                    else {
-                        res.writeHead(200, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({
-                            success: true,
-                            operationId: operation.id,
-                            result,
-                            logs: operation.logs,
-                        }));
-                    }
-                }
-                catch (error) {
-                    if (operation) {
-                        finalizeNotemdOperation(operation, operation.controller.signal.aborted ? 'cancelled' : 'error');
-                    }
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        const statusCode = operation?.controller.signal.aborted ? 499 : 403;
-                        const payload = { success: false, error: String(error.message || 'Access denied') };
-                        if (streamEnabled) {
-                            writeSseEvent(res, 'error', payload);
-                            res.end();
-                        }
-                        else {
-                            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-                            res.end(JSON.stringify(payload));
-                        }
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/process-folder');
-                    const payload = { success: false, error: String(error) };
-                    if (streamEnabled) {
-                        writeSseEvent(res, 'error', payload);
-                        res.end();
-                    }
-                    else {
-                        res.writeHead(500, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify(payload));
-                    }
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/generate-content') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const settings = await loadNotemdSettings();
-                    let title = String(payload.title || '').trim();
-                    const filePathCandidate = String(payload.filePath || '').trim();
-                    if (!title && filePathCandidate) {
-                        title = path.basename(filePathCandidate, path.extname(filePathCandidate));
-                    }
-                    if (!title) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: 'Missing title or filePath' }));
-                        return;
-                    }
-                    const content = await notemdService.generateContent(title, typeof payload.context === 'string' ? payload.context : undefined, settings);
-                    let outputPath = null;
-                    if (payload.outputPath) {
-                        outputPath = await resolvePathWithinKnowledgeBase(payload.outputPath, {
-                            expectedType: 'any',
-                            allowMissing: true,
-                        });
-                    }
-                    else if (filePathCandidate) {
-                        outputPath = await resolvePathWithinKnowledgeBase(filePathCandidate, {
-                            expectedType: 'any',
-                            allowMissing: true,
-                        });
-                    }
-                    if (outputPath) {
-                        await fs.promises.mkdir(path.dirname(outputPath), { recursive: true });
-                        await fs.promises.writeFile(outputPath, content, 'utf8');
-                    }
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        success: true,
-                        title,
-                        outputPath,
-                        content,
-                    }));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: String(error.message || 'Access denied') }));
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/generate-content');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/translate-file') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const settings = await loadNotemdSettings();
-                    const resolvedFilePath = await resolvePathWithinKnowledgeBase(payload.filePath, {
-                        expectedType: 'file',
-                    });
-                    const resolvedOutputPath = payload.outputPath
-                        ? await resolvePathWithinKnowledgeBase(payload.outputPath, {
-                            expectedType: 'any',
-                            allowMissing: true,
-                        })
-                        : undefined;
-                    const targetLanguage = String(payload.targetLanguage || settings.translateLanguage || settings.language).trim();
-                    if (!targetLanguage) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: 'Missing targetLanguage' }));
-                        return;
-                    }
-                    const result = await notemdService.translateFile({
-                        filePath: resolvedFilePath,
-                        outputPath: resolvedOutputPath,
-                        targetLanguage,
-                    }, settings);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, result }));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: String(error.message || 'Access denied') }));
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/translate-file');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/translate-folder') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const settings = await loadNotemdSettings();
-                    const resolvedFolderPath = await resolvePathWithinKnowledgeBase(payload.folderPath, {
-                        expectedType: 'directory',
-                    });
-                    const targetLanguage = String(payload.targetLanguage || settings.translateLanguage || settings.language).trim();
-                    if (!targetLanguage) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: 'Missing targetLanguage' }));
-                        return;
-                    }
-                    const result = await notemdService.translateFolder(resolvedFolderPath, targetLanguage, settings);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, result }));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: String(error.message || 'Access denied') }));
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/translate-folder');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/fix-mermaid') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const resolvedFilePath = await resolvePathWithinKnowledgeBase(payload.filePath, {
-                        expectedType: 'file',
-                    });
-                    const inPlace = payload.inPlace !== false;
-                    const result = await notemdService.fixMermaid(resolvedFilePath, inPlace);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, result }));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: String(error.message || 'Access denied') }));
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/fix-mermaid');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/fix-formulas') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const resolvedFilePath = await resolvePathWithinKnowledgeBase(payload.filePath, {
-                        expectedType: 'file',
-                    });
-                    const inPlace = payload.inPlace !== false;
-                    const result = await notemdService.fixFormulas(resolvedFilePath, inPlace);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, result }));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: String(error.message || 'Access denied') }));
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/fix-formulas');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/check-duplicates') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const resolvedFilePath = await resolvePathWithinKnowledgeBase(payload.filePath, {
-                        expectedType: 'file',
-                    });
-                    const result = await notemdService.checkDuplicates(resolvedFilePath);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, result }));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: String(error.message || 'Access denied') }));
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/check-duplicates');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/extract-concepts') {
-                const streamEnabled = shouldStreamNotemdResponse(req);
-                let operation = null;
-                try {
-                    const payload = await readJsonBody(req);
-                    const settings = await loadNotemdSettings();
-                    operation = createNotemdOperation(payload.operationId);
-                    const reporter = createNotemdReporter(operation, streamEnabled ? res : undefined);
-                    if (streamEnabled) {
-                        res.writeHead(200, {
-                            'Content-Type': 'text/event-stream',
-                            'Cache-Control': 'no-cache',
-                            Connection: 'keep-alive',
-                        });
-                        writeSseEvent(res, 'operation', {
-                            operationId: operation.id,
-                            status: operation.status,
-                        });
-                    }
-                    const resolvedFilePath = await resolvePathWithinKnowledgeBase(payload.filePath, {
-                        expectedType: 'file',
-                    });
-                    const result = await notemdService.extractConcepts(resolvedFilePath, settings, reporter, operation.controller.signal);
-                    void persistNotemdWorkspacePatch({
-                        filePath: resolvedFilePath,
-                        folderPath: path.dirname(resolvedFilePath),
-                    }).catch((workspaceError) => {
-                        warnDiagnostic('[NoteMD] Failed to persist workspace state after extract-concepts.', workspaceError);
-                    });
-                    finalizeNotemdOperation(operation, 'done');
-                    if (streamEnabled) {
-                        writeSseEvent(res, 'done', {
-                            success: true,
-                            operationId: operation.id,
-                            result,
-                        });
-                        res.end();
-                    }
-                    else {
-                        res.writeHead(200, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: true, operationId: operation.id, result, logs: operation.logs }));
-                    }
-                }
-                catch (error) {
-                    if (operation) {
-                        finalizeNotemdOperation(operation, operation.controller.signal.aborted ? 'cancelled' : 'error');
-                    }
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        const statusCode = operation?.controller.signal.aborted ? 499 : 403;
-                        const payload = { success: false, error: String(error.message || 'Access denied') };
-                        if (streamEnabled) {
-                            writeSseEvent(res, 'error', payload);
-                            res.end();
-                        }
-                        else {
-                            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-                            res.end(JSON.stringify(payload));
-                        }
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/extract-concepts');
-                    const payload = { success: false, error: String(error) };
-                    if (streamEnabled) {
-                        writeSseEvent(res, 'error', payload);
-                        res.end();
-                    }
-                    else {
-                        res.writeHead(500, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify(payload));
-                    }
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/one-click-extract') {
-                let operation = null;
-                try {
-                    const payload = await readJsonBody(req);
-                    const settings = await loadNotemdSettings();
-                    operation = createNotemdOperation(payload.operationId);
-                    const reporter = createNotemdReporter(operation);
-                    const resolvedFilePath = await resolvePathWithinKnowledgeBase(payload.filePath, {
-                        expectedType: 'file',
-                    });
-                    const result = await notemdService.oneClickExtract(resolvedFilePath, settings, reporter, operation.controller.signal);
-                    void persistNotemdWorkspacePatch({
-                        filePath: resolvedFilePath,
-                        folderPath: result.outputFolderPath,
-                        outputFolderPath: result.outputFolderPath,
-                    }).catch((workspaceError) => {
-                        warnDiagnostic('[NoteMD] Failed to persist workspace state after one-click-extract.', workspaceError);
-                    });
-                    finalizeNotemdOperation(operation, 'done');
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, operationId: operation.id, result, logs: operation.logs }));
-                }
-                catch (error) {
-                    if (operation) {
-                        finalizeNotemdOperation(operation, operation.controller.signal.aborted ? 'cancelled' : 'error');
-                    }
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: String(error.message || 'Access denied') }));
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/one-click-extract');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/batch-fix-mermaid') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const resolvedFolderPath = await resolvePathWithinKnowledgeBase(payload.folderPath, {
-                        expectedType: 'directory',
-                    });
-                    const result = await notemdService.batchFixMermaid(resolvedFolderPath, payload.inPlace !== false);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, result }));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: String(error.message || 'Access denied') }));
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/batch-fix-mermaid');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
-            if (postPathname === '/api/notemd/generate-folder-content') {
-                try {
-                    const payload = await readJsonBody(req);
-                    const settings = await loadNotemdSettings();
-                    const resolvedFolderPath = await resolvePathWithinKnowledgeBase(payload.folderPath, {
-                        expectedType: 'directory',
-                    });
-                    const result = await notemdService.generateFolderContent(resolvedFolderPath, settings);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, result }));
-                }
-                catch (error) {
-                    if (writeBodyParseErrorResponse(res, error)) {
-                        return;
-                    }
-                    if (isAccessDeniedError(error)) {
-                        res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ success: false, error: String(error.message || 'Access denied') }));
-                        return;
-                    }
-                    console.error(error);
-                    CrashLogger_1.CrashLogger.log(error, 'API:POST /api/notemd/generate-folder-content');
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: false, error: String(error) }));
-                }
-                return;
-            }
             if (req.url === '/api/render/math') {
                 try {
                     const payload = await readJsonBody(req);
@@ -12590,6 +12044,17 @@ const startServer = async (options = {}) => {
                 try {
                     const payload = await readJsonBody(req);
                     const { target, maxWorkers, enableGPU, enableGPULayout, memorySavingMode, deepDebug } = payload;
+                    const requestedRelationRecomputeMode = payload?.relationRecomputeMode;
+                    const relationRecomputeMode = normalizeRelationRecomputeModeValue(requestedRelationRecomputeMode);
+                    if (requestedRelationRecomputeMode !== undefined
+                        && (!relationRecomputeMode || relationRecomputeMode === 'auto')) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({
+                            success: false,
+                            error: 'relationRecomputeMode must be one of: none, incremental, full',
+                        }));
+                        return;
+                    }
                     logDiagnostic('Received build request for:', target, 'maxWorkers:', maxWorkers, 'enableGPU:', enableGPU, 'enableGPULayout:', enableGPULayout, 'memorySavingMode:', memorySavingMode, 'deepDebug:', deepDebug);
                     const buildKey = JSON.stringify({
                         target,
@@ -12597,7 +12062,8 @@ const startServer = async (options = {}) => {
                         enableGPU,
                         enableGPULayout,
                         memorySavingMode,
-                        deepDebug
+                        deepDebug,
+                        relationRecomputeMode: relationRecomputeMode || 'incremental',
                     });
                     // De-duplicate accidental double-submit from frontend.
                     if (activeBuildPromise) {
@@ -12640,7 +12106,13 @@ const startServer = async (options = {}) => {
                             deepDebug
                         });
                         ACTIVE_GRAPH_TARGET = normalizedRuntimeTarget;
-                        return await syncLearningWorkspaceForTarget(normalizedRuntimeTarget, 'build_graph');
+                        const files = await collectMarkdownFilePaths(targetToBuild);
+                        const documents = await buildKnowledgeDocumentPayloadsFromPaths(files);
+                        const ingest = await knowledgeLearningPlatform.ingestKnowledge({
+                            incremental: true, documents, ingestedAt: new Date().toISOString(),
+                            relationRecomputeMode: relationRecomputeMode || 'incremental',
+                        });
+                        return { target: normalizedRuntimeTarget, documentCount: documents.length, summary: ingest.summary };
                     })();
                     activeBuildKey = buildKey;
                     activeBuildPromise = buildPromise;
@@ -12707,6 +12179,10 @@ const startServer = async (options = {}) => {
                 return;
             }
         }
+        if (!res.writableEnded && !res.destroyed) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'API route not found' }));
+        }
     });
     server.on('close', () => {
         try {