@openrig/cli 0.7.0 → 0.7.1

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:
@@ -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

@@ -12,11 +12,82 @@ daemon-owned retry scheduler. Sibling seats keep their own mode.
 | `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.
 

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

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:

package/daemon/docs/reference/terminal-sessions.md

@@ -0,0 +1,90 @@
+# Choose a Herdr session for a terminal view
+
+Use `--session <name>` to open a view in a named Herdr session on the daemon's
+host. For example, keep development and production rigs in separate sessions:
+
+```sh
+rig terminal open future-rig --provider herdr --session default --json
+rig terminal open future-prod-rig --provider herdr --session future-prod --json
+rig terminal status --provider herdr --session future-prod --json
+```
+
+The explicit provider form places the view in the existing Herdr session
+without opening a desktop window. Use Herdr's own session management to prepare
+the session. An unavailable selected session returns `herdr_unavailable`; it
+does not redirect the view to a different session.
+
+The `session` field in an open result confirms the requested selection. Status
+also names the session and returns its resolved control socket in `status.launch`.
+Session names are a single non-empty name, such as `future-prod`, rather than a
+socket path. `--session default` explicitly selects Herdr's default session.
+
+## Default selection and scope
+
+When Herdr is selected with no `--session`, the daemon uses the endpoint selected when it started:
+its `HERDR_SOCKET_PATH`, then its `HERDR_SESSION`, then the default endpoint.
+Setting either variable only on a later `rig terminal open` command does not
+change that daemon configuration. Pass `--session` for a per-command selection.
+
+With neither a provider nor a session, the daemon's open and preview APIs try
+a live Herdr first, then a live cmux. An explicit session always selects Herdr
+and skips that fallback, including when the daemon's default Herdr endpoint is down.
+
+An explicit session resolves under the daemon user's Herdr session directory;
+it takes precedence over that daemon's default socket override. The selection
+belongs to the request. Saved views still describe membership and layout, so
+pass `--session` again when reopening the view in that session.
+
+The existing view rules apply: saved views, rig and pod views, read-only mission
+and slice views, pagination, absent seats and partial results all use the same
+composer. Selecting a session changes where those tiles are placed. It does
+not relaunch the seats' tmux sessions or move queue ownership.
+
+## Desktop windows and previews
+
+```sh
+rig terminal open future-prod-rig --session future-prod --window --json
+```
+
+The window launcher, readiness checks, workspace inventory, reuse and layout
+application use the selected endpoint. When launched inside Herdr, the current
+Herdr endpoint must match that selection to reuse the current terminal. To
+place a view in another existing session from such a caller, use the explicit
+`--provider herdr` form without `--window`.
+
+An endpoint-mismatch error also gives a command for the caller's own session,
+such as `rig terminal open future-rig --session work`. Previously it only
+explained how to place the view in the daemon's selected session. The caller's
+name comes from the same resolved socket path used by the endpoint check:
+`~/.config/herdr/sessions/<name>/herdr.sock`, or `default` for
+`~/.config/herdr/herdr.sock`. An explicit `HERDR_SOCKET_PATH` takes precedence
+over `HERDR_SESSION` for both the check and the suggestion. Other custom socket
+paths keep the existing guidance without guessing a session name, even when
+`HERDR_SESSION` is set. Reporting the mismatch opens nothing.
+
+Previews include the selected session in their fingerprint. A preview from one
+session cannot authorize an open in another; refresh the preview after changing
+the selection. The CLI asks the daemon to confirm named-session support before
+requesting an open, so an older daemon cannot silently ignore the option and
+write into its default session. An unconfirmed reply after an open is reported
+as an unknown outcome; inspect the selected session before retrying.
+
+`--session` applies to Herdr. A named session does not fall back to plain tmux
+when Herdr is absent, and combining a session with cmux is rejected. Existing
+workspaces are kept during reuse checks. Any suggested cleanup command for a
+stale named-session workspace includes the selected socket.
+
+## HTTP API
+
+- `POST /api/terminal/open`: `{ view, provider?: "herdr", session?: string, expectedPlan?: string }`.
+- `GET /api/terminal/preview?view=<view>&provider=herdr&session=<name>`.
+- `GET /api/terminal/status?provider=herdr&session=<name>`.
+- The alias `POST /api/rigs/:rigId/terminal/open` accepts the same session and
+  preview binding, with the rig determining the view.
+
+Malformed names and unsupported provider/session combinations return HTTP 400
+before socket calls. A changed preview returns HTTP 409. An unavailable Herdr
+session keeps the normal HTTP 200 provider result with `ok: false`, its selected
+`session`, an error code and direct-attach guidance.
+The `kernel_seats_unavailable` result also keeps the selected session, so the CLI
+reports that known failure instead of replacing it with an unconfirmed-session error.

package/daemon/docs/reference/topology-naming.md

@@ -29,7 +29,7 @@ What a seat runs has its own words:
 | --- | --- | --- |
 | Runtime | What a seat runs: a harness, a terminal, or the stub (a scripted stand-in used in tests). It's the rig spec's `runtime` field and the TUI's runtime column | `claude-code`, `codex`, `terminal` |
 | Harness | The agent software around a model | Claude Code, Codex, Pi |
-| Community harness | A harness an outside contributor maintains. It's installed as a preset under `$OPENRIG_HOME/community-harnesses/`, listed by `rig community-harness list`, and OpenRig doesn't test it | A preset's name in a member's `runtime` |
+| Community harness | A harness an outside contributor maintains. It's installed as a preset under `$OPENRIG_HOME/community-harnesses/` ([format](community-harness-presets.md)), listed by `rig community-harness list`, and OpenRig doesn't test it | A preset's name in a member's `runtime` |
 | Terminal | A seat with no agent: a shell for infrastructure processes | `runtime: terminal` |
 
 ## How the software teams grow