@martinloop/mcp 0.3.4 → 0.3.5

package/dist/vendor/contracts/index.d.ts

@@ -92,6 +92,29 @@ export interface LoopArtifact {
     label: string;
     uri: string;
 }
+export type CallStage = "routing" | "planning" | "execution" | "verification" | "retry" | "rollback" | "receipt";
+export type AgentRole = "manager" | "router" | "planner" | "worker" | "verifier" | "reviewer" | "fixer" | "system";
+export interface FirstDelta {
+    detected: boolean;
+    timestampMs?: number;
+    filePath?: string;
+    changeType?: "create" | "modify" | "delete" | "patch_proposed";
+    /** Elapsed ms from run start to first meaningful workspace change. */
+    timeToFirstDeltaMs?: number;
+}
+export interface RoutingEconomics {
+    preworkCostUsd: number;
+    executionCostUsd: number;
+    verificationCostUsd: number;
+    retryCostUsd: number;
+    totalCostUsd: number;
+    preworkBurnPct: number;
+    timeToFirstDeltaMs?: number;
+    firstDelta?: FirstDelta;
+    costPerAcceptedChange?: number;
+    routeRecommendation?: "same_route" | "direct_worker" | "manager_required" | "consensus_required";
+    routeRecommendationReason?: string;
+}
 export interface LoopAttempt {
     attemptId: string;
     index: number;
@@ -104,6 +127,8 @@ export interface LoopAttempt {
     intervention?: InterventionType;
     /** Actionable diagnosis from failure classification, injected into the next attempt's prompt. */
     diagnosticHint?: string;
+    /** Which stage of the run lifecycle this attempt represents. */
+    callStage?: CallStage;
 }
 export interface LoopEvent {
     eventId: string;
@@ -130,6 +155,7 @@ export interface LoopRecord {
     updatedAt: string;
     receiptScope?: ReceiptScope;
     receiptIntegrity?: ReceiptIntegritySummary;
+    routingEconomics?: RoutingEconomics;
 }
 export interface LoopRecordDraft {
     loopId?: string;
@@ -376,7 +402,8 @@ export interface RollbackOutcomeArtifact {
 export { createGovernanceSnapshot } from "./governance.js";
 export type { DestructiveActionPolicy, GovernanceSnapshot, PolicyProfile, TelemetryDestination } from "./governance.js";
 export { cloneExecutionPolicy } from "./execution-policy.js";
-export type { ExecutionPolicy, ExecutionPolicyCompileInput, ExecutionPolicyConfigInput, ExecutionPolicyDefaults, ExecutionPolicyProvenanceEntry, ExecutionPolicyRequestInput } from "./execution-policy.js";
+export type { ExecutionPolicy, ExecutionPolicyCompileInput, ExecutionPolicyConfigInput, ExecutionPolicyDefaults, ExecutionPolicyProvenanceEntry, ExecutionPolicyRequestInput, RoutingPolicy, RoutingMode } from "./execution-policy.js";
+export { DEFAULT_ROUTING_POLICY } from "./execution-policy.js";
 export { cloneContextGraphSnapshot } from "./context-graph.js";
 export type { ContextGraphBuildOptions, ContextGraphEdge, ContextGraphHit, ContextGraphNode, ContextGraphNodeKind, ContextGraphSnapshot, ContextQuery } from "./context-graph.js";
 export { cloneIdentityAttestation, cloneIdentityClaims, cloneIdentityToken } from "./identity.js";

package/dist/vendor/contracts/index.js

@@ -218,6 +218,7 @@ function hasText(value) {
 }
 export { createGovernanceSnapshot } from "./governance.js";
 export { cloneExecutionPolicy } from "./execution-policy.js";
+export { DEFAULT_ROUTING_POLICY } from "./execution-policy.js";
 export { cloneContextGraphSnapshot } from "./context-graph.js";
 export { cloneIdentityAttestation, cloneIdentityClaims, cloneIdentityToken } from "./identity.js";
 export { cloneCircuitBreakDecision, cloneTrajectoryAssessment } from "./trajectory.js";

package/dist/vendor/core/index.d.ts

@@ -2,10 +2,10 @@ import { type ApprovalPolicy, type CostProvenance, type ExecutionProfile, type F
 import { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, type ExitDecision } from "./policy.js";
 import { evaluateChangeApprovalLeash, evaluateFilesystemLeash, evaluateSecretLeash, redactSecretsFromText, resolveExecutionProfile, evaluateVerificationLeash } from "./leash.js";
 import { buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations } from "./grounding.js";
-import { captureRollbackBoundary, restoreRollbackBoundary } from "./rollback.js";
+import { captureRollbackBoundary, listAttemptChangedFilesSinceBoundary, restoreRollbackBoundary } from "./rollback.js";
 import { type RunStore } from "./persistence/index.js";
-export type { ApprovalPolicy, BudgetPreflightEstimate, BudgetSettlement, CostProvenance, EvidenceVector, ExecutionProfile, FailureClass, InterventionType, PatchDecision, PatchDecisionArtifact, PatchDecisionReasonCode, PatchScore, MutationMode, RollbackBoundaryArtifact, RollbackBoundaryStrategy, RollbackFileSnapshot, RollbackOutcomeArtifact, RollbackOutcomeStatus, PolicyPhase } from "../contracts/index.js";
-export { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, evaluateVerificationLeash, evaluateFilesystemLeash, evaluateChangeApprovalLeash, evaluateSecretLeash, resolveExecutionProfile, redactSecretsFromText, buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations, captureRollbackBoundary, restoreRollbackBoundary };
+export type { ApprovalPolicy, BudgetPreflightEstimate, BudgetSettlement, CostProvenance, EvidenceVector, ExecutionProfile, FailureClass, InterventionType, PatchDecision, PatchDecisionArtifact, PatchDecisionReasonCode, PatchScore, MutationMode, RollbackBoundaryArtifact, RollbackBoundaryStrategy, RollbackFileSnapshot, RollbackOutcomeArtifact, RollbackOutcomeStatus, PolicyPhase, CallStage, AgentRole, FirstDelta, RoutingEconomics } from "../contracts/index.js";
+export { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, evaluateVerificationLeash, evaluateFilesystemLeash, evaluateChangeApprovalLeash, evaluateSecretLeash, resolveExecutionProfile, redactSecretsFromText, buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations, captureRollbackBoundary, listAttemptChangedFilesSinceBoundary, restoreRollbackBoundary };
 export type { BudgetPreflightDecision, BudgetPreflightInput, CostGovernorState, EvidenceVectorInput, EvaluatedPatchDecision, ExitDecision, FailureAssessment, PatchDecisionInput, RecoveryDecision, RecoveryRecipe } from "./policy.js";
 export type { ResolvedExecutionProfile, SafetyLeashDecision, SafetyViolation } from "./leash.js";
 export type { GroundingScanResult, GroundingViolation, GroundingViolationKind, RepoGroundingHit, RepoGroundingIndex } from "./grounding.js";
@@ -14,6 +14,8 @@ export { createLocalIdentityAuthority, hasIdentityScope, issueIdentityToken, ver
 export type { LocalIdentityAuthority } from "./identity.js";
 export { compileExecutionPolicy } from "./policy-compiler.js";
 export { assessTrajectory, decideCircuitBreak } from "./trajectory.js";
+export { classifyRoute, evaluatePreworkBurnPolicy } from "./routing.js";
+export type { RouteDecision, RouteClassificationInput } from "./routing.js";
 export { runContextIntegrityPrecheck } from "./context-integrity.js";
 export type { ContextIntegrityPrecheck, ContextIntegrityVerdict } from "./context-integrity.js";
 export { compilePromptPacket } from "./compiler.js";

package/dist/vendor/core/index.js

@@ -1,18 +1,19 @@
-import { spawnSync } from "node:child_process";
 import { appendLoopEvent, createLoopRecord } from "../contracts/index.js";
 import { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe } from "./policy.js";
 import { evaluateChangeApprovalLeash, evaluateFilesystemLeash, evaluateSecretLeash, redactSecretsFromText, resolveExecutionProfile, evaluateVerificationLeash } from "./leash.js";
 import { buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations } from "./grounding.js";
-import { captureRollbackBoundary, restoreRollbackBoundary } from "./rollback.js";
+import { captureRollbackBoundary, listAttemptChangedFilesSinceBoundary, restoreRollbackBoundary } from "./rollback.js";
 import { compilePromptPacket } from "./compiler.js";
 import { makeLedgerEvent, resolveRunsRoot, runDir } from "./persistence/index.js";
 import { runContextIntegrityPrecheck } from "./context-integrity.js";
 import { decideCircuitBreak } from "./trajectory.js";
-export { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, evaluateVerificationLeash, evaluateFilesystemLeash, evaluateChangeApprovalLeash, evaluateSecretLeash, resolveExecutionProfile, redactSecretsFromText, buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations, captureRollbackBoundary, restoreRollbackBoundary };
+export { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, evaluateVerificationLeash, evaluateFilesystemLeash, evaluateChangeApprovalLeash, evaluateSecretLeash, resolveExecutionProfile, redactSecretsFromText, buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations, captureRollbackBoundary, listAttemptChangedFilesSinceBoundary, restoreRollbackBoundary };
 export { buildContextGraphSnapshot, queryContextGraph } from "./context-graph.js";
 export { createLocalIdentityAuthority, hasIdentityScope, issueIdentityToken, verifyIdentityToken } from "./identity.js";
 export { compileExecutionPolicy } from "./policy-compiler.js";
 export { assessTrajectory, decideCircuitBreak } from "./trajectory.js";
+// ─── Routing economics ─────────────────────────────────────────────────────
+export { classifyRoute, evaluatePreworkBurnPolicy } from "./routing.js";
 // ─── Context Integrity Pre-gate ──────────────────────────────────────────────
 export { runContextIntegrityPrecheck } from "./context-integrity.js";
 // ─── Prompt packet compiler ──────────────────────────────────────────────────
@@ -263,6 +264,13 @@ export async function runMartin(input) {
     // Explicit PolicyPhase state machine — starts at GATHER, advances per attempt
     let currentPhase = "GATHER";
     let phaseRetryCount = 0;
+    // Routing economics: track first meaningful workspace delta
+    const runStartMs = Date.now();
+    let firstDeltaDetected = false;
+    let firstDeltaTimestampMs;
+    let firstDeltaFilePath;
+    let firstDeltaChangeType;
+    let preDeltaCostUsd = 0;
     while (loop.attempts.length < loop.budget.maxIterations) {
         const distilled = distillContext(loop, {
             maxRecentAttempts: useCompressedContext ? 1 : (input.maxRecentAttempts ?? 3)
@@ -647,8 +655,22 @@ export async function runMartin(input) {
             }));
         }
         const changedFiles = tracksWorkspaceMutations
-            ? resolveChangedFiles(result, request.context.repoRoot)
+            ? resolveChangedFiles(result, request.context.repoRoot, rollbackBoundary)
             : [];
+        // Routing economics: detect first meaningful workspace delta
+        if (!firstDeltaDetected && changedFiles.length > 0) {
+            const meaningfulFile = changedFiles.find((f) => !isMartinLoopMetadata(f));
+            if (meaningfulFile) {
+                firstDeltaDetected = true;
+                firstDeltaTimestampMs = Date.now();
+                firstDeltaFilePath = meaningfulFile;
+                firstDeltaChangeType = "modify";
+                preDeltaCostUsd = roundUsd(loop.cost.actualUsd - getUsageUsd(result.usage));
+            }
+        }
+        if (!firstDeltaDetected) {
+            preDeltaCostUsd = loop.cost.actualUsd;
+        }
         // Evidence is only reliable when the adapter explicitly reported files OR git actually
         // returned a non-empty list. A repoRoot alone is insufficient — git may fail (e.g. not
         // a git repo) and silently return [], which would falsely trigger no_code_change.
@@ -1071,7 +1093,8 @@ export async function runMartin(input) {
                     payload: createRunExitPayload(decision)
                 }));
             }
-            const finalizedLoop = finalizeLoop(loop, decision, now(), idFactory);
+            const routingInput = { runStartMs, firstDeltaDetected, firstDeltaTimestampMs, firstDeltaFilePath, firstDeltaChangeType, preDeltaCostUsd };
+            const finalizedLoop = finalizeLoop(loop, decision, now(), idFactory, routingInput);
             await persistLoopRecordIfSupported(input.store, finalizedLoop);
             return {
                 loop: finalizedLoop,
@@ -1092,7 +1115,8 @@ export async function runMartin(input) {
             payload: createRunExitPayload(decision)
         }));
     }
-    const finalizedLoop = finalizeLoop(loop, decision, now(), idFactory);
+    const routingInput = { runStartMs, firstDeltaDetected, firstDeltaTimestampMs, firstDeltaFilePath, firstDeltaChangeType, preDeltaCostUsd };
+    const finalizedLoop = finalizeLoop(loop, decision, now(), idFactory, routingInput);
     await persistLoopRecordIfSupported(input.store, finalizedLoop);
     return {
         loop: finalizedLoop,
@@ -1142,19 +1166,78 @@ function safetyLeashReasonCode(decision, safetySurface) {
             return `${safetySurface}_safety_block`;
     }
 }
-function finalizeLoop(loop, decision, timestamp, idFactory) {
+function finalizeLoop(loop, decision, timestamp, idFactory, routingEconomicsInput) {
     const finalized = appendLoopEvent(loop, {
         type: "run.completed",
         lifecycleState: decision.lifecycleState,
         payload: createRunExitPayload(decision)
     }, { now: timestamp, idFactory });
+    const routingEconomics = routingEconomicsInput
+        ? buildRoutingEconomics(finalized, routingEconomicsInput, decision)
+        : undefined;
     return {
         ...finalized,
         status: decision.status,
         lifecycleState: decision.lifecycleState,
-        updatedAt: timestamp
+        updatedAt: timestamp,
+        ...(routingEconomics ? { routingEconomics } : {})
+    };
+}
+function buildRoutingEconomics(loop, input, decision) {
+    const totalCost = loop.cost.actualUsd;
+    const preworkCost = roundUsd(Math.max(input.preDeltaCostUsd, 0));
+    const executionCost = roundUsd(Math.max(totalCost - preworkCost, 0));
+    const preworkBurnPct = totalCost > 0 ? Math.round((preworkCost / totalCost) * 100) : 0;
+    const timeToFirstDeltaMs = input.firstDeltaTimestampMs
+        ? input.firstDeltaTimestampMs - input.runStartMs
+        : undefined;
+    const accepted = decision.lifecycleState === "completed";
+    // Route recommendation based on prework burn
+    let routeRecommendation;
+    let routeRecommendationReason;
+    if (preworkBurnPct > 50) {
+        routeRecommendation = "direct_worker";
+        routeRecommendationReason = `${String(preworkBurnPct)}% of spend was pre-work coordination. Use direct execution for similar tasks.`;
+    }
+    else if (preworkBurnPct > 30) {
+        routeRecommendation = "direct_worker";
+        routeRecommendationReason = `${String(preworkBurnPct)}% pre-work burn is high. Consider direct execution.`;
+    }
+    else {
+        routeRecommendation = "same_route";
+        routeRecommendationReason = `Pre-work burn at ${String(preworkBurnPct)}% is within acceptable range.`;
+    }
+    return {
+        preworkCostUsd: preworkCost,
+        executionCostUsd: executionCost,
+        verificationCostUsd: 0,
+        retryCostUsd: 0,
+        totalCostUsd: totalCost,
+        preworkBurnPct,
+        timeToFirstDeltaMs,
+        firstDelta: {
+            detected: input.firstDeltaDetected,
+            ...(input.firstDeltaTimestampMs ? { timestampMs: input.firstDeltaTimestampMs } : {}),
+            ...(input.firstDeltaFilePath ? { filePath: input.firstDeltaFilePath } : {}),
+            ...(input.firstDeltaChangeType ? { changeType: input.firstDeltaChangeType } : {}),
+            ...(timeToFirstDeltaMs !== undefined ? { timeToFirstDeltaMs } : {})
+        },
+        ...(accepted ? { costPerAcceptedChange: totalCost } : {}),
+        routeRecommendation,
+        routeRecommendationReason
     };
 }
+const MARTINLOOP_METADATA_PATTERNS = [
+    /^PROGRESS\.md$/u,
+    /^\.martin\//u,
+    /\.lock$/u,
+    /^node_modules\//u,
+    /^\.git\//u,
+    /^\.cache\//u,
+];
+function isMartinLoopMetadata(filePath) {
+    return MARTINLOOP_METADATA_PATTERNS.some((p) => p.test(filePath));
+}
 async function persistLoopRecordIfSupported(store, loop) {
     await store?.writeLoopRecord?.(loop.loopId, loop);
 }
@@ -1190,29 +1273,11 @@ function mergeCostProvenance(previous, current) {
     }
     return COST_PROVENANCE_RANK[current] < COST_PROVENANCE_RANK[previous] ? current : previous;
 }
-function resolveChangedFiles(result, repoRoot) {
+function resolveChangedFiles(result, repoRoot, rollbackBoundary) {
     if (result.execution?.changedFiles !== undefined) {
         return result.execution.changedFiles;
     }
-    if (!repoRoot) {
-        return [];
-    }
-    try {
-        const diff = spawnSync("git", ["diff", "--name-only", "HEAD", "--", "."], {
-            cwd: repoRoot,
-            encoding: "utf8"
-        });
-        if (diff.status !== 0 || typeof diff.stdout !== "string") {
-            return [];
-        }
-        return diff.stdout
-            .split(/\r?\n/u)
-            .map((entry) => entry.trim())
-            .filter(Boolean);
-    }
-    catch {
-        return [];
-    }
+    return listAttemptChangedFilesSinceBoundary({ repoRoot, boundary: rollbackBoundary });
 }
 function buildPatchDiff(result, changedFiles) {
     // Use structured diff stats to build a minimal diff header if no raw diff is available

package/dist/vendor/core/persistence/store.js

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { writeReceiptIntegrityMaterial } from "./integrity.js";
 // ─── FileRunStore implementation ─────────────────────────────────────────────
+const RUN_INDEX_FILENAME = "run-index.ndjson";
 export function resolveRunsRoot(env = process.env) {
     return env["MARTIN_RUNS_DIR"]?.trim() ??
         join(homedir(), ".martin", "runs");
@@ -84,6 +85,7 @@ export function createFileRunStore(options = {}) {
             const dir = runDir(runsRoot, runId);
             await mkdir(dir, { recursive: true });
             await writeJsonFile(join(dir, "loop-record.json"), loop);
+            await appendRunIndexRecord(runsRoot, loop);
             const ledgerRaw = await readFile(join(dir, "ledger.jsonl"), "utf8").catch(() => "");
             const ledgerEntries = ledgerRaw
                 .split(/\r?\n/u)
@@ -110,3 +112,14 @@ export function createFileRunStore(options = {}) {
 async function writeJsonFile(path, value) {
     await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
+async function appendRunIndexRecord(runsRoot, loop) {
+    const line = JSON.stringify({
+        loopId: loop.loopId,
+        workspaceId: loop.workspaceId,
+        projectId: loop.projectId,
+        status: loop.status,
+        lifecycleState: loop.lifecycleState,
+        updatedAt: loop.updatedAt
+    });
+    await appendFile(join(runsRoot, RUN_INDEX_FILENAME), `${line}\n`, "utf8");
+}

package/dist/vendor/core/policy.d.ts

@@ -74,6 +74,19 @@ export declare function evaluateCostGovernor(input: {
     cost: LoopCost;
     attemptsUsed: number;
 }): CostGovernorState;
+export interface CostPerOutcome {
+    costPerAcceptedChange: number | undefined;
+    costPerAttempt: number;
+    acceptanceRate: number;
+    wastedCoordinationUsd: number;
+}
+export declare function calculateCostPerOutcome(input: {
+    totalCostUsd: number;
+    preworkCostUsd: number;
+    attemptCount: number;
+    accepted: boolean;
+    verificationPassed: boolean;
+}): CostPerOutcome;
 export declare function inferExit(input: {
     loop: {
         budget: LoopBudget;

package/dist/vendor/core/policy.js

@@ -196,6 +196,19 @@ export function evaluateCostGovernor(input) {
         remainingTokens
     };
 }
+export function calculateCostPerOutcome(input) {
+    const costPerAttempt = input.attemptCount > 0
+        ? roundUsd(input.totalCostUsd / input.attemptCount)
+        : 0;
+    return {
+        costPerAcceptedChange: input.accepted ? input.totalCostUsd : undefined,
+        costPerAttempt,
+        acceptanceRate: input.accepted ? 1 : 0,
+        wastedCoordinationUsd: input.accepted
+            ? roundUsd(input.preworkCostUsd)
+            : roundUsd(input.totalCostUsd)
+    };
+}
 export function inferExit(input) {
     if (input.lastResult.status === "completed" && input.lastResult.verification.passed) {
         return {

package/dist/vendor/core/rollback.d.ts

@@ -1,4 +1,8 @@
 import type { PatchDecision, RollbackBoundaryArtifact, RollbackOutcomeArtifact } from "../contracts/index.js";
+export declare function listAttemptChangedFilesSinceBoundary(input: {
+    repoRoot?: string;
+    boundary?: RollbackBoundaryArtifact;
+}): string[];
 export declare function captureRollbackBoundary(input: {
     repoRoot?: string;
     capturedAt: string;

package/dist/vendor/core/rollback.js

@@ -1,6 +1,21 @@
 import { spawnSync } from "node:child_process";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, relative, resolve } from "node:path";
+export function listAttemptChangedFilesSinceBoundary(input) {
+    if (!input.repoRoot) {
+        return [];
+    }
+    const repoState = readRepoState(input.repoRoot);
+    if (!input.boundary) {
+        return uniqueSorted([...repoState.trackedDirtyFiles, ...repoState.untrackedFiles]);
+    }
+    const baselineTracked = new Set(input.boundary.trackedDirtyFiles);
+    const baselineUntracked = new Set(input.boundary.untrackedFiles);
+    return uniqueSorted([
+        ...repoState.trackedDirtyFiles.filter((filePath) => !baselineTracked.has(filePath)),
+        ...repoState.untrackedFiles.filter((filePath) => !baselineUntracked.has(filePath))
+    ]);
+}
 export async function captureRollbackBoundary(input) {
     if (!input.repoRoot) {
         return undefined;

package/dist/vendor/core/routing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Route classification and compression for governed agent runs.
+ *
+ * Decides whether a task needs manager/planner orchestration or can go
+ * directly to a worker, based on task complexity signals. Prevents
+ * wasted coordination cost (Pre Work Burn) on simple tasks.
+ */
+import type { RoutingMode, RoutingPolicy } from "../contracts/index.js";
+export interface RouteDecision {
+    selectedMode: RoutingMode;
+    confidence: number;
+    expectedCostUsd: number;
+    expectedPreworkBurnPct: number;
+    reason: string[];
+    blockedSteps: string[];
+    compressed: boolean;
+    compressionSummary?: string;
+}
+export interface RouteClassificationInput {
+    objective: string;
+    verificationPlan: string[];
+    repoRoot?: string;
+    allowedPaths?: string[];
+    deniedPaths?: string[];
+    budgetUsd: number;
+    policy?: Partial<RoutingPolicy>;
+    /** Number of files the task references or is scoped to. */
+    scopedFileCount?: number;
+    /** Historical success rate for similar tasks with direct execution (0-1). */
+    historicalDirectSuccessRate?: number;
+}
+export declare function classifyRoute(input: RouteClassificationInput): RouteDecision;
+/**
+ * Checks whether a run's Pre Work Burn exceeds the routing policy limits.
+ * Returns a block reason if exceeded, undefined if within bounds.
+ */
+export declare function evaluatePreworkBurnPolicy(preworkCostUsd: number, totalCostUsd: number, policy?: Partial<RoutingPolicy>): {
+    exceeded: boolean;
+    reason?: string;
+};

package/dist/vendor/core/routing.js

@@ -0,0 +1,185 @@
+/**
+ * Route classification and compression for governed agent runs.
+ *
+ * Decides whether a task needs manager/planner orchestration or can go
+ * directly to a worker, based on task complexity signals. Prevents
+ * wasted coordination cost (Pre Work Burn) on simple tasks.
+ */
+import { DEFAULT_ROUTING_POLICY } from "../contracts/index.js";
+const SECURITY_KEYWORDS = [
+    "auth", "authentication", "authorization", "credential", "secret",
+    "token", "password", "oauth", "jwt", "session", "csrf", "xss",
+    "injection", "encryption", "certificate", "tls", "ssl", "permission"
+];
+const ARCHITECTURE_KEYWORDS = [
+    "refactor", "architecture", "redesign", "restructure", "migration",
+    "database schema", "api design", "service boundary", "microservice",
+    "event sourcing", "cqrs", "distributed"
+];
+const MIGRATION_KEYWORDS = [
+    "migration", "migrate", "upgrade", "downgrade", "schema change",
+    "data migration", "database migration", "breaking change"
+];
+const MULTI_FILE_KEYWORDS = [
+    "across", "all files", "every file", "codebase-wide", "global",
+    "rename everywhere", "update all", "system-wide"
+];
+function extractComplexitySignals(input) {
+    const lower = input.objective.toLowerCase();
+    return {
+        objectiveLength: input.objective.length,
+        fileCount: input.scopedFileCount ?? estimateFileCount(input),
+        hasSecurityKeywords: SECURITY_KEYWORDS.some((kw) => lower.includes(kw)),
+        hasArchitectureKeywords: ARCHITECTURE_KEYWORDS.some((kw) => lower.includes(kw)),
+        hasMigrationKeywords: MIGRATION_KEYWORDS.some((kw) => lower.includes(kw)),
+        hasMultiFileKeywords: MULTI_FILE_KEYWORDS.some((kw) => lower.includes(kw)),
+        verifierCount: input.verificationPlan.length,
+        budgetUsd: input.budgetUsd,
+        scopeRestricted: (input.allowedPaths?.length ?? 0) > 0 || (input.deniedPaths?.length ?? 0) > 0
+    };
+}
+function estimateFileCount(input) {
+    const pathCount = (input.allowedPaths?.length ?? 0) + (input.deniedPaths?.length ?? 0);
+    if (pathCount > 0)
+        return pathCount;
+    // Heuristic: short objectives with specific file refs → 1-2 files
+    const fileRefs = input.objective.match(/[\w/.-]+\.\w{1,5}/g);
+    return fileRefs?.length ?? 1;
+}
+// ---------------------------------------------------------------------------
+// Confidence scoring
+// ---------------------------------------------------------------------------
+function calculateDirectConfidence(signals, input) {
+    let confidence = 0.7; // Base: most tasks can go direct
+    // Boost for simple tasks
+    if (signals.objectiveLength < 200)
+        confidence += 0.1;
+    if (signals.fileCount <= 2)
+        confidence += 0.1;
+    if (signals.scopeRestricted)
+        confidence += 0.05;
+    if (signals.verifierCount === 1)
+        confidence += 0.05;
+    // Penalize for complex tasks
+    if (signals.hasSecurityKeywords)
+        confidence -= 0.25;
+    if (signals.hasArchitectureKeywords)
+        confidence -= 0.2;
+    if (signals.hasMigrationKeywords)
+        confidence -= 0.3;
+    if (signals.hasMultiFileKeywords)
+        confidence -= 0.15;
+    if (signals.objectiveLength > 500)
+        confidence -= 0.1;
+    if (signals.fileCount > 5)
+        confidence -= 0.15;
+    if (signals.budgetUsd > 10)
+        confidence -= 0.1;
+    // Historical evidence
+    if (input.historicalDirectSuccessRate !== undefined) {
+        confidence = confidence * 0.6 + input.historicalDirectSuccessRate * 0.4;
+    }
+    return Math.max(0, Math.min(1, confidence));
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function classifyRoute(input) {
+    const policy = { ...DEFAULT_ROUTING_POLICY, ...input.policy };
+    const signals = extractComplexitySignals(input);
+    const directConfidence = calculateDirectConfidence(signals, input);
+    const reason = [];
+    const blockedSteps = [];
+    // Policy override: forced mode
+    if (policy.mode === "direct") {
+        return {
+            selectedMode: "direct",
+            confidence: 1,
+            expectedCostUsd: estimateDirectCost(input.budgetUsd),
+            expectedPreworkBurnPct: 5,
+            reason: ["Policy forces direct execution mode."],
+            blockedSteps: ["manager", "planner", "router", "consensus"],
+            compressed: true,
+            compressionSummary: "Policy: direct mode — skipping all orchestration."
+        };
+    }
+    if (policy.mode === "consensus") {
+        return {
+            selectedMode: "consensus",
+            confidence: 0.5,
+            expectedCostUsd: input.budgetUsd * 0.8,
+            expectedPreworkBurnPct: 35,
+            reason: ["Policy forces consensus mode."],
+            blockedSteps: [],
+            compressed: false
+        };
+    }
+    // Adaptive routing
+    if (directConfidence >= policy.skipOrchestrationIfConfidenceAbove) {
+        reason.push(`Direct confidence ${(directConfidence * 100).toFixed(0)}% exceeds threshold ${(policy.skipOrchestrationIfConfidenceAbove * 100).toFixed(0)}%.`);
+        if (signals.objectiveLength < 200)
+            reason.push("Short, focused objective.");
+        if (signals.fileCount <= 2)
+            reason.push(`Scoped to ${String(signals.fileCount)} file(s).`);
+        if (signals.scopeRestricted)
+            reason.push("Path scope is restricted.");
+        blockedSteps.push("manager", "consensus");
+        return {
+            selectedMode: "direct",
+            confidence: directConfidence,
+            expectedCostUsd: estimateDirectCost(input.budgetUsd),
+            expectedPreworkBurnPct: 8,
+            reason,
+            blockedSteps,
+            compressed: true,
+            compressionSummary: `Compressed from manager→planner→worker to direct worker. Estimated savings: ${String(Math.round(input.budgetUsd * 0.3 * 100) / 100)} USD.`
+        };
+    }
+    // Complex task — needs orchestration
+    if (signals.hasSecurityKeywords)
+        reason.push("Security-sensitive task detected.");
+    if (signals.hasMigrationKeywords)
+        reason.push("Migration task detected.");
+    if (signals.hasArchitectureKeywords)
+        reason.push("Architectural scope detected.");
+    if (signals.fileCount > 5)
+        reason.push(`Touches ${String(signals.fileCount)}+ files.`);
+    const needsConsensus = signals.hasSecurityKeywords && signals.hasMigrationKeywords;
+    return {
+        selectedMode: needsConsensus ? "consensus" : "manager",
+        confidence: directConfidence,
+        expectedCostUsd: input.budgetUsd * (needsConsensus ? 0.8 : 0.6),
+        expectedPreworkBurnPct: needsConsensus ? 40 : 25,
+        reason,
+        blockedSteps: needsConsensus ? [] : ["consensus"],
+        compressed: false
+    };
+}
+function estimateDirectCost(budgetUsd) {
+    // Direct execution typically uses 30-50% of budget
+    return Math.round(budgetUsd * 0.35 * 100) / 100;
+}
+/**
+ * Checks whether a run's Pre Work Burn exceeds the routing policy limits.
+ * Returns a block reason if exceeded, undefined if within bounds.
+ */
+export function evaluatePreworkBurnPolicy(preworkCostUsd, totalCostUsd, policy = {}) {
+    const resolved = { ...DEFAULT_ROUTING_POLICY, ...policy };
+    if (!resolved.enabled) {
+        return { exceeded: false };
+    }
+    if (preworkCostUsd > resolved.maxPreworkCostUsd) {
+        return {
+            exceeded: true,
+            reason: `Pre-work cost $${preworkCostUsd.toFixed(2)} exceeds routing policy cap of $${resolved.maxPreworkCostUsd.toFixed(2)}.`
+        };
+    }
+    const burnPct = totalCostUsd > 0 ? (preworkCostUsd / totalCostUsd) * 100 : 0;
+    if (burnPct > resolved.maxPreworkBudgetPct) {
+        return {
+            exceeded: true,
+            reason: `Pre Work Burn at ${burnPct.toFixed(0)}% exceeds routing policy cap of ${String(resolved.maxPreworkBudgetPct)}%.`
+        };
+    }
+    return { exceeded: false };
+}

package/dist/workflow-state.d.ts

@@ -1,5 +1,20 @@
 import type { LoopBudget, ReceiptScope } from "./vendor/contracts/index.js";
 type McpWorkflowStepName = "doctor" | "plan" | "preflight";
+interface McpWorkflowReceipt {
+    step: McpWorkflowStepName;
+    recordedAt: string;
+    workingDirectory: string;
+    objectiveKey?: string;
+    engine?: string;
+    verificationPlanKey?: string;
+    scopeKey?: string;
+    pathScopeKey?: string;
+    budgetKey?: string;
+}
+interface WorkflowState {
+    version: 1;
+    mcp?: Partial<Record<McpWorkflowStepName, McpWorkflowReceipt>>;
+}
 export interface RecordMcpWorkflowStepInput {
     runsRoot: string;
     step: McpWorkflowStepName;
@@ -31,4 +46,5 @@ export interface McpRunGateResult {
 }
 export declare function recordMcpWorkflowStep(input: RecordMcpWorkflowStepInput): Promise<void>;
 export declare function evaluateMcpRunGate(input: EvaluateMcpRunGateInput): Promise<McpRunGateResult>;
+export declare function readWorkflowState(runsRoot: string): Promise<WorkflowState>;
 export {};

package/dist/workflow-state.js

@@ -76,7 +76,7 @@ export async function evaluateMcpRunGate(input) {
         missingSteps
     };
 }
-async function readWorkflowState(runsRoot) {
+export async function readWorkflowState(runsRoot) {
     const statePath = resolveWorkflowStatePath(runsRoot);
     try {
         const raw = await readFile(statePath, "utf8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinloop/mcp",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "mcpName": "io.github.Keesan12/martin-loop",
   "private": false,
   "type": "module",