@martinloop/mcp 0.1.1 → 0.1.3

package/dist/vendor/core/index.js

@@ -5,12 +5,15 @@ import { evaluateChangeApprovalLeash, evaluateFilesystemLeash, evaluateSecretLea
 import { buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations } from "./grounding.js";
 import { captureRollbackBoundary, restoreRollbackBoundary } from "./rollback.js";
 import { compilePromptPacket } from "./compiler.js";
-import { makeLedgerEvent } from "./persistence/index.js";
+import { makeLedgerEvent, resolveRunsRoot, runDir } from "./persistence/index.js";
+import { runContextIntegrityPrecheck } from "./context-integrity.js";
 export { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, evaluateVerificationLeash, evaluateFilesystemLeash, evaluateChangeApprovalLeash, evaluateSecretLeash, resolveExecutionProfile, redactSecretsFromText, buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations, captureRollbackBoundary, restoreRollbackBoundary };
+// ─── Context Integrity Pre-gate ──────────────────────────────────────────────
+export { runContextIntegrityPrecheck } from "./context-integrity.js";
 // ─── Prompt packet compiler ──────────────────────────────────────────────────
 export { compilePromptPacket } from "./compiler.js";
 // ─── Persistence (RunStore, LedgerEvent, FileRunStore) ──────────────────────
-export { createFileRunStore, makeLedgerEvent, resolveRunsRoot } from "./persistence/index.js";
+export { createFileRunStore, makeLedgerEvent, readAllLoopRecords, readLatestLoopRecord, readLatestLoopRecordFromFile, readLoopRecordsFromFile, resolveRunsRoot } from "./persistence/index.js";
 export { compileAndPersistContext } from "./persistence/index.js";
 /**
  * Admission gate — must pass before any attempt is executed.
@@ -126,6 +129,7 @@ export async function runMartin(input) {
             runId: loop.loopId,
             payload: { workspaceId: input.workspaceId, projectId: input.projectId }
         }));
+        await persistLoopRecordIfSupported(input.store, loop);
     }
     const DEFAULT_FALLBACK_MODELS = [
         "claude-haiku-4-5",
@@ -136,6 +140,7 @@ export async function runMartin(input) {
     let currentAdapterIndex = 0;
     let currentAdapter = adapterChain[currentAdapterIndex] ?? input.adapter;
     let useCompressedContext = false;
+    const isVerifyOnly = input.task.mutationMode === "verify_only";
     const executionProfile = resolveExecutionProfile({
         executionProfile: input.task.executionProfile,
         allowedNetworkDomains: input.task.allowedNetworkDomains
@@ -153,7 +158,8 @@ export async function runMartin(input) {
             shouldExit: true,
             lifecycleState: "human_escalation",
             status: "exited",
-            reason
+            reason,
+            ...classifySafetyLeashExit(leashDecision, "verifier")
         };
         if (input.store) {
             await input.store.appendLedger(loop.loopId, makeLedgerEvent({
@@ -169,15 +175,13 @@ export async function runMartin(input) {
             await input.store.appendLedger(loop.loopId, makeLedgerEvent({
                 kind: "run.exited",
                 runId: loop.loopId,
-                payload: {
-                    lifecycleState: leashExitDecision.lifecycleState,
-                    status: leashExitDecision.status,
-                    reason: leashExitDecision.reason
-                }
+                payload: createRunExitPayload(leashExitDecision)
             }));
         }
+        const finalizedLoop = finalizeLoop(loop, leashExitDecision, now(), idFactory);
+        await persistLoopRecordIfSupported(input.store, finalizedLoop);
         return {
-            loop: finalizeLoop(loop, leashExitDecision, now(), idFactory),
+            loop: finalizedLoop,
             decision: leashExitDecision
         };
     }
@@ -193,7 +197,8 @@ export async function runMartin(input) {
             shouldExit: true,
             lifecycleState: "human_escalation",
             status: "exited",
-            reason: secretDecision.reason ?? "Safety leash blocked secret-like values in the runtime context."
+            reason: secretDecision.reason ?? "Safety leash blocked secret-like values in the runtime context.",
+            ...classifySafetyLeashExit(secretDecision, "secret")
         };
         if (input.store) {
             await input.store.appendLedger(loop.loopId, makeLedgerEvent({
@@ -208,15 +213,13 @@ export async function runMartin(input) {
             await input.store.appendLedger(loop.loopId, makeLedgerEvent({
                 kind: "run.exited",
                 runId: loop.loopId,
-                payload: {
-                    lifecycleState: secretExitDecision.lifecycleState,
-                    status: secretExitDecision.status,
-                    reason: secretExitDecision.reason
-                }
+                payload: createRunExitPayload(secretExitDecision)
             }));
         }
+        const finalizedLoop = finalizeLoop(loop, secretExitDecision, now(), idFactory);
+        await persistLoopRecordIfSupported(input.store, finalizedLoop);
         return {
-            loop: finalizeLoop(loop, secretExitDecision, now(), idFactory),
+            loop: finalizedLoop,
             decision: secretExitDecision
         };
     }
@@ -254,20 +257,52 @@ export async function runMartin(input) {
                 await input.store.appendLedger(loop.loopId, makeLedgerEvent({
                     kind: "run.exited",
                     runId: loop.loopId,
-                    payload: {
-                        lifecycleState: preflightExitDecision.lifecycleState,
-                        status: preflightExitDecision.status,
-                        reason: preflightExitDecision.reason
-                    }
+                    payload: createRunExitPayload(preflightExitDecision)
                 }));
             }
+            const finalizedLoop = finalizeLoop(loop, preflightExitDecision, now(), idFactory);
+            await persistLoopRecordIfSupported(input.store, finalizedLoop);
             return {
-                loop: finalizeLoop(loop, preflightExitDecision, now(), idFactory),
+                loop: finalizedLoop,
                 decision: preflightExitDecision
             };
         }
         // GATHER → ADMIT: run admission control before executing
         currentPhase = "ADMIT";
+        // T05: Context Integrity Pre-gate — blocks authority inversion / injection before reasoning
+        const contextPrecheck = await runContextIntegrityPrecheck(loop.loopId, loop.attempts.length + 1, runDir(resolveRunsRoot(), loop.loopId), {
+            userPrompt: distilled.focus,
+            history: loop.attempts.map(a => a.summary).join("\n")
+        });
+        if (contextPrecheck.verdict === "context_poisoning_block") {
+            currentPhase = "ABORT";
+            const poisoningExitDecision = {
+                shouldExit: true,
+                lifecycleState: "human_escalation",
+                status: "exited",
+                reason: "Context Integrity Pre-gate: context poisoning attempt detected.",
+                failureClass: "safety_leash_blocked",
+                safetySurface: "context_integrity",
+                reasonCode: "context_poisoning_blocked"
+            };
+            if (input.store) {
+                await input.store.appendLedger(loop.loopId, makeLedgerEvent({
+                    kind: "safety.violations_found",
+                    runId: loop.loopId,
+                    payload: {
+                        verdict: contextPrecheck.verdict,
+                        signals: contextPrecheck.detectedSignals,
+                        source: "context_integrity_pregate"
+                    }
+                }));
+            }
+            const finalizedLoop = finalizeLoop(loop, poisoningExitDecision, now(), idFactory);
+            await persistLoopRecordIfSupported(input.store, finalizedLoop);
+            return {
+                loop: finalizedLoop,
+                decision: poisoningExitDecision
+            };
+        }
         const admissionDecision = evaluateAttemptPolicy({
             request: {
                 loopId: loop.loopId,
@@ -315,15 +350,13 @@ export async function runMartin(input) {
                 await input.store.appendLedger(loop.loopId, makeLedgerEvent({
                     kind: "run.exited",
                     runId: loop.loopId,
-                    payload: {
-                        lifecycleState: exitDecision.lifecycleState,
-                        status: exitDecision.status,
-                        reason: exitDecision.reason
-                    }
+                    payload: createRunExitPayload(exitDecision)
                 }));
             }
+            const finalizedLoop = finalizeLoop(loop, exitDecision, now(), idFactory);
+            await persistLoopRecordIfSupported(input.store, finalizedLoop);
             return {
-                loop: finalizeLoop(loop, exitDecision, now(), idFactory),
+                loop: finalizedLoop,
                 decision: exitDecision
             };
         }
@@ -361,6 +394,7 @@ export async function runMartin(input) {
                 objective: loop.task.objective,
                 verificationPlan: loop.task.verificationPlan,
                 ...(loop.task.verificationStack ? { verificationStack: loop.task.verificationStack } : {}),
+                ...(loop.task.mutationMode ? { mutationMode: loop.task.mutationMode } : {}),
                 ...(loop.task.repoRoot ? { repoRoot: loop.task.repoRoot } : {}),
                 ...(loop.task.allowedPaths ? { allowedPaths: loop.task.allowedPaths } : {}),
                 ...(loop.task.deniedPaths ? { deniedPaths: loop.task.deniedPaths } : {}),
@@ -539,6 +573,92 @@ export async function runMartin(input) {
         // returned a non-empty list. A repoRoot alone is insufficient — git may fail (e.g. not
         // a git repo) and silently return [], which would falsely trigger no_code_change.
         const changedFileEvidenceAvailable = result.execution?.changedFiles !== undefined || changedFiles.length > 0;
+        if (isVerifyOnly && changedFiles.length > 0) {
+            const patchDecision = evaluatePatchDecision({
+                verificationPassed: result.verification.passed,
+                previousVerifierScore,
+                verifierScore: result.verification.passed ? 1 : 0,
+                scopeViolationCount: changedFiles.length,
+                changedFileCount: changedFiles.length,
+                diffNovelty: 1,
+                diffStats: result.execution?.diffStats,
+                costUsd: getUsageUsd(result.usage),
+                summary: result.summary
+            });
+            const verifyOnlyExitDecision = {
+                shouldExit: true,
+                lifecycleState: "human_escalation",
+                status: "exited",
+                reason: "Verify-only mode forbids file changes.",
+                failureClass: "safety_leash_blocked",
+                safetySurface: "filesystem",
+                reasonCode: "verify_only_write_attempt"
+            };
+            const rollbackOutcome = await restoreRollbackBoundary({
+                repoRoot: request.context.repoRoot,
+                boundary: rollbackBoundary,
+                restoredAt: attemptCompletedAt,
+                decision: patchDecision.decision
+            });
+            if (input.store) {
+                const verifyOnlyViolation = {
+                    kind: "path_not_allowed",
+                    message: `Verify-only mode forbids changed files: ${changedFiles.join(", ")}`,
+                    file: changedFiles[0]
+                };
+                await input.store.writeAttemptArtifacts(loop.loopId, currentAttemptIndex, {
+                    compiledContext,
+                    leash: createLeashArtifact({
+                        surface: "filesystem",
+                        reason: verifyOnlyExitDecision.reason,
+                        violations: [verifyOnlyViolation]
+                    }, currentAttemptIndex),
+                    patchScore: patchDecision.score,
+                    patchDecision: toPatchDecisionArtifact(patchDecision),
+                    ...(rollbackBoundary ? { rollbackBoundary } : {}),
+                    ...(rollbackOutcome ? { rollbackOutcome } : {})
+                });
+                await input.store.appendLedger(loop.loopId, makeLedgerEvent({
+                    kind: "safety.violations_found",
+                    runId: loop.loopId,
+                    attemptIndex: currentAttemptIndex,
+                    payload: {
+                        surface: "filesystem",
+                        blocked: true,
+                        attemptIndex: currentAttemptIndex,
+                        violations: [
+                            {
+                                kind: "path_not_allowed",
+                                message: verifyOnlyExitDecision.reason,
+                                files: changedFiles
+                            }
+                        ]
+                    }
+                }));
+                await input.store.appendLedger(loop.loopId, makeLedgerEvent({
+                    kind: "attempt.discarded",
+                    runId: loop.loopId,
+                    attemptIndex: currentAttemptIndex,
+                    payload: {
+                        decision: patchDecision.decision,
+                        reason: patchDecision.summary,
+                        reasonCodes: patchDecision.reasonCodes,
+                        score: patchDecision.score.score
+                    }
+                }));
+                await input.store.appendLedger(loop.loopId, makeLedgerEvent({
+                    kind: "run.exited",
+                    runId: loop.loopId,
+                    payload: createRunExitPayload(verifyOnlyExitDecision)
+                }));
+            }
+            const finalizedLoop = finalizeLoop(loop, verifyOnlyExitDecision, now(), idFactory);
+            await persistLoopRecordIfSupported(input.store, finalizedLoop);
+            return {
+                loop: finalizedLoop,
+                decision: verifyOnlyExitDecision
+            };
+        }
         const filesystemDecision = evaluateFilesystemLeash({
             repoRoot: request.context.repoRoot,
             changedFiles,
@@ -561,7 +681,8 @@ export async function runMartin(input) {
                 shouldExit: true,
                 lifecycleState: "human_escalation",
                 status: "exited",
-                reason: filesystemDecision.reason ?? "Safety leash blocked filesystem changes."
+                reason: filesystemDecision.reason ?? "Safety leash blocked filesystem changes.",
+                ...classifySafetyLeashExit(filesystemDecision, "filesystem")
             };
             const rollbackOutcome = await restoreRollbackBoundary({
                 repoRoot: request.context.repoRoot,
@@ -603,15 +724,13 @@ export async function runMartin(input) {
                 await input.store.appendLedger(loop.loopId, makeLedgerEvent({
                     kind: "run.exited",
                     runId: loop.loopId,
-                    payload: {
-                        lifecycleState: filesystemExitDecision.lifecycleState,
-                        status: filesystemExitDecision.status,
-                        reason: filesystemExitDecision.reason
-                    }
+                    payload: createRunExitPayload(filesystemExitDecision)
                 }));
             }
+            const finalizedLoop = finalizeLoop(loop, filesystemExitDecision, now(), idFactory);
+            await persistLoopRecordIfSupported(input.store, finalizedLoop);
             return {
-                loop: finalizeLoop(loop, filesystemExitDecision, now(), idFactory),
+                loop: finalizedLoop,
                 decision: filesystemExitDecision
             };
         }
@@ -638,7 +757,8 @@ export async function runMartin(input) {
                 lifecycleState: "human_escalation",
                 status: "exited",
                 reason: changeApprovalDecision.reason ??
-                    "Safety leash blocked dependency or migration changes that require approval."
+                    "Safety leash blocked dependency or migration changes that require approval.",
+                ...classifySafetyLeashExit(changeApprovalDecision, "dependency")
             };
             const rollbackOutcome = await restoreRollbackBoundary({
                 repoRoot: request.context.repoRoot,
@@ -681,15 +801,13 @@ export async function runMartin(input) {
                 await input.store.appendLedger(loop.loopId, makeLedgerEvent({
                     kind: "run.exited",
                     runId: loop.loopId,
-                    payload: {
-                        lifecycleState: approvalExitDecision.lifecycleState,
-                        status: approvalExitDecision.status,
-                        reason: approvalExitDecision.reason
-                    }
+                    payload: createRunExitPayload(approvalExitDecision)
                 }));
             }
+            const finalizedLoop = finalizeLoop(loop, approvalExitDecision, now(), idFactory);
+            await persistLoopRecordIfSupported(input.store, finalizedLoop);
             return {
-                loop: finalizeLoop(loop, approvalExitDecision, now(), idFactory),
+                loop: finalizedLoop,
                 decision: approvalExitDecision
             };
         }
@@ -728,8 +846,8 @@ export async function runMartin(input) {
                 previousVerifierScore,
                 verifierScore: result.verification.passed ? 1 : 0,
                 groundingViolationCount: groundingScanResult?.violations.length ?? 0,
-                changedFileCount: changedFileEvidenceAvailable ? changedFiles.length : undefined,
-                diffNovelty: changedFileEvidenceAvailable ? (changedFiles.length > 0 ? 1 : 0) : undefined,
+                changedFileCount: !isVerifyOnly && changedFileEvidenceAvailable ? changedFiles.length : undefined,
+                diffNovelty: !isVerifyOnly && changedFileEvidenceAvailable ? (changedFiles.length > 0 ? 1 : 0) : undefined,
                 diffStats: result.execution?.diffStats,
                 costUsd: getUsageUsd(result.usage),
                 summary: result.summary
@@ -822,15 +940,13 @@ export async function runMartin(input) {
                 await input.store.appendLedger(loop.loopId, makeLedgerEvent({
                     kind: "run.exited",
                     runId: loop.loopId,
-                    payload: {
-                        lifecycleState: patchExitDecision.lifecycleState,
-                        status: patchExitDecision.status,
-                        reason: patchExitDecision.reason
-                    }
+                    payload: createRunExitPayload(patchExitDecision)
                 }));
             }
+            const finalizedLoop = finalizeLoop(loop, patchExitDecision, now(), idFactory);
+            await persistLoopRecordIfSupported(input.store, finalizedLoop);
             return {
-                loop: finalizeLoop(loop, patchExitDecision, now(), idFactory),
+                loop: finalizedLoop,
                 decision: patchExitDecision
             };
         }
@@ -870,15 +986,13 @@ export async function runMartin(input) {
                 await input.store.appendLedger(loop.loopId, makeLedgerEvent({
                     kind: "run.exited",
                     runId: loop.loopId,
-                    payload: {
-                        lifecycleState: decision.lifecycleState,
-                        status: decision.status,
-                        reason: decision.reason
-                    }
+                    payload: createRunExitPayload(decision)
                 }));
             }
+            const finalizedLoop = finalizeLoop(loop, decision, now(), idFactory);
+            await persistLoopRecordIfSupported(input.store, finalizedLoop);
             return {
-                loop: finalizeLoop(loop, decision, now(), idFactory),
+                loop: finalizedLoop,
                 decision
             };
         }
@@ -893,23 +1007,64 @@ export async function runMartin(input) {
         await input.store.appendLedger(loop.loopId, makeLedgerEvent({
             kind: "run.exited",
             runId: loop.loopId,
-            payload: {
-                lifecycleState: decision.lifecycleState,
-                status: decision.status,
-                reason: decision.reason
-            }
+            payload: createRunExitPayload(decision)
         }));
     }
+    const finalizedLoop = finalizeLoop(loop, decision, now(), idFactory);
+    await persistLoopRecordIfSupported(input.store, finalizedLoop);
     return {
-        loop: finalizeLoop(loop, decision, now(), idFactory),
+        loop: finalizedLoop,
         decision
     };
 }
+function createRunExitPayload(decision) {
+    return {
+        lifecycleState: decision.lifecycleState,
+        status: decision.status,
+        reason: decision.reason,
+        ...(decision.failureClass ? { failureClass: decision.failureClass } : {}),
+        ...(decision.safetySurface ? { safetySurface: decision.safetySurface } : {}),
+        ...(decision.reasonCode ? { reasonCode: decision.reasonCode } : {})
+    };
+}
+function classifySafetyLeashExit(decision, safetySurface = decision.surface) {
+    return {
+        failureClass: "safety_leash_blocked",
+        safetySurface,
+        reasonCode: safetyLeashReasonCode(decision, safetySurface)
+    };
+}
+function safetyLeashReasonCode(decision, safetySurface) {
+    const kind = decision.violations[0]?.kind;
+    switch (kind) {
+        case "command_blocked":
+            return safetySurface === "verifier" ? "destructive_verifier_command" : "command_blocked";
+        case "network_blocked":
+            return safetySurface === "verifier" ? "verifier_network_blocked" : "network_access_blocked";
+        case "secret_value":
+            return "secret_context_value";
+        case "path_denied":
+        case "protected_path":
+            return "protected_surface_write";
+        case "path_not_allowed":
+            return "surface_write_not_allowed";
+        case "path_outside_repo":
+            return "outside_repo_write";
+        case "dependency_approval_required":
+            return "dependency_approval_required";
+        case "migration_approval_required":
+            return "migration_approval_required";
+        case "config_change_approval_required":
+            return "config_change_approval_required";
+        default:
+            return `${safetySurface}_safety_block`;
+    }
+}
 function finalizeLoop(loop, decision, timestamp, idFactory) {
     const finalized = appendLoopEvent(loop, {
         type: "run.completed",
         lifecycleState: decision.lifecycleState,
-        payload: { status: decision.status, reason: decision.reason }
+        payload: createRunExitPayload(decision)
     }, { now: timestamp, idFactory });
     return {
         ...finalized,
@@ -918,6 +1073,9 @@ function finalizeLoop(loop, decision, timestamp, idFactory) {
         updatedAt: timestamp
     };
 }
+async function persistLoopRecordIfSupported(store, loop) {
+    await store?.writeLoopRecord?.(loop.loopId, loop);
+}
 function getAdapterTransport(adapter) {
     return adapter.metadata.transport ?? (adapter.kind === "agent-cli" ? "cli" : "http");
 }
@@ -934,7 +1092,7 @@ function getUsageProvenance(usage) {
     return "actual";
 }
 function resolveChangedFiles(result, repoRoot) {
-    if (result.execution?.changedFiles?.length) {
+    if (result.execution?.changedFiles !== undefined) {
         return result.execution.changedFiles;
     }
     if (!repoRoot) {

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

@@ -2,5 +2,7 @@ export { makeLedgerEvent } from "./ledger.js";
 export type { LedgerEvent, LedgerEventDraft, LedgerEventKind } from "./ledger.js";
 export { artifactDir, createFileRunStore, resolveRunsRoot, runDir } from "./store.js";
 export type { AttemptArtifacts, RunContract, RunStore } from "./store.js";
+export { readAllLoopRecords, readLatestLoopRecord, readLatestLoopRecordFromFile, readLoopRecordsFromFile } from "./runs-reader.js";
+export type { LoopAttemptRecord, LoopRunRecord } from "./runs-reader.js";
 export { compileAndPersistContext } from "./compiler.js";
 export type { CompileResult } from "./compiler.js";

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

@@ -1,4 +1,5 @@
 export { makeLedgerEvent } from "./ledger.js";
 export { artifactDir, createFileRunStore, resolveRunsRoot, runDir } from "./store.js";
+export { readAllLoopRecords, readLatestLoopRecord, readLatestLoopRecordFromFile, readLoopRecordsFromFile } from "./runs-reader.js";
 export { compileAndPersistContext } from "./compiler.js";
 //# sourceMappingURL=index.js.map

package/dist/vendor/core/persistence/runs-reader.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Reads completed loop records from ~/.martin/runs/ for analysis.
+ * Used by the Trust Calibration Engine and other offline analytics.
+ *
+ * Supports both storage layouts:
+ * - legacy root JSONL files: <runsRoot>/*.jsonl
+ * - canonical run trees: <runsRoot>/<loopId>/loop-record.json
+ */
+export interface LoopAttemptRecord {
+    index: number;
+    model?: string;
+    adapterId?: string;
+    failureClass?: string;
+    intervention?: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+export interface LoopRunRecord {
+    loopId: string;
+    status: string;
+    lifecycleState: string;
+    createdAt: string;
+    updatedAt: string;
+    budget: {
+        maxUsd: number;
+        softLimitUsd: number;
+        maxIterations: number;
+        maxTokens: number;
+    };
+    cost: {
+        actualUsd: number;
+        tokensIn: number;
+        tokensOut: number;
+        avoidedUsd?: number;
+    };
+    attempts: LoopAttemptRecord[];
+    task: {
+        title: string;
+        objective: string;
+    };
+}
+export declare function readLoopRecordsFromFile(file: string): Promise<LoopRunRecord[]>;
+export declare function readLatestLoopRecordFromFile(file: string): Promise<LoopRunRecord | null>;
+/**
+ * Reads all loop records from the given directory (default: ~/.martin/runs/).
+ * Returns an empty array if the directory doesn't exist or has no records.
+ */
+export declare function readAllLoopRecords(runsDir?: string): Promise<LoopRunRecord[]>;
+/**
+ * Returns the most recently updated loop record, or null if none exist.
+ */
+export declare function readLatestLoopRecord(runsDir?: string): Promise<LoopRunRecord | null>;

package/dist/vendor/core/persistence/runs-reader.js

@@ -0,0 +1,84 @@
+/**
+ * Reads completed loop records from ~/.martin/runs/ for analysis.
+ * Used by the Trust Calibration Engine and other offline analytics.
+ *
+ * Supports both storage layouts:
+ * - legacy root JSONL files: <runsRoot>/*.jsonl
+ * - canonical run trees: <runsRoot>/<loopId>/loop-record.json
+ */
+import { readFile, readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { extname, join } from "node:path";
+export async function readLoopRecordsFromFile(file) {
+    const text = await readFile(file, "utf8");
+    const extension = extname(file).toLowerCase();
+    if (extension === ".jsonl") {
+        return text
+            .split(/\r?\n/u)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : [parsed];
+}
+export async function readLatestLoopRecordFromFile(file) {
+    const records = await readLoopRecordsFromFile(file);
+    if (records.length === 0)
+        return null;
+    return records.reduce((latest, record) => {
+        const currentTimestamp = new Date(record.updatedAt ?? record.createdAt).getTime();
+        const latestTimestamp = new Date(latest.updatedAt ?? latest.createdAt).getTime();
+        return currentTimestamp > latestTimestamp ? record : latest;
+    }, records[0]);
+}
+/**
+ * Reads all loop records from the given directory (default: ~/.martin/runs/).
+ * Returns an empty array if the directory doesn't exist or has no records.
+ */
+export async function readAllLoopRecords(runsDir) {
+    const dir = runsDir ?? join(homedir(), ".martin", "runs");
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    const jsonlFiles = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => entry.name);
+    for (const file of jsonlFiles) {
+        try {
+            records.push(...(await readLoopRecordsFromFile(join(dir, file))));
+        }
+        catch {
+            // skip malformed files or lines
+        }
+    }
+    const runDirectories = entries.filter((entry) => entry.isDirectory());
+    for (const entry of runDirectories) {
+        try {
+            records.push(...(await readLoopRecordsFromFile(join(dir, entry.name, "loop-record.json"))));
+        }
+        catch {
+            // skip missing or malformed canonical records
+        }
+    }
+    return records;
+}
+/**
+ * Returns the most recently updated loop record, or null if none exist.
+ */
+export async function readLatestLoopRecord(runsDir) {
+    const records = await readAllLoopRecords(runsDir);
+    if (records.length === 0)
+        return null;
+    return records.reduce((latest, r) => {
+        const a = new Date(r.updatedAt ?? r.createdAt).getTime();
+        const b = new Date(latest.updatedAt ?? latest.createdAt).getTime();
+        return a > b ? r : latest;
+    }, records[0]);
+}
+//# sourceMappingURL=runs-reader.js.map

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

@@ -1,4 +1,4 @@
-import type { LoopBudget, LoopTask, MachineState } from "../../contracts/index.js";
+import type { LoopBudget, LoopRecord, LoopTask, MachineState } from "../../contracts/index.js";
 import { type LedgerEvent } from "./ledger.js";
 export interface RunContract {
     runId: string;
@@ -53,6 +53,11 @@ export interface RunStore {
      * Write artifacts for a completed attempt to artifacts/attempt-<n>/.
      */
     writeAttemptArtifacts(runId: string, attemptIndex: number, artifacts: AttemptArtifacts): Promise<void>;
+    /**
+     * Persist the latest canonical loop record snapshot when the caller has one.
+     * Optional to avoid breaking custom RunStore implementations.
+     */
+    writeLoopRecord?(runId: string, loop: LoopRecord): Promise<void>;
 }
 export declare function resolveRunsRoot(env?: NodeJS.ProcessEnv): string;
 export declare function runDir(runsRoot: string, runId: string): string;

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

@@ -74,6 +74,11 @@ export function createFileRunStore(options = {}) {
             if (artifacts.rollbackOutcome !== undefined) {
                 await writeJsonFile(join(dir, "rollback-outcome.json"), artifacts.rollbackOutcome);
             }
+        },
+        async writeLoopRecord(runId, loop) {
+            const dir = runDir(runsRoot, runId);
+            await mkdir(dir, { recursive: true });
+            await writeJsonFile(join(dir, "loop-record.json"), loop);
         }
     };
 }

package/dist/vendor/core/policy.d.ts

@@ -18,6 +18,12 @@ export interface ExitDecision {
     lifecycleState: LoopLifecycleState;
     status: LoopStatus;
     reason: string;
+    /** Machine-readable stop classifier for non-attempt exits such as preflight safety blocks. */
+    failureClass?: FailureClass;
+    /** Machine-readable safety surface, when the stop came from a safety leash. */
+    safetySurface?: string;
+    /** Stable reason code for dashboards, MCP, and downstream automation. */
+    reasonCode?: string;
 }
 export interface MartinAdapterResultLike {
     status: "completed" | "failed";