@martinloop/mcp 0.3.3 → 0.3.4

package/README.md

@@ -1,132 +1,137 @@
 # @martinloop/mcp
 
-Governed MCP server for AI coding agents over local stdio.
-
-`@martinloop/mcp@0.3.2` is the live public baseline today. `0.3.3` is the next planned public cut.
-
-This package stays local-first and stdio-first in the public OSS lane.
-
-## Public release train
-
-- `0.2.7` made the guided MCP workflow easier to adopt and harder to misuse.
-- `0.3.0` is the live adoption baseline that made host setup and onboarding clearer.
-- `0.3.1` is the live review and handoff release.
-- `0.3.2` is the live engine-validation hotfix that fixes spend-limit requests for Gemini-backed runs.
-- `0.3.3` is the planned follow-on for opt-in execution controls.
-
-## What ships today
-
-### Tools
-
-- `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
-
-- `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/publish-readiness`
-
-### 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`
-
-## Recommended flow
-
-1. `martin_doctor`
-2. `martin_plan`
-3. `martin_preflight`
-4. `martin_run`
-5. `martin_status` or `martin_logs`
-6. `martin_dossier`
-7. `martin_eval`
+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
-npx -y @martinloop/mcp
+claude mcp add martin-loop -- npx -y @martinloop/mcp
 ```
 
-Codex:
+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
 ```
 
-Claude Code:
-
+### Gemini CLI
 ```sh
-# macOS/Linux
-claude mcp add --transport stdio --scope user martin-loop -- npx -y @martinloop/mcp
+gemini mcp add martin-loop -- npx -y @martinloop/mcp
+```
 
-# Windows PowerShell or cmd.exe
-claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp
+### Any MCP Host
+```sh
+npx -y @martinloop/mcp
 ```
 
-If you want generated host config, use the MartinLoop CLI:
+## How a Governed Run Works
 
-```sh
-martin mcp print-config --host codex --transport stdio --profile minimal
-martin mcp print-config --host claude --transport stdio --profile diagnostic
-martin mcp print-config --host gemini --transport stdio --profile full-local
-martin mcp print-config --host generic --transport stdio --profile github-review
 ```
+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:
 
-## Compatibility posture
+`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`
 
-- `martin_run` remains the single execution entrypoint.
-- Read-only inspection stays available without execution-capable profiles.
-- The OSS package stays focused on local stdio workflows. Hosted and team features live on a separate product track.
-- Later `0.3.x` releases should widen adoption and guidance without blurring those boundaries.
+### Configuration Profiles
 
-## Verification
+Generate host config tuned to your workflow:
 
 ```sh
-pnpm --filter @martinloop/mcp lint
-pnpm --filter @martinloop/mcp test
-pnpm --filter @martinloop/mcp build
-pnpm --filter @martinloop/mcp smoke:pack
-pnpm --filter @martinloop/mcp smoke:published:pack
-pnpm --filter @martinloop/mcp verify:release
+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-support.js

@@ -143,7 +143,7 @@ function collectVerificationSnapshots(loop, ledgerEvents) {
     }
     snapshots.sort((left, right) => new Date(left.timestamp).getTime() - new Date(right.timestamp).getTime());
     if (hasConflictingStatusesForLatestAttempt(snapshots)) {
-        warnings.push("Verification evidence conflicts for the latest attempt; reporting status as unavailable.");
+        warnings.push("Verification evidence conflicts for the latest attempt; marking verification as contradicted.");
     }
     return { snapshots, warnings };
 }
@@ -176,7 +176,7 @@ function verificationSnapshotKey(snapshot) {
     ].join(":");
 }
 function selectLatestVerificationSnapshot(snapshots, warnings) {
-    if (warnings.includes("Verification evidence conflicts for the latest attempt; reporting status as unavailable.")) {
+    if (warnings.includes("Verification evidence conflicts for the latest attempt; marking verification as contradicted.")) {
         return undefined;
     }
     return snapshots.at(-1);

package/dist/resources.js

@@ -626,173 +626,173 @@ function inferAgentNextStep(loop, verification) {
 }
 function buildMcpUsageGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin Loop MCP Usage
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Martin Loop exposes governed coding workflows over MCP. Use the server health and run-store views to decide when to preflight, execute, inspect, or escalate.
-
-## Recommended Flow
-
-1. Read \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` or call \`martin_doctor\` to confirm the environment and run-store visibility.
-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.
-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}\`
-- 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\`
-
-## Notes
-
-- Discovery helpers read the existing Martin run-store; they do not create new schema.
-- Verification history is derived from persisted \`verification.completed\` evidence in loop records and ledgers.
-- Attempt inspection stays aligned with the same loop selectors used by \`martin_status\` and \`martin_inspect\`.
+    return `# Martin Loop MCP Usage
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Martin Loop exposes governed coding workflows over MCP. Use the server health and run-store views to decide when to preflight, execute, inspect, or escalate.
+
+## Recommended Flow
+
+1. Read \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` or call \`martin_doctor\` to confirm the environment and run-store visibility.
+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.
+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}\`
+- 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\`
+
+## Notes
+
+- Discovery helpers read the existing Martin run-store; they do not create new schema.
+- Verification history is derived from persisted \`verification.completed\` evidence in loop records and ledgers.
+- Attempt inspection stays aligned with the same loop selectors used by \`martin_status\` and \`martin_inspect\`.
 `;
 }
 function buildAgentStartGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Agent Start Here
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use Martin Loop as the local governor before you spend agent tokens or retry a failed coding loop.
-
-## Cheap Default Flow
-
-1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\` first. It is the smallest "what should I do now?" payload.
-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}\`.
-
-## Install Profiles
-
-- \`minimal\` (default): doctor, preflight, list, triage, dossier. Good for low tool bloat.
-- \`diagnostic\`: read-only inspection tools for debugging without execution.
-- \`full-local\`: all local tools, including \`martin_run\`.
-- \`github-review\`: review-oriented local profile for PR drafting and reviewer evidence.
-- \`starter\` and \`full\`: compatibility aliases.
-
-## Copy-Paste Agent Rule
-
-Before running or retrying an autonomous coding task, call Martin. Prefer compact resources first, then full dossiers only when the compact receipt says more evidence is needed. Never claim success unless Martin shows verifier-backed completion or a clear blocked reason.
+    return `# Agent Start Here
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use Martin Loop as the local governor before you spend agent tokens or retry a failed coding loop.
+
+## Cheap Default Flow
+
+1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\` first. It is the smallest "what should I do now?" payload.
+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}\`.
+
+## Install Profiles
+
+- \`minimal\` (default): doctor, preflight, list, triage, dossier. Good for low tool bloat.
+- \`diagnostic\`: read-only inspection tools for debugging without execution.
+- \`full-local\`: all local tools, including \`martin_run\`.
+- \`github-review\`: review-oriented local profile for PR drafting and reviewer evidence.
+- \`starter\` and \`full\`: compatibility aliases.
+
+## Copy-Paste Agent Rule
+
+Before running or retrying an autonomous coding task, call Martin. Prefer compact resources first, then full dossiers only when the compact receipt says more evidence is needed. Never claim success unless Martin shows verifier-backed completion or a clear blocked reason.
 `;
 }
 function buildCommandMapGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin Command Map
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use this guide when an IDE or agent needs to know which Martin surface to call next.
-
-## Default Governed Sequence
-
-1. \`martin_doctor\` — confirm environment and visibility.
-2. \`martin_plan\` — propose the bounded approach without spending a run.
-3. \`martin_preflight\` — turn the plan into an explicit contract.
-4. \`martin_run\` — execute only after the contract is safe.
-5. \`martin_dossier\` — inspect what happened and what Martin prevented.
-6. \`martin_eval\` — convert the result into review posture when needed.
-
-## When To Use Which Surface
-
-- 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 a full run review: \`martin_dossier\`
-- Need to decide whether to retry: \`martin_triage_runs\`
-- Need IDE setup guidance: \`${MARTIN_STATIC_RESOURCE_URIS.ideOnboardingGuide}\`
+    return `# Martin Command Map
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use this guide when an IDE or agent needs to know which Martin surface to call next.
+
+## Default Governed Sequence
+
+1. \`martin_doctor\` — confirm environment and visibility.
+2. \`martin_plan\` — propose the bounded approach without spending a run.
+3. \`martin_preflight\` — turn the plan into an explicit contract.
+4. \`martin_run\` — execute only after the contract is safe.
+5. \`martin_dossier\` — inspect what happened and what Martin prevented.
+6. \`martin_eval\` — convert the result into review posture when needed.
+
+## When To Use Which Surface
+
+- 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 a full run review: \`martin_dossier\`
+- Need to decide whether to retry: \`martin_triage_runs\`
+- Need IDE setup guidance: \`${MARTIN_STATIC_RESOURCE_URIS.ideOnboardingGuide}\`
 `;
 }
 function buildIdeOnboardingGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin IDE Onboarding
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use this guide after the MCP server is installed so the host naturally uses MartinLoop during real work.
-
-## IDE Default Flow
-
-1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`
-2. Read \`${MARTIN_STATIC_RESOURCE_URIS.operatingRulesGuide}\`
-3. Use prompt \`martin_start\` or \`martin_governed_coding_kickoff\`
-4. Call \`martin_doctor\`
-5. Call \`martin_plan\`
-6. Call \`martin_preflight\`
-7. Only then call \`martin_run\`
-
-## Goal
-
-MartinLoop should become the normal path for coding work in the host, not a manual extra step the human has to remember.
+    return `# Martin IDE Onboarding
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use this guide after the MCP server is installed so the host naturally uses MartinLoop during real work.
+
+## IDE Default Flow
+
+1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`
+2. Read \`${MARTIN_STATIC_RESOURCE_URIS.operatingRulesGuide}\`
+3. Use prompt \`martin_start\` or \`martin_governed_coding_kickoff\`
+4. Call \`martin_doctor\`
+5. Call \`martin_plan\`
+6. Call \`martin_preflight\`
+7. Only then call \`martin_run\`
+
+## Goal
+
+MartinLoop should become the normal path for coding work in the host, not a manual extra step the human has to remember.
 `;
 }
 function buildOperatingRulesGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin Operating Rules
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use these rules inside the IDE or MCP host as the default MartinLoop operating posture.
-
-## Required Sequence Before Real Work
-
-1. \`martin_doctor\`
-2. \`martin_plan\`
-3. \`martin_preflight\`
-4. \`martin_run\`
-5. \`martin_dossier\`
-
-## Enforcement Rule
-
-Do not execute real coding work through MartinLoop until doctor and preflight have both been used for the current task.
-
-## Completion Rule
-
-Do not claim success until MartinLoop shows verifier-backed completion or an explicit blocked reason backed by evidence.
+    return `# Martin Operating Rules
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use these rules inside the IDE or MCP host as the default MartinLoop operating posture.
+
+## Required Sequence Before Real Work
+
+1. \`martin_doctor\`
+2. \`martin_plan\`
+3. \`martin_preflight\`
+4. \`martin_run\`
+5. \`martin_dossier\`
+
+## Enforcement Rule
+
+Do not execute real coding work through MartinLoop until doctor and preflight have both been used for the current task.
+
+## Completion Rule
+
+Do not claim success until MartinLoop shows verifier-backed completion or an explicit blocked reason backed by evidence.
 `;
 }
 function buildPublishReadinessGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin MCP Publish Readiness
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use this guide when reviewing whether the public MCP package is ready to publish, promote, or hand off for registry submission.
-
-## Review Areas
-
-1. Environment health: confirm \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` shows a sane working directory, runs root, and engine availability for the target mode.
-2. Discovery surface: verify tools, prompts, static resources, and resource templates are all discoverable and named consistently.
-3. Run evidence: inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\` and, when relevant, \`martin://runs/{loopId}/verification\` to confirm verification outcomes are explainable from persisted data.
-4. Packaging lane: run the MCP package test, build, and smoke-pack commands before calling the package publish-ready.
-5. Findings-first reporting: call out missing schema, integration gaps, triage-critical runs, and verification blockers before summarizing strengths.
-
-## Evidence Expectations
-
-- Prefer concrete run IDs, attempt indices, and verification summaries over vague statements.
-- Distinguish local package validation from live registry readiness.
-- 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.
+    return `# Martin MCP Publish Readiness
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use this guide when reviewing whether the public MCP package is ready to publish, promote, or hand off for registry submission.
+
+## Review Areas
+
+1. Environment health: confirm \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` shows a sane working directory, runs root, and engine availability for the target mode.
+2. Discovery surface: verify tools, prompts, static resources, and resource templates are all discoverable and named consistently.
+3. Run evidence: inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\` and, when relevant, \`martin://runs/{loopId}/verification\` to confirm verification outcomes are explainable from persisted data.
+4. Packaging lane: run the MCP package test, build, and smoke-pack commands before calling the package publish-ready.
+5. Findings-first reporting: call out missing schema, integration gaps, triage-critical runs, and verification blockers before summarizing strengths.
+
+## Evidence Expectations
+
+- Prefer concrete run IDs, attempt indices, and verification summaries over vague statements.
+- Distinguish local package validation from live registry readiness.
+- 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.
 `;
 }
 function withDiscoveryMetadata(value, runsRoot) {

package/dist/server-validation.js

@@ -148,6 +148,7 @@ function validateRunInput(args) {
         "maxUsd",
         "maxIterations",
         "maxTokens",
+        "verifyTimeoutMs",
         "maxMinutes",
         "maxFilesChanged",
         "maxCommands",
@@ -176,6 +177,7 @@ function validateRunInput(args) {
         ...optionalPositiveNumber(record.maxUsd, "maxUsd"),
         ...optionalPositiveInteger(record.maxIterations, "maxIterations"),
         ...optionalPositiveInteger(record.maxTokens, "maxTokens"),
+        ...optionalPositiveInteger(record.verifyTimeoutMs, "verifyTimeoutMs"),
         ...optionalPositiveInteger(record.maxMinutes, "maxMinutes"),
         ...optionalPositiveInteger(record.maxFilesChanged, "maxFilesChanged"),
         ...optionalPositiveInteger(record.maxCommands, "maxCommands"),

package/dist/server.js

@@ -118,7 +118,7 @@ const verificationSchema = {
     type: "object",
     additionalProperties: true,
     properties: {
-        status: { type: "string", enum: ["passed", "failed", "unavailable"] },
+        status: { type: "string", enum: ["passed", "failed", "contradicted", "not_run"] },
         eventCount: { type: "integer" },
         ledgerEventCount: { type: "integer" },
         latestAttemptIndex: { type: "integer" },