@ipv9/tokentracker-cli 0.39.43 → 0.39.45

package/src/lib/doctor.js

@@ -1,9 +1,15 @@
 const fs = require("node:fs/promises");
+const { findRowViolations } = require("./queue-compact");
 const { constants } = require("node:fs");
 const path = require("node:path");
 
 const { readJsonStrict } = require("./fs");
 
+// Stands in for a check whose `id` is missing or not a usable string, so that such
+// a check can still be counted rather than silently dropped. See rule 2 in
+// `listDegradedChecks`.
+const UNNAMED_CHECK_ID = "(unnamed)";
+
 async function buildDoctorReport({
   runtime = {},
   diagnostics = null,
@@ -11,6 +17,7 @@ async function buildDoctorReport({
   now = () => new Date(),
   paths = {},
   system = null,
+  ingest = null,
 } = {}) {
   const checks = [];
 
@@ -28,26 +35,140 @@ async function buildDoctorReport({
   if (paths.cliPath) {
     checks.push(await checkCliEntrypoint(paths.cliPath));
   }
+  if (paths.queuePath) {
+    checks.push(await checkQueueRows(paths.queuePath));
+  }
 
   // No cloud reachability check: TokenTracker is local-only, so there is no
   // remote endpoint whose availability could affect anything here.
 
+  if (ingest) {
+    const suppression = buildTranscriptSuppressionCheck(ingest.transcriptSuppression);
+    if (suppression) checks.push(suppression);
+  }
+
   if (diagnostics) {
     checks.push(...buildDiagnosticsChecks(diagnostics));
   }
 
   const summary = summarizeChecks(checks);
+  const degradedChecks = listDegradedChecks(checks);
 
   return {
     version: 1,
     generated_at: now().toISOString(),
     ok: summary.critical === 0,
+    // `ok` answers "should this exit non-zero", and only `critical` moves it.
+    // A warning therefore leaves an entirely green-looking report, which is
+    // exactly how a source going unrecorded stayed invisible. `degraded` is the
+    // machine-readable half of that distinction: automation can alert on it
+    // without any existing caller's exit code changing.
+    //
+    // It counts every warn and fail except a warn whose check marked itself
+    // `advisory`. A first version counted every warn, which made it useless on the
+    // one machine it was written for: that box carries a standing
+    // `queue.row_invariant` warn about two parseable invariant violations, so
+    // `degraded` read true
+    // on a perfectly healthy day and an alert wired to it could never clear. An
+    // always-on alert and an alert that never fires fail the same way.
+    // `listDegradedChecks` holds the exact rule including its two fail-closed
+    // clauses. Advisory is assigned at the individual warning return site: a
+    // standing condition can opt out without muting an actionable warning from
+    // the same check id.
+    degraded: degradedChecks.length > 0,
+    // Which checks put it there. Without this, `degraded: true` is unactionable —
+    // a consumer has to re-derive the reason by walking `checks` itself, and a
+    // human reading the JSON cannot tell a new problem from the standing one.
+    degraded_checks: degradedChecks,
     summary,
     checks,
     diagnostics,
   };
 }
 
+// A check is advisory when its warn describes a standing condition the operator
+// cannot act on in the moment. Such a check still reports `warn` and still appears
+// in `summary.warn`: the report does not become quieter, only the alert signal
+// becomes specific. Anything that does not opt in counts, so a new check is
+// alert-worthy by default and has to argue its way out.
+//
+// Two rules here are deliberately fail-CLOSED, because the failure this field
+// exists to prevent is a real problem reading as silence, and both were live
+// holes in the first version of this function:
+//
+//   1. `advisory` suppresses a `warn` and NOTHING ELSE. The rationale for the
+//      flag is about standing warnings; nothing argues for muting a `fail` on the
+//      same id, so a `fail` degrades the report whatever the flag says.
+//   2. A check with a missing or malformed `id` is still counted, under
+//      UNNAMED_CHECK_ID. The earlier version mapped to `check.id` and then
+//      dropped non-strings, so an id typo silently removed a genuine warn from
+//      `degraded` altogether — it rendered as `[WARN] unknown` to a human and as
+//      nothing at all to automation. A placeholder keeps `degraded` and
+//      `degraded_checks` honest and in agreement.
+function listDegradedChecks(checks = []) {
+  return checks
+    .filter((check) => check && (check.status === "warn" || check.status === "fail"))
+    // A malformed id overrides advisory suppression. Advisory is an explicit
+    // classification made at a known warning call site; if that identity is
+    // lost, fail closed under the placeholder rather than silently dropping it.
+    .filter((check) => !(
+      check.status === "warn"
+      && check.advisory === true
+      && typeof check.id === "string"
+      && check.id.trim().length > 0
+    ))
+    .map((check) =>
+      typeof check.id === "string" && check.id.trim().length > 0 ? check.id : UNNAMED_CHECK_ID,
+    )
+    .sort();
+}
+
+// Reports Claude CLI processes that were started with `--no-session-persistence`.
+// Those sessions write no transcript, and transcripts are the only thing the
+// Claude parser can read, so their tokens are unobservable to TokenTracker.
+//
+// Returns null when the platform cannot answer the question at all. A check that
+// was never run must not be printed as `[OK]` — absence is honest, a green line
+// would not be.
+function buildTranscriptSuppressionCheck(detection) {
+  if (!detection || detection.supported === false) return null;
+
+  const id = "ingest.transcript_suppressed";
+
+  if (!detection.checked) {
+    return {
+      id,
+      status: "warn",
+      detail: "Could not read the process list, so transcript-suppressed sessions were not checked",
+      critical: false,
+      meta: { checked: false, reason: detection.reason || "process_list_failed" },
+    };
+  }
+
+  const count = Number(detection.count) || 0;
+  if (count === 0) {
+    return {
+      id,
+      status: "ok",
+      detail: "No Claude CLI process is running with --no-session-persistence",
+      critical: false,
+      meta: { checked: true, count: 0, models: [] },
+    };
+  }
+
+  const models = Array.isArray(detection.models) ? detection.models : [];
+  const modelSuffix = models.length ? ` (${models.join(", ")})` : "";
+  return {
+    id,
+    status: "warn",
+    detail:
+      `${count} Claude CLI process${count === 1 ? "" : "es"} running with --no-session-persistence${modelSuffix}`
+      + " - these sessions write no transcript, so their token usage cannot be recorded",
+    critical: false,
+    meta: { checked: true, count, models },
+  };
+}
+
 async function buildSystemChecks({
   nodeVersion = process.version,
   platform = process.platform,
@@ -78,11 +199,14 @@ function buildNodeVersionCheck(nodeVersion) {
 async function buildBrowserOpenerCheck({ platform = process.platform, env = process.env, commandExists }) {
   const headless = isHeadlessEnvironment({ platform, env });
   if (headless) {
+    // Standing environment property: neither --no-open nor opening the printed
+    // URL manually can make a headless session acquire a browser opener.
     return {
       id: "browser.opener",
       status: "warn",
       detail: "headless/session environment detected; use --no-open or open the printed URL manually",
       critical: false,
+      advisory: true,
       meta: { platform, command: null, headless: true },
     };
   }
@@ -328,14 +452,21 @@ function buildDiagnosticsChecks(diagnostics) {
     notify.claude_hook_configured ||
     notify.gemini_hook_configured ||
     notify.opencode_plugin_configured ||
-    notify.openclaw_hook_configured,
+    notify.openclaw_hook_configured ||
+    notify.openclaw_session_plugin_configured ||
+    notify.grok_hook_configured,
   );
 
+  // This aggregate describes an optional integration preference, not whether
+  // passive log ingestion works. `init` also skips hooks for providers whose
+  // config is absent, so "none configured" can be a stable, intentional state.
+  // Keep only that warn advisory; this check currently has no fail path.
   checks.push({
     id: "notify.configured",
     status: notifyConfigured ? "ok" : "warn",
     detail: notifyConfigured ? "notify configured" : "notify not configured",
     critical: false,
+    ...(notifyConfigured ? {} : { advisory: true }),
     meta: { configured: notifyConfigured },
   });
 
@@ -358,8 +489,103 @@ function summarizeChecks(checks = []) {
   return summary;
 }
 
+// CLAUDE.md states the column invariant in prose:
+//
+//   total = input + output + cache_creation + cache_read + reasoning
+//
+// Nothing enforced it at runtime, so a miswritten or corrupt row was aggregated
+// and rendered rather than flagged — and a parser bug of exactly that shape is
+// the class CLAUDE.md records at 1.6-7x magnitude. Same conversion as the
+// curated-expiry and version-lockstep checks: a rule that lived in a document
+// starts running.
+//
+// A warn rather than a fail: the rows are already on disk and already being
+// rendered, so failing the whole health check would be reporting a crisis the
+// user cannot act on in the moment. What they can act on is knowing which rows,
+// and how many.
+const QUEUE_VIOLATIONS_SHOWN = 5;
+
+// `advisory: true` keeps a warn out of `degraded` and `degraded_checks` while
+// leaving it a full `warn` in `checks` and in `summary.warn`. The flag is decided
+// PER CALL SITE, not once for this check id, because the two warns this check can
+// emit are not the same kind of thing:
+//
+//   - a parseable row-invariant violation IS advisory: the row is already written
+//     and rendered, so there is nothing the operator can do at report time.
+//   - an unparseable line or unreadable queue is NOT. Those conditions omit usage
+//     or can stop ingestion and are actionable (corruption, permissions, disk).
+//
+// An earlier version of this function stamped `advisory: true` on everything it
+// returned, which silenced the unreadable case: `warn` in `checks`,
+// `degraded: false` on the wire. Default is NOT advisory, so a new call site has
+// to argue its way out rather than inherit silence.
+function queueCheck(status, detail, meta, { advisory = false } = {}) {
+  const check = { id: "queue.row_invariant", status, detail, critical: false, meta };
+  return advisory ? { ...check, advisory: true } : check;
+}
+
+async function readQueueRowsForDoctor(queuePath) {
+  const raw = await fs.readFile(queuePath, "utf8");
+  const rows = [];
+  let malformed = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      rows.push(JSON.parse(line));
+    } catch {
+      malformed += 1;
+    }
+  }
+  return { rows, malformed };
+}
+
+async function checkQueueRows(queuePath) {
+  let rows;
+  let malformed;
+  try {
+    ({ rows, malformed } = await readQueueRowsForDoctor(queuePath));
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      return queueCheck("ok", "no queue yet", { path: queuePath });
+    }
+    return queueCheck("warn", `queue unreadable: ${err?.message || err}`, { path: queuePath });
+  }
+
+  const violations = findRowViolations(rows);
+  if (violations.length === 0 && malformed === 0) {
+    return queueCheck("ok", `${rows.length} rows satisfy the column invariant`, {
+      path: queuePath,
+      rows: rows.length,
+    });
+  }
+
+  const parts = [];
+  if (violations.length > 0) parts.push(`${violations.length} row problem(s)`);
+  if (malformed > 0) parts.push(`${malformed} unparseable line(s)`);
+  // Parseable invariant violations are already on disk and already aggregated
+  // into what the dashboard renders, so they are advisory. Malformed lines are
+  // skipped by local-api readers and their usage is absent; corruption or a
+  // partial write is actionable and must degrade the report.
+  return queueCheck(
+    "warn",
+    `${parts.join(", ")} in ${rows.length + malformed} line(s)`,
+    {
+      path: queuePath,
+      rows: rows.length,
+      malformed,
+      violations: violations.length,
+      examples: violations.slice(0, QUEUE_VIOLATIONS_SHOWN),
+    },
+    { advisory: malformed === 0 },
+  );
+}
+
 module.exports = {
   buildDoctorReport,
+  buildTranscriptSuppressionCheck,
+  listDegradedChecks,
+  UNNAMED_CHECK_ID,
+  checkQueueRows,
   buildBrowserOpenerCheck,
   buildNodeVersionCheck,
   isHeadlessEnvironment,