klyro 1.0.0 → 1.0.1

package/dist/mcp/client.js

@@ -7,7 +7,7 @@
  * failures and server errors surface as typed `McpError`s — never throws
  * raw across the boundary.
  */
-import { spawn } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 export class McpError extends Error {
     code;
     details;
@@ -21,6 +21,10 @@ export class McpError extends Error {
 const PROTOCOL_VERSION = '2024-11-05';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_STDERR_BYTES = 8192;
+/** Upper bound on spawn + initialize handshake; partial children are killed. */
+const CONNECT_TIMEOUT_MS = 15_000;
+/** Grace period between SIGTERM and SIGKILL in close(). */
+const CLOSE_SIGKILL_AFTER_MS = 2000;
 export class McpClient {
     name;
     spec;
@@ -54,6 +58,12 @@ export class McpClient {
                 return;
             }
             this.child = child;
+            // Swallow async stream errors (e.g. EPIPE on write-after-exit):
+            // request promises already surface failures via write callbacks and
+            // the exit handler, so these must never become uncaught exceptions.
+            child.stdin?.on('error', () => { });
+            child.stdout?.on('error', () => { });
+            child.stderr?.on('error', () => { });
             child.on('error', (err) => {
                 this.failAll(new McpError(`mcp server "${this.name}" process error: ${err.message}`, 'SPAWN_FAILED'));
                 if (!this.connected)
@@ -73,13 +83,29 @@ export class McpClient {
             resolve();
         });
         try {
-            await this.request('initialize', {
-                protocolVersion: PROTOCOL_VERSION,
-                capabilities: {},
-                clientInfo: { name: 'klyro', version: '1.0.0' },
-            }, timeoutMs);
-            this.notify('notifications/initialized', {});
-            this.connected = true;
+            let connectTimer;
+            try {
+                await Promise.race([
+                    (async () => {
+                        await this.request('initialize', {
+                            protocolVersion: PROTOCOL_VERSION,
+                            capabilities: {},
+                            clientInfo: { name: 'klyro', version: '1.0.1' },
+                        }, timeoutMs);
+                        this.notify('notifications/initialized', {});
+                        this.connected = true;
+                    })(),
+                    new Promise((_resolve, reject) => {
+                        connectTimer = setTimeout(() => {
+                            reject(new McpError(`mcp server "${this.name}" connect timed out after ${CONNECT_TIMEOUT_MS}ms`, 'TIMEOUT'));
+                        }, CONNECT_TIMEOUT_MS);
+                    }),
+                ]);
+            }
+            finally {
+                if (connectTimer)
+                    clearTimeout(connectTimer);
+            }
         }
         catch (err) {
             await this.close();
@@ -87,9 +113,9 @@ export class McpClient {
         }
     }
     connected = false;
-    async listTools() {
+    async listTools(signal) {
         this.assertLive();
-        const res = (await this.request('tools/list', {}, this.timeout()));
+        const res = (await this.request('tools/list', {}, this.timeout(), signal));
         return Array.isArray(res.tools) ? res.tools : [];
     }
     async callTool(name, args, signal) {
@@ -99,9 +125,9 @@ export class McpClient {
         const text = blocks.map((b) => (typeof b.text === 'string' ? b.text : JSON.stringify(b))).join('\n');
         return { text, isError: res.isError === true, raw: res };
     }
-    async listResources() {
+    async listResources(signal) {
         this.assertLive();
-        const res = (await this.request('resources/list', {}, this.timeout()));
+        const res = (await this.request('resources/list', {}, this.timeout(), signal));
         return Array.isArray(res.resources) ? res.resources : [];
     }
     async readResource(uri, signal) {
@@ -111,16 +137,49 @@ export class McpClient {
         return contents.map((c) => (typeof c.text === 'string' ? c.text : JSON.stringify(c))).join('\n');
     }
     async close() {
+        // Idempotent vs the exit handler: closed is set FIRST (the on('exit')
+        // callback checks it before failAll), and a second close() with no child
+        // left is a no-op.
+        if (this.closed && this.child === null)
+            return;
         this.closed = true;
         this.failAll(new McpError(`mcp server "${this.name}" closed`, 'CLOSED'));
         const child = this.child;
         this.child = null;
-        if (child && !child.killed) {
+        if (!child)
+            return;
+        // Already reaped — no escalation timer needed.
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        if (process.platform === 'win32') {
+            try {
+                if (child.pid !== undefined) {
+                    execFileSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+                }
+            }
+            catch { /* ignore — fall through to kill() */ }
             try {
                 child.kill();
             }
             catch { /* ignore */ }
+            return;
+        }
+        try {
+            child.kill('SIGTERM');
         }
+        catch { /* already gone */ }
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+        }, CLOSE_SIGKILL_AFTER_MS);
+        timer.unref?.();
+        child.once('exit', () => clearTimeout(timer));
+    }
+    /** Test hook: number of in-flight JSON-RPC requests. */
+    pendingCount() {
+        return this.pending.size;
     }
     /* ---------------- internals ---------------- */
     timeout() {
@@ -154,7 +213,8 @@ export class McpClient {
                 continue;
             this.pending.delete(msg.id);
             clearTimeout(pend.timer);
-            pend.signal?.removeEventListener('abort', pend.onAbort);
+            if (pend.signal && pend.onAbort)
+                pend.signal.removeEventListener('abort', pend.onAbort);
             if (msg.error) {
                 pend.reject(new McpError(`mcp server "${this.name}" error: ${msg.error.message ?? 'unknown'}`, 'SERVER_ERROR', msg.error));
             }
@@ -181,6 +241,9 @@ export class McpClient {
             }
             const id = this.nextId++;
             const timer = setTimeout(() => {
+                const p = this.pending.get(id);
+                if (p?.signal && p.onAbort)
+                    p.signal.removeEventListener('abort', p.onAbort);
                 this.pending.delete(id);
                 reject(new McpError(`mcp call "${method}" timed out after ${timeoutMs}ms`, 'TIMEOUT'));
             }, timeoutMs);
@@ -202,6 +265,8 @@ export class McpClient {
                     if (err) {
                         this.pending.delete(id);
                         clearTimeout(timer);
+                        if (signal && pend.onAbort)
+                            signal.removeEventListener('abort', pend.onAbort);
                         reject(new McpError(`mcp call "${method}" write failed: ${err.message}`, 'IO_ERROR'));
                     }
                 });
@@ -209,6 +274,8 @@ export class McpClient {
             catch (err) {
                 this.pending.delete(id);
                 clearTimeout(timer);
+                if (signal && pend.onAbort)
+                    signal.removeEventListener('abort', pend.onAbort);
                 reject(new McpError(`mcp call "${method}" write failed: ${err instanceof Error ? err.message : String(err)}`, 'IO_ERROR'));
             }
         });
@@ -219,6 +286,8 @@ export class McpClient {
         for (const [id, pend] of [...this.pending]) {
             this.pending.delete(id);
             clearTimeout(pend.timer);
+            if (pend.signal && pend.onAbort)
+                pend.signal.removeEventListener('abort', pend.onAbort);
             pend.reject(err);
         }
     }

package/dist/mcp/config.d.ts

@@ -24,6 +24,16 @@ export interface McpServersConfig {
     /** Where each server entry came from (for doctor/diagnostics). */
     sources: Record<string, string>;
 }
+/** Upper bound for per-server timeouts — larger values are clamped, not rejected. */
+export declare const MAX_MCP_TIMEOUT_MS = 600000;
+/**
+ * Expand `${env:VAR}` references from `process.env`.
+ *
+ * A reference to an UNSET or empty variable expands to `''` (silent empty
+ * expansion): the entry is kept with the empty value rather than rejected,
+ * so callers always see the effective spec. Pure — exported for unit tests.
+ */
+export declare function expandEnv(value: string): string;
 /** Load + merge global and project MCP server specs. Invalid entries are skipped. */
 export declare function loadMcpServers(cwd: string): McpServersConfig;
 /** Servers eligible for connection (configured and not disabled). */

package/dist/mcp/config.js

@@ -25,7 +25,16 @@ export const McpServerSpecSchema = z.object({
     disabled: z.boolean().optional(),
     policy: McpServerPolicySchema.optional(),
 });
-function expandEnv(value) {
+/** Upper bound for per-server timeouts — larger values are clamped, not rejected. */
+export const MAX_MCP_TIMEOUT_MS = 600_000;
+/**
+ * Expand `${env:VAR}` references from `process.env`.
+ *
+ * A reference to an UNSET or empty variable expands to `''` (silent empty
+ * expansion): the entry is kept with the empty value rather than rejected,
+ * so callers always see the effective spec. Pure — exported for unit tests.
+ */
+export function expandEnv(value) {
     return value.replace(/\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => process.env[name] ?? '');
 }
 function normalizeRaw(raw) {
@@ -55,10 +64,18 @@ export function loadMcpServers(cwd) {
     for (const [filePath, label] of [[globalPath, 'global'], [projectPath, 'project']]) {
         const raw = normalizeRaw(readJsonFile(filePath));
         for (const [name, specRaw] of Object.entries(raw)) {
+            // Empty server names can never produce a valid tool name — skip
+            // silently (shape stays `{servers, sources}`; registry reports
+            // empty TOOL names as errors at registration time).
+            if (name === '')
+                continue;
             const parsed = McpServerSpecSchema.safeParse(specRaw);
             if (!parsed.success)
                 continue;
             const spec = parsed.data;
+            if (spec.policy?.timeoutMs !== undefined && spec.policy.timeoutMs > MAX_MCP_TIMEOUT_MS) {
+                spec.policy.timeoutMs = MAX_MCP_TIMEOUT_MS;
+            }
             if (spec.env) {
                 const env = {};
                 for (const [k, v] of Object.entries(spec.env))

package/dist/mcp/registry.d.ts

@@ -37,7 +37,16 @@ export interface RegisterMcpOpts {
     policy?: PolicyEngine;
     clientFactory?: (name: string, spec: McpServerSpec) => McpClientLike;
 }
-/** `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64. */
+/** Success values are redacted FIRST, then truncated to this many chars. */
+export declare const MCP_SUCCESS_MAX_CHARS = 12000;
+/**
+ * `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64.
+ *
+ * No `'server'`/`'tool'` fallbacks: an empty raw part (or one that
+ * sanitizes to empty) yields an empty segment, and registration skips that
+ * tool with an `empty-name` error instead of masking a misconfiguration
+ * behind a plausible-looking name.
+ */
 export declare function sanitizeMcpName(server: string, tool: string): string;
 export declare function registerMcpServers(cfg: {
     servers: Record<string, McpServerSpec>;
@@ -47,4 +56,17 @@ export declare function loadAndRegisterMcp(opts: {
     registry: ToolRegistry;
     policy?: PolicyEngine;
     clientFactory?: (name: string, spec: McpServerSpec) => McpClientLike;
+    /**
+     * Consent gate for project-sourced (`.mcp.json`) servers, which can
+     * auto-spawn processes. Global-source servers connect as before; a project
+     * server connects ONLY when this callback returns true. When the callback
+     * is ABSENT, project servers are never auto-connected — each surfaces as
+     * an error (`project server requires approval (skipped)`) so the skip is
+     * visible. Callers may compose this with `McpTrust` (see `./trust.js`) to
+     * remember approvals per spec hash.
+     */
+    approveProjectServer?: (info: {
+        name: string;
+        source: 'global' | 'project';
+    }) => Promise<boolean>;
 }): Promise<McpRegisterResult>;

package/dist/mcp/registry.js

@@ -26,14 +26,23 @@ import { defineTool } from '../tools/types.js';
 const MAX_NAME_LEN = 64;
 /** Server part is capped here; the tool part takes whatever remains. */
 const MAX_SERVER_PART = 20;
+/** Success values are redacted FIRST, then truncated to this many chars. */
+export const MCP_SUCCESS_MAX_CHARS = 12_000;
 function sanitizePart(s) {
     return s.replace(/[^A-Za-z0-9_]/g, '_');
 }
-/** `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64. */
+/**
+ * `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64.
+ *
+ * No `'server'`/`'tool'` fallbacks: an empty raw part (or one that
+ * sanitizes to empty) yields an empty segment, and registration skips that
+ * tool with an `empty-name` error instead of masking a misconfiguration
+ * behind a plausible-looking name.
+ */
 export function sanitizeMcpName(server, tool) {
-    const srv = sanitizePart(server).slice(0, MAX_SERVER_PART) || 'server';
+    const srv = sanitizePart(server).slice(0, MAX_SERVER_PART);
     const maxTool = Math.max(1, MAX_NAME_LEN - 'mcp__'.length - srv.length - '__'.length);
-    const tl = sanitizePart(tool).slice(0, maxTool) || 'tool';
+    const tl = sanitizePart(tool).slice(0, maxTool);
     return `mcp__${srv}__${tl}`;
 }
 function errMessage(err) {
@@ -66,8 +75,17 @@ async function executeMcpTool(spec, toolDef, client, input, ctx) {
         if (res.isError) {
             return { ok: false, error: { code: 'TOOL_ERROR', message: redact(res.text).slice(0, 2000) } };
         }
-        // (5) Success — redact BEFORE the value reaches the model/trace.
-        return { ok: true, value: redact(res.text) };
+        // (5) Success — redact BEFORE the value reaches the model/trace, then
+        // truncate to a bounded size with a marker.
+        const redacted = redact(res.text);
+        if (redacted.length > MCP_SUCCESS_MAX_CHARS) {
+            return {
+                ok: true,
+                value: redacted.slice(0, MCP_SUCCESS_MAX_CHARS) +
+                    `\n... [truncated ${redacted.length - MCP_SUCCESS_MAX_CHARS} chars]`,
+            };
+        }
+        return { ok: true, value: redacted };
     }
     catch (err) {
         // Tool contract: never throw — always return a ToolResult.
@@ -81,6 +99,9 @@ export async function registerMcpServers(cfg, opts) {
     const errors = [];
     const skipped = [];
     const clients = [];
+    // Sanitized name → first raw (server, tool) that claimed it, used to tell
+    // sanitization-collisions apart from exact-duplicates (see below).
+    const claimed = new Map();
     for (const [server, spec] of Object.entries(cfg.servers)) {
         try {
             // enabledServers-style: skip disabled entries silently.
@@ -116,11 +137,35 @@ export async function registerMcpServers(cfg, opts) {
             }
             clients.push(client);
             for (const toolDef of tools) {
+                // Empty raw names (or names that sanitize to empty) are a
+                // misconfiguration — skip as an error, never with a fallback name.
+                if (!server || !toolDef.name || sanitizePart(server) === '' || sanitizePart(toolDef.name) === '') {
+                    errors.push({ server, message: `empty-name: server "${server}" tool "${toolDef.name}" sanitizes to an empty name part (skipped)` });
+                    continue;
+                }
                 const name = sanitizeMcpName(server, toolDef.name);
+                const prior = claimed.get(name);
+                if (prior) {
+                    if (prior.server === server && prior.tool === toolDef.name) {
+                        skipped.push({ name, reason: 'name-collision' });
+                        continue;
+                    }
+                    // Sanitization-collision: two DIFFERENT raw names map to the same
+                    // sanitized name. This is an error (not a silent skip) and names
+                    // both raw identities so the conflict is actionable.
+                    errors.push({
+                        server,
+                        message: `name collision: "${prior.server}/${prior.tool}" and "${server}/${toolDef.name}" both sanitize to "${name}" (skipped)`,
+                    });
+                    continue;
+                }
                 if (registry.get(name)) {
+                    // Exact-duplicate: the literal name already exists (e.g. a
+                    // builtin) — skip quietly, first registration wins.
                     skipped.push({ name, reason: 'name-collision' });
                     continue;
                 }
+                claimed.set(name, { server, tool: toolDef.name });
                 // Capture per-tool bindings for the closure.
                 const boundSpec = spec;
                 const boundDef = toolDef;
@@ -158,7 +203,34 @@ export async function registerMcpServers(cfg, opts) {
 export async function loadAndRegisterMcp(opts) {
     try {
         const cfg = loadMcpServers(opts.cwd);
-        return await registerMcpServers(cfg, opts);
+        const filtered = {};
+        const gateErrors = [];
+        for (const [name, spec] of Object.entries(cfg.servers)) {
+            if (cfg.sources[name] !== 'project') {
+                filtered[name] = spec;
+                continue;
+            }
+            if (!opts.approveProjectServer) {
+                gateErrors.push({ server: name, message: 'project server requires approval (skipped)' });
+                continue;
+            }
+            let ok = false;
+            try {
+                ok = await opts.approveProjectServer({ name, source: 'project' });
+            }
+            catch (err) {
+                gateErrors.push({ server: name, message: `project server approval error (skipped): ${errMessage(err)}` });
+                continue;
+            }
+            if (!ok) {
+                gateErrors.push({ server: name, message: 'project server not approved (skipped)' });
+                continue;
+            }
+            filtered[name] = spec;
+        }
+        const res = await registerMcpServers({ servers: filtered }, opts);
+        res.errors.unshift(...gateErrors);
+        return res;
     }
     catch (err) {
         // Never throws — surface load failures as error entries.

package/dist/mcp/schema.d.ts

@@ -2,10 +2,17 @@
  * P1 — JSON Schema → Zod converter for MCP tool input schemas.
  *
  * MCP servers describe inputs with JSON Schema; Klyro tools validate with
- * Zod. This converts the common subset (object/string/number/integer/
- * boolean/array/enum + required) and falls back to a permissive
- * `z.looseObject({}).catchall(z.unknown())`-style schema for anything else —
- * validation must never trust, but must also never crash on exotic schemas.
+ * Zod. Supported subset:
+ *
+ *   - `type`: `object` (with `properties` + `required`), `string`,
+ *     `number`, `integer`, `boolean`, `array` (with `items`)
+ *   - string `enum` (handled before `type`)
+ *   - a schema object WITHOUT a `type` but WITH a `properties` map is
+ *     treated as `type: 'object'` (many servers omit the type)
+ *
+ * Anything else — an empty/absent schema, non-object input, an unknown
+ * `type` — falls back to `z.unknown()` (accept anything, validate nothing).
+ * Validation must never trust, but must also never crash on exotic schemas.
  */
 import { z } from 'zod';
 export declare function jsonSchemaToZod(schema: unknown): z.ZodTypeAny;

package/dist/mcp/schema.js

@@ -2,22 +2,43 @@
  * P1 — JSON Schema → Zod converter for MCP tool input schemas.
  *
  * MCP servers describe inputs with JSON Schema; Klyro tools validate with
- * Zod. This converts the common subset (object/string/number/integer/
- * boolean/array/enum + required) and falls back to a permissive
- * `z.looseObject({}).catchall(z.unknown())`-style schema for anything else —
- * validation must never trust, but must also never crash on exotic schemas.
+ * Zod. Supported subset:
+ *
+ *   - `type`: `object` (with `properties` + `required`), `string`,
+ *     `number`, `integer`, `boolean`, `array` (with `items`)
+ *   - string `enum` (handled before `type`)
+ *   - a schema object WITHOUT a `type` but WITH a `properties` map is
+ *     treated as `type: 'object'` (many servers omit the type)
+ *
+ * Anything else — an empty/absent schema, non-object input, an unknown
+ * `type` — falls back to `z.unknown()` (accept anything, validate nothing).
+ * Validation must never trust, but must also never crash on exotic schemas.
  */
 import { z } from 'zod';
+function objectFrom(s) {
+    const props = s['properties'] ?? {};
+    const required = new Set(Array.isArray(s['required']) ? s['required'].filter((v) => typeof v === 'string') : []);
+    const shape = {};
+    for (const [k, v] of Object.entries(props)) {
+        const inner = jsonSchemaToZod(v);
+        shape[k] = required.has(k) ? inner : inner.optional();
+    }
+    return z.looseObject(shape);
+}
 export function jsonSchemaToZod(schema) {
     if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
-        return z.looseObject({}).catchall(z.unknown());
+        return z.unknown();
     }
     const s = schema;
     const enumerated = Array.isArray(s['enum']) ? s['enum'] : undefined;
     if (enumerated && enumerated.length > 0 && enumerated.every((v) => typeof v === 'string')) {
         return z.enum(enumerated);
     }
-    switch (s['type']) {
+    const t = s['type'];
+    if (t === 'object' || (t === undefined && s['properties'] !== undefined && typeof s['properties'] === 'object' && s['properties'] !== null && !Array.isArray(s['properties']))) {
+        return objectFrom(s);
+    }
+    switch (t) {
         case 'string':
             return z.string();
         case 'number':
@@ -30,16 +51,6 @@ export function jsonSchemaToZod(schema) {
             const items = jsonSchemaToZod(s['items']);
             return z.array(items);
         }
-        case 'object': {
-            const props = s['properties'] ?? {};
-            const required = new Set(Array.isArray(s['required']) ? s['required'].filter((v) => typeof v === 'string') : []);
-            const shape = {};
-            for (const [k, v] of Object.entries(props)) {
-                const inner = jsonSchemaToZod(v);
-                shape[k] = required.has(k) ? inner : inner.optional();
-            }
-            return z.looseObject(shape);
-        }
         default:
             return z.unknown();
     }

package/dist/mcp/trust.d.ts

@@ -0,0 +1,20 @@
+import type { McpServerSpec } from './config.js';
+export interface McpTrustRecord {
+    sha256: string;
+    trustedAt: number;
+}
+export type McpTrustStore = Record<string, McpTrustRecord>;
+/** sha256 of the canonical (key-sorted) JSON encoding of a server spec. */
+export declare function hashSpec(spec: McpServerSpec): string;
+export declare function defaultMcpTrustStorePath(): string;
+export declare class McpTrust {
+    private readonly storePath;
+    private store;
+    constructor(storePath?: string);
+    private load;
+    private save;
+    /** True only when `name` was approved for exactly this spec hash. */
+    isTrusted(name: string, hash: string): boolean;
+    /** Record approval of `name` for exactly this spec hash. */
+    approve(name: string, hash: string): void;
+}

package/dist/mcp/trust.js

@@ -0,0 +1,74 @@
+/**
+ * P1 — MCP server-spec trust store (hash-based approval persistence).
+ *
+ * Companions the project-server consent gate in `registry.ts`: callers ask
+ * the user to approve a project-sourced server once via
+ * `approveProjectServer`, then persist `(name → sha256(spec))` here so later
+ * runs can auto-approve unchanged specs. Any spec change (new hash) requires
+ * fresh approval. Decisions persist in `~/.klyro/mcp-trust.json`.
+ *
+ * `registry.ts` does NOT use this class directly — callers compose it with
+ * the `approveProjectServer` callback. This module is intentionally
+ * side-effect free on import (file I/O happens in the constructor).
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Deterministic JSON: object keys sorted recursively, arrays preserved. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((v) => stableStringify(v)).join(',')}]`;
+    const entries = Object.entries(value)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+}
+/** sha256 of the canonical (key-sorted) JSON encoding of a server spec. */
+export function hashSpec(spec) {
+    return crypto.createHash('sha256').update(stableStringify(spec), 'utf-8').digest('hex');
+}
+export function defaultMcpTrustStorePath() {
+    return path.join(os.homedir() || process.cwd(), '.klyro', 'mcp-trust.json');
+}
+export class McpTrust {
+    storePath;
+    store = {};
+    constructor(storePath = defaultMcpTrustStorePath()) {
+        this.storePath = storePath;
+        this.load();
+    }
+    load() {
+        try {
+            const raw = fs.readFileSync(this.storePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                this.store = parsed;
+            }
+        }
+        catch {
+            this.store = {};
+        }
+    }
+    save() {
+        try {
+            fs.mkdirSync(path.dirname(this.storePath), { recursive: true });
+            fs.writeFileSync(this.storePath, JSON.stringify(this.store, null, 2), 'utf-8');
+        }
+        catch {
+            /* best-effort — trust stays in memory for the session */
+        }
+    }
+    /** True only when `name` was approved for exactly this spec hash. */
+    isTrusted(name, hash) {
+        const rec = this.store[name];
+        return !!rec && rec.sha256 === hash;
+    }
+    /** Record approval of `name` for exactly this spec hash. */
+    approve(name, hash) {
+        this.store[name] = { sha256: hash, trustedAt: Date.now() };
+        this.save();
+    }
+}

package/dist/persistence/audit.d.ts

@@ -2,6 +2,11 @@
  * Audit log — append-only JSONL of runtime events. Same shape as the
  * future durable-task scheduler will read, so the data layout is
  * forward-compatible.
+ *
+ * Durability: every record is hash-chained. Each line carries `prevHash`
+ * (hex sha256 of the previous line's canonical JSON, 'GENESIS' for the
+ * first line) and `hash` (sha256 of the record-with-prevHash canonical
+ * JSON). `verifyAuditChain` recomputes the chain for `klyro audit`.
  */
 export type AuditEvent = {
     kind: 'session_created';
@@ -68,8 +73,31 @@ export type AuditEvent = {
     attempt: number;
     ts: number;
 };
+export declare const AUDIT_GENESIS = "GENESIS";
+export interface ChainedAuditRecord {
+    prevHash: string;
+    hash: string;
+    [key: string]: unknown;
+}
+/** Canonical JSON: object keys sorted recursively, so hashes are stable. */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(s: string): string;
+/** Hash of a chained record excluding its own `hash` field. */
+export declare function hashAuditRecord(record: Record<string, unknown>): string;
 export declare class AuditLog {
     private readonly filePath;
+    /** Serializes chained appends so concurrent writes can't fork the chain. */
+    private chain;
     constructor(filePath: string);
     write(event: AuditEvent): Promise<void>;
+    private appendChained;
 }
+/**
+ * Recompute the hash chain of a session JSONL file.
+ * Sessions live at `<sessionsDir>/<sessionId>.jsonl` (see SessionStore).
+ */
+export declare function verifyAuditChain(sessionsDir: string, sessionId: string): Promise<{
+    ok: boolean;
+    events: number;
+    error?: string;
+}>;