@tech-leads-club/harness-toolkit 0.2.1 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ npm i -g @tech-leads-club/harness-toolkit
 tlc harness install
 ```
 
-Then restart Cursor or Claude Code. That is the whole setup — the installer finds which of the two you
+Then restart Cursor or Claude Code. That is the whole setup — `install` finds which of the two you
 have and wires only those, and the harness works in every repository right away with a safe baseline.
 
 To give one project its own rules, open it and say **"setup harness"** to the agent, or run
@@ -41,12 +41,11 @@ To give one project its own rules, open it and say **"setup harness"** to the ag
 12. [Connect a project](#connect-a-project)
 13. [Paths and shared state](#paths-and-shared-state)
 14. [Ship claims](#ship-claims)
-15. [Price catalogs](#price-catalogs)
-16. [Windows](#windows)
-17. [Troubleshooting](#troubleshooting)
-18. [Documentation](#documentation)
-19. [Contributing](#contributing)
-20. [License](#license)
+15. [Prices](#prices)
+16. [Troubleshooting](#troubleshooting)
+17. [Documentation](#documentation)
+18. [Contributing](#contributing)
+19. [License](#license)
 
 ## Everything it validates
 
@@ -214,9 +213,12 @@ nothing reads — `src/providers/provider.degrade.ts`.
 
 | Dependency | Notes |
 |------------|--------|
-| **Bun** *or* **Node.js 24+** | Either one is enough. Bun runs every hook directly with no build step (~1 ms/hook); Node needs 24 LTS or 26 and the shipped `dist/` (~27 ms/hook). With neither, the installer stops and names both fixes |
-| **npm** | Delivers the package on every platform |
-| **esbuild** (only for the Node path) | Needed once to recompile `dist/`; the published `dist/` already works |
+| **Bun** *or* **Node.js 24+** | Either one is enough. Bun runs every hook directly (~1 ms/hook); Node runs the shipped bundles (~27 ms/hook). With neither, the install stops and names both fixes |
+| **npm** | Delivers the package, and generates the `tlc` shim for the platform it runs on |
+
+Linux, macOS and Windows, same commands and same code path. CI runs the full suite and the bundle build on all
+three on every push; hooks firing inside an editor session on Windows are outside that coverage
+([`docs/decisions/ad-006.md`](docs/decisions/ad-006.md), [`docs/decisions/ad-097.md`](docs/decisions/ad-097.md)).
 
 ## Install
 
@@ -301,8 +303,8 @@ Reload/restart the provider session afterward if hooks or the init skill should
 | `managed checkout` | moves it to upstream with a hard reset. Do not develop there — a local change is discarded |
 | `link to a working clone` | nothing in the clone. That is a contributor install; you pull it yourself |
 
-`dist/` is rebuilt only when a bundle is missing. Rebuilding a complete `dist/` is what used to dirty the checkout
-and break every later update, because Bun and esbuild emit different bytes for the same source.
+The bundles are rebuilt only when one is missing, and only Bun builds them — a second bundler emits different
+bytes for the same source.
 
 **If `update` aborts on `dist/`, install the package again.** A stuck install cannot deliver its own fix — the fix
 lives in the revision `update` has to fetch — so `npm i -g @tech-leads-club/harness-toolkit@latest` followed by
@@ -352,7 +354,8 @@ graph LR
 | Project shim (per provider) | `<repo>/.cursor/hooks.json`, `<repo>/.claude/settings.json` |
 
 Entrypoint: `bin/tlc-exec.mjs`.
-Wrappers: `bin/tlc`, `bin/tlc-exec` (Unix); `bin/tlc.cmd`, `bin/tlc-exec.cmd` (Windows).
+Wrappers: `bin/tlc` and `bin/tlc.cmd`, kept for installs made before the package existed. Everything else
+spawns `bin/tlc-exec.mjs` with the interpreter already running.
 
 See `tlc harness help architecture` or [`docs/architecture.md`](docs/architecture.md).
 
@@ -373,7 +376,7 @@ See `tlc harness help architecture` or [`docs/architecture.md`](docs/architectur
 | `tlc harness attest` | Tamper-evident record of what each session ran under |
 | `tlc harness handoff` | Handoff state between turns and sessions — the sanctioned reader |
 | `tlc harness obs live` / `obs report` | Signal / session rollup |
-| `tlc harness prices refresh` / `lookup` | Cost catalogs |
+| `tlc harness prices refresh` / `lookup` | The machine's price catalogue |
 | `tlc harness lessons list` | Lessons across the three tiers, with staleness and effectiveness |
 | `tlc harness lessons add "…" [--ref path:symbol] [--global] [--pin]` | Write a lesson; `--ref` retires it when that stops resolving, `--pin` puts it ahead of ranking |
 | `tlc harness policy` / `policy accept <path>` | List a mid-session policy change; accept exactly those paths |
@@ -427,26 +430,19 @@ HARNESS_PLAN_DEVIATION: src/x.ts — the call site moved with the type
 Both are protocol lines on purpose. A gate that fires on free-English "done" fires on the word, not the
 claim.
 
-## Price catalogs
+## Prices
 
 ```bash
 tlc harness prices refresh
 tlc harness prices refresh cursor
-tlc harness prices refresh litellm
 tlc harness prices lookup <model-id> [provider]
 ```
 
-See `tlc harness help prices` or [`docs/measure.md`](docs/measure.md).
-
-## Windows
+Catalogue: `~/.tlc/harness/model-prices.json`, one plane per billing origin. Overrides:
+`model-prices.local.json`. Neither is versioned. `install` fetches once, `update` refreshes past a 7-day TTL,
+`doctor` reports the age.
 
-Path resolution goes through `os.homedir()` only, hooks use exec form, filenames are sanitized,
-atomic writes retry, and the CLI ships a `.cmd` shim alongside directory junctions
-([`docs/decisions/ad-006.md`](docs/decisions/ad-006.md)).
-
-CI runs the full suite and the `dist/` build on `windows-latest` on every push.
-
-Outside CI coverage: `install.ps1`, and hooks firing inside a Cursor or Claude Code session on Windows.
+See `tlc harness help prices` or [`docs/measure.md`](docs/measure.md).
 
 ## Troubleshooting
 

package/bin/tlc-build.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Build the Node-runnable ESM bundles under `dist/`.
+ *
+ * why this is not a shell script any more: the bash version ran only where bash runs, so `update` could not
+ * rebuild a missing bundle on Windows — `spawnSync` cannot execute an extensionless bash file there — and CI had
+ * to invoke it through `shell: bash` on all three legs. Nothing it does needs a shell
+ * ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * why Bun only: `dist/` is committed and `check-dist-fresh` compares bytes, so the bundler is part of the
+ * artefact. The bash version preferred Bun and fell back to esbuild, which means a contributor without Bun
+ * produced different bytes for the same source — measured at 223,390 against 228,018 for one bundle
+ * ([/decisions/ad-046.md](/decisions/ad-046.md)). One bundler is the only reproducible answer.
+ *
+ * invariant: what to build is derived from disk, one level deep. A hardcoded list silently stops building a new
+ * entrypoint, and the missing bundle only surfaces when a hook fires on somebody's machine.
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const dist = join(root, "dist");
+
+/**
+ * why one level: `tools/dev/` holds the checks that validate *this* repository — a user's install has no
+ * `src/core` of ours to validate — so the directory boundary is the whole declaration and nothing under it is
+ * ever a bundle ([/decisions/ad-068.md](/decisions/ad-068.md)).
+ */
+function sourcesIn(dir) {
+  if (!existsSync(dir)) {
+    return [];
+  }
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts"))
+    .map((entry) => ({ name: basename(entry.name, ".ts"), source: join(dir, entry.name) }));
+}
+
+function buildOne(source, out) {
+  const result = spawnSync(
+    "bun",
+    ["build", "--target=node", "--format=esm", `--outfile=${out}`, source],
+    { stdio: "inherit" },
+  );
+  if (result.error?.code === "ENOENT") {
+    console.error("tlc-build: Bun is not on PATH, and dist/ is committed so the bundler is part of the artefact.");
+    console.error("  curl -fsSL https://bun.sh/install | bash");
+    process.exit(1);
+  }
+  if ((result.status ?? 1) !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+const targets = [
+  ...sourcesIn(join(root, "src", "entrypoints")),
+  ...sourcesIn(join(root, "tools")),
+  { name: "tlc-cli", source: join(root, "bin", "tlc-cli.ts") },
+];
+
+mkdirSync(dist, { recursive: true });
+console.log(`tlc-build → ${dist}`);
+for (const target of targets) {
+  buildOne(target.source, join(dist, `${target.name}.mjs`));
+}
+
+// invariant: the launcher stays executable on a filesystem that tracks the bit. A no-op where it does not.
+try {
+  chmodSync(join(root, "bin", "tlc"), 0o755);
+} catch {
+  // a checkout on a filesystem without a mode bit is not a build failure
+}
+
+/**
+ * hazard: a bundle whose source moved or was deleted is not rebuilt, so it is never diffed either — it stays in
+ * `dist/` and ships. Deriving what to remove from the same disk that decides what to build closes that.
+ */
+const wanted = new Set(targets.map((target) => `${target.name}.mjs`));
+let bundles = 0;
+for (const entry of readdirSync(dist, { withFileTypes: true })) {
+  if (!entry.isFile() || !entry.name.endsWith(".mjs")) {
+    continue;
+  }
+  if (wanted.has(entry.name)) {
+    bundles += 1;
+    continue;
+  }
+  console.log(`tlc-build: pruning ${entry.name} — no source`);
+  rmSync(join(dist, entry.name), { force: true });
+}
+
+console.log(`tlc-build: ok (${bundles} bundles)`);

package/bin/tlc-cli.ts

@@ -9,11 +9,17 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { coreFacade } from "../src/core/index.ts";
 import { emitJson, JSON_FLAG, takeJsonFlag, unknownFlags } from "../src/platform/cli-output.ts";
-import { flagsDir, projectConfigPath, projectStateDir, runtimeHome } from "../src/platform/paths.ts";
+import { linkDir, seedConfig } from "../src/platform/links.ts";
+import {
+  flagsDir,
+  projectConfigPath,
+  projectStateDir,
+  providerConfigDirs,
+  runtimeHome,
+} from "../src/platform/paths.ts";
 import { type Row, render, type Screen, type Section } from "../src/platform/screen.ts";
 import { createStyle, PLAIN, type Style } from "../src/platform/style.ts";
 
@@ -482,7 +488,7 @@ export const NPM_PACKAGE = "@tech-leads-club/harness-toolkit";
 export const NPM_MARKER = "installed-from-npm";
 
 /**
- * hazard: `install.sh` links the runtime path to the clone it was run from, so on a contributor's machine
+ * hazard: `install --link` points the runtime path at the clone it was run from, so on a contributor's machine
  * `~/.tlc/harness` is a symlink to their working repository. The old failure message told them to run
  * `git reset --hard` there, which would have destroyed uncommitted work. Verified on this machine.
  *
@@ -514,7 +520,7 @@ export function classifyRuntimePath(
  * hazard: an earlier version also treated "resolves elsewhere" as linked, to catch a symlinked ancestor. macOS CI
  * refuted it: `/var` is a symlink to `/private/var`, so every path under the system temp directory resolves
  * elsewhere and a **managed** checkout was classified as linked — which would silently stop updates on the very
- * platform the reporter uses. Only the last hop decides, which is the one thing `install.sh` actually creates.
+ * platform the reporter uses. Only the last hop decides, which is the one thing the install actually creates.
  */
 export function runtimePathKind(dest: string): RuntimePathKind {
   return classifyRuntimePath(dest, {
@@ -746,13 +752,16 @@ const GATE_FIELDS: Record<string, GateField> = {
 
 // why: resolved without executing. Running the binary to see whether it exists would run it, which is not
 // something a config write is allowed to do.
-export function resolveExecutable(
-  name: string,
-  env: NodeJS.ProcessEnv = process.env,
-  platform: string = process.platform,
-): string | null {
-  const extensions = platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
-  const candidates = (base: string): string[] => [base, ...extensions.map((ext) => `${base}${ext}`)];
+/**
+ * why one list rather than a platform branch reading PATHEXT: the extensions only exist on the platform that uses
+ * them, so trying all of them everywhere finds the same file and removes a branch nobody can test twice. The bare
+ * name is first, so a POSIX `foo` is never beaten by a stray `foo.exe`
+ * ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ */
+const EXECUTABLE_EXTENSIONS = ["", ".exe", ".cmd", ".bat", ".ps1"];
+
+export function resolveExecutable(name: string, env: NodeJS.ProcessEnv = process.env): string | null {
+  const candidates = (base: string): string[] => EXECUTABLE_EXTENSIONS.map((ext) => `${base}${ext}`);
 
   if (name.includes("/") || name.includes("\\")) {
     return candidates(name).find((candidate) => existsSync(candidate)) ?? null;
@@ -861,22 +870,24 @@ export function helpText(style: Style = PLAIN): string {
 
 export function pricesHelpScreen(): Screen {
   return {
-    title: "price catalogs",
+    title: "prices",
     sections: [
       {
-        lines: `  tlc harness prices refresh [all|cursor|litellm]
+        lines: `  tlc harness prices refresh [all|cursor|litellm] [--if-stale]
   tlc harness prices lookup <model-id>
 
-  refresh / refresh all   Cursor catalog + LiteLLM fallback
-  refresh cursor          model-prices.cursor.json (tracked)
-  refresh litellm         model-prices.litellm.json (local)
+  refresh / refresh all   both planes of model-prices.json
+  refresh cursor          the provider's own rates
+  refresh litellm         the vendors' list prices
+  --if-stale              fetch only past the 7-day TTL
   lookup <model-id>       catalog key, pool, USD for 1M in + 1M out
 
-  Resolution: overrides → Cursor → LiteLLM → null
+  Catalogue: <runtime home>/model-prices.json — fetched per machine, never versioned
+  Overrides: <runtime home>/model-prices.local.json — yours, hand-written
   Documentation: tlc harness help prices`.split("\n"),
       },
     ],
-    footer: "resolution: local overrides → the provider's own catalog → LiteLLM → null",
+    footer: "resolution: your overrides → the asking provider's plane → the vendor plane → null",
   };
 }
 
@@ -893,12 +904,69 @@ export function resolveHarnessRoot(): string {
   }
 }
 
+/**
+ * Everything an install has to put in place outside the runtime directory itself: the init skill where each
+ * provider reads it, the user-level hooks, and a seeded config.
+ *
+ * hazard: there were three implementations of this — bash, PowerShell, and the POSIX branch here — and they
+ * disagreed. The PowerShell one linked the init skill into `~/.tlc/skills/harness-init`, which no provider reads,
+ * so on Windows `update` refreshed a skill nothing could route to. That is the defect
+ * [/decisions/ad-095.md](/decisions/ad-095.md) fixed on the other side, still live on this one
+ * ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * invariant: one function, no platform branch, and the launcher on PATH is npm's business.
+ */
+export function wireRuntime(dest: string, home: string): { lines: string[]; missingSkill: boolean } {
+  const lines: string[] = [];
+  const seeded = seedConfig(dest);
+  if (seeded.seeded) {
+    lines.push(`config seeded → ${seeded.path}`);
+  }
+
+  if (!existsSync(join(dest, "skills", "harness-init"))) {
+    return { lines, missingSkill: true };
+  }
+
+  const links = coreFacade.skill.skillLinks(dest, providerConfigDirs(), existsSync);
+  if (links.length === 0) {
+    lines.push("no provider config dir found — skill not linked");
+  }
+  for (const link of links) {
+    const outcome = linkDir(link.source, link.target);
+    lines.push(
+      outcome.kind === "refused" ? `skill not linked — ${outcome.reason}` : `skill → ${outcome.target}`,
+    );
+  }
+
+  const hooks = spawnSync(process.execPath, [join(dest, "bin", "write-user-hooks.mjs")], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_HOME: home },
+  });
+  if ((hooks.status ?? 1) !== 0) {
+    lines.push("hooks unchanged (merge manually or: node bin/write-user-hooks.mjs --force)");
+  }
+  return { lines, missingSkill: false };
+}
+
+/**
+ * hazard: this was the extensionless bash wrapper, so every `runEntry` spawn — `doctor`, `prices refresh`,
+ * `install-runtime`, `price-lookup` — named a file Windows cannot execute. The hooks never had this problem
+ * because they name the `.mjs` ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * invariant: paired with `process.execPath`, so the entry runs under the interpreter that is already running.
+ */
 export function execBinPath(): string {
-  return join(resolveHarnessRoot(), "bin", "tlc-exec");
+  return join(resolveHarnessRoot(), "bin", "tlc-exec.mjs");
 }
 
+/**
+ * why the `.mjs` and not a wrapper: the wrapper was bash, so `spawnSync` could not run it on Windows and
+ * `update` there could never rebuild a missing bundle ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ *
+ * invariant: spawned with `process.execPath`, so the interpreter running the CLI is the one that builds.
+ */
 export function buildBinPath(): string {
-  return join(resolveHarnessRoot(), "bin", "tlc-build");
+  return join(resolveHarnessRoot(), "bin", "tlc-build.mjs");
 }
 
 export type Action =
@@ -1217,13 +1285,18 @@ function runUpdate(root: string): never {
     const bump = spawnSync("npm", ["install", "-g", `${NPM_PACKAGE}@latest`], {
       stdio: "inherit",
       env: process.env,
-      shell: process.platform === "win32",
+      // why: `npm` is `npm.cmd` on Windows and a shell is how that resolves; on POSIX it costs one `/bin/sh`,
+      // and the argv here is fixed ([/decisions/ad-097.md](/decisions/ad-097.md)).
+      shell: true,
     });
     if ((bump.status ?? 1) !== 0) {
       console.error(npmUpdateFailureMessage());
       process.exit(bump.status ?? 1);
     }
-    const sync = spawnSync(execBinPath(), ["install-runtime"], { stdio: "inherit", env: process.env });
+    const sync = spawnSync(process.execPath, [execBinPath(), "install-runtime"], {
+      stdio: "inherit",
+      env: process.env,
+    });
     if ((sync.status ?? 1) !== 0) {
       process.exit(sync.status ?? 1);
     }
@@ -1262,38 +1335,13 @@ function runUpdate(root: string): never {
     );
   }
 
-  const binDir = process.env.TLC_BIN_DIR || join(homedir(), ".local", "bin");
-  mkdirSync(binDir, { recursive: true });
-  mkdirSync(join(home, "..", "skills"), { recursive: true });
-
-  if (process.platform === "win32") {
-    const installPs1 = join(dest, "install.ps1");
-    const r = spawnSync("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", installPs1], {
-      stdio: "inherit",
-      env: { ...process.env, TLC_HOME: home },
-      cwd: dest,
-    });
-    if ((r.status ?? 1) !== 0) {
-      process.exit(r.status ?? 1);
-    }
-  } else {
-    const tlcBin = join(dest, "bin", "tlc");
-    const skillSrc = join(dest, "skills", "harness-init");
-    const skillDest = join(home, "..", "skills", "harness-init");
-    spawnSync("ln", ["-sfn", tlcBin, join(binDir, "tlc")], { stdio: "inherit" });
-    if (!existsSync(skillSrc)) {
-      console.error(`update: missing skill at ${skillSrc}`);
-      process.exit(1);
-    }
-    spawnSync("ln", ["-sfn", skillSrc, skillDest], { stdio: "inherit" });
-    console.log(`update: skill → ${skillDest}`);
-    const hooks = spawnSync(process.execPath, [join(dest, "bin", "write-user-hooks.mjs")], {
-      stdio: "inherit",
-      env: { ...process.env, TLC_HOME: home },
-    });
-    if ((hooks.status ?? 1) !== 0) {
-      console.log("update: hooks unchanged (merge manually or: node bin/write-user-hooks.mjs --force)");
-    }
+  const wired = wireRuntime(dest, home);
+  for (const line of wired.lines) {
+    console.log(`update: ${line}`);
+  }
+  if (wired.missingSkill) {
+    console.error(`update: missing skill at ${join(dest, "skills", "harness-init")}`);
+    process.exit(1);
   }
 
   // invariant: never build into the artifact when it is already complete. `dist/` is committed for the Node
@@ -1305,7 +1353,7 @@ function runUpdate(root: string): never {
     console.log("update: dist/ complete — no rebuild, so the runtime path stays clean");
   } else if (existsSync(buildBinPath())) {
     console.log(`update: ${missing.length} bundle(s) missing — building`);
-    const build = spawnSync(buildBinPath(), [], { stdio: "inherit", env: process.env });
+    const build = spawnSync(process.execPath, [buildBinPath()], { stdio: "inherit", env: process.env });
     if ((build.status ?? 1) !== 0) {
       console.log(`update: build failed — ${missing.length} bundle(s) still missing from dist/`);
     }
@@ -1314,8 +1362,19 @@ function runUpdate(root: string): never {
   announceNewCapabilities(root, dest);
   announceLandedDecisions(root, dest, revisionBefore);
 
+  /**
+   * why: an update is the moment a machine is already reaching the network, so it is the natural place to notice
+   * that its prices are a week old. `--if-stale` is what keeps this from being a fetch on every update, and the
+   * failure is tolerated — a rate that could not be fetched is not a reason for a failed update
+   * ([/decisions/ad-096.md](/decisions/ad-096.md)).
+   */
+  spawnSync(process.execPath, [execBinPath(), "refresh-model-prices", "all", "--if-stale"], {
+    stdio: "inherit",
+    env: { ...process.env, TLC_PROJECT_DIR: root },
+  });
+
   console.log("update: running doctor…");
-  const doctor = spawnSync(execBinPath(), ["doctor"], {
+  const doctor = spawnSync(process.execPath, [execBinPath(), "doctor"], {
     stdio: "inherit",
     env: { ...process.env, TLC_PROJECT_DIR: root },
   });
@@ -1324,7 +1383,7 @@ function runUpdate(root: string): never {
 }
 
 function runEntry(entry: string, toolArgs: string[], root: string): never {
-  const r = spawnSync(execBinPath(), [entry, ...toolArgs], {
+  const r = spawnSync(process.execPath, [execBinPath(), entry, ...toolArgs], {
     stdio: "inherit",
     env: { ...process.env, TLC_PROJECT_DIR: root },
   });
@@ -1425,7 +1484,7 @@ function main(argv: string[]): void {
       console.log(helpText(createStyle()));
       break;
     case "build": {
-      const r = spawnSync(buildBinPath(), [], { stdio: "inherit", env: process.env });
+      const r = spawnSync(process.execPath, [buildBinPath()], { stdio: "inherit", env: process.env });
       process.exit(r.status ?? 1);
       break;
     }

package/bin/tlc-exec.mjs

@@ -62,20 +62,23 @@ export function resolveHarnessHome(
   return candidate;
 }
 
-export function bunExecutableName(platform = process.platform) {
-  return platform === "win32" ? "bun.exe" : "bun";
-}
+/**
+ * why a list and not a branch: the only difference between platforms is which of these names exists on disk, and
+ * asking for both costs one extra `existsSync` per PATH entry. `bun.exe` never exists on Linux and `bun` never
+ * shadows it on Windows ([/decisions/ad-097.md](/decisions/ad-097.md)).
+ */
+export const BUN_EXECUTABLE_NAMES = ["bun", "bun.exe"];
 
-export function findBunOnPath(env = process.env, platform = process.platform) {
-  const pathValue = env.PATH ?? "";
-  const bunName = bunExecutableName(platform);
-  for (const dir of pathValue.split(delimiter)) {
+export function findBunOnPath(env = process.env) {
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
     if (!dir) {
       continue;
     }
-    const candidate = join(dir, bunName);
-    if (existsSync(candidate)) {
-      return candidate;
+    for (const name of BUN_EXECUTABLE_NAMES) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) {
+        return candidate;
+      }
     }
   }
   return null;
@@ -122,12 +125,12 @@ export function writeRuntimeCache(harnessHome, bunPath) {
   return record;
 }
 
-export function resolveBunPath(harnessHome, env = process.env, platform = process.platform) {
+export function resolveBunPath(harnessHome, env = process.env) {
   const cached = readRuntimeCache(harnessHome);
   if (cached) {
     return cached.bunPath;
   }
-  const found = findBunOnPath(env, platform);
+  const found = findBunOnPath(env);
   writeRuntimeCache(harnessHome, found);
   return found;
 }
@@ -167,7 +170,7 @@ export function decideRuntime({ harnessHome, entry, bunPath, nodeMajor, distExis
       status: 1,
       message: [
         `tlc: Node ${process.version} found, but dist/${entry}.mjs is missing.`,
-        `  Run: ${join(harnessHome, "bin", "tlc-build")}`,
+        `  Run: node ${join(harnessHome, "bin", "tlc-build.mjs")}`,
       ].join("\n"),
     };
   }