@senpi/runtime 3.0.148 → 3.0.149

package/dist/quant/engine-runner.d.ts

@@ -0,0 +1,133 @@
+import { type QuantDocument, type QuantError, type QuantRequest, type QuantSection } from "./types.js";
+/** Outer bound on one desk run (spec §4.4). Past it the child is SIGKILLed → `E_QUANT_TIMEOUT`. */
+export declare const QUANT_ENGINE_TIMEOUT_MS = 240000;
+/** Outer bound on re-rendering a stored run (no network, so far shorter than a run). */
+export declare const QUANT_RENDER_TIMEOUT_MS = 30000;
+/** How to reach and run the engine. `engineDir` is the directory CONTAINING the `quantdesk` package. */
+export interface EngineSpawnOptions {
+    /** Directory holding the `quantdesk` package; prepended to the child's PYTHONPATH. */
+    engineDir: string;
+    /** Interpreter to run. Default `$PYTHON`, else `python3` on PATH. */
+    pythonBin?: string;
+    /** Outer bound before SIGKILL. Default {@link QUANT_ENGINE_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Base environment (default process.env). */
+    env?: NodeJS.ProcessEnv;
+    /** Senpi MCP bearer; wins over the base env's SENPI_AUTH_TOKEN / SENPI_API_KEY. */
+    senpiAuthToken?: string;
+    /** Senpi MCP URL; wins over the base env's SENPI_MCP_URL. */
+    senpiMcpUrl?: string;
+    /** Called once per complete stderr line as it arrives (the `[quant-desk] [n/8]` progress). */
+    onStderrLine?: (line: string) => void;
+}
+/** A desk run: where the engine keeps its cache/scratch, and (tests only) a recorded fixture. */
+export interface RunEngineOptions extends EngineSpawnOptions {
+    stateDir: string;
+    fixture?: string;
+}
+/** What the process did, before interpretation. `out` is the parsed result file, if any. */
+export interface EngineProcessResult {
+    /** The process exit code; null when it was killed by a signal or never started. */
+    exitCode: number | null;
+    /** True when the outer timeout fired and SIGKILLed the child. */
+    timedOut: boolean;
+    /** Set when the interpreter could not be started at all (e.g. ENOENT). */
+    spawnError?: string;
+    /** The last {@link STDERR_TAIL_LINES} non-empty stderr lines. */
+    stderrTail: string[];
+    /** The parsed result file; undefined when absent or not JSON. */
+    out?: unknown;
+}
+/** A desk run's interpreted outcome. `refused` = a deterministic "no"; `failed` = could not answer. */
+export type EngineOutcome = {
+    readonly ok: true;
+    readonly document: QuantDocument;
+} | {
+    readonly ok: false;
+    readonly status: "failed" | "refused";
+    readonly error: QuantError;
+};
+/**
+ * A re-render's outcome.
+ *
+ * `storedRunUnreadable` is set (to the engine's reason) when render.py exited 2 WITH a result file:
+ * that is render_doc saying the run file could not be parsed or holds no document — a fact about
+ * the STORED RUN, not an engine fault. The gateway turns it into a NOT_FOUND-style answer with the
+ * re-run command rather than "quote the error, do not retry". An exit 2 with no file (the argument
+ * parser) never sets it.
+ */
+export type RenderOutcome = {
+    readonly ok: true;
+    readonly markdown: string;
+} | {
+    readonly ok: false;
+    readonly error: QuantError;
+    readonly storedRunUnreadable?: string;
+};
+/**
+ * The child's environment. PYTHONPATH gets the engine dir first. MCP credentials are injected only
+ * when present — never as "" — mirroring the scanner launcher, so the engine's own "no token → no
+ * senpi client" path stays truthful.
+ *
+ * Two interpreter settings are forced, whatever the base env says:
+ * - `PYTHONHASHSEED=0`: the engine still has sites that iterate a `set` of strings (coin names,
+ *   wallets) where the order can reach the output. String hashing is randomised per process, so
+ *   those sites would make the same wallet produce different documents run to run (one such site
+ *   already made the oracle reproduce only two runs in three before it was fixed). The recorded
+ *   fixture does not exercise the remaining ones, so tests cannot catch them; a fixed seed makes
+ *   every run deterministic until they are all fixed.
+ * - `PYTHONDONTWRITEBYTECODE=1`: the engine runs from the installed `dist/quant/engine`; without
+ *   this every first import would drop `__pycache__` into the shipped package directory.
+ */
+export declare function buildEngineEnv(opts: EngineSpawnOptions): NodeJS.ProcessEnv;
+/**
+ * Run `python -m quantdesk <args>` once; resolve when it exits (or is killed), never reject.
+ *
+ * @param args    The interface arguments after `-m quantdesk` (`run …` or `render …`).
+ * @param outPath The `--out` path inside `args`; read after exit. A missing or non-JSON file leaves
+ *                `out` undefined — the caller decides what that means from the exit code.
+ * @returns The raw process facts. Side effect: SIGKILLs the child if it outlives `timeoutMs`.
+ */
+export declare function spawnEngine(args: readonly string[], outPath: string, opts: EngineSpawnOptions): Promise<EngineProcessResult>;
+/**
+ * Interpret a finished engine process (spec §4.4 exit map). Pure — exported for tests.
+ * 0 done · 1 E_QUANT_UPSTREAM · 2 E_QUANT_INVALID_REQUEST · 3 E_QUANT_NO_ACTIVITY ·
+ * 4 E_QUANT_NOT_A_TRADER · anything else (the engine's crash code 70, the retired lock's 5, any
+ * code this runtime does not know) E_QUANT_ENGINE_ERROR. An exit 2 with NO result file is the
+ * engine's argument parser, mapped to E_QUANT_INVALID_REQUEST like any other exit 2; any other exit
+ * with no result file is an engine fault.
+ *
+ * Only exit 4 names `--force`: it is the one refusal a reader can knowingly override (read a vault
+ * as a trader). Every other next step is non-destructive and never suggests forcing.
+ *
+ * Exit 3's next step follows the request's voice: the engine's own-wallet guidance for `mine`,
+ * "a longer --days or another address" for `other` (someone else's wallet has no strategy wallets
+ * of the reader's to resolve).
+ *
+ * @param res       The process facts from {@link spawnEngine}.
+ * @param request   The request, to spell the exact re-run command in teaching text.
+ * @param timeoutMs The bound that was applied, for the timeout message.
+ * @param nowMs     "Now" for the index-coverage figure's staleness (exact count vs "over 25,000").
+ */
+export declare function mapEngineResult(res: EngineProcessResult, request: QuantRequest, timeoutMs: number, nowMs?: number): EngineOutcome;
+/**
+ * Run one desk. Writes the config into a private temp dir, reads the result file, removes the dir.
+ *
+ * @param request The validated request (addresses lowercased, days bounded) — the runtime's job.
+ * @param opts    Where the engine lives and where it keeps its cache/scratch (`stateDir`), plus
+ *                `fixture` for tests (the engine then replays a recording with no network).
+ * @returns The document, or a refused/failed outcome whose error leads with `[E_QUANT_*]`.
+ */
+export declare function runQuantEngine(request: QuantRequest, opts: RunEngineOptions): Promise<EngineOutcome>;
+/**
+ * Re-render sections of a stored run through render.py, so the engine stays the one producer of
+ * the desk's Markdown (a TypeScript renderer would drift). No network, no recompute.
+ *
+ * @param runFile  A stored run record (`runs/<id>.json`) or a bare document.
+ * @param sections Sections to render, in the order given; empty renders the whole desk.
+ * @returns The Markdown, or an `[E_QUANT_*]` error: TIMEOUT, INVALID_REQUEST (the engine's parser
+ *          refused, e.g. an unknown section) or ENGINE_ERROR (anything else, with the stderr tail;
+ *          `storedRunUnreadable` marks the exit-2-with-a-file case, see {@link RenderOutcome}).
+ */
+export declare function renderQuantMarkdown(runFile: string, sections: readonly QuantSection[], opts: EngineSpawnOptions): Promise<RenderOutcome>;
+//# sourceMappingURL=engine-runner.d.ts.map

package/dist/quant/engine-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-runner.d.ts","sourceRoot":"","sources":["../../src/quant/engine-runner.ts"],"names":[],"mappings":"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"}

package/dist/quant/engine-runner.js

@@ -0,0 +1,306 @@
+/**
+ * Spawns the Python desk engine (`python3 -m quantdesk`) and turns its result file into an outcome.
+ *
+ * - Spawned through utils/safe-spawn.ts: OpenClaw's install scanner blocks any plugin file holding
+ *   both a spawn call and the standard-library process module's name, so that name appears nowhere
+ *   in this file — not even here (pinned by the runner test's "install-scanner hygiene" case).
+ * - The result travels by FILE (spec D11, the live-stage precedent): the engine's stdout is drained
+ *   and ignored, so nothing it prints can corrupt the document.
+ * - stderr lines are forwarded as they arrive (the `[quant-desk] [n/8]` progress lines) and the
+ *   last 20 are kept for failure detail.
+ * - Outer timeout then SIGKILL. The engine has no timeout of its own that bounds a stalled socket.
+ * - The result file is strict JSON: non-finite figures arrive as the STRINGS "Infinity",
+ *   "-Infinity", "NaN". They parse as ordinary strings and are passed through untouched — they are
+ *   data, not a sign of a broken engine.
+ */
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "../utils/safe-spawn.js";
+import { QUANT_DOC_VERSION, QUANT_SECTIONS, SENPI_INDEX_COVERAGE, indexCoverageFigure, quantError, quantRunArgs, } from "./types.js";
+/** Outer bound on one desk run (spec §4.4). Past it the child is SIGKILLed → `E_QUANT_TIMEOUT`. */
+export const QUANT_ENGINE_TIMEOUT_MS = 240_000;
+/** Outer bound on re-rendering a stored run (no network, so far shorter than a run). */
+export const QUANT_RENDER_TIMEOUT_MS = 30_000;
+/** How many trailing stderr lines a failure carries — enough for a Python traceback's last frames. */
+const STDERR_TAIL_LINES = 20;
+/**
+ * argparse's exit status. `python -m quantdesk` itself exits 2 WITHOUT writing a result file when
+ * its own arguments are wrong (a bad `--section`, a missing `--out`): the parse fails before the
+ * interface has anywhere to write. Everything past parsing writes a file stating `exit_code`.
+ */
+const ARGPARSE_EXIT = 2;
+/** Narrow to a plain JSON object (not an array), else undefined. */
+function asRecord(x) {
+    return x !== null && typeof x === "object" && !Array.isArray(x) ? x : undefined;
+}
+/** A non-empty string, else undefined — so `??` fallbacks also cover "". */
+function str(x) {
+    return typeof x === "string" && x.length > 0 ? x : undefined;
+}
+/** The listed keys of `body` that are present, for a refusal's `details`. */
+function pick(body, keys) {
+    return Object.fromEntries(keys.filter((k) => body[k] !== undefined).map((k) => [k, body[k]]));
+}
+/**
+ * The child's environment. PYTHONPATH gets the engine dir first. MCP credentials are injected only
+ * when present — never as "" — mirroring the scanner launcher, so the engine's own "no token → no
+ * senpi client" path stays truthful.
+ *
+ * Two interpreter settings are forced, whatever the base env says:
+ * - `PYTHONHASHSEED=0`: the engine still has sites that iterate a `set` of strings (coin names,
+ *   wallets) where the order can reach the output. String hashing is randomised per process, so
+ *   those sites would make the same wallet produce different documents run to run (one such site
+ *   already made the oracle reproduce only two runs in three before it was fixed). The recorded
+ *   fixture does not exercise the remaining ones, so tests cannot catch them; a fixed seed makes
+ *   every run deterministic until they are all fixed.
+ * - `PYTHONDONTWRITEBYTECODE=1`: the engine runs from the installed `dist/quant/engine`; without
+ *   this every first import would drop `__pycache__` into the shipped package directory.
+ */
+export function buildEngineEnv(opts) {
+    const base = opts.env ?? process.env;
+    const env = { ...base };
+    env.PYTHONPATH = base.PYTHONPATH ? `${opts.engineDir}:${base.PYTHONPATH}` : opts.engineDir;
+    delete env.SENPI_AUTH_TOKEN;
+    delete env.SENPI_MCP_URL;
+    const token = opts.senpiAuthToken || base.SENPI_AUTH_TOKEN || base.SENPI_API_KEY || undefined;
+    const mcpUrl = opts.senpiMcpUrl || base.SENPI_MCP_URL || undefined;
+    if (token)
+        env.SENPI_AUTH_TOKEN = token;
+    if (mcpUrl)
+        env.SENPI_MCP_URL = mcpUrl;
+    env.PYTHONHASHSEED = "0";
+    env.PYTHONDONTWRITEBYTECODE = "1";
+    return env;
+}
+/**
+ * Run `python -m quantdesk <args>` once; resolve when it exits (or is killed), never reject.
+ *
+ * @param args    The interface arguments after `-m quantdesk` (`run …` or `render …`).
+ * @param outPath The `--out` path inside `args`; read after exit. A missing or non-JSON file leaves
+ *                `out` undefined — the caller decides what that means from the exit code.
+ * @returns The raw process facts. Side effect: SIGKILLs the child if it outlives `timeoutMs`.
+ */
+export function spawnEngine(args, outPath, opts) {
+    const python = opts.pythonBin ?? process.env.PYTHON ?? "python3";
+    const timeoutMs = opts.timeoutMs ?? QUANT_ENGINE_TIMEOUT_MS;
+    return new Promise((done) => {
+        const tail = [];
+        let pending = "";
+        let settled = false;
+        let timedOut = false;
+        const pushLine = (line) => {
+            if (line.length === 0)
+                return;
+            tail.push(line);
+            if (tail.length > STDERR_TAIL_LINES)
+                tail.shift();
+            opts.onStderrLine?.(line);
+        };
+        const child = spawn(python, ["-m", "quantdesk", ...args], { env: buildEngineEnv(opts), stdio: ["ignore", "pipe", "pipe"] });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (pending)
+                pushLine(pending);
+            done({ ...r, timedOut, stderrTail: [...tail] });
+        };
+        child.stdout?.on("data", () => undefined); // drained, never read: results travel by file
+        // Decode as a stream: the progress lines carry "…" and "—", and a chunk boundary can fall inside
+        // a multibyte character — String(buffer) per chunk would print replacement characters.
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            pending += String(chunk);
+            const lines = pending.split("\n");
+            pending = lines.pop() ?? "";
+            for (const l of lines)
+                pushLine(l.replace(/\r$/, ""));
+        });
+        child.on("error", (err) => finish({ exitCode: null, spawnError: err.message }));
+        child.on("close", (code) => {
+            let out;
+            try {
+                out = JSON.parse(readFileSync(outPath, "utf8"));
+            }
+            catch {
+                out = undefined;
+            }
+            finish({ exitCode: code, out });
+        });
+    });
+}
+/** An engine fault: never the wallet's doing, so the next step is to quote it, not to retry. */
+function engineError(text, stderrTail) {
+    return quantError("E_QUANT_ENGINE_ERROR", text, "This is a fault in the desk engine, not in the wallet. Quote the error; do not retry in a loop.", stderrTail.length > 0 ? { stderrTail: [...stderrTail] } : undefined);
+}
+/** The last stderr line carrying an argparse-style `error:` — the one sentence naming the cause. */
+function lastErrorLine(stderrTail) {
+    return [...stderrTail].reverse().find((l) => /error:/.test(l));
+}
+/** The interpreter never started: the fix is on the agent (python3), not in the request. */
+function spawnFailure(spawnError) {
+    return quantError("E_QUANT_ENGINE_ERROR", `the desk engine could not be started: ${spawnError}.`, "This agent needs python3 on its PATH (or PYTHON set to an interpreter). Nothing was computed.");
+}
+/**
+ * The engine's own argument parser refused (exit 2, no result file). The runtime builds these
+ * arguments, so this is a request the runtime should not have sent — a bad section name is the
+ * realistic case. The parser's last line ("…: error: argument --section: invalid choice …") is the
+ * one sentence worth showing, and it leads the message.
+ */
+function argparseRefusal(stderrTail) {
+    const why = lastErrorLine(stderrTail) ?? stderrTail[stderrTail.length - 1];
+    return quantError("E_QUANT_INVALID_REQUEST", `the desk engine refused its arguments${why ? `: ${why}` : "."}`, `Nothing was computed. Check the request: sections are ${QUANT_SECTIONS.join(", ")}; addresses are 0x followed by 40 hex characters.`, stderrTail.length > 0 ? { stderrTail: [...stderrTail] } : undefined);
+}
+/**
+ * Interpret a finished engine process (spec §4.4 exit map). Pure — exported for tests.
+ * 0 done · 1 E_QUANT_UPSTREAM · 2 E_QUANT_INVALID_REQUEST · 3 E_QUANT_NO_ACTIVITY ·
+ * 4 E_QUANT_NOT_A_TRADER · anything else (the engine's crash code 70, the retired lock's 5, any
+ * code this runtime does not know) E_QUANT_ENGINE_ERROR. An exit 2 with NO result file is the
+ * engine's argument parser, mapped to E_QUANT_INVALID_REQUEST like any other exit 2; any other exit
+ * with no result file is an engine fault.
+ *
+ * Only exit 4 names `--force`: it is the one refusal a reader can knowingly override (read a vault
+ * as a trader). Every other next step is non-destructive and never suggests forcing.
+ *
+ * Exit 3's next step follows the request's voice: the engine's own-wallet guidance for `mine`,
+ * "a longer --days or another address" for `other` (someone else's wallet has no strategy wallets
+ * of the reader's to resolve).
+ *
+ * @param res       The process facts from {@link spawnEngine}.
+ * @param request   The request, to spell the exact re-run command in teaching text.
+ * @param timeoutMs The bound that was applied, for the timeout message.
+ * @param nowMs     "Now" for the index-coverage figure's staleness (exact count vs "over 25,000").
+ */
+export function mapEngineResult(res, request, timeoutMs, nowMs = Date.now()) {
+    const again = `openclaw senpi quant run ${quantRunArgs(request)}`;
+    const failed = (error) => ({ ok: false, status: "failed", error });
+    const refused = (error) => ({ ok: false, status: "refused", error });
+    if (res.timedOut) {
+        return failed(quantError("E_QUANT_TIMEOUT", `the desk did not finish within ${Math.round(timeoutMs / 1000)}s and was stopped.`, `Run it once more — reads cached by the first attempt make the second faster: ${again}. Never start several at once.`, res.stderrTail.length > 0 ? { stderrTail: res.stderrTail } : undefined));
+    }
+    if (res.spawnError)
+        return failed(spawnFailure(res.spawnError));
+    const out = asRecord(res.out);
+    if (!out && res.exitCode === ARGPARSE_EXIT)
+        return refused(argparseRefusal(res.stderrTail));
+    const code = typeof out?.exit_code === "number" ? out.exit_code : undefined;
+    if (!out || code === undefined) {
+        return failed(engineError(`the desk engine exited ${res.exitCode ?? "abnormally"} without a result.`, res.stderrTail));
+    }
+    const body = asRecord(out.refusal) ?? {};
+    switch (code) {
+        case 0: {
+            const doc = asRecord(out.document);
+            if (!doc || doc.doc_version !== QUANT_DOC_VERSION || !Array.isArray(doc.cards)) {
+                return failed(engineError(`the engine returned a document this runtime cannot read (doc_version ${String(doc?.doc_version)}; expected ${QUANT_DOC_VERSION}).`, res.stderrTail));
+            }
+            return { ok: true, document: doc };
+        }
+        case 1:
+            return failed(quantError("E_QUANT_UPSTREAM", str(body.error) ?? "a Hyperliquid read failed.", str(body.what_to_do) ?? `One retry is worth it: ${again}`, pick(body, ["rate_limited"])));
+        case 2: {
+            // Exit 2 WITH a file: the engine rejected the config the runtime built (malformed config), or
+            // desk.py's own parser rejected the argv run() derived from it — then the body is only
+            // "no detail" and the real `error:` line is on stderr. Addresses were validated before the
+            // spawn, so this is a runtime defect, never something the reader can fix by retyping.
+            const bodyError = str(body.error);
+            const cause = bodyError && bodyError !== "no detail" ? bodyError : lastErrorLine(res.stderrTail) ?? bodyError ?? "no detail";
+            return refused(quantError("E_QUANT_INVALID_REQUEST", `the desk engine rejected the request the runtime built for it: ${cause}`, "Nothing was computed. The addresses passed validation, so this is a runtime defect the reader cannot fix: quote the error above and report it; do not retry with other input.", res.stderrTail.length > 0 ? { stderrTail: [...res.stderrTail] } : undefined));
+        }
+        case 3: {
+            // The engine says only WHETHER Senpi's index has the wallet; the count is the runtime's
+            // (SENPI_INDEX_COVERAGE), printed exact while fresh and as the round floor once stale.
+            const indexed = body.indexed === true ? true : body.indexed === false ? false : null;
+            const figure = indexCoverageFigure(nowMs);
+            const indexLine = indexed === false
+                ? `Senpi's index does not have this wallet yet: it covers ${figure} wallets with closed positions (as of ${SENPI_INDEX_COVERAGE.asOf}); wallets are added in waves — never promise a date.`
+                : indexed === true
+                    ? "Senpi's index has this wallet."
+                    : `Whether Senpi's index (${figure} wallets with closed positions, as of ${SENPI_INDEX_COVERAGE.asOf}) has this wallet cannot be told: nothing closed in the window either way.`;
+            // The engine's own-wallet guidance (resolve your strategy wallets with strategy_list) is for
+            // the reader's OWN book. An --other read is someone else's wallet: pointing the reader at
+            // their strategy wallets there answers a question they did not ask, so the analyst voice
+            // gets the one next step that can change the answer.
+            const own = request.whose === "other" ? undefined : str(body.if_this_is_your_own_wallet);
+            return refused(quantError("E_QUANT_NO_ACTIVITY", `${str(body.error) ?? "no perp activity in the window."} ${indexLine}${own ? ` If this is your own wallet: ${own}` : ""}`, request.whose === "other"
+                ? "This wallet had no perp activity in the window; try a longer --days or another address."
+                : own ?? str(body.what_this_usually_means) ?? "Try a wallet with perp trades in the window, or a longer --days.", { indexed, indexedWallets: SENPI_INDEX_COVERAGE.indexedWallets, indexAsOf: SENPI_INDEX_COVERAGE.asOf,
+                ...pick(body, ["if_this_is_your_own_wallet", "what_this_usually_means", "perp_fills_in_window", "open_perp_positions"]) }));
+        }
+        case 4: {
+            const say = str(body.say_to_the_reader);
+            return refused(quantError("E_QUANT_NOT_A_TRADER", str(body.error) ?? "this address is not a trader's book.", `${say ? `Tell the reader: ${say} ` : ""}Only if they still want it read as a trader: ${again} --force`, pick(body, ["not_a_trader", "say_to_the_reader", "if_you_meant_it", "name", "coins", "tape_cap"])));
+        }
+        default:
+            return failed(engineError(str(asRecord(out.crash)?.error) ?? `the desk engine exited ${code}.`, res.stderrTail));
+    }
+}
+/**
+ * Run one desk. Writes the config into a private temp dir, reads the result file, removes the dir.
+ *
+ * @param request The validated request (addresses lowercased, days bounded) — the runtime's job.
+ * @param opts    Where the engine lives and where it keeps its cache/scratch (`stateDir`), plus
+ *                `fixture` for tests (the engine then replays a recording with no network).
+ * @returns The document, or a refused/failed outcome whose error leads with `[E_QUANT_*]`.
+ */
+export async function runQuantEngine(request, opts) {
+    const dir = mkdtempSync(join(tmpdir(), "senpi-quant-"));
+    try {
+        const configPath = join(dir, "config.json");
+        const outPath = join(dir, "out.json");
+        writeFileSync(configPath, JSON.stringify({
+            addresses: request.addresses, days: request.days, whose: request.whose, book: request.book, force: request.force,
+            state_dir: opts.stateDir, ...(opts.fixture ? { fixture: opts.fixture } : {}),
+        }), "utf8");
+        const res = await spawnEngine(["run", "--config", configPath, "--out", outPath], outPath, opts);
+        return mapEngineResult(res, request, opts.timeoutMs ?? QUANT_ENGINE_TIMEOUT_MS);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Re-render sections of a stored run through render.py, so the engine stays the one producer of
+ * the desk's Markdown (a TypeScript renderer would drift). No network, no recompute.
+ *
+ * @param runFile  A stored run record (`runs/<id>.json`) or a bare document.
+ * @param sections Sections to render, in the order given; empty renders the whole desk.
+ * @returns The Markdown, or an `[E_QUANT_*]` error: TIMEOUT, INVALID_REQUEST (the engine's parser
+ *          refused, e.g. an unknown section) or ENGINE_ERROR (anything else, with the stderr tail;
+ *          `storedRunUnreadable` marks the exit-2-with-a-file case, see {@link RenderOutcome}).
+ */
+export async function renderQuantMarkdown(runFile, sections, opts) {
+    const dir = mkdtempSync(join(tmpdir(), "senpi-quant-render-"));
+    try {
+        const outPath = join(dir, "out.json");
+        const args = ["render", "--doc", runFile, ...sections.flatMap((s) => ["--section", s]), "--out", outPath];
+        const timeoutMs = opts.timeoutMs ?? QUANT_RENDER_TIMEOUT_MS;
+        const res = await spawnEngine(args, outPath, { ...opts, timeoutMs });
+        const out = asRecord(res.out);
+        if (out?.exit_code === 0 && typeof out.markdown === "string")
+            return { ok: true, markdown: out.markdown };
+        if (res.timedOut) {
+            return { ok: false, error: quantError("E_QUANT_TIMEOUT", `rendering the stored desk did not finish within ${Math.round(timeoutMs / 1000)}s and was stopped.`, "Rendering reads no network; read the stored run's document instead of retrying in a loop.", res.stderrTail.length > 0 ? { stderrTail: [...res.stderrTail] } : undefined) };
+        }
+        if (res.spawnError)
+            return { ok: false, error: spawnFailure(res.spawnError) };
+        if (!out && res.exitCode === ARGPARSE_EXIT)
+            return { ok: false, error: argparseRefusal(res.stderrTail) };
+        const why = str(asRecord(out?.refusal)?.error) ?? str(asRecord(out?.crash)?.error);
+        return {
+            ok: false,
+            error: engineError(`rendering the stored desk failed (exit ${String(out?.exit_code ?? res.exitCode)})${why ? `: ${why}` : "."}`, res.stderrTail),
+            ...(out?.exit_code === ARGPARSE_EXIT ? { storedRunUnreadable: why ?? "the stored run could not be read" } : {}),
+        };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=engine-runner.js.map

package/dist/quant/engine-runner.js.map

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

package/dist/quant/job.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The quant job controller: one in-flight desk per wallet set, run detached, finished into the
+ * registry.
+ *
+ * The slot is IN-MEMORY ONLY (the deploy/job.ts idiom): a persisted slot would wedge a wallet after
+ * a crash. The freshness lookup is async, so the slot is checked and claimed AFTER it, with no await
+ * between the check and the claim — two simultaneous starts cannot both pass, and a cached answer
+ * never takes the slot. The engine runner's own outer timeout is the watchdog: it always settles.
+ *
+ * Restart safety: a `running` row left in the index by a dead process must never read as live. The
+ * boot janitor ({@link QuantRunRegistry.markInterrupted}) stamps those rows, and it has to run
+ * BEFORE this process creates a run of its own — otherwise it would stamp a live run. The gateway
+ * methods are registered (and callable) before the plugin service's `start()`, so waiting for the
+ * service is not enough: every `start` awaits {@link QuantJobController.recoverInterrupted} first,
+ * and so do the read paths, so no caller can observe a dead run as running.
+ */
+import type { EngineOutcome } from "./engine-runner.js";
+import type { QuantRunRegistry } from "./registry.js";
+import { type QuantError, type QuantRequest, type QuantRunStatus } from "./types.js";
+/**
+ * A start refused because the same wallet set already has a run in flight. Carries the running id
+ * so the refusal can name it and `senpi quant status <id>` — a second run would not finish the first
+ * any sooner, it would only halve both runs' share of Hyperliquid's rate limit.
+ */
+export declare class QuantInProgressError extends Error {
+    readonly runId: string;
+    readonly addresses: readonly string[];
+    constructor(runId: string, addresses: readonly string[]);
+}
+/**
+ * A start refused because the boot janitor (stamping runs a restart cut short) failed. Kept apart
+ * from other start failures so the gateway can name the recovery step: the quant state dir must be
+ * writable; the next start retries the cleanup.
+ */
+export declare class QuantJanitorError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/**
+ * What `start` answers: a new running run (`cached: false`), or a done run for the same request
+ * finished inside the freshness window, served from the registry (`status: "done"`, `cached: true`).
+ */
+export interface QuantStartResult {
+    runId: string;
+    status: "running" | "done";
+    cached: boolean;
+}
+/**
+ * One run's status as the gateway reports it. `progress` is the engine's latest `[quant-desk]`
+ * stderr line and exists only while this process runs the desk; `error` only on failed/refused.
+ */
+export interface QuantStatus {
+    runId: string;
+    status: QuantRunStatus;
+    startedAt: string;
+    finishedAt?: string;
+    progress?: string;
+    error?: QuantError;
+    addresses: readonly string[];
+    days: number;
+}
+/** Collaborators; `runEngine` is injected so the controller is testable without Python. */
+export interface QuantJobControllerOptions {
+    registry: QuantRunRegistry;
+    /** Run one desk. Must always settle (the real runner has its own SIGKILL timeout). */
+    runEngine(request: QuantRequest, onProgress: (line: string) => void): Promise<EngineOutcome>;
+    /** Stamped into each run's meta (the runtime package version). */
+    engineVersion: string;
+    log(line: string): void;
+}
+/** Single-flight desk runs. See the module doc for the slot and restart invariants. */
+export declare class QuantJobController {
+    private readonly opts;
+    private readonly bySet;
+    private readonly byId;
+    private janitor?;
+    constructor(opts: QuantJobControllerOptions);
+    /**
+     * Run the registry's boot janitor once per process and answer the ids it stamped failed.
+     *
+     * Memoized: the plugin service calls it at start (to log what a restart cut short), and `start`
+     * awaits it before claiming a slot, whichever comes first. A failure is NOT memoized — the next
+     * caller retries — and `start` refuses while it fails, so this process never creates a run the
+     * janitor has not yet had a chance to run ahead of (which it would then stamp as dead).
+     */
+    recoverInterrupted(): Promise<string[]>;
+    /**
+     * Serve a fresh run, or claim the wallet set's slot and start the engine detached.
+     *
+     * Order: janitor → freshness (async) → check-and-claim (sync) → create record → spawn. The claim
+     * follows the last await before it, so of two simultaneous starts exactly one claims and the other
+     * sees the slot taken.
+     *
+     * @throws {QuantInProgressError} when the wallet set (case- and order-insensitive) has a run in flight.
+     * @throws {QuantJanitorError} when the boot janitor fails; nothing runs, the next start retries it.
+     * @throws When the record write fails; the slot is released and nothing runs.
+     */
+    start(request: QuantRequest, options: {
+        fresh: boolean;
+    }): Promise<QuantStartResult>;
+    /**
+     * A run's status; no id = the newest run. `undefined` when there is no such run (including an
+     * invalid, path-like id — the registry never resolves one). Waits for the boot janitor, so a run a
+     * restart cut short reads `failed`, never `running`. A janitor failure does not block reads.
+     *
+     * A record that says `running` while this process has no live job for it is dead — every run of
+     * this process is live from before its record is written until after its outcome is — whether the
+     * outcome could not be recorded (disk full after create) or a failing janitor left a restart's
+     * row. It is answered `failed` with the re-run command, and stamped failed best-effort (the
+     * registry keeps the first outcome, so this can never overwrite a real one).
+     *
+     * @throws {QuantRunLookupError} (from the registry) for a record of another docVersion.
+     */
+    status(runId?: string): Promise<QuantStatus | undefined>;
+    /** Resolves when a live run has been finished into the registry (immediately if not live). Tests use it. */
+    waitFor(runId: string): Promise<void>;
+    /**
+     * Run the engine and record its outcome. Never rejects: an engine that throws (spawn exploded) is
+     * recorded as `E_QUANT_ENGINE_ERROR`, and a failure to record even that is logged. The slot is
+     * always released, so a wallet can never stay busy after its run ended. The registry's `finish`
+     * keeps the first outcome, so a late second finisher cannot overwrite a delivered desk.
+     */
+    private execute;
+}
+//# sourceMappingURL=job.d.ts.map

package/dist/quant/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../../src/quant/job.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAA2C,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9H;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM;IAAE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE;gBAApD,KAAK,EAAE,MAAM,EAAW,SAAS,EAAE,SAAS,MAAM,EAAE;CAI1E;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;CAIpC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2FAA2F;AAC3F,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,sFAAsF;IACtF,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7F,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAuBD,uFAAuF;AACvF,qBAAa,kBAAkB;IAKjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IACnD,OAAO,CAAC,OAAO,CAAC,CAAoB;gBAEP,IAAI,EAAE,yBAAyB;IAE5D;;;;;;;OAOG;IACH,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAWvC;;;;;;;;;;OAUG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2B1F;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAwC9D,4GAA4G;IAC5G,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC;;;;;OAKG;YACW,OAAO;CAiBtB"}