harness-multitool

0012 — Flowcharts are live: flowstate_update callbacks, runs, run history

Decision

A flowchart is not only documentation: it can be bound to a real process or pipeline of the project the agent works on (a CI job, a deploy, a data pipeline, a release procedure, a service's request path) and show it live. A fourth kind of callback, flowstate_update (named flow until 2026-11-01), exists for this.

Binding

A flowchart is bound to the process it describes, and to the windows that watch it: a specific session (tab) of a specific agent. The binding is configuration, like other triggers (CON-23).

Flow events

A flowstate_update callback names three things:

Live state

Every watching window shows the chart's current run: the active node highlighted, the path already taken marked, a failed node in the error colour, the time spent per node.

Every flowstate_update event that changes the chart renders it in the terminal. The chart is drawn into the transcript the same way the /flowchart command draws it, already in its new state — active node, path taken, failures. The user sees the pipeline move step by step: the work is visibly going on. (Decided by the owner, 2026-11-01; replaces the earlier "updated in place, not appended on every event" rule.)

Runs are instances of a reference chart — decided by the owner (answers Q-11)

The flowchart the agent draws for a pipeline is its reference. One new pass of the pipeline is one new instance: a new flowchart made from the reference, with its own state.

The client identifies the pass by its own unique id — a correlation_id of a request chain or any other identifier its product logic guarantees. It sends that id with every flowstate_update of that pass. The id ties events to their instance, idempotently from the client to the instance.

Several instances render collapsed — decided by the owner, replacing "the latest is expanded".

Run history

Every event of every run is kept, in order, with its time (INV-13). Runs can be listed, opened and replayed step by step; two runs can be compared.

This makes a chart a tool for retrospective validation: did the callbacks fire as designed, did the process take the path the chart says, where does it stall or fail, which runs differed.

Checks the chart enables

In short

So the agent can document a pipeline as a flowchart, instrument the pipeline to send flowstate_update callbacks at its steps, and then watch and debug it as it runs, and afterwards from its history: event-driven, live debugging of any process of the project.

Boundaries

Why

The owner wants charts to serve beyond documentation: as the live view and the flight recorder of the processes the agent builds and runs. A chart already holds the intended flow; checking real events against it turns every deviation into something visible and every past run into evidence.

Open

Still open (Q-12, Q-13):

The event schema is the callback contract (uuid, type, the client's pipeline id; IF-13). The owner left the mechanism open on purpose.

Used by ADR 0013: step-debug mode builds on live charts — the active node is the one the latest flowstate_update callback came from, and a run that reaches a terminal block is saved to the project's .harness/debug/ SQLite and the chart reset.

Clarified by the owner, 2026-11-01:

This page's source