knodin 0.7.5 → 0.8.2

package/dist/src/tools/knodin-tools.js

@@ -12,6 +12,7 @@ import { resolveCliRuntimeCommand } from "../cli-args.js";
 import { compactExplainResult, compactQueryResult, compactSearchResult, expandCompactIdentity, } from "../compact-structural.js";
 import { buildKnodinContext } from "../context.js";
 import { exportContext, grepPackedArtifact, readPackedArtifact } from "../context-export.js";
+import { collectDiagnostics, persistDiagnosticsPreview } from "../diagnostics.js";
 import { getDocSection, listDocTopics } from "../docs-sections.js";
 import { diagnoseInstallation } from "../doctor.js";
 import { createEngine, REPO_WIDE_QUERY_PATTERNS, } from "../engine/index.js";
@@ -21,6 +22,7 @@ import { diagnoseFailure, } from "../failure-diagnosis.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../graph-query-health.js";
 import { inspectRepositoryIntegrationStatus } from "../init.js";
 import { attachLifecycleHealth, attachRepairLifecycle } from "../lifecycle-health.js";
+import { listMirrors } from "../mirror.js";
 import { compressOutput, compressOutputFile, deleteOutputArtifact, readOutputArtifact, } from "../output-compression.js";
 import { appendTelemetryRecord, clearTelemetry, countOutputTokens, exportTelemetry, measureOutput, readTelemetryRecords, telemetryStatus, writeTelemetryReport, } from "../output-telemetry.js";
 import { auditPullRequests, ghUnavailableReason, triagePrDetail } from "../pr-triage.js";
@@ -29,7 +31,7 @@ import { createRepairPlan } from "../repair-progress.js";
 import { runRepositoryInitializationProcess } from "../repository-init-process.js";
 import { discoverRepositories, initializeRepositories, inventoryRepository, searchRepositories, } from "../repository-management.js";
 import { applyResponseBudget } from "../response-budget.js";
-import { enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../system-config.js";
+import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../system-config.js";
 import { trustedUpdateStatus } from "../update-policy.js";
 import { waitForFresh } from "../wait-for-fresh.js";
 import { inspectWorktrees, reconcileWorktrees, removeManagedWorktree, } from "../worktree-lifecycle.js";
@@ -177,10 +179,12 @@ function buildDocumentedKnodinTools() {
                             "worktrees",
                             "repair",
                             "repositories",
+                            "remote",
                             "system",
                             "telemetry",
+                            "diagnostics",
                         ],
-                        description: "Which knodin capability to run. context: call this FIRST when starting any investigation and unsure which operation to reach for — one ultra-compact orientation (repo stats + top subsystems/hubs/flows + a risk score if there's a diff + a heuristic next-operation suggestion); the suggestion is only a hint and never blocks calling any operation directly. explain: use when orienting on a symbol/file or before editing it — returns edit-ready source + call paths + blast radius. review: use before writing a PR description or approving a diff — risk-scored context (changed symbols, affected flows, test gaps). map: use before a cross-cutting refactor or to understand subsystem boundaries — communities + hub/bridge nodes + confidence-tagged edges. search: use when you don't know the exact symbol name — hybrid semantic + keyword lookup over code symbols. query: use for a structured question about a known symbol — callers_of, tests_for, shortest_path, dead_code, rename_preview, flows, and more (see `pattern`). pack: create deterministic Markdown/JSON/XML source context under hard budgets, or bounded-read/exact-regex-grep a saved artifact. compress: reduce already-produced diagnostic text under exact line/content-byte budgets, preserve exit metadata and detected signals, retain private local drill-down data by default, and never label insufficient-fidelity output complete. execute: run one immutable repository-defined profile only when independently enabled globally and locally; no executable or argv is accepted from the caller, unsupported containment fails closed, and output is compressed then diagnosed. prs: use to triage open GitHub PRs (via your local authenticated `gh`) — per-PR status, CI, and blast radius sorted ready-small-impact first; pass `prNumber` for one PR's impacted files + community names. wiki: write a static markdown documentation site for the repository's logical subsystems to `.knodin/wiki/`. Generates an index plus one page per mapped community. Reuses the `map` output. Idempotent: unchanged pages are untouched on disk unless `force` is true. docs: call this to retrieve curated, focused markdown usage guidance directly over MCP.",
+                        description: "Which knodin capability to run. context: call this FIRST when starting any investigation and unsure which operation to reach for — one ultra-compact orientation (repo stats + top subsystems/hubs/flows + a risk score if there's a diff + a heuristic next-operation suggestion); the suggestion is only a hint and never blocks calling any operation directly. explain: use when orienting on a symbol/file or before editing it — returns edit-ready source + call paths + blast radius. review: use before writing a PR description or approving a diff — risk-scored context (changed symbols, affected flows, test gaps). map: use before a cross-cutting refactor or to understand subsystem boundaries — communities + hub/bridge nodes + confidence-tagged edges. search: use when you don't know the exact symbol name — hybrid semantic + keyword lookup over code symbols. query: use for a structured question about a known symbol — callers_of, tests_for, shortest_path, dead_code, rename_preview, flows, and more (see `pattern`). pack: create deterministic Markdown/JSON/XML source context under hard budgets, or bounded-read/exact-regex-grep a saved artifact. compress: reduce already-produced diagnostic text under exact line/content-byte budgets, preserve exit metadata and detected signals, retain private local drill-down data by default, and never label insufficient-fidelity output complete. execute: run one immutable repository-defined profile only when independently enabled globally and locally; no executable or argv is accepted from the caller, unsupported containment fails closed, and output is compressed then diagnosed. prs: use to triage open GitHub PRs (via your local authenticated `gh`) — per-PR status, CI, and blast radius sorted ready-small-impact first; pass `prNumber` for one PR's impacted files + community names. wiki: write a static markdown documentation site for the repository's logical subsystems to `.knodin/wiki/`. Generates an index plus one page per mapped community. Reuses the `map` output. Idempotent: unchanged pages are untouched on disk unless `force` is true. docs: call this to retrieve curated, focused markdown usage guidance directly over MCP. remote: list read-only mirrors of repositories that are reachable but not checked out locally, so you can run explain/query/map/search against one by passing its `path` as `repoPath`. Each mirror is a snapshot pinned at a commit; the remote is not watched. Acquiring, refreshing, and removing mirrors is CLI-only (`knodin remote add|refresh|remove`) because it clones another repository's source onto this machine and consumes disk nothing reclaims automatically — the user's decision to make, not an agent's.",
                     },
                     profile: {
                         type: "string",
@@ -442,7 +446,7 @@ function buildDocumentedKnodinTools() {
                     telemetryAction: {
                         type: "string",
                         enum: ["records", "status", "report", "export", "clear"],
-                        description: "telemetry action.",
+                        description: "telemetry action; diagnostics uses report (preview) or export (archive).",
                     },
                     telemetryRetentionDays: {
                         type: "integer",
@@ -631,17 +635,23 @@ function buildDocumentedKnodinTools() {
                     statusAudit: {
                         type: "string",
                         enum: ["cached", "deep"],
-                        description: "status only: cached (default) reuses a warm deep audit only after a bounded freshness probe; deep forces a complete filesystem/schema/orphan audit.",
+                        description: "status: cached (default) or complete deep audit.",
                     },
                     timeoutMs: {
-                        type: "number",
+                        type: "integer",
                         minimum: 0,
-                        maximum: 300000,
+                        maximum: 300_000,
                         description: "wait: maximum milliseconds to wait for freshness.",
                     },
+                    sinceHours: {
+                        type: "integer",
+                        minimum: 1,
+                        maximum: 8_760,
+                        description: "diagnostics: history window in hours (default 24).",
+                    },
                     client: {
                         type: "string",
-                        enum: ["claude", "codex", "gemini", "antigravity"],
+                        enum: ["claude", "codex", "gemini", "copilot", "antigravity"],
                         description: "doctor: optionally return one client-specific integration diagnosis.",
                     },
                     repairPlan: {
@@ -662,26 +672,32 @@ function buildDocumentedKnodinTools() {
 export function getDocumentedKnodinToolsForSchemaProof() {
     return buildDocumentedKnodinTools();
 }
-const COMPACT_TOOL_DESCRIPTION = "Local code intelligence.";
 const COMPACT_PARAMETER_DESCRIPTIONS = {
     operation: "Capability.",
     symbol: "Target.",
     pattern: "Query pattern.",
-    impactMode: "Symbol or file impact.",
-    apply: "Apply verified edits.",
-    diffScope: "Review diff scope.",
-    section: "Documentation section.",
-    persistTelemetry: "Persist metadata telemetry.",
+    impactMode: "Symbol or file.",
+    apply: "Apply edits.",
+    // Shortened from "Review diff scope." / "Documentation section." on main: the
+    // `remote` operation added to the enum costs tokens, and this surface has a
+    // hard ceiling enforced by tool-schema-budget.spec.ts.
+    diffScope: "Diff scope.",
+    section: "Docs section.",
+    persistTelemetry: "Persist telemetry.",
 };
-function compactParameterDescription(name, description) {
-    void description;
+/**
+ * The documented description is deliberately discarded: the compact surface
+ * carries only the curated one-liners, and falling back to full prose would
+ * reintroduce the per-tool context cost this surface exists to avoid.
+ */
+function compactParameterDescription(name, _description) {
     return COMPACT_PARAMETER_DESCRIPTIONS[name];
 }
 /** The compact, always-on MCP surface. Full prose remains available via docs. */
 export function getKnodinTools() {
     const tools = buildDocumentedKnodinTools();
     for (const tool of tools) {
-        tool.description = COMPACT_TOOL_DESCRIPTION;
+        tool.description = undefined;
         const properties = tool.inputSchema.properties;
         for (const [name, property] of Object.entries(properties)) {
             property.description = compactParameterDescription(name, property.description);
@@ -703,6 +719,8 @@ const RESPONSE_DEFAULTS = {
     "explain:minimal": { bytes: 16_384, tokens: 4_096, items: 25 },
     map: { bytes: 131_072, tokens: 32_768, items: 200 },
     "map:minimal": { bytes: 32_768, tokens: 8_192, items: 15 },
+    "diagnostics:preview": { bytes: 524_288, tokens: 131_072, items: 1_000 },
+    "diagnostics:archive": { bytes: 65_536, tokens: 16_384, items: 100 },
     default: { bytes: 65_536, tokens: 16_384, items: 100 },
 };
 async function populateRepositoryDiagnoses(records, repositories, configRoot) {
@@ -757,6 +775,7 @@ async function handleRepositoriesOperation(options) {
     if (repositoryAction === "init") {
         const command = gatewayCliCommand();
         const systemConfig = loadSystemConfiguration(discoveryRoots[0] ?? repo);
+        const memoryLimitBytes = configuredRepositoryInitMemoryLimitBytes(systemConfig);
         const summary = await initializeRepositories(discoveryRoots, {
             command,
             index: (target) => engine.index(target),
@@ -766,7 +785,7 @@ async function handleRepositoriesOperation(options) {
             dryRun,
             manifestPath,
             indexMode: (target) => indexModeForPath(systemConfig, target),
-            isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command }),
+            isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command, memoryLimitBytes }),
         });
         const { repositories } = await inventory();
         return bounded({ schemaVersion: 1, ...summary, repositories }, "repositories:init");
@@ -898,8 +917,19 @@ function validateKnodinArgs(args) {
     if (args.timeoutMs !== undefined &&
         (!Number.isInteger(args.timeoutMs) || args.timeoutMs < 0 || args.timeoutMs > 300_000))
         throw new Error("knodin: timeoutMs must be an integer between 0 and 300000");
+    if (args.operation === "diagnostics" &&
+        args.telemetryAction !== undefined &&
+        !["report", "export"].includes(args.telemetryAction))
+        throw new Error("knodin: diagnostics telemetryAction must be report or export");
+    if (args.sinceHours !== undefined &&
+        (!Number.isInteger(args.sinceHours) || args.sinceHours < 1 || args.sinceHours > 8760))
+        throw new Error("knodin: sinceHours must be an integer from 1 through 8760");
+    if (args.operation === "diagnostics" &&
+        args.artifactId !== undefined &&
+        !/^[a-f0-9]{32}$/.test(args.artifactId))
+        throw new Error("knodin: diagnostics artifactId must be a preview ID");
     if (args.client !== undefined &&
-        !["claude", "codex", "gemini", "antigravity"].includes(args.client))
+        !["claude", "codex", "gemini", "copilot", "antigravity"].includes(args.client))
         throw new Error("knodin: invalid client");
 }
 function compactExplainSource(result) {
@@ -1209,7 +1239,53 @@ async function tryCompactStructural(args, repo, selector, bounded) {
             (await runCompactQuery(compactPattern, symbol ?? "", repo, Math.min(args.limit ?? args.itemBudget ?? 100, args.itemBudget ?? 1000), args.depth, selector, byteBudget)),
     };
 }
-export async function handleKnodinTool(args) {
+const mcpRequestSignals = new WeakMap();
+export function attachMcpRequestSignal(args, signal) {
+    if (args && typeof args === "object")
+        mcpRequestSignals.set(args, signal);
+    return args;
+}
+async function repairLifecycleForRequest(repo, args) {
+    const signal = args && typeof args === "object" ? mcpRequestSignals.get(args) : undefined;
+    return attachRepairLifecycle(repo, await engine.repair(repo, { signal }));
+}
+async function handleDiagnosticsOperation(repo, args, bounded) {
+    let graph;
+    let doctor;
+    try {
+        graph = attachLifecycleHealth(repo, await engine.status(repo, { audit: "deep" }));
+    }
+    catch {
+        // A support bundle must remain available when graph diagnostics fail.
+    }
+    if (graph) {
+        try {
+            doctor = await diagnoseInstallation(repo, {
+                currentVersion: graph.version,
+                runtimeCommand: [process.execPath, process.argv[1] ?? "", "serve"],
+                graph,
+                client: args.client,
+            });
+        }
+        catch {
+            // The allowlisted health section reports installation as unavailable.
+        }
+    }
+    const options = {
+        sinceHours: args.sinceHours ?? 24,
+        doctor,
+        graph,
+        knodinVersion: graph?.version,
+    };
+    return bounded(args.telemetryAction === "export"
+        ? collectDiagnostics(repo, {
+            ...options,
+            outputPath: args.outputPath,
+            previewId: args.artifactId,
+        })
+        : persistDiagnosticsPreview(repo, options), `diagnostics:${args.telemetryAction === "export" ? "archive" : "preview"}`);
+}
+async function dispatchKnodinTool(args) {
     const startedAt = performance.now();
     const parsedArgs = (args ?? {});
     const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
@@ -1230,9 +1306,8 @@ export async function handleKnodinTool(args) {
     const observe = (output, op, minimal = false) => {
         const root = output;
         const budgetMeta = root.responseBudget;
-        if (op === "review") {
+        if (op === "review")
             measurePerfPhaseSync("review_serialization", () => JSON.stringify(output));
-        }
         const telemetry = measureOutput({
             repo,
             operation: op,
@@ -1243,18 +1318,16 @@ export async function handleKnodinTool(args) {
                 root.telemetry?.truncated === true,
             schemaTokens: gatewaySchemaTokens(),
         });
-        if (op === "execute" && parsedArgs.profile) {
+        if (op === "execute" && parsedArgs.profile)
             telemetry.executionProfile = parsedArgs.profile;
-        }
         telemetry.temperature = localTelemetry.some(({ operation, repositoryId }) => operation === op && repositoryId === telemetry.repositoryId)
             ? "warm"
             : "cold";
         localTelemetry.push(telemetry);
         if (localTelemetry.length > 1000)
             localTelemetry.shift();
-        if (persistTelemetry === true) {
+        if (persistTelemetry === true)
             appendTelemetryRecord(repo, telemetry, telemetryRetentionDays);
-        }
         return root;
     };
     const bounded = (result, op = String(operation), minimal = false) => {
@@ -1279,6 +1352,8 @@ export async function handleKnodinTool(args) {
     if (detailLevel === "compact")
         throw new Error("knodin: compact detail is unsupported here");
     switch (operation) {
+        case "diagnostics":
+            return handleDiagnosticsOperation(repo, parsedArgs, bounded);
         case "telemetry": {
             const action = telemetryAction ?? "records";
             if (action === "records")
@@ -1324,7 +1399,29 @@ export async function handleKnodinTool(args) {
         case "repair":
             if (repairPlan)
                 return bounded(createRepairPlan(await engine.status(repo, { audit: "deep" })), "repair:plan");
-            return bounded(attachRepairLifecycle(repo, await engine.repair(repo)), "repair");
+            return bounded(await repairLifecycleForRequest(repo, args), "repair");
+        case "remote": {
+            // Read-only over MCP by design. Acquiring a mirror clones another
+            // repository's source onto this machine and consumes disk that nothing
+            // reclaims automatically; refresh discards local state and remove
+            // deletes a graph that cost minutes to build. Those are the user's
+            // calls, made explicitly at the CLI, not side effects of an agent's
+            // investigation. Listing is safe and is what makes a mirror usable:
+            // pass a listed `path` as `repoPath` to explain/query/map/search it.
+            const mirrors = listMirrors().map((mirror) => ({
+                identity: mirror.identity,
+                url: mirror.url,
+                path: mirror.path,
+                snapshot: mirror.sha,
+                fetchedAt: mirror.fetchedAt,
+                readOnly: true,
+            }));
+            return bounded({
+                mirrors,
+                acquisition: "CLI only: `knodin remote add <url>` / `refresh <identity>` / `remove <identity>`.",
+                note: "Each mirror is a snapshot pinned at `snapshot`; the remote is not watched, so results describe that commit and no later one.",
+            }, "remote:list");
+        }
         case "repositories": {
             if (!repositoryAction)
                 throw new Error("knodin repositories requires `repositoryAction`");
@@ -1517,13 +1614,27 @@ export async function handleKnodinTool(args) {
             const result = pattern === "impact" || pattern === "dead_code"
                 ? incorporateSystemQueryEvidence(await enrichSystemRelationships(loadSystemConfiguration(repo)), repo, pattern, symbol ?? "", queryResult)
                 : queryResult;
-            return bounded(queryHealth?.available
-                ? decorateGraphQueryResult(result, verifiedQueryHealth?.available ? verifiedQueryHealth.state : queryHealth.state, verifiedQueryHealth?.available
-                    ? verifiedQueryHealth.graph.freshness
-                    : queryHealth.graph.freshness)
-                : result, `query:${pattern}`);
+            let decorated = result;
+            if (queryHealth?.available) {
+                // A verified probe supersedes the unverified one for both fields, so
+                // state and freshness always come from the same observation.
+                const authoritative = verifiedQueryHealth?.available ? verifiedQueryHealth : queryHealth;
+                decorated = decorateGraphQueryResult(result, authoritative.state, authoritative.graph.freshness);
+            }
+            return bounded(decorated, `query:${pattern}`);
         }
         default:
             throw new Error(`unknown knodin operation: ${String(operation)}`);
     }
 }
+let responseTestMutator;
+/** @internal Test-only response seam. Production callers must never register a mutator. */
+export function setKnodinResponseTestMutator(mutator) {
+    if (process.env.KNODIN_C95_TEST_MODE !== "offline-contract-replay")
+        throw new Error("knodin: C95 response mutation seam is unavailable outside its test replay");
+    responseTestMutator = mutator;
+}
+export async function handleKnodinTool(args) {
+    const response = await dispatchKnodinTool(args);
+    return responseTestMutator ? responseTestMutator(args, response) : response;
+}

package/dist/src/update-ceremony.js

@@ -1,10 +1,11 @@
 import { createHash, createPublicKey } from "node:crypto";
+import { compareBytes } from "./compare.js";
 import { canonicalizeUpdateMetadata, verifyUpdateRootChain, } from "./update-trust.js";
 const SHA256 = /^[0-9a-f]{64}$/;
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{2,63}$/;
 function exactKeys(value, expected, label) {
-    const actual = Object.keys(value).sort();
-    const wanted = [...expected].sort();
+    const actual = Object.keys(value).sort(compareBytes);
+    const wanted = [...expected].sort(compareBytes);
     if (actual.join("\0") !== wanted.join("\0"))
         throw new Error(`${label} contains missing or unknown fields`);
 }
@@ -78,8 +79,10 @@ export function validateRootCeremonyManifest(value) {
     const assigned = manifest.custodians
         .filter((c) => c.role === "root-signer")
         .map((c) => c.publicKeyId)
-        .sort();
-    if (assigned.join("\0") !== [...manifest.roleKeyIds.root].sort().join("\0"))
+        // `publicKeyId` is optional on the type but validated present for every
+        // root-signer above; `sort` also never passes undefined to a comparator.
+        .sort((left, right) => compareBytes(left ?? "", right ?? ""));
+    if (assigned.join("\0") !== [...manifest.roleKeyIds.root].sort(compareBytes).join("\0"))
         throw new Error("root signer assignments must exactly match root role keys");
     const recovery = manifest.custodians.filter((c) => c.role === "recovery");
     if (recovery.length < manifest.thresholds.root ||
@@ -134,7 +137,8 @@ export function preparePublicRootImport(envelope, pin, manifestValue, receiptVal
         const expected = manifest.roleKeyIds[role];
         const actual = envelope.signed.roles[role];
         if (actual.threshold !== manifest.thresholds[role] ||
-            [...actual.keyids].sort().join("\0") !== [...expected].sort().join("\0"))
+            [...actual.keyids].sort(compareBytes).join("\0") !==
+                [...expected].sort(compareBytes).join("\0"))
             throw new Error(`manifest ${role} role does not match root envelope`);
     }
     for (const key of Object.values(envelope.signed.keys)) {

package/dist/src/update-trust.js

@@ -1,4 +1,5 @@
 import { createHash, createPublicKey, verify as cryptoVerify, timingSafeEqual, } from "node:crypto";
+import { compareBytes } from "./compare.js";
 export class UpdateTrustError extends Error {
     code;
     role;
@@ -53,10 +54,10 @@ function canonicalize(value, seen) {
     seen.add(value);
     const object = value;
     const serialized = `{${Object.keys(object)
-        // ECMAScript's default code-unit ordering is locale-independent, which is
-        // required because these bytes are signed on one host and verified on another.
-        // A localeCompare comparator would make trust bytes depend on host ICU data.
-        .sort() // NOSONAR: cryptographic canonicalization must not use locale collation.
+        // Code-unit ordering is locale-independent, which is required because these
+        // bytes are signed on one host and verified on another. A localeCompare
+        // comparator would make trust bytes depend on host ICU data.
+        .sort(compareBytes)
         .map((key) => {
         if (object[key] === undefined)
             invalid(`metadata field ${key} must not be undefined`);