@oss-autopilot/core 3.2.0 → 3.4.0

package/dist/core/auth.js

@@ -6,9 +6,9 @@
  *
  * Extracted from utils.ts under #1116.
  */
-import { execFileSync, execFile } from 'child_process';
+import { execFileSync, execFile } from 'node:child_process';
 import { ConfigurationError } from './errors.js';
-import { debug } from './logger.js';
+import { debug, warn } from './logger.js';
 const MODULE = 'auth';
 // Cached GitHub token (fetched once per session)
 let cachedGitHubToken = null;
@@ -36,7 +36,7 @@ export function getGitHubToken() {
     }
     try {
         const token = execFileSync('gh', ['auth', 'token'], {
-            encoding: 'utf-8',
+            encoding: 'utf8',
             stdio: ['pipe', 'pipe', 'pipe'],
             timeout: 2000,
         }).trim();
@@ -47,7 +47,10 @@ export function getGitHubToken() {
         }
     }
     catch (err) {
-        debug(MODULE, 'gh auth token failed (CLI unavailable or not authenticated)', err);
+        // Promote to warn-once-per-session so a slow `gh` (2s timeout) or a
+        // misconfigured CLI is visible without DEBUG=1 (#1209 L6). The
+        // tokenFetchAttempted cache means subsequent calls don't re-warn.
+        warn(MODULE, `gh auth token failed (CLI unavailable or not authenticated): ${err instanceof Error ? err.message : String(err)}`);
     }
     return null;
 }
@@ -101,7 +104,7 @@ export async function getGitHubTokenAsync() {
     }
     try {
         const token = await new Promise((resolve, reject) => {
-            execFile('gh', ['auth', 'token'], { encoding: 'utf-8', timeout: 2000 }, (error, stdout) => {
+            execFile('gh', ['auth', 'token'], { encoding: 'utf8', timeout: 2000 }, (error, stdout) => {
                 if (error) {
                     reject(error);
                 }
@@ -117,7 +120,8 @@ export async function getGitHubTokenAsync() {
         }
     }
     catch (err) {
-        debug(MODULE, 'gh auth token failed (CLI unavailable or not authenticated)', err);
+        // Same warn-once promotion as the sync version (#1209 L6).
+        warn(MODULE, `gh auth token failed (CLI unavailable or not authenticated): ${err instanceof Error ? err.message : String(err)}`);
     }
     return null;
 }
@@ -126,7 +130,7 @@ export async function getGitHubTokenAsync() {
  * Usernames must start with an alphanumeric character, can contain hyphens
  * (but not consecutive ones and not at the end), and be 1-39 characters.
  */
-const GITHUB_USERNAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/;
+const GITHUB_USERNAME_RE = /^[\da-z](?:[\da-z]|-(?=[\da-z])){0,38}$/i;
 /**
  * Detect the authenticated GitHub username via the `gh` CLI.
  *
@@ -137,7 +141,7 @@ const GITHUB_USERNAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/
 export async function detectGitHubUsername() {
     try {
         const login = await new Promise((resolve, reject) => {
-            execFile('gh', ['api', 'user', '--jq', '.login'], { encoding: 'utf-8', timeout: 5000 }, (error, stdout) => {
+            execFile('gh', ['api', 'user', '--jq', '.login'], { encoding: 'utf8', timeout: 5000 }, (error, stdout) => {
                 if (error) {
                     reject(error);
                 }

package/dist/core/daily-logic.d.ts

@@ -14,7 +14,7 @@
  * re-exports them at the bottom so existing imports keep working without
  * a sweep.
  */
-import type { FetchedPR, FetchedPRStatus, StalenessTier, ActionReason, AgentState, ShelvedPRRef, ComputedRepoSignals, RepoGroup, CommentedIssue, CapacityAssessment, ActionableIssue, ActionMenu } from './types.js';
+import type { FetchedPR, FetchedPRStatus, StalenessTier, ActionReason, AgentState, ShelvedPRRef, ComputedRepoSignals, RepoGroup, CommentedIssue, CapacityAssessment, ActionableIssue, ActionMenu, StarFilter } from './types.js';
 /**
  * Statuses indicating action needed from the contributor.
  * Used for auto-unshelving shelved PRs.
@@ -49,6 +49,18 @@ export declare function applyStatusOverrides(prs: FetchedPR[], state: Readonly<A
  * @returns Lightweight reference for display
  */
 export declare function toShelvedPRRef(pr: ShelvedPRRef): ShelvedPRRef;
+/**
+ * Build a star filter from state for use in fetchUserPRCounts.
+ *
+ * Returns undefined if no star data is available (first run). Pure logic
+ * over `Readonly<AgentState>` — lives here in core/daily-logic.ts so the
+ * dashboard layer can reuse it without importing from a sibling command
+ * module (#1208 M7).
+ *
+ * @param state - Current agent state (read-only)
+ * @returns Star filter with minimum threshold and known counts, or undefined on first run
+ */
+export declare function buildStarFilter(state: Readonly<AgentState>): StarFilter | undefined;
 /**
  * Group PRs by repository (#80).
  * Ensures one agent per repo during parallel dispatch, preventing branch checkout conflicts.

package/dist/core/daily-logic.js

@@ -129,6 +129,29 @@ export function toShelvedPRRef(pr) {
         status: pr.status,
     };
 }
+/**
+ * Build a star filter from state for use in fetchUserPRCounts.
+ *
+ * Returns undefined if no star data is available (first run). Pure logic
+ * over `Readonly<AgentState>` — lives here in core/daily-logic.ts so the
+ * dashboard layer can reuse it without importing from a sibling command
+ * module (#1208 M7).
+ *
+ * @param state - Current agent state (read-only)
+ * @returns Star filter with minimum threshold and known counts, or undefined on first run
+ */
+export function buildStarFilter(state) {
+    const minStars = state.config.minStars ?? 50;
+    const knownStarCounts = new Map();
+    for (const [repo, score] of Object.entries(state.repoScores)) {
+        if (score.stargazersCount !== undefined) {
+            knownStarCounts.set(repo, score.stargazersCount);
+        }
+    }
+    if (knownStarCounts.size === 0)
+        return undefined;
+    return { minStars, knownStarCounts };
+}
 /**
  * Group PRs by repository (#80).
  * Ensures one agent per repo during parallel dispatch, preventing branch checkout conflicts.
@@ -232,37 +255,41 @@ export function collectActionableIssues(prs, lastDigestAt) {
             let label;
             let type;
             switch (reason) {
-                case 'needs_response':
+                case 'needs_response': {
                     label = '[Needs Response]';
                     type = 'needs_response';
                     break;
-                case 'needs_changes':
+                }
+                case 'needs_changes': {
                     label = '[Needs Changes]';
                     type = 'needs_changes';
                     break;
+                }
                 case 'failing_ci': {
                     const checkInfo = pr.failingCheckNames.length > 0 ? ` (${pr.failingCheckNames.join(', ')})` : '';
                     label = `[CI Failing${checkInfo}]`;
                     type = 'ci_failing';
                     break;
                 }
-                case 'merge_conflict':
+                case 'merge_conflict': {
                     label = '[Merge Conflict]';
                     type = 'merge_conflict';
                     break;
+                }
                 case 'incomplete_checklist': {
                     const stats = pr.checklistStats ? ` (${pr.checklistStats.checked}/${pr.checklistStats.total})` : '';
                     label = `[Incomplete Checklist${stats}]`;
                     type = 'incomplete_checklist';
                     break;
                 }
-                default:
+                default: {
                     // Defensive fallback for ActionReason values not explicitly handled
                     // above (e.g. ci_not_running, needs_rebase, missing_required_files).
                     // These aren't in reasonOrder today but this guards future additions.
                     warn('daily-logic', `Unhandled ActionReason "${reason}" for PR ${pr.url} — falling back to needs_response`);
                     label = `[${reason}]`;
                     type = 'needs_response';
+                }
             }
             // A PR is "new" if it was created after the last daily digest (first time seen).
             // If there's no previous digest (first run) or createdAt is invalid, assume new.

package/dist/core/dates.js

@@ -30,9 +30,9 @@ export function formatRelativeTime(dateStr) {
     const diffMs = Date.now() - date.getTime();
     if (diffMs < 0)
         return 'just now';
-    const diffMins = Math.floor(diffMs / 60000);
-    const diffHours = Math.floor(diffMs / 3600000);
-    const diffDays = Math.floor(diffMs / 86400000);
+    const diffMins = Math.floor(diffMs / 60_000);
+    const diffHours = Math.floor(diffMs / 3_600_000);
+    const diffDays = Math.floor(diffMs / 86_400_000);
     if (diffMins < 60)
         return `${diffMins}m ago`;
     if (diffHours < 24)

package/dist/core/errors.d.ts

@@ -32,6 +32,20 @@ export declare class ValidationError extends OssAutopilotError {
 export declare class GistPermissionError extends ConfigurationError {
     constructor(message?: string);
 }
+/**
+ * Thrown when state.json fetched from a Gist is malformed or fails Zod
+ * validation. The Gist content is preserved as a `.rejected-<ts>.json` file
+ * in the local cache directory so the user can inspect or recover from it
+ * before the next push overwrites the Gist with fresh state.
+ *
+ * See issue #1201.
+ */
+export declare class GistCorruptError extends ConfigurationError {
+    readonly gistId: string;
+    readonly rejectedPath: string | null;
+    readonly cause: unknown;
+    constructor(gistId: string, rejectedPath: string | null, cause: unknown);
+}
 /**
  * Thrown when an optimistic compare-and-swap on state.json detects that
  * another process wrote the file between load and save. See issue #1030.
@@ -73,6 +87,21 @@ export declare function getHttpStatusCode(error: unknown): number | undefined;
 export declare function isRateLimitError(error: unknown): boolean;
 /** Return true for errors that should propagate (not degrade gracefully): rate limits, auth failures, abuse detection. */
 export declare function isRateLimitOrAuthError(err: unknown): boolean;
+/**
+ * Check if an error is a transient network/server-side failure that's safe
+ * to retry or fall back from (vs. a permanent error that should surface).
+ *
+ * Returns true for:
+ * - Node socket errors: ECONNRESET, ETIMEDOUT, ENETUNREACH, ENOTFOUND, ECONNREFUSED
+ * - HTTP 5xx (server errors)
+ * - AbortError (timeout)
+ *
+ * Returns false for everything else (including 4xx, schema errors, config errors).
+ *
+ * Used by {@link getStateManagerAsync} to decide whether a Gist init failure
+ * is recoverable enough to silently fall back to local-only mode (#1202).
+ */
+export declare function isTransientNetworkError(err: unknown): boolean;
 /**
  * Build a `.catch()` handler for the "non-fatal parallel fetch" pattern used
  * by daily.ts and dashboard-data.ts (#960). When a sibling fetch fails during

package/dist/core/errors.js

@@ -49,6 +49,31 @@ export class GistPermissionError extends ConfigurationError {
         this.name = 'GistPermissionError';
     }
 }
+/**
+ * Thrown when state.json fetched from a Gist is malformed or fails Zod
+ * validation. The Gist content is preserved as a `.rejected-<ts>.json` file
+ * in the local cache directory so the user can inspect or recover from it
+ * before the next push overwrites the Gist with fresh state.
+ *
+ * See issue #1201.
+ */
+export class GistCorruptError extends ConfigurationError {
+    gistId;
+    rejectedPath;
+    cause;
+    constructor(gistId, rejectedPath, cause) {
+        const causeMsg = cause instanceof Error ? cause.message : String(cause);
+        const recoverHint = rejectedPath
+            ? `\nCorrupt content preserved at: ${rejectedPath}\n` +
+                'Inspect or restore manually, then re-run. Falling back to a fresh state would overwrite your Gist.'
+            : '\nCould not preserve the rejected content; do not push without inspecting the Gist manually.';
+        super(`Gist ${gistId} state.json is corrupt or fails schema validation: ${causeMsg}${recoverHint}`);
+        this.gistId = gistId;
+        this.rejectedPath = rejectedPath;
+        this.cause = cause;
+        this.name = 'GistCorruptError';
+    }
+}
 /**
  * Thrown when an optimistic compare-and-swap on state.json detects that
  * another process wrote the file between load and save. See issue #1030.
@@ -128,6 +153,44 @@ export function isRateLimitOrAuthError(err) {
     }
     return false;
 }
+/**
+ * Check if an error is a transient network/server-side failure that's safe
+ * to retry or fall back from (vs. a permanent error that should surface).
+ *
+ * Returns true for:
+ * - Node socket errors: ECONNRESET, ETIMEDOUT, ENETUNREACH, ENOTFOUND, ECONNREFUSED
+ * - HTTP 5xx (server errors)
+ * - AbortError (timeout)
+ *
+ * Returns false for everything else (including 4xx, schema errors, config errors).
+ *
+ * Used by {@link getStateManagerAsync} to decide whether a Gist init failure
+ * is recoverable enough to silently fall back to local-only mode (#1202).
+ */
+export function isTransientNetworkError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const status = getHttpStatusCode(err);
+    if (typeof status === 'number' && status >= 500 && status < 600)
+        return true;
+    // Node socket-level errors expose `code`
+    const code = err.code;
+    if (typeof code === 'string') {
+        if (code === 'ECONNRESET' ||
+            code === 'ETIMEDOUT' ||
+            code === 'ENETUNREACH' ||
+            code === 'ENOTFOUND' ||
+            code === 'ECONNREFUSED' ||
+            code === 'EAI_AGAIN') {
+            return true;
+        }
+    }
+    // Octokit's RequestError surfaces the underlying name; fetch timeout is AbortError
+    const name = err.name;
+    if (typeof name === 'string' && (name === 'AbortError' || name === 'TimeoutError'))
+        return true;
+    return false;
+}
 /**
  * Build a `.catch()` handler for the "non-fatal parallel fetch" pattern used
  * by daily.ts and dashboard-data.ts (#960). When a sibling fetch fails during

package/dist/core/formatter-detection.js

@@ -4,8 +4,8 @@
  * Programmatically detects formatters/linters configured in a local repo directory
  * and diagnoses CI formatting failures from log output.
  */
-import * as fs from 'fs';
-import * as path from 'path';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { debug } from './logger.js';
 const MODULE = 'formatter-detection';
 // ── Prettier config file patterns ──────────────────────────────────────────
@@ -42,7 +42,7 @@ const FORMAT_SCRIPT_NAMES = ['lint:fix', 'format', 'fmt', 'lint', 'format:check'
 const CI_PATTERNS = [
     {
         formatter: 'prettier',
-        patterns: [/Code style issues found/i, /Forgot to run Prettier/i, /prettier --check/i],
+        patterns: [/code style issues found/i, /forgot to run prettier/i, /prettier --check/i],
     },
     {
         formatter: 'ruff',
@@ -50,19 +50,19 @@ const CI_PATTERNS = [
     },
     {
         formatter: 'black',
-        patterns: [/Oh no! .* files? would be reformatted/i, /black --check/i],
+        patterns: [/oh no! .* files? would be reformatted/i, /black --check/i],
     },
     {
         formatter: 'rustfmt',
-        patterns: [/Diff in .*\.rs/i, /rustfmt --check/i, /cargo fmt.*--check/i],
+        patterns: [/diff in .*\.rs/i, /rustfmt --check/i, /cargo fmt.*--check/i],
     },
     {
         formatter: 'biome',
-        patterns: [/biome check/i, /biome ci/i, /Found \d+ fixable diagnostics?/i],
+        patterns: [/biome check/i, /biome ci/i, /found \d+ fixable diagnostics?/i],
     },
     {
         formatter: 'eslint',
-        patterns: [/eslint.*--fix/i, /eslint.*\d+ problems?/i],
+        patterns: [/eslint.*--fix/i, /eslint\D+\d+ problems?/i],
     },
     {
         formatter: 'gofmt',
@@ -82,7 +82,7 @@ const CI_PATTERNS = [
  */
 function readJsonFile(filePath) {
     try {
-        const content = fs.readFileSync(filePath, 'utf-8');
+        const content = fs.readFileSync(filePath, 'utf8');
         return JSON.parse(content);
     }
     catch (err) {
@@ -95,7 +95,7 @@ function readJsonFile(filePath) {
  */
 function readTextFile(filePath) {
     try {
-        return fs.readFileSync(filePath, 'utf-8');
+        return fs.readFileSync(filePath, 'utf8');
     }
     catch (err) {
         debug(MODULE, `Failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/core/gist-state-store.d.ts

@@ -44,6 +44,22 @@ export interface BootstrapResult {
     /** True when state was loaded from local cache due to API failure. */
     degraded?: boolean;
 }
+/**
+ * Discriminated outcome of {@link GistStateStore.refreshFromGist} (#1209 L9).
+ * Lets callers distinguish "got fresh data" from "throttled / no-op / failed"
+ * without conflating them as a single boolean.
+ */
+export type RefreshResult = {
+    status: 'refreshed';
+} | {
+    status: 'no-gist';
+} | {
+    status: 'throttled';
+    sinceLastMs: number;
+} | {
+    status: 'error';
+    error: Error;
+};
 /**
  * Minimal Octokit-shaped interface for the Gist API methods we use.
  * Accepts the real ThrottledOctokit or a plain mock object in tests.
@@ -121,6 +137,14 @@ export declare class GistStateStore {
     private readonly octokit;
     private lastRefreshAt;
     private static readonly REFRESH_THROTTLE_MS;
+    /**
+     * Most recent error from a `refreshFromGist()` attempt, or `null` when the
+     * last attempt succeeded or was skipped by the throttle. Lets callers
+     * (StateManager) distinguish "throttled, nothing new to see" from "fetch
+     * failed, you're now operating on stale state" without changing the
+     * existing boolean return contract (#1193).
+     */
+    lastRefreshError: Error | null;
     constructor(octokit: OctokitLike);
     /**
      * Bootstrap the Gist store: locate or create the backing Gist,
@@ -186,8 +210,15 @@ export declare class GistStateStore {
     /**
      * Re-fetch the Gist and update the in-memory cache.
      * Throttled to at most once per 30 seconds.
+     *
+     * Returns a discriminated union so callers can tell apart the four
+     * outcomes that previously collapsed into a single boolean (#1209 L9):
+     *   - `{ status: 'refreshed' }` — fresh data loaded successfully.
+     *   - `{ status: 'no-gist' }` — store not in Gist mode (e.g. degraded).
+     *   - `{ status: 'throttled', sinceLastMs }` — within the 30s throttle.
+     *   - `{ status: 'error', error }` — fetch attempt failed.
      */
-    refreshFromGist(): Promise<boolean>;
+    refreshFromGist(): Promise<RefreshResult>;
     /**
      * Preflight check: verify the token has Gist API scope.
      * Costs one cheap API call; catches permission issues early with a clear message.
@@ -199,9 +230,17 @@ export declare class GistStateStore {
      */
     private fetchAndCache;
     /**
-     * Parse `state.json` from the in-memory cache. Handles v2 migration
+     * Parse `state.json` from the in-memory cache. Handles v1→v4 migration
      * by running through the Zod schema (which requires version: 4).
-     * Falls back to fresh state if the file is missing or unparseable.
+     *
+     * Throws {@link GistCorruptError} on parse or schema-validation failure.
+     * The corrupt raw content is preserved as `<state-cache-path>.rejected-<ts>`
+     * so the caller can recover (#1201).
+     *
+     * Returning fresh state on failure (the previous behavior) is unsafe in
+     * Gist mode because the next `push()` would overwrite the Gist with the
+     * empty fallback, silently destroying repoScores, dismissedIssues,
+     * guidelines pointers, and digest history.
      */
     private parseStateFromCache;
     /**

package/dist/core/gist-state-store.js

@@ -31,12 +31,12 @@
  *  cells, which matches the "last-write-wins by intent" model the rest of
  *  oss-autopilot already assumes for state.json.
  */
-import * as fs from 'fs';
+import * as fs from 'node:fs';
 import { AgentStateSchema } from './state-schema.js';
 import { atomicWriteFileSync, createFreshState, migrateV1ToV2, migrateV2ToV3, migrateV3ToV4, } from './state-persistence.js';
 import { getGistIdPath, getStateCachePath } from './paths.js';
 import { debug, warn } from './logger.js';
-import { GistPermissionError, GistConcurrencyError, isRateLimitError } from './errors.js';
+import { GistPermissionError, GistConcurrencyError, GistCorruptError, isRateLimitError } from './errors.js';
 const MODULE = 'gist-store';
 /**
  * Extract the ETag header from an Octokit response, tolerating both lower-
@@ -48,6 +48,24 @@ function extractEtag(headers) {
         return null;
     return headers.etag ?? headers.ETag ?? null;
 }
+/**
+ * Preserve corrupt Gist content for user recovery. Returns the path written,
+ * or null if the preservation itself failed (logged at warn). Mirrors the
+ * pattern in state-persistence.ts:401-407 for the local-state path.
+ *
+ * See {@link GistCorruptError} and issue #1201.
+ */
+function preserveRejectedGistContent(raw, gistId) {
+    try {
+        const rejectedPath = `${getStateCachePath()}.rejected-${Date.now()}`;
+        fs.writeFileSync(rejectedPath, raw, { encoding: 'utf8', mode: 0o600 });
+        return rejectedPath;
+    }
+    catch (err) {
+        warn(MODULE, `Could not preserve rejected Gist content for ${gistId}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
 /** Well-known Gist description used for search-based discovery. */
 export const GIST_DESCRIPTION = 'oss-autopilot-state';
 /** Primary state file name inside the Gist. */
@@ -70,6 +88,14 @@ export class GistStateStore {
     octokit;
     lastRefreshAt = 0;
     static REFRESH_THROTTLE_MS = 30_000;
+    /**
+     * Most recent error from a `refreshFromGist()` attempt, or `null` when the
+     * last attempt succeeded or was skipped by the throttle. Lets callers
+     * (StateManager) distinguish "throttled, nothing new to see" from "fetch
+     * failed, you're now operating on stale state" without changing the
+     * existing boolean return contract (#1193).
+     */
+    lastRefreshError = null;
     constructor(octokit) {
         this.octokit = octokit;
     }
@@ -116,10 +142,12 @@ export class GistStateStore {
             // All API paths failed — enter degraded mode
             warn(MODULE, 'All Gist API paths failed, entering degraded mode', err);
             // Try reading from local cache file
+            const cachePath = getStateCachePath();
+            let cacheRaw = null;
             try {
-                const cachePath = getStateCachePath();
                 if (fs.existsSync(cachePath)) {
-                    let obj = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+                    cacheRaw = fs.readFileSync(cachePath, 'utf8');
+                    let obj = JSON.parse(cacheRaw);
                     // Chain migrations
                     if (typeof obj === 'object' && obj !== null) {
                         const record = obj;
@@ -136,7 +164,16 @@ export class GistStateStore {
                 }
             }
             catch (cacheErr) {
-                debug(MODULE, `Failed to read local cache in degraded mode: ${cacheErr}`);
+                // Promote to warn (#1201) and preserve corrupt cache so fresh-state
+                // fallback doesn't silently destroy recoverable data on next push.
+                if (cacheRaw) {
+                    const rejectedPath = preserveRejectedGistContent(cacheRaw, 'local-cache');
+                    warn(MODULE, `Local state cache failed to parse in degraded mode: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}. ` +
+                        `Corrupt cache preserved at: ${rejectedPath ?? '(could not preserve)'}`);
+                }
+                else {
+                    warn(MODULE, `Failed to read local cache in degraded mode: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}`);
+                }
             }
             // No cache either — return fresh state in degraded mode
             debug(MODULE, 'No local cache found, returning fresh state in degraded mode');
@@ -188,10 +225,12 @@ export class GistStateStore {
             // All API paths failed — enter degraded mode
             warn(MODULE, 'bootstrapWithMigration: all Gist API paths failed, entering degraded mode', err);
             // Try reading from local cache file
+            const cachePath = getStateCachePath();
+            let cacheRaw = null;
             try {
-                const cachePath = getStateCachePath();
                 if (fs.existsSync(cachePath)) {
-                    let obj = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+                    cacheRaw = fs.readFileSync(cachePath, 'utf8');
+                    let obj = JSON.parse(cacheRaw);
                     // Chain migrations
                     if (typeof obj === 'object' && obj !== null) {
                         const record = obj;
@@ -208,7 +247,14 @@ export class GistStateStore {
                 }
             }
             catch (cacheErr) {
-                debug(MODULE, `bootstrapWithMigration: failed to read local cache in degraded mode: ${cacheErr}`);
+                if (cacheRaw) {
+                    const rejectedPath = preserveRejectedGistContent(cacheRaw, 'local-cache');
+                    warn(MODULE, `bootstrapWithMigration: local cache failed to parse: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}. ` +
+                        `Corrupt cache preserved at: ${rejectedPath ?? '(could not preserve)'}`);
+                }
+                else {
+                    warn(MODULE, `bootstrapWithMigration: failed to read local cache: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}`);
+                }
             }
             // No cache either — use the provided existingState in degraded mode
             debug(MODULE, 'bootstrapWithMigration: no local cache found, returning existing state in degraded mode');
@@ -376,21 +422,35 @@ export class GistStateStore {
     /**
      * Re-fetch the Gist and update the in-memory cache.
      * Throttled to at most once per 30 seconds.
+     *
+     * Returns a discriminated union so callers can tell apart the four
+     * outcomes that previously collapsed into a single boolean (#1209 L9):
+     *   - `{ status: 'refreshed' }` — fresh data loaded successfully.
+     *   - `{ status: 'no-gist' }` — store not in Gist mode (e.g. degraded).
+     *   - `{ status: 'throttled', sinceLastMs }` — within the 30s throttle.
+     *   - `{ status: 'error', error }` — fetch attempt failed.
      */
     async refreshFromGist() {
         if (!this.gistId)
-            return false;
+            return { status: 'no-gist' };
         const now = Date.now();
-        if (now - this.lastRefreshAt < GistStateStore.REFRESH_THROTTLE_MS)
-            return false;
+        const sinceLastMs = now - this.lastRefreshAt;
+        // Throttle hits are not failures — preserve any previous lastRefreshError
+        // for the caller to inspect.
+        if (sinceLastMs < GistStateStore.REFRESH_THROTTLE_MS) {
+            return { status: 'throttled', sinceLastMs };
+        }
         try {
             await this.fetchAndCache(this.gistId);
             this.lastRefreshAt = now;
-            return true;
+            this.lastRefreshError = null;
+            return { status: 'refreshed' };
         }
         catch (err) {
-            warn(MODULE, `refreshFromGist failed: ${err}`);
-            return false;
+            const error = err instanceof Error ? err : new Error(String(err));
+            warn(MODULE, `refreshFromGist failed: ${error.message}`);
+            this.lastRefreshError = error;
+            return { status: 'error', error };
         }
     }
     // ── Private helpers ─────────────────────────────────────────────────
@@ -436,9 +496,17 @@ export class GistStateStore {
         return state;
     }
     /**
-     * Parse `state.json` from the in-memory cache. Handles v2 migration
+     * Parse `state.json` from the in-memory cache. Handles v1→v4 migration
      * by running through the Zod schema (which requires version: 4).
-     * Falls back to fresh state if the file is missing or unparseable.
+     *
+     * Throws {@link GistCorruptError} on parse or schema-validation failure.
+     * The corrupt raw content is preserved as `<state-cache-path>.rejected-<ts>`
+     * so the caller can recover (#1201).
+     *
+     * Returning fresh state on failure (the previous behavior) is unsafe in
+     * Gist mode because the next `push()` would overwrite the Gist with the
+     * empty fallback, silently destroying repoScores, dismissedIssues,
+     * guidelines pointers, and digest history.
      */
     parseStateFromCache() {
         const raw = this.cachedFiles.get(STATE_FILE_NAME);
@@ -461,8 +529,10 @@ export class GistStateStore {
             return AgentStateSchema.parse(obj);
         }
         catch (err) {
-            warn(MODULE, `Failed to parse state.json from Gist: ${err}`);
-            return createFreshState();
+            const rejectedPath = preserveRejectedGistContent(raw, this.gistId ?? 'unknown');
+            warn(MODULE, `Gist state.json failed to parse — refusing to overwrite with fresh state. ` +
+                `Corrupt content preserved at: ${rejectedPath ?? '(could not preserve)'}`);
+            throw new GistCorruptError(this.gistId ?? 'unknown', rejectedPath, err);
         }
     }
     /**
@@ -541,7 +611,7 @@ export class GistStateStore {
         try {
             const gistIdPath = getGistIdPath();
             if (fs.existsSync(gistIdPath)) {
-                const id = fs.readFileSync(gistIdPath, 'utf-8').trim();
+                const id = fs.readFileSync(gistIdPath, 'utf8').trim();
                 return id || null;
             }
         }

package/dist/core/guidelines-store.js

@@ -2,7 +2,7 @@ import { OssAutopilotError } from './errors.js';
 /** Filename prefix shared by every guidelines file in the Gist. */
 export const GUIDELINES_FILE_PREFIX = 'guidelines--';
 /** Hard byte budget for a single guidelines file (#867 design log §1). */
-export const GUIDELINES_MAX_BYTES = 8_192;
+export const GUIDELINES_MAX_BYTES = 8192;
 /** Suffix appended to the filename so it renders as markdown in Gist. */
 const GUIDELINES_FILE_SUFFIX = '.md';
 /**
@@ -83,7 +83,7 @@ export function getGuidelines(store, repo) {
 export function setGuidelines(store, repo, content) {
     if (!store)
         throw new GuidelinesNotAvailableError();
-    const byteSize = Buffer.byteLength(content, 'utf-8');
+    const byteSize = Buffer.byteLength(content, 'utf8');
     if (byteSize > GUIDELINES_MAX_BYTES) {
         throw new GuidelinesTooLargeError(byteSize);
     }