@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/testing/fixtures/connectGraph.ts

@@ -0,0 +1,159 @@
+/**
+ * A fixture graph authored to exercise `graph connect`'s traversal POLICY and
+ * every one of its five negative answers.
+ *
+ * This is where exact numbers belong. The shipped pack is about to change —
+ * new channel symbols and hundreds of binding records will move every hop count
+ * and path set in it — so a test that pinned "these two are exactly 2 hops
+ * apart" against real data would fail on a correct change and teach a
+ * maintainer to update the fixture rather than to think. Here the data is
+ * authored, so the numbers ARE the specification: this graph exists to make one
+ * statement per shape, and if a count moves, the behaviour moved.
+ *
+ * The roster sizes are GENERATED from the kernel's own threshold rather than
+ * written out, for the reason `blockGraph.ts` gives for the same move: the count
+ * is the whole point of the case, and a hand-copied number invites someone to
+ * tidy one line away and quietly turn a roster back into a relation. They are
+ * also derived from the constant rather than a copy of it, so a change to the
+ * threshold moves this fixture with it.
+ *
+ * What each region is for:
+ *
+ * - **the chain** `ds:a1 … ds:a8`, one predicate, one edge per node: hop
+ *   counting, the default limit, the `--hops` ceiling, and the "no path within
+ *   the limit" answer. Deliberately UNTYPED — a class with eight members is a
+ *   relation under the fan-in rule, so typing them would connect every pair of
+ *   them through their class in two hops and there would be no unconnected pair
+ *   left to test.
+ * - **the reversed pair** `ds:r1 … ds:r3`: a path that has to be walked against
+ *   the direction of one of its edges.
+ * - **the fan of three routes** `ds:m1 … ds:m2`: several shortest paths, both
+ *   ranking tiebreaks, and the path cap.
+ * - **`ds:shares` twice over**: ONE predicate carrying a roster group and a
+ *   relation group, which is what a rule keyed on a predicate NAME could never
+ *   get right.
+ * - **`ds:fansTo`**: the other direction of the same rule — one subject fanning
+ *   out past the threshold.
+ * - **`ds:isolated`**: in the graph, but with nothing walkable on it at all.
+ * - **the blank-node bridge**: a path THROUGH a record, which is the traversal
+ *   a per-layer SPARQL query cannot do because a blank node cannot be re-bound
+ *   by name.
+ */
+
+import { ROSTER_THRESHOLD } from "../../kernel/runtime/readEntity.js";
+
+/** The prefixes the fixture store is built and queried with. */
+export const CONNECT_PREFIXES: Readonly<Record<string, string>> = {
+  ds: "https://ds.canonical.com/",
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+/** How long the hop-counting chain is — long enough to outrun the ceiling. */
+export const CHAIN_LENGTH = 8;
+
+/**
+ * How many members a group needs to be a roster: one clear of the threshold,
+ * plus one so that removing a line does not silently reclassify the group.
+ */
+export const ROSTER_SIZE = ROSTER_THRESHOLD + 2;
+
+/**
+ * The true size of the `(ds:shares, ds:hub)` group: the generated members plus
+ * `ds:isolated`, which shares the hub precisely so that it has nothing walkable
+ * of its own. Stated rather than left to be recounted, because it is the number
+ * the answer reports.
+ */
+export const HUB_ROSTER_SIZE = ROSTER_SIZE + 1;
+
+/** `ds:a1 -> ds:a2 -> … -> ds:a8`, one admitted edge per link. */
+const CHAIN = Array.from(
+  { length: CHAIN_LENGTH - 1 },
+  (_, index) => `ds:a${index + 1} ds:linksTo ds:a${index + 2} .`,
+).join("\n");
+
+/**
+ * `ROSTER_SIZE` subjects all asserting `ds:shares ds:hub` — so the group
+ * `(ds:shares, ds:hub)` fans in past the threshold and every one of those edges
+ * is refused. Each member also holds ONE private relation, so it is still a
+ * node the walk can start from: an endpoint with no relation at all is a
+ * different answer, and `ds:isolated` is where that one is tested.
+ */
+const ROSTER = Array.from(
+  { length: ROSTER_SIZE },
+  (_, index) =>
+    `ds:member${index} a ds:Probe ; ds:shares ds:hub ; ds:owns ds:private${index} .`,
+).join("\n");
+
+/**
+ * One subject asserting `ds:fansTo` at `ROSTER_SIZE` objects — the OTHER
+ * direction of the same rule. Its objects share a roster; none of the edges is
+ * walkable. Each object holds one private relation, for the same reason the
+ * roster members do.
+ */
+const FAN = `ds:fanHub ${Array.from(
+  { length: ROSTER_SIZE },
+  (_, index) => `ds:fansTo ds:leaf${index}`,
+).join(" ; ")} .
+${Array.from(
+  { length: ROSTER_SIZE },
+  (_, index) => `ds:leaf${index} ds:owns ds:leafPrivate${index} .`,
+).join("\n")}`;
+
+/** The fixture ontology + individuals as Turtle. */
+export const CONNECT_TTL = `
+@prefix ds: <https://ds.canonical.com/> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# ---- Ontology (TBox) ----
+ds:Probe a owl:Class ; rdfs:label "Probe" .
+ds:Record a owl:Class ; rdfs:label "Record" .
+
+ds:linksTo a owl:ObjectProperty ; rdfs:label "linksTo" .
+ds:pointsAt a owl:ObjectProperty ; rdfs:label "pointsAt" .
+ds:alpha a owl:ObjectProperty ; rdfs:label "alpha" .
+ds:beta a owl:ObjectProperty ; rdfs:label "beta" .
+ds:gamma a owl:ObjectProperty ; rdfs:label "gamma" .
+ds:shares a owl:ObjectProperty ; rdfs:label "shares" .
+ds:fansTo a owl:ObjectProperty ; rdfs:label "fansTo" .
+ds:owns a owl:ObjectProperty ; rdfs:label "owns" .
+ds:holds a owl:ObjectProperty ; rdfs:label "holds" .
+ds:refers a owl:ObjectProperty ; rdfs:label "refers" .
+
+# ---- The chain: hop counting, the limit, and the ceiling ----
+${CHAIN}
+
+# ---- The reversed pair: r1 <-pointsAt- r2 -pointsAt-> r3 ----
+ds:r2 ds:pointsAt ds:r1 , ds:r3 .
+
+# ---- Three shortest routes from m1 to m2, for ranking and the path cap ----
+# via1 stays inside ds:alpha; via3 stays inside ds:gamma; via2 mixes the two.
+# So the ranking's second key (fewest distinct predicates) puts via1 and via3
+# ahead of via2, and its third key (lexicographic) settles alpha before gamma.
+ds:m1 ds:alpha ds:via1 , ds:via2 .
+ds:via1 ds:alpha ds:m2 .
+ds:via2 ds:beta ds:m2 .
+ds:m1 ds:gamma ds:via3 .
+ds:via3 ds:gamma ds:m2 .
+
+# ---- ds:shares, as a ROSTER: ${ROSTER_SIZE} subjects on one object ----
+${ROSTER}
+
+# ---- ds:shares, as a RELATION: two subjects on one object ----
+# The SAME predicate as the roster above. Nothing about the name distinguishes
+# these edges; only the fan-in does.
+ds:relA a ds:Probe ; ds:shares ds:small .
+ds:relB a ds:Probe ; ds:shares ds:small .
+
+# ---- ds:fansTo: one subject past the threshold, the other direction ----
+${FAN}
+
+# ---- In the graph, but nothing walkable on it ----
+ds:isolated a ds:Probe ; ds:shares ds:hub .
+
+# ---- A path THROUGH a blank-node record ----
+ds:bridgeStart ds:holds [ a ds:Record ; ds:refers ds:bridgeEnd ] .
+`;

package/src/testing/fixtures/graph/canonical.ts

@@ -29,7 +29,7 @@
  *
  * Two of those anchors exist to pin an ABSENCE, and are load-bearing for the
  * "declared, not inferred" halves of the read grammar:
- * - `ds:token.legacy.borderRadius` — a `ds:Token` with no `ds:tokenId`, which
+ * - `dt:legacy.borderRadius` — a `dt:TokenSymbol` with no `rdfs:label`, which
  *   `token list` therefore never publishes and `token lookup`/`token sample`
  *   must never reach (`PackLookup.nameFallback` is declared by `standard`
  *   alone).
@@ -42,6 +42,10 @@ import { BLOCK_PREFIXES, BLOCK_TTL } from "../blockGraph.js";
 
 /** Extra `ds:` individuals: a tier-chain + a beta-only block, tokens, tiers. */
 const DS_EXTRA_TTL = `
+@prefix dt: <https://dt.canonical.com/> .
+@prefix w3c-tokens: <https://dt.canonical.com/w3c-tokens/> .
+@prefix dt-web: <https://dt.canonical.com/platform/web/> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 # ---- Tiers beyond the global BLOCK_TTL already declares ----
 ds:apps a ds:Tier ; ds:name "apps" .
 ds:apps_lxd a ds:Tier ; ds:name "apps/lxd" .
@@ -66,37 +70,125 @@ ds:betaWidget a ds:Component ;
   ds:summary "An experimental widget gated to the prerelease channel." .
 
 # ---- Tokens ----
-ds:Token a owl:Class .
-ds:TokenType a owl:Class .
-ds:tokenId a owl:DatatypeProperty ; rdfs:domain ds:Token ; rdfs:range xsd:string .
-ds:tokenType a owl:ObjectProperty ; rdfs:domain ds:Token ; rdfs:range ds:TokenType .
-ds:valueLight a owl:DatatypeProperty ; rdfs:domain ds:Token ; rdfs:range xsd:string .
-ds:valueDark a owl:DatatypeProperty ; rdfs:domain ds:Token ; rdfs:range xsd:string .
-
-ds:type.color a ds:TokenType ; rdfs:label "color" .
-ds:type.spacing a ds:TokenType ; rdfs:label "spacing" .
-
-ds:token.color.primary a ds:Token ;
-  ds:tokenId "color.primary" ;
-  ds:tokenType ds:type.color ;
-  ds:valueLight "#0066CC" ;
-  ds:valueDark "#4D94FF" .
-ds:token.spacing.medium a ds:Token ;
-  ds:tokenId "spacing.medium" ;
-  ds:tokenType ds:type.spacing ;
-  ds:valueLight "16px" ;
-  ds:valueDark "16px" .
-
-# A ds:Token carrying NO ds:tokenId — the entity "token list" does not publish,
-# because its query REQUIRES the id. It is here to pin what a lookup may NOT
-# reach: "token lookup" addresses by ds:tokenId, and a story whose list requires
-# its "by" property must not become addressable (or sampleable) under a name
-# derived from its IRI. See PackLookup.nameFallback, declared by the "standard"
-# story alone — the one story whose list DOES publish such a name.
-ds:token.legacy.borderRadius a ds:Token ;
-  ds:tokenType ds:type.spacing ;
-  ds:valueLight "4px" ;
-  ds:valueDark "4px" .
+# The token STRATA, not the retired ds:Token class: the story addresses
+# dt:TokenSymbol, keyed on the rdfs:label the token-ontology pack publishes,
+# with type and description hanging on the DEFINITIONS behind each symbol
+# rather than on the symbol itself. The story reaches the one definition that
+# speaks for the symbol through the symbol's BASE resolved value — the head of
+# its resolution chain — so every labelled symbol here carries one, which is
+# the shipped graph's own shape.
+dt:TokenSymbol a owl:Class .
+w3c-tokens:Token a owl:Class .
+w3c-tokens:TokenType a owl:Class .
+dt:symbol a owl:ObjectProperty ; rdfs:range dt:TokenSymbol .
+dt:tokenType a owl:ObjectProperty ; rdfs:range w3c-tokens:TokenType .
+dt:channelOf a owl:ObjectProperty ; rdfs:range dt:TokenSymbol .
+dt:covers a owl:ObjectProperty ; rdfs:range dt:TokenSymbol .
+dt:forSymbol a owl:ObjectProperty ; rdfs:range dt:TokenSymbol .
+dt:resolvesTo a owl:DatatypeProperty ; rdfs:range xsd:string .
+dt:resolutionChain a owl:ObjectProperty .
+dt:derivedFrom a owl:ObjectProperty ; rdfs:range dt:TokenSymbol .
+dt:coordinate a owl:ObjectProperty .
+w3c-tokens:description a owl:DatatypeProperty ; rdfs:range xsd:string .
+w3c-tokens:inFile a owl:ObjectProperty .
+w3c-tokens:path a owl:DatatypeProperty ; rdfs:range xsd:string .
+
+w3c-tokens:color a w3c-tokens:TokenType ; rdfs:label "color" .
+w3c-tokens:dimension a w3c-tokens:TokenType ; rdfs:label "dimension" .
+
+dt:color.primary a dt:TokenSymbol ; rdfs:label "color.primary" .
+dt:spacing.medium a dt:TokenSymbol ; rdfs:label "spacing.medium" .
+
+<https://dt.canonical.com/file/light.json#color.primary> a w3c-tokens:Token ;
+  dt:symbol dt:color.primary ;
+  dt:tokenType w3c-tokens:color ;
+  w3c-tokens:inFile <https://dt.canonical.com/file/light.json> ;
+  w3c-tokens:description "The primary brand colour." .
+<https://dt.canonical.com/file/light.json#spacing.medium> a w3c-tokens:Token ;
+  dt:symbol dt:spacing.medium ;
+  dt:tokenType w3c-tokens:dimension ;
+  w3c-tokens:inFile <https://dt.canonical.com/file/light.json> ;
+  w3c-tokens:description "A medium spacing step." .
+<https://dt.canonical.com/file/light.json> w3c-tokens:path "light.json" .
+
+[] a dt:ResolvedValue ; dt:forSymbol dt:color.primary ;
+  dt:resolvesTo "#0066CC" ;
+  dt:resolutionChain ( <https://dt.canonical.com/file/light.json#color.primary> ) .
+[] a dt:ResolvedValue ; dt:forSymbol dt:spacing.medium ;
+  dt:resolvesTo "1rem" ;
+  dt:resolutionChain ( <https://dt.canonical.com/file/light.json#spacing.medium> ) .
+
+# ---- Platform variables ----
+# The second stratum-shaped noun needs a population here for the same reason the
+# symbols do: the cross-noun sweeps derive their cases from the declared stories,
+# so a noun with no rows in this graph makes every filter's roster empty and
+# every refusal unable to name what it would accept.
+dt:Variable a owl:Class .
+dt:Declaration a owl:Class .
+dt:Condition a owl:Class .
+dt:Coordinate a owl:Class .
+dt:Tier a owl:Class .
+dt:Visibility a owl:Class .
+dt:ofSymbol a owl:ObjectProperty ; rdfs:range dt:TokenSymbol .
+dt:tier a owl:ObjectProperty ; rdfs:range dt:Tier .
+dt:visibility a owl:ObjectProperty ; rdfs:range dt:Visibility .
+dt:declaredAt a owl:ObjectProperty ; rdfs:range dt:Declaration .
+dt:under a owl:ObjectProperty ; rdfs:range dt:Condition .
+dt:emits a owl:DatatypeProperty ; rdfs:range xsd:string .
+dt:at a owl:DatatypeProperty ; rdfs:range xsd:string .
+dt:alsoAt a owl:ObjectProperty ; rdfs:range dt:Coordinate .
+dt:derives a owl:ObjectProperty .
+dt:references a owl:ObjectProperty .
+dt:selectsCoordinate a owl:ObjectProperty ; rdfs:range dt:Coordinate .
+dt-web:selector a owl:DatatypeProperty ; rdfs:range xsd:string .
+dt-web:inAtRule a owl:ObjectProperty .
+
+dt:tier.semantic a dt:Tier .
+dt:tier.primitive a dt:Tier .
+dt:visibility.public a dt:Visibility .
+dt:visibility.internal a dt:Visibility .
+dt:coordinate.mode.dark a dt:Coordinate .
+
+<https://dt.canonical.com/s4/web/cond/root> a dt:Condition ;
+  dt-web:selector ":root" ;
+  dt-web:inAtRule ( "@layer ds.tokens" ) .
+
+# Published WITHOUT its leading dashes, which is the only form typable as a
+# positional argument.
+<https://dt.canonical.com/s4/web/--color-primary> a dt:Variable ;
+  rdfs:label "color-primary" ;
+  dt:ofSymbol dt:color.primary ;
+  dt:tier dt:tier.semantic ;
+  dt:visibility dt:visibility.public ;
+  dt:declaredAt [
+    a dt:Declaration ;
+    dt:under <https://dt.canonical.com/s4/web/cond/root> ;
+    dt:emits "#0066CC" ;
+    dt:at "tokens.css:4" ;
+    dt:alsoAt dt:coordinate.mode.dark
+  ] .
+# Stands for NO symbol — the population the token noun cannot reach.
+<https://dt.canonical.com/s4/web/--legacy-radius> a dt:Variable ;
+  rdfs:label "legacy-radius" ;
+  dt:tier dt:tier.primitive ;
+  dt:visibility dt:visibility.internal ;
+  dt:declaredAt [
+    a dt:Declaration ;
+    dt:under <https://dt.canonical.com/s4/web/cond/root> ;
+    dt:emits "var(--color-primary)" ;
+    dt:at "tokens.css:9" ;
+    dt:references ( <https://dt.canonical.com/s4/web/--color-primary> )
+  ] .
+
+# A dt:TokenSymbol carrying NO rdfs:label — the entity "token list" does not
+# publish, because its query REQUIRES the literal. It is here to pin what a
+# lookup may NOT reach: "token lookup" addresses by rdfs:label, and a story
+# whose list requires its "by" property must not become addressable (or
+# sampleable) under a name derived from its IRI. See PackLookup.nameFallback,
+# declared by the "standard" story alone — the one story whose list DOES
+# publish such a name. The token noun deliberately declares none, because the
+# kernel's derivation would publish these dots as slashes.
+dt:legacy.borderRadius a dt:TokenSymbol .
 `;
 
 /**
@@ -336,6 +428,10 @@ ds:implementation.svelte-ds-global.button a ds:ImplementationObject ;
 /** The prefixes the canonical store is built and queried with. */
 export const CANONICAL_PREFIXES: Readonly<Record<string, string>> = {
   ...BLOCK_PREFIXES,
+  dt: "https://dt.canonical.com/",
+  "w3c-tokens": "https://dt.canonical.com/w3c-tokens/",
+  "dt-web": "https://dt.canonical.com/platform/web/",
+  rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
   cs: "http://pragma.canonical.com/codestandards#",
   skos: "http://www.w3.org/2004/02/skos/core#",
 };

package/src/testing/helpers/fsProbe.ts

@@ -0,0 +1,88 @@
+/**
+ * Filesystem fixtures for `probeWritable`'s seam — the two machines no CI host
+ * is.
+ *
+ * `probeWritable` decides whether a row REPORTS a named skip or attempts a
+ * write that fails with a raw fs message, and its two blocking answers cannot
+ * be arranged for real here: no CI host has a `/nix/store`, and a test process
+ * running as root can write to a `0o500` directory whatever its mode bits say.
+ * So the filesystem is three injected functions.
+ *
+ * Two factories, because the suites want different things. {@link storeProbe}
+ * keeps the REAL filesystem and rewrites one subtree's realpath into the
+ * store, so an end-to-end case can build a genuine project and still be a Nix
+ * machine for the one path that matters. {@link fakeFsProbe} invents the
+ * filesystem outright and RECORDS every call, so a unit case can assert the
+ * walk itself and not only its answer.
+ */
+
+import { accessSync, existsSync, realpathSync } from "node:fs";
+import type { FsProbe } from "../../capabilities/setup/operations/writability.js";
+
+/**
+ * A probe over the real filesystem whose `realpathSync` maps everything under
+ * `root` into `/nix/store/<hash>-…`.
+ *
+ * @param root - The subtree that resolves into the store.
+ * @param hash - The store path's name, so two suites can tell theirs apart.
+ * @returns The probe.
+ * @note Impure — `existsSync`/`accessSync` are the real ones.
+ */
+export const storeProbe = (root: string, hash = "1a2b3c-vscode"): FsProbe => ({
+  existsSync,
+  accessSync,
+  realpathSync: (path) =>
+    path.startsWith(root)
+      ? `/nix/store/${hash}${path.slice(root.length)}`
+      : realpathSync(path),
+});
+
+/** What a {@link fakeFsProbe} filesystem consists of. */
+export interface FakeFsSpec {
+  /** The paths that exist. */
+  readonly present?: readonly string[];
+  /** Each path's realpath, for the ones that resolve elsewhere. */
+  readonly realpath?: Readonly<Record<string, string>>;
+  /** The RESOLVED paths that refuse `W_OK`. */
+  readonly denied?: readonly string[];
+  /** Whether `realpathSync` throws (a race, or a symlink loop). */
+  readonly realpathThrows?: boolean;
+}
+
+/** A {@link fakeFsProbe}, plus the calls it saw. */
+export type RecordingFsProbe = FsProbe & {
+  /** Every path `existsSync` was asked about, in order — the walk. */
+  readonly seen: string[];
+  /** Every path `accessSync` was asked about, in order. */
+  readonly accessed: string[];
+};
+
+/**
+ * An invented filesystem that records what it was asked.
+ *
+ * @param spec - The filesystem to present.
+ * @returns The probe, carrying `seen` and `accessed`.
+ * @note Pure — it touches no real path; the arrays are its own state.
+ */
+export const fakeFsProbe = (spec: FakeFsSpec): RecordingFsProbe => {
+  const seen: string[] = [];
+  const accessed: string[] = [];
+  return {
+    seen,
+    accessed,
+    existsSync: (path) => {
+      seen.push(path);
+      return (spec.present ?? []).includes(path);
+    },
+    realpathSync: (path) => {
+      if (spec.realpathThrows === true) throw new Error("ELOOP");
+      return spec.realpath?.[path] ?? path;
+    },
+    accessSync: (path) => {
+      accessed.push(path);
+      if ((spec.denied ?? []).includes(path)) {
+        throw new Error("EACCES: permission denied");
+      }
+    },
+  };
+};

package/src/testing/helpers/runCli.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Pins how `runCli` reports a child that does not finish.
+ *
+ * `spawnSync` reports a timeout the same way it reports a failure to spawn —
+ * through `error` — and a caller that does not look will see only
+ * `status: null`, which reads downstream as an ordinary non-zero exit or, worse,
+ * as a content mismatch. These tests hold the boundary where that distinction
+ * is made, because the cost of losing it is paid in diagnosis rather than in a
+ * red test.
+ */
+
+import { describe, expect, it } from "vitest";
+import { runCli } from "./runCli.js";
+
+describe("runCli — a child that does not finish", () => {
+  it("reports a timeout as a timeout, with the duration", async () => {
+    // `--help` on a 1ms budget cannot complete; any real CLI start-up exceeds it.
+    await expect(async () =>
+      runCli(["--help"], { timeoutMs: 1 }),
+    ).rejects.toThrow(/timed out after 1ms/);
+  });
+
+  it("names the signal that killed it, so a hang is distinguishable", async () => {
+    await expect(async () =>
+      runCli(["--help"], { timeoutMs: 1 }),
+    ).rejects.toThrow(/killed by SIG/);
+  });
+
+  it("does not describe a timeout as a failure to spawn", async () => {
+    // The previous message said "failed to spawn", which sent a reader looking
+    // for a missing binary or a bad path instead of a slow or hung command.
+    await expect(async () =>
+      runCli(["--help"], { timeoutMs: 1 }),
+    ).rejects.not.toThrow(/failed to spawn/);
+  });
+
+  it("attaches whatever the child managed to write", async () => {
+    // Empty streams are still reported explicitly: "(empty)" is evidence, an
+    // absent section is an omission the reader has to interpret.
+    await expect(async () =>
+      runCli(["--help"], { timeoutMs: 1 }),
+    ).rejects.toThrow(/stdout:[\s\S]*stderr:/);
+  });
+});

package/src/testing/helpers/runCli.ts

@@ -46,10 +46,17 @@ export interface RunCliOptions {
    * test the shipped-entry boundary itself.
    */
   readonly mode?: "shipped" | "source";
-  /** Spawn timeout in milliseconds (default 20000). */
+  /** Spawn timeout in milliseconds (default {@link DEFAULT_TIMEOUT_MS}). */
   readonly timeoutMs?: number;
 }
 
+/**
+ * How long a spawned CLI may run before it is killed. Twenty seconds is far
+ * past any assertion these tests make; a run that reaches it has hung, not
+ * been slow.
+ */
+const DEFAULT_TIMEOUT_MS = 20_000;
+
 /** The captured outcome of a `runCli` invocation. */
 export interface RunCliResult {
   readonly stdout: string;
@@ -114,12 +121,29 @@ export function runCli(
     cwd: options.cwd,
     env: { ...env, ...options.env },
     encoding: "utf-8",
-    timeout: options.timeoutMs ?? 20_000,
+    timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
   });
 
   if (result.error) {
+    // A timeout is not a spawn failure, and saying so costs real diagnosis
+    // time: `spawnSync` reports both through `error`, but a timed-out child
+    // has already produced output worth seeing, and the duration is the whole
+    // finding. Separated here so the message names what happened, and carries
+    // the evidence rather than making the reader go and get it.
+    const timedOutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const invocation = `${command} ${spawnArgs.join(" ")}`;
+    const captured = [
+      result.stdout ? `stdout:\n${result.stdout}` : "stdout: (empty)",
+      result.stderr ? `stderr:\n${result.stderr}` : "stderr: (empty)",
+    ].join("\n");
+
+    if ((result.error as NodeJS.ErrnoException).code === "ETIMEDOUT") {
+      throw new Error(
+        `runCli: ${invocation} timed out after ${timedOutMs}ms (killed by ${result.signal ?? "signal"}).\n${captured}`,
+      );
+    }
     throw new Error(
-      `runCli: failed to spawn ${command} ${spawnArgs.join(" ")} — ${result.error.message}`,
+      `runCli: failed to spawn ${invocation} — ${result.error.message}.\n${captured}`,
     );
   }
 

package/src/testing/perf/budgets.test.ts

@@ -77,7 +77,9 @@ describe("perf budgets (PROTECTED)", () => {
     // so it flaked red under whole-suite CPU contention on slower-than-reference
     // hardware even though the median sat comfortably under budget (see
     // BUDGETS.md). p95 is kept as a SOFT signal against gross regressions, with
-    // headroom rather than at the bare ceiling. The 100 ms ceiling is unchanged.
+    // headroom rather than at the bare ceiling. That statistic change left the
+    // ceiling of the day (100 ms) untouched; BUDGET_COMPLETE_MS has been
+    // re-derived twice since, most recently to 240 on 2026-09-10.
     expect(result.trimmedMeanMs).toBeLessThanOrEqual(BUDGET_COMPLETE_MS);
     expect(result.p95Ms).toBeLessThanOrEqual(BUDGET_COMPLETE_MS * 1.5);
   });