feat(mcp): add leadbay_scan_portfolio_signals — bulk portfolio signal scan + stale_at honesty fix

Closes leadbay/product#3704.

Two root causes, both fixed:

1. Capability gap — no way to scan a portfolio for a signal in bulk. JM built
   a 497-lead Monitor portfolio, asked which had an M&A signal since 2025, and
   the agent fell back to one research_lead_by_id call per lead (~60 calls)
   before abandoning the task. New composite leadbay_scan_portfolio_signals
   bulk-reads CACHED web_fetch signals across the portfolio (read-only GET
   fan-out, no quota burn), filters entries by a diacritic/case-folded query
   + optional `since` date, and returns the matched cohort campaign-ready.

2. stale_at hallucination — the agent inferred signal presence/absence from
   freshness fields and reported confident-but-wrong results. New
   snippets/gates/signal-honesty.md guardrail, included in pull-followups,
   research-lead-by-id, and the followup_check_in prompt: freshness markers are
   not signal indicators; route portfolio-wide signal questions to the bulk
   tool; unresearched leads are reported (not_researched), never fabricated.

The tool separates "no matching signal" (researched, no match) from "not yet
researched" (no data to search) via a not_researched[] bucket — the structural
antidote to the original hallucination.

Verified live against the US test account end-to-end through the MCP server:
one scan_portfolio_signals call over 169 leads correctly surfaced genuine
post-2025 acquirers, with the agent reading the signal text to discard
false-positive senses of "acquisition" and reporting 0 unresearched.

- Extracts web_fetch reshaping into shared _web-fetch-helpers.ts (reused by
  research-lead-by-id).
- Registered in compositeReadTools, _composite-file-names, TOOLS_WITH_ROUTING,
  output-schema conformance, WORKFLOWS.md.
- Unit tests (new file) cover match/since/diacritics/not_researched/429/cap.
- Two eval scenarios authored (underdeliver + honesty); runner glue not yet on
  this branch, so they are fixture-ready, not wired.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ArtyETH06

.claude-plugin/plugins/leadbay/skills/leadbay_followup_check_in/SKILL.md

@@ -166,6 +166,29 @@ Unlike `leadbay_daily_check_in` which deep-dives on every promising lead in Phas
 
 When the user picks a row, call `leadbay_research_lead_by_id` on that single lead (or `leadbay_research_lead_by_name_fuzzy` if they only have the name) and offer to `leadbay_prepare_outreach` once they say "let's reach out".
 
+# PHASE 3b — BULK SIGNAL SCAN (when the user asks "which of these have signal X")
+
+If the user wants to filter the whole portfolio by a web-research signal — "which of my leads acquired a company since 2025", "find everyone with a funding signal", "who changed CEO" — do NOT loop `leadbay_research_lead_by_id` per row, and do NOT guess from freshness fields. Call `leadbay_scan_portfolio_signals({query, since?})` once: it bulk-reads the cached signals across the portfolio and returns only the matches, campaign-ready. Report any `not_researched` leads honestly ("K aren't researched yet — want me to qualify them and re-scan?"), and offer to build a campaign from the matches.
+
+**SIGNAL HONESTY — never infer signals from freshness.** `stale_at`,
+`web_fetch_in_progress`, `fetch_at` and `web_insights_fetched_at` are
+FRESHNESS markers, not signal indicators. A fresh timestamp does **not** mean a
+given signal (M&A, funding, a new hire, a CEO change) is present; a stale or
+missing one does **not** mean it's absent. The presence of a signal is
+determined ONLY by reading the actual `signals[]` / `web_fetch.content`
+entries.
+
+To answer "which of my leads have signal X" across a portfolio, call
+**`leadbay_scan_portfolio_signals`** — it bulk-reads the cached signals and
+filters them for you. Do NOT loop `leadbay_research_lead_by_id` one lead at a
+time, and do NOT guess from list-level freshness flags.
+
+If a lead has no cached signal content, say so honestly — "not yet researched,
+want me to qualify it?" — and surface it as `not_researched`. Never fabricate
+or imply a scan you didn't actually run, and never report a confident
+signal-presence verdict for a lead whose signals you never read.
+
+
 # CROSS-MODE PIVOT
 
 Below the table, offer the cross-mode pivot in one short line so the user can redirect if you guessed wrong on entry-point routing: "Want to see NEW leads from your wishlist instead?" — that routes back to `leadbay_daily_check_in` (Discovery via `leadbay_pull_leads`).

WORKFLOWS.md

@@ -26,6 +26,7 @@ The table is the human-readable index. The `yaml expected` + `yaml scenario` blo
 | 12 | **Lens extension — on-demand fill for bigger appetite** — "I want more leads on this lens / I need a bigger batch today" | `leadbay_extend_my_lens` | "I want more leads on this lens — bigger batch today" |
 | 13 | **Lens management — list / switch audiences** — "show me my lenses", "which audiences do I have", "switch to my Joinery lens" | `leadbay_my_lenses` | "Show me my lenses and switch to the Joinery one" |
 | 14 | **Lens creation — make a named audience** — "create a lens called X for sector Y", "set up a new audience" | `leadbay_new_lens` | "Create a lens called Joinery for the fintech sector" |
+| 15 | **Bulk portfolio signal scan** — "which of my leads acquired a company since 2025", "scan my portfolio for funding signals", "find everyone who changed CEO" — filters a known portfolio by a web-research signal in ONE call instead of looping `leadbay_research_lead_by_id` per lead | `leadbay_scan_portfolio_signals` | "Which of my leads acquired a company since 2025?" |
 
 ---
 

packages/core/src/composite/_composite-file-names.ts

@@ -39,6 +39,7 @@ export const COMPOSITE_FILE_TOOL_NAMES: ReadonlySet<string> = new Set([
   "leadbay_research_lead_by_id",
   "leadbay_research_lead_by_name_fuzzy",
   "leadbay_resolve_import_rows",
+  "leadbay_scan_portfolio_signals",
   "leadbay_seed_candidates",
   "leadbay_tour_plan",
 ]);

packages/core/src/composite/_web-fetch-helpers.ts

@@ -0,0 +1,55 @@
+import type { WebFetchSignalsSection } from "../types.js";
+
+// Shared web_fetch.content reshaping. The backend keys web-research signals
+// by emoji-prefixed section labels (e.g. "🏢 company profile", "📈 business
+// signals"); each value is an array of WebFetchEntry. Composites that surface
+// signals to the agent reshape this dynamic dict into an ordered array.
+//
+// Used by leadbay_research_lead_by_id (single lead) and
+// leadbay_scan_portfolio_signals (bulk read).
+
+// Stable section ordering: profile → signals → clues → others (alphabetical).
+export const SECTION_PRIORITY = ["profile", "signals", "clues"];
+
+// Map an emoji-prefixed section label like "🏢 company profile" to
+// {emoji: "🏢", label: "company profile"}. If no emoji prefix, label stays
+// as-is and emoji is null.
+export function splitEmojiSection(key: string): {
+  emoji: string | null;
+  label: string;
+} {
+  // Match a leading non-letter/non-digit run (typically emoji) followed by space.
+  const m = key.match(/^([^\p{L}\p{N}\s]+)\s+(.+)$/u);
+  if (m) return { emoji: m[1], label: m[2] };
+  return { emoji: null, label: key };
+}
+
+export function reshapeWebFetchContent(
+  content: Record<string, unknown> | null
+): WebFetchSignalsSection[] {
+  if (!content) return [];
+  const sections: WebFetchSignalsSection[] = [];
+  for (const [key, val] of Object.entries(content)) {
+    if (!Array.isArray(val)) continue;
+    const { emoji, label } = splitEmojiSection(key);
+    sections.push({
+      section_label: label,
+      section_emoji: emoji,
+      entries: val as WebFetchSignalsSection["entries"],
+    });
+  }
+  // Sort: known section labels first (in priority order), then alphabetical.
+  sections.sort((a, b) => {
+    const ai = SECTION_PRIORITY.findIndex((p) =>
+      a.section_label.toLowerCase().includes(p)
+    );
+    const bi = SECTION_PRIORITY.findIndex((p) =>
+      b.section_label.toLowerCase().includes(p)
+    );
+    const aN = ai < 0 ? SECTION_PRIORITY.length : ai;
+    const bN = bi < 0 ? SECTION_PRIORITY.length : bi;
+    if (aN !== bN) return aN - bN;
+    return a.section_label.localeCompare(b.section_label);
+  });
+  return sections;
+}

packages/core/src/composite/research-lead-by-id.ts

@@ -5,12 +5,12 @@ import type {
   AiAgentResponse,
   LeadPayload,
   LeadWebFetchPayload,
-  WebFetchSignalsSection,
   PaidContactPayload,
   ContactPayload,
   PaginatedActivities,
 } from "../types.js";
 import { withAgentMemoryMeta } from "../agent-memory/index.js";
+import { reshapeWebFetchContent } from "./_web-fetch-helpers.js";
 
 import { leadbay_research_lead_by_id as RESEARCH_LEAD_BY_ID_DESCRIPTION } from "../tool-descriptions.generated.js";
 
@@ -169,43 +169,8 @@ export function renderResearchLeadMarkdown(
   return out.join("\n");
 }
 
-// Map an emoji-prefixed section label like "🏢 company profile" to
-// {section_emoji: "🏢", section_label: "company profile"}. If no emoji, label
-// stays as-is. Stable section ordering: profile → signals → clues → others.
-const SECTION_PRIORITY = ["profile", "signals", "clues"];
-
-function splitEmojiSection(key: string): { emoji: string | null; label: string } {
-  // Match a leading non-letter/non-digit character (typically emoji) followed by space.
-  const m = key.match(/^([^\p{L}\p{N}\s]+)\s+(.+)$/u);
-  if (m) return { emoji: m[1], label: m[2] };
-  return { emoji: null, label: key };
-}
-
-function reshapeWebFetchContent(
-  content: Record<string, unknown> | null
-): WebFetchSignalsSection[] {
-  if (!content) return [];
-  const sections: WebFetchSignalsSection[] = [];
-  for (const [key, val] of Object.entries(content)) {
-    if (!Array.isArray(val)) continue;
-    const { emoji, label } = splitEmojiSection(key);
-    sections.push({
-      section_label: label,
-      section_emoji: emoji,
-      entries: val as WebFetchSignalsSection["entries"],
-    });
-  }
-  // Sort: known section labels first (in priority order), then alphabetical.
-  sections.sort((a, b) => {
-    const ai = SECTION_PRIORITY.findIndex((p) => a.section_label.toLowerCase().includes(p));
-    const bi = SECTION_PRIORITY.findIndex((p) => b.section_label.toLowerCase().includes(p));
-    const aN = ai < 0 ? SECTION_PRIORITY.length : ai;
-    const bN = bi < 0 ? SECTION_PRIORITY.length : bi;
-    if (aN !== bN) return aN - bN;
-    return a.section_label.localeCompare(b.section_label);
-  });
-  return sections;
-}
+// Section reshaping (splitEmojiSection / reshapeWebFetchContent / SECTION_PRIORITY)
+// moved to ./_web-fetch-helpers.js — shared with leadbay_scan_portfolio_signals.
 
 // Hashable contact summary used by hasReachableContact. A contact is
 // "reachable" iff it has at least one of: non-empty email, non-empty