sift-light 1.0.2 → 1.0.3-2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.0.3-2 — 2026-09-30
+
+- Accept an empty `sourceCursor` placeholder outside `mode: "inspect"` by removing the key before mode validation, with the normalization disclosed in text and `details.requestNotes` ([#101](https://github.com/lightsifter/sift-light/issues/101)). Nonempty source continuation tokens still require inspection mode; empty inspection tokens and ordinary `cursor` validation retain their existing failure behavior.
+- Apply the same normalization to Pi, OMP and MCP through the shared request boundary. This fixes the reported rejected request shape without attributing the placeholder to a particular model or host.
+
+## 1.0.3-1 — 2026-09-30
+
+- Explain missing inspection paths explicitly while retaining the `source-unavailable` status for compatibility.
+- Label term counts with numbered input literals in text, structured output and continuation pages; keep anonymized labels when redaction is requested.
+- Bundle a Codex local-search skill and discovery guidance that checks the complete runtime registry, including deferred tools, before reporting sift-light unavailable.
+
 ## 1.0.2 — 2026-09-29
 
 ### Fixed

package/README.md

@@ -167,6 +167,8 @@ MCP returns readable text plus structured evidence by default. If a host seriali
 
 ### Native plugins
 
+The Codex plugin includes a `local-search` skill for discovering and calling deferred MCP tools. Before declaring the tool unavailable, inspect the host's complete runtime registry (including `ALL_TOOLS` where `functions.exec` is available), then call `mcp__sift_light__sift_light` when registered. Omission from the initial expanded declarations does not mean absence. Restart or start a new session after updating the plugin to load the new skill. MCP-only clients receive the same server guidance, but the skill discovery entry requires the native plugin.
+
 For conventional search enforcement in other hosts:
 
 - **Claude Code:** `/plugin marketplace add lightsifter/sift-light`, then `/plugin install sift-light@sift-light`.

package/README.zh-CN.md

@@ -167,6 +167,8 @@ MCP 默认同时返回可读文本和结构化证据。如果宿主会把两种
 
 ### 原生插件
 
+Codex 插件包含 `local-search` 技能，用于发现和调用延迟加载的 MCP 工具。判断工具不可用前，先检查宿主完整运行时注册表（在提供 `functions.exec` 的环境中包括 `ALL_TOOLS`），找到 `mcp__sift_light__sift_light` 后直接调用；初始声明未展开不代表工具缺失。更新插件后重启或新建会话，让宿主加载新版技能。仅配置 MCP 的客户端会收到同样的服务说明，但技能发现入口需要安装原生插件。
+
 如果希望在其他宿主中也强制常规搜索使用本插件：
 
 - **Claude Code：** 先运行 `/plugin marketplace add lightsifter/sift-light`，再运行 `/plugin install sift-light@sift-light`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.2",
+  "version": "1.0.3-2",
   "description": "Context-efficient local search for files, documents, notes and logs across Pi, OMP and MCP clients",
   "keywords": [
     "ai-agent",

package/plugins/sift-light/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.2",
+  "version": "1.0.3-2",
   "description": "Require sift-light for conventional local searches while keeping development tools available.",
   "author": {
     "name": "baoer"

package/plugins/sift-light/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.2",
+  "version": "1.0.3-2",
   "description": "Require sift-light for conventional local searches while keeping development tools available.",
   "author": {
     "name": "baoer"
@@ -8,11 +8,12 @@
   "homepage": "https://github.com/lightsifter/sift-light#readme",
   "license": "AGPL-3.0-only",
   "mcpServers": "./.mcp.json",
+  "skills": "./skills/",
   "interface": {
     "displayName": "sift-light",
     "shortDescription": "Enforced local code search",
     "longDescription": "Require sift-light for conventional local searches while keeping development tools available.",
-    "defaultPrompt": "Search this project's code using sift-light.",
+    "defaultPrompt": "Search this project's code using sift-light. Before reporting sift-light absent, check the complete runtime registry, including ALL_TOOLS deferred entries. Read mcp__sift_light__sift_light's declaration and call it via tools in functions.exec; use host tool search otherwise. Unexpanded does not mean absent; call failures are connection/capability failures.",
     "developerName": "baoer",
     "category": "Productivity",
     "capabilities": []

package/plugins/sift-light/.mcp.json

@@ -5,7 +5,7 @@
       "args": [
         "--yes",
         "--package",
-        "sift-light-runtime@npm:sift-light@1.0.2",
+        "sift-light-runtime@npm:sift-light@1.0.3-2",
         "sift-light-mcp",
         "--stdio"
       ],

package/plugins/sift-light/kimi.plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.2",
+  "version": "1.0.3-2",
   "description": "Require sift-light for conventional local searches while keeping development tools available.",
   "author": {
     "name": "baoer"
@@ -13,7 +13,7 @@
       "args": [
         "--yes",
         "--package",
-        "sift-light-runtime@npm:sift-light@1.0.2",
+        "sift-light-runtime@npm:sift-light@1.0.3-2",
         "sift-light-mcp",
         "--stdio"
       ],

package/plugins/sift-light/omp-extension.mjs

@@ -1822,7 +1822,7 @@ function createCtagsStructureProvider(options = {}) {
 // package.json
 var package_default = {
   name: "sift-light",
-  version: "1.0.2",
+  version: "1.0.3-2",
   description: "Context-efficient local search for files, documents, notes and logs across Pi, OMP and MCP clients",
   keywords: [
     "ai-agent",
@@ -3482,8 +3482,10 @@ async function readWorkspaceDocument(path, cwd, signal, expected, readBudget = M
     realpath3(cwd)
   ]);
   if (!canonical)
-    throw new SourceDocumentError("source-unavailable", "Source is unavailable");
-  const before = await getSourceRevision(absolute);
+    throw new SourceDocumentError("source-unavailable", `Path not found: ${path}`);
+  const before = await getSourceRevision(absolute, (error) => {
+    throw error;
+  });
   if (!before)
     throw new SourceDocumentError("source-unavailable", "Source is unavailable");
   if (expected && !sameSourceRevision(before, expected.revision)) {
@@ -5198,6 +5200,11 @@ var SEMANTIC_JUDGE_CLASSIFICATIONS = [
 ];
 var SEMANTIC_JUDGE_NON_PROOF_CLAIM = "semantic classification only; local static and runtime verification is not asserted";
 
+// src/term-count-label.ts
+function termCountLabel(term, index, redact = false) {
+  return redact ? `condition #${String(index + 1)}` : `#${String(index + 1)} ${JSON.stringify(term)}`;
+}
+
 // src/analysis-term-pages.ts
 var MAX_INLINE_TERM_COUNT_BYTES = 8 * 1024;
 function termCountRequest(id, offset, redact = false) {
@@ -5215,7 +5222,7 @@ function analysisTermPage(result, id, offset) {
     const term = all[index];
     if (!term)
       throw new Error("Term inventory index unavailable");
-    const label = `condition #${String(index + 1)}`;
+    const label = termCountLabel(term.term, index, result.redact);
     const row = `${label}: ${String(term.retainedOccurrences)} retained occurrences`;
     const size = Buffer.byteLength(row) + 2;
     if (bytes + size > MAX_INLINE_TERM_COUNT_BYTES)
@@ -5351,8 +5358,8 @@ function analysisExtraGroups(counts, termCounts, items) {
   const classification = counts ? statisticsGroup("classification", Object.entries(counts).map(([label, count]) => ({ label, count }))) : undefined;
   if (classification)
     groups.push(classification);
-  const terms = termCounts ? statisticsGroup("conditions", termCounts.map((term, index) => ({
-    label: `condition #${String(index + 1)}`,
+  const terms = termCounts ? statisticsGroup("conditions", termCounts.map((term) => ({
+    label: term.term,
     count: term.retainedOccurrences
   }))) : undefined;
   if (terms)
@@ -5505,9 +5512,9 @@ function publicAnalysisItem(result, item, index, storedId, modelOutput) {
     ...publicDetails ? { details: publicDetails } : {}
   };
 }
-function safeTermCounts(termCounts) {
+function safeTermCounts(termCounts, redact = false) {
   return termCounts?.map((entry, index) => ({
-    term: `condition #${String(index + 1)}`,
+    term: termCountLabel(entry.term, index, redact),
     retainedOccurrences: entry.retainedOccurrences
   }));
 }
@@ -5629,21 +5636,22 @@ class AnalysisStore {
       throw new CursorError("Analysis item is outside the retained result");
     return structuredClone(item);
   }
-  page(cursor, modelOutput = false) {
+  page(cursor, modelOutput = false, redact = false) {
     const { stored, offset, kind } = this.resolve(cursor);
-    const { result } = stored;
+    const result = redact ? { ...stored.result, redact: true } : stored.result;
     if (kind === "analysis-terms")
       return analysisTermPage(result, stored.id, offset);
     const hybridPreview = kind === "analysis-hybrid";
     const hybridMatchesRequest = hybridPreview ? { cursor: `${stored.id}.analysis.0`, ...result.redact ? { redact: true } : {} } : undefined;
-    const pagedTerms = result.termCounts && Buffer.byteLength(JSON.stringify(result.termCounts)) > MAX_INLINE_TERM_COUNT_BYTES;
-    const inlineTerms = pagedTerms ? undefined : safeTermCounts(result.termCounts);
+    const publicTerms = safeTermCounts(result.termCounts, result.redact);
+    const pagedTerms = publicTerms && Buffer.byteLength(JSON.stringify(publicTerms)) > MAX_INLINE_TERM_COUNT_BYTES;
+    const inlineTerms = pagedTerms ? undefined : publicTerms;
     const termsRequest = pagedTerms ? termCountRequest(stored.id, 0, result.redact) : undefined;
     const items = [];
     const sources = [];
     const sourceIds = new Map;
     const hybridInspectCursor = result.kind === "hybrid" ? `${stored.id}.analysis.0` : undefined;
-    const statistics = statisticsForItems(result.items, result.items.length, result.unit, analysisExtraGroups(result.counts, result.termCounts, result.items));
+    const statistics = statisticsForItems(result.items, result.items.length, result.unit, analysisExtraGroups(result.counts, inlineTerms, result.items));
     const scope = result.scope ? ` Scope: ${result.scope.assertion === "project-wide" ? "project root" : "requested path"} ${JSON.stringify(result.scope.path)}${result.scope.expandedToProjectRoot ? `, expanded after ${JSON.stringify(result.scope.requestedPath)} had no matches` : ""}.${modificationTimeBoundsText(result.scope.modifiedAfterMs, result.scope.modifiedBeforeMs)}` : "";
     const coverage = result.coverage ? ` Coverage: ${JSON.stringify(result.coverage)}.` : "";
     const stats = result.stats ? ` Stats: ${JSON.stringify(result.stats)}.` : "";
@@ -11170,7 +11178,7 @@ class EvidenceService {
       this.#analyses.resolve(input.cursor);
       if (input.mode !== undefined && input.mode !== "matches" && input.mode !== "auto")
         throw new CursorError("Analysis cursor cannot continue in the requested mode", "E_CURSOR_WRONG_KIND");
-      return this.#analyses.page(input.cursor, options.modelOutput);
+      return this.#analyses.page(input.cursor, options.modelOutput, input.redact);
     }
     if (input.mode === "outline" || input.mode === "imports" || input.mode === "tests")
       return this.#navigate(input, access, options);
@@ -11626,6 +11634,11 @@ function normalizeRequestAliases(request) {
   } else if (mode !== undefined) {
     input = { ...rest, mode };
   }
+  if (input.mode !== "inspect" && input.sourceCursor === "") {
+    const { sourceCursor: _sourceCursor, ...withoutSourceCursor } = input;
+    input = withoutSourceCursor;
+    notes.push("Empty sourceCursor is ignored outside mode=inspect.");
+  }
   if (input.sourceCursor !== undefined && input.line !== undefined) {
     const { line: _line, ...withoutLine } = input;
     input = withoutLine;
@@ -13634,16 +13647,18 @@ ${page.body}${rangeNote}${contextNote}${missingSelectionNote}
 }
 
 // src/prompt-guidelines.ts
+var SIFT_LIGHT_DISCOVERY_GUIDANCE = "Before reporting sift-light absent, check the complete runtime registry, including ALL_TOOLS deferred entries. Read mcp__sift_light__sift_light's declaration and call it via tools in functions.exec; use host tool search otherwise. Unexpanded does not mean absent; call failures are connection/capability failures.";
 var SOURCE_OUTPUT_GUIDANCE = "Auto/summary text may include bounded source excerpts; ordinary matches text is metadata-only. Inspect may return bounded source windows covering an entire small file. Analysis text may include semantic passages; structured details may retain excerpts, names and signatures. Follow output limits, coverage and continuations.";
 function siftLightPromptGuidelines(structuredOutput = true) {
   return [
+    SIFT_LIGHT_DISCOVERY_GUIDANCE,
     `Use sift-light for read-only content search. ${SOURCE_OUTPUT_GUIDANCE} For routine development searches, start with fast exact content, filename or applicable structural modes when the request has a usable name, symbol, error text or other literal clue. Omitted mode is ordinary exact search and never loads the local embedding model. Vector search is disabled by default; concept/hybrid require vectorSearchEnabled:true in sift-light.json and an installed model. They can take tens of seconds on an uncached scope, so select them only when semantic recall is needed. Omit mode and limit for automatic detail/summary selection; use mode="matches" for ordinary match metadata.`,
     `An omitted path searches the project cwd. Use scope:"strict" for a question restricted to one path; otherwise, if an explicit subpath has zero matches, ordinary and content-analysis searches retry from cwd and return project-wide counts with an expansion notice. Explicit absolute paths and .. traversal can search outside cwd, except protected external system areas and .git internals. Git changes mode remains cwd-scoped.`,
     `Search output includes counts, categories, ranked paths, coverage and continuation metadata. Source excerpts may contain the searched text. Use mode="inspect" or the host read capability when exact source is required for an edit or verification.`,
     `Use file and directory distributions to choose evidence. Reuse the visible cursor with path or paths for match metadata; mode="summary" pages the remaining file statistics. Match counts are not relevance scores.`,
     `Mode="inspect" with a direct path/line or ordinary retained match returns bounded source windows and source-revision metadata. Some retained analysis selectors return only revision metadata; use direct path/line or the host read capability when source is needed. Do not use inspection merely to obtain a citation.`,
     `Use allOf:["term1","term2"] for explicit same-file literal AND. Add within:"function" only together with allOf to restrict that conjunction to one own-implementation JS/TS/TSX function; omit within for ordinary single-pattern searches. Use roles:["declaration"] or roles:["call"] with a single pattern for JS/TS/TSX/Go syntactic occurrence statistics.`,
-    `Use anyOf:["term1","term2"] when every exact occurrence of 2-64 literals is needed in one version-bound result. It is case-sensitive, reports anonymized condition counts, and runs requests above eight terms as bounded parallel chunks. Large condition inventories have separate continuation pages; copy those requests to retrieve the complete counts.`,
+    `Use anyOf:["term1","term2"] when every exact occurrence of 1-64 literals is needed in one version-bound result. It is case-sensitive, labels counts with input literals unless redact:true is requested, and runs requests above eight terms as bounded parallel chunks. Large condition inventories have separate continuation pages; copy those requests to retrieve the complete counts.`,
     `For a changed-code question, add changes:{base:"HEAD",scope:"lines",side:"new"}; omit target for the working tree, use side:"old" for deleted-side statistics. Copy returned continuation requests to preserve source versions.`,
     `Use mode:"capabilities" when the language or requested operation is unclear to get a compact lazy inventory. Use mode:"outline" with a concrete source file path for symbol counts and locations, mode:"imports" for static relationships, and mode:"tests" for related-test candidates. Their text pages summarize metadata; structured details can retain source evidence.`,
     `Use mode:"files" plus query for unknown filenames and fuzzy paths. Multi-word filename queries require each word literally in the path; use hybrid/concept only for business concepts that cannot be located by a literal clue. Use wholeWord:true for a single-pattern whole-word search. exclude contains file globs, not content negation.`,
@@ -21057,7 +21072,7 @@ var siftLightSchema = _Object_({
     })
   })),
   sourceCursor: Optional(String2({
-    description: "Missing-source continuation token. Copy nextRequest exactly: mode=inspect plus sourceCursor only. Same token replays the same page; changed or expired sources fail clearly."
+    description: "Missing-source continuation token. Copy nextRequest exactly: mode=inspect plus sourceCursor only. Same token replays the same page; changed or expired sources fail clearly. An empty string outside mode=inspect is treated as an omitted placeholder and disclosed in request notes; nonempty tokens still require mode=inspect."
   })),
   symbol: Optional(String2({
     description: "Syntax name for outline/imports/tests; use a concrete source file and line to narrow repeated names."

package/plugins/sift-light/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.2",
+  "version": "1.0.3-2",
   "private": true,
   "type": "module",
   "omp": {

package/plugins/sift-light/skills/local-search/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: local-search
+description: Use sift-light for local project content, filenames, symbols and related tests. Before reporting its MCP unavailable, inspect the complete runtime registry including ALL_TOOLS deferred entries and load mcp__sift_light__sift_light. Applies when searching local files or diagnosing sift-light discovery; ordinary exact-path reads, edits, builds and tests do not require a search.
+---
+
+# Local search with sift-light
+
+Before reporting sift-light absent, check the complete runtime registry, including ALL_TOOLS deferred entries. Read mcp__sift_light__sift_light's declaration and call it via tools in functions.exec; use host tool search otherwise. Unexpanded does not mean absent; call failures are connection/capability failures.
+
+Use exact pattern searches for names and error text; files + query for unknown filenames; anyOf/allOf for several literal conditions. Use applicable structural modes for symbols and relationships. Select concept/hybrid only when semantic recall is needed and enabled.
+
+Read the live tool declaration before constructing the request. Copy continuation and argument-repair requests exactly; repair rejected arguments once. Inspect exact source when it is needed for the authorized task. Report partial coverage and connection failures accurately. This skill does not authorize edits, installations, configuration changes or remote actions.

package/src/analysis-store.ts

@@ -25,6 +25,7 @@ import {
 } from "./analysis-term-pages.js";
 
 import { analysisExtraGroups, statisticsForItems } from "./result-statistics.js";
+import { termCountLabel } from "./term-count-label.js";
 interface StoredAnalysis {
   id: string;
   result: AnalysisResultSet;
@@ -217,10 +218,11 @@ function publicAnalysisItem(
 }
 
 function safeTermCounts(
-  termCounts: readonly { retainedOccurrences: number }[] | undefined,
+  termCounts: readonly { term: string; retainedOccurrences: number }[] | undefined,
+  redact = false,
 ): { term: string; retainedOccurrences: number }[] | undefined {
   return termCounts?.map((entry, index) => ({
-    term: `condition #${String(index + 1)}`,
+    term: termCountLabel(entry.term, index, redact),
     retainedOccurrences: entry.retainedOccurrences,
   }));
 }
@@ -368,18 +370,18 @@ export class AnalysisStore {
     return structuredClone(item);
   }
 
-  page(cursor: string, modelOutput = false): SiftLightResult {
+  page(cursor: string, modelOutput = false, redact = false): SiftLightResult {
     const { stored, offset, kind } = this.resolve(cursor);
-    const { result } = stored;
+    const result = redact ? { ...stored.result, redact: true } : stored.result;
     if (kind === "analysis-terms") return analysisTermPage(result, stored.id, offset);
     const hybridPreview = kind === "analysis-hybrid";
     const hybridMatchesRequest = hybridPreview
       ? { cursor: `${stored.id}.analysis.0`, ...(result.redact ? { redact: true } : {}) }
       : undefined;
+    const publicTerms = safeTermCounts(result.termCounts, result.redact);
     const pagedTerms =
-      result.termCounts &&
-      Buffer.byteLength(JSON.stringify(result.termCounts)) > MAX_INLINE_TERM_COUNT_BYTES;
-    const inlineTerms = pagedTerms ? undefined : safeTermCounts(result.termCounts);
+      publicTerms && Buffer.byteLength(JSON.stringify(publicTerms)) > MAX_INLINE_TERM_COUNT_BYTES;
+    const inlineTerms = pagedTerms ? undefined : publicTerms;
     const termsRequest = pagedTerms ? termCountRequest(stored.id, 0, result.redact) : undefined;
     const items: NonNullable<SiftLightResult["details"]["analysis"]>["items"] = [];
     const sources: NonNullable<SiftLightResult["details"]["analysis"]>["sources"] = [];
@@ -389,7 +391,7 @@ export class AnalysisStore {
       result.items,
       result.items.length,
       result.unit,
-      analysisExtraGroups(result.counts, result.termCounts, result.items),
+      analysisExtraGroups(result.counts, inlineTerms, result.items),
     );
     const scope = result.scope
       ? ` Scope: ${result.scope.assertion === "project-wide" ? "project root" : "requested path"} ${JSON.stringify(result.scope.path)}${result.scope.expandedToProjectRoot ? `, expanded after ${JSON.stringify(result.scope.requestedPath)} had no matches` : ""}.${modificationTimeBoundsText(result.scope.modifiedAfterMs, result.scope.modifiedBeforeMs)}`

package/src/analysis-term-pages.ts

@@ -1,5 +1,6 @@
 import type { AnalysisResultSet } from "./analysis-types.js";
 import type { SiftLightResult } from "./types.js";
+import { termCountLabel } from "./term-count-label.js";
 
 export const MAX_INLINE_TERM_COUNT_BYTES = 8 * 1024;
 
@@ -23,7 +24,7 @@ export function analysisTermPage(
   for (let index = offset; index < all.length; index++) {
     const term = all[index];
     if (!term) throw new Error("Term inventory index unavailable");
-    const label = `condition #${String(index + 1)}`;
+    const label = termCountLabel(term.term, index, result.redact);
     const row = `${label}: ${String(term.retainedOccurrences)} retained occurrences`;
     const size = Buffer.byteLength(row) + 2;
     if (bytes + size > MAX_INLINE_TERM_COUNT_BYTES) break;

package/src/evidence-service.ts

@@ -595,7 +595,7 @@ export class EvidenceService {
           "Analysis cursor cannot continue in the requested mode",
           "E_CURSOR_WRONG_KIND",
         );
-      return this.#analyses.page(input.cursor, options.modelOutput);
+      return this.#analyses.page(input.cursor, options.modelOutput, input.redact);
     }
     if (input.mode === "outline" || input.mode === "imports" || input.mode === "tests")
       return this.#navigate(input, access, options);

package/src/mcp-server.mjs

@@ -7,7 +7,7 @@ import { URL as URL2 } from "node:url";
 // package.json
 var package_default = {
   name: "sift-light",
-  version: "1.0.2",
+  version: "1.0.3-2",
   description: "Context-efficient local search for files, documents, notes and logs across Pi, OMP and MCP clients",
   keywords: [
     "ai-agent",
@@ -270,8 +270,8 @@ function analysisExtraGroups(counts, termCounts, items) {
   const classification = counts ? statisticsGroup("classification", Object.entries(counts).map(([label, count]) => ({ label, count }))) : undefined;
   if (classification)
     groups.push(classification);
-  const terms = termCounts ? statisticsGroup("conditions", termCounts.map((term, index) => ({
-    label: `condition #${String(index + 1)}`,
+  const terms = termCounts ? statisticsGroup("conditions", termCounts.map((term) => ({
+    label: term.term,
     count: term.retainedOccurrences
   }))) : undefined;
   if (terms)
@@ -4152,8 +4152,10 @@ async function readWorkspaceDocument(path, cwd, signal, expected, readBudget = M
     realpath3(cwd)
   ]);
   if (!canonical)
-    throw new SourceDocumentError("source-unavailable", "Source is unavailable");
-  const before = await getSourceRevision(absolute);
+    throw new SourceDocumentError("source-unavailable", `Path not found: ${path}`);
+  const before = await getSourceRevision(absolute, (error) => {
+    throw error;
+  });
   if (!before)
     throw new SourceDocumentError("source-unavailable", "Source is unavailable");
   if (expected && !sameSourceRevision(before, expected.revision)) {
@@ -5707,6 +5709,11 @@ var SEMANTIC_JUDGE_CLASSIFICATIONS = [
 ];
 var SEMANTIC_JUDGE_NON_PROOF_CLAIM = "semantic classification only; local static and runtime verification is not asserted";
 
+// src/term-count-label.ts
+function termCountLabel(term, index, redact = false) {
+  return redact ? `condition #${String(index + 1)}` : `#${String(index + 1)} ${JSON.stringify(term)}`;
+}
+
 // src/analysis-term-pages.ts
 var MAX_INLINE_TERM_COUNT_BYTES = 8 * 1024;
 function termCountRequest(id, offset, redact = false) {
@@ -5724,7 +5731,7 @@ function analysisTermPage(result, id, offset) {
     const term = all[index];
     if (!term)
       throw new Error("Term inventory index unavailable");
-    const label = `condition #${String(index + 1)}`;
+    const label = termCountLabel(term.term, index, result.redact);
     const row = `${label}: ${String(term.retainedOccurrences)} retained occurrences`;
     const size = Buffer.byteLength(row) + 2;
     if (bytes + size > MAX_INLINE_TERM_COUNT_BYTES)
@@ -5911,9 +5918,9 @@ function publicAnalysisItem(result, item, index, storedId, modelOutput) {
     ...publicDetails ? { details: publicDetails } : {}
   };
 }
-function safeTermCounts(termCounts) {
+function safeTermCounts(termCounts, redact = false) {
   return termCounts?.map((entry, index) => ({
-    term: `condition #${String(index + 1)}`,
+    term: termCountLabel(entry.term, index, redact),
     retainedOccurrences: entry.retainedOccurrences
   }));
 }
@@ -6035,21 +6042,22 @@ class AnalysisStore {
       throw new CursorError("Analysis item is outside the retained result");
     return structuredClone(item);
   }
-  page(cursor, modelOutput = false) {
+  page(cursor, modelOutput = false, redact = false) {
     const { stored, offset, kind } = this.resolve(cursor);
-    const { result } = stored;
+    const result = redact ? { ...stored.result, redact: true } : stored.result;
     if (kind === "analysis-terms")
       return analysisTermPage(result, stored.id, offset);
     const hybridPreview = kind === "analysis-hybrid";
     const hybridMatchesRequest = hybridPreview ? { cursor: `${stored.id}.analysis.0`, ...result.redact ? { redact: true } : {} } : undefined;
-    const pagedTerms = result.termCounts && Buffer.byteLength(JSON.stringify(result.termCounts)) > MAX_INLINE_TERM_COUNT_BYTES;
-    const inlineTerms = pagedTerms ? undefined : safeTermCounts(result.termCounts);
+    const publicTerms = safeTermCounts(result.termCounts, result.redact);
+    const pagedTerms = publicTerms && Buffer.byteLength(JSON.stringify(publicTerms)) > MAX_INLINE_TERM_COUNT_BYTES;
+    const inlineTerms = pagedTerms ? undefined : publicTerms;
     const termsRequest = pagedTerms ? termCountRequest(stored.id, 0, result.redact) : undefined;
     const items = [];
     const sources = [];
     const sourceIds = new Map;
     const hybridInspectCursor = result.kind === "hybrid" ? `${stored.id}.analysis.0` : undefined;
-    const statistics = statisticsForItems(result.items, result.items.length, result.unit, analysisExtraGroups(result.counts, result.termCounts, result.items));
+    const statistics = statisticsForItems(result.items, result.items.length, result.unit, analysisExtraGroups(result.counts, inlineTerms, result.items));
     const scope = result.scope ? ` Scope: ${result.scope.assertion === "project-wide" ? "project root" : "requested path"} ${JSON.stringify(result.scope.path)}${result.scope.expandedToProjectRoot ? `, expanded after ${JSON.stringify(result.scope.requestedPath)} had no matches` : ""}.${modificationTimeBoundsText(result.scope.modifiedAfterMs, result.scope.modifiedBeforeMs)}` : "";
     const coverage = result.coverage ? ` Coverage: ${JSON.stringify(result.coverage)}.` : "";
     const stats = result.stats ? ` Stats: ${JSON.stringify(result.stats)}.` : "";
@@ -11202,7 +11210,7 @@ class EvidenceService {
       this.#analyses.resolve(input.cursor);
       if (input.mode !== undefined && input.mode !== "matches" && input.mode !== "auto")
         throw new CursorError("Analysis cursor cannot continue in the requested mode", "E_CURSOR_WRONG_KIND");
-      return this.#analyses.page(input.cursor, options.modelOutput);
+      return this.#analyses.page(input.cursor, options.modelOutput, input.redact);
     }
     if (input.mode === "outline" || input.mode === "imports" || input.mode === "tests")
       return this.#navigate(input, access, options);
@@ -11658,6 +11666,11 @@ function normalizeRequestAliases(request) {
   } else if (mode !== undefined) {
     input = { ...rest, mode };
   }
+  if (input.mode !== "inspect" && input.sourceCursor === "") {
+    const { sourceCursor: _sourceCursor, ...withoutSourceCursor } = input;
+    input = withoutSourceCursor;
+    notes.push("Empty sourceCursor is ignored outside mode=inspect.");
+  }
   if (input.sourceCursor !== undefined && input.line !== undefined) {
     const { line: _line, ...withoutLine } = input;
     input = withoutLine;
@@ -13666,16 +13679,18 @@ ${page.body}${rangeNote}${contextNote}${missingSelectionNote}
 }
 
 // src/prompt-guidelines.ts
+var SIFT_LIGHT_DISCOVERY_GUIDANCE = "Before reporting sift-light absent, check the complete runtime registry, including ALL_TOOLS deferred entries. Read mcp__sift_light__sift_light's declaration and call it via tools in functions.exec; use host tool search otherwise. Unexpanded does not mean absent; call failures are connection/capability failures.";
 var SOURCE_OUTPUT_GUIDANCE = "Auto/summary text may include bounded source excerpts; ordinary matches text is metadata-only. Inspect may return bounded source windows covering an entire small file. Analysis text may include semantic passages; structured details may retain excerpts, names and signatures. Follow output limits, coverage and continuations.";
 function siftLightPromptGuidelines(structuredOutput = true) {
   return [
+    SIFT_LIGHT_DISCOVERY_GUIDANCE,
     `Use sift-light for read-only content search. ${SOURCE_OUTPUT_GUIDANCE} For routine development searches, start with fast exact content, filename or applicable structural modes when the request has a usable name, symbol, error text or other literal clue. Omitted mode is ordinary exact search and never loads the local embedding model. Vector search is disabled by default; concept/hybrid require vectorSearchEnabled:true in sift-light.json and an installed model. They can take tens of seconds on an uncached scope, so select them only when semantic recall is needed. Omit mode and limit for automatic detail/summary selection; use mode="matches" for ordinary match metadata.`,
     `An omitted path searches the project cwd. Use scope:"strict" for a question restricted to one path; otherwise, if an explicit subpath has zero matches, ordinary and content-analysis searches retry from cwd and return project-wide counts with an expansion notice. Explicit absolute paths and .. traversal can search outside cwd, except protected external system areas and .git internals. Git changes mode remains cwd-scoped.`,
     `Search output includes counts, categories, ranked paths, coverage and continuation metadata. Source excerpts may contain the searched text. Use mode="inspect" or the host read capability when exact source is required for an edit or verification.`,
     `Use file and directory distributions to choose evidence. Reuse the visible cursor with path or paths for match metadata; mode="summary" pages the remaining file statistics. Match counts are not relevance scores.`,
     `Mode="inspect" with a direct path/line or ordinary retained match returns bounded source windows and source-revision metadata. Some retained analysis selectors return only revision metadata; use direct path/line or the host read capability when source is needed. Do not use inspection merely to obtain a citation.`,
     `Use allOf:["term1","term2"] for explicit same-file literal AND. Add within:"function" only together with allOf to restrict that conjunction to one own-implementation JS/TS/TSX function; omit within for ordinary single-pattern searches. Use roles:["declaration"] or roles:["call"] with a single pattern for JS/TS/TSX/Go syntactic occurrence statistics.`,
-    `Use anyOf:["term1","term2"] when every exact occurrence of 2-64 literals is needed in one version-bound result. It is case-sensitive, reports anonymized condition counts, and runs requests above eight terms as bounded parallel chunks. Large condition inventories have separate continuation pages; copy those requests to retrieve the complete counts.`,
+    `Use anyOf:["term1","term2"] when every exact occurrence of 1-64 literals is needed in one version-bound result. It is case-sensitive, labels counts with input literals unless redact:true is requested, and runs requests above eight terms as bounded parallel chunks. Large condition inventories have separate continuation pages; copy those requests to retrieve the complete counts.`,
     `For a changed-code question, add changes:{base:"HEAD",scope:"lines",side:"new"}; omit target for the working tree, use side:"old" for deleted-side statistics. Copy returned continuation requests to preserve source versions.`,
     `Use mode:"capabilities" when the language or requested operation is unclear to get a compact lazy inventory. Use mode:"outline" with a concrete source file path for symbol counts and locations, mode:"imports" for static relationships, and mode:"tests" for related-test candidates. Their text pages summarize metadata; structured details can retain source evidence.`,
     `Use mode:"files" plus query for unknown filenames and fuzzy paths. Multi-word filename queries require each word literally in the path; use hybrid/concept only for business concepts that cannot be located by a literal clue. Use wholeWord:true for a single-pattern whole-word search. exclude contains file globs, not content negation.`,
@@ -13689,10 +13704,12 @@ function siftLightPromptGuidelines(structuredOutput = true) {
 }
 function siftLightModelGuidelines() {
   return [
-    `Search with pattern and optional path. ${SOURCE_OUTPUT_GUIDANCE} Default search is exact and model-free. concept/hybrid require vectorSearchEnabled:true in sift-light.json plus an installed model; uncached runs may take tens of seconds. Omit mode/limit for auto pages.`,
-    `Use ranked paths and counts; Cursor continuation pages retained results. Use mode="inspect" for exact source before editing.`,
-    `Modes: files+query for filenames; anyOf/allOf for literals; outline/imports/tests for static code; structure for AST; concept/hybrid for semantic candidates. Similarity is not proof.`,
-    `On rejection keep the strongest applicable mode and apply the stated repair once. Do not repeat the rejected request or include its error. Only explicit capability-unavailable permits a visibly partial alternative.`
+    SIFT_LIGHT_DISCOVERY_GUIDANCE,
+    `pattern + path: exact, model-free; omit mode/limit for auto. concept/hybrid need vectorSearchEnabled:true and an installed model; cold runs take tens of seconds.`,
+    `Auto/summary may quote source; matches: metadata-only. Inspect: bounded source, including an entire small file. Analysis may retain passages/names/signatures. Follow limits and coverage.`,
+    `Use ranked counts and paths. Cursor continuation pages retained results; inspect exact source before editing.`,
+    `files+query: filenames; anyOf/allOf: literals; outline/imports/tests: static code; structure: AST; concept/hybrid: semantic candidates, not proof.`,
+    `On rejection keep the strongest mode; repair once, without repeating request/error. Only explicit capability-unavailable permits a visibly partial alternative.`
   ];
 }
 function siftLightMcpInstructions(outputMode = DEFAULT_MCP_OUTPUT_MODE) {
@@ -13769,7 +13786,7 @@ var siftLightSchema = Type.Object({
     })
   })),
   sourceCursor: Type.Optional(Type.String({
-    description: "Missing-source continuation token. Copy nextRequest exactly: mode=inspect plus sourceCursor only. Same token replays the same page; changed or expired sources fail clearly."
+    description: "Missing-source continuation token. Copy nextRequest exactly: mode=inspect plus sourceCursor only. Same token replays the same page; changed or expired sources fail clearly. An empty string outside mode=inspect is treated as an omitted placeholder and disclosed in request notes; nonempty tokens still require mode=inspect."
   })),
   symbol: Type.Optional(Type.String({
     description: "Syntax name for outline/imports/tests; use a concrete source file and line to narrow repeated names."

package/src/prompt-guidelines.ts

@@ -1,17 +1,21 @@
 import { DEFAULT_MCP_OUTPUT_MODE, type SiftLightMcpOutputMode } from "./mcp-output.js";
 
+export const SIFT_LIGHT_DISCOVERY_GUIDANCE =
+  "Before reporting sift-light absent, check the complete runtime registry, including ALL_TOOLS deferred entries. Read mcp__sift_light__sift_light's declaration and call it via tools in functions.exec; use host tool search otherwise. Unexpanded does not mean absent; call failures are connection/capability failures.";
+
 const SOURCE_OUTPUT_GUIDANCE =
   "Auto/summary text may include bounded source excerpts; ordinary matches text is metadata-only. Inspect may return bounded source windows covering an entire small file. Analysis text may include semantic passages; structured details may retain excerpts, names and signatures. Follow output limits, coverage and continuations.";
 
 export function siftLightPromptGuidelines(structuredOutput = true): string[] {
   return [
+    SIFT_LIGHT_DISCOVERY_GUIDANCE,
     `Use sift-light for read-only content search. ${SOURCE_OUTPUT_GUIDANCE} For routine development searches, start with fast exact content, filename or applicable structural modes when the request has a usable name, symbol, error text or other literal clue. Omitted mode is ordinary exact search and never loads the local embedding model. Vector search is disabled by default; concept/hybrid require vectorSearchEnabled:true in sift-light.json and an installed model. They can take tens of seconds on an uncached scope, so select them only when semantic recall is needed. Omit mode and limit for automatic detail/summary selection; use mode="matches" for ordinary match metadata.`,
     `An omitted path searches the project cwd. Use scope:"strict" for a question restricted to one path; otherwise, if an explicit subpath has zero matches, ordinary and content-analysis searches retry from cwd and return project-wide counts with an expansion notice. Explicit absolute paths and .. traversal can search outside cwd, except protected external system areas and .git internals. Git changes mode remains cwd-scoped.`,
     `Search output includes counts, categories, ranked paths, coverage and continuation metadata. Source excerpts may contain the searched text. Use mode="inspect" or the host read capability when exact source is required for an edit or verification.`,
     `Use file and directory distributions to choose evidence. Reuse the visible cursor with path or paths for match metadata; mode="summary" pages the remaining file statistics. Match counts are not relevance scores.`,
     `Mode="inspect" with a direct path/line or ordinary retained match returns bounded source windows and source-revision metadata. Some retained analysis selectors return only revision metadata; use direct path/line or the host read capability when source is needed. Do not use inspection merely to obtain a citation.`,
     `Use allOf:["term1","term2"] for explicit same-file literal AND. Add within:"function" only together with allOf to restrict that conjunction to one own-implementation JS/TS/TSX function; omit within for ordinary single-pattern searches. Use roles:["declaration"] or roles:["call"] with a single pattern for JS/TS/TSX/Go syntactic occurrence statistics.`,
-    `Use anyOf:["term1","term2"] when every exact occurrence of 2-64 literals is needed in one version-bound result. It is case-sensitive, reports anonymized condition counts, and runs requests above eight terms as bounded parallel chunks. Large condition inventories have separate continuation pages; copy those requests to retrieve the complete counts.`,
+    `Use anyOf:["term1","term2"] when every exact occurrence of 1-64 literals is needed in one version-bound result. It is case-sensitive, labels counts with input literals unless redact:true is requested, and runs requests above eight terms as bounded parallel chunks. Large condition inventories have separate continuation pages; copy those requests to retrieve the complete counts.`,
     `For a changed-code question, add changes:{base:"HEAD",scope:"lines",side:"new"}; omit target for the working tree, use side:"old" for deleted-side statistics. Copy returned continuation requests to preserve source versions.`,
     `Use mode:"capabilities" when the language or requested operation is unclear to get a compact lazy inventory. Use mode:"outline" with a concrete source file path for symbol counts and locations, mode:"imports" for static relationships, and mode:"tests" for related-test candidates. Their text pages summarize metadata; structured details can retain source evidence.`,
     `Use mode:"files" plus query for unknown filenames and fuzzy paths. Multi-word filename queries require each word literally in the path; use hybrid/concept only for business concepts that cannot be located by a literal clue. Use wholeWord:true for a single-pattern whole-word search. exclude contains file globs, not content negation.`,
@@ -28,10 +32,12 @@ export function siftLightPromptGuidelines(structuredOutput = true): string[] {
 
 function siftLightModelGuidelines(): string[] {
   return [
-    `Search with pattern and optional path. ${SOURCE_OUTPUT_GUIDANCE} Default search is exact and model-free. concept/hybrid require vectorSearchEnabled:true in sift-light.json plus an installed model; uncached runs may take tens of seconds. Omit mode/limit for auto pages.`,
-    `Use ranked paths and counts; Cursor continuation pages retained results. Use mode="inspect" for exact source before editing.`,
-    `Modes: files+query for filenames; anyOf/allOf for literals; outline/imports/tests for static code; structure for AST; concept/hybrid for semantic candidates. Similarity is not proof.`,
-    `On rejection keep the strongest applicable mode and apply the stated repair once. Do not repeat the rejected request or include its error. Only explicit capability-unavailable permits a visibly partial alternative.`,
+    SIFT_LIGHT_DISCOVERY_GUIDANCE,
+    `pattern + path: exact, model-free; omit mode/limit for auto. concept/hybrid need vectorSearchEnabled:true and an installed model; cold runs take tens of seconds.`,
+    `Auto/summary may quote source; matches: metadata-only. Inspect: bounded source, including an entire small file. Analysis may retain passages/names/signatures. Follow limits and coverage.`,
+    `Use ranked counts and paths. Cursor continuation pages retained results; inspect exact source before editing.`,
+    `files+query: filenames; anyOf/allOf: literals; outline/imports/tests: static code; structure: AST; concept/hybrid: semantic candidates, not proof.`,
+    `On rejection keep the strongest mode; repair once, without repeating request/error. Only explicit capability-unavailable permits a visibly partial alternative.`,
   ];
 }
 

package/src/request-aliases.ts

@@ -39,6 +39,11 @@ export function normalizeRequestAliases(request: SiftLightRequest): NormalizedRe
   } else if (mode !== undefined) {
     input = { ...rest, mode };
   }
+  if (input.mode !== "inspect" && input.sourceCursor === "") {
+    const { sourceCursor: _sourceCursor, ...withoutSourceCursor } = input;
+    input = withoutSourceCursor;
+    notes.push("Empty sourceCursor is ignored outside mode=inspect.");
+  }
   if (input.sourceCursor !== undefined && input.line !== undefined) {
     const { line: _line, ...withoutLine } = input;
     input = withoutLine;

package/src/result-statistics.ts

@@ -145,7 +145,7 @@ export function formatStatistics(
 
 export function analysisExtraGroups(
   counts: Record<string, number> | undefined,
-  termCounts: readonly { retainedOccurrences: number }[] | undefined,
+  termCounts: readonly { term: string; retainedOccurrences: number }[] | undefined,
   items: readonly AnalysisItem[],
 ): StatisticsGroup[] {
   const groups: StatisticsGroup[] = [];
@@ -159,8 +159,8 @@ export function analysisExtraGroups(
   const terms = termCounts
     ? statisticsGroup(
         "conditions",
-        termCounts.map((term, index) => ({
-          label: `condition #${String(index + 1)}`,
+        termCounts.map((term) => ({
+          label: term.term,
           count: term.retainedOccurrences,
         })),
       )

package/src/source-document.ts

@@ -216,8 +216,10 @@ export async function readWorkspaceDocument(
     new SearchPathPolicy(cwd).resolveExistingPath(absolute),
     realpath(cwd),
   ]);
-  if (!canonical) throw new SourceDocumentError("source-unavailable", "Source is unavailable");
-  const before = await getSourceRevision(absolute);
+  if (!canonical) throw new SourceDocumentError("source-unavailable", `Path not found: ${path}`);
+  const before = await getSourceRevision(absolute, (error) => {
+    throw error;
+  });
   if (!before) throw new SourceDocumentError("source-unavailable", "Source is unavailable");
   if (expected && !sameSourceRevision(before, expected.revision)) {
     throw new SourceDocumentError("source-changed", "Source changed; start a new inspection");

package/src/term-count-label.ts

@@ -0,0 +1,6 @@
+/** Input literals are query metadata; hide them only when redaction is requested. */
+export function termCountLabel(term: string, index: number, redact = false): string {
+  return redact
+    ? `condition #${String(index + 1)}`
+    : `#${String(index + 1)} ${JSON.stringify(term)}`;
+}

package/src/tool-schema.ts

@@ -127,7 +127,7 @@ export const siftLightSchema = Type.Object({
   sourceCursor: Type.Optional(
     Type.String({
       description:
-        "Missing-source continuation token. Copy nextRequest exactly: mode=inspect plus sourceCursor only. Same token replays the same page; changed or expired sources fail clearly.",
+        "Missing-source continuation token. Copy nextRequest exactly: mode=inspect plus sourceCursor only. Same token replays the same page; changed or expired sources fail clearly. An empty string outside mode=inspect is treated as an omitted placeholder and disclosed in request notes; nonempty tokens still require mode=inspect.",
     }),
   ),
   symbol: Type.Optional(