static-fire 0.0.0-stage → 0.44.0

package/src/core/init.ts

@@ -0,0 +1,231 @@
+// `static-fire init`: make a project in the current folder. It finds the harness CLIs on the PATH (it never runs
+// them), writes one config per harness found, judges.yaml with one default judge, static-fire.yaml, empty evals/
+// and suites/, a .gitignore and a short AGENTS.md that points an agent to `static-fire guide`.
+//
+// The folder belongs to the user. init only adds: every file is created with the exclusive flag, so a file that
+// exists (or appears while init runs) is kept as it is and reported. In a project, or a subfolder of one, init
+// writes nothing. static-fire.yaml, the project marker, is written last.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { configLabel } from "./label";
+import { findOutsideTools, type HarnessTools } from "./outside-tools";
+import { findProject, PROJECT_FILE } from "./project";
+import type { AgentConfig, AgentHarness, JudgeConfig } from "./types";
+
+/** The harnesses init looks for, in the order a default judge is chosen. */
+export const INIT_HARNESSES = ["claude", "codex", "agy", "pi"] as const satisfies readonly AgentHarness[];
+type InitHarness = (typeof INIT_HARNESSES)[number];
+
+type ConfigFields = Pick<AgentConfig, "model" | "effort" | "provider">;
+type JudgeFields = Pick<JudgeConfig, "model" | "effort">;
+
+/**
+ * The one table of model ids that init writes: per harness, the config's fields, a comment for its file, and the
+ * judge's fields for a harness that can judge (Pi has no JSON Schema output, so it cannot).
+ */
+export const HARNESS_MODELS: Record<InitHarness, { config: ConfigFields; comment?: string; judge?: JudgeFields }> = {
+  claude: { config: { model: "claude-opus-5-5", effort: "medium" }, judge: { model: "claude-sonnet-5-5", effort: "medium" } },
+  codex: { config: { model: "gpt-6.1-sol", effort: "medium" }, judge: { model: "gpt-6.1-sol", effort: "medium" } },
+  agy: {
+    config: { model: "gemini-4-hydrogen-medium" },
+    comment: "agy model ids carry the effort level (low / medium / high).",
+    judge: { model: "gemini-4-argon-medium" },
+  },
+  pi: {
+    config: { provider: "openai-codex", model: "gpt-6.1-sol", effort: "medium" },
+    comment: "The provider must match the one you are logged in to in Pi (run `pi` and /login).",
+  },
+};
+
+export type HarnessFound = { found: true; path: string } | { found: false };
+/** A harness as init reports it: where its program is, and the outside tools in its user setup (outside-tools.ts). */
+export type HarnessReport = HarnessFound & HarnessTools;
+
+/** What init found and did. `harnesses` is keyed by harness, so each entry can carry more facts later. */
+export interface InitReport {
+  project: string;
+  /** false when the folder is already in a project: nothing was written. */
+  created: boolean;
+  harnesses: Record<InitHarness, HarnessReport>;
+  /** The id of the judge init wrote, or null when it wrote none. */
+  judge: string | null;
+  /** Paths written, relative to the project; a folder ends with "/". */
+  written: string[];
+  /** Paths that existed and were not changed. */
+  kept: string[];
+  notes: string[];
+}
+
+/** Each harness's program on `PATH`, found and never run. */
+export function findHarnesses(PATH = process.env.PATH ?? ""): Record<InitHarness, HarnessFound> {
+  return Object.fromEntries(INIT_HARNESSES.map((h) => {
+    const path = Bun.which(h, { PATH });
+    return [h, path ? { found: true, path } : { found: false }];
+  })) as Record<InitHarness, HarnessFound>;
+}
+
+/** Each harness found, with the outside tools of its user setup. Reads the setup files and changes none. */
+function reportHarnesses(PATH: string): Record<InitHarness, HarnessReport> {
+  const found = findHarnesses(PATH);
+  return Object.fromEntries(INIT_HARNESSES.map((h) => [h, { ...found[h], ...findOutsideTools(h, found[h].found) }])) as Record<InitHarness, HarnessReport>;
+}
+
+const GITIGNORE = ["runs/", ".cache/"];
+
+const AGENTS_MD = `# Static Fire project
+
+This folder is a Static Fire project. It compares agent configurations on tasks from the user's own work.
+
+Before you work here, run \`static-fire guide\` (or \`npx static-fire guide\` when \`static-fire\` is not installed)
+and read all of it. It gives the approach from the user's goal to a dashboard with data, and the formats of the
+files in this folder, for the installed version. Use it instead of reading the engine source.
+`;
+
+/** static-fire.yaml: the project marker and the settings for trials. It blocks nothing by itself. */
+export function settingsFile(): string {
+  return `# Settings for the trials of this Static Fire project.
+trials:
+  # Tools that trials may not use, per harness. A trial runs with no permission prompts, so nobody is there to
+  # approve a tool that acts on an outside service (sends mail, posts a message, spends money, deploys).
+  # Run \`static-fire init --json\` in this folder to list the MCP servers and plugins found in each harness's
+  # setup, with the entry that blocks each one. It changes no file here.
+  # Claude Code: a tool rule; "mcp__<server>" blocks every tool of that server.
+  # Codex: an MCP server name from config.toml, or a plugin as "name@marketplace".
+  # Antigravity and Pi tools cannot be blocked in trials yet.
+  # For example:
+  #   blockedTools:
+  #     claude:
+  #       - mcp__example
+  #     codex:
+  #       - example@marketplace
+  blockedTools: {}
+`;
+}
+
+const yamlLines = (fields: object, indent = "") =>
+  Object.entries(fields).filter(([, v]) => v !== undefined).map(([k, v]) => `${indent}${k}: ${v}\n`).join("");
+
+function configFile(h: InitHarness): string {
+  const { config, comment } = HARNESS_MODELS[h];
+  return `${comment ? `# ${comment}\n` : ""}harness: ${h}\n${yamlLines(config)}`;
+}
+
+function judgeOf(h: InitHarness): JudgeConfig | null {
+  const fields = HARNESS_MODELS[h].judge;
+  if (!fields || h === "pi") return null;
+  return { id: fields.model, label: configLabel({ harness: h, ...fields }), harness: h, ...fields };
+}
+
+const JUDGES_HEAD = `# Judge configurations. The first one is the default and runs every judge criterion.
+# A judge runs on claude, codex or agy (Pi cannot return JSON Schema output).
+`;
+
+function judgesFile(judge: JudgeConfig | null): string {
+  if (!judge) {
+    return `${JUDGES_HEAD}# No harness that can judge was found, so judge criteria cannot run until a judge is added here, for example:
+#   - id: claude-sonnet-5-5
+#     label: Claude Code · Sonnet 5.5 · medium
+#     harness: claude
+#     model: claude-sonnet-5-5
+#     effort: medium
+judges: []
+`;
+  }
+  const { id, ...rest } = judge;
+  return `${JUDGES_HEAD}judges:\n  - id: ${id}\n${yamlLines(rest, "    ")}`;
+}
+
+/** Make a project in `dir` (the current folder by default), or change nothing when `dir` is already in one. */
+export function initProject(dir = process.cwd(), PATH = process.env.PATH ?? ""): InitReport {
+  const root = resolve(dir);
+  const harnesses = reportHarnesses(PATH);
+  const existing = findProject(root);
+  if (existing) return { project: existing, created: false, harnesses, judge: null, written: [], kept: [], notes: [] };
+
+  const written: string[] = [], kept: string[] = [], notes: string[] = [];
+  /** Create `rel` with `text`, or keep the file that is there. True when written. */
+  const put = (rel: string, text: string) => {
+    try {
+      writeFileSync(join(root, rel), text, { flag: "wx" });
+      written.push(rel);
+      return true;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+      kept.push(rel);
+      return false;
+    }
+  };
+  const folder = (rel: string, report: boolean) => {
+    if (existsSync(join(root, rel))) return;
+    mkdirSync(join(root, rel));
+    if (report) written.push(`${rel}/`);
+  };
+
+  const found = INIT_HARNESSES.filter((h) => harnesses[h].found);
+  folder("configs", false);
+  for (const h of found) if (!put(`configs/${h}.yaml`, configFile(h))) notes.push(`configs/${h}.yaml exists and was not changed.`);
+  if (!found.length) notes.push(`no harness was found on the PATH (looked for ${INIT_HARNESSES.join(", ")}), so configs/ has no config.`);
+
+  const judgeHarness = found.find((h) => judgeOf(h));
+  const judge = judgeHarness ? judgeOf(judgeHarness) : null;
+  let judgeId: string | null = null;
+  if (put("judges.yaml", judgesFile(judge))) {
+    judgeId = judge?.id ?? null;
+    if (!judge) notes.push("no judge was written: no harness that can judge (claude, codex, agy) was found. judges.yaml lists none, so judge criteria cannot run until one is added.");
+  } else {
+    notes.push("judges.yaml exists and was not changed.");
+  }
+
+  folder("evals", true);
+  folder("suites", true);
+
+  if (!put(".gitignore", `${GITIGNORE.join("\n")}\n`)) {
+    const lines = readFileSync(join(root, ".gitignore"), "utf8").split(/\r?\n/).map((l) => l.trim());
+    const missing = GITIGNORE.filter((g) => !lines.includes(g) && !lines.includes(g.slice(0, -1)) && !lines.includes(`/${g}`));
+    if (missing.length) notes.push(`.gitignore exists and was not changed; it lacks ${missing.join(", ")}.`);
+  }
+  if (!put("AGENTS.md", AGENTS_MD) && !readFileSync(join(root, "AGENTS.md"), "utf8").includes("static-fire guide")) {
+    notes.push("AGENTS.md exists and was not changed; it has no pointer to `static-fire guide`.");
+  }
+
+  // The marker last: the folder becomes a project only once everything else is in place.
+  if (!put(PROJECT_FILE, settingsFile())) notes.push(`${PROJECT_FILE} exists and was not changed.`);
+
+  return { project: root, created: true, harnesses, judge: judgeId, written, kept, notes };
+}
+
+/** The outside tools section of the text report. */
+function formatTools(r: InitReport): string[] {
+  const lines = ["outside tools in each harness's setup. To block one in trials, add its entry under trials.blockedTools.<harness> in static-fire.yaml:"];
+  for (const h of INIT_HARNESSES) {
+    const x = r.harnesses[h];
+    if (!x.blockable) lines.push(`  ${h}: its tools cannot be blocked in trials yet`);
+    else if (!x.found) lines.push(`  ${h}: not found`);
+    else if (!x.tools.length) lines.push(`  ${h}: none found`);
+    else {
+      lines.push(`  ${h}:`);
+      for (const t of x.tools) lines.push(`    ${t.name} (${t.kind}, ${t.foundIn}): ${t.block.length ? t.block.join(", ") : "nothing to block (no MCP server)"}`);
+    }
+    if (x.blockable) for (const n of x.notes) lines.push(`    note: ${n}`);
+  }
+  return lines;
+}
+
+/** The report as text, for a person. */
+export function formatReport(r: InitReport): string {
+  if (!r.created) return `${[`already a Static Fire project: ${r.project}`, "nothing changed", ...formatTools(r)].join("\n")}\n`;
+  const found = INIT_HARNESSES.filter((h) => r.harnesses[h].found);
+  const missing = INIT_HARNESSES.filter((h) => !r.harnesses[h].found);
+  const lines = [
+    `made a Static Fire project in ${r.project}`,
+    `harnesses found: ${found.length ? found.map((h) => `${h} (${(r.harnesses[h] as { path: string }).path})`).join(", ") : "none"}`,
+    ...(missing.length && found.length ? [`not found: ${missing.join(", ")}`] : []),
+    `judge: ${r.judge ?? "none"}`,
+    `wrote: ${r.written.join(", ") || "nothing"}`,
+    ...(r.kept.length ? [`kept as they were: ${r.kept.join(", ")}`] : []),
+    ...r.notes.map((n) => `note: ${n}`),
+    ...formatTools(r),
+    "next: run `static-fire guide`",
+  ];
+  return `${lines.join("\n")}\n`;
+}

package/src/core/judge-schema.ts

@@ -0,0 +1,37 @@
+// The one shape every judge call must return, as a JSON Schema (sent to the harness) and a
+// validator (run on whatever comes back, because not every harness enforces the schema).
+import type { Vote } from "./types";
+
+export function verdictSchema(ids: string[]) {
+  return {
+    type: "object", additionalProperties: false, required: ["verdicts"],
+    properties: {
+      verdicts: {
+        type: "array",
+        items: {
+          // Reason before pass: the judge states its evidence before it commits to a verdict.
+          type: "object", additionalProperties: false, required: ["id", "reason", "pass"],
+          properties: { id: { type: "string", enum: ids }, reason: { type: "string" }, pass: { type: "boolean" } },
+        },
+      },
+    },
+  };
+}
+
+export type Parsed = { ok: true; verdicts: Record<string, Vote> } | { ok: false; error: string };
+
+export function parseVerdicts(data: unknown, ids: string[]): Parsed {
+  const list = (data as any)?.verdicts;
+  if (!Array.isArray(list)) return { ok: false, error: "no verdicts array" };
+  const out: Record<string, Vote> = {};
+  for (const v of list) {
+    if (!ids.includes(v?.id)) return { ok: false, error: `unknown criterion id ${JSON.stringify(v?.id)}` };
+    if (out[v.id]) return { ok: false, error: `duplicate criterion id ${v.id}` };
+    if (typeof v.pass !== "boolean") return { ok: false, error: `${v.id}: pass is not a boolean` };
+    if (typeof v.reason !== "string" || !v.reason.trim()) return { ok: false, error: `${v.id}: empty reason` };
+    out[v.id] = { pass: v.pass, reason: v.reason.trim() };
+  }
+  const missing = ids.filter((id) => !out[id]);
+  if (missing.length) return { ok: false, error: `missing verdicts: ${missing.join(", ")}` };
+  return { ok: true, verdicts: out };
+}

package/src/core/judge.ts

@@ -0,0 +1,166 @@
+// Judge calls: one prompt + a JSON Schema → validated verdicts, on any judge Host.
+// Every Host returns the same shape (see judge-schema.ts); one retry, then an error.
+import { mkdirSync, readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { agyHome, exec } from "../adapters";
+import { parseVerdicts, verdictSchema, type Parsed } from "./judge-schema";
+import type { JudgeConfig } from "./types";
+
+export type Attached = { label: string; path: string };
+
+/**
+ * What a judge gets besides the prompt text. `images` are attached to its message (null when its Host
+ * cannot attach images); `toRead` are files it must open with its file tool, all inside `readDir`.
+ */
+export interface JudgeFiles { images: Attached[] | null; toRead: string[]; readDir: string }
+
+/** The one list of image types judges take: extension → media type. */
+export const IMAGE_MEDIA: Record<string, string> = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" };
+export const isImage = (path: string) => extname(path).toLowerCase() in IMAGE_MEDIA;
+
+/** Judge Hosts that take images in the message itself. Antigravity takes text only, so it opens them by path. */
+export const attachesImages = (harness: JudgeConfig["harness"]) => harness === "claude" || harness === "codex";
+
+// engine:judgeCall.claude:begin
+/** One stream-json user message for `claude -p --input-format stream-json`: the prompt, then each image after its label. */
+export function claudeImageInput(prompt: string, images: Attached[]): string {
+  const content: unknown[] = [{ type: "text", text: prompt }];
+  images.forEach((im, i) => {
+    content.push({ type: "text", text: `Image ${i + 1}: ${im.label}` });
+    content.push({ type: "image", source: { type: "base64", media_type: IMAGE_MEDIA[extname(im.path).toLowerCase()], data: readFileSync(im.path).toString("base64") } });
+  });
+  return JSON.stringify({ type: "user", message: { role: "user", content } }) + "\n";
+}
+
+// engine:judgeCall.claude:end
+
+// engine:judgeCall.codex:begin
+/** `codex exec -i` per image, in prompt order. The option takes many values, so the prompt must follow `--`. */
+export const codexImageArgs = (images: Attached[]) => images.flatMap((im) => ["-i", im.path]);
+// engine:judgeCall.codex:end
+
+// engine:judgeCall.claude:begin
+/**
+ * The Claude Code judge command, and its stdin when images are attached. Output is always stream-json, so
+ * the log shows each file the judge opened (see missingReads).
+ */
+export function claudeJudgeCmd(judge: JudgeConfig, prompt: string, schema: unknown, files: JudgeFiles): { cmd: string[]; input?: string } {
+  const images = files.images ?? [];
+  const cmd = ["claude", "-p", ...(images.length ? ["--input-format", "stream-json"] : [prompt]), "--output-format", "stream-json", "--verbose",
+    "--model", judge.model, "--no-session-persistence", "--setting-sources", "project,local", "--strict-mcp-config",
+    "--json-schema", JSON.stringify(schema), "--tools", files.toRead.length ? "Read" : ""];
+  // Without --add-dir a headless read outside the judge's own folder is refused.
+  if (files.toRead.length) cmd.push("--add-dir", files.readDir);
+  if (judge.effort) cmd.push("--effort", judge.effort);
+  return images.length ? { cmd, input: claudeImageInput(prompt, images) } : { cmd };
+}
+
+const jsonl = (s: string): any[] => s.split("\n").flatMap((l) => { try { return [JSON.parse(l)]; } catch { return []; } });
+
+/** The verdict data, cost and refused reads from a Claude Code stream-json log. */
+export function parseClaudeResult(stdout: string): { data: unknown; cost: number; denied: number } {
+  const res = jsonl(stdout).find((x) => x.type === "result");
+  return { data: res?.structured_output ?? tryJson(res?.result), cost: res?.total_cost_usd ?? 0, denied: res?.permission_denials?.length ?? 0 };
+}
+
+// engine:judgeCall.claude:end
+
+// engine:judgeCall.agy:begin
+/** The verdict data from an Antigravity stream-json log. */
+export function parseAgyResult(stdout: string): unknown {
+  const res = jsonl(stdout).find((x) => x.event === "result")?.result;
+  return res?.structured_output ?? tryJson(res?.response);
+}
+
+// engine:judgeCall.agy:end
+
+/** Every tool call's arguments in a judge log, as text. */
+function toolCalls(harness: JudgeConfig["harness"], stdout: string): string[] {
+  const events = jsonl(stdout);
+  if (harness === "claude") return events.flatMap((e) => e.type === "assistant" ? (e.message?.content ?? []).filter((c: any) => c.type === "tool_use").map((c: any) => JSON.stringify(c.input)) : []);
+  if (harness === "codex") return events.flatMap((e) => e.type === "item.completed" && e.item?.type === "command_execution" ? [String(e.item.command ?? "")] : []);
+  return events.flatMap((e) => e.step_update?.tool_info ? [JSON.stringify(e.step_update.tool_info.parameters ?? {})] : []);
+}
+
+/** The files a judge was told to open that its log shows no tool call for. */
+export function missingReads(harness: JudgeConfig["harness"], stdout: string, toRead: string[]): string[] {
+  const calls = toolCalls(harness, stdout);
+  return toRead.filter((p) => !calls.some((c) => c.includes(p)));
+}
+
+// A trial can fan out into many judge processes; keep the machine responsive.
+const MAX_JUDGE_PROCS = 6;
+let active = 0;
+const waiting: (() => void)[] = [];
+async function slot<T>(fn: () => Promise<T>): Promise<T> {
+  if (active >= MAX_JUDGE_PROCS) await new Promise<void>((r) => waiting.push(r));
+  active++;
+  try { return await fn(); } finally { active--; waiting.shift()?.(); }
+}
+
+async function callOnce(judge: JudgeConfig, prompt: string, ids: string[], cwd: string, log: string, files: JudgeFiles) {
+  const schema = verdictSchema(ids);
+  const timeout = 5 * 60_000;
+  const images = files.images ?? [];
+  let data: unknown, cost = 0, stdout = "";
+  // engine:judgeCall.claude:begin
+  if (judge.harness === "claude") {
+    const { cmd, input } = claudeJudgeCmd(judge, prompt, schema, files);
+    stdout = (await exec(cmd, cwd, log, timeout, undefined, input)).stdout;
+    const r = parseClaudeResult(stdout);
+    data = r.data; cost = r.cost;
+    // A judge that could not read its evidence answered blind: an error, never a verdict.
+    if (r.denied) return { parsed: { ok: false as const, error: `judge was refused ${r.denied} file read(s)` }, cost };
+  // engine:judgeCall.claude:end
+  // engine:judgeCall.codex:begin
+  } else if (judge.harness === "codex") {
+    const schemaPath = join(cwd, "schema.json");
+    await Bun.write(schemaPath, JSON.stringify(schema));
+    const cmd = ["codex", "exec", "--json", "--skip-git-repo-check", "--ephemeral", "--ignore-user-config", "-m", judge.model,
+      "-s", "read-only", "-C", cwd, "--output-schema", schemaPath];
+    if (judge.effort) cmd.push("-c", `model_reasoning_effort=${judge.effort}`);
+    cmd.push(...codexImageArgs(images), "--", prompt);
+    stdout = (await exec(cmd, cwd, log, timeout)).stdout;
+    const msg = jsonl(stdout).filter((e) => e.type === "item.completed" && e.item?.type === "agent_message").pop();
+    data = tryJson(msg?.item?.text);
+    // Codex reports tokens only; judge cost for Codex is left at 0 (not part of any config's cost).
+  // engine:judgeCall.codex:end
+  // engine:judgeCall.agy:begin
+  } else {
+    const cmd = ["agy", "-p", prompt, "--model", judge.model, "--output-format", "stream-json", "--json-schema", JSON.stringify(schema)];
+    if (judge.effort) cmd.push("--effort", judge.effort);
+    stdout = (await exec(cmd, cwd, log, timeout, { HOME: agyHome() })).stdout;
+    data = parseAgyResult(stdout);
+  }
+  // engine:judgeCall.agy:end
+  // Backstop: a judge that skipped a file it had to open answered without part of its evidence.
+  const missing = missingReads(judge.harness, stdout, files.toRead);
+  if (missing.length) return { parsed: { ok: false as const, error: `judge did not open ${missing.length} evidence file(s): ${missing.map((p) => basename(p)).join(", ")}` }, cost };
+  return { parsed: parseVerdicts(data, ids), cost };
+}
+
+function tryJson(s: unknown): unknown {
+  if (typeof s !== "string") return undefined;
+  try { return JSON.parse(s); } catch { /* fall through */ }
+  const m = s.match(/\{[\s\S]*\}/);
+  try { return m ? JSON.parse(m[0]) : undefined; } catch { return undefined; }
+}
+
+/** One vote for a batch of criteria. Retries once on an invalid answer. */
+export async function judgeVote(judge: JudgeConfig, prompt: string, ids: string[], dir: string, files: JudgeFiles): Promise<{ parsed: Parsed; cost: number }> {
+  mkdirSync(dir, { recursive: true });
+  return slot(async () => {
+    let total = 0, last: Parsed = { ok: false, error: "not run" };
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      try {
+        const { parsed, cost } = await callOnce(judge, prompt, ids, dir, join(dir, `attempt-${attempt}.log`), files);
+        total += cost;
+        last = parsed;
+        if (parsed.ok) break;
+      } catch (e) {
+        last = { ok: false, error: e instanceof Error ? e.message : String(e) };
+      }
+    }
+    return { parsed: last, cost: total };
+  });
+}

package/src/core/label.ts

@@ -0,0 +1,43 @@
+// Config labels: built from the config's own fields, so no label is authored and none can drift from the config.
+import type { AgentConfig, Harness } from "./types";
+
+export const HARNESS_NAME: Record<Harness, string> = { claude: "Claude Code", codex: "Codex", agy: "Antigravity", pi: "Pi", human: "By hand" };
+export const EFFORTS = new Set(["low", "medium", "high", "xhigh", "max", "minimal"]);
+
+const title = (w: string) => w.charAt(0).toUpperCase() + w.slice(1);
+
+/** A readable model name for known id shapes; any other id is shown as it is. */
+export function modelName(model: string): string {
+  const claude = model.match(/^claude-([a-z]+)-(\d+(?:-\d+)*)$/);
+  if (claude) return `${title(claude[1])} ${claude[2].replace(/-/g, ".")}`;
+  const gpt = model.match(/^gpt-(\d+(?:\.\d+)*)-([a-z]+)$/);
+  if (gpt) return `GPT-${gpt[1]} ${title(gpt[2])}`;
+  const gemini = model.match(/^gemini-(\d+(?:\.\d+)*)-([a-z]+)$/);
+  if (gemini) return `Gemini ${gemini[1]} ${title(gemini[2])}`;
+  return model;
+}
+
+type Labelled = Pick<AgentConfig, "harness" | "model" | "effort" | "profile">;
+const USER_LABEL = "User (by hand)";
+
+/** "Model · effort · Profile", leaving out what the config does not set. */
+function parts(c: Labelled): string {
+  let { model, effort } = c;
+  const suffix = model.match(/^(.*)-([a-z]+)$/);
+  // agy ids carry the effort (gemini-4-argon-medium); other harnesses' ids are shown as they are.
+  if (c.harness === "agy" && !effort && suffix && EFFORTS.has(suffix[2])) [model, effort] = [suffix[1], suffix[2]];
+  return [modelName(model), effort, c.profile].filter(Boolean).join(" · ");
+}
+
+/** "Harness · Model · effort · Profile". A human config is the user, whoever runs Static Fire. */
+export const configLabel = (c: Labelled) => (c.harness === "human" ? USER_LABEL : `${HARNESS_NAME[c.harness]} · ${parts(c)}`);
+
+/** The label without the harness, for charts where the marker shape shows the harness. */
+export const shortConfigLabel = (c: Labelled) => (c.harness === "human" ? USER_LABEL : parts(c));
+
+/** Config id → chart label: the short label, or the full one where two configs would otherwise read the same. */
+export function chartLabels(configs: (Labelled & { configId: string })[]): Map<string, string> {
+  const count = new Map<string, number>();
+  for (const c of configs) count.set(shortConfigLabel(c), (count.get(shortConfigLabel(c)) ?? 0) + 1);
+  return new Map(configs.map((c) => [c.configId, count.get(shortConfigLabel(c))! > 1 ? configLabel(c) : shortConfigLabel(c)]));
+}

package/src/core/lock.ts

@@ -0,0 +1,40 @@
+// A lock shared by every process on this machine, for work that must never run twice at once (an apkit
+// install: apkit keeps one record of installs). The lock file is a small SQLite database; the holder keeps
+// an EXCLUSIVE transaction open on it while `fn` runs. The operating system drops that lock when the
+// holder's process ends in any way, so a crashed `run` never leaves a stale lock behind.
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface LockOptions {
+  /** How long to sleep between tries while another process holds the lock. */
+  pollMs?: number;
+  /** Called once, when the lock is busy and this process starts to wait. */
+  onWait?: () => void;
+}
+
+/** Runs `fn` while holding the lock in file `path`. Waits (without blocking the event loop) while another process holds it. */
+export async function withFileLock<T>(path: string, fn: () => Promise<T>, o: LockOptions = {}): Promise<T> {
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new Database(path, { create: true });
+  try {
+    db.run("PRAGMA busy_timeout = 0");   // never wait inside SQLite: that would block this process's event loop
+    for (let waited = false; ; waited = true) {
+      try {
+        db.run("BEGIN EXCLUSIVE");
+        break;
+      } catch (e) {
+        if ((e as { code?: string }).code !== "SQLITE_BUSY") throw e;
+        if (!waited) o.onWait?.();
+        await Bun.sleep(o.pollMs ?? 100);
+      }
+    }
+    try {
+      return await fn();
+    } finally {
+      db.run("ROLLBACK");   // nothing was written: this only lets go of the lock
+    }
+  } finally {
+    db.close();
+  }
+}