recallx-headless 1.0.0 → 1.0.2

package/README.md

@@ -132,9 +132,10 @@ recallx workspace open --root /Users/name/Documents/RecallX-Test
 ## Environment
 
 - `RECALLX_API_URL` to override the local API base URL
-- `RECALLX_TOKEN` to pass a bearer token
+- `RECALLX_API_TOKEN` to pass a bearer token for CLI requests
+- `RECALLX_TOKEN` remains supported as a legacy alias for CLI requests
 - `RECALLX_PORT`, `RECALLX_BIND`, `RECALLX_WORKSPACE_ROOT`, `RECALLX_WORKSPACE_NAME`, and `RECALLX_API_TOKEN` are respected by `recallx serve`
-- Node 20+ is recommended for the headless package
+- Node 22.13+ is recommended for the headless package
 
 ## Notes
 

package/app/cli/src/cli.js

@@ -726,7 +726,14 @@ function buildMcpConfigPayload(launcherPath) {
 }
 async function installMcpLauncher(launcherPath, commandParts) {
     await mkdir(path.dirname(launcherPath), { recursive: true });
-    await writeFile(launcherPath, `#!/bin/sh\nexec ${commandParts.map(quoteShellArg).join(" ")} "$@"\n`, "utf8");
+    await writeFile(launcherPath, `#!/bin/sh
+NODE_BIN="\${RECALLX_NODE_BIN:-$(command -v node 2>/dev/null || true)}"
+if [ -z "$NODE_BIN" ]; then
+  echo "recallx-mcp launcher could not find a node executable in PATH." >&2
+  exit 1
+fi
+exec "$NODE_BIN" ${commandParts.slice(1).map(quoteShellArg).join(" ")} "$@"
+`, "utf8");
     await chmod(launcherPath, 0o755);
 }
 function quoteShellArg(value) {

package/app/cli/src/format.js

@@ -202,11 +202,65 @@ export function renderTelemetrySummary(data) {
       `fts fallback: ${data.ftsFallbackRate.fallbackCount}/${data.ftsFallbackRate.sampleCount} (${data.ftsFallbackRate.ratio ?? "n/a"})`
     );
   }
+  if (data?.searchHitRate) {
+    lines.push(
+      `search hit rate: ${data.searchHitRate.hitCount}/${data.searchHitRate.sampleCount} (${data.searchHitRate.ratio ?? "n/a"})`
+    );
+    const searchHitOps = Array.isArray(data.searchHitRate.operations) ? data.searchHitRate.operations : [];
+    for (const item of searchHitOps.slice(0, 5)) {
+      lines.push(
+        `- [${item.surface}] ${item.operation}: ${item.hitCount}/${item.sampleCount} hits (${item.ratio ?? "n/a"})`
+      );
+    }
+  }
+  if (data?.searchLexicalQualityRate) {
+    lines.push(
+      `lexical quality: strong=${data.searchLexicalQualityRate.strongCount}, weak=${data.searchLexicalQualityRate.weakCount}, none=${data.searchLexicalQualityRate.noneCount}`
+    );
+  }
+  if (data?.workspaceResultCompositionRate) {
+    lines.push(
+      `workspace composition: node_only=${data.workspaceResultCompositionRate.nodeOnlyCount}, semantic_node_only=${data.workspaceResultCompositionRate.semanticNodeOnlyCount}, activity_only=${data.workspaceResultCompositionRate.activityOnlyCount}, mixed=${data.workspaceResultCompositionRate.mixedCount}, semantic_mixed=${data.workspaceResultCompositionRate.semanticMixedCount}, empty=${data.workspaceResultCompositionRate.emptyCount}`
+    );
+  }
+  if (data?.workspaceFallbackModeRate) {
+    lines.push(
+      `workspace fallback modes: strict_zero=${data.workspaceFallbackModeRate.strictZeroCount}, no_strong_node_hit=${data.workspaceFallbackModeRate.noStrongNodeHitCount}`
+    );
+  }
+  if (data?.searchFeedbackRate) {
+    lines.push(
+      `search feedback: useful=${data.searchFeedbackRate.usefulCount}/${data.searchFeedbackRate.sampleCount} (${data.searchFeedbackRate.usefulRatio ?? "n/a"}), top1=${data.searchFeedbackRate.top1UsefulCount}/${data.searchFeedbackRate.top1SampleCount} (${data.searchFeedbackRate.top1UsefulRatio ?? "n/a"}), top3=${data.searchFeedbackRate.top3UsefulCount}/${data.searchFeedbackRate.top3SampleCount} (${data.searchFeedbackRate.top3UsefulRatio ?? "n/a"}), semantic_fp=${data.searchFeedbackRate.semanticFalsePositiveRatio ?? "n/a"}`
+    );
+    const qualityBuckets = Array.isArray(data.searchFeedbackRate.byLexicalQuality) ? data.searchFeedbackRate.byLexicalQuality : [];
+    for (const item of qualityBuckets) {
+      lines.push(
+        `- feedback [${item.lexicalQuality}]: ${item.usefulCount}/${item.sampleCount} useful (${item.usefulRatio ?? "n/a"})`
+      );
+    }
+    const fallbackModeBuckets = Array.isArray(data.searchFeedbackRate.byFallbackMode) ? data.searchFeedbackRate.byFallbackMode : [];
+    for (const item of fallbackModeBuckets) {
+      lines.push(
+        `- feedback mode [${item.fallbackMode}]: ${item.usefulCount}/${item.sampleCount} useful (${item.usefulRatio ?? "n/a"})`
+      );
+    }
+  }
   if (data?.semanticAugmentationRate) {
     lines.push(
       `semantic augmentation: ${data.semanticAugmentationRate.usedCount}/${data.semanticAugmentationRate.sampleCount} (${data.semanticAugmentationRate.ratio ?? "n/a"})`
     );
   }
+  if (data?.semanticFallbackRate) {
+    lines.push(
+      `semantic fallback: eligible=${data.semanticFallbackRate.eligibleCount}, attempted=${data.semanticFallbackRate.attemptedCount}, hit=${data.semanticFallbackRate.hitCount}, hit_ratio=${data.semanticFallbackRate.hitRatio ?? "n/a"}`
+    );
+    const fallbackModes = Array.isArray(data.semanticFallbackRate.modes) ? data.semanticFallbackRate.modes : [];
+    for (const item of fallbackModes) {
+      lines.push(
+        `- fallback mode [${item.fallbackMode}]: attempted=${item.attemptedCount}/${item.eligibleCount} (${item.attemptRatio ?? "n/a"}), hit=${item.hitCount}/${item.attemptedCount} (${item.hitRatio ?? "n/a"})`
+      );
+    }
+  }
 
   return `${lines.join("\n")}\n`;
 }

package/app/cli/src/http.js

@@ -6,7 +6,7 @@ export function getApiBase(argvOptions = {}, env = process.env) {
         DEFAULT_API_BASE);
 }
 export function getAuthToken(argvOptions = {}, env = process.env) {
-    return argvOptions.token || env.RECALLX_TOKEN || "";
+    return argvOptions.token || env.RECALLX_API_TOKEN || env.RECALLX_TOKEN || "";
 }
 export async function requestJson(apiBase, path, { method = "GET", token, body } = {}) {
     const response = await fetch(buildApiUrl(apiBase, path), buildApiRequestInit({ method, token, body }));

package/app/server/app.js

@@ -8,7 +8,7 @@ import { activitySearchSchema, appendActivitySchema, appendRelationUsageEventSch
 import { AppError } from "./errors.js";
 import { isShortLogLikeAgentNodeInput, maybeCreatePromotionCandidate, recomputeAutomaticGovernance, resolveGovernancePolicy, resolveNodeGovernance, resolveRelationStatus, shouldPromoteActivitySummary } from "./governance.js";
 import { refreshAutomaticInferredRelationsForNode, reindexAutomaticInferredRelations } from "./inferred-relations.js";
-import { createObservabilityWriter, summarizePayloadShape } from "./observability.js";
+import { appendCurrentTelemetryDetails, createObservabilityWriter, summarizePayloadShape } from "./observability.js";
 import { buildSemanticCandidateBonusMap, buildCandidateRelationBonusMap, buildContextBundle, buildNeighborhoodItems, buildTargetRelatedRetrievalItems, bundleAsMarkdown, computeRankCandidateScore, shouldUseSemanticCandidateAugmentation } from "./retrieval.js";
 import { buildProjectGraph } from "./project-graph.js";
 import { createId, isPathWithinRoot } from "./utils.js";
@@ -172,6 +172,9 @@ function parseBooleanSetting(value, fallback) {
 function parseNumberSetting(value, fallback) {
     return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
+function readWorkspaceSemanticFallbackMode(value) {
+    return value === "strict_zero" || value === "no_strong_node_hit" ? value : null;
+}
 function normalizeApiRequestPath(value) {
     return value
         .replace(/^\/artifacts\/.+$/g, "/artifacts/:path")
@@ -1406,6 +1409,12 @@ export function createRecallXApp(params) {
         }, (span) => {
             const searchResult = currentRepository().searchNodes(input);
             span.addDetails({
+                searchHit: searchResult.items.length > 0,
+                bestLexicalQuality: searchResult.items.some((item) => item.lexicalQuality === "strong")
+                    ? "strong"
+                    : searchResult.items.some((item) => item.lexicalQuality === "weak")
+                        ? "weak"
+                        : "none",
                 resultCount: searchResult.items.length,
                 totalCount: searchResult.total
             });
@@ -1423,6 +1432,12 @@ export function createRecallXApp(params) {
         }, (span) => {
             const searchResult = currentRepository().searchActivities(input);
             span.addDetails({
+                searchHit: searchResult.items.length > 0,
+                bestLexicalQuality: searchResult.items.some((item) => item.lexicalQuality === "strong")
+                    ? "strong"
+                    : searchResult.items.some((item) => item.lexicalQuality === "weak")
+                        ? "weak"
+                        : "none",
                 resultCount: searchResult.items.length,
                 totalCount: searchResult.total
             });
@@ -1457,6 +1472,7 @@ export function createRecallXApp(params) {
                 })
             });
             span.addDetails({
+                searchHit: searchResult.items.length > 0,
                 resultCount: searchResult.items.length,
                 totalCount: searchResult.total
             });
@@ -1861,9 +1877,55 @@ export function createRecallXApp(params) {
             governance: buildGovernancePayload(repository, "relation", event.relationId, governanceResult.items[0] ?? repository.getGovernanceStateNullable("relation", event.relationId))
         }));
     });
-    app.post("/api/v1/search-feedback-events", (request, response) => {
+    app.post("/api/v1/search-feedback-events", handleAsyncRoute(async (request, response) => {
         const repository = currentRepository();
         const event = repository.appendSearchFeedbackEvent(appendSearchFeedbackSchema.parse(request.body ?? {}));
+        const metadata = event.metadata ?? {};
+        const fallbackMode = readWorkspaceSemanticFallbackMode(metadata.semanticFallbackMode);
+        const lexicalQuality = metadata.lexicalQuality === "strong" || metadata.lexicalQuality === "weak" || metadata.lexicalQuality === "none"
+            ? metadata.lexicalQuality
+            : null;
+        const feedbackRank = typeof metadata.rank === "number" && Number.isFinite(metadata.rank)
+            ? metadata.rank
+            : typeof metadata.resultRank === "number" && Number.isFinite(metadata.resultRank)
+                ? metadata.resultRank
+                : null;
+        const matchStrategy = metadata.matchStrategy === "fts" ||
+            metadata.matchStrategy === "like" ||
+            metadata.matchStrategy === "fallback_token" ||
+            metadata.matchStrategy === "semantic" ||
+            metadata.matchStrategy === "browse"
+            ? metadata.matchStrategy
+            : null;
+        await observability.recordEvent({
+            surface: "api",
+            operation: "search.feedback",
+            details: {
+                feedbackVerdict: event.verdict,
+                feedbackResultType: event.resultType,
+                feedbackLexicalQuality: lexicalQuality,
+                feedbackConfidence: event.confidence,
+                feedbackRank,
+                feedbackMatchStrategy: matchStrategy,
+                feedbackSemanticLifted: metadata.semanticLifted === true,
+                feedbackSemanticFallbackMode: fallbackMode ?? undefined,
+                feedbackHasQuery: Boolean(event.query?.trim()),
+                feedbackHasRunId: Boolean(event.runId),
+                feedbackHasSessionId: Boolean(event.sessionId)
+            }
+        });
+        appendCurrentTelemetryDetails({
+            feedbackVerdict: event.verdict,
+            feedbackResultType: event.resultType,
+            feedbackLexicalQuality: lexicalQuality,
+            feedbackMatchStrategy: matchStrategy,
+            feedbackRank,
+            feedbackSemanticLifted: metadata.semanticLifted === true,
+            feedbackSemanticFallbackMode: fallbackMode ?? undefined,
+            feedbackHasQuery: Boolean(event.query?.trim()),
+            feedbackHasRunId: Boolean(event.runId),
+            feedbackHasSessionId: Boolean(event.sessionId)
+        });
         const governanceResult = event.resultType === "node"
             ? recomputeGovernanceForEntities("node", [event.resultId])
             : { items: [] };
@@ -1878,7 +1940,7 @@ export function createRecallXApp(params) {
                 ? buildGovernancePayload(repository, "node", event.resultId, governanceResult.items[0] ?? repository.getGovernanceStateNullable("node", event.resultId))
                 : null
         }));
-    });
+    }));
     app.post("/api/v1/inferred-relations/recompute", handleAsyncRoute(async (request, response) => {
         const input = recomputeInferredRelationsSchema.parse(request.body ?? {});
         const isFullMaintenancePass = !input.generator && !input.relationIds?.length;

package/app/server/observability.js

@@ -340,8 +340,44 @@ export class ObservabilityWriter {
         const buckets = new Map();
         const mcpFailures = new Map();
         const autoJobs = new Map();
+        const searchHitBuckets = new Map();
+        const lexicalQualityBuckets = new Map();
+        const workspaceFallbackModeBuckets = new Map();
+        const feedbackByLexicalQuality = new Map();
+        const feedbackByFallbackMode = new Map();
+        const semanticFallbackByMode = new Map();
         let ftsFallbackCount = 0;
         let ftsSampleCount = 0;
+        let searchHitCount = 0;
+        let searchMissCount = 0;
+        let searchSampleCount = 0;
+        let strongLexicalCount = 0;
+        let weakLexicalCount = 0;
+        let noLexicalCount = 0;
+        let lexicalSampleCount = 0;
+        let emptyCompositionCount = 0;
+        let nodeOnlyCompositionCount = 0;
+        let activityOnlyCompositionCount = 0;
+        let mixedCompositionCount = 0;
+        let semanticNodeOnlyCompositionCount = 0;
+        let semanticMixedCompositionCount = 0;
+        let compositionSampleCount = 0;
+        let strictZeroFallbackModeCount = 0;
+        let noStrongNodeHitFallbackModeCount = 0;
+        let workspaceFallbackModeSampleCount = 0;
+        let feedbackUsefulCount = 0;
+        let feedbackNotUsefulCount = 0;
+        let feedbackUncertainCount = 0;
+        let feedbackSampleCount = 0;
+        let feedbackTop1UsefulCount = 0;
+        let feedbackTop1SampleCount = 0;
+        let feedbackTop3UsefulCount = 0;
+        let feedbackTop3SampleCount = 0;
+        let feedbackSemanticUsefulCount = 0;
+        let feedbackSemanticNotUsefulCount = 0;
+        let feedbackSemanticSampleCount = 0;
+        let feedbackSemanticLiftUsefulCount = 0;
+        let feedbackSemanticLiftSampleCount = 0;
         let semanticUsedCount = 0;
         let semanticSampleCount = 0;
         let semanticFallbackEligibleCount = 0;
@@ -354,6 +390,209 @@ export class ObservabilityWriter {
                     ftsFallbackCount += 1;
                 }
             }
+            if (typeof event.details.searchHit === "boolean") {
+                searchSampleCount += 1;
+                if (event.details.searchHit) {
+                    searchHitCount += 1;
+                }
+                else {
+                    searchMissCount += 1;
+                }
+                const bucketKey = `${event.surface}:${event.operation}`;
+                const current = searchHitBuckets.get(bucketKey) ?? {
+                    surface: event.surface,
+                    operation: event.operation,
+                    hitCount: 0,
+                    missCount: 0
+                };
+                if (event.details.searchHit) {
+                    current.hitCount += 1;
+                }
+                else {
+                    current.missCount += 1;
+                }
+                searchHitBuckets.set(bucketKey, current);
+            }
+            if (event.details.bestLexicalQuality === "strong" ||
+                event.details.bestLexicalQuality === "weak" ||
+                event.details.bestLexicalQuality === "none" ||
+                event.details.bestNodeLexicalQuality === "strong" ||
+                event.details.bestNodeLexicalQuality === "weak" ||
+                event.details.bestNodeLexicalQuality === "none") {
+                const quality = (event.details.bestNodeLexicalQuality ??
+                    event.details.bestLexicalQuality);
+                lexicalSampleCount += 1;
+                if (quality === "strong") {
+                    strongLexicalCount += 1;
+                }
+                else if (quality === "weak") {
+                    weakLexicalCount += 1;
+                }
+                else {
+                    noLexicalCount += 1;
+                }
+                const bucketKey = `${event.surface}:${event.operation}`;
+                const current = lexicalQualityBuckets.get(bucketKey) ?? {
+                    surface: event.surface,
+                    operation: event.operation,
+                    strongCount: 0,
+                    weakCount: 0,
+                    noneCount: 0
+                };
+                if (quality === "strong") {
+                    current.strongCount += 1;
+                }
+                else if (quality === "weak") {
+                    current.weakCount += 1;
+                }
+                else {
+                    current.noneCount += 1;
+                }
+                lexicalQualityBuckets.set(bucketKey, current);
+            }
+            if (typeof event.details.resultComposition === "string") {
+                compositionSampleCount += 1;
+                switch (event.details.resultComposition) {
+                    case "node_only":
+                        nodeOnlyCompositionCount += 1;
+                        break;
+                    case "activity_only":
+                        activityOnlyCompositionCount += 1;
+                        break;
+                    case "mixed":
+                        mixedCompositionCount += 1;
+                        break;
+                    case "semantic_node_only":
+                        semanticNodeOnlyCompositionCount += 1;
+                        break;
+                    case "semantic_mixed":
+                        semanticMixedCompositionCount += 1;
+                        break;
+                    default:
+                        emptyCompositionCount += 1;
+                        break;
+                }
+            }
+            if (event.operation === "workspace.search" &&
+                (event.details.semanticFallbackMode === "strict_zero" || event.details.semanticFallbackMode === "no_strong_node_hit")) {
+                workspaceFallbackModeSampleCount += 1;
+                if (event.details.semanticFallbackMode === "strict_zero") {
+                    strictZeroFallbackModeCount += 1;
+                }
+                else {
+                    noStrongNodeHitFallbackModeCount += 1;
+                }
+                const bucketKey = `${event.surface}:${event.operation}`;
+                const current = workspaceFallbackModeBuckets.get(bucketKey) ?? {
+                    surface: event.surface,
+                    operation: event.operation,
+                    strictZeroCount: 0,
+                    noStrongNodeHitCount: 0
+                };
+                if (event.details.semanticFallbackMode === "strict_zero") {
+                    current.strictZeroCount += 1;
+                }
+                else {
+                    current.noStrongNodeHitCount += 1;
+                }
+                workspaceFallbackModeBuckets.set(bucketKey, current);
+            }
+            if (event.details.feedbackVerdict === "useful" ||
+                event.details.feedbackVerdict === "not_useful" ||
+                event.details.feedbackVerdict === "uncertain") {
+                feedbackSampleCount += 1;
+                if (event.details.feedbackVerdict === "useful") {
+                    feedbackUsefulCount += 1;
+                }
+                else if (event.details.feedbackVerdict === "not_useful") {
+                    feedbackNotUsefulCount += 1;
+                }
+                else {
+                    feedbackUncertainCount += 1;
+                }
+                const feedbackRank = typeof event.details.feedbackRank === "number" && Number.isFinite(event.details.feedbackRank)
+                    ? event.details.feedbackRank
+                    : null;
+                if (feedbackRank != null) {
+                    if (feedbackRank <= 1) {
+                        feedbackTop1SampleCount += 1;
+                        if (event.details.feedbackVerdict === "useful") {
+                            feedbackTop1UsefulCount += 1;
+                        }
+                    }
+                    if (feedbackRank <= 3) {
+                        feedbackTop3SampleCount += 1;
+                        if (event.details.feedbackVerdict === "useful") {
+                            feedbackTop3UsefulCount += 1;
+                        }
+                    }
+                }
+                const feedbackMatchStrategy = event.details.feedbackMatchStrategy === "fts" ||
+                    event.details.feedbackMatchStrategy === "like" ||
+                    event.details.feedbackMatchStrategy === "fallback_token" ||
+                    event.details.feedbackMatchStrategy === "semantic" ||
+                    event.details.feedbackMatchStrategy === "browse"
+                    ? event.details.feedbackMatchStrategy
+                    : null;
+                if (feedbackMatchStrategy === "semantic") {
+                    feedbackSemanticSampleCount += 1;
+                    if (event.details.feedbackVerdict === "useful") {
+                        feedbackSemanticUsefulCount += 1;
+                    }
+                    else if (event.details.feedbackVerdict === "not_useful") {
+                        feedbackSemanticNotUsefulCount += 1;
+                    }
+                }
+                if (event.details.feedbackSemanticLifted === true) {
+                    feedbackSemanticLiftSampleCount += 1;
+                    if (event.details.feedbackVerdict === "useful") {
+                        feedbackSemanticLiftUsefulCount += 1;
+                    }
+                }
+                const lexicalQuality = event.details.feedbackLexicalQuality === "strong" ||
+                    event.details.feedbackLexicalQuality === "weak" ||
+                    event.details.feedbackLexicalQuality === "none"
+                    ? event.details.feedbackLexicalQuality
+                    : null;
+                if (lexicalQuality) {
+                    const current = feedbackByLexicalQuality.get(lexicalQuality) ?? {
+                        usefulCount: 0,
+                        notUsefulCount: 0,
+                        uncertainCount: 0
+                    };
+                    if (event.details.feedbackVerdict === "useful") {
+                        current.usefulCount += 1;
+                    }
+                    else if (event.details.feedbackVerdict === "not_useful") {
+                        current.notUsefulCount += 1;
+                    }
+                    else {
+                        current.uncertainCount += 1;
+                    }
+                    feedbackByLexicalQuality.set(lexicalQuality, current);
+                }
+                const feedbackFallbackMode = event.details.feedbackSemanticFallbackMode === "strict_zero" ||
+                    event.details.feedbackSemanticFallbackMode === "no_strong_node_hit"
+                    ? event.details.feedbackSemanticFallbackMode
+                    : null;
+                if (feedbackFallbackMode) {
+                    const current = feedbackByFallbackMode.get(feedbackFallbackMode) ?? {
+                        usefulCount: 0,
+                        notUsefulCount: 0,
+                        uncertainCount: 0
+                    };
+                    if (event.details.feedbackVerdict === "useful") {
+                        current.usefulCount += 1;
+                    }
+                    else if (event.details.feedbackVerdict === "not_useful") {
+                        current.notUsefulCount += 1;
+                    }
+                    else {
+                        current.uncertainCount += 1;
+                    }
+                    feedbackByFallbackMode.set(feedbackFallbackMode, current);
+                }
+            }
             if (typeof event.details.semanticUsed === "boolean") {
                 semanticSampleCount += 1;
                 if (event.details.semanticUsed) {
@@ -375,6 +614,29 @@ export class ObservabilityWriter {
                     semanticFallbackHitCount += 1;
                 }
             }
+            const semanticFallbackMode = event.operation === "workspace.search" &&
+                (event.details.semanticFallbackMode === "strict_zero" || event.details.semanticFallbackMode === "no_strong_node_hit")
+                ? event.details.semanticFallbackMode
+                : null;
+            if (semanticFallbackMode) {
+                const current = semanticFallbackByMode.get(semanticFallbackMode) ?? {
+                    eligibleCount: 0,
+                    attemptedCount: 0,
+                    hitCount: 0,
+                    sampleCount: 0
+                };
+                current.sampleCount += 1;
+                if (event.details.semanticFallbackEligible === true) {
+                    current.eligibleCount += 1;
+                }
+                if (event.details.semanticFallbackAttempted === true) {
+                    current.attemptedCount += 1;
+                }
+                if (event.details.semanticFallbackUsed === true) {
+                    current.hitCount += 1;
+                }
+                semanticFallbackByMode.set(semanticFallbackMode, current);
+            }
             if (event.durationMs != null) {
                 const bucketKey = `${event.surface}:${event.operation}`;
                 const current = buckets.get(bucketKey) ??
@@ -440,6 +702,108 @@ export class ObservabilityWriter {
                 sampleCount: ftsSampleCount,
                 ratio: ftsSampleCount > 0 ? Number((ftsFallbackCount / ftsSampleCount).toFixed(4)) : null
             },
+            searchHitRate: {
+                hitCount: searchHitCount,
+                missCount: searchMissCount,
+                sampleCount: searchSampleCount,
+                ratio: searchSampleCount > 0 ? Number((searchHitCount / searchSampleCount).toFixed(4)) : null,
+                operations: [...searchHitBuckets.values()]
+                    .map((item) => ({
+                    ...item,
+                    sampleCount: item.hitCount + item.missCount,
+                    ratio: item.hitCount + item.missCount > 0
+                        ? Number((item.hitCount / (item.hitCount + item.missCount)).toFixed(4))
+                        : null
+                }))
+                    .sort((left, right) => right.sampleCount - left.sampleCount || left.operation.localeCompare(right.operation))
+            },
+            searchLexicalQualityRate: {
+                strongCount: strongLexicalCount,
+                weakCount: weakLexicalCount,
+                noneCount: noLexicalCount,
+                sampleCount: lexicalSampleCount,
+                operations: [...lexicalQualityBuckets.values()]
+                    .map((item) => ({
+                    ...item,
+                    sampleCount: item.strongCount + item.weakCount + item.noneCount
+                }))
+                    .sort((left, right) => right.sampleCount - left.sampleCount || left.operation.localeCompare(right.operation))
+            },
+            workspaceResultCompositionRate: {
+                emptyCount: emptyCompositionCount,
+                nodeOnlyCount: nodeOnlyCompositionCount,
+                activityOnlyCount: activityOnlyCompositionCount,
+                mixedCount: mixedCompositionCount,
+                semanticNodeOnlyCount: semanticNodeOnlyCompositionCount,
+                semanticMixedCount: semanticMixedCompositionCount,
+                sampleCount: compositionSampleCount
+            },
+            workspaceFallbackModeRate: {
+                strictZeroCount: strictZeroFallbackModeCount,
+                noStrongNodeHitCount: noStrongNodeHitFallbackModeCount,
+                sampleCount: workspaceFallbackModeSampleCount,
+                operations: [...workspaceFallbackModeBuckets.values()]
+                    .map((item) => ({
+                    ...item,
+                    sampleCount: item.strictZeroCount + item.noStrongNodeHitCount
+                }))
+                    .sort((left, right) => right.sampleCount - left.sampleCount || left.operation.localeCompare(right.operation))
+            },
+            searchFeedbackRate: {
+                usefulCount: feedbackUsefulCount,
+                notUsefulCount: feedbackNotUsefulCount,
+                uncertainCount: feedbackUncertainCount,
+                sampleCount: feedbackSampleCount,
+                usefulRatio: feedbackSampleCount > 0 ? Number((feedbackUsefulCount / feedbackSampleCount).toFixed(4)) : null,
+                top1UsefulCount: feedbackTop1UsefulCount,
+                top1SampleCount: feedbackTop1SampleCount,
+                top1UsefulRatio: feedbackTop1SampleCount > 0 ? Number((feedbackTop1UsefulCount / feedbackTop1SampleCount).toFixed(4)) : null,
+                top3UsefulCount: feedbackTop3UsefulCount,
+                top3SampleCount: feedbackTop3SampleCount,
+                top3UsefulRatio: feedbackTop3SampleCount > 0 ? Number((feedbackTop3UsefulCount / feedbackTop3SampleCount).toFixed(4)) : null,
+                semanticUsefulCount: feedbackSemanticUsefulCount,
+                semanticNotUsefulCount: feedbackSemanticNotUsefulCount,
+                semanticSampleCount: feedbackSemanticSampleCount,
+                semanticUsefulRatio: feedbackSemanticSampleCount > 0 ? Number((feedbackSemanticUsefulCount / feedbackSemanticSampleCount).toFixed(4)) : null,
+                semanticFalsePositiveRatio: feedbackSemanticSampleCount > 0 ? Number((feedbackSemanticNotUsefulCount / feedbackSemanticSampleCount).toFixed(4)) : null,
+                semanticLiftUsefulCount: feedbackSemanticLiftUsefulCount,
+                semanticLiftSampleCount: feedbackSemanticLiftSampleCount,
+                semanticLiftUsefulRatio: feedbackSemanticLiftSampleCount > 0
+                    ? Number((feedbackSemanticLiftUsefulCount / feedbackSemanticLiftSampleCount).toFixed(4))
+                    : null,
+                byLexicalQuality: ["strong", "weak", "none"]
+                    .map((lexicalQuality) => {
+                    const counts = feedbackByLexicalQuality.get(lexicalQuality) ?? {
+                        usefulCount: 0,
+                        notUsefulCount: 0,
+                        uncertainCount: 0
+                    };
+                    const sampleCount = counts.usefulCount + counts.notUsefulCount + counts.uncertainCount;
+                    return {
+                        lexicalQuality,
+                        ...counts,
+                        sampleCount,
+                        usefulRatio: sampleCount > 0 ? Number((counts.usefulCount / sampleCount).toFixed(4)) : null
+                    };
+                })
+                    .filter((item) => item.sampleCount > 0),
+                byFallbackMode: ["strict_zero", "no_strong_node_hit"]
+                    .map((fallbackMode) => {
+                    const counts = feedbackByFallbackMode.get(fallbackMode) ?? {
+                        usefulCount: 0,
+                        notUsefulCount: 0,
+                        uncertainCount: 0
+                    };
+                    const sampleCount = counts.usefulCount + counts.notUsefulCount + counts.uncertainCount;
+                    return {
+                        fallbackMode,
+                        ...counts,
+                        sampleCount,
+                        usefulRatio: sampleCount > 0 ? Number((counts.usefulCount / sampleCount).toFixed(4)) : null
+                    };
+                })
+                    .filter((item) => item.sampleCount > 0)
+            },
             semanticAugmentationRate: {
                 usedCount: semanticUsedCount,
                 sampleCount: semanticSampleCount,
@@ -454,7 +818,23 @@ export class ObservabilityWriter {
                     : null,
                 hitRatio: semanticFallbackAttemptedCount > 0
                     ? Number((semanticFallbackHitCount / semanticFallbackAttemptedCount).toFixed(4))
-                    : null
+                    : null,
+                modes: ["strict_zero", "no_strong_node_hit"]
+                    .map((fallbackMode) => {
+                    const counts = semanticFallbackByMode.get(fallbackMode) ?? {
+                        eligibleCount: 0,
+                        attemptedCount: 0,
+                        hitCount: 0,
+                        sampleCount: 0
+                    };
+                    return {
+                        fallbackMode,
+                        ...counts,
+                        attemptRatio: counts.eligibleCount > 0 ? Number((counts.attemptedCount / counts.eligibleCount).toFixed(4)) : null,
+                        hitRatio: counts.attemptedCount > 0 ? Number((counts.hitCount / counts.attemptedCount).toFixed(4)) : null
+                    };
+                })
+                    .filter((item) => item.sampleCount > 0)
             },
             autoJobStats: [...autoJobs.entries()].map(([operation, durations]) => ({
                 operation,

package/app/server/repositories.js

@@ -34,6 +34,7 @@ const workspaceInboxSource = {
     actorLabel: "RecallX",
     toolName: "recallx-system"
 };
+const DEFAULT_WORKSPACE_SEMANTIC_FALLBACK_MODE = "strict_zero";
 function normalizeSearchText(value) {
     return (value ?? "").normalize("NFKC").toLowerCase();
 }
@@ -52,32 +53,140 @@ function createSearchFieldMatcher(query) {
         matchTerms: tokens.length ? tokens : [trimmedQuery]
     };
 }
-function collectMatchedFields(matcher, candidates) {
+function collectSearchFieldSignals(matcher, candidates) {
     if (!matcher) {
-        return [];
+        return {
+            matchedFields: [],
+            exactFields: [],
+            matchedTermCount: 0,
+            totalTermCount: 0
+        };
     }
-    const matches = new Set();
+    const matchedFields = new Set();
+    const exactFields = new Set();
+    const matchedTerms = new Set();
     for (const candidate of candidates) {
         const haystack = normalizeSearchText(candidate.value);
         if (!haystack) {
             continue;
         }
-        if (haystack.includes(matcher.trimmedQuery) || matcher.matchTerms.some((term) => haystack.includes(term))) {
-            matches.add(candidate.field);
+        const exactMatch = haystack.includes(matcher.trimmedQuery);
+        const termMatches = matcher.matchTerms.filter((term) => haystack.includes(term));
+        if (!exactMatch && !termMatches.length) {
+            continue;
+        }
+        matchedFields.add(candidate.field);
+        if (exactMatch) {
+            exactFields.add(candidate.field);
+        }
+        for (const term of termMatches) {
+            matchedTerms.add(term);
+        }
+    }
+    return {
+        matchedFields: [...matchedFields],
+        exactFields: [...exactFields],
+        matchedTermCount: matchedTerms.size,
+        totalTermCount: matcher.matchTerms.length
+    };
+}
+function classifyNodeLexicalQuality(strategy, signals) {
+    if (strategy === "browse" || strategy === "semantic" || !signals.matchedFields.length) {
+        return "none";
+    }
+    if (strategy === "fallback_token") {
+        return "weak";
+    }
+    const strongExactFields = new Set(["title", "summary", "tags"]);
+    if (signals.exactFields.some((field) => strongExactFields.has(field))) {
+        return "strong";
+    }
+    const termCoverage = signals.totalTermCount > 0 ? signals.matchedTermCount / signals.totalTermCount : 0;
+    if (strategy === "fts" && termCoverage >= 0.6 && signals.matchedFields.some((field) => strongExactFields.has(field))) {
+        return "strong";
+    }
+    return "weak";
+}
+function classifyActivityLexicalQuality(strategy, signals) {
+    if (strategy === "browse" || strategy === "semantic" || !signals.matchedFields.length) {
+        return "none";
+    }
+    if (strategy === "fallback_token") {
+        return "weak";
+    }
+    if (signals.exactFields.some((field) => field === "targetNodeTitle" || field === "body" || field === "activityType")) {
+        return "strong";
+    }
+    const termCoverage = signals.totalTermCount > 0 ? signals.matchedTermCount / signals.totalTermCount : 0;
+    return strategy === "fts" && termCoverage >= 0.6 ? "strong" : "weak";
+}
+function summarizeLexicalQuality(items) {
+    if (items.some((item) => item.lexicalQuality === "strong")) {
+        return "strong";
+    }
+    if (items.some((item) => item.lexicalQuality === "weak")) {
+        return "weak";
+    }
+    return "none";
+}
+function computeWorkspaceResultComposition(input) {
+    if (input.nodeCount === 0 && input.activityCount === 0) {
+        return "empty";
+    }
+    if (input.nodeCount > 0 && input.activityCount === 0) {
+        return input.semanticUsed ? "semantic_node_only" : "node_only";
+    }
+    if (input.nodeCount === 0 && input.activityCount > 0) {
+        return "activity_only";
+    }
+    return input.semanticUsed ? "semantic_mixed" : "mixed";
+}
+function mergeLexicalQuality(left, right) {
+    if (left === "strong" || right === "strong") {
+        return "strong";
+    }
+    if (left === "weak" || right === "weak") {
+        return "weak";
+    }
+    return "none";
+}
+function mergeNodeSearchItems(primary, secondary) {
+    const merged = [...primary];
+    const indexById = new Map(primary.map((item, index) => [item.id, index]));
+    for (const item of secondary) {
+        const existingIndex = indexById.get(item.id);
+        if (existingIndex == null) {
+            indexById.set(item.id, merged.length);
+            merged.push(item);
+            continue;
         }
+        const existing = merged[existingIndex];
+        merged[existingIndex] = {
+            ...existing,
+            lexicalQuality: existing.lexicalQuality === "strong" ? "strong" : item.lexicalQuality ?? existing.lexicalQuality,
+            matchReason: existing.matchReason && item.matchReason
+                ? mergeMatchReasons(existing.matchReason, item.matchReason, existing.matchReason.strategy)
+                : existing.matchReason ?? item.matchReason
+        };
     }
-    return [...matches];
+    return merged;
 }
-function buildSearchMatchReason(strategy, matchedFields) {
+function buildSearchMatchReason(strategy, matchedFields, extras = {}) {
     return {
         strategy,
-        matchedFields
+        matchedFields,
+        ...(extras.strength ? { strength: extras.strength } : {}),
+        ...(extras.termCoverage != null ? { termCoverage: extras.termCoverage } : {})
     };
 }
 function mergeMatchReasons(left, right, strategy) {
     return {
         strategy,
-        matchedFields: Array.from(new Set([...(left?.matchedFields ?? []), ...(right?.matchedFields ?? [])]))
+        matchedFields: Array.from(new Set([...(left?.matchedFields ?? []), ...(right?.matchedFields ?? [])])),
+        strength: left?.strength ?? right?.strength,
+        termCoverage: typeof left?.termCoverage === "number" || typeof right?.termCoverage === "number"
+            ? Math.max(left?.termCoverage ?? 0, right?.termCoverage ?? 0)
+            : null
     };
 }
 function computeWorkspaceRankBonus(index, total) {
@@ -87,8 +196,18 @@ function computeWorkspaceRankBonus(index, total) {
     return Math.max(0, Math.round(((total - index) / total) * 24));
 }
 function computeWorkspaceSmartScore(input) {
+    const matchBonus = input.matchReason?.strategy === "semantic"
+        ? 3
+        : input.lexicalQuality === "strong"
+            ? 10
+            : input.lexicalQuality === "weak"
+                ? input.matchReason?.strategy === "fallback_token"
+                    ? 1
+                    : 4
+                : 0;
     return (computeWorkspaceRankBonus(input.index, input.total) +
         computeWorkspaceRecencyBonusFromAge(input.nowMs - new Date(input.timestamp).getTime(), input.resultType) +
+        matchBonus +
         (input.resultType === "activity" ? 4 : 0) -
         (input.contested ? 20 : 0));
 }
@@ -132,6 +251,9 @@ function readNumberSetting(settings, key, fallback) {
     const value = settings[key];
     return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
+function normalizeWorkspaceSemanticFallbackMode(value) {
+    return value === "no_strong_node_hit" ? "no_strong_node_hit" : DEFAULT_WORKSPACE_SEMANTIC_FALLBACK_MODE;
+}
 function normalizeSemanticIndexBackend(value) {
     return value === "sqlite-vec" ? "sqlite-vec" : "sqlite";
 }
@@ -171,7 +293,9 @@ function readSemanticIndexSettingSnapshot(settings, runtime) {
         indexBackend: resolveActiveSemanticIndexBackend(configuredIndexBackend, runtime.sqliteVecLoaded),
         extensionStatus: resolveSemanticExtensionStatus(configuredIndexBackend, runtime.sqliteVecLoaded),
         extensionLoadError: configuredIndexBackend === "sqlite-vec" && !runtime.sqliteVecLoaded ? runtime.sqliteVecLoadError : null,
-        chunkEnabled: readBooleanSetting(settings, "search.semantic.chunk.enabled", false)
+        chunkEnabled: readBooleanSetting(settings, "search.semantic.chunk.enabled", false),
+        workspaceFallbackEnabled: readBooleanSetting(settings, "search.semantic.workspaceFallback.enabled", false),
+        workspaceFallbackMode: normalizeWorkspaceSemanticFallbackMode(settings["search.semantic.workspaceFallback.mode"])
     };
 }
 function shouldReindexForSemanticConfigChange(previous, next) {
@@ -601,7 +725,8 @@ export class RecallXRepository {
             "search.semantic.indexBackend",
             "search.semantic.chunk.enabled",
             "search.semantic.chunk.aggregation",
-            "search.semantic.workspaceFallback.enabled"
+            "search.semantic.workspaceFallback.enabled",
+            "search.semantic.workspaceFallback.mode"
         ]);
         return {
             ...readSemanticIndexSettingSnapshot(settings, {
@@ -609,7 +734,8 @@ export class RecallXRepository {
                 sqliteVecLoadError: this.sqliteVecRuntime.loadError
             }),
             chunkAggregation: normalizeSemanticChunkAggregation(settings["search.semantic.chunk.aggregation"]),
-            workspaceFallbackEnabled: readBooleanSetting(settings, "search.semantic.workspaceFallback.enabled", false)
+            workspaceFallbackEnabled: readBooleanSetting(settings, "search.semantic.workspaceFallback.enabled", false),
+            workspaceFallbackMode: normalizeWorkspaceSemanticFallbackMode(settings["search.semantic.workspaceFallback.mode"])
         };
     }
     getSemanticAugmentationSettings() {
@@ -1010,6 +1136,8 @@ export class RecallXRepository {
             "search.semantic.model",
             "search.semantic.indexBackend",
             "search.semantic.chunk.enabled",
+            "search.semantic.workspaceFallback.enabled",
+            "search.semantic.workspaceFallback.mode",
             "search.semantic.last_backfill_at"
         ]);
         const semanticSettings = readSemanticIndexSettingSnapshot(settings, {
@@ -1031,6 +1159,8 @@ export class RecallXRepository {
         }
         return {
             ...semanticStatusSettings,
+            workspaceFallbackEnabled: readBooleanSetting(settings, "search.semantic.workspaceFallback.enabled", false),
+            workspaceFallbackMode: normalizeWorkspaceSemanticFallbackMode(settings["search.semantic.workspaceFallback.mode"]),
             lastBackfillAt: readStringSetting(settings, "search.semantic.last_backfill_at"),
             counts
         };
@@ -1303,6 +1433,7 @@ export class RecallXRepository {
                 const result = this.searchNodesWithFts(input);
                 appendCurrentTelemetryDetails({
                     ftsFallback: false,
+                    lexicalQuality: summarizeLexicalQuality(result.items),
                     resultCount: result.items.length,
                     totalCount: result.total
                 });
@@ -1312,6 +1443,7 @@ export class RecallXRepository {
                 const fallbackResult = this.searchNodesWithLike(input);
                 appendCurrentTelemetryDetails({
                     ftsFallback: true,
+                    lexicalQuality: summarizeLexicalQuality(fallbackResult.items),
                     resultCount: fallbackResult.items.length,
                     totalCount: fallbackResult.total
                 });
@@ -1321,6 +1453,7 @@ export class RecallXRepository {
         const result = this.searchNodesWithLike(input);
         appendCurrentTelemetryDetails({
             ftsFallback: false,
+            lexicalQuality: summarizeLexicalQuality(result.items),
             resultCount: result.items.length,
             totalCount: result.total
         });
@@ -1332,6 +1465,7 @@ export class RecallXRepository {
                 const result = this.searchActivitiesWithFts(input);
                 appendCurrentTelemetryDetails({
                     ftsFallback: false,
+                    lexicalQuality: summarizeLexicalQuality(result.items),
                     resultCount: result.items.length,
                     totalCount: result.total
                 });
@@ -1341,6 +1475,7 @@ export class RecallXRepository {
                 const fallbackResult = this.searchActivitiesWithLike(input);
                 appendCurrentTelemetryDetails({
                     ftsFallback: true,
+                    lexicalQuality: summarizeLexicalQuality(fallbackResult.items),
                     resultCount: fallbackResult.items.length,
                     totalCount: fallbackResult.total
                 });
@@ -1350,6 +1485,7 @@ export class RecallXRepository {
         const result = this.searchActivitiesWithLike(input);
         appendCurrentTelemetryDetails({
             ftsFallback: false,
+            lexicalQuality: summarizeLexicalQuality(result.items),
             resultCount: result.items.length,
             totalCount: result.total
         });
@@ -1465,6 +1601,8 @@ export class RecallXRepository {
         const resolvedActivityResults = fallbackTokens.length >= 2 && includeActivities
             ? this.searchWorkspaceActivityFallback(fallbackTokens, input.activityFilters ?? {}, requestedWindow)
             : activityResults;
+        const bestNodeLexicalQuality = summarizeLexicalQuality(resolvedNodeResults.items);
+        const bestActivityLexicalQuality = summarizeLexicalQuality(resolvedActivityResults.items);
         const merged = this.mergeWorkspaceSearchResults(resolvedNodeResults.items, resolvedActivityResults.items, input.sort);
         const deterministicResult = {
             total: fallbackTokens.length >= 2
@@ -1477,6 +1615,7 @@ export class RecallXRepository {
             semanticFallbackEligible: false,
             semanticFallbackAttempted: false,
             semanticFallbackUsed: false,
+            semanticFallbackMode: includeNodes && semanticSettings.workspaceFallbackEnabled ? semanticSettings.workspaceFallbackMode : null,
             semanticFallbackCandidateCount: 0,
             semanticFallbackResultCount: 0,
             semanticFallbackBackend: null,
@@ -1485,16 +1624,31 @@ export class RecallXRepository {
             semanticFallbackQueryLengthBucket: queryPresent ? bucketSemanticQueryLength(normalizedQuery.length) : null
         };
         const appendWorkspaceSearchTelemetry = (result) => {
+            const nodeItems = result.items.flatMap((item) => item.resultType === "node" && item.node ? [item.node] : []);
+            const activityItems = result.items.flatMap((item) => item.resultType === "activity" && item.activity ? [item.activity] : []);
             appendCurrentTelemetryDetails({
+                searchHit: result.items.length > 0,
                 candidateCount: requestedWindow,
                 nodeCandidateCount: resolvedNodeResults.items.length,
                 activityCandidateCount: resolvedActivityResults.items.length,
+                nodeResultCount: nodeItems.length,
+                activityResultCount: activityItems.length,
+                bestNodeLexicalQuality,
+                bestActivityLexicalQuality,
+                lexicalNodeHit: bestNodeLexicalQuality !== "none",
+                strongNodeLexicalHit: bestNodeLexicalQuality === "strong",
+                resultComposition: computeWorkspaceResultComposition({
+                    nodeCount: nodeItems.length,
+                    activityCount: activityItems.length,
+                    semanticUsed: telemetry.semanticFallbackUsed
+                }),
                 resultCount: result.items.length,
                 totalCount: result.total,
                 fallbackTokenCount: fallbackTokens.length,
                 semanticFallbackEligible: telemetry.semanticFallbackEligible,
                 semanticFallbackAttempted: telemetry.semanticFallbackAttempted,
                 semanticFallbackUsed: telemetry.semanticFallbackUsed,
+                semanticFallbackMode: telemetry.semanticFallbackMode ?? undefined,
                 semanticFallbackCandidateCount: telemetry.semanticFallbackCandidateCount,
                 semanticFallbackResultCount: telemetry.semanticFallbackResultCount,
                 semanticFallbackBackend: telemetry.semanticFallbackBackend,
@@ -1502,13 +1656,18 @@ export class RecallXRepository {
                 semanticFallbackSkippedReason: telemetry.semanticFallbackSkippedReason
             });
         };
+        const strictZeroFallbackBlocked = resolvedNodeResults.total + resolvedActivityResults.total > 0;
+        const noStrongNodeFallbackBlocked = bestNodeLexicalQuality === "strong";
+        const semanticFallbackBlockedByMode = semanticSettings.workspaceFallbackMode === "strict_zero"
+            ? strictZeroFallbackBlocked
+            : noStrongNodeFallbackBlocked;
         const shouldAttemptSemanticFallback = includeNodes &&
             semanticSettings.workspaceFallbackEnabled &&
             queryPresent &&
             normalizedQuery.length >= 6 &&
-            deterministicResult.total === 0 &&
             semanticSettings.enabled &&
-            Boolean(semanticSettings.provider && semanticSettings.model);
+            Boolean(semanticSettings.provider && semanticSettings.model) &&
+            !semanticFallbackBlockedByMode;
         if (!includeNodes) {
             telemetry.semanticFallbackSkippedReason = "nodes_scope_disabled";
         }
@@ -1521,15 +1680,18 @@ export class RecallXRepository {
         else if (!semanticSettings.workspaceFallbackEnabled) {
             telemetry.semanticFallbackSkippedReason = "workspace_fallback_disabled";
         }
-        else if (deterministicResult.total > 0) {
-            telemetry.semanticFallbackSkippedReason = "deterministic_results_present";
-        }
         else if (!semanticSettings.enabled) {
             telemetry.semanticFallbackSkippedReason = "semantic_disabled";
         }
         else if (!semanticSettings.provider || !semanticSettings.model) {
             telemetry.semanticFallbackSkippedReason = "semantic_provider_unconfigured";
         }
+        else if (semanticSettings.workspaceFallbackMode === "strict_zero" && strictZeroFallbackBlocked) {
+            telemetry.semanticFallbackSkippedReason = "strict_zero_results_present";
+        }
+        else if (semanticSettings.workspaceFallbackMode === "no_strong_node_hit" && noStrongNodeFallbackBlocked) {
+            telemetry.semanticFallbackSkippedReason = "strong_node_lexical_present";
+        }
         if (shouldAttemptSemanticFallback) {
             const candidateNodeIds = this.listWorkspaceSemanticFallbackCandidateNodeIds(input.nodeFilters ?? {}, semanticSettings, 200);
             telemetry.semanticFallbackEligible = true;
@@ -1541,8 +1703,7 @@ export class RecallXRepository {
             else {
                 telemetry.semanticFallbackAttempted = true;
                 const runSemanticFallback = async () => {
-                    const semanticMatches = await this.rankSemanticCandidates(normalizedQuery, candidateNodeIds);
-                    const items = this.buildWorkspaceSemanticFallbackNodeItems(candidateNodeIds, semanticMatches, this.getSemanticAugmentationSettings()).map((node) => ({ resultType: "node", node }));
+                    const items = this.buildWorkspaceSemanticFallbackNodeItems(candidateNodeIds, await this.rankSemanticCandidates(normalizedQuery, candidateNodeIds), this.getSemanticAugmentationSettings());
                     return {
                         items,
                         resultCount: items.length
@@ -1554,15 +1715,18 @@ export class RecallXRepository {
                             semanticFallbackCandidateCount: candidateNodeIds.length,
                             semanticFallbackBackend: semanticSettings.indexBackend,
                             semanticFallbackConfiguredBackend: semanticSettings.configuredIndexBackend,
+                            semanticFallbackMode: telemetry.semanticFallbackMode ?? undefined,
                             semanticFallbackQueryLengthBucket: telemetry.semanticFallbackQueryLengthBucket
                         }, runSemanticFallback)
                         : await runSemanticFallback();
                     telemetry.semanticFallbackResultCount = semanticResult.resultCount;
                     if (semanticResult.resultCount > 0) {
                         telemetry.semanticFallbackUsed = true;
+                        const mergedNodeItems = mergeNodeSearchItems(semanticResult.items, resolvedNodeResults.items);
+                        const mergedSemanticItems = this.mergeWorkspaceSearchResults(mergedNodeItems, resolvedActivityResults.items, input.sort);
                         const semanticWorkspaceResult = {
-                            total: semanticResult.resultCount,
-                            items: semanticResult.items
+                            total: mergedNodeItems.length + (includeActivities ? resolvedActivityResults.total : 0),
+                            items: mergedSemanticItems.slice(input.offset, input.offset + input.limit)
                         };
                         appendWorkspaceSearchTelemetry(semanticWorkspaceResult);
                         return {
@@ -1638,6 +1802,8 @@ export class RecallXRepository {
                         timestamp: node.updatedAt,
                         resultType: "node",
                         contested: node.status === "contested",
+                        matchReason: node.matchReason,
+                        lexicalQuality: node.lexicalQuality,
                         nowMs
                     })
                     : 0
@@ -1656,6 +1822,8 @@ export class RecallXRepository {
                         timestamp: activity.createdAt,
                         resultType: "activity",
                         contested: activity.targetNodeStatus === "contested",
+                        matchReason: activity.matchReason,
+                        lexicalQuality: activity.lexicalQuality,
                         nowMs
                     })
                     : 0
@@ -1673,6 +1841,24 @@ export class RecallXRepository {
         }
         return merged.map(({ index: _index, total: _total, timestamp: _timestamp, contested: _contested, smartScore: _smartScore, ...item }) => item);
     }
+    mergeNodeSearchResults(primary, secondary) {
+        const merged = new Map();
+        for (const item of [...primary, ...secondary]) {
+            const current = merged.get(item.id);
+            if (!current) {
+                merged.set(item.id, item);
+                continue;
+            }
+            merged.set(item.id, {
+                ...current,
+                matchReason: current.matchReason?.strategy === "semantic" && item.matchReason
+                    ? item.matchReason
+                    : current.matchReason ?? item.matchReason,
+                lexicalQuality: mergeLexicalQuality(current.lexicalQuality, item.lexicalQuality)
+            });
+        }
+        return Array.from(merged.values());
+    }
     searchNodesWithFts(input) {
         const where = [];
         const values = [];
@@ -1851,23 +2037,31 @@ export class RecallXRepository {
          LIMIT ? OFFSET ?`)
             .all(...whereValues, ...params.orderValues, effectiveLimit, effectiveOffset);
         const matcher = params.strategy === "browse" ? null : createSearchFieldMatcher(params.input.query);
-        const items = rows.map((row) => ({
-            id: String(row.id),
-            targetNodeId: String(row.target_node_id),
-            targetNodeTitle: row.target_title ? String(row.target_title) : null,
-            targetNodeType: row.target_type ? row.target_type : null,
-            targetNodeStatus: row.target_status ? row.target_status : null,
-            activityType: row.activity_type,
-            body: row.body ? String(row.body) : null,
-            sourceLabel: row.source_label ? String(row.source_label) : null,
-            createdAt: String(row.created_at),
-            matchReason: buildSearchMatchReason(params.strategy, collectMatchedFields(matcher, [
+        const items = rows.map((row) => {
+            const signals = collectSearchFieldSignals(matcher, [
                 { field: "body", value: row.body ? String(row.body) : null },
                 { field: "targetNodeTitle", value: row.target_title ? String(row.target_title) : null },
                 { field: "activityType", value: row.activity_type ? String(row.activity_type) : null },
                 { field: "sourceLabel", value: row.source_label ? String(row.source_label) : null }
-            ]))
-        }));
+            ]);
+            const lexicalQuality = classifyActivityLexicalQuality(params.strategy, signals);
+            return {
+                id: String(row.id),
+                targetNodeId: String(row.target_node_id),
+                targetNodeTitle: row.target_title ? String(row.target_title) : null,
+                targetNodeType: row.target_type ? row.target_type : null,
+                targetNodeStatus: row.target_status ? row.target_status : null,
+                activityType: row.activity_type,
+                body: row.body ? String(row.body) : null,
+                sourceLabel: row.source_label ? String(row.source_label) : null,
+                createdAt: String(row.created_at),
+                lexicalQuality,
+                matchReason: buildSearchMatchReason(params.strategy, signals.matchedFields, {
+                    strength: lexicalQuality === "none" ? undefined : lexicalQuality,
+                    termCoverage: signals.totalTermCount > 0 ? Number((signals.matchedTermCount / signals.totalTermCount).toFixed(4)) : null
+                })
+            };
+        });
         const rankedItems = useSearchFeedbackBoost ? this.applyActivitySearchFeedbackBoost(items) : items;
         const cappedItems = this.capActivityResultsPerTarget(rankedItems);
         return {
@@ -1914,6 +2108,14 @@ export class RecallXRepository {
         const matcher = strategy === "browse" ? null : createSearchFieldMatcher(query);
         const items = rows.map((row) => {
             const tags = parseJson(row.tags_json, []);
+            const signals = collectSearchFieldSignals(matcher, [
+                { field: "title", value: row.title ? String(row.title) : null },
+                { field: "summary", value: row.summary ? String(row.summary) : null },
+                { field: "body", value: row.body ? String(row.body) : null },
+                { field: "tags", value: tags.join(" ") },
+                { field: "sourceLabel", value: row.source_label ? String(row.source_label) : null }
+            ]);
+            const lexicalQuality = classifyNodeLexicalQuality(strategy, signals);
             return {
                 id: String(row.id),
                 type: row.type,
@@ -1924,13 +2126,11 @@ export class RecallXRepository {
                 sourceLabel: row.source_label ? String(row.source_label) : null,
                 updatedAt: String(row.updated_at),
                 tags,
-                matchReason: buildSearchMatchReason(strategy, collectMatchedFields(matcher, [
-                    { field: "title", value: row.title ? String(row.title) : null },
-                    { field: "summary", value: row.summary ? String(row.summary) : null },
-                    { field: "body", value: row.body ? String(row.body) : null },
-                    { field: "tags", value: tags.join(" ") },
-                    { field: "sourceLabel", value: row.source_label ? String(row.source_label) : null }
-                ]))
+                lexicalQuality,
+                matchReason: buildSearchMatchReason(strategy, signals.matchedFields, {
+                    strength: lexicalQuality === "none" ? undefined : lexicalQuality,
+                    termCoverage: signals.totalTermCount > 0 ? Number((signals.matchedTermCount / signals.totalTermCount).toFixed(4)) : null
+                })
             };
         });
         const rankedItems = useSearchFeedbackBoost ? this.applySearchFeedbackBoost(items) : items;

package/app/server/workspace-session.js

@@ -76,6 +76,7 @@ export class WorkspaceSessionManager {
             "search.semantic.chunk.enabled": false,
             "search.semantic.chunk.aggregation": "max",
             "search.semantic.workspaceFallback.enabled": false,
+            "search.semantic.workspaceFallback.mode": "strict_zero",
             "search.semantic.augmentation.minSimilarity": 0.2,
             "search.semantic.augmentation.maxBonus": 18,
             "search.semantic.last_backfill_at": null,

package/app/shared/version.js

@@ -1 +1 @@
-export const RECALLX_VERSION = "1.0.0";
+export const RECALLX_VERSION = "1.0.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recallx-headless",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Headless RecallX runtime with API, CLI, and MCP entrypoint.",
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "zod": "^3.25.76"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13.0"
   },
   "keywords": [
     "recallx",