@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/setup/setup.verb.ts

@@ -1,59 +1,88 @@
 /**
- * The `setup` verbs — the run-all self-verb plus the four CLI-only sub-verbs
- * (`mcp`/`completions`/`skills`/`lsp`).
+ * The `setup` verbs — the run-all self-verb plus the five CLI-only sub-verbs
+ * (`config`/`completions`/`lsp`/`mcp`/`skills`), every one of them derived from
+ * the target table.
  *
  * `setup` is the ONE covenant noun that is BOTH directly runnable and has
- * sub-verbs (see the buildProgram mixed-noun change). All five are storeless,
- * interactive mutations. The sub-verbs are `mcp: false` (the covenant marks
- * them so — `buildServer` skips them, `buildProgram` still registers them); only
- * the self-verb `setup` is an MCP tool. `destructive: false` (D4) keeps MCP from
- * advertising the `setup` tool as destructive.
+ * sub-verbs. All of them are storeless, interactive mutations. The sub-verbs are
+ * `mcp: false` (`buildServer` skips them, `buildProgram` still registers them);
+ * only the self-verb is an MCP tool. `destructive: false` keeps MCP from
+ * advertising the tool as destructive.
  *
- * ALL FIVE now flow through the SAME summon `execute` seam `create` uses: each
- * `run` synthesizes a `GeneratorDefinition` (detection up front, a pure
- * `generate`), picks the Ink wizard / auto / MCP strategy off `rt.interaction`,
- * and returns `execute` — so setup inherits the recap, live progress, colours,
- * and the shared cancel fixes. summon-core + the generator ops stay behind a
- * LAZY dynamic import (mirroring `create`'s `loadCreateRuntime`), so building the
- * command tree / `--help` / `__complete` — and `setup --yes` — load no
- * React/Ink. `params: []` on every verb keeps the command surface frozen.
+ * THE SCOPE DEFAULT IS GLOBAL. `--scope` used to default to `both`, and `both`
+ * runs each harness's own default scope — which is `project` for most of the
+ * registry — so a bare `setup` scattered `.mcp.json`, `.gemini/settings.json`
+ * and `opencode.json` into whatever directory you happened to be standing in.
+ * The user scope is what a machine-level installer configures; the project scope
+ * is a deliberate, checked-in, team-shared choice, and is now chosen with
+ * `--local` rather than assumed.
+ *
+ * Every sub-verb registers the scope flags UNIFORMLY. That is what lets the scope
+ * answer come from the table instead of per-verb flag wiring — previously
+ * `setup completions --local` died as an unknown option, while `setup mcp
+ * --local` worked, for no reason a user could see. Asking a target for a scope it
+ * cannot honour is a usage error (exit 2) with the corrected command; asking the
+ * RUN-ALL for such a band merely filters, and the out-of-band target still shows
+ * as a named row.
+ *
+ * summon-core + the generator ops stay behind a LAZY dynamic import (mirroring
+ * `create`'s `loadCreateRuntime`), so building the command tree / `--help` /
+ * `__complete` — and `setup --yes` — load no React/Ink.
  */
 
 import type { GeneratorResult } from "@canonical/summon-core";
-import { $, gen, type Task } from "@canonical/task";
+import { $, gen, pure, type Task } from "@canonical/task";
 import { BIN_NAME } from "../../constants.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { PragmaError } from "../../kernel/error/index.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type {
   CapabilityModule,
   ParamSpec,
   VerbSpec,
-} from "../../kernel/spec/types.js";
-import { setupFormatters } from "./setup.render.js";
-import type { ScopeSelection, SetupMode, SetupResult } from "./types.js";
+} from "../../kernel/spec/index.js";
+import { resolveSetupMode, setupModeInput } from "./mode.js";
+import {
+  isActionable,
+  planExitFailed,
+  planTally,
+  type SetupPlan,
+  TARGET_IDS,
+} from "./plan.js";
+import {
+  renderDetectionSummary,
+  renderProgressLine,
+  renderRecap,
+} from "./plan.render.js";
+import { renderDryRun, setupFormatters } from "./setup.render.js";
+import type { Scope, ScopeSelection, SetupMode } from "./types.js";
 
 /**
- * The `--scope` flag + its `--global`/`--local` boolean sugars, shared by the
- * band-aware verbs (`setup`/`mcp`/`skills`). `completions`/`lsp` never carry
- * them — they are single-band installers.
+ * The `--scope` flag + its `--global`/`--local` boolean sugars. Registered by
+ * EVERY setup verb, including the single-scope ones: a flag that exists on some
+ * sub-verbs and not others is a grammar the user has to memorise, and the scope
+ * a single-scope target can honour is a question the target table answers.
+ *
+ * `--global` is a synonym of the default; it stays for scripts and for symmetry
+ * with `--local`.
  */
 const SCOPE_PARAMS: readonly ParamSpec[] = [
   {
     kind: "enum",
     name: "scope",
-    doc: "Which config band(s) to configure: project, global, or both.",
+    doc: "Where to configure: global (your home directory, the default), project (this repository), or both.",
     values: ["project", "global", "both"],
-    default: "both",
+    default: "global",
   },
   {
     kind: "boolean",
     name: "global",
-    doc: "Shorthand for --scope global (configure the user/home band).",
+    doc: "Shorthand for --scope global — configure your home directory.",
   },
   {
     kind: "boolean",
     name: "local",
-    doc: "Shorthand for --scope project (configure the per-project band).",
+    doc: "Shorthand for --scope project — configure this project only.",
   },
 ];
 
@@ -62,13 +91,47 @@ const SCOPE_PARAMS: readonly ParamSpec[] = [
  * The boolean sugars win over `--scope`; `--global` wins over `--local`.
  *
  * @param params - The coerced param bag.
- * @returns The resolved scope selection (defaults to `both`).
+ * @returns The resolved scope selection (defaults to `global`).
  */
 function resolveScope(params: Record<string, unknown>): ScopeSelection {
   if (params.global === true) return "global";
   if (params.local === true) return "project";
   const scope = params.scope;
-  return scope === "global" || scope === "project" ? scope : "both";
+  return scope === "project" || scope === "both" ? scope : "global";
+}
+
+/**
+ * Reject a sub-verb asked for a scope its target cannot hold.
+ *
+ * This is a usage error, not a skip: the user typed a contradiction, and
+ * correcting it is exactly what exit 2 means. The message names the scope the
+ * target DOES have and prints the command that works, so the correction is one
+ * paste rather than one manual page.
+ *
+ * @param mode - The sub-verb's target, or `all`.
+ * @param scope - The resolved selection.
+ * @throws PragmaError INVALID_INPUT when the target has no such scope.
+ */
+async function assertScopeIsPossible(
+  mode: SetupMode,
+  scope: ScopeSelection,
+): Promise<void> {
+  if (mode === "all" || scope === "both") return;
+  const { findTarget } = await import("./targets.js");
+  const target = findTarget(mode);
+  if (target === undefined || target.scopes.includes(scope as Scope)) return;
+  const only = target.scopes[0] as Scope;
+  const level = only === "global" ? "global only" : "per-project only";
+  const asked = scope === "global" ? "globally" : "per project";
+  const corrected =
+    only === "global"
+      ? `${BIN_NAME} setup ${mode}`
+      : `${BIN_NAME} setup ${mode} --local`;
+  throw new PragmaError({
+    code: "INVALID_INPUT",
+    message: `${mode} is ${level} — it cannot be configured ${asked}.`,
+    recovery: { message: `Run: ${corrected}` },
+  });
 }
 
 /** The exposed-to-MCP capability the run-all self-verb declares. */
@@ -101,38 +164,98 @@ const SUB_CAPABILITY = {
 
 /**
  * The one summon↔pragma seam per setup invocation: lazily load summon-core + the
- * generator ops, build the plan (detection up front), pick the prompt strategy
- * off `rt.interaction`, wire `rt.exec`, and return `execute` mapped back onto
- * {@link SetupResult}.
+ * generator ops, detect and plan, resolve the interaction mode, wire `rt.exec`,
+ * and return the plan with its outcomes filled in.
  *
  * NOTE: `rt.exec` carries NO per-call `cwd`. Unlike `create` (whose generator
- * emits RELATIVE paths jailed to `rt.cwd`), setup's ops build ABSOLUTE effect
- * paths themselves ($HOME/…, resolve(cwd,…)); the interpreter leaves absolute
- * paths unchanged, so no per-call write root is threaded. No stamping either —
- * setup writes symlinks / config / scripts, not generated source.
+ * emits RELATIVE paths jailed to `rt.cwd`), setup's targets build ABSOLUTE
+ * effect paths themselves; the interpreter leaves absolute paths unchanged, so
+ * no per-call write root is threaded. No stamping either — setup writes
+ * symlinks, config and scripts, not generated source.
  *
- * @param mode - Which entry point (`all` or one sub-verb).
- * @param rt - The per-invocation runtime (mutated: `rt.exec` is set).
- * @returns The `Task<SetupResult>` the dispatcher/MCP handler interprets.
- * @note Impure — runs each step's real detection; may throw EMPTY_RESULTS
- *   (direct `setup skills` with no skills) before returning a Task.
+ * @param mode - Which entry point (`all` or one target).
+ * @param rt - The per-invocation runtime (mutated: `rt.exec` and `rt.planData`).
+ * @param scope - The resolved scope selection.
+ * @returns The `Task<SetupPlan>` the dispatcher/MCP handler interprets.
+ * @note Impure — runs every target's real detection before returning a Task.
  */
 async function runSetup(
   mode: SetupMode,
   rt: PragmaRuntime,
   scope: ScopeSelection,
-): Promise<Task<SetupResult>> {
-  // Lazy dynamic imports (R1 lazy-React discipline): summon-core's barrel is
+): Promise<Task<SetupPlan>> {
+  await assertScopeIsPossible(mode, scope);
+
+  // Lazy dynamic imports (lazy-React discipline): summon-core's barrel is
   // React-free, and the non-TTY branch picks autoPrompt/mcpPrompt (never mounts
   // Ink), so `setup --yes` loads no React — the guard test enforces this.
-  const [summon, ops] = await Promise.all([
+  const [summon, projection, ops] = await Promise.all([
     import("@canonical/summon-core"),
+    import("@canonical/summon-core/projection"),
     import("./operations/setupGenerator.js"),
   ]);
 
-  const { generator, toResult } = await ops.buildSetupPlan(rt, mode, scope);
+  const input = setupModeInput(rt);
+  const run = await ops.buildSetupRun(rt, mode, scope, input.undo);
+  const interactionMode = resolveSetupMode(input, projection.decideInteraction);
+
+  // The dry-run seam: the kernel's `--dry-run` branch renders THIS instead of
+  // the raw effect dump, while its honest preview still runs underneath and
+  // still fails exactly when the real run would.
+  rt.planData = { ...run.plan, preview: true };
+
+  // Whether this invocation only PREVIEWS. The task below is driven either way
+  // — that is what makes the preview honest — so anything it says out loud has
+  // to know which of the two it is.
+  const previewing = interactionMode === "batch-dry-run";
 
-  const { isTTY, transport, yes, signal, abort } = rt.interaction ?? {
+  // A CONVERGED machine has no question to ask. Every row is `none` or `skip`,
+  // so nothing composes an effect — and the wizard's confirm gate then mounted
+  // Ink to render summon-core's "No operations planned." above a "Proceed?"
+  // over an empty tally. For a sub-verb, whose prompt list is empty, that
+  // contentless gate was the FIRST AND ONLY thing the user ever saw. The
+  // explanation existed the whole time (each row's `none` detail, one child row
+  // per file/editor marked `unchanged`) and was dropped at the render seam.
+  //
+  // So: report the plan instead of asking a question with no content. There is
+  // no `preview: true` here — the run really did complete. `applied({})` marks
+  // each `none` row `{status:"noop", note:"unchanged"}`, `wasApplied` is then
+  // true, and `setupFormatters.plain` renders the recap. That also retires a
+  // second defect: a non-interactive converged run used to print the misleading
+  // "Nothing was applied. Run again with --yes to apply." over an all-`none`
+  // plan. A run whose every DETECTION threw is not converged in this sense —
+  // its rows are skips that report `failed` — so it falls through to the normal
+  // path, which is the one that raises.
+  if (!previewing && run.plan.rows.every((row) => !isActionable(row.action))) {
+    const converged = run.applied({});
+    if (!planExitFailed(converged)) return pure<SetupPlan>(converged);
+  }
+
+  // Adaptation (b): a non-interactive run without `--yes` previews rather than
+  // mutating. It is the same plan the dry-run prints, plus one hint line, at
+  // exit 0 — the invocation completed a real read-only unit of work.
+  if (interactionMode === "refuse") {
+    return pure<SetupPlan>({ ...run.plan, preview: true });
+  }
+
+  // Say what was DETECTED before asking anything about it. The data has been
+  // sitting in `run.plan` since before the prompt list was built — `inkPrompt`
+  // mounts no React until the first Prompt effect — so this is a rendering gap,
+  // not an ordering one, and closing it is nearly free.
+  //
+  // It MUST be emitted here, before `execute` is driven: the summary and the
+  // Ink frame both write to stderr, and only a line written first lands in
+  // scrollback ABOVE the frame. `rt.report` is the non-Ink seam — `--quiet`
+  // silences it and it is a no-op over MCP — so no React is loaded to print it.
+  // A preview says nothing here: the plan table IS its output.
+  if (!previewing) {
+    const summary = renderDetectionSummary(run.plan, {
+      verbose: rt.globalFlags.verbose,
+    });
+    if (summary !== undefined) rt.report?.(summary);
+  }
+
+  const { transport, yes, signal, abort } = rt.interaction ?? {
     isTTY: false,
     transport: "cli" as const,
     yes: true,
@@ -140,10 +263,27 @@ async function runSetup(
 
   // TTY without --yes → the Ink wizard (recap + live progress). Its callbacks
   // ride rt.exec; `onCancel` threads the run's abort in so an in-Ink Ctrl-C
-  // during execution actually stops the writes (H2). No stamping (A5).
+  // during execution actually stops the writes.
   let task: Task<GeneratorResult>;
-  if (isTTY && !yes) {
-    const session = summon.inkPrompt(generator, { signal, onCancel: abort });
+  const wizard = interactionMode === "wizard";
+  if (wizard) {
+    const session = summon.inkPrompt(run.generator, {
+      signal,
+      onCancel: abort,
+    });
+    // Live progress in the PLAN's units, not the interpreter's: the wizard's
+    // default execution view is the per-effect transcript — right for `create`,
+    // whose unit of work IS the file, and wrong here, where one unit is one
+    // configured target and the transcript renders eighteen symlink rows for
+    // the row the plan called `skills  link  9 skills → 2 folders`. Each row
+    // event carries the SAME sentence `renderProgressLine` prints, so the
+    // watcher and the recap reader see one dialect. `--verbose` withholds the
+    // listener, which falls the wizard back to the full effect transcript —
+    // the same detected-only-unless-verbose rule the detection summary and
+    // doctor already follow.
+    if (rt.globalFlags.verbose !== true) {
+      run.setRowListener((event) => session.reportStep(event));
+    }
     rt.exec = {
       promptHandler: session.promptHandler,
       onEffectStart: session.onEffectStart,
@@ -152,7 +292,7 @@ async function runSetup(
       dispose: session.dispose,
       signal,
     };
-    task = summon.execute(generator, {
+    task = summon.execute(run.generator, {
       prompt: session.promptHandler,
       params: {},
       signal,
@@ -166,103 +306,173 @@ async function runSetup(
       onLog: (_level, message) => process.stderr.write(`${message}\n`),
       signal,
     };
-    task = summon.execute(generator, { prompt, params: {}, signal });
+    task = summon.execute(run.generator, { prompt, params: {}, signal });
   }
 
-  // execute yields a GeneratorResult; map it back onto setup's tagged result
-  // union (its --format json shape is frozen). The completion view is driven by
-  // controller phase, not this value, so mapping after execute is invisible to
-  // the wizard.
   return gen(function* () {
     const result = yield* $(task);
-    return toResult(result.answers);
+    const applied = run.applied(result.answers);
+
+    // Progress: one line per row on stderr for an unattended run (the Ink
+    // session already draws them for the wizard). stdout stays the data stream.
+    //
+    // A dry run reports NOTHING here. Its honest preview drives this very task
+    // with writes recorded, so the progress lines ran for real and announced
+    // "✓ config — installed" above a plan that had installed nothing.
+    if (!previewing && (!wizard || yes)) {
+      const width = Math.max(...applied.rows.map((row) => row.target.length));
+      for (const row of applied.rows) {
+        if (row.outcome === undefined) continue;
+        rt.report?.(renderProgressLine(row, width));
+      }
+    }
+
+    // A failed row exits 1, and the recap is still shown — partial success is
+    // first class, so the run reports every row before naming the ones that did
+    // not happen. The recap goes to stderr here because the error renderer owns
+    // stdout on a failing run.
+    if (planExitFailed(applied)) {
+      rt.report?.(renderRecap(applied));
+      const failed = applied.rows.filter(
+        (row) => row.outcome?.status === "failed",
+      );
+
+      // ONE failure reports itself. The row already carries the cause it was
+      // given ("`bun` is not found on your PATH") and a remedy that runs on
+      // this machine; replacing them with a count would throw away the only
+      // two sentences that say what is wrong and what to do about it.
+      const only = failed.length === 1 ? failed[0] : undefined;
+      if (only?.outcome !== undefined) {
+        throw new PragmaError({
+          code: "UNSUPPORTED",
+          message: `${only.target}: ${only.outcome.note ?? "the step did not complete"}`,
+          ...(only.outcome.remedy === undefined
+            ? {}
+            : { recovery: { message: only.outcome.remedy } }),
+        });
+      }
+
+      // Several failures: name every one with its own cause, then point at the
+      // recap above. A bare list of target names would make the reader re-run
+      // each one to find out why it failed.
+      const named = failed
+        .map(
+          (row) =>
+            `${row.target} (${row.outcome?.note ?? "no cause recorded"})`,
+        )
+        .join("; ");
+      throw new PragmaError({
+        code: "UNSUPPORTED",
+        message: `${failed.length} of ${planTally(applied).accountable} targets did not complete: ${named}.`,
+        recovery: {
+          message: `The other targets are configured. Re-run the ones that did not complete: ${failed
+            .map((row) => `\`${BIN_NAME} setup ${row.target}\``)
+            .join(", ")}.`,
+        },
+      });
+    }
+    return applied;
   });
 }
 
 /** Build a setup verb bound to its {@link SetupMode}. */
 function setupVerb(
-  path: VerbSpec<Record<string, unknown>, SetupResult>["path"],
+  path: VerbSpec<Record<string, unknown>, SetupPlan>["path"],
   summary: string,
   mode: SetupMode,
   capability: typeof SELF_CAPABILITY | typeof SUB_CAPABILITY,
-  extras: Partial<VerbSpec<Record<string, unknown>, SetupResult>> = {},
-): VerbSpec<Record<string, unknown>, SetupResult> {
+  extras: Partial<VerbSpec<Record<string, unknown>, SetupPlan>> = {},
+): VerbSpec<Record<string, unknown>, SetupPlan> {
   return {
     path,
     summary,
-    params: [],
-    output: { formatters: setupFormatters },
+    params: SCOPE_PARAMS,
+    output: {
+      formatters: setupFormatters,
+      // The kernel's dry-run branch renders the plan through this seam instead
+      // of dumping raw effects. Absent on every other verb, so nothing else
+      // changes shape.
+      formatPlan: (planData) => renderDryRun(planData as SetupPlan),
+    },
     capability,
     ...extras,
     run: (params, rt) =>
-      runSetup(mode, rt, resolveScope(params)) as unknown as Task<SetupResult>,
+      runSetup(mode, rt, resolveScope(params)) as unknown as Task<SetupPlan>,
   };
 }
 
 const setupAllVerb = setupVerb(
   ["setup"],
-  "Configure MCP, completions, skills, and the LSP for this project.",
+  "Set up your config file, TAB completion, the editor extension, MCP, and skills.",
   "all",
   SELF_CAPABILITY,
   {
-    params: SCOPE_PARAMS,
-    doc: "Runs the shell-completions, LSP, MCP, and skills installers as a single wizard: pick the steps, review the recap, then apply. The scope option targets the project band, the user/home band, or both.",
+    doc: "Shows what each target needs, then applies the ones you keep. Everything is configured in your home directory by default; the scope option moves the run to this project alone, or covers both. Without an attended terminal the plan is printed and nothing is written unless the run is explicitly confirmed.",
     examples: [
       { cmd: `${BIN_NAME} setup` },
       {
         cmd: `${BIN_NAME} setup --dry-run`,
-        note: "preview every step's effects",
+        note: "show the plan, write nothing",
       },
       {
-        cmd: `${BIN_NAME} setup --global`,
-        note: "configure only the user/home band",
+        cmd: `${BIN_NAME} setup --local`,
+        note: "configure this project instead of your home directory",
       },
       {
         cmd: `${BIN_NAME} setup mcp`,
-        note: "just the MCP server registration",
+        note: "only register the MCP server",
       },
     ],
   },
 );
 
+const configVerb = setupVerb(
+  ["setup", "config"],
+  "Create your global config file, filled in with the defaults.",
+  "config",
+  SUB_CAPABILITY,
+);
+
 const mcpVerb = setupVerb(
   ["setup", "mcp"],
-  `Register the ${BIN_NAME} MCP server in detected AI harnesses.`,
+  `Register the ${BIN_NAME} MCP server with the AI harnesses on this machine.`,
   "mcp",
   SUB_CAPABILITY,
-  { params: SCOPE_PARAMS },
 );
 
 const completionsVerb = setupVerb(
   ["setup", "completions"],
-  "Install the shell-completion script for your shell.",
+  "Install TAB completion for the shell you are running.",
   "completions",
   SUB_CAPABILITY,
 );
 
 const skillsVerb = setupVerb(
   ["setup", "skills"],
-  "Symlink discovered skills into each AI harness.",
+  "Link the skills you have installed into every AI harness that reads them.",
   "skills",
   SUB_CAPABILITY,
-  { params: SCOPE_PARAMS },
 );
 
 const lspVerb = setupVerb(
   ["setup", "lsp"],
-  "Ensure the Terrazzo LSP VS Code extension is installed.",
+  "Install the Terrazzo design-token extension into your VS Code-family editors.",
   "lsp",
   SUB_CAPABILITY,
 );
 
-/** The `setup` capability module (run-all self-verb + four CLI-only sub-verbs). */
+/** The `setup` capability module (run-all self-verb + five CLI-only sub-verbs). */
 export const setupModule: CapabilityModule = {
   name: "setup",
   verbs: [
     asVerb(setupAllVerb),
-    asVerb(mcpVerb),
+    asVerb(configVerb),
     asVerb(completionsVerb),
-    asVerb(skillsVerb),
     asVerb(lspVerb),
+    asVerb(mcpVerb),
+    asVerb(skillsVerb),
   ],
 };
+
+/** Re-exported so the covenant emitter and tests can name the target set. */
+export { TARGET_IDS };

package/src/capabilities/setup/shell.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Shell detection — the shell the user is RUNNING, not the one `/etc/passwd`
+ * records.
+ *
+ * The defect these pin: `$SHELL` is the LOGIN shell. It does not change when
+ * you start a different shell, so a user whose account says bash but who works
+ * in zsh was handed a bash completion script — and doctor then reported it
+ * green, for a shell they never open, while zsh had nothing. The failure is
+ * invisible until TAB does nothing months later, which is exactly why an
+ * unresolved shell must be reported rather than guessed.
+ */
+
+import { afterEach, describe, expect, it } from "vitest";
+import { detectShell, type ProcessEntry } from "./shell.js";
+
+/** A fake process tree: pid → entry, walked exactly as /proc would be. */
+const tree = (entries: Record<number, ProcessEntry>) => (pid: number) =>
+  entries[pid];
+
+const prevShell = process.env.SHELL;
+afterEach(() => {
+  process.env.SHELL = prevShell;
+});
+
+describe("the running shell wins over $SHELL", () => {
+  it("reports the shell that actually started this process", () => {
+    // The case from a real machine: login shell bash, working shell zsh.
+    process.env.SHELL = "/bin/bash";
+    const read = tree({
+      [process.ppid]: { name: "zsh", ppid: 100 },
+      100: { name: "systemd", ppid: 1 },
+    });
+    expect(detectShell(read)).toEqual({ kind: "detected", shell: "zsh" });
+  });
+
+  it("walks past the wrappers a CLI is usually reached through", () => {
+    // `npm run` / `bunx` / a shim script put node or sh between the shell and
+    // us, so the immediate parent is almost never the answer.
+    process.env.SHELL = "/bin/bash";
+    const read = tree({
+      [process.ppid]: { name: "node", ppid: 200 },
+      200: { name: "npm", ppid: 300 },
+      300: { name: "fish", ppid: 400 },
+    });
+    expect(detectShell(read)).toEqual({ kind: "detected", shell: "fish" });
+  });
+
+  it("strips the login dash and any path", () => {
+    const read = tree({ [process.ppid]: { name: "-zsh", ppid: 1 } });
+    expect(detectShell(read)).toEqual({ kind: "detected", shell: "zsh" });
+    const path = tree({ [process.ppid]: { name: "/usr/bin/bash", ppid: 1 } });
+    expect(detectShell(path)).toEqual({ kind: "detected", shell: "bash" });
+  });
+});
+
+describe("an unresolved shell is reported, never guessed", () => {
+  it("is ambiguous when only $SHELL has an opinion", () => {
+    // No shell in the ancestry — a CI runner, an editor task, a daemon. The
+    // login shell names a session that may not exist, so it is not an answer.
+    process.env.SHELL = "/bin/bash";
+    const read = tree({
+      [process.ppid]: { name: "node", ppid: 900 },
+      900: { name: "containerd", ppid: 1 },
+    });
+    expect(detectShell(read)).toEqual({ kind: "ambiguous", login: "bash" });
+  });
+
+  it("is unknown when nothing names a supported shell", () => {
+    process.env.SHELL = "/usr/bin/nu";
+    const read = tree({ [process.ppid]: { name: "init", ppid: 1 } });
+    expect(detectShell(read)).toEqual({ kind: "unknown" });
+  });
+
+  it("is unknown when $SHELL is unset and the tree is silent", () => {
+    process.env.SHELL = "";
+    const read = tree({ [process.ppid]: { name: "init", ppid: 1 } });
+    expect(detectShell(read)).toEqual({ kind: "unknown" });
+  });
+
+  it("gives up rather than walking an unbounded tree", () => {
+    // A cycle (or a very deep tree) must terminate.
+    process.env.SHELL = "";
+    const read = (pid: number): ProcessEntry => ({ name: "node", ppid: pid });
+    expect(detectShell(read)).toEqual({ kind: "unknown" });
+  });
+});