klyro 0.1.63 → 1.0.1

package/dist/context/memory.js

@@ -1,15 +1,49 @@
 /**
  * 8.4 — Working memory & reminders: memory_write → .klyro/memory/session-notes.md (≤1k tokens) + todos re-inject
+ *
+ * Durability: writes are atomic (tmp + rename in the same dir) so a crash
+ * never leaves a half-written note file. Oversized single writes are
+ * rejected with an Error (the memory_write tool's safe() wrapper converts
+ * that into a ToolResult error) instead of being silently truncated.
  */
 import * as fs from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
 import * as path from 'node:path';
+import { redact } from '../policy/secret-redactor.js';
+/** Single-write ceiling — anything larger is rejected, not sliced. */
+export const MEMORY_WRITE_LIMIT_CHARS = 8000;
+/** Steady-state cap (~1k tokens ≈ 4k chars) kept via tail slice. */
+export const MEMORY_STEADY_STATE_CHARS = 4000;
 export async function memoryWrite(cwd, content) {
+    if (content.length > MEMORY_WRITE_LIMIT_CHARS) {
+        throw new Error(`memory budget exceeded: single write is ${content.length} chars (max ${MEMORY_WRITE_LIMIT_CHARS}) — split it into smaller notes`);
+    }
     const dir = path.join(cwd, '.klyro', 'memory');
     await fs.mkdir(dir, { recursive: true });
     const p = path.join(dir, 'session-notes.md');
     const prev = await fs.readFile(p, 'utf-8').catch(() => '');
-    const next = (prev + '\n' + content).slice(-4000); // ≤1k tokens ~4k chars
-    await fs.writeFile(p, next, 'utf-8');
+    // S4-at-rest: redact before appending — redact() only fires on secret
+    // shapes (key/token/password with [:=-]), so normal prose survives.
+    const next = (prev + '\n' + redact(content)).slice(-MEMORY_STEADY_STATE_CHARS); // ≤1k tokens ~4k chars
+    const tmp = path.join(dir, `.session-notes.md.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    await fs.writeFile(tmp, next, 'utf-8');
+    try {
+        const fh = await fs.open(tmp, 'r+');
+        try {
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    catch { /* ignore on Windows */ }
+    try {
+        await fs.rename(tmp, p);
+    }
+    catch {
+        await fs.unlink(tmp).catch(() => undefined);
+        throw new Error('Failed to write memory file');
+    }
     return p;
 }
 export async function loadMemory(cwd) {
@@ -20,6 +54,20 @@ export async function loadMemory(cwd) {
         return '';
     }
 }
+/** Synchronous read for the system-prompt build path (run on every turn). */
+export function loadMemorySync(cwd) {
+    try {
+        return readFileSync(path.join(cwd, '.klyro', 'memory', 'session-notes.md'), 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+/** Wrap persisted notes into the injected prompt block; '' when empty. */
+export function memoryBlock(cwd) {
+    const notes = loadMemorySync(cwd).trim();
+    return notes ? `\n\n<memory>\n${notes.slice(0, 4000)}\n</memory>` : '';
+}
 export function shouldRemind(turn, lastRemindTurn) {
     return turn - lastRemindTurn >= 20;
 }

package/dist/context/project-map.d.ts

@@ -45,6 +45,12 @@ export interface ProjectMap {
     hasDocker?: boolean;
     hasEnvExample?: boolean;
 }
+/**
+ * Dirty-tree fingerprint: max mtimeMs over a bounded walk (≤200 files,
+ * depth ≤4, ignored dirs skipped). Cheap enough to run on every cache
+ * lookup; any edit under the tree changes the key and busts the cache.
+ */
+export declare function dirtyMtime(root: string): Promise<number>;
 /** Build a project map for the repo rooted at `root`. */
 export declare function buildProjectMapCached(root: string): Promise<ProjectMap>;
 /** Build a project map for the repo rooted at `root`. */

package/dist/context/project-map.js

@@ -383,7 +383,8 @@ function lockfileHash(root) {
 async function getCachedProjectMap(root) {
     const head = await gitHead(root);
     const hash = lockfileHash(root);
-    const p = path.join(root, '.klyro', 'cache', `project-map-${head.slice(0, 8)}-${hash}.json`);
+    const dirty = await dirtyMtime(root);
+    const p = path.join(root, '.klyro', 'cache', `project-map-${head.slice(0, 8)}-${hash}-${dirty.toString(36)}.json`);
     try {
         const raw = await fs.readFile(p, 'utf-8');
         const j = JSON.parse(raw);
@@ -396,13 +397,60 @@ async function getCachedProjectMap(root) {
 async function setCachedProjectMap(root, m) {
     const head = await gitHead(root);
     const hash = lockfileHash(root);
-    const p = path.join(root, '.klyro', 'cache', `project-map-${head.slice(0, 8)}-${hash}.json`);
+    const dirty = await dirtyMtime(root);
+    const p = path.join(root, '.klyro', 'cache', `project-map-${head.slice(0, 8)}-${hash}-${dirty.toString(36)}.json`);
     try {
         await fs.mkdir(path.dirname(p), { recursive: true });
         await fs.writeFile(p, JSON.stringify(m, null, 2), 'utf-8');
     }
     catch { /* ignore */ }
 }
+/**
+ * Dirty-tree fingerprint: max mtimeMs over a bounded walk (≤200 files,
+ * depth ≤4, ignored dirs skipped). Cheap enough to run on every cache
+ * lookup; any edit under the tree changes the key and busts the cache.
+ */
+export async function dirtyMtime(root) {
+    let max = 0;
+    let seen = 0;
+    let stop = false;
+    async function walk(dir, depth) {
+        if (stop || depth > 4)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (stop)
+                return;
+            if (IGNORED_DIRS.has(e.name))
+                continue;
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                await walk(full, depth + 1);
+            }
+            else if (e.isFile()) {
+                seen++;
+                try {
+                    const s = await fs.stat(full);
+                    if (s.mtimeMs > max)
+                        max = s.mtimeMs;
+                }
+                catch { /* race */ }
+                if (seen >= 200) {
+                    stop = true;
+                    return;
+                }
+            }
+        }
+    }
+    await walk(root, 0);
+    return Math.floor(max);
+}
 function detectMonorepo(root, rootFiles, rootDirs) {
     if (rootFiles.has('pnpm-workspace.yaml') || rootFiles.has('lerna.json') || rootFiles.has('nx.json'))
         return true;

package/dist/context/repo-map.d.ts

@@ -18,6 +18,8 @@ export interface RepoFile {
     path: string;
     symbols: Symbol[];
 }
+/** Invalidate the repo-map cache (tests + callers that mutate the tree). */
+export declare function clearRepoMapCache(): void;
 /** Heuristic: walk cwd, return at most `maxFiles` files with symbols. */
 export declare function buildRepoMap(opts: {
     cwd: string;

package/dist/context/repo-map.js

@@ -12,11 +12,38 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 const SUPPORTED_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs']);
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.klyro', 'coverage', 'out']);
+const REPO_MAP_TTL_MS = 60_000;
+let repoMapCache = null;
+/** Invalidate the repo-map cache (tests + callers that mutate the tree). */
+export function clearRepoMapCache() {
+    repoMapCache = null;
+}
+/** Re-stat every file in the cached map; true when all stats still match. */
+async function repoMapStatsMatch(cwd, stats) {
+    for (const [rel, prev] of stats) {
+        try {
+            const s = await fs.stat(path.join(cwd, rel));
+            if (s.mtimeMs !== prev.mtimeMs || s.size !== prev.size)
+                return false;
+        }
+        catch {
+            return false; // deleted (or unreadable) — rebuild
+        }
+    }
+    return true;
+}
 /** Heuristic: walk cwd, return at most `maxFiles` files with symbols. */
 export async function buildRepoMap(opts) {
     const maxFiles = opts.maxFiles ?? 500;
     const maxFileBytes = opts.maxFileBytes ?? 256 * 1024;
+    const cached = repoMapCache;
+    if (cached && cached.cwd === opts.cwd && cached.maxFiles === maxFiles &&
+        cached.maxFileBytes === maxFileBytes && Date.now() - cached.at < REPO_MAP_TTL_MS &&
+        (await repoMapStatsMatch(opts.cwd, cached.stats))) {
+        return cached.files;
+    }
     const out = [];
+    const stats = new Map();
     await walk(opts.cwd, async (file) => {
         if (out.length >= maxFiles)
             return false;
@@ -39,9 +66,12 @@ export async function buildRepoMap(opts) {
         catch {
             return true;
         }
-        out.push({ path: path.relative(opts.cwd, file), symbols: extractSymbols(content, ext) });
+        const rel = path.relative(opts.cwd, file);
+        stats.set(rel, { mtimeMs: stat.mtimeMs, size: stat.size });
+        out.push({ path: rel, symbols: extractSymbols(content, ext) });
         return true;
     });
+    repoMapCache = { cwd: opts.cwd, maxFiles, maxFileBytes, files: out, stats, at: Date.now() };
     return out;
 }
 async function walk(dir, visit) {

package/dist/context/trust.d.ts

@@ -0,0 +1,42 @@
+import type { KlyroEvent } from '../events/catalog.js';
+import { type KlyroMdFile } from './klyro-md.js';
+export interface TrustRecord {
+    sha256: string;
+    trustedAt: number;
+}
+export type TrustStore = Record<string, TrustRecord>;
+export type TrustReason = 'unknown' | 'changed';
+export declare function hashContent(content: string): string;
+/** Pure evaluation: split files into trusted vs needs-approval. */
+export declare function evaluateTrust(stored: TrustStore, files: KlyroMdFile[]): {
+    trusted: KlyroMdFile[];
+    untrusted: {
+        file: KlyroMdFile;
+        reason: TrustReason;
+    }[];
+};
+export declare function defaultTrustStorePath(): string;
+export declare class ContextTrust {
+    private readonly storePath;
+    private store;
+    constructor(storePath?: string);
+    private load;
+    private save;
+    check(files: KlyroMdFile[]): ReturnType<typeof evaluateTrust>;
+    /** Record approval for the file's current content. */
+    approve(file: KlyroMdFile): void;
+    isTrusted(file: KlyroMdFile): boolean;
+}
+export interface TrustedLoadOpts {
+    trust: ContextTrust;
+    /** Return true to include an untrusted file (and persist the approval). */
+    approve: (file: KlyroMdFile, reason: TrustReason) => Promise<boolean>;
+    sessionId?: string;
+    emit?: (ev: KlyroEvent) => void;
+}
+/**
+ * Load KLYRO.md hierarchy with the trust gate applied. Untrusted files are
+ * offered to `approve`; declined files are excluded from the returned text.
+ * Every gate decision emits `context.trust_prompt` on the bus.
+ */
+export declare function loadTrustedKlyroMd(cwd: string, opts: TrustedLoadOpts): Promise<string>;

package/dist/context/trust.js

@@ -0,0 +1,111 @@
+/**
+ * P0.3 — context-file trust gate (r-11-17.md §5.1).
+ *
+ * Closes the shared HIGH flaw: `KLYRO.md` / `AGENTS.md` are auto-loaded into
+ * the prompt, so a malicious commit can smuggle instructions that read as
+ * authenticated system guidance. Every auto-loaded file is hashed; the first
+ * sighting (or any change) requires explicit approval before the content may
+ * enter context. Decisions persist in `~/.klyro/context-trust.json`.
+ *
+ * Headless runs approve nothing (secure default): untrusted files are
+ * excluded and the exclusion is visible on the event bus.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadKlyroMdFiles } from './klyro-md.js';
+export function hashContent(content) {
+    return crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+/** Pure evaluation: split files into trusted vs needs-approval. */
+export function evaluateTrust(stored, files) {
+    const trusted = [];
+    const untrusted = [];
+    for (const f of files) {
+        const rec = stored[f.path];
+        if (!rec) {
+            untrusted.push({ file: f, reason: 'unknown' });
+        }
+        else if (rec.sha256 !== hashContent(f.content)) {
+            untrusted.push({ file: f, reason: 'changed' });
+        }
+        else {
+            trusted.push(f);
+        }
+    }
+    return { trusted, untrusted };
+}
+export function defaultTrustStorePath() {
+    return path.join(os.homedir() || process.cwd(), '.klyro', 'context-trust.json');
+}
+export class ContextTrust {
+    storePath;
+    store = {};
+    constructor(storePath = defaultTrustStorePath()) {
+        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 */
+        }
+    }
+    check(files) {
+        return evaluateTrust(this.store, files);
+    }
+    /** Record approval for the file's current content. */
+    approve(file) {
+        this.store[file.path] = { sha256: hashContent(file.content), trustedAt: Date.now() };
+        this.save();
+    }
+    isTrusted(file) {
+        const rec = this.store[file.path];
+        return !!rec && rec.sha256 === hashContent(file.content);
+    }
+}
+/**
+ * Load KLYRO.md hierarchy with the trust gate applied. Untrusted files are
+ * offered to `approve`; declined files are excluded from the returned text.
+ * Every gate decision emits `context.trust_prompt` on the bus.
+ */
+export async function loadTrustedKlyroMd(cwd, opts) {
+    const sessionId = opts.sessionId ?? 'ephemeral';
+    const files = await loadKlyroMdFiles(cwd);
+    const { trusted, untrusted } = opts.trust.check(files);
+    const kept = [...trusted];
+    for (const { file, reason } of untrusted) {
+        let ok = false;
+        try {
+            ok = await opts.approve(file, reason);
+        }
+        catch {
+            ok = false;
+        }
+        opts.emit?.({ type: 'context.trust_prompt', ts: Date.now(), sessionId, path: file.path, reason, trusted: ok });
+        if (ok) {
+            opts.trust.approve(file);
+            kept.push(file);
+        }
+    }
+    // Preserve loader order.
+    const order = new Map(files.map((f, i) => [f.path, i]));
+    kept.sort((a, b) => (order.get(a.path) ?? 0) - (order.get(b.path) ?? 0));
+    return kept.map((f) => `# ${f.path}\n${f.content}`).join('\n\n---\n\n');
+}

package/dist/events/catalog.d.ts

@@ -132,5 +132,104 @@ export type KlyroEvent = {
     ts: number;
     sessionId: string;
     reason: string;
+} | {
+    type: 'subtask.started';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    parentTaskId?: string;
+    agentName: string;
+    depth: number;
+    model?: string;
+} | {
+    type: 'subtask.progress';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    note: string;
+} | {
+    type: 'subtask.completed';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    status: 'succeeded';
+    durationMs: number;
+    steps: number;
+    toolCalls: number;
+} | {
+    type: 'subtask.failed';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    status: 'failed' | 'cancelled' | 'timed_out' | 'blocked';
+    durationMs: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+} | {
+    type: 'subtask.cancelled';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    status: 'cancelled';
+    durationMs: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+} | {
+    type: 'subtask.timed_out';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    status: 'timed_out';
+    durationMs: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+} | {
+    type: 'subtask.tool_call';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    callId: string;
+    name: string;
+} | {
+    type: 'subtask.tool_result';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    callId: string;
+    name: string;
+    isError: boolean;
+    latencyMs: number;
+} | {
+    type: 'subtask.merged';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    changedFiles: string[];
+    merged?: boolean;
+} | {
+    type: 'provider.retry';
+    ts: number;
+    sessionId: string;
+    attempt: number;
+    status: string;
+    retryAfterMs?: number;
+} | {
+    type: 'context.trust_prompt';
+    ts: number;
+    sessionId: string;
+    path: string;
+    reason: 'unknown' | 'changed';
+    trusted: boolean;
+} | {
+    type: 'context.compacted';
+    ts: number;
+    sessionId: string;
+    dropped: number;
 };
 export type KlyroEventType = KlyroEvent['type'];

package/dist/index.js

@@ -23,6 +23,7 @@ import { runCompletion } from './cli/completion.js';
 import { runUpdate } from './cli/update.js';
 import { runLogin, runLogout } from './cli/auth.js';
 import { readVersion } from './version.js';
+import { verifyAuditChain } from './persistence/audit.js';
 const VERSION = readVersion();
 function parsePositiveInt(name, v) {
     const n = Number(v);
@@ -61,8 +62,21 @@ async function main() {
         .option('--output-format <fmt>', 'Headless output format: text|json|stream-json (default text)')
         .option('--no-stream', 'Disable streaming (buffer full response)')
         .option('--show-thinking', 'Show thinking blocks');
+    // Unknown commands / unknown options are usage errors (exit 2 per PRD).
+    // Help and version still exit 0; anything else rethrows to the last-resort
+    // handler (exit 1).
+    program.exitOverride((err) => {
+        if (err.code === 'commander.unknownCommand' || err.code === 'commander.unknownOption') {
+            process.stderr.write(`klyro: ${err.message}\n`);
+            process.exit(2);
+        }
+        if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
+            process.exit(0);
+        }
+        throw err;
+    });
     // Handle global flags before any command runs
-    program.hook('preAction', (thisCommand) => {
+    program.hook('preAction', async (thisCommand) => {
         const opts = thisCommand.optsWithGlobals();
         if (opts.cwd) {
             try {
@@ -73,6 +87,13 @@ async function main() {
                 process.exit(2);
             }
         }
+        // Load <cwd>/.env globally (after chdir) so KLYRO_* vars resolve for
+        // every command. Never throws; explicit env wins (no-clobber).
+        try {
+            const { loadDotenv } = await import('./cli/dotenv.js');
+            loadDotenv(process.cwd());
+        }
+        catch { /* ignore */ }
         if (opts.config)
             process.env.KLYRO_CONFIG = opts.config;
         if (opts.debug)
@@ -271,9 +292,12 @@ async function main() {
         .option('--resume-session <id>', 'Resume from a persisted session (Level 9) by id prefix')
         .option('--verify', 'Enable verification after edits (Level 8, default: enabled)')
         .option('--verify-command <cmd>', 'Custom verification command (default: auto-detected)')
+        .option('--verify-mode <mode>', 'Verification mode: strict (default), advisory, off')
         .option('--max-repairs <n>', 'Max autonomous repair attempts (default 3)', (v) => parsePositiveInt('--max-repairs', v))
         .option('--persist', 'Enable session persistence (Level 9, default: enabled)')
         .option('--require-verify', 'Fail with exit 8 if no verification passed after edits (6.5)')
+        .option('--agent <name>', 'Run under an orchestrator context enabling spawn_agent/task_list/task_get (explorer|implementer|tester|reviewer)')
+        .option('--max-depth <n>', 'Max spawn depth for child agents (default 1)', (v) => parsePositiveInt('--max-depth', v))
         .action(async (prompt, opts) => {
         const model = opts.model ?? process.env.KLYRO_MODEL;
         if (!model) {
@@ -285,6 +309,11 @@ async function main() {
             process.stderr.write(`klyro: invalid --output: ${output} (expected human|json|silent)\n`);
             process.exit(2);
         }
+        const verifyMode = opts.verifyMode ?? 'strict';
+        if (verifyMode !== 'strict' && verifyMode !== 'advisory' && verifyMode !== 'off') {
+            process.stderr.write(`klyro: invalid --verify-mode: ${opts.verifyMode} (expected strict|advisory|off)\n`);
+            process.exit(2);
+        }
         // Provider validation is handled inside runOnce (single source of truth)
         try {
             const code = await runOnce({
@@ -304,9 +333,12 @@ async function main() {
                 sessionId: opts.resumeSession,
                 verify: opts.verify,
                 verifyCommand: opts.verifyCommand,
+                verifyMode: verifyMode,
                 maxRepairAttempts: opts.maxRepairs,
                 persist: opts.persist,
                 requireVerify: !!opts.requireVerify,
+                agent: opts.agent,
+                maxDepth: opts.maxDepth,
             });
             process.exit(code);
         }
@@ -566,15 +598,72 @@ async function main() {
     });
     // 10.1 — MCP
     const mcp = program.command('mcp').description('MCP client/server (10.1)');
-    mcp.command('list').description('List MCP servers').action(async () => { process.stdout.write('mcp servers: (stub) github filesystem — use .mcp.json\n'); });
+    mcp.command('list').description('List MCP servers').action(async () => {
+        const { loadMcpServers } = await import('./mcp/config.js');
+        const cfg = loadMcpServers(process.cwd());
+        const names = Object.keys(cfg.servers);
+        if (names.length === 0) {
+            process.stdout.write('mcp servers: none configured (use .mcp.json)\n');
+            return;
+        }
+        for (const name of names) {
+            const spec = cfg.servers[name];
+            const source = cfg.sources[name] ?? 'unknown';
+            process.stdout.write(`${name} source=${source}${spec?.disabled ? ' disabled' : ''}\n`);
+        }
+    });
     mcp.command('add <name> <url>').description('Add MCP server').action(async (name) => { process.stdout.write(`added mcp ${name} (stub)\n`); });
     mcp.command('serve').description('Serve as MCP server').action(async () => { process.stdout.write('klyro mcp serve — exposing tools (stub)\n'); });
     // 10.2 — Hooks / agents
     program.command('hooks').description('List hooks (10.2)').action(async () => { process.stdout.write('hooks: SessionStart UserPromptSubmit PreToolUse PostToolUse (stub)\n'); });
-    program.command('agents').description('List agents (10.2)').action(async () => { process.stdout.write('agents: explorer implementer tester reviewer (stub)\n'); });
+    program.command('agents [name]').description('List agents (10.2) or show one agent definition').action(async (name) => {
+        const { BUILTIN_AGENTS } = await import('./agent/orchestrator.js');
+        if (!name) {
+            for (const a of BUILTIN_AGENTS)
+                process.stdout.write(`${a.id} — ${a.description}\n`);
+            return;
+        }
+        const def = BUILTIN_AGENTS.find((a) => a.id === name);
+        if (!def) {
+            process.stderr.write(`klyro: unknown agent: ${name} (known: ${BUILTIN_AGENTS.map((a) => a.id).join(', ')})\n`);
+            process.exit(2);
+        }
+        const tools = def.allowedTools ?? ['<inherited: all parent tools>'];
+        const lines = [
+            `agent: ${def.id}`,
+            `description: ${def.description}`,
+            `tools (${tools.length}): ${tools.join(', ')}`,
+            `readonly: ${def.readonly ?? false}`,
+            `canSpawn: ${def.canSpawn ?? false}`,
+            `model: ${def.model ?? '<session default>'}`,
+            `maxSteps: ${def.maxSteps ?? '<default>'}`,
+            `maxTokens: ${def.maxTokens ?? '<default>'}`,
+        ];
+        process.stdout.write(lines.join('\n') + '\n');
+    });
     // 10.3 — Web / git workflows / SDK
     program.command('commit').description('Create commit (10.3)').action(async () => { process.stdout.write('commit — conventional message (stub, use /commit)\n'); });
-    program.command('audit').description('Audit log (13.4)').action(async () => { process.stdout.write('audit — hash-chained JSONL (stub)\n'); });
+    program.command('audit [session]').description('Verify audit chain (13.4)').action(async (session) => {
+        if (!session) {
+            process.stderr.write('klyro: audit requires a session id (usage: klyro audit <session>)\n');
+            process.exit(2);
+        }
+        try {
+            const { getDefaultSessionsDir } = await import('./persistence/session.js');
+            const res = await verifyAuditChain(getDefaultSessionsDir(), session);
+            if (res.ok) {
+                process.stdout.write(`audit ok: ${res.events} events verified\n`);
+                process.exit(0);
+            }
+            process.stderr.write(`klyro: audit failed: ${res.error ?? 'chain broken'}\n`);
+            process.exit(1);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`klyro: audit failed: ${msg}\n`);
+            process.exit(1);
+        }
+    });
     // 10.4 — Benchmark parity (10.5)
     program.command('benchmark').description('Run benchmark (10.5)').action(async () => {
         const { runHarness } = await import('./eval/harness.js');