@openrig/cli 0.6.11 → 0.6.13

package/daemon/docs/reference/agent-startup-guide.md

@@ -38,6 +38,31 @@ The attention codes that stop startup this way are `trust_gate`,
 `bypass_consent_gate`, `codex_auth_refusal` and `codex_client_incompatible`.
 They are recognized from each harness's English prompt text.
 
+## Continue a Codex fork whose child ID arrived late
+
+For a member with `session_source.mode: fork`, OpenRig waits for Codex's new
+child thread ID before sending its role and other startup prompts. It saves the
+ID and sends the role only for a verified child: the bound pane's foreground
+process forks the requested parent, and its own native record, matched to its
+start time, supplies the ID. This capture uses `runtime.readiness_timeout_seconds`
+(30 seconds by default, configurable from 1 to 600 seconds), as does the later
+readiness check. The two waits have separate budgets. A seat handover with
+`--source fork:<seat>` is different: its fork carries the conversation itself,
+and a missed ID capture leaves the ID pending rather than stopping the handover.
+
+If the ID is still unavailable, the seat reports `attention_required` and keeps
+its startup context pending. Wait for the child to finish starting, resolve any
+native prompt, then run `rig seat continue <seat>`. The continuation verifies
+that the bound pane is running a fork of the requested parent and reads the
+child's own native identity before delivering the saved context. It does not
+launch another fork or resume the parent. The parent ID is never saved as the
+child's resume token.
+
+An unavailable or conflicting identity leaves the context pending. Once prompt
+delivery has been attempted, it cannot be replayed by `continue`, including
+after a daemon restart: inspect `rig seat status <seat>` and the native pane
+before deciding how to recover an uncertain delivery.
+
 ## Two Categories of Startup
 
 Everything an agent receives at boot time falls into one of two categories:
@@ -215,7 +240,9 @@ seconds), for up to 30 seconds by default. Change the window with
 `rig config set runtime.readiness_timeout_seconds <1-600>` (or `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`); it
 applies to the next launch. A recognized prompt (the attention codes above) ends the wait at once as
 `attention_required`. A timeout ends startup as `failed` ("Readiness timeout after Ns — harness did not become
-interactive"), and the post-launch files aren't sent.
+interactive"), and the post-launch files aren't sent. A Codex fork that the rig launches (a member with
+`session_source.mode: fork`, or an agent image's fork) is the exception: its timeout ends as `attention_required`,
+with its startup context kept for `rig seat continue` (see below). A seat handover's fork has its own readiness check.
 
 **Claude submission check.** For each startup message to a Claude seat, OpenRig makes a bounded check that the prompt
 was submitted. When the capture can't tell, it records the submission as unverified and carries on. When it sees the
@@ -229,9 +256,9 @@ one wins, and it needs `idempotent: true`). With `authenticated`, a fresh launch
 and the seat answers it with `rig startup-proof submit --challenge-id <id> --answer <answer>`. `rig ps --nodes --full`
 shows the result in the ORIENTED column: `verified`, `missing`, `rejected` or `n-a`. A missing proof doesn't block startup.
 
-**After a failure.** Delivery, launch and action failures, and readiness timeouts, give `failed`. Every 30 seconds the
-context monitor marks a `failed` or `attention_required` seat `ready` once its pane reads ready, unless fresh context
-is still pending for `rig seat continue`. A seat that timed out can therefore read `ready` without having received its
+**After a failure.** Delivery, launch and action failures, and readiness timeouts other than a Codex fork's, give
+`failed`. Every 30 seconds the context monitor marks a `failed` or `attention_required` seat `ready` once its pane reads
+ready, unless its fresh or Codex fork context is still pending for `rig seat continue`. A seat that timed out can therefore read `ready` without having received its
 post-launch files. If it needs them, first look at what that occupant has done; then
 `rig seat launch <seat> --fresh --reason <text>` starts a blank conversation for the seat. If the occupant is still
 live, the command refuses with `session_live` unless you also pass `--stop`, which replaces that occupant deliberately.
@@ -255,6 +282,68 @@ must inspect `launchable === true` before deciding to execute. Request failures
 Execution always resolves and checks the current state again. An older daemon without the preview
 endpoint refuses the request; the CLI never falls back to executing a launch.
 
+### Change an existing seat's working directory
+
+Editing `cwd` in an already applied RigSpec doesn't update an existing seat's saved launch directory. Use `set-cwd` to
+save a new one for the seat's next launch:
+
+```sh
+rig seat set-cwd planning-lead@project \
+  --cwd /work/project/seats/planning-lead --reason "isolate planning"
+rig seat status planning-lead@project
+```
+
+**The path:** it must be absolute **on the daemon's host**. OpenRig creates a missing directory, resolves symlinks to
+its real path, and refuses a filesystem root.
+
+**What it saves:** the directory and a `node.cwd_changed` audit event (from, to, reason, operator), together, in one
+transaction. The seat's node, canonical address, queue, session history and skill selection stay as they are.
+`rig seat status` shows **Working directory for future launches** (`launch_cwd` in JSON). That's saved configuration,
+not where the running process is.
+
+**What it writes:** it creates the folder if it's missing, and writes nothing else there. The seat's next fresh launch or
+rebuild handover writes its startup files there, as launch does today.
+
+**`set-cwd`'s preflight policy:** before saving, it reads, without writing, the enumerated resource copies (including
+nested plugin files) and startup skills that launch would place in the new directory, at their actual destinations,
+as they are at that moment. It's a point-in-time check, not a global overwrite guarantee or protection against later
+changes; at adoption, launch applies its own policy. (The commit's re-check covers the saved startup configuration,
+not the destination's file contents.)
+- **Refused, with the protected paths named (`cwd_destination_conflict`):** a file there that an operator edited, an
+  unrecorded file with different content, or two sources for one destination. That's stricter than launch, which
+  overwrites an unrecorded differing file with a warning; the refusal is deliberate, while the occupant still runs.
+- **What to do:** use a clean destination, or move or merge those files, then retry.
+- **Not checked:** managed guidance blocks and native configuration merges keep the adapter's policy at launch, and
+  launch-owned files such as `.openrig/context-collector.cjs` are written by launch as always.
+- **A community harness** takes no startup files, so none are checked for it.
+
+**The running occupant keeps its current directory.** Adopt the new one with:
+- `rig seat launch <seat> --fresh --stop --reason <text>`, which starts a blank conversation; or
+- `rig handover <seat> --source rebuild --reason <text>`, which carries durable context.
+
+**Adopt it promptly.** The saved directory doesn't move the running process, but background work can use it before
+adoption. Saved configuration isn't the live process's directory, and these examples aren't the only consumers. For a
+running Claude seat:
+- **Collector provisioning** writes `.openrig/context-collector.cjs` and merges `.claude/settings.local.json` in the
+  saved directory, under its existing preservation rules.
+- **Managed compaction,** manual (`POST /api/compaction/trigger`) or automatic, asks the seat to write its restore map
+  under it. That may be outside the seat's current workspace, so a seat without bypass permissions may meet a write
+  prompt.
+
+Adopting promptly is guidance. It doesn't protect against a poll or a compaction that runs before your next command.
+
+**Before adopting,** don't `rig down`/`rig up` or hand over by fork. Those resume the existing conversation in the
+saved directory, and Claude keeps conversations per project directory, so a resume there may not find it.
+Cross-directory resume hasn't been run natively; this is the order to follow. `rig seat restart --keep-conversation`
+(Codex) isn't adoption: it respawns in the directory it observes from the running process.
+
+**Failures:** a refusal, missing or malformed saved startup context, or an audit-write failure leaves the prior
+directory saved, and changes no seat, custody or startup file (a refusal may leave the new folder created). A concurrent configuration change is reported, not overwritten. A CLI timeout means the outcome is
+unknown; check `rig seat status` before retrying. Choosing the same directory again records no second event.
+
+**The old directory:** files there are left as they are, since other seats may still use them. The source RigSpec
+declaration isn't changed either; update it separately if a future recreation should use the new directory.
+
 ### The `applies_on` Field
 
 Each startup file and action specifies when it applies:
@@ -274,7 +363,9 @@ The AgentSpec and RigSpec allow declaring deterministic environment configuratio
 ### What the Spec Supports
 
 **Hooks** ship inside plugins: declare the plugin under `resources.plugins[]`. AgentSpec validation refuses
-`resources.hooks`.
+`resources.hooks`. OpenRig loads one plugin's hooks into a seat itself: the shipped `openrig-core` plugin, for a Claude seat
+that selects it (see [the refocus channel](refocus-channel.md#the-mechanism)). The folder a declared plugin is projected into
+is not one Claude Code or Codex loads, so a plugin of your own does not get its hooks run by that projection.
 
 **Runtime resources** (in `resources.runtime_resources`):
 ```yaml
@@ -308,7 +399,7 @@ run after the harness is ready: `after_files` (the default) after the post-launc
 | Guidance file projection (`guidance_merge`) | **Supported** | Reliable. Primary delivery mechanism. |
 | Skill projection (`skill_install`) | **Supported** | Reliable. Skills are copied to workspace. |
 | `send_text` delivery after ready | **Supported** | Reliable. Requires harness to be ready. |
-| Hooks | **Through plugins** | Declare a plugin under `resources.plugins[]`; `resources.hooks` is refused. |
+| Hooks | **Through plugins, limited** | `resources.hooks` is refused. OpenRig loads the shipped `openrig-core` plugin's hooks into a Claude seat that selects it (Claude Code v2.1.280 or later); a plugin you declare under `resources.plugins[]` is projected, but its hooks are not loaded. |
 | Runtime resource projection | **Supported for recognized fragments** | `claude_settings_fragment`, `claude_mcp_fragment`, and `codex_config_fragment` are applied to provider config. Unknown types are copied to runtime extension directories. |
 | Permission configuration | **Native settings plus managed launch flags** | OpenRig launches Claude with `acceptEdits` and Codex with `workspace-write` unless an explicit supported selection changes them; a seat with no policy, selection or named Codex profile also gets the per-launch [team default](rig-spec.md#team-launch-defaults), and the `kernel` rig's seats get a wider operational default ([rig spec, "At launch"](rig-spec.md)). Neither is written to a settings file. Use [the first-user permission guide](getting-started.md#opt-in-permissive-operation) for opt-in and custom choices. |
 | MCP installation | **Supported for Claude fragments** | A selected `claude_mcp_fragment` is merged into the project's `.mcp.json`. Claude asks to approve new servers found there; that prompt stops startup as `mcp_gate` until someone answers it and runs `rig seat continue`. Otherwise use `/mcp` or `claude mcp add`, or describe the servers in startup files for the agent to configure. |
@@ -426,6 +517,66 @@ remain shared.
 
 **Terminal seats** (`builtin:terminal`) get no agent or profile layers and no startup proof.
 
+### Codex compaction and sizing
+
+OpenRig's managed compaction is for Claude Code seats only, by design. That covers `rig compact`, the
+`policies.claude_compaction.*` automatic policy, and the watchdog jobs that the `managed-compaction` and
+`apprentice-handover` strategies create. A Codex seat compacts with Codex's own automatic compaction, and OpenRig
+leaves that to Codex.
+
+- `rig compact <session>` refuses a Codex seat: "not a Claude (claude-code) seat".
+- `rig compact-plan` lists a Codex seat as skipped (`codex_not_managed_by_claude_compact_in_place`).
+- The automatic policy never acts on a Codex seat.
+- A Codex member with `compaction_strategy: managed-compaction` or `apprentice-handover` gets no watchdog jobs.
+
+**What Codex compacts at.** Codex describes `model_auto_compact_token_limit` as the "token threshold that triggers
+automatic history compaction (unset uses model defaults)". Its configuration reference does not say what those
+defaults are, and the model catalog's `auto_compact_token_limit` is null for the models we checked in Codex 0.162.1.
+Measure a seat's own compactions before relying on an unset limit.
+
+**What window the model has.** `codex debug models` prints the catalog. Each model carries `context_window`,
+`max_context_window` and `effective_context_window_percent`. In Codex 0.162.1, `gpt-5.6-sol` has a `context_window`
+of 272000 at 95%, which is 258400. That is the `model_context_window` its rollout `token_count` events report.
+A limit only matters when it is below that effective window. Leave `model_context_window` alone: don't raise it toward
+`max_context_window` to avoid compaction. Set the limit instead.
+
+**Setting the limit for seats only.** Put `model_auto_compact_token_limit` in a Codex profile file,
+`$CODEX_HOME/<name>.config.toml` (`~/.codex/<name>.config.toml` when `CODEX_HOME` is unset), and name it on each
+Codex member that should use it:
+
+```toml
+# ~/.codex/seat-compaction.config.toml
+model_auto_compact_token_limit = 150000   # choose your own value
+```
+
+```yaml
+codex_config_profile: seat-compaction
+```
+
+OpenRig passes `-p seat-compaction` on that seat's fresh, fork and resume launches. Codex layers the profile file on
+top of the base user config, so only seats that name the profile see the lower limit. A Codex session started without
+that profile keeps the base `config.toml` in the same Codex home (`$CODEX_HOME/config.toml`, or `~/.codex/config.toml`
+when `CODEX_HOME` is unset). The `150000` is an example, not a recommendation.
+
+With the normal launch mode, `codex_config_profile` replaces OpenRig's explicit workspace-write sandbox flag, so the
+profile must set the sandbox and approvals you want. See
+[permission precedence and limits](getting-started.md#custom-settings-and-precedence), which also gives Codex's order
+of precedence between a profile, project settings and CLI overrides.
+
+**The trade-off.** Every model call carries the whole context so far, so a smaller context makes each call cheaper. The
+cost is that Codex compacts sooner and more often, so more of the conversation is carried as a summary instead of
+verbatim. A higher limit keeps more detail and makes each call larger.
+
+**Related keys.** These also shape compaction. This guide doesn't recommend values for them. See Codex's
+[configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference):
+
+| Key | What Codex says it does |
+|---|---|
+| `model_auto_compact_token_limit_scope` | `total` (the default) counts the full active context; `body_after_prefix` counts only growth after the carried compaction-window prefix. |
+| `compact_prompt` | Inline override for the history compaction prompt. |
+| `experimental_compact_prompt_file` | Loads the compaction prompt override from a file (experimental). |
+| `tool_output_token_limit` | Token budget for storing individual tool or function outputs in history. |
+
 When authoring startup content, note which instructions are runtime-specific. For example, an orchestrator that needs a monitoring loop should include instructions like: "If running Claude Code, use `/loop 3m` to periodically check rig health. If running Codex, check rig health at the start of each task cycle instead."
 
 ---
@@ -477,6 +628,28 @@ Existing user files and legacy role blocks are left intact; this is not a cleanu
 of already-installed shared blocks. General user-authored guidance projection is
 unchanged.
 
+The other shipped agent specs that start a seat with `guidance/role.md` mark that
+file `orientation: role` too, so `rig queue whoami --json` reports their role and
+refocus names it. They never projected a role into shared guidance; their startup
+delivery is unchanged.
+
+**Removing a leftover shared role block by hand.** A kernel installed before 0.6.5
+may still hold one seat's old role in its working directory's `CLAUDE.md` (or the
+rig's configured `managed_blocks` file) or `AGENTS.md`. Upgrading doesn't remove it.
+`rig down` removes OpenRig's managed blocks from that file when no other running
+rig uses it, so it stays until then. To remove it sooner, by hand:
+
+1. Find the exact block: the lines from `<!-- BEGIN OpenRig MANAGED BLOCK: role -->`
+   through `<!-- END OpenRig MANAGED BLOCK: role -->` (in older files, `RIGGED`
+   instead of `OpenRig`). Only the block whose id is exactly `role`; leave
+   `rig-role`, other ids and everything outside the markers alone.
+2. Confirm each seat that shares that directory has its per-seat replacement:
+   `rig queue whoami --json` run in the seat reports `role.state` as `present`.
+   A seat started before it was upgraded still has the old content in its
+   conversation; restart it fresh if you want it to start from the per-seat role.
+3. Keep a copy of the file, remove only those lines, and compare the result with
+   the copy: nothing else in the file should differ.
+
 **Separate project context from role**
 
 Don't put project documentation inside the role guidance. The role is about the agent's function; project context is about what the agent is working on. Use rig-level or pod-level startup files for project context.

package/daemon/docs/reference/claude-status-line.md

@@ -0,0 +1,69 @@
+# Custom Claude status line
+
+OpenRig installs a silent context collector as `statusLine.command` in the seat
+working directory's `.claude/settings.local.json`. Claude's project-local setting
+overrides your user-level status line, so a renderer configured only in
+`~/.claude/settings.json` can disappear in that directory. Other Claude sessions
+using the same directory also read that setting.
+
+Since 0.6.5, OpenRig preserves a custom, nonempty project-local status line command,
+including a wrapper or a command composed with shell operators. It still refreshes
+its own collector script. If your command does not run the collector, context and
+provider usage stop updating, and Claude resume-token capture at adoption or
+handover loses its current session evidence. An earlier sidecar can remain and
+contain an older session ID; without one, context and capture report
+`missing_sidecar`, and provider usage reports `no_statusline_cache_yet` unless an
+earlier cache remains.
+
+## Feed both commands the same input
+
+On macOS, Linux or WSL2, save a wrapper such as this, replacing the three
+placeholder paths and `my-statusline` with your actual commands:
+
+```sh
+#!/bin/sh
+input=$(cat)
+printf '%s' "$input" |
+  node '/seat/cwd/.openrig/context-collector.cjs' \
+    '/instance/home/state/context-usage' \
+    '/instance/home/state/provider-usage' >/dev/null 2>&1
+printf '%s' "$input" | my-statusline
+```
+
+Take the collector path and both directory arguments from the existing generated
+`statusLine.command` in that seat's `.claude/settings.local.json`; the instance
+home is the selected `OPENRIG_HOME`. Keep paths quoted, including paths with
+spaces. Each command needs the same status line JSON on stdin: simply running
+the collector and renderer in sequence against a single stdin lets the first
+consume the input.
+
+In that same settings file, merge this field while preserving your other settings:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "sh '/absolute/path/to/openrig-status-line.sh'"
+  }
+}
+```
+
+Use the renderer command from your user-level configuration in the wrapper. The
+collector stays silent and the renderer supplies the visible status line. This
+POSIX-shell example applies to WSL2's Linux installation; it does not establish
+native Windows support.
+
+## Check after an upgrade or instance change
+
+The collector command's paths and arguments are implementation details. OpenRig
+preserves your wrapper, so it cannot refresh those arguments for you. Recheck
+them after an upgrade, a seat-directory move or an `OPENRIG_HOME` change.
+
+After Claude next updates its status line, inspect context usage in `rig ps` or
+`rig whoami --full` from the seat. Unknown or stale context is a reason to check
+the wrapper; it does not prove the collector is running. For a direct check,
+inspect the current session's JSON under the configured `state/context-usage`
+directory: its timestamp should advance and its `session_id` should match the
+current Claude session. A visible custom status line alone does not verify
+collection or end-to-end adoption/handover recovery. The wrapper above suppresses
+collector errors; remove its stderr redirection temporarily when diagnosing it.

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

@@ -15,18 +15,30 @@ 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
 odd-numbered releases (23, 25 and so on) are not supported; Node 26 and later
 even-numbered releases are untested.
 
+On Linux, if Codex cannot run commands and reports `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`,
+ask the machine owner to follow [OpenAI's sandbox prerequisites](https://developers.openai.com/codex/concepts/sandboxing#prerequisites),
+including its `bwrap` AppArmor profile guidance; changes to AppArmor are the owner's choice.
+
 **Choose permissions before starting the team.** Ordinary OpenRig launches use
 Codex's `-s workspace-write`, with approval policy from your native configuration,
 or Claude Code's `acceptEdits`, which still leaves commands subject to native
@@ -98,26 +110,41 @@ user.
 
 **Agents:** if you're setting OpenRig up for someone, load the `rigs` skill and follow it. It carries the install, the
 OpenRig view and the handoff to the operator as one procedure. From 0.6.7, OpenRig installs it as `rigs` in
-`~/.claude/skills` and `~/.agents/skills` when the daemon starts. Before that, add it with
-`npx skills add mvschwarz/openrig --skill rigs`, or read [`skills/rigs/SKILL.md`](../../skills/rigs/SKILL.md).
+`~/.claude/skills` and `~/.agents/skills` when the daemon starts. To add it manually, use the release tag matching
+your installed `rig --version`: replace `<release-tag>` below with that tag, including its `v` prefix.
+`rig --version` prints the version and a commit, for example `0.6.11 (379f0a0d)`; the tag is `v0.6.11`.
+The skill is in the repository from v0.6.6; on an older install, use the v0.6.6 tag or upgrade first.
+Choose the command for the agent doing the setup:
+
+```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
+```
+
+These are the pinned, per-agent forms used on the [rigs pages](https://openrig.dev/rigs).
+You can also read [`skills/rigs/SKILL.md`](../../skills/rigs/SKILL.md) directly.
 
 **One command, for the full setup.** It needs Node.js 22 or 24 with npm already installed. The preview prints what the
 script will do and changes nothing:
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.8/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.8/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
 
@@ -231,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
@@ -306,6 +344,7 @@ different points in the same journey:
 | Herdr shows its introduction or agent-integration panel | These are Herdr's first-run panels. Follow the displayed controls: Return continues the intro and Esc closes the integration panel. Opening this view does not require installing Herdr's agent integrations or changing your Claude/Codex settings. |
 | A saved layout is cramped in an 80×24 window | The default kernel view gives each role a full-width page. A custom saved `kernel` view still controls its own layout; adjust that saved view if needed. Changing or restarting the team is unnecessary. |
 | The command returned, but visibility is unconfirmed | With authorized desktop tools, inspect the new window and a screenshot of its contents. A window listing alone proves only that a window exists. If the agent has only shell access, report what the command confirmed and ask the person to confirm the visible operator and that the dashboard and advisor tabs or windows are available. Do not report visual success without seeing it. |
+| In a Claude Code seat's terminal, Shift+Enter submits instead of adding a newline | Whether Shift+Enter reaches Claude Code as its own key depends on the terminal and on tmux's extended-key support and settings ([`extended-keys`](https://man.openbsd.org/tmux.1#extended-keys), [`terminal-features`](https://man.openbsd.org/tmux.1#terminal-features__)). To add a newline anyway, press Ctrl+J, or type `\` and then press Enter. Claude Code's [tmux configuration guide](https://code.claude.com/docs/en/terminal-config#configure-tmux) covers the setup. |
 
 After a failure, inspect any newly opened surface before retrying. A tmux failure
 may name a newly created viewing session for inspection. Do not replace a failed
@@ -525,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.
@@ -589,6 +638,7 @@ the lifecycle API without booting a new kernel, then stop the remaining rigs.
 | Tool missing or login fails | Use the specific setup/auth hint; recheck that executable in the launch shell. Do not send work to an unready seat. |
 | "Startup attention" or "Startup details" names a prompt | Answer the login, trust or bypass prompt in that seat's terminal, then run the `rig seat continue <seat>` it shows. |
 | "Readiness timeout after 30s — harness did not become interactive" | The harness took longer than the readiness window. Raise it for the next launch with `rig config set runtime.readiness_timeout_seconds <1-600>`, then relaunch that seat. |
+| "Claude resume did not finish within Ns; Claude may still be starting, so the launch was kept" | A restored Claude seat was not interactive when the wait ended. Its pane and resume token are kept. Look at the pane; once Claude is up, run `rig seat clear-attention <seat>`. The wait is about `runtime.readiness_timeout_seconds` in total for each seat (default 30 s), counting the first 3.2 s, and the time adds up seat by seat in a restore. Raising the setting for slow fresh launches lengthens it. If `rig up` or `rig launch` times out at 120 s, that is not a rollback: check `rig ps` before running it again. |
 | Daemon is healthy, kernel is still starting | Read `rig status` and `rig ps --nodes --rig kernel`; kernel readiness is separate. |
 | Kernel seats fail within a second of the first start, and tmux reports "server exited unexpectedly" | Check that your tmux can capture a pane, then start the failed seats again; see the tmux check below this table. |
 | Shared terminal is absent | Inspect the existing kernel binding and recovery state; use standalone `rig tui` while resolving it. |
@@ -883,7 +933,10 @@ after an authorized launch before claiming its actual permission behavior.
 The rig-level verbs are `rig policy permissions list`, `show`, `current` and
 `apply`. Existing `rig policy list/show/current/apply` remain compatibility
 aliases with the same JSON and exit behavior. Pi resource trust and the per-seat
-typing guard are separate controls.
+typing guard are separate controls. To retain automatic messages while you have
+an unfinished terminal input, opt that seat into [draft-aware delivery](seat-delivery.md).
+The same typing guard offers `hold` for a manual terminal (`--enabled true`)
+and `off` for ordinary automatic sends (`--enabled false`).
 
 ### Claude Code: a different launch flag
 
@@ -923,7 +976,17 @@ and managed restrictions still matter; this flag is not a promise about sandbox
 or account access. See [Claude permissions](https://code.claude.com/docs/en/permissions).
 
 **Already running:** changing a file or running `rig policy apply` does not revoke
-a live agent's permissions, nor rewrite a stored rig's policy on restore. Pause
+a live agent's permissions, and a spec edit does not rewrite a stored rig's policy
+on restore: restore and resume read each seat's stored policy. To change that
+for an existing seat, run `rig policy apply <name> --seat <seat> --reason <text>`,
+adding `--operator <address>` outside a managed seat. Restore, resume and launches
+that read the seat's stored state then use it, unless an explicit native selection
+(`rig seat set-permissions`) takes precedence; the running process and the spec
+file are unchanged. `rig up <rig name>` uses it, while launching from a spec that
+declares a policy replaces it with the spec's policy, which later restores then
+use. `--seat none` is an explicit floor for that seat, not "no policy", and it does
+not inherit the rig's policy. After `--seat`, a `rig launch --retry-startup-from`
+file has to carry the new policy. Pause
 work and use the native permission controls for that conversation (current
 Codex and Claude CLIs expose `/permissions`); inspect the effective mode again.
 Keep the launch spec/profile consistent for subsequent launches. If the native

package/daemon/docs/reference/keeping-a-watch.md

@@ -4,9 +4,12 @@
 keeps, using today's queue commands.** The person speaks in sentences. They never see YAML, a job ID or a policy name
 unless they ask.
 
-> **Status (0.7.0, not on by default).** No agent's guidance points here yet, and no profile loads it. It's switched
-> on by adding one line to the kernel operator's role guidance, after a native run on a real install shows the
-> pattern holds. Until then, hand this page to an operator by hand (`docs/reference/keeping-a-watch.md`) to try it.
+> **Status (0.7.0).** The kernel operator's role guidance points here: when a person asks it to watch something or
+> remind them, it reads this page (installed at `$OPENRIG_HOME/reference/keeping-a-watch.md`) first. Every step below
+> was exercised with the CLI on an isolated private daemon: create, set aside, fire, re-arm, list, change, stop, a
+> daemon restart and a handover. A native run with a real operator, install and channel has **not** been run yet.
+> The usage warning's command and field names are checked against the served command on a test fixture; it hasn't
+> been run as a watch.
 
 ## The shape
 
@@ -146,11 +149,105 @@ under some conditions, with no delay guarantee. So:
 
 - **Re-arm promptly** after every fire.
 - **After a restart or handover, list your watches** (above) and re-arm any that show no timed backstop.
+- **Handing a watch to another session** (`rig queue handoff <task> --to <session>`) closes the old task and retires its
+  timer (unless another task shares that timer through `--wake-watchdog`; a watch set up as above never does). The new
+  task arrives pending, with its body and `watch` tag but no timer: the new owner sets it aside again with a fresh
+  timer, as in step 3.
+
+## A usage warning: "warn me when my allowance runs low"
+
+This is a conditional watch like any other: the same task, timer, re-arm, stop and human channel. Only the check is
+specific.
+
+**The check is `rig provider status --all-hosts --json`.** It returns what every registered machine already holds,
+this one included, and never starts a read on any account. With no host registry it covers this machine only, and
+says so. Use it rather than the single-machine `rig provider status --json`: one allowance used from several
+machines appears once, with each machine's own observation beside it, so you can't count it twice. If it answers that
+usage windows are off, tell the person that before setting the watch, as you would an unreachable channel.
+
+**Never put `--refresh` in the timer's check.** `rig provider status --all-hosts --refresh` starts a native read of the
+accounts on every machine. Run it only when the person asks for a fresh reading now.
+
+**Choose the allowance with the person once, and write its identity into the body.**
+- **The allowance:** its `items[].key` and `items[].provider`, read from one run of the check. Show them the allowance
+  by its label in the plain `rig provider status --all-hosts` view, never a key they have to type. An item whose key
+  is null (a login that hasn't been identified) can't be watched: say so, and offer to watch it once it's identified.
+- **For Codex, the login email too:** `items[].observations[].row.identity.email`, shown on each machine's line in the
+  plain view. The same Codex account can appear as more than one item with the same key, one per login email (or none)
+  it was seen under. So on each fire, use the one item whose key matches and whose observations carry the recorded
+  email. If none or several do, you can't tell. A Codex allowance whose login email is missing can't be pinned this
+  way, so it stays can't tell. A changed email isn't followed: if the person's login email changes, set the watch
+  again with them.
+- **The window:** `items[].observations[].row.windows[].window`. Claude's are `five_hour` and `weekly`; Codex's are
+  `primary` and `secondary`, with `items[].observations[].row.windows[].durationMins` saying which is which.
+- **The threshold:** on `items[].observations[].row.windows[].remainingPercent`. It's a percentage, and no absolute
+  amount is served. Remaining is 100 minus `items[].observations[].row.windows[].usedPercent`, never below 0. Both are
+  null when the machine reported no usage for the window.
+
+**What each part of the answer means:**
+
+| Field | What it tells you |
+|---|---|
+| `items[].linkage` | `single`: one machine saw it. `same`: several machines saw one allowance. Compare their observations; **never add or average them**. `conflict`: the machines' fresh observations disagree (their reset times are more than 60 s apart); every observation is kept and none is chosen. `unknown`: the same id seen under another login, or with no login email, and not merged with it. `items[].notes` says why. For Codex, the one item carrying the person's recorded key and email is still theirs: its `unknown` is about the other login's item (see the decision). Any other `unknown` item is not theirs to watch |
+| `items[].observations[].hostId`, `items[].observations[].readAt` | Which machine the observation is from, and when this daemon read it |
+| `items[].observations[].row.windows[].observedAt` | When that machine's reading was taken: the time to tell the person |
+| `items[].observations[].row.windows[].resetsAt` | When that window resets: tell the person this too |
+| `items[].observations[].row.windows[].freshness` | `fresh`, `stale` or `unavailable`, with `items[].observations[].row.windows[].freshnessReason` saying why. A reading is fresh for 15 minutes |
+| `items[].observations[].row.windows[].level` | The served level, with `items[].observations[].row.windows[].levelReason`. Compare the person's threshold, not this level. But **`unknown` means the number can't be used**: no usage was reported, the window's reset time has passed (the number is from before it), or Claude seats report different windows (possibly different logins) |
+| `items[].observations[].row.lastRefresh` | **Codex:** that machine's last native read. When `items[].observations[].row.lastRefresh.outcome` is `failed`, the reading it kept is older and reads `stale`. **Claude:** the last read of the daemon's own Claude login (its identity) only. Claude's windows come from the seats' status-line readings at their own times, so they can stay `fresh` beside a failed identity read |
+| `items[].observations[].row.identityNote` | **Claude:** which login the identity is (as of the last identity read) and which seats the windows came from. The windows aren't proven to be that login. Say so when you tell the person |
+| `hosts[].usage`, `hosts[].usageReason` | Whether each machine's usage was read: `served`, `off`, `older` or `unavailable`, and why. A machine that wasn't read contributes nothing, never a zero |
+| `hosts[].lastRefresh` | The last refresh started from here for that machine, per provider. A `failed` one sits beside the older observation the machine kept |
+| `seatAccounts[].seats[].configured`, `seatAccounts[].seats[].allowance` | The account each seat is **configured** to use. `seatAccounts[].seats[].allowance.linked` is always false: configuration isn't proof of which allowance a running seat draws on, or that a Claude seat's windows are the identity's login. Never tell the person a seat uses this allowance because of it |
+| `seatAccounts[].seats[].observed` | What the seat itself was seen reporting: whether its status line has sent windows and when (`seatAccounts[].seats[].observed.lastSampledAt`), and `seatAccounts[].seats[].observed.differsFrom`, the seats whose readings disagree with it. Observed facts, still not a link to an allowance |
+
+**The decision on each fire,** using the table in "Every time the timer fires". A usable reading is a `fresh`
+observation of the chosen window whose `level` isn't `unknown`.
+- **Met:** a usable reading is below the threshold. Tell them the lowest one, with its machine, `observedAt` and
+  `resetsAt`. If the linkage is `conflict`, also tell them the machines disagree, from `items[].notes`, rather than
+  presenting the lowest as the reading.
+- **Not met:** every usable reading is at or above the threshold, and there is at least one.
+- **Another login on the same Codex account:** when the item matched by key and recorded email has `items[].notes`
+  saying the account is also observed under another login email (or with none), its linkage reads `unknown` on one
+  machine, or `same` on several. Use its own usable readings as above. When you tell the person, say that login's
+  observations are unlinked: not added, and not merged.
+- **Can't tell:** no usable reading: none `fresh`, or the fresh ones' `level` is `unknown`, which includes a null
+  `remainingPercent`. Also when the allowance is missing from the answer or its key is null, or (Codex) no login email
+  was recorded, or no item, or more than one, carries both the key and the recorded email. Use the once-then-quiet
+  unknown rule, and give the reason (`freshnessReason`, `levelReason`, or the machine's `usageReason`).
+
+The task body, for the person's own allowance, window and threshold:
+
+```markdown
+Person's words: "Warn me when my Claude allowance drops below 20% of its 5-hour window; check every 30 minutes."
+Check: `rig provider status --all-hosts --json` (served readings only; never --refresh).
+Allowance: key <allowance key>, provider claude, window five_hour. Chosen with the person.
+(For Codex, also: login email <email shown in the label>.)
+Usable: a fresh observation of that window whose level isn't unknown.
+Met: a usable reading with remainingPercent below 20. Report the lowest, with its machine, observedAt and resetsAt.
+Never add machines' numbers. If the linkage is conflict, say the machines disagree (items[].notes).
+Claude: say the windows come from seats' status lines and aren't proven to be the identity's login (identityNote).
+Codex: the one item with the recorded key and email is theirs even if its linkage is unknown; say the other login's
+observations are unlinked (items[].notes).
+Can't tell: no usable reading (none fresh, or level unknown: give its levelReason), the allowance missing or its key
+null, or (Codex) no email recorded, or no item, or more than one, carries both the key and the recorded email. Give the
+reason.
+Interval: 30m.
+Tell them: <entityId>@external (human channel), once, when met.
+Stop: after telling them once, or when they say stop.
+Unknown: not said yet.
+```
 
 ## What not to use
 
 - **`rig watchdog register --policy periodic-reminder` for a person's watch.** It repeats every interval until it's
   stopped (the first fire comes one interval after you register it), and it stops when the agent that registered it
-  is replaced. It's fine for agent-to-agent reminders.
+  is replaced. It's fine for agent-to-agent reminders. Your own watch timers also show as `periodic-reminder` in
+  `rig watchdog list`: that's the one-shot timer `--wake-after` arms, not a registered repeating reminder. It's retired
+  when it fires or when the task stops being set aside. A wake held back because you were typing (a retained
+  delivery) wasn't delivered, so it doesn't use the timer up: it's tried again at each interval until an attempt goes
+  through (delivered or failed), which retires it. A timer another task shares through `--wake-watchdog` stays live
+  for that task when this task is handed off or stopped, and the same rule applies to its wake. None of this is a
+  delivery guarantee.
 - **Transcript bytes as "usage".** `context-usage-threshold` measures an agent's transcript, not an account's
-  allowance.
+  allowance. For an allowance, see "A usage warning" above.