@oss-autopilot/core 3.13.4 → 3.14.1

package/dist/commands/dashboard-server.js

@@ -4,21 +4,30 @@
  * for live data fetching and state mutations (PR state transitions, issue dismiss).
  *
  * Uses Node's built-in http module — no Express/Fastify.
+ *
+ * Collaborators (#1457): the gist-sync lifecycle lives in
+ * GistSyncCoordinator (dashboard-gist-sync.ts) and the cached-response
+ * state in DashboardCache (dashboard-cache.ts); this file is wiring,
+ * routing and the HTTP handlers.
  */
 import * as http from 'node:http';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { getStateManager, getGitHubToken, getCLIVersion, applyStatusOverrides, classifyAttentionBucket, maybeCheckpoint, ensureGistPersistence, } from '../core/index.js';
-import { errorMessage, ValidationError, ConcurrencyError, ConfigurationError, GistConcurrencyError, } from '../core/errors.js';
+import { getGitHubToken, getCLIVersion, maybeCheckpoint } from '../core/index.js';
+import { errorMessage, ValidationError, ConcurrencyError, GistConcurrencyError } from '../core/errors.js';
 import { warn } from '../core/logger.js';
 import { validateUrl, validateGitHubUrl, PR_URL_PATTERN, ISSUE_URL_PATTERN } from './validation.js';
-import { fetchDashboardData, computePRsByRepo, computeTopRepos, getMonthlyData, buildDashboardStats, reconcileShelvePartition, storedToMergedPRs, storedToClosedPRs, } from './dashboard-data.js';
-import { openInBrowser, detectIssueList } from './startup.js';
-import { parseIssueList } from './parse-list.js';
+import { fetchDashboardData } from './dashboard-data.js';
+import { openInBrowser } from './startup.js';
 import { writeDashboardServerInfo, removeDashboardServerInfo } from './dashboard-process.js';
 import { RateLimiter } from './rate-limiter.js';
-import { isBelowMinStars, } from '../core/types.js';
+import { GistSyncCoordinator } from './dashboard-gist-sync.js';
+import { DashboardCache, getIssueListMtimeMs } from './dashboard-cache.js';
+// Re-export the payload builder for backward compatibility — it moved to
+// dashboard-cache.ts with the cache extraction (#1457) but is unit-tested
+// (and consumed) under this module's name.
+export { buildDashboardJson } from './dashboard-cache.js';
 // Re-export process management functions for backward compatibility
 export { getDashboardPidPath, writeDashboardServerInfo, readDashboardServerInfo, removeDashboardServerInfo, isDashboardServerRunning, findRunningDashboardServer, } from './dashboard-process.js';
 // ── Constants ────────────────────────────────────────────────────────────────
@@ -36,120 +45,6 @@ const MIME_TYPES = {
     '.ico': 'image/x-icon',
 };
 // ── Helpers ────────────────────────────────────────────────────────────────────
-/**
- * Read and parse the vetted issue list file (non-fatal on failure).
- */
-function readVettedIssues() {
-    try {
-        const info = detectIssueList();
-        if (!info)
-            return null;
-        const content = fs.readFileSync(info.path, 'utf8');
-        return parseIssueList(content);
-    }
-    catch (error) {
-        warn(MODULE, `Failed to read vetted issue list: ${errorMessage(error)}`);
-        return null;
-    }
-}
-/**
- * Get the mtime of the vetted issue list file in ms, or null if unknown.
- * Used to detect external edits and invalidate the cached dashboard payload.
- */
-function getIssueListMtimeMs() {
-    try {
-        const info = detectIssueList();
-        if (!info)
-            return null;
-        return fs.statSync(info.path).mtimeMs;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Build the JSON payload that the SPA expects from GET /api/data.
- *
- * Exported for unit testing of response-shape concerns that the full
- * handler harness can't reach (it bakes a stale cachedDigest at server
- * start-up, so tests that need a specific digest should call this directly).
- */
-export function buildDashboardJson(digest, state, commentedIssues, allMergedPRs, allClosedPRs, partialFailures) {
-    // Apply status overrides ONCE, before the shelve partition is derived, so
-    // the dashboard partitions on the same post-override status the CLI
-    // partitions on (#1416). This also covers overrides set AFTER the digest
-    // was cached (a dashboard move stores an override; the action path rebuilds
-    // from the cached digest). Work on a copy — the caller's cached digest must
-    // not accumulate per-request derivations.
-    const overriddenDigest = {
-        ...digest,
-        openPRs: applyStatusOverrides(digest.openPRs || [], state),
-        summary: { ...digest.summary },
-    };
-    // Re-derive the shelve partition from the CURRENT state before reading it.
-    // The POST /api/action path rebuilds with a cached digest whose shelvedPRs
-    // predates the shelve/unshelve, so without this the SPA action appears to do
-    // nothing until the next full /api/refresh.
-    reconcileShelvePartition(overriddenDigest, state);
-    const prsByRepo = computePRsByRepo(overriddenDigest, state);
-    const topRepos = computeTopRepos(prsByRepo);
-    const { monthlyMerged, monthlyOpened, monthlyClosed } = getMonthlyData(state);
-    // Derive from state if not provided (e.g. initial load from cached state)
-    const mergedPRs = allMergedPRs ?? storedToMergedPRs(getStateManager().getMergedPRs());
-    const closedPRs = allClosedPRs ?? storedToClosedPRs(getStateManager().getClosedPRs());
-    // Filter out PRs from repos below the minStars threshold
-    const minStars = state.config.minStars ?? 50;
-    const repoScores = state.repoScores || {};
-    const isAboveMinStars = (pr) => !isBelowMinStars(repoScores[pr.repo]?.stargazersCount, minStars);
-    const filteredMergedPRs = mergedPRs.filter(isAboveMinStars);
-    const filteredClosedPRs = closedPRs.filter(isAboveMinStars);
-    const stats = buildDashboardStats(overriddenDigest, state, filteredMergedPRs.length, filteredClosedPRs.length);
-    const dismissedIssues = state.config.dismissedIssues || {};
-    const issueResponses = commentedIssues.filter((i) => i.status === 'new_response' && !(i.url in dismissedIssues));
-    // Build repo metadata map from repoScores — omit repos without stars or language to avoid empty entries
-    const repoMetadata = {};
-    for (const [repo, score] of Object.entries(repoScores)) {
-        if (score.stargazersCount !== undefined || score.language !== undefined) {
-            repoMetadata[repo] = { stars: score.stargazersCount, language: score.language };
-        }
-    }
-    const vettedIssues = readVettedIssues();
-    if (vettedIssues) {
-        stats.availableIssues = vettedIssues.availableCount;
-    }
-    return {
-        stats,
-        prsByRepo,
-        topRepos: topRepos.map(([repo, data]) => ({ repo, ...data })),
-        monthlyMerged,
-        monthlyOpened,
-        monthlyClosed,
-        // #1352: stamp the unified attention bucket so the SPA renders the same
-        // taxonomy the CLI brief counts (single classifier, no second opinion).
-        // Overrides were already applied when overriddenDigest was built — a
-        // second application here would be a no-op but obscures the single
-        // apply-then-partition ordering (#1416).
-        activePRs: (overriddenDigest.openPRs || []).map((pr) => ({
-            ...pr,
-            attentionBucket: classifyAttentionBucket(pr),
-        })),
-        // Source of truth is digest.shelvedPRs (union of explicitly-shelved URLs
-        // and dormant-non-addressing PRs auto-shelved for display). Returning
-        // only state.config.shelvedPRUrls would under-count and desync from
-        // stats.shelvedPRs, which is already derived from digest.shelvedPRs. (#981)
-        shelvedPRUrls: (overriddenDigest.shelvedPRs || []).map((ref) => ref.url),
-        recentlyMergedPRs: overriddenDigest.recentlyMergedPRs || [],
-        recentlyClosedPRs: overriddenDigest.recentlyClosedPRs || [],
-        autoUnshelvedPRs: overriddenDigest.autoUnshelvedPRs || [],
-        commentedIssues,
-        issueResponses,
-        allMergedPRs: filteredMergedPRs,
-        allClosedPRs: filteredClosedPRs,
-        repoMetadata,
-        vettedIssues,
-        partialFailures: partialFailures && partialFailures.length > 0 ? partialFailures : undefined,
-    };
-}
 /**
  * Read the full request body as a UTF-8 string, with a size limit.
  */
@@ -264,6 +159,14 @@ function sendJson(res, statusCode, data) {
 function sendError(res, statusCode, message) {
     sendJson(res, statusCode, { error: message });
 }
+/**
+ * Collapse CR/LF in a string destined for an HTTP header value — Node's
+ * setHeader throws on embedded newlines, and staleness reasons are built
+ * from arbitrary error messages (#1446 item 2).
+ */
+function sanitizeHeaderValue(value) {
+    return value.replace(/[\r\n]+/g, ' ').trim();
+}
 /**
  * True when an error is an optimistic-concurrency conflict on state.json
  * (local mtime CAS) or the state Gist (ETag CAS). Both carry the
@@ -288,10 +191,12 @@ function sendConflict(res) {
 // ── Server ─────────────────────────────────────────────────────────────────────
 export async function startDashboardServer(options) {
     const { port: requestedPort, assetsDir, token, open } = options;
-    // `let` (#1433): a degraded gist recovery replaces the core singleton, and
-    // this long-lived server must re-resolve its reference or every handler
-    // keeps using the orphaned local manager.
-    let stateManager = getStateManager();
+    // Gist-sync lifecycle state machine (#1457): pending push warnings (#1417),
+    // degraded recovery with throttle/halt (#1433), loss notices (#1443). It
+    // also owns the live StateManager reference — a degraded gist recovery
+    // replaces the core singleton, and this long-lived server must re-resolve
+    // its reference (#1433), so always read it via gistSync.stateManager.
+    const gistSync = new GistSyncCoordinator(token, MODULE);
     const resolvedAssetsDir = path.resolve(assetsDir);
     // ── CSRF token ──────────────────────────────────────────────────────────
     // Fresh per server-start. Exposed to the SPA via X-CSRF-Token on every
@@ -305,158 +210,14 @@ export async function startDashboardServer(options) {
     // Start immediately with state.json data (written by the daily check that
     // precedes this server launch). A background GitHub fetch refreshes the
     // cache after the port is bound, so the startup poller sees us in time.
-    let cachedDigest = stateManager.getState().lastDigest;
-    let cachedCommentedIssues = [];
-    // Persist the last-known partialFailures across rebuild requests (#1035).
-    // Cleared only when a fresh fetchDashboardData returns zero failures;
-    // re-threaded into every buildDashboardJson call so the SPA banner does
-    // not disappear when /api/data rebuilds after a state change or after a
-    // POST /api/action completes.
-    let cachedPartialFailures = undefined;
-    // Gist checkpoint warnings from dashboard mutations (#1417). DELIBERATELY
-    // separate from cachedPartialFailures: fetch failures clear on a successful
-    // PULL, but a gist-sync warning means an un-pushed mutation, and a pull is
-    // exactly the event that can destroy it (refreshFromGist wholesale-replaces
-    // state). These clear only when a checkpoint PUSH succeeds.
-    let pendingGistSyncWarnings = [];
-    // Tracks the last background-refresh failure so /api/data can surface
-    // staleness to the SPA via the X-Dashboard-Stale header (#1205). Cleared
-    // when a refresh succeeds. Without this, token expiry / GitHub outage
-    // produces silent stale data hours old with no client-visible signal.
-    let lastBackgroundRefreshError = null;
-    /** Record a mutation's checkpoint outcome. `null` means the push succeeded
-     * (or local mode) — and a successful push carries the FULL current state,
-     * so any previously pending warning is resolved with it. */
-    function recordGistSyncOutcome(warning) {
-        if (warning === null) {
-            pendingGistSyncWarnings = [];
-            return;
-        }
-        if (!pendingGistSyncWarnings.includes(warning)) {
-            pendingGistSyncWarnings.push(warning);
-        }
-    }
-    /** Merge pending gist-sync warnings into a partialFailures payload for the
-     * SPA banner without coupling their lifecycles. */
-    function withPendingGistWarnings(failures) {
-        const extras = [...pendingGistSyncWarnings, ...recoveryLossNotices];
-        if (gistConfiguredButLocal()) {
-            extras.push(recoveryHaltedReason === null
-                ? GIST_DEGRADED_WARNING
-                : `Gist persistence is configured but recovery FAILED permanently: ${recoveryHaltedReason} — ` +
-                    'fix the Gist setup (check the token gist scope, or run state-show), then restart the dashboard.');
-        }
-        else if (gistBootstrapDegraded()) {
-            extras.push(GIST_STALE_BOOTSTRAP_WARNING);
-        }
-        if (extras.length === 0)
-            return failures;
-        const base = failures ?? [];
-        return [...base, ...extras.filter((w) => !base.includes(w))];
-    }
-    /** Push-before-pull (#1417): an un-pushed mutation would be silently
-     * reverted by the next Gist pull. Retry the checkpoint first so a recovered
-     * network turns the pending warning into a real push before any pull runs.
-     * No-op when nothing is pending. */
-    async function flushPendingGistSync() {
-        if (pendingGistSyncWarnings.length === 0)
-            return;
-        recordGistSyncOutcome(await maybeCheckpoint(stateManager, MODULE));
-    }
-    /** True while the config asks for gist but this process's manager is
-     * local-only (#1433) — the degraded window in which every dashboard
-     * mutation is acknowledged and then clobbered by the next pull. */
-    function gistConfiguredButLocal() {
-        // Defensive: this is an advisory check that runs on EVERY request path
-        // (rebuilds, recovery probes). A getState failure has its own handling
-        // wherever state is actually consumed — the degraded probe must not
-        // become a new crash surface in front of it (#994's stale-serving path).
-        try {
-            return stateManager.getState().config.persistence === 'gist' && !stateManager.isGistMode();
-        }
-        catch (err) {
-            warn(MODULE, `Degraded-gist probe failed (treating as not degraded): ${errorMessage(err)}`);
-            return false;
-        }
-    }
-    /** Gist-backed but the bootstrap itself fell back to the local cache —
-     * reads may be stale even though isGistMode() is true (#1433 review). */
-    function gistBootstrapDegraded() {
-        try {
-            return stateManager.isGistMode() && stateManager.isGistDegraded();
-        }
-        catch {
-            return false;
-        }
-    }
-    const GIST_DEGRADED_WARNING = 'Gist persistence is configured but this dashboard process is running LOCAL-ONLY; ' +
-        'changes made here will NOT sync and may be overwritten by the next successful Gist read. ' +
-        'Recovery is retried automatically.';
-    const GIST_STALE_BOOTSTRAP_WARNING = 'Gist persistence is active but the last Gist read fell back to the local cache; ' +
-        'data shown may be stale until the next successful Gist read.';
-    // Recovery throttling + halt (#1433 review): a PERMANENT failure (token
-    // lacks gist scope, corrupt Gist) must not turn every dashboard poll into
-    // a doomed GitHub round trip for the life of the server, and its root
-    // cause must reach the banner — the detached spawn discards stderr.
-    const RECOVERY_RETRY_INTERVAL_MS = 30_000;
-    let lastRecoveryAttemptAt = 0;
-    let recoveryHaltedReason = null;
-    // Mutations acknowledged while degraded (#1433 review): a successful
-    // recovery bootstraps FROM the existing Gist, which reverts them — the
-    // user must get a retrospective notice, not just the prospective banner
-    // that clears at the exact moment of the loss. Cleared on a successful
-    // full refresh (by then the user has seen the notice across the window).
-    let degradedMutationCount = 0;
-    let recoveryLossNotices = [];
-    /** Re-attempt gist init while degraded (#1433). The serve process used to
-     * bootstrap exactly once at CLI preAction — with its stderr discarded by
-     * the detached spawn — and never retry, so one blip at startup meant
-     * local-only writes for the server's lifetime. Never throws. Transient
-     * failures retry no more often than RECOVERY_RETRY_INTERVAL_MS; permanent
-     * (ConfigurationError-class) failures halt retries and surface the reason
-     * in the banner. */
-    async function maybeRecoverGist() {
-        if (!gistConfiguredButLocal())
-            return;
-        if (recoveryHaltedReason !== null)
-            return;
-        const now = Date.now();
-        if (now - lastRecoveryAttemptAt < RECOVERY_RETRY_INTERVAL_MS)
-            return;
-        const currentToken = token || getGitHubToken();
-        // A token-less probe is free (the auth cache answers instantly) and must
-        // not burn the retry window — stamp only when a real attempt starts.
-        if (!currentToken)
-            return;
-        lastRecoveryAttemptAt = now;
-        try {
-            await ensureGistPersistence(currentToken);
-            // The upgrade replaced the core singleton — re-resolve our reference.
-            stateManager = getStateManager();
-            if (stateManager.isGistMode() && degradedMutationCount > 0) {
-                recoveryLossNotices.push(`Gist persistence recovered, but ${degradedMutationCount} change(s) made while degraded were ` +
-                    'saved locally only and were NOT merged into the Gist — they may have been reverted in this view. ' +
-                    'Re-apply anything missing.');
-                degradedMutationCount = 0;
-            }
-        }
-        catch (err) {
-            // ConfigurationError-class failures are permanent until the user acts
-            // (#1202 semantics) — stop hammering GitHub and say WHY in the banner.
-            if (err instanceof ConfigurationError) {
-                recoveryHaltedReason = errorMessage(err);
-            }
-            warn(MODULE, `Gist recovery attempt failed: ${errorMessage(err)}`);
-        }
-    }
-    if (!cachedDigest) {
+    const initialDigest = gistSync.stateManager.getState().lastDigest;
+    if (!initialDigest) {
         throw new Error('No dashboard data available. Run the daily check first: GITHUB_TOKEN=$(gh auth token) npm start -- daily');
     }
+    const cache = new DashboardCache(initialDigest, (failures) => gistSync.withPendingGistWarnings(failures));
     // ── Build cached JSON response ───────────────────────────────────────────
-    let cachedJsonData;
-    let cachedIssueListMtimeMs = getIssueListMtimeMs();
     try {
-        cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues, undefined, undefined, withPendingGistWarnings(cachedPartialFailures));
+        cache.rebuild(gistSync.stateManager.getState());
     }
     catch (error) {
         throw new Error(`Failed to build dashboard data: ${errorMessage(error)}. State data may be corrupted — try running: daily --json`, { cause: error });
@@ -488,44 +249,34 @@ export async function startDashboardServer(options) {
                 // Expose the CSRF token to the SPA on every data fetch so the client
                 // can attach it on subsequent POSTs. Fresh fetch → fresh token view.
                 res.setHeader('X-CSRF-Token', csrfToken);
-                // Re-read state if modified externally (file mtime for local, Gist API for Gist mode)
-                let stateChanged = false;
-                if (stateManager.isGistMode()) {
-                    await flushPendingGistSync();
-                    stateChanged = await stateManager.refreshFromGist();
-                }
-                else {
-                    stateChanged = stateManager.reloadIfChanged();
-                    await maybeRecoverGist();
-                    // A successful recovery is a state-source change: rebuild so the
-                    // degraded banner clears without waiting for another edit.
-                    if (stateManager.isGistMode())
-                        stateChanged = true;
-                }
+                // Re-read state if modified externally (file mtime for local, Gist
+                // API for Gist mode). Shared with the POST paths via reloadState()
+                // so the recoveryHaltedReason un-halt lives in exactly one place —
+                // this GET path used to hand-duplicate the sequence minus the
+                // un-halt and had already drifted once (#1446 item 5). The #1443
+                // degraded-bootstrap recovery (and its banner-clearing stateChanged
+                // signal) lives inside reloadState too — do NOT add a second
+                // maybeRecoverGist call here or recovery would double-run per poll.
+                const stateChanged = await reloadState();
                 // Also rebuild when the vetted issue list file was edited outside this server (#924)
                 const currentIssueListMtimeMs = getIssueListMtimeMs();
-                const issueListChanged = currentIssueListMtimeMs !== cachedIssueListMtimeMs;
+                const issueListChanged = currentIssueListMtimeMs !== cache.issueListMtimeMs;
                 if (stateChanged || issueListChanged) {
                     try {
-                        cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues, undefined, undefined, withPendingGistWarnings(cachedPartialFailures));
-                        cachedIssueListMtimeMs = currentIssueListMtimeMs;
+                        cache.rebuild(gistSync.stateManager.getState(), undefined, undefined, currentIssueListMtimeMs);
                     }
                     catch (error) {
                         warn(MODULE, `Failed to rebuild dashboard data after state reload: ${errorMessage(error)}`);
-                        // Serve previous cachedJsonData rather than returning 500.
+                        // Serve previous cached payload rather than returning 500.
                         // Signal staleness via response header so clients can detect the degraded mode (#994).
                         res.setHeader('X-Dashboard-Stale', '1');
                     }
                 }
-                // Surface staleness from a failed background refresh too (#1205) so
-                // token expiry / GitHub outage produces a client-visible signal
-                // rather than silent stale data. Only set the header when a failure
-                // is recorded — successful refreshes clear it.
-                if (lastBackgroundRefreshError !== null) {
-                    res.setHeader('X-Dashboard-Stale', '1');
-                    res.setHeader('X-Dashboard-Stale-Reason', `background-refresh-failed: ${lastBackgroundRefreshError}`);
-                }
-                sendJson(res, 200, cachedJsonData);
+                // Gist-divergence + background-refresh staleness (#1446 item 2, #1205)
+                // via the shared helper so this GET and the POST mutators emit the
+                // same headers (#1487). The rebuild-failure flag above is GET-only.
+                applyStalenessHeaders(res);
+                sendJson(res, 200, cache.jsonData);
                 return;
             }
             if (url === '/api/action' && method === 'POST') {
@@ -583,22 +334,83 @@ export async function startDashboardServer(options) {
     });
     server.requestTimeout = REQUEST_TIMEOUT_MS;
     // ── POST /api/action handler ─────────────────────────────────────────────
-    /** Re-read state written by external processes (CLI) before mutating. */
+    /** Re-read state written by external processes (CLI) before mutating.
+     * Returns true when the state source changed (gist pull refreshed, local
+     * file reloaded, or a gist recovery completed) — GET /api/data uses this
+     * to decide whether to rebuild the cached payload (#1446 item 5). */
     async function reloadState() {
-        if (stateManager.isGistMode()) {
-            await flushPendingGistSync();
-            await stateManager.refreshFromGist();
-        }
-        else {
-            if (stateManager.reloadIfChanged()) {
-                // An external config edit may BE the fix for a permanently-halted
-                // recovery (new token scope, repaired gist id) — give it one fresh
-                // attempt cycle (#1433 pass-2).
-                recoveryHaltedReason = null;
+        if (gistSync.stateManager.isGistMode()) {
+            await gistSync.flushPendingGistSync();
+            // Both post-pull steps consume the same refreshFromGist outcome, in
+            // this order: pullFromGist (#1443) settles the LOSS side first —
+            // still-pending push warnings become a loss notice at the instant the
+            // pull replaces state — then adoptNewerPulledDigest harvests the GAIN
+            // side (#1446 item 6) by reading the freshly replaced state, so it
+            // cannot run before the pull. Adoption stays out of pullFromGist
+            // because the background-refresh path also pulls but replaces
+            // cachedDigest unconditionally right after — adoption is a
+            // reloadState-path concern only.
+            const refreshed = await gistSync.pullFromGist();
+            if (refreshed)
+                cache.adoptNewerPulledDigest(gistSync.stateManager.getState().lastDigest);
+            if (gistSync.gistBootstrapDegraded()) {
+                // #1443: a degraded bootstrap keeps isGistMode() true while the
+                // store is disarmed, so refreshFromGist() short-circuits forever
+                // and the local-branch recovery below never sees it. Same
+                // throttle/halt machinery applies inside maybeRecoverGist.
+                await gistSync.maybeRecoverGist();
+                // A successful recovery replaced the singleton with state pulled
+                // from the Gist — report a change so callers rebuild and the
+                // stale-bootstrap banner clears now.
+                if (!gistSync.gistBootstrapDegraded())
+                    return true;
             }
-            // reloadIfChanged may have just pulled a persistence=gist flip made
-            // from a terminal, and a degraded server heals here too (#1433).
-            await maybeRecoverGist();
+            return refreshed;
+        }
+        let changed = gistSync.stateManager.reloadIfChanged();
+        if (changed) {
+            // An external config edit may BE the fix for a permanently-halted
+            // recovery (new token scope, repaired gist id) — give it one fresh
+            // attempt cycle (#1433 pass-2).
+            gistSync.unhaltRecovery();
+        }
+        // reloadIfChanged may have just pulled a persistence=gist flip made
+        // from a terminal, and a degraded server heals here too (#1433).
+        await gistSync.maybeRecoverGist();
+        // A successful recovery is a state-source change: rebuild so the
+        // degraded banner clears without waiting for another edit.
+        if (gistSync.stateManager.isGistMode())
+            changed = true;
+        return changed;
+    }
+    /**
+     * Emit the X-Dashboard-Stale / X-Dashboard-Stale-Reason headers from the
+     * two server-lived staleness sources so EVERY response — GET /api/data and
+     * the POST mutators — reflects the same truth (#1487).
+     *
+     * Before this the setters were GET-only, but the SPA's applyResult clears
+     * its `stale` flag on ANY successfully-applied response. A dashboard whose
+     * gist pulls keep failing while POST /api/refresh and /api/action succeed
+     * would flip back to "healthy" until the next GET (mount or CSRF re-prime).
+     * Carrying the headers on the POST paths keeps the flag honest.
+     *
+     * Reads the same two probes the GET path used inline: the StateManager's
+     * gist-divergence marker (getStateStaleness, #1446 item 2) — set on a
+     * refresh failure / invalid payload / degraded bootstrap and cleared on a
+     * successful pull — and the cache's last background-refresh error (#1205).
+     * When both are set the background-refresh reason wins, matching the prior
+     * GET ordering. The GET path's third, transient source — an inline rebuild
+     * failure (#994) — is specific to that handler and stays inline there.
+     */
+    function applyStalenessHeaders(res) {
+        const staleness = gistSync.stateManager.getStateStaleness();
+        if (staleness !== null) {
+            res.setHeader('X-Dashboard-Stale', '1');
+            res.setHeader('X-Dashboard-Stale-Reason', sanitizeHeaderValue(`state-stale: ${staleness.reason}`));
+        }
+        if (cache.lastBackgroundRefreshError !== null) {
+            res.setHeader('X-Dashboard-Stale', '1');
+            res.setHeader('X-Dashboard-Stale-Reason', sanitizeHeaderValue(`background-refresh-failed: ${cache.lastBackgroundRefreshError}`));
         }
     }
     async function handleAction(req, res) {
@@ -659,11 +471,11 @@ export async function startDashboardServer(options) {
         else {
             // dismiss_issue_response
             applyMutation = async () => {
-                stateManager.dismissIssue(body.url, new Date().toISOString());
+                gistSync.stateManager.dismissIssue(body.url, new Date().toISOString());
                 // Mirror runMove's contract: every mutating surface checkpoints to
                 // Gist and surfaces the warning. Never throws — failures come back
                 // as the warning string.
-                gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+                gistSyncWarning = await maybeCheckpoint(gistSync.stateManager, MODULE);
             };
         }
         // Reload state before mutating to avoid overwriting external CLI changes.
@@ -707,19 +519,21 @@ export async function startDashboardServer(options) {
         // SPA already renders (#1417). Tracked in pendingGistSyncWarnings — NOT
         // cachedPartialFailures — because gist warnings clear on a successful
         // PUSH, while fetch failures clear on a successful pull/refresh.
-        recordGistSyncOutcome(gistSyncWarning);
+        gistSync.recordGistSyncOutcome(gistSyncWarning);
         // Count mutations acknowledged while degraded (#1433): a later recovery
         // bootstraps from the existing Gist and reverts them, and the loss
         // notice needs to know whether there is anything to lose.
-        if (gistConfiguredButLocal())
-            degradedMutationCount++;
+        gistSync.recordMutationWhileDegraded();
         // Rebuild dashboard data from cached digest + updated state. Persist
         // the last-known partialFailures across action rebuilds (#1035) so the
         // SPA banner survives user interactions until the next successful
         // refresh clears it.
-        cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues, undefined, undefined, withPendingGistWarnings(cachedPartialFailures));
-        cachedIssueListMtimeMs = getIssueListMtimeMs();
-        sendJson(res, 200, cachedJsonData);
+        cache.rebuild(gistSync.stateManager.getState());
+        // Carry the same staleness signal a GET would (#1487): a mutation that
+        // succeeds locally while the gist stays unreachable must not let the SPA
+        // clear a previously-stale flag.
+        applyStalenessHeaders(res);
+        sendJson(res, 200, cache.jsonData);
     }
     // ── POST /api/refresh handler ────────────────────────────────────────────
     async function handleRefresh(_req, res) {
@@ -734,18 +548,21 @@ export async function startDashboardServer(options) {
             // refresh's own reloadState may RECOVER and produce a fresh notice,
             // which must survive into the rebuild below, not be wiped 10 lines
             // after its creation (#1433 pass-2).
-            recoveryLossNotices = [];
+            gistSync.clearRecoveryLossNotices();
             await reloadState();
             warn(MODULE, 'Refreshing dashboard data from GitHub...');
             const result = await fetchDashboardData(currentToken);
-            cachedDigest = result.digest;
-            cachedCommentedIssues = result.commentedIssues;
-            // Update the persistent banner signal — clear on a clean refresh,
-            // set when one or more sub-fetches degraded. See #1035.
-            cachedPartialFailures = result.partialFailures.length > 0 ? result.partialFailures : undefined;
-            cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues, result.allMergedPRs, result.allClosedPRs, withPendingGistWarnings(cachedPartialFailures));
-            cachedIssueListMtimeMs = getIssueListMtimeMs();
-            sendJson(res, 200, cachedJsonData);
+            cache.adoptFetchResult(result);
+            cache.rebuild(gistSync.stateManager.getState(), result.allMergedPRs, result.allClosedPRs);
+            // This manual refresh just fetched GitHub successfully, so a prior
+            // background-refresh failure is no longer current (#1487) — clear it as
+            // the background success path does, then emit the staleness headers. A
+            // gist-divergence marker that survived a failed pull inside reloadState
+            // still surfaces via getStateStaleness, so the SPA stays honest even
+            // when the GitHub fetch succeeds but the gist remains unreachable.
+            cache.lastBackgroundRefreshError = null;
+            applyStalenessHeaders(res);
+            sendJson(res, 200, cache.jsonData);
         }
         catch (error) {
             // No server-side retry here (unlike handleAction): a refresh re-run is a
@@ -785,17 +602,28 @@ export async function startDashboardServer(options) {
             sendError(res, 403, 'Forbidden');
             return;
         }
+        // Hashed build outputs live under /assets/ (Vite's content-addressed
+        // bundles). A missing file there must be a real 404, not the SPA
+        // fallback: serving index.html as 200 text/html makes the module loader
+        // reject the response, and after a plugin upgrade a cached index.html
+        // referencing deleted bundles would blank the dashboard (#1459).
+        const isAssetPath = urlPath.startsWith('/assets/');
+        const indexPath = path.join(resolvedAssetsDir, 'index.html');
         // If file doesn't exist or is a directory, serve index.html for SPA routing
         try {
             const stat = fs.statSync(filePath);
             if (stat.isDirectory()) {
-                filePath = path.join(resolvedAssetsDir, 'index.html');
+                filePath = indexPath;
             }
         }
         catch (err) {
             const nodeErr = err;
             if (nodeErr.code === 'ENOENT') {
-                filePath = path.join(resolvedAssetsDir, 'index.html');
+                if (isAssetPath) {
+                    sendError(res, 404, 'Not found');
+                    return;
+                }
+                filePath = indexPath;
             }
             else {
                 warn(MODULE, `Failed to stat file: ${filePath}`);
@@ -805,13 +633,19 @@ export async function startDashboardServer(options) {
         }
         const ext = path.extname(filePath).toLowerCase();
         const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+        // Honest caching (#1459): only hashed /assets/* files are safe to cache —
+        // their names change with their content. index.html (direct or SPA
+        // fallback) and other unhashed files (favicon, etc.) must revalidate so a
+        // plugin upgrade is picked up on the next navigation instead of serving a
+        // stale page that references deleted bundles for up to an hour.
+        const cacheControl = isAssetPath && filePath !== indexPath ? 'public, max-age=3600' : 'no-cache';
         try {
             const content = fs.readFileSync(filePath);
             setSecurityHeaders(res);
             res.writeHead(200, {
                 'Content-Type': contentType,
                 'Content-Length': content.length,
-                'Cache-Control': 'public, max-age=3600',
+                'Cache-Control': cacheControl,
             });
             res.end(content);
         }
@@ -864,30 +698,30 @@ export async function startDashboardServer(options) {
         fetchDashboardData(token)
             .then(async (result) => {
             // Same clear-before-recover ordering as handleRefresh (#1433 pass-2).
-            recoveryLossNotices = [];
-            if (stateManager.isGistMode()) {
-                await flushPendingGistSync();
-                await stateManager.refreshFromGist();
+            gistSync.clearRecoveryLossNotices();
+            if (gistSync.stateManager.isGistMode()) {
+                await gistSync.flushPendingGistSync();
+                await gistSync.pullFromGist();
+                // Heal a degraded bootstrap from the background refresh too (#1443).
+                if (gistSync.gistBootstrapDegraded())
+                    await gistSync.maybeRecoverGist();
             }
             else {
-                stateManager.reloadIfChanged();
-                await maybeRecoverGist();
+                gistSync.stateManager.reloadIfChanged();
+                await gistSync.maybeRecoverGist();
             }
-            cachedDigest = result.digest;
-            cachedCommentedIssues = result.commentedIssues;
-            cachedPartialFailures = result.partialFailures.length > 0 ? result.partialFailures : undefined;
-            cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues, result.allMergedPRs, result.allClosedPRs, withPendingGistWarnings(cachedPartialFailures));
-            cachedIssueListMtimeMs = getIssueListMtimeMs();
+            cache.adoptFetchResult(result);
+            cache.rebuild(gistSync.stateManager.getState(), result.allMergedPRs, result.allClosedPRs);
             // Successful refresh clears any prior failure signal (#1205).
-            lastBackgroundRefreshError = null;
+            cache.lastBackgroundRefreshError = null;
             warn(MODULE, 'Background data refresh complete');
             return;
         })
             .catch((error) => {
             // Capture so /api/data can surface staleness via X-Dashboard-Stale
             // header — previously the catch only logged to stderr (#1205).
-            lastBackgroundRefreshError = errorMessage(error);
-            warn(MODULE, `Background data refresh failed (serving cached data): ${lastBackgroundRefreshError}`);
+            cache.lastBackgroundRefreshError = errorMessage(error);
+            warn(MODULE, `Background data refresh failed (serving cached data): ${cache.lastBackgroundRefreshError}`);
         });
     }
     // ── Open browser ─────────────────────────────────────────────────────────