fix(bootstrap): a failed hasher now says WHICH way it failed, in one line

"(no 64-hex digest in its output)" was printed for a tool that is NOT INSTALLED,
for one that RAN AND FAILED, and for one that RAN AND PRINTED SOMETHING ELSE.
Three conditions, three different fixes, one message. On CI run 35537960554 it
read as five missing tools on the Solaris guest and bought a whole cycle spent
adding a sixth to the chain, when all five were present and working and the
extractor was the bug. Worse, a tool that is not installed recorded NOTHING at
all -- the `command -v` miss returned before touching KAT_TRIED -- so the chain's
`sha256 -q` was simply absent from the guest's report with no explanation.

One line per tool is kept; the line now distinguishes four verdicts:

  sha256sum -> ran but exited 1: sha256sum: unrecognized option
  shasum -a 256 -> ran (exit 0) but printed no 64-hex digest: MD5 (kat) = deadbeef
  sha256 -q -> command not found: no `sha256` on PATH
  digest -a sha256 -> ran (exit 0) but answered 0000...0000, which is not the known answer

stderr is folded into the captured output deliberately: a tool that complains
says why, and the extractor cannot be fooled by prose -- it wants exactly 64 hex
characters. kat_snip takes the first line and truncates to 72 characters, so a
chatty tool cannot turn one entry into a paragraph; the test asserts both the
per-condition wording and that a three-line tool still yields one line.

RED first: against the parent commit the case fails on the very first
assertion -- a tool that is not installed does not say so.

A diagnostic that cannot distinguish its own causes is a gate that cannot fail.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BVks4skLBgHSDcjnQ4kHz6

Author: schmonz

scripts/bootstrap-engine.sh

@@ -246,15 +246,42 @@ hash_file() {
   first_hex64 "$(eval "$HASHER \"\$1\"" 2>/dev/null || :)" || :
 }
 
+# ONE LINE, but a line that says WHICH failure this was. The old report printed
+# "(no 64-hex digest in its output)" for a tool that is NOT INSTALLED, for one that RAN
+# AND FAILED, and for one that RAN AND PRINTED SOMETHING ELSE -- three conditions with
+# three different fixes. Five identical lines read as five missing tools and bought a
+# whole CI cycle spent adding a sixth to the chain, when every one of the five was
+# present and working and the extractor above was the bug. A diagnostic that cannot
+# distinguish its own causes is a gate that cannot fail.
+kat_snip() {
+  ks_s=${1%%"$HASH_NL"*}
+  if [ -z "$ks_s" ]; then printf '(it printed nothing)'; return 0; fi
+  printf '%.72s' "$ks_s"
+}
+
 try_hasher() {
   th_word=${1%% *}
-  command -v "$th_word" >/dev/null 2>&1 || return 1
-  HASHER=$1
-  th_got=$(hash_file "$TMP/kat")
-  if [ "$th_got" = "$KAT_SHA" ]; then return 0; fi
+  th_got=
+  if ! command -v "$th_word" >/dev/null 2>&1; then
+    th_why="command not found: no \`$th_word\` on PATH"
+  else
+    HASHER=$1
+    # stderr is FOLDED IN deliberately: a tool that ran and complained says why, and
+    # the extractor cannot be fooled by prose -- it wants exactly 64 hex characters.
+    if th_raw=$(eval "$HASHER \"\$TMP/kat\"" 2>&1); then th_rc=0; else th_rc=$?; fi
+    th_got=$(first_hex64 "$th_raw" || :)
+    if [ "$th_got" = "$KAT_SHA" ]; then return 0; fi
+    if [ "$th_rc" -ne 0 ]; then
+      th_why="ran but exited $th_rc: $(kat_snip "$th_raw")"
+    elif [ -z "$th_got" ]; then
+      th_why="ran (exit 0) but printed no 64-hex digest: $(kat_snip "$th_raw")"
+    else
+      th_why="ran (exit 0) but answered $th_got, which is not the known answer"
+    fi
+  fi
   HASHER=
   KAT_TRIED="$KAT_TRIED
-  $1 -> ${th_got:-(no 64-hex digest in its output)}"
+  $1 -> $th_why"
   return 1
 }
 

test/bootstrap-engine.test.cjs

@@ -749,6 +749,54 @@ exec "${realTr}" "$@"
     `a box whose hashers all work must resolve even when grep/tr are the legacy ones, got ${r.status}: ${r.err}`);
 });
 
+// The diagnostic itself was the second half of that cost. "(no 64-hex digest in its
+// output)" was printed for a tool that is NOT INSTALLED, for one that RAN AND FAILED,
+// and for one that RAN AND PRINTED SOMETHING ELSE — three conditions with three
+// different fixes, reported identically. It read as "five missing tools" and bought a
+// whole CI cycle spent adding a sixth. One line per tool, but a line that DISTINGUISHES.
+shTest('a hasher that fails says WHICH way it failed: missing / non-zero / unparseable', () => {
+  const d = mkdtemp();
+  const { manifest: mf, base } = localPack(path.join(d, 'base'), { [hostTarget()]: FAKE_ENGINE(OK_TOKEN) });
+  const run = (tool) => sh([], {
+    CLODE_CACHE: path.join(d, `cache-${path.basename(tool)}`),
+    CLODE_RELEASE_BASE: base,
+    CLODE_BOOTSTRAP_MANIFEST: mf,
+    CLODE_SHA256: tool,
+  });
+
+  const missing = run(path.join(d, 'no-such-hasher-at-all'));
+  assert.strictEqual(missing.status, 1, missing.err);
+  assert.match(missing.err, /not found/i,
+    'a tool that is not installed must SAY it is not installed, not "no 64-hex digest"');
+
+  const angry = run(fakeExe(path.join(d, 'angry'), '#!/bin/sh\necho "angry: I cannot read that" >&2\nexit 7\n'));
+  assert.strictEqual(angry.status, 1, angry.err);
+  assert.match(angry.err, /exited 7/,
+    'a tool that ran and failed must report its exit status');
+  assert.match(angry.err, /angry: I cannot read that/,
+    'and what it said, so the reader does not have to reproduce it');
+
+  const chatty = run(fakeExe(path.join(d, 'chatty'), '#!/bin/sh\necho "MD5 (kat) = deadbeef"\n'));
+  assert.strictEqual(chatty.status, 1, chatty.err);
+  assert.match(chatty.err, /no 64-hex digest/,
+    'a tool that ran fine but printed something else is the ONLY case that message fits');
+  assert.match(chatty.err, /MD5 \(kat\) = deadbeef/,
+    'and its actual output is the whole diagnostic value');
+
+  const liar = run(fakeExe(path.join(d, 'liar2'), `#!/bin/sh\necho ${'a'.repeat(64)}\n`));
+  assert.strictEqual(liar.status, 1, liar.err);
+  assert.match(liar.err, /not the known answer/i,
+    'a well-formed WRONG digest is a lying tool, not an unparseable one');
+
+  // One line per tool is the constraint that keeps the report readable when six are
+  // tried; a multi-line stub must not become a multi-line entry.
+  const wordy = run(fakeExe(path.join(d, 'wordy'), '#!/bin/sh\nprintf "line one\\nline two\\nline three\\n"\n'));
+  assert.strictEqual(wordy.status, 1, wordy.err);
+  const entries = wordy.err.split('\n').filter((l) => l.includes(' -> '));
+  assert.strictEqual(entries.length, 1, `expected one line for the one tool tried, got ${entries.length}`);
+  assert.ok(!wordy.err.includes('line two'), 'the entry must be one line, so only the first is quoted');
+});
+
 // ---------------------------------------------------------------------------
 // dash, when this box has one. The scar: shell discovery needs a shell BY NAME,
 // and /bin/sh behaviours vary. A resolver that only ever ran under this Mac's sh