@openrig/cli 0.6.14 → 0.7.1

package/daemon/docs/reference/community-harness-examples/cursor/openrig-cursor-launch

@@ -0,0 +1,61 @@
+#!/bin/sh
+# A reference launcher for Cursor's CLI as an OpenRig community harness. Copy it, own it, and change it: OpenRig
+# doesn't ship or run it. It follows docs/reference/community-harness-presets.md:
+#   - a new launch: `cursor-agent create-chat` prints a new chat id; the launcher reports it, then reopens that chat;
+#   - a resume (OPENRIG_RESUME_REF set): it reopens the chat it was asked for and reports that id, or, when Cursor holds
+#     no such chat, reports it missing and starts nothing.
+# Cursor's chat-id facts come from the probe in OpenRig issue #352, and the chat store's location from Cursor's own CLI
+# (2026.10.22).
+set -eu
+
+producer="openrig-cursor-launch 2"
+cursor="${OPENRIG_CURSOR_AGENT:-cursor-agent}"
+
+# Each seat gets its own Cursor config folder unless CURSOR_CONFIG_DIR is already set. Cursor keeps cli-config.json
+# (`--model`, approval settings) and the chats there, so a seat doesn't rewrite the person's own ~/.cursor. Cursor's
+# login isn't in it: Cursor keeps that in ~/.config/cursor/auth.json on Linux and in the Keychain on macOS.
+CURSOR_CONFIG_DIR="${CURSOR_CONFIG_DIR:-${OPENRIG_HOME:-$HOME/.openrig}/state/cursor/${OPENRIG_NODE_ID:-${OPENRIG_SESSION_NAME:-default}}}"
+export CURSOR_CONFIG_DIR
+mkdir -p "$CURSOR_CONFIG_DIR"
+
+# Write this attempt's record, all at once, where OpenRig asked for it (nothing when it didn't ask).
+report() {
+  [ -n "${OPENRIG_LAUNCH_RESULT:-}" ] || return 0
+  tmp="$OPENRIG_LAUNCH_RESULT.$$.tmp"
+  printf '%s\n' "$1" > "$tmp"
+  mv "$tmp" "$OPENRIG_LAUNCH_RESULT"
+}
+plain_id() { case "$1" in ''|*[!A-Za-z0-9._:-]*) return 1 ;; *) return 0 ;; esac; }
+# Where Cursor keeps a chat: <config folder>/chats/<md5 of the working directory>/<chat id>/store.db. Cursor hashes
+# its process's working directory, which is the physical path, so this hashes `pwd -P`.
+chat_store() {
+  if command -v md5sum >/dev/null 2>&1; then sum=$(pwd -P | tr -d '\n' | md5sum | cut -d' ' -f1)
+  else sum=$(pwd -P | tr -d '\n' | md5 -q); fi
+  printf '%s/chats/%s/%s/store.db' "$CURSOR_CONFIG_DIR" "$sum" "$1"
+}
+
+if [ -n "${OPENRIG_RESUME_REF:-}" ]; then
+  id="$OPENRIG_RESUME_REF"
+  plain_id "$id" || { echo "openrig-cursor-launch: refusing an unusual chat id" >&2; exit 2; }
+  # Cursor's `--resume` with an id it doesn't hold exits 0 on a new, empty chat, so check first. Gone: say so, start nothing.
+  if [ ! -f "$(chat_store "$id")" ]; then
+    report "{\"format\":1,\"attempt\":\"${OPENRIG_LAUNCH_ATTEMPT:-}\",\"harness\":\"cursor\",\"error\":\"missing\",\"producer\":\"$producer\"}"
+    echo "openrig-cursor-launch: Cursor has no chat $id in $CURSOR_CONFIG_DIR for $(pwd -P); starting nothing" >&2
+    exit 1
+  fi
+else
+  # create-chat prints the id but doesn't exit (see #352): read the first line, then stop it.
+  out=$(mktemp)
+  "$cursor" create-chat > "$out" 2>/dev/null &
+  pid=$!
+  i=0
+  while [ "$i" -lt 100 ] && [ ! -s "$out" ]; do sleep 0.1; i=$((i + 1)); done
+  kill "$pid" 2>/dev/null || true
+  id=$(head -n 1 "$out" | tr -d '\r\n\t ')
+  rm -f "$out"
+  # No usable id: report nothing, so OpenRig shows the identity as unavailable, and start Cursor on its own chat.
+  plain_id "$id" || exec "$cursor" --trust "$@"
+fi
+
+report "{\"format\":1,\"attempt\":\"${OPENRIG_LAUNCH_ATTEMPT:-}\",\"harness\":\"cursor\",\"nativeRef\":\"$id\",\"producer\":\"$producer\"}"
+exec "$cursor" --resume "$id" --trust "$@"

package/daemon/docs/reference/community-harness-examples/hermes/config.yaml.example

@@ -0,0 +1,18 @@
+# Merge this into each Hermes seat's config.yaml, in that seat's Hermes home ($OPENRIG_HOME/state/hermes/<node id> with
+# the example launcher), before the seat's first start.
+#
+# Hermes runs every tool command in one gateway per machine, with the gateway's environment. For each session it swaps
+# in the client's own values only for its toolchain names and the names listed here. Without this list, `rig` inside
+# Hermes runs as whichever seat started the gateway, or as no seat. With it, each seat runs `rig` as itself.
+# These are the seat's own OpenRig variables; none is a secret, and Hermes refuses credential-like names anyway.
+terminal:
+  client_env_passthrough:
+    - OPENRIG_SESSION_NAME
+    - OPENRIG_NODE_ID
+    - OPENRIG_HOME
+    - OPENRIG_URL
+    - OPENRIG_HOST
+    - OPENRIG_PORT
+    - OPENRIG_DB
+
+# Your own settings go beside it (the guide says which): the model and provider, and agent.max_turns if you want a cap.

package/daemon/docs/reference/community-harness-examples/hermes/hermes.yaml

@@ -0,0 +1,12 @@
+# Install as $OPENRIG_HOME/community-harnesses/hermes.yaml, with openrig-hermes-launch on the seat's PATH.
+format: 1
+name: hermes
+command: openrig-hermes-launch    # no model, provider or --max-turns here: they go in the seat's Hermes config.yaml
+maintainer: Your name or team
+limits:
+  - resume not declared until reopening a named session, and a missing one, have been checked with a real Hermes
+  - closing a seat's pane detaches it; Hermes finishes any accepted turn, and its gateway exits when idle
+  - creation settings (model, provider, max turns) come from the seat's Hermes config.yaml, not from flags
+  - no guidance, skills or startup files are placed
+  - needs-input and approval prompts are read from the screen only
+names_conversation: true

package/daemon/docs/reference/community-harness-examples/hermes/openrig-hermes-launch

@@ -0,0 +1,34 @@
+#!/bin/sh
+# A reference launcher for Hermes Agent's CLI as an OpenRig community harness. Copy it, own it, and change it: OpenRig
+# doesn't ship or run it. It follows docs/reference/community-harness-presets.md (`names_conversation`):
+#   - a new launch (OPENRIG_CONVERSATION set): Hermes creates the session titled with that name;
+#   - a resume (OPENRIG_RESUME_REF set): Hermes reopens that session, and never creates one. A name that matches nothing
+#     ends with Hermes's own "No session found" error, so a gone conversation isn't replaced by a new one.
+# Put the model, provider and max turns in the seat's Hermes config.yaml, not on the command line. Hermes v0.22.4's CLI
+# creates a `-c <name> --create-if-missing` session with no launch flags, then reopens it and refuses any creation flag
+# that differs, so such flags fail even on a new name. Other arguments go only to a new session, never to a resume.
+set -eu
+
+hermes="${OPENRIG_HERMES:-hermes}"
+
+# Each seat gets its own Hermes home, so seats don't share sessions or a gateway, and a seat's stop concerns only its own.
+# Its settings (model, provider, agent.max_turns) come from that home's config.yaml, and its key from the environment
+# (an OpenRouter key, say), not from the person's ~/.hermes.
+HERMES_HOME="${OPENRIG_HOME:-$HOME/.openrig}/state/hermes/${OPENRIG_NODE_ID:-${OPENRIG_SESSION_NAME:-default}}"
+export HERMES_HOME
+mkdir -p "$HERMES_HOME"
+
+# Hermes's tools see its shared gateway's environment except for the names a profile passes through, so a seat whose
+# config.yaml doesn't pass OPENRIG_SESSION_NAME would run `rig` as another seat, or as none (see config.yaml.example).
+if ! grep -qs OPENRIG_SESSION_NAME "$HERMES_HOME/config.yaml"; then
+  echo "openrig-hermes-launch: $HERMES_HOME/config.yaml doesn't pass OPENRIG_SESSION_NAME to Hermes's tools, so rig run from Hermes won't act as this seat; see config.yaml.example" >&2
+fi
+
+if [ -n "${OPENRIG_RESUME_REF:-}" ]; then
+  exec "$hermes" chat -c "$OPENRIG_RESUME_REF"
+fi
+if [ -n "${OPENRIG_CONVERSATION:-}" ]; then
+  exec "$hermes" chat -c "$OPENRIG_CONVERSATION" --create-if-missing "$@"
+fi
+echo "openrig-hermes-launch: OpenRig passed no conversation name; is names_conversation set in the preset?" >&2
+exit 2

package/daemon/docs/reference/community-harness-examples/openclaw/openclaw.yaml

@@ -0,0 +1,13 @@
+# Install as $OPENRIG_HOME/community-harnesses/openclaw.yaml, with openrig-openclaw-launch on the seat's PATH.
+format: 1
+name: openclaw
+command: openrig-openclaw-launch
+maintainer: Your name or team
+limits:
+  - resume not declared until reopening a named session, and a missing one, have been checked with a real OpenClaw
+  - runs locally in the pane (openclaw chat), with no Gateway; Gateway-attached use isn't covered
+  - automatic session resets (session.reset) must stay off, or a key can start a new conversation
+  - typing /new in the pane moves the chat to a fresh session key; the seat still holds the name OpenRig gave it
+  - no guidance, skills or startup files are placed
+  - needs-input and approval prompts are read from the screen only
+names_conversation: true

package/daemon/docs/reference/community-harness-examples/openclaw/openrig-openclaw-launch

@@ -0,0 +1,38 @@
+#!/bin/sh
+# A reference launcher for OpenClaw's CLI as an OpenRig community harness. Copy it, own it, and change it: OpenRig
+# doesn't ship or run it. It follows docs/reference/community-harness-presets.md (`names_conversation`):
+#   - a new launch (OPENRIG_CONVERSATION set): OpenClaw's local chat starts on the session key OpenRig named;
+#   - a resume (OPENRIG_RESUME_REF set): it first checks that this seat's sessions list the key, and stops if they
+#     don't, so a gone conversation isn't quietly recreated under its old key.
+# It runs `openclaw chat` (the TUI with --local): the agent runs in the seat's own pane, with no Gateway. Arguments after
+# the launcher's name go to every launch and resume alike.
+set -eu
+
+openclaw="${OPENRIG_OPENCLAW:-openclaw}"
+
+# Each seat gets its own OpenClaw state folder: --local needs it to itself, and seats don't share sessions.
+# Its provider settings and credentials come from that folder's config or the environment, not the person's ~/.openclaw.
+OPENCLAW_STATE_DIR="${OPENRIG_HOME:-$HOME/.openrig}/state/openclaw/${OPENRIG_NODE_ID:-${OPENRIG_SESSION_NAME:-default}}"
+export OPENCLAW_STATE_DIR
+mkdir -p "$OPENCLAW_STATE_DIR"
+
+if [ -n "${OPENRIG_RESUME_REF:-}" ]; then
+  key="$OPENRIG_RESUME_REF"
+  # A key may be stored bare or as agent:<id>:<key>; either counts as this conversation.
+  if ! "$openclaw" sessions --json --limit all | KEY="$key" node -e '
+    let raw = ""; process.stdin.on("data", (chunk) => { raw += chunk; });
+    process.stdin.on("end", () => {
+      const key = process.env.KEY;
+      const sessions = JSON.parse(raw).sessions || [];
+      process.exit(sessions.some((s) => s.key === key || String(s.key).endsWith(`:${key}`)) ? 0 : 1);
+    });'; then
+    echo "openrig-openclaw-launch: this seat's OpenClaw sessions don't list \"$key\" (or couldn't be listed); not starting a new one under that key" >&2
+    exit 3
+  fi
+  exec "$openclaw" chat --session "$key" "$@"
+fi
+if [ -n "${OPENRIG_CONVERSATION:-}" ]; then
+  exec "$openclaw" chat --session "$OPENRIG_CONVERSATION" "$@"
+fi
+echo "openrig-openclaw-launch: OpenRig passed no conversation name; is names_conversation set in the preset?" >&2
+exit 2

package/daemon/docs/reference/community-harness-presets.md

@@ -0,0 +1,179 @@
+# Community harness presets
+
+A community harness is a coding harness an outside contributor maintains. You install it as one small data file, and a
+rig member runs it by naming it as its `runtime`. OpenRig doesn't test these harnesses. It shows them as community
+harnesses, and it reads their activity only from what the screen shows.
+
+## The preset
+
+One YAML file per harness: `$OPENRIG_HOME/community-harnesses/<name>.yaml`. `rig community-harness list` shows what's
+installed.
+
+```yaml
+format: 1
+name: example-harness           # must match the file name: lowercase letters, digits and hyphens
+command: example-launch         # one program and its arguments, typed into the seat's pane
+maintainer: Example Maintainer
+limits:                         # what the maintainer says doesn't work
+  - fork unsupported
+launch_result: true             # optional: the launcher reports the conversation it created (below)
+# names_conversation: true      # optional, instead of launch_result: OpenRig names the conversation (below)
+resume: true                    # optional, needs one of those two; declare it only once your harness's resume is checked
+startup_assisted: true           # optional: startup submission needs a person's check (below)
+```
+
+- **`command`** is a single program and its arguments. Shell syntax such as `|`, `&&`, `;`, redirections or `$(…)`
+  is refused: put it in a script and name the script.
+- **Built-in runtime names are reserved.** A preset can't replace `claude-code`, `codex` or the other built-ins.
+- **Unknown fields are refused,** so a preset written for a newer OpenRig says so instead of half-working.
+- **Fork isn't supported, and resume only as described below.** Neither is placing skills, guidance or startup files. Except
+  for assisted startup below, the seat is called ready while something other than a shell runs in its pane, which says
+  nothing about which conversation it is.
+
+### Assisted startup
+
+Set `startup_assisted: true` when the harness doesn't reliably submit OpenRig's startup text. OpenRig still pastes the
+text and presses Enter once. If it sends startup text, the running seat then shows **attention required**, rather than
+ready: check its pane and submit any text still in the composer. Don't resend the identity prompt. After the seat responds,
+use the reported `rig seat clear-attention <session> --reason "Startup submission checked; seat responded"` command to
+acknowledge the check. A launch with no startup text needs no such check. Other presets keep their existing behavior.
+
+## Reporting the conversation a launch created (`launch_result: true`)
+
+Some harnesses create their own conversation id before they start. Cursor's `cursor-agent create-chat` is one. With
+`launch_result: true`, the harness's launcher tells OpenRig that id for each launch.
+
+1. **OpenRig names one file per launch attempt.** It starts `command` with two variables:
+   - `OPENRIG_LAUNCH_RESULT`, a new file path inside `$OPENRIG_HOME/state/launch-results/`;
+   - `OPENRIG_LAUNCH_ATTEMPT`, this attempt's id.
+2. **The launcher writes one JSON record to that path,** then starts the harness:
+   ```json
+   { "format": 1, "attempt": "<OPENRIG_LAUNCH_ATTEMPT>", "harness": "cursor", "nativeRef": "<the conversation id>", "producer": "openrig-cursor-launch 1.0" }
+   ```
+3. **OpenRig reads that attempt's record once,** waiting up to 20 seconds for it. It records `nativeRef` on the session,
+   and the seat shows its identity as **reported by its launcher, not observed**. That's what the launcher says, not
+   proof that the harness used it.
+
+The seat still starts, with its identity **unavailable** and the reason named, when the record:
+- wasn't written;
+- belongs to another attempt or another harness;
+- isn't JSON, isn't format 1, or is larger than 64 KiB;
+- has an unusable `nativeRef` (empty, too long, or containing spaces or control characters);
+- names no producer;
+- or is reached through a link.
+
+None of these means the conversation is gone.
+
+A reported id doesn't make the harness resumable on its own. Without `resume: true`, nothing resumes it: a restore
+stops and asks, as it did before (re-run it with `--fresh <seat>` only if you want a new conversation), and elsewhere a
+resume says it's unsupported, and a new conversation starts only where the caller allows a fresh start.
+
+**Good to know:**
+- **The variables are passed with `/usr/bin/env`,** so `launch_result` needs a POSIX system.
+- **A launcher that never writes its record** adds up to 20 seconds to each launch, while OpenRig waits for it.
+- **Records are kept,** one small file per attempt, under `$OPENRIG_HOME/state/launch-results/<session>/`. A record
+  larger than 64 KiB isn't read.
+
+## Letting OpenRig name the conversation (`names_conversation: true`)
+
+Some harnesses take a conversation name from the caller and create that conversation, or reopen it. Hermes's
+`hermes chat -c <name> --create-if-missing` is one. With `names_conversation: true`, OpenRig names each new conversation
+and the harness uses that name, so no record is needed.
+- **A new launch:** OpenRig starts `command` with `OPENRIG_CONVERSATION` set to a new name, `openrig-<seat>-<8 hex digits>`
+  (at most 100 characters). Each launch gets its own name, so two seats never share a conversation.
+- **What the seat shows:** OpenRig records that name on the session, and the seat shows its identity as **named by
+  OpenRig, not observed**. That's the name OpenRig passed, not proof that the harness used it.
+- **Not with `launch_result`:** a preset declares one or the other. Either the launcher reports the conversation, or
+  OpenRig names it.
+
+## Reopening a conversation (`resume: true`)
+
+**A named conversation:** with `names_conversation`, a resume starts `command` with `OPENRIG_RESUME_REF` set to the saved
+name. The harness reopens it and must never create one under that name. Nothing reports back, so:
+- **readiness is process-only:** the seat reads as ready while something other than a shell runs in its pane. That
+  doesn't show the named conversation exists: a harness (or a launcher's own check) that hasn't yet found it gone reads
+  as ready, and the saved name stays unverified until something observes it;
+- **never creating one is the launcher's job:** a resume must not create a conversation under the saved name. When it's
+  gone, the harness or launcher ends with its error and the pane is back at a shell; the seat keeps its saved name, and
+  OpenRig starts nothing new, though the seat may already have read as ready;
+- **a former runtime's id** isn't passed to the harness, as below.
+
+**A reported conversation:** with `launch_result`, a resume (a restore included) starts the launcher with `OPENRIG_RESUME_REF` set to the
+conversation to reopen. The launcher reports what happened in the same attempt's file:
+- **Reopened:** the usual record, with that conversation as `nativeRef`.
+- **Gone:** `{ "format": 1, "attempt": "…", "harness": "cursor", "error": "missing", "producer": "…" }`. The launcher
+  starts nothing. OpenRig reports the conversation missing and starts nothing either: it never replaces it with a new one.
+
+For a reported conversation, OpenRig also says so plainly when:
+- **no usable record is written:** the resume isn't confirmed. The seat needs attention and keeps the conversation it
+  asked for; nothing is restarted;
+- **the record names a different conversation:** the seat needs attention and keeps the conversation it asked for.
+  OpenRig doesn't switch it to the reported one;
+- **the saved conversation isn't this harness's own** (a former runtime's id, say): it isn't passed to the launcher. A restore stops and asks, and elsewhere the resume says it isn't possible;
+- **the record's folder can't be made:** the launcher couldn't be told what to reopen, so nothing starts.
+
+## An example: Hermes
+
+[`community-harness-examples/hermes/`](community-harness-examples/hermes/) has a preset and a small launcher for Hermes
+Agent's CLI.
+- **The launcher:** it creates the session OpenRig named (`-c <name> --create-if-missing`), and on a resume reopens it
+  without `--create-if-missing`, with its own Hermes home per seat. A name that matches nothing ends with Hermes's own
+  "No session found" error.
+- **Settings go in the seat's Hermes `config.yaml`, not in flags:** Hermes's CLI creates a named session with no launch
+  flags and then reopens it, refusing any creation flag (model, provider, `--max-turns`) that differs. So the preset's
+  command carries none, and each seat's `config.yaml`, in its Hermes home, sets them before the seat's first start:
+  the model and provider, and `agent.max_turns` if you want a cap (nothing else sets it once the flag is gone).
+- **Let Hermes run `rig` as the seat:** Hermes runs every tool command in one gateway per machine, with that gateway's
+  environment, and swaps in a session's own values only for its toolchain names and the names its profile lists in
+  `terminal.client_env_passthrough`. So put the seat's OpenRig variables in that list, in each seat's `config.yaml`
+  ([`config.yaml.example`](community-harness-examples/hermes/config.yaml.example)). Without it, `rig` inside Hermes
+  runs as whichever seat started the gateway, or as no seat; with it, each seat runs `rig` as itself. To check, ask the
+  seat's Hermes to run `rig whoami --json`. The launcher warns when a seat's `config.yaml` doesn't pass
+  `OPENRIG_SESSION_NAME`. This covers Hermes's CLI and TUI, whose clients pass their environment; its ACP clients pass
+  none.
+- **The preset:** it declares `names_conversation` but not `resume`, until reopening a named session, and a missing one,
+  have been checked with a real Hermes.
+- **Stopping:** Hermes's CLI is a client of a gateway, so closing a seat's pane detaches it. Hermes finishes any turn it
+  accepted, and the seat's gateway exits once idle. The preset says so in its limits.
+
+Copy them and maintain them as your own.
+
+## An example: OpenClaw
+
+[`community-harness-examples/openclaw/`](community-harness-examples/openclaw/) has a preset and a small launcher for
+OpenClaw's CLI.
+- **The launcher:** it runs `openclaw chat` (the TUI with `--local`) on the session key OpenRig named, with its own
+  OpenClaw state folder per seat, so the agent runs in the seat's pane with no Gateway.
+- **Its resume check:** before reopening a key, the launcher checks that the seat's `openclaw sessions --json` lists it,
+  and stops if not, so a gone conversation isn't recreated under its old key. That check is the launcher's code, not
+  OpenRig's.
+- **Resets must stay off:** OpenClaw can start a new conversation under the same key on a reset rule
+  (`session.reset`). That's off by default; with it on, a key no longer names one conversation. Likewise, typing `/new`
+  in the pane moves the chat to a fresh session key, while the seat still holds the name OpenRig gave it.
+- **The preset:** it declares `names_conversation` but not `resume`, until both have been checked with a real OpenClaw.
+
+Copy both and maintain them as your own.
+
+**Not supported for community harnesses:** restarting a seat in place (`rig seat restart` is for Codex seats) and
+switching harness on a running seat. Each says so before anything changes.
+
+## An example: Cursor
+
+[`community-harness-examples/cursor/`](community-harness-examples/cursor/) has a preset and a small launcher for Cursor's
+CLI.
+- **The launcher:** it reports the chat `cursor-agent create-chat` makes, then reopens it. Each seat gets its own Cursor
+  config folder unless `CURSOR_CONFIG_DIR` is already set. Cursor keeps its chats and `cli-config.json` there, and its
+  login elsewhere.
+- **The preset:** it declares `launch_result` and `resume`. Cursor's `--resume` with an id it doesn't hold starts a new,
+  empty chat without saying so, so on a resume the launcher first checks that the chat's store exists. When it doesn't, the
+  launcher reports `error: "missing"` and starts nothing.
+- **Startup is assisted:** identity text has remained in Cursor's composer after the initial Enter. The preset declares
+  `startup_assisted: true`; check and submit it in the pane as above. Unattended startup submission is not confirmed.
+- **Sender names come from the sending session.** A command run from an unattached operator shell can arrive as
+  `<unknown sender>`; that doesn't mean the receiving Cursor seat lost its identity.
+
+Copy both and maintain them as your own.
+
+The launcher is the contributor's code, in the contributor's package. OpenRig runs no code from a preset and loads no
+module into its daemon. A preset that sets `launch_result`, `names_conversation` or `startup_assisted` is refused by an older
+OpenRig that doesn't know the field.

package/daemon/docs/reference/getting-started.md

@@ -50,6 +50,9 @@ The `rigs` skill is the procedure: follow it in order. This page is what it look
 >   - Claude Code: workspace trust in `~/.claude.json`, and activity hooks in the project's
 >     `.claude/settings.local.json`, plus a status line unless you already have your own.
 >   - Discovery skills go in `~/.claude/skills` and `~/.agents/skills`.
+>   - Each seat's `CLAUDE.md` or `AGENTS.md` gets OpenRig's managed blocks (culture, identity, onboarding). One more
+>     line, pointing an agent at its seat skills, is added only on a yes: saved at setup, or set where the daemon runs
+>     (`OPENRIG_SKILLS_ROUTER_LINE_ENABLED`).
 > - **Starting a team in your project:** adds managed guidance to `AGENTS.md` or `CLAUDE.md`, plus the team's skills
 >   and plugins.
 > - **Permissions:** by default, OpenRig's own kernel gets broader permissions than a project team gets by default.
@@ -72,12 +75,16 @@ you aren't an administrator, or where Homebrew belongs to another account (its
 `brew install` is refused), install Node.js in your own home folder with
 [nvm](https://github.com/nvm-sh/nvm): run `touch ~/.zshrc` (a new Mac account
 has none, and nvm's installer only adds itself to a profile file that already
-exists), then the install command on nvm's page, open a new terminal, and run
-`nvm install 22`. That needs no administrator password, and `npm install -g`
-then installs into your nvm folder. Native
-Windows isn't supported. On Windows, use WSL2: it's the Windows route OpenRig
-supports, though OpenRig's automated tests don't run on it yet. One user's
-[working setup](#wsl2-a-reported-working-setup) is below. Node 20 and
+exists), then nvm's install command, for nvm v0.40.8
+`curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash`
+([nvm's page](https://github.com/nvm-sh/nvm#install--update-script) has the
+newest), open a new terminal, and run `nvm install 22`. nvm itself needs no
+administrator password, and `npm install -g` then installs into your nvm folder.
+If nvm's installer says you need Apple's command line tools, run
+`xcode-select --install`, then its install command again. Native Windows isn't
+supported. On Windows, use WSL2: it's the Windows route
+OpenRig supports, though OpenRig's automated tests don't run on it yet. One
+user's [working setup](#wsl2-a-reported-working-setup) is below. Node 20 and
 odd-numbered releases (23, 25 and so on) are not supported; Node 26 and later
 even-numbered releases are untested.
 
@@ -177,20 +184,19 @@ You can also read [`skills/rigs/SKILL.md`](../../skills/rigs/SKILL.md) directly.
 script will do and changes nothing:
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.14/scripts/install.sh | sh -s -- --dry-run
+curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.1/scripts/install.sh | sh -s -- --dry-run
 ```
 
 The same command without `--dry-run`,
-`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.14/scripts/install.sh | sh`, installs the
+`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.1/scripts/install.sh | sh`, installs the
 latest published `@openrig/cli` with `npm install -g`,
 runs the Node.js and SQLite check, then `rig setup --dry-run` and `rig setup`. `rig setup` checks both Claude Code and
-Codex and may install a missing one, as described below. A failed step among the first three prints
-`FAILED [n/4] <command or check> (exit <code>)`. When `rig setup` (step 4) doesn't finish ready, for example because a
-provider isn't signed in yet, the script ends with `INSTALLED, SETUP NOT COMPLETE (exit <code>)`: the CLI is
-installed, and `rig setup` lists what's left under "Some steps need attention". If the only items left are provider
-sign-ins, sign in to each selected provider as below, then continue at
-[Start the kernel](#start-the-kernel-and-check-its-state); run `rig setup` again rather than reinstalling the CLI. To
-install only what the selected providers need, go step by step instead:
+Codex and may install a missing one, as described below. A failed step prints
+`FAILED [n/4] <command or check> (exit <code>)`. Where a provider isn't signed in yet, step 4 ends that way and
+`rig setup` lists each sign-in under "Some steps need attention". If the only remaining failures are provider
+sign-ins, the install steps finished: sign in to each selected provider as below, then continue at
+[Start the kernel](#start-the-kernel-and-check-its-state). To install only what the selected providers need, go step
+by step instead:
 
 ### Choose your providers
 
@@ -220,6 +226,37 @@ writes an OpenRig-managed block (mouse on, a longer history) into `~/.tmux.conf`
 It is optional for this selected-provider path, not a requirement to fix an unused
 provider.
 
+Setup also prints the one line OpenRig can add to each seat's `CLAUDE.md` or
+`AGENTS.md`, plus OpenRig's markers around it so it can be removed cleanly: the
+exact text it writes, which files it goes in, and what a no gives up. Show the person,
+ask, and save their answer with `rig setup --router-line yes` or
+`rig setup --router-line no`. No answer isn't a yes: with nothing saved and
+nothing set in the environment, the line isn't added. The answer covers only
+that line, and so does what setup says a no gives up; setup's "OpenRig may
+modify" list names the other writes.
+
+The block keeps `terminal.history_limit` rows of scrollback per pane (default
+10000). To keep more, run `rig config set terminal.history_limit 50000`, then
+`rig setup` again. A running tmux server keeps its old limit until it restarts
+or you run `tmux source-file ~/.tmux.conf`; before tmux 3.7 that changes new
+panes only.
+
+New managed agents and handover successors on macOS/Linux start from the daemon's
+selected launch environment and declared seat values, rather than stored tmux globals.
+Values named by tmux's `update-environment` option, including its default SSH-agent
+and display variables, come from the daemon's environment.
+Normal shell startup and configured tmux shell commands still run. OpenRig reasserts its
+selected `OPENRIG_DB` and configured `TMUX_TMPDIR` when starting the runtime after shell startup.
+If your custom setup intentionally supplies values through tmux's global environment,
+opt in with
+`rig config set terminal.inherit_tmux_environment true`. Setup points out this option
+when it detects custom tmux configuration; it never enables it automatically. The setting
+applies to future launches and successors, not running agents or your personal tmux server.
+If the scoped environment cannot be prepared, launch keeps its previous environment and
+reports a warning in fresh launch results and the daemon log. For handovers, check
+that log for this warning. This is not a promise that shell startup cannot add or override values.
+
+
 ## Start the kernel and check its state
 
 With a working selected login, start the daemon if it is stopped, then read its
@@ -251,9 +288,51 @@ A missing or unknown readiness signal is not proof of readiness. Follow
 startup or missing-seat problems.
 
 `rig setup` itself does not start the daemon. Preserve a daemon and kernel that
-already exist: ordinary daemon startup skips a managed kernel, and
-`OPENRIG_NO_KERNEL=1` skips automatic kernel startup. If neither runtime is
-authenticated, kernel boot reports `auth_blocked`. Do not restart or recreate an
+already exist: daemon startup does not boot a second kernel when one is managed,
+and `OPENRIG_NO_KERNEL=1` (`--no-kernel`) skips automatic kernel startup,
+including the restore below. If neither runtime is authenticated, kernel boot
+reports `auth_blocked`.
+
+Daemon startup restores one existing kernel by itself: a managed kernel whose
+seats are all `detached` and still bound to their newest session, which is what
+startup reconcile leaves when every kernel terminal is gone, for example after a
+reboot. It does not detect a reboot as such. It uses the same restore as
+`rig up kernel --existing`, and `rig status` reports it as `Kernel: booting`
+until the seats are ready. A kernel stopped with `rig down kernel`, including
+one whose seats were already detached, stays down on later starts. So do a kernel
+with only some seats stopped and seats you unclaimed. Start one again with
+`rig up kernel --existing`.
+When the tmux server is gone, an explicit `rig down` of any rig can start an
+empty server and probe again. It records the stop and clears eligible bindings
+only after confirming the sessions are absent. This can leave an empty tmux
+server running; it never launches an agent or provider session. Unreadable or
+permission results and changed occupants leave the stop bookkeeping unchanged.
+
+While that automatic restore runs, `rig start` continues to your other rigs and
+says the kernel is still restoring (`kernelRestore.state: "restoring"` with
+`--json`). Its exit status 0 then does not mean the kernel is ready; check
+`rig status`. When the restore has returned without a ready kernel, `rig start`
+still goes on to your other rigs but exits 1 (`kernelRestore.state: "failed"`),
+so `rig start && next` does not run `next`. A `rig down kernel` made during the
+restore waits for it to return and then stops the kernel, which stays down on
+later starts. A `rig up kernel --existing` with no fresh seats and no change to
+the saved non-interruptive choice, made during the restore, or after it restored
+every seat while those seats still run the sessions it started, reports that
+restore's outcome instead of starting another. Explicitly repeating the saved
+`--non-interruptive` or `--no-non-interruptive` choice also joins that restore.
+
+An explicit `rig up kernel --existing --fresh <seat...>` waits for startup's
+restore to finish, then replaces only the named seats that still hold the exact
+sessions startup launched. Other seats keep running. An operator's conversation
+correction also takes effect for that seat on the next explicit `up` or
+`restore`, using the corrected target; editing the token alone restarts nothing.
+Each replacement takes new seat leases, rechecks the managed occupant and terminal,
+and reports its own per-seat outcome. If the occupant changed, it is left alone.
+A different `--non-interruptive` or `--no-non-interruptive` choice after startup
+launched the seats is refused: the running launch choice stays unchanged. Stop
+the rig, then rerun with the desired choice.
+
+Do not restart or recreate an
 existing kernel merely to open its view. The startup TUI (`rig`) offers its own
 kernel setup and individual-seat recovery; it does not automatically boot agents
 when it starts the daemon.
@@ -410,6 +489,11 @@ rig terminal open saved:kernel --provider cmux --json
 ```
 
 Use `rig terminal status --json` to inspect provider availability and liveness.
+To keep rigs in separate Herdr sessions, select one explicitly:
+`rig terminal open future-prod-rig --provider herdr --session future-prod`.
+`--session default` selects Herdr's default session; omitting the option keeps
+the daemon's configured endpoint. See [named terminal sessions](terminal-sessions.md)
+for desktop windows, previews and session-specific status.
 For the first desktop handoff, use `--window`. Only if the window cannot open,
 `rig tui --shared` is the dashboard-only fallback, not the operator's conversation.
 
@@ -512,8 +596,8 @@ rig ps --nodes --rig starter
 
 Preview the selected seats, models and resources. Plan checks resolution and
 preflight for the working directory. The kernel is already your entry point; this step starts the chosen project
-team. Read readiness for the project seats, not only daemon health. Resolve a named authentication, trust or permission prompt before giving
-that seat work. When a seat stops at such a prompt, `rig up` reports
+team. Read readiness for the project seats, not only daemon health. Have the person answer a named authentication, trust, hook-review or
+permission prompt before giving that seat work; a launch default, or their answer for another seat, isn't their answer to this one. When a seat stops at such a prompt, `rig up` reports
 `Status: partial`, prints `Startup attention (<seat>): <reason>` and exits 1;
 `rig ps --nodes` repeats it as "Startup details". The reason ends with the command
 to run once the prompt is answered: `rig seat continue <seat>`, which delivers the
@@ -690,7 +774,7 @@ the lifecycle API without booting a new kernel, then stop the remaining rigs.
 | Shared terminal is absent | Inspect the existing kernel binding and recovery state; use standalone `rig tui` while resolving it. |
 | Viewing terminal was closed | Open the conversations again with `rig terminal open saved:kernel --window`; `rig tui --shared` is only the dashboard fallback if that window cannot open. Do not relaunch the team. |
 | Daemon restarted but tmux survived | Re-read `rig status` and the existing queue; a daemon restart is not a fresh project. |
-| Host reboot lost tmux sessions | Open `rig`, start the daemon if needed (press **S** if it opens on the work views), and select the existing rig and seats. Resume is the default; a fresh conversation needs a separate decision. |
+| Host reboot lost tmux sessions | Starting the daemon restores the kernel by itself when all of its seats were lost; check `rig status`, and if it reports the restore failed, run `rig up kernel --existing`. For other rigs, open `rig`, start the daemon if needed (press **S** if it opens on the work views), and select the existing rig and seats. Resume is the default; a fresh conversation needs a separate decision. |
 | Launch reports no usable snapshot | Inspect the existing rig and retained project files, then follow the same-seat recovery below. |
 | Work is waiting on a prompt or decision | Read the row, transition and named prompt; preserve the obligation until the missing decision arrives. |
 
@@ -721,8 +805,27 @@ This recovery is for the case the reporter hit: the kernel's seats failed and no
 IDs, for example `advisor.lead operator.agent operator.human queue.worker` when all four failed. `--fresh` starts a
 new conversation for each seat you name. Seats you don't name follow their normal recovery policy and may remain
 awaiting a decision if their old conversation can't be resumed. A later `rig daemon start` doesn't retry the failed
-seats by itself: once a kernel exists, startup skips the built-in kernel boot, and `rig status` then reads
-`Kernel: skipped` whatever its seats' state, so check `rig ps --nodes --rig kernel --full`.
+seats by itself: once a kernel exists, startup skips the built-in kernel boot and restores only a kernel whose seats
+were all lost, not seats that failed. `rig status` then reads `Kernel: skipped` unless some of its seats are running
+and ready, so check `rig ps --nodes --rig kernel --full`.
+
+**When every agent stops at once on Ubuntu 22.04.** Ubuntu 22.04's packaged tmux, 3.2a, can exit its whole server
+when it's asked about a pane or session that has just closed. OpenRig checks each seat about once a second, so when a
+seat's session closes, the next check can stop every agent on that tmux server, and tmux reports "server exited
+unexpectedly". This was reproduced with Ubuntu 22.04's `tmux 3.2a-4ubuntu0.3` for a closed pane, a closed session,
+and a closed pane in a window that stayed open. If `tmux -V` prints `tmux 3.2a`, put tmux 3.4 or later first on
+your `PATH`. Newer versions weren't tested against this crash; #980's reporter runs 3.5a, and none of OpenRig's own
+machines runs 3.2a. One way to get one is to build a current release from the tmux project, as that reporter did:
+
+```sh
+sudo apt install build-essential pkg-config bison libevent-dev libncurses-dev
+# in the unpacked release tarball:
+./configure && make && sudo make install   # installs into /usr/local/bin
+```
+
+Then restart the daemon from a shell where `tmux -V` shows the new tmux. A tmux server that's already running keeps
+its version until it exits, so the change applies to servers started afterwards. If a crash already stopped your
+agents, recover as for lost tmux sessions in the table above.
 
 If a snapshot is unavailable, the startup view checks the selected seat's
 retained startup source and authoritative occupant relation. It reports a
@@ -1072,6 +1175,28 @@ and connection, and equal UIDs do not distinguish separate instances belonging
 to one account. The check
 does not add authentication to the daemon or protect direct HTTP clients.
 
+## Optional database-conflict stop
+
+By default, daemon startup warns and continues when another live daemon is confirmed
+using the selected database. To stop before opening that database instead, run
+`rig config set daemon.db_conflict stop` (set it to `warn` for the default).
+The check requires an open-file holder, a matching `daemon.json`, and a listener
+reporting the same PID; missing or inconclusive evidence does not stop startup.
+Selecting a database outside `OPENRIG_HOME` alone only warns; a confirmed live-daemon
+conflict there still stops when `daemon.db_conflict` is `stop`.
+
+To proceed deliberately for one start, use
+`rig daemon start --allow-db-conflict` with the original start options.
+The flag sets the override on that child only and does not change the setting.
+The underlying `OPENRIG_ALLOW_DB_CONFLICT=1` environment override is also supported:
+exporting it applies to every later start from that shell, even after changing
+`OPENRIG_HOME`. An inherited copy can also bypass the stop in a later seat or test
+home. An inherited `OPENRIG_DAEMON_DB_CONFLICT` overrides that home's file setting;
+inspect or unset inherited overrides when changing homes.
+Separate instances should use separate databases; the check is a startup observation,
+not a lock against later concurrent starts. Changing the setting applies on the next
+daemon start.
+
 ## Custom settings and precedence
 
 - **OpenRig:** member `permission_policy` overrides rig `permission_policy`.

package/daemon/docs/reference/operation-correlation.md

@@ -0,0 +1,9 @@
+# HTTP operation correlation
+
+`GET /api/operations/capabilities` advertises `operation-correlation.v1` and the supported kinds: `rig.create`, `rig.import`, and `member.add`. A client should check this marker before relying on correlation; an older daemon may ignore an unfamiliar request header.
+
+For `POST /api/rigs`, `POST /api/rigs/import`, and `POST /api/rigs/:rigId/pods/:podNamespace/members`, send a UUID in `X-OpenRig-Operation-Id`. Keep the same daemon, route targets, original request text, and behavior-changing headers for a retry. IDs are case-normalized. An ID that isn't an RFC UUID receives HTTP 400 `Invalid X-OpenRig-Operation-Id` before the route does anything else. Once a request passes the route's own validation, a different request using the same ID receives HTTP 409 `operation_id_conflict`. Matching compares the exact request text, so a change in whitespace or key order is a different request, not an equivalent one; an exact replay receives HTTP 200 with `replayed: true` and current database state. A first request retains its usual status and response fields and adds `operation`.
+
+The operation contains the rig and node IDs committed by that request. Its `current` field reads the database at response time, including whether recorded resources still exist and the latest recorded session for each node. It does not inspect tmux or prove a launch finished. A reservation with no IDs can mean that execution is still underway or that it failed before creating resources. Replaying an exact request that failed before creating resources returns HTTP 200 with `operation.rigId: null` and `operation.nodeIds: []`; inspect those fields to distinguish it from a replay that recorded resources. Replays never execute the mutation again, retry a launch, or recreate deleted resources. Use a new UUID only when deliberately starting a new execution.
+
+This contract stores neither the original response nor a recovery verdict. An HTTP response can be lost after a database commit. External launch effects are outside the database transaction, so the contract is correlation rather than exactly-once execution of external effects.