Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
37.5 KB
Raw Blame
/**
 * E5 — the truthful-catalog invariant (T13; plan E5 + D10 carve-out, ENG-21
 * recipe, FOV-4/6c, amendment 31).
 *
 * THE INVARIANT: the catalog is an API promise. For each token class:
 * tools/list, then probe every listed tool — NO probe may return a
 * LIST-LEVEL denial (publish-gate `config_key=...`, bound-client op-fence
 * `fence=op`, scope `insufficient_scope`, or an unknown-tool envelope for a
 * name the list itself advertised). `invalid_params` is an acceptable probe
 * outcome. Inversely: what the list hides stays uncallable — surface-hidden
 * and localOnly ops return the no-leak unknown-tool envelope; gate-hidden
 * ops hit the fail-closed `config_key=` backstop; bound-fence-hidden ops hit
 * `fence=op`. Argument-level fence denials (out-of-prefix slugs on a LISTED
 * write op) are legitimate and excluded (D10) — pinned below as carrying NO
 * list-level marker.
 *
 * PLACEMENT (why not test/e2e/): the test/e2e/ tree runs only under
 * scripts/run-e2e.sh on a Postgres-equipped host; this file needs no
 * DATABASE_URL, so it lives in the unit tree (picked up by `bun test` /
 * run-unit-shard.sh) and guards the invariant in CI without Postgres.
 *
 * WHAT RUNS WHERE (ENG-21 recipe, adapted to a no-Postgres host):
 *   (a) the legacy bearer HTTP transport runs FOR REAL — ONE
 *       startHttpTransport server over a real PGLiteEngine, reused across
 *       cells (per-request gate reads make config flips restart-free; the
 *       surface axis for this transport is startup-bound, so surface cells
 *       run on path (b)).
 *   (b) the OAuth serve-http path runs through the SAME SEAMS serve-http.ts
 *       composes — filterOpsForSurface + hasScope (with the FOV-4
 *       agentCallable carve-out) + opAllowedForBoundClient +
 *       disabledOpsForPublishGates for the list; the scope gate + the real
 *       dispatchToolCall (allowedOps / auth / surface / surfaceCeiling) for
 *       the call. The only serve-http code NOT under test here is its
 *       express/SDK glue and verifyAccessToken; the full OAuth-server sweep
 *       (real HTTP, real tokens) runs on a Postgres-equipped host via
 *       test/e2e/serve-http-oauth.test.ts.
 *
 * Config is pinned on the DB plane (which wins the dual-plane read) so the
 * developer's real ~/.gbrain/config.json can never flip an assertion, and
 * GBRAIN_HOME is redirected to a tmpdir for the file plane. mcp.strict_params
 * is pinned 'reject' so no garbage-arg probe can ever execute a write handler
 * (FOV-6c: exactly ONE warn-mode case below, probing a READ op only).
 *
 * Wall-clock budget: the whole file should finish in < 3 minutes (ENG-21).
 * The budget is ENFORCED only under GBRAIN_TEST_ENFORCE_E5_BUDGET=1 (a loaded CI
 * shard or laptop makes wall-clock assertions flaky); otherwise an overrun
 * warns loudly so drift is still visible.
 */

import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { createHash } from 'crypto';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import {
  operations,
  opAllowedForBoundClient,
  type Operation,
  type AuthInfo,
} from '../src/core/operations.ts';
import { hasScope, operationScopesAllowed } from '../src/core/scope.ts';
import {
  filterOpsForSurface,
  STARTER_OPS,
  effectiveSurfaceForClient,
  resolveClientRowSurface,
  resolveDefaultClientSurface,
  type McpSurface,
} from '../src/mcp/surface.ts';
import { disabledOpsForPublishGates } from '../src/mcp/publish-gates.ts';
import {
  dispatchToolCall,
  isListLevelDenialEnvelope,
  type ToolResult,
} from '../src/mcp/dispatch.ts';
import { startHttpTransport } from '../src/mcp/http-transport.ts';
import { RateLimiter } from '../src/mcp/rate-limit.ts';
import { __setUsageLogPathForTests } from '../src/core/verbs/usage-log.ts';
import { withEnv } from './helpers/with-env.ts';

// Set in beforeAll — module-load time would charge other files' transpile
// and collection work against this file's budget.
let T0 = 0;
const WALL_CLOCK_BUDGET_MS = 3 * 60 * 1000;

const SKILL_FIXTURE = join(import.meta.dir, 'fixtures', 'skill-catalog', 'skills');
const BOUND_PREFIX = 'e2e-bound/';
const LEGACY_TOKEN = 'e5-truthful-catalog-legacy-token';
// Legacy tokens with no explicit scope column retain read/write/admin. The
// paid agent lane is a separate grant; admin does not imply agent.
const LEGACY_DEFAULT_SCOPES = ['read', 'write', 'admin'];

/**
 * Hermetic env pins, applied via withEnv (the repo's R1-compliant pattern):
 * the file config plane reads $GBRAIN_HOME/.gbrain/config.json, and a stray
 * GBRAIN_MCP_FORCE_SURFACE would silently narrow every resolved surface.
 * All decision-relevant config is ALSO pinned on the DB plane (which wins
 * the dual-plane reads), so the pins are belt-and-suspenders.
 */
const home = mkdtempSync(join(tmpdir(), 'e5-truthful-catalog-'));
const ENV_PINS: Record<string, string | undefined> = {
  GBRAIN_HOME: home,
  GBRAIN_MCP_FORCE_SURFACE: undefined,
};

/** test() wrapper: every body runs under the hermetic env pins. */
function e5test(name: string, fn: () => Promise<void> | void): void {
  test(name, () => withEnv(ENV_PINS, async () => { await fn(); }));
}

let engine: PGLiteEngine;
let legacyUrl: string;
let legacyStop: (() => void) | null = null;

// ---------------------------------------------------------------------------
// Shared setup — ONE engine, ONE legacy server, reused across every cell
// (ENG-21). Gate/strict flips happen on the DB plane per cell, restart-free.
// ---------------------------------------------------------------------------

beforeAll(async () => {
  T0 = Date.now();
  __setUsageLogPathForTests(join(home, 'verb-usage.jsonl'));
  await withEnv(ENV_PINS, async () => {
    engine = new PGLiteEngine();
    await engine.connect({});
    await engine.initSchema();

    // DB-plane pins (DB > file, so the dev's real config can't leak in):
    // strict_params=reject means a garbage-arg probe NEVER executes a handler;
    // gates start OFF (the default-off consent posture); the skill catalog
    // points at the test fixture so gate-ON probes are deterministic.
    await engine.setConfig('mcp.strict_params', 'reject');
    await setGates(false);
    await engine.setConfig('mcp.skills_dir', SKILL_FIXTURE);

    // One REAL legacy bearer server over the real engine, started inside the
    // env pins (its surface clamp + file-config snapshot resolve at startup).
    // Generous limiters — the full probe sweep would exhaust the default
    // 30 req/min IP bucket.
    await engine.executeRaw(
      `INSERT INTO access_tokens (name, token_hash) VALUES ($1, $2)`,
      ['e5-truthful-catalog', createHash('sha256').update(LEGACY_TOKEN).digest('hex')],
    );
    const server = await startHttpTransport({
      port: 0,
      engine,
      limiters: {
        ip: new RateLimiter({ limit: 100_000, windowMs: 60_000, lruCap: 100 }),
        token: new RateLimiter({ limit: 100_000, windowMs: 60_000, lruCap: 100 }),
      },
      surface: 'full',
    });
    legacyUrl = `http://localhost:${(server as { port: number }).port}`;
    legacyStop = () => (server as unknown as { stop: (force: boolean) => void }).stop(true);
  });
});

afterAll(async () => {
  legacyStop?.();
  await engine.disconnect();
  __setUsageLogPathForTests(null);
  try { rmSync(home, { recursive: true, force: true }); } catch { /* best-effort */ }
});

// ---------------------------------------------------------------------------
// Harness helpers
// ---------------------------------------------------------------------------

/** Flip EVERY publish gate together on the DB plane (per-key independence is
 * pinned by test/publish-gates.test.ts; the matrix treats gates as one axis). */
async function setGates(on: boolean): Promise<void> {
  await engine.setConfig('mcp.publish_skills', on ? 'true' : 'false');
  await engine.setConfig('mcp.publish_advisor', on ? 'true' : 'false');
  await engine.setConfig('mcp.publish_memory_settings', on ? 'true' : 'false');
  await engine.setConfig('mcp.publish_wakeshift', on ? 'true' : 'false');
}

interface Cell {
  label: string;
  /** Explicit token scopes; null = the legacy read/write/admin defaults. */
  scopes: string[] | null;
  surface: McpSurface;
  gatesOn: boolean;
  bound: boolean;
}

function cellAuth(cell: Cell): AuthInfo {
  const clientId = `e5-${cell.label}`;
  return {
    token: 'e5-token',
    clientId,
    principal: { kind: 'oauth_client', id: clientId },
    scopes: cell.scopes ?? LEGACY_DEFAULT_SCOPES,
    ...(cell.bound ? { boundSlugPrefixes: [BOUND_PREFIX] } : {}),
  };
}

/**
 * The INDEPENDENTLY-composed expectation for what a cell's tools/list must
 * contain, written per-axis from the plan's rules (D7 localOnly, frozen
 * verbs / STARTER_OPS, scope hierarchy + FOV-4 carve-out, ENG-3 bound
 * predicate, WP1 gates). The probes below then assert the REAL dispatch
 * agrees with this set — listed means callable, hidden means denied.
 */
function expectedVisibleSet(cell: Cell): Set<string> {
  const out = new Set<string>();
  const scopes = cell.scopes ?? LEGACY_DEFAULT_SCOPES;
  for (const op of operations) {
    if (op.localOnly) continue;                                  // D7: network transport
    if (op.cliOnly) continue;                                    // F5: owner-only CLI ops are never listed on MCP
    if (cell.surface === 'verbs' && op.verb !== true) continue;  // frozen verb surface
    if (cell.surface === 'starter' && !STARTER_OPS.has(op.name)) continue;
    const scopeOk = hasScope(scopes, op.scope ?? 'read')
      || (op.agentCallable === true && hasScope(scopes, 'agent')); // FOV-4
    if (!scopeOk) continue;
    if (!(op.requiredScopes ?? []).every(scope => hasScope(scopes, scope))) continue;
    if (cell.bound && !opAllowedForBoundClient({ boundSlugPrefixes: [BOUND_PREFIX] }, op)) continue;
    if (op.publishGateKey && !cell.gatesOn) continue;            // WP1 honest catalog
    if (op.publishGateKey === 'mcp.publish_wakeshift') continue; // host file plane plus key only; a DB row never lists it
    out.add(op.name);
  }
  return out;
}

/**
 * The serve-http ListTools computation, composed from the exact seams the
 * real handler uses (serve-http.ts POST /mcp → ListToolsRequestSchema):
 * surface filter after the localOnly filter, then isCallable's cliOnly
 * exclusion (F5), scope (+ agentCallable carve-out), bound-client predicate,
 * publish gates.
 */
async function oauthToolsList(cell: Cell): Promise<Set<string>> {
  const mcpOperations = filterOpsForSurface(operations.filter(op => !op.localOnly), cell.surface);
  const gateDisabled = await disabledOpsForPublishGates(engine, null);
  const auth = cellAuth(cell);
  const visible = mcpOperations.filter(op =>
    !op.cliOnly
    && operationScopesAllowed(auth.scopes, op)
    && opAllowedForBoundClient(auth, op)
    && !gateDisabled.has(op.name));
  return new Set(visible.map(o => o.name));
}

type ProbeKind =
  | 'success'
  | 'invalid_params'
  | 'unknown'             // unknown_tool / unknown_operation
  | 'list_level_denial'   // config_key= / fence=op / insufficient_scope
  | 'arg_level_denial'    // permission_denied WITHOUT a list-level marker (D10: legitimate)
  | 'other_error';

interface ProbeVerdict { kind: ProbeKind; envelope: Record<string, unknown> | null }

function classify(result: ToolResult): ProbeVerdict {
  if (!result.isError) return { kind: 'success', envelope: null };
  let parsed: Record<string, unknown>;
  try {
    parsed = JSON.parse(result.content[0]?.text ?? '') as Record<string, unknown>;
  } catch {
    return { kind: 'other_error', envelope: null };
  }
  if (isListLevelDenialEnvelope(parsed)) return { kind: 'list_level_denial', envelope: parsed };
  if (parsed.error === 'insufficient_scope') return { kind: 'list_level_denial', envelope: parsed };
  if (parsed.error === 'unknown_tool' || parsed.error === 'unknown_operation') return { kind: 'unknown', envelope: parsed };
  if (parsed.error === 'invalid_params') return { kind: 'invalid_params', envelope: parsed };
  if (parsed.error === 'permission_denied') return { kind: 'arg_level_denial', envelope: parsed };
  return { kind: 'other_error', envelope: parsed };
}

/**
 * The serve-http CallTool path over the shared dispatcher: op resolution
 * against the surfaced set (unknown_operation outside it), the hasScope +
 * agentCallable gate (insufficient_scope — logged denied_after_list in
 * production), then the REAL dispatchToolCall with the same opts serve-http
 * passes (remote/http/allowedOps/auth/surface/surfaceCeiling).
 */
async function oauthToolCall(
  cell: Cell,
  name: string,
  args: Record<string, unknown>,
): Promise<ProbeVerdict> {
  const mcpOperations = filterOpsForSurface(operations.filter(op => !op.localOnly), cell.surface);
  const op = mcpOperations.find(o => o.name === name);
  if (!op) return { kind: 'unknown', envelope: { error: 'unknown_operation' } };
  const auth = cellAuth(cell);
  const scopeSatisfied = operationScopesAllowed(auth.scopes, op);
  if (!scopeSatisfied) {
    return { kind: 'list_level_denial', envelope: { error: 'insufficient_scope' } };
  }
  const surfaceAllowedOps: ReadonlySet<string> | undefined =
    cell.surface === 'full' ? undefined : new Set(mcpOperations.map(o => o.name));
  const result = await dispatchToolCall(engine, name, args, {
    remote: true,
    transport: 'http',
    sourceId: 'default',
    auth,
    ...(surfaceAllowedOps ? { allowedOps: surfaceAllowedOps } : {}),
    surface: cell.surface,
    surfaceCeiling: cell.surface,
  });
  return classify(result);
}

/**
 * D10 probe semantics: WRONG-TYPED values for every required param (rejects
 * in warn AND reject modes, before any handler runs); ops with no required
 * params get one undeclared key, which the pinned strict_params=reject
 * refuses — so a full sweep can never execute a write handler.
 */
function probeArgsFor(op: Operation): Record<string, unknown> {
  const wrong: Record<string, unknown> = {};
  let hasRequired = false;
  for (const [key, def] of Object.entries(op.params)) {
    if (!def.required) continue;
    hasRequired = true;
    wrong[key] =
      def.type === 'string' ? 42
      : def.type === 'number' ? 'not-a-number'
      : def.type === 'boolean' ? 'not-a-boolean'
      : def.type === 'array' ? 'not-an-array'
      : 42; // object → number
  }
  return hasRequired ? wrong : { e5_garbage_probe: true };
}

/** Probe EVERY listed tool; return invariant violations (empty = truthful). */
async function sweepCell(cell: Cell, listed: ReadonlySet<string>): Promise<string[]> {
  const violations: string[] = [];
  for (const name of [...listed].sort()) {
    const op = operations.find(o => o.name === name);
    if (!op) { violations.push(`${cell.label}: listed "${name}" is not a known operation`); continue; }
    const verdict = await oauthToolCall(cell, name, probeArgsFor(op));
    // Garbage probes must die at validation — anything else means either a
    // list-level denial (the invariant breach) or a handler executed on
    // garbage args despite strict_params=reject.
    if (verdict.kind !== 'invalid_params') {
      violations.push(`${cell.label}: listed "${name}" → ${verdict.kind} ${JSON.stringify(verdict.envelope)}`);
    }
  }
  return violations;
}

function sortedArray(s: ReadonlySet<string>): string[] {
  return [...s].sort();
}

// --- legacy bearer transport (real HTTP) helpers ---------------------------

async function legacyRpc(method: string, params?: unknown): Promise<Record<string, unknown>> {
  const res = await fetch(`${legacyUrl}/mcp`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${LEGACY_TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, ...(params !== undefined ? { params } : {}) }),
  });
  expect(res.status).toBe(200);
  return await res.json() as Record<string, unknown>;
}

async function legacyToolsList(): Promise<Set<string>> {
  const body = await legacyRpc('tools/list');
  const tools = (body.result as { tools: Array<{ name: string }> }).tools;
  return new Set(tools.map(t => t.name));
}

async function legacyToolCall(name: string, args: Record<string, unknown>): Promise<ProbeVerdict> {
  const body = await legacyRpc('tools/call', { name, arguments: args });
  return classify(body.result as ToolResult);
}

// ---------------------------------------------------------------------------
// (a) The legacy bearer transport — real HTTP server, real engine
// ---------------------------------------------------------------------------

describe('E5 truthful catalog — legacy bearer transport (real HTTP, PGLite)', () => {
  e5test('gates off: tools/list is exactly the expected honest set (no gated, no localOnly)', async () => {
    await setGates(false);
    const listed = await legacyToolsList();
    const expected = expectedVisibleSet({
      label: 'legacy-full-gates-off', scopes: null, surface: 'full', gatesOn: false, bound: false,
    });
    expect(sortedArray(listed)).toEqual(sortedArray(expected));
    for (const gated of ['list_skills', 'get_skill', 'list_brain_skillpack', 'advisor']) {
      expect(listed.has(gated)).toBe(false);
    }
    for (const localOnly of ['file_list', 'file_upload', 'file_url', 'sync_brain']) {
      expect(listed.has(localOnly)).toBe(false);
    }
    for (const [name, args] of [
      ['submit_agent', { prompt: 'Synthetic scope probe' }],
      ['get_agent_job', { id: 1 }],
    ] as const) {
      expect(listed.has(name)).toBe(false);
      const denied = await legacyToolCall(name, args);
      expect(denied.envelope?.error).toBe('permission_denied');
      expect(denied.envelope?.message).toBe('Tool requires agent scope');
      expect(denied.envelope).toMatchObject({ code: 'insufficient_scope', reason: 'insufficient_scope', fix: { actor: 'host_admin', next: 'tell_user_to_run' } });
      expect((denied.envelope as { fix?: { argv?: string[] } }).fix?.argv?.slice(0, 2)).toEqual(['gbrain', 'auth']);
    }
  });

  e5test('full probe sweep: every listed tool dies at validation, never at a list-level denial', async () => {
    await setGates(false);
    const listed = await legacyToolsList();
    expect(listed.size).toBeGreaterThan(50); // the sweep is real, not vacuous
    const violations: string[] = [];
    for (const name of sortedArray(listed)) {
      const op = operations.find(o => o.name === name);
      if (!op) { violations.push(`legacy: listed "${name}" is not a known operation`); continue; }
      const verdict = await legacyToolCall(name, probeArgsFor(op));
      if (verdict.kind !== 'invalid_params') {
        violations.push(`legacy: listed "${name}" → ${verdict.kind} ${JSON.stringify(verdict.envelope)}`);
      }
    }
    expect(violations).toEqual([]);
  });

  e5test('inverse: localOnly op is uncallable with the no-leak unknown_tool envelope', async () => {
    const denied = await legacyToolCall('file_list', {});
    expect(denied.kind).toBe('unknown');
    expect(denied.envelope?.message).toBe('Unknown tool: file_list');
    // Byte-identical error class to a nonexistent op — no existence oracle.
    const noSuchOp = await legacyToolCall('e5_no_such_op_xyz', {});
    expect(noSuchOp.kind).toBe('unknown');
    expect(denied.envelope?.error).toBe(noSuchOp.envelope?.error);
  });

  e5test('inverse: gate-hidden op is call-time-denied with the config_key grammar, never success', async () => {
    await setGates(false);
    expect((await legacyToolsList()).has('list_skills')).toBe(false);
    const verdict = await legacyToolCall('list_skills', {});
    expect(verdict.kind).toBe('list_level_denial');
    expect(verdict.envelope?.detail).toBe('config_key=mcp.publish_skills');
  });

  e5test('restart-free gate flip: ON lists + allows the gated ops; OFF hides them again (per-request read)', async () => {
    await setGates(true);
    const listedOn = await legacyToolsList();
    for (const gated of ['list_skills', 'get_skill', 'list_brain_skillpack', 'advisor']) {
      expect(listedOn.has(gated)).toBe(true);
    }
    // Listed means callable: the gate-on probe reaches the handler and is
    // never a list-level denial (the fixture catalog makes it a clean read).
    const skills = await legacyToolCall('list_skills', {});
    expect(skills.kind).toBe('success');
    const skill = await legacyToolCall('get_skill', { name: 'brain-ops' });
    expect(skill.kind).toBe('success');

    await setGates(false);
    const listedOff = await legacyToolsList();
    for (const gated of ['list_skills', 'get_skill', 'list_brain_skillpack', 'advisor']) {
      expect(listedOff.has(gated)).toBe(false);
    }
  });

  e5test('FOV-6c: the ONE warn-mode case — a READ op accepts the garbage key with a warning, never a denial', async () => {
    try {
      await engine.setConfig('mcp.strict_params', 'warn');
      const body = await legacyRpc('tools/call', {
        name: 'list_pages',
        arguments: { limit: 1, e5_garbage_probe: true },
      });
      const result = body.result as ToolResult;
      expect(result.isError ?? false).toBe(false); // warn mode accepts
      const meta = result._meta as { warnings?: Array<{ code: string; param: string }> } | undefined;
      expect(meta?.warnings?.[0]?.code).toBe('unknown_param');
      expect(meta?.warnings?.[0]?.param).toBe('e5_garbage_probe');
      // HARN-15: the warning lives in _meta.warnings only; no content block names it.
      const blocks = result.content.map(c => c.text);
      expect(blocks.some(t => t.includes('e5_garbage_probe'))).toBe(false);
    } finally {
      await engine.setConfig('mcp.strict_params', 'reject');
    }
  });
});

// ---------------------------------------------------------------------------
// (b) The OAuth serve-http semantics — in-process over the real dispatcher
// ---------------------------------------------------------------------------

const SCOPE_ROWS: ReadonlyArray<[string, string[]]> = [
  ['read', ['read']],
  ['write', ['write']],
  ['admin', ['admin']],
  ['agent', ['agent']],
];
const SURFACES: ReadonlyArray<McpSurface> = ['verbs', 'starter', 'full'];

function makeCell(scopeName: string, scopes: string[], surface: McpSurface, gatesOn: boolean, bound: boolean): Cell {
  return {
    label: `${scopeName}+${surface}+gates-${gatesOn ? 'on' : 'off'}${bound ? '+bound' : ''}`,
    scopes, surface, gatesOn, bound,
  };
}

describe('E5 truthful catalog — OAuth-path cells (serve-http seams over dispatch)', () => {
  e5test('extreme cell: admin + full + gates-on — list-set equality + full probe sweep + gate reachability', async () => {
    await setGates(true);
    const cell = makeCell('admin', ['admin'], 'full', true, false);
    const listed = await oauthToolsList(cell);
    expect(sortedArray(listed)).toEqual(sortedArray(expectedVisibleSet(cell)));
    // Gated ops are LISTED with gates on…
    for (const gated of ['list_skills', 'get_skill', 'list_brain_skillpack', 'advisor']) {
      expect(listed.has(gated)).toBe(true);
    }
    // …and agent-lane ops are NOT (admin does not imply agent, v0.38 D13).
    expect(listed.has('submit_agent')).toBe(false);

    expect(await sweepCell(cell, listed)).toEqual([]);

    // Listed-gated ops are REACHABLE with valid args (the call-time gate
    // backstop must agree with the list): never a list-level denial.
    for (const [name, args] of [
      ['list_skills', {}],
      ['get_skill', { name: 'brain-ops' }],
      ['list_brain_skillpack', {}],
      ['advisor', {}],
    ] as Array<[string, Record<string, unknown>]>) {
      const verdict = await oauthToolCall(cell, name, args);
      expect(['list_level_denial', 'unknown']).not.toContain(verdict.kind);
    }
  });

  e5test('extreme cell: read + starter + gates-off — list-set equality + full probe sweep', async () => {
    await setGates(false);
    const cell = makeCell('read', ['read'], 'starter', false, false);
    const listed = await oauthToolsList(cell);
    expect(sortedArray(listed)).toEqual(sortedArray(expectedVisibleSet(cell)));
    // The starter read slice keeps discovery (FOV-4/D4) and hides writes.
    expect(listed.has('request_tools')).toBe(true);
    expect(listed.has('put_page')).toBe(false);
    // STARTER_OPS carries localOnly daily-driver names (file_list); the
    // network list must still exclude them (localOnly filters run FIRST).
    expect(listed.has('file_list')).toBe(false);

    expect(await sweepCell(cell, listed)).toEqual([]);
  });

  e5test('extreme cell: bound client + write + full + gates-on — sweep + ENG-3/D9/D10 fence pins', async () => {
    await setGates(true);
    const cell = makeCell('write', ['write'], 'full', true, true);
    const listed = await oauthToolsList(cell);
    expect(sortedArray(listed)).toEqual(sortedArray(expectedVisibleSet(cell)));
    // The fenced-write allow-list and the D9 discovery carve-out are listed;
    // unfenceable writes are not.
    expect(listed.has('put_page')).toBe(true);
    expect(listed.has('request_tools')).toBe(true);
    expect(listed.has('extract_facts')).toBe(false);

    expect(await sweepCell(cell, listed)).toEqual([]);

    // Listed fenced write is genuinely callable (dry-run, in-prefix).
    const inPrefix = await oauthToolCall(cell, 'put_page', {
      slug: `${BOUND_PREFIX}e5-probe`, content: '# probe', dry_run: true,
    });
    expect(inPrefix.kind).toBe('success');

    // D10 carve-out: an out-of-prefix slug on a LISTED op is an ARGUMENT-level
    // denial — permission_denied WITHOUT the fence=op marker, excluded from
    // the invariant (and from the denied_after_list metric).
    const outOfPrefix = await oauthToolCall(cell, 'put_page', {
      slug: 'wiki/other/e5-probe', content: '# probe', dry_run: true,
    });
    expect(outOfPrefix.kind).toBe('arg_level_denial');
    expect(isListLevelDenialEnvelope(outOfPrefix.envelope)).toBe(false);

    // Inverse (ENG-3, same predicate at list and call time): a fence-hidden
    // unfenceable write with VALID args denies with the fence=op marker.
    const fenced = await oauthToolCall(cell, 'extract_facts', { turn_text: 'e5 probe' });
    expect(fenced.kind).toBe('list_level_denial');
    expect(fenced.envelope?.detail).toBe('fence=op');

    // D9: discovery survives the fence for slug-bound clients.
    const discovery = await oauthToolCall(cell, 'request_tools', {});
    expect(discovery.kind).toBe('success');
  });

  e5test('matrix: list-set equality for every scope × surface × gates × bound cell (amendment 31)', async () => {
    const mismatches: string[] = [];
    for (const gatesOn of [true, false]) {
      await setGates(gatesOn);
      for (const [scopeName, scopes] of SCOPE_ROWS) {
        for (const surface of SURFACES) {
          for (const bound of [false, true]) {
            const cell = makeCell(scopeName, scopes, surface, gatesOn, bound);
            const actual = sortedArray(await oauthToolsList(cell));
            const expected = sortedArray(expectedVisibleSet(cell));
            if (JSON.stringify(actual) !== JSON.stringify(expected)) {
              mismatches.push(`${cell.label}: listed [${actual.join(',')}] != expected [${expected.join(',')}]`);
            }
          }
        }
      }
    }
    expect(mismatches).toEqual([]);
  });

  e5test('matrix: denial-class representative probes per cell (gated ×4, admin op, localOnly op, request_tools)', async () => {
    const violations: string[] = [];
    const record = (cell: Cell, name: string, msg: string) =>
      violations.push(`${cell.label} / ${name}: ${msg}`);

    for (const gatesOn of [true, false]) {
      await setGates(gatesOn);
      for (const [scopeName, scopes] of SCOPE_ROWS) {
        for (const surface of SURFACES) {
          const cell = makeCell(scopeName, scopes, surface, gatesOn, false);
          const expected = expectedVisibleSet(cell);

          // The four publish-gated ops, probed with VALID args so the
          // call-time gate backstop is actually reached. advisor's listed
          // case uses a garbage probe instead (its full run is exercised
          // once in the extreme cell; reachability is scope/surface-blind).
          const gatedProbes: Array<[string, Record<string, unknown>, Record<string, unknown> | null]> = [
            ['list_skills', {}, null],
            ['get_skill', { name: 'brain-ops' }, null],
            ['list_brain_skillpack', {}, null],
            ['advisor', {}, { e5_garbage_probe: true }],
          ];
          for (const [name, hiddenArgs, listedArgsOverride] of gatedProbes) {
            if (expected.has(name)) {
              const verdict = await oauthToolCall(cell, name, listedArgsOverride ?? hiddenArgs);
              if (verdict.kind === 'list_level_denial' || verdict.kind === 'unknown') {
                record(cell, name, `listed but ${verdict.kind}: ${JSON.stringify(verdict.envelope)}`);
              }
            } else {
              const verdict = await oauthToolCall(cell, name, hiddenArgs);
              if (verdict.kind === 'success') record(cell, name, 'hidden but callable');
              if (verdict.kind !== 'unknown' && verdict.kind !== 'list_level_denial') {
                record(cell, name, `hidden with unexpected verdict ${verdict.kind}: ${JSON.stringify(verdict.envelope)}`);
              }
            }
          }

          // One admin op: listed → dies at validation; hidden → scope/surface
          // denial, never success (the honest-catalog inverse).
          {
            const verdict = await oauthToolCall(cell, 'run_doctor', { e5_garbage_probe: true });
            if (expected.has('run_doctor')) {
              if (verdict.kind !== 'invalid_params') {
                record(cell, 'run_doctor', `listed but ${verdict.kind}: ${JSON.stringify(verdict.envelope)}`);
              }
            } else if (verdict.kind !== 'unknown' && verdict.kind !== 'list_level_denial') {
              record(cell, 'run_doctor', `hidden with unexpected verdict ${verdict.kind}`);
            }
          }

          // One localOnly op: never listed, always the no-leak unknown envelope.
          {
            if (expected.has('file_list')) record(cell, 'file_list', 'localOnly op in the expected list');
            const verdict = await oauthToolCall(cell, 'file_list', {});
            if (verdict.kind !== 'unknown') {
              record(cell, 'file_list', `expected unknown, got ${verdict.kind}: ${JSON.stringify(verdict.envelope)}`);
            }
          }

          // request_tools probed with {surface:'garbage'} → invalid_params on
          // the listed surfaces (never a persist), unknown on verbs (D4/D10).
          {
            const verdict = await oauthToolCall(cell, 'request_tools', { surface: 'garbage' });
            if (expected.has('request_tools')) {
              if (verdict.kind !== 'invalid_params') {
                record(cell, 'request_tools', `expected invalid_params, got ${verdict.kind}: ${JSON.stringify(verdict.envelope)}`);
              }
            } else if (verdict.kind !== 'unknown') {
              record(cell, 'request_tools', `expected unknown on ${cell.surface}, got ${verdict.kind}`);
            }
            const rows = await engine.executeRaw(
              `SELECT count(*)::int AS n FROM oauth_clients WHERE client_id = $1`,
              [`e5-${cell.label}`],
            ) as Array<{ n: number }>;
            if (rows[0].n !== 0) record(cell, 'request_tools', 'garbage surface probe persisted a client row');
          }
        }
      }
    }
    expect(violations).toEqual([]);
  });

  e5test('FOV-4: the agent-only token row lists exactly its callable set, and every member is callable', async () => {
    await setGates(false);
    const cell = makeCell('agent', ['agent'], 'full', false, false);
    const listed = await oauthToolsList(cell);
    // #4098: the generic queue ops (get/list/progress/cancel) are
    // agentCallable with an owner-client fence, so the honest agent-lane
    // row includes them alongside the submit_agent/get_agent_job pair.
    expect(sortedArray(listed)).toEqual([
      'cancel_job', 'get_agent_job', 'get_job', 'get_job_progress',
      'list_jobs', 'request_tools', 'submit_agent', 'wait_job',
    ]);

    // Probes: garbage args die at validation (proving the scope layer let
    // them through), and discovery genuinely works for the agent class.
    for (const name of ['submit_agent', 'get_agent_job', 'get_job', 'get_job_progress', 'cancel_job', 'list_jobs']) {
      const op = operations.find(o => o.name === name)!;
      const verdict = await oauthToolCall(cell, name, probeArgsFor(op));
      expect(verdict.kind).toBe('invalid_params');
    }
    const discovery = await oauthToolCall(cell, 'request_tools', {});
    expect(discovery.kind).toBe('success');

    // Inverse: a read op is NOT listed and NOT callable for the agent class.
    expect(listed.has('get_page')).toBe(false);
    const denied = await oauthToolCall(cell, 'get_page', { slug: 'x' });
    expect(denied.kind).toBe('list_level_denial');
  });

  e5test('monotonicity: verbs ⊆ starter ⊆ full listing per token class (both gate states)', async () => {
    const rows: Array<[string, string[], boolean]> = [
      ...SCOPE_ROWS.map(([name, scopes]) => [name, scopes, false] as [string, string[], boolean]),
      ['bound-write', ['write'], true],
    ];
    for (const gatesOn of [true, false]) {
      await setGates(gatesOn);
      for (const [scopeName, scopes, bound] of rows) {
        const verbs = await oauthToolsList(makeCell(scopeName, scopes, 'verbs', gatesOn, bound));
        const starter = await oauthToolsList(makeCell(scopeName, scopes, 'starter', gatesOn, bound));
        const full = await oauthToolsList(makeCell(scopeName, scopes, 'full', gatesOn, bound));
        for (const name of verbs) {
          expect(starter.has(name)).toBe(true);
        }
        for (const name of starter) {
          expect(full.has(name)).toBe(true);
        }
      }
    }
  });
});

// ---------------------------------------------------------------------------
// persist → re-list flip (amendment 20: per-request recompute, no restart)
// ---------------------------------------------------------------------------

describe('E5 truthful catalog — request_tools persist flips the very next list', () => {
  e5test('{surface: starter} persist → the next per-request resolution serves the starter list, no restart', async () => {
    await setGates(false);
    const clientId = 'e5-flip-client';
    await engine.executeRaw(
      `INSERT INTO oauth_clients (client_id, client_name) VALUES ($1, $2)
       ON CONFLICT (client_id) DO NOTHING`,
      [clientId, 'e5 flip client'],
    );
    const auth: AuthInfo = { token: 't', clientId, scopes: ['read'] };

    // Request #1: NULL row surface + unset DCR default → the server ceiling
    // (full) — pre-WP4 behavior, existing clients untouched.
    const readRowSurface = async (): Promise<unknown> => {
      const rows = await engine.executeRaw(
        `SELECT surface FROM oauth_clients WHERE client_id = $1`, [clientId],
      ) as Array<{ surface: unknown }>;
      return rows[0]?.surface ?? null;
    };
    const resolveEffective = async (): Promise<McpSurface> => effectiveSurfaceForClient({
      ceiling: 'full',
      clientSurface: resolveClientRowSurface(await readRowSurface(), clientId),
      defaultSurface: await resolveDefaultClientSurface(engine, null),
    });

    const before = await resolveEffective();
    expect(before).toBe('full');
    const listBefore = await oauthToolsList({ label: 'flip-before', scopes: ['read'], surface: before, gatesOn: false, bound: false });

    // The REAL persist through the real dispatcher (the same seam serve-http
    // drives). NOTE the verifyAccessToken row-read leg of the loop is
    // emulated by re-reading the row below; the full OAuth-server round trip
    // is the Postgres-host assertion in test/e2e/serve-http-oauth.test.ts.
    const persist = await dispatchToolCall(engine, 'request_tools', { surface: 'starter' }, {
      remote: true, transport: 'http', sourceId: 'default', auth,
      surface: before, surfaceCeiling: 'full',
    });
    expect(persist.isError ?? false).toBe(false);
    const body = JSON.parse(persist.content[0].text) as { persisted: boolean; surface: string };
    expect(body.persisted).toBe(true);
    expect(body.surface).toBe('starter');

    // Request #2, same process, no restart: per-request recompute reads the
    // persisted row and the effective surface narrows to starter.
    const after = await resolveEffective();
    expect(after).toBe('starter');
    const listAfter = await oauthToolsList({ label: 'flip-after', scopes: ['read'], surface: after, gatesOn: false, bound: false });
    expect(sortedArray(listAfter)).toEqual(sortedArray(expectedVisibleSet({
      label: 'flip-expected', scopes: ['read'], surface: 'starter', gatesOn: false, bound: false,
    })));
    // Strictly narrower, and still a subset of what full served (ENG-1 ladder).
    expect(listAfter.size).toBeLessThan(listBefore.size);
    for (const name of listAfter) {
      expect(listBefore.has(name)).toBe(true);
    }
  });
});

// ---------------------------------------------------------------------------
// Wall-clock budget (ENG-21) — declared LAST so it runs after every cell.
// ---------------------------------------------------------------------------

describe('E5 budget', () => {
  test(`the whole file completes in < ${WALL_CLOCK_BUDGET_MS / 60000} minutes`, () => {
    const elapsed = Date.now() - T0;
    if (elapsed >= WALL_CLOCK_BUDGET_MS) {
      const msg =
        `E5 truthful-catalog run took ${(elapsed / 1000).toFixed(1)}s — past the ${WALL_CLOCK_BUDGET_MS / 1000}s ` +
        `budget (ENG-21). The invariant guard must stay cheap enough to run in every unit pass; ` +
        `trim probe work or split cells before raising this budget.`;
      // Machine load makes wall-clock assertions flaky — hard-fail only when
      // the budget gate is explicitly armed (dedicated perf lane / local run).
      if (process.env.GBRAIN_TEST_ENFORCE_E5_BUDGET === '1') throw new Error(msg);
      console.warn(msg);
    }
  });
});