premanmcp 1.1.4 → 1.1.6

package/bin/predict.js

@@ -0,0 +1,857 @@
+/**
+ * One command from a cold machine to an accuracy experiment streaming on screen.
+ *
+ * The pieces are individually simple and collectively easy to get wrong, which
+ * is the only reason this exists. Six things have to be true at once before a
+ * run is *visible*: Postgres has to be up, the API has to be up (it runs the
+ * migrations and the worker that executes the run in-process, so those are not
+ * separate steps), the dashboard has to be serving the working tree, the app
+ * has to be the from-source build pointed at this backend, it has to hold a
+ * session for the same account the run is filed under, and it has to already be
+ * on the Accuracy page.
+ *
+ * Miss any one and the run still happens correctly while showing you nothing.
+ * That is the failure this command exists to stop reproducing -- the account
+ * mismatch especially, which produces no error anywhere, just an empty page.
+ *
+ * Dev-only. It drives a checkout, so it refuses to run from a bare npm install
+ * rather than half-working from one.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const DEFAULT_BACKEND = "http://127.0.0.1:8000";
+const DASHBOARD_ORIGIN = "http://localhost:8080";
+const DESKTOP_PORT = "8790";
+const ACCURACY_ROUTE = "/workbench/workload/accuracy";
+// Where a forecast is read, and where the sources that fed it can be switched
+// off and the run repeated. A different page from the accuracy experiment
+// because they answer different questions: one is "how right is this thing",
+// the other is "what does it tell me to do, and on what evidence".
+const FORECAST_ROUTE = "/workbench/workload/forecast";
+const DEV_LOCAL = path.join(os.homedir(), ".preman", "dev-local.json");
+// Mirrors DEFAULT_SEEDS in flowtest/services/workload_eval_service.py.
+const DEFAULT_SEEDS = [11, 23, 37];
+
+export const PREDICT_HELP = `
+Predict options (local development; 'preman run --predict' works too):
+  --seeds <n|a,b,c>     How many seeds per regime, or the exact seeds to use
+  --regimes <a,b,c>     Only these regimes. Defaults to all of them
+  --train-days <n>      Days of history the forecaster learns from (default 14)
+  --test-days <n>       Days it is scored against (default 14)
+  --tiers [a,b,c]       Also score each access tier, to show what connecting
+                        more data actually buys. Bare flag means T1,T2,T3,T4
+  --backend <url>       Local backend. Defaults to ${DEFAULT_BACKEND}
+  --no-app              Skip the desktop app; stream to this terminal only
+  --app-only            Bring the stack and app up, but start no run
+  --show-inputs         Print what a run reads, and what it does not, then stop
+
+Forecast options (one forecast for this customer, rather than an accuracy run):
+  --forecast            Forecast instead of scoring, and open the app on the
+                        Forecast page, where every source has a switch
+  --without <a,b>       Run without these sources, to see what is lost. One or
+                        more of: reporting, logs, repository, infrastructure
+  --pack <key>          Which representation pack. Defaults to simula
+  --horizon <days>      How far ahead to forecast. Defaults to 90
+`;
+
+function say(message) {
+  process.stdout.write(`\n\u001b[36m==>\u001b[0m ${message}\n`);
+}
+
+function note(message) {
+  process.stdout.write(`    ${message}\n`);
+}
+
+function fail(message, code = 2) {
+  process.stderr.write(`\n${message}\n`);
+  return code;
+}
+
+/**
+ * The checkout this CLI is part of, or null when installed from the registry.
+ *
+ * Resolved from this file rather than from cwd so the command works from
+ * anywhere, and so a global `npm link` still finds the tree it was linked from.
+ */
+function resolveCheckout() {
+  const backendDir = path.resolve(__dirname, "..", "..");
+  const root = path.resolve(backendDir, "..");
+  const dashboardDir = path.join(root, "PreMan-Dashboard");
+  const desktopDir = path.join(root, "PreMan-API-Testing-tool", "desktop");
+  if (!fs.existsSync(path.join(backendDir, "api.py"))) return null;
+  return { root, backendDir, dashboardDir, desktopDir };
+}
+
+async function reachable(url, { headers = {}, timeoutMs = 2000 } = {}) {
+  try {
+    const response = await fetch(url, {
+      headers,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return response.status;
+  } catch {
+    return 0;
+  }
+}
+
+async function waitUntil(check, { seconds, label }) {
+  for (let attempt = 0; attempt < seconds; attempt += 1) {
+    if (await check()) return true;
+    if (attempt === 2) note(`still waiting for ${label}…`);
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+  return false;
+}
+
+/**
+ * Start something that has to outlive this command.
+ *
+ * `detached` so the child gets its own process group: without it the backend
+ * and dashboard die with the terminal the moment the run finishes, which is
+ * never what "bring the stack up" meant.
+ *
+ * ELECTRON_RUN_AS_NODE is stripped from every child, not just the app. Editors
+ * built on Electron -- Cursor, VS Code -- export it to their integrated
+ * terminals, and it turns any Electron binary into a plain Node process that
+ * runs no app, prints nothing, and exits 0 in under 100ms. Inherited, it makes
+ * the window silently never appear.
+ */
+function startDetached(command, args, { cwd, env = {}, logFile }) {
+  const childEnv = { ...process.env, ...env };
+  delete childEnv.ELECTRON_RUN_AS_NODE;
+  const out = fs.openSync(logFile, "a");
+  const child = spawn(command, args, {
+    cwd,
+    env: childEnv,
+    detached: true,
+    stdio: ["ignore", out, out],
+  });
+  child.unref();
+  return child;
+}
+
+function runSync(command, args, { cwd, env = {}, quiet = false } = {}) {
+  const childEnv = { ...process.env, ...env };
+  delete childEnv.ELECTRON_RUN_AS_NODE;
+  return spawnSync(command, args, {
+    cwd,
+    env: childEnv,
+    encoding: "utf8",
+    stdio: quiet ? "pipe" : ["ignore", "pipe", "pipe"],
+  });
+}
+
+async function ensureDatabase(backendDir) {
+  // `--wait db` rather than a bare `up -d`: the compose file also carries an
+  // api container on another port, and two APIs against one database is a
+  // confusing way to spend an afternoon. --wait blocks on the healthcheck, so
+  // the API never starts against a Postgres that is still opening its socket.
+  const result = runSync("docker", ["compose", "up", "-d", "--wait", "db"], {
+    cwd: backendDir,
+  });
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim().split("\n").slice(-3).join("\n");
+    throw new Error(`could not start Postgres:\n${detail}`);
+  }
+}
+
+async function ensureBackend(backendDir, backendUrl) {
+  if ((await reachable(`${backendUrl}/health`)) === 200) {
+    note(`already up on ${backendUrl}`);
+    return;
+  }
+  say("starting Postgres");
+  await ensureDatabase(backendDir);
+
+  say(`starting the API on ${backendUrl}`);
+  // api.py runs the migrations and the workload worker in-process during
+  // lifespan startup, so this one process is the whole backend: there is no
+  // separate migrate step to forget and no worker to start beside it.
+  const port = new URL(backendUrl).port || "8000";
+  startDetached("uv", ["run", "--no-sync", "python", "api.py"], {
+    cwd: backendDir,
+    env: { PORT: port },
+    logFile: "/tmp/preman-predict-api.log",
+  });
+  const up = await waitUntil(async () => (await reachable(`${backendUrl}/health`)) === 200, {
+    seconds: 90,
+    label: "the API",
+  });
+  if (!up) {
+    throw new Error(
+      `the API did not answer on ${backendUrl}/health within 90s.\n` +
+        `Its output is in /tmp/preman-predict-api.log`
+    );
+  }
+}
+
+/**
+ * One key decides two things that have to agree: which account the window logs
+ * into, and which account the run is filed under. When they disagree the run
+ * succeeds and the page stays empty, because the app is looking at a different
+ * tenant -- no error anywhere.
+ *
+ * So it is resolved once, here. ~/.preman/dev-local.json comes before dev.env's
+ * EVAL_API_KEY, which belongs to a different account and would send the window
+ * somewhere you are not. ~/.preman/credentials.json is deliberately not
+ * consulted: that one is for production.
+ */
+function resolveApiKey() {
+  const fromEnv = (process.env.PREMAN_API_KEY || "").trim();
+  if (fromEnv) return { key: fromEnv, origin: "PREMAN_API_KEY" };
+  if (fs.existsSync(DEV_LOCAL)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(DEV_LOCAL, "utf8"));
+      if (parsed?.api_key) return { key: String(parsed.api_key), origin: DEV_LOCAL };
+    } catch {
+      // A corrupt dev file is not worth a stack trace; fall through to the error.
+    }
+  }
+  return { key: "", origin: "" };
+}
+
+/**
+ * Prove the key works here *and* that the account owning it can see the
+ * product, before anything slow happens. A 402 is not an error to report at the
+ * end of a two-minute run.
+ */
+async function ensureEntitlement({ backendDir, backendUrl, key, email }) {
+  const status = await reachable(`${backendUrl}/workload/evals/regimes`, {
+    headers: { authorization: `Bearer ${key}` },
+  });
+  if (status === 200) return true;
+  if (status === 401) {
+    throw new Error(
+      `that key is not valid for ${backendUrl}.\n` +
+        `The key in ~/.preman/credentials.json is for production; this needs a local one.`
+    );
+  }
+  if (status !== 402) {
+    throw new Error(`${backendUrl}/workload/evals/regimes answered ${status || "nothing"}`);
+  }
+
+  say("granting this account the workload product");
+  // Gated per-account and off by default, so a fresh database always lands here
+  // once. Granting it by email rather than letting the script pick the oldest
+  // user is the whole point: the oldest user need not be the one signing in.
+  const args = ["run", "--no-sync", "python", "scripts/enable_workload_locally.py"];
+  if (email) args.push("--email", email);
+  const result = runSync("uv", args, { cwd: backendDir });
+  if (result.status !== 0) {
+    throw new Error(
+      `could not grant the workload product:\n${(result.stderr || result.stdout || "").trim()}`
+    );
+  }
+  note((result.stdout || "").trim().split("\n").pop() || "granted");
+  return (
+    (await reachable(`${backendUrl}/workload/evals/regimes`, {
+      headers: { authorization: `Bearer ${key}` },
+    })) === 200
+  );
+}
+
+async function ensureDashboard(dashboardDir) {
+  // /@vite/client rather than /: something unrelated may hold the port, and
+  // pointing the shell at it would put a stranger's app in a PreMan window.
+  // Only Vite serves that path, so it is the question worth asking.
+  const serving = async () => (await reachable(`${DASHBOARD_ORIGIN}/@vite/client`)) === 200;
+  if (await serving()) {
+    note(`already serving on ${DASHBOARD_ORIGIN}`);
+    return true;
+  }
+  say(`starting the dashboard on ${DASHBOARD_ORIGIN}`);
+  startDetached("npm", ["run", "dev"], {
+    cwd: dashboardDir,
+    logFile: "/tmp/preman-predict-dashboard.log",
+  });
+  const up = await waitUntil(serving, { seconds: 60, label: "Vite" });
+  if (!up) {
+    throw new Error(
+      `Vite did not come up on ${DASHBOARD_ORIGIN} within 60s.\n` +
+        `Its output is in /tmp/preman-predict-dashboard.log`
+    );
+  }
+  return true;
+}
+
+/**
+ * Hand the app a session, and learn which account it belongs to.
+ *
+ * Without this the window cold-starts on a login screen and makes no requests
+ * at all. The app consumes the file on read, so it is minted fresh on every
+ * launch rather than reused. The email it prints is the one fact that proves
+ * the window and the run will agree about who they are.
+ */
+function mintDesktopSession(backendDir, key) {
+  const result = runSync("uv", ["run", "--no-sync", "python", "scripts/dev_desktop_session.py"], {
+    cwd: backendDir,
+    env: { PREMAN_API_KEY: key },
+  });
+  const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+  if (result.status !== 0) throw new Error(`could not mint a desktop session:\n${output}`);
+  const email = output.match(/<([^>]+)>/)?.[1] || "";
+  return { email, line: output.split("\n").pop() || "" };
+}
+
+/**
+ * Restart the app on the Accuracy page, from source.
+ *
+ * From source rather than the installed build for two reasons: the release in
+ * /Applications predates this page, and only a from-source shell honours
+ * PREMAN_START_ROUTE. Pointed at Vite so the window runs the working tree with
+ * hot reload rather than a bundle that was current whenever it was built.
+ *
+ * Restarted rather than reused because a running instance cannot pick up new
+ * environment variables, and -9 because the app traps SIGTERM for a 15s cleanup
+ * phase while squatting the port the next one wants.
+ */
+async function restartDesktop({ desktopDir, backendUrl, route = ACCURACY_ROUTE }) {
+  spawnSync("pkill", ["-9", "-f", "PreMan.app/Contents/MacOS/PreMan"], { stdio: "ignore" });
+  spawnSync("pkill", ["-9", "-f", "desktop/node_modules/electron"], { stdio: "ignore" });
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+
+  const electron = path.join(desktopDir, "node_modules", ".bin", "electron");
+  if (!fs.existsSync(electron)) {
+    throw new Error(
+      `no electron in ${desktopDir}.\n` + `Run \`npm install\` there once, or pass --no-app.`
+    );
+  }
+  startDetached(electron, [desktopDir], {
+    cwd: desktopDir,
+    env: {
+      PREMAN_API_URL: backendUrl,
+      PREMAN_DEV_SERVER: DASHBOARD_ORIGIN,
+      PREMAN_DESKTOP_PORT: DESKTOP_PORT,
+      PREMAN_START_ROUTE: route,
+    },
+    logFile: "/tmp/preman-predict-app.log",
+  });
+  const up = await waitUntil(
+    async () => (await reachable(`http://127.0.0.1:${DESKTOP_PORT}/`)) > 0,
+    { seconds: 45, label: "the window" }
+  );
+  if (!up) {
+    note("the window did not answer in 45s; carrying on — /tmp/preman-predict-app.log has why");
+  }
+  return up;
+}
+
+/**
+ * What a run actually reads, said out loud.
+ *
+ * Worth its own flag because the honest answer is counter-intuitive and the
+ * intuitive answer is wrong in a way that wastes an afternoon: this reads no
+ * repository, no logs and no infrastructure. It runs from any directory and
+ * would behave identically from an empty one. The world comes from a pack
+ * declared out of Simula's public SDK, and the traffic from a seeded simulator
+ * -- which is what makes the scoring possible at all, since only a synthetic
+ * world has a ground truth to be scored against.
+ */
+async function showInputs({ backendUrl, key }) {
+  const authed = { headers: { authorization: `Bearer ${key}` } };
+  const packsResponse = await fetch(`${backendUrl}/workload/packs`, authed);
+  const regimesResponse = await fetch(`${backendUrl}/workload/evals/regimes`, authed);
+  if (!packsResponse.ok) {
+    throw new Error(`${backendUrl}/workload/packs answered ${packsResponse.status}`);
+  }
+  const { packs = [] } = await packsResponse.json();
+  const regimesBody = regimesResponse.ok ? await regimesResponse.json() : {};
+  const regimes = regimesBody.regimes || regimesBody || [];
+
+  say("what a run reads");
+  note("nothing from this directory: no repository, no logs, no cloud account.");
+  note("it would produce the same numbers run from an empty folder.");
+
+  for (const pack of packs) {
+    say(`the world: ${pack.label || pack.key}`);
+    if (pack.summary) note(pack.summary);
+    note(
+      `${pack.endpoints} endpoints, ${pack.drivers} drivers, ` +
+        `${pack.fanout_units} fan-out units, ${(pack.worlds || []).length} worlds`
+    );
+    if (pack.findings?.length) {
+      say("claims it makes about Simula, from their public SDK alone");
+      for (const finding of pack.findings) note(`- ${finding}`);
+    }
+    if (pack.open_questions?.length) {
+      say("what it does not know, and what would answer it");
+      for (const question of pack.open_questions) {
+        note(`- ${question.question}`);
+        if (question.answerable_at_tier) {
+          note(`  readable once you grant: ${question.answerable_at_tier}`);
+        }
+      }
+    }
+  }
+
+  say("the traffic: a seeded simulator, not a recording");
+  note("each regime is a world with a known answer, which is what makes scoring possible.");
+  for (const regime of regimes) {
+    note(`- ${regime.key || regime}: ${regime.label || ""}`);
+    if (regime.hypothesis) note(`  expects: ${regime.hypothesis}`);
+  }
+  return 0;
+}
+
+async function startEval({ backendUrl, key, body }) {
+  const response = await fetch(`${backendUrl}/workload/evals`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  if (response.status === 409) {
+    // The identical experiment is already in flight. Deduplicated on purpose --
+    // attaching to it is what the reader wanted anyway.
+    return { alreadyRunning: true };
+  }
+  if (!response.ok) {
+    throw new Error(`starting the experiment failed (${response.status}): ${text.slice(0, 400)}`);
+  }
+  return { run: JSON.parse(text) };
+}
+
+async function latestEval({ backendUrl, key }) {
+  const response = await fetch(`${backendUrl}/workload/evals/latest`, {
+    headers: { authorization: `Bearer ${key}` },
+  });
+  if (!response.ok) return null;
+  return response.json();
+}
+
+/**
+ * `--seeds 5` means five seeds, not the single seed 5.
+ *
+ * The API takes the seed values themselves, because which seeds were used is
+ * part of what makes a result reproducible. But nobody choosing how long to
+ * wait is thinking in seed values, they are thinking in "how many runs", so a
+ * bare count is expanded here and an explicit list is passed through for anyone
+ * reproducing a specific experiment.
+ */
+function parseSeeds(raw) {
+  const text = String(raw).trim();
+  if (text.includes(",")) {
+    return text.split(",").map((part) => Number(part.trim())).filter(Number.isFinite);
+  }
+  const count = Number(text);
+  if (!Number.isFinite(count) || count < 1) return DEFAULT_SEEDS.slice(0, 1);
+  // Extending the service's own defaults rather than inventing a parallel set,
+  // so `--seeds 3` reproduces exactly what a default run measured.
+  const seeds = [];
+  for (let index = 0; index < count; index += 1) {
+    seeds.push(DEFAULT_SEEDS[index] ?? DEFAULT_SEEDS[0] + index * 7);
+  }
+  return seeds;
+}
+
+/**
+ * Which access tiers to sweep, or null for the default single-tier run.
+ *
+ * Usable as a bare flag, because the whole ladder is what nearly everyone
+ * asking this question wants; a list is for narrowing it afterwards. The bare
+ * form is why this cannot read the next argument unconditionally:
+ * `--tiers --no-app` asked for a tier named "--NO-APP", which normalised to
+ * nothing and ran without the sweep. The run still succeeded and still printed
+ * a headline, so the only sign was one sentence from the analyst saying the
+ * sweep had not happened.
+ */
+export function tiersFromArgs(args) {
+  const index = args.indexOf("--tiers");
+  if (index < 0) return null;
+  const next = args[index + 1];
+  if (!next || next.startsWith("-")) return ["T1", "T2", "T3", "T4"];
+  return next
+    .split(",")
+    .map((part) => part.trim().toUpperCase())
+    .filter(Boolean);
+}
+
+/** Skill is a fraction of the available headroom, so 0.484 is 48%. */
+function percent(value) {
+  return value === null || value === undefined ? "n/a" : `${Math.round(Number(value) * 100)}%`;
+}
+
+/**
+ * Render one event as a line somebody would want to read.
+ *
+ * The runtime prefixes every event with `eval_`, including the two the service
+ * already named `eval_started` and `eval_finished` -- so those arrive as
+ * `eval_eval_started`. Normalised here rather than fixed there: the page reads
+ * these same names, and renaming a published event to tidy a prefix would break
+ * a reader to please a log.
+ *
+ * Unknown types print their name rather than being dropped, so a run that grows
+ * a new phase shows it here without this file needing an edit.
+ */
+function describeEvent(rawType, data) {
+  const type = String(rawType).replace(/^eval_/, "").replace(/^eval_/, "");
+  if (type === "started") {
+    return `measuring ${data.regimes?.length ?? "?"} regimes x ${data.seeds?.length ?? data.seeds ?? "?"} seeds`;
+  }
+  if (type === "ingested") {
+    return (
+      `ingested ${data.regime}: ${data.requests_total ?? "?"} requests over ` +
+      `${data.endpoints_seen ?? "?"} endpoints, ${data.train_days ?? "?"} days of history`
+    );
+  }
+  if (type === "regime_started") return `scoring ${data.regime}…`;
+  if (type === "regime_finished") {
+    const result = data.result || {};
+    // A regime whose baseline is already at the oracle floor has no accuracy
+    // left to win, and a skill figure computed against roughly zero headroom is
+    // noise. The scoring says so with skill_is_meaningful; quoting 0% there
+    // would read as "no better than the baseline" rather than "nothing to beat".
+    const skill =
+      result.skill_is_meaningful === false
+        ? "no headroom to beat"
+        : `${percent(result.skill_vs_baseline)} unaided, ${percent(result.skill_if_answered)} answered`;
+    // Always say whether the prediction held, never only when it failed.
+    // Some regimes are not scored on skill at all -- unmodelled_shock exists to
+    // check the model reports an unexplained residual rather than absorbing it
+    // -- so "no headroom to beat" alone reads as a dud result when it is
+    // actually the regime passing the test it was written for.
+    const held =
+      result.hypothesis_held === true
+        ? "  [hypothesis held]"
+        : result.hypothesis_held === false
+          ? "  [hypothesis did NOT hold]"
+          : "";
+    return `${result.label || data.regime}: ${skill}${held}`;
+  }
+  if (type === "reading") {
+    return data.ran ? "the analyst read the table" : `analyst skipped: ${data.reason || "no key"}`;
+  }
+  if (type === "finished") return "experiment finished";
+  return type;
+}
+
+/**
+ * Follow the run over the same stream the app reads.
+ *
+ * Terminal output is a courtesy here, not the deliverable -- the app is the
+ * deliverable -- so a stream that drops is reported and the command still exits
+ * on the run's real status, read back from the API.
+ */
+async function streamRun({ backendUrl, key, runId }) {
+  const response = await fetch(`${backendUrl}/workbench/automation-runs/${runId}/stream`, {
+    headers: { authorization: `Bearer ${key}`, accept: "text/event-stream" },
+  });
+  if (!response.ok || !response.body) {
+    note(`could not attach to the stream (${response.status}); the run continues regardless`);
+    return null;
+  }
+
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let status = null;
+
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    const frames = buffer.split("\n\n");
+    buffer = frames.pop() ?? "";
+    for (const frame of frames) {
+      const line = frame.split("\n").find((candidate) => candidate.startsWith("data: "));
+      if (!line) continue;
+      let payload;
+      try {
+        payload = JSON.parse(line.slice(6));
+      } catch {
+        continue;
+      }
+      if (payload.type === "snapshot") {
+        status = payload.run?.status ?? status;
+      } else if (payload.type === "event") {
+        // `type`, not `event_type`: the column is event_type but the repo's
+        // projection renames it, and this reads the projection.
+        const { type: eventType, data } = payload.event || {};
+        if (eventType?.startsWith("eval_")) note(describeEvent(eventType, data || {}));
+        if (eventType === "run_finished" || eventType === "run_failed") status = "done";
+      }
+    }
+  }
+  return status;
+}
+
+function summarise(run) {
+  const artifacts = run?.artifacts || [];
+  const summaryArtifact = artifacts.find((a) => a.kind === "workload_eval_summary");
+  if (!summaryArtifact) return;
+  const { summary, reading } = summaryArtifact.content || {};
+  if (summary?.verdict) {
+    say("what it measured");
+    for (const line of String(summary.verdict).trim().split("\n")) note(line);
+    if (summary.measured_at_tier) {
+      note("");
+      note(`measured with ${summary.measured_at_tier} access unless a tier is named below`);
+    }
+  }
+  if (Array.isArray(summary?.tier_curve) && summary.tier_curve.length) {
+    say("what each level of access bought");
+    note("tier   mix error   skill    names 1st   with a number   what it adds");
+    for (const rung of summary.tier_curve) {
+      const skill = rung.skill_is_meaningful === false ? "n/a" : percent(rung.skill_vs_baseline);
+      note(
+        `${String(rung.tier).padEnd(6)} ${Number(rung.mix_error).toFixed(4).padEnd(11)} ` +
+          `${skill.padEnd(8)} ${percent(rung.names_the_first_to_break).padEnd(11)} ` +
+          `${percent(rung.endpoints_with_a_number).padEnd(15)} ` +
+          `${String(rung.what_it_adds || "").split(".")[0]}`
+      );
+    }
+    // The sentence a customer hears, rather than the columns an engineer
+    // reads. "88% of endpoints carry a multiple" is the claim; "0.0812" is
+    // not something anybody can act on in a meeting.
+    say("what you could tell them at each level");
+    for (const rung of summary.tier_curve) {
+      if (!rung.what_it_can_say) continue;
+      note(`${rung.tier}: ${rung.what_it_can_say}`);
+      note("");
+    }
+  }
+  if (reading?.ran && reading?.text) {
+    say("what the analyst made of it");
+    for (const line of String(reading.text).trim().split("\n")) note(line);
+  }
+}
+
+/** The value after a flag, or a fallback. Module level so the forecast path
+ *  and the experiment path read arguments the same way. */
+function valueIn(args, name, fallback = "") {
+  const index = args.indexOf(name);
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+}
+
+
+/** Run one forecast and stream it, with the app open on the page that shows it.
+ *
+ * Separate from the accuracy experiment because they answer different
+ * questions. The experiment scores the forecaster across six synthetic worlds
+ * and takes a minute; this asks the forecaster what it makes of *this*
+ * customer, which is the thing somebody wants to look at first.
+ */
+async function runForecast({ backendUrl, key, wantApp, args }) {
+  const withhold = (valueIn(args, "--without") || "")
+    .split(",")
+    .map((source) => source.trim())
+    .filter(Boolean);
+
+  const body = {
+    pack_key: valueIn(args, "--pack") || "simula",
+    unattended: true,
+    horizon_days: Number(valueIn(args, "--horizon")) || 90,
+    ...(withhold.length ? { withhold } : {}),
+  };
+
+  say("starting the forecast");
+  if (withhold.length) note(`running without: ${withhold.join(", ")}`);
+
+  const response = await fetch(`${backendUrl}/workload/forecasts`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    return fail(`the forecast would not start: ${response.status} ${await response.text()}`);
+  }
+  const run = await response.json();
+  if (!run?.id) return fail("the run started but the API would not say which one it was");
+  note(`run ${run.id}`);
+  if (wantApp) note("the app is watching this run on the Forecast page");
+
+  say("following along");
+  await streamRun({ backendUrl, key, runId: run.id });
+
+  const forecast = await fetch(`${backendUrl}/workload/forecast`, {
+    headers: { authorization: `Bearer ${key}` },
+  })
+    .then((result) => (result.ok ? result.json() : null))
+    .catch(() => null);
+
+  if (forecast) {
+    const summary = forecast.summary || {};
+    say("what it read");
+    for (const row of summary.inputs || []) {
+      note(`[${row.status}] ${row.label} -- ${row.detail}`);
+    }
+    // Said here rather than only on the page, and before the recommendation,
+    // because it is what the recommendation rests on. The sources above are
+    // measurement; everything below this line comes from a model of what the
+    // customer's users do, and the identity check is that model being tested
+    // against the logs rather than fitted to them.
+    const behaviour = summary.behaviour || {};
+    const identity = behaviour.identity || {};
+    say("does the model match the traffic");
+    if (identity.checked) {
+      const off = (Number(identity.error) * 100).toFixed(1);
+      note(
+        identity.agrees
+          ? `Yes, to within ${off}%: ${Number(identity.observed).toFixed(2)} tracking calls per impression against the ${identity.expected} the SDK makes.`
+          : `No: ${Number(identity.observed).toFixed(2)} tracking calls per impression against the ${identity.expected} the SDK makes, so load is arriving from outside the modelled funnel.`
+      );
+    } else {
+      note("Not checked: the test needs both request logs and reported impressions.");
+    }
+    note(
+      `${behaviour.measured_drivers ?? 0} of ${behaviour.total_drivers ?? 0} drivers were measured; the rest are the model's priors.`
+    );
+
+    // Grouped by the constraint each purchase relieves rather than by the
+    // endpoint that revealed it, and each line says what it buys. A plan that
+    // recommended work without saying what the work moves is selling work.
+    const plan = summary.resource_plan || {};
+    const actions = plan.actions || [];
+    if (actions.length) {
+      say("resource planning");
+      for (const action of actions) {
+        note(`[${action.factor}] ${action.headline}`);
+        const relieved = action.relieved_to_multiple;
+        note(
+          `    binds at ${action.binds_at_multiple}x today's traffic; ` +
+            (relieved
+              ? `doing it moves that to ${relieved}x, then ${action.then_binds_on} binds`
+              : "no other ceiling here was measured, so the gain is unknown")
+        );
+        note(`    ${action.why}`);
+      }
+      if (plan.unmeasured_endpoints) {
+        note(
+          `${plan.unmeasured_endpoints} endpoints have no measured ceiling, so nothing is suggested for them.`
+        );
+      }
+    }
+
+    const lead = (summary.index_recommendations || [])[0];
+    if (lead) {
+      say("the statement to run");
+      note(lead.statement);
+    }
+    say("where to look");
+    note(`the Forecast page, at tier ${forecast.access_tier}. Every source above`);
+    note("has a switch there: turn one off and run it again to see what is lost.");
+    note("the Behaviour model tab shows what your users are assumed to do, with");
+    note("the pack's guess beside the measurement wherever the data reached it.");
+  }
+  return 0;
+}
+
+
+export async function predictCommand(commandArgs = []) {
+  const args = commandArgs;
+  const flag = (name) => args.includes(name);
+  const value = (name, fallback = "") => valueIn(args, name, fallback);
+
+  // Before anything is started. Asking what a command does and having it boot
+  // Postgres, the API, the dashboard and restart your editor's window is a
+  // trap, and `--help` is the one flag somebody types precisely because they
+  // do not yet know what the command will do.
+  if (flag("--help") || flag("-h")) {
+    process.stdout.write(PREDICT_HELP);
+    return 0;
+  }
+
+  const checkout = resolveCheckout();
+  if (!checkout) {
+    return fail(
+      "preman predict drives a local checkout, and this copy was installed from the registry.\n" +
+        "Run it from the repo: `node PreMan-Backend/preman-mcp/bin/cli.js predict`."
+    );
+  }
+  const { backendDir, dashboardDir, desktopDir } = checkout;
+  const backendUrl = (value("--backend", DEFAULT_BACKEND) || DEFAULT_BACKEND).replace(/\/$/, "");
+  const wantApp = !flag("--no-app");
+
+  try {
+    say("checking the backend");
+    await ensureBackend(backendDir, backendUrl);
+
+    const { key, origin } = resolveApiKey();
+    if (!key) {
+      return fail(
+        `no local API key.\n` +
+          `Mint one with:\n` +
+          `  cd ${backendDir} && uv run --no-sync python scripts/create_test_user.py --mint-api-key\n` +
+          `then save it to ${DEV_LOCAL} as {"api_key": "pm_live_…"}, or export PREMAN_API_KEY.`
+      );
+    }
+    note(`key from ${origin}`);
+
+    if (flag("--show-inputs")) {
+      // Before the app, the session and the run: this answers a question, and
+      // restarting somebody's window to answer it would be rude.
+      if (!(await ensureEntitlement({ backendDir, backendUrl, key, email: "" }))) {
+        return fail("the workload product is not enabled for that account");
+      }
+      return showInputs({ backendUrl, key });
+    }
+
+    let email = "";
+    if (wantApp) {
+      say("giving the app a session to start logged in");
+      const session = mintDesktopSession(backendDir, key);
+      email = session.email;
+      note(session.line);
+    }
+
+    if (!(await ensureEntitlement({ backendDir, backendUrl, key, email }))) {
+      return fail("the workload product is still not enabled for that account");
+    }
+
+    const forecasting = flag("--forecast");
+    const page = forecasting ? "Forecast" : "Accuracy";
+
+    if (wantApp) {
+      say("checking the dashboard");
+      await ensureDashboard(dashboardDir);
+      say(`restarting the app on the ${page} page`);
+      await restartDesktop({
+        desktopDir,
+        backendUrl,
+        route: forecasting ? FORECAST_ROUTE : ACCURACY_ROUTE,
+      });
+    }
+
+    if (flag("--app-only")) {
+      say("ready");
+      note(`the stack is up and the app is on the ${page} page; no run was started`);
+      return 0;
+    }
+
+    if (forecasting) {
+      return runForecast({ backendUrl, key, wantApp, args });
+    }
+
+    const body = {};
+    if (value("--seeds")) body.seeds = parseSeeds(value("--seeds"));
+    if (value("--regimes")) body.regime_keys = value("--regimes").split(",").map((s) => s.trim());
+    if (value("--train-days")) body.train_days = Number(value("--train-days"));
+    if (value("--test-days")) body.test_days = Number(value("--test-days"));
+    const tiers = tiersFromArgs(args);
+    if (tiers) body.sweep_tiers = tiers;
+
+    say("starting the accuracy experiment");
+    const started = await startEval({ backendUrl, key, body });
+    if (started.alreadyRunning) note("that experiment is already in flight; attaching to it");
+
+    const latest = await latestEval({ backendUrl, key });
+    const runId = started.run?.id || latest?.id;
+    if (!runId) return fail("the run started but the API would not say which one it was");
+    note(`run ${runId}`);
+    if (wantApp) note("the app is watching this run on the Accuracy page");
+
+    say("following along");
+    await streamRun({ backendUrl, key, runId });
+
+    const finished = await latestEval({ backendUrl, key });
+    summarise(finished);
+    const status = finished?.status || "unknown";
+    say(`run ${status}`);
+    return status === "failed" ? 1 : 0;
+  } catch (error) {
+    return fail(String(error?.message || error));
+  }
+}