@canonical/pragma-cli 0.38.0 → 0.42.0

package/src/kernel/project/mcp/prompts/prompts.test.ts

@@ -3,13 +3,16 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { afterEach, describe, expect, it } from "vitest";
-import { CONVENTIONS } from "../../../../capabilities/capabilities/catalog.js";
+import {
+  BLOCKS_SENTENCE,
+  CONVENTIONS,
+} from "../../../../capabilities/capabilities/catalog.js";
 import { capabilities } from "../../../../capabilities/index.js";
 import type { McpHarness } from "../../../../testing/helpers/projectMcp.js";
 import { projectMcp } from "../../../../testing/helpers/projectMcp.js";
 import type { PragmaRuntime } from "../../../runtime/types.js";
-import { emitSurface } from "../../../spec/emitSurface.js";
-import type { CapabilityModule } from "../../../spec/types.js";
+import { emitSurface, toolName } from "../../../spec/emitSurface.js";
+import type { CapabilityModule, VerbSpec } from "../../../spec/types.js";
 import { buildInstructions, INSTRUCTIONS_MAX_CHARS } from "../instructions.js";
 import { fillTemplate, promptProvider } from "./provider.js";
 import { readPrompts } from "./source.js";
@@ -31,21 +34,123 @@ afterEach(async () => {
 });
 
 describe("instructions — handshake orientation (PROTECTED)", () => {
-  it("is present, non-empty, mentions capabilities + the discovery flow", () => {
+  // A client may defer tools: the agent sees tool NAMES and this text, and a
+  // description it never loads cannot steer it. So the text carries a question →
+  // tool index GENERATED from each verb's `useWhen` (it replaced the prose
+  // "discovery sequence" this case used to look for).
+  const reads = capabilities
+    .flatMap((module) => module.verbs)
+    .filter(
+      (verb) =>
+        !verb.hidden && verb.capability.mcp.expose && !verb.capability.mutates,
+    );
+  const isTrio = (verb: VerbSpec): boolean =>
+    ["list", "lookup", "sample"].includes(verb.path[1] ?? "");
+
+  it("indexes every read tool outside a list/lookup/sample trio by the question it answers", () => {
+    const text = buildInstructions(capabilities);
+    const standalone = reads.filter((verb) => !isTrio(verb));
+    expect(standalone.length).toBeGreaterThan(10);
+    for (const verb of standalone) {
+      const clause = (verb.useWhen as string).replace(/^when asked /, "");
+      expect(text).toContain(`${toolName(verb.path)} — ${clause}`);
+    }
+    // The story that failed: asked which components use a token.
+    expect(text).toMatch(/token_consumers — which components use a token/);
+  });
+
+  it("explains the trio once, promising no noun a verb it lacks", () => {
     const text = buildInstructions(capabilities);
-    expect(text.length).toBeGreaterThan(0);
-    expect(text).toContain("capabilities");
-    expect(text.toLowerCase()).toContain("discovery sequence");
+    expect(text.match(/<noun>_list/g)).toHaveLength(1);
+    expect(text).toMatch(/block\*/); // has a sample
+    expect(text).toMatch(/\btier,/); // list + lookup, no sample
+    expect(text).toMatch(/implementation†/); // list only
+  });
+
+  it("is generated: a new read verb adds its own line, a new write joins the plan-first list", () => {
+    const base = capabilities.find((m) => m.name === "info")
+      ?.verbs[0] as VerbSpec;
+    const added: CapabilityModule = {
+      name: "weather",
+      verbs: [
+        {
+          ...base,
+          path: ["weather", "today"],
+          useWhen: "when asked if it rains",
+        },
+        {
+          ...base,
+          path: ["weather", "seed"],
+          capability: { ...base.capability, mutates: true },
+        },
+      ],
+    };
+    const text = buildInstructions([...capabilities, added]);
+    expect(text).toMatch(/^weather_today — if it rains$/m);
+    expect(text).toMatch(/plan-first[^\n]*weather_seed/);
+    expect(buildInstructions([added])).toBe(""); // no module declares an orientation
+  });
+
+  it("fits the HARD ceiling clients cut server instructions at", () => {
+    // Unlike the catalogue budget this is not raised on measurement: text past
+    // about 2 KB is text no agent reads. Tighten a sentence instead.
+    expect(INSTRUCTIONS_MAX_CHARS).toBe(2000);
+    const dropped: number[] = [];
+    const text = buildInstructions(capabilities, (count) =>
+      dropped.push(count),
+    );
+    expect(text.length).toBeLessThanOrEqual(INSTRUCTIONS_MAX_CHARS);
+    // Fitting is the safety net for a project's packs, not for the
+    // distribution: its own registry must fit WHOLE.
+    expect(
+      dropped,
+      "the distribution's own index no longer fits — tighten a useWhen sentence; the 2,000 ceiling is what clients keep",
+    ).toEqual([]);
   });
 
-  it("stays under the length ceiling (cannot bloat)", () => {
-    expect(buildInstructions(capabilities).length).toBeLessThanOrEqual(
-      INSTRUCTIONS_MAX_CHARS,
+  it("when a project's packs overflow it, drops index lines from the end and says so", () => {
+    const base = capabilities.find((m) => m.name === "info")
+      ?.verbs[0] as VerbSpec;
+    const crowd: CapabilityModule = {
+      name: "crowd",
+      verbs: Array.from({ length: 12 }, (_, n) => ({
+        ...base,
+        path: ["crowd", `probe${n}`] as [string, string],
+        category: undefined,
+        useWhen: `when asked a long question number ${n} about the crowd`,
+      })),
+    };
+    const dropped: number[] = [];
+    const text = buildInstructions([...capabilities, crowd], (count) =>
+      dropped.push(count),
+    );
+    expect(text.length).toBeLessThanOrEqual(INSTRUCTIONS_MAX_CHARS);
+    expect(dropped).toHaveLength(1);
+    expect(text.endsWith(`… and ${dropped[0]} more: call capabilities.`)).toBe(
+      true,
     );
+    // What is one line whatever the registry holds is never what gets cut …
+    expect(text).toContain(BLOCKS_SENTENCE);
+    expect(text).toMatch(/plan-first/);
+    expect(text).toMatch(/<noun>_list/);
+    // … and the verbs that read the store lead the index, so they survive.
+    expect(text).toMatch(/^token_consumers — /m);
+  });
+
+  it("emits no heading for an empty group, and skips a verb declaring no useWhen", () => {
+    const base = capabilities.find(
+      (m) => m.name === "capabilities",
+    ) as CapabilityModule;
+    const { useWhen: _useWhen, ...silent } = base.verbs[0] as VerbSpec;
+    const text = buildInstructions([{ ...base, verbs: [silent as VerbSpec] }]);
+    expect(text).not.toContain("When asked:");
+    expect(text).not.toContain("Also:");
+    expect(text).not.toContain("undefined");
   });
 
   it("opens with the shared catalog's conventions, verbatim and once", () => {
-    // The conventions are authored once (capabilities/catalog.ts); instructions
+    // The conventions are authored once (capabilities/catalog.ts) and handed to
+    // the kernel as the module's `mcpOrientation`; instructions
     // must OPEN with them, so a second hand-written preamble cannot creep back
     // in and drift from the `capabilities` tool the same handshake carries.
     expect(buildInstructions(capabilities).startsWith(CONVENTIONS.system)).toBe(
@@ -53,6 +158,17 @@ describe("instructions — handshake orientation (PROTECTED)", () => {
     );
   });
 
+  it("says which tools read components, patterns, layouts and subcomponents", () => {
+    // People ask about "components"; the tools are named for blocks. An agent
+    // that went looking for a component tool found none and fell to raw SPARQL.
+    const text = buildInstructions(capabilities);
+    expect(text).toContain(BLOCKS_SENTENCE);
+    expect(BLOCKS_SENTENCE).toMatch(/components.*block_list/i);
+    // Said in the handshake and in `block_list`'s own description — not a third
+    // time in the catalogue's conventions.
+    expect(Object.values(CONVENTIONS)).not.toContain(BLOCKS_SENTENCE);
+  });
+
   it("quotes the resource templates the MCP surface actually advertises", () => {
     // The `pragma:` scheme is covenant-frozen protocol identity
     // (surface.v2.json). The orientation DERIVES it from the emitted surface
@@ -71,16 +187,16 @@ describe("instructions — handshake orientation (PROTECTED)", () => {
     expect(text).toContain("confirm: true");
   });
 
-  it("orients a cold agent to check/build the store before any store read", () => {
-    // Store-blind guard: the handshake must point a cold agent at the store
-    // pre-check (sources_status → sources_update) BEFORE the sample/query steps,
-    // or it walks straight into STORE_UNAVAILABLE.
+  it("tells an agent which tool explains empty or stale answers, and which rebuilds", () => {
+    // This case used to pin POSITION (`sources_status` before any `_sample`),
+    // from when a cold store failed every read and the text was a numbered
+    // sequence. A fresh install now answers from the shipped snapshot, and the
+    // text is an index whose fixed lines come first so an overflow can only
+    // cut the index. What must still hold: the store check is indexed by the
+    // situation that calls for it, and the rebuild is among the writes.
     const text = buildInstructions(capabilities);
-    const storeCheck = text.indexOf("sources_status");
-    const sample = text.indexOf("_sample");
-    expect(storeCheck).toBeGreaterThanOrEqual(0);
-    expect(text).toContain("sources_update");
-    expect(storeCheck).toBeLessThan(sample);
+    expect(text).toMatch(/^sources_status — when results look empty or stale/m);
+    expect(text).toMatch(/plan-first[^\n]*sources_update/);
   });
 });
 

package/src/kernel/project/mcp/registerVerb.test.ts

@@ -74,6 +74,34 @@ describe("buildZodSchema (params → zod)", () => {
     ).toBe(true);
   });
 
+  it("a list param takes one bare value, and coercion does not skip the item type", () => {
+    const lists = z.object(
+      buildZodSchema([
+        { kind: "string[]", name: "name", doc: "n", required: true },
+        {
+          kind: "enum",
+          name: "kind",
+          doc: "k",
+          values: ["a", "b"],
+          repeatable: true,
+        },
+      ]),
+    );
+    expect(lists.parse({ name: "x", kind: "a" })).toEqual({
+      name: ["x"],
+      kind: ["a"],
+    });
+    expect(lists.parse({ name: ["x", "y"] })).toEqual({ name: ["x", "y"] });
+    expect(lists.safeParse({}).success).toBe(false);
+    expect(lists.safeParse({ name: "x", kind: "z" }).success).toBe(false);
+    expect(lists.safeParse({ name: "x", kind: ["a", 7] }).success).toBe(false);
+    // Only a STRING is coerced, so a wrong type is refused at the param itself.
+    for (const name of [5, { a: 1 }]) {
+      const refused = lists.safeParse({ name });
+      expect(refused.error?.issues.at(0)?.path).toEqual(["name"]);
+    }
+  });
+
   it("applies a declared default when the field is omitted (CLI parity)", () => {
     const withDefault = z.object(
       buildZodSchema([

package/src/kernel/project/mcp/registerVerb.ts

@@ -22,8 +22,10 @@ import { z } from "zod";
 import { asPragmaError } from "../../error/fromTaskError.js";
 import { PragmaError } from "../../error/index.js";
 import type { InteractionRuntime, PragmaRuntime } from "../../runtime/types.js";
+import { describeTool } from "../../spec/guidance.js";
 import type { McpAnnotations, ParamSpec, VerbSpec } from "../../spec/index.js";
 import { toolName } from "../../spec/index.js";
+import { type WireItem, wireType } from "../../spec/wireType.js";
 import { toolError, toolSuccess } from "./envelope.js";
 
 /**
@@ -57,9 +59,9 @@ function resolveEffectiveCwd(rawCwd: unknown, fallback: string): string {
   return rawCwd;
 }
 
-/** The base zod type for a param, before `.describe()`/`.optional()`. */
-function zodForParam(param: ParamSpec): z.ZodTypeAny {
-  switch (param.kind) {
+/** The zod type of ONE value of a param. */
+function zodForItem(item: WireItem): z.ZodTypeAny {
+  switch (item.kind) {
     case "string":
       return z.string();
     case "number":
@@ -67,12 +69,30 @@ function zodForParam(param: ParamSpec): z.ZodTypeAny {
     case "boolean":
       return z.boolean();
     case "enum":
-      return z.enum(param.values as unknown as [string, ...string[]]);
-    case "string[]":
-      return z.array(z.string());
+      return z.enum(item.values as unknown as [string, ...string[]]);
   }
 }
 
+/**
+ * The base zod type for a param, before `.describe()`/`.optional()`, built
+ * from the param's {@link wireType} — the statement the reference prints too.
+ *
+ * A list is ADVERTISED as a plain array and a bare value is COERCED into one
+ * before validation. A preprocess rather than a `string | string[]` union on
+ * purpose: the emitted JSON Schema stays `type: "array"`, where a union emits
+ * `anyOf`, which the weaker models that most need this read badly. The run
+ * bodies already take one value or many, so nothing downstream changes.
+ */
+function zodForParam(param: ParamSpec): z.ZodTypeAny {
+  const wire = wireType(param);
+  const item = zodForItem(wire.item);
+  if (!wire.list) return item;
+  return z.preprocess(
+    (value) => (typeof value === "string" ? [value] : value),
+    z.array(item),
+  );
+}
+
 /**
  * Build the zod input shape for a verb's params.
  *
@@ -152,10 +172,11 @@ function withDetail(
  * `{"ok":true,"data":[],"meta":{}}` — and, later, could not tell an unambiguous
  * lookup hit from one of three blocks sharing a name. Riding in `meta` keeps
  * `data` its uniform shape while making both of those ≠ silence, and the CLI's
- * `--format json` carries the same key so the two surfaces stay byte-equal.
+ * `--format json` carries the same key. The sentence is the ONE place the two
+ * envelopes may differ: a next step inside it is spelled for its surface.
  */
 function noticeMeta(verb: VerbSpec, data: unknown): Record<string, unknown> {
-  const notice = verb.output.formatters.notice?.(data as never);
+  const notice = verb.output.formatters.notice?.(data as never, "mcp");
   // The seam's machine half, merged here so an agent gets the tier scope as
   // DATA (`meta.scope`) and not only as the sentence `notice` carries. The CLI
   // merges the same seam into the same keys (`cli/dispatch.ts#renderData`).
@@ -167,15 +188,22 @@ function noticeMeta(verb: VerbSpec, data: unknown): Record<string, unknown> {
 function readHandler(verb: VerbSpec, runtime: PragmaRuntime) {
   return async (args: Record<string, unknown>): Promise<CallToolResult> => {
     try {
-      if (verb.capability.needsStore) await runtime.store.get();
+      const session = verb.capability.needsStore
+        ? await runtime.store.get()
+        : undefined;
       const params = paramsFromArgs(verb, args);
       const result = await Promise.resolve(
         verb.run(params, withDetail(verb, runtime, args)) as Promise<unknown>,
       );
-      return toolSuccess(
-        JSON.parse(verb.output.formatters.json(result)),
-        noticeMeta(verb, result),
-      );
+      return toolSuccess(JSON.parse(verb.output.formatters.json(result)), {
+        // The store fact this read was answered under, from the session that
+        // answered it: a pack this project built that the boot passed over
+        // because an older CLI built it. The CLI's `--format json` merges the
+        // same key from the same place (`cli/dispatch.ts#storeMeta`), so the
+        // two machine surfaces carry the same fact under the same key.
+        ...(session?.ignoredPack ? { ignoredPack: session.ignoredPack } : {}),
+        ...noticeMeta(verb, result),
+      });
     } catch (error) {
       return toolError(asPragmaError(error));
     }
@@ -297,18 +325,11 @@ function mutateHandler(verb: VerbSpec, runtime: PragmaRuntime) {
 }
 
 /**
- * Register one exposed verb as an MCP tool on the server.
- *
- * @param server - The MCP server to register onto.
- * @param verb - The verb to expose (caller ensures `mcp.expose === true`).
- * @param runtime - The runtime handed to the verb's `run`.
- * @note Impure — mutates the server's tool registry.
+ * The whole input shape a verb's tool accepts: its declared params plus the
+ * arguments the projector injects. Exported so the call rule validates every
+ * example and recovery against the schema an agent's call actually meets.
  */
-export function registerVerb(
-  server: McpServer,
-  verb: VerbSpec,
-  runtime: PragmaRuntime,
-): void {
+export function buildToolShape(verb: VerbSpec): z.ZodRawShape {
   const shape = buildZodSchema(verb.params);
   // A verb with progressive disclosure gains a `detail` enum param derived from
   // its DisclosureSpec (Risk2 — NO new VerbSpec field). The handler seeds
@@ -337,17 +358,34 @@ export function registerVerb(
         "Absolute project directory to write into; defaults to the server's working directory.",
       );
   }
+  return shape;
+}
+
+/**
+ * Register one exposed verb as an MCP tool on the server.
+ *
+ * @param server - The MCP server to register onto.
+ * @param verb - The verb to expose (caller ensures `mcp.expose === true`).
+ * @param runtime - The runtime handed to the verb's `run`.
+ * @note Impure — mutates the server's tool registry.
+ */
+export function registerVerb(
+  server: McpServer,
+  verb: VerbSpec,
+  runtime: PragmaRuntime,
+): void {
+  const shape = buildToolShape(verb);
 
   const config: {
     description: string;
     inputSchema?: z.ZodRawShape;
     annotations: McpAnnotations;
   } = {
-    // The agent-facing tool description is the verb's richer `doc` when present
-    // (pack `toolDescription`s compile into it; hand-written verbs author it
-    // directly), falling back to the one-line `summary`. Tool descriptions are
-    // NOT part of the frozen surface, so this stays covenant-safe.
-    description: verb.doc ?? verb.summary,
+    // Generated, never typed: the question the verb answers, its richer `doc`
+    // (pack `toolDescription`s compile into it) or one-line `summary`, and one
+    // example call. Tool descriptions are NOT part of the frozen surface, so
+    // this stays covenant-safe.
+    description: describeTool(verb),
     annotations: annotationsFor(verb),
   };
   if (Object.keys(shape).length > 0) config.inputSchema = shape;

package/src/kernel/render/__snapshots__/renderers.test.ts.snap

@@ -17,7 +17,7 @@ Active filters:
 Valid options: stable, beta",
   },
   "notFound": {
-    "json": "{"ok":false,"error":{"code":"ENTITY_NOT_FOUND","message":"block \\"Buton\\" not found.","suggestions":["Button"],"recovery":{"message":"List available blocks.","cli":"pragma block list"}}}",
+    "json": "{"ok":false,"error":{"code":"ENTITY_NOT_FOUND","message":"block \\"Buton\\" not found.","suggestions":["Button"],"recovery":{"message":"List available blocks.","cli":"pragma block list","mcp":{"tool":"block_list","params":{}}}}}",
     "llm": "## Error: ENTITY_NOT_FOUND
 block "Buton" not found.
 Suggestions: Button

package/src/kernel/render/renderers.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { PragmaError } from "../error/PragmaError.js";
-import { cliRecovery } from "../error/recovery.js";
+import { callRecovery } from "../error/recovery.js";
 import {
   renderErrorJson,
   renderErrorLlm,
@@ -293,7 +293,7 @@ describe("error render matrix (× plain/llm/json)", () => {
   it("renders each error across the three formats", () => {
     const notFound = PragmaError.notFound("block", "Buton", {
       suggestions: ["Button"],
-      recovery: cliRecovery("block list", "List available blocks."),
+      recovery: callRecovery({ verb: "block list" }, "List available blocks."),
     });
     const empty = PragmaError.emptyResults("token", {
       filters: { channel: "stable", tier: "core" },

package/src/kernel/render/renderers.ts

@@ -201,9 +201,9 @@ function renderHeaderRow<T>(
  *
  * The SCOPE is in the heading for the same reason, and it is the more serious
  * of the two omissions: a truncated page at least ends where it ends, while a
- * scoped read looks exactly like a complete one. `## Block (175, tier scope:
- * global, apps, documentation, sites, stores)` says which part of the design
- * system the 175 are, in the words `--tier` accepts.
+ * scoped read looks exactly like a complete one. `## Block (176, tier scope:
+ * global 121, apps 39, …)` says which part of the design system the 176 are,
+ * in the words `--tier` accepts. The caller composes that text.
  *
  * @param items - The rows on this page.
  * @param options - Columns and empty-state copy.

package/src/kernel/render/turtle.ts

@@ -30,6 +30,7 @@ import type {
   InboundGroup,
   InspectResult,
   NestedRecord,
+  PredicateGroup,
   ReadTerm,
 } from "../runtime/readEntity.js";
 
@@ -120,6 +121,13 @@ function truncationNote(predicate: string, term: ReadTerm): string | undefined {
   return `  # ${predicate} — ${total} chars, showing ${term.value.length}`;
 }
 
+/** `# ds:hasTokenBinding — 24 objects, showing 10` — a cut group, stated as one. */
+function cutNote(group: PredicateGroup): string | undefined {
+  if (!group.truncated || group.count === undefined) return undefined;
+  const total = group.count.toLocaleString("en-US");
+  return `  # ${renderTerm(group.predicate)} — ${total} objects, showing ${group.objects.length}`;
+}
+
 /** Render one inlined blank node as a Turtle `[ … ]` record. */
 function renderNested(record: NestedRecord): string {
   const fields = Object.entries(record).map(([field, value]) => {
@@ -188,21 +196,33 @@ export function toTurtle(
     // Blank objects are written as their inlined records instead, so they are
     // skipped here — emitting both would assert the same edge twice.
     const objects = group.objects.filter((o) => o.termType !== "BlankNode");
+    // A group of blank objects is written further down, as its records — and
+    // says there that it was cut.
     if (objects.length === 0) continue;
     const keyword = predicate === "rdf:type" ? "a" : predicate;
     // Notes are folded INTO the element, above its statement, so the `;` the
     // join appends always lands on the statement line. Pushed as siblings they
     // would each take a separator of their own — into a comment, which runs to
     // end of line and eats it.
-    const notes = objects
-      .map((o) => truncationNote(keyword, o))
-      .filter((n): n is string => n !== undefined);
+    const notes = [
+      cutNote(group),
+      ...objects.map((o) => truncationNote(keyword, o)),
+    ].filter((n): n is string => n !== undefined);
     const rendered = objects.map(renderTerm).join(", ");
     predicates.push([...notes, `  ${keyword} ${rendered}`].join("\n"));
   }
   for (const [via, records] of Object.entries(result.nested)) {
+    const group = result.groups.find(
+      (g) => (g.predicate.prefixed ?? g.predicate.value) === via,
+    );
+    const hasNamed = group?.objects.some((o) => o.termType !== "BlankNode");
+    // Said once per predicate: a group with named objects too said it above.
+    const note = group && !hasNamed ? cutNote(group) : undefined;
     predicates.push(
-      `  ${via}\n    ${records.map(renderNested).join(",\n    ")}`,
+      [
+        ...(note ? [note] : []),
+        `  ${via}\n    ${records.map(renderNested).join(",\n    ")}`,
+      ].join("\n"),
     );
   }
   if (predicates.length > 0) {

package/src/kernel/runtime/graphpack/build.ts

@@ -29,6 +29,7 @@ import {
   createStoreQueryFn,
   serializeExtraction,
 } from "@canonical/ke-graphql";
+import { packIsOlderThanCli } from "../packVersion.js";
 import { packDir, packsCacheDir } from "../paths.js";
 import { buildIndex } from "./buildIndex.js";
 import { contentHash, hashSources } from "./hash.js";
@@ -53,6 +54,7 @@ export interface BuildPackInput {
 /** Provenance and options for a pack build. */
 export interface BuildPackOptions {
   readonly name: string;
+  /** The building CLI's version, recorded in the manifest (see `Manifest`). */
   readonly version: string;
   /** The config `packs` ref (verbatim) or a label. */
   readonly sourceRef: string;
@@ -104,7 +106,12 @@ export async function buildPack(
   if (packIsComplete(dir)) {
     const cached = readManifest(dir);
     if (cached)
-      return { dir, contentHash: hash, manifest: cached, reused: true };
+      return {
+        dir,
+        contentHash: hash,
+        manifest: stampBuilderVersion(dir, cached, options.version),
+        reused: true,
+      };
   }
 
   mkdirSync(packsCacheDir(), { recursive: true });
@@ -185,6 +192,56 @@ export async function buildPack(
   }
 }
 
+/**
+ * Refresh a REUSED pack's recorded builder version to the CLI doing the reuse.
+ *
+ * Without this, `sources update` could not get a project out of the state the
+ * boot decision's upgrade row describes. A pack is content-addressed, so an
+ * update whose sources have not moved resolves to the same hash and reuses the
+ * directory untouched — manifest and all. The manifest would therefore keep
+ * naming the OLD CLI as its builder, the boot would go on passing the pack over,
+ * and the `pragma sources update` the notice recommends would change nothing:
+ * a loop with no way out but `sources reset`.
+ *
+ * Only the version moves. `createdAt` and `sourceRef` describe the build that
+ * produced these bytes and stay as they were — a reuse is not a new build, and
+ * `sources status` reporting today's date for a pack from last month would be
+ * the same kind of lie in the other direction. What the stamp claims is exactly
+ * what happened: THIS CLI resolved these sources and found this pack already
+ * holding what it would have built.
+ *
+ * Best-effort, and deliberately so: the write is a provenance refresh, not part
+ * of the build, so a read-only or racing cache returns the manifest as found
+ * rather than failing an update that otherwise succeeded (the user keeps the
+ * notice, which is recoverable, instead of losing the update, which is worse).
+ *
+ * @param dir - The reused pack directory.
+ * @param cached - Its manifest, as read.
+ * @param version - The running CLI's version.
+ * @returns The manifest as it now stands on disk.
+ * @note Impure — rewrites `manifest.json` in place (temp file + atomic rename,
+ *   so the completeness marker is never observed half-written).
+ */
+function stampBuilderVersion(
+  dir: string,
+  cached: Manifest,
+  version: string,
+): Manifest {
+  // Upward only: the cache directory is shared by every project built from the
+  // same sources, so an older (or dev) CLI reusing it must not make a newer
+  // CLI start passing the pack over.
+  if (!packIsOlderThanCli(cached.version, version)) return cached;
+  const stamped: Manifest = { ...cached, version };
+  try {
+    const temp = join(dir, `.manifest-${process.pid}.json`);
+    writeFileSync(temp, JSON.stringify(stamped));
+    renameSync(temp, join(dir, MANIFEST_FILE));
+    return stamped;
+  } catch {
+    return cached;
+  }
+}
+
 /**
  * Count a store's triples (a cheap aggregate over the union graph).
  *

package/src/kernel/runtime/graphpack/graphpack.test.ts

@@ -445,3 +445,23 @@ describe("graphpack read — incomplete pack recovery (CLI + MCP)", () => {
     }
   });
 });
+
+describe("the builder version recorded on reuse", () => {
+  const stampedBy = async (version: string) =>
+    (
+      await buildPack([{ path: "stamp.ttl", content: `${TTL}\n# stamp` }], {
+        name: "test-pack",
+        version,
+        sourceRef: "test:inline",
+        prefixes: PREFIXES,
+      })
+    ).manifest.version;
+
+  it("moves up to a newer CLI and never down to an older one", async () => {
+    expect(await stampedBy("2.2.0")).toBe("2.2.0");
+    // The cache directory is shared between projects, so an older CLI reusing
+    // it must leave the record alone.
+    expect(await stampedBy("2.1.0")).toBe("2.2.0");
+    expect(await stampedBy("2.3.0")).toBe("2.3.0");
+  });
+});

package/src/kernel/runtime/graphpack/manifest.ts

@@ -108,6 +108,21 @@ export function readManifest(dir: string): Manifest | undefined {
  * — see {@link storiesAreReadable} for why it, and only it, is parsed here. */
 export function packIsComplete(dir: string): boolean {
   if (readManifest(dir) === undefined) return false;
+  return packArtifactsPresent(dir);
+}
+
+/**
+ * The second half of {@link packIsComplete}: every non-manifest artifact,
+ * present and usable. Exported so a caller that ALREADY holds the manifest can
+ * finish the completeness check without reading the file twice —
+ * {@link resolveSources} is one, because it now reads the manifest's recorded
+ * builder version as part of the boot decision.
+ *
+ * @param dir - The pack directory.
+ * @returns Whether the four content artifacts are present and readable.
+ * @note Impure — stats (and, for stories, parses) the pack's files.
+ */
+export function packArtifactsPresent(dir: string): boolean {
   for (const file of [DATA_FILE, SCHEMA_FILE, INDEX_FILE, STORIES_FILE]) {
     try {
       if (statSync(join(dir, file)).size <= 0) return false;

package/src/kernel/runtime/graphpack/read.ts

@@ -16,7 +16,8 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createStore } from "@canonical/ke";
 import { compileFromExtraction } from "@canonical/ke-graphql";
-import { cliRecovery, PragmaError } from "../../error/index.js";
+import { callRecovery, PragmaError } from "../../error/index.js";
+import { BUILD_STORE_CALL } from "../../spec/call.js";
 import type { StoreSession } from "../types.js";
 import { readManifest } from "./manifest.js";
 import { packIndexSchema } from "./schemas.js";
@@ -25,12 +26,9 @@ import { DATA_FILE, INDEX_FILE, SCHEMA_FILE } from "./types.js";
 /** STORE_UNAVAILABLE with the canonical `pragma sources update` recovery (CLI + MCP). */
 function packUnavailable(reason: string): PragmaError {
   return PragmaError.storeUnavailable(reason, {
-    recovery: cliRecovery(
-      "sources update",
+    recovery: callRecovery(
+      BUILD_STORE_CALL,
       "Rebuild the local store from the configured packs.",
-      // An agent recovers by calling the tool, then retrying (PR9 C1 cold-store
-      // retry makes the post-update retry succeed).
-      { tool: "sources_update" },
     ),
   });
 }