knodin 0.5.0

package/dist/src/repository-management.js

@@ -0,0 +1,1089 @@
+import child_process from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { gitExecutable } from "./git-executable.js";
+import { initializeRepository, isRepositoryInitializationCurrent, readRepositoryIntegrationConfig, } from "./init.js";
+import { applyResponseBudget } from "./response-budget.js";
+const DEFAULT_DEPTH = 4;
+const MAX_DEPTH = 32;
+const MAX_GIT_ERROR_BYTES = 16 * 1024;
+const MAX_TRACKED_PATH_BYTES = 1024 * 1024;
+const MAX_DOCUMENT_CANDIDATES = 20;
+const SKIPPED_DIRECTORIES = new Set([".git", ".reckon", "node_modules"]);
+function gitTopLevel(directory) {
+    return child_process
+        .execFileSync(gitExecutable(), ["rev-parse", "--show-toplevel"], {
+        cwd: directory,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+    })
+        .trim();
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function validateDepth(depth) {
+    if (!Number.isInteger(depth) || depth < 0 || depth > MAX_DEPTH) {
+        throw new Error(`knodin repos: --depth must be an integer between 0 and ${MAX_DEPTH}`);
+    }
+}
+function worktreeRecords(repository) {
+    const listing = child_process.execFileSync(gitExecutable(), ["worktree", "list", "--porcelain", "-z"], {
+        cwd: repository,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const records = [];
+    for (const field of listing.split("\0")) {
+        if (field.startsWith("worktree ")) {
+            records.push({
+                path: path.resolve(field.slice("worktree ".length)),
+                main: records.length === 0,
+            });
+        }
+        else if (field.startsWith("prunable ")) {
+            const current = records.at(-1);
+            if (current)
+                current.stale = field.slice("prunable ".length);
+        }
+    }
+    return records;
+}
+/**
+ * Discover repository checkouts without conflating independent repositories
+ * with Git linked worktrees. Classification is relative to the supplied roots:
+ * a repository below another repository is nested; other additional Git roots
+ * are unrelated unless Git's own worktree metadata links them.
+ */
+export async function discoverRepositories(roots, options = {}) {
+    const depth = options.depth ?? DEFAULT_DEPTH;
+    const linkedWorktrees = options.linkedWorktrees ?? "skip";
+    const legacy = await discoverGitRepositoryPaths(roots, depth, linkedWorktrees);
+    const canonicalRoots = (await Promise.all(roots.map(async (root) => {
+        try {
+            return await fs.promises.realpath(path.resolve(root));
+        }
+        catch {
+            return path.resolve(root);
+        }
+    }))).sort((left, right) => left.localeCompare(right));
+    const mainByWorktree = new Map();
+    for (const repository of legacy.repositories) {
+        try {
+            const records = worktreeRecords(repository);
+            const main = records.find(({ main }) => main)?.path ?? repository;
+            for (const record of records)
+                mainByWorktree.set(record.path, main);
+        }
+        catch {
+            mainByWorktree.set(repository, repository);
+        }
+    }
+    const repositorySet = new Set(legacy.repositories);
+    const mainRepositories = legacy.repositories.filter((repository) => (mainByWorktree.get(repository) ?? repository) === repository);
+    const topLevelRepositories = mainRepositories
+        .filter((repository) => !mainRepositories.some((candidate) => candidate !== repository && repository.startsWith(`${candidate}${path.sep}`)))
+        .sort((left, right) => left.localeCompare(right));
+    const repositories = legacy.repositories
+        .map((repository) => {
+        const mainWorktree = mainByWorktree.get(repository) ?? repository;
+        if (mainWorktree !== repository) {
+            return { path: repository, classification: "linked-worktree", mainWorktree };
+        }
+        const hasParentRepository = mainRepositories.some((candidate) => candidate !== repository &&
+            repository.startsWith(`${candidate}${path.sep}`) &&
+            repositorySet.has(candidate));
+        if (hasParentRepository) {
+            return {
+                path: repository,
+                classification: "nested-repository",
+                mainWorktree: repository,
+            };
+        }
+        const isPrimaryForRoot = canonicalRoots.some((root) => topLevelRepositories.find((candidate) => candidate === root || candidate.startsWith(`${root}${path.sep}`)) === repository);
+        return {
+            path: repository,
+            classification: isPrimaryForRoot ? "main-worktree" : "unrelated-repository",
+            mainWorktree: repository,
+        };
+    })
+        .filter(({ classification }) => linkedWorktrees === "include" || classification !== "linked-worktree");
+    // Deterministic UX ordering groups linked worktrees before their main
+    // checkout, followed by nested and then unrelated repositories.
+    const classificationOrder = {
+        "linked-worktree": 0,
+        "main-worktree": 1,
+        "nested-repository": 2,
+        "unrelated-repository": 3,
+    };
+    repositories.sort((left, right) => classificationOrder[left.classification] - classificationOrder[right.classification] ||
+        left.path.localeCompare(right.path));
+    return {
+        repositories,
+        issues: legacy.issues,
+        emptyRoots: legacy.emptyRoots,
+        staleLinkedWorktrees: legacy.staleWorktrees,
+    };
+}
+function requiredArgument(args, index, option) {
+    const value = args[index + 1];
+    if (value === undefined)
+        throw new Error(`knodin repos: ${option} requires a value`);
+    return value;
+}
+function setLinkedWorktreePolicy(state, value) {
+    if (value !== "skip" && value !== "include")
+        throw new Error("knodin repos: --linked-worktrees must be skip or include");
+    state.linkedWorktrees = value;
+}
+function parseRepositoryPrefixedOrPositional(argument, index, cwd, command, state) {
+    if (argument.startsWith("--include=") || argument.startsWith("--exclude=")) {
+        const target = argument.startsWith("--include=") ? state.include : state.exclude;
+        target.push(...argument
+            .slice(argument.indexOf("=") + 1)
+            .split(",")
+            .filter(Boolean));
+        return index;
+    }
+    if (argument.startsWith("--depth=")) {
+        state.depth = Number(argument.slice("--depth=".length));
+        return index;
+    }
+    if (argument.startsWith("--linked-worktrees=")) {
+        setLinkedWorktreePolicy(state, argument.slice("--linked-worktrees=".length));
+        return index;
+    }
+    if (argument.startsWith("--manifest=")) {
+        state.manifestPath = path.resolve(cwd, argument.slice("--manifest=".length));
+        return index;
+    }
+    if (argument.startsWith("--"))
+        throw new Error(`knodin repos: unknown option ${argument}`);
+    if (command === "search" && state.query === undefined)
+        state.query = argument;
+    else
+        state.roots.push(path.resolve(cwd, argument));
+    return index;
+}
+function parseRepositoryOption(args, index, cwd, command, state) {
+    const argument = args[index] ?? "";
+    switch (argument) {
+        case "--dry-run":
+            state.dryRun = true;
+            return index;
+        case "--json":
+            state.json = true;
+            return index;
+        case "--allow-partial":
+            state.allowPartial = true;
+            return index;
+        case "--root":
+            state.roots.push(path.resolve(cwd, requiredArgument(args, index, argument)));
+            return index + 1;
+        case "--include":
+        case "--exclude": {
+            const target = argument === "--include" ? state.include : state.exclude;
+            target.push(...requiredArgument(args, index, argument).split(",").filter(Boolean));
+            return index + 1;
+        }
+        case "--items":
+        case "--bytes":
+        case "--tokens": {
+            const value = Number(requiredArgument(args, index, argument));
+            if (!Number.isInteger(value) || value < 1)
+                throw new Error(`knodin repos: ${argument} requires a positive integer`);
+            if (argument === "--items")
+                state.itemBudget = value;
+            if (argument === "--bytes")
+                state.byteBudget = value;
+            if (argument === "--tokens")
+                state.tokenBudget = value;
+            return index + 1;
+        }
+        case "--cursor":
+            state.cursor = requiredArgument(args, index, argument);
+            return index + 1;
+        case "--manifest":
+            state.manifestPath = path.resolve(cwd, requiredArgument(args, index, argument));
+            return index + 1;
+        case "--depth":
+            state.depth = Number(requiredArgument(args, index, argument));
+            return index + 1;
+        case "--linked-worktrees":
+            setLinkedWorktreePolicy(state, requiredArgument(args, index, argument));
+            return index + 1;
+    }
+    return parseRepositoryPrefixedOrPositional(argument, index, cwd, command, state);
+}
+function parseRepositoryCommand(value) {
+    if (!value || !["discover", "init", "status", "doctor", "search"].includes(value))
+        throw new Error("knodin repos requires discover, init, status, doctor, or search");
+    return value;
+}
+export function parseRepositoryCommandArgs(args, cwd) {
+    const command = parseRepositoryCommand(args[0]);
+    const state = {
+        depth: DEFAULT_DEPTH,
+        dryRun: false,
+        json: false,
+        linkedWorktrees: "skip",
+        roots: [],
+        include: [],
+        exclude: [],
+        allowPartial: false,
+    };
+    let index = 1;
+    while (index < args.length) {
+        index = parseRepositoryOption(args, index, cwd, command, state) + 1;
+    }
+    validateDepth(state.depth);
+    if (command === "search" && !state.query?.trim())
+        throw new Error("knodin repos search requires a non-empty <query>");
+    if (state.roots.length === 0) {
+        if (command === "search")
+            state.roots.push(cwd);
+        else
+            throw new Error(`knodin repos ${command} requires at least one <root>`);
+    }
+    if (state.dryRun && command !== "init")
+        throw new Error(`knodin repos ${command}: --dry-run applies only to init`);
+    if (state.manifestPath && command !== "init")
+        throw new Error(`knodin repos ${command}: --manifest applies only to init`);
+    if (command !== "search" &&
+        command !== "init" &&
+        (state.include.length > 0 || state.exclude.length > 0))
+        throw new Error(`knodin repos ${command}: repository selectors apply only to init or search`);
+    if (command !== "search" &&
+        (state.allowPartial ||
+            state.itemBudget ||
+            state.byteBudget ||
+            state.tokenBudget ||
+            state.cursor))
+        throw new Error(`knodin repos ${command}: search options apply only to search`);
+    return { command, ...state };
+}
+/**
+ * Find real Git worktree roots without following child symlinks. Every supplied
+ * root is resolved through realpath, so aliases are accepted but cannot create
+ * duplicate work. Nested repositories and linked worktrees are independent
+ * targets; traversal continues below a repository until the requested depth.
+ */
+async function gitRepositoryAt(directory) {
+    const gitEntry = path.join(directory, ".git");
+    try {
+        await fs.promises.lstat(gitEntry);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const realTopLevel = await fs.promises.realpath(gitTopLevel(directory));
+    return realTopLevel === directory ? realTopLevel : undefined;
+}
+async function childDirectories(current, depth, worktrees) {
+    if (current.level >= depth)
+        return [];
+    const entries = await fs.promises.readdir(current.directory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    return entries.flatMap((entry) => {
+        const skipped = !entry.isDirectory() ||
+            SKIPPED_DIRECTORIES.has(entry.name) ||
+            (entry.name === ".worktrees" && worktrees === "skip");
+        return skipped
+            ? []
+            : [{ directory: path.join(current.directory, entry.name), level: current.level + 1 }];
+    });
+}
+async function scanDiscoveryRoot(root, depth, worktrees) {
+    const repositories = new Set();
+    const issues = [];
+    const staleWorktrees = new Map();
+    let found = false;
+    const queue = [{ directory: root, level: 0 }];
+    for (const current of queue) {
+        try {
+            const repository = await gitRepositoryAt(current.directory);
+            if (repository) {
+                repositories.add(repository);
+                found = true;
+                for (const record of worktreeRecords(repository)) {
+                    if (record.stale || !fs.existsSync(record.path)) {
+                        staleWorktrees.set(record.path, record.stale ?? "registered worktree path no longer exists");
+                    }
+                }
+            }
+            queue.push(...(await childDirectories(current, depth, worktrees)));
+        }
+        catch (error) {
+            issues.push({ path: current.directory, message: errorMessage(error) });
+        }
+    }
+    return {
+        repositories: [...repositories],
+        issues,
+        staleWorktrees: [...staleWorktrees],
+        found,
+    };
+}
+export async function discoverGitRepositoryPaths(roots, depth = DEFAULT_DEPTH, worktrees = "skip") {
+    validateDepth(depth);
+    const repositories = new Set();
+    const issues = [];
+    const emptyRoots = [];
+    const seenRoots = new Set();
+    const staleWorktrees = new Map();
+    for (const suppliedRoot of [...roots].sort((left, right) => left.localeCompare(right))) {
+        let root;
+        try {
+            root = await fs.promises.realpath(path.resolve(suppliedRoot));
+            const stat = await fs.promises.stat(root);
+            if (!stat.isDirectory())
+                throw new Error("not a directory");
+        }
+        catch (error) {
+            issues.push({
+                path: path.resolve(suppliedRoot),
+                message: errorMessage(error),
+            });
+            continue;
+        }
+        if (seenRoots.has(root))
+            continue;
+        seenRoots.add(root);
+        const scanned = await scanDiscoveryRoot(root, depth, worktrees);
+        for (const repository of scanned.repositories)
+            repositories.add(repository);
+        issues.push(...scanned.issues);
+        for (const [worktree, message] of scanned.staleWorktrees)
+            staleWorktrees.set(worktree, message);
+        if (!scanned.found && scanned.issues.length === 0)
+            emptyRoots.push(root);
+    }
+    const orderedRepositories = [...repositories];
+    orderedRepositories.sort((left, right) => left.localeCompare(right));
+    const orderedIssues = [...issues];
+    orderedIssues.sort((left, right) => left.path.localeCompare(right.path));
+    const orderedEmptyRoots = [...emptyRoots];
+    orderedEmptyRoots.sort((left, right) => left.localeCompare(right));
+    return {
+        repositories: orderedRepositories,
+        issues: orderedIssues,
+        emptyRoots: orderedEmptyRoots,
+        staleWorktrees: [...staleWorktrees]
+            .map(([stalePath, message]) => ({ path: stalePath, message }))
+            .sort((left, right) => left.path.localeCompare(right.path)),
+    };
+}
+/** Parse the deliberately small, bounded `knodin fleet init` argument surface. */
+function parseFleetOption(args, index, cwd, plan) {
+    const argument = args[index] ?? "";
+    switch (argument) {
+        case "--dry-run":
+            plan.dryRun = true;
+            return index;
+        case "--json":
+            plan.json = true;
+            return index;
+        case "--depth": {
+            const value = args[index + 1];
+            if (value === undefined)
+                throw new Error("knodin fleet init: --depth requires a value");
+            plan.depth = Number(value);
+            return index + 1;
+        }
+    }
+    if (argument.startsWith("--depth=")) {
+        plan.depth = Number(argument.slice("--depth=".length));
+        return index;
+    }
+    if (argument === "--worktrees" || argument.startsWith("--worktrees=")) {
+        const value = argument === "--worktrees" ? args[index + 1] : argument.slice("--worktrees=".length);
+        if (value !== "skip" && value !== "include")
+            throw new Error("knodin fleet init: --worktrees must be skip or include");
+        plan.worktrees = value;
+        return argument === "--worktrees" ? index + 1 : index;
+    }
+    if (argument.startsWith("--"))
+        throw new Error(`knodin fleet init: unknown option ${argument}`);
+    plan.roots.push(path.resolve(cwd, argument));
+    return index;
+}
+export function parseFleetInitArgs(args, cwd) {
+    if (args[0] !== "init")
+        throw new Error("knodin fleet requires `init`");
+    const plan = {
+        depth: DEFAULT_DEPTH,
+        dryRun: false,
+        json: false,
+        worktrees: "skip",
+        roots: [],
+    };
+    let index = 1;
+    while (index < args.length) {
+        index = parseFleetOption(args, index, cwd, plan) + 1;
+    }
+    validateDepth(plan.depth);
+    if (plan.roots.length === 0)
+        throw new Error("knodin fleet init requires at least one <root>");
+    return plan;
+}
+function gitValue(repository, args) {
+    try {
+        return child_process
+            .execFileSync(gitExecutable(), args, {
+            cwd: repository,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .trim();
+    }
+    catch {
+        return "";
+    }
+}
+function portableRemote(remote) {
+    try {
+        const parsed = new URL(remote);
+        parsed.username = "";
+        parsed.password = "";
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString().replace(/\/$/, "");
+    }
+    catch {
+        return remote.replace(/^[^@/\s]+@(?=[^:/\s]+[:/])/, "").replace(/\.git$/, "");
+    }
+}
+/** Stable, path-independent identity where Git origin or root history exists. */
+export function repositoryIdentity(repository) {
+    const remote = portableRemote(gitValue(repository, ["remote", "get-url", "origin"]));
+    const rootCommit = gitValue(repository, ["rev-list", "--max-parents=0", "HEAD"]).split("\n")[0] ?? "";
+    const seed = remote || `${rootCommit}:${path.basename(repository)}`;
+    return `repo_${crypto.createHash("sha256").update(seed).digest("hex").slice(0, 20)}`;
+}
+const LANGUAGE_BY_EXTENSION = {
+    ".c": "c",
+    ".cc": "cpp",
+    ".cpp": "cpp",
+    ".cs": "csharp",
+    ".go": "go",
+    ".java": "java",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".kt": "kotlin",
+    ".php": "php",
+    ".py": "python",
+    ".rb": "ruby",
+    ".rs": "rust",
+    ".swift": "swift",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+};
+function insertBoundedCandidate(candidates, file) {
+    const insertion = candidates.findIndex((candidate) => candidate.localeCompare(file) > 0);
+    if (insertion === -1)
+        candidates.push(file);
+    else
+        candidates.splice(insertion, 0, file);
+    if (candidates.length > MAX_DOCUMENT_CANDIDATES)
+        candidates.pop();
+}
+function classifyTrackedFile(inventory, file) {
+    inventory.count += 1;
+    const language = LANGUAGE_BY_EXTENSION[path.extname(file).toLowerCase()];
+    if (language && !inventory.languages.includes(language))
+        inventory.languages.push(language);
+    if (["package.json", "pyproject.toml", "Cargo.toml", "go.mod"].includes(file))
+        inventory.manifests.add(file);
+    const normalized = file.replaceAll("\\", "/");
+    const basename = path.posix.basename(normalized).toLowerCase();
+    const documentationLike = /\.(?:md|mdx|txt|rst|adoc|asciidoc)$/i.test(basename);
+    if (/^readme(?:\.|$)/.test(basename))
+        insertBoundedCandidate(inventory.documentCandidates.readme, file);
+    if (documentationLike &&
+        (/^(?:architecture|design)(?:\.|$)/.test(basename) ||
+            /^adr[-_.]?\d/i.test(basename) ||
+            normalized
+                .toLowerCase()
+                .split("/")
+                .some((part) => part === "architecture" || part === "adr" || part === "adrs")))
+        insertBoundedCandidate(inventory.documentCandidates.architecture, file);
+    if (documentationLike && /^(?:roadmap|backlog)(?:\.|$)/.test(basename))
+        insertBoundedCandidate(inventory.documentCandidates.roadmap, file);
+}
+function trackedFileInventory(repository) {
+    return new Promise((resolve, reject) => {
+        const inventory = {
+            count: 0,
+            languages: [],
+            manifests: new Set(),
+            documentCandidates: { readme: [], architecture: [], roadmap: [] },
+        };
+        const child = child_process.spawn(gitExecutable(), ["ls-files", "-z"], {
+            cwd: repository,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let pending = Buffer.alloc(0);
+        let stderr = "";
+        let settled = false;
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill();
+            reject(error);
+        };
+        child.stdout.on("data", (chunk) => {
+            if (settled)
+                return;
+            pending = Buffer.concat([pending, chunk]);
+            let separator = pending.indexOf(0);
+            while (separator >= 0) {
+                classifyTrackedFile(inventory, pending.subarray(0, separator).toString("utf-8"));
+                pending = pending.subarray(separator + 1);
+                separator = pending.indexOf(0);
+            }
+            if (pending.length > MAX_TRACKED_PATH_BYTES) {
+                fail(new Error(`git ls-files returned a path over ${MAX_TRACKED_PATH_BYTES} bytes`));
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < MAX_GIT_ERROR_BYTES)
+                stderr += chunk.toString("utf-8").slice(0, MAX_GIT_ERROR_BYTES - stderr.length);
+        });
+        child.on("error", fail);
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            if (code !== 0) {
+                const outcome = signal ? `signal ${signal}` : `exit ${code ?? "unknown"}`;
+                const diagnostic = stderr.trim() || "no diagnostic";
+                reject(new Error(`git ls-files failed (${outcome}): ${diagnostic}`));
+                return;
+            }
+            if (pending.length > 0)
+                classifyTrackedFile(inventory, pending.toString("utf-8"));
+            inventory.languages.sort((left, right) => left.localeCompare(right));
+            resolve(inventory);
+        });
+    });
+}
+function packageIdentities(repository, manifestFiles) {
+    const manifests = [
+        ["package.json", "name"],
+        ["pyproject.toml", "name"],
+        ["Cargo.toml", "name"],
+        ["go.mod", "module"],
+    ];
+    const identities = [];
+    for (const [manifest, field] of manifests) {
+        if (!manifestFiles.has(manifest))
+            continue;
+        try {
+            const content = fs.readFileSync(path.join(repository, manifest), "utf-8");
+            if (manifest === "package.json") {
+                const name = JSON.parse(content).name;
+                if (typeof name === "string")
+                    identities.push(name);
+            }
+            else {
+                const pattern = new RegExp(String.raw `^${field}[ \t]*(?:=[ \t]*)?["']?([^"'\s]+)`, "m");
+                const match = pattern.exec(content);
+                if (match?.[1])
+                    identities.push(match[1]);
+            }
+        }
+        catch {
+            // Malformed manifests remain visible through the repository's health error.
+        }
+    }
+    return [...new Set(identities)].sort((left, right) => left.localeCompare(right));
+}
+function canonicalRepositorySelector(value) {
+    try {
+        return fs.realpathSync(path.resolve(value));
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+async function inspectInventoryGraph(repository, options) {
+    try {
+        const graph = await options.status(repository);
+        const lastIndexedHead = (await options.lastIndexedHead?.(repository)) ?? graph.lastIndexedHead ?? "";
+        const indexGeneration = graph.indexGeneration === undefined
+            ? graph.verification.verifiedAt
+            : String(graph.indexGeneration);
+        let health = "healthy";
+        if (graph.status !== "healthy")
+            health = graph.status;
+        else if (graph.coverage.sourceFiles > 0 && graph.coverage.indexedFiles === 0)
+            health = "empty-index";
+        else if (graph.lifecycle && graph.lifecycle.status !== "healthy")
+            health = "lifecycle-degraded";
+        return {
+            health,
+            lastIndexedHead,
+            indexGeneration,
+            errors: [],
+            remediation: health === "healthy" ? [] : graph.repairSteps,
+        };
+    }
+    catch (error) {
+        return {
+            health: "unknown",
+            lastIndexedHead: "",
+            indexGeneration: null,
+            errors: [errorMessage(error)],
+            remediation: [],
+        };
+    }
+}
+function inventoryFreshness(lastIndexedHead, head) {
+    if (lastIndexedHead === "")
+        return "unknown";
+    return lastIndexedHead === head ? "fresh" : "stale";
+}
+export async function inventoryRepository(record, options) {
+    const id = repositoryIdentity(record.path);
+    const mainWorktreeId = repositoryIdentity(record.mainWorktree);
+    const databaseExists = fs.existsSync(path.join(record.path, ".reckon", "db.sqlite"));
+    const head = gitValue(record.path, ["rev-parse", "HEAD"]);
+    let tracked;
+    try {
+        tracked = await trackedFileInventory(record.path);
+    }
+    catch (error) {
+        const message = `tracked-file inventory failed: ${errorMessage(error)}`;
+        return {
+            schemaVersion: 1,
+            id,
+            ...(options.exposePaths === false ? {} : { path: record.path }),
+            classification: record.classification,
+            mainWorktreeId,
+            initialization: databaseExists ? "initialized" : "not-initialized",
+            health: "unknown",
+            head,
+            lastIndexedHead: "",
+            freshness: "unknown",
+            indexGeneration: null,
+            languages: [],
+            packageIdentities: [],
+            systemMemberships: [...(options.systemMemberships?.(record.path) ?? [])].sort((left, right) => left.localeCompare(right)),
+            documentCandidates: { readme: [], architecture: [], roadmap: [] },
+            errors: [message],
+            remediation: [`verify git ls-files in ${record.path}`, "retry repository inventory"],
+        };
+    }
+    const baselineHealth = tracked.count === 0 ? "empty-repository" : "not-initialized";
+    const graph = databaseExists && tracked.count > 0
+        ? await inspectInventoryGraph(record.path, options)
+        : {
+            health: baselineHealth,
+            lastIndexedHead: "",
+            indexGeneration: null,
+            errors: [],
+            remediation: [],
+        };
+    const remediation = [...graph.remediation];
+    const { health, lastIndexedHead, indexGeneration, errors } = graph;
+    if (health === "not-initialized")
+        remediation.push(`knodin init --repo ${record.path}`);
+    if (health === "empty-index" || health === "repair-needed")
+        remediation.push("knodin repair");
+    return {
+        schemaVersion: 1,
+        id,
+        ...(options.exposePaths === false ? {} : { path: record.path }),
+        classification: record.classification,
+        mainWorktreeId,
+        initialization: databaseExists ? "initialized" : "not-initialized",
+        health,
+        head,
+        lastIndexedHead,
+        freshness: inventoryFreshness(lastIndexedHead, head),
+        indexGeneration,
+        languages: tracked.languages,
+        packageIdentities: packageIdentities(record.path, tracked.manifests),
+        systemMemberships: [...(options.systemMemberships?.(record.path) ?? [])].sort((left, right) => left.localeCompare(right)),
+        documentCandidates: tracked.documentCandidates,
+        errors,
+        remediation: [...new Set(remediation)],
+    };
+}
+function encodeCursor(value) {
+    return Buffer.from(JSON.stringify({ version: 1, ...value })).toString("base64url");
+}
+function decodeCursor(cursor, hash) {
+    if (!cursor)
+        return { repository: 0, offset: 0 };
+    try {
+        const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf-8"));
+        if (value.version !== 1 ||
+            value.hash !== hash ||
+            !Number.isInteger(value.repository) ||
+            !Number.isInteger(value.offset) ||
+            (value.repository ?? -1) < 0 ||
+            (value.offset ?? -1) < 0)
+            throw new Error("invalid cursor");
+        return { repository: value.repository ?? 0, offset: value.offset ?? 0 };
+    }
+    catch {
+        throw new Error("knodin repos search: cursor does not match this query and selection");
+    }
+}
+function searchStatus(omissionCount, resultCount, selectedCount) {
+    if (omissionCount > 0)
+        return "partial";
+    if (resultCount > 0)
+        return "ok";
+    return selectedCount > 0 ? "no-match" : "unavailable";
+}
+function finalizeRepositorySearch(value, byteLimit, tokenLimit, itemLimit) {
+    return applyResponseBudget(value, "repositories:search", { bytes: byteLimit, tokens: tokenLimit, items: itemLimit }, { bytes: byteLimit, tokens: tokenLimit, items: itemLimit });
+}
+function searchCandidate(inventory, match, exposePaths) {
+    return {
+        repositoryId: inventory.id,
+        ...(exposePaths === false ? {} : { repositoryPath: inventory.path }),
+        identity: match.identity,
+        symbol: match.symbol,
+        kind: match.kind,
+        file: match.filePath,
+        sourceEvidence: match.source.slice(0, 4000),
+        sourceTruncated: match.source.length > 4000,
+        confidence: match.rrfScore || match.similarity,
+        freshness: inventory.freshness,
+        health: "healthy",
+    };
+}
+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);
+    for (const [matchIndex, match] of page.results.entries()) {
+        if (results.length >= itemLimit) {
+            return { repository: repositoryIndex, offset: offset + matchIndex };
+        }
+        const candidate = searchCandidate(inventory, match, options.exposePaths);
+        const probe = JSON.stringify({
+            results: [...results, candidate],
+            omissions,
+            repositories: selected,
+        });
+        if (Buffer.byteLength(probe) > effectiveBytes) {
+            return { repository: repositoryIndex, offset: offset + matchIndex };
+        }
+        results.push(candidate);
+    }
+    if (page.hasMore)
+        return { repository: repositoryIndex, offset: offset + page.results.length };
+    return undefined;
+}
+async function collectRepositorySearchResults(selected, start, query, itemLimit, effectiveBytes, options) {
+    const results = [];
+    const omissions = [];
+    for (const [index, inventory] of selected.entries()) {
+        if (inventory.health !== "healthy") {
+            omissions.push({
+                repositoryId: inventory.id,
+                state: inventory.health === "no-match" ? "unknown" : inventory.health,
+                reason: inventory.errors[0] ?? `repository graph is ${inventory.health}`,
+                remediation: inventory.remediation,
+            });
+            continue;
+        }
+        if (index < start.repository)
+            continue;
+        const offset = index === start.repository ? start.offset : 0;
+        const next = await searchHealthyRepository(inventory, index, offset, {
+            query,
+            itemLimit,
+            effectiveBytes,
+            results,
+            omissions,
+            selected,
+            options,
+        });
+        if (next)
+            return { results, omissions, next };
+    }
+    return { results, omissions };
+}
+/** Search independent repositories sequentially with explicit omissions and hard response budgets. */
+export async function searchRepositories(roots, query, options) {
+    const discovery = await discoverRepositories(roots, options);
+    const selectors = new Set((options.include ?? []).flatMap((value) => [value, canonicalRepositorySelector(value)]));
+    const excluded = new Set((options.exclude ?? []).flatMap((value) => [value, canonicalRepositorySelector(value)]));
+    const identities = new Map(discovery.repositories.map((record) => [record.path, repositoryIdentity(record.path)]));
+    const matchesSelector = (record, selector) => selector === record.path ||
+        canonicalRepositorySelector(selector) === record.path ||
+        selector === identities.get(record.path);
+    const unknownSelectors = (options.include ?? []).filter((selector) => !discovery.repositories.some((record) => matchesSelector(record, selector)));
+    if (unknownSelectors.length > 0) {
+        throw new Error(`knodin repos search: include selector(s) matched no discovered repository: ${unknownSelectors.join(", ")}`);
+    }
+    const selectedRecords = discovery.repositories.filter((record) => {
+        const id = identities.get(record.path) ?? repositoryIdentity(record.path);
+        return ((selectors.size === 0 || selectors.has(id) || selectors.has(record.path)) &&
+            !excluded.has(id) &&
+            !excluded.has(record.path));
+    });
+    const selected = [];
+    for (const record of selectedRecords) {
+        selected.push(await inventoryRepository(record, options));
+    }
+    const hash = crypto
+        .createHash("sha256")
+        .update(JSON.stringify([query, selected.map(({ id }) => id)]))
+        .digest("hex")
+        .slice(0, 20);
+    const start = decodeCursor(options.cursor, hash);
+    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");
+    if (options.tokenBudget !== undefined && options.tokenBudget < 256)
+        throw new Error("knodin repos search: token budget must be at least 256");
+    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);
+    if (omissions.length > 0 && options.allowPartial !== true) {
+        return finalizeRepositorySearch({
+            schemaVersion: 1,
+            status: "unavailable",
+            query,
+            results: [],
+            repositories: selected,
+            omissions,
+        }, byteLimit, tokenLimit, itemLimit);
+    }
+    const status = searchStatus(omissions.length, results.length, selected.length);
+    const base = {
+        schemaVersion: 1,
+        status,
+        query,
+        results,
+        repositories: selected,
+        omissions,
+        ...(next ? { cursor: encodeCursor({ hash, ...next }) } : {}),
+    };
+    return finalizeRepositorySearch(base, byteLimit, tokenLimit, itemLimit);
+}
+/**
+ * Initialize repositories sequentially. A healthy graph is never fully indexed
+ * merely to refresh stale hooks; a no-op index callback lets the initializer
+ * update only its managed files. Failures are isolated to their repository.
+ */
+function initializationMessage(databaseExists, healthy) {
+    if (healthy)
+        return "managed installation updated; healthy graph preserved";
+    return databaseExists
+        ? "managed installation and graph updated"
+        : "managed installation and graph initialized";
+}
+function dryRunInitialization(repository, databaseExists, current) {
+    if (databaseExists && current) {
+        return {
+            repository,
+            status: "skipped",
+            message: "dry-run: would verify graph health before deciding whether to update",
+        };
+    }
+    return {
+        repository,
+        status: "skipped",
+        plannedStatus: databaseExists ? "updated" : "initialized",
+        message: databaseExists
+            ? "dry-run: would update managed installation"
+            : "dry-run: would initialize",
+    };
+}
+function initializationSignature(repositories, depth, worktrees) {
+    return crypto
+        .createHash("sha256")
+        .update(JSON.stringify({ repositories, depth, worktrees }))
+        .digest("hex");
+}
+function readInitializationManifest(manifestPath, signature) {
+    if (!manifestPath || !fs.existsSync(manifestPath))
+        return null;
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    if (manifest.schemaVersion !== 1 ||
+        manifest.signature !== signature ||
+        !Array.isArray(manifest.completed)) {
+        throw new Error(`knodin repos init: ${manifestPath} does not match this repository selection and policy`);
+    }
+    return manifest;
+}
+function writeInitializationManifest(manifestPath, signature, completed) {
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true, mode: 0o700 });
+    const temporary = `${manifestPath}.${process.pid}.tmp`;
+    const manifest = {
+        schemaVersion: 1,
+        signature,
+        completed,
+        updatedAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(temporary, `${JSON.stringify(manifest, null, 2)}\n`, {
+        encoding: "utf-8",
+        mode: 0o600,
+        flag: "wx",
+    });
+    fs.renameSync(temporary, manifestPath);
+}
+async function initializeOneRepository(repository, options) {
+    try {
+        if (options.indexMode?.(repository) === "provenance-only") {
+            return {
+                repository,
+                status: "skipped",
+                message: "provenance-only policy: graph indexing and lifecycle hooks require an explicit index: full override",
+            };
+        }
+        if (!options.dryRun && options.isolatedInitialize) {
+            return await options.isolatedInitialize(repository);
+        }
+        const databaseExists = fs.existsSync(path.join(repository, ".reckon", "db.sqlite"));
+        const integration = readRepositoryIntegrationConfig(repository);
+        const scope = integration?.scope ?? "personal";
+        const agents = [...new Set([...(options.agents ?? []), ...(integration?.agents ?? [])])];
+        const current = await isRepositoryInitializationCurrent(repository, options.command, scope);
+        if (options.dryRun)
+            return dryRunInitialization(repository, databaseExists, current);
+        const health = databaseExists ? await options.status(repository) : null;
+        if (current && health?.status === "healthy") {
+            return {
+                repository,
+                status: "already-current",
+                message: "managed installation and graph are healthy",
+            };
+        }
+        const healthy = health?.status === "healthy";
+        await initializeRepository(repository, {
+            command: options.command,
+            index: healthy ? async () => undefined : options.index,
+            scope,
+            agents,
+        });
+        return {
+            repository,
+            status: databaseExists ? "updated" : "initialized",
+            message: initializationMessage(databaseExists, healthy),
+        };
+    }
+    catch (error) {
+        return {
+            repository,
+            status: "failed",
+            message: errorMessage(error),
+        };
+    }
+}
+export async function initializeRepositories(roots, options) {
+    const depth = options.depth ?? DEFAULT_DEPTH;
+    const worktrees = options.worktrees ?? "skip";
+    const discovery = await discoverGitRepositoryPaths(roots, depth, worktrees);
+    const identities = new Map(discovery.repositories.map((repository) => [repository, repositoryIdentity(repository)]));
+    const selectorMatches = (repository, selector) => selector === repository ||
+        canonicalRepositorySelector(selector) === repository ||
+        selector === identities.get(repository);
+    const unknownSelectors = (options.include ?? []).filter((selector) => !discovery.repositories.some((repository) => selectorMatches(repository, selector)));
+    if (unknownSelectors.length > 0) {
+        throw new Error(`knodin repos init: include selector(s) matched no discovered repository: ${unknownSelectors.join(", ")}`);
+    }
+    const repositories = discovery.repositories.filter((repository) => ((options.include?.length ?? 0) === 0 ||
+        (options.include ?? []).some((selector) => selectorMatches(repository, selector))) &&
+        !(options.exclude ?? []).some((selector) => selectorMatches(repository, selector)));
+    const signature = initializationSignature(repositories, depth, worktrees);
+    const manifestPath = options.manifestPath ? path.resolve(options.manifestPath) : undefined;
+    const previousManifest = readInitializationManifest(manifestPath, signature);
+    const completedByRepository = new Map((previousManifest?.completed ?? []).map((result) => [result.repository, result]));
+    const results = discovery.issues.map((issue) => ({
+        repository: issue.path,
+        status: "failed",
+        message: `discovery failed: ${issue.message}`,
+    }));
+    for (const emptyRoot of discovery.emptyRoots) {
+        results.push({
+            repository: emptyRoot,
+            status: "skipped",
+            message: `no Git worktree found within depth ${depth}`,
+        });
+    }
+    for (const stale of discovery.staleWorktrees) {
+        results.push({
+            repository: stale.path,
+            status: "skipped",
+            message: `stale worktree metadata: ${stale.message}`,
+        });
+    }
+    for (const repository of repositories) {
+        const completed = completedByRepository.get(repository);
+        if (completed) {
+            results.push(completed);
+            continue;
+        }
+        const result = await initializeOneRepository(repository, options);
+        results.push(result);
+        if (manifestPath &&
+            !options.dryRun &&
+            (result.status === "initialized" ||
+                result.status === "updated" ||
+                result.status === "already-current")) {
+            completedByRepository.set(repository, result);
+            writeInitializationManifest(manifestPath, signature, [...completedByRepository.values()]);
+        }
+    }
+    results.sort((left, right) => left.repository.localeCompare(right.repository));
+    const measured = results.filter(({ peakRssBytes }) => peakRssBytes !== undefined);
+    return {
+        exitCode: results.some(({ status }) => status === "failed") ? 1 : 0,
+        worktrees,
+        results,
+        resources: {
+            isolated: options.isolatedInitialize !== undefined && !options.dryRun,
+            peakRepositoryRssBytes: measured.length > 0
+                ? Math.max(...measured.map(({ peakRssBytes }) => peakRssBytes ?? 0))
+                : null,
+            memoryLimitBytes: measured.find(({ memoryLimitBytes }) => memoryLimitBytes !== undefined)?.memoryLimitBytes ??
+                null,
+            memoryLimitFailures: results.filter(({ message }) => message.includes("memory ceiling exceeded")).length,
+        },
+        ...(manifestPath
+            ? {
+                manifest: {
+                    path: manifestPath,
+                    resumed: previousManifest !== null,
+                    completed: completedByRepository.size,
+                    total: repositories.length,
+                },
+            }
+            : {}),
+    };
+}
+/** Stable line-oriented output for humans and logs that are not JSON consumers. */
+export function formatRepositoryHuman(summary) {
+    const width = Math.max("already-current".length, ...summary.results.map(({ status }) => status.length));
+    const lines = summary.results.map((result) => {
+        const detail = result.message ? ` — ${result.message}` : "";
+        return `${result.status.padEnd(width)}  ${result.repository}${detail}`;
+    });
+    const counts = new Map();
+    for (const result of summary.results)
+        counts.set(result.status, (counts.get(result.status) ?? 0) + 1);
+    const order = [
+        "initialized",
+        "updated",
+        "already-current",
+        "skipped",
+        "failed",
+    ];
+    const totals = order
+        .filter((status) => counts.has(status))
+        .map((status) => `${counts.get(status)} ${status}`);
+    lines.push(`${summary.results.length} entries: ${totals.join(", ")}; .worktrees policy=${summary.worktrees}`);
+    return `${lines.join("\n")}\n`;
+}