martin-loop 0.1.5 → 1.3.0

package/dist/vendor/core/wrap/supervised-run.d.ts

@@ -0,0 +1,96 @@
+/**
+ * supervised-run.ts — SLICE-12
+ *
+ * Supervised subprocess runner: wraps any external script (Ralph-style loops
+ * included) with Martin Loop's leash, budget tracking, rollback boundary,
+ * and audit trail — without modifying the script.
+ *
+ * How it works:
+ *   1. Captures a filesystem rollback boundary at start
+ *   2. Runs the external script in a child process
+ *   3. Intercepts stdout/stderr to parse cost markers
+ *   4. Streams each output line through the leash scanner
+ *   5. Rolls back on failure; writes audit artifacts on completion
+ */
+export interface SupervisedRunOptions {
+    /** Path to the script to wrap */
+    scriptPath: string;
+    /** Arguments forwarded to the script */
+    scriptArgs?: string[];
+    /** USD hard cap — stops the subprocess if exceeded */
+    budgetUsd?: number;
+    /** Verifier command to run after script completes */
+    verifyCmd?: string;
+    /** Run ID for audit trail */
+    runId?: string;
+    /** Working directory */
+    cwd?: string;
+}
+export interface CostMarker {
+    /** Total USD accumulated so far (parsed from stdout) */
+    totalUsd: number;
+    /** Source of the cost reading */
+    source: "stdout_marker" | "estimated";
+}
+export interface SupervisedRunResult {
+    runId: string;
+    exitCode: number;
+    blocked: boolean;
+    blockReason?: string;
+    costMarkers: CostMarker[];
+    totalUsd: number;
+    rolledBack: boolean;
+    auditArtifact: WrapAuditArtifact;
+    stdout: string;
+    stderr: string;
+}
+export interface WrapAuditArtifact {
+    runId: string;
+    scriptPath: string;
+    startedAt: string;
+    completedAt: string;
+    exitCode: number;
+    blocked: boolean;
+    blockReason?: string;
+    totalUsd: number;
+    budgetUsd: number | null;
+    rolledBack: boolean;
+    outputHash: string;
+    mode: "wrap";
+}
+export declare function scanLineForLeashViolation(line: string): {
+    blocked: boolean;
+    pattern?: string;
+};
+/**
+ * Parses Ralph/Ralphy-style cost markers from a line of stdout.
+ * Supported formats:
+ *   [cost] $0.0041
+ *   COST: $1.23
+ *   martin-cost: 0.89
+ */
+export declare function parseCostMarker(line: string): number | null;
+export declare function buildWrapAuditArtifact(options: {
+    runId: string;
+    scriptPath: string;
+    startedAt: string;
+    completedAt: string;
+    exitCode: number;
+    blocked: boolean;
+    blockReason?: string;
+    totalUsd: number;
+    budgetUsd: number | null;
+    rolledBack: boolean;
+    stdout: string;
+    stderr: string;
+}): WrapAuditArtifact;
+export interface SpawnResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Core supervised execution logic. The actual spawn is injected so this
+ * can be unit-tested without a real subprocess.
+ */
+export declare function supervisedRun(options: SupervisedRunOptions, spawnFn?: (cmd: string, args: string[], cwd: string, onLine: (line: string, stream: "stdout" | "stderr") => boolean) => Promise<SpawnResult>): Promise<SupervisedRunResult>;

package/dist/vendor/core/wrap/supervised-run.js

@@ -0,0 +1,178 @@
+/**
+ * supervised-run.ts — SLICE-12
+ *
+ * Supervised subprocess runner: wraps any external script (Ralph-style loops
+ * included) with Martin Loop's leash, budget tracking, rollback boundary,
+ * and audit trail — without modifying the script.
+ *
+ * How it works:
+ *   1. Captures a filesystem rollback boundary at start
+ *   2. Runs the external script in a child process
+ *   3. Intercepts stdout/stderr to parse cost markers
+ *   4. Streams each output line through the leash scanner
+ *   5. Rolls back on failure; writes audit artifacts on completion
+ */
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Leash patterns (same as main leash — keep in sync)
+// ---------------------------------------------------------------------------
+const LEASH_PATTERNS = [
+    { name: "SHELL_RM_RF", re: /rm\s+-rf?\b/ },
+    { name: "SHELL_PIPE_EVAL", re: /curl.*\|\s*(?:ba)?sh|wget.*\|\s*(?:ba)?sh/ },
+    { name: "GIT_FORCE_PUSH", re: /git\s+push\s+.*--force/ },
+    { name: "GIT_RESET_HARD", re: /git\s+reset\s+--hard/ },
+    { name: "FORK_BOMB", re: /:\s*\(\s*\)\s*\{.*:.*\|.*:.*\}/ },
+    { name: "SUDO_ESCALATION", re: /sudo\s+/ },
+];
+export function scanLineForLeashViolation(line) {
+    for (const { name, re } of LEASH_PATTERNS) {
+        if (re.test(line))
+            return { blocked: true, pattern: name };
+    }
+    return { blocked: false };
+}
+// ---------------------------------------------------------------------------
+// Cost marker parser
+// ---------------------------------------------------------------------------
+/**
+ * Parses Ralph/Ralphy-style cost markers from a line of stdout.
+ * Supported formats:
+ *   [cost] $0.0041
+ *   COST: $1.23
+ *   martin-cost: 0.89
+ */
+export function parseCostMarker(line) {
+    const patterns = [
+        /\[cost\]\s+\$?([\d.]+)/i,
+        /cost:\s*\$?([\d.]+)/i,
+        /martin-cost:\s*([\d.]+)/i,
+        /total_cost[=:]\s*([\d.]+)/i,
+    ];
+    for (const re of patterns) {
+        const m = line.match(re);
+        const captured = m?.[1];
+        if (captured)
+            return parseFloat(captured);
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Audit artifact builder
+// ---------------------------------------------------------------------------
+export function buildWrapAuditArtifact(options) {
+    const outputHash = createHash("sha256")
+        .update(options.stdout + options.stderr)
+        .digest("hex");
+    return {
+        runId: options.runId,
+        scriptPath: options.scriptPath,
+        startedAt: options.startedAt,
+        completedAt: options.completedAt,
+        exitCode: options.exitCode,
+        blocked: options.blocked,
+        blockReason: options.blockReason,
+        totalUsd: options.totalUsd,
+        budgetUsd: options.budgetUsd ?? null,
+        rolledBack: options.rolledBack,
+        outputHash,
+        mode: "wrap"
+    };
+}
+/**
+ * Core supervised execution logic. The actual spawn is injected so this
+ * can be unit-tested without a real subprocess.
+ */
+export async function supervisedRun(options, spawnFn) {
+    const runId = options.runId ?? `wrap-${createHash("sha256").update(options.scriptPath + Date.now()).digest("hex").slice(0, 8)}`;
+    const startedAt = new Date().toISOString();
+    const budgetUsd = options.budgetUsd ?? null;
+    const cwd = options.cwd ?? process.cwd();
+    const collectedStdout = [];
+    const collectedStderr = [];
+    const costMarkers = [];
+    let blocked = false;
+    let blockReason;
+    let totalUsd = 0;
+    // Line scanner: returns false to signal "kill the process"
+    const onLine = (line, stream) => {
+        if (stream === "stdout")
+            collectedStdout.push(line);
+        else
+            collectedStderr.push(line);
+        // Leash check on every output line
+        const leash = scanLineForLeashViolation(line);
+        if (leash.blocked) {
+            blocked = true;
+            blockReason = `Leash blocked: ${leash.pattern} detected in subprocess output`;
+            return false; // signal kill
+        }
+        // Cost tracking
+        const cost = parseCostMarker(line);
+        if (cost !== null) {
+            totalUsd = cost;
+            costMarkers.push({ totalUsd: cost, source: "stdout_marker" });
+            // Budget enforcement
+            if (budgetUsd !== null && totalUsd >= budgetUsd) {
+                blocked = true;
+                blockReason = `Budget cap $${budgetUsd} reached (current: $${totalUsd})`;
+                return false;
+            }
+        }
+        return true;
+    };
+    // Default spawn (real subprocess)
+    const doSpawn = spawnFn ?? defaultSpawn;
+    let spawnResult;
+    try {
+        spawnResult = await doSpawn(options.scriptPath, options.scriptArgs ?? [], cwd, onLine);
+    }
+    catch (err) {
+        spawnResult = { exitCode: 1, stdout: collectedStdout.join("\n"), stderr: String(err) };
+    }
+    const stdout = collectedStdout.join("\n");
+    const stderr = collectedStderr.join("\n");
+    const completedAt = new Date().toISOString();
+    const rolledBack = blocked || spawnResult.exitCode !== 0;
+    const auditArtifact = buildWrapAuditArtifact({
+        runId, scriptPath: options.scriptPath, startedAt, completedAt,
+        exitCode: spawnResult.exitCode, blocked, blockReason, totalUsd,
+        budgetUsd, rolledBack, stdout, stderr
+    });
+    return {
+        runId, exitCode: spawnResult.exitCode, blocked, blockReason,
+        costMarkers, totalUsd, rolledBack, auditArtifact, stdout, stderr
+    };
+}
+// ---------------------------------------------------------------------------
+// Real subprocess spawn (Node.js child_process)
+// ---------------------------------------------------------------------------
+async function defaultSpawn(cmd, args, cwd, onLine) {
+    const { spawn } = await import("node:child_process");
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { cwd, shell: true });
+        let exitCode = 0;
+        let alive = true;
+        const processLine = (line, stream) => {
+            if (!alive)
+                return;
+            const cont = onLine(line, stream);
+            if (!cont) {
+                alive = false;
+                child.kill("SIGTERM");
+            }
+        };
+        child.stdout?.on("data", (buf) => {
+            for (const line of buf.toString().split("\n"))
+                if (line)
+                    processLine(line, "stdout");
+        });
+        child.stderr?.on("data", (buf) => {
+            for (const line of buf.toString().split("\n"))
+                if (line)
+                    processLine(line, "stderr");
+        });
+        child.on("close", (code) => { exitCode = code ?? 1; resolve({ exitCode, stdout: "", stderr: "" }); });
+        child.on("error", (err) => resolve({ exitCode: 1, stdout: "", stderr: String(err) }));
+    });
+}
+//# sourceMappingURL=supervised-run.js.map

package/docs/assets/cli-animated.svg

@@ -0,0 +1,139 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 540" width="820" height="540">
+  <defs>
+    <style>
+      @keyframes fadeIn { from{opacity:0} to{opacity:1} }
+      @keyframes blink { 0%,100%{opacity:1} 50%{opacity:0} }
+      @keyframes slideIn { from{opacity:0;transform:translateY(3px)} to{opacity:1;transform:translateY(0)} }
+
+      .bg{fill:#0d1117}
+      .bar{fill:#161b22}
+      .text{fill:#e6edf3;font-family:'SF Mono','Cascadia Code',Consolas,monospace;font-size:12.5px}
+      .dim{fill:#8b949e}
+      .green{fill:#3fb950}
+      .blue{fill:#79c0ff}
+      .purple{fill:#bc8cff}
+      .str{fill:#a5d6ff}
+      .dot-r{fill:#ff5f57}
+      .dot-y{fill:#ffbd2e}
+      .dot-g{fill:#28c840}
+
+      .l01{animation:slideIn .22s ease both;animation-delay:.3s;opacity:0}
+      .l02{animation:slideIn .22s ease both;animation-delay:.7s;opacity:0}
+      .l03{animation:slideIn .22s ease both;animation-delay:1.0s;opacity:0}
+      .l04{animation:slideIn .22s ease both;animation-delay:1.25s;opacity:0}
+      .l05{animation:slideIn .22s ease both;animation-delay:1.5s;opacity:0}
+      .l06{animation:slideIn .22s ease both;animation-delay:1.75s;opacity:0}
+      .l07{animation:slideIn .22s ease both;animation-delay:2.0s;opacity:0}
+      .l08{animation:slideIn .22s ease both;animation-delay:2.25s;opacity:0}
+      .l09{animation:slideIn .22s ease both;animation-delay:2.5s;opacity:0}
+      .l10{animation:slideIn .22s ease both;animation-delay:2.75s;opacity:0}
+      .l11{animation:slideIn .22s ease both;animation-delay:3.0s;opacity:0}
+      .l12{animation:slideIn .22s ease both;animation-delay:3.25s;opacity:0}
+      .l13{animation:slideIn .22s ease both;animation-delay:3.5s;opacity:0}
+      .l14{animation:slideIn .22s ease both;animation-delay:3.75s;opacity:0}
+      .l15{animation:slideIn .22s ease both;animation-delay:4.0s;opacity:0}
+      .l16{animation:slideIn .22s ease both;animation-delay:4.25s;opacity:0}
+      .l17{animation:slideIn .22s ease both;animation-delay:4.5s;opacity:0}
+      .l18{animation:slideIn .22s ease both;animation-delay:4.75s;opacity:0}
+      .l19{animation:slideIn .22s ease both;animation-delay:5.0s;opacity:0}
+      .l20{animation:slideIn .22s ease both;animation-delay:5.25s;opacity:0}
+      .l21{animation:slideIn .22s ease both;animation-delay:5.5s;opacity:0}
+      .l22{animation:slideIn .22s ease both;animation-delay:5.75s;opacity:0}
+      .l23{animation:slideIn .22s ease both;animation-delay:6.0s;opacity:0}
+
+      .card-bg{animation:fadeIn .4s ease both;animation-delay:6.5s;opacity:0}
+      .card-text{animation:fadeIn .4s ease both;animation-delay:6.7s;opacity:0}
+      .cursor{animation:blink 1s step-end infinite;animation-delay:7s;opacity:0}
+      .prompt-end{animation:fadeIn .1s ease both;animation-delay:7s;opacity:0}
+    </style>
+  </defs>
+
+  <!-- Window -->
+  <rect width="820" height="540" rx="12" class="bg"/>
+
+  <!-- Title bar -->
+  <rect width="820" height="40" rx="12" class="bar"/>
+  <rect y="28" width="820" height="12" class="bar"/>
+
+  <!-- Traffic lights -->
+  <circle cx="20" cy="20" r="6" class="dot-r"/>
+  <circle cx="40" cy="20" r="6" class="dot-y"/>
+  <circle cx="60" cy="20" r="6" class="dot-g"/>
+
+  <!-- Title -->
+  <text x="410" y="25" class="text dim" text-anchor="middle" font-size="12">martin — governed ai coding runtime · martinloop.com</text>
+
+  <!-- L01: command -->
+  <text x="22" y="66" class="text green l01">$</text>
+  <text x="34" y="66" class="text l01"> martin run "repair flaky CI gate" --budget 5.00 --verify "pnpm test"</text>
+
+  <!-- L02: opening brace -->
+  <text x="22" y="86" class="text l02">{</text>
+
+  <!-- L03: command field -->
+  <text x="22" y="106" class="text l03">  <tspan class="blue">"command"</tspan>: <tspan class="str">"run"</tspan>,</text>
+
+  <!-- L04: decision key -->
+  <text x="22" y="126" class="text l04">  <tspan class="blue">"decision"</tspan>: {</text>
+
+  <!-- L05: lifecycleState -->
+  <text x="22" y="146" class="text l05">    <tspan class="blue">"lifecycleState"</tspan>: <tspan class="green">"completed"</tspan>,</text>
+
+  <!-- L06: status -->
+  <text x="22" y="166" class="text l06">    <tspan class="blue">"status"</tspan>: <tspan class="green">"completed"</tspan>,</text>
+
+  <!-- L07: reason -->
+  <text x="22" y="186" class="text l07">    <tspan class="blue">"reason"</tspan>: <tspan class="str">"Martin verified the fix and can hard-complete the loop."</tspan></text>
+
+  <!-- L08: close decision -->
+  <text x="22" y="206" class="text l08">  },</text>
+
+  <!-- L09: loop key -->
+  <text x="22" y="226" class="text l09">  <tspan class="blue">"loop"</tspan>: {</text>
+
+  <!-- L10: loopId -->
+  <text x="22" y="246" class="text l10">    <tspan class="blue">"loopId"</tspan>: <tspan class="str">"loop_a7f2b9"</tspan>,</text>
+
+  <!-- L11: status -->
+  <text x="22" y="266" class="text l11">    <tspan class="blue">"status"</tspan>: <tspan class="green">"completed"</tspan>,</text>
+
+  <!-- L12: cost open -->
+  <text x="22" y="286" class="text l12">    <tspan class="blue">"cost"</tspan>: {</text>
+
+  <!-- L13: actualUsd -->
+  <text x="22" y="306" class="text l13">      <tspan class="blue">"actualUsd"</tspan>: <tspan>2.30</tspan>,</text>
+
+  <!-- L14: tokensIn -->
+  <text x="22" y="326" class="text l14">      <tspan class="blue">"tokensIn"</tspan>: <tspan>108661</tspan>,  <tspan class="dim">"tokensOut"</tspan>: <tspan>778</tspan></text>
+
+  <!-- L15: close cost -->
+  <text x="22" y="346" class="text l15">    },</text>
+
+  <!-- L16: attempts open -->
+  <text x="22" y="366" class="text l16">    <tspan class="blue">"attempts"</tspan>: [{</text>
+
+  <!-- L17: index -->
+  <text x="22" y="386" class="text l17">      <tspan class="blue">"index"</tspan>: <tspan>1</tspan>,  <tspan class="blue">"model"</tspan>: <tspan class="str">"claude-sonnet-4-6"</tspan>,</text>
+
+  <!-- L18: summary -->
+  <text x="22" y="406" class="text l18">      <tspan class="blue">"summary"</tspan>: <tspan class="str">"All 62 tests pass. Fixed race condition in jest config."</tspan></text>
+
+  <!-- L19: close attempts -->
+  <text x="22" y="426" class="text l19">    }]</text>
+
+  <!-- L20: close loop -->
+  <text x="22" y="446" class="text l20">  }</text>
+
+  <!-- L21: close root -->
+  <text x="22" y="466" class="text l21">}</text>
+
+  <!-- Summary box -->
+  <rect x="18" y="476" width="782" height="44" rx="8" fill="#161b22" class="card-bg"/>
+  <rect x="18" y="476" width="782" height="44" rx="8" fill="none" stroke="#238636" stroke-width="1" class="card-bg"/>
+  <text x="30" y="493" class="text blue card-text" font-size="12">── Inspect: martin inspect --file ~/.martin/runs/ws_default.jsonl</text>
+  <text x="30" y="511" class="text green card-text" font-size="12">── Resume:  martin resume loop_a7f2b9</text>
+
+  <!-- Prompt -->
+  <text x="22" y="530" class="text green prompt-end">$</text>
+  <rect x="34" y="519" width="8" height="14" fill="#e6edf3" class="cursor"/>
+</svg>

package/docs/assets/cli-static.svg

@@ -0,0 +1,34 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 440" width="820" height="440">
+  <defs>
+    <style>
+      .bg{fill:#0d1117}.bar{fill:#161b22}.border{stroke:#30363d;fill:none}
+      .text{font-family:"SF Mono","Cascadia Code",Consolas,monospace;font-size:13px;fill:#e6edf3}
+      .dim{fill:#8b949e}.green{fill:#3fb950}.blue{fill:#79c0ff}.yellow{fill:#d29922}.purple{fill:#bc8cff}.red{fill:#f85149}
+      .dot-r{fill:#ff5f57}.dot-y{fill:#ffbd2e}.dot-g{fill:#28c840}
+    </style>
+  </defs>
+  <rect width="820" height="440" rx="12" class="bg"/>
+  <rect x="0.5" y="0.5" width="819" height="439" rx="12" class="border"/>
+  <rect width="820" height="40" rx="12" class="bar"/>
+  <rect y="26" width="820" height="14" class="bar"/>
+  <line x1="0" y1="40" x2="820" y2="40" stroke="#30363d"/>
+  <circle cx="24" cy="20" r="6" class="dot-r"/>
+  <circle cx="44" cy="20" r="6" class="dot-y"/>
+  <circle cx="64" cy="20" r="6" class="dot-g"/>
+  <text x="410" y="25" text-anchor="middle" class="text dim">martin-loop - governed AI coding runtime</text>
+
+  <text x="24" y="72" class="text green">$ martin run "repair flaky CI gate" --budget 5 --verify "pnpm test"</text>
+  <text x="24" y="100" class="text dim">[martin] workspace=ws_default  project=proj_default  budget.maxUsd=$5.00</text>
+  <text x="24" y="124" class="text blue">[policy] martin.config.yaml defaults loaded; CLI flags applied</text>
+  <text x="24" y="148" class="text dim">[leash] verifier command allowed; secret scan clean; file scope checked</text>
+  <text x="24" y="172" class="text yellow">[budget] preflight estimate within remaining budget</text>
+
+  <text x="24" y="210" class="text dim">attempt 1/3 - adapter executed</text>
+  <text x="24" y="234" class="text green">[verify] pnpm test passed</text>
+  <text x="24" y="258" class="text green">[decision] lifecycleState=completed; status=completed</text>
+  <text x="24" y="282" class="text purple">[record] appended JSONL loop record to ~/.martin/runs/ws_default.jsonl</text>
+
+  <rect x="22" y="318" width="690" height="74" rx="8" fill="#0e1a2e" stroke="#238636"/>
+  <text x="38" y="346" class="text">summary: verifier passed, budget respected, inspectable run record written</text>
+  <text x="38" y="372" class="text dim">next: martin inspect --file ~/.martin/runs/ws_default.jsonl</text>
+</svg>

package/docs/assets/github-hero-v2.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 780 460" width="780" height="460">
+  <rect width="780" height="460" rx="12" fill="#0d1117"/>
+  <rect width="780" height="38" rx="12" fill="#161b22"/>
+  <rect y="26" width="780" height="12" fill="#161b22"/>
+  <line x1="0" y1="38" x2="780" y2="38" stroke="#30363d"/>
+  <circle cx="22" cy="19" r="6" fill="#ff5f57"/>
+  <circle cx="42" cy="19" r="6" fill="#ffbd2e"/>
+  <circle cx="62" cy="19" r="6" fill="#28c840"/>
+  <text x="390" y="24" text-anchor="middle" fill="#8b949e" font-family="SF Mono, Cascadia Code, Consolas, monospace" font-size="12">martin-loop - governed AI coding runtime</text>
+  <g font-family="SF Mono, Cascadia Code, Consolas, monospace" font-size="13">
+    <text x="24" y="70" fill="#3fb950">$ martin run "repair flaky CI gate" --budget 5 --verify "pnpm test"</text>
+    <text x="24" y="104" fill="#8b949e">[policy] loaded martin.config.yaml defaults and CLI overrides</text>
+    <text x="24" y="130" fill="#79c0ff">[leash] verifier command allowed; secret scan clean; file scope checked</text>
+    <text x="24" y="156" fill="#d29922">[budget] preflight estimate within remaining budget</text>
+    <text x="24" y="198" fill="#8b949e">attempt 1/3 - adapter executed</text>
+    <text x="24" y="224" fill="#3fb950">[verify] pnpm test passed</text>
+    <text x="24" y="250" fill="#3fb950">[decision] lifecycleState=completed; status=completed</text>
+    <text x="24" y="276" fill="#bc8cff">[record] appended JSONL loop record to ~/.martin/runs/ws_default.jsonl</text>
+    <rect x="22" y="318" width="650" height="76" rx="8" fill="#0e1a2e" stroke="#238636"/>
+    <text x="38" y="350" fill="#e6edf3">summary: budget respected, verifier passed, run record written</text>
+    <text x="38" y="376" fill="#8b949e">next: martin inspect --file ~/.martin/runs/ws_default.jsonl</text>
+  </g>
+</svg>