@mauricode/token-derby 3.1.0 → 3.1.2

package/README.md

@@ -103,4 +103,9 @@ at usage you didn't produce.
 - `TOKEN_DERBY_API_BASE` — override the API base URL (default: `https://token-derby.mauricode.co.uk/api`)
 - `TOKEN_DERBY_HOME` — override the data directory (default: `~/.token-derby`)
 - `TOKEN_DERBY_CLAUDE_DIR` — override the transcripts directory (default: `~/.claude/projects`)
+- `CLAUDE_CONFIG_DIR` — Claude Code's own config override. When set, transcripts are read from `$CLAUDE_CONFIG_DIR/projects`. `TOKEN_DERBY_CLAUDE_DIR` still wins.
+
+Token Derby counts usage from this machine's filesystem only. If Claude Code runs
+in a container, over SSH, or on another machine, join the race from there — `join`
+warns before entering a race whose primary model has no transcripts to read.
 - **Top-5 conversations (primary):** a race can be created so that only each racer's **5 most-active conversations per heartbeat** count toward their **primary** model's score (secondaries unaffected). The race creator opts in at `token-derby create` (prompt) or, for organisation-scheduled races, via the "Primary top-5 cap" option on the schedule tab of `token-derby web`. Off by default (every conversation counts).

package/dist/bin.js

@@ -857,12 +857,13 @@ function apiBase() {
 var HEARTBEAT_INTERVAL_MS = 6e4;
 var SCAN_TIMEOUT_MS = HEARTBEAT_INTERVAL_MS * 0.75;
 var HEARTBEAT_RETRY_DELAYS_MS = [1e3, 2e3, 4e3, 8e3, 15e3];
+var PRIMARY_SILENT_THRESHOLD = 10;
 
 // src/version.ts
 import { createRequire } from "module";
 function readVersion() {
-  if ("3.1.0".length > 0) {
-    return "3.1.0";
+  if ("3.1.2".length > 0) {
+    return "3.1.2";
   }
   try {
     const req = createRequire(import.meta.url);
@@ -897,7 +898,11 @@ function activeRacesDir() {
   return path2.join(homeDir(), "active-races");
 }
 function claudeProjectsDir() {
-  return process.env.TOKEN_DERBY_CLAUDE_DIR ?? path2.join(os2.homedir(), ".claude", "projects");
+  const override = process.env.TOKEN_DERBY_CLAUDE_DIR;
+  if (override) return override;
+  const configDir = process.env.CLAUDE_CONFIG_DIR;
+  if (configDir) return path2.join(configDir, "projects");
+  return path2.join(os2.homedir(), ".claude", "projects");
 }
 function codexSessionsDir() {
   return process.env.TOKEN_DERBY_CODEX_DIR ?? path2.join(os2.homedir(), ".codex");
@@ -1559,7 +1564,7 @@ function ModelList(props) {
   ] }) });
 }
 function StatusScreen(props) {
-  const { race, ownHorseId, ownHorseName, ownColors, ownUserName, lastHeartbeatAgoSec, lastHeartbeatOk, stalled, stallReason, primaryModel } = props;
+  const { race, ownHorseId, ownHorseName, ownColors, ownUserName, lastHeartbeatAgoSec, lastHeartbeatOk, stalled, stallReason, primarySilent, primarySourceDir, primaryModel } = props;
   if (!race) {
     return /* @__PURE__ */ jsx7(Box7, { flexDirection: "column", children: /* @__PURE__ */ jsx7(Text7, { children: "Joining race\u2026" }) });
   }
@@ -1630,6 +1635,15 @@ function StatusScreen(props) {
         "\u26A0 ",
         stallReason ?? "Can't read token usage",
         ". Your race continues."
+      ] }),
+      !stalled && primarySilent && /* @__PURE__ */ jsxs5(Text7, { color: "yellow", children: [
+        "\u26A0 No ",
+        MODEL_LABELS[primaryModel ?? "claude"],
+        " transcripts in ",
+        PRIMARY_SILENT_THRESHOLD,
+        " beats",
+        primarySourceDir ? ` \u2014 nothing under ${primarySourceDir}` : "",
+        ". Your race continues, but your horse cannot move until they can be read."
       ] })
     ] }),
     primaryModel && /* @__PURE__ */ jsx7(ModelList, { primaryModel }),
@@ -1869,6 +1883,24 @@ async function readCompleteLines(file, start, end) {
   }
 }
 
+// src/tokens/source-root.ts
+var SourceRootMissing = class extends Error {
+  constructor(dir) {
+    super(`No history directory at ${dir}`);
+    this.dir = dir;
+    this.name = "SourceRootMissing";
+  }
+  dir;
+};
+async function readRoot(dir, read) {
+  try {
+    return await read();
+  } catch (e) {
+    if (e?.code === "ENOENT") throw new SourceRootMissing(dir);
+    throw e;
+  }
+}
+
 // src/tokens/transcripts.ts
 var MAX_PROJECT_DEPTH = 8;
 function conversationId(file, root) {
@@ -1905,29 +1937,33 @@ async function sumTokens() {
   return { input, output };
 }
 async function listJsonlFiles(root) {
-  const projects = await fs4.readdir(root);
+  const entries = await readEntries(root, true);
   const out = [];
-  for (const project of projects) {
-    const projectDir = path6.join(root, project);
-    const stat4 = await fs4.stat(projectDir);
-    if (!stat4.isDirectory()) continue;
-    await collectJsonl(projectDir, MAX_PROJECT_DEPTH, out);
+  for (const entry of entries) {
+    if (!await isDirectory(entry, root)) continue;
+    await collectJsonl(path6.join(root, entry.name), MAX_PROJECT_DEPTH, out);
   }
   return out;
 }
 async function collectJsonl(dir, depth, out) {
   if (depth <= 0) return;
-  const entries = await fs4.readdir(dir);
-  for (const entry of entries) {
-    if (entry.endsWith(".jsonl")) {
-      out.push(path6.join(dir, entry));
-    } else if (depth > 1) {
-      const child = path6.join(dir, entry);
-      const st = await fs4.stat(child);
-      if (st.isDirectory()) await collectJsonl(child, depth - 1, out);
+  for (const entry of await readEntries(dir, false)) {
+    if (entry.name.endsWith(".jsonl")) {
+      out.push(path6.join(dir, entry.name));
+    } else if (depth > 1 && await isDirectory(entry, dir)) {
+      await collectJsonl(path6.join(dir, entry.name), depth - 1, out);
     }
   }
 }
+async function readEntries(dir, failLoud) {
+  if (failLoud) return readRoot(dir, () => fs4.readdir(dir, { withFileTypes: true }));
+  return fs4.readdir(dir, { withFileTypes: true }).catch(() => []);
+}
+async function isDirectory(entry, parent) {
+  if (entry.isDirectory()) return true;
+  if (!entry.isSymbolicLink()) return false;
+  return fs4.stat(path6.join(parent, entry.name)).then((st) => st.isDirectory()).catch(() => false);
+}
 function addNum(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
@@ -1960,11 +1996,8 @@ function num(v) {
 }
 async function sumCodexByConversation() {
   const root = codexSessionsDir();
-  await fs5.stat(root);
-  const files = [
-    ...await collectRollouts(path7.join(root, "sessions")),
-    ...await collectRollouts(path7.join(root, "archived_sessions"))
-  ];
+  await readRoot(root, () => fs5.stat(root));
+  const files = await listCodexRollouts(root);
   const cache = await ScanCache.open("codex");
   const totals = await mapWithConcurrency(
     files,
@@ -1986,6 +2019,12 @@ async function sumCodexTokens() {
   }
   return { input, output };
 }
+async function listCodexRollouts(root) {
+  return [
+    ...await collectRollouts(path7.join(root, "sessions")),
+    ...await collectRollouts(path7.join(root, "archived_sessions"))
+  ];
+}
 async function collectRollouts(dir) {
   let entries;
   try {
@@ -2056,7 +2095,7 @@ async function sumGeminiTokens() {
   return { input, output };
 }
 async function listChatFiles(root) {
-  const entries = await fs6.readdir(root);
+  const entries = await readRoot(root, () => fs6.readdir(root));
   const out = [];
   for (const entry of entries) {
     const chatsDir = path8.join(root, entry, "chats");
@@ -2154,7 +2193,7 @@ async function readAllSources(race, primary, progress) {
   const primaryByConv = /* @__PURE__ */ new Map();
   if (primaryResult.ok) {
     for (const [id, totals] of primaryResult.map) primaryByConv.set(id, scoreFor(race, totals));
-  } else if (primaryResult.err?.code !== "ENOENT") {
+  } else if (!(primaryResult.err instanceof SourceRootMissing)) {
     const err = primaryResult.err;
     return { stall: `Can't read ${primary} token usage: ${err?.message ?? String(err)}` };
   }
@@ -2221,6 +2260,7 @@ var RaceScoreTracker = class {
   seq;
   stalls = 0;
   lastStall = null;
+  primaryEmptyBeats = 0;
   primary;
   primaryTop5;
   constructor(init, primary, primaryTop5) {
@@ -2253,6 +2293,7 @@ var RaceScoreTracker = class {
       const v = reading.secondary[key];
       if (v > 0) this.lastGood[key] = v;
     }
+    this.primaryEmptyBeats = reading.primaryByConv.size === 0 ? this.primaryEmptyBeats + 1 : 0;
     for (const [id, v] of reading.primaryByConv) {
       const prev = this.primaryConvLast[id] ?? 0;
       if (v > prev) this.primaryConvLast[id] = v;
@@ -2304,6 +2345,10 @@ var RaceScoreTracker = class {
   get stalled() {
     return this.stalls >= STALL_THRESHOLD;
   }
+  /** The primary source has produced no conversations for long enough to be worth saying. */
+  get primarySilent() {
+    return this.primaryEmptyBeats >= PRIMARY_SILENT_THRESHOLD;
+  }
   /** Human-readable cause of the most recent stall (null once a good read recovers). */
   get stallReason() {
     return this.lastStall;
@@ -2332,6 +2377,75 @@ var RaceScoreTracker = class {
   }
 };
 
+// src/tokens/source-probe.ts
+import * as fs7 from "fs/promises";
+var ROOTS = {
+  claude: claudeProjectsDir,
+  codex: codexSessionsDir,
+  gemini: geminiTmpDir
+};
+var LISTERS = {
+  claude: listJsonlFiles,
+  codex: listCodexRollouts,
+  gemini: listChatFiles
+};
+var LABELS2 = { claude: "Claude", codex: "Codex", gemini: "Gemini" };
+function sourceDir(key) {
+  return ROOTS[key]();
+}
+async function probeSource(key) {
+  const dir = ROOTS[key]();
+  const exists = await fs7.stat(dir).then((st) => st.isDirectory()).catch(() => false);
+  if (!exists) return { key, dir, exists: false, projects: 0, transcripts: 0 };
+  const entries = await fs7.readdir(dir, { withFileTypes: true }).catch(() => []);
+  const projects = entries.filter((e) => e.isDirectory() || e.isSymbolicLink()).length;
+  const files = await LISTERS[key](dir).catch(() => []);
+  return { key, dir, exists: true, projects, transcripts: files.length };
+}
+function overrideVar(key) {
+  return `TOKEN_DERBY_${key.toUpperCase()}_DIR`;
+}
+async function confirmEmptySource(opts) {
+  if (opts.probe.transcripts > 0) return true;
+  opts.warn(describeEmptySource(opts.probe));
+  if (!opts.interactive) return true;
+  return opts.ask();
+}
+function describeEmptySource(probe) {
+  const label = LABELS2[probe.key];
+  const populated = probe.exists && probe.projects > 0;
+  const reason = !probe.exists ? "does not exist" : populated ? `holds ${probe.projects} project ${probe.projects === 1 ? "directory" : "directories"}, none of which could be read` : "exists, but holds no transcripts";
+  const lines = [
+    `\u26A0 No ${label} transcripts found \u2014 your horse will not move.`,
+    ``,
+    `  Looked in: ${probe.dir}`,
+    `             (${reason})`,
+    ``
+  ];
+  if (populated) {
+    lines.push(
+      `  The directory is there and has history in it, so this is usually a`,
+      `  dangling symlink or a permissions problem on one of those projects.`,
+      `  To find dangling links:`,
+      `    find ${probe.dir} -type l ! -exec test -e {} \\; -print`,
+      ``
+    );
+  }
+  lines.push(
+    `  Token Derby counts ${label} usage from this machine's own filesystem.`,
+    `  If ${label} runs in a container, over SSH, or on another machine, join`,
+    `  the race from there instead.`
+  );
+  if (probe.key === "claude") {
+    lines.push(
+      `  If CLAUDE_CONFIG_DIR relocated your config, Token Derby follows it \u2014`,
+      `  check it points at the config root, not the projects directory.`
+    );
+  }
+  lines.push(``, `  To read them from somewhere else: export ${overrideVar(probe.key)}=<dir>`);
+  return lines.join("\n");
+}
+
 // src/runtime/run-race.tsx
 import { jsx as jsx8, jsxs as jsxs6 } from "react/jsx-runtime";
 function RunRace({ active, initialState, pendingMode, ownUserName }) {
@@ -2348,6 +2462,7 @@ function RunRace({ active, initialState, pendingMode, ownUserName }) {
   const ctrl = useRef(new AbortController());
   const [stalled, setStalled] = useState5(false);
   const [stallReason, setStallReason] = useState5(null);
+  const [primarySilent, setPrimarySilent] = useState5(false);
   useEffect2(() => {
     const t = setInterval(() => setTickNow(/* @__PURE__ */ new Date()), 1e3);
     return () => clearInterval(t);
@@ -2379,6 +2494,7 @@ function RunRace({ active, initialState, pendingMode, ownUserName }) {
         if (pendingRef.current && !isStall(reading)) tracker.reprime();
         setStalled(tracker.stalled);
         setStallReason(tracker.stalled ? tracker.stallReason : null);
+        setPrimarySilent(tracker.primarySilent);
         return tracker.nextBeat();
       },
       sendBeat: async (snapshot) => {
@@ -2446,6 +2562,8 @@ function RunRace({ active, initialState, pendingMode, ownUserName }) {
         lastHeartbeatOk: lastHbOk,
         stalled,
         stallReason,
+        primarySilent,
+        primarySourceDir: sourceDir(active.primary_model),
         primaryModel: active.primary_model
       }
     ),
@@ -2513,6 +2631,28 @@ async function buildInitialState(args) {
   };
 }
 
+// src/ui/prompt.ts
+async function promptYesNo(question, opts = {}) {
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stdout;
+  if (input === process.stdin) resetStdinAfterInk();
+  const readline6 = await import("readline/promises");
+  const rl = readline6.createInterface({ input, output });
+  const a = (await rl.question(question)).trim().toLowerCase();
+  rl.close();
+  if (a === "") return opts.defaultYes !== false;
+  return a === "y" || a === "yes";
+}
+function resetStdinAfterInk() {
+  if (process.stdin.isTTY && typeof process.stdin.setRawMode === "function") {
+    process.stdin.setRawMode(false);
+  }
+  while (process.stdin.read() !== null) {
+  }
+  process.stdin.pause();
+  process.stdin.ref();
+}
+
 // src/commands/join.ts
 function parsePrimaryFlag(argv) {
   for (let i = 0; i < argv.length; i++) {
@@ -2607,6 +2747,19 @@ async function joinCommand(joinCode, argv = []) {
     if (primaryFlag) chosenPrimary = primaryFlag;
     else if (process.stdout.isTTY) chosenPrimary = await pickPrimary();
   }
+  const effectivePrimary = ownHorse?.primary_model ?? chosenPrimary;
+  const proceed = await confirmEmptySource({
+    probe: await probeSource(effectivePrimary),
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    warn: (text) => console.error(`
+${text}
+`),
+    ask: () => promptYesNo("Join anyway? [y/N] ", { defaultYes: false })
+  });
+  if (!proceed) {
+    console.log("Cancelled.");
+    return 1;
+  }
   let joinResp;
   try {
     joinResp = await joinRace(code, { stable_horse_id: chosenStableHorseId, primary_model: chosenPrimary });
@@ -2907,25 +3060,6 @@ async function webCommand(deps = {}) {
   return 0;
 }
 
-// src/ui/prompt.ts
-async function promptYesNo(question) {
-  resetStdinAfterInk();
-  const readline6 = await import("readline/promises");
-  const rl = readline6.createInterface({ input: process.stdin, output: process.stdout });
-  const a = (await rl.question(question)).trim().toLowerCase();
-  rl.close();
-  return a === "" || a === "y" || a === "yes";
-}
-function resetStdinAfterInk() {
-  if (process.stdin.isTTY && typeof process.stdin.setRawMode === "function") {
-    process.stdin.setRawMode(false);
-  }
-  while (process.stdin.read() !== null) {
-  }
-  process.stdin.pause();
-  process.stdin.ref();
-}
-
 // src/commands/login.ts
 function parseDeviceNameFlag(argv) {
   for (let i = 0; i < argv.length; i++) {