catherd-cli 1.2.1 → 1.3.0

package/src/services/catalog-refresh.ts

@@ -12,7 +12,7 @@ import {
   scoresOf,
 } from "../domain/catalog.ts";
 import { DIFFICULTIES, type Difficulty, KINDS, type Kind } from "../domain/lane.ts";
-import type { SourcesFile } from "../domain/sources.ts";
+import { defaultEffortOf, type SourcesFile } from "../domain/sources.ts";
 import type { SourceTransport } from "../infra/sources/http.ts";
 import { adjacent, derive, type RawAnswers } from "./source-derive.ts";
 import { cachedAnswers, syncSources } from "./source-sync.ts";
@@ -72,6 +72,7 @@ export function rebuildShipped(
     direct.filter((s) => s.confidence !== "inferred"),
     new Set(),
     ctx.now,
+    (f) => defaultEffortOf(ctx.sources, f),
   );
   const scores = best([...direct, ...spread], ctx.now);
   const benchmark = (d: Dim) => {

package/src/services/dispatches.ts

@@ -27,6 +27,8 @@ const AdmitSchema = z.looseObject({
   failoverOf: z.string().optional(),
   access: z.enum(ACCESS),
   isolated: z.boolean(),
+  /** the role's network grant (1.1 §5) when admitted; absent before 1.3 */
+  network: z.boolean().optional(),
   cliVersion: z.string().nullable(),
   admittedAt: z.string(),
   repo: z.string(),

package/src/services/doctor-access.ts

@@ -1,5 +1,5 @@
 import { realTmpdir } from "../adapters/access.ts";
-import type { AccessShell } from "../adapters/backend.ts";
+import type { AccessProbeId, AccessShell } from "../adapters/backend.ts";
 import { adapterFor } from "../adapters/registry.ts";
 import "../adapters/all.ts";
 import { tryParseRung } from "../domain/ids.ts";
@@ -12,7 +12,7 @@ import type { Check } from "./doctor-checks.ts";
 // Spec §5 and §12: the five access probes doctor runs per backend that serves a workspace-write role, each
 // in that backend's worker shell with the grants a worker gets, and the rows that report them.
 
-export type ProbeId = "lock" | "temp" | "loopback" | "https" | "docker";
+export type ProbeId = AccessProbeId;
 
 /**
  * What the probes reach: npm's ping, through HTTPS_PROXY when it is set (Bun's fetch honours it), and
@@ -131,8 +131,13 @@ export async function runProbes(shell: AccessShell, network: boolean): Promise<P
   return out;
 }
 
-/** The fix for a failed probe, per backend: Codex's sandbox holds catherd's grants; the others run unsandboxed. */
-function fixFor(backend: string, id: ProbeId): string {
+/**
+ * The fix for a failed probe: the sandbox's own when its shell names one; Codex's sandbox holds catherd's grants;
+ * the others run unsandboxed.
+ */
+function fixFor(backend: string, id: ProbeId, shell: AccessShell): string {
+  const own = shell.fixes?.[id];
+  if (own) return own;
   if (backend === "codex") {
     const override =
       "catherd passes this grant to Codex itself (with your top-level [sandbox_workspace_write] writable_roots added): check that no --profile or managed requirements.toml overrides it";
@@ -173,7 +178,7 @@ export async function accessChecks(profiles: Profile[], installed: ReadonlySet<s
   const checks: Check[] = [];
   for (const [id, network] of workspaceWriteNetwork(profiles)) {
     const a = adapterFor(id);
-    if (!a?.accessShell) continue;
+    if (!a) continue;
     if (!installed.has(id)) {
       checks.push({
         id: `access:${id}`,
@@ -184,7 +189,9 @@ export async function accessChecks(profiles: Profile[], installed: ReadonlySet<s
       });
       continue;
     }
-    const shell = await a.accessShell({ network }).catch((e: unknown) => String(e));
+    const shell = a.accessShell
+      ? await a.accessShell({ network }).catch((e: unknown) => String(e))
+      : `no way to run a shell in ${id}'s sandbox without a model turn; the live kit (docs/dev/live-verification.md) runs the five probes as one worker turn`;
     if (id === "codex")
       checks.push(
         typeof shell === "string"
@@ -217,7 +224,7 @@ export async function accessChecks(profiles: Profile[], installed: ReadonlySet<s
             state: "warn",
             word: "blocked",
             detail: `in ${shell.how}, a worker cannot: ${failed.map((r) => `${r.label} (${r.why})`).join("; ")}`,
-            fix: failed.map((r) => `${r.label}: ${fixFor(id, r.id)}`).join("\n"),
+            fix: failed.map((r) => `${r.label}: ${fixFor(id, r.id, shell)}`).join("\n"),
           }
         : {
             ...base,

package/src/services/doctor-backends.ts

@@ -4,6 +4,7 @@ import "../adapters/all.ts";
 import { ADAPTER_IDS, tryParseRung } from "../domain/ids.ts";
 import type { Profile } from "../domain/profile.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
+import { probeBackend } from "./backends.ts";
 import { refreshDiscovery } from "./catalog-service.ts";
 import { type Check, errText, fixOf } from "./doctor-checks.ts";
 
@@ -30,6 +31,7 @@ const PROBLEM_WORD: Record<string, string> = {
   E_BACKEND_MISSING: "missing",
   E_BACKEND_TOO_OLD: "too old",
   E_BACKEND_NOT_LOGGED_IN: "not logged in",
+  E_BACKEND_CANNOT_RUN: "cannot run",
 };
 
 /**
@@ -91,7 +93,7 @@ export async function backendChecks(
   for (const id of ADAPTER_IDS) {
     const a = adapterFor(id);
     if (!a) continue;
-    const probe: Probe = await a.probe().catch((e: unknown) => ({
+    const probe: Probe = await probeBackend(a).catch((e: unknown) => ({
       installed: false,
       version: null,
       versionOk: false,
@@ -101,6 +103,9 @@ export async function backendChecks(
       ],
     }));
     if (probe.installed) installed?.add(id);
+    // spec 1.3 §4.7: what the probe found worth knowing, nothing to fix (an `agent` on PATH that is not Cursor)
+    for (const i of probe.info ?? [])
+      checks.push({ id: i.id, label: i.label, state: "info", word: "info", detail: i.detail });
     const problem = probe.problems[0];
     const use = used.get(id);
     if (!problem) {
@@ -123,6 +128,10 @@ export async function backendChecks(
             }
           : { id: `backend:${id}`, label: id, state: "ok", word: "ready", detail },
       );
+      // spec 1.3 §6.6: asked only of a logged-in CLI (a logged-out agy -p would open a browser)
+      const quota = probe.loggedIn && a.quota ? await a.quota().catch(() => null) : null;
+      if (quota)
+        checks.push({ id: `quota:${id}`, label: `${id} quota`, state: "info", word: "quota", detail: quota });
       continue;
     }
     checks.push({

package/src/services/doctor-checks.ts

@@ -1,6 +1,7 @@
 import { readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { errorMessage, isCatherdError } from "../domain/errors.ts";
+import type { Profile } from "../domain/profile.ts";
 import { claudeHome, locksDir } from "../infra/paths.ts";
 import { ensurePrivateDir, PRIVATE_FILE } from "../infra/store.ts";
 import { agentLinkState } from "./agent-links.ts";
@@ -146,3 +147,27 @@ export function agentsCheck(): Check {
     ? { ...base, state: "ok", word: "ready", detail: `${links.ok.length} linked` }
     : { ...base, state: "skip", word: "none", detail: "no profile uses a native Claude rung" };
 }
+
+/** The browser CLI the ui-reviewer's prompt takes its screenshots with. */
+const UI_BROWSER = "agent-browser";
+
+/**
+ * The ui-reviewer takes screenshots with agent-browser: a profile that turns it on, on a machine without it,
+ * dispatches a role that cannot do its job. Nothing to say when it is on PATH or no profile turns the role on.
+ */
+export function uiBrowserCheck(profiles: Profile[], onPath: (bin: string) => string | null): Check | null {
+  const on = profiles.filter((p) => p.roles["ui-reviewer"].enabled).map((p) => p.name);
+  if (!on.length || onPath(UI_BROWSER)) return null;
+  return {
+    id: "ui-browser",
+    label: UI_BROWSER,
+    state: "warn",
+    word: "missing",
+    detail: `${UI_BROWSER} is not on PATH, so ui-reviewer (${on.join(", ")}) cannot take screenshots`,
+    fix: [
+      `npm i -g ${UI_BROWSER}`,
+      "or turn the role off:",
+      ...on.map((n) => `catherd profile set roles.ui-reviewer.enabled false --profile ${n}`),
+    ].join("\n"),
+  };
+}

package/src/services/doctor.ts

@@ -19,6 +19,7 @@ import {
   locksCheck,
   mcpCheck,
   pluginCheck,
+  uiBrowserCheck,
 } from "./doctor-checks.ts";
 import { credentialsPath, jevKey, savedJevKey, testJevKey } from "./jev-service.ts";
 import {
@@ -321,6 +322,8 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
       detail: "the plugin's MCP launcher runs bunx when no global catherd is installed",
       fix: "put Bun's bin folder (~/.bun/bin) on PATH",
     });
+  const browser = uiBrowserCheck(mine, onPath);
+  if (browser) checks.push(browser);
   let corrupt: ReturnType<typeof listRuns>["corrupt"] = [];
   try {
     corrupt = listRuns().corrupt;

package/src/services/finalize.ts

@@ -222,6 +222,7 @@ async function compute(run: Run, d: Dispatch): Promise<RunRecord> {
     threadHeavy: o.tokens.input >= THREAD_HEAVY_INPUT,
     access: a.access,
     isolated: a.isolated,
+    ...(a.network === undefined ? {} : { network: a.network }),
     images: o.images,
     error: o.error,
     replyPath: relative(run.dir, p.reply),

package/src/services/lane-service.ts

@@ -4,6 +4,7 @@ import { CatherdError } from "../domain/errors.ts";
 import { assertId, ID_PATTERN, parseRung } from "../domain/ids.ts";
 import { assertLaneHeader, type Difficulty, type Kind } from "../domain/lane.ts";
 import type { Role } from "../domain/roles.ts";
+import { cell } from "../domain/util.ts";
 import {
   type ClimbReason,
   currentRoute,
@@ -28,11 +29,11 @@ import {
 } from "./milestones.ts";
 import type { Deps, Verdict } from "./ports.ts";
 import {
+  appendKnowledge,
   appendLedger,
   appendOutcome,
   appendRoute,
   findRun,
-  knowledgeFile,
   readRoutes,
   type Run,
   runFile,
@@ -41,7 +42,6 @@ import {
 import { writeDigest } from "./protocol.ts";
 import { openQuestions } from "./questions.ts";
 import { type Notes, type NotesPatch, refreshState } from "./state.ts";
-import { appendPrivate } from "../infra/store.ts";
 
 const withHints = (hints: string[]) => (hints.length ? { hints } : {});
 
@@ -212,8 +212,6 @@ export async function climb(
   };
 }
 
-const cell = (s: string) => s.replace(/[|\n]/g, "/").replace(/\s+/g, " ").trim();
-
 export const LAND_SKIPS = ["docs-only", "no-code"] as const;
 export type LandSkip = (typeof LAND_SKIPS)[number];
 
@@ -348,12 +346,7 @@ export async function land(
     hints.push(
       `land: no routed lane is in milestone "${i.milestone}" (routed: ${routed.slice(0, 5).join(", ")}${routed.length > 5 ? ", …" : ""}); check its name: no lane outcome was recorded`,
     );
-  if (i.learned) {
-    appendPrivate(
-      knowledgeFile(run.meta.repo),
-      `- ${now.toISOString().slice(0, 10)} ${run.meta.title} ${i.milestone}: ${cell(i.learned)}\n`,
-    );
-  }
+  if (i.learned) appendKnowledge(run.meta.repo, now, `${run.meta.title} ${i.milestone}`, i.learned);
   // spec 1.1 §10: the milestone's digest, which the milestone push links
   const digest = writeDigest(run, {
     milestone: i.milestone,

package/src/services/profile-service.ts

@@ -15,7 +15,7 @@ import {
   type ProfilePatch,
   resolveProfile,
 } from "../domain/profile.ts";
-import { repairs, type Validation, validateProfile } from "../domain/profile-rules.ts";
+import { repairs, type Validation } from "../domain/profile-rules.ts";
 import { ROLES } from "../domain/roles.ts";
 import { withFileLockSync } from "../infra/filelock.ts";
 import { configDir } from "../infra/paths.ts";
@@ -37,7 +37,7 @@ import {
   readProjects,
   requireProfile,
   roleEnforcement,
-  runnableBackends,
+  validateHere,
   validateNamed,
 } from "./profile-store.ts";
 
@@ -67,7 +67,7 @@ function saveAndLink(name: string, doc: ProfileDoc): Synced {
 }
 
 const validate = (doc: ProfileDoc, name: string): Validation =>
-  validateProfile(resolveProfile(doc, name), loadCatalog({ timings: false }), runnableBackends(), doc);
+  validateHere(resolveProfile(doc, name), loadCatalog({ timings: false }), doc);
 
 /** What a save returns: the port's ProfileSaved (one type for the CLI, the TUI and the MCP tools). */
 export type Saved = ProfileSaved;

package/src/services/profile-store.ts

@@ -14,11 +14,13 @@ import {
   ProfileDocSchema,
   resolveProfile,
 } from "../domain/profile.ts";
-import { type Validation, validateProfile } from "../domain/profile-rules.ts";
+import { type Issue, type Validation, validateProfile } from "../domain/profile-rules.ts";
+import type { Catalog } from "../domain/catalog.ts";
 import type { Access } from "../domain/record.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
 import { configDir } from "../infra/paths.ts";
 import { readJsonFile } from "../infra/store.ts";
+import { standInFor } from "./backends.ts";
 import { backendOfKey, loadCatalog } from "./catalog-service.ts";
 
 // Spec §7.3, the read side of the profile service: where profiles, config.json and projects.json live,
@@ -116,12 +118,114 @@ export const runnableBackends = (): string[] => ["claude", ...ADAPTER_IDS.filter
 export const keyRunnable = (key: string, backends: string[] = runnableBackends()): boolean =>
   backends.includes(backendOfKey(key));
 
+/**
+ * Spec 1.3 §8: each backend `p` isolates whose isolated run logs in with an API key that is not in `env` (the
+ * environment catherd runs, and starts workers, in).
+ */
+export function isolationKeyErrors(
+  p: Profile,
+  env: Record<string, string | undefined> = process.env,
+): Issue[] {
+  const out: Issue[] = [];
+  for (const [id, h] of Object.entries(p.harness)) {
+    const key = h.isolated ? adapterFor(id)?.isolationKey : undefined;
+    if (key && !env[key])
+      out.push({
+        path: `harness.${id}.isolated`,
+        message: `an isolated ${id} run needs ${key}, which catherd's environment does not have`,
+        fix: `export ${key}=<key>, or catherd profile set harness.${id}.isolated false`,
+      });
+  }
+  return out;
+}
+
+/**
+ * Spec 1.3 §9 Q2: each enabled role whose rung, or a failover stand-in of one, runs natively on a backend that
+ * holds the role's access only when isolated (agy has no read-only flag).
+ */
+export function isolatedOnlyErrors(p: Profile): Issue[] {
+  const out: Issue[] = [];
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    if (!rc.enabled) continue;
+    // a stand-in the profile does not name is the one dispatch picks on its own (a paired backend's or the
+    // adapter's); one on the rung's own backend adds nothing, since the rung's own error names that backend
+    const runs = [
+      ...rc.rungs.map((r) => [r, `roles.${role}.rungs`]),
+      ...rc.rungs.flatMap((r) => {
+        if (p.failover[r]) return [[p.failover[r], `failover.${r}`, null]];
+        const s = standInFor(p.failover, r);
+        return s && tryParseRung(s)?.backend !== tryParseRung(r)?.backend
+          ? [[s, `roles.${role}.rungs`, r]]
+          : [];
+      }),
+    ] as [string, string, string | null][];
+    for (const [rung, path, auto] of runs) {
+      const b = tryParseRung(rung)?.backend;
+      if (!b || p.harness[b]?.isolated || !adapterFor(b)?.isolatedOnly?.includes(rc.access)) continue;
+      const isolate = `isolate ${b} (catherd profile set harness.${b}.isolated true)`;
+      out.push({
+        path,
+        message: `${rung}${auto ? `, the automatic stand-in of ${auto}` : ""}: native ${b} cannot hold the ${role} role to ${rc.access}`,
+        fix: auto
+          ? `${isolate}, or name another stand-in (catherd profile set failover.${auto} <rung>)`
+          : `${isolate}, or put this role on another backend`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Spec §4.6: with `budget.usd` set, one warning per backend an enabled role runs on whose adapter reports no
+ * dollar cost, since that cap never sees what the backend spends. Never an error: the cap still counts the rest.
+ */
+export function budgetUsdWarnings(p: Profile): Issue[] {
+  if (p.budget.usd === undefined) return [];
+  const blind = new Map<string, Role[]>();
+  const note = (rung: string, role: Role) => {
+    const b = tryParseRung(rung)?.backend;
+    // no adapter (native `claude`, whose subagents report their own cost): nothing to warn about
+    if (!b || adapterFor(b)?.reportsCost !== false) return;
+    const roles = blind.get(b) ?? [];
+    if (!roles.includes(role)) roles.push(role);
+    blind.set(b, roles);
+  };
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    if (!rc.enabled) continue;
+    for (const rung of rc.rungs) {
+      note(rung, role);
+      // a quota failover runs the role on its stand-in (its own, paired or the backend's), which the cap must see
+      const standIn = standInFor(p.failover, rung);
+      if (standIn) note(standIn, role);
+    }
+  }
+  return [...blind].map(([b, roles]) => ({
+    path: "budget.usd",
+    message: `budget.usd will not see ${b}'s spend: ${b} reports no dollar cost (${roles.join(", ")} run on it)`,
+    fix: "cap it with budget.tokens or budget.minutes: catherd profile set budget.tokens <n>",
+  }));
+}
+
+/**
+ * Spec §7.1 validation on this machine: the backends catherd can run here, the keys isolation needs, the
+ * accesses a backend holds only when isolated, and the backends a dollar budget cannot see.
+ */
+export function validateHere(p: Profile, c: Catalog, doc?: ProfileDoc): Validation {
+  const v = validateProfile(p, c, runnableBackends(), doc);
+  return {
+    errors: [...v.errors, ...isolationKeyErrors(p), ...isolatedOnlyErrors(p)],
+    warnings: [...v.warnings, ...budgetUsdWarnings(p)],
+  };
+}
+
 /** `repo`: the git toplevel whose listing route reads (opencode lists its models per repository). */
 export function validateNamed(name?: string, repo: string | null = null): Validation {
   const n = name ?? activeName(repo);
   const doc = readProfileDoc(n);
   const catalog = loadCatalog({ timings: false, ...(repo === null ? {} : { repo }) });
-  return validateProfile(resolveProfile(doc, n), catalog, runnableBackends(), doc);
+  return validateHere(resolveProfile(doc, n), catalog, doc);
 }
 
 /** Spec D10: how strongly the backend holds a role to its access mode. */

package/src/services/run-service.ts

@@ -18,6 +18,7 @@ import type { Deps } from "./ports.ts";
 import {
   type AgentRun,
   appendAgentRun,
+  appendKnowledge,
   createRun,
   findRun,
   knowledgeFile,
@@ -182,13 +183,45 @@ export function recordAgentRun(
   return row;
 }
 
-/** What past runs of the repo learned; `repo` may be any path inside it. */
-export async function readKnowledge(repo: string): Promise<string> {
+/** The git toplevel of `repo`, any path inside it; refused outside a repository. */
+async function repoTop(repo: string): Promise<string> {
   const top = await gitToplevel(repo);
   if (!top)
     throw new CatherdError("E_IO_PATH", `${repo} is not inside a git repository`, {
       fix: "pass the path of the repository",
     });
-  const file = knowledgeFile(top);
-  return existsSync(file) ? readFileSync(file, "utf8") : "catherd: no knowledge recorded yet for this repo";
+  return top;
+}
+
+/** What past runs of the repo learned; `repo` may be any path inside it. */
+export async function readKnowledge(repo: string): Promise<string> {
+  const file = knowledgeFile(await repoTop(repo));
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  return text.trim() ? text : "catherd: no knowledge recorded yet for this repo";
+}
+
+/** Where the repo's knowledge.md is (it may not exist yet); `repo` may be any path inside it. */
+export async function knowledgePath(repo: string): Promise<{ repo: string; path: string }> {
+  const top = await repoTop(repo);
+  return { repo: top, path: knowledgeFile(top) };
+}
+
+/** The repo's knowledge.md as its lines, none when it is missing or blank; `repo` may be any path inside it. */
+export async function knowledgeLines(repo: string): Promise<{ repo: string; path: string; lines: string[] }> {
+  const at = await knowledgePath(repo);
+  const text = existsSync(at.path) ? readFileSync(at.path, "utf8") : "";
+  return { ...at, lines: text.split("\n").filter((l) => l.trim()) };
+}
+
+/** The source a line added by hand carries, where a landing puts its run's title and milestone. */
+const BY_HAND = "by hand";
+
+/** Appends one line of the user's own to the repo's knowledge.md, as `land`'s `learned` does; returns it. */
+export async function addKnowledge(repo: string, text: string, now: Date = new Date()): Promise<string> {
+  const top = await repoTop(repo);
+  if (!text.trim())
+    throw new CatherdError("E_INPUT_INVALID", "the knowledge line is empty", {
+      fix: 'pass one line of text, e.g. catherd knowledge add "the targeted test is bun test <file>"',
+    });
+  return appendKnowledge(top, now, BY_HAND, text);
 }

package/src/services/run-store.ts

@@ -5,7 +5,7 @@ import { CatherdError } from "../domain/errors.ts";
 import { assertId } from "../domain/ids.ts";
 import { type RunRecord, RunRecordSchema } from "../domain/record.ts";
 import type { OutcomeRow, RouteRow } from "../domain/route.ts";
-import { slug } from "../domain/util.ts";
+import { cell, slug } from "../domain/util.ts";
 import { withFileLock } from "../infra/filelock.ts";
 import { dataDir, repoDir, runsDir } from "../infra/paths.ts";
 import {
@@ -273,6 +273,16 @@ export function appendLedger(run: Run, row: string): void {
 /** Spec §4.7: what past runs of a repo learned, keyed by its git toplevel. */
 export const knowledgeFile = (toplevel: string): string => join(repoDir(toplevel), "knowledge.md");
 
+/**
+ * Appends one line to the repo's knowledge.md, `- <date> <source>: <text>` with `text` on one line, and returns
+ * it. The single writer of knowledge.md: `land`'s `learned` and `catherd knowledge add` both come through here.
+ */
+export function appendKnowledge(toplevel: string, at: Date, source: string, text: string): string {
+  const line = `- ${at.toISOString().slice(0, 10)} ${source}: ${cell(text)}`;
+  appendPrivate(knowledgeFile(toplevel), `${line}\n`);
+  return line;
+}
+
 const SERVER_OWNED = new Set([
   "meta.json",
   "state.md",

package/src/services/source-derive.ts

@@ -85,14 +85,22 @@ export function derive(raw: RawAnswers, ctx: DeriveContext): Derived {
       const { id, effort } = splitSourceRung(row.rung);
       const family = map.family(id);
       if (!family) (unmatched[source] ??= new Set()).add(id);
-      const e = effort ?? (family ? defaultEffortOf(ctx.sources, family) : "");
+      // spec 1.3 §7.1: a family with no effort (Composer) has one rung, #default, whatever effort a source names
+      const effortless = family !== null && familyEfforts(family).length === 0;
+      const e = effortless ? "default" : (effort ?? (family ? defaultEffortOf(ctx.sources, family) : ""));
       const key = `${map.key(family?.id ?? id)}#${e}`;
       const field = `${source}.${row.field}`;
       const at = table.get(field) ?? new Map<string, Keyed>();
       table.set(field, at);
       const had = at.get(key);
       if (!had || row.value > had.row.value)
-        at.set(key, { key, family, effort: e, assumed: effort === null && family !== null, row });
+        at.set(key, {
+          key,
+          family,
+          effort: e,
+          assumed: effort === null && family !== null && !effortless,
+          row,
+        });
     }
   const valuesOf = (f: FieldRef) =>
     new Map([...(table.get(`${f.source}.${f.field}`)?.values() ?? [])].map((k) => [k.key, k.row.value]));
@@ -163,7 +171,9 @@ export function derive(raw: RawAnswers, ctx: DeriveContext): Derived {
       const family = map.family(id);
       if (family && effort !== null) shipped.add(`${family.id}#${effort}|${s.dim}`);
     }
-  scores.push(...adjacent(ctx.models.families, scores, shipped, ctx.now));
+  scores.push(
+    ...adjacent(ctx.models.families, scores, shipped, ctx.now, (f) => defaultEffortOf(ctx.sources, f)),
+  );
 
   const { facts, warnings } = factsOf(raw, ctx, map);
   return {
@@ -203,13 +213,16 @@ function aaFeatures(table: Map<string, Map<string, Keyed>>): Derived["features"]
  * Spec 1.2 §4.3 `adjacent`: for each family effort a dimension has no value at (neither one in `direct` nor
  * one `shipped` names, as `<family>#<effort>|<dim>`), the best value in `direct` at the nearest effort that
  * has one (the weaker on a tie). A sync spreads only its own values, and never onto a value the shipped file
- * carries; `rebuildShipped` spreads the shipped file's published values, with an empty `shipped`.
+ * carries; `rebuildShipped` spreads the shipped file's published values, with an empty `shipped`. A family that
+ * one backend runs without an effort (Cursor's bare slug, spec 1.3 §7.1) also gets `#default`, carried from the
+ * value nearest `defaultEffort(family)`.
  */
 export function adjacent(
   families: Family[],
   direct: Score[],
   shipped: ReadonlySet<string>,
   now: number,
+  defaultEffort: (f: Family) => string = () => "high",
 ): Score[] {
   const out: Score[] = [];
   for (const f of families)
@@ -222,9 +235,11 @@ export function adjacent(
         if (!had || outranks(s, had, now)) byEffort.set(effort, s);
       }
       if (byEffort.size === 0) continue;
-      for (const e of familyEfforts(f)) {
+      const efforts = familyEfforts(f);
+      const bare = efforts.length > 0 && Object.values(f.on).some((o) => o && o.efforts.length === 0);
+      for (const e of bare ? [...efforts, "default"] : efforts) {
         if (byEffort.has(e) || shipped.has(`${f.id}#${e}|${dim}`)) continue;
-        const near = nearestEffort(e, [...byEffort.keys()]);
+        const near = nearestEffort(e === "default" ? defaultEffort(f) : e, [...byEffort.keys()]);
         const from = near ? byEffort.get(near) : undefined;
         if (!near || !from) continue;
         out.push({
@@ -261,7 +276,8 @@ function factsOf(
   for (const f of ctx.models.families) {
     const x: FamilyFacts = { on: {}, speed: {} };
     const vendor = (f as { vendor?: unknown }).vendor;
-    const own = md && typeof vendor === "string" ? modelsDevFacts(md, vendor, f.id) : null;
+    const own =
+      md && typeof vendor === "string" ? modelsDevFacts(md, vendor, modelsDevId(md, vendor, f, map)) : null;
     if (own?.price) x.price = own.price;
     if (own && own.toolUse !== null && own.imageIn !== null && own.reasoning !== null)
       x.capabilities = { toolUse: own.toolUse, imageIn: own.imageIn, reasoning: own.reasoning };
@@ -290,6 +306,15 @@ function factsOf(
   return { facts, warnings };
 }
 
+/**
+ * The id of `vendor`'s models.dev model that is `f`: its own id, else the first that maps to it (spec 1.3 §7.1:
+ * `gemini-3-8-flash` is Google's `gemini-3.8-flash`, `gemini-3-1-pro` its aliased `gemini-3.1-pro-preview`).
+ */
+function modelsDevId(md: unknown, vendor: string, f: Family, map: IdMapper): string {
+  const ids = Object.keys((md as Record<string, { models?: object }>)[vendor]?.models ?? {});
+  return ids.includes(f.id) ? f.id : (ids.find((id) => map.family(id) === f) ?? f.id);
+}
+
 /** The first entry of `list` whose id maps to `f` (OpenRouter's `:batch` variants never do). */
 const entryFor = <T extends { id: string }>(list: T[], f: Family, map: IdMapper): T | undefined =>
   list.find((m) => map.family(m.id) === f);