@oss-autopilot/core 3.11.0 → 3.13.0

package/dist/core/daily-logic.js

@@ -248,62 +248,75 @@ export function collectActionableIssues(prs, lastDigestAt) {
         'merge_conflict',
         'incomplete_checklist',
     ];
-    for (const reason of reasonOrder) {
-        for (const pr of actionPRs) {
-            if (pr.actionReason !== reason)
-                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';
-                }
+    // #1352: every needs_addressing PR produces exactly one entry, including
+    // PRs whose actionReason is missing or outside reasonOrder (the defensive
+    // default below). This keeps the CLI brief's count equal to the dashboard's
+    // needs_attention bucket by construction — previously an unmapped reason
+    // silently dropped the PR from the brief while the dashboard still counted
+    // it. Unmapped reasons sort last.
+    const sortedPRs = [...actionPRs].sort((a, b) => {
+        const rank = (pr) => {
+            const i = reasonOrder.indexOf(pr.actionReason);
+            return i === -1 ? reasonOrder.length : i;
+        };
+        return rank(a) - rank(b);
+    });
+    for (const pr of sortedPRs) {
+        if (pr.actionReason === undefined) {
+            warn('daily-logic', `needs_addressing PR ${pr.url} has no actionReason — defaulting to needs_response`);
+        }
+        const reason = pr.actionReason ?? 'needs_response';
+        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;
             }
-            // A PR is "new" if it was created after the last daily digest (first time seen).
-            // If there's no previous digest (first run) or createdAt is invalid, assume new.
-            const createdTime = new Date(pr.createdAt).getTime();
-            let isNewContribution;
-            if (isNaN(createdTime)) {
-                warn('daily-logic', `Invalid createdAt "${pr.createdAt}" for PR ${pr.url}, assuming new contribution`);
-                isNewContribution = true;
+            case 'incomplete_checklist': {
+                const stats = pr.checklistStats ? ` (${pr.checklistStats.checked}/${pr.checklistStats.total})` : '';
+                label = `[Incomplete Checklist${stats}]`;
+                type = 'incomplete_checklist';
+                break;
             }
-            else {
-                isNewContribution = isNaN(lastDigestTime) || createdTime > lastDigestTime;
+            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, isNewContribution });
         }
+        // A PR is "new" if it was created after the last daily digest (first time seen).
+        // If there's no previous digest (first run) or createdAt is invalid, assume new.
+        const createdTime = new Date(pr.createdAt).getTime();
+        let isNewContribution;
+        if (isNaN(createdTime)) {
+            warn('daily-logic', `Invalid createdAt "${pr.createdAt}" for PR ${pr.url}, assuming new contribution`);
+            isNewContribution = true;
+        }
+        else {
+            isNewContribution = isNaN(lastDigestTime) || createdTime > lastDigestTime;
+        }
+        issues.push({ type, pr, label, isNewContribution });
     }
     return issues;
 }

package/dist/core/index.d.ts

@@ -22,6 +22,8 @@ export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsBy
 export { computeContributionStats, type ContributionStats, type ComputeStatsInput } from './stats.js';
 export { fetchPRTemplate, type PRTemplateResult } from './pr-template.js';
 export { classifyLinkedPR, isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, type LinkedPR, type LinkedPRClassification, type LinkedPRState, } from './linked-pr-classification.js';
+export { classifyIssueAvailability, fetchIssueVerification, type IssueAvailabilityVerdict, type IssueVerification, type LinkedPRLinkType, type VerifiedLinkedPR, type VerifyIssueParams, } from './issue-verification.js';
+export { classifyAttentionBucket, summarizeAttentionBuckets, STUCK_CI_THRESHOLD_DAYS, DORMANT_FOLLOWUP_THRESHOLD_DAYS, type AttentionBucket, type AttentionInput, type AttentionSummary, } from './pr-attention.js';
 export { scanForAntiLLMPolicy, type AntiLLMCategory, type AntiLLMMatch, type AntiLLMScanResult, } from './anti-llm-policy.js';
 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';

package/dist/core/index.js

@@ -23,6 +23,8 @@ export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsBy
 export { computeContributionStats } from './stats.js';
 export { fetchPRTemplate } from './pr-template.js';
 export { classifyLinkedPR, isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, } from './linked-pr-classification.js';
+export { classifyIssueAvailability, fetchIssueVerification, } from './issue-verification.js';
+export { classifyAttentionBucket, summarizeAttentionBuckets, STUCK_CI_THRESHOLD_DAYS, DORMANT_FOLLOWUP_THRESHOLD_DAYS, } from './pr-attention.js';
 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';

package/dist/core/issue-verification.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Deterministic issue verification (#1353, #1354).
+ *
+ * One GraphQL round-trip answers the two questions the issue-scout agent
+ * historically hallucinated: "is this issue actually open?" and "is it
+ * actually taken?". The query fetches the issue's `state`/`stateReason`,
+ * its assignees, every cross-referenced PR with `closingIssuesReferences`,
+ * and `viewer.login` — so "is this my PR?" is derived from the same token
+ * that fetched the data instead of a cached username.
+ *
+ * Classification is a pure function (`classifyIssueAvailability`) so the
+ * verdict rules are unit-testable without network access. The distinction
+ * that matters (#1353): a PR whose `closingIssuesReferences` includes this
+ * issue is a real claim (`closing`); a PR that merely mentions the issue in
+ * its timeline is just a mention (`cross-referenced`) and must not drive a
+ * "Taken" verdict.
+ */
+import type { Octokit } from '@octokit/rest';
+/** How a PR found in the issue's timeline relates to the issue. */
+export type LinkedPRLinkType = 'closing' | 'cross-referenced';
+export interface VerifiedLinkedPR {
+    number: number;
+    url: string;
+    title: string;
+    /** Lowercase normalization of GraphQL's OPEN/CLOSED/MERGED union. */
+    state: 'open' | 'closed' | 'merged';
+    isDraft: boolean;
+    /** PR author login; null for ghost (deleted) accounts. */
+    author: string | null;
+    /** True when the PR author is the authenticated user (case-insensitive). */
+    isOwn: boolean;
+    /** `closing` = the PR's closingIssuesReferences names this issue (a real
+     * claim). `cross-referenced` = timeline mention only (NOT a claim). */
+    linkType: LinkedPRLinkType;
+    updatedAt: string | null;
+}
+/**
+ * The short-circuit signal consumers route on:
+ * - `closed` — issue is not open; stop all further analysis (#1353).
+ * - `own-open-pr` — the authenticated user already has an open closing PR;
+ *   not a new opportunity (#1354).
+ * - `taken` — someone else has an open closing PR, or the issue is assigned
+ *   to someone else.
+ * - `at-risk` — no hard claim, but signals competition or imminent closure
+ *   (open cross-referencing PRs, or a merged closing PR awaiting issue close).
+ * - `available` — open, unassigned, no claiming PRs.
+ */
+export type IssueAvailabilityVerdict = 'closed' | 'own-open-pr' | 'taken' | 'at-risk' | 'available';
+export interface IssueVerification {
+    url: string;
+    owner: string;
+    repo: string;
+    number: number;
+    title: string;
+    /** Lowercase normalization of GraphQL's OPEN/CLOSED union. */
+    state: 'open' | 'closed';
+    /** Lowercase GraphQL IssueStateReason. `completed` = fixed upstream (mark
+     * Done); `not_planned` = wontfix (drop permanently). Note: an OPEN issue
+     * can carry `reopened` — never infer closed-ness from a non-null reason;
+     * branch on `state` only. */
+    stateReason: 'completed' | 'not_planned' | 'reopened' | 'duplicate' | null;
+    closedAt: string | null;
+    assignees: string[];
+    linkedPRs: VerifiedLinkedPR[];
+    verdict: IssueAvailabilityVerdict;
+    verdictReason: string;
+    /** Login of the authenticated user the verdict was computed for. */
+    userLogin: string;
+}
+/** Inputs for the pure verdict classifier — the fetched facts, no I/O. */
+export interface ClassifyIssueAvailabilityInput {
+    state: 'open' | 'closed';
+    stateReason: IssueVerification['stateReason'];
+    assignees: string[];
+    linkedPRs: VerifiedLinkedPR[];
+    userLogin: string;
+}
+/**
+ * Compute the availability verdict from fetched facts. Rules in priority
+ * order; the first match wins.
+ */
+export declare function classifyIssueAvailability(input: ClassifyIssueAvailabilityInput): {
+    verdict: IssueAvailabilityVerdict;
+    verdictReason: string;
+};
+export interface VerifyIssueParams {
+    owner: string;
+    repo: string;
+    number: number;
+}
+export declare function fetchIssueVerification(octokit: Octokit, params: VerifyIssueParams): Promise<IssueVerification>;

package/dist/core/issue-verification.js

@@ -0,0 +1,270 @@
+/**
+ * Deterministic issue verification (#1353, #1354).
+ *
+ * One GraphQL round-trip answers the two questions the issue-scout agent
+ * historically hallucinated: "is this issue actually open?" and "is it
+ * actually taken?". The query fetches the issue's `state`/`stateReason`,
+ * its assignees, every cross-referenced PR with `closingIssuesReferences`,
+ * and `viewer.login` — so "is this my PR?" is derived from the same token
+ * that fetched the data instead of a cached username.
+ *
+ * Classification is a pure function (`classifyIssueAvailability`) so the
+ * verdict rules are unit-testable without network access. The distinction
+ * that matters (#1353): a PR whose `closingIssuesReferences` includes this
+ * issue is a real claim (`closing`); a PR that merely mentions the issue in
+ * its timeline is just a mention (`cross-referenced`) and must not drive a
+ * "Taken" verdict.
+ */
+import { ValidationError } from './errors.js';
+function isSameLogin(a, b) {
+    return a !== null && a !== '' && b !== '' && a.toLowerCase() === b.toLowerCase();
+}
+/**
+ * Compute the availability verdict from fetched facts. Rules in priority
+ * order; the first match wins.
+ */
+export function classifyIssueAvailability(input) {
+    const { state, stateReason, assignees, linkedPRs, userLogin } = input;
+    if (state === 'closed') {
+        const reason = stateReason ?? 'unknown';
+        return {
+            verdict: 'closed',
+            verdictReason: reason === 'not_planned'
+                ? 'issue closed as not planned — drop it permanently'
+                : `issue closed (${reason}) — mark it done upstream`,
+        };
+    }
+    const closingPRs = linkedPRs.filter((pr) => pr.linkType === 'closing');
+    const ownOpenClaim = closingPRs.find((pr) => pr.state === 'open' && pr.isOwn);
+    if (ownOpenClaim) {
+        return {
+            verdict: 'own-open-pr',
+            verdictReason: `you already have an open PR for this issue: ${ownOpenClaim.url}`,
+        };
+    }
+    const otherOpenClaim = closingPRs.find((pr) => pr.state === 'open' && !pr.isOwn);
+    if (otherOpenClaim) {
+        return {
+            verdict: 'taken',
+            verdictReason: `open PR by ${otherOpenClaim.author ?? 'unknown author'} closes this issue: ${otherOpenClaim.url}`,
+        };
+    }
+    const otherAssignees = assignees.filter((login) => !isSameLogin(login, userLogin));
+    if (otherAssignees.length > 0) {
+        return {
+            verdict: 'taken',
+            verdictReason: `assigned to ${otherAssignees.join(', ')}`,
+        };
+    }
+    const mergedClaim = closingPRs.find((pr) => pr.state === 'merged');
+    if (mergedClaim) {
+        return {
+            verdict: 'at-risk',
+            verdictReason: `a merged PR closes this issue (${mergedClaim.url}) — likely resolved, awaiting issue close`,
+        };
+    }
+    const openMention = linkedPRs.find((pr) => pr.linkType === 'cross-referenced' && pr.state === 'open');
+    if (openMention) {
+        return {
+            verdict: 'at-risk',
+            verdictReason: `open PR ${openMention.url} cross-references this issue (mention only, not a claim) — ` +
+                'risk of being superseded by broader work',
+        };
+    }
+    // Self-assignment was filtered out above — don't claim "unassigned" then.
+    const selfAssigned = assignees.length > 0;
+    return {
+        verdict: 'available',
+        verdictReason: selfAssigned ? 'open, assigned to you, no claiming PRs' : 'open, unassigned, no claiming PRs',
+    };
+}
+// ── GraphQL fetch ──────────────────────────────────────────────────────
+const VERIFY_ISSUE_QUERY = /* GraphQL */ `
+  query VerifyIssue($owner: String!, $repo: String!, $number: Int!, $after: String) {
+    viewer {
+      login
+    }
+    repository(owner: $owner, name: $repo) {
+      issue(number: $number) {
+        number
+        title
+        url
+        state
+        stateReason
+        closedAt
+        assignees(first: 10) {
+          nodes {
+            login
+          }
+        }
+        timelineItems(itemTypes: [CROSS_REFERENCED_EVENT], first: 100, after: $after) {
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+          nodes {
+            ... on CrossReferencedEvent {
+              source {
+                ... on PullRequest {
+                  number
+                  url
+                  title
+                  state
+                  isDraft
+                  updatedAt
+                  author {
+                    login
+                  }
+                  closingIssuesReferences(first: 50) {
+                    nodes {
+                      number
+                      repository {
+                        nameWithOwner
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+/**
+ * Fetch + classify in one GraphQL round-trip.
+ *
+ * Throws `ValidationError` when the issue does not exist (or the URL points
+ * at a PR — GitHub's `issue()` resolver returns null for PR numbers).
+ * GraphQL/network/rate-limit errors propagate to the caller; nothing is
+ * swallowed into a degraded verdict.
+ */
+/** True when a GraphQL error response is purely "the repo/issue we asked for
+ * doesn't exist" — a caller-input problem, not an API failure. Requires every
+ * error to be NOT_FOUND *and* rooted at the repository/issue path: a nested
+ * NOT_FOUND (e.g. a cross-referenced source in a deleted repo) must not be
+ * misdiagnosed as "issue not found". Duck-typed so we don't import octokit's
+ * GraphqlResponseError class just for instanceof. */
+function isGraphqlNotFound(error) {
+    const errors = error?.errors;
+    if (!Array.isArray(errors) || errors.length === 0)
+        return false;
+    return errors.every((e) => {
+        if (e?.type !== 'NOT_FOUND')
+            return false;
+        const path = Array.isArray(e.path) ? e.path : [];
+        return path.length <= 2 && (path.length === 0 || (path[0] === 'repository' && (path[1] ?? 'issue') === 'issue'));
+    });
+}
+/**
+ * Hard ceiling on timeline pages (100 events each). Timeline events arrive
+ * oldest-first, so silently stopping early would drop the NEWEST events —
+ * exactly the ones most likely to be the active claiming PR. Past the cap we
+ * fail loudly instead of returning a possibly-false `available`.
+ */
+const MAX_TIMELINE_PAGES = 20;
+export async function fetchIssueVerification(octokit, params) {
+    const { owner, repo, number } = params;
+    let issue;
+    let userLogin;
+    const timelineNodes = [];
+    let after = null;
+    for (let page = 0;; page++) {
+        if (page >= MAX_TIMELINE_PAGES) {
+            throw new Error(`Issue ${owner}/${repo}#${number} has more than ${MAX_TIMELINE_PAGES * 100} cross-reference events; ` +
+                'refusing to verify on a truncated timeline. Check the issue manually.');
+        }
+        let response;
+        try {
+            response = await octokit.graphql(VERIFY_ISSUE_QUERY, {
+                owner,
+                repo,
+                number,
+                after,
+            });
+        }
+        catch (error) {
+            // GitHub reports a missing repo/issue as a NOT_FOUND GraphQL error (the
+            // client throws before our null check below can run). Surface it as the
+            // same ValidationError; everything else (rate limits, network, auth)
+            // propagates untouched.
+            if (isGraphqlNotFound(error)) {
+                throw new ValidationError(`Issue not found: ${owner}/${repo}#${number}. ` +
+                    'Check the URL — it may point at a pull request or a deleted/private issue.');
+            }
+            throw error;
+        }
+        const pageIssue = response.repository?.issue;
+        if (!pageIssue) {
+            throw new ValidationError(`Issue not found: ${owner}/${repo}#${number}. ` +
+                'Check the URL — it may point at a pull request or a deleted/private issue.');
+        }
+        issue ??= pageIssue;
+        userLogin = response.viewer.login;
+        timelineNodes.push(...pageIssue.timelineItems.nodes);
+        const pageInfo = pageIssue.timelineItems.pageInfo;
+        if (!pageInfo?.hasNextPage)
+            break;
+        after = pageInfo.endCursor;
+    }
+    // The loop above either assigns both then breaks, or throws.
+    if (!issue || userLogin === undefined) {
+        throw new Error('unreachable: timeline pagination exited without an issue');
+    }
+    const issueRepo = `${owner}/${repo}`.toLowerCase();
+    const linkedPRs = [];
+    const seenUrls = new Set();
+    for (const node of timelineNodes) {
+        const source = node?.source;
+        // CrossReferencedEvent sources can be issues too; PRs are the ones that
+        // carry a `state` from the inline fragment. Skip everything else.
+        if (!source || typeof source.number !== 'number' || !source.url || !source.state)
+            continue;
+        if (seenUrls.has(source.url))
+            continue;
+        seenUrls.add(source.url);
+        // A "closing" link must name THIS issue in THIS repo — closing references
+        // to same-numbered issues in other repos don't count. Deliberate cap:
+        // `closingIssuesReferences(first: 50)` — a PR closing 50+ issues is
+        // pathological; its claim on this one would downgrade to a mention.
+        const closesThisIssue = (source.closingIssuesReferences?.nodes ?? []).some((ref) => ref !== null && ref.number === number && ref.repository.nameWithOwner.toLowerCase() === issueRepo);
+        const author = source.author?.login ?? null;
+        linkedPRs.push({
+            number: source.number,
+            url: source.url,
+            title: source.title ?? '',
+            state: source.state.toLowerCase(),
+            isDraft: source.isDraft ?? false,
+            author,
+            isOwn: isSameLogin(author, userLogin),
+            linkType: closesThisIssue ? 'closing' : 'cross-referenced',
+            updatedAt: source.updatedAt ?? null,
+        });
+    }
+    const state = issue.state.toLowerCase();
+    const stateReason = (issue.stateReason?.toLowerCase() ?? null);
+    const assignees = issue.assignees.nodes.flatMap((n) => (n ? [n.login] : []));
+    const { verdict, verdictReason } = classifyIssueAvailability({
+        state,
+        stateReason,
+        assignees,
+        linkedPRs,
+        userLogin,
+    });
+    return {
+        url: issue.url,
+        owner,
+        repo,
+        number: issue.number,
+        title: issue.title,
+        state,
+        stateReason,
+        closedAt: issue.closedAt,
+        assignees,
+        linkedPRs,
+        verdict,
+        verdictReason,
+        userLogin,
+    };
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Unified PR attention taxonomy (#1352).
+ *
+ * The headline "needs attention" number used to be computed twice — the CLI
+ * brief counted `collectActionableIssues()` output while the dashboard
+ * counted raw `status === 'needs_addressing'` — and the cases the CLI
+ * deliberately excludes (stuck CI, dormant maintainer waits) sat
+ * undifferentiated inside `waiting_on_maintainer`. This module is the single
+ * classifier both surfaces consume.
+ *
+ * Buckets (mutually exclusive, first match wins):
+ * - `needs_attention` — the contributor has a concrete code-related next
+ *   step today (`status === 'needs_addressing'`: response, changes, CI fix,
+ *   conflict, checklist). This is the headline count on BOTH surfaces.
+ * - `stuck_ci` — waiting PRs whose CI has been `pending` long past any
+ *   normal run time. A "ping / investigate" workflow, not a coding one.
+ * - `dormant_followup` — waiting PRs with `review_required` and no activity
+ *   past the follow-up threshold. A "draft a nudge" workflow.
+ * - `waiting` — everything else that's healthy to leave alone.
+ */
+import type { AttentionBucket, FetchedPR } from './types.js';
+export type { AttentionBucket } from './types.js';
+/**
+ * Days of inactivity after which a `pending` CI status reads as stuck rather
+ * than in-flight. Real CI runs finish in minutes-to-hours; multiple days of
+ * `pending` means a webhook was lost, a runner died, or a required check
+ * never started.
+ */
+export declare const STUCK_CI_THRESHOLD_DAYS = 3;
+/**
+ * Days of inactivity after which a `review_required` PR becomes a follow-up
+ * candidate. Matches the middle step of the 7/14/30 dormant-PR follow-up
+ * cadence — early enough to nudge before the PR goes fully dormant
+ * (default `dormantThresholdDays` is 30).
+ */
+export declare const DORMANT_FOLLOWUP_THRESHOLD_DAYS = 14;
+/** The minimal slice of {@link FetchedPR} the classifier reads. */
+export type AttentionInput = Pick<FetchedPR, 'status' | 'ciStatus' | 'reviewDecision' | 'daysSinceActivity'>;
+/**
+ * Classify one PR into its attention bucket. Pure — both the CLI daily path
+ * and the dashboard `/api/data` path call this, so the two surfaces cannot
+ * diverge on what a count means.
+ */
+export declare function classifyAttentionBucket(pr: AttentionInput): AttentionBucket;
+export interface AttentionSummary {
+    needsAttention: number;
+    stuckCI: number;
+    dormantFollowup: number;
+    waiting: number;
+}
+/** Count PRs per bucket — the shape both headline surfaces render from. */
+export declare function summarizeAttentionBuckets(prs: readonly AttentionInput[]): AttentionSummary;

package/dist/core/pr-attention.js

@@ -0,0 +1,76 @@
+/**
+ * Unified PR attention taxonomy (#1352).
+ *
+ * The headline "needs attention" number used to be computed twice — the CLI
+ * brief counted `collectActionableIssues()` output while the dashboard
+ * counted raw `status === 'needs_addressing'` — and the cases the CLI
+ * deliberately excludes (stuck CI, dormant maintainer waits) sat
+ * undifferentiated inside `waiting_on_maintainer`. This module is the single
+ * classifier both surfaces consume.
+ *
+ * Buckets (mutually exclusive, first match wins):
+ * - `needs_attention` — the contributor has a concrete code-related next
+ *   step today (`status === 'needs_addressing'`: response, changes, CI fix,
+ *   conflict, checklist). This is the headline count on BOTH surfaces.
+ * - `stuck_ci` — waiting PRs whose CI has been `pending` long past any
+ *   normal run time. A "ping / investigate" workflow, not a coding one.
+ * - `dormant_followup` — waiting PRs with `review_required` and no activity
+ *   past the follow-up threshold. A "draft a nudge" workflow.
+ * - `waiting` — everything else that's healthy to leave alone.
+ */
+/**
+ * Days of inactivity after which a `pending` CI status reads as stuck rather
+ * than in-flight. Real CI runs finish in minutes-to-hours; multiple days of
+ * `pending` means a webhook was lost, a runner died, or a required check
+ * never started.
+ */
+export const STUCK_CI_THRESHOLD_DAYS = 3;
+/**
+ * Days of inactivity after which a `review_required` PR becomes a follow-up
+ * candidate. Matches the middle step of the 7/14/30 dormant-PR follow-up
+ * cadence — early enough to nudge before the PR goes fully dormant
+ * (default `dormantThresholdDays` is 30).
+ */
+export const DORMANT_FOLLOWUP_THRESHOLD_DAYS = 14;
+/**
+ * Classify one PR into its attention bucket. Pure — both the CLI daily path
+ * and the dashboard `/api/data` path call this, so the two surfaces cannot
+ * diverge on what a count means.
+ */
+export function classifyAttentionBucket(pr) {
+    if (pr.status === 'needs_addressing')
+        return 'needs_attention';
+    // From here on the PR is waiting_on_maintainer — subdivide the wait.
+    if (pr.ciStatus === 'pending' && pr.daysSinceActivity >= STUCK_CI_THRESHOLD_DAYS) {
+        return 'stuck_ci';
+    }
+    if (pr.reviewDecision === 'review_required' && pr.daysSinceActivity >= DORMANT_FOLLOWUP_THRESHOLD_DAYS) {
+        return 'dormant_followup';
+    }
+    return 'waiting';
+}
+/** Count PRs per bucket — the shape both headline surfaces render from. */
+export function summarizeAttentionBuckets(prs) {
+    const summary = { needsAttention: 0, stuckCI: 0, dormantFollowup: 0, waiting: 0 };
+    for (const pr of prs) {
+        switch (classifyAttentionBucket(pr)) {
+            case 'needs_attention': {
+                summary.needsAttention++;
+                break;
+            }
+            case 'stuck_ci': {
+                summary.stuckCI++;
+                break;
+            }
+            case 'dormant_followup': {
+                summary.dormantFollowup++;
+                break;
+            }
+            case 'waiting': {
+                summary.waiting++;
+                break;
+            }
+        }
+    }
+    return summary;
+}

package/dist/core/types.d.ts

@@ -126,6 +126,8 @@ export type MaintainerActionHint = 'demo_requested' | 'tests_requested' | 'chang
  * This is never persisted in local state — it represents a point-in-time snapshot
  * of a PR's current condition.
  */
+/** Unified attention bucket (#1352) — see core/pr-attention.ts for the classifier. */
+export type AttentionBucket = 'needs_attention' | 'stuck_ci' | 'dormant_followup' | 'waiting';
 export interface FetchedPR {
     id: number;
     url: string;
@@ -142,6 +144,11 @@ export interface FetchedPR {
     actionReasons?: ActionReason[];
     /** How stale the PR is based on activity age. Independent of status — a PR can be both needs_addressing and dormant. */
     stalenessTier: StalenessTier;
+    /** Unified attention bucket (#1352), computed by `classifyAttentionBucket()`
+     * from status/ciStatus/reviewDecision/daysSinceActivity. Stamped by the
+     * dashboard data path so the SPA renders the same taxonomy the CLI brief
+     * counts. Optional: absent on payloads from older producers. */
+    attentionBucket?: AttentionBucket;
     /** 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". */