klyro 1.0.16 → 1.0.18

package/dist/cli/run.js

@@ -7,6 +7,7 @@
  * even on a long task. Tool calls and policy decisions go to stderr so
  * they don't pollute the captured `finalText` if the user pipes.
  */
+import * as path from 'node:path';
 import { stdout, stderr } from 'node:process';
 import { httpChatAdapter } from '../agent/provider-adapter.js';
 import { anthropicAdapter } from '../agent/anthropic-adapter.js';
@@ -20,8 +21,48 @@ import { redact } from '../policy/secret-redactor.js';
 import { buildLevel6Context } from '../context/level6.js';
 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';
+/**
+ * Split a comma-separated tool/dir list (string or string[]) into names.
+ * Exported for tests.
+ */
+export function splitToolList(v) {
+    const arr = v === undefined ? [] : Array.isArray(v) ? v : [v];
+    return arr.flatMap((s) => String(s).split(',')).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+/** Smaller of two optional caps (--max-turns aliases --max-steps). Exported for tests. */
+export function minDefined(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return Math.min(a, b);
+}
+/**
+ * Layer --system-prompt/--append-system-prompt over the assembled prompt
+ * (2.3): replace wins wholesale, append rides after the assembled system
+ * (preserving any suffix the base carries). Exported for tests.
+ */
+export function withSystemPromptOverrides(base, opts) {
+    if (opts.replace === undefined && opts.append === undefined)
+        return base;
+    return (ctx) => {
+        if (opts.replace !== undefined) {
+            return opts.append ? `${opts.replace}\n\n${opts.append}` : opts.replace;
+        }
+        const r = base(ctx);
+        const system = typeof r === 'string' ? r : r.system;
+        const suffix = typeof r === 'string' ? undefined : r.suffix;
+        const out = { system: `${system}\n\n${opts.append}` };
+        if (suffix !== undefined)
+            out.suffix = suffix;
+        return out;
+    };
+}
 /**
  * Double-Ctrl+C detector (pure, exported for tests): the second SIGINT
  * within 1500ms of the first forces `process.exit(130)`. The live handler
@@ -31,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 {
@@ -38,6 +82,9 @@ export async function runOnce(opts) {
         loadDotenv(opts.cwd);
     }
     catch { /* ignore */ }
+    // Model aliases (2.2: sonnet/opus/haiku/gpt/local) resolve once here so
+    // the session store, cost math, and every adapter agree on the id.
+    opts = { ...opts, model: resolveModelAlias(opts.model) };
     const output = opts.output ?? 'human';
     if (opts.dryRun) {
         return await dryRunReport(opts);
@@ -138,7 +185,18 @@ export async function runOnce(opts) {
         catch { /* best-effort — single-provider run proceeds */ }
     }
     const registry = builtinRegistry();
-    const policy = new PolicyEngine(builtinRules(), clonePolicyConfig());
+    const policyConfig = clonePolicyConfig();
+    // Explicit CLI overrides (3.4). Persisted rules load next via applyRules;
+    // the engine's deny-first precedence keeps any denial terminal.
+    if (opts.permissionMode !== undefined)
+        policyConfig.mode = opts.permissionMode;
+    for (const t of splitToolList(opts.allowedTools))
+        policyConfig.allow.push(t);
+    for (const t of splitToolList(opts.disallowedTools))
+        policyConfig.deny.push(t);
+    for (const d of splitToolList(opts.addDir))
+        policyConfig.additionalDirs.push(path.resolve(opts.cwd, d));
+    const policy = new PolicyEngine(builtinRules(), policyConfig);
     // Persisted "always allow" patterns apply to one-shot runs too.
     try {
         const { loadPermissionRules } = await import('./config.js');
@@ -181,7 +239,7 @@ export async function runOnce(opts) {
         }
         catch { /* ignore — MCP is optional */ }
     }
-    const systemPrompt = await makeRunSystemPrompt(opts.cwd, opts.systemPrompt ?? defaultRunSystemPrompt, opts.bare);
+    const systemPrompt = withSystemPromptOverrides(await makeRunSystemPrompt(opts.cwd, opts.systemPrompt ?? defaultRunSystemPrompt, opts.bare), { replace: opts.systemPromptText, append: opts.appendSystemPrompt });
     // Level 9 — session setup (create or resume). --bare skips persistence.
     const persistEnabled = opts.persist !== false && !opts.bare;
     let store;
@@ -219,9 +277,6 @@ export async function runOnce(opts) {
                 stderr.write(`klyro: resuming session ${sessionId.slice(0, 8)} — task: "${rec.task}"\n`);
             }
         }
-        else if (opts.resumePath) {
-            // already handled
-        }
         else {
             // Create new session
             const rec = await store.create({ cwd: opts.cwd, task: opts.task, config: { model: opts.model, maxSteps: opts.maxSteps ?? 30 } });
@@ -313,23 +368,34 @@ export async function runOnce(opts) {
             model: opts.model,
         });
     }
+    // 2.5 latency tracking: TTFT = first model event after run start.
+    const runStartMs = Date.now();
+    let ttftMs;
+    logDebug('run start', { model: opts.model, maxSteps: opts.maxSteps, bare: !!opts.bare });
     try {
         result = await run({
             task: opts.task,
             cwd: opts.cwd,
             model: opts.model,
             ...(opts.bare ? { bare: true } : {}),
-            maxSteps: opts.maxSteps,
+            maxSteps: minDefined(opts.maxSteps, opts.maxTurns),
             maxTokens: opts.maxTokens,
             temperature: opts.temperature,
+            reasoningEffort: opts.reasoningEffort,
             signal: ac.signal,
             nonInteractive: true,
             initialTranscript,
+            // Sandbox roots for file tools: cwd plus --add-dir extras (resolved
+            // absolute). checkAllowedPaths narrows to exactly this set.
+            allowedPaths: [path.resolve(opts.cwd), ...(policyConfig.additionalDirs ?? [])],
             verify: verifyOpts,
             persist: store && sessionId ? { store, sessionId } : undefined,
             ...(agentBridge ? { agentBridge } : {}),
             ...(parentContext ? { parentContext } : {}),
             onEvent: (ev) => {
+                if (ttftMs === undefined && (ev.kind === 'text_delta' || ev.kind === 'tool_call_start')) {
+                    ttftMs = Date.now() - runStartMs;
+                }
                 if (output === 'json') {
                     stdout.write(JSON.stringify(ev) + '\n');
                     return;
@@ -436,9 +502,12 @@ export async function runOnce(opts) {
     // [budget] warnings. Human/silent → stderr one-liner; json → additive
     // cost_usd/usage fields on the final object (purely additive, no shape break).
     const finalCost = estimateCost(opts.model, result.usage.input, result.usage.output);
-    const costLine = `$${finalCost.toFixed(4)} · ${result.usage.input} in / ${result.usage.output} out${result.usage.estimated ? ' (estimated)' : ''}`;
+    const totalMs = Date.now() - runStartMs;
+    logInfo('run finish', { status: result.status, steps: result.steps, toolCalls: result.toolCalls, totalMs });
+    const ttftPart = ttftMs !== undefined ? ` · ttft ${ttftMs}ms` : '';
+    const costLine = `$${finalCost.toFixed(4)} · ${result.usage.input} in / ${result.usage.output} out${result.usage.estimated ? ' (estimated)' : ''}${ttftPart} · total ${totalMs}ms`;
     if (output === 'json') {
-        stdout.write(JSON.stringify({ kind: 'cost', cost_usd: finalCost, usage: result.usage }) + '\n');
+        stdout.write(JSON.stringify({ kind: 'cost', cost_usd: finalCost, usage: result.usage, ttft_ms: ttftMs ?? null, total_ms: totalMs }) + '\n');
     }
     else {
         stderr.write(`klyro: cost ${costLine}\n`);
@@ -457,6 +526,8 @@ export async function runOnce(opts) {
                 toolCalls: result.toolCalls,
                 cost_usd: finalCost,
                 usage: result.usage,
+                ttft_ms: ttftMs ?? null,
+                total_ms: totalMs,
                 ...(result.verification ? { verification: result.verification } : {}),
                 ...(sessionId ? { session_id: sessionId } : {}),
                 ...extra,
@@ -523,7 +594,7 @@ export async function runOnce(opts) {
 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 systemPromptFn = withSystemPromptOverrides(await makeRunSystemPrompt(opts.cwd, opts.systemPrompt ?? defaultRunSystemPrompt), { replace: opts.systemPromptText, append: opts.appendSystemPrompt });
     const { resolveSystemPrompt } = await import('../agent/runtime.js');
     const { system, suffix } = resolveSystemPrompt(systemPromptFn, { cwd: opts.cwd });
     const systemPrompt = suffix ? `${system}\n\n${suffix}` : system;
@@ -536,6 +607,7 @@ async function dryRunReport(opts) {
         maxSteps: opts.maxSteps,
         maxTokens: opts.maxTokens,
         temperature: opts.temperature,
+        reasoningEffort: opts.reasoningEffort,
         // Secrets must never leak into a printable report: redact both the
         // assembled system prompt and the task before printing.
         systemPrompt: redact(systemPrompt),

package/dist/cli/update.js

@@ -13,6 +13,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { createHash } from 'node:crypto';
+import { proxiedFetch } from '../shared/proxy.js';
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 const REGISTRY_BASE = 'https://registry.npmjs.org/klyro';
 const FETCH_TIMEOUT_MS = 3000;
@@ -64,7 +65,7 @@ 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 });
+        const res = await proxiedFetch(url, { signal: ctrl.signal, timeoutMs });
         if (!res.ok)
             throw new Error(`HTTP ${res.status}`);
         return res;
@@ -95,6 +96,11 @@ async function verifyTarballIntegrity(dist) {
 export async function checkForUpdate(current) {
     if (process.env.KLYRO_NO_UPDATE_CHECK === '1')
         return null;
+    // Disabled in CI unless explicitly enabled (1.5): automated pipelines
+    // must never phone home or suggest interactive updates.
+    if ((process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true') && process.env.KLYRO_UPDATE_CHECK !== '1') {
+        return null;
+    }
     const cache = cachePath();
     try {
         const raw = await fs.readFile(cache, 'utf-8');

package/dist/context/accounting.js

@@ -2,8 +2,8 @@
  * 8.1 — Accounting & stable assembly
  * Live token estimate, ctx%, compactAt, reserveOutput, toolResultMax
  */
-import { totalTokens } from './tokenizer.js';
 import { getModelInfo } from '../providers/model-info.js';
+import { totalTokens } from './tokenizer.js';
 /**
  * Single output-reserve used by every budget in the harness (displayed
  * accounting, runtime enforcement, compaction elide). One constant so the

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/context/level7.d.ts

@@ -61,6 +61,10 @@ export declare class RuntimeTelemetry {
     private errorCount;
     private recent;
     constructor(opts?: Level7Options);
+    private muted;
+    /** Disable telemetry accumulation + reporting (also via KLYRO_TELEMETRY=0). */
+    mute(): void;
+    isMuted(): boolean;
     setMaxSteps(n: number): void;
     recordStepStart(step: number): void;
     recordUsage(input: number, output: number): void;

package/dist/context/level7.js

@@ -40,14 +40,29 @@ export class RuntimeTelemetry {
             maxRecentCalls: opts.maxRecentCalls ?? DEFAULT_MAX_RECENT,
             maxChars: opts.maxChars ?? DEFAULT_MAX_CHARS,
         };
+        // KLYRO_TELEMETRY=0 disables telemetry accumulation + reporting.
+        this.muted = process.env.KLYRO_TELEMETRY === '0';
+    }
+    muted = false;
+    /** Disable telemetry accumulation + reporting (also via KLYRO_TELEMETRY=0). */
+    mute() {
+        this.muted = true;
+    }
+    isMuted() {
+        return this.muted;
     }
     setMaxSteps(n) { this.maxSteps = n; }
-    recordStepStart(step) { this.step = step; }
+    recordStepStart(step) { if (!this.muted)
+        this.step = step; }
     recordUsage(input, output) {
+        if (this.muted)
+            return;
         this.inputTokens += input;
         this.outputTokens += output;
     }
     recordToolCall(call, latencyMs, isError) {
+        if (this.muted)
+            return;
         this.toolCallCount++;
         if (isError)
             this.errorCount++;
@@ -63,6 +78,8 @@ export class RuntimeTelemetry {
         }
     }
     recordError(msg) {
+        if (this.muted)
+            return;
         this.lastError = msg;
     }
     /**
@@ -89,6 +106,8 @@ export class RuntimeTelemetry {
         };
     }
     format() {
+        if (this.muted)
+            return emptyTelemetryBlock();
         const s = this.snapshot();
         const lines = [];
         lines.push('# Runtime telemetry');

package/dist/context/project-map.js

@@ -21,6 +21,7 @@
  *     what to walk past.
  */
 import * as fs from 'node:fs/promises';
+import { statSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 export const IGNORED_DIRS = new Set([
     'node_modules', '.git', 'dist', 'build', '.next', '.turbo',
@@ -246,7 +247,7 @@ function detectPackageManager(root, pkg) {
         // Avoid the async cost by re-using the root listing we already do.
         // (Caller threads the listing into detectFrameworks; here we re-stat directly.)
         try {
-            require('node:fs').statSync(path.join(root, lock));
+            statSync(path.join(root, lock));
             return pm;
         }
         catch { /* not present */ }
@@ -295,9 +296,9 @@ function extractBuildCommands(pkg, root) {
     // Makefile: pick the first `target:` block as a hint.
     // (Don't try to parse make fully — just surface the targets as a single hint.)
     try {
-        const stat = require('node:fs').statSync(path.join(root, 'Makefile'));
+        const stat = statSync(path.join(root, 'Makefile'));
         if (stat.isFile() && stat.size < MAX_BYTES) {
-            const raw = require('node:fs').readFileSync(path.join(root, 'Makefile'), 'utf-8');
+            const raw = readFileSync(path.join(root, 'Makefile'), 'utf-8');
             const targets = [...raw.matchAll(/^([a-zA-Z_][\w-]*)\s*:/gm)].map((m) => m[1]).slice(0, 6);
             if (targets.length)
                 out.push(`make <target>  # targets: ${targets.join(', ')}`);
@@ -368,11 +369,11 @@ async function gitHead(root) {
 }
 function lockfileHash(root) {
     const candidates = ['pnpm-lock.yaml', 'yarn.lock', 'package-lock.json', 'bun.lockb', 'Cargo.lock', 'go.sum', 'poetry.lock', 'uv.lock'];
-    let h = crypto.createHash('sha1');
+    const h = crypto.createHash('sha1');
     let found = false;
     for (const f of candidates) {
         try {
-            const d = require('node:fs').readFileSync(path.join(root, f));
+            const d = readFileSync(path.join(root, f));
             h.update(d);
             found = true;
         }
@@ -456,17 +457,17 @@ function detectMonorepo(root, rootFiles, rootDirs) {
         return true;
     if (rootDirs.includes('packages') || rootDirs.includes('apps')) {
         try {
-            const s = require('node:fs').statSync(path.join(root, 'packages'));
+            const s = statSync(path.join(root, 'packages'));
             if (s.isDirectory())
                 return true;
         }
-        catch { }
+        catch { /* ignore — best-effort probe */ }
         try {
-            const s2 = require('node:fs').statSync(path.join(root, 'apps'));
+            const s2 = statSync(path.join(root, 'apps'));
             if (s2.isDirectory())
                 return true;
         }
-        catch { }
+        catch { /* ignore — best-effort probe */ }
     }
     return false;
 }
@@ -477,20 +478,20 @@ async function detectRuntimeVersions(root) {
         if (v)
             out['node'] = v.trim();
     }
-    catch { }
+    catch { /* ignore — best-effort probe */ }
     try {
         const pkg = await readJsonSafe(path.join(root, 'package.json'));
         const eng = pkg?.engines;
         if (eng?.node)
             out['node-eng'] = eng.node;
     }
-    catch { }
+    catch { /* ignore — best-effort probe */ }
     try {
         const py = await readTextSafe(path.join(root, '.python-version'));
         if (py)
             out['python'] = py.trim();
     }
-    catch { }
+    catch { /* ignore — best-effort probe */ }
     try {
         const go = await readTextSafe(path.join(root, 'go.mod'));
         if (go) {
@@ -499,7 +500,7 @@ async function detectRuntimeVersions(root) {
                 out['go'] = m[1];
         }
     }
-    catch { }
+    catch { /* ignore — best-effort probe */ }
     return out;
 }
 async function detectEntryPoints(root) {

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>;

package/dist/eval/baseline.js

@@ -0,0 +1,55 @@
+/**
+ * 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).
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+/** Best-effort `git rev-parse HEAD` (never throws). Exported for tests. */
+export function gitCommit(cwd = process.cwd()) {
+    try {
+        const out = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).toString().trim();
+        return out || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Collect the environment half of a baseline record. Exported for tests. */
+export function collectBaselineMetadata(opts = {}) {
+    return {
+        model: opts.model ?? process.env.KLYRO_MODEL ?? 'mock',
+        node: process.version,
+        platform: process.platform,
+        commit: gitCommit(opts.cwd),
+        timestamp: new Date().toISOString(),
+    };
+}
+/** Combine metadata + suite counts into a full baseline record. */
+export function buildEvalBaseline(meta, suite) {
+    return {
+        ...meta,
+        suite: suite.suite,
+        total: suite.total,
+        passed: suite.passed,
+        failed: suite.failed,
+        passRate: suite.total === 0 ? 0 : suite.passed / suite.total,
+        durationMs: suite.durationMs,
+    };
+}
+/**
+ * Write `baseline.json` into `dir` (created if needed). Returns the path.
+ * Never throws for missing dirs — the caller wraps in try/catch anyway.
+ */
+export async function writeEvalBaseline(dir, baseline) {
+    await fsp.mkdir(dir, { recursive: true });
+    const out = path.join(dir, 'baseline.json');
+    await fsp.writeFile(out, JSON.stringify(baseline, null, 2) + '\n');
+    return out;
+}

package/dist/eval/harness.d.ts

@@ -77,10 +77,21 @@ export interface FileFixture {
     script?: StreamEvent[][];
 }
 export declare function loadFileFixture(dir: string): Promise<FileFixture>;
-export declare function runFileFixture(fixture: FileFixture, opts?: {
+export declare function sanitizedFixtureEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * 5.4b — guard: fixture workdirs must stay inside `os.tmpdir()` (the
+ * harness relies on that isolation). Throws otherwise unless the caller
+ * explicitly passes `allowWorkdirOutsideTmp`. Exported for tests.
+ */
+export declare function assertTmpWorkdir(dir: string, opts?: {
+    allowWorkdirOutsideTmp?: boolean;
+}): void;
+export interface FileFixtureOptions {
     runs?: number;
     parallel?: number;
-}): Promise<TaskResult>;
+    allowWorkdirOutsideTmp?: boolean;
+}
+export declare function runFileFixture(fixture: FileFixture, _opts?: FileFixtureOptions): Promise<TaskResult>;
 /**
  * Agent-driven fixture: seed a tmp repo, run the fixture's canned script
  * through the REAL runtime + tools, then assert outcomes with check.sh
@@ -90,6 +101,7 @@ export declare function runFileFixture(fixture: FileFixture, opts?: {
 export declare function runAgentFixture(fixture: FileFixture, opts?: {
     judgeAdapter?: ProviderAdapter;
     judgeModel?: string;
+    allowWorkdirOutsideTmp?: boolean;
 }): Promise<TaskResult>;
 /** Hook the harness up to a session + audit log so task runs are durable. */ export declare function runHarnessWithPersistence(tasks: ScriptedTask[], opts: {
     storeDir: string;