@openrig/cli 0.6.12 → 0.6.13

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

@@ -15,12 +15,20 @@ operator in the OpenRig view.
 
 ## 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
+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 +131,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.13/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.13/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 +258,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 +564,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.

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/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.

package/daemon/docs/reference/slack-app-setup.md

@@ -301,46 +301,76 @@ decisions, and posts its own replies.
   it with `host.name`).
 - **The hub's own channels** are handled on the hub, as before. A channel can be relayed to one
   machine only, and never the hub's own default channel.
+- **Missed messages:** each machine recovers the channels it owns: the hub its own channels, and
+  every other machine its default channel and its channel map's (the hub never recovers a channel
+  it relays). See [Reconnect recovery and status](#reconnect-recovery-and-status).
 - **Not covered yet:** `rig slack verify` on the hub doesn't check the app's membership in relayed
-  channels, and missed-message recovery covers the hub's default channel only.
+  channels.
 
 ## Reconnect recovery and status
 
 The daemon scans available top-level messages and replies broadcast with **Also send to
-channel** in the configured default channel after a Socket Mode connection and on its
-existing five-minute retry cadence. Broadcast replies keep their thread's routing. Recovered
-tasks say **Recovered after a gap** and show the original Slack posting time.
+channel** in the channels this machine owns: its default channel and its channel map's, except a
+channel it relays to another machine. It also scans replies in the threads it tracks in those
+channels whose root was posted, or which closed, within the last seven days. A root's age is its
+Slack posting time, so rebuilding the thread map doesn't make an old thread eligible again. An old
+thread that closed within seven days is scanned from its root, so this isn't a seven-day history
+limit. Missed replies in older open threads aren't caught up; live delivery is unchanged.
+
+The hub scans after a Socket Mode connection and on its existing five-minute retry cadence. A
+machine the hub relays to scans every five minutes, and recovers only the channels it owns that the
+hub has relayed it an event for. Each such channel's coverage starts when its first relayed event
+arrives, and is kept across restarts, so a restart needs no new event. A channel the machine no
+longer owns isn't scanned, and a machine nothing is relayed to never reads its channels' history.
+
+Broadcast replies keep their thread's routing. Recovered tasks say **Recovered after a gap** and
+show the original Slack posting time. A recovered thread reply lands as a reply in its thread,
+marked late, and never answers a decision, even one still open: the seat reads it and decides. A
+recovered broadcast reply does the same in every channel except the default channel of the machine
+that holds the Socket Mode connection, where it behaves as before; a relayed machine's default
+channel counts as newly covered. A dead-lettered recovered reply keeps that mark when it's retried.
 They use the same sender admission, routing, attachment handling, fixed identity
 and dead-letter path as live messages. A durable dead letter is custody of a
 failed delivery, not successful delivery.
 
 Recovery keeps a per-channel checkpoint across reconnects, restarts and channel
-switches. On upgrade it initializes once from the newest retained accepted
-channel landing; without such evidence it starts at feature adoption. **Older
-history is unknown.** New live messages never move the recovery checkpoint. A
+switches. For the hub's default channel it initializes once from the newest retained accepted
+channel landing; without such evidence it starts at feature adoption. Every other channel starts
+when recovery first adopts it. **Older history is unknown.** A tracked thread's checkpoint starts
+at its root, so its first scan reads the whole thread; replies that already landed are recognized
+and not delivered twice. New live messages never move the recovery checkpoint. A
 partial scan resumes its saved interval; only an exhausted interval advances the
-covered boundary. Each new interval ends five seconds before the local clock to
+covered boundary. The checkpoint moves past a message once it landed, was a duplicate, was
+dead-lettered, was refused because its sender isn't admitted, or was skipped as a kind inbound
+doesn't take (a bot's post, an edit or join, an empty message). Each new interval ends five seconds before the local clock to
 allow recent messages to become visible; larger clock skew or visibility lag is
 not covered by that margin. A corrupt or unreadable checkpoint leaves recovery unavailable
 and preserves the existing file; live inbound continues.
 
-Each pass admits at most four pages, 100 entries and 15 seconds of work, with a
-five-second history-request ceiling. Work already started on a message, such as
+Each pass admits at most four history calls, 100 entries and 15 seconds of work, with a
+five-second request ceiling. Channels and threads take turns within that one budget, so with many
+tracked threads each thread is scanned every few passes; `rig slack status` shows how far behind
+the oldest waiting thread is. Work already started on a message, such as
 an attachment transfer, is not cancelled by these limits or by a stop, and a new
-pass waits for it to finish. Rate limits retain Slack's Retry-After across restart.
+pass waits for it to finish. Rate limits retain Slack's Retry-After across restart, and hold back
+only the method Slack limited (channel history or thread replies).
 Transport and server failures use a five-second backoff unless Slack supplies Retry-After.
 When Slack reports a plan history limit, recovery still lands the available page
 and advances normally, retaining an older-history limitation in status across restarts.
 Missing bot credentials, history scope, membership, retention limits and API
-failures appear as recovery limitations. No additional scope is required to keep
-live delivery working. Non-broadcast thread replies and other channels remain outside
-this recovery scope; global chronological order is not promised. This change does not
-replay intervals already checkpointed before broadcast-reply recovery was added.
+failures appear as recovery limitations. A tracked thread Slack can't find stays incomplete in
+status, with no further call, until its thread mapping changes or the daemon restarts or rewires
+the connector; that isn't proof the thread was deleted. No additional scope is required to keep
+live delivery working. Threads nobody tracks, older open threads, threads closed more than seven
+days ago and other channels remain outside this recovery scope; global chronological order is
+not promised. This change does not replay intervals already checkpointed before broadcast-reply
+recovery was added.
 
 `rig slack status` retains local configuration checks and adds a bounded daemon
-snapshot: socket state/generation, last event, recovery interval/state/reason,
+snapshot: socket state/generation, last event, recovery interval/state/reason for each
+channel, a thread line (tracked, scanned, waiting and why any are backing off or incomplete),
 retry time and accepted/dead-lettered recovery counts since the connector last
-started (they reset when it is enabled or disabled, and when the daemon restarts).
+started, including threads that have since left the window (they reset when it is enabled or disabled, and when the daemon restarts).
 It also reports the durable dead-letter backlog: the retained records for inbound messages,
 reactions and click answers that await retry, counted from both dead-letter files so the number
 survives a restart, and shown as unknown with a reason (and no count) when a file cannot be read.