@oss-autopilot/core 3.13.2 → 3.13.4

package/dist/cli.js

@@ -77,9 +77,36 @@ 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
+        // localOnly commands (shelve/move/dismiss/override/...) already call
+        // maybeCheckpoint, which silently no-ops when the singleton never
+        // bootstrapped — so a gist-configured user's CLI mutations were written
+        // local-only with no warning and never reached the Gist. Best-effort
+        // bootstrap; the warning semantics live (and are unit-tested) in
+        // bootstrapGistBestEffort.
+        const { bootstrapGistBestEffort } = await import('./core/index.js');
+        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);
+        }
     }
 });
 // First-run detection: if no subcommand was provided and no state file exists,

package/dist/commands/daily.js

@@ -546,6 +546,15 @@ async function executeDailyCheckInternal(token) {
     // One collector shared by every phase — threaded through explicitly so the
     // callgraph documents which phases can produce non-fatal warnings. See #1042.
     const warnings = [];
+    // Surface gist-mode degradation in the machine-readable envelope (#1431):
+    // a process whose config says `persistence: gist` but whose manager is
+    // local-only (transient init fallback, or a localOnly entry point that
+    // never bootstrapped) writes mutations that will not sync. Previously the
+    // only signal was a stderr warn, invisible to --json consumers.
+    const smForGistCheck = getStateManager();
+    if (smForGistCheck.getState().config.persistence === 'gist' && !smForGistCheck.isGistMode()) {
+        recordWarning(warnings, 'gist-init', 'Gist persistence degraded', new Error('configured for Gist but running local-only in this process; mutations will not sync until Gist init succeeds'));
+    }
     // Surface Gist staleness up-front so consumers see it even if Phase 1 fails (#1193).
     const staleness = getStateManager().getStateStaleness();
     if (staleness) {

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/core/index.d.ts

@@ -2,7 +2,7 @@
  * Core module exports
  * Re-exports all core functionality for convenient imports
  */
-export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, type GistPersistenceStatus, maybeCheckpoint, resetStateManager, type Stats, } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, bootstrapGistBestEffort, type GistPersistenceStatus, maybeCheckpoint, resetStateManager, type Stats, } from './state.js';
 export { GistStateStore } from './gist-state-store.js';
 export { guidelinesFilename, repoFromGuidelinesFilename, GUIDELINES_FILE_PREFIX, GUIDELINES_MAX_BYTES, GuidelinesNotAvailableError, GuidelinesTooLargeError, } from './guidelines-store.js';
 export { PRMonitor, type PRCheckFailure, type FetchPRsResult, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';

package/dist/core/index.js

@@ -2,7 +2,7 @@
  * Core module exports
  * Re-exports all core functionality for convenient imports
  */
-export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, maybeCheckpoint, resetStateManager, } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, bootstrapGistBestEffort, maybeCheckpoint, resetStateManager, } from './state.js';
 export { GistStateStore } from './gist-state-store.js';
 export { guidelinesFilename, repoFromGuidelinesFilename, GUIDELINES_FILE_PREFIX, GUIDELINES_MAX_BYTES, GuidelinesNotAvailableError, GuidelinesTooLargeError, } from './guidelines-store.js';
 export { PRMonitor, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';

package/dist/core/state.d.ts

@@ -456,6 +456,25 @@ export type GistPersistenceStatus =
  * to local-only (transient network failure). A later call may recover. */
  | 'degraded';
 export declare function ensureGistPersistence(token: string | null): Promise<GistPersistenceStatus>;
+/**
+ * Best-effort gist bootstrap for entry points WITHOUT the auth gate (#1431):
+ * the CLI's localOnly commands (shelve/move/dismiss/override/config/setup/...)
+ * skip token enforcement, but a gist-configured user's mutations must still
+ * reach the Gist — their maybeCheckpoint calls silently no-op when the
+ * singleton never bootstrapped.
+ *
+ * Returns a human-readable LOCAL-ONLY warning when the process will write
+ * local-only despite a gist config, or null when no warning is needed
+ * (local mode, or gist mode successfully activated).
+ *
+ * Ordering: peek first with no token (zero spawn cost for genuinely-local
+ * users), fetch a token only when the config asks for gist. Hard
+ * ConfigurationErrors are converted to a warning instead of thrown — the
+ * localOnly set includes config/setup, the very commands needed to REPAIR a
+ * broken gist setup, so they must not be bricked by it. (The auth-gated
+ * path keeps throwing per #1202.)
+ */
+export declare function bootstrapGistBestEffort(fetchToken: () => Promise<string | null>): Promise<string | null>;
 /**
  * Reset the singleton StateManager instance to null. Intended for test isolation.
  */

package/dist/core/state.js

@@ -1000,6 +1000,49 @@ export async function ensureGistPersistence(token) {
     const mgr = await getStateManagerAsync(token);
     return mgr.isGistMode() ? 'gist' : 'degraded';
 }
+/**
+ * Best-effort gist bootstrap for entry points WITHOUT the auth gate (#1431):
+ * the CLI's localOnly commands (shelve/move/dismiss/override/config/setup/...)
+ * skip token enforcement, but a gist-configured user's mutations must still
+ * reach the Gist — their maybeCheckpoint calls silently no-op when the
+ * singleton never bootstrapped.
+ *
+ * Returns a human-readable LOCAL-ONLY warning when the process will write
+ * local-only despite a gist config, or null when no warning is needed
+ * (local mode, or gist mode successfully activated).
+ *
+ * Ordering: peek first with no token (zero spawn cost for genuinely-local
+ * users), fetch a token only when the config asks for gist. Hard
+ * ConfigurationErrors are converted to a warning instead of thrown — the
+ * localOnly set includes config/setup, the very commands needed to REPAIR a
+ * broken gist setup, so they must not be bricked by it. (The auth-gated
+ * path keeps throwing per #1202.)
+ */
+export async function bootstrapGistBestEffort(fetchToken) {
+    let reason = null;
+    try {
+        let status = await ensureGistPersistence(null);
+        if (status === 'no-token') {
+            status = await ensureGistPersistence(await fetchToken());
+        }
+        if (status === 'no-token')
+            reason = 'no GitHub token is available';
+        else if (status === 'state-unreadable')
+            reason = 'the state file could not be read';
+        else if (status === 'degraded')
+            reason = 'Gist initialization hit a transient network failure';
+    }
+    catch (err) {
+        reason =
+            err instanceof ConfigurationError
+                ? `Gist initialization failed (${errorMessage(err)}) — fix the Gist setup (check the token's gist scope, or run state-show / setup) before relying on sync`
+                : `Gist initialization failed: ${errorMessage(err)}`;
+    }
+    if (reason === null)
+        return null;
+    return (`Gist persistence is configured but ${reason} — changes made by this command are ` +
+        'LOCAL-ONLY and may be overwritten by the next successful Gist sync.');
+}
 /**
  * Reset the singleton StateManager instance to null. Intended for test isolation.
  */

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).
  *
@@ -51,7 +60,7 @@ export interface CompactRepoGroup {
  * See `DailyWarning` and issue #1042 for the rationale — keeping this a
  * fixed union so downstream consumers can switch on it without drift.
  */
-export type DailyWarningPhase = 'fetch' | 'repo-scores' | 'analytics' | 'scout-sync' | 'partition' | 'dismiss-filter' | 'gist-checkpoint' | 'gist-staleness' | 'state-load';
+export type DailyWarningPhase = 'fetch' | 'repo-scores' | 'analytics' | 'scout-sync' | 'partition' | 'dismiss-filter' | 'gist-init' | 'gist-checkpoint' | 'gist-staleness' | 'state-load';
 /**
  * A single non-fatal failure surfaced from the `daily` pipeline. Unlike
  * `PRCheckFailure` (which is scoped to per-PR fetch errors), this covers
@@ -179,6 +188,7 @@ export declare const StatusOutputSchema: z.ZodObject<{
             "scout-sync": "scout-sync";
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
+            "gist-init": "gist-init";
             "gist-checkpoint": "gist-checkpoint";
             "gist-staleness": "gist-staleness";
             "state-load": "state-load";
@@ -394,6 +404,7 @@ export declare const DailyOutputSchema: z.ZodObject<{
             "scout-sync": "scout-sync";
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
+            "gist-init": "gist-init";
             "gist-checkpoint": "gist-checkpoint";
             "gist-staleness": "gist-staleness";
             "state-load": "state-load";
@@ -541,6 +552,7 @@ export declare const CompactDailyOutputSchema: z.ZodObject<{
             "scout-sync": "scout-sync";
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
+            "gist-init": "gist-init";
             "gist-checkpoint": "gist-checkpoint";
             "gist-staleness": "gist-staleness";
             "state-load": "state-load";

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',
@@ -90,6 +99,7 @@ const DailyWarningPhaseSchema = z.enum([
     'scout-sync',
     'partition',
     'dismiss-filter',
+    'gist-init',
     'gist-checkpoint',
     'gist-staleness',
     'state-load',
@@ -728,6 +738,7 @@ export function jsonSuccess(data) {
         success: true,
         data,
         timestamp: new Date().toISOString(),
+        ...(envelopeGistWarning ? { gistInitWarning: envelopeGistWarning } : {}),
     };
 }
 /**
@@ -739,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.2",
+  "version": "3.13.4",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {