@clutor/cli 0.0.0-stage → 0.1.0

package/dist/chunk-6WAEQCCP.js

@@ -0,0 +1,2163 @@
+import {
+  CONFIG_FILE,
+  ConfigError,
+  DEFAULT_PORT,
+  formatGates,
+  formatPlan,
+  formatSimulation,
+  loadConfig,
+  pct,
+  table
+} from "./chunk-U5GHVJJO.js";
+
+// src/args.ts
+function parseArgs(argv, booleans = []) {
+  const flags = /* @__PURE__ */ new Map();
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      const name = eq === -1 ? a.slice(2) : a.slice(2, eq);
+      if (eq !== -1) flags.set(name, a.slice(eq + 1));
+      else if (booleans.includes(name) || i + 1 >= argv.length || argv[i + 1].startsWith("--")) flags.set(name, true);
+      else flags.set(name, argv[++i]);
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+var flagString = (a, name) => {
+  const v = a.flags.get(name);
+  return typeof v === "string" ? v : void 0;
+};
+var flagBool = (a, name) => a.flags.has(name) && a.flags.get(name) !== "false";
+function flagInt(a, name, min, max) {
+  const v = flagString(a, name);
+  if (v === void 0) return void 0;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < min || n > max) throw new UsageError(`--${name} must be an integer from ${min} to ${max}`);
+  return n;
+}
+var UsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+};
+
+// src/decide.ts
+import { createHash } from "crypto";
+import { sealReceipt } from "@clutor/core";
+import { appendReceipt, lastReceiptTag, loadOrCreateReceiptSigner } from "@clutor/core/node";
+var DecideError = class extends Error {
+  constructor(status2, message) {
+    super(message);
+    this.status = status2;
+  }
+  status;
+};
+async function runDecide(e, prompt, choices, f = globalThis.fetch) {
+  if (!prompt || choices.length < 2 || choices.length > 26) throw new DecideError(400, "a prompt and 2 to 26 choices are required");
+  if (new Set(choices).size !== choices.length) throw new DecideError(400, "choices must be different from each other");
+  const letters = choices.map((_, i) => String.fromCharCode(65 + i));
+  const content = `${prompt}
+
+Choose exactly one option and answer with its letter only.
+${choices.map((c, i) => `${letters[i]}) ${c}`).join("\n")}
+Answer:`;
+  const t0 = Date.now();
+  const res = await f(`${e.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...e.apiKey ? { authorization: `Bearer ${e.apiKey}` } : {} },
+    body: JSON.stringify({ model: e.model, messages: [{ role: "user", content }], max_tokens: 1, temperature: 0, logprobs: true, top_logprobs: 20 })
+  });
+  if (!res.ok) throw new DecideError(502, `the model server answered ${res.status}: ${(await res.text().catch(() => "")).slice(0, 300)}`);
+  const body = await res.json();
+  const top = body.choices?.[0]?.logprobs?.content?.[0]?.top_logprobs;
+  if (!top) throw new DecideError(502, "the model server returned no log-probabilities; decide needs a server that supports logprobs (llama-server does)");
+  const mass = letters.map((l) => top.filter((t) => t.token.trim() === l).reduce((a, t) => a + Math.exp(t.logprob), 0));
+  const total = mass.reduce((a, b) => a + b, 0);
+  if (total === 0) throw new DecideError(502, "the model did not put any probability on the choice letters; try rephrasing the prompt");
+  const probs = mass.map((m) => m / total);
+  const best = probs.indexOf(Math.max(...probs));
+  return { choice: choices[best], probabilities: Object.fromEntries(choices.map((c, i) => [c, probs[i]])), probabilityMassOnChoices: total, latencyMs: Date.now() - t0 };
+}
+async function sealDecision(root, model, prompt, choices, r, startedAt) {
+  const signer = await loadOrCreateReceiptSigner(root);
+  const promptSha = createHash("sha256").update(prompt).digest("hex");
+  const receipt = await sealReceipt(signer, {
+    v: 2,
+    id: `dec_${Date.now().toString(36)}`,
+    task: `decide sha256:${promptSha} among [${choices.join("|")}] -> ${r.choice}`,
+    model,
+    startedAt,
+    finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    status: "finished",
+    files: [],
+    commands: [],
+    steps: 1,
+    previous: await lastReceiptTag(root)
+  });
+  await appendReceipt(root, receipt);
+  return receipt;
+}
+
+// src/backend.ts
+import { spawn } from "child_process";
+import { accessSync, constants } from "fs";
+import { homedir } from "os";
+import { delimiter, join } from "path";
+import { createHash as createHash2 } from "crypto";
+import { TASK_MARKER } from "@clutor/core";
+var exe = process.platform === "win32" ? "llama-server.exe" : "llama-server";
+function findLlamaServer(env = process.env, extraDirs = []) {
+  const dirs = [...extraDirs, ...(env["PATH"] ?? "").split(delimiter), "/opt/homebrew/bin", "/usr/local/bin", join(homedir(), ".clutor", "bin")];
+  for (const d of dirs) {
+    if (!d) continue;
+    const p = join(d, exe);
+    try {
+      accessSync(p, constants.X_OK);
+      return p;
+    } catch {
+    }
+  }
+  return null;
+}
+function probeLlamaServer(binary, timeoutMs = 15e3) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn(binary, ["--help"], { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error(`${binary} --help did not finish in ${timeoutMs / 1e3}s`));
+    }, timeoutMs);
+    child.stdout?.on("data", (b) => out += b.toString());
+    child.stderr?.on("data", (b) => out += b.toString());
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+    child.on("close", () => {
+      clearTimeout(timer);
+      resolve3({ flags: new Set(out.match(/--[a-z0-9][a-z0-9-]*/g) ?? []), flashAttnTakesValue: /--flash-attn[^\n]*\[on\|off\|auto\]|--flash-attn\s+\[?on/.test(out), helpText: out });
+    });
+  });
+}
+function buildLlamaArgs(i) {
+  const notes = [];
+  const args = ["-m", i.modelPath, "--host", "127.0.0.1", "--port", String(i.port), "-c", String(i.contextTokens)];
+  if (i.threads) args.push("-t", String(i.threads));
+  if (i.caps.flags.has("--jinja")) args.push("--jinja");
+  else notes.push('this llama-server has no --jinja, so native tool calling may not work; use agent.toolMode "json"');
+  if (i.kvBits < 16) {
+    const t = i.kvBits === 8 ? "q8_0" : "q4_0";
+    if (i.caps.flags.has("--cache-type-k") && i.caps.flags.has("--cache-type-v")) {
+      args.push("--cache-type-k", t, "--cache-type-v", t);
+      if (i.caps.flags.has("--flash-attn")) args.push(...i.caps.flashAttnTakesValue ? ["--flash-attn", "on"] : ["--flash-attn"]);
+      else notes.push("quantised KV cache needs flash attention, which this build lacks; the server may refuse to start");
+    } else notes.push("this llama-server cannot quantise the KV cache; the plan's KV size is too small");
+  }
+  if (i.plan?.strategy === "fully-resident" && i.caps.flags.has("--mlock")) args.push("--mlock");
+  if (i.plan && i.plan.strategy !== "fully-resident") notes.push("the model is larger than the memory budget, so it will be paged in from disk by the operating system (mmap): speed depends on your SSD and on how often the same experts are reused");
+  if (i.slotSavePath) {
+    if (i.caps.flags.has("--slot-save-path")) args.push("--slot-save-path", i.slotSavePath);
+    else notes.push("this llama-server has no --slot-save-path, so the project prefix cannot be saved between runs");
+  }
+  args.push(...i.extraArgs ?? []);
+  return { args, notes };
+}
+var BackendManager = class {
+  constructor(port, fetchFn = globalThis.fetch) {
+    this.port = port;
+    this.fetchFn = fetchFn;
+  }
+  port;
+  fetchFn;
+  state = "stopped";
+  error = null;
+  child = null;
+  log = [];
+  listeners = /* @__PURE__ */ new Set();
+  get baseUrl() {
+    return `http://127.0.0.1:${this.port}/v1`;
+  }
+  get recentLog() {
+    return this.log.slice(-200);
+  }
+  onState(f) {
+    this.listeners.add(f);
+    return () => this.listeners.delete(f);
+  }
+  set(s, err) {
+    this.state = s;
+    this.error = err ?? null;
+    for (const l of this.listeners) l(s);
+  }
+  async start(binary, args, opts = {}) {
+    if (this.child) throw new Error("the backend is already running");
+    this.log.length = 0;
+    this.set("starting");
+    const child = spawn(binary, args, { stdio: ["ignore", "pipe", "pipe"], env: opts.env ?? process.env });
+    this.child = child;
+    const take = (b) => {
+      for (const l of b.toString().split("\n")) if (l.trim()) {
+        this.log.push(l);
+        if (this.log.length > 1e3) this.log.shift();
+      }
+    };
+    child.stdout?.on("data", take);
+    child.stderr?.on("data", take);
+    child.on("error", (e) => {
+      this.child = null;
+      this.set("failed", `could not start ${binary}: ${e.message}`);
+    });
+    child.on("exit", (code2, sig) => {
+      this.child = null;
+      if (this.state !== "stopped") this.set("failed", `llama-server exited (${sig ?? `code ${code2}`}); last output: ${this.log.slice(-3).join(" | ")}`);
+    });
+    const deadline = Date.now() + (opts.readyTimeoutMs ?? 6e5);
+    while (Date.now() < deadline) {
+      if (this.state === "failed") throw new Error(this.error ?? "the backend failed to start");
+      try {
+        const r = await this.fetchFn(`http://127.0.0.1:${this.port}/health`);
+        if (r.ok) {
+          this.set("ready");
+          return;
+        }
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, 250));
+    }
+    await this.stop();
+    this.set("failed", "the model did not finish loading in time");
+    throw new Error(this.error ?? "timeout");
+  }
+  async stop() {
+    const c = this.child;
+    this.set("stopped");
+    if (!c) return;
+    await new Promise((resolve3) => {
+      const kill = setTimeout(() => c.kill("SIGKILL"), 5e3);
+      c.once("exit", () => {
+        clearTimeout(kill);
+        resolve3();
+      });
+      c.kill("SIGTERM");
+    });
+    this.child = null;
+  }
+};
+var SlotSnapshots = class {
+  constructor(baseUrl, slot = 0, fetchFn = globalThis.fetch) {
+    this.baseUrl = baseUrl;
+    this.slot = slot;
+    this.fetchFn = fetchFn;
+  }
+  baseUrl;
+  slot;
+  fetchFn;
+  stats = { restored: 0, saved: 0, restoreMisses: 0, failures: 0 };
+  url(action) {
+    return `${this.baseUrl.replace(/\/v1\/?$/, "")}/slots/${this.slot}?action=${action}`;
+  }
+  async post(action, filename) {
+    try {
+      return await this.fetchFn(this.url(action), { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ filename }), signal: AbortSignal.timeout(6e4) });
+    } catch {
+      this.stats.failures++;
+      return void 0;
+    }
+  }
+  async restore(name) {
+    const r = await this.post("restore", `${name}.bin`);
+    if (r?.ok) {
+      this.stats.restored++;
+      return true;
+    }
+    if (r) {
+      r.body?.cancel().catch(() => void 0);
+      this.stats.restoreMisses++;
+    }
+    return false;
+  }
+  async save(name) {
+    const r = await this.post("save", `${name}.bin`);
+    if (r?.ok) {
+      this.stats.saved++;
+      return true;
+    }
+    if (r) {
+      this.stats.failures++;
+      r.body?.cancel().catch(() => void 0);
+    }
+    return false;
+  }
+};
+function withPrefixSnapshots(inner, snaps) {
+  let done = false;
+  const wrapped = {
+    snapshots: snaps,
+    model: inner.model,
+    toolMode: inner.toolMode,
+    async chat(messages, opts) {
+      if (done) return inner.chat(messages, opts);
+      done = true;
+      const head = messages.map((m) => m.content ?? "").join("\n\n");
+      const cut = head.lastIndexOf(TASK_MARKER);
+      const prefix = cut >= 0 ? head.slice(0, cut) : head;
+      const key = `clt-${createHash2("sha256").update(inner.model).update("\0").update(prefix).digest("hex").slice(0, 32)}`;
+      const had = await snaps.restore(key);
+      const out = await inner.chat(messages, opts);
+      if (!had) await snaps.save(key);
+      return out;
+    }
+  };
+  return wrapped;
+}
+
+// src/models.ts
+import { createWriteStream } from "fs";
+import { mkdir, readdir, rename, rm, stat, statfs } from "fs/promises";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+import { basename, extname, isAbsolute, join as join2, resolve, sep } from "path";
+import { CATALOG, QUANTS, approximateLayout, buildModelLayout, parseGguf } from "@clutor/core";
+import { fileReader } from "@clutor/core/node";
+var ModelError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ModelError";
+  }
+};
+async function resolveModel(ref, opts = {}) {
+  const [idPart, quantPart] = ref.split("@");
+  const spec = CATALOG.find((s) => s.id === idPart);
+  if (spec && !ref.toLowerCase().endsWith(".gguf")) {
+    const quant = quantPart ?? "Q4_K_M";
+    const bpw = QUANTS[quant];
+    if (bpw === void 0) throw new ModelError(`unknown quantisation "${quant}"; choose one of ${Object.keys(QUANTS).join(", ")}`);
+    return { id: `${spec.id}@${quant}`, name: spec.name, source: "catalog", layout: approximateLayout(spec, bpw), quant };
+  }
+  if (!ref.toLowerCase().endsWith(".gguf")) throw new ModelError(`unknown model "${ref}"; use one of ${CATALOG.map((s) => s.id).join(", ")}, or the path of a .gguf file`);
+  if (opts.allowFiles === false) throw new ModelError("reading a model file needs the access token");
+  const path = isAbsolute(ref) ? ref : resolve(opts.modelsDir ?? ".", ref);
+  try {
+    await stat(path);
+  } catch {
+    throw new ModelError(`${path} does not exist`);
+  }
+  const r = await fileReader(path);
+  try {
+    const gguf = await parseGguf(r);
+    const layout = buildModelLayout(gguf);
+    const dominant = Object.entries(layout.quantisations).sort((a, b) => b[1] - a[1])[0]?.[0];
+    return { id: basename(path), name: layout.name || basename(path), source: "file", path, layout, gguf, ...dominant ? { quant: dominant } : {} };
+  } finally {
+    await r.close();
+  }
+}
+async function listLocalModels(dir) {
+  const out = [];
+  const walk = async (d, depth) => {
+    let entries;
+    try {
+      entries = await readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = join2(d, e.name);
+      if (e.isDirectory() && depth < 3) await walk(p, depth + 1);
+      else if (e.isFile() && extname(e.name).toLowerCase() === ".gguf") out.push({ file: p.slice(resolve(dir).length + 1).split(sep).join("/"), path: p, bytes: (await stat(p)).size });
+    }
+  };
+  await walk(resolve(dir), 0);
+  return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+var GiB_ = 2 ** 30;
+var DOWNLOADS = [
+  { id: "olmoe-1b-7b-q4_k_m", catalogId: "olmoe-1b-7b", repo: "bartowski/OLMoE-1B-7B-0924-Instruct-GGUF", file: "OLMoE-1B-7B-0924-Instruct-Q4_K_M.gguf", bytes: Math.round(3.92 * GiB_), note: "a real mixture-of-experts model (64 experts, 8 used): the one to test expert streaming with" },
+  { id: "qwen2.5-coder-7b-q4_k_m", catalogId: "qwen2.5-coder-7b", repo: "Qwen/Qwen2.5-Coder-7B-Instruct-GGUF", file: "qwen2.5-coder-7b-instruct-q4_k_m.gguf", bytes: Math.round(4.36 * GiB_), note: "a dense coding model for the agent (not a mixture of experts)" }
+];
+var downloadUrl = (d) => `https://huggingface.co/${d.repo}/resolve/main/${d.file}`;
+var DownloadError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DownloadError";
+  }
+};
+async function downloadFile(url, dest, opts = {}) {
+  const f = opts.fetch ?? globalThis.fetch;
+  await mkdir(resolve(dest, ".."), { recursive: true });
+  const res = await f(url, { redirect: "follow" });
+  if (!res.ok || !res.body) throw new DownloadError(`the server answered ${res.status} for ${url}`);
+  const total = Number(res.headers.get("content-length") ?? 0);
+  if (!total) throw new DownloadError("the server did not say how large the file is, so it cannot be checked");
+  if (opts.expectedBytes && Math.abs(total - opts.expectedBytes) / opts.expectedBytes > 0.05) throw new DownloadError(`expected about ${opts.expectedBytes} bytes but the server offers ${total}; not downloading`);
+  const fs = await statfs(resolve(dest, ".."));
+  const free = Number(fs.bavail) * Number(fs.bsize);
+  if (free < total * 1.1) throw new DownloadError(`not enough free disk: need ${(total / GiB_).toFixed(2)} GiB, have ${(free / GiB_).toFixed(2)} GiB`);
+  const part = `${dest}.part`;
+  let done = 0;
+  const body = Readable.fromWeb(res.body);
+  body.on("data", (c) => {
+    done += c.length;
+    opts.onProgress?.(done, total);
+  });
+  try {
+    await pipeline(body, createWriteStream(part));
+    if (done !== total) throw new DownloadError(`the download stopped at ${done} of ${total} bytes`);
+    await rename(part, dest);
+  } catch (e) {
+    await rm(part, { force: true });
+    throw e;
+  }
+  return total;
+}
+
+// src/sse.ts
+async function* parseSse(body) {
+  const reader = body.getReader();
+  const dec = new TextDecoder();
+  let buf = "";
+  try {
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let i;
+      while ((i = buf.search(/\r?\n\r?\n/)) >= 0) {
+        const block = buf.slice(0, i);
+        buf = buf.slice(i).replace(/^\r?\n\r?\n/, "");
+        const data = block.split(/\r?\n/).filter((l) => l.startsWith("data:")).map((l) => l.slice(5).replace(/^ /, "")).join("\n");
+        if (data) yield data;
+      }
+    }
+    const rest = buf.split(/\r?\n/).filter((l) => l.startsWith("data:")).map((l) => l.slice(5).replace(/^ /, "")).join("\n");
+    if (rest) yield rest;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/ollama.ts
+function toOpenAiBody(req, model, kind) {
+  const messages = kind === "generate" ? [...req.system ? [{ role: "system", content: req.system }] : [], { role: "user", content: req.prompt ?? "" }] : req.messages ?? [];
+  const o = req.options ?? {};
+  return {
+    model,
+    messages,
+    stream: req.stream !== false,
+    ...o.temperature !== void 0 ? { temperature: o.temperature } : {},
+    ...o.top_p !== void 0 ? { top_p: o.top_p } : {},
+    ...o.num_predict !== void 0 && o.num_predict > 0 ? { max_tokens: o.num_predict } : {},
+    ...o.stop ? { stop: o.stop } : {}
+  };
+}
+var now = () => (/* @__PURE__ */ new Date()).toISOString();
+var piece = (kind, model, text, done, extra = {}) => kind === "chat" ? { model, created_at: now(), message: { role: "assistant", content: text }, done, ...extra } : { model, created_at: now(), response: text, done, ...extra };
+function fromOpenAiReply(kind, model, body) {
+  const text = body.choices?.[0]?.message?.content ?? "";
+  return piece(kind, model, text, true, { done_reason: body.choices?.[0]?.finish_reason ?? "stop", prompt_eval_count: body.usage?.prompt_tokens ?? 0, eval_count: body.usage?.completion_tokens ?? 0 });
+}
+async function* streamToOllama(kind, model, body) {
+  let usage;
+  let reason = "stop";
+  for await (const data of parseSse(body)) {
+    if (data.trim() === "[DONE]") break;
+    let j;
+    try {
+      j = JSON.parse(data);
+    } catch {
+      continue;
+    }
+    if (j.usage) usage = j.usage;
+    const c = j.choices?.[0];
+    if (c?.finish_reason) reason = c.finish_reason;
+    const text = c?.delta?.content;
+    if (text) yield `${JSON.stringify(piece(kind, model, text, false))}
+`;
+  }
+  yield `${JSON.stringify(piece(kind, model, "", true, { done_reason: reason, prompt_eval_count: usage?.prompt_tokens ?? 0, eval_count: usage?.completion_tokens ?? 0 }))}
+`;
+}
+
+// src/agentllm.ts
+import { mkdirSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join3 } from "path";
+import { OpenAiCompatibleClient, toolCallJsonSchema } from "@clutor/core";
+var slotDir = () => join3(homedir2(), ".clutor", "slots");
+function ensureSlotDir() {
+  const dir = slotDir();
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  return dir;
+}
+function agentLlm(config, ep, fetchFn) {
+  const json = config.agent.toolMode === "json";
+  const client = new OpenAiCompatibleClient({
+    baseUrl: ep.baseUrl,
+    model: ep.model,
+    ...ep.apiKey ? { apiKey: ep.apiKey } : {},
+    toolMode: config.agent.toolMode,
+    ...json && config.agent.constrainToolCalls ? { jsonSchema: toolCallJsonSchema() } : {},
+    ...ep.local ? { slot: 0 } : {},
+    ...fetchFn ? { fetch: fetchFn } : {}
+  });
+  if (ep.local && config.agent.prefixSnapshots) return withPrefixSnapshots(client, new SlotSnapshots(ep.baseUrl, 0, fetchFn));
+  return client;
+}
+
+// src/mcp.ts
+import { CATALOG as CATALOG2, GiB, QUANTS as QUANTS2, ShadowWorkspace, buildRepoMap, fmtGiB, planMemory, TOOLS, executeTool, validateToolCall } from "@clutor/core";
+import { NodeProject, hostInfo } from "@clutor/core/node";
+var READ_TOOLS = ["list_files", "read_file", "search", "repo_map"];
+function tools() {
+  const fromAgent = TOOLS.filter((t) => READ_TOOLS.includes(t.name)).map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: { dir: { type: "string", description: "Project folder (must be one Clutor has been given access to)." }, ...Object.fromEntries(Object.entries(t.fields).filter(([k]) => !(t.name === "list_files" && k === "dir") && !(t.name === "search" && k === "dir")).map(([k, f]) => [k, { type: f.type, description: f.description }])), ...t.name === "list_files" || t.name === "search" ? { subdir: { type: "string", description: "Only look under this folder." } } : {} },
+      required: ["dir", ...Object.entries(t.fields).filter(([, f]) => f.required).map(([k]) => k)]
+    }
+  }));
+  return [
+    ...fromAgent,
+    { name: "plan_memory", description: "Would a model fit in this much RAM, and how fast could it possibly run from disk? Models: " + CATALOG2.map((c) => c.id).join(", "), inputSchema: { type: "object", additionalProperties: false, properties: { model: { type: "string" }, ram_gib: { type: "number" }, quant: { type: "string", enum: Object.keys(QUANTS2) }, context_tokens: { type: "integer" } }, required: ["model", "ram_gib"] } }
+  ];
+}
+async function handleMcp(req, ctx) {
+  const id = req.id ?? null;
+  const ok = (result) => ({ status: 200, body: { jsonrpc: "2.0", id, result } });
+  const err = (code2, message) => ({ status: 200, body: { jsonrpc: "2.0", id, error: { code: code2, message } } });
+  if (req.jsonrpc !== "2.0" || typeof req.method !== "string") return err(-32600, "not a JSON-RPC 2.0 request");
+  switch (req.method) {
+    case "initialize":
+      return ok({ protocolVersion: "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "clutor", version: "0.1.0" } });
+    case "notifications/initialized":
+      return { status: 202, body: "" };
+    case "ping":
+      return ok({});
+    case "tools/list":
+      return ok({ tools: tools() });
+    case "tools/call": {
+      const name = req.params?.["name"], args = req.params?.["arguments"] ?? {};
+      const text = (t, isError = false) => ok({ content: [{ type: "text", text: t }], isError });
+      if (name === "plan_memory") {
+        try {
+          const m = await resolveModel(`${String(args["model"])}${args["quant"] ? `@${String(args["quant"])}` : ""}`, { allowFiles: false });
+          const h = hostInfo();
+          const p = planMemory(m.layout, { hostRamBytes: Math.max(1, Number(args["ram_gib"])) * GiB, ...args["context_tokens"] ? { contextTokens: Number(args["context_tokens"]) } : {} });
+          return text([`${m.name} (${m.quant}) on ${fmtGiB(p.ceilingBytes)}: ${p.strategy}`, ...p.components.map((c) => `- ${c.label}: ${fmtGiB(c.bytes)}`), ...p.speed.map((s) => `at ${(s.hitRate * 100).toFixed(0)}% cache hits: at most ${s.maxTokensPerSec === Infinity ? "unlimited" : s.maxTokensPerSec.toFixed(2)} tokens/s (disk bound)`), ...p.warnings.map((w) => `! ${w}`), `(this machine has ${fmtGiB(h.totalRamBytes)})`].join("\n"));
+        } catch (e) {
+          return text(e instanceof Error ? e.message : String(e), true);
+        }
+      }
+      if (typeof name === "string" && READ_TOOLS.includes(name)) {
+        const dir = typeof args["dir"] === "string" ? await ctx.isRoot(args["dir"]) : null;
+        if (!dir) return text("that folder has not been opened in Clutor; open it in the app or run `clutor serve --dir <folder>`", true);
+        const { dir: _d, subdir, ...rest } = args;
+        void _d;
+        const call = name === "list_files" || name === "search" ? { ...rest, ...typeof subdir === "string" ? { dir: subdir } : {} } : rest;
+        const v = validateToolCall(name, call);
+        if (!v.ok) return text(v.error, true);
+        const r = await executeTool({ ws: new ShadowWorkspace(new NodeProject(dir)) }, v.call.name, v.call.args);
+        return text(r.output, !r.ok);
+      }
+      return err(-32602, `unknown tool ${JSON.stringify(name)}`);
+    }
+    default:
+      return err(-32601, `method not found: ${req.method}`);
+  }
+}
+
+// src/sessions.ts
+import { randomBytes } from "crypto";
+import { realpath, stat as stat2 } from "fs/promises";
+import { join as join4 } from "path";
+import { evaluateGates, runAgent } from "@clutor/core";
+import { ConflictError, appendReceipt as appendReceipt2, applyChanges, lastReceiptTag as lastReceiptTag2, loadOrCreateReceiptSigner as loadOrCreateReceiptSigner2, rollbackCheckpoint, scratchRunner, verifyReceiptLog } from "@clutor/core/node";
+var AgentSession = class {
+  constructor(dir, task, project, ws, cfg, hostRamBytes) {
+    this.dir = dir;
+    this.task = task;
+    this.project = project;
+    this.ws = ws;
+    this.cfg = cfg;
+    this.hostRamBytes = hostRamBytes;
+  }
+  dir;
+  task;
+  project;
+  ws;
+  cfg;
+  hostRamBytes;
+  id = `task_${randomBytes(6).toString("hex")}`;
+  events = [];
+  startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  status = "running";
+  result;
+  checkpointId;
+  subs = /* @__PURE__ */ new Set();
+  pending = /* @__PURE__ */ new Map();
+  abort = new AbortController();
+  lastDiffs = [];
+  done = Promise.resolve();
+  push(e) {
+    this.events.push(e);
+    if (e.type === "diff") this.lastDiffs = e.diffs;
+    for (const s of this.subs) s(e);
+  }
+  /** Replays everything so far, then streams new events until the task ends. Returns a function that stops listening. */
+  subscribe(from, send, onEnd) {
+    for (const e of this.events.slice(from)) send(e);
+    if (this.status !== "running" && this.pending.size === 0) {
+      onEnd();
+      return () => void 0;
+    }
+    const f = (e) => {
+      if (e === null) onEnd();
+      else send(e);
+    };
+    this.subs.add(f);
+    return () => this.subs.delete(f);
+  }
+  start(llm) {
+    const root = this.dir;
+    this.done = (async () => {
+      const key = await loadOrCreateReceiptSigner2(root);
+      const previous = await lastReceiptTag2(root);
+      const result = await runAgent({
+        task: this.task,
+        llm,
+        ws: this.ws,
+        signal: this.abort.signal,
+        maxSteps: this.cfg.agent.maxSteps,
+        contextChars: Math.floor(this.cfg.memory.contextTokens * 2.5),
+        ...this.cfg.agent.verifyCommand ? { verifyCommand: this.cfg.agent.verifyCommand } : {},
+        runCommand: scratchRunner(this.project, this.ws, { timeoutMs: this.cfg.agent.commandTimeoutSeconds * 1e3 }),
+        approve: (info) => this.askApproval(info.command, info.network),
+        onEvent: (e) => {
+          if (e.type !== "done") this.push(e);
+        },
+        receipt: { signer: key, previous }
+      });
+      this.result = result;
+      this.status = result.status;
+      if (result.receipt) await appendReceipt2(root, result.receipt);
+      this.push({ type: "done", result });
+      for (const s of this.subs) s(null);
+    })().catch((e) => {
+      this.status = "error";
+      this.push({ type: "done", result: { status: "error", summary: e instanceof Error ? e.message : String(e), error: e instanceof Error ? e.message : String(e), steps: 0, toolCalls: 0, invalidReplies: 0, violations: 0, diffs: [], commands: [], usage: { promptTokens: 0, completionTokens: 0 } } });
+      for (const s of this.subs) s(null);
+    });
+  }
+  wait() {
+    return this.done;
+  }
+  askApproval(command, network) {
+    if (this.cfg.agent.autoApproveProjectCommands) return Promise.resolve(true);
+    const requestId = `appr_${randomBytes(4).toString("hex")}`;
+    return new Promise((resolve3) => {
+      const timer = setTimeout(() => this.resolveApproval(requestId, false), 10 * 6e4);
+      this.pending.set(requestId, { command, network, resolve: resolve3, timer });
+      this.push({ type: "approval", requestId, command, network });
+    });
+  }
+  resolveApproval(requestId, allow) {
+    const p = this.pending.get(requestId);
+    if (!p) return false;
+    clearTimeout(p.timer);
+    this.pending.delete(requestId);
+    this.push({ type: "approval_resolved", requestId, allowed: allow });
+    p.resolve(allow);
+    return true;
+  }
+  stop() {
+    this.abort.abort();
+    for (const id of [...this.pending.keys()]) this.resolveApproval(id, false);
+  }
+  /** Writes the agent's changes to the project (after checking nothing changed under it), with a checkpoint to roll back to. */
+  async apply(force = false) {
+    if (this.status === "running") throw new Error("the task is still running");
+    const changes = await this.ws.changeSet();
+    if (changes.length === 0) throw new Error("there is nothing to apply");
+    const r = await applyChanges(this.project, changes, { force });
+    this.checkpointId = r.id;
+    this.push({ type: "applied", checkpointId: r.id, files: r.applied.length });
+    return { checkpointId: r.id, files: r.applied.length };
+  }
+  async rollback(force = false) {
+    if (!this.checkpointId) throw new Error("nothing has been applied by this task");
+    await rollbackCheckpoint(this.project, this.checkpointId, { force });
+    this.push({ type: "rolled_back", checkpointId: this.checkpointId });
+    delete this.checkpointId;
+  }
+  async info() {
+    const receipts2 = await verifyReceiptLog(this.dir);
+    const gates = evaluateGates({
+      hostRamBytes: this.hostRamBytes,
+      agent: this.result ? { toolCalls: this.result.toolCalls, invalidReplies: this.result.invalidReplies, violations: this.result.violations, commandApproval: this.cfg.agent.autoApproveProjectCommands ? "never-asked" : "project-code" } : { toolCalls: 0, invalidReplies: 0, violations: this.ws.violations, commandApproval: "project-code" },
+      receiptsOk: receipts2.ok ? { ok: true } : { ok: false, detail: `entry ${receipts2.index}: ${receipts2.reason}` }
+    });
+    return {
+      id: this.id,
+      dir: this.dir,
+      task: this.task,
+      status: this.status,
+      startedAt: this.startedAt,
+      diffs: this.lastDiffs,
+      pendingApprovals: [...this.pending].map(([requestId, p]) => ({ requestId, command: p.command, network: p.network })),
+      ...this.result ? { result: this.result } : {},
+      ...this.checkpointId ? { checkpointId: this.checkpointId } : {},
+      gates
+    };
+  }
+};
+async function normaliseRoot(dir) {
+  const real = await realpath(dir);
+  if (!(await stat2(real)).isDirectory()) throw new Error(`${dir} is not a directory`);
+  if (real === "/" || /^[A-Za-z]:\\?$/.test(real)) throw new Error("the root of a drive cannot be used as a project");
+  return real;
+}
+var isInside = (root, p) => p === root || p.startsWith(join4(root, "/"));
+
+// src/server.ts
+import { randomBytes as randomBytes2, timingSafeEqual } from "crypto";
+import { createServer as createHttpServer } from "http";
+import { Readable as Readable2 } from "stream";
+import {
+  BASELINE,
+  CATALOG as CATALOG3,
+  CLUTOR_DEFAULTS,
+  GgufError,
+  GiB as GiB2,
+  buildModelLayout as buildModelLayout2,
+  parseGguf as parseGguf2,
+  QUANTS as QUANTS3,
+  ShadowWorkspace as ShadowWorkspace2,
+  approximateLayout as approximateLayout2,
+  evaluateGates as evaluateGates2,
+  expertSizeBytes,
+  generateRoutingTrace,
+  planMemory as planMemory2,
+  simulateStreaming
+} from "@clutor/core";
+import { NodeProject as NodeProject2, hostInfo as hostInfo2, listCheckpoints, ConflictError as ConflictError2, fileReader as fileReader2, measureExpertReads, readReceipts, verifyReceiptLog as verifyReceiptLog2, writeSyntheticGguf } from "@clutor/core/node";
+import { z } from "zod";
+var HttpError = class extends Error {
+  constructor(status2, message, extra = {}) {
+    super(message);
+    this.status = status2;
+    this.extra = extra;
+  }
+  status;
+  extra;
+};
+var MAX_BODY = 8 * 1024 * 1024;
+var APP_ORIGINS = ["app://clutor", "clutor://app"];
+var LOCAL_HOST = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+function createClutorServer(o) {
+  const cfg = o.config;
+  const token = o.token ?? randomBytes2(24).toString("hex");
+  const f = o.fetch ?? globalThis.fetch;
+  const roots = /* @__PURE__ */ new Set();
+  const sessions = /* @__PURE__ */ new Map();
+  const host = hostInfo2();
+  let boundPort = cfg.port;
+  const ready = (o.roots ?? []).map((r) => normaliseRoot(r).then((x) => roots.add(x)));
+  const send = (res, status2, body, headers = {}) => {
+    const text = typeof body === "string" ? body : JSON.stringify(body);
+    res.writeHead(status2, { "content-type": typeof body === "string" ? "text/plain; charset=utf-8" : "application/json; charset=utf-8", "cache-control": "no-store", "x-content-type-options": "nosniff", ...headers });
+    res.end(text);
+  };
+  const allowedOrigin = (origin) => APP_ORIGINS.includes(origin) || cfg.corsOrigins.includes(origin) || origin === `http://localhost:${boundPort}` || origin === `http://127.0.0.1:${boundPort}`;
+  const readBody = async (req) => {
+    const chunks = [];
+    let n = 0;
+    for await (const c of req) {
+      n += c.length;
+      if (n > MAX_BODY) throw new HttpError(413, "request body is too large");
+      chunks.push(c);
+    }
+    if (n === 0) return {};
+    try {
+      return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    } catch {
+      throw new HttpError(400, "the body is not valid JSON");
+    }
+  };
+  const parse = (schema, v) => {
+    const r = schema.safeParse(v);
+    if (!r.success) throw new HttpError(400, r.error.issues.map((i) => `${i.path.join(".") || "body"}: ${i.message}`).join("; "));
+    return r.data;
+  };
+  const authed = (req) => {
+    const h = req.headers["authorization"];
+    const t = typeof h === "string" && h.startsWith("Bearer ") ? h.slice(7) : req.headers["x-clutor-token"] ?? "";
+    const a = Buffer.from(t), b = Buffer.from(token);
+    return a.length === b.length && timingSafeEqual(a, b);
+  };
+  const needAuth = (req) => {
+    if (!authed(req)) throw new HttpError(401, "this needs the access token (Authorization: Bearer <token>)");
+  };
+  const llm = () => {
+    const b = cfg.backend;
+    if (b.kind === "openai") {
+      if (!b.baseUrl) throw new HttpError(409, "backend.baseUrl is not set");
+      return agentLlm(cfg, { baseUrl: b.baseUrl, model: b.model ?? "default", ...b.apiKeyEnv && process.env[b.apiKeyEnv] ? { apiKey: process.env[b.apiKeyEnv] } : {}, local: false }, f);
+    }
+    if (b.kind === "llama-server") {
+      if (o.backend?.state !== "ready") throw new HttpError(409, "the model is not loaded; start it first (POST /api/backend/start)");
+      return agentLlm(cfg, { baseUrl: o.backend.baseUrl, model: "local", local: true }, f);
+    }
+    throw new HttpError(409, 'no model backend is configured: set backend.kind to "openai" or "llama-server" in clutor.config.json');
+  };
+  const upstream = () => {
+    const b = cfg.backend;
+    if (b.kind === "openai" && b.baseUrl) return { url: b.baseUrl.replace(/\/$/, ""), headers: b.apiKeyEnv && process.env[b.apiKeyEnv] ? { authorization: `Bearer ${process.env[b.apiKeyEnv]}` } : {}, model: b.model ?? "default" };
+    if (b.kind === "llama-server" && o.backend?.state === "ready") return { url: o.backend.baseUrl, headers: {}, model: "local" };
+    throw new HttpError(503, "no model is available to answer: configure a backend and start it", { error: { message: "no model backend is ready", type: "unavailable" } });
+  };
+  const rootFor = async (dir) => {
+    if (typeof dir !== "string" || dir === "") throw new HttpError(400, "dir is required");
+    await Promise.all(ready);
+    let real;
+    try {
+      real = await normaliseRoot(dir);
+    } catch (e) {
+      throw new HttpError(400, e instanceof Error ? e.message : String(e));
+    }
+    for (const r of roots) if (isInside(r, real)) return real;
+    throw new HttpError(403, `${real} has not been opened in Clutor. Open it in the app, or start the server with --dir.`);
+  };
+  const planFor = (m, b) => planMemory2(m.layout, {
+    hostRamBytes: (b.hostRamGiB ?? host.totalRamBytes / GiB2) * GiB2,
+    ...b.ramCeilingGiB ?? cfg.memory.ramCeilingGiB ? { ramCeilingBytes: (b.ramCeilingGiB ?? cfg.memory.ramCeilingGiB) * GiB2 } : {},
+    ...cfg.memory.osHeadroomGiB !== void 0 ? { osHeadroomBytes: cfg.memory.osHeadroomGiB * GiB2 } : {},
+    contextTokens: b.contextTokens ?? cfg.memory.contextTokens,
+    kvBits: b.kvBits ?? cfg.memory.kvBits,
+    ...b.diskGBps ?? cfg.memory.diskGBps ? { diskBytesPerSec: (b.diskGBps ?? cfg.memory.diskGBps) * GiB2, diskMeasured: b.diskMeasured ?? cfg.memory.diskGBps !== void 0 } : {}
+  });
+  const DecideBody = z.object({
+    prompt: z.string().min(1).max(2e5),
+    choices: z.array(z.string().min(1).max(200)).min(2).max(26),
+    model: z.string().max(200).optional()
+  }).strict();
+  const PlanBody = z.object({
+    model: z.string().max(1e3),
+    hostRamGiB: z.number().min(1).max(4096).optional(),
+    ramCeilingGiB: z.number().min(1).max(4096).optional(),
+    contextTokens: z.number().int().min(256).max(2e6).optional(),
+    kvBits: z.union([z.literal(16), z.literal(8), z.literal(4)]).optional(),
+    diskGBps: z.number().min(0.01).max(100).optional(),
+    diskMeasured: z.boolean().optional()
+  }).strict();
+  async function route(req, res) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const path = url.pathname;
+    const method = req.method ?? "GET";
+    if (!LOCAL_HOST.test(req.headers.host ?? "")) throw new HttpError(421, "this server only answers on localhost");
+    const origin = req.headers.origin;
+    const cors = {};
+    if (origin) {
+      if (!allowedOrigin(origin)) throw new HttpError(403, `the origin ${origin} is not allowed; add it to corsOrigins in clutor.config.json`);
+      Object.assign(cors, { "access-control-allow-origin": origin, vary: "Origin", "access-control-allow-headers": "authorization, content-type, x-clutor-token", "access-control-allow-methods": "GET, POST, DELETE, OPTIONS" });
+    }
+    if (method === "OPTIONS") {
+      res.writeHead(204, cors);
+      return void res.end();
+    }
+    const reply = (status2, body) => send(res, status2, body, cors);
+    if (method === "GET" && path === "/api/health") return reply(200, { ok: true, version: o.version, backend: { kind: cfg.backend.kind, state: o.backend?.state ?? (cfg.backend.kind === "openai" ? "external" : "none") } });
+    if (method === "GET" && path === "/api/hardware") return reply(200, host);
+    if (method === "GET" && path === "/api/catalog") return reply(200, { models: CATALOG3.map((c) => ({ id: c.id, name: c.name, experts: c.experts, expertsUsed: c.expertsUsed, layers: c.layers, publishedParamsB: c.publishedParamsB, source: c.source })), quants: QUANTS3 });
+    if (method === "POST" && path === "/api/plan") {
+      const b = parse(PlanBody, await readBody(req));
+      const isFile = b.model.toLowerCase().endsWith(".gguf");
+      if (isFile) needAuth(req);
+      let m2;
+      try {
+        m2 = await resolveModel(b.model, { modelsDir: resolveModelsDir(), allowFiles: isFile });
+      } catch (e) {
+        throw new HttpError(e instanceof ModelError || e instanceof GgufError ? 400 : 500, e instanceof Error ? e.message : String(e));
+      }
+      const plan2 = planFor(m2, b);
+      const gates = evaluateGates2({ hostRamBytes: (b.hostRamGiB ?? host.totalRamBytes / GiB2) * GiB2, plan: plan2, cache: { policy: cfg.cache.policy }, smartRoute: { enabled: cfg.cache.smartRoute.enabled, maxDeltaP: cfg.cache.smartRoute.maxDeltaP }, ...m2.gguf ? { gguf: m2.gguf } : {} });
+      return reply(200, { model: { id: m2.id, name: m2.name, source: m2.source, quant: m2.quant, approximate: m2.layout.approximate, totalBytes: m2.layout.totalBytes, layers: m2.layout.layerCount, experts: m2.layout.expertCount, expertsUsed: m2.layout.expertsUsed }, plan: plan2, gates });
+    }
+    if (method === "POST" && path === "/api/simulate") {
+      const b = parse(z.object({ model: z.string().max(100), quant: z.string().max(20).optional(), cacheGiB: z.number().min(0).max(4096), tokens: z.number().int().min(20).max(1500).default(300), locality: z.number().min(0).max(0.99).default(0.9), diskGBps: z.number().min(0.01).max(100).default(3), computeMsPerLayer: z.number().min(0).max(1e3).default(0.5), seed: z.number().int().default(1), smartRoute: z.boolean().default(false) }).strict(), await readBody(req));
+      const spec = CATALOG3.find((c) => c.id === b.model);
+      if (!spec || spec.experts === 0) throw new HttpError(400, "pick a mixture-of-experts model from the catalog");
+      const bpw = QUANTS3[b.quant ?? "Q4_K_M"];
+      if (bpw === void 0) throw new HttpError(400, "unknown quantisation");
+      const layout = approximateLayout2(spec, bpw);
+      const moe = layout.layers.filter((l) => l.experts.length).map((l) => l.index);
+      const trace = generateRoutingTrace({ moeLayers: moe, experts: spec.experts, used: spec.expertsUsed, tokens: b.tokens, seed: b.seed, locality: b.locality });
+      const base = { cacheBytes: b.cacheGiB * GiB2, disk: { bytesPerSec: b.diskGBps * GiB2, requestLatencySec: 1e-4 }, computePerLayerSec: b.computeMsPerLayer / 1e3 };
+      const baseline = simulateStreaming(layout, trace, { ...BASELINE, ...base });
+      const clutor = simulateStreaming(layout, trace, { ...CLUTOR_DEFAULTS, smartRoute: { ...CLUTOR_DEFAULTS.smartRoute, enabled: b.smartRoute }, ...base });
+      return reply(200, { synthetic: true, note: "A synthetic routing trace: it shows how each policy behaves on a workload with this locality, not how any real model routes.", expertBytes: expertSizeBytes(layout), baseline, clutor });
+    }
+    if (method === "GET" && path === "/v1/models") {
+      const u = upstream();
+      return reply(200, { object: "list", data: [{ id: u.model, object: "model", created: 0, owned_by: "clutor" }] });
+    }
+    if (method === "POST" && path === "/v1/decide") {
+      needAuth(req);
+      const b = parse(DecideBody, await readBody(req));
+      const u = upstream();
+      const model = u.model === "local" ? "local" : b.model ?? u.model;
+      const authorization = u.headers["authorization"];
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      let result;
+      try {
+        result = await runDecide({ baseUrl: u.url, model, ...authorization ? { apiKey: authorization.replace(/^Bearer /, "") } : {} }, b.prompt, b.choices, f);
+      } catch (e) {
+        if (e instanceof DecideError) throw new HttpError(e.status, e.message);
+        throw e;
+      }
+      const root = roots.values().next().value;
+      const receipt = root ? await sealDecision(root, model, b.prompt, b.choices, result, startedAt) : null;
+      return reply(200, { choice: result.choice, probabilities: result.probabilities, probabilityMassOnChoices: result.probabilityMassOnChoices, latencyMs: result.latencyMs, receipt });
+    }
+    if (method === "POST" && path === "/v1/chat/completions") {
+      const u = upstream();
+      const body = await readBody(req);
+      const r = await f(`${u.url}/chat/completions`, { method: "POST", headers: { "content-type": "application/json", ...u.headers }, body: JSON.stringify({ ...body, model: u.model === "local" ? body["model"] ?? "local" : u.model }) });
+      res.writeHead(r.status, { "content-type": r.headers.get("content-type") ?? "application/json", "cache-control": "no-store", ...cors });
+      if (!r.body) return void res.end();
+      const stream = Readable2.fromWeb(r.body);
+      req.on("close", () => stream.destroy());
+      stream.pipe(res);
+      return;
+    }
+    if (method === "GET" && path === "/api/tags") {
+      const u = (() => {
+        try {
+          return upstream();
+        } catch {
+          return null;
+        }
+      })();
+      const local = await listLocalModels(resolveModelsDir()).catch(() => []);
+      return reply(200, { models: [...u ? [{ name: u.model, model: u.model, modified_at: (/* @__PURE__ */ new Date()).toISOString(), size: 0, digest: "", details: { format: "gguf" } }] : [], ...local.map((m2) => ({ name: m2.file, model: m2.file, modified_at: (/* @__PURE__ */ new Date()).toISOString(), size: m2.bytes, digest: "", details: { format: "gguf" } }))] });
+    }
+    if (method === "POST" && (path === "/api/chat" || path === "/api/generate")) {
+      const kind = path === "/api/chat" ? "chat" : "generate";
+      const req0 = await readBody(req);
+      const u = upstream();
+      const model = req0.model ?? u.model;
+      const stream = req0.stream !== false;
+      const r = await f(`${u.url}/chat/completions`, { method: "POST", headers: { "content-type": "application/json", ...u.headers }, body: JSON.stringify({ ...toOpenAiBody(req0, u.model === "local" ? model : u.model, kind), ...stream ? { stream_options: { include_usage: true } } : {} }) });
+      if (!r.ok) throw new HttpError(r.status === 404 ? 404 : 502, `the model server answered ${r.status}: ${(await r.text()).slice(0, 200)}`);
+      if (!stream) return reply(200, fromOpenAiReply(kind, model, await r.json()));
+      res.writeHead(200, { "content-type": "application/x-ndjson", "cache-control": "no-store", ...cors });
+      for await (const line of streamToOllama(kind, model, r.body)) {
+        if (!res.write(line)) await new Promise((x) => res.once("drain", x));
+      }
+      return void res.end();
+    }
+    if (path.startsWith("/api/")) needAuth(req);
+    if (method === "GET" && path === "/api/models") return reply(200, { local: await listLocalModels(resolveModelsDir()), catalog: CATALOG3.map((c) => c.id) });
+    if (method === "GET" && path === "/api/roots") return reply(200, { roots: [...roots] });
+    if (method === "POST" && path === "/api/roots") {
+      const b = parse(z.object({ dir: z.string().min(1).max(2e3) }).strict(), await readBody(req));
+      try {
+        return reply(200, { root: await addRoot(b.dir) });
+      } catch (e) {
+        throw new HttpError(400, e instanceof Error ? e.message : String(e));
+      }
+    }
+    if (method === "GET" && path === "/api/backend") return reply(200, { kind: cfg.backend.kind, state: o.backend?.state ?? "n/a", error: o.backend?.error ?? null, log: o.backend?.recentLog.slice(-40) ?? [] });
+    if (method === "POST" && path === "/api/backend/stop") {
+      await o.backend?.stop();
+      return reply(200, { state: o.backend?.state ?? "n/a" });
+    }
+    if (method === "POST" && path === "/api/backend/start") {
+      if (!o.startBackend || !o.backend) throw new HttpError(409, "this server was not set up to start a model: set backend.kind to llama-server and give it a model file");
+      if (o.backend.state === "ready" || o.backend.state === "starting") return reply(200, { state: o.backend.state });
+      void o.startBackend().catch((e) => o.log?.(`backend: ${e instanceof Error ? e.message : String(e)}`));
+      return reply(202, { state: "starting" });
+    }
+    if (method === "POST" && path === "/api/bench") {
+      const b = parse(z.object({ model: z.string().max(2e3).optional() }).strict(), await readBody(req));
+      let file = b.model;
+      let cleanup;
+      if (file) {
+        try {
+          file = (await resolveModel(file, { modelsDir: resolveModelsDir() })).path;
+        } catch (e) {
+          throw new HttpError(400, e instanceof Error ? e.message : String(e));
+        }
+      } else {
+        const { mkdtemp, rm: rm2 } = await import("fs/promises");
+        const { tmpdir: tmpdir2 } = await import("os");
+        const dir = await mkdtemp(`${tmpdir2()}/clutor-bench-`);
+        cleanup = () => rm2(dir, { recursive: true, force: true });
+        file = `${dir}/bench.gguf`;
+        await writeSyntheticGguf(file, { arch: "qwen2moe", name: "bench-moe", layers: 8, embedding: 1024, heads: 16, kvHeads: 4, contextLength: 4096, expertCount: 32, expertsUsed: 4, expertFfn: 1024, denseFfn: 0, vocab: 4096, sharedExperts: 0 });
+      }
+      try {
+        const r = await fileReader2(file);
+        let layout;
+        try {
+          layout = buildModelLayout2(await parseGguf2(r));
+        } finally {
+          await r.close();
+        }
+        if (!layout.expertCount) throw new HttpError(400, "this model has no experts to read");
+        const m2 = await measureExpertReads(file, layout, host.totalRamBytes, 96);
+        return reply(200, { measurement: m2, synthetic: b.model === void 0 });
+      } finally {
+        await cleanup?.();
+      }
+    }
+    if (method === "POST" && path === "/api/mcp") {
+      const r = await handleMcp(await readBody(req), { isRoot: (d) => rootFor(d).catch(() => null) });
+      return r.status === 202 ? (res.writeHead(202, cors), void res.end()) : reply(r.status, r.body);
+    }
+    if (method === "POST" && path === "/api/agent/run") {
+      const b = parse(z.object({ dir: z.string().min(1), task: z.string().min(1).max(2e4) }).strict(), await readBody(req));
+      const dir = await rootFor(b.dir);
+      const client = llm();
+      const project = new NodeProject2(dir);
+      const s = new AgentSession(dir, b.task, project, new ShadowWorkspace2(project), cfg, host.totalRamBytes);
+      sessions.set(s.id, s);
+      if (sessions.size > 50) for (const [k, v] of sessions) {
+        if (v.status !== "running") {
+          sessions.delete(k);
+          break;
+        }
+      }
+      s.start(client);
+      return reply(202, { id: s.id });
+    }
+    const m = /^\/api\/agent\/(task_[a-f0-9]+)(?:\/([a-z]+))?$/.exec(path);
+    if (m) {
+      const s = sessions.get(m[1]);
+      if (!s) throw new HttpError(404, "no such task");
+      const action = m[2];
+      if (method === "GET" && !action) return reply(200, await s.info());
+      if (method === "GET" && action === "events") {
+        res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive", ...cors });
+        const from = Number(url.searchParams.get("from") ?? 0) || 0;
+        const stop = s.subscribe(from, (e) => res.write(`data: ${JSON.stringify(e)}
+
+`), () => res.end());
+        req.on("close", stop);
+        return;
+      }
+      if (method === "POST" && action === "approve") {
+        const b = parse(z.object({ requestId: z.string(), allow: z.boolean() }).strict(), await readBody(req));
+        return s.resolveApproval(b.requestId, b.allow) ? reply(200, { ok: true }) : reply(404, { error: "no such approval request" });
+      }
+      if (method === "POST" && action === "stop") {
+        s.stop();
+        return reply(200, { ok: true });
+      }
+      if (method === "POST" && action === "apply") {
+        const b = parse(z.object({ force: z.boolean().default(false) }).strict(), await readBody(req));
+        try {
+          return reply(200, await s.apply(b.force));
+        } catch (e) {
+          if (e instanceof ConflictError2) return reply(409, { error: e.message, conflicts: e.conflicts });
+          throw new HttpError(400, e instanceof Error ? e.message : String(e));
+        }
+      }
+      if (method === "POST" && action === "rollback") {
+        const b = parse(z.object({ force: z.boolean().default(false) }).strict(), await readBody(req));
+        try {
+          await s.rollback(b.force);
+          return reply(200, { ok: true });
+        } catch (e) {
+          if (e instanceof ConflictError2) return reply(409, { error: e.message, conflicts: e.conflicts });
+          throw new HttpError(400, e instanceof Error ? e.message : String(e));
+        }
+      }
+    }
+    if (method === "GET" && path === "/api/receipts") {
+      const dir = await rootFor(url.searchParams.get("dir"));
+      return reply(200, { receipts: (await readReceipts(dir)).slice(-100), verification: await verifyReceiptLog2(dir), checkpoints: await listCheckpoints(new NodeProject2(dir)) });
+    }
+    throw new HttpError(404, "no such endpoint");
+  }
+  function resolveModelsDir() {
+    return cfg.models.startsWith("/") || /^[A-Za-z]:/.test(cfg.models) ? cfg.models : `${o.root}/${cfg.models}`;
+  }
+  async function addRoot(dir) {
+    const real = await normaliseRoot(dir);
+    roots.add(real);
+    return real;
+  }
+  const http = createHttpServer((req, res) => {
+    route(req, res).catch((e) => {
+      const status2 = e instanceof HttpError ? e.status : 500;
+      if (status2 === 500) o.log?.(`error: ${e instanceof Error ? e.stack ?? e.message : String(e)}`);
+      if (res.headersSent) return void res.destroy();
+      send(res, status2, { error: e instanceof HttpError ? e.message : "internal error", ...e instanceof HttpError ? e.extra : {} });
+    });
+  });
+  http.headersTimeout = 15e3;
+  http.requestTimeout = 0;
+  return {
+    http,
+    token,
+    sessions,
+    addRoot,
+    listen: () => new Promise((resolve3, reject) => {
+      http.once("error", reject);
+      http.listen(cfg.port, cfg.host, () => {
+        const a = http.address();
+        boundPort = a.port;
+        resolve3({ host: a.address, port: a.port });
+      });
+    }),
+    close: async () => {
+      for (const s of sessions.values()) s.stop();
+      await new Promise((r) => {
+        http.close(() => r());
+        http.closeAllConnections();
+      });
+      await o.backend?.stop();
+    }
+  };
+}
+
+// src/engine.ts
+import { spawn as spawn2 } from "child_process";
+import { accessSync as accessSync2, constants as constants2 } from "fs";
+import { homedir as homedir3 } from "os";
+import { delimiter as delimiter2, dirname, join as join5 } from "path";
+import { fileURLToPath } from "url";
+var EngineError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EngineError";
+  }
+};
+var EXE = process.platform === "win32" ? "clutor-engine.exe" : "clutor-engine";
+var executable = (p) => {
+  try {
+    accessSync2(p, constants2.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+function engineSourceDir() {
+  return join5(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "c");
+}
+function findEngine(env = process.env) {
+  const candidates = [env["CLUTOR_ENGINE"], join5(engineSourceDir(), "build", EXE), join5(homedir3(), ".clutor", "bin", EXE), ...(env["PATH"] ?? "").split(delimiter2).map((d) => join5(d, EXE))];
+  return candidates.find((c) => !!c && executable(c));
+}
+function run(bin, args, opts = {}) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn2(bin, args, { stdio: ["ignore", "pipe", "pipe"], ...opts.cwd ? { cwd: opts.cwd } : {} });
+    let stdout = "", stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new EngineError(`${bin} did not finish within ${(opts.timeoutMs ?? 6e5) / 1e3} seconds`));
+    }, opts.timeoutMs ?? 6e5);
+    child.stdout.on("data", (b) => {
+      stdout += b.toString();
+    });
+    child.stderr.on("data", (b) => {
+      stderr += b.toString();
+    });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(new EngineError(`could not start ${bin}: ${e.message}`));
+    });
+    child.on("close", (code2) => {
+      clearTimeout(timer);
+      resolve3({ code: code2 ?? 1, stdout, stderr });
+    });
+  });
+}
+async function buildEngine() {
+  const dir = engineSourceDir();
+  const r = await run("make", ["-C", dir], { timeoutMs: 3e5 }).catch((e) => {
+    throw new EngineError(`could not run make: ${e instanceof Error ? e.message : String(e)}`);
+  });
+  if (r.code !== 0) throw new EngineError(`the engine did not compile:
+${(r.stderr || r.stdout).split("\n").slice(-15).join("\n")}`);
+  const bin = join5(dir, "build", EXE);
+  if (!executable(bin)) throw new EngineError(`make finished but ${bin} is missing`);
+  return bin;
+}
+function streamArgs(file, o) {
+  const a = ["stream", file, "--json"];
+  const add = (k, v) => {
+    if (v !== void 0) a.push(k, String(v));
+  };
+  add("--tokens", o.tokens);
+  add("--warmup", o.warmup);
+  add("--cache-mb", o.cacheMb);
+  add("--stage", o.stage);
+  add("--policy", o.policy);
+  add("--smart", o.smart);
+  if (o.prefetch !== void 0) add("--prefetch", o.prefetch ? "on" : "off");
+  add("--io-threads", o.ioThreads);
+  add("--seed", o.seed);
+  add("--locality", o.locality);
+  add("--predict-corr", o.predictCorr);
+  add("--compute-us", o.computeUs);
+  add("--window-pct", o.windowPct);
+  add("--dense", o.dense);
+  add("--compute", o.compute);
+  add("--window", o.window);
+  if (o.shift) add("--shift", `${o.shift.at},${o.shift.len}`);
+  if (o.noOsCache) a.push("--no-os-cache");
+  return a;
+}
+async function engineInfo(bin, file) {
+  const r = await run(bin, ["info", file, "--json"], { timeoutMs: 6e4 });
+  if (r.code !== 0) throw new EngineError(r.stderr.trim() || `engine exited with ${r.code}`);
+  return JSON.parse(r.stdout);
+}
+async function engineStream(bin, file, o = {}, timeoutMs = 9e5) {
+  const r = await run(bin, streamArgs(file, o), { timeoutMs });
+  if (r.code !== 0) throw new EngineError(r.stderr.trim() || `engine exited with ${r.code}`);
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    throw new EngineError("the engine printed something that is not a report");
+  }
+}
+
+// src/cli.ts
+import { existsSync, mkdirSync as mkdirSync2, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname as dirname2, join as join6, resolve as resolve2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import {
+  BASELINE as BASELINE2,
+  CATALOG as CATALOG4,
+  CLUTOR_DEFAULTS as CLUTOR_DEFAULTS2,
+  GiB as GiB3,
+  QUANTS as QUANTS4,
+  ShadowWorkspace as ShadowWorkspace3,
+  OpenAiCompatibleClient as OpenAiCompatibleClient2,
+  buildModelLayout as buildModelLayout3,
+  evaluateGates as evaluateGates3,
+  expertSizeBytes as expertSizeBytes2,
+  fmtGiB as fmtGiB2,
+  generateRoutingTrace as generateRoutingTrace2,
+  parseGguf as parseGguf3,
+  planMemory as planMemory3,
+  runAgent as runAgent2,
+  simulateStreaming as simulateStreaming2,
+  validateBounds,
+  approximateLayout as approximateLayout3,
+  fmtBytes,
+  keyThumbprint,
+  sealReceipt as sealReceipt2,
+  verifyReceiptChain
+} from "@clutor/core";
+import { NodeProject as NodeProject3, applyChanges as applyChanges2, diskModelFrom, fileReader as fileReader3, hostInfo as hostInfo3, lastReceiptTag as lastReceiptTag3, listCheckpoints as listCheckpoints2, loadOrCreateReceiptSigner as loadOrCreateReceiptSigner3, measureExpertReads as measureExpertReads2, appendReceipt as appendReceipt3, readReceipts as readReceipts2, rollbackCheckpoint as rollbackCheckpoint2, scratchRunner as scratchRunner2, verifyReceiptLog as verifyReceiptLog3, writeSyntheticGguf as writeSyntheticGguf2, ConflictError as ConflictError3 } from "@clutor/core/node";
+var version = () => {
+  try {
+    const here = dirname2(fileURLToPath2(import.meta.url));
+    return JSON.parse(readFileSync(join6(here, "..", "package.json"), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+};
+var HELP = `clutor: run very large models from disk on small machines, and a coding agent that works on your project
+
+Usage: clutor <command> [options]
+       clutor                      In a terminal: an interactive session. Type a task, or /help for commands.
+
+  init [dir]                         Create clutor.config.json and a models folder
+  models [dir]                       List the model catalog and the .gguf files in your models folder
+  pull [id] [--yes]                  List the small test models you can download, or download one into your models folder
+  inspect <file.gguf>                Read a model file's header: architecture, layers, experts, sizes
+  plan <model> [--ram GiB] [--ctx N] [--kv 16|8|4] [--disk GiB/s] [--quant Q4_K_M] [--json]
+                                     Will it fit? Where does the memory go? How fast could it possibly run?
+  simulate <model> [--cache GiB] [--tokens N] [--locality 0.9] [--disk GiB/s] [--compute-ms N] [--smart-route] [--json]
+                                     Replay a routing trace through the expert cache: baseline LRU against clutor
+  bench [--file model.gguf] [--engine] [--cache-mb N] [--tokens N] [--compute kernel|checksum]
+                                     Measure real disk reads on this machine; with the native engine, also compare cache and prefetch strategies
+  stream <model.gguf> [--tokens N] [--cache-mb N] [--policy lru|wtinylfu|adaptive] [--smart J,M,TAU|off] [--prefetch on|off] [--dense auto|resident|ring] [--compute kernel|checksum] [--json]
+                                     Stream a model's experts from disk through the native engine (synthetic routing; measured I/O and cache)
+  engine build|where                 Compile the native engine from c/ (needs a C compiler), or show which one is used
+  code "<task>" [--dir folder] [--apply] [--yes] [--verify "npm test"] [--max-steps N]
+                                     Run the coding agent on a folder; review the diff before anything is written
+  serve [dir] [--port ${DEFAULT_PORT}] [--folder dir]...   Start the local server: OpenAI and Ollama compatible API, agent, MCP
+  backend [--model file.gguf]        Find llama-server, see which flags it supports and how clutor would start it
+  status [dir]                       One screen: machine, model backend, memory plan, receipts
+  chat [--prompt "<text>"] [--system "<text>"]   Talk to the configured model in the terminal (one-shot with --prompt, else a REPL)
+  decide --prompt "<text>" --choices "a,b,c" [--json]   One forward pass, no chat loop: probability of each choice's first token
+  receipts [dir]                     Verify the agent's receipt log and list checkpoints (also: ledger verify|list)
+  receipt verify <clt_token|file> [dir] [--key-id id|--pubkey file]   Check a receipt log offline; receipt key shows your key id
+  rollback <checkpoint> [--dir folder] [--force]   Undo an applied task
+  doctor [dir]                       Check this machine and the configuration
+
+Models are catalog ids (${CATALOG4.map((c) => c.id).join(", ")}) or the path of a .gguf file.
+Common options: --config <file>  --json  -h, --help  -v, --version
+`;
+var BOOLEANS = ["json", "help", "version", "apply", "yes", "force", "smart-route", "no-start", "engine", "no-os-cache"];
+function cfgFor(args, io, dirArg) {
+  return loadConfig(dirArg ? resolve2(io.cwd, dirArg) : io.cwd, flagString(args, "config"));
+}
+async function main(argv, io, session) {
+  const args = parseArgs(argv, BOOLEANS);
+  const [command, ...rest] = args.positional;
+  const json = flagBool(args, "json");
+  try {
+    if (flagBool(args, "version") || command === "version" || argv.includes("-v")) return io.out(version()), 0;
+    if (!command && !flagBool(args, "help") && !argv.includes("-h") && io.prompt && !session) return await (await import("./repl-OVODHQI5.js")).runRepl(io, (a, s) => main(a, io, s), (cfg, what) => engineSlashCommand(io, cfg, what));
+    if (!command || flagBool(args, "help") || command === "help" || argv.includes("-h")) return io.out(HELP), 0;
+    switch (command) {
+      case "init":
+        return await init(io, rest[0]);
+      case "models":
+        return await models(io, args, rest[0], json);
+      case "stream":
+        return await streamCmd(io, args, rest[0], json);
+      case "engine":
+        return await engineCmd(io, rest[0]);
+      case "pull":
+        return await pull(io, args, rest[0]);
+      case "inspect":
+        return await inspect(io, rest[0], json);
+      case "plan":
+        return await plan(io, args, rest[0], json);
+      case "simulate":
+        return await simulate(io, args, rest[0], json);
+      case "bench":
+        return await bench(io, args, json);
+      case "code":
+        return await code(io, args, rest.join(" "), session);
+      case "serve":
+        return await serve(io, args, rest[0]);
+      case "backend":
+        return await backendCmd(io, args);
+      case "receipts":
+        return await receipts(io, args, rest[0], json);
+      case "ledger":
+        return await receipts(io, args, rest[1], json);
+      case "receipt":
+        return await receiptVerify(io, args, rest[0], rest[1], rest[2]);
+      case "status":
+        return await status(io, args, rest[0], json);
+      case "chat":
+        return await chat(io, args);
+      case "decide":
+        return await decide(io, args, json);
+      case "rollback":
+        return await rollback(io, args, rest[0]);
+      case "doctor":
+        return await doctor(io, args, rest[0], json);
+      default:
+        throw new UsageError(`unknown command "${command}"; run clutor --help`);
+    }
+  } catch (e) {
+    if (e instanceof UsageError || e instanceof ConfigError) {
+      io.err(e.message);
+      return 2;
+    }
+    io.err(e instanceof Error ? e.message : String(e));
+    return 1;
+  }
+}
+function init(io, dirArg) {
+  const dir = resolve2(io.cwd, dirArg ?? ".");
+  mkdirSync2(join6(dir, "models"), { recursive: true });
+  const path = join6(dir, CONFIG_FILE);
+  if (existsSync(path)) {
+    io.err(`${path} already exists; leaving it alone`);
+    return 1;
+  }
+  writeFileSync(path, `${JSON.stringify({ port: DEFAULT_PORT, models: "models", backend: { kind: "none" }, memory: { contextTokens: 8192, kvBits: 16 }, cache: { policy: "adaptive" }, agent: { toolMode: "json", maxSteps: 30 } }, null, 2)}
+`);
+  const h = hostInfo3();
+  io.out(`Created ${path} and ${join6(dir, "models")}.`);
+  io.out(`This machine: ${h.platformName} ${h.arch}, ${h.cpuModel}, ${fmtGiB2(h.totalRamBytes)} RAM.`);
+  io.out("");
+  io.out("Next: put a .gguf file in the models folder, then");
+  io.out("  clutor plan <file.gguf>          to see whether and how it fits");
+  io.out("  clutor backend --model <file>    to see how llama-server would be started for it");
+  return 0;
+}
+async function models(io, args, dirArg, json) {
+  const { config, root } = cfgFor(args, io, dirArg);
+  const local = await listLocalModels(resolve2(root, config.models));
+  if (json) {
+    io.out(JSON.stringify({ local, catalog: CATALOG4.map((c) => c.id) }, null, 2));
+    return 0;
+  }
+  io.out("Catalog (architectures you can plan for before downloading anything):");
+  io.out(table(CATALOG4.map((c) => [c.id, c.name, `${c.publishedParamsB}B`, c.experts ? `${c.experts} experts, ${c.expertsUsed} used` : "dense"])));
+  io.out("");
+  io.out(local.length ? `In ${resolve2(root, config.models)}:
+${table(local.map((m) => [m.file, fmtBytes(m.bytes)]))}` : `No .gguf files in ${resolve2(root, config.models)}.`);
+  return 0;
+}
+async function inspect(io, file, json) {
+  if (!file) throw new UsageError("usage: clutor inspect <file.gguf>");
+  const path = resolve2(io.cwd, file);
+  const r = await fileReader3(path);
+  try {
+    const g = await parseGguf3(r);
+    const l = buildModelLayout3(g);
+    validateBounds(g);
+    if (json) {
+      io.out(JSON.stringify({ version: g.version, tensors: g.tensorCount, arch: l.arch, name: l.name, layers: l.layerCount, experts: l.expertCount, expertsUsed: l.expertsUsed, bytes: l.totalBytes, quantisations: l.quantisations, residentBytes: l.residentBytes, fileBytes: g.fileSize }, null, 2));
+      return 0;
+    }
+    io.out(`${l.name} (${l.arch}), GGUF v${g.version}, ${g.tensorCount} tensors, ${fmtBytes(g.fileSize)}`);
+    io.out(`${l.layerCount} layers${l.expertCount ? `, ${l.expertCount} experts per layer (${l.expertsUsed} used per token${l.sharedExperts ? `, ${l.sharedExperts} shared` : ""})` : ", dense"}`);
+    io.out(`Always needed in RAM: ${fmtBytes(l.residentBytes)}   Per-layer dense weights: ${fmtBytes(l.layers.reduce((s, x) => s + x.denseBytes, 0))}   Experts: ${fmtBytes(l.layers.reduce((s, x) => s + x.experts.length * x.expertBytes, 0))}`);
+    io.out(`Quantisations: ${Object.entries(l.quantisations).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} ${fmtBytes(v)}`).join(", ")}`);
+    io.out(`KV cache: ${l.kv.kvHeads} KV heads x ${l.kv.headDim} dims, up to ${l.kv.maxContext.toLocaleString("en-US")} tokens`);
+    if (l.unsizedTensors) io.out(`! ${l.unsizedTensors} tensors use a quantisation this reader cannot size.`);
+    io.out("All tensors lie inside the file.");
+    return 0;
+  } finally {
+    await r.close();
+  }
+}
+function numFlag(args, name, min, max) {
+  const v = flagString(args, name);
+  if (v === void 0) return void 0;
+  const n = Number(v);
+  if (!Number.isFinite(n) || n < min || n > max) throw new UsageError(`--${name} must be a number from ${min} to ${max}`);
+  return n;
+}
+async function plan(io, args, ref, json) {
+  if (!ref) throw new UsageError("usage: clutor plan <model> [--ram GiB]");
+  const { config, root } = cfgFor(args, io);
+  const quant = flagString(args, "quant");
+  const m = await resolveModel(ref.toLowerCase().endsWith(".gguf") ? resolve2(io.cwd, ref) : quant ? `${ref}@${quant}` : ref, { modelsDir: resolve2(root, config.models) });
+  const h = hostInfo3();
+  const ram = numFlag(args, "ram", 1, 4096) ?? config.memory.ramCeilingGiB;
+  const disk = numFlag(args, "disk", 0.01, 100) ?? config.memory.diskGBps;
+  const kv = flagInt(args, "kv", 4, 16);
+  if (kv !== void 0 && ![4, 8, 16].includes(kv)) throw new UsageError("--kv must be 16, 8 or 4");
+  const ramFlag = numFlag(args, "ram", 1, 4096);
+  const hostRam = ramFlag !== void 0 ? ramFlag * GiB3 : h.totalRamBytes;
+  const p = planMemory3(m.layout, {
+    hostRamBytes: hostRam,
+    ...ramFlag === void 0 && ram ? { ramCeilingBytes: ram * GiB3 } : {},
+    ...config.memory.osHeadroomGiB !== void 0 ? { osHeadroomBytes: config.memory.osHeadroomGiB * GiB3 } : {},
+    contextTokens: flagInt(args, "ctx", 256, 2e6) ?? config.memory.contextTokens,
+    kvBits: kv ?? config.memory.kvBits,
+    ...disk ? { diskBytesPerSec: disk * GiB3, diskMeasured: flagString(args, "disk") !== void 0 || config.memory.diskGBps !== void 0 } : {}
+  });
+  const gates = evaluateGates3({ hostRamBytes: hostRam, plan: p, cache: { policy: config.cache.policy }, smartRoute: { enabled: config.cache.smartRoute.enabled, maxDeltaP: config.cache.smartRoute.maxDeltaP }, ...m.gguf ? { gguf: m.gguf } : {} });
+  if (json) {
+    io.out(JSON.stringify({ model: { id: m.id, name: m.name, approximate: m.layout.approximate }, plan: p, gates }, null, 2));
+    return p.fits ? 0 : 1;
+  }
+  io.out(formatPlan(m.name, m.quant, p));
+  io.out("");
+  io.out(formatGates(gates));
+  return p.fits ? 0 : 1;
+}
+async function simulate(io, args, id, json) {
+  if (!id) throw new UsageError("usage: clutor simulate <model> --cache <GiB>");
+  const spec = CATALOG4.find((c2) => c2.id === id);
+  if (!spec || spec.experts === 0) throw new UsageError(`pick a mixture-of-experts model: ${CATALOG4.filter((c2) => c2.experts).map((c2) => c2.id).join(", ")}`);
+  const quant = flagString(args, "quant") ?? "Q4_K_M";
+  const bpw = QUANTS4[quant];
+  if (bpw === void 0) throw new UsageError(`unknown quantisation ${quant}`);
+  const layout = approximateLayout3(spec, bpw);
+  const cacheGiB = numFlag(args, "cache", 0, 4096) ?? 4;
+  const tokens = flagInt(args, "tokens", 20, 3e3) ?? 300;
+  const moe = layout.layers.filter((l) => l.experts.length).map((l) => l.index);
+  const trace = generateRoutingTrace2({ moeLayers: moe, experts: spec.experts, used: spec.expertsUsed, tokens, seed: flagInt(args, "seed", 0, 2 ** 31) ?? 1, locality: numFlag(args, "locality", 0, 0.99) ?? 0.9 });
+  const base = { cacheBytes: cacheGiB * GiB3, disk: { bytesPerSec: (numFlag(args, "disk", 0.01, 100) ?? 3) * GiB3, requestLatencySec: 1e-4 }, computePerLayerSec: (numFlag(args, "compute-ms", 0, 1e3) ?? 0.5) / 1e3 };
+  const b = simulateStreaming2(layout, trace, { ...BASELINE2, ...base });
+  const c = simulateStreaming2(layout, trace, { ...CLUTOR_DEFAULTS2, smartRoute: { ...CLUTOR_DEFAULTS2.smartRoute, enabled: flagBool(args, "smart-route") }, ...base });
+  if (json) {
+    io.out(JSON.stringify({ synthetic: true, baseline: b, clutor: c }, null, 2));
+    return 0;
+  }
+  io.out(`${spec.name} (${quant}), ${cacheGiB} GiB expert cache, ${tokens} tokens, expert size ${(expertSizeBytes2(layout) / 2 ** 20).toFixed(1)} MiB`);
+  io.out(formatSimulation(b, c));
+  io.out("");
+  io.out("This replays a SYNTHETIC routing trace (skewed expert popularity, neighbouring tokens that pick similar experts). It shows how each policy");
+  io.out("behaves on a workload like that; it is not a measurement of any real model, and speed is modelled from the disk speed you give it.");
+  return 0;
+}
+async function bench(io, args, json) {
+  const h = hostInfo3();
+  const file = flagString(args, "file");
+  let path;
+  let cleanup;
+  if (file) path = resolve2(io.cwd, file);
+  else {
+    const dir = mkdtempSync(join6(tmpdir(), "clutor-bench-"));
+    cleanup = () => rmSync(dir, { recursive: true, force: true });
+    path = join6(dir, "bench.gguf");
+    io.err("No --file given: writing a test model of about 1 GiB to the temp folder (it will be deleted).");
+    await writeSyntheticGguf2(path, { arch: "qwen2moe", name: "bench-moe", layers: 8, embedding: 1024, heads: 16, kvHeads: 4, contextLength: 4096, expertCount: 32, expertsUsed: 4, expertFfn: 1024, denseFfn: 0, vocab: 4096, sharedExperts: 0 });
+  }
+  try {
+    const r = await fileReader3(path);
+    const layout = buildModelLayout3(await parseGguf3(r));
+    await r.close();
+    if (!layout.expertCount) throw new UsageError("this model has no experts; bench measures expert-sized reads");
+    const m = await measureExpertReads2(path, layout, h.totalRamBytes, 96);
+    const dm = diskModelFrom(m, expertSizeBytes2(layout), layout.layers.find((l) => l.experts.length)?.experts[0]?.length ?? 1);
+    const bin = findEngine();
+    if (flagBool(args, "engine") && !bin) throw new UsageError("the native engine is not built: run `clutor engine build` (needs a C compiler)");
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const cmp = bin ? await compareStrategies(bin, path, flagInt(args, "cache-mb", 1, 1e6) ?? Math.max(64, Math.floor(h.totalRamBytes / 2 ** 20 / 16)), flagInt(args, "tokens", 10, 1e5) ?? 300, flagString(args, "dense"), computeFlag(args)) : void 0;
+    if (json) {
+      io.out(JSON.stringify({ measurement: m, diskModel: dm, ...cmp ? { engine: cmp } : {} }, null, 2));
+      return 0;
+    }
+    io.out(`${m.samples} random expert reads from ${path} (${fmtBytes(m.fileBytes)}):`);
+    io.out(table([["throughput", `${(m.bytesPerSec / 2 ** 30).toFixed(2)} GiB/s`], ["mean per expert", `${(m.meanReadSec * 1e3).toFixed(2)} ms`], ["95th percentile", `${(m.p95ReadSec * 1e3).toFixed(2)} ms`], ["modelled request overhead", `${(dm.requestLatencySec * 1e6).toFixed(0)} us`]]));
+    io.out("");
+    io.out(m.likelyCold ? "The file is larger than 1.5x your RAM, so most reads came from the SSD." : `! The file (${fmtBytes(m.fileBytes)}) is not much bigger than your RAM (${fmtGiB2(h.totalRamBytes)}), so the operating system's cache probably served many of these reads. Treat this as an upper bound; run it on your real model file for a true figure.`);
+    io.out(`Use it: clutor plan <model> --disk ${(m.bytesPerSec / 2 ** 30).toFixed(1)}`);
+    if (cmp) io.out(`
+${formatComparison(cmp)}`);
+    if (cmp && flagBool(args, "receipt")) {
+      const dir = resolve2(io.cwd, flagString(args, "dir") ?? ".");
+      const signer = await loadOrCreateReceiptSigner3(dir);
+      const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const brief = cmp.map((x) => `${x.name}: hit ${(x.report.totals.hitRate * 100).toFixed(1)}%, ${x.report.totals.missesPerToken.toFixed(1)} misses/token, ${x.report.totals.tokensPerSecond.toFixed(2)} passes/s`).join(" | ");
+      const first = cmp[0].report;
+      const rc = await sealReceipt2(signer, { v: 2, id: `bench_${Date.now().toString(36)}`, task: `bench ${path.split("/").pop()} (${first.model.layers} layers x ${first.model.experts} experts, top-${first.model.expertsUsed}, ${first.config.cacheSlots} cached, ${first.config.tokens} tokens, synthetic routing, peak RSS ${(Math.max(...cmp.map((x) => x.report.rss.peakBytes)) / 2 ** 20).toFixed(0)} MiB) -> ${brief}`, model: first.model.name, startedAt, finishedAt, status: "finished", files: [], commands: [], steps: cmp.length, previous: await lastReceiptTag3(dir) });
+      await appendReceipt3(dir, rc);
+      io.out(`
+Signed receipt ${rc.tag}
+Verify it with: clutor receipt verify ${rc.tag} ${dir}`);
+    }
+    if (!cmp) io.out("\nThe native engine is not built, so cache and prefetch strategies were not compared. Build it with: clutor engine build");
+    return 0;
+  } finally {
+    cleanup?.();
+  }
+}
+async function startBackendIfConfigured(config, io, existing) {
+  if (config.backend.kind !== "llama-server") return void 0;
+  const ls = config.backend.llamaServer;
+  if (!ls.model) {
+    io.err("backend.llamaServer.model is not set, so no model is loaded.");
+    return void 0;
+  }
+  const binary = ls.binary ?? findLlamaServer();
+  if (!binary) throw new ConfigError("llama-server was not found. Install llama.cpp (for example `brew install llama.cpp`) or set backend.llamaServer.binary.");
+  const caps = await probeLlamaServer(binary);
+  const r = await fileReader3(ls.model);
+  let layout;
+  try {
+    layout = buildModelLayout3(await parseGguf3(r));
+  } finally {
+    await r.close();
+  }
+  const h = hostInfo3();
+  const p = planMemory3(layout, { hostRamBytes: h.totalRamBytes, contextTokens: config.memory.contextTokens, kvBits: config.memory.kvBits });
+  const { args, notes } = buildLlamaArgs({ modelPath: ls.model, port: ls.port, contextTokens: config.memory.contextTokens, kvBits: config.memory.kvBits, ...ls.threads ? { threads: ls.threads } : {}, plan: p, caps, extraArgs: ls.extraArgs, ...config.agent.prefixSnapshots ? { slotSavePath: ensureSlotDir() } : {} });
+  for (const n of notes) io.err(`note: ${n}`);
+  io.err(`Loading ${ls.model} (this can take minutes for a large model)...`);
+  const b = existing ?? new BackendManager(ls.port);
+  await b.start(binary, args);
+  io.err("Model ready.");
+  return b;
+}
+async function serve(io, args, dirArg) {
+  const { config, root } = cfgFor(args, io, dirArg);
+  const port = flagInt(args, "port", 0, 65535);
+  const folders = [.../* @__PURE__ */ new Set([root, ...flagString(args, "folder") ? [resolve2(io.cwd, flagString(args, "folder"))] : []])];
+  const backend = config.backend.kind === "llama-server" ? new BackendManager(config.backend.llamaServer.port) : void 0;
+  if (backend && !flagBool(args, "no-start")) await startBackendIfConfigured(config, io, backend);
+  const server = createClutorServer({
+    root,
+    config: { ...config, ...port !== void 0 ? { port } : {} },
+    version: version(),
+    ...backend ? { backend, startBackend: async () => void await startBackendIfConfigured(config, { ...io, out: () => void 0 }, backend) } : {},
+    roots: folders,
+    log: (l) => io.err(l)
+  });
+  const a = await server.listen();
+  const base = `http://${a.host === "::" ? "localhost" : a.host}:${a.port}`;
+  io.out(`Clutor ${version()} listening on ${base}`);
+  io.out(`  OpenAI API   ${base}/v1       Ollama API   ${base}`);
+  io.out(`  Agent, MCP   ${base}/api/agent/run   ${base}/api/mcp   (need the token below)`);
+  io.out(`  Token        ${server.token}`);
+  io.out(`  Folders      ${folders.join(", ")}`);
+  io.out(`  Backend      ${config.backend.kind}${backend?.state === "ready" ? " (loaded)" : ""}`);
+  await new Promise((res) => {
+    const stop = () => res();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  await server.close();
+  return 0;
+}
+async function backendCmd(io, args) {
+  const { config } = cfgFor(args, io);
+  const binary = config.backend.llamaServer.binary ?? findLlamaServer();
+  if (!binary) {
+    io.err("llama-server was not found on PATH. Install llama.cpp (for example `brew install llama.cpp`), or set backend.llamaServer.binary.");
+    return 1;
+  }
+  const caps = await probeLlamaServer(binary);
+  io.out(`llama-server: ${binary}`);
+  io.out(`Supports: ${["--jinja", "--cache-type-k", "--flash-attn", "--mlock", "--no-mmap"].map((f) => `${f} ${caps.flags.has(f) ? "yes" : "no"}`).join(", ")}`);
+  const model = flagString(args, "model") ?? config.backend.llamaServer.model;
+  if (!model) {
+    io.out("Pass --model <file.gguf> to see the command clutor would run.");
+    return 0;
+  }
+  const r = await fileReader3(resolve2(io.cwd, model));
+  let layout;
+  try {
+    layout = buildModelLayout3(await parseGguf3(r));
+  } finally {
+    await r.close();
+  }
+  const p = planMemory3(layout, { hostRamBytes: hostInfo3().totalRamBytes, contextTokens: config.memory.contextTokens, kvBits: config.memory.kvBits });
+  const { args: a, notes } = buildLlamaArgs({ modelPath: resolve2(io.cwd, model), port: config.backend.llamaServer.port, contextTokens: config.memory.contextTokens, kvBits: config.memory.kvBits, plan: p, caps, extraArgs: config.backend.llamaServer.extraArgs });
+  io.out(`
+${binary} ${a.map((x) => /\s/.test(x) ? JSON.stringify(x) : x).join(" ")}`);
+  for (const n of notes) io.out(`note: ${n}`);
+  return 0;
+}
+function contextCharsFor(contextTokens) {
+  return Math.floor(contextTokens * 2.5);
+}
+async function code(io, args, task, session) {
+  if (!task.trim()) throw new UsageError('usage: clutor code "<what to do>" [--dir folder]');
+  const { config, root } = cfgFor(args, io);
+  const dir = resolve2(io.cwd, flagString(args, "dir") ?? ".");
+  if (!existsSync(dir)) throw new UsageError(`${dir} does not exist`);
+  const backend = session ? session.backend ??= await startBackendIfConfigured(config, io) : await startBackendIfConfigured(config, io);
+  try {
+    const llm = llmFrom(config, backend);
+    const project = new NodeProject3(dir);
+    const ws = new ShadowWorkspace3(project);
+    const auto = flagBool(args, "yes") || config.agent.autoApproveProjectCommands || session?.auto === true;
+    if (auto) io.err("note: commands that run project code will run without asking (--yes). Only do this for projects you trust.");
+    const key = await loadOrCreateReceiptSigner3(dir);
+    const verifyFlag = flagString(args, "verify") ?? session?.verify;
+    const verify = verifyFlag ?? config.agent.verifyCommand;
+    const show = (e) => {
+      if (e.type === "thought") io.out(`  ${e.text.split("\n")[0]?.slice(0, 200)}`);
+      else if (e.type === "tool_call") io.out(`> ${e.name} ${JSON.stringify(e.args).slice(0, 160)}`);
+      else if (e.type === "tool_result") io.out(`  ${e.ok ? "ok" : "failed"}: ${e.output.split("\n")[0]?.slice(0, 200)}`);
+      else if (e.type === "invalid") io.out(`  (invalid reply: ${e.error})`);
+      else if (e.type === "verify") io.out(`  verify ${!e.ran ? "NOT RUN" : e.ok ? "passed" : "FAILED"}${e.attempt > 0 ? ` (after ${e.attempt} retr${e.attempt === 1 ? "y" : "ies"})` : ""}: ${e.command}${!e.ran ? ` (${e.output.split("\n")[0]})` : ""}`);
+    };
+    const result = await runAgent2({
+      task,
+      llm,
+      ws,
+      maxSteps: flagInt(args, "max-steps", 1, 200) ?? config.agent.maxSteps,
+      contextChars: contextCharsFor(config.memory.contextTokens),
+      ...verify ? { verifyCommand: verify } : {},
+      ...session?.notes.length ? { systemExtra: `Earlier in this session (for context only):
+${session.notes.slice(-6).map((n) => `- ${n}`).join("\n")}` } : {},
+      onEvent: show,
+      runCommand: scratchRunner2(project, ws, { timeoutMs: config.agent.commandTimeoutSeconds * 1e3 }),
+      approve: async ({ command, network }) => {
+        if (auto) return true;
+        if (verifyFlag !== void 0 && command === verifyFlag) return true;
+        if (!io.prompt) return false;
+        const a = await io.prompt(`Run \`${command}\`${network ? " (uses the network)" : ""} in a scratch copy of the project? [y/N] `);
+        return /^y(es)?$/i.test(a.trim());
+      },
+      receipt: { signer: key, previous: await lastReceiptTag3(dir) }
+    });
+    if (result.receipt) await appendReceipt3(dir, result.receipt);
+    if (session) {
+      session.usage.promptTokens += result.usage.promptTokens;
+      session.usage.completionTokens += result.usage.completionTokens;
+      session.notes.push(`"${task.slice(0, 120)}" -> ${result.status}: ${result.summary.slice(0, 200)}`);
+    }
+    io.out("");
+    io.out(`${result.status}: ${result.summary}`);
+    for (const d of result.diffs) io.out(`
+${d.patch || `${d.status} ${d.path}`}`);
+    io.out(`
+${result.diffs.length} file${result.diffs.length === 1 ? "" : "s"} changed, ${result.steps} steps, ${result.invalidReplies} invalid replies, ${result.violations} blocked attempts.`);
+    if (result.verification) io.out(`Final check \`${result.verification.command}\`: ${!result.verification.ran ? "NOT RUN" : result.verification.ok ? "passed" : "FAILED"}${result.verification.retries ? ` (${result.verification.retries} self-heal ${result.verification.retries === 1 ? "turn" : "turns"})` : ""}`);
+    if (result.diffs.length === 0) return result.status === "finished" ? 0 : 1;
+    if (verifyFlag !== void 0 && !(result.verification?.ok === true)) {
+      io.out(`Nothing was written: the check \`${verifyFlag}\` ${result.verification && !result.verification.ran ? "was not run" : "did not pass"}. The diff above is what the agent proposed.`);
+      return 1;
+    }
+    let apply = flagBool(args, "apply");
+    if (!apply && io.prompt) apply = /^y(es)?$/i.test((await io.prompt("Apply these changes to the folder? [y/N] ")).trim());
+    if (!apply) {
+      io.out("Nothing was written. Run again with --apply to write the changes.");
+      return result.status === "finished" ? 0 : 1;
+    }
+    try {
+      const r = await applyChanges2(project, await ws.changeSet());
+      if (session) session.lastCheckpoint = { id: r.id, dir };
+      io.out(`Applied ${r.applied.length} files. Undo with: ${session ? "/undo" : `clutor rollback ${r.id} --dir ${dir}`}`);
+    } catch (e) {
+      if (e instanceof ConflictError3) {
+        io.err(`${e.message}
+Nothing was written.`);
+        return 1;
+      }
+      throw e;
+    }
+    return result.status === "finished" ? 0 : 1;
+  } finally {
+    if (!session) await backend?.stop();
+    void root;
+  }
+}
+async function receipts(io, args, dirArg, json) {
+  const dir = resolve2(io.cwd, dirArg ?? flagString(args, "dir") ?? ".");
+  const v = await verifyReceiptLog3(dir);
+  const all = await readReceipts2(dir);
+  const cps = await listCheckpoints2(new NodeProject3(dir));
+  if (json) {
+    io.out(JSON.stringify({ verification: v, receipts: all, checkpoints: cps }, null, 2));
+    return v.ok ? 0 : 1;
+  }
+  io.out(v.ok ? `Receipt chain intact: ${v.count} receipt${v.count === 1 ? "" : "s"}, hash chain and ECDSA signatures verified${v.keyIds.length ? ` (key id ${v.keyIds.join(", ")})` : ""}.` : `Receipt chain BROKEN at entry ${v.index}: ${v.reason}`);
+  if (all.length) io.out(table(all.slice(-15).map((r) => [r.finishedAt.slice(0, 19), r.status, `${r.files.length} files`, r.task.slice(0, 50)]), ["finished", "status", "changed", "task"]));
+  if (cps.length) io.out(`
+Checkpoints:
+${table(cps.slice(0, 10).map((c) => [c.id, c.createdAt.slice(0, 19), `${c.files} files`]))}`);
+  return v.ok ? 0 : 1;
+}
+async function rollback(io, args, id) {
+  if (!id) throw new UsageError("usage: clutor rollback <checkpoint id> [--dir folder]");
+  const project = new NodeProject3(resolve2(io.cwd, flagString(args, "dir") ?? "."));
+  try {
+    const r = await rollbackCheckpoint2(project, id, { force: flagBool(args, "force") });
+    io.out(`Restored ${r.length} files.`);
+    return 0;
+  } catch (e) {
+    if (e instanceof ConflictError3) {
+      io.err(`${e.message}
+Use --force to restore anyway.`);
+      return 1;
+    }
+    throw e;
+  }
+}
+async function doctor(io, args, dirArg, json) {
+  const h = hostInfo3();
+  const checks = [];
+  const add = (level, text) => void checks.push({ level, text });
+  add(Number(h.nodeVersion.split(".")[0]) >= 20 ? "ok" : "fail", `Node.js ${h.nodeVersion}`);
+  add("ok", `${h.platformName} ${h.arch}, ${h.cpuModel}, ${h.logicalCores} cores, ${fmtGiB2(h.totalRamBytes)} RAM`);
+  if (h.totalRamBytes < 8 * GiB3) add("warn", "Under 8 GiB of RAM: only small models will run comfortably, and large mixture-of-experts models will be very slow.");
+  let cfg;
+  let root = resolve2(io.cwd, dirArg ?? ".");
+  try {
+    const l = cfgFor(args, io, dirArg);
+    cfg = l.config;
+    root = l.root;
+    add(l.path ? "ok" : "info", l.path ? `Configuration ${l.path}` : `No ${CONFIG_FILE}: using defaults (run clutor init)`);
+  } catch (e) {
+    add("fail", e instanceof Error ? e.message : String(e));
+  }
+  const ls = findLlamaServer(process.env, cfg?.backend.llamaServer.binary ? [dirname2(cfg.backend.llamaServer.binary)] : []);
+  add(ls ? "ok" : "warn", ls ? `llama-server at ${ls}` : "llama-server not found (install llama.cpp to run models; the planner, simulator and agent tools still work)");
+  const eng = findEngine();
+  add(eng ? "ok" : "info", eng ? `Native engine at ${eng}` : "Native engine not built (clutor engine build): cache and prefetch strategies cannot be measured without it");
+  if (cfg) {
+    const local = await listLocalModels(resolve2(root, cfg.models));
+    add(local.length ? "ok" : "info", `${local.length} .gguf file${local.length === 1 ? "" : "s"} in ${resolve2(root, cfg.models)}`);
+    if (cfg.backend.kind === "none") add("info", "No model backend configured: chat and the agent need one (backend.kind in the configuration).");
+    if (cfg.backend.kind === "openai" && !cfg.backend.baseUrl) add("fail", "backend.kind is openai but backend.baseUrl is missing");
+    if (cfg.backend.kind === "llama-server" && !cfg.backend.llamaServer.model) add("fail", "backend.kind is llama-server but backend.llamaServer.model is missing");
+    if (cfg.agent.autoApproveProjectCommands) add("warn", "agent.autoApproveProjectCommands is on: commands that run project code run without asking.");
+    if (cfg.host !== "127.0.0.1" && cfg.host !== "localhost") add("warn", `The server listens on ${cfg.host}: anyone who can reach it and learns the token can have the agent edit files.`);
+  }
+  if (json) {
+    io.out(JSON.stringify(checks, null, 2));
+    return checks.some((c) => c.level === "fail") ? 1 : 0;
+  }
+  const tag = { ok: "ok  ", info: "info", warn: "warn", fail: "FAIL" };
+  for (const c of checks) (c.level === "fail" ? io.err : io.out)(`${tag[c.level]}  ${c.text}`);
+  return checks.some((c) => c.level === "fail") ? 1 : 0;
+}
+function modelEndpoint(config, backend) {
+  const b = config.backend;
+  if (b.kind === "openai" && b.baseUrl) return { baseUrl: b.baseUrl, model: b.model ?? "default", ...b.apiKeyEnv && process.env[b.apiKeyEnv] ? { apiKey: process.env[b.apiKeyEnv] } : {} };
+  if (backend) return { baseUrl: backend.baseUrl, model: "local" };
+  throw new ConfigError('no model is configured. In clutor.config.json set backend.kind to "openai" (with baseUrl) or "llama-server" (with llamaServer.model).');
+}
+function llmFrom(config, backend) {
+  const e = modelEndpoint(config, backend);
+  return agentLlm(config, { ...e, local: config.backend.kind === "llama-server" });
+}
+async function chat(io, args) {
+  const { config } = cfgFor(args, io);
+  const backend = await startBackendIfConfigured(config, io);
+  try {
+    const llm = new OpenAiCompatibleClient2({ ...modelEndpoint(config, backend), toolMode: "json" });
+    const history = [];
+    const system = flagString(args, "system");
+    if (system) history.push({ role: "system", content: system });
+    const turn = async (text) => {
+      history.push({ role: "user", content: text });
+      const t0 = Date.now();
+      const r = await llm.chat(history);
+      const reply = r.content ?? "";
+      history.push({ role: "assistant", content: reply });
+      io.out(reply);
+      const secs = (Date.now() - t0) / 1e3;
+      const gen = r.usage?.completionTokens;
+      io.err(`[${secs.toFixed(1)} s${gen ? `, ${gen} tokens, ${(gen / secs).toFixed(2)} tok/s measured end to end` : ""}]`);
+    };
+    const one = flagString(args, "prompt");
+    if (one !== void 0) {
+      await turn(one);
+      return 0;
+    }
+    if (!io.prompt) throw new UsageError('chat needs a terminal, or --prompt "<text>"');
+    io.out("clutor chat. /help lists the commands, /exit leaves.");
+    for (; ; ) {
+      const line = (await io.prompt("clt> ")).trim();
+      if (!line) continue;
+      if (line === "/exit" || line === "/quit") return 0;
+      if (line === "/layers" || line === "/cache") {
+        try {
+          await engineSlashCommand(io, config, line.slice(1));
+        } catch (e) {
+          io.err(e instanceof Error ? e.message : String(e));
+        }
+        continue;
+      }
+      if (line === "/help") {
+        io.out("/layers  where the model file's bytes are, per layer\n/cache   a streaming pass over the model file: cache, prefetch and disk waits (native engine)\n/reset   clear the conversation\n/exit    leave");
+        continue;
+      }
+      if (line === "/reset") {
+        history.length = system ? 1 : 0;
+        io.out("(conversation cleared)");
+        continue;
+      }
+      try {
+        await turn(line);
+      } catch (e) {
+        io.err(e instanceof Error ? e.message : String(e));
+      }
+    }
+  } finally {
+    await backend?.stop();
+  }
+}
+async function decide(io, args, json) {
+  const prompt = flagString(args, "prompt");
+  const choices = (flagString(args, "choices") ?? "").split(",").map((c) => c.trim()).filter(Boolean);
+  if (!prompt || choices.length < 2 || choices.length > 26) throw new UsageError('usage: clutor decide --prompt "<text>" --choices "approve,reject,escalate"  (2 to 26 choices)');
+  const { config } = cfgFor(args, io);
+  const backend = await startBackendIfConfigured(config, io);
+  try {
+    const out = await runDecide(modelEndpoint(config, backend), prompt, choices);
+    if (json) io.out(JSON.stringify(out, null, 2));
+    else {
+      io.out(`Decision: ${out.choice}`);
+      choices.forEach((c) => io.out(`  ${c.padEnd(Math.max(...choices.map((x) => x.length)))}  ${"#".repeat(Math.round(out.probabilities[c] * 30)).padEnd(30)} ${pct(out.probabilities[c])}`));
+      io.out(`(the model put ${pct(out.probabilityMassOnChoices)} of its first-token probability on these letters; not a calibrated confidence; ${out.latencyMs} ms)`);
+    }
+    return 0;
+  } finally {
+    await backend?.stop();
+  }
+}
+async function status(io, args, dirArg, json) {
+  const h = hostInfo3();
+  const { config, root, path } = cfgFor(args, io, dirArg);
+  const local = await listLocalModels(resolve2(root, config.models));
+  const ls = findLlamaServer(process.env, config.backend.llamaServer.binary ? [dirname2(config.backend.llamaServer.binary)] : []);
+  const v = await verifyReceiptLog3(root);
+  const s = { host: `${h.platformName} ${h.arch}, ${h.cpuModel}, ${h.logicalCores} cores`, ramBytes: h.totalRamBytes, configuration: path ?? null, backend: config.backend.kind, llamaServer: ls ?? null, models: local.length, receipts: v };
+  if (json) {
+    io.out(JSON.stringify(s, null, 2));
+    return 0;
+  }
+  io.out(`Host        ${s.host}, ${fmtGiB2(h.totalRamBytes)} RAM`);
+  io.out(`Config      ${path ?? "none (defaults)"}`);
+  io.out(`Backend     ${config.backend.kind}${ls ? `, llama-server at ${ls}` : ", llama-server not found"}`);
+  io.out(`Models      ${local.length} .gguf file${local.length === 1 ? "" : "s"} in ${resolve2(root, config.models)}`);
+  io.out(`Receipts    ${v.ok ? `intact (${v.count})` : `BROKEN at entry ${v.index}`}`);
+  return 0;
+}
+async function receiptVerify(io, args, sub, target, dirArg) {
+  if (sub === "key") {
+    const dir = resolve2(io.cwd, target ?? flagString(args, "dir") ?? ".");
+    const signer = await loadOrCreateReceiptSigner3(dir);
+    io.out(`Key id  ${await keyThumbprint(signer.publicJwk)}`);
+    io.out(`Public key (share this; keep ${join6(".clutor", "keys")} private):
+${JSON.stringify(signer.publicJwk, null, 2)}`);
+    return 0;
+  }
+  if (sub !== "verify" || !target) throw new UsageError("usage: clutor receipt verify <clt_token | receipts.jsonl> [dir] [--key-id <id> | --pubkey <file.json>]   or   clutor receipt key [dir]");
+  let trusted;
+  const keyId = flagString(args, "key-id");
+  const pubkey = flagString(args, "pubkey");
+  if (keyId) trusted = [keyId];
+  if (pubkey) trusted = [...trusted ?? [], await keyThumbprint(JSON.parse(readFileSync(resolve2(io.cwd, pubkey), "utf8")))];
+  const isToken = target.startsWith("clt_");
+  let all;
+  if (isToken) all = await readReceipts2(resolve2(io.cwd, dirArg ?? flagString(args, "dir") ?? "."));
+  else all = readFileSync(resolve2(io.cwd, target), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+  const v = await verifyReceiptChain(all, trusted ? { trustedKeyIds: trusted } : {});
+  if (!v.ok) {
+    io.err(`INVALID at entry ${v.index}: ${v.reason}`);
+    return 1;
+  }
+  const found = isToken ? all.find((r) => r.tag === target) : void 0;
+  if (isToken && !found) {
+    io.err("That receipt is not in this log.");
+    return 1;
+  }
+  io.out(isToken && found ? `Valid: ${found.status} "${found.task.slice(0, 60)}" at ${found.finishedAt}, ${found.files.length} files, signed by ${found.keyId}.` : `Valid: ${all.length} receipt${all.length === 1 ? "" : "s"}, chain and ECDSA signatures check out.`);
+  if (isToken && found) {
+    const { tag, ...body } = found;
+    io.out(`Decoded payload (this is exactly what the signature covers):
+${JSON.stringify(body, null, 2)}
+Signature tag: ${tag}`);
+  }
+  io.out(`Signed by key${v.keyIds.length === 1 ? "" : "s"}: ${v.keyIds.join(", ") || "none"}`);
+  io.out(trusted ? "The signing key is one you trust." : "No --key-id or --pubkey given: this shows the log is consistent and unedited, not whose key signed it.");
+  return 0;
+}
+async function pull(io, args, id) {
+  const { config, root } = cfgFor(args, io);
+  const dir = resolve2(root, config.models);
+  if (!id) {
+    io.out(table(DOWNLOADS.map((d2) => [d2.id, fmtBytes(d2.bytes), d2.repo, d2.note]), ["id", "size", "from", "what it is"]));
+    io.out("\nDownload one with: clutor pull <id>");
+    return 0;
+  }
+  const d = DOWNLOADS.find((x) => x.id === id);
+  if (!d) throw new UsageError(`unknown download "${id}"; run clutor pull to see the list`);
+  const dest = join6(dir, d.file);
+  if (existsSync(dest)) {
+    io.out(`${dest} is already there.`);
+    return 0;
+  }
+  if (!flagBool(args, "yes")) {
+    if (!io.prompt) throw new UsageError(`this downloads ${fmtBytes(d.bytes)} from huggingface.co; run again with --yes to confirm`);
+    if (!/^y(es)?$/i.test((await io.prompt(`Download ${d.file} (${fmtBytes(d.bytes)}) from huggingface.co to ${dir}? [y/N] `)).trim())) {
+      io.out("Nothing downloaded.");
+      return 0;
+    }
+  }
+  let last = 0;
+  const bytes = await downloadFile(downloadUrl(d), dest, { expectedBytes: d.bytes, onProgress: (done, total) => {
+    const p = Math.floor(done / total * 10);
+    if (p > last) {
+      last = p;
+      io.err(`  ${p * 10}%`);
+    }
+  } });
+  io.out(`Saved ${dest} (${fmtBytes(bytes)}).`);
+  return 0;
+}
+function shiftFlag(args) {
+  const v = flagString(args, "shift");
+  if (v === void 0) return {};
+  const m = /^(\d+),(\d+)$/.exec(v);
+  if (!m || Number(m[2]) < 1) throw new UsageError("--shift wants AT,LEN, for example 80,10: measured tokens AT..AT+LEN-1 are uniform scan noise");
+  return { shift: { at: Number(m[1]), len: Number(m[2]) } };
+}
+function computeFlag(args) {
+  const c = flagString(args, "compute");
+  if (c !== void 0 && c !== "kernel" && c !== "checksum") throw new UsageError("--compute must be kernel or checksum");
+  return c;
+}
+async function compareStrategies(bin, file, cacheMb, tokens, dense, compute) {
+  const common = { dense: dense ?? "auto", ...compute ? { compute } : {}, tokens, warmup: Math.min(50, Math.floor(tokens / 5)), cacheMb, seed: 1, noOsCache: true };
+  const runs = [
+    ["LRU, no prefetch", { ...common, policy: "lru", prefetch: false, ioThreads: 1 }],
+    ["adaptive cache + prefetch", { ...common, policy: "adaptive", prefetch: true, ioThreads: 2 }],
+    ["+ smart-route (2,12,0.015)", { ...common, policy: "adaptive", prefetch: true, ioThreads: 2, smart: "2,12,0.015" }]
+  ];
+  const out = [];
+  for (const [name, o] of runs) out.push({ name, report: await engineStream(bin, file, o) });
+  return out;
+}
+function formatComparison(c) {
+  const r0 = c[0]?.report;
+  if (!r0) return "";
+  const gb = (x) => `${x.totals.gbPerToken.toFixed(3)}`;
+  const rows = [
+    ["hit rate", ...c.map((x) => pct(x.report.totals.hitRate))],
+    ["misses per token", ...c.map((x) => x.report.totals.missesPerToken.toFixed(1))],
+    ["GB read per token", ...c.map((x) => gb(x.report))],
+    ["time waiting for disk (s)", ...c.map((x) => x.report.totals.ioWaitSeconds.toFixed(2))],
+    ["wall time (s)", ...c.map((x) => x.report.totals.wallSeconds.toFixed(2))],
+    ["passes per second", ...c.map((x) => x.report.totals.tokensPerSecond.toFixed(1))],
+    ["scan-pollution rejects (admission filter)", ...c.map((x) => String(x.report.totals.admitRejects))],
+    ["prefetch issued / late / unused", ...c.map((x) => `${x.report.totals.prefetchIssued} / ${x.report.totals.prefetchLate} / ${x.report.totals.prefetchWasted}`)],
+    ["prefetch hit / late (hits served by prefetch)", ...c.map((x) => `${x.report.totals.stageHits} / ${x.report.totals.prefetchLate}`)],
+    ["lookahead overlap (read time hidden)", ...c.map((x) => pct(x.report.totals.overlap))],
+    ["disk wait / compute time (s)", ...c.map((x) => `${x.report.totals.ioWaitSeconds.toFixed(2)} / ${x.report.totals.computeSeconds.toFixed(2)}`)],
+    ["substitutions per token", ...c.map((x) => (x.report.totals.substituted / Math.max(1, x.report.config.tokens)).toFixed(2))],
+    ["peak RSS of the engine (MiB, ru_maxrss)", ...c.map((x) => (x.report.rss.peakBytes / 2 ** 20).toFixed(0))],
+    ["substitutions (largest probability moved)", ...c.map((x) => `${x.report.totals.substituted} (${x.report.totals.maxDeltaP.toFixed(4)})`)]
+  ];
+  return [
+    `MEASURED by the native engine on this machine: ${r0.model.name}, ${r0.config.cacheSlots} experts cached (${(r0.config.cacheSlots * r0.model.expertBytes / 2 ** 20).toFixed(0)} MiB), ${r0.config.tokens} tokens after ${r0.config.warmup} warm-up; dense weights ${r0.config.denseMode === "resident" ? "resident" : "re-read every token"}.`,
+    `Disk reads, waits and cache behaviour are real. The routing is SYNTHETIC (a skewed random router with drifting topics), so hit rates here are not what a real model would see. ${r0.config.computeMode === "kernel" ? `The compute is a real Q4_0 x Q8_0 kernel (${r0.config.computeKernel}) run over every loaded byte, read as Q4_0 whatever its true type: genuine CPU work, not this model's maths.` : "The compute is a checksum, so this run measures I/O alone."}`,
+    table(rows, ["", ...c.map((x) => x.name)])
+  ].join("\n");
+}
+async function streamCmd(io, args, file, json) {
+  if (!file) throw new UsageError("usage: clutor stream <model.gguf> [--tokens N] [--cache-mb N] [--policy lru|wtinylfu|adaptive] [--smart J,M,TAU|off] [--prefetch on|off]");
+  const bin = findEngine();
+  if (!bin) throw new UsageError("the native engine is not built: run `clutor engine build` (needs a C compiler)");
+  const num = (n, lo, hi) => flagInt(args, n, lo, hi);
+  const pol = flagString(args, "policy");
+  if (pol && !["lru", "wtinylfu", "adaptive"].includes(pol)) throw new UsageError("--policy must be lru, wtinylfu or adaptive");
+  const dn = flagString(args, "dense");
+  if (dn && !["auto", "resident", "ring"].includes(dn)) throw new UsageError("--dense must be auto, resident or ring");
+  const pf = flagString(args, "prefetch");
+  if (pf && !["on", "off"].includes(pf)) throw new UsageError("--prefetch must be on or off");
+  const o = {
+    ...num("tokens", 1, 1e6) !== void 0 ? { tokens: num("tokens", 1, 1e6) } : {},
+    ...num("warmup", 0, 1e6) !== void 0 ? { warmup: num("warmup", 0, 1e6) } : {},
+    ...num("cache-mb", 1, 1e7) !== void 0 ? { cacheMb: num("cache-mb", 1, 1e7) } : {},
+    ...num("io-threads", 1, 16) !== void 0 ? { ioThreads: num("io-threads", 1, 16) } : {},
+    ...num("seed", 0, 2 ** 31) !== void 0 ? { seed: num("seed", 0, 2 ** 31) } : {},
+    ...pol ? { policy: pol } : {},
+    ...flagString(args, "smart") ? { smart: flagString(args, "smart") } : {},
+    ...pf ? { prefetch: pf === "on" } : {},
+    ...dn ? { dense: dn } : {},
+    ...computeFlag(args) ? { compute: computeFlag(args) } : {},
+    ...flagBool(args, "no-os-cache") ? { noOsCache: true } : {},
+    ...num("window", 1, 1e5) !== void 0 ? { window: num("window", 1, 1e5) } : {},
+    ...shiftFlag(args)
+  };
+  const path = resolve2(io.cwd, file);
+  if (!existsSync(path)) throw new UsageError(`${path} does not exist`);
+  const r = await engineStream(bin, path, o);
+  if (json) {
+    io.out(JSON.stringify(r, null, 2));
+    return 0;
+  }
+  io.out(describeStream(r));
+  return 0;
+}
+function describeStream(r) {
+  const t = r.totals;
+  const lines = [
+    `${r.model.name} (${r.model.arch}): ${r.model.layers} layers, ${r.model.experts} experts (${r.model.expertsUsed} used), ${(r.model.expertBytes / 2 ** 20).toFixed(2)} MiB each`,
+    `policy ${r.config.policy}, ${r.config.cacheSlots} cached + ${r.config.stageSlots} staged experts, smart-route ${r.config.smartRoute ? `on (J=${r.config.J}, M=${r.config.M}, tau=${r.config.tau})` : "off"}, prefetch ${r.config.prefetch ? "on" : "off"}, dense weights ${r.config.denseMode === "resident" ? `resident (${(r.config.densePreloadBytes / 2 ** 20).toFixed(0)} MiB read once)` : "re-read every token"}`,
+    `MEASURED  ${((t.demandBytes + t.prefetchBytes + t.denseBytes) / 1e9).toFixed(2)} GB read; waited ${t.ioWaitSeconds.toFixed(2)} s of ${t.wallSeconds.toFixed(2)} s; ${pct(t.overlap)} of read time overlapped with other work`,
+    `MEASURED  cache ${pct(t.hitRate)} hits (${t.stageHits} served by prefetch), ${t.missesPerToken.toFixed(1)} misses per token, ${t.admitRejects} admission rejects`,
+    `MEASURED  prefetch ${t.prefetchIssued} issued, ${t.prefetchLate} late, ${t.prefetchWasted} never used`
+  ];
+  if (r.config.smartRoute) lines.push(`MEASURED  smart-route ${t.substituted} substitutions; the largest probability moved was ${t.maxDeltaP.toFixed(4)} (limit ${r.config.tau})`);
+  lines.push(`MEASURED  peak resident memory of the engine process (ru_maxrss): ${(r.rss.peakBytes / 2 ** 20).toFixed(1)} MiB; COMPUTED from the buffers and tables it allocates: ${(r.rss.predictedBytes / 2 ** 20).toFixed(1)} MiB (${(r.rss.startBytes / 2 ** 20).toFixed(1)} MiB of that was there before the run)`);
+  if (r.windows.length) {
+    const note = r.scenario.shiftLen > 0 ? `; tokens ${r.scenario.shiftAt + 1}-${r.scenario.shiftAt + r.scenario.shiftLen} are uniform scan noise, the rest one tight topic` : "";
+    lines.push(`MEASURED  hit rate and peak RSS per window of tokens${note}:
+${table(r.windows.map((w, i) => [`${i ? r.windows[i - 1].tokEnd + 1 : 1}-${w.tokEnd}`, pct(w.accesses ? w.hits / w.accesses : 0), `${(w.peakRssBytes / 2 ** 20).toFixed(0)} MiB`]), ["tokens", "hit rate", "peak RSS"])}`);
+  }
+  lines.push(`${t.tokensPerSecond.toFixed(1)} passes per second over SYNTHETIC routing; the compute is ${r.config.computeMode === "kernel" ? `a Q4_0 x Q8_0 kernel (${r.config.computeKernel}) over the loaded bytes (${t.computeSeconds.toFixed(2)} s in total), not this model's maths` : "a checksum"}: this is not model tokens per second.`);
+  return lines.join("\n");
+}
+async function engineCmd(io, sub) {
+  if (sub === "where") {
+    const bin = findEngine();
+    io.out(bin ?? "not built (run: clutor engine build)");
+    return bin ? 0 : 1;
+  }
+  if (sub === "build") {
+    io.err("Compiling the native engine...");
+    try {
+      io.out(`Built ${await buildEngine()}`);
+      return 0;
+    } catch (e) {
+      if (e instanceof EngineError) {
+        io.err(e.message);
+        return 1;
+      }
+      throw e;
+    }
+  }
+  throw new UsageError("usage: clutor engine build | where");
+}
+async function engineSlashCommand(io, config, what) {
+  const file = config.backend.llamaServer.model;
+  const bin = findEngine();
+  if (!file) {
+    io.out("No model file is configured (backend.llamaServer.model), so there is nothing to describe.");
+    return;
+  }
+  if (!bin) {
+    io.out("The native engine is not built: run `clutor engine build`.");
+    return;
+  }
+  if (what === "layers") {
+    const info = await engineInfo(bin, file);
+    io.out(`${info.name} (${info.arch}): ${info.layers} layers, ${info.experts} experts (${info.expertsUsed} used)`);
+    const rows = info.layerTable.map((l, i) => [String(i), `${(l.denseBytes / 2 ** 20).toFixed(1)} MiB`, `${(l.expertBytes / 2 ** 20).toFixed(2)} MiB`, `${(l.routerBytes / 2 ** 10).toFixed(0)} KiB`]);
+    io.out(table(rows.length > 24 ? [...rows.slice(0, 12), ["...", "", "", ""], ...rows.slice(-6)] : rows, ["layer", "dense (read every token)", "one expert", "router (resident)"]));
+    return;
+  }
+  io.out("Running a short streaming pass over this model's file (synthetic routing; the chat itself is served by llama-server, which reports no cache data)...");
+  const r = await engineStream(bin, file, { tokens: 30, warmup: 5, cacheMb: 256, policy: "adaptive", prefetch: true, ioThreads: 2, noOsCache: true });
+  io.out(describeStream(r));
+  const worst = [...r.layers].filter((l) => l.accesses > 0).sort((a, b) => b.ioWaitSeconds - a.ioWaitSeconds).slice(0, 5);
+  io.out(`Layers that waited longest: ${worst.map((l) => `${l.layer} (${l.ioWaitSeconds.toFixed(2)} s, ${pct(l.hits / l.accesses)} hits)`).join(", ")}`);
+}
+
+export {
+  parseArgs,
+  flagString,
+  flagBool,
+  flagInt,
+  UsageError,
+  DecideError,
+  runDecide,
+  sealDecision,
+  findLlamaServer,
+  probeLlamaServer,
+  buildLlamaArgs,
+  BackendManager,
+  SlotSnapshots,
+  withPrefixSnapshots,
+  ModelError,
+  resolveModel,
+  listLocalModels,
+  DOWNLOADS,
+  downloadUrl,
+  DownloadError,
+  downloadFile,
+  parseSse,
+  toOpenAiBody,
+  fromOpenAiReply,
+  streamToOllama,
+  slotDir,
+  ensureSlotDir,
+  agentLlm,
+  handleMcp,
+  ConflictError,
+  AgentSession,
+  normaliseRoot,
+  isInside,
+  createClutorServer,
+  EngineError,
+  engineSourceDir,
+  findEngine,
+  run,
+  buildEngine,
+  engineInfo,
+  engineStream,
+  version,
+  main,
+  startBackendIfConfigured
+};
+//# sourceMappingURL=chunk-6WAEQCCP.js.map