@martinloop/mcp 0.8.2 → 0.8.4

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const MARTIN_MCP_PACKAGE_VERSION = "0.8.2";
+export declare const MARTIN_MCP_PACKAGE_VERSION = "0.8.4";

package/dist/package-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by build — do not edit by hand.
 // Source of truth: packages/mcp/package.json#version
-export const MARTIN_MCP_PACKAGE_VERSION = "0.8.2";
+export const MARTIN_MCP_PACKAGE_VERSION = "0.8.4";

package/dist/tools/run-dossier.js

@@ -1,10 +1,11 @@
-import { buildArtifactSummary, buildBudgetSnapshot, buildCostSnapshot, buildEventSummaries, buildLoopPreview, resolveReceiptIntegrity, buildSuggestedPromptNames, buildSuggestedResourceUris, buildVerificationSummary } from "./tool-support.js";
+import { buildArtifactSummary, buildBudgetSnapshot, buildCostSnapshot, buildEventSummaries, buildFileEffectsSummary, buildLoopPreview, resolveReceiptIntegrity, buildSuggestedPromptNames, buildSuggestedResourceUris, buildVerificationSummary } from "./tool-support.js";
 import { resolveTrustedLoopRepoRoot } from "../server-validation.js";
 import { loadDetailedLoopRecord, readAttemptArtifactFiles, readLedgerEvents } from "./run-store.js";
 import { readRunControlState } from "./run-controls.js";
 import { martinEvalTool } from "./eval.js";
 import { assessRunRisk, inspectRepoSignals } from "./workflow-governance.js";
 import { buildVerifiedHandoff } from "../vendor/core/index.js";
+import { renderVerifiedHandoffMarkdown } from "../vendor/presentation/index.js";
 export async function martinRunDossierTool(input) {
     const detail = await loadDetailedLoopRecord(input);
     const ledgerEvents = await readLedgerEvents(detail);
@@ -31,21 +32,64 @@ export async function martinRunDossierTool(input) {
         ...(attempt.summary ? { summary: attempt.summary } : {}),
         artifactFiles: await readAttemptArtifactFiles(detail, attempt.index)
     })));
+    const fileEffects = buildFileEffectsSummary(detail.loop);
+    const verifiedHandoff = buildVerifiedHandoff({
+        loop: detail.loop,
+        receiptIntegrity: resolveReceiptIntegrity(detail.loop),
+        verification: {
+            status: verification.status,
+            summary: verification.summary ?? "No verification summary recorded.",
+            steps: verification.steps,
+            warnings: verification.warnings,
+            ...(verification.binding ? { binding: verification.binding } : {})
+        },
+        fileEffects,
+        scope: {
+            status: detail.loop.task?.allowedPaths?.length ||
+                detail.loop.task?.deniedPaths?.length
+                ? "WITHIN_SCOPE"
+                : "NOT_EVALUATED",
+            allowedPaths: detail.loop.task?.allowedPaths ?? [],
+            deniedPaths: detail.loop.task?.deniedPaths ?? [],
+            changedFiles: verification.changedFiles,
+            violations: []
+        },
+        testIntegrity: {
+            status: "NOT_EVALUATED",
+            verdict: "NOT_EVALUATED",
+            protectedPaths: [],
+            changedProtectedPaths: [],
+            findings: [],
+            summary: "Automatic test-integrity evidence was not recorded for this run."
+        },
+        unresolvedWork: verification.status === "passed"
+            ? []
+            : [verification.summary ?? "Verification did not pass."],
+        nextAction: "Review the canonical dossier evidence."
+    });
+    const receiptIntegrity = resolveReceiptIntegrity(detail.loop);
+    const reviewOutcome = verifiedHandoff.outcome === "VERIFIED"
+        ? "passed"
+        : verifiedHandoff.outcome === "STOPPED"
+            ? "failed"
+            : "needs_review";
+    const nextAction = receiptIntegrity.state !== "verified"
+        ? `Resolve receipt integrity (${receiptIntegrity.state}) before trusting or promoting this run.`
+        : verifiedHandoff.outcome === "VERIFIED"
+            ? "Review the dossier and evaluation, then decide whether to merge or promote."
+            : verifiedHandoff.outcome === "STOPPED"
+                ? `The run stopped${verifiedHandoff.lifecycleTruth.reasonCode ? ` (${verifiedHandoff.lifecycleTruth.reasonCode})` : ""}; review lifecycle evidence before retrying.`
+                : verification.status === "failed" || verification.status === "contradicted"
+                    ? "Investigate the latest verifier failure before retrying or promoting."
+                    : "Collect more evidence before claiming completion.";
+    verifiedHandoff.nextAction = nextAction;
     const review = {
         diffSummary: attempts.length > 0
             ? `Run touched ${attempts.length} attempt(s); latest summary: ${attempts.at(-1)?.summary ?? "No attempt summary recorded."}`
             : "No attempts were recorded for this run.",
         risk,
-        outcome: verification.status === "passed"
-            ? "passed"
-            : verification.status === "failed" || verification.status === "contradicted"
-                ? "failed"
-                : "needs_review",
-        nextAction: verification.status === "passed"
-            ? "Review the dossier and evaluation, then decide whether to merge or promote."
-            : verification.status === "failed" || verification.status === "contradicted"
-                ? "Investigate the latest verifier failure before retrying or promoting."
-                : "Collect more evidence before claiming completion."
+        outcome: reviewOutcome,
+        nextAction
     };
     const output = {
         source: detail.source,
@@ -53,7 +97,7 @@ export async function martinRunDossierTool(input) {
         loop: buildLoopPreview(detail.loop),
         budget: buildBudgetSnapshot(detail.loop.budget),
         cost: buildCostSnapshot(detail.loop.cost),
-        receiptIntegrity: resolveReceiptIntegrity(detail.loop),
+        receiptIntegrity,
         ...(detail.loop.receiptScope ? { receiptScope: detail.loop.receiptScope } : {}),
         ...(detail.loop.terminationEnvelope ? { terminationEnvelope: detail.loop.terminationEnvelope } : {}),
         attempts,
@@ -75,36 +119,7 @@ export async function martinRunDossierTool(input) {
             ...(detail.ledgerPath ? { ledgerPath: detail.ledgerPath } : {})
         },
         warnings: [...detail.warnings, ...verification.warnings],
-        verifiedHandoff: buildVerifiedHandoff({
-            loop: detail.loop,
-            receiptIntegrity: resolveReceiptIntegrity(detail.loop),
-            verification: {
-                status: verification.status,
-                summary: verification.summary ?? "No verification summary recorded.",
-                steps: [],
-                warnings: verification.warnings,
-            },
-            scope: {
-                status: detail.loop.task?.allowedPaths?.length ||
-                    detail.loop.task?.deniedPaths?.length
-                    ? "WITHIN_SCOPE"
-                    : "NOT_EVALUATED",
-                allowedPaths: detail.loop.task?.allowedPaths ?? [],
-                deniedPaths: detail.loop.task?.deniedPaths ?? [],
-                changedFiles: [],
-                violations: [],
-            },
-            testIntegrity: {
-                status: "NOT_EVALUATED",
-                verdict: "NOT_EVALUATED",
-                protectedPaths: [],
-                changedProtectedPaths: [],
-                findings: [],
-                summary: "Automatic test-integrity evidence was not recorded for this run.",
-            },
-            unresolvedWork: verification.status === "passed" ? [] : [verification.summary ?? "Verification did not pass."],
-            nextAction: review.nextAction,
-        }),
+        verifiedHandoff,
     };
     if (output.format !== "json") {
         output.rendered = renderDossier(output);
@@ -113,14 +128,11 @@ export async function martinRunDossierTool(input) {
 }
 function renderDossier(output) {
     const lines = [
-        output.format === "github-pr" ? "## MartinLoop Verified Handoff" : "# MartinLoop Verified Handoff",
+        renderVerifiedHandoffMarkdown(output.verifiedHandoff),
         "",
-        `Outcome: ${output.verifiedHandoff.outcome}`,
-        `Definition of Done: ${output.verifiedHandoff.definitionOfDone.acceptanceCriteria.length} acceptance criterion/criteria`,
-        `Verification: ${output.verifiedHandoff.verification.status}`,
-        `Scope: ${output.verifiedHandoff.scope.status}`,
-        `Test Integrity: ${output.verifiedHandoff.testIntegrity.verdict}`,
+        output.format === "github-pr" ? "### MCP Dossier Context" : "## MCP Dossier Context",
         "",
+        `Definition of Done: ${output.verifiedHandoff.definitionOfDone.acceptanceCriteria.length} acceptance criterion/criteria`,
         `Objective: ${output.loop.objective}`,
         `Run: ${output.loop.loopId}`,
         `Status: ${output.loop.status} / ${output.loop.lifecycleState}`,

package/dist/tools/tool-support.d.ts

@@ -1,5 +1,5 @@
-import type { CostProvenance, LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask, ReceiptIntegritySummary, ReceiptScope, TerminationEnvelopeV1 } from "../vendor/contracts/index.js";
-import { type LedgerEvent, type LoopAttemptRecord, type LoopRunRecord } from "../vendor/core/index.js";
+import type { CostProvenance, LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask, ReceiptIntegritySummary, ReceiptScope, TerminationEnvelopeV1, VerifiedHandoffFileEffectsV1 } from "../vendor/contracts/index.js";
+import { type LedgerEvent, type LoopAttemptRecord, type LoopRunRecord, type VerifierExecutionBinding } from "../vendor/core/index.js";
 export declare const MARTIN_ENGINE_VALUES: readonly ["claude", "codex", "gemini", "openai"];
 export type MartinEngine = (typeof MARTIN_ENGINE_VALUES)[number];
 export interface InspectableLoopAttempt extends LoopAttemptRecord {
@@ -7,6 +7,7 @@ export interface InspectableLoopAttempt extends LoopAttemptRecord {
     summary?: string;
 }
 export interface InspectableLoopRecord extends Omit<LoopRunRecord, "attempts" | "task" | "budget"> {
+    workspaceId?: string;
     budget: LoopBudget;
     attempts: InspectableLoopAttempt[];
     task?: LoopTask;
@@ -75,8 +76,20 @@ export interface VerificationSummary {
     latestAttemptIndex?: number;
     completedAt?: string;
     summary?: string;
+    steps: VerificationStepSummary[];
+    binding?: VerifierExecutionBinding;
+    changedFiles: string[];
     warnings: string[];
 }
+export interface VerificationStepSummary {
+    command: string;
+    launched: boolean;
+    completed?: boolean;
+    crashed?: boolean;
+    exitCode?: number;
+    timedOut?: boolean;
+    detail?: string;
+}
 export interface RunWarningEnvelope {
     warnings: string[];
 }
@@ -126,6 +139,7 @@ export declare function buildLoopPreview(loop: InspectableLoopRecord): LoopPrevi
 export declare function buildAttemptSummary(attempt: InspectableLoopAttempt, artifacts?: AttemptArtifactFiles): AttemptSummary;
 export declare function buildArtifactSummary(loop: InspectableLoopRecord): ArtifactSummary;
 export declare function buildVerificationSummary(loop: InspectableLoopRecord, ledgerEvents?: LedgerEvent[]): VerificationSummary;
+export declare function buildFileEffectsSummary(loop: InspectableLoopRecord): VerifiedHandoffFileEffectsV1;
 export declare function resolveReceiptIntegrity(loop: InspectableLoopRecord): ReceiptIntegritySummary;
 export declare function buildEventSummaries(loop: InspectableLoopRecord, limit?: number): EventSummary[];
 export declare function buildLoopCollectionSummary(loops: Array<LoopRunRecord | InspectableLoopRecord>): LoopCollectionSummary;

package/dist/tools/tool-support.js

@@ -1,7 +1,7 @@
 import { accessSync, constants } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { evaluateCostGovernor, resolveRunsRoot } from "../vendor/core/index.js";
+import { evaluateCostGovernor, resolveRunsRoot, verifierActuallyPassed } from "../vendor/core/index.js";
 import { readAllLoopRecordsSafely } from "./run-store.js";
 export const MARTIN_ENGINE_VALUES = ["claude", "codex", "gemini", "openai"];
 const CLI_CACHE_TTL_MS = 60_000;
@@ -241,18 +241,94 @@ export function buildVerificationSummary(loop, ledgerEvents = []) {
     warnings.push(...selectedEvidence.warnings);
     const latestEvidence = selectedEvidence.evidence;
     if (!latestEvidence)
-        return { status: "not_run", eventCount: verificationEvents.length, ledgerEventCount: verificationLedgerEvents.length, warnings };
-    const contradicted = latestEvidence.passed === true && warnings.some((warning) => warning.toLowerCase().includes("conflicts for the latest attempt"));
+        return {
+            status: "not_run",
+            eventCount: verificationEvents.length,
+            ledgerEventCount: verificationLedgerEvents.length,
+            steps: [],
+            changedFiles: [],
+            warnings
+        };
+    const expectedAttemptId = latestEvidence.attemptIndex !== undefined
+        ? loop.attempts.find((attempt) => attempt.index === latestEvidence.attemptIndex)?.attemptId
+        : loop.attempts.at(-1)?.attemptId;
+    const expectedBinding = latestEvidence.binding && loop.workspaceId
+        ? {
+            runId: loop.loopId,
+            workspaceId: loop.workspaceId,
+            ...(expectedAttemptId ? { attemptId: expectedAttemptId } : {}),
+            cwd: loop.receiptScope?.workingDirectory ?? loop.task?.repoRoot ?? latestEvidence.binding.cwd,
+            ...(loop.receiptScope?.runsRoot ? { runsRoot: loop.receiptScope.runsRoot } : {}),
+            ...(loop.task?.executionProfile ? { executionProfile: loop.task.executionProfile } : {}),
+            ...(loop.task?.allowedNetworkDomains?.length
+                ? { allowedNetworkDomains: [...loop.task.allowedNetworkDomains] }
+                : {}),
+            commands: [...(loop.task?.verificationPlan ?? [])]
+        }
+        : undefined;
+    const executionPassed = expectedBinding
+        ? verifierActuallyPassed({
+            passed: latestEvidence.passed === true,
+            binding: latestEvidence.binding,
+            steps: latestEvidence.steps
+        }, expectedBinding)
+        : false;
+    const contradicted = latestEvidence.passed === true && !executionPassed;
+    if (contradicted) {
+        warnings.push("Persisted verifier claimed success without complete bound execution evidence.");
+    }
     return {
-        status: contradicted ? "contradicted" : latestEvidence.passed === true ? "passed" : latestEvidence.passed === false ? "failed" : "not_run",
+        status: contradicted ? "contradicted" : executionPassed ? "passed" : latestEvidence.passed === false ? "failed" : "not_run",
         eventCount: verificationEvents.length,
         ledgerEventCount: verificationLedgerEvents.length,
         ...(latestEvidence.attemptIndex !== undefined ? { latestAttemptIndex: latestEvidence.attemptIndex } : {}),
         ...(latestEvidence.timestamp ? { completedAt: latestEvidence.timestamp } : {}),
         ...(typeof latestEvidence.summary === "string" && latestEvidence.summary.trim().length > 0 ? { summary: latestEvidence.summary.trim() } : {}),
+        steps: latestEvidence.steps,
+        ...(latestEvidence.binding ? { binding: latestEvidence.binding } : {}),
+        changedFiles: latestEvidence.changedFiles,
         warnings
     };
 }
+export function buildFileEffectsSummary(loop) {
+    const completedEvent = (loop.events ?? []).filter((event) => event.type === "run.completed").at(-1);
+    const payload = completedEvent && isRecord(completedEvent.payload) ? completedEvent.payload : undefined;
+    const candidate = payload && isRecord(payload["fileEffects"]) ? payload["fileEffects"] : undefined;
+    if (!candidate) {
+        return {
+            observationStatus: "unavailable",
+            touchedDuringExecution: [],
+            netChangedAtCompletion: [],
+            revertedBeforeCompletion: [],
+            observationReason: "File-effect evidence was not recorded for this run."
+        };
+    }
+    const observationStatus = candidate["observationStatus"];
+    const touchedDuringExecution = readStringArray(candidate["touchedDuringExecution"]);
+    const netChangedAtCompletion = readStringArray(candidate["netChangedAtCompletion"]);
+    const revertedBeforeCompletion = readStringArray(candidate["revertedBeforeCompletion"]);
+    if ((observationStatus !== "observed" && observationStatus !== "unavailable")
+        || touchedDuringExecution === undefined
+        || netChangedAtCompletion === undefined
+        || revertedBeforeCompletion === undefined) {
+        return {
+            observationStatus: "unavailable",
+            touchedDuringExecution: [],
+            netChangedAtCompletion: [],
+            revertedBeforeCompletion: [],
+            observationReason: "Persisted file-effect evidence was malformed."
+        };
+    }
+    return {
+        observationStatus,
+        touchedDuringExecution,
+        netChangedAtCompletion,
+        revertedBeforeCompletion,
+        ...(typeof candidate["observationReason"] === "string"
+            ? { observationReason: candidate["observationReason"] }
+            : {})
+    };
+}
 export function resolveReceiptIntegrity(loop) {
     return loop.receiptIntegrity ?? { state: "selector_noncanonical", reason: "Receipt integrity metadata was not available on the loop record." };
 }
@@ -370,7 +446,10 @@ function normalizeLoopVerificationEvidence(loop, event) {
         ...(matchedAttempt.attemptId ? { attemptId: matchedAttempt.attemptId } : {}),
         attemptIndex: matchedAttempt.index,
         ...(typeof payload?.["passed"] === "boolean" ? { passed: payload["passed"] } : {}),
-        ...(typeof payload?.["summary"] === "string" ? { summary: payload["summary"] } : {})
+        ...(typeof payload?.["summary"] === "string" ? { summary: payload["summary"] } : {}),
+        steps: readVerificationSteps(payload?.["steps"]),
+        ...(readVerifierBinding(payload?.["binding"]) ? { binding: readVerifierBinding(payload?.["binding"]) } : {}),
+        changedFiles: readStringArray(payload?.["changedFiles"]) ?? []
     };
 }
 function normalizeLedgerVerificationEvidence(loop, event) {
@@ -387,9 +466,68 @@ function normalizeLedgerVerificationEvidence(loop, event) {
         ...(matchedAttempt.attemptId ? { attemptId: matchedAttempt.attemptId } : {}),
         attemptIndex: event.attemptIndex,
         ...(typeof payload?.["passed"] === "boolean" ? { passed: payload["passed"] } : {}),
-        ...(typeof payload?.["summary"] === "string" ? { summary: payload["summary"] } : {})
+        ...(typeof payload?.["summary"] === "string" ? { summary: payload["summary"] } : {}),
+        steps: readVerificationSteps(payload?.["steps"]),
+        ...(readVerifierBinding(payload?.["binding"]) ? { binding: readVerifierBinding(payload?.["binding"]) } : {}),
+        changedFiles: readStringArray(payload?.["changedFiles"]) ?? []
     };
 }
+function readVerificationSteps(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((candidate) => {
+        if (!isRecord(candidate) || typeof candidate["command"] !== "string" || typeof candidate["launched"] !== "boolean") {
+            return undefined;
+        }
+        return {
+            command: candidate["command"],
+            launched: candidate["launched"],
+            ...(typeof candidate["completed"] === "boolean" ? { completed: candidate["completed"] } : {}),
+            ...(typeof candidate["crashed"] === "boolean" ? { crashed: candidate["crashed"] } : {}),
+            ...(typeof candidate["exitCode"] === "number" ? { exitCode: candidate["exitCode"] } : {}),
+            ...(typeof candidate["timedOut"] === "boolean" ? { timedOut: candidate["timedOut"] } : {}),
+            ...(typeof candidate["detail"] === "string" ? { detail: candidate["detail"] } : {})
+        };
+    })
+        .filter((candidate) => candidate !== undefined);
+}
+function readVerifierBinding(value) {
+    if (!isRecord(value)
+        || typeof value["runId"] !== "string"
+        || typeof value["workspaceId"] !== "string"
+        || typeof value["cwd"] !== "string"
+        || !Array.isArray(value["commands"])
+        || !value["commands"].every((command) => typeof command === "string")) {
+        return undefined;
+    }
+    const executionProfile = value["executionProfile"];
+    if (executionProfile !== undefined
+        && executionProfile !== "strict_local"
+        && executionProfile !== "ci_safe"
+        && executionProfile !== "staging_controlled"
+        && executionProfile !== "research_untrusted") {
+        return undefined;
+    }
+    const allowedNetworkDomains = readStringArray(value["allowedNetworkDomains"]);
+    if (value["allowedNetworkDomains"] !== undefined && allowedNetworkDomains === undefined)
+        return undefined;
+    return {
+        runId: value["runId"],
+        workspaceId: value["workspaceId"],
+        ...(typeof value["attemptId"] === "string" ? { attemptId: value["attemptId"] } : {}),
+        cwd: value["cwd"],
+        ...(typeof value["runsRoot"] === "string" ? { runsRoot: value["runsRoot"] } : {}),
+        ...(executionProfile !== undefined ? { executionProfile } : {}),
+        ...(allowedNetworkDomains !== undefined ? { allowedNetworkDomains } : {}),
+        commands: [...value["commands"]]
+    };
+}
+function readStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string")
+        ? [...value]
+        : undefined;
+}
 function isTrustedVerificationTimestamp(value) {
     const timestamp = new Date(value).getTime();
     return Number.isFinite(timestamp) && timestamp <= Date.now() + 5 * 60_000;

package/dist/vendor/adapters/claude-cli.d.ts

@@ -63,6 +63,8 @@ export interface AgentCliAdapterOptions {
     streamingTokenCap?: boolean;
     /** Provider detail-token fields are already included in input/output token totals. */
     streamingUsageDetailsIncludedInTotals?: boolean;
+    /** Whether provider usage arrives incrementally or only on a terminal event. */
+    streamingUsageReportingMode?: "incremental" | "terminal";
     /** Estimated floor used by the host to reject impossible token caps before spawning. */
     budgetPreflight?: {
         minimumViableTokens: number;

package/dist/vendor/adapters/claude-cli.js

@@ -383,7 +383,7 @@ function extractGeminiJsonResult(stdout, modelLabel) {
         })
     };
 }
-function createStreamingUsageInspector(capUsd, modelLabel, promptTokenEstimate, capTokens, detailTokensIncludedInTotals = false, observedUsageGovernor) {
+function createStreamingUsageInspector(capUsd, modelLabel, promptTokenEstimate, capTokens, detailTokensIncludedInTotals = false, observedUsageGovernor, usageReportingMode = "incremental") {
     let pricingResolution = resolveModelPricing(modelLabel);
     // Safety margin: terminate at 80% of cap to bound one-turn overshoot.
     // Without this, a single expensive turn can blow past the cap before the
@@ -424,15 +424,22 @@ function createStreamingUsageInspector(capUsd, modelLabel, promptTokenEstimate,
                 finalObservationPublished = true;
             try {
                 const decision = observedUsageGovernor({ cumulativeUsd, cumulativeTokens, turns, final });
-                if (decision.action === "terminate") {
+                if (decision.action === "terminate" && !(usageReportingMode === "terminal" && final)) {
                     terminate(`Parent observed-usage governor terminated the subprocess: ${decision.reason}.`);
                 }
             }
             catch (error) {
-                terminate(`Parent observed-usage governor failed closed: ${error instanceof Error ? error.message : String(error)}.`);
+                if (!(usageReportingMode === "terminal" && final)) {
+                    terminate(`Parent observed-usage governor failed closed: ${error instanceof Error ? error.message : String(error)}.`);
+                }
             }
             return;
         }
+        // Codex reports authoritative usage on turn.completed, after the provider
+        // turn and its workspace edits have already finished. Record that terminal
+        // settlement, but do not kill and discard completed work at this point.
+        if (usageReportingMode === "terminal" && final)
+            return;
         if (capTokens !== undefined && capTokens > 0 && cumulativeTokens > capTokens) {
             terminate(`Streaming token lease exceeded after ${String(turns)} turn(s): observed ${String(cumulativeTokens)} tokens ` +
                 `surpassed the per-attempt token cap ${String(capTokens)}. Subprocess terminated to prevent additional token usage.`);
@@ -557,7 +564,7 @@ function createStreamingUsageInspector(capUsd, modelLabel, promptTokenEstimate,
             }
             return;
         }
-        extractUsageFromEvent(event, terminate);
+        extractUsageFromEvent(event, terminate, usageReportingMode === "terminal" && event.type === "turn.completed");
     };
     return {
         onChunk: (chunk, terminate) => {
@@ -572,7 +579,8 @@ function createStreamingUsageInspector(capUsd, modelLabel, promptTokenEstimate,
             const bytesCeiling = blendedCostPerChar && blendedCostPerChar > 0
                 ? Math.ceil((capUsd / blendedCostPerChar) * 2)
                 : undefined;
-            if (!usageEventSeen && capUsd > 0 && bytesCeiling !== undefined && totalBytes > bytesCeiling) {
+            if (usageReportingMode === "incremental" &&
+                !usageEventSeen && capUsd > 0 && bytesCeiling !== undefined && totalBytes > bytesCeiling) {
                 terminate(`Streaming byte ceiling exceeded (${String(totalBytes)} bytes > ${String(bytesCeiling)} ceiling) ` +
                     `without any usage events parsed. The Claude stream-json event format may have changed. ` +
                     `Subprocess terminated as a fallback budget guard for cap $${capUsd.toFixed(4)}.`);
@@ -582,7 +590,8 @@ function createStreamingUsageInspector(capUsd, modelLabel, promptTokenEstimate,
             // without a single usage event, estimate spend from byte volume and
             // enforce the cap. This catches cases where Claude's event format
             // changed but bytes are still flowing.
-            if (!usageEventSeen &&
+            if (usageReportingMode === "incremental" &&
+                !usageEventSeen &&
                 capUsd > 0 &&
                 firstChunkAt !== undefined &&
                 Date.now() - firstChunkAt > USAGE_BLIND_TIMEOUT_MS &&
@@ -726,7 +735,7 @@ export function createAgentCliAdapter(options) {
             const streamingUsage = options.streamingUsageCap &&
                 (request.context.remainingBudgetUsd > 0 ||
                     (options.streamingTokenCap && (request.context.remainingTokens ?? 0) > 0))
-                ? createStreamingUsageInspector(request.context.remainingBudgetUsd, options.model ?? options.command, estimatedUsage.tokensIn, options.streamingTokenCap ? request.context.remainingTokens : undefined, options.streamingUsageDetailsIncludedInTotals, request.observedUsageGovernor)
+                ? createStreamingUsageInspector(request.context.remainingBudgetUsd, options.model ?? options.command, estimatedUsage.tokensIn, options.streamingTokenCap ? request.context.remainingTokens : undefined, options.streamingUsageDetailsIncludedInTotals, request.observedUsageGovernor, options.streamingUsageReportingMode)
                 : undefined;
             const agentResult = await runSubprocess(options.executionCommand ?? options.command, args, {
                 cwd: workingDirectory,

package/dist/vendor/adapters/codex-cli.js

@@ -51,6 +51,7 @@ export function createCodexCliAdapter(options = {}) {
         streamingUsageCap: true,
         streamingTokenCap: true,
         streamingUsageDetailsIncludedInTotals: true,
+        streamingUsageReportingMode: "terminal",
         budgetPreflight: {
             minimumViableTokens: CODEX_MINIMUM_VIABLE_TOKEN_BUDGET,
             basis: CODEX_TOKEN_BUDGET_PREFLIGHT_BASIS

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

@@ -472,7 +472,7 @@ export type { ContextC5EnvelopeV1, ContextEvidence, ContextShadowDecisionV1, Con
 export { CONTEXT_MANIFEST_VERSION, CONTEXT_LEDGER_VERSION } from "./context-manifest.js";
 export type { ContinuationCheckpoint, ContextBudget, ContextCandidateDecision, ContextFaultRequest, ContextFaultResult, ContextKind, ContextLedgerEntry, ContextManifest, ContextObject, ContextPolicy, ContextPriority, ContextSensitivity, ContextTrust, TaskItem, UsageEvidence } from "./context-manifest.js";
 export { EVIDENCE_STATUSES, EXECUTION_MODES, TEST_INTEGRITY_STATUSES, TEST_INTEGRITY_VERDICTS, VERIFIED_HANDOFF_OUTCOMES, } from "./verified-handoff.js";
-export type { EvidenceStatus, ExecutionMode, TestIntegrityStatus, TestIntegrityVerdict, VerifiedHandoffCheckV1, VerifiedHandoffOutcome, VerifiedHandoffRecoveryV1, VerifiedHandoffRequirementV1, VerifiedHandoffScopeV1, VerifiedHandoffTestIntegrityV1, VerifiedHandoffV1, } from "./verified-handoff.js";
+export type { EvidenceStatus, ExecutionMode, TestIntegrityStatus, TestIntegrityVerdict, VerifiedHandoffCheckV1, VerifiedHandoffExhaustedLimitV1, VerifiedHandoffFileEffectsV1, VerifiedHandoffLifecycleTruthV1, VerifiedHandoffOutcome, VerifiedHandoffRecoveryV1, VerifiedHandoffRequirementV1, VerifiedHandoffScopeV1, VerifiedHandoffTestIntegrityV1, VerifiedHandoffV1, } from "./verified-handoff.js";
 export { HANDOFF_SCHEMA_VERSION } from "./context-handoff.js";
 export type { ChainIntegrityState, ContextCircuitBreakResult, ContextExclusionDecision, ContextHandoffArtifact, ContextHandoffClaim, ContextHandoffReceipt, ContextHandoffVerification, HandoffClaimState } from "./context-handoff.js";
 export { MISSION_SCHEMA_VERSION, MISSION_STATUSES, ALLOWED_MISSION_TRANSITIONS, createMissionRecord, isMissionTransitionAllowed } from './mission.js';

package/dist/vendor/contracts/verified-handoff.d.ts

@@ -1,4 +1,5 @@
 import type { CostProvenance, LoopLifecycleState, LoopStatus, ReceiptIntegritySummary } from "./index.js";
+import type { ExitKind } from "./exits.js";
 export declare const VERIFIED_HANDOFF_OUTCOMES: readonly ["VERIFIED", "STOPPED", "NEEDS_REVIEW"];
 export type VerifiedHandoffOutcome = (typeof VERIFIED_HANDOFF_OUTCOMES)[number];
 export declare const EXECUTION_MODES: readonly ["governed", "verification_only", "simulated"];
@@ -59,6 +60,24 @@ export interface VerifiedHandoffRecoveryV1 {
     nextCommand?: string;
     summary: string;
 }
+export type VerifiedHandoffExhaustedLimitV1 = "usd" | "tokens" | "iterations" | "wall_clock";
+export interface VerifiedHandoffLifecycleTruthV1 {
+    executionStatus: LoopStatus;
+    lifecycleState: LoopLifecycleState;
+    terminationClass: "operational_exit" | "guard_stop" | "none";
+    reasonCode?: ExitKind | string;
+    reason?: string;
+    matchedReasons: ExitKind[];
+    exhaustedLimits: VerifiedHandoffExhaustedLimitV1[];
+    evidenceAvailable: boolean;
+}
+export interface VerifiedHandoffFileEffectsV1 {
+    observationStatus: "observed" | "unavailable";
+    touchedDuringExecution: string[];
+    netChangedAtCompletion: string[];
+    revertedBeforeCompletion: string[];
+    observationReason?: string;
+}
 export interface VerifiedHandoffV1 {
     schemaVersion: "1.0.0";
     handoffId: string;
@@ -81,6 +100,8 @@ export interface VerifiedHandoffV1 {
         status: LoopStatus;
         lifecycleState: LoopLifecycleState;
     };
+    lifecycleTruth: VerifiedHandoffLifecycleTruthV1;
+    fileEffects: VerifiedHandoffFileEffectsV1;
     verification: {
         status: EvidenceStatus;
         summary: string;

package/dist/vendor/core/external-outcome.js

@@ -71,7 +71,12 @@ export async function verifyExternalOutcomes(contract, options = {}) {
                 return;
             }
             if (observation.kind === "transient") {
-                state.lastTransient = observation.reasonCode;
+                // A final request may inherit only the milliseconds left in the
+                // contract-wide deadline. Do not let that verifier-side timeout erase
+                // a concrete source failure observed by an earlier poll.
+                if (observation.reasonCode !== "deadline_exceeded" || state.observationCount === 1) {
+                    state.lastTransient = observation.reasonCode;
+                }
                 state.nextPollAt = performance.now() + contract.pollIntervalMs;
                 return;
             }

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

@@ -32,7 +32,7 @@ export { runContextIntegrityPrecheck } from "./context-integrity.js";
 export type { ContextIntegrityPrecheck, ContextIntegrityVerdict } from "./context-integrity.js";
 export { compilePromptPacket } from "./compiler.js";
 export type { PromptPacket, CompilerAdapterRequest } from "./compiler.js";
-export { buildVerifiedHandoff, deriveVerifiedHandoffExecutionBoundary, resolveVerifiedHandoffOutcome, toTestIntegrityVerdict, verifierActuallyPassed, } from "./verified-handoff.js";
+export { buildVerifiedHandoff, deriveVerifiedHandoffLifecycleTruth, deriveVerifiedHandoffExecutionBoundary, resolveVerifiedHandoffOutcome, toTestIntegrityVerdict, verifierActuallyPassed, } from "./verified-handoff.js";
 export type { BoundVerifierEvidence, BuildVerifiedHandoffInput, VerifierExecutionBinding, } from "./verified-handoff.js";
 export { createFileRunStore, makeLedgerEvent, readAllLoopRecords, readLatestLoopRecord, readLatestLoopRecordFromFile, readLoopRecordsFromFile, resolveRunsRoot, resolveReceiptIntegrityPath, verifyReceiptIntegrityFromFiles, writeReceiptIntegrityMaterial } from "./persistence/index.js";
 export type { AttemptArtifacts, LedgerEvent, LedgerEventKind, LoopAttemptRecord, LoopRunRecord, ReceiptIntegrityChainEntry, RunContract, RunStore, StoredReceiptIntegrityMaterial } from "./persistence/index.js";

package/dist/vendor/core/index.js

@@ -32,7 +32,7 @@ export { runContextIntegrityPrecheck } from "./context-integrity.js";
 // ─── Prompt packet compiler ──────────────────────────────────────────────────
 export { compilePromptPacket } from "./compiler.js";
 // ─── Verified Handoff builder ────────────────────────────────────────────────
-export { buildVerifiedHandoff, deriveVerifiedHandoffExecutionBoundary, resolveVerifiedHandoffOutcome, toTestIntegrityVerdict, verifierActuallyPassed, } from "./verified-handoff.js";
+export { buildVerifiedHandoff, deriveVerifiedHandoffLifecycleTruth, deriveVerifiedHandoffExecutionBoundary, resolveVerifiedHandoffOutcome, toTestIntegrityVerdict, verifierActuallyPassed, } from "./verified-handoff.js";
 // ─── Persistence (RunStore, LedgerEvent, FileRunStore) ──────────────────────
 export { createFileRunStore, makeLedgerEvent, readAllLoopRecords, readLatestLoopRecord, readLatestLoopRecordFromFile, readLoopRecordsFromFile, resolveRunsRoot, resolveReceiptIntegrityPath, verifyReceiptIntegrityFromFiles, writeReceiptIntegrityMaterial } from "./persistence/index.js";
 export { compileAndPersistContext } from "./persistence/index.js";
@@ -186,6 +186,67 @@ export async function runMartin(input) {
             transport: getAdapterTransport(input.adapter)
         }
     }, { now: now(), idFactory });
+    const adapterChain = [input.adapter, ...(input.fallbackAdapters ?? [])];
+    const runsRoot = input.store?.runsRoot ?? resolveRunsRoot();
+    const observesWorkspaceMutations = input.task.repoRoot !== undefined &&
+        adapterChain.some((adapter) => adapter.metadata.capabilities?.workspaceMutations !== false);
+    const touchedDuringExecution = new Set();
+    let completionBoundary;
+    let completionBoundaryReason;
+    if (observesWorkspaceMutations) {
+        try {
+            completionBoundary = await captureRollbackBoundary({
+                repoRoot: input.task.repoRoot,
+                capturedAt: loop.createdAt
+            });
+            if (!completionBoundary) {
+                completionBoundaryReason = "A run-wide file-effect observation boundary was not available.";
+            }
+        }
+        catch (error) {
+            completionBoundaryReason = `Run-wide file-effect observation was unavailable: ${fileEffectErrorMessage(error)}`;
+        }
+    }
+    else {
+        completionBoundaryReason =
+            "A mutation-capable run-wide file-effect observation boundary was not available.";
+    }
+    async function finalizeCurrentLoop(decision, timestamp, routingEconomicsInput) {
+        const fileEffects = observeRunFileEffects({
+            repoRoot: input.task.repoRoot,
+            boundary: completionBoundary,
+            touchedDuringExecution,
+            unavailableReason: completionBoundaryReason
+        });
+        return finalizeLoop(loop, decision, timestamp, idFactory, routingEconomicsInput, fileEffects);
+    }
+    async function persistGuardStop(decision) {
+        const envelope = {
+            schemaVersion: "termination/1",
+            class: "guard_stop",
+            guard: {
+                reasonCode: decision.reasonCode ?? "guard_stop",
+                reason: decision.reason,
+                ...(decision.failureClass ? { failureClass: decision.failureClass } : {}),
+                ...(decision.safetySurface ? { safetySurface: decision.safetySurface } : {})
+            }
+        };
+        if (input.store) {
+            await persistTerminationEnvelope(runDir(runsRoot, loop.loopId), envelope);
+            await input.store.appendLedger(loop.loopId, makeLedgerEvent({
+                kind: "run.terminated",
+                runId: loop.loopId,
+                payload: {
+                    terminationClass: envelope.class,
+                    reasonCode: envelope.guard.reasonCode,
+                    reason: envelope.guard.reason,
+                    ...(envelope.guard.failureClass ? { failureClass: envelope.guard.failureClass } : {}),
+                    ...(envelope.guard.safetySurface ? { safetySurface: envelope.guard.safetySurface } : {})
+                }
+            }));
+        }
+        return envelope;
+    }
     if (input.store) {
         await input.store.initRun({
             runId: loop.loopId,
@@ -255,7 +316,7 @@ export async function runMartin(input) {
                 reason: handoffGate.message ?? "Context handoff verification failed.",
                 reasonCode: handoffGate.reasonCode ?? "handoff_verification_failed"
             };
-            const finalizedLoop = finalizeLoop(loop, handoffExitDecision, now(), idFactory);
+            const finalizedLoop = await finalizeCurrentLoop(handoffExitDecision, now());
             await persistLoopRecordIfSupported(input.store, finalizedLoop);
             return { loop: finalizedLoop, decision: handoffExitDecision };
         }
@@ -272,7 +333,6 @@ export async function runMartin(input) {
             }));
         }
     }
-    const adapterChain = [input.adapter, ...(input.fallbackAdapters ?? [])];
     let currentAdapterIndex = 0;
     let currentAdapter = adapterChain[currentAdapterIndex] ?? input.adapter;
     let useCompressedContext = false;
@@ -313,10 +373,12 @@ export async function runMartin(input) {
                 payload: createRunExitPayload(leashExitDecision)
             }));
         }
-        const finalizedLoop = finalizeLoop(loop, leashExitDecision, now(), idFactory);
-        await persistLoopRecordIfSupported(input.store, finalizedLoop);
+        const terminationEnvelope = await persistGuardStop(leashExitDecision);
+        const finalizedLoop = await finalizeCurrentLoop(leashExitDecision, now());
+        const finalizedWithEnvelope = { ...finalizedLoop, terminationEnvelope };
+        await persistLoopRecordIfSupported(input.store, finalizedWithEnvelope);
         return {
-            loop: finalizedLoop,
+            loop: finalizedWithEnvelope,
             decision: leashExitDecision
         };
     }
@@ -351,10 +413,12 @@ export async function runMartin(input) {
                 payload: createRunExitPayload(secretExitDecision)
             }));
         }
-        const finalizedLoop = finalizeLoop(loop, secretExitDecision, now(), idFactory);
-        await persistLoopRecordIfSupported(input.store, finalizedLoop);
+        const terminationEnvelope = await persistGuardStop(secretExitDecision);
+        const finalizedLoop = await finalizeCurrentLoop(secretExitDecision, now());
+        const finalizedWithEnvelope = { ...finalizedLoop, terminationEnvelope };
+        await persistLoopRecordIfSupported(input.store, finalizedWithEnvelope);
         return {
-            loop: finalizedLoop,
+            loop: finalizedWithEnvelope,
             decision: secretExitDecision
         };
     }
@@ -380,7 +444,6 @@ export async function runMartin(input) {
     // governedTurnsUsed starts from the already-completed attempt count so
     // resumed runs count correctly; incremented once per governed attempt.
     let governedTurnsUsed = loop.attempts.length;
-    const runsRoot = input.store?.runsRoot ?? resolveRunsRoot();
     const exitSignalSource = input.exitSignalSource ?? createFileExitSignalSource(runsRoot);
     // Diagnostic writes fire from sync callbacks — track them so the finally
     // block can await completion before the run tears down.
@@ -571,7 +634,7 @@ export async function runMartin(input) {
         // persistLoopRecordIfSupported reads ledger.jsonl to compute the integrity hash;
         // any write that lands after that read produces a false ledger_hash_mismatch on verify.
         await stopSignalMonitorAndDrainDiagnostics();
-        const finalizedLoop = finalizeLoop(loop, exitDecision, now(), idFactory, routingInput);
+        const finalizedLoop = await finalizeCurrentLoop(exitDecision, now(), routingInput);
         const finalizedWithEnvelope = { ...finalizedLoop, terminationEnvelope: envelope };
         await persistLoopRecordIfSupported(input.store, finalizedWithEnvelope);
         return { loop: finalizedWithEnvelope, decision: exitDecision };
@@ -625,7 +688,7 @@ export async function runMartin(input) {
                     }));
                 }
                 await stopSignalMonitorAndDrainDiagnostics();
-                const finalizedLoop = finalizeLoop(loop, preflightExitDecision, now(), idFactory);
+                const finalizedLoop = await finalizeCurrentLoop(preflightExitDecision, now());
                 await persistLoopRecordIfSupported(input.store, finalizedLoop);
                 return {
                     loop: finalizedLoop,
@@ -674,10 +737,12 @@ export async function runMartin(input) {
                     }));
                 }
                 await stopSignalMonitorAndDrainDiagnostics();
-                const finalizedLoop = finalizeLoop(loop, poisoningExitDecision, now(), idFactory);
-                await persistLoopRecordIfSupported(input.store, finalizedLoop);
+                const terminationEnvelope = await persistGuardStop(poisoningExitDecision);
+                const finalizedLoop = await finalizeCurrentLoop(poisoningExitDecision, now());
+                const finalizedWithEnvelope = { ...finalizedLoop, terminationEnvelope };
+                await persistLoopRecordIfSupported(input.store, finalizedWithEnvelope);
                 return {
-                    loop: finalizedLoop,
+                    loop: finalizedWithEnvelope,
                     decision: poisoningExitDecision
                 };
             }
@@ -738,7 +803,7 @@ export async function runMartin(input) {
                     }));
                 }
                 await stopSignalMonitorAndDrainDiagnostics();
-                const finalizedLoop = finalizeLoop(loop, exitDecision, now(), idFactory);
+                const finalizedLoop = await finalizeCurrentLoop(exitDecision, now());
                 await persistLoopRecordIfSupported(input.store, finalizedLoop);
                 return {
                     loop: finalizedLoop,
@@ -1011,6 +1076,9 @@ export async function runMartin(input) {
             const changedFiles = tracksWorkspaceMutations
                 ? resolveChangedFiles(result, request.context.repoRoot, rollbackBoundary)
                 : [];
+            for (const filePath of normalizeFileEffectPaths(changedFiles)) {
+                touchedDuringExecution.add(filePath);
+            }
             // Routing economics: detect first meaningful workspace delta
             if (!firstDeltaDetected && changedFiles.length > 0) {
                 const meaningfulFile = changedFiles.find((f) => !isMartinLoopMetadata(f));
@@ -1099,10 +1167,12 @@ export async function runMartin(input) {
                     }));
                 }
                 await stopSignalMonitorAndDrainDiagnostics();
-                const finalizedLoop = finalizeLoop(loop, filesystemExitDecision, now(), idFactory);
-                await persistLoopRecordIfSupported(input.store, finalizedLoop);
+                const terminationEnvelope = await persistGuardStop(filesystemExitDecision);
+                const finalizedLoop = await finalizeCurrentLoop(filesystemExitDecision, now());
+                const finalizedWithEnvelope = { ...finalizedLoop, terminationEnvelope };
+                await persistLoopRecordIfSupported(input.store, finalizedWithEnvelope);
                 return {
-                    loop: finalizedLoop,
+                    loop: finalizedWithEnvelope,
                     decision: filesystemExitDecision
                 };
             }
@@ -1177,10 +1247,12 @@ export async function runMartin(input) {
                     }));
                 }
                 await stopSignalMonitorAndDrainDiagnostics();
-                const finalizedLoop = finalizeLoop(loop, approvalExitDecision, now(), idFactory);
-                await persistLoopRecordIfSupported(input.store, finalizedLoop);
+                const terminationEnvelope = await persistGuardStop(approvalExitDecision);
+                const finalizedLoop = await finalizeCurrentLoop(approvalExitDecision, now());
+                const finalizedWithEnvelope = { ...finalizedLoop, terminationEnvelope };
+                await persistLoopRecordIfSupported(input.store, finalizedWithEnvelope);
                 return {
-                    loop: finalizedLoop,
+                    loop: finalizedWithEnvelope,
                     decision: approvalExitDecision
                 };
             }
@@ -1320,7 +1392,7 @@ export async function runMartin(input) {
                     }));
                 }
                 await stopSignalMonitorAndDrainDiagnostics();
-                const finalizedLoop = finalizeLoop(loop, patchExitDecision, now(), idFactory);
+                const finalizedLoop = await finalizeCurrentLoop(patchExitDecision, now());
                 await persistLoopRecordIfSupported(input.store, finalizedLoop);
                 return {
                     loop: finalizedLoop,
@@ -1414,7 +1486,7 @@ export async function runMartin(input) {
                 // Drain pending diagnostic ledger writes before receipt signing.
                 await stopSignalMonitorAndDrainDiagnostics();
                 const routingInput = { runStartMs, firstDeltaDetected, firstDeltaTimestampMs, firstDeltaFilePath, firstDeltaChangeType, preDeltaCostUsd };
-                const finalizedLoop = finalizeLoop(loop, decision, now(), idFactory, routingInput);
+                const finalizedLoop = await finalizeCurrentLoop(decision, now(), routingInput);
                 await persistLoopRecordIfSupported(input.store, finalizedLoop);
                 return {
                     loop: finalizedLoop,
@@ -1422,28 +1494,11 @@ export async function runMartin(input) {
                 };
             }
         }
-        const decision = {
-            shouldExit: true,
-            lifecycleState: "budget_exit",
-            status: "exited",
-            reason: "Martin exited because the loop exhausted its configured iteration budget."
-        };
-        if (input.store) {
-            await input.store.appendLedger(loop.loopId, makeLedgerEvent({
-                kind: "run.exited",
-                runId: loop.loopId,
-                payload: createRunExitPayload(decision)
-            }));
+        const exhaustedTerminal = await evaluateCheckpoint("before_retry");
+        if (!exhaustedTerminal) {
+            throw new Error("Loop exhausted its configured iterations without an exit-policy decision.");
         }
-        // Drain pending diagnostic ledger writes before receipt signing.
-        await stopSignalMonitorAndDrainDiagnostics();
-        const routingInput = { runStartMs, firstDeltaDetected, firstDeltaTimestampMs, firstDeltaFilePath, firstDeltaChangeType, preDeltaCostUsd };
-        const finalizedLoop = finalizeLoop(loop, decision, now(), idFactory, routingInput);
-        await persistLoopRecordIfSupported(input.store, finalizedLoop);
-        return {
-            loop: finalizedLoop,
-            decision
-        };
+        return await terminateRun(exhaustedTerminal);
     }
     finally {
         if (wallTimer !== undefined)
@@ -1499,11 +1554,14 @@ function safetyLeashReasonCode(decision, safetySurface) {
             return `${safetySurface}_safety_block`;
     }
 }
-function finalizeLoop(loop, decision, timestamp, idFactory, routingEconomicsInput) {
+function finalizeLoop(loop, decision, timestamp, idFactory, routingEconomicsInput, fileEffects) {
     const finalized = appendLoopEvent(loop, {
         type: "run.completed",
         lifecycleState: decision.lifecycleState,
-        payload: createRunExitPayload(decision)
+        payload: {
+            ...createRunExitPayload(decision),
+            ...(fileEffects ? { fileEffects } : {})
+        }
     }, { now: timestamp, idFactory });
     const routingEconomics = routingEconomicsInput
         ? buildRoutingEconomics(finalized, routingEconomicsInput, decision)
@@ -1522,6 +1580,49 @@ function finalizeLoop(loop, decision, timestamp, idFactory, routingEconomicsInpu
         ...(routingEconomics ? { routingEconomics } : {})
     };
 }
+function observeRunFileEffects(input) {
+    const touchedDuringExecution = normalizeFileEffectPaths(input.touchedDuringExecution);
+    if (!input.repoRoot || !input.boundary) {
+        return {
+            observationStatus: "unavailable",
+            touchedDuringExecution,
+            netChangedAtCompletion: [],
+            revertedBeforeCompletion: [],
+            observationReason: input.unavailableReason ??
+                "A run-wide file-effect observation boundary was not available."
+        };
+    }
+    try {
+        const netChangedAtCompletion = normalizeFileEffectPaths(listAttemptChangedFilesSinceBoundary({
+            repoRoot: input.repoRoot,
+            boundary: input.boundary
+        }));
+        const netChanged = new Set(netChangedAtCompletion);
+        return {
+            observationStatus: "observed",
+            touchedDuringExecution,
+            netChangedAtCompletion,
+            revertedBeforeCompletion: touchedDuringExecution.filter((filePath) => !netChanged.has(filePath))
+        };
+    }
+    catch (error) {
+        return {
+            observationStatus: "unavailable",
+            touchedDuringExecution,
+            netChangedAtCompletion: [],
+            revertedBeforeCompletion: [],
+            observationReason: `Final file-effect observation was unavailable: ${fileEffectErrorMessage(error)}`
+        };
+    }
+}
+function normalizeFileEffectPaths(paths) {
+    return [...new Set([...paths]
+            .map((filePath) => filePath.replaceAll("\\", "/").replace(/^\.\//u, "").trim())
+            .filter(Boolean))].sort();
+}
+function fileEffectErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function buildRoutingEconomics(loop, input, decision) {
     const totalCost = loop.cost.actualUsd;
     const preworkCost = roundUsd(Math.max(input.preDeltaCostUsd, 0));
@@ -1614,10 +1715,17 @@ function mergeCostProvenance(previous, current) {
     return COST_PROVENANCE_RANK[current] < COST_PROVENANCE_RANK[previous] ? current : previous;
 }
 function resolveChangedFiles(result, repoRoot, rollbackBoundary) {
-    if (result.execution?.changedFiles !== undefined) {
-        return result.execution.changedFiles;
+    const adapterReported = normalizeFileEffectPaths(result.execution?.changedFiles ?? []);
+    try {
+        const gitObserved = listAttemptChangedFilesSinceBoundary({ repoRoot, boundary: rollbackBoundary });
+        return normalizeFileEffectPaths([...adapterReported, ...gitObserved]);
+    }
+    catch (error) {
+        if (result.execution?.changedFiles !== undefined) {
+            return adapterReported;
+        }
+        throw error;
     }
-    return listAttemptChangedFilesSinceBoundary({ repoRoot, boundary: rollbackBoundary });
 }
 function buildPatchDiff(result, changedFiles) {
     if (result.execution?.patch) {

package/dist/vendor/core/verified-handoff.d.ts

@@ -1,5 +1,6 @@
-import type { ExecutionMode, LoopRecord, ReceiptIntegritySummary, TestIntegrityStatus, TestIntegrityVerdict, VerifiedHandoffOutcome, VerifiedHandoffRecoveryV1, VerifiedHandoffRequirementV1, VerifiedHandoffScopeV1, VerifiedHandoffTestIntegrityV1, VerifiedHandoffV1 } from "../contracts/index.js";
+import type { ExecutionMode, ExitKind, LoopRecord, ReceiptIntegritySummary, TestIntegrityStatus, TestIntegrityVerdict, VerifiedHandoffFileEffectsV1, VerifiedHandoffLifecycleTruthV1, VerifiedHandoffOutcome, VerifiedHandoffRecoveryV1, VerifiedHandoffRequirementV1, VerifiedHandoffScopeV1, VerifiedHandoffTestIntegrityV1, VerifiedHandoffV1 } from "../contracts/index.js";
 export declare function toTestIntegrityVerdict(status: TestIntegrityStatus): TestIntegrityVerdict;
+export declare function deriveVerifiedHandoffLifecycleTruth(loop: LoopRecord): VerifiedHandoffLifecycleTruthV1;
 export interface VerifierExecutionBinding {
     runId: string;
     workspaceId: string;
@@ -25,6 +26,9 @@ export interface BoundVerifierEvidence {
 export declare function verifierActuallyPassed(evidence: BoundVerifierEvidence | null | undefined, expected: VerifierExecutionBinding): boolean;
 export declare function resolveVerifiedHandoffOutcome(input: {
     lifecycleState: LoopRecord["lifecycleState"];
+    sourceStatus?: LoopRecord["status"];
+    terminationClass?: VerifiedHandoffLifecycleTruthV1["terminationClass"];
+    reasonCode?: ExitKind | string;
     executionStatus?: "completed" | "write_blocked" | "sandbox_blocked" | "policy_rejected" | "failed";
     verificationStatus: BuildVerifiedHandoffInput["verification"]["status"];
     receiptIntegrity: ReceiptIntegritySummary["state"];
@@ -65,6 +69,7 @@ export interface BuildVerifiedHandoffInput {
     definitionOfDonePreSatisfied?: boolean;
     evidenceContradicted?: boolean;
     changedFiles?: string[];
+    fileEffects?: Partial<VerifiedHandoffFileEffectsV1>;
     scope?: Partial<VerifiedHandoffScopeV1>;
     testIntegrity?: Partial<VerifiedHandoffTestIntegrityV1>;
     requirements?: VerifiedHandoffRequirementV1[];

package/dist/vendor/core/verified-handoff.js

@@ -28,7 +28,66 @@ const STOPPED_LIFECYCLE_STATES = new Set([
     "diminishing_returns",
     "stuck_exit",
     "human_escalation",
+    "wall_clock",
+    "error_threshold",
+    "external_event",
 ]);
+export function deriveVerifiedHandoffLifecycleTruth(loop) {
+    const envelope = loop.terminationEnvelope;
+    if (envelope === undefined) {
+        return {
+            executionStatus: loop.status,
+            lifecycleState: loop.lifecycleState,
+            terminationClass: "none",
+            matchedReasons: [],
+            exhaustedLimits: [],
+            evidenceAvailable: false,
+        };
+    }
+    if (envelope.class === "guard_stop") {
+        return {
+            executionStatus: loop.status,
+            lifecycleState: loop.lifecycleState,
+            terminationClass: "guard_stop",
+            reasonCode: envelope.guard.reasonCode,
+            reason: envelope.guard.reason,
+            matchedReasons: [],
+            exhaustedLimits: [],
+            evidenceAvailable: true,
+        };
+    }
+    const primary = envelope.exit.primary;
+    const primaryMatch = envelope.exit.matches.find((match) => match.kind === primary);
+    const exhausted = new Set();
+    for (const match of envelope.exit.matches) {
+        if (match.kind === "turn_cap") {
+            exhausted.add("iterations");
+        }
+        else if (match.kind === "wall_clock") {
+            exhausted.add("wall_clock");
+        }
+        else if (match.kind === "budget_cap") {
+            if (match.evidence["usdExceeded"] === true) {
+                exhausted.add("usd");
+            }
+            if (match.evidence["tokensExceeded"] === true) {
+                exhausted.add("tokens");
+            }
+        }
+    }
+    const exhaustedLimits = ["usd", "tokens", "iterations", "wall_clock"]
+        .filter((limit) => exhausted.has(limit));
+    return {
+        executionStatus: loop.status,
+        lifecycleState: loop.lifecycleState,
+        terminationClass: "operational_exit",
+        ...(primary ? { reasonCode: primary } : {}),
+        ...(primaryMatch?.reason ? { reason: primaryMatch.reason } : {}),
+        matchedReasons: [...envelope.exit.matched],
+        exhaustedLimits,
+        evidenceAvailable: true,
+    };
+}
 export function verifierActuallyPassed(evidence, expected) {
     if (!evidence?.passed || !evidence.binding || !evidence.steps) {
         return false;
@@ -58,12 +117,19 @@ export function verifierActuallyPassed(evidence, expected) {
 }
 export function resolveVerifiedHandoffOutcome(input) {
     if (STOPPED_LIFECYCLE_STATES.has(input.lifecycleState) ||
+        input.terminationClass === "guard_stop" ||
+        (input.terminationClass === "operational_exit" &&
+            input.reasonCode !== undefined &&
+            input.reasonCode !== "goal_met") ||
         input.executionStatus === "write_blocked" ||
         input.executionStatus === "sandbox_blocked" ||
         input.executionStatus === "policy_rejected") {
         return "STOPPED";
     }
-    if (input.executionStatus === "failed" ||
+    if (input.sourceStatus !== "completed" ||
+        input.terminationClass !== "operational_exit" ||
+        input.reasonCode !== "goal_met" ||
+        input.executionStatus === "failed" ||
         input.governanceClaimEligible === false ||
         input.evidenceContradicted === true ||
         (input.mutationRequired === true &&
@@ -145,6 +211,18 @@ export function buildVerifiedHandoff(input) {
     const generatedAt = input.generatedAt ?? new Date().toISOString();
     const changedFiles = input.changedFiles ?? [];
     const unresolvedWork = input.unresolvedWork ?? [];
+    const lifecycleTruth = deriveVerifiedHandoffLifecycleTruth(input.loop);
+    const fileEffects = {
+        observationStatus: input.fileEffects?.observationStatus ?? "unavailable",
+        touchedDuringExecution: [...(input.fileEffects?.touchedDuringExecution ?? [])],
+        netChangedAtCompletion: [...(input.fileEffects?.netChangedAtCompletion ?? [])],
+        revertedBeforeCompletion: [...(input.fileEffects?.revertedBeforeCompletion ?? [])],
+        ...(input.fileEffects?.observationReason
+            ? { observationReason: input.fileEffects.observationReason }
+            : input.fileEffects?.observationStatus === "observed"
+                ? {}
+                : { observationReason: "File-effect evidence was not recorded for this run." }),
+    };
     const scope = {
         status: input.scope?.status ?? "NOT_EVALUATED",
         allowedPaths: input.scope?.allowedPaths ?? input.loop.task.allowedPaths ?? [],
@@ -163,12 +241,35 @@ export function buildVerifiedHandoff(input) {
             "Test integrity was not evaluated for this run.",
     };
     const executionBoundary = deriveVerifiedHandoffExecutionBoundary(input.loop);
-    const verifierStepsActuallyPassed = input.verification.steps.length > 0 &&
-        input.verification.steps.every((step) => step.launched === true &&
-            step.completed === true &&
-            step.crashed === false &&
-            step.timedOut !== true &&
-            step.exitCode === 0);
+    const expectedVerifierBinding = input.verification.binding
+        ? {
+            runId: input.loop.loopId,
+            workspaceId: input.loop.workspaceId,
+            ...(input.loop.attempts.at(-1)?.attemptId
+                ? { attemptId: input.loop.attempts.at(-1)?.attemptId }
+                : {}),
+            cwd: input.loop.receiptScope?.workingDirectory ??
+                input.loop.task.repoRoot ??
+                input.verification.binding.cwd,
+            ...(input.loop.receiptScope?.runsRoot
+                ? { runsRoot: input.loop.receiptScope.runsRoot }
+                : {}),
+            ...(input.loop.task.executionProfile
+                ? { executionProfile: input.loop.task.executionProfile }
+                : {}),
+            ...(input.loop.task.allowedNetworkDomains?.length
+                ? { allowedNetworkDomains: [...input.loop.task.allowedNetworkDomains] }
+                : {}),
+            commands: [...input.loop.task.verificationPlan],
+        }
+        : undefined;
+    const verifierStepsActuallyPassed = expectedVerifierBinding
+        ? verifierActuallyPassed({
+            passed: input.verification.status === "passed",
+            binding: input.verification.binding,
+            steps: input.verification.steps,
+        }, expectedVerifierBinding)
+        : false;
     const effectiveVerificationStatus = input.verification.status === "passed" && !verifierStepsActuallyPassed
         ? input.verification.steps.length === 0
             ? "not_run"
@@ -182,6 +283,9 @@ export function buildVerifiedHandoff(input) {
     ];
     const outcome = resolveVerifiedHandoffOutcome({
         lifecycleState: input.loop.lifecycleState,
+        sourceStatus: input.loop.status,
+        terminationClass: lifecycleTruth.terminationClass,
+        reasonCode: lifecycleTruth.reasonCode,
         executionStatus: input.executionStatus,
         verificationStatus: effectiveVerificationStatus,
         receiptIntegrity: input.receiptIntegrity.state,
@@ -218,6 +322,8 @@ export function buildVerifiedHandoff(input) {
             status: input.loop.status,
             lifecycleState: input.loop.lifecycleState,
         },
+        lifecycleTruth,
+        fileEffects,
         verification: {
             status: toEvidenceStatus(effectiveVerificationStatus),
             summary: input.verification.summary,

package/dist/vendor/presentation/verified-handoff.js

@@ -50,17 +50,57 @@ function formatCost(usd, provenance) {
 function resolveHandoffAuthority(handoff) {
     const executionMode = handoff.executionMode ?? "simulated";
     const governanceClaimEligible = executionMode === "governed" && handoff.governanceClaimEligible === true;
-    const effectiveOutcome = handoff.outcome === "VERIFIED" && !governanceClaimEligible
+    const lifecycleTruth = handoff.lifecycleTruth;
+    const canonicalEvidenceSupportsVerified = governanceClaimEligible &&
+        handoff.sourceStatus.status === "completed" &&
+        handoff.sourceStatus.lifecycleState === "completed" &&
+        lifecycleTruth !== undefined &&
+        lifecycleTruth.evidenceAvailable === true &&
+        lifecycleTruth.terminationClass === "operational_exit" &&
+        lifecycleTruth.reasonCode === "goal_met" &&
+        handoff.fileEffects !== undefined &&
+        handoff.verification.status === "PASSED" &&
+        handoff.verification.checks.length > 0 &&
+        handoff.verification.checks.every((check) => check.status === "PASSED") &&
+        handoff.receiptIntegrity.state === "verified" &&
+        handoff.unresolvedWork.length === 0;
+    const effectiveOutcome = handoff.outcome === "VERIFIED" && !canonicalEvidenceSupportsVerified
         ? "NEEDS_REVIEW"
         : handoff.outcome;
     return { executionMode, governanceClaimEligible, effectiveOutcome };
 }
+function formatExecution(handoff) {
+    return `${humanize(handoff.sourceStatus.status)} / ${humanize(handoff.sourceStatus.lifecycleState)}`;
+}
+function formatTerminationReason(handoff) {
+    const truth = handoff.lifecycleTruth;
+    if (!truth?.evidenceAvailable)
+        return "unavailable";
+    if (!truth.reasonCode)
+        return truth.terminationClass === "none" ? "none" : "unknown";
+    return `${humanize(truth.reasonCode)}${truth.reason ? `: ${truth.reason}` : ""}`;
+}
+function formatExhaustedLimits(handoff) {
+    const truth = handoff.lifecycleTruth;
+    if (!truth?.evidenceAvailable)
+        return "unavailable";
+    return truth.exhaustedLimits.length > 0
+        ? truth.exhaustedLimits.map(humanize).join(", ")
+        : "none";
+}
+function formatFileEffectList(handoff, field) {
+    const effects = handoff.fileEffects;
+    if (!effects || effects.observationStatus === "unavailable")
+        return "unavailable";
+    return effects[field].length > 0 ? effects[field].join(", ") : "none";
+}
 export function renderVerifiedHandoff(handoff, options = {}) {
     const environment = options.environment ?? {};
     const width = terminalWidth(options.width);
     const bounded = (line) => truncateVisible(line, width);
     const { executionMode, governanceClaimEligible, effectiveOutcome } = resolveHandoffAuthority(handoff);
     const outcome = effectiveOutcome.replace("_", " ");
+    const labelWidth = 30;
     const checks = handoff.verification.checks.map((check) => ({
         check: check.command,
         status: paint(checkSymbol(check.status) + " " + check.status.replace("_", " "), evidenceTone(check.status), environment),
@@ -72,16 +112,22 @@ export function renderVerifiedHandoff(handoff, options = {}) {
             paint(outcome, outcomeTone(effectiveOutcome), environment),
         horizontalRule(width, "━"),
         "",
-        bounded("Task".padEnd(20) + handoff.task.objective),
-        bounded("Run".padEnd(20) + handoff.loopId),
-        bounded("Execution Mode".padEnd(20) + executionMode.replaceAll("_", " ")),
-        bounded("Governed Claim".padEnd(20) + (governanceClaimEligible ? "ELIGIBLE" : "INELIGIBLE")),
-        bounded("Verification".padEnd(20) + handoff.verification.status.replace("_", " ")),
-        bounded("Scope".padEnd(20) + handoff.scope.status.replaceAll("_", " ")),
-        bounded("Test Integrity".padEnd(20) + handoff.testIntegrity.verdict),
-        bounded("Receipt Integrity".padEnd(20) + handoff.receiptIntegrity.state),
-        bounded("Attempts".padEnd(20) + handoff.usage.attempts),
-        bounded("Cost".padEnd(20) +
+        bounded("Task".padEnd(labelWidth) + handoff.task.objective),
+        bounded("Run".padEnd(labelWidth) + handoff.loopId),
+        bounded("Execution Mode".padEnd(labelWidth) + executionMode.replaceAll("_", " ")),
+        bounded("Governed Claim".padEnd(labelWidth) + (governanceClaimEligible ? "ELIGIBLE" : "INELIGIBLE")),
+        bounded("Execution".padEnd(labelWidth) + formatExecution(handoff)),
+        bounded("Verification".padEnd(labelWidth) + handoff.verification.status.replace("_", " ")),
+        bounded("Receipt Integrity".padEnd(labelWidth) + handoff.receiptIntegrity.state),
+        bounded("Termination Reason".padEnd(labelWidth) + formatTerminationReason(handoff)),
+        bounded("Exhausted Limits".padEnd(labelWidth) + formatExhaustedLimits(handoff)),
+        bounded("Touched During Execution".padEnd(labelWidth) + formatFileEffectList(handoff, "touchedDuringExecution")),
+        bounded("Net Changed at Completion".padEnd(labelWidth) + formatFileEffectList(handoff, "netChangedAtCompletion")),
+        bounded("Reverted Before Completion".padEnd(labelWidth) + formatFileEffectList(handoff, "revertedBeforeCompletion")),
+        bounded("Scope".padEnd(labelWidth) + handoff.scope.status.replaceAll("_", " ")),
+        bounded("Test Integrity".padEnd(labelWidth) + handoff.testIntegrity.verdict),
+        bounded("Attempts".padEnd(labelWidth) + handoff.usage.attempts),
+        bounded("Cost".padEnd(labelWidth) +
             formatCost(handoff.usage.actualUsd, handoff.usage.costProvenance)),
     ];
     if (checks.length > 0) {
@@ -123,10 +169,16 @@ export function renderVerifiedHandoffMarkdown(handoff, options = {}) {
         `| Run | ${handoff.loopId} |`,
         `| Execution Mode | ${executionMode.replaceAll("_", " ")} |`,
         `| Governed Claim | ${governanceClaimEligible ? "ELIGIBLE" : "INELIGIBLE"} |`,
+        `| Execution | ${formatExecution(handoff)} |`,
         `| Verification | ${handoff.verification.status.replace("_", " ")} |`,
+        `| Receipt Integrity | ${handoff.receiptIntegrity.state} |`,
+        `| Termination Reason | ${formatTerminationReason(handoff)} |`,
+        `| Exhausted Limits | ${formatExhaustedLimits(handoff)} |`,
+        `| Touched During Execution | ${formatFileEffectList(handoff, "touchedDuringExecution")} |`,
+        `| Net Changed at Completion | ${formatFileEffectList(handoff, "netChangedAtCompletion")} |`,
+        `| Reverted Before Completion | ${formatFileEffectList(handoff, "revertedBeforeCompletion")} |`,
         `| Scope | ${handoff.scope.status.replaceAll("_", " ")} |`,
         `| Test Integrity | ${handoff.testIntegrity.verdict} |`,
-        `| Receipt Integrity | ${handoff.receiptIntegrity.state} |`,
         `| Attempts | ${handoff.usage.attempts} |`,
         `| Cost | ${formatCost(handoff.usage.actualUsd, handoff.usage.costProvenance)} |`,
     ];

package/package.json

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

package/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/Keesan12/martin-loop",
     "source": "github"
   },
-  "version": "0.8.2",
+  "version": "0.8.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@martinloop/mcp",
-      "version": "0.8.2",
+      "version": "0.8.4",
       "transport": {
         "type": "stdio"
       }