Operations

Operations

Running TRON day to day.

The heartbeat (WAKE)

TRON is autonomous between your inputs. tron --watch idles and wakes on register work, doing one bounded tick each time — filling free slots, clearing ahead, advancing — and idles again when there's nothing to do. It exits cleanly when a STOP file appears. A live tron start console keeps the same engine ticking while you watch.

Walls and your decisions

Anything no worker can clear routes architect-first. Only what the architect genuinely can't resolve — an operator-only task (deploys, secrets, production), an external blocker, human eyes, a true impasse — reaches you as a page (>>ESCALATE), in the terminal and, if configured, on Telegram. The block parks and its slot frees until you decide. A parked block holds the session open — TRON won't end with an unresolved wall on the board.

Pausing before a merge (optional)

If you answer yes to ask-before-merging at bootup, TRON stops at each block's landing and waits for your go-ahead before it merges to trunk — a scheduled touchpoint, not a wall. Approve and it lands; the rest of the fleet keeps moving while it waits. Left off (the default), landings are automatic.

Telegram (optional)

With TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID in a gitignored .env, milestone notes (run start / block done / run done) and pages ride Telegram, and a page waits for your reply there. Missing keys degrade gracefully to the terminal. Keys live only in .env.

Recovery after a crash

Crash-safety is built into every tick — decisions are recorded as they happen (events.jsonl), so a restart resumes from the truth. At boot the engine sweeps: stray agent processes are killed, unverified branches are preserved as orphan/*, and their blocks are re-dispatched fresh. Nothing is double-spawned and no landed work is lost. (Stale worktree arenas from a killed run are also swept at boot.)

Session end

TRON ends only when the whole pipeline is settled — nothing building, nothing waiting on a wall, the architect idle. A completed run ends on its own (or idles under --watch until a STOP file in the project stops it); a pending page can be answered abort to quit.

Validate the instance

Every module ships selftests (no agents, no tokens). Run the suite before trusting a change:

python3 engine/tron.py --selftest && python3 engine/gate.py && python3 engine/tg.py && \
python3 engine/glossary.py && python3 engine/events.py && \
python3 engine/workflow.py && python3 engine/bpmn.py && \
python3 evaluation/harness.py --selftest

The same suite runs in CI on every push. A generated doc that has drifted from its source fails the matching module's doc-sync selftest — regenerate with --write.

Troubleshooting

• A worker looks stuck. It isn't killed on silence alone — the engine probes, re-issues once, then pages (talk-first). Watch events.jsonl (or the run transcript) for the sequence.
• Blocks aren't dispatching. A block is dispatchable only once its file is ready and every dependency has landed on trunk; the architect authors ahead. Raise max_parallel if slots sit free with ready work.
• A >>DONE won't stand. The truth gate bounced it — commits missing, trunk touched, tests red, or the >>CONFIRMED per-criterion evidence was incomplete. After gate_fails bounces it escalates.
• The session won't end. Something is still live — most often a parked wall awaiting your decision. pipeline shows it.
• A generated doc looks wrong. It's generated — edit the source (glossary.py / workflow.toml / events.py) and run the module's --write, never the .md by hand.

See also: Concepts · Architecture.