@openrig/cli 0.6.4 → 0.6.6

package/daemon/context-packs/reference/instance-layout.md

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

package/daemon/context-packs/reference/manifest.yaml

@@ -1,7 +1,7 @@
 # Reference guides the help pack links to, loaded one file or section at a time by address
 # (rig context get reference/<file>#<section>). Each file is a symlink to docs/reference/.
 name: reference
-version: "0.6.4"
+version: "0.6.6"
 taxonomy: world
 purpose: "Version-matched reference guides the help guide links to. Load a single file or section by address; don't load the whole pack."
 files:

package/daemon/context-packs/reference/rig-spec.md

@@ -1,8 +1,8 @@
 # RigSpec Reference
 
 Version: 0.2 (pod-aware)
-Last validated against code: 2026-04-11
-Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/types.ts`
+Last validated against code: 2026-10-05, at main `fcaf1f8e`
+Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/types.ts`, `packages/daemon/src/domain/startup-validation.ts`, `packages/daemon/src/domain/permission-policy/policy-ref.ts`, `packages/daemon/src/domain/profile-resolver.ts`, `packages/daemon/src/domain/rigspec-preflight.ts`
 
 This is the canonical reference for the pod-aware RigSpec YAML format. Every field, validation rule, and default documented here was traced from the actual parser and validator code, not from prior documentation.
 
@@ -121,7 +121,7 @@ pods:
               applies_on: [fresh_start]
           actions:
             - type: send_text
-              value: "Load the implementation-pair skill and begin."
+              value: "Read your guidance and begin."
               phase: after_ready
               idempotent: true
       - id: qa
@@ -170,15 +170,17 @@ edges:
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `version` | string | yes | — | Must be `"0.2"` for pod-aware specs. |
+| `version` | string | yes | — | Use `"0.2"`. Any non-empty string validates; a spec is treated as pod-aware because `pods` is an array. |
 | `name` | string | yes | — | Rig name. Used in session naming (`{pod}-{member}@{name}`), snapshot identification, and spec library lookup. |
-| `summary` | string | no | — | Human-readable description. Shown in spec library, review surfaces, and `rig specs show`. |
+| `summary` | string | no | — | Human-readable description. Shown in the spec library, review surfaces and `rig specs preview` (in `rig specs show` only with `--json`). |
 | `culture_file` | string | no | — | Relative path to a rig-wide culture/constitution file. Must be a safe relative path (no `..`, no absolute). |
-| `permission_policy` | string | no | — | Permission policy attached to the rig. Either a built-in (`builtin:locked`, `builtin:standard`, `builtin:open`, `builtin:yolo`) or a safe relative path to a custom policy file (resolved from this spec's directory; no `..`, no absolute). Absent leaves the default floor. A member may set its own `permission_policy`, which takes precedence over the rig-level one. See "Attaching a permission policy" 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 members always use `AGENTS.md`. See "Choosing the Claude instruction file" below. |
+| `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. |
+| `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. |
 | `startup` | StartupBlock | no | — | Rig-level startup files and actions. Applied to all members via the startup layering model. |
-| `services` | ServicesBlock | no | — | Optional managed services (Docker Compose). When present, services boot before any agent launches. |
+| `services` | ServicesBlock | no | — | Optional managed services (Docker Compose). When present, `rig up` boots them before any agent launches; `rig import` doesn't boot them. |
 | `pods` | Pod[] | yes | — | At least one pod required. Each pod is a bounded context containing members and pod-local edges. |
 | `edges` | CrossPodEdge[] | no | `[]` | Cross-pod edges connecting members in different pods. Must use fully-qualified `pod.member` IDs. |
 
@@ -194,7 +196,7 @@ permission_policy: builtin:standard
 permission_policy: policies/my-cautious-dev.policy.md
 ```
 
-Built-in policies (`locked` / `standard` / `open` / `yolo`) are read-only and are
+Built-in policies (`locked` / `standard` / `open` / `yolo` / `auto`) are read-only and are
 referenced as `builtin:<name>`. A custom policy lives in your own project and is
 referenced by a safe relative path (no `..`, no absolute). A shipped example of the
 custom shape is `packages/daemon/policies/examples/my-cautious-dev.policy.md` — copy it
@@ -211,6 +213,99 @@ future managed launches of that stable seat; it does not rewrite this spec or
 its inherited policy provenance. `inherit` removes that override. See
 [per-seat permission mode](getting-started.md#per-seat-permission-mode).
 
+### Team launch defaults
+
+A non-kernel Claude or Codex seat with no authored permission policy, explicit
+seat permission selection, or named Codex profile receives the team launch
+default. An explicit policy, including `none` or `builtin:locked`, keeps its
+existing meaning. The default is derived again for fresh launch, resume, fork
+and handover; it is not saved as a user choice. Kernel, Pi and terminal behavior
+is unchanged.
+
+Claude keeps `acceptEdits` and receives inline session settings allowing ordinary
+`rig` commands, project reads and common project test commands (for example,
+`npm test`, `pnpm test`, `pytest`, `go test` and `cargo test`). Lifecycle commands
+such as `rig up`, `rig down`, `rig restore`, `rig bundle install` and seat stop or
+handover are listed as **ask** rules. Native deny and ask rules take precedence
+over allow rules. These are native command-matching rules, not filesystem
+containment: a project's test command can execute code. Flags before the verb
+(for example, `rig --host vps up`) or wrapper commands may not match the lifecycle
+prefixes. OpenRig does not write these settings into a personal or project
+permission file.
+
+Codex keeps `workspace-write` with its existing approval policy and receives the
+configured OpenRig workspace root plus its pod's shared state directory as
+additional writable directories. The team workspace preparer creates missing
+directory ancestors and excludes the home directory and its ancestors from its
+prepared scopes. Unavailable optional directories are warned about and omitted
+from that list without blocking launch. When no prepared scopes remain, the
+runtime adapter retains its existing pod-state `--add-dir` fallback, which this
+step does not prepare. This does not modify Codex permission files or enable
+non-interruptive mode.
+
+**Codex lifecycle commands do not gain a new approval rule.** With Codex's
+existing `on-request` policy, non-escalated sandboxed commands, including
+`rig up` and `rig down`, can run without asking. This default addresses writable
+workspace access; it does not promise a lifecycle confirmation prompt.
+
+### Built-in permission policies
+
+The five built-ins live in `packages/daemon/policies/builtin/`. Action names are the
+policies' own semantic classes.
+
+| Policy | Surface | Runs without asking | Asks a person | Denied |
+|--------|---------|---------------------|---------------|--------|
+| `builtin:locked` | config | `run_toolchain` (npm, node, tsc, tests, lint), `rig_up`, `rig_down` | nothing | everything else (`default_posture: deny`) |
+| `builtin:standard` | config | everything not listed, including `push_to_remote` (`default_posture: allow`) | `create_pr`, `publish_package`, `merge_or_release`, `force_push`, and the destructive class | nothing |
+| `builtin:open` | config | everything, including PRs, publishing, merges and force pushes (`default_posture: allow`) | the destructive class only | nothing |
+| `builtin:yolo` | flag (`launch_posture: full_bypass`) | everything; the runtime's permission prompts are bypassed at launch | nothing | nothing |
+| `builtin:auto` | flag (`launch_posture: auto`) | Claude runs with `--permission-mode auto`; Codex, Pi and OMP launch at the floor | Claude: decided by auto mode; others: as at the floor | Claude: decided by auto mode; others: as at the floor |
+
+The destructive class is `delete_everything`, `drop_persistent_store` and
+`reset_or_discard_vcs`; `builtin:locked`'s list also names `delete_files` and `force_push`.
+
+**At launch.** `builtin:yolo` selects Claude `--dangerously-skip-permissions`, Codex
+`-s danger-full-access -a never`, and Pi `--approve`. `builtin:auto` selects Claude
+`--permission-mode auto`, while Codex and Pi do not have an auto mode and launch at the floor.
+Every other seat launches at the floor:
+- Claude `--permission-mode acceptEdits`;
+- Codex `-s workspace-write`, or `-p <profile>` when the member sets
+  `codex_config_profile`, in which case the profile governs its own sandbox;
+- Pi `--no-approve` by default.
+
+Seats of the rig named `kernel` are the exception. With no member or rig policy, no
+per-seat choice and (for Codex) no named profile, Claude launches in `acceptEdits` with a
+per-launch `--settings` allow list for its file tools and operational commands, and Codex
+launches with `-s danger-full-access -a never`.
+
+**Config-surface policies are recorded, not applied at launch.** The seat still starts at
+the floor. The `allow`, `ask` and `deny` rules take effect once they are translated into the
+runtime's native settings. The `applying-a-permission-policy` skill in `openrig-core` does
+that translation, with per-runtime limits. For example, Claude's prefix rules can't
+reliably tell `git push --force` from `git push`. An `ask` waits for a person, so it pauses
+an autonomous seat. Standard suits interactive work, and the policy files point
+autonomous teams to Open or YOLO.
+
+**Pi has no permission policy.** `--approve` and `--no-approve` set Pi's resource trust. The
+OMP variant maps that trust to its approval mode: `yolo` under `--approve`, otherwise
+`always-ask`.
+
+**A custom policy file** is Markdown with frontmatter: `policy_schema_version: 1`, `name`,
+`source: custom`, `description`, and `surface`.
+- `surface: flag` adds `launch_posture` (`floor`, `full_bypass` or `auto`).
+- `surface: config` adds `default_posture` (`allow`, `ask` or `deny`) and the `allow`, `ask`,
+  `deny` and `destructive_class` lists (`[]` for none).
+
+**Claude Code's own checks.** The first time Claude Code starts an interactive session
+with permissions bypassed, it shows a warning dialog asking you to accept responsibility;
+declining exits. OpenRig reports such a seat as `attention_required` and holds its startup
+context for `rig seat continue`; `rig up --non-interruptive` or `rig bundle install
+--non-interruptive` accepts the warning with a launch flag instead (see
+[non-interruptive mode](non-interruptive-mode.md)). That choice is saved on the rig, not in
+`rig.yaml`. On Linux and macOS Claude Code refuses that mode when run as root or under `sudo`,
+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).
+
 ### Choosing the Claude instruction file
 
 OpenRig writes its instructions for Claude Code members into managed blocks in
@@ -247,17 +342,18 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `id` | string | yes | — | Pod identifier. Must not contain dots. Must be unique within the rig. Used as the first segment of session names and logical IDs. |
+| `id` | string | yes | — | Pod identifier. Must not contain dots or `@`. Must be unique within the rig. Used as the first segment of session names and logical IDs. |
 | `label` | string | yes | — | Human-readable pod name. Shown in UI explorer, graph groupings, and detail surfaces. |
 | `summary` | string | no | — | Pod description. |
-| `continuity_policy` | ContinuityPolicy | no | — | Pod-level continuity/restore policy. Controls compaction recovery, artifact management, and peer-driven restoration. |
+| `continuity_policy` | ContinuityPolicy | no | — | Pod-level continuity/restore policy, validated and stored with the pod (see "Continuity Policy"). |
 | `startup` | StartupBlock | no | — | Pod-level startup files and actions. Applied to all members in this pod via the startup layering model. |
-| `members` | Member[] | yes | — | At least one member required (enforced by pods needing content). |
+| `members` | Member[] | yes | — | The pod's members. It must be an array; validation doesn't refuse an empty one. |
 | `edges` | PodLocalEdge[] | no | `[]` | Edges between members within this pod. Must use unqualified member IDs (not `pod.member`). |
 
 ### Pod ID Rules
 
 - Must not contain dots (`.`)
+- Must not contain `@`, which separates the pod/member portion from the rig name in session addresses
 - Must be unique across all pods in the rig
 - Becomes the first segment of the qualified logical ID: `{podId}.{memberId}`
 - Becomes the first segment of the canonical session name: `{podId}-{memberId}@{rigName}`
@@ -268,17 +364,42 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `id` | string | yes | — | Member identifier. Must not contain dots. Must be unique within the pod. |
+| `id` | string | yes | — | Member identifier. Must not contain dots or `@`. Must be unique within the pod. |
 | `agent_ref` | string | yes | — | Reference to an AgentSpec. Must start with `local:` (relative) or `path:` (absolute). Exception: `builtin:terminal` for infrastructure nodes. |
 | `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
 | `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
-| `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `terminal`. |
-| `cwd` | string | yes | — | Working directory for the agent. Resolved relative to the rig root (the directory containing the rig spec). Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. |
+| `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. |
 | `label` | string | no | — | Human-readable member name. Shown in UI when present. |
 | `model` | string | no | — | Model override. Runtime-specific (e.g., `claude-opus-4-6` for Claude Code). |
-| `restore_policy` | string | no | `resume_if_possible` | Restore behavior. One of: `resume_if_possible`, `relaunch_fresh`, `checkpoint_only`. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
 
+### Pi (`runtime: pi`)
+
+`runtime: pi` launches the Pi coding agent (`pi --mode rpc`) through OpenRig's RPC runner.
+
+- **State:** Each seat uses `$OPENRIG_HOME/state/pi/<session>/agent` as its Pi agent directory, with `sessions/` beside it, instead of your default `~/.pi/agent`. The runner sets `PI_CODING_AGENT_DIR` to that directory. `<session>` is the seat's session name, unchanged; for a pod member it is `{podId}-{memberId}@{rigName}`. `$OPENRIG_HOME` defaults to `~/.openrig`. OpenRig creates these directories at launch and does not copy anything from `~/.pi/agent`.
+- **Custom models:** Pi reads `models.json` from its agent directory, so a seat reads `$OPENRIG_HOME/state/pi/<session>/agent/models.json`, not `~/.pi/agent/models.json`. Custom provider and model definitions for a seat go in that file. A seat that uses only providers Pi already includes does not need one. OpenRig does not create or write `models.json`.
+- **Credentials:** The Pi process receives only `PATH`, `HOME`, `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` or `KIMI_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>` or `kimi-coding/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
+
+### Oh My Pi (`runtime: omp`)
+
+`runtime: omp` launches Oh My Pi through OpenRig's RPC runner. It is separate from `runtime: pi`; OMP does not use Pi's `--name` or `--approve` flags.
+
+- **State:** Each seat uses `$OPENRIG_HOME/state/omp/<seat>/agent` and `sessions/` instead of your default `~/.omp` profile, and runs with that seat directory as `HOME`. OpenRig does not copy OMP credentials. The runner finds the real `omp` binary before switching `HOME`, so a version-manager shim such as mise on the daemon's `PATH` still works.
+- **Credentials:** Provision each seat separately, or put the provider's key variable in `recovery.provider_auth_env_allowlist` (for example `ANTHROPIC_API_KEY` or `MISTRAL_API_KEY`). The allowlist accepts the key variable of every provider in OpenRig's OMP provider map, from `anthropic` through `litellm`. A seat receives a key only when its `model` is written as `provider/id`, such as `anthropic/claude-sonnet-4-5`. Short names such as `opus` pass no key. 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.
+- **Restore:** OMP creates its session file after the first persisted turn. A new seat with no persisted turn has no resume token; restoring it requires `rig up --existing <rig> --fresh <seat>`. After that file exists, OpenRig restores that exact session file. If a full rig restore leaves an OMP seat in `attention_required` or `failed`, `rig seat clear-attention` cannot yet reconcile it to `operator_recovered`, even with `--reason`, because restore reconciliation only verifies Claude Code and Codex processes ([#41](https://github.com/mvschwarz/openrig/issues/41)). Relaunch that seat with `rig up --existing <rig> --fresh <seat>`, or restore it manually.
+
 ### Terminal Nodes
 
 Terminal nodes are infrastructure processes (servers, log tails, build watchers) that are not agent runtimes. They require an exact triple:
@@ -309,6 +430,9 @@ The canonical session name is derived from the pod ID, member ID, and rig name:
 
 Example: pod `dev`, member `impl`, rig `my-team` → session `dev-impl@my-team`
 
+Pod and member IDs cannot contain `@` because the first `@` separates their portion
+of the session address from the rig name. Rig names may still contain `@`.
+
 This is human-authored (you choose the pod/member IDs) and system-validated (the system enforces the format).
 
 ---
@@ -320,7 +444,7 @@ This is human-authored (you choose the pod/member IDs) and system-validated (the
 | Kind | Meaning | Use When |
 |------|---------|----------|
 | `delegates_to` | Source delegates work to target. Constrains launch order. | Orchestrator → implementer, lead → worker |
-| `spawned_by` | Target was spawned by source. Constrains launch order. | Parent → child in hierarchical topologies |
+| `spawned_by` | Source was spawned by target; the target launches first. Constrains launch order. | Child → parent in hierarchical topologies |
 | `can_observe` | Source can observe target's output. Does NOT constrain launch order. | Reviewer → implementer, monitor → worker |
 | `collaborates_with` | Peer collaboration relationship. Does NOT constrain launch order. | Co-equal peers working together |
 | `escalates_to` | Source escalates to target for decisions. Does NOT constrain launch order. | Worker → lead for escalation |
@@ -362,13 +486,14 @@ Cross-pod edges must reference different pods. An edge where both `from` and `to
 
 ## Startup Block
 
-Startup blocks can appear at three levels: rig, pod, and member. They are merged additively via the startup layering model (see `docs/reference/startup-layering.md`).
+Startup blocks can appear at three levels: rig, pod, and member. They are merged additively via the startup layering model (see [the layering model](agent-startup-guide.md#the-layering-model)). The rig's `culture_file` joins as a required file with the `auto` hint in the culture layer, on both fresh start and restore.
 
 ### Files
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `path` | string | yes | — | Relative path to the file. Must be a safe relative path. |
+| `orientation` | string | no | — | Set to `role` to identify a per-seat role file for `rig queue whoami --json` and refocus. Does not change delivery or replay startup. |
 | `delivery_hint` | string | no | `auto` | How the file is delivered. One of: `auto`, `guidance_merge`, `skill_install`, `send_text`. |
 | `required` | boolean | no | `true` | Whether startup fails if this file cannot be delivered. |
 | `applies_on` | string[] | no | `[fresh_start, restore]` | When this file is delivered. Subset of: `fresh_start`, `restore`. |
@@ -378,7 +503,7 @@ Startup blocks can appear at three levels: rig, pod, and member. They are merged
 | Hint | Behavior |
 |------|----------|
 | `auto` | System chooses based on file type and context. |
-| `guidance_merge` | Merged into the runtime's guidance file (`CLAUDE.md` or `AGENTS.md`) as a managed block. Delivered before harness boot. |
+| `guidance_merge` | Merged as a managed block into the runtime's guidance file: for Claude, the `managed_blocks` file (`CLAUDE.md` or `CLAUDE.local.md`); for Codex, Pi and OMP, `AGENTS.md`. Delivered before harness boot. |
 | `skill_install` | Installed as a skill in the runtime's skill directory. Delivered before harness boot. |
 | `send_text` | Sent as text to the agent's terminal after the harness is ready. Requires the agent TUI to be active. |
 
@@ -431,6 +556,13 @@ the current proof; resume/adoption also preserves existing proof history.
 The effective selection is recorded on `node.startup_pending`; actions are
 persisted in startup context for restore and fresh relaunch.
 
+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.
+
 ---
 
 ## Services Block
@@ -441,7 +573,7 @@ The services block is optional. When present, services boot before any agent nod
 |-------|------|----------|---------|-------------|
 | `kind` | string | yes | — | Service backend. Only `compose` is supported in v1. |
 | `compose_file` | string | yes | — | Relative path to the Docker Compose file. Must be a safe relative path. Resolved relative to rig root. |
-| `project_name` | string | no | derived from rig name | Docker Compose project name. Must match `[a-z0-9][a-z0-9_-]*`. If omitted, derived by sanitizing the rig name. |
+| `project_name` | string | no | stored predecessor project or unique rig-ID default | Docker Compose project name. Must match `[a-z0-9][a-z0-9_-]*`. An explicit value takes precedence. A new rig uses a stable, unique rig-ID-derived name. A same-name replacement inherits the stored project of the exact generations it replaces; conflicting predecessor projects require an explicit value. Existing stored names remain unchanged. |
 | `profiles` | string[] | no | — | Compose profiles to activate. |
 | `down_policy` | string | no | `down` | What happens on `rig down`. One of: `leave_running`, `down`, `down_and_volumes`. |
 | `wait_for` | WaitTarget[] | no | — | Health targets that must pass before agent launch. |
@@ -454,7 +586,8 @@ Each target must define exactly one of `service`, `url`, or `tcp`:
 
 ```yaml
 wait_for:
-  # HTTP probe — hits the URL, expects 2xx
+  # HTTP probe — any 2xx or 3xx response passes the HTTP wait target; redirects are not followed.
+  # This proves the server answered, not application readiness.
   - url: http://127.0.0.1:8200/v1/sys/health
 
   # TCP probe — connects to host:port
@@ -484,7 +617,7 @@ surfaces:
       command: "vault status -address=http://127.0.0.1:8200"
 ```
 
-Surfaces are metadata only. They are displayed in the UI and in `rig env status` output but are NOT executed by OpenRig.
+Surfaces are metadata only. They are displayed in the UI and in `rig env status --json` output (the text output lists only services) but are NOT executed by OpenRig.
 
 ### Checkpoint Hooks
 
@@ -498,10 +631,10 @@ checkpoints:
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `id` | string | yes | Unique identifier for this checkpoint. |
-| `export` | string | yes | Shell command to export state. `{{artifacts_dir}}` is replaced with a daemon-managed path. |
+| `export` | string | yes | Shell command to export state. |
 | `import` | string | no | Shell command to import state on restore. |
 
-Checkpoint hooks are shell commands run by the daemon. They are best-effort — a failed export does not block snapshot, but continuity is classified as `receipt_only` instead of `checkpointed`.
+Checkpoint hooks are validated and stored with the spec. In this version the daemon doesn't run them during snapshot or restore, and doesn't substitute `{{artifacts_dir}}`.
 
 ---
 
@@ -532,11 +665,24 @@ continuity_policy:
 | `restore_protocol.peer_driven` | boolean | no | — | Whether peers drive the restore process. |
 | `restore_protocol.verify_via_quiz` | boolean | no | — | Whether to verify restoration via quiz. |
 
+These fields are validated, stored on the pod and written back on export. In this version nothing acts on
+`sync_triggers`, `artifacts` or `restore_protocol`.
+
 ---
 
 ## Validation Rules Summary
 
-These rules are enforced by the validator. A spec that violates any of these will be rejected by `rig spec validate` and `rig up`.
+Unknown keys at the rig, pod, member and edge levels are refused ("unknown key … refusing the spec because
+normalization would otherwise discard it"). Keys inside `startup`, `services`, `continuity_policy` and `workspace` are
+not checked this way. Some rules are enforced at preflight rather than validation: the runtime must be one of the
+supported values, rig, pod and member names may use only letters, digits, `-`, `_`, `.` and `@` where allowed above,
+each `agent_ref` must have an `agent.yaml`, Codex profiles must load, and a cwd may not be inside the OpenRig
+installation.
+
+Schema validation checks the structural rules below. Pod and member IDs containing
+`@` are additionally rejected during preflight and member creation or launch; a
+spec can pass `rig spec validate` and then fail at preflight or import. Run
+`rig spec preflight` before creation or import.
 
 1. `version` and `name` are required non-empty strings.
 2. `pods` must be a non-empty array.
@@ -573,8 +719,13 @@ These are the built-in specs shipped with OpenRig. Read them as worked examples.
 
 | Spec | Location | Pods | Members | Services |
 |------|----------|------|---------|----------|
-| `product-team` | `packages/daemon/specs/rigs/preview/product-team/rig.yaml` | orch1, dev1, rev1 | 7 (lead, peer, impl, qa, design, r1, r2) | no |
-| `implementation-pair` | `packages/daemon/specs/rigs/launch/implementation-pair/rig.yaml` | dev | 2 (impl, qa) | no |
-| `adversarial-review` | `packages/daemon/specs/rigs/focused/adversarial-review/rig.yaml` | orch, review | 3 (lead, r1, r2) | no |
-| `research-team` | `packages/daemon/specs/rigs/focused/research-team/rig.yaml` | orch, research | 3 (lead, analyst, synthesizer) | no |
+| `starter` | `packages/daemon/specs/rigs/launch/starter/rig.yaml` | dev | 2 (build, review) | no |
+| `factory` | `packages/daemon/specs/rigs/launch/factory/rig.yaml` | orch, dev, review | 7 (lead, advisor, build, qa, design, r1, r2) | no |
+| `code-review` | `packages/daemon/specs/rigs/focused/code-review/rig.yaml` | orch, review | 3 (lead, r1, r2) | no |
+| `research` | `packages/daemon/specs/rigs/focused/research/rig.yaml` | orch, research | 3 (lead, analyst, synthesizer) | no |
+| `pm` | `packages/daemon/specs/rigs/focused/pm/rig.yaml` | pm, dev | 3 (lead, researcher, build) | no |
 | `secrets-manager` | `packages/daemon/specs/rigs/launch/secrets-manager/rig.yaml` | vault | 1 (specialist) | yes (Vault) |
+
+Also shipped, in the same tree: `launch/kernel`, OpenRig's own team, which starts automatically. `first-project` is
+starter's old name and still resolves to it. `workshop`, the four-agent middle team, is a rig bundle rather than a
+built-in. List the built-ins with `rig specs ls --kind rig`.

package/daemon/context-packs/skills/agent-operated-software/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-operated-software"
-version: "0.6.4"
+version: "0.6.6"
 taxonomy: "skills"
 purpose: "Use when designing, building, operating, or diagnosing an ongoing application whose live backend or control loop includes OpenRig agents, including applications with a Markdown, YAML, or JSON agent control plane or a thin surface over specialist agent roles."
 files:

package/daemon/context-packs/skills/agent-operated-workflows/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-operated-workflows"
-version: "0.6.4"
+version: "0.6.6"
 taxonomy: "skills"
 purpose: "Use when a bounded real-world procedure has a deterministic happy path but brownfield, variable, or partially knowable state; when an operation must resume from verified evidence; or when deciding whether agent judgment or ordinary code should own a procedure's control loop."
 files:

package/daemon/context-packs/skills/applying-a-permission-policy/SKILL.md

@@ -23,22 +23,34 @@ to invent tasks, publish work or change another host.
 Reuse an existing explicit choice for these harnesses and this scope from the
 user's onboarding context; do not ask again. Existing rules are configuration,
 not evidence of consent to expand their scope. Preserve them without expansion.
-If the choice is unknown, briefly explain:
-
-> This allows the whole `rig` command family, including starting/stopping agents,
-> changing OpenRig configuration and launching processes. It is not global YOLO
-> or permission to invent work. The scope is your personal settings for this
-> project unless you explicitly choose your user-wide sessions instead.
->
-> Allow your agents to run OpenRig commands without repeated permission prompts?
-> **Yes — recommended** / **No — keep prompts**
-
-- **Yes:** require an actual affirmative answer, then apply the procedure below
-  at that scope for the selected harnesses. Never substitute user-wide rules
-  when project rules are unsupported. Native restrictions still apply.
-- **No:** leave permission settings unchanged and continue with existing prompts.
-- **No answer:** make no settings change, infer no consent and continue with
-  existing prompts. Do not keep asking during this setup.
+
+For a team with no explicit policy, recommend keeping the team default. Claude
+already allows ordinary `rig` commands, project reads and common tests, while
+lifecycle commands ask. Codex already has writable workspace and pod state;
+its `on-request` policy does **not** guarantee lifecycle prompts. Explicit
+policies, seat choices and named Codex profiles keep their existing meaning.
+
+Native restrictions can still prompt for installs, commits, other shell
+commands and writes outside writable roots. With the Claude team default, an
+allow does **not** override lifecycle ask rules: `rig up`, `rig down` and the other listed
+lifecycle commands still ask even after Yes. Do not promise prompt-free operation.
+
+Only offer additional persistent allowances when wanted, for the selected
+project or explicitly user-wide scope, or to adjust an explicit seat policy:
+
+> Remember these selected OpenRig commands in your native settings for this
+> project? This is separate from the team launch default; stricter rules and
+> Claude lifecycle asks remain. **Yes / No — keep the team default**
+
+- **Yes:** require an affirmative answer, then apply the procedure below only
+  at the agreed scope. Do not replace ask/deny rules or substitute user-wide
+  settings when project rules are unsupported.
+- **No / no answer:** leave settings and any existing explicit choice unchanged.
+  With no policy selected, keep it unset; never record `none` to mean keeping
+  the team default. Do not repeat the question during this setup.
+
+A recommendation is not consent. Broader filesystem/network access requires
+its own explicit choice; permission consent is separate from launch approval.
 
 Remember an explicit Yes or No in the existing onboarding/project context the
 agent already reads: choice, harnesses and scope. For Yes, record the exact files
@@ -55,14 +67,20 @@ an answered setup question or ask again for routine steps already authorized.
 
 | Choice | What the agent configures |
 | --- | --- |
-| Keep prompts | Preserve current native settings and handle requests when they arise. |
+| Keep the team default | Leave an unset policy unset and preserve current native settings; Claude lifecycle asks and other native restrictions remain. Preserve any existing explicit choice. |
+| “Prompt for everything” (`none`) | Only on an explicit request, opt out of the team allowances. Native rules still decide each prompt; `none` does not guarantee a prompt for every command. |
 | Remember selected commands | Add native allow rules for the chosen family or narrower verbs, leaving other rules and sandbox settings intact. |
 | Broader permissive operation | Explain filesystem/network exposure and configure only the explicitly selected native mode and compatible launch settings. |
 
-**Allowing the whole `rig` family covers all its verbs**, including lifecycle,
+If repeated approvals later interrupt the work, name the actual commands and
+offer a scoped adjustment then. Keep the existing choice until the person
+accepts a change; do not promise to adjust later and silently leave the burden
+with them. Do not reopen an answered choice for each routine operation.
+
+**A whole-family allow matches all `rig` verbs**, including lifecycle,
 topology/config changes and commands that can launch other processes. It is not
-a read-only grant. Offer narrower prefixes such as `rig ps` or `rig queue list`
-when that better fits the request. Do not widen a choice to arbitrary shell
+a read-only grant, but stricter ask/deny rules still win. Offer narrower prefixes
+such as `rig ps` or `rig queue list` when that better fits the request. Do not widen a choice to arbitrary shell
 execution, an entire interpreter or a generic shell wrapper.
 
 ## Apply the choice for the user
@@ -95,7 +113,9 @@ execution, an entire interpreter or a generic shell wrapper.
    existing conversation loaded it.
 6. Verify an ordinary matching operation twice in the target conversation and
    check that an unrelated command gained no matching rule. Use harmless reads,
-   not destructive probes. Report effective settings and remaining prompts.
+   not destructive probes. Report effective settings, their source and remaining
+   prompts; a command already allowed by the launch default does not prove a new
+   persistent rule loaded.
    A parser match alone does not establish native behavior.
 
 Give the user this short undo: **“Undo the OpenRig command allowances added by

package/daemon/context-packs/skills/applying-a-permission-policy/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "applying-a-permission-policy"
-version: "0.6.4"
+version: "0.6.6"
 taxonomy: "skills"
 purpose: "Use before launching a team during agent-guided setup, or when a user asks to configure OpenRig command permissions, reduce repeated native approval prompts, or apply a selected rig/seat permission policy."
 files: