@openrig/cli 0.6.10 → 0.6.12

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

@@ -10,8 +10,8 @@ already does it, or two verbs crossed already answer it. **You cannot look up a
 not know exists.** So the point of what follows is not skill. It is recognition: that when a task
 lands, something rhymes, and you go check instead of building.
 
-Eighty-seven top-level verbs ship (capability canon refreshed through
-`capability-delta-v0.6.10`). This marker describes the pack's teaching, not publication or live
+Eighty-eight top-level verbs ship (capability canon refreshed through
+`capability-delta-v0.6.12`). This marker describes the pack's teaching, not publication or live
 adoption. Read this once for shape, and let it make you suspicious that a thing already exists.
 Model-divergence proclamations are live product (trust them; pins use canonical
 model IDs).
@@ -24,7 +24,9 @@ model IDs).
 one command away. Your memory of the fleet is a claim about the past.
 
 - **`rig whoami`** — who you are, who your peers are, and the exact string you use to reach each of
-  them. Ground truth over anything your startup overlay says.
+  them. Ground truth over anything your startup overlay says. With `output.compact` on (off by
+  default), the JSON peer list is bounded to `output.whoami_peers` (default 8), connected peers first;
+  `peersNote` says how many it left out, and `--all-peers` lists them all.
 - **`rig ps`** — what rigs exist. **`rig ps --nodes -A`** — the state of every seat everywhere,
   *including the broken ones*. **The bare form is the question you usually want:** `--active`
   filters to running and **hides detached, exited and attention states** — which are exactly the
@@ -50,6 +52,8 @@ one command away. Your memory of the fleet is a claim about the past.
   `arrangement.source.integration_ref` in `mission.yaml`, and the folded rung checks landed work
   against it; a ref that is invalid or can't be resolved reads INDETERMINATE.
   **`rig view register`** turns a query you keep re-running into a first-class view.
+- **`rig status --json`** — the daemon, kernel, workspace root, rigs and cmux state as one object
+  for a script or an agent; `daemon.reachable: null` means unconfirmed, not down.
 - **`rig config`** — bare, with no arguments: every key, every current value, and where each came
   from. Most agents assume compaction thresholds, snapshot cadence and scan intervals are hardcoded
   daemon behaviour. They are configuration. **Watch one thing:** `source: default` does not mean
@@ -90,20 +94,29 @@ unseen — which makes messages the one delivery channel that never gets skipped
   confirm by effect, never relaunch on it. A send or wake to a seat whose latest hook is a
   question waiting for a person is refused with `target_needs_input`, even when its screen
   can't be read: read it with `rig capture` and get the question answered instead of retrying.
+  `--wait-for-idle N` waits before it takes the seat's delivery lease, so other sends and wakes to
+  that seat aren't held behind it; N is a deadline from the start of the wait.
   Over `--host` to an http-registered host, a send that may have reached the remote reads
   `remote-outcome-unknown` ("Delivery UNCONFIRMED"): check the target with `rig capture <session>
   --host <id>` before any resend. Only a host that was never reached reads as unreachable.
 - **`rig send --raw`** — send exact text or keystrokes without the From/To envelope;
   the interactive-prompt guard still applies. To deliberately drive an interactive prompt,
   **`--dangerously-interact --reason "<why>"`** is the explicit override and implies raw text.
-  Inspect the prompt and establish authority for its effect before using that override.
+  Inspect the prompt and establish authority for its effect before using that override. It types
+  exactly the bytes and keys you give it, in any state: Enter is added only for a complete answer
+  staged in a recognised Claude Code or Codex input box, so anywhere else put CR in the payload.
+  A send to a pane in tmux copy or view mode leaves the mode once and delivers; a pane that can't
+  leave is refused with `pane_in_mode`. With `transport.verify_input_box` on (off by default),
+  `--verify` to Claude Code or Codex reads verified only when the text was seen in the input box
+  and the box was empty after Enter; it only reports.
 - **`rig broadcast`** — one fact to everyone at once, rather than relaying it N times and getting
   the wording wrong on the fourth. **Blast radius is real** — on a large rig this lands in every
   seat's turn.
 - **`rig capture <seat>`** — read what is on their screen right now. **`--rig` / `--pod`** captures
   every seat in one call. `--lines N` is the last N lines (stderr says how many earlier lines were
   cut); `--history-plus-pane` gives the older N history lines plus the whole pane. A short capture
-  doesn't prove a seat is idle.
+  doesn't prove a seat is idle: a capture that cut lines says activity is unknown (`activity:
+  "unknown"` in `--json`), so read `rig ps --nodes` for it.
 - **`rig transcript <seat>`** — what has been *said* in a seat, and **seat-scoped rather than
   session-scoped**: one file spanning every agent generation that has occupied it, so it reaches
   back through handovers. Capped (`transcripts.lines`, default 1000 — raise it for depth), and
@@ -172,27 +185,41 @@ unseen — which makes messages the one delivery channel that never gets skipped
   still can't be posted comes back to the asking seat as a `slack-undeliverable` task. Replies
   sent with “Also send to #channel” reach the seat like any other thread reply. A person's reply
   inside a thread OpenRig opened is answered in that thread: answer with `rig queue create
-  --human-intent update --reply-to <the inbound reply's row>`; a top-level message is answered
-  top-level.
+  --human-intent update --summary "<subject>" --reply-to <the inbound reply's row>`; a top-level message is answered
+  top-level. A person's new message in a rig's own mapped channel reaches that rig's representative,
+  or the seat named with `channel-map set <match> <channel> --inbound <seat>`, and the reached
+  seat's `--reply-to` answer lands in the person's thread; posts name the machine they came from
+  when it has a host name (`host.name`).
+  One Slack app can serve several machines: the machine holding the app-level token relays the
+  channels listed in `forwardChannels` (simulated in one process, not yet run across two real
+  machines). A `botInbox` block delivers named bots' posts in one channel to one seat as rows
+  marked as data from a program, not a person.
 
 ## Making work outlive you
 
 **Your terminal buffer is not a record and your turn is not a container.** A durable row survives
 your context, your compaction and your replacement — and it is the only thing that does.
 
-- **`rig queue create`** — a row with an owner, a body and a transition history. Its reply, like
+- **`rig queue create`** — a row with an owner, a body and a transition history. Give it a `--summary` (its
+  subject wherever it is listed) and, for project work, `project:`/`mission:`/`slice:` tags. Its reply, like
   `handoff`'s, confirms the row was saved; the owner is woken after that. Before you say they were
   told, read the row's transitions, or use `--verify`. For a seat it reports the wake's terminal
   receipt and any claim separately: an unconfirmed receipt is not a failed handoff, and a claim is
-  pickup, not proof the body was read. For a row the seat already claimed, `outcome` can read
-  `indeterminate` while `claim` is accurate: read `claim`. It isn't a failed handoff, so don't
-  re-run the create.
-- **`rig queue show`** — what a row *actually says*. The header is not the body.
+  pickup, not proof the body was read. For a claimed row whose wake wasn't confirmed, `outcome`
+  reads `claimed`; it isn't a failed handoff, so don't re-run the create. For a registered person
+  who is also a seat with a pane, it also waits for the Slack receipt and reports it on its own,
+  up to the 30-second default, even when Slack isn't set up or the row won't be posted. With `output.compact` on (off by default;
+  `rig config set output.compact true`), the queue write commands print a short receipt, `rig queue show` leaves out empty fields,
+  `rig queue transitions` shows the latest five, and `rig whoami --json` bounds its peer list; `--full` (or `--all-peers`) prints
+  everything.
+- **`rig queue show`** — what a row *actually says*. The header is not the body. On a closed row,
+  `--full` adds `closingTransition`: how it ended, who closed it and the closing note.
 - **`rig queue claim` / `unclaim`** — is this mine and running, or still pending where two agents
   might double-work it. Put it down honestly when it is not yours.
 - **`rig queue update`** — record what happened in a form the rest of the system can act on. A
   `--note` does not reopen a terminal row; terminal-to-active repair requires explicit `--reopen`
-  with both `--state` and `--note`.
+  with both `--state` and `--note`. `--summary` on its own corrects a row's subject in any state,
+  and a close with `--resolution "<outcome>"` stores the outcome on the row.
 - **`rig queue handoff`** — pass work so the close and the create are **one transaction**, instead
   of closing yours, failing to create theirs, and stranding the work in between. A standing sweep
   checks recently closed rows (a 24-hour lookback) and flags a `handed_off_to` closure whose
@@ -201,7 +228,10 @@ your context, your compaction and your replacement — and it is the only thing
   visible**, with a plain-language summary and a pointer to what a human must judge; `resolve`
   writes their decision onto the durable record and wakes the owner. **Closing it would be a lie
   and sitting on it silently is indistinguishable from a crash.** `--wake-after <duration>` arms
-  one wake for this park episode; a new park supersedes it and every exit route retires it.
+  one wake for this park episode; a new park supersedes it and every exit route retires it. A wake
+  the typing guard holds back (`retained`) doesn't use the timer up: it's tried again at each
+  interval until an attempt is delivered or fails, and a shared one-shot timer attached with
+  `--wake-watchdog` retires when its last attachment is consumed.
 - **`rig queue overdue`** — what was claimed and never closed in time. **Defaults to the current
   rig**; ask for more if you mean more.
 - **`rig queue undelivered`** — pending create-path nudge failures only. For gateway or human
@@ -261,7 +291,10 @@ relay is a reason to inspect the available routing, not to surrender judgment to
   when release graphs keep being copied or losing stages. The release ceremony and post-release
   boundary remain distinct; no successor is required to finish. Agents judge the evidence.
 - **`rig workflow instantiate`** — start a multi-step, multi-seat run as one governed instance with
-  an entry packet that lands on a real owner.
+  an entry packet that lands on a real owner. `--project`, `--mission`, `--slice` and `--tags`
+  (also on `run`) stamp every packet so the work shows on the slice's Queue tab; an unknown project
+  creates the instance unscoped with a warning. A `preferred_targets` entry written `member@{rig}`
+  addresses whichever rig the instance is bound to with `--rig`.
 - **`rig workflow status`** — which instances need attention, with reason and next action.
   Inspect the exact exception occurrence and packet: resolved overdue work is reconciled without
   closing an overdue sibling. Registered-human fallback reports missing or ambiguous selection
@@ -359,20 +392,40 @@ not have to tear one down to change it, and you rarely have to start from nothin
   is archived), so check `rig ps --nodes` first. Launch-created `AGENTS.md` or `CLAUDE` files now show in `git status`.
   `rig up <rig> --existing` puts back the OpenRig guidance blocks `rig down` removed before a
   resumed seat starts. A seat still missing one makes the rig `partially_restored` (its node lists
-  `guidanceGaps`) and `rig up` exits 1.
+  `guidanceGaps`) and `rig up` exits 1. A seat that wasn't running at the snapshot, but whose
+  earlier session left a resume token, stops at `awaiting-decision` instead of starting fresh, in
+  `rig up --existing` and in `rig launch` (exit 1); the message names the command that starts it
+  fresh on purpose. In a pod-aware rig, a seat is rolled back as unresumable only when its runtime
+  reports the conversation missing. An ordinary terminal seat relaunches fresh on restore and
+  re-runs its startup actions; a seat whose current runtime differs from its snapshot's is stopped
+  before launch; and a Claude seat slow to draw its screen ends `attention_required` with its pane
+  kept, not failed. An `env:` block on the rig or a member in `rig.yaml` reaches every seat and
+  carries into restores and handovers, and `rig up <spec> --env KEY=VALUE` adds one for a single
+  launch; the values aren't secret (they're stored and exported).
+- **`rig community-harness list`**: list installed community-harness presets and declared limits
+  (not tested by OpenRig; launch-only).
 - **`rig down`** — stop a rig's seats and take it out of the running set. It ends the agents'
   sessions and any work in progress; don't run it on a live team unless the person asked. In
   human mode it first prints one line with each agent's last known activity, or “unknown”: a
   best-effort snapshot, not a record of what was interrupted. With `--host`, a remote teardown
   that reports errors exits 2.
-- **`rig launch <rigId> [seat]`** — one seat is down; start just that one, without disturbing the
-  rest. It takes the rig ID from `rig ps --json`; a rig name gives `rig_not_found`. Add `--plan` to preview it first, locally or with `--host`; a plan is never sent to a
+- **`rig launch <rig> [seat]`** — one seat is down; start just that one, without disturbing the
+  rest. It takes the rig's name or ID; a name shared by more than one active rig stops and lists their IDs. Add `--plan` to preview it first, locally or with `--host`; a plan is never sent to a
   daemon older than 0.5.9, which would ignore it and launch. A seat whose agent exited to a shell in
   its kept pane reads `attention_required` (exit 1), not already running: resume it, or
   `rig seat launch <session> --fresh --stop`.
 - **`rig seat launch <seat> --fresh --reason <why>`** — deliberately create a blank occupant for
   exactly one existing seat. It uses no resume, fork, rebuild, snapshot, or restore packet;
-  siblings and durable work stay put, and unmanaged ambiguity refuses.
+  siblings and durable work stay put, and unmanaged ambiguity refuses. With `--stop`, a seat with a
+  still-live older session is refused before anything is stopped; `--plan` previews it.
+- **`rig seat restart <seat> --keep-conversation --reason <why>`** — restart one Codex seat in its
+  own pane on the same conversation, so it starts again on whatever account its Codex home now
+  holds; it doesn't switch accounts itself. It refuses with nothing stopped unless the seat is a
+  Codex seat OpenRig launched, in a single pane, with a conversation it can prove and unchanged
+  running settings. `--plan` runs every check and stops nothing; `--verify --expect-account
+  <account>` reports `moved` only when a tool turn has completed in the same conversation since
+  the restart and Codex's status names that account. Linux only: on macOS a
+  request that reaches the running-process check refuses before stopping the seat.
 - **`rig add`** / **`rig expand`** — graft one more member, or a whole new pod, onto a rig that is
   already running. `rig add` takes the rig's name or ID; a name two active rigs share is refused
   with `rig_ambiguous` and the candidates. `rig grow --new-pod` and `rig expand` are one ingress; choose by input shape.
@@ -408,7 +461,9 @@ version, from checking the environment to a useful report to the OpenRig team.
 
 - **`rig start`** — the box rebooted and everything is gone: bring the whole topology back in one
   move, rather than hand-restoring rig by rig. Selected-rig recovery now demands positive runtime
-  evidence and refuses stale identity by name rather than substituting an occupant.
+  evidence and refuses stale identity by name rather than substituting an occupant. `--last`
+  leaves down a rig you stopped on purpose (`rig down` or `rig seat stop`) and prints how to bring
+  it back (`rig start --rigs <rig>`, or `rig up '<name>' --existing`).
 - **`rig daemon start` / `stop` / `status` / `logs`** — startup reserves the local instance and
   verifies its own child on required listeners. Inspect a retained reservation before retrying.
   Stop distinguishes process/listener exit from a clean asynchronous drain: inspect the matching
@@ -476,11 +531,14 @@ version, from checking the environment to a useful report to the OpenRig team.
 - **`rig seat continue <seat>`** — a launch stopped on Claude's bypass-permissions consent dialog.
   After the person accepts it in the pane, this delivers the pending startup text into the same
   conversation without relaunching; `rig up` and `rig bundle install` name it when startup pauses.
+  It also delivers a Codex fork's pending startup context once, after the forked conversation's
+  ID is verified.
   Managed Codex launches turn off Codex's startup update check, so no update notice stops them;
   updating Codex is the operator's job.
 - **`rig seat set-model` / `stop` / `clean`** — persist the model for later managed resumes, stop
   exactly one live seat (ending its session and any work in progress), or clear a dead seat's
-  stale binding. When the topology is right and only
+  stale binding. A stop is recorded, so the rig doesn't read `degraded` for that seat, and a rig
+  whose seats were all stopped this way reads `stopped`. When the topology is right and only
   the occupant is wrong, use these seat lifecycle verbs or `rig handover`, not a rig down/up cycle.
   Effective-model detection follows the identity-verified current occupant, not a retained
   predecessor; a `<synthetic>` transcript record is skipped, so a PENDING model check is not a
@@ -489,10 +547,18 @@ version, from checking the environment to a useful report to the OpenRig team.
   permission mode for its future managed launches; it relaunches nothing, and `inherit` clears the
   selection. `rig seat status` reports the selection, but a status read does not prove the
   running process enforces it.
-- **`rig seat set-typing-guard <seat> --enabled true|false --reason <text>`** — protect a human's
-  draft in that seat: automatic input is retained instead of typed while the guard is on.
+- **`rig seat set-effort <seat> --effort <level> --reason <text>`** (or `--clear`) — save one seat's
+  reasoning effort for its next launch, restore, handover or in-place Codex restart without
+  touching its spec or its peers; nothing restarts. **`rig seat effort <seat>`** reports what was
+  requested, what's saved, what the running process was launched with and what the session
+  recorded (NOT VERIFIED until the seat takes a turn).
+- **`rig seat set-typing-guard <seat> --mode off|draft-aware|hold --reason <text>`** — choose
+  ordinary automatic delivery, immediate retention when input is busy/unreadable, or holding all automatic
+  input. `--enabled true|false` remains compatible: true selects hold, false selects off.
+  `rig seat status` shows the requested/effective mode; wait for pending activation to finish.
   **`rig seat held-messages`** lists what was retained and **`rig seat retire-held-message`**
-  retires one; disabling the guard does not replay held messages.
+  retires one; changing mode does not replay old held messages. Draft-aware returns the exact
+  refusal and original ID immediately; callers decide further action, with no daemon retry timer.
 - **`rig compact-plan`** → **`rig compact`** — who is near the context wall, then act on it.
   **Ordering matters: running `compact` without the plan is guessing which seat needed it.**
   Managed compaction waits for the seat's restore map before compacting; `rig compact --state`,
@@ -501,7 +567,11 @@ version, from checking the environment to a useful report to the OpenRig team.
   managed compaction, refocus waits for the restore request, which names the `refocusing` skill
   (the daemon installs it globally); three failed refocus attempts in a row for one occupant post
   one issue to the stream. The turn boundary, restore request and read-depth audit reach a seat
-  that stays quiet after `/compact`; they don't wait for its next turn.
+  that stays quiet after `/compact`; they don't wait for its next turn. The managed `/compact` is
+  kept short enough to run as a command and is sent only to an idle seat; its own result reads
+  `submitted, unconfirmed` (it reached the seat, not proof compaction ran), `uncertain` (not
+  replayed) or `not sent`, so confirm by effect. Claude seats that select `openrig-core` load its
+  hooks; a seat can give a slow refocus more time with `OPENRIG_REFOCUS_BUDGET_MS` (4500 to 52000).
 - **Know what compaction costs before you reach for it.** On some runtimes what comes back has
   enough context left to believe it knows everything and not enough to actually know anything — and
   **the compacted agent is the only one who knows it happened**, while every other seat keeps
@@ -568,7 +638,8 @@ scheme, and nothing downstream can see it.
   source actually bound. When someone later asks where the contract items came from, the drop's
   own echo is the answer — not a re-read of the files.
 - **`rig proof judge` / `rig proof show`** — record an attributed judgment on a contract item once,
-  then read derived proof, slice, mission and project readiness. The owning scope selects
+  then read derived proof, slice, mission and project readiness. Both take `--project <id>` or a
+  `<project>:` scope prefix. The owning scope selects
   `proofPolicy.judges` (nearest slice, mission or project policy wins); consult `rig proof --help`
   for that setup and the item/evidence selectors. Accept, reject or withdraw against readable
   evidence; corrections preserve history and unrelated judgments without ancestor status edits.
@@ -674,7 +745,11 @@ working arrangement becomes something someone else can instantiate.
   own install folder first copies each differing file to a backup. A legacy bundle doesn't replace
   a stopped team, and with `--force` it can run its approved install steps before its name check
   fails. Read those choices before reaching for `--force`. The manifest safety check always runs,
-  even with `--skip-version-check --force`.
+  even with `--skip-version-check --force`. `rig bundle create` refuses a harness login file
+  (`.claude/.credentials.json`, `.codex/auth.json`, `.pi/agent/auth.json`); `--include-login-files`
+  includes one only when recipients should have it and its owner agrees, and records it. With
+  `bundle.services_enabled` on (off by default), a bundle carries its declared Compose file and
+  installs into a lasting `--target`.
 - **`rig bundle check <folder>`** — a local, advisory check of a team you are authoring; each
   finding names its file. `rig bundle create` and `rig up <link>` name the bundle after
   `rig.yaml`'s `name`.
@@ -739,7 +814,10 @@ your circumstances is configuration, and the ones that are not, another agent ca
 - **`rig policy permissions list` / `show` / `current` / `apply`** — what permission policy is
   actually in effect: discovers custom policy specs, validates refs (malformed can never read as
   valid OR absent), shows what would apply. The older `rig policy list|show|current|apply` forms
-  remain as aliases with the same output.
+  remain as aliases with the same output. `rig policy apply <policy> --seat <seat> --reason
+  "<why>"` changes an existing seat's stored policy for its next restore, resume or launch without
+  re-creating it; the running agent and the spec don't change, and `rig policy current` and plain
+  `rig ps` don't show the stored override (`rig seat status` does).
 - **What a team seat may do without asking.** Claude seats in a team that OpenRig launches run
   `rig` commands, project reads and common test commands without a prompt; lifecycle commands
   (`rig up`, `rig down`, `rig seat stop`, `rig daemon stop` and similar) ask. Routine `rig`
@@ -771,8 +849,8 @@ your circumstances is configuration, and the ones that are not, another agent ca
   `launch.non_interruptive`. The before-install view shows it as
   `posture[].nonInterruptiveDefault`.
 - **Smaller settings worth knowing:** per-seat `effort`, passed to Claude as `--effort` and to
-  Codex as `model_reasoning_effort`; and `runtime.readiness_timeout_seconds` for seats that start
-  slowly.
+  Codex as `model_reasoning_effort` (`rig seat set-effort` overrides it for one seat); and
+  `runtime.readiness_timeout_seconds` for seats that start slowly.
 - **`rig policy cite` / `defaults`** — what posture the operator is in: how autonomous to be, how
   loudly to report, whether to batch permission questions or block on them. **This declares a
   posture; it does not grant or deny permissions** — the harness's own settings are the control
@@ -787,16 +865,23 @@ your circumstances is configuration, and the ones that are not, another agent ca
   See `docs/reference/scoped-operating-posture.md` for precedence and other scopes.
 - **Project World declares the human authority boundary.** Read the current project and mission
   policy for actions requiring approval; the system mechanics do not impose a universal list.
-  A script's explicit-path authoring guard (for example `OPENRIG_SKILL_CANON_ROOT`) asks for a
-  missing source path and does not itself create a permission gate.
 - **`rig auth list` / `validate` / `seats`** — is this seat's runtime actually logged in, which
   accounts exist, and which account each seat is *supposed* to be on.
 - **`rig provider accounts` / `bindings` / `signals` / `switch`** — which seats are bound to which
   accounts, what the usage signals say, and whether a seat can be moved without stranding the
   conversation it is in the middle of. **`provider signals` reports anomalies rather than a
   listing** — unbound seats, accounts shared across several seats. A Codex seat showing its
-  usage-limit banner reads activity `unknown` with reason `usage_limit`, and `provider signals` can
-  show a provider-event signal for that seat's account that allows a switch decision.
+  usage-limit banner reads activity `unknown` with reason `usage_limit`, and keeps it while its
+  screen redraws; `provider signals` can show a provider-event signal for that seat's account that
+  allows a switch decision. With `provider.usage_windows` on (off by default), `rig provider status`
+  shows Codex's windows and Claude's 5-hour and weekly windows from the seats' status lines, each
+  seat's configured account, and with `--all-hosts` or `--hosts <ids>` every registered machine's
+  windows, listed once per allowance and never added up; `--refresh` (optionally `--provider
+  codex|claude`) reads the logins now. A Claude account's current availability reads `unknown`,
+  because nothing links a seat's reading to the login it used: read each window as that seat's
+  reading, and don't tell a person an account has room from it. With `provider.subscription_moves`
+  on (off by default), `rig provider moves` records and lists moves of a Codex home's seats between
+  subscriptions.
 - **Codex configuration fragments** — a `codex_config_fragment` must open with a table header and
   never overrides a user-declared table; see `docs/reference/agent-spec.md`.
 - **`rig env`** — the real services behind a rig: are they up, what are they saying, how do you
@@ -808,6 +893,11 @@ your circumstances is configuration, and the ones that are not, another agent ca
   `both` sets which harnesses it installs and checks; one not chosen reads `skipped`, never failed.
 - **`rig usage series`** — what a seat's token curve has looked like over time: climbing steadily,
   reset, or stopped reporting entirely. The last one is a signal, not a gap.
+- **`rig usage cost [--seat <session>]`** — what each seat's harness reports it costs, beside its
+  tokens: Claude's own client-side estimate (not an invoice) and Codex's tokens with a note that it
+  reports no cost. A missing figure reads missing, never $0, and no setting gates it. With
+  `usage.pi_cost_facts` and `usage.pi_openrouter_charge` on (both off by default), Pi's estimate and
+  OpenRouter's actual charge show beside each other, never added together.
 - **`rig tui`** — the interactive view over rigs, pods, seats and specs. `rig` and `rig tui` open
   the status dashboard, not a conversation with an agent: talk to the operator through
   `rig terminal open saved:kernel --window`, which opens the dashboard and conversations together.
@@ -834,7 +924,8 @@ your circumstances is configuration, and the ones that are not, another agent ca
   missing, denied, binary, truncated and missing-heading results stay explicit. HTTP(S) links
   show a selectable destination without opening a browser; `v` enables terminal text selection.
   Tab completes commands and snapshot arguments; Recent opens original events. **System** opens
-  to instance **Health**, with **Configuration** and **Connections** beneath it. Contextual Health
+  to instance **Health**, with **Configuration**, **Connections**, **Usage**, **Usage · all hosts**
+  and **Cost** beneath it (the last three are read-only and start no lookup). Contextual Health
   remains available in the owning rig or agent view. **Configuration** browses instance/work
   roots, context, display, waiting, recovery, activity and advanced settings;
   Slack and people are one category. Select a category, use right/left to change panes,
@@ -852,7 +943,10 @@ your circumstances is configuration, and the ones that are not, another agent ca
   behaviour from the web UI. The TUI plus Slack are the human surface; the CLI plus terminal are the agent surface.
 - **`rig mcp serve`** — how an agent that speaks MCP rather than shell drives OpenRig, and which
   operations are exposed that way. Relevant the moment a tool you are integrating cannot run a
-  shell command.
+  shell command. Five queue tools (`rig_queue_create`, `rig_queue_show`, `rig_queue_list`,
+  `rig_queue_claim`, `rig_queue_update`) act as the seat named by `OPENRIG_SESSION_NAME`, so an
+  agent with no shell can hand work to the team and read the closing note as its answer. Nothing
+  wakes such an agent; it sees new work when it checks.
 - **`rig skill loadout --runtime <claude-code|codex>`** — inspect the exact catalog revision,
   selectors, target, and current/missing/shadowed/conflicting state for one working directory.
   `--apply` writes only the managed ownership set, is idempotent, and refuses local edits or
@@ -930,6 +1024,6 @@ deliberate writing.
 
 **`rig --help`**, then `rig <verb> --help`.
 
-Eighty-seven verbs ship, and this page named most of them once. **You will not remember which — you
+Eighty-eight verbs ship, and this page named most of them once. **You will not remember which — you
 are meant to remember only that the list is long enough to be worth reading before you build
 anything.** The question is never *how do I write this*; it is **does this already exist**.

package/daemon/context-packs/reference/getting-started.md

@@ -27,6 +27,10 @@ supports, though OpenRig's automated tests don't run on it yet. One user's
 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,18 +102,32 @@ 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.12/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.12/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
@@ -306,6 +324,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
@@ -589,6 +608,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 +903,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 +946,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/context-packs/reference/manifest.yaml

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

package/daemon/context-packs/reference/rig-spec.md

@@ -179,6 +179,7 @@ edges:
 | `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. |
 | `permission_policy` | string | no | — | Permission policy attached to the rig. Either a built-in (`builtin:locked`, `builtin:standard`, `builtin:open`, `builtin:yolo`, `builtin:auto`) or a safe relative path to a custom policy file (resolved from this spec's directory; no `..`, no absolute, no empty segments, each segment `[A-Za-z0-9][A-Za-z0-9._-]*`), or `none`, a recorded choice of the floor. Absent uses the default floor with the scoped team launch allowances described below. A bare built-in name such as `yolo` is refused ("use 'builtin:yolo'"), and so is an explicit `null`. A custom file that is missing, unreadable or invalid isn't a validation error: it resolves to the floor, and preflight warns. A member may set its own `permission_policy` (not on a terminal member), which takes precedence over the rig-level one; there is no pod level. See "Attaching a permission policy" below. |
+| `env` | map | no | — | Launch environment for every seat in the rig: `NAME: value` pairs. A member's own `env` overrides it name by name. Names match `^[A-Z_][A-Z0-9_]*$`, names starting `OPENRIG_` are reserved, and values must be non-empty strings (quote numbers and booleans). Values are not secret. See "Launch environment" below. |
 | `managed_blocks` | map | no | `CLAUDE.md` | File that receives OpenRig's managed instruction blocks for Claude Code members. Only the `claude-code` key is accepted, with `CLAUDE.md` or `CLAUDE.local.md`. Codex, Pi and OMP members use `AGENTS.md`. See "Choosing the Claude instruction file" below. |
 | `workspace` | object | no | — | The rig's workspace: `workspace_root` (required), `repos[]` of `{name, path, kind}` with `kind` one of `user`, `project`, `knowledge`, `lab` or `delivery` and unique names, an optional `default_repo` naming one of them, and an optional `knowledge_root`. Relative repo paths resolve against `workspace_root`. |
 | `docs` | Doc[] | no | — | Documentation files that should travel with the rig. Included in rig bundles. Each entry has a `path` field (safe relative path). The engine does not consume these — they are for humans and agents setting up the environment before launch. |
@@ -334,6 +335,44 @@ context for `rig seat continue`; `rig up --non-interruptive` or `rig bundle inst
 except inside a recognized sandbox. See Claude Code's
 [Choose a permission mode](https://code.claude.com/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode).
 
+### Launch environment
+
+`env:` sets environment variables for the seats of a rig, so a team can share a setting such as a feature flag, a region or a log level without every member hand-editing a shell profile. Declare it on the rig, on a member, or both:
+
+```yaml
+env:
+  LOG_LEVEL: info
+  REGION: eu
+pods:
+  - id: dev
+    members:
+      - id: impl
+        runtime: claude-code
+        env:
+          LOG_LEVEL: debug   # overrides the rig's value for this seat only
+```
+
+- 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.
+- 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.
+
+**Where the declared names reach, by runtime.** Declared values are handed to the seat's terminal as tmux environment, so most seats take them as given:
+
+- Plain Claude Code (no permission mode selected), Codex and terminal seats take a spec `HOME`, `PATH` or `CLAUDE_CONFIG_DIR` as given.
+- The cleared environment (`env -i`) belongs only to a managed Claude launch, which is the one used when a permission mode is selected for the seat (for example `permission_policy: builtin:auto`). It forwards the declared names through the cleared environment, except `PATH`, `HOME` and `CLAUDE_CONFIG_DIR`, which OpenRig sets for that launch itself, and `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN`, for which it sets its own renderer setting. A spec value for any of those four is not forwarded. A seat that selected the shipped `openrig-core` plugin also has `CLAUDE_CODE_PLUGIN_DIRS` (the vendored plugin, added after a list the seat declares itself) among its declared names, so it is forwarded like the others and the plugin's hooks load in a seat with a permission mode as in one without; a seat that didn't select the plugin has no such name added.
+- Codex seats run OpenRig's own Codex executable whatever a spec `PATH` says, and use the daemon's `CODEX_HOME` when the daemon has one.
+- On Pi and OMP seats the values reach the terminal. The agent process gets only what the runner passes on, so a spec or one-off value reaches it only for the names the runner always passes: `PATH`, `HOME`, `USER`, `LOGNAME`, `TERM`, `LANG`, `LC_ALL`, `SHELL` and `TMPDIR`. Pi's agent process receives the runner's `HOME`, so a spec or one-off `HOME` value that reaches the runner is passed to Pi; OMP's agent process gets its seat state directory (`$OPENRIG_HOME/state/omp/<seat>`, see Oh My Pi below) as `HOME`, so a `HOME` value does not reach it. The selected provider's variables are passed separately, as described under each runtime.
+
+**Do not put secrets in `env:` or `--env`.** The values are not secret, and nothing here encrypts or hides them (see #306):
+
+- Spec values are stored in OpenRig's database and in rig snapshots, and `rig export` and bundles copy them, so a secret put there by mistake travels with the rig.
+- While a seat launches, the values are passed to tmux as command arguments, so other users and processes on the same machine can see them for that time. They then sit in the seat's process environment. Only the managed Claude launch command is value-free: it forwards names, and the terminal supplies the values.
+- A one-off `--env` value is not stored in the database or in snapshots, but it reaches tmux the same way, so it is visible in the same ways while that launch runs.
+
+Use `env:` for settings only. Credentials belong in the provider's own login or a secret store the seat reads at run time.
+
 ### Choosing the Claude instruction file
 
 OpenRig writes its instructions for Claude Code members into managed blocks in
@@ -397,16 +436,17 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 | `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
 | `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
 | `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `pi`, `omp`, `terminal`, `stub`. `stub` is a deterministic test harness, not an agent: a Node runner in the seat's tmux pane goes through the normal launch, skill projection, startup-file and readiness path, follows `<cwd>/.openrig/stub/script.json` when present, and calls no model. See "What a stub can and cannot prove" in `docs/as-built/test-layers.md`. |
-| `cwd` | string | yes | — | Working directory for the agent. A relative path resolves against the rig root (the directory containing the rig spec); an absolute path is used as is. Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. A cwd inside the OpenRig installation fails preflight unless `--cwd` is given. |
+| `cwd` | string | yes | — | Working directory for the agent. A relative path resolves against the rig root (the directory containing the rig spec). If that path exists as written, it is used. Otherwise a leading `~` or `~/` expands to the home directory (`~user` does not) and `$VAR` / `${VAR}` expand from the daemon host's environment; a relative result still resolves against the rig root. A reference to an unset variable stays as written, so the cwd is that literal path and works only if it exists. Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. A cwd inside the OpenRig installation fails preflight unless `--cwd` is given. |
 | `label` | string | no | — | Human-readable member name. Shown in UI when present. |
 | `model` | string | no | — | Model override. Runtime-specific (e.g., `claude-opus-4-6` for Claude Code). |
 | `effort` | string | no | — | Reasoning effort override, trimmed. A non-string value is ignored with an advisory. |
 | `permission_policy` | string | no | — | Member-level permission policy; overrides the rig's. Not valid on terminal members. |
+| `env` | map | no | — | Launch environment for this seat, laid over the rig's `env`. Same rules as the rig-level field. Valid on terminal members too. See "Launch environment" below. |
 | `role` | string | no | — | The seat's role, letters, digits, `_`, `.` and `-`. Not valid on terminal members. |
 | `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. |
+| `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). |
 | `mechanic` | string | no | — | A canonical `seat@rig` session address, for `apprentice-handover`. |
-| `session_source` | object | no | — | Start the seat from an existing session: `fork` with `native_id`, `rebuild` with `artifact_set`, or `agent_image` with `image_name`. Not valid on terminal members. |
+| `session_source` | object | no | — | Start the seat from an existing session: `fork` with `native_id`, `rebuild` with `artifact_set`, or `agent_image` with `image_name`. A Claude Code `fork` needs Claude Code 2.0.73 or later. Not valid on terminal members. |
 | `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. |
 
@@ -415,6 +455,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 `runtime: pi` launches the Pi coding agent (`pi --mode rpc`) through OpenRig's RPC runner.
 
 - **State:** Each seat uses `$OPENRIG_HOME/state/pi/<session>/agent` as its Pi agent directory, with `sessions/` beside it, instead of your default `~/.pi/agent`. The runner sets `PI_CODING_AGENT_DIR` to that directory. `<session>` is the seat's session name, unchanged; for a pod member it is `{podId}-{memberId}@{rigName}`. `$OPENRIG_HOME` defaults to `~/.openrig`. OpenRig creates these directories at launch and does not copy anything from `~/.pi/agent`.
+- **Thinking level:** OpenRig does not pass a node's `effort` to Pi. To set Pi's thinking level, add it to the model as a suffix, for example `model: openrouter/x-ai/grok-4:high`. Pi accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`. Pi first looks for a model whose id is the whole pin, and uses it when there is one, suffix included. Only when there is none does Pi read the suffix as the level and record the model without it. Any other suffix, such as OpenRouter's `:free`, stays part of the model id. The model-divergence check reads the pin literally when the seat's `models.json` defines a model with that exact id; otherwise it accepts the model with or without the suffix. If the seat's `models.json` can't be read, a pin with a suffix stays unchecked, with the usual warning, when the recorded model matches the whole pin or the pin without its suffix. A record that matches neither is reported.
 - **Custom models:** Pi reads `models.json` from its agent directory, so a seat reads `$OPENRIG_HOME/state/pi/<session>/agent/models.json`, not `~/.pi/agent/models.json`. Custom provider and model definitions for a seat go in that file. A seat that uses only providers Pi already includes does not need one. OpenRig does not create or write `models.json`.
 - **Credentials:** The Pi process receives only `PATH`, `HOME`, `USER`, `LOGNAME`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY`, `KIMI_API_KEY` or `MINIMAX_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>`, `kimi-coding/<id>` or `minimax/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
 
@@ -440,6 +481,8 @@ profile: none
 
 All three must be present together. Any partial combination is a validation error.
 
+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.
+
 ### agent_ref Rules
 
 - Must start with `local:` or `path:`
@@ -588,8 +631,26 @@ The harness readiness window defaults to 30 seconds. On a loaded machine, set
 `rig config set runtime.readiness_timeout_seconds 60` to give new seats and
 handover successors longer to become interactive. The setting accepts 1–600
 seconds, applies to the next launch without a daemon restart, and can also be
-set with `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`. It does not change the
-time spent by the runtime adapter before readiness polling starts.
+set with `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`. It also bounds how long a
+restore keeps watching a Claude seat whose resume is still starting, so raising
+it for slow fresh launches lengthens that wait too. The wait is about the
+setting in total per seat, counting the usual 3.2-second check: the adapter polls
+for the rest of it (nominally: it counts polls, and each poll's tmux and process
+reads add a little). A restore
+starts seats one after another, so each seat that never starts Claude adds up to
+about this much, minus the 3.2 seconds, to the restore; the time adds up seat by
+seat, and a longer setting means a longer wait before a stuck seat is reported.
+A seat that is still not interactive then ends `attention_required` with its
+launch and resume token kept, and the later readiness wait is skipped for it.
+That holds at every setting: at 1–3 seconds there are no extra polls, but an
+unresolved boot is still kept rather than failed. A pane that shows a Codex or
+another conversation's Claude is not waited for. `rig up` and
+`rig launch` wait 120 seconds for the daemon, so a restore of several stuck
+seats can pass that (in one measurement, about 31 seconds a seat at the
+default, 95 for three). A client timeout and exit code 1 do not mean the
+restore was rolled back or that it should be run again; check the real state
+first with `rig ps`. Apart from this, the setting does not change the time
+spent by the runtime adapter before readiness polling starts.
 
 ---