@bbradar/mcp 0.3.0 → 0.3.2

package/dist/server.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { requiresActivityQuery } from "./activityContract.js";
+import { requiresActivityQuery, validateActivityCatalogInput } from "./activityContract.js";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BBRadarApiError } from "./bbradarClient.js";
@@ -7,7 +7,7 @@ import { NumericCursorStore } from "./cursorStore.js";
 import { stableStringify, stripUndefined } from "./json.js";
 import { FixedWindowRateLimiter } from "./rateLimit.js";
 import { readArray, readBoolean, readNumber, readObject, readString, sanitizeJson, sanitizeProPayload, sanitizeChange, sanitizeProgram, sanitizeRepositoryChange, sanitizeTarget, sanitizeTargetsForExport } from "./sanitize.js";
-const SERVER_VERSION = "0.3.0";
+const SERVER_VERSION = "0.3.2";
 const MAX_PROGRAMS_PER_SEARCH = 100;
 const MAX_TARGET_EXPORT = 500;
 const MAX_RECENT_CHANGES = 100;
@@ -46,7 +46,7 @@ const MAX_IN_MEMORY_FEED_CURSORS = 500;
 const MAX_RESOLVE_SEARCH_QUERIES = 4;
 const FAST_RESOLVE_SEARCH_QUERIES = 2;
 const MAX_DIRECT_HANDLE_RESOLUTION_REQUESTS = 96;
-const SDK_VERSION = "1.29.0";
+const SDK_VERSION = "1.32.2";
 const CORE_TOOL_NAMES = new Set([
     "search_programs",
     "get_program",
@@ -257,11 +257,11 @@ const stableSnapshotSchema = z
     .string()
     .trim()
     .min(1)
-    .max(1_024)
+    .max(32, "Catalog snapshot tokens have at most 32 characters. Use 'start', then meta.snapshot; Activity snapshot IDs belong only to Activity and payout tools.")
     .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.");
+    .describe("Optional catalog/feed snapshot token, at most 32 characters. Send 'start' on page 1, then reuse meta.snapshot with identical filters. Do not pass get_activity_snapshot's snapshot_id here. Snapshot creation can be slower; omit it for the fastest live result.");
 const opaqueCursorSchema = z.string().min(1).max(4096).describe("Opaque five-minute cursor. Reuse with identical filters and page size; restart the query on expiry.");
 const analyticsDateSchema = () => z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Use an inclusive UTC YYYY-MM-DD date.");
 const proLimitSchema = z.number().int().min(1).max(100);
@@ -294,7 +294,7 @@ const ACTIVITY_SHARED_PARAMS = ["tab", "sort", "direction", "platforms", "tags",
 // a request so it cannot be silently ignored or reinterpreted.
 const ACTIVITY_TAB_PARAMS = {
     payouts: ["period", "basis", "precision"],
-    value: ["include_map"],
+    value: ["period", "include_map"],
     scope: ["period"],
     rewards: ["period"],
     updates: ["period", "category"],
@@ -309,7 +309,7 @@ const activityEventPeriodSchema = () => z.enum(["7d", "30d", "90d"]);
 const activityCatalogNumberSchema = () => z.number().finite().min(0).optional();
 const activityCatalogInput = {
     program_type: z.enum(["paid", "vdp", "unknown"]).optional(),
-    payout_metric: z.enum(["payout_total", "payout_increase", "payout_native_90d"]).optional(),
+    payout_metric: z.enum(["payout_total", "payout_increase", "payout_native_90d"]).optional().describe("payout_total requires all_time; payout_increase is a tracked counter increase in 24h/7d/30d/90d; payout_native_90d requires 90d and is provider-reported. Omit to select the period's default metric."),
     payout_period: activityCountPeriodSchema().optional(),
     payout_precision: z.enum(["exact", "proven_bounds"]).optional(),
     payout_min: activityCatalogNumberSchema(), payout_max: activityCatalogNumberSchema(),
@@ -322,7 +322,7 @@ const activityCatalogInput = {
     reward_change: z.enum(["increased", "decreased"]).optional(), reward_change_min_pct: activityCatalogNumberSchema(),
     updates_period: activityEventPeriodSchema().optional(),
     active_days_min: activityCatalogNumberSchema(), changes_min: activityCatalogNumberSchema(),
-    change_category: z.enum(["scope", "rewards", "rules", "program"]).optional(),
+    change_category: z.enum(["scope", "rewards", "rules", "program"]).optional().describe("Update-event category; requires its own updates_period. scope_period with scope_added_min already filters scope additions and does not need this field."),
     reports_period: activityCountPeriodSchema().optional(),
     reports_min: activityCatalogNumberSchema(), reports_max: activityCatalogNumberSchema(),
     reports_change: z.enum(["rising", "falling"]).optional(), reports_change_min_pct: activityCatalogNumberSchema(),
@@ -336,7 +336,7 @@ const activityCatalogInput = {
     activity_labels: z.array(z.string().min(1).max(64)).max(10).optional(),
     sort_by: activityCatalogSortSchema.optional(), sort_direction: z.enum(["asc", "desc"]).optional()
 };
-const activityCatalogGuidance = "Give each Activity signal its period (e.g. payout_period=30d with payout_positive=true; scope_period with scope_added_min) and use sort_by/sort_direction combinations enabled in get_activity_capabilities; default is updated descending. Tracked no_increase/lower require 30d. Nothing falls back to another period or precision.";
+const activityCatalogGuidance = "Give each Activity signal its own period. payout_total requires all_time; payout_increase uses 24h/7d/30d/90d; payout_native_90d requires 90d. change_category requires updates_period even when scope_period is present; scope_period with scope_added_min needs no change_category. Use enabled sort_by/sort_direction combinations; default is updated descending, and an omitted direction for first_response or time_to_bounty means ascending (fastest first). Tracked no_increase/lower require 30d. Catalog snapshot is 'start' or meta.snapshot, never an Activity snapshot_id. An empty result does not authorize relaxing the user's thresholds or restricting platforms to a recent-feed sample.";
 const freeSubmissionOnlySchema = z.boolean().default(false).describe("Only programs with no detected submission fee or deposit.");
 const programIdSchema = z
     .string()
@@ -348,6 +348,7 @@ const programIdSchema = z
     message: "program_id cannot contain control characters."
 })
     .describe("platform:handle id.");
+const PROGRAM_IDENTIFIER_DESCRIPTION = "BBRadar platform:handle program_id or a human program name/handle. Names are resolved automatically.";
 const programIdentifierSchema = z
     .string()
     .trim()
@@ -356,9 +357,9 @@ const programIdentifierSchema = z
     .refine((value) => !/[\u0000-\u001F\u007F]/.test(value), {
     message: "Program identifiers cannot contain control characters."
 })
-    .describe("BBRadar platform:handle program_id or a human program name/handle. Names are resolved automatically.");
+    .describe(PROGRAM_IDENTIFIER_DESCRIPTION);
 function jsonRecordSchema() {
-    return z.record(z.unknown());
+    return z.record(z.string(), z.unknown());
 }
 function programOutputSchema() {
     return jsonRecordSchema();
@@ -380,6 +381,13 @@ function apiEnvelopeOutputShape() {
         error: jsonRecordSchema().optional()
     };
 }
+// Tools that return one Pro API payload as it is. The API adds response fields
+// between MCP releases, and clients validate each structured result against the
+// discovered schema: listed fields document the contract, while a new top-level
+// field validates instead of failing every call (the API added Status facets on 2026-10-13).
+function apiMirrorOutput(shape) {
+    return z.object(shape).passthrough();
+}
 function programListOutputShape() {
     return {
         ...apiEnvelopeOutputShape(),
@@ -444,7 +452,13 @@ function createProfiledToolRegistrar(server, profile, client) {
             const extra = args[args.length - 1];
             return client.withRequestContext(extra.signal, () => callback(...args), readObject(args[0])?.snapshot === "start");
         });
-        const registeredTool = server.registerTool(name, toolConfig, scopedCallback);
+        // Raw SDK shapes otherwise strip unknown arguments. Every advertised
+        // filter must be applied or rejected, including on the older shortcuts.
+        const inputSchema = toolConfig.inputSchema;
+        const strictConfig = inputSchema && !(inputSchema instanceof z.ZodType)
+            ? { ...toolConfig, inputSchema: z.object(inputSchema).strict() }
+            : toolConfig;
+        const registeredTool = server.registerTool(name, strictConfig, scopedCallback);
         const requiredEndpoint = TOOL_ENDPOINT_REQUIREMENTS[name];
         if ((profile === "core" && !CORE_TOOL_NAMES.has(name)) ||
             (requiredEndpoint !== undefined && !client.supportsEndpoint(requiredEndpoint))) {
@@ -462,7 +476,8 @@ export function createBbradarServer(client, config) {
             "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.",
             "For payouts, reports, response measures or Activity comparisons, first read get_activity_capabilities, then get_activity_rankings with the matching tab for one ranking. For several conditions at once (e.g. recent payouts plus new scope, Web2-only, low competition, no submission fee) use one find_hunt_targets or find_programs call with Activity inputs and local filters together. Keep periods explicit; never intersect separately paginated rankings.",
-            "Activity data is published in versions. get_activity_snapshot reports the current version; pass its snapshot_id as snapshot to bind capabilities and first pages to one version, and never mix rows from different versions.",
+            "Activity data is published in versions. get_activity_snapshot's snapshot_id binds only Activity capabilities, Activity rankings and program payouts. Catalog/feed tools use snapshot=start then meta.snapshot instead; do not send an Activity snapshot_id to find_programs. Never mix rows from different versions.",
+            "Preserve the user's thresholds, periods and platform scope when discovery times out or returns no matches. A sampled recent-change feed does not enumerate all supported platforms. Inspect partial_success, errors, ranking_scope and scan before claiming complete coverage.",
             "For semantic changes use get_history_changes or get_program_history, then get_history_change_detail only when before/after items are needed. For exact activity use get_program_activity; for ranked activity use get_analytics_program_activity. Use daily analytics tools directly for date series.",
             "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."
@@ -474,7 +489,8 @@ export function createBbradarServer(client, config) {
             "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.",
             "For payouts, reports, response measures or Activity comparisons, first read get_activity_capabilities. Use get_activity_rankings (or its per-view alias) for one ranking, or one find_hunt_targets/find_programs call combining Activity inputs with Web2, scope, competition and fee filters. Keep server order and explicit periods; never re-rank a sampled catalog or intersect separate pages.",
-            "Activity data is published in versions. get_activity_snapshot reports the current version; pass its snapshot_id as snapshot to bind capabilities and first pages to one version, and never mix rows from different versions.",
+            "Activity data is published in versions. get_activity_snapshot's snapshot_id binds only Activity capabilities, Activity rankings and program payouts. Catalog/feed tools use snapshot=start then meta.snapshot instead; do not send an Activity snapshot_id to find_programs. Never mix rows from different versions.",
+            "Preserve the user's thresholds, periods and platform scope when discovery times out or returns no matches. A sampled recent-change feed does not enumerate all supported platforms. Inspect partial_success, errors, ranking_scope and scan before claiming complete coverage.",
             "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.",
             "Recently updated programs across platforms: find_recently_updated_programs. Do not infer a platform such as Immunefi unless the user explicitly names it.",
@@ -509,8 +525,8 @@ export function createBbradarServer(client, config) {
     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));
-    const historyOutput = { ...apiEnvelopeOutputShape(), changes: z.array(jsonRecordSchema()).optional(), coverage: jsonRecordSchema().optional(), meta: jsonRecordSchema().optional() };
-    const analyticsOutput = { ...apiEnvelopeOutputShape(), platform: z.string().optional(), program: jsonRecordSchema().optional(), programs: z.array(jsonRecordSchema()).optional(), series: z.array(jsonRecordSchema()).optional(), observations: jsonRecordSchema().optional(), category: z.string().optional(), population: z.string().optional(), ranking_definition: z.string().optional(), inventory_definition: z.string().optional(), meta: jsonRecordSchema().optional() };
+    const historyOutput = apiMirrorOutput({ ...apiEnvelopeOutputShape(), changes: z.array(jsonRecordSchema()).optional(), coverage: jsonRecordSchema().optional(), meta: jsonRecordSchema().optional() });
+    const analyticsOutput = apiMirrorOutput({ ...apiEnvelopeOutputShape(), platform: z.string().optional(), program: jsonRecordSchema().optional(), programs: z.array(jsonRecordSchema()).optional(), series: z.array(jsonRecordSchema()).optional(), observations: jsonRecordSchema().optional(), category: z.string().optional(), population: z.string().optional(), ranking_definition: z.string().optional(), inventory_definition: z.string().optional(), meta: jsonRecordSchema().optional() });
     // Published Activity versions are 64 lowercase hex characters. "start" and
     // catalog snapshot tokens are different contracts and are rejected here.
     const activitySnapshotSchema = z.string().regex(/^[0-9a-f]{64}$/, "Use a snapshot_id returned by Activity.")
@@ -529,7 +545,7 @@ export function createBbradarServer(client, config) {
         program_type: z.enum(["paid", "vdp", "unknown"]).optional(),
         search: z.string().min(1).max(200).optional(),
         current_status: z.enum(["active", "paused", "suspended", "disabled", "closed", "unavailable", "unknown"]).optional(),
-        labels: z.array(z.string().min(1).max(64)).max(10).optional().describe("Only labels listed by get_activity_capabilities; others return 422."),
+        labels: z.array(z.string().min(1).max(64)).max(10).optional().describe("Only labels listed by get_activity_capabilities (for tab=value, the chosen period view's labels); others return 422."),
         opportunity_tiers: z.array(opportunityLevelSchema).min(1).max(4).optional().describe("Any of these catalog opportunity tiers, as frozen into the Activity version. get_activity_capabilities lists the tiers present in facets.opportunity_tiers; an API without the filter is rejected before any request."),
         launched_within: z.enum(["7d", "30d", "90d"]).optional(),
         category: z.enum(["scope", "rewards", "rules", "program"]).optional(),
@@ -539,19 +555,23 @@ export function createBbradarServer(client, config) {
         cursor: opaqueCursorSchema.optional(), limit: proLimitSchema.default(25),
         snapshot: activitySnapshotSchema.optional()
     };
-    const activityOutput = {
+    const activityOutput = apiMirrorOutput({
         ...apiEnvelopeOutputShape(), rows: z.array(jsonRecordSchema()).optional(), points: z.array(jsonRecordSchema()).optional(),
         tab: z.string().optional(), period: z.string().nullable().optional(),
         basis: z.string().nullable().optional(), precision: z.string().nullable().optional(),
         sort: z.string().nullable().optional(), direction: z.string().optional(), meta: jsonRecordSchema().optional(),
         cohort_median: jsonRecordSchema().nullable().optional(), available_views: z.array(jsonRecordSchema()).optional(),
-        map_points_omitted: z.number().int().optional()
-    };
+        map_points_omitted: z.number().int().optional(),
+        // tab=value: the label shortlist applied, including a default landing list (empty = the map's programs).
+        labels: z.array(z.string()).optional(),
+        // tab=status: event counts per change_type and current_status, each under the other filters.
+        facets: jsonRecordSchema().optional()
+    });
     registerTool("get_activity_capabilities", {
         title: "Get Available Activity Views",
         description: "Read the exact enabled period, sort, direction, basis and precision combinations before choosing an Activity ranking. Availability is evaluated before user filters; do not infer combinations from independent enums. Honor each view's sort_directions and default_direction and the enabled label list. The snapshot block identifies the published version these capabilities belong to.",
         inputSchema: z.object({ snapshot: activitySnapshotSchema.optional() }).strict(),
-        outputSchema: { ...apiEnvelopeOutputShape(), tabs: z.array(jsonRecordSchema()).optional(), version: z.union([z.string(), z.number()]).optional(), facets: jsonRecordSchema().optional(), labels: z.array(z.string()).optional(), listing: jsonRecordSchema().optional(), listing_payouts_enabled: z.boolean().optional(), derived_signals_enabled: z.boolean().optional(), snapshot: jsonRecordSchema().optional() },
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), tabs: z.array(jsonRecordSchema()).optional(), version: z.union([z.string(), z.number()]).optional(), facets: jsonRecordSchema().optional(), labels: z.array(z.string()).optional(), listing: jsonRecordSchema().optional(), listing_payouts_enabled: z.boolean().optional(), derived_signals_enabled: z.boolean().optional(), snapshot: jsonRecordSchema().optional() }),
         annotations: readOnlyAnnotations
     }, (args) => runTool("get_activity_capabilities", config, rateLimiter, async () => {
         assertProFeature(client, "activity_capabilities", "enabled");
@@ -560,9 +580,9 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("get_activity_snapshot", {
         title: "Get Current Activity Version",
-        description: "Read only the identity of the currently published Activity version: snapshot_id, frozen as_of cutoff, expires_at, policy_version and suggested poll_seconds. Use it to detect newer Activity data and pass snapshot_id as snapshot to bind capabilities, first pages and payouts to one version. as_of is when BBRadar froze its calculation, not a provider payment or update time.",
+        description: "Read only the identity of the currently published Activity version: snapshot_id, frozen as_of cutoff, expires_at, policy_version and suggested poll_seconds. Pass snapshot_id as snapshot only to get_activity_capabilities, get_activity_rankings and get_program_payouts. Catalog/feed tools such as find_programs use snapshot=start then meta.snapshot instead. as_of is when BBRadar froze its calculation, not a provider payment or update time.",
         inputSchema: z.object({}).strict(),
-        outputSchema: { ...apiEnvelopeOutputShape(), snapshot_id: z.string().optional(), as_of: z.string().optional(), expires_at: z.string().optional(), policy_version: z.string().optional(), poll_seconds: z.number().optional() },
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), snapshot_id: z.string().optional(), as_of: z.string().optional(), expires_at: z.string().optional(), policy_version: z.string().optional(), poll_seconds: z.number().optional() }),
         annotations: readOnlyAnnotations
     }, () => runTool("get_activity_snapshot", config, rateLimiter, async () => {
         assertProFeature(client, "activity_snapshot", "enabled");
@@ -575,11 +595,11 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("get_program_payouts", {
         title: "Get Program Payouts and Response Facts",
-        description: "Read reported totals, measured counter increases, source dates, precision, report and response facts, derived signals and label explanations for one exact platform:handle. Keep null separate from zero, bounds separate from exact amounts and unknown payment dates null. Payout timestamps are when increases were seen, never payment dates. No provider requests are made.",
+        description: "Read reported totals, measured counter increases, source dates, precision, report and response facts, derived signals and label explanations for one exact platform:handle. facts also carry each platform's own published figures (paid_average, paid_maximum, last_paid_on, HackerOne per-severity averages and report counts, triage/resolution times, response rate, researcher counts), each with its measure, unit, period and source_label; keep each definition and never compare them across platforms as one measure. Keep null separate from zero, bounds separate from exact amounts and unknown payment dates null. Payout timestamps are when increases were seen, never payment dates. value_points (include_map) are same-platform peers in the Value period named by value_period. No provider requests are made.",
         inputSchema: z.object({ program_id: programIdSchema, snapshot: activitySnapshotSchema.optional(), include_map: includeMapSchema }).strict(),
-        // Mirrors the API response, including its version identity: a client that
+        // Lists the API response fields, including its version identity: a client that
         // discovered this schema validates every structured result against it.
-        outputSchema: { ...apiEnvelopeOutputShape(), program_id: z.string().optional(), program: jsonRecordSchema().optional(), summary: jsonRecordSchema().optional(), as_of: z.string().optional(), snapshot_id: z.string().optional(), expires_at: z.string().nullable().optional(), facts: z.array(jsonRecordSchema()).optional(), windows: jsonRecordSchema().optional(), series: z.array(jsonRecordSchema()).optional(), payout_summary: jsonRecordSchema().nullable().optional(), views: z.array(jsonRecordSchema()).optional(), reports: jsonRecordSchema().optional(), response: jsonRecordSchema().optional(), last_increase_at: z.string().nullable().optional(), signals: jsonRecordSchema().optional(), label_details: z.array(jsonRecordSchema()).optional(), labels: z.array(z.string()).optional(), value_points: z.array(jsonRecordSchema()).optional(), map_points_omitted: z.number().int().optional(), meta: jsonRecordSchema().optional() },
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), program_id: z.string().optional(), program: jsonRecordSchema().optional(), summary: jsonRecordSchema().optional(), as_of: z.string().optional(), snapshot_id: z.string().optional(), expires_at: z.string().nullable().optional(), facts: z.array(jsonRecordSchema()).optional(), windows: jsonRecordSchema().optional(), series: z.array(jsonRecordSchema()).optional(), payout_summary: jsonRecordSchema().nullable().optional(), views: z.array(jsonRecordSchema()).optional(), reports: jsonRecordSchema().optional(), response: jsonRecordSchema().optional(), last_increase_at: z.string().nullable().optional(), signals: jsonRecordSchema().optional(), label_details: z.array(jsonRecordSchema()).optional(), labels: z.array(z.string()).optional(), value_points: z.array(jsonRecordSchema()).optional(), value_period: z.string().nullable().optional(), map_points_omitted: z.number().int().optional(), meta: jsonRecordSchema().optional() }),
         annotations: readOnlyAnnotations
     }, (args) => runTool("get_program_payouts", config, rateLimiter, async () => {
         assertProFeature(client, "program_payouts", "enabled");
@@ -598,7 +618,7 @@ export function createBbradarServer(client, config) {
     };
     registerTool("get_activity_rankings", {
         title: "Get Activity Ranking",
-        description: "One globally ranked server page of an Activity view, frozen at meta.as_of. Read get_activity_capabilities first: explicit period/basis/precision/sort/direction never fall back, and each tab only accepts its own inputs. tab: payouts (reported and tracked bases stay separate; proven_bounds desc = highest reported minimum, asc = lowest reported maximum, never an exact ranking; source totals can lag); value (fixed lifetime generosity and 90-day volume percentiles, no period; one label gives its shortlist); scope (recorded additions/removals/net, not inventory differences); rewards (net reward-range change, unknown % stays null); updates (active UTC days, change groups); reports (received counts; volume is not competition; all_time is the lifetime counter); response (resolved counts, last resolution, response time; time to bounty is award timing); status (first_seen/paused/resumed/left_listing/returned events); all_changes (chronological events; get_activity_change_detail for before/after). Event tabs use rolling 7d/30d/90d, not calendar months. launched_within applies to reports/response. Payout increases are observed counters, not payment dates. Reuse cursors only with identical inputs. For several signals at once, or with Web2/scope/competition/fee filters, use find_programs or find_hunt_targets.",
+        description: "One globally ranked server page of an Activity view, frozen at meta.as_of. Read get_activity_capabilities first: explicit period/basis/precision/sort/direction never fall back, and each tab only accepts its own inputs. tab: payouts (reported and tracked bases stay separate; proven_bounds desc = highest reported minimum, asc = lowest reported maximum, never an exact ranking; source totals can lag; average_paid is the platform's own current average payment, a range for HackerOne); value (advertised period 7d/30d/90d of report volume against lifetime payout per processed report; each row's value holds that period's count and percentile; Pays near top, No payouts seen and processed_received are 90d only; without period, labels or sort mean 90d and a bare read opens the advertised default, whose shortlist the page's labels name; one label gives its shortlist); scope (recorded additions/removals/net, not inventory differences); rewards (net reward-range change comparing native maxima, unknown % stays null; minimum_usd/maximum_usd are display conversions); updates (active UTC days, change groups); reports (received counts; volume is not competition; all_time is the lifetime counter); response (resolved counts, last resolution, response time with each provider's own label and window; time to bounty is award timing; durations default to fastest first); status (first_seen/paused/resumed/left_listing/returned events; facets count events per change_type and current_status); all_changes (chronological events; get_activity_change_detail for before/after). Event tabs use rolling 7d/30d/90d, not calendar months. launched_within applies to reports/response. Payout increases are observed counters, not payment dates. Reuse cursors only with identical inputs. For several signals at once, or with Web2/scope/competition/fee filters, use find_programs or find_hunt_targets.",
         inputSchema: z.object(activityParams).strict(),
         outputSchema: activityOutput,
         annotations: readOnlyAnnotations
@@ -609,14 +629,14 @@ export function createBbradarServer(client, config) {
     // Single-view aliases for the full profile; each schema exposes only the
     // inputs its view accepts and shares the ranking tool's request path.
     const activityDescriptions = {
-        value: "Discover programs with frozen within-platform value and report-volume percentiles. Generosity is lifetime; volume is 90 days. No period or launch-cohort input applies. Use a label-specific shortlist: Pays near top orders by realization, No payouts seen by received_90d (raw count with its basis; small cohorts remain eligible). Comparative ratio sorts use server percentiles; never recompute after filtering. Preserve label_details explanations and destinations. A counter increase is observed activity, not an individual payment. Map points are returned only with include_map.",
-        payouts: "Rank payouts using the same server calculation as BBRadar. Last 7 days and last 30 days are rolling windows. Explicit periods never fall back. For high or low payouts lately, use the same enabled tracked-30-day cohort, or separately label a native-90-day cohort. Reported and tracked bases stay separate. With proven_bounds, descending is Highest reported minimum using lower bounds; ascending is Lowest reported maximum using upper bounds. Neither claims an exact ranking. Source totals can be delayed, including Immunefi.",
+        value: "Discover programs with frozen within-platform value and report-volume percentiles. Generosity is lifetime payout per processed report; volume covers the selected period: 7d, 30d or 90d, each only when get_activity_capabilities advertises it. Each row's value holds that period's received count, basis and percentile; signals keep the lifetime and 90-day figures. Without period, naming labels or sort means 90d, and a bare read opens the advertised default, which may be a shortlist named in the page's labels. No launch-cohort input applies. High value, Popular and Low per report exist per period; Pays near top (orders by realization), No payouts seen (orders by received_90d, raw count with its basis; small cohorts remain eligible) and processed_received are 90d only. Comparative ratio sorts use server percentiles; never recompute after filtering. Preserve label_details explanations and destinations. A counter increase is observed activity, not an individual payment. Map points are returned only with include_map.",
+        payouts: "Rank payouts using the same server calculation as BBRadar. Last 7 days and last 30 days are rolling windows. Explicit periods never fall back. For high or low payouts lately, use the same enabled tracked-30-day cohort, or separately label a native-90-day cohort. Reported and tracked bases stay separate. With proven_bounds, descending is Highest reported minimum using lower bounds; ascending is Lowest reported maximum using upper bounds. Neither claims an exact ranking. Source totals can be delayed, including Immunefi. Rows also carry average_paid, the platform's own current average payment with its source_label, period, native currency and USD conversion (HackerOne publishes a 45th-55th percentile range); it is the same in every period, and sort=average_paid ranks it where advertised.",
         scope: "Rank recorded scope additions, removals, net movement or largest update; not differences between inventory totals. Periods are rolling 7, 30 or 90 days, not calendar months.",
-        rewards: "Rank comparable net reward-range changes over rolling 7, 30 or 90 days. Unknown change percentages remain null.",
+        rewards: "Rank comparable net reward-range changes over rolling 7, 30 or 90 days. The change percentage compares native maxima; unknown percentages remain null. before/after keep native amounts and add minimum_usd/maximum_usd at the version's current quotes for display (null without a quote).",
         updates: "Rank active UTC days and recorded change groups over rolling periods. Baselines and internal corrections are excluded.",
         reports: "Rank received report counts. Each program uses measured lifetime-counter growth where available, otherwise its supported native period. All-time is the current lifetime counter. Previous and change compare like-for-like. Report volume is not competition. Launch cohorts use the canonical launch date; amounts are not reports since launch.",
-        response: "Rank resolved counter growth or current lifetime counters, last resolution, response duration or time to bounty. Keep the provider's definition: time to bounty is award timing, not payment settlement. Period applies only to resolved counts.",
-        status: "Read distinct First seen, Paused, Resumed, Left listing and Returned events. Event type and current status are separate filters; never merge events from one program.",
+        response: "Rank resolved counter growth or current lifetime counters, last resolution, response duration or time to bounty. Each cell keeps its provider's definition, label and window (for example HackerOne first response over 90 days, YesWeHack's 6-month band, Bugcrowd's 75% validated time); first_response_precision says whether a time is exact, a band bound or approximate. Time to bounty is award timing, not payment settlement. Durations sort fastest first unless a direction is given. Period applies only to resolved counts; use only advertised periods.",
+        status: "Read distinct First seen, Paused, Resumed, Left listing and Returned events. Event type and current status are separate filters; never merge events from one program. facets count events per change_type and current_status for the period and filters, each counted without its own selection; offer only options with counts.",
         all_changes: "Read chronological semantic program changes with event IDs. Fetch get_activity_change_detail lazily for before/after items, including eligible events for programs that left the catalog. Separate events stay separate."
     };
     for (const tab of ACTIVITY_TABS) {
@@ -635,7 +655,7 @@ export function createBbradarServer(client, config) {
         title: "Get Activity Change Detail",
         description: "Read one bounded page of recorded before/after items for an exact Activity event ID in its source snapshot. Pass meta.snapshot_id from the Activity page. Retained eligible events may describe programs that have left the catalog. Reuse an opaque cursor only with the same event, snapshot and limit.",
         inputSchema: z.object({ event_id: z.string().min(1).max(128), snapshot: activitySnapshotSchema.describe("meta.snapshot_id from the Activity page that supplied this event."), cursor: opaqueCursorSchema.optional(), limit: proLimitSchema.default(50) }).strict(),
-        outputSchema: { ...apiEnvelopeOutputShape(), change: jsonRecordSchema().optional(), items: z.array(jsonRecordSchema()).optional(), meta: jsonRecordSchema().optional() }, annotations: readOnlyAnnotations
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), change: jsonRecordSchema().optional(), items: z.array(jsonRecordSchema()).optional(), meta: jsonRecordSchema().optional() }), annotations: readOnlyAnnotations
     }, (args) => runTool("get_activity_change_detail", config, rateLimiter, async () => {
         assertProFeature(client, "activity_event_detail", "enabled");
         return proPage(await client.getActivityChangeDetail(args.event_id, toQuery({ snapshot: args.snapshot, cursor: args.cursor, limit: args.limit })), "items");
@@ -660,7 +680,7 @@ export function createBbradarServer(client, config) {
         title: "Get History Change Detail",
         description: "Fetch one semantic History change's paginated before/after items only when needed.",
         inputSchema: { change_id: z.string().min(1).max(128), cursor: opaqueCursorSchema.optional(), limit: proLimitSchema.default(50) },
-        outputSchema: { ...apiEnvelopeOutputShape(), change: jsonRecordSchema().optional(), items: z.array(jsonRecordSchema()).optional(), meta: jsonRecordSchema().optional() }, annotations: readOnlyAnnotations
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), change: jsonRecordSchema().optional(), items: z.array(jsonRecordSchema()).optional(), meta: jsonRecordSchema().optional() }), annotations: readOnlyAnnotations
     }, (args) => runTool("get_history_change_detail", config, rateLimiter, async () => {
         assertProFeature(client, "history_change_detail");
         assertHistoryCapture(client);
@@ -680,7 +700,7 @@ export function createBbradarServer(client, config) {
         title: "Get Exact Program Activity",
         description: "Read the authoritative activity_summary for one exact program ID.",
         inputSchema: { program_id: programIdSchema },
-        outputSchema: { ...apiEnvelopeOutputShape(), program_id: z.string().optional(), activity_summary: jsonRecordSchema().optional() }, annotations: readOnlyAnnotations
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), program_id: z.string().optional(), activity_summary: jsonRecordSchema().optional() }), annotations: readOnlyAnnotations
     }, (args) => runTool("get_program_activity", config, rateLimiter, async () => {
         assertProFeature(client, "program_activity");
         return proPage(await client.getProgramActivity(args.program_id), "activity_summary");
@@ -787,7 +807,7 @@ export function createBbradarServer(client, 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.",
+        description: "Get one program by platform:handle program_id, handle, or human program name. Names are resolved automatically when unambiguous. A contest or Huntr challenge adds contest_awards: its final published award allocations (awarded_total and pool_amount as decimal strings in the contest's own currency token; currency null when the platform names none, as Huntr; never USD or a payment record), or null before a final result. A finished contest with a final result stays readable here by exact platform:handle, without an opportunity tag, although discovery and name resolution exclude ended contests.",
         inputSchema: {
             program_id: programIdentifierSchema
         },
@@ -918,6 +938,7 @@ export function createBbradarServer(client, config) {
             program_id: programIdentifierSchema,
             search: searchTextSchema.optional(),
             target_type: filterValueSchema().optional(),
+            language_tags: languageTagListSchema().describe("Keep targets with any requested language tag. Applied while paging; repeat with the returned next_offset."),
             min_target_score: z.number().int().min(0).max(100).optional(),
             target_opportunity_label: targetOpportunityLabelSchema.optional(),
             competition_risk: competitionRiskSchema.optional(),
@@ -1195,7 +1216,7 @@ export function createBbradarServer(client, config) {
             include_ineligible: z.boolean().default(false).describe("Include ineligible."),
             recent_changes_page_size: recentChangesPageSizeSchema.default(Math.min(MAX_RECENT_CHANGES, maxTargetChangesPageSize)),
             max_results: z.number().int().min(1).max(MAX_RECENT_CHANGES).default(10),
-            include_full_target_list: z.boolean().default(true).describe("Fetch the newest matching program's complete target list. Set false for the fastest cross-program discovery."),
+            include_full_target_list: z.boolean().default(true).describe("Fetch up to full_target_limit targets for the newest matching program. Check full_targets_has_more and continue with get_program_targets at full_targets_next_offset. Set false for the fastest cross-program discovery."),
             full_target_list_mode: targetListModeSchema.default("identifiers"),
             full_target_limit: z.number().int().min(1).max(MAX_TARGETS_PER_PROGRAM).default(MAX_TARGETS_PER_PROGRAM),
             full_list_include_out_of_scope: z.boolean().default(false),
@@ -1431,7 +1452,8 @@ export function createBbradarServer(client, config) {
             min_added_7d: z.number().int().min(0).optional(),
             max_pages: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
             max_results: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(10),
-            sort_by: z.union([programSortSchema.removeDefault(), activityCatalogSortSchema]).optional(),
+            // One flat enum, as clients have always seen it; a union would advertise anyOf.
+            sort_by: z.enum([...programSortSchema.removeDefault().options, ...activityCatalogSortSchema.options]).optional(),
             include_target_samples: z.boolean().default(false),
             target_sample_programs: z.number().int().min(0).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
             target_sample_size: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(5),
@@ -2389,6 +2411,7 @@ function bbradarGuide(topic, profile, client) {
         { user_goal: "program payouts, recent reports, response times or Activity rankings", first_tool: "get_activity_capabilities", arguments: {}, then: "Choose an enabled period, sort and direction, then call get_activity_rankings with that tab for one server-ranked page. Do not approximate by paging or re-ranking the catalog." },
         { user_goal: "programs with recent payouts and new scope that also match Web2, competition or fee criteria", first_tool: "find_hunt_targets", arguments: { payout_period: "30d", payout_positive: true, scope_period: "30d", scope_added_min: 1, surface_mode: "web2", free_submission_only: true, ranking_mode: "lowest_competition" }, then: "Use find_programs with the same Activity inputs and competition_risks for program-only results; continue with scan.next_cursor." },
         { user_goal: "payout and report facts for one exact program", first_tool: "get_program_payouts", arguments: { program_id: "Platform:handle" } },
+        { user_goal: "final award results of a finished contest or Huntr challenge", first_tool: "get_program", arguments: { program_id: "Platform:handle" }, then: "Read contest_awards: awarded_total and pool_amount are decimal strings in the contest's own token (currency null when the platform names none); null means no final result yet." },
         { user_goal: "semantic program change history", first_tool: "get_program_history", arguments: { program_id: "Platform:handle" }, then: "Fetch get_history_change_detail only for a selected change." },
         { user_goal: "most active programs in a date range", first_tool: "get_analytics_program_activity", arguments: {}, then: "Use this server-side ranking rather than sampling the program catalog." },
         { user_goal: "exact recorded activity for one program", first_tool: "get_program_activity", arguments: { program_id: "Platform:handle" } },
@@ -2502,6 +2525,7 @@ function bbradarGuide(topic, profile, client) {
         decision_tree: decisionTree.filter((entry) => toolAvailableForContract(client, String(entry.first_tool)) &&
             (topic === "start" || guideEntryMatchesTopic(topic, entry))),
         filters,
+        activity_catalog: activityCatalogGuidance,
         advanced_tools: advancedTools,
         examples
     };
@@ -2537,6 +2561,7 @@ function coreBbradarGuide(topic, client) {
         { user_goal: "program payouts, recent reports, response times or Activity rankings", first_tool: "get_activity_capabilities", arguments: {}, then: "Read supported view combinations and call get_activity_rankings with that tab. Use get_activity_change_detail lazily for a selected Activity event." },
         { user_goal: "programs with recent payouts and new scope that also match Web2, competition or fee criteria", first_tool: "find_hunt_targets", arguments: { payout_period: "30d", payout_positive: true, scope_period: "30d", scope_added_min: 1, surface_mode: "web2", free_submission_only: true, ranking_mode: "lowest_competition" } },
         { user_goal: "payout and report facts for one exact program", first_tool: "get_program_payouts", arguments: { program_id: "Platform:handle" } },
+        { user_goal: "final award results of a finished contest or Huntr challenge", first_tool: "get_program", arguments: { program_id: "Platform:handle" }, then: "Read contest_awards in the contest's own token; null means no final result yet." },
         { user_goal: "semantic program change history", first_tool: "get_program_history", arguments: { program_id: "Platform:handle" }, then: "Fetch change detail only when needed." },
         { user_goal: "most active programs", first_tool: "get_analytics_program_activity", arguments: {} },
         { user_goal: "exact recorded activity", first_tool: "get_program_activity", arguments: { program_id: "Platform:handle" } },
@@ -2580,7 +2605,8 @@ function coreBbradarGuide(topic, client) {
         ],
         decision_tree: decisionTree.filter((entry) => toolAvailableForContract(client, String(entry.first_tool)) &&
             (topic === "start" || guideEntryMatchesTopic(topic, entry))),
-        available_tools: [...CORE_TOOL_NAMES].filter((name) => toolAvailableForContract(client, name))
+        available_tools: [...CORE_TOOL_NAMES].filter((name) => toolAvailableForContract(client, name)),
+        activity_catalog: activityCatalogGuidance
     };
 }
 function toolAvailableForContract(client, toolName) {
@@ -3590,29 +3616,14 @@ async function runResolvedProgramAction(client, config, programId, input) {
         });
     }
     if (input.action === "targets") {
-        const api = await client.getProgramTargets(programId);
-        const data = readObject(api.data);
-        const rawTargets = readArray(data?.targets);
-        const sanitizedTargets = rawTargets
-            .map(sanitizeTarget)
-            .filter((target) => targetHasAllowedScope(target, {
+        return getProgramTargetsPayload(client, {
+            target_type: input.target_type,
+            language_tags: input.language_tags,
             include_out_of_scope: input.include_out_of_scope,
             include_ineligible: input.include_ineligible,
-            strict_scope_filter: true
-        }));
-        const targets = sanitizedTargets.slice(0, input.max_targets);
-        return withApiMetadata(api, {
-            program_id: programId,
-            targets: formatTargetList(targets, input.target_list_mode),
-            meta: {
-                limit: input.max_targets,
-                output_mode: input.target_list_mode,
-                total_active_targets: rawTargets.length,
-                total_after_filters: sanitizedTargets.length,
-                returned: targets.length,
-                has_more: sanitizedTargets.length > targets.length
-            }
-        });
+            strict_scope_filter: true,
+            offset: 0, limit: input.max_targets, output_mode: input.target_list_mode
+        }, programId);
     }
     return checkProgramNewTargets(client, config, {
         program_id: programId,
@@ -4738,30 +4749,18 @@ async function getLatestAddedTargets(client, config, input) {
         .map((change) => readObject(change.target))
         .filter((target) => target !== undefined);
     let fullTargets = [];
-    let totalActiveTargets;
-    let totalAfterFilters;
+    let fullTargetsMeta;
     if (input.include_full_target_list && programId) {
-        const targetsApi = await client.getProgramTargets(programId);
-        const targetsData = readObject(targetsApi.data);
-        const rawTargets = readArray(targetsData?.targets);
-        fullTargets = rawTargets
-            .map(sanitizeTarget)
-            .filter((target) => targetHasAllowedScope(target, {
+        const payload = await getProgramTargetsPayload(client, {
             include_out_of_scope: input.full_list_include_out_of_scope,
             include_ineligible: input.full_list_include_ineligible,
-            strict_scope_filter: false
-        }));
-        totalActiveTargets = rawTargets.length;
-        totalAfterFilters = fullTargets.length;
-        sourceRequests.push({
-            source: "program_targets",
-            program_id: programId,
-            request_id: targetsApi.requestId,
-            upstream_request_id: targetsApi.upstreamRequestId,
-            ...apiSourceMetadata(targetsApi)
-        });
+            strict_scope_filter: false,
+            offset: 0, limit: input.full_target_limit, output_mode: input.full_target_list_mode
+        }, programId);
+        fullTargets = readArray(payload.targets);
+        fullTargetsMeta = readObject(payload.meta);
+        sourceRequests.push(...readArray(payload.source_requests).map(readObject).filter((request) => request !== undefined));
     }
-    const limitedFullTargets = fullTargets.slice(0, input.full_target_limit);
     return stripUndefined({
         request_id: randomUUID(),
         source_requests: sourceRequests,
@@ -4770,17 +4769,19 @@ async function getLatestAddedTargets(client, config, input) {
         program,
         matches,
         new_targets: formatTargetList(latestNewTargets, input.full_target_list_mode),
-        full_targets: input.include_full_target_list ? formatTargetList(limitedFullTargets, input.full_target_list_mode) : undefined,
+        full_targets: input.include_full_target_list ? fullTargets : undefined,
         meta: stripUndefined({
             recent_changes_scanned: changes.length,
             matching_changes_scanned: matchingChanges.length,
             matches_returned: matches.length,
             matches_has_more: matches.length < matchingChanges.length,
             new_targets_returned: formatTargetList(latestNewTargets, input.full_target_list_mode).length,
-            full_targets_total_active: totalActiveTargets,
-            full_targets_total_after_filters: totalAfterFilters,
-            full_targets_returned: input.include_full_target_list ? formatTargetList(limitedFullTargets, input.full_target_list_mode).length : undefined,
-            full_targets_has_more: input.include_full_target_list ? limitedFullTargets.length < fullTargets.length : undefined
+            full_targets_total_active: fullTargetsMeta?.total_active_targets,
+            full_targets_total_after_filters: fullTargetsMeta?.total_after_filters,
+            full_targets_returned: input.include_full_target_list ? fullTargets.length : undefined,
+            full_targets_has_more: fullTargetsMeta?.has_more,
+            full_targets_next_offset: fullTargetsMeta?.next_offset,
+            full_targets_possibly_incomplete: fullTargetsMeta?.possibly_incomplete
         })
     });
 }
@@ -4818,15 +4819,21 @@ function latestAddedProgramMatches(change, input, platformFilters) {
     return true;
 }
 async function getProgramTargetsPayload(client, input, programId) {
-    const pageSize = client.endpointNumber("program_targets", "max_page_size", MAX_TARGETS_PER_PROGRAM);
+    const maxPageSize = 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 languageTags = new Set((input.language_tags ?? []).map(normalizeTag));
+    const directOffsetPaging = languageTags.size === 0 && (!input.include_ineligible || (!input.strict_scope_filter && input.include_out_of_scope));
+    // Bound direct reads to the requested prefix. Local post-filters still need
+    // full pages to find sparse matches. Offsets remain filtered row offsets,
+    // independent of the page size used by an earlier call.
+    const pageSize = directOffsetPaging ? Math.min(maxPageSize, input.offset + input.limit) : maxPageSize;
     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;
+    const sourceRequests = [];
     let upstreamMeta;
     let upstreamHasMore = false;
     do {
@@ -4840,11 +4847,15 @@ async function getProgramTargetsPayload(client, input, programId) {
             page,
             page_size: pageSize
         });
+        sourceRequests.push({ source: "program_targets", program_id: programId, page,
+            request_id: api.requestId, upstream_request_id: api.upstreamRequestId, ...apiSourceMetadata(api) });
         const data = readObject(api.data);
         upstreamMeta = readObject(data?.meta);
         for (const target of readArray(data?.targets).map(sanitizeTarget)) {
             if (!targetHasAllowedScope(target, input))
                 continue;
+            if (languageTags.size > 0 && !arraysIntersectNormalized(languageTags, readStringArrayField(target, "language_tags")))
+                continue;
             if (matchedSeen >= input.offset && collected.length < input.limit)
                 collected.push(target);
             matchedSeen += 1;
@@ -4862,8 +4873,10 @@ async function getProgramTargetsPayload(client, input, programId) {
         throw new Error("No program target response was collected.");
     }
     const targets = collected;
+    const hasMore = upstreamHasMore || matchedSeen > input.offset + targets.length;
     return withApiMetadata(api, {
         program_id: programId,
+        source_requests: sourceRequests,
         targets: formatTargetList(targets, input.output_mode),
         meta: {
             offset: input.offset,
@@ -4872,7 +4885,8 @@ async function getProgramTargetsPayload(client, input, programId) {
             total_active_targets: readNumber(upstreamMeta?.total) ?? matchedSeen,
             total_after_filters: upstreamHasMore ? undefined : matchedSeen,
             returned: targets.length,
-            has_more: upstreamHasMore || matchedSeen > input.offset + targets.length,
+            has_more: hasMore,
+            next_offset: hasMore ? input.offset + targets.length : undefined,
             upstream_has_more: upstreamHasMore,
             possibly_incomplete: upstreamHasMore,
             upstream_pages_fetched: page - firstPage,
@@ -4885,9 +4899,16 @@ async function getProgramTargetsPayload(client, input, programId) {
     });
 }
 async function getProgramTargetsExportFallbackPayload(client, input, programId) {
+    if (input.search || input.target_type || input.min_target_score !== undefined
+        || input.target_opportunity_label || input.competition_risk) {
+        throw new Error("The per-program targets endpoint is unavailable. Its search, type and intelligence filters cannot be preserved by the export fallback; the requested filters were not discarded.");
+    }
     const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, programId);
-    const sanitizedTargets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, input));
+    const languageTags = new Set((input.language_tags ?? []).map(normalizeTag));
+    const sanitizedTargets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, input)
+        && (languageTags.size === 0 || arraysIntersectNormalized(languageTags, readStringArrayField(target, "language_tags"))));
     const targets = sanitizedTargets.slice(input.offset, input.offset + input.limit);
+    const hasMore = input.offset + targets.length < sanitizedTargets.length;
     return stripUndefined({
         request_id: exportLookup.requestId,
         upstream_request_id: exportLookup.upstreamRequestId,
@@ -4901,10 +4922,10 @@ async function getProgramTargetsExportFallbackPayload(client, input, programId)
             offset: input.offset,
             limit: input.limit,
             output_mode: input.output_mode,
-            total_active_targets: exportLookup.rawTargets.length,
-            total_after_filters: sanitizedTargets.length,
+            ...fallbackTargetCoverage(exportLookup, sanitizedTargets.length),
             returned: targets.length,
-            has_more: input.offset + input.limit < sanitizedTargets.length,
+            has_more: hasMore || exportLookup.coverage?.possibly_incomplete === true,
+            next_offset: hasMore ? input.offset + targets.length : undefined,
             target_source: exportLookup.source,
             target_list_unavailable: exportLookup.unavailable,
             fallback_error: exportLookup.error
@@ -4933,6 +4954,7 @@ async function fetchProgramTargetsWithEndpointFallback(client, programId) {
             })),
             source: "program_targets",
             rawTargets,
+            coverage: targetPageCoverage(data, rawTargets.length, rawTargets.length),
             sourceRequests: [
                 {
                     source: "program_targets",
@@ -5032,14 +5054,21 @@ function cacheTtlMsFromDiagnostics(cache) {
 }
 async function fetchProgramTargetsFromExportFallback(client, programId) {
     try {
+        const limit = Math.min(MAX_TARGET_EXPORT, client.endpointNumber("target_export", "max_targets", MAX_TARGET_EXPORT));
         const api = await client.exportTargets({
             program_ids: [programId],
             include_out_of_scope: true,
             include_ineligible: true,
             format: "json",
-            limit: MAX_TARGET_EXPORT
+            limit
         });
         const rawTargets = readExportTargetRows(api.data).map((row) => sanitizeTarget(readObject(row)?.target ?? row));
+        const data = readObject(api.data);
+        const coverage = targetPageCoverage({ meta: {
+                ...readObject(data?.meta),
+                // A full capped export is not proof that the inventory ends here.
+                has_more: readObject(data?.meta)?.has_more === true || rawTargets.length >= limit
+            } }, rawTargets.length, rawTargets.length);
         return {
             requestId: api.requestId,
             upstreamRequestId: api.upstreamRequestId,
@@ -5053,6 +5082,7 @@ async function fetchProgramTargetsFromExportFallback(client, programId) {
             })),
             source: "target_export",
             rawTargets,
+            coverage,
             sourceRequests: [
                 {
                     source: "target_export",
@@ -5313,8 +5343,7 @@ async function getProgramScopeSummary(client, config, input) {
         program: formatProgram(lookup.program, "compact"),
         scope: buildTargetScopeSummary(targets, input.target_list_mode, input.group_limit, input.include_out_of_scope, input.include_ineligible),
         meta: {
-            total_active_targets: rawTargets.length,
-            total_after_filters: targets.length,
+            ...targetPageCoverage(targetsData, rawTargets.length, targets.length),
             target_list_mode: input.target_list_mode,
             group_limit: input.group_limit,
             target_source: "program_targets",
@@ -5339,8 +5368,7 @@ async function getProgramScopeSummaryFromIndexFallback(client, indexFallback, in
         program: formatProgram(indexFallback.program, "compact"),
         scope: buildTargetScopeSummary(targets, input.target_list_mode, input.group_limit, input.include_out_of_scope, input.include_ineligible),
         meta: stripUndefined({
-            total_active_targets: exportLookup.rawTargets.length,
-            total_after_filters: targets.length,
+            ...fallbackTargetCoverage(exportLookup, targets.length),
             target_list_mode: input.target_list_mode,
             group_limit: input.group_limit,
             target_source: exportLookup.source,
@@ -5376,8 +5404,7 @@ async function getProgramTargetBreakdown(client, config, input) {
             groups: readObject(scope.groups)
         },
         meta: {
-            total_active_targets: rawTargets.length,
-            total_after_filters: targets.length,
+            ...targetPageCoverage(targetsData, rawTargets.length, targets.length),
             target_list_mode: input.target_list_mode,
             group_limit: input.group_limit,
             target_source: "program_targets",
@@ -5385,6 +5412,32 @@ async function getProgramTargetBreakdown(client, config, input) {
         }
     });
 }
+function targetPageCoverage(data, rows, filteredRows) {
+    const meta = readObject(data?.meta);
+    const total = numberField(meta, "total");
+    const incomplete = meta?.has_more === true || (numberField(meta, "total_pages") ?? 1) > 1
+        || (total !== undefined && total > rows);
+    return stripUndefined({
+        total_active_targets: total ?? (incomplete ? undefined : rows),
+        total_after_filters: incomplete ? undefined : filteredRows,
+        targets_scanned: rows,
+        matching_targets_scanned: filteredRows,
+        possibly_incomplete: incomplete,
+        count_scope: incomplete ? "sampled_target_page" : "complete_target_inventory"
+    });
+}
+function fallbackTargetCoverage(lookup, filteredRows) {
+    const incomplete = lookup.unavailable || lookup.coverage?.possibly_incomplete === true;
+    return stripUndefined({
+        ...lookup.coverage,
+        total_active_targets: lookup.unavailable ? undefined : lookup.coverage?.total_active_targets ?? (incomplete ? undefined : lookup.rawTargets.length),
+        total_after_filters: incomplete ? undefined : filteredRows,
+        targets_scanned: lookup.rawTargets.length,
+        matching_targets_scanned: filteredRows,
+        possibly_incomplete: incomplete,
+        count_scope: lookup.unavailable ? "unavailable" : incomplete ? "sampled_target_page" : "complete_target_inventory"
+    });
+}
 async function getProgramTargetBreakdownFromIndexFallback(client, indexFallback, input) {
     const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, input.program_id);
     const targets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, {
@@ -5411,8 +5464,7 @@ async function getProgramTargetBreakdownFromIndexFallback(client, indexFallback,
             groups: readObject(scope.groups)
         },
         meta: stripUndefined({
-            total_active_targets: exportLookup.rawTargets.length,
-            total_after_filters: targets.length,
+            ...fallbackTargetCoverage(exportLookup, targets.length),
             target_list_mode: input.target_list_mode,
             group_limit: input.group_limit,
             target_source: exportLookup.source,
@@ -6255,6 +6307,7 @@ function compactProgram(program) {
         competition_risk: stringField(program, "competition_risk"),
         competition_risk_reason: stringField(program, "competition_risk_reason"),
         submission_cost: program.submission_cost,
+        contest_awards: program.contest_awards,
         payout_summary: program.payout_summary,
         activity: program.activity,
         activity_summary: program.activity_summary,
@@ -6820,6 +6873,18 @@ function clampLimit(name, value, max, warnings) {
 // server order, so a larger pool lets ranking_mode choose among more of them.
 const HUNT_SERVER_POOL = 100;
 async function findHuntTargets(client, config, input, activity = {}) {
+    const huntStartedAt = Date.now();
+    const phaseTiming = {};
+    const runStage = async (phase, timeoutMs, callback) => {
+        const startedAt = Date.now();
+        try {
+            return await client.withRequestTimeout(timeoutMs, callback);
+        }
+        finally {
+            phaseTiming[phase] = Date.now() - startedAt;
+        }
+    };
+    validateActivityCatalogInput(activity);
     const warnings = [];
     const errors = [];
     const selfHostedOnly = isSelfHostedOnlyPlatformSelection(input.platforms);
@@ -6885,22 +6950,28 @@ async function findHuntTargets(client, config, input, activity = {}) {
         warnings.push(`Recent target-change queries were reduced from ${desiredRecentChangeQueries.length} to ${recentChangeQueries.length} to preserve the upstream request budget.`);
     }
     const serverFiltered = hasActivityCatalogInput(activity);
+    // Catalog discovery and optional changes share at most 60% of the tool
+    // deadline. Keep at least 30% for exact targets and 10% for the response.
     const [programPayload, recentResult] = await Promise.all([
-        serverFiltered
+        runStage("program_discovery_ms", Math.floor(config.requestTimeoutMs * 0.6), () => serverFiltered
             ? findFilteredServerPrograms(client, config, {
                 ...programInput, ...activity, opportunity_levels: [], sort_by: activity.sort_by, sort_direction: activity.sort_direction,
                 platforms: input.platforms, tags: input.tags, updated_since: input.updated_since, vdp_mode: "exclude", include_target_samples: false
             }, {
                 ...programInput, platforms: [], tags: [], vdp_mode: "include", updated_since: undefined,
                 max_pages: programRequestBudget, upstream_request_budget: programRequestBudget
-            }, HUNT_SERVER_POOL)
-            : findPrograms(client, config, programInput),
+            }, HUNT_SERVER_POOL, true)
+            : findPrograms(client, config, programInput, {
+                allowPartialTimeout: true, excludeVdpUpstream: true
+            })),
         recentChangesEnabled
-            ? fetchHuntRecentChanges(client, config, input, recentChangeQueries)
+            ? runStage("recent_changes_ms", Math.floor(config.requestTimeoutMs * 0.3), () => fetchHuntRecentChanges(client, config, input, recentChangeQueries))
             : Promise.resolve({ changes: [], sourceRequests: [], requestsUsed: 0, errors: [] })
     ]);
+    client.throwIfRequestAborted();
     const programWarnings = readArray(programPayload.warnings).filter((warning) => typeof warning === "string");
     warnings.push(...programWarnings);
+    errors.push(...readArray(programPayload.errors).map(readObject).filter((error) => error !== undefined));
     errors.push(...recentResult.errors);
     const programBudget = readObject(programPayload.upstream_budget);
     const programRequestsUsed = readNumber(programBudget?.used) ?? 0;
@@ -6919,8 +6990,12 @@ async function findHuntTargets(client, config, input, activity = {}) {
     const finalistEntries = preliminaryRankedEntries
         .slice(0, sampledProgramCount)
         .map((entry) => entry.entry);
-    const targetResult = await collectHuntTargetSamples(client, finalistEntries, input);
+    const targetResult = await runStage("target_sampling_ms", Math.floor(config.requestTimeoutMs * 0.9) - (Date.now() - huntStartedAt), () => collectHuntTargetSamples(client, finalistEntries, input));
+    client.throwIfRequestAborted();
     errors.push(...targetResult.errors);
+    if (errors.length > 0) {
+        warnings.push("Some discovery or enrichment reads failed or reached their time budget. Returned matches preserve the requested filters; missing target samples or change evidence are unavailable, not confirmed absent. Report the incomplete coverage without narrowing platforms or relaxing thresholds.");
+    }
     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.`);
     }
@@ -6934,6 +7009,10 @@ async function findHuntTargets(client, config, input, activity = {}) {
     }));
     const targetRequestsUsed = targetResult.requestsUsed;
     const totalRequestsUsed = programRequestsUsed + recentResult.requestsUsed + targetRequestsUsed;
+    const coverageIncomplete = errors.length > 0
+        || readObject(programPayload.ranking_scope)?.possibly_incomplete === true
+        || readObject(programPayload.scan)?.complete === false
+        || sampledProgramCount < Math.min(input.max_results, programEntries.length);
     return stripUndefined({
         request_id: randomUUID(),
         fetched_at: new Date().toISOString(),
@@ -6985,7 +7064,10 @@ async function findHuntTargets(client, config, input, activity = {}) {
         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."
+            coverage_incomplete: coverageIncomplete,
+            instruction: coverageIncomplete
+                ? "Use the bounded matches and report warnings and incomplete coverage. Preserve the user's periods, thresholds and platform scope; do not infer supported platforms from a sampled recent-change feed."
+                : "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: {
@@ -6998,7 +7080,8 @@ async function findHuntTargets(client, config, input, activity = {}) {
             model_round_trips_expected: 1,
             parallel_recent_change_fetch: recentChangeQueries.length > 0,
             bulk_resource_links_suppressed: true,
-            partial_success: errors.length > 0
+            partial_success: errors.length > 0,
+            phase_timing: phaseTiming
         }
     });
 }
@@ -7738,6 +7821,7 @@ function hasActivityCatalogInput(input) {
 }
 /** Validates and builds one server-ordered catalog query; nothing is sent. */
 function serverCatalogQuery(client, input) {
+    validateActivityCatalogInput(input);
     const levels = Array.isArray(input.opportunity_levels) ? input.opportunity_levels : [];
     if (levels.length > 1)
         throw new Error("Combined Activity queries accept at most one opportunity tier; separate tier pages cannot form a global ranking.");
@@ -7757,6 +7841,17 @@ function serverCatalogQuery(client, input) {
             vdp_mode: input.vdp_mode, snapshot: input.snapshot }
     };
 }
+// Durations rank fastest first when no direction is given, as the API does. The
+// direction the server reports it applied wins, so an older API is labelled
+// correctly too.
+const ASCENDING_FIRST_SORTS = new Set(["first_response", "time_to_bounty"]);
+function appliedSortDirection(input, served) {
+    if (served === "asc" || served === "desc")
+        return served;
+    if (input.sort_direction === "asc" || input.sort_direction === "desc")
+        return input.sort_direction;
+    return ASCENDING_FIRST_SORTS.has(String(input.sort_by ?? "updated")) ? "asc" : "desc";
+}
 function readServerCatalogPage(client, catalog, page, pageSize, snapshot) {
     const query = toQuery({ ...catalog.query, snapshot, page, page_size: pageSize });
     return catalog.level ? client.getOpportunities(catalog.level, query) : client.listPrograms(query);
@@ -7773,7 +7868,7 @@ async function findServerCatalogPrograms(client, config, input) {
     const mode = input.output_mode === "full" ? "full" : "compact";
     return withApiMetadata(api, {
         programs: readArray(data?.programs).map((program) => formatProgram(sanitizeProgram(program, config.webBaseUrl), mode)),
-        ranking_scope: { mode: "server", sort_by: input.sort_by ?? "updated", sort_direction: input.sort_direction ?? "desc" },
+        ranking_scope: { mode: "server", sort_by: input.sort_by ?? "updated", sort_direction: appliedSortDirection(input, readObject(data?.meta)?.sort_direction) },
         meta: sanitizeJson(data?.meta)
     });
 }
@@ -7817,6 +7912,7 @@ async function scanServerCatalog(client, config, input, local, limits) {
     const start = cursorValue ? decodeScanCursor(cursorValue, fingerprint, pageSize)
         : { v: 1, p: Number(input.page ?? 1), k: 0, s: pageSize, f: fingerprint, a: undefined, t: undefined };
     const sourceRequests = [];
+    const errors = [];
     let matches = [];
     let seen = new Set();
     let nextPage = start.p;
@@ -7825,6 +7921,7 @@ async function scanServerCatalog(client, config, input, local, limits) {
     let token = start.t ?? input.snapshot;
     let totalPages;
     let serverTotal;
+    let servedDirection;
     let rowsScanned = 0;
     let pagesRead = 0;
     let restarted = false;
@@ -7840,11 +7937,25 @@ async function scanServerCatalog(client, config, input, local, limits) {
         const needed = pagesRead === 0 ? 1 : Math.ceil((limits.maxResults - matches.length) / (rate * pageSize));
         const batch = Math.max(1, Math.min(allowance, needed, CATALOG_SCAN_PREFETCH));
         const pageToken = token;
-        const pages = await Promise.all(Array.from({ length: batch }, (_, index) => nextPage + index)
+        const batchStart = nextPage;
+        const pages = await Promise.allSettled(Array.from({ length: batch }, (_, index) => batchStart + index)
             .map(async (page) => ({ page, api: await readServerCatalogPage(client, catalog, page, pageSize, pageToken) })));
-        for (const { page, api } of pages) {
+        // Count all admitted reads, including a failed page or a prefetched page
+        // beyond a gap; only the contiguous successful prefix enters the ranking.
+        for (const result of pages) {
+            const noRequest = result.status === "fulfilled" ? result.value.api.cached || result.value.api.coalesced
+                : result.reason instanceof BBRadarApiError && (result.reason.cached || result.reason.coalesced);
+            limits.budget.remaining -= noRequest ? 0 : 1;
+        }
+        for (const [index, result] of pages.entries()) {
+            if (result.status === "rejected") {
+                if (!limits.allowPartialTimeout || pagesRead === 0 || !(result.reason instanceof BBRadarApiError) || result.reason.status !== 408)
+                    throw result.reason;
+                errors.push(apiOperationError(`program catalog page ${batchStart + index}`, result.reason));
+                break scan;
+            }
+            const { page, api } = result.value;
             pagesRead += 1;
-            limits.budget.remaining -= api.cached || api.coalesced ? 0 : 1;
             sourceRequests.push({ source: catalog.level ? `opportunities:${catalog.level}` : "programs", page, request_id: api.requestId,
                 upstream_request_id: api.upstreamRequestId, ...apiSourceMetadata(api) });
             const data = readObject(api.data);
@@ -7869,6 +7980,7 @@ async function scanServerCatalog(client, config, input, local, limits) {
             version ??= pageVersion;
             totalPages = readNumber(meta?.total_pages) ?? totalPages;
             serverTotal = readNumber(meta?.total) ?? serverTotal;
+            servedDirection = meta?.sort_direction ?? servedDirection;
             if (token !== undefined && typeof meta?.snapshot === "string")
                 token = meta.snapshot;
             const rows = readArray(data?.programs);
@@ -7900,10 +8012,11 @@ async function scanServerCatalog(client, config, input, local, limits) {
     return {
         candidates: matches,
         sourceRequests,
+        errors,
         scan: stripUndefined({
             order: "Server order; local filters only remove programs.",
             sort_by: input.sort_by ?? "updated",
-            sort_direction: input.sort_direction ?? "desc",
+            sort_direction: appliedSortDirection(input, servedDirection),
             local_filters: localFilters.length > 0 ? localFilters : undefined,
             server_matches: serverTotal,
             rows_scanned: rowsScanned,
@@ -7913,17 +8026,20 @@ async function scanServerCatalog(client, config, input, local, limits) {
                 ? encodeScanCursor({ v: 1, p: resume.p, k: resume.k, s: pageSize, f: fingerprint, a: version, t: typeof token === "string" ? token : undefined })
                 : undefined,
             activity_snapshot_id: version,
-            restarted_on_new_activity_version: restarted || undefined
+            restarted_on_new_activity_version: restarted || undefined,
+            deadline_reached: errors.length > 0 || undefined
         })
     };
 }
 /** find_programs with server Activity filters plus local filters or target samples. */
-async function findFilteredServerPrograms(client, config, input, local, maxResults = local.max_results) {
+async function findFilteredServerPrograms(client, config, input, local, maxResults = local.max_results, allowPartialTimeout = false) {
     const normalized = normalizeFindProgramsInput(local);
     const warnings = normalized.warnings;
     local = normalized.input;
     const budget = { initial: local.upstream_request_budget, remaining: local.upstream_request_budget };
-    const result = await scanServerCatalog(client, config, input, local, { maxResults, maxPages: local.max_pages, budget });
+    const result = await scanServerCatalog(client, config, input, local, { maxResults, maxPages: local.max_pages, budget, allowPartialTimeout });
+    if (result.errors.length > 0)
+        warnings.push("Program discovery reached its time budget; ranking covers only the completed server-ordered prefix.");
     if (result.scan.complete !== true) {
         warnings.push("More server pages remain; scan.next_cursor continues in the same order.");
     }
@@ -7936,6 +8052,7 @@ async function findFilteredServerPrograms(client, config, input, local, maxResul
         request_id: randomUUID(),
         fetched_at: new Date().toISOString(),
         source_requests: result.sourceRequests,
+        errors: result.errors.length > 0 ? result.errors : undefined,
         warnings: warnings.length > 0 ? warnings : undefined,
         upstream_budget: { used: budget.initial - budget.remaining, remaining: budget.remaining },
         ranking_scope: { mode: "server_filtered", sort_by: result.scan.sort_by, sort_direction: result.scan.sort_direction, complete: result.scan.complete },
@@ -7950,10 +8067,11 @@ function programHasNoSubmissionFee(program) {
     const amount = numberField(cost, "amount");
     return amount === undefined || (amount === 0 && (numberField(cost, "maximum_amount") ?? 0) === 0);
 }
-async function findPrograms(client, config, input) {
+async function findPrograms(client, config, input, execution = {}) {
     const normalized = normalizeFindProgramsInput(input);
     const warnings = normalized.warnings;
     input = normalized.input;
+    const errors = [];
     const budget = {
         initial: input.upstream_request_budget,
         remaining: input.upstream_request_budget
@@ -7970,11 +8088,13 @@ async function findPrograms(client, config, input) {
         platforms: input.platforms,
         tags: upstreamTags,
         program_kind: input.program_kind ?? (input.contest_like ? "contest" : undefined),
+        vdp_mode: execution.excludeVdpUpstream && input.vdp_mode === "exclude" ? "exclude" : undefined,
         updated_since: input.updated_since,
         opportunity_levels: input.opportunity_levels,
         max_pages: input.max_pages,
         budget,
-        warnings
+        warnings,
+        partialTimeoutErrors: execution.allowPartialTimeout ? errors : undefined
     });
     const filteredCandidates = collected.programs
         .map((program) => toProgramCandidate(program, config.webBaseUrl))
@@ -7998,6 +8118,7 @@ async function findPrograms(client, config, input) {
         source_requests: collected.sourceRequests,
         fetched_at: new Date().toISOString(),
         warnings: warnings.length > 0 ? warnings : undefined,
+        errors: errors.length > 0 ? errors : undefined,
         filters: stripUndefined({
             platforms: input.platforms.length > 0 ? input.platforms : undefined,
             exclude_platforms: input.exclude_platforms && input.exclude_platforms.length > 0 ? input.exclude_platforms : undefined,
@@ -8040,7 +8161,7 @@ async function findPrograms(client, config, input) {
             platform_filter: input.platforms.length > 0 ? input.platforms : "all_platforms",
             max_pages_scanned_per_source: input.max_pages,
             upstream_total_pages: collected.totalPagesBySource,
-            possibly_incomplete: isRankingPossiblyIncomplete(collected.totalPagesBySource, input.max_pages)
+            possibly_incomplete: errors.length > 0 || isRankingPossiblyIncomplete(collected.totalPagesBySource, input.max_pages)
         },
         programs,
         meta: {
@@ -8445,20 +8566,39 @@ async function collectProgramSource(client, source, sourceIndex, options) {
 async function fetchProgramPage(client, source, sourceIndex, page, options) {
     const runWithSlot = options.runWithProgramPageSlot ?? runImmediately;
     return runWithSlot(async () => {
+        const endpoint = source.kind === "programs" ? "programs" : "opportunities";
+        const vdpModes = readArray(readObject(client.endpointCapability(endpoint)?.catalog_filters)?.vdp_mode);
         const query = toQuery({
             search: options.search,
             platforms: options.platforms,
             tags: options.tags,
             updated_since: options.updated_since,
             program_kind: source.kind === "programs" ? options.program_kind : undefined,
+            // This removes only known VDPs; unknown classifications with positive
+            // rewards still reach the local filters. Older APIs keep local exclusion.
+            vdp_mode: supportsCatalogFilters(client, endpoint) && vdpModes.includes("exclude") ? options.vdp_mode : undefined,
             page,
-            page_size: MAX_PROGRAMS_PER_SEARCH
+            page_size: Math.min(MAX_PROGRAMS_PER_SEARCH, client.endpointNumber(endpoint, "max_page_size", MAX_PROGRAMS_PER_SEARCH))
         });
         if (!tryConsumeBudget(options.budget)) {
             addUniqueWarning(options.warnings, "Upstream request budget was exhausted before all requested program pages could be fetched.");
             return undefined;
         }
-        const api = source.kind === "opportunity" ? await client.getOpportunities(source.level, query) : await client.listPrograms(query);
+        let api;
+        try {
+            api = source.kind === "opportunity" ? await client.getOpportunities(source.level, query) : await client.listPrograms(query);
+        }
+        catch (error) {
+            // Hunts can retain completed catalog pages. Ordinary discovery keeps its
+            // existing failure contract, and a failed first page is never an empty hit.
+            if (page === 1 || !options.partialTimeoutErrors || !(error instanceof BBRadarApiError) || error.status !== 408)
+                throw error;
+            if (error.cached || error.coalesced)
+                options.budget.remaining += 1;
+            options.partialTimeoutErrors.push(apiOperationError(`program catalog page ${page}`, error));
+            addUniqueWarning(options.warnings, "Program discovery reached its time budget; ranking covers only completed catalog pages.");
+            return undefined;
+        }
         refundBudgetIfNoUpstreamRequest(options.budget, api);
         const data = readObject(api.data);
         const meta = readObject(data?.meta);
@@ -8944,7 +9084,9 @@ Summarize the program scope:
         title: "Prepare Passive Recon Plan",
         description: "Create a passive-only plan from BBRadar program and target data. Use only when planning is explicitly requested.",
         argsSchema: {
-            program_id: programIdentifierSchema.optional(),
+            // Zod 4 keeps a description on the schema it was set on, and prompt
+            // arguments read the outer optional, so describe it again here.
+            program_id: programIdentifierSchema.optional().describe(PROGRAM_IDENTIFIER_DESCRIPTION),
             focus: z.string().optional().describe("Optional focus area such as APIs, domains, mobile, or cloud.")
         }
     }, (args) => promptResult(`Prepare a passive-only plan from BBRadar data. Program id JSON string, if present: ${promptJson(args.program_id ?? "")}.
@@ -9280,6 +9422,7 @@ function compactToolText(payload, isError) {
         }));
     }
     const meta = readObject(payload.meta);
+    const coverageIncomplete = readObject(payload.result_guidance)?.coverage_incomplete === true;
     const returned = numberField(meta, "returned") ??
         [
             readArray(payload.programs).length,
@@ -9291,6 +9434,12 @@ function compactToolText(payload, isError) {
         request_id: payload.request_id,
         summary: "Full tool result is available in structuredContent.",
         returned,
+        partial_success: meta?.partial_success === true ? true : undefined,
+        coverage_incomplete: coverageIncomplete ? true : undefined,
+        errors: meta?.partial_success === true ? readArray(payload.errors).map((error) => {
+            const value = readObject(error);
+            return stripUndefined({ operation: value?.operation, status: value?.status });
+        }) : undefined,
         mcp_timing: payload.mcp_timing
     }));
 }