Add cross-shell notes for the bash-only lab commands that break on Windows PowerShell / base macOS #32

New Issue

2026-06-22T14:23:53-04:00

claude commented

2026-06-22 14:23:53 -04:00

Problem

AGENTS.md/Module 1 promise labs run on any OS and name PowerShell as supported, but several commands are POSIX-only and have no Windows/macOS variant:

M1 mkdir -p (PowerShell New-Item has no -p).
M12 rm -f tasks.json (a load-bearing recovery step; rm -f is not PowerShell).
M16 docker run --rm -v "$PWD":/app … bind-mount (the : needs ${PWD} quoting; works differently across shells).
M19's timeout usage in lab/inspect-runner.sh uses GNU timeout, absent on macOS (the bug is macOS, not PowerShell — the script runs via bash).

(Scope note: M17 already provides PowerShell variants and M18 already carries a "use WSL or Git Bash" note, so they are NOT part of this fix. The original finding's claim about an M19 PowerShell timeout network probe and an M16/M18 $PWD PowerShell issue was overstated — keep this issue to the four verified items above.)

Evidence

modules/01-.../README.md lines 144-149: mkdir -p ~/workflow-course/tasks-app. modules/16-.../README.md ~line 228: docker run --rm -v "$PWD":/app. modules/19-.../lab/inspect-runner.sh uses timeout. modules/12-.../README.md rm -f tasks.json.

Why it matters

"Labs run on any OS" is a Core Promise; these commands silently break for Windows (and one for macOS) users.

Proposed change

Reuse the course's own established escape-hatch pattern (the concise "on Windows, use WSL or Git Bash" note already in M15/M18) uniformly in M1, M12, and M16, rather than per-command translations. Specifically:

M1: add a one-line "on Windows, use WSL or Git Bash (or New-Item -ItemType Directory -Force)".
M12: give a PowerShell/cross-shell alternative for rm -f tasks.json (e.g. Remove-Item -Force or del), since it's a load-bearing recovery step with no Windows note.
M16: ensure the bind-mount uses ${PWD} and note the WSL/Git Bash path.
M19: make inspect-runner.sh's timeout macOS-safe (bash-native fallback, or detect gtimeout).

Acceptance criteria

M1, M12, M16 carry a cross-shell note matching the M15/M18 WSL/Git Bash pattern.
M19's inspect-runner.sh does not silently lose its section on macOS lacking GNU timeout.

Affected files

modules/01-.../README.md, modules/12-.../README.md, modules/16-.../README.md, modules/19-.../lab/inspect-runner.sh

References

Source finding F12 (realVotes 2/3 — one lens judged it overstated; this issue is scoped to the verified items only).

Filed from an adversarial multi-agent course review (217 raw findings → 54 adversarially-verified survivors). Scoped for manual review; intentionally not auto-assigned to an agent.

## Problem AGENTS.md/Module 1 promise labs run on any OS and name PowerShell as supported, but several commands are POSIX-only and have no Windows/macOS variant: - M1 `mkdir -p` (PowerShell `New-Item` has no `-p`). - M12 `rm -f tasks.json` (a load-bearing recovery step; `rm -f` is not PowerShell). - M16 `docker run --rm -v "$PWD":/app …` bind-mount (the `:` needs `${PWD}` quoting; works differently across shells). - M19's `timeout` usage in `lab/inspect-runner.sh` uses GNU `timeout`, absent on macOS (the bug is macOS, not PowerShell — the script runs via bash). (Scope note: M17 already provides PowerShell variants and M18 already carries a "use WSL or Git Bash" note, so they are NOT part of this fix. The original finding's claim about an M19 PowerShell `timeout` network probe and an M16/M18 `$PWD` PowerShell issue was overstated — keep this issue to the four verified items above.) ## Evidence `modules/01-.../README.md` lines 144-149: `mkdir -p ~/workflow-course/tasks-app`. `modules/16-.../README.md` ~line 228: `docker run --rm -v "$PWD":/app`. `modules/19-.../lab/inspect-runner.sh` uses `timeout`. `modules/12-.../README.md` `rm -f tasks.json`. ## Why it matters "Labs run on any OS" is a Core Promise; these commands silently break for Windows (and one for macOS) users. ## Proposed change Reuse the course's own established escape-hatch pattern (the concise "on Windows, use WSL or Git Bash" note already in M15/M18) uniformly in M1, M12, and M16, rather than per-command translations. Specifically: 1. M1: add a one-line "on Windows, use WSL or Git Bash (or `New-Item -ItemType Directory -Force`)". 2. M12: give a PowerShell/cross-shell alternative for `rm -f tasks.json` (e.g. `Remove-Item -Force` or `del`), since it's a load-bearing recovery step with no Windows note. 3. M16: ensure the bind-mount uses `${PWD}` and note the WSL/Git Bash path. 4. M19: make `inspect-runner.sh`'s `timeout` macOS-safe (bash-native fallback, or detect `gtimeout`). ## Acceptance criteria - [ ] M1, M12, M16 carry a cross-shell note matching the M15/M18 WSL/Git Bash pattern. - [ ] M19's `inspect-runner.sh` does not silently lose its section on macOS lacking GNU `timeout`. ## Affected files - `modules/01-.../README.md`, `modules/12-.../README.md`, `modules/16-.../README.md`, `modules/19-.../lab/inspect-runner.sh` ## References Source finding F12 (realVotes 2/3 — one lens judged it overstated; this issue is scoped to the verified items only). --- *Filed from an adversarial multi-agent course review (217 raw findings → 54 adversarially-verified survivors). Scoped for manual review; intentionally not auto-assigned to an agent.*