@openrig/cli 0.6.12 → 0.6.14

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

@@ -1,26 +1,80 @@
-# Getting started: meet the kernel, then make one useful change
-
-Install OpenRig, use a working provider login, and meet the kernel operator with
-the advisor and TUI beside it. No starter team is needed to reach that view.
-Tell the operator what you want to do, then choose a project team for a bounded
-change you can exercise. Reuse the accounts and terminal tools you already have.
-
-After installation and sign-in, your agent opens the **OpenRig TUI and operator** for you. The path is `rig daemon start` (if stopped),
-then `rig terminal open saved:kernel --window`. The second command opens the
-desktop window itself. An agent can run it from its shell on the daemon's
-desktop; it does not need to type into your current terminal. See
-[Open the kernel conversations](#open-the-kernel-conversations).
-`rig tui` is the team dashboard; installation ends when you are talking to the
-operator in the OpenRig view.
+# OpenRig setup reference
+
+This is the full reference for installing and running OpenRig, written for the agent doing the setup and for anyone
+who wants the detail. The short version for people is [Getting started](quickstart.md).
+
+## For the agent doing the setup
+
+The `rigs` skill is the procedure: follow it in order. This page is what it looks things up in.
+
+- **Done** means the person is talking to the operator in a visible OpenRig view. A healthy daemon, a started kernel
+  or an opened window isn't done on its own. If they'd rather talk later, the handoff is still pending: say so, and
+  leave them the exact command.
+- **Read readiness; don't assume it:**
+  - **The kernel:** the `Kernel:` line in `rig status`, and `rig ps --nodes --rig kernel`.
+  - **A team:** `rig ps --nodes --rig <team>`.
+  - A missing or unknown signal isn't ready.
+  - `rig up` exiting 1 with `Status: partial` and `Startup attention` means a seat is waiting at a prompt. Answer it,
+    or ask the person to, then run the `rig seat continue <seat>` it names.
+- **Prerequisites:** check the person's existing toolchain first (mise, nvm, Homebrew or the nodejs.org installer)
+  and the PATH. Use what's there. Don't change a shared Homebrew's ownership, and don't make a local workaround the
+  standard route. If Node.js is installed after your session started, check that new shells and the session's hooks
+  can find it. In one published-0.6.11 Mac run, OpenRig's Claude hooks reported `node: command not found` until the
+  PATH was fixed.
+- **Ask once, then reuse the answer:** the provider (Claude Code, Codex or both), Herdr, Ghostty on macOS,
+  remembered command allowances, and the team.
+- **Before changing their machine:** say what applies to their route, then wait for a yes. See
+  [what OpenRig changes on your machine](../../README.md#what-openrig-changes-on-your-machine).
+- **When something stops:**
+  - [Incomplete setup and restart](#incomplete-setup-and-restart) maps what you see to the next action.
+  - [What can interrupt installation and the OpenRig view](#what-can-interrupt-installation-and-the-openrig-view)
+    covers the view.
+  - [Headless or SSH handoff](#headless-or-ssh-handoff) covers no-display cases.
+  - A timed-out command may still have taken effect. Read `rig ps` or `rig seat status <seat>` before you run it
+    again.
+- **Don't:**
+  - relaunch a team to reopen its view;
+  - start another seat to clear a prompt;
+  - build the person's project yourself. Give the goal to the operator.
 
 ## Before you start
 
-You need Node.js 22 or 24 and tmux, on macOS or Linux. On Linux, the
-distribution's own Node.js can be older (Ubuntu 24.04's is 18); install a
-supported version with [nvm](https://github.com/nvm-sh/nvm) (`nvm install 22`)
-or NodeSource. On a Mac with Apple
-silicon, use Node.js 22 (see the [compatibility
-history](../releases/v0.5.15.md#known-compatibility-limitation)). Native
+> **What OpenRig changes on your machine**
+> - **Install:** `@openrig/cli` goes in globally with npm.
+> - **Setup:** `rig setup` adds an OpenRig block to `~/.tmux.conf`. It can install tmux (with Homebrew on macOS), and
+>   Herdr unless you pass `--no-herdr`. Plain `rig setup`, which is what the one-command install runs, checks both
+>   Claude Code and Codex and may install a missing one; `rig setup --providers claude` (or `codex`) limits it to
+>   yours.
+> - **Starting OpenRig, for the coding agent you use** (paths are the usual defaults):
+>   - Codex: hooks and trust in `~/.codex/config.toml`.
+>   - 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`.
+> - **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.
+>   On Codex that's full access with no approval prompts (`-s danger-full-access -a never`). On Claude Code, its file
+>   tools, web fetches and operational commands, including reads under your home folder, run without asking. A
+>   permission policy, per-agent choice or Codex profile changes that. What your team can do depends on the team you
+>   choose and your settings; `workshop`, for example, ships with broad access.
+> - **Backups:** OpenRig doesn't guarantee it can preserve or roll back these files, so back them up first.
+>
+> [Everything OpenRig writes, and why →](https://github.com/mvschwarz/openrig#what-openrig-changes-on-your-machine)
+
+You need Node.js 22 or 24 and tmux, on macOS or Linux, and one working Claude
+Code or Codex account: one is enough, since the kernel operator adapts the
+shipped `starter` team to whichever you have. On Linux, the distribution's own
+Node.js can be older (Ubuntu 24.04's is 18); install a supported version with
+[nvm](https://github.com/nvm-sh/nvm) (`nvm install 22`) or NodeSource. On a Mac
+with Apple silicon, use Node.js 22 (see the [compatibility
+history](../releases/v0.5.15.md#known-compatibility-limitation)). On a Mac where
+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
@@ -123,19 +177,20 @@ 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.12/scripts/install.sh | sh -s -- --dry-run
+curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.14/scripts/install.sh | sh -s -- --dry-run
 ```
 
 The same command without `--dry-run`,
-`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.12/scripts/install.sh | sh`, installs the
+`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.14/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
-`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:
+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:
 
 ### Choose your providers
 
@@ -249,6 +304,17 @@ same view and plan, or creates one if none matches, preserving its config and ex
 caller's Herdr endpoint must match the daemon's endpoint; a mismatch is reported
 without opening a window or putting the view in another session.
 
+The shared TUI (`rig tui --shared`) runs in the daemon's tmux server, so its own environment never
+carries the Herdr you are looking at; the markers are on the tmux client attached to it. When you
+open a terminal view from it on Linux, the TUI passes the markers of the client that was active last
+(normally the one that pressed the key) to the command, which then opens the view in that Herdr. The
+chosen client may belong to a different viewer: tmux only counts keys a client types, so a key sent
+by an agent (`send-keys`) or by a control-mode client doesn't count as any client's activity, and the
+view opens in the Herdr of the interactive client that typed last, however long ago. With no client
+attached, more than one client active in the same second, or a client that isn't in Herdr or can't be
+read, nothing is passed and the result is what it was before. Other platforms, and every other way of
+running `rig terminal open`, keep the previous result too.
+
 On Linux, a local graphical display and a supported hosting terminal are required
 (Ghostty, GNOME Terminal, Konsole or xterm). Linux reports a window request; verify
 what actually appeared. SSH, headless, CI and unsupported Linux hosts get a
@@ -544,6 +610,16 @@ views. If the provider cannot open, each labelled fallback command joins a diffe
 seat. Keep all returned commands
 complete when sharing them; a created workspace alone does not confirm visibility.
 
+### Built by the community
+
+Tools built around OpenRig are maintained by their authors. We have not tested them;
+this list does not promise support or compatibility with your OpenRig version.
+
+- **[Rig HQ](https://github.com/dmelo/rig-hq)**, by [dmelo](https://github.com/dmelo):
+  a read-only pixel-office viewer for rigs, seats, attention and queue handoffs, as
+  described in the [author's introduction](https://github.com/mvschwarz/openrig/discussions/879).
+  The author reports testing it with OpenRig 0.6.5. See its repository for setup and support.
+
 ## Continue real project work
 
 Return to the same owner with the next outcome, citing the earlier result.
@@ -965,6 +1041,37 @@ same-seat stop/resume path after checking its retained policy; do not erase the
 rig or start a duplicate to reset permissions. A resume can reapply the stored
 launch mode, so verify the native mode again before continuing work.
 
+## Optional Mac local-user check
+
+On a Mac shared by multiple OS accounts, `transport.local_user_guard` can reduce
+accidental CLI routing to another account's local daemon. It is **off by default**.
+Enable it with `rig config set transport.local_user_guard true`, or set
+`OPENRIG_TRANSPORT_LOCAL_USER_GUARD=true` in the CLI's environment. Set it to
+`false` to turn it off; no daemon restart is needed for the CLI check.
+
+When enabled, automatic local CLI data requests compare the daemon's reported
+`/healthz` PID and effective UID (`euid`) with two `ps` UID/start observations and
+a second health response, with at most one second of observation per check.
+Only stable agreement on a foreign effective UID stops the request. This does
+not require visibility into another user's socket descriptors. It does not
+stop the daemon, choose another port or retry. Diagnostic health/status checks
+remain available. Older daemons without `euid` remain unknown and are permitted.
+`sudo rig …` uses the caller's **effective** UID, so an enabled check against a
+user-owned daemon refuses when its reported/observed UID differs from root.
+
+Explicit `OPENRIG_URL`/`RIGGED_URL` targets and registered remote hosts retain
+their selected routing, including tunnels. An internally resolved local URL is
+still checked. Default UI and TUI openings are checked before launch; this does
+not police later browser or TUI connections.
+
+Missing, disagreeing, restricted or timed-out evidence **continues today's
+behavior**. This is a partial accidental-routing check, not authenticated user
+isolation: it trusts the daemon's PID/UID report and corroborates that process;
+it does not establish the socket's owner. Identity can change between observation
+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.
+
 ## Custom settings and precedence
 
 - **OpenRig:** member `permission_policy` overrides rig `permission_policy`.

package/daemon/docs/reference/publishing-a-rig-bundle.md

@@ -116,8 +116,11 @@ an issue there with the same three things. A maintainer then writes the full ent
 defined in the [bundle formats reference](bundle-formats.md), with the parts only a review can produce, such as the
 pinned commit and each configuration's package digest.
 
-Rig names are unique on the site. If `registry/<your-team>.yaml` already exists, openrig-registry's registry check says the name is taken;
-choose a distinct one, for example `<taken-name>-<your-name>`.
+Rig names are unique on the site. If `registry/<your-team>.yaml` already exists, openrig-registry's registry check
+still replies that your submission was received, and says the name is taken; choose a distinct one, for example
+`<taken-name>-<your-name>`. A team whose `rig.yaml` name matches a listed team's, such as an unchanged copy of one,
+passes the checks with a notice for the maintainer about the shared name. Whether it's listed is the maintainer's
+review decision, not the checks'.
 
 What happens next:
 - a maintainer pins your link to an exact commit, runs the same check, and reads everything your bundle gives to an

package/daemon/docs/reference/quickstart.md

@@ -0,0 +1,187 @@
+# Getting started
+
+OpenRig runs a team of coding agents (Claude Code, Codex and others) on your project, each in its own terminal. You
+talk to one agent, and it hands work to the others. The team keeps its tasks and messages between sessions.
+
+Most people let their coding agent set it up. This page explains what happens either way, so nothing is a black
+box, and shows how to do each step by hand if you'd rather.
+
+## How the pieces fit
+
+- **`rig`** is the command you and your agents use. It comes from the npm package `@openrig/cli`.
+- **The daemon** is a small background service on your machine. It keeps tasks, messages and state in a local
+  database. `rig daemon start` starts it.
+- **tmux** runs each agent in its own terminal session. Agents keep running when you close a window, and one agent
+  can type into another's terminal.
+- **The kernel** is OpenRig's own small team, which starts with the daemon. You talk to its **operator**, which
+  starts and runs teams for you. Its **advisor** helps you think through what you want.
+- **Your team** (a *rig*) is the set of agents that work on your project, such as `starter`.
+- **The OpenRig view** is a terminal window with the operator and, beside it or on another page, a dashboard of your
+  agents.
+
+## What you need
+
+- macOS or Linux. On Windows, use WSL2 ([one person's working setup](getting-started.md#wsl2-a-reported-working-setup)).
+- Node.js 22 or 24 (on Apple silicon, Node.js 22) and tmux.
+- Claude Code or Codex, signed in. One is enough to start.
+
+If `node --version` does not show a supported version, first check your existing Node installation and PATH.
+Ask your coding agent to help use the toolchain already on your machine. On a Mac, a shared Homebrew installation
+may belong to another user; do not change its ownership to complete this setup. After correcting PATH or installing
+Node, open a new terminal and check `node --version` and `npx --version` before continuing.
+
+## The quick way: let your coding agent do it
+
+In your project folder, add OpenRig's `rigs` skill to the agent you use:
+
+```sh
+# Claude Code
+npx skills add https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs --skill rigs --agent claude-code
+# Codex
+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.6.14`. 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 above). Then type `/rigs` in Claude Code, or `$rigs` in Codex, and say what
+you want built.
+
+The skill has your agent work through the steps below in order. It says what it will run and change before it runs
+it, and it asks before installing anything on your system. It finishes when you're talking to the operator.
+
+## What happens, step by step
+
+Each step shows the command, so you can run it yourself.
+
+### 1. Install the `rig` command
+
+```sh
+npm install -g @openrig/cli
+rig --version
+```
+
+This installs the CLI globally under your npm prefix. `rig --version` prints the version and a commit, such as
+`0.6.12 (9e5382dd)`. With npm 11 or later, an `npm warn install-scripts` line is expected: it means only the
+Node.js and SQLite check was skipped.
+
+### 2. Set up the tools around it
+
+```sh
+rig setup --providers claude   # or codex, or both
+```
+
+Add `--dry-run` first to see the plan without changing anything. Setup does four things:
+- it checks Node.js, tmux and your sign-in;
+- it installs a missing tmux (with Homebrew on macOS, if you have it) or the coding agent you chose;
+- it installs Herdr, a terminal workspace app the OpenRig view can use, unless you add `--no-herdr`;
+- it adds an OpenRig block to `~/.tmux.conf` (mouse support and longer scrollback).
+
+It doesn't start anything. It ends with a summary of what's done and what still needs you. A missing sign-in shows
+there: run `claude auth login` or `codex login`, then carry on.
+
+### 3. Start OpenRig
+
+```sh
+rig daemon start
+rig status
+rig ps --nodes --rig kernel
+```
+
+The daemon starts and boots the kernel with the coding agents you're signed in to, or both if you're signed in to both.
+
+**What starting OpenRig changes, for the coding agents you use** (paths are the usual defaults):
+- **For Codex:** hooks and trust in `~/.codex/config.toml`, when OpenRig or a Codex agent starts.
+- **For 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.
+- **For both:** small discovery skills in `~/.claude/skills` and `~/.agents/skills`.
+- **Kernel access:** by default the kernel gets broader permissions than a project team gets by default. On Codex
+  that's full access with no approval prompts. On Claude Code, its file tools, web fetches and operational commands,
+  including reads under your home folder, run without asking. A permission policy, per-agent choice or Codex profile
+  changes that.
+
+OpenRig doesn't guarantee it can preserve or roll back these files, so back them up first. [Everything OpenRig writes, and why](../../README.md#what-openrig-changes-on-your-machine).
+
+Started isn't the same as ready. `rig status` shows a `Kernel:` line, and `rig ps --nodes --rig kernel` shows each
+kernel agent's state. They can take a moment after the daemon is up.
+
+### 4. Open the OpenRig view
+
+```sh
+rig terminal open saved:kernel --window
+```
+
+**What you'll see:**
+- **Where it opens:** a new terminal window or tab. If your agent is already running inside Herdr, it opens a new
+  Herdr space instead. It uses Herdr when installed, plain tmux otherwise.
+- **Layout:** in a narrow window, or when the width can't be measured, the operator fills the first page. From 120
+  columns, the dashboard and the operator share it. The advisor has its own tab.
+- **On a Mac:** you may be asked to let your terminal app be controlled. Allowing it is fine.
+- **Over SSH or with no display:** the window can't open. The command says why and, where it can, prints a command
+  to run in a new terminal. Otherwise your agent works out the exact command to join the operator.
+
+You're installed when you're talking to the operator.
+
+### 5. Start your first team
+
+Tell the operator what you want built, and in which folder. It recommends one of three teams:
+- `starter`: a builder and a reviewer, for one bounded change;
+- `workshop`: a lead, a builder, QA and a reviewer, for ongoing work in one repository;
+- `factory`: seven agents, for sustained product work.
+
+Before it starts one, it tells you what starting a team in your folder changes: managed guidance in `AGENTS.md` or
+`CLAUDE.md`, plus the team's skills. Then it waits for your yes. As shipped, `starter` uses both Claude Code and
+Codex. With only one of them, ask the operator to adapt it.
+
+By hand, from your repository:
+
+```sh
+rig up starter --cwd . --plan    # check what it would start
+rig up starter --cwd .
+rig ps --nodes --rig starter
+```
+
+If an agent stops at a sign-in, trust or permission prompt, `rig up` reports `Status: partial` and names the prompt.
+Answer it in that agent's terminal, then run the `rig seat continue <seat>` command it prints. The team is ready
+for work once its agents show as ready in `rig ps --nodes --rig starter`.
+
+### 6. Give the team work, and stop it
+
+```sh
+rig send dev-build@starter 'Fix <one useful thing>. Ask dev-review to check it, and record the result and how I can try it.'
+rig queue list --destination dev-build@starter
+```
+
+The builder records the work as a task, so you can follow it with `rig queue`. When you're done, `rig down starter`
+stops that team. `rig daemon stop` stops the background service and leaves agent sessions running.
+
+## The one-command install
+
+Instead of steps 1 and 2:
+
+```sh
+curl -fsSL https://openrig.dev/install.sh | sh -s -- --dry-run   # shows the plan and changes nothing
+curl -fsSL https://openrig.dev/install.sh | sh
+```
+
+It checks Node.js and npm, installs the latest `@openrig/cli`, then runs `rig setup`. It doesn't know which coding agent
+you use, so it checks and may install both. For just one, use steps 1 and 2. If a sign-in is missing, setup reports
+it as the step to finish: sign in, then continue at step 3.
+
+## What these words mean
+
+- **Rig:** a team of agents, started with one command. Your first one is usually `starter`.
+- **Seat:** one agent's role and address in a team, such as `dev-build@starter`.
+- **Harness:** the software around the model that an agent runs in: Claude Code, Codex or Pi.
+- **Kernel:** OpenRig's own small team, which starts with OpenRig. It isn't your project's team.
+- **Operator:** the kernel's agent you talk to first. It recommends a team for your goal and starts it when you say
+  yes.
+- **Advisor:** the kernel's agent for thinking through what you want before a team starts. It has its own tab.
+- **OpenRig view:** the terminal view that opens on the operator. In a wide window the dashboard sits beside it;
+  otherwise, or when the width can't be measured, the dashboard is on its own page. `saved:kernel` in
+  `rig terminal open saved:kernel` is the name of this saved view.
+
+## More
+
+- **Every detail of setup:** troubleshooting, permissions, headless and SSH use, and what can stop the view from
+  opening. See the [setup reference](getting-started.md).
+- **Stuck?** Run `rig context get help`, or read [Help](help.md).

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

@@ -125,10 +125,14 @@ reports broken links as gaps rather than following pointers.
 This automatic hook path is additive to one-shot manual injection through
 `rig send --context`; neither mode substitutes for the other.
 
-## The work packet (switched off by default)
+## The work packet (off by default on every runtime, for now)
 
 Set `OPENRIG_REFOCUS_WORK_PACKET=1` in a seat's harness environment so its
 refocus carries the work it is actually doing as text rather than as pointers.
+`=0` (or `off`, `false`, `no`) turns it off. Unset, each runtime's default
+applies. A runtime's default becomes on only after a native run shows the
+packet reaching the agent and leading to the right next action. No runtime has
+been shown that yet, so today both Claude Code and Codex default to off.
 With the switch on:
 
 - The hook asks `rig queue whoami --work-candidates` for labelled evidence.
@@ -154,6 +158,12 @@ With the switch on:
   `OPENRIG_REFOCUS_NOTES_MAX_AGE_DAYS` (default 14) is named with its age, the
   age's source (`updated:` frontmatter, else mtime) and the threshold: a cue
   for judgment, not a staleness verdict.
+- Each field is bounded on its own, with no total cap. A held or next row's
+  summary and continuation are one line each (about 160 characters), with
+  `rig queue show <id>` named when one was shortened. At most 20 held and 10
+  next rows are shown, with how many there are and the `rig queue list` command
+  for the rest. A matched section's body is cut at about 1,500 characters,
+  pointing to `--depth full`.
 
 `trace-to-root.py --packet --work-candidates <path|->` renders the same packet
 by hand.

package/daemon/docs/reference/rig-spec.md

@@ -361,7 +361,7 @@ pods:
 **Where the declared names reach, by runtime.** Declared values are handed to the seat's terminal as tmux environment, so most seats take them as given:
 
 - Plain Claude Code (no permission mode selected), Codex and terminal seats take a spec `HOME`, `PATH` or `CLAUDE_CONFIG_DIR` as given.
-- The cleared environment (`env -i`) belongs only to a managed Claude launch, which is the one used when a permission mode is selected for the seat (for example `permission_policy: builtin:auto`). It forwards the declared names through the cleared environment, except `PATH`, `HOME` and `CLAUDE_CONFIG_DIR`, which OpenRig sets for that launch itself, and `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN`, for which it sets its own renderer setting. A spec value for any of those four is not forwarded. A seat that selected the shipped `openrig-core` plugin also has `CLAUDE_CODE_PLUGIN_DIRS` (the vendored plugin, added after a list the seat declares itself) among its declared names, so it is forwarded like the others and the plugin's hooks load in a seat with a permission mode as in one without; a seat that didn't select the plugin has no such name added.
+- The cleared environment (`env -i`) belongs only to a managed Claude launch, which is the one used when a permission mode is selected for the seat (for example `permission_policy: builtin:auto`). It forwards the declared names through the cleared environment, except `PATH`, `HOME` and `CLAUDE_CONFIG_DIR`, which OpenRig sets for that launch itself, and `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN`, for which it sets its own renderer setting. A spec value for any of those four is not forwarded. A seat that selected the shipped `openrig-core` plugin also has `CLAUDE_CODE_PLUGIN_DIRS` (the vendored plugin, added after a list the seat declares itself) among its declared names, so it is forwarded like the others and the plugin's hooks load in a seat with a permission mode as in one without; a seat that didn't select the plugin has no such name added. Beyond the declared names, the launch also forwards, by name and only when the seat's terminal has them set, the terminal and locale variables (`TERM`, `COLORTERM`, `TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `LANG` and the `LC_*` names) and the person's editor and display session: `EDITOR`, `VISUAL`, `DISPLAY`, `XAUTHORITY` and `WAYLAND_DISPLAY`. They let Claude's external-editor action open the person's editor and let image paste reach the clipboard, without a value in a spec. `WAYLAND_DISPLAY` is passed as an absolute path: an absolute value is kept, and a relative one is joined to the terminal's `XDG_RUNTIME_DIR`; if the terminal has no `XDG_RUNTIME_DIR` for it, the name is left out. `XDG_RUNTIME_DIR` itself is not forwarded, because D-Bus clients look for the session bus at `$XDG_RUNTIME_DIR/bus` and would reach the keyring and `systemctl --user`. `DBUS_SESSION_BUS_ADDRESS`, `XDG_SESSION_TYPE`, `XDG_CURRENT_DESKTOP` and `SSH_AUTH_SOCK` are not forwarded either. A running seat picks the names up at its next managed Claude launch, not before: `rig seat launch <seat> --fresh --stop --reason "<why>"` for that seat alone (a new conversation), or a restore of the whole rig (`rig down <rig>`, then `rig up <rig> --existing`, which resumes each conversation but restarts every seat in the rig), or a handover. A seat that is up keeps the environment it started with.
 - Codex seats run OpenRig's own Codex executable whatever a spec `PATH` says, and use the daemon's `CODEX_HOME` when the daemon has one.
 - On Pi and OMP seats the values reach the terminal. The agent process gets only what the runner passes on, so a spec or one-off value reaches it only for the names the runner always passes: `PATH`, `HOME`, `USER`, `LOGNAME`, `TERM`, `LANG`, `LC_ALL`, `SHELL` and `TMPDIR`. Pi's agent process receives the runner's `HOME`, so a spec or one-off `HOME` value that reaches the runner is passed to Pi; OMP's agent process gets its seat state directory (`$OPENRIG_HOME/state/omp/<seat>`, see Oh My Pi below) as `HOME`, so a `HOME` value does not reach it. The selected provider's variables are passed separately, as described under each runtime.
 
@@ -436,10 +436,10 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 | `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
 | `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
 | `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `pi`, `omp`, `terminal`, `stub`. `stub` is a deterministic test harness, not an agent: a Node runner in the seat's tmux pane goes through the normal launch, skill projection, startup-file and readiness path, follows `<cwd>/.openrig/stub/script.json` when present, and calls no model. See "What a stub can and cannot prove" in `docs/as-built/test-layers.md`. |
-| `cwd` | string | yes | — | Working directory for the agent. A relative path resolves against the rig root (the directory containing the rig spec). If that path exists as written, it is used. Otherwise a leading `~` or `~/` expands to the home directory (`~user` does not) and `$VAR` / `${VAR}` expand from the daemon host's environment; a relative result still resolves against the rig root. A reference to an unset variable stays as written, so the cwd is that literal path and works only if it exists. Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. A cwd inside the OpenRig installation fails preflight unless `--cwd` is given. |
+| `cwd` | string | yes | — | Working directory for the agent. A relative path resolves against the rig root (the directory containing the rig spec). If that path exists as written, it is used. Otherwise a leading `~` or `~/` expands to the home directory (`~user` does not) and `$VAR` / `${VAR}` expand from the daemon host's environment; a relative result still resolves against the rig root. A reference to an unset variable stays as written, so the cwd is that literal path and works only if it exists. Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. A cwd inside the OpenRig installation fails preflight unless `--cwd` is given. Editing this declaration does not update an existing seat; use [`rig seat set-cwd`](agent-startup-guide.md#change-an-existing-seats-working-directory) to save its future launch directory. |
 | `label` | string | no | — | Human-readable member name. Shown in UI when present. |
 | `model` | string | no | — | Model override. Runtime-specific (e.g., `claude-opus-4-6` for Claude Code). |
-| `effort` | string | no | — | Reasoning effort override, trimmed. A non-string value is ignored with an advisory. |
+| `effort` | string | no | — | Reasoning effort override, trimmed. Claude gets `--effort`, Codex `-c model_reasoning_effort=…`, Pi `--thinking` (see "Pi" below). A non-string value is ignored with an advisory. |
 | `permission_policy` | string | no | — | Member-level permission policy; overrides the rig's. Not valid on terminal members. |
 | `env` | map | no | — | Launch environment for this seat, laid over the rig's `env`. Same rules as the rig-level field. Valid on terminal members too. See "Launch environment" below. |
 | `role` | string | no | — | The seat's role, letters, digits, `_`, `.` and `-`. Not valid on terminal members. |
@@ -455,7 +455,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 `runtime: pi` launches the Pi coding agent (`pi --mode rpc`) through OpenRig's RPC runner.
 
 - **State:** Each seat uses `$OPENRIG_HOME/state/pi/<session>/agent` as its Pi agent directory, with `sessions/` beside it, instead of your default `~/.pi/agent`. The runner sets `PI_CODING_AGENT_DIR` to that directory. `<session>` is the seat's session name, unchanged; for a pod member it is `{podId}-{memberId}@{rigName}`. `$OPENRIG_HOME` defaults to `~/.openrig`. OpenRig creates these directories at launch and does not copy anything from `~/.pi/agent`.
-- **Thinking level:** OpenRig does not pass a node's `effort` to Pi. To set Pi's thinking level, add it to the model as a suffix, for example `model: openrouter/x-ai/grok-4:high`. Pi accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`. Pi first looks for a model whose id is the whole pin, and uses it when there is one, suffix included. Only when there is none does Pi read the suffix as the level and record the model without it. Any other suffix, such as OpenRouter's `:free`, stays part of the model id. The model-divergence check reads the pin literally when the seat's `models.json` defines a model with that exact id; otherwise it accepts the model with or without the suffix. If the seat's `models.json` can't be read, a pin with a suffix stays unchecked, with the usual warning, when the recorded model matches the whole pin or the pin without its suffix. A record that matches neither is reported.
+- **Thinking level:** A Pi seat's effort (the choice saved with `rig seat set-effort`, else the spec's `effort`) is sent to Pi as `--thinking <level>` on every managed launch and resume: fresh launch, successor and restore. Pi accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`; OpenRig passes the value as written and does not translate it, so Codex's `none` is not mapped to `off`. Only a value of the shape `set-effort` accepts (a letter, then up to 31 letters, digits, `-` or `_`) is sent; any other spec value, such as one with a space or one that starts with `--`, is left out, and `rig seat effort` says so. An unfamiliar level gets an advisory (a warning from `set-effort`), never a refusal, and Pi itself ignores an unknown level with a warning and keeps the level it would use without the flag: a model suffix, the resumed session's level, or its default. With no effort resolved, no flag is sent. The effort wins over a model suffix, and the model string is never changed. `rig seat effort` reports the level sent at launch and, on Pi 0.99.0 or later, the `thinkingLevel` Pi records on this launch's latest successful assistant turn (error and aborted turns are skipped); that is the session's level after Pi's own cap, not proof the provider applied it, and it is shown apart from the level sent when they differ. On older Pi it is NOT VERIFIED. Without an effort, you can still set the level as a model suffix, for example `model: openrouter/x-ai/grok-4:high`. Pi first looks for a model whose id is the whole pin, and uses it when there is one, suffix included. Only when there is none does Pi read the suffix as the level and record the model without it. Any other suffix, such as OpenRouter's `:free`, stays part of the model id. The model-divergence check reads the pin literally when the seat's `models.json` defines a model with that exact id; otherwise it accepts the model with or without the suffix. If the seat's `models.json` can't be read, a pin with a suffix stays unchecked, with the usual warning, when the recorded model matches the whole pin or the pin without its suffix. A record that matches neither is reported.
 - **Custom models:** Pi reads `models.json` from its agent directory, so a seat reads `$OPENRIG_HOME/state/pi/<session>/agent/models.json`, not `~/.pi/agent/models.json`. Custom provider and model definitions for a seat go in that file. A seat that uses only providers Pi already includes does not need one. OpenRig does not create or write `models.json`.
 - **Credentials:** The Pi process receives only `PATH`, `HOME`, `USER`, `LOGNAME`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY`, `KIMI_API_KEY` or `MINIMAX_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>`, `kimi-coding/<id>` or `minimax/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
 
@@ -466,7 +466,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 - **State:** Each seat uses `$OPENRIG_HOME/state/omp/<seat>/agent` and `sessions/` instead of your default `~/.omp` profile, and runs with that seat directory as `HOME`. OpenRig does not copy OMP credentials. The runner finds the real `omp` binary before switching `HOME`, so a version-manager shim such as mise on the daemon's `PATH` still works.
 - **Credentials:** Provision each seat separately, or put the provider's key variable in `recovery.provider_auth_env_allowlist` (for example `ANTHROPIC_API_KEY` or `MISTRAL_API_KEY`). The allowlist accepts the key variable of every provider in OpenRig's OMP provider map, from `anthropic` through `litellm`. A seat receives a key only when its `model` is written as `provider/id`, such as `anthropic/claude-sonnet-4-5`. Short names such as `opus` pass no key. A provider whose key is scoped to one endpoint also accepts that endpoint's variable: `anthropic`, `openai` and `litellm` each take their `<PROVIDER>_BASE_URL` — `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, `LITELLM_BASE_URL`. The allowlist admits each variable on its own, so an endpoint named without its key is admitted too, which suits a keyless local proxy. The launch gate admits these endpoint names for OMP seats; the match against the seat's declared `provider/id` happens at the OMP child, which forwards a matching endpoint already in the runner's environment just as it forwards a key. OMP also reads the launch directory's `.env`, so use a trusted working directory.
 - **Approval posture:** The default floor is `--approval-mode always-ask`. Because the runner is headless, OMP approval requests are cancelled and the seat stays in needing-attention after the turn ends, until the next agent run starts. A `full_bypass` permission policy selects `--approval-mode yolo`.
-- **Model errors:** A rejected prompt, a provider or authentication error during a turn, or exhausted automatic retries is printed in the pane and keeps the seat in needing-attention until the next agent run starts.
+- **Model errors:** Errors are printed in the pane. A completed assistant failure with a numeric `errorStatus` of 408, 429, 500, 502, 503, 504, or 529 returns to idle at terminal `agent_end`, allowing an ordinary retry. Until that terminal boundary it stays in needing-attention. Intermediate `agent_end(isTerminal:false)` events do not release attention. A statusless failed retry summary retains that classification only when its attempt matches an announced retry and its final error exactly matches the latest typed transient assistant failure in that attempt. New assistant/turn boundaries invalidate the previous failure; unmatched summaries remain runtime errors. Rejected prompts, auth/configuration failures, exhausted retries without a typed transient status, and untyped errors (including text such as `529 overloaded`) retain attention until the next agent run starts. The runner does not classify diagnostic text. A transient failure does not clear a denied approval or another unresolved runtime failure in the same turn.
 - **Restore:** OMP creates its session file after the first persisted turn. A new seat with no persisted turn has no resume token; restoring it requires `rig up --existing <rig> --fresh <seat>`. After that file exists, OpenRig restores that exact session file. If a full rig restore leaves an OMP seat in `attention_required` or `failed`, `rig seat clear-attention` cannot yet reconcile it to `operator_recovered`, even with `--reason`, because restore reconciliation only verifies Claude Code and Codex processes ([#41](https://github.com/mvschwarz/openrig/issues/41)). Relaunch that seat with `rig up --existing <rig> --fresh <seat>`, or restore it manually.
 
 ### Terminal Nodes

package/daemon/docs/reference/rosters.md

@@ -49,8 +49,22 @@ Authored files contain recommendations, not runtime facts. Extra fields are igno
 any authored runtime, model or activity. At read time the command joins by exact host self-id
 and seat. Unmatched or conflicting observations are `unknown`; a seat not reported running is
 `stale`, with current runtime/model unknown. The configured model is the registry declaration.
-The observed native model remains unknown: these commands do not open native histories or verify
-what model the provider is running. Activity includes its sample time when the daemon supplies it;
+Daemon node listings, `rig ps --nodes --full` and roster members also carry the full
+`modelObservation`: `status`, `model`, `source`, `observedAt`, `generation` and `reason`.
+Compact JSON uses the smaller shape described below. The configured `model` stays separate; roster's
+`live.observedModel` is the observation's model or null. Human output says **last observed**.
+Claude (`claude-assistant-response`) and Pi (`pi-assistant-response`) name response evidence;
+Codex (`codex-turn-context` or `codex-world-state`) names recorded turn configuration, not a
+verified backend response. The timestamp is the native record's time, never file mtime or inventory
+read time. None promises the model that will answer the next turn.
+
+The daemon reuses the current-occupant record selectors and bounded readers used by divergence
+monitoring, sharing a process census. Reporting does not need a configured model or comparator.
+A changed or unverified occupant, a record predating its tenure, missing or invalid record time,
+unreadable or ambiguous records, unsupported runtimes and older daemons report **UNKNOWN** with
+a reason, never the configured value as a fallback. An older record from the same verified occupant
+remains labelled last observed at its original time; this is not a freshness guarantee. No record
+contents, transcript paths or credentials are returned. Activity includes its own sample time;
 activity and running status do not promise that someone is available for new work.
 
 The JSON `observations.readAt` is when the inventory read completed, not a native observation
@@ -59,3 +73,16 @@ valid rosters remain usable; duplicate IDs make `show` report ambiguity instead
 Non-regular file targets, such as FIFOs and directories, are skipped with a warning; links to
 regular files remain readable. Inventory uses `ps --no-cleanup` to preserve even stale local
 daemon state files. Ordinary `rig ps` keeps its existing cleanup behavior unless given that flag.
+
+The daemon reuses model facts only while the selected record's identity, size and
+modification time and the occupant generation remain unchanged. Inventory reads
+share two bulk pane snapshots and one process census; identity is checked after
+the final snapshot. A different observation from duplicate host routes makes
+only that observation UNKNOWN, preserving agreed registry fields.
+
+`rig ps --nodes --json` keeps an observed model compact as
+`modelObservation: ["literal-model-id", "evidence-source", "native-record-time"]`.
+UNKNOWN is `{ "status": "unknown", "reason": "..." }`; older daemons may yield
+`null`. `--full` and `--fields modelObservation` retain the full object, including
+its status and occupant generation. Human output and roster reports use the full
+labelled observation.