@oss-autopilot/core 3.13.3 → 3.14.0

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, } from '../core/index.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,7 +191,12 @@ function sendConflict(res) {
 // ── Server ─────────────────────────────────────────────────────────────────────
 export async function startDashboardServer(options) {
     const { port: requestedPort, assetsDir, token, open } = options;
-    const 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
@@ -302,62 +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) {
-        if (pendingGistSyncWarnings.length === 0)
-            return failures;
-        const base = failures ?? [];
-        return [...base, ...pendingGistSyncWarnings.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));
-    }
-    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 });
@@ -389,26 +249,36 @@ 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();
+                // 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();
+                // Gist-mode staleness (#1446 item 2): refreshFromGist() returns
+                // false on BOTH "no change" and "fetch failed", so the boolean can't
+                // signal failure. getStateStaleness() is the API built for exactly
+                // this — StateManager sets the marker when in-memory state diverged
+                // from the canonical Gist (refresh failure, invalid payload,
+                // degraded bootstrap) and clears it on a successful pull.
+                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}`));
                 }
                 // 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');
                     }
@@ -417,11 +287,11 @@ export async function startDashboardServer(options) {
                 // 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) {
+                if (cache.lastBackgroundRefreshError !== null) {
                     res.setHeader('X-Dashboard-Stale', '1');
-                    res.setHeader('X-Dashboard-Stale-Reason', `background-refresh-failed: ${lastBackgroundRefreshError}`);
+                    res.setHeader('X-Dashboard-Stale-Reason', sanitizeHeaderValue(`background-refresh-failed: ${cache.lastBackgroundRefreshError}`));
                 }
-                sendJson(res, 200, cachedJsonData);
+                sendJson(res, 200, cache.jsonData);
                 return;
             }
             if (url === '/api/action' && method === 'POST') {
@@ -479,15 +349,54 @@ 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();
+        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;
+            }
+            return refreshed;
         }
-        else {
-            stateManager.reloadIfChanged();
+        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;
     }
     async function handleAction(req, res) {
         let body;
@@ -547,11 +456,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.
@@ -595,14 +504,17 @@ 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.
+        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());
+        sendJson(res, 200, cache.jsonData);
     }
     // ── POST /api/refresh handler ────────────────────────────────────────────
     async function handleRefresh(_req, res) {
@@ -612,17 +524,18 @@ export async function startDashboardServer(options) {
             return;
         }
         try {
+            // Clear PRE-EXISTING loss notices before the reload: by now they have
+            // been visible across the degraded window. Order matters — this
+            // 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).
+            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);
+            sendJson(res, 200, cache.jsonData);
         }
         catch (error) {
             // No server-side retry here (unlike handleAction): a refresh re-run is a
@@ -662,17 +575,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}`);
@@ -682,13 +606,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);
         }
@@ -740,28 +670,31 @@ export async function startDashboardServer(options) {
     if (token) {
         fetchDashboardData(token)
             .then(async (result) => {
-            if (stateManager.isGistMode()) {
-                await flushPendingGistSync();
-                await stateManager.refreshFromGist();
+            // Same clear-before-recover ordering as handleRefresh (#1433 pass-2).
+            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();
+                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 ─────────────────────────────────────────────────────────

package/dist/commands/features.js

@@ -119,6 +119,12 @@ function toFeaturesCandidate(scoutCandidate, getState) {
  */
 export async function runFeatures(options) {
     const scout = await createAutopilotScout();
+    // Strategy bias (preferLanguages/preferRepos/avoidRepos/boostIssueTypes/
+    // diversityRatio) reaches this path through the bridge-built
+    // ScoutPreferences (#1464) — the same derivation `runSearch` uses per-call.
+    // scout.features() in scout 1.1.0 accepts only count/anchorThreshold/
+    // splitRatio/broad — do NOT pass bias knobs here; unsupported options
+    // would be silently ignored. Preferences are the supported channel.
     const result = await scout.features({
         count: options.maxResults,
         anchorThreshold: options.anchorThreshold,

package/dist/commands/guidelines.d.ts

@@ -50,6 +50,12 @@ export interface FetchCorpusOutput {
     }>;
     /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
     gistSyncWarning?: string;
+    /**
+     * Non-fatal data-quality warnings (#1456). Currently produced when a
+     * bundle's comment streams hit the pagination cap, meaning the newest
+     * comments on that PR are missing from the corpus. Omitted on clean runs.
+     */
+    warnings?: string[];
 }
 interface RepoOption {
     repo: string;

package/dist/commands/guidelines.js

@@ -167,6 +167,12 @@ export async function runFetchCorpus(options) {
     if (bundles.length > 0) {
         gistSyncWarning = await maybeCheckpoint(sm, MODULE);
     }
+    // Surface pagination truncation per bundle (#1456): a truncated bundle is
+    // missing its newest comments, so the host should know the corpus for that
+    // PR is partial rather than assuming every reviewer voice is present.
+    const warnings = bundles
+        .filter((b) => b.truncated)
+        .map((b) => `${b.prUrl}: comment streams hit the pagination cap; newest comments are missing from the corpus`);
     return {
         repo: options.repo,
         bundles,
@@ -174,6 +180,7 @@ export async function runFetchCorpus(options) {
         skipped,
         failures,
         ...(gistSyncWarning ? { gistSyncWarning } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
 function clampLimit(limit) {

package/dist/commands/index.d.ts

@@ -39,10 +39,6 @@ export { runTrack } from './track.js';
 export { runComplianceScore } from './compliance-score.js';
 /** Compute repo health rubric (1–10 score + verdict) via the typed core function (#1271, follow-up to #1242). */
 export { runRepoVet } from './repo-vet.js';
-/** Temporarily hide a PR from the daily digest. */
-export { runShelve } from './shelve.js';
-/** Restore a shelved PR to the daily digest. */
-export { runUnshelve } from './shelve.js';
 /** Move a PR between states: attention, waiting, shelved, auto. */
 export { runMove } from './move.js';
 /** Dismiss issue reply notifications (auto-resurfaces on new activity). */
@@ -85,6 +81,8 @@ export { runParseList, pruneIssueList } from './parse-list.js';
 export { runListMoveTier, moveIssueToTier, type Tier, type ListMoveTierOptions, type ListMoveTierOutput, } from './list-move-tier.js';
 /** Mark an issue line in a curated list as done with strikethrough + Done sub-bullet (#1299). */
 export { runMarkIssueListItemDone, markIssueAsDone, type MarkDoneOptions, type MarkDoneOutput, } from './list-mark-done.js';
+/** Daily merge-loop reconciliation — auto-mark curated-list entries whose PR merged (#1463). */
+export { reconcileMergedPRsWithList, findListEntryUrlByPrUrl } from './merge-loop.js';
 /** Check if new files are properly referenced/integrated. */
 export { runCheckIntegration } from './check-integration.js';
 /** System-health diagnostic — verifies tokens, bundle, state, scout, rate limit. */
@@ -98,7 +96,6 @@ export type { ErrorCode } from '../formatters/json.js';
 export type { DailyOutput, SearchOutput, SearchCandidate, CandidateLinkedPR, FeaturesOutput, FeaturesCandidate, FeaturesHorizon, StartupOutput, StatusOutput, TrackOutput, } from '../formatters/json.js';
 export type { VetOutput, CommentsOutput, PostOutput, ClaimOutput, VetListOutput, VetListItemStatus, } from '../formatters/json.js';
 export type { ConfigOutput, DetectFormattersOutput, ParseIssueListOutput, ParsedIssueItem, CheckIntegrationOutput, LocalReposOutput, } from '../formatters/json.js';
-export type { ShelveOutput, UnshelveOutput } from './shelve.js';
 export type { MoveOutput, MoveTarget } from './move.js';
 export type { GuidelinesListOutput, GuidelinesViewOutput, GuidelinesStoreOutput, GuidelinesResetOutput, FetchCorpusOutput, } from './guidelines.js';
 export type { DismissOutput, UndismissOutput } from './dismiss.js';

package/dist/commands/index.js

@@ -41,10 +41,6 @@ export { runTrack } from './track.js';
 export { runComplianceScore } from './compliance-score.js';
 /** Compute repo health rubric (1–10 score + verdict) via the typed core function (#1271, follow-up to #1242). */
 export { runRepoVet } from './repo-vet.js';
-/** Temporarily hide a PR from the daily digest. */
-export { runShelve } from './shelve.js';
-/** Restore a shelved PR to the daily digest. */
-export { runUnshelve } from './shelve.js';
 /** Move a PR between states: attention, waiting, shelved, auto. */
 export { runMove } from './move.js';
 /** Dismiss issue reply notifications (auto-resurfaces on new activity). */
@@ -92,6 +88,8 @@ export { runParseList, pruneIssueList } from './parse-list.js';
 export { runListMoveTier, moveIssueToTier, } from './list-move-tier.js';
 /** Mark an issue line in a curated list as done with strikethrough + Done sub-bullet (#1299). */
 export { runMarkIssueListItemDone, markIssueAsDone, } from './list-mark-done.js';
+/** Daily merge-loop reconciliation — auto-mark curated-list entries whose PR merged (#1463). */
+export { reconcileMergedPRsWithList, findListEntryUrlByPrUrl } from './merge-loop.js';
 /** Check if new files are properly referenced/integrated. */
 export { runCheckIntegration } from './check-integration.js';
 /** System-health diagnostic — verifies tokens, bundle, state, scout, rate limit. */

package/dist/commands/init.d.ts

@@ -5,6 +5,8 @@
 export interface InitOutput {
     username: string;
     message: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1440). */
+    gistSyncWarning?: string;
 }
 /**
  * Initialize with a GitHub username.