@alan-ai-hq/agent-manager 0.1.113 → 0.1.115

package/dist/skills/__tests__/runtime-skill-manager.test.js

@@ -0,0 +1,664 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, mkdtemp, readdir, readFile, readlink, realpath, rm, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { inspectSkillPackage } from "@alan-ai/shared/node/skill-package";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { RuntimeSkillManager } from "../runtime-skill-manager.js";
+import { createSkillBundle } from "../skill-bundle.js";
+const temporaryDirectories = [];
+async function createTemporaryDirectory() {
+    const directory = await mkdtemp(join(tmpdir(), "alan-runtime-skills-"));
+    temporaryDirectories.push(directory);
+    return directory;
+}
+afterEach(async () => {
+    await Promise.all(temporaryDirectories
+        .splice(0)
+        .map((directory) => rm(directory, { recursive: true, force: true })));
+});
+describe("RuntimeSkillManager", () => {
+    it("adopts only an exact manifest-owned legacy Skill and retires the old inventory", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const legacyAgents = join(homeDirectory, ".agents", "skills", "review-pr");
+        const legacyClaude = join(homeDirectory, ".claude", "skills", "review-pr");
+        const content = "---\nname: review-pr\ndescription: Review this pull request.\n---\nReview carefully.\n";
+        await mkdir(join(homeDirectory, ".alan"), { recursive: true });
+        await mkdir(legacyAgents, { recursive: true });
+        await mkdir(legacyClaude, { recursive: true });
+        await writeFile(join(legacyAgents, "SKILL.md"), content);
+        await writeFile(join(legacyClaude, "SKILL.md"), content);
+        const legacyHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+        await writeFile(join(homeDirectory, ".alan", "sync-manifest.json"), JSON.stringify({ skills: { "review-pr": { hash: legacyHash } } }));
+        const bundle = await createSkillBundle(legacyAgents);
+        const downloadBundle = vi.fn(async () => bundle.bytes);
+        const manager = await RuntimeSkillManager.open({ homeDirectory, downloadBundle });
+        const manifest = desiredManifest(bundle, "review-pr", "review-pr--skill1", "9");
+        const result = await manager.reconcile({ manifest });
+        expect(result.skills[0]?.state).toBe("applied");
+        expect(downloadBundle).not.toHaveBeenCalled();
+        expect(JSON.parse(await readFile(join(homeDirectory, ".agents", "skills", "review-pr--skill1", ".alan-managed.json"), "utf8"))).toMatchObject({ skillId: manifest.skills[0]?.skillId });
+        await expect(lstat(legacyAgents)).rejects.toMatchObject({ code: "ENOENT" });
+        expect((await lstat(join(homeDirectory, ".claude", "skills", "review-pr--skill1"))).isSymbolicLink()).toBe(true);
+        await expect(lstat(join(homeDirectory, ".alan", "sync-manifest.json"))).rejects.toMatchObject({
+            code: "ENOENT",
+        });
+    });
+    it("preserves an edited legacy Skill and treats it as user-owned", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const legacy = join(homeDirectory, ".agents", "skills", "review-pr");
+        await mkdir(join(homeDirectory, ".alan"), { recursive: true });
+        await mkdir(legacy, { recursive: true });
+        const original = "---\nname: review-pr\ndescription: Review this pull request.\n---\nOriginal.\n";
+        await writeFile(join(legacy, "SKILL.md"), `${original}User edit.\n`);
+        await writeFile(join(homeDirectory, ".alan", "sync-manifest.json"), JSON.stringify({
+            skills: {
+                "review-pr": {
+                    hash: createHash("sha256").update(original).digest("hex").slice(0, 16),
+                },
+            },
+        }));
+        const bundle = await createTestBundle("review-pr", "Review this pull request.");
+        const manager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle: async () => bundle.bytes,
+        });
+        await manager.reconcile({
+            manifest: desiredManifest(bundle, "review-pr", "review-pr--skill1", "8"),
+        });
+        expect(await readFile(join(legacy, "SKILL.md"), "utf8")).toContain("User edit");
+    });
+    it("publishes the exact complete package from the last complete discovery snapshot", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const sourceRoot = join(homeDirectory, "editable-skills");
+        const source = join(sourceRoot, "release-notes");
+        await mkdir(join(source, "references"), { recursive: true });
+        await writeFile(join(source, "SKILL.md"), "---\nname: release-notes\ndescription: Prepare release notes.\n---\nRead references/format.md.\n");
+        await writeFile(join(source, "references", "format.md"), "# Required format\n");
+        const expectedBundle = await createSkillBundle(source);
+        const uploadedChunks = [];
+        const controlClient = {
+            sync: vi.fn(),
+            uploadPreparedBundle: vi.fn(async (_grant, bytes) => {
+                uploadedChunks.push(Buffer.from(bytes));
+            }),
+        };
+        const downloadBundle = vi.fn(async () => expectedBundle.bytes);
+        const manager = await RuntimeSkillManager.open({
+            homeDirectory,
+            controlClient,
+            downloadBundle,
+        });
+        const scan = await manager.scan({
+            mode: "audit",
+            reason: "before_publish",
+            roots: [
+                {
+                    kind: "configured",
+                    declarationId: "source-1",
+                    path: sourceRoot,
+                    label: "Editable Skills",
+                    precedence: 0,
+                },
+            ],
+        });
+        expect(scan.status).toBe("complete");
+        if (scan.status !== "complete")
+            throw new Error("expected complete scan");
+        const candidate = scan.candidates[0];
+        const localPreview = await manager.inspectLocalPackage({
+            localKey: candidate.localKey,
+            expectedContentHash: candidate.contentHash,
+        });
+        expect(localPreview.package.files.map((file) => file.path)).toEqual([
+            "SKILL.md",
+            "references/format.md",
+        ]);
+        await expect(manager.readLocalPackageFile({
+            localKey: candidate.localKey,
+            expectedContentHash: candidate.contentHash,
+            expectedFileHash: localPreview.package.files[1].sha256,
+            path: "references/format.md",
+        })).resolves.toMatchObject({ encoding: "utf8", content: "# Required format\n" });
+        expect(controlClient.uploadPreparedBundle).not.toHaveBeenCalled();
+        const published = await manager.publish({
+            commandId: "44444444-4444-4444-8444-444444444444",
+            previewId: "55555555-5555-4555-8555-555555555555",
+            localKey: candidate.localKey,
+            expectedContentHash: candidate.contentHash,
+            uploadGrant: {
+                method: "PUT",
+                url: "https://runtime.invalid/signed-upload",
+                headers: { "content-type": "application/gzip" },
+                expiresAt: "2099-01-01T00:00:00.000Z",
+                maxBytes: 10 * 1024 * 1024,
+            },
+        });
+        expect(published).toMatchObject({
+            state: "uploaded",
+            contentHash: expectedBundle.contentHash,
+            archiveHash: expectedBundle.archiveHash,
+            compressedBytes: expectedBundle.bytes.byteLength,
+        });
+        expect(Buffer.concat(uploadedChunks)).toEqual(expectedBundle.bytes);
+        const manifest = desiredManifest(expectedBundle, "release-notes", "release-notes--skill1", "7");
+        const reconciled = await manager.reconcile({ manifest });
+        expect(reconciled.skills[0]?.state).toBe("applied");
+        expect(downloadBundle).toHaveBeenCalledOnce();
+        expect(await readFile(join(homeDirectory, ".agents", "skills", "release-notes--skill1", "SKILL.md"), "utf8")).toContain("Read references/format.md");
+    });
+    it("downloads, verifies, caches, and atomically projects an exact complete Skill Version", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const sourceParent = await createTemporaryDirectory();
+        const source = join(sourceParent, "release-notes");
+        await mkdir(join(source, "scripts"), { recursive: true });
+        await writeFile(join(source, "SKILL.md"), "---\nname: release-notes\ndescription: Prepare release notes.\n---\nRun scripts/collect.sh.\n");
+        await writeFile(join(source, "scripts", "collect.sh"), "#!/bin/sh\necho collect\n", {
+            mode: 0o755,
+        });
+        const bundle = await createSkillBundle(source);
+        const downloadBundle = vi.fn(async () => bundle.bytes);
+        const manager = await RuntimeSkillManager.open({ homeDirectory, downloadBundle });
+        const manifest = {
+            protocolVersion: 1,
+            revision: `sha256:${"a".repeat(64)}`,
+            skills: [
+                {
+                    skillId: "11111111-1111-4111-8111-111111111111",
+                    versionId: "22222222-2222-4222-8222-222222222222",
+                    slug: "release-notes",
+                    runtimeDirectory: "release-notes--skill1",
+                    contentHash: bundle.contentHash,
+                    archiveHash: bundle.archiveHash,
+                    compressedBytes: bundle.bytes.byteLength,
+                    downloadUrl: "https://runtime.invalid/signed-bundle",
+                    downloadUrlExpiresAt: "2099-01-01T00:00:00.000Z",
+                },
+            ],
+        };
+        const first = await manager.reconcile({ manifest });
+        const projected = join(homeDirectory, ".agents", "skills", "release-notes--skill1");
+        expect(first.skills).toEqual([
+            expect.objectContaining({
+                skillId: "11111111-1111-4111-8111-111111111111",
+                versionId: "22222222-2222-4222-8222-222222222222",
+                contentHash: bundle.contentHash,
+                observedHash: bundle.contentHash,
+                state: "applied",
+            }),
+        ]);
+        expect(await readFile(join(projected, "scripts", "collect.sh"), "utf8")).toContain("echo collect");
+        expect(JSON.parse(await readFile(join(projected, ".alan-managed.json"), "utf8"))).toEqual({
+            protocolVersion: 1,
+            skillId: "11111111-1111-4111-8111-111111111111",
+            versionId: "22222222-2222-4222-8222-222222222222",
+            contentHash: bundle.contentHash,
+        });
+        expect((await inspectSkillPackage(projected, { expectedName: null })).contentHash).toBe(bundle.contentHash);
+        const compatibility = join(homeDirectory, ".claude", "skills", "release-notes--skill1");
+        expect((await lstat(compatibility)).isSymbolicLink()).toBe(true);
+        expect(await readlink(compatibility)).toBe(projected);
+        const second = await manager.reconcile({ manifest });
+        expect(second.skills[0]?.state).toBe("applied");
+        expect(downloadBundle).toHaveBeenCalledTimes(1);
+        expect((await manager.inspect()).appliedRevision).toBe(manifest.revision);
+    });
+    it("resolves an invocation by immutable identity and rejects a same-name different Version", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const bundle = await createTestBundle("review-pr", "Review this pull request.");
+        const manifest = desiredManifest(bundle, "review-pr", "review-pr--skill1", "a");
+        const manager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle: async () => bundle.bytes,
+        });
+        await manager.reconcile({ manifest });
+        const installed = manifest.skills[0];
+        await expect(manager.resolveInvocation("runtime-1", {
+            kind: "skill_version",
+            skillId: installed.skillId,
+            versionId: installed.versionId,
+            displayName: "Review PR",
+        })).resolves.toMatchObject({
+            packageDirectory: join(homeDirectory, ".agents", "skills", "review-pr--skill1"),
+        });
+        await expect(manager.resolveInvocation("runtime-1", {
+            kind: "skill_version",
+            skillId: installed.skillId,
+            versionId: "33333333-3333-4333-8333-333333333333",
+            displayName: "Review PR",
+        })).rejects.toThrow("not installed");
+    });
+    it("keeps production and staging projections isolated for the same runtime directory", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const productionBundle = await createTestBundle("review-pr", "Production instructions.");
+        const stagingBundle = await createTestBundle("review-pr", "Staging instructions.");
+        const productionManifest = desiredManifest(productionBundle, "review-pr", "review-pr--skill1", "1");
+        const stagingManifest = {
+            ...desiredManifest(stagingBundle, "review-pr", "review-pr--skill1", "2"),
+            skills: [
+                {
+                    ...desiredManifest(stagingBundle, "review-pr", "review-pr--skill1", "2").skills[0],
+                    versionId: "33333333-3333-4333-8333-333333333333",
+                },
+            ],
+        };
+        const downloadBundle = vi.fn(async (entry) => entry.versionId === productionManifest.skills[0].versionId
+            ? productionBundle.bytes
+            : stagingBundle.bytes);
+        const productionManager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle,
+            endpointProfile: "production",
+        });
+        await productionManager.reconcile({ manifest: productionManifest });
+        const stagingManager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle,
+            endpointProfile: "staging",
+        });
+        await stagingManager.reconcile({ manifest: stagingManifest });
+        expect(JSON.parse(await readFile(join(homeDirectory, ".alan", "skills", "profiles", "production", "state.json"), "utf8"))).toMatchObject({ appliedRevision: productionManifest.revision });
+        expect(JSON.parse(await readFile(join(homeDirectory, ".alan", "skills", "profiles", "staging", "state.json"), "utf8"))).toMatchObject({ appliedRevision: stagingManifest.revision });
+        await expect(productionManager.resolveInvocation("runtime-production", {
+            kind: "skill_version",
+            skillId: productionManifest.skills[0].skillId,
+            versionId: productionManifest.skills[0].versionId,
+            displayName: "Review PR",
+        })).resolves.toMatchObject({
+            packageDirectory: join(homeDirectory, ".agents", "skills", "review-pr--skill1--alan-production"),
+        });
+        await expect(stagingManager.resolveInvocation("runtime-staging", {
+            kind: "skill_version",
+            skillId: stagingManifest.skills[0].skillId,
+            versionId: stagingManifest.skills[0].versionId,
+            displayName: "Review PR",
+        })).resolves.toMatchObject({
+            packageDirectory: join(homeDirectory, ".agents", "skills", "review-pr--skill1--alan-staging"),
+        });
+    });
+    it("isolates custom runtimes by their stable config identity", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const firstBundle = await createTestBundle("review-pr", "First custom runtime.");
+        const secondBundle = await createTestBundle("review-pr", "Second custom runtime.");
+        const firstManifest = desiredManifest(firstBundle, "review-pr", "review-pr--skill1", "3");
+        const secondManifest = {
+            ...desiredManifest(secondBundle, "review-pr", "review-pr--skill1", "4"),
+            skills: [
+                {
+                    ...desiredManifest(secondBundle, "review-pr", "review-pr--skill1", "4").skills[0],
+                    versionId: "33333333-3333-4333-8333-333333333333",
+                },
+            ],
+        };
+        const firstIdentity = join(homeDirectory, "configs", "first.json");
+        const secondIdentity = join(homeDirectory, "configs", "second.json");
+        const firstManager = await RuntimeSkillManager.open({
+            homeDirectory,
+            endpointProfile: "custom",
+            profileStorageIdentity: firstIdentity,
+            downloadBundle: async () => firstBundle.bytes,
+        });
+        const secondManager = await RuntimeSkillManager.open({
+            homeDirectory,
+            endpointProfile: "custom",
+            profileStorageIdentity: secondIdentity,
+            downloadBundle: async () => secondBundle.bytes,
+        });
+        await firstManager.reconcile({ manifest: firstManifest });
+        await secondManager.reconcile({ manifest: secondManifest });
+        const firstNamespace = `custom-${createHash("sha256").update(firstIdentity).digest("hex").slice(0, 12)}`;
+        const secondNamespace = `custom-${createHash("sha256").update(secondIdentity).digest("hex").slice(0, 12)}`;
+        await expect(firstManager.resolveInvocation("runtime-first", {
+            kind: "skill_version",
+            skillId: firstManifest.skills[0].skillId,
+            versionId: firstManifest.skills[0].versionId,
+            displayName: "Review PR",
+        })).resolves.toMatchObject({
+            packageDirectory: join(homeDirectory, ".agents", "skills", `review-pr--skill1--alan-${firstNamespace}`),
+        });
+        await expect(secondManager.resolveInvocation("runtime-second", {
+            kind: "skill_version",
+            skillId: secondManifest.skills[0].skillId,
+            versionId: secondManifest.skills[0].versionId,
+            displayName: "Review PR",
+        })).resolves.toMatchObject({
+            packageDirectory: join(homeDirectory, ".agents", "skills", `review-pr--skill1--alan-${secondNamespace}`),
+        });
+    });
+    it("preserves an exact unscoped projection while rebuilding scoped state", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const sourceRoot = join(homeDirectory, "editable-skills");
+        const source = join(sourceRoot, "local-review");
+        await mkdir(source, { recursive: true });
+        await writeFile(join(source, "SKILL.md"), "---\nname: local-review\ndescription: Local review instructions.\n---\nReview locally.\n");
+        const bundle = await createTestBundle("review-pr", "Managed instructions.");
+        const manifest = desiredManifest(bundle, "review-pr", "review-pr--skill1", "5");
+        const scanInput = {
+            mode: "audit",
+            reason: "startup",
+            roots: [
+                {
+                    kind: "configured",
+                    declarationId: "source-1",
+                    path: sourceRoot,
+                    label: "Editable Skills",
+                    precedence: 0,
+                },
+            ],
+        };
+        const unscopedManager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle: async () => bundle.bytes,
+        });
+        const unscopedScan = await unscopedManager.scan(scanInput);
+        if (unscopedScan.status !== "complete")
+            throw new Error("expected complete unscoped scan");
+        await unscopedManager.reconcile({ manifest });
+        const localCandidate = unscopedScan.candidates[0];
+        const localRuntimeId = "44444444-4444-4444-8444-444444444444";
+        const scopedManager = await RuntimeSkillManager.open({
+            homeDirectory,
+            endpointProfile: "production",
+            downloadBundle: async () => bundle.bytes,
+        });
+        await expect(scopedManager.resolveInvocation(localRuntimeId, {
+            kind: "local_skill",
+            runtimeId: localRuntimeId,
+            localKey: localCandidate.localKey,
+            contentHash: localCandidate.contentHash,
+            displayName: localCandidate.name,
+        })).rejects.toThrow("last complete scan");
+        await scopedManager.reconcile({ manifest });
+        const scopedScan = await scopedManager.scan(scanInput);
+        if (scopedScan.status !== "complete")
+            throw new Error("expected complete scoped scan");
+        expect(await readFile(join(homeDirectory, ".agents", "skills", "review-pr--skill1", "SKILL.md"), "utf8")).toContain("Managed instructions.");
+        expect((await lstat(join(homeDirectory, ".claude", "skills", "review-pr--skill1"))).isSymbolicLink()).toBe(true);
+        await expect(scopedManager.resolveInvocation(localRuntimeId, {
+            kind: "local_skill",
+            runtimeId: localRuntimeId,
+            localKey: localCandidate.localKey,
+            contentHash: localCandidate.contentHash,
+            displayName: localCandidate.name,
+        })).resolves.toMatchObject({ packageDirectory: await realpath(source) });
+        await expect(scopedManager.resolveInvocation("runtime-production", {
+            kind: "skill_version",
+            skillId: manifest.skills[0].skillId,
+            versionId: manifest.skills[0].versionId,
+            displayName: "Review PR",
+        })).resolves.toMatchObject({
+            packageDirectory: join(homeDirectory, ".agents", "skills", "review-pr--skill1--alan-production"),
+        });
+    });
+    it("preserves a mismatched unscoped projection during scoped reconciliation", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const unscopedBundle = await createTestBundle("review-pr", "Unscoped instructions.");
+        const scopedBundle = await createTestBundle("review-pr", "Scoped staging instructions.");
+        const unscopedManifest = desiredManifest(unscopedBundle, "review-pr", "review-pr--skill1", "6");
+        const scopedManifest = {
+            ...desiredManifest(scopedBundle, "review-pr", "review-pr--skill1", "7"),
+            skills: [
+                {
+                    ...desiredManifest(scopedBundle, "review-pr", "review-pr--skill1", "7").skills[0],
+                    versionId: "33333333-3333-4333-8333-333333333333",
+                },
+            ],
+        };
+        const unscopedManager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle: async () => unscopedBundle.bytes,
+        });
+        await unscopedManager.reconcile({ manifest: unscopedManifest });
+        const scopedManager = await RuntimeSkillManager.open({
+            homeDirectory,
+            endpointProfile: "staging",
+            downloadBundle: async () => scopedBundle.bytes,
+        });
+        await scopedManager.reconcile({ manifest: scopedManifest });
+        expect(await readFile(join(homeDirectory, ".agents", "skills", "review-pr--skill1", "SKILL.md"), "utf8")).toContain("Unscoped instructions.");
+        await expect(scopedManager.resolveInvocation("runtime-staging", {
+            kind: "skill_version",
+            skillId: scopedManifest.skills[0].skillId,
+            versionId: scopedManifest.skills[0].versionId,
+            displayName: "Review PR",
+        })).resolves.toMatchObject({
+            packageDirectory: join(homeDirectory, ".agents", "skills", "review-pr--skill1--alan-staging"),
+        });
+    });
+    it("restores a directly edited managed projection from the cloud bundle", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const bundle = await createTestBundle("review-pr", "Review this pull request.");
+        const downloadBundle = vi.fn(async () => bundle.bytes);
+        const manifest = desiredManifest(bundle, "review-pr", "review-pr--skill1", "b");
+        const manager = await RuntimeSkillManager.open({ homeDirectory, downloadBundle });
+        await manager.reconcile({ manifest });
+        const projected = join(homeDirectory, ".agents", "skills", "review-pr--skill1", "SKILL.md");
+        await writeFile(projected, "---\nname: review-pr\ndescription: Changed directly.\n---\nLocal edit.\n");
+        const result = await manager.reconcile({ manifest });
+        expect(result.skills[0]?.state).toBe("applied");
+        expect(await readFile(projected, "utf8")).toContain("Review this pull request.");
+        expect(await readFile(projected, "utf8")).not.toContain("Local edit.");
+        expect(downloadBundle).toHaveBeenCalledTimes(1);
+    });
+    it("resolves local invocations only for the scanned runtime and exact observed hash", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const sourceRoot = join(homeDirectory, "editable-skills");
+        const source = join(sourceRoot, "review-pr");
+        await mkdir(source, { recursive: true });
+        await writeFile(join(source, "SKILL.md"), "---\nname: review-pr\ndescription: Review a pull request.\n---\nReview carefully.\n");
+        const manager = await RuntimeSkillManager.open({ homeDirectory });
+        const scan = await manager.scan({
+            mode: "audit",
+            reason: "startup",
+            roots: [
+                {
+                    kind: "configured",
+                    declarationId: "source-1",
+                    path: sourceRoot,
+                    label: "Editable Skills",
+                    precedence: 0,
+                },
+            ],
+        });
+        if (scan.status !== "complete")
+            throw new Error("expected complete scan");
+        const candidate = scan.candidates[0];
+        const runtimeId = "11111111-1111-4111-8111-111111111111";
+        await expect(manager.resolveInvocation(runtimeId, {
+            kind: "local_skill",
+            runtimeId,
+            localKey: candidate.localKey,
+            contentHash: candidate.contentHash,
+            displayName: candidate.name,
+        })).resolves.toMatchObject({ packageDirectory: await realpath(source) });
+        await writeFile(join(source, "SKILL.md"), "changed after selection\n");
+        await expect(manager.resolveInvocation(runtimeId, {
+            kind: "local_skill",
+            runtimeId,
+            localKey: candidate.localKey,
+            contentHash: candidate.contentHash,
+            displayName: candidate.name,
+        })).rejects.toThrow();
+    });
+    it("never overwrites an unmanaged destination", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const bundle = await createTestBundle("review-pr", "Review this pull request.");
+        const destination = join(homeDirectory, ".agents", "skills", "review-pr--skill1");
+        await mkdir(destination, { recursive: true });
+        await writeFile(join(destination, "keep.txt"), "user owned\n");
+        const downloadBundle = vi.fn(async () => bundle.bytes);
+        const manager = await RuntimeSkillManager.open({ homeDirectory, downloadBundle });
+        const result = await manager.reconcile({
+            manifest: desiredManifest(bundle, "review-pr", "review-pr--skill1", "b"),
+        });
+        expect(result.skills[0]).toMatchObject({
+            state: "conflict",
+            errorCode: "UNMANAGED_PATH_CONFLICT",
+        });
+        expect(await readFile(join(destination, "keep.txt"), "utf8")).toBe("user owned\n");
+        expect(downloadBundle).not.toHaveBeenCalled();
+    });
+    it("renames the exact conflicting local Skill and immediately installs the managed Skill", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const bundle = await createTestBundle("review-pr", "Managed instructions.");
+        const runtimeDirectory = "review-pr--skill1";
+        const destination = join(homeDirectory, ".agents", "skills", runtimeDirectory);
+        await mkdir(destination, { recursive: true });
+        await writeFile(join(destination, "SKILL.md"), "---\nname: review-pr\ndescription: Local instructions.\n---\nKeep this local package.\n");
+        const manager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle: async () => bundle.bytes,
+        });
+        const manifest = desiredManifest(bundle, "review-pr", runtimeDirectory, "4");
+        const reported = await manager.reconcile({ manifest });
+        const conflict = reported.skills[0]?.conflict;
+        if (!conflict)
+            throw new Error("expected a structured conflict");
+        const resolved = await manager.resolveConflict({
+            commandId: "00000000-0000-4000-8000-000000000001",
+            manifest,
+            skillId: manifest.skills[0].skillId,
+            versionId: manifest.skills[0].versionId,
+            expectedConflict: conflict,
+            resolution: { kind: "rename_local", name: "review-pr-local" },
+        });
+        expect(resolved.state).toBe("applied");
+        expect(await readFile(join(homeDirectory, ".agents", "skills", "review-pr-local", "SKILL.md"), "utf8")).toContain("name: review-pr-local");
+        expect(await readFile(join(destination, "SKILL.md"), "utf8")).toContain("Managed instructions.");
+    });
+    it("overwrites only the reported conflict and rolls directly into managed installation", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const bundle = await createTestBundle("review-pr", "Managed replacement.");
+        const runtimeDirectory = "review-pr--skill1";
+        const destination = join(homeDirectory, ".agents", "skills", runtimeDirectory);
+        await mkdir(destination, { recursive: true });
+        await writeFile(join(destination, "SKILL.md"), "---\nname: review-pr\ndescription: Local instructions.\n---\nLocal version.\n");
+        const manager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle: async () => bundle.bytes,
+        });
+        const manifest = desiredManifest(bundle, "review-pr", runtimeDirectory, "5");
+        const reported = await manager.reconcile({ manifest });
+        const conflict = reported.skills[0]?.conflict;
+        if (!conflict)
+            throw new Error("expected a structured conflict");
+        const resolved = await manager.resolveConflict({
+            commandId: "00000000-0000-4000-8000-000000000002",
+            manifest,
+            skillId: manifest.skills[0].skillId,
+            versionId: manifest.skills[0].versionId,
+            expectedConflict: conflict,
+            resolution: { kind: "overwrite_local" },
+        });
+        expect(resolved.state).toBe("applied");
+        expect(await readFile(join(destination, "SKILL.md"), "utf8")).toContain("Managed replacement.");
+        expect((await readdir(join(homeDirectory, ".agents", "skills"))).filter((name) => name.includes("overwrite-backup"))).toEqual([]);
+    });
+    it("rejects a stale conflict resolution without mutating the changed local Skill", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const bundle = await createTestBundle("review-pr", "Managed replacement.");
+        const runtimeDirectory = "review-pr--skill1";
+        const destination = join(homeDirectory, ".agents", "skills", runtimeDirectory);
+        await mkdir(destination, { recursive: true });
+        const localMarkdown = "---\nname: review-pr\ndescription: Local instructions.\n---\nLocal version.\n";
+        await writeFile(join(destination, "SKILL.md"), localMarkdown);
+        const manager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle: async () => bundle.bytes,
+        });
+        const manifest = desiredManifest(bundle, "review-pr", runtimeDirectory, "6");
+        const reported = await manager.reconcile({ manifest });
+        const conflict = reported.skills[0]?.conflict;
+        if (!conflict)
+            throw new Error("expected a structured conflict");
+        await writeFile(join(destination, "SKILL.md"), `${localMarkdown}Changed after report.\n`);
+        const resolved = await manager.resolveConflict({
+            commandId: "00000000-0000-4000-8000-000000000003",
+            manifest,
+            skillId: manifest.skills[0].skillId,
+            versionId: manifest.skills[0].versionId,
+            expectedConflict: conflict,
+            resolution: { kind: "overwrite_local" },
+        });
+        expect(resolved).toMatchObject({ state: "stale", errorCode: "SKILL_CONFLICT_STALE" });
+        expect(await readFile(join(destination, "SKILL.md"), "utf8")).toContain("Changed after report.");
+    });
+    it("keeps the last good projection and revision when an update bundle fails verification", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const firstBundle = await createTestBundle("review-pr", "Review version one.");
+        const secondBundle = await createTestBundle("review-pr", "Review version two.");
+        const downloadBundle = vi
+            .fn()
+            .mockResolvedValueOnce(firstBundle.bytes)
+            .mockResolvedValueOnce(Buffer.from("not a bundle"));
+        const manager = await RuntimeSkillManager.open({ homeDirectory, downloadBundle });
+        const firstManifest = desiredManifest(firstBundle, "review-pr", "review-pr--skill1", "c");
+        await manager.reconcile({ manifest: firstManifest });
+        const projectedSkill = join(homeDirectory, ".agents", "skills", "review-pr--skill1", "SKILL.md");
+        const update = await manager.reconcile({
+            manifest: {
+                ...desiredManifest(secondBundle, "review-pr", "review-pr--skill1", "d"),
+                skills: [
+                    {
+                        ...desiredManifest(secondBundle, "review-pr", "review-pr--skill1", "d").skills[0],
+                        versionId: "33333333-3333-4333-8333-333333333333",
+                    },
+                ],
+            },
+        });
+        expect(update.skills[0]?.state).toBe("failed");
+        expect(await readFile(projectedSkill, "utf8")).toContain("Review version one.");
+        expect((await manager.inspect()).appliedRevision).toBe(firstManifest.revision);
+    });
+    it("removes only recorded managed projections when a Skill is no longer desired", async () => {
+        const homeDirectory = await createTemporaryDirectory();
+        const bundle = await createTestBundle("review-pr", "Review this pull request.");
+        const manager = await RuntimeSkillManager.open({
+            homeDirectory,
+            downloadBundle: async () => bundle.bytes,
+        });
+        await manager.reconcile({
+            manifest: desiredManifest(bundle, "review-pr", "review-pr--skill1", "e"),
+        });
+        const unmanaged = join(homeDirectory, ".agents", "skills", "my-own-skill");
+        await mkdir(unmanaged, { recursive: true });
+        await writeFile(join(unmanaged, "keep.txt"), "keep\n");
+        await manager.reconcile({
+            manifest: {
+                protocolVersion: 1,
+                revision: `sha256:${"f".repeat(64)}`,
+                skills: [],
+            },
+        });
+        await expect(readFile(join(homeDirectory, ".agents", "skills", "review-pr--skill1", "SKILL.md"))).rejects.toMatchObject({ code: "ENOENT" });
+        await expect(lstat(join(homeDirectory, ".claude", "skills", "review-pr--skill1"))).rejects.toMatchObject({ code: "ENOENT" });
+        expect(await readFile(join(unmanaged, "keep.txt"), "utf8")).toBe("keep\n");
+    });
+});
+async function createTestBundle(name, instructions) {
+    const sourceParent = await createTemporaryDirectory();
+    const source = join(sourceParent, name);
+    await mkdir(source, { recursive: true });
+    await writeFile(join(source, "SKILL.md"), `---\nname: ${name}\ndescription: Test ${name}.\n---\n${instructions}\n`);
+    return createSkillBundle(source);
+}
+function desiredManifest(bundle, slug, runtimeDirectory, revisionCharacter) {
+    return {
+        protocolVersion: 1,
+        revision: `sha256:${revisionCharacter.repeat(64)}`,
+        skills: [
+            {
+                skillId: "11111111-1111-4111-8111-111111111111",
+                versionId: "22222222-2222-4222-8222-222222222222",
+                slug,
+                runtimeDirectory,
+                contentHash: bundle.contentHash,
+                archiveHash: bundle.archiveHash,
+                compressedBytes: bundle.bytes.byteLength,
+                downloadUrl: "https://runtime.invalid/signed-bundle",
+                downloadUrlExpiresAt: "2099-01-01T00:00:00.000Z",
+            },
+        ],
+    };
+}
+//# sourceMappingURL=runtime-skill-manager.test.js.map