@mauricode/token-derby 3.1.2 → 3.1.3

package/README.md

@@ -97,6 +97,35 @@ at usage you didn't produce.
 
 - `~/.token-derby/stable.json` — saved horses
 - `~/.token-derby/active-races/<join-code>.json` — per-race state for rejoin
+- `~/.token-derby/logs/token-derby.log` — debug log (see below)
+
+## Debug log
+
+Every command appends to a rolling log, so a race that stalls overnight can be
+diagnosed afterwards. The race UI takes over the terminal, which is exactly when
+nothing can be printed to the screen.
+
+```bash
+token-derby logs             # print the path of the log file
+token-derby logs --tail 100  # print the last 100 lines (default 50)
+```
+
+The log rolls at 2MB and keeps five files (`token-derby.log` plus `.1`–`.4`), so
+it never exceeds ~10MB. Each environment has its own, next to that environment's
+identity.
+
+What the lines mean when a race misbehaves:
+
+- `beat.prepare.start` with no `beat.prepare.done` after it — the token scan
+  hung, and the poller is still waiting on it.
+- repeated `beat.send.err` with a climbing `next_ms` — the heartbeat is
+  reaching the network and failing; `retry` counts the attempts.
+- `scan.timeout` — the scan blew its budget; `reason` names the source that was
+  still running.
+
+Credentials are never written: identity and horse tokens, request headers and
+bodies are all omitted, and claim tokens and admin codes are masked out of the
+URLs they travel in.
 
 ## Environment
 

package/dist/bin.js

@@ -862,8 +862,8 @@ var PRIMARY_SILENT_THRESHOLD = 10;
 // src/version.ts
 import { createRequire } from "module";
 function readVersion() {
-  if ("3.1.2".length > 0) {
-    return "3.1.2";
+  if ("3.1.3".length > 0) {
+    return "3.1.3";
   }
   try {
     const req = createRequire(import.meta.url);
@@ -910,6 +910,12 @@ function codexSessionsDir() {
 function geminiTmpDir() {
   return process.env.TOKEN_DERBY_GEMINI_DIR ?? path2.join(os2.homedir(), ".gemini", "tmp");
 }
+function logDir() {
+  return path2.join(homeDir(), "logs");
+}
+function logFile() {
+  return path2.join(logDir(), "token-derby.log");
+}
 
 // src/identity/identity.ts
 async function readIdentityFile() {
@@ -964,6 +970,63 @@ function validateDisplayName(name) {
   return { ok: true, name: trimmed };
 }
 
+// src/log/logger.ts
+import * as fs2 from "fs";
+var SECRET_KEY = /token|secret|authorization|credential|password/i;
+function redact(fields) {
+  const out = {};
+  for (const [key, value] of Object.entries(fields)) {
+    out[key] = SECRET_KEY.test(key) ? "[redacted]" : value;
+  }
+  return out;
+}
+function formatLine(at, level, event, fields) {
+  const body = fields && Object.keys(fields).length > 0 ? ` ${JSON.stringify(redact(fields))}` : "";
+  return `${at.toISOString()} ${level.padEnd(5)} ${event}${body}
+`;
+}
+var MAX_BYTES = 2e6;
+var MAX_FILES = 5;
+var currentBytes = null;
+var disabled = false;
+function rotate() {
+  const base = logFile();
+  fs2.rmSync(`${base}.${MAX_FILES - 1}`, { force: true });
+  for (let i = MAX_FILES - 2; i >= 1; i--) {
+    if (fs2.existsSync(`${base}.${i}`)) fs2.renameSync(`${base}.${i}`, `${base}.${i + 1}`);
+  }
+  if (fs2.existsSync(base)) fs2.renameSync(base, `${base}.1`);
+  currentBytes = 0;
+}
+function write(level, event, fields) {
+  if (disabled) return;
+  try {
+    append(level, event, fields);
+  } catch {
+    disabled = true;
+  }
+}
+function append(level, event, fields) {
+  const line = formatLine(/* @__PURE__ */ new Date(), level, event, fields);
+  const bytes = Buffer.byteLength(line);
+  fs2.mkdirSync(logDir(), { recursive: true });
+  if (currentBytes === null) {
+    currentBytes = fs2.existsSync(logFile()) ? fs2.statSync(logFile()).size : 0;
+  }
+  if (currentBytes > 0 && currentBytes + bytes > MAX_BYTES) rotate();
+  fs2.appendFileSync(logFile(), line, "utf8");
+  currentBytes += bytes;
+}
+function logInfo(event, fields) {
+  write("INFO", event, fields);
+}
+function logWarn(event, fields) {
+  write("WARN", event, fields);
+}
+function logError(event, fields) {
+  write("ERROR", event, fields);
+}
+
 // src/api/client.ts
 var ApiError = class extends Error {
   constructor(code, message, status) {
@@ -975,6 +1038,10 @@ var ApiError = class extends Error {
   code;
   status;
 };
+var SECRET_SEGMENT = /^\/(claims|races\/admin)\/[^/]+/;
+function loggablePath(path9) {
+  return path9.replace(SECRET_SEGMENT, (match) => `${match.slice(0, match.lastIndexOf("/") + 1)}[redacted]`);
+}
 var identityCache = null;
 function getIdentity() {
   if (!identityCache) identityCache = loadIdentity();
@@ -995,6 +1062,9 @@ async function request(method, path9, body, horseAuthToken, fetchImpl = fetch, i
   }
   if (horseAuthToken) headers["authorization"] = `Bearer ${horseAuthToken}`;
   if (body !== void 0) headers["content-type"] = "application/json";
+  const safePath = loggablePath(path9);
+  logInfo("http.req", { method, path: safePath });
+  const startedAt2 = Date.now();
   let res;
   try {
     res = await fetchImpl(url, {
@@ -1003,8 +1073,10 @@ async function request(method, path9, body, horseAuthToken, fetchImpl = fetch, i
       body: body !== void 0 ? JSON.stringify(body) : void 0
     });
   } catch (e) {
+    logError("http.err", { method, path: safePath, ms: Date.now() - startedAt2, message: e?.message ?? "fetch failed" });
     throw new ApiError("NETWORK_ERROR", e?.message ?? "fetch failed", 0);
   }
+  logInfo("http.res", { method, path: safePath, status: res.status, ms: Date.now() - startedAt2 });
   const text = await res.text();
   const contentType = res.headers.get("content-type") ?? "";
   let parsed = null;
@@ -1021,6 +1093,14 @@ async function request(method, path9, body, horseAuthToken, fetchImpl = fetch, i
     }
     throw new ApiError("NETWORK_ERROR", `HTTP ${res.status}`, res.status);
   }
+  if (parsed === null) {
+    const got = contentType || "no content-type";
+    throw new ApiError(
+      "NETWORK_ERROR",
+      `Expected JSON from ${method} ${safePath} but the server returned ${got} (HTTP ${res.status}). The API may be unavailable or the request was rejected upstream.`,
+      res.status
+    );
+  }
   return parsed;
 }
 
@@ -1532,11 +1612,11 @@ function PrimaryPicker({ onPick }) {
 }
 
 // src/stable/active-race.ts
-import * as fs2 from "fs/promises";
+import * as fs3 from "fs/promises";
 import * as path4 from "path";
 async function saveActiveRace(active) {
-  await fs2.mkdir(activeRacesDir(), { recursive: true });
-  await fs2.writeFile(
+  await fs3.mkdir(activeRacesDir(), { recursive: true });
+  await fs3.writeFile(
     activeRaceFile(active.join_code),
     JSON.stringify(active, null, 2) + "\n",
     "utf8"
@@ -1709,6 +1789,7 @@ function runHeartbeatLoop(opts) {
   let stopped = false;
   let pending = null;
   const stop = () => {
+    if (!stopped) logInfo("beat.stop", { retry: retryIndex });
     stopped = true;
     if (timer) clearTimeout(timer);
     timer = null;
@@ -1721,9 +1802,16 @@ function runHeartbeatLoop(opts) {
   const tick = async () => {
     if (stopped) return;
     try {
-      if (!pending) pending = await opts.prepareBeat();
+      if (!pending) {
+        logInfo("beat.prepare.start");
+        const startedAt2 = Date.now();
+        pending = await opts.prepareBeat();
+        logInfo("beat.prepare.done", { seq: pending.seq, ms: Date.now() - startedAt2 });
+      }
       const snapshot = pending;
+      const sentAt = Date.now();
       const resp = await opts.sendBeat(snapshot);
+      logInfo("beat.send.ok", { seq: snapshot.seq, ms: Date.now() - sentAt, race_status: resp.race_status });
       pending = null;
       retryIndex = 0;
       opts.onSuccess(resp, snapshot);
@@ -1736,6 +1824,13 @@ function runHeartbeatLoop(opts) {
     } catch (err) {
       opts.onError(err);
       const delay = opts.retryDelaysMs[Math.min(retryIndex, opts.retryDelaysMs.length - 1)] ?? 1e3;
+      logError("beat.send.err", {
+        seq: pending?.seq,
+        code: err?.code,
+        message: err?.message ?? String(err),
+        retry: retryIndex,
+        next_ms: delay
+      });
       retryIndex += 1;
       schedule(delay);
     }
@@ -1744,7 +1839,7 @@ function runHeartbeatLoop(opts) {
 }
 
 // src/tokens/transcripts.ts
-import * as fs4 from "fs/promises";
+import * as fs5 from "fs/promises";
 import * as path6 from "path";
 
 // src/tokens/pool.ts
@@ -1764,7 +1859,7 @@ async function mapWithConcurrency(items, limit, fn) {
 }
 
 // src/tokens/scan-cache.ts
-import * as fs3 from "fs/promises";
+import * as fs4 from "fs/promises";
 import * as path5 from "path";
 var CACHE_VERSION = 1;
 function isEntry(v) {
@@ -1802,7 +1897,7 @@ var ScanCache = class _ScanCache {
    * re-reading that line once the writer completes it.
    */
   async readIncremental(file, fold) {
-    const st = await fs3.stat(file);
+    const st = await fs4.stat(file);
     const prev = this.entries.get(file);
     this.touched.add(file);
     if (prev && prev.mtimeMs === st.mtimeMs && prev.size === st.size) return prev.value;
@@ -1819,11 +1914,11 @@ var ScanCache = class _ScanCache {
    * chats). Gated on mtime+size, recomputed in full whenever either moves.
    */
   async readWhenChanged(file, compute) {
-    const st = await fs3.stat(file);
+    const st = await fs4.stat(file);
     const prev = this.entries.get(file);
     this.touched.add(file);
     if (prev && prev.mtimeMs === st.mtimeMs && prev.size === st.size) return prev.value;
-    const value = await compute(await fs3.readFile(file, "utf8"));
+    const value = await compute(await fs4.readFile(file, "utf8"));
     this.entries.set(file, { mtimeMs: st.mtimeMs, size: st.size, offset: st.size, value });
     return value;
   }
@@ -1835,9 +1930,9 @@ var ScanCache = class _ScanCache {
     const target = cacheFile(this.source);
     const tmp = `${target}.tmp`;
     try {
-      await fs3.mkdir(path5.dirname(target), { recursive: true });
-      await fs3.writeFile(tmp, JSON.stringify({ version: CACHE_VERSION, files: Object.fromEntries(this.entries) }));
-      await fs3.rename(tmp, target);
+      await fs4.mkdir(path5.dirname(target), { recursive: true });
+      await fs4.writeFile(tmp, JSON.stringify({ version: CACHE_VERSION, files: Object.fromEntries(this.entries) }));
+      await fs4.rename(tmp, target);
     } catch {
     }
   }
@@ -1848,7 +1943,7 @@ function cacheFile(source) {
 async function loadEntries(source) {
   let parsed;
   try {
-    parsed = JSON.parse(await fs3.readFile(cacheFile(source), "utf8"));
+    parsed = JSON.parse(await fs4.readFile(cacheFile(source), "utf8"));
   } catch {
     return /* @__PURE__ */ new Map();
   }
@@ -1863,7 +1958,7 @@ async function loadEntries(source) {
 }
 async function readCompleteLines(file, start, end) {
   if (end <= start) return { lines: [], tail: null, consumedTo: start };
-  const fh = await fs3.open(file, "r");
+  const fh = await fs4.open(file, "r");
   try {
     const buf = Buffer.allocUnsafe(end - start);
     const { bytesRead } = await fh.read(buf, 0, end - start, start);
@@ -1956,13 +2051,13 @@ async function collectJsonl(dir, depth, out) {
   }
 }
 async function readEntries(dir, failLoud) {
-  if (failLoud) return readRoot(dir, () => fs4.readdir(dir, { withFileTypes: true }));
-  return fs4.readdir(dir, { withFileTypes: true }).catch(() => []);
+  if (failLoud) return readRoot(dir, () => fs5.readdir(dir, { withFileTypes: true }));
+  return fs5.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);
+  return fs5.stat(path6.join(parent, entry.name)).then((st) => st.isDirectory()).catch(() => false);
 }
 function addNum(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
@@ -1989,14 +2084,14 @@ var CLAUDE_FOLD = {
 };
 
 // src/tokens/codex.ts
-import * as fs5 from "fs/promises";
+import * as fs6 from "fs/promises";
 import * as path7 from "path";
 function num(v) {
   return typeof v === "number" && Number.isFinite(v) ? v : 0;
 }
 async function sumCodexByConversation() {
   const root = codexSessionsDir();
-  await readRoot(root, () => fs5.stat(root));
+  await readRoot(root, () => fs6.stat(root));
   const files = await listCodexRollouts(root);
   const cache = await ScanCache.open("codex");
   const totals = await mapWithConcurrency(
@@ -2028,7 +2123,7 @@ async function listCodexRollouts(root) {
 async function collectRollouts(dir) {
   let entries;
   try {
-    entries = await fs5.readdir(dir, { withFileTypes: true });
+    entries = await fs6.readdir(dir, { withFileTypes: true });
   } catch (e) {
     if (e?.code === "ENOENT") return [];
     throw e;
@@ -2066,7 +2161,7 @@ var CODEX_FOLD = {
 };
 
 // src/tokens/gemini.ts
-import * as fs6 from "fs/promises";
+import * as fs7 from "fs/promises";
 import * as path8 from "path";
 function num2(v) {
   return typeof v === "number" && Number.isFinite(v) ? v : 0;
@@ -2095,13 +2190,13 @@ async function sumGeminiTokens() {
   return { input, output };
 }
 async function listChatFiles(root) {
-  const entries = await readRoot(root, () => fs6.readdir(root));
+  const entries = await readRoot(root, () => fs7.readdir(root));
   const out = [];
   for (const entry of entries) {
     const chatsDir = path8.join(root, entry, "chats");
     let files;
     try {
-      files = await fs6.readdir(chatsDir);
+      files = await fs7.readdir(chatsDir);
     } catch {
       continue;
     }
@@ -2153,11 +2248,24 @@ async function scanWithTimeout(scan, timeoutMs, describeTimeout) {
   const budget = new Promise((resolve) => {
     timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
   });
+  const startedAt2 = Date.now();
   try {
     const result = await Promise.race([scan(), budget]);
-    if (result !== TIMED_OUT) return result;
+    if (result !== TIMED_OUT) {
+      if (isStall(result)) logWarn("scan.stall", { reason: result.stall, ms: Date.now() - startedAt2 });
+      return result;
+    }
     const detail = describeTimeout ? await describeTimeout() : null;
-    return { stall: detail ?? `Token scan timed out after ${Math.round(timeoutMs / 1e3)}s` };
+    const stall = detail ?? `Token scan timed out after ${Math.round(timeoutMs / 1e3)}s`;
+    logWarn("scan.timeout", { budget_ms: timeoutMs, reason: stall });
+    return { stall };
+  } catch (err) {
+    logError("scan.error", {
+      message: err?.message ?? String(err),
+      stack: err?.stack,
+      ms: Date.now() - startedAt2
+    });
+    throw err;
   } finally {
     clearTimeout(timer);
   }
@@ -2184,7 +2292,12 @@ async function readAllSources(race, primary, progress) {
   const secondaryKeys = MODEL_KEYS.filter((k) => k !== primary);
   const secondaryScans = secondaryKeys.map((k) => {
     progress?.begin(k);
-    return SCALAR_READERS[k]().then((t) => scoreFor(race, t)).catch(() => 0).finally(() => progress?.end(k));
+    return SCALAR_READERS[k]().then((t) => scoreFor(race, t)).catch((err) => {
+      if (!(err instanceof SourceRootMissing)) {
+        logWarn("scan.source.err", { source: k, message: err?.message ?? String(err) });
+      }
+      return 0;
+    }).finally(() => progress?.end(k));
   });
   const [primaryResult, secondaryValues] = await Promise.all([
     primaryScan,
@@ -2378,7 +2491,7 @@ var RaceScoreTracker = class {
 };
 
 // src/tokens/source-probe.ts
-import * as fs7 from "fs/promises";
+import * as fs8 from "fs/promises";
 var ROOTS = {
   claude: claudeProjectsDir,
   codex: codexSessionsDir,
@@ -2395,9 +2508,9 @@ function sourceDir(key) {
 }
 async function probeSource(key) {
   const dir = ROOTS[key]();
-  const exists = await fs7.stat(dir).then((st) => st.isDirectory()).catch(() => false);
+  const exists = await fs8.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 entries = await fs8.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 };
@@ -4077,6 +4190,31 @@ function envCommand(arg) {
   return 0;
 }
 
+// src/commands/logs.ts
+import * as fs9 from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+var DEFAULT_TAIL_LINES = 50;
+function tailCount(argv) {
+  const i = argv.indexOf("--tail");
+  if (i === -1) return null;
+  const n = Number(argv[i + 1]);
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_TAIL_LINES;
+}
+async function logsCommand(argv) {
+  const file = logFile();
+  if (!existsSync2(file)) {
+    console.log(`No log file yet \u2014 it appears at ${file} the first time a command runs.`);
+    return 0;
+  }
+  console.log(file);
+  const n = tailCount(argv);
+  if (n === null) return 0;
+  const lines = (await fs9.readFile(file, "utf8")).split("\n").filter((l) => l.length > 0);
+  console.log("");
+  for (const line of lines.slice(-n)) console.log(line);
+  return 0;
+}
+
 // src/bin.ts
 var HELP = `token-derby v${CLI_VERSION}
 
@@ -4105,6 +4243,8 @@ Identity:
 
 Maintenance:
   token-derby update                      Check for and install the latest CLI version
+  token-derby logs                        Show the path of the debug log
+  token-derby logs --tail [n]             Print the last n log lines (default 50)
 
 Stable management:
   token-derby stable create               Make a new horse (interactive)
@@ -4141,9 +4281,25 @@ Environment:
   TOKEN_DERBY_API_BASE                    Hard-override API base URL (wins over env)
   TOKEN_DERBY_HOME                        Hard-override identity/stable directory
 `;
+function describeInvocation(argv) {
+  const cmd = argv[0] ?? "(none)";
+  const container = cmd === "stable" || cmd === "organisation" || cmd === "org";
+  return {
+    cmd,
+    sub: container ? argv[1] : void 0,
+    flags: argv.filter((a) => a.startsWith("--")).map((a) => a.split("=")[0])
+  };
+}
 async function main() {
   const argv = process.argv.slice(2);
   const cmd = argv[0];
+  logInfo("cmd.start", {
+    ...describeInvocation(argv),
+    version: CLI_VERSION,
+    node: process.version,
+    pid: process.pid,
+    env: selectedEnv()
+  });
   if (!cmd || cmd === "--help" || cmd === "-h") {
     console.log(HELP);
     return 0;
@@ -4159,6 +4315,7 @@ async function main() {
   if (cmd === "login") return loginCommand(argv.slice(1));
   if (cmd === "update") return updateCommand();
   if (cmd === "env") return envCommand(argv[1]);
+  if (cmd === "logs") return logsCommand(argv.slice(1));
   const identity = await loadIdentity();
   if (!identity) {
     console.error("Run `token-derby login` to set up your identity before using any other command.");
@@ -4205,9 +4362,33 @@ function parseFlag(args, flag) {
   }
   return void 0;
 }
+var CRASH_HANDLERS_INSTALLED = /* @__PURE__ */ Symbol.for("token-derby.crash-handlers");
+if (!(CRASH_HANDLERS_INSTALLED in process)) {
+  process[CRASH_HANDLERS_INSTALLED] = true;
+  process.on("uncaughtException", (err) => {
+    logError("cmd.uncaught", { message: err?.message ?? String(err), stack: err?.stack });
+    console.error(err?.stack ?? err);
+    process.exit(1);
+  });
+  process.on("unhandledRejection", (reason) => {
+    logError("cmd.unhandled", {
+      message: reason?.message ?? String(reason),
+      stack: reason?.stack
+    });
+  });
+}
+var startedAt = Date.now();
 main().then(
-  (code) => process.exit(code),
+  (code) => {
+    logInfo("cmd.exit", { code, ms: Date.now() - startedAt });
+    process.exit(code);
+  },
   (err) => {
+    logError("cmd.crash", {
+      message: err?.message ?? String(err),
+      stack: err?.stack,
+      ms: Date.now() - startedAt
+    });
     console.error(err?.stack ?? err);
     process.exit(1);
   }