@martinloop/mcp 0.3.2 → 0.3.4

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

@@ -5,6 +5,10 @@ import { dirname, join } from "node:path";
 const RECEIPT_INTEGRITY_SCHEMA_VERSION = "martin.receipt-integrity.v1";
 const RECEIPT_INTEGRITY_KEY_DIR_MODE = 0o700;
 const RECEIPT_INTEGRITY_KEY_FILE_MODE = 0o600;
+export function resolveReceiptIntegrityRoot(env = process.env) {
+    return env["MARTIN_INTEGRITY_KEY_DIR"]?.trim() ??
+        join(homedir(), ".martin", "receipt-integrity");
+}
 export async function writeReceiptIntegrityMaterial(input) {
     const signedAt = input.signedAt ?? new Date().toISOString();
     const keyMaterial = await ensureReceiptIntegrityKey(input.runsRoot, input.runId);
@@ -45,9 +49,9 @@ export async function verifyReceiptIntegrityFromFiles(input) {
     ]);
     if (!rawMaterial || !rawLoopRecord || rawLedger === null || !key) {
         return {
-            state: "unsigned",
+            state: "material_missing",
             reason: "Receipt integrity material is missing for this run.",
-            warnings: ["Receipts are local-only and unsigned; trust claims are unavailable."]
+            warnings: ["Receipt integrity material is incomplete; trust claims are unavailable."]
         };
     }
     let material;
@@ -232,7 +236,7 @@ async function readReceiptIntegrityKey(runsRoot, runId) {
 }
 function resolveReceiptIntegrityKeyPath(runsRoot, runId) {
     const rootHash = sha256(runsRoot).slice(0, 16);
-    return join(homedir(), ".martin", "receipt-integrity", rootHash, `${runId}.key`);
+    return join(resolveReceiptIntegrityRoot(), rootHash, `${runId}.key`);
 }
 function serializeStoredJson(value) {
     return `${JSON.stringify(value, null, 2)}\n`;

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

@@ -39,6 +39,19 @@ export interface LoopRunRecord {
         objective: string;
     };
 }
+export interface LoopRecordsRollup {
+    generatedAt: string;
+    totalRuns: number;
+    statusBreakdown: Record<string, number>;
+    lifecycleBreakdown: Record<string, number>;
+    latestByLoopId: Record<string, {
+        status: string;
+        lifecycleState: string;
+        updatedAt: string;
+        costUsd: number;
+        attempts: number;
+    }>;
+}
 export declare function readLoopRecordsFromFile(file: string): Promise<LoopRunRecord[]>;
 export declare function readLatestLoopRecordFromFile(file: string): Promise<LoopRunRecord | null>;
 /**
@@ -50,3 +63,4 @@ export declare function readAllLoopRecords(runsDir?: string): Promise<LoopRunRec
  * Returns the most recently updated loop record, or null if none exist.
  */
 export declare function readLatestLoopRecord(runsDir?: string): Promise<LoopRunRecord | null>;
+export declare function buildLoopRecordsRollup(records: LoopRunRecord[]): LoopRecordsRollup;

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

@@ -45,13 +45,16 @@ export async function readAllLoopRecords(runsDir) {
     catch {
         return [];
     }
-    const records = [];
+    const recordsByLoopId = new Map();
     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))));
+            const fromFile = await readLoopRecordsFromFile(join(dir, file));
+            for (const record of fromFile) {
+                ingestRecord(recordsByLoopId, record, "legacy_jsonl");
+            }
         }
         catch {
             // skip malformed files or lines
@@ -60,13 +63,16 @@ export async function readAllLoopRecords(runsDir) {
     const runDirectories = entries.filter((entry) => entry.isDirectory());
     for (const entry of runDirectories) {
         try {
-            records.push(...(await readLoopRecordsFromFile(join(dir, entry.name, "loop-record.json"))));
+            const canonical = await readLoopRecordsFromFile(join(dir, entry.name, "loop-record.json"));
+            for (const record of canonical) {
+                ingestRecord(recordsByLoopId, record, "canonical_tree");
+            }
         }
         catch {
             // skip missing or malformed canonical records
         }
     }
-    return records;
+    return [...recordsByLoopId.values()].map((entry) => entry.record);
 }
 /**
  * Returns the most recently updated loop record, or null if none exist.
@@ -81,3 +87,54 @@ export async function readLatestLoopRecord(runsDir) {
         return a > b ? r : latest;
     }, records[0]);
 }
+export function buildLoopRecordsRollup(records) {
+    const statusBreakdown = {};
+    const lifecycleBreakdown = {};
+    const latestByLoopId = {};
+    for (const record of records) {
+        statusBreakdown[record.status] = (statusBreakdown[record.status] ?? 0) + 1;
+        lifecycleBreakdown[record.lifecycleState] = (lifecycleBreakdown[record.lifecycleState] ?? 0) + 1;
+        latestByLoopId[record.loopId] = {
+            status: record.status,
+            lifecycleState: record.lifecycleState,
+            updatedAt: record.updatedAt,
+            costUsd: record.cost.actualUsd,
+            attempts: record.attempts.length
+        };
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        totalRuns: records.length,
+        statusBreakdown,
+        lifecycleBreakdown,
+        latestByLoopId
+    };
+}
+function ingestRecord(recordsByLoopId, record, source) {
+    const existing = recordsByLoopId.get(record.loopId);
+    if (!existing) {
+        recordsByLoopId.set(record.loopId, { record, source });
+        return;
+    }
+    const candidateTimestamp = resolveRecordTimestamp(record);
+    const existingTimestamp = resolveRecordTimestamp(existing.record);
+    if (candidateTimestamp > existingTimestamp) {
+        recordsByLoopId.set(record.loopId, { record, source });
+        return;
+    }
+    if (candidateTimestamp === existingTimestamp &&
+        sourcePrecedence(source) > sourcePrecedence(existing.source)) {
+        recordsByLoopId.set(record.loopId, { record, source });
+    }
+}
+function resolveRecordTimestamp(record) {
+    const updated = Date.parse(record.updatedAt ?? "");
+    if (Number.isFinite(updated)) {
+        return updated;
+    }
+    const created = Date.parse(record.createdAt ?? "");
+    return Number.isFinite(created) ? created : 0;
+}
+function sourcePrecedence(source) {
+    return source === "canonical_tree" ? 2 : 1;
+}

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

@@ -0,0 +1,2 @@
+import { type ExecutionPolicy, type ExecutionPolicyCompileInput } from "../contracts/index.js";
+export declare function compileExecutionPolicy(input: ExecutionPolicyCompileInput): ExecutionPolicy;

package/dist/vendor/core/policy-compiler.js

@@ -0,0 +1,195 @@
+import { cloneExecutionPolicy } from "../contracts/index.js";
+export function compileExecutionPolicy(input) {
+    const provenance = [];
+    const budget = {
+        maxUsd: resolveBudgetField("maxUsd", input, provenance),
+        softLimitUsd: resolveBudgetField("softLimitUsd", input, provenance),
+        maxIterations: resolveBudgetField("maxIterations", input, provenance),
+        maxTokens: resolveBudgetField("maxTokens", input, provenance)
+    };
+    if (budget.softLimitUsd >= budget.maxUsd) {
+        budget.softLimitUsd = Math.round(budget.maxUsd * 0.75 * 100) / 100;
+        provenance.push({
+            field: "budget.softLimitUsd",
+            source: "config",
+            value: String(budget.softLimitUsd)
+        });
+    }
+    const governance = {
+        policyProfile: resolveEnumField({
+            field: "governance.policyProfile",
+            defaultsTo: input.defaults.policyProfile,
+            configValue: input.config?.policyProfile,
+            requestValue: input.request.policyProfile,
+            allowed: ["strict", "balanced", "overnight", "debug"],
+            provenance
+        }),
+        telemetryDestination: resolveEnumField({
+            field: "governance.telemetryDestination",
+            defaultsTo: input.defaults.telemetryDestination,
+            configValue: input.config?.governance?.telemetryDestination,
+            requestValue: input.request.telemetryDestination,
+            allowed: ["local-only", "control-plane"],
+            provenance
+        }),
+        destructiveActionPolicy: resolveEnumField({
+            field: "governance.destructiveActionPolicy",
+            defaultsTo: input.defaults.destructiveActionPolicy,
+            configValue: input.config?.governance?.destructiveActionPolicy,
+            allowed: ["never", "approval", "allowed"],
+            provenance
+        })
+    };
+    const verificationPlan = resolveVerificationPlan(input, provenance);
+    const task = {
+        verificationPlan
+    };
+    if (input.request.mutationMode) {
+        task.mutationMode = input.request.mutationMode;
+        provenance.push({
+            field: "task.mutationMode",
+            source: "request",
+            value: input.request.mutationMode
+        });
+    }
+    if (input.request.repoRoot) {
+        task.repoRoot = input.request.repoRoot;
+        provenance.push({
+            field: "task.repoRoot",
+            source: "request",
+            value: input.request.repoRoot
+        });
+    }
+    if ((input.request.allowedPaths?.length ?? 0) > 0) {
+        const allowedPaths = input.request.allowedPaths ?? [];
+        task.allowedPaths = [...allowedPaths];
+        provenance.push({
+            field: "task.allowedPaths",
+            source: "request",
+            value: allowedPaths.join(", ")
+        });
+    }
+    if ((input.request.deniedPaths?.length ?? 0) > 0) {
+        const deniedPaths = input.request.deniedPaths ?? [];
+        task.deniedPaths = [...deniedPaths];
+        provenance.push({
+            field: "task.deniedPaths",
+            source: "request",
+            value: deniedPaths.join(", ")
+        });
+    }
+    if ((input.request.acceptanceCriteria?.length ?? 0) > 0) {
+        const acceptanceCriteria = input.request.acceptanceCriteria ?? [];
+        task.acceptanceCriteria = [...acceptanceCriteria];
+        provenance.push({
+            field: "task.acceptanceCriteria",
+            source: "request",
+            value: acceptanceCriteria.join(", ")
+        });
+    }
+    if (input.request.approvalPolicy) {
+        task.approvalPolicy = { ...input.request.approvalPolicy };
+        provenance.push({
+            field: "task.approvalPolicy",
+            source: "request",
+            value: JSON.stringify(input.request.approvalPolicy)
+        });
+    }
+    return cloneExecutionPolicy({
+        configPath: input.configPath,
+        budget,
+        governance,
+        task,
+        provenance
+    });
+}
+function resolveBudgetField(field, input, provenance) {
+    if (input.request.budgetOverrides?.[field]) {
+        const value = input.request.budget[field];
+        provenance.push({
+            field: `budget.${String(field)}`,
+            source: "request",
+            value: String(value)
+        });
+        return value;
+    }
+    const configValue = input.config?.budget?.[field];
+    if (typeof configValue === "number" && Number.isFinite(configValue)) {
+        provenance.push({
+            field: `budget.${String(field)}`,
+            source: "config",
+            value: String(configValue)
+        });
+        return configValue;
+    }
+    const value = input.defaults.budget[field];
+    provenance.push({
+        field: `budget.${String(field)}`,
+        source: "default",
+        value: String(value)
+    });
+    return value;
+}
+function resolveVerificationPlan(input, provenance) {
+    const requestVerificationPlan = normalizeStringList(input.request.verificationPlan);
+    if (requestVerificationPlan.length > 0) {
+        provenance.push({
+            field: "task.verificationPlan",
+            source: "request",
+            value: requestVerificationPlan.join(", ")
+        });
+        return requestVerificationPlan;
+    }
+    const configVerificationPlan = normalizeStringList(input.config?.governance?.verifierRules);
+    if (configVerificationPlan.length > 0) {
+        provenance.push({
+            field: "task.verificationPlan",
+            source: "config",
+            value: configVerificationPlan.join(", ")
+        });
+        return configVerificationPlan;
+    }
+    const defaultVerificationPlan = normalizeStringList(input.defaults.verifierRules);
+    provenance.push({
+        field: "task.verificationPlan",
+        source: "default",
+        value: defaultVerificationPlan.join(", ")
+    });
+    return defaultVerificationPlan;
+}
+function resolveEnumField(input) {
+    const normalizedRequest = normalizeEnumCandidate(input.requestValue, input.allowed);
+    if (normalizedRequest) {
+        input.provenance.push({
+            field: input.field,
+            source: "request",
+            value: normalizedRequest
+        });
+        return normalizedRequest;
+    }
+    const normalizedConfig = normalizeEnumCandidate(input.configValue, input.allowed);
+    if (normalizedConfig) {
+        input.provenance.push({
+            field: input.field,
+            source: "config",
+            value: normalizedConfig
+        });
+        return normalizedConfig;
+    }
+    input.provenance.push({
+        field: input.field,
+        source: "default",
+        value: input.defaultsTo
+    });
+    return input.defaultsTo;
+}
+function normalizeEnumCandidate(value, allowed) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return allowed.find((candidate) => candidate === trimmed);
+}
+function normalizeStringList(values) {
+    return (values ?? []).map((value) => value.trim()).filter(Boolean);
+}

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

@@ -4,6 +4,8 @@ export interface FailureAssessment {
     rationale: string;
     retryable: boolean;
     recommendedIntervention: InterventionType;
+    /** Actionable diagnosis injected into the next attempt's prompt context. */
+    diagnosticHint?: string;
 }
 export interface CostGovernorState {
     pressure: "healthy" | "soft_limit" | "hard_limit";

package/dist/vendor/core/policy.js

@@ -78,7 +78,8 @@ export function classifyFailure(input) {
             failureClass: "environment_mismatch",
             rationale: "The adapter could not access the required local runtime or CLI tooling.",
             retryable: false,
-            recommendedIntervention: "switch_adapter"
+            recommendedIntervention: "switch_adapter",
+            diagnosticHint: diagnoseEnvironmentIssue(message)
         };
     }
     if (containsPositive(message, ["syntax error", "parse error", "typescript error"])) {
@@ -86,7 +87,8 @@ export function classifyFailure(input) {
             failureClass: "syntax_error",
             rationale: "The attempt failed on a parser or compiler-style issue.",
             retryable: true,
-            recommendedIntervention: "compress_context"
+            recommendedIntervention: "compress_context",
+            diagnosticHint: "Check for malformed edits — the verifier found a syntax or parse error in the changed files."
         };
     }
     if (containsPositive(message, [
@@ -104,7 +106,8 @@ export function classifyFailure(input) {
             failureClass: "repo_grounding_failure",
             rationale: "The attempt referenced modules, symbols, or files that are not grounded in the repo or approved docs.",
             retryable: true,
-            recommendedIntervention: repeatedFailure === "repo_grounding_failure" ? "tighten_task" : "run_verifier"
+            recommendedIntervention: repeatedFailure === "repo_grounding_failure" ? "tighten_task" : "run_verifier",
+            diagnosticHint: diagnoseGroundingIssue(message)
         };
     }
     if (containsPositive(message, [
@@ -118,7 +121,8 @@ export function classifyFailure(input) {
             failureClass: "verification_failure",
             rationale: "The proposed fix did not satisfy the verification gate.",
             retryable: true,
-            recommendedIntervention: repeatedFailure === "verification_failure" ? "tighten_task" : "run_verifier"
+            recommendedIntervention: repeatedFailure === "verification_failure" ? "tighten_task" : "run_verifier",
+            diagnosticHint: diagnoseVerificationIssue(message)
         };
     }
     if (containsPositive(message, [
@@ -622,3 +626,66 @@ function computeDiffRiskScore(input) {
 function roundScore(value) {
     return Math.round(value * 100) / 100;
 }
+// ---------------------------------------------------------------------------
+// Diagnostic hint generators
+//
+// These extract actionable context from failure messages so the next attempt
+// gets a concrete diagnosis, not just "verification failed."
+// ---------------------------------------------------------------------------
+const KNOWN_TOOLS = {
+    bun: "npm install -g bun",
+    pnpm: "npm install -g pnpm",
+    yarn: "npm install -g yarn",
+    eslint: "npm install eslint",
+    vitest: "npm install vitest",
+    jest: "npm install jest",
+    tsc: "npm install typescript",
+    prettier: "npm install prettier",
+    biome: "npm install @biomejs/biome"
+};
+function diagnoseEnvironmentIssue(message) {
+    // Try to extract the missing command name
+    const cmdMatch = message.match(/(?:command not found|enoent)[:\s]*['"]?(\w[\w.-]*)/i)
+        ?? message.match(/['"](\w[\w.-]*)['"].*(?:not found|enoent)/i);
+    const missingCmd = cmdMatch?.[1];
+    if (missingCmd && KNOWN_TOOLS[missingCmd.toLowerCase()]) {
+        return `The verifier needs "${missingCmd}" which is not installed. Fix: ${KNOWN_TOOLS[missingCmd.toLowerCase()]}`;
+    }
+    if (missingCmd) {
+        return `The verifier could not find "${missingCmd}". Ensure it is installed in the workspace before retrying.`;
+    }
+    return "A required tool or command was not found in the environment. Check that all dependencies referenced by the verify command are installed.";
+}
+function diagnoseGroundingIssue(message) {
+    // Extract the missing module/symbol name
+    const moduleMatch = message.match(/cannot find module ['"]([^'"]+)['"]/i)
+        ?? message.match(/module not found[:\s]*['"]?([^\s'"]+)/i);
+    const nameMatch = message.match(/cannot find name ['"]?(\w+)/i);
+    if (moduleMatch?.[1]) {
+        const mod = moduleMatch[1];
+        const isRelative = mod.startsWith(".") || mod.startsWith("/");
+        if (isRelative) {
+            return `Import "${mod}" points to a file that does not exist. Check the path and filename.`;
+        }
+        return `Module "${mod}" is not installed. Run npm install or check package.json dependencies.`;
+    }
+    if (nameMatch?.[1]) {
+        return `Symbol "${nameMatch[1]}" is not defined. Check that the import exists and the name is spelled correctly.`;
+    }
+    return "The code references modules or symbols that do not exist in the repository. Verify imports and file paths.";
+}
+function diagnoseVerificationIssue(message) {
+    // Count assertion failures for severity signal
+    const assertionCount = (message.match(/assertionerror/gi) ?? []).length;
+    if (assertionCount > 3) {
+        return `${String(assertionCount)} assertion failures detected — the change may have introduced a regression. Focus on the specific test expectations that broke.`;
+    }
+    // Check for common patterns
+    if (/timeout/i.test(message) && !/budget/i.test(message)) {
+        return "Tests timed out. The change may have introduced an infinite loop or unresolved async operation.";
+    }
+    if (/exit code (?!0)\d+/i.test(message) || /exited with code/i.test(message)) {
+        return "The verifier command exited non-zero. Read the output above to identify which specific check failed and why.";
+    }
+    return "Verification did not pass. Review the verifier output for the specific failing assertion or check.";
+}

package/dist/vendor/core/rollback.js

@@ -119,17 +119,24 @@ function readRepoState(repoRoot) {
     };
 }
 function readGitLines(repoRoot, args) {
-    const result = spawnSync("git", args, {
-        cwd: repoRoot,
-        encoding: "utf8"
-    });
-    if (result.status !== 0 || typeof result.stdout !== "string") {
-        return [];
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const result = spawnSync("git", args, {
+            cwd: repoRoot,
+            encoding: "utf8"
+        });
+        if (result.status === 0 && typeof result.stdout === "string") {
+            return uniqueSorted(result.stdout
+                .split(/\r?\n/u)
+                .map((line) => normalizeRepoPath(line))
+                .filter(Boolean));
+        }
+        // Retry once after a short delay — handles git lock-file contention
+        // that occurs when another process holds .git/index.lock.
+        if (attempt === 0 && result.status !== 0) {
+            spawnSync("sleep", ["0.5"], { encoding: "utf8" });
+        }
     }
-    return uniqueSorted(result.stdout
-        .split(/\r?\n/u)
-        .map((line) => normalizeRepoPath(line))
-        .filter(Boolean));
+    return [];
 }
 function readGitScalar(repoRoot, args) {
     const result = spawnSync("git", args, {
@@ -175,9 +182,22 @@ function restoreTrackedFileFromHead(repoRoot, filePath) {
         cwd: repoRoot,
         encoding: "utf8"
     });
-    if (result.status !== 0) {
-        throw new Error(result.stderr?.trim() || `git restore failed for ${filePath}`);
+    if (result.status === 0) {
+        return;
+    }
+    // Retry once after a short delay (git lock-file contention)
+    spawnSync("sleep", ["0.5"], { encoding: "utf8" });
+    const retry = spawnSync("git", ["restore", "--staged", "--worktree", "--source=HEAD", "--", filePath], { cwd: repoRoot, encoding: "utf8" });
+    if (retry.status === 0) {
+        return;
+    }
+    // Fallback: try git checkout which works on older git versions
+    const fallback = spawnSync("git", ["checkout", "HEAD", "--", filePath], { cwd: repoRoot, encoding: "utf8" });
+    if (fallback.status === 0) {
+        return;
     }
+    throw new Error(result.stderr?.trim() ||
+        `git restore failed for ${filePath} (retry and checkout fallback also failed)`);
 }
 async function removeRepoPath(repoRoot, filePath) {
     await rm(resolveRepoPath(repoRoot, filePath), { recursive: true, force: true });

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

@@ -0,0 +1,18 @@
+import { type CircuitBreakDecision, type TrajectoryAssessment } from "../contracts/index.js";
+export declare function assessTrajectory(input: {
+    objective: string;
+    verificationPlan?: string[];
+    attempts: TrajectoryAttemptLike[];
+}): TrajectoryAssessment;
+export declare function decideCircuitBreak(input: {
+    objective: string;
+    verificationPlan?: string[];
+    attempts: TrajectoryAttemptLike[];
+    remainingIterations?: number;
+}): CircuitBreakDecision;
+interface TrajectoryAttemptLike {
+    index: number;
+    summary?: string;
+    failureClass?: string;
+}
+export {};