klyro 1.0.0 → 1.0.2

package/dist/cli/run.js

@@ -16,13 +16,23 @@ 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 { redact } from '../policy/secret-redactor.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) {
     const v = process.env[name];
     return v && v.length > 0 ? v : fallback;
 }
+/**
+ * Double-Ctrl+C detector (pure, exported for tests): the second SIGINT
+ * within 1500ms of the first forces `process.exit(130)`. The live handler
+ * below owns the timestamp closure; tests exercise only this predicate.
+ */
+export function shouldForceExit(lastSigintAt, now) {
+    return lastSigintAt !== undefined && now - lastSigintAt < 1500;
+}
 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).
@@ -87,6 +97,36 @@ export async function runOnce(opts) {
             adapter = retryingAdapter(httpChatAdapter({ baseURL: baseUrl, apiKey, timeoutMs: opts.timeoutMs ?? 60_000 }), { onRetry: onRetryEmit });
         }
     }
+    // L15 provider failover: extra chain entries (after the primary) become
+    // fallback adapters for the runtime. Custom injected adapters (tests)
+    // skip chain wiring. Failures resolving the chain never block the run.
+    let failoverAdapters;
+    if (!opts.adapter) {
+        try {
+            const { resolveProviderChain } = await import('./config.js');
+            const chain = await resolveProviderChain(opts.cwd);
+            const fallbacks = chain.slice(1);
+            if (fallbacks.length > 0) {
+                const built = [];
+                for (const entry of fallbacks) {
+                    if (!entry.apiKey)
+                        continue;
+                    const base = entry.provider === 'anthropic'
+                        ? anthropicAdapter({ baseURL: entry.baseURL, apiKey: entry.apiKey, timeoutMs: opts.timeoutMs ?? 60_000 })
+                        : entry.baseURL
+                            ? httpChatAdapter({ baseURL: entry.baseURL, apiKey: entry.apiKey, timeoutMs: opts.timeoutMs ?? 60_000 })
+                            : null;
+                    if (base)
+                        built.push(retryingAdapter(base, { onRetry: onRetryEmit }));
+                }
+                if (built.length > 0) {
+                    failoverAdapters = built;
+                    stderr.write(`klyro: failover chain: ${built.map((b) => b.id).join(' → ')}\n`);
+                }
+            }
+        }
+        catch { /* best-effort — single-provider run proceeds */ }
+    }
     const registry = builtinRegistry();
     const policy = new PolicyEngine(builtinRules(), clonePolicyConfig());
     // Persisted "always allow" patterns apply to one-shot runs too.
@@ -97,15 +137,29 @@ export async function runOnce(opts) {
     catch {
         /* ignore — engine defaults stand */
     }
-    // Best-effort MCP tools: never fatal, never prompts. src/mcp/registry.ts
-    // lands from a sibling agent — the lazy import keeps runtime + builds green
-    // until then (import failure is caught below). @ts-ignore is used instead
-    // of @ts-expect-error so it stays inert after the sibling file lands.
+    // 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 {
-        // @ts-ignore — sibling-owned module may not exist yet
         const { loadAndRegisterMcp } = await import('../mcp/registry.js');
-        const mcp = await loadAndRegisterMcp({ cwd: opts.cwd, registry, policy });
+        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') {
@@ -134,6 +188,16 @@ export async function runOnce(opts) {
                 return 2;
             }
             sessionId = full;
+            // M22 resume-lock warning (read-only probe — takeover proceeds anyway).
+            try {
+                const { readSessionLock } = await import('../persistence/store.js');
+                const { getDefaultSessionsDir } = await import('../persistence/session.js');
+                const lock = readSessionLock(opts.sessionsDir ?? getDefaultSessionsDir(), sessionId);
+                if (lock.held && lock.alive) {
+                    stderr.write(`klyro: session ${sessionId.slice(0, 8)} is locked by live pid ${lock.pid ?? '?'} — taking over (proceeding anyway)\n`);
+                }
+            }
+            catch { /* probe is best-effort; never block resume */ }
             const msgs = await store.loadMessages(sessionId);
             // Convert StoredMessage to Message
             initialTranscript = msgs.map((m) => ({ role: m.role, content: m.content }));
@@ -161,7 +225,17 @@ export async function runOnce(opts) {
     // persistence is disabled or the session was never created).
     sessionIdForRetry.id = sessionId ?? 'ephemeral';
     const ac = new AbortController();
+    // Double-Ctrl+C: first press aborts the run; a second press within
+    // 1500ms forces process.exit(130) (shouldForceExit owns the predicate).
+    let lastSigintAt;
     const onSigint = () => {
+        const now = Date.now();
+        if (shouldForceExit(lastSigintAt, now)) {
+            stderr.write('\nklyro: SIGINT twice — forcing exit\n');
+            process.exit(130);
+            return;
+        }
+        lastSigintAt = now;
         stderr.write('\nklyro: SIGINT — aborting\n');
         ac.abort();
     };
@@ -179,6 +253,7 @@ 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
@@ -282,8 +357,20 @@ export async function runOnce(opts) {
                     if (output === 'human')
                         stderr.write(`[session ${ev.sessionId.slice(0, 8)} checkpoint]\n`);
                 }
+                else if (ev.kind === 'provider_failover') {
+                    stderr.write(`[failover] ${ev.from} → ${ev.to}: ${ev.reason.slice(0, 200)}\n`);
+                }
+                else if (ev.kind === 'budget_warning') {
+                    stderr.write(`[budget] ${(ev.ratio * 100).toFixed(0)}% of max cost used (threshold ${(ev.threshold * 100).toFixed(0)}%)\n`);
+                }
+                else if (ev.kind === 'model_override') {
+                    stderr.write(`[model] override: requested ${ev.requested} → effective ${ev.effective}\n`);
+                }
             },
-        }, { adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt });
+        }, {
+            adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt,
+            ...(failoverAdapters ? { failoverAdapters } : {}),
+        });
     }
     finally {
         doneSigint();
@@ -297,6 +384,7 @@ export async function runOnce(opts) {
         const statusMap = {
             complete: 'complete',
             max_steps: 'max_steps',
+            limit: 'max_steps',
             aborted: 'aborted',
             no_final: 'aborted',
             verify_failed: 'verify_failed',
@@ -320,7 +408,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;
@@ -328,14 +430,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) {
@@ -361,7 +463,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 = {
@@ -371,8 +475,10 @@ async function dryRunReport(opts) {
         maxSteps: opts.maxSteps,
         maxTokens: opts.maxTokens,
         temperature: opts.temperature,
-        systemPrompt,
-        task: opts.task,
+        // Secrets must never leak into a printable report: redact both the
+        // assembled system prompt and the task before printing.
+        systemPrompt: redact(systemPrompt),
+        task: redact(opts.task),
         toolCount: registry.list().length,
         toolNames: registry.list().map((t) => t.name),
         policyRules: rules.map((r) => r.name),
@@ -386,35 +492,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 {
-        // P0.3 trust gate: unapproved context files are excluded in headless
-        // mode (secure default-deny) and each exclusion is bus-visible.
+        // 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 } = new ContextTrust().check(files);
+        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 kept = trusted.map((f) => `# ${f.path}\n${f.content}`).join('\n\n---\n\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.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`. */