Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
72.0 KB
Raw Blame
/**
 * v0.28: `gbrain think` — INTENT → GATHER → SYNTHESIZE → (optional) COMMIT.
 *
 * v0.28.0 ships the full pipeline. The Anthropic call is dependency-injected
 * (MessagesClient interface) so tests can stub it without an API key. Live
 * runs require ANTHROPIC_API_KEY in the environment.
 *
 * --rounds scaffolding: round 1 is the only round actually exercised in
 * v0.28. Round N+1 fed by gaps from round N is the v0.29 follow-up; the
 * loop structure is in place so rounds > 1 don't fail — they just re-run
 * gather + synthesize without specialized gap-filling logic. Use rounds=1
 * (the default) for production until the gap-fill heuristic ships.
 *
 * --save persists a synthesis page + synthesis_evidence rows. --take
 * appends a take row to the anchor page (requires --anchor). Both are
 * local-CLI-only; remote (MCP) callers get a `not_implemented` envelope
 * for those flags per Codex P1 #7.
 */

import type Anthropic from '@anthropic-ai/sdk';
import { OperationTimeoutError, withTimeout } from '../timeout.ts';
import type { BrainEngine, SynthesisEvidenceInput } from '../engine.ts';
import type { SearchResult } from '../types.ts';
import { runGather, renderPagesBlockDetailed, pagesBlockExcerptLen, takesHitToTakeForPrompt, selectRelevantExcerpt } from './gather.ts';
import { readThinkPagesBudget } from './pages-budget.ts';
import { dropHeldFenceRows, stampPageTrust, stampRowTrust } from '../eligibility/stamp.ts';
import { fenceTranscriptText, neutralizeToolCalls, quoteLabel } from '../search/transcript-quote.ts';
import { renderTakesBlock } from './sanitize.ts';
import { buildThinkSystemPrompt, buildThinkUserMessage } from './prompt.ts';
import { resolveCitations, type ParsedCitation } from './cite-render.ts';
import { resolveOwnerHolder } from '../owner-holder.ts';
import { resolveModel } from '../model-config.ts';
import { chat as gatewayChat, probeChatModel, isThinkingModel, type ChatResult } from '../ai/gateway.ts';
import { withDefaultChatPhase } from '../ai/chat-usage.ts';
import { AIConfigError } from '../ai/errors.ts';
import { normalizeModelId } from '../model-id.ts';
import { hasAnthropicKey } from '../ai/anthropic-key.ts';
import { resolveThinkWindow, trajectoryPointsInWindow } from './temporal-window.ts';
import { resolveThinkTemporalContext } from './temporal-context.ts';
import { resolveExcludePrivatePages, worldOnlyFacts } from '../search/private-visibility.ts';
import { deliverEvidence, effectivePlan, resolveEvidencePlan, EVIDENCE_BLOCK_CHAR_CAP, THINK_RETURN_UNIT_CONFIG_KEY, type DeliveryMeta } from '../search/evidence-delivery.ts';
import { evidenceTitlesEnabled } from '../search/evidence-date.ts';
import { startThinkDecide, thinkAbstainResult, type ThinkAbstention } from './decide.ts';
import { classifyIntent } from './intent.ts';
import { deriveTrust, type TaintRef } from '../trust/taint.ts';
import { withGuestAnswer, type GuestStamp } from '../guests/marker.ts';
import { publishSinglePage, THINK_SYNTHESIS_KIND } from '../generations/adapters/single-page.ts';

/** Anthropic Messages client interface — same shape used by subagent.ts so test stubs can be shared. */
export interface ThinkLLMClient {
  create(params: Anthropic.MessageCreateParamsNonStreaming, opts?: { signal?: AbortSignal }): Promise<Anthropic.Message>;
}

/** Closed set of LLM-call failure classes carried on the wire (D6 discipline). */
export type LlmCallFailureClass = 'timeout' | 'rate_limited' | 'network' | 'provider_error';

/**
 * Coarse, closed-vocabulary failure class for a thrown LLM call. The wire
 * (verb `warnings`) carries ONLY this class — raw provider/transport messages
 * (which can name hosts, keys, request ids) stay off remote responses and go
 * to stderr instead. Exported so tests pin the vocabulary.
 */
export function classifyLlmCallFailure(e: unknown): LlmCallFailureClass {
  const msg = (e instanceof Error ? e.message : String(e)).toLowerCase();
  if (/\b429\b|rate.?limit|overloaded/.test(msg)) return 'rate_limited';
  if (/timeout|timed.?out|etimedout/.test(msg)) return 'timeout';
  if (/econnrefused|econnreset|enotfound|eai_again|network|socket|fetch failed|dns/.test(msg)) return 'network';
  return 'provider_error';
}

export interface RunThinkOpts {
  question: string;
  /** Anchor entity slug. Activates the graph stream + entity-focused prompt. */
  anchor?: string;
  /** v0.28: rounds=1 is the only path exercised. Round-loop scaffolding is in place. */
  rounds?: number;
  /** When true, persist a synthesis page (caller resolves brainDir externally if writing to disk). */
  save?: boolean;
  /** When true, append a take row to the anchor page (requires anchor). */
  take?: boolean;
  /** Model override (CLI flag). Falls through resolveModel's 6-tier chain. */
  model?: string;
  /**
   * v0.41.x (#1698) — true when the CALLER explicitly supplied a model
   * (CLI `--model`, or the MCP `think` op's `model` param). When true, an
   * unresolvable model is a HARD ERROR (throws before gather) instead of
   * silently degrading to the no-LLM stub. Default false: the configured /
   * default model path keeps its graceful-degrade behavior.
   */
  modelExplicit?: boolean;
  /** `false` keeps the gateway client on `model` (no `chat_fallback_chain` hop); an explicit model always does. */
  allowFallback?: boolean;
  /** Optional time window for temporal questions. */
  since?: string;
  until?: string;
  /** When set, MCP-bound calls forward this to the gather phase (server-side filter). */
  takesHoldersAllowList?: string[];
  /** Resolved operation-layer page visibility policy. */
  excludePrivate?: boolean;
  /** Inject an LLM client (for tests). Defaults to a fresh Anthropic SDK client. */
  client?: ThinkLLMClient;
  /** Inject a question-embedding function. When omitted, vector takes search is skipped. */
  embedQuestion?: (q: string) => Promise<Float32Array | null>;
  /** Pure-test escape: return synthesized payload without calling any LLM. */
  stubResponse?: ThinkResponse;
  /**
   * v0.36.1.0 (E1, D22) — when true, retrieve the active calibration profile
   * for the configured holder and inject it into the prompt per D22 placement
   * (after retrieval, before question). The system prompt also gains
   * anti-bias rewrite rules.
   *
   * Off by default (regression posture). When on but no profile exists,
   * think falls back to baseline behavior + a NO_CALIBRATION_PROFILE warning.
   */
  withCalibration?: boolean;
  /**
   * Holder to retrieve the calibration profile for. Resolves via resolveOwnerHolder
   * (config emotional_weight.user_holder, else 'self'). Only consulted when withCalibration=true.
   */
  calibrationHolder?: string;
  /**
   * v0.40.2.0 — when true (default), inject a `<trajectory>` block for
   * temporal / knowledge_update intents. Bypass via
   * `think.trajectory_enabled=false` config OR explicit `withTrajectory:false`
   * caller opt. Kill switch for the rare regression. When set, runThink
   * runs `classifyIntent` + `extractCandidateEntities` + per-candidate
   * `findTrajectory` (5s timeout, concurrency cap 3) before prompt assembly.
   * `other` intent short-circuits the path entirely — no per-candidate
   * SQL fires.
   */
  withTrajectory?: boolean;
  /**
   * v0.40.2.0 — scalar projection of `OperationContext.sourceId`. MCP
   * `think` op handler populates this via `sourceScopeOpts(ctx)` so
   * trajectory queries inherit the same source scope as page/take
   * retrieval. CLI callers omit it and get the engine's default source.
   */
  sourceId?: string;
  /**
   * v0.40.2.0 — scalar projection of `OperationContext.auth.allowedSources`.
   * Federated-read OAuth clients scoped to multiple sources see their
   * full federation. Mutually exclusive with `sourceId` (the array wins
   * when both set, per `sourceScopeOpts` contract).
   */
  allowedSources?: string[];
  /**
   * v0.40.2.0 — scalar projection of `OperationContext.remote`. Trajectory
   * queries apply the `visibility='world'` filter unless this is strictly
   * `false` (FAIL-CLOSED). Every trusted caller (CLI, dream cycle) passes
   * `remote: false` explicitly; omitting it degrades trajectory injection
   * to world-only rows.
   */
  remote?: boolean;
  /**
   * Reference date (YYYY-MM-DD) the question's relative time words resolve
   * against; default today in `brain.timezone`. Evals pass the dataset's
   * question date. Invalid or future values throw ReferenceDateError.
   */
  referenceDate?: string;
}


/** Structured response from the LLM (matches the schema declared in prompt.ts). */
export interface ThinkResponse {
  answer: string;
  citations: Array<{ page_slug: string; row_num: number | null; citation_index?: number }>;
  gaps: string[];
}

/**
 * WP2/T5 — how the synthesis step concluded. Additive: the synthesize verb
 * maps this onto the protocol's `synthesis_status` field (stamping
 * `extractive_fallback` at the verb layer when a compose failure met a
 * non-empty gather). `ok` is the only value that marks a real answer.
 */
export type ThinkSynthesisStatus =
  | 'ok'                // parsed JSON with a non-empty answer
  | 'empty_answer'      // parsed JSON, answer empty
  | 'not_json'          // unparseable output: malformed JSON, refusals, the graceful sentinel
  | 'output_truncated'  // unparseable because stop_reason=max_tokens cut the envelope (#4375)
  | 'no_llm'            // no key configured — gather-only stub
  | 'model_unusable'    // configured model failed the probe (unknown provider/model)
  | 'llm_error';        // client.create() threw (429 / timeout / 5xx / network)

export interface ThinkResult {
  question: string;
  answer: string;
  citations: ParsedCitation[];
  gaps: string[];
  pagesGathered: number;
  takesGathered: number;
  graphHits: number;
  modelUsed: string;
  rounds: number;
  warnings: string[];
  /**
   * v0.41.x (#1698) — true only when an actual synthesis produced a NON-EMPTY
   * answer. False for the no-LLM graceful stub, malformed (not-JSON) output, and
   * valid-but-empty JSON (`{"answer":""}`). `persistSynthesis` refuses to write
   * when this is `=== false`, so an empty page can never be saved. Undefined on
   * pre-existing/test `ThinkResult` literals → treated as persistable (back-compat).
   */
  synthesisOk?: boolean;
  /**
   * WP2/T5 — why synthesis produced (or didn't produce) a real answer.
   * Additive-forever; `synthesisOk` remains the persistence gate. The MCP
   * `think` op spreads this through verbatim.
   */
  synthesis_status?: ThinkSynthesisStatus;
  /**
   * WP2/E2 — extractive-fallback material, present ONLY when synthesis failed
   * (`synthesis_status !== 'ok'`) AND gather returned pages. Composed
   * exclusively from gathered pages — an empty gather never yields one
   * (ENG-19: no pages, no answer). `answer`/`citations` are left untouched
   * so existing consumers keep the raw failure shape; callers opt in.
   */
  extractive?: ExtractiveFallback;
  /**
   * MEMORY_VERBS v1 [E2] — gateway token usage for the synthesis call(s),
   * summed across rounds. Best-effort: null when no LLM ran (graceful stub),
   * when a test client returns no usage, or when a provider omits accounting.
   * The synthesize verb maps this to its frozen `cost` block.
   */
  usage?: { input_tokens: number; output_tokens: number } | null;
  /** Evidence delivery meta, present only when think.return_unit is not chunk. */
  evidence_delivery?: import('../search/evidence-delivery.ts').DeliveryMeta;
  /**
   * #5461: true when at least one gathered page reached the model in part (an
   * excerpt cut by the pages budget / excerpt ceiling, or a delivered block
   * over its cap). The budget is configurable (`think.pages_budget_chars`,
   * `think.excerpt_ceiling_chars`) and soft; see think/pages-budget.ts.
   */
  evidence_truncated?: boolean;
  /** GBRA-504: the outside-guest notes that reached the prompt; `answer` then ends with the fixed guest line gbrain appends. */
  guest_evidence?: Array<{ source_id: string; slug: string; guest: GuestStamp }>;
  /** Gathered pages with the revision retrieved, for retrieval-feedback recording; the op layer strips it. */
  feedback_evidence?: Array<{ source_id: string; slug: string; content_hash: string | null }>;
  /** #5575 I2: every page, take and trajectory fact placed in the synthesis prompt; `persistSynthesis` taints from them. The op layer strips it. */
  taint_refs?: TaintRef[];
  /**
   * GBRA-498: what reaches the prompt beyond taint_refs, for room marks only: the anchor and the graph pages the prompt
   * names, and a calibration profile (no page or fact id, so the answer is unknown). Never feeds trust derivation.
   */
  room_extra?: Array<{ table: 'pages'; sourceId: string; slug: string } | { table: 'calibration'; id: number }>;
  /** Only set when --save was true and the caller persisted a synthesis page. */
  savedSlug?: string;
  /**
   * Quote grounding (think.quote_verify, default on): `answer` is the safe
   * version (near-match quotes repaired to the evidence's words, quotes found
   * in no evidence unquoted and marked [unverified]); `answer_raw` is what the
   * model wrote. Present only when the answer contained quotes.
   */
  answer_raw?: string;
  quote_check?: { grounded: number; repaired: number; unverified: number };
  unverified_quotes?: Array<{ text: string; reason: string }>;
  /** What `persistSynthesis` saves: the raw answer with every claim unit carrying an unverified quote removed, and those units. */
  persist?: { answer: string; unverified_claims: Array<{ text: string; reason: string; detail: string }> };
  /** The synthesis page as the run found it before gathering (GBRA-161 PR 5): `persistSynthesis` binds its write to this revision. */
  persist_base?: { sourceId: string; slug: string; revision: string | null };
  /** Diagnostics for `--explain` callers (CLI surface for v0.29). */
  diagnostics: {
    pagesFromHybrid: number;
    takesFromKeyword: number;
    takesFromVector: number;
    graphHits: number;
  };
  /** USD cost computed from `usage` + `canonicalLookup(modelUsed)`, when both are available. */
  cost_usd?: number;
  /** System One S4 (on): the brain holds no evidence; synthesis was skipped (think/decide.ts). */
  abstained?: ThinkAbstention;
  /** The date frame the synthesis read in (reference date + brain timezone). */
  temporal?: { reference_date: string; time_zone: string };
  /** #6997: set only when a `chat_fallback_chain` model answered: the model asked first (`modelUsed` names the one that answered, which is priced and saved). */
  requested_model?: string;
  /** #6997: with `requested_model`, why it did not answer ("failed (...)" / "refused (...)"). Not returned to HTTP MCP callers. */
  fallback_reason?: string;
  /** PR #5086: who bounded the evidence, when a window applied: the caller's `since`/`until`, or the one explicit date the question named (`WINDOW_FROM_QUESTION` warning). */
  window_source?: 'caller' | 'question';
}

const DEFAULT_MAX_OUTPUT_TOKENS = 4000;

// Thinking-by-default Claude 5 models spend a large share of the output budget
// on internal reasoning before emitting any answer, so the 4000 default leaves
// `think` with empty or truncated text. Give those models headroom; providers
// bill actual tokens, not the cap. Everything else keeps 4000. Detection is
// the gateway's `isThinkingModel` (Claude 5 by name behind any provider
// prefix, or a recipe-declared `thinking_by_default` capability — #4172,
// e.g. DeepSeek v4; fail-closed for unknown providers), so `think` and the
// gateway's own output-cap default cannot drift; think keeps its own
// smaller 16000 cap.
const THINKING_DEFAULT_MAX_OUTPUT_TOKENS = 16000;
// OpenAI reasoning models spend output budget on internal reasoning tokens
// the same way — reasoning tokens are billed as output and count against
// `max_tokens` — so they get the same headroom. Deliberately scoped to the
// gpt-5-and-later families and the numbered o-series only; anything else
// (gpt-4o, the non-reasoning `*-chat` snapshots like gpt-5-chat-latest, other
// providers' reasoning models routed through their own recipes) keeps the
// conservative 4000 default. #7421: matched behind any provider-prefix chain
// (`openai:`, `litellm:`, `openrouter:openai/`), like the Claude regexes,
// because the proxy route does not change how the model bills reasoning; an
// opaque proxy alias (`litellm:my-reasoner`) still cannot be recognized.
const OPENAI_REASONING_MODEL_RE = /[:/](?:gpt-[5-9]|o[0-9]+)(?:[.-]|$)/i;
const OPENAI_CHAT_SNAPSHOT_RE = /-chat(?:-|$)/i; // gpt-5-chat-latest, gpt-5.2-chat-latest
// #4375: the default deep tier (anthropic:claude-opus-4-7) routinely needs
// more than 4000 tokens for the synthesis JSON envelope; at 4000 the envelope
// truncates mid-stream. Anthropic-scoped only (same spelling variants as
// THINKING_BY_DEFAULT_MODEL_RE), so provider hard caps (DeepSeek 8192,
// gpt-4o) are unaffected; providers bill actual tokens, not the cap.
const ANTHROPIC_CLAUDE_4X_MODEL_RE = /(?:^|[:/])(?:anthropic[:/])?claude-(?:opus|sonnet|haiku)-4-\d/i;
export function maxOutputTokensFor(modelStr: string): number {
  const openaiReasoning =
    OPENAI_REASONING_MODEL_RE.test(modelStr) && !OPENAI_CHAT_SNAPSHOT_RE.test(modelStr);
  // Shared predicate (#4087 one source of truth in gateway.ts: Claude 5 by
  // name — provider-prefixed or bare, never 3.5-era — OR the recipe-declared
  // thinking_by_default capability, #4172). Reasoning bills as output and
  // counts against max_tokens; without headroom the 4000 cap is spent on
  // reasoning and think returns truncated/empty JSON.
  if (isThinkingModel(modelStr) || openaiReasoning || ANTHROPIC_CLAUDE_4X_MODEL_RE.test(modelStr)) {
    return THINKING_DEFAULT_MAX_OUTPUT_TOKENS;
  }
  return DEFAULT_MAX_OUTPUT_TOKENS;
}

function inferIntent(question: string, anchor?: string): string {
  if (anchor) return 'entity';
  const q = question.toLowerCase();
  if (/\b(when|history|over time|evolved|since|before|after)\b/.test(q)) return 'temporal';
  if (/\b(meeting|event|happened)\b/.test(q)) return 'event';
  return 'general';
}

/** Strip a wrapping code fence, if present (shared by parse + salvage). */
function stripEnvelopeFences(text: string): string {
  return text.trim().replace(/^```(?:json)?\s*\n?/, '').replace(/```\s*$/, '');
}

function tryParseJSON(text: string): unknown {
  // The model may wrap JSON in code fences. Strip if present.
  const stripped = stripEnvelopeFences(text);
  try {
    return JSON.parse(stripped);
  } catch {
    // Fallback: extract the first {...} block. Useful when the model emits prose alongside JSON.
    const m = stripped.match(/\{[\s\S]*\}/);
    if (m) {
      try { return JSON.parse(m[0]); } catch { /* ignore */ }
    }
    return null;
  }
}

/** #4509 — is this model output SHAPED like a JSON envelope (as opposed to
 * refusal prose / the graceful sentinel, whose raw text is meaningful)? */
export function looksLikeJsonEnvelope(text: string): boolean {
  return stripEnvelopeFences(text).startsWith('{');
}

/**
 * #4509 — best-effort field salvage from a MALFORMED ThinkResponse envelope
 * (the common cause is max-token truncation cutting the JSON mid-string).
 * Pre-fix, the raw envelope text shipped as the user-facing `answer` with
 * `citations: []`. Tolerant by construction: the answer string is recovered
 * up to the cut (dangling escapes trimmed), citations/gaps only when their
 * arrays survived whole. Returns null when no non-empty answer is present —
 * the caller then suppresses the raw JSON entirely.
 */
export function salvageThinkEnvelope(
  text: string,
): Pick<ThinkResponse, 'answer' | 'citations' | 'gaps'> | null {
  const stripped = stripEnvelopeFences(text);
  if (!stripped.startsWith('{')) return null;
  const answer = salvageStringField(stripped, 'answer');
  if (answer === null || answer.trim().length === 0) return null;
  const citations = (salvageArrayField(stripped, 'citations') ?? []).filter(
    (c): c is ThinkResponse['citations'][number] =>
      typeof c === 'object' && c !== null && typeof (c as { page_slug?: unknown }).page_slug === 'string',
  );
  const gaps = (salvageArrayField(stripped, 'gaps') ?? []).filter(
    (g): g is string => typeof g === 'string',
  );
  return { answer, citations, gaps };
}

/** Recover `"key": "…"` even when the closing quote never arrives (truncation). */
function salvageStringField(src: string, key: string): string | null {
  const keyIdx = src.indexOf(`"${key}"`);
  if (keyIdx === -1) return null;
  let i = keyIdx + key.length + 2;
  while (i < src.length && /\s/.test(src[i]!)) i++;
  if (src[i] !== ':') return null;
  i++;
  while (i < src.length && /\s/.test(src[i]!)) i++;
  if (src[i] !== '"') return null;
  i++;
  let raw = '';
  for (; i < src.length; i++) {
    const c = src[i]!;
    if (c === '\\') {
      raw += c + (src[i + 1] ?? '');
      i++;
      continue;
    }
    if (c === '"') break; // properly terminated
    raw += c;
  }
  // Truncation can leave a dangling escape — trim a lone trailing backslash
  // and an incomplete \uXXXX so the re-parse below can't fail on them.
  if (/(?:^|[^\\])(?:\\\\)*\\$/.test(raw)) raw = raw.slice(0, -1);
  raw = raw.replace(/\\u[0-9a-fA-F]{0,3}$/, '');
  try {
    return JSON.parse(`"${raw}"`) as string;
  } catch {
    // Last resort: the escaped text beats the whole raw envelope.
    return raw;
  }
}

/** Parse `"key": [...]` when the array survived whole; null when cut mid-array. */
function salvageArrayField(src: string, key: string): unknown[] | null {
  const keyIdx = src.indexOf(`"${key}"`);
  if (keyIdx === -1) return null;
  const open = src.indexOf('[', keyIdx);
  if (open === -1) return null;
  let depth = 0;
  let inStr = false;
  for (let i = open; i < src.length; i++) {
    const c = src[i]!;
    if (inStr) {
      if (c === '\\') { i++; continue; }
      if (c === '"') inStr = false;
      continue;
    }
    if (c === '"') { inStr = true; continue; }
    if (c === '[') depth++;
    else if (c === ']') {
      depth--;
      if (depth === 0) {
        try {
          const v = JSON.parse(src.slice(open, i + 1));
          return Array.isArray(v) ? v : null;
        } catch {
          return null;
        }
      }
    }
  }
  return null; // truncated mid-array
}

// ─── Extractive fallback [WP2/E2] ────────────────────────────────────────────
// When synthesis fails but gather succeeded, a digest of the top gathered
// pages (title + best excerpt, page-level citations) beats an empty failure.

const EXTRACTIVE_TOP_PAGES = 5;
const EXTRACTIVE_EXCERPT_LEN = 400;

export interface ExtractiveFallback {
  answer: string;
  /** Page-level citations (row_num null) for the digested pages, gather order. */
  citations: ParsedCitation[];
}

/**
 * Compose an extractive digest from gathered pages: one line per page,
 * title + the excerpt window with the strongest query-term coverage, cited
 * `[slug]`. NEVER fabricates: every line quotes ONE gathered page and an
 * empty gather returns null (ENG-19 — no pages, no answer, ever).
 * GST-687: with `untrusted` (a remote caller), a chat page's excerpt is chosen with its tool-call blocks summarized, and it
 * and a page below the owner's tier are fenced as quoted source material, as think's prompt does (#8042); local is unchanged.
 */
export function composeExtractiveFallback(
  pages: SearchResult[],
  question: string,
  untrusted = false,
): ExtractiveFallback | null {
  if (pages.length === 0) return null;
  const top = pages.slice(0, EXTRACTIVE_TOP_PAGES);
  const citations: ParsedCitation[] = [];
  const lines = top.map((p, idx) => {
    const page = p as unknown as {
      slug?: string; title?: string; chunk_text?: string; compiled_truth?: string; snippet?: string;
    };
    const slug = String(page.slug ?? '');
    const title = String(page.title ?? '') || slug;
    const slugIdentity = slug.split('/').pop()?.replace(/[-_]/g, ' ') ?? '';
    const raw = String(page.chunk_text ?? page.compiled_truth ?? page.snippet ?? '');
    const quote = untrusted ? quoteLabel({ ...p, chunk_text: raw }, true) : null;
    const content = quote !== null && quoteLabel({ ...p, chunk_text: raw }) !== null ? neutralizeToolCalls(raw) : raw;
    const excerpt = selectRelevantExcerpt(
      content, question, EXTRACTIVE_EXCERPT_LEN, `${title} ${slugIdentity}`,
    ).trim();
    citations.push({ page_slug: slug, row_num: null, citation_index: idx + 1, source_id: p.source_id ?? 'default' });
    if (!excerpt) return `- ${title} [${slug}]`;
    return quote === null ? `- ${title} [${slug}]: ${excerpt}` : `- ${title} [${slug}]:\n${fenceTranscriptText(excerpt, quote)}`;
  });
  return {
    answer:
      `No synthesized answer — extractive excerpts from the ${top.length} most relevant retrieved page(s):\n` +
      lines.join('\n'),
    citations,
  };
}

/**
 * Persist citations into synthesis_evidence. Resolves slugs to page_ids
 * via the engine. Pages that don't exist in the brain are skipped + warn'd.
 * Pages without a row_num are page-level citations and are NOT persisted
 * (synthesis_evidence is a take→synthesis FK; page-level citations live in
 * the answer body's [slug] markers only).
 */
async function persistCitations(
  engine: BrainEngine,
  synthesisPageId: number,
  citations: ParsedCitation[],
  scope: { sourceId?: string; allowedSources?: string[] } = {},
): Promise<{ inserted: number; warnings: string[] }> {
  const warnings: string[] = [];
  // #5426: the same slug can exist in several sources. Bind each citation to
  // a page in the sources the synthesis drew from (preferring its own source),
  // never to a same-slug page elsewhere in the brain. Unscoped only for an
  // unscoped think.
  const sources = scope.allowedSources?.length ? scope.allowedSources : scope.sourceId ? [scope.sourceId] : null;
  // Resolve unique slugs to page_ids
  const slugToPageId = new Map<string, number>();
  for (const c of citations) {
    if (c.row_num === null) continue;  // page-level, skip
    if (slugToPageId.has(c.page_slug)) continue;
    const rows = sources
      ? await engine.executeRaw<{ id: number }>(
        `SELECT id FROM pages WHERE slug = $1 AND source_id = ANY($2::text[]) ORDER BY (source_id = $3) DESC, id LIMIT 1`,
        [c.page_slug, sources, scope.sourceId ?? ''],
      )
      : await engine.executeRaw<{ id: number }>(
        `SELECT id FROM pages WHERE slug = $1 LIMIT 1`,
        [c.page_slug],
      );
    if (rows[0]) slugToPageId.set(c.page_slug, rows[0].id);
  }
  const evidenceInputs: SynthesisEvidenceInput[] = [];
  for (const c of citations) {
    if (c.row_num === null) continue;
    const pageId = slugToPageId.get(c.page_slug);
    if (!pageId) {
      warnings.push(`CITATION_PAGE_NOT_IN_BRAIN: ${c.page_slug}#${c.row_num}`);
      continue;
    }
    evidenceInputs.push({
      synthesis_page_id: synthesisPageId,
      take_page_id: pageId,
      take_row_num: c.row_num,
      citation_index: c.citation_index,
    });
  }
  if (evidenceInputs.length === 0) return { inserted: 0, warnings };
  const inserted = await engine.addSynthesisEvidence(evidenceInputs);
  return { inserted, warnings };
}

/**
 * Render the <pages> block. Evidence delivery (think.return_unit, default
 * auto) replaces the gathered pages with budgeted delivered blocks, which
 * the renderer passes through whole instead of cutting its own excerpts;
 * auto's unchanged chunks keep the usual excerpts.
 */
/** #5461: source-qualify each citation from the gather (the highest-ranked gathered page with that slug; null outside the gather). */
function stampCitationSources(citations: ParsedCitation[], pages: SearchResult[]): void {
  const sourceOfSlug = new Map<string, string>();
  for (const pg of pages) if (!sourceOfSlug.has(pg.slug)) sourceOfSlug.set(pg.slug, pg.source_id ?? 'default');
  for (const c of citations) c.source_id = sourceOfSlug.get(c.page_slug) ?? null;
}

async function renderThinkPages(engine: BrainEngine, opts: RunThinkOpts, pages: SearchResult[], timeZone: string, warnings: string[]): Promise<{ pagesBlock: string; evidenceTruncated: boolean; evidenceDelivery?: DeliveryMeta }> {
  const [plan, budget, titles] = await Promise.all([
    resolveEvidencePlan(engine, {
      remote: opts.remote, returnUnit: undefined, returnWindow: undefined, budget: undefined,
      snippetChars: undefined, snippetCap: 0, configKey: THINK_RETURN_UNIT_CONFIG_KEY, op: 'think',
    }),
    readThinkPagesBudget(engine, warnings), // #5461
    evidenceTitlesEnabled(engine), // GBRA-205
  ]);
  const excerptLen = pagesBlockExcerptLen(pages.length, undefined, budget);
  const applied = effectivePlan(plan, pages);
  if (!applied) {
    const rendered = renderPagesBlockDetailed(pages, excerptLen, opts.question, { timeZone, titles });
    return { pagesBlock: rendered.text, evidenceTruncated: rendered.truncated };
  }
  const delivered = await deliverEvidence(engine, pages, applied, {
    ...(opts.allowedSources !== undefined && opts.allowedSources.length > 0 ? { sourceIds: opts.allowedSources } : opts.sourceId !== undefined ? { sourceId: opts.sourceId } : {}),
    excludePrivate: opts.excludePrivate ?? await resolveExcludePrivatePages(engine, opts.remote),
    requireSafeChunks: opts.remote !== false,
  });
  // GST-2900: delivery re-reads page text from the database, so the held fence rows are dropped again (GST-2891).
  const results = worldOnlyFacts(opts.remote) ? await dropHeldFenceRows(engine, delivered.results) : delivered.results;
  const rendered = applied.unit === 'auto'
    ? renderPagesBlockDetailed(results, excerptLen, opts.question,
      { verbatim: r => r.delivered?.reason !== 'not_conversation' && r.delivered?.reason !== 'conversation_over_budget', verbatimLen: EVIDENCE_BLOCK_CHAR_CAP, timeZone, titles })
    : renderPagesBlockDetailed(results, EVIDENCE_BLOCK_CHAR_CAP, opts.question, { verbatim: true, timeZone, titles });
  return { pagesBlock: rendered.text, evidenceTruncated: rendered.truncated, evidenceDelivery: delivered.delivery };
}

/**
 * The question embedding gather may use, or undefined. A brain that opted out
 * of embedding never sends the question to a provider (warning
 * QUESTION_EMBED_SKIPPED_EMBEDDING_DISABLED); a failing embedder degrades to
 * QUESTION_EMBED_FAILED with the raw error on stderr only (D6).
 */
async function embedThinkQuestion(engine: BrainEngine, opts: RunThinkOpts, warnings: string[]): Promise<Float32Array | undefined> {
  if (!opts.embedQuestion) return undefined;
  const { factEmbeddingDisabled } = await import('../embedding-disabled.ts');
  if (await factEmbeddingDisabled(engine)) {
    warnings.push((await import('../interop-notices.ts')).QUESTION_EMBED_OPTED_OUT);
    return undefined;
  }
  try {
    return (await opts.embedQuestion(opts.question)) ?? undefined;
  } catch (e) {
    warnings.push('QUESTION_EMBED_FAILED');
    process.stderr.write(`[think] question embed failed: ${e instanceof Error ? e.message : String(e)}\n`);
    return undefined;
  }
}
/**
 * Run the think pipeline. Returns a ThinkResult — caller decides whether
 * to print, persist as synthesis page, or surface as MCP response.
 */
export async function runThink(
  engine: BrainEngine,
  opts: RunThinkOpts,
): Promise<ThinkResult> {
  const rounds = Math.max(1, opts.rounds ?? 1);
  const warnings: string[] = [];
  // PR #5086: caller bounds are authoritative; with none, the one explicit date the question names bounds the synthesis.
  const resolvedWindow = resolveThinkWindow(opts.question, opts.since, opts.until);
  const window = resolvedWindow?.window ?? null;
  if (resolvedWindow?.source === 'question') warnings.push('WINDOW_FROM_QUESTION');
  const windowMeta = resolvedWindow ? { window_source: resolvedWindow.source } : {};
  const temporal = await resolveThinkTemporalContext(engine, { referenceDate: opts.referenceDate });

  // Resolve the model through the 6-tier chain.
  const modelUsed = await resolveModel(engine, {
    cliFlag: opts.model,
    configKey: 'models.think',
    tier: 'deep',
    fallback: 'opus',  // think is the high-stakes synthesis op; opus is the right default
  });

  // #1698: fail fast on an unresolvable EXPLICIT model (CLI --model, or the MCP op's
  // model param) BEFORE gather, so we don't waste retrieval per failure (the 200-call
  // batch case). The default/configured-model path is unaffected (modelExplicit false →
  // it keeps the graceful no-LLM-stub degrade). Test/injected client + stub bypass.
  if (opts.modelExplicit && !opts.client && !opts.stubResponse) {
    const probe = probeChatModel(normalizeModelId(modelUsed));
    if (!probe.ok) {
      throw new Error(
        `think: --model "${opts.model}" is not usable (${probe.reason}): ${probe.detail}. ` +
        `Refusing to run synthesis with no model — fix the model id or omit --model.` +
        (probe.fix ? ` Fix: ${probe.fix}` : ''),
      );
    }
  }

  const persistSlug = synthesisSlug(opts.question, new Date().toISOString().slice(0, 10));
  const persistBase = { sourceId: opts.sourceId ?? 'default', slug: persistSlug,
    revision: (await engine.readPageSnapshot(persistSlug, { sourceId: opts.sourceId ?? 'default', includeDeleted: true }))?.revision ?? null };

  // Optional question embedding — caller decides whether to pay the embedder; an opted-out brain never does.
  const questionEmbedding = await embedThinkQuestion(engine, opts, warnings);

  const thinkDecide = await startThinkDecide(engine, opts, classifyIntent(opts.question)).catch(() => undefined); // System One S2/S4; undefined when both are off
  // GATHER
  const gather = await runGather(engine, {
    question: opts.question,
    anchor: opts.anchor,
    questionEmbedding,
    ...(window ? { window } : {}),
    takesHoldersAllowList: opts.remote === false ? opts.takesHoldersAllowList : opts.takesHoldersAllowList ?? ['world'],
    excludePrivate: opts.excludePrivate ?? await resolveExcludePrivatePages(engine, opts.remote),
    remote: opts.remote,
    ...(opts.sourceId !== undefined ? { sourceId: opts.sourceId } : {}),
    ...(opts.allowedSources !== undefined ? { sourceIds: opts.allowedSources } : {}),
    ...(thinkDecide?.searchIntent ? { decideIntent: thinkDecide.searchIntent } : {}),
  });
  // D6: per-stream gather failures surface as typed codes (GATHER_*_FAILED);
  // raw error text stays on stderr. Distinguishes an errored stream from a
  // legitimately-empty one for MCP/remote callers.
  for (const w of gather.warnings) warnings.push(w);
  if (gather.diagnostics.window?.dropped) warnings.push(`WINDOW_EXCLUDED_${gather.diagnostics.window.dropped}_PAGES`);
  // #5575 A6: every page and take reaches the prompt with its trust tier; GST-2900 drops held fence rows for world-only callers.
  gather.pages = await stampPageTrust(engine, gather.pages, undefined, undefined, worldOnlyFacts(opts.remote));
  gather.takes = await stampRowTrust(engine, 'takes', gather.takes, t => ('take_id' in t ? t.take_id : (t as { id: number }).id));

  // Render evidence blocks for the prompt. #4510: the per-page excerpt is
  // budget-aware — 600 chars is the FLOOR (a big gather never collapses each
  // page below it) and a small gather spreads the block budget into much
  // larger, often complete, per-page windows.
  const { pagesBlock, evidenceTruncated, evidenceDelivery } = await renderThinkPages(engine, opts, gather.pages, temporal.timeZone, warnings);
  const takesForPrompt = gather.takes.map(takesHitToTakeForPrompt);
  const { rendered: takesBlock, sanitizedCount } = renderTakesBlock(takesForPrompt);
  if (sanitizedCount > 0) {
    warnings.push(`SANITIZED_${sanitizedCount}_TAKE_CLAIMS`);
  }
  const graphBlock = gather.graphSlugs.length > 0
    ? `<anchor>${opts.anchor}</anchor>\nReachable: ${gather.graphSlugs.slice(0, 30).join(', ')}`
    : undefined;

  // v0.36.1.0 (E1) — optional calibration profile retrieval. When enabled
  // and a profile exists, inject it per D22 (after retrieval, before question).
  // When enabled and no profile, fall back to baseline + warn.
  let calibrationBlockOpts:
    | { holder: string; patternStatements: string[]; activeBiasTags: string[]; brier?: number | null }
    | undefined;
  if (opts.withCalibration) {
    try {
      const { getLatestProfile } = await import('../../commands/calibration.ts');
      const profile = await getLatestProfile(engine, {
        holder: resolveOwnerHolder({
          override: opts.calibrationHolder,
          configValue: await engine.getConfig('emotional_weight.user_holder'),
        }),
      });
      if (profile) {
        calibrationBlockOpts = {
          holder: profile.holder,
          patternStatements: profile.pattern_statements,
          activeBiasTags: profile.active_bias_tags,
          brier: profile.brier,
        };
      } else {
        warnings.push('NO_CALIBRATION_PROFILE');
      }
    } catch (err) {
      // D6: code-only on the wire; raw exception text goes to server logs.
      warnings.push('CALIBRATION_FETCH_FAILED');
      process.stderr.write(`[think] calibration fetch failed: ${err instanceof Error ? err.message : String(err)}\n`);
    }
  }

  // v0.40.2.0 — trajectory injection for temporal / knowledge_update
  // intents. Default ON (Eng D1). `think.trajectory_enabled` config flag
  // is the kill switch. `withTrajectory: false` caller opt also bypasses.
  // `other` intent short-circuits before any SQL fires.
  let trajectoryBlock = '';
  const trajectoryFactIds: number[] = [];
  let trajectoryPointsCount = 0;
  let trajectoryExcludedCount = 0;
  const trajectoryEnabledConfig = await readThinkTrajectoryEnabled(engine);
  if (trajectoryEnabledConfig && opts.withTrajectory !== false) { // opt defaults true
    try {
      const trajIntent = thinkDecide ? await thinkDecide.trajectoryIntent(classifyIntent(opts.question)) : classifyIntent(opts.question);
      if (trajIntent === 'temporal' || trajIntent === 'knowledge_update') {
        const { extractCandidateEntities } = await import('./entity-extract.ts');
        const retrievedSlugs = [...gather.pages.map(p => p.slug), ...gather.outsideWindowSlugs];
        const candidates = extractCandidateEntities(opts.question, retrievedSlugs);
        if (candidates.length > 0) {
          const { resolveEntitySlugWithSource } = await import('../entities/resolve.ts');
          const { formatTrajectoryBlock } = await import('../trajectory-format.ts');
          const sourceIdScalar = opts.sourceId ?? 'default';
          const excludePrivate = opts.excludePrivate ?? await resolveExcludePrivatePages(engine, opts.remote);
          // Per-candidate trajectory fetch. Concurrency cap = 3; each call
          // has its own 5s timeout via Promise.race. allSettled prevents
          // one error from killing the others (Codex Problem 13: timeout
          // bounds latency, not just failure propagation).
          const allBlocks: string[] = [];
          const seenSlugs = new Set<string>();
          let totalPoints = 0;
          const candidateQueue = [...candidates];
          while (candidateQueue.length > 0) {
            const batch = candidateQueue.splice(0, 3);
            const settled = await Promise.allSettled(
              batch.map(async (cand) => {
                const resolved = await resolveEntitySlugWithSource(engine, sourceIdScalar, cand.raw);
                if (!resolved) return null;
                if (resolved.source === 'fallback_slugify') return null;
                if (seenSlugs.has(resolved.slug)) return null;
                seenSlugs.add(resolved.slug);
                // 5s per-candidate timeout (cleared on settle); a timeout
                // is an empty trajectory, any other error rejects as before.
                const points = await withTimeout(
                  engine.findTrajectory({
                    entitySlug: resolved.slug,
                    ...(opts.sourceId !== undefined ? { sourceId: opts.sourceId } : {}),
                    ...(opts.allowedSources !== undefined ? { sourceIds: opts.allowedSources } : {}),
                    ...(opts.remote !== undefined ? { remote: worldOnlyFacts(opts.remote) } : {}),
                    excludePrivate,
                    kind: 'all',
                    limit: 100,
                  }),
                  5000,
                  'findTrajectory',
                ).catch((err: unknown) => {
                  if (err instanceof OperationTimeoutError) return [];
                  throw err;
                });
                const windowed = window ? trajectoryPointsInWindow(points, window) : { kept: points, excluded: 0 };
                trajectoryExcludedCount += windowed.excluded;
                const boundedPoints = windowed.kept;
                if (boundedPoints.length === 0) return null;
                trajectoryFactIds.push(...boundedPoints.map(point => point.fact_id));
                const fmt = formatTrajectoryBlock(boundedPoints, resolved.slug, {
                  intent: trajIntent,
                });
                if (fmt.rendered.length === 0) return null;
                return { rendered: fmt.rendered, points: fmt.emittedPoints };
              }),
            );
            for (const s of settled) {
              if (s.status !== 'fulfilled' || s.value === null) continue;
              allBlocks.push(s.value.rendered);
              totalPoints += s.value.points;
            }
          }
          if (allBlocks.length > 0) {
            trajectoryBlock = allBlocks.join('\n\n');
            trajectoryPointsCount = totalPoints;
          }
        }
      }
    } catch (err) {
      // Defensive: trajectory injection is best-effort. Any unexpected
      // error degrades to "no trajectory block" + a warning. The think
      // call itself never fails because of trajectory wiring.
      // D6: code-only on the wire; raw exception text goes to server logs.
      warnings.push('TRAJECTORY_INJECTION_FAILED');
      process.stderr.write(`[think] trajectory injection failed: ${err instanceof Error ? err.message : String(err)}\n`);
    }
  }
  if (trajectoryPointsCount > 0) warnings.push(`TRAJECTORY_INJECTED_${trajectoryPointsCount}_POINTS`);
  if (trajectoryExcludedCount > 0) warnings.push(`WINDOW_EXCLUDED_${trajectoryExcludedCount}_TRAJECTORY_POINTS`);

  const abstention = await thinkDecide?.answerability({ pages: gather.pages, takes: gather.takes, trajectory: trajectoryBlock.length > 0 }).catch(() => null); // System One S4
  if (abstention) return thinkAbstainResult(opts.question, gather, modelUsed, warnings, abstention);

  // SYNTHESIZE
  const intent = inferIntent(opts.question, opts.anchor);
  const systemPrompt = buildThinkSystemPrompt({
    currentDate: true, intent, willSave: opts.save, withCalibration: !!calibrationBlockOpts,
    ...(opts.anchor !== undefined ? { anchor: opts.anchor } : {}),
    ...(resolvedWindow?.since !== undefined ? { since: resolvedWindow.since } : {}),
    ...(resolvedWindow?.until !== undefined ? { until: resolvedWindow.until } : {}),
  });
  const userMessage = buildThinkUserMessage({
    question: opts.question, pagesBlock, takesBlock, currentDate: `${temporal.referenceDate} (${temporal.timeZone})`,
    ...(graphBlock !== undefined ? { graphBlock } : {}),
    ...(calibrationBlockOpts !== undefined ? { calibration: calibrationBlockOpts } : {}),
    ...(trajectoryBlock.length > 0 ? { trajectoryBlock } : {}),
  });

  // #1698: true only when an actual synthesis produced a non-empty answer. Set false
  // on the not-JSON branch (covers malformed output AND the buildGracefulMessage
  // sentinel, which is non-JSON) and on the no-client early return below; the final
  // return ANDs it with a non-empty-answer check (catches valid-but-empty JSON).
  let synthesisOk = true;
  // [WP2/T5] typed compose status. Starts 'ok'; failure branches overwrite it
  // with their specific value; the parsed-but-empty check at the bottom is the
  // only downgrade applied to a still-'ok' status.
  let synthesisStatus: ThinkSynthesisStatus = 'ok';
  // [E2] best-effort usage aggregation across synthesis calls (single-pass in
  // v0.28+, but summed so the round loop inherits it when gap-fill lands).
  let usage: { input_tokens: number; output_tokens: number } | null = null;
  let fallback: { answered_by: string; reason?: string } | undefined;
  // Initialized to the llm_error shape; every non-throwing branch overwrites it.
  let response: ThinkResponse = { answer: '', citations: [], gaps: [] };
  if (opts.stubResponse) {
    response = opts.stubResponse;
  } else {
    // Build a ThinkLLMClient. Three sources, in priority order:
    //   1. opts.client (test injection — preserved as test seam)
    //   2. Gateway adapter (routes through gateway.chat() — picks up
    //      anthropic_api_key from gbrain config OR env, gateway rate-leases,
    //      retry, prompt caching, the canonical seam per CLAUDE.md)
    //   3. Graceful fallback ("no LLM available" stub) — when gateway is
    //      unconfigured AND no env var is set, return without throwing.
    //
    // Pre-v0.36, this code path constructed `new Anthropic()` directly.
    // That bypassed gateway config (gbrain config set anthropic_api_key)
    // because the Anthropic SDK only reads process.env.ANTHROPIC_API_KEY.
    // Closes #952 (think over MCP returns "no LLM available").
    const client = opts.client ?? await tryBuildGatewayClient(modelUsed, { explicitModel: opts.modelExplicit, allowFallback: opts.allowFallback });
    if (!client) {
      // Label the failure honestly: a missing key and an unusable model id are
      // different incidents with different fixes. Pre-fix EVERY null client was
      // stamped NO_ANTHROPIC_API_KEY, which sent operators chasing env/keychain
      // problems when the real cause was a model id the recipe didn't know
      // (e.g. a tier-configured model newer than the recipe list). The re-probe
      // is pure and cheap (no IO): same predicate tryBuildGatewayClient used.
      const probe = probeChatModel(normalizeModelId(modelUsed));
      const modelProblem = !probe.ok && probe.reason !== 'unavailable';
      warnings.push(
        modelProblem ? `MODEL_NOT_USABLE:${(probe as { reason: string }).reason}` : 'NO_ANTHROPIC_API_KEY',
      );
      const detail = !probe.ok ? probe.detail : '';
      const fix = !probe.ok && probe.fix ? ` Fix: ${probe.fix}` : '';
      // [WP2/E2] non-empty gather still has value — attach the extractive
      // digest so callers (the synthesize verb) can surface it instead of
      // the stub answer. Null on empty gather (never fabricate).
      const stubExtractive = composeExtractiveFallback(gather.pages, opts.question, opts.remote !== false);
      // Degrade gracefully: return the gather without synthesis. Better than throwing.
      return {
        question: opts.question,
        ...withGuestAnswer(gather.pages, { answer: modelProblem
          ? `(model "${modelUsed}" not usable — ${detail}${fix})`
          : '(no LLM available — set ANTHROPIC_API_KEY or pass `client`)' }),
        citations: [],
        gaps: [
          modelProblem
            ? `model "${modelUsed}" not usable (${(probe as { reason: string }).reason}); gather succeeded but synthesis skipped`
            : 'no LLM available; gather succeeded but synthesis skipped',
        ],
        pagesGathered: gather.pages.length,
        takesGathered: gather.takes.length,
        graphHits: gather.graphSlugs.length,
        modelUsed,
        rounds: 0,
        warnings,
        synthesisOk: false,  // #1698: no LLM ran — never persist this
        synthesis_status: modelProblem ? 'model_unusable' : 'no_llm',
        ...(stubExtractive ? { extractive: stubExtractive } : {}),
        // GBRA-498: the extractive digest quotes the gathered pages, so a room marks this answer from them too.
        taint_refs: [...gather.pages.map(pg => ({ table: 'pages' as const, sourceId: pg.source_id ?? 'default', slug: pg.slug })),
          ...gather.takes.map(t => ({ table: 'takes' as const, id: t.take_id }))],
        usage: null,         // [E2] no LLM ran — no accounting
        ...windowMeta,
        diagnostics: {
          pagesFromHybrid: gather.diagnostics.pagesFromHybrid,
          takesFromKeyword: gather.diagnostics.takesFromKeyword,
          takesFromVector: gather.diagnostics.takesFromVector,
          graphHits: gather.diagnostics.graphHits,
        },
      };
    }
    let created: Anthropic.Message | null = null;
    try {
      created = await client.create({
        model: modelUsed,
        max_tokens: maxOutputTokensFor(normalizeModelId(modelUsed)),
        system: systemPrompt,
        messages: [{ role: 'user', content: userMessage }],
      });
    } catch (e) {
      // [ENG-10] provider/transport failures (429, timeout, 5xx, network)
      // become a typed llm_error status instead of killing the whole call —
      // gather already succeeded and the caller can still act on it. Three
      // throw classes stay hard: the explicit-model config error (#1698 — the
      // gateway adapter only lets AIConfigError escape on the explicit path),
      // budget exhaustion (spend control must stop the enclosing loop), and
      // aborts (cancellation is control flow, not an LLM failure).
      const name = e instanceof Error ? e.name : '';
      if ((opts.modelExplicit && e instanceof AIConfigError) || name === 'BudgetExhausted' || name === 'AbortError') {
        throw e;
      }
      // D6 closed vocabulary: the wire carries the coarse class only; the raw
      // provider/transport message goes to stderr for the operator.
      warnings.push(`LLM_CALL_FAILED: ${classifyLlmCallFailure(e)}`);
      process.stderr.write(`[think] LLM call failed (${classifyLlmCallFailure(e)}): ${e instanceof Error ? e.message : String(e)}\n`);
      synthesisStatus = 'llm_error';
      synthesisOk = false;
      // response keeps its empty llm_error initialization.
    }
    if (created) {
      fallback = (created as { fallback?: { answered_by: string; reason?: string } }).fallback;
      usage = addMessageUsage(usage, created);
      const block = created.content.find(b => b.type === 'text');
      const text = block && 'text' in block ? block.text : '';
      const parsed = tryParseJSON(text);
      if (!parsed || typeof parsed !== 'object') {
        // #4375: a max_tokens stop means the envelope was CUT, not malformed —
        // label it honestly so operators raise the budget instead of chasing
        // model-output bugs. The adapter maps gateway 'length' to 'max_tokens'.
        const stop = (created as { stop_reason?: string }).stop_reason;
        if (stop === 'max_tokens') {
          warnings.push('LLM_OUTPUT_TRUNCATED');
          synthesisStatus = 'output_truncated';
        } else {
          warnings.push('LLM_OUTPUT_NOT_JSON');
          // Refusals + the graceful sentinel land here too — coarse on purpose
          // (no dedicated status; the raw text stays in `answer` for consumers).
          synthesisStatus = 'not_json';
        }
        synthesisOk = false;  // #1698: malformed output (and the non-JSON graceful sentinel)
        // #4509: a malformed JSON envelope (max-token truncation is the
        // common cause) previously shipped VERBATIM as the user-facing
        // answer. Salvage the answer/citations/gaps fields tolerantly; when
        // the text is JSON-shaped but unsalvageable, emit no answer at all
        // (the extractive fallback below carries the content) — never raw
        // JSON to the user.
        const salvaged = salvageThinkEnvelope(text);
        if (salvaged) {
          warnings.push('SALVAGED_ANSWER_FROM_MALFORMED_JSON');
          response = salvaged;
        } else if (looksLikeJsonEnvelope(text)) {
          warnings.push('MALFORMED_JSON_ANSWER_SUPPRESSED');
          response = { answer: '', citations: [], gaps: [] };
        } else {
          response = { answer: text, citations: [], gaps: [] };
        }
      } else {
        response = toThinkResponse(parsed as Partial<ThinkResponse>);
      }
    }
  }

  // Resolve citations: prefer structured, fall back to inline-marker regex scan.
  const resolved = resolveCitations(response.citations, response.answer);
  if (resolved.warnings.length > 0) {
    for (const w of resolved.warnings) warnings.push(w);
  }

  // #4376: close resolved citations against the gathered evidence — a cited
  // slug absent from every gather stream is unverifiable provenance. Warn-only;
  // the never-fail synthesis contract (cite-render.ts) stays intact.
  const gatheredSlugs = new Set<string>([
    ...gather.pages.map(p => p.slug),
    ...gather.takes.map(t => t.page_slug),
    ...gather.graphSlugs,
  ]);
  for (const slug of new Set(resolved.citations.map(c => c.page_slug))) {
    if (!gatheredSlugs.has(slug)) warnings.push(`CITATION_NOT_IN_GATHER:${slug}`);
  }
  stampCitationSources(resolved.citations, gather.pages);

  // Round-loop scaffolding (rounds > 1 currently re-runs without gap-driven retrieval).
  // The loop is in place so the v0.29 gap-fill heuristic doesn't change the call site.
  for (let r = 1; r < rounds; r++) {
    warnings.push(`ROUNDS_GT_1_NOT_GAP_DRIVEN_IN_V028`);
    break;  // v0.28: single-pass only
  }

  // [WP2/T5] parsed-but-empty answer gets its own status; branches that
  // already flagged a more specific failure keep theirs.
  if (synthesisStatus === 'ok' && response.answer.trim().length === 0) {
    synthesisStatus = 'empty_answer';
    warnings.push('SYNTHESIS_EMPTY_ANSWER');
  }
  // [WP2/E2] compose failed + non-empty gather → attach extractive material
  // (callers decide whether to surface it; null on empty gather — ENG-19).
  const extractive = synthesisStatus !== 'ok'
    ? composeExtractiveFallback(gather.pages, opts.question, opts.remote !== false)
    : null;

  return {
    question: opts.question,
    ...withGuestAnswer(gather.pages, { answer: response.answer, ...(synthesisStatus === 'ok' ? await groundThinkAnswer(engine, response.answer, [opts.question, pagesBlock, takesBlock, graphBlock ?? '', trajectoryBlock], warnings) : {}) }),
    citations: resolved.citations,
    gaps: response.gaps,
    pagesGathered: gather.pages.length,
    takesGathered: gather.takes.length,
    graphHits: gather.graphSlugs.length,
    modelUsed: fallback?.answered_by ?? modelUsed,
    ...(fallback ? { requested_model: modelUsed, ...(fallback.reason ? { fallback_reason: fallback.reason } : {}) } : {}),
    rounds: 1,
    warnings,
    // #1698: persistable only when a real synthesis produced a non-empty answer.
    // ANDs the not-JSON/sentinel flag with a content check (catches valid-but-empty JSON).
    synthesisOk: synthesisOk && response.answer.trim().length > 0,
    synthesis_status: synthesisStatus,
    evidence_truncated: evidenceTruncated,
    feedback_evidence: gather.pages.map(pg => ({ source_id: pg.source_id ?? 'default', slug: pg.slug, content_hash: pg.content_hash ?? null })),
    taint_refs: [...gather.pages.map(pg => ({ table: 'pages' as const, sourceId: pg.source_id ?? 'default', slug: pg.slug })),
      ...gather.takes.map(t => ({ table: 'takes' as const, id: t.take_id })), ...trajectoryFactIds.map(id => ({ table: 'facts' as const, id }))],
    room_extra: [...(graphBlock ? (gather.graphRefs ?? gather.graphSlugs.map(slug => ({ slug, sourceId: opts.sourceId ?? 'default' })))
      .filter(r => gather.graphSlugs.slice(0, 30).includes(r.slug)).map(r => ({ table: 'pages' as const, sourceId: r.sourceId, slug: r.slug })) : []),
      ...(calibrationBlockOpts ? [{ table: 'calibration' as const, id: 0 }] : [])],
    ...(extractive ? { extractive } : {}),
    usage, ...(evidenceDelivery ? { evidence_delivery: evidenceDelivery } : {}),
    diagnostics: {
      pagesFromHybrid: gather.diagnostics.pagesFromHybrid,
      takesFromKeyword: gather.diagnostics.takesFromKeyword,
      takesFromVector: gather.diagnostics.takesFromVector,
      graphHits: gather.diagnostics.graphHits,
    },
    temporal: { reference_date: temporal.referenceDate, time_zone: temporal.timeZone },
    ...windowMeta,
    persist_base: persistBase,
  };
}

/**
 * [E2] `prev` plus the message's token usage; `prev` unchanged when the message carries none
 * (test-injected clients and providers without accounting). Single synthesis call in v0.28+;
 * when gap-driven rounds land, runThink sums each round through here.
 */
function addMessageUsage(
  prev: { input_tokens: number; output_tokens: number } | null,
  message: unknown,
): { input_tokens: number; output_tokens: number } | null {
  const u = (message as { usage?: { input_tokens?: number; output_tokens?: number } }).usage;
  if (!u || typeof u.input_tokens !== 'number' || typeof u.output_tokens !== 'number') return prev;
  return { input_tokens: (prev?.input_tokens ?? 0) + u.input_tokens, output_tokens: (prev?.output_tokens ?? 0) + u.output_tokens };
}

/** Normalizes the model's parsed JSON envelope. */
function toThinkResponse(r: Partial<ThinkResponse>): ThinkResponse {
  return {
    answer: typeof r.answer === 'string' ? r.answer : '',
    citations: Array.isArray(r.citations) ? (r.citations as ThinkResponse['citations']) : [],
    gaps: Array.isArray(r.gaps) ? (r.gaps as string[]).filter(g => typeof g === 'string') : [],
  };
}

/**
 * Strip a "## Gaps" section from an answer body.
 *
 * `think` returns gaps in the structured `gaps` array, which the CLI and the
 * persisted synthesis page render exactly once. The system prompt also used to
 * ask for a "Gaps" section inside the answer prose, so a model that still emits
 * one would make the output show "## Gaps" twice — once from the prose, once
 * from the structured array. This removes the prose section so the structured
 * array stays the single source of truth.
 *
 * Matches a heading line `## Gaps` (level 2-6, case-insensitive) and removes it
 * through the next heading of the same-or-higher level, or end of string.
 * Returns the input unchanged when there is no such section.
 */
export function stripGapsSection(answer: string): string {
  if (!answer) return answer;
  const lines = answer.split('\n');
  let start = -1;
  let level = 0;
  for (let i = 0; i < lines.length; i++) {
    const m = /^(#{2,6})\s+gaps\s*$/i.exec(lines[i]);
    if (m) { start = i; level = m[1].length; break; }
  }
  if (start === -1) return answer;
  let end = lines.length;
  for (let i = start + 1; i < lines.length; i++) {
    const h = /^(#{1,6})\s+\S/.exec(lines[i]);
    if (h && h[1].length <= level) { end = i; break; }
  }
  const kept = [...lines.slice(0, start), ...lines.slice(end)].join('\n');
  // Drop trailing blank lines left by removing a trailing section.
  return kept.replace(/\s+$/, '');
}

/** The synthesis page of a question on a day: `synthesis/<slugified-question>-<date>`. */
function synthesisSlug(question: string, today: string): string {
  const slugSafe = question.toLowerCase().replace(/[^a-z0-9\s]+/g, '').trim().replace(/\s+/g, '-').slice(0, 60) || 'untitled';
  return `synthesis/${slugSafe}-${today}`;
}

/**
 * Persist a synthesis page + its evidence. Returns the saved slug.
 * Synthesis pages are written under `synthesis/<slugified-question>-<date>.md` as a single-item `think_synthesis`
 * generation (GBRA-161 PR 5): bound to the revision the run found before gathering (`persist_base`, else read now), so a
 * page that changed meanwhile is fenced (`generation_fenced`), and the page it replaces is versioned first.
 */
export async function persistSynthesis(
  engine: BrainEngine,
  result: ThinkResult,
  scope: { sourceId?: string; allowedSources?: string[] } = {},
): Promise<{ slug: string; evidenceInserted: number; warnings: string[] }> {
  // #1698: never persist an empty synthesis. Returned signal (NOT a throw, F3) so
  // the MCP `think` op can return the gather result + warning instead of a bare error
  // envelope; the CLI keys off this warning to exit non-zero. Guard on `=== false` so
  // pre-existing/test ThinkResult literals without the field still persist (back-compat).
  if (result.synthesisOk === false) {
    return { slug: '', evidenceInserted: 0, warnings: ['SYNTHESIS_EMPTY_NOT_PERSISTED'] };
  }

  const today = new Date().toISOString().slice(0, 10);
  const slug = synthesisSlug(result.question, today);

  // Build the markdown body. A claim whose quote is not in the evidence is not saved as prose;
  // it goes to frontmatter unverified_claims (reviewable with get_page, out of search and recall).
  const body = [
    `# ${result.question}`,
    '',
    stripGapsSection(result.persist?.answer ?? result.answer),
    '',
    result.gaps.length > 0 ? '## Gaps\n\n' + result.gaps.map(g => `- ${g}`).join('\n') : '',
  ].filter(Boolean).join('\n');

  const derivation = await deriveTrust(engine, result.taint_refs ?? [], { channel: 'derive:think' });
  const sourceId = scope.sourceId ?? 'default';
  const base = result.persist_base;
  const expectedRevision = base && base.slug === slug && base.sourceId === sourceId ? base.revision
    : (await engine.readPageSnapshot(slug, { sourceId, includeDeleted: true }))?.revision ?? null;
  const { pageId } = await publishSinglePage(engine, { kind: THINK_SYNTHESIS_KIND, sourceId, slug, expectedRevision, derivation, page: {
    title: result.question.slice(0, 200),
    type: 'synthesis',
    compiled_truth: body,
    frontmatter: {
      type: 'synthesis',
      question: result.question,
      model: result.modelUsed,
      date: today,
      pages_gathered: result.pagesGathered,
      takes_gathered: result.takesGathered,
      ...(result.persist?.unverified_claims.length ? { unverified_claims: result.persist.unverified_claims.map(c => ({ ...c, sources: ['think evidence'], detected_at: today })) } : {}),
    },
  } });

  const persisted = await persistCitations(engine, pageId!, result.citations, scope);
  return { slug, evidenceInserted: persisted.inserted, warnings: persisted.warnings };
}

// ─────────────────────────────────────────────────────────────────
// Gateway adapter for #952 (think over MCP returns "no LLM available").
// ─────────────────────────────────────────────────────────────────
// Pre-v0.36, runThink instantiated `new Anthropic()` directly and read
// ANTHROPIC_API_KEY from process.env. Claude Desktop's stdio MCP launch
// doesn't inherit shell env, so `gbrain config set anthropic_api_key sk-...`
// (which writes to ~/.gbrain/config.json) never reached the SDK and every
// MCP think call degraded to "no LLM available."
//
// The adapter routes through gateway.chat() — the canonical seam per
// CLAUDE.md. Gateway reads the API key from gbrain config OR env, picks
// up prompt caching, rate-leases, retry, and the test seam
// (__setChatTransportForTests) that v0.31.12 already established.
//
// Per plan-eng-review D10 (cross-model tension with codex C7+C8+C9+C10),
// the adapter implements four fixes:
//   1. Drop the new Anthropic() direct path entirely — always route through gateway
//   2. Real availability check via try/catch around resolveRecipe + assertion
//      (NOT the false-positive `getChatModel()` truthy check)
//   3. Model-id resolution: handle both bare (`claude-opus-4-7`) and
//      provider-prefixed (`anthropic:claude-opus-4-7`) shapes
//   4. Response-shape conversion: ChatResult → Anthropic.Message
//
// `opts.client` injection path is preserved (test seam — see ThinkLLMClient).
// `opts.stubResponse` path is preserved (pure-test escape).
// ─────────────────────────────────────────────────────────────────

/**
 * v0.40.2.0 — read the `think.trajectory_enabled` config key. Default
 * true. Returns false ONLY when the value is set AND parses to a false
 * string. Any read error (table missing on pre-v36 brains, etc.) returns
 * true so users on legacy installs still get the feature. The flag is
 * the kill switch for the rare prod regression.
 */
async function readThinkTrajectoryEnabled(engine: BrainEngine): Promise<boolean> {
  try {
    const v = await engine.getConfig('think.trajectory_enabled');
    if (v === null || v === undefined) return true;
    const lower = v.trim().toLowerCase();
    if (lower === 'false' || lower === '0' || lower === 'no' || lower === 'off') return false;
    return true;
  } catch {
    return true;
  }
}

/**
 * Ground every quoted span of a synthesized answer against the evidence blocks
 * the prompt carried, the user's question included (quoting the question back
 * is supported). Empty when think.quote_verify is off or the answer has no
 * quotes; otherwise the safe answer, what the model wrote, the counts, and the
 * body persistSynthesis saves (failing claim units removed).
 */
async function groundThinkAnswer(engine: BrainEngine, answer: string, blocks: string[], warnings: string[]):
  Promise<Partial<Pick<ThinkResult, 'answer' | 'answer_raw' | 'quote_check' | 'unverified_quotes' | 'persist'>>> {
  if (answer.trim().length === 0 || !await readThinkQuoteVerify(engine)) return {};
  const { groundSource, groundAnswerQuotes, verifyBody } = await import('../cycle/synthesize-verify.ts');
  const sources = blocks.map((block, i) => ({ block, i })).filter(b => b.block.trim().length > 0)
    .map(b => groundSource(`think-evidence-${b.i}`, b.block, { tolerant: true }));
  const check = groundAnswerQuotes(answer, sources);
  if (check.quote_check.grounded + check.quote_check.repaired + check.quote_check.unverified === 0) return {};
  if (check.quote_check.unverified > 0) warnings.push('QUOTE_NOT_IN_EVIDENCE');
  const persisted = verifyBody(answer, sources, { checks: 'quotes' });
  return { answer: check.answer, answer_raw: answer, quote_check: check.quote_check, unverified_quotes: check.unverified_quotes,
    persist: { answer: persisted.body, unverified_claims: persisted.quarantined } };
}

/** `think.quote_verify` (on unless set false): ground quoted spans in think answers against the prompt's evidence. */
async function readThinkQuoteVerify(engine: BrainEngine): Promise<boolean> {
  try {
    const v = await engine.getConfig('think.quote_verify');
    return !v || !['false', '0', 'no', 'off'].includes(v.trim().toLowerCase());
  } catch {
    return true;
  }
}

/**
 * Try to build a gateway-backed ThinkLLMClient for the given model.
 * Returns null when the gateway cannot resolve a usable chat provider for
 * this model (missing API key for the resolved provider, unknown provider,
 * touchpoint not supported, etc.). Caller falls through to the graceful
 * "no LLM available" stub on null.
 */
async function tryBuildGatewayClient(
  modelUsed: string,
  opts: { explicitModel?: boolean; allowFallback?: boolean } = {},
): Promise<ThinkLLMClient | null> {
  // Normalize: ensure provider:model shape (and slash→colon — #1698). resolveModel
  // returns bare anthropic ids (`claude-opus-4-7`); gateway.chat needs `anthropic:...`.
  const modelStr = normalizeModelId(modelUsed);

  // #1698: ONE shared probe (resolveRecipe + assertTouchpoint + isAvailable).
  // assertTouchpoint catches chat-less providers (voyage/ollama); isAvailable
  // catches missing keys. Model-id typos are NOT caught locally (no runtime
  // allowlist) — a nonexistent id fails at the provider with model_not_found.
  // For an EXPLICIT model the user typed, an unusable model is a HARD ERROR (throw)
  // — never silently degrade to the no-LLM stub. For the default/configured-model
  // path, return null so the caller falls through to the graceful "no LLM" stub
  // (preserves the documented no-key gather-only behavior).
  const probe = probeChatModel(modelStr);
  if (!probe.ok) {
    if (opts.explicitModel) {
      throw new Error(
        `think: --model "${modelUsed}" is not usable (${probe.reason}): ${probe.detail}. ` +
        `Refusing to run synthesis with no model — fix the model id or omit --model.` +
        (probe.fix ? ` Fix: ${probe.fix}` : ''),
      );
    }
    return null;
  }

  return {
    create: async (params): Promise<Anthropic.Message> => {
      // Build ChatOpts from Anthropic.MessageCreateParamsNonStreaming.
      const messages = params.messages.map(m => ({
        role: m.role,
        content: typeof m.content === 'string'
          ? m.content
          : (Array.isArray(m.content) ? m.content.map(b => 'text' in b ? b.text : '').join('') : ''),
      }));
      const system = typeof params.system === 'string'
        ? params.system
        : (Array.isArray(params.system) ? params.system.map(b => 'text' in b ? b.text : '').join('') : undefined);

      let result: ChatResult;
      try {
        // #7176: chat_usage_log rows for think say so, unless a job or cycle phase already does.
        result = await withDefaultChatPhase('think', () => gatewayChat({
          model: modelStr,
          system,
          messages,
          maxTokens: params.max_tokens,
          // An explicit --model is a hard requirement (#1698), never a hop.
          ...(opts.explicitModel || opts.allowFallback === false ? { allowFallback: false } : {}),
        }));
      } catch (e) {
        // AIConfigError at chat time = e.g. key revoked mid-run. For an EXPLICIT
        // model the user typed, this is a hard error (rethrow) — the early gate
        // normally catches it first; this is defense-in-depth. For the default
        // path, surface a sentinel "no LLM available"-shaped Message so the
        // existing JSON-parse path produces the graceful degradation answer.
        if (e instanceof AIConfigError) {
          if (opts.explicitModel) throw e;
          return buildGracefulMessage(modelStr, e) as unknown as Anthropic.Message;
        }
        throw e;
      }
      return chatResultToMessage(result, modelStr) as unknown as Anthropic.Message;
    },
  };
}

/**
 * Convert gateway's `ChatResult` into an Anthropic-Message-shaped object.
 * The caller (`runThink`) parses `result.content[0].text` as JSON; the
 * other fields (usage, stop_reason) are returned with best-effort mapping
 * for downstream telemetry compat.
 */
function chatResultToMessage(result: ChatResult, modelStr: string): {
  id: string;
  type: 'message';
  role: 'assistant';
  model: string;
  fallback?: { answered_by: string; reason?: string };
  content: Array<{ type: 'text'; text: string }>;
  usage: { input_tokens: number; output_tokens: number };
  stop_reason: 'end_turn' | 'max_tokens' | 'tool_use' | 'stop_sequence';
} {
  return {
    id: '',
    type: 'message',
    role: 'assistant',
    model: modelStr,
    ...(result.fallbackFrom ? { fallback: { answered_by: result.model, ...(result.fallbackReason ? { reason: result.fallbackReason } : {}) } } : {}),
    content: [{ type: 'text', text: result.text }],
    usage: {
      input_tokens: result.usage.input_tokens,
      output_tokens: result.usage.output_tokens,
    },
    stop_reason: mapStopReason(result.stopReason),
  };
}

function mapStopReason(s: ChatResult['stopReason']): 'end_turn' | 'max_tokens' | 'tool_use' | 'stop_sequence' {
  switch (s) {
    case 'end': return 'end_turn';
    case 'length': return 'max_tokens';
    case 'tool_calls': return 'tool_use';
    // 'refusal', 'content_filter', 'other' → end_turn (no Anthropic equivalent)
    default: return 'end_turn';
  }
}

/**
 * Sentinel Message returned when gateway.chat throws AIConfigError (missing
 * API key, or the provider rejecting the model/config with a 4xx — with no
 * runtime model allowlist, a nonexistent model id surfaces here as the
 * provider's model_not_found). The caller's JSON parser will fail on this
 * text, fall through to `LLM_OUTPUT_NOT_JSON`, and surface the sentinel as
 * the answer — matches the legacy graceful-degradation shape.
 *
 * When the thrown error is in hand, its own message + fix are surfaced (they
 * name the actual cause: which key is missing, or what the provider rejected)
 * instead of the generic key advice — the generic text key-blamed provider
 * 4xxs like model_not_found.
 */
function buildGracefulMessage(modelStr: string, err?: AIConfigError): {
  id: string;
  type: 'message';
  role: 'assistant';
  model: string;
  content: Array<{ type: 'text'; text: string }>;
  usage: { input_tokens: number; output_tokens: number };
  stop_reason: 'end_turn';
} {
  return {
    id: '',
    type: 'message',
    role: 'assistant',
    model: modelStr,
    content: [{
      type: 'text',
      text: err
        ? `(no LLM available — ${err.message}${err.fix ? ` Fix: ${err.fix}` : ''})`
        : '(no LLM available — set anthropic_api_key via gbrain config or ANTHROPIC_API_KEY env)',
    }],
    usage: { input_tokens: 0, output_tokens: 0 },
    stop_reason: 'end_turn',
  };
}

// Test-only exports for the adapter helpers. The functions live at module
// scope (not inside runThink) so they can be unit-tested directly. Naming
// follows the `__` prefix convention already established by
// `__setChatTransportForTests` in gateway.ts.
export const __thinkAdapter = {
  tryBuildGatewayClient,
  chatResultToMessage,
  mapStopReason,
  buildGracefulMessage,
  hasAnthropicKey,
};