ast-mcp-server 0.10.0 → 0.11.1

package/dist/services/managed-bundle.js

@@ -0,0 +1,145 @@
+import path from "node:path";
+import { applyManagedFilePlan, canonicalizeFuturePath, captureManagedFilePreimage, captureManagedFileSnapshot, createManagedFileApplyContext, hashBytes, ManagedFileApplyError, rollbackManagedFilePlan, snapshotsEqual, verifyManagedFilePostimage, } from "./managed-file.js";
+export class ManagedBundleConflictError extends Error {
+    destination;
+    constructor(destination) {
+        super(`Managed bundle destination already exists with different content: ${destination}`);
+        this.destination = destination;
+        this.name = "ManagedBundleConflictError";
+    }
+}
+function validateRelease(release) {
+    const paths = new Set();
+    for (const file of release.files) {
+        if (file.path.includes("\\") ||
+            path.posix.isAbsolute(file.path) ||
+            path.win32.isAbsolute(file.path) ||
+            path.posix.normalize(file.path) !== file.path ||
+            file.path.startsWith("../") ||
+            file.path === ".") {
+            throw new Error(`Managed bundle contains an unsafe path: ${file.path}`);
+        }
+        if (paths.has(file.path))
+            throw new Error(`Managed bundle contains a duplicate path: ${file.path}`);
+        paths.add(file.path);
+    }
+}
+export async function planManagedBundle(options) {
+    validateRelease(options.current);
+    for (const predecessor of options.predecessors)
+        validateRelease(predecessor);
+    const signatures = [options.current, ...options.predecessors].map((release) => release.files
+        .map((file) => `${file.path}:${file.sha256}`)
+        .sort()
+        .join("\n"));
+    if (new Set(signatures).size !== signatures.length) {
+        throw new Error("Managed bundle contains a duplicate release digest.");
+    }
+    const currentPaths = new Set(options.current.files.map((file) => file.path));
+    if (options.predecessors.some((release) => release.files.some((file) => !currentPaths.has(file.path)))) {
+        throw new Error("Managed bundle predecessor contains an unmanaged current path.");
+    }
+    for (const file of options.current.files) {
+        if (hashBytes(file.content) !== file.sha256) {
+            throw new Error(`Managed bundle digest does not match source asset: ${file.path}`);
+        }
+    }
+    const canonicalRoot = path.dirname(await canonicalizeFuturePath(path.join(options.destinationRoot, ".managed-bundle-root")));
+    const destinations = await Promise.all(options.current.files.map(async (file) => ({
+        file,
+        destination: await canonicalizeFuturePath(path.join(options.destinationRoot, file.path)),
+    })));
+    for (const { destination } of destinations) {
+        const relative = path.relative(canonicalRoot, destination);
+        if (relative === "" ||
+            relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative)) {
+            throw new Error(`Managed bundle destination is outside the bundle root: ${destination}`);
+        }
+    }
+    if (new Set(destinations.map((entry) => entry.destination)).size !== destinations.length) {
+        throw new Error("Managed bundle contains a duplicate canonical destination.");
+    }
+    const entries = await Promise.all(destinations.map(async ({ file, destination }) => ({
+        file,
+        destination,
+        snapshot: await captureManagedFileSnapshot(destination),
+    })));
+    const exactCurrent = entries.every(({ file, snapshot }) => snapshot.exists && snapshot.sha256 === file.sha256);
+    const empty = entries.every(({ snapshot }) => !snapshot.exists);
+    const exactPredecessor = options.predecessors.some((release) => entries.every(({ file, snapshot }) => {
+        const predecessor = release.files.find((candidate) => candidate.path === file.path);
+        return predecessor === undefined
+            ? !snapshot.exists
+            : snapshot.exists && snapshot.sha256 === predecessor.sha256;
+    }));
+    if (!exactCurrent && !empty && !exactPredecessor && options.force !== true) {
+        throw new ManagedBundleConflictError(entries.find(({ snapshot }) => snapshot.exists)?.destination ?? options.destinationRoot);
+    }
+    return {
+        status: exactCurrent ? "unchanged" : empty ? "installed" : "updated",
+        files: entries.map(({ file, destination, snapshot }) => ({
+            path: destination,
+            snapshot,
+            postimage: file.content,
+            postimageSha256: file.sha256,
+            status: snapshot.exists && snapshot.sha256 === file.sha256
+                ? "unchanged"
+                : snapshot.exists
+                    ? "updated"
+                    : "installed",
+        })),
+    };
+}
+export async function applyManagedBundle(plan, onApplied, context = createManagedFileApplyContext(), hooks = {}) {
+    const preimages = new Map();
+    for (const file of plan.files) {
+        const preimage = await captureManagedFilePreimage(file.path);
+        if (!snapshotsEqual(preimage.snapshot, file.snapshot)) {
+            throw new Error(`Managed file changed after preflight: ${file.path}`);
+        }
+        preimages.set(file, preimage);
+    }
+    const authenticated = [];
+    const mutated = [];
+    let active;
+    try {
+        for (const file of plan.files) {
+            active = file;
+            for (const current of authenticated)
+                await verifyManagedFilePostimage(current, context);
+            await applyManagedFilePlan(file, context, hooks);
+            authenticated.push(file);
+            if (file.status !== "unchanged")
+                mutated.push(file);
+            await onApplied?.(file);
+            active = undefined;
+        }
+        for (const current of authenticated)
+            await verifyManagedFilePostimage(current, context);
+    }
+    catch (error) {
+        if (active !== undefined &&
+            active.status !== "unchanged" &&
+            error instanceof ManagedFileApplyError &&
+            !mutated.includes(active)) {
+            mutated.push(active);
+        }
+        const failures = [];
+        for (const file of mutated.reverse()) {
+            try {
+                await rollbackManagedFilePlan(file, preimages.get(file), context);
+            }
+            catch (rollbackError) {
+                failures.push(rollbackError);
+            }
+        }
+        if (failures.length) {
+            throw new AggregateError([error, ...failures], "Managed bundle rollback was incomplete.", {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}

package/dist/services/managed-file.js

@@ -499,6 +499,43 @@ export async function verifyManagedFilePostimage(plan, context) {
         await directory.close();
     }
 }
+export async function rollbackManagedFilePlan(plan, preimage, context) {
+    await verifyManagedFilePostimage(plan, context);
+    if (preimage.snapshot.exists) {
+        if (preimage.content === undefined) {
+            throw new Error(`Managed file rollback preimage is unavailable: ${plan.path}`);
+        }
+        const current = await captureManagedFileSnapshot(plan.path);
+        await applyManagedFilePlan({
+            path: plan.path,
+            snapshot: current,
+            postimage: preimage.content,
+            postimageSha256: preimage.snapshot.sha256,
+            status: "updated",
+        }, createManagedFileApplyContext());
+        return;
+    }
+    const directory = await openBoundDirectory(plan.snapshot.directory, false, context);
+    try {
+        const key = managedFileKey(plan);
+        let expected = context.authenticatedFiles.get(key);
+        if (expected === undefined) {
+            const current = await captureManagedFileSnapshot(plan.path);
+            if (!current.exists || current.sha256 !== plan.postimageSha256) {
+                throw new Error(`Managed installed file rollback postimage is unavailable: ${plan.path}`);
+            }
+            expected = { dev: current.dev, ino: current.ino };
+            context.authenticatedFiles.set(key, expected);
+        }
+        if ((await removePathIfOwned(directory, path.basename(plan.path), expected)) !== "removed") {
+            throw new Error(`Managed installed file could not be rolled back safely: ${plan.path}`);
+        }
+        context.authenticatedFiles.delete(key);
+    }
+    finally {
+        await directory.close();
+    }
+}
 export async function applyManagedFilePlan(plan, context = createManagedFileApplyContext(), hooks = {}) {
     if (plan.status === "unchanged") {
         await revalidateManagedFilePlan(plan);

package/dist/services/project.js

@@ -237,11 +237,36 @@ function createSessionWatcher(getSession, projectRoot, directories) {
         directories,
         onChange: (files) => {
             const session = getSession();
+            const cachePath = symbolIndexCachePath(session.symbolIndexPolicy, session.context.status.project);
+            let sourceFiles = files;
+            if (cachePath) {
+                const relativeCachePath = path
+                    .relative(session.context.projectRoot, cachePath)
+                    .split(path.sep)
+                    .join("/");
+                if (!relativeCachePath.startsWith("../") && !path.isAbsolute(relativeCachePath)) {
+                    const relativeCacheDirectory = path.posix.dirname(relativeCachePath);
+                    const quarantinePrefix = `${relativeCachePath}.corrupt-`;
+                    sourceFiles = files.filter((file) => {
+                        if (relativeCacheDirectory !== "." && file === relativeCacheDirectory)
+                            return false;
+                        if (file === relativeCachePath ||
+                            file === `${relativeCachePath}-wal` ||
+                            file === `${relativeCachePath}-shm`) {
+                            return false;
+                        }
+                        return !(file.startsWith(quarantinePrefix) &&
+                            /^\d+-\d+$/u.test(file.slice(quarantinePrefix.length)));
+                    });
+                }
+            }
+            if (sourceFiles.length === 0)
+                return;
             session.context = {
                 ...session.context,
                 status: transitionProjectStatus(session.context.status, {
                     type: "source_changed",
-                    files,
+                    files: sourceFiles,
                 }),
             };
         },
@@ -302,32 +327,22 @@ function assertProjectRuntimeAdmissionOpen() {
         throw new ProjectOperationSchedulerError("SERVER_SHUTTING_DOWN");
     }
 }
-function getOrCreateSession(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
-    assertProjectRuntimeAdmissionOpen();
+function createProjectSession(projectRoot, runtimePolicy, symbolIndexPolicy, requestContext, lastAccessSequence) {
     requestContext.checkpoint();
     const tsConfigFilePath = resolveTsConfigPath(projectRoot);
-    const existing = projectSessions.get(tsConfigFilePath);
-    if (existing)
-        return existing;
-    const runtimePolicy = getProjectRuntimePolicy();
-    ensureProjectSessionCapacity(runtimePolicy.maxProjectSessions);
-    const symbolIndexPolicy = readSymbolIndexPersistencePolicy();
-    requestContext.checkpoint();
     const baseContext = buildProjectContext(tsConfigFilePath);
     const context = {
         ...baseContext,
         symbolIndexObservability: createInitialSymbolIndexRuntimeObservability(symbolIndexPolicy),
     };
     const watchDirectories = selectProjectWatchDirectories(context.projectRoot, context.project.getSourceFiles().map((sourceFile) => sourceFile.getFilePath()));
-    const watcher = createSessionWatcher(() => session, context.projectRoot, watchDirectories);
+    const owner = {};
+    const watcher = createSessionWatcher(() => owner.session, context.projectRoot, watchDirectories);
     const session = {
         context,
         watcher,
         watchDirectories,
-        configDigest: (() => {
-            requestContext.checkpoint();
-            return createConfigSnapshot(tsConfigFilePath).digest;
-        })(),
+        configDigest: createConfigSnapshot(tsConfigFilePath).digest,
         fingerprints: new Map(),
         compilerStateUntrusted: false,
         scheduler: new ProjectOperationScheduler({
@@ -335,12 +350,12 @@ function getOrCreateSession(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
             queueWaitTimeoutMs: runtimePolicy.queueWaitTimeoutMs,
             operationDeadlineMs: runtimePolicy.operationDeadlineMs,
         }),
-        lastAccessSequence: nextProjectSessionAccessSequence(),
+        lastAccessSequence,
         symbolIndexPolicy,
     };
-    projectSessions.set(tsConfigFilePath, session);
-    session.watcher.start();
-    if (session.watcher.snapshot().state === "ready") {
+    owner.session = session;
+    watcher.start();
+    if (watcher.snapshot().state === "ready") {
         session.context = {
             ...session.context,
             status: transitionProjectStatus(session.context.status, { type: "watcher_recovered" }),
@@ -348,6 +363,20 @@ function getOrCreateSession(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
     }
     return session;
 }
+function getOrCreateSession(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
+    assertProjectRuntimeAdmissionOpen();
+    requestContext.checkpoint();
+    const tsConfigFilePath = resolveTsConfigPath(projectRoot);
+    const existing = projectSessions.get(tsConfigFilePath);
+    if (existing)
+        return existing;
+    const runtimePolicy = getProjectRuntimePolicy();
+    ensureProjectSessionCapacity(runtimePolicy.maxProjectSessions);
+    const symbolIndexPolicy = readSymbolIndexPersistencePolicy();
+    const session = createProjectSession(projectRoot, runtimePolicy, symbolIndexPolicy, requestContext, nextProjectSessionAccessSequence());
+    projectSessions.set(tsConfigFilePath, session);
+    return session;
+}
 function getQueueStatus(session) {
     const snapshot = session.scheduler.snapshot();
     return projectOperationQueueToProjection(snapshot, snapshot.queue_capacity);
@@ -651,9 +680,7 @@ export async function withProjectOperation(projectRoot, operation, requestContex
         return operation(operationContext);
     }, { signal: requestContext.signal });
 }
-export async function getProjectStatus(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
-    requestContext.checkpoint();
-    const session = getOrCreateSession(projectRoot, requestContext);
+function readProjectStatus(session, requestContext) {
     return runSessionWithSyncPolicy(session, async (context, operationContext) => {
         let effectiveContext = context;
         let indexedCount = 0;
@@ -681,6 +708,55 @@ export async function getProjectStatus(projectRoot, requestContext = NO_REQUEST_
         };
     }, true, requestContext);
 }
+function peekSessionStatus(session) {
+    const context = session.context;
+    return {
+        ...projectStatusToProjection(context.status),
+        index: { state: context.symbolIndexObservability.state },
+        indexed_count: 0,
+        last_successful_index_at: context.symbolIndexObservability.last_successful_persistence_at,
+        index_observability: { ...context.symbolIndexObservability },
+        operation_queue: getQueueStatus(session),
+    };
+}
+export function peekRegisteredProjectStatus(projectRoot) {
+    const session = projectSessions.get(resolveTsConfigPath(projectRoot));
+    return session ? peekSessionStatus(session) : undefined;
+}
+export async function getProjectStatus(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    return readProjectStatus(getOrCreateSession(projectRoot, requestContext), requestContext);
+}
+export async function getDiagnosticProjectStatus(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    const runtimePolicy = getProjectRuntimePolicy();
+    const registered = peekRegisteredProjectStatus(projectRoot);
+    if (registered)
+        return {
+            authority: "registered",
+            runtime_admission: projectRuntimeAdmission,
+            session_capacity: runtimePolicy.maxProjectSessions,
+            status: registered,
+        };
+    if (projectRuntimeAdmission === "closed")
+        return {
+            authority: "unavailable",
+            runtime_admission: "closed",
+            session_capacity: runtimePolicy.maxProjectSessions,
+        };
+    const session = createProjectSession(projectRoot, runtimePolicy, readSymbolIndexPersistencePolicy({ AST_SYMBOL_INDEX_PERSISTENCE: "disabled" }), requestContext, 0n);
+    try {
+        return {
+            authority: "isolated",
+            runtime_admission: projectRuntimeAdmission,
+            session_capacity: runtimePolicy.maxProjectSessions,
+            status: await readProjectStatus(session, requestContext),
+        };
+    }
+    finally {
+        closeProjectSession(session);
+    }
+}
 // Compatibility API for internal scripts. MCP tools should use withProject().
 export function getProject(projectRoot) {
     return createFreshProject(projectRoot).project;

package/dist/services/skill-installer.js

@@ -2,7 +2,8 @@ import { readFile, realpath, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { z } from "zod";
-import { applyManagedFilePlan, canonicalizeFuturePath, captureManagedFileSnapshot, createManagedFileApplyContext, hashBytes, verifyManagedFilePostimage, } from "./managed-file.js";
+import { canonicalizeFuturePath, createManagedFileApplyContext, } from "./managed-file.js";
+import { applyManagedBundle, ManagedBundleConflictError, planManagedBundle, } from "./managed-bundle.js";
 const SKILL_NAME = "structural-code-editing";
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 const ReleaseRecordSchema = z
@@ -12,17 +13,24 @@ const ReleaseRecordSchema = z
     npm_versions: z.array(z.string().min(1)).min(1),
 })
     .strict();
-const SkillReleaseManifestSchema = z
+const SkillFileSchema = z
+    .object({ path: z.string().min(1), sha256: z.string().regex(SHA256_PATTERN) })
+    .strict();
+const BundleReleaseSchema = z
+    .object({
+    version: z.string().min(1),
+    files: z.array(SkillFileSchema).min(1),
+})
+    .strict();
+const BundleSkillReleaseManifestSchema = z
     .object({
-    schema_version: z.literal(1),
+    schema_version: z.literal(2),
     algorithm: z.literal("sha256"),
-    current: z
-        .object({
-        version: z.string().min(1),
-        sha256: z.string().regex(SHA256_PATTERN),
-    })
-        .strict(),
-    predecessors: z.array(ReleaseRecordSchema),
+    current: BundleReleaseSchema,
+    predecessors: z.array(z.union([
+        ReleaseRecordSchema,
+        BundleReleaseSchema.extend({ npm_versions: z.array(z.string().min(1)).min(1) }),
+    ])),
 })
     .strict();
 export class SkillConflictError extends Error {
@@ -101,77 +109,87 @@ async function readReleaseManifest(manifestPath) {
     catch (error) {
         throw new Error(`Skill release manifest is unreadable or invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
-    const result = SkillReleaseManifestSchema.safeParse(parsed);
+    const result = BundleSkillReleaseManifestSchema.safeParse(parsed);
     if (!result.success) {
         throw new Error(`Skill release manifest is invalid: ${result.error.issues[0]?.message ?? "unknown error"}`);
     }
-    const digests = [
-        result.data.current.sha256,
-        ...result.data.predecessors.map((item) => item.sha256),
-    ];
-    if (new Set(digests).size !== digests.length) {
-        throw new Error("Skill release manifest contains a duplicate digest.");
+    const manifest = {
+        current: result.data.current,
+        predecessors: result.data.predecessors.map((item) => "files" in item
+            ? item
+            : {
+                version: item.version,
+                npm_versions: item.npm_versions,
+                files: [{ path: "SKILL.md", sha256: item.sha256 }],
+            }),
+    };
+    if (!manifest.current.files.some((file) => file.path === "SKILL.md")) {
+        throw new Error("Skill release manifest current bundle must include SKILL.md.");
     }
     const predecessorVersions = result.data.predecessors.flatMap((item) => item.npm_versions);
     if (new Set(predecessorVersions).size !== predecessorVersions.length) {
         throw new Error("Skill release manifest contains a duplicate npm version provenance entry.");
     }
-    return result.data;
+    return manifest;
 }
 export async function planBundledSkillInstallation(options) {
     const sourcePath = path.resolve(options.sourceSkillPath);
-    const source = await readFile(sourcePath);
-    const sourceDigest = hashBytes(source);
-    const manifestPath = path.resolve(options.releaseManifestPath ?? path.join(path.dirname(sourcePath), "releases.json"));
+    const sourceRoot = path.dirname(sourcePath);
+    const canonicalSourceRoot = await realpath(sourceRoot);
+    const manifestPath = path.resolve(options.releaseManifestPath ?? path.join(sourceRoot, "releases.json"));
     const manifest = await readReleaseManifest(manifestPath);
-    if (sourceDigest !== manifest.current.sha256) {
-        throw new Error(`Skill release manifest current digest does not match source skill bytes: ${sourcePath}`);
+    const sources = [];
+    for (const file of manifest.current.files) {
+        const assetPath = path.resolve(sourceRoot, file.path);
+        const assetRealPath = await realpath(assetPath).catch(() => undefined);
+        if (assetRealPath === undefined ||
+            (assetRealPath !== canonicalSourceRoot &&
+                !assetRealPath.startsWith(`${canonicalSourceRoot}${path.sep}`)) ||
+            !(await stat(assetPath)).isFile()) {
+            throw new Error(`Skill release manifest asset is missing or escapes the bundle: ${file.path}`);
+        }
+        sources.push({ ...file, content: await readFile(assetPath) });
     }
-    const admittedPredecessors = new Set(manifest.predecessors.map((item) => item.sha256));
     const logical = await destinations(options);
     const filesByPath = new Map();
+    const statusesByRoot = new Map();
     for (const item of logical) {
-        if (filesByPath.has(item.path))
+        const destinationRoot = path.dirname(item.path);
+        if (statusesByRoot.has(destinationRoot))
             continue;
-        const snapshot = await captureManagedFileSnapshot(item.path);
-        let status;
-        if (!snapshot.exists)
-            status = "installed";
-        else if (snapshot.sha256 === sourceDigest)
-            status = "unchanged";
-        else if (admittedPredecessors.has(snapshot.sha256) || options.force === true)
-            status = "updated";
-        else
-            throw new SkillConflictError(item.path);
-        filesByPath.set(item.path, {
-            path: item.path,
-            snapshot,
-            postimage: source,
-            postimageSha256: sourceDigest,
-            status,
-        });
+        let plan;
+        try {
+            plan = await planManagedBundle({
+                destinationRoot,
+                current: { files: sources },
+                predecessors: manifest.predecessors,
+                force: options.force,
+            });
+        }
+        catch (error) {
+            if (error instanceof ManagedBundleConflictError)
+                throw new SkillConflictError(error.destination);
+            if (error instanceof Error && error.message.startsWith("Managed bundle")) {
+                throw new Error(error.message.replace("Managed bundle", "Skill release manifest"), {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+        statusesByRoot.set(destinationRoot, plan.status);
+        for (const file of plan.files)
+            filesByPath.set(file.path, file);
     }
     return {
         installations: logical.map((item) => ({
             ...item,
-            status: filesByPath.get(item.path).status,
+            status: statusesByRoot.get(path.dirname(item.path)),
         })),
         files: [...filesByPath.values()],
     };
 }
-export async function applySkillInstallationPlan(plan, onApplied, context = createManagedFileApplyContext()) {
-    const authenticated = [];
-    for (const file of plan.files) {
-        for (const current of authenticated) {
-            await verifyManagedFilePostimage(current, context);
-        }
-        await applyManagedFilePlan(file, context);
-        authenticated.push(file);
-        await onApplied?.(file);
-    }
-    for (const current of authenticated) {
-        await verifyManagedFilePostimage(current, context);
-    }
+export async function applySkillInstallationPlan(plan, onApplied, context = createManagedFileApplyContext(), hooks = {}) {
+    await applyManagedBundle(plan, onApplied, context, hooks);
 }
 export async function installBundledSkill(options) {
     const plan = await planBundledSkillInstallation(options);

package/dist/services/upgrade-command.js

@@ -0,0 +1,77 @@
+import { inspectUpgrade, performUpgrade, UpgradeError } from "./upgrade.js";
+import { ReconciliationError } from "./upgrade-reconcile.js";
+import { UpgradeCleanupError } from "./upgrade-runtime.js";
+export class UpgradeCommandError extends Error {
+    code;
+    constructor(code = "UPGRADE_USAGE") {
+        super("Usage: ast-tool upgrade [--check]");
+        this.code = code;
+        this.name = "UpgradeCommandError";
+    }
+}
+export async function runUpgradeCommand(args, runtime, reconcile) {
+    if (args.length > 1 || (args.length === 1 && args[0] !== "--check")) {
+        throw new UpgradeCommandError();
+    }
+    if (args[0] === "--check")
+        return inspectUpgrade(runtime);
+    const updated = await performUpgrade(runtime);
+    const { new_cli: newCli, ...result } = updated;
+    if (updated.status === "current")
+        return { ...result, reconciliation: "not_required" };
+    try {
+        await reconcile(newCli);
+        return { ...result, reconciliation: "completed" };
+    }
+    catch (error) {
+        const skillConflict = error instanceof ReconciliationError && error.code === "AGENT_SKILL_CONFLICT";
+        return {
+            ...result,
+            status: "partial",
+            package_status: "updated",
+            reconciliation: "required",
+            continuation: skillConflict
+                ? "ast-tool setup --agents all --yes --force-skill"
+                : "ast-tool setup --agents all --yes",
+            restart_required: true,
+        };
+    }
+}
+function primaryCode(error) {
+    return error instanceof UpgradeError || error instanceof UpgradeCommandError
+        ? error.code
+        : "UPGRADE_ERROR";
+}
+export async function runUpgradeLease(args, lease, reconcile) {
+    let result;
+    let primary;
+    try {
+        result = await runUpgradeCommand(args, lease.runtime, reconcile);
+    }
+    catch (error) {
+        primary = error;
+    }
+    try {
+        await lease.dispose();
+    }
+    catch {
+        if (primary)
+            throw new UpgradeCleanupError(primaryCode(primary));
+        const record = result;
+        if (record.status === "updated" || record.package_status === "updated") {
+            return {
+                ...record,
+                status: "partial",
+                package_status: "updated",
+                cleanup: "required",
+                cleanup_code: "UPGRADE_CLEANUP_FAILED",
+                continuation: record.continuation ?? "ast-tool upgrade --check",
+                restart_required: true,
+            };
+        }
+        throw new UpgradeCleanupError();
+    }
+    if (primary)
+        throw primary;
+    return result;
+}

package/dist/services/upgrade-reconcile.js

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import process from "node:process";
+import { promisify } from "node:util";
+const executeFile = promisify(execFile);
+export class ReconciliationError extends Error {
+    code;
+    constructor(code) {
+        super("The updated package requires managed setup reconciliation.");
+        this.code = code;
+        this.name = "ReconciliationError";
+    }
+}
+export async function reconcileUpgrade(executable, options = {}) {
+    const execute = options.execute ?? executeFile;
+    try {
+        await execute(options.nodeExecutable ?? process.execPath, [executable, "setup", "--agents", "all", "--yes"], {
+            encoding: "utf8",
+            windowsHide: true,
+            env: options.environment ?? process.env,
+        });
+    }
+    catch (error) {
+        const stderr = typeof error === "object" && error !== null && "stderr" in error
+            ? String(error.stderr ?? "")
+            : "";
+        try {
+            const failure = JSON.parse(stderr);
+            if (typeof failure === "object" &&
+                failure !== null &&
+                "code" in failure &&
+                failure.code === "AGENT_SKILL_CONFLICT") {
+                throw new ReconciliationError("AGENT_SKILL_CONFLICT");
+            }
+        }
+        catch (parsed) {
+            if (parsed instanceof ReconciliationError)
+                throw parsed;
+        }
+        throw new ReconciliationError("UPGRADE_RECONCILIATION_FAILED");
+    }
+}