klyro 0.1.63 → 1.0.1

package/dist/cli/run.js

@@ -10,11 +10,14 @@
 import { stdout, stderr } from 'node:process';
 import { httpChatAdapter } from '../agent/provider-adapter.js';
 import { anthropicAdapter } from '../agent/anthropic-adapter.js';
+import { retryingAdapter } from '../agent/retry.js';
+import { globalBus } from '../events/bus.js';
 import { run } from '../agent/runtime.js';
 import { builtinRegistry } from '../tools/registry.js';
 import { builtinRules, clonePolicyConfig, PolicyEngine } from '../policy/engine.js';
 import { DenyAllApprovalPrompt } from '../policy/approval.js';
 import { buildLevel6Context } from '../context/level6.js';
+import { memoryBlock } from '../context/memory.js';
 import { resolveSessionId } from '../persistence/session.js';
 import * as fs from 'node:fs';
 function readEnv(name, fallback) {
@@ -22,6 +25,13 @@ function readEnv(name, fallback) {
     return v && v.length > 0 ? v : fallback;
 }
 export async function runOnce(opts) {
+    // P0.5 — load <cwd>/.env first so KLYRO_* vars resolve without `export`.
+    // Never throws (missing file is a no-op); explicit env wins (no-clobber).
+    try {
+        const { loadDotenv } = await import('./dotenv.js');
+        loadDotenv(opts.cwd);
+    }
+    catch { /* ignore */ }
     const output = opts.output ?? 'human';
     if (opts.dryRun) {
         return await dryRunReport(opts);
@@ -32,6 +42,27 @@ export async function runOnce(opts) {
         clearReadHistory();
     }
     catch { /* ignore */ }
+    // P1.4 — validate --agent early so typos fail fast (exit 2) even without API keys.
+    if (opts.agent) {
+        const { BUILTIN_AGENTS: _known } = await import('../agent/orchestrator.js');
+        if (!_known.some((a) => a.id === opts.agent)) {
+            stderr.write(`klyro: unknown agent: ${opts.agent} (known: ${_known.map((a) => a.id).join(', ')})\n`);
+            return 2;
+        }
+    }
+    // Box so retry telemetry (emitted before the session exists) picks up the
+    // real sessionId once create/resume assigns it below.
+    const sessionIdForRetry = { id: 'ephemeral' };
+    const onRetryEmit = (info) => {
+        globalBus.emit({
+            type: 'provider.retry',
+            ts: Date.now(),
+            sessionId: sessionIdForRetry.id,
+            attempt: info.attempt,
+            status: info.status,
+            ...(info.retryAfterMs !== undefined ? { retryAfterMs: info.retryAfterMs } : {}),
+        });
+    };
     let adapter = opts.adapter;
     if (!adapter) {
         const provider = opts.provider ?? 'openai';
@@ -42,19 +73,19 @@ export async function runOnce(opts) {
             return 2;
         }
         if (provider === 'anthropic') {
-            adapter = anthropicAdapter({
+            adapter = retryingAdapter(anthropicAdapter({
                 baseURL: baseUrl,
                 apiKey,
                 timeoutMs: opts.timeoutMs ?? 60_000,
                 authHeader: opts.authHeader,
-            });
+            }), { onRetry: onRetryEmit });
         }
         else {
             if (!baseUrl) {
                 stderr.write('klyro: KLYRO_BASE_URL is not set (or pass --base-url)\n');
                 return 2;
             }
-            adapter = httpChatAdapter({ baseURL: baseUrl, apiKey, timeoutMs: opts.timeoutMs ?? 60_000 });
+            adapter = retryingAdapter(httpChatAdapter({ baseURL: baseUrl, apiKey, timeoutMs: opts.timeoutMs ?? 60_000 }), { onRetry: onRetryEmit });
         }
     }
     const registry = builtinRegistry();
@@ -67,6 +98,37 @@ export async function runOnce(opts) {
     catch {
         /* ignore — engine defaults stand */
     }
+    // Best-effort MCP tools: never fatal, never prompts (headless cannot
+    // approve). Project-sourced servers auto-connect ONLY when their exact
+    // spec hash is already in the McpTrust store (e.g. approved in a prior
+    // REPL session); unknown specs are skipped with a warning.
+    let closeMcp;
+    try {
+        const { loadAndRegisterMcp } = await import('../mcp/registry.js');
+        const { McpTrust, hashSpec } = await import('../mcp/trust.js');
+        const { loadMcpServers } = await import('../mcp/config.js');
+        const mcpTrust = new McpTrust();
+        const mcpSpecs = loadMcpServers(opts.cwd).servers;
+        const mcp = await loadAndRegisterMcp({
+            cwd: opts.cwd,
+            registry,
+            policy,
+            approveProjectServer: async ({ name }) => {
+                const spec = mcpSpecs[name];
+                if (spec && mcpTrust.isTrusted(name, hashSpec(spec)))
+                    return true;
+                stderr.write(`klyro: mcp project server "${name}" not in trust store (skipped — headless cannot prompt)\n`);
+                return false;
+            },
+        });
+        for (const e of mcp.errors)
+            stderr.write(`klyro: mcp ${e.server}: ${e.message}\n`);
+        if (mcp.registered.length > 0 && output === 'human') {
+            stderr.write(`klyro: mcp tools: ${mcp.registered.join(', ')}\n`);
+        }
+        closeMcp = mcp.closeAll;
+    }
+    catch { /* ignore — MCP is optional */ }
     const systemPrompt = await makeRunSystemPrompt(opts.cwd, opts.systemPrompt ?? defaultRunSystemPrompt);
     // Level 9 — session setup (create or resume)
     const persistEnabled = opts.persist !== false;
@@ -110,6 +172,9 @@ export async function runOnce(opts) {
     else if (opts.resumePath) {
         initialTranscript = loadTranscript(opts.resumePath);
     }
+    // Publish the real sessionId to retry telemetry (stays 'ephemeral' when
+    // persistence is disabled or the session was never created).
+    sessionIdForRetry.id = sessionId ?? 'ephemeral';
     const ac = new AbortController();
     const onSigint = () => {
         stderr.write('\nklyro: SIGINT — aborting\n');
@@ -129,8 +194,52 @@ export async function runOnce(opts) {
             maxRepairAttempts: opts.maxRepairAttempts ?? 3,
             timeoutMs: opts.verifyTimeoutMs,
             requireVerify: opts.requireVerify,
+            ...(opts.verifyMode ? { mode: opts.verifyMode } : {}),
         };
     let result;
+    // P1.4 — if --agent is requested, stand up a parent orchestrator so the
+    // model can call spawn_agent / task_list / task_get. The root run keeps
+    // depth 0; children are capped at maxDepth (default 1 per r-6-10.fix.md).
+    let agentBridge;
+    let parentContext;
+    if (opts.agent) {
+        const { AgentOrchestrator, BUILTIN_AGENTS } = await import('../agent/orchestrator.js');
+        const def = BUILTIN_AGENTS.find((a) => a.id === opts.agent); // validated above
+        const maxDepth = opts.maxDepth ?? 1;
+        const rootDeps = { adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt };
+        const orchestrator = new AgentOrchestrator({ sessionId: sessionId ?? 'ephemeral', deps: rootDeps });
+        const allowedTools = new Set(registry.list().map((t) => t.name));
+        parentContext = {
+            sessionId: sessionId ?? 'ephemeral',
+            depth: 0,
+            maxDepth,
+            allowedTools,
+            model: def.model ?? opts.model,
+        };
+        agentBridge = orchestrator.bridgeFor({
+            sessionId: sessionId ?? 'ephemeral',
+            cwd: opts.cwd,
+            depth: 0,
+            maxDepth,
+            allowedTools,
+            model: def.model ?? opts.model,
+        });
+    }
+    else if (opts.maxDepth !== undefined) {
+        const allowedTools = new Set(registry.list().map((t) => t.name));
+        const { AgentOrchestrator } = await import('../agent/orchestrator.js');
+        const rootDeps = { adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt };
+        const orchestrator = new AgentOrchestrator({ sessionId: sessionId ?? 'ephemeral', deps: rootDeps });
+        parentContext = { sessionId: sessionId ?? 'ephemeral', depth: 0, maxDepth: opts.maxDepth, allowedTools, model: opts.model };
+        agentBridge = orchestrator.bridgeFor({
+            sessionId: sessionId ?? 'ephemeral',
+            cwd: opts.cwd,
+            depth: 0,
+            maxDepth: opts.maxDepth,
+            allowedTools,
+            model: opts.model,
+        });
+    }
     try {
         result = await run({
             task: opts.task,
@@ -144,6 +253,8 @@ export async function runOnce(opts) {
             initialTranscript,
             verify: verifyOpts,
             persist: store && sessionId ? { store, sessionId } : undefined,
+            ...(agentBridge ? { agentBridge } : {}),
+            ...(parentContext ? { parentContext } : {}),
             onEvent: (ev) => {
                 if (output === 'json') {
                     stdout.write(JSON.stringify(ev) + '\n');
@@ -192,12 +303,17 @@ export async function runOnce(opts) {
     }
     finally {
         doneSigint();
+        try {
+            await closeMcp?.();
+        }
+        catch { /* ignore */ }
     }
     if (store && sessionId) {
         // Finalize session status
         const statusMap = {
             complete: 'complete',
             max_steps: 'max_steps',
+            limit: 'max_steps',
             aborted: 'aborted',
             no_final: 'aborted',
             verify_failed: 'verify_failed',
@@ -221,7 +337,21 @@ export async function runOnce(opts) {
             stdout.write(JSON.stringify({ kind: 'final', status: result.status, steps: result.steps }) + '\n');
         else
             stderr.write(`klyro: hit max steps (${result.steps}); consider raising --max-steps\n`);
-        return 3;
+        return 7;
+    }
+    if (result.status === 'limit') {
+        if (output === 'json')
+            stdout.write(JSON.stringify({ kind: 'final', status: result.status, steps: result.steps, text: result.finalText }) + '\n');
+        else
+            stderr.write(`klyro: stopped early: ${result.finalText || result.status} (after ${result.steps} steps)\n`);
+        return 7;
+    }
+    if (result.status === 'stuck') {
+        if (output === 'json')
+            stdout.write(JSON.stringify({ kind: 'final', status: result.status, steps: result.steps }) + '\n');
+        else
+            stderr.write(`klyro: stuck — repeated the same action with no progress; aborting after ${result.steps} steps\n`);
+        return 7;
     }
     if (result.status === 'aborted') {
         return 130;
@@ -229,14 +359,14 @@ export async function runOnce(opts) {
     if (result.status === 'no_final') {
         if (output !== 'json')
             stderr.write('klyro: provider error — no final answer\n');
-        return 4;
+        return 5;
     }
     if (result.status === 'verify_failed') {
         if (output === 'json')
             stdout.write(JSON.stringify({ kind: 'final', status: 'verify_failed', failureType: result.verification?.failureType }) + '\n');
         else
             stderr.write(`klyro: verification failed after ${result.verification?.attempts ?? 3} repairs — see output above\n`);
-        return 5;
+        return 8;
     }
     // 6.5 — --require-verify: if edits were made but verification never passed, exit 8
     if (opts.requireVerify && result.verification && !result.verification.ok) {
@@ -262,7 +392,9 @@ async function dryRunReport(opts) {
     // Assemble the REAL prompt (Level-6 context + KLYRO.md), not the bare base —
     // otherwise dry-run shows a different prompt than production runs use.
     const systemPromptFn = await makeRunSystemPrompt(opts.cwd, opts.systemPrompt ?? defaultRunSystemPrompt);
-    const systemPrompt = systemPromptFn({ cwd: opts.cwd });
+    const { resolveSystemPrompt } = await import('../agent/runtime.js');
+    const { system, suffix } = resolveSystemPrompt(systemPromptFn, { cwd: opts.cwd });
+    const systemPrompt = suffix ? `${system}\n\n${suffix}` : system;
     const registry = builtinRegistry();
     const rules = builtinRules();
     const report = {
@@ -287,23 +419,53 @@ function defaultRunSystemPrompt(_ctx) {
         'Solve it by calling tools as needed. When done, produce a short final text answer.',
         'Do not invent file paths. Do not call tools outside the working directory.',
     ].join(' ');
-    return _ctx.telemetry ? base + '\n\n' + _ctx.telemetry : base;
+    return _ctx.telemetry ? { system: base, suffix: _ctx.telemetry } : { system: base };
 }
 /** Wrap a system-prompt fn to inject Level-6 context (project map etc.) + KLYRO.md (4.4). */
 export async function makeRunSystemPrompt(cwd, base) {
     const ctxBlock = await buildLevel6Context({ cwd });
     const prefix = ctxBlock.formatted ? `\n\n<context>\n${ctxBlock.formatted}\n</context>` : '';
+    // Session memory: .klyro/memory/session-notes.md injected so memory_write
+    // actually takes effect (redacted at write time — see context/memory.ts).
+    const memBlock = memoryBlock(cwd);
     let klyroBlock = '';
     try {
-        const { loadKlyroMd } = await import('../context/klyro-md.js');
-        const md = await loadKlyroMd(cwd);
-        if (md)
-            klyroBlock = `\n\n<KLYRO.md>\n${md.slice(0, 4000)}\n</KLYRO.md>`;
+        // P0.3 trust gate with headless approve-if-store-known: approve(file) is
+        // trust.isTrusted(file), so REPL-persisted approvals are honored with no
+        // prompting; unknown/changed files stay excluded and each exclusion is
+        // bus-visible.
+        const { loadKlyroMdFiles } = await import('../context/klyro-md.js');
+        const { ContextTrust } = await import('../context/trust.js');
+        const { globalBus } = await import('../events/bus.js');
+        const trust = new ContextTrust();
+        // Headless approve-if-store-known (no prompts): approve(file) is
+        // trust.isTrusted(file), so REPL-persisted approvals are honored;
+        // unknown/changed files stay excluded.
+        const approve = (file) => trust.isTrusted(file);
+        const files = await loadKlyroMdFiles(cwd);
+        const { trusted, untrusted } = trust.check(files);
+        for (const { file, reason } of untrusted) {
+            globalBus.emit({ type: 'context.trust_prompt', ts: Date.now(), sessionId: 'ephemeral', path: file.path, reason, trusted: false });
+        }
+        if (untrusted.length > 0) {
+            stderr.write(`klyro: trust gate excluded ${untrusted.length} unapproved context file(s): ${untrusted.map((u) => u.file.path).join(', ')}\n`);
+        }
+        const keptFiles = trusted.filter(approve);
+        const kept = keptFiles.map((f) => `# ${f.path}\n${f.content}`).join('\n\n---\n\n');
+        if (kept)
+            klyroBlock = `\n\n<KLYRO.md>\n${kept.slice(0, 4000)}\n</KLYRO.md>`;
     }
     catch { /* ignore */ }
     return (ctx) => {
-        const t = ctx.telemetry ? '\n\n' + ctx.telemetry : '';
-        return base(ctx) + prefix + klyroBlock + t;
+        const r = base(ctx);
+        if (typeof r === 'string') {
+            // Legacy string fn: keep the exact legacy concatenation behavior.
+            const t = ctx.telemetry ? '\n\n' + ctx.telemetry : '';
+            return r + prefix + klyroBlock + memBlock + t;
+        }
+        // Split shape: Level-6/KLYRO.md join the stable prefix; telemetry stays
+        // the volatile suffix for cache-friendly adapters.
+        return { system: r.system + prefix + klyroBlock + memBlock, ...(r.suffix !== undefined ? { suffix: r.suffix } : {}) };
     };
 }
 export function loadTranscript(path) {

package/dist/cli/update.d.ts

@@ -1,6 +1,11 @@
 /**
  * klyro update — check registry for newer version, cached 24h.
  * Env KLYRO_NO_UPDATE_CHECK=1 disables.
+ *
+ * Integrity: before recommending `npm i`, we verify the tarball's SRI hash
+ * (sha512) against the registry's recorded `dist.integrity`. An install is
+ * only recommended when the download hash matches, so a tampered CDN or
+ * MITM registry response can't push a malicious binary to the operator.
  */
 export declare function checkForUpdate(current: string): Promise<string | null>;
 export declare function runUpdate(): Promise<number>;

package/dist/cli/update.js

@@ -1,15 +1,65 @@
 /**
  * klyro update — check registry for newer version, cached 24h.
  * Env KLYRO_NO_UPDATE_CHECK=1 disables.
+ *
+ * Integrity: before recommending `npm i`, we verify the tarball's SRI hash
+ * (sha512) against the registry's recorded `dist.integrity`. An install is
+ * only recommended when the download hash matches, so a tampered CDN or
+ * MITM registry response can't push a malicious binary to the operator.
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import { createHash } from 'node:crypto';
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_BASE = 'https://registry.npmjs.org/klyro';
+const FETCH_TIMEOUT_MS = 3000;
+const TARBALL_TIMEOUT_MS = 10000;
 function cachePath() {
+    // KLYRO_UPDATE_CACHE lets tests isolate the on-disk cache (and power users
+    // relocate it); default is the home cache like the rest of Klyro.
+    const override = process.env.KLYRO_UPDATE_CACHE;
+    if (override)
+        return override;
     const home = os.homedir() || process.cwd();
     return path.join(home, '.klyro', 'update-cache.json');
 }
+/** SRI string may carry multiple hashes parsable with `pick`; we accept sha512 or sha256. */
+function parseSRI(integrity) {
+    if (!integrity)
+        return null;
+    for (const part of integrity.split(/\s+/)) {
+        const m = /^(sha256|sha512)-([A-Za-z0-9+/=]+)$/.exec(part);
+        if (m)
+            return { algo: m[1], digest: m[2] };
+    }
+    return null;
+}
+/** Fetch with a timeout; rejects on non-2xx. */
+async function fetchWithTimeout(url, timeoutMs = FETCH_TIMEOUT_MS) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { signal: ctrl.signal });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return res;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+/** Download the tarball and confirm its hash equals the registry's SRI digest. */
+async function verifyTarballIntegrity(dist) {
+    const sri = parseSRI(dist.integrity);
+    const tarball = dist.tarball;
+    if (!sri || !tarball)
+        return false;
+    const res = await fetchWithTimeout(tarball, TARBALL_TIMEOUT_MS);
+    const buf = Buffer.from(await res.arrayBuffer());
+    const actual = createHash(sri.algo).update(buf).digest('base64');
+    return actual === sri.digest;
+}
 export async function checkForUpdate(current) {
     if (process.env.KLYRO_NO_UPDATE_CHECK === '1')
         return null;
@@ -25,18 +75,20 @@ export async function checkForUpdate(current) {
         // ignore
     }
     try {
-        const ctrl = new AbortController();
-        const t = setTimeout(() => ctrl.abort(), 3000);
-        const res = await fetch('https://registry.npmjs.org/klyro/latest', { signal: ctrl.signal });
-        clearTimeout(t);
-        if (!res.ok)
-            return null;
+        const res = await fetchWithTimeout(`${REGISTRY_BASE}/latest`);
         const json = (await res.json());
         const latest = json.version ?? '';
-        await fs.mkdir(path.dirname(cache), { recursive: true });
-        await fs.writeFile(cache, JSON.stringify({ at: Date.now(), latest }), 'utf-8');
-        if (latest && latest !== current)
+        if (latest && latest !== current) {
+            // Verify the tarball's integrity before caching/recommending this version.
+            const verRes = await fetchWithTimeout(`${REGISTRY_BASE}/${encodeURIComponent(latest)}`);
+            const verJson = (await verRes.json());
+            const ok = await verifyTarballIntegrity(verJson.dist ?? {});
+            if (!ok)
+                return null; // integrity mismatch — treat as no update, never recommend it
+            await fs.mkdir(path.dirname(cache), { recursive: true });
+            await fs.writeFile(cache, JSON.stringify({ at: Date.now(), latest }), 'utf-8');
             return latest;
+        }
     }
     catch {
         // network failure — silent
@@ -55,7 +107,7 @@ export async function runUpdate() {
         const cur = pkg.version ?? '0.0.0';
         const latest = await checkForUpdate(cur);
         if (latest) {
-            process.stdout.write(`Update available: ${cur} → ${latest}\n  npm i -g klyro@latest\n`);
+            process.stdout.write(`Update available: ${cur} → ${latest} (integrity verified)\n  npm i -g klyro@latest\n`);
         }
         else {
             process.stdout.write(`klyro ${cur} is latest\n`);

package/dist/context/import-graph.d.ts

@@ -3,6 +3,8 @@ export interface ImportGraph {
     edges: Map<string, Set<string>>;
     mtime: number;
 }
+/** Invalidate the import-graph cache (tests + callers that mutate the tree). */
+export declare function clearImportGraphCache(): void;
 export declare function buildImportGraph(cwd: string): Promise<ImportGraph>;
 export declare function importsOf(cwd: string, file: string): Promise<string[]>;
 export declare function importersOf(cwd: string, file: string): Promise<string[]>;

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.d.ts

@@ -6,5 +6,11 @@
  * secret files into context), each file is capped, and total output is
  * capped so a giant monorepo doc can't blow the context budget.
  */
+export interface KlyroMdFile {
+    path: string;
+    content: string;
+}
+/** Per-file loader (used by the trust gate to approve/hash individual files). */
+export declare function loadKlyroMdFiles(cwd: string): Promise<KlyroMdFile[]>;
 export declare function loadKlyroMd(cwd: string): Promise<string>;
 export declare function handleInit(cwd: string): Promise<string>;

package/dist/context/klyro-md.js

@@ -14,37 +14,46 @@ const MAX_TOTAL_CHARS = 8000;
 function cap(s, n) {
     return s.length > n ? s.slice(0, n) + `\n... [truncated ${s.length - n} chars]` : s;
 }
-export async function loadKlyroMd(cwd) {
-    const parts = [];
-    let total = 0;
-    const push = (s) => {
-        if (total >= MAX_TOTAL_CHARS)
-            return;
-        const room = MAX_TOTAL_CHARS - total;
-        const chunk = s.length > room ? s.slice(0, room) + '\n... [truncated]' : s;
-        parts.push(chunk);
-        total += chunk.length;
-    };
-    // Global
+/** Per-file loader (used by the trust gate to approve/hash individual files). */
+export async function loadKlyroMdFiles(cwd) {
+    const files = [];
     const home = os.homedir();
     if (home) {
         for (const p of [path.join(home, '.klyro', 'KLYRO.md'), path.join(home, '.klyro', 'KLYRO.local.md')]) {
             try {
                 const t = await fs.readFile(p, 'utf-8');
-                push(`# ${p}\n${cap(t, MAX_FILE_CHARS)}`);
+                files.push({ path: p, content: cap(t, MAX_FILE_CHARS) });
             }
             catch { /* ignore */ }
         }
     }
-    // Root (imports resolved relative to each file, contained to cwd)
-    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');
-            push(`# ${p}\n${cap(await resolveImports(t, path.dirname(p), cwd), MAX_FILE_CHARS)}`);
+            files.push({ path: p, content: cap(await resolveImports(t, path.dirname(p), cwd), MAX_FILE_CHARS) });
         }
         catch { /* ignore */ }
     }
+    return files;
+}
+export async function loadKlyroMd(cwd) {
+    const parts = [];
+    let total = 0;
+    const push = (s) => {
+        if (total >= MAX_TOTAL_CHARS)
+            return;
+        const room = MAX_TOTAL_CHARS - total;
+        const chunk = s.length > room ? s.slice(0, room) + '\n... [truncated]' : s;
+        parts.push(chunk);
+        total += chunk.length;
+    };
+    for (const f of await loadKlyroMdFiles(cwd)) {
+        push(`# ${f.path}\n${f.content}`);
+    }
     return parts.join('\n\n---\n\n');
 }
 async function resolveImports(text, base, root, depth = 0) {

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;