From 4d6150b811df3df53a09bbd45e93a4c0729b2dff Mon Sep 17 00:00:00 2001 From: norvalbv Date: Fri, 20 Nov 2026 03:59:04 +0000 Subject: [PATCH 1/2] DEGRADED codebase-MCP remedy prints a runnable registration command (sc-7321) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Why About 300 `gate_degraded` rows a day carry the cause "MCP codebase unavailable (missing from the trusted MCP registry)". On those ships, reviewers still return verdicts, but they have no codebase search. This is not an outage. `~/.claude.json` registers the `codebase` server (`search-code serve`) only for frink, qavis and frink-oss. The "October spike" is just when sc-2837 started recording this cause (2026-10-01). | repo | registry-missing rows (Oct + Nov) | |---|---| | devkit | 8,547 | | claude-usage-dashboard | 1,851 | | sonar | 401 | | frink (registered) | 0 | The remedy printed today is prose, and in 7 weeks nobody acted on it. `devkit init --search-code` never says the server needs registering. ## What changes - **The DEGRADED line ends with a command you can paste.** It is built by `codebaseRegisterCommand` in the new `gate-engine/judge/mcp/registration-remedy.mts` and used by `registryRemedy` in `profile.mts`. For this repo it prints: ``` cd '/Users/benji/Desktop/Personal and learning/devkit' && env -u CLAUDE_CONFIG_DIR claude mcp add -s local codebase -e SEMANTIC_SEARCH_ROOT='/Users/benji/Desktop/Personal and learning/devkit' -- search-code serve ``` - **Primary checkout.** `codebaseRegisterCommand` targets the primary checkout. `profile.mts` already reads that checkout's project row from linked gate worktrees. Paths are shell-quoted. - **The root is pinned.** frink, qavis and frink-oss all register this way and show 0 DEGRADED rows. Gate worktrees live under `$TMPDIR`, and an overlay consumer git-excludes `search-code.config.json`. So an unpinned server would walk up from the worktree, find no config, and clear DEGRADED while searching nothing. - **`env -u CLAUDE_CONFIG_DIR`.** When that variable is set, as in a Frink session, `claude` writes `$CLAUDE_CONFIG_DIR/.claude.json`. devkit's registry never reads that file. - **`claude mcp add` does not clear `disabledMcpServers`.** The probe showed this, so the remedy names that extra step. - **An explicit `DEVKIT_JUDGE_MCP_CONFIG` registry gets no `claude` command.** The command would write `~/.claude.json`, not that registry. - **A repo with no `search-code.config.json` is told to opt in first.** DEGRADED checks only that the server is registered, not that search works. A bare registration would clear it while reviewers had nothing to search (sonar, the dashboard). - **`devkit init --search-code` prints the same command for the primary checkout.** When it runs from a linked worktree whose primary checkout has not opted in, it prints no command and says to run init there too, since gates register and search the primary checkout. - The warning's dedupe key now includes the checkout, so a second checkout with the same registry state still prints its own command. - A decision note on `judge-mcp-profiles` records all of the above, plus why one user-scope registration and a `doctor` row were rejected. ## Proof - **Probe 1: `claude -p --strict-mcp-config`** with a stdio server that logs its cwd. The server starts in the judge's cwd. - **Probe 2: `claude mcp add -s local`**, run from a linked worktree subdirectory with a temp `HOME`. - It keys the row by the main worktree root. - It leaves `disabledMcpServers` unchanged. - With `CLAUDE_CONFIG_DIR` set, it writes into that directory instead of `HOME`. - **End to end.** I ran the exact printed command with `CLAUDE_CONFIG_DIR` pointing at a decoy directory: - the decoy stayed empty; - `$HOME/.claude.json` got the pinned row; - devkit's resolver then found `codebase` from a linked worktree, with `root` = the primary checkout. - **Tests:** 144 tests pass across 6 files (`registration-remedy`, `mcp-profile`, `judge-exec-telemetry`, `mcp-degraded`, `completeness-mcp-degraded`, `install-search-code`). - The command test runs the printed command through `/bin/sh` against a stub `claude`. It checks the cwd, the pinned root (a path with spaces and a `'`), that `CLAUDE_CONFIG_DIR` is unset, and the argv. - **Revert proofs:** - The old `registryRemedy` text fails 4 mcp-profile tests. - Dropping `primaryCheckout` from init fails the linked-worktree test. - **Coverage:** 18/18 added lines covered. - **Line count:** `profile.mts` went from 499 to 497 lines. - **Dry run:** `devkit ship --dry-gates` passed. ## Owner steps (the agent did not write `~/.claude.json`); leave sc-7321 open until step 4 1. In devkit, run the printed command. 2. Refresh devkit's primary index: `search-code index` in the primary checkout. It was last refreshed 2026-10-01, and the pinned root makes reviewers search it. 3. For claude-usage-dashboard and sonar: `devkit init --search-code`, `search-code index`, then the printed command. 4. Seven days later, re-read the `gate_degraded` rows with the cause "missing from the trusted MCP registry". The acceptance criterion is near zero. ## Embeddings share (acceptance item c) The "embeddings endpoint unreachable" rows fell from about 560 in October to about 10 in November. The drop matches sc-4215 (2026-10-08), which approves codex MCP calls. Before that fix, a refused MCP call sent codex judges to a sandboxed shell, where the localhost fetch failed. What remains is small, so it gets its own follow-up and no fix here. ## Follow-ups (not in this PR) - A ship's worktree index refresh never writes the primary checkout's index, so the pinned root searches a stale index until someone re-indexes. (devkit, bug) - Should DEGRADED fire at all for repos that never opted into search-code? That would change the sc-2837 ruling. (devkit, feature) - DEGRADED checks only that the server is registered, not that search works. A health probe would catch a missing binary or an empty index. (devkit, feature) - The remaining "embeddings endpoint unreachable" rows. (devkit, bug) - The search-code README's registration example. (search-code, chore) - Already tracked as autonomous report a9570be1: Frink says not to edit `~/.claude.json`, but devkit's judges read it. Reviewer notes declined: - correctness-reviewer, `profile.mts:271` (`projectRoots: []` makes `roots.at(-1)` fall back to cwd): no production caller passes an empty list (only the eval harness passes one root), and an empty list reads no project row, so cwd is the only registration site. Story: sc-7321 🤖 Generated with [Claude Code](https://claude.com/claude-code) Complete against acceptance criteria: NO — owner registration and 7-day gate_degraded re-read: needs the owner (the agent may not write ~/.claude.json, and the check is time-gated) --- cli/__tests__/install-search-code.test.mts | 48 +++++++++++- cli/lib/install/install-search-code.mts | 19 ++++- .../judge/mcp/registration-remedy.mjs | 31 ++++++++ docs/decisions/judge-mcp-profiles.md | 1 + .../judge/__tests__/mcp-profile.test.mts | 46 ++++++++++- .../__tests__/registration-remedy.test.mts | 77 +++++++++++++++++++ gate-engine/judge/mcp/profile.mts | 23 +++--- gate-engine/judge/mcp/registration-remedy.mts | 34 ++++++++ 8 files changed, 263 insertions(+), 16 deletions(-) create mode 100644 dist/gate-engine/judge/mcp/registration-remedy.mjs create mode 100644 gate-engine/judge/__tests__/registration-remedy.test.mts create mode 100644 gate-engine/judge/mcp/registration-remedy.mts diff --git a/cli/__tests__/install-search-code.test.mts b/cli/__tests__/install-search-code.test.mts index b0b2cc1fb..18c19054f 100644 --- a/cli/__tests__/install-search-code.test.mts +++ b/cli/__tests__/install-search-code.test.mts @@ -1,8 +1,17 @@ -import fs, { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { execFileSync } from 'node:child_process'; +import fs, { + existsSync, + mkdirSync, + readFileSync, + realpathSync, + rmSync, + writeFileSync, +} from 'node:fs'; import { syncBuiltinESMExports } from 'node:module'; import { join } from 'node:path'; import { DatabaseSync } from 'node:sqlite'; import { afterEach, describe, expect, it, vi } from 'vitest'; +import { codebaseRegisterCommand } from '../../gate-engine/judge/mcp/registration-remedy.mts'; import { DEFAULT_INDEX_COMMAND, installSearchCode } from '../lib/install/install-search-code.mts'; import { tmpRepos } from './_helpers.mts'; @@ -92,6 +101,43 @@ describe('search-code opt-in component', () => { log.mockRestore(); }); + it('prints the command that registers the codebase MCP server for this repo', () => { + const root = tmpRepo(); + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + installSearchCode(root, false); + expect(log.mock.calls.flat()).toContain(` ${codebaseRegisterCommand(realpathSync(root))}`); + log.mockRestore(); + }); + + it.each([ + ['not opted in: it says to opt the primary in, and prints no command', false], + ['opted in: it registers the primary checkout, which outlives the worktree', true], + ])('run from a linked worktree whose primary is %s', (_name, primaryOptedIn) => { + const root = tmpRepo(); + const worktree = `${root}-wt`; + const git = (...args: string[]) => execFileSync('git', args, { cwd: root }); + git('init', '-q'); + git('-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'base'); + git('worktree', 'add', '-q', '--detach', worktree); + if (primaryOptedIn) writeFileSync(join(root, 'search-code.config.json'), '{}\n'); + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + try { + installSearchCode(worktree, false); + const out = log.mock.calls.flat().map(String); + const primary = realpathSync(root); + expect(out.find((l) => l.includes('claude mcp add'))).toBe( + primaryOptedIn ? ` ${codebaseRegisterCommand(primary)}` : undefined, + ); + if (!primaryOptedIn) + expect(out).toContain( + ` ℹ gate reviewers search the primary checkout: run this there too, in ${primary}`, + ); + } finally { + log.mockRestore(); + rmSync(worktree, { recursive: true, force: true }); + } + }); + it('is off by default (no --search-code → no config)', () => { const root = tmpRepo(); devkit(root, 'init', '--stack', 'generic', '--yes'); diff --git a/cli/lib/install/install-search-code.mts b/cli/lib/install/install-search-code.mts index 1a2ed6551..40fde6005 100644 --- a/cli/lib/install/install-search-code.mts +++ b/cli/lib/install/install-search-code.mts @@ -10,14 +10,19 @@ import { appendFileSync, existsSync, readFileSync, realpathSync, rmSync, statSyn import { join } from 'node:path'; import { indexToInspect, + primaryCheckout, usableChunksAt, } from '../../../gate-engine/co-occurrence/index-refresh.mts'; +import { + codebaseRegisterCommand, + SEARCH_CODE_CONFIG, +} from '../../../gate-engine/judge/mcp/registration-remedy.mts'; import { withGitignoreLock } from './gitignore-cache.mts'; import { writeFileAtomic } from '../atomic-write.mts'; import { type CheckResult, check } from '../doctor/check-result.mts'; import { readJson, writeIfAbsent } from '../fs-helpers.mts'; -export const SEARCH_CODE_CONFIG = 'search-code.config.json'; +export { SEARCH_CODE_CONFIG }; const INDEX_LINE = '.search-code/'; const INDEX_PATH = '.search-code/index.db'; /** What an overlay install git-excludes instead of writing the tracked `.gitignore`. */ @@ -159,6 +164,18 @@ export function installSearchCode( console.log(' ℹ needs the search-code engine + Ollama. Install once, then index this repo:'); console.log(' bun add -g git+ssh://git@github.com/norvalbv/search-code.git'); console.log(' search-code index'); + const primary = realpathSync(primaryCheckout(cwd) ?? cwd); + // Gates register and search the primary checkout, so a linked worktree's opt-in alone is not enough. + if (primary !== realpathSync(cwd) && !existsSync(join(primary, SEARCH_CODE_CONFIG))) { + console.log( + ` ℹ gate reviewers search the primary checkout: run this there too, in ${primary}`, + ); + return; + } + console.log( + ' ℹ gate reviewers search the index only once the codebase MCP server is registered (skip if it is):', + ); + console.log(` ${codebaseRegisterCommand(primary)}`); } // clean reversal: remove the devkit-written opt-in config. The `.search-code/` gitignore line is diff --git a/dist/gate-engine/judge/mcp/registration-remedy.mjs b/dist/gate-engine/judge/mcp/registration-remedy.mjs new file mode 100644 index 000000000..be6d4629b --- /dev/null +++ b/dist/gate-engine/judge/mcp/registration-remedy.mjs @@ -0,0 +1,31 @@ +import { existsSync, realpathSync } from 'node:fs'; +import { homedir } from 'node:os'; +import path from 'node:path'; +import { shellWord } from '../../review/valve/shell-word.mjs'; +/** search-code indexes a repo only when this file sits at its root (the engine's opt-in gate). */ +export const SEARCH_CODE_CONFIG = 'search-code.config.json'; +/** Registers the codebase server for `root` in ~/.claude.json, whatever CLAUDE_CONFIG_DIR says. The + * root is pinned: a gate worktree under $TMPDIR may hold no search-code config to walk up to. */ +export function codebaseRegisterCommand(root) { + const at = shellWord(root); + return `cd ${at} && env -u CLAUDE_CONFIG_DIR claude mcp add -s local codebase -e SEMANTIC_SEARCH_ROOT=${at} -- search-code serve`; +} +function isClaudeRegistry(registryPath) { + const file = path.join(homedir(), '.claude.json'); + try { + return realpathSync(file) === registryPath; + } + catch { + return file === registryPath; + } +} +/** How to restore codebase search for `root`. A repo search-code never indexed is told to opt in + * first, since a bare registration clears DEGRADED while reviewers still have nothing to search. */ +export function codebaseRemedy(root, registryPath) { + const fix = isClaudeRegistry(registryPath) + ? `run \`${codebaseRegisterCommand(root)}\`, and remove \`codebase\` from this project's \`disabledMcpServers\` in ${registryPath} if it is listed there` + : `add the \`codebase\` MCP server for this project in ${registryPath}, or remove it from that project's \`disabledMcpServers\``; + if (!existsSync(path.join(root, SEARCH_CODE_CONFIG))) + return `opt this repo into search-code first (\`devkit init --search-code\`, then \`search-code index\`), then ${fix}`; + return fix; +} diff --git a/docs/decisions/judge-mcp-profiles.md b/docs/decisions/judge-mcp-profiles.md index cdde94e07..64fbba655 100644 --- a/docs/decisions/judge-mcp-profiles.md +++ b/docs/decisions/judge-mcp-profiles.md @@ -31,3 +31,4 @@ created: 2026-08-15 - 2026-10-15 — sc-5134: codebase capability stays on the registry path; claude judges get no search-code Bash grant. A missing codebase server marks every PASS DEGRADED regardless of what the judge's shell retrieved (cascade/reviewer.mts sets mcpDegraded from the profile cause), so a shell grant could not clear it, and most observed fallback calls were piped or chained, which a prefix rule never approves. It would also add a PATH-resolved retrieval channel outside the trusted registry. Instead the brief tells a headless commit-guard to skip the shell fallback, the DEGRADED warn line names the remedy (add or re-enable the codebase server for the project in the registry, or set DEVKIT_JUDGE_MCP_CONFIG), and commit-guard gains only Bash(guard-dup-allowlist check:*), a read-only lookup; check-clone is skipped headless and stays ungranted. - 2026-10-18 — sc-5156: codex gate judges no longer run in the owner's CODEX_HOME. codex injects $CODEX_HOME/AGENTS.override.md or AGENTS.md as user instructions on every turn (codex-rs codex-home/src/instructions/mod.rs, loaded unconditionally from core/src/agents_md_manager.rs); --ignore-user-config only blanks config.toml and no flag disables it (openai/codex#5983 NOT_PLANNED). Measured with the free codex debug prompt-input on codex-cli 0.162.1: a sentinel global AGENTS.md reached the prompt even with -c project_doc_max_bytes=0, and the owner's HOME-relative ~/.agents/skills catalog also reached it (33,919 bytes before, 11,191 after). Every codex judge (read-only and workspace-write) now gets CODEX_HOME=~/.devkit/codex-judge-home, prepared by gate-engine/judge/codex/home.mts, holding only an auth.json symlink to the owner's auth file, plus -c skills.include_instructions=false. Upstream names a separate CODEX_HOME as the isolation unit (openai/codex#15410). The symlink works because codex rewrites auth.json in place (login/src/auth/storage.rs), so refreshed tokens land in the owner's file. A regular auth.json in the judge home is left alone (a login landing between the lstat and the rename can still be replaced; the window is microseconds), and the home never links to itself. Rejected: copying auth.json (forks single-use refresh tokens, #15410); a per-spawn tmpdir home (writable from workspace-write judge shells, and it re-fetches about 1.7 MB of caches per spawn); overriding HOME (breaks git, gh, the login shell and the keychain). Codex bench baselines recorded before this change carried owner context. codex app-server quota probes (rate-limits.mts) still use the owner home on purpose. - 2026-10-19 — sc-4645: the sc-4709 Revisit-when fired. Codex gate judges are now refused mechanically, not by instruction: judgeCliFor passes every codex judge a PreToolUse hook (-c hooks.PreToolUse) and trusts it per run through an inline -c hooks.state trusted_hash computed by devkit (codex reads hook trust from the session-flags layer), so --ignore-user-config and --ignore-rules stay and the owner's ~/.codex/hooks.json stays untrusted. --dangerously-bypass-hook-trust was rejected because it also runs those owner hooks. The hook (gate-engine/judge/codex/tool-gate-hook.mts) parses each Bash command with unbash and allows only a read-only list matching the Claude judge grant: shell reads, git read subcommands without -c/--output/--ext-diff, sed -n print ranges, and node on the granted checklist script; any parse error, expansion, assignment, redirect other than to /dev/null, compound block or other tool is denied (apply_patch included, which closes the .claude write residual; MCP tools stay allowed). Deny is exit 2 and the exit code starts at 2, because codex runs the call on any other hook outcome. Verified live on codex-cli 0.150.0, 0.159.3 and 0.162.1. Refusals are ledgered per codex session and reach judge_exec as permission_denials, so codex spawns are now measured (the 2026-10-13 review-gate-in-chain wording that codex keeps the bare reason no longer holds). A run whose executed commands outnumber the ledger's allows prints 'codex tool gate inactive' and emits gate_degraded without changing the verdict; that catches a future hook-schema change and managed-only hook configs. A checklist grant matches only its exact path, cd and git -C only into the confined repository root, and unquoted globs are denied (they expand to names the reviewed diff controls, such as a file named --output=x), so a lookalike script the reviewed diff adds is not reachable that way. Residuals: exec_command's model-chosen workdir and shell (such as pwsh) are not in the hook payload, so a relative grant could still resolve from another directory, and pwsh is mitigated only by denying unquoted braces. Rejected: execpolicy prefix rules (not hermetic, leaky) and app-server host approvals (replaces the spawn seam for one family). +- 2026-11-20 — sc-7321: the DEGRADED codebase remedy is now a runnable command, cd && env -u CLAUDE_CONFIG_DIR claude mcp add -s local codebase -e SEMANTIC_SEARCH_ROOT= -- search-code serve, also printed by init --search-code (gate-engine/judge/mcp/registration-remedy.mts). The registry gap behind about 300 gate_degraded rows a day was devkit, claude-usage-dashboard and sonar never being registered; the October rise is when sc-2837 started recording the cause, not an outage. The command cds to the primary checkout because local scope keys the row by the session's path, and projectCandidates reads the primary row from a linked worktree. It pins SEMANTIC_SEARCH_ROOT to the primary, the shape frink, qavis and frink-oss run with zero DEGRADED rows: the stdio server starts in the judge's cwd (probed under --strict-mcp-config), and a ship gate worktree under TMPDIR has no search-code config to walk up to when an overlay consumer git-excludes it. It runs claude through env -u CLAUDE_CONFIG_DIR, since a set CLAUDE_CONFIG_DIR (as in a Frink session) makes claude write a file this registry never reads; probed, claude mcp add keys local scope by the main worktree root and leaves disabledMcpServers untouched, so the remedy names that step and an explicit DEVKIT_JUDGE_MCP_CONFIG registry gets no claude command. A repo with no search-code.config.json is told to opt in first, because DEGRADED measures registration, not retrieval: a bare registration would clear it while reviewers have nothing to search. Rejected: one unpinned user-scope registration, which would clear DEGRADED for repos with no index; a devkit doctor row, a third copy of a remedy every ship already prints. diff --git a/gate-engine/judge/__tests__/mcp-profile.test.mts b/gate-engine/judge/__tests__/mcp-profile.test.mts index 7994be8af..8ef56ca85 100644 --- a/gate-engine/judge/__tests__/mcp-profile.test.mts +++ b/gate-engine/judge/__tests__/mcp-profile.test.mts @@ -23,14 +23,15 @@ import { spawnDegradedCause, withNamedAgentMcpTools, } from '../mcp/profile.mts'; +import { codebaseRegisterCommand, codebaseRemedy } from '../mcp/registration-remedy.mts'; const root = mkdtempSync(path.join(tmpdir(), 'judge-mcp-profile-')); const repo = path.join(root, 'repo'); const registry = path.join(root, 'registry.json'); mkdirSync(repo); -const remedy = (registryPath: string) => - ` — to restore it, add or re-enable the \`codebase\` MCP server for this project in ${realpathSync(registryPath)}, or point DEVKIT_JUDGE_MCP_CONFIG at a registry that defines it`; +const remedy = (registryPath: string, at = repo) => + ` — to restore it, ${codebaseRemedy(realpathSync(at), realpathSync(registryPath))}, or point DEVKIT_JUDGE_MCP_CONFIG at a registry that defines it`; interface RegistryFixtureOverrides { projects?: { @@ -326,6 +327,47 @@ describe('missing-server resolution and reporting (sc-2837)', () => { ]); }); + it('the remedy registers codebase at the primary checkout, not the linked worktree', () => { + spyStderr(); + const home = mkdtempSync(path.join(root, 'home-')); + const registryPath = path.join(home, '.claude.json'); + writeFileSync(registryPath, '{"mcpServers":{}}', { mode: 0o600 }); + vi.stubEnv('HOME', home); + vi.stubEnv('DEVKIT_JUDGE_MCP_CONFIG', undefined); + const worktree = mkdtempSync(path.join(root, 'worktree-')); + writeFileSync(path.join(repo, 'search-code.config.json'), '{}\n'); + try { + const resolution = judgeMcpMissingServers(namedAgentMcpProfile(), { + cwd: worktree, + projectRoots: [worktree, repo], + }); + reportMissingMcpServers(resolution, ['correctness-reviewer']); + expect(stderr[0].endsWith(remedy(registryPath, repo))).toBe(true); + } finally { + rmSync(path.join(repo, 'search-code.config.json')); + vi.unstubAllEnvs(); + } + expect(stderr[0]).toContain(`run \`${codebaseRegisterCommand(realpathSync(repo))}\``); + expect(stderr[0]).not.toContain(realpathSync(worktree)); + }); + + it('a second checkout with the same registry state still prints its own command', () => { + spyStderr(); + const registryPath = withServers('context7', 'autonomous_bugs'); + const other = mkdtempSync(path.join(root, 'other-')); + for (const at of [repo, other]) + reportMissingMcpServers( + judgeMcpMissingServers(namedAgentMcpProfile(), { + cwd: at, + registryPath, + projectRoots: [at], + }), + ['correctness-reviewer'], + ); + expect(stderr).toHaveLength(2); + expect(stderr[1].endsWith(remedy(registryPath, other))).toBe(true); + }); + it('a registry edited mid-process to lose a DIFFERENT server warns again (new state, new key)', () => { spyStderr(); const registryPath = withServers('codebase', 'context7'); diff --git a/gate-engine/judge/__tests__/registration-remedy.test.mts b/gate-engine/judge/__tests__/registration-remedy.test.mts new file mode 100644 index 000000000..6db02f48c --- /dev/null +++ b/gate-engine/judge/__tests__/registration-remedy.test.mts @@ -0,0 +1,77 @@ +import { spawnSync } from 'node:child_process'; +import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { afterAll, afterEach, describe, expect, it, vi } from 'vitest'; +import { + codebaseRegisterCommand, + codebaseRemedy, + SEARCH_CODE_CONFIG, +} from '../mcp/registration-remedy.mts'; + +const base = mkdtempSync(path.join(tmpdir(), 'registration-remedy-')); +const home = path.join(base, 'home'); +mkdirSync(home); +const claudeRegistry = path.join(realpathSync(home), '.claude.json'); +writeFileSync(claudeRegistry, '{}'); +afterAll(() => rmSync(base, { recursive: true, force: true })); +afterEach(() => vi.unstubAllEnvs()); + +function repoAt(name: string, optedIn: boolean): string { + const dir = path.join(base, name); + mkdirSync(dir); + if (optedIn) writeFileSync(path.join(dir, SEARCH_CODE_CONFIG), '{}\n'); + return dir; +} + +describe('codebaseRegisterCommand', () => { + it('pastes as-is: a root with spaces and a quote cds, pins, and drops CLAUDE_CONFIG_DIR', () => { + const dir = repoAt("Personal and learning's devkit", true); + const bin = path.join(base, 'bin'); + mkdirSync(bin); + const stub = 'pwd -P; printf "%s\\n" "${CLAUDE_CONFIG_DIR-unset}" "$@"'; + writeFileSync(path.join(bin, 'claude'), `#!/bin/sh\n${stub}\n`, { mode: 0o755 }); + const out = spawnSync('/bin/sh', ['-c', codebaseRegisterCommand(dir)], { + encoding: 'utf8', + env: { ...process.env, PATH: `${bin}:${process.env.PATH}`, CLAUDE_CONFIG_DIR: '/decoy' }, + }).stdout; + expect(out.trimEnd().split('\n')).toEqual([ + realpathSync(dir), + 'unset', + ...['mcp', 'add', '-s', 'local', 'codebase', '-e', `SEMANTIC_SEARCH_ROOT=${dir}`], + ...['--', 'search-code', 'serve'], + ]); + }); + + it('writes ~/.claude.json even under CLAUDE_CONFIG_DIR, with the name before -e', () => { + expect(codebaseRegisterCommand('/repo')).toBe( + 'cd /repo && env -u CLAUDE_CONFIG_DIR claude mcp add -s local codebase -e SEMANTIC_SEARCH_ROOT=/repo -- search-code serve', + ); + }); +}); + +describe('codebaseRemedy', () => { + it('a repo search-code never indexed opts in before it registers', () => { + vi.stubEnv('HOME', home); + const dir = repoAt('plain', false); + expect(codebaseRemedy(dir, claudeRegistry)).toMatch( + /^opt this repo into search-code first \(`devkit init --search-code`, then `search-code index`\), then run `cd /, + ); + }); + + it('an opted-in repo gets the command, plus the disabledMcpServers step it does not cover', () => { + vi.stubEnv('HOME', home); + const dir = repoAt('opted', true); + expect(codebaseRemedy(dir, claudeRegistry)).toBe( + `run \`${codebaseRegisterCommand(dir)}\`, and remove \`codebase\` from this project's \`disabledMcpServers\` in ${claudeRegistry} if it is listed there`, + ); + }); + + it('an explicit registry gets no claude mcp command, which would write ~/.claude.json instead', () => { + vi.stubEnv('HOME', home); + const dir = repoAt('explicit', true); + expect(codebaseRemedy(dir, '/etc/judge-mcp.json')).toBe( + "add the `codebase` MCP server for this project in /etc/judge-mcp.json, or remove it from that project's `disabledMcpServers`", + ); + }); +}); diff --git a/gate-engine/judge/mcp/profile.mts b/gate-engine/judge/mcp/profile.mts index 4bbe7aa98..46cf137a8 100644 --- a/gate-engine/judge/mcp/profile.mts +++ b/gate-engine/judge/mcp/profile.mts @@ -20,6 +20,7 @@ import { type JsonValue, } from '../../comment-firewall/types.mts'; import { withoutGitEnv } from '../judge-isolation.mts'; +import { codebaseRemedy } from './registration-remedy.mts'; const BASELINE_SERVER_NAMES = ['codebase', 'context7', 'autonomous_bugs'] as const; // Claude Code matches server-wide MCP permissions with the explicit `__*` suffix. @@ -228,6 +229,8 @@ export interface JudgeMcpResolution { missing: string[]; /** One warning identity per registry state, shared by every caller in this process. */ warnKey: string; + /** Where a registration belongs: the primary checkout, else cwd (read registries only). */ + root?: string; } function resolveJudgeMcp( @@ -256,21 +259,17 @@ function resolveJudgeMcp( missing: [...serverNames], warnKey: `registry-json:${registryPath}`, }; - const servers = - serverNames.length === 0 - ? {} - : selectedServers( - registry, - serverNames, - projectCandidates(options.cwd, env, options.projectRoots), - ); + const roots = projectCandidates(options.cwd, env, options.projectRoots); + const servers = serverNames.length === 0 ? {} : selectedServers(registry, serverNames, roots); const missing = serverNames.filter((name) => !Object.hasOwn(servers, name)); + const root = roots.at(-1) ?? options.cwd; return { kind: 'resolved', registryPath, servers, missing, - warnKey: `missing:${registryPath}:${missing.join(',')}`, + warnKey: `missing:${registryPath}:${root}:${missing.join(',')}`, + root, }; } @@ -296,9 +295,9 @@ function missingReason(resolution: JudgeMcpResolution): string { /** How to restore a verdict-bearing server a readable registry lacks; empty otherwise. */ function registryRemedy(resolution: JudgeMcpResolution): string { - const lost = verdictBearingMissing(resolution).join(', '); - if (resolution.kind !== 'resolved' || !lost) return ''; - return ` — to restore it, add or re-enable the \`${lost}\` MCP server for this project in ${resolution.registryPath}, or point ${REGISTRY_ENV} at a registry that defines it`; + const { kind, registryPath, root } = resolution; + if (kind !== 'resolved' || !root || verdictBearingMissing(resolution).length === 0) return ''; + return ` — to restore it, ${codebaseRemedy(root, registryPath)}, or point ${REGISTRY_ENV} at a registry that defines it`; } /** One-line cause a DEGRADED reviewer verdict carries, or undefined when nothing verdict-bearing is diff --git a/gate-engine/judge/mcp/registration-remedy.mts b/gate-engine/judge/mcp/registration-remedy.mts new file mode 100644 index 000000000..b89f07118 --- /dev/null +++ b/gate-engine/judge/mcp/registration-remedy.mts @@ -0,0 +1,34 @@ +import { existsSync, realpathSync } from 'node:fs'; +import { homedir } from 'node:os'; +import path from 'node:path'; +import { shellWord } from '../../review/valve/shell-word.mts'; + +/** search-code indexes a repo only when this file sits at its root (the engine's opt-in gate). */ +export const SEARCH_CODE_CONFIG = 'search-code.config.json'; + +/** Registers the codebase server for `root` in ~/.claude.json, whatever CLAUDE_CONFIG_DIR says. The + * root is pinned: a gate worktree under $TMPDIR may hold no search-code config to walk up to. */ +export function codebaseRegisterCommand(root: string): string { + const at = shellWord(root); + return `cd ${at} && env -u CLAUDE_CONFIG_DIR claude mcp add -s local codebase -e SEMANTIC_SEARCH_ROOT=${at} -- search-code serve`; +} + +function isClaudeRegistry(registryPath: string): boolean { + const file = path.join(homedir(), '.claude.json'); + try { + return realpathSync(file) === registryPath; + } catch { + return file === registryPath; + } +} + +/** How to restore codebase search for `root`. A repo search-code never indexed is told to opt in + * first, since a bare registration clears DEGRADED while reviewers still have nothing to search. */ +export function codebaseRemedy(root: string, registryPath: string): string { + const fix = isClaudeRegistry(registryPath) + ? `run \`${codebaseRegisterCommand(root)}\`, and remove \`codebase\` from this project's \`disabledMcpServers\` in ${registryPath} if it is listed there` + : `add the \`codebase\` MCP server for this project in ${registryPath}, or remove it from that project's \`disabledMcpServers\``; + if (!existsSync(path.join(root, SEARCH_CODE_CONFIG))) + return `opt this repo into search-code first (\`devkit init --search-code\`, then \`search-code index\`), then ${fix}`; + return fix; +} From bd920f942a6e0eb1a42aa9babb49e1085a1b4e57 Mon Sep 17 00:00:00 2001 From: norvalbv Date: Fri, 20 Nov 2026 04:24:20 +0000 Subject: [PATCH 2/2] DEGRADED codebase-MCP remedy prints a runnable registration command (sc-7321) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Why About 300 `gate_degraded` rows a day carry the cause "MCP codebase unavailable (missing from the trusted MCP registry)". On those ships, reviewers still return verdicts, but they have no codebase search. This is not an outage. `~/.claude.json` registers the `codebase` server (`search-code serve`) only for frink, qavis and frink-oss. The "October spike" is just when sc-2837 started recording this cause (2026-10-01). | repo | registry-missing rows (Oct + Nov) | |---|---| | devkit | 8,547 | | claude-usage-dashboard | 1,851 | | sonar | 401 | | frink (registered) | 0 | The remedy printed today is prose, and in 7 weeks nobody acted on it. `devkit init --search-code` never says the server needs registering. ## What changes - **The DEGRADED line ends with a command you can paste.** It is built by `codebaseRegisterCommand` in the new `gate-engine/judge/mcp/registration-remedy.mts` and used by `registryRemedy` in `profile.mts`. For this repo it prints: ``` cd '/Users/benji/Desktop/Personal and learning/devkit' && env -u CLAUDE_CONFIG_DIR claude mcp add -s local codebase -e SEMANTIC_SEARCH_ROOT='/Users/benji/Desktop/Personal and learning/devkit' -- search-code serve ``` - **Primary checkout.** `codebaseRegisterCommand` targets the primary checkout. `profile.mts` already reads that checkout's project row from linked gate worktrees. Paths are shell-quoted. - **The root is pinned.** frink, qavis and frink-oss all register this way and show 0 DEGRADED rows. Gate worktrees live under `$TMPDIR`, and an overlay consumer git-excludes `search-code.config.json`. So an unpinned server would walk up from the worktree, find no config, and clear DEGRADED while searching nothing. - **`env -u CLAUDE_CONFIG_DIR`.** When that variable is set, as in a Frink session, `claude` writes `$CLAUDE_CONFIG_DIR/.claude.json`. devkit's registry never reads that file. - **`claude mcp add` does not clear `disabledMcpServers`.** The probe showed this, so the remedy names that extra step. - **An explicit `DEVKIT_JUDGE_MCP_CONFIG` registry gets no `claude` command.** The command would write `~/.claude.json`, not that registry. - **A repo with no `search-code.config.json` is told to opt in first.** DEGRADED checks only that the server is registered, not that search works. A bare registration would clear it while reviewers had nothing to search (sonar, the dashboard). - **`devkit init --search-code` prints the same command for the primary checkout.** When it runs from a linked worktree whose primary checkout has not opted in, it prints no command and says to run init there too, since gates register and search the primary checkout. - The warning's dedupe key now includes the checkout, so a second checkout with the same registry state still prints its own command. - A decision note on `judge-mcp-profiles` records all of the above, plus why one user-scope registration and a `doctor` row were rejected. ## Proof - **Probe 1: `claude -p --strict-mcp-config`** with a stdio server that logs its cwd. The server starts in the judge's cwd. - **Probe 2: `claude mcp add -s local`**, run from a linked worktree subdirectory with a temp `HOME`. - It keys the row by the main worktree root. - It leaves `disabledMcpServers` unchanged. - With `CLAUDE_CONFIG_DIR` set, it writes into that directory instead of `HOME`. - **End to end.** I ran the exact printed command with `CLAUDE_CONFIG_DIR` pointing at a decoy directory: - the decoy stayed empty; - `$HOME/.claude.json` got the pinned row; - devkit's resolver then found `codebase` from a linked worktree, with `root` = the primary checkout. - **Tests:** 144 tests pass across 6 files (`registration-remedy`, `mcp-profile`, `judge-exec-telemetry`, `mcp-degraded`, `completeness-mcp-degraded`, `install-search-code`). - The command test runs the printed command through `/bin/sh` against a stub `claude`. It checks the cwd, the pinned root (a path with spaces and a `'`), that `CLAUDE_CONFIG_DIR` is unset, and the argv. - **Revert proofs:** - The old `registryRemedy` text fails 4 mcp-profile tests. - Dropping `primaryCheckout` from init fails the linked-worktree test. - **Coverage:** 18/18 added lines covered. - **Line count:** `profile.mts` went from 499 to 497 lines. - **Dry run:** `devkit ship --dry-gates` passed. ## Owner steps (the agent did not write `~/.claude.json`); leave sc-7321 open until step 4 1. In devkit, run the printed command. 2. Refresh devkit's primary index: `search-code index` in the primary checkout. It was last refreshed 2026-10-01, and the pinned root makes reviewers search it. 3. For claude-usage-dashboard and sonar: `devkit init --search-code`, `search-code index`, then the printed command. 4. Seven days later, re-read the `gate_degraded` rows with the cause "missing from the trusted MCP registry". The acceptance criterion is near zero. ## Embeddings share (acceptance item c) The "embeddings endpoint unreachable" rows fell from about 560 in October to about 10 in November. The drop matches sc-4215 (2026-10-08), which approves codex MCP calls. Before that fix, a refused MCP call sent codex judges to a sandboxed shell, where the localhost fetch failed. What remains is small, so it gets its own follow-up and no fix here. ## Follow-ups (not in this PR) - A ship's worktree index refresh never writes the primary checkout's index, so the pinned root searches a stale index until someone re-indexes. (devkit, bug) - Should DEGRADED fire at all for repos that never opted into search-code? That would change the sc-2837 ruling. (devkit, feature) - DEGRADED checks only that the server is registered, not that search works. A health probe would catch a missing binary or an empty index. (devkit, feature) - The remaining "embeddings endpoint unreachable" rows. (devkit, bug) - The search-code README's registration example. (search-code, chore) - Already tracked as autonomous report a9570be1: Frink says not to edit `~/.claude.json`, but devkit's judges read it. Reviewer notes declined: - correctness-reviewer, `profile.mts:266` (`root = roots.at(-1)` assumes the primary checkout comes last): `projectCandidates` fixes the production order as `[cwd, primary]` (`profile.mts:161`). The eval harness passes a single root. The end-to-end probe on the default path returned root = primary. - api-security-reviewer, `registration-remedy.mts:12` (control characters in a directory name could spoof how the command displays): the path is the user's own checkout, printed to their own terminal. It is quoted by the same `shellWord` that devkit's other paste commands (waive, resume) use, so changing it here alone would only make the two disagree. - correctness-reviewer, `profile.mts:271` (`projectRoots: []` makes `roots.at(-1)` fall back to cwd): no production caller passes an empty list (only the eval harness passes one root), and an empty list reads no project row, so cwd is the only registration site. Story: sc-7321 🤖 Generated with [Claude Code](https://claude.com/claude-code) Complete against acceptance criteria: NO — owner registration and 7-day gate_degraded re-read: needs the owner (the agent may not write ~/.claude.json, and the check is time-gated) --- cli/lib/install/install-search-code.mts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/cli/lib/install/install-search-code.mts b/cli/lib/install/install-search-code.mts index 40fde6005..44a5e9444 100644 --- a/cli/lib/install/install-search-code.mts +++ b/cli/lib/install/install-search-code.mts @@ -164,8 +164,12 @@ export function installSearchCode( console.log(' ℹ needs the search-code engine + Ollama. Install once, then index this repo:'); console.log(' bun add -g git+ssh://git@github.com/norvalbv/search-code.git'); console.log(' search-code index'); + printCodebaseRegistration(cwd); +} + +/** Gates register and search the primary checkout, so a linked worktree's opt-in alone is not enough. */ +function printCodebaseRegistration(cwd: string): void { const primary = realpathSync(primaryCheckout(cwd) ?? cwd); - // Gates register and search the primary checkout, so a linked worktree's opt-in alone is not enough. if (primary !== realpathSync(cwd) && !existsSync(join(primary, SEARCH_CODE_CONFIG))) { console.log( ` ℹ gate reviewers search the primary checkout: run this there too, in ${primary}`,