@bbradar/mcp 0.2.2 → 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.2";
+const SERVER_VERSION = "0.2.5";
 const MAX_PROGRAMS_PER_SEARCH = 100;
 const MAX_TARGET_EXPORT = 500;
 const MAX_RECENT_CHANGES = 100;
@@ -21,8 +21,13 @@ const MAX_FIND_TARGET_SAMPLE_PROGRAMS = 10;
 const MAX_FIND_TARGET_SAMPLES = 20;
 const MAX_FIND_UPSTREAM_REQUEST_BUDGET = 50;
 const DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET = 20;
+const DEFAULT_HUNT_PROGRAM_PAGES = 7;
+const MAX_HUNT_RESULTS = 15;
+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;
@@ -50,6 +55,7 @@ const CORE_TOOL_NAMES = new Set([
     "get_program_targets",
     "get_recent_changes",
     "get_repository_changes",
+    "find_hunt_targets",
     "find_repository_hunt_targets",
     "get_latest_added_targets",
     "get_opportunities",
@@ -61,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",
@@ -178,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 = {
@@ -236,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);
@@ -397,14 +415,16 @@ export function createBbradarServer(client, config) {
             "Use BBRadar only for passive bug bounty intelligence; never scan or contact targets.",
             "This server uses the compact core tool profile. Start with get_bbradar_guide when unsure.",
             "Use resolve_program or run_program_name_action for a named program.",
-            "Use find_programs for general discovery and find_programs_by_target for reverse target lookup.",
+            "Use find_hunt_targets once for requests combining good rewards, broad scope, target quality, and recent target additions. Use find_repository_hunt_targets instead when Git or repository activity is explicitly required.",
+            "Use find_programs for lower-level program-only discovery and find_programs_by_target for reverse target lookup.",
             "Default to bounty-eligible in-scope data unless the user explicitly requests broader results.",
             "Prefer compact/identifier outputs and disclose sampled ranking scope when present."
         ]
         : [
             "Use BBRadar only for passive bug bounty intelligence; never scan or contact targets.",
             "When unsure which BBRadar tool to use, call get_bbradar_guide first. It is local-only and cheap.",
-            "Simple default path: find_program_candidates for discovery, run_program_name_action for one named program, get_program_eligible_targets_by_name for target lists by program name.",
+            "Simple default path: find_hunt_targets once for ranked target/program discovery, run_program_name_action for one named program, get_program_eligible_targets_by_name for exhaustive target lists by program name.",
+            "Do not repeat program discovery with alternate sorts or fan out get_program_targets across a shortlist; find_hunt_targets already includes exact bounded samples and recent target additions.",
             "Use advanced tools only after the user's goal is clear or the guide points to them.",
             "Partial program name + action: run_program_name_action. Partial program name only: resolve_program.",
             "Default to bounty-eligible in-scope data. Include out-of-scope, ineligible, VDP, disclosure-only, or no-bounty data only when the user explicitly asks.",
@@ -412,7 +432,7 @@ export function createBbradarServer(client, config) {
             "Self-Hosted programs use Self-Hosted:slug ids and are available through program search, exact detail, and target tools. Respect data_capabilities; do not infer missing opportunity, report-count, target-change, submission-cost, or repository signals.",
             "Freshness: find_recently_updated_programs, get_latest_added_targets, check_program_new_targets, check_watchlist_new_targets, find_recent_by_type, get_program_scope_delta.",
             "Repository activity: get_repository_changes defaults to compact program-only events. Seed with after_id, then resume the in-memory per-filter cursor.",
-            "Discovery: find_program_candidates, find_wildcard_programs, find_recently_added_wildcards, find_low_competition_high_reward, find_stack_matches, find_language_programs, find_target_type_programs, find_reward_programs, find_paid_programs, find_vdp_programs, find_web3_contests, find_low_noise_programs.",
+            "Discovery: find_hunt_targets is the one-call default; find_program_candidates, find_wildcard_programs, find_recently_added_wildcards, find_low_competition_high_reward, find_stack_matches, find_language_programs, find_target_type_programs, find_reward_programs, find_paid_programs, find_vdp_programs, find_web3_contests, and find_low_noise_programs are lower-level alternatives.",
             "Details: get_program_brief, get_program_scope_summary, get_program_target_breakdown, find_programs_by_target, compare_programs_compact.",
             "Prefer compact/identifier outputs and disclose sampled ranking scope when present."
         ];
@@ -429,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);
@@ -437,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
@@ -453,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)
@@ -464,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.",
@@ -622,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),
@@ -651,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));
@@ -675,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,
@@ -687,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),
@@ -717,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, {
@@ -733,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),
@@ -741,9 +828,54 @@ export function createBbradarServer(client, config) {
             source_requests: collected.sourceRequests.length > 1 ? collected.sourceRequests : undefined
         }), "repository_changes", "repository changes", continuationStore, 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. 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."),
+            tags: tagListSchema(),
+            scope_tags: scopeTagListSchema(),
+            target_types: targetTypeListSchema(),
+            language_tags: languageTagListSchema(),
+            surface_mode: z.enum(["any", "web2", "web3"]).default("any"),
+            min_bounty_max: z.number().int().min(0).optional(),
+            require_bounty: z.boolean().default(true),
+            max_public_report_count: z.number().int().min(0).optional(),
+            include_unknown_report_count: z.boolean().default(true),
+            min_eligible_targets: z.number().int().min(0).default(3),
+            min_total_targets: z.number().int().min(0).optional(),
+            min_wildcards: z.number().int().min(0).max(1000).default(0),
+            min_added_7d: z.number().int().min(0).optional(),
+            fresh_launch_days: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).optional(),
+            updated_since: isoDateTimeSchema.optional(),
+            min_target_score: z.number().int().min(0).max(100).optional(),
+            target_opportunity_label: targetOpportunityLabelSchema.optional(),
+            competition_risk: competitionRiskSchema.optional(),
+            include_recent_changes: z.boolean().default(true),
+            recent_target_days: z.number().int().min(1).max(365).default(30),
+            recent_changes_page_size: recentChangesPageSizeSchema.default(Math.min(MAX_RECENT_CHANGES, maxTargetChangesPageSize)),
+            max_program_pages: z.number().int().min(1).max(MAX_FIND_PROGRAM_PAGES).default(DEFAULT_HUNT_PROGRAM_PAGES),
+            max_results: z.number().int().min(1).max(MAX_HUNT_RESULTS).default(10),
+            targets_per_result: z.number().int().min(1).max(MAX_HUNT_TARGETS_PER_RESULT).default(5),
+            ranking_mode: z.enum(["balanced", "highest_reward", "widest_scope", "freshest_targets", "lowest_competition"]).default("balanced"),
+            upstream_request_budget: z.number().int().min(2).max(MAX_FIND_UPSTREAM_REQUEST_BUDGET).default(DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET)
+        },
+        outputSchema: {
+            ...apiEnvelopeOutputShape(),
+            matches: z.array(jsonRecordSchema()).optional(),
+            filters: jsonRecordSchema().optional(),
+            errors: z.array(jsonRecordSchema()).optional(),
+            upstream_budget: jsonRecordSchema().optional(),
+            ranking_scope: jsonRecordSchema().optional(),
+            result_guidance: jsonRecordSchema().optional(),
+            meta: jsonRecordSchema().optional()
+        },
+        annotations: readOnlyAnnotations
+    }, (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."),
@@ -864,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),
@@ -888,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),
@@ -989,7 +1121,7 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("find_programs", {
         title: "Find BBRadar Programs",
-        description: "Ranked program discovery with positive and negative platform/surface filters and compact output. Strict-filter retries reuse cached upstream pages, so relax one local filter at a time when a narrow query returns no candidates.",
+        description: "Lower-level program-only discovery. For normal 'find good targets/programs' requests, prefer one find_hunt_targets call because it already combines ranking, exact bounded target samples, and recent additions. Use this tool when raw program filtering without target enrichment is specifically needed; keep output_mode=compact and avoid parallel alternate-sort calls.",
         inputSchema: {
             platforms: platformListSchema(),
             exclude_platforms: stringListSchema("Platforms to exclude after retrieval. Use list_filters first when the user asks for a geographic/platform exclusion without naming exact platform values."),
@@ -1374,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),
@@ -1881,10 +2013,10 @@ function bbradarGuide(topic, profile, client) {
     }
     const primaryEntryPoints = [
         {
-            tool: "find_program_candidates",
-            use_when: "The user wants good programs to hunt, broad discovery, or does not name one exact program.",
+            tool: "find_hunt_targets",
+            use_when: "The user wants good targets or programs ranked by rewards, scope, competition, target quality, or recent target additions without requiring repository activity.",
             minimum_arguments: {},
-            useful_arguments: ["platforms", "target_types", "language_tags", "min_bounty_max", "max_public_report_count", "fresh_launch_days", "has_api_scope"]
+            useful_arguments: ["platforms", "surface_mode", "target_types", "language_tags", "min_bounty_max", "max_public_report_count", "recent_target_days", "ranking_mode"]
         },
         {
             tool: "find_repository_hunt_targets",
@@ -1913,13 +2045,13 @@ function bbradarGuide(topic, profile, client) {
     const decisionTree = [
         {
             user_goal: "find programs to hunt",
-            first_tool: "find_program_candidates",
-            then: "Use get_program_brief on the best program_id if the user wants details."
+            first_tool: "find_hunt_targets",
+            then: "Treat its ranked matches, exact bounded target samples, and recent additions as final unless the user explicitly requests an exhaustive scope dump for one selected program."
         },
         {
             user_goal: "Web2 programs with broad scope, good rewards, recent target activity, and excluded platforms",
-            first_tool: "list_filters",
-            then: "Resolve the excluded platform names, then call find_programs with exclude_platforms, exclude_web3=true, exclude_non_web=true, reward/scope/freshness thresholds, and sort_by=most_new_targets. If strict local filters return zero, relax one threshold and retry; cached source pages make the retry cheap."
+            first_tool: "find_hunt_targets",
+            then: "Call once with surface_mode=web2 and the requested platforms/exclusions. Do not split the platforms or ranking dimensions into separate calls."
         },
         {
             user_goal: "named program summary",
@@ -1991,7 +2123,7 @@ function bbradarGuide(topic, profile, client) {
         }
     ];
     const advancedTools = {
-        discovery: ["find_wildcard_programs", "find_low_competition_high_reward", "find_stack_matches", "find_language_programs", "find_target_type_programs", "find_reward_programs", "find_paid_programs", "find_web3_contests", "find_low_noise_programs"],
+        discovery: ["find_hunt_targets", "find_wildcard_programs", "find_low_competition_high_reward", "find_stack_matches", "find_language_programs", "find_target_type_programs", "find_reward_programs", "find_paid_programs", "find_web3_contests", "find_low_noise_programs"],
         freshness: ["find_recently_added_wildcards", "find_recently_updated_programs", "find_fresh_hunt_candidates", "get_latest_added_targets", "get_recent_target_activity", "get_program_scope_delta", "check_watchlist_new_targets"],
         details: ["get_program_brief", "get_program_scope_summary", "get_program_target_breakdown", "find_programs_by_target"],
         exports: ["export_targets"]
@@ -2064,9 +2196,10 @@ function bbradarGuide(topic, profile, client) {
 function coreBbradarGuide(topic, client) {
     const decisionTree = [
         {
-            user_goal: "find programs to hunt",
-            first_tool: "find_programs",
-            arguments: { max_results: 10, output_mode: "compact" }
+            user_goal: "find good hunt targets or programs using rewards, scope, competition, target quality, or recent target additions",
+            first_tool: "find_hunt_targets",
+            arguments: { max_results: 10, ranking_mode: "balanced" },
+            then: "Use this single result as the final shortlist; do not repeat find_programs with alternate sorts or fetch each program's targets."
         },
         {
             user_goal: "named program targets",
@@ -2102,7 +2235,7 @@ function coreBbradarGuide(topic, client) {
         {
             user_goal: "unknown filter values",
             first_tool: "list_filters",
-            then: "Reuse observed platforms, tags, target types, and language tags in find_programs."
+            then: "Reuse observed platforms, tags, target types, and language tags in one find_hunt_targets call."
         }
     ];
     return {
@@ -2118,6 +2251,7 @@ function coreBbradarGuide(topic, client) {
             require_bounty: true
         },
         primary_entry_points: [
+            "find_hunt_targets",
             "find_programs",
             "find_repository_hunt_targets",
             "run_program_name_action",
@@ -4353,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),
@@ -4375,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"
         }
@@ -5633,7 +5800,7 @@ function previewExportText(payload) {
 }
 function collectResourceLinks(payload) {
     const links = new Map();
-    for (const program of extractProgramsFromPayload(payload)) {
+    for (const program of extractProgramsFromPayload(payload).slice(0, MAX_BULK_PROGRAM_RESOURCE_LINKS)) {
         const id = stringField(program, "id");
         const resourceLinks = readObject(program.resource_links);
         const programUri = stringField(resourceLinks, "program");
@@ -5735,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"),
@@ -5753,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)
     });
 }
@@ -5813,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) ?? {}))
@@ -5981,15 +6154,15 @@ function candidateTradeoffs(candidate) {
 }
 function candidateNextAction(candidate) {
     if (candidate.wildcardCount > 0) {
-        return "Review in-scope wildcard targets with get_program_targets and keep follow-up analysis passive and BBRadar-data-backed.";
+        return "Use included target samples for shortlisting; call get_program_targets only if the user explicitly requests the selected program's exhaustive wildcard scope.";
     }
     if (candidateHasApiSurface(candidate)) {
-        return "Review API targets with get_program_targets and summarize the allowed API scope from BBRadar data.";
+        return "Use included target samples for shortlisting; call get_program_targets only if the user explicitly requests the selected program's exhaustive API scope.";
     }
     if (candidateHasWebSurface(candidate)) {
-        return "Review web/domain targets with get_program_targets and summarize freshness, reward, and report-count signals.";
+        return "Use included target samples for shortlisting; call get_program_targets only if the user explicitly requests the selected program's exhaustive web scope.";
     }
-    return "Fetch exact scope with get_program_targets before making recommendations.";
+    return "The program-level ranking is sufficient for a shortlist; fetch exact scope only if the user requests exhaustive details for this program.";
 }
 function targetSurfaceScore(candidate) {
     return candidate.targetSurfaceScore;
@@ -6294,13 +6467,595 @@ function clampLimit(name, value, max, warnings) {
     warnings.push(`${name} was clamped from ${value} to ${max}.`);
     return max;
 }
+async function findHuntTargets(client, config, input) {
+    const warnings = [];
+    const errors = [];
+    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;
+    const candidatePoolSize = Math.min(MAX_FIND_PROGRAM_RESULTS, Math.max(input.max_results, input.max_results * 3));
+    const programRequestBudget = Math.min(input.max_program_pages, Math.max(1, Math.ceil((input.upstream_request_budget - recentRequestReserve) / 2)));
+    const programInput = {
+        platforms: input.platforms,
+        exclude_platforms: input.exclude_platforms,
+        tags: input.tags,
+        scope_tags: input.scope_tags,
+        target_types: input.target_types,
+        language_tags: input.language_tags,
+        web3: input.surface_mode === "web3",
+        exclude_web3: input.surface_mode === "web2",
+        opportunity_levels: [],
+        updated_since: input.updated_since,
+        min_bounty_min: undefined,
+        min_bounty_max: input.min_bounty_max,
+        max_bounty_max: undefined,
+        require_bounty: input.require_bounty,
+        max_public_report_count: input.max_public_report_count,
+        require_known_report_count: false,
+        include_unknown_report_count: input.include_unknown_report_count,
+        exclude_ctf: true,
+        exclude_mobile_only: input.surface_mode === "web2",
+        exclude_non_web: input.surface_mode === "web2",
+        has_api_scope: false,
+        contest_like: false,
+        vdp_mode: "exclude",
+        fresh_launch_days: input.fresh_launch_days,
+        min_wildcards: input.min_wildcards,
+        min_eligible_targets: input.min_eligible_targets,
+        min_total_targets: input.min_total_targets,
+        min_added_24h: undefined,
+        min_added_7d: input.min_added_7d,
+        max_pages: input.max_program_pages,
+        max_results: candidatePoolSize,
+        sort_by: huntProgramSort(input.ranking_mode),
+        include_target_samples: false,
+        target_sample_programs: 0,
+        target_sample_size: 1,
+        only_in_scope_targets: true,
+        only_bounty_eligible_targets: true,
+        target_samples_only_wildcards: false,
+        output_mode: "compact",
+        upstream_request_budget: programRequestBudget
+    };
+    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) {
+        warnings.push(`Recent target-change queries were reduced from ${desiredRecentChangeQueries.length} to ${recentChangeQueries.length} to preserve the upstream request budget.`);
+    }
+    const [programPayload, recentResult] = await Promise.all([
+        findPrograms(client, config, programInput),
+        recentChangesEnabled
+            ? fetchHuntRecentChanges(client, config, input, recentChangeQueries)
+            : Promise.resolve({ changes: [], sourceRequests: [], requestsUsed: 0, errors: [] })
+    ]);
+    const programWarnings = readArray(programPayload.warnings).filter((warning) => typeof warning === "string");
+    warnings.push(...programWarnings);
+    errors.push(...recentResult.errors);
+    const programBudget = readObject(programPayload.upstream_budget);
+    const programRequestsUsed = readNumber(programBudget?.used) ?? 0;
+    const targetRequestBudget = Math.max(0, input.upstream_request_budget - programRequestsUsed - recentResult.requestsUsed);
+    const programEntries = readArray(programPayload.programs)
+        .map(readObject)
+        .filter((program) => program !== undefined);
+    const recentByProgram = groupRecentHuntChanges(recentResult.changes, input);
+    const preliminaryRankedEntries = programEntries
+        .map((entry) => ({
+        entry,
+        ranking: buildHuntTargetMatch(entry, new Map(), recentByProgram, input)
+    }))
+        .sort((left, right) => compareHuntTargetMatches(left.ranking, right.ranking, input.ranking_mode));
+    const sampledProgramCount = Math.min(input.max_results, preliminaryRankedEntries.length, targetRequestBudget);
+    const finalistEntries = preliminaryRankedEntries
+        .slice(0, sampledProgramCount)
+        .map((entry) => entry.entry);
+    const targetResult = await collectHuntTargetSamples(client, finalistEntries, input);
+    errors.push(...targetResult.errors);
+    if (sampledProgramCount < Math.min(input.max_results, programEntries.length)) {
+        warnings.push(`The upstream request budget limited the final exact target shortlist to ${sampledProgramCount} of ${Math.min(input.max_results, programEntries.length)} requested results.`);
+    }
+    const ranked = finalistEntries
+        .map((entry) => buildHuntTargetMatch(entry, targetResult.targetsByProgram, recentByProgram, input))
+        .sort((left, right) => compareHuntTargetMatches(left, right, input.ranking_mode))
+        .slice(0, input.max_results);
+    const matches = ranked.map((entry, index) => ({
+        rank: index + 1,
+        ...entry.payload
+    }));
+    const targetRequestsUsed = targetResult.requestsUsed;
+    const totalRequestsUsed = programRequestsUsed + recentResult.requestsUsed + targetRequestsUsed;
+    return stripUndefined({
+        request_id: randomUUID(),
+        fetched_at: new Date().toISOString(),
+        source_requests: [
+            ...readArray(programPayload.source_requests),
+            ...recentResult.sourceRequests,
+            ...targetResult.sourceRequests
+        ],
+        warnings: uniqueStrings(warnings).length > 0 ? uniqueStrings(warnings) : undefined,
+        errors: errors.length > 0 ? errors : undefined,
+        filters: stripUndefined({
+            platforms: input.platforms.length > 0 ? input.platforms : undefined,
+            exclude_platforms: input.exclude_platforms.length > 0 ? input.exclude_platforms : undefined,
+            tags: input.tags.length > 0 ? input.tags : undefined,
+            scope_tags: input.scope_tags.length > 0 ? input.scope_tags : undefined,
+            target_types: input.target_types.length > 0 ? input.target_types : undefined,
+            language_tags: input.language_tags.length > 0 ? input.language_tags : undefined,
+            surface_mode: input.surface_mode,
+            min_bounty_max: input.min_bounty_max,
+            require_bounty: input.require_bounty,
+            max_public_report_count: input.max_public_report_count,
+            min_eligible_targets: input.min_eligible_targets,
+            min_total_targets: input.min_total_targets,
+            min_wildcards: input.min_wildcards,
+            min_added_7d: input.min_added_7d,
+            fresh_launch_days: input.fresh_launch_days,
+            updated_since: input.updated_since,
+            min_target_score: input.min_target_score,
+            target_opportunity_label: input.target_opportunity_label,
+            competition_risk: input.competition_risk,
+            recent_target_days: input.include_recent_changes ? input.recent_target_days : undefined,
+            ranking_mode: input.ranking_mode
+        }),
+        upstream_budget: {
+            initial: input.upstream_request_budget,
+            used: totalRequestsUsed,
+            remaining: Math.max(0, input.upstream_request_budget - totalRequestsUsed)
+        },
+        ranking_scope: stripUndefined({
+            ...(readObject(programPayload.ranking_scope) ?? {}),
+            single_program_catalog_pass: true,
+            recent_change_window_days: input.include_recent_changes ? input.recent_target_days : undefined,
+            recent_change_page_size: input.include_recent_changes ? input.recent_changes_page_size : undefined
+        }),
+        result_guidance: {
+            final_shortlist: true,
+            follow_up_calls_required: false,
+            instruction: "Use these matches as the final shortlist. Exact bounded target samples and recent additions are already included; call get_program_targets only if the user explicitly requests an exhaustive scope dump for one selected program."
+        },
+        matches,
+        meta: {
+            returned: matches.length,
+            program_candidates: programEntries.length,
+            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,
+            partial_success: errors.length > 0
+        }
+    });
+}
+function huntProgramSort(mode) {
+    if (mode === "highest_reward") {
+        return "highest_reward";
+    }
+    if (mode === "widest_scope") {
+        return "most_eligible_targets";
+    }
+    if (mode === "freshest_targets") {
+        return "most_new_targets";
+    }
+    if (mode === "lowest_competition") {
+        return "lowest_reports";
+    }
+    return "best_hunt_value";
+}
+async function fetchHuntRecentChanges(client, config, input, targetTypes) {
+    const results = await Promise.all(targetTypes.map(async (targetType) => {
+        try {
+            const api = await client.getRecentChanges(toQuery({
+                change_type: "added",
+                minTargetScore: input.min_target_score,
+                targetOpportunityLabel: input.target_opportunity_label,
+                competitionRisk: input.competition_risk,
+                include_removed: false,
+                include_ineligible: false,
+                include_out_of_scope: false,
+                platforms: input.platforms,
+                tags: targetType ? [targetType] : undefined,
+                page: 1,
+                page_size: input.recent_changes_page_size
+            }));
+            const data = readObject(api.data);
+            return {
+                changes: readArray(data?.results).map((change) => sanitizeChange(change, config.webBaseUrl)),
+                sourceRequest: {
+                    source: "recent_changes",
+                    target_type: targetType,
+                    request_id: api.requestId,
+                    upstream_request_id: api.upstreamRequestId,
+                    ...apiSourceMetadata(api),
+                    page: 1
+                },
+                requestsUsed: api.cached || api.coalesced ? 0 : 1,
+                error: undefined
+            };
+        }
+        catch (error) {
+            return {
+                changes: [],
+                sourceRequest: undefined,
+                requestsUsed: error instanceof BBRadarApiError && (error.cached || error.coalesced) ? 0 : 1,
+                error: apiOperationError(targetType ? `recent ${targetType} target changes` : "recent target changes", error)
+            };
+        }
+    }));
+    const changes = new Map();
+    for (const result of results) {
+        for (const change of result.changes) {
+            const id = readNumber(change.id) ?? stringField(change, "id");
+            const target = readObject(change.target);
+            const program = readObject(change.program);
+            const fallbackKey = `${stringField(program, "id") ?? ""}:${targetIdentifier(target ?? {}) ?? ""}:${stringField(change, "changed_at") ?? ""}`;
+            changes.set(id === undefined ? fallbackKey : String(id), change);
+        }
+    }
+    return {
+        changes: [...changes.values()],
+        sourceRequests: results
+            .map((result) => result.sourceRequest)
+            .filter((request) => request !== undefined),
+        requestsUsed: results.reduce((total, result) => total + result.requestsUsed, 0),
+        errors: results
+            .map((result) => result.error)
+            .filter((error) => error !== undefined)
+    };
+}
+function huntRecentChangeQueries(input) {
+    const requested = uniqueStrings(input.target_types);
+    if (requested.length > 0 && requested.length <= 3) {
+        return requested;
+    }
+    if (requested.length > 3) {
+        return [undefined];
+    }
+    if (input.surface_mode === "web2") {
+        return ["domain", "api", "wildcard"];
+    }
+    if (input.surface_mode === "web3") {
+        return ["source code", "smart contract", "blockchain-dlt"];
+    }
+    return [undefined];
+}
+async function collectHuntTargetSamples(client, programs, input) {
+    const targetsByProgram = new Map();
+    const sourceRequestsByIndex = new Array(programs.length);
+    const errorsByIndex = new Array(programs.length);
+    let requestsUsed = 0;
+    await mapWithConcurrency(programs.map((program, index) => ({ program, index })), TARGET_SAMPLE_CONCURRENCY, async ({ program, index }) => {
+        const programId = stringField(program, "id");
+        if (!programId) {
+            return;
+        }
+        try {
+            const requestedPageSize = Math.max(input.targets_per_result, input.target_types.length > 1 ? input.targets_per_result * 10 : input.targets_per_result * 4, 20);
+            const api = await client.getProgramTargets(programId, {
+                target_type: input.target_types.length === 1 ? input.target_types[0] : undefined,
+                eligibility: "eligible",
+                minTargetScore: input.min_target_score,
+                targetOpportunityLabel: input.target_opportunity_label,
+                competitionRisk: input.competition_risk,
+                page: 1,
+                page_size: Math.min(client.endpointNumber("program_targets", "max_page_size", MAX_TARGETS_PER_PROGRAM), requestedPageSize)
+            });
+            const data = readObject(api.data);
+            const matchingTargets = readArray(data?.targets)
+                .map(sanitizeTarget)
+                .filter((target) => huntTargetMatches(target, input));
+            const targets = selectHuntTargetSamples(matchingTargets, input.targets_per_result, input.recent_target_days);
+            targetsByProgram.set(programId, targets);
+            sourceRequestsByIndex[index] = {
+                source: "program_targets",
+                program_id: programId,
+                request_id: api.requestId,
+                upstream_request_id: api.upstreamRequestId,
+                ...apiSourceMetadata(api)
+            };
+            if (!api.cached && !api.coalesced) {
+                requestsUsed += 1;
+            }
+        }
+        catch (error) {
+            errorsByIndex[index] = apiOperationError(programId, error);
+            if (!(error instanceof BBRadarApiError) || (!error.cached && !error.coalesced)) {
+                requestsUsed += 1;
+            }
+        }
+    });
+    return {
+        targetsByProgram,
+        sourceRequests: sourceRequestsByIndex.filter((request) => request !== undefined),
+        requestsUsed,
+        errors: errorsByIndex.filter((error) => error !== undefined)
+    };
+}
+function huntTargetMatches(target, input) {
+    if (target.in_scope !== true || target.eligible_for_bounty !== true) {
+        return false;
+    }
+    if (input.target_types.length > 0 && !input.target_types.some((targetType) => targetMatchesRequestedType(target, targetType))) {
+        return false;
+    }
+    if (input.scope_tags.length > 0 && !arraysIntersectNormalized(new Set(input.scope_tags.map(normalizeTag)), readStringArrayField(target, "scope_tags"))) {
+        return false;
+    }
+    if (input.language_tags.length > 0 && !arraysIntersectNormalized(new Set(input.language_tags.map(normalizeTag)), readStringArrayField(target, "language_tags"))) {
+        return false;
+    }
+    if (input.min_target_score !== undefined && (readNumber(target.target_opportunity_score) ?? -1) < input.min_target_score) {
+        return false;
+    }
+    if (input.target_opportunity_label !== undefined && stringField(target, "target_opportunity_label") !== input.target_opportunity_label) {
+        return false;
+    }
+    if (input.competition_risk !== undefined && stringField(target, "competition_risk") !== input.competition_risk) {
+        return false;
+    }
+    return true;
+}
+function compareHuntTargets(left, right) {
+    return (compareNumbersDesc(readNumber(left.target_opportunity_score), readNumber(right.target_opportunity_score)) ||
+        Number(readBoolean(right.wildcard) === true) - Number(readBoolean(left.wildcard) === true) ||
+        (targetIdentifier(left) ?? "").localeCompare(targetIdentifier(right) ?? ""));
+}
+function selectHuntTargetSamples(targets, limit, recentTargetDays) {
+    const selected = new Map();
+    const cutoff = Date.now() - recentTargetDays * 24 * 60 * 60 * 1000;
+    const newest = [...targets]
+        .filter((target) => huntTargetAddedTimestamp(target) >= cutoff)
+        .sort((left, right) => huntTargetAddedTimestamp(right) - huntTargetAddedTimestamp(left));
+    const byQuality = [...targets].sort(compareHuntTargets);
+    for (const target of newest.slice(0, Math.min(2, limit))) {
+        const identifier = targetIdentifier(target);
+        if (identifier) {
+            selected.set(identifier, target);
+        }
+    }
+    for (const target of byQuality) {
+        if (selected.size >= limit) {
+            break;
+        }
+        const identifier = targetIdentifier(target);
+        if (identifier && !selected.has(identifier)) {
+            selected.set(identifier, target);
+        }
+    }
+    return [...selected.values()];
+}
+function huntTargetAddedTimestamp(target) {
+    const addedAt = stringField(target, "added_at") ?? stringField(target, "source_added_at");
+    const timestamp = addedAt ? Date.parse(addedAt) : Number.NaN;
+    return Number.isFinite(timestamp) ? timestamp : 0;
+}
+function groupRecentHuntChanges(changes, input) {
+    const cutoff = Date.now() - input.recent_target_days * 24 * 60 * 60 * 1000;
+    const byProgram = new Map();
+    for (const change of changes) {
+        if (stringField(change, "change_type") !== "added" || timestampField(change, "changed_at") < cutoff) {
+            continue;
+        }
+        const program = readObject(change.program);
+        const target = readObject(change.target);
+        const programId = stringField(program, "id");
+        if (!programId || !target || !huntTargetMatches(target, input)) {
+            continue;
+        }
+        const existing = byProgram.get(programId) ?? [];
+        const identifier = targetIdentifier(target);
+        if (!identifier || !existing.some((entry) => targetIdentifier(readObject(entry.target) ?? {}) === identifier)) {
+            existing.push(change);
+            existing.sort((left, right) => timestampField(right, "changed_at") - timestampField(left, "changed_at"));
+            byProgram.set(programId, existing);
+        }
+    }
+    return byProgram;
+}
+function buildHuntTargetMatch(entry, targetsByProgram, recentByProgram, input) {
+    const programId = stringField(entry, "id") ?? "";
+    const targetSamples = targetsByProgram.get(programId) ?? [];
+    const recentChanges = recentByProgram.get(programId) ?? [];
+    const recentTargets = recentHuntTargetEntries(targetSamples, recentChanges, input.recent_target_days);
+    const rankFactors = readObject(entry.rank_factors) ?? {};
+    const latestRecentAt = recentTargets[0]?.addedAt;
+    const rewardScore = normalizedRewardScore(readNumber(rankFactors.bounty_max));
+    const scopeScore = Math.min(100, (readNumber(rankFactors.eligible_targets) ?? 0) * 2 +
+        (readNumber(rankFactors.wildcard_targets) ?? 0) * 5 +
+        (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);
+    // 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);
+    const program = compactProgram(entry);
+    delete program.resource_links;
+    const existingReasons = readArray(entry.why_ranked_here).filter((reason) => typeof reason === "string");
+    const reasons = [...existingReasons];
+    if (recentTargets.length > 0) {
+        reasons.push(`${recentTargets.length} eligible target additions in the last ${input.recent_target_days} days`);
+    }
+    if (bestTargetScore > 0) {
+        reasons.push(`best sampled target score ${bestTargetScore}`);
+    }
+    return {
+        compositeScore,
+        rewardScore,
+        scopeScore,
+        freshnessScore,
+        competitionScore,
+        payload: stripUndefined({
+            program,
+            match_score: compositeScore,
+            rank_factors: {
+                ...rankFactors,
+                reward_score: roundScore(rewardScore),
+                scope_score: roundScore(scopeScore),
+                freshness_score: roundScore(freshnessScore),
+                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,
+                composite_score: compositeScore
+            },
+            why_ranked_here: uniqueStrings(reasons),
+            tradeoffs: readArray(entry.tradeoffs).filter((tradeoff) => typeof tradeoff === "string"),
+            target_samples: targetSamples.map(compactHuntTarget),
+            recent_added_targets: recentTargets.slice(0, input.targets_per_result).map((recent) => ({
+                ...compactHuntTarget(recent.target),
+                added_at: recent.addedAt,
+                freshness_source: recent.source
+            }))
+        })
+    };
+}
+function compactHuntTarget(target) {
+    return stripUndefined({
+        ...compactTarget(target),
+        added_at: stringField(target, "added_at"),
+        source_added_at: stringField(target, "source_added_at"),
+        last_changed_at: stringField(target, "last_changed_at")
+    });
+}
+function recentHuntTargetEntries(targetSamples, recentChanges, recentTargetDays) {
+    const cutoff = Date.now() - recentTargetDays * 24 * 60 * 60 * 1000;
+    const entries = new Map();
+    const remember = (target, addedAt, source) => {
+        const identifier = targetIdentifier(target);
+        const timestamp = addedAt ? Date.parse(addedAt) : Number.NaN;
+        if (!identifier || !addedAt || !Number.isFinite(timestamp) || timestamp < cutoff) {
+            return;
+        }
+        const existing = entries.get(identifier);
+        if (!existing || timestamp > existing.timestamp || (timestamp === existing.timestamp && source === "target_change")) {
+            entries.set(identifier, { target, addedAt, source, timestamp });
+        }
+    };
+    for (const change of recentChanges) {
+        const target = readObject(change.target);
+        if (target) {
+            remember(target, stringField(change, "changed_at"), "target_change");
+        }
+    }
+    for (const target of targetSamples) {
+        remember(target, stringField(target, "added_at") ?? stringField(target, "source_added_at"), "target_inventory");
+    }
+    return [...entries.values()].sort((left, right) => right.timestamp - left.timestamp);
+}
+function normalizedRewardScore(reward) {
+    if (reward === undefined || reward <= 0) {
+        return 0;
+    }
+    return Math.min(100, Math.log10(reward + 1) / Math.log10(100_001) * 100);
+}
+function huntFreshnessScore(latestAt, recentCount, added7d) {
+    if (latestAt) {
+        const timestamp = Date.parse(latestAt);
+        if (Number.isFinite(timestamp)) {
+            const ageDays = Math.max(0, (Date.now() - timestamp) / (24 * 60 * 60 * 1000));
+            return Math.min(100, Math.max(0, 100 - ageDays * 2) + Math.min(20, recentCount * 4));
+        }
+    }
+    return Math.min(100, Math.max(0, added7d ?? 0) * 12);
+}
+function huntCompositeScore(mode, baseHuntScore, rewardScore, scopeScore, freshnessScore, competitionScore, bestTargetScore) {
+    if (mode === "highest_reward") {
+        return roundScore(rewardScore * 0.7 + baseHuntScore * 0.2 + scopeScore * 0.1);
+    }
+    if (mode === "widest_scope") {
+        return roundScore(scopeScore * 0.7 + baseHuntScore * 0.2 + rewardScore * 0.1);
+    }
+    if (mode === "freshest_targets") {
+        return roundScore(freshnessScore * 0.7 + bestTargetScore * 0.15 + baseHuntScore * 0.15);
+    }
+    if (mode === "lowest_competition") {
+        return roundScore(competitionScore * 0.65 + baseHuntScore * 0.2 + rewardScore * 0.15);
+    }
+    return roundScore(baseHuntScore * 0.35 +
+        rewardScore * 0.2 +
+        scopeScore * 0.2 +
+        freshnessScore * 0.15 +
+        bestTargetScore * 0.1);
+}
+function roundScore(value) {
+    return Math.round(value * 100) / 100;
+}
+function compareHuntTargetMatches(left, right, mode) {
+    if (mode === "highest_reward") {
+        return right.rewardScore - left.rewardScore || right.compositeScore - left.compositeScore;
+    }
+    if (mode === "widest_scope") {
+        return right.scopeScore - left.scopeScore || right.compositeScore - left.compositeScore;
+    }
+    if (mode === "freshest_targets") {
+        return right.freshnessScore - left.freshnessScore || right.compositeScore - left.compositeScore;
+    }
+    if (mode === "lowest_competition") {
+        return right.competitionScore - left.competitionScore || right.compositeScore - left.compositeScore;
+    }
+    return right.compositeScore - left.compositeScore;
+}
 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,
@@ -6342,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)
@@ -7153,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;
     }
@@ -7478,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));
 }
@@ -7490,9 +8255,11 @@ function readStringArrayField(value, field) {
 }
 function registerPrompts(server, profile) {
     const discoveryToolInstructions = profile === "core"
-        ? `- Start with find_programs and pass opportunity_levels from the requested value below unless the user asked for a broader search.
-- Express language, target type, reward, Web3, wildcard, VDP, and platform needs through find_programs filters.`
-        : `- Start with find_program_candidates unless the user needs custom filters; pass opportunity_levels from the requested value below.
+        ? `- Start with find_hunt_targets for ranked target/program discovery. Make one call and use its shortlist as final; do not repeat find_programs with alternate sorts or fetch each candidate's targets.
+- Express language, target type, reward, Web2/Web3, wildcard, competition, freshness, and platform needs through find_hunt_targets filters.
+- Use find_repository_hunt_targets instead when the user explicitly requires Git or repository activity.`
+        : `- Start with find_hunt_targets for ranked target/program discovery; use its included target samples and recent additions as the final shortlist.
+- Use find_program_candidates only for lower-level program-only discovery; pass opportunity_levels from the requested value below.
 - Use find_language_programs for language asks, find_target_type_programs for API/mobile/source-code/domain asks, find_reward_programs or find_paid_programs for reward asks, find_vdp_programs only for explicit VDP/no-bounty asks, find_web3_contests for Web3 contest/audit asks, find_web3_programs for general Web3 requests, and find_wildcard_programs for wildcard-specific requests.`;
     server.registerPrompt("find_best_programs_to_hunt", {
         title: "Find Best Programs To Hunt",
@@ -7507,7 +8274,7 @@ function registerPrompts(server, profile) {
 
 Find the best BBRadar program candidates.
 ${discoveryToolInstructions}
-- Use this opportunity level JSON array: ${promptJson([args.opportunity_level ?? "elite"])}.
+- Treat this opportunity level JSON array as a ranking preference, not a strict first-pass filter: ${promptJson([args.opportunity_level ?? "elite"])}.
 - Apply platform filters from this JSON string if provided: ${promptJson(args.platforms ?? "")}.
 - Apply tag filters from this JSON string if provided: ${promptJson(args.tags ?? "")}.
 - Keep the shortlist to this JSON value: ${promptJson(args.max_programs ?? "10")}.
@@ -7586,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 = [];
@@ -7598,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;
@@ -7643,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) {
@@ -7855,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) {
@@ -7903,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"),