Terminus 2 Handbook

State-flow registers

reg-pending-completion

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register prevents the agent from trusting a single completion signal.

Lifecycle:

Cross-Iteration Behavior: Iteration N writes the completion candidate.

Iteration N+1 reads that pending state at [stage-4.9](stage-4.9.html) and stage-4.10 before allowing real completion.

Why This Design: The loop wants confirmation, not a one-shot exit. This register creates a small memory between iterations, so completion becomes a two-step handoff instead of a brittle single observation that could end the run too early.

reg-pending-handoff-prompt

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register gives the summarization side flow a way to pause normal chat history and hand a compressed prompt back into the main loop at the right point.

Lifecycle:

Cross-Iteration Behavior: single-iteration

Why This Design: Summarization happens off to the side, but the result must re-enter the canonical trial record in order. This register is that handoff line. It lets _summarize produce a prompt early, then lets [stage-4.6](stage-4.6.html) splice it into the right structural place without mixing summarization logic into every later stage.

reg-pending-subagent-refs

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register keeps the evidence of summarization work alive long enough for the main loop to record where that summary came from.

Lifecycle:

Cross-Iteration Behavior: single-iteration

Why This Design: The summary text alone is not enough. The system also wants provenance for the summarization ritual. This register carries that provenance from the side flow back to the trajectory writer, so the trial record can show not just that a summary appeared, but which subagent traces support it.

reg-n-episodes

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register gives the system a stable count of how many loop passes actually happened, so teardown can describe the run it is closing.

Lifecycle:

Cross-Iteration Behavior: Iteration N increments the count.

Iteration N+1 sees the accumulated total because the register survives and keeps growing across loop passes until teardown reads the final value.

Why This Design: The run needs one simple thread of continuity across all iterations. This register is that thread. It is not about one stage’s local logic; it is about giving the whole run a monotonic notion of progress that can be reported after the loop ends.

reg-summarization-count

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register prevents summarization from being an invisible side effect by counting how often the compression ritual was invoked across the run.

Lifecycle:

Cross-Iteration Behavior: Iteration N may call _summarize and increase the count.

Later iterations inherit that total, and [stage-5](stage-5.html) reads the final accumulated value after the loop ends.

Why This Design: Summarization changes how the run was managed, so the system wants that activity visible at teardown. Keeping the count in its own register lets the side flow report its footprint without polluting the main chat path or forcing the loop body to reconstruct summarization history after the fact.

reg-trajectory-steps

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register gives the run one canonical place where scattered loop events become an ordered trial history.

Lifecycle:

Cross-Iteration Behavior: Iteration N appends steps.

Iteration N+1 sees the full prior sequence and appends more, so the register grows into the run’s complete ordered history until teardown persists it.

Why This Design: Many stages produce facts, but the system still needs one shared memory of “what happened.” This register is that memory. It lets side-flow outputs, errors, commands, and observations all converge into one ordered record that can survive the loop and be dumped to disk as the trial narrative.

reg-chat-messages

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register gives the LLM query path a current conversation window, while still allowing summarization to replace that window when history gets too large.

Lifecycle:

Cross-Iteration Behavior: Iteration N may have its chat history replaced by [side-S1](side-S1.html).

Iteration N+1 then queries the LLM against that compressed message set unless later writes change it again.

Why This Design: The LLM needs a prompt history, but the full history can become too heavy. This register is the active prompt channel. Because summarization can rewrite it wholesale, the system can carry forward only the context it still needs instead of dragging the full prior transcript through every later call.

reg-asciinema-markers

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register lets loop-time events leave timing marks for a later recording pass that does not run inside the core loop.

Lifecycle:

Cross-Iteration Behavior: Iteration N records markers into the list.

Later iterations keep adding more. After the run, [stage-6](stage-6.html) consumes the full accumulated marker stream during post-processing.

Why This Design: Recording post-process happens after the main work is done, but the timing labels only exist while the loop is live. This register bridges that gap. It lets the loop emit markers when events happen, then hands the whole accumulated set to the external recording path once TmuxSession.stop() is reached.

reg-subagent-metrics

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register keeps subagent cost and token usage separate so the main chat path can stay clean while the run still reports total resource use.

Lifecycle:

Cross-Iteration Behavior: Iteration N adds subagent usage into the accumulator.

Iteration N+1 inherits that running total, and [stage-5](stage-5.html) finally folds the whole register into the trial totals.

Why This Design: Subagents matter to total spend, but they are not the same as the main chat loop. This register creates a dedicated accounting lane. That separation makes later reporting clearer: the system can preserve a clean main-chat metric stream during execution, then combine everything only when it builds the final run totals.

reg-api-request-times

Code sites (authoritative — exact lines grepped from the source):

Purpose: This register preserves the per-call latency trail so teardown can describe how the LLM path behaved over the whole run.

Lifecycle:

Cross-Iteration Behavior: Iteration N appends one or more request times.

Iteration N+1 keeps the existing list and adds more entries, and [stage-5](stage-5.html) reads the accumulated latency history for final metadata.

Why This Design: One request time is just a local fact. The run needs the whole latency trail. This register turns scattered timings from _query_llm and _track_api_request_time into a shared run-level channel, so teardown can report API behavior without re-reading logs or reconstructing timing after execution.