static-fire 0.44.0 → 0.54.1

package/src/core/coverage.ts

@@ -0,0 +1,84 @@
+// Which suites a view's index covers, and why the others are left out (DEC-019, DEC-020). The rule that picks the
+// default set is here, and so is the one line that `static-fire show` and the dashboard both print. No Node
+// imports: the dashboard bundles this file.
+
+/** A suite as the line names it. */
+export interface SuiteRef { id: string; title: string }
+
+/**
+ * Why a suite is not in view: the user did not pick it, no config has completed it, or too few configs have
+ * completed it together with the suites in view.
+ */
+export type LeftOutReason = "not-picked" | "none-completed" | "too-few";
+
+/** What a view's index covers. A view of tasks (no suites) has none. */
+export interface Coverage {
+  /** True when the suites were picked; false when the view chose them by the default rule. */
+  picked: boolean;
+  /** The suites in view, in catalog order: the Agent Performance Index is the mean of their Suite Indexes. */
+  covered: SuiteRef[];
+  /**
+   * Every other suite of the catalog, in catalog order, with the reason and how many configs in view have completed
+   * it. That count is null for a suite left out because it was not picked: the view does not read its trials.
+   */
+  leftOut: (SuiteRef & { reason: LeftOutReason; completed: number | null })[];
+  /** How many configs have completed every covered suite: the configs that have an index. */
+  complete: number;
+}
+
+/**
+ * The default set of suites (DEC-019). `suites` are the suite ids in catalog order; `completedBy` gives, for each,
+ * the configs that have a valid score on every task of it. Start with every suite and drop the suite the fewest
+ * configs have completed (on a tie, the one listed last), until at least two configs have completed all that
+ * remain. When no set has two, keep the largest set that one config has completed (on a tie, the set that comes
+ * first in catalog order). When no config has completed any suite, keep every suite. The result is in catalog order, and the same input always gives the same set.
+ */
+export function defaultSuites(suites: string[], completedBy: Map<string, Set<string>>): string[] {
+  const done = (id: string) => completedBy.get(id) ?? new Set<string>();
+  const completers = (ids: string[]) => {
+    if (!ids.length) return 0;
+    let all = new Set(done(ids[0]!));
+    for (const id of ids.slice(1)) all = new Set([...all].filter((c) => done(id).has(c)));
+    return all.size;
+  };
+  const left = [...suites];
+  while (left.length && completers(left) < 2) {
+    let drop = left[0]!;
+    for (const id of left) if (done(id).size <= done(drop).size) drop = id;   // <=: on a tie the later one
+    left.splice(left.indexOf(drop), 1);
+  }
+  if (left.length && completers(left) >= 2) return left;
+
+  // No set has two configs: the largest set one config has completed.
+  const configs = [...new Set([...completedBy.values()].flatMap((s) => [...s]))].sort();
+  const pos = (ids: string[]) => ids.map((id) => suites.indexOf(id));
+  const earlier = (a: string[], b: string[]) => { const pa = pos(a), pb = pos(b); for (let i = 0; i < pa.length; i++) if (pa[i] !== pb[i]) return pa[i]! < pb[i]!; return false; };
+  let best: string[] = [];
+  for (const c of configs) {
+    const set = suites.filter((id) => done(id).has(c));
+    if (set.length > best.length || (set.length === best.length && earlier(set, best))) best = set;
+  }
+  return best.length ? best : [...suites];
+}
+
+const list = (names: string[]) => names.length <= 1 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+
+/**
+ * The one line a view gives about its index: which suites it covers and, grouped by reason, which it leaves out
+ * and why. `judge` is the label of the judge in view. Null for a view of tasks.
+ */
+export function coverageLine(coverage: Coverage | null, judge: string): string | null {
+  if (!coverage) return null;
+  const parts = [`Covers ${list(coverage.covered.map((s) => s.title)) || "no suite"}.`];
+  const why: Record<LeftOutReason, (many: boolean) => string> = {
+    "none-completed": () => `no config has a score on every task under judge ${judge}`,
+    "too-few": (many) => `fewer than two configs have completed ${many ? "them" : "it"} with the suites covered`,
+    "not-picked": () => "not picked",
+  };
+  const groups = (["none-completed", "too-few", "not-picked"] as const)
+    .map((r) => [r, coverage.leftOut.filter((s) => s.reason === r)] as const).filter(([, s]) => s.length)
+    .map(([r, s]) => `${list(s.map((x) => x.title))} (${why[r](s.length > 1)})`);
+  if (groups.length) parts.push(`Left out: ${groups.join("; ")}.`);
+  if (!coverage.complete && coverage.covered.length) parts.push(`No config has a score on every task of ${coverage.covered.length > 1 ? "these suites" : "it"} yet.`);
+  return parts.join(" ");
+}

package/src/core/db.ts

@@ -344,6 +344,42 @@ export function openStore(path: string): Store {
   return storeOn(db);
 }
 
+/** A new, empty store in memory, with no file: what a plan reads when the project has no record store yet. */
+export function emptyStore(): Store {
+  const db = new Database(":memory:", { strict: true });
+  db.run("PRAGMA foreign_keys = ON");
+  migrate(db, ":memory:");
+  return storeOn(db);
+}
+
+/**
+ * A copy in memory of the store at `path`, for a plan, which must write nothing (#74). The file is opened read-only
+ * and read in one go; an older schema is brought up to SCHEMA_VERSION in the copy only, so the file keeps its
+ * schema, its journal mode and its content. Writes to the copy are lost when it is closed.
+ */
+export function snapshotStore(path: string): Store {
+  const file = new Database(path, { readonly: true, strict: true });
+  let bytes: Uint8Array;
+  try {
+    file.run(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+    bytes = file.serialize();
+  } finally {
+    file.close();
+  }
+  // Bytes 18 and 19 of the header say WAL mode; an image in memory cannot use WAL, so mark it as a rollback journal.
+  bytes[18] = 1;
+  bytes[19] = 1;
+  const db = Database.deserialize(bytes, { strict: true });
+  try {
+    db.run("PRAGMA foreign_keys = ON");
+    migrate(db, path);
+  } catch (e) {
+    db.close();
+    throw e;
+  }
+  return storeOn(db);
+}
+
 /**
  * Switches a new database to WAL mode (the mode is kept in the file, so later opens only read it).
  * SQLite does not apply the busy timeout to this switch: when another process is creating the same file

package/src/core/facets.ts

@@ -36,7 +36,7 @@ export interface GradingOption extends VersionName {
 }
 
 export interface Facets {
-  /** The Workflow Index and every suite and task with a stored trial. A suite's count is the sum over its tasks. */
+  /** The Agent Performance Index and every suite and task with a stored trial. A suite's count is the sum over its tasks. */
   scope: { index: number; suites: FacetValue[]; tasks: FacetValue[] };
   /** The judges in judges.yaml that have graded a task in scope. */
   judge: FacetValue[];
@@ -63,8 +63,11 @@ const tally = (values: string[]): Map<string, number> => {
 };
 
 /** The facets for `filters`. Throws on the same bad filters as buildView. */
-export function buildFacets(store: Store, filters: ViewFilters = {}, catalog: Catalog = projectCatalog()): Facets {
-  const base = buildView(store, filters, catalog);   // validates the filters and resolves scope, judge and grading
+export function buildFacets(store: Store, given: ViewFilters = {}, catalog: Catalog = projectCatalog()): Facets {
+  const base = buildView(store, given, catalog);   // validates the filters and resolves scope, judge and grading
+  // The counts are over the suites the view resolved: without a pick, the default set moves with the filters,
+  // and a count without one filter must not count other suites than the view it is offered in.
+  const filters: ViewFilters = given.tasks?.length || !base.filters.suiteIds.length ? given : { ...given, suites: base.filters.suiteIds };
   const { taskIds } = base.filters;
   const picked = base.filters.grading ? store.getGradingSetup(base.filters.grading) : null;
   const pickedTasks = picked ? store.gradingSetupTaskIds(picked.hash) : [];
@@ -73,16 +76,28 @@ export function buildFacets(store: Store, filters: ViewFilters = {}, catalog: Ca
   const inScope = all.filter((r) => taskIds.includes(r.taskId));
   const listed = (f: ViewFilters): TrialRecord[] => buildView(store, f, catalog).trials.map((t) => byId.get(t.id)!);
 
-  // Scope: one view over every suite; the picked grading setup stays only when its task is in that scope.
-  const suiteTasks = new Set(catalog.suites.flatMap((s) => s.tasks));
-  const index = listed({ ...without(filters, "suites", "tasks", "grading"), ...(picked && pickedTasks.some((t) => suiteTasks.has(t)) ? { grading: picked.hash } : {}) });
-  const perTask = tally(index.map((r) => r.taskId));
+  // Scope. A count is the number of trials the view would list with that value chosen (#80). A task: the view of
+  // that task, with the picked grading setup only when it is of that task (the page drops it for another task), so
+  // a task outside the default set of suites counts its own trials. A suite: the sum over its tasks. The index:
+  // the default set, or, with a picked grading setup, the suite of its task (the page picks it, web/filter-menu.ts
+  // withGradingPick).
+  const unscoped = without(filters, "suites", "tasks", "grading");
   const stored = new Set(all.map((r) => r.taskId));
+  const loads = (t: string) => { try { catalog.loadTask(t); return true; } catch { return false; } };
+  const storedTasks = [...stored].filter(loads).sort();
+  const others = storedTasks.filter((t) => !pickedTasks.includes(t));
+  const ofTasks = [
+    ...(others.length ? listed({ ...unscoped, tasks: others }) : []),
+    ...(picked ? listed({ ...unscoped, tasks: pickedTasks, grading: picked.hash }) : []),
+  ];
+  const perTask = tally(ofTasks.map((r) => r.taskId));
+  const home = picked ? catalog.suites.find((s) => s.tasks.some((t) => pickedTasks.includes(t))) : undefined;
+  const index = home ? listed({ ...unscoped, suites: [home.id], grading: picked!.hash }) : listed(unscoped);
   const scope = {
     index: index.length,
     suites: catalog.suites.filter((s) => s.tasks.some((t) => stored.has(t)))
       .map((s) => ({ value: s.id, count: s.tasks.reduce((n, t) => n + (perTask.get(t) ?? 0), 0) })),
-    tasks: [...suiteTasks].filter((t) => stored.has(t)).sort().map((t) => ({ value: t, count: perTask.get(t) ?? 0 })),
+    tasks: storedTasks.map((t) => ({ value: t, count: perTask.get(t) ?? 0 })),
   };
 
   // A grading setup is offered for a task only when a stored trial of that task carries a grading by it.

package/src/core/init.ts

@@ -1,15 +1,21 @@
-// `static-fire init`: make a project in the current folder. It finds the harness CLIs on the PATH (it never runs
+// `static-fire init [<folder>]`: make the home, report it, or make a second project (ADR-0010). Outside any project
+// and with no home, it makes the project in ~/static-fire (or <folder>) and saves it as the home. With a home and no
+// folder, it reports the home and writes nothing. With a home and a folder, it makes a second project there and
+// leaves the home as it is. Inside a project and with no folder, it writes nothing and names that project. Only the
+// first home is saved here; no init changes a home that is set.
+//
+// Making a project in a folder (initProject): 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 { existsSync, mkdirSync, readFileSync, statSync, 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 { defaultHomeFolder, findProject, HomeNotProjectError, PROJECT_FILE, readHome, saveHome, type Env } from "./project";
 import type { AgentConfig, AgentHarness, JudgeConfig } from "./types";
 
 /** The harnesses init looks for, in the order a default judge is chosen. */
@@ -41,8 +47,9 @@ 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 {
+/** What init found and did in one folder. `harnesses` is keyed by harness, so each entry can carry more facts later. */
+export interface ProjectInit {
+  /** The project's folder: the one made, or the root of the project the folder is already in. */
   project: string;
   /** false when the folder is already in a project: nothing was written. */
   created: boolean;
@@ -56,6 +63,24 @@ export interface InitReport {
   notes: string[];
 }
 
+/** What `static-fire init` found and did, with the home. */
+export interface InitReport extends ProjectInit {
+  /** The saved home's folder after this init, or null when none is set. */
+  home: string | null;
+  /** The project is the home. */
+  isHome: boolean;
+  /** This init saved the home: it was the first one. */
+  homeSaved: boolean;
+}
+
+/** The folder given to init is a file, or is under one. */
+export class NotAFolderError extends Error {
+  constructor(path: string) {
+    super(`${path} is not a folder, so no project can be made in it. Nothing was written.`);
+    this.name = "NotAFolderError";
+  }
+}
+
 /** 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) => {
@@ -135,8 +160,61 @@ judges: []
   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 {
+export interface InitOptions {
+  /** The folder init was given, resolved against `cwd`. None: the current project, the home, or ~/static-fire. */
+  folder?: string;
+  cwd?: string;
+  /** Where HOME (for ~/static-fire and the saved home) and XDG_CONFIG_HOME are read. */
+  env?: Env;
+  PATH?: string;
+}
+
+/**
+ * `static-fire init`. Throws HomeNotProjectError with no folder when the saved home is not a project any more, and
+ * NotAFolderError when the folder is a file; both before anything is written.
+ */
+export function runInit(o: InitOptions = {}): InitReport {
+  const env = o.env ?? process.env;
+  const cwd = resolve(o.cwd ?? process.cwd());
+  const PATH = o.PATH ?? env.PATH ?? "";
+  const saved = readHome(env);
+  const savedIsProject = saved !== null && existsSync(join(saved, PROJECT_FILE));
+
+  // With no folder: the project init runs in, else the home, else the default home folder.
+  const here = o.folder === undefined ? findProject(cwd) : null;
+  let target: string;
+  if (o.folder !== undefined) target = resolve(cwd, o.folder);
+  else if (here) target = here;
+  else if (saved) {
+    if (!savedIsProject) throw new HomeNotProjectError(saved);
+    target = saved;
+  } else target = defaultHomeFolder(env);
+
+  if (!findProject(target)) {
+    if (existsSync(target) && !statSync(target).isDirectory()) throw new NotAFolderError(target);
+    try {
+      mkdirSync(target, { recursive: true });
+    } catch (e) {
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code === "ENOTDIR" || code === "EEXIST") throw new NotAFolderError(target);
+      throw e;
+    }
+  }
+  const report = initProject(target, PATH);
+
+  // The first home only: init inside a project with no folder writes nothing, and a home that is set never changes.
+  let home = saved, homeSaved = false;
+  if (!saved && !here) {
+    home = saveHome(report.project, env);
+    homeSaved = true;
+  }
+  const notes = [...report.notes];
+  if (saved && !savedIsProject) notes.push(new HomeNotProjectError(saved).message);
+  return { ...report, notes, home, isHome: home !== null && resolve(home) === report.project, homeSaved };
+}
+
+/** Make a project in `dir` (the current folder by default), or change nothing when `dir` is already in one. The home is not read or saved here. */
+export function initProject(dir = process.cwd(), PATH = process.env.PATH ?? ""): ProjectInit {
   const root = resolve(dir);
   const harnesses = reportHarnesses(PATH);
   const existing = findProject(root);
@@ -195,7 +273,7 @@ export function initProject(dir = process.cwd(), PATH = process.env.PATH ?? ""):
 }
 
 /** The outside tools section of the text report. */
-function formatTools(r: InitReport): string[] {
+function formatTools(r: ProjectInit): 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];
@@ -211,13 +289,25 @@ function formatTools(r: InitReport): string[] {
   return lines;
 }
 
+/** The line that says if the project is the home. */
+function homeLine(r: InitReport): string {
+  if (r.homeSaved) return "it is now the home: a command run outside any project uses it";
+  if (r.isHome) return "it is the home: a command run outside any project uses it";
+  if (r.home) return `it is not the home. The home is ${r.home}, and it is not changed.`;
+  return "it is not the home, and no home is set. Run `static-fire home <folder>` with a project folder to set one.";
+}
+
 /** 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`;
+  if (!r.created) {
+    const head = r.isHome && !r.homeSaved ? `the home project: ${r.project}` : `already a Static Fire project: ${r.project}`;
+    return `${[head, "nothing changed in it", homeLine(r), ...r.notes.map((n) => `note: ${n}`), ...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}`,
+    homeLine(r),
     `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"}`,

package/src/core/plan.ts

@@ -0,0 +1,84 @@
+// The plan in runs: what a batch or a regrade will start, in the units a subscription counts. Agent runs for each
+// config and judge calls for the judge (DEC-008 of #71). The counts come from the plans the engine runs:
+// batch.ts plannedTrials (the trials startBatch queues) and judgeCallRange below, which counts with grade.ts
+// planBatches and score.ts firstRoundVotes (the rules `grade` runs), so they cannot drift from what starts.
+// `run --plan` and `regrade --plan` print it and start nothing; `--json` prints it as JSON.
+import { plannedTrials, type BatchPlan } from "./batch";
+import { planBatches } from "./grade";
+import { configLabel } from "./label";
+import type { RegradePlan } from "./regrade";
+import { firstRoundVotes } from "./score";
+import type { Task } from "./types";
+
+/**
+ * The judge calls one grading of an output makes, as the fewest and the most: one call per vote for each batch of
+ * planBatches (the batching `grade` uses). The fewest is when the first round of votes agrees in every batch
+ * (firstRoundVotes), the most when every planned vote runs. A retry of an answer that does not parse is not
+ * counted, and an output that is missing gets no judge call.
+ */
+export function judgeCallRange(task: Pick<Task, "gates" | "measures">, votes: number): { min: number; max: number } {
+  const calls = planBatches(task).length;
+  return { min: calls * Math.min(firstRoundVotes(votes), votes), max: calls * votes };
+}
+
+/** What the judge call counts leave out (#74): judge.ts tries an answer that does not parse once more. */
+export const NOT_COUNTED = "the one retry of a judge call whose answer does not parse";
+
+export interface PlanInRuns {
+  command: "run" | "regrade";
+  /** Trials the batch starts, or the regrade grades. */
+  trials: number;
+  /** One per config of a batch, in the batch's order; empty for a regrade. A human config needs no agent run. */
+  agentRuns: { config: string; label: string; harness: string; trials: number; agentRuns: number }[];
+  /** Fewest: the first round of votes agrees in every call group. Most: every planned vote runs. `notCounted` says what is left out. */
+  judgeCalls: { judge: string; label: string; votes: number; min: number; max: number; notCounted: string };
+  /** Regrade only: the trials that passed the filters, and why the others are not graded. */
+  matched?: number;
+  skipped?: RegradePlan["skipped"];
+  /** Run only: how many tasks and configs. */
+  tasks?: number;
+  configs?: number;
+}
+
+/** The plan in runs of a planned batch. */
+export function batchPlanInRuns(plan: BatchPlan): PlanInRuns {
+  const trials = plannedTrials(plan);
+  const judgeCalls = { judge: plan.judge.id, label: plan.judge.label, votes: plan.votes, min: 0, max: 0, notCounted: NOT_COUNTED };
+  for (const { task } of trials) {
+    const r = judgeCallRange(task, plan.votes);
+    judgeCalls.min += r.min;
+    judgeCalls.max += r.max;
+  }
+  return {
+    command: "run", trials: trials.length, tasks: plan.tasks.length, configs: plan.configs.length,
+    agentRuns: plan.configs.map((c) => {
+      const n = trials.filter((t) => t.config.id === c.id).length;
+      return { config: c.id, label: configLabel(c), harness: c.harness, trials: n, agentRuns: c.harness === "human" ? 0 : n };
+    }),
+    judgeCalls,
+  };
+}
+
+/** The plan in runs of a regrade: judge calls only. */
+export function regradePlanInRuns(plan: RegradePlan): PlanInRuns {
+  return {
+    command: "regrade", trials: plan.todo.length, agentRuns: [], matched: plan.matched, skipped: plan.skipped,
+    judgeCalls: { judge: plan.judge.id, label: plan.judge.label, votes: plan.votes, ...plan.judgeCalls, notCounted: NOT_COUNTED },
+  };
+}
+
+const s = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** The plan as text: a heading line, one line per config, one line for the judge, and what is not counted when there are judge calls. */
+export function formatPlan(p: PlanInRuns): string {
+  const head = p.command === "run"
+    ? `plan: ${s(p.tasks!, "task")} × ${s(p.configs!, "config")}, ${s(p.trials, "trial")}`
+    : `plan: ${s(p.trials, "trial")} to grade, of ${p.matched} matching; no agent runs`;
+  const rows = p.agentRuns.map((r) => `  agent runs   ${String(r.agentRuns).padStart(4)}  ${r.label}  (${r.config}${r.harness === "human" ? `; ${s(r.trials, "trial")}, no agent run for a human config` : ""})`);
+  const j = p.judgeCalls;
+  const calls = j.min === j.max ? String(j.max) : `${j.min} to ${j.max}`;
+  const why = j.min === j.max ? "" : `; the fewest when the first votes agree`;
+  rows.push(`  judge calls  ${calls.padStart(4)}  ${j.label}  (${j.judge}; ${s(j.votes, "vote")}${why})`);
+  if (j.max) rows.push(`  not counted  ${j.notCounted}`);
+  return [head, ...rows].join("\n");
+}

package/src/core/project.ts

@@ -1,10 +1,14 @@
 // The two roots. The engine root holds the engine's own files: its source, the dashboard and pricing.yaml. It
 // comes from this file's location, never from the current folder, so it holds when the engine runs from
 // node_modules. The project root is the user's folder: static-fire.yaml, configs/, judges.yaml, suites/,
-// evals/, the record store and trial artifacts in runs/, and the Profile cache in .cache/. A command finds it
-// by walking up from the current folder to static-fire.yaml. Nothing of a project is written to the engine root.
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+// evals/, the record store and trial artifacts in runs/, and the Profile cache in .cache/. A command uses the
+// nearest project at or above the current folder; outside any project it uses the home, the one project saved in
+// the user's config folder (ADR-0010). Nothing of a project is written to the engine root.
+//
+// This module is the one place that finds the project a command uses and that reads and writes the saved home.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 
 export const ENGINE_ROOT = resolve(import.meta.dir, "../..");
 export const PROJECT_FILE = "static-fire.yaml";
@@ -17,7 +21,91 @@ export class NoProjectError extends Error {
   }
 }
 
-/** The first folder from `from` upward that holds static-fire.yaml, or null. */
+/** The saved home is not a project any more: its folder is gone, or has no static-fire.yaml. */
+export class HomeNotProjectError extends Error {
+  constructor(readonly home: string) {
+    super(`the home, ${home}, is not a Static Fire project any more: there is no ${PROJECT_FILE} in it. Run \`static-fire home <folder>\` with a project folder to set the home again.`);
+    this.name = "HomeNotProjectError";
+  }
+}
+
+/** A folder given as the home holds no static-fire.yaml. */
+export class NotAProjectError extends Error {
+  constructor(folder: string) {
+    super(`${folder} is not a Static Fire project: there is no ${PROJECT_FILE} in it. The home is not changed.`);
+    this.name = "NotAProjectError";
+  }
+}
+
+export type Env = Record<string, string | undefined>;
+
+/**
+ * The file that holds the saved home: XDG_CONFIG_HOME/static-fire/home when XDG_CONFIG_HOME is an absolute path,
+ * else HOME/.config/static-fire/home. It holds one line, the home's absolute folder, and nothing else. HOME is read
+ * from `env`, because Bun's os.homedir() does not see a HOME changed while the process runs (tests move it).
+ */
+export function homeFile(env: Env = process.env): string {
+  const xdg = env.XDG_CONFIG_HOME;
+  const config = xdg && isAbsolute(xdg) ? xdg : join(userFolder(env), ".config");
+  return join(config, "static-fire", "home");
+}
+
+/** The user's own folder: HOME from `env`, for the reason homeFile gives. */
+function userFolder(env: Env): string {
+  return env.HOME || homedir();
+}
+
+/** Where the first `init` outside any project makes the home: HOME/static-fire. XDG_CONFIG_HOME does not move it. */
+export function defaultHomeFolder(env: Env = process.env): string {
+  return join(userFolder(env), "static-fire");
+}
+
+/** The saved home's folder, or null when none is saved (no file, or an empty one). */
+export function readHome(env: Env = process.env): string | null {
+  const file = homeFile(env);
+  if (!existsSync(file)) return null;
+  return readFileSync(file, "utf8").trim() || null;
+}
+
+/** Saves `folder` as the home when it holds static-fire.yaml; else throws NotAProjectError and changes nothing. */
+export function saveHome(folder: string, env: Env = process.env): string {
+  const root = resolve(folder);
+  if (!existsSync(join(root, PROJECT_FILE))) throw new NotAProjectError(root);
+  const file = homeFile(env);
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;   // a reader never sees half a file
+  writeFileSync(tmp, `${root}\n`);
+  renameSync(tmp, file);
+  return root;
+}
+
+/** The project a command uses: `home` is true when it is the saved home, used from outside any project. */
+export interface ResolvedProject { root: string; home: boolean }
+
+/**
+ * The nearest project from `from` upward; outside any project, the saved home. Throws NoProjectError when there
+ * is neither, and HomeNotProjectError when the saved home is not a project any more. Reads only.
+ */
+export function resolveProject(from = process.cwd(), env: Env = process.env): ResolvedProject {
+  const near = findProject(from);
+  if (near) return { root: near, home: false };
+  const home = readHome(env);
+  if (!home) throw new NoProjectError(resolve(from));
+  if (!existsSync(join(home, PROJECT_FILE))) throw new HomeNotProjectError(home);
+  return { root: home, home: true };
+}
+
+/** The project resolveProject finds, or null where it would throw. */
+export function currentProject(from = process.cwd(), env: Env = process.env): string | null {
+  try {
+    return resolveProject(from, env).root;
+  } catch (e) {
+    if (e instanceof NoProjectError || e instanceof HomeNotProjectError) return null;
+    throw e;
+  }
+}
+
+/** The first folder from `from` upward that holds static-fire.yaml, or null. Does not read the home. */
 export function findProject(from = process.cwd()): string | null {
   for (let dir = resolve(from); ; dir = dirname(dir)) {
     if (existsSync(join(dir, PROJECT_FILE))) return dir;
@@ -25,11 +113,9 @@ export function findProject(from = process.cwd()): string | null {
   }
 }
 
-/** The project root found from `from`. Throws NoProjectError when there is none. */
+/** The root of the project resolveProject finds from `from`. Throws as resolveProject does. */
 export function projectRoot(from = process.cwd()): string {
-  const root = findProject(from);
-  if (!root) throw new NoProjectError(resolve(from));
-  return root;
+  return resolveProject(from).root;
 }
 
 export interface ProjectPaths {

package/src/core/regrade.ts

@@ -8,6 +8,7 @@
 // grading and the trial is graded again. The stale row is left as it is: the store cannot tell it from a grading
 // another process is doing right now.
 import { DEFAULT_VOTES, gradeTrial } from "./batch";
+import { judgeCallRange } from "./plan";
 import type { Store, TrialRecord } from "./db";
 import { gradingIdentity, taskIdentity, configKey } from "./identity";
 import { loadConfigs } from "./authored";
@@ -69,6 +70,8 @@ export interface RegradePlan {
   /** The trials to grade, in id order, with the grading hash each gets. */
   todo: { trialId: string; taskId: string; gradingHash: string }[];
   skipped: RegradeSkipped;
+  /** The judge calls grading `todo` makes, fewest and most (plan.ts judgeCallRange). */
+  judgeCalls: { min: number; max: number };
 }
 
 export interface RegradeCounts {
@@ -157,7 +160,13 @@ function resolve(store: Store, f: RegradeFilters, o: RegradeOptions): Resolved {
     todo.push({ trialId: t.id, taskId: t.taskId, gradingHash: h.gradingHash });
   }
   const tasks = new Map([...current].flatMap(([id, h]) => (h ? [[id, h.task] as const] : [])));
-  return { plan: { judge, votes, matched: trials.length, todo, skipped }, trials: new Map(trials.map((t) => [t.id, t])), tasks };
+  const judgeCalls = { min: 0, max: 0 };
+  for (const x of todo) {
+    const r = judgeCallRange(tasks.get(x.taskId)!, votes);
+    judgeCalls.min += r.min;
+    judgeCalls.max += r.max;
+  }
+  return { plan: { judge, votes, matched: trials.length, todo, skipped, judgeCalls }, trials: new Map(trials.map((t) => [t.id, t])), tasks };
 }
 
 function canLoad(catalog: Catalog, id: string) {

package/src/core/score.ts

@@ -1,4 +1,4 @@
-// Pure scoring (ADR-0001). Verdicts → measure % → task score → Suite Index → Workflow Index.
+// Pure scoring (ADR-0001). Verdicts → measure % → task score → Suite Index → Agent Performance Index.
 // No I/O here, so every rule is covered by tests/score.test.ts.
 import { configLabel, EFFORTS } from "./label";
 import type { ConfigSummary, Experiment, ExperimentSummary, Grades, Stat, Task, TaskSummary, Trial, Verdict, Vote } from "./types";

package/src/core/task-page.ts

@@ -0,0 +1,54 @@
+// What the dashboard's Tasks page shows of a task (#79): what the agent gets, the output path, the gates (the
+// engine's output gate first) and the criteria by measure. Built from an allowlist, so the graders' own material (references, sources, the held-out
+// file) and grading details (context, check details, evidence, derived evidence scripts) never reach the page.
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { OUTPUT_GATE } from "./grade";
+import type { Criterion, Level, Task } from "./types";
+
+export interface TaskPageCriterion { id: string; question: string; level: Level; grader: Criterion["grader"] }
+
+export interface TaskPage {
+  id: string;
+  title: string;
+  description: string;
+  version?: number;
+  prompt: string;
+  /** The input files as the agent finds them in its workspace (`inputs/brief.md`). */
+  inputFiles: string[];
+  /** The project files, copied to the workspace root. Only when the task has `project`. */
+  projectFiles?: string[];
+  output: string;
+  /** The engine's own output gate (grade.ts OUTPUT_GATE), which every task has, first, then the task's own gates. */
+  gates: TaskPageCriterion[];
+  measures: { id: string; label: string; weight: number; criteria: TaskPageCriterion[] }[];
+}
+
+/** File paths under `dir`, relative to `from`, with "/" separators. Names that start with "." are left out, as the task hash leaves them out. */
+function fileNames(dir: string, from: string): string[] {
+  const out: string[] = [];
+  const walk = (p: string) => {
+    if (statSync(p).isFile()) { out.push(relative(from, p).split(sep).join("/")); return; }
+    for (const f of readdirSync(p).sort()) if (!f.startsWith(".")) walk(join(p, f));
+  };
+  if (existsSync(dir)) walk(dir);
+  return out;
+}
+
+const criterion = (c: Criterion): TaskPageCriterion => ({ id: c.id, question: c.question, level: c.level, grader: c.grader });
+
+export function taskPage(task: Task): TaskPage {
+  const projectDir = task.project ? join(task.dir, task.project) : null;
+  return {
+    id: task.id,
+    title: task.title,
+    description: task.description ?? "",
+    ...(task.version != null ? { version: task.version } : {}),
+    prompt: task.prompt,
+    inputFiles: fileNames(join(task.dir, task.inputs), task.dir),
+    ...(projectDir ? { projectFiles: fileNames(projectDir, projectDir) } : {}),
+    output: task.output,
+    gates: [OUTPUT_GATE, ...(task.gates ?? [])].map(criterion),
+    measures: task.measures.map((m) => ({ id: m.id, label: m.label, weight: m.weight ?? 1, criteria: m.criteria.map(criterion) })),
+  };
+}