@martinloop/mcp 0.2.7 → 0.3.0

package/README.md

@@ -1,79 +1,21 @@
 # @martinloop/mcp
 
-Governed MCP server for AI coding agents with budgets, receipts, and review-ready evidence.
+Governed MCP server for AI coding agents over local stdio.
 
-`@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.
+`@martinloop/mcp@0.2.7` is the current public baseline. It gives hosts one bounded execution entrypoint, strong read-only inspection, clear next-step guidance, and a safer default MartinLoop workflow.
 
-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).
+This package stays local-first and stdio-first in the public OSS lane.
 
-## What is new in 0.2.7
+## Public release train
 
-- 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
+- `0.2.7` made the guided MCP workflow easier to adopt and harder to misuse.
+- `0.3.0` is the next adoption release.
+- `0.3.1` is planned for review and handoff controls.
+- `0.3.2` is planned for opt-in execution controls.
 
-If you are installing MartinLoop for the first time, start with the root CLI first:
+## What ships today
 
-```sh
-npx martin-loop start
-npx martin-loop tour
-npx martin-loop doctor
-```
-
-## Install
-
-Run the packaged server directly:
-
-```sh
-npx -y @martinloop/mcp
-```
-
-Add it to Codex:
-
-```sh
-codex mcp add martin-loop -- npx -y @martinloop/mcp
-```
-
-Add it to Claude Code:
-
-```sh
-claude mcp add --transport stdio --scope user martin-loop -- npx -y @martinloop/mcp
-claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp
-```
-
-Generate host config from the root CLI:
-
-```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
-```
-
-Registry/server identifier: `io.github.Keesan12/martin-loop`
-
-## Recommended Flow
-
-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
-
-`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.
-
-## Profiles
-
-- `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
-
-## Tools
+### Tools
 
 - `martin_doctor`
 - `martin_plan`
@@ -97,7 +39,7 @@ Registry/server identifier: `io.github.Keesan12/martin-loop`
 - `martin_create_pr`
 - `martin_review_pr`
 
-## Resources
+### Resources
 
 - `martin://server/health`
 - `martin://runs/recent`
@@ -114,19 +56,9 @@ Registry/server identifier: `io.github.Keesan12/martin-loop`
 - `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_start`
 - `martin_preflight`
@@ -138,40 +70,56 @@ Registry/server identifier: `io.github.Keesan12/martin-loop`
 - `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
+## Recommended flow
 
-- `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.
+1. `martin_doctor`
+2. `martin_plan`
+3. `martin_preflight`
+4. `martin_run`
+5. `martin_status` or `martin_logs`
+6. `martin_dossier`
+7. `martin_eval`
 
-## Debugging
+## Install
 
-Use the live handshake inspector before you blame a host config:
+```sh
+npx -y @martinloop/mcp
+```
+
+Codex:
 
 ```sh
-pnpm --filter @martinloop/mcp inspect:live
+codex mcp add martin-loop -- npx -y @martinloop/mcp
 ```
 
-If you want the official MCP Inspector UI, point it at the same stdio launch command:
+Claude Code:
 
 ```sh
-npx @modelcontextprotocol/inspector --command npx --args "-y,@martinloop/mcp"
+# macOS/Linux
+claude mcp add --transport stdio --scope user 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
 ```
 
-## Verification
+If you want generated host config, use the MartinLoop CLI:
 
-From the repository root:
+```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
+```
+
+## Compatibility posture
+
+- `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.
+
+## Verification
 
 ```sh
 pnpm --filter @martinloop/mcp lint
@@ -180,7 +128,4 @@ 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 @martin/cli verify:hosts:live
 ```
-
-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/package-version.d.ts

@@ -1 +1 @@
-export declare const MARTIN_MCP_PACKAGE_VERSION = "0.2.7";
+export declare const MARTIN_MCP_PACKAGE_VERSION = "0.3.0";

package/dist/package-version.js

@@ -1,3 +1,3 @@
 // Keep this aligned with packages/mcp/package.json during version bumps so the
 // runtime does not depend on package.json being present in every hosted bundle.
-export const MARTIN_MCP_PACKAGE_VERSION = "0.2.7";
+export const MARTIN_MCP_PACKAGE_VERSION = "0.3.0";

package/dist/prompts.d.ts

@@ -5,7 +5,7 @@ export interface MartinGetPromptInput {
     arguments?: Record<string, string>;
     runsDir?: string;
     workingDirectory?: string;
-    engine?: "claude" | "codex";
+    engine?: "claude" | "codex" | "gemini";
 }
 export declare function listMartinPrompts(): {
     prompts: Prompt[];

package/dist/resources.d.ts

@@ -26,7 +26,7 @@ export interface MartinReadResourceInput {
     uri: string;
     runsDir?: string;
     workingDirectory?: string;
-    engine?: "claude" | "codex";
+    engine?: "claude" | "codex" | "gemini";
 }
 export declare function listMartinResources(): {
     resources: Resource[];

package/dist/resources.js

@@ -338,7 +338,7 @@ async function loadLatestRunForCompactResource(runsRoot) {
                 empty: true,
                 warnings: [
                     "No Martin run records were found yet.",
-                    "Run `npx martin-loop demo`, then run a governed task or set MARTIN_LIVE=false for a no-spend local proof run."
+                    "Run `npx martin-loop demo`, then run `npx martin-loop run ... --proof --verify <command>` for a no-spend local proof pass."
                 ]
             };
         }
@@ -561,7 +561,7 @@ function compactEmptyState(kind, runsRoot, warnings) {
         status: "empty",
         runsRoot,
         summary: "No Martin run records are available yet.",
-        nextStep: "Run `martin doctor`, create the demo workspace with `npx martin-loop demo`, then run a no-spend stub task with MARTIN_LIVE=false.",
+        nextStep: "Run `npx martin-loop doctor`, create the demo workspace with `npx martin-loop demo`, then run `npx martin-loop run ... --proof --verify <command>`.",
         warnings
     };
 }

package/dist/server-validation.d.ts

@@ -2,6 +2,7 @@ type ToolName = "martin_run" | "martin_inspect" | "martin_status" | "martin_doct
 export { sanitizeToolErrorMessage } from "./tools/tool-errors.js";
 export declare function validateToolInput(name: ToolName, args: unknown): unknown;
 export declare function resolveSafeRepoRoot(repoRoot?: string, workspaceRoot?: string): string;
+export declare function resolveTrustedLoopRepoRoot(repoRoot?: string, workspaceRoot?: string): string;
 export declare function resolveSafeRunsJsonPath(file: string, runsRoot?: string): string;
 export declare function resolveSafeRunsPath(file: string, runsRoot?: string): string;
 export declare function resolveSafeRunsRootPath(runsRoot?: string, fallbackRunsRoot?: string): string;

package/dist/server-validation.js

@@ -57,6 +57,14 @@ export function resolveSafeRepoRoot(repoRoot, workspaceRoot = process.env.MARTIN
     });
     return candidate;
 }
+export function resolveTrustedLoopRepoRoot(repoRoot, workspaceRoot = process.env.MARTIN_MCP_WORKSPACE_ROOT ?? process.cwd()) {
+    try {
+        return resolveSafeRepoRoot(repoRoot, workspaceRoot);
+    }
+    catch {
+        throw invalidPathError("Run record points outside the trusted workspace.", "Inspect or promote only loop records that were created under the current workspace root.");
+    }
+}
 export function resolveSafeRunsJsonPath(file, runsRoot = resolveRunsRoot(process.env)) {
     const baseRoot = resolve(runsRoot);
     const candidate = resolve(baseRoot, file);

package/dist/server.js

@@ -122,6 +122,22 @@ const verificationSchema = {
         latestAttemptIndex: { type: "integer" },
         completedAt: { type: "string" },
         summary: { type: "string" },
+        steps: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: true,
+                properties: {
+                    command: { type: "string" },
+                    launched: { type: "boolean" },
+                    exitCode: { type: "integer" },
+                    timedOut: { type: "boolean" },
+                    fastFail: { type: "boolean" },
+                    detail: { type: "string" }
+                },
+                required: ["command", "launched"]
+            }
+        },
         warnings: stringArraySchema
     },
     required: ["status", "eventCount", "ledgerEventCount", "warnings"]
@@ -370,7 +386,7 @@ const doctorOutputSchema = {
                 workspaceRoot: { type: "string" },
                 workingDirectory: { type: "string" },
                 runsRoot: { type: "string" },
-                mode: { type: "string", enum: ["live", "stub"] },
+                mode: { type: "string", enum: ["live", "proof"] },
                 liveMode: { type: "boolean" }
             },
             required: ["workspaceRoot", "workingDirectory", "runsRoot", "mode", "liveMode"]
@@ -405,7 +421,7 @@ const preflightOutputSchema = {
             type: "object",
             additionalProperties: false,
             properties: {
-                mode: { type: "string", enum: ["live", "stub"] },
+                mode: { type: "string", enum: ["live", "proof"] },
                 liveMode: { type: "boolean" },
                 engineReady: { type: "boolean" }
             },

package/dist/tools/doctor.d.ts

@@ -1,3 +1,4 @@
+import { type CodexHostPlatform } from "../vendor/adapters/index.js";
 import { type LoopPreview, type MartinEngine } from "./tool-support.js";
 import { type MartinReadinessReport } from "./workflow-governance.js";
 export interface MartinDoctorInput {
@@ -17,13 +18,23 @@ export interface MartinDoctorOutput {
         workspaceRoot: string;
         workingDirectory: string;
         runsRoot: string;
-        mode: "live" | "stub";
+        mode: "live" | "proof";
         liveMode: boolean;
     };
+    scope: {
+        invocationRoot: string;
+        workingDirectory: string;
+        repoRoot: string;
+        runsRoot: string;
+    };
     engines: Record<MartinEngine, {
         available: boolean;
         detail: string;
         resolvedPath?: string;
+        hostPlatform?: CodexHostPlatform;
+        nativeInstallValid?: boolean;
+        launchReady?: boolean;
+        probeSummary?: string;
     }>;
     requestedEngine?: MartinEngine;
     runStore: {

package/dist/tools/doctor.js

@@ -1,3 +1,4 @@
+import { probeCodexLaunch, resolveCliCommandAvailability } from "../vendor/adapters/index.js";
 import { resolveRunsRoot } from "../vendor/core/index.js";
 import { resolveSafeRepoRoot, resolveSafeRunsRootPath } from "../server-validation.js";
 import { getEngineAvailability, inspectRunsRoot, resolveExecutionMode } from "./tool-support.js";
@@ -5,9 +6,17 @@ import { buildReadinessReport, inspectRepoSignals } from "./workflow-governance.
 export async function martinDoctorTool(input) {
     const workingDirectory = resolveSafeRepoRoot(input.workingDirectory);
     const runsRoot = resolveSafeRunsRootPath(input.runsDir, resolveRunsRoot(process.env));
+    const workspaceRoot = resolveSafeRepoRoot();
     const executionMode = resolveExecutionMode();
     const claude = getEngineAvailability("claude");
-    const codex = getEngineAvailability("codex");
+    const codex = resolveCliCommandAvailability("codex");
+    const gemini = getEngineAvailability("gemini");
+    const codexProbe = executionMode.liveMode && codex.available
+        ? probeCodexLaunch({
+            workingDirectory,
+            availability: codex
+        })
+        : undefined;
     const runStore = await inspectRunsRoot(runsRoot);
     const signals = inspectRepoSignals(workingDirectory);
     const readiness = buildReadinessReport(signals, runStore);
@@ -15,14 +24,17 @@ export async function martinDoctorTool(input) {
     if (!runStore.exists) {
         warnings.push("Configured Martin runs root does not exist yet.");
     }
-    if (executionMode.liveMode && !claude.available && !codex.available) {
-        warnings.push("Neither claude nor codex is currently available on PATH for live runs.");
+    if (executionMode.liveMode && !claude.available && !codex.available && !gemini.available) {
+        warnings.push("None of claude, codex, or gemini is currently available on PATH for live runs.");
     }
     if (input.engine && executionMode.liveMode) {
-        const selected = input.engine === "claude" ? claude : codex;
+        const selected = input.engine === "claude" ? claude : input.engine === "gemini" ? gemini : codex;
         if (!selected.available) {
             warnings.push(`Requested engine '${input.engine}' is not available on PATH.`);
         }
+        if (input.engine === "codex" && codexProbe && !codexProbe.ok) {
+            warnings.push(codexProbe.summary);
+        }
     }
     warnings.push(...runStore.warnings);
     const status = warnings.length === 0 ? "ok" : "degraded";
@@ -38,12 +50,18 @@ export async function martinDoctorTool(input) {
             platform: process.platform
         },
         environment: {
-            workspaceRoot: resolveSafeRepoRoot(),
+            workspaceRoot,
             workingDirectory,
             runsRoot,
             mode: executionMode.mode,
             liveMode: executionMode.liveMode
         },
+        scope: {
+            invocationRoot: workspaceRoot,
+            workingDirectory,
+            repoRoot: workingDirectory,
+            runsRoot
+        },
         engines: {
             claude: {
                 available: claude.available,
@@ -53,7 +71,20 @@ export async function martinDoctorTool(input) {
             codex: {
                 available: codex.available,
                 detail: codex.detail,
-                ...(codex.resolvedPath ? { resolvedPath: codex.resolvedPath } : {})
+                ...(codex.resolvedPath ? { resolvedPath: codex.resolvedPath } : {}),
+                ...(codexProbe
+                    ? {
+                        hostPlatform: codexProbe.diagnosis.hostPlatform,
+                        nativeInstallValid: codexProbe.diagnosis.nativeInstallValid,
+                        launchReady: codexProbe.ok,
+                        probeSummary: codexProbe.summary
+                    }
+                    : {})
+            },
+            gemini: {
+                available: gemini.available,
+                detail: gemini.detail,
+                ...(gemini.resolvedPath ? { resolvedPath: gemini.resolvedPath } : {})
             }
         },
         ...(input.engine ? { requestedEngine: input.engine } : {}),

package/dist/tools/eval.js

@@ -1,12 +1,13 @@
 import { loadDetailedLoopRecord, readLedgerEvents } from "./run-store.js";
+import { resolveTrustedLoopRepoRoot } from "../server-validation.js";
 import { buildVerificationSummary } from "./tool-support.js";
 import { assessRunRisk, inspectRepoSignals } from "./workflow-governance.js";
 export async function martinEvalTool(input) {
     const detail = await loadDetailedLoopRecord(input);
     const ledgerEvents = await readLedgerEvents(detail);
     const verification = buildVerificationSummary(detail.loop, ledgerEvents);
-    const repoRoot = detail.loop.task?.repoRoot;
-    const signals = inspectRepoSignals(repoRoot ?? process.cwd());
+    const repoRoot = resolveTrustedLoopRepoRoot(detail.loop.task?.repoRoot);
+    const signals = inspectRepoSignals(repoRoot);
     const risk = assessRunRisk({
         objective: detail.loop.task?.objective ?? detail.loop.loopId,
         allowedPaths: detail.loop.task?.allowedPaths ?? [],

package/dist/tools/get-run.d.ts

@@ -1,4 +1,5 @@
 import { buildArtifactSummary, buildBudgetSnapshot, buildCostSnapshot, buildLoopPreview, buildVerificationSummary } from "./tool-support.js";
+import type { ReceiptIntegritySummary } from "../vendor/contracts/index.js";
 export interface MartinGetRunInput {
     file?: string;
     loopId?: string;
@@ -12,6 +13,7 @@ export interface MartinGetRunOutput {
     budget: ReturnType<typeof buildBudgetSnapshot>;
     cost: ReturnType<typeof buildCostSnapshot>;
     verification: ReturnType<typeof buildVerificationSummary>;
+    receiptIntegrity: ReceiptIntegritySummary;
     artifacts: ReturnType<typeof buildArtifactSummary>;
     inspection: {
         runsRoot: string;

package/dist/tools/get-run.js

@@ -1,4 +1,4 @@
-import { buildArtifactSummary, buildBudgetSnapshot, buildCostSnapshot, buildLoopPreview, buildVerificationSummary } from "./tool-support.js";
+import { buildArtifactSummary, buildBudgetSnapshot, buildCostSnapshot, buildLoopPreview, resolveReceiptIntegrity, buildVerificationSummary } from "./tool-support.js";
 import { loadDetailedLoopRecord, readLedgerEvents } from "./run-store.js";
 export async function martinGetRunTool(input) {
     const detail = await loadDetailedLoopRecord(input);
@@ -11,6 +11,7 @@ export async function martinGetRunTool(input) {
         budget: buildBudgetSnapshot(detail.loop.budget),
         cost: buildCostSnapshot(detail.loop.cost),
         verification,
+        receiptIntegrity: resolveReceiptIntegrity(detail.loop),
         artifacts: buildArtifactSummary(detail.loop),
         inspection: {
             runsRoot: detail.runsRoot,

package/dist/tools/get-verification-results.d.ts

@@ -1,4 +1,5 @@
 import { buildLoopPreview, buildVerificationSummary } from "./tool-support.js";
+import type { ReceiptIntegritySummary } from "../vendor/contracts/index.js";
 export interface MartinGetVerificationResultsInput {
     file?: string;
     loopId?: string;
@@ -9,6 +10,7 @@ export interface MartinGetVerificationResultsOutput {
     sourceKind: "file" | "loop_id" | "latest" | "runs_root";
     loop: ReturnType<typeof buildLoopPreview>;
     verification: ReturnType<typeof buildVerificationSummary>;
+    receiptIntegrity: ReceiptIntegritySummary;
     warnings: string[];
 }
 export declare function martinGetVerificationResultsTool(input: MartinGetVerificationResultsInput): Promise<MartinGetVerificationResultsOutput>;

package/dist/tools/get-verification-results.js

@@ -1,4 +1,4 @@
-import { buildLoopPreview, buildVerificationSummary } from "./tool-support.js";
+import { buildLoopPreview, buildVerificationSummary, resolveReceiptIntegrity } from "./tool-support.js";
 import { loadDetailedLoopRecord, readLedgerEvents } from "./run-store.js";
 export async function martinGetVerificationResultsTool(input) {
     const detail = await loadDetailedLoopRecord(input);
@@ -9,6 +9,7 @@ export async function martinGetVerificationResultsTool(input) {
         sourceKind: detail.sourceKind,
         loop: buildLoopPreview(detail.loop),
         verification,
+        receiptIntegrity: resolveReceiptIntegrity(detail.loop),
         warnings: [...detail.warnings, ...verification.warnings]
     };
 }

package/dist/tools/pr-tools.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { loadDetailedLoopRecord } from "./run-store.js";
 import { martinRunDossierTool } from "./run-dossier.js";
 import { martinEvalTool } from "./eval.js";
+import { resolveTrustedLoopRepoRoot } from "../server-validation.js";
 import { detectCliAvailability } from "./tool-support.js";
 import { MartinToolError } from "./tool-errors.js";
 export async function martinPrSummaryTool(input) {
@@ -20,7 +21,7 @@ export async function martinPrSummaryTool(input) {
 export async function martinCreatePrTool(input) {
     const summary = await martinPrSummaryTool(input);
     const detail = await loadDetailedLoopRecord(input);
-    const repoRoot = detail.loop.task?.repoRoot ?? process.cwd();
+    const repoRoot = resolveTrustedLoopRepoRoot(detail.loop.task?.repoRoot);
     const branch = readGitValue(repoRoot, ["branch", "--show-current"]);
     const title = input.title?.trim() || summary.title;
     if (!input.execute) {

package/dist/tools/preflight.d.ts

@@ -1,3 +1,4 @@
+import { type CodexHostPlatform } from "../vendor/adapters/index.js";
 import { type MartinEngine } from "./tool-support.js";
 import { buildPolicyPackDefinition, type MartinPlanProposal, type MartinPolicyPack, type MartinRiskAssessment, type MartinRunContract } from "./workflow-governance.js";
 export interface MartinPreflightInput {
@@ -23,8 +24,14 @@ export interface MartinPreflightOutput {
     ok: boolean;
     summary: string;
     warnings: string[];
+    scope: {
+        invocationRoot: string;
+        workingDirectory: string;
+        repoRoot: string;
+        runsRoot: string;
+    };
     readiness: {
-        mode: "live" | "stub";
+        mode: "live" | "proof";
         liveMode: boolean;
         engineReady: boolean;
     };
@@ -52,6 +59,12 @@ export interface MartinPreflightOutput {
             detail: string;
             resolvedPath?: string;
         };
+        codexDiagnostics?: {
+            hostPlatform: CodexHostPlatform;
+            nativeInstallValid: boolean;
+            launchReady: boolean;
+            summary: string;
+        };
         runsRoot: string;
         pathScope: {
             repoRoot: string;

package/dist/tools/preflight.js

@@ -1,3 +1,4 @@
+import { probeCodexLaunch, resolveCliCommandAvailability } from "../vendor/adapters/index.js";
 import { DEFAULT_BUDGET } from "../vendor/contracts/index.js";
 import { resolveRunsRoot } from "../vendor/core/index.js";
 import { resolveSafeRepoRoot } from "../server-validation.js";
@@ -5,10 +6,17 @@ import { formatUsd, getEngineAvailability, resolveExecutionMode } from "./tool-s
 import { buildPlanProposal, buildRunContract, buildPolicyPackDefinition, inspectRepoSignals } from "./workflow-governance.js";
 export async function martinPreflightTool(input) {
     const executionMode = resolveExecutionMode();
+    const workspaceRoot = resolveSafeRepoRoot();
     const workingDirectory = resolveSafeRepoRoot(input.workingDirectory);
     const signals = inspectRepoSignals(workingDirectory);
     const engine = input.engine ?? "claude";
-    const engineAvailability = getEngineAvailability(engine);
+    const engineAvailability = engine === "codex" ? resolveCliCommandAvailability("codex") : getEngineAvailability(engine);
+    const codexProbe = executionMode.liveMode && engine === "codex" && engineAvailability.available
+        ? probeCodexLaunch({
+            workingDirectory,
+            availability: engineAvailability
+        })
+        : undefined;
     const warnings = [];
     const allowedPaths = input.allowedPaths ?? [];
     const deniedPaths = input.deniedPaths ?? [];
@@ -20,11 +28,14 @@ export async function martinPreflightTool(input) {
         ...(input.maxTokens !== undefined ? { maxTokens: input.maxTokens } : {})
     };
     if (!executionMode.liveMode) {
-        warnings.push("Stub mode is active; preflight only proves configuration shape, not live CLI readiness.");
+        warnings.push("Proof mode is active; preflight only proves configuration shape, not live CLI readiness.");
     }
     else if (!engineAvailability.available) {
         warnings.push(`Requested engine '${engine}' is not available on PATH.`);
     }
+    else if (engine === "codex" && codexProbe && !codexProbe.ok) {
+        warnings.push(codexProbe.summary);
+    }
     if ((input.verificationPlan?.length ?? 0) === 0) {
         warnings.push("No verificationPlan was provided; Martin can run, but completion confidence will be lower.");
     }
@@ -37,17 +48,27 @@ export async function martinPreflightTool(input) {
     const plan = buildPlanProposal(workingDirectory, input);
     const runContract = buildRunContract(workingDirectory, input);
     const policy = buildPolicyPackDefinition(input.policyPack, signals);
-    const ok = !executionMode.liveMode || engineAvailability.available;
+    const engineReady = !executionMode.liveMode ||
+        (engineAvailability.available && (engine !== "codex" || codexProbe?.ok !== false));
+    const ok = engineReady;
     return {
         ok,
         summary: ok
             ? `Preflight ready for ${engine} in ${workingDirectory} with a ${formatUsd(budget.maxUsd)} budget cap and ${runContract.risk.level} risk.`
-            : `Preflight blocked: ${engine} is not available for live execution.`,
+            : `Preflight blocked: ${engine === "codex" && codexProbe && !codexProbe.ok
+                ? codexProbe.summary
+                : `${engine} is not available for live execution.`}`,
         warnings,
+        scope: {
+            invocationRoot: workspaceRoot,
+            workingDirectory,
+            repoRoot: workingDirectory,
+            runsRoot: resolveRunsRoot(process.env)
+        },
         readiness: {
             mode: executionMode.mode,
             liveMode: executionMode.liveMode,
-            engineReady: !executionMode.liveMode || engineAvailability.available
+            engineReady
         },
         normalized: {
             objective: input.objective,
@@ -70,6 +91,16 @@ export async function martinPreflightTool(input) {
                     ? { resolvedPath: engineAvailability.resolvedPath }
                     : {})
             },
+            ...(codexProbe
+                ? {
+                    codexDiagnostics: {
+                        hostPlatform: codexProbe.diagnosis.hostPlatform,
+                        nativeInstallValid: codexProbe.diagnosis.nativeInstallValid,
+                        launchReady: codexProbe.ok,
+                        summary: codexProbe.summary
+                    }
+                }
+                : {}),
             runsRoot: resolveRunsRoot(process.env),
             pathScope: {
                 repoRoot: workingDirectory,