@openrig/cli 0.6.10 → 0.6.12

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

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

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.
+- 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,16 +436,17 @@ 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); an absolute path is used as is. 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. |
 | `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. |
 | `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`. Not valid on terminal members. |
+| `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. |
 | `startup` | StartupBlock | no | — | Member-level startup files and actions. Applied only to this member. |
 
@@ -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:** OpenRig does not pass a node's `effort` to Pi. To set Pi's thinking level, add it to the model as a suffix, for example `model: openrouter/x-ai/grok-4:high`. Pi accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`. 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.
 
@@ -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/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
 

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

@@ -37,7 +37,7 @@ one does not deprecate the others. Nothing below deletes or overrides an existin
 | **PRODUCT / MISSION PREPARATION** | **The product-management pass** — the layer above planning, run by the advisor/PM seat before planners touch a mission. The build is a lossy compression pipeline (PM intent → planner spec → builder code); nothing leaks downward by proximity, so this pass grounds in the raw sources, synthesizes ONE scope of record, presents owner decisions decision-ready, mints slices at plan time, deposits the full design contract INLINE in each design-bearing spec (owner words verbatim, settled decisions, evidence, shape of done, anti-goals), routes the complete reading list and internet-research assignments from the spec itself, frames each slice's planning-dial rung with its reason, and rereads every spec as the narrow downstream reader. The measuring stick: SPEC.md alone, plus what it explicitly routes to, reproduces the intent in a reader with none of the author's context. Full reference: `product-management-pass.md`. |
 | **PLAN** | **The planning dial** — planning rigor is a spectrum chosen per piece: P0 mini-requirements and pointers (simple, reversible work) · P1 an authored spec with a proof contract (the default) · P2 plus a research round before the spec freezes, run BEFORE build dispatch · P3 plus an adversarial pass by a non-author, judged against product goals, landing amendments with proof-contract teeth · P4 plus a blind from-scratch design diffed against priors before proceeding. Dial up by what the piece is, exactly as build care is priced below. Full reference: `planning-dial.md`. |
 | **BUILD** | **Part A, the simple flow** (below — the default) · **product-journey components** — a mission-selectable menu for greenfield work, drift recovery, public journey probes, one evidence-gated look at the layer below, minimal repair, independent QA/review, integration, and installed smoke; compose only what the work needs in mission/slice YAML, never as a new mode or mandatory pipeline. Full reference: `product-journey-sdlc.md` · **the wave model** — slices build in parallel in disjoint file territories, an integrator merges serially, and independent review fires once per wave (two reviewers with different vantages, never the writers; fix rounds re-earn verdicts at one final revision; per-slice discipline stays failing-test-first and verify-by-effect). The wave IS the care dial: what shares a wave decides how much review each piece gets · **Part B, the rigorous overlay** (below — only when assigned). These combine: a wave can carry one Part-B piece. Full wave reference: `wave-sdlc.md`. |
-| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE; when the slice's `slice.yaml` carries `execution.depends_on`, that list takes precedence); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live in `mission.yaml` `arrangement.waves` (`{id, slices, review_model?}`; a slice may also name its wave in `slice.yaml` `execution.wave`). Only when the mission has no `mission.yaml`, or it is malformed, does the view fall back to the legacy form: the newest queue row tagged `format:wave-map-v1` and `mission:<mission>` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. Existing batons are never rewritten. |
+| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE; when the slice's `slice.yaml` carries `execution.depends_on`, that list takes precedence); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live in `mission.yaml` `arrangement.waves` (`{id, slices, review_model?}`; a slice may also name its wave in `slice.yaml` `execution.wave`). Only when the mission has no `mission.yaml`, or it is malformed, does the view fall back to the legacy form: the newest queue row tagged `format:wave-map-v1` and `mission:<mission>` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. **Lanes:** Q1 lists each in-progress row as a lane; a row parked on `external:<what>` also appears as a waiting lane, marked `waiting: {on}`. `external:` records an outside dependency (a review, a decision, a capacity limit, a lifecycle step); it does not mean an outside party owns all the work, or that the parked seat is the slice's builder. The views show it as a waiting row (the seat, the blocker, a link to the row), not as the slice's assignment. It yields to an in-progress lane on the same slice, and it is not counted in `lanes_live`, so `q1_lanes` can be longer than `lanes_live`. Rows parked on a qitem, a human seat, or a `fold:`/`auth:` gate are not lanes. Existing batons are never rewritten. |
 | **RELEASE** | The release ceremony conventions (publication identity, honest release notes) and the CAPABILITY-DELTA LIFECYCLE LAW: each release's delta is authored at the fence and bound to the exact candidate, then reconciled to the published cut. Expiry requires both the canon header naming the absorbed delta and a distinct successor delta existing; a draft header alone is insufficient. Verify the actual boundary event and stop citing an expired delta. Full statement: `release-boundary.md` §6. |
 | **BOUNDARY** | **The release boundary** — housekeeping run once per fence so the next release starts clean: seats reset or re-primed per their continuity needs, memory distilled (keep what changed a decision recently), every queue swept by destination and dispositioned, substrate torn down, boards frozen as records, a clean-box baseline captured. A checklist of judgment guides, not gates. Full reference: `release-boundary.md`. |
 
@@ -83,6 +83,25 @@ truth is reconciled to main. Continuous integration to main and a
 release-line fold followed by one explicit merge are both valid; leaving the
 choice implicit is not.
 
+A candidate that merges by squash or rebase is never an ancestor of that ref, so
+ancestry alone cannot read it as merged. A `merged:<pr-number>` tag on a queue row
+bound to the slice (the `slice:` tag, like `candidate:`) is a recorded report of a
+merge, not a verified one: `rig view show execution` shows it on the "merged" rung
+(`folded`) as `merge_report` (`pr`, `row`, `recorded_at`, `linked`) and in the basis
+text, and `recorded_at` is when the row recorded the merge, not when it happened.
+A report never changes the merged answer by itself: without a candidate, with an
+unresolvable candidate, with an unusable declared integration ref or with no
+repository context, the answer, next-up and dependent slices stay as ancestry gives
+them. A row that carries a `merged:` tag is a report, not a build, so it never picks
+which commit counts as built: that stays the newest `candidate:<sha>` tag on a row
+without a `merged:` tag. A report is `linked: true` when its own row's `candidate:<sha>`
+resolves, through the repository context, to that built commit, and `linked: false`
+otherwise (no candidate on the row, or a different commit). The answer changes only
+for a linked report when ancestry answered false (not an ancestor): then the rung
+reads merged and the basis says so. A linked report never turns an answer ancestry
+could not give into merged. The report never changes which commit counts as built
+or reviewed.
+
 **The heavier flow — proof contracts, plan-lock, C1 drops, proof-lock — is PART B and is not in
 force unless assigned.**
 
@@ -117,17 +136,46 @@ Legacy `README.md`, `IMPLEMENTATION-PRD.md`, and pre-convention trees remain
 readable indefinitely. New scaffolds do not create or mirror them, and repair
 is additive: it never deletes, renames, or rewrites legacy bytes.
 
+A slice's frontmatter carries `stage:` (`wip`, `provisional`, `established`,
+`canonical`, or the exits `superseded` and `retired`) and `verified:`
+(`<date> against <source>`). Set them with `rig scope slice stage <slice> <stage>`
+and `rig scope slice verified <slice> --against <source>`; no approval stamp
+changes either. `rig scope` reads an `established` or `canonical` slice whose
+`verified:` is missing, has no source, names a tool-scaffolded placeholder, or is
+older than 90 days as `provisional`.
+
 When the owning scope selects `proofPolicy.judges`, use `rig proof judge` to
 record an attributed accept, reject or withdraw decision on a contract item,
 and `rig proof show` to read derived readiness up through slice, mission and
 project. The nearest slice, mission or project policy selects authorized judges;
-`rig proof --help` describes setup, selectors and evidence requirements. A
+`rig proof --help` describes setup, selectors and evidence requirements. In a
+multi-project workspace catalog, name the project with `--project <id>` or a
+`<id>:` scope prefix (`alpha:m0/slices/01-t001`); unqualified scopes use the
+daemon's selected workspace. The prefix counts only when it names a catalogued
+project and no scope exists at that literal path, so a mission folder with a
+colon (`alpha:trial/slices/01-t001`) still resolves as written. The scopes views
+read a catalog project's readiness against the same project root, so they agree
+with `rig proof show`. A catalog-project read names the project
+(`project: { id, root }`) and reports its source watcher as unavailable; a
+judgment carries that root and is refused (409 `project_changed`) if the
+catalog has since moved the project. A
 correction preserves history and unrelated judgments without editing ancestor
 status checklists. An artifact can identify non-code work without a fabricated
 commit. Evidence capture (`proof add`), policy acceptance, higher outcome
 judgment and publication are distinct. This optional component does not select
 Part B or add a mandatory review gate.
 
+The project readiness that `rig proof show --project` reports counts only
+missions whose `mission.yaml` carries `metadata.status: active` or
+`metadata.status: release-candidate`. `rig scope mission create` writes
+`metadata.status: planned`, for ordinary and release missions alike, so creating
+a mission does not change the project's readiness. A `planned` mission stays
+outside the rollup, even after its slices are accepted, until someone changes
+its status to `active` (or `release-candidate` for a release that is ready to
+judge). Nothing changes the status automatically. Missions created before this
+default carry no status and are not counted either; add the line by hand to
+include them.
+
 The three sections project into the UI's one review structure: a vertical
 stack of **INTENT → PLAN → DELIVERED**. A slice missing a section still
 renders (a missing Intent or Delivered source shows a muted "—", missing