@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/capabilities/shared/assertExecOk.ts

@@ -13,13 +13,66 @@
  * A denied `npm i -g` (EACCES), a registry/network failure, or any other
  * nonzero exit is a fixable ENVIRONMENT condition — NOT a pragma bug — so it is
  * classified UNSUPPORTED with an actionable recovery, never INTERNAL_ERROR's
- * "please report this issue". (A spawn error like ENOENT REJECTS the effect
+ * "report this issue". (A spawn error like ENOENT REJECTS the effect
  * instead of resolving, so it never reaches here.)
  */
 
-import { type ExecResult, fail, recover, type Task } from "@canonical/task";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import type { Recovery } from "../../kernel/error/types.js";
+import {
+  type ExecResult,
+  fail,
+  pure,
+  recover,
+  type Task,
+} from "@canonical/task";
+import type { Recovery } from "../../kernel/error/index.js";
+import { PragmaError } from "../../kernel/error/index.js";
+
+/**
+ * Route a {@link PragmaError} through the Task FAILURE CHANNEL (a `Fail` node
+ * carrying the error as `cause`) instead of a synchronous throw.
+ *
+ * The distinction is load-bearing: a synchronous throw from a bind/recover
+ * continuation ESCAPES the interpreter's trampoline entirely — no enclosing
+ * `recover` can see it — whereas a `Fail` node unwinds to the nearest recovery
+ * frame. Setup's run-all isolates each step with `recover` so one failed step
+ * cannot abort the rest (S1-1); that only works if step failures travel the
+ * failure channel. The boundary (`asPragmaError`) unwraps the carried cause,
+ * so a failure that escapes un-recovered still renders with its own code,
+ * message, and recovery — never the INTERNAL_ERROR catch-all.
+ */
+export function failPragma(error: PragmaError): Task<never> {
+  return fail({ code: error.code, message: error.message, cause: error });
+}
+
+/**
+ * The failure-channel sibling of {@link assertExecOk}: yield `pure(undefined)`
+ * on exit 0, otherwise fail with an UNSUPPORTED {@link PragmaError} carrying
+ * the command, exit code, trimmed stderr, and the CALLER'S recovery — the
+ * recovery must name an action that works on this machine now, not the generic
+ * "permissions or network" guess.
+ *
+ * @param command - Human-readable command, surfaced in the error message.
+ * @param result - The {@link ExecResult} the `exec` effect yielded.
+ * @param recovery - The actionable, site-specific recovery.
+ * @returns A Task that succeeds on exit 0 and fails (recoverably) otherwise.
+ */
+export function checkExecOk(
+  command: string,
+  result: ExecResult,
+  recovery: Recovery,
+): Task<void> {
+  if (result.exitCode === 0) return pure(undefined);
+  const stderr = result.stderr.trim();
+  return failPragma(
+    new PragmaError({
+      code: "UNSUPPORTED",
+      message: `\`${command}\` exited with code ${result.exitCode}.${
+        stderr ? `\n${stderr}` : ""
+      }`,
+      recovery,
+    }),
+  );
+}
 
 /**
  * Raise UNSUPPORTED when an `exec` result carries a nonzero exit code.
@@ -40,7 +93,7 @@ export function assertExecOk(command: string, result: ExecResult): void {
     }`,
     recovery: {
       message:
-        "The command failed — often a permissions or network issue. Check the output above and retry (for a global install, try elevated privileges).",
+        "Check the command's output above; a global install may need elevated privileges.",
     },
   });
 }
@@ -93,11 +146,16 @@ export function guardMissingBinary<A>(
 ): Task<A> {
   return recover(task, (error) => {
     if (isMissingBinaryError(error)) {
-      throw new PragmaError({
-        code: "UNSUPPORTED",
-        message: `\`${bin}\` was not found on your PATH.`,
-        recovery,
-      });
+      // Failure CHANNEL, not a synchronous throw: an enclosing recover (the
+      // run-all's per-step isolation, S1-1) must be able to catch this, and
+      // the boundary unwraps the carried PragmaError when nothing does.
+      return failPragma(
+        new PragmaError({
+          code: "UNSUPPORTED",
+          message: `\`${bin}\` was not found on your PATH.`,
+          recovery,
+        }),
+      );
     }
     // Not a missing binary — re-raise unchanged (the interpreter rethrows it as
     // a TaskExecutionError, exactly as it would with no guard installed).

package/src/capabilities/shared/index.ts

@@ -0,0 +1,32 @@
+/**
+ * The cross-capability shared surface — the few facts more than one capability
+ * needs and none of them owns.
+ *
+ * Everything here earned its place by being needed in two capabilities at
+ * once, and the cohesion principle is that shortness of the list. `shared/` is
+ * not a utility drawer: a helper used by exactly one capability belongs in
+ * that capability, and the moment something here has a single consumer again
+ * it should move back. What survives is the environment the CLI reports on but
+ * does not own — how it was installed, what the registry says about it,
+ * whether a subprocess it ran actually succeeded — plus the one piece of
+ * vocabulary (`BAND_LABELS`) that keeps `setup` and `doctor` calling the two
+ * config bands by the same names users meet in the flags.
+ *
+ * The exec guard is exported as the pair a caller needs together: `checkExecOk`
+ * to classify a result inside a Task and `assertExecOk` to throw on one
+ * outside, with `guardMissingBinary` wrapping the absent-binary case that
+ * neither should report as a pragma bug. The predicates they are built from
+ * stay internal — a caller reaching for the predicate instead of the guard is
+ * a caller about to reimplement the classification.
+ */
+
+export {
+  assertExecOk,
+  checkExecOk,
+  guardMissingBinary,
+} from "./assertExecOk.js";
+export { BAND_LABELS } from "./bands.js";
+export type { InstallSource } from "./packageManager.js";
+export { detectInstallSource, pmUpdateCommand } from "./packageManager.js";
+export type { RegistryCheckResult } from "./registry.js";
+export { checkRegistryVersion, PRAGMA_PACKAGE } from "./registry.js";

package/src/capabilities/shared/packageManager.test.ts

@@ -0,0 +1,55 @@
+/**
+ * The install-scope heuristic's two path questions.
+ *
+ * `detectInstallSource` itself reads `import.meta.url` and the real working
+ * directory, so the decision it makes is exercised here through the two pure
+ * helpers it composes — which is where every case that has ever been wrong
+ * lives.
+ */
+
+import { describe, expect, it } from "vitest";
+import { containsPath, findInstallRoot } from "./packageManager.js";
+
+describe("findInstallRoot", () => {
+  it("yields the directory the package was installed into", () => {
+    expect(
+      findInstallRoot(
+        "/proj/node_modules/@canonical/pragma-cli/dist/src/bin.js",
+      ),
+    ).toBe("/proj");
+  });
+
+  it("takes the INNERMOST node_modules when they nest", () => {
+    expect(
+      findInstallRoot("/proj/node_modules/a/node_modules/b/dist/bin.js"),
+    ).toBe("/proj/node_modules/a");
+  });
+
+  it("reports no install root for a source checkout", () => {
+    expect(findInstallRoot("/work/pragma/packages/cli/pragma/src/bin.ts")).toBe(
+      undefined,
+    );
+  });
+});
+
+describe("containsPath", () => {
+  it("counts a directory as containing itself", () => {
+    expect(containsPath("/proj", "/proj")).toBe(true);
+  });
+
+  // The case a literal cwd-prefix test got wrong: an ordinary local install run
+  // from a subdirectory — which in a monorepo is the usual way to run it — was
+  // reported as a GLOBAL install.
+  it("counts a subdirectory as contained", () => {
+    expect(containsPath("/proj", "/proj/packages/foo")).toBe(true);
+  });
+
+  it("does not count a sibling that merely shares a prefix", () => {
+    expect(containsPath("/proj", "/proj-two")).toBe(false);
+  });
+
+  it("does not count an ancestor or an unrelated tree", () => {
+    expect(containsPath("/proj/packages/foo", "/proj")).toBe(false);
+    expect(containsPath("/usr/lib", "/home/u/proj")).toBe(false);
+  });
+});

package/src/capabilities/shared/packageManager.ts

@@ -4,12 +4,15 @@
  *
  * Promotes the detector that lived inline in `info/collectInfo.ts`: the package
  * manager comes from npm's `npm_config_user_agent` (set by npm/pnpm/yarn/bun
- * when they run a script), the scope from whether the binary sits under
- * `node_modules`. With no agent we report the honest runtime rather than
- * guessing. The old shell's full package.json walk (`#package-manager`) is
+ * when they run a script), the scope from whether the installed entry sits
+ * under the CURRENT PROJECT. With no agent we report the honest runtime rather
+ * than guessing. The old shell's full package.json walk (`#package-manager`) is
  * dropped — only this heuristic and the update-command map survive.
  */
 
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
 /** The install source: package manager and a display label. */
 export interface InstallSource {
   /** Package-manager name (`bun`/`npm`/`pnpm`/`yarn`), else the honest runtime. */
@@ -30,11 +33,64 @@ function packageManager(): string {
  * Detect how the binary was installed — package manager and scope.
  *
  * @returns The install source (pm, label).
- * @note Impure — reads `process.argv`/`process.env`.
+ * @note Impure — reads `import.meta.url`, the working directory, and `process.env`.
  */
+/**
+ * The directory a package was installed INTO — the parent of the `node_modules`
+ * holding it, so `/proj/node_modules/@scope/x/dist/bin.js` yields `/proj`.
+ *
+ * The LAST occurrence, because nested `node_modules` mean the innermost one is
+ * the tree the entry actually lives in.
+ *
+ * @param entry - Absolute path to the running module.
+ * @returns The install root, or `undefined` when the entry is not installed at
+ *   all (a source checkout, where no `node_modules` segment appears).
+ * @remarks Exported for its unit test; not part of the package's public surface.
+ */
+export function findInstallRoot(entry: string): string | undefined {
+  const segments = entry.split(sep);
+  const index = segments.lastIndexOf("node_modules");
+  return index === -1 ? undefined : segments.slice(0, index).join(sep);
+}
+
+/**
+ * Whether `directory` contains `candidate`, or is it.
+ *
+ * Compared through `relative()` rather than a string prefix: a prefix test needs
+ * a hard-coded separator (wrong on Windows) and would call `/proj-two` a child
+ * of `/proj`.
+ *
+ * @param directory - The containing directory.
+ * @param candidate - The path to test.
+ * @returns True when `candidate` is `directory` or sits beneath it.
+ * @remarks Exported for its unit test; not part of the package's public surface.
+ */
+export function containsPath(directory: string, candidate: string): boolean {
+  const offset = relative(directory, candidate);
+  return offset === "" || (!offset.startsWith("..") && !isAbsolute(offset));
+}
+
 export function detectInstallSource(): InstallSource {
-  const bin = process.argv[1] ?? "";
-  const scope = bin.includes("node_modules") ? "local" : "global";
+  // The entry's own location, NOT `process.argv[1]`. Under the compiled binary
+  // argv[1] was the user's FIRST ARGUMENT (the executable was argv[0]), so the
+  // old `includes("node_modules")` test read a command word and answered
+  // "global" for almost everything. Shipping `node dist/src/bin.js` moves the
+  // entry path INTO argv[1], where it always contains `node_modules` — which
+  // would answer "local" for everything, the same bug facing the other way.
+  // `import.meta.url` is the honest source either way.
+  const entry = fileURLToPath(import.meta.url);
+  // LOCAL means the working directory sits inside the project this package was
+  // installed into — not merely that the entry sits under the cwd. Asking the
+  // narrower question called a perfectly ordinary local install "global" the
+  // moment the user ran it from a subdirectory, which in a monorepo is the
+  // usual case. Going the other way, deriving the install root also settles the
+  // $HOME-nested global prefixes (nvm, `~/.npm-global`): their root is the
+  // prefix, which contains no user project.
+  const root = findInstallRoot(entry);
+  const scope =
+    root !== undefined && containsPath(root, resolve(process.cwd()))
+      ? "local"
+      : "global";
   const pm = packageManager();
   return { pm, label: `${pm} (${scope})` };
 }

package/src/capabilities/skill/discover.ts

@@ -120,6 +120,19 @@ export function installedSkillsDir(): string {
   return join(dataHome, BIN_NAME, "skills");
 }
 
+/**
+ * The project skills root: `<cwd>/.<bin>/skills` — skills that belong to THIS
+ * repository and travel with it. Named separately from {@link skillRoots}
+ * because the two roots are also the two setup BANDS: `setup skills --local`
+ * links this root into the project's harness directories, while the global band
+ * links {@link installedSkillsDir} into the user-level ones. Mixing them leaks
+ * machine state into a repository's directories, or applies one repository's
+ * skills machine-wide.
+ */
+export function projectSkillsDir(cwd: string): string {
+  return join(cwd, `.${BIN_NAME}`, "skills");
+}
+
 /**
  * The conventional roots skills are discovered from, in PRECEDENCE order: the
  * project root (`<cwd>/.<bin>/skills`) FIRST so a project-local skill overrides
@@ -128,7 +141,7 @@ export function installedSkillsDir(): string {
  * skills land on `sources update`).
  */
 export function skillRoots(cwd: string): string[] {
-  return [join(cwd, `.${BIN_NAME}`, "skills"), installedSkillsDir()];
+  return [projectSkillsDir(cwd), installedSkillsDir()];
 }
 
 /** Immediate subdirectories of `root` (each a candidate skill folder). */
@@ -149,16 +162,24 @@ function subdirs(root: string): string[] {
 }
 
 /**
- * Discover every skill reachable from the conventional roots.
+ * Discover every skill reachable from an EXPLICIT list of roots, in precedence
+ * order (first-seen wins on a duplicate name).
  *
- * @param cwd - The project directory (project skills root).
+ * Split out of {@link discoverSkills} so a caller that owns one band can read
+ * exactly that band's root: `setup skills` links the project root into project
+ * harness directories and the installed root into user-level ones, and reading
+ * both roots for either band is what used to mix the two.
+ *
+ * @param roots - The roots to read, in precedence order.
  * @returns Discovered skills, sorted by name; malformed ones are skipped.
  * @note Impure — reads SKILL.md files.
  */
-export function discoverSkills(cwd: string): DiscoveredSkill[] {
+export function discoverSkillsFrom(
+  roots: readonly string[],
+): DiscoveredSkill[] {
   const skills: DiscoveredSkill[] = [];
   const seen = new Set<string>();
-  for (const root of skillRoots(cwd)) {
+  for (const root of roots) {
     for (const dir of subdirs(root)) {
       let content: string;
       try {
@@ -182,3 +203,14 @@ export function discoverSkills(cwd: string): DiscoveredSkill[] {
     a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
   );
 }
+
+/**
+ * Discover every skill reachable from the conventional roots.
+ *
+ * @param cwd - The project directory (project skills root).
+ * @returns Discovered skills, sorted by name; malformed ones are skipped.
+ * @note Impure — reads SKILL.md files.
+ */
+export function discoverSkills(cwd: string): DiscoveredSkill[] {
+  return discoverSkillsFrom(skillRoots(cwd));
+}

package/src/capabilities/skill/index.ts

@@ -2,7 +2,7 @@
  * The `skill` capability module — storeless filesystem discovery.
  */
 
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { skillListVerb, skillLookupVerb } from "./verbs.js";
 
 /** The `skill` capability module (`list`, `lookup`). */

package/src/capabilities/skill/render.ts

@@ -3,7 +3,7 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { DiscoveredSkill } from "./discover.js";
 import type { SkillLookup } from "./verbs.js";
 
@@ -12,15 +12,16 @@ const EMPTY_PLAIN = `No skills found.\nSkills come from design-system packs —
 const EMPTY_LLM = `## Skills (0)\n\nNo skills found. Skills come from design-system packs — add one to the project config's packs, run \`${BIN_NAME} sources update\`, then \`${BIN_NAME} setup skills\`.`;
 
 export const skillListFormatters: Formatters<DiscoveredSkill[]> = {
+  // Zero skills: plain stdout stays empty — the guidance is `emptyNotice`,
+  // which the dispatcher routes to stderr (exit 0) so a pipe reads no prose.
   plain: (skills) =>
-    skills.length === 0
-      ? EMPTY_PLAIN
-      : skills
-          .map(
-            (s) =>
-              `${s.name}${s.frontmatter.prompt ? " (prompt)" : ""}  ${s.description}`,
-          )
-          .join("\n"),
+    skills
+      .map(
+        (s) =>
+          `${s.name}${s.frontmatter.prompt ? " (prompt)" : ""}  ${s.description}`,
+      )
+      .join("\n"),
+  emptyNotice: (skills) => (skills.length === 0 ? EMPTY_PLAIN : undefined),
   llm: (skills) =>
     skills.length === 0
       ? EMPTY_LLM

package/src/capabilities/skill/skill.test.ts

@@ -85,11 +85,13 @@ describe("skill lookup (storeless)", () => {
 });
 
 describe("skill list empty-state (U5)", () => {
-  it("plain output is non-blank and guides toward package sources", () => {
-    const plain = skillListFormatters.plain([]);
-    expect(plain).not.toBe("");
-    expect(plain).toContain("No skills found");
-    expect(plain).toContain("pragma sources update");
+  it("the empty notice (stderr's text) guides toward package sources", () => {
+    // Zero skills: plain stdout is empty (a pipe reads no prose) and the
+    // guidance rides the dispatcher's stderr via `emptyNotice`.
+    expect(skillListFormatters.plain([])).toBe("");
+    const notice = skillListFormatters.emptyNotice?.([]);
+    expect(notice).toContain("No skills found");
+    expect(notice).toContain("pragma sources update");
   });
 
   it("llm output announces zero and guides, json stays []", () => {

package/src/capabilities/skill/verbs.ts

@@ -9,12 +9,11 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { BIN_NAME } from "../../constants.js";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import { cliRecovery } from "../../kernel/error/recovery.js";
+import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
 import { suggestNames } from "../../kernel/project/cli/suggestNames.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import { type DiscoveredSkill, discoverSkills } from "./discover.js";
 import { skillListFormatters, skillLookupFormatters } from "./render.js";
 

package/src/capabilities/sources/collectStatus.ts

@@ -12,12 +12,17 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { PackDeclaration } from "../../kernel/config/types.js";
+import type { PackDeclaration } from "../../kernel/config/index.js";
+// DIRECT LEAF IMPORTS, not `graphpack/index.js`. The barrel re-exports
+// `build.ts`/`read.ts` (pulling `@canonical/ke` and `@canonical/ke-graphql`)
+// and `embedded.ts`, whose generated payload is ~1.9 MB. `sources status`
+// reads two manifests and prints them; routing that through the barrel
+// would make a status-only command initialise the whole pack stack.
 import { embeddedManifest } from "../../kernel/runtime/graphpack/embedded.js";
 import { readManifest } from "../../kernel/runtime/graphpack/manifest.js";
 import { INDEX_FILE } from "../../kernel/runtime/graphpack/types.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { resolveSources } from "../../kernel/runtime/resolveSources.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import type { SourcesStatusData } from "./types.js";
 
 const entryName = (entry: PackDeclaration): string =>

package/src/capabilities/sources/index.ts

@@ -4,7 +4,7 @@
  */
 
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { statusVerb } from "./status.verb.js";
 import { updateVerb } from "./update.verb.js";
 

package/src/capabilities/sources/installSkills.ts

@@ -10,27 +10,51 @@
  * first), and the update Task stays reversible (each created link carries an
  * unlink undo).
  *
+ * Installing alone leaks, because planning walks the PACKAGES and so only ever
+ * visits a skill that still exists. When a package DROPS one (a `0.1.2` that
+ * shipped `component-specifier` upgrading to a `0.2.0` that does not), the link
+ * the previous update installed is never revisited and is left dangling at a
+ * target that no longer exists — which reads as a broken install rather than the
+ * intentional removal it is, and which `skill` commands can still list or try to
+ * open. So planning ALSO walks the installed root and prunes those, under a
+ * deliberately narrow rule: an entry is removed only when this run did not plan
+ * it AND it is a symlink whose target is gone. A real directory is a
+ * manually-installed skill and a still-resolving symlink is someone's own link;
+ * neither is this update's to delete.
+ *
  * Decisions run against REAL fs here so the update's `--dry-run` plan is
  * accurate; the composed Task performs only the symlink/delete effects.
  */
 
 import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
-import type { ResolvedPackage } from "../../kernel/runtime/refs/resolve.js";
+import type { ResolvedPackage } from "../../kernel/runtime/refs/index.js";
 import { installedSkillsDir } from "../skill/discover.js";
 
 /** One planned skill symlink into the installed-skills root. */
 export interface SkillLinkAction {
-  /** The package's skill folder — the symlink target. */
+  /**
+   * The symlink target: the package's skill folder for an install, or — on a
+   * `pruned` entry — the missing target the stale link still points at, kept so
+   * the prune's undo can put the link back exactly as it was.
+   */
   readonly target: string;
   /** `<installedSkillsDir>/<folderName>` — where the symlink is created. */
   readonly linkPath: string;
-  /** created (absent), skipped (already correct / a real dir), or replaced. */
-  readonly action: "created" | "skipped" | "replaced";
+  /**
+   * created (absent), skipped (already correct / a real dir), replaced, or
+   * pruned (an unplanned link whose target is gone — deleted, not re-created).
+   */
+  readonly action: "created" | "skipped" | "replaced" | "pruned";
   /** The skill folder name (the discovery key). */
   readonly folderName: string;
-  /** The package the skill came from. */
-  readonly packageName: string;
+  /**
+   * The package the skill came from. Absent on a `pruned` entry: a stale link
+   * records only a target path, and the package that installed it is precisely
+   * the one that no longer provides the skill — there is nothing honest left to
+   * attribute it to.
+   */
+  readonly packageName?: string;
 }
 
 /** What currently occupies a candidate link path. */
@@ -80,9 +104,58 @@ function packageSkillDirs(root: string): string[] {
   return out;
 }
 
+/**
+ * Plan the removal of the links a package has since dropped.
+ *
+ * The install pass walks the packages, so it can only ever visit a skill that
+ * still exists; this pass walks the installed root, which is the ONLY place a
+ * dropped skill still shows up. An entry is pruned only when both hold: this run
+ * did not plan it, and it is a symlink whose target is gone. Both halves matter —
+ *
+ * - a real (non-symlink) entry is a manually-installed skill, which the install
+ *   pass already refuses to clobber (`skipped`) and which this pass must refuse
+ *   just as firmly: "unplanned" is exactly what a hand-placed skill looks like;
+ * - a symlink whose target still resolves is someone's own link into a checkout
+ *   this command knows nothing about. Unplanned does not make it garbage, and an
+ *   update that silently ate it would be a worse bug than the dangling link.
+ *
+ * A broken target, by contrast, cannot be anything but debris: nothing can read
+ * it, and re-creating it is a matter of re-running the update that installed it
+ * (which is also what this prune's undo does).
+ *
+ * @param dest - The installed-skills root.
+ * @param planned - Every folder name the install pass planned, whatever action.
+ * @returns One `pruned` action per stale link, for the plan and its preview.
+ * @note Impure — reads the installed root and stats each entry's target.
+ */
+function planStaleLinkPrunes(
+  dest: string,
+  planned: ReadonlySet<string>,
+): SkillLinkAction[] {
+  let names: string[];
+  try {
+    names = readdirSync(dest);
+  } catch {
+    return []; // No installed root — nothing was ever installed to go stale.
+  }
+  const out: SkillLinkAction[] = [];
+  for (const folderName of names) {
+    if (planned.has(folderName)) continue;
+    const linkPath = resolve(dest, folderName);
+    const state = linkState(linkPath);
+    if (state.kind !== "symlink") continue;
+    // A relative target is stored relative to the link's OWN directory, which
+    // for an entry of the installed root is that root itself.
+    if (existsSync(resolve(dest, state.target))) continue;
+    out.push({ target: state.target, linkPath, action: "pruned", folderName });
+  }
+  return out;
+}
+
 /**
  * Plan the symlink actions that install each resolved package's `skills/*` into
- * the installed-skills discovery root. First-seen wins on a folder-name clash
+ * the installed-skills discovery root, then the removals that retire the links
+ * a package has since dropped. First-seen wins on a folder-name clash
  * across packages. A real (non-symlink) entry at the link path is left untouched
  * (`skipped`) so a manually-installed skill is never clobbered.
  *
@@ -120,5 +193,9 @@ export function planSkillInstall(
       });
     }
   }
+  // `seen` is every folder name this run planned — the `skipped` ones included,
+  // so a name a package still provides is never a prune candidate even when the
+  // install pass decided to leave its entry alone.
+  actions.push(...planStaleLinkPrunes(dest, seen));
   return actions;
 }