@codyswann/lisa 2.327.0 → 2.328.0

package/plugins/lisa-agy/skills/lisa-detect-tooling/scripts/detect-tooling.mjs

@@ -361,9 +361,11 @@ export function detectTooling(cwd = process.cwd()) {
 /**
  * The manifest entries an operator can paste, with the parts only they supply.
  *
- * Returns both lists because a platform-specific archive needs both: an
- * `install` entry for the surface it is built for, and a `require` entry so the
- * other surface still asserts the tool instead of silently ignoring it.
+ * A release archive is proposed as a `platforms` map rather than a single URL
+ * plus `surfaces: ["remote"]`. The old shape could express only one artifact, so
+ * keeping a Linux binary off a laptop meant excluding the tool from laptops
+ * altogether — which is how `bws` and `gh` came to be required on a developer
+ * machine and installable only in a container.
  * @param {{name: string}} proposal One detected tool.
  * @returns {{install: object[], require: object[]}} Manifest skeletons.
  */
@@ -394,23 +396,33 @@ export function proposedEntries(proposal) {
       require: [],
     };
   }
-  // A release archive is built for one platform, so it is proposed as
-  // remote-install plus a local `require`. Proposing only the install entry
-  // produced a manifest that either offered a Linux binary to a laptop or —
-  // once narrowed to remote — stopped checking for the tool locally at all.
-  // Both halves or neither.
+  // A release archive is built for one platform, so every platform the project
+  // is developed or built on needs its own block — with its own install method,
+  // because a vendor may ship a tarball for one and a zip for another, as gh
+  // does. Both containers and laptops are proposed: a tool the manifest can
+  // only install remotely is one every developer installs by hand or does
+  // without.
+  //
+  // The placeholders stay unresolved on purpose. A guessed URL is an artifact
+  // the checksum cannot vouch for, which is the one property that makes a
+  // pinned entry worth reviewing.
+  const archive = platform => ({
+    install: "<release-tar or release-zip, whichever this platform ships>",
+    url: `<release url for this exact version, for ${platform}>`,
+    sha256: `<sha256 published with the ${platform} release>`,
+  });
   return {
     install: [
       {
         name: proposal.name,
         version: "<pin>",
-        install: "release-tar",
-        url: "<release url for this exact version, for the remote platform>",
-        sha256: "<sha256 published with that release>",
-        surfaces: ["remote"],
+        platforms: {
+          "linux-x64": archive("linux-x64"),
+          "darwin-arm64": archive("darwin-arm64"),
+        },
       },
     ],
-    require: [{ name: proposal.name, surfaces: ["local"] }],
+    require: [],
   };
 }
 

package/plugins/lisa-agy/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -73,8 +73,16 @@ function bindingsFor(surface) {
   return SURFACE_BINDINGS[surface] ?? ["repository"];
 }
 
-/** Install methods the toolchain runner supports. */
-const INSTALL_METHODS = new Set(["release-zip", "npm-global"]);
+/**
+ * Install methods the toolchain runner supports.
+ *
+ * `release-tar` was missing here while the runner had supported it for as long
+ * as gh has been pinned — so this validator would have rejected the project's
+ * own manifest, and the only reason nobody hit it is that nothing ran the two
+ * against each other. Kept in step with `assertPinned` in `toolchain.mjs`,
+ * which is the list that actually decides.
+ */
+const INSTALL_METHODS = new Set(["release-zip", "release-tar", "npm-global"]);
 
 /**
  * Validate the `secrets` block.
@@ -143,6 +151,44 @@ export function validateSecrets(secrets) {
   return problems;
 }
 
+/**
+ * Validate the artifact half of one install entry.
+ *
+ * Split out because the same obligations apply whether the fields sit directly
+ * on the entry or inside a per-platform block: a method must be one Lisa can
+ * execute, an archive must carry a checksum, and an npm install must name a
+ * package. Duplicating those three rules per shape is how one shape ends up
+ * quietly weaker than the other.
+ * @param {string} label How to name this entry in a message.
+ * @param {object} entry The entry or platform block.
+ * @param {string[]} problems Accumulator.
+ */
+function validateInstallArtifact(label, entry, problems) {
+  if (!INSTALL_METHODS.has(entry.install)) {
+    problems.push(
+      `remoteEnv install ${label} has method ${JSON.stringify(entry.install)}. ` +
+        `Supported: ${[...INSTALL_METHODS].join(", ")}.`
+    );
+    return;
+  }
+  // Both archive kinds, not just zip. A tarball pinned without a checksum
+  // trusts whatever the URL serves today exactly as much as a zip does, and
+  // checking only one of them meant the tool Lisa's guardrails shell out to —
+  // gh, which ships a tarball on Linux — was the one going unverified.
+  if (
+    (entry.install === "release-zip" || entry.install === "release-tar") &&
+    !(entry.url && entry.sha256)
+  ) {
+    problems.push(
+      `remoteEnv install ${label} needs both url and sha256. A pinned ` +
+        `version with no checksum still trusts whatever the URL serves today.`
+    );
+  }
+  if (entry.install === "npm-global" && !entry.package) {
+    problems.push(`remoteEnv install ${label} needs a package`);
+  }
+}
+
 /**
  * Validate the `remoteEnv` block.
  * @param {object|undefined} remoteEnv The block, if present.
@@ -163,21 +209,37 @@ export function validateRemoteEnv(remoteEnv) {
     if (!tool.version) {
       problems.push(`remoteEnv install "${tool.name}" has no pinned version`);
     }
-    if (!INSTALL_METHODS.has(tool.install)) {
+    // A flat entry means one artifact serves every platform — true of npm-global
+    // and of nothing else. Anything downloaded is platform-specific, so those
+    // declare a block per platform and each block is validated in full: a
+    // half-filled map is the failure this shape exists to prevent, and it is
+    // invisible until someone runs setup on the platform that was left out.
+    if (tool.platforms === undefined) {
+      validateInstallArtifact(`"${tool.name}"`, tool, problems);
+      continue;
+    }
+    if (
+      typeof tool.platforms !== "object" ||
+      tool.platforms === null ||
+      Array.isArray(tool.platforms)
+    ) {
       problems.push(
-        `remoteEnv install "${tool.name}" has method ${JSON.stringify(tool.install)}. ` +
-          `Supported: ${[...INSTALL_METHODS].join(", ")}.`
+        `remoteEnv install "${tool.name}" has a platforms field that is not an ` +
+          `object keyed by <platform>-<arch>. Omit it when one artifact serves ` +
+          `every platform.`
       );
       continue;
     }
-    if (tool.install === "release-zip" && !(tool.url && tool.sha256)) {
+    const platforms = Object.entries(tool.platforms);
+    if (platforms.length === 0) {
       problems.push(
-        `remoteEnv install "${tool.name}" needs both url and sha256. A pinned ` +
-          `version with no checksum still trusts whatever the URL serves today.`
+        `remoteEnv install "${tool.name}" declares platforms but lists none, so ` +
+          `it can never be installed anywhere.`
       );
+      continue;
     }
-    if (tool.install === "npm-global" && !tool.package) {
-      problems.push(`remoteEnv install "${tool.name}" needs a package`);
+    for (const [platform, block] of platforms) {
+      validateInstallArtifact(`"${tool.name}" (${platform})`, block, problems);
     }
   }
 

package/plugins/lisa-agy/skills/lisa-setup-local-env/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: lisa-setup-local-env
+description: "Bring a developer's machine in line with the toolchain the project declares. Reports every tool in remoteEnv.tools that is missing, outdated, or unpinned for this platform, and installs the missing ones into ~/.local/bin from the same pinned, checksummed entries the remote surfaces use — but only when asked. Same manifest, same pins, same installers as lisa-setup-remote-env; what differs is consent and that the pin is a floor rather than an equality. Run it on a fresh checkout, after a manifest change, or when a tool fails at the moment of use."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Setup Local Environment: $ARGUMENTS
+
+Make this machine match what the project says it needs.
+
+## Why this exists separately
+
+`remoteEnv.tools` was always the manifest for **every** surface, and the executor always
+understood `local`. What did not exist was a way to ask for it. The only path ran a file named
+`setup-remote-env.mjs`, out of a directory named `lisa-remote-env`, via a skill named
+`lisa-setup-remote-env` — and it only existed at all once someone had provisioned a *remote*
+environment, because that is what writes it into the repository.
+
+So the machine most likely to be missing a tool was the one with no way to ask about it.
+
+This skill is that surface. It adds no manifest, no pins, and no installer: it imports the
+ones the remote flow owns. A second installer would be a second thing to keep honest, and the
+one people run least is the one that rots.
+
+## Usage
+
+```sh
+node scripts/local-env.mjs                  # report what diverges
+node scripts/local-env.mjs --install-tools  # install what is missing
+node scripts/local-env.mjs --json           # machine-readable plan
+```
+
+Exit status is non-zero when a tool cannot be resolved, so this is usable as a gate.
+
+## What differs from a container
+
+Two things, and both are because a person is here.
+
+**Consent.** A container is disposable and provisions itself silently — that is the whole
+point of it. A laptop belongs to someone, and putting pinned binaries into their
+`~/.local/bin` uninvited is not ours to decide. Nothing installs until `--install-tools`.
+Reporting happens either way, because knowing the machine diverges from what the project
+declares is most of the value.
+
+**The pin is a floor, not an equality.** A container should hold exactly the pinned version;
+it exists to be reproducible. A developer's machine is shared with every other project they
+work on, so installing a pinned binary ahead of a **newer** one already on `PATH` is a
+downgrade this project imposed on all of them. A newer tool is reported as `newer` and left
+alone. Older, or absent, is an install.
+
+## Platform pins
+
+An install entry either serves every platform — true of `npm-global` and nothing else — or
+declares a `platforms` map keyed `<platform>-<arch>`, each block carrying its own `install`
+method, `url`, and `sha256`:
+
+```json
+{
+  "name": "gh",
+  "version": "2.83.0",
+  "platforms": {
+    "linux-x64":    { "install": "release-tar", "url": "...linux_amd64.tar.gz", "sha256": "...", "binary": "gh_2.83.0_linux_amd64/bin/gh" },
+    "darwin-arm64": { "install": "release-zip", "url": "...macOS_arm64.zip",    "sha256": "...", "binary": "gh_2.83.0_macOS_arm64/bin/gh" }
+  }
+}
+```
+
+The method lives **inside** each block because it varies: gh publishes a `.tar.gz` for Linux
+and a `.zip` for macOS, so a single method would have forced one platform onto an archive kind
+its vendor does not ship.
+
+When a tool has no block for the running platform, this skill says so and stops there. It will
+not guess a download URL — a guessed artifact is one the checksum cannot vouch for, and the
+checksum is the only thing standing between a pinned entry and whatever a URL serves today.
+Add the block, or install that one tool however the platform normally would.
+
+## Detect before you install
+
+Run `/lisa:detect-tooling` when the report looks thin. The manifest is the only thing that puts
+a binary on `PATH`, and nothing populates it automatically — so a project ships npm scripts
+invoking `maestro`, wires an MCP server whose CLI it also shells out to, and configures
+Playwright thresholds, while `remoteEnv.tools` stays empty and each of those fails at the
+moment of use instead of at setup.
+
+The detector proposes and a human decides. It writes nothing, so a tool still only ever reaches
+a machine from a reviewed, pinned, checksummed entry.
+
+## What it will not do
+
+- **No unpinned installs.** Every install goes through the same `assertPinned` gate the remote
+  flow uses, and the same in-process checksum verification, which refuses before unpacking.
+- **No package-manager fallback.** Shelling out to Homebrew would give no version pin and no
+  checksum, which is the property this design exists to enforce.
+- **No writes to the manifest.** Proposing entries belongs to `/lisa:detect-tooling`; deciding
+  belongs to a human reviewing a diff.

package/plugins/lisa-agy/skills/lisa-setup-local-env/scripts/local-env.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Bring a developer's machine in line with the toolchain the project declares.
+ *
+ * The manifest, the planner, the pins and the installers are the remote flow's,
+ * unchanged and imported — this is the surface that was missing, not a second
+ * implementation. `remoteEnv.tools` was always surface-aware and the executor
+ * always understood `local`; the only way to reach either was to run a file
+ * called `setup-remote-env.mjs` out of a directory called `lisa-remote-env`,
+ * which nobody looking for local setup ever found.
+ *
+ * Two things differ from the remote flow, and both are because a person is here:
+ *
+ *   consent  — a container provisions itself silently because it is disposable
+ *              and nobody is watching. A laptop belongs to someone, so nothing
+ *              is installed until they ask with --install-tools.
+ *
+ *   tolerance — a container that cannot be fully provisioned should fail before
+ *              it half-runs, because there is no one to read the report. A
+ *              developer can act on a list, so an unprovisionable tool is
+ *              reported, everything else is still installed, and the exit code
+ *              carries the failure.
+ * @module local-env
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve a script belonging to a sibling skill.
+ *
+ * Skills are always siblings under one `skills/` directory, in every install
+ * layout, so this holds for a plugin install, a checkout, and node_modules
+ * alike. Failing loudly here beats reimplementing what the sibling owns.
+ * @param {string} skill Sibling skill slug.
+ * @param {string} script Script filename.
+ * @returns {string} Absolute path.
+ */
+function siblingScript(skill, script) {
+  const path = resolve(HERE, "..", "..", skill, "scripts", script);
+  if (!existsSync(path)) {
+    throw new Error(
+      `cannot find ${skill}/scripts/${script} beside this skill.\n` +
+        `Local setup composes with that skill rather than reimplementing it: ` +
+        `the pins, checksums and installers must be the same ones the remote ` +
+        `surface uses, or the two drift and only one gets fixed.`
+    );
+  }
+  return path;
+}
+
+/**
+ * Load the pieces the remote flow owns.
+ * @returns {Promise<object>} The imported helpers.
+ */
+async function loadRemoteEnv() {
+  const setup = await import(
+    pathToFileURL(
+      siblingScript("lisa-setup-remote-env", "setup-remote-env.mjs")
+    ).href
+  );
+  const toolchain = await import(
+    pathToFileURL(siblingScript("lisa-setup-remote-env", "toolchain.mjs")).href
+  );
+  return { ...toolchain, ...setup };
+}
+
+/**
+ * Describe one blocked decision in terms a person can act on.
+ *
+ * A blocked step on a laptop is usually one of two things, and they are fixed
+ * differently: a tool the project requires and the machine lacks (install it),
+ * or a tool with no artifact pinned for this platform (add the pin, or install
+ * it however this platform normally would). Printing the planner's reason alone
+ * left the reader to work out which.
+ * @param {object} step A plan step.
+ * @param {string} platform The platform key that was resolved against.
+ * @returns {string} A rendered block.
+ */
+function explainBlocked(step, platform) {
+  if (step.action === "invalid" && step.reason.includes("no pin for")) {
+    return (
+      `  ${step.name} — declared, but no artifact is pinned for ${platform}.\n` +
+      `      Lisa will not guess a download URL, because a guessed artifact is ` +
+      `one the checksum cannot vouch for.\n` +
+      `      Add a "${platform}" block under this tool's "platforms" map, or ` +
+      `install it yourself.`
+    );
+  }
+  return `  ${step.name} — ${step.reason.split("\n")[0]}`;
+}
+
+/**
+ * Report and optionally apply the local toolchain.
+ * @param {object} argv Parsed arguments.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function run(argv) {
+  const env = await loadRemoteEnv();
+  // Both seams exist for tests, and both default to this machine. A platform
+  // that can only be exercised by running on it is one CI will never cover,
+  // which is how a resolution bug ships to the platform nobody tested.
+  const platform = argv.platform ?? env.currentPlatform();
+  const { tools } = env.readRemoteEnvConfig(argv.cwd);
+
+  const declared = (tools.require ?? []).length + (tools.install ?? []).length;
+  if (declared === 0) {
+    console.log(
+      "No tools are declared in remoteEnv.tools, so there is nothing to check.\n" +
+        "Run /lisa:detect-tooling — it reads npm scripts, MCP servers, " +
+        "credential\nnotes and quality config, and proposes pinned entries for " +
+        "what it finds."
+    );
+    return 0;
+  }
+
+  const plan = env.planToolchain(tools, env.probe, "local", platform);
+  const blocked = plan.filter(
+    step => step.action === "missing" || step.action === "invalid"
+  );
+  const installable = plan.filter(step => step.action === "install");
+
+  if (argv.json) {
+    console.log(JSON.stringify({ platform, plan }, null, 2));
+    return blocked.length ? 1 : 0;
+  }
+
+  console.log(`Local toolchain for ${platform}\n`);
+  for (const step of plan) {
+    console.log(`  ${step.action.padEnd(8)} ${step.reason.split("\n")[0]}`);
+  }
+
+  if (installable.length && !argv.installTools) {
+    console.log(
+      `\n${installable.length} declared tool(s) can be installed here.\n` +
+        `Nothing has been installed: this machine is yours, not a container.\n` +
+        `Re-run with --install-tools to provision them into ~/.local/bin.`
+    );
+  }
+
+  if (installable.length && argv.installTools) {
+    const binDir = env.ensureBinDir();
+    console.log(`\nInstalling into ${binDir}`);
+    for (const step of installable) {
+      console.log(`  ${step.name}`);
+      if (!argv.dryRun) env.installTool(step.tool, binDir);
+    }
+  }
+
+  if (blocked.length) {
+    console.log(`\n${blocked.length} tool(s) this command cannot resolve:\n`);
+    for (const step of blocked) console.log(explainBlocked(step, platform));
+    return 1;
+  }
+
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const argv = {
+    installTools: process.argv.includes("--install-tools"),
+    dryRun: process.argv.includes("--dry-run"),
+    json: process.argv.includes("--json"),
+  };
+  run(argv)
+    .then(code => process.exit(code))
+    .catch(err => {
+      console.error(err.message);
+      process.exit(1);
+    });
+}

package/plugins/lisa-agy/skills/lisa-setup-remote-env/SKILL.md

@@ -95,6 +95,19 @@ This repository has paid for that twice: `gh` was declared nowhere and a cloud s
 
 The detector proposes and a human decides. It writes nothing, so provisioning still only ever happens from a reviewed, pinned, checksummed entry.
 
+## The same manifest provisions a laptop
+
+`remoteEnv.tools` is not a remote-only manifest, and `/lisa:setup:local-env` is how a developer
+applies it to their own machine — same pins, same checksums, same installers, differing only in
+that nothing installs without `--install-tools` and that a newer tool already on `PATH` is left
+alone rather than downgraded.
+
+A downloaded tool declares a `platforms` map keyed `<platform>-<arch>`, each block carrying its
+own `install` method, `url`, and `sha256`, because the artifact and the archive kind both vary
+by platform. Before that existed, the only way to keep a Linux binary off a laptop was
+`surfaces: ["remote"]`, which achieved it by making the tool uninstallable there — so `bws` and
+`gh` were required on developer machines and provisionable only in containers.
+
 ## Toolchain manifest — two entry kinds
 
 ```json
@@ -108,20 +121,23 @@ The detector proposes and a human decides. It writes nothing, so provisioning st
         { "name": "unzip" }
       ],
       "install": [
-        {
-          "name": "bws",
-          "version": "2.1.0",
-          "install": "release-zip",
-          "url": "https://<vendor>/releases/download/bws-v2.1.0/bws-<platform>-2.1.0.zip",
-          "sha256": "<sha256 published with that exact release>"
-        },
         {
           "name": "gh",
           "version": "2.83.0",
-          "install": "release-tar",
-          "url": "https://<vendor>/releases/download/v2.83.0/gh_2.83.0_linux_amd64.tar.gz",
-          "sha256": "<sha256 published with that exact release>",
-          "binary": "gh_2.83.0_linux_amd64/bin/gh"
+          "platforms": {
+            "linux-x64": {
+              "install": "release-tar",
+              "url": "https://<vendor>/releases/download/v2.83.0/gh_2.83.0_linux_amd64.tar.gz",
+              "sha256": "<sha256 published with that exact release>",
+              "binary": "gh_2.83.0_linux_amd64/bin/gh"
+            },
+            "darwin-arm64": {
+              "install": "release-zip",
+              "url": "https://<vendor>/releases/download/v2.83.0/gh_2.83.0_macOS_arm64.zip",
+              "sha256": "<sha256 published with that exact release>",
+              "binary": "gh_2.83.0_macOS_arm64/bin/gh"
+            }
+          }
         },
         {
           "name": "codex",

package/plugins/lisa-agy/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs

@@ -29,6 +29,7 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import {
   chmodSync,
   existsSync,
@@ -37,7 +38,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { basename, delimiter, dirname, join, resolve } from "node:path";
+import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { assertPinned, extractVersion, planToolchain } from "./toolchain.mjs";
@@ -122,6 +123,34 @@ export function probe(name, exec = execFileSync) {
   }
 }
 
+/**
+ * Refuse an archive whose contents are not exactly what was pinned.
+ *
+ * Hashed in-process rather than by shelling out. `sha256sum` is a GNU coreutils
+ * program: it is not present on a stock macOS, where the equivalent is
+ * `shasum -a 256`, and it was never in the manifest's `require` list either — so
+ * the verification step depended on a tool nothing asserted, on every surface.
+ * Doing it here removes the dependency instead of adding a second name to probe
+ * for, and the check can then be tested without a real archive or a real binary.
+ * @param {string} archive Path to the downloaded file.
+ * @param {string} expected Pinned lowercase hex digest.
+ * @param {string} name Tool name, for the message.
+ */
+export function verifyChecksum(archive, expected, name) {
+  const actual = createHash("sha256")
+    .update(readFileSync(archive))
+    .digest("hex");
+  if (actual !== String(expected).trim().toLowerCase()) {
+    throw new Error(
+      `${name}: checksum mismatch — refusing to install.\n` +
+        `  expected ${expected}\n` +
+        `  actual   ${actual}\n` +
+        `The URL served something other than the reviewed artifact. Do not ` +
+        `update the pin to match without establishing why it changed.`
+    );
+  }
+}
+
 /**
  * Install a pinned archive, refusing anything whose checksum does not match.
  * @param {object} tool Manifest entry.
@@ -137,10 +166,7 @@ function installReleaseZip(tool, binDir) {
     });
     // Verify before unpacking, not after. An unexpected archive must fail
     // before any of its contents reach a directory that is on PATH.
-    execFileSync("sha256sum", ["-c", "-"], {
-      input: `${tool.sha256}  ${archive}\n`,
-      stdio: ["pipe", "ignore", "inherit"],
-    });
+    verifyChecksum(archive, tool.sha256, tool.name);
     execFileSync("unzip", ["-q", "-o", archive, "-d", temporary], {
       stdio: "inherit",
     });
@@ -171,10 +197,7 @@ function installReleaseTar(tool, binDir) {
     execFileSync("curl", ["-fsSL", tool.url, "-o", archive], {
       stdio: "inherit",
     });
-    execFileSync("sha256sum", ["-c", "-"], {
-      input: `${tool.sha256}  ${archive}\n`,
-      stdio: ["pipe", "ignore", "inherit"],
-    });
+    verifyChecksum(archive, tool.sha256, tool.name);
     execFileSync("tar", ["-xzf", archive, "-C", temporary], {
       stdio: "inherit",
     });
@@ -205,16 +228,46 @@ function installNpmGlobal(tool) {
 
 /**
  * Execute one install decision.
- * @param {object} tool Manifest entry.
+ *
+ * Exported because the local-environment flow installs from the same manifest
+ * with the same pins and the same checksum refusal. A second installer would be
+ * a second thing to keep honest, and the one people run least would rot.
+ * @param {object} tool Manifest entry, already resolved to this platform.
  * @param {string} binDir Directory for downloaded binaries.
  */
-function installTool(tool, binDir) {
+export function installTool(tool, binDir) {
   assertPinned(tool);
   if (tool.install === "release-zip") installReleaseZip(tool, binDir);
   else if (tool.install === "release-tar") installReleaseTar(tool, binDir);
   else installNpmGlobal(tool);
 }
 
+/**
+ * Create the directory installs land in, and make sure PATH will find it.
+ *
+ * Installing a binary somewhere nothing looks is the same as not installing it.
+ * `~/.local/bin` is on PATH by default on a developer workstation and is NOT on
+ * a minimal container, so the toolchain step reported `install bws`, the file
+ * landed at ~/.local/bin/bws mode 755, and the very next step died with
+ * `spawnSync bws ENOENT`.
+ *
+ * This was invisible in every local test because a workstation shell already
+ * exports the directory — the environment doing the hiding was the one used to
+ * verify the fix.
+ *
+ * Prepended, not appended: a pinned-and-checksummed binary must win over
+ * whatever an image happens to ship under the same name.
+ * @returns {string} The directory installs are written to.
+ */
+export function ensureBinDir() {
+  const binDir = join(process.env.HOME ?? "", ".local", "bin");
+  mkdirSync(binDir, { recursive: true, mode: 0o755 });
+  if (!pathContains(binDir)) {
+    process.env.PATH = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
+  }
+  return binDir;
+}
+
 /**
  * Apply the toolchain plan, reporting every decision.
  * @param {object} tools Manifest.
@@ -231,8 +284,7 @@ function applyToolchain(tools, dryRun, options = {}) {
     throw new Error(blocked.map(p => p.reason).join("\n\n"));
   }
 
-  const binDir = join(process.env.HOME ?? "", ".local", "bin");
-  mkdirSync(binDir, { recursive: true, mode: 0o755 });
+  const binDir = ensureBinDir();
   const byName = new Map((tools.install ?? []).map(t => [t.name, t]));
 
   // Installing is a different act on a laptop than in a container. A container
@@ -263,26 +315,14 @@ function applyToolchain(tools, dryRun, options = {}) {
     return plan;
   }
 
-  // Installing a binary somewhere nothing looks is the same as not installing
-  // it. `~/.local/bin` is on PATH by default on a developer workstation and is
-  // NOT on a minimal container, so the toolchain step reported `install bws`,
-  // the file landed at ~/.local/bin/bws mode 755, and the very next step died
-  // with `spawnSync bws ENOENT`.
-  //
-  // This was invisible in every local test because a workstation shell already
-  // exports the directory — the environment doing the hiding was the one used
-  // to verify the fix.
-  //
-  // Prepended, not appended: a pinned-and-checksummed binary must win over
-  // whatever an image happens to ship under the same name.
-  if (!pathContains(binDir)) {
-    process.env.PATH = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
-  }
-
   for (const step of plan) {
     console.log(`  ${step.action.padEnd(8)} ${step.reason}`);
+    // The planner already resolved this entry to the running platform, so use
+    // what it decided rather than looking the raw entry up again. `byName` is
+    // the pre-platform shape and would hand the installer a url that belongs to
+    // whichever platform happened to be written first.
     if (step.action === "install" && !dryRun)
-      installTool(byName.get(step.name), binDir);
+      installTool(step.tool ?? byName.get(step.name), binDir);
   }
   return plan;
 }