@mauricode/token-derby 3.1.0 → 3.1.3

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.3".length > 0) {
+    return "3.1.3";
   }
   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");
@@ -905,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() {
@@ -959,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) {
@@ -970,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();
@@ -990,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, {
@@ -998,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;
@@ -1016,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;
 }
 
@@ -1527,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"
@@ -1559,7 +1644,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 +1715,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 }),
@@ -1695,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;
@@ -1707,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);
@@ -1722,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);
     }
@@ -1730,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
@@ -1750,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) {
@@ -1788,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;
@@ -1805,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;
   }
@@ -1821,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 {
     }
   }
@@ -1834,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();
   }
@@ -1849,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);
@@ -1869,6 +1978,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 +2032,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, () => 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 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;
 }
@@ -1953,18 +2084,15 @@ 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 fs5.stat(root);
-  const files = [
-    ...await collectRollouts(path7.join(root, "sessions")),
-    ...await collectRollouts(path7.join(root, "archived_sessions"))
-  ];
+  await readRoot(root, () => fs6.stat(root));
+  const files = await listCodexRollouts(root);
   const cache = await ScanCache.open("codex");
   const totals = await mapWithConcurrency(
     files,
@@ -1986,10 +2114,16 @@ 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 {
-    entries = await fs5.readdir(dir, { withFileTypes: true });
+    entries = await fs6.readdir(dir, { withFileTypes: true });
   } catch (e) {
     if (e?.code === "ENOENT") return [];
     throw e;
@@ -2027,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;
@@ -2056,13 +2190,13 @@ async function sumGeminiTokens() {
   return { input, output };
 }
 async function listChatFiles(root) {
-  const entries = await 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;
     }
@@ -2114,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);
   }
@@ -2145,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,
@@ -2154,7 +2306,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 +2373,7 @@ var RaceScoreTracker = class {
   seq;
   stalls = 0;
   lastStall = null;
+  primaryEmptyBeats = 0;
   primary;
   primaryTop5;
   constructor(init, primary, primaryTop5) {
@@ -2253,6 +2406,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 +2458,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 +2490,75 @@ var RaceScoreTracker = class {
   }
 };
 
+// src/tokens/source-probe.ts
+import * as fs8 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 fs8.stat(dir).then((st) => st.isDirectory()).catch(() => false);
+  if (!exists) return { key, dir, exists: false, projects: 0, transcripts: 0 };
+  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 };
+}
+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 +2575,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 +2607,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 +2675,8 @@ function RunRace({ active, initialState, pendingMode, ownUserName }) {
         lastHeartbeatOk: lastHbOk,
         stalled,
         stallReason,
+        primarySilent,
+        primarySourceDir: sourceDir(active.primary_model),
         primaryModel: active.primary_model
       }
     ),
@@ -2513,6 +2744,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 +2860,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 +3173,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++) {
@@ -3943,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}
 
@@ -3971,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)
@@ -4007,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;
@@ -4025,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.");
@@ -4071,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);
   }