catherd-cli 1.5.0 → 2.0.0-beta.20261022113309

package/src/entry/scorecard-command.ts

@@ -0,0 +1,187 @@
+import { join, resolve } from "node:path";
+import { defineCommand } from "citty";
+import { CatherdError } from "../domain/errors.ts";
+import {
+  passBar,
+  SCORECARD_TASKS,
+  type ScorecardFile,
+  type ScorecardTaskId,
+  type Verdict,
+} from "../domain/scorecard.ts";
+import {
+  defaultPreparedRoot,
+  loadTask,
+  type Prepared,
+  prepareTask,
+  readScorecard,
+  resultsFile,
+  saveTaskScore,
+  scoreTask,
+  scorecardRoot,
+} from "../services/scorecard.ts";
+import { JSON_ARG, mark, printJson, refuseInRole } from "./cli-kit.ts";
+
+const BASELINE = "1.5.0";
+
+/** POSIX single-quote escaping; a value of plain path characters stays bare. */
+const quote = (v: string): string => (/^[\w@%+=:,./-]+$/.test(v) ? v : `'${v.replaceAll("'", `'\\''`)}'`);
+
+/** The prepared task as the operator needs it: where to start, what to paste, and how to record. */
+export function formatPrepared(p: Prepared, label = "<label>"): string[] {
+  const env =
+    p.limits && p.shim ? `CATHERD_SCORECARD_LIMITS=${quote(p.limits)} PATH=${quote(p.shim)}:"$PATH" ` : "";
+  return [
+    `${mark("ok")} ${p.task} prepared in ${p.dir} at ${p.startCommit.slice(0, 8)}`,
+    `  start:  cd ${quote(p.repo)} && ${env}claude`,
+    `  prompt: ${p.prompt}`,
+    `  record: catherd scorecard record ${quote(p.dir)} --label ${label}`,
+  ];
+}
+
+const yes = (b: boolean): string => (b ? "yes" : "no");
+const num = (n: number): string => String(Math.round(n * 10) / 10);
+const k = (n: number): string => `${Math.round(n / 1000)}k`;
+
+function row(id: ScorecardTaskId, current: ScorecardFile, baseline: ScorecardFile | null): string {
+  const s = current.tasks[id];
+  if (!s) return `${id}  -`;
+  const was = baseline?.tasks[id];
+  const input = s.quota.backends.reduce((n, b) => n + b.input, 0);
+  const output = s.quota.backends.reduce((n, b) => n + b.output, 0);
+  return [
+    id,
+    s.catherdVersion,
+    `finished ${yes(s.finished)}`,
+    `interventions ${s.interventions.total}`,
+    `rounds ${s.reviewRounds}`,
+    `wall ${num(s.wallMinutes)} min (${was ? num(was.wallMinutes) : "?"} min)`,
+    `first try ${yes(s.firstTry)}`,
+    `quota ${k(input)}/${k(output)}`,
+  ].join("  ");
+}
+
+export function formatComparison(
+  current: ScorecardFile,
+  baseline: ScorecardFile | null,
+  v: Verdict,
+): string[] {
+  return [
+    `scorecard ${current.label} against ${baseline ? baseline.label : "no baseline"}`,
+    ...SCORECARD_TASKS.map((id) => row(id, current, baseline)),
+    ...(v.pass ? ["PASS"] : v.failures.map((f) => `FAIL: ${f}`)),
+  ];
+}
+
+/** The contributor commands read fixtures from the checkout; an installed package ships none. */
+function checkoutRoot(): string {
+  const root = scorecardRoot();
+  if (!root)
+    throw new CatherdError("E_INPUT_INVALID", "this catherd is not a source checkout", {
+      fix: "run it from a catherd checkout: bun src/cli.ts scorecard …",
+    });
+  return root;
+}
+
+const stamp = (d: Date): string => d.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+
+const RESULTS_ARG = {
+  results: { type: "string", description: "results folder (default: scorecard/results)" },
+} as const;
+const resultsDir = (root: string, given: string | undefined): string =>
+  given ? resolve(given) : join(root, "results");
+
+const prepare = defineCommand({
+  meta: { name: "prepare", description: `Prepare a task's starting point: ${SCORECARD_TASKS.join(", ")}` },
+  args: {
+    task: { type: "positional", required: true, description: SCORECARD_TASKS.join("|") },
+    source: {
+      type: "string",
+      description: "the repository to clone (a path or URL); the Sanitell task needs one",
+    },
+    dir: { type: "string", description: "where prepared tasks go (default: catherd's data dir)" },
+    setup: {
+      type: "boolean",
+      default: true,
+      description: "run the task's setup commands (--no-setup skips them)",
+    },
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd scorecard prepare");
+    const root = checkoutRoot();
+    const task = loadTask(args.task, root);
+    const now = new Date();
+    const into = join(args.dir ? resolve(args.dir) : defaultPreparedRoot(), `${task.id}-${stamp(now)}`);
+    const p = await prepareTask({ task, root, into, source: args.source, now, setup: args.setup });
+    if (args.json) return printJson(p);
+    for (const line of formatPrepared(p)) console.log(line);
+  },
+});
+
+const record = defineCommand({
+  meta: { name: "record", description: "Score a prepared task's run and store its row under a label" },
+  args: {
+    dir: { type: "positional", required: true, description: "the folder `prepare` printed" },
+    label: {
+      type: "string",
+      required: true,
+      description: "a version or plan name: 1.5.0, plan-29, 2.0.0-beta.1",
+    },
+    run: { type: "string", description: "the run to score, when the folder holds more than one" },
+    chat: { type: "string", description: "messages you typed into the session after the start prompt" },
+    ...RESULTS_ARG,
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd scorecard record");
+    const chat = args.chat === undefined ? 0 : Number(args.chat);
+    if (!Number.isInteger(chat) || chat < 0)
+      throw new CatherdError("E_INPUT_INVALID", `--chat ${args.chat} is not a count`, {
+        fix: "--chat <the number of messages you typed into the session>",
+      });
+    const root = checkoutRoot();
+    const out = resultsFile(resultsDir(root, args.results), args.label);
+    const s = await scoreTask({ dir: resolve(args.dir), root, run: args.run, chat, now: Date.now() });
+    const saved = saveTaskScore(out, args.label, s);
+    if (args.json) return printJson({ file: out, score: s });
+    const baseline = readScorecard(resultsFile(resultsDir(root, args.results), BASELINE));
+    console.log(
+      formatComparison(saved, baseline, passBar(saved, baseline))[1 + SCORECARD_TASKS.indexOf(s.task)],
+    );
+    console.log(out);
+  },
+});
+
+const compare = defineCommand({
+  meta: {
+    name: "compare",
+    description: `Check a label against the baseline (${BASELINE}) by the spec's pass bar`,
+  },
+  args: {
+    label: { type: "positional", required: true, description: "the label to check" },
+    baseline: { type: "string", description: `the label to compare with (default: ${BASELINE})` },
+    ...RESULTS_ARG,
+    ...JSON_ARG,
+  },
+  run({ args }) {
+    const dir = resultsDir(checkoutRoot(), args.results);
+    const current = readScorecard(resultsFile(dir, args.label));
+    if (!current)
+      throw new CatherdError("E_INPUT_INVALID", `no scorecard ${args.label} yet`, {
+        fix: `catherd scorecard record <dir> --label ${args.label}`,
+      });
+    const baseline = readScorecard(resultsFile(dir, args.baseline ?? BASELINE));
+    const verdict = passBar(current, baseline);
+    process.exitCode = verdict.pass ? 0 : 1;
+    if (args.json) return printJson({ current, baseline, verdict });
+    for (const line of formatComparison(current, baseline, verdict)) console.log(line);
+  },
+});
+
+export const scorecardCommand = defineCommand({
+  meta: {
+    name: "scorecard",
+    description: "Contributors: measure a catherd version on four fixed tasks against the 1.5.0 baseline",
+  },
+  subCommands: { prepare, record, compare },
+});

package/src/entry/supervise-bin.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// The detached supervisor's entry: it imports only what supervising needs, never src/cli.ts and its TUI.
+// The detached supervisor's entry: it imports only what supervising needs, never src/cli.ts.
 import { errorMessage } from "../domain/errors.ts";
 import { runSupervise } from "./supervise-command.ts";
 

package/src/infra/env.ts

@@ -9,8 +9,6 @@ const SECRET_ENV = new Set([
   "CODEX_SESSION_ID",
   "CATHERD_ORCHESTRATION_HOST",
   "TYPESAFE_API_KEY",
-  // spec 1.2 §9: the user's Artificial Analysis key reads scores for catherd alone
-  "ARTIFICIAL_ANALYSIS_API_KEY",
   "CLAUDE_CODE_MESSAGING_SOCKET",
   "CLAUDE_CODE_MESSAGING_TOKEN",
   "CLAUDE_CODE_SESSION_ID",

package/src/infra/git.ts

@@ -95,3 +95,67 @@ export async function statusSnapshot(repo: string, timeoutMs?: number): Promise<
   for (const { xy, path } of parsePorcelainZ(r.out)) snap[path] = fingerprint(repo, xy, path);
   return snap;
 }
+
+/** What a git command printed and how it ended, for the callers that show a failure (a commit hook's output). */
+export interface GitOutput {
+  code: number | null;
+  out: string;
+  err: string;
+  timedOut: boolean;
+}
+
+/**
+ * `git -C repo <args>` with both streams, for a command that may run hooks (a commit): a long timeout, and no
+ * optional lock avoidance, since this one writes the index.
+ */
+export async function gitRun(repo: string, args: string[], timeoutMs = 300_000): Promise<GitOutput> {
+  let p: Bun.Subprocess<"ignore", "pipe", "pipe">;
+  try {
+    p = Bun.spawn(["git", "-C", repo, ...args], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...scrubSecrets(process.env), LC_ALL: "C" },
+    });
+  } catch (e) {
+    return { code: null, out: "", err: (e as Error).message, timedOut: false };
+  }
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    p.kill("SIGKILL");
+  }, timeoutMs);
+  const out = new Response(p.stdout).text().catch(() => "");
+  const err = new Response(p.stderr).text().catch(() => "");
+  const code = await p.exited;
+  clearTimeout(timer);
+  return {
+    code: timedOut ? null : code,
+    out: timedOut ? "" : await out,
+    err: timedOut ? "" : await err,
+    timedOut,
+  };
+}
+
+/**
+ * `git fetch -q origin <base>` with a cap: catherd's one network git call (spec 2.0 decision 21). True when it
+ * exits 0; a failure never throws, the caller works from the last fetch and says so.
+ */
+export async function fetchBase(repo: string, base: string, timeoutMs = 60_000): Promise<boolean> {
+  const r = await gitRun(repo, ["fetch", "-q", "origin", base], timeoutMs);
+  return r.code === 0;
+}
+
+/** Whether `commit` is an ancestor of `ref`: true on exit 0, false on 1, null when git cannot tell. */
+export async function isAncestor(repo: string, commit: string, ref: string): Promise<boolean | null> {
+  const r = await git(repo, ["merge-base", "--is-ancestor", commit, ref]);
+  if (r.kind === "ok") return true;
+  return r.kind === "failed" && r.exit === 1 ? false : null;
+}
+
+/** The checked-out branch, or null when HEAD is detached (or git cannot say). */
+export async function currentBranch(repo: string): Promise<string | null> {
+  const r = await git(repo, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const name = r.kind === "ok" ? r.out.trim() : "";
+  return name && name !== "HEAD" ? name : null;
+}

package/src/infra/heavy-lock.ts

@@ -1,12 +1,40 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-import { availableParallelism } from "node:os";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { availableParallelism, loadavg } from "node:os";
 import { join } from "node:path";
+import { roleScopeOfScratch } from "../domain/role-scope.ts";
 import { tryLock, withFileLock } from "./filelock.ts";
 import { locksDir } from "./paths.ts";
 import { isAlive, selfIdentity } from "./proc.ts";
 import { ensurePrivateDir, writeJsonAtomic } from "./store.ts";
 
+/** Set in a locked command's env: a `catherd lock` inside it runs at once, holding nothing more. */
+export const LOCK_HELD_ENV = "CATHERD_LOCK_HELD";
+
+const envLoadWaitMs = Number(process.env.CATHERD_HEAVY_LOAD_WAIT_MS ?? 900_000);
+
+/**
+ * Spec 2.0 decision 18: heavy slots wait while the load is above twice the cores, up to 15 minutes.
+ * CATHERD_HEAVY_LOAD_WAIT_MS overrides the wait (0 = none); the test preload sets 0, since a busy CI runner
+ * would otherwise stall every lock in the suite, spawned `catherd lock` processes included.
+ */
+export const heavyLimits = {
+  loadWaitMs: envLoadWaitMs >= 0 ? envLoadWaitMs : 900_000,
+  loadPollMs: 15_000,
+  load: (): number => loadavg()[0] ?? 0,
+  cores: (): number => availableParallelism(),
+};
+
+/**
+ * The emptied TMPDIR and GOTMPDIR of one slot: under the role's scratch when the caller's TMPDIR is one (a role
+ * is told by its TMPDIR, so the slot dir must stay under it), else under catherd's locks dir.
+ */
+export function slotTmpDir(slot: number, inherited?: string): string {
+  return roleScopeOfScratch(inherited)
+    ? join(inherited as string, `heavy-${slot}`)
+    : join(locksDir(), "tmp", `slot-${slot}`);
+}
+
 /** A profile's `lock.heavy` as a slot count: a number, or half the cores. */
 export function heavySlots(setting: number | "cpus/2" | undefined): number {
   if (typeof setting === "number" && Number.isFinite(setting)) return Math.max(1, Math.floor(setting));
@@ -19,8 +47,8 @@ export function heavySlots(setting: number | "cpus/2" | undefined): number {
  */
 export async function withHeavySlot<T>(
   slots: number,
-  fn: (slot: number) => T | Promise<T>,
-  o: { pollMs?: number; onWait?: () => void } = {},
+  fn: (slot: number, tmp: string) => T | Promise<T>,
+  o: { pollMs?: number; onWait?: () => void; tmpBase?: string } = {},
 ): Promise<T> {
   const r = await withHeavySlotWithin(slots, Number.POSITIVE_INFINITY, fn, o);
   if (r.busy) throw new Error("unreachable: an unbounded wait never gives up");
@@ -34,19 +62,29 @@ export async function withHeavySlot<T>(
 export async function withHeavySlotWithin<T>(
   slots: number,
   waitMs: number,
-  fn: (slot: number) => T | Promise<T>,
-  o: { pollMs?: number; onWait?: () => void } = {},
+  fn: (slot: number, tmp: string) => T | Promise<T>,
+  o: { pollMs?: number; onWait?: () => void; tmpBase?: string } = {},
 ): Promise<{ busy: false; value: T } | { busy: true }> {
   const dir = locksDir();
   ensurePrivateDir(dir);
   const deadline = Date.now() + waitMs;
+  // an overloaded host runs the command late, not never: the wait is bounded, and the slot loop follows it
+  const loadDeadline = Date.now() + Math.min(heavyLimits.loadWaitMs, waitMs);
+  while (heavyLimits.load() > 2 * heavyLimits.cores() && Date.now() < loadDeadline) {
+    o.onWait?.();
+    await Bun.sleep(Math.min(heavyLimits.loadPollMs, Math.max(1, loadDeadline - Date.now())));
+  }
   for (;;) {
     for (let i = 0; i < slots; i++) {
       const release = tryLock(join(dir, `slot-${i}`));
       if (!release) continue;
+      const tmp = slotTmpDir(i, o.tmpBase);
       try {
-        return { busy: false, value: await fn(i) };
+        rmSync(tmp, { recursive: true, force: true });
+        ensurePrivateDir(tmp);
+        return { busy: false, value: await fn(i, tmp) };
       } finally {
+        rmSync(tmp, { recursive: true, force: true });
         release();
       }
     }

package/src/infra/launch.ts

@@ -1,25 +1,81 @@
 import { closeSync, openSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { ROLE_ENV } from "../domain/role-scope.ts";
 import { scrubSecrets } from "./env.ts";
 import { log as logRow } from "./log.ts";
 import { PRIVATE_FILE } from "./store.ts";
 
-/** A thin executable that supervises one spec; unlike src/cli.ts it never loads the TUI. */
+/** A thin executable that supervises one spec; it never loads src/cli.ts. */
 export const SUPERVISE_ENTRY = fileURLToPath(new URL("../entry/supervise-bin.ts", import.meta.url));
 
-/** Starts `supervise-bin.ts <spec>` in its own session and returns at once; it outlives this process. */
-export function launchSupervisor(specPath: string): number {
-  const log = openSync(join(dirname(specPath), "supervisor.log"), "a", PRIVATE_FILE);
-  const p = Bun.spawn([process.execPath, SUPERVISE_ENTRY, specPath], {
+/** The thin executable that drives one run; like the supervisor's, it never loads src/cli.ts. */
+export const DAEMON_ENTRY = fileURLToPath(new URL("../entry/daemon-bin.ts", import.meta.url));
+
+/** The thin executable that runs one milestone check (plan 30b); like the others it never loads src/cli.ts. */
+export const CHECK_ENTRY = fileURLToPath(new URL("../entry/check-bin.ts", import.meta.url));
+
+/**
+ * Starts `entry args` in its own session, its output appended to `logFile`, and returns at once: the process
+ * outlives this one.
+ */
+export function launchDetached(
+  entry: string,
+  args: string[],
+  logFile: string,
+  env: Record<string, string>,
+): number {
+  const log = openSync(logFile, "a", PRIVATE_FILE);
+  const p = Bun.spawn([process.execPath, entry, ...args], {
     stdin: "ignore",
     stdout: log,
     stderr: log,
     detached: true,
-    env: scrubSecrets(process.env),
+    env,
   });
   closeSync(log);
   p.unref();
-  logRow("info", "launch", { spec: specPath, pid: p.pid });
   return p.pid;
 }
+
+/** Starts `supervise-bin.ts <spec>` in its own session and returns at once; it outlives this process. */
+export function launchSupervisor(specPath: string): number {
+  const pid = launchDetached(
+    SUPERVISE_ENTRY,
+    [specPath],
+    join(dirname(specPath), "supervisor.log"),
+    scrubSecrets(process.env),
+  );
+  logRow("info", "launch", { spec: specPath, pid });
+  return pid;
+}
+
+/**
+ * The daemon's env (spec 2.0, plan 30 ruling 4): the launching process's own, so Jev's key reaches its routing,
+ * without the session identity of whoever launched it, and never a role's scope: it is nobody's role.
+ */
+export function daemonEnv(base: Record<string, string | undefined> = process.env): Record<string, string> {
+  const env = scrubSecrets(base);
+  if (base.TYPESAFE_API_KEY !== undefined) env.TYPESAFE_API_KEY = base.TYPESAFE_API_KEY;
+  delete env[ROLE_ENV];
+  return env;
+}
+
+/** Starts `daemon-bin.ts <run id>` for a run; its log is `<run dir>/daemon.log`. */
+export function launchDaemon(runId: string, runDir: string): number {
+  const pid = launchDetached(DAEMON_ENTRY, [runId], join(runDir, "daemon.log"), daemonEnv());
+  logRow("info", "launch", { daemon: runId, pid });
+  return pid;
+}
+
+/** Starts `check-bin.ts <flight file>` detached, so a tool timeout that kills its caller does not lose the check. */
+export function launchCheckWorker(flight: string): number {
+  const pid = launchDetached(
+    CHECK_ENTRY,
+    [flight],
+    join(dirname(flight), "worker.log"),
+    scrubSecrets(process.env),
+  );
+  logRow("info", "launch", { check: flight, pid });
+  return pid;
+}

package/src/infra/memory.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { freemem, totalmem } from "node:os";
+
+const MB = 2 ** 20;
+
+const sysctlLevel = (): string | null => {
+  try {
+    const r = Bun.spawnSync(["sysctl", "-n", "kern.memorystatus_level"]);
+    return r.exitCode === 0 ? r.stdout.toString() : null;
+  } catch {
+    return null;
+  }
+};
+
+const procMeminfo = (): string | null => {
+  try {
+    return readFileSync("/proc/meminfo", "utf8");
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The memory the machine could give a new process, in MB. macOS reports almost nothing through `os.freemem()`
+ * (it counts cache as used), so it is the kernel's free percentage of the total; Linux has `MemAvailable`;
+ * anything unreadable falls back to `os.freemem()`. Never throws.
+ */
+export function availableMemoryMb(
+  o: {
+    platform?: NodeJS.Platform;
+    sysctl?: () => string | null;
+    meminfo?: () => string | null;
+  } = {},
+): number {
+  const platform = o.platform ?? process.platform;
+  if (platform === "darwin") {
+    const level = Number.parseInt((o.sysctl ?? sysctlLevel)() ?? "", 10);
+    if (Number.isInteger(level) && level >= 0 && level <= 100)
+      return Math.floor(((level / 100) * totalmem()) / MB);
+  } else if (platform === "linux") {
+    const kb = /^MemAvailable:\s+(\d+) kB$/m.exec((o.meminfo ?? procMeminfo)() ?? "")?.[1];
+    if (kb !== undefined) return Math.floor(Number(kb) / 1024);
+  }
+  return Math.floor(freemem() / MB);
+}

package/src/infra/ntfy.ts

@@ -0,0 +1,40 @@
+import type { NotifyMessage } from "../domain/notify.ts";
+import { log } from "./log.ts";
+
+/** A header value as ntfy reads it: plain ASCII as it is, anything else as an RFC 2047 encoded word. */
+const headerValue = (s: string): string =>
+  /^[\x20-\x7e]*$/.test(s) ? s : `=?UTF-8?B?${Buffer.from(s).toString("base64")}?=`;
+
+/**
+ * Posts one message to an ntfy topic. True once the server accepted it; any error, a non-2xx answer or a
+ * server slower than `timeoutMs` is false, never a throw, and the log never carries the topic (the url is a
+ * secret of the user's).
+ */
+export async function postNotify(
+  url: string,
+  m: NotifyMessage,
+  o: { fetch?: typeof fetch; timeoutMs?: number } = {},
+): Promise<boolean> {
+  const timeoutMs = o.timeoutMs ?? 10_000;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const sent = (o.fetch ?? fetch)(url, {
+      method: "POST",
+      body: m.message,
+      headers: { Title: headerValue(m.title), Tags: m.tags.join(",") },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    // a fetch that ignores its signal still gives up
+    const gaveUp = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`no answer in ${timeoutMs} ms`)), timeoutMs);
+    });
+    const res = await Promise.race([sent, gaveUp]);
+    if (!res.ok) log("warn", "notify", { ntfy: res.status });
+    return res.ok;
+  } catch (e) {
+    log("warn", "notify", { ntfy: e instanceof Error ? e.name : "error" });
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/infra/open-url.ts

@@ -0,0 +1,42 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * A page that sends the browser on to `url`, so the opener's argv (readable by every local user, and kept in
+ * /proc/<pid>/cmdline) carries a path instead of the token. The dir is 0700 and the file 0600; `remove` deletes both.
+ */
+export function writeRedirectPage(url: string): {
+  path: string;
+  remove(): void;
+} {
+  const dir = mkdtempSync(join(tmpdir(), "catherd-panel-"));
+  const path = join(dir, "sign-in.html");
+  writeFileSync(
+    path,
+    `<!doctype html><meta charset="utf-8"><title>catherd panel</title><script>location.replace(${JSON.stringify(url)})</script>\n`,
+    { mode: 0o600 },
+  );
+  return { path, remove: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+/** The command that opens `url` in the user's browser on `platform`. */
+export function openerFor(platform: NodeJS.Platform, url: string): string[] {
+  if (platform === "darwin") return ["open", url];
+  if (platform === "win32") return ["cmd", "/c", "start", "", url];
+  return ["xdg-open", url];
+}
+
+/** Opens `url` in the default browser, detached; a machine with no opener simply opens nothing. */
+export function openUrl(url: string): void {
+  try {
+    Bun.spawn(openerFor(process.platform, url), {
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+      detached: true,
+    }).unref();
+  } catch {
+    // no opener on PATH: the printed link still works
+  }
+}

package/src/infra/paths.ts

@@ -73,5 +73,5 @@ export const runsDir = (toplevel: string): string => join(repoDir(toplevel), "ru
 export const logsDir = (): string => join(dataDir(), "logs");
 export const discoveryDir = (): string => join(dataDir(), "discovery");
 export const locksDir = (): string => join(dataDir(), "locks");
-/** Spec 1.2 §3.3: each source's last good answer, the sync state and lock, and what the sync derived. */
-export const sourcesDir = (): string => join(dataDir(), "sources");
+/** The Slopalytics index: the last good answer of the proxy, one intelligence per model and effort. */
+export const indexPath = (): string => join(dataDir(), "slopalytics.json");

package/src/infra/slopalytics.ts

@@ -0,0 +1,30 @@
+import { existsSync } from "node:fs";
+import { parseProxy, type IndexFile, IndexFileSchema, type SlopRecord } from "../domain/slopalytics.ts";
+import { readVersioned, writeJsonAtomic } from "./store.ts";
+
+export const SLOPALYTICS_URL = "https://slopalyticsproxy.vercel.app";
+
+/** The proxy's answer, parsed. Throws on a transport error, a non-2xx, or an answer with no indexed pair. */
+export async function fetchProxy(
+  o: { fetch?: typeof fetch; timeoutMs?: number } = {},
+): Promise<{ fetchedAt: string | null; models: SlopRecord[] }> {
+  const res = await (o.fetch ?? fetch)(SLOPALYTICS_URL, {
+    signal: AbortSignal.timeout(o.timeoutMs ?? 15_000),
+  });
+  if (!res.ok) throw new Error(`http ${res.status}`);
+  const parsed = parseProxy(await res.json());
+  if (parsed.models.length === 0) throw new Error("no indexed pairs");
+  return parsed;
+}
+
+/** The cached index, or null when there is none or it cannot be read (the next refresh rewrites it). */
+export function readIndexFile(file: string): IndexFile | null {
+  if (!existsSync(file)) return null;
+  try {
+    return readVersioned(file, IndexFileSchema, 1);
+  } catch {
+    return null;
+  }
+}
+
+export const writeIndexFile = (file: string, f: IndexFile): void => writeJsonAtomic(file, f, { mode: 0o600 });

package/src/infra/store.ts

@@ -150,9 +150,14 @@ function endsMidLine(file: string): boolean {
  * tail left by an earlier crash is ended first, in the same write, so the new row stays whole.
  */
 export function appendJsonl(file: string, value: unknown): void {
+  appendJsonlBatch(file, [value]);
+}
+
+/** Several rows in one write, so a crash leaves all of them or at worst a torn last one. */
+export function appendJsonlBatch(file: string, values: unknown[]): void {
   ensurePrivateDir(dirname(file));
   const prefix = endsMidLine(file) ? "\n" : "";
-  appendPrivate(file, `${prefix}${JSON.stringify(value)}\n`);
+  appendPrivate(file, prefix + values.map((v) => `${JSON.stringify(v)}\n`).join(""));
 }
 
 const madePrivate = new Set<string>();