@canonical/pragma-cli 0.32.0 → 0.33.0

package/src/capabilities/sources/runUpdate.ts

@@ -46,6 +46,7 @@ import {
   redactUrl,
 } from "../../kernel/runtime/refs/parseRef.js";
 import {
+  detectPrefixClashes,
   harvestPrefixes,
   type ResolvedPackage,
   resolvePackage,
@@ -172,11 +173,41 @@ export async function buildUpdateTask(
   // token contract); config still wins any clash. The merged map is persisted
   // in the manifest, so boot reads the same names.
   const inputs = resolved.flatMap((pkg) => pkg.sources);
+
+  // Refuse to lock an empty store (A4). A package that ships no `.ttl` (or no
+  // configured packages at all) would build a 0-triple pack whose empty
+  // `data.nq` fails the completeness gate — so the "successful" update boots to
+  // a PERMANENT `STORE_UNAVAILABLE` loop. Fail loudly here, leaving the embedded
+  // fallback (or the prior lock) intact, instead of writing that broken lock.
+  if (inputs.length === 0) {
+    throw PragmaError.configError(
+      entries.length === 0
+        ? "No packages are configured, so there are no sources to build a store from. The embedded sample pack answers reads until you add a package."
+        : `The ${entries.length} configured package(s) resolved 0 RDF sources (no definitions/**.ttl or data/**.ttl). Refusing to write a lock for an empty store.`,
+      {
+        recovery: cliRecovery(
+          `${RECOVERY_CLI_PREFIX}sources update --verbose`,
+          "Add a package that ships `.ttl` under definitions/ or data/, then re-run.",
+        ),
+      },
+    );
+  }
+
   const prefixes = {
     ...CORE_PREFIXES,
     ...harvestPrefixes(inputs),
     ...(layers.config.prefixes ?? {}),
   };
+
+  // Warn on conflicting `@prefix` declarations across packages (A5): last-wins
+  // is silent otherwise, compacting the losing package's URIs to the wrong
+  // prefix. Display-only, so a warning (not a hard failure) is the right call.
+  for (const clash of detectPrefixClashes(inputs)) {
+    report?.(
+      `Prefix "${clash.label}:" is declared with conflicting IRIs across packages (${clash.iris.join(" vs ")}); last wins, so some entities may compact to the wrong prefix.`,
+    );
+  }
+
   report?.(`Building store from ${inputs.length} source(s)`);
   if (verbose) for (const input of inputs) report?.(`  parse ${input.path}`);
 
@@ -239,17 +270,43 @@ export async function buildUpdateTask(
     `${built.reused ? "Reused" : "Built"} store ${built.contentHash.slice(0, 12)}`,
   );
 
+  // Refuse to lock a 0-triple build (A4): non-empty sources can still parse to
+  // no triples (e.g. comment-only TTL, or a file of only `@prefix` lines). A
+  // locked empty pack boots to the same `STORE_UNAVAILABLE` loop, so treat it
+  // as a data error rather than a silent "success". (A manifest predating the
+  // triple count is left alone — `undefined` never trips this.)
+  if (built.manifest.tripleCount === 0) {
+    throw PragmaError.configError(
+      `The configured sources parsed to 0 RDF triples, so the store would be empty. Refusing to write a lock for an empty store.`,
+      {
+        recovery: cliRecovery(
+          `${RECOVERY_CLI_PREFIX}sources update --verbose`,
+          "Check that the package sources actually contain RDF triples, then re-run.",
+        ),
+      },
+    );
+  }
+
   const now = new Date().toISOString();
   const lock: PragmaLock = {
     version: 1,
     contentHash: built.contentHash,
     packs: resolved.map((pkg) => {
       const prev = existing?.packs.find((entry) => entry.name === pkg.name);
+      // Preserve the prior `resolvedAt` when nothing actually changed — under
+      // --frozen (re-pinned to the same revision) AND on a plain re-run that
+      // resolves the IDENTICAL revision from the same source. Otherwise every
+      // `sources update` stamped a fresh timestamp and rewrote the lock, dirtying
+      // the git tree on a no-op run (L1). A moved revision still restamps.
+      const reproducible =
+        prev !== undefined &&
+        (frozen ||
+          (prev.resolved === pkg.resolved && prev.source === pkg.source));
       return {
         name: pkg.name,
         source: pkg.source,
         resolved: pkg.resolved,
-        resolvedAt: frozen && prev ? prev.resolvedAt : now,
+        resolvedAt: reproducible && prev ? prev.resolvedAt : now,
       };
     }),
   };

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

@@ -5,6 +5,7 @@ import {
   mkdtempSync,
   readFileSync,
   rmSync,
+  symlinkSync,
   writeFileSync,
 } from "node:fs";
 import type { createRequire } from "node:module";
@@ -20,12 +21,16 @@ import { bootRuntime } from "../../kernel/runtime/boot.js";
 import { createQueryFacade } from "../../kernel/runtime/facade.js";
 import { readLock } from "../../kernel/runtime/lock.js";
 import { lockPath, packDir } from "../../kernel/runtime/paths.js";
-import { resolvePackageJson } from "../../kernel/runtime/refs/resolve.js";
+import {
+  detectPrefixClashes,
+  resolvePackageJson,
+} from "../../kernel/runtime/refs/resolve.js";
 import { createLazyStore } from "../../kernel/runtime/store.js";
 import type { GlobalFlags, PragmaRuntime } from "../../kernel/runtime/types.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
 import { discoverSkills } from "../skill/discover.js";
+import { collectStatus } from "./collectStatus.js";
 import { sourcesModule } from "./index.js";
 import { buildUpdateTask } from "./runUpdate.js";
 
@@ -153,6 +158,60 @@ describe("sources lock round-trip (PROTECTED)", () => {
     expect(readFileSync(lockPath(cwd), "utf-8")).toBe(firstBytes);
   });
 
+  it("a non-frozen re-run over an unchanged source rewrites a byte-identical lock (L1)", async () => {
+    // On base, every non-frozen update stamped a fresh `resolvedAt`, so a no-op
+    // re-run dirtied the tree. When the revision is unchanged the timestamp is
+    // preserved, so the lock is byte-identical.
+    const pkg = filePackage();
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+    await runTask(await buildUpdateTask(runtime, false));
+    const firstBytes = readFileSync(lockPath(cwd), "utf-8");
+    await runTask(await buildUpdateTask(runtime, false));
+    expect(readFileSync(lockPath(cwd), "utf-8")).toBe(firstBytes);
+  });
+
+  it("follows a symlinked .ttl into the build (L6)", async () => {
+    // pnpm / workspace trees symlink their sources; Dirent.isFile is false for a
+    // symlink, so on base the only `.ttl` was skipped → 0 sources → the empty
+    // build. Following the link ingests it and the build+lock succeed.
+    const pkg = tmp("pragma-symlink-pkg-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    const realTtl = join(pkg, "real.ttl");
+    writeFileSync(realTtl, TTL);
+    symlinkSync(realTtl, join(pkg, "definitions", "linked.ttl"));
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+
+    const result = await runTask(await buildUpdateTask(runtime, false));
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(readLock(cwd)?.packs).toHaveLength(1);
+  });
+
+  it("does not recurse into a symlinked directory cycle (L6 safety)", async () => {
+    // The L6 fix follows symlinked FILES but must NOT recurse into a symlinked
+    // DIRECTORY: a link to an ancestor dir is a cycle that, if walked, recurses
+    // without bound → a stack-overflow RangeError (an INTERNAL "please report").
+    // The real `.ttl` is still ingested and the build completes.
+    const pkg = tmp("pragma-symlink-cycle-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    writeFileSync(join(pkg, "definitions", "widget.ttl"), TTL);
+    // `definitions/loop` → `definitions` (its own parent): a symlink cycle.
+    symlinkSync(join(pkg, "definitions"), join(pkg, "definitions", "loop"));
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+
+    const result = await runTask(await buildUpdateTask(runtime, false));
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(readLock(cwd)?.packs).toHaveLength(1);
+  });
+
   it("undo restores the prior lock (no prior → removed)", async () => {
     const pkg = filePackage();
     const cwd = tmp("pragma-proj-");
@@ -200,6 +259,114 @@ describe("sources update — package-declared prefixes (M1)", () => {
   });
 });
 
+describe("sources update — refuses an empty store (A4)", () => {
+  /** A local package that ships NO `.ttl` (an empty definitions directory). */
+  function emptyPackage(): string {
+    const pkg = tmp("pragma-empty-pkg-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    return pkg;
+  }
+
+  it("a package with no .ttl is refused, and no lock is written", async () => {
+    // On base this builds a 0-triple pack whose empty data.nq fails the
+    // completeness gate — so the "successful" update boots to a PERMANENT
+    // STORE_UNAVAILABLE loop. The fix refuses before writing the lock.
+    const pkg = emptyPackage();
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+
+    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
+      code: "CONFIG_ERROR",
+    });
+    // No lock → the embedded fallback / prior state survives, no boot loop.
+    expect(readLock(cwd)).toBeUndefined();
+  });
+
+  it("no configured packages is refused rather than locking an empty pack", async () => {
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, []);
+    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
+      code: "CONFIG_ERROR",
+    });
+    expect(readLock(cwd)).toBeUndefined();
+  });
+
+  it("a comment-only .ttl (0 triples) is refused too", async () => {
+    const pkg = tmp("pragma-noTriples-pkg-");
+    mkdirSync(join(pkg, "definitions"), { recursive: true });
+    // Parses fine, but yields no triples — the post-build 0-triple guard.
+    writeFileSync(
+      join(pkg, "definitions", "empty.ttl"),
+      "# only a comment, no triples\n",
+    );
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+    await expect(buildUpdateTask(runtime, false)).rejects.toMatchObject({
+      code: "CONFIG_ERROR",
+    });
+    expect(readLock(cwd)).toBeUndefined();
+  });
+});
+
+describe("sources update — conflicting @prefix detection (A5)", () => {
+  it("flags a label bound to two different IRIs across packages", () => {
+    const clashes = detectPrefixClashes([
+      { content: "@prefix ex: <https://a.test/#> .\nex:One a ex:T ." },
+      { content: "@prefix ex: <https://b.test/#> .\nex:Two a ex:T ." },
+    ]);
+    expect(clashes).toHaveLength(1);
+    expect(clashes.at(0)?.label).toBe("ex");
+    expect(clashes.at(0)?.iris).toEqual([
+      "https://a.test/#",
+      "https://b.test/#",
+    ]);
+  });
+
+  it("does NOT flag harmless same-label/same-IRI redeclarations", () => {
+    const clashes = detectPrefixClashes([
+      { content: "@prefix ex: <https://a.test/#> .\nex:One a ex:T ." },
+      { content: "@prefix ex: <https://a.test/#> .\nex:Two a ex:T ." },
+    ]);
+    expect(clashes).toEqual([]);
+  });
+
+  it("warns loudly on a cross-package prefix clash during update", async () => {
+    const owl = "@prefix owl: <http://www.w3.org/2002/07/owl#> .\n";
+    const pkgA = tmp("pragma-clash-a-");
+    mkdirSync(join(pkgA, "definitions"), { recursive: true });
+    writeFileSync(
+      join(pkgA, "definitions", "a.ttl"),
+      `@prefix ex: <https://a.test/#> .\n${owl}ex:Thing a owl:Class .\nex:one a ex:Thing .\n`,
+    );
+    const pkgB = tmp("pragma-clash-b-");
+    mkdirSync(join(pkgB, "definitions"), { recursive: true });
+    writeFileSync(
+      join(pkgB, "definitions", "b.ttl"),
+      `@prefix ex: <https://b.test/#> .\n${owl}ex:Widget a owl:Class .\nex:two a ex:Widget .\n`,
+    );
+    const cwd = tmp("pragma-proj-");
+    const reports: string[] = [];
+    const runtime: PragmaRuntime = {
+      ...runtimeFor(cwd, [
+        { name: "pkg-a", source: `file://${pkgA}` },
+        { name: "pkg-b", source: `file://${pkgB}` },
+      ]),
+      report: (message: string) => reports.push(message),
+    };
+
+    await runTask(await buildUpdateTask(runtime, false));
+    expect(
+      reports.some(
+        (r) => r.includes('Prefix "ex:"') && r.includes("conflicting"),
+      ),
+    ).toBe(true);
+  });
+});
+
 describe("sources update — network-free preview (M2)", () => {
   const updateVerb = sourcesModule.verbs[1] as VerbSpec;
   const DRY_RUN = { dryRun: true, undo: false, yes: false };
@@ -615,6 +782,25 @@ describe("sources update — installs package skills (U10)", () => {
   });
 });
 
+describe("sources status — entityCount from the manifest (A10)", () => {
+  it("reports the count without re-parsing index.json", async () => {
+    const pkg = filePackage(); // ex:Widget class + ex:one individual
+    const cwd = tmp("pragma-proj-");
+    const runtime = runtimeFor(cwd, [
+      { name: "pkg-a", source: `file://${pkg}` },
+    ]);
+    const result = await runTask(await buildUpdateTask(runtime, false));
+
+    // Delete index.json: any path that PARSED it to count would now fail —
+    // proving the figure is read from the manifest's persisted entityCount.
+    rmSync(join(packDir(result.contentHash), "index.json"), { force: true });
+
+    const status = await collectStatus(bootRuntime(flagsJson, cwd));
+    // One abox individual (ex:one); the ex:Widget class is tbox, not counted.
+    expect(status.entityCount).toBe(1);
+  });
+});
+
 describe("sources status CLI-json == MCP tool (PROTECTED)", () => {
   it("a cold store's status is byte-equal on both surfaces", async () => {
     // Both surfaces boot from the SAME cwd + isolated config (default packages,

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

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { type RenderStyle, styleFor } from "../../kernel/render/style.js";
+import { renderSourcesStatusPlain } from "./status.render.js";
+import type { SourcesStatusData } from "./types.js";
+
+const DATA: SourcesStatusData = {
+  cwd: "/repo",
+  lockPresent: true,
+  contentHash: "abcdef012345aaaa",
+  cached: true,
+  builtAt: "2026-01-01",
+  entityCount: 42,
+  sources: [
+    {
+      name: "ds",
+      ref: "ds@1",
+      resolved: "1111111111112222",
+      staleness: "up-to-date",
+    },
+    {
+      name: "extra",
+      ref: "extra@1",
+      resolved: null,
+      staleness: "config-drift",
+    },
+  ],
+};
+
+/** A sentinel styler — enabled, each color wrapped in a visible tag. */
+const TAGGED: RenderStyle = {
+  enabled: true,
+  bold: (t) => `<b>${t}</b>`,
+  dim: (t) => `<d>${t}</d>`,
+  cyan: (t) => `<c>${t}</c>`,
+  green: (t) => `<g>${t}</g>`,
+  yellow: (t) => `<y>${t}</y>`,
+};
+
+describe("renderSourcesStatusPlain", () => {
+  it("is byte-identical to the plain form when the styler is disabled", () => {
+    expect(renderSourcesStatusPlain(DATA, styleFor(false))).toBe(
+      [
+        "Store: ready",
+        "  pack: abcdef012345 — 42 entities, built 2026-01-01",
+        "",
+        "Sources:",
+        "  ds [ok] @ 111111111111",
+        "  extra [config drift]",
+      ].join("\n"),
+    );
+  });
+
+  it("bolds the heading, aligns names, and tints markers on a TTY", () => {
+    const out = renderSourcesStatusPlain(DATA, TAGGED);
+    const nameWidth = "extra".length;
+    expect(out).toContain("<b>Sources:</b>");
+    // up-to-date tints green with a dim resolved suffix; drift tints yellow.
+    expect(out).toContain(
+      `  ${"ds".padEnd(nameWidth)}  <g>[ok]</g><d> @ 111111111111</d>`,
+    );
+    expect(out).toContain(
+      `  ${"extra".padEnd(nameWidth)}  <y>[config drift]</y>`,
+    );
+  });
+});

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

@@ -2,6 +2,7 @@
  * Formatters for `pragma sources status` — plain, llm, json.
  */
 
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
 import type { Formatters } from "../../kernel/spec/types.js";
 import type { SourcesStatusData } from "./types.js";
 
@@ -11,31 +12,57 @@ const STALENESS_MARK: Record<string, string> = {
   uncached: "not built",
 };
 
+/**
+ * Render `sources status` as plain text.
+ *
+ * @param data - The resolved sources-status payload.
+ * @param style - TTY styling; defaults to the process style. On a color-capable
+ *   terminal the `Sources:` heading is bold, source names align into a column,
+ *   and each staleness marker is tinted (green up-to-date, else yellow); off a
+ *   TTY the styler is inert, so the output is byte-identical to the plain form.
+ * @returns The formatted status block.
+ */
+export function renderSourcesStatusPlain(
+  data: SourcesStatusData,
+  style: RenderStyle = defaultStyle(),
+): string {
+  const lines = [
+    data.lockPresent
+      ? `Store: ${data.cached ? "ready" : "locked but not cached"}`
+      : "Store: no lock (run `pragma sources update`)",
+  ];
+  if (data.cached) {
+    lines.push(
+      `  pack: ${data.contentHash?.slice(0, 12)} — ${data.entityCount ?? "?"} entities, built ${data.builtAt ?? "?"}`,
+    );
+  }
+  lines.push("", style.enabled ? style.bold("Sources:") : "Sources:");
+  if (data.sources.length === 0) {
+    lines.push("  (none configured)");
+  }
+  const nameWidth = style.enabled
+    ? Math.max(0, ...data.sources.map((source) => source.name.length))
+    : 0;
+  for (const source of data.sources) {
+    const mark = STALENESS_MARK[source.staleness] ?? source.staleness;
+    const resolved = source.resolved
+      ? ` @ ${source.resolved.slice(0, 12)}`
+      : "";
+    if (!style.enabled) {
+      lines.push(`  ${source.name} [${mark}]${resolved}`);
+      continue;
+    }
+    const tint = source.staleness === "up-to-date" ? style.green : style.yellow;
+    lines.push(
+      `  ${source.name.padEnd(nameWidth)}  ${tint(`[${mark}]`)}${style.dim(resolved)}`,
+    );
+  }
+  return lines.join("\n");
+}
+
 export const statusFormatters: Formatters<SourcesStatusData> = {
   plain(data) {
-    const lines = [
-      data.lockPresent
-        ? `Store: ${data.cached ? "ready" : "locked but not cached"}`
-        : "Store: no lock (run `pragma sources update`)",
-    ];
-    if (data.cached) {
-      lines.push(
-        `  pack: ${data.contentHash?.slice(0, 12)} — ${data.entityCount ?? "?"} entities, built ${data.builtAt ?? "?"}`,
-      );
-    }
-    lines.push("", "Sources:");
-    if (data.sources.length === 0) {
-      lines.push("  (none configured)");
-    }
-    for (const source of data.sources) {
-      const resolved = source.resolved
-        ? ` @ ${source.resolved.slice(0, 12)}`
-        : "";
-      lines.push(
-        `  ${source.name} [${STALENESS_MARK[source.staleness]}]${resolved}`,
-      );
-    }
-    return lines.join("\n");
+    return renderSourcesStatusPlain(data);
   },
 
   llm(data) {

package/src/capabilities/surface.test.ts

@@ -23,12 +23,11 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
     expect(() => assertConforms(emitted, golden)).not.toThrow();
   });
 
-  it("emits config show + the PR6 setters + the PR9 additive set, in covenant order", () => {
+  it("emits config show + the one-command config set, in covenant order (field-verbs retired, B3)", () => {
+    // AV-228 B3 retired the per-field `tier`/`channel`/`detail` setters; the
+    // config noun is now just the `show` reader and the `set <key> <value>` writer.
     expect(emitted.nouns.config?.verbs).toEqual([
       { v: "show", mcp: "config_show" },
-      { v: "tier", args: ["<path>"], mutates: true, mcp: "config_tier" },
-      { v: "channel", args: ["<name>"], mutates: true, mcp: "config_channel" },
-      { v: "detail", args: ["<level>"], mutates: true, mcp: "config_detail" },
       {
         v: "set",
         args: ["<key>", "<value>"],
@@ -95,6 +94,15 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
   it("emits the authored read nouns (ontology TBox, storeless skill, graph inspect)", () => {
     expect(emitted.nouns.ontology?.verbs).toEqual([
       { v: "list", needsStore: true, mcp: "ontology_list" },
+      {
+        v: "lookup",
+        args: ["<prefix>"],
+        flags: ["--properties", "--full-uris", "--class"],
+        needsStore: true,
+        mcp: "ontology_lookup",
+      },
+      // `show` is the deprecated alias of `lookup` (AV-228 B1) — same shape,
+      // both blessed in the covenant.
       {
         v: "show",
         args: ["<prefix>"],
@@ -146,11 +154,28 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
   it("emits setup as a mixed self+sub noun (self is a tool, sub-verbs are mcp:false)", () => {
     // The one covenant noun both directly runnable AND with sub-verbs. The self
     // verb is the `setup` tool; the four installers are CLI-only (mcp:false).
+    // The band-aware verbs (setup/mcp/skills) carry the --scope/--global/--local
+    // flags; completions/lsp are single-band installers with no scope.
     expect(emitted.nouns.setup?.verbs).toEqual([
-      { v: "setup", mutates: true, mcp: "setup" },
-      { v: "mcp", mutates: true, mcp: false },
+      {
+        v: "setup",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: "setup",
+      },
+      {
+        v: "mcp",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
       { v: "completions", mutates: true, mcp: false },
-      { v: "skills", mutates: true, mcp: false },
+      {
+        v: "skills",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
       { v: "lsp", mutates: true, mcp: false },
     ]);
   });
@@ -184,14 +209,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 40) — set equality with the covenant", () => {
+  it("emits every covenant tool (all 38) — 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(40);
+    expect(emitted.mcpSurface.tools).toHaveLength(38);
   });
 
   // The covenant edit: the non-tool MCP surface is frozen too.

package/src/capabilities/tier/lookup.render.test.ts

@@ -0,0 +1,72 @@
+import chalk from "chalk";
+import { afterEach, describe, expect, it } from "vitest";
+import { type TierLookupData, tierLookupFormatters } from "./lookup.render.js";
+
+const TIER: TierLookupData = {
+  uri: "cs:apps/lxd-panel",
+  name: "apps/lxd-panel",
+  blocks: ["LXD Panel", "Status Bar"],
+};
+
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+describe("tierLookupFormatters", () => {
+  it("underlines the plain title with an ═ rule (B7)", () => {
+    const [title, rule, blank, blocks] = tierLookupFormatters
+      .plain(TIER)
+      .split("\n");
+    expect(title).toBe("apps/lxd-panel (cs:apps/lxd-panel)");
+    expect(rule).toBe("═".repeat(Math.max((title as string).length, 24)));
+    expect(blank).toBe("");
+    expect(blocks).toBe("  blocks: LXD Panel, Status Bar");
+  });
+
+  it("floors the plain rule at 24 columns for a short title", () => {
+    const out = tierLookupFormatters.plain({ ...TIER, uri: "x", name: "a" });
+    expect(out.split("\n").at(1)).toBe("═".repeat(24));
+  });
+
+  it("heads the llm entity read at H2, never H1 (B2)", () => {
+    const out = tierLookupFormatters.llm(TIER);
+    expect(out.startsWith("## apps/lxd-panel\n")).toBe(true);
+    expect(out).not.toMatch(/^# /m);
+  });
+});
+
+describe("tierLookupFormatters — shared style seam (B7)", () => {
+  const prevLevel = chalk.level;
+  afterEach(() => {
+    chalk.level = prevLevel;
+  });
+
+  it("styles the plain title on a color-capable TTY (single-sourced frame)", () => {
+    chalk.level = 1;
+    withStdoutTty(true, () => {
+      // Delegating to `renderLookupPlain` now carries the same TTY tint block and
+      // skill lookups get — previously the tier title stayed unstyled.
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the ESC byte is the point
+      expect(tierLookupFormatters.plain(TIER)).toMatch(/\x1b\[/);
+    });
+  });
+
+  it("keeps piped plain output byte-stable off a TTY", () => {
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      const out = tierLookupFormatters.plain(TIER);
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(out).not.toMatch(/\x1b\[/);
+      expect(out.split("\n").at(0)).toBe("apps/lxd-panel (cs:apps/lxd-panel)");
+      expect(out.split("\n").at(3)).toBe("  blocks: LXD Panel, Status Bar");
+    });
+  });
+});