fix(gbrain): thin-client state — remote-MCP brains no longer classify as broken-config (#2051)

A thin client (remote-HTTP MCP brain, no local engine by design) probed `gbrain sources list`, which gbrain's dispatch guard REFUSES on thin clients (exit 1, no recognized error string), so the classifier fell to its defensive broken-config default and every suppression gate silently hid brain-aware blocks from exactly the users on a shared team brain. New 'thin-client' state, detected PRE-probe from gbrain's own remote_mcp config marker via the existing gbrainConfigPath() helper (mirrors gbrain's isThinClient(); honors GBRAIN_HOME; zero network, immune to error-string drift), with a /thin[- ]client/ stderr backstop in the probe catch. Remote reachability is deliberately NOT probed by the classifier — that is the #1964 pathology; gbrain calls degrade gracefully at use time, and the detect JSON says so honestly (gbrain_thin_client: {probed: false}). The state is admitted at every suppression gate — gstack-gbrain-detect --is-ok (drives setup + gbrain-refresh), gen-skill-docs' detection override, gstack-config gbrain-refresh — while the sync stages (code/memory/dream) SKIP with an accurate reason: code indexing runs on the brain server, memory syncs via the remote brain's artifacts pull. The two consumer classes need opposite answers, which is why this is a distinct state and not a skip-the-probe special case. sync-gbrain Step 1.5 and setup-gbrain prose route thin-client to proceed, never into broken-config remediation. detectMcpMode secondary generalization: url-match against the config's remote_mcp.mcp_url (deterministic — gbrain mounts at the generic /mcp path) -> name pattern gbrain[-_]* -> stdio command token; gbrain_mcp_mode stays a 3-value enum. Tripwires: end-to-end --is-ok exits 0 on a thin-client fixture AND still exits 1 on broken-config (the gate didn't widen); pre-probe + stderr-fallback classifier paths; 4 detectMcpMode identification cases incl. a non-matching url that must NOT false-positive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-10 15:09:00 +02:00 · 2026-07-09 19:29:37 -07:00
parent a7a25aa489
commit e742648eda
9 changed files with 266 additions and 27 deletions
@@ -31,7 +31,7 @@ import {
  utimesSync,
 } from "fs";
 import { tmpdir } from "os";
-import { join } from "path";
+import { join, dirname } from "path";

 import { spawnSync } from "child_process";

@@ -61,8 +61,10 @@ interface FakeEnv {
 */
 function makeEnv(opts: {
  withGbrain?: boolean;
-  gbrainBehavior?: "ok" | "broken-db" | "broken-config" | "throws" | "slow";
+  gbrainBehavior?: "ok" | "broken-db" | "broken-config" | "throws" | "slow" | "thin-refusal";
  withConfig?: boolean;
+  /** #2051: config carries gbrain's remote_mcp thin-client marker. */
+  thinClientConfig?: boolean;
 }): FakeEnv {
  const tmp = mkdtempSync(join(tmpdir(), "gbrain-local-status-test-"));
  const bindir = join(tmp, "bin");
@@ -76,7 +78,12 @@ function makeEnv(opts: {
  mkdirSync(gstackHome, { recursive: true });
  mkdirSync(configDir, { recursive: true });

-  if (opts.withConfig) {
+  if (opts.thinClientConfig) {
+    writeFileSync(
+      configPath,
+      JSON.stringify({ remote_mcp: { mcp_url: "https://brain.example.com/mcp" } }),
+    );
+  } else if (opts.withConfig) {
    writeFileSync(
      configPath,
      JSON.stringify({ engine: "pglite", database_url: "pglite:///fake" }),
@@ -102,7 +109,7 @@ function makeEnv(opts: {
 }

 function makeFakeGbrainScript(
-  behavior: "ok" | "broken-db" | "broken-config" | "throws" | "slow",
+  behavior: "ok" | "broken-db" | "broken-config" | "throws" | "slow" | "thin-refusal",
 ): string {
  // "slow": healthy engine on a cold pooler connection (#1964) — sleeps past
  // the (test-lowered) probe timeout, then would answer fine.
@@ -127,7 +134,9 @@ exit 0
        ? 'echo "Error: malformed config.json at ~/.gbrain/config.json" >&2'
        : behavior === "throws"
          ? 'echo "unexpected gbrain failure" >&2'
-          : "";
+          : behavior === "thin-refusal"
+            ? 'echo "Error: gbrain sources is not routable to the remote brain (thin-client of https://brain.example.com/mcp)" >&2'
+            : "";
  const exitCode = behavior === "ok" ? 0 : 1;
  return `#!/bin/sh
 if [ "$1" = "--version" ]; then
@@ -432,3 +441,72 @@ describe("lib/gbrain-local-status — cache behavior", () => {
    }
  });
 });
+
+// ---------------------------------------------------------------------------
+// #2051: thin-client classification + the end-to-end --is-ok gate
+// ---------------------------------------------------------------------------
+
+describe("lib/gbrain-local-status — thin-client (#2051)", () => {
+  let env: FakeEnv | null = null;
+  let restoreEnv: (() => void) | null = null;
+
+  afterEach(() => {
+    if (restoreEnv) restoreEnv();
+    if (env) env.cleanup();
+    env = null;
+    restoreEnv = null;
+  });
+
+  it("returns 'thin-client' when config carries gbrain's remote_mcp marker (pre-probe, no engine call)", () => {
+    // The fake gbrain would answer "ok" if probed — proving the marker is
+    // read from config BEFORE any probe (zero network, no error-string
+    // dependence).
+    env = makeEnv({ withGbrain: true, gbrainBehavior: "ok", thinClientConfig: true });
+    restoreEnv = applyEnv(env);
+    expect(localEngineStatus({ noCache: true })).toBe("thin-client");
+  });
+
+  it("returns 'thin-client' via the stderr refusal fallback when the config marker is unreadable", () => {
+    // Regular (non-thin) config on disk, but gbrain itself refuses with the
+    // dispatch-guard message — the catch-path backstop.
+    env = makeEnv({ withGbrain: true, gbrainBehavior: "thin-refusal", withConfig: true });
+    restoreEnv = applyEnv(env);
+    expect(localEngineStatus({ noCache: true })).toBe("thin-client");
+  });
+
+  // The eng-review 3A tripwire: the END-TO-END gate, not just the classifier
+  // return. --is-ok drives setup:1299 and gstack-config gbrain-refresh — this
+  // exit code is what decides whether brain-aware blocks render for a
+  // thin-client user (the #2051 report).
+  it("--is-ok exits 0 on a thin-client fixture (end-to-end gate)", () => {
+    env = makeEnv({ withGbrain: true, gbrainBehavior: "ok", thinClientConfig: true });
+    const detectBin = join(import.meta.dir, "..", "bin", "gstack-gbrain-detect");
+    const bunDir = dirname(process.execPath);
+    const r = spawnSync(detectBin, ["--is-ok"], {
+      encoding: "utf-8",
+      env: {
+        HOME: env.home,
+        PATH: `${env.bindir}:${bunDir}:/usr/bin:/bin`,
+        GSTACK_HOME: env.gstackHome,
+        GSTACK_DETECT_NO_CACHE: "1",
+      },
+    });
+    expect(r.status).toBe(0);
+  });
+
+  it("--is-ok still exits 1 on broken-config (thin-client did not widen the gate)", () => {
+    env = makeEnv({ withGbrain: true, gbrainBehavior: "broken-config", withConfig: true });
+    const detectBin = join(import.meta.dir, "..", "bin", "gstack-gbrain-detect");
+    const bunDir = dirname(process.execPath);
+    const r = spawnSync(detectBin, ["--is-ok"], {
+      encoding: "utf-8",
+      env: {
+        HOME: env.home,
+        PATH: `${env.bindir}:${bunDir}:/usr/bin:/bin`,
+        GSTACK_HOME: env.gstackHome,
+        GSTACK_DETECT_NO_CACHE: "1",
+      },
+    });
+    expect(r.status).toBe(1);
+  });
+});
@@ -208,6 +208,61 @@ describe('gbrain_mcp_mode — Tier 3: ~/.claude.json jq read', () => {
    );
    expect(runDetect().json.gbrain_mcp_mode).toBe('none');
  });
+
+  // #2051 name generalization: a gbrain server registered under a variant
+  // name still counts. Identification order: url-match against the config's
+  // remote_mcp.mcp_url (deterministic — gbrain mounts at generic /mcp so
+  // URL-path heuristics are impossible) → name pattern gbrain[-_]* → stdio
+  // command token.
+  test('server named gbrain-remote (name pattern) → remote-http', () => {
+    fs.writeFileSync(
+      path.join(tmpHome, '.claude.json'),
+      JSON.stringify({
+        mcpServers: { 'gbrain-remote': { type: 'url', url: 'https://brain.corp.example/mcp' } },
+      })
+    );
+    expect(runDetect().json.gbrain_mcp_mode).toBe('remote-http');
+  });
+
+  test('arbitrarily-named server whose url matches config remote_mcp.mcp_url → remote-http', () => {
+    fs.mkdirSync(path.join(tmpHome, '.gbrain'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, '.gbrain', 'config.json'),
+      JSON.stringify({ remote_mcp: { mcp_url: 'https://team-brain.example.com/mcp' } })
+    );
+    fs.writeFileSync(
+      path.join(tmpHome, '.claude.json'),
+      JSON.stringify({
+        mcpServers: { 'our-team-brain': { type: 'url', url: 'https://team-brain.example.com/mcp' } },
+      })
+    );
+    expect(runDetect().json.gbrain_mcp_mode).toBe('remote-http');
+  });
+
+  test('unrelated server with a non-matching url does NOT false-positive → none', () => {
+    fs.mkdirSync(path.join(tmpHome, '.gbrain'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, '.gbrain', 'config.json'),
+      JSON.stringify({ remote_mcp: { mcp_url: 'https://team-brain.example.com/mcp' } })
+    );
+    fs.writeFileSync(
+      path.join(tmpHome, '.claude.json'),
+      JSON.stringify({
+        mcpServers: { linear: { type: 'url', url: 'https://mcp.linear.app/mcp' } },
+      })
+    );
+    expect(runDetect().json.gbrain_mcp_mode).toBe('none');
+  });
+
+  test('stdio server with gbrain in the command token → local-stdio', () => {
+    fs.writeFileSync(
+      path.join(tmpHome, '.claude.json'),
+      JSON.stringify({
+        mcpServers: { 'my-brain': { type: 'stdio', command: '/usr/local/bin/gbrain' } },
+      })
+    );
+    expect(runDetect().json.gbrain_mcp_mode).toBe('local-stdio');
+  });
 });

 describe('gbrain_mcp_mode — no info anywhere', () => {