klyro 1.0.14 → 1.0.17

package/dist/cli/doctor.js

@@ -6,7 +6,7 @@
 import * as fs from 'node:fs/promises';
 import * as fsSync from 'node:fs';
 import * as path from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, execFileSync } from 'node:child_process';
 import { getConfigPath, loadConfig } from './config.js';
 import { resolveProvider, providerHelp } from '../providers.js';
 import { getDefaultSessionsDir } from '../persistence/session.js';
@@ -120,6 +120,45 @@ async function checkSandbox() {
         return { name: 'Sandbox', ok: true, detail: 'none — policy+path guards only' };
     }
 }
+function checkPackageManager() {
+    try {
+        const npm = execFileSync('npm', ['--version'], { encoding: 'utf-8', timeout: 5000 }).trim();
+        return { name: 'npm', ok: true, detail: `npm ${npm} ✓` };
+    }
+    catch {
+        return { name: 'npm', ok: false, detail: 'npm not on PATH — install Node ≥20' };
+    }
+}
+function checkPath() {
+    const pathVar = process.env.PATH ?? process.env.Path ?? '';
+    const nodeDir = process.execPath.includes('\\') || process.execPath.includes('/')
+        ? process.execPath.slice(0, Math.max(process.execPath.lastIndexOf('\\'), process.execPath.lastIndexOf('/')))
+        : '';
+    const onPath = !!pathVar && !!nodeDir && pathVar.toLowerCase().split(path.delimiter).some((p) => p.toLowerCase() === nodeDir.toLowerCase());
+    return { name: 'PATH', ok: true, detail: onPath ? `node dir on PATH ✓` : `node dir not on PATH (${nodeDir || 'unknown'}) — child shells may miss node` };
+}
+function checkRipgrep() {
+    try {
+        const v = execFileSync('rg', ['--version'], { encoding: 'utf-8', timeout: 5000 }).trim().split('\n')[0] ?? '';
+        return { name: 'ripgrep', ok: true, detail: `${v} ✓` };
+    }
+    catch {
+        return { name: 'ripgrep', ok: true, detail: 'not found — built-in grep tool is used instead' };
+    }
+}
+function checkTerminal() {
+    const isTTY = !!process.stdout.isTTY;
+    const term = process.env.TERM ?? '(unset)';
+    const cols = process.stdout.columns ?? 0;
+    return { name: 'Terminal', ok: true, detail: `${isTTY ? 'TTY' : 'non-TTY (headless/pipe mode)'}, TERM=${term}, cols=${cols}` };
+}
+function checkProxy() {
+    const vars = ['HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy']
+        .filter((k) => process.env[k] && process.env[k].length > 0);
+    if (vars.length === 0)
+        return { name: 'Proxy', ok: true, detail: 'no proxy env — direct connections' };
+    return { name: 'Proxy', ok: true, detail: `${vars.join(', ')} set — honored for provider/web/update fetches` };
+}
 async function checkMcp(cwd) {
     try {
         const { loadMcpServers } = await import('../mcp/config.js');
@@ -169,14 +208,107 @@ async function checkTrust() {
         return { name: 'Trust stores', ok: true, detail: 'none' };
     }
 }
+/**
+ * Pure byte interpreter for `doctor --keys` (unit-tested): names what a
+ * terminal delivered so broken arrow/paste/scroll input becomes provable
+ * fact instead of guesswork. Covers arrows, paging/home/end, Ctrl codes,
+ * bracketed-paste markers, and SGR/X10 mouse sequences.
+ */
+export function describeKeyBytes(chunk) {
+    const s = chunk.toString('latin1');
+    switch (s) {
+        case '\x1b[A': return 'Up arrow (history prev)';
+        case '\x1b[B': return 'Down arrow (history next)';
+        case '\x1b[C': return 'Right arrow';
+        case '\x1b[D': return 'Left arrow';
+        case '\x1b[5~': return 'PageUp (scroll half-page up)';
+        case '\x1b[6~': return 'PageDown (scroll half-page down)';
+        case '\x1b[H':
+        case '\x1b[1~': return 'Home (jump top)';
+        case '\x1b[F':
+        case '\x1b[4~': return 'End (jump bottom)';
+        case '\x1b[Z': return 'Shift+Tab';
+        case '\r':
+        case '\n': return 'Enter';
+        case '\x7f': return 'Backspace';
+        case '\x1b': return 'Escape (lone — arrow/paste sequences arrive joined; lone ESC means the terminal split them or you pressed Esc)';
+        case '\x1b[200~': return 'Bracketed-paste START (terminal supports bulk paste)';
+        case '\x1b[201~': return 'Bracketed-paste END';
+        case '\x03': return 'Ctrl+C';
+        case '\x10': return 'Ctrl+P (history prev, escape-free)';
+        case '\x0e': return 'Ctrl+N (history next, escape-free)';
+        case '\x15': return 'Ctrl+U (scroll half-page up)';
+        case '\x04': return 'Ctrl+D (scroll half-page down)';
+        case '\x09': return 'Tab';
+    }
+    // eslint-disable-next-line no-control-regex -- intentional: parsing SGR mouse sequences requires ESC matching
+    if (/^\x1b\[<\d+;\d+;\d+[Mm]$/.test(s)) {
+        const cb = Number(s.slice(3).split(';')[0]);
+        return (cb & 64) !== 0
+            ? `Mouse wheel ${(cb & 1) === 0 ? 'up' : 'down'} (reporting active)`
+            : 'Mouse click/drag (reporting active — plain selection needs Shift+drag)';
+    }
+    // eslint-disable-next-line no-control-regex -- intentional: parsing X10 mouse sequences requires ESC matching
+    if (/^\x1b\[M...$/.test(s))
+        return 'Mouse event, X10 encoding (reporting active)';
+    if (/^[\x20-\x7e]+$/.test(s))
+        return `Printable text (${s.length} chars — typing/paste-as-typing works)`;
+    return 'Unrecognized sequence (terminal-specific — paste the bytes line into a bug report)';
+}
+/**
+ * Interactive key probe: raw-mode stdin echo of every chunk with its
+ * meaning. Proves what THIS terminal delivers for arrows, Ctrl+P/N,
+ * paste, and wheel — run it when TUI input misbehaves.
+ */
+export async function runKeysProbe() {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+        process.stderr.write('klyro: doctor --keys needs an interactive terminal (stdin is not a TTY)\n');
+        return 2;
+    }
+    stdout.write('klyro doctor --keys — press keys, see exactly what your terminal sends.\n');
+    stdout.write('Try: ↑ ↓ PgUp PgDn Home End Ctrl+P Ctrl+N, then paste text, then scroll the wheel. Ctrl+C quits.\n');
+    stdin.setRawMode(true);
+    stdin.resume();
+    try {
+        await new Promise((resolve) => {
+            const onData = (chunk) => {
+                const bytes = [...chunk].map((b) => b.toString(16).padStart(2, '0')).join(' ');
+                stdout.write(`bytes: ${bytes}  →  ${describeKeyBytes(chunk)}\n`);
+                if (chunk.length === 1 && chunk[0] === 0x03) {
+                    stdin.off('data', onData);
+                    resolve();
+                }
+            };
+            stdin.on('data', onData);
+        });
+    }
+    finally {
+        try {
+            stdin.setRawMode(false);
+        }
+        catch { /* ignore */ }
+        try {
+            stdin.pause();
+        }
+        catch { /* ignore */ }
+    }
+    return 0;
+}
 export async function runDoctor(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const checks = [];
     checks.push(checkNode());
+    checks.push(checkPackageManager());
+    checks.push(checkPath());
     checks.push(await checkConfig());
     checks.push(await checkProvider());
     checks.push(await checkSessions());
     checks.push(await checkGit());
+    checks.push(checkRipgrep());
+    checks.push(checkTerminal());
+    checks.push(checkProxy());
     checks.push(await checkTools());
     checks.push(checkPlatform());
     checks.push(await checkSandbox());

package/dist/cli/dotenv.d.ts

@@ -1,3 +1,5 @@
 export declare function parseDotenv(text: string): Record<string, string>;
+/** True when a `.env` key would change process behaviour or loosen a boundary. */
+export declare function isBlockedDotenvKey(key: string): boolean;
 /** Load `<cwd>/.env` into `process.env` (no-clobber). Returns loaded keys. */
 export declare function loadDotenv(cwd: string): string[];

package/dist/cli/dotenv.js

@@ -36,6 +36,69 @@ export function parseDotenv(text) {
     }
     return out;
 }
+/**
+ * Process-control variables a repository `.env` must never set.
+ *
+ * `.env` ships WITH the repo, so it is untrusted content, and these keys do
+ * not configure Klyro — they change how the OS and node execute every child
+ * process Klyro spawns (MCP servers, hooks, verify commands, shell_exec),
+ * because children inherit `process.env`:
+ *   - `NODE_OPTIONS=--require ./evil.js` injects a module into every node child
+ *   - `PATH`/`PATHEXT`/`LD_PRELOAD`/`DYLD_*` hijack which binary actually runs
+ *   - `EDITOR`/`VISUAL`/`PAGER` turn `klyro config edit` into a shell execution
+ *   - `npm_config_*` redirects package installs to another registry
+ * Legitimate project config (KLYRO_*, provider keys, tool settings) is
+ * unaffected — only the launcher/process-control namespace is refused.
+ */
+const BLOCKED_DOTENV_KEYS = new Set([
+    'PATH',
+    'PATHEXT',
+    'COMSPEC',
+    'SHELL',
+    'SYSTEMROOT',
+    'WINDIR',
+    'NODE_OPTIONS',
+    'NODE_PATH',
+    'NODE_REPL_EXTERNAL_MODULE',
+    'LD_PRELOAD',
+    'LD_LIBRARY_PATH',
+    'DYLD_INSERT_LIBRARIES',
+    'DYLD_LIBRARY_PATH',
+    'EDITOR',
+    'VISUAL',
+    'PAGER',
+    'GIT_SSH',
+    'GIT_SSH_COMMAND',
+    'GIT_EXTERNAL_DIFF',
+    'GIT_ASKPASS',
+    'SSH_ASKPASS',
+    'BASH_ENV',
+    'PROMPT_COMMAND',
+]);
+/**
+ * Klyro's own de-hardening switches. A repo may not loosen a security
+ * boundary for the person who clones it: these are documented as explicit
+ * user decisions (README "Environment"), so they are refused from `.env`
+ * and must come from the real environment or ~/.klyro/settings.json.
+ */
+const BLOCKED_DOTENV_SECURITY_RELAXATIONS = new Set([
+    'KLYRO_ALLOW_INSECURE',
+    'KLYRO_CREDENTIALS_INSECURE_OK',
+    'KLYRO_ALLOW_MAIN_PUSH',
+    'KLYRO_YES',
+    'KLYRO_WORKER',
+]);
+/** npm reads `npm_config_*` from the environment — a repo must not pick the registry. */
+const BLOCKED_DOTENV_PREFIXES = ['NPM_CONFIG_'];
+/** True when a `.env` key would change process behaviour or loosen a boundary. */
+export function isBlockedDotenvKey(key) {
+    const k = key.toUpperCase();
+    if (BLOCKED_DOTENV_KEYS.has(k))
+        return true;
+    if (BLOCKED_DOTENV_SECURITY_RELAXATIONS.has(k))
+        return true;
+    return BLOCKED_DOTENV_PREFIXES.some((p) => k.startsWith(p));
+}
 /** Load `<cwd>/.env` into `process.env` (no-clobber). Returns loaded keys. */
 export function loadDotenv(cwd) {
     let text;
@@ -47,11 +110,22 @@ export function loadDotenv(cwd) {
     }
     const parsed = parseDotenv(text);
     const loaded = [];
+    const blocked = [];
     for (const [k, v] of Object.entries(parsed)) {
+        if (isBlockedDotenvKey(k)) {
+            blocked.push(k);
+            continue;
+        }
         if (process.env[k] === undefined) {
             process.env[k] = v;
             loaded.push(k);
         }
     }
+    if (blocked.length > 0) {
+        try {
+            process.stderr.write(`klyro: ignoring process-control vars in .env (${blocked.join(', ')}) — a repo's .env may not change how your shell, node, or editor runs\n`);
+        }
+        catch { /* ignore */ }
+    }
     return loaded;
 }

package/dist/cli/errors.js

@@ -5,7 +5,7 @@ import { KlyroError } from '../shared/errors.js';
 export function handleFatal(err) {
     const isDebug = !!process.env.KLYRO_LOG_LEVEL || !!process.env.DEBUG || process.argv.includes('--debug');
     let code = 1;
-    let message = err instanceof Error ? err.message : String(err);
+    const message = err instanceof Error ? err.message : String(err);
     let hint;
     if (err instanceof KlyroError) {
         code = err.exitCode;

package/dist/cli/eval.js

@@ -65,13 +65,11 @@ export async function runEval(opts) {
     }
     // 5.4 — suite mode: load from evals/fixtures
     if (opts.suite) {
-        const { runHarness, loadFileFixture } = await import('../eval/harness.js');
         const fs = await import('node:fs/promises');
         const path = await import('node:path');
-        const suiteDir = path.join(process.cwd(), 'evals', 'fixtures', opts.suite === 'smoke' ? '' : opts.suite);
         // For smoke, use the 10 fixtures directly
         const fixturesDir = path.join(process.cwd(), 'evals', 'fixtures');
-        let tasks = [];
+        const tasks = [];
         try {
             const entries = await fs.readdir(fixturesDir);
             for (const e of entries) {

package/dist/cli/hooks.d.ts

@@ -74,8 +74,39 @@ export declare const DEFAULT_HOOK_TIMEOUT_MS = 30000;
 /**
  * Load hooks for a run. Global first, then project — a project hook with
  * the same `name` replaces the global one. Never throws.
+ *
+ * Project hooks are repo-authored and run with `shell: true`, so they are
+ * gated on trust (see `projectHooksTrusted`): a cloned repo must not execute
+ * code just because someone ran `klyro` in it, and an untrusted project can
+ * not shadow a global hook by name.
  */
 export declare function loadHooks(cwd: string): Hook[];
+/** Absolute path of the project's hook file (may not exist). */
+export declare function projectHooksPath(cwd: string): string;
+/**
+ * Is the project's hook file allowed to run? Two paths:
+ *   1. `KLYRO_TRUST_PROJECT_HOOKS=1` — explicit per-shell opt-in, or
+ *   2. the file's current sha256 is pinned in `~/.klyro/trusted-hooks.json`
+ *      (recorded by an explicit `klyro hooks trust`; any later edit changes
+ *      the hash, so the file re-locks until reviewed again).
+ */
+export declare function projectHooksTrusted(cwd: string): boolean;
+/** Describe the project's hook file for the `klyro hooks` surface. */
+export declare function projectHooksStatus(cwd: string): {
+    path: string;
+    exists: boolean;
+    trusted: boolean;
+};
+/**
+ * Trust (or re-trust) the project's hooks file at its current contents.
+ * Throws when there is no project hooks file.
+ */
+export declare function trustProjectHooks(cwd: string): {
+    path: string;
+    hash: string;
+};
+/** Remove the project's hook file from the trust store. False when absent. */
+export declare function untrustProjectHooks(cwd: string): boolean;
 export interface HookContext {
     toolName: string;
     input: unknown;

package/dist/cli/hooks.js

@@ -28,10 +28,12 @@
  * stdin (`{ event, tool, input, sessionId, ... }`).
  */
 import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { z } from 'zod';
+import { stripBom } from '../shared/json.js';
 export const HookEventSchema = z.enum(['preToolUse', 'postToolUse', 'sessionStart', 'sessionEnd', 'stop']);
 export const HookSchema = z.object({
     name: z.string().min(1),
@@ -49,11 +51,28 @@ const MAX_HOOK_OUTPUT_CHARS = 4000;
 /** Paths already warned about (invalid JSON/schema) — warn once per path. */
 const warnedPaths = new Set();
 function warnOnce(filePath, detail) {
-    if (warnedPaths.has(filePath))
+    warnOnceRaw(`invalid:${normWarnKey(filePath)}`, `klyro: hooks: ignoring invalid file ${filePath}: ${detail}\n`);
+}
+/**
+ * Warn-once keys normalize the file identity (resolved absolute path +
+ * NFKC) so the same content can't re-warn via `./x`, `X/../x`, case, or
+ * slash variants — each real file warns at most once.
+ */
+function normWarnKey(filePath) {
+    try {
+        return path.resolve(filePath).normalize('NFKC');
+    }
+    catch {
+        return filePath;
+    }
+}
+/** One stderr line per unique key (used for trust notices too). */
+function warnOnceRaw(key, message) {
+    if (warnedPaths.has(key))
         return;
-    warnedPaths.add(filePath);
+    warnedPaths.add(key);
     try {
-        process.stderr.write(`klyro: hooks: ignoring invalid file ${filePath}: ${detail}\n`);
+        process.stderr.write(message);
     }
     catch { /* ignore */ }
 }
@@ -68,7 +87,7 @@ function readHooksFile(filePath) {
     }
     let parsed;
     try {
-        parsed = JSON.parse(raw);
+        parsed = JSON.parse(stripBom(raw));
     }
     catch (err) {
         warnOnce(filePath, err instanceof Error ? err.message : String(err));
@@ -93,6 +112,11 @@ function globalHooksPath() {
 /**
  * Load hooks for a run. Global first, then project — a project hook with
  * the same `name` replaces the global one. Never throws.
+ *
+ * Project hooks are repo-authored and run with `shell: true`, so they are
+ * gated on trust (see `projectHooksTrusted`): a cloned repo must not execute
+ * code just because someone ran `klyro` in it, and an untrusted project can
+ * not shadow a global hook by name.
  */
 export function loadHooks(cwd) {
     let out = [];
@@ -100,9 +124,16 @@ export function loadHooks(cwd) {
         const byName = new Map();
         for (const h of readHooksFile(globalHooksPath()))
             byName.set(h.name, h);
-        const projectFile = path.join(cwd, '.klyro', 'hooks.json');
-        for (const h of readHooksFile(projectFile))
-            byName.set(h.name, h);
+        const projectFile = projectHooksPath(cwd);
+        if (fs.existsSync(projectFile)) {
+            if (projectHooksTrusted(cwd)) {
+                for (const h of readHooksFile(projectFile))
+                    byName.set(h.name, h);
+            }
+            else {
+                warnOnceRaw(`untrusted:${normWarnKey(projectFile)}`, `klyro: hooks: project hooks ${projectFile} are NOT trusted — review the file, then run \`klyro hooks trust\` (or set KLYRO_TRUST_PROJECT_HOOKS=1)\n`);
+            }
+        }
         out = [...byName.values()];
     }
     catch {
@@ -110,6 +141,94 @@ export function loadHooks(cwd) {
     }
     return out;
 }
+/** Absolute path of the project's hook file (may not exist). */
+export function projectHooksPath(cwd) {
+    return path.join(cwd, '.klyro', 'hooks.json');
+}
+/** Hash-pinned trust store: `{ "<resolved absolute path>": "<sha256 hex>" }`. */
+function trustStorePath() {
+    return path.join(os.homedir() || process.cwd(), '.klyro', 'trusted-hooks.json');
+}
+function sha256File(file) {
+    try {
+        return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+function trustedHashes() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(trustStorePath(), 'utf-8'));
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const out = {};
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v === 'string')
+                    out[k] = v;
+            }
+            return out;
+        }
+    }
+    catch { /* missing or invalid — nothing trusted */ }
+    return {};
+}
+function writeTrustStore(store) {
+    const p = trustStorePath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(store, null, 2), 'utf-8');
+    fs.renameSync(tmp, p);
+}
+/**
+ * Is the project's hook file allowed to run? Two paths:
+ *   1. `KLYRO_TRUST_PROJECT_HOOKS=1` — explicit per-shell opt-in, or
+ *   2. the file's current sha256 is pinned in `~/.klyro/trusted-hooks.json`
+ *      (recorded by an explicit `klyro hooks trust`; any later edit changes
+ *      the hash, so the file re-locks until reviewed again).
+ */
+export function projectHooksTrusted(cwd) {
+    if (process.env.KLYRO_TRUST_PROJECT_HOOKS === '1')
+        return true;
+    const file = projectHooksPath(cwd);
+    if (!fs.existsSync(file))
+        return false;
+    const hash = sha256File(file);
+    if (!hash)
+        return false;
+    const store = trustedHashes();
+    const resolved = path.resolve(file);
+    return store[resolved] === hash || store[file] === hash;
+}
+/** Describe the project's hook file for the `klyro hooks` surface. */
+export function projectHooksStatus(cwd) {
+    const file = projectHooksPath(cwd);
+    const exists = fs.existsSync(file);
+    return { path: file, exists, trusted: exists && projectHooksTrusted(cwd) };
+}
+/**
+ * Trust (or re-trust) the project's hooks file at its current contents.
+ * Throws when there is no project hooks file.
+ */
+export function trustProjectHooks(cwd) {
+    const file = projectHooksPath(cwd);
+    const hash = sha256File(file);
+    if (!hash)
+        throw new Error(`no project hooks file at ${file}`);
+    const store = trustedHashes();
+    store[path.resolve(file)] = hash;
+    writeTrustStore(store);
+    return { path: file, hash };
+}
+/** Remove the project's hook file from the trust store. False when absent. */
+export function untrustProjectHooks(cwd) {
+    const resolved = path.resolve(projectHooksPath(cwd));
+    const store = trustedHashes();
+    if (store[resolved] === undefined)
+        return false;
+    delete store[resolved];
+    writeTrustStore(store);
+    return true;
+}
 /**
  * Minimal filtered env for hook children (mirrors the shell_exec policy:
  * secrets stripped, only safe prefixes pass). Kept local so the hooks

package/dist/cli/markdown.js

@@ -38,7 +38,7 @@ export function renderMarkdown(md, opts = {}) {
     const lines = md.split('\n');
     let inCodeBlock = false;
     let fenceLang = '';
-    for (let line of lines) {
+    for (const line of lines) {
         if (line.startsWith('```')) {
             if (!inCodeBlock)
                 fenceLang = line.replace(/^```/, '').trim().toLowerCase();

package/dist/cli/repl.js

@@ -103,6 +103,7 @@ export async function startRepl(opts = {}) {
     // sanitizeForPrompt in sibling-owned policy/approval.ts — intentionally
     // not imported; kept local to avoid coupling the REPL to that module).
     function sanitizeForPrompt(s) {
+        // eslint-disable-next-line no-control-regex -- intentional: stripping C0 controls + CSI sequences
         return s.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]|\x1b\[[0-9;]*[A-Za-z]/g, '').slice(0, 120);
     }
     async function loadMcpTools() {
@@ -190,7 +191,7 @@ export async function startRepl(opts = {}) {
     // become fallback adapters for agent runs in this session. Live
     // /provider switches rebuild a single adapter (buildAdapter) and bypass
     // the chain — documented, not a bug.
-    let replFailoverAdapters = [];
+    const replFailoverAdapters = [];
     try {
         const { resolveProviderChain } = await import('./config.js');
         const chain = await resolveProviderChain(cwd);
@@ -372,11 +373,12 @@ export async function startRepl(opts = {}) {
     // ── Full-screen takeover like OpenCode — always when klyro in TTY (user explicitly wants it)
     // Scroll now works correctly via internal viewport, not native terminal scroll
     const isAltScreen = useTui && !!process.stdout.isTTY && process.env.KLYRO_NO_ALT !== '1';
-    // Mouse reporting is opt-in (KLYRO_MOUSE=1): when on, the terminal sends
-    // clicks/wheel to the app (wheel scrolls ±3 lines) but native text
-    // selection and right-click paste stop working. Default off so select to
-    // copy and right-click paste work out of the box; bracketed paste
-    // (keyboard paste) is unaffected and always enabled below.
+    // Mouse reporting is ON by default (opencode parity): the wheel scrolls
+    // the chat, clicks are swallowed by the app. That means plain mouse
+    // selection/right-click go to the app, not the terminal — use Shift+drag
+    // to select and Shift+right-click to paste, or set KLYRO_MOUSE=0 for fully
+    // native selection (then scroll with PgUp/PgDn, Ctrl+U/D, Shift+↑/↓,
+    // Home/End, Space). Bracketed (keyboard) paste is unaffected and always on.
     const mouseReporting = isAltScreen && isMouseReportingEnabled();
     const enterAlt = () => {
         if (!isAltScreen)
@@ -501,8 +503,9 @@ export async function startRepl(opts = {}) {
             if (consoleRing.length > 200)
                 consoleRing.splice(0, consoleRing.length - 200);
             try {
+                // KLYRO_LOG_DIR relocates the debug log (1.5); default is ~/.klyro.
                 const home = process.env.HOME ?? process.env.USERPROFILE ?? cwd;
-                const dir = nodePath.join(home, '.klyro');
+                const dir = process.env.KLYRO_LOG_DIR ?? nodePath.join(home, '.klyro');
                 fsSync.mkdirSync(dir, { recursive: true });
                 const logFile = nodePath.join(dir, 'debug.log');
                 // Rotation: never let the debug log grow without bound (2 MiB cap).
@@ -724,6 +727,7 @@ export async function startRepl(opts = {}) {
         }
         catch { /* silent */ }
     })();
+    // eslint-disable-next-line prefer-const -- single assignment, but `let` is required: declaration precedes this for TDZ-safe handler wiring.
     app = render(React.createElement(App, {
         initialModel: model,
         maxSteps: currentMaxSteps,
@@ -778,6 +782,7 @@ export async function startRepl(opts = {}) {
     }), { patchConsole: false });
     // Install SIGINT handler only after app exists (avoids TDZ) and use once
     // On Ctrl+C in alt-screen, leave alt before exit so shell is restored
+    // eslint-disable-next-line prefer-const -- see above: declaration order is load-bearing.
     sigintHandler = () => {
         ac.abort();
         queuedStatus({ status: 'aborted' });
@@ -861,9 +866,6 @@ export async function startRepl(opts = {}) {
                 return;
             }
         }
-        let activeCallId = null;
-        let activeCallName = null;
-        let activeCallArgs = '';
         let runEndStatus = 'error';
         try {
             const result = await run({
@@ -902,14 +904,6 @@ export async function startRepl(opts = {}) {
                     else if (ev.kind === 'checkpoint_saved') {
                         queuedStatus({ status: 'running' });
                     }
-                    else if (ev.kind === 'tool_call_start') {
-                        activeCallId = ev.id;
-                        activeCallName = ev.name;
-                        activeCallArgs = '';
-                    }
-                    else if (ev.kind === 'tool_call_delta') {
-                        activeCallArgs += ev.argsJson;
-                    }
                     else if (ev.kind === 'tool_call_end') {
                         pendingToolIds.add(ev.id);
                         queuedAppend({
@@ -920,9 +914,6 @@ export async function startRepl(opts = {}) {
                             args: JSON.stringify(ev.input, null, 2),
                             status: 'running',
                         });
-                        activeCallId = null;
-                        activeCallName = null;
-                        activeCallArgs = '';
                     }
                     else if (ev.kind === 'policy_decision') {
                         queuedAppend({
@@ -1354,8 +1345,6 @@ export async function startRepl(opts = {}) {
             }
             case 'context': {
                 const { renderContextBreakdown } = await import('./context.js');
-                // use last transcript via closure? approximate with empty
-                const { accounting } = await import('../context/accounting.js');
                 const sys = ''; // system prompt approx
                 const breakdown = renderContextBreakdown(sys, []);
                 queuedAppend({ id: `ctx-${Date.now()}`, kind: 'text', text: breakdown, role: 'assistant' });
@@ -2689,7 +2678,7 @@ export async function startRepl(opts = {}) {
                         '  Enter send · Shift+Enter newline · Tab complete slash · Esc drop queued / Esc×2 cancel run',
                         '  Ctrl+C cancel (1st) / quit (2nd) · Ctrl+O expand last tool group · Ctrl+G jump bottom',
                         '  PgUp/PgDn or Ctrl+U/Ctrl+D half-page · Ctrl+Home/End top/bottom · Home/End jump · Space jump to unread',
-                        '  Ctrl+B/F page · Shift/Ctrl+↑/↓ line · ↑ history at live tail, scrolls while reading above · Ctrl+P/N history always · PgUp/Dn or Ctrl+U/D scroll (KLYRO_MOUSE=1 adds wheel ±3 lines)',
+                        '  Ctrl+B/F page · Shift/Ctrl+↑/↓ line · ↑/↓ and Ctrl+P/N browse input history only · wheel scrolls · PgUp/Dn or Ctrl+U/D scroll · KLYRO_MOUSE=0 for native selection',
                         '  Text selection/copy and right-click paste work natively · Shift+Enter newline · /vim toggles vim input mode · /keymap <note> saves a display note',
                     ].join('\n'),
                 });