@openrig/cli 0.7.0 → 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.
@@ -181,11 +184,11 @@ 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.7.0/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.7.0/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 prints
@@ -223,6 +226,15 @@ 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
@@ -233,8 +245,10 @@ New managed agents and handover successors on macOS/Linux start from the daemon'
 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. If your custom setup
-intentionally supplies values through tmux's global environment, opt in with
+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.
@@ -475,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.
 
@@ -577,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
@@ -790,6 +809,24 @@ seats by itself: once a kernel exists, startup skips the built-in kernel boot an
 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
 missing or ambiguous source instead of selecting an arbitrary historical row.
@@ -1138,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.

package/daemon/docs/reference/project-workspace.md

@@ -168,6 +168,12 @@ The read API adds `GET /api/scopes/projects` and optional `project` and
 detail also requires the selected mission directory. Existing reads without a
 project parameter keep their legacy contract.
 
+`GET /api/scopes?counts=1` is the light list: each mission's slices with only
+their `dirName`, `id`, `displayName`, `status`, `stage` and `locks` (and
+`sourcePath` for a selected project), read from each slice's node file alone. It
+leaves out readiness and proof pairing, which are most of the work and bytes of
+the default list. `detail=1` takes precedence when both are given.
+
 ## UI Mapping
 
 - `workspace.root` maps to the Project workspace.

package/daemon/docs/reference/quickstart.md

@@ -17,7 +17,7 @@ npx skills add https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/ri
 npx skills add https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs --skill rigs --agent codex
 ```
 
-For a new install, use the latest release's tag, for example `v0.7.0`. If OpenRig is already installed, use the tag
+For a new install, use the latest release's tag, for example `v0.7.1`. If OpenRig is already installed, use the tag
 that matches `rig --version`, or upgrade first. If the command fails with `npx: command not found`, Node.js isn't
 installed or isn't on your PATH yet (see [What you need](#what-you-need)). Then type `/rigs` in Claude Code, or `$rigs` in Codex, and say what
 you want built.

package/daemon/docs/reference/refocus-channel.md

@@ -37,10 +37,12 @@ launched before this change, a manual run) the hooks do what they always did. Th
 the seat's own `settings.local.json` copy only when that entry is exactly OpenRig's and the script it names is the same
 script; an entry from an older install doesn't match, so both report until the seat's next launch refreshes it.
 OpenRig automatically installs its Codex plugin for seats that select it. On its first installation, the six exact shipped
-hook definitions are trusted before launch, after checking the installed hook files against this daemon's shipped copy.
-Existing plugin disables and hook choices are retained. An existing untrusted installation stays under native review:
-Codex's "continue without trusting" leaves no record, so OpenRig does not assume an absent trust record is permission.
-The file check happens only when trust is granted: a later edit to the cached hook scripts keeps that trust, as with any hook trusted in Codex.
+hook definitions and bundle content are trusted before launch, after checking the entire installed plugin against this daemon's shipped copy.
+On upgrade, OpenRig renews content approval only for a previously approved OpenRig-owned bundle with unchanged approved hook definitions.
+It keeps explicit disables, refusals, unknown config layers and other plugins' state. An installation without a proven prior approval stays under native review.
+Codex's "continue without trusting" leaves no record: a skip of an otherwise eligible OpenRig-owned update may therefore be superseded on retry.
+OpenRig records its approved bundle in `CODEX_HOME/.openrig-core-hook-trust.json` and leaves Codex's immutable `.hook-trust` baseline untouched.
+Codex 0.164 checks bundle contents when hooks run; a later edit requires native approval again. Older Codex versions enforce their own trust rules.
 The Codex
 column above then applies only to a Codex seat whose plugin selection includes openrig-core: every Codex hook command
 exits 0 before running anything unless OpenRig gave that seat `OPENRIG_SEAT_PROJECT_DIR` and an explicit