@openrig/cli 0.6.13 → 0.7.0

package/daemon/assets/plugins/openrig-core/skills/queue-handoff/SKILL.md

@@ -29,8 +29,9 @@ without an owner.
   with the rig appearing dormant.
 - **Finishing a slice that has a clear next step.** Default-nudge:
   receiver gets a wake-ping plus the durable queue item.
-- **Blocked on another agent's work.** Park the qitem with
-  `closure_reason: blocked_on` and the blocker qitem id.
+- **Blocked on another agent's work.** Use `rig queue block <id> --on <child>`
+  (or `rig queue update <id> --state blocked --blocked-on <child>`). The item
+  stays active and returns to pending when its blocker completes.
 - **Escalating to the human.** Make the escalation a durable attention
   item, not just a chat message.
 
@@ -53,16 +54,20 @@ human. The qitem state machine enforces this:
 `pending → in-progress → done` requires `closure_reason` from one of:
 
 - `handed_off_to` — work continues at a different seat (target = new owner)
-- `blocked_on` — parked pending another qitem (target = blocker qitem id)
 - `denied` — receiver rejected the work
 - `canceled` — sender or receiver withdrew
 - `no-follow-on` — terminal completion, nothing else needed
 - `escalation` — kicked up to a higher tier (target = escalation target)
+- `superseded` — replaced by another qitem (target = successor qitem id)
 
-Three of those (`handed_off_to`, `blocked_on`, `escalation`) additionally
+Two of those (`handed_off_to`, `escalation`) additionally
 require `closure_target`. The daemon enforces this at the domain layer;
 every surface (CLI, MCP, future UI) inherits the same guarantee.
 
+`done` is terminal. `closure_reason: blocked_on` is valid only on an active
+`state=blocked` park record, as used by workflow writers; combining it with
+`state=done` is rejected. Use the block command above to wait on another qitem.
+
 **The drafted-park failure (draft ≠ throw).** The rule is about the *actual* pass, not the
 intention to pass. A turn that ends with a self-instruction **typed into your own prompt but left
 unsent** — a drafted go-ahead, a next-atom note you never sent — has **not** handed off; it has
@@ -120,6 +125,7 @@ inverted the default-nudge polarity.
 - **Scope tags `project:<id>`, `mission:<id>`, `slice:<id>`** on project work, set when you create the row (`--tags`; `create` also takes `--mission` and `--slice`). Tags can't be edited afterwards. A handoff keeps the source row's tags unless you pass `--tags` or `--gate`, either of which replaces them; repeat the scope tags in `--tags` when you use `--gate`.
 - **Pass work on with `handoff-and-complete`.** It closes your row as done and records the next row as its successor in one step. A `create` followed by `update --state done --closure-reason handed_off_to` records no successor, and the stuck sweep raises a recovery item for it.
 - **Close what you hold.** A row you claimed ends in a handoff or an `update --state done --closure-reason …`; `rig queue overdue` lists claimed rows past their deadline.
+- **Use the write's response.** Read the row back only when the response doesn't show what you need (an indeterminate outcome, a field the compact output left out, downstream wake or pickup, a team custody rule): openrig-user, "After a queue write".
 - **Brief for the model that will read it.** Before handing a peer open-ended work, check which model it runs: `delegating-work`, "Check what kind of agent you're handing it to".
 
 ## Queue-body hygiene (token + parse safety)

package/daemon/assets/plugins/openrig-core/skills/refocusing/scripts/trace-to-root.py

@@ -75,39 +75,19 @@ def read(path):
         return None
 
 
+# Contract twin of CLI scope-fs.ts and daemon scope/node-file.ts; parity is tested.
+NOTES_FILE_PRECEDENCE = ("NOTES.md", "MISSION_NOTES.md")
+
+
 def resolve_notes(node):
-    try:
-        result = subprocess.run(
-            ["rig", "scope", "resolve-notes", str(node), "--json"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-            check=False,
-        )
-    except subprocess.TimeoutExpired:
-        return None, "resolver command timed out"
-    except OSError as error:
-        return None, f"resolver command could not start: {error}"
-    if result.returncode != 0:
-        detail = (result.stderr or result.stdout or "").strip().splitlines()
-        suffix = f": {detail[0]}" if detail else ""
-        return None, f"resolver command exited {result.returncode}{suffix}"
-    try:
-        payload = json.loads(result.stdout)
-    except (json.JSONDecodeError, TypeError):
-        return None, "resolver command returned malformed JSON"
-    if not isinstance(payload, dict) or payload.get("ok") is not True or "resolution" not in payload:
-        return None, "resolver command returned an invalid success shape"
-    resolution = payload["resolution"]
-    if resolution is None:
-        return None, None
-    if not isinstance(resolution, dict):
-        return None, "resolver command returned an invalid resolution shape"
-    resolved_path = resolution.get("path")
-    resolved_name = resolution.get("name")
-    if not isinstance(resolved_path, str) or not isinstance(resolved_name, str):
-        return None, "resolver command returned an invalid resolution shape"
-    return (Path(resolved_path), resolved_name), None
+    for name in NOTES_FILE_PRECEDENCE:
+        candidate = node / name
+        try:
+            if candidate.is_file() and os.access(candidate, os.R_OK):
+                return (candidate, name), None
+        except OSError:
+            pass
+    return None, None
 
 
 def intent(text):

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

@@ -14,7 +14,8 @@ if the person asks you to. When they say what they want built, give it to OpenRi
 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
+machine without a yes, and don't start a team, including `rig up`, without their yes to what it will start; a yes they
+already gave for that same launch counts, so don't ask twice. Starting OpenRig and a team writes files: Codex hooks and settings in
 `~/.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
@@ -23,6 +24,10 @@ seats run with an operational default: Codex with `-s danger-full-access -a neve
 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)).
 
+When you give the person a file or a command to run in their own terminal, use a path that exists on their side. A
+file a sandboxed agent writes under `/tmp` may not exist in the person's terminal (seen with Codex), so put files the
+person needs in their project or home folder and name that path.
+
 ## 1. Install OpenRig, if it isn't installed
 
 - **Check first:** `rig --version`. If it prints a version, go to step 2.
@@ -106,13 +111,18 @@ before you start OpenRig ([the full list](https://github.com/mvschwarz/openrig#w
   `--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`.
+  If they decline, a message that must still say who it's from can go as a queue item with a declared source,
+  `rig queue create --source <their id>@external --destination <seat> --summary "<one line>" --body-file <file>`: the
+  seat sees that name, recorded as declared, and can reply to them if they're registered (`rig gateway human list`).
+  A declared name is a claim, not a seat's own identity: for a team that acts only on seat identity, the attached
+  shell above is the route.
 - **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:
   `rig send <canonicalSessionName> 'This is the agent that installed OpenRig. The person will answer in your pane. Goal: <goal>. Project folder: <absolute path>. Branch: <branch>.'`
   Or the person types the goal and folder in the operator's pane. If they give you a goal later, forward it the same
-  way. The operator helps them pick a team that fits their logins, starts it on their yes and gives the goal to the
-  team's lead. Before that yes, it says what launching into their folder changes for their own agent there; relay
+  way. The operator helps them pick a team that fits their logins, starts it (`rig up`) only on their yes to the plan it
+  shows, and gives the goal to the team's lead. Before that yes, it says what launching into their folder changes for their own agent there; relay
   that with the question. Show them where the operator answers, and don't build the project yourself.
 - **Relay the operator's questions:** the operator asks in its own pane, and the person may not be looking there.
   After each step you hand it, read its screen with `rig capture <canonicalSessionName>`. When it asks the person
@@ -125,8 +135,17 @@ before you start OpenRig ([the full list](https://github.com/mvschwarz/openrig#w
 - **See what's running:** `rig ps`, then `rig ps --nodes --rig <rig>` for a team's agents. If a team is already
   running in that repository, tell the operator.
 - **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.
+  read it with `rig capture <seat>@<rig>`. A permission prompt is the person's to answer: show it to them, with any
+  others waiting, one line each (seat, exact action, the choices offered). Before sending their choice, capture that
+  seat again: if its prompt changed, don't reuse the answer. Then send exactly the choice they made for that prompt
+  (`rig send --help` says how to send a digit, a letter or Escape to a prompt). A yes to one prompt isn't a
+  yes to the next, and never pick a "don't ask again" choice they didn't pick. If they've told you outright to decide a
+  kind of future prompt (say, "approve prompts that only write inside my project"), you may decide each one: read its
+  whole action, answer only when it's clearly inside what they said, and tell them you answered under that instruction,
+  not that they said yes. Bring anything unclear or outside it back to them; a command's name or a path that looks like
+  their project doesn't show what the action touches. Their instruction changes no permission setting.
+  Another kind of menu you can answer with
+  the key that screen shows, or ask the person. Capture it again before sending anything more.
 - **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>`.

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.13"
+version: "0.7.0"
 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.13"
+version: "0.7.0"
 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

@@ -11,7 +11,7 @@ not know exists.** So the point of what follows is not skill. It is recognition:
 lands, something rhymes, and you go check instead of building.
 
 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
+`capability-delta-v0.6.14`). 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).
@@ -135,7 +135,8 @@ unseen — which makes messages the one delivery channel that never gets skipped
   read something, do not ask it. Look.**
 - **`rig ask`** — search what was said or decided, across *every generation that ever sat in a
   seat*. It reaches back past a handover that erased your predecessor's context, and costs no
-  runtime tokens.
+  runtime tokens. `--wake` asks a Claude or Codex seat itself; any other runtime (Pi, custom, or
+  none recorded) is refused before a wake starts.
 - **`rig chatroom wait`** — block until a peer actually says something, instead of polling
   `capture` in a loop. Also `history`, `watch`, `topic` for a named thread that stays retrievable.
   Its `--timeout` is in seconds and ignores a suffix, so `2m` means 2 seconds. Poll timeouts,
@@ -460,7 +461,12 @@ not have to tear one down to change it, and you rarely have to start from nothin
   to a node. **`rig adopt`** does the whole thing at once: create the structure and bind the
   running sessions into it.
 - **`rig reconcile-session`** — you resumed a seat by hand and the daemon still shows it down; make
-  the system see the live process **without launching anything**.
+  the system see the live process **without launching anything**. A running seat that refuses every
+  send because its tmux pane was never recorded (one launched by an older OpenRig) takes
+  `rig reconcile-session <seat> --repair-missing-pane --no-launch`: it fills only the missing pane,
+  keeps the session and resume token, and never adopts. Plain reconcile adopts: a new session row
+  (any running row for the seat is superseded); it re-captures the resume token if it can, and
+  conversation continuity stays unverified. Both refuse while typing protection is on.
 - **`rig unclaim` / `rig release`** — stop managing one adopted session, or all of them,
   **without killing the process or the agent inside it**. Handing something back to its human is a
   first-class move, not an abandonment.
@@ -487,6 +493,7 @@ version, from checking the environment to a useful report to the OpenRig team.
   Stop distinguishes process/listener exit from a clean asynchronous drain: inspect the matching
   `daemon-shutdown.json` and log when completion is incomplete or unverified. No target is a
   distinct no-op, and a timeout never proves down. Use command help for exact limits and recovery.
+  `/healthz` reports the daemon's effective UID as `euid`, beside `pid`.
 - **`rig doctor`** — is the *installation* wired up correctly, or are you chasing a bug that is
   really a broken install. It checks Claude and Codex installs, and a login or configured provider
   credential, the way setup does; it fails for a harness the person doesn't use, which they can
@@ -590,7 +597,9 @@ version, from checking the environment to a useful report to the OpenRig team.
 - **`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`,
-  `--cancel` and `--skip-map` inspect, stop or skip that wait. The `claude-compaction-restore`
+  `--cancel` and `--skip-map` inspect, stop or skip that wait. If preparation stops at an ordinary
+  approval, a manual `rig compact` keeps waiting for someone to answer it, within its 180-second
+  budget; OpenRig never answers it, and the request times out after 240 seconds. The `claude-compaction-restore`
   skill covers writing and reading the map; `claude-compact-in-place` no longer ships. After a
   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
@@ -840,7 +849,10 @@ your circumstances is configuration, and the ones that are not, another agent ca
 - **`rig config get` / `reset` / `init-workspace`** — read one value, change a system-wide setting
   and put it back exactly as it was, or additively lay down the canonical project scaffold on a
   box that has none. Instance startup uses the same additive initializer for the surrounding
-  `state`, `context`, `skills`, `topology`, and operational roots.
+  `state`, `context`, `skills`, `topology`, and operational roots. With `transport.local_user_guard`
+  on (off by default; `rig config set transport.local_user_guard true`), a Mac's local `rig` requests
+  stop only when the daemon's reported, `ps`-corroborated user differs from yours; unknown evidence
+  lets the call through. It isn't authentication or isolation.
 - **`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
@@ -914,9 +926,7 @@ your circumstances is configuration, and the ones that are not, another agent ca
   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.
+  before telling anyone an account has room.
 - **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

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

@@ -1,20 +1,66 @@
-# Getting started: meet the kernel, then make one useful change
-
-Install OpenRig, use a working provider login, and meet the kernel operator with
-the advisor and TUI beside it. No starter team is needed to reach that view.
-Tell the operator what you want to do, then choose a project team for a bounded
-change you can exercise. Reuse the accounts and terminal tools you already have.
-
-After installation and sign-in, your agent opens the **OpenRig TUI and operator** for you. The path is `rig daemon start` (if stopped),
-then `rig terminal open saved:kernel --window`. The second command opens the
-desktop window itself. An agent can run it from its shell on the daemon's
-desktop; it does not need to type into your current terminal. See
-[Open the kernel conversations](#open-the-kernel-conversations).
-`rig tui` is the team dashboard; installation ends when you are talking to the
-operator in the OpenRig view.
+# OpenRig setup reference
+
+This is the full reference for installing and running OpenRig, written for the agent doing the setup and for anyone
+who wants the detail. The short version for people is [Getting started](quickstart.md).
+
+## For the agent doing the setup
+
+The `rigs` skill is the procedure: follow it in order. This page is what it looks things up in.
+
+- **Done** means the person is talking to the operator in a visible OpenRig view. A healthy daemon, a started kernel
+  or an opened window isn't done on its own. If they'd rather talk later, the handoff is still pending: say so, and
+  leave them the exact command.
+- **Read readiness; don't assume it:**
+  - **The kernel:** the `Kernel:` line in `rig status`, and `rig ps --nodes --rig kernel`.
+  - **A team:** `rig ps --nodes --rig <team>`.
+  - A missing or unknown signal isn't ready.
+  - `rig up` exiting 1 with `Status: partial` and `Startup attention` means a seat is waiting at a prompt. Answer it,
+    or ask the person to, then run the `rig seat continue <seat>` it names.
+- **Prerequisites:** check the person's existing toolchain first (mise, nvm, Homebrew or the nodejs.org installer)
+  and the PATH. Use what's there. Don't change a shared Homebrew's ownership, and don't make a local workaround the
+  standard route. If Node.js is installed after your session started, check that new shells and the session's hooks
+  can find it. In one published-0.6.11 Mac run, OpenRig's Claude hooks reported `node: command not found` until the
+  PATH was fixed.
+- **Ask once, then reuse the answer:** the provider (Claude Code, Codex or both), Herdr, Ghostty on macOS,
+  remembered command allowances, and the team.
+- **Before changing their machine:** say what applies to their route, then wait for a yes. See
+  [what OpenRig changes on your machine](../../README.md#what-openrig-changes-on-your-machine).
+- **When something stops:**
+  - [Incomplete setup and restart](#incomplete-setup-and-restart) maps what you see to the next action.
+  - [What can interrupt installation and the OpenRig view](#what-can-interrupt-installation-and-the-openrig-view)
+    covers the view.
+  - [Headless or SSH handoff](#headless-or-ssh-handoff) covers no-display cases.
+  - A timed-out command may still have taken effect. Read `rig ps` or `rig seat status <seat>` before you run it
+    again.
+- **Don't:**
+  - relaunch a team to reopen its view;
+  - start another seat to clear a prompt;
+  - build the person's project yourself. Give the goal to the operator.
 
 ## Before you start
 
+> **What OpenRig changes on your machine**
+> - **Install:** `@openrig/cli` goes in globally with npm.
+> - **Setup:** `rig setup` adds an OpenRig block to `~/.tmux.conf`. It can install tmux (with Homebrew on macOS), and
+>   Herdr unless you pass `--no-herdr`. Plain `rig setup`, which is what the one-command install runs, checks both
+>   Claude Code and Codex and may install a missing one; `rig setup --providers claude` (or `codex`) limits it to
+>   yours.
+> - **Starting OpenRig, for the coding agent you use** (paths are the usual defaults):
+>   - Codex: hooks and trust in `~/.codex/config.toml`.
+>   - Claude Code: workspace trust in `~/.claude.json`, and activity hooks in the project's
+>     `.claude/settings.local.json`, plus a status line unless you already have your own.
+>   - Discovery skills go in `~/.claude/skills` and `~/.agents/skills`.
+> - **Starting a team in your project:** adds managed guidance to `AGENTS.md` or `CLAUDE.md`, plus the team's skills
+>   and plugins.
+> - **Permissions:** by default, OpenRig's own kernel gets broader permissions than a project team gets by default.
+>   On Codex that's full access with no approval prompts (`-s danger-full-access -a never`). On Claude Code, its file
+>   tools, web fetches and operational commands, including reads under your home folder, run without asking. A
+>   permission policy, per-agent choice or Codex profile changes that. What your team can do depends on the team you
+>   choose and your settings; `workshop`, for example, ships with broad access.
+> - **Backups:** OpenRig doesn't guarantee it can preserve or roll back these files, so back them up first.
+>
+> [Everything OpenRig writes, and why →](https://github.com/mvschwarz/openrig#what-openrig-changes-on-your-machine)
+
 You need Node.js 22 or 24 and tmux, on macOS or Linux, and one working Claude
 Code or Codex account: one is enough, since the kernel operator adapts the
 shipped `starter` team to whichever you have. On Linux, the distribution's own
@@ -26,12 +72,16 @@ you aren't an administrator, or where Homebrew belongs to another account (its
 `brew install` is refused), install Node.js in your own home folder with
 [nvm](https://github.com/nvm-sh/nvm): run `touch ~/.zshrc` (a new Mac account
 has none, and nvm's installer only adds itself to a profile file that already
-exists), then the install command on nvm's page, open a new terminal, and run
-`nvm install 22`. That needs no administrator password, and `npm install -g`
-then installs into your nvm folder. Native
-Windows isn't supported. On Windows, use WSL2: it's the Windows route OpenRig
-supports, though OpenRig's automated tests don't run on it yet. One user's
-[working setup](#wsl2-a-reported-working-setup) is below. Node 20 and
+exists), then nvm's install command, for nvm v0.40.8
+`curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash`
+([nvm's page](https://github.com/nvm-sh/nvm#install--update-script) has the
+newest), open a new terminal, and run `nvm install 22`. nvm itself needs no
+administrator password, and `npm install -g` then installs into your nvm folder.
+If nvm's installer says you need Apple's command line tools, run
+`xcode-select --install`, then its install command again. Native Windows isn't
+supported. On Windows, use WSL2: it's the Windows route
+OpenRig supports, though OpenRig's automated tests don't run on it yet. One
+user's [working setup](#wsl2-a-reported-working-setup) is below. Node 20 and
 odd-numbered releases (23, 25 and so on) are not supported; Node 26 and later
 even-numbered releases are untested.
 
@@ -131,20 +181,19 @@ You can also read [`skills/rigs/SKILL.md`](../../skills/rigs/SKILL.md) directly.
 script will do and changes nothing:
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.13/scripts/install.sh | sh -s -- --dry-run
+curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.0/scripts/install.sh | sh -s -- --dry-run
 ```
 
 The same command without `--dry-run`,
-`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.13/scripts/install.sh | sh`, installs the
+`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.0/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 among the first three prints
-`FAILED [n/4] <command or check> (exit <code>)`. When `rig setup` (step 4) doesn't finish ready, for example because a
-provider isn't signed in yet, the script ends with `INSTALLED, SETUP NOT COMPLETE (exit <code>)`: the CLI is
-installed, and `rig setup` lists what's left under "Some steps need attention". If the only items left are provider
-sign-ins, sign in to each selected provider as below, then continue at
-[Start the kernel](#start-the-kernel-and-check-its-state); run `rig setup` again rather than reinstalling the CLI. To
-install only what the selected providers need, go step by step instead:
+Codex and may install a missing one, as described below. A failed step prints
+`FAILED [n/4] <command or check> (exit <code>)`. Where a provider isn't signed in yet, step 4 ends that way and
+`rig setup` lists each sign-in under "Some steps need attention". If the only remaining failures are provider
+sign-ins, the install steps finished: sign in to each selected provider as below, then continue at
+[Start the kernel](#start-the-kernel-and-check-its-state). To install only what the selected providers need, go step
+by step instead:
 
 ### Choose your providers
 
@@ -174,6 +223,26 @@ writes an OpenRig-managed block (mouse on, a longer history) into `~/.tmux.conf`
 It is optional for this selected-provider path, not a requirement to fix an unused
 provider.
 
+The block keeps `terminal.history_limit` rows of scrollback per pane (default
+10000). To keep more, run `rig config set terminal.history_limit 50000`, then
+`rig setup` again. A running tmux server keeps its old limit until it restarts
+or you run `tmux source-file ~/.tmux.conf`; before tmux 3.7 that changes new
+panes only.
+
+New managed agents and handover successors on macOS/Linux start from the daemon's
+selected launch environment and declared seat values, rather than stored tmux globals.
+Values named by tmux's `update-environment` option, including its default SSH-agent
+and display variables, come from the daemon's environment.
+Normal shell startup and configured tmux shell commands still run. If your custom setup
+intentionally supplies values through tmux's global environment, opt in with
+`rig config set terminal.inherit_tmux_environment true`. Setup points out this option
+when it detects custom tmux configuration; it never enables it automatically. The setting
+applies to future launches and successors, not running agents or your personal tmux server.
+If the scoped environment cannot be prepared, launch keeps its previous environment and
+reports a warning in fresh launch results and the daemon log. For handovers, check
+that log for this warning. This is not a promise that shell startup cannot add or override values.
+
+
 ## Start the kernel and check its state
 
 With a working selected login, start the daemon if it is stopped, then read its
@@ -205,9 +274,51 @@ A missing or unknown readiness signal is not proof of readiness. Follow
 startup or missing-seat problems.
 
 `rig setup` itself does not start the daemon. Preserve a daemon and kernel that
-already exist: ordinary daemon startup skips a managed kernel, and
-`OPENRIG_NO_KERNEL=1` skips automatic kernel startup. If neither runtime is
-authenticated, kernel boot reports `auth_blocked`. Do not restart or recreate an
+already exist: daemon startup does not boot a second kernel when one is managed,
+and `OPENRIG_NO_KERNEL=1` (`--no-kernel`) skips automatic kernel startup,
+including the restore below. If neither runtime is authenticated, kernel boot
+reports `auth_blocked`.
+
+Daemon startup restores one existing kernel by itself: a managed kernel whose
+seats are all `detached` and still bound to their newest session, which is what
+startup reconcile leaves when every kernel terminal is gone, for example after a
+reboot. It does not detect a reboot as such. It uses the same restore as
+`rig up kernel --existing`, and `rig status` reports it as `Kernel: booting`
+until the seats are ready. A kernel stopped with `rig down kernel`, including
+one whose seats were already detached, stays down on later starts. So do a kernel
+with only some seats stopped and seats you unclaimed. Start one again with
+`rig up kernel --existing`.
+When the tmux server is gone, an explicit `rig down` of any rig can start an
+empty server and probe again. It records the stop and clears eligible bindings
+only after confirming the sessions are absent. This can leave an empty tmux
+server running; it never launches an agent or provider session. Unreadable or
+permission results and changed occupants leave the stop bookkeeping unchanged.
+
+While that automatic restore runs, `rig start` continues to your other rigs and
+says the kernel is still restoring (`kernelRestore.state: "restoring"` with
+`--json`). Its exit status 0 then does not mean the kernel is ready; check
+`rig status`. When the restore has returned without a ready kernel, `rig start`
+still goes on to your other rigs but exits 1 (`kernelRestore.state: "failed"`),
+so `rig start && next` does not run `next`. A `rig down kernel` made during the
+restore waits for it to return and then stops the kernel, which stays down on
+later starts. A `rig up kernel --existing` with no fresh seats and no change to
+the saved non-interruptive choice, made during the restore, or after it restored
+every seat while those seats still run the sessions it started, reports that
+restore's outcome instead of starting another. Explicitly repeating the saved
+`--non-interruptive` or `--no-non-interruptive` choice also joins that restore.
+
+An explicit `rig up kernel --existing --fresh <seat...>` waits for startup's
+restore to finish, then replaces only the named seats that still hold the exact
+sessions startup launched. Other seats keep running. An operator's conversation
+correction also takes effect for that seat on the next explicit `up` or
+`restore`, using the corrected target; editing the token alone restarts nothing.
+Each replacement takes new seat leases, rechecks the managed occupant and terminal,
+and reports its own per-seat outcome. If the occupant changed, it is left alone.
+A different `--non-interruptive` or `--no-non-interruptive` choice after startup
+launched the seats is refused: the running launch choice stays unchanged. Stop
+the rig, then rerun with the desired choice.
+
+Do not restart or recreate an
 existing kernel merely to open its view. The startup TUI (`rig`) offers its own
 kernel setup and individual-seat recovery; it does not automatically boot agents
 when it starts the daemon.
@@ -644,7 +755,7 @@ the lifecycle API without booting a new kernel, then stop the remaining rigs.
 | Shared terminal is absent | Inspect the existing kernel binding and recovery state; use standalone `rig tui` while resolving it. |
 | Viewing terminal was closed | Open the conversations again with `rig terminal open saved:kernel --window`; `rig tui --shared` is only the dashboard fallback if that window cannot open. Do not relaunch the team. |
 | Daemon restarted but tmux survived | Re-read `rig status` and the existing queue; a daemon restart is not a fresh project. |
-| Host reboot lost tmux sessions | Open `rig`, start the daemon if needed (press **S** if it opens on the work views), and select the existing rig and seats. Resume is the default; a fresh conversation needs a separate decision. |
+| Host reboot lost tmux sessions | Starting the daemon restores the kernel by itself when all of its seats were lost; check `rig status`, and if it reports the restore failed, run `rig up kernel --existing`. For other rigs, open `rig`, start the daemon if needed (press **S** if it opens on the work views), and select the existing rig and seats. Resume is the default; a fresh conversation needs a separate decision. |
 | Launch reports no usable snapshot | Inspect the existing rig and retained project files, then follow the same-seat recovery below. |
 | Work is waiting on a prompt or decision | Read the row, transition and named prompt; preserve the obligation until the missing decision arrives. |
 
@@ -675,8 +786,9 @@ This recovery is for the case the reporter hit: the kernel's seats failed and no
 IDs, for example `advisor.lead operator.agent operator.human queue.worker` when all four failed. `--fresh` starts a
 new conversation for each seat you name. Seats you don't name follow their normal recovery policy and may remain
 awaiting a decision if their old conversation can't be resumed. A later `rig daemon start` doesn't retry the failed
-seats by itself: once a kernel exists, startup skips the built-in kernel boot, and `rig status` then reads
-`Kernel: skipped` whatever its seats' state, so check `rig ps --nodes --rig kernel --full`.
+seats by itself: once a kernel exists, startup skips the built-in kernel boot and restores only a kernel whose seats
+were all lost, not seats that failed. `rig status` then reads `Kernel: skipped` unless some of its seats are running
+and ready, so check `rig ps --nodes --rig kernel --full`.
 
 If a snapshot is unavailable, the startup view checks the selected seat's
 retained startup source and authoritative occupant relation. It reports a
@@ -995,6 +1107,37 @@ same-seat stop/resume path after checking its retained policy; do not erase the
 rig or start a duplicate to reset permissions. A resume can reapply the stored
 launch mode, so verify the native mode again before continuing work.
 
+## Optional Mac local-user check
+
+On a Mac shared by multiple OS accounts, `transport.local_user_guard` can reduce
+accidental CLI routing to another account's local daemon. It is **off by default**.
+Enable it with `rig config set transport.local_user_guard true`, or set
+`OPENRIG_TRANSPORT_LOCAL_USER_GUARD=true` in the CLI's environment. Set it to
+`false` to turn it off; no daemon restart is needed for the CLI check.
+
+When enabled, automatic local CLI data requests compare the daemon's reported
+`/healthz` PID and effective UID (`euid`) with two `ps` UID/start observations and
+a second health response, with at most one second of observation per check.
+Only stable agreement on a foreign effective UID stops the request. This does
+not require visibility into another user's socket descriptors. It does not
+stop the daemon, choose another port or retry. Diagnostic health/status checks
+remain available. Older daemons without `euid` remain unknown and are permitted.
+`sudo rig …` uses the caller's **effective** UID, so an enabled check against a
+user-owned daemon refuses when its reported/observed UID differs from root.
+
+Explicit `OPENRIG_URL`/`RIGGED_URL` targets and registered remote hosts retain
+their selected routing, including tunnels. An internally resolved local URL is
+still checked. Default UI and TUI openings are checked before launch; this does
+not police later browser or TUI connections.
+
+Missing, disagreeing, restricted or timed-out evidence **continues today's
+behavior**. This is a partial accidental-routing check, not authenticated user
+isolation: it trusts the daemon's PID/UID report and corroborates that process;
+it does not establish the socket's owner. Identity can change between observation
+and connection, and equal UIDs do not distinguish separate instances belonging
+to one account. The check
+does not add authentication to the daemon or protect direct HTTP clients.
+
 ## Custom settings and precedence
 
 - **OpenRig:** member `permission_policy` overrides rig `permission_policy`.

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.13"
+version: "0.7.0"
 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

@@ -354,7 +354,7 @@ pods:
 
 - A seat gets the rig's `env` with its own `env` laid over it, name by name.
 - The same environment is applied on first launch, on `rig up <rig-name>` restore, and to the successor of a seat handover.
-- `rig up <spec> --env KEY=VALUE` (repeatable) adds or overrides a value for one launch. A one-off value belongs to the terminal that launch creates: it stays in that terminal's environment for as long as the terminal lives, and OpenRig removes it from the tmux session's environment as soon as the terminal has started, so a terminal started later in that session does not get it. A restore, a handover successor or any later launch starts from the spec's `env:` alone, so the value is not saved and does not carry forward. To keep a value, put it in `env:`. One exception to "does not carry forward", for a managed Claude seat (see below): a one-off name that the seat's spec does not declare stays on the session's list of names, `OPENRIG_SEAT_ENV_KEYS` (names only, no values), because the first launch and an in-place restart of the same terminal read that list. So if a later pane in that session gets a value for that name from the tmux server's own environment, its managed Claude launch can forward that value, where a launch without `--env` would leave it out. The first launch's one-off value itself is not passed on to that pane. This comes from reading the code and has not been measured. `--env` does not apply to `rig up <rig-name>` (a restore) or to a topology (several rigs from their own specs); the CLI refuses both. For a topology, put `env:` in each rig's spec.
+- `rig up <spec> --env KEY=VALUE` (repeatable) adds or overrides a value for one launch. A one-off value belongs to the terminal that launch creates: it stays in that terminal's environment for as long as the terminal lives, and OpenRig removes it from the tmux session's environment as soon as the terminal has started, so a terminal started later in that session does not get it. If OpenRig can't take it out, the seat keeps running and the launch warns, naming the variable and the tmux command to put it back or remove it. Until then, a terminal started later in that session would get it. A restore, a handover successor or any later launch starts from the spec's `env:` alone, so the value is not saved and does not carry forward. To keep a value, put it in `env:`. One exception to "does not carry forward", for a managed Claude seat (see below): a one-off name that the seat's spec does not declare stays on the session's list of names, `OPENRIG_SEAT_ENV_KEYS` (names only, no values), because the first launch and an in-place restart of the same terminal read that list. So if a later pane in that session gets a value for that name from the tmux server's own environment, its managed Claude launch can forward that value, where a launch without `--env` would leave it out. The first launch's one-off value itself is not passed on to that pane. This comes from reading the code and has not been measured. `--env` does not apply to `rig up <rig-name>` (a restore) or to a topology (several rigs from their own specs); the CLI refuses both. For a topology, put `env:` in each rig's spec.
 - Names starting `OPENRIG_` are reserved for OpenRig and refused. Empty values are refused, because the launch omits empty variables.
 - `rig export` writes the rig and member `env:` back out.