Mac5 Codex handoff — 2026-04-26 ~14:30 local (last revised ~16:15 post-Wave-5)

Mac5 Codex handoff — 2026-04-26 ~14:30 local (last revised ~16:15 post-Wave-5)

> Topology correction, 2026-04-26: Mac4 is the current Unity Editor / GUI smoke-test host and real-Femto capture host. Mac5 is still the synthpub LaunchAgent / synthetic fallback host. Do not blindly replace all Mac5 references; see `software/demo/TOPOLOGY-CORRECTION-2026-04-26.md`.

This file supersedes the 2026-04-25 handoff (`MAC5-CODEX-HANDOFF.md`,
which anchored on Wave 1 only). This one covers Waves 1-5 (22 commits)
plus the Duncan reference library + gap analysis.

Updated reading order (read in this order, top to bottom)

1. `CODEX-CONTEXT.md` — origin, evolution, decision log. Why the
pipeline looks the way it does. Read this FIRST.
2. `unity/lume_pcloud/ARCHITECTURE.md` — current state mental
model. The 10-component graph + 13 global uniforms + wire formats.
3. `CODEX-PLAN.md` — priority-ranked next-action list with success
criteria + escalation triggers.
4. This file — operational bootstrap prompt (below). Paste into
Codex on Mac5 once you've read 1-3.
5. `DUNCAN-GAP-ANALYSIS.md` — what's left to match Duncan's stack.
6. `Reference/Duncan/INDEX.md` — 83 reels + 69 analyses, indexed by
Duncan's own E-numbering.

Paste from `## ↓↓↓ paste this to Codex ↓↓↓` to the end of this file as
the bootstrap prompt.

---

↓↓↓ paste this to Codex ↓↓↓

You are taking over the LUME real-time visual pipeline on Mac5. Mohamed
is the user; Claude Code did the prior 16 commits. You're reading this
fresh so I'll give you absolute pickup state, not a narrative.

### Where the code lives
- Repo: `Desktop/lume-commerce/` (Mac1 source-of-truth, Mac5 mirror)
- Branch: `main` (no push — local commits only)
- Working dir: `Desktop/lume-commerce/software/demo/`
- Unity project: `software/demo/unity/lume_pcloud/`

### Mac5 vs Mac1
Mac1 (Mohamed's primary Mac) is the source of truth. Mac5 is a mirror
maintained via rsync. Run all `git` commands on Mac1. On Mac5, only
do Unity Editor work + run Python publishers + test the visuals. If
you find diff between Mac1 and Mac5, sync from Mac1; never the other
way round.

What's shipped (22 commits, newest first)

Pipeline overview (memorize)

   pointcloud_pub.py ── :9700 LUME (cloud) / LUMD (raw depth) ──┐
                                                                 ▼
   audio_pub.py      ── :9701 LUMF (84-byte fixed datagrams) ──▶ Unity
                                                                 │
                              LumeUdpReceiver (magic dispatch)   │
                                ├─▶ LumePointRenderer (Cloud)    │
                                └─▶ LumeDepthReprojector (Depth) │
                                      └─▶ LumeOpticalFlow        │
                                            ├─▶ SetInnerSpread (W3 scalar)
                                            └─▶ _FlowField RG16F (W4 vector)
                              LumeAudioFftReceiver (LUMF)       │
                                └─▶ overrides _AudioLevels      │
                              LumeVfxRuntimeBridge              │
                                └─▶ pushes globals into VFX     │

Wave 1 cloud path is the always-on graceful-degrade floor. Disabling W2/3/4
components on the GameObject reverts to Wave 1 with no code changes.

Smoke-test in 5 commands

cd Desktop/lume-commerce/software/demo

# 1. open Unity, scene LumeMain.unity (or run Lume → Bootstrap Scene → Procedural Tunnel)
# 2. menu: Lume → Auto-Wire Wave 1+2+3   (idempotent)
# 3. press Play
# 4. terminal:
python3 pointcloud_pub.py --synthetic-depth --host [ip] --port 9700 \
  --depth-width 512 --depth-height 512 --fps 30
# 5. another terminal:
python3 audio_pub.py --synthetic --host [ip] --port 9701 --fps 60

# Sanity-check protocol streams without Unity:
python3 lume_packet_inspector.py     # binds 9700+9701, rolling diagnostics

Full step-by-step: `MAC5-SMOKE-TEST.md` in this directory (6 stages,
each with expected visual outcome + red-flag failure modes).

Test suite

cd Desktop/lume-commerce/software/demo
python3 -m pytest tests/ -q              # 33 fast tests, sub-second
python3 -m pytest tests/ -m slow -v      # 4 slow integration tests, ~5s
LUME_RUN_SLOW=1 python3 -m pytest tests/  # all 37

If any test fails, stop and report. Do NOT push fixes without confirming
the failure is real (some tests use ephemeral ports — collisions are flaky).

LaunchAgents on Mac5

# Install (idempotent):
bash launchagents/install-mac5.sh

# Health check (one-shot diagnostic):
bash launchagents/health-check.sh

The `com.lume.synthpub-mac5` agent has been live since 2026-04-25 (per
memory: pid 24126 at handoff). The new `com.lume.audio-pub-mac5` agent is
not yet installed on Mac5 — running `install-mac5.sh` from a fresh
mac5 shell brings it up.

Don't-touch list

- `pointcloud_pub.py` — the `synthpub-mac5` LaunchAgent runtime depends
on its CLI. Adding flags is fine; renaming/removing is breaking.
- `LumeUdpReceiver.cs` — magic-byte dispatch is settled; do not refactor.
- `LumeAudioReactor.cs` — parallel session contract. Use the public
setters (`SetInnerSpread`); don't modify the class.
- Wave 1 cloud path — must stay bit-preserved. Anything that breaks the
Wave 1 Sat-demo floor is out of scope.
- `[home-path]` — clear stale `index.lock` if present (no live `git` process),
but do NOT touch any other git state.

Wave 5 priorities (3 of 5 already shipped, 2 remaining)

Read `CODEX-PLAN.md` for the full action list with success criteria,
files to touch, and escalation triggers. Items 4-5 are heavy ports
(~1 day each) that NEED real Unity Editor compilation feedback to
ship safely — don't start them blind. Mac5 GUI smoke-test (P0.3 in
`CODEX-PLAN.md`) is the unblock.

How to ask me (Claude) for help

If you hit a blocker:
1. Capture the exact error / git state / Unity console message.
2. Check the relevant memory file:
`[home-path]` is the
index. The chunks (DV-DU, DT-DS, DR-DQ) are authoritative for
Duncan-source quotes; per-wave progress files
(`lume-v2-depth-reproject-progress.md` etc) are authoritative for
what each commit ships.
3. Then write a focused message back to Mohamed describing what's stuck
and what you tried. Don't silently downgrade or skip steps.

Quality bar

- No git push.
- No new memory files unless something new + non-obvious is learned.
- No Unity scene `.unity` edits via text (those are GUI-authored — use
the Editor menus or the scene-patch sidecar pattern).
- Stable .meta GUIDs for any new Unity asset (use the pattern
`99990000fefdcccc9999bbbb3333eeee` — numeric, not random).
- After each commit, rsync to Mac5: `rsync -av --no-perms ... mac5:.../`
(Mac5 was unreachable as of this handoff — Tailscale 100
`ping mac5` first).

Open hardware blockers (NOT yours to solve)

- Femto Bolt order: Mohamed will buy when K11 arrives. Defer Wave 5
CAD changes until then.
- Mac4 TCC: real Femto on Mac4 still blocked — no real depth feed
to test against. Stay on `--synthetic-depth` until unblocked.
- K11 mini-PC: not yet onsite. Wave 5 Linux-x86_64 build profile
is paper-only until it arrives.

### One-line summary
*Wave 4 is feature-complete on the autonomous-code side; Wave 5 starts
with the third-audio-channel wire (small) then fluid sim (large) per
the gap analysis.*

↑↑↑ end paste to Codex ↑↑↑

---

Context Mohamed should also know

- Duncan reference library lives at `software/demo/unity/lume_pcloud/Reference/Duncan/`.
Outside `Assets/`, so Unity ignores it. Open `INDEX.md` from Finder.
- `refresh_duncan_corpus.sh` pulls newer reels from his profile when run.
Idempotent — safe to schedule daily / weekly.
- `DUNCAN-GAP-ANALYSIS.md` is the "what's left to match Duncan" doc — read
before planning Wave 5.