@canonical/pragma-cli 0.36.0 → 0.38.0

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

@@ -17,6 +17,14 @@
  * 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.
+ *
+ * And it asks, for each group, whether the file could be WRITTEN at all —
+ * `probeWritable`, before a single write is composed. A NixOS or home-manager
+ * user whose config directory is managed produced a `failed` row carrying a
+ * raw `EACCES` and no next step, on a machine configured exactly as its owner
+ * intends; that is now a named skip whose remedy is the entry itself, printed
+ * through the same serializer the write would have used, for the user to put
+ * in the config that owns the directory.
  */
 
 import { dirname } from "node:path";
@@ -29,7 +37,9 @@ 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, Scope } from "../types.js";
+import { type Roots, shortenPath } from "../plan.js";
+import type { McpTargetState, Scope, WriteBlock } from "../types.js";
+import { type FsProbe, probeWritable } from "./writability.js";
 
 /** The `writeMcpConfigTargets` builder, captured from the dynamic harness import. */
 type WriteMcpConfigTargets =
@@ -39,6 +49,10 @@ type WriteMcpConfigTargets =
 type RemoveMcpConfigFrom =
   typeof import("@canonical/harnesses").removeMcpConfigFrom;
 
+/** The one-line TOML entry serializer, captured from the same import. */
+type SerializeTomlInlineEntry =
+  typeof import("@canonical/harnesses").serializeTomlInlineEntry;
+
 /**
  * The detected MCP state: the per-file target groups (already scoped to the
  * requested `--scope`), a by-path map of each group's prior
@@ -61,10 +75,26 @@ export interface McpDetection {
   readonly stateByPath: ReadonlyMap<string, McpTargetState>;
   /** Each write's own state, keyed by {@link mcpWriteKey} — see the docblock. */
   readonly stateByWrite: ReadonlyMap<string, McpTargetState>;
+  /**
+   * The groups whose file cannot be written, by group path — a Nix-managed or
+   * read-only location, probed up front.
+   *
+   * Keyed by the group's path rather than per write, because writability is a
+   * property of the FILE: two harnesses sharing `.vscode/mcp.json` are blocked
+   * or not together, whatever keys they own inside it.
+   */
+  readonly blockedByPath: ReadonlyMap<string, WriteBlock>;
   readonly cwd: string;
   readonly platform: PlatformEnv;
   readonly writeMcpConfigTargets: WriteMcpConfigTargets;
   readonly removeMcpConfigFrom: RemoveMcpConfigFrom;
+  /**
+   * The TOML entry serializer a blocked Codex row prints its remedy with —
+   * carried here for the same reason the writer is: this module imports only
+   * TYPES from `@canonical/harnesses`, so the package stays off the fast path,
+   * and the pure message builders need the function synchronously.
+   */
+  readonly serializeTomlInlineEntry: SerializeTomlInlineEntry;
 }
 
 /**
@@ -188,12 +218,14 @@ const mcpWriteKey = (write: ConfigTarget): string =>
  *
  * @param rt - The per-invocation runtime.
  * @param scope - The scope being planned (global or project).
+ * @param probe - The writability filesystem seam; defaults to the real one.
  * @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,
   scope: Scope,
+  probe?: FsProbe,
 ): Promise<McpDetection> {
   const cwd = rt.cwd;
   const [
@@ -204,6 +236,7 @@ export async function detectMcp(
       readMcpConfigFrom,
       readPlatformEnv,
       removeMcpConfigFrom,
+      serializeTomlInlineEntry,
       writeMcpConfigTargets,
     },
     { runTask },
@@ -224,6 +257,14 @@ export async function detectMcp(
   // than measured separately.
   const stateByPath = new Map<string, McpTargetState>();
   const stateByWrite = new Map<string, McpTargetState>();
+  // Writability, per file, before anything is composed. Cheap (a stat walk and
+  // one `access`), and it is what turns an unavoidable failure into a row that
+  // says what to do instead.
+  const blockedByPath = new Map<string, WriteBlock>();
+  for (const group of groups) {
+    const block = probeWritable(group.path, probe);
+    if (block !== undefined) blockedByPath.set(group.path, block);
+  }
   await Promise.all(
     groups.map(async (group) => {
       const want = pragmaMcpEntry(cwd, group.scope);
@@ -252,10 +293,12 @@ export async function detectMcp(
     groups,
     stateByPath,
     stateByWrite,
+    blockedByPath,
     cwd,
     platform,
     writeMcpConfigTargets,
     removeMcpConfigFrom,
+    serializeTomlInlineEntry,
   };
 }
 
@@ -283,6 +326,155 @@ export function mcpWriteState(
   return d.stateByWrite.get(mcpWriteKey(write)) ?? "absent";
 }
 
+/**
+ * The block on one group's file, or `undefined` when it can be written.
+ *
+ * @param d - The detection gathered up front.
+ * @param path - The group's config file path.
+ * @returns The {@link WriteBlock}, or undefined.
+ */
+export const mcpGroupBlock = (
+  d: McpDetection,
+  path: string,
+): WriteBlock | undefined => d.blockedByPath.get(path);
+
+/**
+ * Why one BLOCKED group's file cannot be written — one line, as the renderer
+ * prints one.
+ *
+ * @param d - The detection gathered up front.
+ * @param group - A group whose file is blocked.
+ * @param roots - The two roots the path renders relative to.
+ * @returns The reason.
+ */
+function describeMcpBlock(
+  block: WriteBlock,
+  path: string,
+  roots: Roots,
+): string {
+  const where = shortenPath(path, roots);
+  return block.kind === "nix-store"
+    ? `${where} is managed by Nix (it resolves to ${block.resolved})`
+    : `${where} is not writable (${block.path})`;
+}
+
+/**
+ * Why one group's file cannot be written, or `undefined` when it can be.
+ *
+ * @param d - The detection gathered up front.
+ * @param group - The group whose file may be blocked.
+ * @param roots - The two roots the path renders relative to.
+ * @returns The reason, or `undefined` when the file can be written.
+ */
+export function mcpBlockReason(
+  d: McpDetection,
+  group: TargetGroup,
+  roots: Roots,
+): string | undefined {
+  const block = mcpGroupBlock(d, group.path);
+  return block === undefined
+    ? undefined
+    : describeMcpBlock(block, group.path, roots);
+}
+
+/**
+ * The remedy beneath a blocked group: the EXACT entry a write would have
+ * emitted, and nothing else.
+ *
+ * It is serialized through the group's own `serializeEntry` — the same
+ * function the writer uses — so the entry a user copies into their
+ * home-manager or NixOS config is byte-for-byte what `setup mcp` would have
+ * written, and the next detection classifies it `registered` rather than
+ * `drifted`. A hand-written sample in this string would be a second
+ * serializer to keep in sync, and the failure mode is a config the tool then
+ * offers to "repair" forever.
+ *
+ * It is written in the file's OWN FORMAT. A JSON body pasted into Codex's
+ * `config.toml` is not an entry, it is a syntax error, and the row that
+ * printed it was the one row whose whole job was to say what to write. The
+ * TOML spelling is the dotted-key inline table — the same entry the writer's
+ * `[mcp_servers.pragma]` table holds, in the one-line form a remedy can print
+ * (the renderer gives it one dim line).
+ *
+ * Every write in the group is included, keyed by its own `mcpKey`: a shared
+ * `.vscode/mcp.json` holds two independent entries, and half the answer is
+ * not an answer.
+ *
+ * The line does NOT restate the path or the cause. The reason line directly
+ * above it has said both ({@link mcpBlockReason}), and a remedy that repeats
+ * them is the duplication the LSP remedies beside it dropped: a remedy states
+ * the action.
+ *
+ * @param d - The detection gathered up front.
+ * @param group - The group whose file is blocked.
+ * @param roots - The two roots the path renders relative to.
+ * @returns The remedy line.
+ */
+function blockedMcpRemedy(
+  d: McpDetection,
+  group: TargetGroup,
+  roots: Roots,
+): string {
+  const want = pragmaMcpEntry(d.cwd, group.scope);
+  const where = shortenPath(group.path, roots);
+  const toml = group.writes[0]?.configFormat === "toml";
+  const body = toml
+    ? group.writes
+        .map((write) =>
+          d.serializeTomlInlineEntry(
+            write.mcpKey,
+            MCP_SERVER_NAME,
+            write.serializeEntry(want),
+          ),
+        )
+        .join(" ")
+    : JSON.stringify(
+        Object.fromEntries(
+          group.writes.map((write) => [
+            write.mcpKey,
+            { [MCP_SERVER_NAME]: write.serializeEntry(want) },
+          ]),
+        ),
+      );
+  return `put this entry in the config that owns ${where}: ${body}`;
+}
+
+/** The groups whose file cannot be written, in `d.groups` order. */
+export const blockedMcpGroups = (d: McpDetection): readonly TargetGroup[] =>
+  d.groups.filter((group) => d.blockedByPath.has(group.path));
+
+/**
+ * The FIRST group whose file cannot be written, with its reason and its remedy
+ * already derived — or `undefined` when every file in the scope is writable.
+ *
+ * It hands back the derived strings rather than the group, for the reason
+ * `firstLspBlock` spells out: the blockedness is what makes the two strings
+ * exist, so a caller that took the group and asked for them separately had to
+ * assert that both were there, on both surfaces.
+ *
+ * @param d - The detection gathered up front.
+ * @param roots - The two roots the path renders relative to.
+ * @returns The first block's reason and remedy, or `undefined`.
+ */
+export const firstMcpBlock = (
+  d: McpDetection,
+  roots: Roots,
+): { readonly reason: string; readonly remedy: string } | undefined => {
+  // A walk rather than `blockedMcpGroups(d).at(0)`: the group and its block
+  // come out together, so nothing has to assert afterwards that the block a
+  // filter just proved is there really is.
+  for (const group of d.groups) {
+    const block = mcpGroupBlock(d, group.path);
+    if (block !== undefined) {
+      return {
+        reason: describeMcpBlock(block, group.path, roots),
+        remedy: blockedMcpRemedy(d, group, roots),
+      };
+    }
+  }
+  return undefined;
+};
+
 /** The target groups the user selected (by path), or all when none recorded. */
 export function selectedGroups(
   d: McpDetection,
@@ -314,7 +506,11 @@ export function composeMcp(
   // file (VS Code + Cline) a single read-modify-write — dry-run safe. The
   // written entry is SCOPE-shaped per group (a global entry omits `cwd`).
   const pending = groups.filter(
-    (group) => mcpGroupState(d, group.path) !== "registered",
+    (group) =>
+      mcpGroupState(d, group.path) !== "registered" &&
+      // A blocked file is never written. The write is what USED to discover the
+      // block, and it discovered it as a raw fs error on a `failed` row.
+      !d.blockedByPath.has(group.path),
   );
   return sequence_(
     pending.map((group) =>
@@ -334,7 +530,13 @@ export function composeMcp(
  * foreign server in a file that does is never touched.
  */
 export const ownedMcpGroups = (d: McpDetection): readonly TargetGroup[] =>
-  d.groups.filter((group) => mcpGroupState(d, group.path) !== "absent");
+  d.groups.filter(
+    (group) =>
+      mcpGroupState(d, group.path) !== "absent" &&
+      // A blocked file cannot be written, so it cannot be un-written either.
+      // The row says so rather than composing a reversal that would fail.
+      !d.blockedByPath.has(group.path),
+  );
 
 /**
  * Compose the removal of the pragma entry from every owned file.
@@ -356,9 +558,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, {
@@ -367,6 +574,7 @@ export function composeMcpRemoval(d: McpDetection): Task<void> {
             d.removeMcpConfigFrom(write, MCP_SERVER_NAME),
           ),
         ),
+        undoKey,
       }),
     ),
   );

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

@@ -754,14 +754,19 @@ export const ownedSkillLinks = (
  * this command owns, never from what a fresh forward plan would create.
  *
  * @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 every owned link.
  */
-export function composeSkillsRemoval(d: SkillsDetection): Task<void> {
+export function composeSkillsRemoval(
+  d: SkillsDetection,
+  undoKey?: string,
+): Task<void> {
   const owned = ownedSkillLinks(d);
   if (owned.length === 0) return sequence_([]);
   return sequence_(
     owned.map((a) =>
-      symlink(a.target, a.linkPath, { undo: deleteFile(a.linkPath) }),
+      symlink(a.target, a.linkPath, { undo: deleteFile(a.linkPath), undoKey }),
     ),
   );
 }

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

@@ -0,0 +1,151 @@
+/**
+ * `probeWritable` — the pure half, driven entirely over its `FsProbe` seam.
+ *
+ * Every branch here decides whether a row REPORTS a named skip or attempts a
+ * write that fails with a raw fs message, and two of them cannot be arranged
+ * for real: a test process running as root can write to a `0o500` directory,
+ * and no CI host has a `/nix/store`. So the filesystem is three injected
+ * functions and each rule is asserted against a fixture that spells out the
+ * machine it stands for.
+ *
+ * The fixture factory is stateful (it records the walk), so it lives in
+ * `testing/helpers/fsProbe.ts` and is shared with the setup and doctor suites
+ * rather than copied into each.
+ */
+
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { fakeFsProbe as probe } from "../../../testing/helpers/fsProbe.js";
+import type { WriteBlock } from "../types.js";
+import { probeWritable } from "./writability.js";
+
+describe("probeWritable", () => {
+  it("probes the TARGET ITSELF when it is present, not only its directory", () => {
+    // home-manager symlinks `mcp.json` straight into the store and leaves
+    // `User/` writable. Stopping at the parent would call the file writable
+    // and then fail on the write.
+    const fs = probe({
+      present: ["/home/u/.config/Code/User/mcp.json"],
+      realpath: {
+        "/home/u/.config/Code/User/mcp.json": "/nix/store/abc-vscode/mcp.json",
+      },
+    });
+    expect(probeWritable("/home/u/.config/Code/User/mcp.json", fs)).toEqual({
+      kind: "nix-store",
+      resolved: "/nix/store/abc-vscode/mcp.json",
+    } satisfies WriteBlock);
+    expect(fs.seen).toEqual(["/home/u/.config/Code/User/mcp.json"]);
+  });
+
+  it("passes a present, writable target", () => {
+    const fs = probe({ present: ["/home/u/.vscode/extensions"] });
+    expect(probeWritable("/home/u/.vscode/extensions", fs)).toBeUndefined();
+    expect(fs.accessed).toEqual(["/home/u/.vscode/extensions"]);
+  });
+
+  it("passes an ABSENT target whose directory is writable", () => {
+    // The ordinary first run: the extensions dir does not exist yet, and it is
+    // writable exactly when the directory that would hold it is.
+    const fs = probe({ present: ["/home/u"] });
+    expect(probeWritable("/home/u/.vscode/extensions", fs)).toBeUndefined();
+    expect(fs.accessed).toEqual(["/home/u"]);
+  });
+
+  it("walks up through several missing levels to the nearest existing node", () => {
+    const fs = probe({ present: ["/home/u"] });
+    expect(
+      probeWritable("/home/u/.config/Code/User/mcp.json", fs),
+    ).toBeUndefined();
+    expect(fs.seen).toEqual([
+      "/home/u/.config/Code/User/mcp.json",
+      "/home/u/.config/Code/User",
+      "/home/u/.config/Code",
+      "/home/u/.config",
+      "/home/u",
+    ]);
+  });
+
+  it("follows the symlink: the STORE path is the answer, not the link's own name", () => {
+    // `~/.vscode/extensions` → `/nix/store/…`: nothing about the link's name
+    // says it is managed, and the raw fs error the write produced said nothing
+    // about Nix either.
+    const fs = probe({
+      present: ["/home/u/.vscode/extensions"],
+      realpath: {
+        "/home/u/.vscode/extensions": "/nix/store/xyz-vscode-with-extensions",
+      },
+    });
+    expect(probeWritable("/home/u/.vscode/extensions", fs)).toEqual({
+      kind: "nix-store",
+      resolved: "/nix/store/xyz-vscode-with-extensions",
+    } satisfies WriteBlock);
+    // W_OK is never consulted — see the next case for why that matters.
+    expect(fs.accessed).toEqual([]);
+  });
+
+  it("the store wins over W_OK: a store path NEVER reports `read-only`", () => {
+    // The store is read-only, so `access(W_OK)` fails there too. Reporting
+    // `read-only` would print a permissions remedy at a Nix user — advice that
+    // cannot work, and that the next `nixos-rebuild` would undo anyway.
+    const fs = probe({
+      present: ["/home/u/.vscode/extensions"],
+      realpath: { "/home/u/.vscode/extensions": "/nix/store/abc/extensions" },
+      denied: ["/nix/store/abc/extensions"],
+    });
+    expect(probeWritable("/home/u/.vscode/extensions", fs)?.kind).toBe(
+      "nix-store",
+    );
+  });
+
+  it("reports read-only with the RESOLVED path a remedy has to name", () => {
+    const fs = probe({
+      present: ["/mnt/ro/home/.vscode/extensions"],
+      realpath: {
+        "/mnt/ro/home/.vscode/extensions": "/mnt/ro/real/extensions",
+      },
+      denied: ["/mnt/ro/real/extensions"],
+    });
+    expect(probeWritable("/mnt/ro/home/.vscode/extensions", fs)).toEqual({
+      kind: "read-only",
+      path: "/mnt/ro/real/extensions",
+    } satisfies WriteBlock);
+  });
+
+  it("reports read-only for an absent target under a read-only directory", () => {
+    const fs = probe({ present: ["/mnt/ro"], denied: ["/mnt/ro"] });
+    expect(probeWritable("/mnt/ro/Code/User/mcp.json", fs)).toEqual({
+      kind: "read-only",
+      path: "/mnt/ro",
+    } satisfies WriteBlock);
+  });
+
+  it("blocks nothing when the walk runs out of parents", () => {
+    // `dirname("/")` is `"/"`, so the walk terminates on the fixed point. With
+    // nothing existing anywhere there is no permission answer to give, and
+    // inventing one either way would be a guess.
+    const fs = probe({});
+    expect(probeWritable("/nowhere/at/all", fs)).toBeUndefined();
+    expect(fs.seen.at(-1)).toBe("/");
+  });
+
+  it("blocks nothing when realpath itself fails — the write is the honest judge", () => {
+    // The node existed a moment ago and cannot be resolved now: a race, or a
+    // symlink loop. Reporting a skip would be a claim this probe cannot back.
+    const fs = probe({
+      present: ["/home/u/.vscode/extensions"],
+      realpathThrows: true,
+    });
+    expect(probeWritable("/home/u/.vscode/extensions", fs)).toBeUndefined();
+  });
+
+  it("defaults to the real filesystem — a writable temp dir passes", () => {
+    // The one case that touches the disk, so the default argument is covered
+    // by something other than a fixture claiming to be it. A temp dir, not
+    // `process.cwd()`: the case says "a writable directory", and the repo
+    // working tree is neither guaranteed to be one nor this suite's business.
+    const dir = mkdtempSync(join(tmpdir(), "pragma-writability-"));
+    expect(probeWritable(dir)).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,135 @@
+/**
+ * "Could this command write there?" — asked BEFORE anything is written.
+ *
+ * Two machines answer no, and until this probe existed both answered it the
+ * same wrong way. A NixOS or home-manager user's `~/.vscode/extensions` is a
+ * symlink into `/nix/store`, which is a read-only filesystem by design:
+ * `--install-extension` failed with a raw fs error, or appeared to succeed and
+ * changed nothing. A managed config directory turned the MCP write into a
+ * `failed` row carrying an EACCES message and no next step. Neither is a
+ * failure of this command — the machine is configured exactly as its owner
+ * intends — so both become NAMED SKIPS whose remedy is the one action that
+ * works there: declaring the extension, or the MCP entry, in the config that
+ * owns the directory.
+ *
+ * Per the owner, 2026-09-16: the decision is made by the DIRECTORY, never by
+ * the OS. Nix is not a platform to branch on — a Nix user's home directory is
+ * ordinary, a non-Nix user can have a read-only mount, and `/etc/nixos` says
+ * nothing about whether THIS path is writable. So the probe walks the path it
+ * was actually given.
+ *
+ * The whole filesystem surface is the injected {@link FsProbe}, so every
+ * branch is exercised over a seam rather than by arranging a real read-only
+ * directory (which a test running as root cannot do at all). It lives under
+ * `setup/operations/` because setup is its one consumer: doctor reads the
+ * result off the detection records setup already produced, and never probes
+ * a second time.
+ */
+
+import { accessSync, constants, existsSync, realpathSync } from "node:fs";
+import { dirname } from "node:path";
+import type { WriteBlock } from "../types.js";
+
+/** The store prefix a Nix-managed path resolves under. */
+const NIX_STORE_PREFIX = "/nix/store/";
+
+/**
+ * The filesystem this probe uses — the seam, defaulting to `node:fs`.
+ *
+ * Narrowed to the three calls, so a fixture is three functions rather than a
+ * module mock, and so nothing here can reach a writer by accident.
+ */
+export interface FsProbe {
+  existsSync(path: string): boolean;
+  accessSync(path: string, mode?: number): void;
+  realpathSync(path: string): string;
+}
+
+/** The real filesystem — the default, and the only impure thing in this module. */
+const nodeFs: FsProbe = { existsSync, accessSync, realpathSync };
+
+/**
+ * The nearest node at or above `target` that exists, or `undefined` when the
+ * walk runs out of parents.
+ *
+ * `dirname("/")` is `"/"`, so the loop terminates on the fixed point rather
+ * than on a path shape — the same is true of a win32 drive root, which is why
+ * the comparison is against the previous value and not against a separator.
+ *
+ * @param target - The path to start at.
+ * @param fs - The filesystem seam.
+ * @returns The nearest existing node, or `undefined`.
+ * @note Impure — stats each path it walks through the injected seam.
+ */
+const findNearestExisting = (
+  target: string,
+  fs: FsProbe,
+): string | undefined => {
+  let current = target;
+  for (;;) {
+    if (fs.existsSync(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+};
+
+/**
+ * Probe whether `target` could be written, returning the {@link WriteBlock}
+ * that says why not — or `undefined` when the write can go ahead.
+ *
+ * Three rules, in this order:
+ *
+ * 1. **Walk up to the nearest node that exists**, starting AT the target. The
+ *    target itself when it is there — home-manager symlinks `mcp.json`
+ *    directly into the store while leaving `User/` writable, so stopping at
+ *    the parent directory would call that file writable and then fail on the
+ *    write. Otherwise its nearest existing ancestor, because a path that does
+ *    not exist yet is writable exactly when the directory that would hold it
+ *    is.
+ * 2. **`realpathSync` it**, so the answer is about the real filesystem rather
+ *    than the symlink standing in front of it.
+ * 3. **`/nix/store/` wins over `W_OK`.** Checked first, deliberately: the
+ *    store is read-only, so `access(W_OK)` would fail there too and the row
+ *    would report "read-only" with a remedy about file permissions — advice
+ *    that cannot work, because `chmod` on the store is not the fix and would
+ *    be undone by the next `nixos-rebuild`. The remedy for a store path is a
+ *    declaration in the user's own config, and naming the store is what earns
+ *    it.
+ *
+ * @param target - The file or directory a write would create or modify.
+ * @param fs - The filesystem seam; defaults to the real `node:fs`.
+ * @returns The block, or `undefined` when the path is writable.
+ * @note Impure by default — it stats and resolves real paths. Every branch is
+ * reachable through the injected {@link FsProbe}.
+ */
+export function probeWritable(
+  target: string,
+  fs: FsProbe = nodeFs,
+): WriteBlock | undefined {
+  const existing = findNearestExisting(target, fs);
+  // Nothing at or above the target exists. That is not a permission answer,
+  // and inventing one either way would be a guess — the write will report its
+  // own error if it is really unreachable.
+  if (existing === undefined) return undefined;
+
+  let resolved: string;
+  try {
+    resolved = fs.realpathSync(existing);
+  } catch {
+    // The node existed a moment ago and cannot be resolved now (a race, or a
+    // symlink loop). Not a block: the caller's write is the honest judge.
+    return undefined;
+  }
+
+  if (resolved.startsWith(NIX_STORE_PREFIX)) {
+    return { kind: "nix-store", resolved };
+  }
+
+  try {
+    fs.accessSync(resolved, constants.W_OK);
+  } catch {
+    return { kind: "read-only", path: resolved };
+  }
+  return undefined;
+}

package/src/capabilities/setup/plan.ts

@@ -117,6 +117,17 @@ export interface SetupPlan {
   readonly rows: readonly PlanRow[];
 }
 
+/**
+ * The context a path renders against — the plan's two named roots.
+ *
+ * It lives here, beside {@link SetupPlan}, because it IS that structure's
+ * `roots` field and every reader of it already imports this module: the target
+ * table, the renderers, the doctor checks, and the operations whose messages
+ * shorten a path. Declaring it in the target table instead put the operations
+ * in the position of importing the module that imports them.
+ */
+export type Roots = SetupPlan["roots"];
+
 /**
  * Whether a plan action would touch the filesystem. `none` and `skip` are the
  * two quiet outcomes: a converged re-run composes no effects at all, so mtimes