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

Ask the user to re-run scripts/install.sh on their Mac. That is the only real confirmation available — see the blocker below.
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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


# 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.