Introducing a new way to review your PRs.

Read the announcement

alishahryar1 / free-claude-code

Use Claude Code, Codex, Antigravity, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

View on GitHub

28 documents · Updated Nov 20, 2026

docs / messaging-conversation-trees

Conversation tree coordination

Conversation tree coordination gives the messaging layer a safe way to run replies as branches of one conversation. It keeps message relationships, execution order, task ownership, cancellation, recovery, and durable state aligned while separate conversations can continue in parallel.

Conversation tree model

Conversation graph

The conversation graph represents one customer conversation as a rooted tree of message nodes. Each node represents a user prompt and its status message. A reply adds a child branch to the node that owns the replied-to platform reference.

The graph keeps two related kinds of links:

  • Logical links connect a child node to its parent node.
  • Platform-reference links connect prompt IDs and status-message IDs to the node they represent.

This distinction lets a reply target either the original prompt or the system status message. It also lets a clear operation remove the exact platform-message branch without removing a sibling branch.

The graph validates restored links before it publishes a tree. A normalized snapshot keeps nodes in root-first order and carries only detached records across the persistence boundary.

References: src/…/graph.py• L16-30 src/…/graph.py• L32-76 src/…/graph.py• L179-264 src/…/node.py• L25-37

Conversation identity

The tree identity is the pair of a message scope and a root message ID. A message scope is the platform and chat namespace in which message IDs are valid. This identity remains stable across runtime restarts while each execution claim receives a separate runtime ID.

The scope prevents a reply from one platform chat from entering another chat's tree. The root ID separates independent conversations that happen in the same chat. Together they provide the key used to find a tree from either a prompt reference or a status-message reference.

References: src/…/models.py• L8-14 src/…/identity.py• L8-14 src/…/graph.py• L42-48 src/…/repository.py• L12-31

Work admission and execution

Turn admission

Turn admission converts an inbound user message into a tree decision. The intake first resolves a reply reference when one exists. The tree manager then creates a new root or adds a child to the matched tree and commits that change before it starts a claim.

The admission result is atomic from the messaging layer's view. It can accept one node for immediate work, place it in the tree's queue, or reject it when the node is already known or its parent branch was removed. A durable store receives the changed tree before the processor can run accepted work.

The main path is:

flowchart LR
    A[Inbound message] --> B[Resolve reply reference]
    B --> C[Find or create conversation tree]
    C --> D{Tree has active claim?}
    D -->|No| E[Create node claim]
    D -->|Yes| F[Place node in FIFO queue]
    E --> G[Run node]
    F --> H[Wait for predecessor]
    G --> I[Complete, fail, or cancel]
    I --> J[Select next queued node]
    J --> G

References: src/…/turn_intake.py• L56-80 src/…/turn_intake.py• L84-160 src/…/manager.py• L120-240 src/…/transaction.py• L14-42 src/…/ports.py• L14-23

Queue and claims

Each tree has at most one active node claim. A node claim is the exclusive permission to run one node. Later replies to the same tree wait in a unique first-in-first-out queue, so duplicate delivery cannot create duplicate work and completion order is predictable.

The queue reports immutable positions to the messaging UI. When the active claim finishes, the tree releases only the matching claim and promotes the next pending node. A stale claim ID cannot finish or replace a newer claim.

Separate trees do not share this single-claim limit. Their claims can run at the same time, which allows independent platform chats or root conversations to make progress in parallel.

References: src/…/queue.py• L6-44 src/…/runtime.py• L38-49 src/…/runtime.py• L105-185 tests/…/test_tree_concurrency.py• L42-106 tests/…/test_tree_concurrency.py• L109-148

Task processing

The queue processor owns the asynchronous task for each claim. The tree remains the owner of scheduling state, while the processor starts the node runner and reports completion or failure back to the manager.

The processor also protects the transition boundary. It attaches task ownership before cancellation can race with task start. If cancellation arrives before the runner enters its body, a recovery task still completes the claim transition. The processor keeps cleanup active after runner cancellation and waits until all owned tasks have finished their completion work before it reports idle.

References: src/…/processor.py• L21-42 src/…/processor.py• L69-125 src/…/processor.py• L158-231 src/…/processor.py• L233-284

Node state and transitions

Node lifecycle

Each node moves through a small execution state model. Pending nodes wait for admission or a queue turn. In-progress nodes have an active claim. Completed nodes retain their session result. Error nodes are terminal for execution and cannot be admitted again.

The parent session ID travels with a child claim when the parent has a session. This gives the node runner the resume point needed to continue a branch while keeping the tree's scheduling state separate from the runner's task state.

StateMeaning in the tree
pendingAccepted but not running
in_progressOwned by the active claim
completedFinished successfully
errorStopped, failed, or interrupted

References: src/…/node.py• L9-16 src/…/node.py• L25-50 src/…/runtime.py• L93-103 src/…/runtime.py• L349-426

Cancellation and branch removal

Cancellation is a tree transition, not only a task interruption. The tree first marks affected nodes as errors and removes queued work. The manager then cancels the matching processor task, drains its cleanup, persists the resulting snapshot, and assigns the final status-message edit to either the runner or the workflow.

A node cancel keeps the active claim identity until that claim performs its matching finish transition. This prevents a late runner callback from clearing a successor claim. A clear operation can also remove a literal platform-reference subtree. If the target is a status message, its prompt node remains as an error anchor while descendants under that status reference are removed. If the target is the root prompt, the manager removes the whole tree.

References: src/…/runtime.py• L187-274 src/…/runtime.py• L276-347 src/…/manager.py• L341-378 src/…/manager.py• L445-631 src/…/workflow.py• L454-490

Failure propagation

A runner failure enters the manager through one failure path. The active node becomes an error and pending descendants can also become errors when failure propagation is enabled. The manager returns copied UI targets, a queue update, and a snapshot so the workflow can update users and durable state without exposing the mutable tree.

Cancellation is kept separate from failure. A cancelled claim does not produce a second late failure or invalidate the next queued claim. This separation lets a stop action remain terminal even if the cancelled runner raises while it unwinds.

References: src/…/runtime.py• L424-464 src/…/manager.py• L305-353 src/…/manager.py• L355-408 tests/…/test_tree_ownership_concurrency.py• L97-135

Persistence and recovery

Repository index

The tree repository is the manager-owned index of live trees. It maps stable tree identities to aggregates and maps every prompt or live status reference in a scoped chat back to its tree. The manager uses this index to resolve replies and to detach a complete tree or branch without exposing the graph to callers.

The index is updated with the same ownership rules as the tree. A new node publishes both its prompt and status references. Branch removal unregisters only the removed references. Whole-tree removal drops the tree and all of its references. If durable storage rejects a transition, the manager restores the prior tree checkpoint and rebuilds its lookup entries.

References: src/…/repository.py• L12-103 src/…/manager.py• L120-142 src/…/manager.py• L204-240 src/…/manager.py• L574-600 src/…/transaction.py• L14-51

Durable storage boundary

Durable storage is the boundary between live tree coordination and saved conversation state. The messaging store loads one conversation snapshot at startup and commits changed trees together with removed identities or a cleared message scope.

The boundary also tracks platform message IDs for later cleanup. Storage errors are explicit transition failures, so the manager can stop new admission for an affected tree instead of allowing memory and durable state to diverge.

References: src/…/ports.py• L10-35 src/…/manager.py• L120-155 src/…/transaction.py• L29-51

Conversation snapshots

A conversation snapshot is a detached, serializable view of all trees. It records the scope, root identity, node IDs, parent references, status references, execution states, and session IDs needed to restore scheduling and reply lookup. It does not expose live node objects or task handles.

Snapshots serve two boundaries: the manager commits them after accepted transitions, and startup loads them before platform delivery is available. Snapshot reads accept older wire shapes where possible and normalize IDs and parent references into the current scoped form. The restored tree marks old runnable nodes as interrupted before it enters the live repository.

References: src/…/snapshot.py• L13-32 src/…/snapshot.py• L77-131 src/…/snapshot.py• L166-221 src/…/runtime.py• L496-522 src/…/ports.py• L14-23

Restart reconciliation

Restart recovery treats every pending or in-progress node from the old process as interrupted. It changes those nodes to error before publishing the restored repository. The workflow persists the normalized snapshot and later edits the old status messages to show that a server restart interrupted them.

Invalid or duplicate trees are skipped during repository restore. A valid tree must remain connected to its root, stay within one message scope, and keep unique prompt and status references. Recovery therefore favors a clean, usable index over loading corrupted or ambiguous work.

References: src/…/runtime.py• L510-522 src/…/repository.py• L107-143 src/…/graph.py• L188-250 src/…/workflow.py• L182-216

Ownership boundaries

Transition values

Transition values are immutable records that carry facts across ownership boundaries. Claims, queue entries, reply targets, cancellation results, and failure results contain copied coordinates rather than mutable graph objects. They let the workflow apply message and status effects without taking ownership of the live tree.

This boundary gives each owner a clear role: the tree decides what state change is valid, the manager coordinates the repository and external effects, and the processor owns asynchronous tasks. The workflow consumes the returned values to update status messages and save snapshots.

References: src/…/transitions.py• L12-155 src/…/manager.py• L86-118 src/…/workflow.py• L680-711

Durable transition transactions

A tree transaction groups live aggregate changes, repository publication, and durable storage into one manager-owned transition. It records a checkpoint before mutation, commits changed snapshots after the mutation, and restores both the tree and its reference index when storage fails.

This transaction boundary prevents a caller from observing a tree that was changed in memory but not saved. It also lets interruption handling mark a tree for cleanup when a worker loses the ability to persist its result.

References: src/…/transaction.py• L14-51 src/…/manager.py• L120-155 src/…/runtime.py• L67-76

Terminal operations

Stop, clear, and branch removal serialize with claim completion and successor publication. A terminal operation waits for the committed transition and drains cancelled tasks before it returns its result. This keeps a removed tree from publishing new work after it has been detached.

Chat clear also advances a per-chat admission boundary before it removes tree and session state. A message that began before the boundary cannot commit after the clear. A later message can create a new tree with the same root ID after the old tree has been detached.

References: src/…/manager.py• L41-77 src/…/manager.py• L485-555 src/…/workflow.py• L492-564 tests/…/test_tree_ownership_concurrency.py• L143-227 tests/…/test_tree_ownership_concurrency.py• L554-602

The parent page Messaging platforms explains how platform adapters deliver normalized messages to this coordination layer. Messaging turn workflows covers the wider turn lifecycle around admission and node execution. Messaging transcripts, rendering, and voice explains the user-visible output and voice paths that consume tree status and cancellation effects.

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep prompt and status references scoped and unique when changing admission or repository indexing.
  • Keep the one-active-claim rule aligned across tree transitions, processor task ownership, and successor publication.
  • Keep branch removal aligned across graph references, repository indexes, queued work, task cancellation, and message deletion IDs.
  • Keep snapshot validation, restart reconciliation, and durable store commits aligned with any change to node state, parent references, or session fields.
  • Keep cancellation UI ownership aligned with runner cleanup so one status message is not edited twice.
  • Keep chat-clear admission boundaries aligned with session-store deletion and tree detachment.
  • Keep transaction rollback aligned with repository reference restoration when a durable commit fails.

Important failure modes

TriggerConsequenceGuard
The same prompt or status ID is admitted twice in one scopeOne user turn could run more than once or corrupt reply lookupThe repository rejects duplicate scoped references and the tree rejects duplicate nodes
A reply arrives after its parent branch was removedThe new message could become detached from the conversationAdmission returns parent_removed and does not publish the new node
A stale claim completes after a newer claim is activeThe newer work could be cleared or skippedTree transitions require the current claim ID
A cancelled runner raises during unwindCancellation could be misreported as a new tree failureProcessor completion keeps cancellation separate from failure handling
A restart restores pending or in-progress workOld work could run twice or show a false active stateRestore marks stale runnable nodes as errors before publication
A branch is removed while its task is activeA detached task could keep running or publish a successorRemoval cancels the matching task and drains cleanup before returning
A snapshot contains cross-scope, duplicate, or disconnected nodesReply resolution could point to the wrong tree or fail unpredictablyGraph validation rejects the tree and repository restore skips it
A tree changes in memory but its durable commit failsLater replies could use state that will disappear after restartThe transaction rolls back the tree and repository index, then gates affected work for recovery

Key files

FileWhy to read it
src/…/manager.pyMain facade that coordinates admission, lookup, persistence results, cancellation, and task ownership
src/…/runtime.pyAggregate that owns per-tree state, queue decisions, claims, and atomic transitions
src/…/graph.pyRules for parent links, prompt/status references, descendants, branch removal, and snapshot validation
src/…/processor.pyLifecycle of asynchronous claim tasks and cleanup after cancellation or failure
src/…/repository.pyLive-tree index, reference lookup, and snapshot restore behavior
src/…/ports.pyDurable storage contract for loading snapshots, committing tree changes, and tracking message IDs
src/…/transaction.pyCheckpoint, commit, and rollback boundary for manager-owned tree changes
src/…/snapshot.pyDurable conversation shape and snapshot normalization rules
src/…/transitions.pyImmutable contracts exchanged between the tree, manager, processor, and workflow
src/…/turn_intake.pyInbound message classification and the handoff into tree admission
src/…/workflow.pyIntegration point that saves snapshots and applies UI effects to stop, clear, and failure results
tests/…/test_tree_concurrency.pyGuarantees FIFO work within one tree and parallel work across separate trees
tests/…/test_tree_ownership_concurrency.pyGuarantees around cancellation races, detachment, and task ownership