@martinloop/mcp 0.3.9 → 0.5.1

package/dist/vendor/contracts/delivery.js

@@ -0,0 +1,18 @@
+/**
+ * R4 Delivery — M1 Contract
+ *
+ * Shared with Lane B (Control Plane). Do not modify unilaterally.
+ * The server selects one message; the client never downloads the catalog.
+ */
+export const DELIVERY_MESSAGE_SCHEMA_VERSION = "delivery-message/1";
+export const DELIVERY_RECORD_SCHEMA_VERSION = "delivery-record/1";
+export const MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION = "martin-message-selection/1";
+export const ALLOWED_ACTION_TYPES = [
+    "upgrade_cli",
+    "upgrade_mcp",
+    "submit_feedback",
+    "open_release_notes",
+    "dismiss",
+    "view_spend_report",
+    "view_run_explain",
+];

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

@@ -0,0 +1,126 @@
+/**
+ * Exit contracts for the MartinLoop Eight-Exit Runtime.
+ *
+ * Precedence rationale (product decision — changing EXIT_PRECEDENCE in core
+ * requires updating this paragraph in the same commit):
+ *   1. human_interrupt and external_event outrank all others — they represent
+ *      authority external to the run's own evidence and cannot be argued with.
+ *   2. wall_clock, budget_cap, and turn_cap all outrank goal_met — governance
+ *      limits (time, cost, iterations) cannot be overridden by a simultaneously
+ *      verified goal; resource limits rank wall_clock > budget_cap > turn_cap.
+ *   3. turn_cap is suppressed at signal-generation time when the goal is already
+ *      met, so goal_met and turn_cap cannot co-occur in a well-formed evaluation.
+ *      Completing on the final permitted iteration is legitimate success, not an
+ *      overrun; turn_cap fires only when iterations are exhausted without
+ *      verified completion.
+ *   4. goal_met outranks error_threshold and no_progress — a deterministically
+ *      verified result takes priority over soft progress signals.
+ */
+export declare const EXIT_POLICY_VERSION: "exit-policy/1";
+export declare const EXIT_EVALUATION_VERSION: "exit-evaluation/1";
+export declare const EXIT_SIGNAL_VERSION: "exit-signal/1";
+export declare const TERMINATION_ENVELOPE_VERSION: "termination/1";
+export declare const EXIT_KINDS: readonly ["goal_met", "turn_cap", "budget_cap", "wall_clock", "no_progress", "human_interrupt", "error_threshold", "external_event"];
+export type ExitKind = (typeof EXIT_KINDS)[number];
+export type ExitEvaluationPhase = "pre_run" | "pre_attempt" | "post_attempt" | "before_retry" | "during_attempt";
+export type ExternalEventDisposition = "satisfied" | "superseded" | "cancelled";
+export interface ExternalExitEvent {
+    source: string;
+    event: string;
+    disposition: ExternalEventDisposition;
+    observedAt: string;
+    subject?: string;
+    reason?: string;
+    evidenceUri?: string;
+}
+export interface ExitPolicyV1 {
+    schemaVersion: typeof EXIT_POLICY_VERSION;
+    goal: {
+        verifierRequired: boolean;
+        minimumScore: number;
+    };
+    turns: {
+        max: number;
+    };
+    budget: {
+        maxUsd: number;
+        maxTokens: number;
+    };
+    wallClock: {
+        maxElapsedMs: number;
+        deadlineAt?: string;
+    };
+    progress: {
+        windowSize: number;
+        unchangedStateLimit: number;
+    };
+    errors: {
+        maxConsecutive: number;
+    };
+    humanInterrupt: {
+        enabled: boolean;
+    };
+    externalEvent: {
+        enabled: boolean;
+    };
+}
+export interface ExitSignalV1 {
+    schemaVersion: typeof EXIT_SIGNAL_VERSION;
+    runId: string;
+    kind: "human_interrupt" | "external_event";
+    requestedAt: string;
+    requestedBy: string;
+    reason?: string;
+    externalEvent?: ExternalExitEvent;
+}
+export interface ExitSnapshotV1 {
+    phase: ExitEvaluationPhase;
+    evaluatedAt: string;
+    runStartedAtMs: number;
+    nowMs: number;
+    turnsUsed: number;
+    actualUsd: number;
+    tokensUsed: number;
+    result?: {
+        status: "completed" | "failed";
+        verificationPassed: boolean;
+        verifierScore: number;
+    };
+    recentStateHashes: string[];
+    consecutiveErrors: number;
+    humanInterrupt?: ExitSignalV1;
+    externalEvent?: ExternalExitEvent;
+    trajectoryStop?: {
+        shouldStop: boolean;
+        reason: string;
+    };
+}
+export interface ExitMatchV1 {
+    kind: ExitKind;
+    reason: string;
+    evidence: Record<string, unknown>;
+}
+export interface ExitEvaluationV1 {
+    schemaVersion: typeof EXIT_EVALUATION_VERSION;
+    policyVersion: typeof EXIT_POLICY_VERSION;
+    shouldExit: boolean;
+    primary?: ExitKind;
+    matched: ExitKind[];
+    phase: ExitEvaluationPhase;
+    evaluatedAt: string;
+    matches: ExitMatchV1[];
+}
+export type TerminationEnvelopeV1 = {
+    schemaVersion: typeof TERMINATION_ENVELOPE_VERSION;
+    class: "operational_exit";
+    exit: ExitEvaluationV1;
+} | {
+    schemaVersion: typeof TERMINATION_ENVELOPE_VERSION;
+    class: "guard_stop";
+    guard: {
+        reasonCode: string;
+        reason: string;
+        failureClass?: string;
+        safetySurface?: string;
+    };
+};

package/dist/vendor/contracts/exits.js

@@ -0,0 +1,32 @@
+/**
+ * Exit contracts for the MartinLoop Eight-Exit Runtime.
+ *
+ * Precedence rationale (product decision — changing EXIT_PRECEDENCE in core
+ * requires updating this paragraph in the same commit):
+ *   1. human_interrupt and external_event outrank all others — they represent
+ *      authority external to the run's own evidence and cannot be argued with.
+ *   2. wall_clock, budget_cap, and turn_cap all outrank goal_met — governance
+ *      limits (time, cost, iterations) cannot be overridden by a simultaneously
+ *      verified goal; resource limits rank wall_clock > budget_cap > turn_cap.
+ *   3. turn_cap is suppressed at signal-generation time when the goal is already
+ *      met, so goal_met and turn_cap cannot co-occur in a well-formed evaluation.
+ *      Completing on the final permitted iteration is legitimate success, not an
+ *      overrun; turn_cap fires only when iterations are exhausted without
+ *      verified completion.
+ *   4. goal_met outranks error_threshold and no_progress — a deterministically
+ *      verified result takes priority over soft progress signals.
+ */
+export const EXIT_POLICY_VERSION = "exit-policy/1";
+export const EXIT_EVALUATION_VERSION = "exit-evaluation/1";
+export const EXIT_SIGNAL_VERSION = "exit-signal/1";
+export const TERMINATION_ENVELOPE_VERSION = "termination/1";
+export const EXIT_KINDS = [
+    "goal_met",
+    "turn_cap",
+    "budget_cap",
+    "wall_clock",
+    "no_progress",
+    "human_interrupt",
+    "error_threshold",
+    "external_event"
+];

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

@@ -1,9 +1,19 @@
+/**
+ * Contracts for the Martin Loop agentic system.
+ *
+ * This module defines the core type contracts and data structures for autonomous agent loop management,
+ * including loop lifecycle states, task definitions, budget tracking, cost accounting, verification,
+ * patch decisions, telemetry, and governance policies. It provides the public API surface for
+ * creating and managing loop records, handling events, validating batches, and tracking
+ * portfolio snapshots and routing economics.
+ */
+import type { TerminationEnvelopeV1 } from "./exits.js";
 export type LoopStatus = "queued" | "running" | "verifying" | "completed" | "failed" | "exited";
-export type LoopLifecycleState = "created" | "running" | "verifying" | "completed" | "budget_exit" | "diminishing_returns" | "stuck_exit" | "human_escalation";
+export type LoopLifecycleState = "created" | "running" | "verifying" | "completed" | "budget_exit" | "diminishing_returns" | "stuck_exit" | "human_escalation" | "wall_clock" | "error_threshold" | "external_event";
 export declare const FAILURE_CLASSES: readonly ["logic_error", "hallucination", "syntax_error", "type_error", "test_regression", "scope_creep", "no_progress", "repo_grounding_failure", "verification_failure", "environment_mismatch", "budget_pressure", "safety_leash_blocked", "sandbox_write_blocked"];
 export type FailureClass = (typeof FAILURE_CLASSES)[number];
 export type InterventionType = "compress_context" | "change_model" | "tighten_task" | "switch_adapter" | "run_verifier" | "escalate_human" | "stop_loop";
-export type LoopEventType = "run.started" | "attempt.started" | "attempt.completed" | "failure.classified" | "intervention.selected" | "verification.completed" | "budget.updated" | "run.completed";
+export type LoopEventType = "run.started" | "attempt.started" | "attempt.completed" | "failure.classified" | "intervention.selected" | "verification.completed" | "budget.updated" | "run.completed" | "run.terminated";
 export interface LoopTask {
     title: string;
     objective: string;
@@ -12,6 +22,8 @@ export interface LoopTask {
     verificationTimeoutMs?: number;
     verificationStack?: VerificationStep[];
     mutationMode?: MutationMode;
+    /** Explicit task-authority evidence that all definition-of-done criteria were satisfied before execution. */
+    definitionOfDonePreSatisfied?: boolean;
     executionProfile?: ExecutionProfile;
     allowedNetworkDomains?: string[];
     approvalPolicy?: ApprovalPolicy;
@@ -54,17 +66,27 @@ export interface LoopCost {
     estimatedUsd?: number;
     provenance?: CostProvenance;
     providerSettlement?: ProviderUsageSettlement;
+    savingsBaseline?: {
+        usd: number;
+        source: "measured_control" | "operator_supplied" | "fixture";
+        provenance: CostProvenance;
+    };
 }
-export type UsageSettlementSource = "claude_json" | "codex_jsonl" | "gemini_json" | "estimated_fallback" | "unavailable";
+export type UsageSettlementSource = "claude_json" | "codex_jsonl" | "gemini_json" | "openai_compatible_json" | "estimated_fallback" | "unavailable";
 export interface ProviderUsageSettlement {
     providerId: string;
-    model: string;
+    model?: string;
     transport?: "cli" | "http" | "routed_http";
     source: UsageSettlementSource;
     inputTokens: number;
     cachedInputTokens?: number;
     outputTokens: number;
     reasoningOutputTokens?: number;
+    cacheCreationInputTokens?: number;
+    billingMode?: "metered_api" | "subscription" | "local_unmetered" | "unknown";
+    modelSource?: "provider_reported" | "explicit_override" | "provider_configured" | "agent_default" | "unavailable";
+    pricingSource?: "provider_reported_total" | "static_catalog" | "blended_fallback" | "none";
+    pricingVersion?: string;
     rawUsageAvailable: boolean;
     settledAt: string;
 }
@@ -73,6 +95,16 @@ export interface ReceiptScope {
     workingDirectory?: string;
     invocationRoot?: string;
     runsRoot?: string;
+    /** Sandbox mode the mission requested before execution. */
+    requestedSandbox?: "read-only" | "workspace-write" | "danger-full-access";
+    /** Effective sandbox capability detected by pre-run filesystem probe. */
+    effectiveSandbox?: "read-only" | "workspace-write" | "unknown";
+    /** Absolute path that the filesystem write probe tested. */
+    writableRoot?: string;
+    /** How the effective sandbox was determined. */
+    capabilitySource?: "probe" | "configured" | "unknown";
+    /** Enforced demo changes (DEMO.md-only enforcement output). */
+    demoChangedFiles?: string[];
 }
 export type ReceiptIntegrityState = "verified" | "unsigned" | "tamper_detected" | "relocated" | "material_missing" | "selector_noncanonical";
 export interface ReceiptIntegritySummary {
@@ -119,7 +151,7 @@ export interface LoopAttempt {
     attemptId: string;
     index: number;
     adapterId: string;
-    model: string;
+    model?: string;
     startedAt: string;
     completedAt?: string;
     summary?: string;
@@ -156,6 +188,8 @@ export interface LoopRecord {
     receiptScope?: ReceiptScope;
     receiptIntegrity?: ReceiptIntegritySummary;
     routingEconomics?: RoutingEconomics;
+    /** Canonical termination identity written by finishFromEvaluation. Present when run ended via exit policy. */
+    terminationEnvelope?: TerminationEnvelopeV1;
 }
 export interface LoopRecordDraft {
     loopId?: string;
@@ -175,6 +209,7 @@ export interface LoopRecordDraft {
     updatedAt?: string;
     receiptScope?: ReceiptScope;
     receiptIntegrity?: ReceiptIntegritySummary;
+    terminationEnvelope?: TerminationEnvelopeV1;
 }
 export type { MartinErrorCategory, MartinOutputMode, MartinRunListFilters, MartinRunSelector } from "./operator.js";
 export { MARTIN_ERROR_CATEGORIES } from "./operator.js";
@@ -310,7 +345,7 @@ export interface MachineState {
  * Cost provenance label — every budget metric must carry this.
  * Never conflate actual with estimated or unavailable.
  */
-export type CostProvenance = "actual" | "estimated" | "unavailable";
+export type CostProvenance = "actual" | "calculated" | "estimated" | "unavailable";
 /**
  * Per-attempt budget preflight estimate produced before admission.
  * Used to gate attempts before any tokens are spent.
@@ -410,3 +445,17 @@ export { cloneIdentityAttestation, cloneIdentityClaims, cloneIdentityToken } fro
 export type { IdentityAttestation, IdentityClaims, IdentityToken } from "./identity.js";
 export { cloneCircuitBreakDecision, cloneTrajectoryAssessment } from "./trajectory.js";
 export type { CircuitBreakDecision, TrajectoryAssessment, TrajectorySignal } from "./trajectory.js";
+export { EXIT_KINDS, EXIT_POLICY_VERSION, EXIT_EVALUATION_VERSION, EXIT_SIGNAL_VERSION, TERMINATION_ENVELOPE_VERSION } from "./exits.js";
+export type { ExitKind, ExitEvaluationPhase, ExternalEventDisposition, ExternalExitEvent, ExitPolicyV1, ExitSignalV1, ExitSnapshotV1, ExitMatchV1, ExitEvaluationV1, TerminationEnvelopeV1 } from "./exits.js";
+export { ALLOWED_ACTION_TYPES, DELIVERY_MESSAGE_SCHEMA_VERSION, DELIVERY_RECORD_SCHEMA_VERSION, MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION } from "./delivery.js";
+export type { ActionType, DeliveryMessage, DeliveryRecord, MessageKind, MessageSelectionResponse, UpdateAvailableField } from "./delivery.js";
+export { CONTEXT_SHADOW_MANIFEST_VERSION, CONTEXT_C5_VERSION } from "./context-shadow.js";
+export type { ContextC5EnvelopeV1, ContextEvidence, ContextShadowDecisionV1, ContextShadowManifestV1, ContextShadowSegmentInput, ContextShadowSegmentKind } from "./context-shadow.js";
+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 { 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';
+export type { MissionStatus, MissionDecision, MissionBudget, MissionCost, MissionRunLink, MissionRunRole, MissionApproval, MissionOutcome, MissionEvent, MissionEventKind, MissionRecord, MissionDraft } from './mission.js';

package/dist/vendor/contracts/index.js

@@ -1,3 +1,12 @@
+/**
+ * Contracts for the Martin Loop agentic system.
+ *
+ * This module defines the core type contracts and data structures for autonomous agent loop management,
+ * including loop lifecycle states, task definitions, budget tracking, cost accounting, verification,
+ * patch decisions, telemetry, and governance policies. It provides the public API surface for
+ * creating and managing loop records, handling events, validating batches, and tracking
+ * portfolio snapshots and routing economics.
+ */
 export const FAILURE_CLASSES = [
     "logic_error",
     "hallucination",
@@ -53,6 +62,7 @@ export function createLoopRecord(draft, options = {}) {
         updatedAt: draft.updatedAt ?? now,
         ...(draft.receiptScope ? { receiptScope: draft.receiptScope } : {}),
         ...(draft.receiptIntegrity ? { receiptIntegrity: draft.receiptIntegrity } : {}),
+        ...(draft.terminationEnvelope ? { terminationEnvelope: draft.terminationEnvelope } : {}),
         ...(draft.teamId ? { teamId: draft.teamId } : {})
     };
 }
@@ -210,6 +220,8 @@ function nextStatus(current, eventType) {
             return "verifying";
         case "run.completed":
             return current === "failed" ? "failed" : "completed";
+        case "run.terminated":
+            return "exited";
         default:
             return current;
     }
@@ -223,3 +235,15 @@ 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";
+export { EXIT_KINDS, EXIT_POLICY_VERSION, EXIT_EVALUATION_VERSION, EXIT_SIGNAL_VERSION, TERMINATION_ENVELOPE_VERSION } from "./exits.js";
+// ─── R4 Delivery — M1 Contract ──────────────────────────────────────────────
+export { ALLOWED_ACTION_TYPES, DELIVERY_MESSAGE_SCHEMA_VERSION, DELIVERY_RECORD_SCHEMA_VERSION, MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION } from "./delivery.js";
+// ─── Context Shadow — A-CTX-0 ────────────────────────────────────────────────
+export { CONTEXT_SHADOW_MANIFEST_VERSION, CONTEXT_C5_VERSION } from "./context-shadow.js";
+// ─── Context Runtime — A-CTX-1 ───────────────────────────────────────────────
+export { CONTEXT_MANIFEST_VERSION, CONTEXT_LEDGER_VERSION } from "./context-manifest.js";
+// ─── Track A — Verified Handoff ───────────────────────────────────────────────
+export { EVIDENCE_STATUSES, EXECUTION_MODES, TEST_INTEGRITY_STATUSES, TEST_INTEGRITY_VERDICTS, VERIFIED_HANDOFF_OUTCOMES, } from "./verified-handoff.js";
+// ─── Context Handoff — A-CTX-2 ───────────────────────────────────────────────
+export { HANDOFF_SCHEMA_VERSION } from "./context-handoff.js";
+export { MISSION_SCHEMA_VERSION, MISSION_STATUSES, ALLOWED_MISSION_TRANSITIONS, createMissionRecord, isMissionTransitionAllowed } from './mission.js';

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

@@ -0,0 +1,102 @@
+/**
+ * Mission Governance contracts — C2
+ *
+ * A MissionRecord governs one software mission: intent → budget → runs →
+ * verification → decision → receipt. It never replaces LoopRecord; it
+ * aggregates above it.
+ *
+ * Invariants:
+ *   - One accountable human owner per mission.
+ *   - State transitions are append-only in the ledger.
+ *   - Ledger is the authority; mission.json is a rebuildable cache.
+ *   - A mission cannot become "verified" without verified run evidence.
+ *   - A mission cannot become "shipped" without an explicit ship decision.
+ *   - Unknown schema versions fail closed.
+ *   - Budgets cannot be raised silently.
+ */
+export declare const MISSION_SCHEMA_VERSION: "martin.mission.v1";
+export declare const MISSION_STATUSES: readonly ["planned", "running", "blocked", "verified", "shipped", "rolled_back", "killed"];
+export type MissionStatus = (typeof MISSION_STATUSES)[number];
+export declare const ALLOWED_MISSION_TRANSITIONS: Record<MissionStatus, readonly MissionStatus[]>;
+export type MissionDecision = "ship" | "retry" | "rollback" | "kill";
+export interface MissionBudget {
+    maxUsd: number;
+    maxTokens: number;
+    maxRuns: number;
+    maxConcurrentRuns: number;
+}
+export interface MissionCost {
+    /** Sum of actualUsd across all linked runs. */
+    totalActualUsd: number;
+    /** Number of linked runs with status "completed" (verified outcome). */
+    verifiedOutcomeCount: number;
+    /** Number of linked runs regardless of outcome. */
+    totalRunCount: number;
+}
+export type MissionRunRole = "primary" | "experiment" | "validation";
+export interface MissionRunLink {
+    loopId: string;
+    role: MissionRunRole;
+    attachedAt: string;
+    /** Set to true when the linked run completed with verification passed. */
+    verifiedOutcome?: boolean;
+    /** Actual cost of this run in USD. */
+    actualUsd?: number;
+}
+export interface MissionApproval {
+    approvalId: string;
+    kind: "ship" | "budget_increase" | "scope_change";
+    decision: "approved" | "denied";
+    approvedBy: string;
+    approvedAt: string;
+    note?: string;
+}
+export interface MissionOutcome {
+    decision: MissionDecision;
+    decidedAt: string;
+    decidedBy: string;
+    note?: string;
+}
+export type MissionEventKind = "mission.created" | "mission.status_changed" | "mission.run_attached" | "mission.run_verified" | "mission.approved" | "mission.closed" | "mission.collision_blocked";
+export interface MissionEvent {
+    eventId: string;
+    kind: MissionEventKind;
+    missionId: string;
+    timestamp: string;
+    payload: Record<string, unknown>;
+}
+export interface MissionRecord {
+    schemaVersion: typeof MISSION_SCHEMA_VERSION;
+    missionId: string;
+    /** Monotonically increasing write counter. Used for CAS enforcement. */
+    revision: number;
+    title: string;
+    objective: string;
+    ownerId: string;
+    workspaceId: string;
+    projectId: string;
+    status: MissionStatus;
+    budget: MissionBudget;
+    cost: MissionCost;
+    runLinks: MissionRunLink[];
+    approvals: MissionApproval[];
+    outcome?: MissionOutcome;
+    acceptanceCriteria: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MissionDraft {
+    missionId?: string;
+    title: string;
+    objective: string;
+    ownerId: string;
+    workspaceId: string;
+    projectId: string;
+    budget: MissionBudget;
+    acceptanceCriteria?: string[];
+}
+export declare function createMissionRecord(draft: MissionDraft, options?: {
+    now?: () => string;
+    idFactory?: (prefix: string) => string;
+}): MissionRecord;
+export declare function isMissionTransitionAllowed(from: MissionStatus, to: MissionStatus): boolean;

package/dist/vendor/contracts/mission.js

@@ -0,0 +1,64 @@
+/**
+ * Mission Governance contracts — C2
+ *
+ * A MissionRecord governs one software mission: intent → budget → runs →
+ * verification → decision → receipt. It never replaces LoopRecord; it
+ * aggregates above it.
+ *
+ * Invariants:
+ *   - One accountable human owner per mission.
+ *   - State transitions are append-only in the ledger.
+ *   - Ledger is the authority; mission.json is a rebuildable cache.
+ *   - A mission cannot become "verified" without verified run evidence.
+ *   - A mission cannot become "shipped" without an explicit ship decision.
+ *   - Unknown schema versions fail closed.
+ *   - Budgets cannot be raised silently.
+ */
+export const MISSION_SCHEMA_VERSION = "martin.mission.v1";
+// ─── Status and transitions ───────────────────────────────────────────────────
+export const MISSION_STATUSES = [
+    "planned",
+    "running",
+    "blocked",
+    "verified",
+    "shipped",
+    "rolled_back",
+    "killed"
+];
+export const ALLOWED_MISSION_TRANSITIONS = {
+    planned: ["running", "killed"],
+    running: ["blocked", "verified", "rolled_back", "killed"],
+    blocked: ["running", "rolled_back", "killed"],
+    verified: ["shipped", "running", "rolled_back", "killed"],
+    shipped: [],
+    rolled_back: ["running", "killed"],
+    killed: []
+};
+// ─── Factory ──────────────────────────────────────────────────────────────────
+export function createMissionRecord(draft, options = {}) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const makeId = options.idFactory ?? ((prefix) => `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`);
+    const ts = now();
+    return {
+        schemaVersion: MISSION_SCHEMA_VERSION,
+        missionId: draft.missionId ?? makeId("mission"),
+        revision: 0,
+        title: draft.title,
+        objective: draft.objective,
+        ownerId: draft.ownerId,
+        workspaceId: draft.workspaceId,
+        projectId: draft.projectId,
+        status: "planned",
+        budget: { ...draft.budget },
+        cost: { totalActualUsd: 0, verifiedOutcomeCount: 0, totalRunCount: 0 },
+        runLinks: [],
+        approvals: [],
+        acceptanceCriteria: draft.acceptanceCriteria ?? [],
+        createdAt: ts,
+        updatedAt: ts
+    };
+}
+// ─── Transition guard ─────────────────────────────────────────────────────────
+export function isMissionTransitionAllowed(from, to) {
+    return ALLOWED_MISSION_TRANSITIONS[from].includes(to);
+}

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

@@ -1,8 +1,9 @@
-export declare const MARTIN_ERROR_CATEGORIES: readonly ["invalid_input", "environment", "auth", "not_found", "store_unreadable", "verification_failed", "policy_blocked", "budget_exit", "transient"];
+export declare const MARTIN_ERROR_CATEGORIES: readonly ["invalid_input", "environment", "auth", "not_found", "store_unreadable", "verification_failed", "policy_blocked", "budget_exit", "transient", "install_failed"];
 export type MartinErrorCategory = (typeof MARTIN_ERROR_CATEGORIES)[number];
 export type MartinOutputMode = "human" | "json" | "quiet";
 export interface MartinRunSelector {
     runsDir?: string;
+    workspaceId?: string;
     file?: string;
     loopId?: string;
     latest?: boolean;
@@ -10,6 +11,7 @@ export interface MartinRunSelector {
 }
 export interface MartinRunListFilters {
     runsDir?: string;
+    workspaceId?: string;
     limit?: number;
     status?: string;
     lifecycleState?: string;

package/dist/vendor/contracts/operator.js

@@ -7,5 +7,6 @@ export const MARTIN_ERROR_CATEGORIES = [
     "verification_failed",
     "policy_blocked",
     "budget_exit",
-    "transient"
+    "transient",
+    "install_failed"
 ];

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

@@ -0,0 +1,106 @@
+import type { CostProvenance, LoopLifecycleState, LoopStatus, ReceiptIntegritySummary } from "./index.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"];
+export type ExecutionMode = (typeof EXECUTION_MODES)[number];
+export declare const EVIDENCE_STATUSES: readonly ["PASSED", "FAILED", "CONTRADICTED", "NOT_RUN", "NOT_EVALUATED"];
+export type EvidenceStatus = (typeof EVIDENCE_STATUSES)[number];
+/**
+ * Granular internal/runtime state. Retained for diagnosis, policy,
+ * receipts and engineering review.
+ */
+export declare const TEST_INTEGRITY_STATUSES: readonly ["UNCHANGED", "AUTHORIZED_CHANGE", "PREVENTED", "DETECTED_AND_ROLLED_BACK", "DETECTED_NEEDS_REVIEW", "NOT_EVALUATED"];
+export type TestIntegrityStatus = (typeof TEST_INTEGRITY_STATUSES)[number];
+/**
+ * Stable public-facing verdict used by CLI, MCP, JSON/Markdown handoffs
+ * and the website. Do not make each renderer collapse states independently.
+ */
+export declare const TEST_INTEGRITY_VERDICTS: readonly ["VERIFIED", "TAMPERING_DETECTED", "NOT_EVALUATED"];
+export type TestIntegrityVerdict = (typeof TEST_INTEGRITY_VERDICTS)[number];
+export interface VerifiedHandoffCheckV1 {
+    command: string;
+    status: EvidenceStatus;
+    exitCode?: number;
+    timedOut?: boolean;
+    detail?: string;
+}
+export interface VerifiedHandoffRequirementV1 {
+    requirement: string;
+    status: "PROVEN" | "FAILED" | "UNRESOLVED" | "NOT_EVALUATED";
+    evidence?: string[];
+}
+export interface VerifiedHandoffScopeV1 {
+    status: "WITHIN_SCOPE" | "VIOLATION_REJECTED" | "NEEDS_REVIEW" | "NOT_EVALUATED";
+    allowedPaths: string[];
+    deniedPaths: string[];
+    changedFiles: string[];
+    violations: string[];
+}
+export interface VerifiedHandoffTestIntegrityV1 {
+    /** Public rendering contract. */
+    verdict: TestIntegrityVerdict;
+    /** Granular runtime state for diagnosis and evidence. */
+    status: TestIntegrityStatus;
+    protectedPaths: string[];
+    changedProtectedPaths: string[];
+    findings: Array<{
+        filePath: string;
+        issue: string;
+        severity: "high" | "medium" | "low";
+        detail: string;
+    }>;
+    summary: string;
+}
+export interface VerifiedHandoffRecoveryV1 {
+    rollbackBoundaryAvailable: boolean;
+    rollbackAttempted: boolean;
+    rollbackSucceeded?: boolean;
+    isolatedRef?: string;
+    nextCommand?: string;
+    summary: string;
+}
+export interface VerifiedHandoffV1 {
+    schemaVersion: "1.0.0";
+    handoffId: string;
+    loopId: string;
+    generatedAt: string;
+    task: {
+        title: string;
+        objective: string;
+    };
+    definitionOfDone: {
+        acceptanceCriteria: string[];
+        verificationPlan: string[];
+    };
+    outcome: VerifiedHandoffOutcome;
+    /** Added compatibly in 1.0.0; missing legacy values must be treated as non-governed. */
+    executionMode?: ExecutionMode;
+    /** Only an explicit true value is eligible for a governed VERIFIED claim. */
+    governanceClaimEligible?: boolean;
+    sourceStatus: {
+        status: LoopStatus;
+        lifecycleState: LoopLifecycleState;
+    };
+    verification: {
+        status: EvidenceStatus;
+        summary: string;
+        checks: VerifiedHandoffCheckV1[];
+        warnings: string[];
+    };
+    requirements: VerifiedHandoffRequirementV1[];
+    scope: VerifiedHandoffScopeV1;
+    testIntegrity: VerifiedHandoffTestIntegrityV1;
+    unresolvedWork: string[];
+    stopReason?: string;
+    recovery: VerifiedHandoffRecoveryV1;
+    usage: {
+        attempts: number;
+        actualUsd: number;
+        estimatedUsd?: number;
+        tokensIn: number;
+        tokensOut: number;
+        costProvenance: CostProvenance;
+    };
+    receiptIntegrity: ReceiptIntegritySummary;
+    nextAction: string;
+}