buddy-agent-harness 0.6.0 → 0.7.0

package/src/diagnose-bridges/doctor.command.ts

@@ -1,36 +1,56 @@
 import { homedir } from 'node:os'
 import type { cli } from 'clibuilder'
-import { command, z } from 'clibuilder'
+import { command, exitCodes, z } from 'clibuilder'
 import { binPath, parseFormat, writeResult } from '../command-output/command-output.ts'
-import { type HarnessName, harnessRegistry } from '../harness-registry/harness-registry.ts'
+import { type ConfigurationFinding, diagnoseConfiguration } from '../diagnose-configuration/diagnose-configuration.ts'
+import { diagnoseMcp } from '../diagnose-mcp/diagnose-mcp.ts'
+import { diagnoseNonstandard } from '../diagnose-nonstandard/diagnose-nonstandard.ts'
+import { parseHarnesses } from '../harness-registry/harness-registry.ts'
 import { type DiagnoseResult, diagnoseBridges } from './diagnose-bridges.ts'
-import { commandInvocation } from './doctor-guidance.ts'
+import { commandInvocation, type DoctorProblem, type RepairAction } from './doctor-guidance.ts'
+import { GitBridgeState } from './git-bridge-state.ts'
 
-type DoctorReport = {
+export type DoctorReport = {
 	bin: string
 	bridges: DiagnoseResult['bridges']
 	instructions: DiagnoseResult['instructions']
 	divergence?: DiagnoseResult['divergence']
-	/** The repair is lifted out into `help`, so a finding row stays to the diagnosis itself. */
-	findings: Omit<DiagnoseResult['findings'][number], 'repair'>[] | string
-	help?: string[]
+	/**
+	 * The repair is lifted out into `help`, so a finding row stays to the diagnosis itself. `problem`
+	 * stays on the row: it is how a caller routes without parsing `detail` prose.
+	 */
+	findings: { path: string; problem: DoctorProblem; detail: string }[] | string
+	/**
+	 * One entry per distinct repair. Two fields rather than a sentence, because the caller has to
+	 * tell an executable repair from an instruction, and `RepairAction` is where that lives.
+	 *
+	 * Both keys are always emitted, `command` as an empty string when there is none. An optional key
+	 * would drop the whole array out of TOON's tabular form into the nested list form — worse for
+	 * exactly the consumer the default format exists for.
+	 */
+	help?: RepairAction[]
 }
 
 /**
  * AXI §5: the healthy answer states the zero with context, so an agent does not re-run with other
  * flags to confirm that an empty section really meant "nothing wrong".
  */
-export function buildReport(bin: string, result: DiagnoseResult): DoctorReport {
+export function buildDoctorReport(
+	bin: string,
+	result: DiagnoseResult,
+	configuration: ConfigurationFinding[] = [],
+): DoctorReport {
+	const findings = [...result.findings, ...configuration]
 	// Both sections are bridges, so the healthy line counts them together rather than making a reader
 	// add up two numbers to learn that nothing is wrong.
-	if (!result.findings.length) {
+	if (!findings.length) {
 		const count = result.bridges.length + result.instructions.length
+		const bridges = count === 1 ? 'the 1 bridge resolves' : `all ${count} bridges resolve`
 		return {
 			bin,
 			bridges: result.bridges,
 			instructions: result.instructions,
-			findings:
-				count === 1 ? '0 problems found — the 1 bridge resolves' : `0 problems found — all ${count} bridges resolve`,
+			findings: `0 problems found — ${bridges} and the configuration around them is current`,
 		}
 	}
 
@@ -39,8 +59,15 @@ export function buildReport(bin: string, result: DiagnoseResult): DoctorReport {
 		bridges: result.bridges,
 		instructions: result.instructions,
 		...(result.divergence.length ? { divergence: result.divergence } : {}),
-		findings: result.findings.map(({ path, detail }) => ({ path, detail })),
-		help: [...new Set(result.findings.map((finding) => `Run \`${finding.repair}\``))],
+		findings: findings.map(({ path, problem, detail }) => ({ path, problem, detail })),
+		// Deduped on the whole pair: several findings often share one repair, and repeating it reads as
+		// more work than there is. Nothing wraps a repair — a `Run …` around every one of them is what
+		// this report used to do, and most repairs are not commands.
+		help: [
+			...new Map(
+				findings.map((finding) => [`${finding.repair.command}\u0000${finding.repair.instruction}`, finding.repair]),
+			).values(),
+		],
 	}
 }
 
@@ -66,28 +93,28 @@ export const doctorCommand: cli.Command = command({
 	run(args) {
 		try {
 			const format = parseFormat(args.format)
-			const requested = args.harness
-				?.split(',')
-				.map((name) => name.trim())
-				.filter(Boolean)
-			const unsupported = requested?.filter((name) => !harnessRegistry.some((harness) => harness.name === name))
-			if (unsupported?.length)
-				throw new Error(
-					`Unsupported harness: ${unsupported.join(', ')}. Supported: ${harnessRegistry
-						.map((harness) => harness.name)
-						.join(', ')}.`,
-				)
+			const harnesses = parseHarnesses(args.harness)
+			const root = args.root ?? process.cwd()
 			const result = diagnoseBridges({
-				root: args.root ?? process.cwd(),
-				...(requested?.length ? { harnesses: requested as HarnessName[] } : {}),
+				root,
+				...(harnesses.length ? { harnesses } : {}),
 				cli: commandInvocation,
 			})
+			const git = new GitBridgeState(root)
+			const configuration = [
+				...diagnoseConfiguration({ root, git, cli: commandInvocation }),
+				...diagnoseMcp({ root, git, cli: commandInvocation }),
+				...diagnoseNonstandard({ root, cli: commandInvocation }),
+			]
 			// Exit stays 0 even with findings: the diagnosis succeeded, and a non-zero code reads to an
 			// agent as "this command is broken, try something else".
-			writeResult(buildReport(binPath(homedir(), process.argv[1]), result), format)
+			writeResult(buildDoctorReport(binPath(homedir(), process.argv[1]), result, configuration), format)
+			return exitCodes.success
 		} catch (error) {
 			process.stderr.write(`error: ${error instanceof Error ? error.message : 'Harness diagnosis failed.'}\n`)
-			process.exitCode = 1
+			// Returned, not written: a command that writes the code reports its failure past `run`
+			// rather than to it, leaving a caller that is not the process no way to learn of it.
+			return exitCodes.error
 		}
 	},
 })

package/src/diagnose-bridges/git-bridge-state.ts

@@ -50,6 +50,36 @@ export class GitBridgeState {
 		return entries.every((entry) => entry.startsWith('S')) ? 'skip-worktree' : 'tracked'
 	}
 
+	/**
+	 * Whether a `.gitignore` rule matches this path. Asked of git rather than matched against the
+	 * file, so a rule on a parent directory — the common way a bridge gets ignored — is caught.
+	 * Outside a repository nothing is ignored, which is the same "cannot tell" degradation the rest
+	 * of this class uses.
+	 */
+	isIgnored(path: string): boolean {
+		if (this.prefix === undefined) return false
+		return git(this.root, ['check-ignore', '-q', '--', path]) !== undefined
+	}
+
+	/**
+	 * The newest commits that touched any of these paths, newest first. Empty outside a repository,
+	 * which is the same "cannot tell" degradation as everything else here.
+	 *
+	 * Bounded like `lastAgreedTree` is: a baseline that is not in the recent history of the two files
+	 * is not a baseline anyone can act on, and walking a whole repository to prove its absence costs
+	 * more than the answer is worth.
+	 */
+	commitsTouching(paths: readonly string[]): string[] {
+		if (this.prefix === undefined) return []
+		return lines(git(this.root, ['rev-list', '-n', '200', 'HEAD', '--', ...paths]))
+	}
+
+	/** One file's content at one commit, or `undefined` when it did not exist there. */
+	contentAt(commit: string, path: string): string | undefined {
+		if (this.prefix === undefined) return undefined
+		return git(this.root, ['show', `${commit}:${this.prefix}${path}`])
+	}
+
 	/**
 	 * Names the side that moved by finding the newest commit whose two trees agreed, then asking which
 	 * of the working directories still matches it.

package/src/diagnose-bridges/locator.ts

@@ -0,0 +1,36 @@
+/**
+ * Where a finding is, in parts.
+ *
+ * A locator addresses a place inside a file — `.cursor/mcp.json#servers.linear.command` — because a
+ * file holding twenty servers is not an address. The parts are known wherever a finding is raised,
+ * and only the report and the repairs need the string, so the parts are what travel and this module
+ * is the one place they become one. Nothing ever recovers a part by splitting a locator back apart:
+ * a server may be named `io.github.foo`, and no split of the rendered string tells where the server
+ * name ends and the field begins.
+ */
+
+/**
+ * Where a malformed file failed. **Position only.** A parser's own error message quotes the
+ * offending line back, and in a file of MCP configuration that line is exactly the one holding a
+ * credential — so neither the message nor the code block it carries is ever read. Line and column
+ * are enough to fix the file and carry nothing out of it.
+ */
+export type Position = { line: number; column: number }
+
+export type Locator = {
+	/** Repository-relative path of the file the finding is about. */
+	file: string
+	/** The MCP server inside that file, when the finding is about one. */
+	server?: string
+	/** The field inside that server, dotted for the per-name fields — `command`, `env.LINEAR_TOKEN`. */
+	field?: string
+	/** Where a file that does not parse failed, when the parser gave a position. */
+	position?: Position | undefined
+}
+
+/** The locator as one string: the finding's `path`, and what a repair names. */
+export function locatorText({ file, server, field, position }: Locator): string {
+	if (position) return `${file}#L${position.line}:${position.column}`
+	if (server === undefined) return file
+	return `${file}#servers.${server}${field === undefined ? '' : `.${field}`}`
+}

package/src/diagnose-configuration/diagnose-configuration.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { filesUnder } from '../diagnose-bridges/directory-files.ts'
+import { type ConfigurationProblem, type RepairAction, repairFor } from '../diagnose-bridges/doctor-guidance.ts'
+import type { GitBridgeState } from '../diagnose-bridges/git-bridge-state.ts'
+import { selectHarnesses } from '../harness-registry/harness-registry.ts'
+
+/**
+ * The configuration half of `doctor`. Where `diagnose-bridges` asks whether a bridge still
+ * resolves, this asks whether the configuration around it is still *right* — a harness name that
+ * has been superseded, an instruction file that never reaches `AGENTS.md`, a bridge git-ignores.
+ *
+ * Everything here is present-and-wrong rather than missing. Configuration that is absent is
+ * `init`'s to create; configuration that is wrong is what the `repair` skill acts on, and this
+ * module is where it reads its work from. Detection has one home so the two cannot drift.
+ *
+ * Instruction bridges are deliberately not here: `diagnose-instructions` owns them, and every one
+ * of its repairs goes back to the `init` skill rather than to `repair`.
+ *
+ * Read-only, like every other part of `doctor`.
+ */
+export type ConfigurationFinding = {
+	/** Repository-relative path the finding is about. */
+	path: string
+	problem: ConfigurationProblem
+	detail: string
+	/** What repairs it, already carrying the path. Every fault here is judgment, so `command` is empty. */
+	repair: RepairAction
+}
+
+export type DiagnoseConfigurationOptions = {
+	root: string
+	git: GitBridgeState
+	/** How to name this tool in the repair commands. */
+	cli: string
+}
+
+const canonicalSkills = '.agents/skills'
+const localOverride = 'AGENTS.local.md'
+
+/**
+ * The two frontmatter faults that make a harness skip a skill outright, per
+ * `skills/init/references/frontmatter.md`: YAML that does not parse, and a missing `description`.
+ * A `name` that mismatches the directory is a warning and still loads, so it is not reported here.
+ *
+ * The unquoted colon is the documented cause of the first, and is checked directly rather than by
+ * parsing YAML: the package ships no parser, and a targeted check names the actual fault.
+ */
+function frontmatterFault(body: string): 'unparseable' | 'no-description' | undefined {
+	const block = /^---\n([\s\S]*?)\n---/.exec(body)
+	if (!block) return 'unparseable'
+	const description = /^description:[ \t]*(.*)$/m.exec(block[1] as string)
+	const value = description?.[1]?.trim()
+	if (!value) return 'no-description'
+	const quoted = /^(['"]).*\1$/.test(value)
+	if (!quoted && /:\s/.test(value)) return 'unparseable'
+	return undefined
+}
+
+/**
+ * Unlike `diagnoseBridges`, this takes no harness preference. Every check here requires the
+ * projection to exist on disk, and a projection cannot exist without its harness's detection
+ * directory — which selects that harness anyway. A preference could therefore never add a finding,
+ * so accepting one would be surface that does nothing.
+ */
+export function diagnoseConfiguration({ root, git, cli }: DiagnoseConfigurationOptions): ConfigurationFinding[] {
+	const findings: ConfigurationFinding[] = []
+	const add = (path: string, problem: ConfigurationProblem) => {
+		const { detail, repair } = repairFor(problem)
+		findings.push({ path, problem, detail, repair: repair({ file: path }, cli) })
+	}
+
+	const harnesses = selectHarnesses(root, [])
+
+	// A superseded name whose projection still exists. `init` reports the deprecation and keeps
+	// projecting, because the old path still works — so nothing else ever says it is stale.
+	for (const harness of harnesses) {
+		const projection = harness.project.skillsDirectory
+		if (harness.deprecated && projection && existsSync(join(root, projection))) add(projection, 'deprecated-harness')
+	}
+
+	// An ignored bridge is untracked, and an untracked bridge swallows a real edit silently.
+	for (const harness of harnesses) {
+		const path = harness.project.skillsDirectory
+		if (path && existsSync(join(root, path)) && git.isIgnored(path)) add(path, 'ignored-bridge')
+	}
+
+	// No harness reads this filename, so whatever it holds is invisible to every agent.
+	if (existsSync(join(root, localOverride))) add(localOverride, 'unread-local-override')
+
+	// `filesUnder` has already confirmed each of these is a readable file, so the read needs no guard
+	// of its own; a failure here is a genuine IO error and belongs in the command's error path.
+	for (const file of filesUnder(join(root, canonicalSkills)).filter((file) => file.endsWith('SKILL.md'))) {
+		if (frontmatterFault(readFileSync(join(root, canonicalSkills, file), 'utf8')))
+			add(`${canonicalSkills}/${file}`, 'unloadable-skill')
+	}
+
+	return findings
+}

package/src/diagnose-mcp/diagnose-mcp.ts

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { type McpProblem, repairFor } from '../diagnose-bridges/doctor-guidance.ts'
+import type { GitBridgeState } from '../diagnose-bridges/git-bridge-state.ts'
+import { type Locator, locatorText } from '../diagnose-bridges/locator.ts'
+import type { ConfigurationFinding } from '../diagnose-configuration/diagnose-configuration.ts'
+import { selectHarnesses } from '../harness-registry/harness-registry.ts'
+import type { McpConfig } from '../harness-registry/mcp-config.ts'
+import { McpBaseline, type McpDirection, parseProjectionRecord, projectionRecordPath } from './mcp-baseline.ts'
+import { divergingFields, type McpServer } from './mcp-model.ts'
+import { credentialFields } from './mcp-secrets.ts'
+import { goldenSetPath, parseGoldenSet, parseTarget } from './mcp-sources.ts'
+
+/**
+ * The MCP half of `doctor`: how a repository's **golden MCP server set** and the harness copies of
+ * it have drifted apart, and where a literal credential is sitting in either.
+ *
+ * The golden set is a file the user authors. That is what makes this capability possible at all:
+ * `init` reports MCP configuration rather than converting it because converting a config someone
+ * wrote for one harness into another's format has to invent values they never wrote, and `init`
+ * invents nothing. A set the user authored inverts the premise — a field they filled in is
+ * transcription. **No golden set means no drift diagnosis**, and nothing here invents anything
+ * either.
+ *
+ * Read-only, like the rest of `doctor`. Projecting the golden set forward and reconciling a
+ * target-side change back into it are writes, and they need an approval-gated home; this module is
+ * where that home reads its work from.
+ */
+export type DiagnoseMcpOptions = {
+	root: string
+	git: GitBridgeState
+	/** How to name this tool in the repair commands. */
+	cli: string
+}
+
+function read(root: string, path: string): string | undefined {
+	const absolute = join(root, path)
+	return existsSync(absolute) ? readFileSync(absolute, 'utf8') : undefined
+}
+
+/**
+ * The distinct MCP files the enabled harnesses read. Two harnesses may name the same file.
+ *
+ * No harness preference is accepted, for the same reason the configuration half accepts none: every
+ * harness documenting an MCP file is already selected without one. Claude Code and Cursor are
+ * selected unconditionally; Codex and Gemini CLI keep their file inside their own detection
+ * directory, so it cannot exist without that directory selecting them. A preference could never add
+ * a finding.
+ */
+function targetsOf(root: string): McpConfig[] {
+	const seen = new Set<string>()
+	return selectHarnesses(root, [])
+		.map((harness) => harness.project.mcpConfig)
+		.filter((config): config is McpConfig => config !== undefined)
+		.filter((config) => !seen.has(config.path) && seen.add(config.path))
+}
+
+const divergence: Record<McpDirection, McpProblem> = {
+	target: 'mcp-diverged-target',
+	golden: 'mcp-diverged-golden',
+	both: 'mcp-diverged-both',
+	unknown: 'mcp-diverged-unknown',
+}
+
+export function diagnoseMcp({ root, git, cli }: DiagnoseMcpOptions): ConfigurationFinding[] {
+	const findings: ConfigurationFinding[] = []
+	// The finding carries the locator in parts as far as the repair, which is where a repair naming
+	// only the server or only the file reads one off. The string is built here and nowhere else, and
+	// nothing recovers a part from it: a server named `io.github.foo` survives no split of it.
+	const add = (at: Locator, problem: McpProblem) => {
+		const { detail, repair } = repairFor(problem)
+		findings.push({ path: locatorText(at), problem, detail, repair: repair(at, cli) })
+	}
+
+	/**
+	 * Credentials are reported for every file that holds servers, the golden set included — a user
+	 * pastes a token into whichever file is open, and the golden set is a file. Severity splits on
+	 * tracking, because a literal in a tracked file is already a committed credential and moving it
+	 * to an environment variable does not un-commit it.
+	 */
+	const reportSecrets = (path: string, servers: Map<string, McpServer>) => {
+		const committed = git.trackingOf(path) !== 'untracked'
+		for (const [name, server] of servers)
+			for (const field of credentialFields(server))
+				add({ file: path, server: name, field }, committed ? 'mcp-committed-secret' : 'mcp-literal-secret')
+	}
+
+	// Targets are read first so an unreadable one is reported whether or not a golden set exists: a
+	// harness cannot read that file either, and its servers are not running.
+	const targets = new Map<string, Map<string, McpServer>>()
+	const configs: McpConfig[] = []
+	for (const config of targetsOf(root)) {
+		const parsed = parseTarget(config, read(root, config.path))
+		if (parsed.kind === 'unreadable') {
+			add({ file: config.path }, 'mcp-target-unreadable')
+			continue
+		}
+		// A harness with no MCP file has nothing that could have drifted. Writing one for the first
+		// time is projection, which is a write and not this command's.
+		if (parsed.kind === 'absent') continue
+		reportSecrets(config.path, parsed.servers)
+		targets.set(config.path, parsed.servers)
+		configs.push(config)
+	}
+
+	const golden = parseGoldenSet(read(root, goldenSetPath))
+	if (golden.kind === 'unreadable') {
+		add({ file: goldenSetPath, position: golden.position }, 'mcp-golden-unreadable')
+		return findings
+	}
+	if (golden.kind === 'absent') return findings
+	reportSecrets(goldenSetPath, golden.servers)
+
+	const baseline = new McpBaseline({ git, record: parseProjectionRecord(read(root, projectionRecordPath)) })
+
+	for (const config of configs) {
+		const servers = targets.get(config.path) as Map<string, McpServer>
+		for (const [name, declared] of golden.servers) {
+			const carried = servers.get(name)
+			if (!carried) {
+				add({ file: config.path, server: name }, 'mcp-unprojected')
+				continue
+			}
+			for (const field of divergingFields(declared, carried))
+				add(
+					{ file: config.path, server: name, field },
+					divergence[baseline.directionOf(config, name, field, declared, carried)],
+				)
+		}
+		for (const name of servers.keys())
+			if (!golden.servers.has(name)) add({ file: config.path, server: name }, 'mcp-undeclared')
+	}
+
+	return findings
+}

package/src/diagnose-mcp/mcp-baseline.ts

@@ -0,0 +1,122 @@
+import type { GitBridgeState } from '../diagnose-bridges/git-bridge-state.ts'
+import { parseJsonWithComments } from '../diagnose-bridges/json-with-comments.ts'
+import type { McpConfig } from '../harness-registry/mcp-config.ts'
+import { isRecord } from '../is-record/is-record.ts'
+import { type McpField, type McpServer, sameField } from './mcp-model.ts'
+import { goldenSetPath, type ParsedServers, parseGoldenSet, parseTarget } from './mcp-sources.ts'
+
+/** Which side of a diverged server moved since the two last agreed. */
+export type McpDirection = 'target' | 'golden' | 'both' | 'unknown'
+
+/** Where the record of what was last written to each target lives, beside the golden set it came from. */
+export const projectionRecordPath = '.agents/buddy-agent-harness/mcp.projected.json'
+
+/**
+ * The last-projected record: per target path, per server name, the model that was written there.
+ *
+ * It exists because git can only answer for a file it can see. Harnesses write their MCP
+ * configuration themselves, at user scope, into files that are often untracked or ignored outright,
+ * and for those "which side moved since they last agreed" has no answer in history. A record
+ * written at projection time has one, exactly, because it *is* what was projected.
+ *
+ * A malformed record answers nothing rather than throwing. It is a cache of an answer, not the
+ * answer, and a diagnosis that dies because its cache is corrupt is worse than one that says
+ * `unknown`.
+ */
+export function parseProjectionRecord(source: string | undefined): Map<string, Map<string, McpServer>> {
+	const document = source === undefined ? undefined : parseJsonWithComments(source)
+	const targets = isRecord(document) ? document['targets'] : undefined
+	if (!isRecord(targets)) return new Map()
+	return new Map(
+		Object.entries(targets)
+			.filter(([, servers]) => isRecord(servers))
+			.map(([path, servers]) => [
+				path,
+				new Map(
+					Object.entries(servers as Record<string, unknown>)
+						.filter(([, server]) => isRecord(server))
+						.map(([name, server]) => [name, server as McpServer]),
+				),
+			]),
+	)
+}
+
+export type BaselineOptions = {
+	git: GitBridgeState
+	record: Map<string, Map<string, McpServer>>
+}
+
+/**
+ * Which side moved, for one server and one field.
+ *
+ * The record is asked first, because it records exactly what was written and therefore answers
+ * exactly. Where it holds nothing, a **tracked** target falls back to git: the newest commit where
+ * the golden set and the target agreed on that field, then which working tree still matches it.
+ * Where neither can answer, the direction is `unknown` and the finding says so — naming a side on a
+ * guess would send a reconcile at the wrong file.
+ */
+export class McpBaseline {
+	constructor(private readonly options: BaselineOptions) {}
+
+	/**
+	 * One parse per commit per file, and one commit walk per target.
+	 *
+	 * `lastAgreed` runs per (config, server, field) that diverges without a projection record, and
+	 * every one of those walks reads the same two files at the same commits. Unmemoized, three
+	 * targets against five servers with two diverged fields each over fifty commits of history is
+	 * three thousand `git show` calls and as many parses — on the command the `doctor` skill says is
+	 * cheap enough for a session-start hook. One instance serves one diagnosis, so the memo lives and
+	 * dies with it and can never answer for a working tree that has moved on.
+	 */
+	private readonly parsed = new Map<string, ParsedServers>()
+	private readonly walked = new Map<string, string[]>()
+
+	directionOf(config: McpConfig, name: string, field: McpField, golden: McpServer, target: McpServer): McpDirection {
+		const base = this.baseFor(config, name, field)
+		if (base === undefined) return 'unknown'
+		const goldenMoved = !sameField(field, golden, base)
+		const targetMoved = !sameField(field, target, base)
+		if (goldenMoved && targetMoved) return 'both'
+		return targetMoved ? 'target' : 'golden'
+	}
+
+	private baseFor(config: McpConfig, name: string, field: McpField): McpServer | undefined {
+		const recorded = this.options.record.get(config.path)?.get(name)
+		if (recorded) return recorded
+		return this.lastAgreed(config, name, field)
+	}
+
+	/**
+	 * The newest committed state where both files described this field the same way. Read at model
+	 * granularity rather than by comparing blobs: the two files never share bytes, and a commit that
+	 * reformatted one of them did not change what it says.
+	 */
+	private lastAgreed(config: McpConfig, name: string, field: McpField): McpServer | undefined {
+		for (const commit of this.commitsTouching(config)) {
+			const golden = this.parseAt(commit, goldenSetPath, parseGoldenSet)
+			const target = this.parseAt(commit, config.path, (source) => parseTarget(config, source))
+			if (golden.kind !== 'servers' || target.kind !== 'servers') continue
+			const left = golden.servers.get(name)
+			const right = target.servers.get(name)
+			if (left && right && sameField(field, left, right)) return left
+		}
+		return undefined
+	}
+
+	private commitsTouching(config: McpConfig): string[] {
+		const walked = this.walked.get(config.path)
+		if (walked) return walked
+		const commits = this.options.git.commitsTouching([goldenSetPath, config.path])
+		this.walked.set(config.path, commits)
+		return commits
+	}
+
+	private parseAt(commit: string, path: string, parse: (source: string | undefined) => ParsedServers): ParsedServers {
+		const key = `${commit}\u0000${path}`
+		const parsed = this.parsed.get(key)
+		if (parsed) return parsed
+		const result = parse(this.options.git.contentAt(commit, path))
+		this.parsed.set(key, result)
+		return result
+	}
+}

package/src/diagnose-mcp/mcp-model.ts

@@ -0,0 +1,88 @@
+import { isRecord } from '../is-record/is-record.ts'
+/**
+ * The shape both sides of an MCP comparison are normalized into.
+ *
+ * No two MCP configuration files are ever byte-equal — the supported harnesses spread the same
+ * servers across six config keys and three serialization formats — so comparison cannot be a
+ * diff. Each side is parsed into this model and the models are compared.
+ *
+ * The field list is a **superset** of what the hosts accept, which is the whole premise of a
+ * golden set: `description`, `enabled`, and `timeout` are Goose's, `source` is Zed's, and a
+ * converter writing into either has to supply them. Supplying a value the user wrote is
+ * transcription; supplying one they did not is invention, and `init` invents nothing. See
+ * `.research/agentic-configuration-standards/` (E-MCP-05) for what each host makes up today.
+ */
+export type McpTransport = 'stdio' | 'http' | 'sse'
+
+export type McpServer = {
+	transport?: McpTransport
+	command?: string
+	args?: readonly string[]
+	env?: Readonly<Record<string, string>>
+	url?: string
+	headers?: Readonly<Record<string, string>>
+	description?: string
+	enabled?: boolean
+	timeout?: number
+	source?: string
+}
+
+/** Every field of the model, in the order a finding reports them. */
+export const mcpFields = [
+	'transport',
+	'command',
+	'args',
+	'env',
+	'url',
+	'headers',
+	'description',
+	'enabled',
+	'timeout',
+	'source',
+] as const
+
+export type McpField = (typeof mcpFields)[number]
+
+/** The two fields holding one value per name rather than a single value. */
+const mapFields = new Set<McpField>(['env', 'headers'])
+
+/**
+ * Whether two values of the same field agree. Arrays are ordered — `args` is a command line, and
+ * reordering it changes what runs. Maps are not, so they are compared by their sorted entries.
+ */
+function sameValue(field: McpField, left: unknown, right: unknown): boolean {
+	if (mapFields.has(field) && isRecord(left) && isRecord(right)) {
+		const keys = Object.keys(left)
+		return keys.length === Object.keys(right).length && keys.every((key) => left[key] === right[key])
+	}
+	return JSON.stringify(left) === JSON.stringify(right)
+}
+
+/**
+ * The fields on which a target disagrees with the golden set.
+ *
+ * Asymmetric by design, and this is the rule that keeps a golden set from accumulating noise. A
+ * field the golden set leaves unset is never a difference, however the target fills it: a host
+ * restating its own default and a user's deliberate edit are indistinguishable in that position,
+ * and pulling both back would grow the golden set on every round-trip. The golden set speaks only
+ * about what it says.
+ *
+ * `env` and `headers` are compared per name for the same reason — a variable only the target sets
+ * is that target's business, and one the golden set names must match.
+ */
+export function divergingFields(golden: McpServer, target: McpServer): McpField[] {
+	return mcpFields.filter((field) => {
+		const declared = golden[field]
+		if (declared === undefined) return false
+		if (mapFields.has(field) && isRecord(declared) && isRecord(target[field])) {
+			const observed = target[field] as Record<string, unknown>
+			return Object.keys(declared).some((key) => declared[key] !== observed[key])
+		}
+		return !sameValue(field, declared, target[field])
+	})
+}
+
+/** Whether one field of two models agrees, for naming the side that moved. */
+export function sameField(field: McpField, left: McpServer | undefined, right: McpServer | undefined): boolean {
+	return sameValue(field, left?.[field], right?.[field])
+}