Loom

Loom is OptimalOS's master control room. One tab, one viewport, one living tapestry where every workflow on every compute node weaves together. Each strand is a workflow, each node on a strand is a step, each run is a pulse traveling the strand.

It is not a drag-drop builder. Workflows are TypeScript modules. Loom is where they are observed, manually triggered, debugged, and (via the agent-first authoring flow) created.

Locked architectural decisions

These are the decisions that drive every other piece of the design. From the charter at optimalOS/docs/superpowers/specs/2026-04-14-loom-charter.md §3.

#	Decision	Why
1	Workflows are TypeScript modules in optimalOS/workflows/, not JSON or drag-drop	Pure code, type-checked, agent-authorable.
2	SVG sculpture renders the Loom tab; everything else stays monospace	Loom reads as the centerpiece by contrast with the austere cockpit.
3	Single hub via Supabase row TTL lease	First-come election on openclaw_instances; availability over correctness.
4	Supabase is the source of truth; SQLite is local cache	Losing a compute node loses nothing.
5	One full OptimalOS instance per compute node	Each node runs its own server, scheduler, and SQLite cache.
6	Capability tags route work	Each node reports tags like has-gpu or has-returnpro-creds; workflows declare requires: [...] and the scheduler matches.
7	Workflows are authored by agents, not humans	The [+ NEW STRAND] flow spawns Claude Code with a scaffold prompt. See Authoring a Strand.
8	Vertical strand orientation	Top = trigger; descending = steps; bottom = outputs. Loki-accurate.

Phase status (as of 2026-04-29)

Shipped:

• Phase 2 — Workflow shape & loader. WorkflowDef validation, two-root scan (project + ~/.optimalos/workflows/), cache-busting reload. See Workflow Anatomy.
• Phase 4 — Local scheduler. Cron-driven firing on the local node, self-rescheduling timers, manual trigger via API. Hub lease is not yet enforced — the running instance assumes it is the hub.
• Phase 5 — Operations registry. Reusable primitives in optimalOS/operations/. See Operations Registry.
• Phase 6 — Run history in SQLite. loom_runs and loom_step_runs tables, output-tail capture (last 4 KB per step), exponential-backoff retry, persistent-red ack endpoint.
• Phase 8 — Agent-first scaffolding. [+ NEW STRAND] modal, scaffold writer, /api/loom/reload. See Authoring a Strand.
• Phase 9 — Cross-node dispatch. Hub enqueues to loom_job_queue; remote workers claim by target_host; results written back. Validated end-to-end on the Pi + pop-os mesh. See Cross-Node Dispatch.
• Phase 10 — External cron mirror. Synthetic strands for every openclaw cron job, real loom_runs writes keyed by sessionId, synthesized EXEC + DELIVER trajectory, two-way enable/disable via POST /api/loom/strands/:id/enabled. See OpenClaw Cron Mirror.

Roadmap (not yet shipped):

• Per-step Loom UI visibility for priority-triage. The workflow currently runs as a single step run; internal phasing (snapshot, prompt, ollama, parse, enforce, write-back, mark-briefs, apply-overrides, emit-summary) is not surfaced as separate Loom rows.
• Hub TTL lease enforcement. The scheduler currently assumes it is the hub. When the lease lands, scheduling will gate on role='hub' in openclaw_instances.
• Step-level WebSocket events for triage_run_step and equivalents.

For the canonical roadmap, see the charter file path above.