Vocabulary

This repo spans multiple surfaces. The same system gets different words depending on whether we’re talking about the control plane, the execution layer, or the house/room/stream collaboration model.

Use the narrowest term that preserves the distinction you care about. If a sentence still works after replacing the word with “thing you come back to later,” the term is too vague.

Arbe control plane

Task

Durable planned work. Lives in .arbe/tasks/, committed alongside code. Answers why work exists.

Run

The unit of intended work. One run per chat, loop, or do invocation. A run contains one or more sessions — chat has one, loop has N (one per iteration), do has one targeting a remote sandbox. wait, resume, and result are operations on existing runs, not new runs.

Session

The conversation — messages, tool calls, retries, permission waits, transcript. Owned by opencode, lives inside a sandbox. A run references its sessions; observation commands (wait, resume, result) read sessions without creating new runs.

Resume

The user-facing arbe command for jumping back into an existing session: arbe resume <n|id>. Use this term for the CLI surface.

Attach

The transport-level action used by opencode or sandbox plumbing to connect an interactive client to a live session. Keep this term for internals, not the top-level arbe command name.

Sandbox

An isolated remote environment (a sprite VM) where sessions execute. Sandboxes are disposable and separate from your machine. Runs can target a sandbox or run locally — local is not a sandbox.

Event stream

The append-only observability timeline for runs and sessions. Lifecycle transitions, tool invocations, permission events. The run timeline is the join layer between task, sandbox, and session.

Result

The inspectable outcome of a run. Shape: { outcome, tasksClosed, error?, tokenUsage }. outcome is one of completed | failed | stuck | blocked. tokenUsage aggregates across all sessions in the run. arbe result <run-id> returns this as JSON; it is also embedded on the Run record.

Record

The only entity — houses, rooms, agents, tools are all records differentiated by type and relational position. See primitives.

Room

The primary conversational scope. A record with identity and permissions, whose content lives in a durable stream.

Thread

A child room. Use only when the parent-child structure matters.

Message

One append-only content item in a stream. The atomic conversational unit.

Stream

An append-only content log. The stream is what happened. Streams live outside Postgres — HTTP-addressed byte logs with their own offset semantics.

Mutation

An append-only audit record of structural changes. Mutations track structure; streams track content. These two histories don’t overlap.

Signal

Observability data — the system witnessing its own operation. Latencies, retries, decisions, activations, failures. Not content (nobody reads signals to understand a conversation) and not structure (nothing was created or moved). Every signal has an agent_id because every action has an author. See observability.md for the four layers.