@oss-scout/core 0.11.0 → 1.1.0

package/dist/core/feature-discovery.js

@@ -11,10 +11,11 @@
  *
  * No state singletons — anchor repos are resolved from RepoScore[] passed in.
  */
-import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { errorMessage, rethrowIfFatal } from "./errors.js";
 import { warn } from "./logger.js";
 import { sleep } from "./utils.js";
 import { fetchRoadmapIssueRefs } from "./roadmap.js";
+import { cachedSearchIssues } from "./search-phases.js";
 const MODULE = "feature-discovery";
 /** Delay between per-repo issue lists, mirroring search-phases.INTER_QUERY_DELAY_MS. */
 const INTER_REPO_DELAY_MS = 2000;
@@ -164,6 +165,53 @@ function isFeatureIssue(item) {
         return false;
     return labels.some((l) => FEATURE_LABELS.includes(l));
 }
+/**
+ * Extract feature signals from a raw issue, vet it, and classify its horizon.
+ * Shared by the anchor (discoverFeatures) and broad (discoverFeaturesBroad)
+ * paths (#157). Returns null when vetting fails for this item so the caller
+ * can skip it; fatal errors (auth/rate-limit) propagate.
+ *
+ * `roadmapRefs` is only supplied by the anchor path: when present, the roadmap
+ * signal is threaded into both the vet call and the horizon classifier exactly
+ * as before; the broad path omits it (roadmap scraping is per-repo and kept out
+ * of the cheap broad search).
+ */
+async function vetAndClassify(item, vetter, roadmapRefs) {
+    const labels = extractLabels(item);
+    const hasMilestone = !!item.milestone;
+    const reactions = item.reactions?.total_count ?? 0;
+    const comments = item.comments ?? 0;
+    const wontfixNoContributor = item.created_at
+        ? detectWontfixNoContributor({ labels, createdAt: item.created_at })
+        : false;
+    const useRoadmap = roadmapRefs !== undefined;
+    const onRoadmap = useRoadmap &&
+        typeof item.number === "number" &&
+        roadmapRefs.has(item.number);
+    let candidate;
+    try {
+        candidate = await vetter.vetIssue(item.html_url, {
+            featureSignals: {
+                reactions,
+                comments,
+                hasMilestone,
+                wontfixNoContributor,
+                ...(useRoadmap ? { onRoadmap } : {}),
+            },
+        });
+    }
+    catch (err) {
+        rethrowIfFatal(err);
+        warn(MODULE, `vet failed for ${item.html_url}: ${errorMessage(err)}`);
+        return null;
+    }
+    const horizon = classifyHorizon({
+        hasMilestone,
+        labels,
+        ...(useRoadmap ? { isOnRoadmap: onRoadmap } : {}),
+    });
+    return { ...candidate, horizon };
+}
 /**
  * Orchestrate `scout features`: anchor resolution → per-repo issue listing
  * → feature-signal extraction → vetting → horizon classification → bucket split.
@@ -211,45 +259,15 @@ export async function discoverFeatures(opts) {
             roadmapRefs = refs;
         }
         catch (err) {
-            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-                throw err;
+            rethrowIfFatal(err);
             warn(MODULE, `failed to list issues for ${anchorRepos[i]}: ${errorMessage(err)}`);
             continue;
         }
         const items = response.data.filter((it) => !it.pull_request && !it.assignee && isFeatureIssue(it));
         for (const item of items) {
-            const labels = extractLabels(item);
-            const hasMilestone = !!item.milestone;
-            const reactions = item.reactions?.total_count ?? 0;
-            const comments = item.comments ?? 0;
-            const wontfixNoContributor = item.created_at
-                ? detectWontfixNoContributor({ labels, createdAt: item.created_at })
-                : false;
-            const onRoadmap = typeof item.number === "number" && roadmapRefs.has(item.number);
-            let candidate;
-            try {
-                candidate = await opts.vetter.vetIssue(item.html_url, {
-                    featureSignals: {
-                        reactions,
-                        comments,
-                        hasMilestone,
-                        wontfixNoContributor,
-                        onRoadmap,
-                    },
-                });
-            }
-            catch (err) {
-                if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-                    throw err;
-                warn(MODULE, `vet failed for ${item.html_url}: ${errorMessage(err)}`);
-                continue;
-            }
-            const horizon = classifyHorizon({
-                hasMilestone,
-                labels,
-                isOnRoadmap: onRoadmap,
-            });
-            candidates.push({ ...candidate, horizon });
+            const candidate = await vetAndClassify(item, opts.vetter, roadmapRefs);
+            if (candidate)
+                candidates.push(candidate);
         }
     }
     // Drop low-viability results — same threshold as scout search.
@@ -273,19 +291,16 @@ const DEFAULT_BROAD_MAX_TO_VET = 30;
  */
 export function buildBroadFeatureSearchQuery(opts) {
     const parts = ["is:issue", "is:open", "no:assignee"];
-    // Feature labels — any-of via parenthesized OR.
+    // Feature labels — any-of via parenthesized OR. The six labels spend
+    // exactly five OR operators, GitHub's entire per-query allowance.
     const labelClause = FEATURE_LABELS.map((l) => `label:"${l}"`).join(" OR ");
     parts.push(`(${labelClause})`);
     // Exclude labels that overlap with `scout` territory.
     for (const excl of FEATURE_EXCLUSION_LABELS) {
         parts.push(`-label:"${excl}"`);
     }
-    // Languages — skip the filter when "any" is the only preference, since
-    // GitHub Search has no `language:any` operator.
-    const languages = (opts.languages ?? []).filter((l) => l && l.toLowerCase() !== "any");
-    if (languages.length > 0) {
-        const langClause = languages.map((l) => `language:${l}`).join(" OR ");
-        parts.push(`(${langClause})`);
+    if (opts.language) {
+        parts.push(`language:${opts.language}`);
     }
     // User exclusions.
     for (const repo of opts.excludeRepos ?? []) {
@@ -296,6 +311,23 @@ export function buildBroadFeatureSearchQuery(opts) {
     }
     return parts.join(" ");
 }
+/**
+ * One query per language. A combined `(language:a OR language:b)` clause
+ * pushed the query past GitHub's 5-operator limit (the label ORs already
+ * spend all five), so every 2+ language config drew a 422 that the caller
+ * swallowed into "no results" (#121). "any" disables the filter.
+ */
+export function buildBroadFeatureSearchQueries(opts) {
+    const base = {
+        excludeRepos: opts.excludeRepos,
+        excludeOrgs: opts.excludeOrgs,
+    };
+    const languages = (opts.languages ?? []).filter((l) => l && l.toLowerCase() !== "any");
+    if (languages.length === 0) {
+        return [buildBroadFeatureSearchQuery(base)];
+    }
+    return languages.map((language) => buildBroadFeatureSearchQuery({ ...base, language }));
+}
 /**
  * Orchestrate broad / cross-repo feature discovery (#100). Bypasses anchor
  * resolution; runs a single GitHub Search API query for feature-labeled
@@ -310,7 +342,7 @@ export function buildBroadFeatureSearchQuery(opts) {
  * degrade gracefully.
  */
 export async function discoverFeaturesBroad(opts) {
-    const query = buildBroadFeatureSearchQuery({
+    const queries = buildBroadFeatureSearchQueries({
         languages: opts.languages,
         excludeRepos: opts.excludeRepos,
         excludeOrgs: opts.excludeOrgs,
@@ -318,17 +350,32 @@ export async function discoverFeaturesBroad(opts) {
     const maxToVet = opts.maxToVet ?? DEFAULT_BROAD_MAX_TO_VET;
     let items;
     try {
-        const response = await opts.octokit.search.issuesAndPullRequests({
-            q: query,
-            sort: "interactions",
-            order: "desc",
-            per_page: maxToVet,
-        });
-        items = response.data.items.filter((it) => !it.pull_request && !it.assignee && isFeatureIssue(it));
+        // cachedSearchIssues pays the budget tracker and the 15-minute search
+        // cache; this was previously the only Search API call in the pipeline
+        // outside that infrastructure (#121). Runtime items keep the rich
+        // fields (milestone, reactions, ...) the narrow cache type omits.
+        const merged = [];
+        const seenUrls = new Set();
+        for (const query of queries) {
+            const data = await cachedSearchIssues(opts.octokit, {
+                q: query,
+                sort: "interactions",
+                order: "desc",
+                per_page: maxToVet,
+            });
+            for (const raw of data.items) {
+                if (seenUrls.has(raw.html_url))
+                    continue;
+                seenUrls.add(raw.html_url);
+                merged.push(raw);
+            }
+        }
+        items = merged
+            .filter((it) => !it.pull_request && !it.assignee && isFeatureIssue(it))
+            .slice(0, maxToVet);
     }
     catch (err) {
-        if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-            throw err;
+        rethrowIfFatal(err);
         warn(MODULE, `broad feature search failed: ${errorMessage(err)}`);
         return {
             quickWins: [],
@@ -339,35 +386,11 @@ export async function discoverFeaturesBroad(opts) {
     }
     const candidates = [];
     for (const item of items) {
-        const labels = extractLabels(item);
-        const hasMilestone = !!item.milestone;
-        const reactions = item.reactions?.total_count ?? 0;
-        const comments = item.comments ?? 0;
-        const wontfixNoContributor = item.created_at
-            ? detectWontfixNoContributor({ labels, createdAt: item.created_at })
-            : false;
-        let candidate;
-        try {
-            candidate = await opts.vetter.vetIssue(item.html_url, {
-                featureSignals: {
-                    reactions,
-                    comments,
-                    hasMilestone,
-                    wontfixNoContributor,
-                    // Roadmap scraping is per-repo and would require an extra fetch
-                    // per unique repo in the broad result set — deliberately skipped
-                    // here to keep the broad path cheap. Anchor mode keeps the bonus.
-                },
-            });
-        }
-        catch (err) {
-            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-                throw err;
-            warn(MODULE, `vet failed for ${item.html_url}: ${errorMessage(err)}`);
-            continue;
-        }
-        const horizon = classifyHorizon({ hasMilestone, labels });
-        candidates.push({ ...candidate, horizon });
+        // No roadmapRefs: roadmap scraping is per-repo and deliberately skipped
+        // on the broad path to keep it cheap. Anchor mode keeps the bonus.
+        const candidate = await vetAndClassify(item, opts.vetter);
+        if (candidate)
+            candidates.push(candidate);
     }
     const passing = candidates.filter((c) => c.viabilityScore >= MIN_VIABILITY_SCORE);
     const split = splitByHorizon(passing, opts.count, opts.splitRatio);

package/dist/core/gist-state-store.d.ts

@@ -72,28 +72,29 @@ export declare class GistStateStore {
      * Push state to the gist. Also writes to local cache as fallback.
      */
     push(state: ScoutState): Promise<boolean>;
-    /**
-     * Pull state from the gist and merge with local state.
-     */
-    pull(): Promise<ScoutState | null>;
     /** Get the current gist ID (if known). */
     getGistId(): string | null;
     private bootstrapFromApi;
     private bootstrapFromCache;
     private fetchGistState;
+    /**
+     * Scan the user's gists for the state gist. `exhaustive: false` means the
+     * page cap was hit while pages were still full, so the account may hold
+     * the state gist beyond the scan window.
+     */
     private searchForGist;
     private createGist;
     private readCachedGistId;
     private saveGistId;
+    /**
+     * Merge the local state-cache into a freshly fetched gist state before it
+     * overwrites the cache (#117). Without this, a prior failed push left its
+     * only copy of the user's changes in state-cache.json, which the next
+     * successful bootstrap silently clobbered. Tombstone-aware mergeStates
+     * keeps both sides' real changes.
+     */
+    private mergeCacheInto;
     private readCache;
     private writeCache;
 }
-/**
- * Merge two ScoutState objects with conflict resolution:
- * - repoScores: per-repo, keep the one with more total PR activity
- * - mergedPRs/closedPRs/openPRs: union by URL
- * - preferences: remote wins
- * - starredRepos: keep the list with the fresher timestamp
- * - savedResults: union by issueUrl, keep newer lastSeenAt
- */
 export declare function mergeStates(local: ScoutState, remote: ScoutState): ScoutState;

package/dist/core/gist-state-store.js

@@ -6,28 +6,23 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import { ScoutStateSchema } from "./schemas.js";
+import { ScoutStateSchema, parseScoutState } from "./schemas.js";
 import { getDataDir } from "./utils.js";
 import { debug, warn } from "./logger.js";
-import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { errorMessage, getHttpStatusCode, isRateLimitError, rethrowIfFatal, } from "./errors.js";
 const MODULE = "gist-state";
 const GIST_DESCRIPTION = "oss-scout-state";
 const GIST_FILENAME = "state.json";
 const GIST_ID_FILE = "gist-id";
 const CACHE_FILE = "state-cache.json";
-const SEARCH_MAX_PAGES = 5;
+const SEARCH_MAX_PAGES = 10;
 /** Classify an unknown error into a DegradedReason for user-facing messaging. */
 function classifyDegradedReason(err) {
+    // isRateLimitError covers 429, 403 + "rate limit" (including secondary),
+    // and 403 + "abuse detection" (#138) — single source of truth.
     if (isRateLimitError(err))
         return "rate_limit";
     const status = getHttpStatusCode(err);
-    // GitHub's abuse-detection responses arrive as 403 with "abuse detection"
-    // in the message but no "rate limit" substring — match resolveErrorCode's
-    // logic in errors.ts so we don't misclassify as 'unknown'.
-    if (status === 403 &&
-        errorMessage(err).toLowerCase().includes("abuse detection")) {
-        return "rate_limit";
-    }
     if (status !== undefined && status >= 500 && status < 600)
         return "server";
     if (err && typeof err === "object" && "code" in err) {
@@ -81,12 +76,29 @@ export class GistStateStore {
      * Push state to the gist. Also writes to local cache as fallback.
      */
     async push(state) {
-        this.writeCache(state);
         if (!this.gistId) {
             warn(MODULE, "No gist ID — cannot push");
+            this.writeCache(state);
             return false;
         }
-        const json = JSON.stringify(state, null, 2);
+        // Fetch the current gist and merge before writing, so a concurrent push
+        // from another machine is not blindly clobbered (#117). The deletion
+        // tombstones in mergeStates keep removals from resurfacing. A fetch
+        // failure (not auth/rate-limit, which propagate) degrades to writing the
+        // local snapshot, the prior best-effort behavior.
+        let toWrite = state;
+        try {
+            const remote = await this.fetchGistState(this.gistId);
+            if (remote) {
+                toWrite = mergeStates(state, remote);
+            }
+        }
+        catch (err) {
+            rethrowIfFatal(err);
+            warn(MODULE, `Could not fetch gist before push, writing local snapshot: ${errorMessage(err)}`);
+        }
+        this.writeCache(toWrite);
+        const json = JSON.stringify(toWrite, null, 2);
         if (json.length > 900000) {
             warn(MODULE, `State too large for gist (${Math.round(json.length / 1024)}KB). Consider clearing old results with 'oss-scout results clear'.`);
             return false;
@@ -105,32 +117,11 @@ export class GistStateStore {
             // Both auth and rate-limit propagate per documented strategy.
             // Local cache write already happened above, so the user's work isn't
             // lost — but they need clear feedback that the sync failed.
-            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-                throw err;
+            rethrowIfFatal(err);
             warn(MODULE, `Failed to push: ${errorMessage(err)}`);
             return false;
         }
     }
-    /**
-     * Pull state from the gist and merge with local state.
-     */
-    async pull() {
-        if (!this.gistId)
-            return null;
-        try {
-            const state = await this.fetchGistState(this.gistId);
-            if (state) {
-                this.writeCache(state);
-            }
-            return state;
-        }
-        catch (err) {
-            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-                throw err;
-            warn(MODULE, `Failed to pull: ${errorMessage(err)}`);
-            return null;
-        }
-    }
     /** Get the current gist ID (if known). */
     getGistId() {
         return this.gistId;
@@ -142,9 +133,10 @@ export class GistStateStore {
         if (cachedId) {
             debug(MODULE, `Trying cached gist ID: ${cachedId}`);
             try {
-                const state = await this.fetchGistState(cachedId);
-                if (state) {
+                const fetched = await this.fetchGistState(cachedId);
+                if (fetched) {
                     this.gistId = cachedId;
+                    const state = this.mergeCacheInto(fetched);
                     this.writeCache(state);
                     return { gistId: cachedId, state, created: false };
                 }
@@ -162,21 +154,28 @@ export class GistStateStore {
             debug(MODULE, "Cached gist ID invalid, searching...");
         }
         // 2. Search user's gists
-        const foundId = await this.searchForGist();
-        if (foundId) {
-            debug(MODULE, `Found gist via search: ${foundId}`);
-            this.saveGistId(foundId);
-            this.gistId = foundId;
-            const state = await this.fetchGistState(foundId);
-            if (state) {
+        const search = await this.searchForGist();
+        if (search.id) {
+            debug(MODULE, `Found gist via search: ${search.id}`);
+            this.saveGistId(search.id);
+            this.gistId = search.id;
+            const fetched = await this.fetchGistState(search.id);
+            if (fetched) {
+                const state = this.mergeCacheInto(fetched);
                 this.writeCache(state);
-                return { gistId: foundId, state, created: false };
+                return { gistId: search.id, state, created: false };
             }
             // Gist exists but content failed validation — fall back to cache
             // to avoid overwriting the user's data by creating a new gist.
-            warn(MODULE, `Found existing gist ${foundId} but content failed validation. Using local cache to avoid data loss.`);
+            warn(MODULE, `Found existing gist ${search.id} but content failed validation. Using local cache to avoid data loss.`);
             return this.bootstrapFromCache("unknown");
         }
+        if (!search.exhaustive) {
+            // The account has more gists than we scanned; an existing state gist
+            // may sit beyond the scan window, and creating a new one would fork
+            // state across machines.
+            warn(MODULE, `Scanned the first ${SEARCH_MAX_PAGES * 100} gists without finding an oss-scout state gist, but the account has more. Creating a new state gist; if one already exists, copy its id into the gist-id file in the oss-scout data directory to avoid a duplicate.`);
+        }
         // 3. Create new gist
         debug(MODULE, "No existing gist found, creating new one");
         const freshState = ScoutStateSchema.parse({ version: 1 });
@@ -219,13 +218,18 @@ export class GistStateStore {
             return null;
         try {
             const parsed = JSON.parse(file.content);
-            return ScoutStateSchema.parse(parsed);
+            return parseScoutState(parsed);
         }
         catch (err) {
             warn(MODULE, `Gist content failed validation: ${errorMessage(err)}`);
             return null;
         }
     }
+    /**
+     * Scan the user's gists for the state gist. `exhaustive: false` means the
+     * page cap was hit while pages were still full, so the account may hold
+     * the state gist beyond the scan window.
+     */
     async searchForGist() {
         for (let page = 1; page <= SEARCH_MAX_PAGES; page++) {
             const { data: gists } = await this.octokit.gists.list({
@@ -233,12 +237,15 @@ export class GistStateStore {
                 page,
             });
             if (gists.length === 0)
-                break;
+                return { id: null, exhaustive: true };
             const match = gists.find((g) => g.description === GIST_DESCRIPTION);
             if (match)
-                return match.id;
+                return { id: match.id, exhaustive: true };
+            // A short page means we have seen every gist
+            if (gists.length < 100)
+                return { id: null, exhaustive: true };
         }
-        return null;
+        return { id: null, exhaustive: false };
     }
     async createGist(state) {
         const { data } = await this.octokit.gists.create({
@@ -267,10 +274,21 @@ export class GistStateStore {
     saveGistId(id) {
         fs.writeFileSync(getGistIdPath(), id + "\n", { mode: 0o600 });
     }
+    /**
+     * Merge the local state-cache into a freshly fetched gist state before it
+     * overwrites the cache (#117). Without this, a prior failed push left its
+     * only copy of the user's changes in state-cache.json, which the next
+     * successful bootstrap silently clobbered. Tombstone-aware mergeStates
+     * keeps both sides' real changes.
+     */
+    mergeCacheInto(fetched) {
+        const cached = this.readCache();
+        return cached ? mergeStates(cached, fetched) : fetched;
+    }
     readCache() {
         try {
             const raw = fs.readFileSync(getCachePath(), "utf-8");
-            return ScoutStateSchema.parse(JSON.parse(raw));
+            return parseScoutState(JSON.parse(raw));
         }
         catch (err) {
             const code = err?.code;
@@ -299,19 +317,76 @@ export class GistStateStore {
  * - preferences: remote wins
  * - starredRepos: keep the list with the fresher timestamp
  * - savedResults: union by issueUrl, keep newer lastSeenAt
+ * - unknown top-level keys (from a newer binary, #137): carried over via
+ *   spreads, remote wins on conflicts to mirror the preferences rule
  */
+/** Retain tombstones this long so a slow-to-sync machine still honors them. */
+const TOMBSTONE_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+/**
+ * Merge tombstones from both sides (newest removedAt per URL wins) and drop
+ * any older than the TTL so the list cannot grow without bound (#117).
+ */
+function mergeTombstones(local, remote) {
+    const cutoff = Date.now() - TOMBSTONE_TTL_MS;
+    const byUrl = new Map();
+    for (const t of [...local, ...remote]) {
+        const existing = byUrl.get(t.url);
+        if (!existing || t.removedAt > existing.removedAt)
+            byUrl.set(t.url, t);
+    }
+    return [...byUrl.values()].filter((t) => {
+        const ts = new Date(t.removedAt).getTime();
+        return !Number.isFinite(ts) || ts >= cutoff;
+    });
+}
+/**
+ * Drop merged items that a tombstone deleted, unless the item was re-added
+ * after the deletion (item timestamp newer than the tombstone) (#117).
+ */
+function applyTombstones(items, tombstones, urlOf, touchedAtOf) {
+    if (tombstones.length === 0)
+        return items;
+    const byUrl = new Map(tombstones.map((t) => [t.url, t.removedAt]));
+    return items.filter((item) => {
+        const removedAt = byUrl.get(urlOf(item));
+        if (removedAt === undefined)
+            return true;
+        // Keep only if re-added strictly after the deletion
+        return touchedAtOf(item) > removedAt;
+    });
+}
 export function mergeStates(local, remote) {
+    const tombstones = mergeTombstones(local.tombstones ?? [], remote.tombstones ?? []);
+    const savedResults = applyTombstones(mergeSavedResults(local.savedResults ?? [], remote.savedResults ?? []), tombstones, (r) => r.issueUrl, (r) => r.lastSeenAt);
+    const skippedIssues = applyTombstones(mergeSkippedIssues(local.skippedIssues ?? [], remote.skippedIssues ?? []), tombstones, (s) => s.url, (s) => s.skippedAt);
+    // A skipped URL must never linger in saved results (skipIssue's own
+    // invariant). Enforce it after the merge so a remote copy can't resurrect
+    // a now-skipped result into the saved list (#117).
+    const skippedUrls = new Set(skippedIssues.map((s) => s.url));
+    const savedResultsFinal = savedResults.filter((r) => !skippedUrls.has(r.issueUrl));
+    // Preferences: keep the side with the fresher preferencesUpdatedAt instead
+    // of always taking remote, which silently reverted a local edit (#117).
+    const localPrefsTs = local.preferencesUpdatedAt;
+    const remotePrefsTs = remote.preferencesUpdatedAt;
+    const localPrefsWin = localPrefsTs !== undefined &&
+        (remotePrefsTs === undefined || localPrefsTs > remotePrefsTs);
+    const preferences = localPrefsWin ? local.preferences : remote.preferences;
+    const preferencesUpdatedAt = pickFresherTimestamp(localPrefsTs, remotePrefsTs);
     return {
+        ...local,
+        ...remote,
         version: 1,
-        preferences: remote.preferences,
+        preferences,
+        preferencesUpdatedAt,
+        tombstones,
         repoScores: mergeRepoScores(local.repoScores, remote.repoScores),
         starredRepos: mergeStarredRepos(local, remote),
         starredReposLastFetched: pickFresherTimestamp(local.starredReposLastFetched, remote.starredReposLastFetched),
         mergedPRs: unionByUrl(local.mergedPRs, remote.mergedPRs),
         closedPRs: unionByUrl(local.closedPRs, remote.closedPRs),
         openPRs: unionByUrl(local.openPRs ?? [], remote.openPRs ?? []),
-        savedResults: mergeSavedResults(local.savedResults ?? [], remote.savedResults ?? []),
-        skippedIssues: mergeSkippedIssues(local.skippedIssues ?? [], remote.skippedIssues ?? []),
+        savedResults: savedResultsFinal,
+        skippedIssues,
         lastSearchAt: pickFresherTimestamp(local.lastSearchAt, remote.lastSearchAt),
         lastRunAt: pickFresherTimestamp(local.lastRunAt, remote.lastRunAt) ??
             new Date().toISOString(),

package/dist/core/http-cache.d.ts

@@ -9,8 +9,25 @@
  * for the same endpoint (e.g., star counts for two PRs in the same repo)
  * share a single HTTP round-trip.
  */
+/**
+ * Schema version for cache entries whose body is an oss-scout-defined shape
+ * (vetting results, search payloads, policy scans, merged-PR counts) rather
+ * than a raw GitHub API response. These are deserialized with an unchecked
+ * cast, so a shape change between releases would otherwise let a new build read
+ * a stale-shaped entry. Bump this whenever one of those cached shapes changes:
+ * old entries then miss the version-prefixed key and are refetched instead of
+ * misread (#158). Raw ETag-keyed GitHub responses are not versioned — their
+ * shape is owned by GitHub, not us.
+ */
+export declare const CACHE_SCHEMA_VERSION = "v1";
+/**
+ * Prefix a synthetic (non-URL) cache key with the schema version so a shape
+ * change invalidates old entries. Use for every key whose body is read back
+ * with an unchecked cast.
+ */
+export declare function versionedCacheKey(key: string): string;
 /** Shape of a single cache entry on disk. */
-interface CacheEntry {
+export interface CacheEntry {
     etag: string;
     url: string;
     body: unknown;
@@ -38,6 +55,12 @@ export declare class HttpCache {
      * (e.g., caching aggregated results from paginated API calls).
      */
     getIfFresh(key: string, maxAgeMs: number): unknown | null;
+    /**
+     * Like {@link getIfFresh}, but returns the whole entry so callers can
+     * distinguish "no fresh entry" (null) from a legitimately cached falsy
+     * body (`0`, `""`, `false`, `null`).
+     */
+    getEntryIfFresh(key: string, maxAgeMs: number): CacheEntry | null;
     /**
      * Look up a cached response. Returns `null` if no cache entry exists.
      */
@@ -91,6 +114,14 @@ export declare function getHttpCache(): HttpCache;
  *    cached body without consuming a rate-limit point.
  * 3. On a fresh 200, caches the ETag + body for next time.
  */
+/**
+ * Share one in-flight computation per key: concurrent callers for the same
+ * key await the same promise instead of paying duplicate API calls (#124).
+ * The check-then-register pair runs without an intervening await, so two
+ * concurrent callers cannot both miss. Rejections propagate to every waiter
+ * and are never cached.
+ */
+export declare function withInflightDedup<T>(cache: HttpCache, key: string, fn: () => Promise<T>): Promise<T>;
 export declare function cachedRequest<T>(cache: HttpCache, url: string, fetcher: (headers: Record<string, string>) => Promise<{
     data: T;
     headers?: Record<string, string>;
@@ -105,4 +136,3 @@ export declare function cachedRequest<T>(cache: HttpCache, url: string, fetcher:
  * (e.g. search queries, project health checks).
  */
 export declare function cachedTimeBased<T>(cache: HttpCache, key: string, maxAgeMs: number, fetcher: () => Promise<T>): Promise<T>;
-export {};