@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/sources/sources.test.ts

@@ -1,9 +1,12 @@
 import { execFileSync } from "node:child_process";
 import {
   existsSync,
+  lstatSync,
   mkdirSync,
   mkdtempSync,
+  readdirSync,
   readFileSync,
+  readlinkSync,
   rmSync,
   symlinkSync,
   writeFileSync,
@@ -14,13 +17,20 @@ import { join } from "node:path";
 import { runTask } from "@canonical/task/node";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { VERSION } from "../../constants.js";
-import type { ConfigLayers, PackageEntry } from "../../kernel/config/types.js";
+import type {
+  ConfigLayers,
+  PackDeclaration,
+} from "../../kernel/config/types.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
 import { executeVerb } from "../../kernel/project/cli/dispatch.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
 import { createQueryFacade } from "../../kernel/runtime/facade.js";
-import { readLock } from "../../kernel/runtime/lock.js";
-import { lockPath, packDir } from "../../kernel/runtime/paths.js";
+import { readManifest } from "../../kernel/runtime/graphpack/manifest.js";
+import {
+  activePackPath,
+  packDir,
+  readActivePack,
+} from "../../kernel/runtime/paths.js";
 import {
   detectPrefixClashes,
   resolvePackageJson,
@@ -58,18 +68,17 @@ const tmp = (prefix: string): string => {
   return dir;
 };
 
-/** A runtime whose config is the given package list (no config files needed). */
-function runtimeFor(cwd: string, packages: PackageEntry[]): PragmaRuntime {
+/** A runtime whose config is the given pack list (no config files needed). */
+function runtimeFor(cwd: string, packs: PackDeclaration[]): PragmaRuntime {
   const layers: ConfigLayers = {
-    config: { channel: "normal", packages },
+    config: { channel: "normal", packs },
     origins: {
       tier: "default",
       channel: "default",
       detail: "default",
-      packages: "project",
+      packs: "project",
       stories: "default",
       prefixes: "default",
-      prompts: "default",
     },
     global: { path: "/nonexistent", exists: false },
     project: { exists: false },
@@ -101,30 +110,24 @@ function filePackage(): string {
   return pkg;
 }
 
-describe("sources lock round-trip (PROTECTED)", () => {
-  it("file source: builds, locks, and --frozen rewrites a byte-identical lock", async () => {
+describe("sources update round-trip (PROTECTED)", () => {
+  it("file source: builds and points the project at the built pack", async () => {
     const pkg = filePackage();
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    const result = await runTask(await buildUpdateTask(runtime, false));
+    const result = await runTask(await buildUpdateTask(runtime));
     expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
-
-    const lock = readLock(cwd);
-    expect(lock?.packs).toHaveLength(1);
-    expect(lock?.packs[0]?.name).toBe("pkg-a");
-    expect(lock?.packs[0]?.resolved).toBe(pkg);
-    expect(lock?.contentHash).toBe(result.contentHash);
-
-    const firstBytes = readFileSync(lockPath(cwd), "utf-8");
-    // A --frozen re-run reproduces the locked state byte-for-byte.
-    await runTask(await buildUpdateTask(runtime, true));
-    expect(readFileSync(lockPath(cwd), "utf-8")).toBe(firstBytes);
+    expect(result.packs).toEqual([
+      { name: "pkg-a", resolved: pkg, sourceCount: 1, storyCount: 0 },
+    ]);
+    // The pointer the next boot reads names exactly the pack just built.
+    expect(readActivePack(cwd)).toBe(result.contentHash);
   });
 
-  it("git source: resolves and locks a commit SHA, --frozen pins it", async () => {
+  it("git source: resolves the ref to a commit SHA", async () => {
     const repo = tmp("pragma-repo-");
     const git = (args: string[]) =>
       execFileSync("git", args, {
@@ -149,34 +152,39 @@ describe("sources lock round-trip (PROTECTED)", () => {
       { name: "pkg-git", source: `git+file://${repo}#main` },
     ]);
 
-    await runTask(await buildUpdateTask(runtime, false));
-    const lock = readLock(cwd);
-    expect(lock?.packs[0]?.resolved).toMatch(/^[0-9a-f]{40}$/);
-
-    const firstBytes = readFileSync(lockPath(cwd), "utf-8");
-    await runTask(await buildUpdateTask(runtime, true));
-    expect(readFileSync(lockPath(cwd), "utf-8")).toBe(firstBytes);
+    const result = await runTask(await buildUpdateTask(runtime));
+    const sha = result.packs.at(0)?.resolved;
+    expect(sha).toMatch(/^[0-9a-f]{40}$/);
+    expect(readActivePack(cwd)).toBe(result.contentHash);
+    // The revision reaches the manifest's provenance label, which is the only
+    // place `sources status` and `doctor` can read it from now that no lock
+    // records it. Same `<name>@<kind>:<resolved>` shape the bundler writes.
+    expect(readManifest(packDir(result.contentHash))?.sourceRef).toBe(
+      `pkg-git@git:${sha}`,
+    );
   });
 
-  it("a non-frozen re-run over an unchanged source rewrites a byte-identical lock (L1)", async () => {
-    // On base, every non-frozen update stamped a fresh `resolvedAt`, so a no-op
-    // re-run dirtied the tree. When the revision is unchanged the timestamp is
-    // preserved, so the lock is byte-identical.
+  it("a re-run over an unchanged source leaves the pointer byte-identical (L1)", async () => {
+    // On base the lock file carried a `resolvedAt` timestamp, so a no-op re-run
+    // rewrote it and dirtied the tree. The pointer holds only the content hash,
+    // which is a pure function of the sources — so this is now true by
+    // construction. The guard stays because it is the property users cared
+    // about: repeating an update changes nothing when nothing changed.
     const pkg = filePackage();
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
-    await runTask(await buildUpdateTask(runtime, false));
-    const firstBytes = readFileSync(lockPath(cwd), "utf-8");
-    await runTask(await buildUpdateTask(runtime, false));
-    expect(readFileSync(lockPath(cwd), "utf-8")).toBe(firstBytes);
+    await runTask(await buildUpdateTask(runtime));
+    const firstBytes = readFileSync(activePackPath(cwd), "utf-8");
+    await runTask(await buildUpdateTask(runtime));
+    expect(readFileSync(activePackPath(cwd), "utf-8")).toBe(firstBytes);
   });
 
   it("follows a symlinked .ttl into the build (L6)", async () => {
     // pnpm / workspace trees symlink their sources; Dirent.isFile is false for a
     // symlink, so on base the only `.ttl` was skipped → 0 sources → the empty
-    // build. Following the link ingests it and the build+lock succeed.
+    // build. Following the link ingests it and the build succeeds.
     const pkg = tmp("pragma-symlink-pkg-");
     mkdirSync(join(pkg, "definitions"), { recursive: true });
     const realTtl = join(pkg, "real.ttl");
@@ -187,15 +195,15 @@ describe("sources lock round-trip (PROTECTED)", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    const result = await runTask(await buildUpdateTask(runtime, false));
+    const result = await runTask(await buildUpdateTask(runtime));
     expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
-    expect(readLock(cwd)?.packs).toHaveLength(1);
+    expect(readActivePack(cwd)).toBe(result.contentHash);
   });
 
   it("does not recurse into a symlinked directory cycle (L6 safety)", async () => {
     // The L6 fix follows symlinked FILES but must NOT recurse into a symlinked
     // DIRECTORY: a link to an ancestor dir is a cycle that, if walked, recurses
-    // without bound → a stack-overflow RangeError (an INTERNAL "please report").
+    // without bound → a stack-overflow RangeError (an INTERNAL "report").
     // The real `.ttl` is still ingested and the build completes.
     const pkg = tmp("pragma-symlink-cycle-");
     mkdirSync(join(pkg, "definitions"), { recursive: true });
@@ -207,21 +215,20 @@ describe("sources lock round-trip (PROTECTED)", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    const result = await runTask(await buildUpdateTask(runtime, false));
+    const result = await runTask(await buildUpdateTask(runtime));
     expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
-    expect(readLock(cwd)?.packs).toHaveLength(1);
+    expect(readActivePack(cwd)).toBe(result.contentHash);
   });
 
-  it("undo restores the prior lock (no prior → removed)", async () => {
+  it("undo removes the pointer when the project had none before", async () => {
     const pkg = filePackage();
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
     const { runUndo } = await import("@canonical/task/node");
-    await runUndo(await buildUpdateTask(runtime, false));
-    // Prior lock was absent, so undo removes the file.
-    expect(readLock(cwd)).toBeUndefined();
+    await runUndo(await buildUpdateTask(runtime));
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 });
 
@@ -237,7 +244,7 @@ describe("sources update — package-declared prefixes (M1)", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    const result = await runTask(await buildUpdateTask(runtime, false));
+    const result = await runTask(await buildUpdateTask(runtime));
     const index = JSON.parse(
       readFileSync(join(packDir(result.contentHash), "index.json"), "utf-8"),
     ) as {
@@ -267,30 +274,30 @@ describe("sources update — refuses an empty store (A4)", () => {
     return pkg;
   }
 
-  it("a package with no .ttl is refused, and no lock is written", async () => {
+  it("a package with no .ttl is refused, and no pointer is written", async () => {
     // On base this builds a 0-triple pack whose empty data.nq fails the
     // completeness gate — so the "successful" update boots to a PERMANENT
-    // STORE_UNAVAILABLE loop. The fix refuses before writing the lock.
+    // STORE_UNAVAILABLE loop. The fix refuses before writing the pointer.
     const pkg = emptyPackage();
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
+    await expect(buildUpdateTask(runtime)).rejects.toMatchObject({
       code: "CONFIG_ERROR",
     });
-    // No lock → the embedded fallback / prior state survives, no boot loop.
-    expect(readLock(cwd)).toBeUndefined();
+    // No pointer → the embedded fallback / prior state survives, no boot loop.
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 
-  it("no configured packages is refused rather than locking an empty pack", async () => {
+  it("no configured packs is refused rather than pointing at an empty pack", async () => {
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, []);
-    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
+    await expect(buildUpdateTask(runtime)).rejects.toMatchObject({
       code: "CONFIG_ERROR",
     });
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 
   it("a comment-only .ttl (0 triples) is refused too", async () => {
@@ -305,10 +312,10 @@ describe("sources update — refuses an empty store (A4)", () => {
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
-    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
+    await expect(buildUpdateTask(runtime)).rejects.toMatchObject({
       code: "CONFIG_ERROR",
     });
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 });
 
@@ -358,7 +365,7 @@ describe("sources update — conflicting @prefix detection (A5)", () => {
       report: (message: string) => reports.push(message),
     };
 
-    await runTask(await buildUpdateTask(runtime, false));
+    await runTask(await buildUpdateTask(runtime));
     expect(
       reports.some(
         (r) => r.includes('Prefix "ex:"') && r.includes("conflicting"),
@@ -385,11 +392,12 @@ describe("sources update — network-free preview (M2)", () => {
 
     // A successful plan — the unreachable clone was never attempted.
     expect(outcome.exitCode).toBe(0);
-    expect(outcome.stdout).toContain("Resolve and build 1 package(s)");
+    expect(outcome.stdout).toContain("Resolve and build 1 pack(s)");
     expect(outcome.stdout).toContain(UNREACHABLE);
-    // The one project mutation is previewed, not performed.
-    expect(outcome.stdout).toContain("pragma.lock.json");
-    expect(readLock(cwd)).toBeUndefined();
+    // The project mutation is previewed, not performed: the plan names the
+    // exact pointer file a real run would write, and no pointer landed.
+    expect(outcome.stdout).toContain(activePackPath(cwd));
+    expect(readActivePack(cwd)).toBeUndefined();
     // The store was never even asked for.
     expect(runtime.store.booted).toBe(false);
   });
@@ -398,7 +406,7 @@ describe("sources update — network-free preview (M2)", () => {
     const cwd = tmp("pragma-proj-");
     writeFileSync(
       join(cwd, "pragma.config.ts"),
-      `export default { packages: [{ name: "pkg-remote", source: "${UNREACHABLE}" }] };\n`,
+      `export default { packs: [{ name: "pkg-remote", source: "${UNREACHABLE}" }] };\n`,
     );
 
     const mcp = await projectMcp([sourcesModule], cwd);
@@ -412,25 +420,8 @@ describe("sources update — network-free preview (M2)", () => {
     });
     const plan = (envelope.data as { plan: string[] }).plan;
     expect(plan.some((line) => line.includes(UNREACHABLE))).toBe(true);
-    // Plan-first withheld the write — no lock landed.
-    expect(readLock(cwd)).toBeUndefined();
-  });
-});
-
-describe("sources update — reproducible-or-fail (m5)", () => {
-  it("--frozen refuses a package that has no lock entry", async () => {
-    const pkg = filePackage();
-    const cwd = tmp("pragma-proj-");
-    const runtime = runtimeFor(cwd, [
-      { name: "pkg-a", source: `file://${pkg}` },
-    ]);
-
-    // No prior lock → nothing to reproduce → refuse rather than silently
-    // advance. The throw is raised during setup, before any Task is returned.
-    await expect(buildUpdateTask(runtime, true)).rejects.toMatchObject({
-      code: "CONFIG_ERROR",
-    });
-    expect(readLock(cwd)).toBeUndefined();
+    // Plan-first withheld the write — no pointer landed.
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 });
 
@@ -498,7 +489,7 @@ describe("sources update — data-failure classification (U6)", () => {
 
     let caught: unknown;
     try {
-      await buildUpdateTask(runtime, false);
+      await buildUpdateTask(runtime);
     } catch (error) {
       caught = error;
     }
@@ -511,13 +502,13 @@ describe("sources update — data-failure classification (U6)", () => {
     expect(err.message).toContain("bad-pkg/definitions/broken.ttl");
     // … carries the parser's own detail …
     expect(err.message.toLowerCase()).toContain("parser error");
-    // … and is NOT the internal-bug "please report this issue" path.
+    // … and is NOT the internal-bug "report this issue" path.
     expect(err.message).not.toContain("Internal error");
     expect(err.recovery?.message ?? "").not.toContain("report this issue");
     // The recovery points the user at a runnable, useful next step.
     expect(err.recovery?.cli).toBe("pragma sources update --verbose");
-    // Nothing was locked on failure.
-    expect(readLock(cwd)).toBeUndefined();
+    // Nothing was pointed at on failure.
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 
   it("classifies a git clone failure, naming the package (not INTERNAL)", async () => {
@@ -534,7 +525,7 @@ describe("sources update — data-failure classification (U6)", () => {
 
     let caught: unknown;
     try {
-      await buildUpdateTask(runtime, false);
+      await buildUpdateTask(runtime);
     } catch (error) {
       caught = error;
     }
@@ -543,7 +534,7 @@ describe("sources update — data-failure classification (U6)", () => {
     expect(err.code).toBe("CONFIG_ERROR");
     expect(err.message).toContain("pkg-remote");
     expect(err.message).not.toContain("Internal error");
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 
   it("names the SPECIFIC bad file among several good ones", async () => {
@@ -557,12 +548,12 @@ describe("sources update — data-failure classification (U6)", () => {
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, [{ name: "mix", source: `file://${pkg}` }]);
 
-    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
+    await expect(buildUpdateTask(runtime)).rejects.toMatchObject({
       code: "CONFIG_ERROR",
     });
     let caught: unknown;
     try {
-      await buildUpdateTask(runtime, false);
+      await buildUpdateTask(runtime);
     } catch (error) {
       caught = error;
     }
@@ -594,9 +585,9 @@ describe("sources update — hidden files and --skip-invalid", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    const result = await runTask(await buildUpdateTask(runtime, false));
+    const result = await runTask(await buildUpdateTask(runtime));
     expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
-    expect(readLock(cwd)?.packs).toHaveLength(1);
+    expect(readActivePack(cwd)).toMatch(/^[0-9a-f]{64}$/);
   });
 
   it("without --skip-invalid, one malformed source fails the whole update", async () => {
@@ -605,10 +596,10 @@ describe("sources update — hidden files and --skip-invalid", () => {
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
-    await expect(buildUpdateTask(runtime, false, false)).rejects.toMatchObject({
+    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
       code: "CONFIG_ERROR",
     });
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 
   it("with --skip-invalid, drops the bad source, warns loudly, and builds from the rest", async () => {
@@ -620,10 +611,10 @@ describe("sources update — hidden files and --skip-invalid", () => {
       report: (message: string) => reports.push(message),
     };
 
-    const result = await runTask(await buildUpdateTask(runtime, false, true));
+    const result = await runTask(await buildUpdateTask(runtime, true));
     // Built from the good widget.ttl, not aborted.
     expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
-    expect(readLock(cwd)?.packs).toHaveLength(1);
+    expect(readActivePack(cwd)).toMatch(/^[0-9a-f]{64}$/);
     // Loud per-source warning names the dropped file …
     expect(
       reports.some(
@@ -643,10 +634,10 @@ describe("sources update — hidden files and --skip-invalid", () => {
       ...runtimeFor(cwd, [{ name: "pkg-a", source: `file://${pkg}` }]),
       report: () => {},
     };
-    await expect(buildUpdateTask(runtime, false, true)).rejects.toMatchObject({
+    await expect(buildUpdateTask(runtime, true)).rejects.toMatchObject({
       code: "CONFIG_ERROR",
     });
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
   });
 });
 
@@ -740,7 +731,7 @@ describe("sources update — installs package skills (U10)", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
 
-    await runTask(await buildUpdateTask(runtime, false));
+    await runTask(await buildUpdateTask(runtime));
 
     // Installed as a symlink into $XDG_DATA_HOME/pragma/skills …
     const linked = join(dataHome, "pragma", "skills", "foo");
@@ -762,7 +753,7 @@ describe("sources update — installs package skills (U10)", () => {
     const runtime = runtimeFor(cwd, [
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
-    await runTask(await buildUpdateTask(runtime, false));
+    await runTask(await buildUpdateTask(runtime));
 
     const shared = discoverSkills(cwd).filter((s) => s.name === "shared");
     expect(shared).toHaveLength(1);
@@ -776,35 +767,191 @@ describe("sources update — installs package skills (U10)", () => {
       { name: "pkg-a", source: `file://${pkg}` },
     ]);
     const { runUndo } = await import("@canonical/task/node");
-    await runUndo(await buildUpdateTask(runtime, false));
+    await runUndo(await buildUpdateTask(runtime));
 
     expect(existsSync(join(dataHome, "pragma", "skills", "bar"))).toBe(false);
   });
+
+  /** The installed-skills root, created so a prior install can be seeded into it. */
+  function installedRoot(): string {
+    const root = join(dataHome, "pragma", "skills");
+    mkdirSync(root, { recursive: true });
+    return root;
+  }
+
+  /** A symlink at `<installedRoot>/<name>` whose target does not exist. */
+  function danglingLink(root: string, name: string): string {
+    const target = join(tmp("pragma-uninstalled-"), "skills", name);
+    symlinkSync(target, join(root, name));
+    return target;
+  }
+
+  // The `@canonical/design-system` 0.2.0 regression: 0.1.2 shipped
+  // `component-specifier`, 0.2.0 deleted it in favour of `specify-component`,
+  // and every machine that had updated against 0.1.2 kept a symlink into a
+  // package directory that no longer exists.
+  it("prunes a link whose package dropped the skill", async () => {
+    const pkg = skillPackage("specify-component"); // the 0.2.0 shape
+    const root = installedRoot();
+    danglingLink(root, "component-specifier"); // what 0.1.2 left behind
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "design-system", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime));
+
+    expect(readdirSync(root)).toEqual(["specify-component"]);
+    expect(discoverSkills(cwd).map((s) => s.name)).not.toContain(
+      "component-specifier",
+    );
+  });
+
+  it("spares a manually-installed skill and a foreign link that still resolves", async () => {
+    const pkg = skillPackage("specify-component");
+    const root = installedRoot();
+    danglingLink(root, "component-specifier");
+
+    // A hand-installed skill: a REAL directory, belonging to no package. The
+    // install pass already refuses to clobber these; so must the prune pass.
+    const manual = join(root, "hand-written");
+    mkdirSync(manual, { recursive: true });
+    writeFileSync(
+      join(manual, "SKILL.md"),
+      "---\nname: hand-written\ndescription: Mine.\n---\n",
+    );
+    // Someone's own link into a checkout this update knows nothing about, and
+    // which still resolves. Deliberately RELATIVE: a relative target is stored
+    // relative to the LINK's directory, so resolving it against anything else
+    // (the cwd, say) would read as broken and eat a perfectly live link.
+    const foreign = join(dataHome, "elsewhere", "my-own");
+    mkdirSync(foreign, { recursive: true });
+    writeFileSync(
+      join(foreign, "SKILL.md"),
+      "---\nname: my-own\ndescription: Theirs.\n---\n",
+    );
+    symlinkSync(join("..", "..", "elsewhere", "my-own"), join(root, "my-own"));
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "design-system", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime));
+
+    // Only the dangling link went.
+    expect(readdirSync(root).sort()).toEqual([
+      "hand-written",
+      "my-own",
+      "specify-component",
+    ]);
+    expect(lstatSync(manual).isDirectory()).toBe(true);
+    expect(existsSync(join(manual, "SKILL.md"))).toBe(true);
+    expect(lstatSync(join(root, "my-own")).isSymbolicLink()).toBe(true);
+    expect(existsSync(join(root, "my-own"))).toBe(true); // still resolves
+    const found = discoverSkills(cwd).map((s) => s.name);
+    expect(found).toEqual(
+      expect.arrayContaining(["hand-written", "my-own", "specify-component"]),
+    );
+  });
+
+  it("re-points, rather than prunes, a dangling link the package still provides", async () => {
+    const pkg = skillPackage("foo");
+    const root = installedRoot();
+    danglingLink(root, "foo"); // e.g. the package moved to a new cache dir
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime));
+
+    // `replaced`, never `pruned`: the prune pass skips every name this run
+    // planned, or it would delete the link the install pass just created.
+    expect(readlinkSync(join(root, "foo"))).toBe(join(pkg, "skills", "foo"));
+    expect(discoverSkills(cwd).map((s) => s.name)).toContain("foo");
+  });
+
+  it("is reversible — undo restores a pruned link, dangling target and all", async () => {
+    const pkg = skillPackage("specify-component");
+    const root = installedRoot();
+    const staleTarget = danglingLink(root, "component-specifier");
+    const link = join(root, "component-specifier");
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "design-system", source: `file://${pkg}` },
+    ]);
+    // The plan is made while the stale link is still there; `runUndo` MOCKS the
+    // forward effects, so stand in for the delete it would have performed.
+    const task = await buildUpdateTask(runtime);
+    rmSync(link);
+
+    const { runUndo } = await import("@canonical/task/node");
+    await runUndo(task);
+
+    expect(lstatSync(link).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(link)).toBe(staleTarget); // the target it always had
+  });
+
+  it("undoes a prune whose forward delete never ran, rather than failing EEXIST", async () => {
+    const pkg = skillPackage("specify-component");
+    const root = installedRoot();
+    const staleTarget = danglingLink(root, "component-specifier");
+
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "design-system", source: `file://${pkg}` },
+    ]);
+    // No `rmSync` this time: the link is still in place when the undo re-links,
+    // and `fs.symlink` refuses an existing path — so the undo must clear it.
+    const { runUndo } = await import("@canonical/task/node");
+    await expect(runUndo(await buildUpdateTask(runtime))).resolves.toBeTruthy();
+
+    expect(readlinkSync(join(root, "component-specifier"))).toBe(staleTarget);
+  });
+
+  it("plans no prunes when nothing was ever installed", async () => {
+    const pkg = skillPackage("foo"); // $XDG_DATA_HOME/pragma/skills absent
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime));
+
+    expect(readdirSync(join(dataHome, "pragma", "skills"))).toEqual(["foo"]);
+  });
 });
 
 describe("sources status — entityCount from the manifest (A10)", () => {
-  it("reports the count without re-parsing index.json", async () => {
-    const pkg = filePackage(); // ex:Widget class + ex:one individual
+  it("reports the count from the manifest even when index.json is unreadable", async () => {
+    // A pack of its OWN (unique TTL ⇒ unique content hash), so corrupting its
+    // cached index cannot reach any other test's pack in the shared cache.
+    const pkg = tmp("pragma-a10-pkg-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    writeFileSync(
+      join(pkg, "definitions", "widget.ttl"),
+      `${TTL}ex:a10only a ex:Widget ; rdfs:label "A10" .\n`,
+    );
     const cwd = tmp("pragma-proj-");
     const runtime = runtimeFor(cwd, [
-      { name: "pkg-a", source: `file://${pkg}` },
+      { name: "pkg-a10", source: `file://${pkg}` },
     ]);
-    const result = await runTask(await buildUpdateTask(runtime, false));
+    const result = await runTask(await buildUpdateTask(runtime));
 
-    // Delete index.json: any path that PARSED it to count would now fail —
-    // proving the figure is read from the manifest's persisted entityCount.
-    rmSync(join(packDir(result.contentHash), "index.json"), { force: true });
+    // Corrupt index.json but keep it non-empty, so the pack still reads as
+    // complete: any path that PARSED it to count would now yield null.
+    writeFileSync(join(packDir(result.contentHash), "index.json"), "not json");
 
     const status = await collectStatus(bootRuntime(flagsJson, cwd));
-    // One abox individual (ex:one); the ex:Widget class is tbox, not counted.
-    expect(status.entityCount).toBe(1);
+    // Two abox individuals (ex:one, ex:a10only); ex:Widget is tbox, not counted.
+    expect(status.entityCount).toBe(2);
   });
 });
 
 describe("sources status CLI-json == MCP tool (PROTECTED)", () => {
-  it("a cold store's status is byte-equal on both surfaces", async () => {
-    // Both surfaces boot from the SAME cwd + isolated config (default packages,
-    // no lock), so the storeless status must be identical.
+  it("a fresh install's status is byte-equal on both surfaces", async () => {
+    // Both surfaces boot from the SAME cwd + isolated config (default packs,
+    // nothing built), so the storeless status must be identical.
     const cwd = tmp("pragma-proj-");
     const cli = await executeVerb(
       statusVerb,
@@ -820,9 +967,8 @@ describe("sources status CLI-json == MCP tool (PROTECTED)", () => {
 
     expect(cliEnvelope).toEqual(mcpEnvelope);
     expect(cliEnvelope.ok).toBe(true);
-    expect((cliEnvelope.data as { lockPresent: boolean }).lockPresent).toBe(
-      false,
-    );
-    expect((cliEnvelope.data as { cached: boolean }).cached).toBe(false);
+    // Nothing built here, and the packs are the distribution's own — so the
+    // embedded snapshot is what answers reads, and status says exactly that.
+    expect((cliEnvelope.data as { store: string }).store).toBe("embedded");
   });
 });