litmus-cli 1.4.0 → 1.4.2

package/dist/lib/chain.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tamper-evidence chain resume for the activity log.
+ *
+ * Watcher events carry `_seq` / `_prevHash` / `_hash` fields forming a hash
+ * chain. The watcher used to initialize the chain at genesis (`seq 0`,
+ * all-zero prev hash) on every start — fine when a watcher started exactly
+ * once per assessment, but a watcher can now be legitimately restarted
+ * mid-assessment (crash + `litmus doctor` revival, machine reboot on a
+ * multi-day assessment). Each genesis restart would leave activity.jsonl
+ * holding several disjoint chains, losing the single-sequence property the
+ * chain fields exist to provide.
+ *
+ * Instead, a starting watcher resumes from the LAST chained event already in
+ * the log: next `_seq` continues the count, `_prevHash` links to the last
+ * `_hash`. Non-chained events (the hook logger's `ai_prompt` / `ai_response`
+ * lines carry no chain fields) are skipped, as are malformed lines.
+ */
+export interface ChainResumePoint {
+    nextSeq: number;
+    prevHash: string;
+}
+export declare const GENESIS_HASH: string;
+/**
+ * Find the resume point in raw activity-log text (newest chained line wins).
+ * The text may start mid-line (tail reads truncate); unparseable lines are
+ * skipped, so a torn first line never matters.
+ */
+export declare function resumeChainFromLogText(text: string): ChainResumePoint;
+/**
+ * Return where the chain should resume by scanning `activityLogPath` backward,
+ * window by window, until a chained event is found. Missing or unreadable
+ * log → genesis (a fresh assessment has no chain yet). Never writes; a
+ * failure here must not stop the watcher from starting.
+ *
+ * A line can straddle a window boundary, so each window carries the bytes
+ * before its predecessor's first newline (`carry`) and re-parses that
+ * boundary line whole. The carry is raw bytes, not decoded text: slicing a
+ * multi-byte UTF-8 character mid-sequence and decoding the halves separately
+ * would corrupt the very line being reconstructed.
+ */
+export declare function resumeChainFromLog(activityLogPath: string): ChainResumePoint;
+//# sourceMappingURL=chain.d.ts.map

package/dist/lib/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../../src/lib/chain.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,eAAO,MAAM,YAAY,QAAiB,CAAA;AA+C1C;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAErE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,gBAAgB,CA2B5E"}

package/dist/lib/chain.js

@@ -0,0 +1,98 @@
+import fs from "fs";
+export const GENESIS_HASH = "0".repeat(64);
+const GENESIS = { nextSeq: 0, prevHash: GENESIS_HASH };
+// The log is scanned BACKWARD in windows of this size until a chained event
+// is found (or the file start is reached). A single bounded tail read is not
+// enough: unchained events — the hook logger's ai_prompt/ai_response lines,
+// and especially a doctor prompt backfill, which can append hundreds of KB of
+// them in one run — can pile up after the last chained watcher event, and a
+// scan that gives up after one window would silently restart the chain at
+// genesis. The scan reads exactly as far back as the newest chained event,
+// which in practice is within the first window (heartbeats land every 5
+// minutes whenever a watcher is running).
+const CHAIN_SCAN_WINDOW_BYTES = 256 * 1024;
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+function chainedPointFromLine(line) {
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return null; // torn or malformed line
+    }
+    if (!event || typeof event !== "object")
+        return null;
+    const { _seq, _hash } = event;
+    if (typeof _seq === "number" && Number.isInteger(_seq) && _seq >= 0 &&
+        typeof _hash === "string" && HASH_PATTERN.test(_hash)) {
+        return { nextSeq: _seq + 1, prevHash: _hash };
+    }
+    return null;
+}
+/** Newest chained line in the text, or null. Unparseable lines are skipped. */
+function scanTextForChained(text) {
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        const point = chainedPointFromLine(line);
+        if (point)
+            return point;
+    }
+    return null;
+}
+/**
+ * Find the resume point in raw activity-log text (newest chained line wins).
+ * The text may start mid-line (tail reads truncate); unparseable lines are
+ * skipped, so a torn first line never matters.
+ */
+export function resumeChainFromLogText(text) {
+    return scanTextForChained(text) ?? GENESIS;
+}
+/**
+ * Return where the chain should resume by scanning `activityLogPath` backward,
+ * window by window, until a chained event is found. Missing or unreadable
+ * log → genesis (a fresh assessment has no chain yet). Never writes; a
+ * failure here must not stop the watcher from starting.
+ *
+ * A line can straddle a window boundary, so each window carries the bytes
+ * before its predecessor's first newline (`carry`) and re-parses that
+ * boundary line whole. The carry is raw bytes, not decoded text: slicing a
+ * multi-byte UTF-8 character mid-sequence and decoding the halves separately
+ * would corrupt the very line being reconstructed.
+ */
+export function resumeChainFromLog(activityLogPath) {
+    try {
+        const stat = fs.statSync(activityLogPath);
+        if (stat.size === 0)
+            return GENESIS;
+        const fd = fs.openSync(activityLogPath, "r");
+        try {
+            let end = stat.size; // exclusive end of the region still unscanned
+            let carry = Buffer.alloc(0); // partial first line of the window above
+            while (end > 0) {
+                const start = Math.max(0, end - CHAIN_SCAN_WINDOW_BYTES);
+                const buf = Buffer.alloc(end - start);
+                fs.readSync(fd, buf, 0, buf.length, start);
+                const window = carry.length > 0 ? Buffer.concat([buf, carry]) : buf;
+                const point = scanTextForChained(window.toString("utf8"));
+                if (point)
+                    return point;
+                if (start === 0)
+                    break;
+                const firstNewline = window.indexOf(0x0a);
+                carry = firstNewline === -1 ? window : window.subarray(0, firstNewline);
+                end = start;
+            }
+            return GENESIS;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return GENESIS;
+    }
+}
+//# sourceMappingURL=chain.js.map

package/dist/lib/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../../src/lib/chain.ts"],"names":[],"mappings":"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"}

package/dist/lib/detect-project.d.ts

@@ -2,7 +2,42 @@ export type ProjectType = "node" | "python" | "go" | "java" | "dotnet" | "rust"
 export interface ProjectInfo {
     type: ProjectType;
     installCommand: string | null;
+    /**
+     * Set for `python` projects when the venv had to be built on an interpreter
+     * that is NOT the one the submission gets graded on. `init` surfaces it so
+     * the candidate learns about the skew here, rather than from a syntax error
+     * the README told them could not happen.
+     */
+    toolchainWarning?: string;
 }
+/**
+ * The Python the candidate's submission is actually GRADED on.
+ *
+ * Not a floor — an exact version, because we own both ends. The E2B grading
+ * image (`backend/assessment/template.py`) installs 3.12 from deadsnakes and
+ * points the candidate-facing `python`/`python3`/`pip` at it, and the workspace
+ * image is `litmus-base-python-3.12`. Anything a candidate writes has to run
+ * there, so that is the interpreter their local venv should be built on.
+ *
+ * Keep in sync with `GRADING_PYTHON_VERSION` in `backend/agent/system_prompt.py`
+ * and the deadsnakes pin in `backend/assessment/template.py` —
+ * `backend/tests/test_candidate_python_version_alignment.py` fails if they drift.
+ */
+export declare const GRADING_PYTHON_VERSION = "3.12";
+/**
+ * Pick the interpreter to build the assessment venv with.
+ *
+ * Never fatal: a candidate with no `GRADING_PYTHON_VERSION` still gets a venv
+ * and a warning. Blocking `litmus init` on a missing interpreter would be a far
+ * worse failure than the mismatch itself. If nothing probes clean we still
+ * return the platform's conventional name so the install is *attempted* — and
+ * `init` reports that attempt's outcome separately.
+ */
+export declare function resolvePythonInterpreter(): {
+    command: string;
+    matchesGrader: boolean;
+    detectedVersion: string | null;
+};
 /**
  * Detect project type and suggest an install command.
  */

package/dist/lib/detect-project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect-project.d.ts","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,QAAQ,GACR,MAAM,GACN,MAAM,GACN,KAAK,GACL,SAAS,CAAA;AAEb,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAwDtD"}
+{"version":3,"file":"detect-project.d.ts","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,QAAQ,GACR,MAAM,GACN,MAAM,GACN,KAAK,GACL,SAAS,CAAA;AAEb,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,SAAS,CAAA;AA0D5C;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,OAAO,CAAA;IACtB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B,CAkBA;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAwEtD"}

package/dist/lib/detect-project.js

@@ -1,5 +1,97 @@
+import { spawnSync } from "child_process";
 import { existsSync, readdirSync } from "fs";
 import path from "path";
+/**
+ * The Python the candidate's submission is actually GRADED on.
+ *
+ * Not a floor — an exact version, because we own both ends. The E2B grading
+ * image (`backend/assessment/template.py`) installs 3.12 from deadsnakes and
+ * points the candidate-facing `python`/`python3`/`pip` at it, and the workspace
+ * image is `litmus-base-python-3.12`. Anything a candidate writes has to run
+ * there, so that is the interpreter their local venv should be built on.
+ *
+ * Keep in sync with `GRADING_PYTHON_VERSION` in `backend/agent/system_prompt.py`
+ * and the deadsnakes pin in `backend/assessment/template.py` —
+ * `backend/tests/test_candidate_python_version_alignment.py` fails if they drift.
+ */
+export const GRADING_PYTHON_VERSION = "3.12";
+/**
+ * Interpreters to try, best first.
+ *
+ * The exact `GRADING_PYTHON_VERSION` comes first because the grader runs
+ * exactly that: a NEWER local interpreter is not "safe" the way a newer runtime
+ * usually is — 3.13 syntax parses locally and then fails in the sandbox.
+ *
+ * The rest are fallbacks, and their ORDER IS PLATFORM-SPECIFIC:
+ *   - Windows: `py` (the launcher) then `python`. `python3` is deliberately
+ *     last, because on Windows it is usually not a real interpreter at all —
+ *     python.org's installer ships `python.exe` + `py.exe` and no `python3.exe`,
+ *     and a stock Windows has an App Execution Alias at `python3.exe` that
+ *     opens the Microsoft Store instead of running anything. Preferring it
+ *     would hand a Windows candidate a command that cannot build a venv.
+ *   - Everywhere else: `python3`. Bare `python` is not a fallback on Unix —
+ *     where it exists at all it is as likely to be a Python 2 or a shim.
+ */
+function pythonCandidates() {
+    const version = GRADING_PYTHON_VERSION;
+    if (process.platform === "win32") {
+        return [
+            { bin: "py", args: [`-${version}`], command: `py -${version}` },
+            { bin: "py", args: [], command: "py" },
+            { bin: "python", args: [], command: "python" },
+            { bin: "python3", args: [], command: "python3" },
+        ];
+    }
+    return [
+        { bin: `python${version}`, args: [], command: `python${version}` },
+        { bin: "python3", args: [], command: "python3" },
+    ];
+}
+/** `Python 3.12.4` on stdout (or stderr, on ancient builds) → `3.12.4`. */
+function probeVersion(candidate) {
+    try {
+        const probed = spawnSync(candidate.bin, [...candidate.args, "--version"], {
+            encoding: "utf8",
+            shell: process.platform === "win32",
+        });
+        if (probed.status !== 0)
+            return null;
+        const match = /Python (\d+\.\d+(?:\.\d+)?)/.exec(`${probed.stdout ?? ""}${probed.stderr ?? ""}`);
+        return match ? match[1] : null;
+    }
+    catch {
+        // Treat an unspawnable probe exactly like a missing interpreter.
+        return null;
+    }
+}
+/**
+ * Pick the interpreter to build the assessment venv with.
+ *
+ * Never fatal: a candidate with no `GRADING_PYTHON_VERSION` still gets a venv
+ * and a warning. Blocking `litmus init` on a missing interpreter would be a far
+ * worse failure than the mismatch itself. If nothing probes clean we still
+ * return the platform's conventional name so the install is *attempted* — and
+ * `init` reports that attempt's outcome separately.
+ */
+export function resolvePythonInterpreter() {
+    const candidates = pythonCandidates();
+    for (const candidate of candidates) {
+        const detectedVersion = probeVersion(candidate);
+        if (!detectedVersion)
+            continue;
+        return {
+            command: candidate.command,
+            // `py -3.12` can only ever be 3.12, but `python`/`python3` are whatever
+            // the machine has — so match on the PROBED version, never on which
+            // candidate we happened to be trying.
+            matchesGrader: detectedVersion.startsWith(`${GRADING_PYTHON_VERSION}.`) ||
+                detectedVersion === GRADING_PYTHON_VERSION,
+            detectedVersion,
+        };
+    }
+    const last = candidates[candidates.length - 1];
+    return { command: last.command, matchesGrader: false, detectedVersion: null };
+}
 /**
  * Detect project type and suggest an install command.
  */
@@ -20,10 +112,26 @@ export function detectProject(dir) {
         // Create a venv and install into it (replaces what the old setup.sh did).
         // Use venv/bin/pip directly so activation isn't required at install time.
         const pipBin = process.platform === "win32" ? "venv\\Scripts\\pip" : "venv/bin/pip";
+        const python = resolvePythonInterpreter();
         const installCommand = existsSync(path.join(dir, "requirements.txt"))
-            ? `python3 -m venv venv && ${pipBin} install -r requirements.txt`
-            : `python3 -m venv venv && ${pipBin} install -e .`;
-        return { type: "python", installCommand };
+            ? `${python.command} -m venv venv && ${pipBin} install -r requirements.txt`
+            : `${python.command} -m venv venv && ${pipBin} install -e .`;
+        // States the SKEW, not what happened: `init` runs this command and reports
+        // its outcome separately, so a warning that claimed the venv "was built"
+        // would contradict the failure message whenever the install did not run.
+        // The two cases read differently on purpose — "venv/ uses that interpreter"
+        // is nonsense when there is no interpreter to use.
+        const toolchainWarning = python.matchesGrader
+            ? undefined
+            : python.detectedVersion
+                ? `Your submission is graded on Python ${GRADING_PYTHON_VERSION}, but this machine has ` +
+                    `Python ${python.detectedVersion} (\`${python.command}\`), which venv/ uses. Code that only ` +
+                    `runs on a different version will fail when graded. Install Python ` +
+                    `${GRADING_PYTHON_VERSION} and re-run \`litmus init\` to avoid the mismatch.`
+                : `No Python interpreter was found on your PATH, so \`${python.command} -m venv\` will ` +
+                    `probably fail. Your submission is graded on Python ${GRADING_PYTHON_VERSION} — install ` +
+                    `that version and re-run \`litmus init\`.`;
+        return { type: "python", installCommand, toolchainWarning };
     }
     if (existsSync(path.join(dir, "go.mod"))) {
         return { type: "go", installCommand: "go mod download" };

package/dist/lib/detect-project.js.map

@@ -1 +1 @@
-{"version":3,"file":"detect-project.js","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"detect-project.js","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"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"}

package/dist/lib/errors.d.ts

@@ -10,6 +10,25 @@ declare let errorContext: {
 };
 export declare function setErrorContext(ctx: Partial<typeof errorContext>): void;
 export type Severity = "error" | "warning" | "info";
+/**
+ * POST a CLI event to the server for logging and optional email notification.
+ *
+ * severity:
+ *   "error"   → our fault (server errors, bugs) → email + log
+ *   "warning" → candidate's fault (wrong dir, deadline, too large) → log only
+ *   "info"    → success events (init complete, submission received) → log only
+ *
+ * Never rejects — candidate experience is unaffected if this fails.
+ *
+ * Exported for `litmus doctor`'s diagnostic phone-home: doctor sends its
+ * forensic payload at severity "error" when it found or repaired problems,
+ * because "warning" and "info" are log-only server-side and a capture outage
+ * reported at warning severity is invisible to the team (that is exactly how
+ * a mid-session config deletion went unnoticed for hours). The server splits
+ * `message` on "\n\nInternal detail:" — keep the part before it stable so
+ * platform-health dedupe keeps working.
+ */
+export declare function reportEvent(severity: Severity, message: string, hint?: string, event?: string): Promise<void>;
 /**
  * Fire-and-forget: log a success event (init complete, submission received).
  * Never blocks or affects the candidate.

package/dist/lib/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,6BAA6B,CAAA;AAEtD,qBAAa,UAAW,SAAQ,KAAK;;CAEpC;AAID,QAAA,IAAI,YAAY,EAAE;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAEN,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,YAAY,CAAC,GAAG,IAAI,CAEvE;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;AAyCnD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,GAAG;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,GAC/D,KAAK,CA2BP;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,6BAA6B,CAAA;AAEtD,qBAAa,UAAW,SAAQ,KAAK;;CAEpC;AAID,QAAA,IAAI,YAAY,EAAE;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAEN,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,YAAY,CAAC,GAAG,IAAI,CAEvE;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,GAAG;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,GAC/D,KAAK,CA2BP;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C"}

package/dist/lib/errors.js

@@ -25,8 +25,16 @@ export function setErrorContext(ctx) {
  *   "info"    → success events (init complete, submission received) → log only
  *
  * Never rejects — candidate experience is unaffected if this fails.
+ *
+ * Exported for `litmus doctor`'s diagnostic phone-home: doctor sends its
+ * forensic payload at severity "error" when it found or repaired problems,
+ * because "warning" and "info" are log-only server-side and a capture outage
+ * reported at warning severity is invisible to the team (that is exactly how
+ * a mid-session config deletion went unnoticed for hours). The server splits
+ * `message` on "\n\nInternal detail:" — keep the part before it stable so
+ * platform-health dedupe keeps working.
  */
-function reportEvent(severity, message, hint, event) {
+export function reportEvent(severity, message, hint, event) {
     const apiBase = errorContext.apiBase || process.env.LITMUS_API_URL || DEFAULT_API_BASE;
     const url = `${apiBase}/api/cli/errors`;
     const payload = JSON.stringify({

package/dist/lib/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"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"}

package/dist/lib/tracker.d.ts

@@ -1,3 +1,29 @@
+/**
+ * True when a healthy watcher of ours is running for this project.
+ *
+ * Deliberately the SAME check startTracker uses to decide whether to respawn,
+ * so callers can't disagree with it. A bare `process.kill(pid, 0)` is not
+ * enough: macOS recycles PIDs from a small space, so a dead watcher's PID can
+ * belong to an unrelated live process — which would read as "running" while
+ * nothing is being recorded. The nonce cross-check is what rules that out.
+ */
+export declare function isTrackerHealthy(projectDir: string): boolean;
+/**
+ * Raw tracker liveness signals for `litmus doctor` — the boolean predicate
+ * plus the inputs it was computed from, so doctor can explain WHY a tracker
+ * reads as unhealthy and distinguish "no process" from "live pid that stopped
+ * heartbeating" (nonce older than the liveness window: a wedged watcher, a
+ * recycled pid over a dead one, or a machine that just woke from sleep).
+ */
+export interface TrackerDiagnostics {
+    pid: number | null;
+    pidAlive: boolean;
+    /** ms since the watcher last proved liveness (nonce mtime), or null if no nonce. */
+    nonceAgeMs: number | null;
+    /** The same predicate startTracker/isTrackerHealthy use. */
+    healthy: boolean;
+}
+export declare function trackerDiagnostics(projectDir: string): TrackerDiagnostics;
 /**
  * Start the file watcher in the background.
  * Spawns watcher.js as a detached process; logs file events to

package/dist/lib/tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/lib/tracker.ts"],"names":[],"mappings":"AA+CA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAwCrD"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/lib/tracker.ts"],"names":[],"mappings":"AA4FA;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAM5D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,QAAQ,EAAE,OAAO,CAAA;IACjB,oFAAoF;IACpF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAsBzE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAqErD"}

package/dist/lib/tracker.js

@@ -1,16 +1,29 @@
 import { spawn } from "child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync, statSync } from "fs";
+import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync, statSync, unlinkSync, closeSync } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const NONCE_FILE = "tracker.nonce";
-// Max gap between watcher startup time (nonce mtime) and `now` to treat a
-// matching PID as legitimate rather than a recycled PID belonging to an
-// unrelated host process. Watcher writes the nonce immediately after spawn,
-// so even a freshly-started CLI session reads a recent nonce. If the gap is
-// larger than this, the PID is stale and we re-spawn.
-const NONCE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+// Max gap between the watcher's last heartbeat (nonce mtime) and `now` to treat
+// a matching PID as legitimate rather than a recycled PID belonging to an
+// unrelated host process. The watcher touches the nonce on startup and on every
+// heartbeat, so a live watcher refreshes this every 5 minutes.
+//
+// THREE MISSED HEARTBEATS, not seven days. The old window only ruled out
+// WEEK-OLD pid reuse: a watcher that died minutes ago whose pid was recycled by
+// an unrelated live process still read as healthy, so `litmus status` skipped
+// the revival and the rest of the session went unrecorded — the exact failure
+// ENG-1215 is about. 3 missed beats matches the house convention for the same
+// question elsewhere (HOST_CORDON_AFTER_SECONDS = 180 = 3 x 60s).
+//
+// Tightening this was previously unsafe and is not any more. The risk was the
+// other direction: a laptop that sleeps for an hour leaves a live watcher with a
+// stale nonce, so we would respawn and end up with TWO watchers interleaving
+// _seq/_prevHash chains on one activity.jsonl. watcher.ts now re-checks the pid
+// claim every second, so the loser exits within ~1s of the spawn. A spurious
+// respawn is self-correcting; a missed revival is not.
+const NONCE_MAX_AGE_MS = 15 * 60 * 1000; // 15 min = 3 missed 5-minute heartbeats
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0); // Signal 0 = check if process exists
@@ -45,6 +58,74 @@ function isExistingTrackerOurs(pidFile, noncePath) {
         return false;
     }
 }
+const SPAWN_LOCK_FILE = "tracker.spawn.lock";
+// A spawn is a few milliseconds of syscalls. Anything older than this was
+// leaked by a process that died mid-spawn, not a live contender — reclaim it
+// rather than blocking tracking for the rest of the session.
+const SPAWN_LOCK_STALE_MS = 30000;
+/**
+ * Exclusive, cross-platform spawn lock. `wx` fails if the file exists, and that
+ * create-or-fail is atomic, so exactly one caller wins.
+ *
+ * Returns the fd on success, or null when another process holds a fresh lock.
+ */
+function acquireSpawnLock(lockPath) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            return openSync(lockPath, "wx");
+        }
+        catch {
+            // Held. Only reclaim it if it's older than any real spawn could take.
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > SPAWN_LOCK_STALE_MS) {
+                    unlinkSync(lockPath);
+                    continue; // retry once against the now-free path
+                }
+            }
+            catch {
+                continue; // vanished between open and stat — the holder just released
+            }
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * True when a healthy watcher of ours is running for this project.
+ *
+ * Deliberately the SAME check startTracker uses to decide whether to respawn,
+ * so callers can't disagree with it. A bare `process.kill(pid, 0)` is not
+ * enough: macOS recycles PIDs from a small space, so a dead watcher's PID can
+ * belong to an unrelated live process — which would read as "running" while
+ * nothing is being recorded. The nonce cross-check is what rules that out.
+ */
+export function isTrackerHealthy(projectDir) {
+    const litmusDir = path.join(projectDir, ".litmus");
+    return isExistingTrackerOurs(path.join(litmusDir, "tracker.pid"), path.join(litmusDir, NONCE_FILE));
+}
+export function trackerDiagnostics(projectDir) {
+    const litmusDir = path.join(projectDir, ".litmus");
+    const pidFile = path.join(litmusDir, "tracker.pid");
+    const noncePath = path.join(litmusDir, NONCE_FILE);
+    let pid = null;
+    try {
+        const parsed = parseInt(readFileSync(pidFile, "utf8").trim(), 10);
+        if (!isNaN(parsed))
+            pid = parsed;
+    }
+    catch { /* no pid file */ }
+    let nonceAgeMs = null;
+    try {
+        nonceAgeMs = Date.now() - statSync(noncePath).mtimeMs;
+    }
+    catch { /* no nonce */ }
+    return {
+        pid,
+        pidAlive: pid !== null && isProcessAlive(pid),
+        nonceAgeMs,
+        healthy: isExistingTrackerOurs(pidFile, noncePath),
+    };
+}
 /**
  * Start the file watcher in the background.
  * Spawns watcher.js as a detached process; logs file events to
@@ -71,22 +152,58 @@ export function startTracker(projectDir) {
     // is our watcher and silently disabling tracking.
     if (isExistingTrackerOurs(pidFile, noncePath))
         return;
-    const errFd = openSync(errLog, "a");
-    const watcherPath = path.join(__dirname, "watcher.js");
-    const cliBinPath = path.join(__dirname, "..", "index.js");
-    // Pass the nonce path so the watcher can touch it on startup + heartbeat.
-    const child = spawn(process.execPath, [watcherPath, projectDir, activityLog, cliBinPath, noncePath], {
-        detached: true,
-        stdio: ["ignore", "ignore", errFd],
-    });
-    if (child.pid) {
-        child.unref();
+    // Serialize spawns across processes. Without this, two callers racing (e.g.
+    // two `litmus status` runs against a dead watcher) can both pass the health
+    // check above and each spawn a watcher; the second pid write then hides the
+    // first, leaving two live watchers appending to the same activity.jsonl with
+    // independent _seq/_prevHash chains. That corrupts the tamper-evidence chain
+    // (ENG-952), double-counts events, and arms two deadline auto-submits.
+    const lockPath = path.join(litmusDir, SPAWN_LOCK_FILE);
+    const lockFd = acquireSpawnLock(lockPath);
+    if (lockFd === null)
+        return; // another process is mid-spawn; let it win
+    try {
+        // Re-check under the lock: the winner of a race may have finished spawning
+        // between our check above and our acquiring the lock.
+        if (isExistingTrackerOurs(pidFile, noncePath))
+            return;
+        const errFd = openSync(errLog, "a");
+        const watcherPath = path.join(__dirname, "watcher.js");
+        const cliBinPath = path.join(__dirname, "..", "index.js");
+        // Pass the nonce path so the watcher can touch it on startup + heartbeat.
+        const child = spawn(process.execPath, [watcherPath, projectDir, activityLog, cliBinPath, noncePath], {
+            detached: true,
+            stdio: ["ignore", "ignore", errFd],
+        });
+        if (child.pid) {
+            child.unref();
+            try {
+                writeFileSync(pidFile, String(child.pid), "utf8");
+                // Stamp the nonce HERE, in the parent, rather than leaving it to the
+                // watcher's own touchNonce() on boot. isExistingTrackerOurs requires
+                // pid-alive AND a nonce, and the watcher needs ~100ms of Node startup
+                // before it writes one — so between spawn and that first write, a
+                // freshly-spawned watcher reads as UNHEALTHY. Concurrent callers then
+                // each spawn their own (observed: 6 watchers from 8 racing calls, even
+                // with the spawn lock, because each re-check under the lock saw a
+                // nonce-less pid). The watcher refreshes this on startup and on every
+                // heartbeat; the parent write just closes the boot-time gap.
+                writeFileSync(noncePath, String(Date.now()), "utf8");
+            }
+            catch {
+                // Non-critical
+            }
+        }
+    }
+    finally {
         try {
-            writeFileSync(pidFile, String(child.pid), "utf8");
+            closeSync(lockFd);
         }
-        catch {
-            // Non-critical
+        catch { /* already closed */ }
+        try {
+            unlinkSync(lockPath);
         }
+        catch { /* already reclaimed */ }
     }
 }
 //# sourceMappingURL=tracker.js.map