@oss-autopilot/core 3.13.4 → 3.14.1

package/dist/commands/dashboard-data.d.ts

@@ -50,10 +50,11 @@ export interface DashboardJsonData {
     lastUpdated?: string;
     /**
      * Labels of sub-fetches that degraded to empty fallbacks during this data
-     * build. Non-empty means one or more background calls failed and the
-     * corresponding sections of the response are approximations (stale or
-     * zero'd) rather than authoritative. The SPA surfaces this as a banner
-     * so users know the dashboard is showing partial data. See #1035.
+     * build, plus persistence steps that failed to save (#1447). Non-empty
+     * means one or more background calls failed and the corresponding sections
+     * of the response are approximations (stale or zero'd) rather than
+     * authoritative. The SPA surfaces this as a banner so users know the
+     * dashboard is showing partial data. See #1035.
      */
     partialFailures?: string[];
 }
@@ -103,10 +104,15 @@ export declare function mergeMonthlyCounts(existing: Record<string, number>, fre
  * Each metric is isolated so partial failures don't produce inconsistent state.
  * Fresh API results are merged into existing data so historical months are preserved.
  * Skips updating when fresh data is empty to avoid wiping chart data on transient API failures.
+ *
+ * Returns the labels of any metrics that failed to persist (#1447) so callers
+ * with a partialFailures surface (fetchDashboardData) can push them into the
+ * SPA banner instead of the failure living only in stderr. Callers without
+ * that surface (daily.ts) may ignore the return value.
  */
 export declare function updateMonthlyAnalytics(prs: Array<{
     createdAt?: string;
-}>, monthlyCounts: Record<string, number>, monthlyClosedCounts: Record<string, number>, openedFromMerged: Record<string, number>, openedFromClosed: Record<string, number>): void;
+}>, monthlyCounts: Record<string, number>, monthlyClosedCounts: Record<string, number>, openedFromMerged: Record<string, number>, openedFromClosed: Record<string, number>): string[];
 export interface DashboardFetchResult {
     digest: DailyDigest;
     commentedIssues: CommentedIssue[];
@@ -114,11 +120,13 @@ export interface DashboardFetchResult {
     allClosedPRs: ClosedPR[];
     /**
      * Labels of non-critical sub-fetches that degraded to empty fallbacks
-     * during this run. Empty array means every fetch succeeded. Non-empty
-     * means one or more slices of the returned data are approximations —
-     * callers surface this to the user so "0 recently merged" does not look
-     * authoritative when it is actually "fetch failed, fell back to empty".
-     * See #1035.
+     * during this run, plus persistence steps that failed to save (#1447:
+     * monthly chart analytics, stored merged/closed PRs, the cached digest).
+     * Empty array means every fetch and persist succeeded. Non-empty means
+     * one or more slices of the returned data are approximations — callers
+     * surface this to the user so "0 recently merged" does not look
+     * authoritative when it is actually "fetch failed, fell back to empty",
+     * and so silently-stale charts/digest are flagged. See #1035.
      */
     partialFailures: string[];
 }

package/dist/commands/dashboard-data.js

@@ -9,7 +9,7 @@ import { warn } from '../core/logger.js';
 import { emptyPRCountsResult, fetchMergedPRsSince, fetchClosedPRsSince } from '../core/github-stats.js';
 import { parseGitHubUrl } from '../core/urls.js';
 import { isBelowMinStars, } from '../core/types.js';
-import { toShelvedPRRef, buildStarFilter } from '../core/index.js';
+import { toShelvedPRRef, buildStarFilter, firstMaintainerResponseFromDigest } from '../core/index.js';
 const MODULE = 'dashboard-data';
 export function buildDashboardStats(digest, state, storedMergedCount, storedClosedCount) {
     const summary = digest.summary || {
@@ -117,16 +117,23 @@ export function mergeMonthlyCounts(existing, fresh) {
  * Each metric is isolated so partial failures don't produce inconsistent state.
  * Fresh API results are merged into existing data so historical months are preserved.
  * Skips updating when fresh data is empty to avoid wiping chart data on transient API failures.
+ *
+ * Returns the labels of any metrics that failed to persist (#1447) so callers
+ * with a partialFailures surface (fetchDashboardData) can push them into the
+ * SPA banner instead of the failure living only in stderr. Callers without
+ * that surface (daily.ts) may ignore the return value.
  */
 export function updateMonthlyAnalytics(prs, monthlyCounts, monthlyClosedCounts, openedFromMerged, openedFromClosed) {
     const stateManager = getStateManager();
     const state = stateManager.getState();
+    const failures = [];
     try {
         if (Object.keys(monthlyCounts).length > 0) {
             stateManager.setMonthlyMergedCounts(mergeMonthlyCounts(state.monthlyMergedCounts || {}, monthlyCounts));
         }
     }
     catch (error) {
+        failures.push('store monthly merged counts');
         warn(MODULE, `Failed to store monthly merged counts: ${errorMessage(error)}`);
     }
     try {
@@ -135,6 +142,7 @@ export function updateMonthlyAnalytics(prs, monthlyCounts, monthlyClosedCounts,
         }
     }
     catch (error) {
+        failures.push('store monthly closed counts');
         warn(MODULE, `Failed to store monthly closed counts: ${errorMessage(error)}`);
     }
     try {
@@ -153,8 +161,10 @@ export function updateMonthlyAnalytics(prs, monthlyCounts, monthlyClosedCounts,
         }
     }
     catch (error) {
+        failures.push('store monthly opened counts');
         warn(MODULE, `Failed to store monthly opened counts: ${errorMessage(error)}`);
     }
+    return failures;
 }
 /**
  * Fetch fresh dashboard data from GitHub.
@@ -172,6 +182,28 @@ export async function fetchDashboardData(token) {
     // Get watermarks for incremental PR fetch
     const watermark = stateManager.getMergedPRWatermark();
     const closedWatermark = stateManager.getClosedPRWatermark();
+    // Self-heal a ledger stranded behind a recent watermark (#1504). The
+    // incremental fetch only asks for merges newer than the newest stored one,
+    // so once the recent-merge feed (daily's recentlyMergedPRs) seeds the ledger
+    // before any full historical fetch ran, the older history can never be
+    // recovered. When the stored detail count is materially below the known
+    // all-time merged count, drop the watermark for a one-shot full backfill
+    // (bounded by the existing pagination cap); once the ledger catches up the
+    // watermark resumes incremental fetching. Closed PRs are not seeded ahead of
+    // their backfill in practice, so only merged needs the guard.
+    const storedMergedCount = stateManager.getMergedPRs().length;
+    const knownMergedAllTime = stateManager.getState().lastDigest?.summary?.totalMergedAllTime ?? 0;
+    // A full backfill can only ever return up to fetchMergedPRsSince's pagination
+    // cap (MAX_PAGINATION_PAGES * 100 = 300). Stop forcing one once the ledger has
+    // reached that ceiling, so a contributor whose star-filtered all-time count
+    // legitimately exceeds 300 doesn't trigger a full refetch on every poll.
+    const MERGED_BACKFILL_CEILING = 300;
+    const mergedNeedsBackfill = storedMergedCount < knownMergedAllTime && storedMergedCount < MERGED_BACKFILL_CEILING;
+    const mergedFetchSince = mergedNeedsBackfill ? undefined : watermark;
+    if (mergedNeedsBackfill) {
+        warn(MODULE, `Merged-PR ledger has ${storedMergedCount} of ~${knownMergedAllTime} known merges; ` +
+            'running a full backfill (watermark dropped) to recover history (#1504).');
+    }
     // Track which non-critical sub-fetches degraded to fallbacks so the SPA
     // can surface a "partial data" banner instead of silently showing zeros.
     // Rate-limit / auth errors still rethrow via isRateLimitOrAuthError —
@@ -213,7 +245,7 @@ export async function fetchDashboardData(token) {
                 failures: [{ issueUrl: 'N/A', error: `Issue conversation fetch failed: ${msg}` }],
             };
         }),
-        fetchMergedPRsSince(octokit, config, watermark).catch(trackingCatch('fetch merged PRs for storage', [])),
+        fetchMergedPRsSince(octokit, config, mergedFetchSince).catch(trackingCatch('fetch merged PRs for storage', [])),
         fetchClosedPRsSince(octokit, config, closedWatermark).catch(trackingCatch('fetch closed PRs for storage', [])),
     ]);
     const commentedIssues = fetchedIssues.issues;
@@ -242,25 +274,42 @@ export async function fetchDashboardData(token) {
             // partition here than on the CLI surface (#1416). Inside the batch
             // because getStatusOverride may auto-clear stale overrides with a save,
             // which must defer to this guarded boundary rather than throw here.
-            const overriddenPRs = applyStatusOverrides(prs, stateManager.getState());
-            // Store new merged PRs incrementally (dedupes by URL)
+            // Per-PR override failures (#1448) land in partialFailures so the SPA
+            // banner flags PRs silently showing their un-overridden status.
+            const overriddenPRs = applyStatusOverrides(prs, stateManager.getState(), partialFailures);
+            // Previous run's digest — read BEFORE setLastDigest below replaces it.
+            // Supplies best-effort firstMaintainerResponseAt for PRs that were
+            // enriched while open, mirroring daily's Phase 3 (#1461). openedAt is
+            // already on the entries (created_at from the search result).
+            const previousDigest = stateManager.getState().lastDigest;
+            // Store new merged PRs incrementally (dedupes by URL; re-seen entries
+            // upgrade missing ledger fields in place)
             try {
-                const { dropped } = stateManager.addMergedPRs(newMergedPRs);
+                const { dropped } = stateManager.addMergedPRs(newMergedPRs.map((pr) => ({
+                    ...pr,
+                    firstMaintainerResponseAt: pr.firstMaintainerResponseAt ?? firstMaintainerResponseFromDigest(previousDigest, pr.url),
+                })));
                 if (dropped > 0) {
                     partialFailures.push(`Dropped ${dropped} merged PR(s) with invalid URLs before persistence`);
                 }
             }
             catch (error) {
+                partialFailures.push('store merged PRs');
                 warn(MODULE, `Failed to store merged PRs: ${errorMessage(error)}`);
             }
-            // Store new closed PRs incrementally (dedupes by URL)
+            // Store new closed PRs incrementally (dedupes by URL; re-seen entries
+            // upgrade missing ledger fields in place)
             try {
-                const { dropped } = stateManager.addClosedPRs(newClosedPRs);
+                const { dropped } = stateManager.addClosedPRs(newClosedPRs.map((pr) => ({
+                    ...pr,
+                    firstMaintainerResponseAt: pr.firstMaintainerResponseAt ?? firstMaintainerResponseFromDigest(previousDigest, pr.url),
+                })));
                 if (dropped > 0) {
                     partialFailures.push(`Dropped ${dropped} closed PR(s) with invalid URLs before persistence`);
                 }
             }
             catch (error) {
+                partialFailures.push('store closed PRs');
                 warn(MODULE, `Failed to store closed PRs: ${errorMessage(error)}`);
             }
             // Store monthly chart data (opened/merged/closed) so charts have data.
@@ -268,7 +317,7 @@ export async function fetchDashboardData(token) {
             // never the createdAt/mergedAt dates the monthly counts key off.
             const { monthlyCounts, monthlyOpenedCounts: openedFromMerged } = mergedResult;
             const { monthlyCounts: monthlyClosedCounts, monthlyOpenedCounts: openedFromClosed } = closedResult;
-            updateMonthlyAnalytics(prs, monthlyCounts, monthlyClosedCounts, openedFromMerged, openedFromClosed);
+            partialFailures.push(...updateMonthlyAnalytics(prs, monthlyCounts, monthlyClosedCounts, openedFromMerged, openedFromClosed));
             // The digest keeps RAW statuses in openPRs: this digest becomes the
             // server's cached/persisted rebuild source, and baking overridden
             // statuses into it would make CLEARING an override (move target=auto) a
@@ -294,6 +343,7 @@ export async function fetchDashboardData(token) {
         });
     }
     catch (error) {
+        partialFailures.push('persist dashboard state');
         warn(MODULE, `Failed to persist dashboard state: ${errorMessage(error)}`);
     }
     warn(MODULE, `Refreshed: ${prs.length} PRs fetched`);

package/dist/commands/dashboard-gist-sync.d.ts

@@ -0,0 +1,93 @@
+/**
+ * GistSyncCoordinator — the dashboard server's gist-sync lifecycle state machine.
+ *
+ * Extracted from dashboard-server.ts (#1457). Owns the five pieces of gist
+ * lifecycle state (pending push warnings, loss notices, degraded mutation
+ * count, recovery halt reason, recovery throttle stamp) plus the live
+ * StateManager reference, which a degraded recovery replaces (#1433). The
+ * HTTP handlers consume it as a collaborator; nothing here touches req/res.
+ */
+import { type StateManager, type GistHealth } from '../core/index.js';
+export declare class GistSyncCoordinator {
+    /** Token from server options; falls back to getGitHubToken() per recovery attempt. */
+    private readonly token;
+    /** Logger module tag (kept identical to the server's so log output is unchanged). */
+    private readonly module;
+    private manager;
+    private pendingGistSyncWarnings;
+    private lastRecoveryAttemptAt;
+    private recoveryHaltedReason;
+    private degradedMutationCount;
+    private recoveryLossNotices;
+    constructor(
+    /** Token from server options; falls back to getGitHubToken() per recovery attempt. */
+    token: string | null, 
+    /** Logger module tag (kept identical to the server's so log output is unchanged). */
+    module: string);
+    /** The live state manager. Always read through this accessor — a degraded
+     * gist recovery replaces the core singleton mid-flight (#1433). */
+    get stateManager(): StateManager;
+    /** 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. */
+    recordGistSyncOutcome(warning: string | null): void;
+    /** Merge pending gist-sync warnings into a partialFailures payload for the
+     * SPA banner without coupling their lifecycles. */
+    withPendingGistWarnings(failures: string[] | undefined): string[] | undefined;
+    /** 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. */
+    flushPendingGistSync(): Promise<void>;
+    /** One health snapshot from the one source (#1444). Defensive: this is an
+     * advisory probe that runs on EVERY request path (rebuilds, recovery
+     * gates). A state failure has its own handling wherever state is actually
+     * consumed — the probe must not become a new crash surface in front of it
+     * (#994's stale-serving path). */
+    probeGistHealth(): GistHealth | null;
+    /** 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. */
+    gistConfiguredButLocal(): boolean;
+    /** Gist-backed but the bootstrap itself fell back to the local cache —
+     * reads may be stale even though isGistMode() is true (#1433 review). */
+    gistBootstrapDegraded(): boolean;
+    /** A successful PULL (refresh, or a recovery re-bootstrap) wholesale-
+     * replaces in-memory state. If push warnings are still pending at that
+     * moment, the mutations they describe are gone from the working state and
+     * a LATER push can never carry them — so an unrelated future push must not
+     * be allowed to "resolve" them (#1443). Convert the prospective warnings
+     * into a retrospective loss notice. Lifecycle invariants from #1417/#1433
+     * are unchanged: pending warnings still clear only via recordGistSyncOutcome
+     * on a successful push, and loss notices still clear at the start of the
+     * next refresh cycle. */
+    convertPendingWarningsToLossNotices(): void;
+    /** Pull from the Gist, converting still-pending push warnings into a loss
+     * notice when the pull actually replaced state (#1443). All dashboard pull
+     * sites go through here; callers flush pending pushes first (#1417), so a
+     * warning that is still pending at pull time means the flush failed. */
+    pullFromGist(): Promise<boolean>;
+    /** 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.
+     *
+     * Covers BOTH degraded shapes (#1443): a local-only manager under a gist
+     * config, and a gist-backed manager whose bootstrap fell back to the local
+     * cache (disarmed store — refreshFromGist can never heal it on its own). */
+    maybeRecoverGist(): Promise<void>;
+    /** 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). */
+    unhaltRecovery(): void;
+    /** 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. */
+    recordMutationWhileDegraded(): void;
+    /** Retire pre-existing loss notices — by the time a refresh cycle starts
+     * they have been visible across the degraded window (#1433 pass-2). */
+    clearRecoveryLossNotices(): void;
+}

package/dist/commands/dashboard-gist-sync.js

@@ -0,0 +1,237 @@
+/**
+ * GistSyncCoordinator — the dashboard server's gist-sync lifecycle state machine.
+ *
+ * Extracted from dashboard-server.ts (#1457). Owns the five pieces of gist
+ * lifecycle state (pending push warnings, loss notices, degraded mutation
+ * count, recovery halt reason, recovery throttle stamp) plus the live
+ * StateManager reference, which a degraded recovery replaces (#1433). The
+ * HTTP handlers consume it as a collaborator; nothing here touches req/res.
+ */
+import { getStateManager, getGitHubToken, maybeCheckpoint, ensureGistPersistence, } from '../core/index.js';
+import { errorMessage, ConfigurationError } from '../core/errors.js';
+import { warn } from '../core/logger.js';
+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.';
+// #1443: a degraded bootstrap disarms the store, so "the next successful
+// Gist read" can never arrive on its own — maybeRecoverGist re-bootstraps
+// (the gate below treats this state as recoverable), which is the retry
+// this banner now promises.
+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. Recovery is retried automatically.';
+// 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;
+export class GistSyncCoordinator {
+    token;
+    module;
+    // Mutable (#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.
+    manager;
+    // 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.
+    pendingGistSyncWarnings = [];
+    lastRecoveryAttemptAt = 0;
+    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).
+    degradedMutationCount = 0;
+    recoveryLossNotices = [];
+    constructor(
+    /** Token from server options; falls back to getGitHubToken() per recovery attempt. */
+    token, 
+    /** Logger module tag (kept identical to the server's so log output is unchanged). */
+    module) {
+        this.token = token;
+        this.module = module;
+        this.manager = getStateManager();
+    }
+    /** The live state manager. Always read through this accessor — a degraded
+     * gist recovery replaces the core singleton mid-flight (#1433). */
+    get stateManager() {
+        return this.manager;
+    }
+    /** 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. */
+    recordGistSyncOutcome(warning) {
+        if (warning === null) {
+            this.pendingGistSyncWarnings = [];
+            return;
+        }
+        if (!this.pendingGistSyncWarnings.includes(warning)) {
+            this.pendingGistSyncWarnings.push(warning);
+        }
+    }
+    /** Merge pending gist-sync warnings into a partialFailures payload for the
+     * SPA banner without coupling their lifecycles. */
+    withPendingGistWarnings(failures) {
+        const extras = [...this.pendingGistSyncWarnings, ...this.recoveryLossNotices];
+        if (this.gistConfiguredButLocal()) {
+            extras.push(this.recoveryHaltedReason === null
+                ? GIST_DEGRADED_WARNING
+                : `Gist persistence is configured but recovery FAILED permanently: ${this.recoveryHaltedReason} — ` +
+                    'fix the Gist setup (check the token gist scope, or run state-show), then restart the dashboard.');
+        }
+        else if (this.gistBootstrapDegraded()) {
+            // Same halt surfacing as the local-only branch (#1443): a permanent
+            // recovery failure must reach the banner here too, or the stale-data
+            // retry promise in GIST_STALE_BOOTSTRAP_WARNING would dangle forever
+            // with no visible reason.
+            extras.push(this.recoveryHaltedReason === null
+                ? GIST_STALE_BOOTSTRAP_WARNING
+                : `Gist persistence is degraded and recovery FAILED permanently: ${this.recoveryHaltedReason} — ` +
+                    'fix the Gist setup (check the token gist scope, or run state-show), then restart the dashboard.');
+        }
+        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 flushPendingGistSync() {
+        if (this.pendingGistSyncWarnings.length === 0)
+            return;
+        this.recordGistSyncOutcome(await maybeCheckpoint(this.manager, this.module));
+    }
+    /** One health snapshot from the one source (#1444). Defensive: this is an
+     * advisory probe that runs on EVERY request path (rebuilds, recovery
+     * gates). A state failure has its own handling wherever state is actually
+     * consumed — the probe must not become a new crash surface in front of it
+     * (#994's stale-serving path). */
+    probeGistHealth() {
+        try {
+            return this.manager.getGistHealth();
+        }
+        catch (err) {
+            warn(this.module, `Degraded-gist probe failed (treating as not degraded): ${errorMessage(err)}`);
+            return null;
+        }
+    }
+    /** 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. */
+    gistConfiguredButLocal() {
+        const health = this.probeGistHealth();
+        return health !== null && health.mode === 'local' && health.degraded !== null;
+    }
+    /** Gist-backed but the bootstrap itself fell back to the local cache —
+     * reads may be stale even though isGistMode() is true (#1433 review). */
+    gistBootstrapDegraded() {
+        const health = this.probeGistHealth();
+        return health !== null && health.mode === 'gist' && health.degraded !== null;
+    }
+    /** A successful PULL (refresh, or a recovery re-bootstrap) wholesale-
+     * replaces in-memory state. If push warnings are still pending at that
+     * moment, the mutations they describe are gone from the working state and
+     * a LATER push can never carry them — so an unrelated future push must not
+     * be allowed to "resolve" them (#1443). Convert the prospective warnings
+     * into a retrospective loss notice. Lifecycle invariants from #1417/#1433
+     * are unchanged: pending warnings still clear only via recordGistSyncOutcome
+     * on a successful push, and loss notices still clear at the start of the
+     * next refresh cycle. */
+    convertPendingWarningsToLossNotices() {
+        if (this.pendingGistSyncWarnings.length === 0)
+            return;
+        this.recoveryLossNotices.push(`A Gist read replaced local state while ${this.pendingGistSyncWarnings.length} change(s) were still un-pushed — ` +
+            'they were NOT synced to the Gist and may have been reverted in this view. Re-apply anything missing.');
+        this.pendingGistSyncWarnings = [];
+    }
+    /** Pull from the Gist, converting still-pending push warnings into a loss
+     * notice when the pull actually replaced state (#1443). All dashboard pull
+     * sites go through here; callers flush pending pushes first (#1417), so a
+     * warning that is still pending at pull time means the flush failed. */
+    async pullFromGist() {
+        const refreshed = await this.manager.refreshFromGist();
+        if (refreshed)
+            this.convertPendingWarningsToLossNotices();
+        return refreshed;
+    }
+    /** 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.
+     *
+     * Covers BOTH degraded shapes (#1443): a local-only manager under a gist
+     * config, and a gist-backed manager whose bootstrap fell back to the local
+     * cache (disarmed store — refreshFromGist can never heal it on its own). */
+    async maybeRecoverGist() {
+        // One probe covers both degraded shapes — health.degraded is non-null
+        // for configured-but-local AND bootstrap-degraded (#1444).
+        if (this.probeGistHealth()?.degraded == null)
+            return;
+        if (this.recoveryHaltedReason !== null)
+            return;
+        const now = Date.now();
+        if (now - this.lastRecoveryAttemptAt < RECOVERY_RETRY_INTERVAL_MS)
+            return;
+        const currentToken = this.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;
+        this.lastRecoveryAttemptAt = now;
+        try {
+            await ensureGistPersistence(currentToken);
+            // The upgrade replaced the core singleton — re-resolve our reference.
+            this.manager = getStateManager();
+            // Genuinely armed only: a retry can resolve via ANOTHER degraded
+            // bootstrap (gist-backed, store disarmed) — that is not a recovery
+            // and must not produce a recovery notice (#1443).
+            const health = this.manager.getGistHealth();
+            const recovered = health.mode === 'gist' && health.degraded === null;
+            if (recovered) {
+                // The re-bootstrap pulled the existing Gist: un-pushed mutations
+                // from the degraded window are not in the replacement state.
+                this.convertPendingWarningsToLossNotices();
+            }
+            if (recovered && this.degradedMutationCount > 0) {
+                this.recoveryLossNotices.push(`Gist persistence recovered, but ${this.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.');
+                this.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) {
+                this.recoveryHaltedReason = errorMessage(err);
+            }
+            warn(this.module, `Gist recovery attempt failed: ${errorMessage(err)}`);
+        }
+    }
+    /** 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). */
+    unhaltRecovery() {
+        this.recoveryHaltedReason = null;
+    }
+    /** 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. */
+    recordMutationWhileDegraded() {
+        if (this.gistConfiguredButLocal())
+            this.degradedMutationCount++;
+    }
+    /** Retire pre-existing loss notices — by the time a refresh cycle starts
+     * they have been visible across the degraded window (#1433 pass-2). */
+    clearRecoveryLossNotices() {
+        this.recoveryLossNotices = [];
+    }
+}

package/dist/commands/dashboard-server.d.ts

@@ -4,9 +4,13 @@
  * 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 { type DashboardJsonData } from './dashboard-data.js';
-import { type DailyDigest, type AgentState, type CommentedIssue, type MergedPR, type ClosedPR } from '../core/types.js';
+export { buildDashboardJson } from './dashboard-cache.js';
 export { getDashboardPidPath, writeDashboardServerInfo, readDashboardServerInfo, removeDashboardServerInfo, isDashboardServerRunning, findRunningDashboardServer, type DashboardServerInfo, } from './dashboard-process.js';
 export interface DashboardServerOptions {
     port: number;
@@ -14,12 +18,4 @@ export interface DashboardServerOptions {
     token: string | null;
     open: boolean;
 }
-/**
- * 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 declare function buildDashboardJson(digest: DailyDigest, state: Readonly<AgentState>, commentedIssues: CommentedIssue[], allMergedPRs?: MergedPR[], allClosedPRs?: ClosedPR[], partialFailures?: string[]): DashboardJsonData;
 export declare function startDashboardServer(options: DashboardServerOptions): Promise<void>;