@martinloop/mcp 0.3.5 → 0.3.7

package/README.md

@@ -1,137 +1,137 @@
-# @martinloop/mcp
-
-You give an AI agent a coding task. It runs. You get a bill.
-
-But did it actually work? Did it pass your tests? How much did it spend? What files did it touch? Did it loop 47 times trying the same broken approach?
-
-You don't know. And that's the problem.
-
-## What This Does
-
-MartinLoop is a governed loop for AI coding agents. You tell it what to do, set a budget, and point it at your test suite. It runs the agent, checks your tests after every attempt, and stops when either the tests pass or the money runs out.
-
-When it's done, you get a receipt — not a vague summary, but a structured record: dollars spent, attempts made, verification results, files changed, and whether you got what you asked for.
-
-**One line to connect it:**
-
-```sh
-claude mcp add martin-loop -- npx -y @martinloop/mcp
-```
-
-That's it. Your agent now runs governed.
-
-## Real Numbers From Real Runs
-
-We tested this against live repos with real API spend:
-
-| What happened | Without MartinLoop | With MartinLoop |
-|---|---|---|
-| Budget: $1.50 task | Agent spent **$28.42** | Agent stopped at **$1.20** |
-| Failing verifier | Retried indefinitely | Stopped after 3 attempts with diagnosis |
-| CLI not on PATH | "not available on PATH" (dead stop) | Auto-discovered in AppData, kept running |
-| `bun run lint && bun run test` | Passed `&&` as a literal arg (always fails) | Routed through shell, worked |
-
-These aren't hypotheticals. The $28 overshoot happened in production testing. We fixed the circuit breaker in `0.3.8`.
-
-## Install
-
-### Claude Code
-```sh
-claude mcp add martin-loop -- npx -y @martinloop/mcp
-```
-
-Windows:
-```sh
-claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp
-```
-
-### Codex
-```sh
-codex mcp add martin-loop -- npx -y @martinloop/mcp
-```
-
-### Gemini CLI
-```sh
-gemini mcp add martin-loop -- npx -y @martinloop/mcp
-```
-
-### Any MCP Host
-```sh
-npx -y @martinloop/mcp
-```
-
-## How a Governed Run Works
-
-```
-You: "Fix the auth bug. Budget $3. Verify: npm test"
-
-  martin_doctor     →  checks CLI, auth, environment
-  martin_plan       →  scopes the task, sets constraints
-  martin_preflight  →  validates before any spend
-  martin_run        →  agent works inside budget + verifier gates
-  martin_dossier    →  receipt: $1.40 spent, 2 attempts, tests pass
-```
-
-Every attempt runs your verifier. Every dollar is tracked. If the agent drifts off-task, the scope contract catches it. If it blows the budget, the circuit breaker kills the subprocess mid-stream — not after the bill arrives.
-
-## What Your Agent Gets
-
-### 21 Tools
-
-**Run the loop:**
-`martin_doctor` `martin_plan` `martin_preflight` `martin_run` `martin_pause` `martin_continue` `martin_cancel`
-
-**Inspect results:**
-`martin_status` `martin_logs` `martin_dossier` `martin_eval` `martin_inspect` `martin_list_runs` `martin_get_run` `martin_get_attempt` `martin_get_verification_results` `martin_triage_runs`
-
-**Ship the work:**
-`martin_pr_summary` `martin_create_pr` `martin_review_pr`
-
-### 11 Read-Only Resources
-
-Your agent can pull context without side effects:
-
-`martin://runs/latest` · `martin://runs/latest/proof-card` · `martin://runs/latest/budget-status` · `martin://runs/latest/verifier-evidence` · `martin://runs/recent` · `martin://server/health` · `martin://policies/current` · `martin://agent/next-step` · `martin://guides/mcp-usage` · `martin://guides/agent-start` · `martin://repo/risk-map`
-
-### Configuration Profiles
-
-Generate host config tuned to your workflow:
-
-```sh
-npx martin-loop mcp print-config --host claude --profile minimal        # run + inspect
-npx martin-loop mcp print-config --host claude --profile diagnostic     # + doctor + triage
-npx martin-loop mcp print-config --host claude --profile full-local     # all local tools
-npx martin-loop mcp print-config --host claude --profile github-review  # + PR workflow
-```
-
-## What Happens When Things Go Wrong
-
-MartinLoop doesn't just report failures — it tries to fix them:
-
-| Failure | Old behavior | Now |
-|---|---|---|
-| CLI not on PATH | Error message, dead stop | Searches npm global, homebrew, nvm, scoop — uses what it finds |
-| Verifier says "command not found" | Generic "verification failed" | Tells the next attempt: "bun is missing, install with `npm i -g bun`" |
-| `git restore` fails mid-rollback | Throws, leaves dirty state | Retries once, falls back to `git checkout`, cleans up |
-| Invalid `--profile` flag | Crashes | Warns, falls back to `minimal`, keeps running |
-
-## Who Uses This
-
-- **Engineers running overnight agent loops** — you need a kill switch that actually works, and a receipt in the morning
-- **Teams with shared API budgets** — you need per-task spend caps, not org-wide prayer
-- **Anyone reviewing agent-generated PRs** — the dossier shows what the agent tried, what passed, and what didn't
-
-## Requirements
-
-- Node.js 20+
-- One AI coding CLI: [Claude Code](https://docs.anthropic.com/claude-code), [Codex](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google/gemini-cli)
-
-## Links
-
-- [martin-loop](https://www.npmjs.com/package/martin-loop) — the standalone CLI
-- [GitHub](https://github.com/Keesan12/martin-loop) — source and issues
-- [martinloop.com](https://martinloop.com)
-
-## License
-
-Apache-2.0
+# @martinloop/mcp
+
+You give an AI agent a coding task. It runs. You get a bill.
+
+But did it actually work? Did it pass your tests? How much did it spend? What files did it touch? Did it loop 47 times trying the same broken approach?
+
+You don't know. And that's the problem.
+
+## What This Does
+
+MartinLoop is a governed loop for AI coding agents. You tell it what to do, set a budget, and point it at your test suite. It runs the agent, checks your tests after every attempt, and stops when either the tests pass or the money runs out.
+
+When it's done, you get a receipt — not a vague summary, but a structured record: dollars spent, attempts made, verification results, files changed, and whether you got what you asked for.
+
+**One line to connect it:**
+
+```sh
+claude mcp add martin-loop -- npx -y @martinloop/mcp
+```
+
+That's it. Your agent now runs governed.
+
+## Real Numbers From Real Runs
+
+We tested this against live repos with real API spend:
+
+| What happened | Without MartinLoop | With MartinLoop |
+|---|---|---|
+| Budget: $1.50 task | Agent spent **$28.42** | Agent stopped at **$1.20** |
+| Failing verifier | Retried indefinitely | Stopped after 3 attempts with diagnosis |
+| CLI not on PATH | "not available on PATH" (dead stop) | Auto-discovered in AppData, kept running |
+| `bun run lint && bun run test` | Passed `&&` as a literal arg (always fails) | Routed through shell, worked |
+
+These aren't hypotheticals. The $28 overshoot happened in production testing. We fixed the circuit breaker in `0.3.8`.
+
+## Install
+
+### Claude Code
+```sh
+claude mcp add martin-loop -- npx -y @martinloop/mcp
+```
+
+Windows:
+```sh
+claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp
+```
+
+### Codex
+```sh
+codex mcp add martin-loop -- npx -y @martinloop/mcp
+```
+
+### Gemini CLI
+```sh
+gemini mcp add martin-loop -- npx -y @martinloop/mcp
+```
+
+### Any MCP Host
+```sh
+npx -y @martinloop/mcp
+```
+
+## How a Governed Run Works
+
+```
+You: "Fix the auth bug. Budget $3. Verify: npm test"
+
+  martin_doctor     →  checks CLI, auth, environment
+  martin_plan       →  scopes the task, sets constraints
+  martin_preflight  →  validates before any spend
+  martin_run        →  agent works inside budget + verifier gates
+  martin_dossier    →  receipt: $1.40 spent, 2 attempts, tests pass
+```
+
+Every attempt runs your verifier. Every dollar is tracked. If the agent drifts off-task, the scope contract catches it. If it blows the budget, the circuit breaker kills the subprocess mid-stream — not after the bill arrives.
+
+## What Your Agent Gets
+
+### 21 Tools
+
+**Run the loop:**
+`martin_doctor` `martin_plan` `martin_preflight` `martin_run` `martin_pause` `martin_continue` `martin_cancel`
+
+**Inspect results:**
+`martin_status` `martin_logs` `martin_dossier` `martin_eval` `martin_inspect` `martin_list_runs` `martin_get_run` `martin_get_attempt` `martin_get_verification_results` `martin_triage_runs`
+
+**Ship the work:**
+`martin_pr_summary` `martin_create_pr` `martin_review_pr`
+
+### 11 Read-Only Resources
+
+Your agent can pull context without side effects:
+
+`martin://runs/latest` · `martin://runs/latest/summary` · `martin://runs/latest/receipt` · `martin://runs/latest/proof-card` · `martin://runs/latest/budget-status` · `martin://runs/latest/verifier-evidence` · `martin://runs/recent` · `martin://server/health` · `martin://policies/current` · `martin://agent/next-step` · `martin://guides/mcp-usage` · `martin://guides/agent-start` · `martin://repo/risk-map`
+
+### Configuration Profiles
+
+Generate host config tuned to your workflow:
+
+```sh
+npx martin-loop mcp print-config --host claude --profile minimal        # run + inspect
+npx martin-loop mcp print-config --host claude --profile diagnostic     # + doctor + triage
+npx martin-loop mcp print-config --host claude --profile full-local     # all local tools
+npx martin-loop mcp print-config --host claude --profile github-review  # + PR workflow
+```
+
+## What Happens When Things Go Wrong
+
+MartinLoop doesn't just report failures — it tries to fix them:
+
+| Failure | Old behavior | Now |
+|---|---|---|
+| CLI not on PATH | Error message, dead stop | Searches npm global, homebrew, nvm, scoop — uses what it finds |
+| Verifier says "command not found" | Generic "verification failed" | Tells the next attempt: "bun is missing, install with `npm i -g bun`" |
+| `git restore` fails mid-rollback | Throws, leaves dirty state | Retries once, falls back to `git checkout`, cleans up |
+| Invalid `--profile` flag | Crashes | Warns, falls back to `minimal`, keeps running |
+
+## Who Uses This
+
+- **Engineers running overnight agent loops** — you need a kill switch that actually works, and a receipt in the morning
+- **Teams with shared API budgets** — you need per-task spend caps, not org-wide prayer
+- **Anyone reviewing agent-generated PRs** — the dossier shows what the agent tried, what passed, and what didn't
+
+## Requirements
+
+- Node.js 20+
+- One AI coding CLI: [Claude Code](https://docs.anthropic.com/claude-code), [Codex](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google/gemini-cli)
+
+## Links
+
+- [martin-loop](https://www.npmjs.com/package/martin-loop) — the standalone CLI
+- [GitHub](https://github.com/Keesan12/martin-loop) — source and issues
+- [martinloop.com](https://martinloop.com)
+
+## License
+
+Apache-2.0

package/dist/discovery-metadata.d.ts

@@ -4,7 +4,7 @@ export declare const MARTIN_MINIMAL_TOOL_NAMES: readonly ["martin_doctor", "mart
 export declare const MARTIN_DIAGNOSTIC_TOOL_NAMES: readonly ["martin_doctor", "martin_plan", "martin_preflight", "martin_estimate", "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_estimate", "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://agent/governance-status", "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_URIS: readonly ["martin://server/health", "martin://runs/recent", "martin://runs/triage", "martin://runs/latest", "martin://runs/latest/summary", "martin://runs/latest/receipt", "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://agent/governance-status", "martin://agent/memory-summary", "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 {

package/dist/discovery-metadata.js

@@ -84,6 +84,7 @@ export const MARTIN_RESOURCE_URIS = [
     "martin://runs/triage",
     "martin://runs/latest",
     "martin://runs/latest/summary",
+    "martin://runs/latest/receipt",
     "martin://runs/latest/proof-card",
     "martin://runs/latest/budget-status",
     "martin://runs/latest/verifier-evidence",
@@ -93,6 +94,7 @@ export const MARTIN_RESOURCE_URIS = [
     "martin://verifiers/results",
     "martin://agent/next-step",
     "martin://agent/governance-status",
+    "martin://agent/memory-summary",
     "martin://guides/mcp-usage",
     "martin://guides/agent-start",
     "martin://guides/command-map",

package/dist/prompts.js

@@ -247,7 +247,25 @@ async function buildKickoffPrompt(input) {
     return {
         description: appendPromptMetadata("Kick off a Martin-governed coding session with explicit scope, budgets, and verification expectations."),
         messages: [
-            textMessage("assistant", "You are helping prepare a Martin Loop coding run. Keep the plan governed: validate the environment first, plan before spend, preflight non-trivial work, preserve scope discipline, and make verification requirements explicit. Do not skip Martin commands and do not treat Martin as optional."),
+            textMessage("assistant", [
+                "You are operating under MartinLoop governance. All coding work MUST follow the governed sequence. This is not optional.",
+                "",
+                "REQUIRED before any code changes:",
+                "1. Read martin://agent/governance-status — check if this session is governed",
+                "2. Call martin_doctor — confirm environment readiness",
+                "3. Call martin_estimate — preview cost and recommended route BEFORE spending",
+                "4. Call martin_plan — scope the bounded approach",
+                "5. Call martin_preflight — validate the run contract",
+                "6. Only then call martin_run",
+                "7. Call martin_dossier — inspect what happened and generate receipt",
+                "",
+                "RULES:",
+                "- Never skip governance steps. Never claim success without verifier-backed evidence.",
+                "- Never generate fake tests. All tests must exercise real code paths with real assertions.",
+                "- Match the existing repo's code style (naming, formatting, test framework, module system).",
+                "- Budget caps are hard limits. If the estimate exceeds budget, ask the user before proceeding.",
+                "- Every run produces a receipt. No silent failures."
+            ].join("\n")),
             embeddedResourceMessage("assistant", firstResourceContent(usageGuide)),
             embeddedResourceMessage("assistant", firstResourceContent(commandMapGuide)),
             embeddedResourceMessage("assistant", firstResourceContent(operatingRulesGuide)),

package/dist/resources.d.ts

@@ -6,6 +6,7 @@ export declare const MARTIN_STATIC_RESOURCE_URIS: {
     readonly triage: "martin://runs/triage";
     readonly latestRun: "martin://runs/latest";
     readonly latestSummary: "martin://runs/latest/summary";
+    readonly latestReceipt: "martin://runs/latest/receipt";
     readonly latestProofCard: "martin://runs/latest/proof-card";
     readonly latestBudgetStatus: "martin://runs/latest/budget-status";
     readonly latestVerifierEvidence: "martin://runs/latest/verifier-evidence";
@@ -21,6 +22,8 @@ export declare const MARTIN_STATIC_RESOURCE_URIS: {
     readonly operatingRulesGuide: "martin://guides/operating-rules";
     readonly publishReadinessGuide: "martin://guides/publish-readiness";
     readonly governanceStatus: "martin://agent/governance-status";
+    readonly memorySummary: "martin://agent/memory-summary";
+    readonly modeStatus: "martin://agent/mode-status";
 };
 export declare const MARTIN_RESOURCE_TEMPLATES: ResourceTemplate[];
 export declare const MARTIN_STATIC_RESOURCES: Resource[];

package/dist/resources.js

@@ -1,3 +1,6 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
 import { buildMartinDiscoveryMetadata } from "./discovery-metadata.js";
 import { MARTIN_MCP_PACKAGE_VERSION } from "./package-version.js";
 import { inspectLoopTool } from "./tools/inspect-loop.js";
@@ -6,6 +9,7 @@ import { martinTriageRunsTool } from "./tools/triage-runs.js";
 import { martinRunDossierTool } from "./tools/run-dossier.js";
 import { inspectRepoSignals, buildPolicyPackDefinition, buildRepoRiskMap } from "./tools/workflow-governance.js";
 import { readWorkflowState } from "./workflow-state.js";
+import { readMemoryEntries, buildMemorySummary } from "./vendor/core/index.js";
 import { buildAttemptSnapshot, buildPersistedLoopPreview, buildVerificationHistorySnapshot, parseAttemptIndex, resolveMartinDiscoveryContext, toPrettyJson } from "./discovery-support.js";
 import { loadDetailedLoopRecord, readLedgerEvents } from "./tools/run-store.js";
 import { invalidArgumentsError, MartinToolError } from "./tools/tool-errors.js";
@@ -15,6 +19,7 @@ export const MARTIN_STATIC_RESOURCE_URIS = {
     triage: "martin://runs/triage",
     latestRun: "martin://runs/latest",
     latestSummary: "martin://runs/latest/summary",
+    latestReceipt: "martin://runs/latest/receipt",
     latestProofCard: "martin://runs/latest/proof-card",
     latestBudgetStatus: "martin://runs/latest/budget-status",
     latestVerifierEvidence: "martin://runs/latest/verifier-evidence",
@@ -29,7 +34,9 @@ export const MARTIN_STATIC_RESOURCE_URIS = {
     ideOnboardingGuide: "martin://guides/ide-onboarding",
     operatingRulesGuide: "martin://guides/operating-rules",
     publishReadinessGuide: "martin://guides/publish-readiness",
-    governanceStatus: "martin://agent/governance-status"
+    governanceStatus: "martin://agent/governance-status",
+    memorySummary: "martin://agent/memory-summary",
+    modeStatus: "martin://agent/mode-status"
 };
 export const MARTIN_RESOURCE_TEMPLATES = [
     {
@@ -93,11 +100,18 @@ export const MARTIN_STATIC_RESOURCES = [
         description: "Compact latest-run summary for context-constrained agents.",
         mimeType: "application/json"
     },
+    {
+        uri: MARTIN_STATIC_RESOURCE_URIS.latestReceipt,
+        name: "martin_latest_receipt",
+        title: "Martin Latest Receipt",
+        description: "Canonical structured receipt for the latest run; use this before optional proof-card views.",
+        mimeType: "application/json"
+    },
     {
         uri: MARTIN_STATIC_RESOURCE_URIS.latestProofCard,
         name: "martin_latest_proof_card",
         title: "Martin Latest Proof Card",
-        description: "Small Markdown receipt showing what happened, what Martin prevented, and the next safe action.",
+        description: "Optional Markdown proof view derived from the latest receipt.",
         mimeType: "text/markdown"
     },
     {
@@ -197,6 +211,20 @@ export const MARTIN_STATIC_RESOURCES = [
         title: "Martin Governance Status",
         description: "Proactive governance status: whether work is governed, budget remaining, unreceipted runs, and recommended next action. Read this before starting agent work.",
         mimeType: "application/json"
+    },
+    {
+        uri: MARTIN_STATIC_RESOURCE_URIS.memorySummary,
+        name: "martin_memory_summary",
+        title: "Martin Memory Summary",
+        description: "MartinLoop persistent memory: user preferences, consent signals, budget patterns, and behavioral observations aggregated over time. Read at session start to personalize recommendations.",
+        mimeType: "application/json"
+    },
+    {
+        uri: MARTIN_STATIC_RESOURCE_URIS.modeStatus,
+        name: "martin_mode_status",
+        title: "Martin Mode Status",
+        description: "Current Martin working mode (auto, plan, or edits) and consent state. Read before starting agent work to confirm whether the user expects autonomous execution, plan approval, or per-edit review.",
+        mimeType: "application/json"
     }
 ];
 export function listMartinResources() {
@@ -232,6 +260,8 @@ export async function readMartinResource(input) {
             return jsonResource(input.uri, withDiscoveryMetadata(await martinRunDossierTool({ latest: true, runsDir: context.runsRoot }), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.latestSummary:
             return jsonResource(input.uri, withDiscoveryMetadata(await buildLatestSummaryResource(context.runsRoot), context.runsRoot));
+        case MARTIN_STATIC_RESOURCE_URIS.latestReceipt:
+            return jsonResource(input.uri, withDiscoveryMetadata(await buildLatestReceiptResource(context.runsRoot), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.latestProofCard:
             return textResource(input.uri, "text/markdown", await buildLatestProofCardResource(context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.latestBudgetStatus:
@@ -246,8 +276,15 @@ export async function readMartinResource(input) {
             return jsonResource(input.uri, withDiscoveryMetadata(buildRepoRiskMap(inspectRepoSignals(context.workingDirectory)), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.verifierResults:
             return jsonResource(input.uri, withDiscoveryMetadata(await buildLatestVerifierEvidenceResource(context.runsRoot), context.runsRoot));
+        case MARTIN_STATIC_RESOURCE_URIS.memorySummary: {
+            const entries = await readMemoryEntries(context.runsRoot);
+            const summary = buildMemorySummary(entries);
+            return jsonResource(input.uri, withDiscoveryMetadata(summary, context.runsRoot));
+        }
         case MARTIN_STATIC_RESOURCE_URIS.governanceStatus:
             return jsonResource(input.uri, withDiscoveryMetadata(await buildGovernanceStatusResource(context.runsRoot, context.workingDirectory), context.runsRoot));
+        case MARTIN_STATIC_RESOURCE_URIS.modeStatus:
+            return jsonResource(input.uri, withDiscoveryMetadata(await buildModeStatusResource(), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.agentNextStep:
             return jsonResource(input.uri, withDiscoveryMetadata(await buildAgentNextStepResource(context.runsRoot), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.mcpUsageGuide:
@@ -396,6 +433,44 @@ async function buildLatestSummaryResource(runsRoot) {
         warnings: [...latest.detail.warnings, ...verification.warnings]
     };
 }
+async function buildLatestReceiptResource(runsRoot) {
+    const latest = await loadLatestRunForCompactResource(runsRoot);
+    if (latest.empty || !latest.detail) {
+        return compactEmptyState("latest-receipt", runsRoot, latest.warnings);
+    }
+    const ledgerEvents = await readLedgerEvents(latest.detail);
+    const loop = latest.detail.loop;
+    const verification = buildVerificationHistorySnapshot(loop, ledgerEvents);
+    const preview = buildPersistedLoopPreview(loop);
+    return {
+        kind: "latest-receipt",
+        loop: preview,
+        task: {
+            title: loop.task?.title,
+            objective: loop.task?.objective,
+            verificationPlan: loop.task?.verificationPlan ?? []
+        },
+        receiptIntegrity: latest.detail.loop.receiptIntegrity,
+        verification: {
+            status: verification.latestVerification?.passed === true
+                ? "passed"
+                : verification.latestVerification?.passed === false
+                    ? "failed"
+                    : "unavailable",
+            summary: verification.latestVerification?.summary,
+            latest: verification.latestVerification,
+            count: verification.verificationCount
+        },
+        whatHappened: loop.attempts.at(-1)?.summary ?? verification.latestVerification?.summary ?? loop.task?.objective,
+        whatMartinPrevented: describePrevention(loop),
+        nextSafeAction: inferAgentNextStep(loop, verification),
+        proofCard: {
+            artifactGuaranteed: false,
+            resource: MARTIN_STATIC_RESOURCE_URIS.latestProofCard
+        },
+        warnings: [...latest.detail.warnings, ...verification.warnings]
+    };
+}
 async function buildLatestBudgetStatusResource(runsRoot) {
     const latest = await loadLatestRunForCompactResource(runsRoot);
     if (latest.empty || !latest.detail) {
@@ -526,7 +601,7 @@ async function buildLatestProofCardResource(runsRoot) {
             "",
             "What happened: Martin has not found a local run record in this runs root.",
             "What Martin prevented: unknown until a governed run executes.",
-            "Next safe action: call `martin_doctor`, run `npx martin-loop demo`, then inspect `martin://runs/latest/summary`.",
+            "Next safe action: call `martin_doctor`, run `npx martin-loop demo`, then inspect `martin://runs/latest/receipt` or `martin://runs/latest/summary`.",
             "",
             "Estimate note: no cost or token savings are claimed without run evidence.",
             ""
@@ -580,9 +655,10 @@ async function buildGovernanceStatusResource(runsRoot, workingDirectory) {
     const state = await readWorkflowState(runsRoot);
     const mcpState = state.mcp ?? {};
     const hasDoctor = Boolean(mcpState.doctor);
+    const hasEstimate = Boolean(mcpState.estimate);
     const hasPlan = Boolean(mcpState.plan);
     const hasPreflight = Boolean(mcpState.preflight);
-    const governed = hasDoctor && hasPlan && hasPreflight;
+    const governed = hasDoctor && hasEstimate && hasPlan && hasPreflight;
     const latest = await loadLatestRunForCompactResource(runsRoot);
     const budgetRemaining = (!latest.empty && latest.detail)
         ? buildPersistedLoopPreview(latest.detail.loop).remainingBudgetUsd
@@ -600,22 +676,27 @@ async function buildGovernanceStatusResource(runsRoot, workingDirectory) {
     const missingSteps = [];
     if (!hasDoctor)
         missingSteps.push("martin_doctor");
+    if (!hasEstimate)
+        missingSteps.push("martin_estimate");
     if (!hasPlan)
         missingSteps.push("martin_plan");
     if (!hasPreflight)
         missingSteps.push("martin_preflight");
     const recommendedAction = !hasDoctor
         ? "Run martin_doctor to confirm environment before any work."
-        : !hasPlan
-            ? "Run martin_plan with your objective to scope the task."
-            : !hasPreflight
-                ? "Run martin_preflight to validate the run contract before execution."
-                : "Governance complete. You may proceed with martin_run.";
+        : !hasEstimate
+            ? "Run martin_estimate to preview cost and route before spending."
+            : !hasPlan
+                ? "Run martin_plan with your objective to scope the task."
+                : !hasPreflight
+                    ? "Run martin_preflight to validate the run contract before execution."
+                    : "Governance complete. You may proceed with martin_run.";
     return {
         kind: "governance-status",
         governed,
         workflowReceipts: {
             doctor: hasDoctor ? { recordedAt: mcpState.doctor.recordedAt } : null,
+            estimate: hasEstimate ? { recordedAt: mcpState.estimate.recordedAt } : null,
             plan: hasPlan ? { recordedAt: mcpState.plan.recordedAt } : null,
             preflight: hasPreflight ? { recordedAt: mcpState.preflight.recordedAt } : null
         },
@@ -623,7 +704,7 @@ async function buildGovernanceStatusResource(runsRoot, workingDirectory) {
         budgetRemaining,
         unreceiptedRuns,
         recommendedAction,
-        requiredSequence: ["martin_doctor", "martin_plan", "martin_preflight", "martin_run", "martin_dossier"],
+        requiredSequence: ["martin_doctor", "martin_estimate", "martin_plan", "martin_preflight", "martin_run", "martin_dossier"],
         warning: governed ? undefined : "This session is NOT governed. Complete the required sequence before making changes."
     };
 }
@@ -670,14 +751,14 @@ function inferAgentNextStep(loop, verification) {
         return {
             action: "triage_before_retry",
             toolOrResource: "martin_triage_runs",
-            instruction: "Call `martin_triage_runs` and inspect the proof card before spending another attempt."
+            instruction: "Call `martin_triage_runs` and inspect the latest receipt before spending another attempt."
         };
     }
     if (loop.status === "completed" && verification.latestVerification?.passed === true) {
         return {
             action: "prove_and_share",
-            toolOrResource: MARTIN_STATIC_RESOURCE_URIS.latestProofCard,
-            instruction: "Read the proof card and full dossier before sharing or promoting the result."
+            toolOrResource: MARTIN_STATIC_RESOURCE_URIS.latestReceipt,
+            instruction: "Read the latest receipt and full dossier before sharing or promoting the result; generate a proof card only when a visual artifact is explicitly needed."
         };
     }
     return {
@@ -702,14 +783,14 @@ Martin Loop exposes governed coding workflows over MCP. Use the server health an
 2. Use the \`martin_governed_coding_kickoff\` prompt to frame a governed coding request.
 3. Call \`martin_preflight\` before \`martin_run\` when the task or safety envelope is non-trivial.
 4. After execution, inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`martin://runs/{loopId}\`, and \`martin://runs/{loopId}/verification\`.
-5. For low-context agents, read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, or \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\` before asking for full JSON.
+5. For low-context agents, read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, or \`${MARTIN_STATIC_RESOURCE_URIS.latestReceipt}\` before asking for full JSON. Treat \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\` as an optional derived view.
 6. Read \`${MARTIN_STATIC_RESOURCE_URIS.triage}\` or call \`martin_triage_runs\` to prioritize which run needs attention first.
 7. Use \`martin_debug_failed_run\` when a loop exits failed, budget-bound, or escalated.
 
 ## Current Martin MCP Surface
 
 - Tools: \`martin_run\`, \`martin_inspect\`, \`martin_status\`, \`martin_doctor\`, \`martin_preflight\`, \`martin_list_runs\`, \`martin_triage_runs\`, \`martin_get_run\`, \`martin_get_attempt\`, \`martin_get_verification_results\`, \`martin_run_dossier\`
-- Static resources: \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\`, \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`${MARTIN_STATIC_RESOURCE_URIS.triage}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestBudgetStatus}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestVerifierEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestRollbackEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.mcpUsageGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.publishReadinessGuide}\`
+- Static resources: \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\`, \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`${MARTIN_STATIC_RESOURCE_URIS.triage}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestReceipt}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestBudgetStatus}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestVerifierEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestRollbackEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.mcpUsageGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.publishReadinessGuide}\`
 - Resource templates: \`martin://runs/{loopId}\`, \`martin://runs/{loopId}/attempts/{attemptIndex}\`, \`martin://runs/{loopId}/verification\`
 - Prompts: \`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\`
 
@@ -736,7 +817,7 @@ Use Martin Loop as the local governor before you spend agent tokens or retry a f
 2. If no runs exist, call \`martin_doctor\`, then \`martin_preflight\`.
 3. If a run exists, read \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\` before reading full run JSON.
 4. If the verifier failed, use prompt \`martin_debug_failed_run\` or \`martin_triage\`.
-5. If you need a shareable receipt, read \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`.
+5. If you need a shareable receipt, read \`${MARTIN_STATIC_RESOURCE_URIS.latestReceipt}\` first. Generate or inspect \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\` only when a visual artifact is explicitly required.
 
 ## Install Profiles
 
@@ -774,7 +855,8 @@ Use this guide when an IDE or agent needs to know which Martin surface to call n
 
 - Need the smallest next action: \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`
 - Need a quick receipt: \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`
-- Need a shareable proof object: \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`
+- Need the structured receipt source of truth: \`${MARTIN_STATIC_RESOURCE_URIS.latestReceipt}\`
+- Need an optional visual proof object: \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`
 - Need a full run review: \`martin_dossier\`
 - Need to decide whether to retry: \`martin_triage_runs\`
 - Need IDE setup guidance: \`${MARTIN_STATIC_RESOURCE_URIS.ideOnboardingGuide}\`
@@ -857,6 +939,32 @@ Use this guide when reviewing whether the public MCP package is ready to publish
 - If a discovery helper exists but is not yet wired into the server, report that as an integration gap instead of treating the capability as fully shipped.
 `;
 }
+async function buildModeStatusResource() {
+    let currentMode = "auto";
+    let modeConfigured = false;
+    try {
+        const config = JSON.parse(await readFile(join(homedir(), ".martin", "config.json"), "utf8"));
+        if (config.defaultMode) {
+            currentMode = config.defaultMode;
+            modeConfigured = true;
+        }
+    }
+    catch { /* fresh install — default to auto */ }
+    return {
+        kind: "mode-status",
+        currentMode,
+        modeConfigured,
+        modes: {
+            auto: "MartinLoop governs autonomously — estimate, preflight, run, receipt without per-step approval.",
+            plan: "MartinLoop shows the proposed plan before executing. Agent waits for user approval.",
+            edits: "MartinLoop shows each file change before writing. Maximum human control."
+        },
+        agentGuidance: modeConfigured
+            ? `User has explicitly set mode to "${currentMode}". Respect this preference during the session.`
+            : "Mode not explicitly configured. Defaulting to auto. Suggest running `martin mode auto|plan|edits` to set a preference.",
+        changeCommand: "martin mode auto | plan | edits"
+    };
+}
 function withDiscoveryMetadata(value, runsRoot) {
     return {
         metadata: {