@canonical/pragma-cli 0.35.0 → 0.37.0

package/src/capabilities/setup/operations/setupLsp.ts

@@ -12,9 +12,10 @@
  * VSCodium/Cursor/Windsurf/Antigravity machines unable to install at all.
  *
  * `detectLsp` probes FOR REAL up front, and spawns NOTHING: an editor is
- * "present" when its CLI resolves on PATH (the `editorClis` registry names
- * them), and "installed" when its extensions dir holds a
- * `canonical.terrazzo-lsp-extension-<version>/` entry. Running
+ * detected when its CLI resolves on PATH (the `editorClis` registry names
+ * them), carries the extension when its extensions dir holds a
+ * `canonical.terrazzo-lsp-extension-<version>/` entry, and is "installed" when
+ * that entry is also new enough to work. Running
  * `--list-extensions` instead would be the natural probe, but Cursor's Linux
  * launcher OPENS THE EDITOR on that flag — a detection step must never launch
  * an app, so the fs is the source of truth. The full extension id is matched
@@ -35,13 +36,21 @@ import type { EditorCliDefinition, PlatformEnv } from "@canonical/harnesses";
 import {
   type ExecResult,
   exec,
+  exists,
   flatMap,
   mkdir,
+  pure,
+  sequence,
   sequence_,
   type Task,
 } from "@canonical/task";
 import { BIN_NAME } from "../../../constants.js";
-import { checkExecOk, guardMissingBinary } from "../../shared/index.js";
+import { PragmaError } from "../../../kernel/error/index.js";
+import {
+  checkExecOk,
+  failPragma,
+  guardMissingBinary,
+} from "../../shared/index.js";
 import type { LspState } from "../types.js";
 
 /** The full extension id, as the editor's extensions dir spells it. */
@@ -50,10 +59,40 @@ const EXTENSION_ID = "canonical.terrazzo-lsp-extension";
 /** The npm package whose tarball bundles the VSIX. */
 const LSP_PACKAGE = "@canonical/terrazzo-lsp-extension";
 
-/** One detected editor: its registry row + whether the extension is present. */
+/**
+ * One detected editor: its registry row, its extensions directory, and the two
+ * DIFFERENT questions about the extension.
+ *
+ * `present` and `installed` are deliberately separate, and collapsing them is a
+ * silent wrong-removal. `installed` is version-gated — an entry older than
+ * {@link MIN_EXTENSION_VERSION} reports false, because the forward plan and
+ * doctor must treat a copy that cannot start as not installed. But a REMOVAL
+ * keyed on that same boolean would walk past a dead pre-0.8.3 copy that pragma
+ * itself put there, report "nothing to remove", and leave it behind forever.
+ * So removal keys on `present` (any matching entry at all) and everything else
+ * keys on `installed` (present AND new enough to work).
+ */
 export interface DetectedEditor {
   readonly editor: EditorCliDefinition;
+  /** Any `canonical.terrazzo-lsp-extension-*` entry, whatever its version. */
+  readonly present: boolean;
+  /** Present AND at least {@link MIN_EXTENSION_VERSION} — i.e. it works. */
   readonly installed: boolean;
+  /**
+   * The editor's extensions directory. Kept because the removal's forward
+   * carrier needs a path that DEMONSTRABLY already exists (see
+   * {@link composeLspRemoval}); when `present` is true, this is that path.
+   */
+  readonly extensionsDir: string;
+  /**
+   * The matching entry NAMES under {@link extensionsDir} — the artifacts
+   * `present` is true about. The removal's postcondition probes exactly
+   * these after the uninstall (see {@link composeLspRemoval}): the editor
+   * CLI's exit code and the directory listing are DIFFERENT success
+   * criteria, and only the directory is the one detection (and doctor)
+   * believe.
+   */
+  readonly presentEntries: readonly string[];
 }
 
 /**
@@ -144,37 +183,45 @@ const compareVersions = (left: number[], right: number[]): number => {
 };
 
 /**
- * Whether an editor's extensions dir holds a copy new enough to WORK.
+ * The two facts an editor's extensions dir answers: is a copy THERE, and is it
+ * new enough to WORK.
  *
- * Version-aware on purpose. Matching any `canonical.terrazzo-lsp-extension-*`
- * entry meant a machine carrying a build whose server cannot start reported
- * `installed`, so `setup lsp` skipped it and `doctor` called it healthy —
- * a wrong skip that reads as correct, which is worse than a wrong failure and
- * is exactly the trap this module's docblock warns about elsewhere. Everyone
- * who ran `setup lsp` before {@link MIN_EXTENSION_VERSION} would have kept a
- * dead language server forever, with nothing telling them why.
+ * `current` is version-aware on purpose. Matching any
+ * `canonical.terrazzo-lsp-extension-*` entry meant a machine carrying a build
+ * whose server cannot start reported `installed`, so `setup lsp` skipped it and
+ * `doctor` called it healthy — a wrong skip that reads as correct, which is
+ * worse than a wrong failure. Everyone who ran `setup lsp` before
+ * {@link MIN_EXTENSION_VERSION} would have kept a dead language server forever,
+ * with nothing telling them why. An unparseable suffix counts as too old: a
+ * directory this function cannot read the version of is one it cannot vouch for.
  *
- * An unparseable suffix counts as too old: a directory this function cannot
- * read the version of is one it cannot vouch for.
+ * `present` is the same probe WITHOUT the version gate, and it exists because
+ * removal asks a different question. A pre-0.8.3 copy is not `current`, but it
+ * is unquestionably there, and it is a copy this command installed — so a
+ * removal keyed on `current` would leave the dead extension on disk while
+ * reporting success. See {@link DetectedEditor}.
  */
-const extensionInstalled = (
+const extensionState = (
   editor: EditorCliDefinition,
   platform: PlatformEnv,
-): boolean => {
+): { present: boolean; current: boolean; entries: string[] } => {
   let entries: string[];
   try {
     entries = readdirSync(editor.extensionsDir(platform));
   } catch {
-    return false; // No extensions dir — nothing installed.
+    // No dir — nothing installed.
+    return { present: false, current: false, entries: [] };
   }
   const prefix = `${EXTENSION_ID}-`;
-  return entries.some((entry) => {
-    const lower = entry.toLowerCase();
-    if (!lower.startsWith(prefix)) return false;
-    const version = parseVersion(lower.slice(prefix.length));
+  const matching = entries.filter((entry) =>
+    entry.toLowerCase().startsWith(prefix),
+  );
+  const current = matching.some((entry) => {
+    const version = parseVersion(entry.toLowerCase().slice(prefix.length));
     if (version === undefined) return false; // Unreadable: cannot vouch for it.
     return compareVersions(version, MINIMUM) >= 0;
   });
+  return { present: matching.length > 0, current, entries: matching };
 };
 
 /**
@@ -191,10 +238,16 @@ export async function detectLsp(_cwd: string): Promise<LspDetection> {
   const platform = readPlatformEnv();
   const editors: DetectedEditor[] = editorClis
     .filter((editor) => cliOnPath(executableCandidates(editor.cli, platform)))
-    .map((editor) => ({
-      editor,
-      installed: extensionInstalled(editor, platform),
-    }));
+    .map((editor) => {
+      const { present, current, entries } = extensionState(editor, platform);
+      return {
+        editor,
+        present,
+        installed: current,
+        extensionsDir: editor.extensionsDir(platform),
+        presentEntries: entries,
+      };
+    });
   const state: LspState =
     editors.length === 0
       ? "unknown"
@@ -327,29 +380,141 @@ export function composeLsp(
 }
 
 /**
- * Compose the removal — deliberately empty. An extension install is an `exec`,
- * and an `exec` carries no reversal: pretending otherwise is what made
- * `setup lsp --undo` report a step count for work it never did. The honest
- * answer is the plan row's, which names the editor CLI that CAN uninstall it
- * (see {@link lspUninstallRemedy}) or states that this machine has none.
+ * The editors this command OWNS an extension copy in right now — every detected
+ * editor whose extensions dir holds a `canonical.terrazzo-lsp-extension-*`
+ * entry, version-gate deliberately NOT applied (see {@link DetectedEditor}).
+ *
+ * Named and shaped like `ownedMcpGroups` and `ownedSkillLinks`, and for the
+ * same reason those exist: a reversal is composed from what detection says this
+ * command owns, never from what a fresh forward plan would create.
  *
- * @param _d - The detection (unused; the shape is the table's).
- * @returns An empty Task.
+ * @param d - The detection gathered up front.
+ * @returns The editors carrying a copy.
  */
-export function composeLspRemoval(_d: LspDetection): Task<void> {
-  return sequence_([]);
+export const ownedLspEditors = (d: LspDetection): readonly DetectedEditor[] =>
+  d.editors.filter((e) => e.present);
+
+/**
+ * Compose the removal: one `<editor cli> --uninstall-extension <id>` per owned
+ * editor, carried as the `undo` of a forward no-op — and each uninstall
+ * asserts its own GOAL, not just its exit code.
+ *
+ * The docblock this replaces claimed "an `exec` carries no reversal". That was
+ * factually wrong about the effect model — `Exec` has an `undo` slot and `exec`
+ * takes `UndoOptions`. What is true is that `exec` has no DEFAULT undo; the
+ * caller supplies one, exactly as `composeMcpRemoval` does for its `mkdir`.
+ *
+ * The carrier is copied from `composeMcpRemoval`, and its trap is the reason
+ * for the shape: `runUndo` collects undos by walking the FORWARD task with
+ * effects MOCKED, so the forward side must be walkable without reading or
+ * mutating anything. A `mkdir` of the editor's own extensions directory — which
+ * `present` proves already exists — reads nothing and is a genuine no-op. Phase
+ * two then runs the uninstall against the real editor.
+ *
+ * THE POSTCONDITION is the removal's real success criterion. The exec's exit
+ * code and the extensions DIRECTORY are two different judges — detection
+ * deliberately reads the directory (probing via the CLI can launch an
+ * editor), and VS Code-family CLIs are known to exit 0 while deferring or
+ * skipping the deletion — so after `checkExecOk` the undo probes the exact
+ * entries detection said this command owns, and FAILS (with the manual
+ * deletion as the remedy — never the command that just claimed success) when
+ * any survived. An in-task failure here is safe precisely because
+ * `runCollectedUndos` executes each undo isolated: it used to abort every
+ * reversal still pending, which is why no removal could afford to assert its
+ * own goal.
+ *
+ * @param d - The detection gathered up front.
+ * @param undoKey - Correlation key stamped on each reversal, echoed on its
+ *   `UndoOutcome` so the caller can read the outcomes back per row.
+ * @returns A Task whose undo uninstalls the extension from each owned editor
+ *   and verifies the copy is gone.
+ */
+export function composeLspRemoval(
+  d: LspDetection,
+  undoKey?: string,
+): Task<void> {
+  const owned = ownedLspEditors(d);
+  // Nothing on this machine carries a copy — there is no honest work to model,
+  // and the plan row says so. Same shape as the other rows' empty removals.
+  if (owned.length === 0) return sequence_([]);
+  return sequence_(
+    owned.map(({ editor, extensionsDir, presentEntries }) => {
+      const command = `${editor.cli} --uninstall-extension ${EXTENSION_ID}`;
+      const ownedPaths = presentEntries.map((entry) =>
+        join(extensionsDir, entry),
+      );
+      const uninstall = flatMap(
+        exec(
+          editor.cli,
+          ["--uninstall-extension", EXTENSION_ID],
+          extensionsDir,
+        ),
+        (result) =>
+          checkExecOk(command, result as ExecResult, {
+            message:
+              `${editor.name} refused the uninstall (its output is above). ` +
+              `Remove it by hand with \`${command}\`.`,
+          }),
+      );
+      // The probe must apply DETECTION'S presence criterion, or the check can
+      // quietly stop checking: `extensionState` calls an entry present when
+      // `readdirSync` lists it, and a default `exists` (`fs.access`) follows
+      // symlinks — so a dangling matching symlink would be "installed" to
+      // detection and "absent" here, and an editor that exits 0 without
+      // removing it would report `undone` while the next detection finds it
+      // again. `followSymlinks: false` is `lstat` semantics: the entry
+      // itself, exactly what the directory listing answers.
+      const verified = flatMap(uninstall, () =>
+        flatMap(
+          sequence(ownedPaths.map((p) => exists(p, { followSymlinks: false }))),
+          (stillThere) => {
+            const survivors = ownedPaths.filter((_, i) => stillThere[i]);
+            if (survivors.length === 0) return pure(undefined);
+            // The remedy presents the surviving paths as DATA, never as a
+            // synthesized shell line: the names come from `readdirSync`, so
+            // no quoting is trustworthy, and one command cannot be right for
+            // every platform the editor registry supports.
+            return failPragma(
+              new PragmaError({
+                code: "UNSUPPORTED",
+                message: `\`${command}\` exited 0, but the extension is still present after the undo ran.`,
+                recovery: {
+                  message: `Delete ${survivors.length === 1 ? "this entry" : "these entries"} from ${editor.name}'s extensions folder by hand, then restart it: ${survivors.join(" · ")}`,
+                },
+              }),
+            );
+          },
+        ),
+      );
+      return mkdir(extensionsDir, true, {
+        undo: guardMissingBinary(
+          editor.cli,
+          {
+            message: `The \`${editor.cli}\` CLI disappeared from PATH mid-run — restore it, then run \`${BIN_NAME} setup lsp --undo\` again.`,
+          },
+          verified,
+        ),
+        undoKey,
+      });
+    }),
+  );
 }
 
 /**
  * The uninstall instruction for a detection — a command that runs on THIS
- * machine, or `undefined` when no editor CLI was found and there is therefore
- * nothing honest to print.
+ * machine, or `undefined` when nothing here carries the extension and there is
+ * therefore nothing honest to print.
+ *
+ * It names an OWNING editor. Reading `d.editors.at(0)` named the first editor
+ * on PATH instead, so a machine with Cursor installed and the extension only in
+ * VSCodium printed a command against the wrong editor — one that would report
+ * success having uninstalled nothing.
  *
  * @param d - The detection gathered up front.
  * @returns The uninstall command, or undefined.
  */
 export function lspUninstallRemedy(d: LspDetection): string | undefined {
-  const cli = d.editors.at(0)?.editor.cli;
+  const cli = ownedLspEditors(d).at(0)?.editor.cli;
   return cli === undefined
     ? undefined
     : `${cli} --uninstall-extension ${EXTENSION_ID}`;

package/src/capabilities/setup/operations/setupMcp.ts

@@ -11,9 +11,9 @@
  *
  * Detection ALSO reads each group's existing config (via `readMcpConfigFrom`,
  * FOR REAL up front) and classifies every group as `absent` (no pragma entry
- * yet), `configured` (the pragma entry already matches what we'd write), or
+ * yet), `registered` (the pragma entry already matches what we'd write), or
  * `drifted` (a pragma entry exists but differs). The wizard shows that prior
- * state in each row and DEFAULT-DESELECTS the already-`configured` files; the
+ * state in each row and DEFAULT-DESELECTS the already-`registered` files; the
  * write itself stays idempotent (a re-merge of the identical entry is
  * byte-for-byte), so a re-run is a no-op the recap reports as "unchanged" — the
  * same state-awareness `setup skills` has always had.
@@ -21,6 +21,7 @@
 
 import { dirname } from "node:path";
 import type {
+  ConfigTarget,
   McpServerConfig,
   PlatformEnv,
   TargetGroup,
@@ -28,7 +29,7 @@ import type {
 import { mkdir, sequence_, type Task } from "@canonical/task";
 import { MCP_SERVER_NAME } from "../../../constants.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
-import type { McpTargetState, ScopeBand } from "../types.js";
+import type { McpTargetState, Scope } from "../types.js";
 
 /** The `writeMcpConfigTargets` builder, captured from the dynamic harness import. */
 type WriteMcpConfigTargets =
@@ -41,15 +42,25 @@ type RemoveMcpConfigFrom =
 /**
  * The detected MCP state: the per-file target groups (already scoped to the
  * requested `--scope`), a by-path map of each group's prior
- * {@link McpTargetState} (read up front), the project root, and the
- * (dynamically imported) target-based writer the pure `composeMcp` needs
- * synchronously. Keeping `groups` a plain {@link TargetGroup}[] leaves every
- * existing `.groups` consumer (path/harnessNames/scope) unchanged; the state
- * rides alongside, keyed by the group's `path`.
+ * {@link McpTargetState} (read up front), the same states at PER-WRITE
+ * resolution, the project root, and the (dynamically imported) target-based
+ * writer the pure `composeMcp` needs synchronously. Keeping `groups` a plain
+ * {@link TargetGroup}[] leaves every existing `.groups` consumer
+ * (path/harnessNames/scope) unchanged; the state rides alongside, keyed by the
+ * group's `path`.
+ *
+ * `stateByPath` is what the WRITE side needs — a file is written unless every
+ * key in it is already current — and it is the aggregate of `stateByWrite`
+ * (see {@link aggregateMcpStates}), so the two can never disagree.
+ * `stateByWrite` is the finer grain a per-HARNESS report needs: two harnesses
+ * sharing one file own two different keys in it, and the file's aggregate is
+ * not either harness's standing.
  */
 export interface McpDetection {
   readonly groups: readonly TargetGroup[];
   readonly stateByPath: ReadonlyMap<string, McpTargetState>;
+  /** Each write's own state, keyed by {@link mcpWriteKey} — see the docblock. */
+  readonly stateByWrite: ReadonlyMap<string, McpTargetState>;
   readonly cwd: string;
   readonly platform: PlatformEnv;
   readonly writeMcpConfigTargets: WriteMcpConfigTargets;
@@ -74,49 +85,54 @@ const MCP_SERVE_ARGV = ["mcp", "serve"] as const;
 /**
  * The pragma MCP server entry we register — the SINGLE source of truth both the
  * classifier (does the existing entry match this?) and the writer (`composeMcp`)
- * consume, so "already configured" means byte-for-byte what a write would emit.
+ * consume, so "already registered" means byte-for-byte what a write would emit.
  *
- * The entry is BAND-shaped: a project-band entry records the project root as
+ * The entry is SCOPE-shaped: a project-scope entry records the project root as
  * `cwd` (that binding is the point of a per-repo registration), while a
- * global-band entry OMITS `cwd` entirely — a per-user server must not be
+ * global-scope entry OMITS `cwd` entirely — a per-user server must not be
  * pinned to whatever directory `setup mcp --global` happened to run from
  * (observed: a global registration from `~/Downloads` permanently served
  * `~/Downloads`, and re-running from repo B "repaired" it to repo B,
- * ping-ponging the machine band between projects). The per-harness
+ * ping-ponging the machine scope between projects). The per-harness
  * serializers already omit an undefined `cwd`, and the matcher treats an
  * omitted controlled field as must-be-absent, so a stale global entry still
  * carrying a `cwd` classifies as `drifted` and converges on the next write.
  *
- * @param cwd - The project root (recorded only on project-band entries).
- * @param band - The config band the entry is written to.
+ * @param cwd - The project root (recorded only on project-scope entries).
+ * @param scope - The config scope the entry is written to.
  * @returns The pragma {@link McpServerConfig}.
  */
-export function pragmaMcpEntry(cwd: string, band: ScopeBand): McpServerConfig {
-  return band === "project"
+export function pragmaMcpEntry(cwd: string, scope: Scope): McpServerConfig {
+  return scope === "project"
     ? { command: MCP_SERVER_NAME, args: [...MCP_SERVE_ARGV], cwd }
     : { command: MCP_SERVER_NAME, args: [...MCP_SERVE_ARGV] };
 }
 
 /**
- * Classify one target group against its on-disk config: `absent` when no pragma
- * entry exists in ANY of the group's writes, `configured` when EVERY write
- * already carries a matching pragma entry, `drifted` otherwise (present in at
- * least one write but not matching everywhere). Reads each write's file for real
- * via `readMcpConfigFrom`, and matches each raw entry against what THAT write's
- * per-harness serializer would emit for the group's BAND (`mcpEntryMatches`
+ * Classify ONE write against its on-disk config: `absent` when the file carries
+ * no pragma entry under this write's `mcpKey`, `registered` when the entry
+ * already matches what this write would emit, `drifted` when one is there and
+ * differs. Reads the file for real via `readMcpConfigFrom` (which reads only
+ * this write's key), and matches the raw entry against what THAT write's
+ * per-harness serializer would emit for the group's SCOPE (`mcpEntryMatches`
  * compares the serializer's controlled fields — so a global entry still
  * pinning a `cwd` reads as drifted — and ignores extra keys a harness or user
  * added, so we never churn a file we did not author).
  *
- * @param group - The target group whose writes to inspect.
- * @param want - The canonical pragma entry for the group's band.
+ * The write, not the file, is the unit that can be classified honestly: a
+ * shared `.vscode/mcp.json` holds VS Code's `servers` and Cline's `mcpServers`
+ * as two independent entries, and "the file" has no single state when one is
+ * current and the other is missing.
+ *
+ * @param write - The resolved config target to inspect.
+ * @param want - The canonical pragma entry for the group's scope.
  * @param harnessesApi - The dynamically imported harnesses module.
  * @param runTask - The node Task interpreter.
- * @returns The group's {@link McpTargetState}.
- * @note Impure — reads each write's config file.
+ * @returns This write's {@link McpTargetState}.
+ * @note Impure — reads the write's config file.
  */
-async function classifyGroup(
-  group: TargetGroup,
+async function classifyWrite(
+  write: ConfigTarget,
   want: McpServerConfig,
   harnessesApi: Pick<
     typeof import("@canonical/harnesses"),
@@ -124,37 +140,60 @@ async function classifyGroup(
   >,
   runTask: typeof import("@canonical/task/node").runTask,
 ): Promise<McpTargetState> {
-  let present = 0;
-  let matching = 0;
-  for (const write of group.writes) {
-    const servers = await runTask(harnessesApi.readMcpConfigFrom(write));
-    const existing = servers[MCP_SERVER_NAME];
-    if (existing === undefined) continue;
-    present += 1;
-    if (harnessesApi.mcpEntryMatches(existing, want, write.serializeEntry)) {
-      matching += 1;
-    }
-  }
-  if (present === 0) return "absent";
-  if (matching === group.writes.length) return "configured";
-  return "drifted";
+  const servers = await runTask(harnessesApi.readMcpConfigFrom(write));
+  const existing = servers[MCP_SERVER_NAME];
+  if (existing === undefined) return "absent";
+  return harnessesApi.mcpEntryMatches(existing, want, write.serializeEntry)
+    ? "registered"
+    : "drifted";
 }
 
+/**
+ * The state of a whole FILE, aggregated from its writes: `absent` when no write
+ * carries the entry, `registered` when every write already carries a matching
+ * one, `drifted` otherwise. This is the rule the write side needs — a file is
+ * rewritten unless it is `registered` everywhere — and it is deliberately the
+ * only place the per-write states are collapsed, so nothing else re-derives it.
+ *
+ * @param states - Each write's own state, in the group's write order.
+ * @returns The group's {@link McpTargetState}.
+ */
+const aggregateMcpStates = (
+  states: readonly McpTargetState[],
+): McpTargetState => {
+  if (states.every((state) => state === "absent")) return "absent";
+  if (states.every((state) => state === "registered")) return "registered";
+  return "drifted";
+};
+
+/**
+ * The key one write's state is recorded under: the file it lands in AND the
+ * `mcpKey` it owns there. `(path, mcpKey)` is exactly the write-dedup key
+ * `groupConfigTargets` builds its `writes` from, so the map has one entry per
+ * write and no two harnesses sharing a file can collide. The separator is NUL
+ * because a config path may legally contain everything else.
+ *
+ * @param write - The resolved config target.
+ * @returns Its lookup key in {@link McpDetection.stateByWrite}.
+ */
+const mcpWriteKey = (write: ConfigTarget): string =>
+  `${write.path}\u0000${write.mcpKey}`;
+
 /**
  * Detect the AI harnesses present in the project (real reads, up front),
  * resolve+dedup their config targets for the chosen scope, AND read each
- * group's existing config to classify it `absent`/`configured`/`drifted` — so
- * the wizard can show prior state and default-deselect already-`configured`
+ * group's existing config to classify it `absent`/`registered`/`drifted` — so
+ * the wizard can show prior state and default-deselect already-`registered`
  * files.
  *
  * @param rt - The per-invocation runtime.
- * @param band - The band being planned (global or project).
- * @returns The band's target groups, their prior states, + the config writer.
+ * @param scope - The scope being planned (global or project).
+ * @returns The scope's target groups, their prior states, + the config writer.
  * @note Impure — reads the filesystem via `detectHarnesses` + `readMcpConfigFrom`.
  */
 export async function detectMcp(
   rt: PragmaRuntime,
-  band: ScopeBand,
+  scope: Scope,
 ): Promise<McpDetection> {
   const cwd = rt.cwd;
   const [
@@ -174,29 +213,45 @@ export async function detectMcp(
   ]);
   const platform = readPlatformEnv();
   const detected = await runTask(detectHarnesses(cwd, platform));
-  const groups = groupTargetsForScope(detected, cwd, band, platform);
+  const groups = groupTargetsForScope(detected, cwd, scope, platform);
 
   // Read each group's existing config (for real, up front) so the recap/preview
   // and the default selection reflect true prior state — the same discipline
   // `detectSkills` uses for its per-link create/skip/replace decision. The
-  // wanted entry is BAND-shaped (a global entry omits `cwd`), so it is built
-  // per group, not once.
+  // wanted entry is SCOPE-shaped (a global entry omits `cwd`), so it is built
+  // per group, not once. Each WRITE is classified and kept; the file's state is
+  // their aggregate, so the coarse view is derived from the fine one rather
+  // than measured separately.
   const stateByPath = new Map<string, McpTargetState>();
+  const stateByWrite = new Map<string, McpTargetState>();
   await Promise.all(
     groups.map(async (group) => {
-      const state = await classifyGroup(
-        group,
-        pragmaMcpEntry(cwd, group.scope),
-        { readMcpConfigFrom, mcpEntryMatches },
-        runTask,
+      const want = pragmaMcpEntry(cwd, group.scope);
+      const classified = await Promise.all(
+        group.writes.map(async (write) => ({
+          write,
+          state: await classifyWrite(
+            write,
+            want,
+            { readMcpConfigFrom, mcpEntryMatches },
+            runTask,
+          ),
+        })),
+      );
+      for (const { write, state } of classified) {
+        stateByWrite.set(mcpWriteKey(write), state);
+      }
+      stateByPath.set(
+        group.path,
+        aggregateMcpStates(classified.map((c) => c.state)),
       );
-      stateByPath.set(group.path, state);
     }),
   );
 
   return {
     groups,
     stateByPath,
+    stateByWrite,
     cwd,
     platform,
     writeMcpConfigTargets,
@@ -212,6 +267,22 @@ export function mcpGroupState(d: McpDetection, path: string): McpTargetState {
   return d.stateByPath.get(path) ?? "absent";
 }
 
+/**
+ * The prior state of ONE write — the state of the single harness key it owns,
+ * not of the file it shares. Defaults to `absent` for an unknown write, the
+ * same way {@link mcpGroupState} does for an unknown path.
+ *
+ * @param d - The detection gathered up front.
+ * @param write - One of a group's {@link ConfigTarget} writes.
+ * @returns That write's {@link McpTargetState}.
+ */
+export function mcpWriteState(
+  d: McpDetection,
+  write: ConfigTarget,
+): McpTargetState {
+  return d.stateByWrite.get(mcpWriteKey(write)) ?? "absent";
+}
+
 /** The target groups the user selected (by path), or all when none recorded. */
 export function selectedGroups(
   d: McpDetection,
@@ -222,7 +293,7 @@ export function selectedGroups(
 
 /**
  * Compose the per-target config writes for the SELECTED groups (pure —
- * re-runnable; builds ABSOLUTE config paths itself). An already-`configured`
+ * re-runnable; builds ABSOLUTE config paths itself). An already-`registered`
  * group composes NOTHING: the entry on disk is byte-for-byte what a write would
  * emit, so re-writing it would only move an mtime. Removal no longer depends on
  * the forward plan having written something ({@link composeMcpRemoval}), which
@@ -241,9 +312,9 @@ export function composeMcp(
   // Re-runnable combinators (NOT a single-use `gen`): `execute` interprets the
   // task twice (preview + perform). One combined write per file keeps a shared
   // file (VS Code + Cline) a single read-modify-write — dry-run safe. The
-  // written entry is BAND-shaped per group (a global entry omits `cwd`).
+  // written entry is SCOPE-shaped per group (a global entry omits `cwd`).
   const pending = groups.filter(
-    (group) => mcpGroupState(d, group.path) !== "configured",
+    (group) => mcpGroupState(d, group.path) !== "registered",
   );
   return sequence_(
     pending.map((group) =>
@@ -257,8 +328,8 @@ export function composeMcp(
 }
 
 /**
- * The groups this band OWNS right now — every file where detection classifies a
- * pragma entry as present (`configured` or `drifted`). Removal acts on exactly
+ * The groups this scope OWNS right now — every file where detection classifies a
+ * pragma entry as present (`registered` or `drifted`). Removal acts on exactly
  * this set, so a file that never carried the entry is never rewritten and a
  * foreign server in a file that does is never touched.
  */
@@ -285,9 +356,14 @@ export const ownedMcpGroups = (d: McpDetection): readonly TargetGroup[] =>
  * same file is never touched.
  *
  * @param d - The detection gathered up front.
+ * @param undoKey - Correlation key stamped on the reversal(s), echoed on
+ *   their undo outcomes so the caller can read results back per row.
  * @returns A Task whose undo removes the pragma entry from each owned file.
  */
-export function composeMcpRemoval(d: McpDetection): Task<void> {
+export function composeMcpRemoval(
+  d: McpDetection,
+  undoKey?: string,
+): Task<void> {
   return sequence_(
     ownedMcpGroups(d).map((group) =>
       mkdir(dirname(group.path), true, {
@@ -296,6 +372,7 @@ export function composeMcpRemoval(d: McpDetection): Task<void> {
             d.removeMcpConfigFrom(write, MCP_SERVER_NAME),
           ),
         ),
+        undoKey,
       }),
     ),
   );