klyro 0.1.46 → 0.1.48

package/dist/agent/registry.js

@@ -16,6 +16,9 @@
  * The result is wrapped in retryingAdapter by default. Pass
  * { retry: false } to skip.
  */
+import * as fsSync from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { httpChatAdapter } from './provider-adapter.js';
 import { anthropicAdapter } from './anthropic-adapter.js';
 import { retryingAdapter } from './retry.js';
@@ -63,9 +66,57 @@ function normalizeProviderName(name) {
         return lower;
     return PROVIDER_ALIASES[lower];
 }
+/**
+ * Persisted provider settings (sync read — for CLIs that must not go async).
+ * Env still wins; ~/.klyro/settings.json + credentials are the fallback so
+ * `klyro run` works in fresh terminals with zero env vars.
+ *
+ * Reads the files directly (no module imports) to avoid any import cycle
+ * between agent/ and cli/ layers.
+ */
+function persistedProviderSettings() {
+    try {
+        const home = process.env.KLYRO_CONFIG_DIR ?? (os.homedir() || process.cwd());
+        const cfgPaths = process.env.KLYRO_CONFIG
+            ? [process.env.KLYRO_CONFIG]
+            : [path.join(home, '.klyro', 'settings.json'), path.join(home, '.klyro', 'config.json')];
+        let cfg = {};
+        for (const p of cfgPaths) {
+            try {
+                const parsed = JSON.parse(fsSync.readFileSync(p, 'utf-8'));
+                if (parsed && typeof parsed === 'object') {
+                    cfg = parsed;
+                    break;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        const credFile = process.env.KLYRO_CREDENTIALS_FILE ?? path.join(home, '.klyro', 'credentials.json');
+        let creds = {};
+        try {
+            creds = JSON.parse(fsSync.readFileSync(credFile, 'utf-8'));
+        }
+        catch { /* none */ }
+        const keyOf = (p) => typeof creds[p] === 'string' && creds[p].length > 0 ? creds[p] : undefined;
+        const baseURL = (cfg.baseUrl ?? cfg.baseURL);
+        const provider = cfg.provider;
+        const model = (cfg.model ?? cfg['model.default']);
+        const apiKey = (cfg.apiKey ?? cfg.api_key) ??
+            (provider ? keyOf(provider) : undefined) ??
+            keyOf('openai') ??
+            keyOf('anthropic');
+        return { baseURL, apiKey, provider, model };
+    }
+    catch {
+        return {};
+    }
+}
 export function buildProvider(opts = {}) {
-    const baseURL = opts.baseURL ?? process.env.KLYRO_BASE_URL;
-    const apiKey = opts.apiKey ?? process.env.KLYRO_API_KEY;
+    const saved = persistedProviderSettings();
+    const baseURL = opts.baseURL ?? process.env.KLYRO_BASE_URL ?? saved.baseURL;
+    const apiKey = opts.apiKey ?? process.env.KLYRO_API_KEY ?? saved.apiKey;
     const timeoutMs = opts.timeoutMs ?? 60_000;
     // Resolve provider (with aliases like 9router -> openrouter -> openai)
     let provider;

package/dist/cli/auth.d.ts

@@ -2,6 +2,20 @@
  * 2.2 — klyro login / logout / aliases
  * Stores masked key → ~/.klyro/credentials.json 0600
  */
+export declare function credPath(): string;
+/** Persist one provider key (0600). Never logs or returns the key. */
+export declare function saveKey(provider: string, key: string): Promise<void>;
+/** Which providers have stored keys (names only — never values). */
+export declare function storedProviders(): string[];
+export declare const LOGIN_DEFAULTS: Record<string, {
+    baseUrl: string;
+    model: string;
+}>;
+/**
+ * `klyro login` — full one-time setup. Persists provider + base URL + model
+ * to ~/.klyro/settings.json and the key to ~/.klyro/credentials.json (0600),
+ * so every future terminal picks them up with no env vars.
+ */
 export declare function runLogin(): Promise<number>;
 export declare function runLogout(provider?: string): Promise<number>;
 export declare function getStoredKey(provider: string): string | undefined;

package/dist/cli/auth.js

@@ -3,37 +3,82 @@
  * Stores masked key → ~/.klyro/credentials.json 0600
  */
 import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import * as readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
-function credPath() {
+export function credPath() {
+    // KLYRO_CREDENTIALS_FILE override exists for tests; real users get ~/.klyro/credentials.json.
+    if (process.env.KLYRO_CREDENTIALS_FILE)
+        return process.env.KLYRO_CREDENTIALS_FILE;
     const home = os.homedir() || process.cwd();
     return path.join(home, '.klyro', 'credentials.json');
 }
+/** Persist one provider key (0600). Never logs or returns the key. */
+export async function saveKey(provider, key) {
+    const creds = {};
+    try {
+        const raw = await fs.readFile(credPath(), 'utf-8');
+        Object.assign(creds, JSON.parse(raw));
+    }
+    catch { /* ignore */ }
+    creds[provider] = key.trim();
+    await fs.mkdir(path.dirname(credPath()), { recursive: true });
+    await fs.writeFile(credPath(), JSON.stringify(creds, null, 2), { mode: 0o600 });
+    try {
+        await fs.chmod(credPath(), 0o600);
+    }
+    catch { /* ignore on Windows */ }
+}
+/** Which providers have stored keys (names only — never values). */
+export function storedProviders() {
+    try {
+        const raw = fsSync.readFileSync(credPath(), 'utf-8');
+        const creds = JSON.parse(raw);
+        return Object.keys(creds).filter((k) => typeof creds[k] === 'string' && creds[k].length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+export const LOGIN_DEFAULTS = {
+    openai: { baseUrl: 'https://api.openai.com/v1', model: 'gpt-4o-mini' },
+    anthropic: { baseUrl: 'https://api.anthropic.com/v1', model: 'claude-3-5-sonnet-20240620' },
+    local: { baseUrl: 'http://localhost:11434/v1', model: 'llama3.2' },
+};
+/**
+ * `klyro login` — full one-time setup. Persists provider + base URL + model
+ * to ~/.klyro/settings.json and the key to ~/.klyro/credentials.json (0600),
+ * so every future terminal picks them up with no env vars.
+ */
 export async function runLogin() {
     const rl = readline.createInterface({ input: stdin, output: stdout });
     try {
-        const provider = (await rl.question('Provider (anthropic/openai) [openai]: ')) || 'openai';
-        const key = await rl.question('API key (input hidden, paste): ');
-        if (!key.trim()) {
+        const providerRaw = (await rl.question('Provider (openai/anthropic/local) [openai]: ')) || 'openai';
+        const provider = providerRaw.trim().toLowerCase();
+        const defs = LOGIN_DEFAULTS[provider] ?? LOGIN_DEFAULTS.openai;
+        const keyPrompt = provider === 'local' ? 'API key (empty for local Ollama): ' : 'API key (paste): ';
+        const key = await rl.question(keyPrompt);
+        if (!key.trim() && provider !== 'local') {
             process.stderr.write('No key provided\n');
             return 2;
         }
-        const creds = {};
-        try {
-            const raw = await fs.readFile(credPath(), 'utf-8');
-            Object.assign(creds, JSON.parse(raw));
-        }
-        catch { /* ignore */ }
-        creds[provider] = key.trim();
-        await fs.mkdir(path.dirname(credPath()), { recursive: true });
-        await fs.writeFile(credPath(), JSON.stringify(creds, null, 2), { mode: 0o600 });
-        try {
-            await fs.chmod(credPath(), 0o600);
+        const baseUrl = ((await rl.question(`Base URL [${defs.baseUrl}]: `)) || defs.baseUrl).trim();
+        const model = ((await rl.question(`Model [${defs.model}]: `)) || defs.model).trim();
+        const storeProvider = provider === 'local' ? 'openai' : provider;
+        if (key.trim()) {
+            await saveKey(storeProvider, key);
+            process.stdout.write(`Saved ${storeProvider} key to ${credPath()} (0600)\n`);
         }
-        catch { /* ignore on Windows */ }
-        process.stdout.write(`Saved ${provider} key to ${credPath()} (0600)\n`);
+        // Persist non-secret settings (merged with existing config, never clobbers).
+        const { loadConfig, saveConfig } = await import('./config.js');
+        const cfg = await loadConfig();
+        cfg.provider = storeProvider;
+        cfg.baseUrl = baseUrl;
+        cfg.model = model;
+        await saveConfig(cfg);
+        process.stdout.write(`Saved provider settings (applies to all terminals — no env vars needed)\n`);
         return 0;
     }
     finally {
@@ -63,9 +108,10 @@ export async function runLogout(provider) {
 }
 export function getStoredKey(provider) {
     try {
-        const raw = require('node:fs').readFileSync(credPath(), 'utf-8');
+        const raw = fsSync.readFileSync(credPath(), 'utf-8');
         const creds = JSON.parse(raw);
-        return creds[provider];
+        const v = creds[provider];
+        return typeof v === 'string' && v.length > 0 ? v : undefined;
     }
     catch {
         return undefined;

package/dist/cli/config.d.ts

@@ -7,8 +7,8 @@ import { z } from 'zod';
 export declare const ConfigSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
     provider: z.ZodOptional<z.ZodEnum<{
-        anthropic: "anthropic";
         openai: "openai";
+        anthropic: "anthropic";
     }>>;
     baseUrl: z.ZodOptional<z.ZodString>;
     apiKey: z.ZodOptional<z.ZodString>;
@@ -31,6 +31,7 @@ declare function setByPath(obj: Record<string, unknown>, dotted: string, value:
 declare function deleteByPath(obj: Record<string, unknown>, dotted: string): boolean;
 declare function parseValue(raw: string): unknown;
 export declare function loadConfig(): Promise<Record<string, unknown>>;
+export declare function loadConfigSync(): Record<string, unknown>;
 export declare function loadMergedConfig(cwd?: string, flags?: Record<string, unknown>): Promise<Record<string, unknown>>;
 export declare function saveConfig(obj: Record<string, unknown>): Promise<void>;
 export declare function runConfig(args: string[]): Promise<number>;

package/dist/cli/config.js

@@ -217,6 +217,26 @@ export async function loadConfig() {
     }
     return {};
 }
+// --- Synchronous single-file load (for sync call sites like buildProvider) ---
+export function loadConfigSync() {
+    const files = [getConfigPath(), getLegacyConfigPath()];
+    for (const file of files) {
+        try {
+            const raw = fsSync.readFileSync(file, 'utf-8');
+            const obj = parseJsonc(raw, file);
+            return validateConfig(obj, file);
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === 'ENOENT')
+                continue;
+            // Corrupt config must not crash provider resolution — ignore here
+            // (klyro config/doctor surface the error properly).
+            return {};
+        }
+    }
+    return {};
+}
 // --- Merged load with 5-layer precedence ---
 export async function loadMergedConfig(cwd = process.cwd(), flags = {}) {
     const layers = [];

package/dist/cli/repl.js

@@ -6,6 +6,8 @@
  * via the global hooks installed by App.useEffect.
  */
 import React from 'react';
+import * as fsSync from 'node:fs';
+import * as nodePath from 'node:path';
 import { render } from 'ink';
 import { App } from '../tui/app.js';
 import { httpChatAdapter } from '../agent/provider-adapter.js';
@@ -19,6 +21,7 @@ import { TuiApprovalBridge } from '../tui/approval.js';
 import { parseUnifiedDiff } from '../tui/diff-parser.js';
 import { parse } from './slash/parser.js';
 import { resolveProvider, providerHelp } from '../providers.js';
+import { MouseFilter, MOUSE_ENABLE, MOUSE_DISABLE } from '../tui/mouse.js';
 import { inferProviderFromBaseURL } from '../agent/registry.js';
 import { getDefaultSessionStore } from '../persistence/session.js';
 import { buildSystemPrompt, parseImageInput } from '../context/system-prompt.js';
@@ -27,16 +30,35 @@ export async function startRepl(opts = {}) {
     // Reuse the same provider resolution as legacy repl.ts — probes local
     // Ollama / LM Studio / vLLM when env is not fully set, so bare `klyro`
     // works with a local model just like `klyro chat` does.
-    const resolved = await resolveProvider();
+    let resolved = await resolveProvider();
     if (!resolved) {
-        process.stderr.write('klyro: no provider available.\n');
-        process.stderr.write(`  ${providerHelp(null)}\n`);
-        process.stderr.write('  Set KLYRO_BASE_URL and KLYRO_API_KEY, or run a local server (Ollama, LM Studio, vLLM).\n');
-        process.stderr.write('  Examples:\n');
-        process.stderr.write('    set KLYRO_BASE_URL=https://api.openai.com/v1\n');
-        process.stderr.write('    set KLYRO_API_KEY=sk-...\n');
-        process.stderr.write('    ollama serve   # then KLYRO_BASE_URL=http://localhost:11434/v1 KLYRO_MODEL=llama3.2\n');
-        return 2;
+        // First-run setup: ask ONCE (stdin is free — the Ink App is not mounted
+        // yet), persist to ~/.klyro, and continue. Every future terminal — this
+        // one, new windows, `klyro run` — picks it up with zero env vars.
+        const interactive = !opts.nonInteractive && (opts.forceTty || process.stdin.isTTY);
+        if (interactive) {
+            const { runFirstRunSetup } = await import('./setup.js');
+            const readline = await import('node:readline/promises');
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                const ans = await runFirstRunSetup((q) => rl.question(q));
+                if (!ans) {
+                    process.stderr.write('klyro: setup aborted — run `klyro login` when ready.\n');
+                    return 2;
+                }
+                process.stderr.write('klyro: saved — this and all future terminals will use it (change via /provider /model or `klyro config`).\n');
+            }
+            finally {
+                rl.close();
+            }
+            resolved = await resolveProvider();
+        }
+        if (!resolved) {
+            process.stderr.write('klyro: no provider available.\n');
+            process.stderr.write(`  ${providerHelp(null)}\n`);
+            process.stderr.write('  Run `klyro login` once (persists for all terminals), set KLYRO_BASE_URL and KLYRO_API_KEY, or run a local server (Ollama, LM Studio, vLLM).\n');
+            return 2;
+        }
     }
     const baseUrl = resolved.baseURL;
     const apiKey = resolved.apiKey;
@@ -139,6 +161,7 @@ export async function startRepl(opts = {}) {
         try {
             process.stdout.write('\x1b[?1049h\x1b[?25l'); // alt screen + hide cursor
             process.stdout.write('\x1b[H\x1b[2J'); // home + clear
+            process.stdout.write(MOUSE_ENABLE); // wheel events (SGR), see tui/mouse.ts
         }
         catch { /* ignore */ }
     };
@@ -146,10 +169,45 @@ export async function startRepl(opts = {}) {
         if (!isAltScreen)
             return;
         try {
+            process.stdout.write(MOUSE_DISABLE);
             process.stdout.write('\x1b[?25h\x1b[?1049l'); // show cursor + leave alt
         }
         catch { /* ignore */ }
     };
+    // OpenCode-style wheel scrolling (§8.5, S8): Ink owns stdin and cannot see
+    // mouse events, so tap stdin.emit — wheel deltas drive the App's scroll
+    // hooks, everything else passes through to Ink untouched.
+    const mouseFilter = new MouseFilter();
+    const origStdinEmit = process.stdin.emit.bind(process.stdin);
+    let mouseTapInstalled = false;
+    function installMouseTap() {
+        if (!isAltScreen || mouseTapInstalled)
+            return;
+        mouseTapInstalled = true;
+        process.stdin.emit = (...a) => {
+            if (a[0] === 'data' && Buffer.isBuffer(a[1])) {
+                const split = mouseFilter.push(a[1]);
+                for (const w of split.wheels) {
+                    try {
+                        if (isMounted && directHooks)
+                            directHooks.scrollLines(w);
+                    }
+                    catch { /* ignore */ }
+                }
+                if (split.kept.length === 0)
+                    return false;
+                a[1] = split.kept;
+            }
+            return origStdinEmit(...a);
+        };
+    }
+    function removeMouseTap() {
+        if (!mouseTapInstalled)
+            return;
+        mouseTapInstalled = false;
+        mouseFilter.reset();
+        process.stdin.emit = origStdinEmit;
+    }
     // Declare app before handler to avoid TDZ; handler added after render
     let app;
     let sigintHandler;
@@ -178,12 +236,10 @@ export async function startRepl(opts = {}) {
             if (consoleRing.length > 200)
                 consoleRing.splice(0, consoleRing.length - 200);
             try {
-                const fs = require('node:fs');
-                const path = require('node:path');
                 const home = process.env.HOME ?? process.env.USERPROFILE ?? cwd;
-                const dir = path.join(home, '.klyro');
-                fs.mkdirSync(dir, { recursive: true });
-                fs.appendFileSync(path.join(dir, 'debug.log'), line + '\n');
+                const dir = nodePath.join(home, '.klyro');
+                fsSync.mkdirSync(dir, { recursive: true });
+                fsSync.appendFileSync(nodePath.join(dir, 'debug.log'), line + '\n');
             }
             catch { /* ignore */ }
         };
@@ -201,7 +257,22 @@ export async function startRepl(opts = {}) {
         console.debug = origConsoleFns.debug;
     }
     patchConsole();
+    installMouseTap();
     const EFFORT_STEPS = { low: 10, medium: 30, high: 50, max: 100 };
+    // Persisted provider settings: /model /provider write through to
+    // ~/.klyro/settings.json so new terminals inherit them. Touch flags keep
+    // /reload from clobbering explicit in-session switches.
+    let modelTouched = false;
+    let providerTouched = false;
+    async function persistProviderPatch(patch) {
+        try {
+            const { loadConfig, saveConfig } = await import('./config.js');
+            const cfg = await loadConfig();
+            Object.assign(cfg, patch);
+            await saveConfig(cfg);
+        }
+        catch { /* best-effort */ }
+    }
     // P1 session/permission state (commands.md Priority 1)
     let sessionLabel = '';
     let currentBranch = '';
@@ -238,10 +309,8 @@ export async function startRepl(opts = {}) {
     catch { /* best-effort */ }
     function persistMap(file, m) {
         try {
-            const fs = require('node:fs');
-            const path = require('node:path');
-            fs.mkdirSync(path.dirname(file), { recursive: true });
-            fs.writeFileSync(file, JSON.stringify(Object.fromEntries(m), null, 2), 'utf-8');
+            fsSync.mkdirSync(nodePath.dirname(file), { recursive: true });
+            fsSync.writeFileSync(file, JSON.stringify(Object.fromEntries(m), null, 2), 'utf-8');
         }
         catch { /* best-effort */ }
     }
@@ -766,8 +835,10 @@ export async function startRepl(opts = {}) {
                 }
                 else {
                     queuedStatus({ model: next });
-                    queuedAppend({ id: `mdl2-${Date.now()}`, kind: 'text', text: `model switched to ${next} (takes effect on next prompt)`, role: 'assistant' });
+                    queuedAppend({ id: `mdl2-${Date.now()}`, kind: 'text', text: `model switched to ${next} (saved — new terminals inherit it)`, role: 'assistant' });
                     model = next;
+                    modelTouched = true;
+                    await persistProviderPatch({ model: next });
                 }
                 return;
             }
@@ -785,7 +856,9 @@ export async function startRepl(opts = {}) {
                     }
                     currentProvider = next;
                     adapter = buildAdapter(currentProvider, currentBaseUrl, currentApiKey);
-                    queuedAppend({ id: `prov2-${Date.now()}`, kind: 'text', text: `provider switched to ${next} (takes effect on next prompt)`, role: 'assistant' });
+                    providerTouched = true;
+                    await persistProviderPatch({ provider: next });
+                    queuedAppend({ id: `prov2-${Date.now()}`, kind: 'text', text: `provider switched to ${next} (saved — new terminals inherit it)`, role: 'assistant' });
                 }
                 return;
             }
@@ -806,9 +879,15 @@ export async function startRepl(opts = {}) {
                 return;
             }
             case 'login': {
-                const { runLogin } = await import('./auth.js');
-                const code = await runLogin();
-                queuedAppend({ id: `login-${Date.now()}`, kind: 'text', text: code === 0 ? 'login saved (0600)' : 'login failed', role: 'assistant' });
+                // NOTE: readline login cannot run inside the TUI (Ink owns stdin —
+                // prompts would garble). Secrets must also never echo into the
+                // transcript, so login lives outside: run it once, /reload picks it up.
+                queuedAppend({
+                    id: `login-${Date.now()}`,
+                    kind: 'text',
+                    text: 'To sign in, run `klyro login` in any terminal (asks once, saves for all terminals), then /reload here.\n(Interactive prompts cannot run inside the TUI — Ink owns stdin.)',
+                    role: 'assistant',
+                });
                 return;
             }
             case 'logout': {
@@ -1984,11 +2063,37 @@ export async function startRepl(opts = {}) {
             }
             case 'reload': {
                 try {
+                    // Re-resolve the provider so `klyro login` (or config edits) in
+                    // another terminal take effect here. Explicit in-session switches
+                    // (/model, /provider) are never clobbered.
+                    const fresh = await resolveProvider();
+                    const notes = [];
+                    if (fresh) {
+                        if (!modelTouched && fresh.model && fresh.model !== model) {
+                            model = fresh.model;
+                            queuedStatus({ model });
+                            notes.push(`model → ${model}`);
+                        }
+                        if (!providerTouched) {
+                            const { inferProviderFromBaseURL: infer } = await import('../agent/registry.js');
+                            const prov = infer(fresh.baseURL);
+                            currentProvider = prov;
+                            currentBaseUrl = fresh.baseURL;
+                            currentApiKey = fresh.apiKey;
+                            adapter = buildAdapter(currentProvider, currentBaseUrl, currentApiKey);
+                            notes.push(`provider → ${prov} (${fresh.baseURL}, ${fresh.source})`);
+                        }
+                    }
                     const ctx = await buildLevel6Context({ cwd });
                     ctxPrefix = ctx.formatted ? `\n\n<context>\n${ctx.formatted}\n</context>` : '';
                     const md = await import('../context/klyro-md.js').then((m) => m.loadKlyroMd(cwd)).catch(() => '');
                     klyroBlock = md ? `\n\n<KLYRO.md>\n${md.slice(0, 4000)}\n</KLYRO.md>` : '';
-                    queuedAppend({ id: `reload-${Date.now()}`, kind: 'text', text: 'reloaded project context + KLYRO.md', role: 'assistant' });
+                    queuedAppend({
+                        id: `reload-${Date.now()}`,
+                        kind: 'text',
+                        text: notes.length > 0 ? `reloaded: ${notes.join(', ')} + project context + KLYRO.md` : 'reloaded project context + KLYRO.md (provider unchanged)',
+                        role: 'assistant',
+                    });
                 }
                 catch (err) {
                     queuedAppend({ id: `reload-err-${Date.now()}`, kind: 'error', message: String(err) });
@@ -2159,6 +2264,7 @@ export async function startRepl(opts = {}) {
                 process.removeListener('SIGTERM', sigintHandler);
             }
             restoreConsole();
+            removeMouseTap();
             leaveAlt();
             // §1.2 exit behavior: replay a plain-text transcript into the main
             // buffer so the session survives in native scrollback.

package/dist/cli/setup.d.ts

@@ -0,0 +1,23 @@
+/**
+ * First-run setup — "set once, works in every terminal".
+ *
+ * When Klyro starts with no provider anywhere (no env, no saved config, no
+ * stored keys, no local server), the TUI asks for provider details ONCE via
+ * readline (stdin is free — the Ink App is not mounted yet), persists them
+ * to ~/.klyro/settings.json + ~/.klyro/credentials.json (0600), and startup
+ * continues. The next terminal never asks again; changes happen explicitly
+ * via /provider, /model, `klyro login`, or `klyro config`.
+ *
+ * The `ask` callback is injected so this is unit-testable without a TTY.
+ */
+export interface SetupAnswers {
+    provider: 'openai' | 'anthropic';
+    baseUrl: string;
+    model: string;
+    keySaved: boolean;
+}
+/**
+ * Run the interactive setup. Returns answers, or null if the user aborted
+ * (empty provider choice) — the caller should exit(2) in that case.
+ */
+export declare function runFirstRunSetup(ask: (question: string) => Promise<string>): Promise<SetupAnswers | null>;

package/dist/cli/setup.js

@@ -0,0 +1,49 @@
+/**
+ * First-run setup — "set once, works in every terminal".
+ *
+ * When Klyro starts with no provider anywhere (no env, no saved config, no
+ * stored keys, no local server), the TUI asks for provider details ONCE via
+ * readline (stdin is free — the Ink App is not mounted yet), persists them
+ * to ~/.klyro/settings.json + ~/.klyro/credentials.json (0600), and startup
+ * continues. The next terminal never asks again; changes happen explicitly
+ * via /provider, /model, `klyro login`, or `klyro config`.
+ *
+ * The `ask` callback is injected so this is unit-testable without a TTY.
+ */
+import { LOGIN_DEFAULTS, saveKey } from './auth.js';
+import { loadConfig, saveConfig } from './config.js';
+import { assertSafeBaseURL } from '../chat.js';
+/**
+ * Run the interactive setup. Returns answers, or null if the user aborted
+ * (empty provider choice) — the caller should exit(2) in that case.
+ */
+export async function runFirstRunSetup(ask) {
+    const choiceRaw = await ask('No provider configured (one-time setup — saved for all terminals).\nProvider [1=openai-compatible, 2=anthropic, 3=local Ollama] [1]: ');
+    const choice = choiceRaw.trim() || '1';
+    if (choice !== '1' && choice !== '2' && choice !== '3')
+        return null;
+    const name = choice === '2' ? 'anthropic' : choice === '3' ? 'local' : 'openai';
+    const defs = LOGIN_DEFAULTS[name] ?? LOGIN_DEFAULTS.openai;
+    const key = await ask(name === 'local' ? 'API key (empty = none needed for local): ' : 'API key (paste, stored 0600): ');
+    if (!key.trim() && name !== 'local')
+        return null;
+    const baseRaw = await ask(`Base URL [${defs.baseUrl}]: `);
+    const baseUrl = (baseRaw.trim() || defs.baseUrl).trim();
+    try {
+        assertSafeBaseURL(baseUrl);
+    }
+    catch {
+        return null;
+    }
+    const modelRaw = await ask(`Model [${defs.model}]: `);
+    const model = (modelRaw.trim() || defs.model).trim();
+    const storeProvider = name === 'local' ? 'openai' : name;
+    if (key.trim())
+        await saveKey(storeProvider, key);
+    const cfg = await loadConfig();
+    cfg.provider = storeProvider;
+    cfg.baseUrl = baseUrl;
+    cfg.model = model;
+    await saveConfig(cfg);
+    return { provider: storeProvider, baseUrl, model, keySaved: key.trim().length > 0 };
+}

package/dist/providers.d.ts

@@ -15,9 +15,21 @@ export interface ProviderConfig {
     baseURL: string;
     apiKey: string;
     model: string;
-    source: 'env' | 'local-probe' | 'manual';
+    source: 'env' | 'config' | 'local-probe' | 'manual';
 }
-/** Resolve which provider to use. Does not throw; returns `null` if nothing is reachable. */
+/**
+ * Resolve which provider to use. Does not throw; returns `null` if nothing
+ * is reachable.
+ *
+ * Precedence (later lines are fallbacks, earlier wins):
+ *   1. KLYRO_BASE_URL env (+ KLYRO_API_KEY / KLYRO_MODEL)
+ *   2. Persisted config (~/.klyro/settings.json: baseUrl, provider, model,
+ *      apiKey) + stored credentials (~/.klyro/credentials.json) — set once
+ *      via `klyro login` or first-run setup, applies to ALL terminals.
+ *   3. KLYRO_API_KEY env alone (OpenAI default)
+ *   4. Stored credential keys alone (provider inferred from which key exists)
+ *   5. Local endpoint probe (Ollama / LM Studio / vLLM / llama.cpp)
+ */
 export declare function resolveProvider(): Promise<ProviderConfig | null>;
 /** Pretty-print a hint about how to configure the provider. */
 export declare function providerHelp(p: ProviderConfig | null): string;

package/dist/providers.js

@@ -18,7 +18,19 @@ const LOCAL_ENDPOINTS = [
     { name: 'vLLM', baseURL: 'http://localhost:8000/v1', defaultModel: 'meta-llama/Llama-3-8B-Instruct' },
     { name: 'llama.cpp', baseURL: 'http://localhost:8080/v1', defaultModel: 'local-model' },
 ];
-/** Resolve which provider to use. Does not throw; returns `null` if nothing is reachable. */
+/**
+ * Resolve which provider to use. Does not throw; returns `null` if nothing
+ * is reachable.
+ *
+ * Precedence (later lines are fallbacks, earlier wins):
+ *   1. KLYRO_BASE_URL env (+ KLYRO_API_KEY / KLYRO_MODEL)
+ *   2. Persisted config (~/.klyro/settings.json: baseUrl, provider, model,
+ *      apiKey) + stored credentials (~/.klyro/credentials.json) — set once
+ *      via `klyro login` or first-run setup, applies to ALL terminals.
+ *   3. KLYRO_API_KEY env alone (OpenAI default)
+ *   4. Stored credential keys alone (provider inferred from which key exists)
+ *   5. Local endpoint probe (Ollama / LM Studio / vLLM / llama.cpp)
+ */
 export async function resolveProvider() {
     const envBaseURL = process.env.KLYRO_BASE_URL;
     const envKey = process.env.KLYRO_API_KEY;
@@ -32,6 +44,62 @@ export async function resolveProvider() {
             source: 'env',
         };
     }
+    // Persisted config — the "set once, works in every terminal" layer.
+    try {
+        const { loadMergedConfig } = await import('./cli/config.js');
+        const { getStoredKey } = await import('./cli/auth.js');
+        const cfg = await loadMergedConfig(process.cwd(), {});
+        const cfgBase = (cfg.baseUrl ?? cfg.baseURL);
+        const cfgProvider = cfg.provider;
+        const cfgModel = (cfg.model ?? cfg['model.default']);
+        const cfgKey = (cfg.apiKey ?? cfg.api_key);
+        if (cfgBase) {
+            assertSafeBaseURL(cfgBase);
+            const key = envKey ?? cfgKey ?? getStoredKey(cfgProvider ?? 'openai') ?? getStoredKey('openai') ?? getStoredKey('anthropic') ?? '';
+            return {
+                baseURL: normalizeBaseURL(cfgBase),
+                apiKey: key,
+                model: envModel ?? cfgModel ?? 'gpt-4o-mini',
+                source: 'config',
+            };
+        }
+        if (cfgKey) {
+            return {
+                baseURL: normalizeBaseURL('https://api.openai.com/v1'),
+                apiKey: cfgKey,
+                model: envModel ?? cfgModel ?? 'gpt-4o-mini',
+                source: 'config',
+            };
+        }
+        // Stored keys alone (e.g. `klyro login` with defaults, or key-only setup).
+        const anthropicKey = getStoredKey('anthropic');
+        const openaiKey = getStoredKey('openai');
+        if (cfgProvider === 'anthropic' && anthropicKey) {
+            return {
+                baseURL: normalizeBaseURL('https://api.anthropic.com/v1'),
+                apiKey: anthropicKey,
+                model: envModel ?? cfgModel ?? 'claude-3-5-sonnet-20240620',
+                source: 'config',
+            };
+        }
+        if (openaiKey) {
+            return {
+                baseURL: normalizeBaseURL('https://api.openai.com/v1'),
+                apiKey: openaiKey,
+                model: envModel ?? cfgModel ?? 'gpt-4o-mini',
+                source: 'config',
+            };
+        }
+        if (anthropicKey) {
+            return {
+                baseURL: normalizeBaseURL('https://api.anthropic.com/v1'),
+                apiKey: anthropicKey,
+                model: envModel ?? cfgModel ?? 'claude-3-5-sonnet-20240620',
+                source: 'config',
+            };
+        }
+    }
+    catch { /* corrupted config must not break startup; probe below */ }
     if (envKey) {
         return {
             baseURL: normalizeBaseURL('https://api.openai.com/v1'),
@@ -43,12 +111,25 @@ export async function resolveProvider() {
     // Probe local endpoints
     for (const ep of LOCAL_ENDPOINTS) {
         if (await probeLocal(ep.baseURL)) {
-            return {
-                baseURL: ep.baseURL,
-                apiKey: '',
-                model: envModel ?? ep.defaultModel,
-                source: 'local-probe',
-            };
+            try {
+                const { loadMergedConfig } = await import('./cli/config.js');
+                const cfg = await loadMergedConfig(process.cwd(), {});
+                const cfgModel = (cfg.model ?? cfg['model.default']);
+                return {
+                    baseURL: ep.baseURL,
+                    apiKey: '',
+                    model: envModel ?? cfgModel ?? ep.defaultModel,
+                    source: 'local-probe',
+                };
+            }
+            catch {
+                return {
+                    baseURL: ep.baseURL,
+                    apiKey: '',
+                    model: envModel ?? ep.defaultModel,
+                    source: 'local-probe',
+                };
+            }
         }
     }
     return null;
@@ -80,5 +161,8 @@ export function providerHelp(p) {
     if (p?.source === 'env') {
         return `(env: ${p.baseURL}, model: ${p.model})`;
     }
-    return `(no provider configured — set KLYRO_BASE_URL + KLYRO_API_KEY, or run a local server like Ollama)`;
+    if (p?.source === 'config') {
+        return `(saved: ${p.baseURL}, model: ${p.model} — change via /provider /model or klyro config)`;
+    }
+    return `(no provider configured — run klyro login once, or set KLYRO_BASE_URL + KLYRO_API_KEY, or run a local server like Ollama)`;
 }

package/dist/tui/app.d.ts

@@ -22,6 +22,8 @@ export interface AppProps {
         updateStatus: (s: Partial<StatusSnapshot>) => void;
         updatePlan: (p: PlanStep[]) => void;
         clearTranscript: () => void;
+        scrollLines: (delta: number) => void;
+        scrollToBottom: () => void;
     }) => void;
     version?: string;
     isFullscreen?: boolean;

package/dist/tui/app.js

@@ -201,6 +201,8 @@ export function App(props) {
         setHistory((prev) => (prev[prev.length - 1] === v ? prev : [...prev.slice(-99), v]));
         setHistIdx(null);
     }, []);
+    // Live scroll control for external drivers (mouse-wheel tap in repl.ts).
+    const scrollCmdsRef = useRef({ line: (_d) => { }, bottom: () => { } });
     const width = stdout?.columns ?? 100;
     const height = stdout?.rows ?? 30;
     const isFullscreen = props.isFullscreen ?? false;
@@ -318,6 +320,19 @@ export function App(props) {
         }
     }
     const visibleGrouped = isFullscreen && !tiny ? grouped.slice(gi0, gi1 + 1) : grouped;
+    // Publish live scroll control for the mouse-wheel tap (stable callbacks, latest ctx).
+    scrollCmdsRef.current = {
+        line: (d) => {
+            const n = Math.abs(Math.round(d));
+            for (let i = 0; i < n; i++) {
+                if (d < 0)
+                    commands.lineUp();
+                else
+                    commands.lineDown();
+            }
+        },
+        bottom: () => commands.jumpBottom(),
+    };
     useEffect(() => bridge.subscribe((p) => setAwaitingApproval(p !== null)), [bridge]);
     useEffect(() => {
         if (queuedInputs.length > 0 && status.status !== 'running' && !awaitingApproval) {
@@ -354,9 +369,13 @@ export function App(props) {
     const updateStatus = useCallback((s) => setStatus((p) => ({ ...p, ...s })), []);
     const updatePlan = useCallback((p) => setPlan(p), []);
     const clearTranscript = useCallback(() => { streamingIdRef.current = null; setTranscript([]); setPlan([]); }, []);
+    // Scroll control for external drivers (mouse-wheel tap in repl.ts, §8.4).
+    // Stored in refs so the callbacks stay stable while acting on latest state.
+    const scrollLines = useCallback((delta) => { scrollCmdsRef.current.line(delta); }, []);
+    const scrollToBottom = useCallback(() => { scrollCmdsRef.current.bottom(); }, []);
     const onMountedRef = useRef(props.onMounted);
     useEffect(() => { onMountedRef.current = props.onMounted; }, [props.onMounted]);
-    useEffect(() => { onMountedRef.current?.({ append, appendDelta, updateStatus, updatePlan, clearTranscript }); globalThis.__klyroAppAppend = append; globalThis.__klyroAppendDelta = appendDelta; globalThis.__klyroAppStatus = updateStatus; globalThis.__klyroAppPlan = updatePlan; return () => { delete globalThis.__klyroAppAppend; delete globalThis.__klyroAppendDelta; delete globalThis.__klyroAppStatus; delete globalThis.__klyroAppPlan; }; }, [append, appendDelta, updateStatus, updatePlan, clearTranscript]);
+    useEffect(() => { onMountedRef.current?.({ append, appendDelta, updateStatus, updatePlan, clearTranscript, scrollLines, scrollToBottom }); globalThis.__klyroAppAppend = append; globalThis.__klyroAppendDelta = appendDelta; globalThis.__klyroAppStatus = updateStatus; globalThis.__klyroAppPlan = updatePlan; return () => { delete globalThis.__klyroAppAppend; delete globalThis.__klyroAppendDelta; delete globalThis.__klyroAppStatus; delete globalThis.__klyroAppPlan; }; }, [append, appendDelta, updateStatus, updatePlan, clearTranscript, scrollLines, scrollToBottom]);
     const toggleGroup = (id) => setExpandedGroups((prev) => { const n = new Set(prev); if (n.has(id))
         n.delete(id);
     else
@@ -390,11 +409,11 @@ export function App(props) {
                 commands.jumpBottom();
                 return;
             } // Ctrl+G → bottom (§8.4)
-            if (key.pageUp || (key.ctrl && inputStr === 'u')) {
+            if (key.pageUp || (key.ctrl && inputStr === 'u') || (key.ctrl && inputStr === 'b')) {
                 commands.pageUp();
                 return;
             }
-            if (key.pageDown || (key.ctrl && inputStr === 'd')) {
+            if (key.pageDown || (key.ctrl && inputStr === 'd') || (key.ctrl && inputStr === 'f')) {
                 commands.pageDown();
                 return;
             }

package/dist/tui/app.test.js

@@ -249,6 +249,25 @@ describe('App', () => {
         await new Promise((r) => setTimeout(r, 100));
         expect(lastFrame() ?? '').toMatch(/LATE-1-tag/);
     });
+    it('onMounted scrollLines/scrollToBottom drive the viewport (wheel path)', async () => {
+        let captured = null;
+        const { lastFrame } = render(_jsx(App, { initialModel: "m", maxSteps: 10, cwd: "/test", onPrompt: async () => { }, onSlash: async () => { }, isFullscreen: true, initialTranscript: makeInitialTranscript(25), onMounted: (h) => {
+                captured = { scrollLines: h.scrollLines, scrollToBottom: h.scrollToBottom };
+            } }));
+        await new Promise((r) => setTimeout(r, 50));
+        expect(captured).not.toBeNull();
+        // Wheel up ×12 (3 lines each = 36 > maxTop 32) → pinned at top.
+        for (let i = 0; i < 12; i++)
+            captured.scrollLines(-3);
+        await new Promise((r) => setTimeout(r, 50));
+        const top = lastFrame() ?? '';
+        expect(top).toMatch(/MSG-00-tag/);
+        expect(top).not.toMatch(/MSG-24-tag/);
+        // scrollToBottom → tail visible again.
+        captured.scrollToBottom();
+        await new Promise((r) => setTimeout(r, 50));
+        expect(lastFrame() ?? '').toMatch(/MSG-24-tag/);
+    });
     it('Shift+Up / Shift+Down scroll by one line', async () => {
         const { stdin, lastFrame } = render(_jsx(App, { initialModel: "m", maxSteps: 10, cwd: "/test", onPrompt: async () => { }, onSlash: async () => { }, isFullscreen: true, initialTranscript: makeInitialTranscript(25) }));
         await new Promise((r) => setTimeout(r, 50));

package/dist/tui/mouse.d.ts

@@ -0,0 +1,36 @@
+/**
+ * scroll.md §8.5 (S8) — mouse wheel capture for OpenCode-style scrolling.
+ *
+ * Ink owns stdin via useInput and cannot see mouse events, so the REPL wraps
+ * `process.stdin.emit` with this stateful splitter: SGR/X10 mouse sequences
+ * are swallowed (wheel → scroll deltas, clicks/motion → dropped), everything
+ * else passes through to Ink untouched.
+ *
+ * Only the wheel is acted on. Clicks are swallowed (not forwarded) because a
+ * mouse-reporting terminal would otherwise deliver them to readline as typed
+ * garbage; Shift+drag still selects natively in most terminals.
+ *
+ * Sequences handled:
+ *   SGR: `\x1b[<Cb;x;yM` / `...m`  (1006, requested via `CSI ? 1006 h`)
+ *   X10: `\x1b[M Cb Cx Cy`         (fallback for terminals ignoring 1006)
+ * Wheel bit is 64 in both; direction bit is 1 (down) — modifiers OR into Cb.
+ */
+export declare const WHEEL_LINES = 3;
+export interface MouseSplit {
+    /** bytes Ink is still allowed to see */
+    kept: Buffer;
+    /** wheel deltas: negative = up (older), positive = down (newer) */
+    wheels: number[];
+}
+export declare class MouseFilter {
+    private pending;
+    /**
+     * Split one stdin chunk. Holds an unambiguous trailing partial mouse
+     * sequence for the next chunk; a lone trailing ESC passes through
+     * immediately so the Esc key (queued-drop) never lags.
+     */
+    push(chunk: Buffer): MouseSplit;
+    reset(): void;
+}
+export declare const MOUSE_ENABLE = "\u001B[?1000h\u001B[?1006h";
+export declare const MOUSE_DISABLE = "\u001B[?1000l\u001B[?1006l";

package/dist/tui/mouse.js

@@ -0,0 +1,94 @@
+/**
+ * scroll.md §8.5 (S8) — mouse wheel capture for OpenCode-style scrolling.
+ *
+ * Ink owns stdin via useInput and cannot see mouse events, so the REPL wraps
+ * `process.stdin.emit` with this stateful splitter: SGR/X10 mouse sequences
+ * are swallowed (wheel → scroll deltas, clicks/motion → dropped), everything
+ * else passes through to Ink untouched.
+ *
+ * Only the wheel is acted on. Clicks are swallowed (not forwarded) because a
+ * mouse-reporting terminal would otherwise deliver them to readline as typed
+ * garbage; Shift+drag still selects natively in most terminals.
+ *
+ * Sequences handled:
+ *   SGR: `\x1b[<Cb;x;yM` / `...m`  (1006, requested via `CSI ? 1006 h`)
+ *   X10: `\x1b[M Cb Cx Cy`         (fallback for terminals ignoring 1006)
+ * Wheel bit is 64 in both; direction bit is 1 (down) — modifiers OR into Cb.
+ */
+export const WHEEL_LINES = 3; // scroll.md §8.4: wheel = ±3 lines
+function isDigit(b) {
+    return b >= 0x30 && b <= 0x39;
+}
+export class MouseFilter {
+    pending = Buffer.alloc(0);
+    /**
+     * Split one stdin chunk. Holds an unambiguous trailing partial mouse
+     * sequence for the next chunk; a lone trailing ESC passes through
+     * immediately so the Esc key (queued-drop) never lags.
+     */
+    push(chunk) {
+        const buf = Buffer.concat([this.pending, chunk]);
+        this.pending = Buffer.alloc(0);
+        const kept = [];
+        const wheels = [];
+        let i = 0;
+        const n = buf.length;
+        while (i < n) {
+            // SGR mouse: ESC [ < Cb ; x ; y (M|m)
+            if (buf[i] === 0x1b && i + 2 < n && buf[i + 1] === 0x5b && buf[i + 2] === 0x3c) {
+                let j = i + 3;
+                while (j < n && (isDigit(buf[j]) || buf[j] === 0x3b))
+                    j++;
+                if (j >= n) {
+                    // split across chunks — hold for more data
+                    this.pending = buf.subarray(i);
+                    break;
+                }
+                const term = buf[j];
+                if (term === 0x4d || term === 0x6d) {
+                    const cb = parseInt(buf.subarray(i + 3, j).toString().split(';')[0] ?? 'NaN', 10);
+                    if (!Number.isNaN(cb) && (cb & 64) !== 0) {
+                        wheels.push((cb & 1) === 0 ? -WHEEL_LINES : WHEEL_LINES);
+                    }
+                    i = j + 1; // swallow (wheel or click/motion)
+                    continue;
+                }
+                // ESC [ < not followed by digits→M/m: not a mouse seq, pass ESC through
+                kept.push(buf.subarray(i, i + 1));
+                i++;
+                continue;
+            }
+            // X10 mouse: ESC [ M Cb Cx Cy
+            if (buf[i] === 0x1b && i + 2 < n && buf[i + 1] === 0x5b && buf[i + 2] === 0x4d) {
+                if (i + 5 >= n) {
+                    this.pending = buf.subarray(i); // split across chunks
+                    break;
+                }
+                const cb = buf[i + 3] - 32;
+                if ((cb & 64) !== 0) {
+                    wheels.push((cb & 1) === 0 ? -WHEEL_LINES : WHEEL_LINES);
+                }
+                i += 6; // swallow
+                continue;
+            }
+            // Trailing partial that could ONLY be a split SGR/X10 start: hold it.
+            // A lone trailing ESC passes through (Esc key must not lag).
+            const tail = n - i;
+            if (tail <= 5) {
+                const rest = buf.subarray(i).toString('latin1');
+                if (/^\x1b\[<$/.test(rest) || /^\x1b\[<[\d;]+$/.test(rest) || /^\x1b\[M.{0,2}$/.test(rest)) {
+                    this.pending = buf.subarray(i);
+                    break;
+                }
+            }
+            kept.push(buf.subarray(i, i + 1));
+            i++;
+        }
+        return { kept: Buffer.concat(kept), wheels };
+    }
+    reset() {
+        this.pending = Buffer.alloc(0);
+    }
+}
+export const MOUSE_ENABLE = '\x1b[?1000h\x1b[?1006h'; // button events + SGR coords
+export const MOUSE_DISABLE = '\x1b[?1000l\x1b[?1006l';

package/dist/tui/scroll-flow.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tui/scroll-flow.test.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * scroll.md diagnostic: realistic session flow — seed history, stream a long
+ * answer in chunks (like provider deltas), scroll mid-stream, stream more.
+ * Asserts the chat-flow invariants the user actually sees:
+ *   - follow-tail: latest streamed text visible while at bottom
+ *   - freeze: pinned viewport doesn't move while streaming
+ *   - badge counts new lines
+ *   - frame never exceeds terminal rows (I1)
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from 'ink-testing-library';
+import { App } from './app.js';
+const PROPS = {
+    initialModel: 'm',
+    maxSteps: 10,
+    cwd: '/test',
+    onPrompt: async () => { },
+    onSlash: async () => { },
+};
+const g = globalThis;
+const tick = (ms = 30) => new Promise((r) => setTimeout(r, ms));
+const rowsOf = (frame) => frame.split('\n').length;
+function seed(n) {
+    return Array.from({ length: n }, (_, i) => ({
+        id: `seed-${i}`,
+        kind: 'text',
+        text: `MSG-${i.toString().padStart(2, '0')}-tag`,
+        role: 'user',
+    }));
+}
+describe('scroll flow diagnostics', () => {
+    it('reports terminal geometry (debug aid)', async () => {
+        const { lastFrame } = render(_jsx(App, { ...PROPS, isFullscreen: true }));
+        await tick(50);
+        const frame = lastFrame() ?? '';
+        // eslint-disable-next-line no-console
+        console.log(`[diag] frame rows=${rowsOf(frame)} cols~${(frame.split('\n')[0] ?? '').length}`);
+        expect(rowsOf(frame)).toBeLessThanOrEqual(32);
+    });
+    it('follow-tail: streamed long answer stays visible, frame stays bounded', async () => {
+        const { lastFrame } = render(_jsx(App, { ...PROPS, isFullscreen: true, initialTranscript: seed(5) }));
+        await tick(50);
+        g.__klyroAppStatus({ status: 'running' });
+        const chunk = 'STREAMCHUNK lorem ipsum dolor sit amet. ';
+        for (let i = 0; i < 12; i++) {
+            g.__klyroAppendDelta(`${chunk}#${i} `);
+            await tick(40);
+            const frame = lastFrame() ?? '';
+            expect(rowsOf(frame)).toBeLessThanOrEqual(32);
+            // latest streamed chunk must be visible (follow-tail)
+            expect(frame).toContain(`#${i}`);
+        }
+    });
+    it('freeze: pinned top survives streaming, badge counts, End restores', async () => {
+        const { stdin, lastFrame } = render(_jsx(App, { ...PROPS, isFullscreen: true, initialTranscript: seed(40) }));
+        await tick(100);
+        stdin.write('\x1b[H'); // Home → top
+        await tick(50);
+        const top = lastFrame() ?? '';
+        expect(top).toContain('MSG-00-tag');
+        g.__klyroAppStatus({ status: 'running' });
+        for (let i = 0; i < 5; i++) {
+            g.__klyroAppendDelta(`late chunk number ${i} with filler words here. `);
+            await tick(40);
+        }
+        const frozen = lastFrame() ?? '';
+        expect(frozen).toContain('MSG-00-tag'); // viewport did not yank down
+        expect(frozen).toMatch(/↓ \d+ new/); // badge visible
+        expect(rowsOf(frozen)).toBeLessThanOrEqual(32);
+        stdin.write('\x1b[F'); // End → follow
+        await tick(50);
+        expect(lastFrame() ?? '').toContain('number 4');
+    });
+    it('wrapped long item: pin mid-item, stream, same first line stays', async () => {
+        const long = Array.from({ length: 10 }, (_, i) => `WRAPLINE-${i} ` + 'x'.repeat(180)).join('\n');
+        const items = [
+            { id: 'w1', kind: 'text', text: long, role: 'assistant' },
+            ...seed(30),
+        ];
+        const { stdin, lastFrame } = render(_jsx(App, { ...PROPS, isFullscreen: true, initialTranscript: items }));
+        await tick(100);
+        stdin.write('\x1b[H');
+        await tick(50);
+        const before = (lastFrame() ?? '').split('\n').slice(0, 3).join('\n');
+        g.__klyroAppStatus({ status: 'running' });
+        for (let i = 0; i < 5; i++) {
+            g.__klyroAppendDelta(`more streamed text ${i} ` + 'y'.repeat(120));
+            await tick(40);
+        }
+        const after = (lastFrame() ?? '').split('\n').slice(0, 3).join('\n');
+        expect(after).toBe(before); // anchor stability at line granularity
+    });
+});

package/dist/tui/scroll-model.js

@@ -22,10 +22,13 @@ export function maxTopFor(ctx) {
 function stickBottom() {
     return { anchor: { mode: 'bottom' }, userScrolled: false, newSinceUnstick: 0 };
 }
-function pinAt(s, ctx, row) {
+// FOLLOW_EPSILON is directional: scrolling DOWN into the last line re-sticks
+// to bottom, but scrolling UP must always escape — otherwise single-line /
+// wheel scrolling from the bottom could never leave it (dead scroll trap).
+function pinAt(s, ctx, row, from) {
     const maxTop = maxTopFor(ctx);
     const top = clampN(row, 0, maxTop);
-    if (top >= maxTop - FOLLOW_EPSILON)
+    if (top >= maxTop - FOLLOW_EPSILON && top >= from)
         return stickBottom();
     if (ctx.count === 0)
         return stickBottom();
@@ -42,13 +45,13 @@ export function scrollReducer(s, a, ctx) {
     const cur = resolveTopRow(s, ctx).topRow;
     switch (a.type) {
         case 'BY_LINES':
-            return pinAt(s, ctx, cur + a.delta);
+            return pinAt(s, ctx, cur + a.delta, cur);
         case 'BY_PAGE':
-            return pinAt(s, ctx, cur + a.dir * (ctx.viewportH - 1)); // 1-line overlap
+            return pinAt(s, ctx, cur + a.dir * (ctx.viewportH - 1), cur); // 1-line overlap
         case 'BY_HALF_PAGE':
-            return pinAt(s, ctx, cur + a.dir * Math.floor(ctx.viewportH / 2));
+            return pinAt(s, ctx, cur + a.dir * Math.floor(ctx.viewportH / 2), cur);
         case 'TO_TOP':
-            return pinAt(s, ctx, 0);
+            return pinAt(s, ctx, 0, cur);
         case 'TO_BOTTOM':
             return stickBottom();
         case 'CONTENT_GREW':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klyro",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "description": "Klyro \u2014 autonomous coding harness CLI that streams from any OpenAI-compatible or Anthropic LLM endpoint.",
   "type": "module",
   "main": "dist/index.js",