Architecture

System layers

Each box: layer name · source path · what it owns.

The engine run loop

Every node is treated the same: execute the handler, evaluate edges, advance. Parallel, subgraphs, human gates — handlers encapsulate it all.

Edge selection priority

1. Suggested next nodes

   If the handler set suggested_next_nodes (e.g., parallel pointing at a fan-in), take that edge.

2. Conditional match

   Evaluate conditions in declaration order; first match wins. Operators: =, !=, <, <=, >, >= (numeric), contains, not contains, startswith, endswith, in, matches (regex), plus logical and/or/not v0.55.0.

3. Label match

   Match a human gate’s preferred_label against edge labels.

4. Default edge

   First unconditional edge. Safety net — and the source of infinite loops if pointed at a loop target.

Handler types

Each node resolves to a handler. The engine calls Execute() and reads the outcome. New handlers register without touching the run loop.

The dippin adapter

pipeline/dippin_adapter.go bridges dippin-lang’s IR to tracker’s Graph model. Every naming mismatch lives here.

Agent backends

AgentBackend is a one-method contract: execute a node, return an agent.Event stream. The engine doesn’t know which backend ran. Mix per node; per-node attr beats --backend.

Lazy LLM client. buildLLMClient() failure is non-fatal when the global --backend isn’t native. A pipeline can run with no API keys at all if every node uses claude-code (subscription auth) or acp (bridge native auth).

Agent-runtime tools

The native backend ships an extensible tool registry. Architect-tier tools register on demand via env vars — no env var, no tool. Lives in agent/tools/; registered from pipeline/handlers/backend_native.go.

Filesystem jail. A native-backend agent node can carry writable_paths to bound where it may write. On Linux this re-execs tracker under a Landlock ABI v3 sandbox before running; in-process tools (Write, Edit, ApplyPatch) additionally resolve every path via openat2(RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS | RESOLVE_NO_MAGICLINKS) against a session-root fd. The gate refuses to start on a malformed glob, an acp/claude-code backend, or a kernel without Landlock v3 — it never silently runs unconfined. Residual escape classes (network egress, reads/exfil, anything inside an allowed path) are documented, not bounded — see the Linux security primitives and writable-paths audit checklist v0.53.0.

State, budgets & resume

The PipelineContext is the typed key-value store shared across nodes. Variable expansion resolves ${ctx.*}, ${params.*}, ${graph.*}, ${inputs.*}, and ${ctx.node.<id>.*} in prompts, tool commands, and edge conditions — single-pass, never re-scanning resolved values.

${inputs.*} is the workflow’s declared, caller-supplied run signature (a dippin inputs block; requires dippin ≥ v0.51). Values are introspectable (tracker.DescribeInputs), validated standalone with structured per-input errors (tracker.ValidateInputs) and bound at run start (Config.Inputs; a missing required input fails closed before any node runs), and untrusted by construction — the whole namespace is blocked from tool_command interpolation. file AND secret inputs are staged to a fixed 0600 path (.tracker/inputs/<name>) the workflow’s shell reads directly; for a secret, ${inputs.<name>} is that path only, so the value never enters a prompt, the provider wire, the trace, or the checkpoint v0.60.0.

Steering channel. pipeline.WithSteeringChan(chan map[string]string) lets a supervisor inject context updates between node executions via MergeWithoutDirty — writes the global namespace without leaking into per-node scope. Used by stack.manager_loop to steer a child pipeline mid-run. Steered values are namespaced under steer. on the child.

Run terminal statuses

EngineResult.Status carries one of five values when a run ends. The enum is open — future minor releases may add values, so consumers should classify via TerminalStatus.IsSuccess() (or the status_class JSON companion field) rather than switching on the raw string.

The tracker run CLI maps fail/budget_exceeded to exit 1 and (with --fail-on-override) maps validation_overridden to exit 2. Without the flag, override runs exit 0 — the default treats an operator-accepted override as audit-positive. See the CLI exit-codes table.

LLM client middleware

Provider-agnostic. Middleware wraps every request for cross-cutting concerns.

Infra retry handles transient errors transparently: max 3 retries, 2s base delay, exponential backoff. Pipeline-level retries are reserved for actual node logic failures. SSE error handling matters because OpenAI’s Responses API returns HTTP 200 and sends error / response.failed as SSE events — the adapter parses these out; they are NOT reflected in the HTTP status.

TUI model

Built on bubbletea. The pipeline runs in a background goroutine; the TUI receives events via tea.Msg. No polling.

• Pipeline panel — node list in topological order (Kahn’s algorithm). Status lamps, thinking spinners, tool indicators. Subgraph nodes inserted and indented dynamically.
• Activity log — append-only, line-level styled. No glamour rendering (too expensive for streaming). Per-node streams with separators on node change.
• Modal overlays — choice radio, freeform textarea, hybrid radio+freeform, fullscreen review with glamour viewport. All Cancellable.
• Event flow — engine emits pipeline events → adapted to tea.Msg → sent to program → state store updates → view re-renders.

Library API

Tracker is also a Go library. The CLI is a thin printer over the same APIs — and one transport among peers. The TUI, the Slack bot, and any future web or mobile app plug into the same tracker.Config → Engine boundary.