# Handoff — 2026-08-31 — the installer's macOS reinstall failure

## State

**Fixed**, on branch `feature/go-format-lint` alongside the Go-tools work, **uncommitted**.

`scripts/install.sh` printed `✗ the installed binary does not run` after a clean build on macOS. The cause was `cp` writing into the existing binary's inode; macOS caches a code signature per inode, so the kernel refused to execute bytes that no longer matched. The installer now writes `.turbo-go.incoming.$$` inside `$prefix` and renames it over the target, giving the name a fresh inode — and making the install atomic.

The verification also captures the binary's own stderr and prints it, so the next such failure names itself.

- 3 new tests in `install_test.go` (13 total); the two behavioural ones were confirmed failing against the `cp` version.
- Whole suite green. Quality gate **PASS**: 0/0/0.
- `how-to/install.md` gained a "When something goes wrong" section in both languages.

## In flight

Nothing.

## Next steps

1. **Ask the user to re-run `scripts/install.sh` on their Mac.** That is the only real confirmation available — see the blocker below.
2. **Commit.** This sits on the same uncommitted branch as the Go tools work.

## Open questions / blockers

- **The fix was never reproduced on macOS.** This sandbox is Linux. `darwin/arm64` and `darwin/amd64` cross-compile and vet cleanly, and the symptom — builds, installs, will not run, on a *reinstall* — matches the inode/signature failure exactly, but "matches exactly" is not "reproduced". If it recurs, the installer now prints the system's own message above the failure; that message is the thing to work from, not this diagnosis.
- **The user's `demo/.turbo-go/tools.toml` predates the `output` key** (written 13:57, before the key existed). It still works — an absent `output` means `popup` — but `Run` will be a popup there, which blocks on an interactive program. Deleting it and re-running **Go ▸ Create tools file** gets the commented file with `Run` set to `terminal`. It is their file; untouched.

## Watch out for

- **Never install a binary with `cp` over an existing one.** It is the inode that carries the code signature on macOS, and the failure is silent, delayed, and looks like a build problem. Rename a complete file into place.
- **The temporary must be in `$prefix`, not in `$STAGING`.** A rename only works within one filesystem, and `mktemp -d` is usually somewhere else entirely.
- **`install -m 0755` is not a fix.** On some platforms it writes in place too.
- **`inodeOf` in `install_test.go` uses `syscall.Stat_t`** and skips where that is unavailable, so the test is Unix-only by construction rather than by accident.