knodin 0.8.6 → 0.8.7

package/README.md

@@ -1,5 +1,11 @@
 # knodin
 
+For an approval-gated, evidence-first way to declare a multi-repository system, use the sanitized [assistant prompt](docs/prompts/declare-multi-repository-system.md).
+
+`knodin init` installs focused `knodin-*` assistant skills for detected Codex,
+Claude, and Gemini clients. Use `knodin skills list|install|remove|doctor` to
+inspect or manage them explicitly; CLI-only scope installs none.
+
 <img src="https://cdn.jsdelivr.net/npm/knodin@latest/docs/assets/knodin-favicon.svg" alt="knodin caret-beak logo" width="96" height="96">
 
 > Local code intelligence that remembers how your code connects—and shows what

package/dist/bin/cli.js

@@ -46,7 +46,9 @@ import { runRepositoryInitializationProcess } from "../src/repository-init-proce
 import { detectRepositorySignals, discoverRepositories, formatRepositoryHuman, initializeRepositories, inventoryRepository, parseFleetInitArgs, parseRepositoryCommandArgs, repositorySignalInspectionLimit, searchRepositories, withRepositorySignals, } from "../src/repository-management.js";
 import { applyResponseBudget } from "../src/response-budget.js";
 import { appendSessionEvent, clearSessionTelemetry, disableSessionTelemetry, enableSessionTelemetry, readSessionEvents, sessionTelemetryStatus, } from "../src/session-telemetry.js";
+import { inspectKnodinSkills, installKnodinSkills, KNODIN_SKILLS, removeKnodinSkills, } from "../src/skill-management.js";
 import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../src/system-config.js";
+import { applySystemPlan, planSystemImport, planSystemLink, planSystemRelate, planSystemUnlink, planSystemUnrelate, } from "../src/system-management.js";
 import { applyTrustedUpdate, checkTrustedUpdate, claimScheduledUpdateCheck, detectUpdateInstallMethod, explainTrustedUpdate, releaseScheduledUpdateCheck, rollbackTrustedUpdate, trustedUpdateStatus, } from "../src/update-policy.js";
 import { KNODIN_VERSION } from "../src/version.js";
 import { writeVisualization, } from "../src/visualization.js";
@@ -643,7 +645,6 @@ async function main() {
         process.send?.({ type: "rss", rssBytes: process.memoryUsage().rss });
         const engine = createEngine({ watcher: "disabled" });
         try {
-            const systemConfig = loadSystemConfiguration(repository);
             const summary = await initializeRepositories([repository], {
                 // A portfolio worker owns exactly one already-discovered worktree.
                 // Do not recursively initialize nested repositories inside the same
@@ -654,7 +655,7 @@ async function main() {
                 index: (target) => engine.index(target),
                 status: (target) => engine.status(target),
                 agents: detectSupportedAgents(),
-                indexMode: (target) => indexModeForPath(systemConfig, target),
+                indexMode: (target) => indexModeForPath(loadSystemConfiguration(target), target),
             });
             const result = summary.results.find(({ repository: target }) => target === repository);
             if (!result)
@@ -805,7 +806,6 @@ async function main() {
                 linkedWorktrees: plan.linkedWorktrees,
             });
             const engine = createEngine({ watcher: "disabled" });
-            const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
             const repositories = [];
             const discoveryRecords = plan.signals
                 ? discovery.repositories.slice(0, repositorySignalInspectionLimit(plan))
@@ -813,7 +813,7 @@ async function main() {
             for (const record of discoveryRecords) {
                 const inventory = await inventoryRepository(record, {
                     status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
-                    systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+                    systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(target), target),
                 });
                 repositories.push(withRepositorySignals(inventory, plan.signals, plan.signals ? await detectRepositorySignals(record.path) : {}));
             }
@@ -910,7 +910,6 @@ async function main() {
         }
         if (plan.command === "search") {
             const engine = createEngine({ watcher: "disabled" });
-            const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
             const output = await searchRepositories(plan.roots, plan.query ?? "", {
                 depth: plan.depth,
                 linkedWorktrees: plan.linkedWorktrees,
@@ -927,7 +926,7 @@ async function main() {
                     includeSource: true,
                     federate: false,
                 }),
-                systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+                systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(target), target),
             });
             await engine.close();
             process.stdout.write(`${JSON.stringify(output, null, plan.json ? 0 : 2)}\n`);
@@ -1628,13 +1627,119 @@ async function main() {
             break;
         }
         case "system": {
-            const allowPartial = rest.includes("--allow-partial");
-            const [action, systemId, ...unsupported] = rest.filter((argument) => argument !== "--allow-partial");
+            const requestedAction = invocation.commandPath[1];
+            if (requestedAction === "link") {
+                const [systemId, ...repositories] = invocation.positionals;
+                if (!systemId)
+                    throw new Error("knodin system link requires <system-id>");
+                const overrides = Object.fromEntries((Array.isArray(invocation.options.repositoryId) ? invocation.options.repositoryId : [])
+                    .map(String)
+                    .map((value) => {
+                    const at = value.lastIndexOf("=");
+                    if (at < 1)
+                        throw new Error("--repository-id must be <path>=<id>");
+                    return [value.slice(0, at), value.slice(at + 1)];
+                }));
+                const componentOverrides = Object.fromEntries((Array.isArray(invocation.options.component) ? invocation.options.component : [])
+                    .map(String)
+                    .map((value) => {
+                    const at = value.indexOf("=");
+                    if (at < 1)
+                        throw new Error("--component must be <repo-id>=<component-id>[:type]");
+                    const repositoryId = value.slice(0, at);
+                    const [id, componentType] = value.slice(at + 1).split(":");
+                    if (!id)
+                        throw new Error("--component requires a component id");
+                    if (componentType &&
+                        !["component", "api", "resource", "artifact"].includes(componentType))
+                        throw new Error(`--component: unsupported type ${componentType}`);
+                    return [
+                        repositoryId,
+                        {
+                            id,
+                            type: componentType,
+                        },
+                    ];
+                }));
+                if (invocation.options.initMissing === true && invocation.options.dryRun !== true) {
+                    for (const checkout of repositories.map((value) => path.resolve(repo, value))) {
+                        if (fs.existsSync(path.join(checkout, ".knodin")))
+                            continue;
+                        await initializeRepository(checkout, {
+                            command: runtimeCommand,
+                            index: (target, indexOptions) => engine.index(target, undefined, false, indexOptions),
+                            scope: "personal",
+                            agents: [],
+                        });
+                    }
+                }
+                const plan = planSystemLink({
+                    systemId,
+                    repositories,
+                    scope: invocation.options.scope === "team" ? "team" : "personal",
+                    distributed: invocation.options.distributed === true,
+                    repositoryIds: overrides,
+                    components: componentOverrides,
+                });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            if (requestedAction === "relate") {
+                const [systemId] = invocation.positionals;
+                if (!systemId)
+                    throw new Error("knodin system relate requires <system-id>");
+                const plan = planSystemRelate({
+                    systemId,
+                    type: String(invocation.options.type),
+                    from: String(invocation.options.from),
+                    to: String(invocation.options.to),
+                    evidence: String(invocation.options.evidence),
+                    repoPath: repo,
+                });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            if (requestedAction === "unlink") {
+                const [systemId, ...repositories] = invocation.positionals;
+                if (!systemId)
+                    throw new Error("knodin system unlink requires <system-id>");
+                const plan = planSystemUnlink({ systemId, repositories, repoPath: repo });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            if (requestedAction === "unrelate") {
+                const [systemId] = invocation.positionals;
+                if (!systemId)
+                    throw new Error("knodin system unrelate requires <system-id>");
+                const plan = planSystemUnrelate({
+                    systemId,
+                    type: String(invocation.options.type),
+                    from: String(invocation.options.from),
+                    to: String(invocation.options.to),
+                    repoPath: repo,
+                });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            if (requestedAction === "import") {
+                const [manifestPath] = invocation.positionals;
+                if (!manifestPath)
+                    throw new Error("knodin system import requires <path>");
+                const plan = planSystemImport({
+                    manifestPath,
+                    scope: invocation.options.scope === "team" ? "team" : "personal",
+                    repoPath: repo,
+                });
+                result = invocation.options.dryRun === true ? plan : applySystemPlan(plan);
+                break;
+            }
+            const requireComplete = rest.includes("--require-complete");
+            const [action, systemId, ...unsupported] = rest.filter((argument) => argument !== "--allow-partial" && argument !== "--require-complete");
             if (!action || !["list", "show", "validate", "query"].includes(action)) {
                 throw new Error("knodin system requires list, show, validate, or query");
             }
-            if (allowPartial && action !== "query")
-                throw new Error(`knodin system ${action}: --allow-partial applies only to query`);
+            if (requireComplete && action !== "query")
+                throw new Error(`knodin system ${action}: --require-complete applies only to query`);
             if (unsupported.length > 0)
                 throw new Error(`knodin system ${action}: unknown argument ${unsupported[0]}`);
             const config = await enrichSystemRelationships(loadSystemConfiguration(repo));
@@ -1673,12 +1778,49 @@ async function main() {
             }
             else {
                 const validation = await validateSystemHealth(config, systemId, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })), repo);
-                result = queryConfiguredSystem(config, systemId, allowPartial, validation);
+                result = queryConfiguredSystem(config, systemId, requireComplete, validation);
                 if (result.status === "unavailable")
                     process.exitCode = 1;
             }
             break;
         }
+        case "skills": {
+            const action = invocation.commandPath[1];
+            const requested = Array.isArray(invocation.options.client)
+                ? invocation.options.client.map(String)
+                : [];
+            const supported = new Set(["codex", "claude", "gemini"]);
+            for (const client of requested)
+                if (!supported.has(client))
+                    throw new Error(`knodin skills: unsupported client ${client}`);
+            const clients = (requested.length ? requested : ["codex", "claude", "gemini"]);
+            const scope = typeof invocation.options.scope === "string"
+                ? parseInitScope(invocation.options.scope)
+                : "personal";
+            if (action === "list") {
+                result = { skills: KNODIN_SKILLS, clients, scope };
+                break;
+            }
+            if (action === "install")
+                result = installKnodinSkills({
+                    repo,
+                    scope,
+                    clients,
+                    dryRun: invocation.options.dryRun === true,
+                });
+            else if (action === "remove")
+                result = removeKnodinSkills({
+                    repo,
+                    scope,
+                    clients,
+                    dryRun: invocation.options.dryRun === true,
+                });
+            else if (action === "doctor")
+                result = inspectKnodinSkills({ repo, scope, clients });
+            else
+                throw new Error("knodin skills requires list, install, remove, or doctor");
+            break;
+        }
         case "hook-refresh": {
             const [kind, first, second] = rest;
             let event;

package/dist/src/cli-model.js

@@ -295,8 +295,38 @@ function createCliProgram(capture = () => { }) {
     for (const action of ["show", "validate", "query"]) {
         const command = leaf(system, `${action} <system-id>`, `${action} one configured system`, capture);
         if (action === "query")
-            command.option("--allow-partial", "return healthy components");
+            command
+                .option("--require-complete", "fail unless every declared repository is available")
+                .option("--allow-partial", "compatibility alias; partial results are now the default");
     }
+    leaf(system, "link <system-id> <repos...>", "declare repositories as one system", capture)
+        .option("--scope <scope>", "personal or team", "personal")
+        .option("--distributed", "write a team fragment to every selected repository")
+        .addOption(option("--repository-id <path=id>", "override a derived repository id", "collect"))
+        .addOption(option("--component <repo=id[:type]>", "override a component id and type", "collect"))
+        .option("--init-missing", "initialize repositories that do not yet have knodin lifecycle state")
+        .option("--dry-run", "preview exact files and semantic changes");
+    leaf(system, "relate <system-id>", "add an explicit evidenced relationship", capture)
+        .requiredOption("--type <type>", "relationship type")
+        .requiredOption("--from <component>", "source component")
+        .requiredOption("--to <component>", "target component")
+        .requiredOption("--evidence <repo:path:line>", "checked-in relationship evidence")
+        .option("--dry-run", "preview exact files and semantic changes");
+    leaf(system, "unlink <system-id> [repos...]", "remove repositories or a whole system", capture).option("--dry-run", "preview exact files and semantic changes");
+    leaf(system, "unrelate <system-id>", "remove an explicit relationship", capture)
+        .requiredOption("--type <type>", "relationship type")
+        .requiredOption("--from <component>", "source component")
+        .requiredOption("--to <component>", "target component")
+        .option("--dry-run", "preview exact files and semantic changes");
+    leaf(system, "import <path>", "register an existing system manifest", capture)
+        .option("--scope <scope>", "personal or team", "personal")
+        .option("--dry-run", "preview exact files and semantic changes");
+    const skills = program.command("skills").description("manage packaged knodin assistant skills");
+    for (const action of ["list", "install", "remove", "doctor"])
+        leaf(skills, action, `${action} knodin assistant skills`, capture)
+            .option("--scope <scope>", "personal, team, or cli-only")
+            .addOption(option("--client <client>", "codex, claude, or gemini", "collect"))
+            .option("--dry-run", "preview skill changes without writing");
     const update = program
         .command("update")
         .description("inspect or apply threshold-signed updates")

package/dist/src/init.js

@@ -7,6 +7,7 @@ import { compareBytes } from "./compare.js";
 import { isIndexableSourcePath } from "./engine/source-policy.js";
 import { lookupMirror } from "./engine/state-paths.js";
 import { inspectLefthookIntegration, installHookManagerIntegration, isActiveLefthookHook, } from "./hook-manager-integration.js";
+import { installKnodinSkills, removeKnodinSkills } from "./skill-management.js";
 import { registerInitializedWorktree } from "./worktree-lifecycle.js";
 const MANAGED_MARKER = "KNODIN MANAGED HOOK";
 const HOOK_NAMES = ["post-commit", "post-checkout", "post-merge", "post-rewrite"];
@@ -1176,6 +1177,21 @@ export async function initializeRepository(repo, options) {
         agents: eligibleAgents,
         run: options.runAgentCommand,
     });
+    const skillClients = (scope === "team"
+        ? ["codex", "claude", "gemini"]
+        : agentIntegration.configured.filter((agent) => ["codex", "claude", "gemini"].includes(agent)));
+    const skillIntegration = scope === "cli-only"
+        ? removeKnodinSkills({
+            repo: resolvedRepo,
+            scope: "team",
+            clients: ["codex", "claude", "gemini"],
+        })
+        : installKnodinSkills({ repo: resolvedRepo, scope, clients: skillClients });
+    for (const issue of skillIntegration.issues)
+        agentIntegration.failed.push({
+            agent: skillClients.find((client) => issue.path.includes(`.${client}`)) ?? "codex",
+            message: `${issue.path}: ${issue.message}`,
+        });
     if (scope === "personal" && agentIntegration.configured.includes("claude"))
         externalConfigurationOutcomes.push({
             system: "claude-local-mcp",

package/dist/src/repository-management.js

@@ -901,7 +901,12 @@ function decodeCursor(cursor, hash) {
             (value.repository ?? -1) < 0 ||
             (value.offset ?? -1) < 0)
             throw new Error("invalid cursor");
-        return { repository: value.repository ?? 0, offset: value.offset ?? 0 };
+        return {
+            repository: value.repository ?? 0,
+            offset: value.offset ?? 0,
+            ...(value.mode === "fallback" ? { mode: "fallback" } : {}),
+            ...(value.mode === "symbol-only" ? { mode: "symbol-only" } : {}),
+        };
     }
     catch {
         throw new Error("knodin repos search: cursor does not match this query and selection");
@@ -930,8 +935,146 @@ function searchCandidate(inventory, match, exposePaths) {
         confidence: match.rrfScore || match.similarity,
         freshness: inventory.freshness,
         health: "healthy",
+        matchType: "symbol",
+        systemMemberships: inventory.systemMemberships,
     };
 }
+const TRACKED_TEXT_CANDIDATE_LIMIT = 1000;
+const TRACKED_TEXT_REPOSITORY_LIMIT = 200;
+const TRACKED_TEXT_OUTPUT_LIMIT = 2 * 1024 * 1024;
+const TRACKED_TEXT_TIMEOUT_MS = 5000;
+function queryTokens(query) {
+    return [
+        ...new Set(query
+            .toLowerCase()
+            .match(/[a-z0-9][a-z0-9._-]{2,}/g)
+            ?.map((token) => token.replace(/^[._-]+|[._-]+$/g, ""))
+            .filter(Boolean) ?? []),
+    ];
+}
+function tokenCoverage(value, tokens) {
+    const lower = value.toLowerCase();
+    return tokens.filter((token) => lower.includes(token)).length;
+}
+function textFallbackReason(results, query) {
+    if (results.length === 0)
+        return "no-symbol-results";
+    const tokens = queryTokens(query);
+    if (tokens.length < 3)
+        return undefined;
+    return results.every((result) => {
+        const identityCoverage = tokenCoverage(`${result.symbol} ${result.file}`, tokens);
+        const sourceCoverage = tokenCoverage(result.sourceEvidence, tokens);
+        return identityCoverage < 2 && (identityCoverage === 0 || sourceCoverage < 2);
+    })
+        ? "weak-symbol-coverage"
+        : undefined;
+}
+function committedFile(repository, file, timeout) {
+    const result = child_process.spawnSync(gitExecutable(), ["show", `HEAD:${file}`], {
+        cwd: repository,
+        encoding: "buffer",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout,
+        maxBuffer: 1024 * 1024,
+    });
+    return result.status === 0 && !result.error ? result.stdout : undefined;
+}
+function trackedTextWindow(repository, file, line, timeout, cache) {
+    try {
+        let content = cache?.get(file);
+        if (!cache?.has(file)) {
+            content = committedFile(repository, file, timeout);
+            cache?.set(file, content);
+        }
+        if (!content || content.includes(0))
+            return "";
+        const lines = content.toString("utf8").split(/\r?\n/);
+        const start = Math.max(0, line - 3);
+        return lines
+            .slice(start, Math.min(lines.length, line + 2))
+            .map((value, index) => `${start + index + 1}: ${value}`)
+            .join("\n");
+    }
+    catch {
+        return "";
+    }
+}
+function trackedTextMatches(inventory, query, exposePaths) {
+    if (!inventory.path)
+        return { matches: [], truncated: false };
+    const tokens = queryTokens(query);
+    if (tokens.length === 0)
+        return { matches: [], truncated: false };
+    const started = Date.now();
+    const remaining = () => Math.max(1, TRACKED_TEXT_TIMEOUT_MS - (Date.now() - started));
+    const args = ["grep", "-n", "-I", "-F", "-i"];
+    for (const token of tokens)
+        args.push("-e", token);
+    args.push("HEAD");
+    const result = child_process.spawnSync(gitExecutable(), args, {
+        cwd: inventory.path,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: remaining(),
+        maxBuffer: TRACKED_TEXT_OUTPUT_LIMIT,
+    });
+    if (result.error && result.error.code !== "ENOBUFS")
+        return { matches: [], truncated: true };
+    const lines = String(result.stdout ?? "")
+        .split(/\r?\n/)
+        .filter(Boolean);
+    const truncated = lines.length > TRACKED_TEXT_REPOSITORY_LIMIT || result.error !== undefined;
+    const records = lines.flatMap((record) => {
+        const match = /^HEAD:(.+?):(\d+):(.*)$/.exec(record);
+        if (!match?.[1] || !match[2])
+            return [];
+        const file = match[1];
+        const extension = path.extname(file).toLowerCase();
+        if (![".yaml", ".yml", ".sh", ".bash", ".zsh", ""].includes(extension))
+            return [];
+        if (extension === "") {
+            const content = committedFile(inventory.path ?? "", file, remaining());
+            if (!content || !content.toString("utf8", 0, 128).startsWith("#!"))
+                return [];
+        }
+        return [{ file, line: Number(match[2]), matchedSource: match[3] ?? "" }];
+    });
+    const phrase = query.trim().toLowerCase();
+    const contentCache = new Map();
+    const matches = records.slice(0, TRACKED_TEXT_REPOSITORY_LIMIT).flatMap((record) => {
+        const { file, line, matchedSource } = record;
+        const source = trackedTextWindow(inventory.path ?? "", file, line, remaining(), contentCache) ||
+            matchedSource;
+        const coverage = tokenCoverage(`${file} ${source}`, tokens);
+        const exactPhrase = phrase.length > 0 && source.toLowerCase().includes(phrase) ? 1 : 0;
+        const pathCoverage = tokenCoverage(file, tokens);
+        return [
+            {
+                repositoryId: inventory.id,
+                ...(exposePaths === false ? {} : { repositoryPath: inventory.path }),
+                identity: `text_${crypto.createHash("sha256").update(`${inventory.id}\0${file}\0${line}`).digest("hex").slice(0, 20)}`,
+                symbol: path.basename(file),
+                kind: "tracked-text",
+                file,
+                line,
+                sourceEvidence: source.slice(0, 4000),
+                sourceTruncated: source.length > 4000,
+                confidence: coverage / tokens.length + exactPhrase * 0.01 + pathCoverage * 0.001,
+                freshness: inventory.freshness,
+                health: "healthy",
+                matchType: "tracked-text",
+                systemMemberships: inventory.systemMemberships,
+                _score: [coverage, exactPhrase, pathCoverage],
+            },
+        ];
+    });
+    matches.sort((left, right) => right._score[0] - left._score[0] ||
+        right._score[1] - left._score[1] ||
+        right._score[2] - left._score[2] ||
+        compareBytes(`${left.repositoryId}:${left.file}:${left.line}`, `${right.repositoryId}:${right.file}:${right.line}`));
+    return { matches: matches.map(({ _score: _ignored, ...match }) => match), truncated };
+}
 async function searchHealthyRepository(inventory, repositoryIndex, offset, context) {
     const { query, itemLimit, effectiveBytes, results, omissions, selected, options } = context;
     const page = await options.search(query, inventory.path ?? "", itemLimit - results.length + 1, offset);
@@ -1013,6 +1156,7 @@ export async function searchRepositories(roots, query, options) {
         .digest("hex")
         .slice(0, 20);
     const start = decodeCursor(options.cursor, hash);
+    const symbolStart = start.mode === "fallback" ? { repository: 0, offset: 0 } : start;
     const itemLimit = Math.min(Math.max(options.itemBudget ?? 25, 1), 1000);
     if (options.byteBudget !== undefined && options.byteBudget < 1024)
         throw new Error("knodin repos search: byte budget must be at least 1024");
@@ -1021,7 +1165,58 @@ export async function searchRepositories(roots, query, options) {
     const byteLimit = options.byteBudget ?? 65_536;
     const tokenLimit = options.tokenBudget ?? 16_384;
     const effectiveBytes = Math.min(byteLimit, tokenLimit * 4);
-    const { results, omissions, next } = await collectRepositorySearchResults(selected, start, query, itemLimit, effectiveBytes, options);
+    const { results, omissions, next } = await collectRepositorySearchResults(selected, symbolStart, query, itemLimit, effectiveBytes, options);
+    const fallbackReason = start.mode === "symbol-only" ? undefined : textFallbackReason(results, query);
+    let textFallbackTruncated = false;
+    let fallbackCursor;
+    if (fallbackReason) {
+        const textMatches = [];
+        const eligible = selected.filter(({ health }) => health === "healthy");
+        const inspected = eligible.slice(0, 25);
+        if (inspected.length < eligible.length)
+            textFallbackTruncated = true;
+        for (const inventory of inspected) {
+            const text = trackedTextMatches(inventory, query, options.exposePaths);
+            textFallbackTruncated ||= text.truncated;
+            textMatches.push(...text.matches);
+            if (textMatches.length >= TRACKED_TEXT_CANDIDATE_LIMIT) {
+                textFallbackTruncated = true;
+                break;
+            }
+        }
+        textMatches.sort((left, right) => right.confidence - left.confidence ||
+            compareBytes(`${left.repositoryId}:${left.file}:${left.line ?? 0}`, `${right.repositoryId}:${right.file}:${right.line ?? 0}`));
+        const combined = textMatches.slice(0, TRACKED_TEXT_CANDIDATE_LIMIT);
+        const fallbackOffset = start.mode === "fallback" ? start.offset : 0;
+        const page = [];
+        let nextOffset = fallbackOffset;
+        while (nextOffset < combined.length && page.length < itemLimit) {
+            const candidate = combined[nextOffset];
+            if (!candidate)
+                break;
+            const probe = JSON.stringify({
+                results: [...page, candidate],
+                omissions,
+                repositories: selected,
+            });
+            if (Buffer.byteLength(probe) > effectiveBytes && page.length > 0)
+                break;
+            page.push(candidate);
+            nextOffset += 1;
+            if (Buffer.byteLength(probe) > effectiveBytes)
+                break;
+        }
+        results.splice(0, results.length, ...page);
+        if (nextOffset < combined.length)
+            fallbackCursor = encodeCursor({
+                hash,
+                repository: 0,
+                offset: nextOffset,
+                mode: "fallback",
+            });
+        else if (results.length > 0 || next)
+            fallbackCursor = encodeCursor({ hash, repository: 0, offset: 0, mode: "symbol-only" });
+    }
     if (omissions.length > 0 && options.allowPartial !== true) {
         return finalizeRepositorySearch({
             schemaVersion: 1,
@@ -1040,7 +1235,28 @@ export async function searchRepositories(roots, query, options) {
         results,
         repositories: selected,
         omissions,
-        ...(next ? { cursor: encodeCursor({ hash, ...next }) } : {}),
+        ...(fallbackReason
+            ? {
+                retrieval: {
+                    textFallback: true,
+                    reason: fallbackReason,
+                    inspectedRepositories: Math.min(25, selected.filter(({ health }) => health === "healthy").length),
+                    candidateLimit: TRACKED_TEXT_CANDIDATE_LIMIT,
+                    truncated: textFallbackTruncated,
+                },
+            }
+            : {}),
+        ...(fallbackCursor
+            ? { cursor: fallbackCursor }
+            : !fallbackReason && next
+                ? {
+                    cursor: encodeCursor({
+                        hash,
+                        ...next,
+                        mode: start.mode === "symbol-only" ? "symbol-only" : "symbol",
+                    }),
+                }
+                : {}),
     };
     return finalizeRepositorySearch(base, byteLimit, tokenLimit, itemLimit);
 }