Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
47.8 KB
Raw Blame
/**
 * Agent operator contract v1 (docs/designs/AGENT_OPERATOR_WAVE.md, A0/A1/A6).
 *
 * One `Action` (`fix`) for every failure, refusal, degradation and
 * recommendation; one error envelope (`AgentEnvelope`) for CLI `--json`, MCP
 * `isError` results and HTTP bodies; one notice wire format. `next` and the
 * shell `command` are computed here at render time and never stored.
 *
 * Everything an agent reads is built from static registry templates plus
 * interpolated ids that pass through `inertText()`: newlines and marker
 * tokens are neutralised so a page title can never forge an instruction.
 */
import { existsSync } from 'node:fs';
import { join } from 'node:path';
import { VERSION } from '../version.ts';
import { OperationError, __registerOperationErrorRenderer, provesNotAdmitted, type WithdrawnDetail } from './ops/contract.ts';
import { StructuredAgentError } from './errors.ts';
import { canonicalCodeFor, codeEntry, codeClass, codeRetryable, exitCodeForCode } from './error-catalogue.ts';
import { VERB_NAMES } from './verbs.ts';
import { classifyPgAccessError, formatDbAccessMarker } from './pg-access-classify.ts';
import { isReadOnlyTransactionError } from './postgres-engine/read-write-transactions.ts';
import { redactConnectionInfo } from './audit/redact-connection-info.ts';
import { redactUrlsInText } from './url-redact.ts';
import { parseRepoBase } from './repo-base.ts';
import { recordAgentContractEvent } from './agent-contract-log.ts';
import { cliRouting, pinRouting, type FixRouting } from './fix-routing.ts';

export const CONTRACT_VERSION = 1 as const;

export type Effect = 'paid' | 'destructive' | 'credentials' | 'egress' | 'persistent_install';
export type Actor = 'agent' | 'user' | 'host_admin' | 'provider';
export type Next = 'run' | 'ask_user' | 'tell_user_to_run' | 'wait' | 'report';
/** A fix expected to run longer than this is the user's or host admin's (`tell_user_to_run`), never the agent's. */
export const AGENT_TOOL_LIMIT_MS = 120_000;
export type Transport = 'cli' | 'stdio' | 'http';
export type Surface = 'verbs' | 'starter' | 'full';
export type ErrorClass = 'caller' | 'consent' | 'retryable' | 'unavailable' | 'server' | 'host_only';

export interface McpCall { tool: string; arguments: Record<string, unknown> }

/** A value the agent must obtain before running (e.g. a model's price). argv holds `<name>` only for these. */
export interface ActionInput { name: string; how: string }

/** Stored/constructed form. Never carries `next` or `command`: both are computed at render time. */
export interface Action {
  /** Escalation only: an action the agent must not take without asking renders `next: ask_user` whatever else it carries. */
  ask_user?: true;
  argv?: string[];
  mcp?: McpCall;
  consent: Effect[];
  actor: Actor;
  why: string;
  user_message?: string;
  verify?: { argv?: string[]; mcp?: McpCall };
  docs?: string;
  requires_exclusive: boolean;
  inputs?: ActionInput[];
  plan_hash?: string;
  preview_argv?: string[];
  then?: Action;
}

/** Wire form: what an agent reads. */
export interface RenderedAction extends Omit<Action, 'then' | 'docs' | 'ask_user'> {
  command?: string;
  next: Next;
  docs?: string;
  then?: RenderedAction;
}

export type NoticeKind = 'safety' | 'degraded' | 'coaching' | 'ask' | 'info';
export interface DecisionOption { id: string; label: string; argv?: string[] }
export interface Decision { id: string; question: string; options: DecisionOption[]; default: string; default_reason: string }

export interface Notice {
  code: string;
  kind: NoticeKind;
  why: string;
  fix?: Action;
  user_message?: string;
  decisions?: Decision[];
  /**
   * Unrendered: the NoticeLedger's dedupe identity. A per-call code carrying
   * one is deduped per session under `code` + this key instead of riding
   * every call; any code carrying one dedupes under it instead of `code`
   * alone. renderNotice never copies it, so it never reaches the wire.
   */
  dedupe_key?: string;
  /**
   * Unrendered (#7165): a coverage notice whose repeat of the same state is
   * suppressed per session (NoticeLedger) and per one-shot CLI window, until
   * `level` rises materially or the `key` (code, sources, kinds) is new.
   */
  escalation?: { key: string; level: number };
}
export interface RenderedNotice extends Omit<Notice, 'fix'> { fix?: RenderedAction; contract_version: 1 }

/** The one error envelope (CLI --json document, MCP isError content[0], HTTP bodies). */
export interface AgentEnvelope {
  error: string;
  code: string;
  reason?: string;
  message: string;
  suggestion: string;
  why?: string;
  fix?: RenderedAction;
  docs?: string;
  docs_cmd: string[];
  class: ErrorClass;
  retryable: boolean;
  notices?: RenderedNotice[];
  contract_version: 1;
  detail?: string; protocol_version?: 1; write_request?: unknown; write_error?: string;
  /** #6188: a fence refusal's location and blocking issues (location and class only). */
  fence?: Record<string, unknown>; fence_issues?: Array<Record<string, unknown>>;
  /** A `fact_withdrawn` refusal's withdrawal (`at`, `subject`, `visibility`). */
  withdrawn?: WithdrawnDetail;
  /** A write-grant refusal's writable sources, from the caller's own grant only (GBRA-200). */
  writable_source_ids?: string[];
}

export interface RenderContext {
  transport: Transport;
  surface?: Surface;
  isCallable(opName: string): boolean;
  preapproved(effects: Effect[], estUsd?: number | null): boolean;
  principal?: string;
  /** A1: the brain/source the failing call acted on; renderAction pins them into gbrain argv (src/core/fix-routing.ts). */
  routing?: FixRouting;
}

export interface AgentErrorContext {
  transport: Transport;
  op?: string;
  command?: string;
  mutating?: boolean;
  idempotent?: boolean;
  outcome?: 'not_started' | 'failed' | 'unknown' | 'committed' | 'pending';
  render: RenderContext;
  /** Additive: the configured DB url + resolved brain id for the GBRAIN_DB_ACCESS classifier row (a mount never reads as host). */
  db?: { url: string | null; brainId?: string };
}

export interface CliErrorRender { stdout?: string; stderr?: string; exitCode: number }

/** Attached to OperationContext (MCP) and the CLI dispatch context. */
export interface NoticeSink { emitNotice(n: Notice): void }

// ── render context defaults ────────────────────────────────────────────────

/** The trusted local CLI: no MCP tool is callable from a shell, nothing is preapproved unless A4 says so. */
export function cliRenderContext(overrides: Partial<RenderContext> = {}): RenderContext {
  const routing = cliRouting();
  return { transport: 'cli', isCallable: () => false, preapproved: () => false, ...(routing ? { routing } : {}), ...overrides };
}

// ── text safety ────────────────────────────────────────────────────────────

const MARKER_RE = /\[(\/?)(AGENT|SHOW USER|gbrain notice)/gi;
const MAX_INLINE = 2_000;

/**
 * Neutralise interpolated text for any agent-visible channel: newlines become
 * spaces and marker tokens lose their opening bracket, so `[/SHOW USER]` in a
 * page title renders as `(/SHOW USER]` and cannot close or open a block.
 */
export function inertText(value: string, max: number = MAX_INLINE): string {
  const flat = value.replace(/\r\n|\r|\n|\u2028|\u2029/g, ' ').replace(MARKER_RE, '($1$2');
  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
}

const SAFE_SHELL = /^[A-Za-z0-9_@%+=:,./-]+$/;

/** POSIX shell quoting; the only way a human `command` string is built. */
export function shellQuote(argv: readonly string[]): string {
  return argv.map(arg => {
    if (arg === '') return "''";
    if (SAFE_SHELL.test(arg)) return arg;
    return `'${inertText(arg).replace(/'/g, `'\\''`)}'`;
  }).join(' ');
}

/**
 * Split a literal shell command that a legacy site stored as a string (F0's
 * refusal `fix`, a `suggestion` that is exactly one command) into argv. Only
 * `gbrain …` commands made of plain or single-quoted words qualify; anything
 * with pipes, substitutions or placeholders returns undefined (prose stays prose).
 */
export function argvFromCommand(command: string): string[] | undefined {
  const s = command.trim().replace(/^`|`$/g, '');
  if (!s.startsWith('gbrain ') && s !== 'gbrain') return undefined;
  const out: string[] = [];
  const re = /\s*(?:'([^']*)'|([^\s'"`$|;&<>()\\]+))/y;
  let i = 0;
  while (i < s.length) {
    re.lastIndex = i;
    const m = re.exec(s);
    if (!m) return undefined;
    out.push(m[1] ?? m[2]);
    i = re.lastIndex;
    while (i < s.length && s[i] === ' ') i++;
  }
  return out.length ? out : undefined;
}

/** `no_pull: true` on MCP, `--no-pull` on the CLI. */
export function paramRef(ctx: { transport: Transport }, param: string): string {
  return ctx.transport === 'cli' ? `--${param.replace(/_/g, '-')}` : `${param}: true`;
}

// ── docs URLs ──────────────────────────────────────────────────────────────

const REPO_BLOB = 'https://github.com/garrytan/gbrain/blob';
let docsRefOverride: string | null = null;

/** Test seam: pin the ref docsUrl() uses (null restores detection). */
export function __setDocsRefForTests(ref: string | null): void { docsRefOverride = ref; }

function docsRef(): string {
  if (docsRefOverride !== null) return docsRefOverride;
  const root = join(import.meta.dir, '..', '..');
  return existsSync(join(root, '.git')) ? 'master' : `v${VERSION}`;
}

/**
 * Absolute docs URL for a repo-relative anchor (`docs/guides/x.md#y`).
 * Published package → the `v<VERSION>` tag; source checkout → `master`;
 * `LLMS_REPO_BASE` (fork override, same knob as build:llms) wins.
 */
export function docsUrl(anchor: string): string {
  if (/^https?:\/\//.test(anchor)) return anchor;
  const path = anchor.replace(/^\.?\//, '');
  const forkBase = parseRepoBase(process.env.LLMS_REPO_BASE);
  if (forkBase !== null && typeof forkBase !== 'string') warnInvalidRepoBase(forkBase.invalid);
  return typeof forkBase === 'string' ? `${forkBase}/${path}` : `${REPO_BLOB}/${docsRef()}/${path}`;
}

let warnedRepoBase: string | null = null;
/** W4.12: an invalid `LLMS_REPO_BASE` is ignored (default links), with one stderr line per value. */
function warnInvalidRepoBase(value: string): void {
  if (warnedRepoBase === value) return;
  warnedRepoBase = value;
  process.stderr.write('[gbrain] LLMS_REPO_BASE is not a plain https URL, so documentation links use the default repository. Unset it or set an https base.\n');
}

// ── next + rendering ───────────────────────────────────────────────────────

/** The published decision table (first matching row wins). */
export function deriveNext(a: Action, ctx: RenderContext): Next {
  if (a.ask_user) return 'ask_user';
  const callableMcp = a.mcp !== undefined && ctx.isCallable(a.mcp.tool);
  const mcpOnlyOnCli = ctx.transport === 'cli' && !a.argv?.length && a.mcp !== undefined && !callableMcp;
  if (!a.argv?.length && !callableMcp && !mcpOnlyOnCli) return 'report';
  if (a.actor === 'provider') return 'wait';
  if (a.actor === 'user' || a.actor === 'host_admin' || mcpOnlyOnCli) return 'tell_user_to_run';
  if (ctx.transport !== 'cli' && !callableMcp) return 'tell_user_to_run';
  if (a.consent.length > 0 && (a.consent.includes('destructive') || !ctx.preapproved(a.consent))) return 'ask_user';
  return 'run';
}

function renderVerify(v: Action['verify'], ctx: RenderContext): RenderedAction['verify'] {
  if (!v) return undefined;
  const mcp = v.mcp && ctx.isCallable(v.mcp.tool) ? v.mcp : undefined;
  if (!v.argv && !mcp) return undefined;
  return { ...(v.argv ? { argv: pinRouting(v.argv, ctx.routing, { remote: ctx.transport === 'http' }) } : {}), ...(mcp ? { mcp } : {}) };
}

/** Render an Action for the caller's surface. Key order is part of the v1 goldens. */
export function renderAction(a: Action, ctx: RenderContext): RenderedAction {
  const callable = a.mcp && ctx.isCallable(a.mcp.tool) ? a.mcp : undefined;
  const cliOnlyOnMcp = ctx.transport !== 'cli' && !callable && a.actor === 'agent' && !!a.argv?.length;
  // The mirror case: an MCP-only fix on the CLI (a remote server's fix on a thin client) is kept as
  // relay data, not dropped: the user (or their MCP client) calls the tool; the CLI cannot.
  const relay = ctx.transport === 'cli' && !callable && !a.argv?.length && a.mcp ? a.mcp : undefined;
  const mcp = callable ?? relay;
  const actor: Actor = cliOnlyOnMcp ? (ctx.transport === 'http' ? 'host_admin' : 'user') : relay && a.actor === 'agent' ? 'user' : a.actor;
  const effective: Action = { ...a, mcp, actor };
  const userMessage = a.user_message ?? (relay ? `Call the ${relay.tool} tool over MCP with ${JSON.stringify(relay.arguments)}; this command line cannot call it.` : undefined);
  const verify = renderVerify(a.verify, ctx);
  const remote = { remote: ctx.transport === 'http' };
  const argv = a.argv ? pinRouting(a.argv, ctx.routing, remote) : undefined;
  const out: RenderedAction = {
    ...(argv ? { argv, command: shellQuote(argv) } : {}),
    ...(mcp ? { mcp } : {}),
    consent: a.consent,
    actor,
    next: deriveNext(effective, ctx),
    why: inertText(a.why),
    ...(userMessage !== undefined ? { user_message: inertText(userMessage) } : {}),
    ...(verify ? { verify } : {}),
    ...(a.docs ? { docs: docsUrl(a.docs) } : {}),
    requires_exclusive: a.requires_exclusive,
    ...(a.inputs?.length ? { inputs: a.inputs } : {}),
    ...(a.plan_hash ? { plan_hash: a.plan_hash } : {}),
    ...(a.preview_argv ? { preview_argv: pinRouting(a.preview_argv, ctx.routing, remote) } : {}),
    ...(a.then ? { then: renderAction(a.then, ctx) } : {}),
  };
  return out;
}

export function renderNotice(n: Notice, ctx: RenderContext): RenderedNotice {
  return {
    code: n.code,
    kind: n.kind,
    why: inertText(n.why),
    ...(n.fix ? { fix: renderAction(n.fix, ctx) } : {}),
    ...(n.user_message !== undefined ? { user_message: inertText(n.user_message) } : {}),
    ...(n.decisions?.length ? { decisions: n.decisions } : {}),
    contract_version: CONTRACT_VERSION,
  };
}

export const NOTICE_PREFIX = '[gbrain notice ';
const NOTICE_KIND_ORDER: readonly NoticeKind[] = ['safety', 'degraded', 'ask', 'coaching', 'info'];

/** Stable order for notice blocks: safety, degraded, ask, coaching, info. */
export function orderNotices<T extends { kind: NoticeKind }>(notices: readonly T[]): T[] {
  return [...notices].sort((a, b) => NOTICE_KIND_ORDER.indexOf(a.kind) - NOTICE_KIND_ORDER.indexOf(b.kind));
}

function renderedStep(fix: RenderedAction): string | undefined {
  if (fix.mcp) return `${fix.mcp.tool} ${JSON.stringify(fix.mcp.arguments)}`;
  return fix.command;
}

/** The MCP extra text block for one notice. First line is the fixed prefix clients key on. */
export function noticeBlock(n: RenderedNotice): string {
  const lines = [`${NOTICE_PREFIX}${n.code} kind=${n.kind}]`, `why: ${n.why}`];
  if (n.fix) {
    const step = renderedStep(n.fix);
    if (step) lines.push(`fix: ${step}`);
    lines.push(`next: ${n.fix.next}`);
  }
  if (n.user_message) lines.push(`user_message: ${n.user_message}`);
  for (const d of n.decisions ?? []) {
    lines.push(`decision ${d.id}: ${inertText(d.question)} (default: ${d.default})`);
  }
  return lines.join('\n');
}

// ── HTTP view ──────────────────────────────────────────────────────────────

const HTTP_DROP_KEYS = new Set(['pid', 'lock_owner', 'path', 'data_dir', 'database_path', 'asset']);
const ABS_PATH_RE = /(?:^|(?<=[\s'"`(=]))(?:\/(?:home|Users|root|tmp|var|private|opt|srv|mnt|etc)\/[^\s'"`)]*|[A-Za-z]:\\[^\s'"`)]*|~\/[^\s'"`)]*)/g;
const PID_RE = /\b(PID|pid)\s*[:=]?\s*\d+/g;
const KEY_NAME_RE = /\b[A-Z][A-Z0-9]*_(?:API_KEY|TOKEN|SECRET)\b/g;

function redactString(s: string): string {
  return s.replace(ABS_PATH_RE, '<path>').replace(PID_RE, '$1 <redacted>').replace(KEY_NAME_RE, '<provider key>');
}

/** One transport-keyed redaction pass: http strips local paths, PIDs, key names and host posture keys. */
export function redactForTransport<T>(value: T, transport: Transport): T {
  if (transport !== 'http') return value;
  const walk = (v: unknown): unknown => {
    if (typeof v === 'string') return redactString(v);
    if (Array.isArray(v)) return v.map(walk);
    if (v && typeof v === 'object') {
      const out: Record<string, unknown> = {};
      for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
        if (HTTP_DROP_KEYS.has(k)) continue;
        out[k] = walk(val);
      }
      return out;
    }
    return v;
  };
  return walk(value) as T;
}

// ── envelope ───────────────────────────────────────────────────────────────

/** Fields a normaliser row extracts before the shared envelope assembly. */
export interface EnvelopeParts {
  error: string;
  code: string;
  message: string;
  suggestion?: string;
  reason?: string;
  why?: string;
  fix?: Action;
  docs?: string;
  notices?: Notice[];
  detail?: string;
  protocol_version?: 1;
  write_request?: unknown;
  write_error?: string;
  retryable?: boolean;
  fence?: Record<string, unknown>;
  fence_issues?: Array<Record<string, unknown>>;
  withdrawn?: WithdrawnDetail;
  writable_source_ids?: string[];
}

/** Replace each occurrence of `bare` that is a whole command (not followed by a word, path or more flags). */
function replaceWholeCommand(text: string, bare: string, step: string): string {
  let out = '';
  let from = 0;
  for (let at = text.indexOf(bare); at >= 0; at = text.indexOf(bare, at + bare.length)) {
    const rest = text.slice(at + bare.length);
    if (/^[\w/-]/.test(rest) || /^\s+-/.test(rest)) continue;
    out += text.slice(from, at) + step;
    from = at + bare.length;
  }
  return from === 0 ? text : out + text.slice(from);
}

function appendFixToSuggestion(suggestion: string, fix: RenderedAction | undefined, unpinned?: readonly string[]): string {
  if (!fix) return suggestion;
  const step = renderedStep(fix);
  if (!step || suggestion.includes(step)) return suggestion;
  // Prose that already quotes the fix before its A1 routing pin quotes the pinned command instead (never both).
  const bare = unpinned?.length && !fix.mcp ? shellQuote(unpinned) : undefined;
  if (bare && bare !== step) {
    const replaced = replaceWholeCommand(suggestion, bare, step);
    if (replaced !== suggestion) return replaced;
  }
  const prose = suggestion.trim();
  return prose ? `${prose.replace(/[.\s]*$/, '.')} Next: ${step}` : `Next: ${step}`;
}

/** Assemble the envelope from normalised parts. Legacy keys first, in their historical order. */
export function buildEnvelope(p: EnvelopeParts, ctx: RenderContext): AgentEnvelope {
  const entry = codeEntry(p.code);
  const fix = p.fix ? renderAction(p.fix, ctx) : undefined;
  const suggestion = appendFixToSuggestion(p.suggestion ?? entry?.suggestion ?? '', fix, p.fix?.argv);
  const docs = p.docs ?? entry?.docs ?? `docs/guides/error-codes.md#${p.code}`;
  const notices = p.notices?.length ? orderNotices(p.notices).map(n => renderNotice(n, ctx)) : undefined;
  return {
    error: p.error,
    code: p.code,
    message: p.message,
    suggestion,
    docs: docsUrl(docs),
    ...(p.detail !== undefined ? { detail: p.detail } : {}),
    ...(p.protocol_version !== undefined ? { protocol_version: p.protocol_version } : {}),
    ...(p.write_request !== undefined ? { write_request: p.write_request } : {}),
    ...(p.write_error !== undefined ? { write_error: p.write_error } : {}),
    ...(p.fence !== undefined ? { fence: p.fence } : {}),
    ...(p.fence_issues?.length ? { fence_issues: p.fence_issues } : {}),
    ...(p.withdrawn !== undefined ? { withdrawn: p.withdrawn } : {}),
    ...(p.writable_source_ids !== undefined ? { writable_source_ids: p.writable_source_ids } : {}),
    ...(p.reason !== undefined ? { reason: p.reason } : {}),
    ...(p.why !== undefined ? { why: p.why } : {}),
    ...(fix ? { fix } : {}),
    docs_cmd: ['gbrain', 'errors', p.code],
    class: codeClass(p.code, p.reason),
    retryable: p.retryable ?? codeRetryable(p.code, p.reason),
    ...(notices ? { notices } : {}),
    contract_version: CONTRACT_VERSION,
  };
}

const VERB_SET: ReadonlySet<string> = new Set(VERB_NAMES);
const isVerbOp = (ctx: AgentErrorContext) => ctx.op !== undefined && VERB_SET.has(ctx.op);

/** The registry's diagnostic default: doctor on the brain host (MCP run_doctor where callable). */
function diagnosticFix(ctx: AgentErrorContext, why: string): Action {
  const remoteHost = ctx.transport === 'http';
  return {
    argv: ['gbrain', 'doctor', '--json'],
    ...(ctx.render.isCallable('run_doctor') ? { mcp: { tool: 'run_doctor', arguments: {} } } : {}),
    consent: [],
    actor: remoteHost ? 'host_admin' : 'agent',
    why,
    requires_exclusive: false,
  };
}

/** The journal fields a receipt-bearing error carries (OperationError.receiptFields), never serialized. */
type ReceiptFields = NonNullable<OperationError['receiptFields']>;

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const TEMPLATE_VALUE: Record<string, RegExp> = {
  slug: /^[A-Za-z0-9][A-Za-z0-9._/:@-]{0,511}$/,
  source_id: /^[a-z0-9][a-z0-9_-]{0,63}$/i,
  request_id: UUID_RE,
  operation: /^[a-z][a-z0-9_]{0,63}$/,
};

/**
 * Fill a registry fix template (`{slug}`, `{source_id}`, `{request_id}`,
 * `{operation}`) from envelope/receipt fields. Every value must pass its strict
 * id pattern; one missing or unsafe value drops the whole template (B4, A1
 * argv safety), so no placeholder ever reaches the wire.
 */
export function fillFixTemplate(template: Action, fields: Record<string, string | null | undefined>): Action | undefined {
  let ok = true;
  const fill = (v: string): string => v.replace(/\{([a-z_]+)\}/g, (_m, key: string) => {
    const value = fields[key];
    if (typeof value !== 'string' || !TEMPLATE_VALUE[key]?.test(value)) { ok = false; return ''; }
    return value;
  });
  const args = (a: Record<string, unknown>) => Object.fromEntries(Object.entries(a).map(([k, v]) => [k, typeof v === 'string' ? fill(v) : v]));
  const filled: Action = {
    ...template,
    ...(template.argv ? { argv: template.argv.map(fill) } : {}),
    ...(template.mcp ? { mcp: { tool: template.mcp.tool, arguments: args(template.mcp.arguments) } } : {}),
  };
  return ok ? filled : undefined;
}

/** The registry default fix for a code, filled from the fields this error carries (undefined when it has none or cannot be filled). */
function registryTemplateFix(code: string, fields: Record<string, string | null | undefined> | undefined): Action | undefined {
  const template = codeEntry(code)?.fix;
  if (!template || !fields) return undefined;
  return fillFixTemplate(template, fields);
}

const RECEIPT_CHANNEL: Record<Transport, string> = { cli: 'local_cli', stdio: 'local_stdio', http: '' };

/**
 * A1 safe-recovery invariant, principal-aware: a write with an unknown or
 * pending outcome, or a replayed terminal receipt, is never told to retry. The
 * fix reads the receipt on the channel that owns it: `gbrain write-request` on
 * the CLI for a CLI-principal receipt, `get_write_request` over MCP where it is
 * callable for this principal; another principal's receipt (or no callable
 * receipt tool) gets the separately authorized host inspection, actor
 * host_admin. No receipt → no receipt command.
 */
function recoveryFix(p: EnvelopeParts, ctx: AgentErrorContext, fields?: ReceiptFields): Action | undefined {
  const outcomeOpen = ctx.outcome === 'unknown' || ctx.outcome === 'pending';
  if (!fields && (!ctx.mutating || !outcomeOpen)) return undefined;
  const receipt = p.write_request as { request_id?: unknown; state?: unknown } | undefined;
  const requestId = typeof receipt?.request_id === 'string' && UUID_RE.test(receipt.request_id) ? receipt.request_id : undefined;
  if (!requestId) return undefined;
  const terminal = typeof receipt?.state === 'string' && ['committed', 'conflict', 'failed', 'cancelled'].includes(receipt.state);
  const why = terminal
    ? 'The receipt is final; read it (and the target) before deciding whether a new write is needed.'
    : 'The write may still commit; its receipt says whether it did. Do not resubmit until the receipt is terminal.';
  const owner = fields?.principal_kind;
  const samePrincipal = owner !== 'oauth_client' || !ctx.render.principal || fields?.principal_id === ctx.render.principal;
  const ownChannel = owner === undefined || samePrincipal && (ctx.transport === 'http' ? !owner.startsWith('local_') : owner === RECEIPT_CHANNEL[ctx.transport]);
  if (ownChannel && ctx.transport === 'cli') {
    return { argv: ['gbrain', 'write-request', '--', requestId], consent: [], actor: 'agent', why, requires_exclusive: false };
  }
  if (ownChannel && ctx.render.isCallable('get_write_request')) {
    return { mcp: { tool: 'get_write_request', arguments: { request_id: requestId } }, consent: [], actor: 'agent', why, requires_exclusive: false };
  }
  const source = fields && TEMPLATE_VALUE.source_id!.test(fields.source_id) ? [fields.source_id] : [];
  return {
    argv: ['gbrain', 'sources', 'writer', 'status', ...source, '--probe', '--json'],
    consent: [], actor: 'host_admin',
    why: `${why} This connection cannot read that receipt itself, so the brain host's operator inspects the write on the owner.`,
    user_message: 'A write gbrain accepted needs a check on the brain host before anything is resubmitted. Please ask whoever runs this brain to run the command shown.',
    requires_exclusive: false,
  };
}

const REFRESH_REFUSALS: ReadonlySet<string> = new Set([
  'refresh_not_managed', 'refresh_not_owner', 'refresh_no_upstream', 'fetch_failed', 'refresh_diverged', 'refresh_dirty',
  'sync_in_progress', 'refresh_in_progress', 'refresh_drain_timeout', 'refresh_lock_timeout', 'refresh_source_changed', 'refresh_recovery_required',
  'worktree_refreshing',
]);

type Row = { match: (e: unknown) => boolean; map: (e: any, ctx: AgentErrorContext) => EnvelopeParts };

/** RemoteMcpError transport reasons (no server envelope) → registry codes. */
const REMOTE_REASON_CODE: Record<string, string> = {
  config: 'config_error', discovery: 'unavailable', auth: 'invalid_token', auth_after_refresh: 'invalid_token',
  rate_limited: 'rate_limited', token: 'unavailable',
  'network:timeout': 'timeout', 'network:aborted': 'interrupted', parse: 'internal_error',
};

const named = (name: string) => (e: unknown) => e instanceof Error && e.name === name;

/** The normaliser table: first matching row wins; the last row is the unknown-throw fallback. */
const ROWS: Row[] = [
  {
    match: e => e instanceof OperationError,
    map: (e: OperationError, ctx) => {
      const j = e.toJSON() as Record<string, unknown>;
      const receiptId = (j.write_request as { request_id?: string } | undefined)?.request_id;
      let fix = e.fix ?? registryTemplateFix(e.canonicalCode, e.receiptFields ? { ...e.receiptFields, request_id: receiptId } : undefined);
      if (!fix && REFRESH_REFUSALS.has(e.code) && e.suggestion) {
        const argv = argvFromCommand(e.suggestion);
        if (argv) fix = { argv, consent: [], actor: 'agent', why: e.message, requires_exclusive: false };
      }
      return {
        error: e.code, code: canonicalCodeFor(e.canonicalCode), message: e.message, suggestion: e.suggestion,
        reason: e.reason, why: e.why, fix, docs: e.docs, notices: e.notices, detail: e.detail,
        protocol_version: e.protocolVersion === 1 ? 1 : undefined,
        write_request: j.write_request, write_error: e.writeError,
        ...(e.fence ? { fence: e.fence } : {}), ...(e.fenceIssues?.length ? { fence_issues: e.fenceIssues } : {}),
        ...(e.withdrawn ? { withdrawn: e.withdrawn } : {}),
        ...(e.writableSourceIds ? { writable_source_ids: e.writableSourceIds } : {}),
        ...(e.retryable !== undefined ? { retryable: e.retryable } : {}),
      };
    },
  },
  {
    match: e => e instanceof StructuredAgentError,
    map: (e: StructuredAgentError) => ({
      error: e.envelope.code, code: canonicalCodeFor(e.envelope.code), message: e.envelope.message,
      suggestion: e.envelope.hint, docs: e.envelope.docs_url,
    }),
  },
  {
    match: isReadOnlyTransactionError,
    map: (e: Error) => ({ error: 'connection_inherited_read_only', code: 'connection_inherited_read_only', message: e.message,
      fix: registryTemplateFix('connection_inherited_read_only', {}) }),
  },
  {
    match: e => e instanceof Error && (e as { tag?: unknown }).tag === 'BUDGET_EXHAUSTED',
    map: (e: Error & { reason: string; cap: number; pricing?: { model: string; units: string[]; lookup: string; register_command: string } }, ctx) => {
      if (e.reason !== 'no_pricing' || !e.pricing) {
        return { error: 'cost_cap_exceeded', code: 'cost_cap_exceeded', message: e.message, reason: e.reason };
      }
      const argv = argvFromPricing(e.pricing.register_command);
      return {
        error: 'no_pricing', code: 'no_pricing', message: e.message, reason: 'no_pricing',
        suggestion: e.pricing.lookup,
        fix: argv ? {
          argv, consent: [], actor: ctx.transport === 'cli' ? 'agent' : 'host_admin',
          why: 'A cost cap needs a price for every model it covers; registering the rate lets the cap be enforced.',
          requires_exclusive: false,
          inputs: e.pricing.units.map(u => ({ name: u, how: e.pricing!.lookup })),
        } : undefined,
      };
    },
  },
  {
    match: named('RemoteMcpError'),
    map: (e: Error & { reason: string; detail?: Record<string, unknown> }) => {
      const d = e.detail ?? {};
      const wire = typeof d.code === 'string' ? d.code : REMOTE_REASON_CODE[e.reason === 'network' ? `network:${String(d.kind)}` : e.reason] ?? 'unavailable';
      const remoteCode = typeof d.canonical_code === 'string' ? d.canonical_code : canonicalCodeFor(wire);
      return {
        error: wire, code: remoteCode, message: typeof d.message === 'string' ? d.message : e.message,
        suggestion: typeof d.suggestion === 'string' ? d.suggestion : undefined,
        reason: typeof d.reason === 'string' ? d.reason : undefined,
        why: typeof d.why === 'string' ? d.why : undefined,
        docs: typeof d.docs === 'string' ? d.docs : undefined,
        detail: typeof d.server_detail === 'string' ? d.server_detail : undefined,
        protocol_version: d.protocol_version === 1 ? 1 : undefined,
        write_request: d.write_request, write_error: typeof d.write_error === 'string' ? d.write_error : undefined,
        notices: Array.isArray(d.notices) ? d.notices as Notice[] : undefined,
        fix: d.fix && typeof d.fix === 'object' ? d.fix as Action
          : e.reason !== 'tool_error' ? { argv: ['gbrain', 'remote', 'doctor'], consent: [], actor: 'agent', requires_exclusive: false,
            why: 'remote doctor checks the remote brain URL, OAuth discovery and credentials from this machine.' } : undefined,
      };
    },
  },
  {
    // The local persistence owner's IPC lane: unreachable (not sent) or the acknowledgment was lost (outcome unknown).
    match: named('PersistenceIpcTransportError'),
    map: (e: Error & { sent: boolean; requestId?: string; toJSON(): { suggestion: string } }) => {
      const requestId = e.requestId && UUID_RE.test(e.requestId) ? e.requestId : undefined;
      return {
        error: 'owner_unavailable', code: 'owner_unavailable', message: e.message, suggestion: e.toJSON().suggestion,
        ...(e.sent ? { reason: 'outcome_unknown', retryable: false } : { reason: 'not_sent' }),
        fix: e.sent && requestId
          ? { argv: ['gbrain', 'write-request', '--', requestId], consent: [], actor: 'agent', requires_exclusive: false,
            why: 'The write may have committed before the acknowledgment was lost; its receipt says whether it did. Do not resubmit until it is terminal.' }
          : { argv: ['gbrain', 'sources', 'writer', 'status', '--probe', '--json'], consent: [], actor: 'agent', requires_exclusive: false,
            why: 'Shows whether the brain\'s persistence owner is running and reachable before anything is repeated.' },
      };
    },
  },
  {
    // Before any PageRevisionConflictError handling: same canonical revision, a newer projection installed by another worker.
    match: named('PageProjectionConflictError'),
    map: (e: Error & { changed: readonly string[]; slug: string; sourceId: string }, ctx) => ({
      error: 'page_projection_conflict', code: 'page_projection_conflict', message: e.message,
      detail: `changed: ${e.changed.join(', ')}`,
      why: `Another worker (the persistence owner's projection rebuild, an embed or an import) installed a newer search projection of ${e.slug} while this command prepared its own; the guard keeps that newer installation instead of overwriting it.`,
      suggestion: `Re-run ${ctx.command ? `gbrain ${ctx.command}` : 'the same command'}; it re-reads the current projection. If it conflicts again, another worker is still installing: wait for it to finish, then re-run.`,
      fix: { argv: ['gbrain', 'get', '--source', e.sourceId, '--', e.slug], consent: [], actor: 'agent', requires_exclusive: false,
        why: 'Reads the page as stored now (read-only) before the command is re-run.' },
    }),
  },
  {
    match: named('EmbeddingDisabledError'),
    map: (e: Error & { fix?: Action }) => ({
      error: 'embedding_disabled', code: 'embedding_disabled', reason: 'disabled_by_choice',
      message: e.message.split('\n')[0]!, why: e.fix?.why, fix: e.fix,
      suggestion: 'Embeddings are off by choice on this brain; keyword search still works. Turning them on needs the user\'s consent.',
    }),
  },
  {
    match: named('CredentialError'),
    map: (e: Error & { code: string; problem: string; cause_text: string; fix: string; doc_url: string }) => ({
      error: e.code, code: e.code, message: e.problem, why: e.cause_text, suggestion: e.fix, docs: e.doc_url,
    }),
  },
  {
    // source-resolver: a caller-selected source (--source, GBRAIN_SOURCE) that is malformed, unregistered or archived.
    match: named('SourceTargetError'),
    map: (e: Error) => {
      const code = e.message.startsWith('Invalid ') ? 'invalid_source' : 'unknown_source';
      return {
        error: code, code, message: e.message,
        suggestion: 'Pass a registered, active source id with --source or GBRAIN_SOURCE (or unset it for the default source); `gbrain sources list --json` shows them.',
        fix: {
          argv: ['gbrain', 'sources', 'list', '--json'], mcp: { tool: 'sources_list', arguments: {} }, consent: [], actor: 'agent', requires_exclusive: false,
          why: 'Lists the source ids this brain has, so the next call can name one that exists.',
        },
      };
    },
  },
  {
    // embed preflight: no usable embedding credentials (userMessage is the paste-ready diagnosis).
    match: named('EmbeddingCredentialError'),
    map: (e: Error & { userMessage?: string }) => {
      const [first, ...rest] = (e.userMessage ?? e.message).split('\n').filter(l => l.trim());
      return { error: 'unavailable', code: 'unavailable', reason: 'embedding_credentials', message: first ?? e.message,
        suggestion: rest.join(' ').trim() || 'Configure an embedding provider key, then retry.' };
    },
  },
  {
    match: named('EmbeddingDimMismatchError'),
    map: (e: Error & { recipeMessage?: string }) => {
      const [first, ...rest] = (e.recipeMessage ?? e.message).split('\n').filter(l => l.trim());
      return { error: 'embedding_width_mismatch', code: 'embedding_width_mismatch', message: first ?? e.message,
        suggestion: rest.join(' ').trim() || 'Run `gbrain doctor --json` to see the brain\'s vector width.' };
    },
  },
  // ── generic rows: the DB classifier runs before these ──
  {
    match: e => named('AIConfigError')(e) || named('AITransientError')(e),
    map: (e: Error & { fix?: string }) => ({
      error: 'unavailable', code: 'unavailable', message: e.message,
      reason: e.name === 'AIConfigError' ? 'ai_config' : 'ai_transient',
      suggestion: e.fix, retryable: e.name === 'AITransientError',
    }),
  },
  {
    match: named('GBrainError'),
    map: (e: Error & { problem: string; cause_description: string; fix: string; docs_url?: string }) => ({
      error: 'config_error', code: 'config_error', message: e.problem,
      why: e.cause_description || undefined, suggestion: e.fix, docs: e.docs_url,
    }),
  },
  {
    match: e => !(e instanceof Error) && !!e && typeof e === 'object'
      && typeof (e as Record<string, unknown>).code === 'string' && typeof (e as Record<string, unknown>).message === 'string'
      && typeof (e as Record<string, unknown>).class === 'string',
    map: (e: { class: string; code: string; message: string; hint?: string }) => ({
      error: e.code, code: canonicalCodeFor(e.code), message: e.message, suggestion: e.hint,
    }),
  },
];

/**
 * A1 safe recovery for non-journaled mutations: when the outcome is unknown
 * (no receipt, a failure that may have struck after the work was accepted),
 * the fix is the op's own status read, never a resubmit.
 */
const STATUS_READ: Readonly<Record<string, Action>> = {
  submit_job: {
    argv: ['gbrain', 'jobs', 'list', '--json'], mcp: { tool: 'list_jobs', arguments: {} }, consent: [], actor: 'agent', requires_exclusive: false,
    why: 'The job may have been queued before the failure; the job list shows whether it was before anything is resubmitted.',
  },
};
const OUTCOME_UNKNOWN_CLASSES: ReadonlySet<ErrorClass> = new Set(['server', 'unavailable', 'retryable']);

function statusReadFix(ctx: AgentErrorContext): Action | undefined {
  const open = ctx.outcome === 'unknown' || ctx.outcome === 'pending';
  return ctx.op && ctx.mutating && open ? STATUS_READ[ctx.op] : undefined;
}

/** Index of the first generic row (AIConfigError); rows before it are typed and beat the DB classifier. */
const FIRST_GENERIC_ROW = ROWS.findIndex(r => r.match(Object.assign(new Error('x'), { name: 'AIConfigError' })));

function argvFromPricing(command: string): string[] | undefined {
  const s = command.replace(/<([a-z0-9-]+)>/gi, 'PLACEHOLDER_$1');
  const argv = argvFromCommand(s);
  return argv?.map(a => a.replace(/^PLACEHOLDER_(.+)$/, '<$1>'));
}

function dbParts(e: unknown, ctx: AgentErrorContext): EnvelopeParts | undefined {
  const d = classifyPgAccessError(e, { url: ctx.db?.url ?? null, brainId: ctx.db?.brainId });
  if (d.reason === 'unknown') return undefined;
  const verb = isVerbOp(ctx);
  if (d.reason === 'schema_missing') {
    return {
      error: 'unavailable', code: 'unavailable', reason: 'schema_missing', message: d.message,
      suggestion: 'Run gbrain apply-migrations on the brain host, then retry.',
      fix: {
        argv: ['gbrain', 'apply-migrations', '--yes'], consent: [], actor: 'agent',
        why: 'The code expects a table or column this brain does not have yet.', requires_exclusive: true,
        verify: { argv: ['gbrain', 'doctor', '--json'] },
      },
      ...(verb ? { detail: 'schema_missing', protocol_version: 1 as const } : {}),
    };
  }
  return {
    error: verb ? 'unavailable' : 'database_error', code: verb ? 'unavailable' : 'database_error', reason: d.reason,
    message: d.message, suggestion: `${formatDbAccessMarker(d)}. ${d.remediation} Run: gbrain db-repair`,
    fix: {
      argv: ['gbrain', 'db-repair'], consent: [], actor: 'agent',
      why: 'db-repair diagnoses the database connection without changing anything.', requires_exclusive: false,
    },
    ...(verb ? { detail: d.reason, protocol_version: 1 as const } : {}),
  };
}

function unknownParts(e: unknown, ctx: AgentErrorContext): EnvelopeParts {
  const raw = e instanceof Error ? e.message : String(e);
  let message = raw;
  try { message = redactUrlsInText(redactConnectionInfo(raw)); } catch { /* keep raw */ }
  const where = ctx.op ?? ctx.command ?? 'this operation';
  const verb = isVerbOp(ctx);
  const resubmit = ctx.mutating ? ' The write may have partly run: inspect state before resubmitting.' : '';
  return {
    error: verb ? 'internal' : 'internal_error', code: verb ? 'internal' : 'internal_error',
    message: redactForTransport(message, ctx.transport),
    suggestion: `Server-side failure in ${where}, not a caller mistake.${resubmit} Run \`gbrain doctor --json\` on the brain host; if it repeats, report it to the user.`,
    fix: statusReadFix(ctx) ?? diagnosticFix(ctx, 'Doctor checks the brain host for the failing dependency.'),
    ...(verb ? { protocol_version: 1 as const } : {}),
  };
}

function genericEnvelope(e: unknown, ctx: AgentErrorContext): AgentEnvelope {
  let message = 'unclassified failure';
  try { message = e instanceof Error ? e.message : String(e); } catch { /* hostile value: keep the placeholder */ }
  const where = ctx.op ?? ctx.command ?? 'this operation';
  return {
    error: 'internal_error', code: 'internal_error', message: redactUrlsInText(redactConnectionInfo(redactForTransport(message, ctx.transport))),
    suggestion: `Server-side failure in ${where}, not a caller mistake. Run \`gbrain doctor --json\` on the brain host; if it repeats, report it to the user.`,
    docs_cmd: ['gbrain', 'errors', 'internal_error'], class: 'server', retryable: false, contract_version: CONTRACT_VERSION,
  };
}

/** Total: never throws; on an internal fault returns the prior generic envelope and logs the class (E11). */
export function toAgentError(e: unknown, ctx: AgentErrorContext): AgentEnvelope {
  try {
    // Typed rows first (OperationError … CredentialError); then the DB-access
    // classifier, which must win over the generic GBrainError/AI/phase rows
    // (a connect failure is often a GBrainError); then the unknown fallback.
    const row = ROWS.find(r => r.match(e));
    const typed = row && ROWS.indexOf(row) < FIRST_GENERIC_ROW;
    let parts = typed ? row.map(e, ctx) : dbParts(e, ctx) ?? (row ? row.map(e, ctx) : unknownParts(e, ctx));
    if (!parts.fix) {
      const recovery = recoveryFix(parts, ctx, e instanceof OperationError ? e.receiptFields : undefined);
      if (recovery) parts = { ...parts, fix: recovery };
    }
    if (!parts.fix && OUTCOME_UNKNOWN_CLASSES.has(codeClass(parts.code))) {
      const status = statusReadFix(ctx);
      if (status) parts = { ...parts, fix: status };
    }
    if (!parts.fix && (codeClass(parts.code) === 'server' || codeClass(parts.code) === 'unavailable')) {
      parts = { ...parts, fix: diagnosticFix(ctx, 'Doctor reports what is missing or failing on the brain host.') };
    }
    if (ctx.mutating === true && ctx.idempotent !== true && !provesNotAdmitted(e)) parts = { ...parts, retryable: false };
    const env = buildEnvelope(parts, ctx.render);
    if (env.code === 'internal_error' || env.code === 'internal' || !env.suggestion) {
      recordAgentContractEvent({ transport: ctx.transport, op: ctx.op, command: ctx.command, code: env.code, has_suggestion: !!env.suggestion, outcome: ctx.outcome });
    }
    return ctx.transport === 'http' ? redactForTransport(env, 'http') : env;
  } catch (fault) {
    recordAgentContractEvent({
      transport: ctx.transport, op: ctx.op, command: ctx.command, code: 'internal_error',
      fault: fault instanceof Error ? fault.name : typeof fault,
    });
    return genericEnvelope(e, ctx);
  }
}

/** A batch command's one-line failure for a projection conflict that outlasted its retries: code, message and next step. */
export function projectionConflictLine(e: unknown, command: string): string | null {
  if (!named('PageProjectionConflictError')(e)) return null;
  const env = toAgentError(e, { transport: 'cli', command, render: cliRenderContext() });
  return `[${env.code}] ${env.message} ${env.suggestion}`;
}

/** Pure: callers write the strings. TTY order: `Error [code]: msg` / `Fix:` / `Why:` / `Docs:`. */
export function renderCliError(e: unknown, opts: { json: boolean; command: string; tty: boolean }): CliErrorRender {
  const env = toAgentError(e, { transport: 'cli', command: opts.command, render: cliRenderContext() });
  const exitCode = exitCodeForCode(env.code, env.reason);
  if (opts.json) return { stdout: `${JSON.stringify(env, null, 2)}\n`, exitCode };
  const lines = [`Error [${env.code}]: ${env.message}`];
  const relay = env.fix && !env.fix.command && env.fix.mcp ? `call ${env.fix.mcp.tool} over MCP with ${JSON.stringify(env.fix.mcp.arguments)}` : undefined;
  lines.push(`Fix: ${env.fix?.command ?? relay ?? env.suggestion}`);
  if (env.why) lines.push(`Why: ${env.why}`);
  if (env.docs) lines.push(`Docs: ${env.docs}`);
  // GST-1582: a retryable refusal that names its delay ends with one line saying so, which survives `| tail -1`.
  const retryAfter = env.retryable === true ? Number(/^retry_after_ms=(\d+)$/.exec(String(env.detail ?? ''))?.[1]) : NaN;
  if (retryAfter > 0) lines.push(`Nothing was saved; retry the same command in about ${Math.max(1, Math.round(retryAfter / 1000))} s (retry_after_ms=${retryAfter}).`);
  return { stderr: `${lines.join('\n')}\n`, exitCode };
}

// ── wire builders shared by dispatch, the CLI and the goldens ──────────────

export interface ToolResultShape {
  content: { type: 'text'; text: string }[];
  isError?: boolean;
  _meta?: Record<string, unknown>;
}

/**
 * MCP success result: `content[0]` is the pre-v1 body (bare arrays included)
 * as compact JSON (C2: every result is re-sent on each later turn; error
 * envelopes stay indented); each notice is one extra prefixed text block,
 * mirrored rendered under `_meta.gbrain_notices`.
 */
export function toolResultWithNotices(result: unknown, notices: readonly Notice[], ctx: RenderContext): ToolResultShape {
  const out: ToolResultShape = { content: [{ type: 'text', text: JSON.stringify(result) }] };
  if (notices.length === 0) return out;
  const rendered = orderNotices(notices).map(n => redactForTransport(renderNotice(n, ctx), ctx.transport));
  for (const n of rendered) out.content.push({ type: 'text', text: noticeBlock(n) });
  out._meta = { gbrain_notices: rendered };
  return out;
}

/** MCP error result: exactly one content block holding the envelope. */
export function toolErrorResult(envelope: AgentEnvelope): ToolResultShape {
  return { content: [{ type: 'text', text: JSON.stringify(envelope, null, 2) }], isError: true };
}

/**
 * Legacy nested error shapes (`{ error: { class, code, message, hint } }`
 * from code-def/code-refs, phase containment) keep their nesting and gain the
 * v1 sibling keys.
 */
export function withAgentSiblings<T extends Record<string, unknown>>(
  legacy: T,
  parts: { code: string; fix?: Action },
  ctx: RenderContext,
): T & { code: string; fix?: RenderedAction; docs_cmd: string[]; contract_version: 1 } {
  return {
    ...legacy,
    code: parts.code,
    ...(parts.fix ? { fix: renderAction(parts.fix, ctx) } : {}),
    docs_cmd: ['gbrain', 'errors', parts.code],
    contract_version: CONTRACT_VERSION,
  };
}

/**
 * `{ error: StructuredError }` (code-def/code-refs/brainstorm `--json`) with
 * the v1 siblings: canonical `code`, an optional diagnostic `fix`, docs_cmd.
 */
export function legacyNestedErrorDocument(envelope: { code: string }, fixArgv?: string[]): Record<string, unknown> {
  return withAgentSiblings({ error: envelope }, {
    code: canonicalCodeFor(envelope.code),
    ...(fixArgv ? { fix: { argv: fixArgv, consent: [], actor: 'agent' as const, why: 'Shows the arguments this command needs.', requires_exclusive: false } } : {}),
  }, cliRenderContext());
}

/** The `--json` exit-time fallback document: a non-zero exit that wrote no final document. */
export function fallbackJsonDocument(exitCode: number, lastCode?: string): Record<string, unknown> {
  return {
    error: 'command_failed',
    code: lastCode ?? 'command_failed',
    message: `The command exited with status ${exitCode} without writing its JSON result.`,
    suggestion: 'Re-run without --json to read the error on stderr, or run `gbrain doctor --json`.',
    exit_code: exitCode,
    contract_version: CONTRACT_VERSION,
  };
}

__registerOperationErrorRenderer({
  fix: a => renderAction(a, cliRenderContext()),
  notice: n => renderNotice(n, cliRenderContext()),
});