@martinloop/mcp 0.3.6 → 0.3.8

package/dist/vendor/adapters/contracts/src/operator.d.ts

@@ -0,0 +1,19 @@
+export declare const MARTIN_ERROR_CATEGORIES: readonly ["invalid_input", "environment", "auth", "not_found", "store_unreadable", "verification_failed", "policy_blocked", "budget_exit", "transient"];
+export type MartinErrorCategory = (typeof MARTIN_ERROR_CATEGORIES)[number];
+export type MartinOutputMode = "human" | "json" | "quiet";
+export interface MartinRunSelector {
+    runsDir?: string;
+    file?: string;
+    loopId?: string;
+    latest?: boolean;
+    attemptIndex?: number;
+}
+export interface MartinRunListFilters {
+    runsDir?: string;
+    limit?: number;
+    status?: string;
+    lifecycleState?: string;
+    adapterId?: string;
+    model?: string;
+    updatedAfter?: string;
+}

package/dist/vendor/adapters/contracts/src/operator.js

@@ -0,0 +1,11 @@
+export const MARTIN_ERROR_CATEGORIES = [
+    "invalid_input",
+    "environment",
+    "auth",
+    "not_found",
+    "store_unreadable",
+    "verification_failed",
+    "policy_blocked",
+    "budget_exit",
+    "transient"
+];

package/dist/vendor/adapters/contracts/src/trajectory.d.ts

@@ -0,0 +1,26 @@
+import type { InterventionType } from "./index.js";
+export type TrajectoryStatus = "healthy" | "watch" | "drifting" | "stalled";
+export type TrajectoryConfidence = "low" | "medium" | "high";
+export type TrajectorySignalCode = "failure_oscillation" | "attempt_repetition" | "verification_stall" | "objective_drift";
+export interface TrajectorySignal {
+    code: TrajectorySignalCode;
+    severity: "low" | "medium" | "high";
+    summary: string;
+    attemptIndexes: number[];
+    matchedTerms?: string[];
+}
+export interface TrajectoryAssessment {
+    status: TrajectoryStatus;
+    confidence: TrajectoryConfidence;
+    summary: string;
+    signals: TrajectorySignal[];
+    recommendedIntervention?: InterventionType;
+}
+export interface CircuitBreakDecision {
+    shouldStop: boolean;
+    reason: string;
+    assessment: TrajectoryAssessment;
+    recommendedIntervention?: InterventionType;
+}
+export declare function cloneTrajectoryAssessment(assessment: TrajectoryAssessment): TrajectoryAssessment;
+export declare function cloneCircuitBreakDecision(decision: CircuitBreakDecision): CircuitBreakDecision;

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

@@ -0,0 +1,27 @@
+export function cloneTrajectoryAssessment(assessment) {
+    return {
+        status: assessment.status,
+        confidence: assessment.confidence,
+        summary: assessment.summary,
+        ...(assessment.recommendedIntervention
+            ? { recommendedIntervention: assessment.recommendedIntervention }
+            : {}),
+        signals: assessment.signals.map((signal) => ({
+            code: signal.code,
+            severity: signal.severity,
+            summary: signal.summary,
+            attemptIndexes: [...signal.attemptIndexes],
+            ...(signal.matchedTerms ? { matchedTerms: [...signal.matchedTerms] } : {})
+        }))
+    };
+}
+export function cloneCircuitBreakDecision(decision) {
+    return {
+        shouldStop: decision.shouldStop,
+        reason: decision.reason,
+        assessment: cloneTrajectoryAssessment(decision.assessment),
+        ...(decision.recommendedIntervention
+            ? { recommendedIntervention: decision.recommendedIntervention }
+            : {})
+    };
+}

package/dist/vendor/adapters/core/src/compiler.d.ts

@@ -0,0 +1,52 @@
+import type { LoopAttempt, LoopTask } from "../../../contracts/index.js";
+/**
+ * The subset of MartinAdapterRequest fields needed by the prompt packet
+ * compiler. Defined here (not in index.ts) to avoid circular imports:
+ *   index.ts → ./persistence/index.js → ./persistence/compiler.js → ./compiler.js (no cycle)
+ */
+export interface CompilerAdapterRequest {
+    loopId: string;
+    attemptId: string;
+    context: {
+        taskTitle: string;
+        objective: string;
+        verificationPlan: string[];
+        verificationStack?: LoopTask["verificationStack"];
+        mutationMode?: LoopTask["mutationMode"];
+        repoRoot?: string;
+        allowedPaths?: string[];
+        deniedPaths?: string[];
+        acceptanceCriteria?: string[];
+        focus: string;
+        remainingBudgetUsd: number;
+        remainingIterations: number;
+        remainingTokens: number;
+    };
+    previousAttempts: LoopAttempt[];
+}
+export interface PromptPacket {
+    loopId: string;
+    attemptNumber: number;
+    contract: {
+        objective: string;
+        verificationPlan: string[];
+        mutationMode?: LoopTask["mutationMode"];
+        allowedPaths?: string[];
+        deniedPaths?: string[];
+        acceptanceCriteria?: string[];
+    };
+    /** Prior failure/intervention pairs as "failureClass:intervention" strings. */
+    priorFailurePatterns: string[];
+    guidance: string;
+    budgetEnvelope: {
+        remainingBudgetUsd: number;
+        remainingIterations: number;
+        remainingTokens: number;
+    };
+}
+/**
+ * Compiles a deterministic PromptPacket from a MartinAdapterRequest.
+ * This is the context compiler — takes structured request state and produces
+ * a reconstructable packet (no chat history required).
+ */
+export declare function compilePromptPacket(request: CompilerAdapterRequest): PromptPacket;

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

@@ -0,0 +1,52 @@
+import { redactSecretsFromText } from "./leash.js";
+/**
+ * Compiles a deterministic PromptPacket from a MartinAdapterRequest.
+ * This is the context compiler — takes structured request state and produces
+ * a reconstructable packet (no chat history required).
+ */
+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."
+        ];
+    if (request.context.allowedPaths && request.context.allowedPaths.length > 0) {
+        guidanceParts.push(`Allowed paths: ${request.context.allowedPaths.join(", ")}.`);
+    }
+    if (request.context.deniedPaths && request.context.deniedPaths.length > 0) {
+        guidanceParts.push(`Denied paths (never touch): ${request.context.deniedPaths.join(", ")}.`);
+    }
+    if (priorFailurePatterns.length > 0) {
+        guidanceParts.push(`Prior failure patterns: ${priorFailurePatterns.join(", ")}. Adjust strategy accordingly.`);
+    }
+    return {
+        loopId: request.loopId,
+        attemptNumber: request.previousAttempts.length + 1,
+        contract: {
+            objective: redactSecretsFromText(request.context.objective),
+            verificationPlan: request.context.verificationPlan,
+            ...(request.context.mutationMode ? { mutationMode: request.context.mutationMode } : {}),
+            ...(request.context.allowedPaths ? { allowedPaths: request.context.allowedPaths } : {}),
+            ...(request.context.deniedPaths ? { deniedPaths: request.context.deniedPaths } : {}),
+            ...(request.context.acceptanceCriteria
+                ? {
+                    acceptanceCriteria: request.context.acceptanceCriteria.map((criterion) => redactSecretsFromText(criterion))
+                }
+                : {})
+        },
+        priorFailurePatterns,
+        guidance: guidanceParts.join(" "),
+        budgetEnvelope: {
+            remainingBudgetUsd: request.context.remainingBudgetUsd,
+            remainingIterations: request.context.remainingIterations,
+            remainingTokens: request.context.remainingTokens
+        }
+    };
+}

package/dist/vendor/adapters/core/src/context-graph.d.ts

@@ -0,0 +1,3 @@
+import { type ContextGraphBuildOptions, type ContextGraphHit, type ContextGraphSnapshot, type ContextQuery } from "../../../contracts/index.js";
+export declare function buildContextGraphSnapshot(repoRoot: string, options?: ContextGraphBuildOptions): Promise<ContextGraphSnapshot>;
+export declare function queryContextGraph(snapshot: ContextGraphSnapshot, query: ContextQuery): ContextGraphHit[];

package/dist/vendor/adapters/core/src/context-graph.js

@@ -0,0 +1,371 @@
+import { readdir, readFile } from "node:fs/promises";
+import { extname, join, posix, relative, resolve } from "node:path";
+import { cloneContextGraphSnapshot } from "../../../contracts/index.js";
+const TEXT_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".json",
+    ".md",
+    ".yaml",
+    ".yml",
+    ".txt",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".sh"
+]);
+const IGNORED_DIRS = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    "coverage",
+    ".pnpm-store",
+    ".npm-cache"
+]);
+export async function buildContextGraphSnapshot(repoRoot, options = {}) {
+    const normalizedRoot = resolve(repoRoot);
+    const maxFiles = options.maxFiles ?? 600;
+    const maxFileBytes = options.maxFileBytes ?? 96_000;
+    const nodes = [];
+    const state = { count: 0, truncated: false };
+    await walkContextGraph(normalizedRoot, normalizedRoot, nodes, state, { maxFiles, maxFileBytes });
+    const edges = buildContextGraphEdges(nodes);
+    return cloneContextGraphSnapshot({
+        schemaVersion: "martin.context-graph.v1",
+        repoRoot: normalizedRoot,
+        createdAt: new Date().toISOString(),
+        nodeCount: nodes.length,
+        edgeCount: edges.length,
+        truncated: state.truncated,
+        nodes,
+        edges
+    });
+}
+export function queryContextGraph(snapshot, query) {
+    const terms = normalizeQueryTerms(query);
+    const pathPrefix = query.pathPrefix?.replace(/\\/gu, "/").replace(/^\.\/+/u, "");
+    const limit = query.limit ?? 8;
+    return snapshot.nodes
+        .filter((node) => {
+        if (query.kinds && !query.kinds.includes(node.kind)) {
+            return false;
+        }
+        if (pathPrefix && !node.path.startsWith(pathPrefix)) {
+            return false;
+        }
+        return true;
+    })
+        .map((node) => scoreContextNode(node, terms))
+        .filter((hit) => hit !== undefined)
+        .sort((left, right) => right.score - left.score || left.path.localeCompare(right.path))
+        .slice(0, limit);
+}
+async function walkContextGraph(repoRoot, currentDir, nodes, state, options) {
+    if (state.count >= options.maxFiles) {
+        state.truncated = true;
+        return;
+    }
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (state.count >= options.maxFiles) {
+            state.truncated = true;
+            break;
+        }
+        const absPath = join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRS.has(entry.name)) {
+                await walkContextGraph(repoRoot, absPath, nodes, state, options);
+            }
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        const extension = extname(entry.name).toLowerCase();
+        if (!TEXT_EXTENSIONS.has(extension)) {
+            continue;
+        }
+        const content = await readFile(absPath, "utf8").catch(() => undefined);
+        if (!content || content.length > options.maxFileBytes) {
+            continue;
+        }
+        const relPath = relative(repoRoot, absPath).replace(/\\/gu, "/");
+        nodes.push(createContextNode(relPath, content));
+        state.count += 1;
+    }
+}
+function createContextNode(path, content) {
+    const kind = classifyContextNodeKind(path);
+    return {
+        nodeId: path,
+        path,
+        kind,
+        ...(inferLanguage(path) ? { language: inferLanguage(path) } : {}),
+        sizeBytes: Buffer.byteLength(content, "utf8"),
+        headings: extractHeadings(path, content),
+        symbols: extractSymbols(content),
+        keywords: extractKeywords(path, content),
+        imports: extractImports(path, content)
+    };
+}
+function buildContextGraphEdges(nodes) {
+    const paths = new Set(nodes.map((node) => node.path));
+    const edges = [];
+    for (const node of nodes) {
+        for (const importTarget of node.imports) {
+            const resolvedTarget = resolveContextImport(node.path, importTarget, paths);
+            if (resolvedTarget) {
+                edges.push({
+                    fromNodeId: node.nodeId,
+                    toNodeId: resolvedTarget,
+                    kind: "imports"
+                });
+            }
+        }
+        if (node.kind === "document") {
+            const documentTargets = node.keywords
+                .map((keyword) => nodes.find((candidate) => candidate.path !== node.path && candidate.path.includes(keyword)))
+                .filter((candidate) => candidate !== undefined)
+                .slice(0, 3);
+            for (const target of documentTargets) {
+                edges.push({
+                    fromNodeId: node.nodeId,
+                    toNodeId: target.nodeId,
+                    kind: "documents"
+                });
+            }
+        }
+    }
+    return dedupeEdges(edges);
+}
+function scoreContextNode(node, terms) {
+    if (terms.length === 0) {
+        return {
+            nodeId: node.nodeId,
+            path: node.path,
+            kind: node.kind,
+            score: 1,
+            matchedTerms: [],
+            reasons: ["default_match"]
+        };
+    }
+    let score = 0;
+    const matchedTerms = new Set();
+    const reasons = new Set();
+    for (const term of terms) {
+        if (node.path.toLowerCase().includes(term)) {
+            score += 6;
+            matchedTerms.add(term);
+            reasons.add("path");
+        }
+        if (node.keywords.includes(term)) {
+            score += 3;
+            matchedTerms.add(term);
+            reasons.add("keyword");
+        }
+        if (node.symbols.some((symbol) => symbol.toLowerCase().includes(term))) {
+            score += 5;
+            matchedTerms.add(term);
+            reasons.add("symbol");
+        }
+        if (node.headings.some((heading) => heading.toLowerCase().includes(term))) {
+            score += 4;
+            matchedTerms.add(term);
+            reasons.add("heading");
+        }
+        if (node.imports.some((importPath) => importPath.toLowerCase().includes(term))) {
+            score += 2;
+            matchedTerms.add(term);
+            reasons.add("import");
+        }
+    }
+    if (score === 0) {
+        return undefined;
+    }
+    return {
+        nodeId: node.nodeId,
+        path: node.path,
+        kind: node.kind,
+        score,
+        matchedTerms: [...matchedTerms],
+        reasons: [...reasons]
+    };
+}
+function normalizeQueryTerms(query) {
+    const rawTerms = [
+        ...(query.text ? tokenize(query.text) : []),
+        ...((query.terms ?? []).flatMap((term) => tokenize(term)))
+    ];
+    return [...new Set(rawTerms)];
+}
+function classifyContextNodeKind(path) {
+    const extension = extname(path).toLowerCase();
+    if (path.endsWith("package.json") || path.endsWith("tsconfig.json")) {
+        return "manifest";
+    }
+    if (extension === ".md" || extension === ".txt") {
+        return "document";
+    }
+    if (extension === ".sh") {
+        return "script";
+    }
+    if (extension === ".json" || extension === ".yaml" || extension === ".yml") {
+        return "config";
+    }
+    return "source_file";
+}
+function inferLanguage(path) {
+    const extension = extname(path).toLowerCase();
+    switch (extension) {
+        case ".ts":
+        case ".tsx":
+            return "typescript";
+        case ".js":
+        case ".jsx":
+        case ".mjs":
+        case ".cjs":
+            return "javascript";
+        case ".md":
+            return "markdown";
+        case ".json":
+            return "json";
+        case ".yaml":
+        case ".yml":
+            return "yaml";
+        case ".py":
+            return "python";
+        case ".sh":
+            return "shell";
+        default:
+            return undefined;
+    }
+}
+function extractHeadings(path, content) {
+    if (extname(path).toLowerCase() !== ".md") {
+        return [];
+    }
+    return content
+        .split(/\r?\n/gu)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("#"))
+        .map((line) => line.replace(/^#+\s*/u, "").trim())
+        .filter(Boolean)
+        .slice(0, 12);
+}
+function extractSymbols(content) {
+    const out = new Set();
+    const patterns = [
+        /export\s+(?:async\s+)?function\s+([A-Za-z0-9_]+)/gu,
+        /export\s+class\s+([A-Za-z0-9_]+)/gu,
+        /export\s+const\s+([A-Za-z0-9_]+)/gu,
+        /function\s+([A-Za-z0-9_]+)/gu,
+        /class\s+([A-Za-z0-9_]+)/gu,
+        /interface\s+([A-Za-z0-9_]+)/gu,
+        /type\s+([A-Za-z0-9_]+)/gu
+    ];
+    for (const pattern of patterns) {
+        for (const match of content.matchAll(pattern)) {
+            if (match[1]) {
+                out.add(match[1]);
+            }
+        }
+    }
+    return [...out].slice(0, 16);
+}
+function extractKeywords(path, content) {
+    const out = new Set();
+    for (const part of path.split(/[\/._-]+/u)) {
+        if (part.length >= 3) {
+            out.add(part.toLowerCase());
+        }
+    }
+    for (const token of tokenize(content.split(/\r?\n/gu).slice(0, 16).join(" "))) {
+        out.add(token);
+    }
+    return [...out].slice(0, 24);
+}
+function extractImports(path, content) {
+    if (![".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].includes(extname(path).toLowerCase())) {
+        return [];
+    }
+    const imports = new Set();
+    const patterns = [
+        /from\s+["']([^"']+)["']/gu,
+        /require\(\s*["']([^"']+)["']\s*\)/gu,
+        /import\(\s*["']([^"']+)["']\s*\)/gu
+    ];
+    for (const pattern of patterns) {
+        for (const match of content.matchAll(pattern)) {
+            const candidate = match[1]?.trim();
+            if (candidate) {
+                imports.add(candidate);
+            }
+        }
+    }
+    return [...imports].slice(0, 24);
+}
+function resolveContextImport(fromPath, importPath, paths) {
+    if (!importPath.startsWith(".")) {
+        return undefined;
+    }
+    const fromDirectory = fromPath.includes("/") ? fromPath.slice(0, fromPath.lastIndexOf("/")) : "";
+    const base = posix.normalize(posix.join(fromDirectory, importPath)).replace(/^\.\//u, "");
+    const extensionlessBase = extname(base) ? base.slice(0, -extname(base).length) : base;
+    const candidates = [
+        base,
+        extensionlessBase,
+        `${extensionlessBase}.ts`,
+        `${extensionlessBase}.tsx`,
+        `${extensionlessBase}.js`,
+        `${extensionlessBase}.jsx`,
+        `${extensionlessBase}.md`,
+        `${base}.ts`,
+        `${base}.tsx`,
+        `${base}.js`,
+        `${base}.jsx`,
+        `${base}.md`,
+        `${base}/index.ts`,
+        `${base}/index.tsx`,
+        `${base}/index.js`
+    ];
+    return candidates.find((candidate) => paths.has(candidate));
+}
+function dedupeEdges(edges) {
+    const seen = new Set();
+    return edges.filter((edge) => {
+        const key = `${edge.kind}:${edge.fromNodeId}:${edge.toNodeId}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function tokenize(input) {
+    const normalized = input.replace(/([a-z0-9])([A-Z])/gu, "$1 $2").toLowerCase();
+    const stopWords = new Set([
+        "the",
+        "and",
+        "for",
+        "with",
+        "from",
+        "that",
+        "this",
+        "into",
+        "only",
+        "keep",
+        "make",
+        "loop",
+        "then",
+        "when"
+    ]);
+    return [...new Set(normalized.match(/[a-z0-9_]{3,}/gu) ?? [])].filter((term) => !stopWords.has(term));
+}

package/dist/vendor/adapters/core/src/context-integrity.d.ts

@@ -0,0 +1,26 @@
+export type ContextIntegrityVerdict = "clean" | "context_poisoning_warning" | "context_poisoning_block";
+export interface ContextIntegrityPrecheck {
+    runId: string;
+    attemptIndex: number;
+    verdict: ContextIntegrityVerdict;
+    reason?: string;
+    detectedSignals: string[];
+    analyzedChannels: {
+        system: boolean;
+        user: boolean;
+        tools: boolean;
+        history: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * T05: Context Poisoning Pre-gate.
+ * Scans untrusted input channels for authority inversion or instruction re-injection.
+ * Runs BEFORE admission control and core reasoning.
+ */
+export declare function runContextIntegrityPrecheck(runId: string, attemptIndex: number, artifactsDir: string, inputs: {
+    userPrompt?: string;
+    toolOutput?: string;
+    retrievedContext?: string;
+    history?: string;
+}): Promise<ContextIntegrityPrecheck>;

package/dist/vendor/adapters/core/src/context-integrity.js

@@ -0,0 +1,80 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const POISON_PATTERNS = [
+    /ignore\s+(?:all\s+)?previous\s+instructions/i,
+    /you\s+are\s+now\s+a\s+(?!Martin\s+Loop)/i,
+    /new\s+rule:/i,
+    /disregard\s+(?:safety|policy|guardrails)/i,
+    /override\s+system\s+authority/i,
+    /hidden\s+instruction:/i,
+    /\[system_override\]/i,
+    /\[authority_inversion\]/i
+];
+/**
+ * Identity-redefinition / persona-override patterns.
+ *
+ * These intentionally require an *override framing* (e.g. "now", "no longer",
+ * "forget", "pretend", or an explicit authority-role claim) rather than any
+ * sentence shaped like "you are X" / "I am X" — the latter matches ordinary
+ * benign text (e.g. "You are welcome to try MartinLoop") and produced
+ * false-positive hard aborts.
+ */
+const IDENTITY_REDEFINITION_PATTERNS = [
+    /\byou(?:'re|\s+are)\s+now\s+(?:a|an|the)\b(?!\s+(?:martin\s+loop|ai\s+coding\s+agent))/i,
+    /\byou(?:'re|\s+are)\s+no\s+longer\s+(?!(?:martin\s+loop|an?\s+ai)\b)/i,
+    /\bforget\s+(?:that\s+)?you(?:'re|\s+are)\s+martin\s+loop\b/i,
+    /\b(?:pretend|imagine)\s+(?:that\s+)?you(?:'re|\s+are)\b/i,
+    /\bact\s+as\s+(?:if\s+you(?:'re|\s+are)\s+)?(?:a|an)\s+(?:different|new|unrestricted|jailbroken)\b/i,
+    /\bi\s+am\s+(?:the|your)\s+(?:new\s+)?(?:system|developer|admin(?:istrator)?|root\s*user|owner|creator|operator)\b/i
+];
+/**
+ * T05: Context Poisoning Pre-gate.
+ * Scans untrusted input channels for authority inversion or instruction re-injection.
+ * Runs BEFORE admission control and core reasoning.
+ */
+export async function runContextIntegrityPrecheck(runId, attemptIndex, artifactsDir, inputs) {
+    const signals = [];
+    const analyzedChannels = {
+        system: true,
+        user: Boolean(inputs.userPrompt),
+        tools: Boolean(inputs.toolOutput),
+        history: Boolean(inputs.history)
+    };
+    const untrustedBuffer = [
+        inputs.userPrompt,
+        inputs.toolOutput,
+        inputs.retrievedContext,
+        inputs.history
+    ]
+        .filter(Boolean)
+        .join("\n---\n");
+    for (const pattern of POISON_PATTERNS) {
+        if (pattern.test(untrustedBuffer)) {
+            signals.push(`Detected poison pattern: ${pattern.toString()}`);
+        }
+    }
+    for (const pattern of IDENTITY_REDEFINITION_PATTERNS) {
+        if (pattern.test(untrustedBuffer)) {
+            signals.push("Identity redefinition attempt detected.");
+            break;
+        }
+    }
+    const verdict = signals.length > 0 ? "context_poisoning_block" : "clean";
+    const precheck = {
+        runId,
+        attemptIndex,
+        verdict,
+        reason: signals.length > 0 ? `Detected ${signals.length} poisoning signal(s).` : undefined,
+        detectedSignals: signals,
+        analyzedChannels,
+        timestamp: new Date().toISOString()
+    };
+    try {
+        await mkdir(artifactsDir, { recursive: true });
+        await writeFile(join(artifactsDir, "context-integrity-precheck.json"), JSON.stringify(precheck, null, 2), "utf8");
+    }
+    catch {
+        // non-fatal — artifact persistence is best-effort
+    }
+    return precheck;
+}