ast-mcp-server 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -6,7 +6,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.10.0] — local release candidate, pending release (2026-08-19)
+## [0.11.1] — local recovery candidate, pending release (2026-08-23)
+
+### Fixed
+
+- Public- and local-registry consumer verification now share one dependency-free managed-skill validator that derives the expected release version from the bundled skill metadata, compares installed copies byte-for-byte, and rejects embedded managed guidance.
+- The exact-tree release matrix now runs `test:local-registry` under both supported Node.js lanes, preventing managed-asset verifier drift from reaching publication again.
+
+### Release status
+
+- This local recovery candidate succeeds the immutable npm `0.11.0` publication, whose public-registry verification failed because two consumer validators still required skill bundle `4.4.0` while the published package correctly contained `4.5.0`. Version `0.11.0` remains under `next` only and must not be promoted, tagged, or released. Version `0.11.1` remains pending its exact-tree matrix, CI, and separately authorized delivery sequence; it has not been published or assigned to any dist-tag.
+
+## [0.11.0] — published to `next`, verification failed, not promoted (2026-08-23)
+
+### Added
+
+- Managed setup and `install-skill` now install manifested multi-file skill bundles atomically, verify every bundled digest, and admit exact npm-proven predecessor bytes without treating version text as ownership.
+- `ast-tool upgrade --check` inspects supported direct npm and Volta installations without mutation; `ast-tool upgrade` performs the safe direct update with isolated package-manager state and then reconciles managed assets.
+- CLI batch and doctor project selection now discovers the nearest `tsconfig.json` or `jsconfig.json` up to the Git or filesystem boundary, while rejecting same-level ambiguity and symlinked config identities.
+- `ast-tool doctor` reports bounded, privacy-safe compiler, session, index, and queue state with executable continuations; unavailable registered-session evidence is reported as `not_run` instead of being fabricated.
+
+### Fixed
+
+- Project watchers now ignore events owned by exact symbol-index cache artifacts while preserving legitimate source invalidations, including POSIX filenames containing a literal backslash.
+
+### Release status
+
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. Public-registry verification then failed because two consumer validators still required skill bundle `4.4.0` while the package correctly contained `4.5.0`; `0.11.0` was never promoted to `latest`, tagged in Git, or released on GitHub.
+
+## [0.10.0] — published to `latest` and `next`, registry verified (2026-08-22)
 
 ### Added
 
@@ -20,7 +48,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Release status
 
-- This local candidate is pending its exact-tree release matrix, CI, and the repository's separately authorized delivery sequence. It has not been published to npm, assigned to `next` or `latest`, tagged in Git, or released on GitHub; registry and GitHub readbacks remain authoritative.
+- 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.10.0`, and the annotated `v0.10.0` tag plus GitHub Release resolve to the same release commit.
 
 ## [0.9.2] — local release candidate, pending release (2026-08-16)
 

package/README.md

@@ -84,11 +84,11 @@ The included batch benchmark records a 50% reduction in model round-trips and a
 
 ## Supported environment and trust boundary
 
-The local `0.10.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.8.1 retains its immutable historical Node.js 22.5.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.
+The local `0.11.1` recovery 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.
 
 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.
 
-In the local `0.10.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.10.0 and the local `0.11.1` recovery 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.
 
 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:
 
@@ -131,6 +131,29 @@ The package exposes two executables when installed:
 - `ast-mcp-server`: MCP stdio server.
 - `ast-tool`: batch, skill-installation, and agent-setup CLI.
 
+### Diagnose the active installation
+
+```bash
+ast-tool doctor [--project <config-or-dir>]
+```
+
+Doctor reuses CLI project discovery and existing runtime authorities without changing project,
+agent, package, or skill state. It prints bounded JSON; exit `0` is healthy, `1` degraded, and `2`
+failed. A healthy compiler remains usable when only the derived SQLite index is degraded.
+Standalone diagnosis marks registered-session-only index and queue evidence as `not_run` rather
+than fabricating healthy state.
+
+### Upgrade an installed package
+
+Inspect the active global installation without writing, or update it immediately:
+
+```bash
+ast-tool upgrade --check
+ast-tool upgrade
+```
+
+Upgrade supports only a direct package proven to belong to the active npm global prefix or to Volta. It rejects linked/source and ambiguous installations, never uses `sudo`, guesses from `PATH`, or accepts `--yes`. npm runs its proven `npm-cli.js` through the active Node with lifecycle scripts disabled and a disposable cache/config copy; cleanup is verified and blocks success if absence cannot be proven. Volta uses its native integration. The updated CLI then reconciles managed setup through that Node. Customized skill bytes remain untouched and produce `ast-tool setup --agents all --yes --force-skill`. Restart MCP clients after any package update; an already-running server does not change in place.
+
 ## Guided agent setup
 
 The installed package opens the interactive wizard with:
@@ -362,6 +385,8 @@ Example search-to-source pipeline:
 
 A `$ref` is an RFC 6901 JSON Pointer rooted at prior step results. References cannot point forward. If `emit` is omitted, only the final step result is returned; intermediate results remain inside the process.
 
+For CLI batches only, omit `project_root` or provide a directory to select the nearest `tsconfig.json` or `jsconfig.json` from the invocation directory upward. An explicit config file always wins. Discovery stops at a `.git` or filesystem boundary and rejects same-level ambiguity or symlinked identities; MCP tool calls still require an explicit `project_root`.
+
 `ast_find_test_candidates` and `ast_explore` are admitted as read steps. The batch runner injects the pipeline `project_root`, rejects a conflicting step root, and invokes the same registered MCP implementation. Candidate relationship proofs and exploration clusters remain whole; final JSON and TOON differ only in serialization, not logical evidence.
 
 ### Bounded foreach

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.10.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.8.1 retains its immutable Node.js 22.5.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. The local `0.11.1` recovery 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.
 
 ## Reporting a vulnerability
 

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
+import path from "node:path";
 import process from "node:process";
 import { ZodError } from "zod";
 import { BatchExecutionError, parseBatchDocument, runBatchDocument } from "./batch/runner.js";
@@ -10,6 +11,12 @@ import { clearSymbolIndexCache, inspectSymbolIndexCache, SymbolIndexCacheError,
 import { AgentSetupError, detectInstalledAgents, resolveServerEntryPath, runAgentSetup, } from "./services/agent-setup.js";
 import { installBundledSkill, resolveBundledSkillAssets, } from "./services/skill-installer.js";
 import { parseAgentsArgument, promptForAgentSelection, resolveAgentSelection, } from "./services/setup-wizard.js";
+import { runUpgradeLease, UpgradeCommandError } from "./services/upgrade-command.js";
+import { reconcileUpgrade } from "./services/upgrade-reconcile.js";
+import { createUpgradeRuntime, UpgradeCleanupError } from "./services/upgrade-runtime.js";
+import { UpgradeError } from "./services/upgrade.js";
+import { CliProjectDiscoveryError, resolveCliBatchProject, } from "./services/cli-project-discovery.js";
+import { runDoctor } from "./services/doctor.js";
 class CliError extends Error {
     code;
     exitCode;
@@ -34,8 +41,10 @@ function usage() {
         "  ast-tool apply <plan.astplan> --plan-hash <sha256>",
         "  ast-tool cache inspect",
         "  ast-tool cache clear --yes",
+        "  ast-tool doctor [--project <config-or-dir>]",
         "  ast-tool install-skill [claude|hermes|all] [--scope user|project] [--project-root <path>] [--force]",
         "  ast-tool setup [--agents claude,hermes|all --yes] [--force-skill]",
+        "  ast-tool upgrade [--check]",
     ].join("\n");
 }
 async function readStdinBounded() {
@@ -71,6 +80,13 @@ function parseApplyArgs(args) {
     }
     return { planFile: args[0], planHash: args[2] };
 }
+function parseDoctorArgs(args) {
+    if (args.length === 0)
+        return {};
+    if (args.length === 2 && args[0] === "--project" && args[1] && !args[1].startsWith("--"))
+        return { project: args[1] };
+    throw new CliError(usage(), "USAGE", 2, "doctor");
+}
 function parseRunArgs(args) {
     let source;
     let outputFormat = "json";
@@ -184,18 +200,37 @@ function parseSetupArgs(args) {
 }
 async function parseDocumentForCommand(source, command) {
     try {
-        return parseBatchDocument(await readBatchInput(source));
+        const input = await readBatchInput(source);
+        return parseBatchDocument(await resolveCliBatchProject(input, process.cwd()));
     }
     catch (error) {
         if (error instanceof CliError) {
             throw new CliError(error.message, error.code, 2, command, error.stepId, { cause: error });
         }
+        if (error instanceof CliProjectDiscoveryError) {
+            const relativeSource = source === "-" ? source : path.relative(process.cwd(), path.resolve(source));
+            const shellSource = `'${relativeSource.replaceAll("'", `'\\''`)}'`;
+            throw new CliError(error.message, error.code, 2, command, undefined, undefined, {
+                continuation: `${error.continuation} Then run: ast-tool ${command} ${shellSource}`,
+            });
+        }
         const message = error instanceof ZodError ? error.issues.map((issue) => issue.message).join("; ") : error;
         throw new CliError(message instanceof Error ? message.message : String(message), "INVALID_BATCH", 2, command, undefined, { cause: error });
     }
 }
 export async function runCli(args) {
     const [command, ...commandArgs] = args;
+    if (command === "doctor") {
+        const executable = process.argv[1];
+        if (!executable)
+            throw new CliError(usage(), "USAGE", 2, command);
+        return runDoctor({
+            ...parseDoctorArgs(commandArgs),
+            cwd: process.cwd(),
+            executable,
+            environment: process.env,
+        });
+    }
     if (command === "run" || command === "validate") {
         const runArgs = command === "run"
             ? parseRunArgs(commandArgs)
@@ -320,6 +355,33 @@ export async function runCli(args) {
             throw new CliError(error instanceof Error ? error.message : String(error), "SKILL_INSTALL_ERROR", 1, command, undefined, { cause: error });
         }
     }
+    if (command === "upgrade") {
+        try {
+            const executable = process.argv[1];
+            if (!executable)
+                throw new Error("missing executable");
+            const lease = await createUpgradeRuntime(executable);
+            return await runUpgradeLease(commandArgs, lease, reconcileUpgrade);
+        }
+        catch (error) {
+            if (error instanceof UpgradeCommandError) {
+                throw new CliError(error.message, "USAGE", 2, command, undefined, { cause: error });
+            }
+            if (error instanceof UpgradeError) {
+                throw new CliError(error.message, error.code, 1, command, undefined, { cause: error }, {
+                    continuation: error.continuation,
+                });
+            }
+            if (error instanceof UpgradeCleanupError) {
+                throw new CliError(error.message, error.code, 1, command, undefined, undefined, {
+                    cleanup: "required",
+                    ...(error.primaryCode ? { primary_code: error.primaryCode } : {}),
+                    continuation: "ast-tool upgrade --check",
+                });
+            }
+            throw new CliError("Upgrade failed without exposing host details.", "UPGRADE_ERROR", 1, command, undefined, { cause: error });
+        }
+    }
     throw new CliError(usage(), "USAGE", 2, command ?? null);
 }
 function failure(error, command = null) {
@@ -363,6 +425,10 @@ async function main() {
         const result = await runCli(args);
         const outputFormat = args[0] === "run" ? parseRunArgs(args.slice(1)).outputFormat : "json";
         process.stdout.write(`${serializeCliSuccess(result, outputFormat)}\n`);
+        if (args[0] === "doctor") {
+            const status = result.status;
+            process.exitCode = status === "healthy" ? 0 : status === "degraded" ? 1 : 2;
+        }
     }
     catch (error) {
         const failed = failure(error, args[0] ?? null);

package/dist/services/agent-setup.js

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { randomUUID } from "node:crypto";
-import { planBundledSkillInstallation, SkillConflictError, } from "./skill-installer.js";
+import { applySkillInstallationPlan, 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";
@@ -29,14 +29,18 @@ export async function applyManagedAssetPlans(skillPlan, guidancePlan, context =
     const rollbackFailed = [];
     const authenticated = [];
     let activePlan;
+    let skillBundleApplying = true;
     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" })),
-        ];
+        await applySkillInstallationPlan(skillPlan, (file) => {
+            authenticated.push(file);
+            if (file.status !== "unchanged")
+                physicalWrites.push({ path: file.path, asset: "skill", status: file.status });
+        }, context, hooks);
+        skillBundleApplying = false;
+        const plans = guidancePlan.files.map((file) => ({ file, asset: "guidance" }));
         for (const { file, asset } of plans) {
             activePlan = { file, asset };
             for (const current of authenticated) {
@@ -55,6 +59,8 @@ export async function applyManagedAssetPlans(skillPlan, guidancePlan, context =
         return physicalWrites;
     }
     catch (error) {
+        if (skillBundleApplying)
+            physicalWrites.length = 0;
         if (activePlan !== undefined && activePlan.file.status !== "unchanged") {
             const write = {
                 path: activePlan.file.path,

package/dist/services/cli-project-discovery.js

@@ -0,0 +1,97 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+const EXPLICIT = "Set project_root to a direct config file.";
+export class CliProjectDiscoveryError extends Error {
+    code;
+    continuation;
+    constructor(code, message, continuation) {
+        super(message);
+        this.code = code;
+        this.continuation = continuation;
+        this.name = "CliProjectDiscoveryError";
+    }
+}
+function fail(code, message, continuation) {
+    throw new CliProjectDiscoveryError(code, message, continuation);
+}
+function same(left, right) {
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+async function directPath(value) {
+    let info;
+    try {
+        info = await lstat(value);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            fail("PROJECT_CONFIG_UNSAFE", "The requested CLI project location could not be inspected safely.", EXPLICIT);
+        fail("PROJECT_CONFIG_NOT_FOUND", "The requested CLI project location does not exist.", "Set project_root to an existing config file.");
+    }
+    if (info.isSymbolicLink())
+        fail("PROJECT_CONFIG_UNSAFE", "Symlinked CLI project locations are unsupported.", EXPLICIT);
+    const canonical = await realpath(value).catch(() => fail("PROJECT_CONFIG_UNSAFE", "CLI project identity could not be proven.", EXPLICIT));
+    if (!same(value, canonical))
+        fail("PROJECT_CONFIG_UNSAFE", "Symlinked CLI project ancestors are unsupported.", EXPLICIT);
+    return { path: canonical, file: info.isFile() };
+}
+async function configAt(directory, name) {
+    const candidate = path.join(directory, name);
+    try {
+        const direct = await directPath(candidate);
+        return direct.file ? direct.path : undefined;
+    }
+    catch (error) {
+        if (error instanceof CliProjectDiscoveryError && error.code === "PROJECT_CONFIG_NOT_FOUND")
+            return;
+        throw error;
+    }
+}
+async function hasGitBoundary(directory) {
+    return lstat(path.join(directory, ".git")).then(() => true, (error) => {
+        if (error.code === "ENOENT")
+            return false;
+        fail("PROJECT_CONFIG_UNSAFE", "The repository boundary could not be inspected safely.", EXPLICIT);
+    });
+}
+function relativeConfig(from, config) {
+    const relative = path.relative(from, config).split(path.sep).join("/");
+    return relative.startsWith(".") ? relative : `./${relative}`;
+}
+async function discover(start, relativeTo) {
+    const visited = new Set();
+    let directory = start;
+    while (!visited.has(directory)) {
+        visited.add(directory);
+        const [tsconfig, jsconfig] = await Promise.all([
+            configAt(directory, "tsconfig.json"),
+            configAt(directory, "jsconfig.json"),
+        ]);
+        if (tsconfig && jsconfig)
+            fail("PROJECT_CONFIG_AMBIGUOUS", "Both supported project configs exist at the nearest CLI project level.", `Set project_root to "${relativeConfig(relativeTo, tsconfig)}" or "${relativeConfig(relativeTo, jsconfig)}".`);
+        if (tsconfig || jsconfig)
+            return tsconfig ?? jsconfig;
+        if (await hasGitBoundary(directory))
+            break;
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    fail("PROJECT_CONFIG_NOT_FOUND", "No supported project config was found within the CLI discovery boundary.", "Set project_root to a config file.");
+}
+export async function resolveCliBatchProject(input, cwd) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return input;
+    const document = input;
+    const requested = document.project_root;
+    if (requested !== undefined && typeof requested !== "string")
+        return input;
+    const absolute = path.resolve(cwd, requested ?? cwd);
+    const direct = await directPath(absolute);
+    const projectRoot = direct.file
+        ? absolute.endsWith(".json")
+            ? direct.path
+            : fail("PROJECT_CONFIG_NOT_FOUND", "The explicit CLI project file is not a JSON config.", "Set project_root to a config file.")
+        : await discover(direct.path, cwd);
+    return { ...document, project_root: projectRoot };
+}

package/dist/services/doctor-continuation.js

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function relativeArgument(project, cwd) {
+    const requested = project ?? ".";
+    if (/[\0\r\n]/u.test(requested))
+        return ".";
+    const relative = path.relative(cwd, path.resolve(cwd, requested)).split(path.sep).join("/") || ".";
+    return relative.startsWith(".") ? relative : `./${relative}`;
+}
+function ambiguousArgument(project, cwd) {
+    let directory = path.resolve(cwd, project ?? ".");
+    while (true) {
+        const candidate = path.join(directory, "tsconfig.json");
+        if (existsSync(candidate) && existsSync(path.join(directory, "jsconfig.json")))
+            return relativeArgument(candidate, cwd);
+        if (existsSync(path.join(directory, ".git")))
+            break;
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return relativeArgument(path.join(project ?? ".", "tsconfig.json"), cwd);
+}
+export function buildDoctorConfigContinuation(state, discoveryContinuation, project, cwd) {
+    void discoveryContinuation;
+    const requested = state === "ambiguous" ? ambiguousArgument(project, cwd) : relativeArgument(project, cwd);
+    const command = `ast-tool doctor --project ${shellQuote(requested)}`;
+    if (state === "ambiguous")
+        return `Run: ${command}`;
+    return state === "unsafe"
+        ? `Replace the requested project location with a direct config, then run: ${command}`
+        : `Create the requested project location and a supported config, then run: ${command}`;
+}

package/dist/services/doctor-model.js

@@ -0,0 +1,77 @@
+import { sanitizePublicText } from "./public-errors.js";
+function item(code, status, summary, reasonCode, continuation, continuationTrusted = false) {
+    return {
+        code,
+        status,
+        summary: sanitizePublicText(summary),
+        reason_code: reasonCode,
+        ...(continuation
+            ? { continuation: continuationTrusted ? continuation : sanitizePublicText(continuation) }
+            : {}),
+    };
+}
+function overall(checks) {
+    if (checks.some((check) => check.status === "failed"))
+        return "failed";
+    return checks.some((check) => check.status === "degraded") ? "degraded" : "healthy";
+}
+export function evaluateDoctor(evidence) {
+    const checks = [];
+    checks.push(evidence.runtime_invalid
+        ? item("runtime_policy", "degraded", "Runtime limits contain invalid values and defaults were applied.", "invalid_runtime_policy", "Fix AST runtime limit values, then run: ast-tool doctor")
+        : item("runtime_policy", "healthy", "Runtime limits are admitted.", "runtime_policy_ready"));
+    checks.push(evidence.config.state === "ready"
+        ? item("project_config", "healthy", "A unique project config was resolved.", "config_ready")
+        : item("project_config", "failed", "Project config discovery did not produce a safe unique identity.", `config_${evidence.config.state}`, evidence.config.continuation, evidence.config.continuation_trusted));
+    if (evidence.project) {
+        const { compiler, watcher, index, operation_queue: queue } = evidence.project;
+        checks.push(compiler.state === "ready"
+            ? item("compiler", "healthy", "Compiler synchronization is ready.", "compiler_ready")
+            : item("compiler", compiler.state === "failed" ? "failed" : "degraded", "Compiler synchronization is not ready.", `compiler_${compiler.state}`, "Run: ast-tool doctor"));
+        checks.push(watcher.state === "ready"
+            ? item("watcher", "healthy", "Project watcher is ready.", "watcher_ready")
+            : item("watcher", "degraded", "Project watcher is unavailable; compiler reads may require resynchronization.", `watcher_${watcher.state}`, "Restart MCP clients, then run: ast-tool doctor"));
+        checks.push(evidence.project_authority === "isolated" && index.state === "disabled"
+            ? item("derived_index", "not_run", "Persistent derived-index inspection is disabled for an isolated diagnosis.", "index_not_run_diagnostic_policy")
+            : index.state === "ready" || index.state === "disabled"
+                ? item("derived_index", "healthy", index.state === "ready"
+                    ? "Derived symbol index is ready."
+                    : "Derived symbol index is disabled by admitted policy.", `index_${index.state}`)
+                : item("derived_index", "degraded", compiler.state === "ready"
+                    ? "Derived index is unavailable; compiler-backed file operations remain available."
+                    : "Derived index is unavailable while compiler synchronization is not ready.", compiler.state === "ready" ? "index_degraded_compiler_ready" : `index_${index.state}`, "Run: ast-tool cache inspect"));
+        const queueDegraded = evidence.runtime_admission !== "open" ||
+            queue.admission !== "open" ||
+            queue.rejected_operations > 0 ||
+            queue.queue_timeout_operations > 0 ||
+            queue.deadline_exceeded_operations > 0;
+        checks.push(evidence.project_authority === "isolated" && evidence.runtime_admission === "open"
+            ? item("operation_queue", "not_run", "No registered project queue exists to inspect.", "queue_not_run_no_registered_session")
+            : queueDegraded
+                ? item("operation_queue", "degraded", "Operation queue reports admission or timeout pressure.", evidence.runtime_admission === "closed"
+                    ? "runtime_admission_closed"
+                    : "queue_pressure", "Run: ast-tool doctor")
+                : item("operation_queue", "healthy", "Operation queue is accepting work.", "queue_ready"));
+    }
+    else if (evidence.config.state === "ready" && evidence.project_authority === "unavailable") {
+        checks.push(item("compiler", "not_run", "Compiler diagnosis is unavailable while runtime admission is closed.", "compiler_not_run_runtime_closed"), item("watcher", "not_run", "Watcher check requires compiler diagnosis.", "watcher_not_run"), item("derived_index", "not_run", "Derived index check requires compiler diagnosis.", "index_not_run"), item("operation_queue", "degraded", "Project runtime admission is closed.", "runtime_admission_closed", "Restart MCP clients, then run: ast-tool doctor"));
+    }
+    else if (evidence.config.state === "ready") {
+        checks.push(item("compiler", "failed", "Compiler creation failed.", "compiler_creation_failed", "Run: ast-tool doctor"), item("watcher", "not_run", "Watcher check requires a ready compiler.", "watcher_not_run"), item("derived_index", "not_run", "Derived index check requires a ready compiler.", "index_not_run"), item("operation_queue", "not_run", "Queue check requires a diagnostic project.", "queue_not_run"));
+    }
+    else {
+        checks.push(item("compiler", "not_run", "Compiler check requires a project config.", "compiler_not_run"), item("watcher", "not_run", "Watcher check requires a project config.", "watcher_not_run"), item("derived_index", "not_run", "Derived index check requires a project config.", "index_not_run"), item("operation_queue", "not_run", "Queue check requires a project config.", "queue_not_run"));
+    }
+    checks.push(evidence.cache.state === "failed" || evidence.cache.unsafe_entry_count > 0
+        ? item("index_cache", "degraded", "Index cache inspection found unavailable or unsafe state.", evidence.cache.unsafe_entry_count > 0 ? "cache_unsafe" : "cache_failed", "Run: ast-tool cache inspect")
+        : item("index_cache", "healthy", `Index cache is ${evidence.cache.state}.`, `cache_${evidence.cache.state}`));
+    checks.push(evidence.package.state === "ready"
+        ? item("package", "healthy", `Package version ${evidence.package.version ?? "unknown"} is locally admitted.`, "package_ready")
+        : item("package", "degraded", "Running package provenance could not be admitted locally.", `package_${evidence.package.state}`, "Run: ast-tool upgrade --check"));
+    checks.push(evidence.setup.state === "ready"
+        ? item("client_setup", "healthy", "Detected client skills are current.", "setup_ready")
+        : item("client_setup", "degraded", "Detected client skill setup requires attention.", `setup_${evidence.setup.state}`, evidence.setup.state === "conflict"
+            ? "Run: ast-tool setup --agents all --yes --force-skill"
+            : "Run: ast-tool setup --agents all --yes"));
+    return { schema_version: 1, status: overall(checks), checks: checks.slice(0, 9) };
+}

package/dist/services/doctor.js

@@ -0,0 +1,111 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { detectInstalledAgents } from "./agent-setup.js";
+import { resolveCliBatchProject, CliProjectDiscoveryError } from "./cli-project-discovery.js";
+import { buildDoctorConfigContinuation } from "./doctor-continuation.js";
+import { evaluateDoctor } from "./doctor-model.js";
+import { getDiagnosticProjectStatus } from "./project.js";
+import { readRuntimePolicy } from "./runtime-policy.js";
+import { planBundledSkillInstallation, resolveBundledSkillAssets, SkillConflictError, } from "./skill-installer.js";
+import { inspectSymbolIndexCache, } from "./symbol-index-cache.js";
+async function resolveProject(project, cwd) {
+    const resolved = (await resolveCliBatchProject({ ...(project ? { project_root: project } : {}) }, cwd));
+    return resolved.project_root;
+}
+async function inspectPackage(executable) {
+    const cli = await realpath(executable);
+    const root = path.resolve(path.dirname(cli), "..");
+    const metadata = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    const bins = metadata.bin;
+    if (metadata.name !== "ast-mcp-server" ||
+        typeof metadata.version !== "string" ||
+        typeof bins?.["ast-tool"] !== "string" ||
+        (await realpath(path.resolve(root, bins["ast-tool"]))) !== cli)
+        return { state: "unsupported" };
+    return { state: "ready", version: metadata.version };
+}
+async function inspectSetup(executable, cwd, environment) {
+    const detections = await detectInstalledAgents({ environment, commandTimeoutMs: 5000 });
+    const installed = detections.filter((agent) => agent.installed);
+    if (installed.length === 0)
+        return { state: "ready" };
+    if (installed.some((agent) => agent.compatibility?.status !== "compatible"))
+        return { state: "outdated" };
+    const assets = await resolveBundledSkillAssets(executable);
+    try {
+        const plan = await planBundledSkillInstallation({
+            target: installed.map((agent) => agent.id),
+            scope: "user",
+            sourceSkillPath: assets.skillPath,
+            releaseManifestPath: assets.releasesPath,
+            environment,
+            ...(environment.HOME ? { homeDirectory: environment.HOME } : {}),
+            workingDirectory: cwd,
+        });
+        if (plan.installations.every((item) => item.status === "unchanged"))
+            return { state: "ready" };
+        return {
+            state: plan.installations.some((item) => item.status === "updated") ? "outdated" : "missing",
+        };
+    }
+    catch (error) {
+        if (error instanceof SkillConflictError)
+            return { state: "conflict" };
+        throw error;
+    }
+}
+const defaults = {
+    resolveProject,
+    projectStatus: getDiagnosticProjectStatus,
+    cache: (environment) => inspectSymbolIndexCache({ environment }),
+    package: inspectPackage,
+    setup: inspectSetup,
+    runtime: readRuntimePolicy,
+};
+export async function runDoctor(options, overrides = {}) {
+    const dependencies = { ...defaults, ...overrides };
+    const environment = options.environment ?? process.env;
+    const policy = dependencies.runtime(environment);
+    const runtimeInvalid = Object.values(policy.reasons).some((reason) => reason === "invalid_integer" || reason === "out_of_range");
+    let config = { state: "ready" };
+    let projectRoot;
+    try {
+        projectRoot = await dependencies.resolveProject(options.project, options.cwd);
+    }
+    catch (error) {
+        const discovery = error instanceof CliProjectDiscoveryError ? error : undefined;
+        const state = discovery?.code.endsWith("AMBIGUOUS")
+            ? "ambiguous"
+            : discovery?.code.endsWith("UNSAFE")
+                ? "unsafe"
+                : "missing";
+        config = {
+            state,
+            continuation: buildDoctorConfigContinuation(state, discovery?.continuation, options.project, options.cwd),
+            continuation_trusted: true,
+        };
+    }
+    let diagnostic;
+    if (projectRoot)
+        diagnostic = await dependencies.projectStatus(projectRoot).catch(() => undefined);
+    const [cache, packageEvidence, setup] = await Promise.all([
+        dependencies
+            .cache(environment)
+            .then((result) => ({ state: result.state, unsafe_entry_count: result.unsafe_entry_count }))
+            .catch(() => ({ state: "failed", unsafe_entry_count: 0 })),
+        dependencies.package(options.executable).catch(() => ({ state: "failed" })),
+        dependencies
+            .setup(options.executable, options.cwd, environment)
+            .catch(() => ({ state: "failed" })),
+    ]);
+    return evaluateDoctor({
+        runtime_invalid: runtimeInvalid,
+        project_authority: diagnostic?.authority ?? (projectRoot ? "failed" : "unavailable"),
+        runtime_admission: diagnostic?.runtime_admission ?? "open",
+        config,
+        ...(diagnostic?.status ? { project: diagnostic.status } : {}),
+        cache,
+        package: packageEvidence,
+        setup,
+    });
+}