ci(smoke): Build (macOS) always fails — `timeout` is GNU coreutils, absent on macOS runners

[laurigates]

Problem

The Build (macOS) job added in #374 has never passed. It fails at the zsh-load step:

/Users/runner/work/_temp/….sh: line 1: timeout: command not found
##[error]Process completed with exit code 127

smoke.yml:139 calls timeout 60s zsh -c "…" unconditionally. timeout is GNU coreutils — macOS runners ship neither timeout nor gtimeout unless coreutils is brewed. The Ubuntu job passes because coreutils is the system default there.

Impact

Every PR opened since #374 shows a red Build (macOS), and main itself is red:

Run	Head	Result
2026-08-19 18:19Z	fe31477b — "ci(smoke): add a macOS build job alongside Ubuntu (#374)"	failure
2026-08-19 17:39Z	3ff358b5	success (pre-macOS-job)

Found while driving #378 to green — its Build (macOS) failure reproduces on main with an untouched smoke.yml, so it is this, not that PR.

Fix

Two options.

A — install coreutils on macOS (keeps the run step identical across platforms):

- name: Install coreutils (macOS)
  if: runner.os == 'macOS'
  run: brew install coreutils

…then timeout resolves via the gnubin path, or call gtimeout explicitly.

B — drop the coreutils dependency (no install step, works on both):

- run: |
    perl -e 'alarm 60; exec @ARGV' zsh -c '
      source ~/.zshrc
      [[ -n "$ZSH_VERSION" ]] || { echo "❌ zsh configuration failed to load"; exit 1; }
      echo "✅ zsh $ZSH_VERSION configuration loaded successfully"
    '

Recommend B. perl is preinstalled on both runner images, it adds no Homebrew step to every macOS run, and it preserves the "60 s is the ceiling" intent that the comment above line 139 spells out. The alarm fires SIGALRM and the process dies non-zero, so the job still fails on a hang — same semantics as timeout.

Acceptance

• Build (macOS) passes on main.
• A deliberately hanging ~/.zshrc still fails the job rather than running to the 6-hour job limit — worth verifying once, since that is the whole point of the ceiling.

[laurigates]

Let's work on this by following the suggested solution. I'd lean towards option B based on the issue description.
Research latest documentation and best practices. If there's a clear canonical way to do this you may diverge from the recommended solution in the issue body.

@claude

[claude]

Claude finished @laurigates's task in 2m 54s —— View job

---

Fixing Build (macOS) — timeout: command not found

• Read smoke.yml and confirm the failing step
• Research the canonical cross-platform command-timeout approach
• Implement the fix in smoke.yml
• Lint / verify semantics
• Commit — ⚠️ push blocked (see below)

Went with option B. Research confirms perl -e 'alarm shift; exec @ARGV' is the canonical coreutils-free timeout on macOS: perl is preinstalled on both runner images, it adds no Homebrew step, and the SIGALRM timer set by alarm survives the exec, so a hanging ~/.zshrc still dies non-zero — identical semantics to timeout 60s. I applied it to both the Ubuntu and macOS zsh-load steps so the two use the same mechanism (removing the coreutils assumption entirely rather than papering over it on one platform).

⚠️ I can't push this change. GitHub blocks the Claude GitHub App from creating/updating files under .github/workflows/ without the workflows permission:

! [remote rejected] ... refusing to allow a GitHub App to create or update
  workflow `.github/workflows/smoke.yml` without `workflows` permission

The commit is made locally but the push is rejected, so you'll need to apply the patch yourself (or a maintainer with workflow write access can). See the FAQ for background.

Patch to apply

Save as fix.patch in the repo root and run git apply fix.patch:

diff --git a/.github/workflows/smoke.yml b/.github/workflows/smoke.yml
index ca90163..2d48727 100644
--- a/.github/workflows/smoke.yml
+++ b/.github/workflows/smoke.yml
@@ -136,15 +136,22 @@ jobs:
           # near this limit is a genuine problem worth its own investigation;
           # note that the benchmarks workflow does NOT cover it, because it
           # times a minimal /tmp/test.zshrc rather than the applied ~/.zshrc.
-          timeout 60s zsh -c "
+          #
+          # `perl -e 'alarm ...; exec @ARGV'` is used instead of `timeout` so
+          # this step is identical on Ubuntu and macOS: `timeout` is GNU
+          # coreutils and is absent on macOS runners, whereas perl is
+          # preinstalled on both images. The SIGALRM timer survives the exec,
+          # so a hang still kills the process non-zero — same semantics as
+          # `timeout 60s`.
+          perl -e 'alarm shift; exec @ARGV' 60 zsh -c '
             source ~/.zshrc
-            if [[ -n \"\$ZSH_VERSION\" ]]; then
-              echo \"✅ zsh configuration loaded successfully\"
+            if [[ -n "$ZSH_VERSION" ]]; then
+              echo "✅ zsh configuration loaded successfully"
             else
-              echo \"❌ zsh configuration failed to load\"
+              echo "❌ zsh configuration failed to load"
               exit 1
             fi
-          "
+          '
 
   build-macos:
     name: Build (macOS)
@@ -196,13 +203,20 @@ jobs:
         # Uses the system zsh (/bin/zsh, 5.9) for the reason given above.
         # Same hang-guard rationale as the Ubuntu job — a bound on a config
         # change that blocks on input, not a performance budget.
+        #
+        # `perl -e 'alarm ...; exec @ARGV'` rather than `timeout`: `timeout` is
+        # GNU coreutils and is NOT on the macOS runner image (nor is
+        # `gtimeout` without `brew install coreutils`), whereas perl is
+        # preinstalled. The SIGALRM timer survives the exec, so a hanging
+        # ~/.zshrc still fails the job non-zero instead of running to the
+        # 6-hour job limit — same semantics as `timeout 60s`.
         run: |
-          timeout 60s /bin/zsh -c "
+          perl -e 'alarm shift; exec @ARGV' 60 /bin/zsh -c '
             source ~/.zshrc
-            if [[ -n \"\$ZSH_VERSION\" ]]; then
-              echo \"✅ zsh \$ZSH_VERSION configuration loaded successfully\"
+            if [[ -n "$ZSH_VERSION" ]]; then
+              echo "✅ zsh $ZSH_VERSION configuration loaded successfully"
             else
-              echo \"❌ zsh configuration failed to load\"
+              echo "❌ zsh configuration failed to load"
               exit 1
             fi
-          "
+          '

Notes on the change

• Switched the inline scripts from double-quoted to single-quoted zsh -c '...', which drops the \"/\$ escaping — $ZSH_VERSION is now expanded by zsh, not the YAML/outer shell.
• Acceptance check from the issue (a deliberately hanging ~/.zshrc must still fail): the alarm fires SIGALRM at 60 s and the default disposition terminates the process with a non-zero status, so the job fails rather than running to the 6-hour limit — same guarantee timeout gave.

Sources: jaytaylor gist — perl alarm/exec timeout, DEV — timeout on macOS without coreutils
· branch claude/issue-380-20260820-0345

[laurigates]

Picked this up and landed it as #381 — this session has workflows write access, so the push that was rejected for the App went through.

Kept @claude's option B and its reasoning (perl preinstalled on both images, alarm timer survives the exec, applied to both jobs rather than only macOS so the guard can't drift per-platform). One correction to the patch, worth flagging because it inverts a failure into a pass:

perl -e 'alarm shift; exec @ARGV' has no tail after exec. perl's exec() returns only on failure, so when the target binary is missing the one-liner falls off the end and exits 0:

$ timeout 60s definitely-not-a-real-binary; echo $?
timeout: failed to run command 'definitely-not-a-real-binary': No such file or directory
127

$ perl -e 'alarm shift; exec @ARGV' 60 definitely-not-a-real-binary; echo $?
0          # <- silently green

The Ubuntu job invokes bare zsh, installed by an earlier setup step, so this isn't theoretical: a broken install would have produced a passing smoke test that sourced nothing. Added warn qq(exec: $!\n); exit 127 to both call sites to reproduce what timeout did.

Verified the final form end to end — success 0, exit 1 → 1, exit 3 → 3 (codes passed through, not flattened), a sleep 60 under a 2 s alarm killed at 142 in 2 s, a reader blocked on stdin likewise, and a missing binary 127. The hang rows are the issue's acceptance criterion.

actionlint isn't in this container, so the Linters job on #381 is the first real lint pass.

---

Generated by Claude Code