@attest-ai/core 1.0.0-rc.5 → 1.0.1

package/dist/esm/index.js

@@ -219,8 +219,8 @@ function extractId(response) {
 }
 
 // src/version.ts
-var VERSION = "1.0.0-rc.5";
-var ENGINE_VERSION = "1.0.0-rc.5";
+var VERSION = "1.0.1";
+var ENGINE_VERSION = "1.0.1";
 
 // src/engine-manager.ts
 import { spawn, spawnSync } from "child_process";
@@ -228,6 +228,565 @@ import { createInterface } from "readline";
 import { existsSync, accessSync, statSync as statSync2, constants as fsConstants } from "fs";
 import { delimiter, join as join2 } from "path";
 
+// src/config.ts
+var _simulationMode = false;
+var _sampleRate = 0;
+function config(options2) {
+  if (options2.simulation !== void 0) {
+    _simulationMode = options2.simulation;
+  }
+  if (options2.sampleRate !== void 0) {
+    if (options2.sampleRate < 0 || options2.sampleRate > 1) {
+      throw new RangeError(
+        `sampleRate must be between 0.0 and 1.0, got ${options2.sampleRate}`
+      );
+    }
+    _sampleRate = options2.sampleRate;
+  }
+}
+function isSimulationMode() {
+  return _simulationMode || simulationEnvEnabled();
+}
+function simulationEnvEnabled() {
+  const env = (process.env["ATTEST_SIMULATION"] ?? "").trim().toLowerCase();
+  return env === "1" || env === "true" || env === "yes";
+}
+function getSampleRate() {
+  if (_sampleRate > 0) return _sampleRate;
+  const env = process.env["ATTEST_SAMPLE_RATE"];
+  if (env !== void 0 && env !== "") {
+    const parsed = Number(env);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+      throw new RangeError(
+        `ATTEST_SAMPLE_RATE must be between 0.0 and 1.0, got '${env}'`
+      );
+    }
+    return parsed;
+  }
+  return 0;
+}
+function resetConfig() {
+  _simulationMode = false;
+  _sampleRate = 0;
+}
+
+// src/usage.ts
+var INT_FIELDS = [
+  "model_calls",
+  "judge_calls",
+  "input_tokens",
+  "output_tokens",
+  "cached_tokens",
+  "unpriced_calls",
+  "budget_refused"
+];
+var USD_FIELDS = ["cost_usd", "retry_cost_usd"];
+function zeroUsage() {
+  return {
+    model_calls: 0,
+    judge_calls: 0,
+    input_tokens: 0,
+    output_tokens: 0,
+    cached_tokens: 0,
+    cost_usd: 0,
+    retry_cost_usd: 0,
+    unpriced_calls: 0,
+    budget_refused: 0
+  };
+}
+function addUsage(a, b) {
+  return {
+    model_calls: a.model_calls + b.model_calls,
+    judge_calls: a.judge_calls + b.judge_calls,
+    input_tokens: a.input_tokens + b.input_tokens,
+    output_tokens: a.output_tokens + b.output_tokens,
+    cached_tokens: a.cached_tokens + b.cached_tokens,
+    cost_usd: a.cost_usd + b.cost_usd,
+    retry_cost_usd: a.retry_cost_usd + b.retry_cost_usd,
+    unpriced_calls: a.unpriced_calls + b.unpriced_calls,
+    budget_refused: a.budget_refused + b.budget_refused
+  };
+}
+function sumUsage(usages) {
+  let total = zeroUsage();
+  for (const u of usages) total = addUsage(total, u);
+  return total;
+}
+function parseUsage(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError(`evaluate_batch result: usage must be an object, got ${JSON.stringify(raw)}`);
+  }
+  const obj = raw;
+  const field = (name, integer) => {
+    const v = obj[name];
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0 || integer && !Number.isInteger(v)) {
+      const kind = integer ? "a non-negative integer" : "a non-negative number";
+      throw new TypeError(`evaluate_batch result: usage.${name} must be ${kind}, got ${JSON.stringify(v)}`);
+    }
+    return v;
+  };
+  const ints = Object.fromEntries(INT_FIELDS.map((f) => [f, field(f, true)]));
+  const usd = Object.fromEntries(USD_FIELDS.map((f) => [f, field(f, false)]));
+  return { ...ints, ...usd };
+}
+function formatUsage(u) {
+  let line = `${u.model_calls} model calls \xB7 ${u.input_tokens + u.output_tokens} tokens (${u.cached_tokens} cached) \xB7 $${u.cost_usd.toFixed(4)} \xB7 retry cost $${u.retry_cost_usd.toFixed(4)}`;
+  if (u.budget_refused > 0) line += ` \xB7 ${u.budget_refused} calls refused by budget`;
+  if (u.unpriced_calls > 0) line += ` \xB7 ${u.unpriced_calls} unpriced calls not in $`;
+  return line;
+}
+function usageSummaryLine(u) {
+  if (u.model_calls === 0 && u.budget_refused === 0) return void 0;
+  return `attest usage: ${formatUsage(u)}`;
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_DIAGNOSTIC_BUFFER = 32;
+var DEFAULT_DESYNC_THRESHOLD = 3;
+var DEFAULT_DESYNC_WINDOW_MS = 1e3;
+function resolveTimeoutMs(override) {
+  if (override !== void 0) return override;
+  const env = process.env["ATTEST_ENGINE_TIMEOUT"];
+  if (env !== void 0 && env !== "") {
+    const parsed = Number(env);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      throw new Error(
+        `ATTEST_ENGINE_TIMEOUT must be a positive number of milliseconds, got: '${env}'`
+      );
+    }
+    return parsed;
+  }
+  return DEFAULT_TIMEOUT_MS;
+}
+function debugProtocolEnabled() {
+  const flag = process.env["ATTEST_DEBUG_PROTOCOL"];
+  return flag === "1" || flag === "true" || flag === "yes";
+}
+function envLoggerDefault() {
+  if (debugProtocolEnabled()) {
+    return {
+      warn: (msg, ...args) => console.warn(msg, ...args),
+      error: (msg, ...args) => console.error(msg, ...args)
+    };
+  }
+  return {
+    warn: () => {
+    },
+    error: () => {
+    }
+  };
+}
+var AttestClient = class {
+  engine;
+  requestId = 0;
+  pending = /* @__PURE__ */ new Map();
+  writeChain = Promise.resolve();
+  readerActive = false;
+  lineHandler = null;
+  attachedReader = null;
+  logger;
+  diagnosticBuffer;
+  diagnosticListeners = /* @__PURE__ */ new Set();
+  desyncThreshold;
+  desyncWindowMs;
+  desynced = false;
+  constructor(engine, options2) {
+    this.engine = engine;
+    this.logger = options2?.logger ?? envLoggerDefault();
+    this.diagnosticBuffer = new ProtocolDiagnosticBuffer(
+      options2?.diagnosticBufferSize ?? DEFAULT_DIAGNOSTIC_BUFFER
+    );
+    this.desyncThreshold = options2?.desyncThreshold ?? DEFAULT_DESYNC_THRESHOLD;
+    this.desyncWindowMs = options2?.desyncWindowMs ?? DEFAULT_DESYNC_WINDOW_MS;
+    if (options2?.onDiagnostic !== void 0) {
+      this.diagnosticListeners.add(options2.onDiagnostic);
+    }
+  }
+  /** Subscribe to protocol diagnostics. Returns an unsubscribe function. */
+  onProtocolDiagnostic(listener) {
+    this.diagnosticListeners.add(listener);
+    return () => {
+      this.diagnosticListeners.delete(listener);
+    };
+  }
+  /** Snapshot of the diagnostic ring buffer (most recent last). */
+  protocolDiagnostics() {
+    return this.diagnosticBuffer.snapshot();
+  }
+  /**
+   * Attach the id-routed reader to the engine's stdout. Idempotent; `sendRequest` starts it
+   * on first use, so calling it is optional.
+   */
+  startReader() {
+    if (this.readerActive) return;
+    const rl = this.engine.readlineInterface;
+    if (rl === null) {
+      throw new Error("Engine readline interface not available. Call engine.start() first.");
+    }
+    this.readerActive = true;
+    this.attachedReader = rl;
+    this.lineHandler = (line) => this.handleLine(line);
+    rl.on("line", this.lineHandler);
+    rl.on("close", () => {
+      if (this.attachedReader !== rl) return;
+      const tail = this.engine.stderrTail ?? "";
+      this.failAll(
+        new Error(tail === "" ? "Engine closed stdout." : `Engine closed stdout. stderr:
+${tail}`)
+      );
+      this.readerActive = false;
+      this.attachedReader = null;
+    });
+  }
+  stopReader() {
+    if (!this.readerActive) return;
+    const rl = this.attachedReader;
+    if (rl !== null && this.lineHandler !== null) {
+      rl.removeListener("line", this.lineHandler);
+    }
+    this.lineHandler = null;
+    this.readerActive = false;
+    this.attachedReader = null;
+  }
+  recordDiagnostic(kind, message, rawLine, countsTowardDesync = true) {
+    const diagnostic = {
+      kind,
+      message,
+      rawLine: previewLine(rawLine),
+      timestampMs: Date.now()
+    };
+    this.diagnosticBuffer.push(diagnostic);
+    this.logger.warn(`[attest.protocol] ${kind}: ${message}`);
+    for (const listener of this.diagnosticListeners) {
+      try {
+        listener(diagnostic);
+      } catch (err) {
+        this.logger.error(
+          `[attest.protocol] diagnostic listener threw: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    if (countsTowardDesync) this.maybeTriggerDesync(diagnostic.timestampMs);
+  }
+  maybeTriggerDesync(nowMs) {
+    if (this.desynced) return;
+    const recent = this.diagnosticBuffer.countWithin(this.desyncWindowMs, nowMs);
+    if (recent >= this.desyncThreshold) {
+      this.desynced = true;
+      const snapshot = this.diagnosticBuffer.snapshot();
+      const err = new ProtocolDesyncError(
+        `Engine protocol desync: ${recent} unroutable response lines within ${this.desyncWindowMs}ms.`,
+        snapshot
+      );
+      this.logger.error(`[attest.protocol] ${err.message}`);
+      this.failAll(err);
+    }
+  }
+  handleLine(line) {
+    let response;
+    try {
+      response = decodeResponse(line);
+    } catch (err) {
+      this.handleDecodeFailure(line, err);
+      return;
+    }
+    let reqId;
+    try {
+      reqId = extractId(response);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.recordDiagnostic("missing_id", message, line, false);
+      return;
+    }
+    const pending = this.pending.get(reqId);
+    if (pending === void 0) {
+      this.recordDiagnostic(
+        "unknown_id",
+        `no pending request for id=${reqId}`,
+        line
+      );
+      return;
+    }
+    this.pending.delete(reqId);
+    try {
+      const result = extractResult(response);
+      pending.resolve(result);
+    } catch (err) {
+      pending.reject(err);
+    }
+  }
+  handleDecodeFailure(line, err) {
+    if (err instanceof ProtocolError) {
+      let reqId = -1;
+      try {
+        const raw = JSON.parse(line.trim());
+        const idCandidate = raw["id"];
+        if (typeof idCandidate === "number" && Number.isFinite(idCandidate)) {
+          reqId = idCandidate;
+        }
+      } catch {
+        reqId = -1;
+      }
+      const pending = this.pending.get(reqId);
+      if (pending !== void 0) {
+        this.pending.delete(reqId);
+        pending.reject(err);
+        return;
+      }
+      this.recordDiagnostic(
+        "non_routable_error",
+        `engine error code=${err.code} (${err.errorMessage}) had no matching pending id`,
+        line
+      );
+      return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const kind = classifyDecodeError(message);
+    this.recordDiagnostic(kind, message, line);
+  }
+  /** Reject every request still waiting for a response. */
+  rejectPending(err) {
+    this.failAll(err);
+  }
+  failAll(err) {
+    for (const pending of this.pending.values()) {
+      pending.reject(err);
+    }
+    this.pending.clear();
+  }
+  /**
+   * Send one request and resolve with the result of the response that carries its id.
+   *
+   * After a timeout the engine is restarted (its late response can no longer be matched),
+   * every other pending request is rejected, and the new engine gets the remaining session
+   * budget.
+   */
+  async sendRequest(method, params, timeoutMs) {
+    return this.send(method, params, timeoutMs, true);
+  }
+  /** `sendRequest` without the restart-on-timeout step, for the engine's own handshake. */
+  async sendWithoutRestart(method, params, timeoutMs) {
+    return this.send(method, params, timeoutMs, false);
+  }
+  async send(method, params, timeoutMs, restartOnTimeout) {
+    if (restartOnTimeout) await this.engine.whenReady?.();
+    const shared = this.engine.client;
+    if (shared !== void 0 && shared !== this) {
+      return restartOnTimeout ? shared.sendRequest(method, params, timeoutMs) : shared.sendWithoutRestart(method, params, resolveTimeoutMs(timeoutMs));
+    }
+    if (this.desynced) {
+      throw new ProtocolDesyncError(
+        "Engine protocol is desynced; AttestClient will not send further requests.",
+        this.diagnosticBuffer.snapshot()
+      );
+    }
+    const resolvedTimeout = resolveTimeoutMs(timeoutMs);
+    if (this.engine.isRunning === false) {
+      const tail = this.engine.stderrTail ?? "";
+      throw new Error(`Engine process is not running.${tail === "" ? "" : ` stderr:
+${tail}`}`);
+    }
+    const cp = this.engine.childProcess;
+    if (cp === null || cp.stdin === null) {
+      throw new Error("Engine process not started.");
+    }
+    this.startReader();
+    const reservation = worstCaseReservation(method, params);
+    let capturedReqId;
+    let timer;
+    const requestPromise = new Promise((resolve5, reject) => {
+      this.writeChain = this.writeChain.then(() => {
+        this.requestId += 1;
+        const reqId = this.requestId;
+        capturedReqId = reqId;
+        this.pending.set(reqId, { resolve: resolve5, reject, reservation });
+        const requestStr = encodeRequest(reqId, method, params);
+        cp.stdin.write(requestStr, (err) => {
+          if (err) {
+            this.pending.delete(reqId);
+            reject(this.describeWriteError(err));
+          }
+        });
+      });
+    });
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new EngineTimeoutError(method, resolvedTimeout)), resolvedTimeout);
+    });
+    try {
+      return await Promise.race([requestPromise, timeoutPromise]);
+    } catch (err) {
+      if (err instanceof EngineTimeoutError) {
+        if (capturedReqId !== void 0) this.pending.delete(capturedReqId);
+        if (restartOnTimeout) await this.recoverFromTimeout(method, params, err);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /** A failed pipe write names the engine's stderr tail; the original error stays as `cause` and `code`. */
+  describeWriteError(err) {
+    const tail = this.engine.stderrTail ?? "";
+    const wrapped = new Error(
+      `Failed to write to the engine: ${err.message}.${tail === "" ? "" : ` stderr:
+${tail}`}`,
+      { cause: err }
+    );
+    return Object.assign(wrapped, { code: err.code });
+  }
+  async recoverFromTimeout(method, params, timeout) {
+    if (this.engine.restartAfterTimeout === void 0 || this.engine.client !== this) return;
+    const abandoned = [
+      worstCaseReservation(method, params),
+      ...[...this.pending.values()].map((p) => p.reservation)
+    ];
+    this.failAll(new Error(`Engine restarted after '${method}' timed out; request abandoned.`));
+    try {
+      await this.engine.restartAfterTimeout(abandoned);
+    } catch (err) {
+      throw new Error(
+        `Engine request '${method}' timed out and the engine could not be restarted: ` + (err instanceof Error ? err.message : String(err)),
+        { cause: timeout }
+      );
+    }
+  }
+  async evaluateBatch(trace, assertions, options2) {
+    if (isSimulationMode()) {
+      requireSimulationCapability(this.engine["initResult"]);
+    }
+    const params = {
+      trace,
+      assertions: [...assertions],
+      ...options2?.budget !== void 0 ? { budget: options2.budget } : {},
+      ...options2?.context !== void 0 ? { context: options2.context } : {}
+    };
+    let raw;
+    try {
+      raw = await this.sendRequest(
+        "evaluate_batch",
+        params,
+        options2?.timeout
+      );
+    } catch (err) {
+      if (err instanceof ProtocolError) this.engine.markUnknownSpend?.();
+      throw err;
+    }
+    const usage = parseUsage(raw["usage"]);
+    this.engine.recordUsage?.(usage);
+    const result = raw;
+    this.requireSentAssertionIds(assertions, result);
+    return { ...result, usage };
+  }
+  /** Reject a response whose assertion ids differ from the ids that were sent. */
+  requireSentAssertionIds(assertions, result) {
+    const sent = new Set(assertions.map((a) => a.assertion_id));
+    const returned = new Set((result.results ?? []).map((r) => r.assertion_id));
+    const missing = [...sent].filter((id) => !returned.has(id));
+    const unexpected = [...returned].filter((id) => !sent.has(id));
+    if (missing.length === 0 && unexpected.length === 0) return;
+    throw new ProtocolDesyncError(
+      `evaluate_batch response does not match the request: missing assertion ids [${missing.join(", ")}], unexpected [${unexpected.join(", ")}].`,
+      this.diagnosticBuffer.snapshot()
+    );
+  }
+  async submitPluginResult(traceId2, pluginName, assertionId2, status, score, explanation, options2) {
+    const result = {
+      assertion_id: assertionId2,
+      status,
+      score,
+      explanation,
+      cost: 0,
+      duration_ms: 0
+    };
+    const params = {
+      trace_id: traceId2,
+      plugin_name: pluginName,
+      assertion_id: assertionId2,
+      result
+    };
+    const raw = await this.sendRequest(
+      "submit_plugin_result",
+      params,
+      options2?.timeout
+    );
+    return Boolean(raw?.accepted ?? false);
+  }
+  async queryDrift(assertionId2, windowSize = 50, options2) {
+    if (isSimulationMode()) {
+      return {
+        assertion_id: assertionId2,
+        mean: 0,
+        stddev: 0,
+        count: 0,
+        latest_score: 0,
+        deviation: 0,
+        status: "no_data"
+      };
+    }
+    const raw = await this.sendRequest(
+      "query_drift",
+      { assertion_id: assertionId2, window_size: windowSize },
+      options2?.timeout
+    );
+    return raw.report;
+  }
+  async generateUserMessage(persona, conversationHistory, faultConfig, options2) {
+    if (isSimulationMode()) {
+      return `[simulation] Hello from ${persona.name}`;
+    }
+    const params = {
+      persona,
+      conversation_history: conversationHistory
+    };
+    if (faultConfig !== void 0) {
+      params.fault_config = faultConfig;
+    }
+    let raw;
+    try {
+      raw = await this.sendRequest(
+        "generate_user_message",
+        params,
+        options2?.timeout
+      );
+    } catch (err) {
+      if (err instanceof ProtocolError) this.engine.markUnknownSpend?.();
+      throw err;
+    }
+    this.engine.markUnknownSpend?.();
+    return String(raw.message);
+  }
+};
+function worstCaseReservation(method, params) {
+  if (method === "generate_user_message") return { judgeCalls: null, usd: null };
+  if (method !== "evaluate_batch") return { judgeCalls: 0, usd: 0 };
+  const assertions = params["assertions"] ?? [];
+  const judges = assertions.some((a) => a.type === "llm_judge");
+  const paid = judges || assertions.some((a) => a.type === "embedding");
+  const budget = params["budget"];
+  return {
+    judgeCalls: judges ? budget?.max_judge_calls ?? null : 0,
+    usd: paid ? budget?.max_cost_usd ?? null : 0
+  };
+}
+function classifyDecodeError(message) {
+  if (message.startsWith("malformed JSON")) return "malformed_json";
+  if (message.startsWith("expected JSON object")) return "non_object_response";
+  if (message.startsWith("invalid jsonrpc version")) return "invalid_jsonrpc_version";
+  if (message.startsWith("empty response line")) return "malformed_json";
+  return "malformed_json";
+}
+function requireSimulationCapability(init) {
+  if (init === null || init === void 0) {
+    throw new Error("simulation mode: the engine has not been initialized");
+  }
+  if (!(init.capabilities ?? []).includes("simulation_mode")) {
+    throw new Error(
+      `simulation mode is on but attest-engine ${init.engine_version} was not started in simulation mode (capability 'simulation_mode' missing), so it would call real providers. Set ATTEST_SIMULATION=1 before the engine starts (the Vitest fixtures do this for you) and use attest-engine 1.0 or later.`
+    );
+  }
+}
+
 // src/engine-downloader.ts
 import * as https from "https";
 import * as http from "http";
@@ -344,686 +903,349 @@ async function downloadEngine() {
   const dir = versionedBinDir();
   fs.mkdirSync(dir, { recursive: true });
   const destPath = path.join(dir, binaryFilename());
-  const suffix = `${String(process.pid)}.${crypto.randomBytes(8).toString("hex")}`;
-  const tmpPath = path.join(dir, `.${binaryFilename()}.tmp.${suffix}`);
-  try {
-    fs.writeFileSync(tmpPath, data, { flag: "wx", mode: 493 });
-    fs.chmodSync(tmpPath, 493);
-    fs.renameSync(tmpPath, destPath);
-  } catch (err) {
-    if (err.code !== "EEXIST") fs.rmSync(tmpPath, { force: true });
-    throw err;
-  }
-  process.stderr.write(`[attest] Engine installed at ${destPath}
-`);
-  return destPath;
-}
-
-// src/engine-manager.ts
-var ENGINE_BINARY_NAME = "attest-engine";
-var VERSION_PROBE_TIMEOUT_MS = 1e4;
-var EngineVersionMismatchError = class extends Error {
-  enginePath;
-  source;
-  found;
-  required;
-  constructor(enginePath, source, found, required) {
-    const reported = found === null ? "reports no version" : `reports version ${found}`;
-    super(
-      `attest-engine at ${enginePath} (from ${source}) ${reported}; this SDK requires attest-engine ${required}. Point ATTEST_ENGINE_PATH at a matching engine, or remove the mismatched one from PATH so the SDK can download ${required} into ~/.attest/bin/${required}/.`
-    );
-    this.name = "EngineVersionMismatchError";
-    this.enginePath = enginePath;
-    this.source = source;
-    this.found = found;
-    this.required = required;
-  }
-};
-function engineVersion(enginePath) {
-  const proc = spawnSync(enginePath, ["version"], {
-    stdio: ["ignore", "pipe", "pipe"],
-    encoding: "utf-8",
-    timeout: VERSION_PROBE_TIMEOUT_MS
-  });
-  if (proc.error) throw proc.error;
-  const out = proc.stdout.trim();
-  const prefix = `${ENGINE_BINARY_NAME} `;
-  if (proc.status !== 0 || !out.startsWith(prefix)) return null;
-  return out.slice(prefix.length).trim();
-}
-function onPath() {
-  for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
-    if (!dir) continue;
-    const candidate = join2(dir, binaryFilename());
-    try {
-      accessSync(candidate, fsConstants.X_OK);
-    } catch {
-      continue;
-    }
-    if (statSync2(candidate).isFile()) return candidate;
-  }
-  return null;
-}
-function requireFile(enginePath, label) {
-  if (!existsSync(enginePath) || !statSync2(enginePath).isFile()) {
-    throw new Error(`${label}=${enginePath} does not exist or is not a file.`);
-  }
-}
-async function locateEngine(explicitPath, allowDownload) {
-  if (explicitPath) {
-    requireFile(explicitPath, "Engine path");
-    return [explicitPath, "explicit engine path"];
-  }
-  const envPath = process.env["ATTEST_ENGINE_PATH"];
-  if (envPath) {
-    requireFile(envPath, "ATTEST_ENGINE_PATH");
-    return [envPath, "ATTEST_ENGINE_PATH"];
-  }
-  const found = onPath();
-  if (found) return [found, "PATH"];
-  const cached = cachedEnginePath();
-  if (cached) return [cached, "engine cache"];
-  if (!allowDownload) {
-    throw new Error(
-      `No '${ENGINE_BINARY_NAME}' ${ENGINE_VERSION} in ATTEST_ENGINE_PATH, PATH or ~/.attest/bin/${ENGINE_VERSION}/.`
-    );
-  }
-  const noDownload = process.env["ATTEST_ENGINE_NO_DOWNLOAD"]?.toLowerCase();
-  if (noDownload === "1" || noDownload === "true" || noDownload === "yes") {
-    throw new Error(
-      `Cannot find '${ENGINE_BINARY_NAME}' ${ENGINE_VERSION} and ATTEST_ENGINE_NO_DOWNLOAD is set.
-Install options:
-  1. Build from source: make engine, then set ATTEST_ENGINE_PATH
-  2. Download release v${ENGINE_VERSION}: https://github.com/attest-framework/attest/releases
-  3. Allow auto-download by unsetting ATTEST_ENGINE_NO_DOWNLOAD`
-    );
-  }
-  return [await downloadEngine(), "download"];
-}
-async function resolveEngine(explicitPath, options2 = {}) {
-  const [enginePath, source] = await locateEngine(explicitPath, options2.allowDownload ?? true);
-  const found = engineVersion(enginePath);
-  if (found !== ENGINE_VERSION) {
-    throw new EngineVersionMismatchError(enginePath, source, found, ENGINE_VERSION);
-  }
-  return enginePath;
-}
-var EngineManager = class {
-  enginePath;
-  logLevel;
-  process = null;
-  reader = null;
-  initialized = false;
-  requestId = 0;
-  initResult = null;
-  constructor(options2) {
-    this.enginePath = options2?.enginePath ?? "";
-    this.logLevel = options2?.logLevel ?? "warn";
-  }
-  async start() {
-    this.enginePath = await resolveEngine(this.enginePath || void 0);
-    this.process = spawn(this.enginePath, [`--log-level=${this.logLevel}`], {
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    this.reader = createInterface({ input: this.process.stdout });
-    try {
-      this.initResult = await this.initialize();
-    } catch (err) {
-      await this.stop();
-      throw err;
-    }
-    this.initialized = true;
-    return this.initResult;
-  }
-  /** Send initialize and check the engine's version and capabilities. */
-  async initialize() {
-    const init = await this.sendRequestInternal("initialize", {
-      sdk_name: "attest-typescript",
-      sdk_version: VERSION,
-      protocol_version: 1,
-      required_capabilities: ["layers_1_4"],
-      preferred_encoding: "json"
-    });
-    if (init.engine_version !== ENGINE_VERSION) {
-      throw new EngineVersionMismatchError(
-        this.enginePath,
-        "initialize",
-        init.engine_version,
-        ENGINE_VERSION
-      );
-    }
-    if (!init.compatible) {
-      throw new Error(`Engine incompatible. Missing capabilities: ${JSON.stringify(init.missing)}`);
-    }
-    return init;
-  }
-  async stop() {
-    if (this.process === null) return;
-    if (this.initialized) {
-      try {
-        await this.sendRequestInternal("shutdown", {});
-      } catch {
-      }
-    }
-    if (this.reader) {
-      this.reader.close();
-      this.reader = null;
-    }
-    if (this.process.exitCode === null) {
-      this.process.kill("SIGTERM");
-      await new Promise((res) => {
-        const timer = setTimeout(() => {
-          this.process?.kill("SIGKILL");
-        }, 5e3);
-        this.process.on("exit", () => {
-          clearTimeout(timer);
-          res();
-        });
-      });
-    }
-    this.initialized = false;
-    this.process = null;
-  }
-  async sendRequest(method, params) {
-    if (!this.initialized && method !== "initialize") {
-      throw new Error("Engine not initialized. Call start() first.");
-    }
-    return this.sendRequestInternal(method, params);
-  }
-  async sendRequestInternal(method, params) {
-    if (this.process === null || this.process.stdin === null || this.reader === null) {
-      throw new Error("Engine process not started.");
-    }
-    this.requestId += 1;
-    const requestStr = encodeRequest(this.requestId, method, params);
-    return new Promise((resolve5, reject) => {
-      const onLine = (line) => {
-        try {
-          const response = decodeResponse(line);
-          resolve5(extractResult(response));
-        } catch (err) {
-          reject(err);
-        }
-      };
-      this.reader.once("line", onLine);
-      const ok = this.process.stdin.write(requestStr, (err) => {
-        if (err) {
-          this.reader.removeListener("line", onLine);
-          reject(err);
-        }
-      });
-      if (!ok) {
-        this.process.stdin.once("drain", () => {
-        });
-      }
-    });
-  }
-  get isRunning() {
-    return this.process !== null && this.process.exitCode === null;
-  }
-  /** Expose process for AttestClient reader loop access */
-  get childProcess() {
-    return this.process;
-  }
-  /** Expose readline interface for AttestClient reader loop */
-  get readlineInterface() {
-    return this.reader;
-  }
-};
-
-// src/config.ts
-var _simulationMode = false;
-var _sampleRate = 0;
-function config(options2) {
-  if (options2.simulation !== void 0) {
-    _simulationMode = options2.simulation;
-  }
-  if (options2.sampleRate !== void 0) {
-    if (options2.sampleRate < 0 || options2.sampleRate > 1) {
-      throw new RangeError(
-        `sampleRate must be between 0.0 and 1.0, got ${options2.sampleRate}`
-      );
-    }
-    _sampleRate = options2.sampleRate;
-  }
-}
-function isSimulationMode() {
-  return _simulationMode || simulationEnvEnabled();
-}
-function simulationEnvEnabled() {
-  const env = (process.env["ATTEST_SIMULATION"] ?? "").trim().toLowerCase();
-  return env === "1" || env === "true" || env === "yes";
-}
-function getSampleRate() {
-  if (_sampleRate > 0) return _sampleRate;
-  const env = process.env["ATTEST_SAMPLE_RATE"];
-  if (env !== void 0 && env !== "") {
-    const parsed = Number(env);
-    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
-      throw new RangeError(
-        `ATTEST_SAMPLE_RATE must be between 0.0 and 1.0, got '${env}'`
-      );
-    }
-    return parsed;
+  const suffix = `${String(process.pid)}.${crypto.randomBytes(8).toString("hex")}`;
+  const tmpPath = path.join(dir, `.${binaryFilename()}.tmp.${suffix}`);
+  try {
+    fs.writeFileSync(tmpPath, data, { flag: "wx", mode: 493 });
+    fs.chmodSync(tmpPath, 493);
+    fs.renameSync(tmpPath, destPath);
+  } catch (err) {
+    if (err.code !== "EEXIST") fs.rmSync(tmpPath, { force: true });
+    throw err;
   }
-  return 0;
-}
-function resetConfig() {
-  _simulationMode = false;
-  _sampleRate = 0;
+  process.stderr.write(`[attest] Engine installed at ${destPath}
+`);
+  return destPath;
 }
 
-// src/usage.ts
-var INT_FIELDS = [
-  "model_calls",
-  "judge_calls",
-  "input_tokens",
-  "output_tokens",
-  "cached_tokens",
-  "unpriced_calls",
-  "budget_refused"
-];
-var USD_FIELDS = ["cost_usd", "retry_cost_usd"];
-function zeroUsage() {
-  return {
-    model_calls: 0,
-    judge_calls: 0,
-    input_tokens: 0,
-    output_tokens: 0,
-    cached_tokens: 0,
-    cost_usd: 0,
-    retry_cost_usd: 0,
-    unpriced_calls: 0,
-    budget_refused: 0
-  };
-}
-function addUsage(a, b) {
-  return {
-    model_calls: a.model_calls + b.model_calls,
-    judge_calls: a.judge_calls + b.judge_calls,
-    input_tokens: a.input_tokens + b.input_tokens,
-    output_tokens: a.output_tokens + b.output_tokens,
-    cached_tokens: a.cached_tokens + b.cached_tokens,
-    cost_usd: a.cost_usd + b.cost_usd,
-    retry_cost_usd: a.retry_cost_usd + b.retry_cost_usd,
-    unpriced_calls: a.unpriced_calls + b.unpriced_calls,
-    budget_refused: a.budget_refused + b.budget_refused
-  };
-}
-function sumUsage(usages) {
-  let total = zeroUsage();
-  for (const u of usages) total = addUsage(total, u);
-  return total;
+// src/engine-manager.ts
+var ENGINE_BINARY_NAME = "attest-engine";
+var VERSION_PROBE_TIMEOUT_MS = 1e4;
+var DEFAULT_INITIALIZE_TIMEOUT_MS = 3e4;
+var SHUTDOWN_TIMEOUT_MS = 5e3;
+var STDERR_TAIL_BYTES = 4096;
+var EXIT_REPORT_GRACE_MS = 1e3;
+var PIPE_WRITE_ERROR_CODES = /* @__PURE__ */ new Set(["EPIPE", "ECONNRESET", "ERR_STREAM_DESTROYED"]);
+function isPipeWriteError(err) {
+  for (let e = err; e instanceof Error; e = e.cause) {
+    const code = e.code;
+    if (code !== void 0 && PIPE_WRITE_ERROR_CODES.has(code)) return true;
+  }
+  return false;
 }
-function parseUsage(raw) {
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    throw new TypeError(`evaluate_batch result: usage must be an object, got ${JSON.stringify(raw)}`);
+var EngineVersionMismatchError = class extends Error {
+  enginePath;
+  source;
+  found;
+  required;
+  constructor(enginePath, source, found, required) {
+    const reported = found === null ? "reports no version" : `reports version ${found}`;
+    super(
+      `attest-engine at ${enginePath} (from ${source}) ${reported}; this SDK requires attest-engine ${required}. Point ATTEST_ENGINE_PATH at a matching engine, or remove the mismatched one from PATH so the SDK can download ${required} into ~/.attest/bin/${required}/.`
+    );
+    this.name = "EngineVersionMismatchError";
+    this.enginePath = enginePath;
+    this.source = source;
+    this.found = found;
+    this.required = required;
   }
-  const obj = raw;
-  const field = (name, integer) => {
-    const v = obj[name];
-    if (typeof v !== "number" || !Number.isFinite(v) || v < 0 || integer && !Number.isInteger(v)) {
-      const kind = integer ? "a non-negative integer" : "a non-negative number";
-      throw new TypeError(`evaluate_batch result: usage.${name} must be ${kind}, got ${JSON.stringify(v)}`);
-    }
-    return v;
-  };
-  const ints = Object.fromEntries(INT_FIELDS.map((f) => [f, field(f, true)]));
-  const usd = Object.fromEntries(USD_FIELDS.map((f) => [f, field(f, false)]));
-  return { ...ints, ...usd };
-}
-function formatUsage(u) {
-  let line = `${u.model_calls} model calls \xB7 ${u.input_tokens + u.output_tokens} tokens (${u.cached_tokens} cached) \xB7 $${u.cost_usd.toFixed(4)} \xB7 retry cost $${u.retry_cost_usd.toFixed(4)}`;
-  if (u.budget_refused > 0) line += ` \xB7 ${u.budget_refused} calls refused by budget`;
-  if (u.unpriced_calls > 0) line += ` \xB7 ${u.unpriced_calls} unpriced calls not in $`;
-  return line;
-}
-function usageSummaryLine(u) {
-  if (u.model_calls === 0 && u.budget_refused === 0) return void 0;
-  return `attest usage: ${formatUsage(u)}`;
+};
+function engineVersion(enginePath) {
+  const proc = spawnSync(enginePath, ["version"], {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+    timeout: VERSION_PROBE_TIMEOUT_MS
+  });
+  if (proc.error) throw proc.error;
+  const out = proc.stdout.trim();
+  const prefix = `${ENGINE_BINARY_NAME} `;
+  if (proc.status !== 0 || !out.startsWith(prefix)) return null;
+  return out.slice(prefix.length).trim();
 }
-
-// src/client.ts
-var DEFAULT_TIMEOUT_MS = 3e4;
-var DEFAULT_DIAGNOSTIC_BUFFER = 32;
-var DEFAULT_DESYNC_THRESHOLD = 3;
-var DEFAULT_DESYNC_WINDOW_MS = 1e3;
-function resolveTimeoutMs(override) {
-  if (override !== void 0) return override;
-  const env = process.env["ATTEST_ENGINE_TIMEOUT"];
-  if (env !== void 0 && env !== "") {
-    const parsed = Number(env);
-    if (!Number.isFinite(parsed) || parsed <= 0) {
-      throw new Error(
-        `ATTEST_ENGINE_TIMEOUT must be a positive number of milliseconds, got: '${env}'`
-      );
+function onPath() {
+  for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join2(dir, binaryFilename());
+    try {
+      accessSync(candidate, fsConstants.X_OK);
+    } catch {
+      continue;
     }
-    return parsed;
+    if (statSync2(candidate).isFile()) return candidate;
   }
-  return DEFAULT_TIMEOUT_MS;
-}
-function makeTimeoutPromise(method, timeoutMs) {
-  return new Promise((_, reject) => {
-    setTimeout(() => {
-      reject(new EngineTimeoutError(method, timeoutMs));
-    }, timeoutMs);
-  });
-}
-function debugProtocolEnabled() {
-  const flag = process.env["ATTEST_DEBUG_PROTOCOL"];
-  return flag === "1" || flag === "true" || flag === "yes";
+  return null;
 }
-function envLoggerDefault() {
-  if (debugProtocolEnabled()) {
-    return {
-      warn: (msg, ...args) => console.warn(msg, ...args),
-      error: (msg, ...args) => console.error(msg, ...args)
-    };
+function requireFile(enginePath, label) {
+  if (!existsSync(enginePath) || !statSync2(enginePath).isFile()) {
+    throw new Error(`${label}=${enginePath} does not exist or is not a file.`);
   }
-  return {
-    warn: () => {
-    },
-    error: () => {
-    }
-  };
 }
-var AttestClient = class {
-  engine;
-  requestId = 0;
-  pending = /* @__PURE__ */ new Map();
-  writeChain = Promise.resolve();
-  readerActive = false;
-  lineHandler = null;
-  logger;
-  diagnosticBuffer;
-  diagnosticListeners = /* @__PURE__ */ new Set();
-  desyncThreshold;
-  desyncWindowMs;
-  desynced = false;
-  constructor(engine, options2) {
-    this.engine = engine;
-    this.logger = options2?.logger ?? envLoggerDefault();
-    this.diagnosticBuffer = new ProtocolDiagnosticBuffer(
-      options2?.diagnosticBufferSize ?? DEFAULT_DIAGNOSTIC_BUFFER
+async function locateEngine(explicitPath, allowDownload) {
+  if (explicitPath) {
+    requireFile(explicitPath, "Engine path");
+    return [explicitPath, "explicit engine path"];
+  }
+  const envPath = process.env["ATTEST_ENGINE_PATH"];
+  if (envPath) {
+    requireFile(envPath, "ATTEST_ENGINE_PATH");
+    return [envPath, "ATTEST_ENGINE_PATH"];
+  }
+  const found = onPath();
+  if (found) return [found, "PATH"];
+  const cached = cachedEnginePath();
+  if (cached) return [cached, "engine cache"];
+  if (!allowDownload) {
+    throw new Error(
+      `No '${ENGINE_BINARY_NAME}' ${ENGINE_VERSION} in ATTEST_ENGINE_PATH, PATH or ~/.attest/bin/${ENGINE_VERSION}/.`
     );
-    this.desyncThreshold = options2?.desyncThreshold ?? DEFAULT_DESYNC_THRESHOLD;
-    this.desyncWindowMs = options2?.desyncWindowMs ?? DEFAULT_DESYNC_WINDOW_MS;
-    if (options2?.onDiagnostic !== void 0) {
-      this.diagnosticListeners.add(options2.onDiagnostic);
-    }
   }
-  /** Subscribe to protocol diagnostics. Returns an unsubscribe function. */
-  onProtocolDiagnostic(listener) {
-    this.diagnosticListeners.add(listener);
-    return () => {
-      this.diagnosticListeners.delete(listener);
-    };
+  const noDownload = process.env["ATTEST_ENGINE_NO_DOWNLOAD"]?.toLowerCase();
+  if (noDownload === "1" || noDownload === "true" || noDownload === "yes") {
+    throw new Error(
+      `Cannot find '${ENGINE_BINARY_NAME}' ${ENGINE_VERSION} and ATTEST_ENGINE_NO_DOWNLOAD is set.
+Install options:
+  1. Build from source: make engine, then set ATTEST_ENGINE_PATH
+  2. Download release v${ENGINE_VERSION}: https://github.com/attest-framework/attest/releases
+  3. Allow auto-download by unsetting ATTEST_ENGINE_NO_DOWNLOAD`
+    );
   }
-  /** Snapshot of the diagnostic ring buffer (most recent last). */
-  protocolDiagnostics() {
-    return this.diagnosticBuffer.snapshot();
+  return [await downloadEngine(), "download"];
+}
+async function resolveEngine(explicitPath, options2 = {}) {
+  const [enginePath, source] = await locateEngine(explicitPath, options2.allowDownload ?? true);
+  const found = engineVersion(enginePath);
+  if (found !== ENGINE_VERSION) {
+    throw new EngineVersionMismatchError(enginePath, source, found, ENGINE_VERSION);
   }
-  startReader() {
-    if (this.readerActive) return;
-    const rl = this.engine.readlineInterface;
-    if (rl === null) {
-      throw new Error("Engine readline interface not available. Call engine.start() first.");
-    }
-    this.readerActive = true;
-    this.lineHandler = (line) => this.handleLine(line);
-    rl.on("line", this.lineHandler);
-    rl.on("close", () => {
-      this.failAll(new Error("Engine closed stdout."));
-      this.readerActive = false;
-    });
+  return enginePath;
+}
+function envNumber(name) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw === "") return null;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+async function reportExit(exited, graceMs) {
+  let timer;
+  const grace = new Promise((done) => {
+    timer = setTimeout(done, graceMs);
+  });
+  try {
+    await Promise.race([exited, grace]);
+  } finally {
+    clearTimeout(timer);
   }
-  stopReader() {
-    if (!this.readerActive) return;
-    const rl = this.engine.readlineInterface;
-    if (rl !== null && this.lineHandler !== null) {
-      rl.removeListener("line", this.lineHandler);
-    }
-    this.lineHandler = null;
-    this.readerActive = false;
+}
+var EngineManager = class {
+  enginePath;
+  logLevel;
+  initializeTimeoutMs;
+  process = null;
+  reader = null;
+  initialized = false;
+  initResult = null;
+  routedClient;
+  /** The running engine's stderr tail; each launch owns a fresh one so a killed engine cannot write into it. */
+  stderr = { text: "" };
+  restarting = null;
+  configuredBudget = { judgeCalls: null, usd: null };
+  usedJudgeCalls = 0;
+  usedUsd = 0;
+  heldJudgeCalls = 0;
+  heldUsd = 0;
+  /** Spend the SDK cannot observe may have happened; a restart then leaves no budget. */
+  unknownSpend = false;
+  constructor(options2) {
+    this.enginePath = options2?.enginePath ?? "";
+    this.logLevel = options2?.logLevel ?? "warn";
+    this.initializeTimeoutMs = options2?.initializeTimeoutMs ?? DEFAULT_INITIALIZE_TIMEOUT_MS;
   }
-  recordDiagnostic(kind, message, rawLine) {
-    const diagnostic = {
-      kind,
-      message,
-      rawLine: previewLine(rawLine),
-      timestampMs: Date.now()
+  /**
+   * Start the engine and complete the `initialize` handshake. Rejects when the engine exits,
+   * closes its pipes or fails to answer within the initialize timeout; the error carries the
+   * tail of the engine's stderr.
+   */
+  async start() {
+    this.enginePath = await resolveEngine(this.enginePath || void 0);
+    this.configuredBudget = {
+      judgeCalls: envNumber("ATTEST_MAX_JUDGE_CALLS"),
+      usd: envNumber("ATTEST_BUDGET_USD")
     };
-    this.diagnosticBuffer.push(diagnostic);
-    this.logger.warn(`[attest.protocol] ${kind}: ${message}`);
-    for (const listener of this.diagnosticListeners) {
-      try {
-        listener(diagnostic);
-      } catch (err) {
-        this.logger.error(
-          `[attest.protocol] diagnostic listener threw: ${err instanceof Error ? err.message : String(err)}`
-        );
-      }
-    }
-    this.maybeTriggerDesync(diagnostic.timestampMs);
-  }
-  maybeTriggerDesync(nowMs) {
-    if (this.desynced) return;
-    const recent = this.diagnosticBuffer.countWithin(this.desyncWindowMs, nowMs);
-    if (recent >= this.desyncThreshold) {
-      this.desynced = true;
-      const snapshot = this.diagnosticBuffer.snapshot();
-      const err = new ProtocolDesyncError(
-        `Engine protocol desync: ${recent} unroutable response lines within ${this.desyncWindowMs}ms.`,
-        snapshot
-      );
-      this.logger.error(`[attest.protocol] ${err.message}`);
-      this.failAll(err);
-    }
+    this.usedJudgeCalls = this.usedUsd = this.heldJudgeCalls = this.heldUsd = 0;
+    this.unknownSpend = false;
+    this.initResult = await this.launch(void 0);
+    this.initialized = true;
+    return this.initResult;
   }
-  handleLine(line) {
-    let response;
-    try {
-      response = decodeResponse(line);
-    } catch (err) {
-      this.handleDecodeFailure(line, err);
-      return;
-    }
-    let reqId;
+  /** Spawn the engine and run `initialize` on it; the engine is stopped when that fails. */
+  async launch(envOverrides) {
+    const stderr = { text: "" };
+    this.stderr = stderr;
+    const child = spawn(this.enginePath, [`--log-level=${this.logLevel}`], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...envOverrides }
+    });
+    this.process = child;
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      stderr.text = (stderr.text + chunk).slice(-STDERR_TAIL_BYTES);
+    });
+    child.stdin.on("error", () => void 0);
+    this.reader = createInterface({ input: child.stdout });
+    const client = new AttestClient(this);
+    this.routedClient = client;
+    client.startReader();
+    const exited = new Promise((_, reject) => {
+      child.once("error", (err) => reject(new Error(`attest-engine failed to start: ${err.message}`)));
+      child.once("close", (code, signal) => {
+        const how = signal !== null ? `signal ${signal}` : `exit code ${String(code)}`;
+        reject(
+          new Error(
+            `attest-engine exited before it was ready (${how}).` + (stderr.text === "" ? "" : ` stderr:
+${stderr.text.trimEnd()}`)
+          )
+        );
+      });
+    });
+    exited.catch(() => void 0);
     try {
-      reqId = extractId(response);
+      return await Promise.race([this.initialize(client), exited]);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.recordDiagnostic("missing_id", message, line);
-      return;
+      await this.terminate();
+      if (isPipeWriteError(err)) await reportExit(exited, EXIT_REPORT_GRACE_MS);
+      throw err;
     }
-    const pending = this.pending.get(reqId);
-    if (pending === void 0) {
-      this.recordDiagnostic(
-        "unknown_id",
-        `no pending request for id=${reqId}`,
-        line
+  }
+  /** Send initialize and check the engine's version and capabilities. */
+  async initialize(client) {
+    const init = await client.sendWithoutRestart(
+      "initialize",
+      {
+        sdk_name: "attest-typescript",
+        sdk_version: VERSION,
+        protocol_version: 1,
+        required_capabilities: ["layers_1_4"],
+        preferred_encoding: "json"
+      },
+      this.initializeTimeoutMs
+    );
+    if (init.engine_version !== ENGINE_VERSION) {
+      throw new EngineVersionMismatchError(
+        this.enginePath,
+        "initialize",
+        init.engine_version,
+        ENGINE_VERSION
       );
-      return;
     }
-    this.pending.delete(reqId);
-    try {
-      const result = extractResult(response);
-      pending.resolve(result);
-    } catch (err) {
-      pending.reject(err);
+    if (!init.compatible) {
+      throw new Error(`Engine incompatible. Missing capabilities: ${JSON.stringify(init.missing)}`);
     }
+    return init;
   }
-  handleDecodeFailure(line, err) {
-    if (err instanceof ProtocolError) {
-      let reqId = -1;
+  async stop() {
+    if (this.restarting !== null) await this.restarting.catch(() => void 0);
+    if (this.process === null) return;
+    if (this.initialized && this.routedClient !== void 0 && this.isRunning) {
       try {
-        const raw = JSON.parse(line.trim());
-        const idCandidate = raw["id"];
-        if (typeof idCandidate === "number" && Number.isFinite(idCandidate)) {
-          reqId = idCandidate;
-        }
+        await this.routedClient.sendWithoutRestart("shutdown", {}, SHUTDOWN_TIMEOUT_MS);
       } catch {
-        reqId = -1;
-      }
-      const pending = this.pending.get(reqId);
-      if (pending !== void 0) {
-        this.pending.delete(reqId);
-        pending.reject(err);
-        return;
       }
-      this.recordDiagnostic(
-        "non_routable_error",
-        `engine error code=${err.code} (${err.errorMessage}) had no matching pending id`,
-        line
-      );
-      return;
     }
-    const message = err instanceof Error ? err.message : String(err);
-    const kind = classifyDecodeError(message);
-    this.recordDiagnostic(kind, message, line);
+    await this.terminate();
+    this.initialized = false;
   }
-  failAll(err) {
-    for (const pending of this.pending.values()) {
-      pending.reject(err);
+  /** Close the pipes, reject pending requests and stop the engine process (SIGKILL when `force`). */
+  async terminate(force = false) {
+    const child = this.process;
+    this.routedClient?.stopReader();
+    this.routedClient?.rejectPending(new Error("Engine stopped."));
+    this.reader?.close();
+    this.reader = null;
+    this.process = null;
+    if (child === null) return;
+    if (child.exitCode === null && child.signalCode === null) {
+      await new Promise((res) => {
+        const timer = force ? void 0 : setTimeout(() => child.kill("SIGKILL"), 5e3);
+        child.once("exit", () => {
+          clearTimeout(timer);
+          res();
+        });
+        child.kill(force ? "SIGKILL" : "SIGTERM");
+      });
     }
-    this.pending.clear();
   }
-  async sendRequest(method, params, timeoutMs) {
-    if (this.desynced) {
-      throw new ProtocolDesyncError(
-        "Engine protocol is desynced; AttestClient will not send further requests.",
-        this.diagnosticBuffer.snapshot()
-      );
+  /**
+   * Replace the engine after a request timed out: its late response can no longer be told
+   * apart from a new one. The new engine gets the remaining session budget: the configured
+   * limit minus the usage already returned, minus what the abandoned requests may still have
+   * reserved. A restart that leaves no budget makes later model calls
+   * `not_evaluated(budget_exhausted)`.
+   */
+  restartAfterTimeout(abandoned) {
+    for (const r of abandoned) {
+      this.heldJudgeCalls += r.judgeCalls ?? Number.POSITIVE_INFINITY;
+      this.heldUsd += r.usd ?? Number.POSITIVE_INFINITY;
     }
-    const resolvedTimeout = resolveTimeoutMs(timeoutMs);
-    if (!this.readerActive) {
-      return Promise.race([
-        this.engine.sendRequest(method, params),
-        makeTimeoutPromise(method, resolvedTimeout)
-      ]);
+    this.restarting ??= this.restart().finally(() => {
+      this.restarting = null;
+    });
+    return this.restarting;
+  }
+  /** An engine reply the SDK cannot account for (no usage, an RPC error, a dropped reply) may have spent budget. */
+  markUnknownSpend() {
+    this.unknownSpend = true;
+  }
+  async restart() {
+    await this.terminate(true);
+    const overrides = {};
+    const { judgeCalls, usd } = this.configuredBudget;
+    const unknown = this.unknownSpend ? Number.POSITIVE_INFINITY : 0;
+    if (judgeCalls !== null) {
+      overrides["ATTEST_MAX_JUDGE_CALLS"] = String(
+        Math.max(0, Math.floor(judgeCalls - this.usedJudgeCalls - this.heldJudgeCalls - unknown))
+      );
     }
-    const cp = this.engine.childProcess;
-    if (cp === null || cp.stdin === null) {
-      throw new Error("Engine process not started.");
+    if (usd !== null) {
+      overrides["ATTEST_BUDGET_USD"] = String(Math.max(0, usd - this.usedUsd - this.heldUsd - unknown));
     }
-    let capturedReqId;
-    const requestPromise = new Promise((resolve5, reject) => {
-      this.writeChain = this.writeChain.then(() => {
-        this.requestId += 1;
-        const reqId = this.requestId;
-        capturedReqId = reqId;
-        this.pending.set(reqId, { resolve: resolve5, reject });
-        const requestStr = encodeRequest(reqId, method, params);
-        cp.stdin.write(requestStr, (err) => {
-          if (err) {
-            this.pending.delete(reqId);
-            reject(err);
-          }
-        });
-      });
-    });
-    const timeoutPromise = makeTimeoutPromise(method, resolvedTimeout);
-    return Promise.race([requestPromise, timeoutPromise]).catch((err) => {
-      if (err instanceof EngineTimeoutError && capturedReqId !== void 0) {
-        this.pending.delete(capturedReqId);
-      }
-      throw err;
-    });
+    this.initResult = await this.launch(overrides);
   }
-  async evaluateBatch(trace, assertions, options2) {
-    if (isSimulationMode()) {
-      requireSimulationCapability(this.engine["initResult"]);
-    }
-    const params = {
-      trace,
-      assertions: [...assertions],
-      ...options2?.budget !== void 0 ? { budget: options2.budget } : {},
-      ...options2?.context !== void 0 ? { context: options2.context } : {}
-    };
-    const raw = await this.sendRequest(
-      "evaluate_batch",
-      params,
-      options2?.timeout
-    );
-    return { ...raw, usage: parseUsage(raw["usage"]) };
+  /** Count the usage an evaluate_batch result reported against the session budget. */
+  recordUsage(usage) {
+    this.usedJudgeCalls += usage.judge_calls;
+    this.usedUsd += usage.cost_usd;
   }
-  async submitPluginResult(traceId2, pluginName, assertionId2, status, score, explanation, options2) {
-    const result = {
-      assertion_id: assertionId2,
-      status,
-      score,
-      explanation,
-      cost: 0,
-      duration_ms: 0
-    };
-    const params = {
-      trace_id: traceId2,
-      plugin_name: pluginName,
-      assertion_id: assertionId2,
-      result
-    };
-    const raw = await this.sendRequest(
-      "submit_plugin_result",
-      params,
-      options2?.timeout
-    );
-    return Boolean(raw?.accepted ?? false);
+  /** Resolves once an engine restart in progress has finished. */
+  async whenReady() {
+    if (this.restarting !== null) await this.restarting;
   }
-  async queryDrift(assertionId2, windowSize = 50, options2) {
-    if (isSimulationMode()) {
-      return {
-        assertion_id: assertionId2,
-        mean: 0,
-        stddev: 0,
-        count: 0,
-        latest_score: 0,
-        deviation: 0,
-        status: "no_data"
-      };
-    }
-    const raw = await this.sendRequest(
-      "query_drift",
-      { assertion_id: assertionId2, window_size: windowSize },
-      options2?.timeout
-    );
-    return raw.report;
+  /** Tail of the engine's stderr: the reason an engine died. */
+  get stderrTail() {
+    return this.stderr.text.trimEnd();
   }
-  async generateUserMessage(persona, conversationHistory, faultConfig, options2) {
-    if (isSimulationMode()) {
-      return `[simulation] Hello from ${persona.name}`;
-    }
-    const params = {
-      persona,
-      conversation_history: conversationHistory
-    };
-    if (faultConfig !== void 0) {
-      params.fault_config = faultConfig;
+  /** The client that routes this engine's responses by id; replaced when the engine restarts. */
+  get client() {
+    return this.routedClient;
+  }
+  async sendRequest(method, params) {
+    if (!this.initialized && method !== "initialize") {
+      throw new Error("Engine not initialized. Call start() first.");
     }
-    const raw = await this.sendRequest(
-      "generate_user_message",
-      params,
-      options2?.timeout
-    );
-    return String(raw.message);
+    if (this.routedClient === void 0) throw new Error("Engine process not started.");
+    return this.routedClient.sendRequest(method, params);
   }
-};
-function classifyDecodeError(message) {
-  if (message.startsWith("malformed JSON")) return "malformed_json";
-  if (message.startsWith("expected JSON object")) return "non_object_response";
-  if (message.startsWith("invalid jsonrpc version")) return "invalid_jsonrpc_version";
-  if (message.startsWith("empty response line")) return "malformed_json";
-  return "malformed_json";
-}
-function requireSimulationCapability(init) {
-  if (init === null || init === void 0) {
-    throw new Error("simulation mode: the engine has not been initialized");
+  get isRunning() {
+    return this.process !== null && this.process.exitCode === null && this.process.signalCode === null;
   }
-  if (!(init.capabilities ?? []).includes("simulation_mode")) {
-    throw new Error(
-      `simulation mode is on but attest-engine ${init.engine_version} was not started in simulation mode (capability 'simulation_mode' missing), so it would call real providers. Set ATTEST_SIMULATION=1 before the engine starts (the Vitest fixtures do this for you) and use attest-engine 1.0 or later.`
-    );
+  /** Expose process for AttestClient reader loop access */
+  get childProcess() {
+    return this.process;
   }
-}
+  /** Expose readline interface for AttestClient reader loop */
+  get readlineInterface() {
+    return this.reader;
+  }
+};
 
 // src/trace.ts
 import { randomUUID } from "crypto";
@@ -2851,11 +3073,14 @@ async function recordExclusive(name, fn, opts) {
     throw new CaptureError(`capture ${name} wrote no fixture (${exitDetail(exit)})`);
   }
   const outcome = JSON.parse(lines[lines.length - 1] ?? "");
-  if (exit.code !== 0 || !outcome.verified) {
+  if (exit.code !== 0 || outcome.outcome === "not_verified") {
     throw new CaptureError(`capture ${name}: fixture ${outcome.fixture} is not verified; no test drafted`, outcome.fixture);
   }
+  if (outcome.outcome === "nothing_to_verify") {
+    return { value, fixture: outcome.fixture, verified: false, outcome: "nothing_to_verify", testFile: null };
+  }
   const testFile = opts.emitTest === false ? null : emitVitest(outcome.fixture);
-  return { value, fixture: outcome.fixture, verified: true, testFile };
+  return { value, fixture: outcome.fixture, verified: true, outcome: "verified", testFile };
 }
 
 // src/replay.ts