@openrig/cli 0.6.5 → 0.6.7

package/README.md

@@ -14,13 +14,24 @@ It's the open-source system behind my AI civilization experiments.
 
 ![The OpenRig TUI: the build rig as a graph, then as a table of seats with runtime, model, context and state, then one seat in detail (real recording, 10 seconds)](assets/readme/openrig-agents-working.gif)
 
-**Start here:** [the guided first-use path](docs/reference/getting-started.md): install, launch a two-agent team in your repository, and get one reviewed change.
+**Start here:** [the guided first-use path](docs/reference/getting-started.md): install, talk to the kernel operator, then choose a team for your first useful change.
 
 Not setting this up today? Get the next walkthrough and occasional OpenRig updates → https://openrig.dev/follow
 
 ## Install and first run
 
-Requires Node.js 22 or 24 and tmux, on macOS or Linux. On a Mac with Apple silicon, use Node.js 22 ([compatibility history](docs/releases/v0.5.15.md#known-compatibility-limitation)). Native Windows is not supported yet, and WSL2 has not been tested. Launching a rig writes provider hooks and workspace trust settings. Before running the commands below, read [what OpenRig changes on your machine](#what-openrig-changes-on-your-machine) and back up the relevant files.
+Requires Node.js 22 or 24 and tmux, on macOS or Linux. On Linux, the distribution's own Node.js can be older (Ubuntu 24.04's is 18); install a supported version with [nvm](https://github.com/nvm-sh/nvm) (`nvm install 22`) or NodeSource. On a Mac with Apple silicon, use Node.js 22 ([compatibility history](docs/releases/v0.5.15.md#known-compatibility-limitation)). On Windows, use WSL2, the Windows route OpenRig supports; native Windows isn't supported. OpenRig's automated tests don't run on WSL2 yet; see [one user's working setup](docs/reference/getting-started.md#wsl2-a-reported-working-setup). Launching a rig writes provider hooks and workspace trust settings. Before running the commands below, read [what OpenRig changes on your machine](#what-openrig-changes-on-your-machine) and back up the relevant files.
+
+**One command.** This runs OpenRig's install script from the `v0.6.7` release. It checks Node.js and npm, installs the latest published `@openrig/cli` with `npm install -g`, runs the Node.js and SQLite check, then runs `rig setup --dry-run` and `rig setup`. The first line prints that plan and changes nothing:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.7/scripts/install.sh | sh -s -- --dry-run
+curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.7/scripts/install.sh | sh
+```
+
+If a provider isn't signed in yet, the last step reports `FAILED [4/4]`, and `rig setup` lists the 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 and continue.
+
+**Or step by step:**
 
 ```bash
 npm install -g @openrig/cli
@@ -29,46 +40,100 @@ rig setup --dry-run
 
 To install with Bun instead, run `bun add -g @openrig/cli`. OpenRig still runs on Node.js, so install Node.js 22 as well. Bun may block this package's postinstall script, in which case the Node.js and SQLite check described under [what OpenRig changes on your machine](#what-openrig-changes-on-your-machine) does not run at install time.
 
-Choose the working account you already have: **Claude Code, Codex, or both**. Reuse an explicit choice; no second subscription is required. `rig setup --dry-run` previews the broader setup, but applying `rig setup` checks both harnesses and cmux. It is optional for the [selected-provider path](docs/reference/getting-started.md#choose-your-providers).
+npm 11 and later can skip that postinstall script and print `npm warn install-scripts` naming `@openrig/cli`. That's expected: the CLI still works, and only the Node.js and SQLite check was skipped. To run it yourself, use `node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"`; `rig doctor` checks the Node.js version only.
+
+Choose the working account you already have: **Claude Code, Codex, or both**. Reuse an explicit choice; no second subscription is required. `rig setup --dry-run` previews the broader setup; applying `rig setup` checks both harnesses and installs a missing one, plus Herdr unless declined with `--no-herdr`. On macOS, the installing agent offers Ghostty once. Setup leaves an existing cmux installation alone. It is optional for the [selected-provider path](docs/reference/getting-started.md#choose-your-providers).
 
-Before launching, your agent asks once: **“Allow your agents to run OpenRig commands without repeated permission prompts?” Yes — recommended / No — keep prompts.** This covers every `rig` command, including starting/stopping agents and configuration, at personal project scope unless you explicitly choose user-wide sessions. It is not global YOLO or permission to invent work. On Yes, the agent [adds and verifies native rules](docs/reference/getting-started.md#have-your-agent-configure-permissions); No or no answer leaves settings unchanged. An existing explicit choice is reused. Say “Undo the OpenRig command allowances added by this setup” to remove only its additions.
+A team seat with no permission policy, per-seat choice or (for Codex) named profile launches with OpenRig's [team default](docs/reference/rig-spec.md#team-launch-defaults): Claude runs ordinary `rig` commands, project reads and common tests without prompting, while lifecycle commands such as `rig up` and `rig down` still ask; Codex also gets the OpenRig workspace and its pod's state directory as writable directories. Before launching, your agent recommends keeping that default, and offers to remember selected OpenRig commands in your native settings only if you want that, at personal project scope unless you explicitly choose user-wide sessions. It is not global YOLO or permission to invent work. On Yes, the agent [adds and verifies native rules](docs/reference/getting-started.md#have-your-agent-configure-permissions); No or no answer keeps the team default and leaves settings unchanged. An existing explicit choice is reused. Say “Undo the OpenRig command allowances added by this setup” to remove only its additions.
+
+If permission prompts are slowing you down, consider the
+[workshop bundle](https://openrig.dev/rigs/workshop). It ships with broad access
+and [non-interruptive mode](docs/reference/non-interruptive-mode.md): its agents
+bypass permission prompts and supported harness warning dialogs. The listing
+and before-install view explain that access before you choose it.
 
 Check `tmux -V` and only your selected CLI/login: `claude --version` plus
 `claude auth status`, or `codex --version` plus `codex login status`. If needed,
 sign in once with `claude auth login` or `codex login`; do not install or log in
 to an unused provider.
 
-| Team | Starter | Models |
-| --- | --- | --- |
-| Two Codex agents | `first-project` | Both `gpt-6-astra` (unchanged) |
-| Two Claude agents | `first-project-claude` | Configured native Claude default |
-| Claude owner + Codex checker | `first-project-mixed` | Claude default + `gpt-6-astra` |
+### Your agent opens OpenRig for you
 
-All three use the same owner/checker roles and task. Show the selected runtime,
-configured model and command before launch; confirm the account supports the
-model instead of silently falling back. The kernel starts automatically and
-selects from available authenticated providers independently of these two project
-agents. A missing unused provider is not a setup requirement.
+After installing, your agent opens the OpenRig TUI and the operator for you. To get back to them later, ask your
+agent for OpenRig or your agents in any words. After checking the selected login, it runs:
+
+```sh
+rig daemon start  # if stopped
+rig terminal open saved:kernel --window
+```
+
+`--window` opens a new terminal tab or window itself, or a space in your current
+Herdr session. Below 120 measured columns,
+the **operator** fills the first page; from 120, the dashboard and operator share
+it equally. The advisor has a separate tab or tmux window.
+An installing agent can run it from its shell on the daemon's
+desktop; the person copies nothing. It uses Herdr when installed, otherwise
+the same layout in plain tmux, and preserves existing conversations. `rig tui`
+is the team dashboard. Installation is finished when you are talking to the
+operator; if you choose to talk later, that handoff remains pending.
+
+If setup stops, read the named step: missing tools and selected-provider logins
+need their specific setup action. A harness permission rule, sandbox or automatic
+permission decision can also block the installing agent's command. The agent
+should name the command and reported reason, then help you resolve that specific
+step within your chosen permissions. A permission refusal is not an OpenRig
+installation result.
+
+The desktop may need an Automation approval; SSH/headless sessions may have no
+display. Herdr can show first-run panels, and an 80×24 window can cramp the view.
+Follow [the OpenRig view checks and next steps](docs/reference/getting-started.md#what-can-interrupt-installation-and-the-openrig-view).
+Herdr is visible only inside a terminal you can see. Changing the shared TUI to
+`:terminals` does not open that terminal. The agent checks the visible window when
+it has desktop access and says what it could not verify otherwise. Over headless
+SSH, it asks you to open a new terminal window or tab and gives the exact connection
+and attachment command for the current view. If you choose a manual attachment
+after a failure,
+ask the installing agent for the exact command using your current operator
+session; run that in a new terminal window.
+
+The kernel's operator helps you pick a first team. It asks what you want to build,
+recommends one of three, and fits it to the providers you have.
+
+| Team | Talk to | Agents and purpose |
+| --- | --- | --- |
+| `starter` | `dev-build@starter` | A Claude Code builder and Codex reviewer for one bounded change |
+| `workshop` | `orch-lead@workshop` | A lead, builder, QA and reviewer for ongoing work in one repository; a rig bundle the operator installs from its pinned listing |
+| `factory` | `orch-lead@factory` | Seven: a lead, advisor, build, QA, design and two independent reviewers for sustained product work |
+
+As shipped, `starter` uses both Claude Code and Codex. With only one of them, ask
+the kernel operator to adapt it: it writes a copy of the team for your providers
+under the same name. `first-project` is starter's old name and still starts it,
+unless you already have a rig named `first-project` or `starter`: then it refuses
+and names the `rig up <name> --existing` command that brings that rig back.
+Show the selected runtime, configured model and command before launch; confirm the
+account supports the model instead of silently falling back. The kernel starts
+automatically and selects from available authenticated providers independently of
+these teams. A missing unused provider is not a setup requirement.
+
+To launch the starter yourself instead (the manual path, without the operator):
 
 ```bash
 cd /path/to/your/repository
-starter=first-project  # or first-project-claude or first-project-mixed
-rig specs preview "$starter" --kind rig
-rig up "$starter" --cwd . --plan
-rig up "$starter" --cwd .
-rig tui --shared
+rig specs preview starter --kind rig
+rig up starter --cwd . --plan
+rig up starter --cwd .
 ```
 
-The kernel provides separate operational support and the shared dashboard. To detach without stopping the dashboard, press Ctrl-b then d; `rig tui --shared` returns to that view. Plain `rig tui` opens an independent view. Closing a viewing terminal does not mean you should relaunch the team.
+To see your agents, use `rig terminal open saved:kernel --window`. If that window cannot open, `rig tui --shared` is the named dashboard-only fallback; it does not show the operator conversation. The installing agent should resolve or explain the window failure, not finish by suggesting a command for you to type. Closing a viewing terminal does not mean you should relaunch the team.
 
-Check project-seat readiness with `rig ps --nodes --rig "$starter"` and resolve any authentication, trust or permission prompt before assigning work. Then give the owner one bounded outcome from your repository:
+Check project-seat readiness with `rig ps --nodes --rig starter` and resolve any authentication, trust or permission prompt before assigning work. If a seat stopped at such a prompt before its startup context arrived, `rig ps` shows the `rig seat continue <seat>` command that delivers it once the prompt is answered. Then give the builder one bounded outcome from your repository:
 
 ```bash
-rig send "dev-owner@$starter" 'Implement <one useful change>. Track the task in the queue and return its ID. Keep it local, verify the behavior, ask dev-check in this rig to check the exact candidate, and record the result and how I can try it.'
-rig queue list --destination "dev-owner@$starter" --limit 1000
+rig send dev-build@starter 'Implement <one useful change>. Track the task in the queue and return its ID. Keep it local, verify the behavior, ask dev-review in this rig to check the exact candidate, and record the result and how I can try it.'
+rig queue list --destination dev-build@starter --limit 1000
 ```
 
-Sending a message does not itself create a queue item; the owner records the task. Read the final artifact and the review of its exact candidate, then return to the same owner for the next change. [The guided first-use path](docs/reference/getting-started.md) covers readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery.
+Sending a message does not itself create a queue item; the builder records the task. Read the final artifact and the review of its exact candidate, then return to the same builder for the next change. [The guided first-use path](docs/reference/getting-started.md) covers readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery.
 
 Not setting this up today? Get the next walkthrough and occasional OpenRig updates → https://openrig.dev/follow
 
@@ -91,11 +156,12 @@ using a published package, since repository guidance can be ahead of npm.
 
 | When | What changes and why |
 | --- | --- |
-| **npm installation** | Installs the CLI, bundled components and dependencies under your npm prefix (with Bun, under Bun's global directory). OpenRig's postinstall checks the Node.js version and that the SQLite module loads; Bun may block this script. It does not run daemon or provider setup. |
-| **`rig setup`** | Attempts missing tools and writes an OpenRig block in `~/.tmux.conf` for mouse support and scrollback. On macOS it can install cmux and enable its automation socket control in `~/.config/cmux/settings.json`; cmux defaults `automation.socketControlMode` to `cmuxOnly`, which only accepts processes started inside cmux and so blocks OpenRig's control, so setup switches it to `automation`. `--full` adds workstation tools. `--dry-run` shows setup's plan without applying it. |
-| **Daemon startup** | Creates/updates instance state under `OPENRIG_HOME` (normally `~/.openrig`), including its database and managed plugin resources. Seeds the `openrig-skills` discovery skill in `~/.claude/skills` and `~/.agents/skills`, subject to existing version ownership. With `runtime.codex.hooks_enabled` enabled (the default), writes Codex hook configuration and trust records as described below—even before a rig launches. |
-| **Rig/seat launch and attachment** | Creates tmux sessions, supplies seat identity and daemon connection environment, and projects selected guidance, skills, plugins and runtime resources into the workspace. Managed startup pre-trusts the workspace. Claude context collection can also be provisioned for attached sessions and refreshed during monitoring. |
-| **Explicit permission configuration** | The built-in bootstrap does **not** add `rig` command allow rules. Agent-guided setup recommends Yes and requires your actual answer before the agent [adds rules at your chosen scope](docs/reference/getting-started.md#have-your-agent-configure-permissions). No/no answer preserves settings; existing choices and stricter rules remain relevant. Broader access is separate. |
+| **npm installation** | Installs the CLI (`rig` and `openrig-tui`), bundled components and dependencies under your npm prefix (with Bun, under Bun's global directory). OpenRig's postinstall checks the Node.js version and that the SQLite module loads; Bun may block this script. It does not run daemon or provider setup. |
+| **`rig setup`** | Attempts missing tools and writes an OpenRig block in `~/.tmux.conf` for mouse support and scrollback. Installs herdr by default on macOS and Linux unless declined with `--no-herdr`; an unavailable herdr install is a warning. On macOS the installing agent offers Ghostty, and `--ghostty` attempts it after acceptance. Existing cmux settings are left unchanged. `--full` adds workstation tools. `--dry-run` shows setup's plan without applying it. |
+| **Daemon startup** | Creates/updates instance state under `OPENRIG_HOME` (normally `~/.openrig`), including its database and managed plugin resources. Seeds the `openrig-skills` discovery skill, the `refocusing` skill and the person-facing `rigs` skill in `~/.claude/skills` and `~/.agents/skills`, subject to existing version ownership. With `runtime.codex.hooks_enabled` enabled (the default), writes Codex hook configuration and trust records as described below—even before a rig launches. |
+| **Rig/seat launch and attachment** | Creates tmux sessions, supplies seat identity and daemon connection environment, and projects selected guidance, skills, plugins and runtime resources into the workspace. Managed startup pre-trusts the workspace. Claude context collection can also be provisioned for attached sessions and refreshed during monitoring. In a Git repository, newly created files under `.codex/plugins/shared:openrig-core/` (or the unqualified `.codex/plugins/openrig-core/`) are added to the repository's Git `info/exclude` inside an `# BEGIN OpenRig generated files` block; new `AGENTS.md`, `CLAUDE.md` and `CLAUDE.local.md` files stay visible with a warning. |
+| **Bundle install** (`rig bundle install`, or `rig up` with a `.rigbundle` or GitHub link) | Writes the bundle's files into the install target: `--target`, or the current directory for `rig up` and for a GitHub link. `rig bundle install` with a local archive needs `--target`. Routes its declared skills, plugins and context packs into your libraries. A GitHub link's archive is kept under `OPENRIG_HOME/bundle-imports/`, and installs are recorded in `OPENRIG_HOME/bundle-audit.jsonl`. A bundle that carries a project creates it under `workspace.projects_root` and records it, with the rig's association, in the workspace catalog. |
+| **Explicit permission configuration** | The built-in bootstrap does **not** add `rig` command allow rules to your settings files; a team seat with no permission policy, per-seat choice or (for Codex) named profile gets the per-launch [team default](docs/reference/rig-spec.md#team-launch-defaults) instead. Agent-guided setup recommends keeping it and requires your actual answer before the agent [adds remembered rules at your chosen scope](docs/reference/getting-started.md#have-your-agent-configure-permissions). No/no answer keeps the team default and preserves settings; existing choices and stricter rules remain relevant. Broader access is separate. |
 
 The provider files are separate from instance state. Here `~` means the daemon
 user's home; changing `OPENRIG_HOME` alone does not isolate provider configuration.
@@ -103,9 +169,11 @@ user's home; changing `OPENRIG_HOME` alone does not isolate provider configurati
 - **Claude Code:** startup writes workspace trust and onboarding completion.
   With an explicit permission mode, it uses the launch-selected `HOME/.claude.json`,
   or `<CLAUDE_CONFIG_DIR>/.claude.json` when that variable is set. Classic startup
-  retains the daemon's `~/.claude.json` path. In the workspace, `.claude/settings.local.json` receives
+  writes `HOME/.claude.json`, and also `<CLAUDE_CONFIG_DIR>/.claude.json` when the
+  daemon has that variable set. In the workspace, `.claude/settings.local.json` receives
   the context collector's `statusLine` command and selected activity hooks;
-  helper scripts live under `.openrig/`. Selected settings/MCP resources can also
+  the collector script lives under `.openrig/`, and the activity-hook relay under
+  the instance's `state/claude-activity-hooks/`. Selected settings/MCP resources can also
   change that settings file and `.mcp.json`. The shared settings resource sets
   `permissions.defaultMode` to `acceptEdits` and enables Exa/Context7 MCP entries;
   selected MCP resources configure those external services. Built-in bootstrap
@@ -115,8 +183,9 @@ user's home; changing `OPENRIG_HOME` alone does not isolate provider configurati
   `~/.codex/config.toml`). Startup enables hooks, adds the OpenRig activity relay
   commands and pre-writes trust hashes for those commands. Seat startup adds
   `trust_level = "trusted"` for the workspace; selected config resources can
-  add MCP settings. Recognized update notices can be skipped during launch,
-  recording the skipped version in Codex's cache; this is not an update install.
+  add MCP settings. Managed launches pass `-c check_for_update_on_startup=false`,
+  which writes no config; a recognized update notice that still appears can be
+  skipped, recording the skipped version in Codex's cache; this is not an update install.
 
 Activity relays send event type/subtype, seat/runtime identity, timestamps and
 native session identity to the configured OpenRig daemon's `/api/activity/hooks`
@@ -131,14 +200,38 @@ Managed launches supply `HOME`, `CODEX_HOME` and `OPENRIG_*` identity/connection
 variables. Claude uses `--permission-mode acceptEdits` and defaults to the classic
 renderer for terminal scrollback. Codex uses `-s workspace-write` unless a named
 profile governs its sandbox; the default does not force an approval-policy flag.
+On that plain launch OpenRig first asks Codex for its own configuration and adds
+`-c sandbox_workspace_write.network_access=true` only when Codex answers that no
+configuration layer sets network access and no managed requirement could restrict
+it, so the seat can reach the local daemon. If Codex can't be asked or doesn't
+answer in time, the launch is left unchanged.
 Fresh Codex launches also add writable access to the workspace's `.git` and the
 pod's shared queue-state directory with `--add-dir`; the shared root comes from
 `OPENRIG_SHARED_DOCS_ROOT` or `~/.openrig/shared-docs`.
+A team seat with no permission policy, per-seat choice or (for Codex) named
+profile also gets the per-launch team default: Claude gets `--settings` allowing
+ordinary `rig` commands, project reads and common tests, with a session-only
+PreToolUse hook that asks before lifecycle commands, and Codex also gets the
+OpenRig workspace root as a writable directory. Neither writes a permission file.
+Seats of the rig named `kernel` launch with an operational default instead,
+unless a permission policy, a per-seat choice or (for Codex) a named profile
+applies: Claude in `acceptEdits` with a per-launch allow list for its file tools,
+web fetches and operational commands (including reads under your home folder),
+and Codex with `-s danger-full-access -a never`. Neither writes a permission file.
 YOLO is **off by default**. An explicitly selected full-bypass policy selects
 Claude's `--dangerously-skip-permissions` or Codex's
 `-s danger-full-access -a never`. The legacy environment-only `OPENRIG_YOLO=1`
-path still selects only Codex's sandbox; a resolved policy overrides that
-environment setting.
+path, with no policy attached, selects Claude's bypass flag, Pi's `--approve` and
+Codex's `-s danger-full-access` without `-a never`; a resolved policy overrides
+that environment setting. The `builtin:auto` policy launches Claude with
+`--permission-mode auto`; Codex and Pi seats launch as they do without a policy (a
+named Codex profile still governs its sandbox, and Pi keeps its configured
+resource trust).
+`--non-interruptive` on `rig up` or `rig bundle install` additionally passes
+per-launch flags to full-bypass seats so Claude's bypass warning and Codex's
+full-access and GPT-5.1 migration notices don't stop startup; it writes nothing to
+their settings files and is saved on the rig. See
+[non-interruptive mode](docs/reference/non-interruptive-mode.md).
 
 Permission mode controls native execution permissions; work posture is separate
 project guidance. Use `rig policy permissions list|show|current|apply` for rig
@@ -177,29 +270,22 @@ OpenRig is a multi-agent harness — it manages the system that coding agents fo
 
 Every agent runs in a tmux session you can attach to, inspect, and work with directly.
 
-## Starter Rigs
-
-Use `first-project`, `first-project-claude`, or `first-project-mixed` for the
-same focused first-use path on your selected providers. `product-team` is an optional
-larger product-development example:
-
-```bash
-rig specs preview product-team --kind rig
-rig up product-team
-```
+## Teams
 
-Use it when you want a larger product squad: two orchestrators, implementation, QA, design, and two independent reviewers.
+Three teams grow with you, and the kernel operator helps you pick one:
 
-For a smaller starter, use `conveyor`:
+- **`starter`**: a builder and a reviewer for one bounded change.
+- **`workshop`**: a lead, a builder, QA and a reviewer for ongoing work in one repository. It's a rig bundle, installed from its pinned listing.
+- **`factory`**: seven agents (a lead, an advisor, build, QA, design and two independent reviewers) for sustained product work. You bring ideas to the advisor, and the lead runs the team.
 
 ```bash
-rig specs preview conveyor --kind rig
-rig up conveyor
+rig specs preview factory --kind rig
+rig up factory
 ```
 
-`conveyor` is a four-seat starter mixing Claude Code and Codex. It shows a handoff path through intake, planning, build, and review; `first-project` remains the smaller two-seat starting point.
+Specialist teams: `code-review` (two independent reviews), `research` (an analyst and a synthesizer) and `pm` (a product lead, a researcher and a builder for prototypes).
 
-Also ships: `implementation-pair`, `adversarial-review`, `research-team`, and `secrets-manager` (HashiCorp Vault managed by a specialist agent).
+Also built in: `secrets-manager`, a HashiCorp Vault instance run by a specialist agent.
 
 Browse the library:
 
@@ -237,21 +323,21 @@ The TUI shows the team's coordination state; herdr and cmux show the actual agen
 With herdr installed and connected, open the starter's terminals together:
 
 ```bash
-rig terminal open first-project --provider herdr
+rig terminal open starter --provider herdr
 ```
 
-For cmux, use `--provider cmux`. In the TUI, a rig's detail view has a `term ▸ rig <name>` link that opens every running seat of that rig in the default terminal provider; with herdr that is up to 16 seats per tab, in a workspace named after the rig. The underlying sessions remain accessible through tmux. See the [terminal workspace guide](docs/reference/getting-started.md#share-the-dashboard-and-return-to-it) for setup and returning to an existing view.
+For cmux, use `--provider cmux`. In the TUI, a rig's detail view has an `Open terminals ▸ rig <name>` link that opens a terminal view of the running seats of that rig (in a new window or tab, or the current Herdr session), laid out with herdr when installed, otherwise plain tmux; with herdr that is up to 16 seats per tab, in a workspace named after the rig. A seat it can't attach is reported as absent or degraded. The underlying sessions remain accessible through tmux. See the [terminal workspace guide](docs/reference/getting-started.md#share-the-dashboard-and-return-to-it) for setup and returning to an existing view.
 
 ## Key Concepts
 
 - **RigSpec**: Declarative multi-agent harness definition in YAML. Pods, members, edges, continuity policies, culture file.
 - **AgentSpec**: Reusable agent blueprint with skills, guidance, hooks, profiles, and startup contracts.
-- **Seat**: A stable role and address in a rig, such as `dev-owner@first-project`. The conversation occupying it can change while its identity and authored context remain.
+- **Seat**: A stable role and address in a rig, such as `dev-build@starter`. The conversation occupying it can change while its identity and authored context remain.
 - **Pod**: A group of related seats with shared guidance and context. Each agent still has its own context window.
 - **Discovery**: `rig discover` fingerprints existing tmux sessions. `rig adopt` brings them under management.
-- **Snapshot/Restore**: `rig down --snapshot` captures full state. `rig up <name>` restores from latest snapshot. Restore reports per-node outcomes (resumed, fresh, or failed).
-- **RigBundle**: Portable archive with vendored AgentSpecs and SHA-256 integrity. Share topologies across machines.
-- **Culture**: CULTURE.md sets coordination norms for the group. Research rigs get exploratory culture. Implementation rigs get conservative, trust-but-verify culture.
+- **Snapshot/Restore**: `rig down --snapshot` captures full state. `rig up <name>` restores from latest snapshot. Restore reports per-node outcomes: resumed, fresh-primed, awaiting-decision (the original conversation can't resume; choose `--fresh`), attention_required, or failed.
+- **RigBundle**: Portable archive with vendored AgentSpecs and SHA-256 integrity. Share topologies across machines. `rig up`, `rig bundle create`, `inspect` and `install` also take a GitHub folder link, `rig bundle check` checks a folder before you share it, and `rig bundle inspect` shows what a bundle will do before you install it. See [publishing a rig bundle](docs/reference/publishing-a-rig-bundle.md).
+- **Culture**: A rig's `CULTURE.md` (its `culture_file`) sets coordination norms for the group, on top of OpenRig's default culture, which every seat receives.
 
 ## Agent-Managed Software
 
@@ -267,7 +353,7 @@ Requires Docker for service-backed rigs.
 
 ## Upgrading an existing instance
 
-For an existing installation, follow the [upgrade procedure](skills/_canonical/core/openrig-upgrade/SKILL.md) and the [0.5.14 release notes](docs/releases/v0.5.14.md). Preserve live seats during the upgrade; `rig down` is not an upgrade step. Upgrading to 0.6.0 also requires Node.js 22 or 24: see [Moving off Node 20](#moving-off-node-20) and the [0.6.0 release notes](docs/releases/v0.6.0.md).
+For an existing installation, follow the [upgrade procedure](skills/_canonical/core/openrig-upgrade/SKILL.md) and the [0.5.14 release notes](docs/releases/v0.5.14.md); notes for later releases are in [CHANGELOG.md](CHANGELOG.md). Preserve live seats during the upgrade; `rig down` is not an upgrade step. Upgrading to 0.6.0 also requires Node.js 22 or 24: see [Moving off Node 20](#moving-off-node-20) and the [0.6.0 release notes](docs/releases/v0.6.0.md).
 
 ### Moving off Node 20
 
@@ -339,7 +425,9 @@ seat, plugin, and release lifecycle actions remain agent-owned.
   longer supported. Node 26 and other versions are untested. On a Mac with Apple
   silicon, use Node.js 22: see the [compatibility history](docs/releases/v0.5.15.md#known-compatibility-limitation).
 - tmux
-- macOS or Linux. Native Windows is not supported yet, and WSL2 has not been tested
+- macOS or Linux. On Windows, use WSL2, the Windows route OpenRig supports; native
+  Windows isn't supported. OpenRig's automated tests don't run on WSL2 yet; one user's
+  working setup is in the [getting-started guide](docs/reference/getting-started.md#wsl2-a-reported-working-setup)
 
 Optional:
 - herdr or cmux for terminal workspaces showing the agents together
@@ -347,9 +435,9 @@ Optional:
 
 ## Setup and Troubleshooting
 
-- `rig setup` attempts core machine preparation: tmux, cmux, Claude Code, Codex, and tmux defaults. It reports what it tried and what actually succeeded. If something fails, it gives the local agent enough context to finish the job.
-- `rig setup --full` attempts a broader operator workstation setup (jq, gh) on top of core.
-- `rig doctor` inspects current system health and helps diagnose problems after setup. Use it when something stops working or after machine changes.
+- `rig setup` attempts core machine preparation: it installs a missing Claude Code or Codex and writes tmux defaults. It installs Herdr by default on macOS and Linux; use `--no-herdr` if you decline it. On macOS it also installs a missing tmux with an existing Homebrew; elsewhere install tmux yourself (setup only checks it). On a Mac, the installing agent offers Ghostty once; accepting uses `rig setup --ghostty`, and declining leaves Terminal.app available. Existing cmux settings are preserved. It reports what it tried and what actually succeeded. If something fails, it gives the local agent enough context to finish the job.
+- `rig setup --full` attempts a broader operator workstation setup (jq, gh, via Homebrew, so macOS only) on top of core.
+- `rig doctor` inspects current system health and helps diagnose problems after setup. Use it when something stops working or after machine changes. It shares setup's local provider login checks. These do not prove provider acceptance or a working agent; also inspect `rig ps --nodes --rig <rig>`.
 
 Both commands support `--json` for agent-driven workflows.
 
@@ -357,7 +445,7 @@ Before setup or managed launch, review [what OpenRig changes on your machine](#w
 
 Already-running adopted sessions may need restart before they pick up newly written runtime config.
 
-**For agents:** First ask which available provider(s) the user wants, reusing an explicit choice. Recommend the working account they already have and follow the selected-provider guide above. Offer core setup (`rig setup`) or the fuller workstation path (`rig setup --full`) only when they want those additional tools. Inspect the result with `--json` and use `rig doctor` to finish any remaining machine-specific issues. When OpenRig itself misbehaves, read [docs/reference/help.md](docs/reference/help.md) (installed agents can run `rig context get help`; the same text is at [openrig.dev/help/agents](https://www.openrig.dev/help/agents)): it covers the next step, known problems, and how to reach the team if you're still stuck.
+**For agents:** First ask which available provider(s) the user wants, reusing an explicit choice. Recommend the working account they already have and follow the selected-provider guide above. Offer core setup (`rig setup`) or the fuller workstation path (`rig setup --full`) only when they want those additional tools. Inspect the result with `--json` and use `rig doctor` to finish any remaining machine-specific issues. Then start the daemon if it is stopped, open the OpenRig TUI and operator for them (say so, then run `rig terminal open saved:kernel --window --json`; no commands for the person to copy), and hand the person's goal and project folder to the kernel operator ([installing-agent handoff](docs/reference/getting-started.md#installing-agent-handoff)). Installation is finished when the person is talking to the operator; don't implement the project yourself. When OpenRig itself misbehaves, read [docs/reference/help.md](docs/reference/help.md) (installed agents can run `rig context get help`; the same text is at [openrig.dev/help/agents](https://www.openrig.dev/help/agents)): it covers the next step, known problems, and how to reach the team if you're still stuck.
 
 ## Comparison with Claude Managed Agents
 

package/daemon/assets/claude-team-permissions.cjs

@@ -0,0 +1,262 @@
+"use strict";
+
+// Session-only Claude PreToolUse helper. The launcher supplies the kernel or team
+// lists; this file never reads or writes a person's permission settings.
+// This is command convenience, not containment (test runners can execute code).
+const { basename, isAbsolute } = require("node:path");
+
+function scanQuotes(text, keepDouble = false, initial = "", arithmetic = 0) {
+  let out = "", state = initial, start = 0, arithmeticStart = 0, wordStarted = Boolean(initial);
+  const spans = [];
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (state === "'") { if (c === "'") { state = ""; spans.push([start, i]); out += "'"; } continue; }
+    if (state === '"') {
+      if (c === "\\") { if (keepDouble) out += c + (text[i + 1] || ""); i++; continue; }
+      if (c === '"') { state = ""; spans.push([start, i]); out += '"'; continue; }
+      if (keepDouble) out += c;
+      continue;
+    }
+    if (c === "\\") { out += c + (text[i + 1] || ""); i++; wordStarted = true; continue; }
+    if (c === "'" || c === '"') { state = c; start = i; out += c; wordStarted = true; continue; }
+    if (arithmetic) {
+      if (c === "(") arithmetic++;
+      if (c === ")" && --arithmetic === 0) spans.push([arithmeticStart, i]);
+      out += c;
+      continue;
+    }
+    if (c === "#" && !wordStarted) {
+      const end = text.indexOf("\n", i);
+      spans.push([i, end === -1 ? text.length : end]);
+      i = end === -1 ? text.length : end - 1;
+      continue;
+    }
+    if (c === "(" && text[i + 1] === "(") {
+      arithmetic = 2; arithmeticStart = i; out += "(("; i++; continue;
+    }
+    wordStarted = !/[\s;&|()<>]/.test(c);
+    out += c;
+  }
+  if (state) spans.push([start, text.length]);
+  if (arithmetic) spans.push([arithmeticStart, text.length]);
+  return { text: out, spans, state, arithmetic };
+}
+
+// Split heredoc bodies off the command text. Quoted delimiters ('EOF', "EOF") make a literal body that never runs;
+// an unquoted delimiter's body still expands substitutions, so it is returned for substitution checks only.
+// Only operators outside quotes, comments and arithmetic can start a heredoc.
+// A missing closing delimiter leaves the remaining text in place for conservative ask detection.
+function splitHeredocs(cmd) {
+  const lines = cmd.split("\n");
+  const main = [];
+  const expanding = [];
+  // Quote state carries across lines: a double-quoted commit message can span several lines, and a `<<` after its
+  // closing quote is still an operator. Heredoc bodies are skipped, so they never change the state.
+  let carry = "", arithmetic = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    main.push(line);
+    const scanned = scanQuotes(line, false, carry, arithmetic);
+    const { spans } = scanned;
+    carry = scanned.state;
+    arithmetic = scanned.arithmetic;
+    const found = [...line.matchAll(/(?<!<)<<(-?)(?!<)\s*(?:'([^']+)'|"([^"]+)"|\\?([A-Za-z_][A-Za-z0-9_]*))/g)]
+      .filter(m => !spans.some(([a, b]) => m.index >= a && m.index <= b));
+    let j = i;
+    for (const m of found) {
+      const delim = m[2] || m[3] || m[4];
+      const quoted = Boolean(m[2] || m[3] || m[0].includes("\\"));
+      const end = lines.findIndex((l, k) => k > j && (m[1] ? l.replace(/^\t+/, "") : l) === delim);
+      if (end === -1) continue;
+      const body = lines.slice(j + 1, end).join("\n");
+      if (!quoted) expanding.push(body);
+      j = end;
+    }
+    i = j;
+  }
+  return { main: main.join("\n"), expanding };
+}
+
+// Bodies of $( ... ) (balanced) and `...`; the text must already have single-quoted strings removed.
+function substitutions(text) {
+  const out = [];
+  const t = text.replace(/\\[`$]/g, "");
+  for (let i = 0; i < t.length; i++) {
+    if (t[i] === "$" && t[i + 1] === "(") {
+      let depth = 1, k = i + 2;
+      for (; k < t.length && depth; k++) { if (t[k] === "(") depth++; else if (t[k] === ")") depth--; }
+      out.push(t.slice(i + 2, depth ? k : k - 1));
+      i = k - 1;
+    } else if (t[i] === "`") {
+      const k = t.indexOf("`", i + 1);
+      if (k === -1) { out.push(t.slice(i + 1)); break; }
+      out.push(t.slice(i + 1, k));
+      i = k;
+    }
+  }
+  return out;
+}
+
+// Decode literal shell words without executing anything. Keep command boundaries
+// for lifecycle asks, but never allow an entire compound/expanding command.
+function words(command, comments = true) {
+  const commands = [];
+  let tokens = [], word = "", started = false, literal = true, quote = "", simple = true, rawWord = "";
+  const flush = () => {
+    if (started) tokens.push({ value: word, literal, assignment: /^[A-Za-z_][A-Za-z0-9_]*=/.test(rawWord) });
+    word = ""; rawWord = ""; started = false; literal = true;
+  };
+  const boundary = () => { flush(); if (tokens.length) commands.push(tokens); tokens = []; };
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (quote || !/\s/.test(c)) rawWord += c;
+    if (quote === "'") {
+      if (c === "'") quote = ""; else word += c;
+    } else if (c === "\\" && quote !== "'") {
+      const next = command[++i];
+      if (next === undefined) { simple = false; literal = false; break; }
+      if (next !== "\n") word += quote === '"' && !'$`"\\'.includes(next) ? "\\" + next : next;
+      started = true;
+    } else if (quote === '"') {
+      if (c === '"') quote = "";
+      else { word += c; if (c === "$" || c === "`") { literal = false; simple = false; } }
+    } else if (c === "'" || c === '"') {
+      quote = c; started = true;
+    } else if (comments && c === "#" && !started) {
+      while (i + 1 < command.length && command[i + 1] !== "\n") i++;
+    } else if (";&|\n()<>".includes(c)) {
+      boundary(); simple = false;
+    } else if (/\s/.test(c)) flush();
+    else {
+      started = true; word += c;
+      if ("$`*?[]{}~".includes(c)) { literal = false; simple = false; }
+    }
+  }
+  if (quote) { literal = false; simple = false; }
+  boundary();
+  return { commands, simple: simple && commands.length === 1 };
+}
+
+function normalize(tokens, forAllow = false) {
+  const result = [...tokens];
+  while (result.length) {
+    const first = result[0];
+    if (first.assignment) {
+      // These can change the executable or inject startup code. Ask detection
+      // still looks through them; an allowance leaves them to native checks.
+      if (forAllow && /^(?:PATH|LD_[A-Za-z0-9_]*|DYLD_[A-Za-z0-9_]*|NODE_OPTIONS|BASH_ENV|ENV)=/.test(first.value)) return [];
+      result.shift();
+    }
+    else if (first.literal && ["env", "command", "exec"].includes(basename(first.value))) {
+      if (forAllow && first.value.includes("/") && !isAbsolute(first.value)) return [];
+      // command -v/-V inspects an executable rather than wrapping its execution.
+      if (basename(first.value) === "command" && ["-v", "-V"].includes(result[1]?.value)) break;
+      result.shift();
+      if (result[0]?.value === "--") result.shift();
+      // Other wrapper options (including sudo) stay with native checks.
+    } else break;
+  }
+  if (!result[0]?.literal) return [];
+  const executable = result[0].value;
+  if (forAllow && executable.includes("/") && !isAbsolute(executable)) return [];
+  result[0] = { value: basename(executable), literal: true };
+  if (/\/(?:node_modules\/\.bin)\/(vitest|jest)$/.test(executable)) {
+    result.unshift({ value: "npx", literal: true });
+  }
+  if (result[0].value === "rig") {
+    // Host selection does not change the lifecycle being requested.
+    while (result[1]?.literal && /^--host(?:=|$)/.test(result[1].value)) {
+      if (result[1].value === "--host") {
+        if (!result[2] || (forAllow && !result[2].literal)) return [];
+        result.splice(1, 2);
+      } else result.splice(1, 1);
+    }
+  }
+  return result;
+}
+
+function prefixEnd(tokens, prefix) {
+  let i = 0;
+  for (const part of prefix) {
+    // Commander accepts separators before a subcommand, including at root.
+    // A separator AFTER the lifecycle prefix still terminates help options.
+    while (prefix[0] === "rig" && i > 0 && tokens[i]?.literal && tokens[i].value === "--") i++;
+    if (!tokens[i]?.literal || tokens[i].value !== part) return undefined;
+    i++;
+  }
+  return i;
+}
+
+function prefixes(rules) {
+  return rules.flatMap(rule => {
+    const match = /^Bash\((.+):\*\)$/.exec(rule);
+    return match ? [match[1].split(" ")] : [];
+  });
+}
+
+function helpOnly(tokens, prefixLength) {
+  // A separator before a subcommand also makes its remaining words operands.
+  // For example, the CLI dispatches `rig -- down --help` on a rig named --help.
+  if (tokens.slice(1, prefixLength).some(t => t.value === "--")) return false;
+  const args = tokens.slice(prefixLength);
+  // A help-looking option value or text after -- is not a help invocation.
+  // Commander also accepts help before positional arguments.
+  const help = args.findIndex(t => ["--help", "-h"].includes(t.value));
+  return help !== -1 && args.every(t => t.literal)
+    && args.slice(0, help).every(t => !t.value.startsWith("-"));
+}
+
+function decide(command, policy, depth = 0) {
+  if (depth > 4) return undefined;
+  const { main, expanding } = splitHeredocs(command);
+  // Substitutions in double quotes and unquoted heredocs still execute. Literal
+  // multiline strings and quoted heredocs are data, not lifecycle invocations.
+  for (const source of [scanQuotes(main, true).text, ...expanding]) {
+    for (const inner of substitutions(source)) {
+      if (decide(inner, policy, depth + 1) === "ask") return "ask";
+    }
+  }
+  const parsed = words(main.trim());
+  const asks = prefixes(policy.ask);
+  const askExecutables = new Set(asks.map(prefix => prefix[0]));
+  // Retain comment text for asks too: a # inside backticks or ${...} must not
+  // hide a later command. Keep the comment-aware scan as well, so quotes in a
+  // real comment cannot swallow the following line. Allow parsing is unchanged.
+  for (const command of [...parsed.commands, ...words(main.trim(), false).commands]) {
+    // ponytail: ask conservatively at every word position rather than owning a
+    // second shell grammar for wrappers/control flow. Unquoted prose may ask;
+    // quoted messages remain single words, and literal heredoc bodies are gone.
+    for (let i = 0; i < command.length; i++) {
+      if (!command[i].literal || !askExecutables.has(basename(command[i].value))) continue;
+      const tokens = normalize(command.slice(i));
+      for (const prefix of asks) {
+        const end = prefixEnd(tokens, prefix);
+        if (end !== undefined && !helpOnly(tokens, end)) return "ask";
+      }
+    }
+  }
+  const tokens = normalize(parsed.commands[0] || [], true);
+  if (!parsed.simple || tokens.some(t => !t.literal)) return undefined;
+  return prefixes(policy.allow).some(prefix => prefixEnd(tokens, prefix) !== undefined) ? "allow" : undefined;
+}
+
+module.exports = { decide };
+if (require.main === module) {
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", chunk => { raw += chunk; });
+  process.stdin.on("end", () => {
+    try {
+      const input = JSON.parse(raw);
+      if (input.tool_name !== "Bash" || typeof input.tool_input?.command !== "string") return;
+      const policy = JSON.parse(Buffer.from(process.argv[2], "base64").toString("utf8"));
+      const decision = decide(input.tool_input.command, policy);
+      if (decision) process.stdout.write(JSON.stringify({ hookSpecificOutput: {
+        hookEventName: "PreToolUse", permissionDecision: decision,
+        permissionDecisionReason: decision === "ask"
+          ? "This rig lifecycle command needs confirmation. Use --help or -h to read its help."
+          : "This command matches the OpenRig session launch allowance.",
+      } }));
+    } catch { /* No decision: retain Claude's own permission handling. */ }
+  });
+}