@oss-autopilot/core 3.2.0 → 3.3.0

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

@@ -121,6 +121,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,
@@ -199,9 +207,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');
@@ -381,15 +427,19 @@ export class GistStateStore {
         if (!this.gistId)
             return false;
         const now = Date.now();
+        // Throttle hits are not failures — preserve any previous lastRefreshError
+        // for the caller to inspect.
         if (now - this.lastRefreshAt < GistStateStore.REFRESH_THROTTLE_MS)
             return false;
         try {
             await this.fetchAndCache(this.gistId);
             this.lastRefreshAt = now;
+            this.lastRefreshError = null;
             return true;
         }
         catch (err) {
             warn(MODULE, `refreshFromGist failed: ${err}`);
+            this.lastRefreshError = err instanceof Error ? err : new Error(String(err));
             return false;
         }
     }
@@ -436,9 +486,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 +519,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 +601,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);
     }

package/dist/core/http-cache.js

@@ -9,9 +9,9 @@
  * for the same endpoint (e.g., star counts for two PRs in the same repo)
  * share a single HTTP round-trip.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as crypto from 'crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
 import { getCacheDir } from './paths.js';
 import { debug } from './logger.js';
 import { getHttpStatusCode } from './errors.js';
@@ -76,7 +76,7 @@ export class HttpCache {
     get(url) {
         const filePath = this.pathFor(url);
         try {
-            const raw = fs.readFileSync(filePath, 'utf-8');
+            const raw = fs.readFileSync(filePath, 'utf8');
             const entry = JSON.parse(raw);
             // Sanity-check: the file should contain the URL we asked for
             if (entry.url !== url) {
@@ -100,7 +100,7 @@ export class HttpCache {
             cachedAt: new Date().toISOString(),
         };
         try {
-            fs.writeFileSync(this.pathFor(url), JSON.stringify(entry), { encoding: 'utf-8', mode: 0o600 });
+            fs.writeFileSync(this.pathFor(url), JSON.stringify(entry), { encoding: 'utf8', mode: 0o600 });
             debug(MODULE, `Cached response for ${url}`);
             // Best-effort size cap (#1057 M27). Runs after each write rather than on
             // a schedule so long-lived sessions can't accumulate past the cap.
@@ -191,7 +191,7 @@ export class HttpCache {
                     continue;
                 const filePath = path.join(this.cacheDir, file);
                 try {
-                    const raw = fs.readFileSync(filePath, 'utf-8');
+                    const raw = fs.readFileSync(filePath, 'utf8');
                     const entry = JSON.parse(raw);
                     const age = now - new Date(entry.cachedAt).getTime();
                     if (age > maxAgeMs) {

package/dist/core/index.d.ts

@@ -8,6 +8,7 @@ export { guidelinesFilename, repoFromGuidelinesFilename, GUIDELINES_FILE_PREFIX,
 export { PRMonitor, type PRCheckFailure, type FetchPRsResult, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
 export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
+export { wrapUntrustedContent, extractFromFence, UNTRUSTED_OPEN_TAG_NAME, UNTRUSTED_CLOSE_TAG, type UntrustedContentMeta, } from './untrusted-content.js';
 export { getOctokit, checkRateLimit, type RateLimitInfo } from './github.js';
 export { parseGitHubUrl, splitRepo, isOwnRepo } from './urls.js';
 export { daysBetween, formatRelativeTime, byDateDescending } from './dates.js';

package/dist/core/index.js

@@ -9,6 +9,7 @@ export { PRMonitor, computeDisplayLabel, classifyCICheck, classifyFailingChecks,
 // Search/vetting now delegated to @oss-scout/core via commands/scout-bridge.ts
 export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
+export { wrapUntrustedContent, extractFromFence, UNTRUSTED_OPEN_TAG_NAME, UNTRUSTED_CLOSE_TAG, } from './untrusted-content.js';
 export { getOctokit, checkRateLimit } from './github.js';
 export { parseGitHubUrl, splitRepo, isOwnRepo } from './urls.js';
 export { daysBetween, formatRelativeTime, byDateDescending } from './dates.js';

package/dist/core/issue-conversation.js

@@ -151,7 +151,9 @@ export class IssueConversationMonitor {
                 body: comment.body || '',
                 createdAt: comment.created_at,
                 isUser: author.toLowerCase() === username.toLowerCase(),
-                authorAssociation: String(comment.author_association ?? ''),
+                authorAssociation: typeof comment.author_association === 'string'
+                    ? comment.author_association
+                    : '',
             });
         }
         timeline.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());

package/dist/core/paths.js

@@ -6,9 +6,9 @@
  *
  * Extracted from utils.ts under #1116.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
 /**
  * Returns the oss-autopilot data directory path, creating it if it does not exist.
  *
@@ -98,7 +98,7 @@ export function stateFileExists() {
 export function getCLIVersion() {
     try {
         const pkgPath = path.join(path.dirname(process.argv[1]), '..', 'package.json');
-        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+        return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version;
     }
     catch {
         return '0.0.0';

package/dist/core/pr-monitor.js

@@ -16,9 +16,8 @@ import { getOctokit } from './github.js';
 import { getStateManager } from './state.js';
 import { daysBetween } from './dates.js';
 import { parseGitHubUrl, extractOwnerRepo, isOwnRepo } from './urls.js';
-import { DEFAULT_CONCURRENCY } from './concurrency.js';
+import { DEFAULT_CONCURRENCY, runWorkerPool } from './concurrency.js';
 import { determineStatus } from './status-determination.js';
-import { runWorkerPool } from './concurrency.js';
 import { ConfigurationError, ValidationError, errorMessage, getHttpStatusCode, isRateLimitOrAuthError, } from './errors.js';
 import { paginateAll } from './pagination.js';
 import { debug, warn, timed } from './logger.js';

package/dist/core/pr-template.js

@@ -43,7 +43,7 @@ export async function fetchPRTemplate(octokit, owner, repo) {
                 debug(MODULE, `${path} has no content, skipping`);
                 continue;
             }
-            const template = Buffer.from(data.content, 'base64').toString('utf-8');
+            const template = Buffer.from(data.content, 'base64').toString('utf8');
             debug(MODULE, `Found PR template at ${path} (${template.length} chars)`);
             return { template, source: path };
         }

package/dist/core/state-persistence.js

@@ -3,8 +3,8 @@
  * Handles file I/O, locking, backup/restore, and schema migration (v1→v2→v3).
  * No module-level mutable state — functions accept/return AgentState objects.
  */
-import * as fs from 'fs';
-import * as path from 'path';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { AgentStateSchema } from './state-schema.js';
 import { getStatePath, getBackupDir, getDataDir } from './paths.js';
 import { errorMessage, ConcurrencyError } from './errors.js';
@@ -21,7 +21,7 @@ const LEGACY_BACKUP_DIR = path.join(process.cwd(), 'data', 'backups');
  */
 function isLockStale(lockPath) {
     try {
-        const existing = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+        const existing = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
         return Date.now() - existing.timestamp > LOCK_TIMEOUT_MS;
     }
     catch (err) {
@@ -72,7 +72,7 @@ export function acquireLock(lockPath) {
  */
 export function releaseLock(lockPath) {
     try {
-        const data = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+        const data = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
         if (data.pid === process.pid) {
             fs.unlinkSync(lockPath);
         }
@@ -273,7 +273,7 @@ function tryRestoreFromBackup() {
     for (const backupFile of backupFiles) {
         const backupPath = path.join(backupDir, backupFile);
         try {
-            const data = fs.readFileSync(backupPath, 'utf-8');
+            const data = fs.readFileSync(backupPath, 'utf8');
             let raw = JSON.parse(data);
             // Chain migrations: v1 → v2 → v3
             if (typeof raw === 'object' && raw !== null) {
@@ -325,7 +325,7 @@ export function loadState() {
     const statePath = getStatePath();
     try {
         if (fs.existsSync(statePath)) {
-            const data = fs.readFileSync(statePath, 'utf-8');
+            const data = fs.readFileSync(statePath, 'utf8');
             let raw = JSON.parse(data);
             // Chain migrations: v1 → v2 → v3 → v4
             let wasMigrated = false;
@@ -491,7 +491,7 @@ export function saveState(state, expectedMtimeMs = null) {
         // Create backup of existing state (best-effort, non-fatal)
         try {
             if (fs.existsSync(statePath)) {
-                const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const timestamp = new Date().toISOString().replace(/[.:]/g, '-');
                 const randomSuffix = Math.random().toString(36).slice(2, 8).padEnd(6, '0');
                 const backupFile = path.join(backupDir, `state-${timestamp}-${randomSuffix}.json`);
                 fs.copyFileSync(statePath, backupFile);

package/dist/core/state.d.ts

@@ -26,6 +26,24 @@ export declare function maybeCheckpoint(stateManager: StateManager, callerModule
  * Retains lightweight CRUD operations for config, issues, shelving, dismissal,
  * and status overrides.
  */
+/**
+ * Surfaced when the in-memory cached state is no longer in sync with the
+ * canonical Gist — typically because `refreshFromGist()` failed (network
+ * blip, rate limit, expired token) or because the bootstrap fell back to
+ * the local cache file (#1193). Commands include this in their `--json`
+ * envelope so cron/dashboard consumers can react instead of silently
+ * operating on stale data.
+ */
+export interface StalenessInfo {
+    /** Why we're operating on cached data. Forward-compatible with future sources. */
+    source: 'cache';
+    /** Human-readable reason from the underlying error. */
+    reason: string;
+    /** ISO timestamp of the most recent successful refresh, or null if never. */
+    lastSuccessfulRefresh: string | null;
+    /** ISO timestamp when this staleness marker was first set. */
+    detectedAt: string;
+}
 export declare class StateManager {
     protected state: AgentState;
     protected inMemoryOnly: boolean;
@@ -34,6 +52,8 @@ export declare class StateManager {
     private _batchDirty;
     protected gistStore: GistStateStore | null;
     protected gistDegraded: boolean;
+    private staleness;
+    private lastSuccessfulRefreshAt;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -142,6 +162,13 @@ export declare class StateManager {
      * Throttled to once per 30 seconds by GistStateStore. Returns true if state was refreshed.
      */
     refreshFromGist(): Promise<boolean>;
+    /**
+     * Returns a staleness marker when the in-memory state diverged from the
+     * canonical Gist (refresh failure or degraded bootstrap), or `null` when
+     * state is current. Commands surface this via their `--json` warnings
+     * envelope (#1193).
+     */
+    getStateStaleness(): StalenessInfo | null;
     /**
      * Store the latest daily digest and update the digest timestamp.
      * @param digest - The daily digest to store