klyro 1.0.1 → 1.0.3

package/dist/agent/runtime.js

@@ -22,12 +22,13 @@ import * as path from 'node:path';
 import { verify, diagnosticForModel } from '../verification/engine.js';
 import { detectVerifyCommand } from '../verification/auto.js';
 import { ensureBaseline, getBaseline } from '../verification/baseline.js';
-import { compressTranscript, totalTokens } from '../context/tokenizer.js';
-import { ratesFor } from '../providers/model-info.js';
+import { compressTranscript, totalTokens, calibrateEstimate, transcriptCharLength } from '../context/tokenizer.js';
+import { ratesFor, isAnthropicModel } from '../providers/model-info.js';
 import { classifyFailure, rerunOnce, gatherRepairContext, guardRepair } from '../verification/classify.js';
 import { findRelatedTests, buildScopedCommand, runScopedVerify, syntaxCheck, checkImports } from '../verification/scoped.js';
 import { globalBus } from '../events/bus.js';
 import { TraceWriter } from '../trace/writer.js';
+import { loadHooks, runHook } from '../cli/hooks.js';
 /** Normalize either systemPrompt shape into {system, suffix}. */
 export function resolveSystemPrompt(fn, ctx) {
     const r = fn(ctx);
@@ -42,18 +43,30 @@ export function toolDefinitions(registry) {
         inputSchema: t.function.parameters,
     }));
 }
-// BUG-005: Model-aware cost estimation, single-sourced from the
+// Model-aware cost estimation, single-sourced from the
 // providers/model-info.ts rate table (local/unknown models are $0).
-// Cost is computed on input/output ONLY: cacheRead/cacheWrite are tracked
-// for observability but excluded because cached tokens bill at
-// provider-specific discounted rates we don't model — charging them at
-// full input rates would overstate spend, silently dropping them
-// understates it, so we keep them visible and out of the math.
+// Cache-aware: for Anthropic-family models (isAnthropicModel), cacheRead
+// bills at 0.1× the input rate and cacheWrite at 1.25×; all other
+// families ignore cache counters (discounted billing, unmodeled).
 /** Estimate USD cost of a usage block given the model name. */
 export function estimateCost(model, usage) {
     const { input: inRate, output: outRate } = ratesFor(model);
-    return (usage.input / 1000) * inRate + (usage.output / 1000) * outRate;
+    const base = (usage.input / 1000) * inRate + (usage.output / 1000) * outRate;
+    if (!isAnthropicModel(model))
+        return base;
+    const read = ((usage.cacheRead ?? 0) / 1000) * inRate * 0.1;
+    const write = ((usage.cacheWrite ?? 0) / 1000) * inRate * 1.25;
+    return base + read + write;
 }
+/**
+ * Parallel fan-out cap: approved concurrencySafe tool calls execute in
+ * sequential chunks of at most this size. Commit order stays identical
+ * (commits run sequentially after execution), so the transcript reads as
+ * if the calls ran in order.
+ */
+export const MAX_PARALLEL_TOOLS = 8;
+/** Progressive budget-warning thresholds (fraction of maxCost), fired once each per run. */
+export const BUDGET_WARNING_THRESHOLDS = [0.4, 0.7, 0.9];
 // PERF-002: Memoized token counting cache.
 let tokenCache = {
     lastRef: null,
@@ -90,6 +103,18 @@ export async function run(opts, deps) {
         return [{ role: 'user', content: [text(opts.task)] }];
     })();
     const usage = { input: 0, output: 0 };
+    /** Emit one `budget_warning` per threshold the cost ratio has crossed. */
+    const checkBudgetWarnings = () => {
+        if (maxCost === undefined || maxCost <= 0)
+            return;
+        const ratio = estimateCost(opts.model, usage) / maxCost;
+        for (const threshold of BUDGET_WARNING_THRESHOLDS) {
+            if (ratio >= threshold && !firedBudgetWarnings.has(threshold)) {
+                firedBudgetWarnings.add(threshold);
+                emit?.({ kind: 'budget_warning', ratio, threshold });
+            }
+        }
+    };
     let steps = 0;
     let toolCallCount = 0;
     let finalText = '';
@@ -120,6 +145,27 @@ export async function run(opts, deps) {
     const emit = opts.onEvent;
     const telemetry = new RuntimeTelemetry();
     telemetry.setMaxSteps(maxSteps);
+    // Model-override surfacing (informational): when a parent/orchestrator
+    // context carries a model override, emit it once so UIs can show which
+    // model actually serves this run.
+    if (opts.parentContext?.model) {
+        emit?.({ kind: 'model_override', requested: opts.model, effective: opts.parentContext.model });
+    }
+    // Hooks engine: loaded once per run. Zero-cost fast path — when no hooks
+    // file exists, both lists are empty and every hook call site is skipped.
+    let runHooks = [];
+    try {
+        runHooks = loadHooks(opts.cwd);
+    }
+    catch {
+        runHooks = [];
+    }
+    const preHooks = runHooks.filter((h) => h.event === 'preToolUse');
+    const postHooks = runHooks.filter((h) => h.event === 'postToolUse');
+    // L15 failover chain: the active adapter starts as deps.adapter; each
+    // terminal provider error consumes one fallback. Bounded — never loops.
+    let activeAdapter = deps.adapter;
+    const failoverQueue = [...(deps.failoverAdapters ?? [])];
     // 3.1 — Event bus + TraceWriter
     const bus = deps.bus ?? globalBus;
     let tracer;
@@ -140,6 +186,10 @@ export async function run(opts, deps) {
     // 5.1 — phases and limits
     const maxCost = opts.maxCost;
     const maxTimeMs = opts.maxTimeMs;
+    // Progressive budget warnings: fire once per threshold per run when the
+    // cost ratio crosses 0.4 / 0.7 / 0.9 of maxCost (checker defined after
+    // `usage` is declared below).
+    const firedBudgetWarnings = new Set();
     const startTime = Date.now();
     let phase = 'understanding';
     const setPhase = (p) => {
@@ -270,7 +320,7 @@ export async function run(opts, deps) {
             ...(typeof opts.temperature === 'number' ? { temperature: opts.temperature } : {}),
             ...(opts.signal ? { signal: opts.signal } : {}),
         };
-        const events = deps.adapter.stream(req);
+        const events = activeAdapter.stream(req);
         let textBuf = '';
         // Thinking is ephemeral: streamed to the UI live, never stored in the
         // transcript, and cleared when the turn's answer completes.
@@ -279,6 +329,12 @@ export async function run(opts, deps) {
         let lastFinishReason;
         // Set when this step's request must be re-issued after overflow recovery.
         let overflowRetryPending = false;
+        // Set when a terminal provider error consumed a failover adapter — the
+        // step is re-issued against the next adapter without consuming budget.
+        let failoverPending = false;
+        let failoverFrom = '';
+        let failoverTo = '';
+        let failoverReason = '';
         for await (const ev of events) {
             if (opts.signal?.aborted)
                 break outer;
@@ -313,11 +369,16 @@ export async function run(opts, deps) {
                     if (ev.usage.cacheWrite !== undefined)
                         usage.cacheWrite = (usage.cacheWrite ?? 0) + ev.usage.cacheWrite;
                     telemetry.recordUsage(ev.usage.input, ev.usage.output);
+                    // R3 — calibrate the local chars/4 heuristic toward the real
+                    // per-character ratio this provider/model reports, so future budget
+                    // checks (and overflow recovery) estimate accurately.
+                    calibrateEstimate(transcriptCharLength(systemForBudget, reqMessages), ev.usage.input);
                     emit?.({
                         kind: 'usage', input: usage.input, output: usage.output,
                         ...(usage.cacheRead !== undefined ? { cacheRead: usage.cacheRead } : {}),
                         ...(usage.cacheWrite !== undefined ? { cacheWrite: usage.cacheWrite } : {}),
                     });
+                    checkBudgetWarnings();
                 }
                 else {
                     // Providers that omit usage (Ollama, vLLM, proxies): estimate from
@@ -329,6 +390,7 @@ export async function run(opts, deps) {
                     usage.estimated = true;
                     telemetry.recordUsage(est.input, est.output);
                     emit?.({ kind: 'usage', input: usage.input, output: usage.output, estimated: true });
+                    checkBudgetWarnings();
                 }
             }
             else if (ev.kind === 'error') {
@@ -357,6 +419,24 @@ export async function run(opts, deps) {
                     catch { /* ignore — retry with the transcript as-is */ }
                     break;
                 }
+                // L15 failover: a terminal provider error swaps to the next chained
+                // adapter and re-issues the step (bounded by chain length). Context
+                // overflow is excluded — it owns its own recovery above. By the time
+                // an error reaches the runtime, per-adapter retries are exhausted,
+                // so any provider error here is terminal for the active adapter.
+                if (failoverQueue.length > 0) {
+                    const next = failoverQueue.shift();
+                    failoverPending = true;
+                    failoverFrom = activeAdapter.id;
+                    failoverTo = next.id;
+                    failoverReason = `${ev.code}: ${ev.message}`.slice(0, 300);
+                    activeAdapter = next;
+                    telemetry.recordError(`failover: ${ev.code}`);
+                    emit?.({ kind: 'provider_failover', from: failoverFrom, to: failoverTo, reason: failoverReason });
+                    emit?.({ kind: 'status', message: `provider ${failoverFrom} failed (${ev.code}) — failing over to ${failoverTo}` });
+                    emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: ev.code, message: `failing over ${failoverFrom} → ${failoverTo}: ${ev.message.slice(0, 200)}` });
+                    break;
+                }
                 telemetry.recordError(`stream_error: ${ev.code}`);
                 if (store && sessionId) {
                     try {
@@ -386,6 +466,19 @@ export async function run(opts, deps) {
             emit?.({ kind: 'step_end', step: steps + 1 });
             continue outer;
         }
+        // Failover lands here via `break`: discard the failed attempt's partial
+        // output and re-issue the same step against the next adapter, again
+        // without consuming the step budget.
+        if (failoverPending) {
+            failoverPending = false;
+            textBuf = '';
+            thinkingBuf = '';
+            pendingToolCalls.clear();
+            lastFinishReason = undefined;
+            steps--;
+            emit?.({ kind: 'step_end', step: steps + 1 });
+            continue outer;
+        }
         // Build the assistant message. Tool calls are finalized here: JSON is
         // parsed and schema-validated BEFORE policy/execution. Malformed calls
         // become structured MALFORMED_TOOL_CALL results — garbage arguments must
@@ -478,7 +571,8 @@ export async function run(opts, deps) {
                     emit?.({ kind: 'verification_started', command: advisoryCmd });
                     let advisoryResult;
                     try {
-                        advisoryResult = await verify({ cwd: opts.cwd, command: advisoryCmd, timeoutMs: opts.verify?.timeoutMs });
+                        // CONTRACT (a): sessionId passthrough to the verify engine.
+                        advisoryResult = await verify({ cwd: opts.cwd, command: advisoryCmd, timeoutMs: opts.verify?.timeoutMs, ...(sessionId ? { sessionId } : {}) });
                     }
                     catch (e) {
                         const msg = e instanceof Error ? e.message : String(e);
@@ -557,7 +651,7 @@ export async function run(opts, deps) {
                             vResult = { ok: sr.ok, exitCode: sr.exitCode, stdout: sr.stdout, stderr: sr.stderr, ...(det ? { failure: det } : {}) };
                         }
                         else {
-                            vResult = await verify({ cwd: opts.cwd, command: cmdToRun, timeoutMs: opts.verify?.timeoutMs });
+                            vResult = await verify({ cwd: opts.cwd, command: cmdToRun, timeoutMs: opts.verify?.timeoutMs, ...(sessionId ? { sessionId } : {}) });
                         }
                     }
                     catch (e) {
@@ -568,7 +662,7 @@ export async function run(opts, deps) {
                 // If scoped passed but full may still fail, run full before declaring success
                 if (vResult.ok && isScoped) {
                     try {
-                        const full = await verify({ cwd: opts.cwd, command: verifyCmd, timeoutMs: opts.verify?.timeoutMs });
+                        const full = await verify({ cwd: opts.cwd, command: verifyCmd, timeoutMs: opts.verify?.timeoutMs, ...(sessionId ? { sessionId } : {}) });
                         if (!full.ok)
                             vResult = full;
                     }
@@ -787,6 +881,32 @@ export async function run(opts, deps) {
         const execTool = async (call) => {
             const t0 = Date.now();
             emitKlyro({ type: 'tool.call', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, input: call.input });
+            // Hooks: every preToolUse hook runs before execution. A non-zero exit
+            // denies the tool with POLICY_DENIED — the real tool never runs.
+            if (preHooks.length > 0) {
+                for (const hook of preHooks) {
+                    let exitCode = -1;
+                    let detail = '';
+                    try {
+                        const r = await runHook(hook, { toolName: call.name, input: call.input });
+                        exitCode = r.exitCode;
+                        detail = (r.stderr || r.stdout || '').slice(0, 300);
+                    }
+                    catch (err) {
+                        detail = String(err instanceof Error ? err.message : err).slice(0, 300);
+                    }
+                    if (exitCode !== 0) {
+                        const reason = `hook ${hook.name} denied: ${detail || 'hook failed'}`;
+                        emit?.({ kind: 'policy_decision', id: call.id, name: call.name, action: 'deny', reason });
+                        emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: 'deny', reason });
+                        const latencyMs = Date.now() - t0;
+                        return {
+                            obs: { ok: false, error: { code: 'POLICY_DENIED', message: reason } },
+                            latencyMs,
+                        };
+                    }
+                }
+            }
             let obs;
             try {
                 obs = await deps.registry.execute(call.name, call.input, toolCtx);
@@ -874,6 +994,31 @@ export async function run(opts, deps) {
             if (last3.length === 3 && last3[0] === last3[1] && last3[1] === last3[2]) {
                 await markStuck(`identical call ×3: ${sig}`);
             }
+            // Hooks: postToolUse hooks are best-effort — failures warn on stderr
+            // plus a bus event, and never fail the turn.
+            if (postHooks.length > 0) {
+                for (const hook of postHooks) {
+                    try {
+                        const r = await runHook(hook, { toolName: call.name, input: call.input });
+                        if (!r.ok || r.exitCode !== 0) {
+                            const msg = `klyro: hooks: postToolUse ${hook.name} failed (exit ${String(r.exitCode)}): ${(r.stderr || r.stdout || '').slice(0, 200)}\n`;
+                            try {
+                                process.stderr.write(msg);
+                            }
+                            catch { /* ignore */ }
+                            emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'hook_failed', message: msg.slice(0, 300) });
+                        }
+                    }
+                    catch (err) {
+                        const msg = `klyro: hooks: postToolUse ${hook.name} error: ${String(err instanceof Error ? err.message : err).slice(0, 200)}\n`;
+                        try {
+                            process.stderr.write(msg);
+                        }
+                        catch { /* ignore */ }
+                        emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'hook_failed', message: msg.slice(0, 300) });
+                    }
+                }
+            }
         };
         // Sequential path: gate → execute → commit per call, in order.
         const runOne = async (call) => {
@@ -897,8 +1042,17 @@ export async function run(opts, deps) {
                     break;
             }
             if (approved.length > 0 && !opts.signal?.aborted) {
-                const settled = await Promise.allSettled(approved.map((c) => execTool(c)));
-                for (let i = 0; i < approved.length; i++) {
+                // Fan-out cap: execute in sequential chunks of MAX_PARALLEL_TOOLS.
+                // Commits below stay in original call order, so the transcript is
+                // unaffected by the chunking.
+                const settled = [];
+                for (let off = 0; off < approved.length; off += MAX_PARALLEL_TOOLS) {
+                    if (opts.signal?.aborted)
+                        break;
+                    const chunk = approved.slice(off, off + MAX_PARALLEL_TOOLS);
+                    settled.push(...await Promise.allSettled(chunk.map((c) => execTool(c))));
+                }
+                for (let i = 0; i < settled.length; i++) {
                     const s = settled[i];
                     if (s.status === 'fulfilled') {
                         await commitResult(approved[i], s.value.obs, s.value.latencyMs);

package/dist/agent/stream-budget.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Rate-limit scheduler for provider streams.
+ *
+ * A global in-flight counter + FIFO semaphore caps concurrent
+ * `ProviderAdapter.stream` calls at `MAX_CONCURRENT_STREAMS` (4). An
+ * adaptive cooldown collapses the cap to 1 while a recent 429 was
+ * observed (`noteRateLimited`), honouring an optional server-provided
+ * `Retry-After` delay, otherwise 60s.
+ *
+ * Consumed by `retryingAdapter` (see `./retry.js`), which acquires one
+ * slot around each `inner.stream` call and releases it in a `finally`.
+ * Aborted waiters are dequeued and rejected promptly.
+ */
+export declare const MAX_CONCURRENT_STREAMS = 4;
+/** Fallback cooldown when no Retry-After delay was provided. */
+export declare const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 60000;
+/**
+ * Record a 429 (or equivalent) rate-limit signal. Collapses the stream
+ * cap to 1 for `retryAfterMs` (or 60s when absent/invalid).
+ */
+export declare function noteRateLimited(retryAfterMs?: number): void;
+/**
+ * Acquire a stream slot. Grants immediately when `inFlight` is under the
+ * effective cap, otherwise queues FIFO until a release (or the cooldown
+ * lifting) frees one. Abort-aware: an already-aborted signal rejects
+ * immediately; aborting while queued dequeues and rejects promptly.
+ */
+export declare function acquireStreamSlot(signal?: AbortSignal): Promise<() => void>;
+/** Observable budget state (tests/diagnostics). */
+export declare function streamBudgetState(): {
+    inFlight: number;
+    queued: number;
+    cap: number;
+};
+/** Reset the budget (counters, cooldown, queued waiters). Tests only. */
+export declare function setStreamBudgetForTests(): void;

package/dist/agent/stream-budget.js

@@ -0,0 +1,121 @@
+/**
+ * Rate-limit scheduler for provider streams.
+ *
+ * A global in-flight counter + FIFO semaphore caps concurrent
+ * `ProviderAdapter.stream` calls at `MAX_CONCURRENT_STREAMS` (4). An
+ * adaptive cooldown collapses the cap to 1 while a recent 429 was
+ * observed (`noteRateLimited`), honouring an optional server-provided
+ * `Retry-After` delay, otherwise 60s.
+ *
+ * Consumed by `retryingAdapter` (see `./retry.js`), which acquires one
+ * slot around each `inner.stream` call and releases it in a `finally`.
+ * Aborted waiters are dequeued and rejected promptly.
+ */
+export const MAX_CONCURRENT_STREAMS = 4;
+/** Fallback cooldown when no Retry-After delay was provided. */
+export const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 60_000;
+let inFlight = 0;
+/** `Date.now()` timestamp until which the cap stays collapsed at 1. */
+let recent429Until = 0;
+const queue = [];
+function abortError() {
+    const err = new Error('stream slot acquisition aborted');
+    err.name = 'AbortError';
+    return err;
+}
+function effectiveCap(now = Date.now()) {
+    return now < recent429Until ? 1 : MAX_CONCURRENT_STREAMS;
+}
+function makeRelease() {
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        inFlight = Math.max(0, inFlight - 1);
+        pump();
+    };
+}
+/** Grant queued waiters while a slot is free under the current cap. */
+function pump() {
+    while (queue.length > 0 && inFlight < effectiveCap()) {
+        const waiter = queue.shift();
+        if (!waiter)
+            break;
+        if (waiter.signal?.aborted) {
+            waiter.reject(abortError());
+            continue;
+        }
+        if (waiter.signal && waiter.onAbort) {
+            waiter.signal.removeEventListener('abort', waiter.onAbort);
+        }
+        inFlight += 1;
+        waiter.resolve(makeRelease());
+    }
+}
+/**
+ * Record a 429 (or equivalent) rate-limit signal. Collapses the stream
+ * cap to 1 for `retryAfterMs` (or 60s when absent/invalid).
+ */
+export function noteRateLimited(retryAfterMs) {
+    const cooldown = typeof retryAfterMs === 'number' &&
+        Number.isFinite(retryAfterMs) &&
+        retryAfterMs >= 0
+        ? retryAfterMs
+        : DEFAULT_RATE_LIMIT_COOLDOWN_MS;
+    recent429Until = Date.now() + cooldown;
+    // Wake queued waiters once the cooldown lifts even if no release
+    // happens in between (holders may outlive the cooldown). Unref'd so
+    // tests and short-lived processes never hang on this timer.
+    if (cooldown > 0 && cooldown < 3_600_000) {
+        const timer = setTimeout(pump, cooldown);
+        timer.unref?.();
+    }
+}
+/**
+ * Acquire a stream slot. Grants immediately when `inFlight` is under the
+ * effective cap, otherwise queues FIFO until a release (or the cooldown
+ * lifting) frees one. Abort-aware: an already-aborted signal rejects
+ * immediately; aborting while queued dequeues and rejects promptly.
+ */
+export function acquireStreamSlot(signal) {
+    if (signal?.aborted)
+        return Promise.reject(abortError());
+    if (inFlight < effectiveCap()) {
+        inFlight += 1;
+        return Promise.resolve(makeRelease());
+    }
+    return new Promise((resolve, reject) => {
+        const waiter = { resolve, reject };
+        if (signal) {
+            waiter.signal = signal;
+            waiter.onAbort = () => {
+                const idx = queue.indexOf(waiter);
+                if (idx >= 0)
+                    queue.splice(idx, 1);
+                reject(abortError());
+            };
+            signal.addEventListener('abort', waiter.onAbort, { once: true });
+        }
+        queue.push(waiter);
+        // Re-check: the cap may have widened (cooldown expiry) between the
+        // fast-path check and the push.
+        pump();
+    });
+}
+/** Observable budget state (tests/diagnostics). */
+export function streamBudgetState() {
+    return { inFlight, queued: queue.length, cap: effectiveCap() };
+}
+/** Reset the budget (counters, cooldown, queued waiters). Tests only. */
+export function setStreamBudgetForTests() {
+    inFlight = 0;
+    recent429Until = 0;
+    const pending = queue.splice(0, queue.length);
+    for (const waiter of pending) {
+        if (waiter.signal && waiter.onAbort) {
+            waiter.signal.removeEventListener('abort', waiter.onAbort);
+        }
+        waiter.reject(new Error('stream budget reset'));
+    }
+}

package/dist/checkpoints/store.d.ts

@@ -1,5 +1,14 @@
 /**
  * 4.5 — Checkpoint snapshots: every mutation to checkpoints dir
+ *
+ * Snapshot bytes stay RAW (no redaction): checkpoint copies must be
+ * bit-identical to the working tree so undo() restores exact fidelity —
+ * redacting at snapshot time would corrupt restores (a redacted snapshot
+ * written back would permanently replace real code with [REDACTED]).
+ * Same-trust-domain rationale: snapshots never leave the project dir and
+ * are only read back by undo() into the same tree, so secret hygiene is
+ * enforced at the trace/persist boundaries (TraceWriter, SessionStore)
+ * instead of here.
  */
 export declare function snapshot(cwd: string, files: string[]): Promise<string>;
 export declare function listCheckpoints(cwd: string): Promise<string[]>;

package/dist/checkpoints/store.js

@@ -1,12 +1,34 @@
 /**
  * 4.5 — Checkpoint snapshots: every mutation to checkpoints dir
+ *
+ * Snapshot bytes stay RAW (no redaction): checkpoint copies must be
+ * bit-identical to the working tree so undo() restores exact fidelity —
+ * redacting at snapshot time would corrupt restores (a redacted snapshot
+ * written back would permanently replace real code with [REDACTED]).
+ * Same-trust-domain rationale: snapshots never leave the project dir and
+ * are only read back by undo() into the same tree, so secret hygiene is
+ * enforced at the trace/persist boundaries (TraceWriter, SessionStore)
+ * instead of here.
  */
 import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 function ckptDir(cwd) {
     return path.join(cwd, '.klyro', 'checkpoints');
 }
+/**
+ * Best-effort permission lockdown (0600 files / 0700 dirs).
+ * Windows ACLs ignore POSIX mode bits — no-op by design.
+ */
+function lockDown(p, mode) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        fsSync.chmodSync(p, mode);
+    }
+    catch { /* best-effort only */ }
+}
 /** Best-effort fsync of a just-written file (crash safety). */
 async function fsyncFile(p) {
     try {
@@ -35,9 +57,11 @@ function containedPath(cwd, base, rel) {
 export async function snapshot(cwd, files) {
     const dir = ckptDir(cwd);
     await fs.mkdir(dir, { recursive: true });
+    lockDown(dir, 0o700);
     const id = `${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
     const dest = path.join(dir, id);
     await fs.mkdir(dest, { recursive: true });
+    lockDown(dest, 0o700);
     const missing = [];
     const kept = [];
     for (const f of files) {
@@ -52,6 +76,7 @@ export async function snapshot(cwd, files) {
                 continue;
             await fs.mkdir(path.dirname(out), { recursive: true });
             await fs.writeFile(out, data);
+            lockDown(out, 0o600);
             await fsyncFile(out);
             kept.push(rel);
         }
@@ -65,6 +90,7 @@ export async function snapshot(cwd, files) {
     // SessionStore.writeIndex atomic pattern).
     const metaPath = path.join(dest, '.meta.json');
     await fs.writeFile(metaPath, JSON.stringify({ id, files: kept, missing, ts: Date.now() }, null, 2));
+    lockDown(metaPath, 0o600);
     await fsyncFile(metaPath);
     // Best-effort last.diff for the repair guard (guardRepair reads it).
     try {

package/dist/cli/commit.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `klyro commit` — conventional commit of already-staged changes.
+ *
+ * Steps:
+ *   (a) `git status --porcelain` must show staged entries (index column set).
+ *       Nothing staged → error 'nothing staged (git add first)', exit 2.
+ *       (`--yes` never bypasses this — there is nothing to commit.)
+ *   (b) Secret-scan the staged diff via `redact()`: if redaction shrinks or
+ *       alters the diff, refuse and list the files (exit 2) unless
+ *       `--force-secret` is passed.
+ *   (c) Build a conventional message: type heuristic + top-dir scope +
+ *       `--message` summary (or `update <n> files`).
+ *   (d) `git commit -m` via execFileSync (no shell). Verification hooks always
+ *       run — by construction this file contains no flag that skips them.
+ *   (e) `--dry-run` prints the message + files and exits 0 without committing.
+ */
+export interface CommitOptions {
+    cwd: string;
+    yes?: boolean;
+    dryRun?: boolean;
+    message?: string;
+    forceSecret?: boolean;
+}
+/** Porcelain XY: staged iff the index (first) column is set. Handles renames. */
+export declare function stagedFilesFromPorcelain(porcelain: string): string[];
+/** Type heuristic: test-only→test, docs-only→docs, lockfiles→chore, else feat. */
+export declare function commitTypeFor(files: string[]): string;
+/** Scope = most common top-level dir among staged files with a dir; '' if none. */
+export declare function commitScopeFor(files: string[]): string;
+export declare function buildCommitMessage(files: string[], summaryOpt?: string): string;
+export declare function runCommit(opts: CommitOptions): Promise<number>;