klyro 1.0.0 → 1.0.1

package/dist/context/import-graph.js

@@ -1,6 +1,10 @@
 /**
  * 7.3 — Import graph (cached) — powers L6 scoped tests + imports_of / importers_of
  * Parses TS/JS/Py/Go imports via regex, builds adjacency, caches by mtime.
+ *
+ * Freshness: the cached graph stores per-file {mtimeMs, size} alongside it.
+ * On a cache hit every file in the graph is re-statted (stat-only, bounded
+ * to files already in the graph) — any mtime/size mismatch rebuilds.
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
@@ -19,10 +23,32 @@ async function parseImports(file, content) {
     }
     return out;
 }
+/** Re-stat every file in the cached graph; true when all stats still match. */
+async function statsStillMatch(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;
+}
+/** Invalidate the import-graph cache (tests + callers that mutate the tree). */
+export function clearImportGraphCache() {
+    cache = null;
+}
 export async function buildImportGraph(cwd) {
-    if (cache && cache.cwd === cwd && Date.now() - cache.graph.mtime < 60_000)
-        return cache.graph;
+    if (cache && cache.cwd === cwd && Date.now() - cache.graph.mtime < 60_000) {
+        if (await statsStillMatch(cwd, cache.stats))
+            return cache.graph;
+        cache = null;
+    }
     const graph = { nodes: new Set(), edges: new Map(), mtime: Date.now() };
+    const stats = new Map();
     async function walk(dir, depth = 0) {
         if (depth > 6)
             return;
@@ -43,6 +69,8 @@ export async function buildImportGraph(cwd) {
                 const rel = path.relative(cwd, full).replace(/\\/g, '/');
                 graph.nodes.add(rel);
                 try {
+                    const st = await fs.stat(full);
+                    stats.set(rel, { mtimeMs: st.mtimeMs, size: st.size });
                     const txt = await fs.readFile(full, 'utf-8');
                     const imps = await parseImports(rel, txt);
                     for (const imp of imps) {
@@ -57,7 +85,7 @@ export async function buildImportGraph(cwd) {
         }
     }
     await walk(cwd);
-    cache = { cwd, graph };
+    cache = { cwd, graph, stats };
     return graph;
 }
 export async function importsOf(cwd, file) {

package/dist/context/klyro-md.js

@@ -27,7 +27,10 @@ export async function loadKlyroMdFiles(cwd) {
             catch { /* ignore */ }
         }
     }
-    for (const name of ['KLYRO.md', 'KLYRO.local.md', 'AGENTS.md', '.cursorrules']) {
+    // Klyro's own instruction file is KLYRO.md. The rest are read-only
+    // fallbacks for imported repos that follow other conventions — Klyro
+    // never writes them. KLYRO.md wins by load order.
+    for (const name of ['KLYRO.md', 'KLYRO.local.md', 'CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md', '.cursorrules']) {
         const p = path.join(cwd, name);
         try {
             const t = await fs.readFile(p, 'utf-8');

package/dist/context/memory.d.ts

@@ -1,5 +1,13 @@
 import type { PlanStep } from '../agent/runtime.js';
+/** Single-write ceiling — anything larger is rejected, not sliced. */
+export declare const MEMORY_WRITE_LIMIT_CHARS = 8000;
+/** Steady-state cap (~1k tokens ≈ 4k chars) kept via tail slice. */
+export declare const MEMORY_STEADY_STATE_CHARS = 4000;
 export declare function memoryWrite(cwd: string, content: string): Promise<string>;
 export declare function loadMemory(cwd: string): Promise<string>;
+/** Synchronous read for the system-prompt build path (run on every turn). */
+export declare function loadMemorySync(cwd: string): string;
+/** Wrap persisted notes into the injected prompt block; '' when empty. */
+export declare function memoryBlock(cwd: string): string;
 export declare function shouldRemind(turn: number, lastRemindTurn: number): boolean;
 export declare function reminderForTodos(todos: PlanStep[]): string | undefined;

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/events/catalog.d.ts

@@ -167,6 +167,28 @@ export type KlyroEvent = {
         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;
@@ -189,6 +211,7 @@ export type KlyroEvent = {
     sessionId: string;
     taskId: string;
     changedFiles: string[];
+    merged?: boolean;
 } | {
     type: 'provider.retry';
     ts: number;
@@ -203,5 +226,10 @@ export type KlyroEvent = {
     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,6 +292,7 @@ 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)')
@@ -287,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({
@@ -306,6 +333,7 @@ async function main() {
                 sessionId: opts.resumeSession,
                 verify: opts.verify,
                 verifyCommand: opts.verifyCommand,
+                verifyMode: verifyMode,
                 maxRepairAttempts: opts.maxRepairs,
                 persist: opts.persist,
                 requireVerify: !!opts.requireVerify,
@@ -570,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');

package/dist/mcp/client.d.ts

@@ -16,9 +16,9 @@ export interface McpCallResult {
     raw: unknown;
 }
 export interface McpClientLike {
-    listTools(): Promise<McpToolDef[]>;
+    listTools(signal?: AbortSignal): Promise<McpToolDef[]>;
     callTool(name: string, args: unknown, signal?: AbortSignal): Promise<McpCallResult>;
-    listResources(): Promise<McpResource[]>;
+    listResources(signal?: AbortSignal): Promise<McpResource[]>;
     close(): Promise<void>;
 }
 export declare class McpError extends Error {
@@ -39,11 +39,13 @@ export declare class McpClient implements McpClientLike {
     constructor(name: string, spec: McpServerSpec);
     connect(): Promise<void>;
     private connected;
-    listTools(): Promise<McpToolDef[]>;
+    listTools(signal?: AbortSignal): Promise<McpToolDef[]>;
     callTool(name: string, args: unknown, signal?: AbortSignal): Promise<McpCallResult>;
-    listResources(): Promise<McpResource[]>;
+    listResources(signal?: AbortSignal): Promise<McpResource[]>;
     readResource(uri: string, signal?: AbortSignal): Promise<string>;
     close(): Promise<void>;
+    /** Test hook: number of in-flight JSON-RPC requests. */
+    pendingCount(): number;
     private timeout;
     private assertLive;
     private onStdout;