kritya 0.8.23-beta → 0.8.25-beta

package/README.md

@@ -50,7 +50,8 @@ review → fix` for building something new end-to-end
   state
 - **Office docs & notebooks** — read/write Word, Excel, PowerPoint, PDF,
   Jupyter
-- **Headless/CI mode** — scriptable, no-TTY runs for automation
+  - **Headless/CI mode** — scriptable, no-TTY runs for automation
+  - **Privacy mode** — `--privacy`, `KRITYA_PRIVACY=1`, or `"privacyMode": true` disables transcript, audit, and telemetry persistence
 
 ## Setup
 
@@ -64,6 +65,9 @@ Requires Node.js >=22.
    - Linux/macOS: `export NVIDIA_API_KEY=nvapi-...`
    - Windows: `setx NVIDIA_API_KEY nvapi-...` (then open a new terminal)
 
+   Skip this and kritya will prompt for the key on first launch (interactive
+   mode only) and save it to `~/.kritya/.env` for you.
+
    Optional: add `TAVILY_API_KEY` the same way to enable the agent's
    web-search tool (`/web-search`) — get one at [tavily.com](https://tavily.com).
 
@@ -158,6 +162,7 @@ In-session commands (type `/` to see them with autocomplete; letters filter the
 | `/cost`                   | token usage and estimated $ (see Pricing below)                                                                                     |
 | `/audit`                  | show this session's permission decisions and verify the audit log's chain ([more](docs/CONFIGURATION.md#audit-log--telemetry))      |
 | `/budget`                 | show session token budget; `/budget reset` or `/budget <number>`                                                                    |
+| `/status`                 | show context/budget/token/task detail left off the always-visible status line                                                       |
 | `/kill`                   | emergency stop: `/kill [reason]` halts everything; `/kill off` releases                                                             |
 | `/help`                   | command list                                                                                                                        |
 | `/exit`                   | quit                                                                                                                                |
@@ -281,8 +286,8 @@ full tool output. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
   message is queued and absorbed before its next step (no need to interrupt).
 - **Auto-compaction → self-improving project memory** — when the conversation
   nears the model's context window (80% of `contextWindow`, default 120k
-  tokens), older turns are summarized automatically; the statusline shows
-  current usage as `ctx N%`. Compaction (auto or manual `/compact`) also
+  tokens), older turns are summarized automatically; `/status` shows current
+  usage as `context used: N%`. Compaction (auto or manual `/compact`) also
   distills durable, objective facts out of what's being summarized away —
   build/test commands, package manager, conventions actually observed — and
   merges any new ones into a `## Learned by kritya` section in `KRITYA.md`,
@@ -293,7 +298,8 @@ full tool output. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
 - **Token budget** — a session-wide cap on combined prompt + completion
   tokens across every turn and model (default 1,000,000; set `tokenBudget` in
   config, or `/budget <number>` mid-session). The statusline shows `budget N%`
-  once usage starts, turning yellow past 80% with a one-time warning, then
+  once usage crosses 80% (yellow, with a one-time warning) or the budget is
+  hit (red); `/status` shows it from the start. It then
   stops further turns entirely at 100% until you run `/budget reset` (clears
   the count) or `/budget <number>` (raises the cap). `/cost` also reports it.
 - **Background processes** — the agent can start dev servers/watchers with
@@ -310,7 +316,7 @@ full tool output. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
   every request.
 - **Sub-task checklist → resumable plans** — for multi-step requests the agent
   plans first and shows a live ☐/◐/☑ checklist as it works, with a compact
-  `tasks N/M` summary in the statusline. The checklist is saved alongside the
+  `tasks N/M` summary available via `/status`. The checklist is saved alongside the
   session, so `kritya -c` (and picking a session via `-r`) restores not just
   the conversation but exactly which steps were done, in progress, or still
   pending.
@@ -345,7 +351,7 @@ full tool output. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
 - **Prompt-caching awareness** — the system prompt is ordered stable-first
   (identity and rules → project memory → volatile git status/listing last) so
   providers can reuse their cached prompt prefix across turns instead of
-  re-reading everything. `/cost` and the statusline show how many prompt
+  re-reading everything. `/cost` and `/status` show how many prompt
   tokens were served from the provider's cache; add an optional
   `"cachedInput"` rate to your `pricing` config to see the dollar savings.
 - **LSP integration** — the agent gets go-to-definition, find-references,

package/dist/agent/loop.js

@@ -78,6 +78,14 @@ export class Agent {
     audit;
     /** OpenTelemetry-shaped tracer for the tool loop. No-op unless enabled. */
     tracer = NOOP_TRACER;
+    /**
+     * Fired around compact() so the UI can show a live "compacting…" indicator
+     * for the summarization call, which otherwise runs silently until it
+     * either finishes or fails (see onToolEnd's "compact" record for the
+     * after-the-fact summary).
+     */
+    onCompactStart;
+    onCompactEnd;
     /** OTLP metrics recorder for tool/turn durations. No-op unless enabled. */
     meter = NOOP_METER;
     /**
@@ -266,6 +274,7 @@ export class Agent {
         this.kill.assertLive();
         const compactSpan = this.tracer.startSpan("agent.compact", { parent: this.currentTurnSpan });
         const tokensBefore = this.lastPromptTokens;
+        this.onCompactStart?.();
         try {
             const note = await this.doCompact(signal, compactSpan);
             compactSpan.setStatus("OK");
@@ -279,6 +288,7 @@ export class Agent {
             compactSpan.setAttribute("kritya.prompt_tokens_before", tokensBefore);
             compactSpan.setAttribute("kritya.prompt_tokens_after", this.lastPromptTokens);
             compactSpan.end();
+            this.onCompactEnd?.();
         }
     }
     async doCompact(signal, compactSpan) {
@@ -444,6 +454,7 @@ export class Agent {
                 onTextDelta: handlers.onTextDelta,
                 onReasoningDelta: handlers.onReasoningDelta,
                 onRetry: handlers.onRetry,
+                onFallback: handlers.onFallback,
             }, signal, { tracer: this.tracer, parent: this.currentTurnSpan });
             let result;
             try {

package/dist/agent/toolExecutor.js

@@ -1,5 +1,5 @@
 import { classifyDanger } from "../permissions/danger.js";
-import { acknowledgeUnsandboxedFallback, sandboxFallbackWarning } from "../shell/sandbox.js";
+import { acknowledgeUnsandboxedFallback, sandboxAvailable, sandboxFallbackWarning, } from "../shell/sandbox.js";
 import { isPlanningDocWrite, loadProjectState } from "./workflow.js";
 import { redactSecrets } from "../tools/secretScan.js";
 /** How much tool output to hand the UI (it shows a preview and expands on toggle). */
@@ -251,7 +251,21 @@ export class ToolExecutor {
                     diff = undefined;
                 }
             }
-            const decision = await handlers.requestPermission(tool.name, summary, diff, danger ?? undefined);
+            const permissionDetails = [
+                summary,
+                `workspace: ${host.ctx.workspace}`,
+                typeof args.path === "string" ? `affected path: ${args.path}` : undefined,
+                tool.name === "shell"
+                    ? `command: ${shellCommand}\nsandbox: ${host.ctx.sandboxMode === "off"
+                        ? "off"
+                        : sandboxAvailable()
+                            ? `${host.ctx.sandboxMode ?? "auto"} (available)`
+                            : `${host.ctx.sandboxMode ?? "auto"} (unavailable; unsandboxed)`}`
+                    : undefined,
+            ]
+                .filter(Boolean)
+                .join("\n");
+            const decision = await handlers.requestPermission(tool.name, permissionDetails, diff, danger ?? undefined);
             // A forced (danger) prompt does not grant a lasting allowance.
             if (danger === null)
                 host.permissions.record(tool.name, decision, args);

package/dist/audit/audit.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { CONFIG_DIR } from "../config/config.js";
 import { hardenWindowsDir } from "../config/winAcl.js";
-import { debugLog, warnUser } from "../config/debug.js";
+import { debugLog, warnPersistenceFailure } from "../config/debug.js";
 const GENESIS = "0".repeat(64);
 /**
  * Where all audit logs live, across every workspace (not scoped per-project).
@@ -108,7 +108,7 @@ export class AuditLog {
         }
         catch (err) {
             // best-effort
-            warnUser(`AuditLog.write(${this.file})`, err);
+            warnPersistenceFailure(`AuditLog.write(${this.file})`, err);
         }
     }
     ensureDir() {

package/dist/commands/registry.js

@@ -9,73 +9,138 @@ import { scanPluginMcpServers } from "../plugins/mcp.js";
 import { listProviders } from "../config/config.js";
 import { expandCommand } from "./custom.js";
 import { artifactPath, clearProjectState, loadProjectState, parseIdea, parsePhase, phaseBlocker, phasePrompt, renameProject, staleArtifacts, PHASE_COMMAND, PHASE_ORDER, PHASE_SUMMARY, saveProjectState, slugify, } from "../agent/workflow.js";
+const WORKFLOW = "Workflow";
+const SESSION = "Session";
+const SAFETY = "Safety & limits";
+const INFO = "Info";
 export const BUILTIN_COMMANDS = [
-    { name: "/help", description: "show available commands" },
-    { name: "/model", description: "pick a model, or /model <id> for any provider model ID" },
-    {
-        name: "/provider",
-        description: "list providers, or /provider <name> to switch mid-session (keeps history); add --default to persist",
-    },
     {
         name: "/flow-brainstorm",
         description: "start a new-project workflow: /flow-brainstorm <idea> (brainstorm→spec→plan→build→review→fix)",
+        category: WORKFLOW,
     },
     {
         name: "/flow-spec",
         description: "project workflow: write the spec from the approved brainstorm",
+        category: WORKFLOW,
+    },
+    {
+        name: "/flow-plan",
+        description: "project workflow: plan from the spec (read-only)",
+        category: WORKFLOW,
+    },
+    {
+        name: "/flow-build",
+        description: "project workflow: implement the plan, with tests",
+        category: WORKFLOW,
+    },
+    {
+        name: "/flow-review",
+        description: "project workflow: spec-compliance and security review",
+        category: WORKFLOW,
+    },
+    {
+        name: "/flow-fix",
+        description: "project workflow: fix the review's findings, re-verified",
+        category: WORKFLOW,
     },
-    { name: "/plan", description: "toggle plan mode: /plan, /plan on, /plan off" },
-    { name: "/flow-plan", description: "project workflow: plan from the spec (read-only)" },
-    { name: "/flow-build", description: "project workflow: implement the plan, with tests" },
-    { name: "/flow-review", description: "project workflow: spec-compliance and security review" },
-    { name: "/flow-fix", description: "project workflow: fix the review's findings, re-verified" },
     {
         name: "/project",
         description: "workflow status · /project goto <phase> · rename <name> · clear",
+        category: WORKFLOW,
     },
-    { name: "/diff", description: "show the cumulative git diff of this session's changes" },
-    { name: "/redo", description: "reapply the change most recently undone" },
-    { name: "/init", description: "scan the repo and generate a KRITYA.md project-memory file" },
-    { name: "/web-search", description: "search the web: /web-search <query>" },
     {
-        name: "/mcp",
-        description: "MCP servers: status, /mcp add|remove <name>, /mcp login|logout <name>",
+        name: "/model",
+        description: "pick a model, or /model <id> for any provider model ID",
+        category: SESSION,
     },
     {
-        name: "/skills",
-        description: "list discovered skills (project + user-global) and why any were skipped",
+        name: "/provider",
+        description: "list providers, or /provider <name> to switch mid-session (keeps history); add --default to persist",
+        category: SESSION,
     },
     {
-        name: "/plugins",
-        description: "list discovered Agent Plugins, what each contributes, and why any were skipped",
+        name: "/diff",
+        description: "show the cumulative git diff of this session's changes",
+        category: SESSION,
+    },
+    {
+        name: "/init",
+        description: "scan the repo and generate a KRITYA.md project-memory file",
+        category: SESSION,
     },
-    { name: "/undo", description: "revert the file changes from the agent's last turn" },
+    { name: "/web-search", description: "search the web: /web-search <query>", category: SESSION },
+    {
+        name: "/commit",
+        description: "have the agent stage and commit the current changes",
+        category: SESSION,
+    },
+    {
+        name: "/compact",
+        description: "summarize older conversation to free context space",
+        category: SESSION,
+    },
+    { name: "/clear", description: "start a fresh conversation", category: SESSION },
+    {
+        name: "/undo",
+        description: "revert the file changes from the agent's last turn",
+        category: SESSION,
+    },
+    { name: "/redo", description: "reapply the change most recently undone", category: SESSION },
     {
         name: "/checkpoint",
         description: "save a named point: /checkpoint <name> (no name lists saved ones)",
+        category: SESSION,
     },
     {
         name: "/rewind",
         description: "rewind the conversation and files to a checkpoint: /rewind <name>",
+        category: SESSION,
+    },
+    {
+        name: "/plan",
+        description: "toggle plan mode (read-only): /plan, /plan on, /plan off",
+        category: SAFETY,
+    },
+    {
+        name: "/kill",
+        description: "emergency stop: /kill [reason] halts everything · /kill off releases (Ctrl+K)",
+        category: SAFETY,
     },
-    { name: "/commit", description: "have the agent stage and commit the current changes" },
-    { name: "/compact", description: "summarize older conversation to free context space" },
-    { name: "/clear", description: "start a fresh conversation" },
-    { name: "/cost", description: "show token usage and estimated cost" },
     {
         name: "/audit",
         description: "show this session's permission decisions and verify the audit log's chain",
+        category: SAFETY,
     },
     {
         name: "/budget",
         description: "show session token budget, /budget reset, or /budget <number> to set it",
+        category: SAFETY,
     },
+    { name: "/cost", description: "show token usage and estimated cost", category: SAFETY },
     {
-        name: "/kill",
-        description: "emergency stop: /kill [reason] halts everything · /kill off releases (Ctrl+K)",
+        name: "/status",
+        description: "show context/budget/token/task detail left off the status line",
+        category: SAFETY,
+    },
+    { name: "/help", description: "show available commands", category: INFO },
+    {
+        name: "/skills",
+        description: "list discovered skills (project + user-global) and why any were skipped",
+        category: INFO,
+    },
+    {
+        name: "/plugins",
+        description: "list discovered Agent Plugins, what each contributes, and why any were skipped",
+        category: INFO,
+    },
+    {
+        name: "/mcp",
+        description: "MCP servers: status, /mcp add|remove <name>, /mcp login|logout <name>",
+        category: INFO,
     },
-    { name: "/exit", description: "leave" },
-    { name: "/quit", description: "leave" },
+    { name: "/exit", description: "leave", category: INFO },
+    { name: "/quit", description: "leave", category: INFO },
 ];
 export const HELP_TEXT = `Commands:
 ${BUILTIN_COMMANDS.map((c) => `  ${c.name.padEnd(14)} ${c.description}`).join("\n")}
@@ -379,6 +444,9 @@ const handlers = {
     "/cost": (ctx) => {
         ctx.addItem({ kind: "info", text: ctx.costReport() });
     },
+    "/status": (ctx) => {
+        ctx.addItem({ kind: "info", text: ctx.statusReport() });
+    },
     "/audit": (ctx) => {
         const audit = ctx.agent.audit;
         if (!audit) {
@@ -674,6 +742,7 @@ const ALLOWED_WHILE_KILLED = new Set([
     "/quit",
     "/audit",
     "/cost",
+    "/status",
     "/diff",
     "/budget",
     "/mcp",

package/dist/config/config.js

@@ -5,6 +5,13 @@ import { hardenWindowsDir } from "./winAcl.js";
 import { debugLog, warnUser } from "./debug.js";
 import { writeFileAtomicSync } from "../atomicWrite.js";
 import { assertJsonWithinLimits } from "./jsonSafety.js";
+/** KRITYA_PRIVACY wins over config.json; truthy values enable privacy mode. */
+export function privacyModeFor(config) {
+    const value = process.env.KRITYA_PRIVACY;
+    if (value !== undefined)
+        return /^(1|true|yes|on)$/i.test(value.trim());
+    return config.privacyMode === true;
+}
 /**
  * Bounds on `mcpServers` entries (from config.json or a workspace's
  * .mcp.json) — without these, an oversized or malicious server list could
@@ -158,6 +165,7 @@ export function resolveProvider(config, override) {
         name,
         baseUrl,
         apiKey,
+        apiKeyEnv: merged.apiKeyEnv,
         temperature: merged.temperature,
         topP: merged.topP,
         maxTokens: merged.maxTokens,
@@ -315,3 +323,17 @@ export function loadDotEnv(paths) {
         }
     }
 }
+/**
+ * Append one KEY=VALUE line to ~/.kritya/.env, creating the directory (and
+ * hardening its permissions) the same way saveConfig does for config.json.
+ * Used by the first-run API key setup prompt so a pasted key survives across
+ * restarts without the user having to edit a dotfile by hand.
+ */
+export function appendGlobalEnvVar(name, value) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    hardenWindowsDir(CONFIG_DIR);
+    const envFile = path.join(CONFIG_DIR, ".env");
+    const sanitized = value.replace(/[\r\n]/g, "");
+    fs.appendFileSync(envFile, `${name}=${sanitized}\n`, { mode: 0o600 });
+    fs.chmodSync(envFile, 0o600);
+}

package/dist/config/debug.js

@@ -47,3 +47,36 @@ export function warnUser(context, err) {
     }
     debugLog(context, err);
 }
+/** Contexts currently warning via warnPersistenceFailure, in the order first seen. */
+const persistenceWarnings = [];
+const persistenceListeners = new Set();
+function notifyPersistenceListeners() {
+    const snapshot = [...persistenceWarnings];
+    for (const listener of persistenceListeners)
+        listener(snapshot);
+}
+/** Current persistence-failure warnings (session/audit/telemetry writes that failed this process). */
+export function activePersistenceWarnings() {
+    return [...persistenceWarnings];
+}
+/** Subscribe to persistence-warning changes. Returns an unsubscribe function. */
+export function onPersistenceWarning(listener) {
+    persistenceListeners.add(listener);
+    return () => persistenceListeners.delete(listener);
+}
+/**
+ * Like warnUser, but for the specific best-effort writes whose failure means
+ * silent data loss (session transcripts, audit log, telemetry) — a stderr
+ * line alone is easy to miss since Ink's full-screen redraws can immediately
+ * paint over it. Recorded once per context, same dedup as warnUser, so the
+ * UI badge doesn't grow without bound from a write that fails every turn.
+ */
+export function warnPersistenceFailure(context, err) {
+    const isNewContext = !warnedContexts.has(context);
+    warnUser(context, err);
+    if (isNewContext) {
+        const message = err instanceof Error ? err.message : String(err);
+        persistenceWarnings.push({ context, message });
+        notifyPersistenceListeners();
+    }
+}

package/dist/config/models.js

@@ -76,3 +76,13 @@ export function modelDisplaySlug(modelId) {
         .replace(/^-+|-+$/g, "");
     return `${prefix}${slug}`;
 }
+/**
+ * "provider/model" for display, without the doubled prefix that comes from
+ * naively joining them: several providers' model IDs already carry their own
+ * namespace (NVIDIA's catalog is "nvidia/nemotron-...", so the "nvidia"
+ * provider plus that model id would otherwise print "nvidia/nvidia/...").
+ * Only skip the provider prefix when the model id already starts with it.
+ */
+export function displayModelId(providerName, modelId) {
+    return modelId.startsWith(`${providerName}/`) ? modelId : `${providerName}/${modelId}`;
+}

package/dist/engine.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { Agent } from "./agent/loop.js";
-import { CONFIG_DIR, legacyGlobalModel, loadConfig, loadDotEnv, resolveProvider, } from "./config/config.js";
+import { CONFIG_DIR, legacyGlobalModel, loadConfig, loadDotEnv, privacyModeFor, resolveProvider, } from "./config/config.js";
 import { DEFAULT_MODEL, contextWindowFor } from "./config/models.js";
 import { PermissionManager } from "./permissions/permissions.js";
 import { loadRules } from "./permissions/rules.js";
@@ -35,6 +35,7 @@ export async function createEngineSession(dir, opts = {}) {
     if (trustWorkspace)
         loadDotEnv([path.join(workspace, ".env")]);
     const config = loadConfig();
+    const privacyMode = privacyModeFor(config);
     const provider = resolveProvider(config, opts.provider);
     if (!provider.apiKey) {
         throw new Error(`No API key found for provider "${provider.name}". Set it via env var, a .env file, or ~/.kritya/config.json.`);
@@ -49,9 +50,11 @@ export async function createEngineSession(dir, opts = {}) {
     const client = provider.name === "switchyard"
         ? await createSwitchyardClient(provider.apiKey, sampling)
         : new ProviderClient(provider.apiKey, provider.baseUrl, sampling);
-    const session = new SessionStore(workspace);
+    const session = new SessionStore(workspace, privacyMode);
     session.start([]);
-    const sessionMeter = createMeter(session.id, config.otel);
+    const sessionMeter = privacyMode
+        ? createMeter(session.id, "off")
+        : createMeter(session.id, config.otel);
     // The crash path is fire-and-forget best-effort by Node's own constraints
     // (a crash handler can't reliably await async work), so this uses the
     // synchronous flush() rather than flushAndWait().
@@ -79,8 +82,10 @@ export async function createEngineSession(dir, opts = {}) {
     if (trustWorkspace) {
         agent.hooks = new HookRunner(loadHooks(workspace, trustWorkspace), workspace);
     }
-    agent.audit = AuditLog.forSession(session.id, config.audit);
-    agent.tracer = createTracer(session.id, config.otel);
+    agent.audit = privacyMode ? undefined : AuditLog.forSession(session.id, config.audit);
+    agent.tracer = privacyMode
+        ? createTracer(session.id, "off")
+        : createTracer(session.id, config.otel);
     agent.meter = sessionMeter;
     if (agent.hooks)
         agent.hooks.tracer = agent.tracer;

package/dist/headless.js

@@ -1,11 +1,11 @@
 import path from "node:path";
 import { Agent } from "./agent/loop.js";
 import { KillSwitchError } from "./agent/killSwitch.js";
-import { CONFIG_DIR, legacyGlobalModel, listProviders, loadConfig, loadDotEnv, resolveProvider, } from "./config/config.js";
+import { CONFIG_DIR, legacyGlobalModel, listProviders, loadConfig, loadDotEnv, privacyModeFor, resolveProvider, } from "./config/config.js";
 import { DEFAULT_MODEL, contextWindowFor } from "./config/models.js";
 import { PermissionManager } from "./permissions/permissions.js";
 import { loadRules } from "./permissions/rules.js";
-import { ProviderClient, RetryExhaustedError } from "./provider/client.js";
+import { ProviderClient, RetryExhaustedError, friendlyProviderErrorHint, } from "./provider/client.js";
 import { createSwitchyardClient } from "./provider/switchyardClient.js";
 import { SWITCHYARD_ROUTE_ID, resolveEffectiveModel, staleSwitchyardModelWarning, stopSwitchyardSidecar, } from "./provider/switchyardSidecar.js";
 import { SessionStore } from "./session/store.js";
@@ -78,6 +78,7 @@ export async function runHeadless(args) {
     if (trustWorkspace)
         loadDotEnv([path.join(workspace, ".env")]);
     const config = loadConfig();
+    const privacyMode = args.privacy === true || privacyModeFor(config);
     const provider = resolveProvider(config, args.provider || undefined);
     if (!provider.apiKey) {
         return finish(args, startedAt, {
@@ -102,12 +103,16 @@ export async function runHeadless(args) {
     const client = provider.name === "switchyard"
         ? await createSwitchyardClient(provider.apiKey, sampling)
         : new ProviderClient(provider.apiKey, provider.baseUrl, sampling);
-    const session = new SessionStore(workspace);
-    const initialHistory = args.continue ? (SessionStore.loadLatest(workspace) ?? []) : [];
+    const session = new SessionStore(workspace, privacyMode);
+    const initialHistory = !privacyMode && args.continue ? (SessionStore.loadLatest(workspace) ?? []) : [];
     session.start(initialHistory);
-    const sessionAudit = AuditLog.forSession(session.id, config.audit);
-    const sessionTracer = createTracer(session.id, config.otel);
-    const sessionMeter = createMeter(session.id, config.otel);
+    const sessionAudit = privacyMode ? undefined : AuditLog.forSession(session.id, config.audit);
+    const sessionTracer = privacyMode
+        ? createTracer(session.id, "off")
+        : createTracer(session.id, config.otel);
+    const sessionMeter = privacyMode
+        ? createMeter(session.id, "off")
+        : createMeter(session.id, config.otel);
     // A crash here orphans MCP children and background processes onto a CI
     // runner, where nothing will ever reap them. No terminal to restore. The
     // crash path is fire-and-forget best-effort by Node's own constraints (a
@@ -252,7 +257,9 @@ export async function runHeadless(args) {
             errorMessage = `Stopped (${err.killReason ?? "kill switch engaged"})`;
         }
         else {
-            errorMessage = err instanceof Error ? err.message : String(err);
+            const message = err instanceof Error ? err.message : String(err);
+            const friendlyHint = friendlyProviderErrorHint(err, provider.name);
+            errorMessage = friendlyHint ? `${friendlyHint} (${message})` : message;
         }
     }
     finally {

package/dist/index.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { render } from "ink";
 import { Agent } from "./agent/loop.js";
-import { CONFIG_DIR, legacyGlobalModel, loadConfig, loadDotEnv, resolveProvider, } from "./config/config.js";
+import { CONFIG_DIR, appendGlobalEnvVar, legacyGlobalModel, loadConfig, loadDotEnv, privacyModeFor, resolveProvider, } from "./config/config.js";
 import { DEFAULT_MODEL, contextWindowFor } from "./config/models.js";
 import { PermissionManager } from "./permissions/permissions.js";
 import { loadRules } from "./permissions/rules.js";
@@ -26,6 +26,7 @@ import { UndoStack } from "./undo/undo.js";
 import { App } from "./ui/App.js";
 import { TrustPrompt } from "./ui/TrustPrompt.js";
 import { AiDisclosurePrompt } from "./ui/AiDisclosurePrompt.js";
+import { ApiKeySetupPrompt } from "./ui/ApiKeySetupPrompt.js";
 import { McpTrustPrompt } from "./ui/McpTrustPrompt.js";
 import { loadHooks, HookRunner } from "./hooks/hooks.js";
 import { loadMcpTools, shutdownMcp, } from "./mcp/client.js";
@@ -35,6 +36,7 @@ import { pluginsDir, scanPlugins, userPluginsDir } from "./plugins/discover.js";
 import { loadPluginMcpServers } from "./plugins/mcp.js";
 import { describeGatedContent, gatedContentHash, isTrusted, saveTrust } from "./trust/trust.js";
 import { isAiDisclosureShown, markAiDisclosureShown } from "./trust/aiDisclosure.js";
+import { isBannerSeen, markBannerSeen } from "./trust/bannerSeen.js";
 import { partitionByTrust, serverFingerprint, trustServer } from "./trust/mcpTrust.js";
 import { runHeadless } from "./headless.js";
 import { installCrashHandlers } from "./crash.js";
@@ -65,6 +67,7 @@ Headless / CI mode (no terminal UI, exits with 0 on success / 1 on failure):
                       since CI often checks out untrusted branches/PRs)
   --timeout <seconds> hard wall-clock cap for the whole run (default 1800)
   --non-interactive   accepted for compatibility; implied by --prompt
+  --privacy           do not persist transcripts, audit logs, or telemetry
 
 Inspect the local audit log:
   kritya audit --list | --verify [file] | --show [file]
@@ -93,6 +96,7 @@ function parseArgs(argv) {
         allowAll: false,
         trust: false,
         timeoutSeconds: 1800,
+        privacy: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -124,6 +128,8 @@ function parseArgs(argv) {
             args.trust = true;
         else if (a === "--timeout")
             args.timeoutSeconds = Number(argv[++i]) || args.timeoutSeconds;
+        else if (a === "--privacy")
+            args.privacy = true;
         else if (a === "--non-interactive") {
             // implied by --prompt; accepted so scripts can pass it explicitly
         }
@@ -176,6 +182,7 @@ if (args.prompt) {
         allowAll: args.allowAll,
         trust: args.trust,
         timeoutSeconds: args.timeoutSeconds,
+        privacy: args.privacy,
     }).then((code) => process.exit(code));
 }
 else {
@@ -259,8 +266,27 @@ async function showAiDisclosureNotice() {
             } }));
     });
 }
+/**
+ * Interactive fallback when no API key resolved for the active provider.
+ * Lets the user paste one straight in, saving it to ~/.kritya/.env, rather
+ * than forcing them out to read env-var instructions and relaunch. Only
+ * called from the interactive TTY path (see main() below) — headless mode
+ * (src/headless.ts) never imports this and keeps failing with a plain error.
+ */
+async function promptApiKeySetup(providerName, envVarName) {
+    if (!envVarName)
+        return null;
+    return new Promise((resolve) => {
+        const instance = render(_jsx(ApiKeySetupPrompt, { providerName: providerName, envVarName: envVarName, onDecision: (result) => {
+                instance.unmount();
+                resolve(result.action === "save" ? result.key : null);
+            } }));
+    });
+}
 async function main() {
     const config = loadConfig();
+    const privacyMode = args.privacy || privacyModeFor(config);
+    const firstLaunch = !isBannerSeen(workspace);
     if (!isAiDisclosureShown(workspace)) {
         await showAiDisclosureNotice();
         markAiDisclosureShown(workspace);
@@ -273,7 +299,15 @@ async function main() {
         loadDotEnv([path.join(workspace, ".env")]);
     }
     const provider = resolveProvider(config, args.provider || undefined);
-    const apiKey = provider.apiKey;
+    let apiKey = provider.apiKey;
+    if (!apiKey) {
+        const entered = await promptApiKeySetup(provider.name, provider.apiKeyEnv);
+        if (entered) {
+            appendGlobalEnvVar(provider.apiKeyEnv, entered);
+            process.env[provider.apiKeyEnv] = entered;
+            apiKey = entered;
+        }
+    }
     if (!apiKey) {
         const hint = provider.name === "nvidia"
             ? `Get one at https://build.nvidia.com, then one of:\n` +
@@ -312,18 +346,22 @@ async function main() {
     let client = provider.name === "switchyard"
         ? await createSwitchyardClient(apiKey, sampling)
         : new ProviderClient(apiKey, provider.baseUrl, sampling);
-    const session = new SessionStore(workspace);
+    const session = new SessionStore(workspace, privacyMode);
     // Shared by the main agent and every subagent it spawns, so a write
     // subagent's commits and a read-only subagent's tool calls land in the same
     // audit trail and trace tree as the turn that spawned them — an agent that
     // edits the repo should never do so off the record.
-    const sessionAudit = AuditLog.forSession(session.id, config.audit);
-    const sessionTracer = createTracer(session.id, config.otel);
-    const sessionMeter = createMeter(session.id, config.otel);
-    const initialHistory = args.continue ? (SessionStore.loadLatest(workspace) ?? []) : [];
-    const initialTasks = args.continue ? SessionStore.loadLatestTasks(workspace) : [];
+    const sessionAudit = privacyMode ? undefined : AuditLog.forSession(session.id, config.audit);
+    const sessionTracer = privacyMode
+        ? createTracer(session.id, "off")
+        : createTracer(session.id, config.otel);
+    const sessionMeter = privacyMode
+        ? createMeter(session.id, "off")
+        : createMeter(session.id, config.otel);
+    const initialHistory = !privacyMode && args.continue ? (SessionStore.loadLatest(workspace) ?? []) : [];
+    const initialTasks = !privacyMode && args.continue ? SessionStore.loadLatestTasks(workspace) : [];
     session.start(initialHistory);
-    const resumeSessions = args.resume ? SessionStore.listSessions(workspace) : [];
+    const resumeSessions = !privacyMode && args.resume ? SessionStore.listSessions(workspace) : [];
     // Filled in once the app is mounted, below; the crash handler needs a way to
     // tear the UI down and is installed before there is a UI to tear down.
     const ui = {};
@@ -677,5 +715,6 @@ async function main() {
             permissionRef.current = fn;
         }, onRequestElicitationReady: (fn) => {
             elicitationRef.current = fn;
-        } }));
+        }, privacyMode: privacyMode, firstLaunch: firstLaunch }));
+    markBannerSeen(workspace);
 }

package/dist/provider/client.js

@@ -99,6 +99,25 @@ export function isRetryable(err) {
     }
     return false;
 }
+/**
+ * A short, actionable translation for the non-retryable failures a
+ * first-time user is most likely to hit — a rejected key or an unknown
+ * model id — instead of the raw `{"status":403,"title":"Forbidden",...}`
+ * body the provider sent. Returns undefined for anything else, so callers
+ * fall back to the raw message unchanged.
+ */
+export function friendlyProviderErrorHint(err, providerName) {
+    const status = err?.status;
+    if (status === 401 || status === 403) {
+        return (`Your API key for provider "${providerName}" was rejected. Check it's correct, ` +
+            `still active, and hasn't expired, then try again.`);
+    }
+    if (status === 404 && !isEmptyBodyNotFound(err)) {
+        return (`Provider "${providerName}" doesn't recognize this model. Check the model ID with ` +
+            `/model, or that your account has access to it.`);
+    }
+    return undefined;
+}
 /** Read one header case-insensitively from whatever shape the SDK attached. */
 function headerValue(err, name) {
     const headers = err?.headers;

package/dist/provider/switchyardClient.js

@@ -29,6 +29,7 @@ export class SwitchyardProviderClient extends ProviderClient {
             let lastErr = err;
             for (const fb of this.fallbacks) {
                 try {
+                    callbacks.onFallback?.("switchyard", fb.model);
                     return await fb.client.chat(fb.model, messages, tools, callbacks, signal, trace);
                 }
                 catch (fbErr) {

package/dist/session/store.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { writeFileAtomicSync } from "../atomicWrite.js";
 import { CONFIG_DIR } from "../config/config.js";
 import { hardenWindowsDir } from "../config/winAcl.js";
-import { debugLog, warnUser } from "../config/debug.js";
+import { debugLog, warnPersistenceFailure } from "../config/debug.js";
 /**
  * A session file loaded whole into memory has no upper bound otherwise —
  * `--continue` on a pathologically large transcript (corruption, a runaway
@@ -127,7 +127,7 @@ export class SessionStore {
             writeSessionFile(this.tasksFilePath(), JSON.stringify(tasks));
         }
         catch (err) {
-            warnUser(`SessionStore.saveTasks(${this.tasksFilePath()})`, err);
+            warnPersistenceFailure(`SessionStore.saveTasks(${this.tasksFilePath()})`, err);
         }
     }
     /** Loads the task checklist saved alongside a given session file, if any. */
@@ -178,7 +178,7 @@ export class SessionStore {
         }
         catch (err) {
             // Persistence is best-effort; never crash the session over it.
-            warnUser(`SessionStore.append(${this.file})`, err);
+            warnPersistenceFailure(`SessionStore.append(${this.file})`, err);
         }
     }
     /** Start over with a fresh session file (used by /clear). */
@@ -201,7 +201,7 @@ export class SessionStore {
         }
         catch (err) {
             // Persistence is best-effort; never crash the session over it.
-            warnUser(`SessionStore.overwrite(${this.file})`, err);
+            warnPersistenceFailure(`SessionStore.overwrite(${this.file})`, err);
         }
     }
     /**

package/dist/telemetry/metrics.js

@@ -1,4 +1,5 @@
 import { VERSION } from "../version.js";
+import { warnPersistenceFailure } from "../config/debug.js";
 import { encodeMetricsSnapshot, postOtlp, postOtlpAndWait, } from "./otlp.js";
 const NOOP_COUNTER = { add() { } };
 const NOOP_HISTOGRAM = { record() { } };
@@ -113,8 +114,10 @@ class RealMeter {
                 return;
             postOtlp(this.endpoint, "/v1/metrics", body, this.headers);
         }
-        catch {
-            // best-effort: metrics must never crash the process
+        catch (err) {
+            // best-effort: metrics must never crash the process, but a dropped
+            // export should still be visible to the user.
+            warnPersistenceFailure("metrics.flush", err);
         }
     }
     async flushAndWait() {
@@ -124,8 +127,8 @@ class RealMeter {
                 return;
             await postOtlpAndWait(this.endpoint, "/v1/metrics", body, this.headers);
         }
-        catch {
-            // best-effort: metrics must never crash the process
+        catch (err) {
+            warnPersistenceFailure("metrics.flushAndWait", err);
         }
     }
     stop() {

package/dist/telemetry/otlp.js

@@ -1,4 +1,4 @@
-import { warnUser } from "../config/debug.js";
+import { warnPersistenceFailure } from "../config/debug.js";
 import { assertSafeUrl, pinnedDispatcherAllowLoopback, } from "../net/urlSafety.js";
 function toAnyValue(value) {
     if (typeof value === "string")
@@ -109,10 +109,10 @@ export function postOtlp(endpoint, path, body, headers) {
             body: JSON.stringify(body),
             dispatcher: pinnedDispatcherAllowLoopback,
         };
-        fetch(url.href, init).catch((err) => warnUser(`postOtlp(${path})`, err));
+        fetch(url.href, init).catch((err) => warnPersistenceFailure(`postOtlp(${path})`, err));
     }
     catch (err) {
-        warnUser(`postOtlp(${path})`, err);
+        warnPersistenceFailure(`postOtlp(${path})`, err);
     }
 }
 /**
@@ -134,6 +134,6 @@ export async function postOtlpAndWait(endpoint, path, body, headers) {
         await fetch(url.href, init);
     }
     catch (err) {
-        warnUser(`postOtlpAndWait(${path})`, err);
+        warnPersistenceFailure(`postOtlpAndWait(${path})`, err);
     }
 }

package/dist/telemetry/tracer.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { CONFIG_DIR } from "../config/config.js";
 import { hardenWindowsDir } from "../config/winAcl.js";
-import { debugLog, warnUser } from "../config/debug.js";
+import { debugLog, warnPersistenceFailure } from "../config/debug.js";
 import { VERSION } from "../version.js";
 import { encodeSpan, postOtlp } from "./otlp.js";
 function nowUnixNano() {
@@ -158,7 +158,7 @@ function fileSink(file) {
         }
         catch (err) {
             // best-effort: telemetry must never crash a turn
-            warnUser(`tracer.fileSink(${file})`, err);
+            warnPersistenceFailure(`tracer.fileSink(${file})`, err);
         }
     };
 }

package/dist/trust/bannerSeen.js

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_DIR } from "../config/config.js";
+import { hardenWindowsDir } from "../config/winAcl.js";
+import { debugLog } from "../config/debug.js";
+/**
+ * Tracks which workspaces have already shown the full ASCII banner once, so
+ * repeat launches (which cost real vertical space in a terminal) can fall
+ * back to a compact one-line header instead. Same shape and persistence
+ * pattern as aiDisclosure.ts's ai-disclosure.json.
+ */
+const BANNER_FILE = path.join(CONFIG_DIR, "banner-seen.json");
+function loadStore(storeFile) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(storeFile, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch (err) {
+        // A missing file means "not shown anywhere yet" (normal); a malformed one
+        // means every workspace re-shows the full banner, worth being able to see.
+        debugLog(`loadStore(${storeFile})`, err);
+        return {};
+    }
+}
+/** Whether the full ASCII banner has already been shown for this workspace. */
+export function isBannerSeen(workspace, storeFile = BANNER_FILE) {
+    return typeof loadStore(storeFile)[path.resolve(workspace)] === "string";
+}
+/** Record that the full ASCII banner has been shown for this workspace, now. */
+export function markBannerSeen(workspace, storeFile = BANNER_FILE) {
+    const store = loadStore(storeFile);
+    store[path.resolve(workspace)] = new Date().toISOString();
+    fs.mkdirSync(path.dirname(storeFile), { recursive: true, mode: 0o700 });
+    hardenWindowsDir(path.dirname(storeFile));
+    fs.writeFileSync(storeFile, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
+}

package/dist/ui/ApiKeySetupPrompt.js

@@ -0,0 +1,22 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import TextInput from "ink-text-input";
+/**
+ * Shown once, only when the active provider has no API key resolved, on the
+ * interactive TTY path (never from headless — see runHeadless in
+ * src/headless.ts, which never imports this component). Lets a first-time
+ * user paste a key instead of hunting through env-var/dotfile instructions.
+ */
+export function ApiKeySetupPrompt({ providerName, envVarName, onDecision, }) {
+    const [value, setValue] = useState("");
+    useInput((_input, key) => {
+        if (key.escape)
+            onDecision({ action: "skip" });
+    });
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsxs(Text, { bold: true, color: "cyan", children: ["No API key found for provider \"", providerName, "\""] }), _jsxs(Text, { children: ["Paste your ", envVarName, " value below to save it to ~/.kritya/.env and continue \u2014 or press Esc to skip and set it up yourself."] }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "cyan", children: "> " }), _jsx(TextInput, { value: value, onChange: setValue, mask: "*", onSubmit: (v) => {
+                            const trimmed = v.trim();
+                            if (trimmed)
+                                onDecision({ action: "save", key: trimmed });
+                        } })] })] }));
+}

package/dist/ui/App.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { Fragment, useCallback, useEffect, useRef, useState } from "react";
 import { Box, Static, Text, useApp, useInput, useStdout } from "ink";
 import TextInput from "ink-text-input";
 import fs from "node:fs";
@@ -30,7 +30,7 @@ const IMAGE_RE = /\.(png|jpe?g|gif|webp|bmp)$/i;
 // Erase screen + scrollback, then home the cursor (same sequence Ink itself
 // uses for its own "content taller than the terminal" clear path).
 const CLEAR_TERMINAL = "\x1b[2J\x1b[3J\x1b[H";
-export function App({ agent, workspace, modelRef, providerRef, config, resumedCount, initialTasks, undoStack, uiBridge, resumeSessions, customCommands = [], mcpToolCount = 0, onSwitchClient, onRequestPermissionReady, onRequestElicitationReady, }) {
+export function App({ agent, workspace, modelRef, providerRef, config, resumedCount, initialTasks, undoStack, uiBridge, resumeSessions, customCommands = [], mcpToolCount = 0, onSwitchClient, onRequestPermissionReady, onRequestElicitationReady, privacyMode, firstLaunch, }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const [input, setInput] = useState("");
@@ -125,7 +125,7 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
             .catch(() => { });
     }, [workspace]);
     useEffect(refreshFileList, [refreshFileList]);
-    const { items, addItem, phase, setPhase, stream, thinking, activity, setActivity, runningPhase, setRunningPhase, workflow, refreshWorkflow, permission, elicitation, inFlight, model, provider, servedModel, totalUsage, totalCost, tasks, setTasks, ctxPct, setCtxPct, tokenBudget, budgetPct, budgetUsed, budgetStopped, resetBudget, setBudgetLimit, branch, planMode, setPlanMode, dryRunMode, killed, killReason, engageKill, releaseKill, acceptEdits, setAcceptEdits, autoApprovedCount, cycleMode, onAcceptEditsConfirm, abortRef, setModelEverywhere, setProviderEverywhere, costReport, runAgent, runWebSearch, onPermissionDecision, onElicitationDecision, onResumeSelect, requestPermission, requestElicitation, } = useAgent({
+    const { items, addItem, phase, setPhase, stream, thinking, activity, setActivity, runningPhase, setRunningPhase, workflow, refreshWorkflow, permission, elicitation, inFlight, model, provider, servedModel, totalUsage, totalCost, tasks, setTasks, ctxPct, setCtxPct, tokenBudget, budgetPct, budgetUsed, budgetStopped, resetBudget, setBudgetLimit, branch, planMode, setPlanMode, dryRunMode, killed, killReason, engageKill, releaseKill, acceptEdits, setAcceptEdits, autoApprovedCount, cycleMode, onAcceptEditsConfirm, abortRef, setModelEverywhere, setProviderEverywhere, costReport, runAgent, runWebSearch, onPermissionDecision, onElicitationDecision, onResumeSelect, requestPermission, requestElicitation, persistenceWarningCount, } = useAgent({
         agent,
         workspace,
         modelRef,
@@ -137,6 +137,7 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
         resumeSessions,
         refreshFileList,
         onSwitchClient,
+        firstLaunch,
     });
     useEffect(() => {
         onRequestPermissionReady?.(requestPermission);
@@ -154,11 +155,49 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
         const t = setInterval(() => setElapsed(Math.floor((Date.now() - start) / 1000)), 1000);
         return () => clearInterval(t);
     }, [phase]);
+    // Detail moved out of the always-visible status line (see StatusLine.tsx) —
+    // surfaced instead via the /status command, on demand.
+    const statusReport = useCallback(() => {
+        const sandboxActive = (config.sandboxExec ?? defaultSandboxMode()) !== "off" && sandboxAvailable();
+        const cachedPct = (totalUsage.cachedPromptTokens ?? 0) > 0
+            ? ` (${Math.round(((totalUsage.cachedPromptTokens ?? 0) / totalUsage.promptTokens) * 100)}% cached)`
+            : "";
+        const lines = [
+            `workspace: ${workspace}`,
+            `sandbox: ${sandboxActive ? "active" : "inactive"}`,
+            `context used: ${ctxPct}%`,
+            `token budget: ${budgetPct}% of ${tokenBudget.toLocaleString()} (${budgetUsed.toLocaleString()} used)${budgetStopped ? " — stopped" : ""}`,
+            `tokens: ${totalUsage.estimated ? "~" : ""}${totalUsage.promptTokens.toLocaleString()} in${cachedPct} / ${totalUsage.completionTokens.toLocaleString()} out`,
+            tasks.length > 0
+                ? `tasks: ${tasks.filter((t) => t.status === "done").length}/${tasks.length} done`
+                : null,
+            phase === "working" && elapsed > 0 ? `elapsed: ${elapsed}s` : null,
+            verbose ? "verbose: on" : null,
+        ].filter((l) => l !== null);
+        return lines.join("\n");
+    }, [
+        config,
+        workspace,
+        ctxPct,
+        budgetPct,
+        tokenBudget,
+        budgetUsed,
+        budgetStopped,
+        totalUsage,
+        tasks,
+        phase,
+        elapsed,
+        verbose,
+    ]);
     const allCommands = [
         ...BUILTIN_COMMANDS,
-        ...customCommands.map((c) => ({ name: c.name, description: c.description })),
+        ...customCommands.map((c) => ({
+            name: c.name,
+            description: c.description,
+            category: "Custom",
+        })),
         // Servers can contribute slash commands too (MCP prompts).
-        ...mcpPrompts().map((p) => ({ name: p.command, description: p.description })),
+        ...mcpPrompts().map((p) => ({ name: p.command, description: p.description, category: "MCP" })),
     ];
     // Command suggestions while typing a slash command (before any arguments).
     const suggestions = phase === "input" && input.startsWith("/") && !input.includes(" ")
@@ -195,6 +234,7 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
             return;
         }
         if (key.escape && phase === "working") {
+            setActivity("cancelling…");
             abortRef.current?.abort();
         }
         // Ctrl+O toggles showing full tool output.
@@ -307,6 +347,7 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
             runWebSearch,
             expandMentions,
             costReport,
+            statusReport,
             gitDiffStat,
             exit,
         };
@@ -444,7 +485,18 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
                                     setInput((prev) => (isCtrlEcho(prev, v) ? prev : v.replace(/\t/g, "")));
                                     setCmdIndex(0);
                                     setFileIndex(0);
-                                }, onSubmit: handleSubmit }, inputKey)] }), suggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [suggestions.map((c, i) => (_jsxs(Text, { color: i === selectedCmd ? "cyan" : undefined, children: [i === selectedCmd ? "❯ " : "  ", _jsx(Text, { bold: i === selectedCmd, children: c.name }), _jsxs(Text, { dimColor: true, children: [" \u2014 ", c.description] })] }, c.name))), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter select \u00B7 Enter again to run" })] })), fileSuggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [fileSuggestions.map((f, i) => (_jsxs(Text, { color: i === selectedFile ? "cyan" : undefined, children: [i === selectedFile ? "❯ " : "  ", f] }, f))), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter attach file" })] }))] })), _jsx(Box, { children: _jsx(StatusLine, { killed: killed, killReason: killReason, dryRunMode: dryRunMode, planMode: planMode, acceptEdits: acceptEdits, autoApprovedCount: autoApprovedCount, model: servedModel && servedModel !== model
+                                }, onSubmit: handleSubmit }, inputKey)] }), suggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [(() => {
+                                // Group headers only earn their keep once more than one
+                                // category is actually on screen — once typing has filtered
+                                // down to a single family, a lone header is just noise.
+                                const showHeaders = new Set(suggestions.map((c) => c.category)).size > 1;
+                                let lastCategory;
+                                return suggestions.map((c, i) => {
+                                    const showHeader = showHeaders && c.category !== lastCategory;
+                                    lastCategory = c.category;
+                                    return (_jsxs(Fragment, { children: [showHeader && _jsx(Text, { dimColor: true, children: c.category ?? "Other" }), _jsxs(Text, { color: i === selectedCmd ? "cyan" : undefined, children: [i === selectedCmd ? "❯ " : "  ", _jsx(Text, { bold: i === selectedCmd, children: c.name }), _jsxs(Text, { dimColor: true, children: [" \u2014 ", c.description] })] })] }, c.name));
+                                });
+                            })(), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter select \u00B7 Enter again to run" })] })), fileSuggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [fileSuggestions.map((f, i) => (_jsxs(Text, { color: i === selectedFile ? "cyan" : undefined, children: [i === selectedFile ? "❯ " : "  ", f] }, f))), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter attach file" })] }))] })), _jsx(Box, { children: _jsx(StatusLine, { killed: killed, killReason: killReason, dryRunMode: dryRunMode, planMode: planMode, acceptEdits: acceptEdits, autoApprovedCount: autoApprovedCount, provider: provider, model: servedModel && servedModel !== model
                         ? `${model}-${modelDisplaySlug(servedModel)}`
-                        : model, workflow: workflow, branch: branch, tasks: tasks, ctxPct: ctxPct, budgetPct: budgetPct, budgetStopped: budgetStopped, phase: phase, elapsed: elapsed, totalUsage: totalUsage, totalCost: totalCost, verbose: verbose, workspace: workspace, sandboxActive: (config.sandboxExec ?? defaultSandboxMode()) !== "off" && sandboxAvailable() }) })] }));
+                        : model, workflow: workflow, branch: branch, budgetPct: budgetPct, budgetStopped: budgetStopped, totalCost: totalCost, sandboxActive: (config.sandboxExec ?? defaultSandboxMode()) !== "off" && sandboxAvailable(), persistenceWarningCount: persistenceWarningCount, privacyMode: privacyMode }) })] }));
 }

package/dist/ui/Banner.js

@@ -50,7 +50,10 @@ function rowColor(row) {
     return `#${[r, g, b].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
 }
 const BETA_LABEL = "beta";
-export function Banner({ subtitle }) {
+export function Banner({ subtitle, compact }) {
+    if (compact) {
+        return (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { dimColor: true, children: subtitle }) }));
+    }
     const columns = terminalColumns(process.stdout);
     const wide = bannerLines("KRITYA", "░░");
     const narrow = bannerLines("KRITYA", "░");

package/dist/ui/StatusLine.js

@@ -1,11 +1,19 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Text } from "ink";
-import path from "node:path";
-/** The single dim status bar pinned to the bottom of the screen. */
-export function StatusLine({ killed, killReason, dryRunMode, planMode, acceptEdits, autoApprovedCount, model, workflow, branch, tasks, ctxPct, budgetPct, budgetStopped, phase, elapsed, totalUsage, totalCost, verbose, workspace, sandboxActive, }) {
-    return (_jsxs(Text, { dimColor: true, children: [killed ? (_jsxs(Text, { bold: true, color: "red", children: ["\u26D4 KILLED", killReason ? ` (${killReason})` : "", " \u00B7", " "] })) : (""), dryRunMode ? (_jsx(Text, { color: "cyan", children: "dry-run \u00B7 " })) : planMode ? (_jsx(Text, { color: "cyan", children: "plan \u00B7 " })) : acceptEdits ? (_jsxs(Text, { color: "green", children: ["accept edits (", autoApprovedCount, " auto-approved) \u00B7 "] })) : (""), model, _jsxs(Text, { color: sandboxActive ? "green" : "red", children: [" ", "\u00B7 ", sandboxActive ? "🔒 sandbox:active" : "🔓 sandbox:inactive"] }), workflow ? (_jsxs(Text, { color: "magenta", children: [" ", "\u00B7 \u2691 ", workflow.name, ":", workflow.phase] })) : (""), branch ? ` · ⎇ ${branch}` : "", tasks.length > 0
-                ? ` · tasks ${tasks.filter((t) => t.status === "done").length}/${tasks.length}`
-                : "", ctxPct > 0 ? ` · ctx ${ctxPct}%` : "", budgetPct > 0 ? (_jsxs(Text, { color: budgetStopped ? "red" : budgetPct >= 80 ? "yellow" : undefined, children: [" ", "\u00B7 budget ", budgetPct, "%"] })) : (""), phase === "working" && elapsed > 0 ? ` · ${elapsed}s` : "", " \u00B7", " ", totalUsage.estimated ? "~" : "", totalUsage.promptTokens.toLocaleString(), " in", (totalUsage.cachedPromptTokens ?? 0) > 0
-                ? ` (${Math.round(((totalUsage.cachedPromptTokens ?? 0) / totalUsage.promptTokens) * 100)}% cached)`
-                : "", " ", "/ ", totalUsage.completionTokens.toLocaleString(), " out", totalCost > 0 ? ` · $${totalCost.toFixed(4)}` : "", verbose ? " · verbose" : "", " \u00B7 ", path.basename(workspace)] }));
+import { displayModelId } from "../config/models.js";
+/**
+ * The single dim status bar pinned to the bottom of the screen. Keeps only
+ * the fields worth glancing at on every render; everything else (context %,
+ * task checklist, elapsed time, token counts, workspace path, verbose flag)
+ * moved to the on-demand `/status` command — see CommandContext.statusReport
+ * in src/commands/registry.ts.
+ */
+export function StatusLine({ killed, killReason, dryRunMode, planMode, acceptEdits, autoApprovedCount, provider, model, workflow, branch, budgetPct, budgetStopped, totalCost, sandboxActive, persistenceWarningCount, privacyMode, }) {
+    return (_jsxs(Text, { dimColor: true, children: [killed ? (_jsxs(Text, { bold: true, color: "red", children: ["\u26D4 KILLED", killReason ? ` (${killReason})` : "", " \u00B7", " "] })) : (""), _jsxs(Text, { color: dryRunMode || planMode ? "cyan" : acceptEdits ? "green" : undefined, children: ["mode:", " ", dryRunMode
+                        ? "dry-run"
+                        : planMode
+                            ? "plan"
+                            : acceptEdits
+                                ? `accept-edits (${autoApprovedCount} auto)`
+                                : "default", " · "] }), displayModelId(provider, model), _jsxs(Text, { color: sandboxActive ? "green" : "red", children: [" ", "\u00B7 ", sandboxActive ? "🔒 sandbox:active" : "🔓 sandbox:inactive"] }), workflow ? (_jsxs(Text, { color: "magenta", children: [" ", "\u00B7 \u2691 ", workflow.name, ":", workflow.phase] })) : (""), branch ? ` · ⎇ ${branch}` : "", budgetStopped || budgetPct >= 80 ? (_jsxs(Text, { color: budgetStopped ? "red" : "yellow", children: [" \u00B7 budget ", budgetPct, "%"] })) : (""), totalCost > 0 ? ` · $${totalCost.toFixed(4)}` : "", persistenceWarningCount > 0 ? (_jsxs(Text, { color: "yellow", children: [" \u00B7 \u26A0 persistence warnings: ", persistenceWarningCount] })) : (""), privacyMode ? _jsx(Text, { color: "cyan", children: " \u00B7 privacy:on" }) : "", " · /status for details"] }));
 }

package/dist/ui/TranscriptItem.js

@@ -9,5 +9,5 @@ export function TranscriptItem({ item, verbose, stdout }) {
     return (_jsxs(Box, { marginBottom: item.kind === "tool" ? 0 : 1, flexDirection: "column", children: [item.kind === "user" && (_jsxs(Text, { children: [_jsxs(Text, { bold: true, color: "green", children: ["\u276F", " "] }), item.text] })), item.kind === "assistant" && _jsx(Markdown, { text: item.text }), item.kind === "tool" && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { dimColor: true, children: [item.error ? _jsx(Text, { color: "red", children: "\u2717" }) : _jsx(Text, { color: "green", children: "\u2713" }), " ", item.summary, item.resultSummary && !verbose ? ` — ${item.resultSummary}` : ""] }), item.output && item.output.trim() && (item.resultSummary === undefined || verbose) && (_jsx(Text, { dimColor: true, children: toolOutputPreview(item.output, verbose, Math.max(20, terminalColumns(stdout) - 6), item.error)
                             .split("\n")
                             .map((l) => `    ${l}`)
-                            .join("\n") }))] })), item.kind === "info" && _jsx(Text, { dimColor: true, children: item.text }), item.kind === "banner" && _jsx(Banner, { subtitle: item.subtitle })] }));
+                            .join("\n") }))] })), item.kind === "info" && _jsx(Text, { dimColor: true, children: item.text }), item.kind === "banner" && _jsx(Banner, { subtitle: item.subtitle, compact: item.compact })] }));
 }

package/dist/ui/useAgent.js

@@ -2,8 +2,8 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import path from "node:path";
 import { gitBranch } from "../git/git.js";
 import { listProviders, resolveProvider, saveConfig, saveProviderModel, } from "../config/config.js";
-import { DEFAULT_MODEL, contextWindowFor } from "../config/models.js";
-import { ProviderClient, RetryExhaustedError } from "../provider/client.js";
+import { DEFAULT_MODEL, contextWindowFor, displayModelId } from "../config/models.js";
+import { ProviderClient, RetryExhaustedError, friendlyProviderErrorHint, } from "../provider/client.js";
 import { createSwitchyardClient } from "../provider/switchyardClient.js";
 import { SWITCHYARD_ROUTE_ID, resolveEffectiveModel } from "../provider/switchyardSidecar.js";
 import { KillSwitchError } from "../agent/killSwitch.js";
@@ -12,12 +12,24 @@ import { tavilySearch } from "../tools/webSearch.js";
 import { killActiveNotice, useKillSwitch } from "./useKillSwitch.js";
 import { useUsageBudget } from "./useUsageBudget.js";
 import { useSessionResume } from "./useSessionResume.js";
+import { activePersistenceWarnings, onPersistenceWarning } from "../config/debug.js";
+function initialToolStatus(name) {
+    if (name.startsWith("mcp_"))
+        return "contacting MCP server…";
+    if (name.startsWith("lsp_"))
+        return "querying language server…";
+    if (name.includes("document"))
+        return "processing document…";
+    if (name.includes("notebook"))
+        return "processing notebook…";
+    return undefined;
+}
 /**
  * Owns everything tied to running agent turns: the transcript, streaming and
  * permission state, usage/cost tracking, and session resume. Input handling
  * (text box, slash-command suggestions, @mention autocomplete) stays in App.
  */
-export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBridge, resumedCount, initialTasks, resumeSessions, refreshFileList, onSwitchClient, }) {
+export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBridge, resumedCount, initialTasks, resumeSessions, refreshFileList, onSwitchClient, firstLaunch, }) {
     const nextId = useRef(0);
     const [items, setItems] = useState(() => {
         const initial = [
@@ -25,6 +37,7 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
                 id: nextId.current++,
                 kind: "banner",
                 subtitle: `${path.basename(workspace)} · ${modelRef.current} · type a request, or /help for commands`,
+                compact: !firstLaunch,
             },
         ];
         if (resumedCount > 0) {
@@ -44,6 +57,21 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
     const [stream, setStream] = useState("");
     const [thinking, setThinking] = useState(false);
     const [activity, setActivity] = useState(null);
+    const [persistenceWarningCount, setPersistenceWarningCount] = useState(() => activePersistenceWarnings().length);
+    useEffect(() => onPersistenceWarning((warnings) => setPersistenceWarningCount(warnings.length)), []);
+    /**
+     * Compaction calls the model directly and can take a while, so without this
+     * the spinner would sit frozen on whatever it showed before compaction
+     * started until onToolEnd's after-the-fact "compact" record appears.
+     */
+    useEffect(() => {
+        agent.onCompactStart = () => setActivity("compacting context…");
+        agent.onCompactEnd = () => setActivity(null);
+        return () => {
+            agent.onCompactStart = undefined;
+            agent.onCompactEnd = undefined;
+        };
+    }, [agent]);
     /**
      * Which workflow phase the *current turn* is running. Turn-scoped and cleared
      * when the turn ends, unlike `workflow` below — `activity` can't carry this,
@@ -355,6 +383,7 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
             return;
         }
         setPhase("working");
+        setActivity(`Calling ${displayModelId(provider, model)}…`);
         const ac = new AbortController();
         abortRef.current = ac;
         setInFlight([]);
@@ -372,7 +401,10 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
                 },
                 onToolStart: (id, name, summary) => {
                     setStream("");
-                    setInFlight((prev) => [...prev, { id, name, summary }]);
+                    setInFlight((prev) => [
+                        ...prev,
+                        { id, name, summary, status: initialToolStatus(name) },
+                    ]);
                 },
                 onToolEnd: (id, name, summary, preview, isError, resultSummary) => {
                     setInFlight((prev) => prev.filter((t) => t.id !== id));
@@ -397,6 +429,10 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
                     setStream("");
                     setActivity(`Provider error${status ? ` (${status})` : ""} — retrying (attempt ${attempt})…`);
                 },
+                onFallback: (from, to) => {
+                    setStream("");
+                    setActivity(`${from} unavailable — trying fallback model ${to}…`);
+                },
                 onUsage: (usage) => {
                     if (usage.servedModel)
                         setServedModel(usage.servedModel);
@@ -433,7 +469,8 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
                     text = `Error: ${message}${hint}`;
                 }
                 else {
-                    text = `Error: ${message}`;
+                    const friendlyHint = friendlyProviderErrorHint(err, provider);
+                    text = friendlyHint ? `${friendlyHint}\n\n(${message})` : `Error: ${message}`;
                 }
             }
             addItem({ kind: "info", text });
@@ -498,6 +535,7 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
         totalCost,
         tasks,
         setTasks,
+        persistenceWarningCount,
         ctxPct,
         setCtxPct,
         tokenBudget,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kritya",
-  "version": "0.8.23-beta",
+  "version": "0.8.25-beta",
   "description": "Kritya — a lean, provider-agnostic terminal coding agent (NVIDIA, OpenAI, OpenRouter, Groq, Ollama, and more)",
   "type": "module",
   "publishConfig": {