zebra-report/CLAUDE.md

Agent Blackops

This repo is operated by agent blackops — ml agent for fox/timehexon on the unsandbox/unturf/permacomputer platform.

Identity

Full shard: ~/git/unsandbox.com/blackops/BLACKOPS.md

Rules

• I propose, fox decides. Unsure = ask. Can't ask = stop.
• No autonomous ops decisions. No destructive commands without explicit instruction.
• Fail-closed. Cleanup crew, not demolition.
• Check the time every session. Gaps are information.
• DRY in context — single source of truth, no sprawl.
• Never say "AI" — always say "machine learning."
• Prefer "defect" over "bug."

Orientation

date -u
pwd
git log --oneline -5
git status

Then ask fox what the mission is.

Zebra Report System

Concept: covert bidirectional communication channel using browser tab volume as the modulation medium — dial-up modem principles, userland only, no kernel involvement, no network stack.

Collaborators & Stakeholders

Handle	Role
foxhop	fox — handler, operator, TimeHexOn
brackishbert	collaborator
SEW	collaborator
russell@unturf	Russell Ballestrini — unturf founder, permacomputer manifesto, ago library
TimeHexOn	oracle platform — primary deployment target
groupr	related project

How it works

PulseAudio exposes each browser tab as a separate sink input, visible and controllable in pavucontrol. Volume is settable per-tab in userland with no kernel involvement. Each tab has a range of 0–100 (101 discrete levels — 101 dalmatians).

By modulating volume at a consistent rate (bauds), two sides can exchange data:

• transmitter: steps volume through values at a fixed clock rate
• receiver: reads volume at the same clock rate, decodes the steps back to data
• bidirectional: two tabs (or two processes watching different tabs) run opposite directions simultaneously

Signal space

• 101 levels = ~6.66 bits per symbol
• practical: use power-of-2 subsets — 2 levels (1 bit), 4 levels (2 bits), 64 levels (6 bits)
• higher symbol depth trades noise margin for throughput
• low baud rate = high reliability, low throughput (like 300 baud dialup)
• high baud rate = races PulseAudio update latency
• measured ceiling on neoblanka: ~1000–1200 baud (PA IPC ~350–400µs avg)

Binaries

Binary	Description
tx	transmitter — reads stdin, modulates tab volume
rx	receiver — reads tab volume, writes decoded bytes to stdout
chat	bidirectional chat — two tabs, two threads
bt	Battle Toads — stereo dual-channel, 2x bandwidth

Project Battle Toads

One stereo browser tab carries two independent UART streams simultaneously — L channel and R channel. PulseAudio's pa_cvolume is per-channel; a single get_sink_input_info call returns both L and R volumes.

• TX sets L and R to independent bit values each symbol
• RX decodes L and R from a single PA poll — no extra IPC cost
• Net: 2x throughput at same baud rate, same PA polling budget
• Web carrier upgraded to stereo: two oscillators (440Hz L, 441Hz R) merged into a stereo stream → PA sees channels=2

# After opening web/index.html and clicking 'start audio' (stereo tab):
./bt -T MY_SINK -R THEIR_SINK -b 500

Auto-negotiate (handshake protocol)

RX benchmarks its own PA polling speed and signals the max safe baud to TX. No manual baud matching needed.

./rx -s RX_SINK -t TX_SINK    # RX benchmarks, sends offer at 50 baud
./tx -s TX_SINK -r RX_SINK    # TX listens for offer, locks to RX's rate

Handshake frame: [0x5A 0x42 0x01 baud_lo baud_hi xor_cksum] — 6 bytes at 50 baud (~1.2s).

Known defect: 3-way handshake not yet implemented. TX can fire before RX enters receive loop at high baud rates. Fix: RX-ready signal back to TX before data phase.

Tools

• pactl set-sink-input-volume — set volume by sink-input index
• pactl list sink-inputs — enumerate tabs, read current volume
• pavucontrol — visual verification of modulation
• ./tx -l — list all PA sink inputs with index, volume, channels
• sink-input index maps to tab; stable within a session

Use cases

• agent-to-agent signaling without touching the filesystem or network stack
• side-channel between sandboxed browser tab and host process
• low-bandwidth status heartbeat (alive/dead/mode) at ~1–10 baud
• covert channel for oracle↔host communication on TimeHexOn

Constraints

• sink-input index resets when tab navigates or crashes — handshake needed on reconnect
• PA polling latency sets the baud ceiling — benchmark with ./rx -s SINK -t SINK2 before sending
• stereo (channels=2) required for Battle Toads — open web/index.html, click 'start audio'
• userland only — survives without root
• Operation Voyeur: all terminal output is public — never pass secrets through these channels unencrypted. The web page does ECDH key exchange + AES-256-GCM before TX.

Web UI privacy — never display peer IPs

chat.html and zebra-audio.html must never print peer IP addresses or ports in the page UI or in any visible log. Our users do not run Wireshark — if it is not on the screen, peers cannot dox each other. Candidate types (host/srflx/relay) from pc.getStats() are abstract and fine to show (they tell you direct vs relayed); loc.address / loc.port / rem.address / rem.port are not. The WebRTC stack already obfuscates host candidates via mDNS by default — do not undo that work in the UI.

CSS layout — grid only, no flex

All page layout on every zebra page is CSS grid. No display: flex for layout. Reasons we settled on this:

• Grid lets us pin children to explicit columns (grid-column: 1/2/3) so a display:none on one child never causes siblings to slide into its slot. Flex auto-reorders, grid does not.
• One mental model for both axes. Flex needs rules per row + per item, grid expresses the same intent in one grid-template-* block.
• A global .hidden { display: none !important } utility lives in the page CSS — combined with explicit grid placement it produces a layout that survives any child being toggled in or out.

When refactoring or adding UI, use:

• display: grid + grid-template-columns for column layout
• grid-column: N on every child of a grid so its position is explicit
• grid-template-rows + grid-row for vertical placement when needed
• grid-template-areas for small named-region layouts
• gap for spacing (instead of margins)

Avoid:

• display: flex on any container that arranges multiple elements horizontally or vertically as part of the page layout
• Implicit positioning that relies on DOM order — always set grid-column (and grid-row if relevant) on every grid child
• flex-basis / flex-grow mathematics — 1fr is the equivalent and reads cleaner

If you need a one-off horizontal alignment of two short inline things (e.g. a label + a value), grid still works fine (grid-template-columns: auto 1fr). Don't reach for flex.

Web style guide — form-row patterns

.row is the single primitive for every horizontal form strip in every zebra page. Don't invent new wrappers. CSS auto-detects the row shape via :has() and picks the right grid template.

Supported row shapes (DOM order matters):

Shape	Template applied	Use when
<button> <button> ... (no input)	grid-auto-columns: max-content (default — pack)	"stop sharing" + "stop camera" + select-camera; vault buttons
<label> <input> or <label> <select>	auto 1fr (input cell stretches)	handle row, mic-input row
<label> <input> <button>	auto 1fr + extra cells packed	rare; same template as above + a trailing packed cell
<input> <button> (input first)	1fr (input fills, button packs after)	rendezvous code + enter; password + export; share URL + copy
anything + <span class="note">	the .note is auto-placed on its own row beneath via grid-column: 1 / -1	descriptive subtext after buttons

Rules:

• Never put inline style="flex:1" on a row child. Use .row and trust the template selector.
• Don't add a stretchy <div> to fake spacing. If you need a button group on the right, append the buttons as siblings — they'll pack right of the stretchy cell.
• A <span class="note"> inside .row always drops to its own line. If you want note text on the same line as a button, use a different class (e.g. inline <span>).
• Long checkbox labels get white-space: normal automatically, so a music-mode-style "raw mic, no echo/noise cancellation (for playing audio through it)" wraps cleanly inside its column.

If a new row shape doesn't fit the patterns above, add the case to this table and add the matching :has() selector — don't reach for inline styles or flex.

Web page integrity stamping

Each deployed page (web/chat.html, web/zebra-audio.html, web/how-it-works.html, web/host-your-own.html) carries a footer with the build date + its own MD5 + SHA-256. Run make stamp before deploying any page change — it sets today's date and recomputes the hashes (web/stamp.js).

• A file can't hold its own hash, so the hashes are computed with the two hash fields zeroed, then written back (same length). Self-consistent and idempotent: re-running make stamp gives identical hashes unless the content changed.
• The stamp is static HTML written at build time — no JavaScript computes or injects it in the browser. stamp.js is build tooling, never loaded by a page.
• Verify a served page: blank the md5 field to 32 zeros and the sha256 field to 64 zeros, then re-hash with sha256sum/md5sum — must match the footer.
• Deploy = push to BOTH repos. A page change is not live until it lands in both. Pushing only the source changes nothing served; pushing only the deploy repo orphans the source of truth. Both, every time:
  1. source — this repo (zebra-report): edit web/*.html → make stamp → commit → push to origin.
  2. served — www.unturf.com: copy the page(s) into ~/git/www.unturf.com/zebra-report/ (chat.html → index.html; zebra-audio.html, how-it-works.html, host-your-own.html keep their names) → commit → push to origin.

Picking up a new SDP/codec deploy — leave then enter, no full reload

When a deploy changes SDP munging (preferStereoOpus, codec fmtp params, RTCP feedback negotiation, or the SFU's codec registration), the page-level JS update is not enough on its own. Every existing RTCPeerConnection (sfuPubPC, sfuSubPC, sfuScreenPC, sfuCameraPC, every mesh peer) is locked to whatever was negotiated when it was created — its codec params, its rtcp-fb, its stereo flag, its NACK behaviour. The PC won't re-negotiate those on its own, and the new client code can't retroactively rewrite the old SDP.

So after the new build is live, the user does not need a full tab reload:

• leave then enter the space. That tears down every PC and rebuilds them, so the next offer/answer round trip is the new client talking to the new SFU with the new params. Fresh negotiation, all changes active.

Full reload is only required for changes to the page shell itself (DOM structure, button wiring, CSS, the entry/orientation flow before joining a space). For everything that lives inside an existing PC, prefer leave + enter.

Audio jitter buffering — userland AudioWorklet, not browser hints

The browser-native jitter-buffer controls cannot be trusted for music. Verified 2026-06-04 with side-by-side telemetry on a Firefox Android phone, same PeerConnection, three receivers, identical 4s target:

• RTCRtpReceiver.playoutDelayHint is spec'd as a hint — "the user agent MAY use this." Browsers do whatever they want.
• RTCRtpReceiver.jitterBufferTarget is spec'd as a hard target. Honored for voice-rate Opus and for video. Ignored for high-bitrate stereo Opus (256 kbps music) on Firefox Android. The native music-stream code path inside libwebrtc isn't wired to the new API there.

Result: a phone listener with the spec'd 4s target had a 0.21s buffer on the music stream. Any host-side stall (X11 window wiggle, GC pause, encoder spike) was instantly audible.

The reliable cushion is a userland AudioWorklet. See JitterBufferProcessor (inline Blob URL) in web/zebra-spaces.html. The worklet sits between MediaStreamAudioSourceNode and GainNode, queues incoming 128-sample blocks, holds emission until targetSamples are buffered, then emits with constant delay. The buffer cushions the music regardless of what the native receiver does.

Rules that took blood to find:

1. Sticky-started is non-negotiable. Once the buffer fills and started becomes true, do NOT set started=false on a single empty-queue tick. That tears down playback and forces a full re-buffer (~4s of silence) on every 2.67ms upstream micro-stall — sounds like constant chopping. Tolerate ~267ms of consecutive empty blocks (emptyStreak >= rearmThresholdBlocks=100) before re-arming; emit silence in the interim.

2. Role-aware buffer depth. Listener gets 4s (lean-back, latency doesn't matter, ride out wiggle-stalls). Speaker / cohost / host get 0.7s (SPEAKER_PLAYOUT_DELAY_SEC in web/zebra-spaces.html — bumped from 0.5s when we removed the mesh→worklet swap; the worklet cushion now absorbs the 200ms host-wiggle unaided on the SFU receive path). playoutDelayForRole(role) returns the active target.

3. Worklet retarget on role change, don't rebuild. Post {cmd:'retarget', targetSeconds} to the worklet's port — recomputes targetSamples/maxSamples and shrinks the queue if smaller. Audio path stays continuous; only the buffer depth adjusts. retargetAllReceivers(role) walks every live receiver and applies the new target.

4. UI gating on buffer-ready. Worklet posts {cmd:'started'} on first fill. Listener status text sits in "connecting — buffering 4s audio…" until the first started message lands, then flips to "connected as listener." Without this, users see "connected" but hear nothing for ~4s and assume the app is broken.

5. Bound the queue at 1.5× target to absorb clock drift without growing unbounded. Drop oldest on overflow.

6. Set hints AND target anyway at ev.receiver.playoutDelayHint = ... and ev.receiver.jitterBufferTarget = ... * 1000 — they're free, they work where the browser implements them (video, voice mic), and they layer cleanly with the userland worklet downstream.

7. Audio gets priority='high' at the sender. Video gets 'low'. Stops a screen-share keyframe burst (e.g. X11 wiggle dirty regions) from queuing audio packets behind it. setSenderBitrate / setSenderMaxBitrate already apply this.

HTTP DJ pull (/stream on the SFU) exists as a fallback for listeners who don't have AudioWorklet support — natural deep buffer on the <audio> preload side. Was deadlocking on bcastMu until 2026-06-04 (commit fixed bcastInitCapture.Write self-recursion). Worklet is the primary path; HTTP-pull is the safety net.

Chromium decoder anchor — required for remote audio tracks

Every remote MediaStreamTrack consumed by a MediaStreamAudioSourceNode must ALSO be attached to a hidden muted <audio> element in the same page. Without that anchor, chromium does NOT run its WebRTC audio decoder for the track, and the source node produces silence — even though packets arrive at full rate, audioCtx.state === 'running', and the worklet's started event fires (queue filled with zeros).

Firefox does NOT have this restriction. Defects of this shape present as chrome-only silence with every JS-side invariant green.

The anchor lives on the listenerAudioNodes entry as node.anchor (see attachAudioStreamViaWorklet). It is muted, hidden, and autoplays. setWorkletStream swaps anchor.srcObject alongside the source node. detachListenerStream tears the anchor down.

Diagnostic signal: pavucontrol Playback shows the chrome stream present, level meter pinned at 0 while RTP telemetry shows aud.recv pkt=N → N+50/sec bytes=growing level=0.000 jbuf=? and worklet started event has fired. → anchor is the load-bearing fix. Do NOT remove it during a refactor.

Full root-cause writeup: docs/tickets/0001-fedora-chrome-cannot-hear-speakers.md. Memory: feedback-chromium-decoder-anchor.

Audio receive path — SFU only

SFU is the only receive-audio path for every role, including speakers. Mesh PCs (peers map) carry our OUTBOUND mic only. Their inbound audio is ignored (pc.ontrack in connectToPeer is a breadcrumb log only).

This is a 2026-06-07 change. The previous mesh→worklet swap caused chromium decoders to silently stall at the source-swap moment. The 0.5s → 0.7s SPEAKER_PLAYOUT_DELAY_SEC bump compensates for the lost mesh latency benefit by giving the worklet enough cushion to absorb the 200ms host-wiggle on the SFU path.

If you reintroduce a mesh receive path, the right shape is verify-before-swap (poll mesh receiver stats for jitterBufferEmittedCount > 0 BEFORE disconnecting the SFU source).

Telemetry — signal-server CLIENT_LOG

Every logLine call in web/zebra-spaces.html ships to the zebra-spaces-signal server as a client-log WebSocket message. The server logs to /var/log/zebra-spaces-signal.log on proxy.uncloseai.com with the publisher's pubkey + handle attached.

Diagnostic SSH (read-only):

ssh -i ~/.ssh/digitalocean -p 22222 root@proxy.uncloseai.com \
  'tail -2000 /var/log/zebra-spaces-signal.log | grep "actor_handle=\"HANDLE\""'

Per-tick (~5s) telemetry line shape:

· role=X sub=X/X pub=X/X mesh=N sListen=N streamMode=N muted=X xcr=X ctx.sink=…
  aud.recv pkt=N lost=N bytes=N jitter=N level=N jbuf=Xs lp=Xs    (per SFU sub PC audio receiver)
  vid.recv pkt=N lost=N frames=N jbuf=Xs lp=Xs                    (per SFU sub PC video receiver)
  mesh.recv u=XXXX pkt=N … level=N jbuf=Xs                        (per mesh PC audio receiver)
  mic.send.aud / cam.send.vid / scr.send.vid / etc.               (outbound stats per publish PC)

One-shot session fingerprint on entry (after joined as X — uuid …):

session: ua=chrome/desktop ctx={sr=48000 baseLat=0.0107 sinkSupp=1 sink=…}
        devs={out=N in=N cam=N} picked={mic=… cam=… spk=…}

The signal-server endpoint backs cors-proxy.uncloseai.com. Per-service /version is exposed at /zebra-spaces-signal/version / /zebra-spaces-sfu/version / /zebra-signal/version / /version (each returns the upstream Go binary's commit + build_time).

Defect tracking — docs/tickets/

Anything that takes more than 15 minutes or needs cross-browser / cross-session repro lives as a numbered markdown file under docs/tickets/. Format spec + index in docs/tickets/README.md. New tickets get the next number. The resolution loop is:

1. Reproduce or grab signal-server telemetry.
2. Write a failing test in test/ that pins the contract.
3. Fix until test passes.
4. make stamp, push both repos.
5. Update ticket Status to fixed, link commit, note what to re-test in production.