@oss-autopilot/core 0.44.2 → 0.44.15

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

@@ -10,17 +10,21 @@
  *   - formatActionHint — human-readable maintainer action hint label
  *   - formatBriefSummary / formatSummary / printDigest — rendering
  */
-import type { FetchedPR, FetchedPRStatus, DailyDigest, ShelvedPRRef, MaintainerActionHint, ComputedRepoSignals, RepoGroup, CommentedIssue, CommentedIssueWithResponse } from './types.js';
+import type { FetchedPR, FetchedPRStatus, StalenessTier, ActionReason, DailyDigest, ShelvedPRRef, MaintainerActionHint, ComputedRepoSignals, RepoGroup, CommentedIssue, CommentedIssueWithResponse } from './types.js';
 import type { CapacityAssessment, ActionableIssue, ActionMenu } from '../formatters/json.js';
 /**
- * Statuses indicating maintainer engagement or action needed from the contributor.
- * Used both for auto-unshelving shelved PRs and for counting critical issues in capacity assessment.
+ * Statuses indicating action needed from the contributor.
+ * Used for auto-unshelving shelved PRs.
  */
 export declare const CRITICAL_STATUSES: ReadonlySet<FetchedPRStatus>;
-/** Statuses indicating active maintainer engagement (reviews, feedback, merges). */
-export declare const ACTIVE_MAINTAINER_STATUSES: ReadonlySet<FetchedPRStatus>;
-/** Statuses indicating staleness — maintainer comments during these statuses don't count as responsive. */
-export declare const STALE_STATUSES: ReadonlySet<FetchedPRStatus>;
+/**
+ * ActionReason values that indicate high-priority issues blocking capacity.
+ * `incomplete_checklist` is excluded — it's actionable but not blocking.
+ * Used in capacity assessment to determine if user can take on new work.
+ */
+export declare const CRITICAL_ACTION_REASONS: ReadonlySet<ActionReason>;
+/** Staleness tiers indicating staleness — maintainer comments during these tiers don't count as responsive. */
+export declare const STALE_STATUSES: ReadonlySet<StalenessTier>;
 /**
  * Map a full FetchedPR to a lightweight ShelvedPRRef for digest output.
  * Only the fields needed for display are retained, reducing JSON payload size.
@@ -33,9 +37,8 @@ export declare function toShelvedPRRef(pr: FetchedPR): ShelvedPRRef;
 export declare function groupPRsByRepo(prs: FetchedPR[]): RepoGroup[];
 /**
  * Compute per-repo maintainer signals from observed open PR data.
- * - isResponsive: true if any PR in the repo has a maintainer comment and status
- *   is not in STALE_STATUSES
- * - hasActiveMaintainers: true if any PR in the repo has a status in ACTIVE_MAINTAINER_STATUSES
+ * - isResponsive: true if any PR in the repo has a maintainer comment and stalenessTier is active
+ * - hasActiveMaintainers: true if any non-stale PR exists in the repo (stalenessTier is 'active')
  */
 export declare function computeRepoSignals(prs: FetchedPR[]): Map<string, ComputedRepoSignals>;
 /**

package/dist/core/daily-logic.js

@@ -16,24 +16,22 @@ import { warn } from './logger.js';
 // Constants
 // ---------------------------------------------------------------------------
 /**
- * Statuses indicating maintainer engagement or action needed from the contributor.
- * Used both for auto-unshelving shelved PRs and for counting critical issues in capacity assessment.
+ * Statuses indicating action needed from the contributor.
+ * Used for auto-unshelving shelved PRs.
  */
-export const CRITICAL_STATUSES = new Set([
+export const CRITICAL_STATUSES = new Set(['needs_addressing']);
+/**
+ * ActionReason values that indicate high-priority issues blocking capacity.
+ * `incomplete_checklist` is excluded — it's actionable but not blocking.
+ * Used in capacity assessment to determine if user can take on new work.
+ */
+export const CRITICAL_ACTION_REASONS = new Set([
     'needs_response',
     'needs_changes',
     'failing_ci',
     'merge_conflict',
 ]);
-/** Statuses indicating active maintainer engagement (reviews, feedback, merges). */
-export const ACTIVE_MAINTAINER_STATUSES = new Set([
-    'healthy',
-    'waiting_on_maintainer',
-    'changes_addressed',
-    'needs_response',
-    'needs_changes',
-]);
-/** Statuses indicating staleness — maintainer comments during these statuses don't count as responsive. */
+/** Staleness tiers indicating staleness — maintainer comments during these tiers don't count as responsive. */
 export const STALE_STATUSES = new Set(['dormant', 'approaching_dormant']);
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -86,16 +84,15 @@ export function groupPRsByRepo(prs) {
 }
 /**
  * Compute per-repo maintainer signals from observed open PR data.
- * - isResponsive: true if any PR in the repo has a maintainer comment and status
- *   is not in STALE_STATUSES
- * - hasActiveMaintainers: true if any PR in the repo has a status in ACTIVE_MAINTAINER_STATUSES
+ * - isResponsive: true if any PR in the repo has a maintainer comment and stalenessTier is active
+ * - hasActiveMaintainers: true if any non-stale PR exists in the repo (stalenessTier is 'active')
  */
 export function computeRepoSignals(prs) {
     const repoMap = buildRepoMap(prs, 'COMPUTE_SIGNALS');
     const result = new Map();
     for (const [repo, repoPRs] of repoMap) {
-        const isResponsive = repoPRs.some((pr) => pr.lastMaintainerComment && !STALE_STATUSES.has(pr.status));
-        const hasActiveMaintainers = repoPRs.some((pr) => ACTIVE_MAINTAINER_STATUSES.has(pr.status));
+        const isResponsive = repoPRs.some((pr) => pr.lastMaintainerComment && !STALE_STATUSES.has(pr.stalenessTier));
+        const hasActiveMaintainers = repoPRs.some((pr) => !STALE_STATUSES.has(pr.stalenessTier));
         result.set(repo, { isResponsive, hasActiveMaintainers });
     }
     return result;
@@ -106,7 +103,7 @@ export function computeRepoSignals(prs) {
  */
 export function assessCapacity(activePRs, maxActivePRs, shelvedPRCount) {
     const activePRCount = activePRs.length;
-    const criticalIssueCount = activePRs.filter((pr) => CRITICAL_STATUSES.has(pr.status)).length;
+    const criticalIssueCount = activePRs.filter((pr) => pr.status === 'needs_addressing' && pr.actionReason && CRITICAL_ACTION_REASONS.has(pr.actionReason)).length;
     // Has capacity if: under PR limit AND no critical issues
     const underPRLimit = activePRCount < maxActivePRs;
     const noCriticalIssues = criticalIssueCount === 0;
@@ -145,37 +142,56 @@ export function assessCapacity(activePRs, maxActivePRs, shelvedPRCount) {
  */
 export function collectActionableIssues(prs, snoozedUrls = new Set()) {
     const issues = [];
-    // 1. Needs Response (highest priority - someone is waiting for you)
-    for (const pr of prs) {
-        if (pr.status === 'needs_response') {
-            issues.push({ type: 'needs_response', pr, label: '[Needs Response]' });
-        }
-    }
-    // 2. Needs Changes (review requested changes, contributor hasn't pushed new code)
-    for (const pr of prs) {
-        if (pr.status === 'needs_changes') {
-            issues.push({ type: 'needs_changes', pr, label: '[Needs Changes]' });
-        }
-    }
-    // 3. CI Failing (include check names so user can distinguish real CI from validation bots)
-    // Skip snoozed PRs — their CI failures are known and temporarily dismissed
-    for (const pr of prs) {
-        if (pr.status === 'failing_ci' && !snoozedUrls.has(pr.url)) {
-            const checkInfo = pr.failingCheckNames.length > 0 ? ` (${pr.failingCheckNames.join(', ')})` : '';
-            issues.push({ type: 'ci_failing', pr, label: `[CI Failing${checkInfo}]` });
-        }
-    }
-    // 4. Merge Conflicts
-    for (const pr of prs) {
-        if (pr.status === 'merge_conflict') {
-            issues.push({ type: 'merge_conflict', pr, label: '[Merge Conflict]' });
-        }
-    }
-    // 5. Incomplete Checklist
-    for (const pr of prs) {
-        if (pr.status === 'incomplete_checklist') {
-            const stats = pr.checklistStats ? ` (${pr.checklistStats.checked}/${pr.checklistStats.total})` : '';
-            issues.push({ type: 'incomplete_checklist', pr, label: `[Incomplete Checklist${stats}]` });
+    const actionPRs = prs.filter((pr) => pr.status === 'needs_addressing');
+    const reasonOrder = [
+        'needs_response',
+        'needs_changes',
+        'failing_ci',
+        'merge_conflict',
+        'incomplete_checklist',
+    ];
+    for (const reason of reasonOrder) {
+        for (const pr of actionPRs) {
+            if (pr.actionReason !== reason)
+                continue;
+            if (reason === 'failing_ci' && snoozedUrls.has(pr.url))
+                continue;
+            let label;
+            let type;
+            switch (reason) {
+                case 'needs_response':
+                    label = '[Needs Response]';
+                    type = 'needs_response';
+                    break;
+                case 'needs_changes':
+                    label = '[Needs Changes]';
+                    type = 'needs_changes';
+                    break;
+                case 'failing_ci': {
+                    const checkInfo = pr.failingCheckNames.length > 0 ? ` (${pr.failingCheckNames.join(', ')})` : '';
+                    label = `[CI Failing${checkInfo}]`;
+                    type = 'ci_failing';
+                    break;
+                }
+                case 'merge_conflict':
+                    label = '[Merge Conflict]';
+                    type = 'merge_conflict';
+                    break;
+                case 'incomplete_checklist': {
+                    const stats = pr.checklistStats ? ` (${pr.checklistStats.checked}/${pr.checklistStats.total})` : '';
+                    label = `[Incomplete Checklist${stats}]`;
+                    type = 'incomplete_checklist';
+                    break;
+                }
+                default:
+                    // Defensive fallback for ActionReason values not explicitly handled
+                    // above (e.g. ci_not_running, needs_rebase, missing_required_files).
+                    // These aren't in reasonOrder today but this guards future additions.
+                    warn('daily-logic', `Unhandled ActionReason "${reason}" for PR ${pr.url} — falling back to needs_response`);
+                    label = `[${reason}]`;
+                    type = 'needs_response';
+            }
+            issues.push({ type, pr, label });
         }
     }
     return issues;
@@ -252,7 +268,7 @@ export function computeActionMenu(actionableIssues, capacity, commentedIssues =
  * Format a brief one-liner summary for the action-first flow
  */
 export function formatBriefSummary(digest, issueCount, issueResponseCount = 0) {
-    const attentionText = issueCount > 0 ? `${issueCount} need${issueCount === 1 ? 's' : ''} attention` : 'all healthy';
+    const attentionText = issueCount > 0 ? `${issueCount} need${issueCount === 1 ? 's' : ''} attention` : 'all on track';
     const issueReplyText = issueResponseCount > 0 ? ` | ${issueResponseCount} issue repl${issueResponseCount === 1 ? 'y' : 'ies'}` : '';
     return `\u{1F4CA} ${digest.summary.totalActivePRs} Active PRs | ${attentionText}${issueReplyText}`;
 }
@@ -267,80 +283,21 @@ export function formatSummary(digest, capacity, issueResponses = []) {
     lines.push(`\u{1F4CA} **${digest.summary.totalActivePRs} Active PRs** | ${digest.summary.totalMergedAllTime} Merged | ${digest.summary.mergeRate}% Merge Rate`);
     lines.push('\u2713 Dashboard generated \u2014 say "open dashboard" to view in browser');
     lines.push('');
-    // CI Failing
-    if (digest.ciFailingPRs.length > 0) {
-        lines.push('### \u274C CI Failing');
-        for (const pr of digest.ciFailingPRs) {
-            lines.push(`- [${pr.repo}#${pr.number}](${pr.url}): ${pr.title}`);
-            if (pr.failingCheckNames.length > 0) {
-                lines.push(`  \u2514\u2500 Failing: ${pr.failingCheckNames.join(', ')}`);
-            }
-        }
-        lines.push('');
-    }
-    // Merge Conflicts
-    if (digest.mergeConflictPRs.length > 0) {
-        lines.push('### \u26A0\uFE0F Merge Conflicts');
-        for (const pr of digest.mergeConflictPRs) {
-            lines.push(`- [${pr.repo}#${pr.number}](${pr.url}): ${pr.title}`);
-        }
-        lines.push('');
-    }
-    // Needs Response
-    if (digest.prsNeedingResponse.length > 0) {
-        lines.push('### \u{1F4AC} Needs Response');
-        for (const pr of digest.prsNeedingResponse) {
-            const maintainer = pr.lastMaintainerComment?.author || 'maintainer';
-            lines.push(`- [${pr.repo}#${pr.number}](${pr.url}): ${pr.title}`);
-            lines.push(`  \u2514\u2500 @${maintainer} commented`);
-            if (pr.maintainerActionHints.length > 0) {
-                const hintLabels = pr.maintainerActionHints.map(formatActionHint).join(', ');
-                lines.push(`  \u2514\u2500 Action: ${hintLabels}`);
-            }
-        }
-        lines.push('');
-    }
-    // Needs Changes (review requested changes, no new commits yet)
-    if (digest.needsChangesPRs.length > 0) {
-        lines.push('### \u{1F527} Needs Changes');
-        for (const pr of digest.needsChangesPRs) {
+    // Needs Addressing
+    if (digest.needsAddressingPRs.length > 0) {
+        lines.push('### \u274C Needs Addressing');
+        for (const pr of digest.needsAddressingPRs) {
             lines.push(`- [${pr.repo}#${pr.number}](${pr.url}): ${pr.title}`);
-            lines.push(`  \u2514\u2500 Review requested changes \u2014 push commits to address`);
+            lines.push(`  \u2514\u2500 ${pr.displayLabel} ${pr.displayDescription}`);
         }
         lines.push('');
     }
-    // Incomplete Checklist
-    if (digest.incompleteChecklistPRs.length > 0) {
-        lines.push('### \u{1F4CB} Incomplete Checklist');
-        for (const pr of digest.incompleteChecklistPRs) {
-            const stats = pr.checklistStats ? ` (${pr.checklistStats.checked}/${pr.checklistStats.total} checked)` : '';
-            lines.push(`- [${pr.repo}#${pr.number}](${pr.url}): ${pr.title}${stats}`);
-        }
-        lines.push('');
-    }
-    // Changes Addressed (waiting for maintainer re-review)
-    if (digest.changesAddressedPRs.length > 0) {
-        lines.push('### \u{1F4E4} Changes Addressed');
-        for (const pr of digest.changesAddressedPRs) {
-            const maintainer = pr.lastMaintainerComment?.author || 'maintainer';
-            lines.push(`- [${pr.repo}#${pr.number}](${pr.url}): ${pr.title}`);
-            lines.push(`  \u2514\u2500 Waiting for @${maintainer} to re-review`);
-        }
-        lines.push('');
-    }
-    // Waiting on Maintainer (approved, no action needed from user)
+    // Waiting on Maintainer
     if (digest.waitingOnMaintainerPRs.length > 0) {
         lines.push('### \u23F3 Waiting on Maintainer');
         for (const pr of digest.waitingOnMaintainerPRs) {
-            lines.push(`- [${pr.repo}#${pr.number}](${pr.url}): ${pr.title} (approved)`);
-        }
-        lines.push('');
-    }
-    // Healthy PRs
-    if (digest.healthyPRs.length > 0) {
-        lines.push('### \u2705 Healthy');
-        for (const pr of digest.healthyPRs) {
             lines.push(`- [${pr.repo}#${pr.number}](${pr.url}): ${pr.title}`);
+            lines.push(`  \u2514\u2500 ${pr.displayDescription}`);
         }
         lines.push('');
     }
@@ -409,63 +366,19 @@ export function printDigest(digest, capacity, commentedIssues = []) {
     console.log(`Merge Rate: ${digest.summary.mergeRate}%`);
     console.log(`\nCapacity: ${capacity.hasCapacity ? '\u2705 Ready for new work' : '\u26A0\uFE0F  Focus on existing work'}`);
     console.log(`  ${capacity.reason}\n`);
-    if (digest.ciFailingPRs.length > 0) {
-        console.log('\u274C CI Failing:');
-        for (const pr of digest.ciFailingPRs) {
-            console.log(`  - ${pr.repo}#${pr.number}: ${pr.title}`);
-            if (pr.failingCheckNames.length > 0) {
-                console.log(`    Failing: ${pr.failingCheckNames.join(', ')}`);
-            }
-        }
-        console.log('');
-    }
-    if (digest.mergeConflictPRs.length > 0) {
-        console.log('\u26A0\uFE0F Merge Conflicts:');
-        for (const pr of digest.mergeConflictPRs) {
-            console.log(`  - ${pr.repo}#${pr.number}: ${pr.title}`);
-        }
-        console.log('');
-    }
-    if (digest.prsNeedingResponse.length > 0) {
-        console.log('\u{1F4AC} Needs Response:');
-        for (const pr of digest.prsNeedingResponse) {
-            console.log(`  - ${pr.repo}#${pr.number}: ${pr.title}`);
-            if (pr.maintainerActionHints.length > 0) {
-                const hintLabels = pr.maintainerActionHints.map(formatActionHint).join(', ');
-                console.log(`    Action: ${hintLabels}`);
-            }
-        }
-        console.log('');
-    }
-    if (digest.needsChangesPRs.length > 0) {
-        console.log('\u{1F527} Needs Changes:');
-        for (const pr of digest.needsChangesPRs) {
+    if (digest.needsAddressingPRs.length > 0) {
+        console.log('\u274C Needs Addressing:');
+        for (const pr of digest.needsAddressingPRs) {
             console.log(`  - ${pr.repo}#${pr.number}: ${pr.title}`);
-            console.log(`    Review requested changes \u2014 push commits to address`);
-        }
-        console.log('');
-    }
-    if (digest.incompleteChecklistPRs.length > 0) {
-        console.log('\u{1F4CB} Incomplete Checklist:');
-        for (const pr of digest.incompleteChecklistPRs) {
-            const stats = pr.checklistStats ? ` (${pr.checklistStats.checked}/${pr.checklistStats.total} checked)` : '';
-            console.log(`  - ${pr.repo}#${pr.number}: ${pr.title}${stats}`);
-        }
-        console.log('');
-    }
-    if (digest.changesAddressedPRs.length > 0) {
-        console.log('\u{1F4E4} Changes Addressed:');
-        for (const pr of digest.changesAddressedPRs) {
-            const maintainer = pr.lastMaintainerComment?.author || 'maintainer';
-            console.log(`  - ${pr.repo}#${pr.number}: ${pr.title}`);
-            console.log(`    Waiting for @${maintainer} to re-review`);
+            console.log(`    ${pr.displayLabel} ${pr.displayDescription}`);
         }
         console.log('');
     }
     if (digest.waitingOnMaintainerPRs.length > 0) {
         console.log('\u23F3 Waiting on Maintainer:');
         for (const pr of digest.waitingOnMaintainerPRs) {
-            console.log(`  - ${pr.repo}#${pr.number}: ${pr.title} (approved)`);
+            console.log(`  - ${pr.repo}#${pr.number}: ${pr.title}`);
+            console.log(`    ${pr.displayDescription}`);
         }
         console.log('');
     }

package/dist/core/display-utils.d.ts

@@ -1,6 +1,10 @@
 /**
  * Display Utils - Human-readable display label computation for PR statuses.
  * Extracted from PRMonitor to isolate presentation logic (#263).
+ *
+ * Uses two reason-keyed maps (ACTION_DISPLAY / WAIT_DISPLAY) instead of a
+ * single status-keyed map, reflecting the 2-status taxonomy where the
+ * granular reason lives in `actionReason` / `waitReason`.
  */
 import { FetchedPR } from './types.js';
 /** Compute display label and description for a FetchedPR (#79). */

package/dist/core/display-utils.js

@@ -1,14 +1,13 @@
 /**
  * Display Utils - Human-readable display label computation for PR statuses.
  * Extracted from PRMonitor to isolate presentation logic (#263).
+ *
+ * Uses two reason-keyed maps (ACTION_DISPLAY / WAIT_DISPLAY) instead of a
+ * single status-keyed map, reflecting the 2-status taxonomy where the
+ * granular reason lives in `actionReason` / `waitReason`.
  */
 import { warn } from './logger.js';
-const MODULE = 'display-utils';
-/**
- * Deterministic mapping from FetchedPRStatus -> human-readable display label (#79).
- * Ensures consistent label text across sessions — agents no longer derive these.
- */
-const STATUS_DISPLAY = {
+const ACTION_DISPLAY = {
     needs_response: {
         label: '[Needs Response]',
         description: (pr) => pr.lastMaintainerComment ? `@${pr.lastMaintainerComment.author} commented` : 'Maintainer awaiting response',
@@ -33,25 +32,20 @@ const STATUS_DISPLAY = {
             return 'One or more CI checks are failing';
         },
     },
-    ci_blocked: {
-        label: '[CI Blocked]',
-        description: (pr) => {
-            const checks = pr.classifiedChecks || [];
-            if (checks.length > 0 && checks.every((c) => c.category !== 'actionable')) {
-                const categories = [...new Set(checks.map((c) => c.category))];
-                return `All failing checks are non-actionable (${categories.join(', ')})`;
-            }
-            return 'CI checks are failing but no action is needed from you';
-        },
+    merge_conflict: {
+        label: '[Merge Conflict]',
+        description: () => 'PR has merge conflicts with the base branch',
+    },
+    incomplete_checklist: {
+        label: '[Incomplete Checklist]',
+        description: (pr) => pr.checklistStats
+            ? `${pr.checklistStats.checked}/${pr.checklistStats.total} items checked`
+            : 'PR body has unchecked required checkboxes',
     },
     ci_not_running: {
         label: '[CI Not Running]',
         description: () => 'No CI checks have been triggered',
     },
-    merge_conflict: {
-        label: '[Merge Conflict]',
-        description: () => 'PR has merge conflicts with the base branch',
-    },
     needs_rebase: {
         label: '[Needs Rebase]',
         description: () => 'PR branch is significantly behind upstream',
@@ -60,48 +54,53 @@ const STATUS_DISPLAY = {
         label: '[Missing Files]',
         description: (pr) => pr.missingRequiredFiles ? `Missing: ${pr.missingRequiredFiles.join(', ')}` : 'Required files are missing',
     },
-    incomplete_checklist: {
-        label: '[Incomplete Checklist]',
-        description: (pr) => pr.checklistStats
-            ? `${pr.checklistStats.checked}/${pr.checklistStats.total} items checked`
-            : 'PR body has unchecked required checkboxes',
-    },
-    changes_addressed: {
-        label: '[Changes Addressed]',
-        description: (pr) => pr.lastMaintainerComment
-            ? `Waiting for @${pr.lastMaintainerComment.author} to re-review`
-            : 'Waiting for maintainer re-review',
-    },
-    waiting: {
-        label: '[Waiting]',
-        description: () => 'CI pending or awaiting review',
+};
+const WAIT_DISPLAY = {
+    pending_review: {
+        label: '[Waiting on Maintainer]',
+        description: () => 'Awaiting review',
     },
-    waiting_on_maintainer: {
+    pending_merge: {
         label: '[Waiting on Maintainer]',
         description: () => 'Approved and CI passes — waiting for merge',
     },
-    healthy: {
-        label: '[Healthy]',
-        description: () => 'Everything looks good — normal review cycle',
-    },
-    approaching_dormant: {
-        label: '[Approaching Dormant]',
-        description: (pr) => `No activity for ${pr.daysSinceActivity} days`,
+    changes_addressed: {
+        label: '[Waiting on Maintainer]',
+        description: (pr) => {
+            if (pr.hasUnrespondedComment && pr.lastMaintainerComment) {
+                return `Changes addressed — waiting for @${pr.lastMaintainerComment.author} to re-review`;
+            }
+            return 'Changes addressed — awaiting re-review';
+        },
     },
-    dormant: {
-        label: '[Dormant]',
-        description: (pr) => `No activity for ${pr.daysSinceActivity} days`,
+    ci_blocked: {
+        label: '[CI Blocked]',
+        description: (pr) => {
+            const checks = pr.classifiedChecks || [];
+            if (checks.length > 0 && checks.every((c) => c.category !== 'actionable')) {
+                const categories = [...new Set(checks.map((c) => c.category))];
+                return `All failing checks are non-actionable (${categories.join(', ')})`;
+            }
+            return 'CI checks are failing but no action is needed from you';
+        },
     },
 };
 /** Compute display label and description for a FetchedPR (#79). */
 export function computeDisplayLabel(pr) {
-    const entry = STATUS_DISPLAY[pr.status];
-    if (!entry) {
-        warn(MODULE, `Unknown status "${pr.status}" for PR #${pr.number} (${pr.url})`);
-        return { displayLabel: `[${pr.status}]`, displayDescription: 'Unknown status' };
+    if (pr.status === 'needs_addressing' && pr.actionReason) {
+        const entry = ACTION_DISPLAY[pr.actionReason];
+        if (entry)
+            return { displayLabel: entry.label, displayDescription: entry.description(pr) };
+    }
+    if (pr.status === 'waiting_on_maintainer' && pr.waitReason) {
+        const entry = WAIT_DISPLAY[pr.waitReason];
+        if (entry)
+            return { displayLabel: entry.label, displayDescription: entry.description(pr) };
+    }
+    // Fallback for missing reason — log so we can identify data issues
+    warn('display-utils', `PR ${pr.url} has status "${pr.status}" but no matching reason (actionReason=${pr.actionReason}, waitReason=${pr.waitReason})`);
+    if (pr.status === 'needs_addressing') {
+        return { displayLabel: '[Needs Addressing]', displayDescription: 'Action required' };
     }
-    return {
-        displayLabel: entry.label,
-        displayDescription: entry.description(pr),
-    };
+    return { displayLabel: '[Waiting on Maintainer]', displayDescription: 'Awaiting maintainer action' };
 }

package/dist/core/errors.d.ts

@@ -2,6 +2,10 @@
  * Custom error type hierarchy for oss-autopilot.
  * Provides structured error codes and specific error classes
  * for different failure categories.
+ *
+ * Error strategy: Rate-limit and auth errors (429, 401, 403+rate-limit) always
+ * propagate to the caller via isRateLimitError/isRateLimitOrAuthError.
+ * Other errors degrade gracefully — modules return partial results and log warnings.
  */
 /**
  * Base error for all oss-autopilot errors.
@@ -31,3 +35,7 @@ export declare function errorMessage(e: unknown): string;
  * Returns undefined if the error doesn't have a numeric `status` property.
  */
 export declare function getHttpStatusCode(error: unknown): number | undefined;
+/** Check if an error is a GitHub rate limit error (429 or rate-limit 403). */
+export declare function isRateLimitError(error: unknown): boolean;
+/** Return true for errors that should propagate (not degrade gracefully): rate limits, auth failures, abuse detection. */
+export declare function isRateLimitOrAuthError(err: unknown): boolean;

package/dist/core/errors.js

@@ -2,6 +2,10 @@
  * Custom error type hierarchy for oss-autopilot.
  * Provides structured error codes and specific error classes
  * for different failure categories.
+ *
+ * Error strategy: Rate-limit and auth errors (429, 401, 403+rate-limit) always
+ * propagate to the caller via isRateLimitError/isRateLimitOrAuthError.
+ * Other errors degrade gracefully — modules return partial results and log warnings.
  */
 /**
  * Base error for all oss-autopilot errors.
@@ -49,3 +53,25 @@ export function getHttpStatusCode(error) {
     }
     return undefined;
 }
+/** Check if an error is a GitHub rate limit error (429 or rate-limit 403). */
+export function isRateLimitError(error) {
+    const status = getHttpStatusCode(error);
+    if (status === 429)
+        return true;
+    if (status === 403) {
+        const msg = errorMessage(error).toLowerCase();
+        return msg.includes('rate limit');
+    }
+    return false;
+}
+/** Return true for errors that should propagate (not degrade gracefully): rate limits, auth failures, abuse detection. */
+export function isRateLimitOrAuthError(err) {
+    const status = getHttpStatusCode(err);
+    if (status === 401 || status === 429)
+        return true;
+    if (status === 403) {
+        const msg = errorMessage(err).toLowerCase();
+        return msg.includes('rate limit') || msg.includes('abuse detection');
+    }
+    return false;
+}

package/dist/core/github-stats.d.ts

@@ -3,7 +3,7 @@
  * Extracted from PRMonitor to isolate statistics-gathering API calls (#263).
  */
 import { Octokit } from '@octokit/rest';
-import { ClosedPR, MergedPR } from './types.js';
+import { ClosedPR, MergedPR, type StarFilter } from './types.js';
 /** TTL for cached PR count results (24 hours — these stats change slowly). */
 export declare const PR_COUNTS_CACHE_TTL_MS: number;
 /** Return type shared by both merged and closed PR count functions. */
@@ -19,7 +19,7 @@ export declare function emptyPRCountsResult<R>(): PRCountsResult<R>;
  * Fetch merged PR counts and latest merge dates per repository for the configured user.
  * Also builds a monthly histogram of all merges for the contribution timeline.
  */
-export declare function fetchUserMergedPRCounts(octokit: Octokit, githubUsername: string): Promise<PRCountsResult<{
+export declare function fetchUserMergedPRCounts(octokit: Octokit, githubUsername: string, starFilter?: StarFilter): Promise<PRCountsResult<{
     count: number;
     lastMergedAt: string;
 }>>;
@@ -27,7 +27,7 @@ export declare function fetchUserMergedPRCounts(octokit: Octokit, githubUsername
  * Fetch closed-without-merge PR counts per repository for the configured user.
  * Used to populate closedWithoutMergeCount in repo scores for accurate merge rate.
  */
-export declare function fetchUserClosedPRCounts(octokit: Octokit, githubUsername: string): Promise<PRCountsResult<number>>;
+export declare function fetchUserClosedPRCounts(octokit: Octokit, githubUsername: string, starFilter?: StarFilter): Promise<PRCountsResult<number>>;
 /**
  * Fetch PRs closed without merge in the last N days.
  * Returns lightweight ClosedPR objects for surfacing in the daily digest.