Skip to content

Process view

Moira shows every workflow that declares progress as a process view: a short chain of blocks a newcomer can read without knowing the graph underneath. The same view shows a run of that workflow: which blocks are done, which one is active, which were repeated or skipped, and the route the run actually took. This topic explains the vocabulary and how each picture is produced.

Vocabulary

  • Block. One stage of the process as a person would name it — “Draft the plan”, “Independent plan review”, “Execute plan steps”. A workflow’s progress.nodes array lists its blocks in process order; each has a label and a one-sentence description (content.summary).
  • List binding. A block that works through a list may declare list: the variable paths of the items array (items), the title inside one item (title), the index in progress (current, counted from indexBase, 1 by default), the finished count (done) and the total (total). At least one of items, current and total is required; total defaults to the items’ length and done to current − indexBase. The run then reports how far through that list it is, and which item each pass was spent on.
  • Step. One authored node of the workflow graph: a directive the agent executes, a condition or expression that routes, a start or an end. Every step belongs to exactly one block through its progressNodeId, routing steps included, so nothing the run does falls outside the picture.
  • Evidence. What a step must return to finish — its input schema. A block’s outcome text (content.outcome) is a template over the variables its steps write, so the run shows what a block concluded, not only that it ran.
  • Transition. An edge that leaves a block for another block. Each carries a short label from connectionLabels on the authored step, such as “plan approved” or “review found defects”. Both diagrams name it on a port at either end of the line — the source’s port says where the transition goes, the target’s says where it came from — so a connection explains itself without following the line.
  • Loop. A transition back to an earlier block, or to the same block. Its label also states the cause of the repetition and what ends it (cycle.cause, cycle.exit); the views draw it as a return and say the cause and the exit on its ports.
  • Hub. A block that several other blocks lead into (a replan or a stop). It is placed after the blocks that feed it, so the process reads left to right, and the map bundles the connectors from its sources into one channel, each still named at the port it leaves and the port it enters.
  • Run. One execution of the workflow. The engine records its route: every step it ran, the connection it left through, the variables it changed, and where it waited.

The flow page: the process without a run

The process is derived from the workflow definition alone: blocks from progress.nodes, membership from progressNodeId, transitions and loops from the labelled edges. Nothing about it is drawn separately, so the picture cannot drift from the graph. Validation refuses a workflow whose process would be unreadable: a step without a block (unowned-node), a block without a description (empty-description) or without steps (empty-block), a boundary edge without a label (unlabeled-edge), a return without its cause and exit (unexplained-cycle), an outcome template on a block that owns no writer of its variable (outcome-unowned) or on two blocks (outcome-duplicate), a block with no transition to or from another block (unconnected-block; the block owning the start node is exempt, and a self-return alone connects nothing). moira-workflow <file> derive prints the derived process with any of these diagnostics, and set-block, add-block, edit-block, set-label and clear-label author it one change at a time.

The web UI shows this derivation on the flow page (/workflows/<id>, see the Reading and editing a flow guide) through two diagrams of the same process: the map, where each block is one card, and the technical node graph, where each block is a group of its steps. A contents list of the blocks sits beside both and moves the camera to whichever block you pick; a panel beside them shows the selected block and, from it, any one step with its directive, completion condition, expected evidence, routing and validation. Both diagrams offer the same layout presets and follow the one you chose, and clicking a port or a line takes you to the other end of that transition. The owner can edit the definition there — blocks, transition labels and loops, step ownership and text, the variable registry — with the diagnostics above shown inline while typing and a save that is refused for an invalid definition or a stale revision.

The run page: the process with a route

A run is projected onto the process from its recorded route, never guessed from block order:

  • active — the block of the last step the run reached; waiting when that step is paused for a person’s or the agent’s input;
  • done — a visited block whose working steps completed once; repeated ×n — the same after n passes through its working steps (a review that ran twice shows ×2);
  • skipped — a block the run bypassed, or entered without doing its work (only its routing steps ran);
  • pending — not reached yet.

Each block also carries its timing and, when it binds one, its list. Every visit records when it was entered and left — a waiting step from the moment its directive is presented to the moment the answer moves the run on — so a block reports each pass with its duration, the total over all passes, and how long the pass in progress has lasted so far. A visit recorded before timestamps existed has no duration; it reads as unknown rather than as zero. The list reports the items with their titles, which are done, which one is in progress, and the time the block’s passes spent on each. Beside them the run view carries statistics for the version the run started on: how long a pass, a whole run through a block, and each list position typically take across the owner’s other completed runs of that version (median with quartiles and range), so the run in front of you can be read against what is usual; one user’s runs are never another’s statistics. Runs recorded without a version stamp are counted apart and never sampled.

An unvisited block is never shown as done. The route itself is available as an ordered list with loop markers, every variable carries its value history, and a value set from outside the flow (a runtime adjustment) is shown as such with who made it. A route cursor shows the run as it stood at any earlier visit, and the execution’s owner can answer the step the run waits for from the page; the answer is validated like an agent’s and recorded as an adjustment (see the Reading a run guide). A run recorded before routes existed shows only its current block and says that no route was recorded. The run’s progress picture (execution (progress-image-token)) is this map rasterised: the same cards, ports, edges, statuses, facts and typical durations from the same projection (see the Workflows concept). A notification attaches a different picture made for a phone — the run’s steps, one row per block, from the same projection.

The run’s task name is independent execution metadata, separate from its own flow name and arbitrary note. A progress read returns source: "trace" when the flow declares progress; without it, source: "metadata" exposes identity and execution state without inventing a process or route. Explicit naming does not create blocks for a graph-only flow.

The PNG is rendered and published by a live paired controller. Select it with device_id on execution({ action: "progress-image-token", executionId, device_id }); omission requires exactly one eligible live controller. COMMUNICATION_OWNER_UNAVAILABLE is a coded MCP failure and HTTP 503 on mint/public read. Restore the paired connection rather than recreating a VM. Ordinary progress reads and text notifications need no owner; an unavailable optional notification image is omitted while text is attempted independently.

The one-use progress URL and the immutable owner publication have different lifetimes. Successful HTTP completion consumes the progress grant; rendering/stream failure releases its claim, and an error response finishing does not consume it. The publication supports repeated reads until its own expiry under current authority.

Making a workflow readable

Name blocks for what a person would call the stage, keep descriptions to one sentence, label every boundary edge with the decision it represents, and explain every return with its cause and exit. Prefer three to fifteen blocks; put routing steps in the block whose decision they route. The Workflow Management Flow requires all of this when it creates or edits a workflow, and execution({ action: "progress" }) or GET /api/executions/:id/progress returns the run view.