litmus-cli 1.4.3 → 1.4.6

package/dist/lib/watcher.js

@@ -14,6 +14,7 @@
  * Writes newline-delimited JSON to the activity log.
  */
 import fs from "fs";
+import os from "os";
 import path from "path";
 import crypto from "crypto";
 import { execSync, execFile } from "child_process";
@@ -21,11 +22,17 @@ import dns from "dns";
 import https from "https";
 import http from "http";
 import { watch as chokidarWatch } from "chokidar";
-import { getEffectiveDeadline } from "./config.js";
+import { getEffectiveDeadline, writeConfig, validateRebuiltTimes, computeTimeSync } from "./config.js";
 import { CLI_VERSION } from "./version.js";
-import { armDeadlineAutoSubmit } from "./deadline.js";
+import { armDeadlinePoll, createAutoSubmitController } from "./deadline.js";
 import { resumeChainFromLog } from "./chain.js";
-import { getProcessList, getConnections, extractConnectionIP } from "./platform.js";
+import { fetchInitMetadata, ServerError } from "./api.js";
+import { ServerTimesSchema } from "./schemas.js";
+import { detectInstalledHooks } from "./ai-tracking.js";
+import { setupAiTracking } from "../commands/init.js";
+import { writeShadowChainCursor, readShadowChainCursor, writeShadowTrackerFile, readShadowConfigById, findShadowConfigForDir, deleteShadowForAssessment, writeRepairFile, removeRepairFile, } from "./shadow.js";
+import { getProcessList, getConnections, extractConnection, resolvePidNames } from "./platform.js";
+import { classifyClaudeProcesses, refineClaudeTool } from "./detection.js";
 // Surface any uncaught throw during startup, before user code reaches the
 // uncaughtException handler installed later. Without this, an early sync
 // failure (createWriteStream EPERM under Windows Defender, import error,
@@ -47,12 +54,17 @@ process.stderr.write(`[watcher] node ${process.version}, platform=${process.plat
 // Touch the nonce file on startup so tracker.ts can distinguish "our watcher
 // is alive" from "a recycled PID happens to match an old tracker.pid".
 // Heartbeat updates the mtime; tracker.ts compares against NONCE_MAX_AGE_MS.
+// Set once the config loads (below); lets the nonce/pid liveness signals be
+// mirrored outside the repo so doctor can find a live watcher after a wipe.
+let shadowAssessmentId = null;
 function touchNonce() {
     if (!noncePath)
         return;
     try {
         const now = new Date();
         fs.writeFileSync(noncePath, String(now.getTime()));
+        if (shadowAssessmentId)
+            writeShadowTrackerFile(shadowAssessmentId, "tracker.nonce", String(now.getTime()));
     }
     catch { /* non-critical */ }
 }
@@ -230,6 +242,16 @@ if (litmusConfig && litmusConfig.token && litmusConfig.backendUrl) {
     uploadConfig = { token: litmusConfig.token, backendUrl: litmusConfig.backendUrl };
     process.stderr.write("[watcher] upload enabled\n");
 }
+// ENG-1490: assigned at the bottom of this file where the deadline poll is
+// armed; referenced earlier by syncServerTimes (upload responses can arrive
+// before the arm block runs — the optional chain covers that window).
+let autoSubmitController = null;
+// ENG-1453: mirror liveness state outside the repo. The pid is written once
+// (it never changes); the nonce mirror rides every touchNonce from here on.
+if (litmusConfig?.assessmentId) {
+    shadowAssessmentId = litmusConfig.assessmentId;
+    writeShadowTrackerFile(shadowAssessmentId, "tracker.pid", String(process.pid));
+}
 /**
  * Upload buffered events to server.
  * Returns a Promise that resolves when the HTTP request completes (used by shutdown).
@@ -285,15 +307,41 @@ function uploadEvents() {
                         const errorCode = body?.detail?.error;
                         if (errorCode === "Session over") {
                             process.stderr.write("[watcher] server signaled session over; shutting down\n");
+                            autoSubmitController?.markDone();
+                            // ENG-1453: the assessment is over — the mirrored credentials
+                            // and any repair prompt go with it. This is the cleanup path
+                            // for candidates who never run another CLI command (abandoned
+                            // or auto-submitted sessions).
+                            if (litmusConfig)
+                                deleteShadowForAssessment(litmusConfig.assessmentId);
+                            removeRepairFile(projectDir);
                             shutdown();
                         }
                     }
                     catch { /* not JSON; nothing to act on */ }
                 }
                 else {
+                    // ENG-1453: record the chain position the server just acknowledged,
+                    // outside the repo. A replacement watcher whose activity.jsonl was
+                    // wiped resumes from here instead of forking a second genesis chain.
+                    if (litmusConfig) {
+                        let ackSeq = -1;
+                        let ackHash = "";
+                        for (const e of events) {
+                            if (typeof e._seq === "number" && e._seq > ackSeq && typeof e._hash === "string") {
+                                ackSeq = e._seq;
+                                ackHash = e._hash;
+                            }
+                        }
+                        if (ackSeq >= 0 && ackHash)
+                            writeShadowChainCursor(litmusConfig.assessmentId, ackSeq, ackHash);
+                    }
                     // Parse response for server signals (e.g., pending questions)
                     try {
                         const body = JSON.parse(responseData);
+                        // ENG-1489: authoritative times ride every activity response.
+                        if (body.times)
+                            syncServerTimes(body.times, "heartbeat");
                         if (body.pendingQuestions && body.pendingQuestions > 0) {
                             const nudgePath = path.join(projectDir, ".litmus", "QUESTION.md");
                             const nudge = `# You have ${body.pendingQuestions} unanswered question${body.pendingQuestions > 1 ? "s" : ""}\n\nPlease check your Litmus browser tab to view and answer.\n`;
@@ -387,6 +435,17 @@ function startChain() {
     const chainStart = resumeChainFromLog(activityLogPath);
     prevHash = chainStart.prevHash;
     nextSeq = chainStart.nextSeq;
+    // ENG-1453: a genesis resume with no local log usually means the repo's
+    // .litmus was wiped, not that this is a fresh assessment. Continue from
+    // the last server-acknowledged position instead of forking the chain.
+    if (nextSeq === 0 && litmusConfig) {
+        const cursor = readShadowChainCursor(litmusConfig.assessmentId);
+        if (cursor) {
+            prevHash = cursor.hash;
+            nextSeq = cursor.seq + 1;
+            process.stderr.write(`[watcher] chain resumed from shadow cursor at seq ${cursor.seq}\n`);
+        }
+    }
     const queued = preChainBuffer;
     preChainBuffer = null;
     for (const event of queued)
@@ -565,23 +624,240 @@ const watchedConfigPath = path.join(projectDir, ".litmus", "config.json");
 // without one (tests, manual spawns) never saw a transition and has no
 // upload credentials to report it anyway.
 let configWasPresent = fs.existsSync(watchedConfigPath);
+/** present, or why not. Null = transient fs error, proves nothing. */
+function probeConfig() {
+    try {
+        if (!fs.existsSync(watchedConfigPath))
+            return { present: false, reason: "absent" };
+        try {
+            JSON.parse(fs.readFileSync(watchedConfigPath, "utf8"));
+            return { present: true };
+        }
+        catch {
+            return { present: false, reason: "corrupt" };
+        }
+    }
+    catch {
+        return null;
+    }
+}
 function checkConfigPresence() {
-    let present;
+    const probe = probeConfig();
+    if (probe === null)
+        return;
+    if (probe.present !== configWasPresent) {
+        emit(probe.present
+            ? { ts: new Date().toISOString(), type: "config_restored" }
+            : { ts: new Date().toISOString(), type: "config_missing", detail: probe.reason });
+        process.stderr.write(`[watcher] ${probe.present ? "config restored" : `CONFIG ${probe.reason.toUpperCase()}`}: ${watchedConfigPath}\n`);
+        if (probe.present)
+            removeRepairFile(projectDir);
+    }
+    configWasPresent = probe.present;
+    // ENG-1453 self-heal: don't just report the outage — end it. Retried every
+    // heartbeat until something works, so a transient offline stretch only
+    // delays the repair.
+    if (!probe.present)
+        void selfHealConfig(probe.reason);
+}
+// ── Config self-heal (ENG-1453) ──────────────────────────────────
+// The watcher outlives the file: it kept the full config in memory from
+// spawn, so a deleted/corrupted config.json is restorable with zero
+// candidate action. Order of preference:
+//   1. Fresh server fetch — times re-validated, can never be stale.
+//   2. The ~/.litmus shadow mirror — offline continuity, same validation.
+//   3. This process's own in-memory config — valid at spawn, same
+//      validation; also re-mirrors the shadow, so a destroyed shadow
+//      self-repairs too.
+//   4. Everything failed (in practice: .litmus unwritable): write
+//      LITMUS-REPAIR.md into the project root pointing at the assessment
+//      page's "Something not working?" panel — NEVER the token itself; a
+//      project-root file can be committed, pushed, or read into an agent's
+//      context. Rewritten every heartbeat, removed the moment the config
+//      is back.
+// Every restore is loud: a `config_restored` event with its source, never a
+// silent write. A corrupt file is moved aside first, never destroyed.
+let healInFlight = false;
+async function selfHealConfig(reason) {
+    if (healInFlight)
+        return;
+    healInFlight = true;
     try {
-        present = fs.existsSync(watchedConfigPath);
+        const base = litmusConfig;
+        if (reason === "corrupt") {
+            try {
+                fs.renameSync(watchedConfigPath, `${watchedConfigPath}.corrupt-${Date.now()}`);
+            }
+            catch { /* already gone */ }
+        }
+        let restored = null;
+        let restoredFrom = null;
+        if (base) {
+            try {
+                const meta = await fetchInitMetadata(base.apiBase, base.token);
+                const candidate = {
+                    ...base,
+                    assessmentId: meta.assessmentId,
+                    assessmentName: meta.assessmentName,
+                    candidateEmail: meta.candidateEmail,
+                    candidateName: meta.candidateName,
+                    startedAt: meta.startedAt,
+                    deadline: meta.deadline,
+                    timeLimit: meta.timeLimit,
+                    walkthroughWindowMinutes: meta.walkthroughWindowMinutes,
+                    backendUrl: meta.backendUrl ?? base.backendUrl,
+                    cliVersion: CLI_VERSION,
+                };
+                if (validateRebuiltTimes(candidate, Date.now()) === null) {
+                    restored = candidate;
+                    restoredFrom = "server";
+                }
+            }
+            catch { /* offline or rejected — try the shadow */ }
+        }
+        if (!restored) {
+            const shadow = (base ? readShadowConfigById(base.assessmentId) : null) ?? findShadowConfigForDir(projectDir);
+            if (shadow && validateRebuiltTimes(shadow, Date.now()) === null) {
+                const { projectDir: _dir, mirroredAt: _at, ...config } = shadow;
+                restored = config;
+                restoredFrom = "shadow";
+            }
+        }
+        if (!restored && base && validateRebuiltTimes(base, Date.now()) === null) {
+            restored = base;
+            restoredFrom = "memory";
+        }
+        let healed = false;
+        if (restored && restoredFrom) {
+            try {
+                await writeConfig(projectDir, restored); // re-mirrors the shadow too
+                litmusConfig = restored;
+                if (restored.token && restored.backendUrl) {
+                    uploadConfig = { token: restored.token, backendUrl: restored.backendUrl };
+                }
+                shadowAssessmentId = restored.assessmentId;
+                configWasPresent = true; // the transition check must not double-report
+                removeRepairFile(projectDir);
+                // A restored config can carry moved times (the server fetch above is
+                // exactly how an extension reaches a session whose config was wiped).
+                // The poll getter picks the new deadline up by itself, but the
+                // controller's retry budget must reset too — otherwise attempts
+                // exhausted against the OLD cutoff leave the NEW one unarmed.
+                autoSubmitController?.noteDeadlineChanged(getEffectiveDeadline(restored));
+                emit({ ts: new Date().toISOString(), type: "config_restored", restoredFrom });
+                process.stderr.write(`[watcher] config self-healed from ${restoredFrom}\n`);
+                healed = true;
+            }
+            catch { /* .litmus unwritable — candidate guidance below */ }
+        }
+        if (!healed && base)
+            writeRepairFile(projectDir);
+    }
+    finally {
+        healInFlight = false;
+    }
+}
+// ── Server time sync (ENG-1489) ──────────────────────────────────
+// The config is written once at init, but the server's times can move
+// mid-session (extension, per-candidate override, support correction). Every
+// /cli/activity response now carries the authoritative times; fold them in
+// here. The deadline poll reads the effective deadline through a getter, so
+// updating litmusConfig IS the re-arm — no timer surgery.
+function syncServerTimes(raw, source) {
+    if (!litmusConfig)
+        return;
+    const parsed = ServerTimesSchema.safeParse(raw);
+    if (!parsed.success)
+        return;
+    const result = computeTimeSync(litmusConfig, parsed.data, Date.now());
+    if (result === null)
+        return;
+    if (result.kind === "refused") {
+        process.stderr.write(`[watcher] server time sync refused: ${result.reason}\n`);
+        return;
+    }
+    const previousDeadlineMs = getEffectiveDeadline(litmusConfig);
+    litmusConfig = result.next;
+    const newDeadlineMs = getEffectiveDeadline(result.next);
+    // Persist so a restart (and doctor, and the shadow) see the synced times.
+    // Failure is non-fatal: the in-memory config and the poll are already
+    // updated, and the config self-heal machinery owns bigger file problems.
+    void writeConfig(projectDir, result.next).catch(() => {
+        process.stderr.write("[watcher] synced times could not be written to config.json (in-memory values still apply)\n");
+    });
+    const iso = (ms) => (ms === null ? null : new Date(ms).toISOString());
+    emit({
+        ts: new Date().toISOString(),
+        type: "deadline_synced",
+        previousDeadline: iso(previousDeadlineMs),
+        newDeadline: iso(newDeadlineMs),
+        timeLimit: result.next.timeLimit ?? null,
+        source,
+    });
+    process.stderr.write(`[watcher] times synced from server (${source}): effective deadline ${iso(previousDeadlineMs) ?? "none"} -> ${iso(newDeadlineMs) ?? "none"}\n`);
+    autoSubmitController?.noteDeadlineChanged(newDeadlineMs);
+}
+// ── Hook self-heal (ENG-1453) ────────────────────────────────────
+// The capture hooks are files too (user-scope configs, the repo-scope Copilot
+// hook, the logger, the registry entry) and any of them can be deleted or
+// clobbered mid-session. Verify every leg each heartbeat and reinstall
+// through the same idempotent setup init uses. Transition events only —
+// `hooks_missing` when a healthy setup breaks, `hooks_restored` when it is
+// whole again — so a long-broken leg doesn't spam.
+let lastHooksHealthy = true; // init installs the hooks before spawning us
+function missingHookLegs() {
+    const hooks = detectInstalledHooks(projectDir);
+    const legs = [];
+    if (hooks.claude === null)
+        legs.push("claude");
+    if (!hooks.codex)
+        legs.push("codex");
+    if (!hooks.cursor)
+        legs.push("cursor");
+    if (!hooks.copilot)
+        legs.push("copilot");
+    if (!hooks.loggerPresent)
+        legs.push("logger");
+    if (!hooks.registered)
+        legs.push("registry");
+    return legs;
+}
+function checkHooksPresence() {
+    // Hooks capture nothing without credentials — let the config heal first.
+    if (!configWasPresent)
+        return;
+    let legs;
+    try {
+        legs = missingHookLegs();
     }
     catch {
-        return; // transient fs error proves nothing either way
+        return; // transient fs error proves nothing
     }
-    if (present !== configWasPresent) {
-        emit({ ts: new Date().toISOString(), type: present ? "config_restored" : "config_missing" });
-        process.stderr.write(`[watcher] ${present ? "config restored" : "CONFIG MISSING"}: ${watchedConfigPath}\n`);
+    if (legs.length === 0) {
+        if (!lastHooksHealthy)
+            emit({ ts: new Date().toISOString(), type: "hooks_restored" });
+        lastHooksHealthy = true;
+        return;
+    }
+    if (lastHooksHealthy) {
+        emit({ ts: new Date().toISOString(), type: "hooks_missing", legs });
+        process.stderr.write(`[watcher] HOOKS MISSING: ${legs.join(", ")}\n`);
+    }
+    lastHooksHealthy = false;
+    try {
+        setupAiTracking(projectDir);
+        if (missingHookLegs().length === 0) {
+            emit({ ts: new Date().toISOString(), type: "hooks_restored", restoredFrom: "reinstall" });
+            process.stderr.write("[watcher] hooks self-healed\n");
+            lastHooksHealthy = true;
+        }
     }
-    configWasPresent = present;
+    catch { /* leave broken; retried next heartbeat, reported already */ }
 }
 // ── Heartbeats ───────────────────────────────────────────────────
 function emitHeartbeat() {
     checkConfigPresence(); // before the heartbeat so both ride the same upload
+    checkHooksPresence();
     emit({ ts: new Date().toISOString(), type: "heartbeat" });
     uploadEvents(); // Upload buffered events to server
     touchNonce(); // Keep our liveness signal fresh for the CLI's PID-reuse check
@@ -669,7 +945,6 @@ const EDITOR_PATTERNS = {
     zed: /\bzed\b/,
 };
 const AI_TOOL_PATTERNS = {
-    claude: /\bclaude\b/,
     aider: /\baider\b/,
     codeium: /\bcodeium\b/,
     codex: /\bcodex\b/,
@@ -694,12 +969,18 @@ function detectEnvironment() {
         const aiTools = Object.entries(AI_TOOL_PATTERNS)
             .filter(([, re]) => re.test(ps))
             .map(([name]) => name);
+        aiTools.push(...classifyClaudeProcesses(ps));
         // Cursor is both an editor and an AI tool
         if (editors.includes("cursor") && !aiTools.includes("cursor")) {
             aiTools.push("cursor");
         }
         if (editors.length > 0 || aiTools.length > 0) {
-            const event = { ts: new Date().toISOString(), type: "env_detected" };
+            const event = {
+                ts: new Date().toISOString(),
+                type: "env_detected",
+                platform: process.platform,
+                osRelease: os.release(),
+            };
             if (editors.length)
                 event.editors = editors;
             if (aiTools.length)
@@ -795,6 +1076,17 @@ function refreshDnsCache() {
 }
 refreshDnsCache(); // Resolve on startup
 let lastNetworkTools = ""; // Dedup: JSON stringified tool set from previous check
+let lastNetworkEmitMs = 0;
+// Re-emit an UNCHANGED tool set after this long. The old dedup emitted only on
+// change, so a chat tab left open for a whole session produced exactly one
+// event — and the grader's recurrence gate (>=2 events before a network-derived
+// tool may be shown) then read "continuously present" as "seen once, could be a
+// shared-IP coincidence" and suppressed it. Re-emitting at a slow cadence keeps
+// the event stream meaning "still present on this scan" without flooding the
+// activity log: with 5-minute scans, any session spanning ~20+ minutes yields
+// the two events the gate needs, while a tab that appears on a single scan
+// still (correctly) does not.
+const NETWORK_REEMIT_MS = 15 * 60 * 1000;
 function detectNetworkAI() {
     if (Date.now() - lastDnsRefresh > DNS_REFRESH_MS)
         refreshDnsCache();
@@ -803,30 +1095,38 @@ function detectNetworkAI() {
     getConnections((err, stdout) => {
         if (err || !stdout)
             return;
-        parseNetworkOutput(stdout);
+        // Windows netstat rows carry only a PID; resolve names first so the
+        // owner-based classification below works there too.
+        resolvePidNames((pidNames) => parseNetworkOutput(stdout, pidNames));
     });
 }
-function parseNetworkOutput(output) {
+function parseNetworkOutput(output, pidNames) {
     const detected = new Map(); // tool -> Set<host>
+    const owners = new Set();
     for (const line of output.split("\n")) {
-        const ipMatch = extractConnectionIP(line);
-        if (!ipMatch)
+        const conn = extractConnection(line);
+        if (!conn)
             continue;
-        const ip = ipMatch[1];
-        const entry = ipToTool.get(ip);
+        const entry = ipToTool.get(conn.ip);
         if (entry) {
-            if (!detected.has(entry.tool))
-                detected.set(entry.tool, new Set());
-            detected.get(entry.tool).add(entry.host);
+            const owner = conn.owner || (conn.pid && pidNames?.get(conn.pid)) || "";
+            const tool = refineClaudeTool(entry.tool, owner);
+            if (owner)
+                owners.add(owner);
+            if (!detected.has(tool))
+                detected.set(tool, new Set());
+            detected.get(tool).add(entry.host);
         }
     }
     if (detected.size === 0)
         return;
-    // Dedup: don't re-emit if same tools detected as last check
+    // Dedup: don't re-emit an unchanged tool set — except after
+    // NETWORK_REEMIT_MS, so sustained presence stays visible in the stream.
     const toolKey = JSON.stringify([...detected.keys()].sort());
-    if (toolKey === lastNetworkTools)
+    if (toolKey === lastNetworkTools && Date.now() - lastNetworkEmitMs < NETWORK_REEMIT_MS)
         return;
     lastNetworkTools = toolKey;
+    lastNetworkEmitMs = Date.now();
     const tools = [];
     const hosts = [];
     for (const [tool, hostSet] of detected) {
@@ -834,12 +1134,15 @@ function parseNetworkOutput(output) {
         for (const h of hostSet)
             hosts.push(h);
     }
-    emit({
+    const event = {
         ts: new Date().toISOString(),
         type: "network_ai_detected",
         tools,
         hosts,
-    });
+    };
+    if (owners.size)
+        event.owners = [...owners].sort();
+    emit(event);
 }
 detectNetworkAI(); // Run immediately
 setInterval(detectNetworkAI, 5 * 60 * 1000); // Every 5 minutes
@@ -877,6 +1180,7 @@ const SNAPSHOT_IGNORE = [
     /package-lock\.json$/,
     /yarn\.lock$/,
     /pnpm-lock\.yaml$/,
+    /bun\.lockb?$/,
     // Likely-secret files. Defensive: dotfile rule catches `.env` and `.envrc`,
     // but a candidate's `secrets.json`, `credentials.yaml`, RSA keys, or PEM
     // certificates would otherwise stream to /cli/snapshot. The snapshot is
@@ -1045,70 +1349,117 @@ setTimeout(() => {
     setInterval(uploadSnapshot, SNAPSHOT_INTERVAL_MS);
 }, 60 * 1000);
 // ── Auto-submit at deadline ──────────────────────────────────────
-// The deadline fires via a wall-clock POLL, not a single absolute setTimeout.
-// setTimeout(fn, msUntilDeadline) is frozen while the machine is asleep /
-// suspended (macOS lid-close / App Nap), so it fires late — or, if the deadline
-// elapses entirely during sleep, only once enough *active* time has accrued.
-// Polling Date.now() reconciles on wake: the interval also pauses while the
-// process is suspended, but the first tick after resume sees that wall-clock
-// has passed the deadline and submits within one poll interval. Polling also
-// removes the old ~24.8-day setTimeout ceiling.
+// Wall-clock POLL (see deadline.ts for the sleep/wake rationale). The poll
+// reads the effective deadline through a getter, so ENG-1489 server syncs
+// re-arm it by simply updating litmusConfig. The fire decision itself is
+// server-verified (ENG-1490): a stale-early local deadline must never turn
+// into an accepted early submission — in the 96h incident the only reason a
+// candidate wasn't auto-submitted ~88h early is that the submit happened to
+// fail. Failures retry with bounded backoff; the server-side cron remains
+// the final backstop.
 if (cliBinPath && litmusConfig) {
-    const effectiveDeadline = getEffectiveDeadline(litmusConfig);
-    if (effectiveDeadline !== null && Number.isFinite(effectiveDeadline)) {
-        let deadlineAutoSubmitFired = false;
-        const fireDeadlineAutoSubmit = () => {
-            if (deadlineAutoSubmitFired)
-                return;
-            deadlineAutoSubmitFired = true;
-            process.stderr.write("[watcher] deadline reached, auto-submitting\n");
-            execFile(process.execPath, [cliBinPath, "submit", "--yes"], { cwd: projectDir, timeout: 5 * 60000 }, (err, stdout, stderr) => {
-                if (!err) {
-                    process.stderr.write("[watcher] auto-submit succeeded\n");
-                    // The watcher's spawn() in tracker.ts uses stdio:["ignore", "ignore",
-                    // errFd] — anything we write to stderr goes to .litmus/tracker.log,
-                    // which the candidate isn't looking at. And `stdout` here (the CLI's
-                    // "Code submitted — one step left. Open your dashboard ..." handoff)
-                    // would otherwise be discarded. Drop a sentinel file at the project
-                    // root with the dashboard URL extracted from the CLI's output so the
-                    // candidate's editor / `ls` / file watcher surfaces the next step
-                    // even if their terminal session is gone.
-                    const urlMatch = stdout && stdout.match(/https?:\/\/[^\s]+\/candidate\/[A-Za-z0-9_-]+/);
-                    const handoffUrl = urlMatch ? urlMatch[0] : null;
-                    if (handoffUrl) {
-                        process.stderr.write(`[watcher] dashboard URL: ${handoffUrl}\n`);
-                        // Mode-neutral wording: the assessment may be VIDEO/LIVE_AGENT
-                        // (record walkthrough) or WRITTEN (complete a written
-                        // reflection) — the watcher only has the URL, not the mode, so
-                        // we say "finish your assessment" rather than over-specifying.
-                        const note = "Your code was auto-submitted at the time limit.\n\n" +
-                            "Open this URL in your browser to finish your assessment:\n\n" +
-                            `  ${handoffUrl}\n\n` +
-                            `You have about ${litmusConfig.walkthroughWindowMinutes ?? 10} minutes. If you miss it, your submission will be graded on code alone.\n`;
-                        try {
-                            fs.writeFileSync(path.join(projectDir, "NEXT-STEP.txt"), note, "utf8");
-                        }
-                        catch { /* non-critical */ }
+    const runAutoSubmit = () => new Promise((resolveRun) => {
+        process.stderr.write("[watcher] deadline reached (server-verified), auto-submitting\n");
+        execFile(process.execPath, [cliBinPath, "submit", "--yes"], { cwd: projectDir, timeout: 5 * 60000 }, (err, stdout, stderr) => {
+            if (!err) {
+                process.stderr.write("[watcher] auto-submit succeeded\n");
+                // The watcher's spawn() in tracker.ts uses stdio:["ignore", "ignore",
+                // errFd] — anything we write to stderr goes to the tracker log,
+                // which the candidate isn't looking at. And `stdout` here (the CLI's
+                // "Code submitted — one step left. Open your dashboard ..." handoff)
+                // would otherwise be discarded. Drop a sentinel file at the project
+                // root with the dashboard URL extracted from the CLI's output so the
+                // candidate's editor / `ls` / file watcher surfaces the next step
+                // even if their terminal session is gone.
+                const urlMatch = stdout && stdout.match(/https?:\/\/[^\s]+\/candidate\/[A-Za-z0-9_-]+/);
+                const handoffUrl = urlMatch ? urlMatch[0] : null;
+                if (handoffUrl) {
+                    process.stderr.write(`[watcher] dashboard URL: ${handoffUrl}\n`);
+                    // Mode-neutral wording: the assessment may be VIDEO/LIVE_AGENT
+                    // (record walkthrough) or WRITTEN (complete a written
+                    // reflection) — the watcher only has the URL, not the mode, so
+                    // we say "finish your assessment" rather than over-specifying.
+                    const note = "Your code was auto-submitted at the time limit.\n\n" +
+                        "Open this URL in your browser to finish your assessment:\n\n" +
+                        `  ${handoffUrl}\n\n` +
+                        `You have about ${litmusConfig?.walkthroughWindowMinutes ?? 10} minutes. If you miss it, your submission will be graded on code alone.\n`;
+                    try {
+                        fs.writeFileSync(path.join(projectDir, "NEXT-STEP.txt"), note, "utf8");
                     }
-                    emit({ ts: new Date().toISOString(), type: "auto_submit" });
+                    catch { /* non-critical */ }
                 }
-                else {
-                    process.stderr.write(`[watcher] auto-submit failed: ${stderr || err.message}\n`);
-                    emit({ ts: new Date().toISOString(), type: "auto_submit_failed", error: (stderr || err.message).slice(0, 500) });
-                }
-            });
-        };
-        armDeadlineAutoSubmit({
-            deadline: effectiveDeadline,
-            pollMs: 30 * 1000,
-            onFire: fireDeadlineAutoSubmit,
-            onArmed: () => process.stderr.write(`[watcher] deadline poll armed for ${new Date(effectiveDeadline).toISOString()} (${Math.round((effectiveDeadline - Date.now()) / 1000)}s)\n`),
-            // Watcher started after the deadline already elapsed (e.g. a restart
-            // post-deadline). The server-side deadline path owns that case; don't
-            // re-submit from here.
-            onAlreadyPassed: () => process.stderr.write("[watcher] deadline already passed at startup, skipping auto-submit\n"),
+                resolveRun({ ok: true });
+            }
+            else {
+                resolveRun({ ok: false, error: (stderr || err.message).slice(0, 500) });
+            }
         });
-    }
+    });
+    // Ask the server for the authoritative times and fold them in. Marking a
+    // pending candidate in_progress is the route's documented side effect and a
+    // no-op mid-session.
+    const verifyTimes = async () => {
+        const cfg = litmusConfig;
+        if (!cfg)
+            return { status: "rejected" };
+        try {
+            const meta = await fetchInitMetadata(cfg.apiBase, cfg.token);
+            syncServerTimes({ startedAt: meta.startedAt, deadline: meta.deadline, timeLimit: meta.timeLimit }, "fire_check");
+            return {
+                status: "ok",
+                effectiveDeadline: litmusConfig ? getEffectiveDeadline(litmusConfig) : null,
+            };
+        }
+        catch (err) {
+            const status = err instanceof ServerError ? err.statusCode : undefined;
+            if (typeof status === "number" && status >= 400 && status < 500)
+                return { status: "rejected" };
+            return { status: "unavailable" };
+        }
+    };
+    autoSubmitController = createAutoSubmitController({
+        verifyTimes,
+        runSubmit: runAutoSubmit,
+        onOutcome: (outcome) => {
+            const ts = new Date().toISOString();
+            switch (outcome.kind) {
+                case "submitted":
+                    emit({ ts, type: "auto_submit", attempt: outcome.attempt });
+                    break;
+                case "failed": {
+                    const final = (outcome.attempt ?? 0) >= 3;
+                    process.stderr.write(`[watcher] auto-submit failed (attempt ${outcome.attempt}${final ? ", final" : ""}): ${outcome.detail}\n`);
+                    emit({ ts, type: "auto_submit_failed", error: outcome.detail ?? "unknown", attempt: outcome.attempt, final });
+                    break;
+                }
+                case "averted":
+                    process.stderr.write("[watcher] auto-submit averted: server says the deadline has not passed; poll re-armed with server times\n");
+                    emit({
+                        ts,
+                        type: "auto_submit_averted",
+                        serverDeadline: litmusConfig
+                            ? (() => { const d = getEffectiveDeadline(litmusConfig); return d === null ? null : new Date(d).toISOString(); })()
+                            : null,
+                    });
+                    break;
+                case "deferred":
+                    process.stderr.write(`[watcher] auto-submit deferred: ${outcome.detail}\n`);
+                    break;
+                case "exhausted":
+                    process.stderr.write("[watcher] auto-submit retry budget exhausted; server-side deadline handling owns this session\n");
+                    break;
+            }
+        },
+    });
+    armDeadlinePoll({
+        getDeadline: () => (litmusConfig ? getEffectiveDeadline(litmusConfig) : null),
+        pollMs: 30 * 1000,
+        onDue: () => { void autoSubmitController?.handleDue(); },
+        onWake: (gapMs) => emit({ ts: new Date().toISOString(), type: "wake_gap", gapMs }),
+        onArmed: (ms) => process.stderr.write(ms === null
+            ? "[watcher] deadline poll armed (no deadline configured; server sync may set one)\n"
+            : `[watcher] deadline poll armed for ${new Date(Date.now() + ms).toISOString()} (${Math.round(ms / 1000)}s)\n`),
+    });
 }
 // ── Graceful shutdown ────────────────────────────────────────────
 let shuttingDown = false;