kritya 0.8.26-beta → 0.8.28-beta

package/README.md

@@ -55,7 +55,7 @@ review → fix` for building something new end-to-end
 
 ## Setup
 
-Requires Node.js >=22.
+Requires Node.js >=22.19.0.
 
 1. Get an API key from your chosen provider (click any
    model → "Get API Key").
@@ -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                                                                                                                        |
@@ -170,7 +189,8 @@ In-session commands (type `/` to see them with autocomplete; letters filter the
 Custom `/commands` you define (see [docs/CONFIGURATION.md](docs/CONFIGURATION.md#custom-slash-commands)) also appear here.
 
 `Esc` cancels a running request. `↑/↓` recalls input history. `Ctrl+O` toggles
-full tool output. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
+full tool output. `Ctrl+E` opens the file the agent touched most recently in
+`$EDITOR`. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
 
 ### More features
 
@@ -432,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/agent/skills.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { writeStderr } from "../stderr.js";
 import { pluginsDir, pluginSkillsRoots, scanPlugins, userPluginsDir } from "../plugins/discover.js";
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 const KEY_VALUE_RE = /^([A-Za-z0-9_-]+):\s*(.*)$/;
@@ -73,7 +74,7 @@ function unquote(value) {
     return value;
 }
 let warnSink = (message) => {
-    process.stderr.write(`kritya: ${message}\n`);
+    writeStderr(`kritya: ${message}\n`);
 };
 function warn(message) {
     warnSink(message);

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/config/config.js

@@ -161,6 +161,8 @@ export function resolveProvider(config, override) {
         apiKey = merged.apiKey;
     if (!apiKey && name === "nvidia")
         apiKey = process.env.NVIDIA_API_KEY || config.apiKey;
+    if (apiKey)
+        apiKey = apiKey.trim();
     return {
         name,
         baseUrl,

package/dist/config/debug.js

@@ -1,3 +1,4 @@
+import { writeStderr } from "../stderr.js";
 /**
  * Most best-effort persistence (session/audit/telemetry writes, config and
  * trust-file reads, hook loading, …) deliberately swallows its own errors —
@@ -10,12 +11,7 @@ export function debugLog(context, err) {
     if ((process.env.KRITYA_DEBUG ?? "").toLowerCase() !== "1" && process.env.KRITYA_DEBUG !== "true")
         return;
     const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
-    try {
-        process.stderr.write(`[kritya debug] ${context}: ${message}\n`);
-    }
-    catch {
-        // stderr itself failing isn't something debug logging can do anything about
-    }
+    writeStderr(`[kritya debug] ${context}: ${message}\n`);
 }
 /**
  * For best-effort persistence that a user actually needs to know failed
@@ -39,12 +35,7 @@ export function warnUser(context, err) {
     }
     warnedContexts.add(context);
     const message = err instanceof Error ? err.message : String(err);
-    try {
-        process.stderr.write(`[kritya] warning: ${context} failed: ${message}\n`);
-    }
-    catch {
-        // stderr itself failing isn't something this can do anything about
-    }
+    writeStderr(`[kritya] warning: ${context} failed: ${message}\n`);
     debugLog(context, err);
 }
 /** Contexts currently warning via warnPersistenceFailure, in the order first seen. */

package/dist/config/models.js

@@ -45,6 +45,24 @@ export const CURATED_MODELS = [
         note: "strong agentic tool use",
         contextWindow: 256_000,
     },
+    {
+        id: "z-ai/glm-5.3",
+        label: "GLM 5.3",
+        note: "strong agentic tool use",
+        contextWindow: 1_048_576,
+    },
+    {
+        id: "z-ai/glm-5.3-flash",
+        label: "GLM 5.3 Flash",
+        note: "fast + cheap",
+        contextWindow: 1_048_576,
+    },
+    {
+        id: "deepseek-ai/deepseek-v4.1-flash",
+        label: "DeepSeek V4.1 Flash",
+        note: "fast + cheap",
+        contextWindow: 1_048_576,
+    },
 ];
 export const DEFAULT_MODEL = CURATED_MODELS[0].id;
 /**

package/dist/index.js

@@ -16,7 +16,7 @@ import { AuditLog } from "./audit/audit.js";
 import { runAuditCli } from "./audit/cli.js";
 import { runSkillsCli } from "./agent/skillsCli.js";
 import { createTracer, cleanupOldTelemetry } from "./telemetry/tracer.js";
-import { createMeter } from "./telemetry/metrics.js";
+import { createMeter, RENDER_BOUNDS_MS } from "./telemetry/metrics.js";
 import { retentionDaysFor } from "./config/retention.js";
 import { backgroundManager } from "./shell/background.js";
 import { defaultSandboxMode, sandboxAvailable, sandboxUnavailableReason } from "./shell/sandbox.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()) {
@@ -415,6 +445,17 @@ async function main() {
                     sessionMeter.flushAndWait(),
                     new Promise((resolve) => setTimeout(resolve, 2000).unref()),
                 ]);
+                // Hand the terminal back before leaving. Ink hides the cursor for the
+                // whole time it is rendering and only shows it again from its own
+                // teardown — which the process.exit() below skips, leaving the shell's
+                // prompt invisible until the user runs `reset`. unmount() is that
+                // teardown; it also finishes drawing the frame we are standing on.
+                try {
+                    ui.instance?.unmount();
+                }
+                catch {
+                    // Whatever brought us here may have been the UI itself. Exit anyway.
+                }
                 cleanup();
                 process.exit(code);
             })();
@@ -709,12 +750,24 @@ async function main() {
     // compaction — subagents (read-only or write) never do, even though they
     // run the same Agent class and can also trigger auto-compaction.
     agent.autoMemory = true;
+    // How long Ink takes to turn the React tree into a frame, per frame. This is
+    // the part of drawing a screen that grows with the size of the transcript, so
+    // it is the number that says whether the UI is getting sluggish — the
+    // terminal write it excludes is bounded by the terminal, not by us.
+    // `renderTime` excludes Ink's own throttling, so it is the raw cost of the
+    // frame rather than the interval between frames.
+    const renderHistogram = sessionMeter.histogram("kritya.render.duration_ms", RENDER_BOUNDS_MS);
     ui.instance = render(_jsx(App, { agent: agent, workspace: workspace, modelRef: modelRef, providerRef: providerRef, config: config, resumedCount: initialHistory.length, initialTasks: initialTasks, undoStack: undoStack, uiBridge: uiBridge, resumeSessions: resumeSessions.length ? resumeSessions : undefined, customCommands: loadCustomCommands(workspace, trustWorkspace, plugins), mcpToolCount: mcpTools.length, onSwitchClient: (newClient) => {
             client = newClient;
         }, onRequestPermissionReady: (fn) => {
             permissionRef.current = fn;
         }, onRequestElicitationReady: (fn) => {
             elicitationRef.current = fn;
-        }, privacyMode: privacyMode, firstLaunch: firstLaunch }));
+        }, privacyMode: privacyMode, firstLaunch: firstLaunch }), {
+        onRender: ({ renderTime }) => renderHistogram.record(renderTime),
+        // Repaint only the lines that changed instead of the whole frame:
+        // less flicker and less CPU while streaming. Ink 8 native.
+        incrementalRendering: true,
+    });
     markBannerSeen(workspace);
 }