Folds the last unmerged workshop work into main:
- ResiliencePanel — the failure-injection 'theater' UI (cloud outage → on-board
Qwen live demo) that visualizes the [agents.chaos] (custom.dead → llamacpp)
failover, plus Module2 integration + api/nodes support.
- build-deploy.sh — one-command aarch64-musl cross-build + adb deploy helper,
REFRESHED for 0.8.3: adds the web SPA prebuild step and the full feature set
(hardware, peripheral-rpi, embedded-web, gateway-voice-duplex) + the
embedded-web/web_dist_dir gotcha.
Config conflict resolved as a union: the branch's custom.dead + [agents.chaos]
demo blocks alongside this session's channels/voice/skills/risk-profile edits.
Verified: tsc clean, web 229 + api 58 tests green.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Commits the workshop inference pool (LiteLLM → boards: pooled coding plans,
per-attendee virtual keys, failover) — config + docs only, no secrets. Ignores
the vendored Uno-QClaw reference repo and the generated qr-sheet.html.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Vendors the fork's 11 granular UNO Q skills (bridge, flashing, led-matrix,
uno-q-hardware, sketch-patterns, modulino, linux-led, audio, vision, wireless,
arduino-app-lab) next to the comprehensive arduino-uno-q skill, and installs the
whole set into every agent's workspace on each board.
Why both: the comprehensive skill is the rich cloud reference (read_skill →
references); the granular skills are keyword-triggered and match the fork's eager
skill-inliner rules, so the on-board Qwen auto-inlines them (no read_skill
round-trip). flashing + led-matrix carry the exact uno_q_flash + frame-API /
ArduinoGraphics-not-installed detail that makes flashing reliable.
- push-skill.sh generalized: a single skill dir (has SKILL.md) OR a parent dir
installs every skill under it; provision-fleet now ships all of skills/.
- Verified on board 65301572: cloud/Sonnet-5 lists all 12 skills.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Vendors the comprehensive UNO Q skill (SKILL.md + 7 references/*.md) and installs
it into EVERY agent's workspace on each board, so agents know this board's
specifics (dual-brain arch, Bridge/RPC, pin tables, LED matrix + the
ArduinoGraphics-not-installed gotcha) instead of guessing generic Arduino.
Why per-agent workspace: ZeroClaw's read_skill returns only SKILL.md; the agent
reads references/*.md via the workspace-sandboxed file_read tool, so references
are only reachable under ~/.zeroclaw/agents/<alias>/workspace/skills/. A
shared/skills bundle surfaces the skill but its references get sandbox-blocked.
- push-skill.sh installs a SKILL.md+references skill into every agent workspace
(discovers aliases from the board); provision-fleet runs it per board.
- config.template risk profile now allows + auto-approves read_skill + file_read
so agents load skills without a human approver (webhook path is non-interactive).
- Flattened the folded 'description: >-' to single-line (ZeroClaw's frontmatter
parser is a flat scanner, not full YAML).
Verified on board 65301572 with cloud/Sonnet-5: discovered arduino-uno-q →
read_skill(SKILL.md) → file_read references/04-bridge-rpc.md → correct
board-specific answer citing the file.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Boards now boot LAN-open (host 0.0.0.0, allow_public_bind, require_pairing=false)
so a team reaches its node's embedded ZeroClaw dashboard + web chat directly by
IP with no token — the 'Open your node' path. Two more modalities ride the same
default (cloud-first) agent:
- Telegram: config seeds [channels.telegram.default] disabled + pre-bound to the
default agent; a team enables it from the dashboard by pasting a @BotFather
token. Dashboard writes only set pending_reload, and /admin/reload is
loopback-only, so a new zeroclaw-reload-watcher.sh (loopback) applies dashboard
config edits within seconds — no shell. provision-fleet pushes + launches it.
- Lockdown: zeroclaw-lockdown.sh flips require_pairing=true, reloads, and mints a
pair code (open -> locked harden step); documented as a board/adb action since
minting + reload are loopback-only.
- Voice: seeds a commented [channels.voice_duplex.default] + documents the
aarch64 build (embedded-web + gateway-voice-duplex); build/hardware work is
separate.
Onboarding scripts (apess-selfregister.sh, provision-uno-q.sh) now tolerate
open-boot: when the gateway mints no pair code, they announce with a placeholder
token (the open board ignores auth) instead of hard-failing.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
The board self-registers its gateway URL (http://<lan-ip>:8080) but the API
withheld it from the browser — teams saw only an online boolean. The bearer
token is the only real secret; the URL is safe to expose. Return it in the
/claim response and the node status poll, thread it into device.nodeUrl, and
render an 'Open your node →' deep-link in EnvSetup's connected-device card so a
team can reach its own node's embedded web chat directly on the workshop LAN.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Fixes the reachability gap: a cloud-hosted API can't reach boards behind the
workshop NAT, so live board features (claim status, Build & flash, module
feeds) fail. This stack runs web + API on one box on the workshop WiFi, where
the API CAN reach each board's LAN IP.
- deploy/lan/: docker-compose (web + internal API), nginx.lan.conf (SPA +
same-origin /api reverse-proxy with WS/SSE support), .env.example, README
(launch, point the fleet's APESS_URL at the box, run the room).
- Web is IP-agnostic: nginx serves the SPA and proxies /api on the same origin,
so no box IP is baked into the build.
- api.ts: API_BASE now supports a relative same-origin base ("/api"); wsUrl()
derives ws scheme+host from the page for it (absolute prod base unchanged).
- Dockerfile.web: VITE_API_BASE build arg (empty=prod default, "/api"=LAN).
Verified E2E with a real `docker compose up`: SPA 200, /api/healthz ok,
self-register→unclaimed round-trip through the proxy, /api/ws → 101 Switching
Protocols, and 0 hosted-URL refs in the /api build. Web 220 + api 56 green.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Fixes a latent bug and hardens claim recovery. Refactors the unclaimed pool
into a BoardRegistry that tracks claimedBy, so a board's binding survives its
own reboot and a team can get back onto its board after an error.
- Auto-heal: a claimed board that reboots re-announces with a fresh IP/token;
self-register now REFRESHES its node binding instead of dumping it back into
the unclaimed pool (previously the team's board went stale/offline + the kit
wrongly reappeared as unclaimed).
- Resume: re-claiming an already-claimed kit with the right code returns the
board's CANONICAL teamId + team snapshot (not a fresh identity). The client
adopts it via a new resumeTeam() action, restoring name/members/phases/stats
so a lost-browser re-claim doesn't clobber synced progress.
- Release: POST /claim/release (admin) frees a kit back to the pool + unbinds
its node, for mis-claims / reassignment. Wired to a small control in /admin.
API 56 tests green; web 220 green; tsc + eslint clean.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Folds the boot animation into the fleet pass — after onboarding each
board (env + self-register + timer/cron), provision-fleet now flashes the
default sketch (sketches/matrix_rain) via flash-sketch.sh. Best-effort: a
flash hiccup logs a warning but doesn't fail the board's onboarding.
- FLASH_DEFAULT=1 (default; 0 skips) and FLASH_SKETCH=<dir> knobs.
- Upfront guards for flash-sketch.sh + the sketch dir.
- provision() refactored to a single success tail (persistence → flash).
Verified on hardware: one pass reports both "ok — onboarding (cron)" and
"ok — boot animation (matrix_rain)".
Co-Authored-By: Claude Opus 4.8 <[email protected]>
- flash-sketch.sh: compile + flash a sketch dir onto a board's MCU over adb
(push → arduino-cli compile with TMPDIR=/tmp → arduino-flash @ 0x80F0000).
Defaults to sketches/matrix_rain; includes a fleet loop over adb devices.
DRYs up the recipe and makes "set the board default" one command.
- Designate matrix_rain as the boot animation boards ship with (the flashed
MCU sketch persists across power cycles). Documented in the sketches README
+ parent Files list.
Flashed matrix_rain to the board via the helper (821 bytes, verified E2E).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Rounds out the sampler with the remaining effects:
- bloom — a filled diamond grows from the centre to full, then collapses.
- breathe — a dithered shimmer that swells and fades (density ramp via a
fixed per-pixel threshold, since the matrix can't truly fade).
- checker — a checkerboard that inverts on each beat.
Full cycle is now rain -> knight-rider -> comet -> ripple -> bloom ->
breathe -> sparkle -> checker -> wipe. Compiled + flashed E2E (2057 bytes).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
A pixel that bounces off the walls trailing its last 5 cells (a diagonal
streak that bends on each bounce). Wired into the cycle between the
knight-rider sweep and ripple. Compiled + flashed E2E (1637 bytes).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
There was only a scroll-text template; add frame-based animations for the
Uno Q's built-in 13x8 monochrome-blue matrix. Both compiled (arduino:zephyr
0.51.0) and flashed E2E on hardware (OpenOCD @ 0x80F0000, per boards.txt).
- matrix_rain/ — digital rain: staggered per-column drops + trails.
- matrix_effects/ — sampler cycling rain / knight-rider / ripple / sparkle
/ wipe.
- README: the grid->uint32[4] packing pattern (row-major, MSB-first), how to
add an effect, and the compile/flash recipe (TMPDIR=/tmp trap + the correct
0x80F0000 address vs QClaw's stale 0x8100000).
Note: the matrix is physically blue + on/off only — no colour/brightness in
software.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Two host-side helpers that close the operational gap between minting kit
codes and boards-in-hand.
- provision-fleet.sh: provision a whole fleet from fleet.csv (kit,serial).
Per board it pushes the per-kit apess-node.env + apess-selfregister.sh
over adb and enables the boot/refresh systemd timer (MODE=systemd, root)
or an equivalent cron (@reboot + every 5 min; the no-root default).
fleet.csv.example is the assignment template.
- gen-qr-sheet.sh: render the sticker CSV into a self-contained, printable
QR sheet (A4, ~9/page). QRs are baked in as inline SVG via qrencode, so
the HTML has zero external refs — prints offline. Each sticker: kit id,
QR of the claim URL (/workshop?kit=..&code=..), and the 6-digit code.
- .gitignore: never commit kit-codes/ (env files hold FLEET_SECRET +
claim codes) or fleet.csv.
- README: documents both, plus the one-command fleet path.
Verified: provision-fleet loop logic (header/comment/missing skips) and a
4-kit end-to-end sheet build (4 inline SVGs, 0 external refs).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
In live mode the sense loop runs on the board (ZeroClaw on the Uno Q),
so the browser observes it rather than reading frames over Web Serial.
- useNodeFeed(teamId, enabled): subscribes to the node's SSE activity
feed (openTeamActivity) and seeds liveness with a one-shot getNodeStatus
(the per-team stream only emits status on change). Inert in sim mode.
- LiveBoardFeed: shows the board's real perception->reason->act activity
+ a live tally (agent runs / flashes / errors) + online indicator.
- Module 1/2 are now mode-aware: sim keeps the synthetic IMU feed +
browser classification (the teaching sandbox); live shows LiveBoardFeed
from the actual board. Proceed gates on board online (M1) / real board
activity (M2) in live, unchanged in sim.
Note: this consumes the board's real activity stream (the signal the
Uno Q emits today). Streaming raw IMU frames for browser-side
classification in live mode would need a board-side sensor emitter
(ZeroClaw firmware) + an API frame relay — a separate piece.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Surfaces the self-register pool in the instructor console so you can tell
at a glance which boards are up but not yet claimed.
- api: GET /nodes/unclaimed (admin-only; kit ids, never secrets) +
broadcast unclaimed:update on self-register (added) and claim (removed).
The WS connect snapshot now carries the current unclaimed kit ids
(attachWs takes the pool), so a freshly opened console is populated
without waiting for a change.
- web: useCollective tracks `unclaimed` (snapshot + unclaimed:update, with
a REST getUnclaimed seed for the poll fallback); Admin shows an
"Unclaimed" stat + a live "Unclaimed boards" panel of kit chips.
Verified live: empty → self-register adds the kit → claim removes it;
judge code is 401 on the endpoint.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
verify-onboarding.sh runs the self-register + claim chain against a live
APESS API and asserts each HTTP status (correct/wrong fleet secret,
wrong code, unknown kit, successful claim, status, cleanup). Proven
end-to-end against a local API (7/7). bash 3.2-safe (no apostrophes in
${:?} messages, temp-file body capture).
API=… FLEET_SECRET=… [ADMIN_CODE=…] deploy/verify-onboarding.sh
Co-Authored-By: Claude Opus 4.8 <[email protected]>
The API gates board self-registration on FLEET_SECRET; wire it through
docker-compose (host .env) alongside ADMIN_CODE/JUDGE_CODE and document
it in the deploy README.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Board-side half of "preloaded + self-register + claim", plus the QR flow.
- apess-selfregister.sh (on-board): pairs locally for a token, discovers
the LAN IP, and announces {kitId, url, token, claimCode} to APESS
/nodes/self-register (x-fleet-secret gated). Retries until APESS is up;
idempotent, safe on boot and on a timer.
- systemd/apess-selfregister.{service,timer}: self-register After the
daemon, re-announce every 5 min so a DHCP lease change can't strand a
board.
- apess-node.env.example: per-board identity (KIT_ID, CLAIM_CODE,
FLEET_SECRET, APESS_URL).
- gen-kit-codes.sh (host): mint per-kit 6-digit codes, write the
per-board env files, and emit the QR sticker CSV
(…/workshop?kit=KIT-NN&code=NNNNNN).
- web: BoardClaim accepts initialCode; TeamRegistration pre-fills it from
?code= so scanning the kit QR fills kit + code — one tap to claim.
- deploy/uno-q/README: documents the whole self-serve onboarding path.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Attendee-facing half of the "preloaded + self-register + claim" flow.
- BoardClaim wizard: three physical bring-up steps (power → boot →
enter code) + a claim-code field that calls POST /claim. On success
the board shows as claimed; ClaimError surfaces the server's message
(wrong code / not powered on / rate-limited).
- TeamRegistration: swaps the Web-Serial "connect device · 115200 baud"
step for the wizard, with a "use the simulator instead" escape hatch
(sim needs no board). serial.ts stays — Module1/2 still use it for the
simulated sense path.
- EnvSetup: live self-test now polls GET /nodes/:teamId/status (board
liveness) instead of reading Web-Serial frames; sim path unchanged.
- api client: claimBoard() + ClaimError + getNodeStatus().
- api: GET /nodes/:teamId/status (public per-team liveness).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Adds the server side of the "preloaded + self-register + claim" board
onboarding so attendees bring a board online with no operator and no
admin code.
- claim.ts: an unclaimed pool keyed by kitId, holding {url, token,
claimCode}; single-use claim with a constant-time code compare and a
per-kit sliding-window rate limit (MAX_FAILS/WINDOW_MS) to blunt code
guessing.
- POST /nodes/self-register — a booting board announces itself; gated
by a shared FLEET_SECRET (baked into the image), not the admin code.
- POST /claim {kit, teamId, code} — public + rate-limited; validates
the claim code, moves the bearer token straight from the pool into
the node bridge (never touches the browser), binds the board to the
team without clobbering an existing name/members, and emits the
node:status + team:update the live feeds already consume.
- index.ts: wire the pool + FLEET_SECRET env.
22 new tests (claim unit + endpoint integration).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
The landing page only routed attendees; /judge and /admin were
unlinked. Add a subtle "Staff sign-in ▾" disclosure in the header
linking to the judge and instructor consoles (both already gated by
AccessGate). Attendee hero is unchanged.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Front-end still told the old UNO R4 WiFi story (Cortex-M4 / Renesas
RA4M1 / ~6 MB binary / UART→ESP32-S3 / browser-direct Web Serial).
The actual workshop node is the dual-brain Uno Q: ZeroClaw runs on
the quad-A53 Linux side, hosts a local Qwen model, and flashes the
on-board STM32U585 MCU it drives.
- Landing: hero, hardware spec tile, kit pickup, Stack cards, prereqs
- Lecture: Movement 3 (ZeroClaw) rewritten to the Uno Q architecture
- serial.ts + callers: device identity strings uno-r4-wifi -> uno-q
(Web Serial transport mechanism unchanged)
- README stack line
- tests updated to match
Co-Authored-By: Claude Opus 4.8 <[email protected]>
`strings "$BIN" | grep -qm1 …` under `set -o pipefail` fails on a MATCH:
grep -q closes the pipe on first hit, `strings` dies with SIGPIPE, and
pipefail propagates the non-zero pipeline status — so the verify-gate
reported "peripheral tools MISSING" on a binary that actually had them.
Grep the binary directly with `grep -qa` (no pipe, no SIGPIPE).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Adds deploy/uno-q/build-deploy.sh: cross-compiles ZeroClaw for the Uno Q
(aarch64) on macOS via cargo-zigbuild and deploys it to the board over
adb as a proper drop-in for /home/arduino/zeroclaw.
Bakes in the two things that bit us:
- `--features hardware` is MANDATORY, else the build silently drops the
10 Uno Q peripheral tools (GPIO bridge, flash, sysfs_led, camera,
network, i2cdetect). The script fails fast if the artifact lacks them.
- each adb step runs with `</dev/null` so the shell returns (a trailing
`setsid … &` otherwise hangs the adb call).
Flow: build (hardware, musl static) → verify tools present → push +
sha-check → stop supervisor + kill daemon → swap (keeps .prev.bak) →
relaunch supervisor → poll :8080/health. Also --build-only and
--rollback. Verified: the hardware cross-build produces a static aarch64
binary with the peripheral+flash tools and the streaming-fallback fix.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Prototype #1 of the APESS innovation set: make the Uno Q's unique story —
a real LLM running on the board — visible and demonstrable. A team can
inject a cloud outage and watch their agent keep reasoning on the on-board
Qwen, which is exactly ADD Layer 4 (failure modes) / Layer 5 (edge vs cloud)
made concrete instead of merely documented.
- New `fallback` NodeActivityKind (api + client, kept in sync). `mapNodeEvent`
now recognizes ZeroClaw's failover log lines ("ModelProvider call failed",
"Exhausted retries, trying next model") and surfaces them as a first-class
resilience signal — NOT swallowed by the generic error branch. Rendered in
a distinct rose in the board-activity feeds.
- ResiliencePanel (Module 2): a "Simulate cloud outage" button that routes a
prompt through the board's new `chaos` agent; streams the live failover and
shows a "survived" banner when a fallback is followed by a response. Sim mode
plays a deterministic failover so it demos with zero hardware.
- Board config: a `chaos` agent backed by a deliberately-dead cloud endpoint
(:9099) with `fallback = ["llamacpp.local"]`, so the outage is deterministic
and workshop-safe (no tunnel-hacking, no real cloud to kill).
Tests: api 34, front-end 191 (+ResiliencePanel), typecheck clean, build passes.
Live-on-board validation pending (board USB link down at commit time).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
A board power-cycle exposed two bugs that left the node dead after boot:
- recover-uno-q.sh step 3 ran `pgrep -f zeroclaw-supervisor`, which matches
the pgrep's OWN shell (its args contain the supervisor path) — so it always
concluded "already running" and never launched the supervisor. Bracket the
pattern (`[z]eroclaw-supervisor.sh`) so only the real process matches.
- The supervisor's single-instance lock only checked that the locked pid was
alive. After a reboot the stale pid can be recycled by an unrelated process,
falsely blocking startup. Now require the live pid's /proc/<pid>/cmdline to
actually be a supervisor before deferring — otherwise treat the lock as stale.
- Also export a full PATH in the supervisor for cron's minimal @reboot env.
Validated on hardware: discriminator matches a real supervisor and rejects
init's pid; fixed recover detects the running supervisor without spawning a
duplicate; board comes back healthy (gateway + llama up).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
The node bridge opened a board's /api/events stream once; when the board
dropped or its daemon restarted, the async reader just ended and never
reconnected. Registration still read `online` (set at register time), so a
board looked fine while its event stream was dead — participant prompts
appeared to vanish. Only a manual DELETE+POST re-register revived it.
Reproduced live: kill the on-board daemon → the feed went permanently blind.
- subscribeNodeEvents now reconnects with exponential backoff (1s→15s,
reset on a healthy connection) until aborted, and reports each connect/drop
via an onStatus callback.
- The bridge maps onStatus → a deduped node:status, so `online` tracks reality
and the collective + participant feeds get offline/online transitions. A node
that was offline at register is promoted once its stream connects.
Proven: unit tests for drop→reconnect, dedup, and offline-at-register
promotion; and live against the board — killing the daemon now yields
node:status false→true on the participant feed with no re-register.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
A sudden USB/adb drop breaks the Uno Q node in ways that don't self-heal:
adb tunnels vanish, held-shell services die, llama wedges (alive but not
serving), and flashes silently stop landing. systemd is the clean fix with
root — but the dev board's account is expired (no sudo) and has no user
session bus, so neither system nor user units run. These are the no-root
equivalents, both validated on hardware:
- zeroclaw-supervisor.sh — on-board watchdog. Polls the /health ENDPOINTS
(a wedged process passes pgrep but fails here) and restarts llama / the
daemon on death or wedge. Launches children with `setsid … exec` so they
survive the launching shell — the property `nohup … &` in adb shell lacks.
Startup grace avoids reaping llama mid-cold-load; single-instance lock;
no per-restart shell leak. Proven: kill -9 the daemon → auto-restarted.
Boot-persisted via `@reboot` crontab (no root).
- recover-uno-q.sh — host-side. After the board is back, re-does adb + both
tunnels (out :8080, back :8090 shim), ensures the supervisor is running,
and health-checks every hop by endpoint. Proven end-to-end after a
simulated tunnel drop.
README: new Resilience section documenting the no-root reality + both tools.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Stage E deeper — derive real signal from the board event stream:
- Collective reducer tallies per-team {calls, flashes, errors} from
node:activity (thinking→calls, flash→flashes, error→errors); exposed
as `counts` alongside the existing activity feed.
- Admin gains a room-wide "Flashes" pulse stat.
- Judge review card shows a live "Board evidence" panel — streams the
reviewed team's own board activity via its SSE feed, so scoring can
reference real on-device work, not just the submitted code.
Tests: front-end 182, typecheck clean, prod build passes.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Codify the verified board setup into a repeatable kit under deploy/uno-q/:
- config.template.toml — the tested node config: cloud / cloud+fallback /
on-board-Qwen providers, three agents (default / cloud / local) on the
hardware risk profile, gateway, peripherals. Secrets stripped; cloud
endpoint substituted at provision time.
- provision-uno-q.sh — one-shot adb-driven provisioner (no root): install
config, start llama-server + `zeroclaw daemon`, pair for a bearer token,
and POST /nodes to APESS.
- systemd/{zeroclaw-llama,zeroclaw-daemon}.service — production units
(daemon, not `gateway start`, so peripheral tools register).
- README.md — dev (adb) and production (systemd + LAN bind) runbooks.
The individual steps are hardware-verified: all three agent aliases resolve
and route correctly on the board (local→Qwen, cloud→cloud, default→cloud
with Qwen fallback). Full script orchestration + live phone-home land once
the api (with /nodes) is redeployed.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Close the tune→deploy loop without live config mutation. The gateway
already supports per-request `?agent=` selection, so map the harness to a
pre-provisioned agent alias and route the prompt to it:
- local primary → `local` (on-board Qwen only)
- cloud primary + fallback → `default` (cloud + Qwen fallback)
- cloud primary, no fallback→ `cloud` (cloud only)
- lib/harness: harnessToAgent(h).
- api: sendPrompt(node, msg, agent?) → `?agent=`; bridge.prompt +
POST /nodes/:teamId/prompt accept an optional `agent`.
- lib/api.sendPrompt(teamId, msg, agent?); BuildFlash derives the alias
from the live harness.
Boards must be provisioned with the `default`/`cloud`/`local` aliases
(our board currently has `default`); that lands with the provisioning kit.
Tests: front-end 180, api 29, typecheck clean, prod build passes.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Extend the collective feed to consume node:status / node:activity: the
reducer now tracks per-team board online state and a bounded,
most-recent-first activity feed (preserved across snapshots). Admin gains
a "Boards live" stat and a "Board activity" panel (new BoardActivity
component) showing real generate/compile/flash events across teams.
Tests: front-end 177, typecheck clean, prod build passes.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Turn the workshop shell into a real on-device agent platform: APESS now
proxies each team's Arduino Uno Q (running ZeroClaw) and drives
generate → compile → flash from the UI, with a simulation fallback.
api — node backbone
- nodes.ts: team→node registry, a pure ZeroClaw /api/events → WsEvent
mapper, per-node live SSE subscription fanned out to the collective hub
AND per-team participant listeners, and a prompt proxy. Bearer tokens
stay server-side; list()/broadcasts never expose them.
- routes: POST/GET/DELETE /nodes (register is admin-only), public
POST /nodes/:teamId/prompt, and a participant-scoped SSE
GET /nodes/:teamId/events.
- WsEvent gains node:status / node:activity.
front-end
- session store: mode 'live' | 'sim' (default sim); a 'local' provider
and a harness.fallbackLocal toggle ("cloud first, on-board Qwen if it
fails") reflected in the harness.toml preview.
- EnvSetup: Simulation / Live board toggle — sim runs a virtual board
(self-test + Proceed with no hardware), live requires a registered node.
- BuildFlash panel (in Module 2): prompt the board, watch activity stream
live (SSE) or a simulated generate→flash sequence.
- lib/api: sendPrompt + openTeamActivity (EventSource).
housekeeping
- better-sqlite3 → 12.11 (Node 26 support; the 11.x native build fails on
Node 26's V8).
- vitest excludes the vendored Uno-QClaw/ tree.
Tests: front-end 172, api 29, typecheck clean, prod build passes.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
api.apess.redclaw.dev is a multi-level subdomain that Cloudflare Universal
SSL and the *.redclaw.dev origin cert don't cover (edge TLS handshake fails).
Switch the API host to apess-api.redclaw.dev, which the existing edge + origin
certs cover with no paid Cloudflare features. Updates the client API base
default, the Traefik router host, and deploy docs.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- api/Dockerfile: node:22-alpine, builds better-sqlite3 from source for musl
(prebuilds are glibc), runs tsx; healthcheck on /healthz
- .dockerignore: stops host node_modules (wrong-platform native binaries)
from shadowing the in-container build — the root cause of an ERR_DLOPEN
'Exec format error' found while validating the image
- docker-compose.yml: apess-api service on clawbooks-net + apess-data volume,
ADMIN_CODE/JUDGE_CODE/CORS_ORIGIN env
- traefik/apess-api.yml: file-provider router for api.apess.redclaw.dev
(reuses the *.redclaw.dev cert; WS proxied automatically)
- deploy/README: API prerequisites (.env codes, DNS, router), deploy/verify
(REST + WS smoke tests), rollback notes; .env gitignored
Validated by building + running the image: /healthz=ok, PUT/GET /teams with
auth (401 without code), WS snapshot on connect, WS 4401 on bad code.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Final screen — replaces the last WorkshopStub; App.tsx now has zero stubs:
- SubmissionList: live review queue with scored markers + selection
- AddReview: read-only render of a submitted 5-layer ADD
- ScoreForm: 0-10 rubric per layer, auto-summed total, notes
- Leaderboard: ranked teams by average judge total
- Judge page (behind name+code AccessGate): queue + review/score + leaderboard,
refreshes on scoring and on any collective event
21 new tests; suite 140/140 green, typecheck + lint clean, build OK.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- AccessGate: shared code (+optional name) gate for /admin and /judge,
sessionStorage-backed
- TeamCard: pure 15-grid tile — phase dots, stats line, submitted/judged
badges, stale dimming
- useCollective: REST-seeded + WS-live reducer of all teams/submissions,
degrades to polling when the socket is silent
- useNow: ticking clock hook (effect-driven) for stale dimming
- Admin page: aggregate strip + 15-card grid behind the access gate
19 new tests; suite 126/126 green, typecheck + lint clean, build OK.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- src/lib/api.ts: typed client for the collective — pushTeam/pushSubmission
(public), getTeams/getSubmissions/getSubmission/postScore/getLeaderboard
(code-gated), and openCollective WS with auto-reconnect
- src/lib/useCollectiveSync.ts: offline-first sync mounted once in App —
projects the store to a TeamSnapshot, pushes on phase change + submission,
throttles stat churn, and routes failures to a sessionStorage outbox that
retries on interval + window 'online'. Never blocks the participant flow.
11 new tests (incl. backend-down path); suite 112/112 green, typecheck + lint clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- session store gains a persisted teamId (crypto.randomUUID, preserved
across reset) used as the team's stable identity for the collective
- src/types.ts: TeamSnapshot/SubmissionDTO/ScoreDTO/LeaderboardRow/WsEvent,
the contract shared with the api backend
2 new tests; suite 88/88 green.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
All four workshop phases are now real screens, replacing WorkshopStub:
- EnvSetup (/workshop/setup): device check + serial self-test (no stats
pollution) + provider/model selection; gated Proceed
- Module1 (/workshop/module1): live IMU feed via useSerial, actor map,
ADD Layer 1 capture; gated on observed frames + L1 goal
- Module2 (/workshop/module2): harness tuner + live TOML preview, test
triggers that classify against the tuned threshold, ADD L2/L3
- AddBuilder (/workshop/add): ADD L4/L5, assembled AddDocument, print-to-PDF
export, deterministic submission code; completes the run
- New components: ActorMap, HarnessTuner, TriggerButtons, AddDocument
23 new tests; suite 86/86 green, typecheck + lint clean, build OK.
Only /admin and /judge remain stubbed (need the backend).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- AddLayerForm: keystone ADD capture — string layers (L2-L5) as textarea,
object layers (L1) as per-field inputs; writes straight to the store
- StatsTally: live classified-frame counts
- LiveFeed: presentational IMU readout (props-driven)
- HarnessTomlPreview: live harness.toml render
- HarnessProviderSelect: provider toggle group + model field
- ui/textarea primitive
14 new tests; suite 63/63 green, typecheck + lint clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
osobh