klyro 1.0.14 → 1.0.16

package/README.md

@@ -51,6 +51,7 @@ node dist/index.js chat
 | `KLYRO_YES` / `--yes` | **Commit only** — auto-approves `klyro commit` prompts; nothing else reads it |
 | `KLYRO_NO_UPDATE_CHECK=1` | Disables the 24h update check |
 | `KLYRO_ALLOW_MAIN_PUSH=1` | Per-risk escape for protected-branch push |
+| `KLYRO_TRUST_PROJECT_HOOKS=1` | Per-shell opt-in to run repo-authored `.klyro/hooks.json` commands without pinning them via `klyro hooks trust` |
 | `KLYRO_CREDENTIALS_INSECURE_OK=1` | Warn (don't refuse) on group-readable credentials |
 | `KLYRO_LSP=0` | Force language tools off |
 | `KLYRO_SYMBOLS=0` | Force `find_symbol` off |
@@ -60,6 +61,7 @@ node dist/index.js chat
 ## New in recent releases
 
 - `klyro run --bare` — deterministic runs: skips MCP, hooks, memory/KLYRO.md/context, persistence
+- `klyro hooks trust` — project `.klyro/hooks.json` commands run only after explicit review: the file is hash-pinned in `~/.klyro/trusted-hooks.json` and any edit re-locks it (a cloned repo can no longer execute code just because you ran `klyro` in it)
 - `klyro mcp trust <name>` / `mcp prompts [server]` / `mcp add <name> <https-url>` — remote MCP + prompt trust
 - `klyro agents lint` — validate `.klyro/agents/*.md` (ids, tool names)
 - `klyro init` — scan-seeded `KLYRO.md` + `.mcp.json` (never overwrites)
@@ -72,13 +74,20 @@ node dist/index.js chat
 
 ## Documentation
 
+Progress: Klyro is **complete through Level 10** ("Klyro 1.0" milestone) of the
+20-level plan; see [`docs/STATUS.md`](docs/STATUS.md) for the audited
+level-by-level grading.
+
 | Doc | Purpose |
 |---|---|
-| [`docs/done.md`](docs/done.md) | **Status** — what's built, what's verified, what isn't |
-| [`docs/plan.md`](docs/plan.md) | **Roadmap** — 20-level plan from bare CLI to super-harness |
-| [`docs/PRD.md`](docs/PRD.md) | (authoritative) product vision |
-| [`docs/HarnessFlow.md`](docs/HarnessFlow.md) | (authoritative) system flow |
-| [`docs/MVP.md`](docs/MVP.md) | (authoritative) MVP scope |
+| [`docs/STATUS.md`](docs/STATUS.md) | **Status (authoritative)** — release state + plan level progress |
+| [`plan.md`](plan.md) | **Roadmap** — 20-level / 100-sub-level plan from bare CLI to super-harness |
+| [`PRD.md`](PRD.md) | Product vision and requirements |
+| [`READ.md`](READ.md) | Full build documentation / architecture walkthrough |
+| [`review.md`](review.md) | Point-in-time repository review (1.0.9) |
+| [`comparison.md`](comparison.md) | Architectural audit vs Claude Code (36 rounds) |
+| [`commands.md`](commands.md) | CLI + slash-command reference |
+| [`TUI_DESIGN.md`](TUI_DESIGN.md) | TUI design notes (layout, scroll model) |
 
 ## Code structure
 

package/dist/agent/child-worker.js

@@ -33,6 +33,11 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
 import { run } from './runtime.js';
+import { cappedOutput } from '../shared/output-cap.js';
+/** Child results are ONE JSON line, but a misbehaving child can print forever. */
+const MAX_CHILD_STDOUT_BYTES = 8 * 1024 * 1024;
+/** stderr keeps its TAIL — callers slice(-500/-1000) for the failure reason. */
+const MAX_CHILD_STDERR_CHARS = 16_000;
 /**
  * Differently-phrased crash, distinct from an in-process throw the parent
  * would catch. The child either exited non-zero without a parseable result
@@ -81,12 +86,18 @@ export async function forkChild(entry, payload, opts = {}) {
         windowsHide: true,
         shell: false,
     });
-    let stdout = '';
+    const stdoutCap = cappedOutput(MAX_CHILD_STDOUT_BYTES);
     let stderr = '';
     child.stdout.setEncoding('utf8');
     child.stderr.setEncoding('utf8');
-    child.stdout.on('data', (c) => { stdout += c; });
-    child.stderr.on('data', (c) => { opts.onStderr?.(c); stderr += c; });
+    // Keep the HEAD of stdout (the ChildResult line) and the TAIL of stderr
+    // (where the reason lives), so neither can grow the parent's heap without
+    // bound over the child's 10-minute budget.
+    child.stdout.on('data', (c) => { stdoutCap.push(Buffer.from(c, 'utf8')); });
+    child.stderr.on('data', (c) => {
+        opts.onStderr?.(c);
+        stderr = (stderr + c).slice(-MAX_CHILD_STDERR_CHARS);
+    });
     // Write the payload to stdin, then signal EOF so the child knows it has
     // the whole payload before it starts running.
     child.stdin.on('error', () => { });
@@ -119,7 +130,7 @@ export async function forkChild(entry, payload, opts = {}) {
         });
         child.on('close', (code, signal) => {
             cleanup();
-            const first = stdout.split('\n').find((l) => l.trim().length > 0);
+            const first = stdoutCap.text().split('\n').find((l) => l.trim().length > 0);
             if (code === 0 && first) {
                 try {
                     resolve(JSON.parse(first));

package/dist/checkpoints/store.js

@@ -14,6 +14,7 @@ import * as fs from 'node:fs/promises';
 import * as fsSync from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
+import { cappedOutput } from '../shared/output-cap.js';
 function ckptDir(cwd) {
     return path.join(cwd, '.klyro', 'checkpoints');
 }
@@ -107,7 +108,7 @@ export async function snapshot(cwd, files) {
         const args = ['diff', '--', ...kept.slice(0, 20)];
         const diffText = await new Promise((resolve) => {
             const child = spawn('git', args, { cwd, shell: false, windowsHide: true });
-            const chunks = [];
+            const sink = cappedOutput(20 * 1024);
             let done = false;
             const t = setTimeout(() => {
                 if (!done) {
@@ -119,16 +120,13 @@ export async function snapshot(cwd, files) {
                     resolve('');
                 }
             }, 10_000);
-            child.stdout.on('data', (b) => {
-                if (Buffer.concat(chunks).length < 20 * 1024)
-                    chunks.push(b);
-            });
+            child.stdout.on('data', (b) => sink.push(b));
             child.on('close', () => {
                 if (done)
                     return;
                 done = true;
                 clearTimeout(t);
-                resolve(Buffer.concat(chunks).toString('utf-8').slice(0, 20 * 1024));
+                resolve(sink.text());
             });
             child.on('error', () => {
                 if (done)
@@ -214,9 +212,9 @@ export async function diff(cwd, id) {
     const { spawn } = await import('node:child_process');
     return new Promise((resolve) => {
         const child = spawn('git', ['diff', '--stat'], { cwd, shell: false, windowsHide: true });
-        let out = '';
-        child.stdout.on('data', (b) => { out += b.toString(); });
-        child.on('close', () => resolve(out || 'No diff'));
+        const sink = cappedOutput(64 * 1024);
+        child.stdout.on('data', (b) => sink.push(b));
+        child.on('close', () => resolve(sink.text() || 'No diff'));
         child.on('error', () => resolve('No git diff available'));
     });
 }

package/dist/cli/config.js

@@ -328,6 +328,91 @@ export function loadConfigSync() {
     }
     return {};
 }
+/**
+ * Project-layer trust boundary (P1): `.klyro/settings*.json` ship with the
+ * repo, so a hostile checkout can plant them. API keys are NEVER accepted
+ * from project layers — keys load only from ~/.klyro, env, or flags. A
+ * project baseUrl pointing at a public host (which would receive the user's
+ * key + prompts) warns loudly; loopback/RFC1918 stay silent for shared
+ * local setups (Ollama etc.).
+ */
+function isPublicHostUrl(raw) {
+    let host = '';
+    try {
+        host = new URL(raw).hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    }
+    catch {
+        return true; // unparseable endpoint — treat as hostile, warn
+    }
+    if (host === 'localhost' || host === '127.0.0.1' || host === '::1')
+        return false;
+    if (host.endsWith('.localhost') || host.endsWith('.local'))
+        return false;
+    if (host.startsWith('127.'))
+        return false;
+    if (/^10\.\d+\.\d+\.\d+$/.test(host))
+        return false;
+    if (/^192\.168\.\d+\.\d+$/.test(host))
+        return false;
+    if (/^172\.(1[6-9]|2\d|3[0-1])\.\d+\.\d+$/.test(host))
+        return false;
+    return true;
+}
+function scrubProjectLayer(obj, file) {
+    const warn = (msg) => {
+        try {
+            process.stderr.write(msg);
+        }
+        catch { /* ignore */ }
+    };
+    for (const k of ['apiKey', 'api_key']) {
+        if (obj[k] !== undefined) {
+            delete obj[k];
+            warn(`klyro: ignoring apiKey in project config ${file} — keys load only from ~/.klyro/settings.json, env (KLYRO_API_KEY), or --api-key\n`);
+        }
+    }
+    for (const k of ['baseUrl', 'baseURL']) {
+        const v = obj[k];
+        if (typeof v === 'string' && v.length > 0 && isPublicHostUrl(v)) {
+            warn(`klyro: warning: project config ${file} points the provider at ${v} — API requests (including your key) will go there\n`);
+        }
+    }
+    scrubProjectFailover(obj['providers'], file, warn);
+    return obj;
+}
+/**
+ * Failover entries from a project layer get the same trust treatment as the
+ * primary endpoint. Two reasons `apiKeyEnv` is dropped rather than warned
+ * about: (a) a fallback fires *without a prompt*, so a repo-chosen env var
+ * name would silently ship the user's credential to a repo-chosen host, and
+ * (b) the name can also cross providers (`provider:'openai'` + an Anthropic
+ * env var). A literal `apiKey` in project config is left alone — that is the
+ * repo's own key, not the user's secret — matching the accepted
+ * `providers.failover[].apiKey` behaviour. Keys for a project-authored
+ * fallback belong in ~/.klyro/settings.json.
+ */
+function scrubProjectFailover(providers, file, warn) {
+    if (providers === null || typeof providers !== 'object')
+        return;
+    const failover = providers.failover;
+    if (!Array.isArray(failover))
+        return;
+    for (const entry of failover) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const e = entry;
+        if (e['apiKeyEnv'] !== undefined) {
+            delete e['apiKeyEnv'];
+            warn(`klyro: ignoring apiKeyEnv in project config ${file} — a repo must not choose which env var holds your key; configure that fallback in ~/.klyro/settings.json\n`);
+        }
+        for (const k of ['baseURL', 'baseUrl']) {
+            const v = e[k];
+            if (typeof v === 'string' && v.length > 0 && isPublicHostUrl(v)) {
+                warn(`klyro: warning: project config ${file} routes a failover provider to ${v} — API requests (including your key) will go there\n`);
+            }
+        }
+    }
+}
 // --- Merged load with 5-layer precedence ---
 export async function loadMergedConfig(cwd = process.cwd(), flags = {}) {
     const layers = [];
@@ -351,7 +436,7 @@ export async function loadMergedConfig(cwd = process.cwd(), flags = {}) {
     try {
         const raw = await fs.readFile(path.join(cwd, '.klyro', 'settings.json'), 'utf-8');
         const obj = parseJsonc(raw, path.join(cwd, '.klyro/settings.json'));
-        layers.push(validateConfig(obj, path.join(cwd, '.klyro/settings.json')));
+        layers.push(scrubProjectLayer(validateConfig(obj, path.join(cwd, '.klyro/settings.json')), path.join(cwd, '.klyro/settings.json')));
     }
     catch (err) {
         const e = err;
@@ -362,7 +447,7 @@ export async function loadMergedConfig(cwd = process.cwd(), flags = {}) {
     try {
         const raw = await fs.readFile(path.join(cwd, '.klyro', 'settings.local.json'), 'utf-8');
         const obj = parseJsonc(raw, path.join(cwd, '.klyro/settings.local.json'));
-        layers.push(validateConfig(obj, path.join(cwd, '.klyro/settings.local.json')));
+        layers.push(scrubProjectLayer(validateConfig(obj, path.join(cwd, '.klyro/settings.local.json')), path.join(cwd, '.klyro/settings.local.json')));
     }
     catch (err) {
         const e = err;

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

@@ -2689,7 +2689,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 · PgUp/Dn or Ctrl+U/D scroll · wheel scrolls with KLYRO_MOUSE=1',
                         '  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'),
                 });

package/dist/cli/run.js

@@ -22,10 +22,6 @@ import { memoryBlock } from '../context/memory.js';
 import { estimateCost } from '../providers/model-info.js';
 import { resolveSessionId } from '../persistence/session.js';
 import * as fs from 'node:fs';
-function readEnv(name, fallback) {
-    const v = process.env[name];
-    return v && v.length > 0 ? v : fallback;
-}
 /**
  * Double-Ctrl+C detector (pure, exported for tests): the second SIGINT
  * within 1500ms of the first forces `process.exit(130)`. The live handler
@@ -75,10 +71,22 @@ export async function runOnce(opts) {
         });
     };
     let adapter = opts.adapter;
+    let chain = [];
     if (!adapter) {
-        const provider = opts.provider ?? 'openai';
-        const baseUrl = opts.baseUrl ?? readEnv('KLYRO_BASE_URL');
-        const apiKey = opts.apiKey ?? readEnv('KLYRO_API_KEY');
+        // Single source of truth: the provider chain (flags > merged config >
+        // env > defaults) resolves the primary identically everywhere, so CLI
+        // flags (--provider/--api-key/--base-url) and every key env source apply
+        // to the primary and to each failover entry alike.
+        const { resolveProviderChain } = await import('./config.js');
+        chain = await resolveProviderChain(opts.cwd, {
+            ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
+            ...(opts.baseUrl !== undefined ? { baseUrl: opts.baseUrl } : {}),
+            ...(opts.apiKey !== undefined ? { apiKey: opts.apiKey } : {}),
+        });
+        const primary = chain[0];
+        const provider = primary.provider;
+        const baseUrl = primary.baseURL;
+        const apiKey = primary.apiKey;
         if (!apiKey) {
             stderr.write('klyro: KLYRO_API_KEY is not set (or pass --api-key)\n');
             return 2;
@@ -102,11 +110,11 @@ export async function runOnce(opts) {
     // L15 provider failover: extra chain entries (after the primary) become
     // fallback adapters for the runtime. Custom injected adapters (tests)
     // skip chain wiring. Failures resolving the chain never block the run.
+    // (Chain already resolved above with CLI flags; reuse it — no second
+    // resolution, no divergent key sources.)
     let failoverAdapters;
     if (!opts.adapter) {
         try {
-            const { resolveProviderChain } = await import('./config.js');
-            const chain = await resolveProviderChain(opts.cwd);
             const fallbacks = chain.slice(1);
             if (fallbacks.length > 0) {
                 const built = [];

package/dist/cli/session-commands.js

@@ -111,7 +111,8 @@ export function registerSessionCommands(program) {
     async function sessionImport(file) {
         let data;
         try {
-            data = JSON.parse(await (await import('node:fs/promises')).readFile(file, 'utf-8'));
+            const { stripBom } = await import('../shared/json.js');
+            data = JSON.parse(stripBom(await (await import('node:fs/promises')).readFile(file, 'utf-8')));
         }
         catch (err) {
             process.stderr.write(`klyro: cannot import ${file}: ${err instanceof Error ? err.message : String(err)}\n`);