peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/loop/monotonic-guard.d.ts

@@ -0,0 +1,80 @@
+/**
+ * peaks-loop v3.0.0 — Slice C.1
+ *
+ * Monotonic-improvement guard for the loop runtime. Compares adjacent
+ * cycles' per-evaluator scores (rescaled gateAction → 0..1) and
+ * returns a structured envelope indicating:
+ *
+ *   - status: 'pass' | 'warn' | 'block' | 'skip'
+ *   - regressions: per-evaluator score deltas where current < previous
+ *   - reason: human-readable summary
+ *
+ * Karpathy §2 Simplicity First: pure function, no IO, no new deps.
+ *
+ * File budget: ≤ 800 lines (Karpathy §2).
+ */
+/** Per-evaluator score row, derived from an `EvaluatorVerdictEnvelope`. */
+export interface MonotonicScoreRow {
+    readonly evaluator: string;
+    readonly score: number;
+    readonly gateAction: 'pass' | 'warn' | 'block';
+    readonly degraded: boolean;
+    /** ISO-8601 timestamp the verdict was recorded. */
+    readonly observedAt: string;
+}
+/** Cycle index — a single attempt at the loop. */
+export interface MonotonicCycle {
+    readonly cycle: number;
+    /** Per-evaluator score rows. Same evaluator appearing twice collapses
+     *  to the last entry (BC: deterministic, no merging surprises). */
+    readonly scores: readonly MonotonicScoreRow[];
+}
+export interface MonotonicRegression {
+    readonly evaluator: string;
+    readonly previousScore: number;
+    readonly currentScore: number;
+    readonly delta: number;
+}
+/** Result of a `checkMonotonicImprovement` call. */
+export interface MonotonicReport {
+    readonly status: 'pass' | 'warn' | 'block' | 'skip';
+    readonly ok: boolean;
+    readonly reason: string;
+    readonly threshold: number;
+    readonly previousCycle: number | null;
+    readonly currentCycle: number;
+    /** Per-evaluator regressions exceeding the threshold (sorted by |delta| desc). */
+    readonly regressions: readonly MonotonicRegression[];
+    /** Convenience boolean — true iff a regression exceeds the threshold. */
+    readonly monotonicityViolation: boolean;
+    /** Diagnostic hint surfaced as `MONOTONICITY_VIOLATION` in the CLI envelope. */
+    readonly code: 'MONOTONIC_OK' | 'MONOTONIC_NO_PREVIOUS' | 'MONOTONIC_VIOLATION' | 'MONOTONIC_INCOMPARABLE_EVALUATORS';
+}
+/** Convert an envelope-shaped verdict row to `MonotonicScoreRow`.
+ *  Pure helper, exported for the CLI layer. */
+export declare function toScoreRow(evaluator: string, gateAction: 'pass' | 'warn' | 'block', degraded: boolean, observedAtIso?: string): MonotonicScoreRow;
+/** Default threshold = 5% of [0,1] scale → 0.05. */
+export declare const DEFAULT_MONOTONIC_THRESHOLD = 0.05;
+export interface CheckMonotonicOptions {
+    /** Maximum regression permitted (in [0,1] scale). Default 0.05 (5%). */
+    readonly threshold?: number;
+    /** When provided, the guard logs the cycle id this report refers to. */
+    readonly nowIso?: string;
+}
+/** Compare `previous` against `current` and report monotonicity.
+ *
+ *  Rules (reflected in `tests/unit/loop/monotonic-guard.test.ts`):
+ *    - missing previous cycle → skip (`MONOTONIC_NO_PREVIOUS`)
+ *    - evaluators not present in both cycles → skip that evaluator
+ *    - score unchanged / up → ok
+ *    - score ↓ ≤ threshold → ok
+ *    - score ↓ > threshold → regression row + status 'block'
+ *      with `code = MONOTONICITY_VIOLATION`.
+ */
+export declare function checkMonotonicImprovement(previous: MonotonicCycle | null, current: MonotonicCycle, options?: CheckMonotonicOptions): MonotonicReport;
+/** Read `.peaks/_sub_agents/<sid>/shared/` cross-session signal — on
+ *  any IO error, return `null` so the guard never crashes on missing
+ *  cross-batch signal (per Slice C (b) case "跨 session 读
+ *  .peaks/_sub_agents/<sid>/shared/ 跨批 signal → 不 crash").
+ *  Pure helper; only present for the cross-session case. */
+export declare function loadCrossSessionSignal(projectRoot: string, sid: string): MonotonicCycle | null;

package/dist/services/loop/monotonic-guard.js

@@ -0,0 +1,232 @@
+/**
+ * peaks-loop v3.0.0 — Slice C.1
+ *
+ * Monotonic-improvement guard for the loop runtime. Compares adjacent
+ * cycles' per-evaluator scores (rescaled gateAction → 0..1) and
+ * returns a structured envelope indicating:
+ *
+ *   - status: 'pass' | 'warn' | 'block' | 'skip'
+ *   - regressions: per-evaluator score deltas where current < previous
+ *   - reason: human-readable summary
+ *
+ * Karpathy §2 Simplicity First: pure function, no IO, no new deps.
+ *
+ * File budget: ≤ 800 lines (Karpathy §2).
+ */
+/** Score normalisation — gateAction maps to a 0..1 score:
+ *    pass  → 1.0
+ *    warn  → 0.5
+ *    block → 0.0
+ *
+ *  `degraded` (evaluator fell back to stub) collapses to 0.25 so the
+ *  guard never regresses past the boundary value; downstream callers
+ *  can surface `degraded` separately.
+ */
+function gateActionToScore(gateAction, degraded) {
+    if (degraded)
+        return 0.25;
+    if (gateAction === 'pass')
+        return 1.0;
+    if (gateAction === 'warn')
+        return 0.5;
+    return 0.0;
+}
+/** Strict-greater-than with a small epsilon to absorb FP rounding
+ *  (e.g. 1.0 - 0.95 = 0.04999999…). The boundary at exactly
+ *  threshold stays a pass. */
+const DELTA_EPSILON = 1e-9;
+/** Convert an envelope-shaped verdict row to `MonotonicScoreRow`.
+ *  Pure helper, exported for the CLI layer. */
+export function toScoreRow(evaluator, gateAction, degraded, observedAtIso = new Date(0).toISOString()) {
+    return {
+        evaluator,
+        score: gateActionToScore(gateAction, degraded),
+        gateAction,
+        degraded,
+        observedAt: observedAtIso
+    };
+}
+/** Default threshold = 5% of [0,1] scale → 0.05. */
+export const DEFAULT_MONOTONIC_THRESHOLD = 0.05;
+/** Compare `previous` against `current` and report monotonicity.
+ *
+ *  Rules (reflected in `tests/unit/loop/monotonic-guard.test.ts`):
+ *    - missing previous cycle → skip (`MONOTONIC_NO_PREVIOUS`)
+ *    - evaluators not present in both cycles → skip that evaluator
+ *    - score unchanged / up → ok
+ *    - score ↓ ≤ threshold → ok
+ *    - score ↓ > threshold → regression row + status 'block'
+ *      with `code = MONOTONICITY_VIOLATION`.
+ */
+export function checkMonotonicImprovement(previous, current, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_MONOTONIC_THRESHOLD;
+    const at = options.nowIso ?? new Date().toISOString();
+    if (previous === null) {
+        return {
+            status: 'skip',
+            ok: true,
+            reason: 'no previous cycle recorded — monotonicity check is a no-op (first run is allowed to start anywhere)',
+            threshold,
+            previousCycle: null,
+            currentCycle: current.cycle,
+            regressions: [],
+            monotonicityViolation: false,
+            code: 'MONOTONIC_NO_PREVIOUS'
+        };
+    }
+    // Build previous evaluator → score lookup.
+    const prevMap = new Map();
+    for (const row of previous.scores)
+        prevMap.set(row.evaluator, row);
+    const regressions = [];
+    let comparable = 0;
+    for (const cur of current.scores) {
+        const prev = prevMap.get(cur.evaluator);
+        if (prev === undefined)
+            continue; // incomparable evaluator → skip
+        comparable++;
+        const delta = prev.score - cur.score; // positive = regression
+        if (delta > threshold + DELTA_EPSILON) {
+            regressions.push({
+                evaluator: cur.evaluator,
+                previousScore: prev.score,
+                currentScore: cur.score,
+                delta: round4(delta)
+            });
+        }
+    }
+    regressions.sort((a, b) => b.delta - a.delta);
+    if (comparable === 0) {
+        return {
+            status: 'skip',
+            ok: true,
+            reason: 'no evaluator appears in both the previous and current cycle — nothing to compare',
+            threshold,
+            previousCycle: previous.cycle,
+            currentCycle: current.cycle,
+            regressions: [],
+            monotonicityViolation: false,
+            code: 'MONOTONIC_INCOMPARABLE_EVALUATORS'
+        };
+    }
+    if (regressions.length > 0) {
+        const summary = regressions
+            .map((r) => `${r.evaluator} ${r.previousScore.toFixed(4)}→${r.currentScore.toFixed(4)} (Δ=${r.delta.toFixed(4)})`)
+            .join(', ');
+        return {
+            status: 'block',
+            ok: false,
+            reason: `MONOTONICITY_VIOLATION: ${regressions.length} evaluator(s) regressed beyond threshold ${threshold} (at ${at}): ${summary}`,
+            threshold,
+            previousCycle: previous.cycle,
+            currentCycle: current.cycle,
+            regressions,
+            monotonicityViolation: true,
+            code: 'MONOTONIC_VIOLATION'
+        };
+    }
+    return {
+        status: 'pass',
+        ok: true,
+        reason: `all ${comparable} evaluators held or improved (threshold ${threshold})`,
+        threshold,
+        previousCycle: previous.cycle,
+        currentCycle: current.cycle,
+        regressions: [],
+        monotonicityViolation: false,
+        code: 'MONOTONIC_OK'
+    };
+}
+function classifyFsError(err) {
+    const code = err?.code;
+    if (code === 'ENOENT')
+        return 'NOT_FOUND';
+    return 'IO_ERROR';
+}
+/** Read `.peaks/_sub_agents/<sid>/shared/` cross-session signal — on
+ *  any IO error, return `null` so the guard never crashes on missing
+ *  cross-batch signal (per Slice C (b) case "跨 session 读
+ *  .peaks/_sub_agents/<sid>/shared/ 跨批 signal → 不 crash").
+ *  Pure helper; only present for the cross-session case. */
+export function loadCrossSessionSignal(projectRoot, sid) {
+    // Lazily import so unit tests in non-windows environments don't pull
+    // node:fs through a static `import` (test envs stay small).
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const sharedDir = path.join(projectRoot, '.peaks', '_sub_agents', sid, 'shared');
+    const readdir = (() => {
+        try {
+            return { ok: true, value: fs.readdirSync(sharedDir) };
+        }
+        catch (err) {
+            return { ok: false, reason: classifyFsError(err) };
+        }
+    })();
+    if (!readdir.ok)
+        return null; // missing dir or permission denied — both are no-ops.
+    const entries = readdir.value;
+    // Pick the highest cycle number from the filenames; tolerate garbage.
+    let best = null;
+    for (const entry of entries) {
+        const m = entry.match(/^cycle-(\d+)\.json$/);
+        if (m === null)
+            continue;
+        const cycle = parseInt(m[1] ?? '0', 10);
+        if (best === null || cycle > best)
+            best = cycle;
+    }
+    if (best === null)
+        return null;
+    const target = path.join(sharedDir, `cycle-${best}.json`);
+    const readFile = (() => {
+        try {
+            return { ok: true, value: fs.readFileSync(target, 'utf8') };
+        }
+        catch (err) {
+            return { ok: false, reason: classifyFsError(err) };
+        }
+    })();
+    if (!readFile.ok)
+        return null;
+    const parse = (() => {
+        try {
+            return { ok: true, value: JSON.parse(readFile.value) };
+        }
+        catch {
+            return { ok: false, reason: 'PARSE_ERROR' };
+        }
+    })();
+    if (!parse.ok)
+        return null;
+    const parsed = parse.value;
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    const cycleNo = typeof obj['cycle'] === 'number' ? obj['cycle'] : best;
+    const scoresRaw = Array.isArray(obj['scores']) ? obj['scores'] : [];
+    const scores = [];
+    for (const s of scoresRaw) {
+        if (s === null || typeof s !== 'object')
+            continue;
+        const r = s;
+        if (typeof r['evaluator'] !== 'string')
+            continue;
+        const gate = r['gateAction'];
+        if (gate !== 'pass' && gate !== 'warn' && gate !== 'block')
+            continue;
+        const observedAt = typeof r['observedAt'] === 'string' ? r['observedAt'] : new Date(0).toISOString();
+        const degraded = r['degraded'] === true;
+        scores.push({
+            evaluator: r['evaluator'],
+            score: typeof r['score'] === 'number' ? r['score'] : gateActionToScore(gate, degraded),
+            gateAction: gate,
+            degraded,
+            observedAt
+        });
+    }
+    return { cycle: cycleNo, scores };
+}
+function round4(n) {
+    return Math.round(n * 10000) / 10000;
+}

package/dist/services/loop/monotonic-runner.d.ts

@@ -0,0 +1,58 @@
+import { type MonotonicCycle, type MonotonicScoreRow, type MonotonicReport } from './monotonic-guard.js';
+/** Set of evaluator kinds the loop walker actually scores — keeps the
+ *  guard surface tight (the verdict-aggregate is the cross-source merge
+ *  and not a per-cycle input). */
+declare const WALKED_EVALUATORS: readonly ["karpathy", "code-review", "security-review", "perf-baseline"];
+type WalkedKind = (typeof WALKED_EVALUATORS)[number];
+export interface RunMonotonicOptions {
+    readonly projectRoot: string;
+    readonly sid: string;
+    readonly rid: string;
+    /** Threshold (0..1 scale). Default 0.05 (5%). */
+    readonly threshold?: number;
+    /** When set, write the current cycle score rows to disk (default: true). */
+    readonly persist?: boolean;
+    /** When set, override the auto-derived cycle index. */
+    readonly cycle?: number;
+    /** Override the peaks binary path (default: `node bin/peaks.js`). */
+    readonly peaksBin?: string;
+}
+export interface RunMonotonicResult {
+    readonly projectRoot: string;
+    readonly sid: string;
+    readonly rid: string;
+    readonly currentCycle: number;
+    readonly previousCycle: number | null;
+    readonly persistedAt: string | null;
+    readonly rows: readonly MonotonicScoreRow[];
+    readonly report: MonotonicReport;
+    /** Additive surface for non-fatal persistence warnings (e.g. mkdir
+     *  failure). Optional so existing destructures keep compiling. */
+    readonly warnings?: readonly string[];
+}
+/** Resolve the slice dir used by both writer + reader — keeps tests
+ *  insulated from real sessions. */
+export declare function sliceDir(projectRoot: string, sid: string, rid: string): string;
+/** Load the most recent prior cycle (highest-N `cycle-N.json`) for
+ *  `(sid, rid)` from the slice dir; falls back to the
+ *  `.peaks/_sub_agents/<sid>/shared/` dir when no slice-level prior
+ *  cycle exists. Returns `null` on any read error. */
+export declare function loadPreviousCycle(projectRoot: string, sid: string, rid: string): MonotonicCycle | null;
+/** Determine the next cycle index — `max(prior) + 1`, or `1` when none exist. */
+export declare function nextCycleIndex(projectRoot: string, sid: string, rid: string): number;
+/** Run the guard end-to-end: walk the 4 evaluators, persist the current
+ *  cycle score rows, compare against the prior cycle, return a
+ *  structured report. */
+export declare function runMonotonicCheck(options: RunMonotonicOptions): RunMonotonicResult;
+/** Helper for tests + CLI — resolve project root + sid consistently. */
+export declare function resolveMonotonicContext(opts: {
+    project?: string;
+    session: string;
+    rid: string;
+}): {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+};
+/** Suppress unused-import lint when only the typedefs are exported. */
+export type { WalkedKind };

package/dist/services/loop/monotonic-runner.js

@@ -0,0 +1,231 @@
+/**
+ * peaks-loop v3.0.0 — Slice C.2
+ *
+ * Runtime for the `monotonic-improvement` evaluator. Walks the prior
+ * cycle's score rows (per evaluator), invokes each evaluator against
+ * the current rid + project, then compares adjacent cycles.
+ *
+ *  - current cycle score rows are stored at
+ *      .peaks/_runtime/<sid>/loop/<rid>/cycle-<N>.json
+ *  - previous cycle rows are loaded from the same directory
+ *    (or from `.peaks/_sub_agents/<sid>/shared/cycle-<M>.json`
+ *    if the slice directory is empty).
+ *  - missing previous cycle → skip (not abort).
+ *
+ * Karpathy §2 Simplicity First: shell-out to existing
+ * `dispatchEvaluator`, persist JSON to disk; no new deps.
+ *
+ * File budget: ≤ 800 lines (Karpathy §2).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { dispatchEvaluator } from './evaluator-dispatcher.js';
+import { checkMonotonicImprovement, toScoreRow, DEFAULT_MONOTONIC_THRESHOLD } from './monotonic-guard.js';
+import { findProjectRoot } from '../config/config-safety.js';
+function classifyFsError(err) {
+    const code = err?.code;
+    if (code === 'ENOENT')
+        return 'NOT_FOUND';
+    return 'IO_ERROR';
+}
+/** Set of evaluator kinds the loop walker actually scores — keeps the
+ *  guard surface tight (the verdict-aggregate is the cross-source merge
+ *  and not a per-cycle input). */
+const WALKED_EVALUATORS = [
+    'karpathy',
+    'code-review',
+    'security-review',
+    'perf-baseline'
+];
+/** Resolve the slice dir used by both writer + reader — keeps tests
+ *  insulated from real sessions. */
+export function sliceDir(projectRoot, sid, rid) {
+    return join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid);
+}
+/** Load the most recent prior cycle (highest-N `cycle-N.json`) for
+ *  `(sid, rid)` from the slice dir; falls back to the
+ *  `.peaks/_sub_agents/<sid>/shared/` dir when no slice-level prior
+ *  cycle exists. Returns `null` on any read error. */
+export function loadPreviousCycle(projectRoot, sid, rid) {
+    return loadMostRecentCycle(sliceDir(projectRoot, sid, rid))
+        ?? loadMostRecentCycleFromSubAgents(projectRoot, sid);
+}
+function loadMostRecentCycleFromSubAgents(projectRoot, sid) {
+    const dir = join(projectRoot, '.peaks', '_sub_agents', sid, 'shared');
+    return loadMostRecentCycle(dir);
+}
+function loadMostRecentCycle(dir) {
+    if (!existsSync(dir))
+        return null;
+    const readdir = (() => {
+        try {
+            return { ok: true, value: require('node:fs').readdirSync(dir) };
+        }
+        catch (err) {
+            return { ok: false, reason: classifyFsError(err) };
+        }
+    })();
+    if (!readdir.ok)
+        return null;
+    const entries = readdir.value;
+    let bestCycle = null;
+    for (const entry of entries) {
+        const m = entry.match(/^cycle-(\d+)\.json$/);
+        if (m === null)
+            continue;
+        const n = parseInt(m[1] ?? '0', 10);
+        if (bestCycle === null || n > bestCycle)
+            bestCycle = n;
+    }
+    if (bestCycle === null)
+        return null;
+    const target = join(dir, `cycle-${bestCycle}.json`);
+    const readFile = (() => {
+        try {
+            return { ok: true, value: readFileSync(target, 'utf8') };
+        }
+        catch (err) {
+            return { ok: false, reason: classifyFsError(err) };
+        }
+    })();
+    if (!readFile.ok)
+        return null;
+    return parseCycle(readFile.value, bestCycle);
+}
+function parseCycle(raw, fallbackCycle) {
+    const parse = (() => {
+        try {
+            return { ok: true, value: JSON.parse(raw) };
+        }
+        catch {
+            return { ok: false, reason: 'PARSE_ERROR' };
+        }
+    })();
+    if (!parse.ok)
+        return null;
+    const parsed = parse.value;
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    const scores = Array.isArray(obj['scores']) ? obj['scores'] : [];
+    const rows = [];
+    for (const s of scores) {
+        if (s === null || typeof s !== 'object')
+            continue;
+        const r = s;
+        if (typeof r['evaluator'] !== 'string')
+            continue;
+        const gate = r['gateAction'];
+        if (gate !== 'pass' && gate !== 'warn' && gate !== 'block')
+            continue;
+        const observedAt = typeof r['observedAt'] === 'string' ? r['observedAt'] : new Date(0).toISOString();
+        rows.push({
+            evaluator: r['evaluator'],
+            score: typeof r['score'] === 'number' ? r['score'] : (gate === 'pass' ? 1.0 : gate === 'warn' ? 0.5 : 0.0),
+            gateAction: gate,
+            degraded: r['degraded'] === true,
+            observedAt
+        });
+    }
+    return { cycle: typeof obj['cycle'] === 'number' ? obj['cycle'] : fallbackCycle, scores: rows };
+}
+/** Determine the next cycle index — `max(prior) + 1`, or `1` when none exist. */
+export function nextCycleIndex(projectRoot, sid, rid) {
+    const prev = loadPreviousCycle(projectRoot, sid, rid);
+    if (prev === null)
+        return 1;
+    return prev.cycle + 1;
+}
+/** Run the guard end-to-end: walk the 4 evaluators, persist the current
+ *  cycle score rows, compare against the prior cycle, return a
+ *  structured report. */
+export function runMonotonicCheck(options) {
+    const threshold = options.threshold ?? DEFAULT_MONOTONIC_THRESHOLD;
+    const persist = options.persist !== false;
+    const cycle = options.cycle ?? nextCycleIndex(options.projectRoot, options.sid, options.rid);
+    const rows = [];
+    for (const kind of WALKED_EVALUATORS) {
+        let env;
+        try {
+            env = dispatchEvaluator(kind, {
+                projectRoot: options.projectRoot,
+                rid: options.rid,
+                ...(options.peaksBin !== undefined ? { peaksBin: options.peaksBin } : {})
+            });
+        }
+        catch {
+            // Per-evaluator failures never abort the loop — degrade to warn,
+            // score 0.25, degraded=true, observed-at=now.
+            const now = new Date().toISOString();
+            rows.push({
+                evaluator: kind,
+                score: 0.25,
+                gateAction: 'warn',
+                degraded: true,
+                observedAt: now
+            });
+            continue;
+        }
+        rows.push(toScoreRow(env.kind, env.gateAction, env.degraded, new Date().toISOString()));
+    }
+    const currentCycle = { cycle, scores: rows };
+    const previousCycle = loadPreviousCycle(options.projectRoot, options.sid, options.rid);
+    const report = checkMonotonicImprovement(previousCycle, currentCycle, { threshold });
+    let persistedAt = null;
+    const envelopeWarns = [];
+    if (persist) {
+        const dir = sliceDir(options.projectRoot, options.sid, options.rid);
+        const mkdir = (() => {
+            try {
+                mkdirSync(dir, { recursive: true });
+                return { ok: true, value: undefined };
+            }
+            catch (err) {
+                return { ok: false, reason: classifyFsError(err) };
+            }
+        })();
+        if (!mkdir.ok) {
+            envelopeWarns.push(`mkdir-failed: ${dir} (${mkdir.reason})`);
+        }
+        const path = join(dir, `cycle-${cycle}.json`);
+        const payload = JSON.stringify({
+            cycle,
+            rid: options.rid,
+            sid: options.sid,
+            persistedAt: new Date().toISOString(),
+            scores: rows
+        });
+        const writeFile = (() => {
+            try {
+                writeFileSync(path, payload, 'utf8');
+                return { ok: true, value: undefined };
+            }
+            catch (err) {
+                return { ok: false, reason: classifyFsError(err) };
+            }
+        })();
+        if (writeFile.ok) {
+            persistedAt = path;
+        }
+        else {
+            persistedAt = null;
+            envelopeWarns.push(`write-failed: ${path} (${writeFile.reason})`);
+        }
+    }
+    return {
+        projectRoot: options.projectRoot,
+        sid: options.sid,
+        rid: options.rid,
+        currentCycle: cycle,
+        previousCycle: previousCycle === null ? null : previousCycle.cycle,
+        persistedAt,
+        rows,
+        report,
+        ...(envelopeWarns.length > 0 ? { warnings: envelopeWarns } : {})
+    };
+}
+/** Helper for tests + CLI — resolve project root + sid consistently. */
+export function resolveMonotonicContext(opts) {
+    const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    return { projectRoot, sid: opts.session, rid: opts.rid };
+}

package/dist/services/loop/run-driver.d.ts

@@ -0,0 +1,70 @@
+import { type SpecTerminationStrategy } from './spec-service.js';
+import { type EvaluatorVerdictEnvelope } from './evaluator-dispatcher.js';
+import { type MonotonicScoreRow, type MonotonicReport } from './monotonic-guard.js';
+export type RunDriverCode = 'RUN_OK' | 'RUN_OK_REGRESSION' | 'SPEC_NOT_FOUND' | 'SPEC_INVALID' | 'UNKNOWN_TERMINATION_STRATEGY' | 'MONOTONICITY_VIOLATION' | 'EVALUATOR_THREW' | 'LOCKED' | 'EVALUATOR_UNKNOWN' | 'RUN_FAILED';
+export interface RunDriverOptions {
+    readonly projectRoot: string;
+    readonly sid: string;
+    readonly rid: string;
+    /** Monotonic threshold (0..1). Default 0.05. */
+    readonly threshold?: number;
+    /** Override the strategy (otherwise read from spec.yaml). */
+    readonly strategyOverride?: SpecTerminationStrategy;
+    /** Override max-cycles (otherwise read from spec.yaml). */
+    readonly maxCyclesOverride?: number;
+    /** When true, persist cycle rows + a summary.json to disk. Default true. */
+    readonly persist?: boolean;
+    /** Test seam: when set, used as the dispatch path instead of `node bin/peaks.js`. */
+    readonly peaksBin?: string;
+    /** Test seam: when set, replaces the per-evaluator dispatcher (no shell-out). */
+    readonly dispatchOverride?: (kind: string, ctx: {
+        projectRoot: string;
+        rid: string;
+        sid: string;
+    }) => EvaluatorVerdictEnvelope;
+}
+export interface CycleRecord {
+    readonly cycle: number;
+    readonly rows: readonly MonotonicScoreRow[];
+    readonly persistedAt: string | null;
+    readonly monotonicReport: MonotonicReport;
+}
+export interface RunDriverResult {
+    readonly code: RunDriverCode;
+    readonly ok: boolean;
+    readonly message: string;
+    readonly strategy: SpecTerminationStrategy | 'unknown';
+    readonly maxCycles: number;
+    readonly cycles: readonly CycleRecord[];
+    readonly finalReport: MonotonicReport | null;
+    readonly summary: {
+        readonly reachedMaxCycles: boolean;
+        readonly regressionCount: number;
+        readonly totalCycles: number;
+    };
+}
+/** Test seam: clear in-process locks between test cases. */
+export declare function _clearRunLocks(): void;
+/** Compose the cycle dir used for the writer (kept distinct from the
+ *  slice dir so we can co-locate the per-cycle summary without
+ *  overloading the monotonic-runner writer's `cycle-N.json`). */
+export declare function cyclesDir(projectRoot: string, sid: string, rid: string): string;
+/** Top-level entry point — `peaks loop run <rid>`.
+ *
+ *  Returns a `RunDriverResult` (the CLI layer maps `code → exit
+ *  code` + printResult envelope). The function is intentionally
+ *  non-throwing; per-cycle errors are captured as
+ *  `code = EVALUATOR_THREW` but the loop continues to the next cycle
+ *  so the caller sees a complete picture. */
+export declare function runLoop(options: RunDriverOptions): RunDriverResult;
+/** CLI helper: resolve the project root, sid, and rid from a
+ *  `(project, session, rid)` triple. */
+export declare function resolveRunContext(opts: {
+    project?: string;
+    session: string;
+    rid: string;
+}): {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+};