@openrig/cli 0.6.12 → 0.6.14

package/daemon/context-packs/onboarding-width/public-what-you-can-do.md

@@ -11,7 +11,7 @@ not know exists.** So the point of what follows is not skill. It is recognition:
 lands, something rhymes, and you go check instead of building.
 
 Eighty-eight top-level verbs ship (capability canon refreshed through
-`capability-delta-v0.6.12`). This marker describes the pack's teaching, not publication or live
+`capability-delta-v0.6.14`). This marker describes the pack's teaching, not publication or live
 adoption. Read this once for shape, and let it make you suspicious that a thing already exists.
 Model-divergence proclamations are live product (trust them; pins use canonical
 model IDs).
@@ -32,6 +32,11 @@ one command away. Your memory of the fleet is a claim about the past.
   filters to running and **hides detached, exited and attention states** — which are exactly the
   cells you were scanning for. A seat whose tmux session is confirmed gone reads `detached`
   (activity reason `session_missing`), and `rig ps --nodes` says to restore or relaunch it.
+  `rig ps --nodes` also shows the model each seat was last seen using (`modelObservation`, with its
+  source and time), or unknown; it never shows the configured model in its place. A Claude seat at
+  Claude Code's MCP-server approval menu reads as needing input (`mcp_gate`), a Codex seat at its
+  folder-trust panel reads `trust_gate`, and an OMP seat whose turn ended with a typed transient
+  provider failure reads idle and takes an ordinary retry.
   **`rig ps --resources`** shows this host's load and transcript capture cost.
 - **`rig ps --all-hosts --nodes -A`** — the same across every registered machine. Rollup-only
   unless you ask for nodes.
@@ -74,7 +79,7 @@ one command away. Your memory of the fleet is a claim about the past.
 - **`rig roster list` / `show` / `find`** — who across your rigs and hosts is recommended for a
   kind of work, from JSON rosters in `<workspace.root>/rosters`. Read-only: it dispatches nothing
   and does not claim anyone is available. The built-in starter and factory leads publish their
-  team's roster at first start.
+  team's roster at first start. `show` and `find` include each seat's last observed model.
 - **`rig telemetry events` / `transitions` / `tenures <node-id>`** — past events, queue
   transitions and a seat's occupants, one bounded page at a time with gaps reported. Reach for it
   before querying the database yourself.
@@ -98,7 +103,9 @@ unseen — which makes messages the one delivery channel that never gets skipped
   that seat aren't held behind it; N is a deadline from the start of the wait.
   Over `--host` to an http-registered host, a send that may have reached the remote reads
   `remote-outcome-unknown` ("Delivery UNCONFIRMED"): check the target with `rig capture <session>
-  --host <id>` before any resend. Only a host that was never reached reads as unreachable.
+  --host <id>` before any resend. Only a host that was never reached reads as unreachable. A send
+  whose caller goes away (Ctrl-C, or its own timeout) before input starts is refused with
+  `caller_cancelled` and never types later.
 - **`rig send --raw`** — send exact text or keystrokes without the From/To envelope;
   the interactive-prompt guard still applies. To deliberately drive an interactive prompt,
   **`--dangerously-interact --reason "<why>"`** is the explicit override and implies raw text.
@@ -116,7 +123,9 @@ unseen — which makes messages the one delivery channel that never gets skipped
   every seat in one call. `--lines N` is the last N lines (stderr says how many earlier lines were
   cut); `--history-plus-pane` gives the older N history lines plus the whole pane. A short capture
   doesn't prove a seat is idle: a capture that cut lines says activity is unknown (`activity:
-  "unknown"` in `--json`), so read `rig ps --nodes` for it.
+  "unknown"` in `--json`), so read `rig ps --nodes` for it. For a Claude Code or Codex seat, stderr
+  notes whether the input box's text looks typed or like a faint harness suggestion (`inputBox` in
+  `--json`); it's a heuristic, and `unknown` means unknown.
 - **`rig transcript <seat>`** — what has been *said* in a seat, and **seat-scoped rather than
   session-scoped**: one file spanning every agent generation that has occupied it, so it reaches
   back through handovers. Capped (`transcripts.lines`, default 1000 — raise it for depth), and
@@ -126,7 +135,8 @@ unseen — which makes messages the one delivery channel that never gets skipped
   read something, do not ask it. Look.**
 - **`rig ask`** — search what was said or decided, across *every generation that ever sat in a
   seat*. It reaches back past a handover that erased your predecessor's context, and costs no
-  runtime tokens.
+  runtime tokens. `--wake` asks a Claude or Codex seat itself; any other runtime (Pi, custom, or
+  none recorded) is refused before a wake starts.
 - **`rig chatroom wait`** — block until a peer actually says something, instead of polling
   `capture` in a loop. Also `history`, `watch`, `topic` for a named thread that stays retrievable.
   Its `--timeout` is in seconds and ignores a suffix, so `2m` means 2 seconds. Poll timeouts,
@@ -170,7 +180,10 @@ unseen — which makes messages the one delivery channel that never gets skipped
 - **`rig slack`** — inspect and manage one connector implementation. Use registered-human
   readiness for the delivery decision and `queue create --verify` for its receipt; connector
   setup or verification is not an outbound human message. After a connection gap the daemon
-  catches up on missed channel messages and marks them late; `rig slack status` shows the
+  catches up on missed messages in the channels this machine owns (its default channel, its
+  channel map's, and on a relayed machine each channel the hub has relayed to it) and on replies
+  in tracked threads whose root or close is within seven days; recovered replies are marked late
+  and never answer a decision. `rig slack status` shows the
   connection, the catch-up state, and the count of retained retry records for inbound messages,
   reactions and click answers (kept across restarts, not a distinct-message count). A retained alert whose row closed before its retry isn't
   posted; the row says why. Its `Delivery:` line says whether events are confirmed arriving;
@@ -389,7 +402,8 @@ not have to tear one down to change it, and you rarely have to start from nothin
 - **`rig up <source>`** — make a whole rig exist and run: from a spec you wrote, a shipped starter
   by name, a bundle someone handed you, a GitHub folder link (pinned to one commit), or a stopped
   rig. `rig up` with a pod-aware spec on a stopped team's name replaces that team (the earlier one
-  is archived), so check `rig ps --nodes` first. Launch-created `AGENTS.md` or `CLAUDE` files now show in `git status`.
+  is archived), so check `rig ps --nodes` first. A rig name containing a dot is refused before
+  launch, because tmux would rename its sessions. Launch-created `AGENTS.md` or `CLAUDE` files now show in `git status`.
   `rig up <rig> --existing` puts back the OpenRig guidance blocks `rig down` removed before a
   resumed seat starts. A seat still missing one makes the rig `partially_restored` (its node lists
   `guidanceGaps`) and `rig up` exits 1. A seat that wasn't running at the snapshot, but whose
@@ -426,8 +440,13 @@ not have to tear one down to change it, and you rarely have to start from nothin
   <account>` reports `moved` only when a tool turn has completed in the same conversation since
   the restart and Codex's status names that account. Linux only: on macOS a
   request that reaches the running-process check refuses before stopping the seat.
+  An adopted seat (one OpenRig didn't launch) refuses with `claimed_session`. "A conversation it
+  can prove" means the stored conversation matches the one the running Codex's command line names
+  (or, when it names none, the only one Codex has logged since it started); OpenRig can't tell
+  which conversation Codex is on now. If the conversation was changed inside the running Codex,
+  the restart may refuse or resume the earlier one, so look at the pane (`rig capture <seat>`) first.
 - **`rig add`** / **`rig expand`** — graft one more member, or a whole new pod, onto a rig that is
-  already running. `rig add` takes the rig's name or ID; a name two active rigs share is refused
+  already running. `rig add`, `rig grow` and `rig remove` take the rig's name or ID; a name two active rigs share is refused
   with `rig_ambiguous` and the candidates. `rig grow --new-pod` and `rig expand` are one ingress; choose by input shape.
 - **`rig remove`** / **`rig shrink`** — take a seat, or an entire pod, out of a running topology.
   If it holds active work, pass `--fallback <live-seat>` to reroute before mutation; without a
@@ -442,7 +461,12 @@ not have to tear one down to change it, and you rarely have to start from nothin
   to a node. **`rig adopt`** does the whole thing at once: create the structure and bind the
   running sessions into it.
 - **`rig reconcile-session`** — you resumed a seat by hand and the daemon still shows it down; make
-  the system see the live process **without launching anything**.
+  the system see the live process **without launching anything**. A running seat that refuses every
+  send because its tmux pane was never recorded (one launched by an older OpenRig) takes
+  `rig reconcile-session <seat> --repair-missing-pane --no-launch`: it fills only the missing pane,
+  keeps the session and resume token, never adopts, and refuses while typing protection is on.
+  Plain reconcile adopts the seat into a new session without its resume token; use the repair even
+  where a protected seat's compaction refusal still suggests plain reconcile.
 - **`rig unclaim` / `rig release`** — stop managing one adopted session, or all of them,
   **without killing the process or the agent inside it**. Handing something back to its human is a
   first-class move, not an abandonment.
@@ -469,6 +493,7 @@ version, from checking the environment to a useful report to the OpenRig team.
   Stop distinguishes process/listener exit from a clean asynchronous drain: inspect the matching
   `daemon-shutdown.json` and log when completion is incomplete or unverified. No target is a
   distinct no-op, and a timeout never proves down. Use command help for exact limits and recovery.
+  `/healthz` reports the daemon's effective UID as `euid`, beside `pid`.
 - **`rig doctor`** — is the *installation* wired up correctly, or are you chasing a bug that is
   really a broken install. It checks Claude and Codex installs, and a login or configured provider
   credential, the way setup does; it fails for a harness the person doesn't use, which they can
@@ -543,6 +568,16 @@ version, from checking the environment to a useful report to the OpenRig team.
   Effective-model detection follows the identity-verified current occupant, not a retained
   predecessor; a `<synthetic>` transcript record is skipped, so a PENDING model check is not a
   divergence.
+- **`rig seat set-cwd <seat> --cwd <absolute-path> --reason <text>`** — save an existing seat's
+  launch directory, audited, for its next fresh launch or rebuild handover. Its node, address, queue
+  and history stay intact. It creates the folder (on the daemon's host) and writes nothing else there: launch writes the
+  startup files, as today. Its preflight policy refuses, naming the paths, when the new directory
+  holds an edited, unrecorded-and-different or doubly sourced copy that launch would place. The
+  running process keeps its directory: adopt the new one with `rig seat launch <seat> --fresh
+  --stop --reason <text>` or a rebuild handover, promptly (background work, such as a Claude seat's
+  managed compaction, can use the saved directory before then; that's guidance, not a guard), and
+  before any `rig down`/`rig up` or fork handover. In-place Codex restart isn't adoption. `rig seat status` shows the
+  saved `launch_cwd`. Old-directory files are left.
 - **`rig seat set-permissions <seat> --mode <mode> --reason <text>`** — select one seat's native
   permission mode for its future managed launches; it relaunches nothing, and `inherit` clears the
   selection. `rig seat status` reports the selection, but a status read does not prove the
@@ -551,7 +586,7 @@ version, from checking the environment to a useful report to the OpenRig team.
   reasoning effort for its next launch, restore, handover or in-place Codex restart without
   touching its spec or its peers; nothing restarts. **`rig seat effort <seat>`** reports what was
   requested, what's saved, what the running process was launched with and what the session
-  recorded (NOT VERIFIED until the seat takes a turn).
+  recorded (NOT VERIFIED until the seat takes a turn). It works for Pi seats too, sent as `--thinking`.
 - **`rig seat set-typing-guard <seat> --mode off|draft-aware|hold --reason <text>`** — choose
   ordinary automatic delivery, immediate retention when input is busy/unreadable, or holding all automatic
   input. `--enabled true|false` remains compatible: true selects hold, false selects off.
@@ -562,7 +597,9 @@ version, from checking the environment to a useful report to the OpenRig team.
 - **`rig compact-plan`** → **`rig compact`** — who is near the context wall, then act on it.
   **Ordering matters: running `compact` without the plan is guessing which seat needed it.**
   Managed compaction waits for the seat's restore map before compacting; `rig compact --state`,
-  `--cancel` and `--skip-map` inspect, stop or skip that wait. The `claude-compaction-restore`
+  `--cancel` and `--skip-map` inspect, stop or skip that wait. If preparation stops at an ordinary
+  approval, a manual `rig compact` keeps waiting for someone to answer it, within its 180-second
+  budget; OpenRig never answers it, and the request times out after 240 seconds. The `claude-compaction-restore`
   skill covers writing and reading the map; `claude-compact-in-place` no longer ships. After a
   managed compaction, refocus waits for the restore request, which names the `refocusing` skill
   (the daemon installs it globally); three failed refocus attempts in a row for one occupant post
@@ -572,6 +609,8 @@ version, from checking the environment to a useful report to the OpenRig team.
   `submitted, unconfirmed` (it reached the seat, not proof compaction ran), `uncertain` (not
   replayed) or `not sent`, so confirm by effect. Claude seats that select `openrig-core` load its
   hooks; a seat can give a slow refocus more time with `OPENRIG_REFOCUS_BUDGET_MS` (4500 to 52000).
+  The refocus work packet stays off by default for Claude Code and Codex;
+  `OPENRIG_REFOCUS_WORK_PACKET=1` turns it on, with each field bounded.
 - **Know what compaction costs before you reach for it.** On some runtimes what comes back has
   enough context left to believe it knows everything and not enough to actually know anything — and
   **the compacted agent is the only one who knows it happened**, while every other seat keeps
@@ -810,7 +849,10 @@ your circumstances is configuration, and the ones that are not, another agent ca
 - **`rig config get` / `reset` / `init-workspace`** — read one value, change a system-wide setting
   and put it back exactly as it was, or additively lay down the canonical project scaffold on a
   box that has none. Instance startup uses the same additive initializer for the surrounding
-  `state`, `context`, `skills`, `topology`, and operational roots.
+  `state`, `context`, `skills`, `topology`, and operational roots. With `transport.local_user_guard`
+  on (off by default; `rig config set transport.local_user_guard true`), a Mac's local `rig` requests
+  stop only when the daemon's reported, `ps`-corroborated user differs from yours; unknown evidence
+  lets the call through. It isn't authentication or isolation.
 - **`rig policy permissions list` / `show` / `current` / `apply`** — what permission policy is
   actually in effect: discovers custom policy specs, validates refs (malformed can never read as
   valid OR absent), shows what would apply. The older `rig policy list|show|current|apply` forms
@@ -848,9 +890,9 @@ your circumstances is configuration, and the ones that are not, another agent ca
   permission policy: an explicit flag wins over it, and it wins over the operator default
   `launch.non_interruptive`. The before-install view shows it as
   `posture[].nonInterruptiveDefault`.
-- **Smaller settings worth knowing:** per-seat `effort`, passed to Claude as `--effort` and to
-  Codex as `model_reasoning_effort` (`rig seat set-effort` overrides it for one seat); and
-  `runtime.readiness_timeout_seconds` for seats that start slowly.
+- **Smaller settings worth knowing:** per-seat `effort`, passed to Claude as `--effort`, to
+  Codex as `model_reasoning_effort` and to Pi as `--thinking` (`rig seat set-effort` overrides it for
+  one seat); and `runtime.readiness_timeout_seconds` for seats that start slowly.
 - **`rig policy cite` / `defaults`** — what posture the operator is in: how autonomous to be, how
   loudly to report, whether to batch permission questions or block on them. **This declares a
   posture; it does not grant or deny permissions** — the harness's own settings are the control
@@ -879,7 +921,12 @@ your circumstances is configuration, and the ones that are not, another agent ca
   windows, listed once per allowance and never added up; `--refresh` (optionally `--provider
   codex|claude`) reads the logins now. A Claude account's current availability reads `unknown`,
   because nothing links a seat's reading to the login it used: read each window as that seat's
-  reading, and don't tell a person an account has room from it. With `provider.subscription_moves`
+  reading, and don't tell a person an account has room from it. Each account row also carries a
+  sign-in fact (`usable`, `needs sign-in` or `unknown`); a signed-in Claude login never reads
+  better than `unknown`. A Codex account's last reading, its reset and its last observed exhaustion
+  survive a daemon restart as history (`retained: "before_restart"`), never a current reading; a
+  window whose reset has passed shows an `expectation`, which is planning, not a reading. Run `rig provider status --refresh`
+  before telling anyone an account has room. With `provider.subscription_moves`
   on (off by default), `rig provider moves` records and lists moves of a Codex home's seats between
   subscriptions.
 - **Codex configuration fragments** — a `codex_config_fragment` must open with a table header and
@@ -893,6 +940,19 @@ your circumstances is configuration, and the ones that are not, another agent ca
   `both` sets which harnesses it installs and checks; one not chosen reads `skipped`, never failed.
 - **`rig usage series`** — what a seat's token curve has looked like over time: climbing steadily,
   reset, or stopped reporting entirely. The last one is a signal, not a gap.
+- **`rig usage top`** — which of this machine's seats used the most tokens over a window (`--window
+  90m`, `1h`, `2d`; `--top <n>` caps the list). Each ranked seat shows its token delta and samples;
+  a seat that has reported usage before but has no usable samples in the window is listed as
+  unknown with its reason, never as zero.
+  To compare machines, run it on each machine, or against each machine's daemon with
+  `OPENRIG_URL=<that daemon's URL>`, back to back, with the same `--window`, no `--top`, and `--json`.
+  Show the results side by side in tokens. For each machine, give its host, the window and its
+  `sinceIso` (each daemon counts from its own clock), how many seats were ranked and over what span,
+  the unknown seats and their reasons, and each seat's runtime, declared `model` and last observed
+  model (`modelObservation`: model, source, time) from `rig ps --nodes -A --json` on that machine.
+  A seat that has never reported usage is in neither list: name each seat that `rig ps --nodes -A
+  --json` shows and `rig usage top` doesn't as not covered. Don't add machines into one total unless
+  they cover the same seats over the same span; where coverage differs, say so instead.
 - **`rig usage cost [--seat <session>]`** — what each seat's harness reports it costs, beside its
   tokens: Claude's own client-side estimate (not an invoice) and Codex's tokens with a note that it
   reports no cost. A missing figure reads missing, never $0, and no setting gates it. With

package/daemon/context-packs/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/context-packs/reference/manifest.yaml

@@ -1,7 +1,7 @@
 # Reference guides the help pack links to, loaded one file or section at a time by address
 # (rig context get reference/<file>#<section>). Each file is a symlink to docs/reference/.
 name: reference
-version: "0.6.12"
+version: "0.6.14"
 taxonomy: world
 purpose: "Version-matched reference guides the help guide links to. Load a single file or section by address; don't load the whole pack."
 files:

package/daemon/context-packs/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