tines/docs/superpowers/specs/2026-10-24-tines-fleet-console-design.md

tines fleet console + simulated fleet — design

Date: 2026-10-24 Status: approved by Kyle (2026-10-24) — decision C: add NodeEvent::Contact/NodeEvent::Lost to core (see "The how")

Intent

A desktop GUI (new tines-gui crate) that operates tines nodes in two containerized modes:

1. Bluetooth: a container with the host Bluetooth adapter passed through runs the full robot stack; its node talks to real tines robots over BLE.
2. Simulated fleet: containers on the host run the full stack with a new IPC-bus transport (new tines-bus crate); they exchange tines frames with each other over a host bus.

The GUI is a console: a launcher screen plus one window per container. Each window exposes the whole node control surface — observe (including addressed), belief, store listing, events (contacts, drops, confirmed deliveries), status — so tines can be exercised without hand-rolled JSON.

Why

• Testing tines today means hand-crafting length-prefixed JSON to a Unix socket; contacts and custody can only be watched in stderr.
• The two-device BLE check (tines-bt/README.md) has never been recorded; a BT container plus a console makes it a routine manual test.
• The only exchange transports are BLE (real radio) and tines-sim's in-process memory transport; nothing lets separate processes exchange frames. A simulated fleet on one machine needs a host IPC transport.
• No runtime container image exists (Dockerfile.ros2 is a CI build-check).
• Kyle wants to test tines functionality and interact with tines-enabled robots (hexapod on a Jetson running ROS2, Pi-class robots).

Goals

• G1. tines-gui: an egui/eframe Wayland app following this desktop's conventions (the wayland-gui skill): a launcher, plus one GUI process per container.
• G2. BT mode: a containerized full stack with host Bluetooth passthrough; the container's node is a real radio peer for robots in range.
• G3. Sim mode: a new tines-bus host transport crate over a host IPC bus; containers plug in and exchange frames; fleet size is operator-chosen.
• G4. The tines service config gains a transport choice (bt default, bus); existing config files keep working.
• G5. Widened service IPC: addressed observe (to + lifetime_ms via Node::observe_to), contact/lost events, dropped-frame events, and a store listing; the existing four operations are unchanged.
• G6. GUI windows expose every node operation; the docker lifecycle (create, start, stop, remove, logs) is managed from the GUI.
• G7. A runtime container image in the repo (new Dockerfile); both modes run from the same image with different runtime flags.

Non-goals

• tines-core changes limited to one additive pair (decision C, approved 2026-10-24): NodeEvent::Contact/NodeEvent::Lost variants, so the console's event feed can show live contacts. Nothing else in core changes: it stays no_std, and the 1.0 branch is unaffected (the enum is non-exhaustive). The bus is a host crate implementing the existing Transport trait; the IPC widening is in the tines service crate.
• No tines-sim changes: the simulator remains the protocol test harness; the simulated fleet runs real services over the bus transport.
• No ROS2 integration this round: containers run the service (Pi-class load). tines-ros2 is untouched; a ROS2-backed container is future work.
• Not a fleet deployment tool: the console is for development, testing and interacting; systemd units and production deployment stay out of scope.
• No node in the GUI process: the Node is not Send and the GUI never hosts one; it only speaks IPC to containerized services.

Anti-goals

• No weakening of the trust boundary: the widened IPC keeps the existing posture — malformed input gets an Error response, never a panic; frame caps stay; hex-on-the-wire stays.
• No silent config breakage: transport defaults to bt; existing configs parse unchanged; unknown keys are still rejected.
• No radio in the GUI process; no BLE access outside the BT container.
• No X11: eframe features glow/default_fonts/wayland only.
• No docker SDK dependency: docker is driven as a subprocess (CLI).

Constraints

• AGENTS.md applies unchanged: spec-first, TDD with sh scripts/ci.sh before commit, conventional commits. New crates go in the workspace and the AGENTS.md crate layout.
• The Node is not Send; the service's inline poll architecture is unchanged. tines-bus is a Transport implementation and must not require Send of the node (same as BtTransport).
• The bus carries the core's wire frames (MAX_FRAME = 1500 and friends are unchanged).
• Docker is available on this desktop; the GUI shells out to it.
• The console follows wayland-gui conventions: theme watch on ~/.local/state/omarchy/current, vsync = false, opaque window painted with the theme background.

The how (decided with Kyle)

Core change (decision C, approved 2026-10-24)

Add NodeEvent::Contact / NodeEvent::Lost variants to core, emitted from the exchange's on_event when the transport reports a contact starting or ending. The enum is non-exhaustive and the variants ride the existing drop-oldest event queue, so this is additive and changes no wire format. This is the only core change in this work.

Modes

• Launcher: two choices — Bluetooth (real robots) and Simulated fleet. From it: create containers (name them, choose or generate node ids), see the running fleet, open any node's window.

• One GUI process per container (Kyle: "one GUI instance per container"): the launcher spawns a child process of the same binary in node-window mode, so a hung container can't freeze the fleet view.

• BT mode: docker run privileged, host network, D-Bus access (bluer/BlueZ needs the system bus and the hci device). Service config: node id, peer (the service still takes one — F3 remainder; the GUI exposes exactly what the service supports), log path on a named volume, socket path on a mounted directory. The GUI connects to the socket on the host filesystem.

• Sim mode: the launcher starts a bus daemon on the host, then N containers, each running the service with the bus transport and the socket directory mounted. GUI windows drive each node.

• Bus access control (wntrmute's call): the bus daemon's socket lives in a per-fleet directory under the operator's XDG state directory, created 0700. Same-user local processes are already inside the trust boundary (THREAT_MODEL); the bus adds no new posture.

• Status strip transport (wntrmute's call): the launcher knows the transport because it wrote the container's config; it passes it to the window process. Status on the wire is unchanged.

• Addressed panel in BT mode (wntrmute's call): the panel stays in every window — observe_to is a valid node operation whatever the transport. BT windows show a hint that the transport currently exchanges with exactly one configured peer, so an addressed observation to anyone else will sit until its lifetime expires.

The bus transport (tines-bus, new crate)

• Implements Transport with Addr = NodeId, exactly like tines-bt: frames are the core wire frames; a frame's declared sender is checked against the bound peer (same address-spoofing rule).
• Topology (wntrmute's call; Kyle can override): hub-and-spoke. A small bus daemon (a bin in the crate) binds a Unix socket in a per-fleet directory on the host; each node connects once. The bus fans every frame out to all connected nodes — a shared medium, like radio — and reports joins/leaves so the transport can emit Contact/Lost.
• Peers: the bus transport enforces core's MAX_PEERS (8), as tines-bt does; an empty allowlist means any bus peer (the bus is a test medium, so it drops bt's single-peer F3 limit).
• Framing: length-prefixed core frames over the socket; no new wire format.
• Contact model: any frame from a bus peer is an implicit contact (core already treats unknown addresses that way); daemon disconnect → Lost for every peer.

Service changes (tines crate)

• Config: new optional transport key, "bt" (default) or "bus"; with bus, a bus_socket path key. peer stays required for bt; for bus it is an optional allowlist (empty = any peer).
• IPC widening (backward-compatible: new tagged variants; the existing four operations are untouched):
  • Observe gains optional to (hex NodeId) and lifetime_ms (present together or not at all) → Node::observe_to; without them, the existing observe path.
  • Events also returns contact/lost events (peer hex + kind) and dropped-frame events (reason + count), alongside confirmed deliveries. This changes the current D3 surfacing (drops to stderr only) so the console can show them; the stderr line stays.
  • New List request → the stored observations (id, observer, topic, payload, addressed destination, age), capped so a response fits the 1 MiB frame cap.
  • Status unchanged.
• Trusted-time behavior is unchanged; the console shows service stderr via docker logs.

The GUI (tines-gui, new crate)

• Window layout: status strip (node id, next seq, stored count, transport, socket path); observe panel (topic, payload, optional recipient + lifetime, broadcast default; text mode with a hex toggle — the wire is hex, the operator should not have to hex-encode by hand); belief panel (query a topic; list known topics from List); store browser (List view with refresh); events feed (contacts, lost, delivered, dropped, live); container panel (docker logs tail, stop/remove/restart).
• Config generation: the launcher writes each container's service config JSON (matching the deny_unknown_fields schema), generates random node ids unless the operator supplies them, and manages volume/socket paths under a per-fleet state directory.
• IPC client: the GUI speaks the widened IPC through a client module implementing the length-prefixed JSON framing. The request/response types are public in the tines crate (lib + bin), so the GUI can depend on the lib and share the types (builder's call, leaning yes).

Docker image

• New Dockerfile.tines: builds the workspace, installs BlueZ runtime dependencies; the entrypoint runs the tines service with a mounted config. Both modes use this image; BT mode adds the privileged/host network and D-Bus/hci plumbing at run time.

What's left to the builder

• Exact JSON schemas for the new IPC variants (within the constraints above).
• Bus daemon protocol details (framing, join/leave messages, fan-out).
• egui layout specifics and the theme integration.
• Docker run flags per mode (device passthrough, volume layout, image build/tag flow).
• Launcher supervision of child processes and daemons (PID tracking, cleanup on exit).

Success looks like

• Sim mode: N containers exchange over the bus; broadcast observations converge in every node; an addressed observation with custody relay is watchable in the events feeds.
• BT mode: the container's node exchanges with a real tines robot over BLE — the two-device check from tines-bt/README.md is finally run and recorded from the console.
• Every operation in the widened IPC is reachable from a window without hand-rolled JSON.