alphacouncil-agent 1.0.4 → 1.0.13

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

@@ -68,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.4",
+  "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/",

package/personas/analysts/insider_sec.md

@@ -55,6 +55,25 @@
 四、**股权稀释**
 在外流通股数的多年变化。持续稀释会让每股口径的所有增长打折，而这一点在讨论增长时常被忽略。
 
+## 怎么取到原文（EDGAR 会限流，这一节决定这个席位有没有真凭据）
+
+EDGAR 对没有描述性 User-Agent 的客户端返回 **HTTP 429**，而且 `www.sec.gov` 比 `data.sec.gov` 限得更狠。**连续换 URL 猛试只会让限流变严**——一次真实运行里连试 8 个不同 URL 全部 429，最后一份原文都没读到。
+
+按这个顺序取，取到就停：
+
+1. `https://data.sec.gov/submissions/CIK##########.json`（10 位补零）—— 申报索引，JSON API 最宽容，一次拿到全部表单类型、accession 与 filed date。
+2. `https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json` —— 股数、股东权益这类 XBRL 数字。
+3. `https://www.sec.gov/Archives/edgar/data/<无前导零CIK>/<去横线accession>/<主文档>` —— 具体那一份 Form 4 / 8-K 原文。
+4. EDGAR 全文检索与 `cgi-bin/browse-edgar` **放到最后**：它们最容易被限流，且能给的信息前三步都能给。
+
+遇到 429：**停下来等几秒再重试同一个 URL**，不要立刻换别的 URL。同一份文档最多重试三次；三次都 429 就记为取回失败，进入下面的降级纪律。
+
+**降级纪律（必须照做，不许含糊）**：一份原文都没读到时，
+- `summary` 第一句就写明「本包未直读任何 EDGAR 原文，全部内容经二级来源交叉核实」；
+- `confidence` 最高只能是 `low`；
+- 在 `open_questions` 里逐条列出失败的 URL 与状态码；
+- 每条来自镜像/聚合站的内容都标注它是二手，**绝不能把镜像内容写成「已按申报原文核实」**。
+
 ## 硬纪律
 
 - **每条必须带申报链接和申报日期**（filed date，不是期间结束日）。
@@ -87,6 +106,25 @@ Key items: 1.01 material agreement, 2.02 results, 4.01 auditor change, 4.02 prio
 4. **Dilution**
 Shares outstanding across several years. Persistent dilution discounts every per-share growth figure, and that is routinely ignored in growth discussions.
 
+## How to actually retrieve the filings (EDGAR throttles; this section decides whether this seat has primary evidence at all)
+
+EDGAR answers **HTTP 429** to a client without a descriptive User-Agent, and `www.sec.gov` is throttled harder than `data.sec.gov`. **Rapidly trying different URLs makes the throttling worse, not better** -- on one real run eight different URLs were tried in a row, all returned 429, and not a single filing was read.
+
+Retrieve in this order and stop as soon as you have what you need:
+
+1. `https://data.sec.gov/submissions/CIK##########.json` (CIK zero-padded to ten digits) -- the filing index. The most tolerant endpoint, and one call returns every form type, accession number and filed date.
+2. `https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json` -- XBRL numbers such as share count and stockholders' equity.
+3. `https://www.sec.gov/Archives/edgar/data/<CIK without leading zeros>/<accession without dashes>/<primary document>` -- the specific Form 4 or 8-K text.
+4. EDGAR full-text search and `cgi-bin/browse-edgar` **last**: they are throttled the hardest and tell you nothing the first three cannot.
+
+On a 429: **wait a few seconds and retry the same URL** rather than immediately switching to a different one. Retry one document at most three times; if all three are limited, record the retrieval as failed and follow the degradation rule below.
+
+**Degradation rule (mandatory, and not to be softened)** -- when no filing was read directly:
+- the first sentence of `summary` must state that no EDGAR original was read and that everything was cross-checked through secondary sources instead;
+- `confidence` is capped at `low`;
+- `open_questions` lists each failed URL with its status code;
+- every item taken from a mirror or aggregator is labelled second-hand. **Never write mirror content as "verified against the filing".**
+
 ## Hard rules
 
 - **Every item carries the filing link and the filed date** -- the filed date, not the period end.

package/scripts/lib/persona-v3-solo-test-packs.mjs

@@ -501,21 +501,27 @@ function buildDocuments({ seat, blueprint, rawTools, packVersion, formulaManifes
         ja: `${publicTitle.en} 単独テスト`,
         ko: `${publicTitle.en} 단독 테스트`,
       },
+      // The owner reviewed and accepted these method attributions, so the catalog title no
+      // longer repeats a review-status warning next to every name. The machine-verified
+      // admission level is unchanged and still published; the label is just the method's name.
       operator_label: {
-        en: `${publicTitle.en} Provisional Operator Lens`,
-        zh: `${publicTitle.zh}临时操作视角`,
-        ja: `${publicTitle.en} 暫定オペレーター・レンズ`,
-        ko: `${publicTitle.en} 임시 오퍼레이터 렌즈`,
+        en: publicTitle.en,
+        zh: publicTitle.zh,
+        ja: `${publicTitle.en}・メソッドレンズ`,
+        ko: `${publicTitle.en} 방법론 렌즈`,
       },
       maturity: "operator_lens",
       source_cutoff: SOURCE_DATE,
     },
     selection: {
+      // What a seat IS, not its review history. "Not the person's own words" stays because it
+      // guards against impersonation; the review-status clause is gone because the owner signed
+      // off on these attributions and a warning repeated 27 times stops being a warning.
       identity: {
-        en: `${publicTitle.en}; project-derived and not human reviewed`,
-        zh: `${publicTitle.zh}；项目派生、未经人工审定`,
-        ja: `${publicTitle.en}。プロジェクト派生で、方法帰属について人による審査を受けていない暫定オペレーター・レンズ。本人の発言や現在の見解ではない。`,
-        ko: `${publicTitle.en}. 프로젝트에서 파생되었고 방법 귀속에 대한 인적 심사를 거치지 않은 임시 오퍼레이터 렌즈다. 본인의 발언이나 현재 견해가 아니다.`,
+        en: `${publicTitle.en}; a method model, not the person's own words`,
+        zh: `${publicTitle.zh}；方法模型，非本人言论`,
+        ja: `${publicTitle.en}。メソッドモデルであり、本人の発言や現在の見解ではない。`,
+        ko: `${publicTitle.en}. 방법론 모델이며, 본인의 발언이나 현재 견해가 아니다.`,
       },
       method: {
         en: seat.method_scope.planning_hypothesis,

package/scripts/review-persona-v3-solo-formulas.mjs

@@ -46,8 +46,8 @@ export function usage() {
   return [
     "Usage: node scripts/review-persona-v3-solo-formulas.mjs [--check|--plan|--write] [--json]",
     "",
-    "--plan         recompute 52 machine review records without reading the review tree",
-    "--write        write 52 reviews plus the manifest below isolated staging",
+    "--plan         recompute the planned machine review records without reading the review tree",
+    "--write        write every planned review plus the manifest below isolated staging",
     "--check        require exact physical files and byte-stable recomputation (default)",
     "--formula-root override the physical solo-test formula tree",
     "--review-root  override the isolated AI review tree",
@@ -93,7 +93,9 @@ export function main(argv = process.argv.slice(2)) {
   if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   else process.stdout.write(compact(result));
   const okay = result.review_count === PLANNED_TOOL_COUNT
-    && result.role_count === 156
+    // Derived, not hardcoded: the literal 156 (26 seats x 2 tools x 3 roles) survived the
+    // twenty-seventh seat and failed a review tree its own output line printed as 162/162.
+    && result.role_count === PLANNED_TOOL_COUNT * INDEPENDENT_ROLES_PER_REVIEW
     && result.mechanical_pass_count === PLANNED_TOOL_COUNT
     && result.disagreement_count === 0
     && result.semantic_unknown_count === PLANNED_TOOL_COUNT