ast-mcp-server 0.11.2 → 0.13.0

package/CHANGELOG.md

@@ -6,7 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.11.2] — local release candidate, pending release (2026-08-25)
+## [0.13.0] — local release candidate, pending release (2026-08-27)
+
+### Added
+
+- DeepSeek Harness Developer Preview adapter (roadmap initiative 4, first slice): `cordis.patch.yml` mounts the packaged `ast-mcp-server` stdio command through `@deepseek-ai/dsh-mcp-client`, declared via the exact `"dsh": {"bundle": {"patch": "./cordis.patch.yml"}}` contract with the pinned identity recorded separately in `deepseekHarness` (revision `cd5ef814…`, `dsh-v0.1.2-alpha.1`). The first surface is reads + prepare + preview with a fail-closed apply guard (`ast_apply_operation` registers only under an explicit `AST_MCP_APPLY_GUARD=allow`; unset, `deny`, or invalid denies it). `yarn test:dsh-adapter` is a mandatory, never-skipping gate: tarball fixture and hashes, guard matrix, and — against the clean source-built pinned Harness — native-mode profile composition plus Harness-mediated read, dry-run rename, preview, apply absence, and rejected direct apply invocation.
+
+## [0.12.0] — published to `latest` and `next`, registry verified (2026-08-27)
+
+### Added
+
+- Diagnostic pagination can now include opt-in bounded aggregates computed from the complete normalized snapshot, with code and file dimensions capped at 20 entries and explicit coverage metadata.
+- Added an immutable tool capability catalog with MCP, batch, and agent projections derived from one source of truth, plus independent inventory, integration, canary, package, and documentation oracles.
+
+### Fixed
+
+- Canary validation continues to enforce the established public runtime gate payload while capability metadata is checked independently, preventing an internal catalog change from widening the public canary schema.
+
+### Release status
+
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. Public-registry consumer and release-preflight verification passed, `latest` and `next` both resolve to `0.12.0`, and the annotated `v0.12.0` tag plus GitHub Release resolve to the same release commit.
+
+## [0.11.2] — published to `latest` and `next`, registry verified (2026-08-25)
 
 ### Added
 
@@ -22,7 +43,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Release status
 
-- This local release candidate succeeds immutable npm versions `0.11.0` and `0.11.1`, neither of which was promotable: `0.11.0` verification exposed stale managed-skill predicates, and `0.11.1` verification exposed the copied runner's missing validator module. Version `0.11.2` remains pending its exact-tree matrix, CI, and separately authorized delivery sequence; it has not been published or assigned to any dist-tag.
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. Public-registry consumer and release-preflight verification passed, `latest` and `next` both resolve to `0.11.2`, and the annotated `v0.11.2` tag plus GitHub Release resolve to the same release commit. This release supersedes immutable versions `0.11.0` and `0.11.1`, whose separate public-registry verification defects prevented promotion.
 
 ## [0.11.1] — published to `next`, verification failed, not promoted (2026-08-23)
 

package/README.md

@@ -55,12 +55,12 @@ Reads can start with a bounded file slice, a compact outline, or exact source on
 
 The server exposes evidence labels instead of collapsing every result into an unqualified confidence score:
 
-| Label                                                                                                 | Meaning                                                                                                                                                                                                       | Safe use                                                                                                 |
-| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `provenance: "compiler"`, `confidence: "exact"`, `resolution: "resolved"`, `freshness.state: "fresh"` | A relationship resolved by the active TypeScript compiler snapshot. This is the only combination that sets `compiler_authoritative: true`.                                                                    | May support bounded impact evidence and compiler-backed test candidates.                                 |
-| `provenance: "syntax"`                                                                                | Syntax or AST structure without semantic symbol resolution.                                                                                                                                                   | Navigation and structural context only; not proof that two symbols are related.                          |
-| `provenance: "heuristic"`                                                                             | A convention or name-based suggestion.                                                                                                                                                                        | Discovery hints only; never mutation authority or a compiler-backed test candidate.                      |
-| index evidence                                                                                        | A derived query accelerator, not compiler authority. The current production status reports the index as disabled; any future ready index still requires compiler selector validation and a compiler fallback. | Faster routing only; stale, missing or mismatched entries must fail closed or fall back to the compiler. |
+| Label                                                                                                 | Meaning                                                                                                                                                                                                                    | Safe use                                                                                                 |
+| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `provenance: "compiler"`, `confidence: "exact"`, `resolution: "resolved"`, `freshness.state: "fresh"` | A relationship resolved by the active TypeScript compiler snapshot. This is the only combination that sets `compiler_authoritative: true`.                                                                                 | May support bounded impact evidence and compiler-backed test candidates.                                 |
+| `provenance: "syntax"`                                                                                | Syntax or AST structure without semantic symbol resolution.                                                                                                                                                                | Navigation and structural context only; not proof that two symbols are related.                          |
+| `provenance: "heuristic"`                                                                             | A convention or name-based suggestion.                                                                                                                                                                                     | Discovery hints only; never mutation authority or a compiler-backed test candidate.                      |
+| index evidence                                                                                        | A derived query accelerator, not compiler authority. The production default uses native SQLite when persistence is absent or `enabled`; every indexed selector still requires compiler validation and a compiler fallback. | Faster routing only; stale, missing or mismatched entries must fail closed or fall back to the compiler. |
 
 Freshness is orthogonal to TypeScript diagnostics. `fresh` means the evidence matches the synchronized snapshot; `pending`, `rebuilding`, `stale`, or `degraded` means the response must not be presented as current compiler evidence. Read tools expose the state, causes (`source_change`, `config_change`, `index_failure`, `watcher_failure`, or `compiler_rebuild`), and bounded `checked_at` timestamp. `ast_get_impact` refuses non-fresh compiler relationships. `ast_explore` returns the state together with `completeness`, `unresolved`, `budget`, and `truncation` metadata rather than silently dropping evidence.
 
@@ -84,7 +84,7 @@ The included batch benchmark records a 50% reduction in model round-trips and a
 
 ## Supported environment and trust boundary
 
-The local `0.11.2` release candidate requires Node.js `>=22.13.0`; its evidence matrix targets exact Node.js 22.13.0 and the current Node.js 24 line. Published v0.10.0 retains its immutable historical Node.js 22.13.0/24 evidence. Managed setup-file publication additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified.
+Published v0.12.0 requires Node.js `>=22.13.0`; its immutable evidence matrix targets exact Node.js 22.13.0 and the current Node.js 24 line. Managed setup-file publication additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified.
 
 This is a local stdio server. It runs with the invoking user's filesystem permissions, and clients may request any `project_root` that user can access. It does not provide HTTP authentication, sandboxing, tenant isolation, or a remote-service security boundary. Remote, untrusted, and multi-tenant operation is unsupported.
 
@@ -100,7 +100,7 @@ The parent waits for child readiness before replaying bounded initialization sta
 
 The scoped Linux canary passed on exact Node.js 22.13.0 and Node.js 24 with repeatable PSS reclamation, stable compiler fingerprints, unchanged SQLite reuse, bounded redacted diagnostics, and no orphan after parent death. This is one child per connection, not a shared daemon, pool, or new default. See [ADR 0014](docs/adr/0014-supervised-compiler-worker.md).
 
-In published v0.10.0 and the local `0.11.2` release candidate, an absent `AST_SYMBOL_INDEX_PERSISTENCE` or explicit `enabled` selects the private SQLite symbol-index cache. `disabled` is the immediate memory-only rollback. `canary` requires an explicit absolute normalized `AST_SYMBOL_INDEX_CACHE_ROOT`. Invalid policy or storage fails closed to compiler-authoritative memory reads with bounded path-free status.
+In published v0.12.0, an absent `AST_SYMBOL_INDEX_PERSISTENCE` or explicit `enabled` selects the private SQLite symbol-index cache. `disabled` is the immediate memory-only rollback. `canary` requires an explicit absolute normalized `AST_SYMBOL_INDEX_CACHE_ROOT`. Invalid policy or storage fails closed to compiler-authoritative memory reads with bounded path-free status.
 
 The default cache root is selected from `AST_SYMBOL_INDEX_CACHE_ROOT`, then `XDG_CACHE_HOME`, then `HOME`. Inspect or clear only derived cache artifacts through the bounded CLI:
 
@@ -261,7 +261,7 @@ Claude Code supports local stdio MCP servers. After building this repository, re
 
 ```bash
 AST_MCP_DIR="$(pwd)"
-claude mcp add --scope user --transport stdio ast -- \
+claude mcp add --scope user --env AST_MCP_APPLY_GUARD=allow --transport stdio ast -- \
   node "$AST_MCP_DIR/dist/index.js"
 claude mcp get ast
 ```
@@ -316,12 +316,44 @@ Use `/mcp` inside Claude Code to inspect server status and tools. Outside the se
 Hermes Agent:
 
 ```bash
-hermes mcp add ast --command node --args /absolute/path/to/ast-mcp-server/dist/index.js
+hermes mcp add ast --command node --env AST_MCP_APPLY_GUARD=allow --args /absolute/path/to/ast-mcp-server/dist/index.js
 hermes mcp test ast
 ```
 
 Project-scoped tools accept `project_root`, either the project directory or an explicit `tsconfig.json` path. The server contains no repository-specific paths.
 
+### DeepSeek Harness (Developer Preview)
+
+A thin adapter ships inside this package: `cordis.patch.yml` mounts the packaged
+`ast-mcp-server` stdio command through the official
+[`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness/blob/cd5ef8148158c3a752a658978873241fdf8e2bbc/packages/mcp/mcp-client/README.md)
+bridge, declared through exactly `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`.
+This is a Developer Preview against a pinned, **source-built** Harness revision
+(`dsh-v0.1.2-alpha.1` at `cd5ef8148158c3a752a658978873241fdf8e2bbc`); that revision
+is validated from source, and `ast-mcp-server@0.13.0` is not published yet. Install a
+locally packed tarball instead:
+
+```bash
+yarn pack --out ast-mcp-server-%v.tgz
+dsh plugin --profile web add ./ast-mcp-server-0.13.0.tgz
+```
+
+The first supported surface is **reads + prepare + preview**. Every apply path is
+denied by a fail-closed guard: `ast_apply_operation` is not registered unless
+`AST_MCP_APPLY_GUARD=allow` is set explicitly (the shipped patch instead pins `deny`,
+so the Harness surface stays deny-by-default; an unset or invalid value also denies). Known upstream
+gaps apply and are never safety authority: the official bridge drops MCP tool
+annotations (`readOnlyHint`/`destructiveHint`) and launches the stdio child outside
+the Harness sandbox.
+
+`yarn test:dsh-adapter` is the mandatory verification: it packs the exact tarball,
+installs it into an isolated profile on the pinned Harness, proves `--dump-config`
+composition including effective `tools.mode: native`, and — through the Harness registry
+itself — invokes the server-qualified read, dry-run rename prepare, and preview tools.
+It separately proves `mcp__ast__ast_apply_operation` is absent and that a bounded direct
+registry invocation is rejected. The smoke fails (never skips) if the pinned Harness
+revision, tag, CLI/client version, clean source identity, or a prerequisite is missing.
+
 ## MCP tools
 
 | Tool                        | Purpose                                                              | Mutates files |
@@ -345,6 +377,12 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 
 Read results use project-relative paths, deterministic ordering, structured MCP output, and pagination where result sets can grow with the project.
 
+### Diagnostic aggregates
+
+Set `include_aggregates: true` on `ast_get_diagnostics` to summarize the complete normalized diagnostic snapshot independently of the selected raw page. The option defaults to `false`; disabled responses omit `aggregates` and keep the existing shape.
+
+Each code and file dimension returns at most 20 ranked groups. `groups.length + omitted_group_count = total_group_count`, and `sum(groups[*].count) = covered_diagnostic_count`. Code coverage plus `omitted_diagnostic_count` equals the diagnostic total; file coverage also adds `unfiled_diagnostic_count`. File groups contain normalized project-relative paths only, but may disclose a path that is absent from the selected raw page.
+
 `ast_explore` supports query, exact file, and exact symbol routes. Its default `summary` profile returns bounded reusable selectors; `context` adds selected source and `full` adds compiler references. Whole symbol clusters are admitted under the caller's `max_bytes` ceiling, so source, reference records, and call paths are never sliced. `omissions` classifies withheld components as `budget`, `incomplete`, or `untrusted`, and any requested omission keeps completeness false.
 
 Exact `file_path` plus `symbol_path` requests may opt into bounded static `call_spines`. Only fresh, exact, compiler-resolved invocation sites qualify; generic references, dynamic dispatch, and runtime behavior are not inferred. Absence of `call_spines` performs no call traversal. Every response still reports freshness, completeness, truncation, unresolved selectors, record limits, and canonical serialized-byte accounting. Use the primitive tools when a single exact operation is clearer or when preparing a mutation. See [ADR 0013](docs/adr/0013-ast-explore-presentation.md).
@@ -486,7 +524,19 @@ The server does **not** claim a filesystem-wide transaction:
 
 ## Development gates
 
+### Add or change an MCP tool
+
+Keep schemas, metadata, annotations, handlers, errors, and serialization in the tool module. Export
+one frozen descriptor, add it to the intentional order in `src/tools/catalog.ts`, and declare only
+static effect, batch, compatibility, and direct-format facts. Do not add request state, dynamic
+discovery, invocation-by-name, or a generic executor to the catalog.
+
+Update the independent `tools/list` inventories only after reviewing the complete wire metadata;
+they must not import or derive expectations from the catalog. Then run the focused catalog and MCP
+integration tests plus the runtime, package, and managed-skill gates below.
+
 ```bash
+yarn vitest run test/tool-catalog.test.ts test/mcp.integration.test.ts
 yarn format:check
 yarn lint
 yarn typecheck

package/SECURITY.md

@@ -11,7 +11,7 @@ Security fixes are provided for the exact version currently identified by the np
 | Earlier npm versions                        | No        |
 | Unpublished release candidates              | No        |
 
-This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The local `0.11.2` release candidate requires Node.js `>=22.13.0`, with evidence targeted at exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.10.0 retains its immutable Node.js 22.13.0/24 release matrix. Managed setup mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. The candidate's default SQLite cache also relies on Linux ownership, mode, no-follow, link-count and inode-identity checks; it does not defend against a malicious same-UID process. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
+This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. Published v0.12.0 requires Node.js `>=22.13.0`, with immutable evidence targeted at exact Node.js 22.13.0 and the governed Node.js 24 major. Managed setup mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. The release's default SQLite cache also relies on Linux ownership, mode, no-follow, link-count and inode-identity checks; it does not defend against a malicious same-UID process. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
 
 ## Reporting a vulnerability
 

package/cordis.patch.yml

@@ -0,0 +1,31 @@
+# DeepSeek Harness adapter patch for ast-mcp-server (roadmap initiative 4).
+#
+# Mounts the packaged `ast-mcp-server` stdio command through the official
+# `@deepseek-ai/dsh-mcp-client` bridge. Harness does not resolve MCP binaries
+# from PATH, so the entrypoint is resolved relative to the profile directory
+# (`baseUrl`), where `dsh plugin --profile <name> add ./ast-mcp-server-0.13.0.tgz`
+# installs a locally packed package as a dependency.
+#
+# First-slice surface: reads + prepare + preview. Every apply path is denied
+# by the server-side guard activated through `AST_MCP_APPLY_GUARD=deny`.
+#
+# Known upstream gaps (documented, never safety authority):
+# - the official bridge drops MCP tool.annotations, incl. readOnlyHint and
+#   destructiveHint, so the guard enumerates tool names instead of hints;
+# - the stdio child runs outside the Harness sandbox.
+- insert:
+    - id: mcp-ast
+      name: "@deepseek-ai/dsh-mcp-client"
+      config:
+        serverName: ast
+        transport: stdio
+        command: !!js process.execPath
+        args:
+          - !!js >-
+            process.getBuiltinModule('node:url').fileURLToPath(
+              new URL('node_modules/ast-mcp-server/dist/index.js', baseUrl)
+            )
+        env:
+          AST_MCP_APPLY_GUARD: "deny"
+        cwd: !!js process.cwd()
+        failOnStartupError: true

package/dist/batch/schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { toolCatalog } from "../tools/catalog.js";
 export const BATCH_SCHEMA_VERSION = 1;
 export const MAX_BATCH_STEPS = 50;
 export const MAX_BATCH_INVOCATIONS = 500;
@@ -8,22 +9,12 @@ export const MAX_BATCH_CONCURRENCY = 16;
 export const MAX_BATCH_INPUT_BYTES = 1024 * 1024;
 export const MAX_BATCH_OUTPUT_BYTES = 10 * 1024 * 1024;
 export const MAX_BATCH_CONTEXT_BYTES = 50 * 1024 * 1024;
-export const READ_BATCH_TOOLS = [
-    "ast_list_files",
-    "ast_get_outline",
-    "ast_get_symbol_source",
-    "ast_search_symbols",
-    "ast_find_references",
-    "ast_find_test_candidates",
-    "ast_explore",
-    "ast_get_diagnostics",
-];
-export const PREPARE_BATCH_TOOLS = [
-    "ast_rename_symbol",
-    "ast_replace_symbol_body",
-    "ast_scaffold_class",
-];
-export const BATCH_TOOLS = [...READ_BATCH_TOOLS, ...PREPARE_BATCH_TOOLS];
+export const READ_BATCH_TOOLS = toolCatalog.batch.read;
+export const PREPARE_BATCH_TOOLS = toolCatalog.batch.prepare;
+export const BATCH_TOOLS = Object.freeze([
+    ...READ_BATCH_TOOLS,
+    ...PREPARE_BATCH_TOOLS,
+]);
 const BatchToolSchema = z.enum(BATCH_TOOLS);
 const BatchStepSchema = z
     .object({

package/dist/server.js

@@ -1,22 +1,7 @@
 import { createRequire } from "node:module";
 import { McpServer, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { PublicOperationalError } from "./services/public-errors.js";
-import { registerApplyOperation } from "./tools/apply_operation.js";
-import { registerFindReferences } from "./tools/find_references.js";
-import { registerFindTestCandidates } from "./tools/find_test_candidates.js";
-import { registerGetDiagnostics } from "./tools/get_diagnostics.js";
-import { registerGetFile } from "./tools/get_file.js";
-import { registerGetImpact } from "./tools/get_impact.js";
-import { registerGetOperationPreview } from "./tools/get_operation_preview.js";
-import { registerGetOutline } from "./tools/get_outline.js";
-import { registerGetProjectStatus } from "./tools/get_project_status.js";
-import { registerGetSymbolSource } from "./tools/get_symbol_source.js";
-import { registerListFiles } from "./tools/list_files.js";
-import { registerRenameSymbol } from "./tools/rename_symbol.js";
-import { registerReplaceSymbolBody } from "./tools/replace_symbol_body.js";
-import { registerScaffoldClass } from "./tools/scaffold_class.js";
-import { registerSearchSymbols } from "./tools/search_symbols.js";
-import { registerExplore } from "./tools/explore.js";
+import { toolCatalog } from "./tools/catalog.js";
 import { createToolErrorContext, errorResult } from "./tools/result.js";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 export const PACKAGE_VERSION = packageMetadata.version;
@@ -40,21 +25,11 @@ export function createServer(options = {}) {
     });
     if (options.runtimeActivity)
         installRuntimeActivityTracking(server, options.runtimeActivity);
-    registerListFiles(server);
-    registerGetProjectStatus(server);
-    registerExplore(server);
-    registerGetOutline(server);
-    registerGetSymbolSource(server);
-    registerSearchSymbols(server);
-    registerFindReferences(server);
-    registerGetImpact(server);
-    registerFindTestCandidates(server);
-    registerGetDiagnostics(server);
-    registerGetFile(server);
-    registerRenameSymbol(server);
-    registerReplaceSymbolBody(server);
-    registerScaffoldClass(server);
-    registerGetOperationPreview(server);
-    registerApplyOperation(server);
+    if (options.denyApply === undefined) {
+        toolCatalog.registerAll(server);
+    }
+    else {
+        toolCatalog.registerAll(server, { denyApply: options.denyApply });
+    }
     return server;
 }

package/dist/services/agent-setup.js

@@ -9,7 +9,7 @@ import { applySkillInstallationPlan, planBundledSkillInstallation, SkillConflict
 import { planManagedGuidance, } from "./managed-guidance.js";
 import { applyManagedFilePlan, createManagedFileApplyContext, ManagedFileApplyError, ManagedFileRollbackError, revalidateManagedFilePlan, verifyManagedFilePostimage, } from "./managed-file.js";
 import { AGENT_IDS, classifyAgentVersion, getAgentTarget, MCP_SERVER_NAME, } from "./agent-targets.js";
-import { applyOpenCodeConfigPlan, planOpenCodeConfig, resolveOpenCodeConfigPath, withIsolatedOpenCodeConfig, } from "./opencode-config.js";
+import { applyOpenCodeConfigPlan, classifyOpenCodeAstRegistration, planOpenCodeConfig, resolveOpenCodeConfigPath, OpenCodeConfigRecoveryError, runOpenCodeConfigTransaction, withIsolatedOpenCodeConfig, } from "./opencode-config.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
 export class AgentSetupError extends Error {
@@ -238,10 +238,12 @@ async function verifyOpenCode(detection, environment, timeoutMs, context) {
             throw new AgentSetupError("OpenCode resolved configuration output is unknown.", "AGENT_VERIFICATION_FAILED", { agent: "opencode" });
         }
         const command = config?.mcp?.ast?.command;
+        const guard = config?.mcp?.ast?.environment?.AST_MCP_APPLY_GUARD;
         if (!Array.isArray(command) ||
             command.length !== 2 ||
             command[0] !== context.nodeExecutable ||
-            command[1] !== context.serverEntryPath) {
+            command[1] !== context.serverEntryPath ||
+            guard !== "allow") {
             throw new AgentSetupError("OpenCode resolved configuration does not contain the expected ast server.", "AGENT_VERIFICATION_FAILED", { agent: "opencode" });
         }
         const listed = await runtime.run(["mcp", "list", "--pure"]);
@@ -265,6 +267,63 @@ async function configureMcp(agent, detection, serverEntryPath, nodeExecutable, e
         throw new AgentSetupError(`${target.label} saved the MCP registration but verification did not match.`, "AGENT_VERIFICATION_FAILED", { agent, inspection: verified });
     }
 }
+async function repairMcp(agent, detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
+    const target = getAgentTarget(agent);
+    const runtime = targetRuntime(detection, environment, timeoutMs);
+    const context = { serverEntryPath, nodeExecutable };
+    const authenticated = await target.mcp.inspect(runtime, context);
+    if (authenticated.status !== "repairable") {
+        throw new AgentSetupError(`${target.label} legacy registration changed before repair and was not removed.`, "AGENT_MCP_CONFLICT", { agent, inspection: authenticated });
+    }
+    const recover = async (cause) => {
+        const durable = await target.mcp.inspect(runtime, context);
+        if (durable.status === "current")
+            return;
+        if (durable.status === "repairable")
+            throw cause;
+        if (durable.status !== "missing") {
+            throw new AgentSetupError(`${target.label} migration outcome conflicts with the authenticated registration; it was preserved.`, "AGENT_MCP_CONFLICT", { agent, inspection: durable });
+        }
+        // The authenticated preimage is absent. Add it directly: never unregister
+        // here, because a concurrent replacement must make this add fail harmlessly.
+        const restored = await target.mcp.registerLegacy(runtime, context);
+        const afterRestore = await target.mcp.inspect(runtime, context);
+        if (afterRestore.status === "current")
+            return;
+        if (afterRestore.status === "repairable")
+            throw cause;
+        if (!target.mcp.registrationAccepted(restored) && afterRestore.status === "conflict") {
+            throw new AgentSetupError(`${target.label} changed concurrently during migration recovery; the replacement was preserved.`, "AGENT_MCP_CONFLICT", { agent, inspection: afterRestore });
+        }
+        throw new AgentSetupError(`${target.label} migration failed and its authenticated legacy registration is missing.`, "AGENT_VERIFICATION_FAILED", { agent, cause: cause instanceof Error ? cause.message : String(cause), afterRestore });
+    };
+    try {
+        let removalError;
+        try {
+            const removed = await target.mcp.unregister(runtime);
+            if (!target.mcp.removalAccepted(removed)) {
+                removalError = commandFailure(agent, "legacy MCP removal", removed);
+            }
+        }
+        catch (error) {
+            removalError = error;
+        }
+        if (removalError !== undefined) {
+            return recover(removalError);
+        }
+        const added = await target.mcp.register(runtime, context);
+        if (!target.mcp.registrationAccepted(added)) {
+            throw commandFailure(agent, "MCP registration repair", added);
+        }
+        const verified = await target.mcp.inspect(runtime, context);
+        if (verified.status !== "current") {
+            throw new AgentSetupError(`${target.label} saved the repaired MCP registration but verification did not match.`, "AGENT_VERIFICATION_FAILED", { agent, inspection: verified });
+        }
+    }
+    catch (error) {
+        return recover(error);
+    }
+}
 async function assertRegularFile(filePath, label) {
     let fileStat;
     try {
@@ -367,16 +426,11 @@ export async function runAgentSetup(options) {
         catch {
             throw new AgentSetupError("OpenCode effective configuration output is unknown.", "AGENT_MCP_CONFLICT", { agent: "opencode", correlation_id: correlationId });
         }
-        const effectiveAst = effectiveConfig?.mcp?.ast;
-        const desiredAst = {
-            type: "local",
-            command: [nodeExecutable, options.serverEntryPath],
-            enabled: true,
-        };
-        if (effectiveAst !== undefined && JSON.stringify(effectiveAst) !== JSON.stringify(desiredAst)) {
+        const effectiveAstStatus = classifyOpenCodeAstRegistration(effectiveConfig?.mcp?.ast, nodeExecutable, options.serverEntryPath);
+        if (effectiveAstStatus === "conflict") {
             throw new AgentSetupError("OpenCode effective configuration conflict at mcp.ast.", "AGENT_MCP_CONFLICT", { agent: "opencode", correlation_id: correlationId });
         }
-        if (effectiveAst !== undefined && openCodePlan.status === "installed") {
+        if (effectiveAstStatus === "current" && openCodePlan.status === "installed") {
             openCodePlan = { ...openCodePlan, status: "unchanged" };
         }
     }
@@ -434,23 +488,35 @@ export async function runAgentSetup(options) {
         const inspection = inspections.find((item) => item.agent === agent);
         try {
             await verifyManagedAssetPlans(skillPlan, guidancePlan, applyContext);
-            if (inspection.status === "missing") {
+            if (inspection.status === "missing" || inspection.status === "repairable") {
                 if (agent === "opencode") {
-                    await applyOpenCodeConfigPlan(openCodePlan);
-                    if (openCodePlan.status === "installed") {
+                    try {
+                        await runOpenCodeConfigTransaction(openCodePlan, async () => {
+                            await applyOpenCodeConfigPlan(openCodePlan);
+                            await verifyOpenCode(detection, environment, timeoutMs, {
+                                nodeExecutable,
+                                serverEntryPath: options.serverEntryPath,
+                            });
+                        });
+                    }
+                    catch (error) {
+                        if (error instanceof OpenCodeConfigRecoveryError)
+                            throw new AgentSetupError("OpenCode configuration outcome could not be restored safely.", "AGENT_VERIFICATION_FAILED", { cause: error.message });
+                        throw error;
+                    }
+                    if (openCodePlan.status === "installed")
                         physicalWrites.push({
                             path: openCodePlan.filePath,
                             asset: "mcp_config",
                             status: "installed",
                         });
-                    }
-                    await verifyOpenCode(detection, environment, timeoutMs, {
-                        nodeExecutable,
-                        serverEntryPath: options.serverEntryPath,
-                    });
                 }
-                else
+                else if (inspection.status === "repairable") {
+                    await repairMcp(agent, detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
+                }
+                else {
                     await configureMcp(agent, detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
+                }
             }
             else if (agent === "opencode") {
                 await verifyOpenCode(detection, environment, timeoutMs, {