ast-mcp-server 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -6,7 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.12.0] — local release candidate, pending release (2026-08-27)
+## [0.13.1] - 2026-09-01
+
+### Fixed
+
+- The DeepSeek Harness adapter now opts into a bounded canonical-JSON text projection when a successful MCP result has structured data but no ordinary text, preserving lossless `structuredContent` while making native Agent/Session results useful and durable. The mandatory pinned-host smoke freezes the public 0.13.0 RED baseline and verifies the corrected candidate across the next model request, persisted `tool/result`, cold replay, guarded catalog, and cleanup readback.
+- `ast_explore` now publishes its complete object input schema while retaining all cross-field runtime rejection, and `ast_get_impact` no longer advertises one false output shape across JSON and TOON. The pinned Harness gate binds the public empty-schema RED to candidate registry/native parity and unchanged hashes for the other 14 model schemas.
+- Timeout ownership is now explicit across the Harness, queue, and AST worker: the shipped outer timeout exceeds the complete queue/execution/margin budget, deterministic slow work returns bounded AST-owned operational errors, queued work never starts after its deadline, cancellation remains correlated across worker generations, and cleanup proves zero active work, held requests, listeners, or owned processes.
+- Harness lifecycle handling now converges deterministically through MCP removal and reconnect, rejects retired-generation effects, preserves AST `REQUEST_CANCELLED` authority separately from bridge transport observations, and completes correlated shutdown without residual state. The pinned native and rendered-GUI gates verify the `15→0→15` catalog sequence, request/header identity, secret-safe diagnostics, and ordered cleanup that still runs every owner check after an earlier cleanup failure.
+
+### Release status
+
+- This is the reviewed `0.13.1` release candidate. Publication to npm `next`, public-registry verification, promotion to `latest`, tagging, and GitHub Release creation remain pending and are not claimed here.
+
+## [0.13.0] — published to `latest` and `next`, registry verified (2026-08-29)
+
+### 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
 
@@ -19,7 +38,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Release status
 
-- Version `0.12.0` remains pending its exact-tree two-runtime matrix, CI, and separately authorized delivery sequence. It has not been published, assigned to an npm dist-tag, tagged in Git, or released on GitHub.
+- 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)
 

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.12.0` 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.11.2 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.11.2 and the local `0.12.0` 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,61 @@ 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`). The published
+`ast-mcp-server@0.13.0` package is the compatibility baseline:
+
+```bash
+dsh plugin --profile web add ast-mcp-server@0.13.0
+```
+
+For a local candidate, pack and install its tarball instead:
+
+```bash
+yarn pack --out ast-mcp-server-%v.tgz
+dsh plugin --profile web add ./ast-mcp-server-0.13.1.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).
+The adapter also sets `AST_MCP_TEXT_PROJECTION=canonical_json`: successful structured
+results keep their lossless `structuredContent` and gain canonical JSON text only when
+ordinary MCP text is empty, because the pinned native presenter otherwise exposes only a
+non-useful empty-result marker. The projection is adapter-specific, never replaces existing
+text, and reports an explicit size-limit marker when the complete supervised frame has room.
+If even the unchanged structured-only result exceeds the existing worker frame, supervised mode
+fails closed rather than truncating or corrupting it. Known upstream gaps remain non-authoritative:
+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 binds the public 0.13.0 npm
+integrity, packs the candidate, builds the pinned Harness and bridge from source, and proves
+`tools.mode: native`, the 15-tool scoped catalog, complete executable input schemas,
+read/prepare/preview, all three invalid `ast_explore` combinations, apply absence, and rejected direct apply.
+The schema gate freezes the public empty `ast_explore` contract as RED, requires the candidate
+registry/native definitions to match, and hashes all 14 unaffected model schemas. A deterministic
+two-step model then invokes
+`mcp__ast__ast_get_project_status` through a real headless Agent/Session: the public baseline
+must reproduce the empty-result marker, while the corrected candidate must deliver lossless
+canonical JSON to the next model request, the durable `tool/result`, and a cold Agent
+resume/replay reconstructed from persistence. The smoke removes and read-backs its disposable
+profile/workspace state and fails
+(never skips) on an identity mismatch, missing prerequisite, lifecycle leak, or evidence gap.
+
 ## MCP tools
 
 | Tool                        | Purpose                                                              | Mutates files |

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.12.0` 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.11.2 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,38 @@
+# 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.1.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.
+# Harness native presentation reads text content, so this adapter explicitly
+# requests a lossless canonical JSON projection while preserving structuredContent.
+- 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"
+          AST_MCP_TEXT_PROJECTION: "canonical_json"
+        cwd: !!js process.cwd()
+        toolCallTimeoutMs: !!js >-
+          JSON.parse(process.getBuiltinModule('node:fs').readFileSync(
+            new URL('node_modules/ast-mcp-server/package.json', baseUrl), 'utf8'
+          )).deepseekHarness.timeoutBudget.outerToolCallMs
+        failOnStartupError: true

package/dist/server.js

@@ -2,9 +2,20 @@ import { createRequire } from "node:module";
 import { McpServer, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { PublicOperationalError } from "./services/public-errors.js";
 import { toolCatalog } from "./tools/catalog.js";
-import { createToolErrorContext, errorResult } from "./tools/result.js";
+import { createToolErrorContext, errorResult, projectStructuredContentAsText, } from "./tools/result.js";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 export const PACKAGE_VERSION = packageMetadata.version;
+function installStructuredContentTextProjection(server) {
+    const registerTool = server.registerTool.bind(server);
+    function projectedRegisterTool(name, config, callback) {
+        const projectedCallback = (async (...args) => {
+            const result = await Reflect.apply(callback, undefined, args);
+            return projectStructuredContentAsText(result, true);
+        });
+        return registerTool(name, config, projectedCallback);
+    }
+    server.registerTool = projectedRegisterTool;
+}
 function installRuntimeActivityTracking(server, runtimeActivity) {
     const registerTool = server.registerTool.bind(server);
     function trackedRegisterTool(name, config, callback) {
@@ -25,6 +36,14 @@ export function createServer(options = {}) {
     });
     if (options.runtimeActivity)
         installRuntimeActivityTracking(server, options.runtimeActivity);
-    toolCatalog.registerAll(server);
+    if (options.projectStructuredContentAsText === true) {
+        installStructuredContentTextProjection(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, {