alphacouncil-agent 1.0.3 → 1.0.13

package/mcp/lib/prompts.mjs

@@ -91,7 +91,67 @@ function fundOrIndexTaskInstruction(task, instrument, language) {
   });
 }
 
-export function taskPrompt(task, symbol, asOfDate, userPrompt = "", language = "auto", grounding = null) {
+/**
+ * Output shaping for a depth tier.
+ *
+ * A tier is a timeout, and a timeout is not a plan. Sending the identical prompt with a shorter
+ * fuse does not buy a faster good packet -- it buys a packet the worker could not finish, which
+ * arrives as `degraded` or not at all. For an LLM call the wall clock is dominated by the tokens
+ * it generates, so the way to run faster without losing information is to ask for the same
+ * information in less prose.
+ *
+ * The line every tier holds: claims, numbers, scoped source IDs, required report sections and
+ * the decision itself are never what gets cut. What `fast` removes is restatement -- re-quoting
+ * evidence the packet can cite by ID, recapping an opponent before answering, methodology
+ * preambles. What `slow` buys back is room to write a derivation out in full.
+ */
+export function paceShapingInstruction(pace, role, chinese) {
+  const tier = String(pace || "normal").toLowerCase();
+  if (tier !== "fast" && tier !== "slow") return "";
+  const isReport = role === "portfolio_manager";
+  if (tier === "fast") {
+    if (chinese) {
+      return [
+        "本轮按 fast 档运行。要压缩的是叙述，不是内容：",
+        "- 每一条仍必须带具体数字和作用域来源 ID（`<task>:S<n>`）。少写一条论点比少写一个来源 ID 更可接受，凭记忆补数字则永远不可接受。",
+        "- 不要复述证据原文——引用来源 ID 即可。不要在回答前复述对手立场。不要写方法论开场或结尾总结。",
+        "- 每条论点压到一到两句，只保留「主张 + 数字 + 来源 + 它错在哪」。",
+        isReport
+          ? "- 报告的每一个必需章节仍必须齐备且非空：简洁只能来自散文，不能来自删章节。价位阶梯与失效条件不得压缩成一句话，它们是这份报告唯一可执行的部分。"
+          : "- 论点条数上限 6 条，取信息量最高的 6 条，其余舍弃而不是缩写成半句。",
+        "- 如果时间不足以完成，宁可交一份明确标注缺口的短包，也不要交一份看起来完整但数字来自记忆的包。",
+      ].join("\n");
+    }
+    return [
+      "This round runs at the fast tier. Compress the prose, not the content:",
+      "- Every item still carries its figure and its scoped source ID (`<task>:S<n>`). Dropping one argument is acceptable; dropping a source ID is not, and filling a number from memory never is.",
+      "- Do not re-quote evidence -- cite the source ID. Do not recap the opponent before answering. No methodology preamble and no closing summary.",
+      "- One or two sentences per item: claim, figure, source, and what would break it.",
+      isReport
+        ? "- Every required report section must still be present and non-empty: terseness comes out of prose, never out of sections. Price levels and invalidation conditions may not be compressed to one line -- they are the only actionable part of the report."
+        : "- At most 6 arguments. Keep the six highest-information ones and drop the rest rather than shortening every one into a fragment.",
+      "- If there is not enough time to finish, hand in a short packet that names the gap rather than a complete-looking one built from memory.",
+    ].join("\n");
+  }
+  if (chinese) {
+    return [
+      "本轮按 slow 档运行。这一档买到的是把推导写完整的空间：",
+      "- 多步推算要逐步写出，把每一步的口径、假设与它对结论的敏感度都写明，而不是只给结果。",
+      "- 逐条处置对手的论点：哪一条你接受、哪一条你反驳、反驳依据的是哪个来源 ID 与哪个数字。",
+      "- 明确写出你自己的证伪条件：什么读数会让你放弃这条论点。",
+      "- 更长不等于更好：每一段要么带来新的数字，要么带来新的反驳。重复已说过的内容仍然要删。",
+    ].join("\n");
+  }
+  return [
+    "This round runs at the slow tier. What that budget buys is room to write the derivation out:",
+    "- Show multi-step arithmetic step by step, with the basis, the assumption and the sensitivity of the conclusion to each step, not just the result.",
+    "- Handle the opponent's arguments one by one: which you accept, which you refute, and on which source ID and figure the refutation rests.",
+    "- State your own falsification conditions explicitly: which reading would make you drop the argument.",
+    "- Longer is not better. Every paragraph must add either a new figure or a new refutation; repetition of what you already said still gets cut.",
+  ].join("\n");
+}
+
+export function taskPrompt(task, symbol, asOfDate, userPrompt = "", language = "auto", grounding = null, pace = null) {
   const resolvedLanguage = resolveLanguage({ language, prompt: userPrompt });
   const chinese = isChineseLanguage(resolvedLanguage);
   const reg = registry();
@@ -112,7 +172,13 @@ export function taskPrompt(task, symbol, asOfDate, userPrompt = "", language = "
   // which facts are already settled, or it reads them as the whole assignment.
   const instrumentOverride = fundOrIndexTaskInstruction(task, grounding?.instrument, resolvedLanguage);
   const grounded = groundingBlock(grounding, resolvedLanguage);
-  return [`${base}\n\n${chinese ? "任务：" : "Task: "}${task}\n${body}`, instrumentOverride, grounded].filter(Boolean).join("\n\n");
+  return [
+    `${base}\n\n${chinese ? "任务：" : "Task: "}${task}\n${body}`,
+    instrumentOverride,
+    grounded,
+    // Last, so it is the final word on form after the role brief and the settled facts.
+    paceShapingInstruction(pace, task, chinese),
+  ].filter(Boolean).join("\n\n");
 }
 
 export function debatePrompt(role, run, context = {}) {
@@ -190,6 +256,8 @@ export function debatePrompt(role, run, context = {}) {
       ].filter(Boolean).join("\n\n")
       : "",
     role === "portfolio_manager" && !quick ? outputModeInstruction(context.outputMode || "chat", language) : "",
+    // The tier's shaping is the final word on form. Quick has its own shaping already.
+    quick ? "" : paceShapingInstruction(run.council_pace, role, chinese),
     `Evidence JSON: ${evidenceJson}`,
   ].filter(Boolean).join("\n\n");
 }
@@ -269,8 +337,9 @@ export function masterVoicePrompt(masterId, run, frozenOpinion) {
     ].join(" "),
     `\`position_intent\` MUST be one of: ${intentsForStance(frozenOpinion?.stance).join(" | ")}. Those are the only intents the frozen stance admits; anything else is rejected without changing run state.`,
     "Return ONLY one valid JSON object, no Markdown fence. Schema: {\"master\":\"stable id\",\"acknowledged_stance\":\"constructive|cautious|opposed|out_of_scope\",\"position_intent\":\"one of the allowed intents above\",\"voice\":{\"what_i_see\":\"string\",\"how_my_method_reads_it\":\"string\",\"would_i_act\":\"string\",\"what_changes_my_mind\":\"string\",\"where_i_disagree\":\"string\"},\"key_findings\":[\"string\"],\"disagreements\":[\"string\"],\"what_would_change_my_mind\":[\"string\"],\"source_ids\":[\"task:S1\"],\"confidence\":\"high|medium|low\"}.",
+    paceShapingInstruction(run.council_pace, masterId, isChineseLanguage(language)),
     `Bounded shared evidence JSON: ${evidence}`,
-  ].join("\n\n");
+  ].filter(Boolean).join("\n\n");
 }
 
 /** The master ids a run has selected, from an explicit list or a roster name. */

package/mcp/lib/rpc.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import readline from "node:readline";
-import { COUNCIL_MODES, LIMITS, MASTER_STANCES, OUTPUT_MODES, QUICK_TASKS, SERVER_NAME, VERSION } from "./constants.mjs";
+import { COUNCIL_MODES, COUNCIL_PACE_NAMES, DEFAULT_COUNCIL_PACE, LIMITS, MASTER_STANCES, OUTPUT_MODES, QUICK_TASKS, SERVER_NAME, VERSION, councilPaceProfile } from "./constants.mjs";
 import { RpcCode, methodNotFound, invalidParams, toRpcError } from "./errors.mjs";
 import { readJson, readJsonl, writeJson } from "./fsutil.mjs";
 import { localized, resolveLanguage } from "./lang.mjs";
@@ -147,6 +147,36 @@ export function jsonContent(text, structuredContent = {}) {
   };
 }
 
+// Series history and per-fact lineage are the two unbounded parts of a grounding object: on one
+// real run they were 2.33 MB of a 2.54 MB plan payload, which exceeded the host's tool-result
+// limit and pushed the entire plan to a scratch file. They are already saved in evidence.json and
+// baked into every seat prompt, so the plan response replaces them with a pointer and a count.
+const BULK_GROUNDING_FIELDS = ["macro_series", "typed_fact_sources"];
+
+/**
+ * The grounding a plan response carries: the same object minus its two unbounded fields.
+ * Shape, flags and gap lists are preserved so a host can still read what was established.
+ */
+export function compactGrounding(run) {
+  const g = run?.grounding;
+  if (!g || typeof g !== "object") return g;
+  const compact = { ...g };
+  const omitted = [];
+  for (const field of BULK_GROUNDING_FIELDS) {
+    if (compact[field] === undefined) continue;
+    const count = Array.isArray(compact[field]) ? compact[field].length : Object.keys(compact[field] || {}).length;
+    omitted.push(`${field} (${count} entries)`);
+    delete compact[field];
+  }
+  if (!omitted.length) return compact;
+  compact.omitted_from_this_response = {
+    fields: omitted,
+    reason: "kept out of the plan payload for size; every seat prompt already carries them",
+    saved_to: join(runPath(run.run_id), "evidence.json"),
+  };
+  return compact;
+}
+
 export function tool(name, description, inputSchema, annotations = {}) {
   return { name, description, inputSchema, annotations };
 }
@@ -197,12 +227,34 @@ function startValidation(args, entryTool) {
       maximum_ms: LIMITS.QUICK_HARD_MAX_MS,
     });
   }
-  if (mode === "full" && args.total_timeout_ms > LIMITS.FULL_HARD_MAX_MS) {
-    throw invalidParams(`Full council total_timeout_ms cannot exceed ${LIMITS.FULL_HARD_MAX_MS}.`, {
-      reason: "FULL_TOTAL_TIMEOUT_EXCEEDS_MAX",
-      maximum_ms: LIMITS.FULL_HARD_MAX_MS,
+  if (args.council_pace !== undefined && !COUNCIL_PACE_NAMES.includes(String(args.council_pace))) {
+    throw invalidParams(`council_pace must be one of ${COUNCIL_PACE_NAMES.join(", ")}.`, {
+      reason: "INVALID_COUNCIL_PACE",
+      allowed: COUNCIL_PACE_NAMES,
+    });
+  }
+  if (mode === "quick" && args.council_pace !== undefined) {
+    throw invalidParams("council_pace applies to the full council only. Quick is a smaller contract, not a slower one.", {
+      reason: "QUICK_PACE_FORBIDDEN",
     });
   }
+  // A call is held to its own pace's budget, not to the outer bound of the schema: asking for
+  // an hour at the fast pace would buy idle time, because what bounds each worker is its
+  // per-stage cap and those are set by the pace.
+  if (mode === "full" && args.total_timeout_ms !== undefined) {
+    const profile = councilPaceProfile(args.council_pace);
+    if (args.total_timeout_ms > profile.total_ms) {
+      throw invalidParams(
+        `Full council total_timeout_ms cannot exceed ${profile.total_ms} at the ${profile.pace} pace. Raise council_pace to buy more time.`,
+        {
+          reason: "FULL_TOTAL_TIMEOUT_EXCEEDS_MAX",
+          council_pace: profile.pace,
+          maximum_ms: profile.total_ms,
+          paces: Object.fromEntries(COUNCIL_PACE_NAMES.map((name) => [name, councilPaceProfile(name).total_ms])),
+        },
+      );
+    }
+  }
   if (mode === "quick" && args.synthesis === false) {
     throw invalidParams("Quick council requires its one-round bull/bear and portfolio-manager synthesis.", {
       reason: "QUICK_SYNTHESIS_REQUIRED",
@@ -263,12 +315,30 @@ function selectedRunArgs(args = {}, entryTool) {
       prompt: typeof args.prompt === "string" ? args.prompt : "",
       council_mode: args.council_mode || "full",
     });
+    // The pace was approved at the gate, so the receipt is authoritative: an execution call may
+    // repeat it but not change it. Otherwise a user could approve fifteen minutes and get an
+    // hour, or the reverse, with nothing in the record showing the switch.
+    if (args.council_pace !== undefined
+      && selection.council_pace
+      && String(args.council_pace) !== String(selection.council_pace)) {
+      throw invalidParams(
+        `council_pace ${args.council_pace} does not match the pace confirmed at the selection gate (${selection.council_pace}).`,
+        {
+          reason: "COUNCIL_PACE_RECEIPT_MISMATCH",
+          confirmed_council_pace: selection.council_pace,
+          submitted_council_pace: String(args.council_pace),
+          remedy: "Send the confirmed pace or start a new selection to change it.",
+        },
+      );
+    }
     return {
       ...args,
       run_id: id,
       entry_tool: entryTool,
       masters: selection.selected_master_ids,
       master_selection: selection,
+      // The gate's decision wins when the caller omitted it.
+      council_pace: args.council_pace ?? selection.council_pace ?? undefined,
       existing_run: existing,
       release_run_lock: releaseRunLock,
     };
@@ -400,10 +470,16 @@ export function tools() {
     timeout_ms: { type: "number", default: LIMITS.CODEX_TIMEOUT_MS },
     synthesis: { type: "boolean", default: true, description: "Run bull, bear, and portfolio-manager synthesis after evidence collection." },
     synthesis_timeout_ms: { type: "number", default: LIMITS.CODEX_TIMEOUT_MS },
+    council_pace: {
+      type: "string",
+      enum: COUNCIL_PACE_NAMES,
+      default: DEFAULT_COUNCIL_PACE,
+      description: "Full-council depth/time tier. fast = 15 minutes, normal = 30, slow = 60. The tier sets the total budget AND every per-stage cap together: slow gives each evidence seat 12 minutes instead of 6 and each debate round 6 minutes per side instead of 150 seconds, which is where the extra depth comes from. Raising total_timeout_ms alone buys idle time, not depth. Quick rejects this field.",
+    },
     total_timeout_ms: {
       type: "number",
       maximum: LIMITS.FULL_HARD_MAX_MS,
-      description: "Hard queue-to-persistence wall-clock budget. quick defaults to and cannot exceed ten minutes; full defaults to and cannot exceed thirty minutes. Callers may lower the applicable ceiling, never raise it.",
+      description: "Hard queue-to-persistence wall-clock budget. Cannot exceed the selected council_pace's total (fast 900000, normal 1800000, slow 3600000) or ten minutes for quick. Callers may lower the applicable ceiling, never raise it.",
     },
     output_mode: { type: "string", enum: OUTPUT_MODES, default: "public_equity", description: "Final synthesis target shape." },
     selection_receipt: { type: "string", description: "One-run receipt returned by confirm_master_selection. Required for every council run and consumed exactly once." },
@@ -426,6 +502,11 @@ export function tools() {
           items: { type: "string", enum: masterIds },
           description: "Optional stable IDs inferred from masters explicitly named in the request. They are highlighted only; the user must still submit this run's selection.",
         },
+        council_pace: {
+          type: "string",
+          enum: COUNCIL_PACE_NAMES,
+          description: "Prefill only, when the request already named a speed such as fast or slow. It highlights that tier in the returned pace_options and never confirms one. Full only.",
+        },
       },
       required: ["symbol"],
     }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }),
@@ -438,6 +519,11 @@ export function tools() {
         selected_master_ids: { type: "array", minItems: 1, uniqueItems: true, items: { type: "string", enum: masterIds } },
         select_all: { type: "boolean", const: true },
         selection: { type: "string", minLength: 1, description: "Text fallback: stable numbers/ranges/IDs, or all." },
+        council_pace: {
+          type: "string",
+          enum: COUNCIL_PACE_NAMES,
+          description: "The depth tier the user picked from the pace_options this selection returned. Full only; omit to accept the default (normal, ~20 min expected, 30 min ceiling). Binds into the receipt, so an execution call may repeat it but never change it.",
+        },
       },
       required: ["selection_id", "catalog_hash", "display_ack"],
       oneOf: [
@@ -793,7 +879,7 @@ export async function handleToolCall(id, params) {
         + `Network preflight: ${preflight.status}. `
         + `Established facts: ${run.grounding && !run.grounding.facts_unavailable ? "attached to every seat" : "UNAVAILABLE -- seats will run without filings or quotes, say so in the report"}.`,
         {
-          run,
+          run: { ...run, grounding: compactGrounding(run) },
           idempotent_replay: Boolean(runArgs.existing_run),
           preflight,
           ...specs,

package/mcp/lib/run-store.mjs

@@ -70,6 +70,9 @@ export function statusSnapshot(run) {
     language: run.language,
     execution_mode: run.execution_mode,
     council_mode: run.council_mode || "full",
+    // Which depth/time tier produced this run. Two runs of the same symbol at different paces
+    // are not the same analysis, so the pace belongs in the audit record beside the budget.
+    council_pace: run.council_pace || null,
     debate_format: run.debate_format || "three_round_cross_exam",
     visible_debate_contract: visibleDebate?.contract || null,
     visible_debate_rounds_expected: visibleDebate?.rounds_expected || null,

package/mcp/lib/screen.mjs

@@ -17,6 +17,21 @@ const pct = (x) => (x === null ? null : Number((x * 100).toFixed(2)));
 const last = (series, n) => series.slice(-n);
 const sum = (xs) => xs.reduce((a, b) => a + b, 0);
 
+/**
+ * Pair two annual series by fiscal period end, newest last, capped at n pairs.
+ *
+ * Pairing by array position instead put every year after a gap onto the wrong
+ * counterpart -- a filer that stopped tagging InterestExpense had this year's EBIT
+ * divided by a two-year-old interest figure, and an equity series missing one middle
+ * year shifted a decade of ROE by one year -- while the provenance block still showed
+ * a clean range. A year present on only one side is dropped, never matched to a
+ * neighbour; the pair count is what the rule reports as its coverage.
+ */
+const pairByEnd = (a, b, n) => {
+  const byEnd = new Map(b.map((row) => [row.end, row]));
+  return a.filter((row) => byEnd.has(row.end)).slice(-n).map((row) => [row, byEnd.get(row.end)]);
+};
+
 /**
  * XBRL reports share counts under the `shares` unit, not `USD`. Requesting the default unit
  * for a share concept returns nothing, so the dilution rule reported `skipped` for every
@@ -117,41 +132,36 @@ export function evaluateRules(facts, { asOf = null } = {}) {
   };
 
   add("roe_10y", { en: "10-year average ROE", zh: "10年平均ROE" }, () => {
-    const ni = last(netIncome, 10);
-    const eq = last(equity, 10);
-    if (ni.length < 5 || eq.length < 5) return null;
-    const n = Math.min(ni.length, eq.length);
-    const roes = [];
-    for (let i = 0; i < n; i += 1) {
-      const e = eq[eq.length - n + i].val;
-      if (e > 0) roes.push(ni[ni.length - n + i].val / e);
-    }
+    const pairs = pairByEnd(netIncome, equity, 10);
+    if (pairs.length < 5) return null;
+    const roes = pairs.filter(([, e]) => e.val > 0).map(([n, e]) => n.val / e.val);
     if (roes.length < 5) return null;
     const avg = sum(roes) / roes.length;
     return {
       passed: avg >= 0.08, value: pct(avg), unit: "%", threshold: 8, direction: "min", years: roes.length,
-      ...ruleProvenance([ni.slice(-n), eq.slice(-n)]),
+      ...ruleProvenance([pairs.map(([n]) => n), pairs.map(([, e]) => e)]),
     };
   });
 
   add("fcf_5y", { en: "5-year cumulative free cash flow", zh: "5年累计自由现金流" }, () => {
-    const o = last(ocf, 5);
-    const c = last(capex, 5);
-    if (o.length < 3 || c.length < 3) return null;
-    const n = Math.min(o.length, c.length);
-    const total = sum(o.slice(-n).map((x) => x.val)) - sum(c.slice(-n).map((x) => x.val));
+    const pairs = pairByEnd(ocf, capex, 5);
+    if (pairs.length < 3) return null;
+    const total = sum(pairs.map(([o, c]) => o.val - c.val));
     // Raw dollars, not billions rounded to two places: rounding erased the entire figure
     // for anything below ~$5m, which is most of the small-cap universe.
     return {
-      passed: total >= 0, value: Math.round(total), unit: "USD", threshold: 0, direction: "min", years: n,
-      ...ruleProvenance([o.slice(-n), c.slice(-n)]),
+      passed: total >= 0, value: Math.round(total), unit: "USD", threshold: 0, direction: "min", years: pairs.length,
+      ...ruleProvenance([pairs.map(([o]) => o), pairs.map(([, c]) => c)]),
     };
   });
 
   add("interest_cover", { en: "EBIT / interest cover", zh: "利息保障倍数" }, () => {
-    const ebit = last(operatingIncome, 1)[0];
-    const int = last(interest, 1)[0];
-    if (!ebit || !int || int.val === 0) return null;
+    // The interest figure must belong to the same period as the latest EBIT. A filer that
+    // stops tagging InterestExpense gets a skip here, not a ratio built on old debt.
+    const pairs = pairByEnd(last(operatingIncome, 1), interest, 1);
+    if (!pairs.length) return null;
+    const [ebit, int] = pairs[0];
+    if (int.val === 0) return null;
     const cover = ebit.val / Math.abs(int.val);
     return {
       passed: cover >= 2, value: Number(cover.toFixed(2)), unit: "x", threshold: 2, direction: "min",
@@ -160,48 +170,38 @@ export function evaluateRules(facts, { asOf = null } = {}) {
   });
 
   add("gross_margin", { en: "long-run gross margin", zh: "长期毛利率" }, () => {
-    const gp = last(grossProfit, 5);
-    const rev = last(revenue, 5);
-    if (gp.length < 3 || rev.length < 3) return null;
-    const n = Math.min(gp.length, rev.length);
-    const margins = [];
-    for (let i = 0; i < n; i += 1) {
-      const r = rev[rev.length - n + i].val;
-      if (r > 0) margins.push(gp[gp.length - n + i].val / r);
-    }
+    const pairs = pairByEnd(grossProfit, revenue, 5);
+    if (pairs.length < 3) return null;
+    const margins = pairs.filter(([, r]) => r.val > 0).map(([g, r]) => g.val / r.val);
     if (!margins.length) return null;
     const avg = sum(margins) / margins.length;
     return {
       passed: avg >= 0.15, value: pct(avg), unit: "%", threshold: 15, direction: "min", years: margins.length,
-      ...ruleProvenance([gp.slice(-n), rev.slice(-n)]),
+      ...ruleProvenance([pairs.map(([g]) => g), pairs.map(([, r]) => r)]),
     };
   });
 
   add("ocf_over_ni", { en: "5-year OCF / net income", zh: "5年经营现金流/净利" }, () => {
-    const o = last(ocf, 5);
-    const ni = last(netIncome, 5);
-    if (o.length < 3 || ni.length < 3) return null;
-    const n = Math.min(o.length, ni.length);
-    const totalNi = sum(ni.slice(-n).map((x) => x.val));
+    const pairs = pairByEnd(ocf, netIncome, 5);
+    if (pairs.length < 3) return null;
+    const totalNi = sum(pairs.map(([, n]) => n.val));
     if (totalNi <= 0) return null;
-    const ratio = sum(o.slice(-n).map((x) => x.val)) / totalNi;
+    const ratio = sum(pairs.map(([o]) => o.val)) / totalNi;
     return {
-      passed: ratio >= 0.7, value: Number(ratio.toFixed(2)), unit: "x", threshold: 0.7, direction: "min", years: n,
-      ...ruleProvenance([o.slice(-n), ni.slice(-n)]),
+      passed: ratio >= 0.7, value: Number(ratio.toFixed(2)), unit: "x", threshold: 0.7, direction: "min", years: pairs.length,
+      ...ruleProvenance([pairs.map(([o]) => o), pairs.map(([, n]) => n)]),
     };
   });
 
   add("net_margin", { en: "long-run net margin", zh: "长期净利率" }, () => {
-    const ni = last(netIncome, 5);
-    const rev = last(revenue, 5);
-    if (ni.length < 3 || rev.length < 3) return null;
-    const n = Math.min(ni.length, rev.length);
-    const totalRev = sum(rev.slice(-n).map((x) => x.val));
+    const pairs = pairByEnd(netIncome, revenue, 5);
+    if (pairs.length < 3) return null;
+    const totalRev = sum(pairs.map(([, r]) => r.val));
     if (totalRev <= 0) return null;
-    const margin = sum(ni.slice(-n).map((x) => x.val)) / totalRev;
+    const margin = sum(pairs.map(([n]) => n.val)) / totalRev;
     return {
-      passed: margin >= 0.05, value: pct(margin), unit: "%", threshold: 5, direction: "min", years: n,
-      ...ruleProvenance([ni.slice(-n), rev.slice(-n)]),
+      passed: margin >= 0.05, value: pct(margin), unit: "%", threshold: 5, direction: "min", years: pairs.length,
+      ...ruleProvenance([pairs.map(([n]) => n), pairs.map(([, r]) => r)]),
     };
   });
 

package/mcp/lib/sec.mjs

@@ -97,20 +97,35 @@ export async function fetchFilingIndex(cik, { signal } = {}) {
   return { cik: padded, name: data?.name || null, filings: rows };
 }
 
-/** One filing document, fetched as text. Same throttle and User-Agent as every other call. */
+/**
+ * One filing document, fetched as text. Same throttle, User-Agent and 429 backoff as the JSON
+ * calls.
+ *
+ * The backoff was the part missing here. Every JSON endpoint retried a rate-limited response
+ * while this one threw on the first 429, so the documents that carry the actual disclosure --
+ * a Form 4's transaction table, an 8-K's item text -- were the easiest evidence in the run to
+ * lose. `www.sec.gov/Archives` is also throttled harder than `data.sec.gov`, which makes this
+ * the path most likely to be limited and was the least protected against it.
+ */
 export async function fetchFilingDocument(cik, accession, document, { signal } = {}) {
-  await throttle();
   const stripped = String(cik).replace(/\D/gu, "").replace(/^0+/u, "");
   const folder = String(accession).replace(/-/gu, "");
   const url = `https://www.sec.gov/Archives/edgar/data/${stripped}/${folder}/${document}`;
-  const abort = linkedAbort(LIMITS.QUOTE_FETCH_MS * 2, signal);
-  try {
-    const res = await fetch(url, { signal: abort.signal, headers: { "User-Agent": UA } });
-    if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
-    return { url, text: await res.text() };
-  } finally {
-    abort.cleanup();
-  }
+  const outcome = await withRateLimitRetry(async () => {
+    await throttle();
+    const abort = linkedAbort(LIMITS.QUOTE_FETCH_MS * 2, signal);
+    try {
+      const res = await fetch(url, { signal: abort.signal, headers: { "User-Agent": UA } });
+      if (isRateLimited(res.status)) {
+        return { rateLimited: true, error: new Error(`HTTP ${res.status} for ${url}`) };
+      }
+      if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+      return { rateLimited: false, value: { url, text: await res.text() } };
+    } finally {
+      abort.cleanup();
+    }
+  });
+  return outcome.value;
 }
 
 /** The full US listed universe: ~10k entries of {cik, ticker, title}. */

package/mcp/lib/voice-from-decision.mjs

@@ -119,8 +119,11 @@ function copyFor(language) {
  *
  * `result` is the frozen `structured_decision.result`; `policy` is the seat's decision policy,
  * which supplies the human-readable condition ids the result refers to by index.
+ * `readableIds` maps each anonymised id back to the declared one exactly; prefer it over the
+ * positional fallback, which assumes the executor's hits/misses/uncomputable split happens to
+ * come back in declaration order and silently swaps two condition names when it does not.
  */
-export function voiceFromDecision({ result, policy, factPack, language = "English" } = {}) {
+export function voiceFromDecision({ result, policy, factPack, readableIds, language = "English" } = {}) {
   const copy = copyFor(language);
   const facts = new Map((factPack?.facts || []).map((fact) => [fact.fact_id, fact]));
   const stance = result?.common_projection?.stance || "out_of_scope";
@@ -136,7 +139,7 @@ export function voiceFromDecision({ result, policy, factPack, language = "Englis
   const computed = (result?.computations?.trace || [])
     .filter((step) => step.status === "computed" && finite(step.value))
     .slice(0, MAX_ITEMS)
-    .map((step) => `${step.output_id} = ${Number(step.value.toFixed(4))}`)
+    .map((step) => `${readableIds?.get?.(step.output_id) || step.output_id} = ${Number(step.value.toFixed(4))}`)
     .join("; ");
 
   // The executor publishes the rules it evaluated already split into hits, misses and the ones
@@ -157,13 +160,18 @@ export function voiceFromDecision({ result, policy, factPack, language = "Englis
     .map((rule) => rule.rule_id)
     .filter(Boolean)
     .map((id, index) => [id, index]));
+  const declaredName = (anon) => (anon && readableIds?.get?.(anon)) || null;
   const ruleName = (rule) => {
     const anon = rule.rule_id || rule.id;
-    const readable = readableRuleIds.get(anonOrder.get(anon));
-    return readable || anon || "rule";
+    return declaredName(anon) || readableRuleIds.get(anonOrder.get(anon)) || anon || "rule";
   };
 
-  const vetoes = (result?.vetoes_triggered || []).map((veto) => veto.veto_id).filter(Boolean);
+  // Vetoes went unmapped, so a hashed veto reached the reader while the scoring conditions
+  // beside it were readable. That asymmetry is what made two seats speculate about their own
+  // hard veto instead of naming it.
+  const vetoes = (result?.vetoes_triggered || [])
+    .map((veto) => declaredName(veto.veto_id) || veto.veto_id)
+    .filter(Boolean);
 
   const whatISee = [
     readList ? copy.readFacts(readList) : copy.noFacts,

package/mcp/lib/weights.mjs

@@ -76,8 +76,15 @@ export function resolveSeatWeights(run, overrides = {}) {
 
   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]) {
+  // Evidence seats belong here too. The contract says a failed verification down-weights the
+  // seat that made the claim, but the enumeration stopped at debate and master seats, so a
+  // `contradicted` verdict against an analyst was recorded and then silently ignored.
+  const evidenceIds = [
+    ...(run.tasks || []),
+    ...(run.verifier_verdicts || []).map((v) => v?.seat).filter(Boolean),
+  ];
+
+  for (const id of new Set([...debateIds, ...masterIds, ...evidenceIds])) {
     const persona = reg.get(id);
     if (!persona) continue;
     const declared = baseWeight(persona);

package/mcp/lib/xbrl-series.mjs

@@ -29,9 +29,14 @@ export const MAX_ALIGNMENT_DRIFT_DAYS = 45;
 /**
  * Concept aliases, ordered by preference, on top of the ones sec.mjs already publishes.
  *
- * Aliases inside one entry are the same economic quantity under different taxonomies. They
- * are never a fallback to a different concept: total liabilities is not reconstructed from
- * an equity subtraction, and a missing depreciation tag stays missing.
+ * Aliases inside one entry are the same economic quantity under different taxonomies. They are
+ * never a fallback to a different concept: a missing depreciation tag stays missing.
+ *
+ * Total liabilities has one sanctioned reconstruction and it is guarded. Subtracting equity
+ * from the balance-sheet total is wrong when the two tags disagree about non-controlling
+ * interests -- the difference then lands inside "liabilities", silently. Done against the
+ * INCLUDING-NCI equity tag the identity is exact, so that tag, and only that tag, may stand in
+ * where a filer never tags `Liabilities` directly. See `totalLiabilitiesFor`.
  */
 export const FUNDAMENTAL_CONCEPTS = Object.freeze({
   revenue: { tags: CONCEPTS.revenue, unit: "USD" },
@@ -50,6 +55,8 @@ export const FUNDAMENTAL_CONCEPTS = Object.freeze({
   },
   current_assets: { tags: ["AssetsCurrent"], unit: "USD" },
   total_liabilities: { tags: ["Liabilities"], unit: "USD" },
+  liabilities_and_equity: { tags: ["LiabilitiesAndStockholdersEquity"], unit: "USD" },
+  equity_including_nci: { tags: ["StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest"], unit: "USD" },
   goodwill: { tags: ["Goodwill"], unit: "USD" },
   intangibles: { tags: ["IntangibleAssetsNetExcludingGoodwill", "FiniteLivedIntangibleAssetsNet"], unit: "USD" },
   cash: {
@@ -61,9 +68,28 @@ export const FUNDAMENTAL_CONCEPTS = Object.freeze({
   },
   // Debt buckets are non-overlapping by construction so they can be summed. `debt_combined`
   // is the whole of it in one tag and wins outright when a filer publishes it.
+  //
+  // Within a bucket the tags are ALIASES, not addends: an earlier alias wins a year outright.
+  // The convertible aliases are therefore appended last, which makes them strictly additive --
+  // a filer that already resolves a bucket resolves it to exactly the same number as before,
+  // and only a filer whose sole balance-sheet debt line is a convertible note changes at all.
+  //
+  // That filer is not rare. ServiceNow's FY2020 and FY2025 balance sheets carry no straight
+  // debt tag whatsoever: the only debt instant either year is ConvertibleLongTermNotesPayable
+  // ($1.64bn and $1.491bn). Total debt therefore read as unknown, and because unknown debt is
+  // correctly refused rather than treated as zero, three separate facts died from one absent
+  // alias -- leverage, downside asset value, and incremental return on capital -- which in turn
+  // is why a seat requiring incremental return on capital abstained on a company whose debt is
+  // plainly stated on the face of its balance sheet.
   debt_combined: { tags: ["DebtLongtermAndShorttermCombinedAmount"], unit: "USD" },
-  debt_long_term_noncurrent: { tags: ["LongTermDebtNoncurrent", "LongTermDebtAndCapitalLeaseObligations"], unit: "USD" },
-  debt_long_term_current: { tags: ["LongTermDebtCurrent", "LongTermDebtAndCapitalLeaseObligationsCurrent"], unit: "USD" },
+  debt_long_term_noncurrent: {
+    tags: ["LongTermDebtNoncurrent", "LongTermDebtAndCapitalLeaseObligations", "ConvertibleLongTermNotesPayable"],
+    unit: "USD",
+  },
+  debt_long_term_current: {
+    tags: ["LongTermDebtCurrent", "LongTermDebtAndCapitalLeaseObligationsCurrent", "ConvertibleNotesPayableCurrent"],
+    unit: "USD",
+  },
   debt_short_term: { tags: ["ShortTermBorrowings", "OtherShortTermBorrowings", "CommercialPaper"], unit: "USD" },
   tax_expense: { tags: ["IncomeTaxExpenseBenefit"], unit: "USD" },
   pretax_income: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alphacouncil-agent",
-  "version": "1.0.3",
+  "version": "1.0.13",
   "description": "Multi-agent company, ETF and market-index research workflow for Codex & Claude Code: sourced evidence, method seats, bull/bear debate and portfolio-manager synthesis.",
   "type": "module",
   "license": "MIT",
@@ -127,6 +127,7 @@
     ".opencode/command/",
     ".grok/commands/",
     "docs/INSTALL.md",
+    "docs/examples/",
     "docs/plans/",
     "docs/releases/",
     "docs/evaluation/",