@martinloop/mcp 0.3.6 → 0.3.8

package/dist/vendor/adapters/core/src/trajectory.js

@@ -0,0 +1,295 @@
+import { cloneCircuitBreakDecision, cloneTrajectoryAssessment } from "../../../contracts/index.js";
+const STOP_WORDS = new Set([
+    "about",
+    "after",
+    "again",
+    "along",
+    "also",
+    "been",
+    "before",
+    "being",
+    "between",
+    "could",
+    "failed",
+    "failure",
+    "from",
+    "have",
+    "into",
+    "just",
+    "keep",
+    "made",
+    "make",
+    "need",
+    "only",
+    "over",
+    "same",
+    "should",
+    "still",
+    "than",
+    "that",
+    "their",
+    "them",
+    "then",
+    "there",
+    "these",
+    "they",
+    "this",
+    "those",
+    "touching",
+    "without",
+    "would"
+]);
+const STALL_FAILURE_CLASSES = new Set([
+    "logic_error",
+    "verification_failure",
+    "repo_grounding_failure",
+    "scope_creep",
+    "no_progress"
+]);
+export function assessTrajectory(input) {
+    const attempts = input.attempts.filter((attempt) => attempt.index > 0);
+    if (attempts.length === 0) {
+        return cloneTrajectoryAssessment({
+            status: "healthy",
+            confidence: "low",
+            summary: "No prior attempts exist, so Martin has no drift evidence yet.",
+            signals: []
+        });
+    }
+    const signals = [];
+    const recentAttempts = attempts.slice(-4);
+    const lastThree = recentAttempts.slice(-3);
+    const lastTwo = recentAttempts.slice(-2);
+    const oscillation = detectFailureOscillation(lastThree);
+    if (oscillation) {
+        signals.push(oscillation);
+    }
+    const repetition = detectAttemptRepetition(lastThree);
+    if (repetition) {
+        signals.push(repetition);
+    }
+    const verificationStall = detectVerificationStall(lastTwo);
+    if (verificationStall) {
+        signals.push(verificationStall);
+    }
+    const objectiveDrift = detectObjectiveDrift({
+        objective: input.objective,
+        verificationPlan: input.verificationPlan,
+        attempts: lastTwo
+    });
+    if (objectiveDrift) {
+        signals.push(objectiveDrift);
+    }
+    const status = deriveTrajectoryStatus(signals);
+    const confidence = deriveTrajectoryConfidence(signals);
+    const recommendedIntervention = deriveRecommendedIntervention(signals);
+    if (signals.length === 0) {
+        return cloneTrajectoryAssessment({
+            status: "healthy",
+            confidence: "medium",
+            summary: "Recent attempts stay aligned enough that Martin does not need a circuit break yet.",
+            signals: []
+        });
+    }
+    const summary = summarizeTrajectory(status, signals);
+    return cloneTrajectoryAssessment({
+        status,
+        confidence,
+        summary,
+        signals,
+        ...(recommendedIntervention ? { recommendedIntervention } : {})
+    });
+}
+export function decideCircuitBreak(input) {
+    const assessment = assessTrajectory(input);
+    const remainingIterations = input.remainingIterations ?? Number.POSITIVE_INFINITY;
+    const stopForHighSignal = assessment.signals.some((signal) => signal.severity === "high");
+    const stopForLateDrift = assessment.status === "drifting" &&
+        remainingIterations <= 1 &&
+        assessment.signals.some((signal) => signal.code === "objective_drift");
+    const stopForLateStall = assessment.status === "watch" &&
+        remainingIterations <= 1 &&
+        assessment.signals.some((signal) => signal.code === "verification_stall");
+    const shouldStop = stopForHighSignal || stopForLateDrift || stopForLateStall;
+    return cloneCircuitBreakDecision({
+        shouldStop,
+        reason: shouldStop
+            ? assessment.summary
+            : "Trajectory signals do not justify a hard circuit break yet.",
+        assessment,
+        ...(assessment.recommendedIntervention
+            ? { recommendedIntervention: assessment.recommendedIntervention }
+            : {})
+    });
+}
+function detectFailureOscillation(attempts) {
+    if (attempts.length < 3) {
+        return undefined;
+    }
+    const [first, second, third] = attempts;
+    if (!first?.failureClass ||
+        !second?.failureClass ||
+        !third?.failureClass ||
+        first.failureClass === second.failureClass ||
+        first.failureClass !== third.failureClass) {
+        return undefined;
+    }
+    return {
+        code: "failure_oscillation",
+        severity: "high",
+        summary: `Attempts ${first.index}, ${second.index}, and ${third.index} oscillate between failure classes instead of converging.`,
+        attemptIndexes: [first.index, second.index, third.index]
+    };
+}
+function detectAttemptRepetition(attempts) {
+    if (attempts.length < 3) {
+        return undefined;
+    }
+    const tokenSets = attempts.map((attempt) => toTokenSet(attempt.summary));
+    if (tokenSets.some((tokens) => tokens.size < 4)) {
+        return undefined;
+    }
+    const pairScores = [
+        jaccardSimilarity(tokenSets[0], tokenSets[1]),
+        jaccardSimilarity(tokenSets[1], tokenSets[2]),
+        jaccardSimilarity(tokenSets[0], tokenSets[2])
+    ];
+    if (pairScores.every((score) => score >= 0.55)) {
+        const matchedTerms = intersectSets(tokenSets[0], new Set(intersectSets(tokenSets[1], tokenSets[2])));
+        return {
+            code: "attempt_repetition",
+            severity: "high",
+            summary: `Attempts ${attempts.map((attempt) => attempt.index).join(", ")} are materially repetitive and are not exploring a new path.`,
+            attemptIndexes: attempts.map((attempt) => attempt.index),
+            ...(matchedTerms.length > 0 ? { matchedTerms: matchedTerms.slice(0, 6) } : {})
+        };
+    }
+    return undefined;
+}
+function detectVerificationStall(attempts) {
+    if (attempts.length < 2) {
+        return undefined;
+    }
+    const relevant = attempts.filter((attempt) => {
+        const failureClass = attempt.failureClass;
+        return failureClass !== undefined && STALL_FAILURE_CLASSES.has(failureClass);
+    });
+    if (relevant.length < 2) {
+        return undefined;
+    }
+    const tokenSets = relevant.map((attempt) => toTokenSet(attempt.summary));
+    const overlap = tokenSets
+        .slice(1)
+        .map((tokens, index) => jaccardSimilarity(tokenSets[index], tokens))
+        .reduce((highest, score) => Math.max(highest, score), 0);
+    if (overlap < 0.35) {
+        return undefined;
+    }
+    const latest = relevant.at(-1);
+    return {
+        code: "verification_stall",
+        severity: "medium",
+        summary: `Recent attempts keep landing on the same verifier-facing failure surface (${latest.failureClass}).`,
+        attemptIndexes: relevant.map((attempt) => attempt.index)
+    };
+}
+function detectObjectiveDrift(input) {
+    if (input.attempts.length < 2) {
+        return undefined;
+    }
+    const objectiveTerms = toTokenSet(`${input.objective} ${(input.verificationPlan ?? []).join(" ")}`);
+    if (objectiveTerms.size < 4) {
+        return undefined;
+    }
+    const summaryTerms = input.attempts.map((attempt) => toTokenSet(attempt.summary));
+    const overlaps = summaryTerms.map((terms) => jaccardSimilarity(terms, objectiveTerms));
+    if (overlaps.some((score) => score >= 0.18)) {
+        return undefined;
+    }
+    const sharedDriftTerms = intersectSets(summaryTerms[0], summaryTerms[1]);
+    if (sharedDriftTerms.length < 3) {
+        return undefined;
+    }
+    return {
+        code: "objective_drift",
+        severity: "medium",
+        summary: "Recent attempt summaries are converging on work that does not overlap with the original objective or verifier plan.",
+        attemptIndexes: input.attempts.map((attempt) => attempt.index),
+        matchedTerms: sharedDriftTerms.slice(0, 6)
+    };
+}
+function deriveTrajectoryStatus(signals) {
+    if (signals.some((signal) => signal.severity === "high")) {
+        return "stalled";
+    }
+    if (signals.some((signal) => signal.code === "objective_drift")) {
+        return "drifting";
+    }
+    if (signals.some((signal) => signal.severity === "medium")) {
+        return "watch";
+    }
+    return "healthy";
+}
+function deriveTrajectoryConfidence(signals) {
+    if (signals.some((signal) => signal.severity === "high")) {
+        return "high";
+    }
+    if (signals.some((signal) => signal.severity === "medium")) {
+        return "medium";
+    }
+    return "low";
+}
+function deriveRecommendedIntervention(signals) {
+    if (signals.some((signal) => signal.code === "failure_oscillation" || signal.code === "attempt_repetition")) {
+        return "escalate_human";
+    }
+    if (signals.some((signal) => signal.code === "objective_drift")) {
+        return "tighten_task";
+    }
+    if (signals.some((signal) => signal.code === "verification_stall")) {
+        return "run_verifier";
+    }
+    return undefined;
+}
+function summarizeTrajectory(status, signals) {
+    const lead = signals[0];
+    if (!lead) {
+        return "Trajectory is healthy.";
+    }
+    switch (status) {
+        case "stalled":
+            return `Trajectory stalled: ${lead.summary}`;
+        case "drifting":
+            return `Trajectory drift detected: ${lead.summary}`;
+        case "watch":
+            return `Trajectory warning: ${lead.summary}`;
+        default:
+            return lead.summary;
+    }
+}
+function toTokenSet(text) {
+    return new Set((text ?? "")
+        .toLowerCase()
+        .match(/[a-z][a-z0-9_/-]{2,}/g)
+        ?.flatMap((token) => splitCompositeToken(token))
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3 && !STOP_WORDS.has(token)) ?? []);
+}
+function splitCompositeToken(token) {
+    return token
+        .split(/[-_/]/g)
+        .flatMap((part) => part.split(/(?=[A-Z])/g))
+        .map((part) => part.toLowerCase())
+        .filter(Boolean);
+}
+function jaccardSimilarity(left, right) {
+    if (left.size === 0 || right.size === 0) {
+        return 0;
+    }
+    const intersection = intersectSets(left, right).length;
+    const union = new Set([...left, ...right]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+function intersectSets(left, right) {
+    return [...left].filter((term) => right.has(term));
+}

package/dist/vendor/adapters/openai-compatible.js

@@ -72,12 +72,12 @@ function estimateCost(model, inputChars, outputChars) {
 // ---------------------------------------------------------------------------
 // Prompt builder
 // ---------------------------------------------------------------------------
-const DEFAULT_SYSTEM_PROMPT = `You are an expert software engineer executing a governed coding task.
-Follow these rules exactly:
-- Read the task description carefully and implement only what is asked.
-- Do not add features, refactors, or improvements beyond the stated task.
-- If the task asks you to write or modify code, output the complete file content with changes applied.
-- Be precise, minimal, and test-backed in all changes.
+const DEFAULT_SYSTEM_PROMPT = `You are an expert software engineer executing a governed coding task.
+Follow these rules exactly:
+- Read the task description carefully and implement only what is asked.
+- Do not add features, refactors, or improvements beyond the stated task.
+- If the task asks you to write or modify code, output the complete file content with changes applied.
+- Be precise, minimal, and test-backed in all changes.
 - State what you changed and why at the end of your response.`;
 export const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com";
 export const DEFAULT_OPENAI_MODEL = "gpt-4.1-mini";

package/dist/vendor/adapters/verifier-only.js

@@ -20,11 +20,11 @@ export function createVerifierOnlyAdapter(options = {}) {
             const shouldTrackVerifierWrites = request.context.verificationPlan.length > 0 ||
                 (request.context.verificationStack?.length ?? 0) > 0;
             const baselineChangedFiles = shouldTrackVerifierWrites
-                ? new Set(await readGitChangedFiles(workingDirectory, 5_000))
+                ? new Set(await readGitChangedFiles(workingDirectory, 5_000, options.spawnImpl))
                 : new Set();
             const verification = await runVerification(request.context.verificationPlan, workingDirectory, verifyTimeoutMs, request.context.verificationStack, options.spawnImpl);
             const changedFiles = shouldTrackVerifierWrites
-                ? (await readGitChangedFiles(workingDirectory, 5_000)).filter((file) => !baselineChangedFiles.has(file))
+                ? (await readGitChangedFiles(workingDirectory, 5_000, options.spawnImpl)).filter((file) => !baselineChangedFiles.has(file))
                 : [];
             const execution = { changedFiles };
             if (verification.passed) {

package/dist/vendor/contracts/delivery.d.ts

@@ -0,0 +1,47 @@
+/**
+ * R4 Delivery — M1 Contract
+ *
+ * Shared with Lane B (Control Plane). Do not modify unilaterally.
+ * The server selects one message; the client never downloads the catalog.
+ */
+export declare const DELIVERY_MESSAGE_SCHEMA_VERSION: "delivery-message/1";
+export declare const DELIVERY_RECORD_SCHEMA_VERSION: "delivery-record/1";
+export declare const MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION: "martin-message-selection/1";
+export declare const ALLOWED_ACTION_TYPES: readonly ["upgrade_cli", "upgrade_mcp", "submit_feedback", "open_release_notes", "dismiss", "view_spend_report", "view_run_explain"];
+export type ActionType = (typeof ALLOWED_ACTION_TYPES)[number];
+export type MessageKind = "update" | "feedback_request" | "milestone";
+export interface DeliveryMessage {
+    schemaVersion: typeof DELIVERY_MESSAGE_SCHEMA_VERSION;
+    id: string;
+    revision: number;
+    kind: MessageKind;
+    title: string;
+    body: string;
+    action: {
+        type: ActionType;
+        url?: string;
+        targetVersion?: string;
+    };
+    expiresAt: string;
+    cooldownHours: number;
+}
+export interface MessageSelectionResponse {
+    schemaVersion: typeof MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION;
+    message?: DeliveryMessage;
+}
+/** Local cooldown/dismissal state — persisted in .martin/delivery-record.json */
+export interface DeliveryRecord {
+    schemaVersion: typeof DELIVERY_RECORD_SCHEMA_VERSION;
+    lastMessageId?: string;
+    lastShownAtEpochMs?: number;
+    dismissedIds: string[];
+    cooldownUntilEpochMs?: number;
+    cachedMessage?: DeliveryMessage;
+    cachedAtEpochMs?: number;
+}
+/** Structured update field for --json and MCP responses */
+export interface UpdateAvailableField {
+    targetVersion: string;
+    kind: "cli" | "mcp";
+    message?: string;
+}

package/dist/vendor/contracts/delivery.js

@@ -0,0 +1,18 @@
+/**
+ * R4 Delivery — M1 Contract
+ *
+ * Shared with Lane B (Control Plane). Do not modify unilaterally.
+ * The server selects one message; the client never downloads the catalog.
+ */
+export const DELIVERY_MESSAGE_SCHEMA_VERSION = "delivery-message/1";
+export const DELIVERY_RECORD_SCHEMA_VERSION = "delivery-record/1";
+export const MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION = "martin-message-selection/1";
+export const ALLOWED_ACTION_TYPES = [
+    "upgrade_cli",
+    "upgrade_mcp",
+    "submit_feedback",
+    "open_release_notes",
+    "dismiss",
+    "view_spend_report",
+    "view_run_explain",
+];

package/dist/vendor/contracts/index.d.ts

@@ -23,7 +23,7 @@ export interface LoopTask {
     acceptanceCriteria?: string[];
 }
 export type ExecutionProfile = "strict_local" | "ci_safe" | "staging_controlled" | "research_untrusted";
-export type MutationMode = "edit" | "verify_only";
+export type MutationMode = "edit";
 export interface ApprovalPolicy {
     dependencyAdds?: boolean;
     migrations?: boolean;
@@ -410,3 +410,5 @@ export { cloneIdentityAttestation, cloneIdentityClaims, cloneIdentityToken } fro
 export type { IdentityAttestation, IdentityClaims, IdentityToken } from "./identity.js";
 export { cloneCircuitBreakDecision, cloneTrajectoryAssessment } from "./trajectory.js";
 export type { CircuitBreakDecision, TrajectoryAssessment, TrajectorySignal } from "./trajectory.js";
+export { ALLOWED_ACTION_TYPES, DELIVERY_MESSAGE_SCHEMA_VERSION, DELIVERY_RECORD_SCHEMA_VERSION, MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION } from "./delivery.js";
+export type { ActionType, DeliveryMessage, DeliveryRecord, MessageKind, MessageSelectionResponse, UpdateAvailableField } from "./delivery.js";

package/dist/vendor/contracts/index.js

@@ -223,3 +223,5 @@ export { DEFAULT_ROUTING_POLICY } from "./execution-policy.js";
 export { cloneContextGraphSnapshot } from "./context-graph.js";
 export { cloneIdentityAttestation, cloneIdentityClaims, cloneIdentityToken } from "./identity.js";
 export { cloneCircuitBreakDecision, cloneTrajectoryAssessment } from "./trajectory.js";
+// ─── R4 Delivery — M1 Contract ──────────────────────────────────────────────
+export { ALLOWED_ACTION_TYPES, DELIVERY_MESSAGE_SCHEMA_VERSION, DELIVERY_RECORD_SCHEMA_VERSION, MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION } from "./delivery.js";

package/dist/vendor/core/compiler.js

@@ -8,15 +8,10 @@ export function compilePromptPacket(request) {
     const priorFailurePatterns = request.previousAttempts
         .filter((a) => a.failureClass && a.intervention)
         .map((a) => `${a.failureClass}:${a.intervention}`);
-    const guidanceParts = request.context.mutationMode === "verify_only"
-        ? [
-            "Do not modify files.",
-            "Run the verifier only and report whether it passed."
-        ]
-        : [
-            "Only modify files directly required to satisfy the contract.",
-            "Do not touch files outside the allowed paths."
-        ];
+    const guidanceParts = [
+        "Only modify files directly required to satisfy the contract.",
+        "Do not touch files outside the allowed paths."
+    ];
     if (request.context.allowedPaths && request.context.allowedPaths.length > 0) {
         guidanceParts.push(`Allowed paths: ${request.context.allowedPaths.join(", ")}.`);
     }

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

@@ -0,0 +1,6 @@
+export { fetchSelectedMessage } from "./message-client.js";
+export type { MessageClientOptions, MessageSelectRequest } from "./message-client.js";
+export { cacheMessage, isCooldownExpired, isDismissed, loadDeliveryRecord, recordDismissed, recordShown, resolveDefaultLedgerPath, saveDeliveryRecord, } from "./message-ledger.js";
+export { parseMessageSelectionResponse } from "./message-schema.js";
+export type { ParseFailure, ParseResult, ValidationError } from "./message-schema.js";
+export { getCliInstalledVersion, getMcpInstalledVersion, isNewerVersion } from "./update-check.js";

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

@@ -0,0 +1,4 @@
+export { fetchSelectedMessage } from "./message-client.js";
+export { cacheMessage, isCooldownExpired, isDismissed, loadDeliveryRecord, recordDismissed, recordShown, resolveDefaultLedgerPath, saveDeliveryRecord, } from "./message-ledger.js";
+export { parseMessageSelectionResponse } from "./message-schema.js";
+export { getCliInstalledVersion, getMcpInstalledVersion, isNewerVersion } from "./update-check.js";

package/dist/vendor/core/delivery/message-client.d.ts

@@ -0,0 +1,18 @@
+import { type DeliveryMessage } from "../../contracts/index.js";
+export interface MessageSelectRequest {
+    installId?: string;
+    clientVersion: string;
+    clientKind: "cli" | "mcp";
+    /** Enum signal — never a transcript or raw content */
+    trigger?: "first_verified_run" | "milestone_reached" | "version_check";
+}
+export interface MessageClientOptions {
+    endpoint?: string;
+    timeoutMs?: number;
+}
+/**
+ * Fetch a server-selected message from the Control Plane.
+ * Returns null on any network failure, timeout, or validation error.
+ * Never throws — the primary command must never be affected.
+ */
+export declare function fetchSelectedMessage(request: MessageSelectRequest, options?: MessageClientOptions): Promise<DeliveryMessage | null>;

package/dist/vendor/core/delivery/message-client.js

@@ -0,0 +1,38 @@
+import { parseMessageSelectionResponse } from "./message-schema.js";
+const DEFAULT_ENDPOINT = "https://api.martinloop.com/v1/messages/select";
+const REQUEST_TIMEOUT_MS = 4_000;
+/**
+ * Fetch a server-selected message from the Control Plane.
+ * Returns null on any network failure, timeout, or validation error.
+ * Never throws — the primary command must never be affected.
+ */
+export async function fetchSelectedMessage(request, options = {}) {
+    const endpoint = options.endpoint ?? process.env["MARTIN_MESSAGE_ENDPOINT"] ?? DEFAULT_ENDPOINT;
+    const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+    let controller;
+    let timeoutId;
+    try {
+        controller = new AbortController();
+        timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Accept": "application/json" },
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const raw = await response.text();
+        const result = parseMessageSelectionResponse(raw);
+        if (!result.ok)
+            return null;
+        return result.message ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    }
+}

package/dist/vendor/core/delivery/message-ledger.d.ts

@@ -0,0 +1,35 @@
+import { type DeliveryMessage, type DeliveryRecord } from "../../contracts/index.js";
+/**
+ * Load DeliveryRecord from disk. Returns empty record on any read/parse failure — never throws.
+ */
+export declare function loadDeliveryRecord(ledgerPath: string): DeliveryRecord;
+/**
+ * Persist DeliveryRecord atomically via temp-file + rename.
+ */
+export declare function saveDeliveryRecord(ledgerPath: string, record: DeliveryRecord): void;
+/**
+ * Returns true when the cooldown period has elapsed and the message should be shown.
+ * Clock-skew safe: if now < lastShownAtEpochMs (clock jumped back), treat cooldown as expired.
+ */
+export declare function isCooldownExpired(record: DeliveryRecord, nowMs: number): boolean;
+/**
+ * Returns true if this message id was permanently dismissed.
+ */
+export declare function isDismissed(record: DeliveryRecord, messageId: string): boolean;
+/**
+ * Record that a message was shown. Updates cooldown window.
+ */
+export declare function recordShown(record: DeliveryRecord, message: DeliveryMessage, nowMs: number): DeliveryRecord;
+/**
+ * Record that a message was permanently dismissed.
+ */
+export declare function recordDismissed(record: DeliveryRecord, messageId: string): DeliveryRecord;
+/**
+ * Cache a fetched message for offline use.
+ */
+export declare function cacheMessage(record: DeliveryRecord, message: DeliveryMessage, nowMs: number): DeliveryRecord;
+/**
+ * Resolve the default ledger path: $MARTIN_STATE_DIR/delivery-record.json
+ * or ~/.martin/delivery-record.json.
+ */
+export declare function resolveDefaultLedgerPath(): string;

package/dist/vendor/core/delivery/message-ledger.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DELIVERY_RECORD_SCHEMA_VERSION } from "../../contracts/index.js";
+const EMPTY_RECORD = {
+    schemaVersion: DELIVERY_RECORD_SCHEMA_VERSION,
+    dismissedIds: [],
+};
+/**
+ * Load DeliveryRecord from disk. Returns empty record on any read/parse failure — never throws.
+ */
+export function loadDeliveryRecord(ledgerPath) {
+    try {
+        const raw = fs.readFileSync(ledgerPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            !Array.isArray(parsed) &&
+            parsed["schemaVersion"] === DELIVERY_RECORD_SCHEMA_VERSION) {
+            return parsed;
+        }
+    }
+    catch {
+        // file missing or corrupt — start fresh
+    }
+    return { ...EMPTY_RECORD, dismissedIds: [] };
+}
+/**
+ * Persist DeliveryRecord atomically via temp-file + rename.
+ */
+export function saveDeliveryRecord(ledgerPath, record) {
+    const dir = path.dirname(ledgerPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(os.tmpdir(), `martin-dlv-${process.pid}-${Date.now()}.json`);
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2), "utf8");
+    fs.renameSync(tmp, ledgerPath);
+}
+/**
+ * Returns true when the cooldown period has elapsed and the message should be shown.
+ * Clock-skew safe: if now < lastShownAtEpochMs (clock jumped back), treat cooldown as expired.
+ */
+export function isCooldownExpired(record, nowMs) {
+    const until = record.cooldownUntilEpochMs;
+    if (until === undefined)
+        return true;
+    const last = record.lastShownAtEpochMs ?? 0;
+    // If clock appears to have gone backwards past last-shown, treat as expired
+    if (nowMs < last)
+        return true;
+    return nowMs >= until;
+}
+/**
+ * Returns true if this message id was permanently dismissed.
+ */
+export function isDismissed(record, messageId) {
+    return record.dismissedIds.includes(messageId);
+}
+/**
+ * Record that a message was shown. Updates cooldown window.
+ */
+export function recordShown(record, message, nowMs) {
+    return {
+        ...record,
+        lastMessageId: message.id,
+        lastShownAtEpochMs: nowMs,
+        cooldownUntilEpochMs: nowMs + message.cooldownHours * 60 * 60 * 1000,
+    };
+}
+/**
+ * Record that a message was permanently dismissed.
+ */
+export function recordDismissed(record, messageId) {
+    if (record.dismissedIds.includes(messageId))
+        return record;
+    return {
+        ...record,
+        dismissedIds: [...record.dismissedIds, messageId],
+    };
+}
+/**
+ * Cache a fetched message for offline use.
+ */
+export function cacheMessage(record, message, nowMs) {
+    return {
+        ...record,
+        cachedMessage: message,
+        cachedAtEpochMs: nowMs,
+    };
+}
+/**
+ * Resolve the default ledger path: $MARTIN_STATE_DIR/delivery-record.json
+ * or ~/.martin/delivery-record.json.
+ */
+export function resolveDefaultLedgerPath() {
+    const stateDir = process.env["MARTIN_STATE_DIR"] ?? path.join(os.homedir(), ".martin");
+    return path.join(stateDir, "delivery-record.json");
+}

package/dist/vendor/core/delivery/message-schema.d.ts

@@ -0,0 +1,16 @@
+import { type DeliveryMessage } from "../../contracts/index.js";
+export type ValidationError = "schema_version_unknown" | "schema_unknown_kind" | "schema_unknown_action_type" | "schema_invalid_id" | "schema_invalid_date" | "schema_invalid_cooldown" | "schema_url_not_https" | "schema_text_too_long" | "schema_response_too_large" | "schema_malformed";
+export interface ParseResult {
+    ok: true;
+    message: DeliveryMessage | undefined;
+}
+export interface ParseFailure {
+    ok: false;
+    error: ValidationError;
+    detail?: string;
+}
+/**
+ * Parse and validate a raw response body from the message selection endpoint.
+ * Returns ok:false on any violation — caller must render nothing and log the error.
+ */
+export declare function parseMessageSelectionResponse(raw: string): ParseResult | ParseFailure;