@martinloop/mcp 0.2.0 → 0.2.7

package/README.md

@@ -1,43 +1,26 @@
 # @martinloop/mcp
 
-Governed MCP server for AI coding agents that need hard spend limits, verifier gates, scoped file edits, and inspectable run records.
+Governed MCP server for AI coding agents with budgets, receipts, and review-ready evidence.
 
-`@martinloop/mcp@0.2.0` exposes ten stdio tools plus read-only MCP resources, resource templates, and prompts:
+`@martinloop/mcp` is the standalone MartinLoop server for MCP hosts. It stays local-first and stdio-first, and it gives hosts one clear execution path: check readiness, plan the work, preflight the contract, run it, and inspect the result with enough evidence to decide what happens next.
 
-- `martin_doctor`
-- `martin_preflight`
-- `martin_run`
-- `martin_inspect`
-- `martin_status`
-- `martin_list_runs`
-- `martin_get_run`
-- `martin_get_attempt`
-- `martin_get_verification_results`
-- `martin_run_dossier`
-
-Recommended flow:
-
-1. `martin_doctor`
-2. `martin_preflight`
-3. `martin_run`
-4. `martin_list_runs`, `martin_run_dossier`, `martin_inspect`, or `martin_status`
-
-## What This Server Is For
+The root `martin-loop` package and the standalone `@martinloop/mcp` package move on separate version lines. For the current root release, see [MartinLoop 0.2.8 release notes](../../docs/release/OSS-0.2.8-RELEASE-NOTES.md).
 
-Use this MCP when a host already knows how to delegate coding work, but you want Martin Loop to bound that work with:
+## What is new in 0.2.7
 
-- a hard budget ceiling (`maxUsd`)
-- an attempt ceiling (`maxIterations`)
-- a total token ceiling (`maxTokens`)
-- verifier commands (`verificationPlan`)
-- allowed and denied file globs
-- persisted run records you can inspect afterward
+- better onboarding inside MCP, including guide resources for command mapping, IDE setup, and operating rules
+- a stricter governed run sequence, so `martin_run` refuses to start until matching `martin_doctor`, `martin_plan`, and `martin_preflight` receipts exist for the same task
+- cleaner review and handoff surfaces, especially around dossier, eval, and publish-readiness guidance
 
-It is a good fit for Claude Code, Codex-oriented hosts, and other MCP clients that want governed code-change execution instead of open-ended retry behavior.
+If you are installing MartinLoop for the first time, start with the root CLI first:
 
-For host-facing integration guidance, see [MCP for AI Agents](https://github.com/Keesan12/martin-loop/blob/main/docs/oss/MCP-FOR-AI-AGENTS.md).
+```sh
+npx martin-loop start
+npx martin-loop tour
+npx martin-loop doctor
+```
 
-## Quickstart
+## Install
 
 Run the packaged server directly:
 
@@ -54,176 +37,136 @@ codex mcp add martin-loop -- npx -y @martinloop/mcp
 Add it to Claude Code:
 
 ```sh
-# macOS/Linux
 claude mcp add --transport stdio --scope user martin-loop -- npx -y @martinloop/mcp
-
-# Windows PowerShell/cmd
 claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp
 ```
 
-Generic stdio configuration:
+Generate host config from the root CLI:
 
-```json
-{
-  "type": "stdio",
-  "command": "npx",
-  "args": ["-y", "@martinloop/mcp"]
-}
-```
-
-Codex host configuration in `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.martin-loop]
-command = "npx"
-args = ["-y", "@martinloop/mcp"]
+```sh
+npx martin-loop mcp print-config --host codex --transport stdio --profile minimal
+npx martin-loop mcp print-config --host claude --transport stdio --profile diagnostic
+npx martin-loop mcp print-config --host gemini --transport stdio --profile full-local
+npx martin-loop mcp print-config --host generic --transport stdio --profile github-review
 ```
 
-## Requirements
+Registry/server identifier: `io.github.Keesan12/martin-loop`
 
-- Node 20+
-- For live `martin_run` usage, either the `claude` CLI or the `codex` CLI must be available on `PATH`
-- For stub or smoke flows, set `MARTIN_LIVE=false`
+## Recommended Flow
 
-Example stub launch:
+1. `martin_doctor`
+2. `martin_plan`
+3. `martin_preflight`
+4. `martin_run`
+5. `martin_status` or `martin_logs`
+6. `martin_dossier` or the `martin_get_*` tools
+7. `martin_eval`
+8. `martin_pr_summary` or `martin_review_pr` when a host is preparing GitHub review output
 
-```sh
-MARTIN_LIVE=false npx -y @martinloop/mcp
-```
+`martin_run` is the primary coding execution entrypoint. In `0.2.7`, it hard-blocks until the matching readiness, planning, and preflight receipts exist for the same task. That keeps the default flow honest for both humans and agents.
 
-## Tool Contract
+## Profiles
 
-| Tool | Purpose | Required input | Important optional input | Notes |
-| --- | --- | --- | --- | --- |
-| `martin_doctor` | Inspect local readiness and run-store health | none | `workingDirectory`, `runsDir`, `engine` | Read-only setup lane before execution. |
-| `martin_preflight` | Normalize and validate a proposed run contract | `objective` | `workingDirectory`, `engine`, `model`, `maxUsd`, `maxIterations`, `maxTokens`, `verificationPlan`, `allowedPaths`, `deniedPaths`, `workspaceId`, `projectId` | Read-only contract check; does not execute work. |
-| `martin_run` | Run a governed coding loop | `objective` | `workingDirectory`, `engine`, `model`, `maxUsd`, `maxIterations`, `maxTokens`, `verificationPlan`, `allowedPaths`, `deniedPaths`, `workspaceId`, `projectId` | Unknown arguments are rejected. |
-| `martin_inspect` | Read a saved run record or run folder | none | `file`, `runsDir` | `file` may point to a `loop-record.json`, legacy `.jsonl`, or a run directory under the runs root. |
-| `martin_status` | Report budget pressure and stop conditions | exactly one of `loopJson`, `file`, `loopId`, or `latest` | `runsDir` | `latest` must be `true` when used. |
-| `martin_list_runs` | List recent run summaries | none | `runsDir`, `limit` | Read-only cockpit view over local run records. |
-| `martin_get_run` | Load a run dossier | exactly one of `loopId` or `latest` | `runsDir` | Read-only task, budget, cost, and attempt details. |
-| `martin_get_attempt` | Load one attempt | `loopId`, `attemptIndex` | `runsDir` | Read-only attempt evidence. |
-| `martin_get_verification_results` | Extract verifier events | exactly one of `loopId` or `latest` | `runsDir` | Read-only verifier completion summaries. |
-| `martin_run_dossier` | Build a compact review dossier | exactly one of `loopId` or `latest` | `runsDir` | Summary, budget, attempts, and verification evidence. |
+- `minimal`: read-heavy default for safe host setup
+- `diagnostic`: deeper inspection and evaluator support
+- `full-local`: includes execution and run-control helpers for local workflows
+- `github-review`: adds PR review helpers for GitHub-oriented hosts
+- `starter` and `full`: compatibility aliases that map onto the same discovery surface
 
-## Discovery Surface
+## Tools
 
-`0.2.0` adds read-only cockpit discovery for MCP hosts that support resources and prompts.
+- `martin_doctor`
+- `martin_plan`
+- `martin_preflight`
+- `martin_run`
+- `martin_inspect`
+- `martin_status`
+- `martin_logs`
+- `martin_pause`
+- `martin_cancel`
+- `martin_continue`
+- `martin_list_runs`
+- `martin_triage_runs`
+- `martin_get_run`
+- `martin_get_attempt`
+- `martin_get_verification_results`
+- `martin_run_dossier`
+- `martin_dossier`
+- `martin_eval`
+- `martin_pr_summary`
+- `martin_create_pr`
+- `martin_review_pr`
 
-Resources:
+## Resources
 
-- `martin://runs/summary`
+- `martin://server/health`
+- `martin://runs/recent`
+- `martin://runs/triage`
 - `martin://runs/latest`
-
-Resource templates:
+- `martin://runs/latest/summary`
+- `martin://runs/latest/proof-card`
+- `martin://runs/latest/budget-status`
+- `martin://runs/latest/verifier-evidence`
+- `martin://runs/latest/rollback-evidence`
+- `martin://policies/current`
+- `martin://repo/risk-map`
+- `martin://verifiers/results`
+- `martin://agent/next-step`
+- `martin://guides/mcp-usage`
+- `martin://guides/agent-start`
+- `martin://guides/command-map`
+- `martin://guides/ide-onboarding`
+- `martin://guides/operating-rules`
+- `martin://guides/publish-readiness`
+
+## Resource Templates
 
 - `martin://runs/{loopId}`
+- `martin://runs/{loopId}/dossier`
 - `martin://runs/{loopId}/attempts/{attemptIndex}`
 - `martin://runs/{loopId}/verification`
 
-Prompts:
+## Prompts
 
-- `martin_review_run`
-- `martin_triage_failures`
-
-## Safe-Root Path Model
-
-This MCP does not let tool callers point at arbitrary filesystem locations. The server resolves tool paths against safe roots chosen when the server starts.
-
-- `workingDirectory`
-  Defaults to `MARTIN_MCP_WORKSPACE_ROOT` or the server process current directory. If you pass a value, it must still resolve inside that workspace root. `.` and repo-relative subpaths are the safest choices.
-- `file`
-  For `martin_inspect` and `martin_status`, `file` resolves under the runs root, not the whole machine. Direct file targets must end in `.json` or `.jsonl`; run directories are also accepted where the tool supports them.
-- `runsDir`
-  Defaults to `MARTIN_RUNS_DIR` or `~/.martin/runs`. Passing `runsDir` only re-states or narrows that safe runs root; it does not grant access outside it.
-- `allowedPaths` and `deniedPaths`
-  These are relative glob patterns only. Absolute paths, drive-qualified paths, and patterns containing `..` are rejected.
-
-Absolute paths can work only when they still resolve inside the corresponding safe root. Escapes above the workspace or runs root are rejected.
-
-## Tool Examples
-
-### `martin_run`
-
-```json
-{
-  "objective": "Fix the auth regression and prove it with tests",
-  "engine": "codex",
-  "maxUsd": 3,
-  "maxIterations": 3,
-  "maxTokens": 20000,
-  "verificationPlan": ["pnpm test --filter auth"],
-  "workingDirectory": ".",
-  "allowedPaths": ["src/**", "tests/**"],
-  "deniedPaths": [".env*", "secrets/**"]
-}
-```
-
-### `martin_inspect`
-
-Inspect the default runs root:
-
-```json
-{}
-```
-
-Inspect a specific saved loop record under the runs root:
-
-```json
-{
-  "file": "loop-123/loop-record.json"
-}
-```
-
-Inspect a subdirectory under the configured runs root:
-
-```json
-{
-  "runsDir": "team-a"
-}
-```
-
-### `martin_status`
-
-Status for the latest saved run:
-
-```json
-{
-  "latest": true
-}
-```
-
-Status for a specific persisted loop:
-
-```json
-{
-  "loopId": "loop-123"
-}
-```
-
-Status from inline JSON:
+- `martin_start`
+- `martin_preflight`
+- `martin_triage`
+- `martin_resume`
+- `martin_prove`
+- `martin_release_check`
+- `martin_governed_coding_kickoff`
+- `martin_debug_failed_run`
+- `martin_publish_readiness_review`
+- `martin_triage_run_store`
+- `safe_bug_fix`
+- `write_tests_first`
+- `small_refactor`
+- `security_review`
+- `pr_review`
+- `release_check`
+
+## Runtime Model
+
+- `martin_run` is the primary coding execution entrypoint.
+- `martin_run` now blocks until the same task has matching `martin_doctor`, `martin_plan`, and `martin_preflight` receipts.
+- `martin_plan`, `martin_doctor`, `martin_preflight`, `martin_status`, `martin_logs`, `martin_dossier`, `martin_eval`, and the `martin_get_*` family are planning or inspection surfaces.
+- `martin_pause`, `martin_cancel`, `martin_continue`, and `martin_create_pr` are explicit follow-on control helpers and stay out of the default `minimal` profile.
+- Live runs require `claude` or `codex` on `PATH`.
+- Stub or smoke flows use `MARTIN_LIVE=false`.
+- Paths stay bounded to the configured workspace root and runs root.
+
+## Debugging
+
+Use the live handshake inspector before you blame a host config:
 
-```json
-{
-  "loopJson": "{\"loopId\":\"loop-123\",\"status\":\"completed\",\"lifecycleState\":\"completed\",\"attempts\":[],\"budget\":{\"maxUsd\":5,\"softLimitUsd\":3,\"maxIterations\":2,\"maxTokens\":1000},\"cost\":{\"actualUsd\":1.25,\"avoidedUsd\":0,\"tokensIn\":20,\"tokensOut\":10}}"
-}
+```sh
+pnpm --filter @martinloop/mcp inspect:live
 ```
 
-## Registry Metadata
-
-The registry manifest artifact for this package is `server.json`. In this repository, that manifest is authored at `packages/mcp/server.json`.
-
-Current metadata:
-
-- npm package: `@martinloop/mcp`
-- registry server name: `io.github.Keesan12/martin-loop`
-- manifest artifact name: `server.json`
-
-Official MCP Registry publication is separate from npm publication. After publishing the package to npm, run the publisher from `packages/mcp`:
+If you want the official MCP Inspector UI, point it at the same stdio launch command:
 
 ```sh
-mcp-publisher login github
-mcp-publisher publish
+npx @modelcontextprotocol/inspector --command npx --args "-y,@martinloop/mcp"
 ```
 
 ## Verification
@@ -237,14 +180,7 @@ pnpm --filter @martinloop/mcp build
 pnpm --filter @martinloop/mcp smoke:pack
 pnpm --filter @martinloop/mcp smoke:published:pack
 pnpm --filter @martinloop/mcp verify:release
-pnpm --filter @martinloop/mcp smoke:published
+pnpm --filter @martin/cli verify:hosts:live
 ```
 
-- `smoke:pack` verifies the packed tarball shape and a stdio MCP launch
-- `smoke:published:pack` verifies install-and-run behavior from a freshly packed local tarball before npm publish
-- `verify:release` checks metadata parity, release-note presence, and public MCP doc accuracy for the current package version
-- `smoke:published` verifies the npm-installed artifact through `npm install` plus live MCP tool calls
-
-## Version Notes
-
-The root `CHANGELOG.md` is repo-wide and includes non-MCP changes. For the `@martinloop/mcp` surface, prefer this README and `server.json`.
+See [MCP setup](../../docs/getting-started/mcp.md), [MCP tool reference](../../docs/reference/mcp-tools.md), and [MCP compatibility](../../docs/reference/mcp-compatibility.md).

package/dist/discovery-metadata.d.ts

@@ -0,0 +1,21 @@
+export declare const MARTIN_TOOL_NAMES: readonly ["martin_run", "martin_inspect", "martin_status", "martin_doctor", "martin_plan", "martin_preflight", "martin_logs", "martin_pause", "martin_cancel", "martin_continue", "martin_list_runs", "martin_triage_runs", "martin_get_run", "martin_get_attempt", "martin_get_verification_results", "martin_run_dossier", "martin_dossier", "martin_eval", "martin_pr_summary", "martin_create_pr", "martin_review_pr"];
+export declare const MARTIN_STARTER_TOOL_NAMES: readonly ["martin_doctor", "martin_plan", "martin_preflight", "martin_run", "martin_triage_runs", "martin_dossier"];
+export declare const MARTIN_MINIMAL_TOOL_NAMES: readonly ["martin_doctor", "martin_plan", "martin_preflight", "martin_list_runs", "martin_triage_runs", "martin_dossier"];
+export declare const MARTIN_DIAGNOSTIC_TOOL_NAMES: readonly ["martin_doctor", "martin_plan", "martin_preflight", "martin_logs", "martin_list_runs", "martin_triage_runs", "martin_get_run", "martin_get_attempt", "martin_get_verification_results", "martin_dossier", "martin_eval"];
+export declare const MARTIN_GITHUB_REVIEW_TOOL_NAMES: readonly ["martin_doctor", "martin_plan", "martin_preflight", "martin_dossier", "martin_eval", "martin_pr_summary", "martin_create_pr", "martin_review_pr"];
+export declare const MARTIN_PAID_REMOTE_TOOL_NAMES: readonly ["martin_doctor", "martin_plan", "martin_preflight", "martin_run", "martin_list_runs", "martin_triage_runs", "martin_get_run", "martin_get_verification_results", "martin_dossier", "martin_eval"];
+export declare const MARTIN_RESOURCE_URIS: readonly ["martin://server/health", "martin://runs/recent", "martin://runs/triage", "martin://runs/latest", "martin://runs/latest/summary", "martin://runs/latest/proof-card", "martin://runs/latest/budget-status", "martin://runs/latest/verifier-evidence", "martin://runs/latest/rollback-evidence", "martin://policies/current", "martin://repo/risk-map", "martin://verifiers/results", "martin://agent/next-step", "martin://guides/mcp-usage", "martin://guides/agent-start", "martin://guides/command-map", "martin://guides/ide-onboarding", "martin://guides/operating-rules", "martin://guides/publish-readiness"];
+export declare const MARTIN_RESOURCE_TEMPLATE_URIS: readonly ["martin://runs/{loopId}", "martin://runs/{loopId}/dossier", "martin://runs/{loopId}/attempts/{attemptIndex}", "martin://runs/{loopId}/verification"];
+export declare const MARTIN_PROMPT_NAMES: readonly ["martin_start", "martin_preflight", "martin_triage", "martin_resume", "martin_prove", "martin_release_check", "martin_governed_coding_kickoff", "martin_debug_failed_run", "martin_publish_readiness_review", "martin_triage_run_store", "safe_bug_fix", "write_tests_first", "small_refactor", "security_review", "pr_review", "release_check"];
+export interface MartinDiscoveryMetadata {
+    serverVersion: string;
+    discoveryRevision: string;
+    generatedAt: string;
+    toolCount: number;
+    resourceCount: number;
+    resourceTemplateCount: number;
+    promptCount: number;
+    starterTools: string[];
+    profiles: Record<string, string[]>;
+}
+export declare function buildMartinDiscoveryMetadata(serverVersion: string): MartinDiscoveryMetadata;

package/dist/discovery-metadata.js

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+export const MARTIN_TOOL_NAMES = [
+    "martin_run",
+    "martin_inspect",
+    "martin_status",
+    "martin_doctor",
+    "martin_plan",
+    "martin_preflight",
+    "martin_logs",
+    "martin_pause",
+    "martin_cancel",
+    "martin_continue",
+    "martin_list_runs",
+    "martin_triage_runs",
+    "martin_get_run",
+    "martin_get_attempt",
+    "martin_get_verification_results",
+    "martin_run_dossier",
+    "martin_dossier",
+    "martin_eval",
+    "martin_pr_summary",
+    "martin_create_pr",
+    "martin_review_pr"
+];
+export const MARTIN_STARTER_TOOL_NAMES = [
+    "martin_doctor",
+    "martin_plan",
+    "martin_preflight",
+    "martin_run",
+    "martin_triage_runs",
+    "martin_dossier"
+];
+export const MARTIN_MINIMAL_TOOL_NAMES = [
+    "martin_doctor",
+    "martin_plan",
+    "martin_preflight",
+    "martin_list_runs",
+    "martin_triage_runs",
+    "martin_dossier"
+];
+export const MARTIN_DIAGNOSTIC_TOOL_NAMES = [
+    "martin_doctor",
+    "martin_plan",
+    "martin_preflight",
+    "martin_logs",
+    "martin_list_runs",
+    "martin_triage_runs",
+    "martin_get_run",
+    "martin_get_attempt",
+    "martin_get_verification_results",
+    "martin_dossier",
+    "martin_eval"
+];
+export const MARTIN_GITHUB_REVIEW_TOOL_NAMES = [
+    "martin_doctor",
+    "martin_plan",
+    "martin_preflight",
+    "martin_dossier",
+    "martin_eval",
+    "martin_pr_summary",
+    "martin_create_pr",
+    "martin_review_pr"
+];
+export const MARTIN_PAID_REMOTE_TOOL_NAMES = [
+    "martin_doctor",
+    "martin_plan",
+    "martin_preflight",
+    "martin_run",
+    "martin_list_runs",
+    "martin_triage_runs",
+    "martin_get_run",
+    "martin_get_verification_results",
+    "martin_dossier",
+    "martin_eval"
+];
+export const MARTIN_RESOURCE_URIS = [
+    "martin://server/health",
+    "martin://runs/recent",
+    "martin://runs/triage",
+    "martin://runs/latest",
+    "martin://runs/latest/summary",
+    "martin://runs/latest/proof-card",
+    "martin://runs/latest/budget-status",
+    "martin://runs/latest/verifier-evidence",
+    "martin://runs/latest/rollback-evidence",
+    "martin://policies/current",
+    "martin://repo/risk-map",
+    "martin://verifiers/results",
+    "martin://agent/next-step",
+    "martin://guides/mcp-usage",
+    "martin://guides/agent-start",
+    "martin://guides/command-map",
+    "martin://guides/ide-onboarding",
+    "martin://guides/operating-rules",
+    "martin://guides/publish-readiness"
+];
+export const MARTIN_RESOURCE_TEMPLATE_URIS = [
+    "martin://runs/{loopId}",
+    "martin://runs/{loopId}/dossier",
+    "martin://runs/{loopId}/attempts/{attemptIndex}",
+    "martin://runs/{loopId}/verification"
+];
+export const MARTIN_PROMPT_NAMES = [
+    "martin_start",
+    "martin_preflight",
+    "martin_triage",
+    "martin_resume",
+    "martin_prove",
+    "martin_release_check",
+    "martin_governed_coding_kickoff",
+    "martin_debug_failed_run",
+    "martin_publish_readiness_review",
+    "martin_triage_run_store",
+    "safe_bug_fix",
+    "write_tests_first",
+    "small_refactor",
+    "security_review",
+    "pr_review",
+    "release_check"
+];
+export function buildMartinDiscoveryMetadata(serverVersion) {
+    const surface = {
+        tools: [...MARTIN_TOOL_NAMES],
+        resources: [...MARTIN_RESOURCE_URIS],
+        resourceTemplates: [...MARTIN_RESOURCE_TEMPLATE_URIS],
+        prompts: [...MARTIN_PROMPT_NAMES],
+        starterTools: [...MARTIN_STARTER_TOOL_NAMES],
+        profiles: {
+            minimal: [...MARTIN_MINIMAL_TOOL_NAMES],
+            diagnostic: [...MARTIN_DIAGNOSTIC_TOOL_NAMES],
+            "github-review": [...MARTIN_GITHUB_REVIEW_TOOL_NAMES],
+            "full-local": [...MARTIN_TOOL_NAMES],
+            starter: [...MARTIN_STARTER_TOOL_NAMES],
+            full: [...MARTIN_TOOL_NAMES]
+        }
+    };
+    const discoveryRevision = createHash("sha256")
+        .update(JSON.stringify({ serverVersion, surface }))
+        .digest("hex")
+        .slice(0, 12);
+    return {
+        serverVersion,
+        discoveryRevision,
+        generatedAt: new Date().toISOString(),
+        toolCount: surface.tools.length,
+        resourceCount: surface.resources.length,
+        resourceTemplateCount: surface.resourceTemplates.length,
+        promptCount: surface.prompts.length,
+        starterTools: [...surface.starterTools],
+        profiles: surface.profiles
+    };
+}

package/dist/discovery-support.d.ts

@@ -0,0 +1,62 @@
+import { type LedgerEvent, type LoopAttemptRecord, type LoopRunRecord } from "./vendor/core/index.js";
+import type { LoopArtifact, LoopAttempt, LoopEvent, LoopTask } from "./vendor/contracts/index.js";
+import { type LoopPreview, type MartinEngine } from "./tools/tool-support.js";
+type PersistedLoopTask = LoopRunRecord["task"] & Partial<Pick<LoopTask, "verificationPlan" | "verificationStack" | "repoRoot" | "allowedPaths" | "deniedPaths" | "acceptanceCriteria" | "mutationMode" | "executionProfile" | "allowedNetworkDomains" | "approvalPolicy">>;
+export type PersistedLoopAttemptRecord = LoopAttemptRecord & Partial<Pick<LoopAttempt, "attemptId" | "summary">>;
+export interface PersistedLoopRecord extends LoopRunRecord {
+    workspaceId?: string;
+    projectId?: string;
+    teamId?: string;
+    task: PersistedLoopTask;
+    attempts: PersistedLoopAttemptRecord[];
+    artifacts?: LoopArtifact[];
+    events?: LoopEvent[];
+    metadata?: Record<string, string>;
+}
+export interface MartinDiscoveryContext {
+    runsRoot: string;
+    workingDirectory: string;
+    engine?: MartinEngine;
+}
+export interface MartinVerificationSnapshot {
+    attemptId?: string;
+    attemptIndex?: number;
+    timestamp: string;
+    lifecycleState: string;
+    passed?: boolean;
+    summary?: string;
+}
+export interface MartinAttemptSnapshot {
+    loopId: string;
+    attemptIndex: number;
+    loop: LoopPreview;
+    attempt: PersistedLoopAttemptRecord;
+    verification?: MartinVerificationSnapshot;
+    warnings: string[];
+}
+export interface MartinVerificationHistorySnapshot {
+    loopId: string;
+    loop: LoopPreview;
+    verificationCount: number;
+    latestVerification?: MartinVerificationSnapshot;
+    verificationHistory: MartinVerificationSnapshot[];
+    warnings: string[];
+}
+export declare function resolveMartinDiscoveryContext(input?: {
+    runsDir?: string;
+    workingDirectory?: string;
+    engine?: MartinEngine;
+}): MartinDiscoveryContext;
+export declare function loadPersistedLoopRecord(input: {
+    loopId: string;
+    runsDir?: string;
+}): Promise<{
+    source: string;
+    loop: PersistedLoopRecord;
+}>;
+export declare function buildAttemptSnapshot(loop: PersistedLoopRecord, requestedAttemptIndex?: number, ledgerEvents?: LedgerEvent[]): MartinAttemptSnapshot;
+export declare function buildVerificationHistorySnapshot(loop: PersistedLoopRecord, ledgerEvents?: LedgerEvent[]): MartinVerificationHistorySnapshot;
+export declare function buildPersistedLoopPreview(loop: PersistedLoopRecord): LoopPreview;
+export declare function parseAttemptIndex(value: string): number;
+export declare function toPrettyJson(value: unknown): string;
+export {};