@oss-autopilot/core 3.3.0 → 3.4.1

package/dist/cli.js

@@ -32,9 +32,23 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
         enableDebug();
         debug('cli', `Running command: ${actionCommand.name()}`);
     }
-    // actionCommand is the command being executed (e.g., 'status', 'daily')
-    const commandName = actionCommand.name();
-    if (!localOnlySet.has(commandName)) {
+    // actionCommand is the command being executed (e.g., 'status', 'daily').
+    // For subcommand groups (e.g. `guidelines view`), Commander returns the
+    // leaf name `view` — but the registry sets `localOnly` on the parent
+    // entry `guidelines`. Walk the parent chain so a `localOnly` ancestor
+    // covers all its leaves (#1208 M2). Without this, `guidelines view` —
+    // which works fine in local mode (returns storageMode: 'local-unavailable')
+    // — would still hit the auth gate and fail.
+    let cmd = actionCommand;
+    let isLocalOnly = false;
+    while (cmd) {
+        if (localOnlySet.has(cmd.name())) {
+            isLocalOnly = true;
+            break;
+        }
+        cmd = cmd.parent;
+    }
+    if (!isLocalOnly) {
         const token = await getGitHubTokenAsync();
         if (!token) {
             // Honor --json at the CLI boundary so machine consumers (plugins, MCP

package/dist/commands/daily.d.ts

@@ -6,17 +6,11 @@
  * Domain logic lives in src/core/daily-logic.ts; this file is a thin
  * orchestration layer that wires up the phases and handles I/O.
  */
-import { type DailyDigest, type CommentedIssue, type PRCheckFailure, type RepoGroup, type AgentState, type StarFilter } from '../core/index.js';
+import { type DailyDigest, type CommentedIssue, type PRCheckFailure, type RepoGroup } from '../core/index.js';
 import { type DailyOutput, type DailyWarning, type CapacityAssessment, type ActionableIssue, type ActionMenu } from '../formatters/json.js';
 export { applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatBriefSummary, formatSummary, printDigest, CRITICAL_STATUSES, } from '../core/index.js';
-/**
- * Build a star filter from state for use in fetchUserPRCounts.
- * Returns undefined if no star data is available (first run).
- *
- * @param state - Current agent state (read-only)
- * @returns Star filter with minimum threshold and known counts, or undefined on first run
- */
-export declare function buildStarFilter(state: Readonly<AgentState>): StarFilter | undefined;
+import { buildStarFilter } from '../core/daily-logic.js';
+export { buildStarFilter };
 /**
  * Internal result of the daily check, using full (non-deduplicated) types.
  * Consumed by printDigest() (text mode) and converted to DailyOutput (JSON mode)

package/dist/commands/daily.js

@@ -39,26 +39,12 @@ function nonFatalCatchWithWarning(opts) {
 // Re-export domain functions so existing consumers (tests, dashboard, startup)
 // can continue importing from './daily.js' without changes.
 export { applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatBriefSummary, formatSummary, printDigest, CRITICAL_STATUSES, } from '../core/index.js';
-/**
- * Build a star filter from state for use in fetchUserPRCounts.
- * Returns undefined if no star data is available (first run).
- *
- * @param state - Current agent state (read-only)
- * @returns Star filter with minimum threshold and known counts, or undefined on first run
- */
-export function buildStarFilter(state) {
-    const minStars = state.config.minStars ?? 50;
-    const knownStarCounts = new Map();
-    for (const [repo, score] of Object.entries(state.repoScores)) {
-        if (score.stargazersCount !== undefined) {
-            knownStarCounts.set(repo, score.stargazersCount);
-        }
-    }
-    // Only filter if we have some star data to work with
-    if (knownStarCounts.size === 0)
-        return undefined;
-    return { minStars, knownStarCounts };
-}
+// buildStarFilter moved to core/daily-logic.ts so the dashboard layer can
+// reuse it without crossing the commands → sibling-command boundary
+// (#1208 M7). Re-exported here for backward compatibility with anyone
+// importing from this module.
+import { buildStarFilter } from '../core/daily-logic.js';
+export { buildStarFilter };
 // ---------------------------------------------------------------------------
 // Phase functions
 // ---------------------------------------------------------------------------

package/dist/commands/dashboard-data.js

@@ -9,7 +9,7 @@ import { warn } from '../core/logger.js';
 import { emptyPRCountsResult, fetchMergedPRsSince, fetchClosedPRsSince } from '../core/github-stats.js';
 import { parseGitHubUrl } from '../core/urls.js';
 import { isBelowMinStars, } from '../core/types.js';
-import { toShelvedPRRef, buildStarFilter } from './daily.js';
+import { toShelvedPRRef, buildStarFilter } from '../core/index.js';
 const MODULE = 'dashboard-data';
 export function buildDashboardStats(digest, state, storedMergedCount, storedClosedCount) {
     const summary = digest.summary || {

package/dist/commands/dashboard-server.js

@@ -265,6 +265,11 @@ export async function startDashboardServer(options) {
     // not disappear when /api/data rebuilds after a state change or after a
     // POST /api/action completes.
     let cachedPartialFailures = undefined;
+    // Tracks the last background-refresh failure so /api/data can surface
+    // staleness to the SPA via the X-Dashboard-Stale header (#1205). Cleared
+    // when a refresh succeeds. Without this, token expiry / GitHub outage
+    // produces silent stale data hours old with no client-visible signal.
+    let lastBackgroundRefreshError = null;
     if (!cachedDigest) {
         throw new Error('No dashboard data available. Run the daily check first: GITHUB_TOKEN=$(gh auth token) npm start -- daily');
     }
@@ -327,6 +332,14 @@ export async function startDashboardServer(options) {
                         res.setHeader('X-Dashboard-Stale', '1');
                     }
                 }
+                // Surface staleness from a failed background refresh too (#1205) so
+                // token expiry / GitHub outage produces a client-visible signal
+                // rather than silent stale data. Only set the header when a failure
+                // is recorded — successful refreshes clear it.
+                if (lastBackgroundRefreshError !== null) {
+                    res.setHeader('X-Dashboard-Stale', '1');
+                    res.setHeader('X-Dashboard-Stale-Reason', `background-refresh-failed: ${lastBackgroundRefreshError}`);
+                }
                 sendJson(res, 200, cachedJsonData);
                 return;
             }
@@ -598,11 +611,16 @@ export async function startDashboardServer(options) {
             cachedPartialFailures = result.partialFailures.length > 0 ? result.partialFailures : undefined;
             cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues, result.allMergedPRs, result.allClosedPRs, cachedPartialFailures);
             cachedIssueListMtimeMs = getIssueListMtimeMs();
+            // Successful refresh clears any prior failure signal (#1205).
+            lastBackgroundRefreshError = null;
             warn(MODULE, 'Background data refresh complete');
             return;
         })
             .catch((error) => {
-            warn(MODULE, `Background data refresh failed (serving cached data): ${errorMessage(error)}`);
+            // Capture so /api/data can surface staleness via X-Dashboard-Stale
+            // header — previously the catch only logged to stderr (#1205).
+            lastBackgroundRefreshError = errorMessage(error);
+            warn(MODULE, `Background data refresh failed (serving cached data): ${lastBackgroundRefreshError}`);
         });
     }
     // ── Open browser ─────────────────────────────────────────────────────────

package/dist/commands/guidelines.d.ts

@@ -27,6 +27,16 @@ export interface FetchCorpusOutput {
     prCount: number;
     /** PRs skipped because `commentsFetchedAt` is already set (without --force). */
     skipped: number;
+    /**
+     * PRs that were attempted but errored (404, rate limit, transient API
+     * failure). Surfaced so the host can decide whether to retry or warn the
+     * user that the corpus is partial. Empty array when all attempted fetches
+     * succeeded. (#1209 L8)
+     */
+    failures: Array<{
+        prUrl: string;
+        error: string;
+    }>;
 }
 interface RepoOption {
     repo: string;

package/dist/commands/guidelines.js

@@ -108,7 +108,11 @@ export async function runFetchCorpus(options) {
     const eligible = candidates.filter((c) => {
         if (!c.url.startsWith(repoUrlPrefix))
             return false;
-        if (Date.parse(c.timestamp || '') < cutoffMs)
+        // Date.parse('') is NaN, and `NaN < cutoffMs` is false — the previous
+        // form silently passed PRs with empty/malformed timestamps through the
+        // recency cliff (#1204). Number.isFinite filters those out explicitly.
+        const ts = Date.parse(c.timestamp || '');
+        if (!Number.isFinite(ts) || ts < cutoffMs)
             return false;
         return true;
     });
@@ -118,10 +122,12 @@ export async function runFetchCorpus(options) {
     const skipped = options.forceRefetch ? 0 : eligible.filter((c) => c.alreadyFetched).length;
     const toFetch = (options.forceRefetch ? eligible : eligible.filter((c) => !c.alreadyFetched))
         // Most-recent first so the host always sees the freshest signal in its corpus window.
+        // After the eligibility filter (#1204), every entry has a finite Date.parse,
+        // so the comparator is well-defined.
         .sort((a, b) => Date.parse(b.timestamp || '') - Date.parse(a.timestamp || ''))
         .slice(0, limit);
     if (toFetch.length === 0) {
-        return { repo: options.repo, bundles: [], prCount: 0, skipped };
+        return { repo: options.repo, bundles: [], prCount: 0, skipped, failures: [] };
     }
     const token = requireGitHubToken();
     const octokit = getOctokit(token);
@@ -129,7 +135,7 @@ export async function runFetchCorpus(options) {
     if (!username) {
         warn(MODULE, 'githubUsername is not set; bot/own-comment filtering will be incomplete');
     }
-    const bundles = await fetchPRCommentBundlesBatch(octokit, toFetch.map((c) => c.url), username);
+    const { bundles, failures } = await fetchPRCommentBundlesBatch(octokit, toFetch.map((c) => c.url), username);
     // Stamp commentsFetchedAt on each PR we successfully fetched — the bundle
     // list mirrors the input order until paginateAll fan-out, so we mark on
     // a per-bundle basis to be safe.
@@ -148,6 +154,7 @@ export async function runFetchCorpus(options) {
         bundles,
         prCount: bundles.length,
         skipped,
+        failures,
     };
 }
 function clampLimit(limit) {

package/dist/commands/validation.js

@@ -2,6 +2,7 @@
  * Shared validation patterns and helpers for CLI commands.
  */
 import { ValidationError } from '../core/errors.js';
+import { isPlaceholderUsername } from '../core/placeholder-usernames.js';
 /** Matches GitHub PR URLs: https://github.com/owner/repo/pull/123 */
 export const PR_URL_PATTERN = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+$/;
 /** Matches GitHub issue URLs: https://github.com/owner/repo/issues/123 */
@@ -106,5 +107,13 @@ export function validateGitHubUsername(username) {
     if (CONSECUTIVE_HYPHENS_PATTERN.test(trimmed)) {
         throw new ValidationError('GitHub username cannot contain consecutive hyphens.');
     }
+    // Reject the same placeholder strings that pr-monitor's runtime auto-repair
+    // catches. Without this guard `init`, `setup --set username=`, and the MCP
+    // `config` tool happily persist values like "example-user" copied from
+    // documentation, leaving auto-repair to clean up after the next fetch and
+    // surfacing a "showing partial data" banner on the dashboard in the meantime.
+    if (isPlaceholderUsername(trimmed)) {
+        throw new ValidationError(`"${trimmed}" looks like a placeholder from documentation, not a real GitHub username. Use your actual GitHub login.`);
+    }
     return trimmed;
 }

package/dist/core/auth.js

@@ -8,7 +8,7 @@
  */
 import { execFileSync, execFile } from 'node:child_process';
 import { ConfigurationError } from './errors.js';
-import { debug } from './logger.js';
+import { debug, warn } from './logger.js';
 const MODULE = 'auth';
 // Cached GitHub token (fetched once per session)
 let cachedGitHubToken = null;
@@ -47,7 +47,10 @@ export function getGitHubToken() {
         }
     }
     catch (err) {
-        debug(MODULE, 'gh auth token failed (CLI unavailable or not authenticated)', err);
+        // Promote to warn-once-per-session so a slow `gh` (2s timeout) or a
+        // misconfigured CLI is visible without DEBUG=1 (#1209 L6). The
+        // tokenFetchAttempted cache means subsequent calls don't re-warn.
+        warn(MODULE, `gh auth token failed (CLI unavailable or not authenticated): ${err instanceof Error ? err.message : String(err)}`);
     }
     return null;
 }
@@ -117,7 +120,8 @@ export async function getGitHubTokenAsync() {
         }
     }
     catch (err) {
-        debug(MODULE, 'gh auth token failed (CLI unavailable or not authenticated)', err);
+        // Same warn-once promotion as the sync version (#1209 L6).
+        warn(MODULE, `gh auth token failed (CLI unavailable or not authenticated): ${err instanceof Error ? err.message : String(err)}`);
     }
     return null;
 }

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

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

package/dist/core/daily-logic.js

@@ -129,6 +129,29 @@ export function toShelvedPRRef(pr) {
         status: pr.status,
     };
 }
+/**
+ * Build a star filter from state for use in fetchUserPRCounts.
+ *
+ * Returns undefined if no star data is available (first run). Pure logic
+ * over `Readonly<AgentState>` — lives here in core/daily-logic.ts so the
+ * dashboard layer can reuse it without importing from a sibling command
+ * module (#1208 M7).
+ *
+ * @param state - Current agent state (read-only)
+ * @returns Star filter with minimum threshold and known counts, or undefined on first run
+ */
+export function buildStarFilter(state) {
+    const minStars = state.config.minStars ?? 50;
+    const knownStarCounts = new Map();
+    for (const [repo, score] of Object.entries(state.repoScores)) {
+        if (score.stargazersCount !== undefined) {
+            knownStarCounts.set(repo, score.stargazersCount);
+        }
+    }
+    if (knownStarCounts.size === 0)
+        return undefined;
+    return { minStars, knownStarCounts };
+}
 /**
  * Group PRs by repository (#80).
  * Ensures one agent per repo during parallel dispatch, preventing branch checkout conflicts.

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

@@ -44,6 +44,22 @@ export interface BootstrapResult {
     /** True when state was loaded from local cache due to API failure. */
     degraded?: boolean;
 }
+/**
+ * Discriminated outcome of {@link GistStateStore.refreshFromGist} (#1209 L9).
+ * Lets callers distinguish "got fresh data" from "throttled / no-op / failed"
+ * without conflating them as a single boolean.
+ */
+export type RefreshResult = {
+    status: 'refreshed';
+} | {
+    status: 'no-gist';
+} | {
+    status: 'throttled';
+    sinceLastMs: number;
+} | {
+    status: 'error';
+    error: Error;
+};
 /**
  * Minimal Octokit-shaped interface for the Gist API methods we use.
  * Accepts the real ThrottledOctokit or a plain mock object in tests.
@@ -194,8 +210,15 @@ export declare class GistStateStore {
     /**
      * Re-fetch the Gist and update the in-memory cache.
      * Throttled to at most once per 30 seconds.
+     *
+     * Returns a discriminated union so callers can tell apart the four
+     * outcomes that previously collapsed into a single boolean (#1209 L9):
+     *   - `{ status: 'refreshed' }` — fresh data loaded successfully.
+     *   - `{ status: 'no-gist' }` — store not in Gist mode (e.g. degraded).
+     *   - `{ status: 'throttled', sinceLastMs }` — within the 30s throttle.
+     *   - `{ status: 'error', error }` — fetch attempt failed.
      */
-    refreshFromGist(): Promise<boolean>;
+    refreshFromGist(): Promise<RefreshResult>;
     /**
      * Preflight check: verify the token has Gist API scope.
      * Costs one cheap API call; catches permission issues early with a clear message.

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

@@ -422,25 +422,35 @@ export class GistStateStore {
     /**
      * Re-fetch the Gist and update the in-memory cache.
      * Throttled to at most once per 30 seconds.
+     *
+     * Returns a discriminated union so callers can tell apart the four
+     * outcomes that previously collapsed into a single boolean (#1209 L9):
+     *   - `{ status: 'refreshed' }` — fresh data loaded successfully.
+     *   - `{ status: 'no-gist' }` — store not in Gist mode (e.g. degraded).
+     *   - `{ status: 'throttled', sinceLastMs }` — within the 30s throttle.
+     *   - `{ status: 'error', error }` — fetch attempt failed.
      */
     async refreshFromGist() {
         if (!this.gistId)
-            return false;
+            return { status: 'no-gist' };
         const now = Date.now();
+        const sinceLastMs = now - this.lastRefreshAt;
         // Throttle hits are not failures — preserve any previous lastRefreshError
         // for the caller to inspect.
-        if (now - this.lastRefreshAt < GistStateStore.REFRESH_THROTTLE_MS)
-            return false;
+        if (sinceLastMs < GistStateStore.REFRESH_THROTTLE_MS) {
+            return { status: 'throttled', sinceLastMs };
+        }
         try {
             await this.fetchAndCache(this.gistId);
             this.lastRefreshAt = now;
             this.lastRefreshError = null;
-            return true;
+            return { status: 'refreshed' };
         }
         catch (err) {
-            warn(MODULE, `refreshFromGist failed: ${err}`);
-            this.lastRefreshError = err instanceof Error ? err : new Error(String(err));
-            return false;
+            const error = err instanceof Error ? err : new Error(String(err));
+            warn(MODULE, `refreshFromGist failed: ${error.message}`);
+            this.lastRefreshError = error;
+            return { status: 'error', error };
         }
     }
     // ── Private helpers ─────────────────────────────────────────────────

package/dist/core/http-cache.js

@@ -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;
         }
     }

package/dist/core/index.d.ts

@@ -18,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';
@@ -26,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

@@ -19,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';
@@ -27,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/placeholder-usernames.d.ts

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

package/dist/core/placeholder-usernames.js

@@ -0,0 +1,34 @@
+/**
+ * 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',
+    // GitHub's mascot accounts. Real users on github.com but seeded into countless
+    // example configs, READMEs, and SDK docs (Octokit's quickstarts use `octocat`
+    // as the canonical login). Treating them as placeholders keeps a stale example
+    // value from silently swapping a real user's PR feed with the mascot's open
+    // PRs in violet-org/boysenberry-repo (octocat's public test fixtures).
+    'octocat',
+    'monalisa',
+];
+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

@@ -28,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/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;