@openrig/cli 0.6.11 → 0.6.13

package/daemon/docs/reference/project-workspace.md

@@ -189,7 +189,11 @@ ambiguity.
 ## Queue Mapping
 
 A `slice:<id>` tag is the authoritative way to attach a queue item to a slice;
-with a project selected, typed rows also need the `project:<id>` tag. As a
+with a project selected, typed rows also need the `project:<id>` tag. The tag
+value is either the slice's frontmatter `id` (a dot-ID such as `CUS.9775.1.1`)
+or its directory name (`01-custody-funds`); both resolve to the same slice on
+the Queue tab, the ownership lanes and the agents band. A row that carries both
+forms counts once. As a
 fallback, for slices with no typed rows, items attach when their body or tags
 mention one of:
 
@@ -210,6 +214,71 @@ Slice: capture-product-ideas
 This makes Story, Queue, Tests, and Topology tabs line up with the filesystem
 slice without adding a separate project database schema.
 
+### Workflow packets
+
+Packets that `rig workflow` projects carry the scope of their instance. Pass the
+scope when the instance is created and every packet it creates (the entry, each
+hand-off and gate, exception items, and resume packets) is tagged, so they show
+on the slice's Queue tab:
+
+```bash
+rig workflow instantiate ./spec.workflow.md \
+  --root-objective "Build the capture flow" --created-by orch@my-rig \
+  --project my-project --mission idea-ledger --slice capture-product-ideas \
+  --tags ticket-7
+```
+
+- `--project` should name a project in the workspace catalog. `--mission` and
+  `--slice` take the same ids as the slice routes. `rig workflow run` takes the
+  same flags. The CLI refuses what it can check itself (an id of the wrong shape,
+  a reserved tag, a tag that contradicts a flag) as a usage error, before
+  anything is sent. Only the daemon knows the catalog, so a mistyped `--project`
+  is **not refused**: the daemon creates the instance unscoped, its packets carry
+  no scope tags, and the CLI prints a warning on stderr (also with `--json`)
+  that names the instance and says the scope was not applied. The CLI does not
+  retry; instantiating again creates a second instance.
+- Packets carry `project:<id>`, `mission:<id>` and `slice:<id>` for the parts
+  you set, then your `--tags`, after the tags the workflow system writes. Tags
+  compose as in `rig queue create`: duplicates collapse, so `--slice S --tags
+  slice:S` is one tag.
+- `--tags` is refused locally when it carries what the workflow runtime reads
+  back to route packets: `workflow`, `handoff`, `gate`, `entry`, `resume`,
+  `re-route`, `workflow-exception`, and the `workflow:`, `instance:`, `step:`,
+  `exception:`, `occurrence:` and `recovery-for:` prefixes, a `project:`,
+  `mission:` or `slice:` tag that contradicts its flag, or a second value of
+  the same key.
+- `rig workflow instantiate-lifecycle` needs no flags: it takes the project and
+  mission from the lifecycle identity it compiles. A compiled step's packets
+  carry the `slice:<directory>` of the slice that step was compiled from, even
+  when another slice's directory has the same name as its `metadata.id`. A step
+  an authored graph names carries `slice:<directory>` when it names an active
+  slice: by its exact directory name, else by a `metadata.id` that exactly one
+  active slice claims (an id two slices claim maps to nothing, with a compile
+  advisory). A step that names no slice, such as an authored closing step,
+  carries only `project:` and `mission:`, so it appears on no slice's Queue tab.
+  A project id or mission name the compiler reads from the manifests that cannot
+  be a tag (a space, a `:`, a leading `.`, `_` or `-`, or too long) is left off
+  the packets with a compile advisory; the lifecycle still instantiates. Slice
+  metadata the lifecycle does not run is read only leniently, for step names, and
+  never fails compile or instantiate.
+- Over HTTP, `POST /api/workflow/instantiate` reads the scope from a `scope`
+  object (`{ project, mission, slice, tags }`). A scope that is valid and names
+  a catalogued project is applied as above. A scope the route cannot apply (a
+  project the catalog does not declare, a conflicting, reserved or malformed tag
+  or id, or a `scope` that is not an object) is ignored: the route does what it
+  did before the field existed and creates one unscoped instance, records
+  nothing the scope named, and never lets a rejected tag reach a packet. The
+  response `advisories` then carry a `Scope not applied (...)` note that names
+  the instance (`scopeIgnored` repeats it); `rig workflow run` prints
+  `advisories`. Bare `project`, `mission`, `slice` or `tags` fields in the body
+  are ignored the same way, with a note. A failure unrelated to the scope still
+  fails the request.
+- A Projects view scoped to a project lists a slice's packets only when they
+  carry `project:<id>` as well as `slice:<id>`, so pass `--project` with
+  `--slice`.
+- The scope is stored on the instance when it is created and does not change.
+  Instances created without it behave as before.
+
 ## Compatibility
 
 The default discovery root is `workspace.slices_root=<workspace.root>/missions`.

package/daemon/docs/reference/publishing-a-rig-bundle.md

@@ -21,7 +21,12 @@ Two rules matter most for strangers:
 - **Keep everything inside the folder.** Every `agent_ref` should be `local:` and point inside it. A path that exists on
   your machine won't exist on anyone else's.
 - **Never put credentials in it.** No tokens, keys or `.env` files. `rig bundle create` refuses well-known sensitive
-  file names (such as `.env`, `.pem` and `.key`) anyway.
+  file names (such as `.env`, `.pem` and `.key`) anyway. It also refuses contained `.claude/.credentials.json`,
+  `.codex/auth.json` and `.pi/agent/auth.json`, including nested copies in agents or a carried project. Remove them
+  and rebuild. Only if recipients should have these logins (for example, your own internal test bundle) and their
+  owner agrees, `rig bundle create --include-login-files` records the exact included login-file paths in the
+  manifest and consumers show a notice; anyone with the bundle could read those files.
+  Unrecorded login files and other sensitive paths still fail. See [harness login files](rig-bundle.md#harness-login-files).
 
 Two optional files sit beside `rig.yaml`:
 - **`bundle.yaml`** declares what people need before installing: setup steps (`preconditions`, shown before install
@@ -111,8 +116,11 @@ an issue there with the same three things. A maintainer then writes the full ent
 defined in the [bundle formats reference](bundle-formats.md), with the parts only a review can produce, such as the
 pinned commit and each configuration's package digest.
 
-Rig names are unique on the site. If `registry/<your-team>.yaml` already exists, openrig-registry's registry check says the name is taken;
-choose a distinct one, for example `<taken-name>-<your-name>`.
+Rig names are unique on the site. If `registry/<your-team>.yaml` already exists, openrig-registry's registry check
+still replies that your submission was received, and says the name is taken; choose a distinct one, for example
+`<taken-name>-<your-name>`. A team whose `rig.yaml` name matches a listed team's, such as an unchanged copy of one,
+passes the checks with a notice for the maintainer about the shared name. Whether it's listed is the maintainer's
+review decision, not the checks'.
 
 What happens next:
 - a maintainer pins your link to an exact commit, runs the same check, and reads everything your bundle gives to an

package/daemon/docs/reference/refocus-channel.md

@@ -16,6 +16,30 @@ it is the mechanism that makes shipped chain files (see
 | Stop | ✓ | — | catch a long Claude turn crossing the growth threshold |
 | PostCompact | ✓ | ✓ | retain exact compaction due-state; deliver on the next actionable prompt |
 
+**How the hooks reach a seat.** A Claude seat whose resolved plugin selection includes the shipped `openrig-core` plugin
+(for example `plugins: [shared:openrig-core]`, or the same plugin under another name) starts with `CLAUDE_CODE_PLUGIN_DIRS`
+set to the vendored plugin (`$OPENRIG_HOME/plugins/openrig-core`), so Claude loads `hooks/claude.json` with no setup step, on a
+fresh launch, a restore, a handover successor and a launch with a permission mode. A seat that didn't select the plugin is
+launched as before and doesn't load these hooks. The folder a spec's plugin selection projects into the seat's workspace is
+not what Claude loads. A list the seat declares itself in `CLAUDE_CODE_PLUGIN_DIRS` keeps working, with the vendored plugin
+added after it.
+Claude Code reads this variable from v2.1.280. OpenRig doesn't check the Claude version at launch: an older Claude ignores the
+variable, starts normally, and doesn't load these hooks. The behaviour was checked on Claude Code 2.1.296 and not on
+earlier versions.
+A Claude started from inside a seat (its shell or Bash tool) inherits the seat's environment and so loads the plugin as well.
+A seat that loads the plugin is also given `OPENRIG_SEAT_PROJECT_DIR`, its launch project, and the plugin's seat effects (the
+activity and session-identity posts, the compaction hooks, refocus, and the first-launch marker) run only when that Claude's
+`CLAUDE_PROJECT_DIR` names the same folder (compared by real path, so a trailing slash or symlink doesn't matter). A nested
+Claude in another project, or in a subfolder of the seat's project, therefore changes nothing for the seat, and a `cd` inside
+the seat's own session keeps working because `CLAUDE_PROJECT_DIR` is fixed when Claude starts. A nested Claude in the seat's
+own project folder is the same project and still acts as the seat, as before this change. Without either variable (a seat
+launched before this change, a manual run) the hooks do what they always did. The plugin's activity relay stays quiet next to
+the seat's own `settings.local.json` copy only when that entry is exactly OpenRig's and the script it names is the same
+script; an entry from an older install doesn't match, so both report until the seat's next launch refreshes it.
+Codex has no way to load a plugin from a directory; its hooks come from the daemon's
+managed block in `config.toml`, which today carries the activity relay only, so the Codex column above describes
+`hooks/codex.json`'s registration and not a hook a Codex seat currently runs.
+
 Claude's additional firing signal is **transcript growth** — not turns (one turn
 can burn 200k tokens across fifty tool calls) and not wall-clock (the failure is
 sustained work, not elapsed time). Its default threshold is ~2.6MB of JSONL
@@ -33,11 +57,23 @@ that request asks the seat to read the refocusing skill and consume the delivere
 traces rather than rerun them, and the read-depth audit accounts for them. Otherwise the hook
 is a no-op (it writes a stderr advisory when the transcript shrinks or the
 session has no identity), and it degrades to silence on unrelated hook errors.
-Both runtimes stop the hook after 5 seconds, and the content REF lookup gets 2;
-a slow REF shows as `REFOCUS CONTENT REF FAILED`. A
-configured REF resolution failure instead degrades
-loudly in the delivered payload while still completing the hook — a refocus
-must never break a seat's turn.
+**Time budget.** By default each lookup (the trace, the content REF, `rig queue whoami`, `rig config`) gets 2 seconds,
+as before, and a slow one ends as a reported gap (`TRACE GAP`, `REFOCUS CONTENT REF FAILED`, or a role marked
+unknown). Set `OPENRIG_REFOCUS_BUDGET_MS` in a seat's environment to give a slow trace more time, up to 52000 (52 s).
+Each lookup's cap then grows in proportion (at 45000 the trace may take 20 seconds; at 52000, about 23), and every lookup
+is also cut to what is left of that budget, so the attempt delivers what it has and counts as failed. After a failed
+attempt, the issue report gets its own 1.5 seconds once the lookups are done. Both registrations allow `refocus.cjs` 60
+seconds, where they used to stop it at 5; the other OpenRig hooks keep theirs. So a default fire whose lookups together
+pass 5 seconds now completes instead of being stopped with nothing delivered, and a hook that hangs outside its lookups
+can hold a prompt for up to those 60 seconds.
+
+A configured REF resolution failure degrades loudly in the delivered payload while still completing the hook — a
+refocus must never break a seat's turn.
+
+**Overlapping events (unresolved).** Two hook runs for the same seat and occupant are not serialized. If they overlap,
+a `PostCompact` recorded while a prompt is delivering can be lost, and one refocus can be delivered twice. This is
+reproduced between hook processes; whether a harness overlaps these events for one session is not established, so it is
+an open gap, not one shown to be safe.
 
 Failed trace or configured-content resolution keeps refocus due. After three
 consecutive failed attempts for the same seat and occupant, the hook emits one
@@ -89,10 +125,14 @@ reports broken links as gaps rather than following pointers.
 This automatic hook path is additive to one-shot manual injection through
 `rig send --context`; neither mode substitutes for the other.
 
-## The work packet (switched off by default)
+## The work packet (off by default on every runtime, for now)
 
 Set `OPENRIG_REFOCUS_WORK_PACKET=1` in a seat's harness environment so its
 refocus carries the work it is actually doing as text rather than as pointers.
+`=0` (or `off`, `false`, `no`) turns it off. Unset, each runtime's default
+applies. A runtime's default becomes on only after a native run shows the
+packet reaching the agent and leading to the right next action. No runtime has
+been shown that yet, so today both Claude Code and Codex default to off.
 With the switch on:
 
 - The hook asks `rig queue whoami --work-candidates` for labelled evidence.
@@ -118,6 +158,12 @@ With the switch on:
   `OPENRIG_REFOCUS_NOTES_MAX_AGE_DAYS` (default 14) is named with its age, the
   age's source (`updated:` frontmatter, else mtime) and the threshold: a cue
   for judgment, not a staleness verdict.
+- Each field is bounded on its own, with no total cap. A held or next row's
+  summary and continuation are one line each (about 160 characters), with
+  `rig queue show <id>` named when one was shortened. At most 20 held and 10
+  next rows are shown, with how many there are and the `rig queue list` command
+  for the rest. A matched section's body is cut at about 1,500 characters,
+  pointing to `--depth full`.
 
 `trace-to-root.py --packet --work-candidates <path|->` renders the same packet
 by hand.

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

@@ -191,6 +191,7 @@ integrity:
 | `rig_spec` | string | yes | Relative path to the rig spec within the archive. Safe relative path. |
 | `agents` | AgentEntry[] | yes | Array of vendored agent entries. |
 | `culture_file` | string | no | Relative path to the culture file if present. |
+| `included_login_files` | string[] | no | Exact archive-relative harness login files deliberately included by the producer. Only these paths are exempt from the login-file refusal; this unsigned declaration is not authentication or receiver approval. |
 | `integrity` | Integrity | no | Per-file SHA-256 checksums for content verification. Validation doesn't require it, but install refuses an archive without it and inspect reports integrity FAIL. |
 | `provenance` | object | no | Stated, not verified: `created_at`, `daemon_version`, `cli_version`, `source_host`, `author_session`, `source_rig_id`, `source_rig_name`, `notes`, and `source` for a GitHub link build. |
 | `assembler` | object | no | `openrigVersion` of the OpenRig that built the archive. |
@@ -221,6 +222,28 @@ integrity:
 | `original_ref` | string | yes | The original import ref before rewriting. |
 | `hash` | string | yes | SHA-256 hash of the imported agent.yaml. |
 
+### Harness login files
+
+By default, create refuses `.claude/.credentials.json`, `.codex/auth.json` and `.pi/agent/auth.json`
+at the root or nested anywhere in selected bundle content, including agents and an explicitly carried project.
+The author check reports them too. Messages name paths, never contents, and explain both remedies:
+remove the file from the agent folder or carried project and build again; or, only if recipients should have this
+login (for example, your own internal test bundle) and its owner agrees, recreate with
+`rig bundle create <spec> -o <archive.rigbundle> --include-login-files`.
+Anyone with that archive could read the included login files.
+
+The flag applies to this create only. The generated `included_login_files` manifest list names only the actual,
+exact archive-relative login files included. Inspect, unpack, install and bootstrap honour those paths without
+another flag and show a credential-bearing notice. An additional unrecorded login file still fails, as do malformed
+records, directory or wildcard exemptions, and unrelated sensitive files. There is no machine setting or `--force`
+bypass. The unsigned record states the producer's choice; it does not authenticate the producer, establish trust,
+or constitute a fresh recipient approval. Review the source and files before using a bundle.
+
+Compatibility change: previously accepted bundles containing these files now fail default creation and downstream
+verification/install unless deliberately rebuilt with the record. Inspection remains diagnostic: it reports failed
+integrity. Ordinary `auth.json` elsewhere and non-login harness files are unchanged. Filename checks do not scan
+arbitrary contents for secrets.
+
 ### Integrity Section
 
 | Field | Type | Required | Description |
@@ -272,7 +295,7 @@ where the daemon runs.
 ### Create a bundle
 
 ```bash
-rig bundle create <spec-path-or-github-link> -o <output.rigbundle> [--rig-root <dir>] [--preset <name>] [--seat <pod.member=runtime>]... [--context-pack <dir>]... [--project-dir <dir>] [--name <name>] [--bundle-version <ver>] [--min-cli-version <ver>] [--min-daemon-version <ver>] [--notes <text>] [--include-packages <refs...>] [--allow-drift] [--json]
+rig bundle create <spec-path-or-github-link> -o <output.rigbundle> [--rig-root <dir>] [--preset <name>] [--seat <pod.member=runtime>]... [--context-pack <dir>]... [--project-dir <dir>] [--name <name>] [--bundle-version <ver>] [--min-cli-version <ver>] [--min-daemon-version <ver>] [--notes <text>] [--include-packages <refs...>] [--allow-drift] [--include-login-files] [--json]
 ```
 
 | Flag | Required | Default | Description |
@@ -289,6 +312,7 @@ rig bundle create <spec-path-or-github-link> -o <output.rigbundle> [--rig-root <
 | `--min-cli-version`, `--min-daemon-version` | no | — | The oldest OpenRig CLI or daemon that may install the bundle, checked on install. For a link they override the author's `bundle.yaml` minimums. |
 | `--notes <text>` | no | — | Notes stored in the manifest's provenance. |
 | `--include-packages <refs...>` | no | all from the spec | Legacy (schema 1) specs only: the package refs to include. |
+| `--include-login-files` | no | off | Only if recipients should have these logins and their owner agrees (for example, an internal test bundle), include them and record their exact archive-relative paths. Create and consumers show a credential-bearing notice. Does not exempt other sensitive files. |
 | `--allow-drift` | no | off | Build a spec that differs from the running rig of the same name. Without it, create refuses; with it, the difference is written into the manifest's provenance notes. |
 | `--json` | no | off | Machine-readable output. |
 
@@ -537,7 +561,7 @@ When an agent spec has `imports`, each import is resolved, vendored into the bun
 7. Each agent must have `name`, `path` (safe relative), and `hash`
 8. Optional blocks, when present, must be well formed: `provenance`, `compatibility`, `skills`, `plugins`,
    `workflow_specs`, `context_packs`, `agent_images`, and `project` (an `id` made of letters, digits, `.`, `_` and `-`,
-   and a safe relative `path`)
+   and a safe relative `path`), plus `included_login_files` (unique safe relative paths)
 
 The manifest validator doesn't check `integrity`; unpack does (below).
 

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

@@ -179,6 +179,7 @@ edges:
 | `culture_file` | string | no | — | Relative path to a rig-wide culture/constitution file. Must be a safe relative path (no `..`, no absolute). |
 | `non_interruptive` | boolean | no | — | Pod-aware rig launch-warning default. With full-bypass Claude/Codex seats, true accepts or hides supported harness warnings using launch flags. Explicit CLI choices override this field; this field overrides the machine default. It does not grant permissions, change native settings files, or bypass login. |
 | `permission_policy` | string | no | — | Permission policy attached to the rig. Either a built-in (`builtin:locked`, `builtin:standard`, `builtin:open`, `builtin:yolo`, `builtin:auto`) or a safe relative path to a custom policy file (resolved from this spec's directory; no `..`, no absolute, no empty segments, each segment `[A-Za-z0-9][A-Za-z0-9._-]*`), or `none`, a recorded choice of the floor. Absent uses the default floor with the scoped team launch allowances described below. A bare built-in name such as `yolo` is refused ("use 'builtin:yolo'"), and so is an explicit `null`. A custom file that is missing, unreadable or invalid isn't a validation error: it resolves to the floor, and preflight warns. A member may set its own `permission_policy` (not on a terminal member), which takes precedence over the rig-level one; there is no pod level. See "Attaching a permission policy" below. |
+| `env` | map | no | — | Launch environment for every seat in the rig: `NAME: value` pairs. A member's own `env` overrides it name by name. Names match `^[A-Z_][A-Z0-9_]*$`, names starting `OPENRIG_` are reserved, and values must be non-empty strings (quote numbers and booleans). Values are not secret. See "Launch environment" below. |
 | `managed_blocks` | map | no | `CLAUDE.md` | File that receives OpenRig's managed instruction blocks for Claude Code members. Only the `claude-code` key is accepted, with `CLAUDE.md` or `CLAUDE.local.md`. Codex, Pi and OMP members use `AGENTS.md`. See "Choosing the Claude instruction file" below. |
 | `workspace` | object | no | — | The rig's workspace: `workspace_root` (required), `repos[]` of `{name, path, kind}` with `kind` one of `user`, `project`, `knowledge`, `lab` or `delivery` and unique names, an optional `default_repo` naming one of them, and an optional `knowledge_root`. Relative repo paths resolve against `workspace_root`. |
 | `docs` | Doc[] | no | — | Documentation files that should travel with the rig. Included in rig bundles. Each entry has a `path` field (safe relative path). The engine does not consume these — they are for humans and agents setting up the environment before launch. |
@@ -334,6 +335,44 @@ context for `rig seat continue`; `rig up --non-interruptive` or `rig bundle inst
 except inside a recognized sandbox. See Claude Code's
 [Choose a permission mode](https://code.claude.com/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode).
 
+### Launch environment
+
+`env:` sets environment variables for the seats of a rig, so a team can share a setting such as a feature flag, a region or a log level without every member hand-editing a shell profile. Declare it on the rig, on a member, or both:
+
+```yaml
+env:
+  LOG_LEVEL: info
+  REGION: eu
+pods:
+  - id: dev
+    members:
+      - id: impl
+        runtime: claude-code
+        env:
+          LOG_LEVEL: debug   # overrides the rig's value for this seat only
+```
+
+- A seat gets the rig's `env` with its own `env` laid over it, name by name.
+- The same environment is applied on first launch, on `rig up <rig-name>` restore, and to the successor of a seat handover.
+- `rig up <spec> --env KEY=VALUE` (repeatable) adds or overrides a value for one launch. A one-off value belongs to the terminal that launch creates: it stays in that terminal's environment for as long as the terminal lives, and OpenRig removes it from the tmux session's environment as soon as the terminal has started, so a terminal started later in that session does not get it. A restore, a handover successor or any later launch starts from the spec's `env:` alone, so the value is not saved and does not carry forward. To keep a value, put it in `env:`. One exception to "does not carry forward", for a managed Claude seat (see below): a one-off name that the seat's spec does not declare stays on the session's list of names, `OPENRIG_SEAT_ENV_KEYS` (names only, no values), because the first launch and an in-place restart of the same terminal read that list. So if a later pane in that session gets a value for that name from the tmux server's own environment, its managed Claude launch can forward that value, where a launch without `--env` would leave it out. The first launch's one-off value itself is not passed on to that pane. This comes from reading the code and has not been measured. `--env` does not apply to `rig up <rig-name>` (a restore) or to a topology (several rigs from their own specs); the CLI refuses both. For a topology, put `env:` in each rig's spec.
+- Names starting `OPENRIG_` are reserved for OpenRig and refused. Empty values are refused, because the launch omits empty variables.
+- `rig export` writes the rig and member `env:` back out.
+
+**Where the declared names reach, by runtime.** Declared values are handed to the seat's terminal as tmux environment, so most seats take them as given:
+
+- Plain Claude Code (no permission mode selected), Codex and terminal seats take a spec `HOME`, `PATH` or `CLAUDE_CONFIG_DIR` as given.
+- The cleared environment (`env -i`) belongs only to a managed Claude launch, which is the one used when a permission mode is selected for the seat (for example `permission_policy: builtin:auto`). It forwards the declared names through the cleared environment, except `PATH`, `HOME` and `CLAUDE_CONFIG_DIR`, which OpenRig sets for that launch itself, and `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN`, for which it sets its own renderer setting. A spec value for any of those four is not forwarded. A seat that selected the shipped `openrig-core` plugin also has `CLAUDE_CODE_PLUGIN_DIRS` (the vendored plugin, added after a list the seat declares itself) among its declared names, so it is forwarded like the others and the plugin's hooks load in a seat with a permission mode as in one without; a seat that didn't select the plugin has no such name added. Beyond the declared names, the launch also forwards, by name and only when the seat's terminal has them set, the terminal and locale variables (`TERM`, `COLORTERM`, `TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `LANG` and the `LC_*` names) and the person's editor and display session: `EDITOR`, `VISUAL`, `DISPLAY`, `XAUTHORITY` and `WAYLAND_DISPLAY`. They let Claude's external-editor action open the person's editor and let image paste reach the clipboard, without a value in a spec. `WAYLAND_DISPLAY` is passed as an absolute path: an absolute value is kept, and a relative one is joined to the terminal's `XDG_RUNTIME_DIR`; if the terminal has no `XDG_RUNTIME_DIR` for it, the name is left out. `XDG_RUNTIME_DIR` itself is not forwarded, because D-Bus clients look for the session bus at `$XDG_RUNTIME_DIR/bus` and would reach the keyring and `systemctl --user`. `DBUS_SESSION_BUS_ADDRESS`, `XDG_SESSION_TYPE`, `XDG_CURRENT_DESKTOP` and `SSH_AUTH_SOCK` are not forwarded either. A running seat picks the names up at its next managed Claude launch, not before: `rig seat launch <seat> --fresh --stop --reason "<why>"` for that seat alone (a new conversation), or a restore of the whole rig (`rig down <rig>`, then `rig up <rig> --existing`, which resumes each conversation but restarts every seat in the rig), or a handover. A seat that is up keeps the environment it started with.
+- Codex seats run OpenRig's own Codex executable whatever a spec `PATH` says, and use the daemon's `CODEX_HOME` when the daemon has one.
+- On Pi and OMP seats the values reach the terminal. The agent process gets only what the runner passes on, so a spec or one-off value reaches it only for the names the runner always passes: `PATH`, `HOME`, `USER`, `LOGNAME`, `TERM`, `LANG`, `LC_ALL`, `SHELL` and `TMPDIR`. Pi's agent process receives the runner's `HOME`, so a spec or one-off `HOME` value that reaches the runner is passed to Pi; OMP's agent process gets its seat state directory (`$OPENRIG_HOME/state/omp/<seat>`, see Oh My Pi below) as `HOME`, so a `HOME` value does not reach it. The selected provider's variables are passed separately, as described under each runtime.
+
+**Do not put secrets in `env:` or `--env`.** The values are not secret, and nothing here encrypts or hides them (see #306):
+
+- Spec values are stored in OpenRig's database and in rig snapshots, and `rig export` and bundles copy them, so a secret put there by mistake travels with the rig.
+- While a seat launches, the values are passed to tmux as command arguments, so other users and processes on the same machine can see them for that time. They then sit in the seat's process environment. Only the managed Claude launch command is value-free: it forwards names, and the terminal supplies the values.
+- A one-off `--env` value is not stored in the database or in snapshots, but it reaches tmux the same way, so it is visible in the same ways while that launch runs.
+
+Use `env:` for settings only. Credentials belong in the provider's own login or a secret store the seat reads at run time.
+
 ### Choosing the Claude instruction file
 
 OpenRig writes its instructions for Claude Code members into managed blocks in
@@ -397,14 +436,15 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 | `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
 | `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
 | `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `pi`, `omp`, `terminal`, `stub`. `stub` is a deterministic test harness, not an agent: a Node runner in the seat's tmux pane goes through the normal launch, skill projection, startup-file and readiness path, follows `<cwd>/.openrig/stub/script.json` when present, and calls no model. See "What a stub can and cannot prove" in `docs/as-built/test-layers.md`. |
-| `cwd` | string | yes | — | Working directory for the agent. A relative path resolves against the rig root (the directory containing the rig spec). If that path exists as written, it is used. Otherwise a leading `~` or `~/` expands to the home directory (`~user` does not) and `$VAR` / `${VAR}` expand from the daemon host's environment; a relative result still resolves against the rig root. A reference to an unset variable stays as written, so the cwd is that literal path and works only if it exists. Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. A cwd inside the OpenRig installation fails preflight unless `--cwd` is given. |
+| `cwd` | string | yes | — | Working directory for the agent. A relative path resolves against the rig root (the directory containing the rig spec). If that path exists as written, it is used. Otherwise a leading `~` or `~/` expands to the home directory (`~user` does not) and `$VAR` / `${VAR}` expand from the daemon host's environment; a relative result still resolves against the rig root. A reference to an unset variable stays as written, so the cwd is that literal path and works only if it exists. Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. A cwd inside the OpenRig installation fails preflight unless `--cwd` is given. Editing this declaration does not update an existing seat; use [`rig seat set-cwd`](agent-startup-guide.md#change-an-existing-seats-working-directory) to save its future launch directory. |
 | `label` | string | no | — | Human-readable member name. Shown in UI when present. |
 | `model` | string | no | — | Model override. Runtime-specific (e.g., `claude-opus-4-6` for Claude Code). |
-| `effort` | string | no | — | Reasoning effort override, trimmed. A non-string value is ignored with an advisory. |
+| `effort` | string | no | — | Reasoning effort override, trimmed. Claude gets `--effort`, Codex `-c model_reasoning_effort=…`, Pi `--thinking` (see "Pi" below). A non-string value is ignored with an advisory. |
 | `permission_policy` | string | no | — | Member-level permission policy; overrides the rig's. Not valid on terminal members. |
+| `env` | map | no | — | Launch environment for this seat, laid over the rig's `env`. Same rules as the rig-level field. Valid on terminal members too. See "Launch environment" below. |
 | `role` | string | no | — | The seat's role, letters, digits, `_`, `.` and `-`. Not valid on terminal members. |
 | `restore_policy` | string | no | the AgentSpec's | Restore behavior. One of: `resume_if_possible`, `relaunch_fresh`, `checkpoint_only`. The default comes from the AgentSpec's `defaults.lifecycle` (else `resume_if_possible`) as narrowed by its profile; a member value may only narrow it further, in that order. |
-| `compaction_strategy` | string | no | — | `default-compaction`, `managed-compaction`, `handover` or `apprentice-handover`; `harness_native` and `pod_continuity` are accepted as deprecated aliases, and `custom_prompt` is refused. |
+| `compaction_strategy` | string | no | — | `default-compaction`, `managed-compaction`, `handover` or `apprentice-handover`; `harness_native` and `pod_continuity` are accepted as deprecated aliases, and `custom_prompt` is refused. `managed-compaction` and `apprentice-handover` create their jobs only for `claude-code` seats; see [Codex compaction and sizing](agent-startup-guide.md#codex-compaction-and-sizing). |
 | `mechanic` | string | no | — | A canonical `seat@rig` session address, for `apprentice-handover`. |
 | `session_source` | object | no | — | Start the seat from an existing session: `fork` with `native_id`, `rebuild` with `artifact_set`, or `agent_image` with `image_name`. A Claude Code `fork` needs Claude Code 2.0.73 or later. Not valid on terminal members. |
 | `starter_ref` | object | no | — | `{ name }` of an agent starter (`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`) whose files lead the seat's startup. Not valid on terminal members or with a fork. |
@@ -415,6 +455,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 `runtime: pi` launches the Pi coding agent (`pi --mode rpc`) through OpenRig's RPC runner.
 
 - **State:** Each seat uses `$OPENRIG_HOME/state/pi/<session>/agent` as its Pi agent directory, with `sessions/` beside it, instead of your default `~/.pi/agent`. The runner sets `PI_CODING_AGENT_DIR` to that directory. `<session>` is the seat's session name, unchanged; for a pod member it is `{podId}-{memberId}@{rigName}`. `$OPENRIG_HOME` defaults to `~/.openrig`. OpenRig creates these directories at launch and does not copy anything from `~/.pi/agent`.
+- **Thinking level:** A Pi seat's effort (the choice saved with `rig seat set-effort`, else the spec's `effort`) is sent to Pi as `--thinking <level>` on every managed launch and resume: fresh launch, successor and restore. Pi accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`; OpenRig passes the value as written and does not translate it, so Codex's `none` is not mapped to `off`. Only a value of the shape `set-effort` accepts (a letter, then up to 31 letters, digits, `-` or `_`) is sent; any other spec value, such as one with a space or one that starts with `--`, is left out, and `rig seat effort` says so. An unfamiliar level gets an advisory (a warning from `set-effort`), never a refusal, and Pi itself ignores an unknown level with a warning and keeps the level it would use without the flag: a model suffix, the resumed session's level, or its default. With no effort resolved, no flag is sent. The effort wins over a model suffix, and the model string is never changed. `rig seat effort` reports the level sent at launch and, on Pi 0.99.0 or later, the `thinkingLevel` Pi records on this launch's latest successful assistant turn (error and aborted turns are skipped); that is the session's level after Pi's own cap, not proof the provider applied it, and it is shown apart from the level sent when they differ. On older Pi it is NOT VERIFIED. Without an effort, you can still set the level as a model suffix, for example `model: openrouter/x-ai/grok-4:high`. Pi first looks for a model whose id is the whole pin, and uses it when there is one, suffix included. Only when there is none does Pi read the suffix as the level and record the model without it. Any other suffix, such as OpenRouter's `:free`, stays part of the model id. The model-divergence check reads the pin literally when the seat's `models.json` defines a model with that exact id; otherwise it accepts the model with or without the suffix. If the seat's `models.json` can't be read, a pin with a suffix stays unchecked, with the usual warning, when the recorded model matches the whole pin or the pin without its suffix. A record that matches neither is reported.
 - **Custom models:** Pi reads `models.json` from its agent directory, so a seat reads `$OPENRIG_HOME/state/pi/<session>/agent/models.json`, not `~/.pi/agent/models.json`. Custom provider and model definitions for a seat go in that file. A seat that uses only providers Pi already includes does not need one. OpenRig does not create or write `models.json`.
 - **Credentials:** The Pi process receives only `PATH`, `HOME`, `USER`, `LOGNAME`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY`, `KIMI_API_KEY` or `MINIMAX_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>`, `kimi-coding/<id>` or `minimax/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
 
@@ -425,7 +466,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 - **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. A provider whose key is scoped to one endpoint also accepts that endpoint's variable: `anthropic`, `openai` and `litellm` each take their `<PROVIDER>_BASE_URL` — `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, `LITELLM_BASE_URL`. The allowlist admits each variable on its own, so an endpoint named without its key is admitted too, which suits a keyless local proxy. The launch gate admits these endpoint names for OMP seats; the match against the seat's declared `provider/id` happens at the OMP child, which forwards a matching endpoint already in the runner's environment just as it forwards a 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.
+- **Model errors:** Errors are printed in the pane. A completed assistant failure with a numeric `errorStatus` of 408, 429, 500, 502, 503, 504, or 529 returns to idle at terminal `agent_end`, allowing an ordinary retry. Until that terminal boundary it stays in needing-attention. Intermediate `agent_end(isTerminal:false)` events do not release attention. A statusless failed retry summary retains that classification only when its attempt matches an announced retry and its final error exactly matches the latest typed transient assistant failure in that attempt. New assistant/turn boundaries invalidate the previous failure; unmatched summaries remain runtime errors. Rejected prompts, auth/configuration failures, exhausted retries without a typed transient status, and untyped errors (including text such as `529 overloaded`) retain attention until the next agent run starts. The runner does not classify diagnostic text. A transient failure does not clear a denied approval or another unresolved runtime failure in the same turn.
 - **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
@@ -440,6 +481,8 @@ profile: none
 
 All three must be present together. Any partial combination is a validation error.
 
+A terminal seat no longer waits for a `--fresh` decision just because it has no resume token: on restore it relaunches fresh and re-runs its startup actions. The runtime, identity and replay prerequisites still apply. A runtime mismatch still waits for a decision, an ambiguous occupant still fails, and a missing required replay file still blocks.
+
 ### agent_ref Rules
 
 - Must start with `local:` or `path:`
@@ -588,8 +631,26 @@ The harness readiness window defaults to 30 seconds. On a loaded machine, set
 `rig config set runtime.readiness_timeout_seconds 60` to give new seats and
 handover successors longer to become interactive. The setting accepts 1–600
 seconds, applies to the next launch without a daemon restart, and can also be
-set with `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`. It does not change the
-time spent by the runtime adapter before readiness polling starts.
+set with `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`. It also bounds how long a
+restore keeps watching a Claude seat whose resume is still starting, so raising
+it for slow fresh launches lengthens that wait too. The wait is about the
+setting in total per seat, counting the usual 3.2-second check: the adapter polls
+for the rest of it (nominally: it counts polls, and each poll's tmux and process
+reads add a little). A restore
+starts seats one after another, so each seat that never starts Claude adds up to
+about this much, minus the 3.2 seconds, to the restore; the time adds up seat by
+seat, and a longer setting means a longer wait before a stuck seat is reported.
+A seat that is still not interactive then ends `attention_required` with its
+launch and resume token kept, and the later readiness wait is skipped for it.
+That holds at every setting: at 1–3 seconds there are no extra polls, but an
+unresolved boot is still kept rather than failed. A pane that shows a Codex or
+another conversation's Claude is not waited for. `rig up` and
+`rig launch` wait 120 seconds for the daemon, so a restore of several stuck
+seats can pass that (in one measurement, about 31 seconds a seat at the
+default, 95 for three). A client timeout and exit code 1 do not mean the
+restore was rolled back or that it should be run again; check the real state
+first with `rig ps`. Apart from this, the setting does not change the time
+spent by the runtime adapter before readiness polling starts.
 
 ---
 

package/daemon/docs/reference/rosters.md

@@ -49,8 +49,22 @@ Authored files contain recommendations, not runtime facts. Extra fields are igno
 any authored runtime, model or activity. At read time the command joins by exact host self-id
 and seat. Unmatched or conflicting observations are `unknown`; a seat not reported running is
 `stale`, with current runtime/model unknown. The configured model is the registry declaration.
-The observed native model remains unknown: these commands do not open native histories or verify
-what model the provider is running. Activity includes its sample time when the daemon supplies it;
+Daemon node listings, `rig ps --nodes --full` and roster members also carry the full
+`modelObservation`: `status`, `model`, `source`, `observedAt`, `generation` and `reason`.
+Compact JSON uses the smaller shape described below. The configured `model` stays separate; roster's
+`live.observedModel` is the observation's model or null. Human output says **last observed**.
+Claude (`claude-assistant-response`) and Pi (`pi-assistant-response`) name response evidence;
+Codex (`codex-turn-context` or `codex-world-state`) names recorded turn configuration, not a
+verified backend response. The timestamp is the native record's time, never file mtime or inventory
+read time. None promises the model that will answer the next turn.
+
+The daemon reuses the current-occupant record selectors and bounded readers used by divergence
+monitoring, sharing a process census. Reporting does not need a configured model or comparator.
+A changed or unverified occupant, a record predating its tenure, missing or invalid record time,
+unreadable or ambiguous records, unsupported runtimes and older daemons report **UNKNOWN** with
+a reason, never the configured value as a fallback. An older record from the same verified occupant
+remains labelled last observed at its original time; this is not a freshness guarantee. No record
+contents, transcript paths or credentials are returned. Activity includes its own sample time;
 activity and running status do not promise that someone is available for new work.
 
 The JSON `observations.readAt` is when the inventory read completed, not a native observation
@@ -59,3 +73,16 @@ valid rosters remain usable; duplicate IDs make `show` report ambiguity instead
 Non-regular file targets, such as FIFOs and directories, are skipped with a warning; links to
 regular files remain readable. Inventory uses `ps --no-cleanup` to preserve even stale local
 daemon state files. Ordinary `rig ps` keeps its existing cleanup behavior unless given that flag.
+
+The daemon reuses model facts only while the selected record's identity, size and
+modification time and the occupant generation remain unchanged. Inventory reads
+share two bulk pane snapshots and one process census; identity is checked after
+the final snapshot. A different observation from duplicate host routes makes
+only that observation UNKNOWN, preserving agreed registry fields.
+
+`rig ps --nodes --json` keeps an observed model compact as
+`modelObservation: ["literal-model-id", "evidence-source", "native-record-time"]`.
+UNKNOWN is `{ "status": "unknown", "reason": "..." }`; older daemons may yield
+`null`. `--full` and `--fields modelObservation` retain the full object, including
+its status and occupant generation. Human output and roster reports use the full
+labelled observation.

package/daemon/docs/reference/schemas/bundle-behaviour.v1.schema.json

@@ -212,7 +212,11 @@
             "description": "Host settings (for example OPENRIG_YOLO, persisted or native settings) decide the effective permission at launch."
           },
           "permissionPrompts": {
-            "enum": ["off", "on", "default"],
+            "enum": [
+              "off",
+              "on",
+              "default"
+            ],
             "description": "Archive declaration per seat: off for full_bypass (including builtin:yolo) on any runtime; on for a Claude/Codex flag-surface floor policy, or Codex under auto; default for Claude/Codex with no declared policy. Omitted for Claude under auto, config-surface policies, host-resolved Codex profiles, and Pi except declared full bypass. Absent means not stated, never on. Host settings may differ; nativeEffect remains unknown."
           },
           "sourceRefs": {
@@ -417,7 +421,10 @@
           "commands": {
             "type": "array",
             "description": "Unexecuted author setup lines, in order in one shell; the install command follows in the resulting working directory.",
-            "items": { "type": "string", "minLength": 1 }
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
           },
           "status": {
             "const": "not_checked"
@@ -459,6 +466,102 @@
           }
         }
       }
+    },
+    "services": {
+      "type": "array",
+      "description": "Optional opt-in service declarations from archived Compose YAML. Host-resolved values remain unresolved; no Compose or health probe ran.",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "composeFile",
+          "image",
+          "ports",
+          "privileged",
+          "capAdd",
+          "securityOpt",
+          "devices",
+          "environment",
+          "mounts",
+          "healthcheck",
+          "waitFor",
+          "downPolicy",
+          "unresolved",
+          "notes"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "composeFile": {
+            "type": "string"
+          },
+          "image": {
+            "type": "string"
+          },
+          "ports": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "privileged": {
+            "type": [
+              "boolean",
+              "string"
+            ]
+          },
+          "capAdd": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "securityOpt": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "devices": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "environment": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "mounts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "healthcheck": {},
+          "waitFor": {
+            "type": "array"
+          },
+          "downPolicy": {
+            "type": "string"
+          },
+          "unresolved": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "notes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
     }
   },
   "allOf": [

package/daemon/docs/reference/scoped-operating-posture.md

@@ -81,8 +81,18 @@ their bindings and ten-field records. They do not imply either operating posture
 Only human-led/delegated bindings participate in posture precedence. The legacy
 `effective` and `posture: known|unknown_posture` fields remain for compatibility;
 `unknown_posture` there means no legacy mode binding and does not override the
-new `operatingPosture.source: product-default` result. Setting another mode at the
-same scope replaces that row; inspect effective posture after any mode change.
+new `operatingPosture.source: product-default` result. A saved legacy mode and a
+posture are kept side by side at the same target: a write replaces only the
+binding of its own kind. Inspect effective posture after any mode change.
+
+Eight of the record's fields are stored, validated and shown, but nothing in
+OpenRig acts on them yet: `autonomy_scope`, `heartbeat_cadence`,
+`inspection_depth`, `update_detail`, `escalation_threshold`, `concurrency_limit`,
+`permission_prompt_posture` and `expiry_or_stale_rule`. `rig mode effective`,
+`rig mode defaults` and the `rig mode set` preview mark them `(stored; not applied)`.
+`scope` is the binding's key, and the posture reads `evidence_citation` into its
+`binding.evidence`. `permission_prompt_posture` never changes a native permission
+prompt.
 
 ## Diagnosis effects