@openrig/cli 0.6.4-rc.1 → 0.6.5

package/daemon/docs/reference/agent-startup-guide.md

@@ -250,11 +250,14 @@ OpenRig performs best-effort deterministic runtime configuration for managed ses
   installations may retain one; existing user settings are not removed.
 - Claude global state: `~/.claude.json`
   Purpose: pre-trust managed workspaces and mark onboarding complete for fresh managed sessions.
+  Explicit permission modes use the launch-selected `HOME/.claude.json`, or
+  `<CLAUDE_CONFIG_DIR>/.claude.json` when that variable is set. Classic startup
+  retains the daemon-home path.
 - Claude project-local config: `.claude/settings.local.json`
   Purpose: apply context collector/activity hooks and selected `claude_settings_fragment` resources inside the project without committing them to git.
 - Claude project-local MCP config: `.mcp.json`
   Purpose: apply selected `claude_mcp_fragment` resources for Claude in that project.
-- Codex global config: `~/.codex/config.toml`
+- Codex global config: `$CODEX_HOME/config.toml`, or `~/.codex/config.toml` when unset
   Purpose: pre-trust managed workspaces and apply selected `codex_config_fragment` resources. Codex currently has no equivalent project-local MCP config path for global profile settings.
 
 Two important caveats:
@@ -266,6 +269,39 @@ can affect native configuration, but OpenRig's launch flags can override those
 values. Recording a config-surface `permission_policy` is not proof that its
 rules were translated or applied. See [permission precedence and limits](getting-started.md#custom-settings-and-precedence).
 
+### Separate Codex homes for separate installations
+
+Set an **absolute `CODEX_HOME` in the environment that starts the daemon** when
+you want a separate Codex configuration and state root. OpenRig uses that root
+for its startup hook setup/removal and trust records, feature flag, workspace
+trust and selected config fragments. Startup can write those files even when
+the daemon has no seats.
+
+The explicit selection also applies to future managed Codex fresh, resume and
+fork launches, their capability/profile/configuration probes, native thread and
+context reads, and plugin-cache discovery. Launch commands reassert it after
+pane shell startup, so an rc file cannot silently switch that launch to another
+Codex home. Executable and PATH selection stay the same. Existing running
+sessions are not moved or restarted; a thread in another home is not searched
+as a fallback for an explicitly selected home.
+
+**With `CODEX_HOME` unset, a second install still shares `~/.codex`.** Setting only
+`OPENRIG_HOME` separates OpenRig state, not provider configuration. The default
+launch behavior is unchanged, including existing pane-shell overrides.
+
+OpenRig does not copy or migrate authentication, history, rules, trust or
+settings into the selected home. A separate file-backed home needs its intended
+authentication provisioned if absent; OS credential stores and other config
+layers can behave differently, so a new login is not universally required.
+Explicit Codex auth commands resolve their **caller's** `CODEX_HOME`, otherwise
+`$HOME/.codex`; contacting a daemon with `OPENRIG_URL` does not retarget auth
+save/switch/registry writes to that daemon's selection. Set the intended root
+on those commands as well.
+
+This separates provider files, not OS users or accounts. Project-local resources
+still use the selected project directory; shared project and system settings
+remain shared.
+
 ### Runtime Differences
 
 **Claude Code:**
@@ -283,6 +319,14 @@ rules were translated or applied. See [permission precedence and limits](getting
 - Approval policy and sandbox access are separate controls. OpenRig's default
   `-s workspace-write` selects the sandbox; it does not force `-a`. A member's
   `codex_config_profile` selects native `-p`, distinct from the AgentSpec `profile`.
+- On that plain `-s workspace-write` launch (fresh, resume, fork or restore), a
+  short-lived `codex app-server` first reads Codex's own configuration with the
+  seat's executable, home and working directory. OpenRig adds
+  `-c sandbox_workspace_write.network_access=true` only when no configuration
+  layer sets network access and no managed requirement could restrict it. A
+  timeout, error or unrecognized answer adds nothing. Named profiles and full
+  bypass are not read. The read may write Codex's own state files in
+  `CODEX_HOME`, read its login and fetch managed policy, as a Codex start does.
 - Can self-install dependencies from instructions but timer/recurring behavior is not reliably available
 
 When authoring startup content, note which instructions are runtime-specific. For example, an orchestrator that needs a monitoring loop should include instructions like: "If running Claude Code, use `/loop 3m` to periodically check rig health. If running Codex, check rig health at the start of each task cycle instead."
@@ -301,6 +345,41 @@ profile → uses.skills: [openrig-user]
 ```
 This is the minimum effective startup. The agent knows who it is, how the team works, and how to use the rig.
 
+For seats sharing a working directory, keep each role in its own AgentSpec startup entry:
+
+```yaml
+startup:
+  files:
+    - path: guidance/role.md
+      orientation: role
+      delivery_hint: send_text
+      required: true
+```
+
+`rig queue whoami --json` reports only the calling seat's explicitly marked role
+bindings, independently of its current work. The `role.state` is `no-record`,
+`not-declared`, `missing`, `present`, or `unknown` when identity, storage or the
+observation is unavailable. Files retain their original `path`, `absolutePath`
+and `ownerRoot` plus the currently resolved `resolvedPath` and
+`resolvedOwnerRoot`. Built-in packaged paths follow the running installation;
+existing development-checkout paths stay where they were recorded.
+
+`recordedAt` is the startup-context record write/attempt, which happens before
+launch succeeds. Exact resume can retain an older record. `present` means the
+resolved file currently exists, not that its bytes still match the spec or that
+the agent read it. Unmarked startup files and startup actions are not exposed.
+
+Refocus includes the role path and a re-read reminder with topology or both trees,
+even if the trace fails. Work-only mode omits it; disabling refocus still disables
+the entire hook. Custom refocus prose keeps its existing precedence. The hook
+reuses its work lookup, or makes one bounded lookup when the work node is explicit;
+a failed or skipped lookup reports `unknown`.
+
+The shipped kernel seats no longer project their role into shared guidance.
+Existing user files and legacy role blocks are left intact; this is not a cleanup
+of already-installed shared blocks. General user-authored guidance projection is
+unchanged.
+
 **Separate project context from role**
 
 Don't put project documentation inside the role guidance. The role is about the agent's function; project context is about what the agent is working on. Use rig-level or pod-level startup files for project context.
@@ -356,7 +435,7 @@ If your rig REQUIRES a hook to function and the hook installation fails silently
 When creating a new agent's startup experience:
 
 - [ ] Write a `guidance/role.md` — who is this agent?
-- [ ] Reference it in the agent spec's `resources.guidance` AND `startup.files`
+- [ ] Reference it in `startup.files` with `orientation: role` and `delivery_hint: send_text`. Avoid projecting distinct seat roles into one shared `AGENTS.md` or `CLAUDE.md`.
 - [ ] Write a rig `CULTURE.md` if the rig doesn't have one
 - [ ] Choose skills from the shared pool via profile `uses`
 - [ ] Write a `startup/context.md` if the agent needs environment grounding

package/daemon/docs/reference/browser-access.md

@@ -12,7 +12,10 @@ comes from a web page, only when that page is the OpenRig UI or a page you allow
   its own Tailscale name (for example `my-machine.your-tailnet.ts.net`, or the short `my-machine`).
   The daemon learns its own Tailscale name automatically from Tailscale on this machine.
 - The web UI, when it is turned on (`rig config set ui.enabled true`, then restart the daemon) and
-  opened at the daemon's own address and port.
+  opened at the daemon's own address and port. To open it at a non-loopback name or address, such
+  as its Tailscale name, also list that page's exact origin in `OPENRIG_ALLOWED_ORIGINS` (for
+  example `http://my-machine.your-tailnet.ts.net:7433`), then restart the daemon. Without it, the
+  UI's terminal is refused there, and at a non-loopback IPv6 address its API requests are too.
 
 ### When you see a refusal
 

package/daemon/docs/reference/developing.md

@@ -1,8 +1,13 @@
 # Developing OpenRig — gates and lanes
 
 This is the contributor-facing statement of which checks BLOCK a change and which are
-advisory. There is no external CI at this tip: the root `package.json` script chain IS
-the gate, and the release checklists invoke it.
+advisory. Every pull request to `main` runs `.github/workflows/tests.yml` on a clean GitHub
+runner: build and packaging, typecheck, the repository scripts (`npm run test:repo`), each
+workspace's test suite (daemon, cli, tui and ui) on macOS without ambient credentials or
+external network, and an installed-package scenario (`scripts/run-pr-scenarios.sh`). The root
+`package.json` scripts below run the same build, typecheck, repository and test checks locally,
+with one difference: `npm test` does not include the UI suite, which CI runs as
+`package-tests (ui)`. Run `npm run test:ui` for it.
 
 ## Blocking gates (must pass before a candidate moves)
 
@@ -10,23 +15,26 @@ the gate, and the release checklists invoke it.
 |---|---|---|
 | Typecheck | `npm run lint` | daemon + **ui** + cli + tui tsconfigs — UI typecheck STAYS blocking |
 | Build | `npm run build` | all workspaces — the UI dist ships in the package, so its build STAYS blocking |
-| Repo scripts | `npm run test:repo` | script self-tests, docs guard, skill mirror check |
+| Repo scripts | `npm run test:repo` | daemon build, script self-tests, docs guard, skill mirror check, context-pack generation check |
 | Unit tests | `npm run test:workspaces` | `packages/daemon` + `packages/cli` + `packages/tui` |
+| UI unit tests | `npm run test:ui` | `packages/ui` vitest. NOT part of `npm test`, but every pull request runs it as `package-tests (ui)` (the `package-tests` matrix in `.github/workflows/tests.yml`) |
 
-`npm test` runs `test:repo` and `test:workspaces` — the blocking set is readable in the
-script itself.
+`npm test` runs `test:repo` and `test:workspaces`; `npm run test:ui` is the separate UI
+suite. Both sets are readable in the root `package.json` scripts.
 
 ## Advisory lane
 
 | Lane | Command | Meaning |
 |---|---|---|
-| UI unit tests | `npm run test:ui` | runs `packages/ui` vitest at will; NOT part of `npm test` |
+| Portability report | `node scripts/portability-report.mjs` | lists added lines with machine-specific values; findings never fail it (`.github/workflows/portability-report.yml`) |
 
 ## The norm (web-UI freeze at 0.5.0)
 
-Daemon API changes no longer require UI sync or UI verification; the contract mirrors
-under `packages/ui/src/hooks/` are no longer proactively maintained; a new `test:ui`
-failure signals a moved API contract, not a broken gate.
+Daemon API changes no longer require browser or interaction verification of the UI, and
+the contract mirrors under `packages/ui/src/hooks/` are no longer proactively maintained. A
+new `test:ui` failure usually signals a moved API contract. Because pull-request CI runs the
+UI suite as `package-tests (ui)`, the change that moves the contract has to update the affected
+UI test or mirror to pass that check.
 
 Browser/interaction testing of the web UI is not a contributor gate. (The packaged
 starter-rig agent skills that exercise the UI are product content for user rigs, not

package/daemon/docs/reference/getting-started.md

@@ -15,8 +15,13 @@ supported; Node 26 and other versions are untested.
 Codex's `-s workspace-write`, with approval policy from your native configuration,
 or Claude Code's `acceptEdits`, which still leaves commands subject to native
 rules and prompts. Codex's sandbox normally blocks network access, including the
-local OpenRig daemon. A command allowance does not change general sandbox/network
-settings. The starter's `profile: default` selects OpenRig resources, not a native
+local OpenRig daemon, so before that plain launch OpenRig asks Codex for its own
+configuration and adds network access inside the sandbox unless a configuration
+layer sets `sandbox_workspace_write.network_access` or a managed requirement could
+restrict it. To keep it off, set `network_access = false` under
+`[sandbox_workspace_write]` in your Codex configuration. If Codex does not answer
+within a few seconds, the seat starts without it. A command allowance does not
+change general sandbox/network settings. The starter's `profile: default` selects OpenRig resources, not a native
 permission profile.
 Agent-guided setup [asks once](#have-your-agent-configure-permissions): “Allow
 your agents to run OpenRig commands without repeated permission prompts?”

package/daemon/docs/reference/health-diagnosis.md

@@ -132,9 +132,13 @@ these boundaries. One occurrence and the existing owner cooldown apply to each
 episode; a disposition stops repeated requests.
 
 This bounded source covers explicitly linked project or mission work: at most 2,000 touched
-qitems, 200 roots, 1,000 members / 10,000 transitions per family, 200 workflow
+qitems, 1,000 members / 10,000 transitions per family, 200 workflow
 receipts, 200 declared slices, and 100 proof files per selected slice. Overflow
-refuses visibly. Context files are bounded to 64 KiB. A lineage beginning before
+refuses visibly. When more than 200 families (roots) were touched, it evaluates the
+200 with the most transitions in the window, then by lineage ID, and reports the
+result as partial coverage with the total and omitted counts. Omitted families
+were not evaluated, so having no finding for them is not a healthy verdict.
+Context files are bounded to 64 KiB. A lineage beginning before
 the retained window remains indeterminate, with the missing interval named.
 Project planning does not require a successor mission: an explicit project identity
 resolves its current context, with mission and phase absent unless evidenced.
@@ -370,7 +374,10 @@ A consumer such as a later Herder plugin reads `GET /api/health` and
 `GET /api/health/:findingId`, or the identical `rig health --json` and
 `rig health explain <finding-id> --json` records. The record schema is
 `openrig.health/v0alpha1`; list metadata is `openrig.health-list/v0alpha1`.
-Preserve ID, status, policy version, time window, freshness, evidence and
+For a source that bounds its input, list metadata also carries `coverage`
+(`source`, `total`, `evaluated`, `omitted`, `limit`, `order`, `partial`), and
+`rig health policy` reports the scheduled evaluation's coverage under
+`engine.lastEvaluation.coverage`. Preserve ID, status, policy version, time window, freshness, evidence and
 threshold together. There is no health score or implicit remediation authority.
 The default list excludes cleared records; explicit cleared queries and exact
 ID reads retain them while the source can still project them. A recurrence after

package/daemon/docs/reference/help.md

@@ -78,12 +78,17 @@ involved before proposing changes.
 Compare the harness version and what you actually observe before attributing a failure to one of these. Check the
 issue's current status; a similar symptom alone is not a diagnosis.
 
-- Claude seats reported as needing attention after a restore: [#86](https://github.com/mvschwarz/openrig/issues/86).
-- Claude usage limits are not detected: [#98](https://github.com/mvschwarz/openrig/issues/98),
-  [#99](https://github.com/mvschwarz/openrig/issues/99).
-- Codex prompt variants not recognised as ready: [#79](https://github.com/mvschwarz/openrig/issues/79).
+- Claude seats reported as needing attention after a restore: [#86](https://github.com/mvschwarz/openrig/issues/86),
+  [#273](https://github.com/mvschwarz/openrig/issues/273).
+- Claude usage limits may not be detected: [#99](https://github.com/mvschwarz/openrig/issues/99).
+- Codex prompt variants not recognised as idle: [#79](https://github.com/mvschwarz/openrig/issues/79).
 - Codex asks about hook trust at first launch: [#17](https://github.com/mvschwarz/openrig/issues/17), not reproduced
   by the team.
+- A Codex seat on the default `workspace-write` sandbox starts without network access, so it can't reach the local
+  daemon, when its Codex configuration sets network access off, a managed requirement could restrict it, or Codex
+  doesn't answer OpenRig's configuration read in time: [#275](https://github.com/mvschwarz/openrig/issues/275).
+- Stopping the daemon can report a timeout while closing connections:
+  [#166](https://github.com/mvschwarz/openrig/issues/166).
 
 For everything else, search [open issues](https://github.com/mvschwarz/openrig/issues).
 

package/daemon/docs/reference/host-resources.md

@@ -0,0 +1,60 @@
+# Host load and transcript capture
+
+Use `rig ps --resources` to inspect the serving host, or add `--host <id>`
+for one registered HTTP/SSH host. `--json` returns the same measurements for
+operators and monitoring tools. This view is host-scoped; rig/node filters and
+multi-host fan-out do not apply. Ordinary `rig ps` output is unchanged.
+
+The view reports available CPU count, host load averages (1/5/15 minutes),
+load divided by CPU count, running seats, and transcript capture attempts,
+failures, UTF8 bytes and elapsed capture time for currently rotating seats.
+Load is not CPU utilization; capture elapsed time includes waiting for tmux,
+and is not daemon CPU time. Load averages are unavailable on Windows, rather
+than reported as zero. Counters reset when a rotation is restarted/stopped or
+the daemon restarts, so they are observations rather than a durable billing log.
+When no seat is capturing, the active interval, idle ceiling and line count are
+unavailable (`null` in JSON), not zero.
+
+## Reduce idle capture cost
+
+Transcript rotation still captures the bounded trailing buffer. When successive
+captures are unchanged and tmux exposes an unchanged current-window activity
+hint, capture backs off exponentially to a derived ceiling. With the default
+2-second active interval and 1-second settings timer, the effective ceiling is
+3 seconds: the 10-second freshness window minus the 1-second activity-hint
+deadline, 5-second capture-result deadline and 1-second timer spacing. The
+ceiling is capped at 6 seconds but never below the configured active interval.
+This scheduling budget is not a CPU or child-process lifetime bound; the result
+deadline does not cancel an unfinished capture. One shared tmux
+activity read wakes idle rotations; a changed hint restores the active cadence.
+Missing/failed hints retain the configured full-capture cadence. A hint read
+that takes longer than one second becomes unknown without starting additional
+metadata probes while its underlying call is still pending. Periodic full
+capture reconciles output even when a hint fails to change (tmux timestamps have
+one-second resolution). Longer configured active intervals retain that interval
+instead of silently increasing capture frequency.
+
+This does not change provider readiness, delivery guards, seat activity or queue
+state. Capture activity is not proof an agent is healthy or finished. As before,
+transcripts are bounded trailing snapshots, not lossless terminal archives: an
+output burst larger than retained tmux scrollback or the configured line limit
+can exceed the saved trail. Interactive terminal streaming is unchanged.
+
+## Change capture settings without restarting
+
+```bash
+rig config set transcripts.poll_interval_seconds 3
+rig config set transcripts.lines 2000
+rig ps --resources
+rig config reset transcripts.poll_interval_seconds
+```
+
+Running rotations reread shared settings at most once per second and adopt the
+next valid policy without starting overlapping captures. Intervals accept whole
+seconds from 1 to 3600; trailing lines accept integers from 1 to 1000000. The
+existing environment variables take precedence over file settings. Malformed
+intermediate JSON retains the last usable policy, is shown in the resource view,
+and is retried; normal config
+writes reject invalid values. Changing `transcripts.enabled` or
+`transcripts.path` still requires a daemon restart. This feature does not impose
+CPU quotas or allocate build slots.

package/daemon/docs/reference/instance-layout.md

@@ -104,3 +104,14 @@ runtime reads for compatibility. Treat the two-home state as an explicit
 limitation: use the live spec-library commands to determine where a spec is
 served from, and do not infer convergence merely because the canonical
 directory exists.
+
+Config updates publish a complete replacement file atomically where directory
+permissions and the filesystem allow it. On POSIX systems, replacement preserves
+the existing owner, group, and read/write/execute permission bits. If creating or
+preparing the replacement, or renaming it, fails with `EACCES`, `EPERM`, or `EBUSY`,
+the stores write the writable target in place, preserving compatibility with
+unwritable directories and single-file bind mounts. This fallback is not atomic
+and retains the previous partial-write risk. Read-only config files are refused.
+Other errors, including `ENOSPC`, leave the original file intact on the atomic
+path. Atomic replacement does not carry extended ACLs or other inode metadata;
+a hard-linked second name continues to refer to the previous file.

package/daemon/docs/reference/rig-spec.md

@@ -247,7 +247,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `id` | string | yes | — | Pod identifier. Must not contain dots. Must be unique within the rig. Used as the first segment of session names and logical IDs. |
+| `id` | string | yes | — | Pod identifier. Must not contain dots or `@`. Must be unique within the rig. Used as the first segment of session names and logical IDs. |
 | `label` | string | yes | — | Human-readable pod name. Shown in UI explorer, graph groupings, and detail surfaces. |
 | `summary` | string | no | — | Pod description. |
 | `continuity_policy` | ContinuityPolicy | no | — | Pod-level continuity/restore policy. Controls compaction recovery, artifact management, and peer-driven restoration. |
@@ -258,6 +258,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 ### Pod ID Rules
 
 - Must not contain dots (`.`)
+- Must not contain `@`, which separates the pod/member portion from the rig name in session addresses
 - Must be unique across all pods in the rig
 - Becomes the first segment of the qualified logical ID: `{podId}.{memberId}`
 - Becomes the first segment of the canonical session name: `{podId}-{memberId}@{rigName}`
@@ -268,17 +269,35 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `id` | string | yes | — | Member identifier. Must not contain dots. Must be unique within the pod. |
+| `id` | string | yes | — | Member identifier. Must not contain dots or `@`. Must be unique within the pod. |
 | `agent_ref` | string | yes | — | Reference to an AgentSpec. Must start with `local:` (relative) or `path:` (absolute). Exception: `builtin:terminal` for infrastructure nodes. |
 | `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
 | `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
-| `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `terminal`. |
+| `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `pi`, `omp`, `terminal`, `stub`. `stub` is a deterministic test harness, not an agent: a Node runner in the seat's tmux pane goes through the normal launch, skill projection, startup-file and readiness path, follows `<cwd>/.openrig/stub/script.json` when present, and calls no model. See "What a stub can and cannot prove" in `docs/as-built/test-layers.md`. |
 | `cwd` | string | yes | — | Working directory for the agent. Resolved relative to the rig root (the directory containing the rig spec). Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. |
 | `label` | string | no | — | Human-readable member name. Shown in UI when present. |
 | `model` | string | no | — | Model override. Runtime-specific (e.g., `claude-opus-4-6` for Claude Code). |
 | `restore_policy` | string | no | `resume_if_possible` | Restore behavior. One of: `resume_if_possible`, `relaunch_fresh`, `checkpoint_only`. |
 | `startup` | StartupBlock | no | — | Member-level startup files and actions. Applied only to this member. |
 
+### Pi (`runtime: pi`)
+
+`runtime: pi` launches the Pi coding agent (`pi --mode rpc`) through OpenRig's RPC runner.
+
+- **State:** Each seat uses `$OPENRIG_HOME/state/pi/<session>/agent` as its Pi agent directory, with `sessions/` beside it, instead of your default `~/.pi/agent`. The runner sets `PI_CODING_AGENT_DIR` to that directory. `<session>` is the seat's session name, unchanged; for a pod member it is `{podId}-{memberId}@{rigName}`. `$OPENRIG_HOME` defaults to `~/.openrig`. OpenRig creates these directories at launch and does not copy anything from `~/.pi/agent`.
+- **Custom models:** Pi reads `models.json` from its agent directory, so a seat reads `$OPENRIG_HOME/state/pi/<session>/agent/models.json`, not `~/.pi/agent/models.json`. Custom provider and model definitions for a seat go in that file. A seat that uses only providers Pi already includes does not need one. OpenRig does not create or write `models.json`.
+- **Credentials:** The Pi process receives only `PATH`, `HOME`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY` or `KIMI_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>` or `kimi-coding/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
+
+### Oh My Pi (`runtime: omp`)
+
+`runtime: omp` launches Oh My Pi through OpenRig's RPC runner. It is separate from `runtime: pi`; OMP does not use Pi's `--name` or `--approve` flags.
+
+- **State:** Each seat uses `$OPENRIG_HOME/state/omp/<seat>/agent` and `sessions/` instead of your default `~/.omp` profile, and runs with that seat directory as `HOME`. OpenRig does not copy OMP credentials. The runner finds the real `omp` binary before switching `HOME`, so a version-manager shim such as mise on the daemon's `PATH` still works.
+- **Credentials:** Provision each seat separately, or put the provider's key variable in `recovery.provider_auth_env_allowlist` (for example `ANTHROPIC_API_KEY` or `MISTRAL_API_KEY`). The allowlist accepts the key variable of every provider in OpenRig's OMP provider map, from `anthropic` through `litellm`. A seat receives a key only when its `model` is written as `provider/id`, such as `anthropic/claude-sonnet-4-5`. Short names such as `opus` pass no key. OMP also reads the launch directory's `.env`, so use a trusted working directory.
+- **Approval posture:** The default floor is `--approval-mode always-ask`. Because the runner is headless, OMP approval requests are cancelled and the seat stays in needing-attention after the turn ends, until the next agent run starts. A `full_bypass` permission policy selects `--approval-mode yolo`.
+- **Model errors:** A rejected prompt, a provider or authentication error during a turn, or exhausted automatic retries is printed in the pane and keeps the seat in needing-attention until the next agent run starts.
+- **Restore:** OMP creates its session file after the first persisted turn. A new seat with no persisted turn has no resume token; restoring it requires `rig up --existing <rig> --fresh <seat>`. After that file exists, OpenRig restores that exact session file. If a full rig restore leaves an OMP seat in `attention_required` or `failed`, `rig seat clear-attention` cannot yet reconcile it to `operator_recovered`, even with `--reason`, because restore reconciliation only verifies Claude Code and Codex processes ([#41](https://github.com/mvschwarz/openrig/issues/41)). Relaunch that seat with `rig up --existing <rig> --fresh <seat>`, or restore it manually.
+
 ### Terminal Nodes
 
 Terminal nodes are infrastructure processes (servers, log tails, build watchers) that are not agent runtimes. They require an exact triple:
@@ -309,6 +328,9 @@ The canonical session name is derived from the pod ID, member ID, and rig name:
 
 Example: pod `dev`, member `impl`, rig `my-team` → session `dev-impl@my-team`
 
+Pod and member IDs cannot contain `@` because the first `@` separates their portion
+of the session address from the rig name. Rig names may still contain `@`.
+
 This is human-authored (you choose the pod/member IDs) and system-validated (the system enforces the format).
 
 ---
@@ -369,6 +391,7 @@ Startup blocks can appear at three levels: rig, pod, and member. They are merged
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `path` | string | yes | — | Relative path to the file. Must be a safe relative path. |
+| `orientation` | string | no | — | Set to `role` to identify a per-seat role file for `rig queue whoami --json` and refocus. Does not change delivery or replay startup. |
 | `delivery_hint` | string | no | `auto` | How the file is delivered. One of: `auto`, `guidance_merge`, `skill_install`, `send_text`. |
 | `required` | boolean | no | `true` | Whether startup fails if this file cannot be delivered. |
 | `applies_on` | string[] | no | `[fresh_start, restore]` | When this file is delivered. Subset of: `fresh_start`, `restore`. |
@@ -454,7 +477,8 @@ Each target must define exactly one of `service`, `url`, or `tcp`:
 
 ```yaml
 wait_for:
-  # HTTP probe — hits the URL, expects 2xx
+  # HTTP probe — any 2xx or 3xx response passes the HTTP wait target; redirects are not followed.
+  # This proves the server answered, not application readiness.
   - url: http://127.0.0.1:8200/v1/sys/health
 
   # TCP probe — connects to host:port
@@ -536,7 +560,10 @@ continuity_policy:
 
 ## Validation Rules Summary
 
-These rules are enforced by the validator. A spec that violates any of these will be rejected by `rig spec validate` and `rig up`.
+Schema validation checks the structural rules below. Pod and member IDs containing
+`@` are additionally rejected during preflight and member creation or launch; a
+spec can pass `rig spec validate` and then fail at preflight or import. Run
+`rig spec preflight` before creation or import.
 
 1. `version` and `name` are required non-empty strings.
 2. `pods` must be a non-empty array.

package/daemon/docs/reference/sdlc-conventions.md

@@ -100,9 +100,12 @@ Each slice directory carries:
     approval starts here.
   - **`## Proof contract`** — a checkbox list of promised deliverables (see
     §3). The UI's DELIVERED section pairs each item with its proof.
-- **`PROGRESS.md`** — the slice's acceptance checklist: the durable
-  mission/slice-level to-do checked at acceptance. In-process steps stay in
-  the working agent's own todo tool.
+- **`PROGRESS.md`** — the slice's current delivery state and retained outcome
+  log. Record material changes with links to proof; historical checkboxes are
+  testimony, not current acceptance authority. For a selected proof policy,
+  `rig proof show <slice>` derives current readiness from the proof contract
+  and attributed judgments. In-process steps stay in the working agent's
+  own todo tool.
 - **`PROOF.md`** — the retained proof summary, explicitly paired to the
   `SPEC.md` proof contract.
 - **`proof/`** — the proof-artifact directory. Curated canonical evidence

package/daemon/docs/reference/slack-app-setup.md

@@ -76,6 +76,12 @@ So after installing, compare the granted scopes Slack shows for the app with all
 The app subscribes to messages in public channels it is a member of (`message.channels`) and to
 mentions of the app (`app_mention`). It does not request direct-message or private-channel access.
 
+The manifest also turns on **Interactivity**, so the human can answer a decision's structured
+questions by clicking a button (`rig queue create --human-questions-file`). In Socket Mode the
+clicks arrive over the same socket, so no request URL is needed. An app created from an older
+manifest has Interactivity off: turn it on under **Interactivity & Shortcuts**, or the buttons
+will do nothing. A typed reply in the thread still answers the decision either way.
+
 ## What the connector does with the tokens
 
 The tokens stay in the env file you created. The connector reads them from that file and uses them

package/daemon/specs/agents/shared/agent.yaml

@@ -47,7 +47,7 @@ resources:
     - id: openrig-core
       source:
         kind: local
-        path: ~/.openrig/plugins/openrig-core
+        path: openrig-home:plugins/openrig-core
   runtime_resources:
     - id: claude-default-settings
       path: runtime/claude-settings.fragment.json

package/daemon/specs/agents/shared/skills/core/messaging-the-human/SKILL.md

@@ -79,6 +79,30 @@ never silently clipped. Shorten the brief or related detail as directed. Inspect
 the failed row, then deliberately cancel/replace the authored request if its
 content needs correction; a timeout alone is never a reason to replace it.
 
+A follow-up **update** about earlier work ("the change you approved is merged")
+can post into that item's thread with `--reply-to <earlier-qitem-id>`. It is
+accepted only with `--human-intent update`. Name the item whose thread the
+human saw, such as the parked row, and create the update on the same host as
+that item. Send the update from the seat that owns that thread: the seat that
+parked the row, or the author of the earlier item. A human reply in a thread
+reaches its owning seat, so an update from any other seat posts as a new
+message. It also posts as a new message, rather than being refused, if the
+earlier thread is missing or closed, or while the earlier item still waits on
+the human (a pending human decision, or a row parked on the human), since a
+reply in that thread would answer the decision. In every such case the
+`--verify` result says `threaded: false` with the reason.
+
+A **decision** with a few clear choices can carry `--human-questions-file <path>`:
+a JSON array of 1–4 questions, each
+`{"id", "question", "options": [{"id", "label", "recommended"?}]}` with 2–4
+options (labels up to 75 characters, at most one recommended). Slack shows each
+question as a row of buttons. Each click records that answer on the item, and
+the decision resolves once every question has one. You then receive one reply
+row listing the answers, and the item's `humanAnswers` holds the option ids. The
+human may instead type a reply in the thread; that resolves the decision as
+usual, so read the reply rather than assuming an option was picked. Keep the
+brief complete: the questions add buttons, they do not replace the explanation.
+
 If an existing agent-owned row must wait for a **decision**, block it on the **new live qitem ID**
 (`rig queue block <work-id> --on <human-qitem-id> ...`), not on the human address.
 Completion of the human qitem resumes its dependants. Blocking on the human as

package/daemon/specs/agents/shared/skills/core/openrig-skills/SKILL.md

@@ -120,6 +120,12 @@ and a useful report to the OpenRig team if you are still stuck. If `rig` won't r
 `daemon/docs/reference/help.md` inside the installed `@openrig/cli` package, or https://www.openrig.dev/help/agents
 (the same text).
 
+## Developing OpenRig itself
+
+If you're changing OpenRig's own source in a clone of the openrig repository, use that repository's
+`developing-openrig` skill (in the checkout's `.claude/skills/` or `.agents/skills/`). It maps the architecture, the
+areas where a small change has a large effect, and which tests to run before a pull request.
+
 ## Need more than what ships here?
 
 This index covers the **shipped** surface. Your project, rig or machine may add its own skills and routers. Check the

package/daemon/specs/agents/shared/skills/core/topology-mutation-and-seat-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: topology-mutation-and-seat-management
-description: Use when changing a rig while it is alive — `rig expand` / `rig shrink` / `rig launch` / `rig remove` / `rig discover` / `rig bind` / `rig adopt` / `rig attach`. Covers the 4 failure modes (newly created seat lacks queue/startup/role; edges and permissions not updated; adopt/bind succeeds at tmux but not OpenRig identity; shrink/remove leaves stale topology references) and the rule that mutation must work while the rig is active, not just in clean fixtures.
+description: Use when changing a rig while it is alive — `rig grow` / `rig expand` / `rig shrink` / `rig launch` / `rig remove` / `rig discover` / `rig bind` / `rig adopt` / `rig attach`. Covers the 4 failure modes (newly created seat lacks queue/startup/role; edges and permissions not updated; adopt/bind succeeds at tmux but not OpenRig identity; shrink/remove leaves stale topology references) and the rule that mutation must work while the rig is active, not just in clean fixtures.
 metadata:
   cli_surfaces_referenced:
     - adopt
@@ -8,6 +8,7 @@ metadata:
     - bind
     - discover
     - expand
+    - grow
     - launch
     - ps
     - release
@@ -43,13 +44,32 @@ static launch scripts.
 
 ## Use this when
 
-- Adding capacity to a running rig (`rig expand <rig> <pod-fragment-path>`)
+- Adding seats to a running rig (`rig grow <rig-id> <member...>` for the simple case, a fragment with `rig expand` or `rig add` otherwise; see below)
 - Removing capacity (`rig shrink` / `rig remove`)
 - Launching/relaunching a node in a running rig (`rig launch`)
 - Binding a discovered session into an existing logical node (`rig bind`)
 - Adopting a topology + binding live sessions (`rig adopt`)
 - Attaching a shell or agent into a rig node (`rig attach --self`)
 
+## Adding seats: `rig grow` first, a fragment when you need more
+
+`rig grow <rig-id> <member...>` adds one or more seats to a running rig without
+writing YAML. Each seat gets the default agent spec and its `default` profile.
+Check `rig grow --help` on your installed version; at the time of writing:
+
+- `--pod <pod>`: the target pod; inferred when the rig has one pod
+- `--new-pod <pod>`: create a new pod for the seats (not together with `--pod`)
+- `--runtime <runtime>`: one runtime for every named seat (default `claude-code`)
+- `--cwd <path>`: one working directory for every named seat (default: the current directory)
+- `--json`: output for agents
+
+Write a fragment instead when a seat needs something `rig grow` does not set: an
+explicit model, a permission policy, a different agent spec or role profile, a
+per-seat runtime or working directory, or startup files. Use
+`rig expand <rig-id> <pod-fragment-path>` to add a pod, or
+`rig add <rig-id> <pod-namespace> <member-fragment-path>` to add one member to an
+existing pod.
+
 ## Don't use this when
 
 - The rig is being created fresh from scratch — use `rig up` (lifecycle, not mutation)
@@ -89,6 +109,7 @@ adding or removing a seat from replacing its occupant; use
 
 Per `cli-reference.md` v0.2.0:
 
+- `rig grow <rig-id> <member...> [--pod <pod> | --new-pod <pod>] [--runtime <runtime>] [--cwd <path>]` (added after v0.2.0; check `rig grow --help`)
 - `rig expand <rig-id> <pod-fragment-path>` (with optional `session_source`)
 - `rig shrink <rigId> <podRef>`
 - `rig launch <rigId> <nodeRef>`
@@ -114,7 +135,7 @@ unfinished proof obligation is implied by loading this skill.
 
 ## See also
 
-- `openrig-user` skill — CLI surface for `rig expand / shrink / launch / remove / bind / adopt / attach`
+- `openrig-user` skill — CLI surface for `rig grow / expand / shrink / launch / remove / bind / adopt / attach`
 - `seat-scaling-and-specialization` skill — when to add specialized capacity vs generic
 - `seat-continuity-and-handover` skill — replacing an occupant on a stable seat (different shape than topology mutation)
 - `cross-host-rig-commands` skill — cross-host topology mutation (deferred)

package/daemon/specs/rigs/launch/kernel/agents/advisor/lead/agent.yaml

@@ -12,21 +12,15 @@ profiles:
   default:
     uses:
       skills: [openrig-architect, requirements-writer]
-      guidance: [role]
+      guidance: []
       subagents: []
       plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
-resources:
-  guidance:
-    - id: role
-      path: guidance/role.md
-      target: CLAUDE.md
-      merge: managed_block
-
 startup:
   files:
     - path: guidance/role.md
+      orientation: role
       delivery_hint: send_text
       required: true
     - path: startup/context.md