alphacouncil-agent 0.9.2 → 1.0.0

package/mcp/lib/personas-v3/staging.mjs

@@ -25,7 +25,6 @@ import { canonicalJson, canonicalValue, sha256 } from "./canonical.mjs";
 import { canDefineMethodRule, validateSourceAnchor } from "./source-anchor.mjs";
 import { defaultKnowledgeDir } from "./admission.mjs";
 
-export const CANONICAL_MASTER_COUNT = 26;
 export const CANONICAL_MASTER_IDS = Object.freeze([
   "master_aschenbrenner",
   "master_buffett",
@@ -53,8 +52,12 @@ export const CANONICAL_MASTER_IDS = Object.freeze([
   "master_taleb",
   "master_natenberg",
   "master_sinclair",
+  "master_bogle",
 ]);
 
+/** Derived, never written twice: the roster above is the only place a seat is added. */
+export const CANONICAL_MASTER_COUNT = CANONICAL_MASTER_IDS.length;
+
 export const STAGING_COMPONENTS = Object.freeze([
   "sources",
   "doctrine",
@@ -316,6 +319,22 @@ function writeNew(file, content, created, existing) {
   created.push(file);
 }
 
+/**
+ * The seat index is derived from the canonical roster, not authored, so refusing to overwrite
+ * it -- which is the right rule for every other file here -- would leave a seat addition
+ * permanently unrepresentable without a manual delete.
+ */
+function writeDerived(file, content, created, existing) {
+  mkdirSync(dirname(file), { recursive: true });
+  const present = existsSync(file);
+  if (present && readFileSync(file, "utf8") === content) {
+    existing.push(file);
+    return;
+  }
+  writeFileSync(file, content, "utf8");
+  (present ? existing : created).push(file);
+}
+
 function prettyJson(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -329,7 +348,7 @@ export function scaffoldPersonaV3Staging({
   const blueprints = canonicalMasterBlueprints({ personaDir });
   const created = [];
   const existing = [];
-  writeNew(join(stagingRoot, INDEX_FILE), prettyJson(createStagingIndex(blueprints)), created, existing);
+  writeDerived(join(stagingRoot, INDEX_FILE), prettyJson(createStagingIndex(blueprints)), created, existing);
   writeNew(join(stagingRoot, TEMPLATE_DIR, "source-adjudication-record.template.json"), prettyJson(sourceRecordTemplate()), created, existing);
   writeNew(join(stagingRoot, TEMPLATE_DIR, "human-review-checklist.md"), reviewChecklist(), created, existing);
   for (const blueprint of blueprints) {
@@ -520,7 +539,7 @@ export function inspectPersonaV3Staging({
   else {
     const actualIndex = parseJson(indexFile, INDEX_FILE);
     const expectedIndex = createStagingIndex(blueprints);
-    if (canonicalJson(actualIndex) !== canonicalJson(expectedIndex)) globalErrors.push(`${INDEX_FILE} does not match the canonical 26-seat registry`);
+    if (canonicalJson(actualIndex) !== canonicalJson(expectedIndex)) globalErrors.push(`${INDEX_FILE} does not match the canonical seat registry`);
   }
 
   const expectedIds = new Set(CANONICAL_MASTER_IDS);

package/mcp/lib/prompts.mjs

@@ -1,11 +1,13 @@
 import { join } from "node:path";
-import { isChineseLanguage, resolveLanguage } from "./lang.mjs";
+import { isChineseLanguage, localized, resolveLanguage } from "./lang.mjs";
 import { runPath } from "./run-store.mjs";
 import { compactDebateContext, compactEvidence, compactMasterOpinions, compactQuickEvidence } from "./packets.mjs";
 import { outputModeInstruction } from "./output-modes.mjs";
 import { resolveSeatWeights, weightTableMarkdown } from "./weights.mjs";
 import { groundingBlock } from "./grounding.mjs";
+import { isFundOrIndex } from "./instruments.mjs";
 import { personaPrompt, personaTitle, registry, selectRoster } from "./personas/registry.mjs";
+import { intentsForStance } from "./voice.mjs";
 
 /**
  * Prompt text lives in personas/, not here.
@@ -22,6 +24,73 @@ function render(template, values) {
     (Object.prototype.hasOwnProperty.call(values, key) ? String(values[key] ?? "") : match));
 }
 
+function fundOrIndexTaskInstruction(task, instrument, language) {
+  if (!isFundOrIndex(instrument)) return "";
+  const type = instrument.asset_type || "fund_or_index";
+  const details = {
+    market_data: {
+      en: "Establish the tracked index or calculation methodology, holdings/constituent as-of date, weights, top-ten and sector concentration, fee or index rules, AUM where applicable, liquidity/spread, premium-discount or tracking difference, and dated flows. Separate missing fields.",
+      zh: "查清跟踪指数或计算方法、持仓/成分时点、权重、前十大和行业集中度、费率或指数规则、适用时的规模、流动性/点差、溢折价或跟踪差及带日期资金流；逐项列出缺失数据。",
+      ja: "連動指数または算出方法、保有銘柄・構成銘柄の基準日とウェイト、上位10銘柄・業種集中度、経費率または指数ルール、該当する純資産、流動性・スプレッド、乖離・トラッキング差、日付付き資金フローを確認し、欠落項目を分けて示す。",
+      ko: "추종 지수 또는 산출 방법, 보유·구성 종목 기준일과 비중, 상위 10개·섹터 집중도, 보수 또는 지수 규칙, 해당 시 AUM, 유동성·스프레드, 괴리율·추적 차이, 날짜가 있는 자금 흐름을 확인하고 누락 항목을 분리해 기록한다.",
+    },
+    earnings_deep_dive: {
+      en: "Perform holdings-level earnings look-through. State the covered portfolio weight and one-date aggregation method; keep issuer results separate. Never report fund/index revenue, EPS, cash flow, or an earnings call as though the instrument were an operating company.",
+      zh: "做持仓层盈利穿透，披露覆盖的组合权重与同日聚合方法，并分开记录各发行人结果。不得编造基金/指数自身营收、EPS、现金流或把成分公司电话会写成基金电话会。",
+      ja: "保有銘柄レベルの利益ルックスルーを行い、カバーしたポートフォリオウェイトと同一基準日の集計方法を示し、発行体ごとの結果を分離する。ファンド・指数固有の売上高、EPS、CF、決算説明会を作らない。",
+      ko: "보유 종목 수준 이익 룩스루를 수행하고 커버한 포트폴리오 비중과 동일 기준일 집계 방법을 밝히며 발행사 결과를 분리한다. 펀드·지수 자체 매출, EPS, 현금흐름 또는 실적 발표 콜을 만들지 않는다.",
+    },
+    forward_expectations: {
+      en: "Use weighted constituent or provider-published aggregate expectations with one date and a coverage percentage. Analyse top-constituent, sector, factor and macro expectation changes; never label a few issuer estimates as the fund's own guidance.",
+      zh: "只使用同一时点、披露覆盖权重的加权成分预期或指数提供方聚合预期；分析头部成分、行业、因子与宏观预期变化，不得把少数公司预测称为基金自身指引。",
+      ja: "同一基準日とカバーウェイトを示す加重構成銘柄予想または提供者公表の集計予想を使い、上位銘柄・業種・ファクター・マクロ予想の変化を分析する。一部発行体予想をファンド固有ガイダンスと呼ばない。",
+      ko: "동일 기준일과 커버 비중을 밝힌 가중 구성 종목 전망 또는 제공자 공개 집계 전망을 사용하고 상위 종목·섹터·팩터·거시 전망 변화를 분석한다. 일부 발행사 전망을 펀드 자체 가이던스로 부르지 않는다.",
+    },
+    quant_factor: {
+      en: "Measure total and relative return, breadth, factor/sector exposure, volatility, correlation, drawdown, tracking behaviour, liquidity and flows where available. Distinguish the tradable fund from the cash index and from any derivative proxy.",
+      zh: "衡量总收益与相对收益、市场广度、因子/行业暴露、波动、相关性、回撤、跟踪表现、流动性及可得的资金流；分开可交易基金、现金指数与衍生品代理。",
+      ja: "トータル・相対リターン、ブレッドス、ファクター・業種エクスポージャー、ボラティリティ、相関、ドローダウン、トラッキング、流動性、利用可能な資金フローを測り、上場ファンド、現物指数、デリバティブ代理を分ける。",
+      ko: "총수익·상대수익, 시장 폭, 팩터·섹터 노출, 변동성, 상관, 낙폭, 추적 성과, 유동성 및 가능한 자금 흐름을 측정하고 거래 펀드, 현물 지수, 파생상품 대용물을 구분한다.",
+    },
+    valuation_long_short: {
+      en: "Use same-date aggregate P/E, P/B, cash-flow yield or other portfolio metrics only with the provider/methodology and covered weight. Compare concentration and factor exposures. Never add a handful of constituent financial statements into portfolio financials.",
+      zh: "聚合 P/E、P/B、现金流收益率等组合指标必须同日、说明数据提供方/方法及覆盖权重，并比较集中度与因子暴露；不得把少数成分财报相加成组合财报。",
+      ja: "集計P/E、P/B、CF利回り等は同一基準日、提供者・方法、カバーウェイトを示し、集中度とファクターを比較する。一部構成銘柄の財務諸表を足してポートフォリオ財務にしない。",
+      ko: "집계 P/E, P/B, 현금흐름 수익률 등은 동일 기준일, 제공자·방법, 커버 비중을 밝히고 집중도와 팩터 노출을 비교한다. 일부 구성 종목 재무제표를 더해 포트폴리오 재무로 만들지 않는다.",
+    },
+    news_industry_management: {
+      en: "Cover sponsor and index-provider changes, methodology/rebalance notices, regulation and market-structure news, plus material dated news from top holdings and dominant sectors. Do not invent fund management guidance.",
+      zh: "覆盖基金管理人/指数提供方变化、方法与再平衡公告、监管和市场结构新闻，以及头部持仓和主导行业的重大带日期新闻；不得编造基金经营层指引。",
+      ja: "運用会社・指数提供者の変更、方法・リバランス通知、規制・市場構造ニュース、上位保有銘柄と主要業種の重要な日付付きニュースを扱い、ファンド経営ガイダンスを作らない。",
+      ko: "운용사·지수 제공자 변경, 방법론·리밸런싱 공지, 규제·시장 구조 뉴스와 상위 보유 종목·주요 섹터의 중요한 날짜가 있는 뉴스를 다루며 펀드 경영진 가이던스를 만들지 않는다.",
+    },
+    insider_sec: {
+      en: "Review applicable fund/index filings, prospectus and methodology changes, holdings reports, lending/derivative disclosures and sponsor conflicts. Constituent Form 4 filings are issuer activity, not fund insider trading.",
+      zh: "检查适用的基金/指数申报、招募说明书和方法变更、持仓报告、证券出借/衍生品披露及管理人冲突；成分股 Form 4 属于发行人活动，不是基金内部人交易。",
+      ja: "適用するファンド・指数届出、目論見書・方法変更、保有報告、貸株・デリバティブ開示、運用会社の利益相反を確認する。構成銘柄のForm 4は発行体の活動であり、ファンドの内部者取引ではない。",
+      ko: "적용 가능한 펀드·지수 신고, 투자설명서·방법론 변경, 보유 보고, 대차·파생상품 공시, 운용사 이해상충을 검토한다. 구성 종목 Form 4는 발행사 활동이지 펀드 내부자 거래가 아니다.",
+    },
+    ib_event_analysis: {
+      en: "Treat reconstitution, rebalances, methodology/provider changes, fee or sponsor changes, closures/mergers/splits and capital-market plumbing as instrument events. Constituent M&A matters only through explicit weight, replacement and flow effects.",
+      zh: "把指数重构/再平衡、方法或提供方变化、费率或管理人变化、清盘/合并/拆分及资本市场机制视为资产事件；成分股并购只通过明确的权重、替换与资金流影响纳入。",
+      ja: "入替・リバランス、方法・提供者変更、経費率・運用会社変更、償還・合併・分割、資本市場の仕組みを銘柄イベントとして扱う。構成銘柄M&Aは明示したウェイト、置換、フロー効果だけで反映する。",
+      ko: "지수 재구성·리밸런싱, 방법론·제공자 변경, 보수·운용사 변경, 청산·합병·분할 및 자본시장 구조를 종목 이벤트로 다룬다. 구성 종목 M&A는 명시한 비중·교체·자금 흐름 효과로만 반영한다.",
+    },
+  }[task];
+  const generic = {
+    en: "Use the fund/index research contract and record unavailable fields explicitly.",
+    zh: "使用基金/指数研究合同，并逐项记录不可得数据。",
+    ja: "ファンド・指数調査契約を使い、取得できない項目を明記する。",
+    ko: "펀드·지수 조사 계약을 사용하고 확보하지 못한 항목을 명시한다.",
+  };
+  return localized(language, {
+    en: `## ${type} task override\n${(details || generic).en}`,
+    zh: `## ${type} 专用任务改写\n${(details || generic).zh}`,
+    ja: `## ${type} 専用タスク\n${(details || generic).ja}`,
+    ko: `## ${type} 전용 작업\n${(details || generic).ko}`,
+  });
+}
+
 export function taskPrompt(task, symbol, asOfDate, userPrompt = "", language = "auto", grounding = null) {
   const resolvedLanguage = resolveLanguage({ language, prompt: userPrompt });
   const chinese = isChineseLanguage(resolvedLanguage);
@@ -41,8 +110,9 @@ export function taskPrompt(task, symbol, asOfDate, userPrompt = "", language = "
 
   // Grounding goes AFTER the role brief: the analyst must know its job before it is told
   // 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}`, grounded].filter(Boolean).join("\n\n");
+  return [`${base}\n\n${chinese ? "任务：" : "Task: "}${task}\n${body}`, instrumentOverride, grounded].filter(Boolean).join("\n\n");
 }
 
 export function debatePrompt(role, run, context = {}) {
@@ -83,6 +153,11 @@ export function debatePrompt(role, run, context = {}) {
           ? "这是快速委员会的唯一多空陈述轮。只给最有信息量的 4–6 条论点，使用已提供来源 ID，明确回应方法席分歧；不要生成第二/第三轮问题，也不要写长报告。"
           : "This is the quick council's only bull/bear statement round. Give only the 4-6 highest-information arguments, use supplied source IDs, and engage with method-seat disagreements. Do not create round-2/3 questions or a long report.")
     : "";
+  const instrumentReportInstruction = role === "portfolio_manager" && isFundOrIndex(run?.grounding?.instrument)
+    ? (chinese
+        ? "这是ETF、基金或大盘指数研究。报告必须新增真实 Markdown 标题 `## 基金与指数结构`，明确资产类型、跟踪方法、持仓/成分权重时点、集中度、费用或指数规则、流动性/溢折价/跟踪差/资金流（适用时）、聚合盈利与估值口径，以及每项未取得的数据。不得写基金或指数自身营收/EPS，也不得把少数成分股相加成组合财报。"
+        : "This is ETF, fund or broad-index research. Add a real Markdown heading `## Fund and Index Structure` covering asset type, tracking methodology, dated holdings/constituent weights, concentration, fee or index rules, liquidity/premium-discount/tracking difference/flows when applicable, aggregate earnings and valuation methodology, and every unavailable item. Do not invent fund/index revenue or EPS and never add a few constituents into portfolio financials.")
+    : "";
 
   return [
     // The original spread the preamble's lines as separate array elements, so they are
@@ -90,6 +165,7 @@ export function debatePrompt(role, run, context = {}) {
     ...base.split("\n"),
     roleText,
     quickInstruction,
+    instrumentReportInstruction,
     roundTwoInstruction,
     roundThreeInstruction,
     context.round ? `Debate round: ${context.round}` : "",
@@ -156,6 +232,47 @@ export function masterPrompt(masterId, run) {
   ].filter(Boolean).join("\n\n");
 }
 
+/**
+ * One isolated worker per selected physical v3 method, after its structured decision is
+ * frozen. The worker may explain and challenge the evidence, but it cannot vote again.
+ */
+export function masterVoicePrompt(masterId, run, frozenOpinion) {
+  const reg = registry();
+  const persona = reg.get(masterId);
+  if (!persona || persona.kind !== "master") throw new Error(`unknown master persona: ${masterId}`);
+  const language = run.language || "English";
+  const values = { symbol: run.symbol, as_of: run.as_of, language };
+  const evidence = JSON.stringify(run.council_mode === "quick" ? compactQuickEvidence(run) : compactEvidence(run));
+  return [
+    `You are the dedicated, isolated method-seat explanation worker for ${personaTitle(persona, language)} (${masterId}) in the ${run.symbol} council.`,
+    `Write every reader-facing field in ${language}. Keep stable IDs, tickers and source IDs unchanged.`,
+    "This is a project-derived provisional method lens, not the named person's current statement, endorsement, or quotation.",
+    "The structured method decision below is already frozen. You MUST NOT change, soften, strengthen or reinterpret its stance. Explain why that frozen result follows, identify the highest-information facts or missing facts, state any disagreement with analyst interpretation, and say what evidence would change the method result. Do not browse or add facts.",
+    `Frozen method result JSON: ${JSON.stringify({
+      master: masterId,
+      stance: frozenOpinion?.stance,
+      verdict: frozenOpinion?.verdict,
+      summary: frozenOpinion?.summary,
+      disqualifiers_triggered: frozenOpinion?.disqualifiers_triggered || [],
+      what_would_change_my_mind: frozenOpinion?.what_would_change_my_mind || [],
+      source_ids: frozenOpinion?.source_ids || [],
+      deterministic_core_hash: frozenOpinion?.deterministic_core_hash || null,
+      frozen_decision_hash: frozenOpinion?.frozen_decision_hash || null,
+    })}`,
+    `Method instructions (for explanation only):\n${render(personaPrompt(persona, language), values)}`,
+    [
+      "Write the five `voice` fields in the first person, as the METHOD speaks -- \"I look for X, here the number is Y, so I would Z\".",
+      "First person is the voice of the method, never a claim about what the living person currently thinks: write \"this standard asks for...\", never \"he now believes...\".",
+      "Every figure you cite must already appear in the evidence or the frozen result, with its source ID. Cite the number, not an adjective about the number.",
+      "`what_changes_my_mind` must name a threshold or an observation that would flip the reading, not a wish for more research.",
+      "If the frozen stance is out_of_scope, say plainly and in the method's own voice which input it needs and why its absence is not a bearish view.",
+    ].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\"}.",
+    `Bounded shared evidence JSON: ${evidence}`,
+  ].join("\n\n");
+}
+
 /** The master ids a run has selected, from an explicit list or a roster name. */
 export function selectedMasters(run) {
   const reg = registry();

package/mcp/lib/quotes.mjs

@@ -45,6 +45,10 @@ export function parseYahooChart(json, requested) {
     change_pct: changePct != null ? Number(changePct.toFixed(2)) : null,
     currency: meta.currency || null,
     exchange: meta.exchangeName || null,
+    instrument_type: meta.instrumentType || null,
+    short_name: meta.shortName || null,
+    long_name: meta.longName || null,
+    exchange_timezone: meta.exchangeTimezoneName || null,
     market_state: meta.marketState || null,
     quote_time: meta.regularMarketTime ? new Date(meta.regularMarketTime * 1000).toISOString() : null,
     source: "yahoo",
@@ -62,6 +66,7 @@ export function parseStooqCsv(csv, requested) {
     query: requested, symbol: cols[0] || requested, price: close,
     previous_close: null, change: null, change_pct: null,
     currency: null, exchange: "stooq", market_state: null,
+    instrument_type: null, short_name: null, long_name: null, exchange_timezone: null,
     quote_time: (cols[1] && cols[2]) ? `${cols[1]}T${cols[2]}` : null,
     source: "stooq", note: "delayed / EOD fallback, not real-time",
   };

package/mcp/lib/rpc.mjs

@@ -4,7 +4,7 @@ import readline from "node:readline";
 import { COUNCIL_MODES, LIMITS, MASTER_STANCES, OUTPUT_MODES, QUICK_TASKS, SERVER_NAME, VERSION } from "./constants.mjs";
 import { RpcCode, methodNotFound, invalidParams, toRpcError } from "./errors.mjs";
 import { readJson, readJsonl, writeJson } from "./fsutil.mjs";
-import { resolveLanguage } from "./lang.mjs";
+import { localized, resolveLanguage } from "./lang.mjs";
 import { sweepStaleOutputs } from "./codex.mjs";
 import { completenessStatus, sourceManifest } from "./gates.mjs";
 import { artifactPaths, existingDebate, runId, runPath, safeSymbol, saveRun } from "./run-store.mjs";
@@ -76,7 +76,14 @@ export function recordAck(run, extra = {}) {
   };
 }
 
-function renderSelectionCatalog(data, zh) {
+function renderSelectionCatalog(data) {
+  const copy = (messages) => localized(data.language, messages);
+  const labels = copy({
+    en: { identity: "Identity", method: "Method", bestFor: "Best for", maturity: "Maturity", pack: "Pack format", preselected: "preselected" },
+    zh: { identity: "身份", method: "方法", bestFor: "适合", maturity: "成熟度", pack: "物理格式", preselected: "已预选" },
+    ja: { identity: "人物像", method: "手法", bestFor: "適した対象", maturity: "成熟度", pack: "パック形式", preselected: "事前選択済み" },
+    ko: { identity: "정체성", method: "방법", bestFor: "적합 대상", maturity: "성숙도", pack: "팩 형식", preselected: "사전 선택" },
+  });
   const preselected = new Set(data.preselected_master_ids || []);
   // Some MCP hosts expose only text content even when the server also returns
   // structuredContent. Keep the selection handshake usable on those hosts by
@@ -91,31 +98,45 @@ function renderSelectionCatalog(data, zh) {
     council_mode: data.council_mode,
   })}`;
   const cards = data.masters.map((master) => [
-    `${master.index}. ${master.title} [${master.id}]${preselected.has(master.id) ? (zh ? " [已预选]" : " [preselected]") : ""}`,
-    `${zh ? "身份" : "Identity"}: ${master.identity}`,
-    `${zh ? "方法" : "Method"}: ${master.method}`,
-    `${zh ? "适合" : "Best for"}: ${master.best_for}`,
-    `${zh ? "成熟度" : "Maturity"}: ${master.maturity}`,
-    `${zh ? "物理格式" : "Pack format"}: ${master.pack_format} (${master.admission_level})`,
+    `${master.index}. ${master.title} [${master.id}]${preselected.has(master.id) ? ` [${labels.preselected}]` : ""}`,
+    `${labels.identity}: ${master.identity}`,
+    `${labels.method}: ${master.method}`,
+    `${labels.bestFor}: ${master.best_for}`,
+    `${labels.maturity}: ${master.maturity_label} (${master.maturity})`,
+    `${labels.pack}: ${master.pack_format} (${master.admission_level})`,
   ].join("\n   ")).join("\n\n");
   const quick = data.council_mode === "quick";
-  const instructions = zh
-    ? quick
-      ? `Quick 模式请选择 1 至 ${data.maximum} 位大师。回复编号、范围或稳定 ID，例如：1 / 1,3,8 / 1-4 / master_buffett；不支持 all 全选。`
-      : `请选择 1 至 ${data.maximum} 位大师。回复编号、范围、稳定 ID，或 all 全选，例如：1 / 1,3,8 / 1-5 / master_buffett / all。`
-    : quick
-      ? `Quick mode: choose 1 to ${data.maximum} masters. Submit numbers, ranges, or stable IDs, for example: 1 / 1,3,8 / 1-4 / master_buffett. Selecting all is not supported.`
-      : `Choose 1 to ${data.maximum} masters. Submit numbers, ranges, stable IDs, or all, for example: 1 / 1,3,8 / 1-5 / master_buffett / all.`;
+  const instructions = quick
+    ? copy({
+      en: `Quick mode: choose 1 to ${data.maximum} masters. Submit numbers, ranges, or stable IDs, for example: 1 / 1,3,8 / 1-4 / master_buffett. Selecting all is not supported.`,
+      zh: `Quick 模式请选择 1 至 ${data.maximum} 位大师。回复编号、范围或稳定 ID，例如：1 / 1,3,8 / 1-4 / master_buffett；不支持 all 全选。`,
+      ja: `Quick モードでは1席から${data.maximum}席を選んでください。番号、範囲、stable ID（例：1 / 1,3,8 / 1-4 / master_buffett）を送信してください。all は使用できません。`,
+      ko: `Quick 모드에서는 1개에서 ${data.maximum}개 마스터 좌석을 선택하십시오. 번호, 범위 또는 stable ID(예: 1 / 1,3,8 / 1-4 / master_buffett)를 제출하십시오. all은 지원하지 않습니다.`,
+    })
+    : copy({
+      en: `Choose 1 to ${data.maximum} masters. Submit numbers, ranges, stable IDs, or all, for example: 1 / 1,3,8 / 1-5 / master_buffett / all.`,
+      zh: `请选择 1 至 ${data.maximum} 位大师。回复编号、范围、稳定 ID，或 all 全选，例如：1 / 1,3,8 / 1-5 / master_buffett / all。`,
+      ja: `1席から${data.maximum}席のマスターを選んでください。番号、範囲、stable ID、または all（例：1 / 1,3,8 / 1-5 / master_buffett / all）を送信してください。`,
+      ko: `1개에서 ${data.maximum}개 마스터 좌석을 선택하십시오. 번호, 범위, stable ID 또는 all(예: 1 / 1,3,8 / 1-5 / master_buffett / all)을 제출하십시오.`,
+    });
   return [
-    zh
-      ? `大师选择（目录共 ${data.masters.length} 席；最多选择 ${data.maximum} 席）`
-      : `Master selection (${data.masters.length} in catalog; choose up to ${data.maximum})`,
+    copy({
+      en: `Master selection (${data.masters.length} in catalog; choose up to ${data.maximum})`,
+      zh: `大师选择（目录共 ${data.masters.length} 席；最多选择 ${data.maximum} 席）`,
+      ja: `マスター選択（全${data.masters.length}席、最大${data.maximum}席まで）`,
+      ko: `마스터 선택(전체 ${data.masters.length}개 좌석, 최대 ${data.maximum}개 선택)`,
+    }),
     fallbackContext,
     "",
     cards,
     "",
     instructions,
-    zh ? "提交选择后才会开始研究。" : "Research starts only after this selection is submitted.",
+    copy({
+      en: "Research starts only after this selection is submitted.",
+      zh: "提交选择后才会开始研究。",
+      ja: "選択を送信するまで調査は開始されません。",
+      ko: "선택을 제출하기 전에는 조사를 시작하지 않습니다.",
+    }),
   ].join("\n");
 }
 
@@ -176,6 +197,12 @@ 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 (mode === "quick" && args.synthesis === false) {
     throw invalidParams("Quick council requires its one-round bull/bear and portfolio-manager synthesis.", {
       reason: "QUICK_SYNTHESIS_REQUIRED",
@@ -230,7 +257,9 @@ function selectedRunArgs(args = {}, entryTool) {
       selection_receipt: args.selection_receipt,
       symbol,
       run_id: id,
-      language: args.language || "English",
+      // Preserve omission so consumeCouncilSelection can infer the same locale
+      // from the prompt that begin_council_selection bound into the receipt.
+      language: args.language,
       prompt: typeof args.prompt === "string" ? args.prompt : "",
       council_mode: args.council_mode || "full",
     });
@@ -373,9 +402,8 @@ export function tools() {
     synthesis_timeout_ms: { type: "number", default: LIMITS.CODEX_TIMEOUT_MS },
     total_timeout_ms: {
       type: "number",
-      default: LIMITS.QUICK_TOTAL_MS,
-      maximum: LIMITS.QUICK_HARD_MAX_MS,
-      description: "Hard end-to-end wall-clock budget for council_mode=quick, including grounding wait, retries and synthesis. It may be lowered but never raised above ten minutes. Full mode has no implicit global deadline.",
+      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.",
     },
     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." },
@@ -418,7 +446,7 @@ export function tools() {
         { required: ["selection"], not: { anyOf: [{ required: ["selected_master_ids"] }, { required: ["select_all"] }] } },
       ],
     }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }),
-    tool("plan_visible_run", "Create the visible-host-thread AlphaCouncil run after a confirmed master selection. Requires a one-time selection_receipt. Does NOT execute. You MUST then run every planned evidence agent and every selected master, record bull_researcher and bear_researcher, and only then record the portfolio_manager decision.", {
+    tool("plan_visible_run", "Create the visible-host-thread AlphaCouncil run after a confirmed master selection. Requires a one-time selection_receipt. Does NOT execute. Run every returned evidence_agent, then every returned master_agent. Physical v3 master agents explain a frozen deterministic stance and may not change it. Record all required bull/bear rounds before the portfolio_manager decision; PM rejects any returned master_agent that was not recorded.", {
       type: "object",
       properties: {
         symbol: common.symbol,
@@ -435,7 +463,7 @@ export function tools() {
       },
       required: ["symbol", "selection_receipt"],
     }),
-    tool("record_visible_packet", "MANDATORY sequential step (not optional): record one completed visible evidence agent packet into a planned visible run. Every planned evidence task MUST be recorded before the portfolio_manager decision; a run missing any planned packet will be marked incomplete.", {
+    tool("record_visible_packet", "MANDATORY sequential step (not optional): record one completed visible evidence agent packet into a planned visible run. Every reader-facing field must use the run language or the packet is rejected without changing run state. Every planned evidence task MUST be recorded before debate completion and portfolio_manager.", {
       type: "object",
       properties: {
         run_id: { type: "string" },
@@ -446,23 +474,34 @@ export function tools() {
       },
       required: ["run_id", "task", "packet"],
     }),
-    tool("record_visible_decision", "Record one completed visible bull_researcher / bear_researcher / portfolio_manager packet. Record bull_researcher and bear_researcher before portfolio_manager. For role=portfolio_manager, ALL planned evidence packets AND both debate researchers (bull_researcher and bear_researcher) MUST already be recorded; otherwise the run is marked status=incomplete (NOT complete) and final_report.md gets a visible INCOMPLETE banner. This is the LAST step.", {
+    tool("record_visible_decision", "Record exactly one visible decision step. Full visible bull_researcher and bear_researcher calls MUST supply round=1, then round=2, then round=3; both sides of the prior round are required before advancing. Round 2 asks exactly three questions; Round 3 preserves its own questions and answers the opponent's questions with exact bindings. Packets are persisted by role+round: an identical replay is idempotent and conflicting content is rejected. portfolio_manager accepts no round and is rejected until all evidence, selected masters, both three-round sides, and the exact Q&A gate are complete. Every reader-facing field must use the run language.", {
       type: "object",
       properties: {
         run_id: { type: "string" },
         role: { type: "string", enum: debateIds },
+        round: { type: "integer", minimum: 1, maximum: 3, description: "Required for bull_researcher and bear_researcher. Full visible runs require 1, 2, and 3 in order. Omit for portfolio_manager." },
         packet: { type: "object" },
         thread_id: { type: "string" },
         thread_title: { type: "string" },
       },
       required: ["run_id", "role", "packet"],
+      allOf: [
+        {
+          if: { properties: { role: { enum: ["bull_researcher", "bear_researcher"] } }, required: ["role"] },
+          then: { required: ["round"] },
+        },
+        {
+          if: { properties: { role: { const: "portfolio_manager" } }, required: ["role"] },
+          then: { not: { required: ["round"] } },
+        },
+      ],
     }),
     tool("collect_evidence", "Launch Codex subagents and save shared JSON evidence packets. Use dry_run=true only for planning/self-tests.", {
       type: "object",
       properties: common,
       required: ["symbol", "selection_receipt"],
     }),
-    tool("analyze_symbol", "Collect evidence and write a manager-style decision summary. Set council_mode=quick for the bounded news-inclusive quick_v1 path; the default remains the full council.", {
+    tool("analyze_symbol", "Research an operating company, ETF, mutual fund or market index and write a manager-style decision summary. The instrument is classified before evidence routing: funds use holdings look-through, indices use aggregate methodology, and Company Facts screens apply only to operating companies. Set council_mode=quick for the bounded news-inclusive quick_v1 path; the default remains the full council.", {
       type: "object",
       properties: {
         ...common,
@@ -504,15 +543,27 @@ export function tools() {
       type: "object",
       properties: { language: common.language },
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }),
-    tool("record_master_opinion", "Record one completed selected master-seat opinion into a planned visible run. Masters run AFTER every evidence packet is recorded and BEFORE the bull/bear debate, so the debate has their disagreements to argue with. A master may return stance=out_of_scope, which is a recorded conclusion rather than an abstention. Every selected seat must either report or be settled deterministically before the run can be complete.", {
+    tool("record_master_opinion", "Record one returned visible method-seat worker after evidence and before debate. For physical v3 seats, submit the method-voice schema from plan_visible_run: master, acknowledged_stance, statement, key_findings, disagreements, what_would_change_my_mind, source_ids and confidence. acknowledged_stance must equal the frozen stance; the worker cannot vote again. Legacy packets may use stance/verdict/summary. Reader-facing fields in the wrong run language are rejected without changing state. Every returned selected seat must be recorded before PM.", {
       type: "object",
       properties: {
         run_id: { type: "string" },
         master: { type: "string", enum: masterIds },
         packet: {
           type: "object",
-          description: `The master_opinion packet. stance MUST be one of ${MASTER_STANCES.join(" | ")} -- anything else is recorded as out_of_scope and carries zero weight, so a seat whose stance does not survive normalization silently stops voting. Common synonyms (long/bullish, neutral/hold, short/bearish/avoid, n/a/abstain) are mapped for you.`,
-          properties: { stance: { type: "string", enum: MASTER_STANCES } },
+          description: `Current physical v3 seats use acknowledged_stance + statement; acknowledged_stance MUST be one of ${MASTER_STANCES.join(" | ")} and match the frozen stance returned by plan_visible_run. The legacy stance/verdict/summary shape remains accepted only for a legacy seat.`,
+          properties: {
+            master: { type: "string", enum: masterIds },
+            acknowledged_stance: { type: "string", enum: MASTER_STANCES },
+            statement: { type: "string", minLength: 1 },
+            key_findings: { type: "array", items: { type: "string" } },
+            disagreements: { type: "array", items: { type: "string" } },
+            what_would_change_my_mind: { type: "array", items: { type: "string" } },
+            source_ids: { type: "array", items: { type: "string" } },
+            confidence: { type: "string", enum: ["high", "medium", "low"] },
+            stance: { type: "string", enum: MASTER_STANCES },
+            verdict: { type: "string" },
+            summary: { type: "string" },
+          },
         },
         thread_id: { type: "string" },
       },
@@ -612,7 +663,7 @@ export function tools() {
       properties: { symbols: { type: "array", items: { type: "string" } } },
       required: ["symbols"],
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }),
-    tool("compose_research_brief", "Assemble the hard facts BEFORE the analysts search: quote, SEC filer profile, the mechanical screen with every computed metric, macro readings, and the industry chain map. Returns both the structured data and a prompt block that tells an analyst these numbers are already established and that its search exists to explain, extend and challenge them -- with the rule that a searched number never silently overwrites a filed one. Pass the returned `grounding` object to plan_visible_run so every analyst prompt carries it.", {
+    tool("compose_research_brief", "Classify the instrument and assemble hard facts BEFORE analysts search. Operating companies may receive SEC Company Facts or local-market financials; ETFs and funds receive a holdings look-through contract; indices receive an aggregate-index contract. The result also carries quote, applicable filer profile, options/macro/industry context, explicit not-applicable routes, typed facts, and a prompt block. A searched number never silently overwrites a filed one. Pass the returned `grounding` object to plan_visible_run so every analyst prompt carries it.", {
       type: "object",
       properties: {
         symbol: common.symbol,
@@ -640,7 +691,7 @@ export function tools() {
       type: "object",
       properties: {},
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }),
-    tool("screen_ticker", "Run the mechanical elimination screen against a company's own SEC filings. No language model is involved: seven hard rules (10y ROE, 5y cumulative FCF, interest cover, gross margin, OCF/NI, net margin, dilution) with three exemptions, and every rejection names the metric, the measured value and the threshold. Rules whose inputs are missing from the filings are reported as skipped, never as passes. Surviving is not a recommendation -- it means the name is worth research time. US filers only; other markets need their own regulator feed.", {
+    tool("screen_ticker", "Run the mechanical elimination screen against an operating company's own SEC filings. It is not applicable to ETFs, funds or indices; use compose_research_brief so those instruments are classified and routed correctly. No language model is involved: seven hard rules (10y ROE, 5y cumulative FCF, interest cover, gross margin, OCF/NI, net margin, dilution) with three exemptions, and every rejection names the metric, value and threshold. Missing rules are skipped, never passes. Surviving is not a recommendation. US operating-company filers only.", {
       type: "object",
       properties: {
         cik: { type: "string", description: "SEC CIK. Use list_us_universe to resolve a ticker." },
@@ -692,8 +743,7 @@ export async function handleToolCall(id, params) {
   const args = params?.arguments || {};
   if (name === "begin_council_selection") {
     const data = beginCouncilSelection(args);
-    const zh = /中文|chinese|zh/i.test(String(data.language || ""));
-    sendResult(id, jsonContent(renderSelectionCatalog(data, zh), data));
+    sendResult(id, jsonContent(renderSelectionCatalog(data), data));
     return;
   }
   if (name === "confirm_master_selection") {
@@ -705,10 +755,13 @@ export async function handleToolCall(id, params) {
       intent_hash: data.intent_hash,
       council_mode: data.council_mode,
     })}`;
-    sendResult(id, jsonContent(
-      `${fallbackContext}\nConfirmed ${data.selected_count} master seat(s) for ${data.symbol}. Use the one-time selection_receipt to start this run.`,
-      data,
-    ));
+    const confirmation = localized(data.language, {
+      en: `Confirmed ${data.selected_count} master seat(s) for ${data.symbol}. Use the one-time selection_receipt to start this run.`,
+      zh: `已为 ${data.symbol} 确认 ${data.selected_count} 个大师席位。请使用一次性 selection_receipt 启动本轮运行。`,
+      ja: `${data.symbol} について ${data.selected_count} 席のマスターを確定しました。今回の実行を開始するには1回限りの selection_receipt を使用してください。`,
+      ko: `${data.symbol}에 대해 마스터 ${data.selected_count}개 좌석을 확정했습니다. 이번 실행을 시작하려면 일회용 selection_receipt를 사용하십시오.`,
+    });
+    sendResult(id, jsonContent(`${fallbackContext}\n${confirmation}`, data));
     return;
   }
   if (name === "plan_visible_run") {
@@ -720,7 +773,7 @@ export async function handleToolCall(id, params) {
       // no macro, and nothing in the output says so. Same reasoning as the preflight below:
       // the host that skips the optional step is exactly the host whose seats fail quietly.
       if (!run.grounding) {
-        run.grounding = await gatherGrounding({ symbol: run.symbol, asOf: run.as_of })
+        run.grounding = await gatherGrounding({ symbol: run.symbol, asOf: run.as_of, language: run.language })
           .catch((error) => ({ error: String(error?.message || error), facts_unavailable: true }));
         saveRun(run);
       }
@@ -766,13 +819,18 @@ export async function handleToolCall(id, params) {
   if (name === "record_visible_decision") {
     const result = recordVisibleDecision(args);
     sendResult(id, jsonContent(
-      `Recorded visible decision ${args.role} for ${result.run.symbol}: ${result.run.run_id}`,
+      `Recorded visible decision ${args.role}${args.round ? ` round ${args.round}` : ""} for ${result.run.symbol}: ${result.run.run_id}`,
       // decision and opinion are small and are what a caller reads back; only the full
       // run object is dropped.
       recordAck(result.run, {
         decision: result.decision,
+        idempotent_replay: result.idempotent_replay === true,
         report_quality: result.report_quality?.status,
         missing_report_items: result.report_quality?.missing || [],
+        ...(args.role === "portfolio_manager" ? {
+          handoff_contract: "inline_user_response_v1",
+          user_response_markdown: result.user_response_markdown || "",
+        } : {}),
       }),
     ));
     return;
@@ -844,10 +902,11 @@ export async function handleToolCall(id, params) {
   if (name === "compose_research_brief") {
     const grounding = await gatherGrounding({
       symbol: args.symbol, cik: args.cik, industry: args.industry,
-      macro: args.macro !== false, asOf: args.as_of,
+      macro: args.macro !== false, asOf: args.as_of, language: resolveLanguage(args),
     });
     const block = groundingBlock(grounding, resolveLanguage(args));
     const facts = [
+      grounding.instrument ? `instrument (${grounding.instrument.asset_type}/${grounding.instrument.research_model})` : null,
       grounding.quote ? "quote" : null,
       grounding.filer ? "filer profile" : null,
       grounding.screen ? `screen (${grounding.screen.rules_computed}/${grounding.screen.rules_total} rules)` : null,
@@ -856,7 +915,7 @@ export async function handleToolCall(id, params) {
     ].filter(Boolean);
     sendResult(id, jsonContent(
       groundingDashboard(grounding, resolveLanguage(args)),
-      { grounding, prompt_block: block, dashboard: groundingDashboard(grounding, resolveLanguage(args)) },
+      { grounding, prompt_block: block, facts_available: facts, dashboard: groundingDashboard(grounding, resolveLanguage(args)) },
     ));
     return;
   }