@oss-autopilot/core 3.5.0 → 3.7.0

package/dist/commands/vet-list.js

@@ -3,7 +3,7 @@
  * Re-vets all available issues in a curated issue list file via @oss-scout/core.
  */
 import * as fs from 'node:fs';
-import { adaptScoutLinkedPR, createAutopilotScout } from './scout-bridge.js';
+import { adaptScoutLinkedPR, buildCandidateLinkedPR, createAutopilotScout } from './scout-bridge.js';
 import { runParseList, pruneIssueList } from './parse-list.js';
 import { detectIssueList } from './startup.js';
 import { computeSuccessGrade, gradeFromCandidate } from '../core/issue-grading.js';
@@ -17,7 +17,7 @@ const KNOWN_SKIP_REASONS = new Set([
     'anti_llm_policy',
     'other',
 ]);
-function mapSkipReasonToStatus(reason) {
+function mapSkipReasonToStatus(reason, vetResult) {
     switch (reason) {
         case 'issue_closed': {
             return 'closed';
@@ -26,6 +26,12 @@ function mapSkipReasonToStatus(reason) {
             return 'claimed';
         }
         case 'has_linked_pr': {
+            // Open linked PRs that have been idle for 30+ days are revive
+            // opportunities (#97 / scout 0.9.0) — surface them with a distinct
+            // status rather than auto-dropping as `has_pr`.
+            if (vetResult.linkedPR?.state === 'open' && vetResult.linkedPR.isStalled) {
+                return 'has_stalled_pr';
+            }
             return 'has_pr';
         }
         case 'score_too_low':
@@ -57,7 +63,7 @@ export function extractSkipReason(candidate) {
  */
 export function classifyListStatus(vetResult, skipReason) {
     if (skipReason) {
-        const fromEnum = mapSkipReasonToStatus(skipReason);
+        const fromEnum = mapSkipReasonToStatus(skipReason, vetResult);
         if (fromEnum)
             return fromEnum;
         // skipReason was set but maps to 'other' / low-score / policy — let the
@@ -69,8 +75,15 @@ export function classifyListStatus(vetResult, skipReason) {
             return 'closed';
         if (skipReasons.some((r) => r.includes('claimed') || r.includes('assigned')))
             return 'claimed';
-        if (skipReasons.some((r) => r.includes('existing pr') || r.includes('linked pr') || r.includes('pull request')))
+        if (skipReasons.some((r) => r.includes('existing pr') || r.includes('linked pr') || r.includes('pull request'))) {
+            // Same revive-opportunity branch as the enum path above — when scout
+            // hasn't yet emitted skipReason but we can see a stalled open PR on
+            // the candidate, prefer the dedicated status (#97 / scout 0.9.0).
+            if (vetResult.linkedPR?.state === 'open' && vetResult.linkedPR.isStalled) {
+                return 'has_stalled_pr';
+            }
             return 'has_pr';
+        }
     }
     if (vetResult.recommendation === 'approve' || vetResult.recommendation === 'needs_review') {
         return 'still_available';
@@ -102,7 +115,7 @@ export async function runVetList(options = {}) {
     if (parsed.available.length === 0) {
         return {
             results: [],
-            summary: { total: 0, stillAvailable: 0, claimed: 0, closed: 0, hasPR: 0, errors: 0 },
+            summary: { total: 0, stillAvailable: 0, claimed: 0, closed: 0, hasPR: 0, hasStalledPR: 0, errors: 0 },
         };
     }
     // 2. Vet each available issue in parallel with concurrency limit
@@ -126,6 +139,7 @@ export async function runVetList(options = {}) {
                     linkedPR: adaptScoutLinkedPR(candidate.vettingResult.linkedPR),
                     userLogin,
                 });
+                const linkedPR = buildCandidateLinkedPR(candidate.vettingResult.linkedPR);
                 const vetResult = {
                     issue: {
                         repo: candidate.issue.repo,
@@ -141,6 +155,7 @@ export async function runVetList(options = {}) {
                     vettingResult: candidate.vettingResult,
                     antiLLMPolicy: candidate.antiLLMPolicy,
                     linkedPRClassification,
+                    ...(linkedPR ? { linkedPR } : {}),
                     slmTriage: candidate.slmTriage ?? null,
                     grade,
                 };
@@ -175,6 +190,7 @@ export async function runVetList(options = {}) {
         claimed: results.filter((r) => r.listStatus === 'claimed').length,
         closed: results.filter((r) => r.listStatus === 'closed').length,
         hasPR: results.filter((r) => r.listStatus === 'has_pr').length,
+        hasStalledPR: results.filter((r) => r.listStatus === 'has_stalled_pr').length,
         errors: results.filter((r) => r.listStatus === 'error').length,
     };
     // 4. Prune the file if requested — remove completed/skipped/low-score items

package/dist/commands/vet.js

@@ -2,7 +2,7 @@
  * Vet command
  * Vets a specific issue before working on it via @oss-scout/core
  */
-import { createAutopilotScout, adaptScoutLinkedPR } from './scout-bridge.js';
+import { adaptScoutLinkedPR, buildCandidateLinkedPR, createAutopilotScout } from './scout-bridge.js';
 import { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
 import { gradeFromCandidate } from '../core/issue-grading.js';
 import { getStateManager, classifyLinkedPR } from '../core/index.js';
@@ -29,6 +29,7 @@ export async function runVet(options) {
         linkedPR: adaptScoutLinkedPR(candidate.vettingResult.linkedPR),
         userLogin,
     });
+    const linkedPR = buildCandidateLinkedPR(candidate.vettingResult.linkedPR);
     return {
         issue: {
             repo: candidate.issue.repo,
@@ -44,6 +45,7 @@ export async function runVet(options) {
         vettingResult: candidate.vettingResult,
         antiLLMPolicy: candidate.antiLLMPolicy,
         linkedPRClassification,
+        ...(linkedPR ? { linkedPR } : {}),
         slmTriage: candidate.slmTriage ?? null,
         grade,
     };

package/dist/core/anti-llm-policy.d.ts

@@ -1,26 +1,35 @@
 /**
- * Anti-LLM policy scan (#108, #911, #979).
+ * AI/LLM policy scans (#108, #911, #979, #1269).
  *
- * Scan concatenated repo docs (CONTRIBUTING.md, CODE_OF_CONDUCT.md,
- * README) for language that indicates the project does not accept
- * AI/LLM-generated contributions. Previously described as a keyword
- * table in prose in agents/issue-scout.md.
+ * Two complementary scanners over the same input (concatenated repo docs
+ * — CONTRIBUTING.md, CODE_OF_CONDUCT.md, README, etc.):
+ *
+ * 1. {@link scanForAntiLLMPolicy} — detects language indicating the
+ *    project does NOT accept AI/LLM-generated contributions. Used by
+ *    issue-scout / repo-evaluator to filter out repos where landing a
+ *    PR is impossible.
+ *
+ * 2. {@link scanAIDisclosureRequirement} — detects the opposite:
+ *    language requiring or inviting AI disclosure ("must disclose AI
+ *    use", "credit AI tools"). Used by pr-compliance-checker to decide
+ *    whether AI attribution should be flagged as a violation, encouraged,
+ *    or required (#1269 Improvement C).
  *
  * The long-term home for this logic is `@oss-scout/core`, where the
  * relevant files are already fetched during vetting. Keeping it here
  * for now lets the agent invoke it directly and gives scout a
  * reference implementation + test fixtures to adopt. See #979.
  *
- * Precision matters more than recall. False positives (flagging a
- * project that actually welcomes AI help) silently shrink the user's
- * contribution surface without recourse. We only match on phrases
- * that combine a rejection keyword (no / reject / will be closed /
- * don't accept) with an AI/LLM noun.
+ * Precision matters more than recall in both directions. A false
+ * positive on the anti-LLM side silently shrinks the user's
+ * contribution surface; a false positive on the disclosure side tells
+ * the user to add attribution that the maintainer didn't actually ask
+ * for. Patterns require an explicit verb-phrase + AI/LLM-noun pairing.
  *
  * **User-facing reference:** `docs/anti-llm-policy.md` — explains the
- * three categories, example phrases per category, and the false-positive-
- * resistance design (why "AI division will be closed at end of Q4"
- * does NOT match).
+ * three anti-LLM categories, example phrases per category, and the
+ * false-positive-resistance design (why "AI division will be closed at
+ * end of Q4" does NOT match).
  */
 export type AntiLLMCategory = 'explicit_ban' | 'tool_ban' | 'reject_framing';
 export interface AntiLLMMatch {
@@ -35,3 +44,23 @@ export interface AntiLLMScanResult {
     matches: AntiLLMMatch[];
 }
 export declare function scanForAntiLLMPolicy(text: string): AntiLLMScanResult;
+export type AIDisclosureCategory = 'mandatory' | 'recommended' | 'invited';
+export interface AIDisclosureMatch {
+    category: AIDisclosureCategory;
+    phrase: string;
+    excerpt: string;
+}
+export interface AIDisclosureScanResult {
+    matched: boolean;
+    matches: AIDisclosureMatch[];
+}
+/**
+ * Scan repo docs for language requiring or inviting AI disclosure (#1269).
+ *
+ * Mirrors {@link scanForAntiLLMPolicy}'s shape: same input contract,
+ * same false-positive-resistance discipline, same per-match excerpt for
+ * surfacing to the user. Categories are ordered by binding strength —
+ * callers that want to avoid false-positive flagging on weak invitations
+ * can filter to 'mandatory' / 'recommended' only.
+ */
+export declare function scanAIDisclosureRequirement(text: string): AIDisclosureScanResult;

package/dist/core/anti-llm-policy.js

@@ -1,26 +1,35 @@
 /**
- * Anti-LLM policy scan (#108, #911, #979).
+ * AI/LLM policy scans (#108, #911, #979, #1269).
  *
- * Scan concatenated repo docs (CONTRIBUTING.md, CODE_OF_CONDUCT.md,
- * README) for language that indicates the project does not accept
- * AI/LLM-generated contributions. Previously described as a keyword
- * table in prose in agents/issue-scout.md.
+ * Two complementary scanners over the same input (concatenated repo docs
+ * — CONTRIBUTING.md, CODE_OF_CONDUCT.md, README, etc.):
+ *
+ * 1. {@link scanForAntiLLMPolicy} — detects language indicating the
+ *    project does NOT accept AI/LLM-generated contributions. Used by
+ *    issue-scout / repo-evaluator to filter out repos where landing a
+ *    PR is impossible.
+ *
+ * 2. {@link scanAIDisclosureRequirement} — detects the opposite:
+ *    language requiring or inviting AI disclosure ("must disclose AI
+ *    use", "credit AI tools"). Used by pr-compliance-checker to decide
+ *    whether AI attribution should be flagged as a violation, encouraged,
+ *    or required (#1269 Improvement C).
  *
  * The long-term home for this logic is `@oss-scout/core`, where the
  * relevant files are already fetched during vetting. Keeping it here
  * for now lets the agent invoke it directly and gives scout a
  * reference implementation + test fixtures to adopt. See #979.
  *
- * Precision matters more than recall. False positives (flagging a
- * project that actually welcomes AI help) silently shrink the user's
- * contribution surface without recourse. We only match on phrases
- * that combine a rejection keyword (no / reject / will be closed /
- * don't accept) with an AI/LLM noun.
+ * Precision matters more than recall in both directions. A false
+ * positive on the anti-LLM side silently shrinks the user's
+ * contribution surface; a false positive on the disclosure side tells
+ * the user to add attribution that the maintainer didn't actually ask
+ * for. Patterns require an explicit verb-phrase + AI/LLM-noun pairing.
  *
  * **User-facing reference:** `docs/anti-llm-policy.md` — explains the
- * three categories, example phrases per category, and the false-positive-
- * resistance design (why "AI division will be closed at end of Q4"
- * does NOT match).
+ * three anti-LLM categories, example phrases per category, and the
+ * false-positive-resistance design (why "AI division will be closed at
+ * end of Q4" does NOT match).
  */
 const PATTERNS = [
     // Explicit "no X" bans against AI/LLM nouns.
@@ -104,3 +113,83 @@ export function scanForAntiLLMPolicy(text) {
     }
     return { matched: matches.length > 0, matches };
 }
+const DISCLOSURE_PATTERNS = [
+    // Mandatory: imperative verbs binding to an AI/LLM disclosure noun.
+    // Match shape: <verb-phrase> <AI noun> <disclosure noun>?
+    // Verb phrases: "must disclose", "required to disclose", "are required
+    // to indicate", "you must indicate". The optional disclosure-action
+    // noun catches "must disclose use of AI" without requiring a separate
+    // pattern. The AI noun can be plain "ai/llm" or a tool name.
+    {
+        category: 'mandatory',
+        regex: /\b(must|required\s+to|are\s+required\s+to)\s+(disclose|indicate|declare|note|state|mention|label|tag|credit|acknowledge)\s+(?:[a-z\s'-]{0,40}?\b)?(ai|llm|generative\s+ai|copilot|chatgpt|claude|cursor)\b/i,
+    },
+    // "PRs using AI must be labeled / tagged / disclosed"
+    {
+        category: 'mandatory',
+        regex: /\b(prs?|contributions?|commits?|code)\s+(using|generated\s+by|written\s+by|made\s+with)\s+(ai|llm|copilot|chatgpt|claude|cursor)\s+(?:tools?\s+)?(must\s+be|need\s+to\s+be|are\s+to\s+be)\s+(labeled|tagged|disclosed|marked|flagged|noted)\b/i,
+    },
+    // "Disclosure of AI assistance is required" — passive form
+    {
+        category: 'mandatory',
+        regex: /\b(disclosure|disclosing|labeling|labelling|tagging|crediting)\s+(of\s+)?(ai|llm|copilot|chatgpt|claude|cursor)(\s+(use|usage|assistance|tools?|contributions?|generated\s+code))?\s+(is\s+required|is\s+mandatory|must\s+be\s+included)\b/i,
+    },
+    // Recommended: softer "should" or "we ask" framing. Same noun anchors.
+    // Verb forms allow optional gerund (-ing) endings since "we strongly
+    // encourage acknowledging AI" reads naturally even though "acknowledge"
+    // is the bare verb in the imperative list.
+    {
+        category: 'recommended',
+        regex: /\b(should|we\s+ask\s+you\s+to|we\s+ask\s+that\s+you|we\s+(?:strongly\s+)?(?:encourage|recommend))\s+(disclose|disclosing|indicate|indicating|declare|declaring|note|noting|mention|mentioning|label|labeling|labelling|tag|tagging|credit|crediting|acknowledge|acknowledging)\s+(?:[a-z\s'-]{0,40}?\b)?(ai|llm|generative\s+ai|copilot|chatgpt|claude|cursor)\b/i,
+    },
+    // "credit AI tools you used" — direct imperative without "must/should"
+    {
+        category: 'recommended',
+        regex: /\b(credit|acknowledge|attribute)\s+(ai|llm|generative\s+ai)\s+(tools?|assistants?|use|usage|assistance)\b/i,
+    },
+    // Invited: permissive framing. Lower confidence.
+    // The "please" branch is dropped intentionally — bare "please mention X"
+    // doesn't carry enough policy weight on its own, and including it as
+    // `please\s+(?:feel\s+free\s+to)?\s+` introduces super-linear backtracking
+    // (regexp/no-super-linear-backtracking) because of the ambiguous \s+
+    // boundary on either side of the optional group.
+    {
+        category: 'invited',
+        regex: /\b(feel\s+free\s+to|please\s+feel\s+free\s+to|you('re|\s+are)\s+welcome\s+to|welcome\s+to)\s+(disclose|mention|note|indicate|label|tag|credit)\s+(?:[a-z\s'-]{0,40}?\b)?(ai|llm|generative\s+ai|copilot|chatgpt|claude|cursor)\b/i,
+    },
+];
+/**
+ * Scan repo docs for language requiring or inviting AI disclosure (#1269).
+ *
+ * Mirrors {@link scanForAntiLLMPolicy}'s shape: same input contract,
+ * same false-positive-resistance discipline, same per-match excerpt for
+ * surfacing to the user. Categories are ordered by binding strength —
+ * callers that want to avoid false-positive flagging on weak invitations
+ * can filter to 'mandatory' / 'recommended' only.
+ */
+export function scanAIDisclosureRequirement(text) {
+    if (typeof text !== 'string') {
+        throw new TypeError(`scanAIDisclosureRequirement: expected string, received ${typeof text}`);
+    }
+    if (text === '')
+        return { matched: false, matches: [] };
+    const normalized = normalizeText(text);
+    const seenLabels = new Set();
+    const matches = [];
+    for (const pattern of DISCLOSURE_PATTERNS) {
+        const hit = normalized.match(pattern.regex);
+        if (!hit || hit.index === undefined)
+            continue;
+        const phrase = hit[0];
+        const key = `${pattern.category}:${phrase.toLowerCase()}`;
+        if (seenLabels.has(key))
+            continue;
+        seenLabels.add(key);
+        matches.push({
+            category: pattern.category,
+            phrase,
+            excerpt: makeExcerpt(normalized, hit.index, phrase.length),
+        });
+    }
+    return { matched: matches.length > 0, matches };
+}

package/dist/core/ci-analysis.d.ts

@@ -3,7 +3,7 @@
  * Extracted from PRMonitor to isolate CI-related logic (#263).
  */
 import type { Octokit } from '@octokit/rest';
-import { CIFailureCategory, ClassifiedCheck, CIStatusResult } from './types.js';
+import { CIFailureCategory, ClassifiedCheck, CIStatusResult, CIStatus, CIStatusCategorization } from './types.js';
 /**
  * Classify a failing CI check as actionable, fork_limitation, auth_gate, or infrastructure (#81, #145, #743).
  * Default is 'actionable' — only known patterns get reclassified.
@@ -16,6 +16,37 @@ export declare function classifyCICheck(name: string, description?: string, conc
  * Accepts optional conclusion data to detect infrastructure failures and auth gates.
  */
 export declare function classifyFailingChecks(failingCheckNames: string[], conclusions?: Map<string, string>): ClassifiedCheck[];
+/**
+ * Map an aggregate `ciStatus + failingCheckNames + classifiedChecks` triple
+ * into one of five mutually exclusive overall states (#1272). The 5-row
+ * truth table previously lived as prose in `agents/pr-health-checker.md`;
+ * extracting it lets that agent (and any future consumer — dashboard,
+ * MCP, sibling agents that adopt the field) read a single typed value
+ * instead of re-deriving from `ciStatus + failingCheckNames + classifiedChecks`.
+ *
+ * Decision order (each branch is exclusive):
+ *   1. `passing`                      → `all_passing`
+ *   2. `pending`                      → `blocked` (awaiting trigger / completion)
+ *   3. `failing` + actionable         → `failing` (real test/lint/build issue)
+ *   4. `failing` + only infrastructure → `blocked` (cancelled/timed-out runner — needs rerun)
+ *   5. `failing` + only fork/auth     → `fork_limitation` (informational)
+ *   6. `failing` + zero classified    → `failing` w/ "details unavailable" summary
+ *   7. `unknown`                      → `not_running`
+ *
+ * Why infrastructure routes to `blocked` and not `fork_limitation`:
+ * a cancelled or timed-out runner is genuinely worth re-running; calling
+ * it "informational" would tell the agent to ignore something the user
+ * can fix with a rerun-request.
+ *
+ * The `summary` is short (≤180 char even for 10+ failing checks) and
+ * suitable for inline display. `action` is a hint, not enforcement —
+ * agents may still escalate based on other PR context.
+ */
+export declare function categorizeCIStatus(input: {
+    ciStatus: CIStatus;
+    failingCheckNames: string[];
+    classifiedChecks: ClassifiedCheck[];
+}): CIStatusCategorization;
 /**
  * Analyze check runs (GitHub Actions, etc.) and categorize them.
  * Returns flags for failing/pending/success and lists of failing check names + conclusions.

package/dist/core/ci-analysis.js

@@ -92,6 +92,98 @@ export function classifyFailingChecks(failingCheckNames, conclusions) {
         };
     });
 }
+/**
+ * Map an aggregate `ciStatus + failingCheckNames + classifiedChecks` triple
+ * into one of five mutually exclusive overall states (#1272). The 5-row
+ * truth table previously lived as prose in `agents/pr-health-checker.md`;
+ * extracting it lets that agent (and any future consumer — dashboard,
+ * MCP, sibling agents that adopt the field) read a single typed value
+ * instead of re-deriving from `ciStatus + failingCheckNames + classifiedChecks`.
+ *
+ * Decision order (each branch is exclusive):
+ *   1. `passing`                      → `all_passing`
+ *   2. `pending`                      → `blocked` (awaiting trigger / completion)
+ *   3. `failing` + actionable         → `failing` (real test/lint/build issue)
+ *   4. `failing` + only infrastructure → `blocked` (cancelled/timed-out runner — needs rerun)
+ *   5. `failing` + only fork/auth     → `fork_limitation` (informational)
+ *   6. `failing` + zero classified    → `failing` w/ "details unavailable" summary
+ *   7. `unknown`                      → `not_running`
+ *
+ * Why infrastructure routes to `blocked` and not `fork_limitation`:
+ * a cancelled or timed-out runner is genuinely worth re-running; calling
+ * it "informational" would tell the agent to ignore something the user
+ * can fix with a rerun-request.
+ *
+ * The `summary` is short (≤180 char even for 10+ failing checks) and
+ * suitable for inline display. `action` is a hint, not enforcement —
+ * agents may still escalate based on other PR context.
+ */
+export function categorizeCIStatus(input) {
+    const { ciStatus, failingCheckNames, classifiedChecks } = input;
+    if (ciStatus === 'passing') {
+        return { category: 'all_passing', summary: 'All checks passing', action: 'none' };
+    }
+    if (ciStatus === 'pending') {
+        // `mergeStatuses` currently sets `failingCheckNames: []` on pending,
+        // so the count branch is defensive — kept so a future caller that
+        // forwards pending names doesn't silently drop them.
+        const count = failingCheckNames.length;
+        const summary = count > 0 ? `${count} pending check(s); CI run incomplete` : 'CI checks pending';
+        return { category: 'blocked', summary, action: 'request_rerun' };
+    }
+    if (ciStatus === 'failing') {
+        const actionable = classifiedChecks.filter((c) => c.category === 'actionable');
+        if (actionable.length > 0) {
+            const preview = actionable
+                .slice(0, 3)
+                .map((c) => c.name)
+                .join(', ');
+            const more = actionable.length > 3 ? ` (+${actionable.length - 3} more)` : '';
+            return {
+                category: 'failing',
+                summary: `${actionable.length} actionable failure(s): ${preview}${more}`,
+                action: 'investigate',
+            };
+        }
+        // No actionable failures. Distinguish three sub-cases:
+        // (a) failing with zero classified checks: status came from the
+        //     legacy combined-status endpoint without per-check detail. Be
+        //     honest about the missing detail rather than asserting "fork
+        //     limitations" the caller can't verify.
+        if (classifiedChecks.length === 0) {
+            return {
+                category: 'failing',
+                summary: 'CI reported failure but no check details available',
+                action: 'investigate',
+            };
+        }
+        // (b) at least one infrastructure failure (cancelled / timed-out /
+        //     dependency-install). Re-running often fixes the issue, so
+        //     surface as `blocked` with `request_rerun` rather than
+        //     mislabeling as "fork limits / auth gates."
+        const hasInfrastructure = classifiedChecks.some((c) => c.category === 'infrastructure');
+        if (hasInfrastructure) {
+            const total = classifiedChecks.length;
+            return {
+                category: 'blocked',
+                summary: `${total} non-actionable failure(s) including infrastructure issues; rerun may resolve`,
+                action: 'request_rerun',
+            };
+        }
+        // (c) only fork-limitation / auth-gate failures — purely informational.
+        const total = classifiedChecks.length;
+        return {
+            category: 'fork_limitation',
+            summary: `${total} non-actionable failure(s) (fork limits / auth gates)`,
+            action: 'informational',
+        };
+    }
+    // ciStatus === 'unknown' — no checks reported, or status couldn't be
+    // determined. Treat both as not_running so callers don't have to
+    // distinguish the rare indeterminate case from the common "no CI
+    // configured" case.
+    return { category: 'not_running', summary: 'No CI checks reported', action: 'check_workflows' };
+}
 /**
  * Analyze check runs (GitHub Actions, etc.) and categorize them.
  * Returns flags for failing/pending/success and lists of failing check names + conclusions.

package/dist/core/errors.d.ts

@@ -85,6 +85,25 @@ export declare function errorMessage(e: unknown): string;
 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;
+/**
+ * Check if an error is GitHub's "users do not exist" Search-API validation
+ * failure (HTTP 422 with `resource: 'Search', code: 'invalid'` and a message
+ * indicating the user couldn't be resolved). Returned when the Search API
+ * can't resolve the user named in an `author:`/`user:` qualifier — the
+ * typical cause is a stale or mis-typed `githubUsername` in
+ * `~/.oss-autopilot/state.json`.
+ *
+ * Surfaced as a generic "Validation Failed" string by Octokit, which gives
+ * the user no actionable signal. Callers wrap the search and rethrow this
+ * as a {@link ConfigurationError} so the CLI prints the configured username
+ * and points at `/setup-oss`.
+ *
+ * The message-text gate is load-bearing: GitHub returns the same
+ * `resource`/`code` pair for other Search 422s (query too long, too many
+ * ORs). Without the gate, those would silently rewrite to "your configured
+ * username is wrong," which is actively misleading.
+ */
+export declare function isInvalidUserSearchError(err: 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

@@ -142,6 +142,60 @@ export function isRateLimitError(error) {
     }
     return false;
 }
+/**
+ * Match-text used to discriminate the user-resolution failure from sibling
+ * `resource: 'Search', code: 'invalid'` 422s (query-too-long,
+ * too-many-OR-operators, malformed qualifier). Both the structured and the
+ * fallback paths gate on this pattern so the matcher's name remains accurate
+ * if a future caller uses a different Search query.
+ */
+const USER_NOT_FOUND_SEARCH_MESSAGE = /users.*do not exist|cannot be searched/i;
+/**
+ * Check if an error is GitHub's "users do not exist" Search-API validation
+ * failure (HTTP 422 with `resource: 'Search', code: 'invalid'` and a message
+ * indicating the user couldn't be resolved). Returned when the Search API
+ * can't resolve the user named in an `author:`/`user:` qualifier — the
+ * typical cause is a stale or mis-typed `githubUsername` in
+ * `~/.oss-autopilot/state.json`.
+ *
+ * Surfaced as a generic "Validation Failed" string by Octokit, which gives
+ * the user no actionable signal. Callers wrap the search and rethrow this
+ * as a {@link ConfigurationError} so the CLI prints the configured username
+ * and points at `/setup-oss`.
+ *
+ * The message-text gate is load-bearing: GitHub returns the same
+ * `resource`/`code` pair for other Search 422s (query too long, too many
+ * ORs). Without the gate, those would silently rewrite to "your configured
+ * username is wrong," which is actively misleading.
+ */
+export function isInvalidUserSearchError(err) {
+    if (getHttpStatusCode(err) !== 422)
+        return false;
+    const data = err?.response?.data;
+    const errors = data && typeof data === 'object' ? data.errors : undefined;
+    if (Array.isArray(errors)) {
+        return errors.some((e) => {
+            if (!e || typeof e !== 'object')
+                return false;
+            const entry = e;
+            if (entry.resource !== 'Search' || entry.code !== 'invalid')
+                return false;
+            // The Search API includes a per-error `message` for this case. When
+            // present, gate on it to avoid matching sibling validation failures
+            // that share the resource/code pair. When absent, fall back to the
+            // top-level message check below — some serializations drop the
+            // per-entry message but keep it on the response.
+            if (typeof entry.message === 'string') {
+                return USER_NOT_FOUND_SEARCH_MESSAGE.test(entry.message);
+            }
+            return USER_NOT_FOUND_SEARCH_MESSAGE.test(errorMessage(err));
+        });
+    }
+    // Fallback for serialized errors that lost the structured `response.data`
+    // (e.g. messages re-thrown across boundaries). The Search API's own copy
+    // is stable enough to match against.
+    return USER_NOT_FOUND_SEARCH_MESSAGE.test(errorMessage(err));
+}
 /** Return true for errors that should propagate (not degrade gracefully): rate limits, auth failures, abuse detection. */
 export function isRateLimitOrAuthError(err) {
     const status = getHttpStatusCode(err);

package/dist/core/index.d.ts

@@ -21,7 +21,7 @@ export { HttpCache, getHttpCache, cachedRequest, type CacheEntry } from './http-
 export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, buildStarFilter, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';
 export { computeContributionStats, type ContributionStats, type ComputeStatsInput } from './stats.js';
 export { fetchPRTemplate, type PRTemplateResult } from './pr-template.js';
-export { classifyLinkedPR, type LinkedPR, type LinkedPRClassification, type LinkedPRState, } from './linked-pr-classification.js';
+export { classifyLinkedPR, isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, type LinkedPR, type LinkedPRClassification, type LinkedPRState, } from './linked-pr-classification.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

@@ -22,7 +22,7 @@ export { HttpCache, getHttpCache, cachedRequest } from './http-cache.js';
 export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, buildStarFilter, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';
 export { computeContributionStats } from './stats.js';
 export { fetchPRTemplate } from './pr-template.js';
-export { classifyLinkedPR, } from './linked-pr-classification.js';
+export { classifyLinkedPR, isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, } from './linked-pr-classification.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/linked-pr-classification.d.ts

@@ -23,7 +23,35 @@ export interface LinkedPR {
         login: string;
     } | null;
     state: LinkedPRState;
+    /**
+     * ISO timestamp of the linked PR's last update, surfaced from scout's
+     * timeline-event metadata when available (#97). Optional so existing
+     * callers and fixtures that don't carry the field continue to type-check.
+     * Used by `isLinkedPRStalled` to flag open PRs that haven't been touched
+     * in the last `STALLED_PR_THRESHOLD_DAYS` days.
+     */
+    updatedAt?: string;
 }
+/**
+ * Days of inactivity that classify an open linked PR as "stalled" — kept
+ * in sync with scout's `STALLED_PR_THRESHOLD_DAYS` so the autopilot helper
+ * and scout's own annotation use the same boundary.
+ */
+export declare const STALLED_PR_THRESHOLD_DAYS = 30;
+/**
+ * Determine whether an autopilot-shaped `LinkedPR` is stalled.
+ *
+ * True when:
+ *   - the PR is open, AND
+ *   - `updatedAt` is set, AND
+ *   - the elapsed time since `updatedAt` is at least `thresholdDays`.
+ *
+ * Returns false for closed/merged PRs, missing `updatedAt`, or invalid
+ * timestamps. Reimplemented locally rather than delegating to scout's
+ * helper so this module owns autopilot's `LinkedPR` shape contract end
+ * to end (avoids a runtime import dependency on scout's internal type).
+ */
+export declare function isLinkedPRStalled(linkedPR: LinkedPR | null | undefined, now?: Date, thresholdDays?: number): boolean;
 export declare function classifyLinkedPR(params: {
     linkedPR: LinkedPR | null;
     userLogin: string;

package/dist/core/linked-pr-classification.js

@@ -11,6 +11,38 @@
  * linked PR themselves (e.g. via Octokit) and hand the shape to this
  * function. See #978 for the upstream data-contract work.
  */
+/**
+ * Days of inactivity that classify an open linked PR as "stalled" — kept
+ * in sync with scout's `STALLED_PR_THRESHOLD_DAYS` so the autopilot helper
+ * and scout's own annotation use the same boundary.
+ */
+export const STALLED_PR_THRESHOLD_DAYS = 30;
+/**
+ * Determine whether an autopilot-shaped `LinkedPR` is stalled.
+ *
+ * True when:
+ *   - the PR is open, AND
+ *   - `updatedAt` is set, AND
+ *   - the elapsed time since `updatedAt` is at least `thresholdDays`.
+ *
+ * Returns false for closed/merged PRs, missing `updatedAt`, or invalid
+ * timestamps. Reimplemented locally rather than delegating to scout's
+ * helper so this module owns autopilot's `LinkedPR` shape contract end
+ * to end (avoids a runtime import dependency on scout's internal type).
+ */
+export function isLinkedPRStalled(linkedPR, now = new Date(), thresholdDays = STALLED_PR_THRESHOLD_DAYS) {
+    if (!linkedPR)
+        return false;
+    if (linkedPR.state !== 'open')
+        return false;
+    if (!linkedPR.updatedAt)
+        return false;
+    const updatedMs = Date.parse(linkedPR.updatedAt);
+    if (!Number.isFinite(updatedMs))
+        return false;
+    const ageDays = (now.getTime() - updatedMs) / (1000 * 60 * 60 * 24);
+    return ageDays >= thresholdDays;
+}
 /**
  * Normalize a state value from either REST (lowercase `open`/`closed`
  * plus a separate `merged` boolean) or GraphQL (uppercase `OPEN`/