@openrig/cli 0.6.11 → 0.6.13

package/daemon/assets/skills/rigs/SKILL.md

@@ -15,17 +15,26 @@ building it yourself.
 
 Tell the person what you're about to run and why before you run it. Don't install system packages or change their
 machine without a yes. Starting OpenRig and a team writes files: Codex hooks and settings in
-`~/.codex/config.toml`, a discovery skill in `~/.claude/skills` and `~/.agents/skills`, and, in the repository, managed
-guidance in `AGENTS.md` or `CLAUDE.md` plus the team's skills and plugins. Say so before you start OpenRig
-([the full list](https://github.com/mvschwarz/openrig#what-openrig-changes-on-your-machine)).
+`~/.codex/config.toml`, Claude Code workspace trust in `~/.claude.json`, discovery skills in `~/.claude/skills` and
+`~/.agents/skills`, and, in the repository, managed guidance in `AGENTS.md` or `CLAUDE.md`, activity hooks in
+`.claude/settings.local.json` and a status line there unless the project already has its own, plus the team's skills
+and plugins. Unless a permission policy, a per-seat choice or (for Codex) a named profile applies, the kernel's own
+seats run with an operational default: Codex with `-s danger-full-access -a never`, and Claude Code with its file
+tools, web fetches and operational commands, including reads under the home folder, allowed without asking. Say so
+before you start OpenRig ([the full list](https://github.com/mvschwarz/openrig#what-openrig-changes-on-your-machine)).
 
 ## 1. Install OpenRig, if it isn't installed
 
 - **Check first:** `rig --version`. If it prints a version, go to step 2.
 - **What it needs:** macOS or Linux, Node.js 22 or 24, tmux, and Claude Code or Codex signed in. Check only what's
   missing: `node --version`, `tmux -V`, `claude auth status` or `codex login status`.
-- **Install:** `npm install -g @openrig/cli`, then `rig preflight` (Node, tmux, the daemon port and state folders)
-  and `rig doctor`.
+- **A check that needs the network** (`gh auth status`, a registry or other fetch) can fail falsely in a sandbox without
+  network access, such as Codex's default one. Re-run that one command with network access before you tell the person
+  to sign in again or fix anything.
+- **Install:** `npm install -g @openrig/cli`, then `rig setup --providers codex` (or `claude`, or `both`: the harness
+  the person uses). Setup checks Node, tmux and the logins. It installs tmux (with Homebrew, when present) or the chosen
+  harness (with npm) if either is missing, installs Herdr for the OpenRig view unless they decline it (`--no-herdr`),
+  and adds an OpenRig block to `~/.tmux.conf`, so say all of that first. It doesn't start the daemon. Then `rig doctor`.
 - **Then go on to step 2:** say it's installed and ask what they want worked on, and in which repository. A plain
   "install OpenRig" includes this. Stop here only if they say not to start a team.
 - **If something fails:** `rig context get help` is the help guide for the installed version. If `rig` itself won't
@@ -36,6 +45,8 @@ guidance in `AGENTS.md` or `CLAUDE.md` plus the team's skills and plugins. Say s
 - **Start OpenRig:** `rig daemon status`, and `rig daemon start` if it isn't running. `rig preflight` and `rig doctor`
   don't start it. Starting it also starts OpenRig's own team, the kernel, whose operator sets up the person's team.
   Keep it.
+- **If the person uses Codex:** now that OpenRig is running, make the one-time offer under "Codex: one offer, once,
+  after OpenRig starts" at the end of this step.
 - **Show them OpenRig, the handoff:** once OpenRig is running, open the OpenRig TUI and operator for the person. Say
   you're opening it, then run `rig terminal open saved:kernel --window` on the daemon's desktop. This is the next step
   after installing or starting OpenRig, and the way back whenever they want their agents or OpenRig again. Don't wait
@@ -75,6 +86,26 @@ guidance in `AGENTS.md` or `CLAUDE.md` plus the team's skills and plugins. Say s
 
   For any other failure, the table under "What can interrupt installation and the OpenRig view" in
   `rig context get reference/getting-started.md#open-the-kernel-conversations` says why and what to do next.
+- **Offer to join this session before the first send:** if this session hasn't already joined, recommend joining
+  OpenRig in a plain shell so the operator sees a named teammate instead of "unknown sender". Inside tmux, offer
+  joining as optional, with the effects below. Ask the person yes or no after this short explanation:
+  - This adds me as a named member of the team, with my name on messages.
+  - In a plain shell, joining writes no files in your project or personal settings.
+  - Inside tmux on 0.6.11, my sender and reply address is your existing tmux session name, even a number like `0`.
+    `rig attach --self` returns that address and `rig whoami` confirms it; `--display-name` does not change it.
+  - Inside tmux, other agents can type into this window, and stopping the team (`rig down`) also closes this tmux
+    session (both from source, not hand-tested). Transcript recording and, for Claude Code, writing
+    `.openrig/context-collector.cjs` and `.claude/settings.local.json` for the status line were hand-tested on 0.6.11.
+    Updating an existing `.claude/settings.local.json`, keeping its custom status line, is from source.
+  - In a plain shell, other agents reply through the task queue because they can't type into this window, and
+    stopping the team leaves this session running.
+
+  Attach only on their yes; if they decline, continue the operator handoff. For this first contact, use the kernel's
+  rig ID (the `rigId` of the `kernel` row in `rig ps --json`) and its `operator` pod:
+  `rig attach --self --rig <rigId> --pod operator --member person-agent --runtime <claude-code|codex> --print-env`.
+  `--node <logicalId>` binds to an existing seat instead. Attach once, and keep the variables it prints
+  (`OPENRIG_NODE_ID` and `OPENRIG_SESSION_NAME`). Each command may run in a fresh shell, so put them in front of every
+  later `rig` command. Check with `rig whoami --json`.
 - **Give the operator the goal:** ask what they want worked on, in which repository and on which branch, unless they've
   said. Find the `operator.agent` row in `rig ps --nodes --rig kernel --json`, take its `canonicalSessionName`
   (never the logical ID or a guessed name) and send:
@@ -96,15 +127,34 @@ guidance in `AGENTS.md` or `CLAUDE.md` plus the team's skills and plugins. Say s
 - **Check it's ready before you say so:** `rig ps --nodes --rig <rig>`. If an agent is stopped at a prompt or a menu,
   read it with `rig capture <seat>@<rig>` and answer with the key that screen shows (`rig send --help` says how to
   send a digit, a letter or Escape), or ask the person. Capture it again before sending anything more.
-- **Join this session to the team, if that helps:**
-  `rig attach --self --rig <rigId> --pod <pod> --member <name> --runtime <claude-code|codex> --print-env` adds this
-  session as a new member of a pod. `--node <logicalId>` binds it to an existing seat instead. Attach once, and keep
-  the variables it prints (`OPENRIG_NODE_ID` and `OPENRIG_SESSION_NAME`). Each command may run in a fresh shell, so put
-  them in front of every later `rig` command. Check with `rig whoami --json`.
-- **Replies:** other agents can't type into this session. Read work sent to you with
+- **Replies:** in a plain shell, other agents can't type into this session. Read work sent to you with
   `rig queue list --destination <your address>` and `rig queue show <id> --full`, and read an agent's screen with
   `rig capture <seat>@<rig>`.
 
+### Codex: one offer, once, after OpenRig starts
+
+First the agent resolves the person's real Codex folder (`CODEX_HOME`, or `~/.codex` when that isn't set) and puts the exact path in the
+offer, so the person sees the real file, not a placeholder:
+
+> Codex asks you to approve OpenRig commands. May I let six of them run without asking: `rig ps`, `rig capture`, `rig send`,
+> `rig queue`, `rig status` and `rig whoami`, each with whatever follows it? They would run outside Codex's sandbox, in every Codex
+> project and session you run on this computer, and `rig send` and `rig queue` can message your agents and change their task records, not
+> only read them. I'd add one file, `/home/you/.codex/rules/openrig.rules` (the resolved path). Codex reads it when it starts, so it
+> applies from your next Codex session. To undo, ask me to remove the OpenRig rules this added and keep your other rules.
+
+- **No, or no answer:** nothing is written, and Codex behaves as before.
+- **Yes:** the agent applies it the way OpenRig's existing permission steps already describe (`applying-a-permission-policy`, in the
+  installed OpenRig skills): read the existing rules first, keep any stricter rule, change no sandbox or approval setting, and record what
+  it added. The file is created only if it doesn't exist; if it does, the agent changes nothing and says what's there. A new file holds
+  exactly these two lines:
+  ```
+  # Added by OpenRig on the person's yes: these six rig command families run without a prompt. Ask to undo, or delete this file if it holds nothing else.
+  prefix_rule(pattern = ["rig", ["ps", "capture", "send", "queue", "status", "whoami"]], decision = "allow", justification = "OpenRig coordination commands the person approved once")
+  ```
+- **Undo** (the same skill's words: "Undo the OpenRig command allowances added by this setup; keep my other rules"): the agent removes
+  only the lines it recorded adding, keeps anything else in the file, and deletes the file only if it still holds nothing but those lines.
+  It applies from the next Codex session.
+
 ## 3. Follow the work to its result
 
 - **Find the team's task:** the operator gives the goal to the team's lead as a queue task: `dev-build@starter`, or
@@ -118,7 +168,7 @@ guidance in `AGENTS.md` or `CLAUDE.md` plus the team's skills and plugins. Say s
   actually did (the branch, commit, review or PR text), not just that you sent it.
 - **Give the team more work:** write the goal to a file: what to change, in which repository and branch, what done
   looks like, and that the result comes back to you (the branch or commit, the review, any PR text). Then
-  `rig queue create --source <your name> --destination <seat>@<rig> --body-file <file>`, and tell that agent with
+  `rig queue create --source <your name> --destination <seat>@<rig> --summary "<the goal in a sentence>" --body-file <file>`, and tell that agent with
   `rig send <seat>@<rig> "task <id> is yours"`. A message informs, and a queue task is the work someone owns.
   `--source` names you when this session hasn't joined the team.
 - **Then ask what's next.** If no team can take the work, fix that or ask the person. Don't quietly do it yourself.
@@ -132,4 +182,4 @@ guidance in `AGENTS.md` or `CLAUDE.md` plus the team's skills and plugins. Say s
 - **Everything in the library:** `rig context list`.
 - **Exact syntax:** `rig <command> --help` is always current for the installed version.
 
-Written for OpenRig 0.6.7. When something here and `--help` disagree, `--help` wins.
+When something here and `rig <command> --help` disagree, `--help` wins.

package/daemon/context-packs/help/manifest.yaml

@@ -1,6 +1,6 @@
 # Agent help: the single troubleshooting and escalation guide (docs/reference/help.md).
 name: help
-version: "0.6.11"
+version: "0.6.13"
 taxonomy: world
 purpose: "What an agent does when its user says OpenRig isn't working: diagnose, fix within permissions, verify, and escalate to OpenRig support."
 files:

package/daemon/context-packs/onboarding-width/manifest.yaml

@@ -1,6 +1,6 @@
 # Public capability and source-map width for the default onboarding walk.
 name: onboarding-width
-version: "0.6.11"
+version: "0.6.13"
 taxonomy: world
 purpose: "The public capability map and source map referenced by the default onboarding walk."
 files:

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.11`). 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.13`). 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,12 +24,19 @@ 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
   cells you were scanning for. A seat whose tmux session is confirmed gone reads `detached`
   (activity reason `session_missing`), and `rig ps --nodes` says to restore or relaunch it.
+  `rig ps --nodes` also shows the model each seat was last seen using (`modelObservation`, with its
+  source and time), or unknown; it never shows the configured model in its place. A Claude seat at
+  Claude Code's MCP-server approval menu reads as needing input (`mcp_gate`), a Codex seat at its
+  folder-trust panel reads `trust_gate`, and an OMP seat whose turn ended with a typed transient
+  provider failure reads idle and takes an ordinary retry.
   **`rig ps --resources`** shows this host's load and transcript capture cost.
 - **`rig ps --all-hosts --nodes -A`** — the same across every registered machine. Rollup-only
   unless you ask for nodes.
@@ -50,6 +57,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
@@ -70,7 +79,7 @@ one command away. Your memory of the fleet is a claim about the past.
 - **`rig roster list` / `show` / `find`** — who across your rigs and hosts is recommended for a
   kind of work, from JSON rosters in `<workspace.root>/rosters`. Read-only: it dispatches nothing
   and does not claim anyone is available. The built-in starter and factory leads publish their
-  team's roster at first start.
+  team's roster at first start. `show` and `find` include each seat's last observed model.
 - **`rig telemetry events` / `transitions` / `tenures <node-id>`** — past events, queue
   transitions and a seat's occupants, one bounded page at a time with gaps reported. Reach for it
   before querying the database yourself.
@@ -94,18 +103,29 @@ unseen — which makes messages the one delivery channel that never gets skipped
   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.
+  --host <id>` before any resend. Only a host that was never reached reads as unreachable. A send
+  whose caller goes away (Ctrl-C, or its own timeout) before input starts is refused with
+  `caller_cancelled` and never types later.
 - **`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. For a Claude Code or Codex seat, stderr
+  notes whether the input box's text looks typed or like a faint harness suggestion (`inputBox` in
+  `--json`); it's a heuristic, and `unknown` means unknown.
 - **`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
@@ -159,7 +179,10 @@ unseen — which makes messages the one delivery channel that never gets skipped
 - **`rig slack`** — inspect and manage one connector implementation. Use registered-human
   readiness for the delivery decision and `queue create --verify` for its receipt; connector
   setup or verification is not an outbound human message. After a connection gap the daemon
-  catches up on missed channel messages and marks them late; `rig slack status` shows the
+  catches up on missed messages in the channels this machine owns (its default channel, its
+  channel map's, and on a relayed machine each channel the hub has relayed to it) and on replies
+  in tracked threads whose root or close is within seven days; recovered replies are marked late
+  and never answer a decision. `rig slack status` shows the
   connection, the catch-up state, and the count of retained retry records for inbound messages,
   reactions and click answers (kept across restarts, not a distinct-message count). A retained alert whose row closed before its retry isn't
   posted; the row says why. Its `Delivery:` line says whether events are confirmed arriving;
@@ -174,29 +197,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 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), the queue write commands print a short
-  receipt and `--full` prints the whole row.
-- **`rig queue show`** — what a row *actually says*. The header is not the body.
+  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
@@ -205,11 +240,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. In
-  this release a wake the typing guard holds back (`retained`) is recorded as that one fire and
-  later wakes aren't, so the timer isn't retired: it can wake the owner again at each interval
-  while the row stays parked. A row attached to a shared timer with `--wake-watchdog` loses its
-  one wake if that wake is held back.
+  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
@@ -269,7 +303,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
@@ -364,21 +401,29 @@ not have to tear one down to change it, and you rarely have to start from nothin
 - **`rig up <source>`** — make a whole rig exist and run: from a spec you wrote, a shipped starter
   by name, a bundle someone handed you, a GitHub folder link (pinned to one commit), or a stopped
   rig. `rig up` with a pod-aware spec on a stopped team's name replaces that team (the earlier one
-  is archived), so check `rig ps --nodes` first. Launch-created `AGENTS.md` or `CLAUDE` files now show in `git status`.
+  is archived), so check `rig ps --nodes` first. A rig name containing a dot is refused before
+  launch, because tmux would rename its sessions. 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. 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.
+  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`.
@@ -394,8 +439,13 @@ not have to tear one down to change it, and you rarely have to start from nothin
   <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.
+  An adopted seat (one OpenRig didn't launch) refuses with `claimed_session`. "A conversation it
+  can prove" means the stored conversation matches the one the running Codex's command line names
+  (or, when it names none, the only one Codex has logged since it started); OpenRig can't tell
+  which conversation Codex is on now. If the conversation was changed inside the running Codex,
+  the restart may refuse or resume the earlier one, so look at the pane (`rig capture <seat>`) first.
 - **`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
+  already running. `rig add`, `rig grow` and `rig remove` take 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.
 - **`rig remove`** / **`rig shrink`** — take a seat, or an entire pod, out of a running topology.
   If it holds active work, pass `--fallback <live-seat>` to reroute before mutation; without a
@@ -429,7 +479,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
@@ -497,6 +549,8 @@ 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
@@ -507,14 +561,32 @@ version, from checking the environment to a useful report to the OpenRig team.
   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
   divergence.
+- **`rig seat set-cwd <seat> --cwd <absolute-path> --reason <text>`** — save an existing seat's
+  launch directory, audited, for its next fresh launch or rebuild handover. Its node, address, queue
+  and history stay intact. It creates the folder (on the daemon's host) and writes nothing else there: launch writes the
+  startup files, as today. Its preflight policy refuses, naming the paths, when the new directory
+  holds an edited, unrecorded-and-different or doubly sourced copy that launch would place. The
+  running process keeps its directory: adopt the new one with `rig seat launch <seat> --fresh
+  --stop --reason <text>` or a rebuild handover, promptly (background work, such as a Claude seat's
+  managed compaction, can use the saved directory before then; that's guidance, not a guard), and
+  before any `rig down`/`rig up` or fork handover. In-place Codex restart isn't adoption. `rig seat status` shows the
+  saved `launch_cwd`. Old-directory files are left.
 - **`rig seat set-permissions <seat> --mode <mode> --reason <text>`** — select one seat's native
   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). It works for Pi seats too, sent as `--thinking`.
+- **`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`,
@@ -523,7 +595,13 @@ 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).
+  The refocus work packet stays off by default for Claude Code and Codex;
+  `OPENRIG_REFOCUS_WORK_PACKET=1` turns it on, with each field bounded.
 - **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
@@ -697,7 +775,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`.
@@ -762,7 +844,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`
@@ -793,9 +878,9 @@ your circumstances is configuration, and the ones that are not, another agent ca
   permission policy: an explicit flag wins over it, and it wins over the operator default
   `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.
+- **Smaller settings worth knowing:** per-seat `effort`, passed to Claude as `--effort`, to
+  Codex as `model_reasoning_effort` and to Pi as `--thinking` (`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
@@ -810,8 +895,6 @@ 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
@@ -820,8 +903,20 @@ your circumstances is configuration, and the ones that are not, another agent ca
   listing** — unbound seats, accounts shared across several seats. A Codex seat showing its
   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
-  --refresh` reads a Codex login's usage windows once.
+  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. Each account row also carries a
+  sign-in fact (`usable`, `needs sign-in` or `unknown`); a signed-in Claude login never reads
+  better than `unknown`. A Codex account's last reading, its reset and its last observed exhaustion
+  survive a daemon restart as history (`retained: "before_restart"`), never a current reading; a
+  window whose reset has passed shows an `expectation`, which is planning, not a reading. Run `rig provider status --refresh`
+  before telling anyone an account has room. 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
@@ -833,6 +928,24 @@ 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 top`** — which of this machine's seats used the most tokens over a window (`--window
+  90m`, `1h`, `2d`; `--top <n>` caps the list). Each ranked seat shows its token delta and samples;
+  a seat that has reported usage before but has no usable samples in the window is listed as
+  unknown with its reason, never as zero.
+  To compare machines, run it on each machine, or against each machine's daemon with
+  `OPENRIG_URL=<that daemon's URL>`, back to back, with the same `--window`, no `--top`, and `--json`.
+  Show the results side by side in tokens. For each machine, give its host, the window and its
+  `sinceIso` (each daemon counts from its own clock), how many seats were ranked and over what span,
+  the unknown seats and their reasons, and each seat's runtime, declared `model` and last observed
+  model (`modelObservation`: model, source, time) from `rig ps --nodes -A --json` on that machine.
+  A seat that has never reported usage is in neither list: name each seat that `rig ps --nodes -A
+  --json` shows and `rig usage top` doesn't as not covered. Don't add machines into one total unless
+  they cover the same seats over the same span; where coverage differs, say so instead.
+- **`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.
@@ -859,7 +972,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,
@@ -877,7 +991,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
@@ -955,6 +1072,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**.