@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/capabilities/reference.test.ts

@@ -0,0 +1,32 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { emitReference } from "../kernel/spec/emitReference.js";
+import { capabilities } from "./index.js";
+
+/** Read a committed reference page exactly as a consumer (or lychee) would. */
+function readCommitted(relPath: string): string {
+  return readFileSync(
+    fileURLToPath(new URL(`../../docs/reference/${relPath}`, import.meta.url)),
+    "utf-8",
+  );
+}
+
+describe("reference docs drift-guard — emitReference == committed (PROTECTED)", () => {
+  const emitted = emitReference(capabilities);
+
+  it("every generated page is byte-identical to the committed file", () => {
+    for (const [relPath, expected] of emitted) {
+      expect(readCommitted(relPath)).toBe(expected);
+    }
+  });
+
+  it("the committed file set matches the generated key set (no orphans, none missing)", () => {
+    const committed = readdirSync(
+      fileURLToPath(new URL("../../docs/reference/", import.meta.url)),
+    )
+      .filter((name) => name.endsWith(".md"))
+      .sort();
+    expect(committed).toEqual([...emitted.keys()].sort());
+  });
+});

package/src/capabilities/resources/provider.ts

@@ -3,9 +3,11 @@
  *
  * Listing and autocomplete are STORELESS: they read the enriched `index.json`
  * (readPackIndex) off disk, so the resource surface costs nothing until an agent
- * reads one. A read is STORE-BACKED through the SHARED {@link readEntity} — the
- * same reader `graph inspect` uses — so a resource read and a `graph inspect` of
- * the same URI return identical content (the mirror contract).
+ * reads one. They read it for the pack the BOOT DECISION names, so the listing
+ * can never advertise entities whose reads then fail STORE_UNAVAILABLE. A read
+ * is STORE-BACKED through the SHARED {@link readEntity} — the same reader
+ * `graph inspect` uses — so a resource read and a `graph inspect` of the same
+ * URI return identical content (the mirror contract).
  *
  * Degradation (Risk4): on a missing or legacy (pre-v2) index the listing returns
  * a single "run `pragma sources update`" hint — never a live re-index of the
@@ -16,10 +18,14 @@
  * the `--help`/`__complete` fast path.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { readPackIndex } from "../../kernel/completion/entitySource.js";
+import { asPragmaError } from "../../kernel/error/fromTaskError.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { mcpErrorFrom } from "../../kernel/project/mcp/mcpError.js";
 import type { PackIndex } from "../../kernel/runtime/graphpack/types.js";
 import { readEntity } from "../../kernel/runtime/readEntity.js";
+import { resolveSources } from "../../kernel/runtime/resolveSources.js";
 import type { McpResourceProvider } from "../../kernel/spec/types.js";
 
 /** Max autocomplete suggestions returned for a partial URI. */
@@ -30,13 +36,25 @@ const CLASS_PRIORITY = 0.9;
 /** MCP annotation priority for an individual (ABox) entry. */
 const INDIVIDUAL_PRIORITY = 0.3;
 
-/** The `pragma:` URI scheme + the single reserved-expansion template variable. */
+/**
+ * The `pragma:` URI scheme + the single reserved-expansion template variable.
+ *
+ * A LITERAL, and it must stay one until the wire identifiers move together.
+ * `surface/surface.v2.json` freezes `pragma:{+uri}` as protocol identity, and
+ * `buildResourceList` mints `pragma:<prefixed>` for every entry it lists —
+ * three writings of one decision. Deriving only this one made a fork advertise
+ * `recipes:{+uri}` over a list of 653 `pragma:` URIs: every resource the server
+ * offered became unreadable, and the readable form was never advertised.
+ * `resources.test.ts` pins the pair through {@link resourceProvider}'s declared
+ * surface; `identity.test.ts` masks this template out of its leak scan for the
+ * same reason.
+ */
 const URI_TEMPLATE = "pragma:{+uri}";
 
 const TEMPLATE_DESCRIPTION =
   "Knowledge-graph entities from the local pack. Read any entry by its prefixed " +
   "URI (e.g. pragma:ds:button); autocomplete matches URI or label substrings. " +
-  "Content mirrors `pragma graph inspect <uri>`.";
+  `Content mirrors \`${BIN_NAME} graph inspect <uri>\`.`;
 
 /** Agent-navigability annotations mirrored onto a listed resource. */
 export interface ResourceAnnotations {
@@ -78,8 +96,7 @@ export function buildResourceList(
       {
         uri: "pragma:sources",
         name: "Store not indexed",
-        description:
-          "No enriched entity index. Run `pragma sources update` to build it.",
+        description: `No enriched entity index. Run \`${BIN_NAME} sources update\` to build it.`,
         mimeType: "application/json",
       },
     ];
@@ -88,7 +105,18 @@ export function buildResourceList(
     const boxRank = (e: typeof a) => (e.box === "tbox" ? 0 : 1);
     return boxRank(a) - boxRank(b) || a.name.localeCompare(b.name);
   });
-  return ordered.map((entity) => {
+  // Dedup by resource URI: an OWL-punned subject (a class/property IRI ALSO
+  // asserted as a domain individual) is indexed as TWO entities — a tbox and an
+  // abox facet — that compact to the SAME `pragma:<uri>`. Mapping both would
+  // list one URI twice (A8). The sort above puts the tbox facet first, so
+  // keeping the first occurrence per URI surfaces the schema facet (its higher
+  // priority + instance count) and drops the punned duplicate.
+  const seen = new Set<string>();
+  const resources: ListedResource[] = [];
+  for (const entity of ordered) {
+    const uri = `pragma:${entity.prefixed ?? entity.name}`;
+    if (seen.has(uri)) continue;
+    seen.add(uri);
     const isTbox = entity.box === "tbox";
     // Port of the old shell's `_meta` taxonomy: `pragma/box` + a priority that
     // ranks schema (classes/properties) above individuals, so an agent browsing
@@ -104,8 +132,8 @@ export function buildResourceList(
     if (typeof instanceCount === "number") {
       meta["pragma/instanceCount"] = instanceCount;
     }
-    return {
-      uri: `pragma:${entity.prefixed ?? entity.name}`,
+    resources.push({
+      uri,
       name: entity.label || entity.name,
       ...(entity.description ? { description: entity.description } : {}),
       mimeType: "application/json" as const,
@@ -114,8 +142,9 @@ export function buildResourceList(
         priority: isTbox ? CLASS_PRIORITY : INDIVIDUAL_PRIORITY,
       },
       _meta: meta,
-    };
-  });
+    });
+  }
+  return resources;
 }
 
 /**
@@ -180,14 +209,21 @@ export const resourceProvider: McpResourceProvider = {
     const { ResourceTemplate } = await import(
       "@modelcontextprotocol/sdk/server/mcp.js"
     );
+    const { McpError, ErrorCode } = await import(
+      "@modelcontextprotocol/sdk/types.js"
+    );
+    // The index of the pack the boot decision names — `undefined` when the
+    // store is unavailable, which `buildResourceList` renders as the recovery
+    // entry rather than a catalogue of unreadable URIs.
+    const activeIndex = async (): Promise<PackIndex | undefined> =>
+      readPackIndex(resolveSources(await runtime.loadConfig(), runtime.cwd));
+
     const template = new ResourceTemplate(URI_TEMPLATE, {
-      list: async () => ({
-        resources: buildResourceList(readPackIndex(runtime.cwd)),
-      }),
+      list: async () => ({ resources: buildResourceList(await activeIndex()) }),
       complete: {
         uri: async (value: string) =>
           rankUriCompletions(
-            readPackIndex(runtime.cwd)?.entities ?? [],
+            (await activeIndex())?.entities ?? [],
             value,
             COMPLETION_LIMIT,
           ),
@@ -215,15 +251,12 @@ export const resourceProvider: McpResourceProvider = {
             ],
           };
         } catch (error) {
-          const message =
-            error instanceof PragmaError
-              ? JSON.stringify({ code: error.code, message: error.message })
-              : String(error);
-          return {
-            contents: [
-              { uri: url.href, mimeType: "text/plain", text: message },
-            ],
-          };
+          // Surface the failure as a JSON-RPC error (the resource-read analogue
+          // of a tool result's `isError`), preserving the machine code AND the
+          // recovery in `data` — never swallow it into `text/plain` content an
+          // agent reads as a successful entity (which dropped the recovery and
+          // masked a cold store as though the entity itself were malformed).
+          throw mcpErrorFrom(asPragmaError(error), { McpError, ErrorCode });
         }
       },
     );

package/src/capabilities/resources/resources.test.ts

@@ -7,6 +7,10 @@
  * degrades to a `pragma sources update` hint (never a live re-index).
  */
 
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { readPackIndex } from "../../kernel/completion/entitySource.js";
 import { verbKey } from "../../kernel/packs/uniqueness.js";
@@ -17,7 +21,35 @@ import type { VerbSpec } from "../../kernel/spec/types.js";
 import { TEST_FLAGS } from "../../testing/helpers/projectCli.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
 import { graphModule } from "../graph/index.js";
-import { buildResourceList, rankUriCompletions } from "./provider.js";
+import {
+  buildResourceList,
+  rankUriCompletions,
+  resourceProvider,
+} from "./provider.js";
+
+/**
+ * Two entities of the committed embedded pack, chosen for what they PROVE: an
+ * abox individual and the tbox class it instantiates, so the schema-before-
+ * individual ordering has both sides. Named, not counted — the roster moves
+ * whenever the design system does.
+ */
+const BUTTON_NAME = "ds:global.component.button";
+const BUTTON_URI = `pragma:${BUTTON_NAME}`;
+const COMPONENT_URI = "pragma:ds:Component";
+
+/**
+ * Blank out blank-node labels.
+ *
+ * Oxigraph re-mints blank-node identifiers every time it loads a store, so two
+ * independently booted sessions over the SAME pack name the same blank node
+ * differently. Those labels are store-local handles, not content — and this
+ * test's subject is that both surfaces return the same CONTENT for the same
+ * entity. (That the labels are not stable across processes is a real property
+ * of exposing blank nodes through `graph inspect`; the toy pack this suite used
+ * to run against simply had none.)
+ */
+const withoutBlankNodeLabels = (value: InspectResult): unknown =>
+  JSON.parse(JSON.stringify(value).replace(/_:[0-9a-f]+/g, "_:b"));
 
 describe("resource listing (storeless, over the pack index)", () => {
   it("degrades to a recovery entry on a missing or legacy index", () => {
@@ -32,37 +64,99 @@ describe("resource listing (storeless, over the pack index)", () => {
   });
 
   it("lists the enriched (v2) embedded index, schema entries first", () => {
-    const index = readPackIndex(process.cwd());
+    const index = readPackIndex({ kind: "embedded" });
     expect(index?.version).toBe(2);
     const resources = buildResourceList(index);
-    expect(resources.some((r) => r.uri === "pragma:ex:Button")).toBe(true);
+    expect(resources.some((r) => r.uri === BUTTON_URI)).toBe(true);
     // A class (tbox) sorts before an individual (abox).
-    const componentIdx = resources.findIndex(
-      (r) => r.uri === "pragma:ex:Component",
-    );
-    const buttonIdx = resources.findIndex((r) => r.uri === "pragma:ex:Button");
+    const componentIdx = resources.findIndex((r) => r.uri === COMPONENT_URI);
+    const buttonIdx = resources.findIndex((r) => r.uri === BUTTON_URI);
     expect(componentIdx).toBeLessThan(buttonIdx);
   });
 
+  it("emits ONE resource per URI for an OWL-punned subject (A8)", () => {
+    // A punned subject (a class IRI also asserted as an individual) is indexed
+    // as TWO facets — tbox + abox — sharing one prefixed URI. The listing must
+    // dedup them so the MCP resource surface carries no duplicate URI. The abox
+    // facet is listed first here to prove the dedup relies on the schema-first
+    // SORT, not input order.
+    const punned: PackIndex = {
+      version: 2,
+      contentHash: "test",
+      prefixes: {},
+      entities: [
+        {
+          name: "ex:Slider",
+          type: "ex:Category",
+          uri: "https://ex.test/#Slider",
+          prefixed: "ex:Slider",
+          types: ["owl:Class", "ex:Category"],
+          label: "Slider",
+          box: "abox",
+          description: null,
+        },
+        {
+          name: "ex:Slider",
+          type: "owl:Class",
+          uri: "https://ex.test/#Slider",
+          prefixed: "ex:Slider",
+          types: ["owl:Class", "ex:Category"],
+          label: "Slider",
+          box: "tbox",
+          description: null,
+        },
+      ],
+      instanceCountByType: {},
+    };
+    const slider = buildResourceList(punned).filter(
+      (r) => r.uri === "pragma:ex:Slider",
+    );
+    expect(slider).toHaveLength(1);
+    // The retained facet is the schema (tbox) one — surfaced above individuals.
+    expect(slider.at(0)?._meta?.["pragma/box"]).toBe("tbox");
+  });
+
   it("enriches each entry with the _meta taxonomy (pragma/box + priority)", () => {
-    const resources = buildResourceList(readPackIndex(process.cwd()));
-    const component = resources.find((r) => r.uri === "pragma:ex:Component");
-    const button = resources.find((r) => r.uri === "pragma:ex:Button");
+    const resources = buildResourceList(readPackIndex({ kind: "embedded" }));
+    const component = resources.find((r) => r.uri === COMPONENT_URI);
+    const button = resources.find((r) => r.uri === BUTTON_URI);
     // A schema class: tbox, higher priority, carries its instance count.
     expect(component?._meta?.["pragma/box"]).toBe("tbox");
     expect(component?.annotations?.audience).toEqual(["assistant"]);
     expect(component?.annotations?.priority).toBe(0.9);
-    expect(component?._meta?.["pragma/instanceCount"]).toBe(3);
+    expect(component?._meta?.["pragma/instanceCount"]).toBeGreaterThan(0);
     // An individual: abox, lower priority, no instance count.
     expect(button?._meta?.["pragma/box"]).toBe("abox");
     expect(button?.annotations?.priority).toBe(0.3);
     expect(button?._meta?.["pragma/instanceCount"]).toBeUndefined();
   });
 
+  it("mints every URI in the scheme the declared template routes", () => {
+    // Two writings of one decision: the template `register` installs (and the
+    // covenant publishes as `mcpSurface.resources`) and the scheme every listed
+    // URI carries. Nothing compared them, and a half-derivation left a fork
+    // advertising `recipes:{+uri}` over a list of `pragma:` URIs — every
+    // resource offered was unreadable and the readable form was unadvertised.
+    // DERIVED from the declared surface, so this cannot be satisfied by two
+    // literals that agree today.
+    const declared = resourceProvider.surface?.templates?.[0];
+    const scheme = `${declared?.split(":")[0]}:`;
+    const listed = [
+      ...buildResourceList(readPackIndex({ kind: "embedded" })),
+      ...buildResourceList(undefined),
+    ];
+    expect(listed.length).toBeGreaterThan(1);
+    expect(listed.filter((r) => !r.uri.startsWith(scheme))).toEqual([]);
+  });
+
   it("ranks autocomplete over prefixed URI and label", () => {
-    const index = readPackIndex(process.cwd());
-    const hits = rankUriCompletions(index?.entities ?? [], "but", 10);
-    expect(hits).toContain("ex:Button");
+    const index = readPackIndex({ kind: "embedded" });
+    const hits = rankUriCompletions(
+      index?.entities ?? [],
+      "global.component.button",
+      10,
+    );
+    expect(hits).toContain(BUTTON_NAME);
   });
 });
 
@@ -77,7 +171,7 @@ describe("resource surface over the server (embedded pack)", () => {
 
   it("registers the {+uri} template and lists resources (not tools)", async () => {
     const resources = await harness.listResources();
-    expect(resources.some((r) => r.uri === "pragma:ex:Button")).toBe(true);
+    expect(resources.some((r) => r.uri === BUTTON_URI)).toBe(true);
     // Resources are NOT tools — the graph module's tools (inspect + the PR6
     // SPARQL escape hatch) are what appear in the tool surface.
     const tools = await harness.listTools();
@@ -88,12 +182,12 @@ describe("resource surface over the server (embedded pack)", () => {
   });
 
   it("autocompletes a partial URI through the template", async () => {
-    const values = await harness.completeResource("But");
-    expect(values).toContain("ex:Button");
+    const values = await harness.completeResource("global.component.butt");
+    expect(values).toContain(BUTTON_NAME);
   });
 
   it("reads an entity, mirroring `graph inspect` content", async () => {
-    const read = await harness.readResource("pragma:ex:Button");
+    const read = await harness.readResource(BUTTON_URI);
     expect(read.mimeType).toBe("application/json");
     const fromResource = JSON.parse(read.text) as InspectResult;
 
@@ -103,12 +197,73 @@ describe("resource surface over the server (embedded pack)", () => {
       (v) => verbKey(v.path) === "graph inspect",
     ) as VerbSpec;
     const fromCli = (await inspect.run(
-      { uri: "ex:Button" },
+      { uri: BUTTON_NAME },
       rt,
     )) as InspectResult;
     (await rt.store.get()).store.dispose();
 
-    expect(fromResource).toEqual(fromCli);
-    expect(fromResource.uri).toBe("https://pragma.canonical.com/sample#Button");
+    expect(withoutBlankNodeLabels(fromResource)).toEqual(
+      withoutBlankNodeLabels(fromCli),
+    );
+    expect(fromResource.uri).toBe(
+      "https://ds.canonical.com/global.component.button",
+    );
+  });
+
+  it("rejects a read of an absent entity as InvalidParams carrying ENTITY_NOT_FOUND", async () => {
+    // The warm embedded pack resolves the `ds:` prefix but holds no `Nonexistent`
+    // subject, so the read fails ENTITY_NOT_FOUND — the caller's fault, which
+    // `mcpErrorFrom` maps to JSON-RPC InvalidParams, NOT the InternalError a cold
+    // store (STORE_UNAVAILABLE) earns.
+    const error = await harness.readResource("pragma:ds:Nonexistent").then(
+      () => undefined,
+      (caught: unknown) => caught,
+    );
+    expect(error, "the read must throw, not swallow to content").toBeDefined();
+    expect((error as Error).message).toMatch(/not found/i);
+    const failure = error as { code?: number; data?: { code?: string } };
+    expect(failure.data?.code).toBe("ENTITY_NOT_FOUND");
+    expect(failure.code).toBe(ErrorCode.InvalidParams);
+    expect(failure.code).not.toBe(ErrorCode.InternalError);
+  });
+});
+
+/**
+ * D3 — a resource-read failure surfaces as a JSON-RPC error (the read analogue of
+ * a tool result's `isError`) carrying the recovery, NOT swallowed into a
+ * `text/plain` "success" body that drops the recovery and reads as though the
+ * entity itself were malformed. A project that declares its own packs and has
+ * never built them is the cold store — it must NOT be served the distribution's
+ * embedded graph; the read boots the store, so it refuses with
+ * STORE_UNAVAILABLE.
+ */
+describe("resource read — cold-store failure surfaces isError + recovery (D3)", () => {
+  let harness: Awaited<ReturnType<typeof projectMcp>>;
+  beforeAll(async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-resource-cold-"));
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      `export default { packs: [{ name: "unbuilt", source: "file:///pragma-never-built" }] };\n`,
+    );
+    harness = await projectMcp([graphModule], cwd);
+  });
+  afterAll(async () => {
+    await harness.cleanup();
+  });
+
+  it("rejects (does not return text/plain content) with the STORE_UNAVAILABLE recovery", async () => {
+    const error = await harness.readResource(BUTTON_URI).then(
+      () => undefined,
+      (caught: unknown) => caught,
+    );
+    expect(error, "the read must throw, not swallow to content").toBeDefined();
+    expect((error as Error).message).toMatch(/store unavailable/i);
+    const data = (
+      error as {
+        data?: { code?: string; recovery?: { mcp?: { tool?: string } } };
+      }
+    ).data;
+    expect(data?.code).toBe("STORE_UNAVAILABLE");
+    expect(data?.recovery?.mcp?.tool).toBe("sources_update");
   });
 });

package/src/capabilities/scopeTypeSync.test.ts

@@ -0,0 +1,37 @@
+/**
+ * Type-sync pin (PROTECTED): the CLI's redeclared `ScopeBand`/`ScopeSelection`
+ * mirrors must stay structurally EQUAL to the `@canonical/harnesses` types.
+ *
+ * The CLI redeclares these in `doctor/types.ts` and `setup/types.ts` on purpose
+ * — so those statically-reachable type modules never pull the harnesses runtime
+ * onto the fast-path module graph (the lazy-dispatch invariant). That freedom is
+ * only safe if the mirrors do not DRIFT from the source of truth, which this
+ * `expectTypeOf` pin enforces at `tsc` time.
+ *
+ * Every harnesses import here is `import type` (type-only, erased at emit), so
+ * this file loads no harnesses runtime — the `lazy.test` no-runtime-import guard
+ * stays green (it also never reaches this test file: it walks the graph from
+ * `capabilities/index`, which imports no test).
+ */
+
+import type {
+  ScopeBand as HarnessScopeBand,
+  ScopeSelection as HarnessScopeSelection,
+} from "@canonical/harnesses";
+import { describe, expectTypeOf, it } from "vitest";
+import type { ScopeBand as DoctorScopeBand } from "./doctor/types.js";
+import type {
+  ScopeBand as SetupScopeBand,
+  ScopeSelection as SetupScopeSelection,
+} from "./setup/types.js";
+
+describe("scope type-sync — CLI mirrors == @canonical/harnesses", () => {
+  it("both ScopeBand mirrors equal the harnesses ScopeBand", () => {
+    expectTypeOf<DoctorScopeBand>().toEqualTypeOf<HarnessScopeBand>();
+    expectTypeOf<SetupScopeBand>().toEqualTypeOf<HarnessScopeBand>();
+  });
+
+  it("the setup ScopeSelection mirror equals the harnesses ScopeSelection", () => {
+    expectTypeOf<SetupScopeSelection>().toEqualTypeOf<HarnessScopeSelection>();
+  });
+});

package/src/capabilities/setup/index.ts

@@ -3,4 +3,10 @@
  */
 
 export { setupModule } from "./setup.verb.js";
-export type { SetupResult, SetupSkillsResult, SymlinkAction } from "./types.js";
+export type {
+  ConfiguredTarget,
+  ScopeSelection,
+  SetupResult,
+  SetupSkillsResult,
+  SymlinkAction,
+} from "./types.js";

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

@@ -10,6 +10,7 @@
  * `setup completions`").
  */
 
+import { existsSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
 import {
   deleteFile,
@@ -26,15 +27,39 @@ import {
   detectShell,
   type ShellId,
 } from "../shell.js";
+import type { CompletionsState } from "../types.js";
 
 /**
  * The detected completion install target: the shell, the absolute script path,
- * and the emitted script body — all `null` when no shell could be detected.
+ * the emitted script body — all `null` when no shell could be detected — and the
+ * prior on-disk {@link CompletionsState} (whether an up-to-date/stale script is
+ * already installed), read up front so the recap and a `--dry-run` are accurate
+ * and an identical rewrite is skipped.
  */
 export interface CompletionsDetection {
   readonly shell: ShellId | null;
   readonly path: string | null;
   readonly script: string | null;
+  readonly state: CompletionsState;
+}
+
+/**
+ * Classify the completion script already at `path` against the body we would
+ * write: `installed` when byte-identical (a re-run skips it), `stale` when a
+ * different script is present, `absent` when no file exists.
+ *
+ * @param path - The install path.
+ * @param script - The body a write would emit.
+ * @returns The prior {@link CompletionsState}.
+ * @note Impure — reads the install path.
+ */
+function classifyCompletions(path: string, script: string): CompletionsState {
+  if (!existsSync(path)) return "absent";
+  try {
+    return readFileSync(path, "utf8") === script ? "installed" : "stale";
+  } catch {
+    return "stale";
+  }
 }
 
 /**
@@ -52,7 +77,7 @@ export async function detectCompletions(
   cwd: string,
 ): Promise<CompletionsDetection> {
   const shell = detectShell();
-  if (!shell) return { shell: null, path: null, script: null };
+  if (!shell) return { shell: null, path: null, script: null, state: "absent" };
 
   const [{ capabilities }, { emitScripts }, { readConfig }] = await Promise.all(
     [
@@ -68,18 +93,16 @@ export async function detectCompletions(
         .filter(([, enabled]) => enabled === false)
         .map(([family]) => family)
     : undefined;
-  return {
-    shell,
-    path: completionScriptPath(shell),
-    script: emitScripts(capabilities, {
-      ...(completion?.minChars !== undefined
-        ? { minChars: completion.minChars }
-        : {}),
-      ...(disabledFamilies && disabledFamilies.length > 0
-        ? { disabledFamilies }
-        : {}),
-    })[shell],
-  };
+  const path = completionScriptPath(shell);
+  const script = emitScripts(capabilities, {
+    ...(completion?.minChars !== undefined
+      ? { minChars: completion.minChars }
+      : {}),
+    ...(disabledFamilies && disabledFamilies.length > 0
+      ? { disabledFamilies }
+      : {}),
+  })[shell];
+  return { shell, path, script, state: classifyCompletions(path, script) };
 }
 
 /**
@@ -89,6 +112,12 @@ export async function detectCompletions(
  * interprets a generator's task TWICE — once for the confirm-gate preview and
  * once to perform it — so the composed task must survive a second drive.
  *
+ * The prior `state` drives the MESSAGE only ("already up to date" / "Updating" /
+ * "Installing"), NOT whether the write happens: the (idempotent) write is always
+ * composed so it carries its `undo` — `--undo` reverses the SAME task and must
+ * find the reversible effect, and `execute` interprets the task twice. A
+ * byte-identical rewrite in the `installed` case is harmless.
+ *
  * @param d - The detection gathered up front.
  * @returns A Task that writes the script (with an undo), or warns if no shell.
  */
@@ -98,9 +127,13 @@ export function composeCompletions(d: CompletionsDetection): Task<void> {
       "Could not detect your shell — set $SHELL to zsh, bash, or fish.",
     );
   }
-  const { path, script, shell } = d;
+  const { path, script, shell, state } = d;
+  const opening =
+    state === "installed"
+      ? `${shell} completions already up to date at ${path}.`
+      : `${state === "stale" ? "Updating" : "Installing"} ${shell} completions to ${path}...`;
   return sequence_([
-    info(`Installing ${shell} completions to ${path}...`),
+    info(opening),
     mkdir(dirname(path), true),
     writeFile(path, script, { undo: deleteFile(path) }),
     info(activationHint(shell)),