@canonical/pragma-cli 0.38.0 → 0.40.0

package/src/capabilities/sources/sources.test.ts

@@ -23,6 +23,7 @@ import type {
 } from "../../kernel/config/types.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
 import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { styleFor } from "../../kernel/render/style.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
 import { createQueryFacade } from "../../kernel/runtime/facade.js";
 import { readManifest } from "../../kernel/runtime/graphpack/manifest.js";
@@ -44,6 +45,7 @@ import { discoverSkills } from "../skill/discover.js";
 import { collectStatus } from "./collectStatus.js";
 import { sourcesModule } from "./index.js";
 import { buildUpdateTask } from "./runUpdate.js";
+import { renderSourcesStatusPlain } from "./status.render.js";
 
 const FLAGS: GlobalFlags = {
   llm: false,
@@ -69,15 +71,25 @@ const tmp = (prefix: string): string => {
   return dir;
 };
 
-/** A runtime whose config is the given pack list (no config files needed). */
-function runtimeFor(cwd: string, packs: PackDeclaration[]): PragmaRuntime {
+/**
+ * A runtime whose config is the given pack list (no config files needed).
+ *
+ * `packsOrigin` is the knob the boot decision reads to tell "this project pinned
+ * its own packs" from "the distribution's defaults" — `"project"` by default,
+ * since that is what a test that BUILDS a pack is describing.
+ */
+function runtimeFor(
+  cwd: string,
+  packs: PackDeclaration[],
+  packsOrigin: "default" | "project" = "project",
+): PragmaRuntime {
   const layers: ConfigLayers = {
     config: { channel: "normal", packs },
     origins: {
       tier: "default",
       channel: "default",
       detail: "default",
-      packs: "project",
+      packs: packsOrigin,
       stories: "default",
       prefixes: "default",
     },
@@ -562,6 +574,9 @@ describe("sources update — data-failure classification (U6)", () => {
     expect(err.recovery?.message ?? "").not.toContain("report this issue");
     // The recovery points the user at a runnable, useful next step.
     expect(err.recovery?.cli).toBe("pragma sources update --verbose");
+    // `--verbose` is a global CLI flag with no MCP counterpart, and a hint
+    // never carries `confirm`: the plan the tool returns says how to proceed.
+    expect(err.recovery?.mcp).toEqual({ tool: "sources_update", params: {} });
     // Nothing was pointed at on failure.
     expect(readActivePack(cwd)).toBeUndefined();
   });
@@ -1255,3 +1270,143 @@ describe("sources status CLI-json == MCP tool (PROTECTED)", () => {
     expect((cliEnvelope.data as { store: string }).store).toBe("embedded");
   });
 });
+
+describe("a pack an older CLI built (upgrade healing)", () => {
+  const resetVerb = sourcesModule.verbs[2] as VerbSpec;
+  const REAL = { dryRun: false, undo: false, yes: true };
+  /** Any version below the running CLI's — what an older build recorded. */
+  const OLDER = "0.1.0";
+
+  /** Build a real pack for `cwd`, then rewrite the builder version it records. */
+  async function builtWithVersion(
+    cwd: string,
+    version: string,
+  ): Promise<string> {
+    const pkg = filePackage();
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-old", source: `file://${pkg}` },
+    ]);
+    const result = await runTask(await buildUpdateTask(runtime));
+    const path = join(packDir(result.contentHash), "manifest.json");
+    const manifest = JSON.parse(readFileSync(path, "utf-8"));
+    writeFileSync(path, JSON.stringify({ ...manifest, version }));
+    return result.contentHash;
+  }
+
+  it("status reports the snapshot answering, and names the pack passed over", async () => {
+    const cwd = tmp("pragma-proj-");
+    const hash = await builtWithVersion(cwd, OLDER);
+
+    // The reported install: a pointer to a pack an older CLI built, and a config
+    // that pins no packs of its own (the distribution's defaults).
+    const status = await collectStatus(runtimeFor(cwd, [], "default"));
+    expect(status.store).toBe("embedded");
+    expect(status.ignoredPack).toEqual({
+      contentHash: hash,
+      builtBy: OLDER,
+      builtAt: expect.any(String),
+    });
+    expect(renderSourcesStatusPlain(status, styleFor(false))).toContain(
+      `a pack built by pragma ${OLDER} on`,
+    );
+  });
+
+  it("a project with its OWN packs keeps reading its pack, stale or not", async () => {
+    const cwd = tmp("pragma-proj-");
+    const hash = await builtWithVersion(cwd, OLDER);
+
+    // Byte-identical to the behaviour before the upgrade row existed: its own
+    // packs are its own graph, and the snapshot is not a substitute for them.
+    const status = await collectStatus(
+      runtimeFor(cwd, [{ name: "pkg-old", source: "file:///x" }], "project"),
+    );
+    expect(status.store).toBe("built");
+    expect(status.contentHash).toBe(hash);
+    expect(status.ignoredPack).toBeNull();
+  });
+
+  it("re-running the update makes the pack answer again, and the notice goes", async () => {
+    const cwd = tmp("pragma-proj-");
+    const hash = await builtWithVersion(cwd, OLDER);
+    const pkg = filePackage();
+
+    // The STRICTEST form of this case: the sources have not moved, so the update
+    // reuses the very same content-addressed directory rather than building a
+    // new one. Reuse has to refresh the recorded builder version, or the update
+    // the notice recommends would change nothing and the project would be stuck.
+    const rebuilt = await runTask(
+      await buildUpdateTask(
+        runtimeFor(cwd, [{ name: "pkg-old", source: `file://${pkg}` }]),
+      ),
+    );
+    expect(rebuilt.contentHash).toBe(hash);
+    expect(rebuilt.reused).toBe(true);
+    expect(readManifest(packDir(hash))?.version).toBe(VERSION);
+
+    const status = await collectStatus(runtimeFor(cwd, [], "default"));
+    expect(status.store).toBe("built");
+    expect(status.ignoredPack).toBeNull();
+  });
+
+  it("`sources reset` drops the pointer, and the snapshot answers", async () => {
+    const cwd = tmp("pragma-proj-");
+    const hash = await builtWithVersion(cwd, OLDER);
+
+    const outcome = await executeVerb(
+      resetVerb,
+      {},
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain(hash.slice(0, 12));
+    expect(outcome.stdout).toContain("snapshot shipped with the CLI");
+    // The pointer is gone, so the boot has nothing to pass over any more.
+    expect(readActivePack(cwd)).toBeUndefined();
+    const status = await collectStatus(bootRuntime(FLAGS, cwd));
+    expect(status.store).toBe("embedded");
+    expect(status.ignoredPack).toBeNull();
+    // The pack's own files are left alone: the cache is content-addressed and
+    // shared, so another project reading the same hash is untouched, and the
+    // next update reuses it instead of rebuilding.
+    expect(existsSync(packDir(hash))).toBe(true);
+  });
+
+  it("a second reset is a calm no-op, not a failure", async () => {
+    const cwd = tmp("pragma-proj-");
+    await builtWithVersion(cwd, OLDER);
+    await executeVerb(resetVerb, {}, REAL, bootRuntime(FLAGS, cwd));
+
+    const again = await executeVerb(
+      resetVerb,
+      {},
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(again.exitCode).toBe(0);
+    expect(again.stdout).toContain("nothing to reset");
+  });
+
+  it("MCP sources_reset without confirm plans only, and removes nothing", async () => {
+    const cwd = tmp("pragma-proj-");
+    const hash = await builtWithVersion(cwd, OLDER);
+
+    const mcp = await projectMcp([sourcesModule], cwd);
+    const envelope = await mcp.callTool("sources_reset"); // no confirm
+    expect(envelope.ok).toBe(true);
+    expect(envelope.meta).toMatchObject({
+      planOnly: true,
+      confirmRequired: true,
+    });
+    const plan = (envelope.data as { plan: string[] }).plan;
+    expect(plan.some((line) => line.includes(activePackPath(cwd)))).toBe(true);
+    expect(readActivePack(cwd)).toBe(hash);
+
+    // And with `confirm`, the same call performs it.
+    const done = await mcp.callTool("sources_reset", { confirm: true });
+    await mcp.cleanup();
+    expect(done.ok).toBe(true);
+    expect((done.data as { removed: boolean }).removed).toBe(true);
+    expect(readActivePack(cwd)).toBeUndefined();
+  });
+});

package/src/capabilities/sources/status.render.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { type RenderStyle, styleFor } from "../../kernel/render/style.js";
-import { renderSourcesStatusPlain } from "./status.render.js";
+import { renderSourcesStatusPlain, statusFormatters } from "./status.render.js";
 import type { SourcesStatusData } from "./types.js";
 
 /** A project reading from its own built pack, with two configured sources. */
@@ -11,6 +11,7 @@ const BUILT: SourcesStatusData = {
   sourceRef: "ds,extra",
   builtAt: "2026-01-01",
   entityCount: 42,
+  ignoredPack: null,
   sources: [
     { name: "ds", ref: "git+https://example.test/ds.git#main" },
     { name: "extra", ref: "extra@1" },
@@ -84,6 +85,45 @@ describe("renderSourcesStatusPlain", () => {
     expect(out).not.toContain("  pack: ");
   });
 
+  it("names the built pack the snapshot is answering in place of", () => {
+    // The upgrade state: this project HAS a pack, an older CLI built it, and the
+    // snapshot is answering. The headline still reports what answers (the
+    // snapshot); the extra line is the pack that is being passed over, and both
+    // ways out of it.
+    const out = renderSourcesStatusPlain(
+      {
+        ...BUILT,
+        store: "embedded",
+        ignoredPack: {
+          contentHash: "0e82d35c66687b8a",
+          builtBy: "0.37.0",
+          builtAt: "2026-09-10T21:49:00.411Z",
+        },
+      },
+      styleFor(false),
+    );
+    expect(out).toContain("Store: embedded snapshot");
+    expect(out).toContain(
+      "  0e82d35c6668: a pack built by pragma 0.37.0 on 2026-09-10 is ignored — run `pragma sources update` to rebuild it or `pragma sources reset` to remove it",
+    );
+  });
+
+  it("the llm form names the ignored pack and both ways out", () => {
+    const out = statusFormatters.llm({
+      ...BUILT,
+      store: "embedded",
+      ignoredPack: {
+        contentHash: "0e82d35c66687b8a",
+        builtBy: "0.37.0",
+        builtAt: "2026-09-10T21:49:00.411Z",
+      },
+    });
+    expect(out).toContain(
+      "- Ignored: a pack built by pragma 0.37.0 on 2026-09-10 is ignored",
+    );
+    expect(out).toContain("`pragma sources reset`");
+  });
+
   it("says so when no packs are configured", () => {
     const out = renderSourcesStatusPlain(
       { ...BUILT, sources: [] },
@@ -92,3 +132,25 @@ describe("renderSourcesStatusPlain", () => {
     expect(out).toContain("  (none configured)");
   });
 });
+
+describe("sources status — the condensed form keeps the next step", () => {
+  it("says what to run when the store is not built, and nothing extra when it is", () => {
+    const unavailable: SourcesStatusData = {
+      ...BUILT,
+      store: "unavailable",
+      contentHash: null,
+      sourceRef: null,
+      builtAt: null,
+      entityCount: null,
+    };
+    expect(statusFormatters.llm(unavailable)).toContain(
+      "- Store: not built (run `pragma sources update`)",
+    );
+    expect(
+      statusFormatters.llm({ ...unavailable, store: "embedded" }),
+    ).toContain(
+      "- Store: embedded snapshot (run `pragma sources update` to build from the configured packs)",
+    );
+    expect(statusFormatters.llm(BUILT)).toContain("- Store: ready");
+  });
+});

package/src/capabilities/sources/status.render.ts

@@ -2,9 +2,11 @@
  * Formatters for `pragma sources status` — plain, llm, json.
  */
 
-import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
+import { describeIgnoredPack } from "../../kernel/runtime/resolveSources.js";
+import { renderCall } from "../../kernel/spec/call.js";
 import type { Formatters } from "../../kernel/spec/index.js";
+import { BUILD_STORE_CALL } from "../shared/calls.js";
 import type { SourcesStatusData } from "./types.js";
 
 /**
@@ -12,11 +14,13 @@ import type { SourcesStatusData } from "./types.js";
  * explicitly: the distribution's snapshot answers reads, but it is a snapshot,
  * so reporting it as "up to date" would be a lie.
  */
-const STORE_HEADLINE: Record<SourcesStatusData["store"], string> = {
-  built: "ready",
-  embedded: `embedded snapshot (run \`${BIN_NAME} sources update\` to build from the configured packs)`,
-  unavailable: `not built (run \`${BIN_NAME} sources update\`)`,
-};
+function storeHeadline(store: SourcesStatusData["store"]): string {
+  const update = `run \`${renderCall(BUILD_STORE_CALL, "cli")}\``;
+  if (store === "built") return "ready";
+  return store === "embedded"
+    ? `embedded snapshot (${update} to build from the configured packs)`
+    : `not built (${update})`;
+}
 
 /**
  * Render `sources status` as plain text.
@@ -32,13 +36,22 @@ export function renderSourcesStatusPlain(
   data: SourcesStatusData,
   style: RenderStyle = defaultStyle(),
 ): string {
-  const lines = [`Store: ${STORE_HEADLINE[data.store]}`];
+  const lines = [`Store: ${storeHeadline(data.store)}`];
   if (data.contentHash !== null) {
     lines.push(
       `  pack: ${data.contentHash.slice(0, 12)} — ${data.entityCount ?? "?"} entities, built ${data.builtAt ?? "?"}`,
       `  from: ${data.sourceRef ?? "?"}`,
     );
   }
+  // The pack this project built and is NOT reading. It says so on its own line
+  // rather than in the headline: the headline answers "what is answering", and
+  // the answer (the snapshot) is unchanged — this is the extra fact that the
+  // directory has a pack and it is being passed over.
+  if (data.ignoredPack !== null) {
+    lines.push(
+      `  ${data.ignoredPack.contentHash.slice(0, 12)}: ${describeIgnoredPack(data.ignoredPack)}`,
+    );
+  }
   lines.push("", style.enabled ? style.bold("Sources:") : "Sources:");
   if (data.sources.length === 0) {
     lines.push("  (none configured)");
@@ -62,7 +75,11 @@ export const statusFormatters: Formatters<SourcesStatusData> = {
   },
 
   llm(data) {
-    const lines = [`# sources`, `- Store: ${data.store}`];
+    // The next step rides the condensed form too: an agent reading `embedded`
+    // or `unavailable` bare was told a state and not what to do about it.
+    const lines = [`# sources`, `- Store: ${storeHeadline(data.store)}`];
+    if (data.ignoredPack !== null)
+      lines.push(`- Ignored: ${describeIgnoredPack(data.ignoredPack)}`);
     if (data.sourceRef !== null) lines.push(`- From: ${data.sourceRef}`);
     if (data.entityCount !== null)
       lines.push(`- Entities: ${data.entityCount}`);

package/src/capabilities/sources/status.verb.ts

@@ -21,6 +21,8 @@ export const statusVerb: VerbSpec<
   path: ["sources", "status"],
   summary: "Report which pack answers reads, and the packs it was built from.",
   doc: "Storeless — reads config and the pack cache without booting the store, so it works even when the store is cold. Reports whether reads are answered by a locally built pack, by the embedded snapshot, or not at all.",
+  useWhen:
+    "when results look empty or stale, to see which data pack is answering",
   params: [],
   output: { formatters: statusFormatters },
   examples: [

package/src/capabilities/sources/types.ts

@@ -3,6 +3,8 @@
  * (the Task that resolves, builds, and points the project at a pack).
  */
 
+import type { IgnoredPack } from "../../kernel/runtime/resolveSources.js";
+
 /** The `sources status` payload — assembled without booting the store. */
 export interface SourcesStatusData {
   readonly cwd: string;
@@ -19,6 +21,15 @@ export interface SourcesStatusData {
   readonly builtAt: string | null;
   /** Total indexed entity count from the answering pack, or null. */
   readonly entityCount: number | null;
+  /**
+   * The project's own built pack when the boot passed over it — built by an
+   * older CLI, in a project that declares no packs of its own, so the embedded
+   * snapshot answers instead. `store` is `"embedded"` in that case (it reports
+   * which pack ANSWERS, and the snapshot does), and this is how status says the
+   * pack is still there and why it is not being read. Null whenever there is
+   * nothing passed over, which is every other state.
+   */
+  readonly ignoredPack: IgnoredPack | null;
   /** The configured pack declarations, as written in the config. */
   readonly sources: readonly {
     readonly name: string;
@@ -26,6 +37,21 @@ export interface SourcesStatusData {
   }[];
 }
 
+/** The `sources reset` result payload. */
+export interface SourcesResetData {
+  /** Whether a pointer was there to remove (false = nothing was built). */
+  readonly removed: boolean;
+  /** The content hash the removed pointer named, or null when there was none. */
+  readonly contentHash: string | null;
+  /**
+   * What answers this project's reads now that the pointer is gone — the
+   * embedded snapshot, or nothing at all because the project declares its own
+   * packs and must build them. Resolved from config in the run body, so the
+   * result can say which of the two it left behind instead of guessing.
+   */
+  readonly answers: "embedded" | "unavailable";
+}
+
 /** One resolved source in the `sources update` result. */
 export interface UpdatedSource {
   readonly name: string;

package/src/capabilities/sources/update.verb.ts

@@ -26,6 +26,9 @@ export const updateVerb: VerbSpec<
   path: ["sources", "update"],
   summary: "Resolve configured packs and build the local store from them.",
   doc: "Resolves each configured pack (git, file, or npm) and builds one local pack from them, which every later run reads without touching the network. Put a commit SHA in a pack source ref to pin it to that revision.",
+  useWhen:
+    "when asked to fetch or rebuild the design-system data, or when a read reports that the store is unavailable",
+  example: { skipInvalid: true },
   params: [
     {
       kind: "boolean",

package/src/capabilities/surface.test.ts

@@ -378,14 +378,14 @@ describe("surface COMPLETE — emitted == covenant (PROTECTED)", () => {
   // The CLOSING direction: assertConforms already proves emitted ⊆ covenant;
   // this proves covenant ⊆ emitted, so together the tool sets are EQUAL — the
   // surface-complete milestone. After PR7, every covenant tool is realized.
-  it("emits every covenant tool (all 49) — set equality with the covenant", () => {
+  it("emits every covenant tool (all 50) — set equality with the covenant", () => {
     const emittedTools = new Set(emitted.mcpSurface.tools);
     const missing = golden.mcpSurface.tools.filter((t) => !emittedTools.has(t));
     expect(missing).toEqual([]);
     expect([...emitted.mcpSurface.tools].sort()).toEqual(
       [...golden.mcpSurface.tools].sort(),
     );
-    expect(emitted.mcpSurface.tools).toHaveLength(49);
+    expect(emitted.mcpSurface.tools).toHaveLength(50);
   });
 
   // The covenant edit: the non-tool MCP surface is frozen too.

package/src/capabilities/token.parity.test.ts

@@ -34,7 +34,7 @@ import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
 import type { PragmaRuntime } from "../kernel/runtime/types.js";
 import type { VerbSpec } from "../kernel/spec/types.js";
 import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
-import { declaredStories } from "./distribution.js";
+import { declaredLookups, declaredStories } from "./distribution.js";
 
 const tokenPack = declaredStories.get("token");
 if (!tokenPack) {
@@ -269,6 +269,7 @@ const verbs = () =>
     tokenPack,
     distributionSource("pragma.conf.ts"),
     DEFAULT_PREFIX_MAP,
+    declaredLookups,
   );
 const verb = (label: string) =>
   verbs().find((v) => verbKey(v.path) === `token ${label}`) as VerbSpec;
@@ -624,7 +625,7 @@ describe("token consumers — the binding tuple, either spelling (PROTECTED)", (
       answered as never,
     );
     expect(notice).toContain("matches `--variable button-color-background`.");
-    expect(notice).toContain("Either no component uses this token");
+    expect(notice).toContain("stands for no token");
   });
 
   it("--key and --state narrow to one tuple each", async () => {

package/src/capabilities/tokenGraph.shipped.exec.test.ts

@@ -44,7 +44,7 @@ import { bootRuntime } from "../kernel/runtime/boot.js";
 import type { PragmaRuntime } from "../kernel/runtime/types.js";
 import type { CapabilityModule, VerbSpec } from "../kernel/spec/types.js";
 import { TEST_FLAGS } from "../testing/helpers/projectCli.js";
-import { declaredStories } from "./distribution.js";
+import { declaredLookups, declaredStories } from "./distribution.js";
 
 const SOURCE = distributionSource("pragma.conf.ts");
 
@@ -55,7 +55,7 @@ const modules = new Map<string, CapabilityModule>(
   NOUNS.map((noun) => {
     const story = declaredStories.get(noun);
     if (!story) throw new Error(`pragma.conf.ts declares no "${noun}" story`);
-    return [noun, compileStoryModule(story, SOURCE, {})];
+    return [noun, compileStoryModule(story, SOURCE, {}, declaredLookups)];
   }),
 );
 
@@ -536,6 +536,18 @@ describe("the shipped nouns answer, end to end (PROTECTED)", () => {
     }
   });
 
+  it("several mistyped symbols each get a share of the suggestions", async () => {
+    const refusal = await rows("token", "values", {
+      symbol: ["color.tex", "color.bordr"],
+    }).catch((error: unknown) => error);
+    expect(refusal).toMatchObject({
+      code: "INVALID_INPUT",
+      message: 'No token is named "color.tex", "color.bordr".',
+    });
+    const { suggestions } = refusal as { suggestions: string[] };
+    expect(suggestions.slice(0, 2)).toEqual(["color.text", "color.border"]);
+  });
+
   it("a dash-stripped variable name resolves, with its declarations", async () => {
     const variable = await lookup("variable", "color-text");
     expect(variable).toMatchObject({

package/src/capabilities/upgrade/upgrade.verb.ts

@@ -24,6 +24,7 @@ const upgradeVerb: VerbSpec<Record<string, unknown>, UpgradeData> = {
   path: ["upgrade"],
   summary: `Upgrade the ${BIN_NAME} CLI to the latest version.`,
   doc: "Checks the registry for the active channel's latest release and runs your package manager's global-update command. Preview the update before applying it.",
+  useWhen: "when asked to update the CLI itself to the latest release",
   params: [],
   output: { formatters: upgradeFormatters },
   examples: [

package/src/capabilities/variable.parity.test.ts

@@ -34,7 +34,7 @@ import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
 import type { PragmaRuntime } from "../kernel/runtime/types.js";
 import type { VerbSpec } from "../kernel/spec/types.js";
 import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
-import { declaredStories } from "./distribution.js";
+import { declaredLookups, declaredStories } from "./distribution.js";
 
 const variablePack = declaredStories.get("variable");
 if (!variablePack) {
@@ -183,6 +183,7 @@ const verbs = () =>
     variablePack,
     distributionSource("pragma.conf.ts"),
     DEFAULT_PREFIX_MAP,
+    declaredLookups,
   );
 const verb = (label: string) =>
   verbs().find((v) => verbKey(v.path) === `variable ${label}`) as VerbSpec;

package/src/capabilities/version/version.verb.ts

@@ -15,6 +15,7 @@ const versionVerb: VerbSpec<Record<string, unknown>, string> = {
   path: ["version"],
   summary: "Print the CLI version.",
   doc: "Prints the version `--version` prints — one value, two spellings of the same read.",
+  useWhen: "when asked only for the installed version number",
   params: [],
   output: {
     formatters: {

package/src/capabilities/wireContract.test.ts

@@ -0,0 +1,110 @@
+/**
+ * The wire contract of list-valued parameters, derived from the registry.
+ *
+ * Two recorded failures are the reason this file exists. A weak model asked
+ * for twenty tokens' variables with twenty `variable_list` calls, because over
+ * MCP a filter took ONE value while the CLI took the flag repeated; a stronger
+ * one passed `name: "color.text"` to `token_lookup` and was refused by schema
+ * validation over a pair of brackets. So: every parameter that takes several
+ * values ADVERTISES an array, and accepts one bare value as a list of one.
+ *
+ * Derived rather than listed — a story declared tomorrow is held to the rule
+ * by the act of declaring it.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { z } from "zod";
+import { buildToolShape } from "../kernel/project/mcp/registerVerb.js";
+import { toolName } from "../kernel/spec/index.js";
+import type { ParamSpec, VerbSpec } from "../kernel/spec/types.js";
+import { type McpHarness, projectMcp } from "../testing/helpers/projectMcp.js";
+import { capabilities } from "./index.js";
+
+const exposed: readonly VerbSpec[] = capabilities
+  .flatMap((module) => module.verbs)
+  .filter((verb) => !verb.hidden && verb.capability.mcp.expose !== false);
+
+/** Every `[tool, param]` pair whose param satisfies `test`. */
+function paramsWhere(
+  test: (param: ParamSpec) => boolean,
+): (readonly [string, string, VerbSpec, ParamSpec])[] {
+  return exposed.flatMap((verb) =>
+    verb.params
+      .filter(test)
+      .map((param) => [toolName(verb.path), param.name, verb, param] as const),
+  );
+}
+
+/** One admissible value for a param: its first enum value, else any word. */
+const sample = (param: ParamSpec): string =>
+  param.kind === "enum" ? (param.values.at(0) ?? "") : "anything";
+
+/** Parse ONE field of a tool's input shape, leaving its other params aside. */
+function parseField(verb: VerbSpec, param: ParamSpec, value: unknown) {
+  const field = buildToolShape(verb)[param.name];
+  if (!field) throw new Error(`no "${param.name}" in the tool shape`);
+  return z.object({ [param.name]: field }).safeParse({ [param.name]: value });
+}
+
+const variadic = paramsWhere((param) => param.kind === "string[]");
+const repeatable = paramsWhere(
+  (param) => param.kind !== "string[]" && param.repeatable === true,
+);
+
+describe("a parameter that takes several values takes one, too", () => {
+  it("the registry has both kinds (the derivation is not vacuous)", () => {
+    expect(variadic.length).toBeGreaterThan(0);
+    expect(repeatable.length).toBeGreaterThan(0);
+  });
+
+  it.each(variadic)(
+    "%s { %s }: a bare string is a list of one",
+    (_tool, name, verb, param) => {
+      expect(parseField(verb, param, "color.text")).toEqual({
+        success: true,
+        data: { [name]: ["color.text"] },
+      });
+      expect(parseField(verb, param, ["a", "b"]).success).toBe(true);
+    },
+  );
+
+  it.each(repeatable)(
+    "%s { %s }: an array and a bare string are both accepted",
+    (_tool, name, verb, param) => {
+      const value = sample(param);
+      expect(parseField(verb, param, [value, value]).success).toBe(true);
+      expect(parseField(verb, param, value)).toEqual({
+        success: true,
+        data: { [name]: [value] },
+      });
+    },
+  );
+});
+
+describe("what is advertised is a plain array", () => {
+  let harness: McpHarness;
+  let schemas: Map<string, Record<string, Record<string, unknown>>>;
+  beforeAll(async () => {
+    harness = await projectMcp(capabilities);
+    schemas = new Map(
+      (await harness.listTools()).map((tool) => [
+        tool.name,
+        ((tool.inputSchema as { properties?: unknown }).properties ??
+          {}) as Record<string, Record<string, unknown>>,
+      ]),
+    );
+  });
+  afterAll(() => harness.cleanup());
+
+  // `anyOf` is what a `string | string[]` union would emit, and it is the
+  // shape the weaker models read badly — so the coercion must not leak into
+  // the advertised schema.
+  it.each([...variadic, ...repeatable])(
+    "%s { %s } is `type: array`, never `anyOf`",
+    (tool, name) => {
+      const advertised = schemas.get(tool)?.[name];
+      expect(advertised?.type).toBe("array");
+      expect(advertised).not.toHaveProperty("anyOf");
+    },
+  );
+});

package/src/constants.ts

@@ -61,9 +61,10 @@ const PROJECT_CONFIG_FILENAME = `${identity.name}.config.ts`;
 /**
  * The distribution's name plus a space: the prefix a `recovery.cli` hint carries
  * so it quotes a command the installed binary answers to (D5). Kernel hints are
- * authored through `cliRecovery`, which prepends it; `packs/schema.ts` REJECTS
- * it in a user-authored pack's `emptyRecovery.cli`, because the CONSUMING
- * distribution's renderer supplies its own. Use {@link BIN_NAME} for prose —
+ * authored through `callRecovery`, whose call renderer prepends it; a pack's
+ * `emptyRecovery.call` names a verb path and never a binary (`packs/schema.ts`
+ * rejects a command line there), because the CONSUMING distribution's renderer
+ * supplies its own. Use {@link BIN_NAME} for prose —
  * this constant's trailing space belongs to the recovery invariant, not to
  * sentences.
  */