Resident FLUX motion research loop

Spiral

Closed-loop GPU-saturation render daemons for the Quivent render system.

One fixed-seed latent. Many interesting paths.

Status — 2026-06-10: DISABLED

ACTION REQUIRED

All spiral-* systemd units are stopped and disabled after a system audit found the spiral was the source of runaway GPU load (uncoordinated producers + multiple restart authorities + an in-process governor, with no shared arbiter or convergence stop).

Do not re-enable until the guardrails below and in the SYSTEM-AUDIT-2026-06-10.md are in place. up requires --force.

LIVE AT spiral.influx.vision
• Auto-TLS via Caddy + Let's Encrypt

The spiral continuously feeds and steers the FLUX render worker so the GH200 stays busy, nudging the generation formula toward a calibrated target each cycle.

Two Products, One Checkout

The render repository contains two largely independent systems:

Quantum Render
the headline

Deterministic, model-free, byte-reproducible geometry. The pure render CLI, source/gpu_*.py, PIPELINE.md.

The FLUX Motion Studio
the substrate

Comfort UI + inference stack + this spiral. The resident ~34 GB FLUX.1 pipeline + the autonomous research loop.

The seam between them is the render-stream/1 protocol and the shared out/ + museum surfaces. The spiral belongs entirely to the second product.

Runtime Model

~/spiral (or $SPIRAL_ROOT) is both the Python package and the live data directory.

  • It is importable as import spiral (the directory is the package).
  • All long-lived state (queue, renders, axes/gain maps, experiments, calibration, insights) lives here and is deliberately gitignored.
  • The model-manager in the render repo reads/writes the same files under SPIRAL_ROOT for the web UI.
  • PYTHONPATH is set so python -m spiral.xxx and the systemd units resolve the package correctly.

This design makes the spiral a self-contained “colony” that can be NFS-shared for fleet workers while the rich control surface lives in the Comfort UI + model-manager.

Package & Data Layout

~/spiral/                          # SPIRAL_ROOT (also the import root)
├── cli.py                         # the operator console (python -m spiral)
├── __main__.py
├── core/                          # shared libraries
│   ├── convergence.py
│   ├── crew.py, crewcfg.py
│   ├── modules.py
│   └── ...
├── agents/                        # the autonomous crew
│   ├── mathematician.py, physicist.py, researcher.py...
├── orchestration/
│   ├── controller.py              # closed-loop feedback governor
│   └── runner.py
├── observability/
│   └── monitor.py                 # live dashboard
├── ops/
│   ├── refill.sh, guardian.sh, converge.sh, reaper.sh...
├── systemd/
│   └── spiral-*.service, *.timer
├── docs/
│   └── OVERNIGHT.md, SPEC-observability-agentic.md
└── *.json                         # live state (globals, control, calibration...)

Data directories created at runtime (gitignored): queue/, renders/, axes/, insights.jsonl, spiral.jsonl.

The Operator CLI

python -m spiral <verb> is the single front door for inspecting and driving the system.

Important: It is deliberately read/control only. It never launches agent loops (systemd owns that). A second launch authority was one of the root causes of the 2026-06-10 incident.
COMMON INVOCATIONS
python -m spiral status
python -m spiral monitor --watch 2
python -m spiral refill
python -m spiral converge
python -m spiral down
python -m spiral up --force

CLI Verbs

Verb Purpose Notes / Safety
status Services, queue depth, owner prompt, convergence snapshot Uses the read-only monitor under the hood
monitor Live terminal dashboard Pure read. --watch N or --once
converge Drive the multivec optimizer (foreground) Wraps ops/converge.sh
refill Keep the queue fed from the owner prompt Wraps ops/refill.sh
reap Renders retention reaper Dry-run by default. Use --go to delete.
down Stop the entire spiral unit set Always safe. No --force needed.
up Start the spiral unit set Refuses without --force while DISABLED.

How It Operates — A Typical Cycle

1
Intent
Owner (via Comfort UI or control.json) sets prompt + globals and a fixed seed basis.
2
Refill / Kick
refill.sh or the UI "feed workers" button POSTs to the model-manager, which writes job JSONs into ~/spiral/queue/.
3
Claim & Render
The spiral-worker claims a job (host-tagged), runs the moment operator, produces frames + webm.
4
Evaluate
spiral-evaluator scores the render on the 8 dimensions. Results go to insights.jsonl.
5
Convergence & Steering
The orchestration/controller reads the convergence spine and nudges the actuators (rates, gain map...).
6
Research Loop + Visibility
Agents propose new bases, discover motion planes, update gain maps. Everything is observable via the CLI, UI, and spiral.jsonl.

The Agent Crew

The autonomous research system is factored into specialized agents (each can run as its own python -m spiral.agents.<name> unit):

mathematician
Proposes and validates motion math (operator modes, living-band, organic rhythm).
physicist
Low-level simulation / forward model of the latent walk.
researcher
High-level experiment design.
cartographer
Discovers and maintains motion axes / gain maps.
evaluator
Scores renders on the multi-dimensional ladder.
gemma_eval
Uses Gemma for higher-level semantic judgment.
controller (orchestration)
The closed-loop governor that actually moves the dials toward the target.
head / overseer / integrator / wrangler / translator
Coordination, priority, meta-control, data movement, and translation.

Many of these run “CPU lane” (nice, capped) so they do not fight the GPU worker.

Systemd Units

Core render & saturation
spiral-worker
spiral-saturator (GPU floor)
Research loop
controller • mathematician • cartographer • researcher • evaluator • gemma • physicist • head • overseer • integrator...
Support & safety
refill • guardian • reaper.timer • overnight • saturator...

Every unit has Restart=on-failure, StartLimitBurst=5, memory/task caps, and clean shutdown modes.

Control Surfaces

  1. This CLI (python -m spiral) — the safe terminal operator console.
  2. Comfort UI (Motion tab) — live steering, InMotion, gain map, Research papers, kick / store / train.
  3. Model-manager APIs (/api/mm/spiral/*) — the common substrate.
  4. Direct systemd + ops scripts — for emergencies.
  5. Fleet control plane — when additional boxes are joined via NFS.

Safety, Guardrails & the 2026-06-10 Audit

The audit found that the spiral had become an uncoordinated multi-producer system with no single source of truth for “should we be rendering right now?”

One restart authority (systemd for crashes, guardian for hangs)
Crash-loop backoff on every unit
Saturation detection + automatic rate back-off
RAM / task caps via systemd
Explicit reaper with budget
up is gated behind --force
Single queue producer rule
All long-running state written to disk

Fleet & Multi-Box Operation

ops/fleet-join.sh (run from the hub) enrolls additional GH200 boxes:

  • Verifies CLAIM_SAFE marker
  • Exports ~/spiral over NFS
  • Mounts it on the remote box
  • Ships and enables the spiral-worker unit (with host-tagged claims)

The remote worker claims jobs and writes results back into the shared directories. The model-manager and CLI on the hub see the combined capacity.

Sources & Where Things Actually Run From

The spiral is deliberately split across two concerns:

  • This runtime package (~/spiral): CLI, agents, core, orchestration, observability, ops scripts, systemd units.
  • quivent/render: the heavy worker.py and saturator.py, the model-manager, and the research papers.

Quick Reference — Common Tasks

# See everything at a glance
python -m spiral status
# Watch the live experiment
python -m spiral monitor --watch 2
# Manually top up the queue
python -m spiral refill
# Drive a convergence pass
python -m spiral converge
# Full stop (safe)
python -m spiral down
# Start (only after guardrails verified)
python -m spiral up --force

For the rich visual experience, use the Comfort UI Motion section.

This page is the single canonical operator guide. It is versioned in docs/spiral.html (generated from the detailed Markdown source in the repository) and served live at https://spiral.influx.vision.