Introduction

Riff connects the AI agent sessions of different people. The sessions find each other, send messages and share work.

To use riff now, go to Start a Riff.

flowchart LR
    subgraph A["Person A"]
        A1[agent session]
        A2[agent session]
    end
    subgraph B["Person B"]
        B1[agent session]
    end
    A1 <--> S(("riff-server"))
    A2 <--> S
    B1 <--> S

Status: experiment. riff runs each work item in a container on the machine of each person. The sessions of a riff meet in riff-server: on your machine for a riff of one machine, or in Google Cloud for a team.

Jazz players riff off each other. Each adds a part, and the group takes the music where no one player would. Riff lets engineers and their agents work the same way.

riff on a phone

This page is the design of the phone app (#951): the riff chat on an Android phone. It is one child design of the UIs of riff (#982). The build items come after Mike signs off the design. Until then, riff --help does not show riff device, and no release has the app. The requirements of the phone app hold each decision.

What the app does first

The first app does four things:

• It shows the thread chat: the history, then each new line.
• It posts a line.
• It sends @lead, @USER and /me as riff chat does. @lead wakes your lead, and @USER wakes the lead of USER.
• It shows a notice on the phone when a line names you.

Later items can add riff top, the questions of the lead, and the steps of a lead, for example a pause. The app itself is #963. Until then, answer your lead in riff chat: see Ask a lead in the chat.

How the phone reaches the chat

riff-server stays (#953). So the phone reaches the chat through riff-server over HTTPS.

flowchart LR
    subgraph P["your Android phone"]
        U["the Slint app: Rust"]
        C["the core library of #982<br/>and riff-core"]
        A["Android through JNI: the Keystore,<br/>Credential Manager, the camera, the notices"]
        U --> C
        U --> A
    end
    subgraph M["your machine"]
        R["riff chat"]
        L["your lead"]
    end
    C -- "HTTPS: read, tail, post" --> S["riff-server"]
    R -- "HTTPS" --> S
    L -- "HTTPS" --> S
    S -- "a line names you" --> F["Firebase Cloud Messaging"]
    F -- "a notice with a fixed text" --> A

• The app is a Slint app, all in Rust. Slint is the toolkit of each graphical UI of riff (#982).
• The app builds on the core library of #982, which comes first: the client of riff-server and the models of the views. The parse of @lead and @USER, the signed payload and the sign-in proof come from riff-core. So the app and riff chat cannot differ.
• The app uses the calls of riff chat: it joins the thread chat, reads its history, follows it with /v1/tail, and posts. It is a person, as riff chat is. It is not a session.

The platform

The app runs on Android 10 or later. No part of it draws in a web view. It has no Kotlin or Java source of the riff project.

• Slint has had official Android support since 1.5. It has its own Android input code, so the soft keyboard, the IME and copy and paste work.
• The app calls the parts of Android through JNI: the Keystore, Credential Manager, the camera and the notices.
• The Java that the app needs comes from crates and libraries: the helper of Slint, the callback class of jni-min-helper, Credential Manager and Firebase Messaging. Gradle builds the APK with these libraries, so the build needs a JDK.
• The app uses the royalty-free license of Slint. It shows the AboutSlint widget in its About screen.
• The app has no TalkBack: Slint has no screen reader support on Android.

Pair a phone

A phone is a device of a member, as a machine is. One command adds each kind of device: riff device add. You add your phone from a machine where you ran riff login. Then the phone signs in with Google, as riff login does.

riff device add pixel

• NAME is the name of the device, for example pixel, as the host name of a machine. It is not a Google ID. Your chat lines from the phone show as USER@NAME, and riff device remove NAME uses it.
• --kind names the kind of device. The kind sets the scope of the device when you add it. The first kind is phone, the default: a phone acts only on the chat. Each child design of #982 adds its kind and its scope, for example a browser or a desktop app.
• NAME is optional. With no NAME, the name is the kind, for example phone.

sequenceDiagram
    participant P as you
    participant M as riff device add (your machine)
    participant S as riff-server
    participant A as the app (your phone)
    participant G as Google
    P->>M: riff device add pixel
    M->>S: ask for a pair code, with your sign-in
    S-->>M: the code: one time, 10 minutes
    M-->>P: a QR code: the address of riff-server and the code
    P->>A: scan the QR code, or type the code
    A->>A: make a P-256 key in the Keystore
    A->>G: Credential Manager: sign in
    G-->>A: an ID token
    A->>S: the code, the name, the ID token and the key (DPoP)
    S->>S: the account made the code? a new sign-in, host pixel
    S-->>A: the tokens

• riff device add [NAME] runs in a terminal of your own. It refuses with no terminal, so an agent session cannot add a device. It draws the QR code with tui-qrcode, a Ratatui widget, and prints the code as text too. The code is in no URL, so no request line and no log of riff-server holds it. riff-server keeps only its hash.
• The app reads the QR code with the camera, through the NDK camera API and the decoder rqrr. A typed code is the fallback.
• The Google sign-in uses Credential Manager: one tap on the account sheet. It needs an Android OAuth client and a Web OAuth client of the riff. riff-server takes an ID token whose audience is that Web client.
• The person comes from the riff login of the terminal: riff-server ties the code to that Google account. It takes the phone only when the phone signs in with the same Google account. Then it binds the tokens of the phone to the key.
• The key is ECDSA P-256 in the Android Keystore, in StrongBox when the phone has it. It cannot leave the Keystore. The device key of a machine is P-256 too, so the sign-in proof (DPoP) stays the same.
• Your lines from the phone show as <USER@NAME>, for example <mike@pixel>. riff-server sets the host from the name of the pair. It refuses a name that is the host of a machine or of another phone of yours, so a line of the phone cannot look like a line of a machine.
• The token of a phone acts only on the thread chat and on the notices of the phone. A phone cannot claim, pause, invite or read another thread. So a lost phone cannot do a step of a lead or of an admin.
• A sign-in ends after 30 days with no refresh, as each sign-in does. Then pair the phone again.
• The app keeps no text of a message in its storage: only the alias of its key, its tokens and the number of the last line that it showed. A key of the Keystore encrypts the tokens.

A lost phone

riff device list shows each of your devices: its kind, its name, the time of its sign-in and the time of its last call. A machine where you ran riff login is a device of the kind machine, with its host as its name. riff device remove NAME ends the sign-in of one device at once, also of a machine. Run them on a machine of yours:

riff device list
riff device remove pixel

An admin ends the device of another person with --user. riff logout --all and riff remove also end each device of the person. When you clear the data of the app, its key goes. Then add the phone again.

Install the app

Each release of riff attaches riff-phone.apk, of the same build as riff and riff-server. The release key of the riff project signs it. You install it by hand: Android asks you to allow the install.

• The app sends its build, as each client of riff does. When riff-server refuses its release line, the app says to install the APK of the release of riff-server.
• From 2027, Android installs an app from outside Google Play only from a verified developer: see developer verification. Then the riff project uses a free account of “limited distribution”, for up to 20 devices: see the FAQ.
• Google Play can come later. It costs 25 USD one time.

The notices

A phone gets a notice for:

• a line of the thread chat that names its user with @USER, from another person or from a session of another user;
• each line of the verified lead of its user in the thread chat.

Your own lines give no notice. riff-server finds the lines from the to, the sender and the lead mark. It does not read the body: the client makes the selector user=USER, lead=true from @USER.

sequenceDiagram
    participant B as riff chat (brett)
    participant S as riff-server
    participant F as FCM
    participant W as the app of mike
    B->>S: @mike can I take #14? (to user=mike, lead=true)
    alt the app runs
        S-->>W: the line, on the tail of the app
        W-->>W: a local notice: brett@heron: @mike can I take #14?
    else the app is in the background
        S->>F: a notification message: riff: a line names you
        F-->>W: the Firebase library shows the notice
        W->>S: read the chat when you open the app
    end

• While the app runs, it follows the chat. It shows a local notice through JNI, with the sender and the line.
• In the background, riff-server sends an FCM notification message with a fixed text, for example “riff: a line names you”. The Firebase library of the APK shows it by itself, with no service of ours. No push holds the text of a line: the app shows the line when you open it.
• riff-server sends with the FCM HTTP v1 API and its Cloud Run service identity, so it needs no key file. Firebase is on in the Google Cloud project of riff-server (como-riff). FCM is free.
• You turn the notices on and off in the app. Android asks for your consent the first time.
• When FCM says that the token of a phone is not registered, riff-server deletes it. A push never delays a post.
• A phone with no Google Play services gets no background notice. The chat and the local notice work.

What others can see

The app calls only riff-server, Google for the sign-in, and FCM through the Firebase Messaging library. It has no analytics and no crash report.

What the phone needs from #958

#958 encrypts each message end to end, also at rest. The phone is one more device that needs a key. This design leaves the key choices to #958, and gives it these facts:

• The pair is the step where a machine of the person admits the new phone. #958 can admit the encryption key of the phone in the same step.
• The app is Rust, so it can hold the encryption of #958 with the same crates as the CLI.
• No push holds the text of a line. The rule of the notices reads only the to, the sender and the lead mark. #958 must leave them in clear text, or give riff-server another way to find a line that names a person.
• The release key of the riff project signs the app, so riff-server cannot change its code.
• Today a new phone reads the kept history of the chat. #958 decides whether a new device can read the old lines.

An iPhone app

The riff project makes the app for Android. riff is open source, so another person can make an iPhone app. It needs:

• the iOS support of Slint, a tech preview since 1.12;
• the Apple Developer Program, 99 USD each year: a free account cannot use push;
• the key in the Secure Enclave, which keeps P-256 keys;
• a push through APNs, with an APNs key on riff-server or in Firebase;
• a Mac to build the app.

The core library, the screens of Slint and the rules of this page stay the same.

If a later release removes riff-server

No release removes riff-server now. If one does, the phone needs a new path:

• The phone talks over iroh to a daemon of its user, as a client of that daemon. It is no peer of the riff: a phone sleeps, and holds no copy of the records.
• n0 supports iroh on Android, so the app can hold iroh.
• That daemon pairs the phone. That release chooses how a notice reaches the phone.

The build items

Each item is an issue in the Backlog. They start after Mike signs off this design, in this order:

The lead puts them in the waves.

Start a Riff

A riff is the place where your sessions and the sessions of your team meet. In a riff, your Claude Code sessions find each other, talk and share work. riff runs on Linux only.

Did a person give you a riff address?

• Yes: go to Join a Riff.
• No, and the riff is only for this machine: do Just this machine. You do not sign in.
• No, and the riff is for a team, or for more than one machine: go to Start a Team Riff. Each person signs in.

flowchart TD
    Q{Did a person give you a riff address?}
    Q -- yes --> J[Join a Riff]
    Q -- no --> P{Only this machine?}
    P -- yes --> L[Just this machine]
    P -- no --> T[Start a Team Riff]

You need

• Linux with a desktop. riff keeps a key in the keyring of your desktop.
• Claude Code.
• Rust. If you do not have it, install it with rustup.
• A C compiler. On Ubuntu, install it with sudo apt install build-essential.

Just this machine

1. Install riff:

   cargo install --locked --git https://github.com/como-technologies/riff riff riff-server
   

2. Start the riff of this machine in a terminal of its own. Keep that terminal open: the riff stops when you close it or press Ctrl-C:

   riff-server
   

3. In a second terminal, go to your project. Get ready for riff, and start your lead. You do not sign in: riff uses the name that you log in with on this machine. See Get this machine ready and Let the lead start the work.

Use it

In your project, run riff lead start. Your lead runs in a container. The riff daemon starts the other sessions in containers too. Ask the lead: “Who else is in the riff?” The sessions ask their questions there. See The lead. The lead starts at effort xhigh.

Resume the new riff

A new riff is paused. The sessions talk, but they take no work. When you want them to work, run this in a terminal:

riff resume --riff

See Pause the riff.

Let riff work in auto mode

In auto mode, Claude Code can block riff work: a riff tool, riff wave run, or a step of a pull request. A session cannot allow this itself. Run this once in each project, then commit the file that it names:

riff setup

It adds the missing permission rules of riff to .claude/settings.json at the top of the repository. It keeps each rule that is there. It also denies a push to the default branch and gh pr merge --admin. Start your sessions again to use the rules.

Check the rules

This command changes nothing. It names each missing rule, and exits with status 1 when a rule is missing:

riff setup --check

When rules are missing, riff setup adds them. Run it again.

For the rules of your sessions, see The permission rules of Claude Code.

Update riff

Update riff on your machine. It installs riff and riff-server of a release. On Linux x86-64, it downloads the static binaries of the release from GitHub. On another machine, or for a release with no static binaries, cargo builds them (see How riff is built and installed):

riff update

It installs the release that your riff runs. That is not always the newest release (see Releases):

• The riff of this machine: it installs the release that GitHub marks Latest.
• A shared riff: it installs the release of the shared server. After a new release, update when the shared riff runs it. Before that, the command installs the release that the shared riff still runs.

When the riff of this machine runs the old build, the command tells you to start it again. Press Ctrl-C in the terminal of the riff, then do step 2 of Just this machine again. A new start of the riff forgets its messages and its claims, and the riff is paused again. Run riff resume --riff when you want the sessions to work.

A riff of another version can refuse riff (see Builds). When you joined a riff, see Update riff of Join a Riff.

With the update by itself on, riff installs each release with no command. The riff daemon of the release then does each step of riff init that needs no person: its unit and the session images. It tells you each step that needs you. See Each step of an update, and See each step of an update for riff update --check.

Approve a release

The owner or an admin of a riff that deploys its own server gives the human gates of each release: the deploy, a rollback and a skip. The riff daemon tells you in riff chat when a deploy waits. Approve it in a plain terminal, outside Claude Code:

riff release approve v3.3.0

See The release cycle for each gate.

Get this machine ready

riff runs each work item in a container of its own on your machine: the riff daemon runs it. To get ready, install podman and catatonit, the init of podman. riff starts each container with it. On Ubuntu:

sudo apt install podman catatonit

Then run this in your clone of the project:

riff init

flowchart LR
    C["check this machine"] --> R["ask to remove<br/>wide rules"]
    R --> S["ask to set up the<br/>repository on GitHub"]
    S -- "each check passes" --> D["install and start<br/>the riff daemon"]
    S -- "a check fails" --> F["print the fix"]
    D --> I["get the session image<br/>of the project"]

riff init prints one line for each check, with pass, step or fail:

A line with fail also gives the fix. A line with step is a check of your repository on GitHub that riff init fixes itself, after one question. Do each fix, then run riff init again. When each check passes, riff init installs and starts the riff daemon, and the daemon gets the session image. A riff daemon that runs already stays. Then do one item: see Run one item in a container.

Let the lead start the work

You start no worker by hand. When the current wave has free work, the rollout of your lead asks the riff daemon of your machine to run the wave of the repository. The daemon runs each free item and each verify in a container, in the limit of the machine. The lead gets a note.

To run your lead in a container too, run this in your clone of the project. It also starts the wave of the repository, when none runs. The lead needs the claude token of this machine: see Start the lead.

riff lead start

When another session of you is the lead, riff lead start makes the new session the lead. It prints which session was the lead before. In the lead container, whoami says in its first line when the session is not the lead. To see which session is the lead:

riff who

To see the containers:

riff daemon status

A second machine takes work when its daemon runs the wave too: see Use a second machine.

Get the static riff

A riff of cargo install or just install links the libc of your machine. A session image can have an older libc, so that riff may not start there. Then the check of the riff binary fails, and the riff daemon starts no session. Get the static riff of the release:

riff update

Then run riff init again. The riff daemon needs no restart: it reads the riff at each start of a session. With update.auto on, riff gets the static riff by itself: see Update riff by itself.

The permission rules of Claude Code

In auto mode, Claude Code can refuse a step of riff. So riff writes the permission rules of its steps in two places. riff init writes no rule into your own Claude Code settings.

The project place has these rules:

Each rule names its program and its words. Its only * is at its end, after a space. So a rule allows only the steps that it names.

The project place also denies a push to the default branch and gh pr merge --admin. The deny rules never leave the project.

The riff daemon gives each session the rules of its steps. The lead in a container calls its riff by the path /opt/riff/riff, so it gets these rules of its own:

When the auto mode check still refuses a step of riff, the session writes the step on its issue and tells your lead. The fix is a new rule in the code of riff, not a step that you type.

The rules of gh on GitHub

The session place has these rules of gh, by role:

One step in each call

Claude Code matches a rule to each part of a Bash call. So a session of riff runs each riff and gh step alone, in its own call, and gives each file by its absolute path:

gh issue comment 12 --body-file /home/you/tmp/comment-12.md

A rule allows no call that also has a cd out of the working folders of the session, for example cd ~/tmp && gh issue comment 12 --body-file comment-12.md. Then the auto mode check judges the whole call, and it can refuse it. A -R before the words of a step also matches no rule: put --repo OWNER/REPO after them.

Remove a wide rule

riff adds rules, and removes none with no yes. A rule that you added by hand can be much wider than its step. riff init reads the allow rules of your user settings, and of the project settings and the local settings of the repository of the current folder. It names each rule that is wider than the steps of riff, with its file, and asks one question. Answer y to remove them:

riff init

riff removes only the wide rules. It keeps each other rule and each other key. A wide rule fails no check. riff init --yes and riff init --check remove no rule. A rule of the Bash tool is wide when:

• it has no pattern: Bash allows each command;
• or it has a * that is not at its end after a space, for example Bash(gh pr merge * --auto --squash);
• or it allows a command that no step of riff needs, for example Bash(git push *) allows a push to the default branch.

The old form Bash(cargo test:*) is the same as Bash(cargo test *). A rule of another tool, for example Read, is never wide.

Run riff init with no question

This command asks no question. It sets up the repository on GitHub: see Add another repository to the riff. It removes no wide rule:

riff init --yes

Check this machine only

This command changes nothing and asks nothing. It prints the fix of each check that fails and each wide rule. It exits with status 1 when a check fails:

riff init --check

Add another repository to the riff

riff works on other projects too. In a clone of the repository, run riff init. On a repository that is not set up for riff, it shows each step and asks one question. Answer y. You must be an admin of the repository:

riff init

riff init sets up the repository with gh, in this order. It skips each step that is done already:

flowchart LR
    I["riff init<br/>in a clone"] --> C["checks the<br/>repository"]
    C -- "a step to do" --> Q["one question<br/>y, or --yes"]
    Q --> S["the steps, with gh"]
    S --> D["the daemon and<br/>the session image"]
    C -- "all done" --> D

riff init makes riff.toml on the default branch of origin. When your clone is on the default branch, has no change, and lacks only commits of origin, it runs git pull --ff-only there. Else it says why it did not, and you run git pull in your clone. A second run of riff init changes nothing on GitHub and asks nothing. See Read the output for a repository on GitHub.

One part is your own work: the CI. The full check of a pull request, its CI, is the gate of a change: riff waits for it before it starts a verify, and the ruleset lets no change merge without it. riff needs no CI, though. A repository with no CI has no check but riff/verify, and riff init says so in a note. See Use the checks that you have and A repository with no CI.

A CLAUDE.md or an AGENTS.md is the choice of the repository. riff needs neither, and riff init checks neither: it prints no line for them, and a repository with none passes. A session reads the rules of the repository for agents when it has them. See Write a CLAUDE.md, when you want one.

The wave starts a session only for an issue with a Done when: line. riff init names the open issues that lack it, in a note that fails no check. See Find the issues with no Done when line. The names that riff uses on the forge are in The names riff uses on the forge.

To do the steps with no question, run riff init --yes. To see the steps and change nothing, run riff init --check. A person who is not an admin of the repository gets the fix of each check, and riff changes nothing: ask an admin to run riff init.

Run the checks in the container of the lead

A lead can run riff init --check in its container. A container runs no podman, and the host runs the checks of the machine. So in a container riff init skips them, says so in one line, and runs the checks of the repository:

riff init --check

riff checks this machine:
  skip  the checks of the machine: the host runs them
  ...

riff init with no --check does the steps of the repository in the container, as on the host. It installs no daemon and pulls no image: the host has them.

Read the output for a repository on GitHub

This is the output of riff init in a clone of acme/app that is not set up for riff. The answer to the question is y. A line with ... stands for lines that this page leaves out:

riff checks this machine:
  ...
  step  the session image: cannot read the riff config /home/mike/app/riff.toml: No such file or directory (os error 2). Step: make riff.toml on main with a pull request
  ...
  step  riff.toml on main: main of acme/app has no riff.toml, so riff lead start stops. Step: make riff.toml on main with a pull request
  step  auto-merge and squash merge: acme/app allows no auto-merge. Step: allow auto-merge and squash merge
  step  the ruleset of main: no ruleset of main requires the check riff/verify, so a merge does not wait for the verify. Step: make the ruleset riff on main
  step  the milestone Backlog: acme/app has no open milestone Backlog. Step: make the milestone Backlog
  step  the first wave: acme/app has no open wave. Step: make the milestone Wave 1
  pass  the checks of a pull request: pull requests ran checks / lint and checks / test, and the ruleset that riff makes requires them
  ...
riff can set up acme/app for riff. These steps change GitHub:
  allow auto-merge and squash merge
  make riff.toml on main with a pull request
  make the milestone Backlog
  make the milestone Wave 1
  make the ruleset riff on main
Do them? [y/N] y
  done  allow auto-merge and squash merge: allowed both
  done  make riff.toml on main with a pull request: opened https://github.com/acme/app/pull/7 and merged it
  done  make the milestone Backlog: made Backlog
  done  make the milestone Wave 1: made Wave 1
  done  make the ruleset riff on main: requires checks / lint and checks / test and riff/verify
riff.toml is on main now. riff ran git pull --ff-only in this clone, so the clone has it.
riff checks this machine again:
  ...
  pass  riff.toml on main: main of acme/app has it
  pass  auto-merge and squash merge: acme/app allows both
  pass  the ruleset of main: it requires the check riff/verify
  pass  the milestone Backlog: acme/app has it open
  pass  the first wave: acme/app has the open wave Wave 1
  pass  the checks of a pull request: the full check is checks / lint and checks / test
  ...
This machine is ready. Run one item in a container: riff run ITEM

• A line with step is a check that fails, and that riff init fixes with a step. No fact that a step fixes shows as fail. A line with fail is your work: it gives the fix.
• After the steps, riff checks again. A check passes when its step worked.
• riff init makes riff.toml on origin. Then it runs git pull --ff-only in your clone when your clone is on the default branch, has no change, and lacks only commits of origin. Else it says why it did not, and you run git pull yourself.

When a check still fails, the end of the output names each one with its fix. riff installs nothing then, and exits with 1. For example, when the pull requests ran a check of your CI and no rule requires it, the check of a pull request fails until you add that check to the ruleset:

riff checks this machine:
  ...
  fail  the checks of a pull request: pull requests of acme/app ran checks / lint, and no rule requires them, so a merge does not wait for them. Fix: add them to the ruleset of main. See "Use the checks that you have" in the book. Then run riff init again
  ...
1 check failed. riff installed no daemon and pulled no image. Do each fix, then run riff init again:
  the checks of a pull request: add them to the ruleset of main. See "Use the checks that you have" in the book. Then run riff init again

A repository with no CI

riff needs no CI. A repository with no CI has no check but riff/verify. riff init makes the ruleset with that check alone, and it says so in a note:

riff checks this machine again:
  ...
  pass  the checks of a pull request: acme/app has no CI: no pull request ran a check, so riff/verify is the only check
  ...
This machine is ready. Run one item in a container: riff run ITEM

The wave starts the verify of a pull request at once, as no check must end first. The verifier runs the tests that the criteria name, as no check ran them. GitHub merges the pull request when riff/verify passes. riff never invents a check for you. When you add a CI later, run riff init again: it names the checks to add to the ruleset, and Use the checks that you have shows how.

Do the steps by hand

You can do each step yourself. riff init --check names the step of each check that fails:

riff init --check

flowchart LR
    T["riff.toml on the<br/>default branch"] --> S["a session:<br/>gh pr merge --auto --squash"]
    S --> G["your full check<br/>passes"]
    G --> V["riff sets<br/>riff/verify"]
    V --> R["the ruleset lets<br/>the merge go"]
    R --> M["GitHub squash-merges"]

The checks of a pull request are your own work. Your repository may have a CI already: see Use the checks that you have. With no CI, see A repository with no CI.

Add riff.toml

Each repository of the riff has the file riff.toml at its root, on its default branch. Its key image pins the session image. Without the file on the default branch of origin, riff lead start stops with the error riff.toml is not on origin/main. It starts no lead and no wave. The base image of riff, riff-base, has claude, git and gh, and no language. A project adds its toolchain in an image of its own: see Build the image of a project.

riff sets no cache and no variable of a tool in a session. A project that wants a build cache adds the tables [session.env] and [session.volumes] to riff.toml: see Set the env and the volumes of a session.

This command writes riff.toml with riff-base:

IMAGE=$(gh api repos/como-technologies/riff/contents/deploy/rust/Dockerfile --jq .content | base64 -d | sed -n 's/^FROM //p' | head -n 1)
printf '[session]\nimage = "%s"\n' "$IMAGE" > riff.toml

Commit it on the default branch, and push it. Do this before you make the ruleset: after the ruleset, each change needs a pull request.

git add riff.toml
git commit -m "Pin the session image"
git push

Set up the repository on GitHub

Run each step once, in a clone of the repository, as an admin of the repository. gh fills {owner} and {repo} from the remote of the clone.

Use the checks that you have

A repository whose ruleset of the default branch requires checks has a full check. riff reads the required checks of that ruleset. The full check is each of them but riff/verify. riff starts the verify of a pull request when each of them passed or ended on its head. A pass of riff verify pass needs a success of each of them. A check that GitHub skipped, or that ended neutral, counts as a success. The daemon watches main with the same checks: see When main breaks. riff reads the rulesets of GitHub, and not the branch protection of the old kind.

To see the checks that riff waits for:

BRANCH=$(gh api repos/{owner}/{repo} --jq .default_branch)
gh api "repos/{owner}/{repo}/rules/branches/$BRANCH" --jq '[.[] | select(.type == "required_status_checks") | .parameters.required_status_checks[].context] - ["riff/verify"]'

The answer is a list, for example ["checks / docs"]. An empty list means that the repository has no CI: riff/verify is the only check, and riff waits for nothing else. When your CI has checks that the list does not name, put them in the ruleset before riff/verify: see Make the ruleset of the default branch.

Allow auto-merge and squash merge

Each work session runs gh pr merge --auto --squash. GitHub refuses it until the repository allows both:

gh api -X PATCH repos/{owner}/{repo} -F allow_auto_merge=true -F allow_squash_merge=true

Make the ruleset of the default branch

Without a rule, nothing on GitHub makes a merge wait for the verify. This ruleset needs a pull request, and the check riff/verify. It allows squash merges only, and it lets nobody bypass it. When your CI has checks, put each of them before riff/verify, in the same list:

gh api -X POST repos/{owner}/{repo}/rulesets --input - <<'JSON'
{
  "name": "riff",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "bypass_actors": [],
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 0,
        "dismiss_stale_reviews_on_push": false,
        "require_code_owner_review": false,
        "require_last_push_approval": false,
        "required_review_thread_resolution": false,
        "allowed_merge_methods": ["squash"]
      }
    },
    {
      "type": "required_status_checks",
      "parameters": {
        "strict_required_status_checks_policy": false,
        "required_status_checks": [
          { "context": "riff/verify" }
        ]
      }
    }
  ]
}
JSON

Make the Backlog and the first wave

A wave is a milestone named Wave N. The Backlog is the milestone Backlog: riff wave move --to Backlog and riff wave end --move-open-to-backlog need it. This command makes the first wave. It makes the Backlog too, when the repository has none:

riff wave make "Wave 1"

A repository that has waves and no Backlog gets the Backlog alone:

gh api -X POST repos/{owner}/{repo}/milestones -f title=Backlog

Write a CLAUDE.md, when you want one

A CLAUDE.md or an AGENTS.md is the choice of the repository. riff needs neither. The start text of riff says only what riff needs: the item, the branch, the frame of the pull request and, for a verify, the report. A session reads the rules of the repository for agents when it has them. Write one when you want to give each session rules.

flowchart LR
    S["start text of riff<br/>the item, the branch,<br/>the pull request"] --> A["a session"]
    C["CLAUDE.md of the repository<br/>its rules, when it has them"] --> A

Write the file with your own commands in place of make check, and push it with a pull request:

cat > CLAUDE.md <<'EOF'
# Notes for agents

## Work

- Run `make check` before each push. It passes with no warning.
- Each change has a test.

## Issues

- Each "Done when:" line of an issue names a test that you can run.

## Verify

- A verifier reads the diff and runs the test of each criterion.
- A verifier does not run `make check` again: the CI did it.
EOF

The CLAUDE.md of riff is an example of a longer file.

Use any default branch

The default branch can have any name: main, master or trunk. The wave reads it from GitHub, and keeps it in no file. A verify reads its diff against that branch, a rebase starts from it, and the look watches its full check. This command shows the branch that riff reads:

gh api repos/{owner}/{repo} --jq .default_branch

After you rename the default branch, do nothing: the wave reads the new name within 10 minutes. When GitHub does not answer, the wave starts no work at that look, and riff daemon status says why. The wave looks again each minute.

Build the image of a project

riff publishes two images that a project builds its session image FROM:

flowchart LR
    B["riff-base<br/>claude, git, gh"] --> R["riff-rust<br/>+ Rust"]
    B --> P["your image<br/>+ your toolchain"]
    R --> P
    P -- "push, then the digest" --> T["riff.toml<br/>pins the digest"]

Your image adds the toolchain of your project to one of them. Do not add riff to the image: riff binds its own binary into each session. A session cannot write the toolchain folder of the image, so the toolchain must be in the image.

These two commands read the digest of each image from main of riff. You pin a digest, so a tag cannot move under you:

BASE=$(gh api repos/como-technologies/riff/contents/deploy/rust/Dockerfile --jq .content | base64 -d | sed -n 's/^FROM //p' | head -n 1)
RUST=$(gh api repos/como-technologies/riff/contents/deploy/session/Dockerfile --jq .content | base64 -d | sed -n 's/^FROM //p' | head -n 1)

The notes of each release of riff name the same two digests. Then write the Dockerfile. This one is for a project that needs Node:

mkdir -p deploy/session
cat > deploy/session/Dockerfile <<EOF
FROM $BASE
RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm && rm -rf /var/lib/apt/lists/*
EOF

A Rust project has two ways. When its CI uses the Rust of riff-rust, build FROM riff-rust and add what the project needs:

mkdir -p deploy/session
cat > deploy/session/Dockerfile <<EOF
FROM $RUST
RUN apt-get update && apt-get install -y --no-install-recommends libssl-dev && rm -rf /var/lib/apt/lists/*
EOF

When its CI pins another Rust, build FROM riff-base and install that version. Put the version of rust-toolchain.toml in place of 1.88:

mkdir -p deploy/session
cat > deploy/session/Dockerfile <<EOF
FROM $BASE
RUN apt-get update && apt-get install -y --no-install-recommends gcc libc6-dev make pkg-config && rm -rf /var/lib/apt/lists/*
ENV RUSTUP_HOME=/usr/local/rustup CARGO_HOME=/usr/local/cargo PATH=/usr/local/cargo/bin:\$PATH
RUN curl -fsSL https://sh.rustup.rs | sh -s -- -y --no-modify-path --profile minimal --default-toolchain 1.88 --component rustfmt --component clippy && chmod -R a+rX /usr/local/rustup /usr/local/cargo
EOF

Try the image on your machine before you push it:

podman build -t localhost/session:test deploy/session
podman run --rm localhost/session:test claude --version

Build the image with a workflow

A workflow builds the image on each change of its folder, and pushes it to the registry of GitHub. The package name is the repository name with -session:

mkdir -p .github/workflows
cat > .github/workflows/session-image.yml <<'EOF'
name: Session image
on:
  push:
    branches: [main]
    paths: [deploy/session/**]
  pull_request:
    paths: [deploy/session/**]
permissions:
  contents: read
  packages: write
jobs:
  image:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}-session" >> "$GITHUB_ENV"
      - uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/setup-buildx-action@v4
      - id: build
        uses: docker/build-push-action@v7
        with:
          context: deploy/session
          push: true
          tags: ${{ env.IMAGE }}:${{ github.sha }}
          provenance: false
      - run: echo "image = \"$IMAGE@${{ steps.build.outputs.digest }}\"" >> "$GITHUB_STEP_SUMMARY"
EOF

Merge the Dockerfile and the workflow with a pull request. A pull request from a branch of the repository runs the workflow too, so the summary of the run shows the line for riff.toml. Show it:

gh run list --workflow session-image.yml --limit 1
gh run view RUN_ID

Pin the image of the project

Put the digest from the summary in riff.toml. Put your owner and your repository in place of OWNER and REPO, and the digest in place of DIGEST. riff refuses a tag:

IMAGE=ghcr.io/OWNER/REPO-session
DIGEST=sha256:DIGEST
printf '[session]\nimage = "%s@%s"\n' "$IMAGE" "$DIGEST" > riff.toml

Merge riff.toml into the default branch with a pull request: the sessions use only the merged pin (see Only a merged pin counts). Make the package public in its settings on GitHub, and check that each host can pull it: see Check that each host can pull the image. Then run riff init. When each check passes, the riff daemon pulls the image:

riff init

For a repository that has no riff.toml yet, riff init --image pins the image in the first pull request:

riff init --yes --image "$IMAGE@$DIGEST"

Check that each host can pull the image

The session image must be pullable by each host of the wave. The riff daemon runs podman pull as your user on the host. riff manages no registry login, so only a podman login of your user on that host counts. A host that cannot pull the image starts no session of the repository.

flowchart LR
    P["a pull request<br/>changes the image"] --> V["riff verify pass<br/>asks the registry"]
    V -- "no manifest" --> F["no pass, and the fix"]
    V -- "the manifest,<br/>with no login" --> M["merge"]
    M --> H["each host:<br/>podman pull"]
    H -- "fails" --> S["riff daemon status<br/>and a message to the lead"]

To ask the registry the question of a host that has no login, run this in a clone of the repository. It reads riff.toml of the working tree, so you can try an edit before its pull request:

riff image --check

When the registry gives the manifest, it prints one line and exits with status 0. When it gives none, it prints the fix and exits with status 1. This is the line for a private package:

ghcr.io gives no manifest of ghcr.io/acme/session@sha256:… with no login (the registry answered 403 Forbidden). A host with no login cannot pull it, and then each new session of the repository stops there. Fix: make the package public, or run podman login ghcr.io on each host of the wave.

Do the fix. Make the package public in its settings on GitHub. Or run this as your user on each host of the wave, and give the login of the registry:

podman login ghcr.io

The verify of a pull request that changes the image in riff.toml asks the registry the same question. It passes no pull request while the registry gives no manifest: see Report a verify. When a host cannot pull the image of a wave, the daemon starts no item there. It shows the image and the reason in the line of the wave, and it tells the lead once with the fix. It pulls again each minute:

riff daemon status

Build the image again for a new riff-base

riff needs a version of claude and of gh at least as new as those of its riff-base. A new release of riff can need newer tools. At the first job of a wave of your repository after the update, the daemon reads the version of both tools in your image. When one is too old, the lead gets one message. It names the tools and the digest of the new riff-base. File an item for it, and in the item change the FROM line of the Dockerfile to the new digest:

BASE=$(gh api repos/como-technologies/riff/contents/deploy/rust/Dockerfile --jq .content | base64 -d | sed -n 's/^FROM //p' | head -n 1)
sed -i "s|^FROM .*|FROM $BASE|" deploy/session/Dockerfile

Merge it. The workflow builds the new image. Then pin its digest in riff.toml, as in Pin the image of the project. A project that builds FROM riff-rust takes the digest of riff-rust from the notes of the release, in place of $BASE.

To learn more, read How It Works.

Start a Team Riff

A team riff is the place where the sessions of your team meet. It runs on a Linux host that each person of your team reaches. Each person signs in with their own account. You are the owner: you invite each person.

For a riff on your machine only, with no sign-in, see Start a Riff.

flowchart LR
    A[machine of a person] -- HTTPS --> P[TLS proxy]
    P -- HTTP on 127.0.0.1:7878 --> S[riff-server]
    S -- sign-in --> O[OIDC app of the team]

You need

• A Linux host with an address that your team reaches, for example riff.example.com.
• A TLS proxy on that host, for example Caddy. riff-server has no TLS.
• Rust and a C compiler on the host. See Start a Riff.

Make an OIDC app

riff has no built-in sign-in app. Make your own Google OAuth client once. See Make your own OAuth client. Keep its client ID and its client secret in a safe place. Do not put them in source, in a commit or on a page.

Start the riff

Do these steps on the host.

1. Install riff:

   cargo install --locked --git https://github.com/como-technologies/riff riff riff-server
   

2. Put the OIDC app in the environment of riff-server. Put your client ID in place of ID and your client secret in place of SECRET:

   export RIFF_OIDC_CLIENT_ID=ID RIFF_OIDC_CLIENT_SECRET=SECRET
   

3. Start the riff in the same terminal. Keep that terminal open. Put the address of the riff in place of URL, for example https://riff.example.com, and the email of your account in place of EMAIL:

   riff-server --public-url URL --owner EMAIL
   

   riff-server listens on 127.0.0.1:7878. --public-url is the address that people use. --owner names you as the owner.

4. In a second terminal, start the TLS proxy. It takes HTTPS at the address of the riff and sends it to riff-server. For Caddy:

   caddy reverse-proxy --from riff.example.com --to 127.0.0.1:7878
   

Host your own riff on Cloud Run

In place of a Linux host, riff cloud can run the riff on Google Cloud Run. It uses the gcloud of your machine. Install the gcloud CLI, and sign in:

gcloud auth login

Make a Google Cloud project, and link a billing account to it. See Set up the cloud project for the commands.

flowchart LR
    C["riff cloud create"] --> S["riff cloud signin"]
    S --> D["riff cloud deploy"]
    D --> L["riff cloud list<br/>status, log"]

Who runs riff cloud

You run the writes of riff cloud in a terminal: create, signin, deploy, smoke and delete. smoke is a write too: it signs in to the riff, and posts a message. Your lead session can run them too. A worker, or an agent session that is not your lead, cannot run them: riff refuses, and changes nothing. In a worker, it says:

riff: a worker never changes a riff in the cloud. riff cloud changed nothing. Ask the lead: the lead or a person runs it.

Each session can run the reads: list, status and log.

Make the riff

Do these steps in a clone of riff, so that the deploy can build the image. Put a name for the riff in place of NAME, for example team, your project in place of PROJECT, and a region in place of REGION, for example europe-west1:

git clone https://github.com/como-technologies/riff
cd riff
riff cloud create NAME --project PROJECT --region REGION

It writes the settings file deploy/cloud/NAME.env. The service, the bucket, the accounts and the secret take the name of the riff. Then it makes each of them. It checks each one first, so you can run it again. To get an email for each error of the riff, give your email:

RIFF_OWNER=YOUR_EMAIL riff cloud create NAME

Store the sign-in client

riff cloud signin NAME

It shows the steps to make the sign-in client in the console of Google. Then it asks for the client ID and the client secret. The secret goes to Secret Manager. The ID goes to the settings file.

Deploy the riff

The riff needs an owner: your email. With no tag, Cloud Build builds the image from your clone:

export RIFF_OWNER=YOUR_EMAIL
riff cloud deploy NAME

The URL of the riff is in riff cloud list. Tell each person to use it (see Join a riff).

See and stop the riff

riff cloud list
riff cloud status NAME
riff cloud log NAME --errors

To stop the riff, delete its service. riff asks you to type the name. The bucket with the state stays, unless you add --with-state:

riff cloud delete NAME

Sign in to gcloud again

When the sign-in of gcloud ended, each riff cloud command stops with this line:

gcloud: the sign-in ended: run gcloud auth login

Sign in again, then run the command again:

gcloud auth login
riff cloud list

no service in riff cloud list means that gcloud replied that the service does not exist. When your account has no permission on the project, riff stops with the PERMISSION_DENIED line of gcloud. Sign in with an account of the project, or ask the owner of the project for the permission.

Sign in first

Sign in before you invite a person. On your machine, use the riff. Put the address of the riff in place of URL. For zsh, use ~/.zshrc:

echo 'export RIFF_SERVER=URL' >> ~/.bashrc

Open a new terminal. Sign in with the account of EMAIL. Your browser opens:

riff login

Invite a person

Invite each person with the email of their account:

riff invite EMAIL

The command prints the address of the riff and the lines that the person runs to join. Send the lines to the person. The lines hold no secret. The person follows Join a Riff. To see the members of the riff, see See the members.

See the members

To see the owner, the admins, the members and the allowed domains of the riff, run:

riff members

It shows each person once, with the highest role: owner, then admin, then member:

owner            mike@example.com
admins           ada@example.com
members          bob@gmail.com
allowed domains  example.com

A riff with no owner shows the owner none. Its last line, in yellow, says how an admin takes the owner role (see Take the owner role).

The lead runs it in its container too. The riff daemon of the host reads riff-server for the lead, so the lead can see who is an admin, for example to know who may approve a release. riff invite, riff remove, riff admin and riff owner change the members. A person runs these in a terminal on the host.

See each change of the members

The riff posts each change of the members to the thread of each repository of the riff, as a note: riff invite, riff remove, riff admin add, riff admin remove and each step of the owner role (see Take the owner role). The note names the user that made the change, the email and the change. It wakes no session. The command prints the threads that got the note. A note that the riff posts by itself comes from riff@server.

To see the notes as they come, run this in the directory of a repository:

riff tail

A note looks like this:

members: ada invited bob@gmail.com. bob@gmail.com is a member now.

Take the owner role

A riff has one owner. Each admin can take the owner role. The owner can answer, but an owner who is away does not stop the riff.

stateDiagram-v2
    Owner --> Asked: an admin runs riff owner --take
    Asked --> Owner: the owner passes or keeps the role
    Asked --> Owner: no answer in 10 minutes, the admin is the owner
    Owner --> NoOwner: the owner is gone
    NoOwner --> Owner: the first admin runs riff owner --take

Ask for the owner role

Only an admin can ask:

riff owner --take

The riff tells the owner at once: a direct message to the lead session of the owner, and a note. The owner has 10 minutes to answer. With no answer, you are the owner. The old owner stays an admin. One request waits at a time. A second request is refused, and the refusal names the admin that asked first.

When you are the owner already, the command says so and changes nothing. It is not an error:

You are the owner already. Nothing changed.

Answer a request

To pass the role, the owner names the admin that asked:

riff owner EMAIL

To keep the role:

riff owner --deny

The riff tells the admin.

See a change of the owner in the chat

A change of who the owner is also posts one line in the chat, as riff@server. The line has the text of the note. These changes post a line: a pass, a grant after the time, a gone owner, and a take on a riff with no owner. A request and a deny post none, because the owner stays the owner. The line wakes no session. To see it, run:

riff chat

A line looks like this:

members: mike took the owner role. The riff had no owner. mike@example.com is the owner now.

An owner who is gone

riff-server checks the owner each 10 minutes, while the riff has an admin who is not the owner. A check misses when no session of the owner is live, and the owner ran no riff command since the last check. After 3 misses in a row, the server warns the owner: a note to the sessions of the owner, and one line in the chat. When the next check misses too, the owner is gone. The old owner stays an admin, and the riff has no owner. The riff asks each admin for a volunteer: a direct message to the lead session of each admin, and a note. The first admin that runs riff owner --take is the owner at once, with no wait.

While the riff has no owner, riff members says so. riff admin and riff owner EMAIL are refused until an admin takes the role.

Stay the owner

When the server warns you, run any riff command before the next check, for example:

riff who

Change the times

Three settings of riff-server set the times:

For example, to give the owner 30 minutes to answer, add the option to step 3 of Start the riff:

riff-server --public-url URL --owner EMAIL --owner-take-minutes 30

A restart

riff-server keeps its state in memory. When it stops, it forgets the members, the sign-ins, the messages and the claims. Do steps 2 and 3 of Start the riff again. Then sign in again with riff login, and invite each person again. Each person signs in again with riff login.

Keep the state over a restart

Give riff-server a directory for its state. It then keeps the members, the sign-ins, the messages and the claims over a restart. It starts 15 seconds later. Wait for the line riff-server listens on before you run the first riff command:

riff-server --public-url URL --owner EMAIL --dir ~/.local/state/riff-server

Join a Riff

A riff is the place where your sessions and the sessions of your team meet. It has an address, for example https://riff.example.com.

Use this page to join a riff with sign-in. The steps are the same in each case:

• You join the riff of your team, or of another person. The owner of the riff invites you first.
• You add a second machine to your own riff. You are its owner, so you need no invite.

flowchart LR
    I[install riff] --> C[choose the riff]
    C --> S["riff login<br/>signs you in"]
    S --> W["riff who<br/>shows each machine"]

riff runs on Linux.

You need

• The things of Start a Riff.
• The address of the riff. Ask its owner.
• An invite. The owner of the riff runs riff invite EMAIL with your email. Your own riff needs no invite.
• A clone of the project of the riff.

To start a riff with sign-in for your team, see Start a Team Riff.

Join the riff

1. Install riff:

   cargo install --locked --git https://github.com/como-technologies/riff riff
   

2. Choose the riff. Put its address in place of ADDRESS. The line goes in the profile of your shell, so that each new terminal has it. ~/.bashrc is for bash only. For zsh, use ~/.zshrc:

   echo 'export RIFF_SERVER=ADDRESS' >> ~/.bashrc
   

3. Open a new terminal, so that it has RIFF_SERVER. Sign in. Your browser opens. On a second machine of your own, use the same account as on the first machine:

   riff login
   

Check it

Show the riff that riff uses, its build and your sign-in:

riff server

List the sessions of the riff. It shows the sessions of each machine:

riff who

Then start your lead from that terminal, in your clone of the project: riff lead start. Ask: “Who else is in the riff?”

Update riff

A riff of another version can refuse riff (see Builds). When the owner updates the riff, update riff on your machine. It installs the release that the riff runs (see Releases):

riff update

Then pull each clone of your project.

To skip this step at each new release, let riff update itself on your machine (see Update riff by itself).

A riff with no bucket forgets each sign-in when it starts again. Then sign in again (see After a restart with no bucket, run riff login).

Change to another riff

For example, you move from the riff of this machine to the riff of your team. riff moves no messages and no claims to the new riff.

1. Remove the old RIFF_SERVER line from the profile of your shell. Then add the line of the new riff. Put its address in place of ADDRESS:

   sed -i '/^export RIFF_SERVER=/d' ~/.bashrc
   echo 'export RIFF_SERVER=ADDRESS' >> ~/.bashrc
   

2. Open a new terminal. Sign in to the new riff, if it has sign-in:

   riff login
   

3. Start your lead again from the new terminal. A session that runs keeps its old riff.

To go back to the riff of this machine, remove the line only, then open a new terminal:

sed -i '/^export RIFF_SERVER=/d' ~/.bashrc

riff keeps a sign-in for each riff. So a change back needs no new sign-in.

How It Works

Parts

flowchart LR
    subgraph M["Your machine"]
        S1["agent session<br/>in a container"] -- MCP --> C1["riff relay mcp"]
        W1["riff relay watch"] -- wakes --> S1
        L["riff-server<br/>in a terminal"]
    end
    C1 -- "HTTP, loopback" --> L
    L -- wakes --> W1

• riff-server is the central service. It holds the live sessions, the threads, the claims and the leads. It runs on your machine, in a terminal (see Start a Riff). It listens on loopback. A riff with sign-in listens on your network, so that other machines join it (see Join a Riff).
• riff relay mcp gives a session in a container its tools: whoami, who, threads, read, post, tell, status and blocked.
• riff relay watch writes one line for each message that wakes the session. Your agent tool reads the line and wakes the session. See Wake a session.

Sessions in containers

The riff daemon of each machine runs each work item in a container of its own. riff-server is the server of the riff: the claims, the messages, the chat, the sign-in and the update of each machine. The waves stay on GitHub.

The goal of isolation

riff is not a security tool. It does not make Claude Code more secure than a plain claude that you start. The permission modes and the settings of Claude Code do that, and you choose them.

riff isolates sessions, so that they do not step on each other or on your machine: files, git state, processes, /tmp, ports, CPU and memory.

riff does not make Claude less secure. A session gets no power that a plain claude lacks, other than the riff tools.

The picture

flowchart LR
    subgraph M["your machine"]
        L["the lead:<br/>riff lead start,<br/>or claude on the host"] -- "the rollout:<br/>run the wave" --> D["riff daemon<br/>systemd user unit"]
        V["riff view, riff top"] --> D
        D -- "podman" --> C1
        D -- "podman" --> C2
        subgraph C1["container: issue-12 (conmon)"]
            R1["riff relay"] --> K1["claude -p"]
        end
        subgraph C2["container: verify of issue-9 (conmon)"]
            R2["riff relay"] --> K2["claude -p"]
        end
        R1 -- "its own socket" --> D
        R2 -- "its own socket" --> D
        I[("session image<br/>pinned by digest")] -.-> C1
        I -.-> C2
    end
    D -- "claims, riff tools, wakes:<br/>your sign-in of riff" --> S["riff-server"]
    L -- "messages" --> S
    C1 -- "push with your sign-in" --> G["GitHub"]
    D -- "verify, waves" --> G

• The daemon is a systemd user unit. It owns the sessions of the machine.
• Each work item is one session in one rootless podman container. A verify is an item too. The session starts, does its item and ends.
• The rollout runs the wave of the daemon. The lead asks the daemon to run the wave of the repository. The wave starts one session for each free item, in the limit of the machine. The rollout starts no worker on the host.
• riff relay is the entrypoint of the container. It starts claude and talks to the daemon through a socket that only that session sees.
• The daemon makes the claim of each item on riff-server, as the worker session of the item, with your sign-in of riff. The riff tools of the session act on riff-server through the daemon.
• Each repository names its session image, pinned by digest, in the file riff.toml at its root. A project builds that image FROM the public image riff-base of riff, or riff-rust, and adds its own toolchain. See Build the image of a project and Change the session image.
• The daemon reads the version of claude and gh in the session image of a repository at the first job of its wave after the daemon starts. When a tool is older than the riff-base of this riff has, the lead gets one message with the new digest. See Build the image again for a new riff-base.
• The session pushes its work with your sign-in of GitHub.

How a session works in a container

sequenceDiagram
    participant W as the wave of the daemon
    participant S as riff-server
    participant D as the riff daemon
    participant C as the container: relay and claude
    participant G as GitHub
    W->>S: the pause, the holds and the claims
    W->>G: the free items and the pull requests that wait for a verify
    W->>D: room for one more session?
    D->>S: a new worker session, and its claim of issue-12
    D->>D: a clone of the item, with --reference MAIN
    D->>C: podman run --init: riff relay -- claude
    C->>D: the riff tools, on the socket of the session
    D->>S: read, post, tell and status, as the worker session
    C->>G: push the branch, open the pull request
    C-->>D: the end of claude
    D->>S: the verify request to the lead, then the release of issue-12
    D->>D: the container and the clone go

A second machine takes work when its daemon runs the wave of the repository too. riff wave run --host HOST adds it: see Add a host to the wave. The claims on riff-server keep two machines from one item.

What sessions share

Each row is a thing that two sessions on one machine share. The last column is honest: it says what a session can still do to another session. The rows use the result of the spike of one item in a container, #707, and the result of the spike of the claims, #708. The requirements for sessions in containers hold each decision of the design.

Where the env of a session comes from

riff sets in a session only what riff needs itself: the home, the user, the sign-ins, the git config, the Claude folder, the clone, the folder of the socket, and the caps --memory and --cpus. It sets no variable and no volume of a language or a tool. The repository gives them in its riff.toml, in the tables [session.env] and [session.volumes]. Only the merged riff.toml counts, as for the image (see Only a merged pin counts).

flowchart LR
    R["riff.toml on the default branch:<br/>[session.env] and [session.volumes]"] --> S["the spec of the session"]
    H["riff: the home, the user, the sign-ins,<br/>the clone, the socket, --cpus, --memory"] --> S
    S --> P["podman run -e NAME=VALUE -v VOLUME:PATH"]

A riff.toml with neither table gives a session no tool variable and no cache volume. A repository of any language works the same way. The riff.toml of riff sets the build cache of riff: the cargo home, sccache, and their two volumes. To write the tables, see Set the env and the volumes of a session.

Find a command

riff --help lists the commands that people use, under the headings Get started, Work in the riff, Pull requests, Lead and Members. Each command has one short line. riff help with a command shows its full text:

riff --help
riff help invite

riff-server --help lists the settings of the server.

The riff that riff uses

riff finds its riff in --server or RIFF_SERVER. With neither, it uses the riff of this machine, http://127.0.0.1:7878. riff keeps no choice in a file.

flowchart LR
    F{"--server?"} -- yes --> U[that riff]
    F -- no --> E{"RIFF_SERVER?"}
    E -- yes --> U
    E -- no --> L["the riff of this machine<br/>http://127.0.0.1:7878"]

Each value is a URL, HOST or HOST:PORT. With no scheme, riff uses http://. With no port, it uses port 7878. So first is http://first:7878. An IPv6 address takes brackets with a port: ::1 is http://[::1]:7878, and so is [::1]:7878. To use another riff, see Change to another riff.

Show the forms of –server

The help of each command gives --server one short line. riff help server shows the forms of a value and the default:

riff help server

Show the riffs

riff server shows the riff that riff uses, and where that choice comes from, with its release and your sign-in. It shows one fact on a line:

riff server

riff        v0.6.0  (75209ac, 2026-09-29)
server      https://riff.example.com  (from RIFF_SERVER)
  release   v0.6.0  same build ✓
  sign-in   yes, signed in as mike@example.com

• local shows the riff of this machine too, when it answers.
• answer none: the riff does not answer.
• Under the sign-in line, it shows the facts of the server.
• When you must act, the last line says what to run, for example Run riff update or Run riff login. It is yellow when the versions can talk, and red when they cannot or when you must sign in.
• It says Run riff update only when the server is newer than this riff. When this riff is newer, it says Update riff-server when you can. See When the builds differ.

localhost, 127.0.0.1 and [::1] with the same port are one riff: the riff of this machine. riff server shows it once.

To show the riffs with no color, use --color never. A pipe gets no color either, so a grep finds a line:

riff server --color never
riff server | grep release

See the facts of the server

riff server also asks the riff that riff uses for its facts. Use them to see if the server is healthy:

riff server

server      https://riff.example.com  (from RIFF_SERVER)
  release   v0.9.0  same build ✓
  sign-in   yes, signed in as mike@example.com
  serves    yes
  error     none since the start
  log       position 1234; the last chunk write was 3s ago and took 45 ms
  faults    0 write errors, 0 skipped records since the start
  saved     checkpoint at position 1000, 5m old, from v0.9.0
  counts    12 chunks, 8 sessions, 40 cursors, 9 threads, 5 live sign-ins
  memory    35 MB in use
  started   2h ago; the replay took 120 ms

• A riff with sign-in gives its facts only to a person who is signed in. Else the lines are not there.
• An older riff-server has no facts. The lines are not there.

Name the riff for one command

--server names the riff for one command. It wins over RIFF_SERVER:

riff --server 127.0.0.1:7878 who

Builds

A build of riff or riff-server is the crate version, the last commit that changed the code, and the time of that commit. A commit that changes only the book keeps the build.

The version is a semantic version, MAJOR.MINOR.PATCH. It tells which versions can talk. The line of a version is its major, and its minor while the major is 0: 0.4.1 is on the line 0.4, and 1.2.0 is on the line 1. A change that another machine or session can notice starts a new line (see Versions). Most merges keep the line.

riff-server talks with a riff of its own line, and of the line before. So you have one release to update riff in. It talks with no riff of another line.

Each call of riff names its build, and each reply of riff-server names its own. Each side compares the versions:

flowchart LR
    R["riff<br/>a build"] -- "call, with the build of riff" --> S{"riff-server:<br/>riff on its line<br/>or the line before?"}
    S -- yes --> OK["the reply. Another build:<br/>riff tells you once to update"]
    S -- no --> E["409: both builds, and the side to update"]

See the build

riff --version
riff-server --version

riff whoami and riff who also show the build, after the server answers, in the fact build. When the builds differ, the fact riff-server shows the build of the server, in yellow, and says that the versions can talk:

build        v0.7.0  (3c7b111, 2026-09-29)
riff-server  v0.7.0  (f45be4d, 2026-09-29)  another build; the versions can talk

When the builds differ

riff works. Each riff process tells you once which side is older. riff server gives the same advice on its last line. When the server is newer, the note says to update riff:

riff: riff-server runs build 0.4.3 7213825ab1c2 2026-09-27T20:10:44Z; this riff runs build 0.4.0 929605821e54 2026-09-27T22:03:01Z. Run riff update when you can.

When this riff is newer on the same line, for example while a deploy runs or after a rollback of the server, the server is the older side. This machine needs no step:

riff: riff-server runs build 0.4.0 7213825ab1c2 2026-09-27T20:10:44Z; this riff runs build 0.4.3 929605821e54 2026-09-27T22:03:01Z. Update riff-server when you can.

When riff is on the line before the server, the next line of the server refuses it. The note says so:

riff: riff-server runs build 0.4.0 7213825ab1c2 2026-09-27T20:10:44Z; this riff runs build 0.3.2 929605821e54 2026-09-20T22:03:01Z. riff-server 0.5 will refuse riff 0.3. Run riff update soon.

When the note says “Run riff update”, update riff on this machine:

riff update

riff relay watch, riff tail, riff top and riff chat see the new riff on disk, and run it. They go on with no restart, in the same repository and worktree. This is also true when you removed their worktree.

• riff chat keeps its lines on the screen, and draws its prompt again. Text that you typed but did not send is lost.

When riff cannot read its directory

A riff command in a removed directory fails. The error names the directory:

Error: riff cannot read its working directory /src/riff/.claude/worktrees/issue-12. Change to a directory that exists

Change to a directory that exists, for example your repository, and run the command again:

cd ~/src/riff

When git fails

riff asks git where you work: the repository, the remote origin and the worktree. riff never guesses. A directory outside git is not a fault: its repository is -. A repository with no origin is not a fault either: its repository is local/NAME. When a call of git fails for another reason, riff tries it 3 times. Then the command fails, and the error names the call and the reason of git:

Error: riff cannot read git in /src/riff: `git rev-parse --show-toplevel` failed with exit code 128: fatal: detected dubious ownership in repository at '/src/riff'. riff does not guess where you work. Run the command again.

The command registers no session. Fix what git says, and run the command again. To see the reason yourself, run the same call:

git -C ~/src/riff rev-parse --show-toplevel

When the versions do not match

Each riff command fails with an error like this one:

riff: this riff (0.2.0 929605821e54 2026-09-27T22:03:01Z) and its riff-server (0.4.0 7213825ab1c2 2026-09-28T20:10:44Z) do not match. riff-server 0.4 talks only with riff 0.4 and 0.3. Update riff on this machine, then start your sessions again. See https://como-technologies.github.io/riff/how-it-works.html#when-the-versions-do-not-match

A reply with no build names what riff saw in place of the build of riff-server, for example no riff build in the reply: status 200 OK from https://…/v1/who.

A new session gets the same error at its start. It tells you, and it does not use the riff. riff tail prints the error once, try again every 5 seconds, and go on when the versions can talk. riff server shows both builds.

Update the older side:

• riff on this machine, and riff-server of your own riff: do Update riff. When you joined a riff, see Update riff of Join a Riff.
• The shared server: an admin pushes a release tag at the end of each wave, and CI deploys it. A push to main does not deploy it. See Deploy the shared server at the end of a wave.

Then start your Claude Code sessions again.

Releases

riff update installs a release, not the newest commit of main. A release is a git tag vX.Y.Z of the repository (see Make a release). It picks the release this way:

flowchart TD
    U[riff update] --> T{"--tag vX.Y.Z?"}
    T -- yes --> I[install that release]
    T -- no --> L{"riff uses the riff<br/>of this machine?"}
    L -- yes --> N[install the release that<br/>GitHub marks Latest]
    L -- no --> B{"riff can read<br/>the build of the riff?"}
    B -- yes --> S[install the release that the riff runs]
    B -- no --> N

So a new tag does not break your machine before the shared server runs it. riff server shows the release of riff and of each riff.

When the riff names no release, riff update installs the release that GitHub marks “Latest”: the release that the shared riff runs. It is not always the highest tag: GitHub never marks a prerelease Latest. See the Latest release:

gh release view --repo como-technologies/riff

An old riff cannot always read the build of a newer riff, for example after a change of the build header. Then riff update installs the Latest release and prints this line:

riff cannot read the build of the riff at https://riff.example.com, so riff installs the Latest release, v0.3.0.

Install one release

To install one release, for example the release of another riff, name its tag:

riff update --tag v0.2.0

See what changed in a release

The GitHub releases are the changelog of riff. The notes of a release give its level, the command that each person runs, and each pull request that the release adds. The pull requests come in three groups: Changes for people first, then Design (design pages), then Internal (tests and checks only). List the releases, and read one:

gh release list --repo como-technologies/riff
gh release view v0.4.0 --repo como-technologies/riff

Update riff by itself

A machine can update riff by itself. When the riff runs a new release, riff on the machine installs that release, with no riff update by you. Turn it on for this machine:

riff update --auto on

Turn it off:

riff update --auto off

See the setting:

riff update --auto

update.auto  true  (/home/mike/.config/riff/config.toml)
Turn it off with: riff update --auto off

The setting is the key update.auto in ~/.config/riff/config.toml ($XDG_CONFIG_HOME/riff/config.toml). It is off by default.

Each reply of the riff names its release. When a riff process sees a newer release than its own, it starts one update in the background, and tells you once:

riff: riff-server runs the release v0.4.0. riff installs it now, in the background (update.auto).

The update goes this way:

sequenceDiagram
    participant P as riff process
    participant S as the riff
    participant U as riff update, in the background
    participant L as your lead
    participant D as riff daemon
    P->>S: call
    S-->>P: reply, release v0.4.0 (newer)
    P->>U: start: riff update --tag v0.4.0
    U->>U: take the update lock of the machine
    U->>U: install v0.4.0
    U->>L: "riff on pangolin updated itself from v0.3.0 to v0.4.0."
    U->>D: start again on the new riff

• One update runs at a time on the machine. Each release gets one try.

• Each riff process starts again on the new riff when it is idle. See Which processes start again.

• The riff daemon of the release does each step of riff init that needs no person. See Each step of an update.

• The update stops no session, and a running test goes on. Your sign-in and the device key stay.

• Your lead gets one direct message: the host, the old release and the new release.

• A failed update keeps the old riff. The message to your lead holds the error. riff tries again at the next release. To try again now, run riff update --tag with the release.

• The update runs in a directory that exists, also when the riff process that saw the new release runs in a removed worktree. If the directory of the update is missing, the release does not count as tried, and the next riff command tries again.

• riff never installs an older release by itself.

• An older riff updates itself with cargo. So after the update, your riff can be a build of the new release that is not static, and the riff daemon starts no session with it. When the riff of the bin folder of cargo (~/.cargo/bin) sees the riff run its own release, and it or riff-server there is not static, it installs its own release again in the background. riff update then puts the static files of the release in place. This fix gets one try for each release. Your lead gets one message:

  riff on pangolin put the static riff and riff-server of v1.4.1 in place of a build that is not static.
  

The output of the update is in update.log, in the local folder of riff.

Which process tells your lead

The first riff process on the machine that sees the new release starts the update. That update, riff update --background, tells your lead once in each repository of the message:

The riff daemon has no repository of its own. Its working folder can be in the work tree of another repository, for example a home folder that is a dotfiles repository. The daemon does not use that repository. When the daemon serves no repository, the update tells no lead, and update.log says why.

The update tells your lead first. Then it starts the daemon again on the new riff. The daemon does not start again while the update runs: a new start of the daemon stops the update that the daemon started. When the message to your lead fails, update.log says why, in the line riff: cannot tell the lead.

Each step of an update

riff init does more than the binary: it installs the unit of the riff daemon, and pulls the session image. A release can change each of them. Your yes to the update by itself is your yes to each step. So the riff daemon of the new release does each step that needs no person, at its start:

flowchart TD
    B["the update by itself installs the new riff"] --> D["the riff daemon starts again on it"]
    D --> G{"update.auto on, and its riff<br/>is a release on GitHub?"}
    G -- "no" --> N["it changes nothing"]
    G -- "yes" --> U["1. the unit of the daemon"]
    U --> I["2. the session image of each wave"]
    I --> P["3. the checks of the machine:<br/>it only tells you"]
    N --> P

• Only a release does a step: a riff whose SHA-256 is in SHA256SUMS of the GitHub release of its version. A check build or a dev build changes nothing. With RIFF_RELEASES set, the daemon changes nothing.
• The daemon logs one line for its gate and one line for each step. See them with journalctl --user -u riff.service.
• A step that needs you shows in the log, with its fix.

The update and the daemon say what they did in their logs:

• update.log holds the output of the update by itself. Its last lines after an update:

  riff downloads the static riff and riff-server of v1.7.0 (x86_64-unknown-linux-musl) into /home/mike/.cargo/bin.
  riff: riff on pangolin updated itself from v1.6.0 to v1.7.0.
  

  The update shows no note that riff-server runs another build: the update installed that build.

• The log of the riff daemon has one line when the daemon starts again on a new riff:

  riff daemon: a new riff is on disk, and no session runs. The daemon starts again on it.
  

  The new start stops the old daemon and its systemctl. That is no failure, so the log has no other line for it. Only a failed ask to systemd logs cannot start again on the new riff, with the error and the fix riff daemon install.

See each step of an update

See each step on this machine, in step or not, with its fix. The command changes nothing:

riff update --check

update.auto is on, and this riff is the release v1.6.0: at its next start, the riff daemon does each step that is not in step and needs no person
in step  the riff binary: it is the release v1.6.0
not in step  the unit of the daemon: the unit file is not the text that this riff writes for it. Fix: riff daemon install
in step  the session image of como-technologies/riff: ghcr.io/como-technologies/riff-session@sha256:…
in step  podman: podman version 5.7.0
needs you  the init of podman: podman has no init: no catatonit in /usr/local/libexec/podman, /usr/local/lib/podman, /usr/libexec/podman, /usr/lib/podman, so no session can start. Fix: install catatonit, the init of podman, for example: sudo apt install catatonit
in step  /etc/subuid: 65536 IDs for mike
in step  /etc/subgid: 65536 IDs for mike
in step  cgroup v2: user@1000.service has cpu and memory

• Each line starts with in step, not in step, needs you or failed. A line that is not in step names its fix.
• It also shows the image of the repository of the current folder.
• It exits with 1 when a step is not in step.
• After you do the fix of a step that needs you, run it again.

Which processes start again

After an update, by you or by itself, each riff process of the machine starts again on the new riff. It does this only when it is idle, so no work stops:

You still start riff-server again yourself. riff update tells you when it runs the old build.

The unit of the riff daemon can run another riff than the riff on your PATH, for example the build of a check after a release. Then riff update writes the unit again with the riff on your PATH. It keeps the variables of the unit:

riff update

riff wrote the unit /home/mike/.config/systemd/user/riff.service again: it ran /home/mike/.cache/riff/check/target/static/release/riff, and runs /home/mike/.cargo/bin/riff now.
The riff daemon runs 2 sessions or jobs. It starts again on the new riff after its last session.

When the daemon runs no session, it starts again at once:

The riff daemon runs no session. It starts again on the new riff now.

A session keeps its network over a start of the daemon again. riff runs each podman run in a systemd scope of its own. So pasta, the network process of podman, is not in the cgroup of riff.service, and the stop of the unit does not end it:

flowchart LR
    U["riff.service"] --> D["riff daemon"]
    D -- "systemd-run --user --scope" --> S["scope of the session: podman run, pasta"]
    S --> C["the container, with its network"]
    U -. "a stop ends the daemon only" .-> D

The stop of the daemon stops no container. Still, riff starts the daemon again only when it owns no session, no start of riff run waits for room, and no job of a wave runs. A start of a wave that waits for room does not stop it, also with the limit 0: the new daemon waits for room for the wave again. The daemon looks at the end of each session and each job, and each minute:

flowchart TD
    U["riff update"] --> X{"the unit runs the riff on PATH?"}
    X -- no --> W["write the unit with the riff on PATH"]
    X -- yes --> O
    W --> O{"the daemon runs an old riff?"}
    O -- no --> N["nothing to do"]
    O -- yes --> B{"a session, a start of riff run that waits,<br/>or a job of a wave?"}
    B -- no --> R["systemd starts the daemon again"]
    B -- yes --> L["the daemon waits"]
    L --> E["the end of a session or a job, or a minute"]
    E --> B

To start the daemon again at once, also with sessions, install it again. Its sessions go on:

riff daemon install

A new machine asks about the update by itself

On a machine with no update.auto key, for example a new or rebuilt machine, riff login asks you once:

Update riff by itself when the riff gets a new release? [Y/n]

Press Enter to turn it on, or type n to keep it off. It does not ask again. With no terminal, for example in a script, it does not ask. To ask again, remove the key, then run riff login.

Versions

A riff is a contract between machines and between sessions. Two sessions on different versions in one riff must not act differently or fail to understand each other. The level of a release tells you what changed.

Patch

The patch number grows. Nothing changes that another machine or session can notice:

• a fix that restores the intended behavior;
• the docs, an output format, the tests;
• words of a requirement that make a rule clearer, with no change in behavior.

Minor

The minor number grows. A change that another machine or session can notice:

• the wire: a route or a field that a client needs, a removed one, or a new meaning;
• the saved state of riff-server;
• the names and arguments of the riff tools;
• the behavior: a change of a requirement that changes what a session does, for example the pull request flow, the verify, the claims, the waves or the pause.

riff-server still talks with a riff of the line before its own (see Builds), so a wire change stays additive for one line. Riff does not hide a difference in behavior: the version note tells the older session to update.

Major

A major version promises that the wire and the behavior stay stable. A major breaks, a minor adds and a patch fixes. A change of behavior that can break a pipeline or a policy is a major.

The test for each release

Ask: can a session on the old version and a session on the new version, in the same riff, act differently or fail to understand each other?

flowchart LR
    Q{"old and new session<br/>in one riff: act differently<br/>or fail to understand?"} -- yes --> M["minor<br/>(major after 1.0)"]
    Q -- no --> P[patch]

A wave release is a patch unless the wave has a minor change.

Sign-in

sequenceDiagram
    participant C as riff login
    participant G as Google
    participant E as riff-server
    C->>G: open browser, sign in
    G-->>C: Google ID token
    C->>E: Google ID token + device public key
    E->>E: check signature; owner, admin, member or allowed domain
    E-->>C: riff tokens, bound to the device key
    Note over C: tokens and key go to the OS keyring

Each agent session then gets its own short-lived token from riff. The token acts only as that session. riff keeps it in memory, not in the keyring.

A session token has no refresh token. Each riff process of a session swaps the person token for a session token of its own: riff relay mcp, riff relay watch and each riff command. A new session token ends no other token. A process that runs for a long time swaps the person token again before its session token expires.

riff-server keeps each sign-in, and the hash of each live token, in the object signins.json. A swap is a change of it too. A restart with a bucket says when the server writes the object, and which reply waits for the write.

sequenceDiagram
    participant M as riff relay mcp
    participant C as riff claim
    participant S as riff-server
    M->>S: swap the person token, session a6cf
    S-->>M: session token 1
    C->>S: swap the person token, session a6cf
    S-->>C: session token 2
    M->>S: a call with token 1
    S-->>M: 200, token 1 stays live
    Note over M: before token 1 expires
    M->>S: swap the person token, session a6cf
    S-->>M: session token 3

A refresh token works once. It names its chain and its generation: chain.generation.secret. A sign-in has one chain, for the person. Each refresh gives the next generation of the chain. riff-server keeps only the hash of the current generation, and of the one before it.

A refresh token of an older generation ends the sign-in: somebody copied it. A lost reply is not a copy. When the token of the generation before the current one comes back, the reply of its refresh did not come back, for example after a 503. riff-server then gives a new pair, and the sign-in stays. Only the device key of the sign-in can end it this way: the server checks the key first.

flowchart TD
    R[refresh token of generation G comes back] --> K{the device key of the sign-in?}
    K -- no --> W[refuse; the sign-in stays]
    K -- yes --> C{G is the current generation?}
    C -- yes --> N[new pair, generation G+1]
    C -- no --> L{G is the generation before it?}
    L -- yes --> P[end the current pair, give a new pair: the reply was lost]
    L -- no --> E[G is older: end the sign-in]

Get back into the riff

riff relay watch, riff tail and each tool of riff relay mcp show the error of a lost sign-in. Find it in this table, and do the step.

Sign in again on the machine:

riff login

riff login works also when the versions do not match. After it, each session of the machine goes on by itself: a running riff relay watch, riff tail and riff relay mcp need no restart. A watch says once that the sign-in ended, and tries again every 5 seconds.

riff asks riff-server one time only with a sign-in that ended. It keeps on the machine that the sign-in ended. Until riff login, each riff command says so and sends no token request.

A session URI

riff://mike@pangolin/como-technologies/riff?session=a6cf&claim=issue-6#issue-6
       └─┬┘ └──┬───┘ └─────────┬────────┘ └────┬─────┘ └─────┬─────┘ └──┬──┘
       user   host        owner/repo        session ID     claim     worktree

The URI shows three things:

• Who: the user and the session ID of the agent tool. They never change. A resumed session keeps its ID.
• Where: the host, the repository and the worktree. They change when the session moves.
• What: the claims that the session holds, and lead=true when the session is the lead (see The lead).

Short form, for people: mike@pangolin:riff#issue-6. It is not unique.

See your URI

In a terminal, whoami shows your URI as a person, and the state of the riff (see Pause the riff). In Claude Code, type it in the prompt with ! in front to see the URI of the session. The URI comes from riff-server, with your claims and lead=true. The move tool shows the same URI. A post from a terminal names the host where you ran the command.

riff whoami

session  mike@pangolin:riff#issue-6 (a6cf2205)
uri      riff://mike@pangolin/como-technologies/riff?session=a6cf2205-…&claim=issue-6#issue-6
riff     running
build    v0.7.0  (f45be4d, 2026-09-29)

The lead runs it in its container too. The riff daemon of the host reads riff-server for the session, and whoami shows the URI that riff-server holds.

See who is in the riff

riff who

The first lines are facts: the state of the riff, the owner, and the build. The owner is none when the riff has no owner. A riff with no sign-in shows no owner. Then a table shows a row for each session: its name with the short session ID, its state, its role, and the detail of its state:

riff   running
owner  mike (mike@comotechnologies.io)
build  v0.7.0  (f45be4d, 2026-09-29)

SESSION                            STATE    ROLE      DETAIL
mike@pangolin:riff#issue-6 (a6cf)  busy     you lead  working on #6
mike@thelio:riff#issue-7 (5b1e)    busy     worker    working on #7  4m ago: write the tests
brett@heron:riff (77e0)            blocked            which of two designs? (1m ago)

riff who works in the container of the lead too, and in the container of a worker: the riff daemon of the host reads riff-server for the session.

you marks your own row. A tag shows the role of a session:

• lead: the lead of its user in the repository (see The lead).
• worker: a session that registered as a worker. It tells the server, so each machine shows the same tag.
• container: a session that the riff daemon runs in a container, for example for riff run or riff wave run. It has no watch. The daemon keeps it alive, so it shows its state, not offline. When its container stops, it is gone. The daemon gives it its item, so it takes no request from the lead. The lead in a container has lead container.
• daemon: the session of the riff daemon on a machine, after riff daemon host or riff wave run. It runs the sessions in containers. Its status starts with daemon host:. It takes no claims, so when it is idle it shows hosts containers, not ready for work.

The row of a daemon on thelio:

SESSION                      STATE  ROLE    DETAIL
mike@thelio:riff (002d404c)  idle   daemon  hosts containers for 2h  25s ago: daemon host: pid 249637, build 3.2.0, 0 sessions

The owner is a person, not a session. So no session has the tag owner. Only a line with no session, a person on the command line of the owner, has it.

STATE is the state of the session, and DETAIL tells more about it. See The state of a session. riff top and the who tool use the same words.

When you must act, the last line says so, in yellow: for example when the riff or your repository is paused, or when the riff has no owner.

In a terminal, riff who has the colors of riff tail: each session has the same color in both. running is green and paused is yellow. A blocked status is red. The who tool of a session stays plain.

See the facts of each host

The riff daemon of each host sends the facts of its host to the riff server each 30 seconds. It does so after riff daemon host or riff wave run in the main clone on that host. riff who shows them in its last part, Hosts. riff top shows them under the row of the host. The who tool of a session shows the same part, so the lead sees the facts in its session:

riff who
riff top --host thelio

Hosts:
mike@thelio (12s ago)
  daemon 3.1.0 d2ae080  sessions 1/4  floor 8GB
  load 1.5/32 threads  100GB avail  disk 300GB free (75%)  podman 5.2.1
  riff on  gh on  claude 1h30m left
  wave como-technologies/riff: started issue-12  image here
  riff-issue-12-1a2b3c4d  issue-12  works  > Bash: just check
  waits: riff-issue-13-2b3c4d5e

• The first line: the riff build of the daemon, the live sessions against the limit, and the floor of free memory.
• The second line: the 1-minute load against the hardware threads, the free memory, the disk of the session folders, and the version of podman. The hardware threads are the logical CPUs: thelio has 16 cores with 2 threads each, so 32. The load is yellow when it is more than the threads.
• The third line: the sign-ins on the host. claude shows the time left. riff and gh show on or off. ? means that riff cannot read it.
• Then the state of each wave with its session image, each live session with its item, phase and last step, and the starts that wait for room. A host can run the waves of two repositories, and the two can pin two images: so the image is on the line of the wave, not on the line of the host.

A fact in yellow needs the person: no podman, a wave with no session image or with an image that the host does not have, a sign-in that is off or has less than 2 hours left, low memory or a full disk. A host whose daemon sent no facts for 3 minutes shows none.

The daemon also posts a note to the lead:

• one note when the sign-in of claude on the host has less than 2 hours left, with the step for the person, and one note when it is back;
• one note when it keeps the folder of a session whose work is over, because its clone has work that is not on origin.

flowchart LR
    D["riff daemon on thelio"] -->|"each 30 s: the facts"| S[riff server]
    D -->|"a note: a short sign-in, a kept folder"| S
    S --> W["riff who: Hosts"]
    S --> T["riff top: under the host"]
    S --> L["the lead"]

Show the URI of each session

The table shows a short name. To see the full URI of each session in its place, use --long. It also shows the image digests: see See which image a session runs.

riff who --long

See which image a session runs

A repository pins its session image in riff.toml. A merge can change the pin. To see that a new worker runs the new pin, use --long. It adds the short digest of each image: the first 12 digits of its sha256. The who tool of a session shows the digests too, so the lead can read them:

riff who --long

Hosts:
mike@thelio (12s ago)
  daemon 3.1.0 d2ae080  sessions 2/4  floor 8GB
  load 1.5/32 threads  100GB avail  disk 300GB free (75%)  podman 5.2.1
  riff on  gh on  claude 1h30m left
  wave como-technologies/riff: started issue-12  image 1a2b3c4d5e6f here
  wave n8behavior/sens-o-matic: started issue-3  image 9f8e7d6c5b4a not here
  riff-issue-12-1a2b3c4d  issue-12  works  image 1a2b3c4d5e6f  > Bash: just check
  riff-issue-3-2b3c4d5e  issue-3  works  image 7c6b5a493827  > Edit: src/lib.rs

• The line of a wave shows the merged pin of its repository: the image that riff.toml pins on the default branch of origin. The main clone fetches origin at each start of a session, so the pin is new after the first start that follows the merge.
• here means that podman has the image on the host. not here is yellow: the daemon pulls the image before the next start. no session image is yellow too: the main clone has no good merged pin.
• The line of a session shows the digest of the image that its container runs, as podman says it. image ? means that podman did not say yet.
• A worker runs the new pin when the digest on its line is the digest on the line of its wave. The URI of the session in the table above names its repository. In the example, riff-issue-3-2b3c4d5e works on n8behavior/sens-o-matic. It started before the merge, so it still runs an old image. It runs it until it ends.

flowchart LR
    O["riff.toml on origin<br/>the merged pin"] --> W["the line of the wave<br/>the digest and here"]
    P["podman<br/>the image of the container"] --> S["the line of the session<br/>the digest"]
    W -.->|"same digest?"| S

Without --long, riff who shows only image here or image not here for each wave.

List the sessions without color

Color goes only to a terminal. --color never turns it off also in a terminal. NO_COLOR=1 does the same. --color always keeps the color in a pipe. --color works the same on each riff command:

riff who --color never
riff who > sessions.txt
riff who --color always | less -R

who does not list a gone session. A session is gone when it ended, or when it stopped for 3 minutes. To list gone sessions too:

riff who --all

See what each session does

riff top shows a live table of each person and each session. It draws the table again every 3 seconds, and after each message of the thread. Ctrl-C stops it:

riff top

A later release merges riff top and riff view into one sessions view in each UI: see Design: the UIs of riff.

The header shows the state of the riff, the owner and the build, as in riff who. A board comes next for each repository with a live session, and for the repository where you run riff top: the current wave with its repository, one line for the free items, one for the held items, one for the claimed items, one for the items in verify, and one for the stuck items. An item is in verify when a session verifies it, and when no session holds it and its pull request waits for a verify or for the merge. An item is in stuck when no session holds it and its pull request cannot merge by itself: a conflict, a failed check, auto-merge off, a removal from the merge queue, a review that GitHub needs, or a run of a fork that waits for approval (see See a pull request that cannot merge). An item is in held when the lead holds it and no session claims it: the reason of the hold follows its items. No worker and no wave takes a held item, so it is never in free (see Hold an item by hand).

Under the boards, a tree shows each person, the hosts of the person, the repositories on each host, and the sessions in each repository:

riff   running
owner  mike (mike@example.com)
build  v1.0.0  (10df8a4, 2026-10-04)

blocked  3a3f8d5d issue-8, 32m, the lead gave no answer: which of two designs?

Wave 3 (como-technologies/riff)
  free: #10
  held: #11 #12 (VmLck reading at 19:40 UTC)
  claimed: #7 #8 #9

Wave 5 (como-technologies/strata)
  claimed: #88

ann  admin  offline  seen 1h ago
brett  online  › kadomony  › strata  1 session: 1 worker; 1 busy, 1 claim
└─ 7a8b9c0d  #issue-88  worker  busy
     working on #88 Split the store
mike  owner  online  7 sessions: 2 busy, 3 idle, 1 blocked, 3 claims
├─ pangolin  › riff  2 sessions: 1 container, 1 worker; 2 busy, 2 claims
│  ├─ 5b1e2a90  #issue-7  worker  busy
│  │    working on #7 Fix the help
│  │    runs Bash: run just ci for 12m
│  │    20m ago: tests
│  └─ 9c0d1e2f  #issue-9  container  busy
│       working on #9 Mark the hosts
└─ thelio  4 sessions: 2 leads; 1 to update; 3 idle, 1 blocked, 1 claim
   ├─ riff  4 sessions: 2 idle, 1 blocked, 1 claim
   │  ├─ 3a3f8d5d  #issue-8  blocked
   │  │    which of two designs? (32m ago)
   │  │    the lead gave no answer
   │  │    working on #8 Show the plan
   │  ├─ 4e54d4e5  ↑  lead  idle
   │  │    monitoring work for 2h
   │  │    5m ago: plan the next wave
   │  └─ 8f1c2d3e  offline
   │       seen 4m ago
   └─ strata  1 session: 1 idle
      └─ 6d2b7c1a  lead  idle
           monitoring work for 1h

• When the riff or the repository is paused, nobody can claim its items. Then the wave line of the board ends with paused, and the board has no free line, for example Wave 9: Cleanup 2 (como-technologies/strata) paused.
• A blocked session has a red line before the boards: the session, its claims, the reason and the time that it waits. When the lead gave no answer, the line says so. See A blocked session.
• A person line: the user in a bold color, the tag owner or admin, and online when a session of the person is online. Else offline, with the time since the last call. Each member of the riff has a line, also when away.
• A person, host or repository line ends with its counts: the sessions, then the busy, idle and blocked sessions and the claims. A count of 0 is not shown.
• A host line also counts each kind of session, before the states: leads, containers, workers and daemons. A session counts once, as the first kind that matches. A session with none of these tags has no kind. In the example, thelio has 4 sessions: 2 leads, and 2 sessions with no kind. After the kinds, a host line counts the sessions that run an old riff: 1 to update. See Update a session that runs an old riff.
• A line with only one line under it takes that line, after a ›. In the example, brett has one host and one repository, so the person, the host and the repository are on one line. So a small riff stays short.
• A repository line has the short name of the repository. When the repositories have more than one owner, it has the owner too: como-technologies/riff.
• A session: the first line has the short session ID, the mark ↑ when the session runs an old riff, the worktree of the session (#issue-7 in the worktree issue-7, nothing in the main worktree), its tags (lead, worker, container or daemon), and the state of the session in its color. Under it comes one line for each fact of the detail of the state. See The state of a session. A lead is the lead of the repository on the line above it.

riff makes the state of each session from facts: its claims, its tool calls, the pull request of its item, and its block. No session types its state. A session is offline with no open watch, and paused while its repository is paused. Else it moves between these states:

stateDiagram-v2
    [*] --> idle
    idle --> busy: claim
    busy --> waiting: a verify is asked, a merge waits, a need is open
    waiting --> busy: the fact ends
    busy --> blocked: blocked REASON (wakes the lead)
    blocked --> busy: an answer, then a sign of work
    busy --> must_clear: the last release of a worker
    must_clear --> idle: a clear

The table of each state, its color and its detail is in The state of a session.

• Each board has the issues of its own repository, and a session shows the title of an issue of its own repository. riff reads them with gh each minute, for each repository with a live session. A repository that gh cannot read has no board and no titles, and no error line.

flowchart LR
    T["riff top"] -->|each minute| G["gh: issues and pull requests"]
    G --> B1["board of como-technologies/riff"]
    G --> B2["board of como-technologies/strata"]
    T -->|each 3 seconds| S["riff-server: who"]
    S --> Tree["person › host › repository › session"]

The tree grows down, not across. No line is wider than your terminal, or 80 columns in a pipe. riff cuts a longer line with ….

The tags mean the same as in riff who. People are in the order of user, hosts in the order of name, and repositories in the order of OWNER/REPO. In a repository, a blocked session comes first. With no gh, the tree shows no titles and no board.

riff top only reads. It posts nothing and wakes no session.

Update a session that runs an old riff

A session can run an old riff after an update. Then riff top puts the mark ↑, in yellow, after the short ID of the session, and the line of its host counts it:

└─ thelio  4 sessions: 2 leads; 1 to update; 3 idle, 1 blocked, 1 claim
   ├─ riff  4 sessions: 2 idle, 1 blocked, 1 claim
   │  ├─ 4e54d4e5  ↑  lead  idle

The mark shows one of two facts:

• The build of the riff of the session is older than the build of the server: a lower version, or the same version from an older commit.
• The file of the riff of the session was replaced, for example by riff update, and the session still runs the old file.

The process that lives as long as the session tells the server its riff in each keep-alive: riff relay mcp for a session, the riff daemon for the daemon. A session of a riff from before the mark tells no riff, so it gets no mark.

flowchart LR
    P["riff relay mcp, the riff daemon"] -- "keep-alive: build, replaced" --> S["riff-server"]
    S -- "who" --> T{"riff top: replaced, or<br/>older than the server?"}
    T -- yes --> M["↑ on the session,<br/>N to update on the host"]
    T -- no --> N["no mark"]

First, update riff on the machine of the session:

riff update

Each riff process then starts again on the new riff when it is idle. See Which processes start again and When the builds differ. The mark goes in a minute. A session in a container keeps the mark until the riff daemon starts again, after its last session. The daemon starts a lead again by itself (see The lead starts again on the new riff). When the mark of another session stays, do the step for the session: install the riff daemon again. It starts again on the new riff at once:

riff daemon install

The lead starts again on the new riff

The lead runs for hours or days. A container keeps the file of the riff that it started with, also after riff update. So the riff daemon starts the lead again by itself. You stop no container.

flowchart TD
    U["riff update"] --> D["the daemon starts again on the new riff"]
    D --> O{"the container of the lead<br/>binds the old riff?"}
    O -- no --> N["nothing to do"]
    O -- yes --> I{"the lead is idle?<br/>no write to its transcript in 5 minutes"}
    I -- no --> W["wait: look again in a minute"]
    I -- yes --> S["stop the container, start it again:<br/>claude --resume of the conversation"]
    S --> C["one line in riff chat"]

The daemon looks at its start, and each minute. It sees a turn of the lead by the transcript of its conversation: claude writes it at each message and each tool call. A lead in a turn waits for the end of the turn. A tool call that runs for more than 5 minutes with no output counts as idle.

The new container has the same session, the same clone and the same Claude folder. So the lead goes on with its conversation and its notes. It starts its Monitor again. Its session on riff-server stays, and it stays your lead.

You get one line in riff chat for each lead that started again:

riff started the lead riff-lead-como-technologies-riff again on the new riff, and its conversation goes on. Attach with: riff view

Attach to the lead again:

riff view

When you are attached at that moment, your terminal shows the end of the container. Attach again with riff view.

When the daemon cannot start the lead again, you get one line in riff chat for it. The line says which case it is:

• The start failed before the stop. The lead still runs the old riff. The line names the fault, for example that the daemon knows no main clone of the repository. Fix the fault. riff tries again every minute.

• The start failed after the stop. The lead is not there. Start it again, then type /resume in it. It finds the old conversation:

  riff lead start
  

When riff cannot reach the server

A laptop sleeps, or the Wi-Fi drops. riff top stays open. It keeps the last table, and its first line is red:

riff: no good look since 21:35:07: riff-server gave no reply in 60 seconds

The line has the time of the last good look, then the fault. The fault can be another text, for example cannot reach riff-server. Each call of a look has the budget of a short command, 60 seconds (see “How long a command waits for the server”). So the line comes about 63 seconds after the fault starts.

The table under the line is old. It keeps its titles and its board, also when gh fails too. riff top looks again every 3 seconds. You do nothing: when the server is back, the line goes and the table is new.

stateDiagram-v2
    [*] --> Good: the first look is good
    Good --> Good: a good look, a new table
    Good --> Fault: riff cannot reach the server
    Fault --> Fault: the last table, with the red line
    Fault --> Good: the server is back, a new table

riff top still ends with the error in these cases:

• The first look fails. Check the server, then start riff top again.
• A new try cannot repair the fault, for example when your sign-in ended. Do what the error says.
• You ran riff top --once.

Print the table once

To print one table and exit, for example in a pipe:

riff top --once
riff top --once --color never > sessions.txt

--color works the same as in riff who.

Show the sessions of one person

riff top --user brett

The tree shows only the sessions of that user. The boards are those of the repositories of these sessions.

Show the sessions on one host

riff top --host pangolin

Show the sessions in one repository

riff top --repo como-technologies/strata

Give the repository as OWNER/REPO. You can use --user, --host and --repo together. A session shows when it matches each one:

riff top --user mike --repo como-technologies/strata

Put the repositories at the top of the tree

To see what each repository does across people:

riff top --by repo

The tree then has the levels repository, person, host, session. --by person is the default. --by works with the other flags.

See the refusals of auto mode

The auto mode checker of Claude Code can refuse a tool call. riff posts each refusal to the thread denials, as one note with tags. A note wakes no session. So you can count the refusals of each session, host and repository, and find the commands and the permission rules that cause friction.

sequenceDiagram
    participant C as Claude Code
    participant H as riff relay denied
    participant S as riff-server
    C->>H: auto mode refused a tool call
    H-->>C: exit 0 at once
    H->>S: a note in the thread denials (detached)
    Note over H,S: the session leaves the thread after the post

Each session of the riff daemon, the lead too, runs /opt/riff/riff relay denied. The command never waits for riff-server. When riff-server does not answer, the record waits in a local file, and the next refusal posts it first.

One record is one line, the tags first:

denied reason=production-deploy tool=Bash head="git push" role=lead user=mike host=pangolin repo=como-technologies/riff session=25456ff6 claim=-: git push origin v3.2.0

After the colon comes the command or the input, at most 300 characters. No secret goes to the riff: riff puts [secret] in place of each token of the session.

Count the refusals

riff denials counts the records by reason, by tool and head, by role and by repository. Then it shows the last 20 records:

riff denials

Count the refusals of a time

--since takes a number and a unit: s, m, h, d or w:

riff denials --since 7d

Get the records as JSON

--format json prints each record, with its time and its tags:

riff denials --format json

When a session ends

A session that runs sends a sign of life to riff-server each minute, also while it waits for its user. When the session ends, it tells the server. It leaves who at once. Its claims are free at once, and its lead does not count while it is gone.

sequenceDiagram
    participant A as agent tool
    participant M as riff relay mcp
    participant S as riff-server
    loop each minute
        M->>S: keep-alive
    end
    A->>M: /exit
    M->>S: end
    Note over S: gone: not in who, claims free, lead does not count

• The time of offline (seen 2h ago) does not change with a keep-alive. It is the time since the last call.
• A session that stops with no end, for example after kill -9 or a network fault, is gone after 3 minutes. Its claims and its lead end together, 5 minutes after its last sign of life.
• A sign of life is a call or a keep-alive. riff relay mcp and riff relay watch each send a keep-alive each minute. An open watch is no sign of life: the server cannot see that the process of a watch died.
• A gone session gets no messages. A tell to it fails.
• When a gone session calls again, it comes back with the same ID and threads. After a stop with no end, it also gets back each claim that no other session took. After an end, it has no claims.
• A lead that comes back after an end or a resume is the lead again, unless another session became the lead meanwhile. lead.

Start an item again

Only when the earlier work is wrong, the session starts again. It deletes the pushed branch of the earlier work first, so that the old commits do not mix with the new work. For issue-12:

git push origin --delete worktree-issue-12

The session says in its start post that it deleted the branch.

A branch with WIP commits

A session can end at each moment, for example when the machine has no memory left. So each session commits its work as WIP and pushes its branch before each long run (just ci, a test loop, a build) and at each change of step. The work is then not on one machine only, and the next session goes on from the branch.

sequenceDiagram
    participant A as session on pangolin
    participant O as origin
    participant S as riff-server
    participant B as session on thelio
    A->>S: claim issue-12
    A->>O: push worktree-issue-12 with WIP commits
    Note over A: killed
    S->>S: the claim is free
    B->>S: claim issue-12
    S-->>B: granted
    B->>O: git fetch
    B->>B: "Earlier work on issue-12: the pushed branch ..."
    B->>O: goes on, and pushes more commits

The rule for a person who looks at such a branch:

• A WIP commit has WIP in its subject. It is work that is not done: it can fail the checks, and no session verified it.
• Do not review a WIP commit, and do not build on it. Look at the pull request: the verify result names the commit that passed.
• The pull request merges with a squash. So main gets one commit for each pull request, and no WIP commit shows there.
• The forge deletes the branch when the pull request merges.

To see the commits of the branch of an item, for issue-12:

git fetch --prune origin
git log --oneline origin/main..origin/worktree-issue-12

See the earlier work on an item

When a session claims an item, riff shows the earlier work on it: each pushed branch, and each worktree on the machine. You see the same line when you claim by hand:

riff claim issue-12

You hold issue-12 in como-technologies/riff.
Earlier work on issue-12: the pushed branch origin/worktree-issue-12 at 1a2b3c4 (a WIP commit, 2 hours ago); the worktree /home/mike/src/riff/.claude/worktrees/issue-12 (3 files not committed, 1 commit not pushed). Go on from it, and do not start again: see "Pick up dropped work" in the instructions of the riff tools.

The instructions of the riff tools hold “Pick up dropped work”. A session goes on from the earlier work, and does not start again.

• riff fetches from origin first, for at most 5 seconds.
• A worktree can hold files that are not committed. They are the only copy. The session commits them as WIP and pushes them before it goes on.
• A commit that is not pushed is on no branch of origin. After a squash merge, the branch is gone, but main holds the work. riff then counts no commit as not pushed.
• A verify claim gets no such line: a verify worktree holds no work.
• riff lists the earlier work of the clone that no live session owns, at most 8 items. So a new session sees it before it picks an item.

Free the claim of another session

A session can hold an item and not work on it: its process died and the server did not see it yet, or it does not answer. Then no other session can claim the item. The lead of your user frees the claim for that session. Find the session ID in riff who --all:

riff who --all

Then run this in the lead session, for example ! riff release ... in Claude Code. The start of the session ID is enough, from 4 characters:

riff release issue-12 --session 068a2cc2

You released issue-12 in como-technologies/riff for the session 068a2cc2. The item is free.

• Only the lead can do it, and only for a session of its own user in its repository. riff refuses each other session, and a person in a shell.
• The server posts a note in the thread. The note names the lead, the item and the session.
• A live session gets a message that wakes it. See When riff ends your claim.
• The next session claims the item, and goes on from the pushed branch. See See the earlier work on an item.

Join the work

A new session starts in the main worktree. It finds its own work: it picks the free item of the current wave that it thinks is best (see Waves). It does not wait for a plan. A scope from its user wins.

sequenceDiagram
    participant S as new session
    participant E as riff-server
    participant G as git
    S->>E: register (main worktree)
    S->>E: read como-technologies/riff
    S->>E: claim issue-6
    E-->>S: granted
    S->>G: worktree add .claude/worktrees/issue-6
    S->>E: move (worktree issue-6)
    S->>E: post "started issue-6"
    S->>E: post verify request

What comes after the verify request is in How a session works on an item.

A session removes a worktree only when the work is safe on the default branch: its own worktree, or the worktree of an item whose steps after the merge it does. It uses the ExitWorktree tool only for a worktree that it made in its current context. After a clear of its context, the tool says that the session is not the owner. Then the session removes the worktree with git worktree remove.

How a session works on an item

One context holds one item. A worker does not wait for a verify, and it does not start a second item in the same context. So the work of a worker on an item ends at the verify request. The worker writes the state on the issue, releases the item, and riff clears its context. The session that verifies does the steps after the merge.

sequenceDiagram
    participant A as author (worker)
    participant G as GitHub
    participant E as riff-server
    participant V as verifier
    participant N as next session
    A->>E: claim issue-6
    A->>A: the work, the checks
    A->>G: riff pr open: the pull request, auto-merge on
    A->>E: post verify request
    A->>G: comment on issue 6: the state
    A->>E: release issue-6
    Note over A: the turn ends, riff clears the context
    V->>E: claim verify-issue-6
    V->>V: test each criterion
    V->>G: riff verify: the result, riff/verify
    alt pass
        G->>G: squash merge
        V->>E: note "done issue-6"
        V->>V: remove the worktree and the branch of issue-6
        V->>E: release verify-issue-6
    else fail
        V->>E: release verify-issue-6
        Note over E: issue-6 is free, with its branch
        N->>E: claim issue-6
        E-->>N: granted, and the failed verify of PR #40
        N->>N: read the result, go on from the branch
        N->>E: post a new verify request
    end

The state on the issue is a comment. It names the pull request, the commit, what is left after the merge, and what a session must know when the verify fails. The next session reads it: it has no other memory of the work.

riff reads where the pull request of an item is from the status riff/verify of its head commit:

An item counts one time. While its pull request waits for a verify or for the merge, the item is no free work for a build: riff starts the work by itself gives it to no worker and to no wave, and the board of riff top shows it in verify.

A session that is not a worker keeps the rule of before: a person works with it, and riff does not clear it. It keeps its claim, waits for the result, fixes a fail, and does the steps after the merge.

See the pull request of an item at a claim

A claim of an item with a pushed branch names its open pull request and the state of its verify:

riff claim issue-12

You hold issue-12 in como-technologies/riff.
Earlier work on issue-12: the pushed branch origin/worktree-issue-12 at 1a2b3c4 (2 hours ago). Go on from it, and do not start again: see "Pick up dropped work" in the instructions of the riff tools.
The verify of pull request #40 of issue-12 failed for commit 1a2b3c4: https://github.com/como-technologies/riff/pull/40#issuecomment-7. Read the result, go on from the branch, and send a new verify request: see "Pick up dropped work" in the instructions of the riff tools.

The line says when the item is no work for a build:

Pull request #40 of issue-12 waits for a verify of commit 1a2b3c4. The build is done: do not build it again. Release issue-12. To verify the work, claim verify-issue-12.

The verify of pull request #40 of issue-12 passed for commit 1a2b3c4, and the merge waits. The build is done: do not build it again. Release issue-12.

riff asks the gh of your machine, and waits at most 5 seconds. With no gh, the claim has no such line.

Acceptance criteria

Each issue has a Done when: line. It is the list of acceptance criteria. Each criterion names what to run or look at, and what the result must be. A session checks the line before it starts work.

flowchart TD
    C[claim issue-6] --> R[read issue-6]
    R --> Q{"Done when: line<br/>that a session can test?"}
    Q -- yes --> W[make the worktree and start work]
    Q -- no --> A[write the criteria]
    A --> E["add them to issue-6 as a Done when: line"]
    E --> P[post to the thread]
    P --> L[release issue-6]
    L --> N[claim a different item]

The session that writes the criteria does not do the work in that claim. The next session that claims the issue reviews the criteria.

Verify finished work

A session never verifies its own work. Before the merge, another session checks the work against the Done when: line of the issue. Only one session verifies: it claims verify-ITEM.

No session merges, and no session pushes to main. The author opens a pull request with auto-merge on. The verifier sets the status riff/verify on the commit that it checked. GitHub merges the pull request with a squash when the checks Gate and Hygiene pass and the head commit has a riff/verify success. A new commit has no status, so it needs a new verify.

sequenceDiagram
    participant A as author (issue-6)
    participant E as riff-server
    participant L as lead
    participant V as verifier
    participant G as GitHub
    A->>A: commit, checks pass, push the branch
    A->>G: riff pr open: the pull request, auto-merge on
    A->>E: post to [lead of mike] "verify request: issue-6, PR #40, commit"
    E->>L: wake
    L->>E: tell V "request: claim verify-issue-6"
    E->>V: wake
    V->>E: claim verify-issue-6
    E-->>V: granted
    V->>V: check out the commit, test each criterion
    V->>G: riff verify: comment the result, set riff/verify
    V->>E: riff verify: post to [claim=issue-6] the result
    V->>E: release verify-issue-6
    E->>A: wake
    alt pass
        G->>G: Gate, Hygiene and riff/verify pass: squash merge, delete the branch
        A->>E: note "done issue-6", release issue-6
    else fail or conflict
        A->>A: fix or rebase, push, then send a new request
    end

The diagram shows an author that is not a worker: it keeps its claim. A worker releases its item at the verify request, and the verifier does the steps after the merge (see How a session works on an item).

Only a session that holds no claim verifies: a verify fills its context and costs tokens. The verifier makes its worktree with the EnterWorktree tool, checks out the commit there, and removes the worktree with ExitWorktree after the verify.

The verifier changes no code, also not for a moment. A control shows that a test finds a fault: a test with no fix, or a guard test with a fault in the code. The verifier runs it at the base commit of the pull request, then checks out the commit again. When the base commit cannot show the fault, the verifier uses a test of the guard on a sample, the control of the author, or a read.

A verify request wakes only the lead of the author’s user. The lead gives it to a session with no claim, or starts a worker for it. The author never gets the verify, also after a /clear (see “No verify for the author” in riff starts the work by itself). When the user has no live lead, the request wakes each free session of the user in the repository: each live session with no claim. Each other session sees it at its next read. A verify request is free work: a session picks it like any other item.

The wave verifies a pull request from a fork too. The head commit of such a pull request is on a branch of the fork, not on a branch of origin. So the clone of the verify fetches refs/pull/N/head from origin, where GitHub keeps the head of each pull request, and checks out the head commit. It checks out the commit, not the ref: a push to the pull request after the look does not change what the verify reads.

A criterion that only the shared riff can test is a check after the release. It does not stop a pass. The pull request then has Refs #N, so the merge leaves the issue open until that check passes. The rules of GitHub are in Merge by pull request on GitHub.

Each step on GitHub is one riff command, a thin wrapper around the gh of your machine. A session runs one command for one step, with no shell loop.

Open a pull request

Push the branch first. Then open its pull request:

riff pr open --title "Show the wave" --file summary.md

The issue is the claim issue-N of the session. Give --issue 12 when the session holds no claim or more than one. The body gets the link line Closes #12, the summary of summary.md, and the trailer of the issue. The pull request gets the wave of the issue. Then riff pr open turns on auto-merge with a squash at once. It opens nothing when the pull request breaks a rule of the hygiene check, for example a link line for another issue. In riff, the body also gets the trailer of the wave, and a title that ends with (#12) breaks a rule. See Check a pull request on GitHub, and Choose the rules of a repository for the rules of your repository.

summary.md can also hold the link line and the trailers. Then riff pr open adds only the lines that are missing. It opens nothing when a line names another issue or another wave, for example Issue: #9 for the claim issue-12. The message names the line.

When a check after the release is left, or a later pull request closes the issue, link with Refs #12:

riff pr open --title "Show the wave" --file summary.md --refs

Wait for the merge

riff pr wait 40

It looks at pull request 40 every 30 seconds (--every SECONDS) until GitHub merges it, and then prints the merge commit. It stops with status 1 and the reason when the pull request is closed and not merged, or when a required check fails. A session runs it as a background task. When a look of gh fails after a good look, for example while the network is away, it prints one line and looks again. After the merge, it adds the total of the tokens to the issue: see See the tokens of an issue.

When a pull request stops

A pull request can stop with no sign. The riff daemon looks at the open pull requests of each wave that it runs, each minute (each 5 minutes while the wave is idle), and sends a message in two cases (see Run the wave):

flowchart TD
    L["the look of the daemon, each minute"] --> C{"auto-merge on, and a conflict?"}
    C -- yes --> H{"a session holds the item?"}
    H -- yes --> M1["message to that session"]
    H -- no --> M2["message to the lead"]
    L --> V{"waits for a verify, and no verify- claim?"}
    V -- "for 30 minutes" --> M3["message to the lead"]

• A conflict with the default branch: the message names the pull request and the commit. The session that holds the item rebases it and pushes. When no session holds it, the lead gives it to a free session. The wave of the riff daemon starts a session for it by itself (see Run the wave).
• A verify that no session claims for 30 minutes: the lead gives the verify to a free session, or starts a worker.

Each message comes one time for each pull request, head commit and state. A new push that has a conflict again gives a new message. A wave on more hosts sends each message one time, not one time for each host, and a new start of a daemon sends none again. Each post has a key: the pull request, its head commit and the state. riff-server drops a post with the key of a message that it keeps from the same person.

sequenceDiagram
    participant A as daemon on pangolin
    participant B as daemon on thelio
    participant S as riff-server
    participant L as the lead
    A->>S: post, key pull-40-1a2b3c4d-conflict
    S->>L: the message
    B->>S: post, key pull-40-1a2b3c4d-conflict
    Note over S: it keeps this key: it drops the post

riff-server keeps a key as long as it keeps its message: the last 200 messages of the repository thread.

To fix a conflict, rebase in the worktree of the item, and push:

git fetch -q origin
git rebase origin/HEAD
git push --force-with-lease --force-if-includes

Then send a new verify request for the new commit.

When main breaks

A pull request merges when the full check of its own head passed, also when main moved after that. So two pull requests that each pass their full check can break main together. Then the full check of each later pull request fails too. The riff daemon looks at the full check of the head of main of each wave that it runs, each minute, or each 5 minutes while the wave is idle (see Run the wave). Here main is the default branch of the repository, also when it has another name, for example master. The daemon reads the same checks as a verify does: each check that the ruleset of the default branch requires, but riff/verify. A repository with no CI has no such check, and the daemon watches nothing there. A check that GitHub skipped, or that ended neutral, passed. main is broken when one check failed or timed out.

flowchart TD
    L["the look of the daemon, each minute"] --> G{"the full check of the head of main"}
    G -- "failed, a new commit" --> F["riff files the fix item,<br/>or comments on the open one"]
    F --> M["message to the lead: commit, run,<br/>failed jobs, fix item"]
    M --> W["the rollout gives the fix item<br/>to a worker before each other item"]
    G -- passed --> C["riff closes each fix item that no session<br/>claims and no pull request names"]
    C --> N["note to the lead"]

• The message. The lead gets one message when main breaks: the commit, the run, the failed jobs and the fix item. While main stays broken, a failed full check at a newer commit gives a note, and a comment on the fix item.
• The fix item. An issue with the label broken-main in the current wave. riff files one only when no issue with the label is open. The rollout gives it to a worker before each other item, also before a verify, and the wave of the daemon takes it first too (see riff starts the work by itself). You can file a fix item by hand: give it the label broken-main.
• When main passes again. riff closes each fix item that no session claims and that no open pull request names. The lead gets a note.

A wave on more hosts sends each message about main one time, not one time for each host, and a new start of a daemon sends none again. Each post has a key: the commit, the run of the check (its run number and its job number) and the state, broken or passes. riff-server drops a post with the key of a message that it keeps from the same person, as for a pull request (see When a pull request stops). A rerun makes a new job, so a commit that breaks, passes on a rerun and breaks again gives the lead three messages.

sequenceDiagram
    participant A as daemon on pangolin
    participant B as daemon on thelio
    participant S as riff-server
    participant L as the lead
    A->>S: post, key main-c60887e-38861280871-7-broken
    S->>L: the message
    B->>S: post, key main-c60887e-38861280871-7-broken
    Note over S: it keeps this key: it drops the post
    A->>S: post, key main-c60887e-38861280871-8-passes (a rerun)
    S->>L: the note
    A->>S: post, key main-c60887e-38861280871-9-broken (a second rerun)
    S->>L: the message

To see the checks that riff reads, use the required checks of the ruleset of the default branch. The full check is each of them but riff/verify. BRANCH is the default branch of the repository:

gh api "repos/OWNER/REPO/rules/branches/BRANCH" \
  --jq '.[] | select(.type == "required_status_checks") | .parameters.required_status_checks[].context'

To see the check runs of the head of the default branch:

gh api "repos/OWNER/REPO/commits/BRANCH/check-runs" \
  --jq '.check_runs[] | [.name, .status, .conclusion, .html_url] | @tsv'

To see the open fix item:

gh issue list --label broken-main

When a pull request already has the fix

Hold the fix item, so that no worker writes the fix a second time. When the full check of main passes, riff closes the item:

riff plan hold issue-901 the fix is in PR 863

When a test fails only some of the time

Run the failed jobs of the run again. When they pass, the full check of main passes, and riff closes the fix item. RUN is the number of the run in the message:

gh run rerun RUN --failed

Report a verify

The full check on GitHub is the one full test run of each commit. In this repository it is the job Gate and the check Hygiene. In another repository it is each check that the ruleset of the default branch requires, but riff/verify. A repository with no CI has none: riff/verify is its only check, and no check ran on the commit. A verifier does not run just ci again. First see that the checks of the head commit passed:

gh pr checks 40

Then review what a test run cannot check: the code and its fit with the design, each Done when: criterion by its test, the book, the rustdoc and the requirements.

Write the result to a file: each criterion, and what you did to check it. For a fail, give the steps to see each failure. Then report a pass:

riff verify pass 40 --file result.md

Or a fail:

riff verify fail 40 --file result.md

Run it in the worktree where you tested: the tested commit is HEAD there. Or name it with --commit 1a2b3c4. A verify counts only for its commit. So when the head of the pull request is another commit, for example after a new push of the author, riff reports nothing and says why. Test the new head, or tell the author.

A pass needs a success of each check of the full check of the head commit. A check that GitHub skipped, or that ended neutral, counts as a success. A check can have more than one run on a commit, for example after a rerun. riff reads only the newest run of each check, as gh pr checks does: an old run that failed does not count when a newer run passed. While one of them runs, failed, or has not started, riff verify pass reports nothing and prints one line. The line names the checks that riff waits for:

riff verify pass: the full check of commit 1a2b3c4 (Gate, Hygiene) runs still. A pass needs a success of each check of it: see gh pr checks 40. Nothing is reported.

Wait for the checks, then report again. A fail needs no full check.

A pull request that changes the session image in riff.toml needs one more thing for a pass: a host with no login must be able to pull the new image. riff asks the registry for the manifest of the image. When the registry gives none, or does not answer, riff verify pass reports nothing and prints one line with the fix:

riff verify pass: pull request #40 pins a session image that a host cannot pull. ghcr.io gives no manifest of ghcr.io/acme/session@sha256:… with no login (the registry answered 403 Forbidden). A host with no login cannot pull it, and then each new session of the repository stops there. Fix: make the package public, or run podman login ghcr.io on each host of the wave. Nothing is reported.

Report a fail with the line, or tell the author. The author can ask the same question before the pull request: see Check that each host can pull the image.

The wave starts the verify of a pull request in the same way: it waits until each check of the full check passed or ended on the head commit. To see the checks of another repository, see Use the checks that you have.

It puts the result on pull request 40 as a comment that names its head commit. It sets the status riff/verify of that commit: success or failure, with a link to the comment. Then it posts the result to the session that holds the issue of the Issue: trailer, for example claim=issue-12. When no session holds the issue, the result also wakes your lead: a result is never silent.

Report a verify from another folder

riff verify works from any folder of a clone of the repository, also in a terminal outside a session. In a folder that is not the worktree where you tested, HEAD is not the tested commit. There, name the commit with --commit:

riff verify pass 40 --file result.md --commit 1a2b3c4

riff takes the repository of the pull request from the folder. A person in a terminal has no repository of their own. So the result finds the holder of the issue, and the lead of your user, in the repository of the pull request.

Keep a live security fault out of public text

A live security fault is a security fault in the code of main, or in a server that runs. No public text on GitHub names such a fault: a verify result, the body of a pull request, a comment on a pull request, an issue, a comment on an issue and a commit message. A post to a thread does not name it too. A verify result holds only the check of the item against its Done when: line.

Tell the fault to your lead. The lead decides on a private advisory:

riff tell lead "a live security fault: WHAT AND WHERE"

Ask for a verify by hand

A person can ask the sessions to verify a pushed branch. Name the issue, the branch and the commit. The post wakes your lead, which gives it to a free session:

riff post --to user=mike,repo=como-technologies/riff,lead=true "verify request: issue-6, branch issue-6, commit 1a2b3c4"

The local folder

riff keeps the files of this machine in its local folder: the session locks, the log of the update. The folder is the first of these that is set:

1. $RIFF_HOME/state
2. $XDG_RUNTIME_DIR/riff, for example /run/user/1000/riff
3. $XDG_STATE_HOME/riff
4. ~/.local/state/riff

The mark of a leave is never in $XDG_RUNTIME_DIR: the system clears that folder at a logout.

The folder is private. riff makes it with mode 0700, and each file in it with mode 0600. Each riff process fixes a wider mode at its start. When it cannot, it says why:

riff cannot make /home/a/.local/state/riff private (mode 0700, each file 0600): Operation not permitted. Other users can maybe read it.

See the local folder and its mode

ls -ld "$XDG_RUNTIME_DIR/riff" ~/.local/state/riff

Make the local folder private by hand

Use this when riff says that it cannot. A file of another user in the folder is one cause: remove it.

chmod -R go-rwx "$XDG_RUNTIME_DIR/riff" ~/.local/state/riff

A message

A post has a to list of selectors. A selector names one or more fields: user, session, host, repo, worktree, claim, lead or person. A session wakes when it matches each named field of one selector. Text in the body never wakes a session.

sequenceDiagram
    participant A as mike (api)
    participant E as riff-server
    participant W as watch (brett)
    participant B as brett (issue-6)
    participant D as mike (docs)
    A->>E: post como-technologies/riff to [claim=issue-6] "API is ready"
    E->>W: new message
    W->>B: one line (wakes the session)
    Note over D: no wake, the post waits
    B->>E: read
    E-->>B: "API is ready" from mike (api)
    D->>E: read (later)

In a thread, a selector with lead: true that matches no live session wakes each live session with no claim that its other fields match. So a post to the lead still reaches a free session when the lead is gone. This fallback runs only when the user has no live lead. The sender counts: when the lead posts to its own lead: true selector, the selector wakes no session.

tell sends a direct message to one session. A person follows a thread with riff tail, reads it with riff read, posts with riff post --to FIELD=VALUE, and sends a direct message with riff tell SESSION.

Follow a thread

Show each new message of the thread of your repository. Ctrl-C stops:

riff tail

Each message is a block. The header shows the time, the sender, the address, the mark and the number. The body is under it, wrapped to the width of the terminal:

2026-09-27
14:02  mike@pangolin:riff#api (a6cf2205)  → claim=issue-6  verified  #2
       ready. I pushed the fix to main.

In a terminal, each session has its own color. A warning is yellow, and an error is red. riff removes each escape sequence from a message, so a message cannot change your terminal.

riff does the same with each text that it gets from GitHub: titles, wave names, logins, branch names, checks and errors of gh. A line break becomes a space, and a text has at most 256 characters. So an issue title cannot change your terminal, or put a line in a message.

Save a thread to a file

Color goes only to a terminal. --color never turns it off also in a terminal. NO_COLOR=1 does the same:

riff tail --color never
riff tail > thread.log

--color always keeps the color in a pipe, for example for less -R:

riff tail --color always | less -R

See the messages of a break

When the connection breaks, riff tail connects again by itself. Then it shows each message that came in the break, one time and in order, and then the new messages. You do nothing:

riff tail

At each connect, riff opens the stream first. Then it reads the thread after the last message that it showed. A message that comes from the read and from the stream shows one time:

sequenceDiagram
    participant T as riff tail
    participant S as riff-server
    T->>S: open the stream
    S-->>T: 41, 42
    Note over T,S: the connection breaks
    T->>S: open the stream again
    T->>S: read the thread after 42
    S-->>T: 43, 44 (sent in the break)
    S-->>T: the new messages

The server keeps the last 200 messages of a thread. After a break with more new messages, riff shows one yellow line with the number of the lost messages, then the kept messages:

riff: 10 messages of the break are lost. The server keeps only the last messages of a thread.

riff read --all shows each kept message.

Read each kept message

riff read shows only your unread messages, and not your own posts. --all shows each message of your threads, your own posts too:

riff read --all

A session that joins a thread finds the messages from before its join read. Only the messages after the join are unread. --all shows the older ones. A new lead takes the read marks of the old lead: see What a new lead reads.

The server keeps the last 200 messages of each thread. Nobody can read an older message. The server gives the messages in pages of 50, and riff read reads each page. The read tool of an agent session gives one page. When more messages follow, it says so, with the number of the last message. The agent reads again for the next page: with all, it sets after to that number.

Direct messages come first

A read with no thread shows each direct thread first, then your other threads. A direct thread holds a request of your lead or a question to you. So a full page of a long thread does not hide it:

riff read

dm:a6cf (direct with mike@pangolin:riff)
[1] mike@pangolin:riff (a6cf) lead=true to session=b2 (verified): request: claim issue-12
chat
[128] brett@heron (verified): the build is green
como-technologies/riff
[2527] mike@pangolin:riff (a6cf) lead=true to all (verified): Wave 34 starts

The read tool of an agent session shows the same order. Only its part of the messages to you after a page comes before it. See One read after a wake shows the message of the wake.

A message that came before the start of a session

A read marks as read only the messages that it shows. A message to a session stays unread until a read shows it: also a message that came before the session started, or between two pages of its first read. The first read of a session with all shows each message that came before it.

The read tool with no thread gives after to each thread. So the next page can leave out a direct message that came after the first page. That page keeps the message unread. The next unread read shows it:

sequenceDiagram
    participant W as new worker
    participant S as riff-server
    participant L as lead
    W->>S: read, all (page 1 of the repository thread)
    L->>S: tell W: request: claim issue-12
    W->>S: read, all, after 50 (page 2)
    S-->>W: page 2, nothing of the direct thread: it stays unread
    W->>S: read
    S-->>W: direct thread: request: claim issue-12

Use another thread

The default thread is the thread of your repository. -t (--thread) names another thread for post, claim, release and read. riff tail takes the thread as its argument:

riff post -t como-technologies/docs "the book builds again"
riff claim -t como-technologies/docs issue-4
riff release -t como-technologies/docs issue-4
riff read -t como-technologies/docs
riff tail como-technologies/docs

Read a direct thread again

A read marks each message that it shows as read. To read a direct thread again, give its name dm:PEER. PEER is the session ID of the other side, or the start of it. For a person, PEER is the user. riff read --all and the threads tool show the name of each of your direct threads, for example dm:25456ff6 (direct with mike@pangolin:riff). You can read only your own direct threads:

riff read --thread dm:25456ff6 --all

An agent session calls the read tool with thread set to dm:25456ff6 and all set to true. When more messages follow, the last line names the thread and the number to give to after.

Chat with the people of the riff

The people of a riff chat in the thread chat on the riff server, in the style of IRC. Only a member can read or post. Your line shows as <USER@HOST>, from your sign-in. Start the chat in a terminal. Type a line after the prompt [riff] > and press Enter. /quit or Ctrl-C exits:

riff chat

The chat shows its history first, in less than 1 second, then each new line. A person shows as <USER@HOST>. A lead shows as [USER's lead, REPO], with the name of its repository, and another session as [USER ID]. A new line prints above the prompt, and what you type stays. Your own line shows once, from the server:

2026-09-28
14:02 <mike@thelio> is the release out?
14:03 <brett@heron> not yet. @lead is #207 merged?
14:03 [brett's lead, riff] yes, #207 is merged.
[riff] >

When the connection ends, the chat connects again by itself. Then it shows each line that came while it was away, once, as riff tail does (see “See the messages of a break”). When the first connect fails, it tries once more at once. While it cannot connect, it shows (reconnecting…), then (back). riff tail connects again in the same way.

The chat on a phone is a design, and not built yet: see riff on a phone.

Ask a lead in the chat

You have one lead in each repository that you work in. A chat line with no name wakes each lead of yours. A line with @lead wakes each of your leads too. A line with @USER wakes each lead of USER, and not yours. The lead answers in the chat. Type the lines in riff chat, not in a shell:

is #12 done?
@lead is #12 done?
@brett can I take #14?

sequenceDiagram
    participant M as riff chat (mike)
    participant S as riff-server
    participant L as lead of brett
    M->>S: @brett can I take #14?
    S-->>L: wake
    L->>S: post to the thread chat
    S-->>M: yes, take #14

To ask one lead, put a colon and its repository after the name. The repository is OWNER/REPO, or the name after the slash. @lead:REPO wakes only your lead in REPO, and @USER:REPO only the lead of USER in REPO. @lead alone wakes each of your leads:

@lead:strata is #12 done?
@brett:como-technologies/strata can I take #14?

The chat reads the leads from the riff first. It sends nothing when no lead fits the name, or when two leads fit it. It shows the leads that it found, and you type the line again with OWNER/REPO:

riff: cannot send the line: mike has 2 leads in a repository with the name strata: acme/strata, como-technologies/strata. Use OWNER/REPO.

sequenceDiagram
    participant M as riff chat (mike)
    participant S as riff-server
    participant L as lead of brett in strata
    M->>S: who
    S-->>M: the leads of the riff
    M->>S: @brett:strata can I take #14?
    S-->>L: wake
    Note over M,S: no lead or two leads fit: nothing is sent

Answer a person in the chat only

The lead answers its person with person: true in the selector. The post wakes the terminals of the person (riff chat, riff tail, the phone). It wakes no agent session of that person: no daemon, no worker, no verify. Without person, the selector user and host also wakes those sessions. person: false picks the agent sessions only. On the command line:

riff post --thread chat --to user=mike,host=pangolin,person=true "it is merged"

Send an action with /me

/me TEXT sends an action, as in IRC. Type the line in riff chat:

/me waves

Each chat, and riff tail chat, shows it with no <USER@HOST>:

14:05 * mike@thelio waves

An older riff shows the line as /me waves. @lead and @USER in an action wake as in any line. The chat knows only /me and /quit. It sends no line with another command. To send a line that starts with /, start it with //.

Chat without color

--color works as in riff tail:

riff chat --color never

A signed message

Each message carries a signature from the device key of its sender. The reader checks the signature before it shows the message. So a message that changed after it was sent, or a message with a false sender, shows as not verified.

sequenceDiagram
    participant A as mike (api)
    participant E as riff-server
    participant S as storage
    participant B as brett (tests)
    A->>E: who: am I the lead?
    E-->>A: the lead mark of mike (api)
    A->>A: sign the sender, lead mark, thread, to, body, kind and time
    A->>E: post and signature
    E->>E: check that the key of the token signed it
    E->>E: check the lead mark
    E->>S: save the message and its signature
    B->>E: read
    E-->>B: the messages and the keys of each sender
    B->>B: check each signature
    Note over B: verified, or not verified

• The server refuses a post that the key of its token did not sign.
• The signature covers the lead mark. The server refuses a signed lead mark from a session that is not the lead.
• A message is verified when its signature is valid, and its key is the key of a live sign-in of the sender.
• A message that is not verified never counts as from the lead. See When a message of the lead counts.
• Without sign-in, riff-server keeps no signature. See the next part.

A riff with no sign-in

The riff of Just this machine has no sign-in. It trusts its network. So its reader counts each message as verified.

flowchart LR
    R[riff-server] --> P{No sign-in provider and no --require-sign-in?}
    P -- yes --> V[it trusts its network: each message is verified]
    P -- no --> S{Valid signature from a live sign-in of the sender?}
    S -- yes --> V2[verified]
    S -- no --> N[not verified]

This holds only for a riff with no sign-in, on a network that you trust. Each program that can reach the riff can send a message with any name, also as your lead (see When a message of the lead counts).

So a riff with no sign-in listens only on a loopback address, for example 127.0.0.1. To listen on your network, give it an OAuth client (see Run the server in a terminal). For a network that you trust, see A riff on your network with no sign-in.

riff-server has no TLS. On a network, the traffic is plain HTTP. For TLS, put a proxy in front of it, or run it on a platform that gives TLS, for example Cloud Run.

Check who sent a message

Read your messages:

riff read

Each line shows (verified) or (not verified) after the sender and the address:

[1] mike@pangolin:riff (a6cf) lead=true to all (verified): the API is ready
[2] brett@heron:riff (77e0) to claim=issue-6 (not verified): look

The sender is short: the user, the host, the repository, the worktree, and the start of the session ID. lead=true marks a verified lead. to all is a post to each session of the repository of the thread. riff who shows the full URI of each session. riff tail shows the same mark on each new message.

Answer the sender of a message

riff tell takes the start of a session ID, as riff read shows it:

riff tell a6cf "7878"

When the start fits more than one session, riff tell stops and names them. Give more of the ID.

Wake a session

A session wakes when a message for it comes. A session in a container has no watch of its own: the riff daemon watches its wakes for it (see How a container session gets a message). The lead starts one watch (see below).

Wake the lead in a container with no restart

The lead in a container does not start its watch for each wake. It starts one watch with the Monitor tool of Claude Code. The watch prints one line for each wake. Monitor turns each line into a notification, so the lead wakes. Claude Code ends a Monitor after 30 minutes at most. When the Monitor ends, the lead starts the watch again, and only then. A new watch does not wake the lead for a message that it read, also with all and after. The riff daemon sends each wake once, also two messages in a row.

sequenceDiagram
    participant L as lead (Monitor)
    participant W as riff relay watch --follow
    participant D as riff daemon
    participant E as riff-server
    L->>W: start (and again when the Monitor ends)
    W->>D: follow
    E-->>D: message 417
    D-->>W: one line
    W-->>L: the line wakes the lead
    E-->>D: message 418
    D-->>W: one line
    W-->>L: the line wakes the lead

Inside the container of the lead, the command is:

/opt/riff/riff relay watch --follow

A worker or a verifier does nothing: the daemon puts each wake in its input.

One read after a wake shows the message of the wake

A read gives one page of 50 messages of each thread, the oldest unread first. The message of a wake can come after many older pages. So the page also gives each unread message after it that woke the session. The read tool shows them first, in their own part:

Messages to you after this page (the watch does not wake for them again):
chat
[327] mike@pangolin to session=193c7051 (verified): Can you look at #1110?

chat
[128] ann@heron (verified): ...
More messages follow. Read this thread again. With all, set after to 177.

One read after a wake is enough: the next watch does not wake again for the messages of that part. Later pages show them again in their place.

Post a note

A wake costs the woken session a read of its whole context. So a post wakes only the sessions that must act. Each other post is a note. A note wakes nobody. The sessions that its --to selects see it at their next read:

riff post --kind note --to repo=como-technologies/riff "Board: Wave 4 starts."

These posts wake:

How a container session gets a message

A worker or a verifier of riff run or of a wave runs in a container, with no watch of its own. The riff daemon watches its wakes for it. Until the end of the first turn, the session gets each wake as one input, as a session in a container does. During a takeover, the wake waits until the session goes on.

Tell a container session, by its session ID:

riff tell b7d0 "Use the new error type of #1063."

Or post to the thread of its item:

riff post --to claim=issue-1066 "Use the new error type of #1063."

At the end of its first turn, the session ended its work: it reads no more messages. Your first message to it after that gets an answer from the daemon, in a direct message to you. Your later messages get no answer:

riff: the session b7d0 ended its work, and does not read your message 9 in como-technologies/riff. Start a new session for the work.

When the session ended on riff-server too, riff tell to it fails.

sequenceDiagram
    participant Y as you
    participant E as riff-server
    participant D as riff daemon
    participant S as container session
    D->>E: watch the wakes of the session
    Y->>E: riff tell b7d0 "..."
    E-->>D: wake
    D->>S: the wake, as one input
    Note over S: the end of the first turn
    Y->>E: riff tell b7d0 "..."
    E-->>D: wake
    D->>Y: the session ended its work

A claim

A claim stops two sessions from doing the same work.

sequenceDiagram
    participant A as mike (api)
    participant E as riff-server
    participant B as brett (tests)
    A->>E: claim issue-12
    E-->>A: granted
    B->>E: claim issue-12
    E-->>B: held by mike (api)
    A->>E: release issue-12

While the riff or the repository is paused, each claim there fails. The answer names the pause, who set it, and who can end it.

What keeps a claim and what ends it

A claim stays while its session works. Only these steps end it:

Each other step keeps the claim: move, a keep-alive, status, a read, a post, a compaction and a pause. To see the claims of your session after a step, look at its URI:

riff whoami

When riff ends your claim

A new start of a live session and a release of the lead end its claims. Then riff-server sends the session one direct message from riff@server. The message wakes the session, also a process of the session that still works, for example the outer session of a claude -p. It names each claim, the reason and the step:

• After a new start: claim the item again to go on with it, or stop the work on it.
• After a release of the lead: stop the work on the item, push it as WIP, and write the state on the issue.

The release of the session itself sends no message.

sequenceDiagram
    participant W as worker (w1)
    participant E as riff-server
    participant L as lead
    W->>E: claim issue-12
    L->>E: release issue-12 --session w1
    E-->>W: wake: riff@server wrote to you in a direct message
    W->>E: read
    E-->>W: claims: the lead released your claim issue-12 ...

To see the message, read your threads:

riff read

Claim an item by hand

A person can claim and release in a terminal too. riff claim exits with status 1 when another session holds the item:

riff claim issue-12
riff release issue-12

-t (--thread) names another thread. See Use another thread.

Hold an item

A lead holds an item to keep it from the workers, for example while it waits for the word of a person. A hold is not a claim. No worker can claim a held item. Each other session can, and its answer has the hold as a warning.

sequenceDiagram
    participant L as lead
    participant E as riff-server
    participant W as worker
    participant S as session of a person
    L->>E: hold issue-12 "waits for the word of Mike"
    W->>E: claim issue-12
    E-->>W: on_hold: held by the lead since TIME: REASON
    S->>E: claim issue-12
    E-->>S: granted, with a warning
    L->>E: free issue-12

• Only a lead of the repository, the owner or an admin can hold and free an item. A worker cannot.
• A hold names one item by its exact name. A hold of issue-12 does not stop verify-issue-12.
• A hold does not end a claim. It stops only the next claim of a worker. Only free ends a hold.
• The lead session uses the hold and free tools.

Hold an item by hand

Run it in a terminal in the repository. The reason has 1 to 200 characters:

riff plan hold issue-12 waits for the word of Mike

issue-12 in como-technologies/riff is on hold now: no worker can claim it. `riff plan free issue-12` frees it.

A hold of a held item replaces its reason. -t (--thread) names another repository thread.

Free a held item

riff plan free issue-12

issue-12 in como-technologies/riff is free of its hold: a worker can claim it.

Keep the verify of an item from the workers

A hold of verify-issue-12 stops the claim of the verify by a worker. riff run and the wave of the daemon send no verify request for the item. Only a lead, the owner or an admin can hold it:

riff plan hold verify-issue-12 a scratch item

A worker cannot hold an item. The label no-verify on the issue works for each session: riff offers no verify of the pull request of the issue to a worker, and riff run and the wave of the daemon send no verify request for it. The first command makes the label, or updates it:

gh label create no-verify --description "riff offers no verify of this item" --force
gh issue edit 12 --add-label no-verify

riff run says why it sends no verify request:

riff run sends no verify request for issue-12: issue #12 has the label no-verify.

The wave of the daemon (riff wave run) posts a note to the lead in place of the verify request, with the reason:

issue-12: the session of the wave ended, and the item is free. The riff daemon sends no verify request for PR #40, branch worktree-issue-12, commit 1a2b3c4 (session 9f8e7d6c): issue #12 has the label no-verify.

With no verify, the pull request does not merge. To let riff offer the verify again, remove the label, or free the hold:

gh issue edit 12 --remove-label no-verify
riff plan free verify-issue-12

Pause the riff

riff has two pauses:

• The pause of one repository. It stops the sessions of that repository. The other repositories go on.
• The pause of the whole riff. It stops each session. A new riff is paused, so no session takes work before you say so.

A session is paused when its repository is paused, or the whole riff is paused. The wake of a pause sends each session to “Pause” in the instructions of its riff tools. While a session is paused:

• Each claim fails. The sessions keep the claims that they hold.

• A new session on a host claims nothing. It says hello to the lead, and waits. The resume wakes it.

• A session on a host with work stops at its next step. It lets a command that runs finish. It commits each change as a WIP commit on the branch of its worktree, and pushes that branch. It pushes nothing to the default branch, and waits.

• A container session of riff daemon stops at its next step in the same way, and ends after its WIP push. The daemon sends no verify request for a WIP head. The lead gets this note:

  issue-12: the session of the wave ended, and the item is free. The head of PR #40, branch worktree-issue-12, is the WIP commit 1a2b3c4 (session 9f8e7d6c). The riff daemon sends no verify request. The item goes back to a build when the riff runs again.
  

  At the resume, the daemon starts a new build of the item. The build has the start text of a resume and goes on from the WIP commit.

• The lead tells its person that the riff is paused. It calls resume only when the person says so.

• Messages still flow. A session on a host answers a status request and the lead.

sequenceDiagram
    participant P as you
    participant E as riff-server
    participant W as session with work
    P->>E: riff pause
    E-->>W: wake: the repository is paused
    W->>W: finish the command, WIP commit, push the branch
    W->>E: keep the claims, wait
    P->>E: riff resume
    E-->>W: wake: the repository is running again
    W->>W: go on from where it stopped

A riff with no sign-in has no owner: each person there can set each pause. A pause and a resume wake each session that they stop or start. The lead of a repository with a pause of its own hears the pause and the resume of the whole riff too (see Tell the lead of a paused repository). The pauses stay when riff-server saves its state in a bucket (see A restart).

Pause your repository

Run it in a terminal in your repository, not in an agent session:

riff pause

You can also ask your lead: “Pause the repository.”

Resume your repository

riff resume

You can also ask your lead: “Resume the repository.” When the whole riff is paused too, the answer says so. Then the sessions wait for the resume of the riff.

Pause the whole riff

Only the owner or an admin can. Use it for example for a release:

riff pause --riff

When your lead is your session and you are an admin, you can also ask it: “Pause the whole riff.”

Resume the whole riff

riff resume --riff

A repository that has a pause of its own stays paused. The answer names it, and the leads that it told.

Tell the lead of a paused repository

A pause of the whole riff and a resume of the whole riff wake the workers of each repository that has no pause of its own. They do not wake the workers of a repository that has one: its pause still stops them. Its lead is different. The lead keeps the running state, its tools work, and it may wait for the resume. So riff posts one message to the lead of each such repository, in the thread of that repository. The message says that the riff runs again (or is paused), that the pause of the repository still stops its workers, and who set that pause.

sequenceDiagram
    participant P as you
    participant E as riff-server
    participant W as workers of a free repository
    participant L as lead of a paused repository
    participant X as workers of that repository
    P->>E: riff resume --riff
    E-->>W: wake: the riff is running again
    E-->>L: wake: the riff runs, your repository is still paused
    E--xX: no wake: their repository is paused

Run it as before:

riff resume --riff

The answer names the leads that riff told:

The riff is running now. Woke mike@pangolin:riff (l1). Told the lead of como-technologies/strata: brett@heron:strata (62b2). Still paused: como-technologies/strata. Its user or its lead resumes it with `riff resume`.

The lead resumes its repository with riff resume, or you do.

Pause a repository of another person

Only the owner or an admin can. Name the repository:

riff pause --repo acme/app
riff resume --repo acme/app

See the pauses

riff whoami

riff     running
paused   como-technologies/strata by the session brett/62b2

The fact riff is the pause of the whole riff, with who set it. Each fact paused is a repository that is paused, with who set its pause. riff who and riff top show the same facts.

A status

riff makes the state of each session from facts. No session reports it. Each session also has a status: its current step, in its own words. The words help a person, and make no state. riff who shows the state, then its detail, then the step with its age, in the DETAIL column of the row of its session:

SESSION                            STATE    ROLE  DETAIL
mike@pangolin:riff#issue-6 (a6cf)  busy           working on #6  runs Bash: run just ci for 4m  6m ago: write the tests
brett@heron:riff#issue-7 (77e0)    waiting        working on #7  waits for a verify of PR #418

The facts come from three places:

flowchart LR
    K["riff relay mcp: the keep-alive"]
    G["riff pr open, riff verify, riff pr wait,<br/>the look of the lead (gh)"] --> S
    K --> S["riff-server"]
    C["claims, pauses, clears"] --> S
    S --> W["the state in riff who and riff top"]

• The keep-alive of riff relay mcp carries the newest fact of the session to the server, each minute, and each 10 seconds in a worker. A riff tool and riff relay watch are no work. The text of a Bash call is its description, never its command.
• The server has no credential of GitHub. riff pr open, riff verify, riff pr wait and the look of the lead each minute tell it the state of each pull request, and the open items of each Needs: line.
• The claims, the pauses and the clears are in the server already.

A status request is a post of kind status. It wakes each session that its to list selects. Each woken session answers with its status. It does not post a reply.

sequenceDiagram
    participant P as person
    participant E as riff-server
    participant A as mike (issue-6)
    participant B as brett (issue-7)
    P->>E: post kind=status to [repo=como-technologies/riff]
    E->>A: wake (status request)
    E->>B: wake (status request)
    A->>E: read, then status "write the tests"
    B->>E: read, then status "merge"
    P->>E: who
    E-->>P: each session with its state, and its status with the age

Ask each session for its status

Run this in the repository. Give the sessions one wake to answer, then list them:

riff post --kind status --to repo=como-technologies/riff
riff who

The state of a session

riff-server derives the state from the facts, and riff who, riff top and the who tool show it. The first state that matches wins:

The work is the newest fact of the session: runs Bash: run just ci for 12m, works, 5s ago between two tools, or turn ended 5m ago.

The author of an item waits for the verify, then for the merge. The session that verifies works until its result, then waits for the merge. A wait wakes nobody: the verify request is the wake. A wait ends when its fact ends.

The lead takes no claims: it conducts the other sessions. So its state comes from its facts. See The state of the lead. An idle lead shows monitoring work. The time of idle counts from the last release of the session. must clear is the state of a worker after its last release, until its context clears.

A step goes stale when the state of the session changes after the step was set: a claim, a release, a pause, a resume, or a new start of riff-server. A stale step is dim, and says stale.

stateDiagram-v2
    [*] --> Current: the session sets a step
    Current --> Stale: a claim, a release, a pause, a resume, or a new start of riff-server
    Stale --> Current: the session sets a step

To see the state of each session:

riff who
riff top --once

SESSION                  STATE  ROLE    DETAIL
mike@thelio:riff (4e54)  idle   lead    monitoring work for 2h
mike@thelio:riff (9c0d)  idle   worker  ready for work for 6m

Set your status

A session sets its own status with the status tool. A person can set a status from a terminal:

riff status write the tests

A status is one line of at most 400 characters. riff refuses a longer one with the step has more than 400 characters.

The state of the lead

The lead has no claims. riff makes its state from what it does:

stateDiagram-v2
    [*] --> idle
    idle --> busy: a prompt or a wake starts a turn
    busy --> idle: the turn ends
    busy --> waiting: blocked REASON
    waiting --> busy: the next prompt of the person

A lead that calls only the command line still shows in riff who and riff top while it calls. Each riff call, riff status too, is a sign of life. After 3 minutes with no call, the lead is gone.

Say that the lead waits for you

When the lead needs you, for example to run a command as the owner, it says so. riff shows it as waiting, with your name and the reason:

riff blocked run riff owner --take

You wait for your person: run riff owner --take. Ask your user. The next prompt ends the wait.

The lead sends no message: you read its terminal. A message of another session does not end the wait. Your next prompt in the lead ends it. The blocked tool does the same.

End the wait of the lead

Give the lead a prompt in its terminal. The wait ends at once, and the row of the lead no longer shows it:

riff who

mike@pangolin:riff (4e54)  idle  lead  monitoring work for 5s

The settings of the lead container run the hook UserPromptSubmit at each prompt: /opt/riff/riff relay prompt. It tells the riff daemon, and the daemon tells riff-server. The hook prints nothing, and never stops your prompt. When the daemon is away, the wait holds until your next prompt.

sequenceDiagram
    participant P as you
    participant C as claude (the lead)
    participant H as riff relay prompt
    participant D as riff daemon
    participant S as riff-server
    P->>C: a prompt
    C->>H: UserPromptSubmit
    H->>D: prompt, on the socket of the lead
    D->>S: keep-alive: a prompt now
    Note over S: the wait of the lead ends
    D-->>H: done

A prompt in a worker ends no block: the riff daemon gives each input of a worker, not a person.

Show a long step

A step that runs longer than one tool call, for example a live window of two hours, gets a row in riff who and riff top. Start it:

riff step start live window

mike@pangolin:riff (4e54)  busy  lead  runs Bash: run the live window for 2m  live window for 40m

When it ends well:

riff step done

When it fails, give the reason. riff who and riff top show it in red, and the message step failed: NAME: REASON wakes your lead:

riff step fail the stage gave 502

mike@pangolin:riff (9c0d)  idle  ready for work for 5m  live window failed 1m ago: the stage gave 502

A new riff step start replaces the old step. A failed step shows until the next riff step command. A new start of riff-server keeps the step: the checkpoint saves it with the status. Its age goes on from its first start.

A blocked session

A session is blocked when it cannot go on with no decision of a person. One command says so. It shows the session as blocked, and the message blocked: REASON wakes the lead of its user. A session calls the blocked tool. From a terminal:

riff blocked "which of two designs?"

Do not use it to wait for a verify, a merge or a need: riff shows that wait as waiting by itself.

A message that wakes the blocked session is its answer. The block ends at the next work of the session after the answer: a tool call, a claim, a release, or a new start. The lead is not blocked: it waits for you, and your next prompt ends the wait. See Say that the lead waits for you. A note or a status request is no answer. The answer ends the line the lead gave no answer at once.

When the lead gives no answer, riff tells the person:

sequenceDiagram
    participant W as blocked session
    participant S as riff-server
    participant L as the lead
    participant P as you
    W->>S: blocked "which design?"
    S->>L: blocked: which design? (wake 1)
    Note over S: 15 minutes, no answer
    S->>L: blocked: ... has no answer after 15 minutes (wake 2)
    Note over S: 15 minutes more, no answer
    S-->>L: unanswered
    L->>P: a desktop notification
    Note over P: riff top: the lead gave no answer

The riff relay mcp of the lead looks each minute. The notification holds the session, its item and the reason, and no text of a message. It needs a desktop: a display and notify-send, as on GNOME. A machine with no desktop gets no notification, and nothing fails. The keys lead.wake (minutes, 15 by default) and lead.notify (true by default) are in the settings file of the machine of the lead.

See what the lead does

The lead does not need to set its step. riff sets the step of the lead from each call that the lead makes with the tools tell, post, pause, resume and lead. Look at the row of the lead:

riff who

SESSION                  STATE  ROLE  DETAIL
mike@thelio:riff (4e54)  idle   lead  monitoring work for 2m  12s ago: told 075ff6a7

The step of a post shows the message in one line of at most 80 characters. A direct message is private to its two sessions, and each member of the riff reads riff who. So the step of a tell shows only the session.

For work that riff cannot see, the lead sets its status with the status tool, for example read the review report. That status stays until the next of these calls. A step does not end a block of the lead. The step of each other session changes only when the session sets it.

The notes of the lead

The notes of the lead are text that riff-server keeps for you in each repository: the running state of the lead, what waits for you, your choices and the choices of a host. A lead on any host reads them at its start. So a new lead, or a lead after a crash, needs no Claude memory of one host. The lead keeps the state in its notes and on GitHub.

flowchart LR
    L[the lead] -->|notes tool| S[(riff-server)]
    P[you] -->|riff lead notes edit| S
    S -->|riff lead notes| P
    S -->|the notes tool, at each start| L2[the lead on a new host]

Only you and the owner of the riff can read your notes. A secret never goes in them: riff refuses a text that looks like a token. The limit is 64 KiB.

Show the notes of the lead

riff lead notes

Add --thread OWNER/REPO for another repository.

Edit the notes of the lead

riff lead notes edit

riff opens $VISUAL, $EDITOR or vi. The new text replaces the old text. To take the text from a file:

riff lead notes edit --file notes.md

See the old texts of the notes

riff keeps each old text.

riff lead notes --history

The owner can show the notes of another user with --user NAME.

Move the lead to another host

You can move the lead of a repository from one host to another, for example from pangolin to thelio. One command does it all: no scp, no copy of the Claude memory. The notes of the lead hold the rules and the running state, so the new lead has them.

sequenceDiagram
    participant P as you
    participant O as old lead (pangolin)
    participant D as riff daemon (thelio)
    participant N as new lead (thelio)
    P->>O: riff lead move thelio: write the handover
    O->>O: handover in the notes
    P->>D: start the lead
    D->>N: claude, first prompt: read the notes
    N->>N: is the lead now
    P->>O: you are not the lead any more

On thelio, the riff daemon must serve the repository. If it does not, run this once in your clone of the repository. The daemon of thelio makes its own main clone (see Add a host to the wave):

riff daemon host --host thelio

Then run this on pangolin, in the repository:

riff lead move thelio

riff waits at most 5 minutes for the handover of the old lead. If the old lead writes none, riff says so and moves the lead with the notes as they are. If thelio has no daemon, nothing moves, and the old lead stays the lead. Only the lead and you can run this command. The lead runs it on your word, and writes its handover to the notes first.

The old session stays as a plain session. End it when you are ready. To attach to the new lead, run this on thelio:

riff lead start

The lead

A person often runs many sessions at once. The person works in one of them: the lead. The other sessions of the person are workers. The workers send their questions to the lead, and the lead gives them work. The person answers there. No question waits at a terminal that the person does not watch.

This graph shows two people in one repository. mike has a lead on pangolin, and workers on pangolin and thelio. brett has a lead and a worker on thelio.

flowchart TB
    M((mike)) <-->|questions, answers| ML
    B((brett)) <-->|questions, answers| BL
    subgraph pangolin
        ML[mike: lead]
        MA[mike: issue-6]
    end
    subgraph thelio
        MB[mike: issue-7]
        BL[brett: lead]
        BA[brett: issue-9]
    end
    MA -->|questions, reports| ML
    MB -->|questions, reports| ML
    ML -->|answers, requests| MA
    ML -->|answers, requests| MB
    BA -->|questions, reports| BL
    BL -->|answers, requests| BA
    ML <-.->|repository thread| BL

• Each person has at most one lead in each repository, on all machines together.
• No session becomes the lead by itself, also the first. You name the lead: see Name the lead. A session cannot make itself the lead. A worker is never the lead: see When you have no lead.
• The URI of the lead has lead=true. riff who shows it.
• A lead that ends, stops for more than 5 minutes, or works in another repository, is not the lead until it comes back. A lead that leaves the thread is not the lead any more. With no lead, each session asks its own user.
• A lead talks only to the sessions of its own person. When the work of two people touches, the leads post to the repository thread, and the people agree.

What the lead does:

• It shows the questions of the workers to its person, and sends the answers back. See Ask the lead.
• It gives each worker an item. See The lead conducts your sessions.
• It plans the waves. See Waves.
• It takes no claims: no work item and no verify. So it is free for you at all times. A verify request waits for a free worker. See Verify finished work.

sequenceDiagram
    participant P as person
    participant L as lead (main)
    participant E as riff-server
    participant S as session (issue-6)
    S->>E: tell lead "merge now, or wait for issue-5?"
    E->>L: wake
    L->>E: read
    L->>P: issue-6 asks: merge now, or wait for issue-5?
    P->>L: wait
    L->>E: tell issue-6 "wait for issue-5"
    E->>S: wake
    S->>E: read
    Note over S: continues, with no input at its own terminal

Name the lead

Only you name your lead. riff lead start starts a lead in a container and names it the lead: see Start the lead. To name another session the lead, for example a session on the host when the lead container ended, find its session ID:

riff who --long

Then run this in a terminal in the repository, not in an agent session. Use the session ID, or its first 4 characters or more:

riff lead --session 77e0a1b2

The new lead replaces the old lead. riff sends the old lead a message: it is not the lead now. In an agent session, riff lead fails: a session cannot name the lead, also not itself. A worker cannot be the lead: a worker cannot be the lead. Make another session the lead.

flowchart TD
    C[a call names the lead] --> P{from a person, with no session ID?}
    P -- no --> R[refused]
    P -- yes --> W{the named session is a worker?}
    W -- yes --> R
    W -- no --> L[the lead]
    L --> O[the old lead gets a message]
    S[a session registers or starts] --> N[not the lead]

What a new lead reads

A new lead does not find the kept history of each thread unread. It takes the read marks of the lead before it, in each thread that both joined. So its unread messages are the messages that the old lead did not read. This holds after each riff lead start, and after each riff lead --session ID.

sequenceDiagram
    participant A as old lead
    participant E as riff-server
    participant B as new lead
    A->>E: read the thread up to message 3
    Note over E: messages 4 and 5 come
    B->>E: start: joins the thread at message 5
    B->>E: named the lead
    Note over E: B takes the mark of A: message 3
    B->>E: read
    E->>B: messages 4 and 5

A thread that the new lead joins after it is the lead starts at its newest message, as for each session: see Read each kept message. To read the older messages too:

riff read --all

When you have no lead

When you name no lead in a repository, or each of your sessions there is a worker, you have no lead there. This is what you see:

• riff who shows no session of you with the tag lead.
• A tell to lead fails, and says to ask your own user. So a session asks you in its own terminal.
• A verify request goes to each of your live sessions with no claim.
• No session of you can pause or resume the riff. You can, from a terminal.

To get a lead, start one with riff lead start, or name a session that is not a worker with riff lead --session ID. See Name the lead.

Ask the lead

A session asks the lead with tell and the session lead. It does not need the session ID of the lead. A person can do the same from a terminal in the repository:

riff tell lead "Merge issue-6 now?"

When the person has no lead, the tell fails and says to ask your own user. A session never asks the lead of another person.

You look only at your lead. So a session that is not the lead never asks you in its own terminal. When a permission refusal stops it, for example riff pr open, it tells the lead the pull request, the commit and the verify result. You decide. No session pushes to main (see Merge by pull request on GitHub).

The lead conducts your sessions

The lead splits the work among the other sessions of its person. It sends each free session one item, and the session reports back. The lead never sends work to the sessions of another person.

sequenceDiagram
    participant L as lead
    participant A as session a1
    participant B as session b2
    L->>A: tell "request: claim issue-12"
    L->>B: tell "request: claim issue-7"
    A->>L: tell lead "started issue-12"
    B->>L: tell lead "blocked on issue-7: needs issue-5"
    L->>B: tell "request: release issue-7, claim issue-9"
    A->>L: tell lead "issue-12: the verify request is sent, and I released the item"

To see what each of your sessions holds and does, run this in the repository. Use your own user and repository:

riff post --kind status --to user=mike,repo=como-technologies/riff
riff who

To give a session an item by hand, use its full session ID from the session= part of its URI in riff who:

riff tell 77e0a1b2-3c4d-4e5f-8a9b-0c1d2e3f4a5b "request: claim issue-12"

You can also ask your lead: “Split the free items of the wave among my sessions.”

Give a session a task with no item

Some work has no issue, for example a listener that runs for an hour. Name a task claim task-NAME in the request:

riff tell 77e0a1b2-3c4d-4e5f-8a9b-0c1d2e3f4a5b "request: claim task-iroh-listener, then run the listener of #697"

The session claims task-iroh-listener before it starts, and releases it when the task ends. While it holds the claim, it is busy: riff gives it no free work (see riff starts the work by itself). When a request names no claim, the session claims a task-NAME of its own. riff who shows the session as working on task-iroh-listener.

When a message of the lead counts

A worker takes a message from the lead as a decision of its person only when both are true:

• The message is verified. See A signed message.
• Its sender has lead=true, and is the lead of the same person.

Each other message is advice: from another session of the same person, from another person or their lead, or not verified. The worker uses its own judgment: it acts on the advice, asks about it, or says no. A message that is not verified never counts as from the lead: the reader shows its sender without lead=true. A scope from the person in the terminal of the worker wins over a request of the lead.

riff-server refuses a copy of a signed message. So a worker gets each request of the lead once.

Sessions talk to each other when it helps, with no lead: they share what they found, ask questions, and warn about a conflict before they edit the same files.

On a riff with no sign-in, each message is verified. So each program that can reach the riff can send a message as your lead. See A riff with no sign-in.

A restart

riff-server keeps its state in memory. What a restart keeps depends on the bucket (see Save the state in a bucket and Keep the state in a directory).

With no bucket and no directory, for example the riff of Start a Riff, a restart forgets each thread, session, claim and lead. The riff is paused again. Start your Claude Code sessions again after it, and run riff resume --riff when you want them to work.

After a restart with no bucket, run riff login

A riff with sign-in and no bucket is a new riff after each restart. It also forgets each sign-in. Each riff has a riff ID, and riff keeps it with your sign-in. At a new riff, the next riff command removes the old sign-in of your machine and stops with:

This riff is new. Run riff login.

Sign in again, then start your Claude Code sessions again:

riff login

The command after it runs with no sign-in, so it gives no other error.

A restart with a bucket

A restart with a bucket keeps the riff ID, and your sign-in stays.

With a bucket, each change is a record in one log: a message, a join, a claim, a lead, a pause, and each change of the people. riff-server writes the records as chunks to Cloud Storage. A call that makes a record gets its reply after the write, and its wakes go out after the write too. So nobody sees a change that a restart can lose. Each record names its cause: the caller and the command. See Find who did what.

A checkpoint is the whole state at one position of the log, with the read cursors, the status and the last call of each session. At start, the server loads the newest checkpoint and replays only the records after it. So a start stays fast while the log grows. The server keeps the last 3 checkpoints and one for each day of the last 30 days. It deletes each chunk that no kept checkpoint needs.

The server writes a checkpoint:

• each 1,000 records, or each 60 minutes when records came;
• on SIGTERM, after the last record;
• at a deploy, when the old instance reads the lease of the new one (see the deploy below).

flowchart LR
    C[call] --> H[check against the state]
    H -->|refused| E[error]
    H -->|records| Q[queue]
    Q --> W[writer: one chunk for each write]
    W --> L[(log in Cloud Storage)]
    L -->|written| R[reply, wake, tail]
    T[each 1,000 records or 60 minutes,<br/>SIGTERM, a deploy] --> K[(checkpoint)]
    K -->|at start: load| P[replay the records after it]
    L --> P

On SIGTERM, riff-server writes each record in the queue and a last checkpoint, then exits. When a write fails for 10 seconds, the server stops, and a new instance replays the log without the lost change. The call of that change got an error, and riff tries it again. A restart loses the open streams. riff relay watch and riff tail connect again. The session then gets one wake if an addressed message is unread. Cloud Run also ends each stream after 60 minutes. The streams then connect again in the same way. riff tail and riff chat then show each message that came while they were not connected.

After a restart with a bucket, each session counts as stopped. Its claims and its lead stay for 5 minutes. A session that connects again in that time keeps them. who shows a session again only after it calls. A stop and a deploy write a last checkpoint, so each read cursor and each status stays, and riff read shows no message again. After a crash, the start uses the checkpoint before it: then riff read can show a message two times. It never misses one.

The server forgets a session after 30 days with no sign of life. It drops the threads, the claims, the lead and the read cursors of the session, and each direct thread whose two sessions are gone.

A sign-in stays valid after a restart with a bucket. The server saves the sign-ins and their chains in the object signins.json, with only a hash of each refresh token. The object also keeps a hash of each live access token. So after a restart or a deploy, riff uses its access token as before, and does not refresh.

The server writes the object when it changed:

• at most one time each second. The second counts from the end of the last write, so Cloud Storage never gets two writes of the object in one second, also when one write is slow;
• when Cloud Storage refuses a write for its rate limit (429), the server waits two times longer before the next write, up to 32 seconds. A good write sets the wait back to one second;
• on SIGTERM, after the last record;
• at a deploy, when the old instance reads the lease of the new one. It writes the object one last time, before its last checkpoint. So a token from the last second of the old instance works on the new one.

Only a token from the last second before a crash is lost: then riff refreshes one time by itself.

The people are not in that object. Who may join, the owner, the admins, the members and the riff ID are records of the log. So they stay after a restart, and the log shows who changed them. See Find who changed the people.

A removal ends each sign-in of the person. The server writes the record first, and then ends the sign-ins. Each sign-in keeps the position of the log at its start. When the server stops between the two steps, the next start drops each sign-in from before the removal. So a removed person never gets in again with an old sign-in.

sequenceDiagram
    participant A as admin
    participant E as riff-server
    participant L as log
    participant S as signins.json
    A->>E: riff remove bob@gmail.com
    E->>L: member_removed, position 8
    Note over E: stop before the end of the sign-ins
    Note over S: holds the sign-in of bob, from position 5
    E->>L: new instance: replay
    E->>S: load
    Note over E: 5 is before 8: drop the sign-in of bob

A sign-in gets its reply only after the server wrote the object. A refresh gets its reply before the write. So after a crash, the object can be one generation behind. The first refresh of each chain after a start takes the saved generation, or the next one, as good. While a write of the object fails, a refresh gets 503, and riff tries again. A swap for a session token never gets 503 for a write that failed: after a crash, a lost session token only costs riff one new swap.

sequenceDiagram
    participant C as riff
    participant E as riff-server
    participant S as signins.json
    C->>E: refresh, generation 7
    E-->>C: pair of generation 8
    Note over E: crash before the write
    Note over S: holds generation 7
    E->>S: new instance: load
    C->>E: refresh, generation 8
    Note over E: 8 is the next one after 7: good
    E-->>C: pair of generation 9
    E->>S: write generation 9

During a deploy, Cloud Run starts the new instance before it stops the old one. Cloud Run can also change the instance with no deploy, for example when it moves the instance to another machine. A lease in Cloud Storage makes sure that only one instance serves. The new instance loads the state first. It opens its port and takes the lease only when the load works:

sequenceDiagram
    participant O as old instance
    participant S as Cloud Storage
    participant N as new instance
    participant W as riff relay watch
    N->>S: load the sign-ins, the checkpoint and the log
    alt the load fails
        Note over N: exits: no open port, no lease
        Note over O: serves on
    else the load works
        Note over N: opens its port: 503 until it serves
        N->>S: write the lease (new ID)
        Note over N: waits 15 s
        O->>S: read the lease (every 2 s)
        S-->>O: new ID
        O-->>W: close the stream
        Note over O: closes its port, saves no record
        O->>S: write signins.json, when it changed
        O->>S: write the last checkpoint
        Note over O: exits
        N->>S: list the checkpoints again
        Note over N: loads the state again from the last checkpoint of O
        N->>S: read the chunks that came since the load
        Note over N: serves
        W->>N: connect again
        N-->>W: one line, if an addressed message is unread
    end

A new build that cannot read the state never serves. It opens no port, so Cloud Run sends no call to it, and the old instance serves on.

At an instance change, riff sees this:

• The old instance serves until it reads the new lease. Then it closes its port at once, so Cloud Run sends each call to the new instance. The old instance exits when its last checkpoint is written, at most 10 seconds later.
• The new instance replies 503 until it serves, about 15 seconds after it took the lease. riff tries each call again, and shows (waits for riff-server…) (see Wait while the server starts).
• For a few seconds after the old instance exits, Cloud Run can still send a call to it. Cloud Run then replies 500 or 429 by itself, with the text The request was aborted because there was no available instance. That reply names no build, so riff knows that it comes from Cloud Run, and tries the call again as after a 503. Each command, riff relay mcp, riff relay watch, riff tail, riff chat and the daemon do this. riff server and riff update say that the server does not answer: run them again.
• At a deploy, Cloud Run can start a second instance of the old revision while the new instance waits. The lease holds the number of the revision of its instance, so the second old instance does not take the lease of the newer revision. It replies 503 too, and it exits at once when Cloud Run stops it. So the wait of the new instance does not start again: each call gets its reply in less than 20 seconds.
• At a failed deploy, Cloud Run stops the new instance in its wait, before it serves. The new instance ends its lease before it exits. So an instance of the old revision takes the lease at its next read, and serves 15 seconds later: each call gets its reply in less than 20 seconds after the stop.
• At a shift of the traffic back to an older revision in the Cloud Run console, Cloud Run stops the newer instance. When it still waits, it ends its lease as at a failed deploy. When it serves, it ends its lease at its shutdown. The older instance then serves after its wait of 15 seconds. Until then, each call gets 503.
• When the new instance crashes in its wait, it does not end its lease. The lease then ends by its age: 90 seconds after its last write. An old instance then takes it and serves 15 seconds later. So each call can get 503 for up to 2 minutes.
• Your access token still works on the new instance, also a token from the last second of the old instance: riff gets no 401, does not refresh, and does not sign in again.

The claims of each session come back with the log. Each session has 5 minutes from the load to call again. After that, its claims are free.

The read cursors are only in the memory of the old instance and in the checkpoints. So when the old instance reads the new lease, it writes a last checkpoint for the new one. After its wait, the new instance lists the checkpoints again, and loads its state again from the newest one. So a deploy keeps each read cursor: no session gets an old message again. The new instance waits 15 seconds, and the old one reads the lease each 2 seconds, so the checkpoint comes in time. The old instance writes no checkpoint when a tool such as riff-server log cut takes the lease.

At a rollback, the old instance runs a later release. The new instance then writes no checkpoint past the checkpoint of the later release, and riff server says so in its saved line.

The update to release 1.0.0 keeps your work

Release 1.0.0 keeps the state of the riff in a new form: one log. The first start of the new server moves the state of the old server into the log, one time. You do nothing for it.

flowchart LR
    O[(old objects:<br/>sessions, tokens, threads)] -->|the first start reads them one time| I[the command import]
    I --> L[(the log)]
    I --> C[(a checkpoint with the read cursors)]
    O -.->|they stay for a rollback| O

• The riff keeps its ID, its owner, its admins and its members.
• Your sign-in stays. Do not run riff login.
• Each session keeps its threads, its claims, its lead and its read cursors. A thread keeps its last 200 messages.
• riff on your machine updates itself, or tells you to run riff update.
• The whole riff is paused after the move. The owner or an admin resumes it (see Resume the whole riff).

Check that your machine and the server run the new release, and that the riff has its old ID:

riff server

When riff says the sign-in ended: run riff login, the old refresh token of your machine did not work. It works one time only. Sign in again:

riff login

Wait while the server starts

Each start of the server has a gap of about 15 seconds. riff tries each call again while the server replies 503, for up to 60 seconds. You do nothing. When a call waits for more than 1 second, riff shows one line:

(waits for riff-server…)

riff chat shows the line above its prompt. riff top keeps its table, and shows the line below it.

A server on one machine with --dir opens its port after its load, and replies 503 in the gap. Before the end of the load, each connect is refused. A riff that got a reply from the server before waits in the same way: riff relay mcp, riff relay watch, riff chat and riff top go on after a restart. A new riff command cannot tell a server on this machine that starts from no server, so a refused connect to 127.0.0.1 or localhost ends it at once. Wait for the line riff-server listens on in the log of the server, then run the command again. The line riff-server serves comes after the gap.

The front end of Cloud Run can also reply by itself, for example 502 while it moves an instance. Such a reply has no riff-build header. riff tries the call again in the same way. It does not show a version error for it.

When a connection dies with no sign

A laptop sleeps, or its address changes. Then a connection to the server can die with no sign. So each call and each stream of riff has time limits:

The server sends a keep-alive line on each stream each 15 seconds. So a stream that is alive never meets the limit of 45 seconds. A stream of riff relay watch, riff tail, or riff chat that died comes back in at most 45 seconds. The calls also send an HTTP/2 ping each 10 seconds, and drop a connection with no answer in 5 seconds.

A stream that falls behind the events of the server also ends at the server. riff connects again, and the watch gets the newest wake that it did not read.

sequenceDiagram
    participant R as riff tail
    participant S as riff-server
    R->>S: open the stream
    S-->>R: a keep-alive line each 15 s
    Note over R,S: the laptop sleeps: no byte comes
    R->>R: 45 s with no byte: the stream ends
    R->>S: open the stream again

You do nothing. To see it, keep riff tail open, sleep the laptop, and wake it again. In at most 45 seconds, it shows the messages of the sleep, then the new messages:

riff tail

Run the lead

The riff daemon runs the workers in containers. Start the lead by hand, as in Start a Riff.

How long a command waits for the server

Each call of riff to the server has a budget: the longest time from its first try to its end.

When a try gets no reply, riff tries again after a short wait, while the budget lasts. The wait grows from a quarter of a second to 5 seconds. A reply that says no, for example held, gets no new try.

flowchart TD
    T[a try] -->|a reply| R[the command shows it]
    T -->|a refusal| N[the command shows why]
    T -->|no reply, a cut, 502, 503 or 429| W{budget left?}
    W -->|yes| A[wait, then a new try with the same call ID]
    A --> T
    W -->|no| E["riff-server at URL gave no reply in 60 seconds"]

Each try of one call sends the same call ID. So the server runs a command one time only, also when a reply was lost and riff sent the command again. A post or a claim never runs two times.

A command with no server on this machine ends at once:

riff who

Error: cannot reach riff-server at http://127.0.0.1:7878

Start the lead

Start the lead in a container, in your clone of the repository (see Start the lead):

riff lead start

To watch the repository thread beside the lead, start riff tail in a second terminal.

Watch the riff on another machine

On a machine with no lead, start riff tail yourself. Name the thread, so that the directory does not matter:

riff tail como-technologies/riff

Start each session in the main clone

Start each session in the main clone of the repository, never in a worktree of a session. A session in a worktree can change the work of the other session.

When a session starts in a worktree where another live session works, its start context names that session and the main clone. The session claims nothing and asks you, through the lead, to start it again in the main clone.

riff starts the work by itself

When the riff runs and the current wave has free work, riff asks the riff daemon to run the wave. You do not ask, and the lead does not remember a step. The lead does it, once each 10 seconds. The daemon runs each item and each verify in a container. riff starts no worker on the host.

flowchart TD
    T["each 10 seconds"] --> R{"the riff runs?"}
    R -- "no: paused" --> T
    R -- yes --> D["ask the riff daemon of this machine, at most 5 s:<br/>does a wave of the repository run?"]
    D -- "it runs" --> T
    D -- "no" --> W["count the free work with gh"]
    W --> I{"free work?"}
    I -- no --> T
    I -- yes --> C{"ask the daemon: have the session image<br/>(podman, and a pull when it is missing)"}
    C -- "it cannot" --> N
    C -- "it has it" --> S["ask the daemon: run the wave of the repository"]
    S --> N["a note to the lead"]
    N --> T

• Free work. The free items of the current wave, and the pull requests that wait for a verify. A free item is an open issue of the current wave (see Waves). No session claims it, it has no comment Merged in #, and each issue of its Needs: line is closed. A pull request counts for the issue that it names (see See the item of a pull request). An item counts one time: while its pull request waits for a verify or for the merge, the item is no free item. This is also true for a release pull request. After a failed verify the item is free again (see How a session works on an item). A held item is no free work (see Keep an item from the rollout).
• A fix item first. An open issue with the label broken-main fixes a broken main. It comes before each other item, its verify first, also when it is not in the current wave (see When main breaks).
• The wave. riff asks only the daemon of the machine of the lead, and only when no wave of the repository runs there. The daemon runs each item in a container, in its own limit (see Let the rollout of the lead run the wave). While the wave runs, the rollout asks nothing. The claims on riff-server keep the sessions from one item. A second machine runs its own wave (see Use a second machine).
• A daemon that does not answer. Each look waits at most 5 seconds for the answer of the daemon. A daemon that gives no answer in that time runs no wave. The lead gets one note with the reason.
• A machine that cannot run a container. Before it asks for the wave, riff asks the daemon to have the session image. podman must run, and the image must be on the machine, or the daemon pulls it. When the daemon cannot, riff asks for no wave. So a machine with no podman runs no wave, and its daemon sends no message of a failed start.
• Notes. After each ask, the lead gets a note. When the daemon gives no answer, cannot start a container, or cannot run the wave, the lead gets one note with the reason, and riff asks again at its next look. A note does not wake the lead.
• Pause. A pause stops the rollout within one look. A look that started before the pause can ask for the wave one more time. The wave starts nothing while the repository is paused. The resume starts the rollout again.

See why the rollout runs no wave

The note to the lead gives the reason. On a machine with no podman, it is:

thelio: the rollout cannot run the wave of como-technologies/riff on the riff daemon: The riff daemon cannot start a container of the session image: riff cannot start podman. Install it, or put it on PATH.: No such file or directory (os error 2). The rollout tries again at its next look.

A daemon that takes the ask and gives no answer gives the reason The riff daemon gave no answer in 5 s. On the machine of the lead, see whether the daemon answers, and whether podman runs:

riff daemon status
podman info

Install podman, or start the daemon again with riff daemon install. The next look asks again: you run no other command.

Keep an item from the rollout

Hold the item. The wave starts no session for a held item. A hold names one item: hold verify-issue-12 to keep the verify too (see Hold an item).

riff plan hold issue-12 waits for the word of Mike

The rollout reads the holds at each look. Free the item, and the next look gives it to the wave:

riff plan free issue-12

See the item of a pull request

The trailer Issue: #N of a pull request names its item, as for riff verify. When the body has no trailer, the branch names the item, for example worktree-issue-12. So a release pull request on the branch release-v1.5.0 counts for its release issue. Look at the last lines of the body:

gh pr view 40 --json headRefName,body --jq '.headRefName, .body' | tail -n 3

While the pull request waits for a verify, the rollout gives verify-issue-N, not issue-N. While it waits for the merge, the rollout gives neither.

The auto mode settings of a session

In auto mode, Claude Code can block a normal step. After some blocks, when the settings have no autoMode.environment entries, Claude Code shows the dialog “Teach auto mode about your environment?” at the end of a turn. No person answers it in a session of the daemon. So riff gives each session that the daemon starts two Claude Code settings:

The places of riff work are the GitHub owner of the repository, the repository of riff with its releases, ghcr.io, the riff server of the session and the package sources of the repository.

The session gets them in the settings.json of its own Claude folder. The lead in a container gets each missing one at each start. Claude Code does not read autoMode from the project settings of a repository. So riff does not write them there.

See the entries that auto mode uses in your own session:

claude auto-mode config

Trust a package source

The package sources come from riff.toml of the repository. riff adds none by itself: with no sources, auto mode trusts no package source. The key sources of the table [session] is a list of hosts. riff reads it from the default branch of origin, as it reads the session image (see Only a merged pin counts). So a change counts after its merge, and a session cannot trust a source with an edit in its own clone.

flowchart LR
    T["riff.toml on origin/main<br/>[session] sources"] -- "riff run, riff lead start,<br/>the wave" --> E["autoMode.environment<br/>one entry for each host"]
    E --> S["settings.json of the session"]

Add the hosts of the package index of your repository, for example PyPI. Run this where riff.toml has no sources yet:

sed -i '/^\[session\]/a sources = ["pypi.org", "files.pythonhosted.org"]' riff.toml

Then merge the change by a pull request. The next session that riff starts trusts the hosts. A session that runs keeps its entries.

A host is a name such as pypi.org: no https://, no path. When sources has other text, riff starts no session and names the text.

Add to an issue

The lead owns the body and the title of an issue: the design, the Done when: line and the status. Only the lead changes them. A worker and a verifier add to an issue with a comment, and a comment keeps the history and the author.

flowchart LR
    L["lead"] -- "gh issue edit --body-file" --> B["body of the issue"]
    W["worker, verifier"] -- "gh issue comment --body-file" --> C["comment on the issue"]
    W -. "refused" .-> B

The settings of a session of a worker or a verifier allow gh issue comment. They refuse gh issue edit with --body, --body-file, -b, -F, --title and -t, also after gh -R. Write the text to a file, and post it:

gh issue comment 12 --body-file /home/you/tmp/comment-12.md

A worker has no rule for the other changes of an issue, for example a label: the auto mode check judges them. No rule names gh api, so a write to an issue with the API has no rule either, and the auto mode check judges it.

Waves

Sessions take their work in waves. A wave is a numbered group of work items: Wave 1, Wave 2, and so on. The waves run in number order. The items of one wave run at the same time, each in its own session.

• The current wave is the open wave with the lowest number. The next wave is the open wave after it.
• When a repository has no waves, each open item is in the current wave.
• The lead plans the waves. When a repository has the leads of more than one person, the people agree on one lead to plan them. See The lead.

Needs

An item can need other items. Its Needs: line names them:

Needs: #51, #58

An item is merged when it is closed, or when it has the comment Merged in #PR (COMMIT). The author adds this comment when a check after the release is left (see Verify finished work).

Pick an item

A session takes a free item of the current wave, never of a later wave. When the current wave has no free item, the session verifies the work of others, runs its checks after the release, or waits.

flowchart TD
    S[session looks for work] --> C{"free item in<br/>the current wave?"}
    C -- yes --> T[claim it]
    C -- no --> W["verify the work of others,<br/>run checks after the release, or wait"]

The wave of the riff daemon takes only an issue with a Done when: line in its body. A session stops at once without that line. For an issue with no such line, the lead gets one message, and the wave starts no session. When the line comes, the wave will take the issue at its next look. See Add a Done when line to an issue.

The life of a wave

flowchart LR
    P[planned] --> C[current]
    C --> M[each item merged]
    M --> S[the lead stops the workers]
    S --> V[an admin makes a release]
    V --> P2[CI deploys the release tag to the shared server]
    P2 --> U[each machine gets the merged code]
    U --> R[the sessions start again]
    R --> K[checks after the release]
    K --> X[each item closed]
    X --> D[the wave is done]
    D --> E[the lead ends the wave]
    E --> N[the next wave is current]

A wave is done when each of its items is closed. An item is closed when it is merged and each check after the release passed. Some items have a check that needs the merged code on each machine. The order in a wave: merge each item, make a release, deploy the release to the shared server, stop the workers, update each machine, start the sessions again, run the checks after the release, close each item. The work goes on while the deploy waits for a person. A riff with no shared server of its own code skips the release and the deploy. In the riff repository, the update is Update riff.

A push to main does not deploy the shared server. So a merge in the middle of a wave does not stop the sessions with a build mismatch. The lead makes a release once, at the end of the wave, with the riff commands. CI deploys its tag after a person approves the deploy. See Make a release and Deploy the shared server at the end of a wave.

No session starts an item of the next wave before the current wave is done.

A new item

A person or a session can add a work item at any time, with no wave. The lead puts it in a wave:

• Each item is in a later wave than each of its needs.
• No item blocks or breaks the other work of its wave.
• When the item fits in no open wave, the lead makes a new wave. Its number is the last number plus one.

Then the lead posts to the thread: the item, its wave, what it needs, and what needs it.

sequenceDiagram
    participant P as person
    participant L as lead
    participant E as riff-server
    participant S as sessions
    P->>P: add issue-70, with no wave
    P->>E: tell lead "new item: issue-70"
    E->>L: wake
    L->>L: write the Needs line, put issue-70 in Wave 3
    L->>E: post to [repo] "issue-70 is in Wave 3. It needs issue-55. issue-67 needs it."
    E->>S: wake

Tell the lead about a new item

Add the item with no wave. On GitHub, see Add an item with no wave. The lead looks for items with no wave each time it wakes. To wake it now, tell it:

riff tell lead "New item: issue-70"

Waves on GitHub

This is the only part of the book that is special to one forge.

• A wave is a milestone named Wave N. A name can follow, for example Wave 5: Cloud. A work item is an issue in the milestone.
• A milestone with another name is out of the waves.
• The backlog is the milestone Backlog. It holds the items that we track but do not start. An item in the backlog is not free work: no session starts it. Only the lead moves an item from the backlog into a wave, when you schedule the item.
• An open wave is an open milestone. The lead ends a wave: it closes the milestone. It closes a milestone only when the milestone has no open issue.

The waves of riff are its milestones.

The names that riff uses on the forge are in The names riff uses on the forge.

See the waves

Run this in a clone of the repository. It shows each open wave in number order, then the backlog, with the number of the open and the closed items. The current wave has the mark current and the hosts of its loop. The open items of each wave follow in the groups free, held, claimed, verify, stuck and tracker (see See which wave runs, and where):

riff wave list

Make a wave

Give the new wave the last number plus one. A name can follow the number. riff refuses a number that an open wave has. riff also makes the label tracker when it is missing (see Track a group of items), and the milestone Backlog when the repository has none:

riff wave make "Wave 6: Cloud"

Rename a wave

Give the number of the wave and its new name. The number stays: it is the wave. This command gives the milestone the title Wave 6: Cloud and sign-in:

riff wave rename 6 "Cloud and sign-in"

A pull request names its wave by the number only, in the trailer Milestone: Wave 6. The check Hygiene compares only the number. So a rename breaks no pull request, also one with the old title in its trailer.

End a wave

Give the number of the wave. riff closes its milestone. It refuses a wave that has an open item or an open pull request:

riff wave end 6

Move items to another wave

Give the numbers of the issues, and the wave to move them to: its number, or Backlog. riff refuses an item that a session claims, and a wave that is not open. Then it moves nothing:

riff wave move 71 72 --to 7
riff wave move 73 --to Backlog

When an item has no Done when: line, riff warns, and moves the item. The wave takes only an issue with that line: see Add a Done when line to an issue. --to Backlog gives no warning.

To end a wave that still has open items, move them to the Backlog and end the wave in one step:

riff wave end 6 --move-open-to-backlog

The lead plans the waves in its container, and these steps work there: the daemon of the host makes the calls on riff-server. The lead does them for you when it plans the waves. They are riff commands, so the permission rule Bash(riff *) covers them.

Track a group of items

A tracker is an issue that lists a group of items. It has no code of its own: each part is a separate item. The wave starts no session for a tracker: no build and no verify. riff wave list and riff top show it in the group tracker, never in free.

An issue is a tracker when it has the label tracker, or when its title starts with Tracker:. Add the label to issue 1248:

gh issue edit 1248 --add-label tracker

riff wave make makes the label. When the repository does not have it yet, make it first:

gh label create tracker --description "a tracker: its parts are separate items, and no session does it" --force

flowchart LR
    I["an open issue of the current wave"] --> T{"label tracker, or<br/>title Tracker: ...?"}
    T -- "yes" --> G["group tracker: no session"]
    T -- "no" --> F["free work: the wave starts a session"]

See the open items of a wave

gh needs the full title of the milestone, as riff wave list shows it. "Wave 6" does not find the wave Wave 6: Cloud:

gh issue list --milestone "Wave 6: Cloud"

See the items in the backlog

gh issue list --milestone Backlog

To schedule an item, tell your lead: “Move issue 71 into Wave 4.”

Add an item with no wave

gh issue create --title "Show the wave in riff who" --body "Done when: riff who shows the wave of each claim."

The names riff uses on the forge

riff uses a fixed set of names on the forge. They are rules of riff: each repository gets the same names, and no setting changes them. When your repository has a milestone or a label with one of these names, riff gives it the meaning below. Other milestones and labels are out of the waves, and riff ignores them.

flowchart LR
    R["a milestone, a label,<br/>a line or a branch<br/>of your repository"] --> N{"a name<br/>of riff?"}
    N -- yes --> U["riff gives it the<br/>meaning of the table"]
    N -- no --> I["riff ignores it"]

See the names that your repository has

Run this in a clone of the repository, before the first wave. The first command lists the milestones, and the second lists the labels. A name of the table that your repository uses with another meaning is a clash: rename it on the forge.

gh api 'repos/{owner}/{repo}/milestones?state=all' --jq '.[].title'
gh label list

riff init makes the milestone Backlog, and Wave 1 when the repository has no open wave. It also counts the open issues with no Done when: line: see Find the issues with no Done when line.

Design: the store of riff-server

This page is the design for Wave 15 and release 1.0.0. When the build is done, the big picture and the operations stay in the book. The details go into the rustdoc. The reviews and the report are in design/reviews/.

Target and goals

• The target: dozens of people and dozens of repositories, for 12 months and more. The load is less than 100 requests each second.
• The goals:
  • One instance decides each change, in one tokio runtime.
  • Each change that must not be lost is a record in one log. A start loads a checkpoint and replays the log after it.
  • Each write is small. The start time and each read have a limit.
  • Old records and old sessions go away by a rule.
  • The formats have clear rules for versions, and CI enforces them.
  • The cost is small. We do not operate more services.
• Not goals: more than one instance that serves, a web client, reads of old history, a new wire.

The picture

flowchart LR
    R[riff sessions] -->|JSON over HTTP| S[riff-server<br/>one instance]
    S -->|watch, tail| R
    S --- M[(memory:<br/>the state, the sessions,<br/>the last N messages)]
    S -->|append records| L[(GCS: log chunks)]
    S -->|from time to time| C[(GCS: checkpoint)]
    S -->|when they change| G[(GCS: sign-ins)]
    C -->|at start: load| S
    L -->|at start: replay after the checkpoint| S

The classes of data

Each person who can write the bucket controls the riff. The records of people and settings are not signed. The service account of riff-server and the admins of the cloud project are the only writers.

Event sourcing

riff-server follows the pattern of event sourcing with CQRS. It does not use a framework for it.

flowchart LR
    C[command] --> H["permits, then<br/>handle(pending copy, command)"]
    H -->|"changes, or a refusal"| Q[queue: one entry]
    Q --> P["apply(pending copy, record)"]
    P --> H
    Q -->|writer, outside the lock| L[(log)]
    L -->|written| A["apply(written copy, record),<br/>in order"]
    A --> R["wakes, then the reply<br/>or the error to the caller"]
    A --> V["views: who, top, board"]

• handle(&State, Command) -> Result<Vec<Change>, Refused> checks a command against the state. It does not change the state, and it does no I/O. A Change has no position and no time: the log adds them. The command engine gives the full form: each command is a type, and handle gets the caller and a view.
• apply(&mut Riff, &Record) changes the riff for one record: the state that the log gives. It does no I/O, reads no clock, and does not fail. A record that the state cannot take (for example, a release of a claim that is not there) changes nothing, and the server logs a warning. The live path and the replay use the same apply, so a replay gives the same state as the live server.
• Under the one lock, the engine runs handle, gives each change its position and time, puts the entry of the command in the queue, and runs apply on the pending state. Then it releases the lock. A refused command has an entry too, with no record.
• The writer takes each record in the queue into one chunk: a group commit. It writes outside the lock. So each call runs handle against the state of each call before it, and two claims of one item never both pass.
• A command replies after the writer is done with it: its chunk is written, and each chunk before it. This is also the rule for a command that makes no record, and for one that is refused. A query (who, read, top) does not wait.
• The server keeps two copies of the state. handle checks against the pending state, which has each record in the queue. Each read, wake, view and reply uses the written state, which has only the records whose chunk is written. After each chunk write, the server applies its records to the written state. So nobody sees a record that is not in the log. When a chunk fails for good, the instance stops, and the next instance replays without it.
• A view is a function of the state. It does not change the state.
• The whole riff is one aggregate. So one check can see claims, leads, members and threads together.

Tests

Each rule has a test in this form:

#![allow(unused)]
fn main() {
given(&[invite("ann"), join("ann/s1", "repo")])
    .when(claim("ann/s1", "repo", "issue-7"))
    .then(&[claim_item("ann/s1", "repo", "issue-7")]);
}

• given applies records to an empty state.
• when runs handle with one command.
• then compares the changes, or then_refused compares the error.
• The tests do no I/O, so they are fast. A replay test applies the records of a test log, and compares the state with the state of the live path.
• A test puts two posts in one chunk. A test measures how long each call holds the lock and waits for it.

Why no framework

A framework such as cqrs-es has a stream and a lock in a database for each aggregate, and it loads an aggregate from the store for each command. riff-server has one instance, one log, one aggregate and the state in memory. So a framework adds concepts and code that riff-server does not need. The GCS store is the part that we write in each case.

The log

One log for the riff

• The riff has one log. Each record has a position: 1, 2, 3, and so on. The position gives one order for all records.
• A message also has a seq: its number in its own thread. People and read cursors use the seq. The server keeps the last seq of each thread in memory. It gives each post the next seq, and writes the seq in the record. So each record says where it is in its thread, and a replay can find a gap. See Appendix A.

The records

Each record is one line of JSON. The Rust types in riff-core are the schema. This is an example; see The book shows the real code:

{"position":1234,"written_at_ms":1790000000000,"by":{"session":"ann/s1"},"command":"claim","change":{"claimed":{"session":"riff://ann@host/o/repo?session=s1","thread":"o/repo","item":"issue-7"}}}

• The change names say what happened, in the past tense, for example posted, claimed, released, pause_set. The full list of the kinds, and the caller and the command in each record, are in the design of the command engine.
• A posted record keeps the signed bytes of its message unchanged. See Signed messages.
• The rules for a change of a record:
  • A new field has a default, and the default means “as before”. An old build skips a field that it does not know.
  • Do not change the type or the meaning of a field. Do not use the name of a removed field again.
  • A new kind of change gets a new name. A build that does not know a kind skips the record and logs a warning with its position.
  • A field with a set of named values that can grow has the value other. A build reads a value that it does not know as other. Such a record counts as a skipped record. The kind of a message has this value. A selector that the build does not know is a selector other: it keeps its JSON as it came, and it matches no session (01M3XSF90E9JYYTC13D9THY4WE). A session URI keeps each query part that the build does not know, and such a record counts as a skipped record too (01M3XYYSY536AEJVERBPTQFQYX).
• Each release adds a sample log to the test fixtures, from 1.0.0 on: crates/riff-server/tests/fixtures/1.0.0/. CI replays each fixture of each earlier release.

Signed messages

The signature is the one of today: a JWS with a detached payload, from the device key of the sender. The header carries the public key. The payload is the JSON of Content.

 sig = <header>..<signature>
       header  {"typ":"riff-message","alg":"ES256","jwk":{public key}}
       payload the JSON of Content

Content holds the user and the session of the sender, the lead mark, the thread, the to selectors, the body, the kind and the time (R196).

The posted record keeps the payload bytes and the signature unchanged, and adds the fields that the server owns: the thread seq and the sessions that the message woke.

The server checks each post:

1. It decodes the payload. It refuses bytes that do not decode.
2. It compares the decoded fields with the call: the thread, the user and the session of the sender, the lead mark, the selectors. It refuses a difference. It refuses lead = true from a session that is not the lead.
3. It checks the signature with the key in the header, and checks that the key is the key of the token of the caller (R197).
4. It keeps the payload bytes unchanged. It never encodes them again.

A reader checks the signature over the kept bytes. Then it checks that the thumbprint of the key is the key of a live sign-in of the user of the sender (R199). A message whose sender’s sign-in ended shows as not verified. Then it decodes the bytes to use the fields. It takes the user and the lead mark only from the signed bytes. These are separate steps, and none changes the bytes. So a new field never stops a check. See Appendix B.

The copy check compares a hash of the payload, not the bytes of the signature, because ECDSA gives a second valid signature for the same bytes.

A new signature scheme (a new algorithm or key type) gets a new typ. It comes in two releases:

1. Release N can check the new scheme, but it signs with the old scheme.
2. Release N+1 signs with the new scheme.

riff-server talks only with riff N and N-1. So each build that can talk with the server can check each message. A test fails when a build signs with a scheme that the build before it cannot check. A build that meets a scheme that it does not know shows the message as not verified.

Chunks

• The writer writes the queue to GCS as one new object, a chunk, then empties the queue. It writes at most one chunk at a time. While it writes, new records wait in the queue for the next chunk.
• The name of a chunk is its first position, with zeros in front: log/00000000000000001234.jsonl. So the names sort in log order.
• The first line of a chunk is a header with the format version and the first position. Then each record is one line.
• Each write of a chunk or a checkpoint sends ifGenerationMatch=0, so it never replaces an object.
• A 412 means that another instance writes the log. The instance stops for good, as today (R141).
• A write that fails with a 429, a 5xx, a timeout or a failed token is tried again with a backoff, for 10 s. When the retry gets a 412, the writer reads the object: when its bytes are the same, the write is done. After 10 s, the instance stops for good: it gives 503 to each call, logs one error that names the chunk and the error, and exits. Cloud Run starts a new instance, and it replays from GCS.

The checkpoint

• From time to time (each 1,000 records, or each 60 minutes when records came), the server writes a checkpoint: checkpoint/00000000000000001234-1790000000000.json, with the position and the time of the write. The keep rule reads the day from the name. It holds the state that the log gives up to that position, the read cursors, the last N messages of each thread, and the version of the build that wrote it.
• The server encodes a copy of the state outside the lock.
• A build writes no checkpoint past the first record that it skipped, or that it read with a value other. A build writes no checkpoint while the newest checkpoint comes from a later version. riff server says so. A test runs a new build, an old build, then the new build again, and compares the state. A second test does the same with a pause whose scope the old build does not know. A third test does the same with a message whose kind, selector or session URI the old build does not know.
• The server keeps the last 3 checkpoints, and one checkpoint each day for 30 days.
• The server deletes a chunk only when each kept checkpoint is past it. No rule deletes chunks by age.

Forget a session

A timer writes a session_forgotten record for each session with no sign of life for SESSION_EXPIRY (30 days), after one released record for each claim that the session holds. apply drops the session, its memberships, its lead, and each direct thread whose two sessions are gone. The presence drops its read cursors. apply reads the time from the record, not from a clock.

The start and the replay

sequenceDiagram
    participant S as riff-server
    participant G as GCS
    S->>G: list checkpoint/, load the newest one that reads
    S->>G: list log/ after its position
    loop each chunk, in order
        S->>G: read the chunk
        S->>S: apply each record
    end
    S->>G: load the sign-ins
    alt the load failed
        S->>S: exit; the old instance serves on
    else the load worked
        S->>G: take the lease, wait
        S->>G: read the chunks that came since, apply them
        S->>G: list checkpoint/ again
        opt a checkpoint came since
            S->>G: read the newest one: its position and its version
        end
        S->>G: load the sign-ins again
        S->>S: open the port, serve
    end

• The new instance loads and replays before it takes the lease. It opens its port only after the load works. So a build that cannot load exits, and Cloud Run keeps the traffic on the old revision.
• The start time depends on the size of the checkpoint and the records after it, not on the whole history.
• When the newest checkpoint does not read, the server uses the one before it.
• The claims of a session come back with the log. The 5-minute claim timer of each session starts at the load.
• The old instance can write a checkpoint until it reads the new lease. So the new instance lists the checkpoints again after the wait. When the newest one comes from a later version, it writes no checkpoint past it.

Reads

• read gives at most 50 messages, and a cursor for the next page. riff read --all follows the cursors by itself.
• Memory and the checkpoint keep the last 200 messages of each thread. Nobody reads an older message.
• One rule for each path that gives messages (read, tail, watch): the caller acts as its token, and gets a direct thread only when it is one of its two sessions. Each path has a given/when/then test.

The sign-ins

• A refresh token names its chain and a generation: chain.generation.secret. The server keeps the hash of the current generation of each chain, and of the generation before it for a lost reply. It keeps nothing for older generations.
• A refresh with the current generation gives the next generation. A refresh with an older generation is reuse: the server ends the sign-in. The server checks the DPoP key before the generation.
• A sign-in has one chain: the chain of the person. A session token has no refresh token and no chain. The server gives a session an access token only. Each process of a session swaps the person token for a token of its own, and a swap ends no other token. A swap changes nothing in signins.json.
• The server writes signins.json at most one time each second, when something changed. A sign-in waits for the write. A refresh does not. A revoke waits for the write of its record in the log. After a crash, the snapshot can be one generation behind. So the first refresh of each chain after a start takes the current generation, or the next one, as good.
• While a write of signins.json fails, a refresh gets 503. So the snapshot does not fall more generations behind.
• signins.json holds only the sign-ins. The people (the owner, the admins, the members) and the riff ID are in the log. Each sign-in keeps the position of the log at its start. A load drops each sign-in from before the last removal or revoke of its person. See “What stays outside” in the engine design.
• Access tokens and DPoP replay IDs are in memory. After a start, each client refreshes one time. A new instance refuses each DPoP proof from before its start.

Live messages

• Watch and tail get new messages through channels in the memory of the instance. The server finds a missed wake in its memory.
• Each stream sends its first bytes when it opens, and a keep-alive.

The lease

• lease names the instance that serves. A new instance writes its ID, waits, then serves. An instance that sees another ID stops.
• Each start has a gap of about 15 s. The client waits through the gap. When a call waits for more than 1 s, the client shows one line that it waits. riff top and riff chat keep their screen. The client gives up after 60 s, as today.
• On Cloud Run, the front end holds each call in the gap. On one machine, the port is closed in the gap, and each connect is refused. The client tries a refused connect again only when its process got a reply from the server before. A new process cannot tell a server that starts from no server, so it fails at once.

The wire

• The wire is the one of today: JSON over HTTP on /v1, the watch and tail streams, DPoP, and the riff-build header on each reply.
• The Rust types in riff-core are the schema of the wire, the log, the checkpoint and the sign-ins.

The book shows the real code

• The book does not copy code. It includes the real files with mdbook anchors, so a change of the code changes the book:

  {{#include ../../crates/riff-core/src/record.rs:record}}
  

• Each file marks the parts that the book shows with // ANCHOR: name and // ANCHOR_END: name.

• just book fails on an ERROR line of mdbook. A test in the hygiene crate reads docs/book/*.html. It fails on an include line that mdbook left in the text, outside a code block, and on an empty code block. An example of an include in a code block, as above, is escaped, and the test skips it.

Tools

• riff-server log prints the records of the log as text, from a position (--from POSITION).
• riff-server log verify reads each chunk and each checkpoint from the oldest kept checkpoint, and names each line that does not read.
• riff-server log cut --after POSITION --yes deletes each chunk and each checkpoint after the position. It writes the chunk that holds the position again, with only its first records. It prints the records that it removes, and the threads. It refuses to cut before the oldest kept checkpoint when the chunks before it are gone, and while a server holds the lease. With no --yes, it removes nothing.
• The tools take a token from the metadata server of Cloud Run, or from the Google sign-in of the person (gcloud auth print-access-token). So they run on a laptop too.

Operations

Set up

riff cloud create does each step. When you run it again, it changes nothing.

1. A standard bucket in the region of today, with object versioning on.
2. A lifecycle rule: delete older versions of each object after 7 days.
3. The riff-server service account can read and write objects in the bucket.
4. --memory 1Gi on the Cloud Run service. Each deploy sets it too.
5. An alert on severity>=ERROR in the log of the service, with an email to the owner (RIFF_OWNER).

Cost

The numbers come from design/measures.md: the load of 2026-09-29, 2 people, scaled to 36 people with 8 live sessions and 20 new session IDs each day for each person. The prices are the list prices of GCS Standard in us-central1: $0.005 for each 1,000 writes, $0.020 for each GB each month. Make sure of the prices when you set up.

• The GCS write time is not measured. riff server shows the time of the last chunk write.
• The direct threads are most of the checkpoint: about 24,800 of them at 36 people.
• The checkpoint settings: keep “each 1,000 records”. Change “each 10 minutes” to “each 60 minutes”. At 36 people, a checkpoint each 10 minutes keeps about 170 GB of older versions, for $3.40 each month.
• The Cloud Run instance, which always runs, stays the largest cost.

Monitoring

riff server shows these facts, from GET /v1/server. The call answers also while the server replies 503 to each other call:

• serves, or 503 and why; the last error,
• the log position, and the time and the duration of the last chunk write,
• the number of write errors and skipped records since the start,
• the position, the age and the version of the newest checkpoint, and why this build writes none,
• the numbers of chunks, sessions, cursors, threads and live sign-ins,
• the memory in use,
• the start time of the instance, and how long the replay took.

Each log line of riff-server is JSON with a severity field, so a Cloud Logging filter finds the errors. An alert on severity>=ERROR goes to the owner.

Backup and restore

• Object versioning keeps each older version of an object for 7 days.
• To go back to a position:
  1. Stop the server: riff cloud delete shared.
  2. riff-server log verify, to find the first bad record.
  3. riff-server log cut --after POSITION. A cut loses each change after the position: the tool names them. Then the same command with --yes.
  4. Start the server: riff cloud deploy shared vX.Y.Z.

Deploy and rollback

• The rules for a change of a record, and the fixtures in CI, make sure that an older build reads the records of a newer build, and the other way. So a rollback to N-1 works.
• A rollback of riff-server past a release line is also a rollback of each machine: riff update --tag.
• A machine that is newer than the server can stay. Then the server refuses the kind riff of a line that riff writes in riff chat, so riff posts the line again with the kind message and the mark [by riff] at the start of the body. No line of riff is lost. The lead still skips such a line when it looks for the approval of the owner.

sequenceDiagram
    participant R as riff (newer)
    participant S as riff-server (rolled back)
    R->>S: post a line of riff, kind riff
    S-->>R: refused: no such kind
    R->>S: post again, kind message, body "[by riff] ..."
    S-->>R: posted
    Note over R: riff release approve skips the line

Local development

• riff-server with no bucket keeps the log in memory.
• With RIFF_DIR, it keeps the log and the checkpoints as files in that directory. The tests use a temporary directory or memory, never the real bucket.

Go live

Go live is one release at a wave end of the riff repository. The riff is paused. Another repository can hold claims: they stay.

1. The lead writes its handoff in the release issue on GitHub, not in the riff.
2. The tag deploys the new server. It keeps the riff ID, and it starts paused.
3. The new server reads the old objects one time, and writes the records of the import. See The import of go-live. So nobody invites a member again, and each claim and each lead stays.
4. Each machine updates itself: the old riff sees the new build in the riff-build header of each reply.
5. No person signs in again: a refresh token of today works one time on the new server, and gives a token of a new chain.
6. Each lead is the lead as before. It reads its handoff from the release issue. The owner or an admin resumes the riff.
7. The old objects (sessions, tokens, threads/) stay until the first wave after go-live ends, for a rollback. Then the lead deletes them. The new server uses the same lease object, so an old and a new instance never serve at the same time.

The steps for the person who deploys are in Go live with release 1.0.0.

Build items

Items 1 to 3 need nothing, and run at the same time. Items 4 to 9 run one after another, in this order. They change the same code.

1. Measure the load of today: the records each day by kind, the size of the state, and the p50 and p99 of a GCS write from Cloud Run. Take 8 live sessions and 20 new session IDs each day for each person. Update the cost table.
2. Removed in 4.0 (#1173).
3. just book fails on a missing include or anchor.
4. The log: handle, apply and the given/when/then tests; the records as JSON lines; the writer with a group commit outside the lock; the replies after the write; the retry and the stop; the replay; the stores for memory, a directory and GCS; the rule for who reads a thread.
5. The checkpoint: the start from a checkpoint, the version rules, the last N messages, read with pages, the delete of chunks by checkpoint, and the forgotten sessions.
6. The sign-ins: chains with generations, the snapshot.
7. The start order: load, then the lease, then the port.
8. The tools (riff-server log, log verify, log cut), the facts in riff server, the JSON log lines and the alert, cloud setup, and the book (operations, restore).
9. Go live: one release, at a wave end (see “Go live”).

Decisions

1. The wire stays JSON over HTTP. No gRPC.
2. The log, the checkpoint and the sign-ins are JSON. No protobuf.
3. A standard bucket. No zonal bucket, and no compaction.
4. The log keeps each chunk that a kept checkpoint needs. No rule deletes chunks by age.
5. The server writes a checkpoint each 1,000 records, or each 60 minutes when records came (settings). See “Cost”.
6. The default rule for a new field is a requirement.
7. We go live at a wave end, and import the state of today one time: the people, the sessions, the claims, the leads, the settings and the messages.

Appendix A: position and seq

A message has two numbers:

• The position: its place in the one log. It counts each record, of each kind, in each thread.
• The seq: its number in its own thread. It counts only the messages of that thread.

An example of the log:

• People see the seq: “message 287” in the repo thread, “message 51” in chat. The positions of one thread have gaps (1041, 1045).
• A read cursor is a seq for each thread. The unread count is the last seq less the cursor.
• A replay checks the positions: each record is the last position plus
  1. A gap or a repeat shows a bad or a missing chunk. riff-server log verify finds it.

Appendix B: signed messages over versions

A new field

Release 1.1 adds reply_to to Content.

Why the server keeps the bytes

When a 1.0 server decodes a 1.1 message and encodes it again, it drops reply_to, because it does not know it. The new bytes are not the signed bytes, and each later check fails. So no build encodes the payload again.

A field that limits a message

A new field that limits the meaning of a message (for example, “only for this worktree”) needs a new signature scheme. Else an old build shows the message with a wider meaning.

A new signature scheme

When N+1 signs with the new scheme, the server talks only with N and N+1, and each of them can check it.

Design: the command engine of riff-server

This page is the design of the command engine for release 1.0.0. It builds on the store: one log, handle, apply, and the writer. Three reviews are in design/reviews/ (engine-01 to engine-03), and the decisions are at the end of this page. When the build is done, the big picture stays in the book, and the details go into the rustdoc.

Goals

• One path: each call that changes the state of the log goes through one dispatch.
• One trace: each command leaves its records, or one log line.
• A worker clears its context between two items. handle refuses a claim that is against this rule.
• The compiler enforces the order of the stages. A handler cannot reply before the write.
• Release 1.0.0 fixes the format of the log. So this page names each record kind.
• Not goals: a new wire, a new store, more than one instance.

The terms

One path

flowchart TD
    C[call with a token] --> A["authenticate:<br/>Authenticated&lt;C&gt;"]
    A -->|denied| D[log line: denied] --> E0[401 or 403]
    A --> K{kind of call}
    K -->|query| Q["view of the written copy"] --> QR[reply]
    K -->|signal| P["presence in memory"] --> QR
    K -->|command| H["permits, then handle<br/>under the lock: Checked"]
    H -->|"accepted, or refused"| U["Queued: positions, the entry in the queue,<br/>apply to the pending copy"]
    U --> W["the writer writes the chunk<br/>outside the lock"]
    W -->|failed for good| J3[log line: failed] --> S[503, the instance stops]
    W --> AP["the writer applies the chunk<br/>to the written copy, in order"]
    AP --> F["the writer: the log line of a command<br/>with no record, the effects"]
    F -->|"Applied, accepted"| R[the call makes the reply<br/>from the written copy]
    F -->|"Applied, refused"| E[error to the caller]

• The engine is the only code that locks the state. Its one entry for a change is Engine::dispatch. Its one entry for a signal is Engine::signal.
• Each command is a type that implements the trait Command. The trait gives the kind, the type of the reply, handle and reply. A command that a client can send also implements Routed, which gives the HTTP path. One generic handler serves each routed command. A new command is one type and one line in the list of routes.
• handle checks the command against the pending copy. It does no I/O and changes nothing. It gives the changes and a note for the reply, or the reason for a refusal. The writer makes the effects from the written records: the wakes and the tail event of each posted record.
• The writer finishes each command. It writes the chunk, applies the records of the chunk to the written copy in the order of their positions, writes the log line of a command that made no record, and sends the effects. The call only waits, and makes the reply. A call that the client drops loses only its reply.
• Each command waits until the writer is done with its entry in the queue. The queue is in order, so each entry before it is done too. This is one rule for each command, also for a command that makes no record, and for a command that is refused: a refused command has an entry with no record. So no reply and no refusal tells of a change that is not in the log.
• A call can be a command and a signal: a register sets the place, and an end ends the session. The trait Command has the method signal, which gives the signal of the call, or none. The engine sets it in the presence at the check, under the same lock, also when the command makes no record. A refused command sets no signal.
• The server is a caller too. Each timer sends a command as the caller server: forget the old sessions, grant a request for the owner role, end the role of an owner who is gone, post a note of the server, name the owner of the settings. The engine has one function for each command of the server: Engine::make_riff, Engine::announce, Engine::forget, Engine::import, Engine::name_owner, Engine::grant_owner and Engine::end_owner. The function makes the Authenticated value inside the engine module. Engine::sign_in sends the command admit of the token path, with the proof of the sign-in (01M3XA877YZQ649SWB5TN60V5P).
• Engine::make_riff goes through the same stages as Engine::dispatch (Engine::send: the check and the entry), and does not wait for the write: the build of a service is not async.
• Two signals of the server are no call of Engine::signal: the end of a watch stream (Engine::watch_ended) and the ask to stop an idle worker (Engine::stop_idle_workers). They are no call of a session, so they register nothing and they count as no call. Each one changes only the presence, under the lock of the engine.
• The first start of a riff sends the command make_riff of the server, with the ID of the riff. It makes the riff_made record, and a pause_set record that pauses the riff. make_riff never replaces an ID that the riff has (01M3XA87HE06Z6M32ZJPSYSYRZ): in a log with records and no ID, it makes only riff_made. At go-live, the command import makes the riff_made record with the ID of the riff of today, and the server sends no make_riff.
• A call from a session that the state does not know first runs the command register for that session, also when the call is a query or a signal. It is a command of its own, with an entry of its own: its records name register, and they have a session_started record with the reason join. In the code it is the type Arrive, with the kind register: it keeps the worker mark of the state, and it makes no lead. Engine::check runs the two handle functions under one lock. A query of such a session waits for that write, then reads the view. A signal of such a session first sends register through Engine::dispatch and waits for it, then sets the signal. An end of such a session registers nothing.
• The first register of a caller that the state does not know runs before permits of its command. So the session is registered also when its command is refused. A caller that the state knows gets the signal Called at the check, also when its command is refused: a refused call is a sign of life.

The callers

• The token layer makes the caller, with its class. Engine::check adds the worker mark and the role (member, admin or owner) under the lock, before permits. A session that the state does not know is not a worker.
• The role of a command comes from the people of the pending copy, with the admins of the settings (01M3XA87F70CD3WH4STADSCW6S). The queue is in order. So a command that comes after admin_set in the queue gets the new role, and the log never shows a change by a person who had no role for it. A query reads the people of the written copy.
• A build reads a class of caller that it does not know as other.
• A riff with no sign-in trusts its network. The caller is then the me of the body, with the role of an admin. Such a riff has no people: Engine::check refuses each command of the group “people” there, before permits, with the code no_sign_in. The refused command has its entry in the queue, as each refused command. A call whose body names no me needs a token: the caller is then the caller of the token (01M3WRD9G5GAF65EX8P6D5DMQM).
• The role of a caller with no token comes from the trust of the riff (01M3X4Z6G0TG0B4FT2N1FSPDHS): an admin in a riff with no sign-in, else a member.

The commands

• make_riff, announce, forget, import, grant_owner, end_owner, name_owner and admit are not Routed. No HTTP call can send them.
• pause, resume and set_idle each have a path of their own: /v1/pause, /v1/resume and /v1/idle/set. A read of the pause (/v1/riff) or of the idle setting (/v1/idle) is a query.
• The path and the reply type of each routed command are in riff-core, next to its wire type: the trait Call. The server and the client use the same ones.
• The wire changes in these places: start gets the fields reason and worker (E4); pause, resume and set_idle get paths of their own; join and leave, and claim, release and release_for, each get a wire type of their own; the reply to a claim has no granted. The client and the server are one release.
• A kind is never renamed, and the name of a removed command is never used again. A file in the fixtures lists each kind of each release.
• Each group has one file in crates/riff-state/src/state/, with its part of the riff, its apply arms, its part of the checkpoint and its commands. The record session_forgotten of forget changes each part, so its arm calls each part. The rustdoc of the module state says where each part lives.
• The wire type of each routed command is its command type.
• The lead of a user frees the claim of another session of that user with release_for, a command of the group work with the path /v1/release/for (01M3WRD9MGSC3FTBAANT4ZSMKY). Its note of the server is a posted record in the chunk of the command.

Who can send a command

One function, permits, holds this table. It reads only the caller: its class (person, session, sign-in, server), its worker mark, and its role (member, admin, owner; the owner has the role of an admin too). It does not read the state. The engine calls it before handle, and its refusal has the code not_allowed. A kind with no row does not compile. One test runs each command as each class, mark and role, and compares the result with the table. Each command gives the role that it needs (Command::needs), and permits compares it with the role of the caller.

The engine registers the first call of a person too, so register has the class of a person.

Command::needs gets the caller, only to know if the command names the caller: a revoke with no name, or with the name of the caller, ends the own sign-ins. A command that needs the owner in a riff with no owner gets the text “the riff has no owner; an admin takes the owner role with: riff owner –take”. permits reads only the caller, so State::check puts that text in its refusal.

/// Says if `caller` can send a command of `kind` that needs the role
/// `needs` (01M3WRD959DYNZHDKP5ZT9Q1C7). It reads only the caller: its
/// class, its worker mark and its role. It does not read the state.
/// Each kind has a row with its classes and its worker rule: a kind
/// with no row does not compile (01M51JBTEM10W68K6F267BB79N). The life
/// cycle of a session is a check of `handle`, not of this table.
///
/// ```
/// use riff_core::name::SessionUri;
/// use riff_state::state::{Caller, Code, CommandKind, Role, permits};
///
/// let session: SessionUri = "riff://mike@pangolin/como-technologies/riff?session=a6cf".parse()?;
/// let session = Caller::of(&session);
/// assert!(permits(CommandKind::Claim, &session, Role::Member).is_ok());
/// // Only the server forgets a session.
/// let refused = permits(CommandKind::Forget, &session, Role::Member).unwrap_err();
/// assert_eq!(refused.code, Code::NotAllowed);
/// // A session cannot name the lead, also not itself.
/// assert!(permits(CommandKind::Lead, &session, Role::Member).is_err());
/// // A change of the idle workers needs a person who is an admin.
/// let person: SessionUri = "riff://mike@pangolin".parse()?;
/// let person = Caller::of(&person);
/// assert!(permits(CommandKind::SetIdle, &person, Role::Admin).is_err());
/// let admin = person.with_role(Role::Admin);
/// assert!(permits(CommandKind::SetIdle, &admin, Role::Admin).is_ok());
/// assert!(permits(CommandKind::SetIdle, &session.with_role(Role::Admin), Role::Admin).is_err());
/// # Ok::<(), riff_core::name::NameError>(())
/// ```
pub fn permits(kind: CommandKind, caller: &Caller, needs: Role) -> Result<(), Refused> {
    use Class::{Person, Server, Session, SignIn};
    use Workers::{Can, Cannot};
    let class = caller.class();
    let (classes, workers): (&[Class], Workers) = match kind {
        // The engine registers the first call of a person too. A person
        // has no life cycle.
        CommandKind::Register => (&[Person, Session], Can),
        CommandKind::Start | CommandKind::End => (&[Session], Can),
        CommandKind::Join | CommandKind::Leave | CommandKind::Post => (&[Person, Session], Can),
        CommandKind::Claim | CommandKind::Release => (&[Person, Session], Can),
        // `handle` checks that the caller is the lead of the user of
        // the holder.
        CommandKind::ReleaseFor => (&[Session], Can),
        // Only a person names the lead (01M5NJAXTQ0YKN7Q7XN0A7ZMPF).
        // `handle` refuses a worker as the new lead.
        CommandKind::Lead => (&[Person], Can),
        // The command gives the role: an admin for the whole riff.
        // `handle` checks that a session is a lead.
        CommandKind::Pause | CommandKind::Resume => (&[Person, Session], Can),
        // `handle` checks that the caller is a lead of the thread, the
        // owner or an admin (01M43GSGGY0QMB5D5EH92M6ZFP).
        CommandKind::Hold => (&[Person, Session], Cannot("hold an item. Tell the lead.")),
        CommandKind::Free => (&[Person, Session], Cannot("free an item. Tell the lead.")),
        // `handle` checks that the caller is a session in the thread, the
        // owner or an admin (01M4A4YTWK68JDA0DKXX2HV4FA).
        CommandKind::Plan => (&[Person, Session], Cannot("send plan. Tell the lead.")),
        CommandKind::PlanOff => (&[Person, Session], Cannot("send plan_off. Tell the lead.")),
        // The notes of the user of the caller (01M59258NTXPMWV18TKRKWNTYN).
        CommandKind::Notes => (
            &[Person, Session],
            Cannot("write the notes of the lead. Tell the lead."),
        ),
        // Only a person changes the settings and the people.
        CommandKind::SetIdle
        | CommandKind::Invite
        | CommandKind::Remove
        | CommandKind::SetAdmin
        | CommandKind::PassOwner
        | CommandKind::TakeOwner
        | CommandKind::DenyOwner
        | CommandKind::Revoke => (&[Person], Can),
        CommandKind::Admit => (&[SignIn], Can),
        CommandKind::MakeRiff
        | CommandKind::Announce
        | CommandKind::Forget
        | CommandKind::Import
        | CommandKind::GrantOwner
        | CommandKind::EndOwner
        | CommandKind::NameOwner => (&[Server], Can),
    };
    if !classes.contains(&class) {
        let reason = match (kind, class) {
            (CommandKind::Lead, Session) => LEAD_BY_PERSON.to_owned(),
            _ => format!("{} cannot send the command {kind}", class.text()),
        };
        return Err(Refused::new(Code::NotAllowed, reason));
    }
    if let Cannot(what) = workers
        && caller.worker()
    {
        return Err(Refused::new(
            Code::NotAllowed,
            format!("a worker cannot {what}"),
        ));
    }
    if class.has_role() && caller.role() < needs {
        let user = caller.who().user();
        let admin = |what: &str| format!("{user} is not an admin; only an admin {what}");
        let owner = |what: &str| format!("{user} is not the owner; only the owner {what}");
        let reason = match (kind, needs) {
            (CommandKind::SetIdle, _) => admin("can change the settings of idle workers"),
            (CommandKind::Pause | CommandKind::Resume, _) => format!(
                "{user} is not an admin; only the owner or an admin can {kind} the whole riff \
                 or a repository by its name"
            ),
            (CommandKind::Invite, _) => admin("can invite a person"),
            (CommandKind::Remove, _) => admin("can remove a person"),
            (CommandKind::TakeOwner, _) => admin("can take the owner role"),
            (CommandKind::Revoke, _) => admin("revokes another person"),
            (CommandKind::SetAdmin, _) => owner("adds or removes an admin"),
            (CommandKind::PassOwner, _) => owner("passes the owner role"),
            (CommandKind::DenyOwner, _) => owner("denies the owner role"),
            (_, Role::Owner) => format!("{user} is not the owner; the command {kind} needs it"),
            _ => format!("{user} is not an admin; the command {kind} needs an admin"),
        };
        return Err(Refused::new(Code::NotAllowed, reason));
    }
    Ok(())
}

A pause or a resume of a repository that the call names needs an admin too. handle makes each check that reads the state: a session pauses only when it is a lead, a worker in MustClear cannot claim, a caller releases only what it holds. See “The moves that handle refuses”.

No session is the lead by itself, and a session cannot send lead: only a person names the lead. A worker is never the lead. When a person names no lead in a repository, that person has no lead there: tell lead fails, and each session asks in its own terminal.

What stays outside

• The state has two parts with two types: the riff (the state that the log gives) and the presence (memory). View holds the two, read only. A signal is a value of the type Signal, and Signal::set gets &mut Presence only. So a signal cannot change a claim or a lead.
• A record changes the presence only in Presence::applied: a session_forgotten record removes the session and its cursors, a claimed or a released record sets the time of the last change of the claims, and a pause_set record sets the time for a stale status, for the riff or for its repository. The writer calls apply(&mut riff, record) and then Presence::applied, with the record, the riff after the apply, and the time of the call that made the record. A replay gives no time, and then Presence::applied sets no time.
• A session whose item another session takes has a released record of its own (01M3X4Z6BKM251H7CS2CEGR205). So Presence::applied reads only the record and the riff.
• who shows the time of a change after the write of its record: each reader sees the written copy.
• A status is a signal. The wire type refuses a bad text. A register is a signal (the place) and a command (the join of the repository thread). An end is a command (it frees the claims) and a signal (the session ended).
• The first sign-in of a person changes the people: it gives the user its email, and it can make the first owner. The token path sends the command admit for it, with the sign-in as the caller. Then it makes the chain. admit makes no record for a person that the state knows.
• A remove and a revoke end sign-ins. The end of the sign-ins is an effect after the write: the writer does it, and its word to the call has the number of sign-ins that ended, for the reply (01M3XA87A9GGFA89RQXWSKY0V6).
• Each sign-in keeps the position of the log at its start: the position of the pending copy at the check of its admit. The effect ends each sign-in of the person from before the position of the record. In the same step, under the lock of the token store, the store keeps that position for the person, and it starts no sign-in of the person below it. So a sign-in that is in flight when a remove comes does not stay, at each point of the removal.
• When a load finds a sign-in whose position is less than the position of the last member_removed or signins_ended record of its user, it drops the sign-in. So a stop between the write and the effect lets no removed person in.
• A load also drops each sign-in that the log does not hold (01M3XGNZYD1E35DXYTHHJT1CR7): its position is after the position of the log, or the people do not know its user. A log that went back to an earlier position gives such sign-ins, for example after log cut. The person signs in again.
• The token layer gives the engine the position of the sign-in of each token. Engine::check refuses each command of a caller whose sign-in started before the last end of the sign-ins of its user in the pending copy, before permits (01M3XGP03RDF6S15JYS718WWFC). So between the entry of a removal in the queue and the effect, the removed person changes nothing, also not through a session.
• admit checks first if the person may join, and then the USER of the email (01M3XGP011KGXDP9D1FNMT374F). A person who may not join gets not_member.

sequenceDiagram
    participant P as sign-in of bob
    participant E as engine
    participant W as writer
    participant T as token store
    P->>E: admit: checked at the position 7
    Note over E: an admin sends remove (bob)
    E->>W: member_removed at the position 8
    W->>T: end (bob, 8): the position of bob is 8
    P->>T: start (bob, 7)
    T-->>P: refused: 7 is before 8

• The setting --owner is the command name_owner of the server. It runs one time after the load, and makes an owner_set record when the riff has no owner and had none. The server sends it only in a riff with sign-in.
• The settings that handle and reply read are not in the log: the admins of the settings, the public address (the reply to an invite names it) and the times of the owner role. View holds them. The admins of the settings add to the role of the caller.
• “The old owner stays an admin” is a decision, so handle makes it (01M3XA87KQ6ESMQ4W1W1PTW766): member_invited and admin_set for the old owner come before owner_set, in the same chunk. apply of owner_set stores only the owner. set_admin for a person who is not a member gives member_invited, then admin_set.
• take_owner, deny_owner, grant_owner and end_owner put their notes in their chunk as posted records. pass_owner posts no note of the server: riff posts it. The warning to the owner is an announce: it is no change of the people.

The trace of a command

The log is the truth for each change. Each record names its cause: the envelope has the caller (by) and the kind of the command (command). So the log alone shows who made each change, and riff audit reads only the log.

{"position":1234,"written_at_ms":1790000000000,"by":{"session":"mike/a6cf"},"command":"claim","change":{"claimed":{"session":"riff://mike@pangolin/como-technologies/riff?session=a6cf","thread":"como-technologies/riff","item":"issue-355"}}}

• The records of one command are in one chunk, one after another (01M3X4Z60G1FXQTDC5XDJ05BAX). State::queue gives the records of a command their positions and their cause under one lock, and the writer takes whole entries of the queue.
• A record from before E2 has no by and no command. It reads, and its cause is not known. riff-server log prints the cause of each record.
• A note of the server that a command causes is a posted record in the chunk of that command, with the by and the command of the cause. The sender of the message is the server.
• The session in a change is a full URI: it holds the place at the time of the record. by holds only the user and the session ID.

A command that makes no record gives one log line of riff-server. The line has the format of each other log line (severity, time, message, target), and these fields:

{"severity":"INFO","time":"2026-10-01T12:00:00Z","target":"engine","message":"refused","caller":{"session":"mike/84cf"},"key":"0f3a…","command":"claim","result":"refused","code":"held","reason":"issue-355 is held by mike/a6cf"}

• The writer makes the lines refused, no_change and failed (Engine::finish and Engine::fail, 01M3X4Z62RJREQ5H8F18Y85T6V). The token layer makes the line denied (01M3X4Z64ZNRD0G0F4JV1M64FN). The module crates/riff-server/src/trace.rs holds each line.

• failed: one line with the severity ERROR for each command of a chunk whose write failed. A command that waits in the queue when the server stops gets a failed line with the severity WARNING, and the reason of the stop: its chunk did not fail. So a stop for a lost lease, as at a deploy, sends no alert email.

• At a stop signal, the server first writes what waits: shutdown closes the gate, and then waits until the writer is done with each entry of the queue (Engine::settle), while the instance holds the lease. So a normal stop gives no failed line.

• A refusal has a code and a reason as text. A test of a refusal compares the code. The codes of this release: not_allowed (the class or the role of the caller), no_sign_in (a command of the people in a riff with no sign-in), held, paused, must_clear, not_holder, other_user, not_member (the command names a person who is not a member), bad_request (the fields of the call do not agree, for example the signed fields of a post). A release can add a code. A reader takes a code that it does not know as text. The enum Code has each code of this list. must_clear gets its first use in E4. The reply to a refused command has the code in the header riff-refused, and the reason as its text (01M3WRD9JBQMNN96TXJH8EAJ3W).

• The HTTP status of a refused command comes from its code (01M3X4Z69CFV23V4QZBE8RP1GJ):

  Status	Codes
  403	not_allowed, no_sign_in, not_member
  409	held, paused, must_clear, not_holder, other_user
  400	bad_request

• A denied line has no caller. It has named (the caller that the call named), proved with the value false (no token proved the name), path in the place of command, and a code. It has no reason. These codes are codes of the token layer only. They are not codes of a refused command:

  Code	When	Status
  no_token	The call has no token.	401
  bad_token	The server does not know the token, or the token expired.	401
  bad_proof	The proof of the device key is refused: 401. The signature of a post is refused: 403.	401, 403
  not_you	The token may not act as the me of the body.	403
  old_build	The build of the client is too old or too new.	409

• named is the me of the body, or the uri of the query. The server reads the body for it only after it refused the call, and at most 64 KiB of it. A call with a longer body, or with no name, gives a line with no named. A name that is no session URI is text: {"text":"..."}. A name of more than 200 characters is cut, and the line then has named_cut with the value true. A line break in a name is escaped, so the line stays one line.

• The cost of a refused call has a bound. Two constants of trace.rs hold the limits:

  Limit	Constant	Value
  The time of the read of the body	BODY_TIME	2 seconds
  The denied lines in one window	DENIED_MAX in DENIED_INTERVAL	100 lines in 10 seconds
  The lines of a window kept for a valid token	DENIED_KEPT	20 lines

flowchart TD
      R[the token layer refuses a call] --> V{"a valid token?<br/>not_you, bad_proof"}
      V -->|yes| W{"fewer than 100 lines<br/>in this window?"}
      V -->|no| K{"fewer than 80 lines<br/>in this window?"}
      W -->|yes| B["read the body for the name:<br/>at most 64 KiB, at most 2 seconds"]
      K -->|yes| B
      B --> D[line: denied]
      W -->|no| N["no read, no line:<br/>the count of the code goes up"]
      K -->|no| N
      N -->|"the window ends,<br/>or the server stops"| C["line: dropped, with the count<br/>and the count of each code"]
      D --> S[the same reply]
      N --> S

• The time limit (01M3Z67B9RMVKY7TCXCG8HEZT4): the server reads the body for named for at most 2 seconds. After it, the line has no named. When the read stops before the end of the body, at the time limit or at 64 KiB, the reply has the header connection: close, and the server reads no more of the call.

• The limit of rate (01M3Z67DZX9BC3TYF3PWGFGZJ7): the server writes at most 100 denied lines in each window of 10 seconds. A window starts at the first refused call after the end of the last window. Over the limit, the server writes no line and does not read the body. At the end of a window with such calls, a timer writes one line with the result dropped, the severity WARNING and count: the number of denied lines that the server did not write. The line also has counts: that number for each code (01M419Z1RM0TDJ50F6SEJC40GB). So a window has at most one dropped line. A stop of the server ends the window, so no count is lost.

  {"severity":"WARNING","time":"2026-10-01T12:00:10Z","target":"engine","message":"dropped","result":"dropped","count":920,"counts":{"no_token":918,"not_you":2}}
  

• The kept lines (01M419Z1V3YT48PR2NTFYWAXG9): the last 20 lines of each window are for a call with a valid token, with the code not_you or bad_proof. A call with no token, a bad token or an old build takes a line only from the first 80. So a flood of calls with no token does not hide a member that acts as another session.

• The count is one count for the whole server. Behind Cloud Run, the server knows no address of a caller that it can trust. So many refused calls of one caller also take the lines of each other caller in that window. The request log of Cloud Run still holds each call.

• The limit also holds for the old_build lines. At go-live, each client of v0.8.0 gets a refusal for each call until its update. The server then writes at most 100 of these lines in 10 seconds, and the dropped lines hold the count of the rest.

• The limits change only the lines. The reply to a refused call has the same status and the same text with a line and with no line.

• key is the thumbprint of the device key of the token. It is not a secret. A call with no token has no key.

• A line never holds the body of a post, a token or a key (01M3X4Z675D0ZQX93E93F3M8FA). A test runs each command with a marked body and a marked token, and finds no mark in the lines.

• A line never holds an email (01M3XA87CJHCGZX283ZQAFKARZ): the people are personal data. An email is in a record, and in a reply to a member. The reason of a refused command of the people can name an email, so its line has the code and no reason. The line of a sign-in names its USER: {"sign_in":"mike"}. A test runs each command of the people with a marked email, and finds no mark in the lines.

• A command with records gets no line. A signal and a query that the token layer accepts get no line. The request log of Cloud Run holds each call with its path and its status.

• The lines are best effort: a stop between the result and the line loses the line.

• The log shows who did what for as long as it keeps its chunks: about 30 days (see “The checkpoint” in the store design).

The life cycle of a session

The state that the log gives holds the life cycle of each session. Records move it, so a replay gives the same state. Presence (live, gone, ended) is a different thing: it is in memory, and it says only if the session is there.

stateDiagram-v2
    [*] --> Ready: the first record that names the session
    Ready --> Working: claimed
    Working --> Working: claimed, or released with a claim left
    Working --> Ready: the last claim goes, and not by a release of a worker
    Working --> MustClear: a worker releases its last claim
    MustClear --> Ready: session_started (process, clear)
    Ready --> [*]: session_forgotten
    MustClear --> [*]: session_forgotten
    Working --> [*]: released for each claim, then session_forgotten

• handle decides, and the record holds the decision: the released record of the last claim of a worker, made by its own release, has must_clear. apply only stores it. A session_started record with a fresh context ends it.
• A claim that goes in another way leaves the worker Ready: a start, an end, or a claim of another session after the 5 minutes of the claim timer. So a worker that a person resumes in the middle of an item claims its item again and goes on.
• A session_started record has a reason: process (a new agent process), resume, clear, or join (the session comes with no new start). process and clear are fresh starts. The record also says if the session is a worker.
• The start call carries the reason and the worker mark. An explicit register whose worker mark is not the mark of the state makes a session_started record with the reason join and the new mark. A register of a session that the log does not know makes one too. The register that the engine runs first keeps the mark of the state.
• The worker mark is a fact of the riff, not of the presence. handle and permits get it from the pending copy, and who from the written copy.
• The start sends the reason from the source of Claude Code: startup is process, resume is resume, clear is clear. It sends no start for compact: a compaction is no new session, so the session keeps its claims and its lead, and a worker in MustClear stays there.
• A start frees each claim of the session: one released record for each, then the session_started record. An end frees each claim too. The log has no record for the end itself.
• A claim that takes an item whose holder is gone gives a released record for the old holder, then the claimed record, in one chunk.
• forget gives one released record for each claim of the session, then the session_forgotten record. That record says that each thing of the session goes: apply removes the session, its places in the threads and its lead.
• The state keeps the time of the last fresh start of each session: the time of its last session_started record with a fresh context.
• A person has no session ID and no life cycle. A person can claim and release.

The moves that handle refuses

permits refuses a lead of a session, before handle. handle refuses a worker as the new lead.

The clear of a worker

sequenceDiagram
    participant W as worker
    participant S as riff-server
    participant L as lead
    W->>S: release (the last claim)
    S->>S: released with must_clear: the worker is in MustClear
    S-->>W: reply: riff clears your context when your turn ends
    L->>S: tell the worker: request: claim issue-12
    S->>S: posted. The wake waits.
    W->>W: the turn ends: the check starts
    W->>S: keep-alive
    S-->>W: reply: clear
    W->>W: riff types /clear
    W->>S: start (clear)
    S->>S: session_started (clear): the worker is Ready
    W->>S: watch
    S-->>W: the wake that it missed
    W->>S: claim issue-12

• The clear comes when the turn of the worker ends, not at the release. So a step of an item that comes after the release, for example the removal of the worktree, runs before the clear.
• The reply to a keep-alive of a worker in MustClear tells riff to clear its context. A check of a worker sends one keep-alive, and types the clear when the reply asks for it (01M3XV0562D3H3P22CJDBPAZBH, crates/riff/src/next.rs). So the clear does not depend on the reply to the release, or on a call of the worker. The reply to the release carries the ask too: riff shows it in the text of the release.
• The engine sends no wake to a session in MustClear. The message is in its thread, and its posted record names the session in woken. The wake waits in the written copy, as an unread message that woke the session: the presence holds no state for it. A watch that starts in MustClear gets no missed wake. The watch of a worker runs through the clear, so the writer sends the wake: when it applies the session_started record that ends MustClear, it sends the wake of the newest unread message that woke the session (State::written). A watch that starts after the clear gets the same wake. A start of the server loses nothing: the next watch start gives the wake. One message gives one wake: when the posted record and the session_started record are in one chunk, the writer does not send the wake of the posted record too (01M3XV0588C2XZKZ3NM67JXCKJ).
• The reply to a release is ReleaseReply with must_clear. The reply to a keep-alive is AliveReply with clear: the state adds it to the reply of the signal, from the written copy.
• who, top and riff workers show MustClear, and the time since the last fresh start of each worker.

The pipeline in the types

The stages of a command are types of the engine module. Only that module can make Checked, Queued and Applied, and each one is made from the stage before it. Authenticated<C> has two doors: its constructor for a routed command takes the proof of the token layer (SignedIn), and the functions of the engine for the commands of the server and for admit make it inside the module. The state, its lock and the queue are private fields of the engine module. The files of the commands are next to the engine module, not below it, so no command can make a stage or lock the state.

The writer has a proof too (01M3X4Z6DSWKMJ2R549R4TSYP0). log::write gives the value Written, and only the module log makes it. Engine::finish takes the chunk and its Written. So the types show that only a written chunk reaches the written copy. A chunk with no record needs no object: a write of no record gives its Written with no I/O. A chunk that is not written goes to Engine::fail.

• Only Applied gives the reply. So a handler cannot reply before the write. The writer sends the effects, so no wake goes out for a record that is not written.
• Only the writer calls apply on the written copy, with the records of a chunk that it wrote. So the server cannot apply a record that is not written, and the written copy is the replay of the log.
• Checked holds the guard of a std::sync::Mutex, so no other call comes between the check and the queue. The guard is not Send, and axum needs a Send future. So a handler that holds it over an await does not compile.
• Two rules have a doc test with compile_fail that names its error code, and a twin doc test that compiles and differs in the one line that the rule forbids:
  • Code outside the engine module cannot make a stage: Engine::check is private (E0624). The twin uses Engine::dispatch. The two are on Authenticated.
  • A signal cannot reach the riff: Signal::set does not take a Riff (E0308). The twin gives it the presence. The two are on Signal.
• The stages are public types, so a doc test can name them. Their fields and the functions that make them are private to the engine module: the privacy of the module keeps the rule for each other way to make a stage.
• The rule “no await while Checked lives” has no doc test: only dispatch can break it, and then the one handler does not build. The rustdoc of dispatch says so, with the text of the error.
• The tests a_state_with_a_writer_shows_a_record_only_after_its_write and a_post_of_a_state_with_a_writer_is_read_only_after_its_write stay. The tests of the engine are in crates/riff-server/src/lib.rs: one drops a call while the write waits, then checks the written copy and the wake. One puts a claim and a release in one chunk, and compares the written copy with the replay of the log. One checks that a refusal as held comes only after the write of the claim that holds.

This is the real code. A command, with its kind, its reply and its rule:

/// A call that asks for a change. [`Command::handle`] holds its rule.
///
/// ```
/// use std::time::Instant;
/// use riff_core::name::SessionUri;
/// use riff_core::wire::Claim;
/// use riff_state::state::{Caller, Code, Command, CommandKind, State};
///
/// /// The kind of a command, and the code of its refusal now.
/// fn refusal<C: Command>(state: &mut State, me: &SessionUri, command: &C) -> (&'static str, Option<Code>) {
///     let refused = state.run(&Caller::of(me), command, Instant::now()).err();
///     (C::KIND.as_str(), refused.map(|r| r.code))
/// }
///
/// let mike: SessionUri = "riff://mike@pangolin/como-technologies/riff?session=a6cf".parse()?;
/// let mut state = State::default();
/// state.register(&mike, Instant::now());
/// let claim = Claim { me: mike.clone(), thread: mike.default_thread().unwrap(), item: "issue-12".into() };
/// // A new riff is paused, so a claim is refused.
/// assert_eq!(refusal(&mut state, &mike, &claim), ("claim", Some(Code::Paused)));
/// # Ok::<(), riff_core::name::NameError>(())
/// ```
pub trait Command: Send + 'static {
    /// The name in each record and in each log line. Never renamed.
    const KIND: CommandKind;
    /// The reply to the call.
    type Reply: Send;
    /// What `handle` keeps for the reply, for example the selectors of
    /// a post that matched no session.
    ///
    /// The engine keeps the note of a call with a call ID, and a
    /// repeated call gets a copy of it. After a start, the kept call has
    /// the default note (01M48VFXHHND8SX4DBXZTFMJGQ).
    type Note: Clone + Default + Send + 'static;

    /// The role that the command of `caller` needs. [`permits`]
    /// compares it with the role of the caller. It reads the caller
    /// only to know if the command names the caller: a `revoke` of the
    /// own sign-ins needs a member, and a `revoke` of another person
    /// needs an admin.
    fn needs(&self, _caller: &Caller) -> Role {
        Role::Member
    }

    /// Checks the command of `caller` against `view`: the pending copy.
    /// Gives the changes and the note, or why the command is refused.
    /// It does no I/O and changes nothing.
    fn handle(
        &self,
        caller: &Caller,
        view: &View<'_>,
        now: Now,
    ) -> Result<(Vec<Change>, Self::Note), Refused>;

    /// Makes the reply from `view`: the written copy, after the write
    /// of the records of the command. `done` is the word of the writer:
    /// the records, and what their effects did.
    fn reply(
        &self,
        caller: &Caller,
        view: &View<'_>,
        done: &Done,
        note: Self::Note,
        now: Now,
    ) -> Self::Reply;

    /// The signal of the call, for the presence. Most commands have
    /// none. The state sets it at the check, only when the command is
    /// not refused (01M3WRD97EZJK3AABXECXEY133).
    fn signal(&self, _caller: &Caller) -> Option<Signal> {
        None
    }
}

A call, in riff-core, and a command that a client can send:

/// A call: one wire type with its path and the type of its reply
/// (01M3WRD8TBDPA4JNEZY6J4N2EX). The client sends each call with one
/// generic function, and the server makes one route for each.
///
/// ```
/// use riff_core::wire::{Call, Claim};
///
/// /// The path of a call and the JSON of its body.
/// fn request<C: Call>(call: &C) -> (&'static str, String) {
///     (C::PATH, serde_json::to_string(call).unwrap())
/// }
///
/// let claim = Claim {
///     me: "riff://mike@pangolin/como-technologies/riff?session=a6cf".parse()?,
///     thread: "como-technologies/riff".parse()?,
///     item: "issue-12".into(),
/// };
/// let (path, body) = request(&claim);
/// assert_eq!(path, "/v1/claim");
/// assert!(body.contains("issue-12"));
/// let reply: <Claim as Call>::Reply = serde_json::from_str(
///     r#"{"holder":"riff://mike@pangolin/como-technologies/riff?session=a6cf&claim=issue-12"}"#,
/// ).unwrap();
/// assert_eq!(reply.holder.claims(), ["issue-12"]);
/// # Ok::<(), riff_core::name::NameError>(())
/// ```
pub trait Call: Serialize + DeserializeOwned {
    /// The HTTP path of the call, for example `/v1/claim`.
    const PATH: &'static str;
    /// The reply to the call.
    type Reply: Serialize + DeserializeOwned;
}

/// A command that a client can send: a [`Call`] that is a [`Command`]
/// with the same reply (01M3WRD8TBDPA4JNEZY6J4N2EX). [`command`] is the
/// handler of each, and the router has one line for each:
/// `.route(C::PATH, post(command::<C>))`.
pub trait Routed: Call + Command<Reply = <Self as Call>::Reply> {
    /// The session that the body names, for the token layer.
    fn me(&self) -> Option<&SessionUri>;

    /// Lets the token layer check and fill the body before the engine
    /// gets the command. Only a post has such a check: its signature.
    fn prepare(&mut self, _proof: Option<&SignedIn>, _now_ms: u64) -> Result<(), String> {
        Ok(())
    }
}

A signal:

/// A change of the presence only: it makes no record, and it cannot
/// change the riff (01M3WRD97EZJK3AABXECXEY133).
///
/// A signal takes the presence:
///
/// ```
/// use std::time::Instant;
/// use riff_core::name::SessionUri;
/// use riff_state::state::{Presence, Riff, Signal};
///
/// let mike: SessionUri = "riff://mike@pangolin/como-technologies/riff?session=a6cf".parse()?;
/// let (mut presence, mut riff) = (Presence::default(), Riff::default());
/// let place = Signal::Place { place: mike.place().clone() };
/// place.set(&mut presence, mike.who(), Instant::now());
/// Signal::Alive { activity: None, prompt_secs: None, container: false, binary: None }.set(&mut presence, mike.who(), Instant::now());
/// # let _ = &mut riff;
/// # Ok::<(), riff_core::name::NameError>(())
/// ```
///
/// It does not take the riff. This differs only in the value that the
/// last signal gets, and it does not compile:
///
/// ```compile_fail,E0308
/// use std::time::Instant;
/// use riff_core::name::SessionUri;
/// use riff_state::state::{Presence, Riff, Signal};
///
/// let mike: SessionUri = "riff://mike@pangolin/como-technologies/riff?session=a6cf".parse()?;
/// let (mut presence, mut riff) = (Presence::default(), Riff::default());
/// let place = Signal::Place { place: mike.place().clone() };
/// place.set(&mut presence, mike.who(), Instant::now());
/// Signal::Alive { activity: None, prompt_secs: None, container: false, binary: None }.set(&mut riff, mike.who(), Instant::now());
/// # Ok::<(), riff_core::name::NameError>(())
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Signal {
    /// A call of the session from `place`: a sign of life. A person takes the place of each
    /// call
    /// (01M3MWW8KYJ3ZV91X22RBSAF33).
    Called { place: Place },
    /// A keep-alive: a sign of life that is not a call (R204). It
    /// carries the newest fact of the hooks of the session
    /// (01M41FZNTPXQNCZ1S99HE42PYQ). A fact of work after an answer
    /// ends a block (01M41FZPT31ATXP75QW965P3JB). A prompt of the
    /// person after the block, `prompt_secs` ago, ends it too
    /// (01M48VDWPDYRPEAXHR1MYDN1M7): the prompt hook of the lead in a
    /// container gives it (01M5GVQQ8NK3RD9CM3VTGXEHZQ). With
    /// `container`, the riff daemon sends it for a session in a
    /// container: the mark stays until the session ends
    /// (01M510MG0CKDXAKF6YJ768K7E8). A `binary` replaces
    /// the riff of the session; none keeps it
    /// (01M514C11BPE93PJT4221PYVHS).
    Alive {
        activity: Option<Activity>,
        prompt_secs: Option<u64>,
        container: bool,
        binary: Option<RiffBinary>,
    },
    /// The place of the session, from a `register`. It makes a session
    /// that the presence does not know.
    Place { place: Place },
    /// The status of the session, set at `at_ms`.
    Status { status: Status, at_ms: u64 },
    /// The session cannot go on with no decision, since `at_ms`
    /// (01M41FZPGEK4TNPSM2051W4VMS). A new block replaces the old one.
    Blocked { reason: String, at_ms: u64 },
    /// A change of the long step of the session at `at_ms`
    /// (01M48VDGTD40P8RBZMS0XB5M9N). It is a sign of life.
    Step { change: StepChange, at_ms: u64 },
    /// The numbers of the machine of the session, sent at `at_ms`
    /// (01M515KSWVGCBS76AWZV74TJQ3). New numbers replace the old ones. A
    /// checkpoint does not keep them: the session sends them again.
    Machine { numbers: String, at_ms: u64 },
    /// What a client saw of the items of `thread` on the forge
    /// (01M41FZP2C4Z4J6WKRXZ5B31EH). With `all`, the facts replace each
    /// fact of the thread.
    Facts {
        thread: ThreadName,
        items: Vec<ItemFact>,
        all: bool,
    },
    /// A look saw the plan of `thread` (01M4A4YTYVHFGK0CJVACJQ8DQ3): a
    /// `plan` that the server took, or a `plan_seen` of the position of
    /// the plan of the server. A plan is stale
    /// [`PLAN_TTL`](super::plan::PLAN_TTL) after the last look.
    PlanSeen { thread: ThreadName },
    /// A watch stream opened.
    WatchStarted,
    /// A watch stream closed. It is no sign of life
    /// (01M3WG240PNMQYZ7TX6Z7ZF6M9).
    WatchEnded,
    /// The session ended (R205).
    Ended,
    /// The session read `thread` up to `seq`. A read of all the
    /// messages (`all`) never moves the cursor back. `woken` is the
    /// newest message after `seq` that woke the session and that the
    /// read showed, or 0 (01M588J4XNV1TXEPMGTKRVY9VK).
    Read {
        thread: ThreadName,
        seq: u64,
        all: bool,
        woken: u64,
    },
}

One entry of the queue, and why a call gets no reply:

/// One command in the queue of the writer: accepted (with its records,
/// or none) or refused (no record).
struct Entry {
    made: Vec<Record>,
    /// Who sent the command, for its log line. An entry of
    /// [`Engine::settle`] is no command, and has none.
    sent: Option<Sent>,
    /// Tells the call that the entry is done. The `register` that the
    /// engine runs first for a caller has no call of its own.
    done: Option<oneshot::Sender<Done>>,
    /// The key of a command with a call ID, and its note. The writer
    /// keeps the result of the call ([`Engine::finish`]).
    call: Option<Called>,
}

/// The key of a call in the queue, and the note of `handle`: `None`
/// for a refused command.
struct Called {
    key: Key,
    note: Option<Box<dyn Any + Send>>,
}

/// The trace of a command that makes no record: who sent it, and why it
/// is refused (01M3X4Z62RJREQ5H8F18Y85T6V).
struct Sent {
    traced: Traced,
    refused: Option<Refused>,
}


/// Why a call gets no reply.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Failed {
    /// The token layer refused the call: 403. The token check of the
    /// router gives 401 before the engine gets the call.
    Denied(Denied),
    /// `permits` or `handle` refused the command: 400, 403 or 409, by
    /// its code (01M3WRD9JBQMNN96TXJH8EAJ3W).
    Refused(Refused),
    /// The chunk was not written, and the instance stops: 503.
    Stopped,
}

The one path, and the handler of each routed command:

    /// The one path of each command (01M3WRD8WJ2JF9077PRDX04T9A): the
    /// check under the lock, the entry in the queue, the wait for the
    /// writer, and then the reply or the refusal. A refused command
    /// waits as each command does (01M3WRD933ESXF33WDEDFCRFB8).
    ///
    /// The rule "no `await` while `Checked` lives" has no doc test.
    /// `Checked` holds the guard of a `std::sync::Mutex`, which is not
    /// `Send`. Only this function can hold it over an `await`, and then
    /// the future of [`command`] is not `Send`, so the one handler does
    /// not build. The error is at each line of the router. It does not
    /// name the lock. A test build with one `await` between the check
    /// and the queue gave it:
    ///
    /// ```text
    /// error[E0277]: the trait bound `fn(State<Engine>, ...) -> ... {command::<...>}: Handler<_, _>` is not satisfied
    ///     --> crates/riff-server/src/lib.rs:1465:41
    ///      |
    /// 1465 |             .route(Register::PATH, post(command::<Register>))
    ///      |                                    ---- ^^^^^^^^^^^^^^^^^^^ the trait `Handler<_, _>` is not implemented for fn item `fn(State<Engine>, Authenticated<Register>) -> ... {command::<...>}`
    /// ```
    pub async fn dispatch<C: Command>(&self, call: Authenticated<C>) -> Result<C::Reply, Failed> {
        self.run(call).await.map(|replied| replied.reply)
    }

    /// [`Engine::dispatch`], which also says whether the reply is the
    /// reply of a kept call (01M48VFX22S4811DYBBD7QDW24). A second try
    /// of a call that waits for the writer waits for the same entry, and
    /// then gets the kept reply (01M48VFX8K93F8XRWDB2BDP240). When the
    /// first try was refused, the second try runs `handle`
    /// (01M48VFXBGBW3PTC2JNHYNSE0W).
    pub async fn run<C: Command>(
        &self,
        mut call: Authenticated<C>,
    ) -> Result<Replied<C::Reply>, Failed> {
        loop {
            let next = match self.check(call) {
                // lock, permits, handle, signal; then positions, the entry
                Try::Run(checked) => Next::Queued(checked.queue()),
                Try::Kept(reply) => {
                    let repeat = true;
                    return Ok(Replied { reply, repeat });
                }
                Try::Wait(again, wait) => Next::Wait(again, wait),
            };
            match next {
                Next::Queued(queued) => {
                    let applied: Applied<C> = queued.applied().await?; // the writer did the rest
                    let reply = applied.reply()?; // the reply, or the refusal
                    let repeat = false;
                    return Ok(Replied { reply, repeat });
                }
                Next::Wait(again, wait) => {
                    wait.await.map_err(|_| Failed::Stopped)?;
                    call = again;
                }
            }
        }
    }

    /// The first stages of a command of the server, with no `await`:
    /// the check under the lock, and the entry in the queue. The writer
    /// finishes the command, also when nobody waits for it: a call that
    /// is gone loses only its reply. A command of the server has no
    /// call ID, so it always gets an entry.
    fn send<C: Command>(&self, call: Authenticated<C>) -> Option<Queued<C>> {
        match self.check(call) {
            Try::Run(checked) => Some(checked.queue()),
            Try::Kept(_) | Try::Wait(..) => None,
        }
    }

/// The handler of each routed command. The router makes one route for
/// each: `.route(C::PATH, post(command::<C>))`.
///
/// The reply to a repeated call has the header `riff-repeat: 1`
/// (01M48VFX22S4811DYBBD7QDW24).
pub async fn command<C: Routed>(
    AxumState(engine): AxumState<Engine>,
    call: Authenticated<C>,
) -> Result<Response, Failed>
where
    <C as Call>::Reply: serde::Serialize,
{
    let Replied { reply, repeat } = engine.run(call).await?;
    Ok(match repeat {
        true => ([(REPEAT_HEADER, "1")], Json(reply)).into_response(),
        false => Json(reply).into_response(),
    })
}

The router has one line for each routed command:

        // The commands: one line for each, and one handler for all
        // (01M3WRD8TBDPA4JNEZY6J4N2EX).
        let commands = Router::new()
            .route(Register::PATH, post(command::<Register>))
            .route(Start::PATH, post(command::<Start>))
            .route(End::PATH, post(command::<End>))
            .route(Join::PATH, post(command::<Join>))
            .route(Leave::PATH, post(command::<Leave>))
            .route(Post::PATH, post(command::<Post>))
            .route(Claim::PATH, post(command::<Claim>))
            .route(Release::PATH, post(command::<Release>))
            .route(ReleaseFor::PATH, post(command::<ReleaseFor>))
            .route(Lead::PATH, post(command::<Lead>))
            .route(Pause::PATH, post(command::<Pause>))
            .route(Resume::PATH, post(command::<Resume>))
            .route(Hold::PATH, post(command::<Hold>))
            .route(Free::PATH, post(command::<Free>))
            .route(SetPlan::PATH, post(command::<SetPlan>))
            .route(PlanOff::PATH, post(command::<PlanOff>))
            .route(SetNotes::PATH, post(command::<SetNotes>));
        // `set_idle` has a router of its own: in a riff with sign-in,
        // its route always has the token check.
        let set_idle = Router::new().route(SetIdle::PATH, post(command::<SetIdle>));

The writer is one task of the server. It takes each entry of the queue (Engine::take), writes their records as one chunk outside the lock, and gives the chunk and the proof of its write to Engine::finish:

    /// Finishes each command of a chunk that the writer wrote
    /// (01M3WRD90WBBCWTDGVQCBR6MNT). `written` is the proof of the
    /// write: only [`riff_state::log::write`] makes it (01M3X4Z6DSWKMJ2R549R4TSYP0). It
    /// applies the records to the written copy in the order of their
    /// positions, under the lock. Then, for each entry in order, it
    /// writes the log line of a command with no record (01M3X4Z62RJREQ5H8F18Y85T6V),
    /// sends the effects and tells the call that the entry is done. The
    /// call can be gone: the change is done. A session that a record
    /// takes out of MustClear gets the wake that it missed (01M3X9XBMB3R718Z81BYXTHMZ0).
    /// One message gives a session one wake: when the message and the
    /// record that ends MustClear are in one chunk, the session gets
    /// only the missed wake (01M3XV0588C2XZKZ3NM67JXCKJ).
    ///
    /// A proof of other records is an error of the writer: the chunk
    /// fails, and the engine stops.
    pub fn finish(&self, mut chunk: Chunk, written: Written) {
        if !written.covers(&chunk.records()) {
            self.fail(chunk);
            self.stop("the writer gave the proof of other records");
            return;
        }
        let mut missed = Vec::new();
        {
            let now = Instant::now();
            let mut core = self.core();
            for entry in &mut chunk.entries {
                missed.extend(core.state.written(&entry.made));
                // The writer keeps the result of an accepted call with
                // its records, under the same lock
                // (01M48VFX22S4811DYBBD7QDW24).
                if let Some(called) = &mut entry.call
                    && let Some(note) = called.note.take()
                {
                    let done = Done::of(entry.made.clone());
                    core.state.keep(called.key.clone(), done, note, now);
                }
            }
        }
        for wake in &missed {
            // A send fails only when nobody listens. That is not an error.
            let _ = self.0.wakes.send(wake.clone());
        }
        for entry in chunk.entries {
            if let (true, Some(sent)) = (entry.made.is_empty(), &entry.sent) {
                sent.traced.line(match &sent.refused {
                    Some(refused) => Outcome::Refused(refused),
                    None => Outcome::NoChange,
                });
            }
            let ended = self.effects(&entry.made, &missed);
            if let Some(called) = &entry.call {
                self.called(&called.key, ended);
            }
            if let Some(done) = entry.done {
                let made = entry.made;
                let _ = done.send(Done { made, ended });
            }
        }
    }

The tests keep the given/when/then form of the store design.

A repeated call

The link of riff sends a command again until it gets a reply (see the client link). So each command carries a call ID, and the engine runs each call one time only. Engine::check looks up the key of the call (the caller and the call ID) before handle:

flowchart TD
    C[a command with a call ID] --> K{the key}
    K -->|kept| R["the reply from the kept result,<br/>on the written copy of now:<br/>no handle, riff-repeat: 1"]
    K -->|pending| W[wait for the entry of the first try] --> K
    K -->|none| H[permits and handle, as each command] --> Q["the entry has the key;<br/>the records have the call ID"]
    Q --> F{"Engine::finish"}
    F -->|accepted| KEPT["kept: the records and the note,<br/>under the lock of the write"]
    F -->|refused| GONE[no key]

• The table of the kept calls is a part of the state. The waits of the second tries are in the engine, under the same lock.
• The writer keeps the result, not the call. So a cut, which drops the future of the call, does not lose the result.
• A checkpoint keeps the records of each kept call. A load makes the kept calls again from the checkpoint and the records after it.
• The rustdoc of state/calls.rs has the rules and the limits.

The records

Release 1.0.0 fixes this list. The enum Change and the list of its kinds come from one macro, so a kind cannot be in one and not in the other. The fixtures of CI hold one record of each kind: crates/riff-server/tests/fixtures/1.0.0/.

The envelope of each record: position, written_at_ms, by, command and call, next to its change. call came after 1.0.0: the call ID of the command, when its call has one (see A repeated call). A build of 1.0.0 skips it. The envelope is one Rust type, Envelope. The record and the reader of a log line share it, so a new field gets to each path.

• pause_set holds the pause of the riff too.
• The list has only the kinds of a build that was released. A kind that only a build of main before 1.0.0 wrote is not in the format: a build reads such a record as a kind that it does not know.
• A record of the people names a person by the email. The state finds the user from the email.
• setting_changed holds each setting. Each setting is a field that can be absent: absent means “not changed”.
• The log has no record for the end of a session. A later release can add one, with a new name.

The rules for a change of a record

The three rules of the store design stay. These rules come with them:

• apply only stores what a record says (01M3WNQQWA7XGK4Y9ET8HJZ8NN). It reads only the record and the riff, and no clock, no presence and no setting. It makes no decision. So a new policy changes only handle, and the same log gives the same riff on each build that knows the records. The table below has each place where apply reads the riff. A new place needs a line in the list of state/riff.rs.
• by and command are fields of the envelope with a default: a record with no by has a cause that is not known.
• A new record kind after 1.0.0 gets a new name. An old build skips it, and writes no checkpoint past it.
• A field with a set of named values that can grow (reason, scope, the class in by) has the value other. A build reads a value that it does not know as other: a text, and each other form of JSON. apply stores nothing for such a value: a session_started with the reason other is not a fresh start and changes no worker mark, and a pause_set with the scope other changes no pause. As for each record that names a session, apply keeps the URI of the session and the time of the record. A record with a value that the build read as other, in its change or in its by, counts as a skipped record: the build writes no checkpoint past it, and riff server counts it. state of pause_set has two values and no other.
• A new command needs no change of the format: command is text. A reader takes a command that it does not know as text.
• A kind of record and a kind of command are never renamed, and the name of a removed kind is never used again. The file kinds.json of the fixtures lists the kinds of the release. A test fails when a name of the list is gone from the code, and when a kind of the code is not in the list.
• The order of the kinds in the code is not a part of the format: a reader finds a kind by its name.
• Two parts of a posted record have the value other too (01M3XSF90E9JYYTC13D9THY4WE): the kind of the message, and each selector of its to. A selector that the build does not know is a selector other: an object with a field or a value that the build does not know, and each other form of JSON. It keeps its JSON as it came, and it matches no session: a field that the build cannot check never makes a selector wider. apply keeps the message in its thread, with the sessions that the record says it woke. A reader shows a message of the kind other as a message, with its text. Such a record counts as a skipped record.
• A session URI keeps each query part that the build does not know, as it came (01M3XYYSY536AEJVERBPTQFQYX). The session is the same session, and the part gives no mark: no lead and no claim. Such a record counts as a skipped record.
• Only the read of the log takes a value of a later build. A post call with a kind or a selector that the server does not know is refused, with the code bad_request. Each call of a caller whose URI has a part that the server does not know is refused, with the status 400.
• The rustdoc of crates/riff-core/src/record.rs lists each type with named values that a record holds, and each text with a grammar. Each line has the rule for a value of a later build, or the reason why the set never grows.

The checkpoint

Each part of the state that the log gives is in the checkpoint. The store design names the parts of today. The engine adds these parts, and the build item that adds a part to the state adds it to the checkpoint:

• the riff ID;
• the people: the email of each user, the members, the admins, the owner, a riff whose owner is gone, and the request for the owner role with its time;
• the position of the last member_removed and signins_ended record of each user;
• the worker mark, the MustClear mark and the time of the last fresh start of each session;
• each pause, with who set it and when.

A test takes the fixture log and makes a checkpoint at each position. A load of the checkpoint gives the state of a replay up to that position, and a start from it gives the state of a full replay. So a part that a checkpoint loses fails the test at the first position that has it. A second test replays the fixture log with apply alone, and in a state with a presence at two times: the riff after each record is the same. A third test keeps the read cursors of a live state through a checkpoint.

The scope of a pause

The state holds a pause of the whole riff, and a pause for each repository.

pub struct Pauses {
    /// The pause of the whole riff. A new riff is paused.
    riff: Option<PauseInfo>,
    /// The pause of each repository thread. A new repository runs.
    repositories: BTreeMap<ThreadName, PauseInfo>,
}

/// Who set a pause, and when: the `by` and the time of its record.
/// `by` is `None` for the pause of a new riff, and for a record with
/// no cause.
pub struct PauseInfo { by: Option<By>, at_ms: u64 }

{"position":2001,"written_at_ms":1790000000000,"by":{"session":"brett/62b2"},"command":"pause","change":{"pause_set":{"scope":{"repository":"como-technologies/strata"},"state":"paused"}}}
{"position":2002,"written_at_ms":1790000100000,"by":{"person":"mike"},"command":"pause","change":{"pause_set":{"scope":"riff","state":"paused"}}}

• A thread is paused when the riff is paused, or when the thread is a repository thread that is paused. handle reads the two for the thread of a claim: view.pauses().check(thread). The refusal names the pause and who set it.
• A session is paused when the repository of its place is paused, or the riff is paused. whoami, who and top show which pause it is and who set it.
• A claim in a thread that is not a repository thread sees only the pause of the riff.

• A resume of a repository while the riff is paused changes only the pause of the repository. The reply says that the riff is still paused.
• A pause and a resume wake each session that it changes: the sessions of the repository, or each session. A session that another pause still stops does not wake. The lead of a repository with a pause of its own hears a pause and a resume of the whole riff.
• pause and resume name the repository of the call. The field riff names the whole riff, and the field repository names a repository. The reply has the state for the place of the caller, the pause of the riff, and each paused repository.
• The rollout starts no worker for a repository that is paused.
• The server keeps the idle workers for each user, host and repository.

The import of go-live

A start that finds the old objects and no log is the import. It needs no flag: the deploy of release 1.0.0 is the import. The server reads the old objects before it takes the lease, and gives what it read to the command import of the server. Engine::dispatch writes these records as one chunk, with by server and command import:

1. riff_made, with the riff ID of today.
2. person_joined for each user, with its email.
3. member_invited, admin_set and owner_set; owner_asked when a request for the owner role waits.
4. pause_set for the riff, paused; setting_changed.
5. The posted records: the last 200 messages of each thread, as the checkpoint keeps them. A direct thread with no session that did not end is not in the import.
6. session_forgotten for each sender of a message that is no session of the import. A posted record names its sender, and this record takes the sender out again.
7. For each session: session_started (the reason join, the worker mark), then its joined_thread records. For a session that held at the save: its lead_set and claimed records.

sequenceDiagram
    participant M as main
    participant B as bucket
    participant E as Engine
    participant T as token store
    M->>B: read sessions, tokens, threads/
    Note over M: an object that does not read stops the start
    M->>B: take the lease, wait for the old instance
    M->>B: read sessions, tokens, threads/ again
    Note over M: a log now: another instance made the import. Replay it
    M->>T: the sign-ins of the old tokens object
    T->>B: signins.json
    M->>E: import (the changes of the old objects)
    E->>B: one chunk of the log
    E->>E: the memory of each session, the read cursors
    M->>B: a checkpoint
    Note over M: open the port

• The old instance serves and saves its objects until it reads the new lease. So the server reads the old objects again after its wait, and imports from that read. The first read is the check before the lease.
• When the log is there after the wait, another new instance made the import. The server then replays the log. It does not import, and it does not change the sign-ins.
• A signed message of release 0.8.0 has a signature and no payload. The import makes the payload from the fields of the message. So a message that was verified before go-live is verified after it, also a request of a lead. A message whose signature does not sign that payload stays not verified.
• The import writes only kinds of 1.0.0, and it can make each of them.
• An imported posted record keeps its old seq. So a thread can start at a seq that is not 1.
• The session records come after the posted records. So each session is in the place of the old sessions object, not in the place of its last message.
• A session with no sign of life for 30 days is not in the import. A session that ended is in the import with its threads and its read cursors, and with no claim and no lead. A session that comes back reads no message a second time.
• A session held at the save when it did not end and its last sign of life was at most 5 minutes before the save. Only such a session keeps its claims and its lead.
• After the import, the server writes a checkpoint with the read cursors of the old objects. So no session reads a message of the import a second time.
• A worker that holds no claim at the import is Ready.
• A second start finds the log, and does not import again. The command import is refused in a log that has a record.
• The token store takes each live sign-in of the old tokens object, at the position of the end of the import. A person refresh token of today works one time: it gives the first pair of a new chain. So no person signs in again. A session token has no chain: the session swaps the new person token.
• The server saves the sign-ins before it writes the log. A server that stops between the two steps finds no log at its next start, and imports again. So no stop loses the sign-ins.
• The import changes no old object. They stay for a rollback.
• After go-live, only the owner and the admins resume the whole riff.

Build items

Each item is in Wave 17, with a Needs: line. A session takes an item only when each item that it needs is merged. No release goes out from main before go-live (#341). Each item that adds a part to the state adds it to the checkpoint, with a test: a start from a checkpoint gives the state of a full replay.

E1a is built: the riff and the presence, and each command as a type.

E1b is built: the module crates/riff-server/src/engine.rs. The sync methods of State (State::run, State::claim and the others) stay for a state with no writer: the tests, the examples and the tools use them. Each one runs the same steps as the engine: State::check, State::queue and State::written. The server cannot call them: the state is a private field of the engine.

E5 is built: the type Pauses in crates/riff-state/src/state/the_riff.rs, and the record pause_set (riff_core::record::PauseSet).

E2 is built: the cause in each record (riff_core::record::By), the lines of the module crates/riff-server/src/trace.rs, and the proof of a write (log::Written).

E3 is built: the people of the module crates/riff-state/src/state/people.rs, with their 9 kinds and their 11 commands. crates/riff-server/src/token.rs holds only the sign-ins. A signins.json from before E3 reads, and its people are lost: main was never deployed.

E4 is built: the life cycle is in the part Sessions of the riff (crates/riff-state/src/state/sessions.rs), with its checkpoint fields.

E6 is built: the macros that make Change and CommandKind with their lists, Record::other in crates/riff-core/src/record.rs, the count of such a record in log::replay_after, and the fixtures and the tests of crates/riff-server/tests/format.rs. A later release adds a directory of fixtures of its own, and the build reads each one with no change (01M3WNQR41K41TV832GRQZ2CQS).

E6b is built: Kind::Other in crates/riff-core/src/wire.rs, the selector other in crates/riff-core/src/selector.rs, the query parts of a later build in SessionUri (crates/riff-core/src/name.rs), and the refusals in the post command and in Engine::admit (01M3XSF90E9JYYTC13D9THY4WE, 01M3XYYSY536AEJVERBPTQFQYX).

Other items:

• #353 (riff clears a worker) needs E4. A worker ends its turn after its last release, and runs no command for the clear.
• #354 (riff audit) needs E2, E4 and #353.
• #341 (go live) needs E6, #381 (the token of a session) and #363 (the guards of log cut).

Decisions

1. The stages of a command are types. The call makes Checked and Queued. The writer makes Applied.
2. The writer finishes each command: the write, the apply in order, the log line, the effects.
3. Each command leaves one trace: its records, or one log line. A command with records gets no log line.
4. Each record names its caller and its command. by is an object that names the class of the caller.
5. The log shows who did what for as long as it keeps its chunks.
6. A status and a place are signals. The sign-in chains, presence, the read cursors and the queries stay outside the dispatch. A signal cannot change the state of the log.
7. A command is a type with a trait, not a variant of one enum. One generic handler serves each routed command. A command of the server has no route.
8. One table, permits, says who can send each command.
9. MustClear comes only from the release of a worker itself. handle decides, and the released record holds it.
10. The server starts the clear of a worker: its reply to a keep-alive asks for it. riff acts on the ask when the turn of the worker ends.
11. apply only stores what a record says.
12. A worker is never the lead.
13. Each change of the people is a record kind of its own. The people are in the log before go-live. The caller carries its role.
14. One kind, pause_set, holds the two scopes of a pause.
15. A field with named values that can grow has the value other, and a record that a build read as other stops its checkpoint.
16. The log has no record for the end of a session.

Design: the client link

This page is the design of the link: the one part of riff that connects to riff-server, sends each call, tries again, follows each stream, sends the sign of life, and knows the state of the connection. Each command uses it. The crate review is design/reviews/link-00-crates.md. Three reviews are in design/reviews/ (link-01 to link-03), and the decisions are at the end of this page. When the build is done, the big picture stays in the book, and the details go into the rustdoc.

Goals

• One link for each command: top, watch, chat, tail, mcp, workers host and each short command. A command does not connect, try again or show a fault in a way of its own.
• Each call has a time limit. No call waits for ever.
• One rule for a new try. A fault of the connection gets a new try on a new connection. A refusal gets none.
• Delivery is guaranteed: the link sends a command until it gets a reply, and riff-server runs each command one time only.
• One sign of life for a session: the heartbeat.
• Each stream has a connection of its own, finds a dead connection in 45 s, and loses no message after a break.
• One state of the connection, with one text, in each command that runs until stopped.
• Not goals: a new wire, HTTP/3, a connection that lives through a change of the address, a queue of calls that waits for the network while no command runs.

The terms

The picture

flowchart LR
    subgraph riff [one riff process]
        C1[top] --> L
        C2[watch, tail, chat] --> L
        C3[mcp, workers host] --> L
        C4[a short command] --> L
        L["the link of the server:<br/>calls, tries, streams,<br/>heartbeat, state"]
    end
    L -->|"calls: one shared HTTP/2 connection"| S[riff-server]
    L -->|"each stream: a connection of its own"| S

1. One link

The link is the module link of the crate riff-client. link::of(base) gives the one link of a server in the process: a map by the URL of the server. So each Api of one server shares one link, one HTTP client and one state. Api keeps its typed methods (who, post, claim and the others), and each method goes through the link. Only the link talks to riff-server. The client of the sign-in provider in login of the crate riff is not a client of riff-server, and its faults do not change the state.

The budget

The budget belongs to each call. A process gives its calls a default.

The budget is a deadline for the whole call. The link cuts the open try at the deadline. Each try has the limit min(TRY_WAIT, the budget that is left), and each connect min(CONNECT_WAIT, the budget that is left).

The constants

2. One rule for a new try

Each try ends in one of three ways: a reply, a fault or a refusal.

• A 401 to a token is the one exception: the link gets a new token and tries one more time, as today.
• The wait before a new try grows: 250 ms, then double, up to MOST_WAIT. Each wait has a random part of up to half of it, so many workers do not try at the same moment after a deploy. getrandom, which riff uses already, gives the random part.
• A fault with no HTTP reply (no connect, a cut, no reply in time) makes a new HTTP client of the link, which each Api of the server shares. A 503 or a 429 came on a good connection, so it keeps the client.
• A refused connect (ECONNREFUSED) to a loopback address of a server that never replied to this process ends a call with a budget at once. riff cannot tell a server that starts from no server, so riff who with no server on this machine ends at once. This sets no state. Each other connect error is a fault, and a stream takes each connect error as a fault.

Each command gets to the server one time

Delivery is guaranteed (the decision of the user). The link sends a command again after each fault, also after a cut and after no reply in time, until it gets a reply or a refusal. riff-server runs each command one time only. So each command carries a call ID, and the server keeps the reply of each call ID.

sequenceDiagram
    participant C as riff
    participant S as riff-server
    C->>S: release issue-12, riff-call 7f3a
    S->>S: handle, write; the writer keeps the result of 7f3a
    S--xC: the reply is lost (a cut)
    C->>S: release issue-12, riff-call 7f3a (new connection)
    S-->>C: the reply of 7f3a: released, must clear (riff-repeat: 1)

The client

• The link makes a call ID for each call of a command: 16 random bytes in base 64. Each try of the call sends the same ID in the header riff-call. A query and a signal need no call ID: each of them is safe to send two times. The server reads the header only for a command.
• When the budget of a command ends with no reply, the link puts the command in the outbox of its caller on this machine: a file in local::dir(), with the path, the body, the call ID and the time. The command gives the text of down, and says that riff sends the command when riff-server is back.
• Each call of the link of that caller sends the commands of the outbox first, in their order, with their call IDs. The heartbeat sends them too. One process at a time sends the outbox: it holds a lock of local. A command leaves the outbox at its reply or its refusal.
• A call of the same command with the same body, while the outbox has it, takes the call ID of the outbox. So an agent or a person that sends a command again does not make it run two times.
• A command older than OUTBOX_KEEP (23 h) leaves the outbox with one line on stderr that names it: the server keeps a call ID for CALL_KEEP (24 h), so a later send can run it two times.

The server

• Authenticated<C> reads the header riff-call into its field call. The key of a call is the caller (Caller::by) and the call ID.
• The engine has the table of the calls in Core, under its lock. A key is Pending or Kept.
• Engine::check looks up the key before handle:
  • No key: the engine puts Pending in the table and runs handle, as today.
  • Pending: the first try waits for the writer. The second try waits for the same entry, then makes its reply as for Kept.
  • Kept: the engine runs no handle. The try makes its reply with C::reply from the kept result, on the written copy of now.
• The writer keeps the result, not the call: Entry gets the key, and Engine::finish puts Kept { done, note, at } in the table. So a cut, which drops the future of the call, does not lose the result. The note of a command (Command::Note) gets the bounds Clone + Default + Send + 'static.
• A refused command removes its key: a refusal is not kept. A second try runs handle again. The first try changed nothing, so this is safe.
• A reply to a kept call has the header riff-repeat: 1, for the log line and the tests. The client takes it as each other reply. The reply shows the state of now: a claim that another session took between the two tries says “held by”.
• The table keeps a key for CALL_KEEP (24 h), and at most CALL_KEEP_MOST (1024) keys for each caller. The oldest key goes first.

The log and the checkpoint

• Each record of a command has the call ID in its envelope: the field call, with a default, next to by and command. A record of 1.0.0 has no call, and a build reads it as None. A build of 1.0.0 skips the field: Record has no deny_unknown_fields. This follows the rules for a change of a record (see the command engine).
• The checkpoint (Snapshot) gets the field calls, with a default: the records of each call of the last CALL_KEEP. Each record names its caller and its call ID, so the records give the key and the time of each call. An old checkpoint has none.
• At a start, the load makes Kept from the checkpoint and from each record after it: the records of a call give its done, and its note is Note::default(). So a start from a checkpoint and a start from the full log give the same reply to a repeated call.
• A command that the engine accepted with no record (for example a claim of an item that the caller holds) has no call ID in the log. After a start, a second try runs handle again. Such a command changed nothing, so this is safe.
• A rollback to a build with no call ID loses the table. For CALL_KEEP after it, a repeated command can run two times. The procedure of a rollback says so.

stateDiagram-v2
    [*] --> Try
    Try --> Reply: a reply, also a kept reply
    Try --> Refusal: a refusal
    Try --> Wait: a fault, budget left
    Try --> Outbox: a command, no budget left
    Try --> Ended: a query, no budget left
    Wait --> Try: the same call ID
    Outbox --> Try: the next call of the caller, or the heartbeat
    Reply --> [*]
    Refusal --> [*]
    Ended --> [*]: the error with the text of the state

3. The wire

riff stays on HTTPS over TCP. No HTTP/3 now: it is not widely adopted yet, and the design does not depend on a property of QUIC.

reqwest speaks HTTP/2 to a server that offers it, as Cloud Run does, from its default features. So the calls of one process share one TCP connection. The local tests speak HTTP/1.1 over http://.

4. One sign of life

The heartbeat is the only sign of life of a session, with each call of the session, as today. An open stream is not a sign of life.

• The heartbeat is POST /v1/alive. Its reply carries the asks of the server: stop an idle worker, clear the context. Since #424 its body carries the newest fact of the session, so body makes it at each tick.
• Each tick is one try, with the period as its limit. A tick that fails sets the state down. The next tick is the new try.
• A stream has a heartbeat of its own: riff-server sends a comment each 15 s (KeepAlive::default() of axum), and the comment ready when the stream opens. The link ends a stream that gives no byte for STREAM_IDLE, three comments, and connects again. So a stream that died with no sign, for example after a sleep of the laptop, comes back in at most 45 s.
• The server counts the open watch streams of a session (Session::watching), but only while the session is not gone. So the count is no sign of life. A new connection after STREAM_IDLE makes the count go down and up, and changes nothing for a session with a heartbeat.

sequenceDiagram
    participant M as riff relay mcp
    participant W as riff relay watch
    participant S as riff-server
    loop each ALIVE_EVERY
        M->>S: heartbeat (the newest fact)
        S-->>M: stop? clear?
    end
    W->>S: watch stream (no sign of life)
    loop each 15 s
        S-->>W: comment
    end
    Note over W: no byte for 45 s: a new connection
    S->>S: no heartbeat and no call for 3 minutes: gone

5. Streams

Each stream has a connection of its own, which never goes to the pool of the calls. The end of a stream by the server is normal: Cloud Run ends each stream after 60 minutes, and a deploy ends each stream. The link connects again at once, and shows nothing. A connect that fails is a fault: the link waits STREAM_RETRY and tries again.

• The open comes before the read, so no message falls between the two.
• The server keeps the last 200 messages of a thread. A break with more new messages shows one line with the number of the lost messages.
• A stream that is slow to read can lose events on the server: the broadcast of the engine has room for 1024 events. The server ends a stream that lost an event (Lagged). Then the client connects again, and reads what it lost.

sequenceDiagram
    participant T as riff tail
    participant S as riff-server
    T->>S: GET /v1/tail
    S-->>T: message 41, message 42
    Note over T,S: the Wi-Fi drops
    T->>T: no byte for 45 s: down
    T->>S: GET /v1/tail (a new connection)
    T->>S: read the thread after 42
    S-->>T: 43, 44 (sent in the break)
    S-->>T: live messages

6. One state that a person sees

The link has one state, and one text for each state:

stateDiagram-v2
    [*] --> up: the first reply
    [*] --> down: the first fault
    up --> down: a fault
    down --> down: a fault: no new line
    down --> up: a reply: the line "back"
    up --> refused: another build, a refused sign-in
    down --> refused: the same
    refused --> up: a new binary runs

• Each command that runs until stopped shows the state in its place: top in its first line, and it draws again at each change of the state, also while a look waits. chat shows it above its prompt. watch, tail and workers host show it on stderr. Each uses the one function text::link_line.
• A short command shows the line of down one time on stderr after LINE_AFTER. A call that ends with no budget left gives the text of down as its error. A command then waits in the outbox, and the text says so.
• At refused for another build, a command that runs until stopped waits for a new binary and runs it, as today (01M3MNVTC248YYJJQKFD9H1WY9). A refused sign-in ends it.
• The lines (waits for riff-server…), (reconnecting…), (back) and the fault line of top go. The state gives each of them.

The parts of the link

The crate review gives one part for each piece:

The repository has no configuration of cargo deny. The first build item that adds a crate adds it: the advisories with no exception, a list of the licenses, no second reqwest or hyper, and crates.io as the only source.

The cost

Build items

Each item changes the requirements that it replaces (R131, R132, R148 and the decisions of the code in api.rs), the rustdoc, and the book.

Decisions

1. Delivery is guaranteed (the decision of the user, 2026-10-03). Each command has a call ID in the header riff-call. The writer keeps the result, a second try waits for a pending first try, a kept reply is made with C::reply and has riff-repeat, and the record envelope and the checkpoint keep the call IDs. A command with no reply at the end of its budget waits in the outbox. (link-01-2, link-01-4, link-01-14, link-01-15, link-02-4 to link-02-8. The user did not take link-03-3 and link-03-4.)
2. The budget belongs to each call. A tool call of riff relay mcp, a post of chat and a look of top have SHORT_BUDGET. Only the streams have none. (link-01-1, link-02-10, link-03-1.)
3. A refused connect ends a call at once only for a call with a budget, a loopback address and a server that never replied. It sets no state. (link-02-9, link-03-2.)
4. One shared HTTP client for each server in the process, swapped only after a fault with no HTTP reply. (link-02-1, link-02-12, link-03-10.)
5. A stream is not a sign of life. STREAM_IDLE is 45 s, three comments of the server. (link-02-3, link-03-11.)
6. No state file. (link-01-5, link-02-17, link-03-5.)
7. tail and chat read after a break from the last seq that they showed. No cursor on the server, no Last-Event-ID. The server ends a stream at Lagged. (link-01-9, link-02-13 to link-02-15, link-03-6, link-03-12.)
8. At refused for another build, a command that runs until stopped waits for a new binary, as today. (link-01-3.)
9. Removed in 4.0 (#1173). (link-02-11, link-03-8.)
10. A short command shows the line of down after 1 s. (link-03-7.)
11. The heartbeat makes one try at each tick, with the period as its limit. Its body comes from a function. (link-01-7, link-02-16, link-03-13.)
12. The time limits come first, as L1: they repair the two faults that are left today, a call with no limit and a stream that dies with no sign. (link-01-12, link-03-9.)
13. HTTPS over TCP. No HTTP/3 now (the decision of the user, 2026-10-01).

Design: the plan on the server

This page is the design of the plan: the current wave of a repository, the order of its items, and the held items. It builds on the command engine: each change of the plan is a command, with a record. Two reviews are in design/reviews/ (plan-01 and plan-02), and the decisions are at the end of this page. When the build is done, the big picture stays in the book, and the details go into the rustdoc.

Goals

• The plan is state on the server. Each change of it is a record in the log, with the caller and the command.
• The server refuses a claim of a worker against the plan, and the refusal names the reason.
• A lead holds an item with a reason, and frees it again. A hold is not a claim.
• One source for each part of the plan, one writer rule that loses no update, and a limit on the age of the copy on the server.
• Not goals: a plan that the server reads from the forge itself, a plan of more than the current wave, an order inside a wave, a plan for a thread that is not a repository thread.

The terms

The picture

flowchart LR
    P[person] -->|waves, Needs: lines, merges| G[(GitHub)]
    G -->|"one gh query each minute"| L["the look of the lead<br/>(riff relay mcp)"]
    L -->|"plan, when it changed;<br/>plan_seen, when it did not"| S[riff-server]
    LD[lead] -->|"hold, free"| S
    S -->|"plan_set, plan_ended,<br/>item_held, item_freed"| LOG[(the log)]
    W[worker] -->|claim| S
    S -->|"granted, or refused with the reason"| W
    S -->|the plan| V["riff plan, riff top,<br/>the rollout, riff audit"]

1. The source of the plan

• A person plans on GitHub, as today. The book and the leads keep the waves and the Needs: lines.
• The server has no credential of the forge (#424). So the server never reads GitHub. A client tells it the plan.
• The plan is opt-in for each repository. riff plan on sends the first plan. riff plan off sends plan_off, and the server forgets the plan of the repository. A repository with no plan gets no check of a plan, as today. So the people of another repository (for example como-technologies/strata) decide for themselves.
• The look of the lead reads the plan of each repository with a plan on. It makes one GraphQL query of gh for each look: the open waves, and the open issues of the current wave with their body and their last comments, and the state of each need. The same query gives the item facts of #424. So the look reads the forge one time, and the needs come to the server one time: the server makes waits from the plan, and ItemFact has no needs.
• The look compares the plan of the forge with the plan that the server gave it last (the reply of the query plan at the start of the look, and the reply of each plan after it):
  • When the two differ, it sends plan with the full plan and with base, the position of the plan_set record that it compared with.
  • When they are the same, it sends the signal plan_seen with the same position. The signal changes only the presence: the time of the last look that saw the plan. It makes no record.
• riff plan sync does the same as one look, at once. Each session that is not a worker can run it, and a person in a terminal.
• riff pr wait sends nothing. The Merged in comment comes after it, and the next look finds it.
• The look drops a need that is not an issue of this repository (an issue of another repository, a pull request), with one log line. One such need never stops the plan.
• A look against a server with no command plan (a build of 1.0.0) writes one log line, and tries again after one hour.

sequenceDiagram
    participant G as GitHub
    participant L as the look of the lead
    participant S as riff-server
    participant W as worker
    L->>S: query plan
    S-->>L: the plan, at position 3001
    loop each minute
        L->>G: one query: the wave, the issues, the needs
        alt the forge differs
            L->>S: plan (the full plan), base 3001
            S->>S: a plan_set record at 3050
            S-->>L: the plan, at position 3050
        else the same
            L->>S: plan_seen 3001
            S->>S: the presence: seen now
        end
    end
    W->>S: claim issue-12
    S-->>W: granted, or refused with the reason

Two writers, and the age of the copy

• handle of plan refuses the command with the code stale_base when base is not the position of the plan_set record of the plan of the repository, or not none when the repository has no plan. A refusal is text, so the reason names the position of the plan of the server, and the look reads that plan with the query plan. The look reads the forge again at its next turn. So two looks that cross never write an old plan over a new one.
• plan with the plan that the server has already gives no record. It counts as plan_seen.
• The plan is stale when no plan and no plan_seen came for PLAN_TTL (10 minutes). The time of the last look is presence, so a new start of the server begins the count again from the start.
• A stale plan checks no wave and no need: the server checks only the holds. The reply of a claim says “the plan of the server is stale; run riff plan sync”. So a stale plan never blocks work for long. A plan that is not stale but older than the forge can refuse a claim for at most one minute: the refusal is safe, and the session picks another item.

The plan on GitHub

• A wave is the milestone Wave N. The current wave is the open milestone Wave N with the lowest N.
• The GraphQL query of the look reads the open milestones, and the open issues of the milestone of the current wave.
• With no milestone Wave N, the items of the plan are the open issues with no milestone.
• The lead moves an item to an open wave with riff wave move N --to M.

2. When an item is done

• An item is done when it is merged: its issue is closed, or the issue has the comment Merged in #PR (COMMIT). This is the rule of the waves. The look reads it from the forge, and the command plan carries it.
• The release of a claim is not done. A worker releases its item at the verify request, before the merge.
• The word of the lead is a close of the issue, or the comment Merged in, on GitHub. Then the next look, or riff plan sync, sends it. The server has no command “done” of its own: one source for done.
• A need is done by the same rule, in each wave and in no wave. Today the rollout counts a need that is open with Merged in as open (crate::rollout::free_items). The plan counts it as done, as riff audit does.
• The plan has no check of done for a claim. An open item with Merged in has a check after the release. The session that runs the check, or that fixes it, claims the item. A closed issue is not an item of the plan.

3. The records and the commands

Release 1.0.0 fixed the format. The rules for a change of a record (see the engine) give the new kinds new names. A build of 1.0.0 skips them, and writes no checkpoint past the first one. The fixtures of the next release go into a directory of their own, for example crates/riff-server/tests/fixtures/1.1.0/, with its kinds, its log and its replay. The test of the kinds takes the union of the lists.

{"position":3001,"written_at_ms":1791000000000,"by":{"session":"mike/3511"},"command":"plan","change":{"plan_set":{"thread":"como-technologies/riff","wave":{"number":19,"title":"Wave 19"},"items":[{"item":"issue-366","needs":[]},{"item":"issue-459","needs":["issue-416"]}],"done":["issue-416"]}}}
{"position":3002,"written_at_ms":1791000100000,"by":{"session":"mike/3511"},"command":"hold","change":{"item_held":{"thread":"como-technologies/riff","item":"issue-366","reason":"waits for the word of Mike"}}}

• plan_set holds the full plan of one repository. apply replaces the plan of its thread with it, and keeps the position and the time of the record. A full plan is small: a wave of 20 items is about 2 KB. One record for each change keeps apply simple, and the record shows the whole plan at that time, for riff audit.
• done lists each need that is done. A need that is not in done is open.
• plan_ended removes the plan of the thread. The holds stay.
• item_held adds the hold of an item, or replaces its reason. item_freed ends it. apply keeps the by and the time of the item_held record, so that a view shows who held the item and when.
• A hold names one item by its exact name. A hold of issue-12 stops a claim of issue-12. It does not stop verify-issue-12.
• A hold can name an item that is not in the plan, for example an item of the next wave. A hold needs no plan.
• A hold does not end a claim. A hold of an item that a session holds stops only the next claim of a worker. The reply names the holder. The lead frees the claim of a session of its user with riff release ITEM --session ID.
• Only free ends a hold. A hold of a done item stops nothing that matters, and the lead frees it.
• apply only stores what a record says (01M3WNQQWA7XGK4Y9ET8HJZ8NN). The checks are in handle.
• The code is the group file crates/riff-state/src/state/plan.rs, with the part Plans of the riff and its Saved for the checkpoint. The arms go into Record::of_repository, and the lines into the tables of record.rs and riff.rs.

The wire

• The reply of plan, plan_seen and the query is the plan of the server (PlanReply): the wave, the items with their needs, the done needs, the holder of each item with a claim, the holds, the position and the time of the plan_set record, the time of the last look, and whether the plan is stale. A client finds the rest of the state of an item from these: waits, held, claimed.
• POST /v1/log skips a record of a kind that the client does not know, as Line::parse does, so that riff audit of one build reads the log of a later one. P1 adds this to the reader of LogReply.

Who can send each command

permits gives each command to a person or a session with the role member and no worker mark. A worker gets not_allowed, also a worker of the owner. handle then checks the rest, because “the lead of this thread” needs the state:

• plan checks the form: each item and each need is issue-N, no item is twice in items, and the thread is a repository thread. Else bad_request.
• hold needs a reason of 1 to 200 characters. Else bad_request.
• free of an item with no hold changes nothing: a log line, no record.
• The lead of each person in the repository can hold and free each item. The record names who did it.

The checks of a claim

handle of claim checks in this order. The first check that fails gives the refusal:

1. The worker must clear its context: must_clear.
2. The item has a name that is not valid: bad_request.
3. The riff or the repository is paused: paused.
4. The session holds the item already: granted, with no record.
5. The item is held, and the caller is a worker: on_hold. The reason names the lead, the time and the reason of the hold.
6. The item is issue-N, the plan of the repository is on and not stale, the item is not an item of the plan, and the caller is a worker: not_in_wave. The reason names the current wave, and says when the issue is closed.
7. The item is an item of the plan, a need is not in done, the plan is not stale, and the caller is a worker: needs_open. The reason names each open need.
8. Another session holds the item: held.

flowchart TD
    C[claim ITEM] --> M{must clear?}
    M -->|yes| X1[must_clear]
    M -->|no| B{valid name?}
    B -->|no| X2[bad_request]
    B -->|yes| P{paused?}
    P -->|yes| X3[paused]
    P -->|no| S{the caller holds it?}
    S -->|yes| G
    S -->|no| WK{a worker?}
    WK -->|no| O
    WK -->|yes| H{held?}
    H -->|yes| X4[on_hold]
    H -->|no| I{"issue-N, and a plan<br/>that is on and not stale?"}
    I -->|no| O
    I -->|yes| W{an item of the plan?}
    W -->|no| X5[not_in_wave]
    W -->|yes| N{each need done?}
    N -->|no| X6[needs_open]
    N -->|yes| O{another holder?}
    O -->|yes| X7[held]
    O -->|no| G[granted]

• The checks of the plan and the hold refuse only a worker. A session that a person works in, and a session that does a request of the lead, is granted. Its reply has a warning with the reason that a worker would get: issue-12 is held by the lead: REASON. So a scope from the user still wins, and the lead can claim an item that it held. riff audit lists each such claim.
• The plan checks only an item with the name issue-N. A verify (verify-issue-N) and an item with another name, for example wave5-live-evidence, get only the hold and the checks of today. A verify comes after the build, so the needs of its item are no check for it.
• A change of the plan never ends a claim.
• The codes on_hold, not_in_wave, needs_open and stale_base are new. Each one has the status 409, as held. A client of 1.0.0 shows the reason of a code that it does not know: “claim failed (409 Conflict): REASON” (riff_client::api). A new client treats the three codes of a claim as held: not granted, with the reason, exit 1. P2 tests both.