@oss-autopilot/core 3.2.0 → 3.4.0

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) {
@@ -85,7 +85,16 @@ export class HttpCache {
             }
             return entry;
         }
-        catch {
+        catch (err) {
+            // ENOENT (cache miss) is the common case and not worth logging — but
+            // EISDIR / JSON parse / disk corruption all looked identical to a miss
+            // before, hiding repeated cache misses caused by a corrupt entry. Log
+            // anything that's not "file not found" so the cause becomes
+            // diagnosable in DEBUG mode (#1209 L5).
+            if (err && typeof err === 'object' && err.code !== 'ENOENT') {
+                const msg = err instanceof Error ? err.message : 'unknown error';
+                debug(MODULE, `Cache read failed for ${url} (treating as miss): ${msg}`);
+            }
             return null;
         }
     }
@@ -100,7 +109,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 +200,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';
@@ -17,7 +18,7 @@ export { DEFAULT_CONCURRENCY } from './concurrency.js';
 export { OssAutopilotError, ConfigurationError, ValidationError, GistPermissionError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, nonFatalCatch, resolveErrorCode, } from './errors.js';
 export { enableDebug, isDebugEnabled, debug, info, warn, timed } from './logger.js';
 export { HttpCache, getHttpCache, cachedRequest, type CacheEntry } from './http-cache.js';
-export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';
+export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, buildStarFilter, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';
 export { computeContributionStats, type ContributionStats, type ComputeStatsInput } from './stats.js';
 export { fetchPRTemplate, type PRTemplateResult } from './pr-template.js';
 export { classifyLinkedPR, type LinkedPR, type LinkedPRClassification, type LinkedPRState, } from './linked-pr-classification.js';
@@ -25,4 +26,5 @@ export { scanForAntiLLMPolicy, type AntiLLMCategory, type AntiLLMMatch, type Ant
 export { detectFormatters, diagnoseCIFormatterFailure, getPreferredFormatter, type DetectedFormatter, type FormatterDetectionResult, type CIFormatterDiagnosis, type FormatterName, } from './formatter-detection.js';
 export { CONFIG_KEY_REGISTRY, type ConfigKeyDef, type SettableVia, isKnownKey, getKeyDef, getSetupKeys, getConfigKeys, suggestKey, formatUnknownKeyError, } from './config-registry.js';
 export { DashboardDataSchema, DashboardStatsSchema, validateDashboardData, type DashboardDataParsed, } from './dashboard-data-schema.js';
+export { fetchPRCommentBundle, fetchPRCommentBundlesBatch, type PRCommentBundle, type PRReviewEntry, type PRReviewCommentEntry, type PRIssueCommentEntry, } from './pr-comments-fetcher.js';
 export * from './types.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';
@@ -18,7 +19,7 @@ export { DEFAULT_CONCURRENCY } from './concurrency.js';
 export { OssAutopilotError, ConfigurationError, ValidationError, GistPermissionError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, nonFatalCatch, resolveErrorCode, } from './errors.js';
 export { enableDebug, isDebugEnabled, debug, info, warn, timed } from './logger.js';
 export { HttpCache, getHttpCache, cachedRequest } from './http-cache.js';
-export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';
+export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, buildStarFilter, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';
 export { computeContributionStats } from './stats.js';
 export { fetchPRTemplate } from './pr-template.js';
 export { classifyLinkedPR, } from './linked-pr-classification.js';
@@ -26,4 +27,8 @@ export { scanForAntiLLMPolicy, } from './anti-llm-policy.js';
 export { detectFormatters, diagnoseCIFormatterFailure, getPreferredFormatter, } from './formatter-detection.js';
 export { CONFIG_KEY_REGISTRY, isKnownKey, getKeyDef, getSetupKeys, getConfigKeys, suggestKey, formatUnknownKeyError, } from './config-registry.js';
 export { DashboardDataSchema, DashboardStatsSchema, validateDashboardData, } from './dashboard-data-schema.js';
+// PR comment bundle types — wire shape consumed by the MCP extract-learnings
+// prompt. Re-exported so MCP doesn't have to redeclare the interface and
+// silently drift (#1208 M5).
+export { fetchPRCommentBundle, fetchPRCommentBundlesBatch, } from './pr-comments-fetcher.js';
 export * from './types.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/placeholder-usernames.d.ts

@@ -0,0 +1 @@
+export declare function isPlaceholderUsername(username: string): boolean;

package/dist/core/placeholder-usernames.js

@@ -0,0 +1,27 @@
+/**
+ * Known placeholder values that can end up in `config.githubUsername` from
+ * doc snippets, example configs, or aborted setup flows.
+ *
+ * Two callers consult this list:
+ *   - `pr-monitor.ts` — runtime auto-repair: if a fetch is about to run with
+ *     a placeholder, the configured value is replaced with the authenticated
+ *     viewer's login before the search hits GitHub. Without this, the search
+ *     silently returns zero results and the dashboard looks like a fresh install.
+ *   - `commands/validation.ts` — write-side rejection: prevents `init`,
+ *     `setup --set username=`, and the MCP `config` tool from persisting one
+ *     of these values in the first place, so the auto-repair only runs as a
+ *     fallback for legacy state rather than masking a fresh user error.
+ *
+ * Entries must be lowercase — `Lowercase<string>` on the source tuple makes a
+ * non-lowercase entry a compile error, keeping the case-insensitive lookup
+ * contract type-checked instead of comment-documented.
+ */
+const PLACEHOLDER_USERNAMES = [
+    'example-user',
+    'your-username',
+    'your-github-username',
+];
+const KNOWN_PLACEHOLDER_USERNAMES = new Set(PLACEHOLDER_USERNAMES);
+export function isPlaceholderUsername(username) {
+    return KNOWN_PLACEHOLDER_USERNAMES.has(username.toLowerCase());
+}

package/dist/core/pr-comments-fetcher.d.ts

@@ -58,10 +58,18 @@ export declare function fetchPRCommentBundle(octokit: Octokit, prUrl: string, gi
 /**
  * Fetch comment bundles for many PRs with a small concurrency cap (default 3).
  *
- * Failures on individual PRs are logged and skipped — the batch returns a
- * shorter array rather than aborting. Rationale: extraction quality is
- * already a partial-information problem (users contribute to many repos and
- * many PRs), so a single 404 / rate limit on one PR should not deny the
- * host the corpus from the other 4.
+ * Failures on individual PRs are logged and recorded — the batch returns
+ * `{ bundles, failures }` so the caller can decide whether to retry, surface
+ * a partial-data banner, or proceed. Rationale: extraction quality is already
+ * a partial-information problem (users contribute to many repos and many PRs),
+ * so a single 404 / rate limit on one PR should not deny the host the corpus
+ * from the other 4 — but the failure should still be visible (#1209 L8).
  */
-export declare function fetchPRCommentBundlesBatch(octokit: Octokit, prUrls: string[], githubUsername: string, concurrency?: number): Promise<PRCommentBundle[]>;
+export interface PRCommentBundlesBatchResult {
+    bundles: PRCommentBundle[];
+    failures: Array<{
+        prUrl: string;
+        error: string;
+    }>;
+}
+export declare function fetchPRCommentBundlesBatch(octokit: Octokit, prUrls: string[], githubUsername: string, concurrency?: number): Promise<PRCommentBundlesBatchResult>;

package/dist/core/pr-comments-fetcher.js

@@ -92,17 +92,9 @@ export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
         })),
     };
 }
-/**
- * Fetch comment bundles for many PRs with a small concurrency cap (default 3).
- *
- * Failures on individual PRs are logged and skipped — the batch returns a
- * shorter array rather than aborting. Rationale: extraction quality is
- * already a partial-information problem (users contribute to many repos and
- * many PRs), so a single 404 / rate limit on one PR should not deny the
- * host the corpus from the other 4.
- */
 export async function fetchPRCommentBundlesBatch(octokit, prUrls, githubUsername, concurrency = DEFAULT_BATCH_CONCURRENCY) {
-    const results = [];
+    const bundles = [];
+    const failures = [];
     const queue = [...prUrls];
     async function worker() {
         while (queue.length > 0) {
@@ -111,15 +103,17 @@ export async function fetchPRCommentBundlesBatch(octokit, prUrls, githubUsername
                 return;
             try {
                 const bundle = await fetchPRCommentBundle(octokit, url, githubUsername);
-                results.push(bundle);
+                bundles.push(bundle);
             }
             catch (err) {
-                warn(MODULE, `Skipping ${url}: ${errorMessage(err)}`);
+                const errorMsg = errorMessage(err);
+                failures.push({ prUrl: url, error: errorMsg });
+                warn(MODULE, `Skipping ${url}: ${errorMsg}`);
             }
         }
     }
     const workers = Array.from({ length: Math.min(concurrency, prUrls.length) }, worker);
     await Promise.all(workers);
-    debug(MODULE, `Fetched ${results.length}/${prUrls.length} comment bundles`);
-    return results;
+    debug(MODULE, `Fetched ${bundles.length}/${prUrls.length} comment bundles (${failures.length} failed)`);
+    return { bundles, failures };
 }

package/dist/core/pr-monitor.d.ts

@@ -18,8 +18,6 @@ export { computeDisplayLabel } from './display-utils.js';
 export { classifyCICheck, classifyFailingChecks, getCIStatus } from './ci-analysis.js';
 export { isConditionalChecklistItem } from './checklist-analysis.js';
 export { determineStatus } from './status-determination.js';
-declare function isPlaceholderUsername(username: string): boolean;
-export { isPlaceholderUsername };
 /**
  * Check if a PR has a merge conflict based on GitHub's mergeable flag and mergeable_state.
  * Returns true when mergeable is explicitly false or the mergeable_state is 'dirty'.

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';
@@ -29,34 +28,12 @@ import { analyzeChecklist } from './checklist-analysis.js';
 import { extractMaintainerActionHints } from './maintainer-analysis.js';
 import { computeDisplayLabel } from './display-utils.js';
 import { fetchUserMergedPRCounts as fetchUserMergedPRCountsImpl, fetchUserClosedPRCounts as fetchUserClosedPRCountsImpl, fetchRecentlyClosedPRs as fetchRecentlyClosedPRsImpl, fetchRecentlyMergedPRs as fetchRecentlyMergedPRsImpl, } from './github-stats.js';
+import { isPlaceholderUsername } from './placeholder-usernames.js';
 // Re-export so existing consumers can still import from pr-monitor
 export { computeDisplayLabel } from './display-utils.js';
 export { classifyCICheck, classifyFailingChecks, getCIStatus } from './ci-analysis.js';
 export { isConditionalChecklistItem } from './checklist-analysis.js';
 export { determineStatus } from './status-determination.js';
-/**
- * Known placeholder values that can end up in `config.githubUsername` from
- * doc snippets, example configs, or aborted setup flows. When the configured
- * username matches one of these, the PR fetch silently returns zero results
- * and the dashboard looks like a fresh install. Detecting these lets us
- * auto-repair the config from the authenticated viewer before fetching.
- *
- * Entries must be lowercase — `Lowercase<string>` on the source tuple makes
- * a non-lowercase entry a compile error, keeping the case-insensitive lookup
- * contract type-checked instead of comment-documented.
- */
-const PLACEHOLDER_USERNAMES = [
-    'example-user',
-    'your-username',
-    'your-github-username',
-];
-const KNOWN_PLACEHOLDER_USERNAMES = new Set(PLACEHOLDER_USERNAMES);
-function isPlaceholderUsername(username) {
-    return KNOWN_PLACEHOLDER_USERNAMES.has(username.toLowerCase());
-}
-// Module-private on purpose: callers should only use the predicate so the
-// `.toLowerCase()` contract can't be bypassed by reading the set directly.
-export { isPlaceholderUsername };
 /**
  * Check if a PR has a merge conflict based on GitHub's mergeable flag and mergeable_state.
  * Returns true when mergeable is explicitly false or the mergeable_state is 'dirty'.

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.d.ts

@@ -1,6 +1,6 @@
 /**
  * State persistence layer for the OSS Contribution Agent.
- * Handles file I/O, locking, backup/restore, and schema migration (v1→v2→v3).
+ * Handles file I/O, locking, backup/restore, and schema migration (v1→v2→v3→v4).
  * No module-level mutable state — functions accept/return AgentState objects.
  */
 import { AgentState } from './types.js';
@@ -41,7 +41,7 @@ export declare function migrateV2ToV3(rawState: Record<string, unknown>): Record
  */
 export declare function migrateV3ToV4(rawState: Record<string, unknown>): Record<string, unknown>;
 /**
- * Create a fresh state (v3).
+ * Create a fresh state (v4).
  * Leverages Zod schema defaults to produce a complete state.
  */
 export declare function createFreshState(): AgentState;

package/dist/core/state-persistence.js

@@ -1,10 +1,10 @@
 /**
  * State persistence layer for the OSS Contribution Agent.
- * Handles file I/O, locking, backup/restore, and schema migration (v1→v2→v3).
+ * Handles file I/O, locking, backup/restore, and schema migration (v1→v2→v3→v4).
  * 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);
         }
@@ -170,7 +170,7 @@ export function migrateV3ToV4(rawState) {
     return rawState;
 }
 /**
- * Create a fresh state (v3).
+ * Create a fresh state (v4).
  * Leverages Zod schema defaults to produce a complete state.
  */
 export function createFreshState() {
@@ -273,9 +273,9 @@ 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
+            // Chain migrations: v1 → v2 → v3 → v4
             if (typeof raw === 'object' && raw !== null) {
                 const rawObj = raw;
                 if (rawObj.version === 1) {
@@ -306,8 +306,11 @@ function tryRestoreFromBackup() {
             debug(MODULE, `Backup ${backupFile} full validation errors:`, parsed.error.issues);
         }
         catch (backupErr) {
-            // This backup is also corrupted, try the next one
-            warn(MODULE, `Backup ${backupFile} is corrupted, trying next...`);
+            // This backup is also corrupted, try the next one. Include the error
+            // message in the warn so non-DEBUG users can diagnose without enabling
+            // DEBUG=1 (#1209 L7); the full stack still goes to debug.
+            const msg = backupErr instanceof Error ? backupErr.message : String(backupErr);
+            warn(MODULE, `Backup ${backupFile} is corrupted (${msg}), trying next...`);
             debug(MODULE, `Backup ${backupFile} parse failed`, backupErr);
         }
     }
@@ -325,7 +328,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 +494,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-schema.js

@@ -45,18 +45,22 @@ export const StoredMergedPRSchema = z.object({
     title: z.string(),
     mergedAt: z.string(),
     /** When the raw review-comment bundle for this PR was last fetched (#867). */
-    commentsFetchedAt: z.string().optional(),
+    // ISO-8601 datetime guards against `markPRCommentsFetched(url, "garbage")`
+    // poisoning state through the stamping API (#1209 L4).
+    commentsFetchedAt: z.string().datetime().optional(),
     /** When the host last ran LLM extraction over this PR's comment bundle (#867). */
-    learningsExtractedAt: z.string().optional(),
+    learningsExtractedAt: z.string().datetime().optional(),
 });
 export const StoredClosedPRSchema = z.object({
     url: z.string(),
     title: z.string(),
     closedAt: z.string(),
     /** When the raw review-comment bundle for this PR was last fetched (#867). */
-    commentsFetchedAt: z.string().optional(),
+    // ISO-8601 datetime guards against `markPRCommentsFetched(url, "garbage")`
+    // poisoning state through the stamping API (#1209 L4).
+    commentsFetchedAt: z.string().datetime().optional(),
     /** When the host last ran LLM extraction over this PR's comment bundle (#867). */
-    learningsExtractedAt: z.string().optional(),
+    learningsExtractedAt: z.string().datetime().optional(),
 });
 export const AnalyzedIssueConversationSchema = z.object({
     url: z.string(),

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

package/dist/core/state.js

@@ -3,12 +3,12 @@
  * Thin coordinator that delegates persistence to state-persistence.ts
  * and scoring logic to repo-score-manager.ts.
  */
-import * as fs from 'fs';
+import * as fs from 'node:fs';
 import { AgentStateSchema } from './state-schema.js';
 import { loadState, saveState, reloadStateIfChanged, createFreshState, atomicWriteFileSync, } from './state-persistence.js';
 import * as repoScoring from './repo-score-manager.js';
 import { debug, warn } from './logger.js';
-import { errorMessage, ConfigurationError, ConcurrencyError } from './errors.js';
+import { errorMessage, ConfigurationError, ConcurrencyError, isTransientNetworkError } from './errors.js';
 import { GistStateStore } from './gist-state-store.js';
 import * as guidelinesStoreModule from './guidelines-store.js';
 import { getStatePath, getStateCachePath } from './paths.js';
@@ -53,13 +53,6 @@ export async function maybeCheckpoint(stateManager, callerModule) {
         warn(callerModule, `Gist checkpoint failed (local mutation succeeded, will retry on next push): ${errorMessage(err)}`);
     }
 }
-/**
- * Singleton manager for persistent agent state stored in ~/.oss-autopilot/state.json.
- *
- * Delegates file I/O to state-persistence.ts and scoring logic to repo-score-manager.ts.
- * Retains lightweight CRUD operations for config, issues, shelving, dismissal,
- * and status overrides.
- */
 export class StateManager {
     state;
     inMemoryOnly;
@@ -68,6 +61,8 @@ export class StateManager {
     _batchDirty = false;
     gistStore = null;
     gistDegraded = false;
+    staleness = null;
+    lastSuccessfulRefreshAt = null;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -131,6 +126,16 @@ export class StateManager {
         manager.gistStore = gistStore;
         manager.gistDegraded = result.degraded ?? false;
         manager.inMemoryOnly = false; // re-enable persistence
+        // Seed the staleness marker if bootstrap fell back to the local cache —
+        // a `daily` running on a cron right after this start needs to know.
+        if (result.degraded) {
+            manager.staleness = {
+                source: 'cache',
+                reason: 'initial Gist bootstrap fell back to local cache',
+                lastSuccessfulRefresh: null,
+                detectedAt: new Date().toISOString(),
+            };
+        }
         return manager;
     }
     /**
@@ -340,11 +345,24 @@ export class StateManager {
     async refreshFromGist() {
         if (!this.gistStore)
             return false;
-        const refreshed = await this.gistStore.refreshFromGist();
+        const result = await this.gistStore.refreshFromGist();
+        // StateManager keeps its boolean shape (callers rely on truthy-check
+        // semantics) but consults the discriminated union internally to know
+        // whether to reload state.json from the now-fresh cache (#1209 L9).
+        const refreshed = result.status === 'refreshed';
         if (refreshed) {
             const raw = this.gistStore.cachedFiles.get('state.json');
             if (!raw) {
                 warn(MODULE, 'Gist refreshed but state.json missing from cache');
+                // HTTP fetch succeeded but the Gist body is missing state.json — we
+                // still have stale in-memory data, so surface a marker rather than
+                // silently returning false (#1193 review).
+                this.staleness = {
+                    source: 'cache',
+                    reason: 'Gist refresh returned no state.json file',
+                    lastSuccessfulRefresh: this.lastSuccessfulRefreshAt,
+                    detectedAt: new Date().toISOString(),
+                };
                 return false;
             }
             try {
@@ -353,11 +371,41 @@ export class StateManager {
             }
             catch (err) {
                 warn(MODULE, `Failed to parse refreshed Gist state: ${errorMessage(err)}`);
+                // Same reasoning as the missing-file branch: parse failure leaves us
+                // on stale in-memory state, so flag it.
+                this.staleness = {
+                    source: 'cache',
+                    reason: `Gist refresh succeeded but payload was invalid: ${errorMessage(err)}`,
+                    lastSuccessfulRefresh: this.lastSuccessfulRefreshAt,
+                    detectedAt: new Date().toISOString(),
+                };
                 return false;
             }
+            // Successful refresh clears any prior staleness (#1193).
+            this.lastSuccessfulRefreshAt = new Date().toISOString();
+            this.staleness = null;
+        }
+        else if (this.gistStore.lastRefreshError) {
+            // Distinguish "fetch failed" (set marker) from "throttled" (preserve
+            // any existing marker, set nothing new).
+            this.staleness = {
+                source: 'cache',
+                reason: errorMessage(this.gistStore.lastRefreshError),
+                lastSuccessfulRefresh: this.lastSuccessfulRefreshAt,
+                detectedAt: new Date().toISOString(),
+            };
         }
         return refreshed;
     }
+    /**
+     * 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() {
+        return this.staleness;
+    }
     // === Dashboard Data Setters ===
     /**
      * Store the latest daily digest and update the digest timestamp.
@@ -847,11 +895,20 @@ export async function getStateManagerAsync(token) {
         })
             .catch((err) => {
             asyncManagerPromise = null;
-            // Configuration errors (e.g. GistPermissionError) must surface to the user
+            // Configuration errors (e.g. GistPermissionError, GistCorruptError)
+            // must surface — falling back to local-only would silently split state
+            // across machines (#1202).
             if (err instanceof ConfigurationError)
                 throw err;
-            warn(MODULE, `Gist initialization failed, falling back to local-only mode: ${err}`);
-            return getStateManager(); // fall back to sync/local for transient errors
+            // Only fall back on actual network/server errors. Other failures
+            // (auth, schema, concurrency conflicts) indicate the Gist mode is
+            // broken in a way the user needs to address — silently falling back
+            // would write subsequent mutations to the local file while the Gist
+            // marker stays in config, causing permanent cross-machine divergence.
+            if (!isTransientNetworkError(err))
+                throw err;
+            warn(MODULE, `Gist initialization failed (transient network error), falling back to local-only mode: ${err}`);
+            return getStateManager();
         });
         return asyncManagerPromise;
     }
@@ -880,7 +937,7 @@ export async function ensureGistPersistence(token) {
         return;
     let persistence;
     try {
-        const raw = fs.readFileSync(getStatePath(), 'utf-8');
+        const raw = fs.readFileSync(getStatePath(), 'utf8');
         persistence = JSON.parse(raw)?.config?.persistence;
     }
     catch {