@openrig/cli 0.6.14 → 0.7.1

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

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

package/daemon/docs/reference/quickstart.md

@@ -6,6 +6,25 @@ talk to one agent, and it hands work to the others. The team keeps its tasks and
 Most people let their coding agent set it up. This page explains what happens either way, so nothing is a black
 box, and shows how to do each step by hand if you'd rather.
 
+## The quick way: let your coding agent do it
+
+In your project folder, add OpenRig's `rigs` skill to the agent you use:
+
+```sh
+# Claude Code
+npx skills add https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs --skill rigs --agent claude-code
+# Codex
+npx skills add https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs --skill rigs --agent codex
+```
+
+For a new install, use the latest release's tag, for example `v0.7.1`. If OpenRig is already installed, use the tag
+that matches `rig --version`, or upgrade first. If the command fails with `npx: command not found`, Node.js isn't
+installed or isn't on your PATH yet (see [What you need](#what-you-need)). Then type `/rigs` in Claude Code, or `$rigs` in Codex, and say what
+you want built.
+
+The skill has your agent work through the steps below in order. It says what it will run and change before it runs
+it, and it asks before installing anything on your system. It finishes when you're talking to the operator.
+
 ## How the pieces fit
 
 - **`rig`** is the command you and your agents use. It comes from the npm package `@openrig/cli`.
@@ -30,24 +49,18 @@ Ask your coding agent to help use the toolchain already on your machine. On a Ma
 may belong to another user; do not change its ownership to complete this setup. After correcting PATH or installing
 Node, open a new terminal and check `node --version` and `npx --version` before continuing.
 
-## The quick way: let your coding agent do it
-
-In your project folder, add OpenRig's `rigs` skill to the agent you use:
+On a Mac where you aren't an administrator, or where another account owns Homebrew, install Node.js in your own home
+folder with [nvm](https://github.com/nvm-sh/nvm); nvm itself needs no administrator password. A new Mac account has no
+`~/.zshrc`, and nvm's installer only adds itself to a profile file that already exists, so create one first:
 
 ```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
+touch ~/.zshrc
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
 ```
 
-For a new install, use the latest release's tag, for example `v0.6.14`. If OpenRig is already installed, use the tag
-that matches `rig --version`, or upgrade first. If the command fails with `npx: command not found`, Node.js isn't
-installed or isn't on your PATH yet (see above). Then type `/rigs` in Claude Code, or `$rigs` in Codex, and say what
-you want built.
-
-The skill has your agent work through the steps below in order. It says what it will run and change before it runs
-it, and it asks before installing anything on your system. It finishes when you're talking to the operator.
+Then open a new terminal and run `nvm install 22`. If nvm's installer says you need Apple's command line tools, run
+`xcode-select --install`, then its install command again. That's nvm v0.40.8's install command; [nvm's
+page](https://github.com/nvm-sh/nvm#install--update-script) has the newest.
 
 ## What happens, step by step
 
@@ -67,10 +80,10 @@ Node.js and SQLite check was skipped.
 ### 2. Set up the tools around it
 
 ```sh
-rig setup --providers claude   # or codex, or both
+rig setup --providers claude
 ```
 
-Add `--dry-run` first to see the plan without changing anything. Setup does four things:
+Use `codex` or `both` in place of `claude` to match the coding agents you use. Add `--dry-run` first to see the plan without changing anything. Setup does four things:
 - it checks Node.js, tmux and your sign-in;
 - it installs a missing tmux (with Homebrew on macOS, if you have it) or the coding agent you chose;
 - it installs Herdr, a terminal workspace app the OpenRig view can use, unless you add `--no-herdr`;
@@ -132,10 +145,10 @@ Before it starts one, it tells you what starting a team in your folder changes:
 `CLAUDE.md`, plus the team's skills. Then it waits for your yes. As shipped, `starter` uses both Claude Code and
 Codex. With only one of them, ask the operator to adapt it.
 
-By hand, from your repository:
+By hand, from your repository (the first command shows what it would start, and starts nothing):
 
 ```sh
-rig up starter --cwd . --plan    # check what it would start
+rig up starter --cwd . --plan
 rig up starter --cwd .
 rig ps --nodes --rig starter
 ```
@@ -156,10 +169,10 @@ stops that team. `rig daemon stop` stops the background service and leaves agent
 
 ## The one-command install
 
-Instead of steps 1 and 2:
+Instead of steps 1 and 2 (the first line shows the plan and changes nothing):
 
 ```sh
-curl -fsSL https://openrig.dev/install.sh | sh -s -- --dry-run   # shows the plan and changes nothing
+curl -fsSL https://openrig.dev/install.sh | sh -s -- --dry-run
 curl -fsSL https://openrig.dev/install.sh | sh
 ```
 

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

@@ -36,9 +36,17 @@ own project folder is the same project and still acts as the seat, as before thi
 launched before this change, a manual run) the hooks do what they always did. The plugin's activity relay stays quiet next to
 the seat's own `settings.local.json` copy only when that entry is exactly OpenRig's and the script it names is the same
 script; an entry from an older install doesn't match, so both report until the seat's next launch refreshes it.
-Codex has no way to load a plugin from a directory; its hooks come from the daemon's
-managed block in `config.toml`, which today carries the activity relay only, so the Codex column above describes
-`hooks/codex.json`'s registration and not a hook a Codex seat currently runs.
+OpenRig automatically installs its Codex plugin for seats that select it. On its first installation, the six exact shipped
+hook definitions and bundle content are trusted before launch, after checking the entire installed plugin against this daemon's shipped copy.
+On upgrade, OpenRig renews content approval only for a previously approved OpenRig-owned bundle with unchanged approved hook definitions.
+It keeps explicit disables, refusals, unknown config layers and other plugins' state. An installation without a proven prior approval stays under native review.
+Codex's "continue without trusting" leaves no record: a skip of an otherwise eligible OpenRig-owned update may therefore be superseded on retry.
+OpenRig records its approved bundle in `CODEX_HOME/.openrig-core-hook-trust.json` and leaves Codex's immutable `.hook-trust` baseline untouched.
+Codex 0.164 checks bundle contents when hooks run; a later edit requires native approval again. Older Codex versions enforce their own trust rules.
+The Codex
+column above then applies only to a Codex seat whose plugin selection includes openrig-core: every Codex hook command
+exits 0 before running anything unless OpenRig gave that seat `OPENRIG_SEAT_PROJECT_DIR` and an explicit
+`OPENRIG_NODE`.
 
 Claude's additional firing signal is **transcript growth** — not turns (one turn
 can burn 200k tokens across fifty tool calls) and not wall-clock (the failure is

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

@@ -174,7 +174,7 @@ edges:
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `version` | string | yes | — | Use `"0.2"`. Any non-empty string validates; a spec is treated as pod-aware because `pods` is an array. |
-| `name` | string | yes | — | Rig name. Used in session naming (`{pod}-{member}@{name}`), snapshot identification, and spec library lookup. |
+| `name` | string | yes | — | Rig name. Used in session naming (`{pod}-{member}@{name}`), snapshot identification, and spec library lookup. `rig up <spec> --name <rig>` launches the spec under another name instead (see below). |
 | `summary` | string | no | — | Human-readable description. Shown in the spec library, review surfaces and `rig specs preview` (in `rig specs show` only with `--json`). |
 | `culture_file` | string | no | — | Relative path to a rig-wide culture/constitution file. Must be a safe relative path (no `..`, no absolute). |
 | `non_interruptive` | boolean | no | — | Pod-aware rig launch-warning default. With full-bypass Claude/Codex seats, true accepts or hides supported harness warnings using launch flags. Explicit CLI choices override this field; this field overrides the machine default. It does not grant permissions, change native settings files, or bypass login. |
@@ -188,6 +188,8 @@ edges:
 | `pods` | Pod[] | yes | — | At least one pod required. Each pod is a bounded context containing members and pod-local edges. |
 | `edges` | CrossPodEdge[] | no | `[]` | Cross-pod edges connecting members in different pods. Must use fully-qualified `pod.member` IDs. |
 
+**Launching one spec under another name.** `rig up <spec> --name <rig>` creates the rig as `<rig>` instead of the spec's `name:`, so one spec can run as several rigs at once, for example `--name alpha` and `--name beta`, with seats `{pod}-{member}@alpha` and `{pod}-{member}@beta`. The spec file is not changed. The rig keeps the chosen name from then on: `rig ps`, `rig down alpha`, `rig up alpha --existing`, snapshots and restore all use it. The same checks as a launch without `--name` apply to the chosen name: a running rig of that name refuses the launch, and a stopped one is archived and replaced, as an explicit spec import does today. `--name` does not rename an existing rig, so the CLI refuses it with the name of an existing rig to restore, with a topology and with a GitHub bundle link. A library spec name works: `rig up starter --name beta` launches the library spec as `beta` even while a rig named `starter` exists. Over `--host`, pass the spec path or bundle file with `--name`. A spec that sets `services.project_name` refuses `--name`: every rig launched from it would share that Compose project, and `rig down` or a failed service boot of one would stop the others' services. Without `project_name`, each rig gets its own project. Two launches of the same spec started at the same moment can answer 409 (already in progress for this source) even under different names; start them one after the other.
+
 ### Attaching a permission policy
 
 Attach a policy to a rig with `permission_policy`, either at the rig level or on a member:
@@ -354,7 +356,7 @@ pods:
 
 - A seat gets the rig's `env` with its own `env` laid over it, name by name.
 - The same environment is applied on first launch, on `rig up <rig-name>` restore, and to the successor of a seat handover.
-- `rig up <spec> --env KEY=VALUE` (repeatable) adds or overrides a value for one launch. A one-off value belongs to the terminal that launch creates: it stays in that terminal's environment for as long as the terminal lives, and OpenRig removes it from the tmux session's environment as soon as the terminal has started, so a terminal started later in that session does not get it. A restore, a handover successor or any later launch starts from the spec's `env:` alone, so the value is not saved and does not carry forward. To keep a value, put it in `env:`. One exception to "does not carry forward", for a managed Claude seat (see below): a one-off name that the seat's spec does not declare stays on the session's list of names, `OPENRIG_SEAT_ENV_KEYS` (names only, no values), because the first launch and an in-place restart of the same terminal read that list. So if a later pane in that session gets a value for that name from the tmux server's own environment, its managed Claude launch can forward that value, where a launch without `--env` would leave it out. The first launch's one-off value itself is not passed on to that pane. This comes from reading the code and has not been measured. `--env` does not apply to `rig up <rig-name>` (a restore) or to a topology (several rigs from their own specs); the CLI refuses both. For a topology, put `env:` in each rig's spec.
+- `rig up <spec> --env KEY=VALUE` (repeatable) adds or overrides a value for one launch. A one-off value belongs to the terminal that launch creates: it stays in that terminal's environment for as long as the terminal lives, and OpenRig removes it from the tmux session's environment as soon as the terminal has started, so a terminal started later in that session does not get it. If OpenRig can't take it out, the seat keeps running and the launch warns, naming the variable and the tmux command to put it back or remove it. Until then, a terminal started later in that session would get it. A restore, a handover successor or any later launch starts from the spec's `env:` alone, so the value is not saved and does not carry forward. To keep a value, put it in `env:`. One exception to "does not carry forward", for a managed Claude seat (see below): a one-off name that the seat's spec does not declare stays on the session's list of names, `OPENRIG_SEAT_ENV_KEYS` (names only, no values), because the first launch and an in-place restart of the same terminal read that list. So if a later pane in that session gets a value for that name from the tmux server's own environment, its managed Claude launch can forward that value, where a launch without `--env` would leave it out. The first launch's one-off value itself is not passed on to that pane. This comes from reading the code and has not been measured. `--env` does not apply to `rig up <rig-name>` (a restore) or to a topology (several rigs from their own specs); the CLI refuses both. For a topology, put `env:` in each rig's spec.
 - Names starting `OPENRIG_` are reserved for OpenRig and refused. Empty values are refused, because the launch omits empty variables.
 - `rig export` writes the rig and member `env:` back out.
 
@@ -440,8 +442,12 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 | `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. Claude gets `--effort`, Codex `-c model_reasoning_effort=…`, Pi `--thinking` (see "Pi" below). A non-string value is ignored with an advisory. |
+| `advisor` | string | no | — | Claude-only Advisor model for this seat. Overrides the AgentSpec profile/default; blank or non-string values are 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. |
+| `agent_file` | string | no | — | Claude members only. A Claude agent definition (a `.md` file with `name` in its frontmatter) for this seat. It's copied into the seat's own storage and launched as `--agent openrig:<name>`. A path beside the spec: no `..`, not absolute. |
+| `append_system_prompt_file` | string | no | — | Claude members only. A prompt file appended to Claude's system prompt for this seat. It's copied into the seat's own storage and passed as `--append-system-prompt-file`. A path beside the spec. |
+| `plugin_dirs` | list | no | — | Claude members only. Claude plugin folders for this seat, each copied into the seat's own storage and loaded through `CLAUDE_CODE_PLUGIN_DIRS`. Paths beside the spec. Each is copied under its folder name, so two folders with the same name are refused; an empty list is none. A missing file or folder fails that seat's launch by name. `rig bundle create` carries all three; `rig export` names a seat whose additions it doesn't carry. |
 | `role` | string | no | — | The seat's role, letters, digits, `_`, `.` and `-`. Not valid on terminal members. |
 | `restore_policy` | string | no | the AgentSpec's | Restore behavior. One of: `resume_if_possible`, `relaunch_fresh`, `checkpoint_only`. The default comes from the AgentSpec's `defaults.lifecycle` (else `resume_if_possible`) as narrowed by its profile; a member value may only narrow it further, in that order. |
 | `compaction_strategy` | string | no | — | `default-compaction`, `managed-compaction`, `handover` or `apprentice-handover`; `harness_native` and `pod_continuity` are accepted as deprecated aliases, and `custom_prompt` is refused. `managed-compaction` and `apprentice-handover` create their jobs only for `claude-code` seats; see [Codex compaction and sizing](agent-startup-guide.md#codex-compaction-and-sizing). |
@@ -450,6 +456,36 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 | `starter_ref` | object | no | — | `{ name }` of an agent starter (`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`) whose files lead the seat's startup. Not valid on terminal members or with a fork. |
 | `startup` | StartupBlock | no | — | Member-level startup files and actions. Applied only to this member. |
 
+### Claude Advisor (`runtime: claude-code`)
+
+Set `advisor` independently of the primary `model`:
+
+```yaml
+members:
+  - id: owner
+    agent_ref: local:agents/implementer
+    profile: default
+    runtime: claude-code
+    cwd: .
+    model: claude-sonnet-5-5
+    effort: medium
+    advisor: opus
+```
+
+OpenRig passes `--model claude-sonnet-5-5 --effort medium --advisor opus` to this
+Claude session. The primary model stays Sonnet. Advisor resolution uses the member's
+`advisor`, then the profile's `preferences.advisor`, then the agent's `defaults.advisor`.
+Blank candidates are skipped before applying this precedence. Materialization stores
+the resolved value, so node/graph output, exported specs and snapshots include it even
+before the first launch. Launching the original spec re-resolves its current preferences.
+The selection is supplied again on resume, restore, fresh restart and handover. A fork
+uses the resulting member's configuration and keeps its own conversation identity.
+
+This requires a Claude Code version that supports `--advisor`. OpenRig never writes
+`advisorModel` to user or project settings. Members sharing a checkout can therefore
+choose different Advisors. When Advisor is unset, no flag is emitted and Claude's
+own defaults/settings apply. Other runtimes ignore this field.
+
 ### Pi (`runtime: pi`)
 
 `runtime: pi` launches the Pi coding agent (`pi --mode rpc`) through OpenRig's RPC runner.
@@ -467,7 +503,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 - **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:** 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.
+- **Restore:** OMP creates its session file after the first persisted turn. A new seat with no persisted turn has no resume token, so a restore leaves it awaiting a decision. Start it fresh with `rig seat launch <seat> --fresh --reason "<why>"`, the command `rig start` and `rig up --existing` print for that 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 seat launch <seat> --fresh --reason "<why>"`, or restore it manually. `rig seat launch --fresh` refuses a managed seat whose pane is still running unless you add `--stop`, which ends what is running there; add it only when you mean to replace that session.
 
 ### Terminal Nodes
 
@@ -483,6 +519,8 @@ All three must be present together. Any partial combination is a validation erro
 
 A terminal seat no longer waits for a `--fresh` decision just because it has no resume token: on restore it relaunches fresh and re-runs its startup actions. The runtime, identity and replay prerequisites still apply. A runtime mismatch still waits for a decision, an ambiguous occupant still fails, and a missing required replay file still blocks.
 
+`rig send` to a terminal node types the exact text, without the From/To envelope that agent seats get, because the shell would run the envelope lines. The sender's output says so.
+
 ### agent_ref Rules
 
 - Must start with `local:` or `path:`
@@ -553,6 +591,48 @@ edges:
 
 Cross-pod edges must reference different pods. An edge where both `from` and `to` are in the same pod is a validation error — use pod-local edges instead.
 
+### Changing edges on an existing rig
+
+Use `rig edge add` to ensure relationships between seats that already exist. It
+accepts a rig name or ID and **fully qualified logical IDs for both same-pod and
+cross-pod edges**. This command only changes edges; it does not create pods,
+restart sessions or change seat identity.
+
+```sh
+rig edge add my-rig orch.lead review.reviewer --kind delegates_to --plan --json
+rig edge add my-rig orch.lead review.reviewer --kind delegates_to --json
+```
+
+Run it once per edge. It returns `added` with the new edge's ID, or `present` with
+the existing edge's ID when that `{from, to, kind}` is already there, and then
+writes nothing. Existing duplicate rows from other creation paths are retained;
+this operation does not create more copies.
+
+Unknown endpoints, an invalid kind or a launch-order cycle leave the graph
+unchanged. Both endpoints must belong to the target rig. `--plan` performs the
+same validation and returns `would_add` for a new edge without writing anything.
+
+Each `added` receipt includes a rollback command,
+`rig edge remove <rig-id> <edge-id>`, which removes exactly that edge in that rig.
+Removal also supports `--plan` and `--json`. Removing an edge that is already gone changes nothing
+and returns `edge_not_found` (HTTP 404, exit 1), so a repeated removal reports not found, not success.
+Rig names resolve only among unarchived rigs, and an ambiguous name requires an
+explicit ID. These commands target the local daemon, as `rig add` does.
+
+A `delegates_to` edge also decides routing. A seat's stuck-row findings and recovery go to its most
+recently started parent. A person's top-level Slack message in the rig's mapped channel goes to the rig's
+representative, its one delegation root, unless that channel names an `inbound` seat; with no single root it
+goes to Slack's inbound destination. When an added or removed edge changes either, the receipt says what
+moved in `routing`:
+`orchestrator: {seat, from, to}` and `representative: {from, to}`, where `null` is none. The plain output
+prints a `routing:` line for each. A change that moves nothing has no `routing`, and `--plan` doesn't
+preview it.
+
+Changes are persisted immediately and included in `rig export`. Existing snapshots
+remain unchanged, and restore reads the **selected snapshot's edges**. To restore
+the modified topology, run `rig snapshot <rig-id>` and use its returned ID with
+`rig restore <snapshot-id> --rig <rig-id>`.
+
 ---
 
 ## Startup Block

package/daemon/docs/reference/seat-delivery.md

@@ -8,15 +8,86 @@ daemon-owned retry scheduler. Sibling seats keep their own mode.
 | Mode | Terminal input | When input is unavailable |
 |---|---|---|
 | `off` (default) | Existing delivery and prompt checks | Existing send result |
-| `draft-aware` | Paste into a recognized empty composer; check ownership again before Enter | Immediately retain the original message with the exact refusal reason and ID |
+| `draft-aware` | Paste into a recognized empty composer; check ownership again before Enter | Hold input and retain this attempt for inspection when bookkeeping is available |
 | `hold` | No automatic terminal input, even at an empty prompt | Retain for inspection outside the pane |
 
 Runtime permissions are separate. Recipient and interactive-prompt checks still
-apply. `--raw`, `--force` and `--dangerously-interact` do not bypass the typing guard.
-Direct human input remains available.
+apply. `--raw` and `--force` do not bypass the typing guard. A deliberate
+`--dangerously-interact --reason` remains available at every interruption level
+and uses the existing-input check below. Direct human input remains available.
 
 ## Configure and inspect
 
+### Who may intervene
+
+`rig seat status <seat>` shows the seat's terminal interaction account alongside
+its native permissions and interruption level. These choices are independent.
+The presets `no-peer-interventions`, `help-within-instructions` and `full-control`
+set the peer row. Self and OpenRig retain their existing authority unless an
+explicit exception changes it. Named helpers and the delegating instruction are
+shown; OpenRig does not interpret free-text instructions as executable rules.
+
+~~~sh
+rig seat set-terminal-policy reviewer@my-rig --preset help-within-instructions \
+  --helper lead@my-rig --peer-model deny \
+  --reason "Help with compaction; keep the review model"
+rig seat status reviewer@my-rig
+~~~
+
+Each `--peer-compaction`, `--self-compaction`, `--openrig-compaction`,
+`--peer-model`, `--self-model` or `--openrig-model` exception takes `allow` or
+`deny`. Model includes reasoning effort. Exceptions apply to the whole actor
+row: `--peer-compaction allow` also allows unnamed peers. A choice with
+exceptions reads as Custom. The setter replaces the complete choice; omit
+exceptions to return to the preset's defaults. Outside a managed seat, use `--operator <address>` for
+audit attribution. This does not establish an authenticated identity.
+
+Enforcement covers managed compaction and saved model/effort changes only.
+The latter take effect at the next managed continuation, not in the current
+process. Other interventions remain guidance-only. Managed compaction applies
+to Claude seats; it is not offered for Codex or Pi. A policy change during
+preparation is checked before further input. It does not undo a submitted
+`/compact` or abandon an already-owed restore/audit.
+
+Existing seats retain current behaviour on upgrade. To choose a default for
+newly added seats in a rig, add `--rig-default` to the setter above: existing
+seats keep their own copied choices. OpenRig's standing managed-compaction
+authority stays active unless its exception is deliberately changed.
+
+Caller attribution is cooperative. An unattributed caller retains current
+behaviour rather than being labelled the person or a peer. The existing
+`rig send --dangerously-interact --reason` path remains available; this policy
+adds no restriction there. Its existing-input check applies independently of the
+typing mode. Plain tmux is not prevented.
+
+### Deliberate interaction and existing input
+
+A managed `rig send <seat> "<answer>" --dangerously-interact --reason "<why>" can
+drive a recognized native menu as before. Otherwise, with the delivery guard
+attached, it reads the visible composer under the seat's lease immediately before
+pasting, after buffer preparation. Empty input proceeds. A recognized dim
+suggestion is displayed separately and counts as empty; typed or pasted text
+(author unknown) stops the send with `override_input_present`. An unreadable input
+stops with `override_input_unknown`, never an empty-input claim. Both return single-send HTTP
+409, `sent: false`, and caller-only `existingInput` evidence (visible rows, suggestion
+rows, cursor/dimensions and target binding). A collapsed paste shows its label,
+not the hidden contents. OpenRig neither holds nor retries this stopped override.
+
+Inspect the shown input in the native terminal, deliberately clear the prompt with
+native/tmux controls, then issue the send again. Manual clearing runs outside
+OpenRig's lease and observation checks and is not recorded. For a deliberate
+unchecked write, add `--type-without-checking` to that same command. It skips the
+read and does **not** clear input: the text may join or submit what is already there.
+The result names that choice. It requires `--dangerously-interact` and `--reason`.
+
+Observed input is returned only to the caller, never saved in an outbox, held
+message, capture-observer record or override audit. The audit keeps classifications,
+counts and the choice, without input contents. The lease serializes OpenRig writes;
+human typing can still race the capture and paste. Ordinary sends and wakes keep
+their existing behaviour.
+
+### Terminal delivery
+
 Run from a seat shell with `OPENRIG_SESSION_NAME` set; the daemon derives the
 audit actor from transport identity.
 
@@ -36,13 +107,22 @@ to finish. The API may return HTTP 202 with `pending: true`; wait for
 `pending: false` before relying on the requested mode. Status reports desired
 and effective modes and retains the text `Typing guard: on (hold)` for hold.
 
-A held send immediately returns `outcome: "retained"`, `sent: false`,
-`outboxIds` and its exact reason, such as `draft_input_busy` or
-`draft_input_unknown`. No automatic retry is scheduled, including when the
-caller requested wait-for-idle. The caller can inspect or route the retained work
-and decide when to make a new request. Reusing the same delivery ID reads its
-original result; it does not replay that message. Changing modes, clearing a
-draft, or restarting the daemon also does not flush held records.
+A held send immediately returns `outcome: "retained"`, `sent: false`, its exact
+reason (such as `draft_input_busy`) and the saved attempt's `outboxIds`. No automatic
+retry is scheduled. Each explicit draft-aware request is a new attempt, including
+one with a reused `deliveryId`; the result warns older callers that this field no
+longer deduplicates input. The CLI does not generate a deduplication key.
+
+Clearing a draft, changing modes or restarting does not flush saved messages or
+callbacks. To try again, send a current request: it rechecks the recipient and input.
+A caller abort before paste cancels input; after a write may have started, the
+result preserves that uncertainty rather than claiming nothing was sent.
+
+Bookkeeping is observational. If its write fails, an otherwise valid input attempt
+still proceeds and the response includes a warning instead of a saved receipt.
+Actual transport success stays success; an unknown write stays unknown. If input
+was held and no record could be saved, the response reports failure with `sent:
+false` and the protection reason, rather than claiming durable custody.
 
 Reading never sends. Retirement frees that record's active retention quota while
 preserving evidence; it does not deliver a message or close queue work.
@@ -72,22 +152,34 @@ A large paste can appear as several labels plus a literal tail. The existing
 boundary. That complete rendering must be observed after this operation's paste
 and remain unchanged before Enter. Labels alone do not prove arbitrary content.
 
-| Delivery state | Meaning |
+| Historical delivery state | Meaning |
 |---|---|
-| `sending` | The original IDs have an unresolved write attempt |
-| `held` | No input was written; the original message remains retained or has been retired |
+| `sending` | This saved attempt has an unresolved write outcome |
+| `held` | No input was written; this attempt remains retained or has been retired |
 | `complete` | Transport execution succeeded, including render verification if requested; native consumption is not asserted |
-| `indeterminate` | Input may have occurred or requested render verification failed; no automatic replay |
+| `indeterminate` | Input may have occurred or requested render verification failed |
+| `failed` | A definite failure before input, such as caller cancellation |
 
 Migration `100_typing_guard_modes` extends the existing guard/audit rows and
 adds receipt metadata to the original outbox rows; it creates no tables, retry
 indexes or executable requests. Combined wakes retain each original ID and body.
-A held queue wake stays on the existing queue recovery path. Interrupted writes
-become indeterminate at startup regardless of which recovery component runs first.
+A held queue wake stays on the existing queue recovery path. Interrupted historical
+writes become indeterminate at startup. That history never suppresses a current
+explicit request and is not consulted to determine its result.
+
+At startup, the queue recovery pass retries still-current failed or unconfirmed
+wake notifications. It preserves their original envelopes and warns that delivery
+may repeat. Each notification is attempted once per pass, including coalesced
+wakes; a failed attempt cannot spin in that pass. A no-write failure on a later
+retry does not resolve an earlier unknown delivery. Prior-process claims are
+reconciled before new startup sends can begin. Known deliveries and held or
+retired messages stay untouched. Closed, claimed or reassigned work is not woken,
+and the retry never repeats the queue mutation or a lifecycle action.
 
 The existing retention limits apply: 100 records and 8 MiB per seat, with a 1 MiB
-message limit. New admissions refuse at capacity; already-committed queue intent
-remains durable even if concurrent activation exceeds the limit.
+message limit. Hold mode cannot retain another message at capacity. Draft-aware
+input attempts continue with a bookkeeping warning if a record cannot be saved;
+already-committed queue intent remains durable.
 
 ## Rollback and lifecycle
 
@@ -121,7 +213,25 @@ unchanged; no RigSpec field is required.
 ## Verification scope
 
 Regression tests exercise rollback/re-upgrade, same-value legacy writes, exact
-retained outcomes, restart without replay, unchanged IDs/bodies, trailing spaces,
-numbered bodies, real-menu refusals and multi-placeholder ownership. Native tests
+retained outcomes, current requests after restart, coalesced queue bodies, trailing
+spaces, numbered bodies, real-menu refusals and multi-placeholder ownership. Native tests
 use private real tmux panes with scripted editable composers. These verify the
 transport mechanics; they are not live Claude/Codex provider sessions.
+
+## Watchdog reminders
+
+A currently due watchdog reminder makes a new delivery attempt, including after an interrupted attempt or job
+accounting. Historical outbox receipts do not suppress a lone reminder or prevent it from joining a digest. The
+message tells its recipient that delivery may repeat after an unconfirmed attempt. Its job history records the
+current transport result; an unknown write is not proof that nothing arrived.
+
+The transport still protects approval/question prompts, human drafts and recipient identity. Scheduler timing,
+current parked-row eligibility and stop checks still apply. This changes message retries, not the idempotence of
+structured continuity actions such as creating a cutover baton.
+
+The parked-owner supervisor also retries current obligations despite an earlier failed, unknown or unrecorded attempt.
+A recorded success to the same known occupant waits for a change in its obligations. Rotation includes retained attempts,
+so a held input cannot starve another owner. Interactive prompts stay with the existing prompt-refusal recovery.
+Its own reminders wait while managed compaction owes the turn boundary, restore or audit, including a fresh check
+at the paste and Enter boundary. A stage that begins after paste leaves an honest partial-input result; OpenRig
+does not erase or replay that text. Peer messages and unrelated reminder policies keep their existing behavior.

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

@@ -137,7 +137,9 @@ part of OpenRig.
 
 ## One channel per rig or seat (optional)
 
-By default every human-bound item posts to the one channel from `rig slack setup --channel`.
+Every ask to a person posts to Slack by default: that's their Slack subscription's `every-ask` preset. A person who wants
+Slack for urgent asks only sets `rig gateway human set <id> slack-subscription urgent-only`: then only an ask marked
+`--alert` posts, and the rest wait on Steering and the TUI. An ask marked `--alert` stands out either way (an interrupt with a mention). By default every post goes to the one channel from `rig slack setup --channel`.
 To follow each rig separately, post a rig's items, or a single seat's, to its own channel:
 
 ```bash
@@ -280,6 +282,7 @@ decisions, and posts its own replies.
   and the machine checks it when it has `OPENRIG_AUTH_BEARER_TOKEN` set.
 - **What the receiving machine trusts:** a relayed event comes from whoever holds that machine's
   daemon token (or, with no token set, anything that can reach its daemon), not from Slack directly, and nothing checks Slack's own signature on it. The
+  credential issued by `rig host pair` is the daemon API bearer, not a relay-only credential; it also authorizes the other daemon write APIs that use that bearer. The
   machine still looks up the sender in its own list of people, but on a relayed event that's no
   proof a person just typed or clicked it in Slack: it trusts the caller for where the event came
   from.
@@ -297,16 +300,44 @@ decisions, and posts its own replies.
   that's down costs one attempt per retry: its other relays wait for the next one. A relay the
   machine keeps refusing is kept and retried with no limit, because dropping it would lose a
   person's message.
+- **Changing forwarding entries is not a drain or cancellation:** relays already retained keep
+  their original host and remain visible in `rig slack status`, even after the last entry is
+  removed. An enabled connector retries them; disabling it pauses retry without deleting them.
+  Let relays finish before removing a forward entry. A zero dead-letter backlog alone does not
+  prove they have drained: it does not count relay HTTP requests still in flight.
 - **Who answered:** every post ends `from <seat> on <machine>`, using the machine's host id (set
   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.
+  Messages that match neither forwarding nor an existing thread or channel route fall back locally
+  to `inboundDestination`; `rig slack status` names that policy and destination. These lists do not
+  establish exclusive channel ownership: two machines can still both handle a 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.
 
+## Quiet hours for a person (optional)
+
+Quiet hours hold a person's routine asks while they're on, and post them once they end.
+
+- **Set them** with `rig gateway human quiet set <entityId> --daily 22:00-07:00` (every day) or `--until 07:00` (from now
+  until then), with `--tz` for the person's zone. `show` reports whether they're on, `end` ends tonight's early ("I'm back";
+  a daily rule stays for tomorrow), and `clear` removes the rule. A person's mode can set them too (`rig gateway human
+  mode save … --quiet`).
+- **While quiet is on,** an ask that would post to the person isn't posted and doesn't mention them, whatever their delivery
+  class: it's held, and its row records the hold.
+- **Not held:** an urgent ask, meaning one tagged `escalation` or `wake-escalation` that isn't an update, and the operator's
+  wake-ladder alerts. These reach the person exactly as they would outside quiet. An ask below the posting level is only
+  logged, as at any time.
+- **When quiet ends,** each held ask that never started posts once, on its own, with no mention. One that no longer applies
+  isn't posted, and its row says why: it closed, a newer notification replaced it, its recipient changed, or it's now below
+  the posting level.
+- **A post that may already be in Slack**, confirmed or only partly sent, isn't held: it finishes as itself, in its own
+  thread.
+- **If quiet hours can't be read,** nothing is posted to that person until they can.
+
 ## Reconnect recovery and status
 
 The daemon scans available top-level messages and replies broadcast with **Also send to
@@ -372,9 +403,27 @@ channel, a thread line (tracked, scanned, waiting and why any are backing off or
 retry time and accepted/dead-lettered recovery counts since the connector last
 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.
+reactions and click answers that await retry, including retained relays, counted across all three
+dead-letter files so the number survives a restart. Retry is paused while the connector is disabled.
+If a file cannot be read, status shows unknown with a reason and no count.
 Human-readable coverage and pending bounds use ISO timestamps; JSON keeps Slack timestamps.
 The status read calls no Slack API and starts no scan. If the daemon cannot be
 observed, local configuration remains visible and live state is unknown. A
 connected socket or valid configuration alone does not prove end-to-end delivery.
+
+### Slack rejects a message with `invalid_blocks`
+
+`rig queue show <qitemId> --json` records the failure as
+`class=slack-invalid-blocks error=invalid_blocks` in the delivery transition.
+Slack rejected that message's blocks, so OpenRig retains the notification as
+undelivered and does not post the same payload again, including after a daemon
+restart. The rejection is tied to the rendered payload: corrected content can
+make a new attempt. Network failures, server errors and rate limits still retry
+as before; a timed-out request remains uncertain until reconciliation.
+
+The source seat gets a `slack-undeliverable` queue item explaining the failure.
+Check the evidence links and message content, then send a corrected ask as a new
+queue item. Close the original when you have handled it. If a long ask was split
+into several messages, earlier parts may already be in Slack; the notice says
+when only part of the ask was posted. A failed part never counts as delivery of
+the whole ask.

package/daemon/docs/reference/stream-classifier-worker.md

@@ -102,6 +102,34 @@ transport or inventory. Failed runs preserve already written output; inspect
 `unavailable`, `remaining`, call count and stop reason rather than treating a file
 as proof of success.
 
+From 0.7.2, `rig project wake --experiment` records its attempts under
+`<classifier-version>+experiment`. `rig stream show` labels its classifications
+`experiment`, not intake's, and its abstentions don't keep an item from the typed
+decisions path below. It still creates no work.
+
+## Typed decisions in the intake turn (`--decide`)
+
+With `decisions.enabled` and the `stream` consumer configured (`rig project decisions
+status`), `rig project wake --decide` takes the same options as a wake and asks a typed
+decision for each eligible item, within the run's call budget. An accepted answer is
+written with the item's classification and becomes owned work (a created or joined queue
+row) or a recorded no-action or duplicate; `rig stream show <id>` shows what became of it.
+Everything else stays with the intake seat: abstentions, errors, a deferral's reason, and
+any item that intake or an earlier version already abstained on (an experiment's
+abstentions excepted). The manual path (`rig project classify`, or a wake with
+`--decisions`) is unchanged and remains the fallback.
+
+**Turning decisions off, or changing them mid-run:**
+- Off means no new provider calls. A run rechecks the settings before every send and halts
+  with `settings_changed`; an answer that arrives after a change is `stale` and isn't applied.
+- Nothing already committed is discarded. Classifications, dispositions and work are kept,
+  and a disposition accepted before the change but not yet applied is still applied:
+  `rig project wake --decide` with decisions off asks nothing, takes the classifier lease
+  and applies those effects (`recovered` in its output).
+- One classifier lease serves every path; an effect is applied only by the lease holder.
+- Old unclassified items are bounded by stream retention (`retention.stream_days`,
+  `retention.stream_max_items`), which keeps items any of these records name.
+
 ## One bounded wake
 
 From the selected occupant, read candidates using the configured project ID:

package/daemon/docs/reference/telemetry.md

@@ -21,6 +21,9 @@ An empty match set can still have more source records: check `page.hasMore` and
 `page.nextCursor`. The cursor binds the stream and filters; retain the same filter
 options when continuing. Do not use `--start` with `--cursor`.
 
+`rig mcp serve` offers the events read as the `rig_telemetry_events` tool, with the
+same parameters and envelope; its `rigId` also takes a rig name.
+
 ## HTTP and envelope
 
 These reads use the daemon's existing browser/access boundary: