@oss-scout/mcp 0.2.0 → 0.3.0

package/dist/mcp-server.bundle.cjs

@@ -35495,6 +35495,15 @@ function getCacheDir() {
   }
   return dir;
 }
+function extractRepoFromUrl(url2) {
+  const apiMatch = url2.match(/api\.github\.com\/repos\/([^/]+\/[^/]+)/);
+  if (apiMatch)
+    return apiMatch[1];
+  const webMatch = url2.match(/github\.com\/([^/]+\/[^/]+)/);
+  if (webMatch)
+    return webMatch[1];
+  return null;
+}
 var OWNER_PATTERN = /^[a-zA-Z0-9_-]+$/;
 var REPO_PATTERN = /^[a-zA-Z0-9_.-]+$/;
 function isValidOwnerRepo(owner, repo) {
@@ -35656,13 +35665,30 @@ function getSearchBudgetTracker() {
 
 // ../core/dist/core/types.js
 var SCOPE_LABELS = {
-  beginner: ["good first issue", "help wanted", "easy", "up-for-grabs", "first-timers-only", "beginner"],
-  intermediate: ["enhancement", "feature", "feature-request", "contributions welcome"],
+  beginner: [
+    "good first issue",
+    "help wanted",
+    "easy",
+    "up-for-grabs",
+    "first-timers-only",
+    "beginner"
+  ],
+  intermediate: [
+    "enhancement",
+    "feature",
+    "feature-request",
+    "contributions welcome"
+  ],
   advanced: ["proposal", "RFC", "accepted", "design"]
 };
 
 // ../core/dist/core/schemas.js
-var IssueStatusSchema = external_exports3.enum(["candidate", "claimed", "in_progress", "pr_submitted"]);
+var IssueStatusSchema = external_exports3.enum([
+  "candidate",
+  "claimed",
+  "in_progress",
+  "pr_submitted"
+]);
 var ProjectCategorySchema = external_exports3.enum([
   "nonprofit",
   "devtools",
@@ -35671,9 +35697,24 @@ var ProjectCategorySchema = external_exports3.enum([
   "data-ml",
   "education"
 ]);
-var IssueScopeSchema = external_exports3.enum(["beginner", "intermediate", "advanced"]);
-var SearchStrategySchema = external_exports3.enum(["merged", "orgs", "starred", "broad", "maintained", "all"]);
-var CONCRETE_STRATEGIES = ["merged", "orgs", "starred", "broad", "maintained"];
+var IssueScopeSchema = external_exports3.enum([
+  "beginner",
+  "intermediate",
+  "advanced"
+]);
+var SearchStrategySchema = external_exports3.enum([
+  "merged",
+  "starred",
+  "broad",
+  "maintained",
+  "all"
+]);
+var CONCRETE_STRATEGIES = [
+  "merged",
+  "starred",
+  "broad",
+  "maintained"
+];
 var RepoSignalsSchema = external_exports3.object({
   hasActiveMaintainers: external_exports3.boolean(),
   isResponsive: external_exports3.boolean(),
@@ -35742,6 +35783,13 @@ var TrackedIssueSchema = external_exports3.object({
   vetted: external_exports3.boolean(),
   vettingResult: IssueVettingResultSchema.optional()
 });
+var SkippedIssueSchema = external_exports3.object({
+  url: external_exports3.string(),
+  repo: external_exports3.string(),
+  number: external_exports3.number(),
+  title: external_exports3.string(),
+  skippedAt: external_exports3.string()
+});
 var SavedCandidateSchema = external_exports3.object({
   issueUrl: external_exports3.string(),
   repo: external_exports3.string(),
@@ -35758,13 +35806,12 @@ var SavedCandidateSchema = external_exports3.object({
 var PersistenceModeSchema = external_exports3.enum(["local", "gist"]);
 var ScoutPreferencesSchema = external_exports3.object({
   githubUsername: external_exports3.string().default(""),
-  languages: external_exports3.array(external_exports3.string()).default(["typescript", "javascript"]),
+  languages: external_exports3.array(external_exports3.string()).default(["any"]),
   labels: external_exports3.array(external_exports3.string()).default(["good first issue", "help wanted"]),
   scope: external_exports3.array(IssueScopeSchema).optional(),
   excludeRepos: external_exports3.array(external_exports3.string()).default([]),
   excludeOrgs: external_exports3.array(external_exports3.string()).default([]),
   aiPolicyBlocklist: external_exports3.array(external_exports3.string()).default(["matplotlib/matplotlib"]),
-  preferredOrgs: external_exports3.array(external_exports3.string()).default([]),
   projectCategories: external_exports3.array(ProjectCategorySchema).default([]),
   minStars: external_exports3.number().default(50),
   maxIssueAgeDays: external_exports3.number().default(90),
@@ -35782,13 +35829,19 @@ var ScoutStateSchema = external_exports3.object({
   mergedPRs: external_exports3.array(StoredMergedPRSchema).default([]),
   closedPRs: external_exports3.array(StoredClosedPRSchema).default([]),
   savedResults: external_exports3.array(SavedCandidateSchema).default([]),
+  skippedIssues: external_exports3.array(SkippedIssueSchema).default([]),
   lastSearchAt: external_exports3.string().optional(),
   lastRunAt: external_exports3.string().default(() => (/* @__PURE__ */ new Date()).toISOString()),
   gistId: external_exports3.string().optional()
 });
 
 // ../core/dist/core/issue-filtering.js
-var DOC_ONLY_LABELS = /* @__PURE__ */ new Set(["documentation", "docs", "typo", "spelling"]);
+var DOC_ONLY_LABELS = /* @__PURE__ */ new Set([
+  "documentation",
+  "docs",
+  "typo",
+  "spelling"
+]);
 function isDocOnlyIssue(item) {
   if (!item.labels || !Array.isArray(item.labels) || item.labels.length === 0)
     return false;
@@ -35827,7 +35880,9 @@ function detectLabelFarmingRepos(items) {
   const spamRepos = /* @__PURE__ */ new Set();
   const repoSpamCounts = /* @__PURE__ */ new Map();
   for (const item of items) {
-    const repoFullName = item.repository_url.split("/").slice(-2).join("/");
+    const repoFullName = extractRepoFromUrl(item.repository_url);
+    if (!repoFullName)
+      continue;
     if (isLabelFarming(item)) {
       spamRepos.add(repoFullName);
       continue;
@@ -35913,20 +35968,111 @@ function calculateViabilityScore(params) {
 
 // ../core/dist/core/category-mapping.js
 var CATEGORY_TOPICS = {
-  nonprofit: ["nonprofit", "social-good", "humanitarian", "charity", "social-impact", "civic-tech"],
-  devtools: ["developer-tools", "devtools", "cli", "sdk", "linter", "formatter", "build-tool"],
-  infrastructure: ["infrastructure", "cloud", "kubernetes", "docker", "devops", "monitoring", "observability"],
-  "web-frameworks": ["web-framework", "frontend", "backend", "fullstack", "nextjs", "react", "vue"],
-  "data-ml": ["machine-learning", "data-science", "deep-learning", "nlp", "data-pipeline", "analytics"],
-  education: ["education", "learning", "tutorial", "courseware", "edtech", "teaching"]
+  nonprofit: [
+    "nonprofit",
+    "social-good",
+    "humanitarian",
+    "charity",
+    "social-impact",
+    "civic-tech"
+  ],
+  devtools: [
+    "developer-tools",
+    "devtools",
+    "cli",
+    "sdk",
+    "linter",
+    "formatter",
+    "build-tool"
+  ],
+  infrastructure: [
+    "infrastructure",
+    "cloud",
+    "kubernetes",
+    "docker",
+    "devops",
+    "monitoring",
+    "observability"
+  ],
+  "web-frameworks": [
+    "web-framework",
+    "frontend",
+    "backend",
+    "fullstack",
+    "nextjs",
+    "react",
+    "vue"
+  ],
+  "data-ml": [
+    "machine-learning",
+    "data-science",
+    "deep-learning",
+    "nlp",
+    "data-pipeline",
+    "analytics"
+  ],
+  education: [
+    "education",
+    "learning",
+    "tutorial",
+    "courseware",
+    "edtech",
+    "teaching"
+  ]
 };
 var CATEGORY_ORGS = {
-  nonprofit: ["code-for-america", "opengovfoundation", "ushahidi", "hotosm", "openfn", "democracyearth"],
-  devtools: ["eslint", "prettier", "vitejs", "biomejs", "oxc-project", "ast-grep", "turbot"],
-  infrastructure: ["kubernetes", "hashicorp", "grafana", "prometheus", "open-telemetry", "envoyproxy", "cncf"],
-  "web-frameworks": ["vercel", "remix-run", "sveltejs", "nuxt", "astro", "redwoodjs", "blitz-js"],
-  "data-ml": ["huggingface", "mlflow", "apache", "dbt-labs", "dagster-io", "prefecthq", "langchain-ai"],
-  education: ["freeCodeCamp", "TheOdinProject", "exercism", "codecademy", "oppia", "Khan"]
+  nonprofit: [
+    "code-for-america",
+    "opengovfoundation",
+    "ushahidi",
+    "hotosm",
+    "openfn",
+    "democracyearth"
+  ],
+  devtools: [
+    "eslint",
+    "prettier",
+    "vitejs",
+    "biomejs",
+    "oxc-project",
+    "ast-grep",
+    "turbot"
+  ],
+  infrastructure: [
+    "kubernetes",
+    "hashicorp",
+    "grafana",
+    "prometheus",
+    "open-telemetry",
+    "envoyproxy",
+    "cncf"
+  ],
+  "web-frameworks": [
+    "vercel",
+    "remix-run",
+    "sveltejs",
+    "nuxt",
+    "astro",
+    "redwoodjs",
+    "blitz-js"
+  ],
+  "data-ml": [
+    "huggingface",
+    "mlflow",
+    "apache",
+    "dbt-labs",
+    "dagster-io",
+    "prefecthq",
+    "langchain-ai"
+  ],
+  education: [
+    "freeCodeCamp",
+    "TheOdinProject",
+    "exercism",
+    "codecademy",
+    "oppia",
+    "Khan"
+  ]
 };
 function repoBelongsToCategory(repoFullName, categories) {
   if (categories.length === 0)
@@ -36046,7 +36192,10 @@ var HttpCache = class {
       cachedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     try {
-      fs2.writeFileSync(this.pathFor(url2), JSON.stringify(entry), { encoding: "utf-8", mode: 384 });
+      fs2.writeFileSync(this.pathFor(url2), JSON.stringify(entry), {
+        encoding: "utf-8",
+        mode: 384
+      });
       debug(MODULE4, `Cached response for ${url2}`);
     } catch (err) {
       warn(MODULE4, `Failed to write cache for ${url2}: ${errorMessage(err)}`);
@@ -36301,7 +36450,12 @@ function analyzeRequirements(body) {
   const hasSteps = /\d\.|[-*]\s/.test(body);
   const hasCodeBlock = /```/.test(body);
   const hasExpectedBehavior = /expect|should|must|want/i.test(body);
-  const indicators = [hasSteps, hasCodeBlock, hasExpectedBehavior, body.length > 200];
+  const indicators = [
+    hasSteps,
+    hasCodeBlock,
+    hasExpectedBehavior,
+    body.length > 200
+  ];
   return indicators.filter(Boolean).length >= 2;
 }
 
@@ -36378,7 +36532,12 @@ async function fetchContributionGuidelines(octokit, owner, repo) {
   if (cached2 && Date.now() - cached2.fetchedAt < CACHE_TTL_MS) {
     return cached2.guidelines;
   }
-  const filesToCheck = ["CONTRIBUTING.md", ".github/CONTRIBUTING.md", "docs/CONTRIBUTING.md", "contributing.md"];
+  const filesToCheck = [
+    "CONTRIBUTING.md",
+    ".github/CONTRIBUTING.md",
+    "docs/CONTRIBUTING.md",
+    "contributing.md"
+  ];
   const results = await Promise.allSettled(filesToCheck.map((file2) => octokit.repos.getContent({ owner, repo, path: file2 }).then(({ data }) => {
     if ("content" in data) {
       return Buffer.from(data.content, "base64").toString("utf-8");
@@ -36400,7 +36559,10 @@ async function fetchContributionGuidelines(octokit, owner, repo) {
       }
     }
   }
-  guidelinesCache.set(cacheKey, { guidelines: void 0, fetchedAt: Date.now() });
+  guidelinesCache.set(cacheKey, {
+    guidelines: void 0,
+    fetchedAt: Date.now()
+  });
   pruneCache();
   return void 0;
 }
@@ -36603,12 +36765,9 @@ var IssueVetter = class {
       matchesPreferredCategory: matchesCategory
     });
     const starredRepos = this.stateReader.getStarredRepos();
-    const preferredOrgs = this.stateReader.getPreferredOrgs();
     let searchPriority = "normal";
     if (effectiveMergedCount > 0) {
       searchPriority = "merged_pr";
-    } else if (preferredOrgs.some((o) => o.toLowerCase() === orgName?.toLowerCase())) {
-      searchPriority = "preferred_org";
     } else if (starredRepos.includes(repoFullName)) {
       searchPriority = "starred";
     }
@@ -36662,7 +36821,11 @@ var IssueVetter = class {
     if (allFailed) {
       warn(MODULE7, `All ${attemptedCount} issue(s) failed vetting. This may indicate a systemic issue (rate limit, auth, network).`);
     }
-    return { candidates: candidates.slice(0, maxResults), allFailed, rateLimitHit: rateLimitFailures > 0 };
+    return {
+      candidates: candidates.slice(0, maxResults),
+      allFailed,
+      rateLimitHit: rateLimitFailures > 0
+    };
   }
 };
 
@@ -36763,11 +36926,13 @@ async function searchWithChunkedLabels(octokit, labels, reservedOps, buildQuery,
 async function filterVetAndScore(vetter, items, filterIssues, excludedRepoSets, remainingNeeded, minStars, phaseLabel) {
   const spamRepos = detectLabelFarmingRepos(items);
   if (spamRepos.size > 0) {
-    const spamCount = items.filter((i) => spamRepos.has(i.repository_url.split("/").slice(-2).join("/"))).length;
+    const spamCount = items.filter((i) => spamRepos.has(extractRepoFromUrl(i.repository_url) ?? "")).length;
     debug(MODULE8, `[SPAM_FILTER] Filtered ${spamCount} issues from ${spamRepos.size} label-farming repos: ${[...spamRepos].join(", ")}`);
   }
   const itemsToVet = filterIssues(items).filter((item) => {
-    const repoFullName = item.repository_url.split("/").slice(-2).join("/");
+    const repoFullName = extractRepoFromUrl(item.repository_url);
+    if (!repoFullName)
+      return false;
     if (spamRepos.has(repoFullName))
       return false;
     return excludedRepoSets.every((s) => !s.has(repoFullName));
@@ -36835,6 +37000,152 @@ var MODULE9 = "issue-discovery";
 var INTER_PHASE_DELAY_MS = 2e3;
 var LOW_BUDGET_THRESHOLD = 20;
 var CRITICAL_BUDGET_THRESHOLD = 10;
+function buildIssueFilter(config2) {
+  return (items) => {
+    return items.filter((item) => {
+      const repoFullName = extractRepoFromUrl(item.repository_url);
+      if (!repoFullName)
+        return false;
+      if (config2.excludedRepos.has(repoFullName))
+        return false;
+      if (config2.excludeOrgs.size > 0) {
+        const orgName = repoFullName.split("/")[0]?.toLowerCase();
+        if (orgName && config2.excludeOrgs.has(orgName))
+          return false;
+      }
+      if (config2.aiBlocklisted.has(repoFullName))
+        return false;
+      if (config2.lowScoringRepos.has(repoFullName))
+        return false;
+      if (config2.skippedUrls.has(item.html_url))
+        return false;
+      const updatedAt = new Date(item.updated_at);
+      const ageDays = daysBetween(updatedAt, config2.now);
+      if (ageDays > config2.maxAgeDays)
+        return false;
+      if (!config2.includeDocIssues && isDocOnlyIssue(item))
+        return false;
+      return true;
+    });
+  };
+}
+async function runPhase0(octokit, vetter, repos, baseQualifiers, maxResults, filterIssues) {
+  info(MODULE9, `Phase 0: Searching issues in ${repos.length} merged-PR repos (no label filter)...`);
+  const { candidates, allBatchesFailed, rateLimitHit } = await searchInRepos(octokit, vetter, repos, baseQualifiers, [], maxResults, "merged_pr", filterIssues);
+  info(MODULE9, `Found ${candidates.length} candidates from merged-PR repos`);
+  return {
+    candidates,
+    error: allBatchesFailed ? "All merged-PR repo batches failed" : null,
+    rateLimitHit
+  };
+}
+async function runPhase1(octokit, vetter, repos, baseQualifiers, labels, maxResults, filterIssues) {
+  info(MODULE9, `Phase 1: Searching issues in ${repos.length} starred repos...`);
+  const phase1Labels = labels.slice(0, 3);
+  const { candidates, allBatchesFailed, rateLimitHit } = await searchInRepos(octokit, vetter, repos.slice(0, 10), baseQualifiers, phase1Labels, maxResults, "starred", filterIssues);
+  info(MODULE9, `Found ${candidates.length} candidates from starred repos`);
+  return {
+    candidates,
+    error: allBatchesFailed ? "All starred repo batches failed" : null,
+    rateLimitHit
+  };
+}
+async function runPhase2(octokit, vetter, scopes, labels, configLabels, baseQualifiers, maxResults, minStars, phase0RepoSet, starredRepoSet, existingCandidates, filterIssues) {
+  info(MODULE9, "Phase 2: General issue search...");
+  const seenRepos = new Set(existingCandidates.map((c) => c.issue.repo));
+  const tierLabelGroups = [];
+  if (scopes && scopes.length > 1) {
+    for (const scope of scopes) {
+      const scopeLabels = SCOPE_LABELS[scope] ?? [];
+      if (scopeLabels.length === 0) {
+        warn(MODULE9, `Scope "${scope}" has no labels, skipping tier`);
+        continue;
+      }
+      tierLabelGroups.push({ tier: scope, tierLabels: scopeLabels });
+    }
+    const allScopeLabels = new Set(scopes.flatMap((s) => SCOPE_LABELS[s] ?? []));
+    const customOnly = configLabels.filter((l) => !allScopeLabels.has(l));
+    if (customOnly.length > 0) {
+      tierLabelGroups.push({ tier: "custom", tierLabels: customOnly });
+    }
+  } else {
+    tierLabelGroups.push({ tier: "general", tierLabels: labels });
+  }
+  const budgetPerTier = Math.ceil(maxResults / tierLabelGroups.length);
+  const tierResults = [];
+  let error48 = null;
+  let rateLimitHit = false;
+  for (const { tier, tierLabels } of tierLabelGroups) {
+    try {
+      const allItems = await searchWithChunkedLabels(octokit, tierLabels, 0, (labelQ) => `${baseQualifiers} ${labelQ}`.replace(/  +/g, " ").trim(), budgetPerTier * 3);
+      info(MODULE9, `Phase 2 [${tier}]: processing ${allItems.length} items...`);
+      const { candidates: tierCandidates, allVetFailed, rateLimitHit: vetRateLimitHit } = await filterVetAndScore(vetter, allItems, filterIssues, [phase0RepoSet, starredRepoSet, seenRepos], budgetPerTier, minStars, `Phase 2 [${tier}]`);
+      tierResults.push(tierCandidates);
+      for (const c of tierCandidates)
+        seenRepos.add(c.issue.repo);
+      if (allVetFailed) {
+        error48 = (error48 ? error48 + "; " : "") + `${tier}: all vetting failed`;
+      }
+      if (vetRateLimitHit) {
+        rateLimitHit = true;
+      }
+      info(MODULE9, `Found ${tierCandidates.length} candidates from ${tier} tier`);
+    } catch (err) {
+      if (getHttpStatusCode(err) === 401)
+        throw err;
+      const errMsg = errorMessage(err);
+      error48 = (error48 ? error48 + "; " : "") + `${tier}: ${errMsg}`;
+      if (isRateLimitError(err)) {
+        rateLimitHit = true;
+      }
+      warn(MODULE9, `Error in ${tier} tier search: ${errMsg}`);
+      tierResults.push([]);
+    }
+  }
+  const interleaved = interleaveArrays(tierResults);
+  if (interleaved.length === 0 && error48) {
+    warn(MODULE9, `All ${tierLabelGroups.length} scope tiers failed in Phase 2: ${error48}`);
+  }
+  return {
+    candidates: interleaved.slice(0, maxResults),
+    error: error48,
+    rateLimitHit
+  };
+}
+async function runPhase3(octokit, vetter, langQuery, minStars, projectCategories, maxResults, phase0RepoSet, starredRepoSet, existingCandidates, filterIssues) {
+  info(MODULE9, "Phase 3: Searching actively maintained repos...");
+  const thirtyDaysAgo = /* @__PURE__ */ new Date();
+  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
+  const pushedSince = thirtyDaysAgo.toISOString().split("T")[0];
+  const categoryTopics = getTopicsForCategories(projectCategories);
+  const topicQuery = categoryTopics.length > 0 ? `topic:${categoryTopics[0]}` : "";
+  const phase3Query = `is:issue is:open no:assignee ${langQuery} ${topicQuery} stars:>=${minStars} pushed:>=${pushedSince} archived:false`.replace(/  +/g, " ").trim();
+  try {
+    const data = await cachedSearchIssues(octokit, {
+      q: phase3Query,
+      sort: "updated",
+      order: "desc",
+      per_page: maxResults * 3
+    });
+    info(MODULE9, `Found ${data.total_count} issues in maintained-repo search, processing top ${data.items.length}...`);
+    const seenRepos = new Set(existingCandidates.map((c) => c.issue.repo));
+    const { candidates, allVetFailed, rateLimitHit: vetRateLimitHit } = await filterVetAndScore(vetter, data.items, filterIssues, [phase0RepoSet, starredRepoSet, seenRepos], maxResults, minStars, "Phase 3");
+    info(MODULE9, `Found ${candidates.length} candidates from maintained-repo search`);
+    return {
+      candidates,
+      error: allVetFailed ? "all vetting failed" : null,
+      rateLimitHit: vetRateLimitHit
+    };
+  } catch (error48) {
+    const errMsg = errorMessage(error48);
+    warn(MODULE9, `Error in maintained-repo search: ${errMsg}`);
+    return {
+      candidates: [],
+      error: errMsg,
+      rateLimitHit: isRateLimitError(error48)
+    };
+  }
+}
 var IssueDiscovery = class {
   preferences;
   stateReader;
@@ -36864,8 +37175,8 @@ var IssueDiscovery = class {
   }
   /**
    * Search for issues matching our criteria.
-   * Searches in priority order: merged-PR repos first (no label filter), then preferred
-   * organizations, then starred repos, then general search, then actively maintained repos.
+   * Searches in priority order: merged-PR repos first (no label filter), then starred
+   * repos, then general search, then actively maintained repos.
    * Filters out issues from low-scoring and excluded repos.
    *
    * @param options - Search configuration
@@ -36898,8 +37209,7 @@ var IssueDiscovery = class {
     const enabledStrategies = new Set(rawStrategies.includes("all") ? ALL_STRATEGIES : rawStrategies);
     const strategiesUsed = [];
     const allCandidates = [];
-    let phase0Error = null;
-    let phase1Error = null;
+    const phaseErrors = {};
     let rateLimitHitDuringSearch = false;
     this.rateLimitWarning = null;
     const tracker = getSearchBudgetTracker();
@@ -36919,235 +37229,82 @@ var IssueDiscovery = class {
         info(MODULE9, `Search budget low (${searchBudget} remaining) \u2014 skipping heavy phases (2, 3)`);
       }
     } catch (error48) {
-      if (getHttpStatusCode(error48) === 401) {
+      if (getHttpStatusCode(error48) === 401)
         throw error48;
-      }
       tracker.init(CRITICAL_BUDGET_THRESHOLD, new Date(Date.now() + 6e4).toISOString());
       warn(MODULE9, "Could not check rate limit \u2014 using conservative budget, skipping heavy phases:", errorMessage(error48));
     }
+    if (searchBudget <= 0) {
+      this.rateLimitWarning = "GitHub search API quota exhausted. Try again after the rate limit resets.";
+      return { candidates: [], strategiesUsed: [] };
+    }
     const mergedPRRepos = this.stateReader.getReposWithMergedPRs();
     const starredRepos = this.getStarredRepos();
     const starredRepoSet = new Set(starredRepos);
-    const minRepoScoreThreshold = config2.minRepoScoreThreshold;
-    const lowScoringRepos = new Set(this.deriveLowScoringRepos(minRepoScoreThreshold));
-    const excludedRepos = new Set(config2.excludeRepos);
-    const excludeOrgs = new Set((config2.excludeOrgs ?? []).map((o) => o.toLowerCase()));
-    const maxAgeDays = config2.maxIssueAgeDays || 90;
-    const now = /* @__PURE__ */ new Date();
+    const lowScoringRepos = new Set(this.deriveLowScoringRepos(config2.minRepoScoreThreshold));
     const isAnyLanguage = languages.some((l) => l.toLowerCase() === "any");
     const langQuery = isAnyLanguage ? "" : languages.map((l) => `language:${l}`).join(" ");
     const baseQualifiers = `is:issue is:open ${langQuery} no:assignee`.replace(/  +/g, " ").trim();
-    const includeDocIssues = config2.includeDocIssues ?? true;
     const aiBlocklisted = new Set(config2.aiPolicyBlocklist);
     if (aiBlocklisted.size > 0) {
       debug(MODULE9, `[AI_POLICY_FILTER] Filtering issues from ${aiBlocklisted.size} blocklisted repo(s): ${[...aiBlocklisted].join(", ")}`);
     }
-    const filterIssues = (items) => {
-      return items.filter((item) => {
-        const repoFullName = item.repository_url.split("/").slice(-2).join("/");
-        if (excludedRepos.has(repoFullName))
-          return false;
-        if (excludeOrgs.size > 0) {
-          const orgName = repoFullName.split("/")[0]?.toLowerCase();
-          if (orgName && excludeOrgs.has(orgName))
-            return false;
-        }
-        if (aiBlocklisted.has(repoFullName))
-          return false;
-        if (lowScoringRepos.has(repoFullName))
-          return false;
-        const updatedAt = new Date(item.updated_at);
-        const ageDays = daysBetween(updatedAt, now);
-        if (ageDays > maxAgeDays)
-          return false;
-        if (!includeDocIssues && isDocOnlyIssue(item))
-          return false;
-        return true;
-      });
-    };
+    const filterIssues = buildIssueFilter({
+      excludedRepos: new Set(config2.excludeRepos),
+      excludeOrgs: new Set((config2.excludeOrgs ?? []).map((o) => o.toLowerCase())),
+      aiBlocklisted,
+      lowScoringRepos,
+      skippedUrls: options.skippedUrls ?? /* @__PURE__ */ new Set(),
+      maxAgeDays: config2.maxIssueAgeDays || 90,
+      now: /* @__PURE__ */ new Date(),
+      includeDocIssues: config2.includeDocIssues ?? true
+    });
     const phase0Repos = mergedPRRepos.slice(0, 10);
     const phase0RepoSet = new Set(phase0Repos);
     if (phase0Repos.length > 0 && enabledStrategies.has("merged")) {
-      info(MODULE9, `Phase 0: Searching issues in ${phase0Repos.length} merged-PR repos (no label filter)...`);
-      const remainingNeeded = maxResults - allCandidates.length;
-      if (remainingNeeded > 0) {
-        const { candidates: mergedCandidates, allBatchesFailed, rateLimitHit } = await searchInRepos(this.octokit, this.vetter, phase0Repos, baseQualifiers, [], remainingNeeded, "merged_pr", filterIssues);
-        allCandidates.push(...mergedCandidates);
-        if (allBatchesFailed) {
-          phase0Error = "All merged-PR repo batches failed";
-        }
-        if (rateLimitHit) {
+      const remaining = maxResults - allCandidates.length;
+      if (remaining > 0) {
+        const result = await runPhase0(this.octokit, this.vetter, phase0Repos, baseQualifiers, remaining, filterIssues);
+        allCandidates.push(...result.candidates);
+        phaseErrors["0"] = result.error;
+        if (result.rateLimitHit)
           rateLimitHitDuringSearch = true;
-        }
-        info(MODULE9, `Found ${mergedCandidates.length} candidates from merged-PR repos`);
       }
       strategiesUsed.push("merged");
     }
-    let phase0_5Error = null;
-    const preferredOrgs = config2.preferredOrgs ?? [];
-    if (allCandidates.length < maxResults && preferredOrgs.length > 0 && searchBudget >= CRITICAL_BUDGET_THRESHOLD && enabledStrategies.has("orgs")) {
-      if (phase0Repos.length > 0)
-        await sleep(INTER_PHASE_DELAY_MS);
-      const phase0Orgs = new Set(phase0Repos.map((r) => r.split("/")[0]?.toLowerCase()));
-      const orgsToSearch = preferredOrgs.filter((org) => !phase0Orgs.has(org.toLowerCase())).slice(0, 5);
-      if (orgsToSearch.length > 0) {
-        info(MODULE9, `Phase 0.5: Searching issues in ${orgsToSearch.length} preferred org(s)...`);
-        const remainingNeeded = maxResults - allCandidates.length;
-        const orgRepoFilter = orgsToSearch.map((org) => `org:${org}`).join(" OR ");
-        const orgOps = orgsToSearch.length - 1;
-        try {
-          const allItems = await searchWithChunkedLabels(this.octokit, labels, orgOps, (labelQ) => `${baseQualifiers} ${labelQ} (${orgRepoFilter})`.replace(/  +/g, " ").trim(), remainingNeeded * 3);
-          if (allItems.length > 0) {
-            const filtered = filterIssues(allItems).filter((item) => {
-              const repoFullName = item.repository_url.split("/").slice(-2).join("/");
-              return !phase0RepoSet.has(repoFullName);
-            });
-            const { candidates: orgCandidates, allFailed: allVetFailed, rateLimitHit } = await this.vetter.vetIssuesParallel(filtered.slice(0, remainingNeeded * 2).map((i) => i.html_url), remainingNeeded, "preferred_org");
-            allCandidates.push(...orgCandidates);
-            if (allVetFailed) {
-              phase0_5Error = "All preferred org issue vetting failed";
-            }
-            if (rateLimitHit) {
-              rateLimitHitDuringSearch = true;
-            }
-            info(MODULE9, `Found ${orgCandidates.length} candidates from preferred orgs`);
-          }
-        } catch (error48) {
-          const errMsg = errorMessage(error48);
-          phase0_5Error = errMsg;
-          if (isRateLimitError(error48)) {
-            rateLimitHitDuringSearch = true;
-          }
-          warn(MODULE9, `Error searching preferred orgs: ${errMsg}`);
-        }
-      }
-      strategiesUsed.push("orgs");
-    }
     if (allCandidates.length < maxResults && starredRepos.length > 0 && searchBudget >= CRITICAL_BUDGET_THRESHOLD && enabledStrategies.has("starred")) {
       await sleep(INTER_PHASE_DELAY_MS);
       const reposToSearch = starredRepos.filter((r) => !phase0RepoSet.has(r));
       if (reposToSearch.length > 0) {
-        info(MODULE9, `Phase 1: Searching issues in ${reposToSearch.length} starred repos...`);
-        const remainingNeeded = maxResults - allCandidates.length;
-        if (remainingNeeded > 0) {
-          const phase1Labels = labels.slice(0, 3);
-          const { candidates: starredCandidates, allBatchesFailed, rateLimitHit } = await searchInRepos(this.octokit, this.vetter, reposToSearch.slice(0, 10), baseQualifiers, phase1Labels, remainingNeeded, "starred", filterIssues);
-          allCandidates.push(...starredCandidates);
-          if (allBatchesFailed) {
-            phase1Error = "All starred repo batches failed";
-          }
-          if (rateLimitHit) {
+        const remaining = maxResults - allCandidates.length;
+        if (remaining > 0) {
+          const result = await runPhase1(this.octokit, this.vetter, reposToSearch, baseQualifiers, labels, remaining, filterIssues);
+          allCandidates.push(...result.candidates);
+          phaseErrors["1"] = result.error;
+          if (result.rateLimitHit)
             rateLimitHitDuringSearch = true;
-          }
-          info(MODULE9, `Found ${starredCandidates.length} candidates from starred repos`);
         }
       }
       strategiesUsed.push("starred");
     }
-    let phase2Error = null;
     if (allCandidates.length < maxResults && searchBudget >= LOW_BUDGET_THRESHOLD && enabledStrategies.has("broad")) {
       await sleep(INTER_PHASE_DELAY_MS);
-      info(MODULE9, "Phase 2: General issue search...");
-      const remainingNeeded = maxResults - allCandidates.length;
-      const seenRepos = new Set(allCandidates.map((c) => c.issue.repo));
-      const tierLabelGroups = [];
-      if (scopes && scopes.length > 1) {
-        for (const scope of scopes) {
-          const scopeLabels = SCOPE_LABELS[scope] ?? [];
-          if (scopeLabels.length === 0) {
-            warn(MODULE9, `Scope "${scope}" has no labels, skipping tier`);
-            continue;
-          }
-          tierLabelGroups.push({ tier: scope, tierLabels: scopeLabels });
-        }
-        const allScopeLabels = new Set(scopes.flatMap((s) => SCOPE_LABELS[s] ?? []));
-        const customOnly = config2.labels.filter((l) => !allScopeLabels.has(l));
-        if (customOnly.length > 0) {
-          tierLabelGroups.push({ tier: "custom", tierLabels: customOnly });
-        }
-      } else {
-        tierLabelGroups.push({ tier: "general", tierLabels: labels });
-      }
-      const budgetPerTier = Math.ceil(remainingNeeded / tierLabelGroups.length);
-      const tierResults = [];
-      for (const { tier, tierLabels } of tierLabelGroups) {
-        try {
-          const allItems = await searchWithChunkedLabels(
-            this.octokit,
-            tierLabels,
-            0,
-            // no repo/org ORs in Phase 2
-            (labelQ) => `${baseQualifiers} ${labelQ}`.replace(/  +/g, " ").trim(),
-            budgetPerTier * 3
-          );
-          info(MODULE9, `Phase 2 [${tier}]: processing ${allItems.length} items...`);
-          const { candidates: tierCandidates, allVetFailed, rateLimitHit: vetRateLimitHit } = await filterVetAndScore(this.vetter, allItems, filterIssues, [phase0RepoSet, starredRepoSet, seenRepos], budgetPerTier, minStars, `Phase 2 [${tier}]`);
-          tierResults.push(tierCandidates);
-          for (const c of tierCandidates)
-            seenRepos.add(c.issue.repo);
-          if (allVetFailed) {
-            phase2Error = (phase2Error ? phase2Error + "; " : "") + `${tier}: all vetting failed`;
-          }
-          if (vetRateLimitHit) {
-            rateLimitHitDuringSearch = true;
-          }
-          info(MODULE9, `Found ${tierCandidates.length} candidates from ${tier} tier`);
-        } catch (error48) {
-          if (getHttpStatusCode(error48) === 401)
-            throw error48;
-          const errMsg = errorMessage(error48);
-          phase2Error = (phase2Error ? phase2Error + "; " : "") + `${tier}: ${errMsg}`;
-          if (isRateLimitError(error48)) {
-            rateLimitHitDuringSearch = true;
-          }
-          warn(MODULE9, `Error in ${tier} tier search: ${errMsg}`);
-          tierResults.push([]);
-        }
-      }
-      const interleaved = interleaveArrays(tierResults);
-      if (interleaved.length === 0 && phase2Error) {
-        warn(MODULE9, `All ${tierLabelGroups.length} scope tiers failed in Phase 2: ${phase2Error}`);
-      }
-      allCandidates.push(...interleaved.slice(0, remainingNeeded));
+      const remaining = maxResults - allCandidates.length;
+      const result = await runPhase2(this.octokit, this.vetter, scopes, labels, config2.labels, baseQualifiers, remaining, minStars, phase0RepoSet, starredRepoSet, allCandidates, filterIssues);
+      allCandidates.push(...result.candidates);
+      phaseErrors["2"] = result.error;
+      if (result.rateLimitHit)
+        rateLimitHitDuringSearch = true;
       strategiesUsed.push("broad");
     }
-    let phase3Error = null;
     if (allCandidates.length < maxResults && searchBudget >= LOW_BUDGET_THRESHOLD && enabledStrategies.has("maintained")) {
       await sleep(INTER_PHASE_DELAY_MS);
-      info(MODULE9, "Phase 3: Searching actively maintained repos...");
-      const remainingNeeded = maxResults - allCandidates.length;
-      const thirtyDaysAgo = /* @__PURE__ */ new Date();
-      thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
-      const pushedSince = thirtyDaysAgo.toISOString().split("T")[0];
-      const categoryTopics = getTopicsForCategories(config2.projectCategories ?? []);
-      const topicQuery = categoryTopics.length > 0 ? `topic:${categoryTopics[0]}` : "";
-      const phase3Query = `is:issue is:open no:assignee ${langQuery} ${topicQuery} stars:>=${minStars} pushed:>=${pushedSince} archived:false`.replace(/  +/g, " ").trim();
-      try {
-        const data = await cachedSearchIssues(this.octokit, {
-          q: phase3Query,
-          sort: "updated",
-          order: "desc",
-          per_page: remainingNeeded * 3
-        });
-        info(MODULE9, `Found ${data.total_count} issues in maintained-repo search, processing top ${data.items.length}...`);
-        const seenRepos = new Set(allCandidates.map((c) => c.issue.repo));
-        const { candidates: starFiltered, allVetFailed, rateLimitHit: vetRateLimitHit } = await filterVetAndScore(this.vetter, data.items, filterIssues, [phase0RepoSet, starredRepoSet, seenRepos], remainingNeeded, minStars, "Phase 3");
-        allCandidates.push(...starFiltered);
-        if (allVetFailed) {
-          phase3Error = "all vetting failed";
-        }
-        if (vetRateLimitHit) {
-          rateLimitHitDuringSearch = true;
-        }
-        info(MODULE9, `Found ${starFiltered.length} candidates from maintained-repo search`);
-      } catch (error48) {
-        const errMsg = errorMessage(error48);
-        phase3Error = errMsg;
-        if (isRateLimitError(error48)) {
-          rateLimitHitDuringSearch = true;
-        }
-        warn(MODULE9, `Error in maintained-repo search: ${errMsg}`);
-      }
+      const remaining = maxResults - allCandidates.length;
+      const result = await runPhase3(this.octokit, this.vetter, langQuery, minStars, config2.projectCategories ?? [], remaining, phase0RepoSet, starredRepoSet, allCandidates, filterIssues);
+      allCandidates.push(...result.candidates);
+      phaseErrors["3"] = result.error;
+      if (result.rateLimitHit)
+        rateLimitHitDuringSearch = true;
       strategiesUsed.push("maintained");
     }
     const phasesSkippedForBudget = searchBudget < LOW_BUDGET_THRESHOLD;
@@ -37158,14 +37315,13 @@ var IssueDiscovery = class {
       budgetNote = ` Some search phases were skipped due to low API quota (${searchBudget} remaining).`;
     }
     if (allCandidates.length === 0) {
-      const phaseErrors = [
-        phase0Error ? `Phase 0 (merged-PR repos): ${phase0Error}` : null,
-        phase0_5Error ? `Phase 0.5 (preferred orgs): ${phase0_5Error}` : null,
-        phase1Error ? `Phase 1 (starred repos): ${phase1Error}` : null,
-        phase2Error ? `Phase 2 (general): ${phase2Error}` : null,
-        phase3Error ? `Phase 3 (maintained repos): ${phase3Error}` : null
+      const errorDetails = [
+        phaseErrors["0"] ? `Phase 0 (merged-PR repos): ${phaseErrors["0"]}` : null,
+        phaseErrors["1"] ? `Phase 1 (starred repos): ${phaseErrors["1"]}` : null,
+        phaseErrors["2"] ? `Phase 2 (general): ${phaseErrors["2"]}` : null,
+        phaseErrors["3"] ? `Phase 3 (maintained repos): ${phaseErrors["3"]}` : null
       ].filter(Boolean);
-      const details = phaseErrors.length > 0 ? ` ${phaseErrors.join(". ")}.` : "";
+      const details = errorDetails.length > 0 ? ` ${errorDetails.join(". ")}.` : "";
       if (rateLimitHitDuringSearch || phasesSkippedForBudget) {
         this.rateLimitWarning = `Search returned no results due to GitHub API rate limits.${details}${budgetNote} Try again after the rate limit resets.`;
         return { candidates: [], strategiesUsed };
@@ -37176,7 +37332,11 @@ var IssueDiscovery = class {
       this.rateLimitWarning = `Search results may be incomplete: GitHub API rate limits were hit during search.${budgetNote} Found ${allCandidates.length} candidate${allCandidates.length === 1 ? "" : "s"} but some search phases were limited. Try again after the rate limit resets for complete results.`;
     }
     allCandidates.sort((a, b) => {
-      const priorityOrder = { merged_pr: 0, preferred_org: 1, starred: 2, normal: 3 };
+      const priorityOrder = {
+        merged_pr: 0,
+        starred: 1,
+        normal: 2
+      };
       const priorityDiff = priorityOrder[a.searchPriority] - priorityOrder[b.searchPriority];
       if (priorityDiff !== 0)
         return priorityDiff;
@@ -37261,11 +37421,16 @@ var GistStateStore = class {
       warn(MODULE10, "No gist ID \u2014 cannot push");
       return false;
     }
+    const json2 = JSON.stringify(state, null, 2);
+    if (json2.length > 9e5) {
+      warn(MODULE10, `State too large for gist (${Math.round(json2.length / 1024)}KB). Consider clearing old results with 'oss-scout results clear'.`);
+      return false;
+    }
     try {
       await this.octokit.gists.update({
         gist_id: this.gistId,
         files: {
-          [GIST_FILENAME]: { content: JSON.stringify(state, null, 2) }
+          [GIST_FILENAME]: { content: json2 }
         }
       });
       debug(MODULE10, "State pushed to gist");
@@ -37323,6 +37488,8 @@ var GistStateStore = class {
         this.writeCache(state);
         return { gistId: foundId, state, created: false };
       }
+      warn(MODULE10, `Found existing gist ${foundId} but content failed validation. Using local cache to avoid data loss.`);
+      return this.bootstrapFromCache();
     }
     debug(MODULE10, "No existing gist found, creating new one");
     const freshState = ScoutStateSchema.parse({ version: 1 });
@@ -37418,7 +37585,9 @@ var GistStateStore = class {
   }
   writeCache(state) {
     try {
-      fs3.writeFileSync(getCachePath(), JSON.stringify(state, null, 2) + "\n", { mode: 384 });
+      fs3.writeFileSync(getCachePath(), JSON.stringify(state, null, 2) + "\n", {
+        mode: 384
+      });
     } catch (err) {
       warn(MODULE10, `Failed to write cache: ${errorMessage(err)}`);
     }
@@ -37434,6 +37603,7 @@ function mergeStates(local, remote) {
     mergedPRs: unionByUrl(local.mergedPRs, remote.mergedPRs),
     closedPRs: unionByUrl(local.closedPRs, remote.closedPRs),
     savedResults: mergeSavedResults(local.savedResults ?? [], remote.savedResults ?? []),
+    skippedIssues: mergeSkippedIssues(local.skippedIssues ?? [], remote.skippedIssues ?? []),
     lastSearchAt: pickFresherTimestamp(local.lastSearchAt, remote.lastSearchAt),
     lastRunAt: pickFresherTimestamp(local.lastRunAt, remote.lastRunAt) ?? (/* @__PURE__ */ new Date()).toISOString(),
     gistId: remote.gistId ?? local.gistId
@@ -37484,6 +37654,18 @@ function mergeSavedResults(local, remote) {
   }
   return [...merged.values()];
 }
+function mergeSkippedIssues(local, remote) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const item of local)
+    merged.set(item.url, item);
+  for (const item of remote) {
+    const existing = merged.get(item.url);
+    if (!existing || item.skippedAt > existing.skippedAt) {
+      merged.set(item.url, item);
+    }
+  }
+  return [...merged.values()];
+}
 function pickFresherTimestamp(a, b) {
   if (!a)
     return b;
@@ -37514,20 +37696,58 @@ function loadLocalState() {
       const backupPath = `${statePath}.corrupt.${Date.now()}`;
       fs4.copyFileSync(statePath, backupPath);
       warn(MODULE11, `Corrupt state backed up to ${backupPath}`);
-    } catch {
+    } catch (backupErr) {
+      warn(MODULE11, `Failed to back up corrupt state: ${errorMessage(backupErr)}`);
     }
     return ScoutStateSchema.parse({ version: 1 });
   }
 }
 
 // ../core/dist/scout.js
+function toGistOctokit(octokit) {
+  return {
+    gists: {
+      async get(params) {
+        const { data } = await octokit.gists.get(params);
+        if (!data.id)
+          throw new Error("Gist get returned no id");
+        const files = data.files ? Object.fromEntries(Object.entries(data.files).map(([k, v]) => [
+          k,
+          v ? { content: v.content } : void 0
+        ])) : null;
+        return { data: { id: data.id, files } };
+      },
+      async create(params) {
+        const { data } = await octokit.gists.create(params);
+        if (!data.id)
+          throw new Error("Gist create returned no id");
+        return { data: { id: data.id } };
+      },
+      async update(params) {
+        const { data } = await octokit.gists.update(params);
+        if (!data.id)
+          throw new Error("Gist update returned no id");
+        return { data: { id: data.id } };
+      },
+      async list(params) {
+        const { data } = await octokit.gists.list(params);
+        return {
+          data: data.filter((g) => g.id).map((g) => ({
+            id: g.id,
+            description: g.description ?? null
+          }))
+        };
+      }
+    }
+  };
+}
 async function createScout(config2) {
   let state;
   let gistStore = null;
   if (config2.persistence === "provided") {
     state = config2.initialState;
   } else if (config2.persistence === "gist") {
-    gistStore = new GistStateStore(getOctokit(config2.githubToken));
+    gistStore = new GistStateStore(toGistOctokit(getOctokit(config2.githubToken)));
     const result = await gistStore.bootstrap();
     if (result.degraded) {
       warn("scout", "Gist sync unavailable \u2014 running in offline mode. Changes will only be saved locally.");
@@ -37557,12 +37777,16 @@ var OssScout = class {
   // ── Search ──────────────────────────────────────────────────────────
   /**
    * Multi-strategy issue search. Returns scored, sorted candidates.
+   * Automatically culls expired skip entries and filters skipped issues.
    */
   async search(options) {
+    this.cullExpiredSkips();
+    const skippedUrls = new Set((this.state.skippedIssues ?? []).map((s) => s.url));
     const discovery = new IssueDiscovery(this.githubToken, this.state.preferences, this);
     const { candidates, strategiesUsed } = await discovery.searchIssues({
       maxResults: options?.maxResults,
-      strategies: options?.strategies
+      strategies: options?.strategies,
+      skippedUrls
     });
     this.state.lastSearchAt = (/* @__PURE__ */ new Date()).toISOString();
     this.dirty = true;
@@ -37653,7 +37877,7 @@ var OssScout = class {
   getReposWithMergedPRs() {
     const repoCounts = /* @__PURE__ */ new Map();
     for (const pr of this.state.mergedPRs ?? []) {
-      const repo = this.extractRepoFromUrl(pr.url);
+      const repo = extractRepoFromUrl(pr.url);
       if (repo) {
         repoCounts.set(repo, (repoCounts.get(repo) ?? 0) + 1);
       }
@@ -37663,9 +37887,6 @@ var OssScout = class {
   getStarredRepos() {
     return this.state.starredRepos;
   }
-  getPreferredOrgs() {
-    return this.state.preferences.preferredOrgs;
-  }
   getProjectCategories() {
     return this.state.preferences.projectCategories;
   }
@@ -37796,6 +38017,69 @@ var OssScout = class {
     this.state.savedResults = [];
     this.dirty = true;
   }
+  // ── Skip List ───────────────────────────────────────────────────────
+  /**
+   * Skip an issue — excludes it from future searches. Auto-culled after 90 days.
+   */
+  skipIssue(url2, metadata) {
+    const existing = this.state.skippedIssues ?? [];
+    if (existing.some((s) => s.url === url2))
+      return;
+    this.state.skippedIssues = [
+      ...existing,
+      {
+        url: url2,
+        repo: metadata?.repo ?? "",
+        number: metadata?.number ?? 0,
+        title: metadata?.title ?? "",
+        skippedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    ];
+    if (this.state.savedResults) {
+      this.state.savedResults = this.state.savedResults.filter((r) => r.issueUrl !== url2);
+    }
+    this.dirty = true;
+  }
+  /**
+   * Get all skipped issues.
+   */
+  getSkippedIssues() {
+    return this.state.skippedIssues ?? [];
+  }
+  /**
+   * Remove a specific issue from the skip list.
+   */
+  unskipIssue(url2) {
+    this.state.skippedIssues = (this.state.skippedIssues ?? []).filter((s) => s.url !== url2);
+    this.dirty = true;
+  }
+  /**
+   * Clear all skipped issues.
+   */
+  clearSkippedIssues() {
+    this.state.skippedIssues = [];
+    this.dirty = true;
+  }
+  /**
+   * Remove skipped issues older than maxDays (default 90). Called automatically during search.
+   * @returns The number of expired entries that were removed.
+   */
+  cullExpiredSkips(maxDays = 90) {
+    const cutoff = /* @__PURE__ */ new Date();
+    cutoff.setDate(cutoff.getDate() - maxDays);
+    const before = (this.state.skippedIssues ?? []).length;
+    this.state.skippedIssues = (this.state.skippedIssues ?? []).filter((s) => {
+      const d = new Date(s.skippedAt);
+      if (isNaN(d.getTime())) {
+        return true;
+      }
+      return d >= cutoff;
+    });
+    const culled = before - this.state.skippedIssues.length;
+    if (culled > 0)
+      this.dirty = true;
+    return culled;
+  }
   // ── Persistence ─────────────────────────────────────────────────────
   /**
    * Check if state has uncommitted changes.
@@ -37826,17 +38110,13 @@ var OssScout = class {
     return this.state;
   }
   // ── Private helpers ─────────────────────────────────────────────────
-  extractRepoFromUrl(url2) {
-    const match = url2.match(/github\.com\/([^/]+\/[^/]+)\//);
-    return match ? match[1] : null;
-  }
   updateRepoScoreFromPRs(repo) {
-    const mergedCount = (this.state.mergedPRs ?? []).filter((p) => this.extractRepoFromUrl(p.url) === repo).length;
-    const closedCount = (this.state.closedPRs ?? []).filter((p) => this.extractRepoFromUrl(p.url) === repo).length;
+    const mergedCount = (this.state.mergedPRs ?? []).filter((p) => extractRepoFromUrl(p.url) === repo).length;
+    const closedCount = (this.state.closedPRs ?? []).filter((p) => extractRepoFromUrl(p.url) === repo).length;
     this.updateRepoScore(repo, {
       mergedPRCount: mergedCount,
       closedWithoutMergeCount: closedCount,
-      lastMergedAt: mergedCount > 0 ? (this.state.mergedPRs ?? []).filter((p) => this.extractRepoFromUrl(p.url) === repo).sort((a, b) => b.mergedAt.localeCompare(a.mergedAt))[0]?.mergedAt : void 0
+      lastMergedAt: mergedCount > 0 ? (this.state.mergedPRs ?? []).filter((p) => extractRepoFromUrl(p.url) === repo).sort((a, b) => b.mergedAt.localeCompare(a.mergedAt))[0]?.mergedAt : void 0
     });
   }
   /**
@@ -37859,32 +38139,71 @@ var OssScout = class {
 };
 
 // src/tools.ts
+var TOOL_TIMEOUT_MS = 6e4;
+function withTimeout(promise2, ms = TOOL_TIMEOUT_MS) {
+  let timeoutId;
+  const timer = new Promise((_, reject) => {
+    timeoutId = setTimeout(
+      () => reject(new Error(`Request timed out after ${ms / 1e3}s`)),
+      ms
+    );
+  });
+  return Promise.race([promise2, timer]).finally(() => clearTimeout(timeoutId));
+}
 function registerTools(server, scout) {
   server.tool(
     "search",
     "Search for open source issues matching your preferences",
     {
       maxResults: external_exports3.number().optional().describe("Maximum number of results to return (default 10)"),
-      strategies: external_exports3.string().optional().describe("Comma-separated search strategies: merged, orgs, starred, broad, maintained, all")
+      strategies: external_exports3.string().optional().describe(
+        "Comma-separated search strategies: merged, starred, broad, maintained, all"
+      )
     },
     async ({ maxResults, strategies }) => {
-      const parsedStrategies = strategies ? strategies.split(",").map((s) => SearchStrategySchema.parse(s.trim())) : void 0;
-      const result = await scout.search({
-        maxResults: maxResults ?? 10,
-        strategies: parsedStrategies
-      });
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      try {
+        const parsedStrategies = strategies ? strategies.split(",").map((s) => SearchStrategySchema.parse(s.trim())) : void 0;
+        const result = await withTimeout(
+          scout.search({
+            maxResults: maxResults ?? 10,
+            strategies: parsedStrategies
+          })
+        );
+        scout.saveResults(result.candidates);
+        await scout.checkpoint();
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${msg}` }],
+          isError: true
+        };
+      }
     }
   );
   server.tool(
     "vet",
     "Vet a specific GitHub issue for contribution viability",
     {
-      issueUrl: external_exports3.string().describe("Full GitHub issue URL (e.g. https://github.com/owner/repo/issues/123)")
+      issueUrl: external_exports3.string().describe(
+        "Full GitHub issue URL (e.g. https://github.com/owner/repo/issues/123)"
+      )
     },
     async ({ issueUrl }) => {
-      const candidate = await scout.vetIssue(issueUrl);
-      return { content: [{ type: "text", text: JSON.stringify(candidate, null, 2) }] };
+      try {
+        const candidate = await withTimeout(scout.vetIssue(issueUrl));
+        return {
+          content: [{ type: "text", text: JSON.stringify(candidate, null, 2) }]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${msg}` }],
+          isError: true
+        };
+      }
     }
   );
   server.tool(
@@ -37892,33 +38211,131 @@ function registerTools(server, scout) {
     "Show current oss-scout configuration preferences",
     async () => {
       const preferences = scout.getPreferences();
-      return { content: [{ type: "text", text: JSON.stringify(preferences, null, 2) }] };
+      return {
+        content: [{ type: "text", text: JSON.stringify(preferences, null, 2) }]
+      };
+    }
+  );
+  server.tool(
+    "skip",
+    "Skip, unskip, list, or clear skipped issues. Skipped issues are excluded from future searches and auto-expire after 90 days.",
+    {
+      action: external_exports3.enum(["add", "remove", "list", "clear"]).default("add").describe("Action to perform (default: add)"),
+      issueUrl: external_exports3.string().optional().describe("GitHub issue URL (required for add/remove actions)")
+    },
+    async ({ action, issueUrl }) => {
+      try {
+        if ((action === "add" || action === "remove") && !issueUrl) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: issueUrl is required for the "${action}" action.`
+              }
+            ],
+            isError: true
+          };
+        }
+        if (action === "list") {
+          const skipped = scout.getSkippedIssues();
+          return {
+            content: [{ type: "text", text: JSON.stringify(skipped, null, 2) }]
+          };
+        }
+        if (action === "clear") {
+          const count = scout.getSkippedIssues().length;
+          scout.clearSkippedIssues();
+          const synced2 = await scout.checkpoint();
+          const syncNote2 = synced2 ? "" : " (saved locally, gist sync failed)";
+          return {
+            content: [
+              {
+                type: "text",
+                text: count > 0 ? `Skip list cleared (${count} entries removed)${syncNote2}` : `Skip list already empty${syncNote2}`
+              }
+            ]
+          };
+        }
+        if (action === "remove") {
+          const wasPresent = scout.getSkippedIssues().some((s) => s.url === issueUrl);
+          scout.unskipIssue(issueUrl);
+          const synced2 = await scout.checkpoint();
+          const syncNote2 = synced2 ? "" : " (saved locally, gist sync failed)";
+          return {
+            content: [
+              {
+                type: "text",
+                text: wasPresent ? `Removed from skip list: ${issueUrl}${syncNote2}` : `Not in skip list: ${issueUrl}`
+              }
+            ]
+          };
+        }
+        const alreadySkipped = scout.getSkippedIssues().some((s) => s.url === issueUrl);
+        if (alreadySkipped) {
+          return {
+            content: [
+              { type: "text", text: `Already in skip list: ${issueUrl}` }
+            ]
+          };
+        }
+        const saved = scout.getSavedResults().find((r) => r.issueUrl === issueUrl);
+        const metadata = saved ? {
+          repo: saved.repo,
+          number: saved.number,
+          title: saved.title
+        } : void 0;
+        scout.skipIssue(issueUrl, metadata);
+        const synced = await scout.checkpoint();
+        const syncNote = synced ? "" : " (saved locally, gist sync failed)";
+        return {
+          content: [{ type: "text", text: `Skipped: ${issueUrl}${syncNote}` }]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${msg}` }],
+          isError: true
+        };
+      }
     }
   );
   const VALID_KEYS = Object.keys(ScoutPreferencesSchema.shape);
   const ARRAY_KEYS = /* @__PURE__ */ new Set([
     "languages",
     "labels",
-    "preferredOrgs",
     "projectCategories",
     "excludeRepos",
+    "excludeOrgs",
     "aiPolicyBlocklist",
     "scope",
     "defaultStrategy"
   ]);
-  const NUMBER_KEYS = /* @__PURE__ */ new Set(["minStars", "maxIssueAgeDays", "minRepoScoreThreshold"]);
+  const NUMBER_KEYS = /* @__PURE__ */ new Set([
+    "minStars",
+    "maxIssueAgeDays",
+    "minRepoScoreThreshold"
+  ]);
   const BOOLEAN_KEYS = /* @__PURE__ */ new Set(["includeDocIssues"]);
   server.tool(
     "config-set",
     "Update an oss-scout configuration preference",
     {
-      key: external_exports3.string().describe("Preference key to update (e.g. languages, minStars, excludeRepos)"),
-      value: external_exports3.string().describe("New value \u2014 comma-separated for arrays, plain string for scalars")
+      key: external_exports3.string().describe(
+        "Preference key to update (e.g. languages, minStars, excludeRepos)"
+      ),
+      value: external_exports3.string().describe(
+        "New value \u2014 comma-separated for arrays, plain string for scalars"
+      )
     },
     async ({ key, value }) => {
       if (!VALID_KEYS.includes(key)) {
         return {
-          content: [{ type: "text", text: `Unknown config key: "${key}". Valid keys: ${VALID_KEYS.join(", ")}` }],
+          content: [
+            {
+              type: "text",
+              text: `Unknown config key: "${key}". Valid keys: ${VALID_KEYS.join(", ")}`
+            }
+          ],
           isError: true
         };
       }
@@ -37936,7 +38353,9 @@ function registerTools(server, scout) {
         const num = Number(value);
         if (isNaN(num)) {
           return {
-            content: [{ type: "text", text: `Invalid number for "${key}": "${value}"` }],
+            content: [
+              { type: "text", text: `Invalid number for "${key}": "${value}"` }
+            ],
             isError: true
           };
         }
@@ -37947,7 +38366,12 @@ function registerTools(server, scout) {
         else if (lower === "false" || lower === "no") parsed = false;
         else {
           return {
-            content: [{ type: "text", text: `Invalid boolean for "${key}": "${value}". Use true/false or yes/no.` }],
+            content: [
+              {
+                type: "text",
+                text: `Invalid boolean for "${key}": "${value}". Use true/false or yes/no.`
+              }
+            ],
             isError: true
           };
         }
@@ -37965,8 +38389,11 @@ function registerTools(server, scout) {
         };
       }
       scout.updatePreferences({ [key]: parsed });
+      await scout.checkpoint();
       const updated = scout.getPreferences();
-      return { content: [{ type: "text", text: JSON.stringify(updated, null, 2) }] };
+      return {
+        content: [{ type: "text", text: JSON.stringify(updated, null, 2) }]
+      };
     }
   );
 }
@@ -37978,11 +38405,13 @@ function registerResources(server, scout) {
     "scout://config",
     { description: "Current oss-scout preferences" },
     async () => ({
-      contents: [{
-        uri: "scout://config",
-        mimeType: "application/json",
-        text: JSON.stringify(scout.getPreferences(), null, 2)
-      }]
+      contents: [
+        {
+          uri: "scout://config",
+          mimeType: "application/json",
+          text: JSON.stringify(scout.getPreferences(), null, 2)
+        }
+      ]
     })
   );
   server.resource(
@@ -37990,11 +38419,13 @@ function registerResources(server, scout) {
     "scout://results",
     { description: "Saved search results from previous runs" },
     async () => ({
-      contents: [{
-        uri: "scout://results",
-        mimeType: "application/json",
-        text: JSON.stringify(scout.getSavedResults(), null, 2)
-      }]
+      contents: [
+        {
+          uri: "scout://results",
+          mimeType: "application/json",
+          text: JSON.stringify(scout.getSavedResults(), null, 2)
+        }
+      ]
     })
   );
   server.resource(
@@ -38004,11 +38435,13 @@ function registerResources(server, scout) {
     async () => {
       const state = scout.getState();
       return {
-        contents: [{
-          uri: "scout://scores",
-          mimeType: "application/json",
-          text: JSON.stringify(state.repoScores, null, 2)
-        }]
+        contents: [
+          {
+            uri: "scout://scores",
+            mimeType: "application/json",
+            text: JSON.stringify(state.repoScores, null, 2)
+          }
+        ]
       };
     }
   );
@@ -38025,7 +38458,7 @@ async function main() {
   }
   const scout = await createScout({ githubToken: token });
   const server = new McpServer(
-    { name: "@oss-scout/core", version: "0.1.0" },
+    { name: "oss-scout-mcp", version: "0.2.1" },
     { capabilities: { resources: {}, tools: {} } }
   );
   registerTools(server, scout);
@@ -38034,8 +38467,10 @@ async function main() {
   await server.connect(transport);
 }
 main().catch((err) => {
-  process.stderr.write(`oss-scout-mcp fatal: ${err instanceof Error ? err.message : String(err)}
-`);
+  process.stderr.write(
+    `oss-scout-mcp fatal: ${err instanceof Error ? err.message : String(err)}
+`
+  );
   process.exit(1);
 });
 /*! Bundled license information: