@oss-autopilot/core 3.10.0 → 3.11.0

package/dist/commands/guidelines.js

@@ -1,6 +1,7 @@
 /**
  * Guidelines CLI commands (#867 PR 4).
  *
+ * `guidelines list`        — list repos with stored guidelines.
  * `guidelines view`        — read the per-repo guidelines file from the Gist.
  * `guidelines store`       — overwrite the per-repo guidelines file.
  * `guidelines reset`       — tombstone the file so subsequent reads return null.
@@ -41,6 +42,20 @@ export async function runGuidelinesView(options) {
         storageMode: sm.isGuidelinesAvailable() ? 'gist' : 'local-unavailable',
     };
 }
+/**
+ * List every repo with non-empty stored guidelines. Never throws in local
+ * mode — returns an empty list with `storageMode: 'local-unavailable'` so
+ * hosts can distinguish "nothing stored" from "storage not configured".
+ */
+export async function runGuidelinesList() {
+    const sm = getStateManager();
+    const repos = sm.listGuidelinesRepos();
+    return {
+        repos,
+        count: repos.length,
+        storageMode: sm.isGuidelinesAvailable() ? 'gist' : 'local-unavailable',
+    };
+}
 /**
  * Persist per-repo guidelines for `repo`. Throws when not in Gist mode or
  * when content exceeds the byte budget — the CLI surface relies on the
@@ -57,11 +72,12 @@ export async function runGuidelinesStore(options) {
     // Push to Gist — autoSave only writes the local state-cache mirror in Gist
     // mode, so without this checkpoint the change never propagates across
     // machines (#1200).
-    await maybeCheckpoint(sm, MODULE);
+    const gistSyncWarning = await maybeCheckpoint(sm, MODULE);
     return {
         repo: options.repo,
         byteSize: Buffer.byteLength(options.content, 'utf8'),
         stored: true,
+        ...(gistSyncWarning ? { gistSyncWarning } : {}),
     };
 }
 /** Tombstone the guidelines file for `repo`. */
@@ -72,12 +88,13 @@ export async function runGuidelinesReset(options) {
         throw new GuidelinesNotAvailableError();
     }
     const existed = sm.getGuidelines(options.repo) !== null;
+    let gistSyncWarning = null;
     if (existed) {
         sm.deleteGuidelines(options.repo);
         // Push to Gist — see runGuidelinesStore note (#1200).
-        await maybeCheckpoint(sm, MODULE);
+        gistSyncWarning = await maybeCheckpoint(sm, MODULE);
     }
-    return { repo: options.repo, deleted: existed };
+    return { repo: options.repo, deleted: existed, ...(gistSyncWarning ? { gistSyncWarning } : {}) };
 }
 /**
  * Fetch raw PR comment bundles for the most recent merged/closed PRs in `repo`
@@ -146,8 +163,9 @@ export async function runFetchCorpus(options) {
     // Push commentsFetchedAt stamps to Gist so other machines don't re-fetch
     // the same PRs forever. autoSave only writes the local mirror in Gist
     // mode (#1200).
+    let gistSyncWarning = null;
     if (bundles.length > 0) {
-        await maybeCheckpoint(sm, MODULE);
+        gistSyncWarning = await maybeCheckpoint(sm, MODULE);
     }
     return {
         repo: options.repo,
@@ -155,6 +173,7 @@ export async function runFetchCorpus(options) {
         prCount: bundles.length,
         skipped,
         failures,
+        ...(gistSyncWarning ? { gistSyncWarning } : {}),
     };
 }
 function clampLimit(limit) {

package/dist/commands/index.d.ts

@@ -61,6 +61,8 @@ export { runInit } from './init.js';
 export { runSetup } from './setup.js';
 /** Check whether setup has been completed. */
 export { runCheckSetup } from './setup.js';
+/** List repos with stored guidelines (empty in local mode). */
+export { runGuidelinesList } from './guidelines.js';
 /** Read the guidelines file for a repo. */
 export { runGuidelinesView } from './guidelines.js';
 /** Persist a guidelines file for a repo (overwrites on subsequent calls). */
@@ -96,7 +98,7 @@ export type { VetOutput, CommentsOutput, PostOutput, ClaimOutput, VetListOutput,
 export type { ConfigOutput, DetectFormattersOutput, ParseIssueListOutput, ParsedIssueItem, CheckIntegrationOutput, LocalReposOutput, } from '../formatters/json.js';
 export type { ShelveOutput, UnshelveOutput } from './shelve.js';
 export type { MoveOutput, MoveTarget } from './move.js';
-export type { GuidelinesViewOutput, GuidelinesStoreOutput, GuidelinesResetOutput, FetchCorpusOutput, } from './guidelines.js';
+export type { GuidelinesListOutput, GuidelinesViewOutput, GuidelinesStoreOutput, GuidelinesResetOutput, FetchCorpusOutput, } from './guidelines.js';
 export type { DismissOutput, UndismissOutput } from './dismiss.js';
 export type { InitOutput } from './init.js';
 export type { ConfigSetOutput, ConfigCommandOutput } from './config.js';

package/dist/commands/index.js

@@ -66,6 +66,8 @@ export { runSetup } from './setup.js';
 /** Check whether setup has been completed. */
 export { runCheckSetup } from './setup.js';
 // ── Per-Repo Guidelines (#867) ──────────────────────────────────────────────
+/** List repos with stored guidelines (empty in local mode). */
+export { runGuidelinesList } from './guidelines.js';
 /** Read the guidelines file for a repo. */
 export { runGuidelinesView } from './guidelines.js';
 /** Persist a guidelines file for a repo (overwrites on subsequent calls). */

package/dist/commands/move.d.ts

@@ -9,6 +9,8 @@ export interface MoveOutput {
     target: MoveTarget;
     /** Human-readable description of what happened. */
     description: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 /**
  * Move a PR between states: attention, waiting, shelved, or auto (computed).

package/dist/commands/move.js

@@ -7,6 +7,10 @@ import { ValidationError } from '../core/errors.js';
 import { PR_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
 const MODULE = 'move';
 export const VALID_TARGETS = ['attention', 'waiting', 'shelved', 'auto'];
+/** Attach the checkpoint warning only when present, keeping the key off the wire on clean runs (#1370). */
+function withGistSyncWarning(output, gistSyncWarning) {
+    return gistSyncWarning ? { ...output, gistSyncWarning } : output;
+}
 /**
  * Move a PR between states: attention, waiting, shelved, or auto (computed).
  *
@@ -36,32 +40,32 @@ export async function runMove(options) {
                 stateManager.setStatusOverride(options.prUrl, status, lastActivityAt);
                 stateManager.unshelvePR(options.prUrl);
             });
-            await maybeCheckpoint(stateManager, MODULE);
-            return { url: options.prUrl, target, description: `Moved to ${label}` };
+            const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+            return withGistSyncWarning({ url: options.prUrl, target, description: `Moved to ${label}` }, gistSyncWarning);
         }
         case 'shelved': {
             stateManager.batch(() => {
                 stateManager.shelvePR(options.prUrl);
                 stateManager.clearStatusOverride(options.prUrl);
             });
-            await maybeCheckpoint(stateManager, MODULE);
-            return {
+            const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+            return withGistSyncWarning({
                 url: options.prUrl,
                 target,
                 description: 'Shelved — excluded from capacity and actionable items',
-            };
+            }, gistSyncWarning);
         }
         case 'auto': {
             stateManager.batch(() => {
                 stateManager.clearStatusOverride(options.prUrl);
                 stateManager.unshelvePR(options.prUrl);
             });
-            await maybeCheckpoint(stateManager, MODULE);
-            return {
+            const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+            return withGistSyncWarning({
                 url: options.prUrl,
                 target,
                 description: 'Reset to computed status',
-            };
+            }, gistSyncWarning);
         }
         default: {
             const _exhaustive = target;

package/dist/commands/repo-vet.js

@@ -11,7 +11,7 @@
  * no state mutation, runs against a public `owner/repo` slug.
  */
 import { getOctokit, requireGitHubToken } from '../core/index.js';
-import { errorMessage } from '../core/errors.js';
+import { errorMessage, getHttpStatusCode, isRateLimitOrAuthError } from '../core/errors.js';
 import { warn } from '../core/logger.js';
 import { validateRepoIdentifier } from './validation.js';
 import { computeRepoVet } from '../core/repo-vet.js';
@@ -160,13 +160,30 @@ export async function runRepoVet(options) {
     const token = requireGitHubToken();
     const octokit = getOctokit(token);
     const now = new Date();
+    // Tracks the release-list analogue of communityHealth's `incomplete`:
+    // set when the listReleases call failed for a reason that does NOT
+    // prove absence (5xx, network), so the caller can distinguish "repo
+    // has no releases" from "couldn't check releases" (#1373).
+    let releasesIncomplete = false;
     const [repoMetaResp, closedPRsResp, commitsResp, releasesResp, communityHealthSummary] = await Promise.all([
         octokit.repos.get({ owner, repo }),
         octokit.pulls.list({ owner, repo, state: 'closed', sort: 'updated', direction: 'desc', per_page: 100 }),
         octokit.repos.listCommits({ owner, repo, per_page: 100 }),
-        octokit.repos
-            .listReleases({ owner, repo, per_page: 1 })
-            .catch(() => ({ data: [] })),
+        octokit.repos.listReleases({ owner, repo, per_page: 1 }).catch((err) => {
+            // Rate-limit / auth failures must abort the run, same as every
+            // sibling fetch — under throttling, a blanket catch here would
+            // silently report "no releases" for the whole vet batch (#1373).
+            if (isRateLimitOrAuthError(err))
+                throw err;
+            const empty = { data: [] };
+            // 404 is a definitive "nothing there" — genuine absence, not a gap.
+            if (getHttpStatusCode(err) === 404)
+                return empty;
+            // 5xx / network: absence is unproven. Degrade gracefully but flag it.
+            releasesIncomplete = true;
+            warn(MODULE, `release listing for ${owner}/${repo} failed: ${errorMessage(err)} — release-recency signal is incomplete`);
+            return empty;
+        }),
         checkCommunityHealth(octokit, owner, repo),
     ]);
     const prs = closedPRsResp.data.map((p) => ({
@@ -201,15 +218,20 @@ export async function runRepoVet(options) {
     const result = computeRepoVet(input);
     // The core function names its metadata object `repo`. Rename to `repoMeta`
     // at the CLI boundary so the top-level slug doesn't collide with it.
-    // Also overlay the community-health `incomplete` flag the wrapper
-    // tracks (the core type doesn't carry it because computeRepoVet is
-    // pure — only the wrapper makes the API calls that can fail mid-probe).
-    const { repo: repoMeta, communityHealth, ...rest } = result;
+    // Also overlay the community-health `incomplete` and the
+    // `releasesIncomplete` flags the wrapper tracks (the core type doesn't
+    // carry them because computeRepoVet is pure — only the wrapper makes
+    // the API calls that can fail mid-probe). Like communityHealth's
+    // incomplete flag, releasesIncomplete deliberately does NOT alter the
+    // rubric score — the score reflects the fetched signals as-is and the
+    // flag tells consumers which signal was unverified.
+    const { repo: repoMeta, communityHealth, maintainerActivity, ...rest } = result;
     return {
         repoSlug: options.repo,
         fetchedAt: now.toISOString(),
         repoMeta,
         communityHealth: { ...communityHealth, incomplete: communityHealthSummary.incomplete },
+        maintainerActivity: { ...maintainerActivity, releasesIncomplete },
         ...rest,
     };
 }

package/dist/commands/shelve.d.ts

@@ -11,10 +11,14 @@ import { PR_URL_PATTERN } from './validation.js';
 export interface ShelveOutput {
     shelved: boolean;
     url: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 export interface UnshelveOutput {
     unshelved: boolean;
     url: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 export { PR_URL_PATTERN };
 /**

package/dist/commands/shelve.js

@@ -29,8 +29,8 @@ export async function runShelve(options) {
         added = stateManager.shelvePR(options.prUrl);
         stateManager.clearStatusOverride(options.prUrl);
     });
-    await maybeCheckpoint(stateManager, MODULE);
-    return { shelved: added, url: options.prUrl };
+    const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+    return { shelved: added, url: options.prUrl, ...(gistSyncWarning ? { gistSyncWarning } : {}) };
 }
 /**
  * Unshelve a PR, restoring it to the daily digest.
@@ -49,6 +49,6 @@ export async function runUnshelve(options) {
         removed = stateManager.unshelvePR(options.prUrl);
         stateManager.clearStatusOverride(options.prUrl);
     });
-    await maybeCheckpoint(stateManager, MODULE);
-    return { unshelved: removed, url: options.prUrl };
+    const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+    return { unshelved: removed, url: options.prUrl, ...(gistSyncWarning ? { gistSyncWarning } : {}) };
 }

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

@@ -49,7 +49,7 @@ 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, GistCorruptError, isRateLimitError } from './errors.js';
+import { ConfigurationError, GistPermissionError, GistConcurrencyError, GistCorruptError, isRateLimitError, } from './errors.js';
 const MODULE = 'gist-store';
 /**
  * Extract the ETag header from an Octokit response, tolerating both lower-
@@ -139,6 +139,13 @@ export class GistStateStore {
                     return { gistId: localId, state, created: false };
                 }
                 catch (err) {
+                    // A corrupt or permission-broken Gist must surface immediately
+                    // (#1367): falling through to search would either re-find the same
+                    // corrupt Gist or silently abandon it and create a fresh one.
+                    if (err instanceof ConfigurationError)
+                        throw err;
+                    if (isRateLimitError(err))
+                        throw err;
                     warn(MODULE, `Failed to fetch Gist ${localId}, will search/create`, err);
                     // Fall through to search
                 }
@@ -159,10 +166,22 @@ export class GistStateStore {
             return { gistId: id, state, created: true };
         }
         catch (err) {
-            // Configuration errors (e.g. GistPermissionError) must surface, not degrade
-            if (err instanceof GistPermissionError)
+            // Configuration errors (GistPermissionError, GistCorruptError) and rate
+            // limits must surface, not degrade (#1367). A corrupt Gist especially:
+            // fetchAndCache arms this.gistId/lastFetchedEtag before the parse
+            // throws, so a degraded store could push() local or fresh state over
+            // the corrupt remote — the exact data loss #1201 exists to prevent.
+            // Rate limits propagate per the errors.ts contract; degrading would
+            // present "you are rate-limited" as a stale local cache.
+            if (err instanceof ConfigurationError)
                 throw err;
-            // All API paths failed — enter degraded mode
+            if (isRateLimitError(err))
+                throw err;
+            // All API paths failed — enter degraded mode. Disarm the remote write
+            // path first: a degraded store never verified its Gist, so it must
+            // never be able to push to one (#1367).
+            this.gistId = null;
+            this.lastFetchedEtag = null;
             warn(MODULE, 'All Gist API paths failed, entering degraded mode', err);
             // Try reading from local cache file
             const cachePath = getStateCachePath();
@@ -222,6 +241,12 @@ export class GistStateStore {
                     return { gistId: localId, state, created: false, migrated: false };
                 }
                 catch (err) {
+                    // See bootstrap(): corrupt/permission/rate-limit errors surface
+                    // immediately rather than falling through (#1367).
+                    if (err instanceof ConfigurationError)
+                        throw err;
+                    if (isRateLimitError(err))
+                        throw err;
                     warn(MODULE, `bootstrapWithMigration: failed to fetch Gist ${localId}, will search/create`, err);
                     // Fall through to search
                 }
@@ -242,10 +267,16 @@ export class GistStateStore {
             return { gistId: id, state, created: true, migrated: true };
         }
         catch (err) {
-            // Configuration errors (e.g. GistPermissionError) must surface, not degrade
-            if (err instanceof GistPermissionError)
+            // Same surfacing contract as bootstrap() (#1367): configuration errors
+            // and rate limits rethrow; only genuine API unavailability degrades.
+            if (err instanceof ConfigurationError)
+                throw err;
+            if (isRateLimitError(err))
                 throw err;
-            // All API paths failed — enter degraded mode
+            // All API paths failed — enter degraded mode with the push path
+            // disarmed (see bootstrap()).
+            this.gistId = null;
+            this.lastFetchedEtag = null;
             warn(MODULE, 'bootstrapWithMigration: all Gist API paths failed, entering degraded mode', err);
             // Try reading from local cache file
             const cachePath = getStateCachePath();
@@ -627,6 +658,10 @@ export class GistStateStore {
             }
         }
         catch (err) {
+            // A rate-limited search must not read as "no Gist found" — bootstrap
+            // would proceed to create a duplicate Gist while throttled (#1367).
+            if (isRateLimitError(err))
+                throw err;
             warn(MODULE, 'Failed to search Gists by description', err);
         }
         return null;

package/dist/core/index.d.ts

@@ -8,7 +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 { wrapUntrustedContent, extractFromFence, safeExtractFromFence, 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,7 +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 { wrapUntrustedContent, extractFromFence, safeExtractFromFence, 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

@@ -12,7 +12,7 @@ import { getStateManager } from './state.js';
 import { daysBetween } from './dates.js';
 import { splitRepo, extractOwnerRepo, isOwnRepo } from './urls.js';
 import { runWorkerPool, DEFAULT_CONCURRENCY } from './concurrency.js';
-import { ConfigurationError, errorMessage } from './errors.js';
+import { ConfigurationError, errorMessage, isRateLimitOrAuthError } from './errors.js';
 import { debug, warn } from './logger.js';
 const MODULE = 'issue-conversation';
 const MAX_CONCURRENT_REQUESTS = DEFAULT_CONCURRENCY;
@@ -108,6 +108,14 @@ export class IssueConversationMonitor {
                 }
             }
             catch (error) {
+                // Rate-limit / auth failures must propagate, not degrade to "fewer
+                // results" — under throttling every sibling analysis fails the same
+                // way and the partial result silently looks like a quiet day (#1391).
+                // runWorkerPool aborts remaining workers and rejects; daily.ts and
+                // dashboard-data.ts rethrow rate-limit/auth from their phase catches,
+                // aborting the run just like PRMonitor's 429s do.
+                if (isRateLimitOrAuthError(error))
+                    throw error;
                 const msg = errorMessage(error);
                 failures.push({ issueUrl: item.html_url, error: msg });
                 warn(MODULE, `Error analyzing issue ${item.html_url}: ${msg}`);
@@ -117,7 +125,7 @@ export class IssueConversationMonitor {
             warn(MODULE, `${failures.length}/${candidates.length} issue analysis call(s) failed`);
         }
         if (failures.length === candidates.length && candidates.length > 0) {
-            warn(MODULE, `All ${candidates.length} issue analysis call(s) failed. Possible systemic issue (rate limit, auth, network).`);
+            warn(MODULE, `All ${candidates.length} issue analysis call(s) failed. Possible systemic issue (network, GitHub availability).`);
         }
         // Sort: new_response first, then waiting, then acknowledged
         const statusOrder = {
@@ -199,6 +207,11 @@ export class IssueConversationMonitor {
             }
         }
         const labels = (item.labels || []).map((l) => l.name || '').filter(Boolean);
+        // Body excerpts stay RAW here on purpose (#1372): these objects feed the
+        // dashboard SPA and the CLI text renderers directly, and the matching
+        // above (acknowledgment / @mention) operates on raw text. The
+        // `<github-content>` fence is applied at the agent-facing serialization
+        // boundary in `toDailyOutput()` (commands/daily.ts).
         const base = {
             repo: repoFullName,
             number: item.number,

package/dist/core/paths.d.ts

@@ -25,6 +25,18 @@ export declare function getDataDir(): string;
  * Implicitly creates the data directory via {@link getDataDir} if it does not exist.
  */
 export declare function getStatePath(): string;
+/**
+ * Returns the legacy (pre-`~/.oss-autopilot`) state file path: `./data/state.json`
+ * relative to the working directory.
+ *
+ * Functions rather than module constants so tests can mock them per-file:
+ * as constants in state-persistence.ts they resolved to the one shared
+ * `packages/core/data/` during vitest, and the migration tests racing
+ * parallel workers on that real directory caused CI flakes (#1382).
+ */
+export declare function getLegacyStatePath(): string;
+/** Legacy backup directory (`./data/backups`); see {@link getLegacyStatePath}. */
+export declare function getLegacyBackupDir(): string;
 /**
  * Returns the backup directory path, creating it if it does not exist.
  *

package/dist/core/paths.js

@@ -36,6 +36,22 @@ export function getDataDir() {
 export function getStatePath() {
     return path.join(getDataDir(), 'state.json');
 }
+/**
+ * Returns the legacy (pre-`~/.oss-autopilot`) state file path: `./data/state.json`
+ * relative to the working directory.
+ *
+ * Functions rather than module constants so tests can mock them per-file:
+ * as constants in state-persistence.ts they resolved to the one shared
+ * `packages/core/data/` during vitest, and the migration tests racing
+ * parallel workers on that real directory caused CI flakes (#1382).
+ */
+export function getLegacyStatePath() {
+    return path.join(process.cwd(), 'data', 'state.json');
+}
+/** Legacy backup directory (`./data/backups`); see {@link getLegacyStatePath}. */
+export function getLegacyBackupDir() {
+    return path.join(process.cwd(), 'data', 'backups');
+}
 /**
  * Returns the backup directory path, creating it if it does not exist.
  *

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

@@ -16,6 +16,7 @@ import type { Octokit } from '@octokit/rest';
 export interface PRReviewEntry {
     author: string;
     authorAssociation: string;
+    /** `<github-content>`-fenced review body (#1372). */
     body: string;
     submittedAt: string;
 }
@@ -23,6 +24,7 @@ export interface PRReviewEntry {
 export interface PRReviewCommentEntry {
     author: string;
     authorAssociation: string;
+    /** `<github-content>`-fenced comment body (#1372). */
     body: string;
     path: string;
     createdAt: string;
@@ -31,6 +33,7 @@ export interface PRReviewCommentEntry {
 export interface PRIssueCommentEntry {
     author: string;
     authorAssociation: string;
+    /** `<github-content>`-fenced comment body (#1372). */
     body: string;
     createdAt: string;
 }
@@ -62,8 +65,13 @@ export declare function fetchPRCommentBundle(octokit: Octokit, prUrl: string, gi
  * `{ 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).
+ * so a single 404 / transient failure on one PR should not deny the host the
+ * corpus from the other 4 — but the failure should still be visible (#1209 L8).
+ *
+ * Rate-limit / auth errors are the exception: they reject the whole batch
+ * (#1391). Under throttling every remaining PR would fail the same way, so
+ * degrading to "skipped N PRs" silently masks a systemic failure the caller
+ * needs to surface (the CLI/MCP error envelope on `guidelines fetch-corpus`).
  */
 export interface PRCommentBundlesBatchResult {
     bundles: PRCommentBundle[];

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

@@ -1,7 +1,8 @@
 import { paginateAll } from './pagination.js';
+import { wrapUntrustedContent } from './untrusted-content.js';
 import { isBotAuthor } from './comment-utils.js';
 import { parseGitHubUrl } from './urls.js';
-import { ValidationError, errorMessage } from './errors.js';
+import { ValidationError, errorMessage, isRateLimitOrAuthError } from './errors.js';
 import { debug, warn } from './logger.js';
 const MODULE = 'pr-comments-fetcher';
 /** Default concurrency for {@link fetchPRCommentBundlesBatch}. */
@@ -60,6 +61,12 @@ export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
         return true;
     };
     const mergedAt = pr.merged_at ?? pr.closed_at ?? '';
+    // Fence every body at fetch time (#1372): the bundle's only consumer is
+    // `guidelines fetch-corpus`, whose output goes straight into the host's
+    // extract-learnings prompt — there is no human-display or string-matching
+    // consumer downstream, so fetch-time wrapping is safe here.
+    const fenceLabel = `${repoFull}#${pull_number}`;
+    const fence = (body, source, author, association) => wrapUntrustedContent(body, fenceLabel, { author, association, source });
     return {
         prUrl,
         prTitle: pr.title,
@@ -70,7 +77,7 @@ export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
             .map((r) => ({
             author: r.user?.login ?? '',
             authorAssociation: r.author_association ?? 'NONE',
-            body: r.body ?? '',
+            body: fence(r.body ?? '', 'pr-review', r.user?.login ?? '', r.author_association ?? 'NONE'),
             submittedAt: r.submitted_at ?? '',
         })),
         reviewComments: reviewComments
@@ -78,7 +85,7 @@ export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
             .map((c) => ({
             author: c.user?.login ?? '',
             authorAssociation: c.author_association ?? 'NONE',
-            body: c.body ?? '',
+            body: fence(c.body ?? '', 'pr-review-comment', c.user?.login ?? '', c.author_association ?? 'NONE'),
             path: c.path ?? '',
             createdAt: c.created_at ?? '',
         })),
@@ -87,7 +94,7 @@ export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
             .map((c) => ({
             author: c.user?.login ?? '',
             authorAssociation: c.author_association ?? 'NONE',
-            body: c.body ?? '',
+            body: fence(c.body ?? '', 'pr-issue-comment', c.user?.login ?? '', c.author_association ?? 'NONE'),
             createdAt: c.created_at ?? '',
         })),
     };
@@ -96,8 +103,11 @@ export async function fetchPRCommentBundlesBatch(octokit, prUrls, githubUsername
     const bundles = [];
     const failures = [];
     const queue = [...prUrls];
+    let aborted = false;
     async function worker() {
         while (queue.length > 0) {
+            if (aborted)
+                return;
             const url = queue.shift();
             if (!url)
                 return;
@@ -106,6 +116,14 @@ export async function fetchPRCommentBundlesBatch(octokit, prUrls, githubUsername
                 bundles.push(bundle);
             }
             catch (err) {
+                // Rate-limit / auth failures abort the batch instead of degrading to
+                // a per-PR skip — see the doc comment above (#1391). The abort flag
+                // stops sibling workers from burning more rate-limited requests on
+                // results that will be discarded when Promise.all rejects.
+                if (isRateLimitOrAuthError(err)) {
+                    aborted = true;
+                    throw err;
+                }
                 const errorMsg = errorMessage(err);
                 failures.push({ prUrl: url, error: errorMsg });
                 warn(MODULE, `Skipping ${url}: ${errorMsg}`);

package/dist/core/state-persistence.d.ts

@@ -45,16 +45,41 @@ export declare function migrateV3ToV4(rawState: Record<string, unknown>): Record
  * Leverages Zod schema defaults to produce a complete state.
  */
 export declare function createFreshState(): AgentState;
+/**
+ * Details about a recovery that happened during {@link loadState} — set when
+ * the main state file was unreadable (JSON parse error) or structurally
+ * invalid (Zod rejection) and the loader fell back to a backup or fresh state.
+ * Surfaced through StateManager.getLoadRecovery() so commands can include the
+ * event in structured output instead of only stderr warn() lines (#1371).
+ */
+export interface LoadRecoveryInfo {
+    /** Where the loaded state came from after the original file was rejected. */
+    source: 'backup' | 'fresh';
+    /** Path of the preserved `.rejected-<ts>` copy, or null if preservation failed. */
+    rejectedPath: string | null;
+    /** Short summary of why the original state file was rejected. */
+    reason: string;
+}
+/**
+ * Result of {@link loadState}: the loaded state, the file's mtime for change
+ * detection, and (only when the main file was rejected) recovery details.
+ */
+export interface LoadStateResult {
+    state: AgentState;
+    mtimeMs: number;
+    recovery?: LoadRecoveryInfo;
+}
 /**
  * Load state from file, or create initial state if none exists.
  * If the main state file is corrupted, attempts to restore from the most recent backup.
  * Performs migration from legacy ./data/ location if needed.
- * @returns Object with the loaded state and the file's mtime (for change detection).
+ * @returns Object with the loaded state, the file's mtime (for change detection),
+ *   and recovery details when the main file was rejected.
+ * @throws Error when the state file exists but cannot be read due to a
+ *   permission error (EACCES/EPERM) — that is an environment problem, not
+ *   corruption, so restore-or-fresh would mask it and risk clobbering data.
  */
-export declare function loadState(): {
-    state: AgentState;
-    mtimeMs: number;
-};
+export declare function loadState(): LoadStateResult;
 /**
  * Persist state to disk, creating a timestamped backup of the previous
  * state file first. Retains at most 10 backup files.
@@ -79,7 +104,4 @@ export declare function saveState(state: Readonly<AgentState>, expectedMtimeMs?:
  * Uses mtime comparison (single statSync call) to avoid unnecessary JSON parsing.
  * @returns The new state and mtime if reloaded, or null if no change detected.
  */
-export declare function reloadStateIfChanged(lastLoadedMtimeMs: number): {
-    state: AgentState;
-    mtimeMs: number;
-} | null;
+export declare function reloadStateIfChanged(lastLoadedMtimeMs: number): LoadStateResult | null;