martin-loop 0.1.4 → 1.3.0

package/dist/vendor/core/otel/tracer.js

@@ -0,0 +1,116 @@
+// SLICE-18 — OpenTelemetry traces (noop implementation)
+// Provides a stable tracer interface with an in-memory noop fallback.
+// Actual OTLP export is a future enhancement — the interface is stable now.
+// No @opentelemetry packages are required; this is a pure noop implementation.
+// All valid span names for runtime validation
+export const VALID_SPAN_NAMES = [
+    "martin.run",
+    "martin.attempt",
+    "martin.adapter_call",
+    "martin.patch_proof",
+    "martin.leash_check",
+    "martin.grounding_scan",
+    "martin.rollback",
+    "martin.gateway_policy",
+    "martin.router_decision"
+];
+// ─── In-memory span store (for testing and noop mode) ────────────────────────
+let collectedSpans = [];
+/**
+ * Returns all spans collected in the current process.
+ * Useful for test assertions.
+ */
+export function getCollectedSpans() {
+    return [...collectedSpans];
+}
+/**
+ * Resets the in-memory span array.
+ * Call this in test beforeEach/afterEach to isolate tests.
+ */
+export function clearCollectedSpans() {
+    collectedSpans = [];
+}
+// ─── ID generation helpers ───────────────────────────────────────────────────
+function randomHex(bytes) {
+    // Use crypto.getRandomValues in Node.js / browser environments
+    // Fall back to Math.random if unavailable (test environments)
+    try {
+        // Node.js crypto module
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { randomBytes } = require("node:crypto");
+        return randomBytes(bytes).toString("hex");
+    }
+    catch {
+        // Fallback: Math.random-based hex (not cryptographically secure, but fine for noop)
+        let result = "";
+        const chars = "0123456789abcdef";
+        for (let i = 0; i < bytes * 2; i++) {
+            result += chars[Math.floor(Math.random() * 16)];
+        }
+        return result;
+    }
+}
+// ─── Noop tracer implementation ───────────────────────────────────────────────
+function createNoopTracer() {
+    return {
+        startSpan(name, attributes = {}) {
+            const span = {
+                spanId: randomHex(8),
+                traceId: randomHex(16),
+                startTime: new Date().toISOString(),
+                name,
+                status: "UNSET",
+                attributes: { ...attributes }
+            };
+            collectedSpans.push(span);
+            return span;
+        },
+        endSpan(span, status = "OK") {
+            // Mutate the collected span reference
+            span.endTime = new Date().toISOString();
+            span.status = status;
+            return span;
+        },
+        recordException(span, error) {
+            span.attributes["exception.type"] = error.name;
+            span.attributes["exception.message"] = error.message;
+            if (error.stack) {
+                span.attributes["exception.stacktrace"] = error.stack.slice(0, 500);
+            }
+            span.status = "ERROR";
+            return span;
+        }
+    };
+}
+/**
+ * Creates a tracer instance. When endpoint is undefined or empty, uses the
+ * noop implementation (stores spans in memory, no network calls).
+ * When endpoint is set, the same noop is used — actual OTLP export is a
+ * future enhancement.
+ */
+export function createTracer(options = {}) {
+    // In both cases (endpoint set or not), we use the noop implementation.
+    // The interface is stable; OTLP export will be added when OTel peer deps
+    // are installed.
+    void options.endpoint; // acknowledged, not yet used
+    return createNoopTracer();
+}
+// ─── Default module-level singleton ──────────────────────────────────────────
+let _defaultTracer = null;
+/**
+ * Returns the default module-level tracer singleton.
+ * Initializes with a noop tracer if not already set.
+ */
+export function getTracer() {
+    if (!_defaultTracer) {
+        _defaultTracer = createTracer();
+    }
+    return _defaultTracer;
+}
+/**
+ * Resets the default tracer singleton (for testing).
+ */
+export function resetDefaultTracer() {
+    _defaultTracer = null;
+}
+//# sourceMappingURL=tracer.js.map

package/dist/vendor/core/parallel/parallel-attempts.d.ts

@@ -0,0 +1,28 @@
+import { type AttemptScore, type ScorerWeights } from "./scorer.js";
+export interface ParallelAttemptInput {
+    attemptId: string;
+    grade: "A" | "B" | "C";
+    groundingScore: number;
+    costUsd: number;
+    diff: string;
+}
+export interface ParallelConsensusArtifact {
+    runId: string;
+    parallelN: number;
+    attempts: AttemptScore[];
+    winner: AttemptScore | null;
+    allFailed: boolean;
+    totalCostUsd: number;
+    producedAt: string;
+    featureFlag: "parallel.enabled";
+}
+export interface ParallelResult {
+    winner: ParallelAttemptInput | null;
+    allFailed: boolean;
+    totalCostUsd: number;
+    artifact: ParallelConsensusArtifact;
+}
+export declare function runParallelConsensus(attempts: ParallelAttemptInput[], options: {
+    runId: string;
+    weights?: ScorerWeights;
+}): ParallelResult;

package/dist/vendor/core/parallel/parallel-attempts.js

@@ -0,0 +1,41 @@
+// ─── Parallel Consensus ───────────────────────────────────────────────────────
+//
+// Scores N pre-computed attempt results, selects a winner, builds the
+// consensus artifact, and returns a ParallelResult.
+//
+// Feature flag: "parallel.enabled" — this module is behind a flag.
+// The actual adapter concurrency (Promise.allSettled) lives in index.ts.
+// This function is synchronous and pure: score, select, artifact — no I/O.
+import { scoreAttempt, selectWinner } from "./scorer.js";
+// ─── Implementation ───────────────────────────────────────────────────────────
+export function runParallelConsensus(attempts, options) {
+    const scores = attempts.map((a) => scoreAttempt({
+        attemptId: a.attemptId,
+        grade: a.grade,
+        groundingScore: a.groundingScore,
+        costUsd: a.costUsd
+    }, options.weights));
+    const winnerScore = selectWinner(scores);
+    const allFailed = winnerScore === null;
+    const totalCostUsd = attempts.reduce((sum, a) => sum + a.costUsd, 0);
+    const winnerInput = winnerScore
+        ? (attempts.find((a) => a.attemptId === winnerScore.attemptId) ?? null)
+        : null;
+    const artifact = {
+        runId: options.runId,
+        parallelN: attempts.length,
+        attempts: scores,
+        winner: winnerScore,
+        allFailed,
+        totalCostUsd,
+        producedAt: new Date().toISOString(),
+        featureFlag: "parallel.enabled"
+    };
+    return {
+        winner: winnerInput,
+        allFailed,
+        totalCostUsd,
+        artifact
+    };
+}
+//# sourceMappingURL=parallel-attempts.js.map

package/dist/vendor/core/parallel/scorer.d.ts

@@ -0,0 +1,24 @@
+export interface AttemptScore {
+    attemptId: string;
+    grade: "A" | "B" | "C";
+    groundingScore: number;
+    costUsd: number;
+    compositeScore: number;
+}
+export interface ScorerWeights {
+    grounding: number;
+    verifier: number;
+    cost: number;
+}
+export declare function scoreAttempt(attempt: {
+    attemptId: string;
+    grade: "A" | "B" | "C";
+    groundingScore: number;
+    costUsd: number;
+}, weights?: ScorerWeights): AttemptScore;
+/**
+ * Selects the winning attempt from a scored list.
+ * Returns null if all attempts have grade C (all failed).
+ * Tiebreak order: highest compositeScore → lowest costUsd → alphabetical attemptId.
+ */
+export declare function selectWinner(scores: AttemptScore[]): AttemptScore | null;

package/dist/vendor/core/parallel/scorer.js

@@ -0,0 +1,65 @@
+// ─── Attempt Scorer ───────────────────────────────────────────────────────────
+//
+// Computes a composite score for a parallel attempt using:
+//   compositeScore = (groundingScore * grounding)
+//                  + (verifierConfidenceProxy * verifier)
+//                  + (1 / (costUsd + 0.01) * cost)
+//
+// verifierConfidenceProxy:
+//   grade A or B → 1.0
+//   grade C       → 0.0
+//
+// selectWinner returns null when ALL grades are C (all failed).
+// Tiebreak: lowest costUsd first; if still tied, alphabetical attemptId.
+const DEFAULT_WEIGHTS = {
+    grounding: 0.4,
+    verifier: 0.4,
+    cost: 0.2
+};
+function verifierProxy(grade) {
+    return grade === "A" || grade === "B" ? 1.0 : 0.0;
+}
+export function scoreAttempt(attempt, weights = DEFAULT_WEIGHTS) {
+    const w = { ...DEFAULT_WEIGHTS, ...weights };
+    const vp = verifierProxy(attempt.grade);
+    const compositeScore = attempt.groundingScore * w.grounding +
+        vp * w.verifier +
+        (1 / (attempt.costUsd + 0.01)) * w.cost;
+    return {
+        attemptId: attempt.attemptId,
+        grade: attempt.grade,
+        groundingScore: attempt.groundingScore,
+        costUsd: attempt.costUsd,
+        compositeScore
+    };
+}
+/**
+ * Selects the winning attempt from a scored list.
+ * Returns null if all attempts have grade C (all failed).
+ * Tiebreak order: highest compositeScore → lowest costUsd → alphabetical attemptId.
+ */
+export function selectWinner(scores) {
+    if (scores.length === 0)
+        return null;
+    // All-failed check: all grades are C
+    const allFailed = scores.every((s) => s.grade === "C");
+    if (allFailed)
+        return null;
+    // Filter out grade C — they can't win
+    const eligible = scores.filter((s) => s.grade !== "C");
+    if (eligible.length === 0)
+        return null;
+    return eligible.slice().sort((a, b) => {
+        // Primary: highest composite score (descending)
+        if (b.compositeScore !== a.compositeScore) {
+            return b.compositeScore - a.compositeScore;
+        }
+        // Secondary: lowest cost (ascending)
+        if (a.costUsd !== b.costUsd) {
+            return a.costUsd - b.costUsd;
+        }
+        // Tertiary: alphabetical attemptId (ascending)
+        return a.attemptId.localeCompare(b.attemptId);
+    })[0] ?? null;
+}
+//# sourceMappingURL=scorer.js.map

package/dist/vendor/core/pattern-detection.d.ts

@@ -0,0 +1,64 @@
+import type { FailureClass, LoopAttempt } from "../contracts/index.js";
+export type LoopPatternId = "no_op_success" | "repo_worktree_mismatch" | "broken_tool_loop" | "stale_state_drift";
+export interface LoopPatternDetection {
+    attemptId: string;
+    patternId: LoopPatternId;
+    severity: "warn";
+    message: string;
+    evidence: Record<string, unknown>;
+}
+interface PatternDetectionExecution {
+    changedFiles?: string[];
+    diffStats?: {
+        filesChanged: number;
+        addedLines: number;
+        deletedLines: number;
+    };
+    baseline?: {
+        startHeadSha: string;
+        startTrackedStatus: string;
+        startUntrackedSet: string[];
+        startTimestamp: string;
+        worktreeClean: boolean;
+        pilotRepoClass: string | null;
+    };
+    gitNormalization?: {
+        startHeadSha: string;
+        endHeadShaBeforeNormalization: string;
+        normalizationApplied: boolean;
+        normalizationMode: "reset_mixed_to_start_head" | "none";
+        normalizationSucceeded: boolean;
+        headAfterNormalization: string;
+    };
+    scopeSurface?: {
+        trackedChangedPaths: string[];
+        deletedPaths: string[];
+        newUntrackedPaths: string[];
+        allChangedPaths: string[];
+        baselineWasClean: boolean;
+        noCodeChange: boolean;
+        diffStats?: {
+            filesChanged: number;
+            addedLines: number;
+            deletedLines: number;
+        };
+    };
+}
+interface PatternDetectionResult {
+    status: "completed" | "failed";
+    summary: string;
+    verification: {
+        passed: boolean;
+        summary: string;
+    };
+    execution?: PatternDetectionExecution;
+}
+export interface DetectStreamingAnomaliesInput {
+    attemptId: string;
+    result: PatternDetectionResult;
+    previousAttempts: LoopAttempt[];
+    resolvedChangedFiles: string[];
+    failureClass?: FailureClass;
+}
+export declare function detectStreamingAnomalies(input: DetectStreamingAnomaliesInput): LoopPatternDetection[];
+export {};

package/dist/vendor/core/pattern-detection.js

@@ -0,0 +1,108 @@
+const CHANGE_CLAIM_RE = /\b(fix(?:ed)?|update(?:d)?|implement(?:ed)?|change(?:d)?|patch(?:ed)?|add(?:ed)?|remove(?:d)?|repair(?:ed)?|refactor(?:ed)?)\b/i;
+export function detectStreamingAnomalies(input) {
+    const patterns = [];
+    const groundedChangedFiles = uniqueNormalizedPaths(input.resolvedChangedFiles);
+    const reportedChangedFiles = uniqueNormalizedPaths(input.result.execution?.changedFiles);
+    const scopeSurfaceFiles = uniqueNormalizedPaths(input.result.execution?.scopeSurface?.allChangedPaths);
+    const effectiveChangedFiles = groundedChangedFiles.length > 0 ? groundedChangedFiles : scopeSurfaceFiles;
+    const summaryClaimsChange = CHANGE_CLAIM_RE.test(input.result.summary);
+    const diffStats = input.result.execution?.diffStats ?? input.result.execution?.scopeSurface?.diffStats;
+    const baselineDirty = input.result.execution?.baseline?.worktreeClean === false ||
+        input.result.execution?.scopeSurface?.baselineWasClean === false;
+    const normalizationApplied = input.result.execution?.gitNormalization?.normalizationApplied === true ||
+        (input.result.execution?.gitNormalization?.startHeadSha !== undefined &&
+            input.result.execution?.gitNormalization?.endHeadShaBeforeNormalization !== undefined &&
+            input.result.execution.gitNormalization.startHeadSha !==
+                input.result.execution.gitNormalization.endHeadShaBeforeNormalization);
+    if (input.result.status === "completed" &&
+        input.result.verification.passed &&
+        summaryClaimsChange &&
+        effectiveChangedFiles.length === 0 &&
+        (input.result.execution?.scopeSurface?.noCodeChange ?? true) &&
+        !hasSubstantiveDiffStats(diffStats)) {
+        patterns.push({
+            attemptId: input.attemptId,
+            patternId: "no_op_success",
+            severity: "warn",
+            message: "Verification passed, but the run summary claimed a fix without repo-backed change evidence.",
+            evidence: {
+                summary: input.result.summary,
+                verificationSummary: input.result.verification.summary,
+                resolvedChangedFiles: groundedChangedFiles,
+                reportedChangedFiles
+            }
+        });
+    }
+    if (reportedChangedFiles.length > 0 &&
+        effectiveChangedFiles.length > 0 &&
+        !samePathSet(reportedChangedFiles, effectiveChangedFiles)) {
+        patterns.push({
+            attemptId: input.attemptId,
+            patternId: "repo_worktree_mismatch",
+            severity: "warn",
+            message: "The adapter-reported changed files diverged from the grounded repo/worktree state.",
+            evidence: {
+                reportedChangedFiles,
+                resolvedChangedFiles: effectiveChangedFiles
+            }
+        });
+    }
+    const currentVerifierSignature = normalizeText(input.result.verification.summary || input.result.summary);
+    const repeatedFailureSignature = input.failureClass !== undefined &&
+        currentVerifierSignature.length > 0 &&
+        input.previousAttempts.slice(-2).length === 2 &&
+        input.previousAttempts.slice(-2).every((attempt) => {
+            const priorSignature = normalizeText(attempt.verifierSummary ?? attempt.summary);
+            return attempt.failureClass === input.failureClass && priorSignature === currentVerifierSignature;
+        });
+    if (repeatedFailureSignature) {
+        patterns.push({
+            attemptId: input.attemptId,
+            patternId: "broken_tool_loop",
+            severity: "warn",
+            message: "The loop is repeating the same failed verifier signature without a new recovery signal.",
+            evidence: {
+                failureClass: input.failureClass,
+                verifierSummary: input.result.verification.summary,
+                repeatedAttempts: input.previousAttempts.slice(-2).map((attempt) => attempt.attemptId)
+            }
+        });
+    }
+    if (input.result.status === "completed" &&
+        input.result.verification.passed &&
+        (baselineDirty || normalizationApplied)) {
+        patterns.push({
+            attemptId: input.attemptId,
+            patternId: "stale_state_drift",
+            severity: "warn",
+            message: "The attempt passed verification on a dirty or normalized baseline, so state drift may be masking the true change source.",
+            evidence: {
+                baselineWasClean: input.result.execution?.scopeSurface?.baselineWasClean,
+                worktreeClean: input.result.execution?.baseline?.worktreeClean,
+                normalizationApplied: input.result.execution?.gitNormalization?.normalizationApplied ?? false,
+                startHeadSha: input.result.execution?.gitNormalization?.startHeadSha,
+                endHeadShaBeforeNormalization: input.result.execution?.gitNormalization?.endHeadShaBeforeNormalization
+            }
+        });
+    }
+    return patterns;
+}
+function normalizeText(value) {
+    return (value ?? "").toLowerCase().replace(/\s+/g, " ").trim();
+}
+function normalizePath(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function uniqueNormalizedPaths(paths) {
+    return [...new Set((paths ?? []).map(normalizePath).filter((path) => path.length > 0))].sort();
+}
+function samePathSet(left, right) {
+    return left.length === right.length && left.every((path, index) => path === right[index]);
+}
+function hasSubstantiveDiffStats(diffStats) {
+    if (!diffStats) {
+        return false;
+    }
+    return diffStats.filesChanged > 0 || diffStats.addedLines > 0 || diffStats.deletedLines > 0;
+}
+//# sourceMappingURL=pattern-detection.js.map

package/dist/vendor/core/persistence/checkpoint.d.ts

@@ -0,0 +1,44 @@
+export type CheckpointPhase = "run_start" | "attempt_start" | "attempt_complete" | "run_complete";
+export interface Checkpoint {
+    loopId: string;
+    phase: CheckpointPhase;
+    attemptNumber: number;
+    lastCompletedAttempt: number;
+    costSoFar: number;
+    fileHashSnapshot: Record<string, string>;
+    lastAttemptRolledBack: boolean;
+    writtenAt: string;
+}
+export declare class WorkspaceModifiedError extends Error {
+    readonly modifiedFiles: string[];
+    constructor(modifiedFiles: string[]);
+}
+export declare function getCheckpointStorageDir(): string;
+/**
+ * Writes checkpoint.json using writeFileSync (synchronous — survives crash).
+ * Path: <storageDir>/<loopId>/checkpoint.json
+ */
+export declare function writeCheckpoint(checkpoint: Checkpoint, storageDir: string): void;
+/**
+ * Returns null if the checkpoint file does not exist.
+ */
+export declare function readCheckpoint(loopId: string, storageDir: string): Checkpoint | null;
+/**
+ * Returns SHA-256 of file contents for each path that exists.
+ * Files that do not exist are omitted from the result.
+ */
+export declare function hashFiles(filePaths: string[]): Record<string, string>;
+/**
+ * Compares current file hashes to the checkpoint snapshot.
+ * If force=true: always returns valid:true (but still lists modified files).
+ */
+export declare function validateWorkspaceHashes(checkpoint: Checkpoint, force?: boolean): {
+    valid: boolean;
+    modifiedFiles: string[];
+};
+/**
+ * Deletes checkpoint files older than maxAgeMs (default 30 days).
+ * Returns count of deleted checkpoint directories.
+ */
+export declare function cleanupOldCheckpoints(storageDir: string, maxAgeMs?: number): number;
+export declare function assertSafeLoopId(loopId: string): void;

package/dist/vendor/core/persistence/checkpoint.js

@@ -0,0 +1,156 @@
+/// <reference types="node" />
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const SAFE_LOOP_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+// ─── WorkspaceModifiedError ───────────────────────────────────────────────────
+export class WorkspaceModifiedError extends Error {
+    modifiedFiles;
+    constructor(modifiedFiles) {
+        super(`Workspace modified since checkpoint. Modified: ${modifiedFiles.join(", ")}. Use --force to resume anyway.`);
+        this.modifiedFiles = modifiedFiles;
+        this.name = "WorkspaceModifiedError";
+    }
+}
+// ─── Storage path resolution ──────────────────────────────────────────────────
+export function getCheckpointStorageDir() {
+    const env = process.env["MARTIN_STORAGE"];
+    return typeof env === "string" && env.trim().length > 0
+        ? env.trim()
+        : join(homedir(), ".martin", "loops");
+}
+// ─── Write ────────────────────────────────────────────────────────────────────
+/**
+ * Writes checkpoint.json using writeFileSync (synchronous — survives crash).
+ * Path: <storageDir>/<loopId>/checkpoint.json
+ */
+export function writeCheckpoint(checkpoint, storageDir) {
+    assertSafeLoopId(checkpoint.loopId);
+    const dir = join(storageDir, checkpoint.loopId);
+    mkdirSync(dir, { recursive: true });
+    const filePath = join(dir, "checkpoint.json");
+    writeFileSync(filePath, `${JSON.stringify(checkpoint, null, 2)}\n`, "utf8");
+}
+// ─── Read ─────────────────────────────────────────────────────────────────────
+/**
+ * Returns null if the checkpoint file does not exist.
+ */
+export function readCheckpoint(loopId, storageDir) {
+    assertSafeLoopId(loopId);
+    const filePath = join(storageDir, loopId, "checkpoint.json");
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// ─── File hashing ─────────────────────────────────────────────────────────────
+/**
+ * Returns SHA-256 of file contents for each path that exists.
+ * Files that do not exist are omitted from the result.
+ */
+export function hashFiles(filePaths) {
+    const result = {};
+    for (const filePath of filePaths) {
+        if (!existsSync(filePath)) {
+            continue;
+        }
+        try {
+            const contents = readFileSync(filePath);
+            result[filePath] = createHash("sha256").update(contents).digest("hex");
+        }
+        catch {
+            // Skip files that cannot be read (permission error, etc.)
+        }
+    }
+    return result;
+}
+// ─── Workspace validation ─────────────────────────────────────────────────────
+/**
+ * Compares current file hashes to the checkpoint snapshot.
+ * If force=true: always returns valid:true (but still lists modified files).
+ */
+export function validateWorkspaceHashes(checkpoint, force) {
+    const snapshot = checkpoint.fileHashSnapshot;
+    const modifiedFiles = [];
+    for (const [filePath, savedHash] of Object.entries(snapshot)) {
+        if (!existsSync(filePath)) {
+            modifiedFiles.push(filePath);
+            continue;
+        }
+        try {
+            const currentContents = readFileSync(filePath);
+            const currentHash = createHash("sha256").update(currentContents).digest("hex");
+            if (currentHash !== savedHash) {
+                modifiedFiles.push(filePath);
+            }
+        }
+        catch {
+            modifiedFiles.push(filePath);
+        }
+    }
+    if (force === true) {
+        return { valid: true, modifiedFiles };
+    }
+    return {
+        valid: modifiedFiles.length === 0,
+        modifiedFiles
+    };
+}
+// ─── Cleanup ──────────────────────────────────────────────────────────────────
+const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+/**
+ * Deletes checkpoint files older than maxAgeMs (default 30 days).
+ * Returns count of deleted checkpoint directories.
+ */
+export function cleanupOldCheckpoints(storageDir, maxAgeMs) {
+    const cutoffMs = maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const now = Date.now();
+    let deletedCount = 0;
+    if (!existsSync(storageDir)) {
+        return 0;
+    }
+    let entries;
+    try {
+        entries = readdirSync(storageDir);
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const checkpointPath = join(storageDir, entry, "checkpoint.json");
+        if (!existsSync(checkpointPath)) {
+            continue;
+        }
+        try {
+            const stat = statSync(checkpointPath);
+            if (now - stat.mtimeMs > cutoffMs) {
+                // Read checkpoint to get writtenAt for more accurate age check
+                const raw = readFileSync(checkpointPath, "utf8");
+                const cp = JSON.parse(raw);
+                const writtenAt = new Date(cp.writtenAt).getTime();
+                if (!Number.isNaN(writtenAt) && now - writtenAt > cutoffMs) {
+                    // Remove the checkpoint file (not the whole dir — may have other artifacts)
+                    rmSync(checkpointPath);
+                    deletedCount += 1;
+                }
+            }
+        }
+        catch {
+            // Skip on any error
+        }
+    }
+    return deletedCount;
+}
+export function assertSafeLoopId(loopId) {
+    if (!SAFE_LOOP_ID_PATTERN.test(loopId)) {
+        throw new Error(`unsafe loop id: ${loopId}`);
+    }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/vendor/core/persistence/cleanup.d.ts

@@ -0,0 +1,22 @@
+import type { RunContract } from "./store.js";
+export interface CleanupResult {
+    readonly cleaned: number;
+    readonly errors: string[];
+}
+/**
+ * Scan runsRoot for abandoned non-terminal runs and mark them session_timeout.
+ *
+ * A run is stale when:
+ *   - Its state.json lifecycleState is not in TERMINAL_STATES, AND
+ *   - Its state.json updatedAt timestamp is older than ttlMs
+ *
+ * The TTL defaults to MARTIN_SESSION_TTL_MS env var, then 4 hours.
+ */
+export declare function cleanStaleRuns(runsRoot: string, ttlMs?: number): Promise<CleanupResult>;
+/**
+ * Return RunContracts for all runs currently in a non-terminal lifecycleState.
+ * Reads both state.json (for lifecycleState) and contract.json (for RunContract).
+ * Entries missing either file are silently skipped.
+ */
+export declare function resolveActiveRuns(runsRoot: string): Promise<RunContract[]>;
+export declare function ensureRunsRoot(runsRoot: string): Promise<void>;