simt-dev 0.5.0 → 0.6.2

package/src/distribute/release.mjs

@@ -0,0 +1,142 @@
+// The binary channel: what a release publishes, where a repository keeps its copy,
+// and the one command that gets it there.
+//
+// This module is the single place that knows those facts, because three generated
+// surfaces must agree on them and they are rendered from different call sites: the
+// locator block (src/locate.mjs) checks a path, the hook shim's remedy prints a
+// download command, and the CI workflow renders the same download as a step. A
+// second copy of the asset name or the URL is a copy that drifts, and a drifted
+// remedy tells a reader to fetch bytes that do not exist.
+//
+// The channel is a fourth beside npm, PyPI and Homebrew (ADR-058), and unlike the
+// other three it is the one that needs no toolchain at all: the npm channel needs
+// npm, the wheel needs a Python, and the formula - until this release - needed
+// node. The binary is a file. That is the whole design (ADR-098), and it is why
+// the locator checks a path in the repository before it checks PATH: the bytes a
+// repository pinned are the bytes its gate runs, on a machine with nothing else.
+
+import { CLI, PACKAGE_NAME } from '../name.mjs';
+
+// The GitHub repository the release is published from. A fact about where the
+// bytes come from, like the npm registry host: a reader outside this estate
+// reads it as a URL, not as an organisation. Not exported: the only surface a
+// caller needs is the URL, and a second copy of the slug is a copy that drifts.
+const REPO_SLUG = 'QuazarMedia/simt-dev';
+
+/** The platforms the release builds. The set is small on purpose: it is the set
+ *  the locator's remedy and the CI step can name, and a platform in this list that
+ *  the release does not build is a remedy that downloads a 404. */
+export const TARGETS = ['darwin-arm64', 'darwin-x64', 'linux-x64'];
+
+// Where a repository keeps the binary it pinned, relative to its top level.
+// Beneath `.simt`, like every other per-repo state this tool writes, so a reader
+// who has seen one knows where to look for all of them. The name is the command,
+// not the package: the reader types one program and this is it, the same way
+// `bin/simt.mjs` is it on npm.
+const LOCAL_BIN_NAME = CLI;
+
+/** The directory a repository keeps its pinned binary in, relative to its top
+ *  level. Exported because a caller that installs the binary must create it and
+ *  has no other source for the fact. */
+export const LOCAL_BIN_DIR = '.simt/bin';
+
+/** The path the locator checks, relative to the repository's top level. */
+export const LOCAL_BIN = `${LOCAL_BIN_DIR}/${LOCAL_BIN_NAME}`;
+
+/**
+ * The release asset name for a version and a target.
+ *
+ * The package name, not the command: it sits beside its siblings in the release
+ * and next to the npm tarball `simt-dev-0.5.0.tgz`, where one name for the project
+ * is what a reader matching names expects.
+ *
+ * @param {string} version x.y.z
+ * @param {string} osArch one of TARGETS
+ * @returns {string} e.g. `simt-dev-0.5.0-darwin-arm64`
+ */
+export function assetName(version, osArch) {
+  if (!TARGETS.includes(osArch)) throw new Error(`unknown target ${osArch}; known: ${TARGETS.join(', ')}`);
+  return `${PACKAGE_NAME}-${version}-${osArch}`;
+}
+
+/**
+ * The asset name with the platform left for the shell to fill in at runtime.
+ *
+ * The CI step and the remedy both run on a machine whose platform is not known
+ * where the text was written, so the name is completed from `uname` or the
+ * runner there. One template shared with {@link assetName} keeps the two from
+ * drifting: a name rendered here that the release does not publish is a 404.
+ *
+ * @param {string} version x.y.z
+ * @returns {string} e.g. `simt-dev-0.5.0-$os-$arch`, for a shell with $os and $arch set
+ */
+export function assetNameExpr(version) {
+  return `${PACKAGE_NAME}-${version}-$os-$arch`;
+}
+
+/**
+ * The URL the release serves a version's assets from.
+ *
+ * @param {string} version x.y.z
+ * @returns {string}
+ */
+export function releaseBase(version) {
+  return `https://github.com/${REPO_SLUG}/releases/download/v${version}`;
+}
+
+/**
+ * The URL the release serves one asset from.
+ *
+ * @param {string} version x.y.z
+ * @param {string} osArch one of TARGETS
+ * @returns {string}
+ */
+export function releaseUrl(version, osArch) {
+  return `${releaseBase(version)}/${assetName(version, osArch)}`;
+}
+
+/**
+ * The download a reader without npm runs from their repository's top level: fetch
+ * the asset this machine needs and put it where the locator looks.
+ *
+ * One line on purpose - it is rendered into a remedy that a reader copies from an
+ * error message, and a multi-line script in an error message is not copied. The
+ * platform is derived rather than baked in, because the remedy lives in a file
+ * that is committed and shared: a URL rendered for the machine that wrote the
+ * shim would be a 404 for the colleague who clones it.
+ *
+ * The transport is TLS from the release, and the version the bytes report is
+ * checked against the repository's pin by the dispatcher itself (ADR-098), so
+ * the remedy does not also carry a checksum: it is the shortest command that
+ * reaches a working state, and the gate re-verifies what it runs.
+ *
+ * @param {string} version x.y.z
+ * @returns {string} POSIX sh, run from the repository's top level
+ */
+export function localInstall(version) {
+  return [
+    `mkdir -p ${LOCAL_BIN_DIR}`,
+    ...platformLines(),
+    `curl -fsSL "${releaseBase(version)}/${assetNameExpr(version)}" -o ${LOCAL_BIN}`,
+    `chmod +x ${LOCAL_BIN}`,
+  ].join(' && ');
+}
+
+/**
+ * The two shell lines that derive this machine's release target at run time.
+ *
+ * `uname -m` answers `x86_64` on both platforms' Intel builds and `arm64` on
+ * Apple Silicon, so one substitution covers the naming gap. Both the remedy and
+ * the generated CI step name their asset from these lines: the text is committed
+ * and shared, so a URL baked for the machine that wrote it is a 404 for the
+ * colleague who clones it, and a workflow expression interpolated into a command
+ * substitution is worse - the CI step once rendered `os=$('${{ runner.os }}' …)`,
+ * which the runner substitutes to `os=$('Linux' …)` and `set -eu` refuses, so the
+ * install failed on every run in the one repository kind this channel exists for.
+ * The step is executed, not pattern-matched, in test/binary.test.mjs.
+ *
+ * @returns {string[]} POSIX sh lines assigning `$os` and `$arch`
+ */
+export function platformLines() {
+  return [`os=$(uname -s | tr A-Z a-z)`, `arch=$(uname -m | sed "s/x86_64/x64/")`];
+}

package/src/graph/load.mjs

@@ -35,14 +35,15 @@ function defaultRegistryPath() {
 /**
  * The registry to read when the reader names none, in order (ADR-061 ruling 3):
  *
- * 1. The package root, when it holds one. In this checkout that is how the tool finds its
- *    own registry; in an installed package `graph` is not in the published `files`, so it
- *    never does, and the reader falls through to 2 instead of being handed this workspace's
- *    catalogue.
- * 2. A member of the resolved workspace, when exactly one holds one: a tool installed from
- *    node_modules or a formula resolves its workspace by configuration, and the member that
- *    holds the registry is usually the tool's own checkout. More than one holding it is
- *    ambiguity and the reader must pick; none is an honest absence, reported with the
+ * 1. The package root, when it holds one. In a source checkout that is how the tool
+ *    finds its own registry, sitting next to the code that reads it. An installed
+ *    package holds no registry (ADR-061 ruling 2): the catalogue is workspace data,
+ *    and an install serving another estate's skills to an adopting repository would
+ *    be a confident wrong answer. This tier is a source-checkout convenience; when it
+ *    is empty, resolution falls through to the workspace member or an honest absence.
+ * 2. A member of the resolved workspace, when exactly one holds one: reachable in a checkout
+ *    whose package root holds no registry. More than one holding it is ambiguity and the
+ *    reader must pick; none is an honest absence, reported with the
  *    workspace that was looked in.
  *
  * Every step is file existence plus the configured workspace, so the answer can be

package/src/hooks/dispatcher.mjs

@@ -68,8 +68,9 @@ export async function runGates(event, { root, manifest }) {
   }
 
   // The gates below run from the binary that resolved this shim. For a repository
-  // without npm that is a global install, whose version nothing else pins: if it is not
-  // the one this repo adopted, the gates that run here are not the ones CI runs.
+  // without npm that is the release binary in `.simt/bin` (ADR-098), whose version
+  // nothing else pins: if it is not the one this repo adopted, the gates that run here
+  // are not the ones CI runs.
   // Placed after the empty-list check on purpose - with no gates there is nothing the
   // version could get wrong, and failing that case would block commits in repos that
   // deliberately declare none.

package/src/hooks/shim.mjs

@@ -18,6 +18,7 @@
 
 import { renderLocator } from '../locate.mjs';
 import { BIN_ENV, CLI, MANIFEST_FILE, PACKAGE_NAME } from '../name.mjs';
+import { localInstall } from '../distribute/release.mjs';
 import { packageVersion } from '../package-version.mjs';
 
 /**
@@ -49,8 +50,8 @@ export function fileFor(event) {
  * @param {string} event one of EVENTS
  * @param {{npm?: boolean, version?: string}} [opts]
  *   `npm` is whether the repository has a package.json: it decides the remedy's install
- *   (a devDependency where one exists, a pinned global install where there is no
- *   node_modules to pin in). `version` defaults to the running package's own version,
+ *   (a devDependency where one exists, the release binary into the repository where
+ *   there is no node_modules to pin in). `version` defaults to the running package's own version,
  *   so a shim generated by 0.2.0 names 0.2.0 in its remedy and CI install.
  * @returns {string} POSIX sh source, LF-terminated, executable
  */
@@ -62,8 +63,9 @@ export function renderShim(event, { npm = true, version } = {}) {
   // The install that finds the binary when node_modules and PATH both come up empty.
   // A repository with a package.json pins simt-dev as a devDependency, so the remedy
   // installs it there; one without (Gradle, Connect IQ) has no node_modules to pin in,
-  // so the remedy is a pinned global install - the same pinned bytes CI gets.
-  const install = npm ? `npm i -D ${PACKAGE_NAME}@${v}` : `npm i -g ${PACKAGE_NAME}@${v}`;
+  // so the remedy downloads the release binary into the repository - the same pinned
+  // bytes CI gets, and one that needs no npm and no node on the machine (ADR-098).
+  const install = npm ? `npm i -D ${PACKAGE_NAME}@${v}` : localInstall(v);
   const D = '$';
   return `#!/bin/sh
 ${SHIM_MARKER}
@@ -75,7 +77,8 @@ ${SHIM_MARKER}
 # This file only locates the dispatcher and hands over. It resolves in order:
 #   1. ${D}SIMT_DEV_BIN    explicit override, for CI images and odd checkouts
 #   2. node_modules/       the pinned project dependency
-#   3. ${CLI} on PATH       a global install
+#   3. .simt/bin/          the release binary this repository downloaded
+#   4. ${CLI} on PATH       a global install
 # If none resolves it REFUSES rather than exiting 0. A hook that cannot verify
 # anything must never report success - that is what teaches authors to reach for
 # --no-verify.
@@ -102,7 +105,9 @@ ${renderLocator(`hooks run ${event} --root "${D}ROOT"`, {
  */
 export function renderEvidenceShim({ npm = true, version } = {}) {
   const v = version ?? packageVersion();
-  const install = npm ? `npm i -D ${PACKAGE_NAME}@${v}` : `npm i -g ${PACKAGE_NAME}@${v}`;
+  // The same split as renderShim: a devDependency where one exists, the release
+  // binary into the repository where there is no node_modules to pin in.
+  const install = npm ? `npm i -D ${PACKAGE_NAME}@${v}` : localInstall(v);
   const D = '$';
   return `#!/bin/sh
 ${SHIM_MARKER}

package/src/index/govern.mjs

@@ -56,7 +56,7 @@ export function sourceRoots(files) {
 /**
  * One Affects token.
  *
- * A prefixed command (`simt-dev init`, `simt hooks run`) is a command only when
+ * A prefixed command (`simt init`, `simt hooks run`) is a command only when
  * that command exists. The tool name on its own is not a command and not a path.
  * Anything else is a path or a glob, at the repo root and then under each source
  * root. A token that is none of those is unresolved.

package/src/index/map.mjs

@@ -285,7 +285,7 @@ export async function embedTaskQuery(root, task, { embed = false, allowRemote =
  * }} [opts]
  */
 export async function measureRecall(root, opts = {}) {
-  const tasksDir = join(root, '.simt-dev', 'bench', 'tasks');
+  const tasksDir = join(root, '.simt', 'bench', 'tasks');
   let names;
   try {
     names = (await readdir(tasksDir)).filter((name) => name.endsWith('.json')).sort();

package/src/index/persist.mjs

@@ -7,8 +7,8 @@
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
-export const SQLITE_FILE = '.simt-dev/index.sqlite';
-export const JSONL_FILE = '.simt-dev/index.jsonl';
+export const SQLITE_FILE = '.simt/index.sqlite';
+export const JSONL_FILE = '.simt/index.jsonl';
 export const SCHEMA_V = '3';
 
 const SCHEMA = `

package/src/index/store.mjs

@@ -4,7 +4,7 @@
 // otherwise. Either one is a cache: `git ls-files -s` can rebuild it, so a missing
 // file is not a lost database. A blob that has not changed is not read again.
 
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
@@ -387,9 +387,9 @@ export async function packageOf(root, filePath, cache) {
   }
 }
 
-function git(root, args, input, binary = false) {
+function git(root, args, input) {
   return new Promise((resolve, reject) => {
-    const child = execFile('git', args, { cwd: root, encoding: binary ? 'buffer' : 'utf8', maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+    const child = execFile('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
       if (error) reject(Object.assign(error, { stdout, stderr }));
       else resolve(stdout);
     });
@@ -477,28 +477,58 @@ function normalise(filePath, got) {
   return { symbols, imports: Array.isArray(got.imports) ? got.imports : [], edges };
 }
 
+/**
+ * The body of each listed blob, read as one `cat-file --batch` stream.
+ *
+ * Streamed and parsed incrementally rather than buffered: the combined output of a
+ * repository whose tracked content exceeds execFile's maxBuffer (64 MiB) used to
+ * reject the whole index with "stdout maxBuffer length exceeded" — an ~82 MiB
+ * Android checkout died on first run for exactly that reason.
+ */
 export async function blobTexts(root, blobs) {
   const unique = [...new Set(blobs)];
   const texts = new Map();
   if (unique.length === 0) return texts;
-  const stdout = await git(root, ['cat-file', '--batch'], `${unique.join('\n')}\n`, true);
-  let offset = 0;
-  while (offset < stdout.length) {
-    const nl = stdout.indexOf(0x0a, offset);
-    if (nl < 0) break;
-    const header = stdout.toString('utf8', offset, nl);
-    const parts = header.split(' ');
-    const size = Number(parts[2]);
-    if (parts[1] !== 'blob' || !Number.isFinite(size)) {
-      offset = nl + 1;
-      continue;
+  const child = spawn('git', ['cat-file', '--batch'], { cwd: root });
+  child.stdin.end(`${unique.join('\n')}\n`);
+  let pending = null;
+  const onChunk = (chunk) => {
+    pending = pending === null ? chunk : Buffer.concat([pending, chunk]);
+    let consumed = 0;
+    for (;;) {
+      const nl = pending.indexOf(0x0a, consumed);
+      if (nl < 0) break;
+      const parts = pending.toString('utf8', consumed, nl).split(' ');
+      const size = Number(parts[2]);
+      if (parts[1] !== 'blob' || !Number.isFinite(size)) {
+        consumed = nl + 1;
+        continue;
+      }
+      const end = nl + 1 + size + 1;
+      if (pending.length < end) break; // the body is not fully arrived yet
+      const start = nl + 1;
+      const body = pending.subarray(start, start + size);
+      consumed = end;
+      texts.set(parts[0], body.includes(0) ? null : body.toString('utf8'));
     }
-    const start = nl + 1;
-    const body = stdout.subarray(start, start + size);
-    offset = start + size + 1;
-    texts.set(parts[0], body.includes(0) ? null : body.toString('utf8'));
-  }
-  return texts;
+    // Drop the consumed prefix. Copy the tail once it has grown past a MiB, so the
+    // released bytes are actually freed instead of staying alive behind a view into
+    // the buffer they came from.
+    if (consumed > 0) {
+      const tail = pending.subarray(consumed);
+      pending = tail.length === 0 ? null : consumed >= 1 << 20 ? Buffer.from(tail) : tail;
+    }
+  };
+  return new Promise((resolve, reject) => {
+    let stderr = '';
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.stdout.on('data', onChunk);
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0) reject(new Error(`git cat-file --batch exited ${code}${stderr ? `: ${stderr.trim()}` : ''}`));
+      else resolve(texts);
+    });
+  });
 }
 
 async function blobSizes(root, blobs) {

package/src/ledger/index.mjs

@@ -22,7 +22,7 @@ import {
 
 const exec = promisify(execFile);
 
-const LEDGER_FILE = '.simt-dev/ledger.jsonl';
+const LEDGER_FILE = '.simt/ledger.jsonl';
 
 /** Phrases that claim a run happened. `unverified` and `not verified` are removed
  *  first, because both contain the word and neither is a claim. */
@@ -76,7 +76,7 @@ export async function recordRun(root, { cmd, exit, ms, output }) {
         }
       : {}),
   };
-  await mkdir(join(root, '.simt-dev'), { recursive: true });
+  await mkdir(join(root, '.simt'), { recursive: true });
   await appendFile(join(root, LEDGER_FILE), `${JSON.stringify(line)}\n`);
 
   if (exit === 0 && typeof cmd === 'string') {

package/src/local/client.mjs

@@ -26,6 +26,7 @@ function guardEndpoint(endpoint, { allowRemote = false } = {}) {
   if (!model) {
     return { ok: false, error: 'local model endpoint is missing `model`', refusedRemote: false };
   }
+  const apiKey = typeof endpoint.apiKey === 'string' && endpoint.apiKey.length > 0 ? endpoint.apiKey : null;
   const loopback = isLoopbackUrl(rawUrl);
   if (!loopback && !allowRemote) {
     return {
@@ -39,6 +40,7 @@ function guardEndpoint(endpoint, { allowRemote = false } = {}) {
     url: rawUrl,
     baseUrl: resolveEndpointUrl(rawUrl, ''),
     model,
+    apiKey,
     timeoutMs: Number.isInteger(endpoint.timeoutMs) && endpoint.timeoutMs > 0
       ? endpoint.timeoutMs
       : DEFAULT_LOCAL_TIMEOUT_MS,
@@ -46,13 +48,20 @@ function guardEndpoint(endpoint, { allowRemote = false } = {}) {
   };
 }
 
-async function requestJson(url, { method = 'GET', body = undefined, timeoutMs = DEFAULT_LOCAL_TIMEOUT_MS, fetchImpl = globalThis.fetch } = {}) {
+async function requestJson(url, { method = 'GET', body = undefined, timeoutMs = DEFAULT_LOCAL_TIMEOUT_MS, apiKey = null, fetchImpl = globalThis.fetch } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
+    const headers = {
+      ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+      accept: 'application/json',
+    };
+    if (typeof apiKey === 'string' && apiKey.length > 0) {
+      headers.authorization = `Bearer ${apiKey}`;
+    }
     const response = await fetchImpl(url, {
       method,
-      headers: body !== undefined ? { 'content-type': 'application/json', accept: 'application/json' } : { accept: 'application/json' },
+      headers,
       body: body !== undefined ? JSON.stringify(body) : undefined,
       signal: controller.signal,
     });
@@ -121,6 +130,7 @@ export async function localModels(endpoint, { allowRemote = false, fetchImpl = g
   const res = await requestJson(targetUrl, {
     method: 'GET',
     timeoutMs: guard.timeoutMs,
+    apiKey: guard.apiKey,
     fetchImpl,
   });
   if (!res.ok) {
@@ -200,6 +210,7 @@ export async function localChat(
       stream: false,
     },
     timeoutMs: guard.timeoutMs,
+    apiKey: guard.apiKey,
     fetchImpl,
   });
 
@@ -216,12 +227,14 @@ export async function localChat(
   }
 
   const choice = Array.isArray(res.data.choices) ? res.data.choices[0] : null;
-  const content =
-    typeof choice?.message?.content === 'string'
-      ? choice.message.content
-      : typeof choice?.text === 'string'
-        ? choice.text
-        : null;
+  const message = choice?.message ?? {};
+  // Prefer the final answer. A reasoning model (omlx, Qwen3-thinking) emits its
+  // output in `reasoning_content` and leaves `content` empty or absent when the
+  // budget is tiny (e.g. doctor's 1-token ping), so fall back to it, then the
+  // legacy `text` field. Whitespace-only output counts as absent.
+  const content = [message.content, message.reasoning_content, choice?.text]
+    .map((value) => (typeof value === 'string' && value.trim().length > 0 ? value : null))
+    .find((value) => value !== null) ?? null;
 
   if (content === null) {
     return {
@@ -275,6 +288,7 @@ export async function localEmbed(
       input: Array.isArray(input) ? input.map(String) : String(input ?? ''),
     },
     timeoutMs: guard.timeoutMs,
+    apiKey: guard.apiKey,
     fetchImpl,
   });
 

package/src/local/config.mjs

@@ -8,6 +8,10 @@
 //     "embed": { "url": "http://127.0.0.1:11434/v1", "model": "nomic-embed-code" }
 //   }
 //
+// Each role also accepts an optional `apiKey` (a non-empty string). When present it is
+// sent as an `Authorization: Bearer <key>` header, for servers that require a token
+// (omlx, llama.cpp `--api-key`, OpenAI-compatible gateways). Omitted by default.
+//
 // Non-loopback URLs are refused unless `--allow-remote` is explicitly passed (ADR-075).
 
 import { EXIT, fail } from '../output/index.mjs';
@@ -114,6 +118,17 @@ function parseEndpoint(role, entry, { allowRemote = false } = {}) {
     };
   }
 
+  // Optional bearer credential for servers that require authentication (omlx,
+  // llama.cpp `--api-key`, OpenAI-compatible gateways). Absent by default: most
+  // local servers (Ollama, LM Studio) accept unauthenticated loopback requests.
+  let apiKey = '';
+  if (entry.apiKey !== undefined) {
+    if (typeof entry.apiKey !== 'string' || entry.apiKey.trim().length === 0) {
+      return { endpoint: null, finding: `\`local.${role}.apiKey\` must be a non-empty string when set` };
+    }
+    apiKey = entry.apiKey;
+  }
+
   const loopback = isLoopbackHost(parsedUrl.hostname);
   const baseUrl = resolveEndpointUrl(rawUrl, '');
   const blocked = !loopback && !allowRemote;
@@ -126,6 +141,7 @@ function parseEndpoint(role, entry, { allowRemote = false } = {}) {
         baseUrl,
         model,
         timeoutMs,
+        apiKey,
         loopback: false,
         blocked: true,
       },
@@ -141,6 +157,7 @@ function parseEndpoint(role, entry, { allowRemote = false } = {}) {
       baseUrl,
       model,
       timeoutMs,
+      apiKey,
       loopback,
       blocked: false,
     },

package/src/locate.mjs

@@ -12,6 +12,7 @@
 // this is a block and not a script.
 
 import { BIN_ENV, BIN_REL, CLI, PACKAGE_NAME } from './name.mjs';
+import { LOCAL_BIN } from './distribute/release.mjs';
 
 /**
  * @param {string} command arguments to hand the tool, with `$ROOT` spelled as a shell
@@ -24,6 +25,13 @@ import { BIN_ENV, BIN_REL, CLI, PACKAGE_NAME } from './name.mjs';
  * @returns {string} POSIX sh source
  */
 export function renderLocator(command, { subject = CLI, remedy = `REMEDY run: npm i -D ${PACKAGE_NAME}` } = {}) {
+  // The remedy is emitted single-quoted (see the assignment at the bottom of the
+  // block), so a quote in it would end that string and re-open the shell to
+  // whatever follows. Refuse at render time: the failure is a template bug, and
+  // it should be found where the string is written, not in a hook on a machine.
+  if (remedy.includes("'")) {
+    throw new Error(`the remedy is embedded single-quoted and cannot contain a quote: ${remedy}`);
+  }
   const D = '$';
   return `# ${D}${BIN_ENV} must name ONE program: an executable on PATH, or a .mjs entry
 # point to hand to node. It cannot be a command line, because there is no safe way
@@ -59,6 +67,15 @@ if [ -f "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ]; then
   exec node "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ${command}
 fi
 
+# The binary this repository downloaded for itself: the pinned bytes, no node.
+# It is checked before PATH so a repository's own copy wins over whatever a
+# machine happens to have installed, the same way node_modules wins - and the
+# dispatcher still compares the version it runs against the pin, so a stale
+# copy is refused rather than trusted.
+if [ -x "${D}ROOT/${LOCAL_BIN}" ]; then
+  exec "${D}ROOT/${LOCAL_BIN}" ${command}
+fi
+
 if command -v ${CLI} >/dev/null 2>&1; then
   exec ${CLI} ${command}
 fi
@@ -68,7 +85,11 @@ echo "${CLI}: cannot locate ${subject}." >&2
 # unbound variable aborts the shell, so an unguarded ${D}${BIN_ENV} here would
 # kill the message that exists to explain the failure - and this block only runs
 # when nothing resolved, which is the one moment the reader needs it.
-echo "  looked for: ${D}{${BIN_ENV}:-<unset>}, ${D}ROOT/node_modules/${PACKAGE_NAME}, ${CLI} on PATH" >&2
+echo "  looked for: ${D}{${BIN_ENV}:-<unset>}, ${D}ROOT/node_modules/${PACKAGE_NAME}, ${D}ROOT/${LOCAL_BIN}, ${CLI} on PATH" >&2
+# The remedy is assigned single-quoted and echoed, so a command in it - the binary
+# download derives its platform with $(uname) - stays text here and runs only when
+# the reader runs it. A remedy in double quotes would be half-executed by this echo.
+remedy='${remedy}'
 echo "${remedy}" >&2
 exit 1
 `;