@canonical/pragma-cli 0.35.0 → 0.37.0

package/src/capabilities/setup/setup.test.ts

@@ -26,9 +26,9 @@ import {
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { join, relative, sep } from "node:path";
 import { execute } from "@canonical/summon-core";
-import { dryRun, type Effect, type Task } from "@canonical/task";
+import { collectUndos, dryRun, type Effect, type Task } from "@canonical/task";
 import { runTask, runUndo } from "@canonical/task/node";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { BIN_NAME } from "../../constants.js";
@@ -42,13 +42,16 @@ import { projectCli } from "../../testing/helpers/projectCli.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
 import { capabilities } from "../index.js";
 import { detectCompletions } from "./operations/setupCompletions.js";
-import { buildSetupRun } from "./operations/setupGenerator.js";
+import { buildSetupRun, type RowEvent } from "./operations/setupGenerator.js";
 import {
   composeSkills,
   composeSkillsRemoval,
   detectSkills,
   ownedSkillLinks,
+  skillsSkipReason,
+  skillsSkipRemedy,
 } from "./operations/setupSkills.js";
+import { DRY_RUN_HINT, PREVIEW_HINT } from "./setup.render.js";
 import { setupModule } from "./setup.verb.js";
 import { completionScriptPath, detectShell, type ShellId } from "./shell.js";
 
@@ -98,6 +101,14 @@ const stubPath = (): string => {
   return dir;
 };
 
+/**
+ * The machine's real PATH, captured before the suite isolates it. A stub
+ * editor script that has to run a real utility (`rm`) restores this INSIDE
+ * itself — hardcoding `/bin:/usr/bin` breaks on hosts that keep coreutils
+ * elsewhere, and the isolated PATH the tests run under has no `rm`.
+ */
+const HOST_PATH = process.env.PATH ?? "";
+
 let prevHome: string | undefined;
 let prevPath: string | undefined;
 beforeEach(() => {
@@ -204,7 +215,7 @@ describe("setup completions", () => {
       // The dry-run renders the PLAN through the verb's formatPlan seam, not the
       // kernel's raw effect dump: one row, the shell it detected, and the script
       // path rendered against the header's roots instead of repeated absolutely.
-      expect(outcome.stdout).toContain("Setup plan — global band");
+      expect(outcome.stdout).toContain("Setup plan — global");
       expect(outcome.stdout).toMatch(
         new RegExp(`completions\\s+install\\s+${SHELL} →`),
       );
@@ -249,7 +260,7 @@ describe("setup mcp — recap gate", () => {
     mkdirSync(join(cwd, ".cursor"), { recursive: true }); // makes Cursor detected
     const configPath = join(cwd, ".cursor", "mcp.json");
 
-    // `--local`: the project band is opt-in now, so a bare `setup mcp` would
+    // `--local`: the project scope is opt-in now, so a bare `setup mcp` would
     // write the HOME config and leave this repository untouched.
     const outcome = await executeVerb(
       verbOf("mcp"),
@@ -405,7 +416,7 @@ describe("setup mcp — scope & dedup", () => {
     // A per-user server must not be pinned to whatever directory `setup mcp
     // --global` happened to run from (a registration made from ~/Downloads
     // used to serve ~/Downloads forever, and re-running from repo B flipped
-    // the machine band to repo B).
+    // the machine scope to repo B).
     const home = process.env.HOME ?? "";
     const configPath = join(home, ".codeium", "windsurf", "mcp_config.json");
     const register = async (cwd: string): Promise<string> => {
@@ -461,9 +472,9 @@ describe("setup mcp — scope & dedup", () => {
     expect(
       JSON.parse(readFileSync(configPath, "utf-8")).mcpServers.pragma,
     ).toEqual({ command: "pragma", args: ["mcp", "serve"] });
-    // ...and it stays `configured` afterwards (no churn on every run).
+    // ...and it stays `registered` afterwards (no churn on every run).
     const after = await detectMcp(bootRuntime(FLAGS, cwd), "global");
-    expect(mcpGroupState(after, configPath)).toBe("configured");
+    expect(mcpGroupState(after, configPath)).toBe("registered");
   });
 
   it("a PROJECT entry still records the project root as cwd", async () => {
@@ -482,25 +493,32 @@ describe("setup mcp — scope & dedup", () => {
   });
 });
 
-describe("setup mcp — customize opt-in gate (Item 6)", () => {
-  it("gates the per-file multiselect behind an explicit customize=true", async () => {
+describe("setup mcp — the per-file question, asked directly", () => {
+  it("asks the per-file multiselect with NO `customize` meta-question in front", async () => {
+    // `answers.customize` was read in exactly one place in the repo — this
+    // prompt's `when` — and by nothing else: not `generate`, not `applied`, not
+    // any plan, recap, renderer or JSON projection. Answering no just meant the
+    // child prompt went unasked, its key was absent, and the compose bodies
+    // read that as "all" — so everything detected was configured anyway.
     const cwd = tmp("pragma-setup-proj-");
-    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // ⇒ one MCP target group
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    mkdirSync(join(cwd, ".gemini"), { recursive: true }); // 2 children ⇒ narrowable
     const { generator } = await buildSetupRun(
       bootRuntime(FLAGS, cwd),
       "mcp",
-      "both",
+      "project",
     );
-    const customize = generator.prompts.find((p) => p.name === "customize");
+    expect(generator.prompts.map((p) => p.name)).not.toContain("customize");
     const targets = generator.prompts.find((p) => p.name === "mcpTargets");
-    // The gate is an opt-in confirm that defaults to NOT customizing.
-    expect(customize?.type).toBe("confirm");
-    expect(customize?.default).toBe(false);
-    // The per-file multiselect only surfaces after an explicit yes — so the
-    // "all" default configures every deduped file without an extra question.
-    expect(targets?.when?.({})).toBe(false);
-    expect(targets?.when?.({ customize: false })).toBe(false);
-    expect(targets?.when?.({ customize: true })).toBe(true);
+    expect(targets).toBeDefined();
+    // It is asked whenever its row is in the run — the row's own selection is
+    // the only gate, and the choices carry the detected state per file.
+    expect(targets?.when?.({})).toBe(true);
+    expect(
+      (targets?.choices as { label: string }[]).every((c) =>
+        /— (add|update|unchanged)$/.test(c.label),
+      ),
+    ).toBe(true);
   });
 
   it("recaps the files the run KEPT, not the ones it offered", async () => {
@@ -517,7 +535,6 @@ describe("setup mcp — customize opt-in gate (Item 6)", () => {
 
     const applied = run.applied({
       targets: ["project:mcp"],
-      customize: true,
       mcpTargets: [kept],
     });
     expect(applied.rows.find((r) => r.target === "mcp")?.outcome?.note).toBe(
@@ -526,6 +543,67 @@ describe("setup mcp — customize opt-in gate (Item 6)", () => {
   });
 });
 
+describe("setup — live row events (the wizard's step feed)", () => {
+  it("brackets each row with start/done, in the recap's own sentence", async () => {
+    // The wizard's live progress renders the PLAN's rows, not the effect
+    // transcript — one `start` as a row's body is entered, one `done` carrying
+    // the same `target  detail — note` sentence the recap will print, so the
+    // watcher and the recap reader see one dialect.
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    const run = await buildSetupRun(bootRuntime(FLAGS, cwd), "mcp", "project");
+    const events: RowEvent[] = [];
+    run.setRowListener((event) => events.push(event));
+    await runTask(run.generator.generate({}), { onLog: () => {} });
+    expect(events.map((event) => event.status)).toEqual(["start", "done"]);
+    expect(events[0]?.key).toBe("project:mcp");
+    // The start label is the row without an outcome; the done label appends
+    // the SAME note `applied()` puts on the recap row.
+    const applied = run.applied({});
+    const note = applied.rows.find((r) => r.target === "mcp")?.outcome?.note;
+    expect(note).toBe("1 added");
+    expect(events[1]?.label).toBe(`${events[0]?.label} — ${note}`);
+  });
+
+  it("no listener registered costs nothing — the run is unchanged", async () => {
+    // `--yes`, `--dry-run` and MCP never register one; the bracket emits into
+    // the void and the composed effects are identical.
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    const run = await buildSetupRun(bootRuntime(FLAGS, cwd), "mcp", "project");
+    await runTask(run.generator.generate({}), { onLog: () => {} });
+    expect(existsSync(join(cwd, ".cursor", "mcp.json"))).toBe(true);
+  });
+
+  it("a failing row reports `failed` with its cause, and its siblings still bracket", async () => {
+    // Same arrangement as the S1-1 isolation test: an editor on PATH with no
+    // `bun`, so the LSP row's compose fails. The event stream must name the
+    // failure — the wizard paints that row ✗ live — while the run continues.
+    const prevPath = process.env.PATH;
+    const prevData = process.env.XDG_DATA_HOME;
+    process.env.XDG_DATA_HOME = tmp("pragma-rowevents-data-");
+    const dir = stubPath();
+    writeFileSync(join(dir, "code"), "");
+    process.env.PATH = dir;
+    try {
+      const run = await buildSetupRun(
+        bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+        "lsp",
+        "global",
+      );
+      const events: RowEvent[] = [];
+      run.setRowListener((event) => events.push(event));
+      await runTask(run.generator.generate({}), { onLog: () => {} });
+      expect(events.map((event) => event.status)).toEqual(["start", "failed"]);
+      expect(events[1]?.label).toContain("bun");
+    } finally {
+      process.env.PATH = prevPath;
+      if (prevData === undefined) delete process.env.XDG_DATA_HOME;
+      else process.env.XDG_DATA_HOME = prevData;
+    }
+  });
+});
+
 describe("setup lsp — per-editor multiselect (child rows)", () => {
   let prevPath: string | undefined;
   let stubDir = "";
@@ -573,20 +651,18 @@ describe("setup lsp — per-editor multiselect (child rows)", () => {
     expect(children?.find((c) => c.key === "codium")?.action).toBe("add");
   });
 
-  it("gates the per-editor multiselect behind the same customize confirm", async () => {
+  it("asks the per-editor multiselect directly, with both forks pre-selected", async () => {
     const { generator } = await buildSetupRun(
       bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
       "lsp",
       "global",
     );
-    const customize = generator.prompts.find((p) => p.name === "customize");
+    expect(generator.prompts.map((p) => p.name)).not.toContain("customize");
     const editors = generator.prompts.find((p) => p.name === "lspEditors");
-    expect(customize?.default).toBe(false);
-    // Both pending editors are pre-selected, so the default path installs into
-    // every fork without an extra question.
+    // Both pending editors are pre-selected, so pressing enter installs into
+    // every fork — the same default the meta-question used to stand for.
     expect(editors?.default).toEqual(["code", "codium"]);
-    expect(editors?.when?.({ customize: false })).toBe(false);
-    expect(editors?.when?.({ customize: true })).toBe(true);
+    expect(editors?.when?.({})).toBe(true);
   });
 
   it("sideloads only into the editors the user kept", async () => {
@@ -608,6 +684,405 @@ describe("setup lsp — per-editor multiselect (child rows)", () => {
     const { effects } = dryRun(composeLsp(detected, []));
     expect(effects.some((e) => e._tag === "Exec")).toBe(false);
   });
+
+  it("the removal is `none` when no editor carries the extension", async () => {
+    // Both forks are on PATH, neither has a copy — there is nothing this
+    // command owns, so a removal has honestly nothing to do.
+    const { detectLsp, composeLspRemoval, ownedLspEditors } = await import(
+      "./operations/setupLsp.js"
+    );
+    const detected = await detectLsp(tmp("pragma-setup-proj-"));
+    expect(ownedLspEditors(detected)).toEqual([]);
+    expect(collectUndos(composeLspRemoval(detected))).toEqual([]);
+
+    const { plan } = await buildSetupRun(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "lsp",
+      "global",
+      true,
+    );
+    const row = plan.rows.find((r) => r.target === "lsp");
+    expect(row?.action).toBe("none");
+    expect(row?.detail).toBe("no editor carries the extension");
+  });
+});
+
+describe("setup lsp — the removal contract the other four rows implement", () => {
+  let prevPath: string | undefined;
+  let stubDir = "";
+  beforeEach(() => {
+    prevPath = process.env.PATH;
+    stubDir = stubPath();
+    writeFileSync(join(stubDir, "code"), "");
+    writeFileSync(join(stubDir, "codium"), "");
+    process.env.PATH = stubDir;
+  });
+  afterEach(() => {
+    process.env.PATH = prevPath;
+  });
+
+  /** Seed a versioned extension copy in an editor's extensions dir. */
+  const seedExtension = (dir: string, version: string): void => {
+    mkdirSync(
+      join(
+        process.env.HOME ?? "",
+        dir,
+        "extensions",
+        `canonical.terrazzo-lsp-extension-${version}`,
+      ),
+      { recursive: true },
+    );
+  };
+
+  it("carries one `--uninstall-extension` exec per OWNED editor as its undo", async () => {
+    // The row hardcoded a skip behind a docblock claiming "an `exec` carries no
+    // reversal" — factually wrong: `Exec` has an `undo` slot, and the sibling
+    // `composeMcpRemoval` already uses this exact carrier shape.
+    seedExtension(".vscode", "1.2.3");
+    const { detectLsp, composeLspRemoval } = await import(
+      "./operations/setupLsp.js"
+    );
+    const detected = await detectLsp(tmp("pragma-setup-proj-"));
+
+    // The FORWARD side must be walkable with every effect mocked: it is a
+    // `mkdir` of the editor's own extensions dir, which reads nothing.
+    const forward = dryRun(composeLspRemoval(detected));
+    expect(forward.effects.map((e) => e._tag)).toEqual(["MakeDir"]);
+    expect(forward.effects.some((e) => e._tag === "Exec")).toBe(false);
+
+    const undos = collectUndos(composeLspRemoval(detected));
+    expect(undos).toHaveLength(1);
+    const execs = undos
+      .flatMap((u) => dryRun(u).effects)
+      .filter((e) => e._tag === "Exec") as (Effect & {
+      _tag: "Exec";
+      command: string;
+      args: string[];
+    })[];
+    expect(execs.map((e) => e.command)).toEqual(["code"]);
+    expect(execs[0].args).toEqual([
+      "--uninstall-extension",
+      "canonical.terrazzo-lsp-extension",
+    ]);
+  });
+
+  it("REGRESSION: a pre-0.8.3 copy still plans `install` forward but `remove` back", async () => {
+    // The conflation that would have caused a silent wrong-skip.
+    // `extensionInstalled` was version-gated, so an editor carrying a dead
+    // pre-0.8.3 copy — one this command itself installed — reported
+    // `installed: false`, and a removal keyed on it would have walked past the
+    // dead extension while reporting success.
+    seedExtension(".vscode", "0.8.1");
+    const { detectLsp, composeLspRemoval, ownedLspEditors } = await import(
+      "./operations/setupLsp.js"
+    );
+    const detected = await detectLsp(tmp("pragma-setup-proj-"));
+    const code = detected.editors.find((e) => e.editor.cli === "code");
+    // Present, but not current — the two facts stay separate.
+    expect(code?.present).toBe(true);
+    expect(code?.installed).toBe(false);
+
+    // Forward is UNCHANGED by this fix: the dead copy is still "not installed".
+    const forward = await buildSetupRun(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "lsp",
+      "global",
+    );
+    expect(forward.plan.rows.find((r) => r.target === "lsp")?.action).toBe(
+      "install",
+    );
+
+    // Removal keys on ownership, so the dead copy IS removed.
+    expect(ownedLspEditors(detected).map((e) => e.editor.cli)).toEqual([
+      "code",
+    ]);
+    const { plan } = await buildSetupRun(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "lsp",
+      "global",
+      true,
+    );
+    const row = plan.rows.find((r) => r.target === "lsp");
+    expect(row?.action).toBe("remove");
+    expect(row?.children?.map((c) => c.key)).toEqual(["code"]);
+    expect(
+      collectUndos(composeLspRemoval(detected))
+        .flatMap((u) => dryRun(u).effects)
+        .filter((e) => e._tag === "Exec"),
+    ).toHaveLength(1);
+  });
+
+  it("the remedy names an OWNING editor, not the first one on PATH", async () => {
+    // With Cursor (or here: `code`) installed and the extension only in
+    // VSCodium, the printed remedy named the wrong editor — a command that
+    // would report success having uninstalled nothing.
+    seedExtension(".vscode-oss", "1.2.3"); // codium's extensions dir
+    const { detectLsp, lspUninstallRemedy } = await import(
+      "./operations/setupLsp.js"
+    );
+    const detected = await detectLsp(tmp("pragma-setup-proj-"));
+    expect(detected.editors[0]?.editor.cli).toBe("code"); // first on PATH
+    expect(lspUninstallRemedy(detected)).toBe(
+      "codium --uninstall-extension canonical.terrazzo-lsp-extension",
+    );
+  });
+
+  it("still SKIPS with the named reason when no editor CLI is on PATH", async () => {
+    process.env.PATH = stubPath(); // no editor CLI at all
+    const { plan } = await buildSetupRun(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "lsp",
+      "global",
+      true,
+    );
+    const row = plan.rows.find((r) => r.target === "lsp");
+    expect(row?.action).toBe("skip");
+    expect(row?.reason).toContain("no VS Code-family editor CLI on PATH");
+  });
+
+  it("end to end: `setup lsp --undo` reports `Undid 1 step(s)` against a STUB cli", async () => {
+    // The reported symptom was `Undid 0 step(s).` at exit 0. The stub is a
+    // marker-writing script — never a real editor: an undo test must not be
+    // able to mutate the machine running it. It DOES delete the seeded
+    // extension entry (inside this test's temp HOME), because the removal now
+    // asserts its own goal against the extensions directory: a stub that
+    // exits 0 leaving the entry behind is the LYING-editor case, pinned as a
+    // failure below.
+    const marker = join(tmp("pragma-lsp-undo-"), "uninstalled");
+    const dir = stubPath();
+    writeFileSync(
+      join(dir, "code"),
+      `#!/bin/sh\nprintf '%s\\n' "$@" > ${marker}\nPATH='${HOST_PATH}' rm -rf "$HOME/.vscode/extensions/canonical.terrazzo-lsp-extension-"*\n`,
+      { mode: 0o755 },
+    );
+    process.env.PATH = dir;
+    seedExtension(".vscode", "1.2.3");
+
+    const outcome = await executeVerb(
+      verbOf("lsp"),
+      {},
+      UNDO,
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toBe("Undid 1 step(s).\n");
+    expect(readFileSync(marker, "utf-8")).toBe(
+      "--uninstall-extension\ncanonical.terrazzo-lsp-extension\n",
+    );
+    // NON-GOAL guard: the staging dir is a cache, not this removal's business.
+    // Nothing here deletes it, and nothing here touches the VSIX.
+    const { detectLsp, composeLspRemoval } = await import(
+      "./operations/setupLsp.js"
+    );
+    const detected = await detectLsp(tmp("pragma-setup-proj-"));
+    const all = [
+      ...dryRun(composeLspRemoval(detected)).effects,
+      ...collectUndos(composeLspRemoval(detected)).flatMap(
+        (u) => dryRun(u).effects,
+      ),
+    ];
+    expect(all.some((e) => e._tag === "DeleteFile")).toBe(false);
+    expect(all.some((e) => e._tag === "DeleteDirectory")).toBe(false);
+  });
+
+  /** Drive `setup lsp --undo` capturing stderr (where the row lines land). */
+  const undoLspCapturing = async (): Promise<{
+    chunks: string[];
+    outcome?: { stdout?: string; stderr?: string; exitCode: number };
+    thrown?: unknown;
+  }> => {
+    const chunks: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: unknown): boolean => {
+        chunks.push(String(chunk));
+        return true;
+      });
+    try {
+      const outcome = await executeVerb(
+        verbOf("lsp"),
+        {},
+        UNDO,
+        bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      );
+      return { chunks, outcome };
+    } catch (thrown) {
+      return { chunks, thrown };
+    } finally {
+      spy.mockRestore();
+    }
+  };
+
+  it("HEADLINE: an uninstall that exits 0 leaving the extension on disk reports FAILED, never `✓ removed`", async () => {
+    // The observed field defect: VS Code-family CLIs can exit 0 while
+    // deferring or skipping the deletion. The reversal's success criterion
+    // was that exit code; detection's criterion is the extensions DIRECTORY.
+    // The two disagreed permanently and the run printed `✓ … removed` over an
+    // extension that was still installed. The removal now asserts its own
+    // goal in-task — probe the owned entries after the uninstall — and the
+    // run reports the survival as a failure with a manual remedy.
+    const dir = stubPath();
+    writeFileSync(join(dir, "code"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    process.env.PATH = dir;
+    seedExtension(".vscode", "1.2.3");
+    const survivor = join(
+      process.env.HOME ?? "",
+      ".vscode",
+      "extensions",
+      "canonical.terrazzo-lsp-extension-1.2.3",
+    );
+
+    const { chunks, outcome, thrown } = await undoLspCapturing();
+    const stderrText = chunks.join("");
+
+    // The world: the artifact survived, and the run must not claim otherwise.
+    expect(existsSync(survivor)).toBe(true);
+    expect(stderrText).not.toContain("— removed");
+    expect(outcome).toBeUndefined();
+    expect(thrown).toBeDefined();
+    const err = asPragmaError(thrown);
+    expect(err.code).toBe("UNSUPPORTED");
+    expect(err.message).toContain("lsp");
+    expect(err.message).toContain("still present after the undo ran");
+    // The remedy names the surviving path as DATA for a manual deletion —
+    // not the CLI command that has just demonstrably done nothing while
+    // reporting success, and not a synthesized shell line (the entry names
+    // come off the filesystem, so no quoting is trustworthy, and one command
+    // cannot be right for every supported platform).
+    expect(err.recovery?.message ?? "").toContain(survivor);
+    expect(err.recovery?.message ?? "").not.toContain("rm -rf");
+    expect(err.recovery?.message ?? "").not.toContain("--uninstall-extension");
+    // The truthful row is reported (stderr), naming the survival.
+    expect(stderrText).toContain("still present after the undo ran");
+  });
+
+  it("a DANGLING matching symlink still counts as a survivor — the probe uses detection's criterion", async () => {
+    // Detection calls an entry present when `readdirSync` lists it. A probe
+    // built on default `exists` (`fs.access`) FOLLOWS symlinks, so a dangling
+    // matching symlink would be "installed" to detection and "absent" to the
+    // probe: an editor that exits 0 without removing it would report
+    // `undone`, and the next detection would find it again — the exact
+    // "reports success it did not achieve" this fix exists to close, rebuilt
+    // inside the fix. The probe therefore asks about the entry itself
+    // (lstat semantics), the same question the directory listing answers.
+    const dir = stubPath();
+    writeFileSync(join(dir, "code"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    process.env.PATH = dir;
+    const extensionsDir = join(process.env.HOME ?? "", ".vscode", "extensions");
+    mkdirSync(extensionsDir, { recursive: true });
+    const entry = join(extensionsDir, "canonical.terrazzo-lsp-extension-1.2.3");
+    symlinkSync(join(extensionsDir, "no-such-target"), entry);
+
+    const { chunks, outcome, thrown } = await undoLspCapturing();
+
+    expect(lstatSync(entry).isSymbolicLink()).toBe(true); // still there
+    expect(chunks.join("")).not.toContain("— removed");
+    expect(outcome).toBeUndefined();
+    const err = asPragmaError(thrown);
+    expect(err.message).toContain("still present after the undo ran");
+    expect(err.recovery?.message ?? "").toContain(entry);
+  });
+
+  it("a truthful uninstall reports its `removed` row from the executed reversal", async () => {
+    // The positive half of the headline: when the editor really deletes the
+    // entry, the in-task postcondition passes, the reversal's outcome comes
+    // back `undone`, and the row reports `removed` — same sentence as before
+    // the fix, now derived from what ran instead of from the plan.
+    const dir = stubPath();
+    writeFileSync(
+      join(dir, "code"),
+      `#!/bin/sh\nPATH='${HOST_PATH}' rm -rf "$HOME/.vscode/extensions/canonical.terrazzo-lsp-extension-"*\n`,
+      { mode: 0o755 },
+    );
+    process.env.PATH = dir;
+    seedExtension(".vscode", "1.2.3");
+
+    const { chunks, outcome, thrown } = await undoLspCapturing();
+    expect(thrown).toBeUndefined();
+    expect(outcome?.exitCode).toBe(0);
+    expect(outcome?.stdout).toBe("Undid 1 step(s).\n");
+    expect(chunks.join("")).toContain("— removed");
+  });
+
+  it("the `✓ … removed` rows cannot be produced by the collection walk alone", async () => {
+    // The collection walk mocks every exec to exit 0 and every prompt to its
+    // default — under the old code that was enough to print the whole green
+    // recap before one real process had spawned. With an uninstall that
+    // GENUINELY fails (exit 1), the executed reversal fails; if any `removed`
+    // row still appeared on stderr, it could only have come from the mocked
+    // walk.
+    const dir = stubPath();
+    writeFileSync(join(dir, "code"), "#!/bin/sh\nexit 1\n", { mode: 0o755 });
+    process.env.PATH = dir;
+    seedExtension(".vscode", "1.2.3");
+
+    const { chunks, outcome, thrown } = await undoLspCapturing();
+    expect(chunks.join("")).not.toContain("— removed");
+    expect(outcome).toBeUndefined();
+    expect(thrown).toBeDefined();
+    const err = asPragmaError(thrown);
+    expect(err.message).toContain("--uninstall-extension");
+    expect(err.message).toContain("exited with code 1");
+  });
+
+  it("appliedUndo grades rows from the outcomes — one model, both directions", async () => {
+    // The projection unit: the sink the FORWARD run fills is fed by the undo
+    // interpreter's outcomes instead, and the same `outcomeFor` reads it
+    // back. A failed outcome keyed to the row fails the row (carrying the
+    // reversal's own remedy); an actionable row that no reversal reported
+    // back for cannot claim `removed`; a run with clean outcomes reports
+    // `removed`.
+    seedExtension(".vscode", "1.2.3");
+    const run = await buildSetupRun(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "lsp",
+      "global",
+      true,
+    );
+
+    const clean = run.appliedUndo([{ key: "global:lsp", status: "undone" }]);
+    expect(clean.rows.find((r) => r.target === "lsp")?.outcome).toMatchObject({
+      status: "removed",
+      note: "removed",
+    });
+
+    const failed = run.appliedUndo([
+      {
+        key: "global:lsp",
+        status: "failed",
+        error: { code: "UNSUPPORTED", message: "still there" },
+      },
+    ]);
+    expect(failed.rows.find((r) => r.target === "lsp")?.outcome).toMatchObject({
+      status: "failed",
+      note: "still there",
+    });
+
+    // No reversal reported back at all for an actionable row: never `removed`.
+    const silent = run.appliedUndo([]);
+    expect(silent.rows.find((r) => r.target === "lsp")?.outcome).toMatchObject({
+      status: "failed",
+      note: "no reversal was executed for this target",
+    });
+  });
+
+  it("a removal row with nothing owned reports `kept`, not a green noop", async () => {
+    // The `kept` status was declared in the vocabulary and counted by
+    // `planTally` but no producer ever emitted it. On a removal, a `none`
+    // row IS the kept case: the run owned nothing here and deliberately left
+    // the machine's state standing — standing aside (○), not work done (✓).
+    const run = await buildSetupRun(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "lsp",
+      "global",
+      true,
+    );
+    expect(run.plan.rows.find((r) => r.target === "lsp")?.action).toBe("none");
+    const kept = run.appliedUndo([]);
+    expect(kept.rows.find((r) => r.target === "lsp")?.outcome).toEqual({
+      status: "kept",
+    });
+  });
 });
 
 describe("setup (run-all wizard) — scope threading", () => {
@@ -630,7 +1105,7 @@ describe("setup (run-all wizard) — scope threading", () => {
     writeFileSync(join(editorPath, "code"), "");
   };
 
-  /** Seed a discoverable skill so the project-band skills step is offerable. */
+  /** Seed a discoverable skill so the project-scope skills step is offerable. */
   const seedSkill = (cwd: string): void => {
     const dir = join(cwd, ".pragma", "skills", "s");
     mkdirSync(dir, { recursive: true });
@@ -640,10 +1115,10 @@ describe("setup (run-all wizard) — scope threading", () => {
     );
   };
 
-  it("--local omits the global-band completions + lsp steps, keeping project steps", async () => {
+  it("--local omits the global-scope completions + lsp steps, keeping project steps", async () => {
     const cwd = tmp("pragma-setup-proj-");
-    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // project-band MCP target
-    seedSkill(cwd); // project-band skills step
+    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // project-scope MCP target
+    seedSkill(cwd); // project-scope skills step
     const outcome = await executeVerb(
       setupSelfVerb,
       { local: true },
@@ -652,17 +1127,19 @@ describe("setup (run-all wizard) — scope threading", () => {
     );
     expect(outcome.exitCode).toBe(0);
     const plan = outcome.stdout ?? "";
-    // A band FILTERS the run-all: the out-of-band targets are still named, as
-    // rows saying why they are not in this run, so nothing is silently absent.
-    expect(plan).toContain("completions  skip");
-    expect(plan).toContain("user-level only — it has no project band");
-    // The project-band steps remain: MCP into .cursor, skills into .agents/skills.
+    // A scope FILTERS the run-all: the out-of-scope targets are still named, as
+    // rows saying why they are not in this run, so nothing is silently absent —
+    // and the reason names the flag that WOULD reach them, so the row is not a
+    // dead end either.
+    expect(plan).toContain("completions  nothing to do");
+    expect(plan).toContain("this one is global only — run it with `--global`");
+    // The per-project steps remain: MCP into .cursor, skills into .agents/skills.
     expect(plan).toContain("mcp.json");
     expect(plan).toContain(".agents/skills");
   });
 
   withShell(
-    "--global omits the project-band skills step, keeping global steps",
+    "--global omits the project-scope skills step, keeping global steps",
     async () => {
       const cwd = tmp("pragma-setup-proj-");
       seedSkill(cwd); // WOULD be offered under the default `both`
@@ -675,13 +1152,20 @@ describe("setup (run-all wizard) — scope threading", () => {
       );
       expect(outcome.exitCode).toBe(0);
       const plan = outcome.stdout ?? "";
-      // The global-band steps are present under --global. Paths render against
+      // The global-scope steps are present under --global. Paths render against
       // the header's roots, so the row shows `~/.zfunc/_pragma`, not an absolute
       // prefix repeated on every line.
       expect(plan).toMatch(new RegExp(`completions\\s+install\\s+${SHELL} →`));
       expect(plan).toContain("lsp");
-      // The project-band skills step is gone (the bug: it used to run under --global).
-      expect(plan).not.toContain(".agents/skills");
+      // The project-scope skills step is gone (the bug: it used to run under
+      // --global). `shortenPath` renders a project path as `./…` and a global
+      // one as `~/…`, and the two scopes' cross-client directories differ only
+      // by that marker — so the covenant is asserted on the PROJECT spelling.
+      // A bare "not .agents/skills" no longer separates them: the global scope
+      // legitimately links its own `~/.agents/skills` now that the bundled
+      // snapshot gives it skills on a machine that has run nothing.
+      expect(plan).not.toContain(`.${sep}.agents${sep}skills`);
+      expect(plan).toContain(`~${sep}.agents${sep}skills`);
     },
   );
 });
@@ -701,7 +1185,101 @@ describe("setup skills", () => {
     );
     expect(outcome.exitCode).toBe(0);
     expect(outcome.stdout).toContain("skills");
-    expect(outcome.stdout).toContain("no project skills");
+    expect(outcome.stdout).toContain("this project holds no skills");
+    // The skip is no longer a dead end: it names the action that settles it on
+    // THIS machine. The reason does NOT invert — the row still skips.
+    expect(outcome.stdout).toContain("SKILL.md, then run this again");
+  });
+
+  it("an EXISTING but empty project skills root is not reported as absent", async () => {
+    // `available` is false for an absent root and for an empty one alike, so
+    // the shared reason line said "is absent" about a directory the user is
+    // looking at. `rootExists` is the flag that already separates those two
+    // states everywhere else in the module; the wording now honours it.
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".pragma", "skills"), { recursive: true });
+
+    const { plan } = await buildSetupRun(
+      bootRuntime(FLAGS, cwd),
+      "skills",
+      "project",
+    );
+    const row = plan.rows.find((r) => r.target === "skills");
+    expect(row?.action).toBe("skip"); // still nothing to do...
+    expect(row?.reason).toContain("is empty"); // ...for the honest reason
+    expect(row?.reason).not.toContain("does not exist");
+  });
+
+  it("a genuinely MISSING project skills root still reports absent", async () => {
+    // The other half of the distinction: the empty-root wording must not have
+    // been bought by making every skip vague.
+    const { plan } = await buildSetupRun(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "skills",
+      "project",
+    );
+    const row = plan.rows.find((r) => r.target === "skills");
+    expect(row?.action).toBe("skip");
+    expect(row?.reason).toContain("does not exist");
+  });
+
+  it("the GLOBAL scope OFFERS skills on a machine that has run nothing", async () => {
+    // THE BEHAVIOUR CHANGE, asserted at the scope that used to be empty. The
+    // global scope's only source was the installed root, so an empty
+    // `XDG_DATA_HOME` — a fresh install — planned `skip` and told the user to
+    // go and run `sources update` first. The bundled snapshot is the scope's
+    // second root, so the row is actionable with no network and no prior
+    // command. The empty-root WORDING this replaces is still asserted, on the
+    // pure reason/remedy pair, in the cell below.
+    const prevData = process.env.XDG_DATA_HOME;
+    process.env.XDG_DATA_HOME = tmp("pragma-skills-data-");
+    try {
+      const { plan } = await buildSetupRun(
+        bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+        "skills",
+        "global",
+      );
+      const row = plan.rows.find((r) => r.target === "skills");
+      expect(row?.action).toBe("link");
+      expect(row?.detail).toMatch(/\d+ skills? →/);
+
+      // End to end, inside the same jail (an ambient data root that happened to
+      // hold a skill would stop this exercising the fresh-machine condition).
+      const outcome = await executeVerb(
+        verbOf("skills"),
+        {},
+        YES,
+        bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      );
+      expect(outcome.exitCode).toBe(0);
+      expect(outcome.stdout).not.toContain("no skills installed");
+    } finally {
+      // `process.env.X = undefined` STORES THE STRING "undefined"; it does not
+      // unset. The variable is always set here (`setupXdgIsolation.ts` gives
+      // every test file its own XDG root), so this restores rather than
+      // deletes in practice — but a test must not leave a poisoned path behind
+      // for the files that run after it if that ever stops being true.
+      if (prevData === undefined) delete process.env.XDG_DATA_HOME;
+      else process.env.XDG_DATA_HOME = prevData;
+    }
+  });
+
+  it("the GLOBAL skip still names `sources update` when it does happen", async () => {
+    // The remedy the cell above used to assert end-to-end. That state is no
+    // longer reachable with a snapshot in the package — it takes a build whose
+    // `bundled-skills/` is missing AND an empty installed root — so it is
+    // asserted where it actually lives: on the pure pair that both the setup row
+    // and the doctor row read, which is what stops the two surfaces wording one
+    // finding differently. A skip with no next step is the defect.
+    expect(
+      skillsSkipReason("~/.local/share/pragma/skills", "global", true),
+    ).toBe(
+      "nothing to link — no skills installed yet; they arrive with the packs " +
+        `\`${BIN_NAME} sources update\` builds`,
+    );
+    expect(
+      skillsSkipRemedy("~/.local/share/pragma/skills", "global"),
+    ).toContain(`${BIN_NAME} sources update`);
   });
 
   it("detects a created action and composes a symlink carrying an undo", async () => {
@@ -727,6 +1305,77 @@ describe("setup skills", () => {
     expect(existsSync(join(cwd, ".agents", "skills", "my-skill"))).toBe(false);
   });
 
+  it("NEVER deletes a user's own symlink that collides with a shipped skill (REGRESSION)", async () => {
+    // Bundled skills ship on every install, so a folder-name collision with a
+    // user's own link is reachable with NO user action — where previously an
+    // empty skill set meant no action was ever composed for that path.
+    // `composeSkills` composes every non-skipped row, so classifying a
+    // resolving foreign link as `replaced` deletes the user's link.
+    const cwd = tmp("pragma-setup-proj-");
+    const skillDir = join(cwd, ".pragma", "skills", "my-skill");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(skillDir, "SKILL.md"),
+      "---\nname: my-skill\ndescription: A test skill.\n---\n",
+    );
+
+    // Somewhere entirely outside every pragma root, and it RESOLVES.
+    const mine = join(cwd, "my-own-work", "my-skill");
+    mkdirSync(mine, { recursive: true });
+    writeFileSync(join(mine, "SKILL.md"), "---\nname: mine\n---\n");
+
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    const linkPath = join(linkDir, "my-skill");
+    symlinkSync(mine, linkPath);
+
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd), "project");
+    const action = detected.actions.find((a) => a.linkPath === linkPath);
+    expect(action?.action).toBe("skipped");
+    expect(action?.owned).toBe(false);
+
+    // Neither the preview nor the real run may touch it.
+    const { effects } = dryRun(composeSkills(detected));
+    expect(
+      effects.filter(
+        (e) =>
+          e._tag === "DeleteFile" && (e as { path?: string }).path === linkPath,
+      ),
+    ).toHaveLength(0);
+
+    await runTask(composeSkills(detected));
+    expect(readlinkSync(linkPath)).toBe(mine);
+    expect(existsSync(join(linkPath, "SKILL.md"))).toBe(true);
+  });
+
+  it("sweeps a link into a REMOVED package directory once its skill is gone (REGRESSION)", async () => {
+    // The upgrade shape under a version-stamped layout (pnpm, npx, volta): the
+    // link points into `…@0.34.0/bundled-skills/<name>`, a directory the
+    // upgrade replaced. Ownership by residence in a CURRENT root cannot see it,
+    // and once the release drops that skill no per-skill action covers the path
+    // either — so the dangling link would survive every reconcile, invisible to
+    // setup and to doctor alike.
+    const cwd = tmp("pragma-setup-proj-");
+    const skillDir = join(cwd, ".pragma", "skills", "still-here");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(skillDir, "SKILL.md"),
+      "---\nname: still-here\ndescription: A test skill.\n---\n",
+    );
+
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    // Never created: this is the point — the old package directory is gone.
+    const retired = join(cwd, "pragma-cli@0.34.0", "bundled-skills", "retired");
+    const linkPath = join(linkDir, "retired");
+    symlinkSync(retired, linkPath);
+
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd), "project");
+    const orphan = detected.orphans.find((o) => o.linkPath === linkPath);
+    expect(orphan).toBeDefined();
+    expect(orphan?.owned).toBe(true);
+  });
+
   it("classifies a DANGLING symlink as replaced and repairs it (S1-2)", async () => {
     // `existsSync` FOLLOWS a symlink, so a dangling link used to read as
     // "absent" → plan `created` → the real symlink() crashed EEXIST labeled
@@ -858,6 +1507,40 @@ describe("setup skills", () => {
     expect(() => lstatSync(linkPath)).toThrow();
   });
 
+  it("the removal plan's children are the FOLDERS the links live in, deduped", async () => {
+    // `dirs` mapped `a.linkPath` — one path per LINK — so the `new Set(…)`
+    // deduped nothing and the removal preview printed an N-path wall where
+    // the forward plan says `N skills → M folders`. The folders are the
+    // links' parent directories.
+    const cwd = tmp("pragma-setup-proj-");
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    for (const name of ["s1", "s2"]) {
+      const skillDir = join(cwd, ".pragma", "skills", name);
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(
+        join(skillDir, "SKILL.md"),
+        `---\nname: ${name}\ndescription: A test skill.\n---\n`,
+      );
+      symlinkSync(skillDir, join(linkDir, name));
+    }
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd), "project");
+    expect(ownedSkillLinks(detected)).toHaveLength(2);
+
+    const { findTarget } = await import("./targets.js");
+    const draft = findTarget("skills")?.removalPlan(
+      detected as never,
+      "project",
+      { global: process.env.HOME ?? "", project: cwd },
+    );
+    expect(draft?.action).toBe("remove");
+    expect(draft?.detail).toBe("2 links");
+    // TWO links, ONE folder: the children name the folder once, not each link.
+    expect(draft?.children?.map((c) => c.label)).toEqual([
+      `.${sep}${join(".agents", "skills")}`,
+    ]);
+  });
+
   it("owns a RELATIVE link into the skill root, resolved against the link dir", async () => {
     // `readlink` reports the raw target, which may be relative — resolving it
     // against the link's own directory is what makes the containment test
@@ -877,17 +1560,168 @@ describe("setup skills", () => {
     const detected = await detectSkills(bootRuntime(FLAGS, cwd), "project");
     const action = detected.actions.find((a) => a.linkPath === linkPath);
     expect(action?.owned).toBe(true);
+    // A relative link that RESOLVES to the skill is already correct. Comparing
+    // the raw `readlink` string to an absolute path classified it `replaced`,
+    // so it churned on every run and doctor called it "points elsewhere".
+    expect(action?.action).toBe("skipped");
+    expect(dryRun(composeSkills(detected)).effects).toEqual([]);
 
     await runUndo(composeSkillsRemoval(detected));
     expect(existsSync(linkPath)).toBe(false);
   });
 });
 
+describe("setup skills — the forward pass is a RECONCILE", () => {
+  /** Seed one project skill and return its source dir. */
+  const seed = (cwd: string, name: string): string => {
+    const dir = join(cwd, ".pragma", "skills", name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "SKILL.md"),
+      `---\nname: ${name}\ndescription: A skill.\n---\n`,
+    );
+    return dir;
+  };
+
+  it("removes the link a dropped skill left behind, without --undo", async () => {
+    // The reported bug. `d.orphans` was computed and read ONLY by `--undo`,
+    // which removes every owned link rather than the stale ones — so no command
+    // reconciled, and a skill dropped upstream kept its link forever.
+    const cwd = tmp("pragma-setup-proj-");
+    const kept = seed(cwd, "kept");
+    const dropped = seed(cwd, "dropped");
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    symlinkSync(kept, join(linkDir, "kept"));
+    symlinkSync(dropped, join(linkDir, "dropped"));
+    rmSync(dropped, { recursive: true, force: true }); // retired upstream
+
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd), "project");
+    expect(detected.orphans.map((o) => o.skillName)).toEqual(["dropped"]);
+
+    await runTask(composeSkills(detected));
+    // `existsSync` FOLLOWS a link, so a dangling one false-negatives — lstat.
+    expect(() => lstatSync(join(linkDir, "dropped"))).toThrow();
+    expect(readlinkSync(join(linkDir, "kept"))).toBe(kept);
+  });
+
+  it("plans the sweep as an ACTIONABLE row, not a deselected `none`", async () => {
+    // An orphan-only tree planned `none` → `defaultSelected(none)` is false →
+    // the row was never composed, so even the fixed reconcile would not run.
+    const cwd = tmp("pragma-setup-proj-");
+    const dropped = seed(cwd, "dropped");
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    symlinkSync(dropped, join(linkDir, "dropped"));
+    rmSync(dropped, { recursive: true, force: true });
+
+    const { plan } = await buildSetupRun(
+      bootRuntime(FLAGS, cwd),
+      "skills",
+      "project",
+    );
+    const row = plan.rows.find((r) => r.target === "skills");
+    expect(row?.action).toBe("update");
+    expect(row?.selected).toBe(true);
+    expect(row?.detail).toContain("1 stale link to remove");
+  });
+
+  it("the sweep is reversible — undo puts the stale link back", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const dropped = seed(cwd, "dropped");
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    const linkPath = join(linkDir, "dropped");
+    symlinkSync(dropped, linkPath);
+    rmSync(dropped, { recursive: true, force: true });
+
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd), "project");
+    const { undoCount } = await runUndo(composeSkills(detected));
+    expect(undoCount).toBeGreaterThan(0);
+    expect(readlinkSync(linkPath)).toBe(dropped);
+  });
+
+  it("is idempotent — a second pass composes zero effects", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const dropped = seed(cwd, "dropped");
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    symlinkSync(dropped, join(linkDir, "dropped"));
+    rmSync(dropped, { recursive: true, force: true });
+
+    await runTask(
+      composeSkills(await detectSkills(bootRuntime(FLAGS, cwd), "project")),
+    );
+    const second = await detectSkills(bootRuntime(FLAGS, cwd), "project");
+    expect(dryRun(composeSkills(second)).effects).toEqual([]);
+  });
+
+  it("SAFETY: an ABSENT source root means no opinion — nothing is swept", async () => {
+    // `available` conflated "the root is empty" with "the root does not exist".
+    // Sweeping on that alone would wipe every pragma link out of the harness
+    // dirs on any machine where XDG_DATA_HOME moved or sources update never ran.
+    const cwd = tmp("pragma-setup-proj-");
+    const skillDir = seed(cwd, "gone");
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    const linkPath = join(linkDir, "gone");
+    symlinkSync(skillDir, linkPath);
+    // The whole source ROOT disappears, not just one skill.
+    rmSync(join(cwd, ".pragma", "skills"), { recursive: true, force: true });
+
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd), "project");
+    expect(detected.rootExists).toBe(false);
+    expect(detected.available).toBe(false);
+    expect(detected.orphans).toEqual([]);
+    expect(dryRun(composeSkills(detected)).effects).toEqual([]);
+
+    await runTask(composeSkills(detected));
+    expect(readlinkSync(linkPath)).toBe(skillDir);
+  });
+
+  it("SAFETY: a real dir, a resolving user link and a `-backup` sibling all survive", async () => {
+    // The three shapes the sweep must never touch, in one tree: a hand-placed
+    // directory, a link into someone's own checkout, and a link into a SIBLING
+    // whose name merely EXTENDS the root's (the old string-prefix bug).
+    const cwd = tmp("pragma-setup-proj-");
+    const root = join(cwd, ".pragma", "skills");
+    mkdirSync(root, { recursive: true }); // exists, but holds no skill
+    const backup = join(cwd, ".pragma", "skills-backup", "sibling");
+    mkdirSync(backup, { recursive: true });
+    writeFileSync(join(backup, "SKILL.md"), "the user's own copy\n");
+    const elsewhere = join(cwd, "elsewhere", "mine");
+    mkdirSync(elsewhere, { recursive: true });
+
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    const realDir = join(linkDir, "hand-placed");
+    mkdirSync(realDir, { recursive: true });
+    writeFileSync(join(realDir, "SKILL.md"), "hand-placed\n");
+    symlinkSync(elsewhere, join(linkDir, "mine"));
+    symlinkSync(backup, join(linkDir, "sibling"));
+
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd), "project");
+    expect(detected.rootExists).toBe(true); // the sweep IS entitled to act
+    expect(detected.orphans).toEqual([]); // ...and finds nothing of its own
+    expect(dryRun(composeSkills(detected)).effects).toEqual([]);
+
+    await runTask(composeSkills(detected));
+    expect(readFileSync(join(realDir, "SKILL.md"), "utf-8")).toBe(
+      "hand-placed\n",
+    );
+    expect(readlinkSync(join(linkDir, "mine"))).toBe(elsewhere);
+    expect(readlinkSync(join(linkDir, "sibling"))).toBe(backup);
+    expect(readFileSync(join(backup, "SKILL.md"), "utf-8")).toBe(
+      "the user's own copy\n",
+    );
+  });
+});
+
 describe("setup — detections settle independently", () => {
   it("gives a rejecting detection its own failed row, leaving the rest planned", async () => {
     // The targets are independent, and one `Promise.all` made them share a
     // fate: a single rejecting detection prevented a run being built at all,
-    // so NONE of the other targets ran and doctor rendered no banded rows.
+    // so NONE of the other targets ran and doctor rendered no scoped rows.
     const { TARGETS } = await import("./targets.js");
     const lsp = TARGETS.find((t) => t.id === "lsp") as (typeof TARGETS)[number];
     const spy = vi
@@ -1364,8 +2198,8 @@ describe("setup (run-all wizard)", () => {
     let thrown: unknown;
     try {
       // `--scope both`: the failing target (lsp) is global-only, and the two
-      // that must survive it write the project band, so the run has to cover
-      // both. A bare run-all is the GLOBAL band now and would not touch this
+      // that must survive it write the project scope, so the run has to cover
+      // both. A bare run-all is the GLOBAL scope now and would not touch this
       // repository at all.
       await executeVerb(
         setupSelfVerb,
@@ -1392,11 +2226,17 @@ describe("setup (run-all wizard)", () => {
   });
 
   it("omits skills gracefully when none are discovered (no mid-wizard EMPTY_RESULTS)", async () => {
-    // A run-all in a project with no skills must NOT throw — it just doesn't
-    // offer the skills step. Reaching a clean plan proves the graceful degrade.
+    // A run-all in a scope with no skills must NOT throw — it just doesn't offer
+    // the skills step. Reaching a clean plan proves the graceful degrade.
+    //
+    // POINTED AT THE PROJECT BAND, which is where an empty skills root is still
+    // an ordinary condition: the global scope now always has the bundled
+    // snapshot behind it, so a run-all there can no longer produce the empty
+    // row this cell exists to survive. The condition is the same one; only the
+    // scope that can still reach it has changed.
     const outcome = await executeVerb(
       setupSelfVerb,
-      {},
+      { local: true },
       DRY,
       bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
     );
@@ -1404,9 +2244,245 @@ describe("setup (run-all wizard)", () => {
     // The skills row is PRESENT and says why it cannot act, rather than being
     // dropped from a plan that then claims completeness.
     expect(outcome.stdout).toContain("skills");
-    expect(outcome.stdout).toContain("no skills installed");
+    expect(outcome.stdout).toContain("this project holds no skills");
     expect(outcome.stdout).toContain("lsp");
   });
+
+  it("the GLOBAL run-all offers the skills row on a fresh machine", async () => {
+    // The other side of the same graceful-degrade question, and the one a fresh
+    // install actually meets: a bare run-all is the global scope, whose skills
+    // row is now offerable from the bundled snapshot rather than skipped with a
+    // remedy the user has to go away and run.
+    const prevData = process.env.XDG_DATA_HOME;
+    process.env.XDG_DATA_HOME = tmp("pragma-runall-data-");
+    try {
+      const outcome = await executeVerb(
+        setupSelfVerb,
+        {},
+        DRY,
+        bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      );
+      expect(outcome.exitCode).toBe(0);
+      expect(outcome.stdout).toContain("skills");
+      expect(outcome.stdout).not.toContain("no skills installed");
+    } finally {
+      if (prevData === undefined) delete process.env.XDG_DATA_HOME;
+      else process.env.XDG_DATA_HOME = prevData;
+    }
+  });
+});
+
+describe("setup — a converged machine is reported, never asked", () => {
+  // A converged run composes ZERO effects, and the confirm gate then mounted
+  // Ink to render summon-core's "No operations planned." above "Proceed?".
+  // On a sub-verb, whose prompt list is empty, that contentless gate was the
+  // first and only thing the user ever saw.
+  let prevPath: string | undefined;
+  beforeEach(() => {
+    prevPath = process.env.PATH;
+    process.env.PATH = stubPath(); // no editor CLI ⇒ lsp skips
+  });
+  afterEach(() => {
+    process.env.PATH = prevPath;
+  });
+
+  const NO = { dryRun: false, undo: false, yes: false };
+
+  it("non-interactive + no --yes: the recap, NOT the `run again with --yes` hint", async () => {
+    // The compounding defect: a converged plan printed "Nothing was applied.
+    // Run again with --yes to apply." over a machine where there was nothing
+    // to apply in the first place.
+    const outcome = await executeVerb(
+      verbOf("lsp"),
+      {},
+      NO,
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).not.toContain("Run again with --yes");
+    expect(outcome.stdout).not.toContain("Setup plan");
+    // It says what was detected and what happened to it — doctor's house shape.
+    expect(outcome.stdout).toContain("skipped");
+    expect(outcome.stdout).toContain("no VS Code-family editor CLI on PATH");
+  });
+
+  it("a converged TTY run without --yes mounts NO Ink and prints the recap", async () => {
+    // The acceptance case. Faking a terminal on both streams is what makes
+    // `cliIsTTY()` true, which is the ONLY gate between this run and the wizard.
+    const prevIn = process.stdin.isTTY;
+    const prevErr = process.stderr.isTTY;
+    (process.stdin as { isTTY?: boolean }).isTTY = true;
+    (process.stderr as { isTTY?: boolean }).isTTY = true;
+    let outcome: Awaited<ReturnType<typeof executeVerb>>;
+    try {
+      outcome = await executeVerb(
+        verbOf("lsp"),
+        {},
+        NO,
+        bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      );
+    } finally {
+      (process.stdin as { isTTY?: boolean }).isTTY = prevIn;
+      (process.stderr as { isTTY?: boolean }).isTTY = prevErr;
+    }
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).not.toContain("Proceed");
+    expect(outcome.stdout).toContain("skipped");
+    // The same lazy-React probe the PROTECTED guard below uses: had the
+    // contentless gate mounted, Ink would be in the module cache.
+    const isReactPkg = (k: string) =>
+      /[\\/](react|react-dom|ink)@\d/.test(k) ||
+      /[\\/]node_modules[\\/](react|react-dom|ink)[\\/]/.test(k);
+    expect(Object.keys(require.cache ?? {}).filter(isReactPkg)).toEqual([]);
+  });
+
+  it("--dry-run is untouched — it still ends with the dry-run hint", async () => {
+    // The guard sits AFTER the `previewing` computation precisely so a preview
+    // keeps saying it was a preview.
+    const outcome = await executeVerb(
+      verbOf("lsp"),
+      {},
+      DRY,
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("Setup plan");
+    expect(outcome.stdout).toContain(DRY_RUN_HINT);
+  });
+
+  it("a PARTIALLY converged plan is NOT short-circuited", async () => {
+    // One actionable row is enough: the run goes through `execute` as before,
+    // so the wizard is still reachable on a machine with something to do.
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    const outcome = await executeVerb(
+      verbOf("mcp"),
+      { local: true },
+      NO,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    // Non-interactive without --yes ⇒ still the preview, hint and all.
+    expect(outcome.stdout).toContain("Setup plan");
+    expect(outcome.stdout).toContain(PREVIEW_HINT);
+  });
+
+  it("the run-all on a fully converged machine recaps every row at exit 0", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    // First pass configures whatever this machine can hold...
+    await executeVerb(setupSelfVerb, {}, YES, bootRuntime(FLAGS, cwd));
+    // ...the second has nothing left to do.
+    const outcome = await executeVerb(
+      setupSelfVerb,
+      {},
+      NO,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).not.toContain("Run again with --yes");
+    expect(outcome.stdout).toContain("targets configured");
+  });
+});
+
+describe("setup — the detection summary", () => {
+  let prevPath: string | undefined;
+  beforeEach(() => {
+    prevPath = process.env.PATH;
+    process.env.PATH = stubPath();
+  });
+  afterEach(() => {
+    process.env.PATH = prevPath;
+  });
+
+  /**
+   * Drive a run, capturing STDERR — which is where the report seam writes, and
+   * the same stream the Ink frame would use. The dispatcher builds its own
+   * runtime for a mutation, so an `rt.report` set on the boot runtime is
+   * replaced; capturing the stream is what actually pins the behaviour.
+   */
+  const onStderr = async (
+    verb: VerbSpec,
+    params: Record<string, unknown>,
+    flags: GlobalFlags,
+    cwd: string,
+    mutation = YES,
+  ): Promise<string[]> => {
+    const chunks: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: unknown): boolean => {
+        chunks.push(String(chunk));
+        return true;
+      });
+    try {
+      await executeVerb(verb, params, mutation, bootRuntime(flags, cwd));
+    } finally {
+      spy.mockRestore();
+    }
+    return chunks;
+  };
+
+  /** The one write the report seam made for the summary block, if any. */
+  const summaryOf = (chunks: readonly string[]): string =>
+    chunks.find((c) => c.startsWith("Detected —")) ?? "";
+
+  it("names what was detected BEFORE anything is asked, detected rows only", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    const chunks = await onStderr(setupSelfVerb, { local: true }, FLAGS, cwd);
+    // The report seam writes the block as ONE write, before the generator is
+    // driven — so it is also the first thing on the stream.
+    expect(chunks[0]?.startsWith("Detected —")).toBe(true);
+    const summary = summaryOf(chunks);
+    // FIRST — the Ink frame and this line both go to stderr, so only a line
+    // written before `execute` lands above the frame in scrollback.
+    expect(summary).toContain("Detected —");
+    expect(summary).toContain("mcp");
+    // A skip is "nothing detected here", so it is out of the default view...
+    expect(summary).not.toContain("user-level only");
+    expect(summary).toContain("--verbose lists them");
+  });
+
+  it("--verbose widens it to every row, with no `not detected` footer", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    const summary = summaryOf(
+      await onStderr(
+        setupSelfVerb,
+        { local: true },
+        { ...FLAGS, verbose: true },
+        cwd,
+      ),
+    );
+    // ...and back in under `--verbose`, which consumes the EXISTING global flag
+    // rather than adding a signal.
+    expect(summary).toContain("this one is global only");
+    expect(summary).not.toContain("--verbose lists them");
+  });
+
+  it("says nothing on a --dry-run — the plan table IS that run's output", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    const chunks = await onStderr(
+      setupSelfVerb,
+      { local: true },
+      FLAGS,
+      cwd,
+      DRY,
+    );
+    expect(summaryOf(chunks)).toBe("");
+  });
+
+  it("is silent over MCP — `rt.report` is a no-op there, so no Ink and no noise", async () => {
+    // The seam is the point: a plain-string report, not an Ink mount, is what
+    // keeps this off the React graph AND out of the MCP data stream.
+    const cwd = tmp("pragma-setup-proj-");
+    const mcp = await projectMcp([setupModule], cwd);
+    const result = await mcp.callTool("setup", { confirm: true });
+    await mcp.cleanup();
+    expect(result.ok).toBe(true);
+    expect(JSON.stringify(result.data)).not.toContain("Detected —");
+  });
 });
 
 describe("lazy-React discipline (PROTECTED)", () => {