kritya 0.8.27-beta → 0.8.28-beta

package/README.md

@@ -132,6 +132,25 @@ kritya [directory] [options]
   -v, --version         version
 ```
 
+Subcommands — these run instead of starting a session:
+
+```
+kritya doctor [dir] [--json] [--offline]
+                      check that this installation is set up correctly: the
+                      Node version against the package's engines, the config
+                      file, the active provider and whether its API key
+                      resolves *and* the endpoint accepts it, workspace trust
+                      and git state, MCP servers (including unset ${VAR}s),
+                      sandbox availability, persistence settings, skills and
+                      hooks, and whether a newer release exists
+kritya audit ...      inspect the local audit log (see docs/CONFIGURATION.md)
+kritya skills ...     list and validate discovered skills
+```
+
+`kritya doctor` exits non-zero only when something is actually broken; the
+warnings it prints are "this works, but not the way you may expect" — an
+unavailable sandbox, an untrusted workspace, a lagging `latest` tag.
+
 In-session commands (type `/` to see them with autocomplete; letters filter the list):
 
 | Command                   | What it does                                                                                                                        |
@@ -433,10 +452,20 @@ model config lives in `~/.kritya/config.json`.
 kritya collects **no telemetry** and phones home to nothing of its own by
 default. Network requests go only to the model provider you configure (and to
 Tavily if you use web search). Sessions and config stay on your machine under
-`~/.kritya/`. The one opt-in exception is `KRITYA_OTEL_ENDPOINT` (see
-[Audit log & telemetry](docs/CONFIGURATION.md#audit-log--telemetry)): if you explicitly set it, tracing/metrics spans are sent
-to the OpenTelemetry Collector you point it at — nothing is exported anywhere
-unless you configure that endpoint yourself.
+`~/.kritya/`.
+
+Two things leave the machine beyond the model provider, and both are opt-out:
+
+- **The update check.** `kritya --version` and `kritya doctor` ask the public
+  npm registry for the latest published version, so they can tell you when
+  you're behind. The answer is cached in `~/.kritya/update-check.json` for 24
+  hours, so it is one request per day at most, and it only runs when stdout is
+  a TTY — a script or a pipe never triggers it and never sees the notice.
+  `KRITYA_NO_UPDATE_CHECK=1` turns it off entirely.
+- **Tracing**, if you opt in via `KRITYA_OTEL_ENDPOINT` (see
+  [Audit log & telemetry](docs/CONFIGURATION.md#audit-log--telemetry)): spans
+  are sent to the OpenTelemetry Collector you point it at — nothing is
+  exported anywhere unless you configure that endpoint yourself.
 
 ## Development
 

package/dist/commands/doctor.js

@@ -0,0 +1,380 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { BUILTIN_PROVIDERS, CONFIG_DIR, CONFIG_FILE, legacyGlobalModel, loadConfig, privacyModeFor, resolveProvider, } from "../config/config.js";
+import { DEFAULT_MODEL, contextWindowFor } from "../config/models.js";
+import { retentionDaysFor } from "../config/retention.js";
+import { assertJsonWithinLimits } from "../config/jsonSafety.js";
+import { isGitRepo } from "../agent/worktree.js";
+import { loadHooks } from "../hooks/hooks.js";
+import { loadProjectMcpServers, missingVars } from "../mcp/servers.js";
+import { scanSkillsDetailed, skillsDir, userSkillsDir } from "../agent/skills.js";
+import { defaultSandboxMode, sandboxAvailable, sandboxUnavailableReason, } from "../shell/sandbox.js";
+import { SWITCHYARD_ROUTE_ID, resolveEffectiveModel } from "../provider/switchyardSidecar.js";
+import { gatedContentHash, isTrusted } from "../trust/trust.js";
+import { checkForUpdate, updateCheckDisabled } from "../update/check.js";
+import { VERSION } from "../version.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json");
+export const DOCTOR_USAGE = `kritya doctor — check that this installation is set up correctly
+
+Usage:
+  kritya doctor [dir]            diagnose the setup for [dir] (default: current directory)
+  kritya doctor [dir] --json     machine-readable output
+  kritya doctor [dir] --offline  skip the network probes (provider, update check)
+
+Exits non-zero if any check failed. Warnings alone do not fail it — most are
+"this works, but not the way you may expect" (an unavailable sandbox, an
+untrusted workspace).
+
+Checks: Node version against the package's engines, config file validity, the
+active provider and whether its key resolves and the endpoint answers, workspace
+trust and git state, MCP servers, sandbox availability, persistence/privacy
+settings, discovered skills and hooks, and whether a newer release exists.`;
+const MARKS = { ok: "✓", warn: "!", fail: "✗" };
+function ok(label) {
+    return { level: "ok", label };
+}
+function warn(label) {
+    return { level: "warn", label };
+}
+function fail(label) {
+    return { level: "fail", label };
+}
+/** A path shortened to `~/…` when it lives under the home directory. */
+function tilde(p) {
+    const home = os.homedir();
+    return p === home || p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p;
+}
+function exists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+function runtimeSection() {
+    const checks = [];
+    const required = pkg.engines?.node;
+    const actual = process.versions.node;
+    const [major = 0, minor = 0] = actual.split(".").map(Number);
+    // engines.node is `>=22.19.0`. Parsed by hand because the only operators
+    // this package ever uses are `>=` and a bare version.
+    const minimum = required?.replace(/^>=\s*/, "");
+    const [reqMajor = 0, reqMinor = 0] = (minimum ?? "").split(".").map(Number);
+    const tooOld = Boolean(minimum) && (major < reqMajor || (major === reqMajor && minor < reqMinor));
+    checks.push(tooOld
+        ? fail(`node ${actual} — this package requires >=${minimum}`)
+        : ok(`node ${actual}${minimum ? ` (requires >=${minimum})` : ""}`));
+    checks.push(ok(`${process.platform} ${process.arch}`));
+    checks.push(ok(`kritya ${VERSION}`));
+    return { title: "Runtime", checks };
+}
+async function updateSection(options) {
+    if (options.offline) {
+        return { title: "Releases", checks: [warn("update check skipped (--offline)")] };
+    }
+    if (updateCheckDisabled()) {
+        return {
+            title: "Releases",
+            checks: [warn(`update check disabled by ${"KRITYA_NO_UPDATE_CHECK"}`)],
+        };
+    }
+    const status = await checkForUpdate({ fetchImpl: options.fetchImpl, force: true });
+    const checks = [];
+    if (status.source === "unavailable") {
+        checks.push(warn(`could not reach the npm registry — ${status.reason}`));
+        return { title: "Releases", checks };
+    }
+    checks.push(ok(`installed ${status.current}`));
+    if (status.outdated) {
+        checks.push(warn(`newer version available: ${status.latest} — npm install -g kritya@${status.latest}`));
+    }
+    else {
+        checks.push(ok(`newest published: ${status.latest}`));
+    }
+    return { title: "Releases", checks };
+}
+function configSection(options) {
+    const configDir = options.configDir ?? CONFIG_DIR;
+    const configFile = options.configDir ? path.join(options.configDir, "config.json") : CONFIG_FILE;
+    const checks = [];
+    if (!exists(configFile)) {
+        checks.push(warn(`${tilde(configFile)} not found — built-in defaults are in use`));
+    }
+    else {
+        try {
+            const raw = fs.readFileSync(configFile, "utf8");
+            // The same two guards loadConfig applies. Reported separately because
+            // loadConfig swallows both and returns {} — which otherwise looks
+            // identical to "no config at all", the classic "my config isn't taking
+            // effect" report.
+            assertJsonWithinLimits(raw, "config.json");
+            JSON.parse(raw);
+            checks.push(ok(`${tilde(configFile)} parsed`));
+        }
+        catch (err) {
+            checks.push(fail(`${tilde(configFile)} is unusable: ${err instanceof Error ? err.message : String(err)}`));
+        }
+    }
+    checks.push(exists(configDir)
+        ? ok(`${tilde(configDir)} exists`)
+        : warn(`${tilde(configDir)} not created yet`));
+    return { title: "Configuration", checks };
+}
+function providerSection(config, provider) {
+    const checks = [];
+    checks.push(ok(`active provider: ${provider.name}`));
+    checks.push(ok(`base URL: ${provider.baseUrl}`));
+    if (provider.apiKey) {
+        const source = provider.apiKeyEnv
+            ? `${provider.apiKeyEnv} is set`
+            : "a literal key is configured";
+        checks.push(ok(`API key resolved (${source})`));
+    }
+    else if (provider.apiKeyEnv) {
+        checks.push(fail(`no API key — ${provider.apiKeyEnv} is unset and no literal key is configured. ` +
+            `Set it in the environment, in a .env file, or under providers.${provider.name}.apiKey ` +
+            `in ${tilde(CONFIG_FILE)}`));
+    }
+    else {
+        checks.push(fail(`no API key resolved for provider "${provider.name}"`));
+    }
+    const model = resolveEffectiveModel(provider.name, [config.providers?.[provider.name]?.model, legacyGlobalModel(config, provider.name)], provider.name === "switchyard" ? SWITCHYARD_ROUTE_ID : DEFAULT_MODEL);
+    checks.push(ok(`model: ${model} (context ${contextWindowFor(model, config).toLocaleString("en-US")})`));
+    // A pinned provider name with no matching entry is a silent misconfiguration:
+    // resolveProvider falls back to NVIDIA's URL, so requests go somewhere the
+    // user never intended. Built-ins count as known even with no config entry.
+    const known = Boolean(BUILTIN_PROVIDERS[provider.name] ?? config.providers?.[provider.name]);
+    if (!known) {
+        checks.push(warn(`provider "${provider.name}" is not a built-in and has no config.providers entry — ` +
+            `falling back to the default base URL`));
+    }
+    return { title: "Provider", checks };
+}
+/**
+ * Ask the provider's `/models` endpoint whether the key works. A 401/403 here
+ * is the single most useful thing doctor can report — it is the difference
+ * between "your setup is wrong" and "the model is having a bad day".
+ *
+ * Exported so each response class can be tested without a real provider.
+ */
+export async function probeProvider(provider, fetchImpl, timeoutMs = 5_000) {
+    const url = `${provider.baseUrl.replace(/\/+$/, "")}/models`;
+    try {
+        const response = await (fetchImpl ?? fetch)(url, {
+            headers: provider.apiKey ? { authorization: `Bearer ${provider.apiKey}` } : {},
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (response.ok)
+            return ok(`endpoint reachable — GET ${url} returned ${response.status}`);
+        if (response.status === 401 || response.status === 403) {
+            return fail(`the endpoint rejected the API key — GET ${url} returned ${response.status}. ` +
+                `Check that the key is valid, not expired, and belongs to this provider.`);
+        }
+        if (response.status === 404) {
+            return warn(`endpoint reachable, but GET ${url} returned 404 — not every provider ` +
+                `implements /models, so this is not necessarily a problem`);
+        }
+        return warn(`GET ${url} returned ${response.status}`);
+    }
+    catch (err) {
+        return fail(`could not reach ${url} — ${err instanceof Error ? err.message : String(err)}. ` +
+            `Check your network, proxy, and the provider's baseUrl.`);
+    }
+}
+function workspaceSection(workspace, config) {
+    const checks = [];
+    const krityaDir = path.join(workspace, ".kritya");
+    checks.push(ok(tilde(workspace)));
+    checks.push(isGitRepo(workspace)
+        ? ok("git repository")
+        : warn("not a git repository — /commit and isolated write subagents are unavailable"));
+    // Trust gates the workspace's own settings.json allow rules, hooks, .env and
+    // custom commands. Worth stating explicitly: an untrusted workspace looks
+    // like "my hooks just don't run".
+    const hash = gatedContentHash(workspace);
+    if (!hash) {
+        checks.push(ok("no trust-gated content present"));
+    }
+    else if (isTrusted(workspace, hash)) {
+        checks.push(ok("workspace trust-gated content is trusted"));
+    }
+    else {
+        checks.push(warn("workspace is NOT trusted — .kritya/settings.json allow rules, hooks, .env and " +
+            ".kritya/commands/*.md will be ignored until you accept the prompt"));
+    }
+    for (const [rel, note] of [
+        ["settings.json", "permission rules"],
+        [".mcp.json", "project MCP servers"],
+        [".env", "workspace environment"],
+    ]) {
+        const file = rel === ".mcp.json" ? path.join(workspace, rel) : path.join(krityaDir, rel);
+        if (exists(file))
+            checks.push(ok(`${rel} present (${note})`));
+    }
+    const commandsDir = path.join(krityaDir, "commands");
+    if (exists(commandsDir)) {
+        const count = fs.readdirSync(commandsDir).filter((f) => f.endsWith(".md")).length;
+        checks.push(ok(`${count} custom command(s) in .kritya/commands`));
+    }
+    // Surfaced here rather than only on use: a configured MCP server whose env
+    // var is missing fails at load with a warning that is easy to miss.
+    const servers = {
+        ...loadProjectMcpServers(workspace),
+        ...config.mcpServers,
+    };
+    const names = Object.keys(servers);
+    if (names.length === 0) {
+        checks.push(ok("no MCP servers configured"));
+    }
+    else {
+        checks.push(ok(`${names.length} MCP server(s) configured: ${names.join(", ")}`));
+        for (const name of names) {
+            const missing = missingVars(servers[name]).filter((v) => process.env[v] === undefined);
+            if (missing.length > 0) {
+                checks.push(warn(`MCP server "${name}" references unset variable(s): ${missing.join(", ")}`));
+            }
+        }
+    }
+    return { title: "Workspace", checks };
+}
+function safetySection(config) {
+    const checks = [];
+    const mode = config.sandboxExec ?? defaultSandboxMode();
+    const available = sandboxAvailable();
+    if (mode === "off") {
+        checks.push(warn('sandboxExec is "off" — shell commands run unconfined'));
+    }
+    else if (available) {
+        checks.push(ok(`sandboxExec "${mode}" and a sandbox backend is available`));
+    }
+    else if (mode === "strict") {
+        // "strict" fails closed — the command is refused rather than run
+        // unprotected, so this is not a "falls back with a warning" situation.
+        checks.push(warn(`sandboxExec is "strict" but ${sandboxUnavailableReason()} — commands that would be ` +
+            `sandboxed are refused outright rather than run unprotected`));
+    }
+    else {
+        checks.push(warn(`sandboxExec is "${mode}" but ${sandboxUnavailableReason()} — sandboxed commands ` +
+            `fall back to unsandboxed execution with a warning`));
+    }
+    const privacy = privacyModeFor(config);
+    checks.push(privacy
+        ? warn("privacy mode is ON — transcripts, audit logs and telemetry are not written")
+        : ok("privacy mode is off"));
+    const audit = config.audit ?? "on";
+    const otel = config.otel ?? "off";
+    const retention = retentionDaysFor(config);
+    checks.push(ok(`audit ${audit}, telemetry ${otel}`));
+    checks.push(retention > 0
+        ? ok(`retention ${retention} day(s)`)
+        : warn(`retention disabled (${retention}) — transcripts and logs are kept forever`));
+    return { title: "Safety & persistence", checks };
+}
+function extensionsSection(workspace, config) {
+    const checks = [];
+    const hash = gatedContentHash(workspace);
+    const trusted = !hash || isTrusted(workspace, hash);
+    const { loaded, skipped } = scanSkillsDetailed([skillsDir(workspace), userSkillsDir()]);
+    checks.push(skipped.length === 0
+        ? ok(`${loaded.length} skill(s) discovered`)
+        : warn(`${loaded.length} skill(s) discovered, ${skipped.length} skipped — ` +
+            skipped.map((s) => `${s.name} (${s.reason})`).join("; ")));
+    const hooks = loadHooks(workspace, trusted);
+    // HooksConfig is keyed by event, each holding an array — sum across events
+    // rather than looking for a `hooks` key that does not exist.
+    const hookCount = Object.values(hooks).reduce((total, list) => total + (Array.isArray(list) ? list.length : 0), 0);
+    checks.push(hookCount > 0 ? ok(`${hookCount} hook(s) configured`) : ok("no hooks configured"));
+    checks.push(ok(`KRITYA.md ${exists(path.join(workspace, "KRITYA.md")) ? "present" : "not present"}`));
+    checks.push(ok(`config.mcpServers: ${Object.keys(config.mcpServers ?? {}).length}`));
+    return { title: "Skills & hooks", checks };
+}
+/** Every diagnostic, in display order. Exported so it can be tested directly. */
+export async function collectDiagnostics(options = {}) {
+    const workspace = path.resolve(options.workspace ?? ".");
+    const config = options.config ?? loadConfig();
+    const configSec = configSection(options);
+    const sections = [runtimeSection(), await updateSection(options), configSec];
+    if (!exists(workspace) || !fs.statSync(workspace).isDirectory()) {
+        sections.push({
+            title: "Workspace",
+            checks: [fail(`${workspace} is not a directory`)],
+        });
+        return sections;
+    }
+    const resolved = resolveProvider(config);
+    const provider = providerSection(config, resolved);
+    if (options.offline) {
+        provider.checks.push(warn("provider endpoint not probed (--offline)"));
+    }
+    else if (resolved.name === "switchyard") {
+        // Its baseUrl is a placeholder; the real client is a local sidecar that
+        // only exists for the lifetime of a session, so there is nothing to probe.
+        provider.checks.push(warn("endpoint not probed — switchyard runs a local sidecar, started on launch"));
+    }
+    else if (resolved.apiKey) {
+        provider.checks.push(await probeProvider(resolved, options.fetchImpl));
+    }
+    sections.push(provider);
+    sections.push(workspaceSection(workspace, config));
+    sections.push(safetySection(config));
+    sections.push(extensionsSection(workspace, config));
+    return sections;
+}
+export function summarize(sections, workspace) {
+    const checks = sections.flatMap((s) => s.checks);
+    return {
+        version: VERSION,
+        workspace,
+        sections,
+        failures: checks.filter((c) => c.level === "fail").length,
+        warnings: checks.filter((c) => c.level === "warn").length,
+    };
+}
+/** Exported for tests: the human-readable rendering, given the collected checks. */
+export function renderReport(report) {
+    const lines = [
+        `kritya doctor — ${report.version}`,
+        `workspace: ${tilde(report.workspace)}`,
+        "",
+    ];
+    for (const section of report.sections) {
+        lines.push(section.title);
+        for (const check of section.checks)
+            lines.push(`  ${MARKS[check.level]} ${check.label}`);
+        lines.push("");
+    }
+    if (report.failures > 0) {
+        lines.push(`${report.failures} problem(s) found${report.warnings ? `, ${report.warnings} warning(s)` : ""}.`);
+    }
+    else if (report.warnings > 0) {
+        lines.push(`No problems found (${report.warnings} warning(s) — see ! above).`);
+    }
+    else {
+        lines.push("No problems found.");
+    }
+    return lines.join("\n");
+}
+/** Handles `kritya doctor ...`. Resolves to the process exit code. */
+export async function runDoctorCli(argv, options = {}) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(DOCTOR_USAGE);
+        return 0;
+    }
+    const json = argv.includes("--json");
+    const offline = argv.includes("--offline");
+    const dirArg = argv.find((a) => !a.startsWith("-"));
+    const workspace = path.resolve(options.workspace ?? dirArg ?? ".");
+    const sections = await collectDiagnostics({ ...options, workspace, offline });
+    const report = summarize(sections, workspace);
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(renderReport(report));
+    }
+    return report.failures > 0 ? 1 : 0;
+}

package/dist/index.js

@@ -42,6 +42,7 @@ import { runHeadless } from "./headless.js";
 import { installCrashHandlers } from "./crash.js";
 import { createWorktree, commitWorktree, worktreeDiffStat, removeWorktree, isGitRepo, } from "./agent/worktree.js";
 import { VERSION } from "./version.js";
+import { updateNoticeForUser } from "./update/check.js";
 const USAGE = `kritya — a lean, provider-agnostic terminal coding agent
 
 Usage: kritya [directory] [options]
@@ -75,6 +76,11 @@ Inspect the local audit log:
 List and validate skills:
   kritya skills [dir] [--json] [--validate]
 
+Check the installation:
+  kritya doctor [dir] [--json] [--offline]
+  Diagnoses the Node version, config, provider and its API key, workspace
+  trust, MCP servers, sandbox, and whether a newer release exists.
+
 Setup:
   1. Get an API key at https://build.nvidia.com (free credits available)
   2. export NVIDIA_API_KEY=nvapi-...        (Linux/macOS)
@@ -153,14 +159,38 @@ if (process.argv[2] === "audit") {
 if (process.argv[2] === "skills") {
     process.exit(runSkillsCli(process.argv.slice(3)));
 }
+// `kritya doctor` is the third standalone subcommand. It is async (it probes
+// the provider and the registry), so unlike the two above it has to be awaited
+// here — without that, top-level execution would fall through to parseArgs and
+// start a session after the diagnosis had already run. Imported dynamically so
+// `--version`, `--help` and a normal launch don't pay to load its module graph.
+if (process.argv[2] === "doctor") {
+    const { runDoctorCli } = await import("./commands/doctor.js");
+    process.exit(await runDoctorCli(process.argv.slice(3)));
+}
 const args = parseArgs(process.argv.slice(2));
 if (args.help) {
     console.log(USAGE);
     process.exit(0);
 }
 if (args.version) {
+    // The version itself goes to stdout and is printed before anything else, so
+    // `kritya --version` stays exactly one parseable line. The staleness notice
+    // is a courtesy, not part of that contract, so it is TTY-only (a script or a
+    // pipe never pays for it and never sees it), cached for a day, bounded, and
+    // written to stderr.
     console.log(VERSION);
-    process.exit(0);
+    if (process.stdout.isTTY) {
+        void updateNoticeForUser()
+            .then((notice) => {
+            if (notice)
+                console.error(notice);
+        })
+            .finally(() => process.exit(0));
+    }
+    else {
+        process.exit(0);
+    }
 }
 const workspace = path.resolve(args.dir);
 if (!fs.existsSync(workspace) || !fs.statSync(workspace).isDirectory()) {

package/dist/update/check.js

@@ -0,0 +1,189 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_DIR } from "../config/config.js";
+import { debugLog } from "../config/debug.js";
+import { writeFileAtomicSync } from "../atomicWrite.js";
+import { VERSION } from "../version.js";
+/**
+ * "Is a newer kritya out?" — a courtesy notice, so every path here is
+ * best-effort by design: it never throws, never blocks for long, and never
+ * runs when it would be in the way (see `updateCheckDisabled` and the TTY gate
+ * at the call sites). A version check that can break `kritya --version` or
+ * stall startup would be a worse bug than the staleness it reports.
+ */
+export const UPDATE_CHECK_DISABLED_ENV = "KRITYA_NO_UPDATE_CHECK";
+const CACHE_FILE = path.join(CONFIG_DIR, "update-check.json");
+/** How long a cached answer stays good. One registry hit per day, per machine. */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+/** Kept short: this is a nicety, and it sits in front of a user's shell prompt. */
+const REQUEST_TIMEOUT_MS = 2_000;
+const REGISTRY_URL = "https://registry.npmjs.org/kritya";
+/** npm's abbreviated packument — a fraction of the full document's size. */
+const PACKUMENT_ACCEPT = "application/vnd.npm.install-v1+json";
+export function updateCheckDisabled() {
+    const value = process.env[UPDATE_CHECK_DISABLED_ENV];
+    return value !== undefined && /^(1|true|yes|on)$/i.test(value.trim());
+}
+/**
+ * Semver precedence: -1 if a < b, 0 if equal, 1 if a > b.
+ *
+ * Hand-rolled rather than pulled from a dependency because the only shapes
+ * this ever sees are our own release tags (`0.8.27-beta`), and a full semver
+ * implementation would be more code than it saves. Follows §11 where it
+ * matters: a release outranks any prerelease of the same core, and numeric
+ * prerelease identifiers rank below alphanumeric ones.
+ */
+export function compareVersions(a, b) {
+    const parse = (value) => {
+        const [core, ...rest] = value.trim().replace(/^v/, "").split("-");
+        return { nums: core.split(".").map((n) => Number(n) || 0), pre: rest.join("-") };
+    };
+    const left = parse(a);
+    const right = parse(b);
+    for (let i = 0; i < 3; i += 1) {
+        const x = left.nums[i] ?? 0;
+        const y = right.nums[i] ?? 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    if (left.pre === right.pre)
+        return 0;
+    if (!left.pre)
+        return 1;
+    if (!right.pre)
+        return -1;
+    const li = left.pre.split(".");
+    const ri = right.pre.split(".");
+    for (let i = 0; i < Math.max(li.length, ri.length); i += 1) {
+        const x = li[i];
+        const y = ri[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xNum = /^\d+$/.test(x);
+        const yNum = /^\d+$/.test(y);
+        if (xNum && yNum) {
+            const dx = Number(x);
+            const dy = Number(y);
+            if (dx !== dy)
+                return dx < dy ? -1 : 1;
+        }
+        else if (xNum !== yNum) {
+            return xNum ? -1 : 1;
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}
+/**
+ * The newest version across a packument's dist-tags.
+ *
+ * Deliberately the maximum of *all* tags rather than a single channel: this
+ * package currently only publishes prereleases under `beta`, while `latest`
+ * lags behind by design (it is moved by hand — see publish.yml). Reading only
+ * `latest` would mean the notice never fires for the people actually running
+ * betas.
+ */
+export function newestVersion(distTags) {
+    let newest = null;
+    for (const version of Object.values(distTags ?? {})) {
+        if (typeof version !== "string" || !version)
+            continue;
+        if (!newest || compareVersions(version, newest) > 0)
+            newest = version;
+    }
+    return newest;
+}
+export function isOutdated(current, latest) {
+    return latest !== null && compareVersions(latest, current) > 0;
+}
+/** The user-facing notice, or null when there's nothing worth saying. */
+export function updateNotice(current, latest) {
+    if (!isOutdated(current, latest))
+        return null;
+    return (`A newer version of kritya is available: ${current} → ${latest}\n` +
+        `  npm install -g kritya@${latest}`);
+}
+function readCache(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof parsed.checkedAt !== "number" || typeof parsed.latest !== "string")
+            return null;
+        return { checkedAt: parsed.checkedAt, latest: parsed.latest };
+    }
+    catch (err) {
+        // Missing on first run, or corrupt — either way, just check the registry.
+        debugLog(`readUpdateCache(${file})`, err);
+        return null;
+    }
+}
+function writeCache(file, entry) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        writeFileAtomicSync(file, `${JSON.stringify(entry, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch (err) {
+        // Not being able to remember the answer only costs one extra request.
+        debugLog(`writeUpdateCache(${file})`, err);
+    }
+}
+/**
+ * Resolve whether a newer version exists. Never rejects.
+ *
+ * A cached answer younger than the TTL is returned as-is; otherwise the
+ * registry is asked with a hard 2s timeout and the result is cached. Any
+ * failure resolves to `source: "unavailable"` — being offline is not an error
+ * worth showing anyone.
+ */
+export async function checkForUpdate(options = {}) {
+    const current = VERSION;
+    if (updateCheckDisabled()) {
+        return { current, latest: null, outdated: false, source: "disabled" };
+    }
+    const now = options.now ?? Date.now();
+    const cacheFile = options.cacheFile ?? CACHE_FILE;
+    if (!options.force) {
+        const cached = readCache(cacheFile);
+        if (cached && now - cached.checkedAt < CACHE_TTL_MS) {
+            return {
+                current,
+                latest: cached.latest,
+                outdated: isOutdated(current, cached.latest),
+                source: "cache",
+            };
+        }
+    }
+    try {
+        const fetchImpl = options.fetchImpl ?? fetch;
+        const response = await fetchImpl(REGISTRY_URL, {
+            headers: { accept: PACKUMENT_ACCEPT },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            throw new Error(`registry returned HTTP ${response.status}`);
+        const doc = (await response.json());
+        const latest = newestVersion(doc["dist-tags"]);
+        if (!latest)
+            throw new Error("registry response contained no dist-tags");
+        writeCache(cacheFile, { checkedAt: now, latest });
+        return { current, latest, outdated: isOutdated(current, latest), source: "registry" };
+    }
+    catch (err) {
+        debugLog(`checkForUpdate(${REGISTRY_URL})`, err);
+        return {
+            current,
+            latest: null,
+            outdated: false,
+            source: "unavailable",
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** The notice to print for a user, or null. Never throws. */
+export async function updateNoticeForUser(options = {}) {
+    const status = await checkForUpdate(options);
+    return updateNotice(status.current, status.latest);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kritya",
-  "version": "0.8.27-beta",
+  "version": "0.8.28-beta",
   "description": "Kritya — a lean, provider-agnostic terminal coding agent (NVIDIA, OpenAI, OpenRouter, Groq, Ollama, and more)",
   "type": "module",
   "publishConfig": {
@@ -37,9 +37,12 @@
     "format:check": "prettier --check .",
     "check:audit": "node scripts/check-audit.mjs",
     "check:install-scripts": "node scripts/check-install-scripts.mjs",
+    "check:package": "node scripts/check-package.mjs",
+    "check:release": "node scripts/check-release.mjs",
+    "check:smoke": "node scripts/smoke-install.mjs",
     "check:typescript-setup": "node scripts/check-typescript-setup.mjs",
     "link": "npm run build && npm link",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run build && npm run check:package && npm run check:smoke",
     "prepare": "husky",
     "electron:dev": "npm run build && electron .",
     "electron:build": "npm run build && electron-builder"