@canonical/pragma-cli 0.35.0 → 0.37.0

package/src/capabilities/upgrade/runUpgrade.ts

@@ -13,6 +13,11 @@
  *   by `assertExecOk` as an actionable UNSUPPORTED (exit 1) — the interpreter
  *   RESOLVES on a nonzero exit, so the check is the consumer's job.
  * - offline / already-latest carry NO exec — a real run just returns the status.
+ * - a non-global install (linked / ephemeral / workspace / unknown) also
+ *   carries NO exec even when an update exists: there is no command pragma may
+ *   run for it, so the task reports the delta plus the state's guidance and
+ *   mutates nothing. `pmUpdateCommand` only accepts the global arm, so this is
+ *   enforced by the types, not by convention.
  *
  * The whole registry read is preview-safe, so no `mutation.preview` gating is
  * needed here (unlike `sources update`, whose heavy resolve must be gated).
@@ -29,6 +34,7 @@ import {
   guardMissingBinary,
   PRAGMA_PACKAGE,
   pmUpdateCommand,
+  updateGuidance,
 } from "../shared/index.js";
 import type { UpgradeData } from "./types.js";
 
@@ -46,8 +52,15 @@ export async function runUpgrade(
 ): Promise<Task<UpgradeData>> {
   const { channel } = (await rt.loadConfig()).config;
   const install = detectInstallSource();
-  const command = pmUpdateCommand(install.pm, PRAGMA_PACKAGE);
+  // Only a GLOBAL install has a sanctioned update command — the type of
+  // `pmUpdateCommand` enforces the narrowing. A linked checkout in particular
+  // must never be handed `npm i -g`: it would overwrite the development link.
+  const command =
+    install.kind === "global"
+      ? pmUpdateCommand(install, PRAGMA_PACKAGE)
+      : undefined;
   const pm = install.label;
+  const kind = install.kind;
   const current = rt.version;
 
   const registry = await checkRegistryVersion(PRAGMA_PACKAGE, channel);
@@ -55,9 +68,10 @@ export async function runUpgrade(
   if (registry === undefined) {
     const data: UpgradeData = {
       pm,
+      kind,
       current,
       latest: undefined,
-      command,
+      ...(command !== undefined ? { command } : {}),
       offline: true,
       alreadyLatest: false,
       executed: false,
@@ -71,9 +85,10 @@ export async function runUpgrade(
   if (registry.latest === current) {
     const data: UpgradeData = {
       pm,
+      kind,
       current,
       latest: registry.latest,
-      command,
+      ...(command !== undefined ? { command } : {}),
       offline: false,
       alreadyLatest: true,
       executed: false,
@@ -84,16 +99,40 @@ export async function runUpgrade(
     });
   }
 
+  if (install.kind !== "global") {
+    // An update exists, but this install has no command pragma may run for
+    // it — say so honestly and run NOTHING. (The discriminant narrowing is
+    // what lets `updateGuidance` accept `install` here.)
+    const guidance = updateGuidance(install);
+    const data: UpgradeData = {
+      pm,
+      kind,
+      current,
+      latest: registry.latest,
+      guidance,
+      offline: false,
+      alreadyLatest: false,
+      executed: false,
+    };
+    return gen(function* () {
+      yield* $(info(`${current} → ${registry.latest}`));
+      yield* $(warn(`No automatic upgrade for this install: ${guidance}`));
+      return data;
+    });
+  }
+
+  const updateCommand = pmUpdateCommand(install, PRAGMA_PACKAGE);
   const data: UpgradeData = {
     pm,
+    kind,
     current,
     latest: registry.latest,
-    command,
+    command: updateCommand,
     offline: false,
     alreadyLatest: false,
     executed: true,
   };
-  const parts = command.split(" ");
+  const parts = updateCommand.split(" ");
   const bin = parts[0] ?? "npm";
   const args = parts.slice(1);
   // Guard the spawn: an absent package manager (`bin` not on PATH) REJECTS the
@@ -112,7 +151,7 @@ export async function runUpgrade(
       // so inspect the result: a failed install (e.g. EACCES on a global
       // `npm i -g`) must fail loudly, not report a silent success.
       const result = yield* $(exec(bin, args, rt.cwd));
-      assertExecOk(command, result);
+      assertExecOk(updateCommand, result);
       return data;
     }),
   );

package/src/capabilities/upgrade/types.ts

@@ -2,16 +2,24 @@
  * Data shape for `pragma upgrade`.
  */
 
+import type { InstallKind } from "../../kernel/render/vocabulary.js";
+
 /** The outcome of an upgrade run (or its plan). */
 export interface UpgradeData {
   /** The install-source label (e.g. `bun (global)`). */
   readonly pm: string;
+  /** The install-source state behind the label. */
+  readonly kind: InstallKind;
   /** The currently-installed version. */
   readonly current: string;
   /** The latest published version, or `undefined` when offline. */
   readonly latest: string | undefined;
-  /** The package-manager command that applies the update. */
-  readonly command: string;
+  /** The package-manager command that applies the update — only for a GLOBAL
+   * install; every other state carries {@link guidance} instead. */
+  readonly command?: string;
+  /** The honest sentence for an install with no sanctioned update command
+   * (linked / ephemeral / workspace / unknown). */
+  readonly guidance?: string;
   /** True when the registry could not be reached. */
   readonly offline: boolean;
   /** True when the installed version is already the latest. */

package/src/capabilities/upgrade/upgrade.render.ts

@@ -33,8 +33,12 @@ export const upgradeFormatters: Formatters<UpgradeData> = {
         "",
         `Updated to ${data.latest}.`,
       );
-    } else {
+    } else if (data.command) {
       lines.push(`Run: ${chalk.cyan(data.command)}`);
+    } else {
+      // No sanctioned command for this install (linked / ephemeral /
+      // workspace / unknown) — the guidance sentence is the whole story.
+      lines.push(`No automatic upgrade for this install: ${data.guidance}`);
     }
     return lines.join("\n");
   },
@@ -45,7 +49,10 @@ export const upgradeFormatters: Formatters<UpgradeData> = {
       return `Already at the latest version (${data.current}).`;
     }
     if (data.executed) return `Upgraded: ${data.current} → ${data.latest}`;
-    return `Update available: ${data.current} → ${data.latest} (\`${data.command}\`)`;
+    if (data.command) {
+      return `Update available: ${data.current} → ${data.latest} (\`${data.command}\`)`;
+    }
+    return `Update available: ${data.current} → ${data.latest} — ${data.guidance}`;
   },
 
   json(data) {

package/src/capabilities/upgrade/upgrade.test.ts

@@ -28,6 +28,7 @@ import {
   guardMissingBinary,
   isMissingBinaryError,
 } from "../shared/assertExecOk.js";
+import type { InstallSource } from "../shared/index.js";
 import {
   checkRegistryVersion,
   REGISTRY_TIMEOUT_MS,
@@ -36,6 +37,22 @@ import { runUpgrade } from "./runUpgrade.js";
 import type { UpgradeData } from "./types.js";
 import { upgradeModule } from "./upgrade.verb.js";
 
+// Pin the install-source detection: the real detector reads THIS process
+// (whose entry is a source checkout — an honest `unknown` with no command,
+// which would starve every update-needed case of its exec). Detection itself
+// is covered by `shared/packageManager.test.ts`; here it is a fixture.
+const detection = vi.hoisted(() => ({ install: undefined as unknown }));
+vi.mock("../shared/index.js", async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  detectInstallSource: () => detection.install,
+}));
+
+const GLOBAL_NPM: InstallSource = {
+  kind: "global",
+  pm: "npm",
+  label: "npm (global)",
+};
+
 const upgradeVerb = upgradeModule.verbs[0] as VerbSpec;
 const FLAGS_JSON: GlobalFlags = {
   llm: false,
@@ -71,6 +88,7 @@ let prevXdg: string | undefined;
 beforeEach(() => {
   prevXdg = process.env.XDG_CONFIG_HOME;
   process.env.XDG_CONFIG_HOME = tmpCwd();
+  detection.install = GLOBAL_NPM;
 });
 afterEach(() => {
   process.env.XDG_CONFIG_HOME = prevXdg;
@@ -181,6 +199,60 @@ describe("upgrade — update needed", () => {
   });
 });
 
+describe("upgrade — a non-global install NEVER gets an exec (the headline)", () => {
+  const LINKED: InstallSource = {
+    kind: "linked",
+    pm: "npm",
+    target: "/home/u/code/pragma/packages/cli/pragma",
+    label: "npm link (development checkout)",
+  };
+
+  it("linked + update available: no command, no exec — guidance instead", async () => {
+    // The case that must never regress: `npm i -g` against an npm-linked
+    // install would OVERWRITE the symlink to the development worktree.
+    detection.install = LINKED;
+    stubRegistry("99.0.0");
+    const task = await runUpgrade(bootRuntime(FLAGS_JSON, tmpCwd()));
+    const { value, effects } = dryRun(task);
+    expect(value.executed).toBe(false);
+    expect(value.command).toBeUndefined();
+    expect(value.kind).toBe("linked");
+    expect(value.guidance).toMatch(/development checkout/i);
+    expect(effects.some((e) => e._tag === "Exec")).toBe(false);
+  });
+
+  it("--dry-run through dispatch plans NO Execute line for a linked install", async () => {
+    detection.install = LINKED;
+    stubRegistry("99.0.0");
+    const outcome = await executeVerb(
+      upgradeVerb,
+      {},
+      DRY,
+      bootRuntime(FLAGS_JSON, tmpCwd()),
+    );
+    const plan = JSON.parse(outcome.stdout as string).data.plan as string[];
+    expect(plan.some((line) => line.startsWith("Execute:"))).toBe(false);
+    expect(plan.some((line) => line.includes("No automatic upgrade"))).toBe(
+      true,
+    );
+  });
+
+  it("an ephemeral run reports its state with no command either", async () => {
+    detection.install = {
+      kind: "ephemeral",
+      runner: "npx",
+      label: "npx (ephemeral)",
+    } satisfies InstallSource;
+    stubRegistry("99.0.0");
+    const { value, effects } = dryRun(
+      await runUpgrade(bootRuntime(FLAGS_JSON, tmpCwd())),
+    );
+    expect(value.executed).toBe(false);
+    expect(value.command).toBeUndefined();
+    expect(effects.some((e) => e._tag === "Exec")).toBe(false);
+  });
+});
+
 describe("assertExecOk — the exec-exitCode guard", () => {
   it("returns on a zero exit and throws an actionable UNSUPPORTED (with stderr) on nonzero", () => {
     expect(() =>

package/src/constants.ts

@@ -41,6 +41,13 @@ const ISSUES_URL = identity.issuesUrl;
 /** Semver version string read from package.json. */
 const VERSION: string = pkg.version;
 
+/**
+ * The Node.js range this distribution supports, read from `engines.node` in
+ * package.json so the manifest stays the single statement of the floor. The
+ * doctor check quotes it, and `isSupportedNodeVersion` is pinned to it by test.
+ */
+const SUPPORTED_NODE_RANGE: string = pkg.engines.node;
+
 /**
  * The project config filename the walker looks for and every surface that
  * quotes it — diagnostics, the onboarding note, the generated reference, the
@@ -76,7 +83,12 @@ type OutputFormat = (typeof OUTPUT_FORMATS)[number];
 const DEFAULT_DETAIL_LEVEL: DetailLevel = "standard";
 
 /**
- * The wordmark `--help` opens with, as raw ASCII-art lines.
+ * The wordmark `--help` opens with FOR A HUMAN READER, as raw ASCII-art lines.
+ *
+ * Whether it prints is decided at the one emit site (`rootHelp.ts`) from the
+ * invocation's global flags: a captured run (`--format llm`/`json`, including
+ * the `llm` a non-interactive stdout infers) gets the bare header instead. This
+ * constant is the ART, not the policy.
  *
  * PROJECTED from the distribution config, exactly like {@link BIN_NAME} and
  * {@link PROGRAM_DESCRIPTION} — a wordmark spells a name, so it is identity, and
@@ -111,5 +123,6 @@ export {
   PROGRAM_LOGO,
   PROJECT_CONFIG_FILENAME,
   RECOVERY_CLI_PREFIX,
+  SUPPORTED_NODE_RANGE,
   VERSION,
 };

package/src/identity.test.ts

@@ -123,6 +123,9 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
       ],
       "9.9.9",
       "https://recipes.test/issues",
+      // A human at a terminal: the fork's own art (it declares none) would
+      // print here, so the assertions below see the widest page.
+      { llm: false, format: "plain", verbose: false },
     );
 
     expect(help).not.toMatch(THIS_DISTRIBUTION);
@@ -214,15 +217,25 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     // `$XDG_DATA_HOME/pragma/skills` and one `<cwd>/.pragma/skills`, so a fork
     // read the other's skills and could not install its own without collision.
     process.env.XDG_DATA_HOME = join(tmpdir(), "identity-data");
-    const { skillRoots, installedSkillsDir } = await import(
+    const { skillRoots, installedSkillsDir, bundledSkillsDir } = await import(
       "./capabilities/skill/discover.js"
     );
     expect(installedSkillsDir().endsWith(join("recipes", "skills"))).toBe(true);
-    expect(skillRoots("/work")).toEqual([
+    // The two roots that live on SHARED ground — the user's data home and the
+    // user's repository — are the ones a fork must namespace.
+    const namespaced = [
       join("/work", ".recipes", "skills"),
       installedSkillsDir(),
-    ]);
-    for (const root of skillRoots("/work")) {
+    ];
+    // The bundled snapshot is the third, and it is deliberately NOT namespaced
+    // by the bin name: it is the distribution's OWN package directory, which is
+    // already private to the install. A fork is a different package and ships
+    // its own `bundled-skills/`, so there is no shared ground to collide on —
+    // and it is exempt from the check below for exactly that reason, since the
+    // path this repository's package sits at necessarily says "pragma".
+    expect(bundledSkillsDir()).toBeDefined();
+    expect(skillRoots("/work")).toEqual([...namespaced, bundledSkillsDir()]);
+    for (const root of namespaced) {
       expect(root).not.toMatch(THIS_DISTRIBUTION);
     }
   });
@@ -259,7 +272,7 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
       args: ["mcp", "serve"],
       cwd: "/work",
     });
-    // The global band omits `cwd` (a per-user server is not project-pinned)
+    // The global scope omits `cwd` (a per-user server is not project-pinned)
     // but still runs the fork's own binary.
     expect(pragmaMcpEntry("/work", "global")).toEqual({
       command: "recipes",

package/src/kernel/completion/entitySource.test.ts

@@ -2,6 +2,10 @@ import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  bundledSkillsDir,
+  discoverSkillsFrom,
+} from "../../capabilities/skill/discover.js";
 import { readConfig } from "../config/readConfig.js";
 import { embeddedManifest } from "../runtime/graphpack/embedded.js";
 import { activePackPath, packDir } from "../runtime/paths.js";
@@ -121,10 +125,19 @@ describe("indexCompletionEnv — multi-source names(ref)", () => {
       join(skillDir, "SKILL.md"),
       "---\nname: docx\ndescription: Word docs.\n---\n",
     );
+    // The BUNDLED snapshot ships inside the package, so it is a discovery root
+    // on every machine — including this one. The project root's skill is what
+    // this cell is about; the expectation is derived from the shipped artifact
+    // rather than pinned to a list, so a release that changes which skills the
+    // packs provide does not rewrite this test.
+    const bundled = discoverSkillsFrom([bundledSkillsDir() as string]).map(
+      (skill) => skill.name,
+    );
+    const expected = [...new Set(["docx", ...bundled])].sort();
     const env = indexCompletionEnv(cwd);
-    expect(await env.names({ from: "skills" })).toEqual(["docx"]);
+    expect(await env.names({ from: "skills" })).toEqual(expected);
     // A second read returns the same list (one filesystem walk per env).
-    expect(await env.names({ from: "skills" })).toEqual(["docx"]);
+    expect(await env.names({ from: "skills" })).toEqual(expected);
   });
 
   it("a type nothing matches yields [] (prefixes still list the default map)", async () => {

package/src/kernel/completion/safety.test.ts

@@ -331,15 +331,22 @@ describe("storeless guarantee (PROTECTED)", () => {
       runComplete(["tier", "lookup", "ap"], capabilities, env),
     ).resolves.toContain("ds:apps");
 
-    // skills (no skills root here) and prompt labels (this graph carries no
-    // prompt entities) have nothing to offer, and the honest storeless answer
-    // is an empty list rather than a store boot.
-    for (const words of [
-      ["skill", "lookup", "do"],
-      ["prompt", "lookup", "bu"],
-    ]) {
-      await expect(runComplete(words, capabilities, env)).resolves.toEqual([]);
-    }
+    // skills: the BUNDLED snapshot ships inside the package, so even this
+    // fresh cwd with an empty XDG data home completes REAL skill names — and
+    // does it storelessly, which is the whole point of the cell. (It used to
+    // assert `[]` here, which was true only because a fresh machine had no
+    // skills at all; that is the defect the snapshot fixes.) The names are not
+    // spelled out: an empty prefix asks for all of them.
+    await expect(
+      runComplete(["skill", "lookup", ""], capabilities, env),
+    ).resolves.not.toHaveLength(0);
+
+    // prompt labels: this graph carries no prompt entities and no shipped skill
+    // declares `prompt: true`, so the honest storeless answer is still an empty
+    // list rather than a store boot.
+    await expect(
+      runComplete(["prompt", "lookup", "bu"], capabilities, env),
+    ).resolves.toEqual([]);
 
     expect(vi.mocked(createStore)).not.toHaveBeenCalled();
   });

package/src/kernel/config/defaults.test.ts

@@ -44,7 +44,12 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
     expect(defaults.colophon?.summary?.length).toBeLessThan(400);
   });
 
-  it("ships the four canonical default packs (git+https sources)", () => {
+  // Five packs, and ONE carries a subdirectory. That is load-bearing, not
+  // decoration: `@canonical/token-ontology` lives inside a monorepo, and a
+  // git source names a repository — without `:packages/token-ontology` the
+  // clone would succeed against a root that has no `definitions/` or `data/`
+  // and the pack would contribute nothing, silently.
+  it("ships the five canonical default packs (all git+https)", () => {
     expect(
       defaults.packs?.map((pack) =>
         typeof pack === "string"
@@ -60,9 +65,15 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
         name: "@canonical/anatomy-dsl",
         source: "git+https://github.com/canonical/anatomy-dsl.git#main",
       },
+      {
+        name: "@canonical/token-ontology",
+        source:
+          "git+https://github.com/canonical/design-tokens.git#main:packages/token-ontology",
+      },
       {
         name: "@canonical/code-standards",
-        source: "git+https://github.com/canonical/web-code-standards.git#main",
+        source:
+          "git+https://github.com/canonical/web-code-standards.git#v0.1.5",
       },
       {
         name: "@canonical/ds-implementations",
@@ -78,7 +89,7 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
     const storyCounts = defaults.packs?.map((pack) =>
       typeof pack === "string" ? 0 : (pack.stories?.length ?? 0),
     );
-    expect(storyCounts).toEqual([5, 0, 1, 1]);
+    expect(storyCounts).toEqual([5, 0, 0, 1, 1]);
   });
 
   it("declares no removed field — the validator would refuse to load one", () => {
@@ -97,6 +108,11 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
     // can expand — `cs:` is here for that reader.
     expect(defaults.prefixes).toEqual({
       ds: "https://ds.canonical.com/",
+      dt: "https://dt.canonical.com/",
+      // Nested under `dt:`, and bound separately because `compactUri` takes the
+      // longest match — with only the parent bound, every term of this
+      // vocabulary would render as `dt:w3c-tokens/…`.
+      "w3c-tokens": "https://dt.canonical.com/w3c-tokens/",
       cs: "http://pragma.canonical.com/codestandards#",
     });
   });

package/src/kernel/config/readConfig.test.ts

@@ -59,7 +59,7 @@ describe("readConfig — layering + provenance", () => {
     expect(config.tier).toBe("core");
     expect(config.channel).toBe("experimental");
     expect(config.detail).toBe("detailed");
-    expect(config.packs).toHaveLength(4); // from defaults
+    expect(config.packs).toHaveLength(5); // from defaults
 
     expect(origins).toMatchObject({
       tier: "project",

package/src/kernel/index.ts

@@ -10,8 +10,16 @@
  * is high: it must be a declaration the kernel makes about itself rather than
  * a step in any one pipeline.
  *
- * Today that is the declared vocabulary — the distribution's mapping from the
- * roles the CLI knows (a prompt, a resource) onto the RDF terms that actually
+ * Today that is the declared vocabulary and the interactivity vocabulary. The
+ * latter (`interactivity.ts`) names the questions about attended streams — is
+ * stdout captured, may we prompt, may we color (that third one lives with the
+ * styler, for the dependency reason its docblock records) — which render,
+ * dispatch and flag parsing each used to answer with their own inline probe.
+ * They are different questions over different streams, and the names are what
+ * keeps them from being flattened into one flag.
+ *
+ * The declared vocabulary is the distribution's mapping from the roles the
+ * CLI knows (a prompt, a resource) onto the RDF terms that actually
  * carry them in the active graph. It is parsed once at module load and read
  * from the prompt capability, the MCP prompt source, and the pack index
  * builder, none of which owns it and any of which would otherwise hardcode
@@ -22,5 +30,6 @@
  * exporting it here would advertise a runtime API the gate does not have.
  */
 
+export { canPrompt, stdoutIsCaptured } from "./interactivity.js";
 export type { DeclaredVocabulary } from "./vocabulary.js";
 export { VOCABULARY } from "./vocabulary.js";

package/src/kernel/interactivity.test.ts

@@ -0,0 +1,76 @@
+import chalk from "chalk";
+import { afterEach, describe, expect, it } from "vitest";
+import { canPrompt, stdoutIsCaptured } from "./interactivity.js";
+import { canColor } from "./render/style.js";
+
+/** Force a stream's `isTTY`, as only a test may. */
+const setTTY = (
+  stream: NodeJS.ReadStream | NodeJS.WriteStream,
+  value: boolean | undefined,
+): void => {
+  (stream as { isTTY?: boolean }).isTTY = value;
+};
+
+const savedIn = process.stdin.isTTY;
+const savedOut = process.stdout.isTTY;
+const savedErr = process.stderr.isTTY;
+const savedLevel = chalk.level;
+afterEach(() => {
+  setTTY(process.stdin, savedIn);
+  setTTY(process.stdout, savedOut);
+  setTTY(process.stderr, savedErr);
+  chalk.level = savedLevel;
+});
+
+describe("the interactivity vocabulary asks THREE questions, not one", () => {
+  it("a captured stdout with an attended terminal is still promptable", () => {
+    // The case that makes flattening these wrong: an agent runs a mutating
+    // verb with `| cat` while a terminal is still attached. Answering the
+    // prompting question with stdout's probe would refuse a human; answering
+    // the output-shape question with stdin's would hand an agent a page of
+    // decoration it cannot use.
+    setTTY(process.stdout, false);
+    setTTY(process.stdin, true);
+    setTTY(process.stderr, true);
+    expect(stdoutIsCaptured()).toBe(true);
+    expect(canPrompt()).toBe(true);
+  });
+
+  it("a redirected stderr is NOT promptable, however attended stdout is", () => {
+    // `<verb> 2>/dev/null`: the step sequence renders to stderr, so gating on
+    // stdout would mount an invisible render that then blocks on stdin.
+    setTTY(process.stdout, true);
+    setTTY(process.stdin, true);
+    setTTY(process.stderr, false);
+    expect(stdoutIsCaptured()).toBe(false);
+    expect(canPrompt()).toBe(false);
+  });
+
+  it("stdin alone does not make a run promptable", () => {
+    setTTY(process.stdin, false);
+    setTTY(process.stderr, true);
+    expect(canPrompt()).toBe(false);
+  });
+
+  it("colour needs the terminal AND a usable chalk level", () => {
+    setTTY(process.stdout, true);
+    chalk.level = 1;
+    expect(canColor()).toBe(true);
+    // Off in CI-shaped environments where `supports-color` fires off a TTY…
+    setTTY(process.stdout, false);
+    expect(canColor()).toBe(false);
+    // …and off whenever the level is zeroed (what `NO_COLOR` does at load).
+    setTTY(process.stdout, true);
+    chalk.level = 0;
+    expect(canColor()).toBe(false);
+  });
+
+  it("treats an absent isTTY as captured / unpromptable, never as attended", () => {
+    setTTY(process.stdout, undefined);
+    setTTY(process.stdin, undefined);
+    setTTY(process.stderr, undefined);
+    expect(stdoutIsCaptured()).toBe(true);
+    expect(canPrompt()).toBe(false);
+    expect(canColor()).toBe(false);
+  });
+});

package/src/kernel/interactivity.ts

@@ -0,0 +1,69 @@
+/**
+ * The interactivity vocabulary — three named questions over three streams.
+ *
+ * Every one of these used to be spelled inline as a bare `process.<stream>
+ * .isTTY === true` at the site that needed it, in four places, and the
+ * spellings did not agree — because they are NOT the same question. Naming them
+ * is the point: the names are what stop the next reader from "simplifying"
+ * three probes into one flag.
+ *
+ * - {@link stdoutIsCaptured} reads **stdout**. It governs OUTPUT SHAPE: whether
+ *   a consumer is piping the data stream somewhere (the shape an agent
+ *   captures), which is what AUTO-INFERS the condensed `llm` default. Capture
+ *   is the inference, not the gate: what drops the root-help wordmark is the
+ *   resulting shape — `llm` or `json` — so an explicit `--format plain` through
+ *   a pipe is captured and keeps the art, while `--format llm` on an attended
+ *   terminal is not captured and drops it. Explicit format beats inference, in
+ *   both directions.
+ * - {@link canPrompt} reads **stdin AND stderr** — never stdout. The step
+ *   sequence renders to stderr and reads stdin, so `<verb> 2>/dev/null` is
+ *   non-interactive while `<verb> | cat` is not. Gating this one on stdout
+ *   would mount an invisible render that then blocks on stdin.
+ * - `canColor` (`render/style.ts`) reads **stdout** plus chalk's own color
+ *   level, so piped, redirected and MCP output stays byte-stable even where
+ *   `supports-color` fires off a TTY. It is the one question of the three that
+ *   lives with the styler rather than here, because it needs `chalk` and this
+ *   module is imported by global-flag parsing — which runs before `--version`
+ *   answers, on a path that must load nothing it does not use. It still asks
+ *   its stdout half through {@link stdoutIsCaptured}, so the three stay one
+ *   vocabulary.
+ *
+ * The distinction is not academic: an agent running a mutating verb with its
+ * stdout captured but a terminal still attached is CAPTURED and PROMPTABLE at
+ * the same time. Answering either question with the other's probe would either
+ * hang a pipeline or refuse a human.
+ *
+ * These are the only sanctioned readers of `process.*.isTTY` outside a test.
+ * Each is a plain function rather than a module-load constant because a test
+ * assigns the streams' `isTTY` per case, and a constant would freeze the first
+ * value the process ever saw.
+ */
+
+/**
+ * Whether stdout is going somewhere other than an attended terminal — piped,
+ * redirected, or read by a parent process.
+ *
+ * The OUTPUT-SHAPE question, and stdout's alone: it says nothing about whether
+ * a human is available to answer a prompt (see {@link canPrompt}).
+ *
+ * @returns True when stdout is not a TTY.
+ * @note Impure — reads `process.stdout.isTTY`.
+ */
+export function stdoutIsCaptured(): boolean {
+  return process.stdout.isTTY !== true;
+}
+
+/**
+ * Whether this invocation may ask the user a question: stdin AND stderr are
+ * both attended terminals.
+ *
+ * THE interactivity gate (H3). One exported fact, so the kernel's interaction
+ * context and a mounted subtree's own decision can never disagree about what
+ * "a TTY" means. Deliberately blind to stdout — see the module docblock.
+ *
+ * @returns True when a prompt can be both drawn and answered.
+ * @note Impure — reads `process.stdin.isTTY` and `process.stderr.isTTY`.
+ */
+export function canPrompt(): boolean {
+  return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}