klyro 1.0.6 → 1.0.8

package/READ.md

@@ -1,6 +1,6 @@
 # Klyro — Complete Build Documentation
 
-**For any coding agent:** This file is the single source of truth for what has been built till now (v0.1.15, Levels 1-5 complete, Level 6-8 partial, TUI full-screen). After reading, you have the complete picture.
+**For any coding agent:** This file is the single source of truth for what has been built till now (current version: see `package.json` — v1.0.8; Levels 1-9 complete, Level 10 largely complete incl. MCP/hooks/sub-agents, 34 built-in tools incl. `web_fetch`/`web_search`). The §20 ledger below is the historical record (v0.1.39→v0.1.61); version/test-count numbers inside it are point-in-time, not current. After reading, you have the complete picture.
 
 ---
 

package/README.md

@@ -1,15 +1,17 @@
 # Klyro
 
-Minimal streaming CLI for any OpenAI-compatible LLM endpoint. **Foundation piece** of the Klyro harness project.
+Autonomous AI coding harness — terminal-native agent (CLI + Ink TUI) for any OpenAI-compatible or Anthropic LLM endpoint.
 
 ## What works today
 
-- Streams from `https://<host>/v1/chat/completions`
+- Streams from `https://<host>/v1/chat/completions` (OpenAI-compatible) and Anthropic `/v1/messages`
 - HTTPS-only (with localhost exemption for local LLMs)
-- Per-request timeout
-- Interactive REPL with multi-turn history
-- Bounded error reads
-- Strict TypeScript, zero dependencies beyond `commander`
+- Per-request timeout, retry with backoff, usage/cost accounting
+- Interactive Ink TUI + REPL with multi-turn history, slash commands, approvals
+- Autonomous loop: phases, budgets, stuck detection, verification + repair
+- 34 built-in tools (fs/search/shell/git/verify/plan/web), policy engine, MCP client/server
+- Session persistence (JSON), hash-chained audit log, checkpoints/undo, eval harness
+- Strict TypeScript (`tsc`, noEmit typecheck, vitest)
 
 ## Quick start
 
@@ -55,6 +57,19 @@ node dist/index.js chat
 | `KLYRO_WORKER=0` | Disable subprocess isolation for subagents |
 | `KLYRO_SESSIONS_DIR`, `KLYRO_UPDATE_CACHE`, `KLYRO_CREDENTIALS_FILE` | Relocatable state (tests + power users) |
 
+## New in recent releases
+
+- `klyro run --bare` — deterministic runs: skips MCP, hooks, memory/KLYRO.md/context, persistence
+- `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)
+- `klyro update --apply` — opt-in self-apply of the verified update
+- `klyro eval --judge-model <id>` — model-graded rubric scoring
+- Hooks: `matcher` scoping, stdin JSON, `sessionStart`/`sessionEnd`/`stop` events, JSON verdicts
+- Custom agents (`.klyro/agents/*.md`), custom commands (`.klyro/commands/*.md`), vim mode (`/vim`), `@`-file completion
+- Credentials prefer the OS keychain (macOS Keychain, Linux libsecret), 0600 file fallback
+- Headless JSON ends with exactly one stable `kind:result` envelope (parse the LAST line)
+
 ## Documentation
 
 | Doc | Purpose |
@@ -69,9 +84,20 @@ node dist/index.js chat
 
 ```
 src/
-├── index.ts   # commander entry — two commands (chat, REPL)
-├── chat.ts    # single-turn streaming chat (251 LOC)
-└── repl.ts    # multi-turn REPL (168 LOC)
+├── index.ts        # commander entry — tui/run/chat/eval/session/mcp/agents/commit/audit/...
+├── agent/          # runtime loop, orchestrator, adapters, worktree, tasks
+├── cli/            # run/repl/config/doctor/hooks/eval/slash/...
+├── tools/          # 34 built-ins: fs/search/shell/git/verify/plan/web (+ registry)
+├── policy/         # engine, path-guard, approval, secret-redactor
+├── context/        # project-map, repo-map, tokenizer, compaction, memory, trust
+├── verification/   # registry, parsers, repair loop, baseline, scoped
+├── mcp/            # client (stdio/SSE/HTTP), trust, serve, OAuth
+├── persistence/    # JSON session store, hash-chained audit
+├── checkpoints/    # snapshots, undo/rewind
+├── events/ trace/ renderers/  # event bus, JSONL traces, terminal/JSON output
+├── tui/            # Ink app (transcript, approval, diff, scroll, markdown)
+├── eval/           # scripted harness, tasks, judge
+└── chat.ts / repl.ts  # legacy one-shot chat + legacy REPL
 ```
 
 ## License

package/dist/agent/orchestrator.d.ts

@@ -53,7 +53,13 @@ export interface AgentDefinition {
 }
 /** Default agents a model can delegate to. */
 export declare const BUILTIN_AGENTS: readonly AgentDefinition[];
-/** Compact summary returned to the parent — the child's transcript stays separate. */ export interface ChildSummary {
+/**
+ * Layer specialist instructions into a child's system prompt (not the user
+ * task). Pure — unit-tested directly. No-op when the def has no prompt.
+ */
+export declare function layerSpecialistPrompt(base: RuntimeDeps['systemPrompt'], def: Pick<AgentDefinition, 'id' | 'prompt'>): RuntimeDeps['systemPrompt'];
+/** Compact summary returned to the parent — the child's transcript stays separate. */
+export interface ChildSummary {
     taskId: string;
     agentName: string;
     status: TaskStatus;

package/dist/agent/orchestrator.js

@@ -33,7 +33,7 @@ export const BUILTIN_AGENTS = [
         description: 'Read-only reconnaissance: map the repo, find symbols and tests.',
         readonly: true,
         canSpawn: false,
-        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'find_symbol', 'git_status', 'git_log', 'git_diff', 'recent_files', 'imports_of', 'importers_of'],
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'find_symbol', 'git_status', 'git_log', 'git_diff', 'recent_files', 'imports_of', 'importers_of', 'web_fetch', 'web_search'],
     },
     {
         id: 'implementer',
@@ -68,9 +68,22 @@ export const BUILTIN_AGENTS = [
         description: 'Read-only documentation lookup: find and summarise docs, READMEs, and code structure.',
         readonly: true,
         canSpawn: false,
-        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'recent_files'],
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'recent_files', 'web_fetch', 'web_search'],
     },
 ];
+/**
+ * Layer specialist instructions into a child's system prompt (not the user
+ * task). Pure — unit-tested directly. No-op when the def has no prompt.
+ */
+export function layerSpecialistPrompt(base, def) {
+    if (!def.prompt)
+        return base;
+    return (ctx) => {
+        const r = base(ctx);
+        const block = `\n\n<specialist id="${def.id}">\n${def.prompt}\n</specialist>`;
+        return typeof r === 'string' ? r + block : { ...r, system: r.system + block };
+    };
+}
 /**
  * All agents: builtins plus custom `.klyro/agents/*.md` definitions.
  * Custom ids win on clash (including overriding a builtin) — the override
@@ -368,7 +381,8 @@ export class AgentOrchestrator {
         }
         this.taskMeta.set(record.id, worktree ? { def, dropped: resolved.dropped, worktree, repoCwd } : { def, dropped: resolved.dropped });
         const childRegistry = new ScopedRegistry(this.deps.registry, resolved.allowed);
-        const childDeps = { ...this.deps, registry: childRegistry };
+        const childPromptFn = layerSpecialistPrompt(this.deps.systemPrompt, def);
+        const childDeps = { ...this.deps, registry: childRegistry, systemPrompt: childPromptFn };
         const childRef = {
             taskId: record.id,
             ...(parent.taskId !== undefined ? { parentTaskId: parent.taskId } : {}),
@@ -380,11 +394,8 @@ export class AgentOrchestrator {
             ...(childModel !== undefined ? { model: childModel } : {}),
             ...(resolved.allowedPaths !== undefined ? { allowedPaths: resolved.allowedPaths } : {}),
         };
-        // Specialist instructions from `.klyro/agents/*.md` (or programmatic
-        // defs) ride with the delegated task on both paths below.
-        const childTask = def.prompt ? `${def.prompt}\n\n---\n\n${input.task}` : input.task;
         const childOptions = {
-            task: childTask,
+            task: input.task,
             cwd: childCwd,
             model: childModel ?? 'inherit', // model override must reach the adapter (see runtime)
             maxSteps: def.maxSteps,
@@ -431,7 +442,7 @@ export class AgentOrchestrator {
             let childOutcome;
             try {
                 if (useProcessIsolation) {
-                    const sysPrompt = resolveSystemPrompt(this.deps.systemPrompt, { cwd: childCwd });
+                    const sysPrompt = resolveSystemPrompt(childPromptFn, { cwd: childCwd });
                     // Splice the volatile telemetry suffix into the stable prefix so the
                     // child's provider sees one system string. Telemetry is best-effort
                     // inside the child (it re-emits); the goal here is parity, not
@@ -439,7 +450,7 @@ export class AgentOrchestrator {
                     const systemPrompt = sysPrompt.suffix ? `${sysPrompt.system}\n${sysPrompt.suffix}` : sysPrompt.system;
                     const payload = {
                         cwd: childCwd,
-                        task: childTask,
+                        task: input.task,
                         // A concrete provider model must reach the child — 'inherit' only
                         // exists to defer resolution inside the parent's run().
                         model: (childModel ?? parent.model),

package/dist/agent/runtime.d.ts

@@ -131,6 +131,16 @@ export interface RunOptions {
         store?: import('../persistence/store.js').SessionStore;
         sessionId?: string;
     };
+    /**
+     * Level 10 — tamper-evident audit. When an AuditLog is provided, the
+     * runtime writes policy decisions and tool completions into the chained
+     * audit stream (complements, does not replace, persistence). Defaults off
+     * so callers opt in; `klyro` CLI enables it when a sessions dir exists.
+     */
+    audit?: {
+        log?: import('../persistence/audit.js').AuditLog;
+        sessionId?: string;
+    };
     /**
      * Orchestration context (P0). Present for any agent that is itself managed
      * by an AgentOrchestrator — so a child knows who its parent is, how deep the

package/dist/agent/runtime.js

@@ -23,7 +23,7 @@ import { verify, diagnosticForModel } from '../verification/engine.js';
 import { detectVerifyCommand } from '../verification/auto.js';
 import { ensureBaseline, getBaseline } from '../verification/baseline.js';
 import { compressTranscript, totalTokens, calibrateEstimate, transcriptCharLength } from '../context/tokenizer.js';
-import { capForModel } from '../context/accounting.js';
+import { capForModel, RESERVE_OUTPUT_TOKENS } from '../context/accounting.js';
 import { shouldRemind, reminderForTodos } from '../context/memory.js';
 import { ratesFor, isAnthropicModel } from '../providers/model-info.js';
 import { classifyFailure, rerunOnce, gatherRepairContext, guardRepair } from '../verification/classify.js';
@@ -186,6 +186,16 @@ export async function run(opts, deps) {
         bus.emit(ev);
         tracer?.write(ev).catch(() => undefined);
     };
+    // Light audit writer: mirrors policy decisions + tool results into the
+    // chained audit log. Best-effort — audit errors must not break the run.
+    const auditLog = opts.audit?.log;
+    const auditSessionId = opts.audit?.sessionId ?? opts.persist?.sessionId;
+    const writeAudit = (ev) => {
+        if (!auditLog || !auditSessionId)
+            return;
+        // fire-and-forget — the log serializes its own chain internally
+        void auditLog.write(ev).catch(() => undefined);
+    };
     const closeTracer = async () => {
         try {
             await tracer?.close();
@@ -279,6 +289,10 @@ export async function run(opts, deps) {
     const fileEditCounts = new Map();
     let stuckTriggers = 0;
     let stuckAbort = false;
+    // Steerable stop: a stop hook's `{"continue":true}` verdict carries one
+    // more turn. Consumed once at the completion point, max 3 per run.
+    let stopCont = null;
+    let stopContUsed = 0;
     outer: while (steps < maxSteps) {
         // 5.1 limits: max-cost, max-time
         if (maxCost !== undefined) {
@@ -358,7 +372,7 @@ export async function run(opts, deps) {
         const systemForBudget = telemetrySuffix ? `${stableSystem}\n\n${telemetrySuffix}` : stableSystem;
         // Window-aware ceiling (was a hardcoded 120k that overflowed 8k local
         // models): size the input budget to the model's context window.
-        const BUDGET = { total: capForModel(opts.model, 4000), reservedOutput: 4000 };
+        const BUDGET = { total: capForModel(opts.model, RESERVE_OUTPUT_TOKENS), reservedOutput: RESERVE_OUTPUT_TOKENS };
         let reqMessages = transcript;
         let reqSystem = stableSystem;
         let reqSuffix = telemetrySuffix;
@@ -464,7 +478,7 @@ export async function run(opts, deps) {
                     telemetry.recordError('overflow_retry');
                     emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'REQUEST_TOO_LARGE', message: 'context overflow — aggressively compacting transcript and retrying the request once' });
                     try {
-                        const compacted = compressTranscript(reqSystem, transcript, { total: 30_000, reservedOutput: 4000 });
+                        const compacted = compressTranscript(reqSystem, transcript, { total: 30_000, reservedOutput: RESERVE_OUTPUT_TOKENS });
                         if (compacted.messages.length < transcript.length || compacted.dropped > 0) {
                             transcript.splice(0, transcript.length, ...compacted.messages);
                         }
@@ -472,7 +486,7 @@ export async function run(opts, deps) {
                             // Transcript already fits the aggressive budget — force it
                             // strictly smaller so the retry cannot repeat the overflow.
                             const halved = Math.max(4000, Math.floor(totalTokens(reqSystem, transcript) / 2));
-                            const smaller = compressTranscript(reqSystem, transcript, { total: halved, reservedOutput: 4000 });
+                            const smaller = compressTranscript(reqSystem, transcript, { total: halved, reservedOutput: RESERVE_OUTPUT_TOKENS });
                             transcript.splice(0, transcript.length, ...smaller.messages);
                         }
                         tokenCache = { lastRef: null, lastSystem: undefined, lastCount: 0 };
@@ -603,6 +617,17 @@ export async function run(opts, deps) {
             return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
         }
         if (finalizedCalls.length === 0) {
+            // Steerable stop: a stop hook asked for one more turn instead of
+            // completing. Consumed once per verdict, max 3 per run.
+            if (stopCont !== null && stopContUsed < 3) {
+                stopContUsed++;
+                const contMsg = { role: 'user', content: [text(`[system note] ${stopCont}`)] };
+                stopCont = null;
+                transcript.push(contMsg);
+                await checkpoint(contMsg);
+                emit?.({ kind: 'step_end', step: steps });
+                continue;
+            }
             if (hadInvalidTool) {
                 // The model attempted a tool call that failed validation; the error is
                 // already a tool_result in the transcript — loop so the model can
@@ -902,6 +927,7 @@ export async function run(opts, deps) {
                 else {
                     emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: decision.action, reason: decision.reason });
                 }
+                writeAudit({ kind: 'policy_decision', sessionId: auditSessionId ?? 'ephemeral', callId: call.id, action: decision.action, ts: Date.now() });
                 if (decision.action === 'deny') {
                     const denyMsg = {
                         role: 'tool',
@@ -990,29 +1016,40 @@ export async function run(opts, deps) {
             // Hooks: matching preToolUse hooks run before execution. A non-zero
             // exit denies the tool with POLICY_DENIED — the real tool never runs.
             // Matchers scope hooks per tool; stdin carries the structured payload.
+            // A structured JSON verdict wins over the exit code: deny blocks with
+            // its message, allow+context attaches model-visible context.
+            const hookContext = [];
             const matchingPre = hooksForEvent(runHooks, 'preToolUse', call.name);
             if (matchingPre.length > 0) {
                 for (const hook of matchingPre) {
                     let exitCode = -1;
                     let detail = '';
+                    let verdict;
                     try {
                         const r = await runHook(hook, { toolName: call.name, input: call.input }, { event: 'preToolUse', tool: call.name, input: call.input, sessionId, cwd: opts.cwd });
                         exitCode = r.exitCode;
                         detail = (r.stderr || r.stdout || '').slice(0, 300);
+                        if (r.verdict)
+                            verdict = r.verdict;
                     }
                     catch (err) {
                         detail = String(err instanceof Error ? err.message : err).slice(0, 300);
                     }
-                    if (exitCode !== 0) {
-                        const reason = `hook ${hook.name} denied: ${detail || 'hook failed'}`;
+                    if (verdict?.decision === 'deny' || exitCode !== 0) {
+                        const reason = `hook ${hook.name} denied: ${verdict?.message || detail || 'hook failed'}`;
                         emit?.({ kind: 'policy_decision', id: call.id, name: call.name, action: 'deny', reason });
                         emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: 'deny', reason });
                         const latencyMs = Date.now() - t0;
                         return {
                             obs: { ok: false, error: { code: 'POLICY_DENIED', message: reason } },
                             latencyMs,
+                            hookContext,
                         };
                     }
+                    // Allow verdicts may carry model-visible context (sliced at parse).
+                    if (verdict?.decision !== 'deny' && typeof verdict?.context === 'string' && verdict.context) {
+                        hookContext.push({ hook: hook.name, context: verdict.context });
+                    }
                 }
             }
             let obs;
@@ -1023,7 +1060,7 @@ export async function run(opts, deps) {
                 obs = { ok: false, error: { code: 'EXEC_CRASH', message: err instanceof Error ? err.message : String(err) } };
             }
             const latencyMs = Date.now() - t0;
-            return { obs, latencyMs };
+            return { obs, latencyMs, hookContext };
         };
         // 5.2 stuck termination (P0-3): the FIRST detection injects one
         // "change approach" synthetic message for the next model turn; the SECOND
@@ -1044,7 +1081,7 @@ export async function run(opts, deps) {
         };
         // Commit phase: fold one execution result into the transcript, in original
         // call order. The only writer — call sequentially, never concurrently.
-        const commitResult = async (call, obs, latencyMs) => {
+        const commitResult = async (call, obs, latencyMs, hookContext = []) => {
             const output = obs.ok ? redactOutput(obs.value) : redactOutput({ error: obs.error });
             const toolMsg = {
                 role: 'tool',
@@ -1052,6 +1089,16 @@ export async function run(opts, deps) {
             };
             transcript.push(toolMsg);
             await checkpoint(toolMsg, { toolCallId: call.id, toolName: call.name, input: call.input, output, isError: !obs.ok });
+            // Hook-injected context rides as its own user message right after the
+            // tool result (uniform across output shapes — no result surgery).
+            if (hookContext.length > 0) {
+                const note = {
+                    role: 'user',
+                    content: [text(hookContext.map((h) => `[hook ${h.hook} context]\n${h.context}`).join('\n\n'))],
+                };
+                transcript.push(note);
+                await checkpoint(note);
+            }
             if (obs.ok) {
                 telemetry.recordToolCall(call, latencyMs, false);
                 if (call.name === 'write_file' || call.name === 'edit_file' || call.name === 'multi_edit' || call.name === 'apply_patch') {
@@ -1074,6 +1121,8 @@ export async function run(opts, deps) {
             }
             emitKlyro({ type: 'tool.result', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, output, isError: !obs.ok, latencyMs });
             emit?.({ kind: 'tool_result', id: call.id, name: call.name, output, isError: !obs.ok, latencyMs });
+            // Light audit: every executed call completes into the chained log.
+            writeAudit({ kind: 'tool_call_completed', sessionId: auditSessionId ?? 'ephemeral', callId: call.id, isError: !obs.ok, latencyMs, ts: Date.now() });
             if (obs.ok) {
                 const fileChanged = inferFileChanged(call.name, call.input, obs.value);
                 if (fileChanged) {
@@ -1133,8 +1182,8 @@ export async function run(opts, deps) {
         const runOne = async (call) => {
             if (!(await gateCall(call)))
                 return;
-            const { obs, latencyMs } = await execTool(call);
-            await commitResult(call, obs, latencyMs);
+            const { obs, latencyMs, hookContext } = await execTool(call);
+            await commitResult(call, obs, latencyMs, hookContext);
         };
         // 3.5 — parallel when every call is concurrencySafe, sequential otherwise.
         // Gate runs sequentially in both paths (approval UI is one-at-a-time).
@@ -1164,7 +1213,7 @@ export async function run(opts, deps) {
                 for (let i = 0; i < settled.length; i++) {
                     const s = settled[i];
                     if (s.status === 'fulfilled') {
-                        await commitResult(approved[i], s.value.obs, s.value.latencyMs);
+                        await commitResult(approved[i], s.value.obs, s.value.latencyMs, s.value.hookContext);
                     }
                     else {
                         await commitResult(approved[i], { ok: false, error: { code: 'EXEC_CRASH', message: String(s.reason) } }, 0);
@@ -1193,8 +1242,11 @@ export async function run(opts, deps) {
             }
         }
         catch { /* ignore — completions are best-effort visibility */ }
-        // stop hooks: run once per completed step (blocking, side effects only —
-        // output is logged, never injected into the transcript).
+        // stop hooks: run once per completed step (blocking). A structured
+        // `{"continue": true, "message": ...}` verdict asks for one more turn
+        // instead of completing — consumed at the completion point below,
+        // bounded to 3 continuations per run so a hook can't loop forever.
+        stopCont = null; // fresh verdict per step; stale ones never carry over
         for (const hook of hooksForEvent(runHooks, 'stop')) {
             try {
                 const r = await runHook(hook, { toolName: '', input: {} }, { event: 'stop', sessionId, cwd: opts.cwd, step: steps, status: 'open' });
@@ -1204,6 +1256,11 @@ export async function run(opts, deps) {
                     }
                     catch { /* ignore */ }
                 }
+                else if (r.verdict?.cont === true && stopContUsed < 3) {
+                    stopCont = typeof r.verdict.message === 'string' && r.verdict.message
+                        ? r.verdict.message
+                        : `stop hook ${hook.name} requested continuation`;
+                }
             }
             catch { /* ignore — stop hooks never fail the turn */ }
         }

package/dist/chat.d.ts

@@ -20,6 +20,8 @@ export interface ChatOptions {
 }
 /** Strip a trailing slash so we can append /chat/completions cleanly. */
 export declare function normalizeBaseURL(url: string): string;
+/** True for loopback hostnames (localhost / 127.0.0.0/8 / ::1). */
+export declare function isLoopbackHost(host: string): boolean;
 /**
  * Validate that the base URL is HTTPS (or localhost over HTTP for local LLMs).
  * Refuses to send the bearer token over a plaintext remote connection.
@@ -31,6 +33,14 @@ export declare function normalizeBaseURL(url: string): string;
 export declare function assertSafeBaseURL(url: string, opts?: {
     allowInsecure?: boolean;
 }): void;
+/**
+ * Remote MCP URL guard. Mirrors `assertSafeBaseURL`'s fail-closed posture but
+ * is named for MCP config/transports so callers do not have to import provider
+ * URL text.
+ */
+export declare function assertSafeRemoteURL(url: string, opts?: {
+    allowInsecure?: boolean;
+}): void;
 export declare function chat(prompt: string, system: string, modelOverride?: string, opts?: ChatOptions): Promise<void>;
 /**
  * Parse SSE frames and write text deltas to stdout. Handles

package/dist/chat.js

@@ -18,6 +18,17 @@ const MAX_ERROR_BODY_BYTES = 4_000;
 export function normalizeBaseURL(url) {
     return url.replace(/\/+$/, '');
 }
+/** True for loopback hostnames (localhost / 127.0.0.0/8 / ::1). */
+export function isLoopbackHost(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, '');
+    if (h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '0.0.0.0' || h === '::')
+        return true;
+    if (h.startsWith('127.')) {
+        const parts = h.split('.');
+        return parts.length === 4 && parts.every((p) => /^\d+$/.test(p) && Number(p) >= 0 && Number(p) <= 255);
+    }
+    return false;
+}
 /**
  * Validate that the base URL is HTTPS (or localhost over HTTP for local LLMs).
  * Refuses to send the bearer token over a plaintext remote connection.
@@ -41,14 +52,10 @@ export function assertSafeBaseURL(url, opts) {
         if (opts?.allowInsecure === true || process.env.KLYRO_ALLOW_INSECURE === '1')
             return;
         const host = parsed.hostname.toLowerCase();
-        // Allow loopback and private networks without extra flag
-        if (host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0' || host === '::' || host === '[::]')
+        // Allow loopback without flag (shared helper); private LAN ranges keep
+        // the provider-path behavior below.
+        if (isLoopbackHost(host))
             return;
-        if (host.startsWith('127.')) {
-            const parts = host.split('.');
-            if (parts.length === 4 && parts.every((p) => /^\d+$/.test(p) && Number(p) >= 0 && Number(p) <= 255))
-                return;
-        }
         // Private ranges 10/8, 192.168/16, 172.16-31/12
         if (/^10\.\d+\.\d+\.\d+$/.test(host))
             return;
@@ -62,6 +69,31 @@ export function assertSafeBaseURL(url, opts) {
     }
     throw new Error(`Unsupported KLYRO_BASE_URL protocol: ${parsed.protocol}`);
 }
+/**
+ * Remote MCP URL guard. Mirrors `assertSafeBaseURL`'s fail-closed posture but
+ * is named for MCP config/transports so callers do not have to import provider
+ * URL text.
+ */
+export function assertSafeRemoteURL(url, opts) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`invalid remote MCP URL: ${url}`);
+    }
+    if (parsed.protocol === 'https:')
+        return;
+    if (parsed.protocol === 'http:') {
+        if (isLoopbackHost(parsed.hostname))
+            return;
+        if (opts?.allowInsecure === true || process.env.KLYRO_ALLOW_INSECURE === '1')
+            return;
+        throw new Error(`Refusing to connect to remote MCP server over plaintext HTTP to ${parsed.hostname}. ` +
+            `Use https:// or a loopback URL, or set KLYRO_ALLOW_INSECURE=1 for this terminal only (not recommended).`);
+    }
+    throw new Error(`unsupported remote MCP URL protocol: ${parsed.protocol}`);
+}
 export async function chat(prompt, system, modelOverride, opts = {}) {
     const baseURL = opts.baseURL ?? process.env.KLYRO_BASE_URL ?? 'https://api.openai.com/v1';
     const apiKey = opts.apiKey ?? process.env.KLYRO_API_KEY;

package/dist/checkpoints/store.d.ts

@@ -21,6 +21,8 @@ export interface CheckpointInfo {
 }
 /** Numbered snapshot list for `/checkpoints` and the `/rewind` menu. */
 export declare function listCheckpointInfo(cwd: string): Promise<CheckpointInfo[]>;
+/** File paths a snapshot would restore (for `/rewind <n> preview`). */
+export declare function snapshotFiles(cwd: string, id: string): Promise<string[]>;
 export declare function diff(cwd: string, id?: string): Promise<string>;
 export declare function undo(cwd: string, n?: number): Promise<void>;
 export declare function rewind(cwd: string): Promise<void>;

package/dist/checkpoints/store.js

@@ -174,6 +174,18 @@ export async function listCheckpointInfo(cwd) {
     }
     return out;
 }
+/** File paths a snapshot would restore (for `/rewind <n> preview`). */
+export async function snapshotFiles(cwd, id) {
+    try {
+        const meta = JSON.parse(await fs.readFile(path.join(ckptDir(cwd), id, '.meta.json'), 'utf-8'));
+        const files = Array.isArray(meta.files) ? meta.files : [];
+        const missing = Array.isArray(meta.missing) ? meta.missing.map((f) => `${f} (deleted)`) : [];
+        return [...files, ...missing];
+    }
+    catch {
+        return [];
+    }
+}
 export async function diff(cwd, id) {
     const ckpts = await listCheckpoints(cwd);
     const target = id ?? ckpts[ckpts.length - 1];

package/dist/cli/auth.d.ts

@@ -1,10 +1,17 @@
 /**
  * 2.2 — klyro login / logout / aliases
- * Stores masked key → ~/.klyro/credentials.json 0600
+ * Stores masked key → OS keychain when available, else
+ * ~/.klyro/credentials.json 0600 (with refuse-on-lax-perms reads).
  */
 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>;
+/** Persist one provider key: OS keychain when available, else 0600 file. Never logs or returns the key. */
+export declare function saveKey(provider: string, key: string): Promise<'keychain' | 'file'>;
+/**
+ * Async key read: OS keychain first (when available), then the 0600 file
+ * (with refuse-on-lax-perms). Use in async paths (provider resolution,
+ * eval, setup); sync contexts keep `getStoredKey` (file only).
+ */
+export declare function getStoredKeyAsync(provider: string): Promise<string | undefined>;
 /** Which providers have stored keys (names only — never values). */
 export declare function storedProviders(): string[];
 export declare const LOGIN_DEFAULTS: Record<string, {

package/dist/cli/auth.js

@@ -1,6 +1,7 @@
 /**
  * 2.2 — klyro login / logout / aliases
- * Stores masked key → ~/.klyro/credentials.json 0600
+ * Stores masked key → OS keychain when available, else
+ * ~/.klyro/credentials.json 0600 (with refuse-on-lax-perms reads).
  */
 import * as fs from 'node:fs/promises';
 import * as fsSync from 'node:fs';
@@ -15,21 +16,44 @@ export function credPath() {
     const home = os.homedir() || process.cwd();
     return path.join(home, '.klyro', 'credentials.json');
 }
-/** Persist one provider key (0600). Never logs or returns the key. */
+/** Persist one provider key: OS keychain when available, else 0600 file. Never logs or returns the key. */
 export async function saveKey(provider, key) {
+    const trimmed = key.trim();
+    try {
+        const { keychainSet } = await import('./keychain.js');
+        if (await keychainSet(provider, trimmed))
+            return 'keychain';
+    }
+    catch { /* fall through to file */ }
     const creds = {};
     try {
         const raw = await fs.readFile(credPath(), 'utf-8');
         Object.assign(creds, JSON.parse(raw));
     }
     catch { /* ignore */ }
-    creds[provider] = key.trim();
+    creds[provider] = trimmed;
     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 */ }
+    return 'file';
+}
+/**
+ * Async key read: OS keychain first (when available), then the 0600 file
+ * (with refuse-on-lax-perms). Use in async paths (provider resolution,
+ * eval, setup); sync contexts keep `getStoredKey` (file only).
+ */
+export async function getStoredKeyAsync(provider) {
+    try {
+        const { keychainGet } = await import('./keychain.js');
+        const v = await keychainGet(provider);
+        if (v)
+            return v;
+    }
+    catch { /* fall through to file */ }
+    return getStoredKey(provider);
 }
 /** Which providers have stored keys (names only — never values). */
 export function storedProviders() {
@@ -78,8 +102,10 @@ export async function runLogin() {
             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`);
+                const where = await saveKey(storeProvider, key);
+                process.stdout.write(where === 'keychain'
+                    ? `Saved ${storeProvider} key to the OS keychain\n`
+                    : `Saved ${storeProvider} key to ${credPath()} (0600)\n`);
             }
             // Persist non-secret settings (merged with existing config, never clobbers).
             const { loadConfig, saveConfig } = await import('./config.js');
@@ -106,6 +132,18 @@ export async function runLogin() {
     }
 }
 export async function runLogout(provider) {
+    // Best-effort keychain removal first (a keychain-held key must not survive
+    // a file-only logout).
+    try {
+        const { keychainDelete } = await import('./keychain.js');
+        if (provider)
+            await keychainDelete(provider);
+        else {
+            await keychainDelete('openai');
+            await keychainDelete('anthropic');
+        }
+    }
+    catch { /* ignore */ }
     try {
         const raw = await fs.readFile(credPath(), 'utf-8');
         const creds = JSON.parse(raw);

package/dist/cli/doctor.js

@@ -198,7 +198,6 @@ export async function runDoctor(opts = {}) {
     process.stdout.write('─'.repeat(40) + '\n');
     for (const c of checks) {
         const glyph = c.ok ? '✓' : '✗';
-        const color = c.ok ? '' : '';
         process.stdout.write(`${glyph} ${c.name.padEnd(14)} ${c.detail}\n`);
     }
     process.stdout.write('─'.repeat(40) + '\n');