klyro 1.0.17 → 1.0.20

package/dist/agent/runtime.d.ts

@@ -271,6 +271,13 @@ export type RuntimeEvent = {
     kind: 'model_override';
     requested: string;
     effective: string;
+} | {
+    kind: 'turn.summary';
+    turn: number;
+    toolCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    durationMs: number;
 };
 export interface RunResult {
     status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked' | 'stuck';

package/dist/agent/runtime.js

@@ -119,6 +119,8 @@ export async function run(opts, deps) {
         }
     };
     let steps = 0;
+    // 4.5c — per-turn start time for turn.summary durationMs.
+    let turnStartMs = Date.now();
     let lastRemindTurn = 0;
     let toolCallCount = 0;
     let finalText = '';
@@ -247,6 +249,23 @@ export async function run(opts, deps) {
             // best-effort — don't crash runtime on persistence failure
         }
     }
+    /**
+     * 4.5c — end-of-turn summary: emit a turn.summary event (cumulative
+     * toolCalls + token counts, per-turn durationMs) and record a compact
+     * one-line summary in the transcript.
+     */
+    async function emitTurnSummary() {
+        const durationMs = Date.now() - turnStartMs;
+        emit?.({ kind: 'turn.summary', turn: steps, toolCalls: toolCallCount, inputTokens: usage.input, outputTokens: usage.output, durationMs });
+        const msg = {
+            role: 'user',
+            content: [text(`[turn ${steps} summary] ${toolCallCount} tool call(s), ${usage.input} in / ${usage.output} out tokens, ${durationMs}ms`)],
+        };
+        transcript.push(msg);
+        await checkpoint(msg);
+        // Invalidate token cache since transcript changed
+        tokenCache = { lastRef: null, lastSystem: undefined, lastCount: 0 };
+    }
     // Persist initial user message
     if (store && sessionId && transcript.length > 0) {
         // Fire-and-forget initial checkpoint (don't await to block loop start)
@@ -322,6 +341,7 @@ export async function run(opts, deps) {
             return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined, phase: 'blocked' };
         }
         steps++;
+        turnStartMs = Date.now();
         // 8.4 — stale-todo reminder: every 20 turns, re-inject pending plan
         // items from `.klyro/plans/todos.json` (written by todo_write) so a
         // long run cannot silently drop its checklist. Best-effort + tiny.
@@ -615,6 +635,9 @@ export async function run(opts, deps) {
             return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
         }
         if (finalizedCalls.length === 0) {
+            // 4.5c — the turn completed (final text, malformed-only, or
+            // stop-hook continuation): summarize before the verify branching.
+            await emitTurnSummary();
             // Steerable stop: a stop hook asked for one more turn instead of
             // completing. Consumed once per verdict, max 3 per run.
             if (stopCont !== null && stopContUsed < 3) {
@@ -1051,6 +1074,19 @@ export async function run(opts, deps) {
                     }
                 }
             }
+            // 4.5a — shell/git mutations bypass file-change inference: take a
+            // pre-execution snapshot so the turn stays restorable. Best-effort.
+            if (call.name === 'shell_exec' || call.name.startsWith('git_')) {
+                try {
+                    const { snapshot } = await import('../checkpoints/store.js');
+                    await snapshot(opts.cwd, [...fileEditCounts.keys()].slice(-20), {
+                        ...(sessionId !== undefined ? { sessionId } : {}),
+                        eventId: call.id,
+                        transcript,
+                    });
+                }
+                catch { /* ignore */ }
+            }
             let obs;
             try {
                 obs = await deps.registry.execute(call.name, call.input, toolCtx);
@@ -1138,7 +1174,11 @@ export async function run(opts, deps) {
                     // 4.5 — checkpoint snapshot after each mutation
                     try {
                         const { snapshot } = await import('../checkpoints/store.js');
-                        await snapshot(opts.cwd, [fileChanged.path]);
+                        await snapshot(opts.cwd, [fileChanged.path], {
+                            ...(sessionId !== undefined ? { sessionId } : {}),
+                            eventId: call.id,
+                            transcript,
+                        });
                     }
                     catch { /* ignore */ }
                     // 5.2 file edit count
@@ -1251,6 +1291,8 @@ export async function run(opts, deps) {
                     break;
             }
         }
+        // 4.5c — the tool turn completed: summarize (cumulative counts).
+        await emitTurnSummary();
         // P0 — drain finished sub-agent completions into parent visibility.
         // drainCompletions is OPTIONAL on the bridge — guarded with `?.` so
         // older bridges without it simply yield nothing.

package/dist/checkpoints/store.d.ts

@@ -10,7 +10,23 @@
  * enforced at the trace/persist boundaries (TraceWriter, SessionStore)
  * instead of here.
  */
-export declare function snapshot(cwd: string, files: string[]): Promise<string>;
+/** Optional provenance recorded into a checkpoint's .meta.json. */
+export interface SnapshotOptions {
+    sessionId?: string;
+    eventId?: string;
+    transcript?: unknown[];
+}
+/** Checkpoint meta on disk — sessionId/eventId are absent on old metas. */
+export interface CheckpointMeta {
+    id: string;
+    files: string[];
+    missing: string[];
+    ts: number;
+    sessionId?: string;
+    eventId?: string;
+    transcriptHash?: string;
+}
+export declare function snapshot(cwd: string, files: string[], opts?: SnapshotOptions): Promise<string>;
 export declare function listCheckpoints(cwd: string): Promise<string[]>;
 export interface CheckpointInfo {
     /** 1-based index from the latest (1 = newest, like `undo(n)`). */
@@ -23,6 +39,17 @@ export interface CheckpointInfo {
 export declare function listCheckpointInfo(cwd: string): Promise<CheckpointInfo[]>;
 /** File paths a snapshot would restore (for `/rewind <n> preview`). */
 export declare function snapshotFiles(cwd: string, id: string): Promise<string[]>;
+/**
+ * Transcript captured at a checkpoint, or null when the snapshot predates
+ * transcript capture or the payload is missing/corrupt.
+ *
+ * The stored hash is verified on read: a checkpoint is only ever trusted for
+ * restoring the conversation when its transcript.json still matches the
+ * transcriptHash recorded in .meta.json. A mismatch (partial write, manual
+ * edit, tampering) yields null so the caller can report "conversation
+ * untouched" instead of rewinding onto unverified content.
+ */
+export declare function readSnapshotTranscript(cwd: string, id: string): Promise<unknown[] | null>;
 export declare function diff(cwd: string, id?: string): Promise<string>;
 export declare function undo(cwd: string, n?: number): Promise<void>;
 export declare function rewind(cwd: string): Promise<void>;

package/dist/checkpoints/store.js

@@ -55,7 +55,7 @@ function containedPath(cwd, base, rel) {
         return null;
     return out;
 }
-export async function snapshot(cwd, files) {
+export async function snapshot(cwd, files, opts) {
     const dir = ckptDir(cwd);
     await fs.mkdir(dir, { recursive: true });
     lockDown(dir, 0o700);
@@ -92,7 +92,20 @@ export async function snapshot(cwd, files) {
     // leaves a truncated .meta.json that undo() then trusts).
     const metaPath = path.join(dest, '.meta.json');
     const metaTmp = `${metaPath}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
-    await fs.writeFile(metaTmp, JSON.stringify({ id, files: kept, missing, ts: Date.now() }, null, 2));
+    const meta = { id, files: kept, missing, ts: Date.now() };
+    if (opts?.sessionId !== undefined)
+        meta.sessionId = opts.sessionId;
+    if (opts?.eventId !== undefined)
+        meta.eventId = opts.eventId;
+    if (opts?.transcript) {
+        const transcriptPath = path.join(dest, 'transcript.json');
+        await fs.writeFile(transcriptPath, JSON.stringify(opts.transcript), 'utf-8');
+        lockDown(transcriptPath, 0o600);
+        await fsyncFile(transcriptPath);
+        const hash = crypto.createHash('sha256').update(JSON.stringify(opts.transcript)).digest('hex');
+        meta.transcriptHash = hash;
+    }
+    await fs.writeFile(metaTmp, JSON.stringify(meta, null, 2));
     lockDown(metaTmp, 0o600);
     await fsyncFile(metaTmp);
     try {
@@ -203,6 +216,35 @@ export async function snapshotFiles(cwd, id) {
         return [];
     }
 }
+/**
+ * Transcript captured at a checkpoint, or null when the snapshot predates
+ * transcript capture or the payload is missing/corrupt.
+ *
+ * The stored hash is verified on read: a checkpoint is only ever trusted for
+ * restoring the conversation when its transcript.json still matches the
+ * transcriptHash recorded in .meta.json. A mismatch (partial write, manual
+ * edit, tampering) yields null so the caller can report "conversation
+ * untouched" instead of rewinding onto unverified content.
+ */
+export async function readSnapshotTranscript(cwd, id) {
+    try {
+        const dir = path.join(ckptDir(cwd), id);
+        const meta = JSON.parse(await fs.readFile(path.join(dir, '.meta.json'), 'utf-8'));
+        const raw = await fs.readFile(path.join(dir, 'transcript.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return null;
+        if (typeof meta.transcriptHash === 'string') {
+            const actual = crypto.createHash('sha256').update(raw).digest('hex');
+            if (actual !== meta.transcriptHash)
+                return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
 export async function diff(cwd, id) {
     const ckpts = await listCheckpoints(cwd);
     const target = id ?? ckpts[ckpts.length - 1];
@@ -227,6 +269,8 @@ export async function undo(cwd, n = 1) {
     const metaRaw = await fs.readFile(path.join(srcDir, '.meta.json'), 'utf-8');
     const meta = JSON.parse(metaRaw);
     // Restore modified/created files to their snapshotted content…
+    // Transcript restore is handled by caller via transcript snapshot — read via
+    // readSnapshotTranscript() if the caller wants conversation rewind.
     for (const f of meta.files) {
         const src = containedPath(cwd, srcDir, f);
         const dest = src ? containedPath(cwd, cwd, f) : null;

package/dist/cli/args.d.ts

@@ -1 +1,8 @@
 export declare function parsePositiveInt(name: string, v: string): number;
+/**
+ * 5.3 — `--auto-answer <text>` wiring. `ask_user` honors
+ * `KLYRO_AUTO_ANSWER` in headless runs; `klyro run` / `klyro eval` set it
+ * from the flag via this helper before the run starts (explicit env wins
+ * when the flag is omitted). Exported for tests.
+ */
+export declare function applyAutoAnswer(value: string | undefined): void;

package/dist/cli/args.js

@@ -12,3 +12,13 @@ export function parsePositiveInt(name, v) {
     }
     return n;
 }
+/**
+ * 5.3 — `--auto-answer <text>` wiring. `ask_user` honors
+ * `KLYRO_AUTO_ANSWER` in headless runs; `klyro run` / `klyro eval` set it
+ * from the flag via this helper before the run starts (explicit env wins
+ * when the flag is omitted). Exported for tests.
+ */
+export function applyAutoAnswer(value) {
+    if (value !== undefined)
+        process.env.KLYRO_AUTO_ANSWER = value;
+}

package/dist/cli/eval.d.ts

@@ -81,6 +81,22 @@ export interface EvalResult {
     };
     /** Isolated workdir the scenario ran in (tmp unless --cwd). Debugging aid. */
     workDir?: string;
+    /** 5.4a — provider token usage for the scenario run. */
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    /** 5.4a — estimated USD cost (runtime pricing helper, same rates as budgets). */
+    costUsd?: number;
+    /** 5.4a — distinct file paths referenced by tool-call inputs (best-effort). */
+    filesTouched?: string[];
+    /** 5.4a — verification outcome passthrough. */
+    verification?: {
+        ok: boolean;
+        attempts: number;
+    };
+    /** 5.4a — repair count passthrough. */
+    repairs?: number;
 }
 export interface RunEvalOptions {
     inputPath: string;
@@ -98,10 +114,26 @@ export interface RunEvalOptions {
      * touch the caller's directory. Pass explicitly to inspect artifacts.
      */
     cwd?: string;
+    /**
+     * 5.3 — `--auto-answer <text>`: sets `KLYRO_AUTO_ANSWER` before the run
+     * starts so headless `ask_user` calls resolve without prompting.
+     */
+    autoAnswer?: string;
 }
+/**
+ * 5.5a — curated stable subset of `evals/fixtures` for `--suite core`.
+ * Every entry has task.md + check.sh (verified 2026-09-24).
+ */
+export declare const CORE_SUITE_FIXTURES: string[];
+/**
+ * Filter directory names down to the core suite (in curated order).
+ * Exported for tests.
+ */
+export declare function selectCoreFixtures(entries: string[]): string[];
 export declare function runEval(opts: RunEvalOptions): Promise<number>;
 export declare function scriptedAdapterFromSpec(spec: Array<Array<unknown[]>> | undefined): ProviderAdapter;
 export declare function runScenario(sc: EvalScenario, judgeOpts?: {
     adapter: ProviderAdapter;
     model: string;
 }, workDir?: string): Promise<EvalResult>;
+export declare function collectFilesTouched(transcript: RunResult['transcript']): string[];

package/dist/cli/eval.js

@@ -45,11 +45,26 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import * as readline from 'node:readline/promises';
 import { stdin as input, stdout, stderr } from 'node:process';
-import { run } from '../agent/runtime.js';
+import { run, estimateCost } from '../agent/runtime.js';
+import { applyAutoAnswer } from './args.js';
 import { builtinRegistry } from '../tools/registry.js';
 import { builtinRules, DEFAULT_POLICY_CONFIG, PolicyEngine } from '../policy/engine.js';
 import { DenyAllApprovalPrompt } from '../policy/approval.js';
+/**
+ * 5.5a — curated stable subset of `evals/fixtures` for `--suite core`.
+ * Every entry has task.md + check.sh (verified 2026-09-24).
+ */
+export const CORE_SUITE_FIXTURES = ['read-answer', 'add-fn-test', 'fix-failing-test', 'rename', 'cli-flag'];
+/**
+ * Filter directory names down to the core suite (in curated order).
+ * Exported for tests.
+ */
+export function selectCoreFixtures(entries) {
+    return CORE_SUITE_FIXTURES.filter((id) => entries.includes(id));
+}
 export async function runEval(opts) {
+    // 5.3 — --auto-answer sets KLYRO_AUTO_ANSWER before anything runs.
+    applyAutoAnswer(opts.autoAnswer);
     // Live judge adapter (shared by suite + JSONL paths) for `judge.rubric`.
     let judgeAdapter;
     if (opts.judgeModel) {
@@ -65,6 +80,7 @@ export async function runEval(opts) {
     }
     // 5.4 — suite mode: load from evals/fixtures
     if (opts.suite) {
+        const suiteStart = Date.now();
         const fs = await import('node:fs/promises');
         const path = await import('node:path');
         // For smoke, use the 10 fixtures directly
@@ -75,8 +91,13 @@ export async function runEval(opts) {
             for (const e of entries) {
                 if (opts.filter && !e.includes(opts.filter))
                     continue;
-                // 6.5 — suite filter: smoke = type smoke, l6 = prefix l6-introduce
-                if (opts.suite && opts.suite !== 'smoke') {
+                // 5.5a — core = curated stable subset (see CORE_SUITE_FIXTURES).
+                if (opts.suite === 'core') {
+                    if (!CORE_SUITE_FIXTURES.includes(e))
+                        continue;
+                    // 6.5 — suite filter: smoke = type smoke, l6 = prefix l6-introduce
+                }
+                else if (opts.suite && opts.suite !== 'smoke') {
                     if (!e.startsWith(opts.suite) && !e.includes(opts.suite))
                         continue;
                 }
@@ -141,6 +162,16 @@ export async function runEval(opts) {
             await fs.mkdir(outDir, { recursive: true });
             const ts = new Date().toISOString().replace(/[:.]/g, '-');
             await fs.writeFile(path.join(outDir, `${ts}.json`), JSON.stringify({ suite: opts.suite, results }, null, 2));
+            // 5.5b — refresh the tracked baseline with environment metadata.
+            const { collectBaselineMetadata, buildEvalBaseline, writeEvalBaseline } = await import('../eval/baseline.js');
+            const meta = collectBaselineMetadata({ model: opts.model });
+            await writeEvalBaseline(outDir, buildEvalBaseline(meta, {
+                suite: opts.suite ?? '',
+                total: results.length,
+                passed,
+                failed: results.length - passed,
+                durationMs: Date.now() - suiteStart,
+            }));
         }
         catch { /* ignore */ }
         return passed === results.length ? 0 : 1;
@@ -165,6 +196,18 @@ export async function runEval(opts) {
             stdout.write(`[${tag}] ${r.name} (${r.durationMs}ms, ${r.steps} steps, ${r.toolCalls} tools)\n`);
             for (const f of r.failures)
                 stdout.write(`         - ${f}\n`);
+            // 5.4a — rich record extras (tokens/cost/files/verification).
+            const extras = [];
+            if (r.tokens)
+                extras.push(`${r.tokens.input} in/${r.tokens.output} out`);
+            if (r.costUsd !== undefined)
+                extras.push(`$${r.costUsd.toFixed(4)}`);
+            if (r.filesTouched && r.filesTouched.length > 0)
+                extras.push(`${r.filesTouched.length} files`);
+            if (r.verification)
+                extras.push(`verify:${r.verification.ok ? 'ok' : 'fail'}`);
+            if (extras.length > 0)
+                stdout.write(`         · ${extras.join(' · ')}\n`);
         }
     }
     const passed = results.filter((r) => r.passed).length;
@@ -332,5 +375,41 @@ export async function runScenario(sc, judgeOpts, workDir) {
         durationMs: 0,
         workDir: cwd,
         ...(judge ? { judge } : {}),
+        // 5.4a — rich records mapped from RunResult (cost reuses the runtime
+        // pricing helper, the same rates the budget code uses).
+        tokens: { input: result.usage.input, output: result.usage.output },
+        costUsd: estimateCost(model, result.usage),
+        filesTouched: collectFilesTouched(result.transcript),
+        ...(result.verification
+            ? { verification: { ok: result.verification.ok, attempts: result.verification.attempts } }
+            : {}),
+        ...(result.repairs !== undefined ? { repairs: result.repairs } : {}),
     };
 }
+/**
+ * 5.4a — best-effort distinct file paths from tool-call inputs in a run
+ * transcript. Looks for common path-ish keys on `tool_use` blocks.
+ * Exported for tests.
+ */
+const FILE_PATH_KEYS = ['path', 'file', 'filePath', 'filename', 'target'];
+export function collectFilesTouched(transcript) {
+    const seen = new Set();
+    for (const m of transcript) {
+        for (const b of m.content) {
+            if (b.kind !== 'tool_use')
+                continue;
+            const input = b.input;
+            for (const k of FILE_PATH_KEYS) {
+                const v = input[k];
+                if (typeof v === 'string' && v.length > 0)
+                    seen.add(v);
+                else if (Array.isArray(v)) {
+                    for (const e of v)
+                        if (typeof e === 'string' && e.length > 0)
+                            seen.add(e);
+                }
+            }
+        }
+    }
+    return [...seen].sort();
+}

package/dist/cli/repl.js

@@ -1261,6 +1261,20 @@ export async function startRepl(opts = {}) {
                     }
                     await undo(cwd, n);
                     let text = `Rewound to checkpoint ${n} (${target.id.slice(0, 12)}, ${target.files} file(s))`;
+                    // If transcript was captured for this checkpoint, restore it into the
+                    // active REPL session so /rewind full also reverts the conversation.
+                    const { readSnapshotTranscript } = await import('../checkpoints/store.js');
+                    const raw = await readSnapshotTranscript(cwd, target.id);
+                    // readSnapshotTranscript returns `unknown[]`; verify minimal Message shape
+                    // before giving it to adoptTranscript to avoid runtime type errors.
+                    const isMessage = (v) => !!v && typeof v === 'object' && 'role' in v && 'content' in v;
+                    if (Array.isArray(raw) && raw.length > 0 && raw.every(isMessage)) {
+                        sessionMessages = adoptTranscript(raw);
+                        text += '\nConversation restored from checkpoint transcript.';
+                    }
+                    else if (mode === 'full') {
+                        text += '\nConversation rewind skipped — no transcript captured for this checkpoint.';
+                    }
                     if (mode === 'summary' || mode === 'full') {
                         const files = before.split('\n').map((l) => l.trim()).filter(Boolean).slice(0, 20);
                         text += files.length > 0 ? `\nReverted working-tree changes:\n${files.map((f) => `  ${f}`).join('\n')}` : '\nWorking tree was clean before restore.';
@@ -2074,8 +2088,8 @@ export async function startRepl(opts = {}) {
                         queuedAppend({ id: `ckpt-${Date.now()}`, kind: 'text', text: 'Working tree clean — nothing to checkpoint.', role: 'assistant' });
                     }
                     else {
-                        const id = await snapshot(cwd, files.slice(0, 50));
-                        queuedAppend({ id: `ckpt2-${Date.now()}`, kind: 'text', text: `checkpoint ${String(id).slice(0, 8)} — ${files.length} file(s)`, role: 'assistant' });
+                        const id = await snapshot(cwd, files.slice(0, 50), { transcript: sessionMessages });
+                        queuedAppend({ id: `ckpt2-${Date.now()}`, kind: 'text', text: `checkpoint ${String(id).slice(0, 8)} — ${files.length} file(s)` + ` (conversation archived)`, role: 'assistant' });
                     }
                 }
                 catch (err) {

package/dist/cli/run.d.ts

@@ -91,6 +91,11 @@ export interface RunCliOptions {
     /** P1.4 — run the task under a named child-capable orchestrator context. */
     agent?: string;
     maxDepth?: number;
+    /**
+     * 5.3 — `--auto-answer <text>`: answer `ask_user` prompts headlessly.
+     * Applied to `process.env.KLYRO_AUTO_ANSWER` at the top of `runOnce`.
+     */
+    autoAnswer?: string;
 }
 /**
  * Split a comma-separated tool/dir list (string or string[]) into names.

package/dist/cli/run.js

@@ -23,6 +23,7 @@ import { memoryBlock } from '../context/memory.js';
 import { estimateCost } from '../providers/model-info.js';
 import { resolveModelAlias } from '../providers/model-info.js';
 import { logDebug, logInfo } from '../util/log.js';
+import { applyAutoAnswer } from './args.js';
 import { resolveSessionId } from '../persistence/session.js';
 import * as fs from 'node:fs';
 /**
@@ -71,6 +72,9 @@ export function shouldForceExit(lastSigintAt, now) {
     return lastSigintAt !== undefined && now - lastSigintAt < 1500;
 }
 export async function runOnce(opts) {
+    // 5.3 — --auto-answer sets KLYRO_AUTO_ANSWER before anything runs so
+    // headless ask_user calls resolve without prompting.
+    applyAutoAnswer(opts.autoAnswer);
     // 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 {

package/dist/context/klyro-md.d.ts

@@ -12,5 +12,16 @@ export interface KlyroMdFile {
 }
 /** Per-file loader (used by the trust gate to approve/hash individual files). */
 export declare function loadKlyroMdFiles(cwd: string): Promise<KlyroMdFile[]>;
+/**
+ * 4.4a — Subdirectory instructions: root files PLUS instruction files found
+ * in ancestor directories of targetPath from cwd down to targetPath's dir
+ * (nearest-wins order root→leaf, each capped like cap()).
+ *
+ * Laziness preserved: plain loadKlyroMdFiles(cwd) never reads subdirs —
+ * callers pass the relevant active path explicitly.
+ *
+ * Containment: a targetPath escaping cwd is rejected (root files only).
+ */
+export declare function loadKlyroMdForPath(cwd: string, targetPath: 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

@@ -30,16 +30,65 @@ export async function loadKlyroMdFiles(cwd) {
     // 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']) {
+    for (const name of INSTRUCTION_NAMES) {
         const p = path.join(cwd, name);
         try {
             const t = await fs.readFile(p, 'utf-8');
-            files.push({ path: p, content: cap(await resolveImports(t, path.dirname(p), cwd), MAX_FILE_CHARS) });
+            files.push({ path: p, content: cap(await resolveImports(t, path.dirname(p), cwd, 0, [p]), MAX_FILE_CHARS) });
         }
         catch { /* ignore */ }
     }
     return files;
 }
+/** Instruction file names read at every level (root + subdirectories). */
+const INSTRUCTION_NAMES = ['KLYRO.md', 'KLYRO.local.md', 'CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md', '.cursorrules'];
+/**
+ * 4.4a — Subdirectory instructions: root files PLUS instruction files found
+ * in ancestor directories of targetPath from cwd down to targetPath's dir
+ * (nearest-wins order root→leaf, each capped like cap()).
+ *
+ * Laziness preserved: plain loadKlyroMdFiles(cwd) never reads subdirs —
+ * callers pass the relevant active path explicitly.
+ *
+ * Containment: a targetPath escaping cwd is rejected (root files only).
+ */
+export async function loadKlyroMdForPath(cwd, targetPath) {
+    const files = await loadKlyroMdFiles(cwd);
+    const root = path.resolve(cwd);
+    const absTarget = path.resolve(root, targetPath);
+    const relTarget = path.relative(root, absTarget);
+    if (relTarget.startsWith('..') || path.isAbsolute(relTarget))
+        return files;
+    // Target dir: the target itself when it is an existing directory,
+    // otherwise its parent dir (i.e. the target is a file being edited).
+    let targetDir = absTarget;
+    try {
+        const st = await fs.stat(absTarget);
+        if (!st.isDirectory())
+            targetDir = path.dirname(absTarget);
+    }
+    catch {
+        targetDir = path.dirname(absTarget);
+    }
+    const relDir = path.relative(root, targetDir);
+    if (relDir.startsWith('..') || path.isAbsolute(relDir))
+        return files;
+    const segs = relDir.split(path.sep).filter((s) => s && s !== '.');
+    let prefix = root;
+    for (const seg of segs) {
+        prefix = path.join(prefix, seg);
+        const dir = prefix;
+        for (const name of INSTRUCTION_NAMES) {
+            const p = path.join(dir, name);
+            try {
+                const t = await fs.readFile(p, 'utf-8');
+                files.push({ path: p, content: cap(await resolveImports(t, path.dirname(p), root, 0, [p]), MAX_FILE_CHARS) });
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return files;
+}
 export async function loadKlyroMd(cwd) {
     const parts = [];
     let total = 0;
@@ -56,7 +105,7 @@ export async function loadKlyroMd(cwd) {
     }
     return parts.join('\n\n---\n\n');
 }
-async function resolveImports(text, base, root, depth = 0) {
+async function resolveImports(text, base, root, depth = 0, chain = []) {
     if (depth > 5)
         return text;
     const importRe = /^@import\s+(.+)$/gm;
@@ -69,9 +118,15 @@ async function resolveImports(text, base, root, depth = 0) {
         const relToRoot = path.relative(root, p);
         if (relToRoot.startsWith('..') || path.isAbsolute(relToRoot))
             continue;
+        // Cycle guard: an @import target already on the current chain resolves
+        // to a marker instead of recursing (depth cap stays as backstop).
+        if (chain.includes(p)) {
+            out = out.replace(m[0], `<!-- klyro: import cycle skipped: ${rel} -->`);
+            continue;
+        }
         try {
             const t = await fs.readFile(p, 'utf-8');
-            const resolved = await resolveImports(cap(t, MAX_FILE_CHARS), path.dirname(p), root, depth + 1);
+            const resolved = await resolveImports(cap(t, MAX_FILE_CHARS), path.dirname(p), root, depth + 1, [...chain, p]);
             out = out.replace(m[0], resolved);
         }
         catch { /* ignore missing */ }

package/dist/eval/baseline.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 5.5b — eval baseline writer. Records the environment alongside suite
+ * results so regressions can be attributed (model/node/platform/commit).
+ *
+ * The tracked `evals/results/baseline.json` is refreshed by `klyro eval
+ * --suite <name>` (best-effort; suite failures never fail the write path).
+ */
+export interface EvalBaselineMeta {
+    /** Model id the suite ran under (KLYRO_MODEL fallback, then 'mock'). */
+    model: string;
+    /** Node version (process.version). */
+    node: string;
+    /** OS platform (process.platform). */
+    platform: string;
+    /** Git HEAD, best-effort ('unknown' outside a repo). */
+    commit: string;
+    /** ISO timestamp of the run. */
+    timestamp: string;
+}
+export interface EvalBaseline extends EvalBaselineMeta {
+    suite: string;
+    total: number;
+    passed: number;
+    failed: number;
+    passRate: number;
+    durationMs: number;
+}
+/** Best-effort `git rev-parse HEAD` (never throws). Exported for tests. */
+export declare function gitCommit(cwd?: string): string;
+/** Collect the environment half of a baseline record. Exported for tests. */
+export declare function collectBaselineMetadata(opts?: {
+    model?: string;
+    cwd?: string;
+}): EvalBaselineMeta;
+/** Combine metadata + suite counts into a full baseline record. */
+export declare function buildEvalBaseline(meta: EvalBaselineMeta, suite: {
+    suite: string;
+    total: number;
+    passed: number;
+    failed: number;
+    durationMs: number;
+}): EvalBaseline;
+/**
+ * Write `baseline.json` into `dir` (created if needed). Returns the path.
+ * Never throws for missing dirs — the caller wraps in try/catch anyway.
+ */
+export declare function writeEvalBaseline(dir: string, baseline: EvalBaseline): Promise<string>;