@codyswann/lisa 2.328.4 → 2.329.0

package/plugins/lisa/.codex-plugin/skills/lisa-detect-tooling/scripts/detect-tooling.mjs

@@ -22,9 +22,11 @@
  * @module detect-tooling
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 
+import { commandsIn } from "./commands.mjs";
+
 /** The tool named by the Expo template's scripts and its flows directory. */
 const MAESTRO = "maestro";
 
@@ -109,6 +111,128 @@ export function toolsFromScripts(pkg) {
   return found;
 }
 
+/** Where git hooks live, strongest signal first. */
+const HOOK_DIRECTORIES = [".husky", join(".git", "hooks")];
+
+/**
+ * Coding agents, which a PROJECT manifest must never try to provision.
+ *
+ * A hook that shells out to `claude` is real evidence of a real dependency, but
+ * `remoteEnv.tools` is the wrong place to answer it: agents belong to the
+ * machine, not the checkout, and each is installed by its vendor's own method
+ * into a version directory it manages itself. Pinning one as a release archive
+ * would fight the self-updater that owns that directory.
+ *
+ * That layer is `lisa-setup-workstation`. Named here rather than imported from
+ * it, because a detector that stops working when a sibling skill is absent is
+ * worse than one carrying six strings.
+ *
+ * Deliberately NOT extended to `gh`, `bws`, `aws` or `sonar`: those genuinely
+ * belong in a project manifest, and `gh` going undeclared is the incident this
+ * skill was written after.
+ */
+const WORKSTATION_PROVISIONED = new Set([
+  "claude",
+  "codex",
+  "cursor-agent",
+  "opencode",
+  "agy",
+  "copilot",
+]);
+
+/**
+ * Tools a git hook runs — the strongest signal a project can give.
+ *
+ * Stronger than an npm script, because a hook runs on EVERY commit and push
+ * whether anyone asked or not. A container missing one of these cannot commit at
+ * all; the failure arrives mid-task, unattended, at the moment of use.
+ *
+ * The worst shape is the guarded one. This repository's pre-commit hook wraps
+ * its secret scan in `command -v gitleaks`, so on a machine without gitleaks the
+ * scan is SKIPPED SILENTLY — the hook passes, the commit succeeds, and nothing
+ * was scanned. A guard makes the absence invisible exactly where it matters
+ * most, which is why a probed name counts as evidence rather than being read as
+ * "optional".
+ * @param {string} cwd Project root.
+ * @returns {Map<string, string>} Tool name to the hook that proves it.
+ */
+export function toolsFromGitHooks(cwd) {
+  const found = new Map();
+  for (const directory of HOOK_DIRECTORIES) {
+    const full = join(cwd, directory);
+    let names = [];
+    try {
+      names = readdirSync(full);
+    } catch {
+      continue;
+    }
+    for (const name of names.sort()) {
+      // `.sample` files ship with git and run nothing.
+      if (name.endsWith(".sample")) continue;
+      let body;
+      try {
+        body = readFileSync(join(full, name), "utf8");
+      } catch {
+        continue;
+      }
+      for (const tool of commandsIn(body)) {
+        if (!found.has(tool)) found.set(tool, `git hook ${directory}/${name}`);
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Tools an npm script invokes, discovered rather than matched against a list.
+ *
+ * `toolsFromScripts` answers "which of the tools I already know about appear
+ * here". This answers the open question — what does this project actually RUN —
+ * which is the one that finds a tool nobody thought to add. An Expo project
+ * invoking `eas` from eight scripts produced nothing under the old shape,
+ * because `eas` was not in `KNOWN_TOOLS`.
+ * @param {object|null} pkg Parsed package.json.
+ * @returns {Map<string, string>} Tool name to the script that proves it.
+ */
+export function toolsDiscoveredInScripts(pkg) {
+  const found = new Map();
+  for (const [name, body] of Object.entries(pkg?.scripts ?? {})) {
+    if (typeof body !== "string") continue;
+    for (const tool of commandsIn(body)) {
+      if (found.has(tool)) continue;
+      found.set(tool, `npm script "${name}": ${body.trim().slice(0, 60)}`);
+    }
+  }
+  return found;
+}
+
+/**
+ * Whether the package manager already puts this binary on the local path.
+ *
+ * A dependency's binary lands in `node_modules/.bin`, where npm scripts resolve
+ * it without it ever being on PATH. Proposing a manifest entry for one is noise,
+ * and noise is how a detector teaches people to skim it.
+ *
+ * Only meaningful once dependencies are installed, which is why
+ * `dependenciesInstalled` exists rather than this quietly returning false on a
+ * fresh clone and over-proposing every dev tool in the project.
+ * @param {string} cwd Project root.
+ * @param {string} tool Tool name.
+ * @returns {boolean} Whether npm already provides it.
+ */
+export function providedByNodeModules(cwd, tool) {
+  return existsSync(join(cwd, "node_modules", ".bin", tool));
+}
+
+/**
+ * Whether `node_modules` is populated, so its absence can be reported.
+ * @param {string} cwd Project root.
+ * @returns {boolean} Whether dependencies are installed.
+ */
+export function dependenciesInstalled(cwd) {
+  return existsSync(join(cwd, "node_modules", ".bin"));
+}
+
 /**
  * MCP servers that are access substrates rather than evidence for a CLI.
  *
@@ -330,8 +454,14 @@ export function detectTooling(cwd = process.cwd()) {
   const notes = readJson(join(cwd, ".lisa", "secret-notes.json"));
 
   const declared = declaredTools(config);
+  // Curated signals carry a vetted `why`. Discovered ones carry only the fact
+  // that the project runs the thing — weaker prose, identical standing as
+  // evidence, and the only kind that can find a tool nobody listed.
+  const hooks = toolsFromGitHooks(cwd);
   const signals = [
+    hooks,
     toolsFromScripts(pkg),
+    toolsDiscoveredInScripts(pkg),
     toolsFromMcp(mcp),
     toolsFromSecretNotes(notes),
     toolsFromQuality(config, pkg, cwd),
@@ -343,8 +473,11 @@ export function detectTooling(cwd = process.cwd()) {
       if (declared.has(tool)) continue;
       // Already provided by the package manager, so there is nothing to pin.
       if (satisfiedByNpm(pkg, tool)) continue;
+      if (providedByNodeModules(cwd, tool)) continue;
+      // Real dependency, wrong manifest — the workstation layer owns it.
+      if (WORKSTATION_PROVISIONED.has(tool)) continue;
       const entry = merged.get(tool) ?? { evidence: [] };
-      entry.evidence.push(evidence);
+      if (!entry.evidence.includes(evidence)) entry.evidence.push(evidence);
       merged.set(tool, entry);
     }
   }
@@ -352,12 +485,35 @@ export function detectTooling(cwd = process.cwd()) {
   return [...merged.entries()]
     .map(([name, entry]) => ({
       name,
-      why: KNOWN_TOOLS[name]?.why ?? "",
+      why: KNOWN_TOOLS[name]?.why ?? discoveredWhy(name, hooks.has(name)),
       evidence: entry.evidence,
+      // Says which vocabulary the `why` came from, so a reader can weigh it.
+      // A curated entry has been thought about; a discovered one has only been
+      // observed.
+      source: Object.hasOwn(KNOWN_TOOLS, name) ? "curated" : "discovered",
     }))
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/**
+ * The `why` for a tool nobody wrote prose for.
+ *
+ * Every proposal must carry one — a proposal without a reason is an assertion,
+ * and this program's whole boundary is that it asserts nothing. So a discovered
+ * tool states the observation plainly rather than borrowing confidence it has
+ * not earned.
+ * @param {string} name Tool name.
+ * @param {boolean} fromHook Whether a git hook runs it.
+ * @returns {string} A reason a reader can check.
+ */
+export function discoveredWhy(name, fromHook) {
+  return fromHook
+    ? `A git hook runs \`${name}\` on every commit or push, and nothing ` +
+        `declares it — a machine without it fails at commit time, or skips the ` +
+        `check silently if the hook guards it.`
+    : `An npm script invokes \`${name}\`, and nothing puts it on PATH.`;
+}
+
 /**
  * The manifest entries an operator can paste, with the parts only they supply.
  *
@@ -438,8 +594,18 @@ if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
     console.log(
       `${proposals.length} tool(s) look required but are not declared:\n`
     );
+    if (!dependenciesInstalled(process.cwd())) {
+      // Without node_modules there is no way to tell a tool that needs PATH
+      // from one npm already provides, so every dev dependency looks missing.
+      // Said out loud rather than silently over-proposing.
+      console.log(
+        "note: dependencies are not installed, so binaries npm would provide " +
+          "cannot be\n      excluded. Run the install first for a shorter, " +
+          "more accurate list.\n"
+      );
+    }
     for (const proposal of proposals) {
-      console.log(`  ${proposal.name}`);
+      console.log(`  ${proposal.name}  [${proposal.source}]`);
       console.log(`    why: ${proposal.why}`);
       for (const evidence of proposal.evidence) {
         console.log(`    evidence: ${evidence}`);

package/plugins/lisa/.codex-plugin/skills/lisa-setup-workstation/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: lisa-setup-workstation
+description: "Prepare a machine — a fresh…"
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Setup Workstation: $ARGUMENTS
+
+Get a machine ready to run agents. No checkout required.
+
+## Why this exists separately
+
+`lisa-setup-local-env` reads `remoteEnv.tools` — a **project's** declared toolchain — so it
+needs a checkout to exist before it can answer anything. That leaves a gap at the start:
+a bare laptop or an empty container has no repository yet, and therefore nothing to ask.
+
+This skill fills that gap and stops there. It describes a **machine**, never a project:
+
+```text
+workstation  ->  git clone  ->  lisa-detect-tooling  ->  lisa-setup-local-env
+```
+
+Project-scoped tools stay in `remoteEnv.tools` where they belong. Nothing here reads a
+repository, and nothing here duplicates that manifest.
+
+## Usage
+
+```sh
+node scripts/cli.mjs                              # report what is present and missing
+node scripts/cli.mjs --install                    # install what is missing
+node scripts/cli.mjs --install --agents=claude,codex   # only these agents
+node scripts/cli.mjs --provider=bitwarden         # credential manager (asked if a TTY)
+node scripts/cli.mjs --json                       # machine-readable plan
+node scripts/cli.mjs --print-dockerfile           # an image that runs this same script
+```
+
+Nothing is installed or written without `--install`. Exit status is non-zero when a required
+tool is absent or an install fails, so this is usable as a gate.
+
+## Ephemerality is not a mode
+
+There is no Docker branch anywhere in this skill. A container gets a throwaway `$HOME` and
+dies with it; a laptop keeps its own. Same code path either way — so the rarely-run one
+cannot rot, which is the failure mode a second install path eventually always has.
+
+`--print-dockerfile` emits an image rather than shipping a committed one, so the image cannot
+drift from the catalogue it provisions. It deliberately bakes in **no repository**: clone
+inside the container, then run `lisa-detect-tooling` and `lisa-setup-local-env` for that
+project's own tools.
+
+```sh
+node scripts/cli.mjs --print-dockerfile --agents=claude,codex --provider=bitwarden > Dockerfile
+docker build -t lisa-workstation . && docker run --rm -it lisa-workstation
+```
+
+## Already-installed wins, however it got there
+
+A tool present by **any** means is reported and left alone. That dissolves the "Homebrew or
+`~/.local/bin`" question entirely: we never contend for ownership of a tool someone else's
+package manager installed, and never shadow it with an earlier PATH entry that would silently
+win over their upgrades. The report names where each tool came from so the operator can see
+why it was skipped.
+
+Running twice installs nothing the second time, and says so rather than going quiet — silence
+reads as "did nothing because it broke".
+
+## Install method is a per-tool property, not a global policy
+
+The obvious design — put every binary in `~/.local/bin` so one code path serves a laptop and a
+container alike — is wrong, and the agents show why:
+
+```text
+claude        -> ~/.local/share/claude/versions/2.1.221
+cursor-agent  -> ~/.local/share/cursor-agent/versions/2026.07.16-899851b
+codex         -> ~/.codex/packages/standalone/current/bin/codex
+```
+
+Each vendor manages its own version directory, and `~/.local/bin` holds only a **symlink**.
+Writing a raw binary there breaks the vendor's self-updater, which expects to swap a link
+target and would instead find a real file in its way.
+
+So each catalogue entry declares its own method, and the honest cost is recorded with it:
+
+| kind | pinned | checksummed | notes |
+| --- | --- | --- | --- |
+| `release-zip` / `release-tar` | yes | yes | reuses the remote-env installer |
+| `npm-global` | no | no | vendor registry |
+| `vendor-script` | no | no | pipes a fetched script to a shell |
+| `manual` | n/a | n/a | no headless installer published |
+| `required` | n/a | n/a | expected from the OS or base image |
+
+`vendor-script` is a real weakening of the guarantee `assertPinned` exists to provide, so the
+report **names every unchecksummed install** rather than blending them in. Installing them
+trusts the vendor's script at fetch time. The alternative — repackaging vendor binaries
+ourselves — would break the self-updaters that own those directories.
+
+## The credential manager is asked, never assumed
+
+`lisa-secrets-access` already treats the provider as an axis: Bitwarden, 1Password, Doppler,
+Vault, AWS, or plain environment variables. A bootstrap that installed `bws` unconditionally
+would contradict that — pushing every workstation onto one vendor and quietly making the
+others second-class.
+
+So the provider is a question, `none` is a first-class answer, and only the selected one is
+installed. Installing all of them would leave four unused credential CLIs on the machine,
+each an extra thing to keep patched for no benefit.
+
+Headless is the primary mode, so with no TTY and no `--provider`, the answer is `none` — not
+a prompt that would hang a container build forever. A misspelled provider stops the run
+instead of falling back, because quietly provisioning the wrong credential manager is worse
+than stopping.
+
+## What it will not do
+
+- **Read a repository.** That is the next step, not this one.
+- **Install a credential manager you did not pick.**
+- **Reinstall over a tool that is already there**, whatever installed it.
+- **Install anything without `--install`.**
+- **Install `agy`.** Antigravity publishes no headless installer; it is reported as manual
+  with a pointer, because "not installed" and "cannot be installed by this tool" are
+  different answers to the operator.

package/plugins/lisa/.codex-plugin/skills/lisa-setup-workstation/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Setup Workstation"
+short_description: "Prepare a machine — a fresh…"
+default_prompt:
+  - "Use $lisa-setup-workstation: Prepare a machine — a fresh…."

package/plugins/lisa/.codex-plugin/skills/lisa-setup-workstation/scripts/catalogue.mjs

@@ -0,0 +1,262 @@
+/**
+ * What a workstation can hold, and how each piece is installed.
+ *
+ * This is the layer beneath `remoteEnv.tools`: it describes a MACHINE, not a
+ * project, so nothing here is read from a checkout and no repository needs to
+ * exist. The project-scoped manifest still owns project-scoped tools.
+ *
+ * ## Install method is a per-tool property, not a global policy
+ *
+ * The obvious design — put every binary in `~/.local/bin` so one code path
+ * serves a laptop and a container alike — is wrong, and the agents show why:
+ *
+ *     claude       -> ~/.local/share/claude/versions/2.1.221
+ *     cursor-agent -> ~/.local/share/cursor-agent/versions/2026.07.16-899851b
+ *     codex        -> ~/.codex/packages/standalone/current/bin/codex
+ *
+ * Each vendor manages its own version directory and `~/.local/bin` holds only a
+ * SYMLINK. Writing a raw binary there breaks the vendor's self-updater, which
+ * expects to swap a link target and would instead find a real file in its way.
+ *
+ * So each entry declares its own method, and the honest cost is recorded with
+ * it: a `vendor-script` entry is NOT pinned and NOT checksummed. That is a real
+ * weakening of the guarantee `assertPinned` exists to provide, so the kind is
+ * visible in the catalogue and in the report rather than blended in with
+ * checksummed entries. A reader can see which tools are trusted to a vendor.
+ * @module catalogue
+ */
+
+/** Lisa's supported coding agents. Kept in sync with the harness list. */
+export const AGENTS = [
+  {
+    name: "claude",
+    label: "Claude Code",
+    kind: "vendor-script",
+    // The vendor script installs into ~/.local/share/claude/versions/<v> and
+    // links ~/.local/bin/claude at it, which is why we must not write there.
+    script: "https://claude.ai/install.sh",
+    selfUpdates: true,
+  },
+  {
+    name: "codex",
+    label: "Codex",
+    kind: "npm-global",
+    package: "@openai/codex",
+    selfUpdates: true,
+  },
+  {
+    name: "cursor-agent",
+    label: "Cursor",
+    kind: "vendor-script",
+    script: "https://cursor.com/install",
+    selfUpdates: true,
+  },
+  {
+    name: "opencode",
+    label: "OpenCode",
+    kind: "vendor-script",
+    script: "https://opencode.ai/install",
+    // Installs to its own directory and appends a PATH line to the user's
+    // shell rc — which a non-interactive container never sources. Declared
+    // here so the run puts it on PATH itself rather than reporting a binary
+    // that is on disk as missing.
+    binDir: "~/.opencode/bin",
+    selfUpdates: true,
+  },
+  {
+    name: "agy",
+    label: "Antigravity",
+    kind: "manual",
+    // No headless installer published. Reported as absent with a pointer
+    // rather than silently skipped, because "not installed" and "cannot be
+    // installed by this tool" are different answers to the operator.
+    note: "no headless installer published; install from the vendor",
+  },
+  {
+    name: "copilot",
+    label: "GitHub Copilot CLI",
+    kind: "npm-global",
+    package: "@github/copilot",
+    selfUpdates: false,
+  },
+];
+
+/**
+ * Credential managers, one of which a workstation may use.
+ *
+ * A CHOICE, not a fixed tool. `lisa-secrets-access` already treats the provider
+ * as an axis — bitwarden, 1password, doppler, vault, aws, or plain `env` — and
+ * a bootstrap that installed `bws` unconditionally would contradict that,
+ * pushing every workstation onto one vendor and quietly making the others
+ * second-class.
+ *
+ * `none` is a first-class answer. A machine using plain environment variables
+ * is a supported configuration, not a degraded one, so it must be selectable
+ * rather than merely what happens when a question is skipped.
+ *
+ * Only the SELECTED provider is installed. Installing all of them would put
+ * four unused credential CLIs on a machine, each an extra thing to keep patched
+ * for no benefit.
+ */
+export const PROVIDERS = [
+  {
+    name: "bitwarden",
+    binary: "bws",
+    label: "Bitwarden Secrets Manager",
+    // The one genuinely pinned credential CLI: Bitwarden publishes per-platform
+    // archives that can carry a checksum, and a credential bootstrap is exactly
+    // where an unverified download matters most.
+    kind: "release-zip",
+    version: "2.1.0",
+    platforms: {
+      "linux-x64": {
+        url: "https://github.com/bitwarden/sdk-sm/releases/download/bws-v2.1.0/bws-x86_64-unknown-linux-gnu-2.1.0.zip",
+        sha256:
+          "ba8233c3a4aee5d43e3c73bbd04d99e9bc5aba13bbbfd06d89b073abe732b860",
+      },
+      "linux-arm64": {
+        url: "https://github.com/bitwarden/sdk-sm/releases/download/bws-v2.1.0/bws-aarch64-unknown-linux-gnu-2.1.0.zip",
+        sha256:
+          "18253757286e119d450133a87eb463bf8c1ce418ce24c834f4f250d60cba6f9e",
+      },
+    },
+  },
+  {
+    name: "1password",
+    binary: "op",
+    label: "1Password CLI",
+    kind: "vendor-script",
+    note: "install from 1password.com/downloads/command-line",
+  },
+  {
+    name: "doppler",
+    binary: "doppler",
+    label: "Doppler CLI",
+    kind: "vendor-script",
+    script: "https://cli.doppler.com/install.sh",
+  },
+  {
+    name: "vault",
+    binary: "vault",
+    label: "HashiCorp Vault CLI",
+    kind: "vendor-script",
+    note: "install from developer.hashicorp.com/vault/install",
+  },
+  {
+    name: "aws",
+    binary: "aws",
+    label: "AWS Secrets Manager (via AWS CLI)",
+    kind: "vendor-script",
+    // Deliberately the same entry as the general AWS CLI below: a provider of
+    // `aws` needs exactly that binary and nothing extra.
+    note: "uses the AWS CLI, which is also a general tool",
+  },
+  {
+    name: "none",
+    binary: null,
+    label: "No credential manager (plain environment variables)",
+    kind: "none",
+    note: "supported configuration; nothing is installed",
+  },
+];
+
+/**
+ * Tools every workstation needs regardless of project or provider.
+ */
+export const TOOLS = [
+  {
+    name: "git",
+    label: "git",
+    kind: "required",
+    note: "expected from the OS or base image",
+  },
+  {
+    name: "node",
+    label: "Node.js",
+    kind: "required",
+    minVersion: "22",
+    note: "expected from the OS or base image; the installers run on it",
+  },
+  {
+    name: "gh",
+    label: "GitHub CLI",
+    kind: "release-tar",
+    version: "2.83.0",
+    platforms: {
+      "linux-x64": {
+        url: "https://github.com/cli/cli/releases/download/v2.83.0/gh_2.83.0_linux_amd64.tar.gz",
+        sha256:
+          "a5cf6cdb40fc67751adf561126b3314044779cea81ba4f254fbe8e9a69f1676f",
+        binary: "gh_2.83.0_linux_amd64/bin/gh",
+      },
+      "linux-arm64": {
+        url: "https://github.com/cli/cli/releases/download/v2.83.0/gh_2.83.0_linux_arm64.tar.gz",
+        sha256:
+          "12311e320d4cfdb54d7fa2d58cd1e3a2ccb4c12e1c3abb32b0a2e48bd0f991bf",
+        binary: "gh_2.83.0_linux_arm64/bin/gh",
+      },
+      "darwin-arm64": {
+        url: "https://github.com/cli/cli/releases/download/v2.83.0/gh_2.83.0_macOS_arm64.zip",
+        sha256:
+          "fecba907bc361d5e33620dbf1145f11432c39fb2b388a839463cfbb89a84820b",
+        binary: "gh_2.83.0_macOS_arm64/bin/gh",
+      },
+    },
+  },
+  {
+    name: "aws",
+    label: "AWS CLI v2",
+    kind: "aws-cli",
+    // Not expressible as release-zip: the artifact is a ~73 MB archive
+    // containing an installer, not a single binary on PATH. It gets its own
+    // kind rather than a vendor-script URL because the steps in between —
+    // unzip, then `./aws/install` with an explicit prefix — are the whole job.
+    note: "archive wraps an installer rather than a binary",
+    selfUpdates: false,
+  },
+  {
+    name: "sonar",
+    label: "SonarQube CLI",
+    kind: "vendor-script",
+    // The vendor's real installer. The plausible-looking `sonarsource.com/install`
+    // that was here first 404s, and because a 404 piped to a shell exits 0, it
+    // was reported as installed on a machine that had no `sonar` at all.
+    script:
+      "https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh",
+    // Same shell-rc assumption as OpenCode.
+    binDir: "~/.local/share/sonarqube-cli/bin",
+    selfUpdates: true,
+  },
+];
+
+/** Install kinds this tool can actually perform, versus report only. */
+export const INSTALLABLE = new Set([
+  "release-zip",
+  "release-tar",
+  "npm-global",
+  "vendor-script",
+  "aws-cli",
+]);
+
+/** Kinds whose artifact is verified against a published checksum. */
+export const CHECKSUMMED = new Set(["release-zip", "release-tar"]);
+
+/**
+ * Every directory a workstation must have on PATH.
+ *
+ * Vendors that manage their own version directory append a PATH line to the
+ * user's shell rc, which a non-interactive run — a container build, a cron, an
+ * agent — never sources. Collecting them here means one place decides what PATH
+ * must contain, used identically by the runtime and by the emitted Dockerfile.
+ * @param {string} home The home directory to expand `~` against.
+ * @returns {string[]} Absolute directories, most specific last.
+ */
+export function pathDirs(home) {
+  const declared = [...AGENTS, ...PROVIDERS, ...TOOLS]
+    .map(entry => entry.binDir)
+    .filter(Boolean)
+    .map(dir => dir.replace(/^~/, home));
+  // ~/.local/bin first: it is where the pinned, checksummed binaries land, and
+  // those must win over whatever an image happens to ship under the same name.
+  return [`${home}/.local/bin`, ...declared];
+}