@oss-autopilot/core 3.13.3 → 3.13.4

package/dist/cli.js

@@ -77,9 +77,17 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
         }
         // Activate Gist persistence if configured, before any command runs.
         // Shared helper peeks at the state file and only pre-sets the singleton
-        // when Gist mode is the configured persistence (#1000).
+        // when Gist mode is the configured persistence (#1000). Hard errors
+        // still throw (#1202); the resolving degraded modes are surfaced in the
+        // JSON envelope so --json consumers see them too (#1433).
         const { ensureGistPersistence } = await import('./core/index.js');
-        await ensureGistPersistence(token);
+        const status = await ensureGistPersistence(token);
+        if (status === 'degraded' || status === 'state-unreadable') {
+            const { setEnvelopeGistWarning } = await import('./formatters/json.js');
+            setEnvelopeGistWarning('Gist persistence is configured but this run is LOCAL-ONLY (' +
+                (status === 'degraded' ? 'transient network failure during init' : 'state file could not be read') +
+                '); changes may be overwritten by the next successful Gist sync.');
+        }
     }
     else {
         // #1431: localOnly skips the AUTH GATE, not gist persistence. Mutating
@@ -93,6 +101,11 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
         const localOnlyWarning = await bootstrapGistBestEffort(getGitHubTokenAsync);
         if (localOnlyWarning) {
             console.error(`Warning: ${localOnlyWarning}`);
+            // Also thread it into the JSON envelope: shelve/move/dismiss --json
+            // consumers (the agent harness) must see the mutation will not sync —
+            // stderr alone is invisible to them (#1433).
+            const { setEnvelopeGistWarning } = await import('./formatters/json.js');
+            setEnvelopeGistWarning(localOnlyWarning);
         }
     }
 });

package/dist/commands/dashboard-server.js

@@ -9,8 +9,8 @@ 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 { errorMessage, ValidationError, ConcurrencyError, GistConcurrencyError } from '../core/errors.js';
+import { getStateManager, getGitHubToken, getCLIVersion, applyStatusOverrides, classifyAttentionBucket, maybeCheckpoint, ensureGistPersistence, } from '../core/index.js';
+import { errorMessage, ValidationError, ConcurrencyError, ConfigurationError, 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';
@@ -288,7 +288,10 @@ function sendConflict(res) {
 // ── Server ─────────────────────────────────────────────────────────────────────
 export async function startDashboardServer(options) {
     const { port: requestedPort, assetsDir, token, open } = options;
-    const stateManager = getStateManager();
+    // `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();
     const resolvedAssetsDir = path.resolve(assetsDir);
     // ── CSRF token ──────────────────────────────────────────────────────────
     // Fresh per server-start. Exposed to the SPA via X-CSRF-Token on every
@@ -336,10 +339,20 @@ export async function startDashboardServer(options) {
     /** Merge pending gist-sync warnings into a partialFailures payload for the
      * SPA banner without coupling their lifecycles. */
     function withPendingGistWarnings(failures) {
-        if (pendingGistSyncWarnings.length === 0)
+        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, ...pendingGistSyncWarnings.filter((w) => !base.includes(w))];
+        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
@@ -350,6 +363,92 @@ export async function startDashboardServer(options) {
             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) {
         throw new Error('No dashboard data available. Run the daily check first: GITHUB_TOKEN=$(gh auth token) npm start -- daily');
     }
@@ -397,6 +496,11 @@ export async function startDashboardServer(options) {
                 }
                 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;
                 }
                 // Also rebuild when the vetted issue list file was edited outside this server (#924)
                 const currentIssueListMtimeMs = getIssueListMtimeMs();
@@ -486,7 +590,15 @@ export async function startDashboardServer(options) {
             await stateManager.refreshFromGist();
         }
         else {
-            stateManager.reloadIfChanged();
+            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;
+            }
+            // reloadIfChanged may have just pulled a persistence=gist flip made
+            // from a terminal, and a degraded server heals here too (#1433).
+            await maybeRecoverGist();
         }
     }
     async function handleAction(req, res) {
@@ -596,6 +708,11 @@ export async function startDashboardServer(options) {
         // cachedPartialFailures — because gist warnings clear on a successful
         // PUSH, while fetch failures clear on a successful pull/refresh.
         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++;
         // 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
@@ -612,6 +729,12 @@ 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).
+            recoveryLossNotices = [];
             await reloadState();
             warn(MODULE, 'Refreshing dashboard data from GitHub...');
             const result = await fetchDashboardData(currentToken);
@@ -740,12 +863,15 @@ export async function startDashboardServer(options) {
     if (token) {
         fetchDashboardData(token)
             .then(async (result) => {
+            // Same clear-before-recover ordering as handleRefresh (#1433 pass-2).
+            recoveryLossNotices = [];
             if (stateManager.isGistMode()) {
                 await flushPendingGistSync();
                 await stateManager.refreshFromGist();
             }
             else {
                 stateManager.reloadIfChanged();
+                await maybeRecoverGist();
             }
             cachedDigest = result.digest;
             cachedCommentedIssues = result.commentedIssues;

package/dist/formatters/json.d.ts

@@ -16,7 +16,16 @@ export interface JsonOutput<T = unknown> {
     error?: string;
     errorCode?: ErrorCode;
     timestamp: string;
+    /** Present when the process is gist-configured but running local-only
+     * (#1433): machine consumers of mutating --json commands must see that
+     * the mutation will not sync. Set once per process from the CLI bootstrap
+     * via {@link setEnvelopeGistWarning}; envelope-level (not data-level) so
+     * per-command output schemas are untouched. */
+    gistInitWarning?: string;
 }
+/** Set (or clear) the gist degradation warning carried by every subsequent
+ * JSON envelope. Exported for the CLI bootstrap and for test isolation. */
+export declare function setEnvelopeGistWarning(warning: string | null): void;
 /**
  * Deduplicated daily digest for JSON output (#287).
  *

package/dist/formatters/json.js

@@ -4,6 +4,15 @@
  */
 import { z } from 'zod';
 import { fenceFetchedPR } from '../core/untrusted-content.js';
+// Process-level gist degradation warning threaded into every JSON envelope
+// (#1433). The CLI preAction bootstrap sets it; one-shot processes never
+// clear it (the whole invocation runs degraded or it doesn't).
+let envelopeGistWarning = null;
+/** Set (or clear) the gist degradation warning carried by every subsequent
+ * JSON envelope. Exported for the CLI bootstrap and for test isolation. */
+export function setEnvelopeGistWarning(warning) {
+    envelopeGistWarning = warning;
+}
 export function buildStalenessWarning(info) {
     return {
         phase: 'gist-staleness',
@@ -729,6 +738,7 @@ export function jsonSuccess(data) {
         success: true,
         data,
         timestamp: new Date().toISOString(),
+        ...(envelopeGistWarning ? { gistInitWarning: envelopeGistWarning } : {}),
     };
 }
 /**
@@ -740,6 +750,7 @@ export function jsonError(message, errorCode) {
         error: message,
         errorCode,
         timestamp: new Date().toISOString(),
+        ...(envelopeGistWarning ? { gistInitWarning: envelopeGistWarning } : {}),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "3.13.3",
+  "version": "3.13.4",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {