knodin 0.8.7 → 0.9.0

package/dist/src/cli-model.js

@@ -175,6 +175,29 @@ function addGraphCommands(program, capture) {
         .option("--apply", "apply the verified edit")
         .option("--no-verify", "skip post-apply typecheck");
 }
+function addBackupCommands(program, capture) {
+    const backups = program.command("backups").description("inspect and prune local graph backups");
+    leaf(backups, "list [roots...]", "list exact completed backup snapshots", capture)
+        .addOption(option("--depth <count>", "maximum discovery depth", "integer"))
+        .option("--jsonl", "stream one record per line");
+    leaf(backups, "prune [roots...]", "preview or apply safe backup pruning", capture)
+        .option("--apply", "delete exact preview candidates after revalidation")
+        .addOption(option("--retention-days <count>", "retention window in days", "integer"))
+        .addOption(option("--keep-newest <count>", "newest backups retained per repository", "integer"))
+        .addOption(option("--depth <count>", "maximum discovery depth", "integer"))
+        .option("--jsonl", "stream one record per line");
+    const retention = backups.command("retention").description("manage opt-in ongoing retention");
+    leaf(retention, "install [roots...]", "install daily and opportunistic retention", capture)
+        .addOption(option("--retention-days <count>", "retention window in days", "integer"))
+        .addOption(option("--keep-newest <count>", "newest backups retained per repository", "integer"))
+        .addOption(option("--depth <count>", "maximum discovery depth", "integer"))
+        .option("--schedule <time>", "daily local HH:MM schedule")
+        .option("--dry-run", "install a policy that logs without deleting")
+        .option("--jsonl", "stream one record per line");
+    for (const action of ["status", "doctor", "remove"])
+        leaf(retention, action, `${action} installed backup retention`, capture);
+    leaf(retention, "run", "run the installed retention policy", capture);
+}
 function addArtifactCommands(program, capture) {
     leaf(program, "evidence <level> <file>", "deliver progressive source evidence", capture)
         .option("--continuation <handle>", "resume an exact prior response")
@@ -241,8 +264,8 @@ function createCliProgram(capture = () => { }) {
         .exitOverride();
     program.configureOutput({ writeErr: () => { } });
     addGlobalOptions(program);
-    program.addHelpText("after", "\nMCP callers use the `prs` operation and corresponding operations on the single `knodin` gateway.\nknodin update status|check|explain|apply|rollback consumes only threshold-signed metadata.\n");
-    leaf(program, "init", "initialize graph, lifecycle hooks, and agent integration", capture)
+    program.addHelpText("after", "\nMCP callers use the `prs` operation and corresponding operations on the single `knodin` gateway.\nLegacy update status|check|explain|apply|rollback consumes only threshold-signed metadata. Manager-aware available|upgrade|pin|unpin|acknowledge|auto binds actions to the proven active owner.\n");
+    leaf(program, "init", "initialize graph and lifecycle hooks; configure agents only with --scope", capture)
         .option("--scope <scope>", "personal, team, or cli-only")
         .addHelpText("after", "\nUsage: knodin init [--scope personal|team|cli-only] [--json]\n\npersonal  recommended; local/excluded agent adapters and a clean Git status\nteam      commit-ready shared agent configuration\ncli-only  no agent discovery; AI agents will not know to invoke knodin\n\nChange later with `knodin configure --scope <scope>`.\nTracked files are never added to Git exclude files.\n");
     leaf(program, "configure", "change or inspect agent integration", capture)
@@ -286,6 +309,7 @@ function createCliProgram(capture = () => { }) {
     leaf(program, "agent-event <event>", "internal coding-agent lifecycle event", capture);
     leaf(program, "refresh-artifacts [event]", "refresh external graph artifacts", capture);
     addRepositoryCommands(program, capture);
+    addBackupCommands(program, capture);
     addRemoteCommands(program, capture);
     addSharedIndexCommands(program, capture);
     addGraphCommands(program, capture);
@@ -327,12 +351,15 @@ function createCliProgram(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")
-        .allowExcessArguments(false)
-        .addArgument(new Argument("<action>").choices(["status", "check", "explain", "apply", "rollback"]));
-    update.action((...values) => capture(values.at(-1)));
+    const update = program.command("update").description("inspect or apply verified updates");
+    for (const action of ["status", "check", "explain", "apply", "rollback"])
+        leaf(update, action, `${action} threshold-signed updates`, capture);
+    leaf(update, "available", "query the active owner's release channel", capture);
+    leaf(update, "upgrade [version]", "plan or apply an exact verified upgrade", capture).option("--apply", "execute the owning package manager");
+    leaf(update, "pin <version>", "pin an exact version", capture).option("--apply", "install and verify the pinned version");
+    leaf(update, "unpin", "remove the active update pin", capture);
+    leaf(update, "acknowledge", "acknowledge the current rollback notice", capture);
+    leaf(update, "auto <action>", "status, enable, disable, or run automatic updates", capture);
     leaf(program, "docs <topic>", "read canonical product documentation", capture);
     leaf(program, "prs [action]", "audit pull requests, reviews, and checks", capture)
         .option("--state <state>", "open, merged, closed, or all")

package/dist/src/docs-sections.js

@@ -112,6 +112,7 @@ const DOC_TOPIC_FILES = {
     provenance: "INDEXING-POLICY-AND-PROVENANCE.md",
     "dead-code": "DEAD-CODE-AND-IMPACT.md",
     doctor: "DOCTOR-AND-UPDATES.md",
+    backups: "BACKUP-RETENTION.md",
     compression: "COMMAND-OUTPUT-COMPRESSION.md",
 };
 function packageRoot() {

package/dist/src/doctor.js

@@ -3,7 +3,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { detectSupportedAgents } from "./agent-integration.js";
+import { listBackups, pruneBackups, retentionDoctor } from "./backup-retention.js";
 import { inspectLifecycleHealth } from "./lifecycle-health.js";
+import { readManagerUpdateState, readUpdateJournal, resolveManagerOwnership, updateAttention, } from "./manager-update.js";
 import { trustedUpdateStatus } from "./update-policy.js";
 function defaultRun(command, args, options = {}) {
     const result = child_process.spawnSync(command, args, {
@@ -141,12 +143,83 @@ function sanitizeRegistry(raw) {
         return "unknown";
     }
 }
+const MANAGED_REPOSITORY_PATHS = [
+    "AGENTS.md",
+    "GEMINI.md",
+    ".mcp.json",
+    ".codex/config.toml",
+    ".gemini/settings.json",
+    ".vscode/mcp.json",
+    ".agents/mcp_config.json",
+];
+function managedConfigurationRemediation(repo, run) {
+    const paths = [...MANAGED_REPOSITORY_PATHS];
+    for (const root of [".agents/skills", ".claude/skills", ".gemini/skills"]) {
+        const absolute = path.join(repo, root);
+        let entries = [];
+        try {
+            entries = fs.readdirSync(absolute, { withFileTypes: true }).slice(0, 64);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const relative = path.posix.join(root, entry.name);
+            if (fs.existsSync(path.join(repo, relative, ".knodin-managed.json")))
+                paths.push(relative);
+        }
+    }
+    return paths
+        .map((relative) => {
+        const absolute = path.join(repo, relative);
+        const present = fs.existsSync(absolute);
+        const trackedResult = run("git", ["-C", repo, "ls-files", "--error-unmatch", "--", relative]);
+        const tracked = trackedResult.status === 0;
+        const diffResult = tracked
+            ? run("git", ["-C", repo, "diff", "--no-ext-diff", "--unified=3", "--", relative])
+            : { status: 0, stdout: "", stderr: "" };
+        const receipted = fs.existsSync(path.join(absolute, ".knodin-managed.json"));
+        let entryOwned = false;
+        if (present && !receipted) {
+            try {
+                entryOwned = fs.readFileSync(absolute, "utf8").includes("knodin");
+            }
+            catch {
+                entryOwned = false;
+            }
+        }
+        const instructions = [];
+        if (tracked && diffResult.stdout)
+            instructions.push(`Review the diff, then restore manually with: git restore --source=HEAD -- ${relative}`);
+        if (!tracked && receipted)
+            instructions.push(`Review the Knodin receipt, then remove manually if unwanted: ${relative}`);
+        if (!tracked && present && (receipted || entryOwned))
+            instructions.push(`To retain it locally without committing, add ${relative} to .git/info/exclude manually.`);
+        return {
+            path: relative,
+            tracked,
+            present,
+            ownership: receipted ? "knodin-receipt" : entryOwned ? "knodin-entry" : "none",
+            diff: diffResult.stdout ? diffResult.stdout.slice(0, 32_768) : null,
+            instructions,
+        };
+    })
+        .filter((entry) => entry.present || entry.tracked || entry.diff !== null || entry.ownership !== "none");
+}
 function readAgentConfig(agent, file) {
     try {
         const content = fs.readFileSync(file, "utf-8");
         if (agent === "claude" && path.basename(file) === ".claude.json") {
             const present = content.includes('"knodin"');
-            return { agent, file, present, command: present ? "knodin" : null, args: ["serve"] };
+            return {
+                agent,
+                file,
+                present,
+                command: present ? "knodin" : null,
+                args: ["serve"],
+            };
         }
         if (file.endsWith(".toml")) {
             const sectionStart = content.indexOf('[mcp_servers."knodin"]');
@@ -273,15 +346,27 @@ function mcpProbe(command, run) {
                 clientInfo: { name: "knodin-doctor", version: "1" },
             },
         }),
-        JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }),
+        JSON.stringify({
+            jsonrpc: "2.0",
+            method: "notifications/initialized",
+            params: {},
+        }),
         JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }),
         "",
     ].join("\n");
     const [executable, ...args] = command;
     if (!executable)
-        return { initialize: "failed", toolsList: "failed", toolNames: [], stderr: "no command" };
+        return {
+            initialize: "failed",
+            toolsList: "failed",
+            toolNames: [],
+            stderr: "no command",
+        };
     const result = run(executable, args, { input });
-    return { ...parseMcp(result.stdout), stderr: result.status === 0 ? undefined : result.stderr };
+    return {
+        ...parseMcp(result.stdout),
+        stderr: result.status === 0 ? undefined : result.stderr,
+    };
 }
 export async function diagnoseInstallation(repoPath, options) {
     const repo = path.resolve(repoPath);
@@ -298,6 +383,7 @@ export async function diagnoseInstallation(repoPath, options) {
     const detectedAgents = detectSupportedAgents();
     const repositoryCommands = configuredAgentCommands(repo);
     const personalCommands = personalAgentCommands(options.homeDir ?? os.homedir());
+    const configurationRemediation = managedConfigurationRemediation(repo, run);
     const clients = repositoryCommands
         .filter(({ agent }) => options.client === undefined || options.client === agent)
         .map((repository) => {
@@ -323,7 +409,16 @@ export async function diagnoseInstallation(repoPath, options) {
         };
     });
     const manager = managerEvidence(chain.at(-1) ?? executable, env);
+    const owner = resolveManagerOwnership({
+        runtimeCommand: options.runtimeCommand,
+        executablePath: chain.at(-1) ?? executable,
+        env,
+    });
+    const stateHome = env.XDG_STATE_HOME;
+    const managerState = readManagerUpdateState(stateHome);
     const packageVersion = installedPackageVersion(chain.at(-1) ?? executable);
+    const backupInventory = listBackups([repo], { depth: 0 });
+    const backupPrunePreview = pruneBackups([repo], { depth: 0 });
     return {
         schemaVersion: 1,
         status: options.graph.status === "healthy" &&
@@ -360,19 +455,54 @@ export async function diagnoseInstallation(repoPath, options) {
             configuredCommands: repositoryCommands,
             clients,
         },
+        configurationRemediation,
         mcp,
         lifecycle,
         graph: options.graph,
-        update: trustedUpdateStatus({
-            currentVersion: options.currentVersion,
-            stateHome: options.cacheHome,
-            installMethod: manager.name,
-            env,
-        }),
+        backups: {
+            inventory: backupInventory,
+            reclaimableBytes: backupPrunePreview.reclaimableBytes,
+            skippedRepositories: backupPrunePreview.skipped,
+            retention: retentionDoctor(),
+            remediation: "Preview with `knodin backups prune`; deletion requires `--apply` or installed retention.",
+        },
+        update: {
+            ...trustedUpdateStatus({
+                currentVersion: options.currentVersion,
+                stateHome: options.cacheHome,
+                installMethod: manager.name,
+                env,
+            }),
+            owner: {
+                method: owner.method,
+                status: owner.status,
+                executable: owner.executable,
+                evidence: owner.evidence,
+            },
+            pin: managerState.pin ?? null,
+            auto: {
+                enabled: managerState.autoEnabled,
+                platformEligible: managerState.platformAutoEligible,
+            },
+            attention: updateAttention(managerState),
+            journal: readUpdateJournal(stateHome),
+        },
         remediation: {
             manager: managerRemediation(manager.name, options.currentVersion),
-            duplicates: candidates.length > 1
-                ? "Remove only the unintended manager-owned installation, then rerun `knodin doctor`."
+            duplicates: owner.duplicates.length > 0 || owner.staleLinks.length > 0 || owner.pathShadowing
+                ? {
+                    instructions: [
+                        ...owner.duplicates.map((entry) => `Use the package manager that owns ${entry.path} to remove only that competing installation.`),
+                        ...owner.staleLinks.map((entry) => `Inspect and manually remove the stale executable link ${entry}.`),
+                        ...(owner.pathShadowing
+                            ? [
+                                "Correct PATH ordering so the intended manager-owned executable resolves first.",
+                            ]
+                            : []),
+                        "Rerun `knodin doctor`; Knodin will not remove another installation automatically.",
+                    ],
+                    ownershipEvidence: owner.evidence,
+                }
                 : null,
             graph: options.graph.status === "healthy"
                 ? null

package/dist/src/engine/embeddings.js

@@ -18,6 +18,7 @@ let embedderReady = false;
 export const EMBEDDING_DIMENSIONS = 384;
 export const EMBEDDING_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
 export const EMBEDDING_MODEL_REVISION = "751bff37182d3f1213fa05d7196b954e230abad9";
+export const EMBEDDING_MODEL_DTYPE = "q8";
 const DEFAULT_MODEL_REMOTE_HOST = "https://huggingface.co/";
 /**
  * One machine-level model cache shared by every repository and every installed
@@ -137,6 +138,9 @@ export function getEmbedder(onProgress) {
                 notify({ status: "loading", name: EMBEDDING_MODEL_ID });
                 const pipe = await pipeline("feature-extraction", EMBEDDING_MODEL_ID, {
                     revision: EMBEDDING_MODEL_REVISION,
+                    // q8 preserves the model's 384-dimensional normalized-vector contract
+                    // while avoiding the 86 MiB FP32 graph load on every cold CLI process.
+                    dtype: EMBEDDING_MODEL_DTYPE,
                     progress_callback: notify,
                 });
                 realEmbedderLoadCount++;
@@ -162,7 +166,10 @@ export async function generateEmbeddings(texts, onModelProgress) {
     if (texts.length === 0)
         return [];
     const extractor = await getEmbedder(onModelProgress);
-    const result = await extractor([...texts], { pooling: "mean", normalize: true });
+    const result = await extractor([...texts], {
+        pooling: "mean",
+        normalize: true,
+    });
     const data = result.data instanceof Float32Array ? result.data : Float32Array.from(result.data);
     const dims = result.dims;
     if (dims?.length !== 2 || dims[0] !== texts.length || dims[1] !== EMBEDDING_DIMENSIONS) {