@oss-autopilot/core 0.44.2 → 0.44.15

package/dist/core/pr-monitor.js

@@ -13,7 +13,7 @@
  */
 import { getOctokit } from './github.js';
 import { getStateManager } from './state.js';
-import { daysBetween, parseGitHubUrl, extractOwnerRepo } from './utils.js';
+import { daysBetween, parseGitHubUrl, extractOwnerRepo, DEFAULT_CONCURRENCY } from './utils.js';
 import { runWorkerPool } from './concurrency.js';
 import { ConfigurationError, ValidationError, errorMessage, getHttpStatusCode } from './errors.js';
 import { paginateAll } from './pagination.js';
@@ -31,8 +31,7 @@ export { computeDisplayLabel } from './display-utils.js';
 export { classifyCICheck, classifyFailingChecks } from './ci-analysis.js';
 export { isConditionalChecklistItem } from './checklist-analysis.js';
 const MODULE = 'pr-monitor';
-// Concurrency limit for parallel API calls
-const MAX_CONCURRENT_REQUESTS = 5;
+const MAX_CONCURRENT_REQUESTS = DEFAULT_CONCURRENCY;
 export class PRMonitor {
     octokit;
     stateManager;
@@ -120,27 +119,11 @@ export class PRMonitor {
                 }
             }, MAX_CONCURRENT_REQUESTS);
         });
-        // Sort by days since activity (most urgent first)
+        // Sort by status (needs_addressing first, then waiting_on_maintainer)
         prs.sort((a, b) => {
-            // Priority: needs_response > failing_ci > merge_conflict > approaching_dormant > dormant > waiting > healthy
-            const statusPriority = {
-                needs_response: 0,
-                needs_changes: 1,
-                failing_ci: 2,
-                ci_blocked: 3,
-                ci_not_running: 4,
-                merge_conflict: 5,
-                needs_rebase: 6,
-                missing_required_files: 7,
-                incomplete_checklist: 8,
-                changes_addressed: 9,
-                approaching_dormant: 10,
-                dormant: 11,
-                waiting: 12,
-                waiting_on_maintainer: 13,
-                healthy: 14,
-            };
-            return statusPriority[a.status] - statusPriority[b.status];
+            if (a.status === b.status)
+                return 0;
+            return a.status === 'needs_addressing' ? -1 : 1;
         });
         return { prs, failures };
     }
@@ -196,14 +179,18 @@ export class PRMonitor {
         const { hasUnrespondedComment, lastMaintainerComment } = checkUnrespondedComments(comments, reviews, reviewComments, config.githubUsername);
         // Fetch CI status and (conditionally) latest commit date in parallel
         // We need the commit date when hasUnrespondedComment is true (to distinguish
-        // "needs_response" from "changes_addressed") OR when reviewDecision is "changes_requested"
+        // "needs_response" from "waiting_on_maintainer") OR when reviewDecision is "changes_requested"
         // (to detect needs_changes: review requested changes but no new commits pushed)
         const ciPromise = this.getCIStatus(owner, repo, ghPR.head.sha);
         const needCommitDate = hasUnrespondedComment || reviewDecision === 'changes_requested';
-        const commitDatePromise = needCommitDate
+        const commitInfoPromise = needCommitDate
             ? this.octokit.repos
                 .getCommit({ owner, repo, ref: ghPR.head.sha })
-                .then((res) => res.data.commit.author?.date)
+                .then((res) => ({
+                date: res.data.commit.author?.date,
+                // GitHub user login of the commit author (may differ from git author)
+                author: res.data.author?.login,
+            }))
                 .catch((err) => {
                 // Rate limit errors must propagate — silently swallowing them produces
                 // misleading status (e.g. needs_changes when changes were addressed) (#469).
@@ -222,10 +209,12 @@ export class PRMonitor {
                 return undefined;
             })
             : Promise.resolve(undefined);
-        const [{ status: ciStatus, failingCheckNames, failingCheckConclusions }, latestCommitDate] = await Promise.all([
+        const [{ status: ciStatus, failingCheckNames, failingCheckConclusions }, commitInfo] = await Promise.all([
             ciPromise,
-            commitDatePromise,
+            commitInfoPromise,
         ]);
+        const latestCommitDate = commitInfo?.date;
+        const latestCommitAuthor = commitInfo?.author;
         // Analyze PR body for incomplete checklists (delegated to checklist-analysis module)
         const { hasIncompleteChecklist, checklistStats } = analyzeChecklist(ghPR.body || '');
         // Extract maintainer action hints from comments (delegated to maintainer-analysis module)
@@ -238,7 +227,7 @@ export class PRMonitor {
         const classifiedChecks = classifyFailingChecks(failingCheckNames, failingCheckConclusions);
         // Determine status
         const hasActionableCIFailure = ciStatus === 'failing' && classifiedChecks.some((c) => c.category === 'actionable');
-        const status = this.determineStatus({
+        const { status, actionReason, waitReason, stalenessTier } = this.determineStatus({
             ciStatus,
             hasMergeConflict,
             hasUnrespondedComment,
@@ -248,6 +237,8 @@ export class PRMonitor {
             dormantThreshold: config.dormantThresholdDays,
             approachingThreshold: config.approachingDormantDays,
             latestCommitDate,
+            latestCommitAuthor,
+            contributorUsername: config.githubUsername,
             lastMaintainerCommentDate: lastMaintainerComment?.createdAt,
             latestChangesRequestedDate,
             hasActionableCIFailure,
@@ -259,6 +250,9 @@ export class PRMonitor {
             number,
             title: ghPR.title,
             status,
+            actionReason,
+            waitReason,
+            stalenessTier,
             createdAt: ghPR.created_at,
             updatedAt: ghPR.updated_at,
             daysSinceActivity,
@@ -295,61 +289,110 @@ export class PRMonitor {
      * Determine the overall status of a PR
      */
     determineStatus(input) {
-        const { ciStatus, hasMergeConflict, hasUnrespondedComment, hasIncompleteChecklist, reviewDecision, daysSinceActivity, dormantThreshold, approachingThreshold, latestCommitDate, lastMaintainerCommentDate, latestChangesRequestedDate, hasActionableCIFailure = true, } = input;
-        // Priority order: needs_response/needs_changes/changes_addressed > failing_ci > merge_conflict > incomplete_checklist > dormant > approaching_dormant > waiting_on_maintainer > waiting/healthy
+        const { ciStatus, hasMergeConflict, hasUnrespondedComment, hasIncompleteChecklist, reviewDecision, daysSinceActivity, dormantThreshold, approachingThreshold, latestCommitDate: rawCommitDate, latestCommitAuthor, contributorUsername, lastMaintainerCommentDate, latestChangesRequestedDate, hasActionableCIFailure = true, } = input;
+        // Compute staleness tier (independent of status)
+        let stalenessTier = 'active';
+        if (daysSinceActivity >= dormantThreshold)
+            stalenessTier = 'dormant';
+        else if (daysSinceActivity >= approachingThreshold)
+            stalenessTier = 'approaching_dormant';
+        // Only count the latest commit if it was authored by the contributor or a
+        // CI bot (#547, #568). Non-contributor commits (maintainer merge commits,
+        // GitHub suggestion commits) should not mask unaddressed feedback.
+        const latestCommitDate = rawCommitDate && this.isContributorCommit(latestCommitAuthor, contributorUsername) ? rawCommitDate : undefined;
+        // Priority order: needs_addressing (response/changes/ci/conflict/checklist) > waiting_on_maintainer (review/merge/addressed/ci_blocked)
         if (hasUnrespondedComment) {
             // If the contributor pushed a commit after the maintainer's comment,
-            // the changes have been addressed — waiting for maintainer re-review
-            if (latestCommitDate && lastMaintainerCommentDate && latestCommitDate > lastMaintainerCommentDate) {
+            // the changes have been addressed — waiting for maintainer re-review.
+            // Require a minimum 2-minute gap to avoid false positives from race
+            // conditions (pushing while review is being submitted) (#547).
+            if (latestCommitDate &&
+                lastMaintainerCommentDate &&
+                this.isCommitAfterComment(latestCommitDate, lastMaintainerCommentDate)) {
                 // Safety net (#431): if a CHANGES_REQUESTED review was submitted after
                 // the commit, the maintainer still expects changes — don't mask it
                 if (latestChangesRequestedDate && latestCommitDate < latestChangesRequestedDate) {
-                    return 'needs_response';
+                    return { status: 'needs_addressing', actionReason: 'needs_response', stalenessTier };
                 }
                 if (ciStatus === 'failing' && hasActionableCIFailure)
-                    return 'failing_ci';
+                    return { status: 'needs_addressing', actionReason: 'failing_ci', stalenessTier };
                 // Non-actionable CI failures (infrastructure, fork, auth) don't block changes_addressed —
                 // the contributor can't fix them, so the relevant status is "waiting for re-review" (#502)
-                return 'changes_addressed';
+                return { status: 'waiting_on_maintainer', waitReason: 'changes_addressed', stalenessTier };
             }
-            return 'needs_response';
+            return { status: 'needs_addressing', actionReason: 'needs_response', stalenessTier };
         }
         // Review requested changes but no unresponded comment.
         // If the latest commit is before the review, the contributor hasn't addressed it yet.
         if (reviewDecision === 'changes_requested' && latestChangesRequestedDate) {
             if (!latestCommitDate || latestCommitDate < latestChangesRequestedDate) {
-                return 'needs_changes';
+                return { status: 'needs_addressing', actionReason: 'needs_changes', stalenessTier };
             }
             // Commit is after review — changes have been addressed
             if (ciStatus === 'failing' && hasActionableCIFailure)
-                return 'failing_ci';
+                return { status: 'needs_addressing', actionReason: 'failing_ci', stalenessTier };
             // Non-actionable CI failures don't block changes_addressed (#502)
-            return 'changes_addressed';
+            return { status: 'waiting_on_maintainer', waitReason: 'changes_addressed', stalenessTier };
         }
         if (ciStatus === 'failing') {
-            return hasActionableCIFailure ? 'failing_ci' : 'ci_blocked';
+            return hasActionableCIFailure
+                ? { status: 'needs_addressing', actionReason: 'failing_ci', stalenessTier }
+                : { status: 'waiting_on_maintainer', waitReason: 'ci_blocked', stalenessTier };
         }
         if (hasMergeConflict) {
-            return 'merge_conflict';
+            return { status: 'needs_addressing', actionReason: 'merge_conflict', stalenessTier };
         }
         if (hasIncompleteChecklist) {
-            return 'incomplete_checklist';
-        }
-        if (daysSinceActivity >= dormantThreshold) {
-            return 'dormant';
-        }
-        if (daysSinceActivity >= approachingThreshold) {
-            return 'approaching_dormant';
+            return { status: 'needs_addressing', actionReason: 'incomplete_checklist', stalenessTier };
         }
         // Approved and CI passing/unknown = waiting on maintainer to merge
         if (reviewDecision === 'approved' && (ciStatus === 'passing' || ciStatus === 'unknown')) {
-            return 'waiting_on_maintainer';
+            return { status: 'waiting_on_maintainer', waitReason: 'pending_merge', stalenessTier };
         }
-        // CI pending means we're waiting
-        if (ciStatus === 'pending') {
-            return 'waiting';
+        // Default: no actionable issues found. Covers pending CI, no reviews yet, etc.
+        return { status: 'waiting_on_maintainer', waitReason: 'pending_review', stalenessTier };
+    }
+    /**
+     * CI-fix bots that push commits as a direct result of the contributor's push (#568).
+     * Their commits represent contributor work and should count as addressing feedback.
+     * This is intentionally an allowlist — not all `[bot]` accounts are CI-fix bots
+     * (e.g. dependabot[bot] and renovate[bot] open their own PRs).
+     * Values must be lowercase — lookup uses .toLowerCase() for case-insensitive matching.
+     */
+    static CI_FIX_BOTS = new Set([
+        'autofix-ci[bot]',
+        'prettier-ci[bot]',
+        'pre-commit-ci[bot]',
+    ]);
+    /**
+     * Check whether the HEAD commit was authored by the contributor (#547).
+     * Returns true when the author matches, when the author is a known CI-fix
+     * bot (#568), or when author info is unavailable (graceful degradation).
+     */
+    isContributorCommit(commitAuthor, contributorUsername) {
+        if (!commitAuthor || !contributorUsername)
+            return true; // degrade gracefully
+        const author = commitAuthor.toLowerCase();
+        if (PRMonitor.CI_FIX_BOTS.has(author))
+            return true; // CI-fix bots act on behalf of the contributor (#568)
+        return author === contributorUsername.toLowerCase();
+    }
+    /** Minimum gap (ms) between maintainer comment and contributor commit for
+     *  the commit to count as "addressing" the feedback (#547). Prevents false
+     *  positives from race conditions, clock skew, and in-flight pushes. */
+    static MIN_RESPONSE_GAP_MS = 2 * 60 * 1000; // 2 minutes
+    /**
+     * Check whether the contributor's commit is meaningfully after the maintainer's
+     * comment — i.e. the commit timestamp is at least MIN_RESPONSE_GAP_MS later (#547).
+     */
+    isCommitAfterComment(commitDate, commentDate) {
+        const commitMs = new Date(commitDate).getTime();
+        const commentMs = new Date(commentDate).getTime();
+        if (Number.isNaN(commitMs) || Number.isNaN(commentMs)) {
+            // Fall back to simple string comparison (pre-#547 behavior)
+            return commitDate > commentDate;
         }
-        return 'healthy';
+        return commitMs - commentMs >= PRMonitor.MIN_RESPONSE_GAP_MS;
     }
     /**
      * Check if PR has merge conflict
@@ -427,17 +470,17 @@ export class PRMonitor {
      * Fetch merged PR counts and latest merge dates per repository for the configured user.
      * Delegates to github-stats module.
      */
-    async fetchUserMergedPRCounts() {
+    async fetchUserMergedPRCounts(starFilter) {
         const config = this.stateManager.getState().config;
-        return fetchUserMergedPRCountsImpl(this.octokit, config.githubUsername);
+        return fetchUserMergedPRCountsImpl(this.octokit, config.githubUsername, starFilter);
     }
     /**
      * Fetch closed-without-merge PR counts per repository for the configured user.
      * Delegates to github-stats module.
      */
-    async fetchUserClosedPRCounts() {
+    async fetchUserClosedPRCounts(starFilter) {
         const config = this.stateManager.getState().config;
-        return fetchUserClosedPRCountsImpl(this.octokit, config.githubUsername);
+        return fetchUserClosedPRCountsImpl(this.octokit, config.githubUsername, starFilter);
     }
     /**
      * Fetch GitHub star counts for a list of repositories.
@@ -482,7 +525,7 @@ export class PRMonitor {
             }
             // If entire chunk failed, likely a systemic issue (rate limit, auth, outage) — abort remaining
             if (chunkFailures === chunk.length && chunk.length > 0) {
-                const remaining = repos.length - i - chunkSize;
+                const remaining = uniqueRepos.length - i - chunkSize;
                 if (remaining > 0) {
                     warn(MODULE, `Entire chunk failed, aborting remaining ${remaining} repos`);
                 }
@@ -514,52 +557,22 @@ export class PRMonitor {
     generateDigest(prs, recentlyClosedPRs = [], recentlyMergedPRs = []) {
         const now = new Date().toISOString();
         // Categorize PRs
-        const prsNeedingResponse = prs.filter((pr) => pr.status === 'needs_response');
-        const ciFailingPRs = prs.filter((pr) => pr.status === 'failing_ci');
-        const mergeConflictPRs = prs.filter((pr) => pr.status === 'merge_conflict');
-        const approachingDormant = prs.filter((pr) => pr.status === 'approaching_dormant');
-        const dormantPRs = prs.filter((pr) => pr.status === 'dormant');
-        const healthyPRs = prs.filter((pr) => pr.status === 'healthy' || pr.status === 'waiting');
+        const needsAddressingPRs = prs.filter((pr) => pr.status === 'needs_addressing');
+        const waitingOnMaintainerPRs = prs.filter((pr) => pr.status === 'waiting_on_maintainer');
         // Get stats from state manager (historical data from repo scores)
         const stats = this.stateManager.getStats();
-        const ciBlockedPRs = prs.filter((pr) => pr.status === 'ci_blocked');
-        const ciNotRunningPRs = prs.filter((pr) => pr.status === 'ci_not_running');
-        const needsRebasePRs = prs.filter((pr) => pr.status === 'needs_rebase');
-        const missingRequiredFilesPRs = prs.filter((pr) => pr.status === 'missing_required_files');
-        const incompleteChecklistPRs = prs.filter((pr) => pr.status === 'incomplete_checklist');
-        const needsChangesPRs = prs.filter((pr) => pr.status === 'needs_changes');
-        const changesAddressedPRs = prs.filter((pr) => pr.status === 'changes_addressed');
-        const waitingOnMaintainerPRs = prs.filter((pr) => pr.status === 'waiting_on_maintainer');
         return {
             generatedAt: now,
             openPRs: prs,
-            prsNeedingResponse,
-            ciFailingPRs,
-            ciBlockedPRs,
-            ciNotRunningPRs,
-            mergeConflictPRs,
-            needsRebasePRs,
-            missingRequiredFilesPRs,
-            incompleteChecklistPRs,
-            needsChangesPRs,
-            changesAddressedPRs,
+            needsAddressingPRs,
             waitingOnMaintainerPRs,
-            approachingDormant,
-            dormantPRs,
-            healthyPRs,
             recentlyClosedPRs,
             recentlyMergedPRs,
             shelvedPRs: [],
             autoUnshelvedPRs: [],
             summary: {
                 totalActivePRs: prs.length,
-                totalNeedingAttention: prsNeedingResponse.length +
-                    needsChangesPRs.length +
-                    ciFailingPRs.length +
-                    mergeConflictPRs.length +
-                    needsRebasePRs.length +
-                    missingRequiredFilesPRs.length +
-                    incompleteChecklistPRs.length,
+                totalNeedingAttention: needsAddressingPRs.length,
                 totalMergedAllTime: stats.mergedPRs,
                 mergeRate: parseFloat(stats.mergeRate),
             },

package/dist/core/state.d.ts

@@ -2,7 +2,7 @@
  * State management for the OSS Contribution Agent
  * Persists state to a JSON file in ~/.oss-autopilot/
  */
-import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, StateEvent, StateEventType, DailyDigest, LocalRepoCache, SnoozeInfo } from './types.js';
+import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, StateEvent, StateEventType, DailyDigest, LocalRepoCache, SnoozeInfo, StatusOverride, FetchedPRStatus } from './types.js';
 /**
  * Acquire an advisory file lock using exclusive-create (`wx` flag).
  * If the lock file already exists but is stale (older than LOCK_TIMEOUT_MS or corrupt),
@@ -257,6 +257,27 @@ export declare class StateManager {
      * @returns Array of PR URLs whose snoozes were expired.
      */
     expireSnoozes(): string[];
+    /**
+     * Set a manual status override for a PR.
+     * @param url - The full GitHub PR URL.
+     * @param status - The target status to override to.
+     * @param lastActivityAt - The PR's current updatedAt timestamp (for auto-clear detection).
+     */
+    setStatusOverride(url: string, status: FetchedPRStatus, lastActivityAt: string): void;
+    /**
+     * Clear a status override for a PR.
+     * @param url - The full GitHub PR URL.
+     * @returns true if found and removed, false if no override existed.
+     */
+    clearStatusOverride(url: string): boolean;
+    /**
+     * Get the status override for a PR, if one exists and hasn't been auto-cleared.
+     * @param url - The full GitHub PR URL.
+     * @param currentUpdatedAt - The PR's current updatedAt from GitHub. If newer than
+     *   the stored lastActivityAt, the override is stale and auto-cleared.
+     * @returns The override metadata, or undefined if none exists or it was auto-cleared.
+     */
+    getStatusOverride(url: string, currentUpdatedAt?: string): StatusOverride | undefined;
     /**
      * Get the score record for a repository.
      * @param repo - Repository in "owner/repo" format.

package/dist/core/state.js

@@ -4,7 +4,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { INITIAL_STATE, } from './types.js';
+import { INITIAL_STATE, isBelowMinStars, } from './types.js';
 import { getStatePath, getBackupDir, getDataDir } from './utils.js';
 import { ValidationError, errorMessage } from './errors.js';
 import { debug, warn } from './logger.js';
@@ -843,6 +843,53 @@ export class StateManager {
         }
         return expired;
     }
+    // === Status Overrides ===
+    /**
+     * Set a manual status override for a PR.
+     * @param url - The full GitHub PR URL.
+     * @param status - The target status to override to.
+     * @param lastActivityAt - The PR's current updatedAt timestamp (for auto-clear detection).
+     */
+    setStatusOverride(url, status, lastActivityAt) {
+        if (!this.state.config.statusOverrides) {
+            this.state.config.statusOverrides = {};
+        }
+        this.state.config.statusOverrides[url] = {
+            status,
+            setAt: new Date().toISOString(),
+            lastActivityAt,
+        };
+    }
+    /**
+     * Clear a status override for a PR.
+     * @param url - The full GitHub PR URL.
+     * @returns true if found and removed, false if no override existed.
+     */
+    clearStatusOverride(url) {
+        if (!this.state.config.statusOverrides || !(url in this.state.config.statusOverrides)) {
+            return false;
+        }
+        delete this.state.config.statusOverrides[url];
+        return true;
+    }
+    /**
+     * Get the status override for a PR, if one exists and hasn't been auto-cleared.
+     * @param url - The full GitHub PR URL.
+     * @param currentUpdatedAt - The PR's current updatedAt from GitHub. If newer than
+     *   the stored lastActivityAt, the override is stale and auto-cleared.
+     * @returns The override metadata, or undefined if none exists or it was auto-cleared.
+     */
+    getStatusOverride(url, currentUpdatedAt) {
+        const override = this.state.config.statusOverrides?.[url];
+        if (!override)
+            return undefined;
+        // Auto-clear if the PR has new activity since the override was set
+        if (currentUpdatedAt && currentUpdatedAt > override.lastActivityAt) {
+            this.clearStatusOverride(url);
+            return undefined;
+        }
+        return override;
+    }
     // === Repository Scoring ===
     /**
      * Get the score record for a repository.
@@ -1060,6 +1107,8 @@ export class StateManager {
         for (const [repoKey, score] of Object.entries(this.state.repoScores)) {
             if (this.isExcluded(repoKey))
                 continue;
+            if (isBelowMinStars(score.stargazersCount, this.state.config.minStars ?? 50))
+                continue;
             totalTracked++;
             totalMerged += score.mergedPRCount;
             totalClosed += score.closedWithoutMergeCount;

package/dist/core/test-utils.js

@@ -17,9 +17,11 @@ export function makeFetchedPR(overrides = {}) {
         repo,
         number,
         title: 'Test PR',
-        status: 'healthy',
-        displayLabel: '[Healthy]',
-        displayDescription: 'Everything looks good',
+        status: 'waiting_on_maintainer',
+        waitReason: 'pending_review',
+        stalenessTier: 'active',
+        displayLabel: '[Waiting on Maintainer]',
+        displayDescription: 'Awaiting review',
         createdAt: '2025-06-01T00:00:00Z',
         updatedAt: '2025-06-15T00:00:00Z',
         daysSinceActivity: 2,
@@ -41,20 +43,8 @@ export function makeDailyDigest(overrides = {}) {
     return {
         generatedAt: '2025-06-20T00:00:00Z',
         openPRs: [],
-        prsNeedingResponse: [],
-        ciFailingPRs: [],
-        ciBlockedPRs: [],
-        ciNotRunningPRs: [],
-        mergeConflictPRs: [],
-        needsRebasePRs: [],
-        missingRequiredFilesPRs: [],
-        incompleteChecklistPRs: [],
-        needsChangesPRs: [],
-        changesAddressedPRs: [],
+        needsAddressingPRs: [],
         waitingOnMaintainerPRs: [],
-        approachingDormant: [],
-        dormantPRs: [],
-        healthyPRs: [],
         recentlyClosedPRs: [],
         recentlyMergedPRs: [],
         shelvedPRs: [],

package/dist/core/types.d.ts

@@ -52,37 +52,35 @@ export interface DetermineStatusInput {
     dormantThreshold: number;
     approachingThreshold: number;
     latestCommitDate?: string;
+    /** GitHub login of the HEAD commit's author (from `repos.getCommit`). */
+    latestCommitAuthor?: string;
+    /** GitHub login of the PR contributor (configured username). */
+    contributorUsername?: string;
     lastMaintainerCommentDate?: string;
     latestChangesRequestedDate?: string;
     /** True if at least one failing CI check is classified as 'actionable'. */
     hasActionableCIFailure?: boolean;
 }
 /**
- * Computed status for a {@link FetchedPR}, determined by `PRMonitor.determineStatus()`.
- * Statuses are checked in priority order — the first match wins.
- *
- * **Action required (contributor must act):**
- * - `needs_response` — Maintainer commented after the contributor's last activity
- * - `needs_changes` — Reviewer requested changes (via review, not just a comment)
- * - `failing_ci` — One or more CI checks are failing (at least one is actionable)
- * - `ci_not_running` — No CI checks have been triggered *(reserved)*
- * - `merge_conflict` — PR has merge conflicts with the base branch
- * - `needs_rebase` — PR branch is significantly behind upstream *(reserved)*
- * - `missing_required_files` — Required files like changesets or CLA are missing *(reserved)*
- * - `incomplete_checklist` — PR body has unchecked required checkboxes
- *
- * **Waiting (no action needed right now):**
- * - `ci_blocked` — All failing CI checks are non-actionable (infrastructure, fork limitation, auth gate)
- * - `changes_addressed` — Contributor pushed commits after reviewer feedback; awaiting re-review
- * - `waiting` — CI is pending or no specific action needed
- * - `waiting_on_maintainer` — PR is approved and CI passes; waiting for maintainer to merge
- * - `healthy` — Everything looks good; normal review cycle
+ * Granular reason why a PR needs addressing (contributor's turn).
+ * Active values (produced by determineStatus): needs_response, needs_changes,
+ * failing_ci, merge_conflict, incomplete_checklist.
+ * Reserved (display mappings exist but detection not yet wired): ci_not_running,
+ * needs_rebase, missing_required_files.
+ */
+export type ActionReason = 'needs_response' | 'needs_changes' | 'failing_ci' | 'merge_conflict' | 'incomplete_checklist' | 'ci_not_running' | 'needs_rebase' | 'missing_required_files';
+/** Granular reason why a PR is waiting on the maintainer. */
+export type WaitReason = 'pending_review' | 'pending_merge' | 'changes_addressed' | 'ci_blocked';
+/** How stale is the PR based on days since activity. Orthogonal to status. */
+export type StalenessTier = 'active' | 'approaching_dormant' | 'dormant';
+/**
+ * Top-level classification of a PR's state. Only two values:
+ * - `needs_addressing` — Contributor's turn. See `actionReason` for what to do.
+ * - `waiting_on_maintainer` — Maintainer's turn. See `waitReason` for why.
  *
- * **Staleness warnings:**
- * - `approaching_dormant` — No activity for `approachingDormantDays` (default 25)
- * - `dormant` — No activity for `dormantThresholdDays` (default 30)
+ * Staleness (active/approaching_dormant/dormant) is tracked separately in `stalenessTier`.
  */
-export type FetchedPRStatus = 'needs_response' | 'failing_ci' | 'ci_blocked' | 'ci_not_running' | 'merge_conflict' | 'needs_rebase' | 'missing_required_files' | 'incomplete_checklist' | 'needs_changes' | 'changes_addressed' | 'waiting' | 'waiting_on_maintainer' | 'healthy' | 'approaching_dormant' | 'dormant';
+export type FetchedPRStatus = 'needs_addressing' | 'waiting_on_maintainer';
 /**
  * Hints about what a maintainer is asking for in their review comments.
  * Extracted from comment text by keyword matching.
@@ -101,6 +99,12 @@ export interface FetchedPR {
     title: string;
     /** Computed by `PRMonitor.determineStatus()` based on the fields below. */
     status: FetchedPRStatus;
+    /** Granular reason for needs_addressing status. Undefined when waiting_on_maintainer. */
+    actionReason?: ActionReason;
+    /** Granular reason for waiting_on_maintainer status. Undefined when needs_addressing. */
+    waitReason?: WaitReason;
+    /** How stale the PR is based on activity age. Independent of status — a PR can be both needs_addressing and dormant. */
+    stalenessTier: StalenessTier;
     /** Human-readable status label for consistent display (#79). E.g., "[CI Failing]", "[Needs Response]". */
     displayLabel: string;
     /** Brief description of what's happening (#79). E.g., "3 checks failed", "@maintainer commented". */
@@ -321,21 +325,10 @@ export interface DailyDigest {
     generatedAt: string;
     /** All open PRs authored by the user, fetched from GitHub Search API. */
     openPRs: FetchedPR[];
-    prsNeedingResponse: FetchedPR[];
-    ciFailingPRs: FetchedPR[];
-    ciBlockedPRs: FetchedPR[];
-    ciNotRunningPRs: FetchedPR[];
-    mergeConflictPRs: FetchedPR[];
-    needsRebasePRs: FetchedPR[];
-    missingRequiredFilesPRs: FetchedPR[];
-    incompleteChecklistPRs: FetchedPR[];
-    needsChangesPRs: FetchedPR[];
-    changesAddressedPRs: FetchedPR[];
+    /** PRs where the contributor needs to take action. Subset of openPRs where status === 'needs_addressing'. */
+    needsAddressingPRs: FetchedPR[];
+    /** PRs waiting on the maintainer. Subset of openPRs where status === 'waiting_on_maintainer'. */
     waitingOnMaintainerPRs: FetchedPR[];
-    /** PRs with no activity for 25+ days (configurable via `approachingDormantDays`). */
-    approachingDormant: FetchedPR[];
-    dormantPRs: FetchedPR[];
-    healthyPRs: FetchedPR[];
     /** PRs closed without merge in the last 7 days. Surfaced to alert the contributor. */
     recentlyClosedPRs: ClosedPR[];
     /** PRs merged in the last 7 days. Surfaced as wins in the dashboard. */
@@ -354,7 +347,7 @@ export interface DailyDigest {
         totalActivePRs: number;
         /** Count of PRs requiring contributor action (response, CI fix, conflict resolution, etc.). */
         totalNeedingAttention: number;
-        /** Lifetime merged PR count across all repos, derived from {@link RepoScore} data. */
+        /** Lifetime merged PR count across all repos, derived from RepoScore data. */
         totalMergedAllTime: number;
         /** Percentage of all-time PRs that were merged (merged / (merged + closed)). */
         mergeRate: number;
@@ -411,6 +404,24 @@ export interface SnoozeInfo {
     snoozedAt: string;
     expiresAt: string;
 }
+/** Filter for excluding repos below a minimum star count from PR count queries. */
+export interface StarFilter {
+    minStars: number;
+    knownStarCounts: ReadonlyMap<string, number>;
+}
+/**
+ * Check if a repo should be excluded based on its star count.
+ * Returns true if the repo is known to be below the threshold.
+ * Repos with unknown star counts pass through (fail-open).
+ */
+export declare function isBelowMinStars(stargazersCount: number | undefined, minStars: number): boolean;
+/** Manual status override for a PR, set via dashboard or CLI. Auto-clears when new activity is detected. */
+export interface StatusOverride {
+    status: FetchedPRStatus;
+    setAt: string;
+    /** PR's updatedAt at the time the override was set. Used to detect new activity for auto-clear. */
+    lastActivityAt: string;
+}
 /** User-configurable settings, populated via `/setup-oss` and stored in {@link AgentState}. */
 export interface AgentConfig {
     /** False until the user completes initial setup via `/setup-oss`. */
@@ -457,6 +468,8 @@ export interface AgentConfig {
     dismissedIssues?: Record<string, string>;
     /** PR URLs with snoozed CI failures, mapped to snooze metadata. Snoozed PRs are excluded from actionable CI failure list until expiry. */
     snoozedPRs?: Record<string, SnoozeInfo>;
+    /** Manual status overrides for PRs. Maps PR URL to override metadata. Auto-clears when the PR has new activity. */
+    statusOverrides?: Record<string, StatusOverride>;
 }
 /** Status of a user's comment thread on a GitHub issue. */
 export type IssueConversationStatus = 'new_response' | 'waiting' | 'acknowledged';

package/dist/core/types.js

@@ -1,6 +1,14 @@
 /**
  * Core types for the Open Source Contribution Agent
  */
+/**
+ * Check if a repo should be excluded based on its star count.
+ * Returns true if the repo is known to be below the threshold.
+ * Repos with unknown star counts pass through (fail-open).
+ */
+export function isBelowMinStars(stargazersCount, minStars) {
+    return stargazersCount !== undefined && stargazersCount < minStars;
+}
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
 export const DEFAULT_CONFIG = {
     setupComplete: false,

package/dist/core/utils.d.ts

@@ -1,6 +1,8 @@
 /**
  * Shared utility functions
  */
+/** Default concurrency limit for parallel GitHub API requests. */
+export declare const DEFAULT_CONCURRENCY = 5;
 /**
  * Returns the oss-autopilot data directory path, creating it if it does not exist.
  *