litmus-cli 1.4.0 → 1.4.2

package/dist/commands/doctor.js

@@ -0,0 +1,1055 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync, renameSync, unlinkSync, statSync } from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import * as readline from "readline/promises";
+import chalk from "chalk";
+import { readConfig, writeConfig, findProjectRoot, getEffectiveDeadline } from "../lib/config.js";
+import { fatal, setErrorContext, reportEvent } from "../lib/errors.js";
+import { formatDeadlinePT } from "../lib/format-time.js";
+import { startTracker, isTrackerHealthy, trackerDiagnostics } from "../lib/tracker.js";
+import { detectInstalledHooks, readRegistrySnapshot } from "../lib/ai-tracking.js";
+import { setupAiTracking } from "./init.js";
+import { fetchSubmitStatus, fetchInitMetadata, uploadActivityEvents, ServerError } from "../lib/api.js";
+import { resolveApiBase } from "../lib/api-base.js";
+import { collectBackfillSessions, planUploadBatches, defaultClaudeProjectsDir, } from "../lib/backfill.js";
+import { CLI_VERSION } from "../lib/version.js";
+// Doctor prints in the same grammar as `litmus status` and `litmus submit`:
+// plain 4-space "Key: value" lines where the STATE lives in the wording and
+// color, not in a status gutter. ok/fixed render plain (the words say what
+// happened), warn renders yellow, fail renders red — mirroring status's red
+// "Time remaining: PASSED" and yellow "Warning:" conventions.
+const STATUS_PAINT = {
+    ok: (s) => s,
+    fixed: (s) => s,
+    warn: chalk.yellow,
+    fail: chalk.red,
+};
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+// ── Tunables ─────────────────────────────────────────────────────
+// Backlog flush window when there is no cursor: the dead watcher's last
+// heartbeat marks roughly when server uploads stopped, and its unflushed
+// in-memory buffer held at most one heartbeat interval of events. Reaching
+// one extra interval further back trades a few duplicate rows (the server
+// stores batches append-only) for never missing the gap.
+const FLUSH_WINDOW_BEFORE_LAST_HEARTBEAT_MS = 10 * 60 * 1000;
+// Per-request caps for the backlog flush. The server accepts up to 5000
+// events per batch and rate-limits /cli/activity per candidate, so a bounded
+// number of modest batches per doctor run stays well inside both while still
+// clearing any realistic gap. Anything left over is remembered in the cursor
+// and picked up by the next run.
+export const MAX_EVENTS_PER_BATCH = 500;
+export const MAX_BATCH_BYTES = 2000000;
+const MAX_BATCHES_PER_RUN = 4;
+/** One pass over raw activity-log text: counts and latest timestamps. */
+export function scanActivityLog(text) {
+    const scan = {
+        totalBytes: Buffer.byteLength(text, "utf8"),
+        eventCount: 0,
+        malformedCount: 0,
+        aiPromptCount: 0,
+        lastEventTs: null,
+        lastHeartbeatTs: null,
+        lastLiveAiPromptTs: null,
+    };
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            scan.malformedCount++;
+            continue;
+        }
+        if (!event || typeof event !== "object") {
+            scan.malformedCount++;
+            continue;
+        }
+        scan.eventCount++;
+        const e = event;
+        if (typeof e.ts === "string")
+            scan.lastEventTs = e.ts;
+        if (e.type === "ai_prompt") {
+            scan.aiPromptCount++;
+            if (e.backfilled !== true && typeof e.ts === "string")
+                scan.lastLiveAiPromptTs = e.ts;
+        }
+        if (e.type === "heartbeat" && typeof e.ts === "string")
+            scan.lastHeartbeatTs = e.ts;
+    }
+    return scan;
+}
+/**
+ * Byte offset of the first log line whose event timestamp is at or after
+ * `cutoffMs`. Lines without a parseable timestamp don't start the window.
+ * Returns the total byte length (i.e. "flush nothing") when no line qualifies.
+ */
+export function offsetForFirstEventAtOrAfter(text, cutoffMs) {
+    let offset = 0;
+    for (const line of text.split("\n")) {
+        const lineBytes = Buffer.byteLength(line, "utf8") + 1; // + newline
+        if (line.trim()) {
+            try {
+                const event = JSON.parse(line);
+                if (typeof event.ts === "string") {
+                    const ts = Date.parse(event.ts);
+                    if (!isNaN(ts) && ts >= cutoffMs)
+                        return offset;
+                }
+            }
+            catch { /* malformed line can't start the window */ }
+        }
+        offset += lineBytes;
+    }
+    return Buffer.byteLength(text, "utf8");
+}
+/**
+ * Slice the log from `startOffset` into upload batches. Events are passed
+ * through VERBATIM (chained watcher events stay verifiable); malformed lines
+ * are skipped but still advance the offset so they are never retried forever.
+ * `startOffset` must fall on a line boundary (it always does: every stored
+ * cursor value is a `FlushBatch.endOffset`); a mid-line offset skips the torn
+ * line rather than uploading half an event.
+ */
+export function planFlushBatches(text, startOffset) {
+    const batches = [];
+    let offset = 0;
+    let current = [];
+    let currentBytes = 0;
+    let end = startOffset;
+    const finish = () => {
+        if (current.length > 0) {
+            batches.push({ events: current, endOffset: end });
+            current = [];
+            currentBytes = 0;
+        }
+    };
+    for (const line of text.split("\n")) {
+        const lineBytes = Buffer.byteLength(line, "utf8") + 1;
+        const lineStart = offset;
+        offset += lineBytes;
+        if (lineStart < startOffset)
+            continue;
+        if (!line.trim()) {
+            end = Math.min(offset, Buffer.byteLength(text, "utf8"));
+            continue;
+        }
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            end = offset; // skip malformed, but move past it
+            continue;
+        }
+        const eventBytes = Buffer.byteLength(line, "utf8");
+        if (current.length >= MAX_EVENTS_PER_BATCH || currentBytes + eventBytes > MAX_BATCH_BYTES) {
+            finish();
+        }
+        current.push(event);
+        currentBytes += eventBytes;
+        end = Math.min(offset, Buffer.byteLength(text, "utf8"));
+    }
+    finish();
+    return batches;
+}
+// ── Flush cursor (.litmus/upload-state.json) ─────────────────────
+// Records the byte offset up to which doctor has delivered locally-recorded
+// events to the server. Only exists while a recovery is in flight: a fully
+// flushed backlog removes it (live watcher uploads own everything after
+// that), and it NEVER moves backward.
+const UPLOAD_STATE_FILE = "upload-state.json";
+export function readUploadState(litmusDir) {
+    try {
+        const raw = JSON.parse(readFileSync(path.join(litmusDir, UPLOAD_STATE_FILE), "utf8"));
+        const v = raw?.flushFromBytes;
+        if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+            return v;
+    }
+    catch { /* absent or unreadable */ }
+    return null;
+}
+export function writeUploadState(litmusDir, flushFromBytes) {
+    const existing = readUploadState(litmusDir);
+    // Forward-only: a smaller offset would make the next run re-upload events
+    // the server already has.
+    const value = Math.max(existing ?? 0, flushFromBytes);
+    const target = path.join(litmusDir, UPLOAD_STATE_FILE);
+    const tmp = `${target}.litmus-tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify({ flushFromBytes: value, updatedAt: new Date().toISOString() }, null, 2) + "\n", "utf8");
+    renameSync(tmp, target);
+}
+function clearUploadState(litmusDir) {
+    try {
+        unlinkSync(path.join(litmusDir, UPLOAD_STATE_FILE));
+    }
+    catch { /* already gone */ }
+}
+// ── Small utilities ──────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function waitFor(predicate, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (predicate())
+            return true;
+        await sleep(100);
+    }
+    return predicate();
+}
+function agoText(tsMs) {
+    const delta = Math.max(0, Date.now() - tsMs);
+    const mins = Math.floor(delta / 60000);
+    if (mins < 1)
+        return "under a minute ago";
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 48)
+        return `${hours}h ${mins % 60}m ago`;
+    return `${Math.floor(hours / 24)}d ${hours % 24}h ago`;
+}
+/** Append a doctor line to .litmus/tracker.log (the tracking diagnostics log
+ *  that already ships with every submission). Never throws. */
+function logToTrackerLog(projectRoot, line) {
+    try {
+        appendFileSync(path.join(projectRoot, ".litmus", "tracker.log"), `[doctor] ${new Date().toISOString()} ${line}\n`);
+    }
+    catch { /* diagnostics logging must never break the repair */ }
+}
+// ── Config rebuild (R1) ──────────────────────────────────────────
+/**
+ * Sanity-check the times the server sent before writing a rebuilt config.
+ * Returns a human-readable problem, or null when they are usable.
+ *
+ * The failure this guards against is real: the init route used to answer
+ * every re-fetch with `startedAt: now`, and a config rebuilt from that
+ * mid-session arms the client-side deadline (startedAt + timeLimit) hours
+ * late — the tracker then sleeps through the real cutoff. The route is fixed
+ * to return the candidate's true start, and this check refuses any regression
+ * of that class rather than writing a config that lies about time.
+ *
+ * A deadline already in the past is deliberately NOT refused: the deadline
+ * check reports it, and support flows still need the config on disk.
+ */
+export function validateRebuiltTimes(meta, nowMs) {
+    const started = Date.parse(meta.startedAt);
+    if (isNaN(started))
+        return "the start time was unreadable";
+    // Small allowance for client clock skew; anything past it means the server
+    // stamped a fresh "now" instead of the real start.
+    if (started > nowMs + 2 * 60000)
+        return "the start time is in the future";
+    const effective = getEffectiveDeadline(meta);
+    if (effective !== null && effective < started)
+        return "the cutoff is earlier than the start time";
+    return null;
+}
+async function promptForToken(corrupted) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return null;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // The prompt carries its own context: it is the only place the candidate
+        // learns the settings file is gone, and it only appears when no token was
+        // passed on the command line.
+        const answer = await rl.question(`  Your assessment settings file is ${corrupted ? "unreadable" : "missing"}. Paste your assessment token to restore it (it is on your assessment page, under "Something not working?"): `);
+        return answer.trim() || null;
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Rebuild a missing or corrupted .litmus/config.json in place (R1).
+ *
+ * This is `litmus init` minus everything destructive: fetch the same
+ * metadata, write the same config — but into the CURRENT directory. Never
+ * create a folder, never download the starter zip: the candidate's work is
+ * already here, possibly days deep, and must not be touched.
+ *
+ * Either returns the freshly written config or exits via fatal() — there is
+ * no degraded mode, because every later repair (deadline, tracker, capture,
+ * uploads) needs a config to act on.
+ */
+async function rebuildConfig(args) {
+    const { projectRoot, corrupted } = args;
+    let token = args.tokenFlag?.trim() || null;
+    if (!token)
+        token = await promptForToken(corrupted);
+    if (!token) {
+        fatal("No Litmus assessment found in this directory.", 'Doctor needs your assessment token to restore it. The token is on your assessment page in the browser, under "Something not working?". Run "litmus doctor" again and paste it when asked. If you cannot find it, contact support@litmushiring.com.', { severity: "warning" });
+    }
+    const apiBase = resolveApiBase(process.env.LITMUS_API_URL);
+    setErrorContext({ token, apiBase });
+    let metadata;
+    try {
+        metadata = await fetchInitMetadata(apiBase, token);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const detail = err instanceof ServerError ? `${err.message}\n${err.detail}` : undefined;
+        const severity = err instanceof ServerError && err.statusCode && err.statusCode < 500 ? "warning" : "error";
+        fatal(msg, "Check the token and try again, or contact support@litmushiring.com for help.", { internalDetail: detail, severity });
+    }
+    setErrorContext({ candidateEmail: metadata.candidateEmail, assessmentName: metadata.assessmentName });
+    const timeProblem = validateRebuiltTimes(metadata, Date.now());
+    if (timeProblem) {
+        fatal(`The server sent assessment settings that look wrong (${timeProblem}), so nothing was written.`, "Contact support@litmushiring.com and include this output.", {
+            internalDetail: JSON.stringify({ startedAt: metadata.startedAt, deadline: metadata.deadline, timeLimit: metadata.timeLimit }),
+            severity: "error",
+        });
+    }
+    const rebuilt = {
+        assessmentId: metadata.assessmentId,
+        assessmentName: metadata.assessmentName,
+        candidateEmail: metadata.candidateEmail,
+        candidateName: metadata.candidateName,
+        token,
+        startedAt: metadata.startedAt,
+        deadline: metadata.deadline,
+        timeLimit: metadata.timeLimit,
+        walkthroughWindowMinutes: metadata.walkthroughWindowMinutes,
+        apiBase,
+        backendUrl: metadata.backendUrl,
+        cliVersion: CLI_VERSION,
+    };
+    await writeConfig(projectRoot, rebuilt);
+    return rebuilt;
+}
+// ── Tracker revival ──────────────────────────────────────────────
+/**
+ * Restart the tracker through the SAME spawn/ownership path init uses
+ * (startTracker: health check, cross-process spawn lock, watcher-side
+ * singleton claim). `graceful` handles the live-but-stalled case: ask the
+ * incumbent to flush and exit via the shutdown sentinel it already polls,
+ * then clear the stale identity files so startTracker doesn't read the
+ * incumbent as healthy and refuse to spawn.
+ *
+ * Deliberately NO SIGTERM anywhere: a stalled tracker's pid may belong to an
+ * unrelated process that recycled it, and doctor must never signal a pid it
+ * cannot verify. The sentinel only affects our own watcher, and a genuinely
+ * live-but-superseded watcher also exits on its own via the singleton claim.
+ */
+async function reviveTracker(projectRoot, opts) {
+    const litmusDir = path.join(projectRoot, ".litmus");
+    const sentinel = path.join(litmusDir, "shutdown");
+    if (opts.graceful) {
+        try {
+            writeFileSync(sentinel, String(Date.now()), "utf8");
+        }
+        catch { /* best effort */ }
+        // The watcher polls the sentinel every second and deletes it during its
+        // graceful shutdown (which also flushes its upload buffer). Give it a
+        // few seconds to do so.
+        await waitFor(() => !existsSync(sentinel), 3000);
+        // Clear the stale identity so startTracker's health check doesn't keep
+        // trusting the old pid + nonce. Control files only, never the log.
+        try {
+            unlinkSync(path.join(litmusDir, "tracker.pid"));
+        }
+        catch { /* gone */ }
+        try {
+            unlinkSync(path.join(litmusDir, "tracker.nonce"));
+        }
+        catch { /* gone */ }
+    }
+    // A leftover sentinel (e.g. written by a submit path after the watcher had
+    // already died) would make the NEW watcher shut itself down within a
+    // second of starting. Remove it before spawning.
+    try {
+        unlinkSync(sentinel);
+    }
+    catch { /* not present */ }
+    startTracker(projectRoot);
+    return waitFor(() => isTrackerHealthy(projectRoot), 3000);
+}
+// ── Diagnostic phone-home payload (R5) ───────────────────────────
+function mtimeOrNull(p) {
+    try {
+        return statSync(p).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The forensic snapshot we cannot get server-side (R5). The single most
+ * important bit is `hooks.claudeUserScope`: submit is what uninstalls the
+ * user-scope hook, so on a live assessment it discriminates "hook install
+ * worked, something later deleted the config" (true) from "install failed or
+ * fell back to project scope at init" (false) — the two surviving causes of
+ * a zero-prompts session. The mtimes date the damage; the registry shows what
+ * the shared logger could still resolve.
+ */
+export function collectDoctorDiagnostics(projectRoot, results) {
+    const litmusDir = path.join(projectRoot, ".litmus");
+    let claudeVersion = null;
+    try {
+        claudeVersion = execSync("claude --version", { timeout: 3000, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" }).trim();
+    }
+    catch { /* claude not installed or not on PATH */ }
+    return {
+        cliVersion: CLI_VERSION,
+        claudeVersion,
+        checks: Object.fromEntries(results.map((r) => [r.name, r.status])),
+        // The full candidate-facing and internal text of every check, INCLUDING
+        // the ones doctor keeps quiet on stdout. Discretion applies only to what
+        // the candidate's terminal shows — our record always gets everything.
+        checkDetails: results.map((r) => ({ name: r.name, status: r.status, detail: r.detail, ...(r.verbose ? { verbose: r.verbose } : {}) })),
+        hooks: detectInstalledHooks(projectRoot),
+        projectClaudeDirExists: existsSync(path.join(projectRoot, ".claude")),
+        litmusDir: {
+            exists: existsSync(litmusDir),
+            configMtime: mtimeOrNull(path.join(litmusDir, "config.json")),
+            activityLogMtime: mtimeOrNull(path.join(litmusDir, "activity.jsonl")),
+            trackerPidMtime: mtimeOrNull(path.join(litmusDir, "tracker.pid")),
+            trackerNonceMtime: mtimeOrNull(path.join(litmusDir, "tracker.nonce")),
+        },
+        registry: readRegistrySnapshot(),
+    };
+}
+export async function runDoctor(opts) {
+    const verbose = opts.verbose === true;
+    const results = [];
+    const record = (r) => {
+        results.push(r);
+        if (r.quiet && !verbose)
+            return;
+        console.log(`    ${STATUS_PAINT[r.status](r.detail)}`);
+        if (verbose && r.verbose)
+            console.log(chalk.dim(`      ${r.verbose}`));
+    };
+    // 1. Local assessment state ---------------------------------------------
+    // Missing OR corrupted config both route to the R1 rebuild: the two shapes
+    // have one cause in practice (cleanup tooling deleting/mangling gitignored
+    // files) and one cure (re-fetch the metadata, rewrite the file in place).
+    let config = null;
+    let configCorrupted = false;
+    try {
+        config = await readConfig();
+    }
+    catch {
+        configCorrupted = true;
+    }
+    if (config) {
+        setErrorContext({ token: config.token, apiBase: config.apiBase, candidateEmail: config.candidateEmail, assessmentName: config.assessmentName });
+    }
+    // With no readable config this is null for a missing file (rebuild lands in
+    // cwd — the email tells the candidate to run doctor inside their assessment
+    // folder) but still finds the root when the file exists and is corrupted.
+    const projectRoot = findProjectRoot() ?? process.cwd();
+    const litmusDir = path.join(projectRoot, ".litmus");
+    let configRebuilt = false;
+    if (!config) {
+        config = await rebuildConfig({ projectRoot, corrupted: configCorrupted, tokenFlag: opts.token });
+        configRebuilt = true;
+    }
+    // Title matches litmus status: the assessment name, bold. Printed after
+    // the config is resolved, because a rebuild is what tells us the name.
+    console.log();
+    console.log(chalk.bold(`  ${config.assessmentName}`));
+    console.log();
+    logToTrackerLog(projectRoot, `run started (cli ${CLI_VERSION})${configRebuilt ? " — config rebuilt" : ""}`);
+    if (configRebuilt) {
+        record({
+            name: "assessment",
+            status: "fixed",
+            detail: `Assessment: settings restored (started ${agoText(Date.parse(config.startedAt))})`,
+            verbose: `wrote ${path.join(litmusDir, "config.json")}`,
+        });
+    }
+    else {
+        const startedAt = new Date(config.startedAt);
+        record({
+            name: "assessment",
+            status: "ok",
+            detail: `Assessment: found (started ${agoText(startedAt.getTime())})`,
+            verbose: `root=${projectRoot}`,
+        });
+    }
+    // 2. Deadline vs wall clock ---------------------------------------------
+    const effectiveDeadline = getEffectiveDeadline(config);
+    let deadlineLocallyPassed = false;
+    if (effectiveDeadline === null) {
+        record({ name: "deadline", status: "ok", detail: "Time remaining: no submission cutoff configured" });
+    }
+    else {
+        const remaining = effectiveDeadline - Date.now();
+        const cutoff = formatDeadlinePT(new Date(effectiveDeadline));
+        if (remaining <= 0) {
+            deadlineLocallyPassed = true;
+            record({
+                name: "deadline",
+                status: "fail",
+                detail: `Time remaining: PASSED (cutoff was ${cutoff}). If you have not submitted, run "litmus submit" now and contact support@litmushiring.com.`,
+            });
+        }
+        else {
+            const remHours = Math.floor(remaining / 3600000);
+            const remMins = Math.floor((remaining % 3600000) / 60000);
+            record({
+                name: "deadline",
+                status: "ok",
+                detail: `Time remaining: ${remHours}h ${remMins}m (cutoff ${cutoff})`,
+                verbose: `auto-submit fires at the cutoff while the tracker is running`,
+            });
+        }
+    }
+    // 3. Activity log (read-only: doctor NEVER rewrites or truncates it) -----
+    const activityPath = path.join(litmusDir, "activity.jsonl");
+    let scan = null;
+    let logText = "";
+    if (existsSync(activityPath)) {
+        try {
+            logText = readFileSync(activityPath, "utf8");
+            scan = scanActivityLog(logText);
+            const last = scan.lastEventTs ? `, last event ${agoText(Date.parse(scan.lastEventTs))}` : "";
+            const malformed = scan.malformedCount > 0 ? ` (${scan.malformedCount} unreadable lines, left as-is)` : "";
+            record({
+                name: "activity_log",
+                status: scan.malformedCount > 0 ? "warn" : "ok",
+                detail: `Activity log: ${scan.eventCount} events${last}${malformed}`,
+                verbose: `${scan.totalBytes} bytes, ${scan.aiPromptCount} AI prompts, last heartbeat ${scan.lastHeartbeatTs ?? "never"}`,
+            });
+        }
+        catch (err) {
+            record({
+                name: "activity_log",
+                status: "fail",
+                detail: "Activity log: could not be read. Do not delete it; contact support@litmushiring.com.",
+                verbose: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    else {
+        record({
+            name: "activity_log",
+            status: "warn",
+            detail: "Activity log: none yet (it is created as soon as the tracker runs)",
+        });
+    }
+    // 4. Server round-trip ----------------------------------------------------
+    // A real authenticated request, not a ping: this is how doctor detects the
+    // silent failure where the server has started rejecting uploads (expired or
+    // invalid token) while everything looks fine locally.
+    console.log(); // stanza break: local state above, connections and repairs below
+    const backendUrl = config.backendUrl || config.apiBase;
+    let channel = "unreachable";
+    try {
+        await fetchSubmitStatus(backendUrl, config.token);
+        channel = "healthy";
+        // Quiet: a healthy connection is implied by the absence of a red line
+        // (failures below always print). Saying it out loud just teaches the
+        // candidate that there is a token to worry about.
+        record({ name: "server", status: "ok", quiet: true, detail: "Server connection: OK, your access token is accepted" });
+    }
+    catch (err) {
+        if (err instanceof ServerError && (err.errorCode === "Token expired" || err.statusCode === 403)) {
+            channel = "session_over";
+            record({
+                name: "server",
+                status: "fail",
+                detail: "Server connection: the server reports this assessment has ended. If that seems wrong, contact support@litmushiring.com.",
+                verbose: `HTTP ${err.statusCode}: ${err.message}`,
+            });
+        }
+        else if (err instanceof ServerError && (err.statusCode === 401 || err.statusCode === 404)) {
+            channel = "bad_token";
+            record({
+                name: "server",
+                status: "fail",
+                detail: "Server connection: your access token was not accepted, so activity uploads are failing. Contact support@litmushiring.com and include this output.",
+                verbose: `HTTP ${err.statusCode}: ${err.message}`,
+            });
+        }
+        else {
+            channel = "unreachable";
+            record({
+                name: "server",
+                status: "fail",
+                detail: "Server connection: FAILED. Check your internet connection, then run \"litmus doctor\" again.",
+                verbose: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    logToTrackerLog(projectRoot, `server probe: ${channel}`);
+    // Repairs only make sense while the session is (or may still be) live.
+    const sessionOver = channel === "session_over" || (channel !== "healthy" && deadlineLocallyPassed);
+    // 5. Tracker liveness + revival ------------------------------------------
+    const diag = trackerDiagnostics(projectRoot);
+    // A live pid that no longer reads healthy stopped heartbeating within the
+    // liveness window: a wedged watcher, a recycled pid over a dead one, or a
+    // machine just woken from sleep. All deserve a GRACEFUL restart (sentinel
+    // ask, then the watcher-side singleton contest settles any survivor).
+    const stalled = diag.pidAlive && !diag.healthy;
+    const trackerWasUnhealthy = !diag.healthy;
+    // R3: a healthy tracker is still the WRONG tracker after a config rebuild.
+    // It read the old config at spawn, so its deadline auto-submit is armed from
+    // the stale startedAt + timeLimit (and a latch that already fired never
+    // retries). Only a restart re-arms it from the restored settings.
+    const staleInMemory = configRebuilt && diag.healthy;
+    const diagVerbose = `pid=${diag.pid ?? "none"} alive=${diag.pidAlive} lastLivenessSignal=${diag.nonceAgeMs === null ? "never" : Math.round(diag.nonceAgeMs / 1000) + "s ago"}`;
+    if (sessionOver) {
+        record({
+            name: "tracker",
+            status: diag.healthy ? "warn" : "ok",
+            detail: diag.healthy
+                ? "Tracker: still running, but the assessment has ended. It will stop on its own."
+                : "Tracker: not running (the assessment has ended, so it was not restarted)",
+            verbose: diagVerbose,
+        });
+    }
+    else if (diag.healthy && !staleInMemory) {
+        record({ name: "tracker", status: "ok", detail: "Tracker: running", verbose: diagVerbose });
+    }
+    else {
+        const why = !diag.pidAlive
+            ? "it was not running"
+            : stalled
+                ? "it had stopped responding"
+                : staleInMemory
+                    ? "it was still using your old settings"
+                    : "it was not running";
+        logToTrackerLog(projectRoot, `tracker ${why} (${diagVerbose}); restarting`);
+        let revived = false;
+        try {
+            revived = await reviveTracker(projectRoot, { graceful: stalled || staleInMemory });
+        }
+        catch (err) {
+            logToTrackerLog(projectRoot, `restart threw: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (revived) {
+            const rearm = effectiveDeadline !== null && effectiveDeadline > Date.now()
+                ? ", auto-submit at the cutoff is armed"
+                : "";
+            record({
+                name: "tracker",
+                status: "fixed",
+                detail: `Tracker: resumed${rearm}`,
+                verbose: `restarted because ${why}; after restart: ${JSON.stringify(trackerDiagnostics(projectRoot))}`,
+            });
+            logToTrackerLog(projectRoot, "tracker restarted successfully");
+        }
+        else {
+            record({
+                name: "tracker",
+                status: "fail",
+                detail: "Tracker: could not be restarted. Try reinstalling the CLI (npm install -g litmus-cli), run \"litmus doctor\" again, and contact support@litmushiring.com if this line repeats.",
+                verbose: diagVerbose,
+            });
+            logToTrackerLog(projectRoot, "tracker restart FAILED");
+        }
+    }
+    // 6. AI-usage capture hooks ----------------------------------------------
+    // Editor updates and cleanup tools clobber these. Reinstall goes through
+    // setupAiTracking, the exact code init runs: idempotent merges that keep
+    // the candidate's own hooks and never overwrite an earlier config backup
+    // (see backupAside in ai-tracking.ts).
+    //
+    // Capture stands on three legs and doctor reports each one every run (R2):
+    // the per-editor hook configs, the shared logger they invoke, and the
+    // active-assessments registry the logger resolves this folder through.
+    // Any one missing means prompts silently stop being recorded.
+    let aiCaptureFixed = false;
+    {
+        const hooksVerboseOf = (h) => `claude=${h.claude ?? "none"} codex=${h.codex} cursor=${h.cursor} copilot=${h.copilot} registered=${h.registered} logger=${h.loggerPresent}`;
+        const printLegs = (h) => {
+            const leg = (ok, label) => {
+                console.log(`      ${ok ? chalk.green("+") : chalk.red("x")} ${chalk.dim(label)}`);
+            };
+            const claudeDesc = h.claude === "user"
+                ? "installed"
+                : h.claude === "project"
+                    ? "installed inside this folder only"
+                    : "NOT installed";
+            leg(h.claude !== null && h.codex && h.cursor && h.copilot, `editor hooks: Claude Code ${claudeDesc}; Codex ${h.codex ? "installed" : "NOT installed"}, Cursor ${h.cursor ? "installed" : "NOT installed"}, Copilot ${h.copilot ? "installed" : "NOT installed"}`);
+            leg(h.loggerPresent, `shared capture helper: ${h.loggerPresent ? "present" : "MISSING"}`);
+            leg(h.registered, `this folder registered for capture: ${h.registered ? "yes" : "NO"}`);
+        };
+        // Project-scope Claude capture lives inside the assessment folder — the
+        // same gitignored blast radius as .litmus/, deletable by the same cleanup
+        // that causes these incidents. It works, but it is fragile, so doctor
+        // always tries for user scope and never treats the fallback as silent
+        // success (R2).
+        const warnProjectScope = (why) => {
+            console.log(chalk.yellow("    Note: Claude Code capture could only be installed inside this folder"));
+            console.log(chalk.yellow(`    because your personal Claude settings could not be updated${why ? ` (${why})` : ""}.`));
+            console.log(chalk.yellow("    Please keep the .claude folder here; deleting it turns capture off."));
+        };
+        const hooks = detectInstalledHooks(projectRoot);
+        const missing = [];
+        if (hooks.claude !== "user")
+            missing.push("Claude Code");
+        if (!hooks.codex)
+            missing.push("Codex");
+        if (!hooks.cursor)
+            missing.push("Cursor");
+        if (!hooks.copilot)
+            missing.push("Copilot");
+        const healthy = missing.length === 0 && hooks.loggerPresent && hooks.registered;
+        if (healthy) {
+            record({ name: "ai_capture", status: "ok", quiet: true, detail: "AI usage capture: installed for Claude Code, Codex, Cursor, and Copilot", verbose: hooksVerboseOf(hooks) });
+            if (verbose)
+                printLegs(hooks);
+        }
+        else if (sessionOver) {
+            record({ name: "ai_capture", status: "warn", quiet: true, detail: "AI usage capture: incomplete, but the assessment has ended so it was left alone", verbose: hooksVerboseOf(hooks) });
+            if (verbose)
+                printLegs(hooks);
+        }
+        else {
+            logToTrackerLog(projectRoot, `ai capture incomplete (${hooksVerboseOf(hooks)}); reinstalling`);
+            try {
+                const setup = setupAiTracking(projectRoot);
+                const after = detectInstalledHooks(projectRoot);
+                // Fixed = every leg the installed mode needs is standing. In project
+                // mode the logger is folder-local and the registry is deliberately
+                // not used, so those legs read differently.
+                const repaired = after.claude === "user"
+                    ? after.loggerPresent && after.registered
+                    : after.claude === "project";
+                const stillProjectScope = after.claude === "project";
+                record({
+                    name: "ai_capture",
+                    status: !repaired ? "fail" : stillProjectScope ? "warn" : "fixed",
+                    // A clean reinstall is our plumbing — quiet. The project-scope
+                    // fallback stays loud because the candidate must not delete .claude.
+                    quiet: repaired && !stillProjectScope,
+                    detail: !repaired
+                        ? "AI usage capture: could not be reinstalled. Contact support@litmushiring.com and include this output."
+                        : stillProjectScope
+                            ? "AI usage capture: reinstalled, but Claude Code capture is folder-local (see the note below)"
+                            : `AI usage capture: reinstalled (was incomplete: ${missing.length > 0 ? missing.join(", ") : "shared files missing"})`,
+                    verbose: `after reinstall: ${hooksVerboseOf(after)}`,
+                });
+                if (verbose)
+                    printLegs(after);
+                if (stillProjectScope)
+                    warnProjectScope(setup.userScopeError);
+                aiCaptureFixed = repaired;
+                logToTrackerLog(projectRoot, `ai capture reinstall ${!repaired ? "FAILED" : stillProjectScope ? `fell back to project scope (${setup.userScopeError ?? "unknown"})` : "succeeded"}`);
+            }
+            catch (err) {
+                record({
+                    name: "ai_capture",
+                    status: "fail",
+                    detail: "AI usage capture: could not be reinstalled. Contact support@litmushiring.com and include this output.",
+                    verbose: err instanceof Error ? err.message : String(err),
+                });
+                logToTrackerLog(projectRoot, `ai capture reinstall threw: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    // 7. Backlog flush ---------------------------------------------------------
+    // Everything the trackers record lands in activity.jsonl first, so the file
+    // is the source of truth. When the watcher died, its last few minutes of
+    // events never reached the server; deliver that gap now (verbatim, through
+    // the same /cli/activity endpoint) so the team's monitoring sees the
+    // recovery. The cursor makes this resumable and strictly forward-moving.
+    {
+        const cursor = readUploadState(litmusDir);
+        let flushFrom = null;
+        if (cursor !== null) {
+            flushFrom = Math.min(cursor, scan?.totalBytes ?? cursor);
+        }
+        else if (trackerWasUnhealthy && scan?.lastHeartbeatTs) {
+            const cutoff = Date.parse(scan.lastHeartbeatTs) - FLUSH_WINDOW_BEFORE_LAST_HEARTBEAT_MS;
+            flushFrom = offsetForFirstEventAtOrAfter(logText, cutoff);
+        }
+        if (flushFrom === null) {
+            record({
+                name: "uploads",
+                status: "ok",
+                quiet: true,
+                detail: channel === "healthy"
+                    ? "Pending uploads: none. Activity is delivered to the server as it happens."
+                    : "Pending uploads: none recorded so far.",
+            });
+        }
+        else if (channel !== "healthy") {
+            // Remember the gap so the next doctor run delivers it once the server
+            // is reachable again.
+            let remembered = false;
+            try {
+                writeUploadState(litmusDir, flushFrom);
+                remembered = true;
+            }
+            catch { /* reported below */ }
+            const pending = planFlushBatches(logText, flushFrom).reduce((n, b) => n + b.events.length, 0);
+            record({
+                name: "uploads",
+                status: "fail",
+                detail: `Pending uploads: ${pending} recorded events have not reached the server yet. Nothing is lost; they are saved on this machine. Run "litmus doctor" again once you are back online.`,
+                verbose: `flushFrom=${flushFrom} rememberedCursor=${remembered}`,
+            });
+            logToTrackerLog(projectRoot, `flush skipped (channel=${channel}); pending=${pending} from byte ${flushFrom}`);
+        }
+        else {
+            const batches = planFlushBatches(logText, flushFrom);
+            const totalEvents = batches.reduce((n, b) => n + b.events.length, 0);
+            if (totalEvents === 0) {
+                clearUploadState(litmusDir);
+                record({ name: "uploads", status: "ok", quiet: true, detail: "Pending uploads: none. Activity is delivered to the server as it happens." });
+            }
+            else {
+                let sent = 0;
+                let lastGood = flushFrom;
+                let failure = null;
+                for (const batch of batches.slice(0, MAX_BATCHES_PER_RUN)) {
+                    try {
+                        await uploadActivityEvents(backendUrl, config.token, batch.events);
+                        sent += batch.events.length;
+                        lastGood = batch.endOffset;
+                    }
+                    catch (err) {
+                        failure = err instanceof Error ? err.message : String(err);
+                        break;
+                    }
+                }
+                const remaining = totalEvents - sent;
+                if (remaining === 0 && failure === null) {
+                    clearUploadState(litmusDir);
+                    record({
+                        name: "uploads",
+                        status: "fixed",
+                        quiet: true,
+                        detail: `Pending uploads: delivered ${sent} recorded events the server was missing`,
+                        verbose: `flushed bytes ${flushFrom}..${lastGood}`,
+                    });
+                    logToTrackerLog(projectRoot, `flushed ${sent} events (bytes ${flushFrom}..${lastGood})`);
+                }
+                else {
+                    try {
+                        writeUploadState(litmusDir, lastGood);
+                    }
+                    catch { /* next run recomputes */ }
+                    record({
+                        name: "uploads",
+                        status: failure ? "fail" : "warn",
+                        detail: failure
+                            ? `Pending uploads: delivered ${sent} of ${totalEvents} before the connection failed. Nothing is lost; run "litmus doctor" again to send the rest.`
+                            : `Pending uploads: delivered ${sent} of ${totalEvents} (large backlog). Run "litmus doctor" again to send the rest.`,
+                        verbose: failure ?? `cursor now at byte ${lastGood}`,
+                    });
+                    logToTrackerLog(projectRoot, `flush partial: ${sent}/${totalEvents}${failure ? ` (error: ${failure})` : ""}`);
+                }
+            }
+        }
+    }
+    // 8. Prompt backfill from Claude Code transcripts (R4) ---------------------
+    // The hook logger records nothing while the config is unresolvable, but the
+    // prompts survive in Claude Code's own session transcripts. Re-synthesize
+    // and upload them — every event marked `backfilled: true`, counts printed,
+    // never silently (see lib/backfill.ts for the invariants).
+    //
+    // Runs AUTOMATICALLY when this run proved capture was broken (config had to
+    // be rebuilt, or the capture hooks had to be repaired) — the candidate just
+    // runs `litmus doctor` and the gap heals. The automatic window starts at the
+    // last LIVE-captured prompt, which makes it self-limiting: on a setup where
+    // capture worked all along, doctor never reaches this section, and the
+    // window would be empty even if it did. `--backfill-prompts` forces a run
+    // over the whole assessment (support-guided); `--no-backfill` opts out.
+    const backfillForced = opts.backfillPrompts === true;
+    const backfillAuto = !backfillForced && opts.backfill !== false && (configRebuilt || aiCaptureFixed);
+    let backfillSummary = null;
+    if ((backfillForced || backfillAuto) && channel !== "healthy") {
+        record({
+            name: "backfill",
+            status: backfillForced ? "fail" : "warn",
+            detail: sessionOver
+                ? "AI activity recovery: skipped, the server reports this assessment has ended"
+                : 'AI activity recovery: skipped, the server could not be reached. Run "litmus doctor" again when you are back online.',
+        });
+    }
+    else if (backfillForced || backfillAuto) {
+        let sinceMs = null;
+        let sinceLabel;
+        if (opts.since) {
+            sinceMs = Date.parse(opts.since);
+            if (isNaN(sinceMs)) {
+                fatal(`Could not understand --since "${opts.since}".`, "Use an ISO timestamp like 2026-08-07T19:00:00Z.", { severity: "warning" });
+            }
+            sinceLabel = new Date(sinceMs).toISOString();
+        }
+        else if (backfillAuto && scan?.lastLiveAiPromptTs) {
+            // Everything before the last live-captured prompt already reached the
+            // record through the normal path; only the gap after it can be missing.
+            sinceMs = Date.parse(scan.lastLiveAiPromptTs);
+            if (isNaN(sinceMs))
+                sinceMs = null;
+            sinceLabel = sinceMs === null ? "the beginning" : `your last recorded AI prompt (${new Date(sinceMs).toISOString()})`;
+        }
+        else {
+            const started = Date.parse(config.startedAt);
+            sinceMs = isNaN(started) ? null : started;
+            sinceLabel = sinceMs === null ? "the beginning" : `your assessment start (${new Date(sinceMs).toISOString()})`;
+        }
+        const transcripts = collectBackfillSessions({
+            claudeProjectsDir: defaultClaudeProjectsDir(),
+            assessmentRoot: projectRoot,
+            allSessions: opts.allSessions === true,
+            sinceMs,
+        });
+        const scopeLabel = opts.allSessions === true
+            ? "every Claude Code session on this machine"
+            : "Claude Code sessions in this assessment folder";
+        const allEvents = transcripts.sessions.flatMap((s) => s.events);
+        const promptCount = transcripts.sessions.reduce((n, s) => n + s.prompts, 0);
+        const responseCount = transcripts.sessions.reduce((n, s) => n + s.responses, 0);
+        if (allEvents.length === 0) {
+            record({
+                name: "backfill",
+                status: "ok",
+                // Quiet on the automatic path; someone who passed --backfill-prompts
+                // asked a question and gets the answer.
+                quiet: !backfillForced,
+                detail: "AI activity recovery: nothing to recover",
+                verbose: `scope: ${scopeLabel}, since ${sinceLabel}; scanned ${transcripts.scannedFiles} transcript files, ${transcripts.skippedOversized.length} oversized, ${transcripts.unreadable.length} unreadable`,
+            });
+        }
+        else {
+            // Local record first, prompts only: local copies survive an upload
+            // failure, while full response bodies (30KB each) stay upload-only so
+            // they cannot bloat activity.jsonl past the submission-zip cap.
+            const localPrompts = allEvents.filter((e) => e.type === "ai_prompt");
+            try {
+                appendFileSync(activityPath, localPrompts.map((e) => JSON.stringify(e)).join("\n") + "\n");
+            }
+            catch { /* upload is the real delivery; the summary event below still records the run */ }
+            let uploaded = 0;
+            let failure = null;
+            for (const batch of planUploadBatches(allEvents)) {
+                try {
+                    await uploadActivityEvents(backendUrl, config.token, batch);
+                    uploaded += batch.length;
+                }
+                catch (err) {
+                    failure = err instanceof Error ? err.message : String(err);
+                    break;
+                }
+            }
+            backfillSummary = {
+                trigger: backfillForced ? "flag" : "auto",
+                scope: opts.allSessions === true ? "all_sessions" : "assessment_dir",
+                since: sinceMs === null ? null : new Date(sinceMs).toISOString(),
+                sessions: transcripts.sessions.length,
+                prompts: promptCount,
+                responses: responseCount,
+                uploaded,
+                skippedOversized: transcripts.skippedOversized.length,
+                unreadable: transcripts.unreadable.length,
+            };
+            // The local summary event is appended ALWAYS (even on upload failure):
+            // it is the durable, submission-visible record that a recovery ran and
+            // exactly what it took (the never-silent half of the over-capture rule).
+            try {
+                appendFileSync(activityPath, JSON.stringify({
+                    ts: new Date().toISOString(),
+                    type: "backfill_run",
+                    cliVersion: CLI_VERSION,
+                    backfillSource: "claude_transcript",
+                    ...backfillSummary,
+                }) + "\n");
+            }
+            catch { /* nothing else to do locally */ }
+            const recovered = `AI activity recovery: recovered ${plural(promptCount, "prompt")} and ${plural(responseCount, "response")} from ${plural(transcripts.sessions.length, "session")}`;
+            record({
+                name: "backfill",
+                status: failure ? "fail" : "fixed",
+                detail: failure
+                    ? `${recovered}, but only ${uploaded} of ${allEvents.length} events reached the server before the connection failed. Run "litmus doctor${backfillForced ? " --backfill-prompts" : ""}" again to send the rest.`
+                    : recovered,
+                verbose: failure ?? `scope: ${scopeLabel}, since ${sinceLabel}; scanned ${transcripts.scannedFiles} transcript files, ${transcripts.skippedOversized.length} oversized, ${transcripts.unreadable.length} unreadable`,
+            });
+            // Show the candidate exactly what was taken, per session.
+            const projectsDir = defaultClaudeProjectsDir();
+            for (const s of transcripts.sessions) {
+                const shortName = path.relative(projectsDir, s.file);
+                console.log(chalk.dim(`      • ${shortName}: ${plural(s.prompts, "prompt")}, ${plural(s.responses, "response")}`));
+            }
+            logToTrackerLog(projectRoot, `backfill: ${uploaded}/${allEvents.length} events uploaded from ${transcripts.sessions.length} sessions (scope=${backfillSummary.scope})${failure ? ` error: ${failure}` : ""}`);
+        }
+    }
+    // 9. Record the run --------------------------------------------------------
+    const fixed = results.filter((r) => r.status === "fixed");
+    const problems = results.filter((r) => r.status === "fail");
+    const summaryLine = `doctor v${CLI_VERSION}: ${results.map((r) => `${r.name}=${r.status}`).join(" ")}`;
+    const doctorEvent = {
+        ts: new Date().toISOString(),
+        type: "doctor_run",
+        cliVersion: CLI_VERSION,
+        checks: results.map((r) => ({ name: r.name, status: r.status })),
+        repaired: fixed.map((r) => r.name),
+        problems: problems.map((r) => r.name),
+        ...(backfillSummary ? { backfill: backfillSummary } : {}),
+    };
+    // Local record first (same append-only pattern as the hook logger; carries
+    // no chain fields, so the watcher chain is untouched). Ships in the zip.
+    try {
+        appendFileSync(activityPath, JSON.stringify(doctorEvent) + "\n");
+    }
+    catch { /* log may be unwritable; the tracker.log lines still record the run */ }
+    logToTrackerLog(projectRoot, summaryLine);
+    // Server-side record: the doctor_run activity event (visible to monitoring
+    // next to the watcher's own events) plus the diagnostic phone-home below.
+    if (channel === "healthy") {
+        try {
+            await uploadActivityEvents(backendUrl, config.token, [doctorEvent]);
+        }
+        catch { /* the reportEvent below still records the run server-side */ }
+    }
+    // R5: diagnostic phone-home. Severity gates on whether anything was wrong:
+    // "error" reaches platform-health monitoring (a candidate whose setup needed
+    // repair is exactly what the team must see); "info" on clean runs stays
+    // log-only so healthy doctor runs never page anyone. The part of the message
+    // before "Internal detail:" is the server's dedupe key — keep it stable.
+    const stableSummary = problems.length > 0
+        ? `litmus doctor: problems remain (${problems.map((r) => r.name).sort().join(", ")})`
+        : fixed.length > 0
+            ? `litmus doctor: repaired (${fixed.map((r) => r.name).sort().join(", ")})`
+            : "litmus doctor: healthy";
+    const diagnostics = collectDoctorDiagnostics(projectRoot, results);
+    await reportEvent(problems.length > 0 || fixed.length > 0 ? "error" : "info", `${stableSummary}\n\nInternal detail: ${JSON.stringify(diagnostics)}`, undefined, "doctor");
+    // 10. Summary + exit code ---------------------------------------------------
+    console.log();
+    // The repaired count only counts VISIBLE fixes, so the sentence matches the
+    // lines the candidate just read. Quiet internal fixes (upload bookkeeping,
+    // hook refreshes) still get "healthy now" rather than the false "no changes
+    // were made", and the machine line + records always carry the full set.
+    const visibleFixed = fixed.filter((r) => !r.quiet);
+    if (problems.length > 0) {
+        console.log(chalk.red(`  ${problems.length} problem${problems.length === 1 ? "" : "s"} need${problems.length === 1 ? "s" : ""} attention.`));
+        console.log(chalk.dim("  Copy this whole output into an email to support@litmushiring.com if you need help."));
+    }
+    else if (visibleFixed.length > 0) {
+        console.log(chalk.green(`  Repaired ${visibleFixed.length} issue${visibleFixed.length === 1 ? "" : "s"}. Everything is healthy now; you can keep working.`));
+    }
+    else if (fixed.length > 0) {
+        console.log(chalk.green("  Everything is healthy now; you can keep working."));
+    }
+    else {
+        console.log(chalk.green("  Everything is healthy. No changes were made."));
+    }
+    console.log(chalk.dim(`  ${summaryLine}`));
+    // After a capture-affecting repair, close with the self-check. Deliberately
+    // NOT a wait: an in-terminal wait blocks the very terminal the candidate
+    // would use to send the test prompt (their typed input piles into doctor's
+    // stdin and executes in the shell after exit).
+    // Quieted for now (verbose-only) — support-guided runs still get it, and
+    // the candidate default ends at the summary.
+    if (verbose && !sessionOver && (configRebuilt || aiCaptureFixed)) {
+        console.log();
+        console.log(chalk.bold("  One more step, to confirm AI capture is working again:"));
+        console.log("  Open your AI assistant (Claude Code, Cursor, Codex, or Copilot) in this");
+        console.log(`  folder and send any short prompt. Then run ${chalk.cyan("litmus status")}: the`);
+        console.log('  "AI prompts captured" count should go up within a few seconds.');
+    }
+    console.log();
+    process.exitCode = problems.length > 0 ? 1 : 0;
+}
+//# sourceMappingURL=doctor.js.map