Monorepo for Aesthetic.Computer
aesthetic.computer
docs: add intel mac usb boot debug handoff
+180
+180
reports/2026-03-29-intel-mac-usb-boot-debug.md
+180
reports/2026-03-29-intel-mac-usb-boot-debug.md
···
1
+
# Intel Mac USB Boot Debug Handoff
2
+
3
+
Prepared on 2026-03-29 from the local flashing/debugging session in `/workspaces/aesthetic-computer`.
4
+
5
+
## Goal
6
+
7
+
Get `fedac/native` USB media to appear and boot reliably on an older Intel MacBook while preserving per-user `config.json` and the recent hybrid-media work.
8
+
9
+
## Current Repo State
10
+
11
+
At the time of this note:
12
+
13
+
- Branch: `main`
14
+
- HEAD: `39f4a773c`
15
+
- Worktree: clean before adding this report
16
+
17
+
The current checked-in native changes already include:
18
+
19
+
- `fedac/native/ac-os`
20
+
- `build_kernel()` now stages built-in firmware from `/usr/lib/firmware` or `/lib/firmware`, including nested paths like `i915/glk_dmc_ver1_04.bin`.
21
+
- `fedac/native/initramfs/init`
22
+
- USB mount logic now prefers a FAT partition with `config.json` before falling back to FAT partitions that only have boot files.
23
+
- `fedac/native/src/ac-native.c`
24
+
- Display-failure diagnostics now write to `/mnt/ac-init.log` instead of `/mnt/usb/ac-init.log`.
25
+
- `fedac/native/scripts/flash-helper-runner.sh`
26
+
- This file is where the Intel-Mac-specific boot-media behavior was being iterated during this session.
27
+
28
+
## Build Result
29
+
30
+
A fresh local kernel build completed successfully during this session.
31
+
32
+
- `fedac/native/build/vmlinuz`
33
+
- Size: `282571776`
34
+
- SHA256: `09e1f63b92540d12a0f5209b5566894540f9c53e776cedd9aa557a23dabdbb0b`
35
+
36
+
## What Happened
37
+
38
+
### 1. Initial hybrid flash was discoverable but wrong on the Mac
39
+
40
+
The first hybrid-media flash produced 3 visible `EFI Boot` entries on the old Intel MacBook.
41
+
42
+
Local verification showed why:
43
+
44
+
- partition 1 (`ACBOOT`) had `config.json`, `EFI/BOOT/BOOTX64.EFI`, and `EFI/BOOT/KERNEL.EFI`
45
+
- partition 2 (`ACEFI`) had the same boot tree
46
+
- partition 3 (`AC-MAC`) had the same boot tree plus a blessed Mac path
47
+
48
+
That matched the Mac behavior: 3 generic boot targets.
49
+
50
+
The user reported:
51
+
52
+
- all 3 `EFI Boot` entries appeared
53
+
- each one crashed/rebooted back into macOS
54
+
55
+
At the same time, the USB had no runtime logs written back to the writable partition. That strongly suggested the failure was happening before Linux userland mounted the writable FAT partition.
56
+
57
+
### 2. First attempt to force a single Mac target regressed too far
58
+
59
+
The next iteration tried to force a single Apple-visible target by:
60
+
61
+
- removing `BOOTX64.EFI` from the FAT helper partitions
62
+
- hiding the FAT partitions in partition metadata
63
+
- leaving only a blessed HFS Mac path
64
+
- using a direct-kernel `boot.efi` on the HFS partition
65
+
66
+
This was the version the user tried next, and the old Intel MacBook did not show the stick at all.
67
+
68
+
That is the key regression.
69
+
70
+
### 3. The USB then became awkward to rewrite cleanly in-place
71
+
72
+
After one interrupted rewrite, `/dev/sda1` remained kernel-busy inside the privileged helper environment:
73
+
74
+
- `mkfs.vfat /dev/sda1` kept returning `Device or resource busy`
75
+
- `sda2` and `sda3` were still writable
76
+
- `sda1` could not be cleanly reformatted again during this session
77
+
78
+
Because of that, later updates were done in-place on `sda2` and `sda3` rather than from a perfectly clean full reprovision.
79
+
80
+
## Current USB State
81
+
82
+
The most recent local write left the stick in this state:
83
+
84
+
- GPT still has 3 partitions:
85
+
- `sda1` `ACBOOT`
86
+
- `sda2` `ACEFI`
87
+
- `sda3` `AC-MAC`
88
+
- Hybrid MBR currently advertises only the Apple HFS partition:
89
+
- protective entry
90
+
- `0xAF` for the HFS partition
91
+
- `sda2` was refreshed and verified to contain:
92
+
- `config.json`
93
+
- `EFI/BOOT/KERNEL.EFI`
94
+
- no `EFI/BOOT/BOOTX64.EFI`
95
+
- `sda3` was refreshed with:
96
+
- `System/Library/CoreServices/boot.efi`
97
+
- that file’s SHA256 matched the rebuilt kernel hash above
98
+
99
+
Important caveat:
100
+
101
+
- this exact latest USB state was not re-tested by the user on the old MacBook before this report was requested
102
+
- the last user-observed result on the old MacBook was still: “did not show up at all”
103
+
104
+
## Source-Backed Findings
105
+
106
+
The web check suggests the “hide everything except one blessed HFS file” approach was too improvised and not close enough to the Fedora path.
107
+
108
+
### Fedora docs
109
+
110
+
Fedora’s `livecd-iso-to-disk --efi` docs explicitly say that this mode is necessary for most Intel Macs and can create up to 3 partitions:
111
+
112
+
- main image partition
113
+
- EFI helper partition from `/images/efiboot.img`
114
+
- HFS+ Mac helper partition from `/images/macboot.img`
115
+
116
+
Source:
117
+
118
+
- https://raw.githubusercontent.com/livecd-tools/livecd-tools/master/docs/livecd-iso-to-disk.pod
119
+
120
+
### Fedora implementation
121
+
122
+
The `livecd-iso-to-disk.sh` source does not treat the Mac helper partition as “just write one arbitrary `boot.efi` file.” It formats the HFS partition and copies the contents of `macboot.img` into it.
123
+
124
+
Source:
125
+
126
+
- https://raw.githubusercontent.com/livecd-tools/livecd-tools/main/tools/livecd-iso-to-disk.sh
127
+
128
+
### Fedora Mac EFI notes
129
+
130
+
Fedora’s Intel Mac EFI notes emphasize:
131
+
132
+
- HFS+ blessing matters
133
+
- Apple-visible boot media needs Apple-style metadata, not just a generic GPT ESP
134
+
135
+
Source:
136
+
137
+
- https://fedoraproject.org/wiki/User%3APjones/MacCDsForEFI
138
+
139
+
### Apple boot path
140
+
141
+
Apple’s booting documentation describes `/System/Library/CoreServices/boot.efi` as the standard bootloader path for the simplest boot configuration.
142
+
143
+
Source:
144
+
145
+
- https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/KernelProgramming/booting/booting.html
146
+
147
+
### HFS blessing tool
148
+
149
+
`hfs-bless` is explicitly meant to make an HFS+ filesystem bootable for EFI Apple hardware.
150
+
151
+
Source:
152
+
153
+
- https://www.mankier.com/1/hfs-bless
154
+
155
+
## Best Current Reading
156
+
157
+
The safest reading is:
158
+
159
+
- the older Intel MacBook is sensitive to the exact Apple helper partition layout
160
+
- the first “3 EFI Boot” result showed the stick was at least discoverable
161
+
- the later “single visible target” rewrite likely removed or distorted something the old Mac firmware needed for discovery
162
+
- Fedora’s documented path is closer to “separate helper images for EFI and Mac” than to the custom hidden-partition approach used in the later local experiment
163
+
164
+
## Recommended Next Step
165
+
166
+
Claude should optimize for “shows up and boots” first, not for deduplicating the Option-boot picker.
167
+
168
+
Recommended order:
169
+
170
+
1. Move `fedac/native/scripts/flash-helper-runner.sh` back toward a Fedora-style discoverable layout.
171
+
2. Stop hiding the helper FAT partition(s) until boot discovery is stable on the old MacBook.
172
+
3. Recreate a proper Mac helper partition rather than treating partition 3 as only a hand-written `boot.efi` drop.
173
+
4. Once the stick reliably appears and boots, then iterate on reducing duplicate Option-boot entries.
174
+
175
+
## Practical Notes For Claude
176
+
177
+
- Do not assume the current USB contents are a clean baseline. `sda1` became sticky/busy after an interrupted rewrite.
178
+
- The rebuilt kernel artifact is good and verified.
179
+
- The biggest unresolved problem is old-Intel-Mac discovery semantics, not Linux kernel compilation.
180
+
- If you need a fully clean USB reprovision, physically replugging the stick may be the fastest way to clear the stale `sda1` busy state before retrying.