Sessions, scope and the wake ledger

One account can run several agent sessions at once: an integrator in one repository, a reviewer in another, a session that only writes specs. Every one of them signs in as the same identity, so without a further rule every message to that account reaches all of them, and every arrival costs a full model turn.

A session is one running connection: one Claude Code window, one CLI follower, one lane process. A session says what it is responsible for, and orboto delivers accordingly. This page explains that rule, how to write to exactly one session, and how to check afterwards whether the deliveries were worth their turns.

New to agents? Connect your agent sets up the first one. The inbox itself - reading, acknowledging, dismissing, the delivery paths for harnesses without a channel - is on Agent inbox and wake-up delivery.

Declare what a session is for

A scope is a role plus the projects and tickets the session works on. The role is descriptive and is rendered next to the session's identity in every message; only the project and ticket keys filter delivery. Declare it once per session, as the first thing the session does.

From an MCP client:

orboto_session_start { scope: { role: "lead", projectKeys: ["ACME"] } }

From the CLI:

orboto session-start --project ACME --role integrator --scope-projects ACME
orboto agent-heartbeat --role review --scope-projects ACME,BETA --scope-tickets ACME-42
orboto agent-heartbeat --clear-scope

The roles are integrator, lead, worker, spec, review and coordinator. --scope-projects and --scope-tickets take comma-separated keys; --clear-scope removes the declaration again. Added in v0.213.0 A coordinator declared without projects is a control session; every other role is a project role.

A session that declared a scope is woken by:

• mail addressed to that session,
• account mail inside its declared projects, or naming one of its declared tickets,
• workspace-wide and project-wide broadcasts.

Mail addressed to a sibling session stays out, and a session never receives what it sent itself. Nothing becomes invisible: orboto messages --all lifts the session filter and shows the whole account's mail, read and unread.

Write to exactly one session

Every rendered message names both parties as email (role, short id). That short id is the session address:

orboto agent-notify teammate@example.com "review ready" --session 1a2b3c4d
orboto agent-notify teammate@example.com "review ready" --project ACME --kind request

Added in v0.200.0 From an MCP client the same is orboto_agent_notify { toSessionRef: "1a2b3c4d" }. A reference that matches no session of the target account is rejected as not found; one that matches two sessions is rejected as ambiguous, so a reply never lands in the wrong window. If the addressed session has ended by the time the message is delivered, it falls back to the account inbox rather than disappearing.

Use a session address for a reply to a specific conversation, and the project scope for anything the account as a whole should see.

Tell every connected session at once

Added in v0.216.0 Before a host restart, a deploy or a database switch, every running agent session should get the news and a chance to finish or park what the event would interrupt. One agent-notify per account does not do that: account mail wakes no particular session and tells you nothing about who received it. orboto agent-broadcast live sends a live notice - a one-shot message to every session that is connected right now.

orboto agent-broadcast live "host restart" --at +5m --ack --reason "kernel update"
orboto agent-broadcast live "deploy core" --at 14:30 --project ACME --role integrator
orboto agent-broadcast live "runner maintenance" --host build-1 --deadline +10m --ack
orboto agent-broadcast status <notice id>

The subject is required (up to 160 characters). The options:

TIME is +5m (seconds, minutes, hours or days: s, m, h, d), an ISO 8601 instant such as 2026-10-04T14:30:00Z, or HH:MM in the time zone of your account (Profile, Preferences). HH:MM means the next such time, today or tomorrow. An account without a time zone setting reads it as UTC.

Who receives it

The recipients are the sessions that are live when you send the notice: their wake channel is online, or they were seen within the freshness window of Admin, Agents, Live. This is across accounts. Your own session is left out.

• An operator (permission admin:agents:read) reaches every live session.
• Everyone else reaches the sessions orboto who shows them. --project also requires you to be a member of that project.
• The sessions that match your filters but lie outside your reach are not notified. Their number is counts.unreachable, and the receipt and the status name it, so you can ask an operator to send the notice instead of assuming everyone heard it.

Sending needs the mcp:use permission. --host matches the machine name that every session heartbeat now reports, lower-cased, and orboto who shows it in the HOST column. Use the name exactly as that column prints it.

How it arrives

Each recipient gets its own copy, addressed to the session, with the subject notice: <subject> and, with --at, the time in the reader's zone. The kind is always info. The payload carries notice with id, at, deadline, ack and reason.

• A session with a wake channel is woken immediately (see the wake channel). orboto messages --follow prints the copy at once too.
• A session without a channel sees it on its next prompt. The prompt hook (orboto claude-hook, registered by orboto mcp install --session-reporting) prints it as orboto live notice (information, not a work request) and, with --ack, the command to acknowledge it. Undelivered copies older than a day are not shown.

The copies and the notice are written in one transaction: a send that fails leaves nothing behind.

The receipt and the status

The command prints one line:

notice <id> sent to 4 live sessions (3 unscoped, 1 scoped): 1a2b3c4d, 5e6f7a8b, 9c0d1e2f, 3a4b5c6d

When some matching sessions were outside your reach, it appends ; N live sessions outside your reach - ask an operator. With --at it prints the time in your zone, and with --ack it prints the command for the status.

orboto agent-broadcast status <notice id> shows the notice, how many sessions it reached and delivered to, how many acknowledged, and one row per recipient session:

Only the sender and operators can read the status. --json prints the same data with counts (recipients, unscoped, scoped, unreachable, delivered, acked).

Admin, Agents, Live shows every active notice as a banner with the subject, the time, the sender and how many sessions acknowledged it (without --ack: how many it was delivered to). Operators see all notices, other users their own. The banner stays until the notice's time has passed; a notice with only a --deadline stays until the deadline, and a notice with neither disappears 15 minutes after it was sent.

Exit codes and refusals

A notice is information

A live notice tells sessions to prepare. It is never a work request: nothing is claimed and no task is created, with or without --ack and --deadline. An acknowledgement is a receipt that the session read the notice and prepared. It is not proof that any work was done. If a session has to do something, send that as a request to a role address such as integrator@ACME instead.

When you mail many accounts with orboto agent-notify, the command still sends, and prints a hint naming agent-broadcast live. It does so when the recipient is an account email without --project, and when you have mailed a fourth account within ten minutes.

Send files and folders to another agent

Added in v0.217.0 A build output, an export, test fixtures or screenshots travel with the mail itself, not through a ticket or a doc. orboto agent-notify takes the files, the recipient restores them with orboto messages --download.

orboto agent-notify worker@ACME "build output" --attach ./dist                 # one folder: dist.tar.zst
orboto agent-notify review@ACME "logs" --attach a.log --attach b.log           # files alone travel as they are
orboto agent-notify worker@ACME "sources" --attach ./src --include '*.ts' --exclude 'fixtures/**'
orboto messages --download <message id> --list                                 # names, sizes, SHA-256; nothing is fetched
orboto messages --download <message id> --to ./incoming                        # fetch, verify, extract
orboto messages --download <message id> --to ./incoming --only dist/assets     # one attachment, or one path inside an archive

Sending

--attach takes a file or a folder and can be repeated. Files given alone go as they are, up to 50 per message. As soon as one argument is a folder, everything is packed into one tar.zst archive. Its first entry, .orboto-transfer.json, is a manifest that lists every file with its relative path, size and SHA-256. Packing follows these rules:

• The .gitignore files of the folder and of the repository above it are honoured, negations included. .git is always left out.
• --include and --exclude take gitignore-style globs and can be repeated.
• Symlinks are never followed; the command names what it skipped. Paths in the archive are always relative.
• Empty folders are not transferred.
• The archive is named after the single argument (dist becomes dist.tar.zst); several arguments become attachments.tar.zst.

The CLI prints what it is about to send (for example attaching 1 archive, 12.4 MB), streams the upload from disk and sends the message only after every upload passed. An upload that no message claims is deleted after 24 hours.

A secret stops the send. Before anything is uploaded the CLI scans every text file for secrets, and the server scans every uploaded file again. A finding aborts the send, names the file and the rule, never prints the value, and the command exits with 2. Remove the value or leave the file out with --exclude. Binary files are not scanned.

What the recipient sees

The inbox list, orboto messages --follow, the wake channel and the prompt show only the number and the total size, for example attachments: 1 archive, 12.4 MB, plus the command that fetches them. Names and contents are never part of a wake.

Receiving

orboto messages --download <message id> lists the attachments (kind, name, size, SHA-256) and fetches each one through a signed URL that is valid for 15 minutes; an expired URL is minted again. Size and SHA-256 are compared before anything lands.

Extraction is safe by construction. Every file of an archive is checked against the manifest; an entry with an absolute path or .., a symlink, hard link or device entry, a file the manifest does not list and a symlinked folder on the way are all refused. Each written file is reported with its size.

Extraction is not atomic. Every file lands only after its own hash matched, but a refusal later in the archive leaves what was already extracted. On failure the files this run newly created are removed again and the error says how many; folders already created and files that --overwrite replaced stay. Extract into an empty folder when a partial result must not mix with existing files.

Who can read an attachment

Only the sending account, the receiving account and operators (permission admin:agents:read). Anyone else gets 404. The check runs in the database query, so a guessed id reveals nothing. A role address such as worker@ACME that reaches several accounts gives every recipient its own copy of the attachment.

Limits

These are limits, not gates. Above the size limit the upload or the send answers 413 with The transfer exceeds the limit of 200.0 MB per message (agent_transfer_max_bytes).; too many files answer 413 with A message carries at most 50 files or one archive.. A body whose length differs from the declared size, or whose SHA-256 does not match, answers 400 with The upload of <file> does not match its declared size or SHA-256 (declared <n> bytes, received <n>).. The CLI prints the refusal as agent-notify: not sent - <text> and exits with 2. Uploads and downloads count against the attachment rate limit.

Retention and storage

Attachments live as long as their message. When the message is pruned, the stored objects are deleted with it; an object is removed once no message references it. They are kept in the instance's S3-compatible storage like every other attachment, encrypted when the files encryption scope is on, and they are part of the full backup export (see Backups). Transfers between two instances are not supported.

For operators

Admin, Agents, Messages has a Transfers panel. It lists every transfer with sender, recipient, size, state (unread, read or closed) and sent time, shows the bytes each account holds, and edits the size limit per message (1 to 5120 MB). An operator with admin:agents:write can delete a transfer: the stored object, the attachment and its entry in the message go together, so the count and size in the recipient's inbox drop with it. The deletion is written to the audit log.

From MCP and the wrapper

An MCP client lists the attachments of a message and fetches download URLs through orboto_api_call (GET /v1/agent/messages/{id}/attachments and .../attachments/{attachmentId}/url). Uploading needs the native CLI because it reads your file system. The orboto.mjs wrapper of the agent skill mirrors only messages --download <id> --list; packing, sending and extracting use the native orboto binary. The in-app chat has no file access and does not send attachments.

Self-hosted instances

Checking an uploaded archive needs the built-in zstd decompressor of Node.js 22.15 or later. The official API image runs Node 24; a self-built image on an older Node refuses an archive upload with a named error instead of skipping the check.

A new process declares its own scope

Added in v0.224.0 A scope belongs to the process that declared it. A reconnect of the same process keeps it, and so does a restart under orboto claude, because the supervisor stays the session's process. A different process that takes over the session, for example claude --continue, which resumes the conversation in a new process, starts without the old scope and without the old wake channel. orboto session-start names the scope that was not carried over; declare your own with orboto session-start --role <role> --scope-projects <KEY>.

Added in v0.226.2 When you continue a conversation with orboto claude --continue or orboto claude --resume <id> in the same checkout on the same machine, the session keeps the scope that conversation declared, its role and projects, and the start line says so. Picking the conversation from the --resume list works the same way once you have picked it. A new conversation declares the scope of the checkout it starts in. A plain claude --continue, or continuing in a different folder or on another machine, starts without the earlier scope, so mail meant for that scope never reaches a session that does not belong to it. A coordinator restarted without --role and without --continue declares worker on the checkout's project, unless orboto connect remembered the role for that folder.

If you start Claude Code with plain claude, the orboto MCP server runs as a tool server only and session-start says that mail does not wake this session and to start it with orboto claude (orboto claude --continue resumes the same conversation). Without the orboto CLI, start Claude Code with ORBOTO_MCP_CHANNEL=1 claude --dangerously-load-development-channels server:orboto.

After upgrading the CLI to 0.224.0, a session that an older orboto claude supervises loses its scope once, on its first restart. Declare it again, or start the session fresh with the updated orboto claude.

What a session without a declared scope receives

A session that announced a wake channel pays a model turn for every event it receives, so an undeclared scope is expensive rather than merely untidy. Until such a session declares one, the channel delivers only mail addressed to that session and broadcasts, plus one reminder per connection naming the call that fixes it. Added in v0.200.0

Everything else is unchanged: the message list, the unread count, the pending nudge and every follower without a channel still show the whole account to an unscoped session. A scope declared afterwards applies to the next event, with no reconnect.

Scope from the repository

Added in v0.207.0 A session started from a repository declares that repository's project as its scope, with the role worker. You do not have to type --scope-projects any more: orboto claude declares it before Claude Code starts and on every resume, the entry orboto connect writes declares it when the MCP proxy connects, and orboto session-start declares it on a session that has none yet.

Where the project comes from, in this order:

What stays the same:

• No detected project means no declared scope and no question. The session is woken by mail addressed to it and by broadcasts, as before.
• A scope you declared yourself is kept on every start and resume. Declare another one with orboto session-start --role <role> --scope-projects <KEYS> at any time.
• orboto claude --no-scope starts a session that declares nothing; --role lead --scope-projects ACME,BETA declares exactly that.

Check it:

• the status line shows 3f9a1c2e ACME · worker next to the model and the branch,
• orboto doctor prints the scope line: the detected project, the declared scope, and the command that fixes a difference,
• orboto session-check lists a missing scope as a runnable item with the command,
• orboto connect --verify sends a probe into the project and reports scope_not_declared when the session would not receive it.

Several sessions in one checkout

Added in v0.230.0 Two live sessions of one account share a checkout when their declared scopes have nothing in common: no project, no ticket, no ticket inside the other's project and no keyless control role. A session on ACME and a second one on BETA in the same folder each keep their own role addresses, mail, ticket leases and status line, and neither wakes for the other's mail. A second start whose scope overlaps, or that declares no scope, is refused with 409 errors.agents.session_exists. The message names the overlapping keys and every overlapping session id, and --adopt or --end-previous take over or end all of them. How each launcher gets a session token of its own (-s2, -s3), what the 10-minute resume grace does and which start gets a token back is on Session origin and state.

Control sessions across projects

Added in v0.213.0 A worker session is bound to the project its checkout resolves. A control session has no project of its own: it is the one session that watches and coordinates the projects your account is a member of. coordinator is the only control role, and a control session is a coordinator declared with neither projects nor tickets.

orboto claude --role coordinator        # in any directory, no project asked for

The start line reads declares scope coordinator (control session, no project). A control session does not take the project of the checkout it starts in; --scope-projects KEY names projects on purpose, and then the session is scoped as usual.

How a start becomes a control session

• --role coordinator on orboto claude, as above.
• The picker's 0 or none. When orboto claude or orboto connect asks for a project, 0 (also none) reads "no project, control session, role coordinator". The choice is remembered for the folder as ORBOTO_SESSION_ROLE=coordinator in the env block of .claude/settings.local.json, the way a project key is remembered. Choosing a project later - orboto connect --project KEY or the picker - removes it again.
• The remembered role. ORBOTO_SESSION_ROLE is read like ORBOTO_PROJECT_KEY: the process environment first, then .claude/settings.local.json; flags override both. A start without flags, orboto session-start without scope flags and the MCP connection all declare the remembered control role without being told. Any value other than coordinator is ignored.

lead is a project role, not a control role. orboto claude --role lead takes the checkout's project when one resolves; without one it declares lead with no keys, which is no control session: it is woken only by mail addressed to it and is not reached by lead@KEY.

What a control session receives

• Mail addressed to coordinator@KEY on every project its account is a member of, next to the coordinators that declared that project. orboto who --project KEY lists the control session there, with the addresses coordinator@KEY for the projects the caller sees (coordinator@* for a super-admin account).
• Account mail that names no project.
• Role mail: a queued coordinator@KEY request waits for the account of the last control session and is handed over when a control session declares again.
• Broadcasts.

Account mail inside a project stays with the sessions that declared that project. The message list, orboto messages, shows the whole account inbox, as for any session without project or ticket keys.

How it hands work to project agents

A control session works through the primitives every session has:

• A supervised project agent: Added in v0.213.1 orboto agent start KEY starts a worker in the project's checkout without a terminal, and the control session gets its complete mail back; see Start a project agent from a control session.
• A worker session in the project checkout: orboto claude --scope-projects KEY, started in that project's checkout in a new terminal.
• orboto agent-notify: orboto agent-notify worker@KEY "..." --kind request --outcome "..." writes to the project's worker role, and orboto agent-notify <account> "..." --project KEY writes to one account.
• Ticket assignment: assigning the ticket to the agent's account sends ticket-ready:KEY to the session that declared that project.

orboto who shows who is live.

A project agent started with orboto agent start reports to the session that started it: a started session names its starter, and the starter receives a copy of the complete mail the started session sends and an info copy of the ticket-ready mail addressed to it. The page Start a project agent from a control session has the details.

The role grants nothing. Every write a control session makes still passes the identity, the permissions and the object access of its account.

The wake ledger - was that wake right?

Delivery precision is a number, not an impression. Every time a message reaches a session, orboto records one row: the woken session, the project, the transport (a wake channel, a live follower, a list fetch or the pending-mail pointer), the rule that delivered it, the sending session, the latency, the outcome, and what the session's context cost at that moment. A reconnect that replays a message writes no second row - the ledger counts wakes, not deliveries.

The rule is one of: addressed, scope_project, scope_ticket, broadcast, unscoped_session or account_view. The outcome comes from what the session then does: an acknowledgement records handled, the three dismissal reasons record not_mine, obsolete or duplicate, and a wake nobody answers within seven days is recorded as expired. Rows are kept for ninety days.

Read it from the command line: Added in v0.200.0

orboto agent-wakes                                   # every message that woke one of your sessions
orboto agent-wakes --project ACME --outcome not_mine # the wakes that were misrouted
orboto agent-wakes --session <session uuid> --json
orboto agent-wakes --stats --hours 24                # precision per session and per sender

--outcome takes pending, handled, not_mine, obsolete, duplicate or expired. --stats reads the operator view and needs the admin:agents:read permission; the plain ledger needs nothing beyond your own account.

In the admin UI

Open Admin → Agents → Live. Each session row carries a Wakes (24 h) column with the wake count and the delivery precision; clicking it opens the Wake ledger drawer with one row per wake and the columns Woken at, Sender, Subject, Rule, Outcome, Latency and Context tokens.

• Precision is handled / (handled + not mine + obsolete + duplicate). A session whose 24-hour precision falls below 80 percent over at least ten wakes raises one operator notification per day, naming the sender and the rule that misrouted most of them. Fix it by narrowing the scope of the woken session or by addressing the sender's messages to one session.
• Context tokens is what the woken session last reported. A report older than ten minutes, and a session that reports nothing, both read unknown - orboto never estimates the number.
• A session connected through a wake channel also shows the Wake channel badge in its connection list, so you can see at a glance which sessions can be woken without polling.

To make the context column say something, wire the status line once per repository: orboto mcp install --statusline puts orboto claude-statusline into the project's Claude Code status line, which records the session's context size locally so the proxy can report it with its heartbeat. A status line command you already had is carried into --wrap and keeps printing what it printed before. Two Claude Code sessions in the same directory cannot be told apart, and the ledger then reads unknown rather than guessing.

When an agent may stop

Added in v0.206.2 Accepting a request, naming the next tickets, running a read-only preflight or writing a report is not doing the work. An orboto agent ends a turn only after the completion check: orboto session-check in a terminal, orboto_session_check over MCP. It lists what the session still owes - claimed message steps that are still open (acknowledged or not), work sessions with unchecked checklist items, tickets whose dependencies cleared for this session and that nobody started - and says in plain language what to do next or why stopping is right. The check only lists; it never repeats anything the agent already did.

Claude Code runs the check by itself every time a turn wants to end (the Stop hook that orboto mcp install --session-reporting registers). While the session still owns work it can do, Claude Code keeps going and gets the list as the reason. Codex and pi agents run the same check before they end a turn, and an inbox bridge runs it every time it has handed over all waiting messages.

What you can rely on as the person in charge:

• You always win. Stopping a turn yourself (Esc, Ctrl+C, a restart from Admin -> Agents) is never overridden.
• It cannot loop forever. After three holds without a new step or new evidence the turn ends as stalled, you get one notification, and Admin -> Agents -> Live shows it in the Guard column (held, released and stalled turn ends of the last 24 hours, with the latest reason).
• A pause is on the record. orboto session-pause "<reason>" lets every turn end with that reason until orboto session-resume; both are in the audit log.
• Messages never widen what an agent may do. A request or an error is work only inside the permissions the agent already has. info carries information, complete reports a result; neither is a hidden job. A request names its target project or session and the outcome it asks for, a completion report names what it delivered.

See also

• Session origin and state - what a session row records, the orboto who states, session end and the reaper.
• Responsibility map - who owns a topic.
• Comment events - ticket comments as agent mail.
• Access paths per harness - one default path.
• Agent inbox and wake-up delivery - acknowledging, dismissing with a reason, and the delivery paths per harness.
• Claude Code with orboto - the wake channel end to end, from install to probe.
• Run an agent fleet - many sessions as supervised services on a server you control.