@bbradar/mcp 0.2.3 → 0.2.5

package/dist/server.js

@@ -6,7 +6,7 @@ import { NumericCursorStore } from "./cursorStore.js";
 import { stableStringify, stripUndefined } from "./json.js";
 import { FixedWindowRateLimiter } from "./rateLimit.js";
 import { readArray, readBoolean, readNumber, readObject, readString, sanitizeJson, sanitizeChange, sanitizeProgram, sanitizeRepositoryChange, sanitizeTarget, sanitizeTargetsForExport } from "./sanitize.js";
-const SERVER_VERSION = "0.2.3";
+const SERVER_VERSION = "0.2.5";
 const MAX_PROGRAMS_PER_SEARCH = 100;
 const MAX_TARGET_EXPORT = 500;
 const MAX_RECENT_CHANGES = 100;
@@ -27,6 +27,7 @@ const MAX_HUNT_TARGETS_PER_RESULT = 10;
 const MAX_BULK_PROGRAM_RESOURCE_LINKS = 5;
 const DEFAULT_RESOLVE_UPSTREAM_REQUEST_BUDGET = 12;
 const MAX_ACCEPTED_NUMERIC_LIMIT = 1_000;
+const MAX_UPSTREAM_PAGE = 500;
 const PROGRAM_COLLECTION_CONCURRENCY = 4;
 const TARGET_SAMPLE_CONCURRENCY = 3;
 const DEFAULT_FILTER_DISCOVERY_PAGES = 2;
@@ -66,6 +67,7 @@ const CORE_TOOL_NAMES = new Set([
     "export_targets"
 ]);
 const TOOL_ENDPOINT_REQUIREMENTS = {
+    search_targets: "target_search",
     get_repository_changes: "repository_changes",
     find_repository_hunt_targets: "repository_changes",
     export_targets: "target_export",
@@ -183,6 +185,8 @@ const vdpModeSchema = z.enum(["include", "exclude", "only_likely", "only_known_n
 const targetMatchModeSchema = z
     .enum(["smart", "contains", "exact", "suffix", "wildcard"])
     .describe("How to match target_query. smart is forgiving for URLs, wildcards, target names, and partial words.");
+const apiTargetMatchModeSchema = z.enum(["contains", "exact", "suffix", "wildcard"]);
+const targetChangeTypeSchema = z.enum(["added", "readded", "updated", "removed"]);
 const programNameActionSchema = z.enum(["new_targets", "targets", "scope_delta", "brief", "target_breakdown"]);
 const guideTopicSchema = z.enum(["start", "program", "discovery", "freshness", "targets", "compare", "export", "filters"]).default("start");
 const readOnlyAnnotations = {
@@ -241,6 +245,15 @@ const targetQuerySchema = z
 })
     .describe("Target identifier, domain, URL, wildcard, app/package/repo name, or partial target text. URLs and wildcards are normalized automatically.");
 const isoDateTimeSchema = z.string().datetime({ offset: true });
+const stableSnapshotSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(1_024)
+    .refine((value) => !/[\u0000-\u001F\u007F]/.test(value), {
+    message: "Snapshot tokens cannot contain control characters."
+})
+    .describe("Optional stable-page token. Send 'start' on page 1, then reuse meta.snapshot with identical filters. Snapshot creation is consistency-first and can be slower; omit it for the fastest live result.");
 const pageSchema = z.number().int().min(1).default(1);
 const programsPageSizeSchema = z.number().int().min(1).max(MAX_PROGRAMS_PER_SEARCH).default(20);
 const recentChangesPageSizeSchema = z.number().int().min(1).max(MAX_RECENT_CHANGES).default(50);
@@ -436,6 +449,7 @@ export function createBbradarServer(client, config) {
     const feedCursorStore = new NumericCursorStore(config.cursorStatePath, MAX_IN_MEMORY_FEED_CURSORS);
     const maxProgramsPageSize = client.endpointNumber("programs", "max_page_size", MAX_PROGRAMS_PER_SEARCH);
     const maxProgramTargetsPageSize = client.endpointNumber("program_targets", "max_page_size", MAX_TARGETS_PER_PROGRAM);
+    const maxTargetSearchPageSize = client.endpointNumber("target_search", "max_page_size", MAX_TARGETS_PER_PROGRAM);
     const maxTargetChangesPageSize = client.endpointNumber("target_changes", "max_page_size", MAX_RECENT_CHANGES);
     const maxRepositoryChangesPageSize = client.endpointNumber("repository_changes", "max_page_size", MAX_RECENT_CHANGES);
     const maxTargetExport = client.endpointNumber("target_export", "max_targets", MAX_TARGET_EXPORT);
@@ -444,14 +458,16 @@ export function createBbradarServer(client, config) {
     const recentChangesPageSizeSchema = z.number().int().min(1).max(maxTargetChangesPageSize).default(Math.min(50, maxTargetChangesPageSize));
     const repositoryChangesPageSizeSchema = z.number().int().min(1).max(maxRepositoryChangesPageSize).default(Math.min(50, maxRepositoryChangesPageSize));
     const acceptedTargetLimitSchema = z.number().int().min(1).max(maxProgramTargetsPageSize);
+    const targetSearchPageSizeSchema = z.number().int().min(1).max(maxTargetSearchPageSize).default(Math.min(50, maxTargetSearchPageSize));
     registerTool("search_programs", {
         title: "Search BBRadar Programs",
-        description: `Search or list active platform and Self-Hosted programs. page_size max ${MAX_PROGRAMS_PER_SEARCH}.`,
+        description: `Search or list active and confirmed paused platform programs plus active Self-Hosted programs. page_size max ${maxProgramsPageSize}. Stable snapshots are opt-in because creating one can be slower than live indexed pagination.`,
         inputSchema: {
             search: searchTextSchema.optional().describe("Server-side program name, handle, platform, policy-host, or target search."),
             platforms: platformListSchema(),
             tags: tagListSchema(),
             updated_since: isoDateTimeSchema.optional().describe("ISO datetime."),
+            snapshot: stableSnapshotSchema.optional(),
             vdp_mode: vdpModeSchema.default("exclude").describe("VDP/no-bounty filter mode."),
             page: pageSchema,
             page_size: programsPageSizeSchema
@@ -460,6 +476,7 @@ export function createBbradarServer(client, config) {
         annotations: readOnlyAnnotations
     }, (args) => runTool("search_programs", config, rateLimiter, async () => {
         const { vdp_mode, ...filters } = args;
+        assertStableSnapshotSupported(client, "programs", filters.snapshot);
         const api = await client.listPrograms(toQuery(filters));
         const data = readObject(api.data);
         const programs = readArray(data?.programs)
@@ -471,6 +488,47 @@ export function createBbradarServer(client, config) {
             meta: sanitizeJson(data?.meta)
         });
     }));
+    registerTool("search_targets", {
+        title: "Search BBRadar Targets",
+        description: `Low-level reverse target search and current target-inventory paging. q may be omitted for inventory traversal. page_size max ${maxTargetSearchPageSize}. Stable snapshots are opt-in and intentionally not used by find_hunt_targets.`,
+        inputSchema: {
+            q: targetQuerySchema.optional(),
+            match_mode: apiTargetMatchModeSchema.default("contains"),
+            snapshot: stableSnapshotSchema.optional(),
+            platforms: platformListSchema(),
+            tags: tagListSchema(),
+            include_out_of_scope: z.boolean().default(false),
+            include_ineligible: z.boolean().default(false),
+            page: pageSchema,
+            page_size: targetSearchPageSizeSchema,
+            output_mode: targetListModeSchema.default("compact")
+        },
+        outputSchema: {
+            ...apiEnvelopeOutputShape(),
+            results: z.array(jsonRecordSchema()).optional(),
+            meta: jsonRecordSchema().optional(),
+            continuation: jsonRecordSchema().optional()
+        },
+        annotations: readOnlyAnnotations
+    }, (args) => runTool("search_targets", config, rateLimiter, async () => {
+        const { output_mode, ...filters } = args;
+        assertStableSnapshotSupported(client, "target_search", filters.snapshot);
+        const api = await client.searchTargets(toQuery(filters));
+        const data = readObject(api.data);
+        const results = readArray(data?.results).map((value) => {
+            const row = readObject(value) ?? {};
+            const program = sanitizeProgram(row.program, config.webBaseUrl);
+            const target = sanitizeTarget(row.target);
+            return stripUndefined({
+                program: formatProgram(program, output_mode === "full" ? "full" : "compact"),
+                target: output_mode === "full" ? target : compactTarget(target)
+            });
+        });
+        return applyCollectionContinuation(withApiMetadata(api, {
+            results,
+            meta: sanitizeJson(data?.meta)
+        }), "results", "target search results", continuationStore, config);
+    }));
     registerTool("get_program", {
         title: "Get BBRadar Program",
         description: "Get one program by platform:handle program_id, handle, or human program name. Names are resolved automatically when unambiguous.",
@@ -629,7 +687,8 @@ export function createBbradarServer(client, config) {
         title: "Get Recent Target Changes",
         description: `List recent target changes. page_size max ${MAX_RECENT_CHANGES}.`,
         inputSchema: {
-            change_type: z.enum(["added", "updated", "removed"]).optional(),
+            change_type: targetChangeTypeSchema.optional(),
+            snapshot: stableSnapshotSchema.optional(),
             after_id: z.number().int().min(0).optional().describe("Incremental cursor; returns changes after this id in ascending order."),
             resume_cursor: z.boolean().default(false).describe("Resume the in-memory cursor for this exact normalized filter set. Seed it once with after_id."),
             max_cursor_pages: z.number().int().min(1).max(10).default(2),
@@ -658,16 +717,24 @@ export function createBbradarServer(client, config) {
         annotations: readOnlyAnnotations
     }, (args) => runTool("get_recent_changes", config, rateLimiter, async () => {
         const { output_mode, resume_cursor, max_cursor_pages, cursor_time_budget_ms, ...filters } = args;
+        assertStableSnapshotSupported(client, "target_changes", filters.snapshot);
         const cursor = resolveFeedCursor(feedCursorStore, "target_changes", filters, resume_cursor);
-        const { min_target_score, target_opportunity_label, competition_risk, ...upstreamFilters } = filters;
-        const collected = await collectCursorFeedPages(feedCursorStore, cursor, max_cursor_pages, cursor_time_budget_ms, (afterId) => client.getRecentChanges(toQuery({
+        const { min_target_score, target_opportunity_label, competition_risk, snapshot, ...upstreamFilters } = filters;
+        const collected = await collectCursorFeedPages(feedCursorStore, cursor, max_cursor_pages, cursor_time_budget_ms, snapshot, (afterId, recoveryProbe, activeSnapshot) => client.getRecentChanges(toQuery({
             ...upstreamFilters,
             minTargetScore: min_target_score,
             targetOpportunityLabel: target_opportunity_label,
             competitionRisk: competition_risk,
+            snapshot: activeSnapshot,
             after_id: afterId,
             page: afterId === undefined ? filters.page : 1
-        })));
+        }), recoveryProbe ? { cache: false, coalesce: false } : {}), (startPage, recoveryProbe) => refreshInventoryBaseline((page, pageProbe) => client.searchTargets(toQuery({
+            q: upstreamFilters.search,
+            platforms: upstreamFilters.platforms,
+            tags: upstreamFilters.tags,
+            page,
+            page_size: client.endpointNumber("target_search", "max_page_size", 100)
+        }), pageProbe ? { cache: false, coalesce: false } : {}), "results", max_cursor_pages, cursor_time_budget_ms, startPage, recoveryProbe));
         const api = collected.lastApi;
         const data = collected.lastData;
         const sanitizedMeta = readObject(sanitizeJson(data?.meta));
@@ -682,7 +749,9 @@ export function createBbradarServer(client, config) {
                 pages_fetched: collected.pagesFetched,
                 returned_across_pages: changes.length,
                 cursor_page_budget_exhausted: collected.pageBudgetExhausted,
-                cursor_time_budget_exhausted: collected.timeBudgetExhausted
+                cursor_time_budget_exhausted: collected.timeBudgetExhausted,
+                history_gap: collected.gapRecovery !== undefined,
+                inventory_baseline: collected.gapRecovery
             }),
             facets: sanitizeJson(data?.facets),
             cursor: collected.cursor,
@@ -694,6 +763,7 @@ export function createBbradarServer(client, config) {
         description: "Read-only repository push/change feed for direct inspection or polling. Defaults to lightweight program summaries; use after_id for efficient incremental polling. Use find_repository_hunt_targets instead when reward or target-quality ranking is also required.",
         inputSchema: {
             after_id: z.number().int().min(0).optional().describe("Incremental cursor; returns events after this id in ascending order."),
+            snapshot: stableSnapshotSchema.optional(),
             resume_cursor: z.boolean().default(false).describe("Resume the in-memory cursor for this exact normalized filter set. Seed it once with after_id."),
             max_cursor_pages: z.number().int().min(1).max(10).default(2),
             cursor_time_budget_ms: z.number().int().min(100).max(10_000).default(3_000),
@@ -724,12 +794,20 @@ export function createBbradarServer(client, config) {
             throw new Error("The negotiated BBRadar API contract does not expose repository changes.");
         }
         const { output_mode, resume_cursor, max_cursor_pages, cursor_time_budget_ms, ...filters } = args;
+        assertStableSnapshotSupported(client, "repository_changes", filters.snapshot);
         const cursor = resolveFeedCursor(feedCursorStore, "repository_changes", filters, resume_cursor);
-        const collected = await collectCursorFeedPages(feedCursorStore, cursor, max_cursor_pages, cursor_time_budget_ms, (afterId) => client.getRepositoryChanges(toQuery({
-            ...filters,
+        const { snapshot, ...upstreamFilters } = filters;
+        const collected = await collectCursorFeedPages(feedCursorStore, cursor, max_cursor_pages, cursor_time_budget_ms, snapshot, (afterId, recoveryProbe, activeSnapshot) => client.getRepositoryChanges(toQuery({
+            ...upstreamFilters,
+            snapshot: activeSnapshot,
             after_id: afterId,
             page: afterId === undefined ? filters.page : 1
-        })));
+        }), recoveryProbe ? { cache: false, coalesce: false } : {}), (startPage, recoveryProbe) => refreshInventoryBaseline((page, pageProbe) => client.getRepositoryChanges(toQuery({
+            ...upstreamFilters,
+            after_id: undefined,
+            page,
+            page_size: client.endpointNumber("repository_changes", "max_page_size", 100)
+        }), pageProbe ? { cache: false, coalesce: false } : {}), "results", max_cursor_pages, cursor_time_budget_ms, startPage, recoveryProbe));
         const api = collected.lastApi;
         const data = collected.lastData;
         return applyCollectionContinuation(withApiMetadata(api, {
@@ -740,7 +818,9 @@ export function createBbradarServer(client, config) {
                 pages_fetched: collected.pagesFetched,
                 returned_across_pages: collected.results.length,
                 cursor_page_budget_exhausted: collected.pageBudgetExhausted,
-                cursor_time_budget_exhausted: collected.timeBudgetExhausted
+                cursor_time_budget_exhausted: collected.timeBudgetExhausted,
+                history_gap: collected.gapRecovery !== undefined,
+                inventory_baseline: collected.gapRecovery
             }),
             facets: sanitizeJson(data?.facets),
             available_facets: sanitizeJson(data?.available_facets),
@@ -750,7 +830,7 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("find_hunt_targets", {
         title: "Find Best Hunt Targets",
-        description: "Preferred one-call path for requests combining good rewards, broad Web2/Web3 scope, target quality, competition, and recently added targets. Returns a final ranked shortlist with exact bounded target samples and recent additions; do not fan out into repeated find_programs/get_program_targets calls. Use find_repository_hunt_targets instead only when Git or repository activity is explicitly requested.",
+        description: "Preferred one-call path for requests combining good rewards, broad Web2/Web3 scope, target quality, competition, and recently added targets. Returns a final ranked shortlist with exact bounded target samples and recent additions; do not fan out into repeated find_programs/get_program_targets calls. Self-Hosted is supported through current inventory and automatically skips its unavailable change feed. Use find_repository_hunt_targets instead only when Git or repository activity is explicitly requested.",
         inputSchema: {
             platforms: platformListSchema(),
             exclude_platforms: stringListSchema("Platforms to exclude from the final shortlist."),
@@ -795,7 +875,7 @@ export function createBbradarServer(client, config) {
     }, (args) => runTool("find_hunt_targets", config, rateLimiter, async () => findHuntTargets(client, config, args)));
     registerTool("find_repository_hunt_targets", {
         title: "Find Repository-Aware Hunt Targets",
-        description: "Fast one-call path for requests that combine recent repository activity with program rewards and target quality. Fetches program rankings and repository changes in parallel, joins them locally, and works with arbitrary platforms, Web2/Web3 modes, reward thresholds, target types, languages, and freshness criteria.",
+        description: "Fast one-call path for requests that combine recent repository activity with program rewards and target quality. Fetches program rankings and repository changes in parallel, joins them locally, and works with arbitrary supported platform catalogs, Web2/Web3 modes, reward thresholds, target types, languages, and freshness criteria. Self-Hosted has no repository stream and is rejected without upstream work.",
         inputSchema: {
             platforms: platformListSchema(),
             exclude_platforms: stringListSchema("Platforms to exclude from final matches."),
@@ -916,7 +996,7 @@ export function createBbradarServer(client, config) {
         inputSchema: {
             program_id: programIdentifierSchema,
             since: isoDateTimeSchema.optional(),
-            change_type: z.enum(["added", "updated", "removed"]).optional(),
+            change_type: targetChangeTypeSchema.optional(),
             target_type: filterValueSchema().optional(),
             language_tags: languageTagListSchema(),
             include_removed: z.boolean().default(true),
@@ -940,7 +1020,7 @@ export function createBbradarServer(client, config) {
         title: "Get Recent Target Activity",
         description: "Recent target changes grouped by program.",
         inputSchema: {
-            change_type: z.enum(["added", "updated", "removed"]).optional(),
+            change_type: targetChangeTypeSchema.optional(),
             target_type: filterValueSchema().optional(),
             include_removed: z.boolean().default(true),
             include_out_of_scope: z.boolean().default(false),
@@ -1426,7 +1506,7 @@ export function createBbradarServer(client, config) {
         description: "Recent changes by target type grouped by program.",
         inputSchema: {
             target_type: filterValueSchema(),
-            change_type: z.enum(["added", "updated", "removed"]).default("added"),
+            change_type: targetChangeTypeSchema.default("added"),
             include_removed: z.boolean().default(false),
             include_out_of_scope: z.boolean().default(false),
             include_ineligible: z.boolean().default(false),
@@ -4407,21 +4487,50 @@ function latestAddedProgramMatches(change, input, platformFilters) {
     return true;
 }
 async function getProgramTargetsPayload(client, input, programId) {
-    const api = await client.getProgramTargets(programId, {
-        search: input.search,
-        target_type: input.target_type,
-        eligibility: input.include_ineligible ? "all" : "eligible",
-        minTargetScore: input.min_target_score,
-        targetOpportunityLabel: input.target_opportunity_label,
-        competitionRisk: input.competition_risk,
-        page: 1,
-        page_size: client.endpointNumber("program_targets", "max_page_size", MAX_TARGETS_PER_PROGRAM)
-    });
-    const data = readObject(api.data);
-    const upstreamMeta = readObject(data?.meta);
-    const rawTargets = readArray(data?.targets);
-    const sanitizedTargets = rawTargets.map(sanitizeTarget).filter((target) => targetHasAllowedScope(target, input));
-    const targets = sanitizedTargets.slice(input.offset, input.offset + input.limit);
+    const pageSize = client.endpointNumber("program_targets", "max_page_size", MAX_TARGETS_PER_PROGRAM);
+    // `eligibility=eligible` is an API-level in-scope bounty-eligibility filter,
+    // so the common eligible-only path needs no second local scope pass.
+    const directOffsetPaging = !input.include_ineligible || (!input.strict_scope_filter && input.include_out_of_scope);
+    const collected = [];
+    let matchedSeen = directOffsetPaging ? Math.floor(input.offset / pageSize) * pageSize : 0;
+    let page = directOffsetPaging ? Math.floor(input.offset / pageSize) + 1 : 1;
+    const firstPage = page;
+    let api;
+    let upstreamMeta;
+    let upstreamHasMore = false;
+    do {
+        api = await client.getProgramTargets(programId, {
+            search: input.search,
+            target_type: input.target_type,
+            eligibility: input.include_ineligible ? "all" : "eligible",
+            minTargetScore: input.min_target_score,
+            targetOpportunityLabel: input.target_opportunity_label,
+            competitionRisk: input.competition_risk,
+            page,
+            page_size: pageSize
+        });
+        const data = readObject(api.data);
+        upstreamMeta = readObject(data?.meta);
+        for (const target of readArray(data?.targets).map(sanitizeTarget)) {
+            if (!targetHasAllowedScope(target, input))
+                continue;
+            if (matchedSeen >= input.offset && collected.length < input.limit)
+                collected.push(target);
+            matchedSeen += 1;
+        }
+        upstreamHasMore = readBoolean(upstreamMeta?.has_more) === true;
+        const totalPages = readNumber(upstreamMeta?.total_pages);
+        page += 1;
+        if (totalPages !== undefined && page > totalPages) {
+            upstreamHasMore = false;
+        }
+    } while (upstreamHasMore &&
+        page <= MAX_UPSTREAM_PAGE &&
+        collected.length < input.limit);
+    if (!api) {
+        throw new Error("No program target response was collected.");
+    }
+    const targets = collected;
     return withApiMetadata(api, {
         program_id: programId,
         targets: formatTargetList(targets, input.output_mode),
@@ -4429,12 +4538,16 @@ async function getProgramTargetsPayload(client, input, programId) {
             offset: input.offset,
             limit: input.limit,
             output_mode: input.output_mode,
-            total_active_targets: readNumber(upstreamMeta?.total) ?? rawTargets.length,
-            total_after_filters: sanitizedTargets.length,
+            total_active_targets: readNumber(upstreamMeta?.total) ?? matchedSeen,
+            total_after_filters: upstreamHasMore ? undefined : matchedSeen,
             returned: targets.length,
-            has_more: input.offset + input.limit < sanitizedTargets.length || readBoolean(upstreamMeta?.has_more) === true,
-            upstream_has_more: readBoolean(upstreamMeta?.has_more),
-            possibly_incomplete: readBoolean(upstreamMeta?.has_more) === true,
+            has_more: upstreamHasMore || matchedSeen > input.offset + targets.length,
+            upstream_has_more: upstreamHasMore,
+            possibly_incomplete: upstreamHasMore,
+            upstream_pages_fetched: page - firstPage,
+            upstream_start_page: firstPage,
+            direct_offset_paging: directOffsetPaging,
+            upstream_page_limit_reached: upstreamHasMore && page > MAX_UPSTREAM_PAGE,
             data_capabilities: readObject(upstreamMeta?.data_capabilities),
             target_source: "program_targets"
         }
@@ -5789,6 +5902,8 @@ function compactProgram(program) {
         name: stringField(program, "name"),
         platform: stringField(program, "platform"),
         catalog: stringField(program, "catalog"),
+        program_status: stringField(program, "program_status"),
+        is_active: readBoolean(program.is_active),
         program_type: stringField(program, "program_type"),
         platform_url: stringField(program, "platform_url"),
         bbradar_url: stringField(program, "bbradar_url"),
@@ -5807,6 +5922,9 @@ function compactProgram(program) {
         last_updated: stringField(program, "last_updated"),
         targets_updated_at: stringField(program, "targets_updated_at"),
         scope_summary: readObject(program.scope_summary),
+        match_qualities: Array.isArray(program.match_qualities)
+            ? readStringArrayField(program, "match_qualities")
+            : undefined,
         resource_links: readObject(program.resource_links)
     });
 }
@@ -5867,6 +5985,7 @@ function formatRepositoryChange(change, mode) {
             })
             : undefined,
         changes_url: stringField(change, "changes_url"),
+        comparison: sanitizeJson(change.comparison),
         programs: readArray(change.programs).map((program) => formatProgram(readObject(program) ?? {}, "compact")),
         targets: Array.isArray(change.targets)
             ? change.targets.map((target) => compactTarget(readObject(target) ?? {}))
@@ -6351,7 +6470,11 @@ function clampLimit(name, value, max, warnings) {
 async function findHuntTargets(client, config, input) {
     const warnings = [];
     const errors = [];
-    const recentChangesEnabled = input.include_recent_changes && client.supportsEndpoint("target_changes");
+    const selfHostedOnly = isSelfHostedOnlyPlatformSelection(input.platforms);
+    const targetChangesEndpointSupported = client.supportsEndpoint("target_changes");
+    const recentChangesEnabled = input.include_recent_changes &&
+        !selfHostedOnly &&
+        targetChangesEndpointSupported;
     const desiredRecentChangeQueries = recentChangesEnabled ? huntRecentChangeQueries(input) : [];
     const recentChangeQueries = desiredRecentChangeQueries.slice(0, Math.max(0, input.upstream_request_budget - 2));
     const recentRequestReserve = recentChangeQueries.length;
@@ -6399,7 +6522,10 @@ async function findHuntTargets(client, config, input) {
         output_mode: "compact",
         upstream_request_budget: programRequestBudget
     };
-    if (input.include_recent_changes && !recentChangesEnabled) {
+    if (input.include_recent_changes && selfHostedOnly) {
+        warnings.push("Self-Hosted does not expose target-change history; recent target evidence was derived only from current target-inventory timestamps.");
+    }
+    else if (input.include_recent_changes && !recentChangesEnabled) {
         warnings.push("The negotiated API contract does not expose target changes; ranked current programs without recent-change enrichment.");
     }
     else if (recentChangeQueries.length < desiredRecentChangeQueries.length) {
@@ -6502,6 +6628,7 @@ async function findHuntTargets(client, config, input) {
             exact_target_programs_sampled: targetResult.targetsByProgram.size,
             recent_changes_scanned: recentResult.changes.length,
             recent_programs_matched: recentByProgram.size,
+            recent_change_catalog_supported: !selfHostedOnly && targetChangesEndpointSupported,
             model_round_trips_expected: 1,
             parallel_recent_change_fetch: recentChangeQueries.length > 0,
             bulk_resource_links_suppressed: true,
@@ -6747,7 +6874,9 @@ function buildHuntTargetMatch(entry, targetsByProgram, recentByProgram, input) {
         (readNumber(rankFactors.target_surface_score) ?? 0) * 0.25);
     const freshnessScore = huntFreshnessScore(latestRecentAt, recentTargets.length, readNumber(rankFactors.added_7d));
     const publicReports = readNumber(rankFactors.public_report_count);
-    const competitionScore = publicReports === undefined ? 50 : Math.max(0, 100 - Math.min(100, publicReports / 10));
+    // Missing report evidence is unknown, not low competition. Keep the
+    // internal ranking conservative and do not expose a made-up numeric signal.
+    const competitionScore = publicReports === undefined ? 20 : Math.max(0, 100 - Math.min(100, publicReports / 10));
     const bestTargetScore = Math.max(0, ...targetSamples.map((target) => readNumber(target.target_opportunity_score) ?? 0));
     const baseHuntScore = readNumber(rankFactors.hunt_value_score) ?? 0;
     const compositeScore = huntCompositeScore(input.ranking_mode, baseHuntScore, rewardScore, scopeScore, freshnessScore, competitionScore, bestTargetScore);
@@ -6775,7 +6904,8 @@ function buildHuntTargetMatch(entry, targetsByProgram, recentByProgram, input) {
                 reward_score: roundScore(rewardScore),
                 scope_score: roundScore(scopeScore),
                 freshness_score: roundScore(freshnessScore),
-                competition_score: roundScore(competitionScore),
+                competition_score: publicReports === undefined ? undefined : roundScore(competitionScore),
+                competition_signal: publicReports === undefined ? "unknown" : "public_report_count",
                 best_sample_target_score: bestTargetScore > 0 ? bestTargetScore : undefined,
                 recent_added_targets_in_window: recentTargets.length,
                 latest_added_target_at: latestRecentAt,
@@ -6880,11 +7010,52 @@ function compareHuntTargetMatches(left, right, mode) {
 }
 async function findRepositoryHuntTargets(client, config, input) {
     const warnings = [];
+    const repositoryPlatforms = input.platforms.filter((platform) => !isSelfHostedPlatform(platform));
+    const selfHostedRequested = repositoryPlatforms.length !== input.platforms.length;
+    if (input.platforms.length > 0 && repositoryPlatforms.length === 0) {
+        return {
+            request_id: randomUUID(),
+            fetched_at: new Date().toISOString(),
+            source_requests: [],
+            warnings: [
+                "Self-Hosted does not expose repository-change events or target intelligence, so repository-aware hunting is unavailable for this catalog. Use find_hunt_targets for current Self-Hosted program and target inventory."
+            ],
+            filters: {
+                platforms: input.platforms,
+                surface_mode: input.surface_mode,
+                ranking_mode: input.ranking_mode,
+                output_mode: input.output_mode
+            },
+            upstream_budget: {
+                initial: input.upstream_request_budget,
+                used: 0,
+                remaining: input.upstream_request_budget
+            },
+            ranking_scope: {
+                mode: "unsupported_catalog",
+                possibly_incomplete: false
+            },
+            programs: [],
+            matches: [],
+            meta: {
+                returned: 0,
+                matched_programs: 0,
+                program_candidates: 0,
+                repository_events_scanned: 0,
+                qualifying_targets_before_result_limit: 0,
+                repository_request_attempts: 0,
+                parallel_source_fetch: false
+            }
+        };
+    }
+    if (selfHostedRequested) {
+        warnings.push("Self-Hosted was excluded from repository-aware matching because that catalog has no repository-change stream; other requested platforms were processed normally.");
+    }
     const repositoryRequestReserve = input.upstream_request_budget >= 3 ? 2 : 1;
     const programRequestBudget = Math.max(1, input.upstream_request_budget - repositoryRequestReserve);
     const programInput = {
-        platforms: input.platforms,
-        exclude_platforms: input.exclude_platforms,
+        platforms: repositoryPlatforms,
+        exclude_platforms: uniqueStrings([...input.exclude_platforms, "Self-Hosted"]),
         tags: input.tags,
         scope_tags: input.scope_tags,
         target_types: input.target_types,
@@ -6926,7 +7097,7 @@ async function findRepositoryHuntTargets(client, config, input) {
     };
     const [programPayload, repository] = await Promise.all([
         findPrograms(client, config, programInput),
-        fetchRepositoryHuntPage(client, input, warnings, repositoryRequestReserve)
+        fetchRepositoryHuntPage(client, { ...input, platforms: repositoryPlatforms }, warnings, repositoryRequestReserve)
     ]);
     const candidatePrograms = readArray(programPayload.programs)
         .map(readObject)
@@ -7737,6 +7908,10 @@ function toProgramCandidate(rawProgram, webBaseUrl) {
     return candidate;
 }
 function programCandidateMatches(candidate, filters) {
+    const programStatus = normalizeTag(stringField(candidate.program, "program_status") ?? "");
+    if (readBoolean(candidate.program.is_active) === false || programStatus === "paused") {
+        return false;
+    }
     if (filters.platforms.length > 0 && !filters.platforms.map(normalizeTag).includes(normalizeTag(stringField(candidate.program, "platform") ?? ""))) {
         return false;
     }
@@ -8062,6 +8237,12 @@ function uniqueStrings(values) {
 function normalizeTag(value) {
     return value.trim().toLowerCase();
 }
+function isSelfHostedPlatform(value) {
+    return normalizeTag(value).replace(/[\s_]+/g, "-") === "self-hosted";
+}
+function isSelfHostedOnlyPlatformSelection(platforms) {
+    return platforms.length > 0 && platforms.every(isSelfHostedPlatform);
+}
 function tokenSet(value) {
     return new Set(value.split(/[^a-z0-9]+/).filter((token) => token.length >= 2));
 }
@@ -8172,7 +8353,7 @@ function advanceFeedCursor(store, cursor, rawMeta) {
         stored_in_memory: true
     };
 }
-async function collectCursorFeedPages(store, initialCursor, maxPages, timeBudgetMs, fetchPage) {
+async function collectCursorFeedPages(store, initialCursor, maxPages, timeBudgetMs, initialSnapshot, fetchPage, refreshInventory) {
     const startedAt = Date.now();
     const results = [];
     const sourceRequests = [];
@@ -8184,9 +8365,110 @@ async function collectCursorFeedPages(store, initialCursor, maxPages, timeBudget
     let hasMore = false;
     let pageBudgetExhausted = false;
     let timeBudgetExhausted = false;
+    let gapRecovery;
+    let activeSnapshot = initialSnapshot;
     do {
-        const api = await fetchPage(currentCursor.afterId);
+        let api;
+        try {
+            api = await fetchPage(currentCursor.afterId, undefined, activeSnapshot);
+            feedRecoveryProgress.get(store)?.delete(currentCursor.key);
+        }
+        catch (error) {
+            if (!(error instanceof BBRadarApiError) ||
+                error.status !== 410 ||
+                currentCursor.afterId === undefined ||
+                activeSnapshot !== undefined ||
+                !refreshInventory) {
+                throw error;
+            }
+            const recoveryNonce = `${Date.now()}-${currentCursor.afterId}`;
+            const markerApi = await fetchPage(undefined, `${recoveryNonce}-marker`);
+            const markerData = readObject(markerApi.data);
+            const markerAfterId = feedBaselineAfterId(markerData);
+            let progress = feedRecoveryProgress.get(store)?.get(currentCursor.key);
+            let restartedForDrift = false;
+            if (progress && (progress.previousAfterId !== currentCursor.afterId ||
+                progress.baselineAfterId !== markerAfterId)) {
+                feedRecoveryProgress.get(store)?.delete(currentCursor.key);
+                progress = undefined;
+                restartedForDrift = true;
+            }
+            const beforeAfterId = progress?.baselineAfterId ?? markerAfterId;
+            const startPage = progress?.nextPage ?? 1;
+            const inventoryPart = await refreshInventory(startPage, `${recoveryNonce}-inventory`);
+            const inventory = {
+                ...inventoryPart,
+                rows_observed: (progress?.rowsObserved ?? 0) + (readNumber(inventoryPart.rows_observed) ?? 0),
+                pages_fetched: (progress?.pagesFetched ?? 0) + (readNumber(inventoryPart.pages_fetched) ?? 0),
+                resumed_from_page: startPage,
+                restarted_for_feed_drift: restartedForDrift
+            };
+            const inventoryComplete = readBoolean(inventory.complete) === true;
+            const endpointPageLimitReached = readBoolean(inventory.endpoint_page_limit_reached) === true;
+            const afterApi = inventoryComplete ? await fetchPage(undefined, `${recoveryNonce}-after`) : markerApi;
+            const afterData = readObject(afterApi.data);
+            const afterAfterId = feedBaselineAfterId(afterData);
+            const baselineStable = inventoryComplete && beforeAfterId !== undefined && beforeAfterId === afterAfterId;
+            const nextAfterId = baselineStable ? beforeAfterId : currentCursor.afterId;
+            if (baselineStable) {
+                store.set(currentCursor.key, nextAfterId);
+                feedRecoveryProgress.get(store)?.delete(currentCursor.key);
+            }
+            else if (!inventoryComplete && !endpointPageLimitReached && beforeAfterId !== undefined) {
+                // Persist only the unchanged expired bookmark so resume_cursor can
+                // continue recovery without treating partial inventory as a baseline.
+                store.set(currentCursor.key, currentCursor.afterId);
+                setRecoveryCheckpoint(store, currentCursor.key, {
+                    previousAfterId: currentCursor.afterId,
+                    baselineAfterId: beforeAfterId,
+                    nextPage: readNumber(inventoryPart.next_page) ?? startPage,
+                    rowsObserved: readNumber(inventory.rows_observed) ?? 0,
+                    pagesFetched: readNumber(inventory.pages_fetched) ?? 0
+                });
+            }
+            else {
+                // A failed first explicit recovery must remain resumable even when no
+                // safe inventory checkpoint can be retained.
+                store.set(currentCursor.key, currentCursor.afterId);
+                feedRecoveryProgress.get(store)?.delete(currentCursor.key);
+            }
+            gapRecovery = {
+                historical_gap: true,
+                current_inventory_refreshed: inventoryComplete,
+                recovery_complete: baselineStable,
+                retained_previous_cursor: !baselineStable,
+                incomplete_reason: !inventoryComplete
+                    ? endpointPageLimitReached ? "inventory_endpoint_page_limit_reached" : "inventory_page_or_time_budget_exhausted"
+                    : beforeAfterId === undefined
+                        ? "feed_baseline_unavailable"
+                        : beforeAfterId !== afterAfterId
+                            ? "feed_changed_during_inventory_refresh"
+                            : undefined,
+                inventory,
+                next_inventory_page: baselineStable ? undefined : readNumber(inventoryPart.next_page),
+                previous_after_id: currentCursor.afterId,
+                baseline_after_id: baselineStable ? nextAfterId : undefined,
+                baseline_events_emitted: 0,
+                limitation: "Changes retired before recovery cannot be reconstructed."
+            };
+            lastApi = afterApi;
+            lastData = afterData;
+            cursorPayload = {
+                endpoint: currentCursor.endpoint,
+                mode: baselineStable ? "recovered_baseline" : "recovery_incomplete",
+                used_after_id: currentCursor.afterId,
+                next_after_id: nextAfterId,
+                has_more: false,
+                stored_in_memory: true
+            };
+            pagesFetched += 1;
+            break;
+        }
         const data = readObject(api.data);
+        const returnedSnapshot = readString(readObject(data?.meta)?.snapshot);
+        if (activeSnapshot === "start" && returnedSnapshot) {
+            activeSnapshot = returnedSnapshot;
+        }
         const pageResults = readArray(data?.results);
         lastApi = api;
         lastData = data;
@@ -8229,12 +8511,61 @@ async function collectCursorFeedPages(store, initialCursor, maxPages, timeBudget
         pagesFetched,
         pageBudgetExhausted,
         timeBudgetExhausted,
-        sourceRequests
+        sourceRequests,
+        gapRecovery
+    };
+}
+const feedRecoveryProgress = new WeakMap();
+function recoveryProgressFor(store) {
+    let progress = feedRecoveryProgress.get(store);
+    if (!progress) {
+        progress = new Map();
+        feedRecoveryProgress.set(store, progress);
+    }
+    return progress;
+}
+function setRecoveryCheckpoint(store, key, checkpoint) {
+    const progress = recoveryProgressFor(store);
+    if (!progress.has(key) && progress.size >= 500) {
+        const oldest = progress.keys().next().value;
+        if (oldest !== undefined)
+            progress.delete(oldest);
+    }
+    progress.delete(key);
+    progress.set(key, checkpoint);
+}
+function feedBaselineAfterId(data) {
+    const metaAfterId = readNumber(readObject(data?.meta)?.next_after_id);
+    const ids = readArray(data?.results)
+        .map((entry) => readNumber(readObject(entry)?.id))
+        .filter((value) => value !== undefined);
+    return ids.length > 0 ? Math.max(metaAfterId ?? 0, ...ids) : metaAfterId;
+}
+async function refreshInventoryBaseline(fetchPage, collection, maxPages, timeBudgetMs, startPage = 1, recoveryProbe = "inventory") {
+    const startedAt = Date.now();
+    let page = startPage;
+    let rows = 0;
+    let hasMore = false;
+    do {
+        const api = await fetchPage(page, `${recoveryProbe}-${page}`);
+        const data = readObject(api.data);
+        rows += readArray(data?.[collection]).length;
+        hasMore = readBoolean(readObject(data?.meta)?.has_more) === true;
+        page += 1;
+    } while (hasMore && page < startPage + maxPages && Date.now() - startedAt < timeBudgetMs);
+    return {
+        collection,
+        rows_observed: rows,
+        pages_fetched: page - startPage,
+        next_page: hasMore && page <= MAX_UPSTREAM_PAGE ? page : undefined,
+        endpoint_page_limit_reached: hasMore && page > MAX_UPSTREAM_PAGE,
+        complete: !hasMore,
+        bounded: true
     };
 }
 function normalizeFeedCursorFilters(filters) {
     return Object.fromEntries(Object.entries(filters)
-        .filter(([key, value]) => key !== "after_id" && key !== "page" && value !== undefined)
+        .filter(([key, value]) => key !== "after_id" && key !== "page" && key !== "snapshot" && value !== undefined)
         .map(([key, value]) => [key, normalizeFeedCursorFilterValue(value)]));
 }
 function normalizeFeedCursorFilterValue(value) {
@@ -8441,6 +8772,11 @@ function splitFilterList(value) {
 function toQuery(values) {
     return compactRecord(values);
 }
+function assertStableSnapshotSupported(client, endpoint, snapshot) {
+    if (snapshot !== undefined && !client.supportsStableSnapshot(endpoint)) {
+        throw new Error(`The negotiated BBRadar API contract does not advertise stable snapshots for ${endpoint}. Omit snapshot to use live pagination.`);
+    }
+}
 function compactRecord(values) {
     return Object.fromEntries(Object.entries(values).filter(([, value]) => {
         if (value === undefined || value === null) {
@@ -8489,6 +8825,10 @@ function compactTarget(target) {
         in_scope: readBoolean(target.in_scope),
         eligible_for_bounty: readBoolean(target.eligible_for_bounty),
         wildcard: readBoolean(target.wildcard),
+        path_kind: stringField(target, "path_kind"),
+        path_prefix: stringField(target, "path_prefix"),
+        match_quality: stringField(target, "match_quality"),
+        match_reason: stringField(target, "match_reason"),
         target_opportunity_score: readNumber(target.target_opportunity_score),
         target_opportunity_label: stringField(target, "target_opportunity_label"),
         competition_risk: stringField(target, "competition_risk"),