catherd-cli 1.1.0 → 1.2.0

package/src/entry/tui/effects.ts

@@ -2,7 +2,7 @@ import { realpathSync, statSync, watch } from "node:fs";
 import { adapterFor } from "../../adapters/registry.ts";
 import "../../adapters/all.ts";
 import { agentFiles } from "../../domain/agents.ts";
-import type { Catalog } from "../../domain/catalog.ts";
+import { type Catalog, rungInfo } from "../../domain/catalog.ts";
 import { HARNESS_KEYS, type Profile, type ProfileDoc, type ProfilePatch } from "../../domain/profile.ts";
 import { type Validation, validateProfile } from "../../domain/profile-rules.ts";
 import type { Access } from "../../domain/record.ts";
@@ -17,6 +17,11 @@ import {
 } from "../../services/catalog-service.ts";
 import { cancel } from "../../services/dispatch-service.ts";
 import { type DoctorReport, doctor } from "../../services/doctor.ts";
+import { ageText } from "../../services/doctor-sources.ts";
+import { valuesUsed, type ValueUsed } from "../../services/provenance.ts";
+import { evidenceLine, evidenceOf, runEvidence } from "../../services/run-evidence.ts";
+import { type SyncReport, sourcesStatus, syncSources } from "../../services/source-sync.ts";
+import { type Suggestion, suggestStandIns } from "../../services/standins.ts";
 import type { Synced } from "../../services/agent-links.ts";
 import {
   activate,
@@ -139,6 +144,46 @@ export interface Effects {
   create(name: string, from?: string): Saved;
   remove(name: string): Synced;
   refreshCatalog(): Promise<Refreshed[]>;
+  /** spec 1.2 §9 (`r`): syncs the public sources (each at most every 12 hours) */
+  syncSources(): Promise<SyncReport>;
+  /** spec 1.2 §9: each source's name, age and last error, as the `r` dialog shows them */
+  sources(): { source: string; name: string; age: string; error: string | null }[];
+  /** spec 1.2 §6.3: the three nearest stand-ins for a rung, for the treat-like picker */
+  suggest(c: Catalog, rung: string): Suggestion[];
+  /** spec 1.2 §5.3, §8: a rung's values with confidence and source, and catherd's own runs on it */
+  rungDetail(c: Catalog, rung: string): { values: ValueUsed[]; evidence: string | null };
+}
+
+/** Spec 1.2 §9: each source's age and last error, from the sync's state. */
+export function sourceRows(now = Date.now()): ReturnType<Effects["sources"]> {
+  return sourcesStatus().sources.map((s) => ({
+    source: s.source,
+    name: s.name,
+    age: s.fetchedAt ? `${ageText(now - Date.parse(s.fetchedAt))} ago` : "never fetched",
+    error: s.error,
+  }));
+}
+
+/** Spec 1.2 §5.3, §8: what the rung detail shows; an unparseable rung has nothing to show. */
+export function rungDetailOf(c: Catalog, rung: string): ReturnType<Effects["rungDetail"]> {
+  try {
+    const canonical = rungInfo(c, rung).canonical;
+    return {
+      values: valuesUsed(c, canonical),
+      evidence: evidenceLine(evidenceOf(runEvidence(c), canonical)),
+    };
+  } catch {
+    return { values: [], evidence: null };
+  }
+}
+
+/** Spec 1.2 §6.3: a rung's nearest stand-ins; none for a rung that does not parse. */
+export function suggestFor(c: Catalog, rung: string): Suggestion[] {
+  try {
+    return suggestStandIns(c, rungInfo(c, rung).canonical);
+  } catch {
+    return [];
+  }
 }
 
 /** The word for `here`: the bound repo's profile, or the global active one. */
@@ -308,5 +353,9 @@ export function liveEffects(repo: string | null = null): Effects {
     create: createProfile,
     remove: deleteProfile,
     refreshCatalog: () => refreshDiscovery(),
+    syncSources: () => syncSources(),
+    sources: () => sourceRows(),
+    suggest: suggestFor,
+    rungDetail: rungDetailOf,
   };
 }

package/src/entry/tui/fixtures.ts

@@ -6,7 +6,7 @@ import {
   type ProfileDoc,
   resolveProfile,
 } from "../../domain/profile.ts";
-import { validateProfile } from "../../domain/profile-rules.ts";
+import { repairs, validateProfile } from "../../domain/profile-rules.ts";
 import { catalogQuery, loadCatalog } from "../../services/catalog-service.ts";
 import type { RunRecord } from "../../domain/record.ts";
 import type { DoctorReport } from "../../services/doctor.ts";
@@ -17,8 +17,10 @@ import {
   type RoleDetail,
   type RoleRow,
   rowOf,
+  rungDetailOf,
   type SessionRow,
   type SessionRun,
+  suggestFor,
 } from "./effects.ts";
 import { withStaged } from "./profile-tree.ts";
 
@@ -401,6 +403,14 @@ export interface FixtureOptions {
   watchable?: boolean;
 }
 
+/** Spec 1.2 §9: the sources as the `r` dialog shows them, one failing. */
+export const FIXTURE_SOURCES: ReturnType<Effects["sources"]> = [
+  { source: "models-dev", name: "models.dev", age: "2 h ago", error: null },
+  { source: "arena", name: "Arena (LMArena)", age: "2 h ago", error: null },
+  { source: "epoch", name: "Epoch AI benchmarks", age: "1 d ago", error: "network error" },
+  { source: "artificial-analysis", name: "Artificial Analysis", age: "never fetched", error: null },
+];
+
 export function fixtureEffects(o: FixtureOptions = {}): Effects & {
   writes: string[];
   /** what a change to a watched run file does: every open watch hears of it */
@@ -425,9 +435,12 @@ export function fixtureEffects(o: FixtureOptions = {}): Effects & {
     staged: Record<string, string> = {},
   ) => {
     const p = resolveProfile(after, name);
-    const v = validateProfile(p, withStaged(loadCatalog({ timings: false }), staged), BACKENDS);
+    const c = withStaged(loadCatalog({ timings: false }), staged);
+    const v = validateProfile(p, c, BACKENDS);
+    // spec 1.2 §6.2, as the ProfileService rules: a save that repairs part of an invalid profile goes through
+    const was = docs.has(name) ? validateProfile(resolveProfile(before, name), c, BACKENDS) : null;
     return {
-      saved: v.errors.length === 0,
+      saved: repairs(was, v),
       ...v,
       diff: diffProfiles(resolveProfile(before, name), p),
       linked: [],
@@ -581,5 +594,20 @@ export function fixtureEffects(o: FixtureOptions = {}): Effects & {
       writes.push("refresh");
       return [{ backend: "codex", models: 14, fetchedAt: "2026-09-26T12:00:00.000Z" }];
     },
+    async syncSources() {
+      writes.push("sync");
+      return {
+        busy: false,
+        sources: [],
+        newlyScored: [],
+        noLongerNeeded: [],
+        failed: [],
+        warnings: [],
+        unmatched: {},
+      };
+    },
+    sources: () => FIXTURE_SOURCES,
+    suggest: suggestFor,
+    rungDetail: rungDetailOf,
   };
 }

package/src/entry/tui/profile-edits.ts

@@ -1,3 +1,4 @@
+import type { Suggestion } from "../../services/standins.ts";
 import { type Catalog, rungInfo, scoresOf } from "../../domain/catalog.ts";
 import { parseRung, tryParseRung } from "../../domain/ids.ts";
 import { NOTIFY, type Profile, type ProfilePatch } from "../../domain/profile.ts";
@@ -113,26 +114,33 @@ export function failoverOptions(
       if (!(r.enabled || usable(r.rung)) || r.rung.startsWith("claude:")) continue;
       const q = quotaOf(parseRung(r.rung));
       if (q === quota) continue;
-      const via = inferredScores(c, rungInfo(c, r.rung)).via;
+      const note = inferredScores(c, rungInfo(c, r.rung)).note;
       out.push({
         value: r.rung,
         title: shortRung(r.rung),
         group: m.billing,
-        detail: via ? `scores borrowed from ${via}` : "",
+        detail: note ?? "",
         current: r.rung === cur,
       });
     }
   return out;
 }
 
-/** The treat-like picker: every rung with scores of its own, by model. */
-export function treatLikeOptions(c: Catalog): SelectOption[] {
+/**
+ * The treat-like picker: every rung with scores of its own, by model; spec 1.2 §6.4: the suggested stand-ins
+ * (`suggestions`, nearest first) say their distance and what they would lend.
+ */
+export function treatLikeOptions(c: Catalog, suggestions: Suggestion[] = []): SelectOption[] {
   return Object.keys(c.scores)
     .filter((canonical) => scoresOf(c, canonical)?.via === null)
     .sort()
-    .map((canonical) => ({
-      value: canonical,
-      title: canonical,
-      group: canonical.slice(0, canonical.lastIndexOf("#")),
-    }));
+    .map((canonical) => {
+      const s = suggestions.find((x) => x.like === canonical);
+      return {
+        value: canonical,
+        title: canonical,
+        group: canonical.slice(0, canonical.lastIndexOf("#")),
+        ...(s ? { detail: `distance ${s.distance.toFixed(2)} · lends ${s.lends.join(", ")}` } : {}),
+      };
+    });
 }

package/src/entry/tui/profile-tree.ts

@@ -350,8 +350,8 @@ export function buildRows(i: TreeInput): Row[] {
     let mark = "";
     if (to) {
       try {
-        const via = inferredScores(i.catalog, rungInfo(i.catalog, to)).via;
-        mark = via ? ` (scores borrowed from ${via})` : "";
+        const note = inferredScores(i.catalog, rungInfo(i.catalog, to)).note;
+        mark = note ? ` (${note})` : "";
       } catch {
         mark = "";
       }

package/src/entry/tui/run.tsx

@@ -10,6 +10,16 @@ import { liveEffects } from "./effects.ts";
 import { fixtureEffects } from "./fixtures.ts";
 import { createAppKeymap } from "./providers/keymap.tsx";
 import { Providers } from "./providers/root.tsx";
+
+/**
+ * OpenTUI's SystemClock counts from process start (performance.now), but the pages compare its time with the
+ * wall-clock timestamps catherd writes (admittedAt, createdAt, lastActivity), so it must be epoch milliseconds.
+ */
+export class WallClock extends SystemClock {
+  override now(): number {
+    return Date.now();
+  }
+}
 import { initialState, type Tab } from "./state.ts";
 import { detectUi, type ThemeMode } from "./theme.ts";
 import { App } from "./views/app.tsx";
@@ -72,7 +82,7 @@ export async function openTui(o: TuiOptions): Promise<number> {
         keybinds={keybinds}
         keymap={createAppKeymap(renderer)}
         effects={effects}
-        clock={new SystemClock()}
+        clock={new WallClock()}
         initial={initialState(o.tab ?? "status")}
         copy={(text) => renderer.copyToClipboardOSC52(text)}
         onExit={(code, kept) => {

package/src/entry/tui/state.ts

@@ -54,6 +54,10 @@ export type Purpose =
   | { type: "start"; role: Role }
   | { type: "treatLike"; rung: string; role: Role | null }
   | { type: "failover"; rung: string }
+  /** spec 1.2 §9: each source's age and last error, after `r` synced them */
+  | { type: "sources" }
+  /** spec 1.2 §9: a rung's values with confidence and source, and its runs */
+  | { type: "rung"; rung: string }
   | { type: "stories" };
 
 export interface SelectOption {

package/src/entry/tui/views/profile-actions.ts

@@ -314,7 +314,15 @@ export function useProfileDialogs(): void {
     } catch (e) {
       fail(app, e);
     }
-    app.toast({ variant: "success", message: `Saved profile ${p.name}` });
+    // spec 1.2 §6.2: a save that repaired part of an invalid profile says what is still open
+    app.toast(
+      r.errors.length
+        ? {
+            variant: "warning",
+            message: `Saved profile ${p.name}; ${r.errors.length} ${r.errors.length === 1 ? "error" : "errors"} still open`,
+          }
+        : { variant: "success", message: `Saved profile ${p.name}` },
+    );
     sessionsNeeded(app, r.newSessionNeededFor);
     if (value === "activate") activateNow(app, data, p.name, shown);
   });

package/src/entry/tui/views/profiles.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { type Profile, resolveProfile } from "../../../domain/profile.ts";
+import type { Role } from "../../../domain/roles.ts";
 import { errorMessage, isCatherdError } from "../../../domain/errors.ts";
 import { hereWord } from "../effects.ts";
 import { useApp, useDialogHandler } from "../providers/app.tsx";
@@ -215,17 +216,7 @@ export function ProfilesView(props: { width: number; height: number }) {
           empty: "no scored rung on another quota",
         },
       });
-    else if (a.type === "rung" && !a.scored)
-      app.dispatch({
-        type: "open",
-        dialog: {
-          kind: "select",
-          purpose: { type: "treatLike", rung: a.rung, role: a.role },
-          title: `Treat ${a.rung} like…`,
-          options: treatLikeOptions(catalog),
-          empty: "no scored rung",
-        },
-      });
+    else if (a.type === "rung" && !a.scored) openTreatLike(a.rung, a.role);
     else if (a.type === "number") {
       const v = numberValue(profile, a.path);
       app.dispatch({
@@ -241,6 +232,49 @@ export function ProfilesView(props: { width: number; height: number }) {
       });
     }
   };
+  /** spec 1.2 §6.4: the treat-like picker, its three nearest stand-ins first */
+  const openTreatLike = (rung: string, role: Role | null) => {
+    if (!catalog) return;
+    const suggestions = app.effects.suggest(catalog, rung);
+    app.dispatch({
+      type: "open",
+      dialog: {
+        kind: "select",
+        purpose: { type: "treatLike", rung, role },
+        title: `Treat ${rung} like…`,
+        options: treatLikeOptions(catalog, suggestions),
+        suggested: suggestions.map((s) => s.like),
+        empty: "no scored rung",
+      },
+    });
+  };
+  /** spec 1.2 §9: the rung's values with confidence and source, and catherd's runs on it */
+  const openDetail = (rung: string) => {
+    if (!catalog) return;
+    const d = app.effects.rungDetail(catalog, rung);
+    app.dispatch({
+      type: "open",
+      dialog: {
+        kind: "select",
+        purpose: { type: "rung", rung },
+        title: rung,
+        options: [
+          ...d.values.map((v) => ({
+            value: v.dim,
+            title: `${v.dim} ${v.value}`,
+            group: "values",
+            detail: `${v.inferred ? `inferred from ${v.from}` : v.confidence} · ${v.source} ${v.benchmark} · ${v.date}`,
+          })),
+          {
+            value: "runs",
+            title: d.evidence ?? "no runs yet",
+            group: "catherd's runs (never used to route)",
+          },
+        ],
+        empty: "no values",
+      },
+    });
+  };
   const primary = (r: Row | null) => {
     const p = current();
     if (!r || !p) return;
@@ -267,10 +301,31 @@ export function ProfilesView(props: { width: number; height: number }) {
     "catalog.refresh": () => {
       // after a failed read, r reads it again (and only that)
       if (failure) return failure.retry();
-      void app.effects.refreshCatalog().then(
-        () => {
+      // spec 1.2 §9: r lists every backend's models and syncs the public sources, then shows each source's
+      // age and last error
+      void Promise.all([app.effects.refreshCatalog(), app.effects.syncSources()]).then(
+        ([, sync]) => {
           loaded.refresh();
-          app.toast({ variant: "success", message: "Catalog refreshed" });
+          app.toast({
+            variant: sync.failed.length ? "warning" : "success",
+            message: sync.busy
+              ? "Catalog refreshed; another sync is running"
+              : `Catalog refreshed${sync.newlyScored.length ? `; ${sync.newlyScored.length} rungs newly scored` : ""}`,
+          });
+          app.dispatch({
+            type: "open",
+            dialog: {
+              kind: "select",
+              purpose: { type: "sources" },
+              title: "Sources",
+              options: app.effects.sources().map((s) => ({
+                value: s.source,
+                title: s.name,
+                detail: s.error ? `${s.age} · ${s.error}` : s.age,
+              })),
+              empty: "no sources",
+            },
+          });
         },
         (e: unknown) => app.toast(errorToast(e)),
       );
@@ -279,6 +334,16 @@ export function ProfilesView(props: { width: number; height: number }) {
     "edit.redo": () => app.dispatch({ type: "redo" }),
   });
   useCommandLayer("row.profiles", {
+    "tree.detail": () => {
+      const a = rowNow()?.action;
+      if (a?.type === "rung") openDetail(a.rung);
+      else app.toast({ variant: "info", message: "Pick a rung (an effort row) to see its values" });
+    },
+    "tree.treatLike": () => {
+      const a = rowNow()?.action;
+      if (a?.type === "rung") openTreatLike(a.rung, a.role);
+      else app.toast({ variant: "info", message: "Pick a rung (an effort row) to map it" });
+    },
     "tree.toggle": () => toggle(rowNow()),
     "tree.open": () => primary(rowNow()),
     "tree.expand": () => {
@@ -313,6 +378,8 @@ export function ProfilesView(props: { width: number; height: number }) {
         : null;
     app.dispatch({ type: "treatLike", rung: p.rung, like: value, ...(tick ? { patch: tick } : {}) });
   });
+  useDialogHandler("sources", () => app.dispatch({ type: "close" }));
+  useDialogHandler("rung", () => app.dispatch({ type: "close" }));
   useDialogHandler("number", (p, value) => {
     if (p.type !== "number") return;
     const r = parseNumber(p.path, value);

package/src/entry/tui/views/save-dialog.tsx

@@ -9,7 +9,7 @@ import {
   patchBetween,
   resolveProfile,
 } from "../../../domain/profile.ts";
-import type { Validation } from "../../../domain/profile-rules.ts";
+import { repairs, type Validation } from "../../../domain/profile-rules.ts";
 import type { Effects } from "../effects.ts";
 import { useApp } from "../providers/app.tsx";
 import { useData, useLoad } from "../providers/data.tsx";
@@ -36,6 +36,8 @@ export interface SavePreview {
   changes: Change[];
   treatLikes: [string, string][];
   validation: Validation;
+  /** spec 1.2 §6.2: the save leaves errors but removes one of the stored profile's and adds none */
+  repair: boolean;
   agentsAdded: string[];
   agentsRemoved: string[];
 }
@@ -54,10 +56,13 @@ function previewSave(
   const { catalog } = fx.catalog(after.billing);
   const a = new Set(fx.agents(before));
   const b = new Set(fx.agents(after));
+  const staged = withStaged(catalog, d.treatLikes);
+  const validation = fx.validate(after, staged);
   return {
     changes: diffProfiles(before, after),
     treatLikes: Object.entries(d.treatLikes),
-    validation: fx.validate(after, withStaged(catalog, d.treatLikes)),
+    validation,
+    repair: validation.errors.length > 0 && repairs(fx.validate(before, staged), validation),
     agentsAdded: [...b].filter((x) => !a.has(x)),
     agentsRemoved: [...a].filter((x) => !b.has(x)),
   };
@@ -200,7 +205,8 @@ export function SaveDialog(props: { dialog: Save }) {
     setChanged(true);
     return { same: false, now: doc };
   };
-  const blocked = error !== null || (preview?.validation.errors.length ?? 0) > 0;
+  // spec 1.2 §6.2: a save that repairs part of an invalid profile is offered; any other error leaves Cancel
+  const blocked = error !== null || ((preview?.validation.errors.length ?? 0) > 0 && !preview?.repair);
   // spec §9.2's order: Save / Save & make active / Cancel; errors leave only Cancel
   const labels = blocked ? ["Cancel"] : ["Save", "Save & make active", "Cancel"];
   const [focused, setFocusedState] = useState(0);
@@ -272,7 +278,9 @@ export function SaveDialog(props: { dialog: Save }) {
         ],
       },
       {
-        head: [[]],
+        head: preview.repair
+          ? [[], ...text("This save fixes an error and adds none; these stay open:", "warning")]
+          : [[]],
         hold: "error",
         more: (n) => `… and ${n} more ${n === 1 ? "error" : "errors"}`,
         items: preview.validation.errors.map((e) =>

package/src/infra/env.ts

@@ -6,6 +6,8 @@
  */
 const SECRET_ENV = new Set([
   "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/jev-client.ts

@@ -1,5 +1,6 @@
 // Spec §5.5 transport: a thin client (the official SDK is 0.x and Node-targeted) with the SDK's retry
-// semantics (research 2026-09-25-jev.md §4, §5.6).
+// semantics (research 2026-09-25-jev.md §4, §5.6). The public sources of spec 1.2 §3.3 reuse its policy
+// through `retryingFetch`.
 
 export const JEV_BASE = "https://api.typesafe.ai/v1";
 
@@ -20,6 +21,19 @@ export type JevResponse =
   | { ok: true; body: unknown; requestId: string | null; latencyMs: number; attempts: number }
   | { ok: false; error: string; status: number | null; latencyMs: number; attempts: number };
 
+/** What `retryingFetch` got: the body's bytes on a 2xx, else the last error and status. */
+export type FetchOutcome =
+  | { ok: true; status: number; headers: Headers; bytes: Uint8Array; latencyMs: number; attempts: number }
+  | {
+      ok: false;
+      error: string;
+      status: number | null;
+      /** the last answer's headers, when there was an answer */
+      headers: Headers | null;
+      latencyMs: number;
+      attempts: number;
+    };
+
 const RETRY_AFTER_MAX_MS = 10_000;
 const retryable = (status: number) => status === 408 || status === 429 || status >= 500;
 
@@ -64,25 +78,30 @@ function httpError(status: number, text: string): string {
 }
 
 /**
- * `method path` against the Jev API with a bearer key: 10 s per attempt, up to two retries on 408, 429,
- * 5xx, a network error or a timeout, honouring Retry-After, and never past the 25 s deadline. The attempt
- * timer covers the whole exchange, body included, and aborts the request when it fires.
+ * `url` with the Jev client's retry policy: `attemptMs` per attempt (10 s), up to `retries` (two) retries on
+ * 408, 429, 5xx, a network error or a timeout, honouring Retry-After, and never past `deadlineMs` (25 s). The
+ * attempt timer covers the whole exchange, body included, and aborts the request when it fires. `headers`
+ * builds each attempt's headers from its number (1 first); `errorOf` names a failed status (`http <status>`).
+ * Bun's fetch honours HTTPS_PROXY and HTTP_PROXY.
  */
-export async function jevRequest(
-  method: "GET" | "POST",
-  path: string,
-  key: string,
-  body: unknown,
-  o: JevTransport = {},
-): Promise<JevResponse> {
+export async function retryingFetch(
+  url: string,
+  init: { method: "GET" | "POST"; headers: (attempt: number) => Record<string, string>; body?: string },
+  o: JevTransport & { errorOf?: (status: number, text: string) => string } = {},
+): Promise<FetchOutcome> {
   const now = o.now ?? Date.now;
   const sleep = o.sleep ?? ((ms: number) => Bun.sleep(ms));
   const random = o.random ?? Math.random;
   const fetchImpl = o.fetchImpl ?? globalThis.fetch;
+  const errorOf = o.errorOf ?? ((status: number) => `http ${status}`);
   const start = now();
   const deadline = start + (o.deadlineMs ?? 25_000);
   const retries = o.retries ?? 2;
-  let last: { error: string; status: number | null } = { error: "network error", status: null };
+  let last: { error: string; status: number | null; headers: Headers | null } = {
+    error: "network error",
+    status: null,
+    headers: null,
+  };
   let attempt = 0;
   for (;;) {
     attempt++;
@@ -100,52 +119,37 @@ export async function jevRequest(
       );
     });
     const exchange = async () => {
-      const res = await fetchImpl(`${JEV_BASE}${path}`, {
-        method,
-        headers: {
-          authorization: `Bearer ${key}`,
-          ...(body === undefined ? {} : { "content-type": "application/json" }),
-          ...(attempt > 1 ? { "x-typesafe-retry-count": String(attempt - 1) } : {}),
-        },
-        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      const res = await fetchImpl(url, {
+        method: init.method,
+        headers: init.headers(attempt),
+        ...(init.body === undefined ? {} : { body: init.body }),
         signal: ctl.signal,
       });
-      const text = res.ok ? await res.text() : await res.text().catch(() => "");
-      return { res, text };
+      if (res.ok) return { res, bytes: new Uint8Array(await res.arrayBuffer()), text: "" };
+      return { res, bytes: new Uint8Array(), text: await res.text().catch(() => "") };
     };
     let wait: number | null = null;
     try {
       const r = await Promise.race([exchange(), timeout]);
       if (r === "timeout") {
-        last = { error: "timeout", status: null };
+        last = { error: "timeout", status: null, headers: null };
       } else if (r.res.ok) {
-        let parsed: unknown = null;
-        try {
-          parsed = JSON.parse(r.text);
-        } catch {
-          return {
-            ok: false,
-            error: "unexpected response",
-            status: r.res.status,
-            latencyMs: now() - start,
-            attempts: attempt,
-          };
-        }
         return {
           ok: true,
-          body: parsed,
-          requestId: r.res.headers.get("x-typesafe-request-id"),
+          status: r.res.status,
+          headers: r.res.headers,
+          bytes: r.bytes,
           latencyMs: now() - start,
           attempts: attempt,
         };
       } else {
-        last = { error: httpError(r.res.status, r.text), status: r.res.status };
+        last = { error: errorOf(r.res.status, r.text), status: r.res.status, headers: r.res.headers };
         if (!retryable(r.res.status))
           return { ok: false, ...last, latencyMs: now() - start, attempts: attempt };
         wait = retryAfterMs(r.res.headers, now());
       }
     } catch {
-      last = { error: "network error", status: null };
+      last = { error: "network error", status: null, headers: null };
     } finally {
       clearTimeout(timer);
       ctl.abort();
@@ -153,10 +157,54 @@ export async function jevRequest(
     if (attempt > retries) break;
     const pause = wait ?? backoffMs(attempt, random);
     if (now() + pause >= deadline) {
-      last = { error: `deadline (${last.error})`, status: last.status };
+      last = { ...last, error: `deadline (${last.error})` };
       break;
     }
     await sleep(pause);
   }
   return { ok: false, ...last, latencyMs: now() - start, attempts: attempt };
 }
+
+/** `method path` against the Jev API with a bearer key, under `retryingFetch`'s policy. */
+export async function jevRequest(
+  method: "GET" | "POST",
+  path: string,
+  key: string,
+  body: unknown,
+  o: JevTransport = {},
+): Promise<JevResponse> {
+  const r = await retryingFetch(
+    `${JEV_BASE}${path}`,
+    {
+      method,
+      headers: (attempt) => ({
+        authorization: `Bearer ${key}`,
+        ...(body === undefined ? {} : { "content-type": "application/json" }),
+        ...(attempt > 1 ? { "x-typesafe-retry-count": String(attempt - 1) } : {}),
+      }),
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    },
+    { ...o, errorOf: httpError },
+  );
+  if (!r.ok)
+    return { ok: false, error: r.error, status: r.status, latencyMs: r.latencyMs, attempts: r.attempts };
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(r.bytes));
+  } catch {
+    return {
+      ok: false,
+      error: "unexpected response",
+      status: r.status,
+      latencyMs: r.latencyMs,
+      attempts: r.attempts,
+    };
+  }
+  return {
+    ok: true,
+    body: parsed,
+    requestId: r.headers.get("x-typesafe-request-id"),
+    latencyMs: r.latencyMs,
+    attempts: r.attempts,
+  };
+}

package/src/infra/paths.ts

@@ -36,3 +36,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");