alphacouncil-agent 0.5.0

package/mcp/lib/social.mjs

@@ -0,0 +1,261 @@
+import { LIMITS } from "./constants.mjs";
+import { parseFeed, applyRecencyGate } from "./feeds.mjs";
+
+/**
+ * Keyless social signal: retail positioning and technical-community discussion.
+ *
+ * The goal was an X hotspot layer. As of 2026-07-26 that is not obtainable without paying:
+ * Nitter is dead (search returns nothing on every surviving instance), the X API bills per
+ * post, xAI's x_search bills per call, StockTwits sits behind Cloudflare, and Bluesky's
+ * searchPosts requires auth. All tested, none assumed.
+ *
+ * What IS free, and was verified working:
+ *   - Reddit subreddit and search RSS (rate-limited; 429s under load, so it backs off)
+ *   - Hacker News via the Algolia index
+ *   - Bluesky getAuthorFeed for a named account, which needs no auth even though search does
+ *   - X single-post verification by id via cdn.syndication.twimg.com
+ *
+ * The output says plainly what this is and is not. Reddit and HN are retail and engineer
+ * opinion; they are NOT the professional FinTwit layer, and treating them as a proxy for it
+ * is the mistake this module is written to prevent.
+ */
+
+const UA = "alphacouncil-agent/0.4 (open-source equity research; contact via repository issues)";
+
+async function getText(url, { timeoutMs = LIMITS.QUOTE_FETCH_MS * 2, accept = "*/*" } = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal, headers: { "User-Agent": UA, Accept: accept } });
+    if (res.status === 429) return { ok: false, status: 429, reason: "rate limited" };
+    if (!res.ok) return { ok: false, status: res.status, reason: `HTTP ${res.status}` };
+    return { ok: true, status: res.status, text: await res.text() };
+  } catch (error) {
+    return { ok: false, status: 0, reason: String(error?.name === "AbortError" ? "timed out" : error?.message || error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Reddit answers 429 readily and recovers within seconds. One retry after a pause turns a
+ * dead source into a working one; without it the layer reports "unavailable" for a source
+ * that is merely busy, which understates coverage in a way nobody would notice.
+ */
+async function getTextWithBackoff(url, opts = {}) {
+  const first = await getText(url, opts);
+  if (first.ok || first.status !== 429) return first;
+  await new Promise((r) => setTimeout(r, 2500));
+  return getText(url, opts);
+}
+
+/** Subreddits whose subject matter is equities. Deliberately conservative and well-known. */
+export const DEFAULT_SUBREDDITS = ["stocks", "investing", "SecurityAnalysis", "wallstreetbets", "options"];
+
+export async function fetchReddit({ subreddits = DEFAULT_SUBREDDITS, query = null, days = 7, asOf = null } = {}) {
+  const subs = (subreddits || DEFAULT_SUBREDDITS).slice(0, 6);
+  // A site-wide search for a ticker name returns whatever Reddit happens to be discussing:
+  // a live run for "Micron" came back with medical posts. Searching inside the equity
+  // subreddits keeps the source on topic instead of quietly filling with noise.
+  const specs = query
+    ? [{
+        source: `Reddit search in r/${subs.join("+")}`,
+        url: `https://www.reddit.com/r/${subs.map(encodeURIComponent).join("+")}/search.rss`
+          + `?q=${encodeURIComponent(query)}&restrict_sr=1&sort=new&t=month`,
+      }]
+    : subs.map((s) => ({ source: `r/${s}`, url: `https://www.reddit.com/r/${encodeURIComponent(s)}/.rss` }));
+
+  const results = [];
+  // Sequential on purpose: Reddit rate-limits aggressively and parallel requests trip it.
+  for (const spec of specs) {
+    const res = await getTextWithBackoff(spec.url, { accept: "application/atom+xml, application/xml" });
+    results.push({
+      ...spec,
+      ok: res.ok,
+      reason: res.reason,
+      items: res.ok ? parseFeed(res.text, { source: spec.source }) : [],
+    });
+  }
+  const gate = applyRecencyGate(results.flatMap((r) => r.items), { days, asOf });
+  // Reddit search matches post bodies as well as titles, so a result whose title omits the
+  // term is a legitimate hit, not noise -- filtering those out would silently drop real
+  // matches. Marking where the term matched lets a reader see which ones need opening
+  // instead of judging relevance from a title that was never the thing that matched.
+  if (query) {
+    const term = String(query).toLowerCase();
+    gate.included = gate.included.map((item) => ({
+      ...item,
+      matched_in: String(item.title || "").toLowerCase().includes(term) ? "title" : "body (open the link to see the mention)",
+    }));
+  }
+  return {
+    platform: "reddit",
+    what_this_is: "Retail investor discussion. Useful for crowding and for what a popular narrative sounds like. "
+      + "It is not professional analysis and must never be cited as evidence about a business.",
+    ...gate,
+    feeds: results.map(({ source, ok, reason, items }) => ({ source, ok, reason, item_count: items.length })),
+  };
+}
+
+export async function fetchHackerNews({ query, days = 7, asOf = null, hits = 30 } = {}) {
+  if (!query) return { platform: "hackernews", ok: false, reason: "a query is required", included: [], excluded: [] };
+  const now = asOf ? Date.parse(`${asOf}T23:59:59Z`) : Date.now();
+  const since = Math.floor((now - days * 86400000) / 1000);
+  // Algolia applies typo tolerance by default, which made "Micron" match "microkernels" and
+  // "Microsoft" in a live run. Quoting the phrase and disabling typo tolerance is the fix;
+  // without it the layer looks well-sourced while discussing a different subject entirely.
+  const url = `https://hn.algolia.com/api/v1/search_by_date?query=${encodeURIComponent(`"${query}"`)}`
+    + `&tags=story&numericFilters=created_at_i>${since}&hitsPerPage=${Math.min(hits, 50)}`
+    + "&typoTolerance=false&advancedSyntax=true";
+  const res = await getText(url, { accept: "application/json" });
+  if (!res.ok) return { platform: "hackernews", ok: false, reason: res.reason, included: [], excluded: [] };
+  let json;
+  try { json = JSON.parse(res.text); } catch { return { platform: "hackernews", ok: false, reason: "unparsable response", included: [], excluded: [] }; }
+  const included = (json.hits || []).map((h) => ({
+    title: h.title || h.story_title,
+    link: h.url || `https://news.ycombinator.com/item?id=${h.objectID}`,
+    published_at: h.created_at,
+    source: "Hacker News",
+    points: h.points ?? 0,
+    comments: h.num_comments ?? 0,
+    discussion: `https://news.ycombinator.com/item?id=${h.objectID}`,
+  })).filter((h) => h.title);
+  const term = String(query).toLowerCase();
+  const onTopic = included.filter((h) => h.title.toLowerCase().includes(term));
+  const offTopic = included.length - onTopic.length;
+  return {
+    platform: "hackernews",
+    ok: true,
+    what_this_is: "Engineer and technical-community discussion. Its value is the comment thread, where people "
+      + "who build the thing being discussed correct the article. Weak on financials, occasionally very strong "
+      + "on whether a technical claim is real.",
+    total_matching: json.nbHits ?? included.length,
+    included: onTopic,
+    // Belt and braces: the service can still return a near-match, and a near-match on a
+    // ticker name is a different company.
+    dropped_off_topic: offTopic,
+    excluded: [],
+  };
+}
+
+/**
+ * Bluesky, by account only.
+ *
+ * searchPosts returns 403 without auth, so cashtag discovery is not possible. getAuthorFeed
+ * is public, which makes a curated account list workable -- and a curated list was the right
+ * design anyway: cashtag search is where the promotional accounts live.
+ */
+export async function fetchBluesky({ handles = [], days = 7, asOf = null, limit = 20 } = {}) {
+  if (!handles.length) {
+    return {
+      platform: "bluesky", ok: true, configured: false, included: [], excluded: [],
+      note: "No handles configured. Bluesky search requires authentication, but reading a named account does not, "
+        + "so this source activates as soon as handles are supplied. Add them under social_handles.",
+    };
+  }
+  const out = [];
+  const failed = [];
+  for (const handle of handles.slice(0, 12)) {
+    const url = "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed"
+      + `?actor=${encodeURIComponent(handle)}&limit=${Math.min(limit, 50)}`;
+    const res = await getText(url, { accept: "application/json" });
+    if (!res.ok) { failed.push({ handle, reason: res.reason }); continue; }
+    let json;
+    try { json = JSON.parse(res.text); } catch { failed.push({ handle, reason: "unparsable response" }); continue; }
+    for (const entry of json.feed || []) {
+      const post = entry.post;
+      if (!post?.record?.text) continue;
+      out.push({
+        title: post.record.text.slice(0, 280),
+        link: `https://bsky.app/profile/${handle}`,
+        published_at: post.record.createdAt || null,
+        source: `bluesky:${handle}`,
+        likes: post.likeCount ?? null,
+        reposts: post.repostCount ?? null,
+        replies: post.replyCount ?? null,
+      });
+    }
+  }
+  const gate = applyRecencyGate(out, { days, asOf });
+  return {
+    platform: "bluesky", ok: true, configured: true,
+    what_this_is: "Named accounts only, because search needs auth. Whatever these accounts are worth is what "
+      + "this source is worth -- the curation is the signal, and it is the user's, not this tool's.",
+    ...gate,
+    handles_failed: failed,
+  };
+}
+
+/**
+ * Verify one X post really exists and says what it was quoted as saying.
+ *
+ * The endpoint is undocumented and unsupported, so it is used only for verification, never
+ * as a data source. It closes a specific hole: a decoded snowflake timestamp proves nothing,
+ * because any made-up 19-digit id decodes to a plausible date. Existence has to be checked.
+ */
+export async function verifyXPost(id) {
+  const clean = String(id || "").trim();
+  if (!/^\d{1,20}$/.test(clean)) return { id, exists: false, reason: "not a numeric post id" };
+  const res = await getText(`https://cdn.syndication.twimg.com/tweet-result?id=${clean}&lang=en&token=a`, { accept: "application/json" });
+  if (!res.ok) {
+    // A 404 here is the meaningful answer: the id does not exist.
+    return { id: clean, exists: false, reason: res.status === 404 ? "no such post" : res.reason, checked: true };
+  }
+  let json;
+  try { json = JSON.parse(res.text); } catch { return { id: clean, exists: false, reason: "unparsable response", checked: true }; }
+  if (!json?.text) return { id: clean, exists: false, reason: "response carries no post text", checked: true };
+  return {
+    id: clean,
+    exists: true,
+    text: json.text,
+    created_at: json.created_at ?? null,
+    author: json.user?.screen_name ?? null,
+    favorite_count: json.favorite_count ?? null,
+    note: "Verified against an undocumented endpoint. Use to confirm a quoted post, not as a data feed.",
+  };
+}
+
+export async function getSocialPulse({ query = null, symbol = null, subreddits, handles = [], days = 7, asOf = null } = {}) {
+  const term = query || symbol;
+  const [reddit, hn, bsky] = await Promise.all([
+    fetchReddit({ subreddits, query: term, days, asOf }).catch((e) => ({ platform: "reddit", ok: false, reason: String(e?.message || e), included: [] })),
+    term ? fetchHackerNews({ query: term, days, asOf }) : Promise.resolve({ platform: "hackernews", ok: true, skipped: "no query given", included: [] }),
+    fetchBluesky({ handles, days, asOf }).catch((e) => ({ platform: "bluesky", ok: false, reason: String(e?.message || e), included: [] })),
+  ]);
+
+  const counts = {
+    reddit: reddit.included?.length ?? 0,
+    hackernews: hn.included?.length ?? 0,
+    bluesky: bsky.included?.length ?? 0,
+  };
+
+  return {
+    as_of: asOf || new Date().toISOString().slice(0, 10),
+    window_days: days,
+    query: term,
+    platforms: { reddit, hackernews: hn, bluesky: bsky },
+    counts,
+    total: counts.reddit + counts.hackernews + counts.bluesky,
+    // Stated in the payload, not only in a persona, because the payload is what gets quoted.
+    coverage_limits: [
+      "X / Twitter has no free discovery channel as of 2026-07. Nitter search is dead on every "
+      + "surviving instance, the X API bills per post retrieved, and xAI's x_search bills per call. "
+      + "This layer therefore does NOT cover professional FinTwit, which is where most of the "
+      + "genuinely early equity discussion happens. Treating Reddit as a substitute for it is wrong.",
+      "StockTwits is behind Cloudflare and Bluesky search requires authentication; neither is "
+      + "reachable without credentials, so neither is used.",
+      "Reddit and Hacker News are retail and engineer opinion. They evidence what a narrative "
+      + "sounds like and how crowded it is. They are not evidence about a business.",
+      "Engagement counts are unavailable on Reddit RSS. Where a count is absent it is reported "
+      + "absent rather than estimated.",
+    ],
+    how_to_use: [
+      "Look for CONTRADICTION, not agreement. A view held loudly here that the filings do not support "
+      + "is a crowding signal; agreement with the filings adds nothing you did not have.",
+      "A claim from this layer may never enter the conclusion on its own. It is a lead, to be "
+      + "confirmed against a filing or a dated source, or else recorded in open_questions.",
+      "Volume of mentions measures attention, not correctness, and the loudest posts are the most "
+      + "emotional ones. Do not rank by engagement and then read the top as representative.",
+    ],
+  };
+}

package/mcp/lib/tables.mjs

@@ -0,0 +1,150 @@
+/**
+ * Markdown tables for tool output.
+ *
+ * Hosts render the `content[0].text` of a tool result as markdown, so a table there is a
+ * table the user actually sees. Structured data still goes in structuredContent for the
+ * model; this is the human-facing half, and a screen result with seven metrics is far
+ * easier to check as a table than as a sentence.
+ */
+
+const escape = (value) => String(value ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
+
+/**
+ * @param {string[]} headers
+ * @param {Array<Array<unknown>>} rows
+ * @param {object} [options]
+ * @param {string} [options.title]
+ * @param {string} [options.empty] shown instead of an empty table
+ */
+/**
+ * Reduce any cell to display text.
+ *
+ * A {en, zh} label reaching a template literal renders as "[object Object]", which sits
+ * next to real numbers and reads as a broken field rather than a missing one -- so the
+ * reader distrusts the surrounding data without being able to say why. Two shipped that
+ * way before this existed, in the grounding block's skipped rules and its macro readings.
+ */
+const cellText = (cell, zh) => {
+  if (cell == null) return "";
+  if (typeof cell === "object" && !Array.isArray(cell)) {
+    if ("en" in cell || "zh" in cell) return (zh ? cell.zh : cell.en) ?? cell.en ?? cell.zh ?? "";
+    return JSON.stringify(cell);
+  }
+  return String(cell);
+};
+
+export function table(headers, rows, { title, empty = "_(no rows)_", zh = false } = {}) {
+  const parts = title ? [`**${title}**`, ""] : [];
+  if (!rows.length) return [...parts, empty].join("\n");
+  parts.push(`| ${headers.map(escape).join(" | ")} |`);
+  parts.push(`|${headers.map(() => "---").join("|")}|`);
+  for (const row of rows) parts.push(`| ${row.map((cell) => escape(cellText(cell, zh))).join(" | ")} |`);
+  return parts.join("\n");
+}
+
+/**
+ * Status markers. A glyph plus a word: the glyph gives the row a shape you can scan, the
+ * word survives a terminal that renders the glyph badly.
+ */
+export const mark = (ok) => (ok ? "✅ pass" : "❌ **FAIL**");
+export const SKIPPED = "⚪ skipped";
+export const skippedMark = (zh) => (zh ? "⚪ 跳过" : SKIPPED);
+
+/** A label that may be a plain string or a {en, zh} pair. */
+export const label = (value, zh) => (typeof value === "string" ? value : (zh ? value?.zh : value?.en) ?? "");
+
+/** Threshold with its direction, so "27.17% vs 15" cannot be read backwards. */
+export function threshold(value, direction, unit) {
+  const arrow = direction === "max" ? "≤" : direction === "min" ? "≥" : "";
+  return `${arrow}${arrow ? " " : ""}${metricValue(value, unit)}`;
+}
+
+/** Compact money, so a table column stays readable. */
+export function money(value, currency = "USD") {
+  if (value === null || value === undefined) return "n/a";
+  const abs = Math.abs(value);
+  if (abs >= 1e12) return `${(value / 1e12).toFixed(2)}T ${currency}`;
+  if (abs >= 1e9) return `${(value / 1e9).toFixed(2)}bn ${currency}`;
+  if (abs >= 1e6) return `${(value / 1e6).toFixed(1)}m ${currency}`;
+  return `${value.toLocaleString("en-US")} ${currency}`;
+}
+
+export function metricValue(value, unit) {
+  if (value === null || value === undefined) return "n/a";
+  if (unit === "%") return `${value}%`;
+  if (unit === "USD") return money(value);
+  return unit ? `${value} ${unit}` : String(value);
+}
+
+
+/**
+ * One dashboard for a whole grounding payload.
+ *
+ * A run currently answers across several tool calls, and the reader has to hold five
+ * results in their head to see the picture. This renders the lot as sections of a single
+ * document: what is established, what could not be fetched, and who is in play with which
+ * data behind them.
+ */
+export function groundingDashboard(g, language = "English") {
+  const zh = /中文|chinese|zh/i.test(String(language));
+  const t = (en, cn) => (zh ? cn : en);
+  const out = [];
+
+  out.push(`# ${t("Research dashboard", "研究总览")}${g.quote?.symbol ? ` — ${g.quote.symbol}` : ""}`);
+
+  const facts = [];
+  if (g.filer) facts.push([t("Filer", "主体"), `${g.filer.name} (SIC ${g.filer.sic ?? "?"})`, g.filer.sic_description ?? "-", "SEC"]);
+  if (g.quote) {
+    facts.push([t("Quote", "行情"), `${g.quote.price}${g.quote.currency ? " " + g.quote.currency : ""}`,
+      g.quote.change_pct != null ? `${g.quote.change_pct > 0 ? "+" : ""}${g.quote.change_pct}%` : "-",
+      `${g.quote.source} ${t("(~15m delayed)", "（延迟约15分钟）")}`]);
+  }
+  if (g.market?.financials) {
+    const f = g.market.financials;
+    facts.push([t("Latest filing", "最新申报"), `${f.gregorian_year ?? f.period?.year}Q${f.period?.quarter}`,
+      `${t("revenue", "营收")} ${f.revenue?.toLocaleString() ?? "n/a"} ${f.currency}`, f.source]);
+  }
+  if (facts.length) out.push("", table([t("Item", "项目"), t("Value", "数值"), t("Detail", "细节"), t("Source", "来源")], facts, { title: t("Established facts", "已确立的事实") }));
+
+  if (g.screen) {
+    const rows = g.screen.metrics.map((m) => [
+      label(m.label, zh), metricValue(m.value, m.unit), threshold(m.threshold, m.direction, m.unit), mark(m.passed),
+    ]);
+    for (const sk of g.screen.skipped || []) rows.push([
+      typeof sk === "string" ? sk : label(sk.label, zh),
+      t("not computable", "无法计算"), "-", skippedMark(zh),
+    ]);
+    out.push("", table([t("Rule", "规则"), t("Measured", "实测"), t("Threshold", "阈值"), t("Result", "结果")], rows,
+      { title: `${t("Mechanical screen", "硬指标筛选")} — ${g.screen.verdict} (${g.screen.rules_computed}/${g.screen.rules_total})` }));
+  }
+
+  if (g.macro?.derived?.length) {
+    out.push("", table([t("Reading", "读数"), t("Value", "数值")],
+      g.macro.derived.map((d) => [label(d.label, zh), String(d.value)]), { title: t("Macro", "宏观") }));
+  }
+
+  if (g.coverage?.rows?.length) {
+    out.push("", table(
+      [t("Symbol", "标的"), t("Market", "市场"), t("Structured financials", "结构化财务"), t("Blocker", "阻碍")],
+      g.coverage.rows.map((r) => [
+        r.symbol, r.market,
+        zh ? { yes: "有", "summary only": "仅摘要", no: "无" }[r.structured_financials] ?? r.structured_financials
+           : r.structured_financials,
+        r.needs_env || (r.reason ? r.reason.slice(0, 40) : "-"),
+      ]),
+      { title: t("Data coverage", "数据覆盖") }));
+  }
+
+  if (g.industry?.participants?.length) {
+    out.push("", table([t("Layer", "环节"), t("Company", "公司"), t("Symbol", "代码"), t("Market", "市场")],
+      g.industry.participants.map((p) => [p.layer?.[zh ? "zh" : "en"] ?? "-", p.name, p.symbol ?? t("unlisted", "未上市"), p.market ?? "-"]),
+      { title: t("Value chain", "产业链") }));
+  }
+
+  if (g.unavailable?.length) {
+    out.push("", `**${t("Data gaps — do not fill these from memory", "数据缺口 — 禁止用记忆填补")}**`, "",
+      ...g.unavailable.map((u) => `- ${u}`));
+  }
+
+  return out.join("\n");
+}

package/mcp/lib/text.mjs

@@ -0,0 +1,27 @@
+import { LIMITS } from "./constants.mjs";
+
+export function appendLimited(base, chunk, max = LIMITS.LOG_TAIL_BYTES) {
+  const next = `${base}${chunk}`;
+  return next.length > max ? next.slice(-max) : next;
+}
+
+export function cleanLog(value, max = LIMITS.CLEAN_LOG_BYTES) {
+  return String(value || "")
+    .replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "")
+    .slice(-max);
+}
+
+export function fence(value, lang = "text") {
+  const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  return `~~~${lang}\n${text.replaceAll("~~~", "~~~\\u200b")}\n~~~`;
+}
+
+export function bullets(items) {
+  if (!Array.isArray(items) || items.length === 0) return "- None";
+  return items.map((item) => `- ${typeof item === "string" ? item : JSON.stringify(item)}`).join("\n");
+}
+
+export function clip(text, max = LIMITS.CLIP_CHARS) {
+  const value = String(text || "").replace(/\s+/g, " ").trim();
+  return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}

package/mcp/lib/weights.mjs

@@ -0,0 +1,150 @@
+import { registry, selectRoster } from "./personas/registry.mjs";
+
+/**
+ * How much each seat counts in the synthesis, and why.
+ *
+ * Two layers, both visible in the report:
+ *
+ *   1. A declared base weight per persona. Never hidden, always overridable.
+ *   2. An adjustment driven by whether that seat's cited sources survived verification.
+ *      A seat whose evidence was contradicted loses standing automatically -- it does not
+ *      get to keep its share of the decision because its philosophy is well regarded.
+ *
+ * What this is NOT: an optimised allocation. Nobody can honestly claim to have found the
+ * best weighting for a committee of language models, because measuring that would require
+ * a return backtest of LLM judgment, and such a backtest is invalidated by look-ahead
+ * bias -- the model already knows what happened after the as-of date. The weights are a
+ * transparent, editable prior, and the report says so.
+ */
+
+/** Verifier outcomes that reduce a seat's standing, and by how much. */
+const VERDICT_PENALTY = {
+  contradicted: 1.0,
+  disagree: 1.0,
+  refuted: 1.0,
+  source_does_not_mention: 0.75,
+  partial: 0.4,
+  weakened: 0.4,
+  cannot_confirm: 0.3,
+  source_unreachable: 0.3,
+  superseded_by_newer: 0.3,
+};
+
+/** Floor so a penalised seat is quieter but never silently erased. */
+const MIN_WEIGHT_FRACTION = 0.15;
+
+export function baseWeight(persona) {
+  const declared = persona?.default_weight;
+  return Number.isFinite(declared) && declared > 0 ? declared : 1;
+}
+
+/**
+ * @param {object[]} verdicts  [{ seat, verdict }] from the Stage 2b verifiers
+ * @returns {{factor:number, reasons:string[]}}
+ */
+export function verificationAdjustment(seat, verdicts = []) {
+  const mine = verdicts.filter((v) => v?.seat === seat && v?.verdict);
+  if (mine.length === 0) return { factor: 1, reasons: [] };
+
+  let penalty = 0;
+  const reasons = [];
+  for (const { verdict } of mine) {
+    const hit = VERDICT_PENALTY[verdict];
+    if (!hit) continue;
+    penalty += hit;
+    reasons.push(verdict);
+  }
+  if (penalty === 0) return { factor: 1, reasons: [] };
+
+  // Penalty is per checked claim, so normalise by how many claims were checked: one bad
+  // verdict out of ten is not the same as one out of one.
+  const factor = Math.max(MIN_WEIGHT_FRACTION, 1 - penalty / mine.length);
+  return { factor: Number(factor.toFixed(3)), reasons };
+}
+
+/**
+ * Resolve final weights for every seat in a run.
+ *
+ * @param {object} run
+ * @param {object[]} [run.master_opinions]
+ * @param {object[]} [run.verifier_verdicts]  [{ seat, verdict, claim }]
+ * @param {object}   [overrides]              seat id -> weight, from the caller
+ */
+export function resolveSeatWeights(run, overrides = {}) {
+  const reg = registry();
+  const seats = [];
+
+  const debateIds = reg.ids("debate").filter((id) => id !== "portfolio_manager");
+  const masterIds = (run.master_opinions || []).map((o) => o.master);
+
+  for (const id of [...debateIds, ...masterIds]) {
+    const persona = reg.get(id);
+    if (!persona) continue;
+    const declared = baseWeight(persona);
+    const override = Number.isFinite(overrides[id]) && overrides[id] >= 0 ? overrides[id] : null;
+    const base = override ?? declared;
+    const { factor, reasons } = verificationAdjustment(id, run.verifier_verdicts);
+
+    // A master that ruled itself out of scope should not carry weight into a verdict it
+    // declined to give. That is not a penalty; it is taking the seat at its word.
+    const opinion = (run.master_opinions || []).find((o) => o.master === id);
+    const outOfScope = opinion?.stance === "out_of_scope";
+
+    seats.push({
+      seat: id,
+      kind: persona.kind,
+      declared_weight: declared,
+      override_weight: override,
+      verification_factor: factor,
+      verification_reasons: reasons,
+      out_of_scope: outOfScope,
+      effective_weight: outOfScope ? 0 : Number((base * factor).toFixed(3)),
+      stance: opinion?.stance,
+    });
+  }
+
+  const total = seats.reduce((sum, s) => sum + s.effective_weight, 0);
+  for (const seat of seats) {
+    seat.share = total > 0 ? Number((seat.effective_weight / total).toFixed(4)) : 0;
+  }
+  return { seats, total_effective_weight: Number(total.toFixed(3)) };
+}
+
+/** A table the PM must reproduce in the report, so the weighting is never invisible. */
+export function weightTableMarkdown(resolved, language = "English") {
+  const chinese = /中文|chinese|zh/i.test(String(language));
+  const { seats } = resolved;
+  if (!seats.length) return "";
+
+  const header = chinese
+    ? "| 席位 | 立场 | 声明权重 | 核验系数 | 生效权重 | 占比 | 调整原因 |"
+    : "| Seat | Stance | Declared | Verification | Effective | Share | Why adjusted |";
+  const rule = "|---|---|---|---|---|---|---|";
+  const rows = seats.map((s) => {
+    const why = s.out_of_scope
+      ? (chinese ? "自述超出判断范围" : "declared out of scope")
+      : (s.verification_reasons.length
+        ? s.verification_reasons.join(", ")
+        : (chinese ? "无" : "-"));
+    const stance = s.stance || (chinese ? "（辩论角色）" : "(debate role)");
+    const declared = s.override_weight !== null
+      ? `${s.override_weight} ${chinese ? "(覆盖)" : "(override)"}`
+      : String(s.declared_weight);
+    return `| ${s.seat} | ${stance} | ${declared} | ${s.verification_factor} | ${s.effective_weight} | ${(s.share * 100).toFixed(1)}% | ${why} |`;
+  });
+
+  const note = chinese
+    ? "\n权重是可编辑的先验，不是最优解。没人能诚实地宣称找到了 LLM 委员会的最佳配比——要衡量它需要对 LLM 判断做收益回测，而那种回测被前视偏差证伪（模型已经知道分析基准日之后发生了什么）。引用被核验推翻的席位会自动降权，但不会被完全抹掉。"
+    : "\nThese weights are an editable prior, not an optimum. Nobody can honestly claim to have found the best weighting for a committee of language models: measuring that would need a return backtest of LLM judgment, and such a backtest is invalidated by look-ahead bias -- the model already knows what happened after the as-of date. Seats whose cited evidence failed verification are down-weighted automatically, but never silently erased.";
+
+  return [header, rule, ...rows].join("\n") + "\n" + note;
+}
+
+/** Seats available for a roster, for tool schemas and previews. */
+export function rosterWeights(rosterName) {
+  const reg = registry();
+  return selectRoster(reg, { kind: "master", roster: rosterName }).map((p) => ({
+    seat: p.id,
+    declared_weight: baseWeight(p),
+  }));
+}