@almanak/mcp-server 0.1.14 → 0.1.15

package/dist/testing/controller-client.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Thin HTTP client for the test-controller sidecar.
+ *
+ * The controller is a Python sidecar (see `almanak/test_controller/__main__.py`
+ * in the SDK repo) that lives in its own Cloud Run container, holds the
+ * privileged RPC env, and exposes ``/start_gateway`` + ``/stop_gateway`` over
+ * localhost. The MCP `run_test` tool talks to it from the worker container to
+ * spin up a fresh per-test gateway, run the SDK ladder, then tear it down.
+ *
+ * No external HTTP dep — uses Node's stdlib so this package stays zero-dep.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestControllerClient = void 0;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+class TestControllerClient {
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.timeoutMs = config.timeoutMs;
+    }
+    async health() {
+        return this.request('GET', '/health');
+    }
+    async startGateway(workspacePath) {
+        return this.request('POST', '/start_gateway', { workspace_path: workspacePath });
+    }
+    async stopGateway() {
+        return this.request('POST', '/stop_gateway');
+    }
+    request(method, path, body) {
+        return new Promise((resolve, reject) => {
+            const url = new URL(this.baseUrl + path);
+            const headers = { Accept: 'application/json' };
+            let bodyStr;
+            if (body !== undefined) {
+                bodyStr = JSON.stringify(body);
+                headers['Content-Type'] = 'application/json';
+                headers['Content-Length'] = Buffer.byteLength(bodyStr).toString();
+            }
+            const transport = url.protocol === 'https:' ? https : http;
+            const req = transport.request(url, { method, headers, timeout: this.timeoutMs }, (res) => {
+                const chunks = [];
+                res.on('data', (c) => chunks.push(c));
+                res.on('end', () => {
+                    var _a, _b;
+                    const raw = Buffer.concat(chunks).toString('utf-8');
+                    let parsed;
+                    try {
+                        parsed = raw ? JSON.parse(raw) : {};
+                    }
+                    catch {
+                        reject(new Error(`controller ${method} ${path} returned non-JSON (status=${res.statusCode}): ${raw.slice(0, 200)}`));
+                        return;
+                    }
+                    if (res.statusCode && res.statusCode >= 400) {
+                        const detail = (_b = (_a = parsed === null || parsed === void 0 ? void 0 : parsed.detail) !== null && _a !== void 0 ? _a : parsed === null || parsed === void 0 ? void 0 : parsed.error) !== null && _b !== void 0 ? _b : raw.slice(0, 200);
+                        reject(new Error(`controller ${method} ${path} -> HTTP ${res.statusCode}: ${detail}`));
+                        return;
+                    }
+                    resolve(parsed);
+                });
+            });
+            req.on('error', (e) => reject(new Error(`controller ${method} ${path} failed: ${e.message}`)));
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new Error(`controller ${method} ${path} timed out after ${this.timeoutMs}ms`));
+            });
+            if (bodyStr !== undefined)
+                req.write(bodyStr);
+            req.end();
+        });
+    }
+}
+exports.TestControllerClient = TestControllerClient;
+//# sourceMappingURL=controller-client.js.map

package/dist/testing/controller-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-client.js","sourceRoot":"","sources":["../../src/testing/controller-client.ts"],"names":[],"mappings":"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"}

package/dist/testing/runner.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Orchestrates the SDK test ladder against a workspace.
+ *
+ * The flow:
+ *   1. ``imports``   — ``python -c 'from strategy import *'``
+ *   2. ``unit``      — ``pytest tests/ -v --tb=short``  (skipped if no tests/ dir)
+ *   3. ``smoke``     — ``almanak strat run --network anvil --once --no-gateway ...``
+ *   4. ``lifecycle`` — ``almanak strat test --no-gateway --json ...``
+ *
+ * Steps 1+2 are fail-fast (no point booting a gateway if imports break).
+ * Steps 3+4 share a gateway provisioned via the test-controller sidecar;
+ * the gateway is torn down in ``finally`` whether the ladder passes or not.
+ *
+ * Step 4's ``--json`` summary is parsed out of stdout and surfaced on the
+ * step result so the agent doesn't have to re-parse mixed output.
+ *
+ * Privileged env (Alchemy / Etherscan / etc.) is stripped before spawning
+ * subprocesses — the SDK CLI talks to the gateway over localhost via
+ * ``--no-gateway`` and never needs the upstream RPC URL directly.
+ */
+import { TestControllerClient } from './controller-client';
+export interface RunTestArgs {
+    workspacePath: string;
+    actions?: string[];
+    teardown?: boolean;
+    /**
+     * Optional file path. When set, the full stdout + stderr of every ladder
+     * step is appended to this file (with per-step headers). Caller is
+     * responsible for the parent dir existing. When unset, only the truncated
+     * tails on each step result carry log content.
+     */
+    logPath?: string;
+}
+export type StepName = 'imports' | 'unit' | 'smoke' | 'lifecycle';
+export interface StepResult {
+    name: StepName;
+    passed: boolean;
+    exit_code: number | null;
+    duration_ms: number;
+    stdout_tail: string;
+    stderr_tail: string;
+    /** Only set on the ``lifecycle`` step — the strat-test ``--json`` payload. */
+    summary?: Record<string, any> | null;
+    /** Set when fail-fast or a prior dependency failure caused this step to be skipped. */
+    skipped_reason?: string;
+}
+export interface RunTestResult {
+    all_passed: boolean;
+    steps: StepResult[];
+}
+export declare function tail(s: string, max?: number): string;
+/**
+ * Extract the last top-level JSON object from a mixed stdout stream.
+ *
+ * ``strat test --json`` emits its summary as the last top-level object after
+ * setup chatter; we use a depth-counting scan instead of greedy regex so
+ * braces inside strings don't confuse the parse.
+ */
+export declare function extractLastJsonObject(text: string): Record<string, any> | null;
+export declare function runTestLadder(args: RunTestArgs, controller: TestControllerClient): Promise<RunTestResult>;

package/dist/testing/runner.js

@@ -0,0 +1,472 @@
+"use strict";
+/**
+ * Orchestrates the SDK test ladder against a workspace.
+ *
+ * The flow:
+ *   1. ``imports``   — ``python -c 'from strategy import *'``
+ *   2. ``unit``      — ``pytest tests/ -v --tb=short``  (skipped if no tests/ dir)
+ *   3. ``smoke``     — ``almanak strat run --network anvil --once --no-gateway ...``
+ *   4. ``lifecycle`` — ``almanak strat test --no-gateway --json ...``
+ *
+ * Steps 1+2 are fail-fast (no point booting a gateway if imports break).
+ * Steps 3+4 share a gateway provisioned via the test-controller sidecar;
+ * the gateway is torn down in ``finally`` whether the ladder passes or not.
+ *
+ * Step 4's ``--json`` summary is parsed out of stdout and surfaced on the
+ * step result so the agent doesn't have to re-parse mixed output.
+ *
+ * Privileged env (Alchemy / Etherscan / etc.) is stripped before spawning
+ * subprocesses — the SDK CLI talks to the gateway over localhost via
+ * ``--no-gateway`` and never needs the upstream RPC URL directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tail = tail;
+exports.extractLastJsonObject = extractLastJsonObject;
+exports.runTestLadder = runTestLadder;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+/** Per-step subprocess timeouts (ms). Smoke + lifecycle hit Anvil; give them headroom. */
+const STEP_TIMEOUT_MS = {
+    imports: 60000,
+    unit: 300000,
+    smoke: 300000,
+    lifecycle: 600000,
+};
+const STDOUT_TAIL_BYTES = 8192;
+/** Default Anvil account #0 — public test key, safe to embed. */
+const ANVIL_DEFAULT_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+// Exported for tests; production callers reach it via runStep.
+function tail(s, max = STDOUT_TAIL_BYTES) {
+    if (!s || s.length <= max)
+        return s;
+    // String-level slice — Buffer.subarray at an arbitrary byte offset can split
+    // a multi-byte UTF-8 character mid-codepoint and produce invalid UTF-8 at
+    // the leading boundary. Slicing the string operates on code units instead,
+    // which is safe for the diagnostic-only stdout/stderr tail we emit here.
+    return `[...${s.length - max} chars truncated...]\n${s.slice(-max)}`;
+}
+/**
+ * Extract the last top-level JSON object from a mixed stdout stream.
+ *
+ * ``strat test --json`` emits its summary as the last top-level object after
+ * setup chatter; we use a depth-counting scan instead of greedy regex so
+ * braces inside strings don't confuse the parse.
+ */
+// Exported for tests; production callers reach it via runStep with parseSummary=true.
+function extractLastJsonObject(text) {
+    if (!text)
+        return null;
+    const starts = [];
+    // Match every '{' that begins a line — those are the candidates for a
+    // top-level JSON object. Inside-line braces (inside strings or nested
+    // structures) are skipped.
+    const re = /^\{/gm;
+    let m;
+    while ((m = re.exec(text)) !== null)
+        starts.push(m.index);
+    for (let i = starts.length - 1; i >= 0; i--) {
+        const slice = text.substring(starts[i]);
+        const end = findJsonObjectEnd(slice);
+        if (end < 0)
+            continue;
+        try {
+            const parsed = JSON.parse(slice.substring(0, end));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // try the next earlier candidate
+        }
+    }
+    return null;
+}
+function findJsonObjectEnd(s) {
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (esc) {
+            esc = false;
+            continue;
+        }
+        if (c === '\\') {
+            esc = true;
+            continue;
+        }
+        if (c === '"') {
+            inStr = !inStr;
+            continue;
+        }
+        if (inStr)
+            continue;
+        if (c === '{')
+            depth++;
+        else if (c === '}') {
+            depth--;
+            if (depth === 0)
+                return i + 1;
+        }
+    }
+    return -1;
+}
+function processEnv() {
+    const env = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (v !== undefined)
+            env[k] = v;
+    }
+    return env;
+}
+/**
+ * Preflight: confirm that the ``python`` binary on PATH can import ``almanak``.
+ *
+ * Without this we'd hit a ``ModuleNotFoundError`` mid-ladder on Step 1 and
+ * the caller sees a Python traceback instead of an actionable diagnostic.
+ * Fails loudly with a single-line error that tells the caller exactly which
+ * Python was used + what to do about it.
+ *
+ * Times out at 5s; in practice this is sub-second.
+ */
+async function preflightCheckSdkAvailable(env) {
+    return new Promise((resolve, reject) => {
+        var _a, _b;
+        const proc = (0, child_process_1.spawn)('python', ['-c', 'import almanak; import sys; print(almanak.__file__, sys.executable)'], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        const stderrChunks = [];
+        (_a = proc.stdout) === null || _a === void 0 ? void 0 : _a.on('data', () => { });
+        (_b = proc.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (c) => stderrChunks.push(c));
+        const timer = setTimeout(() => {
+            proc.kill('SIGKILL');
+            reject(new Error('preflight: python -c "import almanak" timed out after 5s. Check that ' +
+                'the worker container has the SDK installed and PATH points at the right ' +
+                'Python interpreter.'));
+        }, 5000);
+        proc.on('error', (e) => {
+            clearTimeout(timer);
+            reject(new Error(`preflight: could not spawn 'python' (${e.message}). The worker container ` +
+                "must have 'python' on PATH."));
+        });
+        // Use 'close' (not 'exit') so the child's stderr stream has fully flushed
+        // before we read it. 'exit' can fire while stderrChunks is still being
+        // populated, truncating the diagnostic the user sees on a real failure.
+        proc.on('close', (code) => {
+            clearTimeout(timer);
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
+            reject(new Error(`preflight: 'python -c "import almanak"' failed (exit=${code}). Check that ` +
+                'PATH points at a Python that has the almanak SDK installed. ' +
+                `python stderr: ${stderr.slice(0, 500)}`));
+        });
+    });
+}
+async function runStep(name, argv, cwd, env, timeoutMs, parseSummary, logPath) {
+    const start = Date.now();
+    return new Promise((resolve) => {
+        var _a, _b;
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let proc;
+        try {
+            proc = (0, child_process_1.spawn)(argv[0], argv.slice(1), {
+                cwd,
+                env,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (e) {
+            resolve({
+                name,
+                passed: false,
+                exit_code: null,
+                duration_ms: Date.now() - start,
+                stdout_tail: '',
+                stderr_tail: `failed to spawn ${argv[0]}: ${e.message}`,
+            });
+            return;
+        }
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            proc.kill('SIGKILL');
+        }, timeoutMs);
+        // Guard against the (theoretically possible) case where both ``error``
+        // and ``exit`` fire on the same subprocess. Promise.resolve is idempotent,
+        // but the listener body still runs each time and would log duplicates /
+        // do redundant work. One-shot resolve makes the intent explicit.
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        (_a = proc.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (c) => stdoutChunks.push(c));
+        (_b = proc.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (c) => stderrChunks.push(c));
+        proc.on('error', (e) => {
+            settle({
+                name,
+                passed: false,
+                exit_code: null,
+                duration_ms: Date.now() - start,
+                stdout_tail: tail(Buffer.concat(stdoutChunks).toString('utf-8')),
+                stderr_tail: `subprocess error: ${e.message}`,
+            });
+        });
+        // Use 'close' (not 'exit'): 'exit' fires when the process exits but stdio
+        // streams may not yet be flushed, which can truncate the captured output.
+        // 'close' fires after both 'exit' AND all stdio handles have emitted 'end'.
+        // Critical for the lifecycle step whose JSON summary is parsed from stdout.
+        proc.on('close', (code) => {
+            const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf-8');
+            const result = {
+                name,
+                passed: code === 0 && !timedOut,
+                exit_code: code,
+                duration_ms: Date.now() - start,
+                stdout_tail: tail(stdout),
+                stderr_tail: timedOut
+                    ? `[TIMEOUT: exceeded ${timeoutMs}ms]\n${tail(stderr)}`
+                    : tail(stderr),
+            };
+            if (parseSummary) {
+                result.summary = extractLastJsonObject(stdout);
+            }
+            if (logPath !== undefined) {
+                // Append this step's block to the shared log file. We don't fail the
+                // step on a log write error — the response still carries the tail.
+                const block = `\n===== step: ${name} =====\n` +
+                    `argv: ${argv.join(' ')}\n` +
+                    `cwd: ${cwd}\n` +
+                    `exit_code: ${code}\n` +
+                    `duration_ms: ${Date.now() - start}\n` +
+                    (timedOut ? `TIMEOUT: exceeded ${timeoutMs}ms\n` : '') +
+                    `--- stdout ---\n${stdout}` +
+                    (stdout.endsWith('\n') ? '' : '\n') +
+                    `--- stderr ---\n${stderr}` +
+                    (stderr.endsWith('\n') ? '' : '\n');
+                try {
+                    (0, fs_1.appendFileSync)(logPath, block);
+                }
+                catch (e) {
+                    process.stderr.write(`[run_test] WARNING: failed to append log to ${logPath}: ${e.message}\n`);
+                }
+            }
+            settle(result);
+        });
+    });
+}
+function skipped(name, reason) {
+    return {
+        name,
+        passed: false,
+        exit_code: null,
+        duration_ms: 0,
+        stdout_tail: '',
+        stderr_tail: '',
+        skipped_reason: reason,
+    };
+}
+/** Skip reasons that don't count as a ladder failure (e.g., no tests dir present). */
+const BENIGN_SKIP_PREFIXES = ['no tests/'];
+function isBenignSkip(reason) {
+    if (!reason)
+        return false;
+    return BENIGN_SKIP_PREFIXES.some((p) => reason.startsWith(p));
+}
+async function runTestLadder(args, controller) {
+    var _a;
+    const workspace = args.workspacePath;
+    if (!(0, fs_1.existsSync)(workspace) || !(0, fs_1.statSync)(workspace).isDirectory()) {
+        throw new Error(`workspace_path is not a directory: ${workspace}`);
+    }
+    if (!(0, fs_1.existsSync)((0, path_1.join)(workspace, 'strategy.py'))) {
+        throw new Error(`workspace missing strategy.py: ${workspace}`);
+    }
+    if (!(0, fs_1.existsSync)((0, path_1.join)(workspace, 'config.json'))) {
+        throw new Error(`workspace missing config.json: ${workspace}`);
+    }
+    const teardown = args.teardown !== false; // default true
+    const actions = (_a = args.actions) !== null && _a !== void 0 ? _a : [];
+    // Resolve + sandbox the caller-supplied log path to inside the workspace.
+    // Without this, any tool caller could overwrite arbitrary container files
+    // (e.g. ``/etc/passwd``) by passing an absolute path or a ``..``-traversing
+    // relative path. The workspace itself is already the agent's working area,
+    // so restricting writes there does not block legitimate use.
+    const workspaceResolved = (0, path_1.resolve)(workspace);
+    let logPath;
+    if (args.logPath !== undefined) {
+        const candidate = (0, path_1.isAbsolute)(args.logPath)
+            ? (0, path_1.resolve)(args.logPath)
+            : (0, path_1.resolve)(workspaceResolved, args.logPath);
+        const rel = (0, path_1.relative)(workspaceResolved, candidate);
+        if (rel.startsWith('..') || (0, path_1.isAbsolute)(rel)) {
+            throw new Error(`log_path must be inside workspace_path (got ${args.logPath})`);
+        }
+        logPath = candidate;
+    }
+    // Truncate (or create) the log file up front so retries don't accumulate
+    // output from a previous run on the same path. Caller owns parent dir.
+    if (logPath !== undefined) {
+        try {
+            (0, fs_1.writeFileSync)(logPath, `# run_test ladder log — ${new Date().toISOString()}\n# workspace: ${workspace}\n`);
+        }
+        catch (e) {
+            throw new Error(`failed to open log_path ${logPath}: ${e.message}`);
+        }
+    }
+    const steps = [];
+    const env = processEnv();
+    // Preflight before any step runs — a misconfigured worker (Python missing
+    // or SDK not installed in the active env) would otherwise produce a Step 1
+    // ModuleNotFoundError traceback that's hard to read. Surface the actionable
+    // diagnostic upfront instead.
+    await preflightCheckSdkAvailable(env);
+    // ---- Step 1: imports ----
+    const step1 = await runStep('imports', ['python', '-c', 'from strategy import *'], workspace, env, STEP_TIMEOUT_MS.imports, false, logPath);
+    steps.push(step1);
+    if (!step1.passed) {
+        steps.push(skipped('unit', 'imports failed'));
+        steps.push(skipped('smoke', 'imports failed'));
+        steps.push(skipped('lifecycle', 'imports failed'));
+        return { all_passed: false, steps };
+    }
+    // ---- Step 2: pytest (skipped if no tests/ dir) ----
+    const testsDir = (0, path_1.join)(workspace, 'tests');
+    let step2;
+    if ((0, fs_1.existsSync)(testsDir) && (0, fs_1.statSync)(testsDir).isDirectory()) {
+        step2 = await runStep('unit', ['pytest', 'tests/', '-v', '--tb=short'], workspace, env, STEP_TIMEOUT_MS.unit, false, logPath);
+    }
+    else {
+        step2 = skipped('unit', 'no tests/ directory in workspace');
+    }
+    steps.push(step2);
+    if (!step2.passed && !isBenignSkip(step2.skipped_reason)) {
+        steps.push(skipped('smoke', 'unit tests failed'));
+        steps.push(skipped('lifecycle', 'unit tests failed'));
+        return { all_passed: false, steps };
+    }
+    // ---- Step 3: smoke (own gateway lifecycle) ----
+    // Each gateway-bound step gets its OWN start/stop cycle so each lands on a
+    // freshly-forked Anvil. Sharing one gateway across smoke + lifecycle leaves
+    // smoke's on-chain mutations (a buy that opens a position, an approval, …)
+    // visible to lifecycle, which then sees pre-existing positions when it
+    // tries to drive `force_action=open` from a clean slate.
+    //
+    // --fresh on `strat run` clears any prior almanak_state.db in the workspace
+    // (state.db is workspace-scoped, not anvil-scoped, so a stop/start of the
+    // gateway doesn't touch it). `strat test` handles its own state clearing
+    // internally (cli.py: fresh=True), so we only pass --fresh on the smoke step.
+    //
+    // If the test-controller isn't reachable (ECONNREFUSED — typical local-dev
+    // shape where no sidecar is running), runGatewayStep falls back to the
+    // SDK's ManagedGateway path: argv omits --no-gateway/--gateway-host/--port,
+    // env omits ALMANAK_GATEWAY_*, and the SDK boots/tears down its own Anvil
+    // per step. Identical UX in cloud vs local — `run_test` "just works."
+    const step3 = await runGatewayStep(controller, workspace, 'smoke', (port) => {
+        const argv = [
+            'almanak', 'strat', 'run',
+            '--network', 'anvil', '--once', '--fresh',
+            '-d', workspace,
+        ];
+        if (port !== null) {
+            argv.push('--no-gateway', '--gateway-host', 'localhost', '--gateway-port', String(port));
+        }
+        return argv;
+    }, env, STEP_TIMEOUT_MS.smoke, false, logPath);
+    steps.push(step3);
+    // Do NOT fail-fast on Step 3 — its failure can be informative for the
+    // lifecycle diagnosis below, and the lifecycle often surfaces the same
+    // root cause with more detail in its JSON summary.
+    // ---- Step 4: lifecycle (own gateway lifecycle, fresh Anvil fork) ----
+    const step4 = await runGatewayStep(controller, workspace, 'lifecycle', (port) => {
+        const argv = [
+            'almanak', 'strat', 'test',
+            '--json',
+            '-d', workspace,
+        ];
+        if (port !== null) {
+            argv.push('--no-gateway', '--gateway-host', 'localhost', '--gateway-port', String(port));
+        }
+        if (actions.length > 0)
+            argv.push('--actions', actions.join(','));
+        if (teardown)
+            argv.push('--teardown');
+        return argv;
+    }, env, STEP_TIMEOUT_MS.lifecycle, true, logPath);
+    steps.push(step4);
+    // A step "passes" for ladder purposes if it actually ran successfully OR
+    // was a benign skip (e.g., no tests/ directory). Any other failure flips
+    // all_passed to false.
+    const all_passed = steps.every((s) => s.passed || isBenignSkip(s.skipped_reason));
+    return { all_passed, steps };
+}
+/** True if the controller-client error wraps a transport-level "nothing
+ *  listening" signal — typical local-dev shape where the sidecar isn't
+ *  running. Other failures (controller running but returning 5xx, timing
+ *  out mid-request, hitting an unknown route) bubble up as real errors. */
+function isControllerUnreachable(e) {
+    var _a;
+    const msg = (_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : '';
+    return msg.includes('ECONNREFUSED');
+}
+/**
+ * Run one step with a gateway. Two modes:
+ *   1. Controller-managed: start a gateway via the sidecar, run with --no-gateway
+ *      pointing at it, stop the gateway after — always, even on exception.
+ *   2. SDK-managed (fallback when controller isn't listening): skip start/stop,
+ *      run without --no-gateway so the SDK boots its own Anvil + ManagedGateway.
+ *
+ * The fallback only fires on ECONNREFUSED. A controller that's up but unhealthy
+ * (timeout, 5xx) bubbles up as a real failure step — silent fallback there
+ * would hide a misbehaving sidecar.
+ */
+async function runGatewayStep(controller, workspace, name, buildArgv, env, timeoutMs, parseSummary, logPath) {
+    let port = null;
+    try {
+        const startResp = await controller.startGateway(workspace);
+        port = startResp.port;
+    }
+    catch (e) {
+        if (!isControllerUnreachable(e)) {
+            return {
+                name,
+                passed: false,
+                exit_code: null,
+                duration_ms: 0,
+                stdout_tail: '',
+                stderr_tail: `gateway startup failed: ${e.message}`,
+            };
+        }
+        // Local-dev fallback: controller not listening — let the SDK manage its own gateway.
+        process.stderr.write(`[run_test] test-controller not reachable; using SDK-managed gateway for ${name}\n`);
+    }
+    const gwEnv = {
+        ...env,
+        ALMANAK_PRIVATE_KEY: ANVIL_DEFAULT_PRIVATE_KEY,
+    };
+    if (port !== null) {
+        gwEnv.ALMANAK_GATEWAY_HOST = 'localhost';
+        gwEnv.ALMANAK_GATEWAY_PORT = String(port);
+    }
+    try {
+        return await runStep(name, buildArgv(port), workspace, gwEnv, timeoutMs, parseSummary, logPath);
+    }
+    finally {
+        if (port !== null) {
+            try {
+                await controller.stopGateway();
+            }
+            catch (e) {
+                process.stderr.write(`[run_test] WARNING: /stop_gateway after ${name} failed: ${e.message}\n`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=runner.js.map