ast-mcp-server 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -4,13 +4,45 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.7.2] — release candidate (unreleased, 2026-08-12)
+## [Unreleased]
+
+## [0.8.0] — release candidate (unreleased, 2026-08-14)
+
+### Fixed
+
+- OpenCode effective-config discovery and verification now run against disposable routed copies because the client normalizes both configured files even for diagnostic commands; the real planned destination remains snapshot-protected.
+
+### Added
+
+- Added managed `structural-code-editing` activation guidance for the verified Claude, OpenCode, Codex, and Gemini global instruction surfaces; Hermes and Copilot remain explicitly skill-only.
+- Added an exact SHA-256 release manifest for safe upgrades from registry-proven skill bytes and packaged the canonical marker-free guidance payload.
+
+### Changed
+
+- Setup now preflights MCP, skill, and guidance across every selected client before mutation, preserves user-owned instruction bytes, applies snapshot-checked descriptor-bound file writes, and reports schema v2 with logical outcomes plus completed, possibly committed, rolled-back, rollback-failed, pending, and successful physical asset states.
+- `install-skill` uses the same official-byte manifest but remains skill-only; explicit force never bypasses guidance ownership, route, or race checks.
+- Managed file writes hold staged and preimage inodes through publication, use no-clobber descriptor links for creation and atomic exchange with exact-pair rollback for replacement, reject same-inode content or mode races before cleanup, then reauthenticate unchanged/completed postimages before later asset or MCP writes.
+
+### Release status
+
+- This version is bound to exact-SHA CI and the repository's staged `next` publication, public-registry verification, `latest` promotion, annotated-tag, and hosted-release sequence. npm registry and GitHub readbacks remain authoritative for those external transitions.
+
+## [0.7.2] — published to `latest` and `next`, registry verified (2026-08-13)
 
 ### Fixed
 
 - Promotion preflight now validates raw npm registry metadata exactly once, compares live integrity with the verified artifact before and after mutation, and classifies the normalized readback without reinterpreting its field schema.
 - Added a composed regression covering eligible, already-promoted, and integrity-drift promotion readbacks.
 
+### Added
+
+- Expanded convergent setup to Claude Code, Hermes, OpenCode, Codex CLI, Gemini CLI, and GitHub Copilot CLI with fail-closed versioned contracts.
+- Added native checkbox selection, shared `.agents/skills` planning, routed JSONC-safe OpenCode configuration, bounded correlated diagnostics, and fixture admission gates.
+
+### Release status
+
+- npm exposes the immutable published `0.7.2` bytes under both `latest` and `next`. The `0.8.0` section above describes distinct release bytes and cannot be attributed to that package version.
+
 ## [0.7.1] — published to `next`, verified, not promoted (2026-08-12)
 
 ### Fixed

package/README.md

@@ -82,7 +82,7 @@ The included batch benchmark records a 50% reduction in model round-trips and a
 
 ## Supported environment and trust boundary
 
-The supported v0.7.2 target is Linux x64 with GNU coreutils `mv` supporting `--update=none-fail`, under Node.js 22.5.0 and the current Node.js 24 line. The production-readiness matrix covers both runtimes on that target; the Node 22.5 persistence canary requires `--experimental-sqlite`. Other Linux architectures or systems without the required GNU `mv`, macOS, and Windows are unverified until they pass equivalent filesystem, process, MCP/CLI/package, and mutation gates.
+The package engine floor remains Node.js `>=22.5.0`. The v0.8.0 release matrix covers Linux x64 under exact Node.js 22.5.0 and the current Node.js 24 line, including managed setup-file publication. That mutation 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 until equivalent exact-tree gates pass.
 
 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.
 
@@ -134,24 +134,44 @@ From a source checkout, use the Yarn script; it builds first and then opens the
 yarn setup
 ```
 
-The wizard detects Claude Code and Hermes from `PATH`, shows their executable and version, selects every detected agent by default, and lets you deselect agents before confirmation. For each selected agent it:
+The wizard supports exactly six CLI clients in this order: Claude Code, Hermes, OpenCode, Codex CLI, Gemini CLI, and GitHub Copilot CLI. Cursor, Windsurf, Cline, and other editor-integrated clients are intentionally excluded. Compatible detected clients start checked; unavailable or incompatible clients are disabled with a reason. Use Up/Down to move, Space to toggle, Enter to submit, or Escape/Ctrl-C to cancel.
 
-1. preflights any existing `ast` MCP registration;
-2. installs the bundled `structural-code-editing` skill;
-3. registers this package's MCP server through the agent's official CLI;
-4. reconnects and verifies the expected tools.
+1. preflights every selected client's existing `ast` MCP registration, skill destination, and effective managed-guidance destination;
+2. installs or safely upgrades the bundled `structural-code-editing` skill;
+3. adds one marker-owned activation block to each verified global instruction surface while preserving all user-owned bytes;
+4. registers this package's MCP server through the agent's official CLI;
+5. reconnects and verifies the expected tools.
 
-Existing matching registrations and skill files are unchanged. Conflicting MCP registrations fail before any write; remove or rename them explicitly instead of letting a setup script guess. Conflicting skill content also fails closed unless `--force-skill` is explicit.
+Existing matching registrations, skill files, and managed blocks are unchanged. Conflicting MCP registrations or malformed/unknown managed guidance fail before any write; resolve them explicitly instead of letting a setup script guess. Skill upgrades are automatic only when the installed bytes match an exact SHA-256 admitted from a published npm tarball. Unknown or customized skill bytes fail closed unless `--force-skill` is explicit. That flag applies only to the skill and cannot override guidance conflicts, unsafe routes, or filesystem races.
+
+Guidance uses each client's verified global instruction contract rather than one universal filename:
+
+| Client   | Managed guidance destination                                                                                          |
+| -------- | --------------------------------------------------------------------------------------------------------------------- |
+| Claude   | `$CLAUDE_CONFIG_DIR/CLAUDE.md`, or `~/.claude/CLAUDE.md`                                                              |
+| OpenCode | Effective native `AGENTS.md`; an existing Claude fallback may be shared or preserved when OpenCode has no native file |
+| Codex    | Non-empty `$CODEX_HOME/AGENTS.override.md`, otherwise `$CODEX_HOME/AGENTS.md`; `CODEX_HOME` defaults to `~/.codex`    |
+| Gemini   | The one supported safe `context.fileName` from `~/.gemini/settings.json`, otherwise `~/.gemini/GEMINI.md`             |
+| Hermes   | `skill_only`; setup does not modify `SOUL.md` or invent a global instruction destination                              |
+| Copilot  | `skill_only`; setup does not invent a personal global instruction destination                                         |
+
+The managed range is delimited by `ast-tool:structural-code-editing guidance v1` begin/end markers. Setup updates only that range, preserves the file's UTF-8 BOM, newline style, mode, and all content outside the range, and rejects duplicate, partial, reordered, unknown, symlinked, or non-regular destinations. Writes pin the parent chain, preimage, held temporary inode, and destination. New files use descriptor-bound no-clobber publication; replacements use an atomic same-directory exchange, validate both exchanged identities plus the pinned preimage bytes and mode, and roll the exact pair back when an in-call substitution or same-inode edit is detected. Every completed postimage is reauthenticated before later asset or MCP mutation. Cross-client setup is convergent rather than globally transactional.
+
+Successful setup output uses schema `version: 2`. Each agent reports `mcp`, `skill`, and `guidance`; physical writes include an `asset` of `skill`, `guidance`, or `mcp_config`. A complete replay returns every applicable item as `unchanged`/`skill_only` and an empty `physical_writes` array. A failed managed publication separates `completed_writes`, `possibly_committed`, `rolled_back`, `rollback_failed`, and `pending`; an uncertain commit or failed rollback is never reported as untouched and requires inspection plus a fresh replan.
 
 For automation, make the target set and confirmation explicit:
 
 ```bash
 ast-tool setup --agents all --yes
-ast-tool setup --agents claude --yes
+ast-tool setup --agents claude,codex --yes
 ```
 
 From a source checkout, replace `ast-tool` with `yarn setup` in those commands.
 
+`--agents all` is resolved only after detection and means every detected compatible client. If any detected client has unknown or incompatible output, setup fails before writes. Explicit IDs are strict and reject unavailable clients. Non-interactive setup requires both `--agents` and `--yes`.
+
+OpenCode 1.18.18 or newer is required. Because `opencode mcp add` ignores custom config routing, setup updates only `mcp.ast` in `OPENCODE_CONFIG`, then `OPENCODE_CONFIG_DIR/opencode.json`, then `~/.config/opencode/opencode.json`. JSONC comments, unrelated keys, and file mode are preserved. OpenCode's nominally diagnostic config command normalizes both routed config files, so setup runs discovery and verification against disposable copies while retaining the selected config bytes and fails closed if the planned real destination changes. Gemini setup may require trusting the current folder before registration. Diagnostics use a correlation ID and omit command arguments, environment, credentials, and raw provider output; setup failures may include a bounded destination path so the operator can inspect an uncertain or pending write.
+
 ## Install the agent skill
 
 The package bundles a `structural-code-editing` skill that teaches an agent when to use the AST tools, how to minimize context, and how to review mutations safely. Install it for both Claude Code and Hermes with one command:
@@ -169,10 +189,11 @@ ast-tool install-skill hermes
 
 The default is user scope. It writes to Claude Code's personal skill directory and to the active `HERMES_HOME`:
 
-| Target      | Destination                                                                                                |
-| ----------- | ---------------------------------------------------------------------------------------------------------- |
-| Claude Code | `$CLAUDE_CONFIG_DIR/skills/structural-code-editing/SKILL.md`, or `~/.claude/skills/...` by default         |
-| Hermes      | `$HERMES_HOME/skills/software-development/structural-code-editing/SKILL.md`, or `~/.hermes/...` by default |
+| Target                           | Destination                                                                                                |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Claude Code                      | `$CLAUDE_CONFIG_DIR/skills/structural-code-editing/SKILL.md`, or `~/.claude/skills/...` by default         |
+| Hermes                           | `$HERMES_HOME/skills/software-development/structural-code-editing/SKILL.md`, or `~/.hermes/...` by default |
+| OpenCode, Codex, Gemini, Copilot | `~/.agents/skills/structural-code-editing/SKILL.md` (one physical write, four logical outcomes)            |
 
 To commit the skill into one project for Claude Code, use project scope:
 
@@ -182,7 +203,7 @@ ast-tool install-skill claude --scope project --project-root /absolute/project
 
 This writes `.claude/skills/structural-code-editing/SKILL.md` below that project. Project scope is intentionally rejected for Hermes because Hermes skills belong to a profile, not a source repository.
 
-Installation is idempotent. Existing identical content is left untouched; different content fails closed unless `--force` is explicit. From an unlinked source checkout, replace `ast-tool` with `yarn node /absolute/path/to/ast-mcp-server/dist/cli.js`.
+Installation is idempotent. Existing current bytes are left untouched; exact predecessor bytes admitted by the bundled npm-provenance manifest are upgraded safely. Unknown or customized bytes fail closed unless `--force` is explicit. `install-skill` never writes global guidance or configures MCP. From an unlinked source checkout, replace `ast-tool` with `yarn node /absolute/path/to/ast-mcp-server/dist/cli.js`.
 
 Claude Code detects changes in an existing skill directory live; restart it if the top-level skills directory did not exist when the session started. In Hermes, run `/reload-skills` or start a new session, then verify with `hermes skills list`.
 
@@ -421,11 +442,12 @@ yarn build
 yarn test:mcp
 yarn test:cli
 yarn test:package
+yarn test:installed-agents
 yarn npm audit --all --recursive
 yarn pack --dry-run
 ```
 
-`test:mcp` exercises the built stdio server. `test:cli` runs a read pipeline and a prepare/apply/replay workflow across separate Node processes.
+`test:mcp` exercises the built stdio server. `test:cli` runs a read pipeline and a prepare/apply/replay workflow across separate Node processes. `test:installed-agents` is a host-dependent manual gate: it builds first, detects locally installed supported clients, uses only disposable homes/config roots, verifies deterministic effective discovery without model calls, reports unavailable clients, and removes the disposable state. It is not a portable CI requirement because CI does not install every external client.
 
 ## Benchmarks
 

package/SECURITY.md

@@ -2,16 +2,16 @@
 
 ## Supported versions
 
-Security fixes are provided for the latest published minor release and the current `main` development line. During the v0.7.2 release-candidate cycle, the support window is:
+Security fixes are provided for the exact version currently identified by the npm registry's `latest` dist-tag and for the current `main` development line. The support window is registry-authoritative:
 
-| Version                            | Supported                          |
-| ---------------------------------- | ---------------------------------- |
-| `main` / v0.7.2 release candidates | Yes                                |
-| 0.6.x                              | Yes, until v0.7.2 becomes `latest` |
-| 0.7.0 / 0.7.1                      | No, superseded `next` candidates   |
-| 0.5.x and earlier                  | No                                 |
+| Release state                               | Supported |
+| ------------------------------------------- | --------- |
+| `main` / `Unreleased`                       | Yes       |
+| Exact npm version currently tagged `latest` | Yes       |
+| Earlier npm versions                        | No        |
+| Unpublished release candidates              | No        |
 
-This project supports trusted single-user local stdio use. The current v0.7.2 target supports Linux x64 only when GNU coreutils `mv` provides `--update=none-fail`, with Node.js 22.5.0 or the current Node.js 24 line. Other Linux architectures, systems without that primitive, macOS and Windows are unverified. 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. The package engine floor is Node.js `>=22.5.0`, and the v0.8.0 release matrix covers Linux x64 under exact Node.js 22.5.0 and the current Node.js 24 line, including managed setup-file publication. That 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`. 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/dist/cli.js

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import process from "node:process";
-import { createInterface } from "node:readline/promises";
 import { ZodError } from "zod";
 import { BatchExecutionError, parseBatchDocument, runBatchDocument } from "./batch/runner.js";
 import { MAX_BATCH_INPUT_BYTES, isPrepareBatchTool } from "./batch/schema.js";
 import { CliOutputError, serializeCliSuccess } from "./cli-output.js";
 import { applyPersistedOperation, persistOperationPlan } from "./services/operation-plan-file.js";
 import { AgentSetupError, detectInstalledAgents, resolveServerEntryPath, runAgentSetup, } from "./services/agent-setup.js";
-import { installBundledSkill, resolveBundledSkillPath, } from "./services/skill-installer.js";
-import { parseAgentsArgument, promptForAgentSelection, } from "./services/setup-wizard.js";
+import { installBundledSkill, resolveBundledSkillAssets, } from "./services/skill-installer.js";
+import { parseAgentsArgument, promptForAgentSelection, resolveAgentSelection, } from "./services/setup-wizard.js";
 class CliError extends Error {
     code;
     exitCode;
@@ -241,30 +240,33 @@ export async function runCli(args) {
         const options = parseSetupArgs(commandArgs);
         try {
             const detections = await detectInstalledAgents();
-            let agents = options.agents;
-            if (agents === undefined) {
+            let agents;
+            if (options.agents === undefined) {
                 if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
                     throw new CliError("Interactive setup requires a TTY. Use --agents claude,hermes --yes for automation.", "USAGE", 2, command);
                 }
-                const prompt = createInterface({ input: process.stdin, output: process.stderr });
-                try {
-                    agents = await promptForAgentSelection(detections, (question) => prompt.question(question));
-                }
-                finally {
-                    prompt.close();
-                }
+                agents = await promptForAgentSelection(detections, {
+                    input: process.stdin,
+                    output: process.stderr,
+                    signals: process,
+                });
                 if (agents.length === 0) {
                     return { status: "cancelled", command: "setup", agents: [] };
                 }
             }
+            else
+                agents = resolveAgentSelection(options.agents, detections);
             const executablePath = process.argv[1];
             if (!executablePath) {
                 throw new Error("Cannot resolve the ast-tool executable path.");
             }
+            const assets = await resolveBundledSkillAssets(executablePath);
             return await runAgentSetup({
                 agents,
                 detections,
-                sourceSkillPath: await resolveBundledSkillPath(executablePath),
+                sourceSkillPath: assets.skillPath,
+                sourceGuidancePath: assets.guidancePath,
+                releaseManifestPath: assets.releasesPath,
                 serverEntryPath: await resolveServerEntryPath(executablePath),
                 forceSkill: options.forceSkill,
             });
@@ -286,9 +288,11 @@ export async function runCli(args) {
             if (!executablePath) {
                 throw new Error("Cannot resolve the ast-tool executable path.");
             }
+            const assets = await resolveBundledSkillAssets(executablePath);
             return await installBundledSkill({
                 ...options,
-                sourceSkillPath: await resolveBundledSkillPath(executablePath),
+                sourceSkillPath: assets.skillPath,
+                releaseManifestPath: assets.releasesPath,
             });
         }
         catch (error) {

package/dist/services/agent-setup.js

@@ -1,10 +1,15 @@
 import { spawn } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
 import { access, realpath, stat } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
-import { installBundledSkill, SkillConflictError, } from "./skill-installer.js";
-import { AGENT_IDS, getAgentTarget, MCP_SERVER_NAME, } from "./agent-targets.js";
+import { randomUUID } from "node:crypto";
+import { planBundledSkillInstallation, SkillConflictError, } from "./skill-installer.js";
+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";
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
 export class AgentSetupError extends Error {
@@ -17,6 +22,87 @@ export class AgentSetupError extends Error {
         this.details = details;
     }
 }
+export async function applyManagedAssetPlans(skillPlan, guidancePlan, context = createManagedFileApplyContext(), hooks = {}) {
+    const physicalWrites = [];
+    const possiblyCommitted = [];
+    const rolledBack = [];
+    const rollbackFailed = [];
+    const authenticated = [];
+    let activePlan;
+    try {
+        for (const file of [...skillPlan.files, ...guidancePlan.files]) {
+            await revalidateManagedFilePlan(file);
+        }
+        const plans = [
+            ...skillPlan.files.map((file) => ({ file, asset: "skill" })),
+            ...guidancePlan.files.map((file) => ({ file, asset: "guidance" })),
+        ];
+        for (const { file, asset } of plans) {
+            activePlan = { file, asset };
+            for (const current of authenticated) {
+                await verifyManagedFilePostimage(current, context);
+            }
+            await applyManagedFilePlan(file, context, hooks);
+            authenticated.push(file);
+            if (file.status !== "unchanged") {
+                physicalWrites.push({ path: file.path, asset, status: file.status });
+            }
+            activePlan = undefined;
+        }
+        for (const current of authenticated) {
+            await verifyManagedFilePostimage(current, context);
+        }
+        return physicalWrites;
+    }
+    catch (error) {
+        if (activePlan !== undefined && activePlan.file.status !== "unchanged") {
+            const write = {
+                path: activePlan.file.path,
+                asset: activePlan.asset,
+                status: activePlan.file.status,
+            };
+            if (error instanceof ManagedFileRollbackError) {
+                rolledBack.push(write);
+            }
+            else if (error instanceof ManagedFileApplyError) {
+                if (error.commitState === "committed") {
+                    physicalWrites.push(write);
+                }
+                else {
+                    possiblyCommitted.push(write);
+                }
+                if (error.rollbackState === "failed") {
+                    rollbackFailed.push(write);
+                }
+            }
+        }
+        throw new AgentSetupError(error instanceof Error ? error.message : "Managed asset apply failed.", "AGENT_ASSET_APPLY_FAILED", {
+            completed_writes: physicalWrites,
+            possibly_committed: possiblyCommitted,
+            rolled_back: rolledBack,
+            rollback_failed: rollbackFailed,
+            pending: [
+                ...skillPlan.files
+                    .filter((file) => file.status !== "unchanged")
+                    .map((file) => ({ path: file.path, asset: "skill", status: file.status })),
+                ...guidancePlan.files
+                    .filter((file) => file.status !== "unchanged")
+                    .map((file) => ({ path: file.path, asset: "guidance", status: file.status })),
+            ].filter((pending) => !physicalWrites.some((completed) => completed.path === pending.path && completed.asset === pending.asset) &&
+                !possiblyCommitted.some((uncertain) => uncertain.path === pending.path && uncertain.asset === pending.asset)),
+        });
+    }
+}
+async function verifyManagedAssetPlans(skillPlan, guidancePlan, context) {
+    try {
+        for (const file of [...skillPlan.files, ...guidancePlan.files]) {
+            await verifyManagedFilePostimage(file, context);
+        }
+    }
+    catch (error) {
+        throw new AgentSetupError(error instanceof Error ? error.message : "Managed asset postimage verification failed.", "AGENT_ASSET_APPLY_FAILED", { cause: error instanceof Error ? error.message : String(error) });
+    }
+}
 function environmentPath(environment) {
     return environment.PATH ?? environment.Path ?? environment.path ?? "";
 }
@@ -76,7 +162,7 @@ async function runCommand(executable, args, options) {
         const appendOutput = (target, chunk) => {
             outputBytes += chunk.byteLength;
             if (outputBytes > MAX_COMMAND_OUTPUT_BYTES) {
-                finishWithError(new AgentSetupError(`Agent command exceeded ${MAX_COMMAND_OUTPUT_BYTES} output bytes.`, "AGENT_COMMAND_OUTPUT_LIMIT", { executable, args }));
+                finishWithError(new AgentSetupError(`Agent command exceeded ${MAX_COMMAND_OUTPUT_BYTES} output bytes.`, "AGENT_COMMAND_OUTPUT_LIMIT"));
                 return;
             }
             if (target === "stdout") {
@@ -87,15 +173,12 @@ async function runCommand(executable, args, options) {
             }
         };
         const timeout = setTimeout(() => {
-            finishWithError(new AgentSetupError(`Agent command timed out after ${options.timeoutMs}ms.`, "AGENT_COMMAND_TIMEOUT", { executable, args }));
+            finishWithError(new AgentSetupError(`Agent command timed out after ${options.timeoutMs}ms.`, "AGENT_COMMAND_TIMEOUT"));
         }, options.timeoutMs);
         child.stdout.on("data", (chunk) => appendOutput("stdout", chunk));
         child.stderr.on("data", (chunk) => appendOutput("stderr", chunk));
-        child.on("error", (error) => {
-            finishWithError(new AgentSetupError(`Failed to start ${executable}: ${error.message}`, "AGENT_COMMAND_START", {
-                executable,
-                args,
-            }));
+        child.on("error", () => {
+            finishWithError(new AgentSetupError("Failed to start the agent command.", "AGENT_COMMAND_START"));
         });
         child.on("close", (exitCode) => {
             if (settled) {
@@ -109,8 +192,7 @@ async function runCommand(executable, args, options) {
     });
 }
 function commandFailure(agent, operation, result) {
-    const output = `${result.stdout}\n${result.stderr}`.trim().slice(0, 4000);
-    return new AgentSetupError(`${getAgentTarget(agent).label} ${operation} failed with exit code ${result.exitCode}.`, "AGENT_COMMAND_FAILED", { agent, operation, output });
+    return new AgentSetupError(`${getAgentTarget(agent).label} ${operation} failed with exit code ${result.exitCode}.`, "AGENT_COMMAND_FAILED", { agent, operation, reason: `Command exited with code ${result.exitCode}.` });
 }
 function targetRuntime(detection, environment, timeoutMs) {
     return {
@@ -136,6 +218,33 @@ async function inspectMcp(agent, detection, serverEntryPath, nodeExecutable, env
         ...(inspection.detail ? { detail: inspection.detail } : {}),
     };
 }
+async function verifyOpenCode(detection, environment, timeoutMs, context) {
+    await withIsolatedOpenCodeConfig(environment, environment.HOME ?? os.homedir(), async (isolatedEnvironment) => {
+        const runtime = targetRuntime(detection, isolatedEnvironment, timeoutMs);
+        const resolved = await runtime.run(["debug", "config", "--pure"]);
+        if (resolved.exitCode !== 0)
+            throw commandFailure("opencode", "resolved configuration verification", resolved);
+        let config;
+        try {
+            config = JSON.parse(resolved.stdout);
+        }
+        catch {
+            throw new AgentSetupError("OpenCode resolved configuration output is unknown.", "AGENT_VERIFICATION_FAILED", { agent: "opencode" });
+        }
+        const command = config?.mcp?.ast?.command;
+        if (!Array.isArray(command) ||
+            command.length !== 2 ||
+            command[0] !== context.nodeExecutable ||
+            command[1] !== context.serverEntryPath) {
+            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"]);
+        const plainList = listed.stdout.replaceAll("\u001b", "");
+        if (listed.exitCode !== 0 || !/ast[\s\S]*connected/i.test(plainList)) {
+            throw new AgentSetupError("OpenCode did not report the ast server as connected.", "AGENT_VERIFICATION_FAILED", { agent: "opencode" });
+        }
+    });
+}
 async function configureMcp(agent, detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
     const target = getAgentTarget(agent);
     const added = await target.mcp.register(targetRuntime(detection, environment, timeoutMs), {
@@ -175,7 +284,12 @@ export async function detectInstalledAgents(options = {}) {
         const definition = getAgentTarget(id);
         const executable = await findExecutable(definition.command, environment);
         if (executable === undefined) {
-            return { id, label: definition.label, installed: false };
+            return {
+                id,
+                label: definition.label,
+                installed: false,
+                compatibility: { status: "unavailable", reason: "Not found in PATH." },
+            };
         }
         let version;
         try {
@@ -191,10 +305,17 @@ export async function detectInstalledAgents(options = {}) {
         catch {
             version = undefined;
         }
-        return { id, label: definition.label, installed: true, executable, version };
+        const compatibility = version === undefined
+            ? {
+                status: "incompatible",
+                reason: "Version command did not produce admitted evidence.",
+            }
+            : classifyAgentVersion(id, version);
+        return { id, label: definition.label, installed: true, executable, version, compatibility };
     }));
 }
 export async function runAgentSetup(options) {
+    const correlationId = randomUUID();
     const environment = options.environment ?? process.env;
     const nodeExecutable = options.nodeExecutable ?? process.execPath;
     const timeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
@@ -208,42 +329,137 @@ export async function runAgentSetup(options) {
         if (!detection?.installed || detection.executable === undefined) {
             throw new AgentSetupError(`${getAgentTarget(agent).label} is not installed or is not available in PATH.`, "AGENT_NOT_INSTALLED", { agent });
         }
+        if (detection.compatibility && detection.compatibility.status !== "compatible") {
+            throw new AgentSetupError(`${getAgentTarget(agent).label} is incompatible: ${detection.compatibility.reason}`, detection.compatibility.status === "blocked_untrusted_folder"
+                ? "AGENT_TRUST_REQUIRED"
+                : "AGENT_INCOMPATIBLE", { agent, correlation_id: correlationId });
+        }
     }
     await assertRegularFile(options.serverEntryPath, "MCP server entrypoint");
     await assertRegularFile(options.sourceSkillPath, "Bundled skill");
-    const inspections = await Promise.all(requested.map((agent) => inspectMcp(agent, detectionMap.get(agent), options.serverEntryPath, nodeExecutable, environment, timeoutMs)));
+    let openCodePlan;
+    if (requested.includes("opencode")) {
+        openCodePlan = await planOpenCodeConfig({
+            filePath: resolveOpenCodeConfigPath(environment, environment.HOME ?? os.homedir()),
+            nodeExecutable,
+            serverEntryPath: options.serverEntryPath,
+        }).catch((error) => {
+            throw new AgentSetupError(error instanceof Error ? error.message : "OpenCode configuration preflight failed.", "AGENT_MCP_CONFLICT", { agent: "opencode", correlation_id: correlationId });
+        });
+        const effective = await withIsolatedOpenCodeConfig(environment, environment.HOME ?? os.homedir(), (isolatedEnvironment) => targetRuntime(detectionMap.get("opencode"), isolatedEnvironment, timeoutMs).run([
+            "debug",
+            "config",
+            "--pure",
+        ]));
+        if (effective.exitCode !== 0) {
+            throw new AgentSetupError(`OpenCode effective configuration preflight failed with exit code ${effective.exitCode}.`, "AGENT_MCP_CONFLICT", { agent: "opencode", correlation_id: correlationId });
+        }
+        let effectiveConfig;
+        try {
+            effectiveConfig = JSON.parse(effective.stdout);
+        }
+        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)) {
+            throw new AgentSetupError("OpenCode effective configuration conflict at mcp.ast.", "AGENT_MCP_CONFLICT", { agent: "opencode", correlation_id: correlationId });
+        }
+        if (effectiveAst !== undefined && openCodePlan.status === "installed") {
+            openCodePlan = { ...openCodePlan, status: "unchanged" };
+        }
+    }
+    const inspections = await Promise.all(requested.map((agent) => agent === "opencode"
+        ? Promise.resolve({
+            agent,
+            status: openCodePlan?.status === "unchanged" ? "current" : "missing",
+        })
+        : inspectMcp(agent, detectionMap.get(agent), options.serverEntryPath, nodeExecutable, environment, timeoutMs)));
     const conflict = inspections.find((item) => item.status === "conflict");
     if (conflict !== undefined) {
         throw new AgentSetupError(`Conflicting ${getAgentTarget(conflict.agent).label} MCP registration: ${conflict.detail}`, "AGENT_MCP_CONFLICT", { agent: conflict.agent });
     }
-    const skillTarget = requested.length === AGENT_IDS.length ? "all" : getAgentTarget(requested[0]).skillTarget;
-    const skillResult = await installBundledSkill({
-        target: skillTarget,
-        scope: "user",
-        force: options.forceSkill ?? false,
-        sourceSkillPath: options.sourceSkillPath,
-        environment,
-    }).catch((error) => {
+    const blocked = inspections.find((item) => item.status === "blocked_untrusted_folder");
+    if (blocked !== undefined) {
+        throw new AgentSetupError(`${getAgentTarget(blocked.agent).label} requires the working folder to be trusted before setup.`, "AGENT_TRUST_REQUIRED", { agent: blocked.agent, correlation_id: correlationId });
+    }
+    let skillPlan;
+    try {
+        skillPlan = await planBundledSkillInstallation({
+            target: requested,
+            scope: "user",
+            force: options.forceSkill ?? false,
+            sourceSkillPath: options.sourceSkillPath,
+            releaseManifestPath: options.releaseManifestPath,
+            environment,
+            homeDirectory: environment.HOME ?? os.homedir(),
+        });
+    }
+    catch (error) {
         if (error instanceof SkillConflictError) {
             throw new AgentSetupError(`Skill already exists with different content at ${error.destination}; pass --force-skill to replace it.`, "AGENT_SKILL_CONFLICT", { path: error.destination });
         }
-        throw error;
-    });
-    const skillStatuses = new Map(skillResult.installations.map((installation) => [installation.target, installation.status]));
+        throw new AgentSetupError(error instanceof Error ? error.message : "Skill preflight failed.", "SETUP_ASSET_INVALID", { asset: "skill", correlation_id: correlationId });
+    }
+    let guidancePlan;
+    try {
+        guidancePlan = await planManagedGuidance({
+            agents: requested,
+            sourceGuidancePath: options.sourceGuidancePath,
+            environment,
+            homeDirectory: environment.HOME ?? os.homedir(),
+        });
+    }
+    catch (error) {
+        throw new AgentSetupError(error instanceof Error ? error.message : "Managed guidance preflight failed.", "AGENT_GUIDANCE_CONFLICT", { asset: "guidance", correlation_id: correlationId });
+    }
+    const skillStatuses = new Map(skillPlan.installations.map((installation) => [installation.target, installation.status]));
+    const guidanceStatuses = new Map(guidancePlan.installations.map((installation) => [installation.agent, installation.status]));
+    const applyContext = createManagedFileApplyContext();
+    const physicalWrites = await applyManagedAssetPlans(skillPlan, guidancePlan, applyContext);
     const completed = [];
     for (const agent of requested) {
         const detection = detectionMap.get(agent);
         const inspection = inspections.find((item) => item.agent === agent);
         try {
+            await verifyManagedAssetPlans(skillPlan, guidancePlan, applyContext);
             if (inspection.status === "missing") {
-                await configureMcp(agent, detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
+                if (agent === "opencode") {
+                    await applyOpenCodeConfigPlan(openCodePlan);
+                    if (openCodePlan.status === "installed") {
+                        physicalWrites.push({
+                            path: openCodePlan.filePath,
+                            asset: "mcp_config",
+                            status: "installed",
+                        });
+                    }
+                    await verifyOpenCode(detection, environment, timeoutMs, {
+                        nodeExecutable,
+                        serverEntryPath: options.serverEntryPath,
+                    });
+                }
+                else
+                    await configureMcp(agent, detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
+            }
+            else if (agent === "opencode") {
+                await verifyOpenCode(detection, environment, timeoutMs, {
+                    nodeExecutable,
+                    serverEntryPath: options.serverEntryPath,
+                });
             }
+            await verifyManagedAssetPlans(skillPlan, guidancePlan, applyContext);
             completed.push({
                 agent,
                 executable: detection.executable,
                 version: detection.version,
                 mcp: inspection.status === "current" ? "unchanged" : "configured",
                 skill: skillStatuses.get(agent),
+                guidance: guidanceStatuses.get(agent),
             });
         }
         catch (error) {
@@ -251,16 +467,21 @@ export async function runAgentSetup(options) {
                 throw new AgentSetupError(error.message, error.code, {
                     cause: error.details,
                     completed,
-                    skills: skillResult.installations,
+                    skills: skillPlan.installations,
+                    guidance: guidancePlan.installations,
+                    completed_writes: physicalWrites,
                 });
             }
             throw error;
         }
     }
     return {
+        version: 2,
         status: "ok",
         command: "setup",
         server: { name: MCP_SERVER_NAME, command: nodeExecutable, args: [options.serverEntryPath] },
         agents: completed,
+        correlation_id: correlationId,
+        physical_writes: physicalWrites,
     };
 }