@openrig/cli 0.6.5 → 0.6.7

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.5"
+version: "0.6.7"
 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:
@@ -14,3 +14,6 @@ files:
   - path: rig-spec.md
     role: reference
     summary: "The rig specification format."
+  - path: whats-new.md
+    role: reference
+    summary: "What changed in the installed version, for an agent on an upgraded install."

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-07, at the 0.6.6 cut `2620dea8` (whole document at `fcaf1f8e`; changes to its sources since then checked)
+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`, `packages/daemon/src/adapters/kernel-authority.ts`, `packages/daemon/src/domain/native-permission-store.ts`, `packages/daemon/src/domain/codex-team-workspace.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,124 @@ 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 ask through a session `PreToolUse` hook. Their literal help forms, such
+as `rig down --help`, `rig bundle install -h` and `rig help down`, run without
+that lifecycle prompt. Native personal, project and managed deny/ask rules still
+apply; OpenRig does not remove or override them.
+
+For allowances, the hook recognizes literal command words (including quoted or absolute paths),
+leading environment assignments that do not change executable lookup or startup,
+and `env`, `command` and `exec` wrappers without options other than `--`.
+Relative executable paths and assignments such as `PATH` or `NODE_OPTIONS` stay
+with native checks. The same existing team allowances apply after spelling
+normalization; project `node_modules/.bin/vitest` and `jest` paths match their
+existing `npx` allowances. It does not automatically allow pipelines, command
+substitutions, redirects, heredocs, shell functions or other unrecognized syntax.
+Lifecycle prefixes are checked at every word position, including after wrappers,
+control-flow words and CLI argument separators. A `--` separator before or after
+the subcommand ends option parsing, so a later `--help` is an operand and still
+asks. Ask detection also scans with comment text retained, so a `#` inside a
+substitution does not hide a later lifecycle command. Unquoted prose or comments
+containing a lifecycle command may also ask; ordinary trailing comments do not
+change allowance matching. Quoted messages and quoted heredoc bodies remain data.
+Arithmetic shifts are not treated as heredoc operators. These are command
+allowances, not containment: a project's test command can execute code. The
+hook and allowances are passed with `--settings` at launch, including resume
+and fork; nothing is written to personal or project permission files.
+
+If the helper asset is missing at launch, OpenRig falls back to the native lifecycle
+ask rules; help can prompt in that fallback. A helper that disappears or times out
+after launch cannot supply a decision, leaving Claude's remaining native rules
+in effect. The hook is a convenience policy, not a containment boundary.
+
+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 (a non-kernel seat with no policy also gets the
+[team launch default](#team-launch-defaults) above):
+- 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`, plus per-launch `-c` overrides that hide its
+full-access and GPT-5.1 migration notices, whatever the rig's non-interruptive choice.
+
+**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
@@ -250,9 +370,9 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 | `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
@@ -274,10 +394,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. 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`. |
+| `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`)
@@ -286,14 +413,14 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 
 - **State:** Each seat uses `$OPENRIG_HOME/state/pi/<session>/agent` as its Pi agent directory, with `sessions/` beside it, instead of your default `~/.pi/agent`. The runner sets `PI_CODING_AGENT_DIR` to that directory. `<session>` is the seat's session name, unchanged; for a pod member it is `{podId}-{memberId}@{rigName}`. `$OPENRIG_HOME` defaults to `~/.openrig`. OpenRig creates these directories at launch and does not copy anything from `~/.pi/agent`.
 - **Custom models:** Pi reads `models.json` from its agent directory, so a seat reads `$OPENRIG_HOME/state/pi/<session>/agent/models.json`, not `~/.pi/agent/models.json`. Custom provider and model definitions for a seat go in that file. A seat that uses only providers Pi already includes does not need one. OpenRig does not create or write `models.json`.
-- **Credentials:** The Pi process receives only `PATH`, `HOME`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY` or `KIMI_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>` or `kimi-coding/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
+- **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.
 
 ### Oh My Pi (`runtime: omp`)
 
 `runtime: omp` launches Oh My Pi through OpenRig's RPC runner. It is separate from `runtime: pi`; OMP does not use Pi's `--name` or `--approve` flags.
 
 - **State:** Each seat uses `$OPENRIG_HOME/state/omp/<seat>/agent` and `sessions/` instead of your default `~/.omp` profile, and runs with that seat directory as `HOME`. OpenRig does not copy OMP credentials. The runner finds the real `omp` binary before switching `HOME`, so a version-manager shim such as mise on the daemon's `PATH` still works.
-- **Credentials:** Provision each seat separately, or put the provider's key variable in `recovery.provider_auth_env_allowlist` (for example `ANTHROPIC_API_KEY` or `MISTRAL_API_KEY`). The allowlist accepts the key variable of every provider in OpenRig's OMP provider map, from `anthropic` through `litellm`. A seat receives a key only when its `model` is written as `provider/id`, such as `anthropic/claude-sonnet-4-5`. Short names such as `opus` pass no key. OMP also reads the launch directory's `.env`, so use a trusted working directory.
+- **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.
@@ -342,7 +469,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 |
@@ -384,7 +511,7 @@ 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
 
@@ -401,7 +528,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. |
 
@@ -454,6 +581,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
@@ -464,7 +598,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. |
@@ -508,7 +642,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
 
@@ -522,10 +656,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}}`.
 
 ---
 
@@ -556,10 +690,20 @@ 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
 
+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
@@ -600,8 +744,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/reference/whats-new.md

@@ -0,0 +1,134 @@
+# What changed in OpenRig 0.6.7
+
+This note is for an agent on an install that was just upgraded to 0.6.7. It lists only what behaves differently from
+0.6.6 and what to do about it. For everything OpenRig can do, read the capability map:
+`rig context get onboarding-width/public-what-you-can-do.md`. Each release replaces this file, so
+`rig context get reference/whats-new.md` describes the installed version once the upgraded daemon is running. Without
+a running daemon, read `$OPENRIG_HOME/reference/whats-new.md`. The daemon refreshes that copy when it starts, so right
+after an upgrade it can still hold the previous version's note.
+
+## The OpenRig view is now the handoff
+
+- **Open the view as the step after install or start; don't wait to be asked.** Say you're opening it, run
+  `rig terminal open saved:kernel --window`, then tell the person where it opened. Don't ask "Open the OpenRig view
+  now?", don't wait for a phrase like "show me my agents", and don't finish by printing a command for them to copy. The
+  same command brings their agents back later.
+- **The layout follows the person's terminal width.** On a narrow terminal the operator gets the first tab. On a wide
+  one the dashboard and operator sit side by side and the advisor has its own tab. Inside herdr it opens a focused
+  `openrig kernel` space. A `kernel` view the person saved themselves still wins.
+- **It opens where the caller is.** Terminal gets a window and Ghostty a tab. From Claude Desktop, iTerm or VS Code on a
+  Mac it opens a new Ghostty or Terminal window, and macOS may ask to allow it: mention that clicking Allow is fine only
+  in that case. Over SSH, in CI or with no display, it returns a definite no-window result with the reason. Relay the
+  `run:` command it prints exactly, or give `env -u TMUX tmux attach-session -t '=<canonicalSessionName>'` for the
+  operator.
+- **`rig terminal open <view>` opens a window by default.** Pass `--provider herdr` or `--provider cmux` only to add
+  tiles to a workspace that's already visible. With `--json`, `reusedWorkspace` and `opened: []` mean an existing view
+  was reused, which is success.
+- **The TUI's action is now "Open terminals ▸"** (it was `term ▸`). It opens a desktop window through the same
+  launcher, so the TUI must run on the daemon's desktop.
+- **The `rigs` skill is installed for the person's own agent.** The daemon writes it to `~/.claude/skills/rigs` and
+  `~/.agents/skills/rigs` and refreshes it on every upgrade. It now triggers on any mention of OpenRig, rigs or a team
+  of coding agents. A copy added earlier with skills.sh is left alone and never refreshed.
+
+## Installing and setting up
+
+- **Show the install preview first.** The published install command has a `--dry-run` preview
+  (`rig context get reference/getting-started.md` has both forms). Run the install when the person agrees. If the only
+  failures left are provider sign-ins, have them sign in and continue at "Start the kernel".
+- **If your own harness refuses a tool call while installing,** say so and show the refusal: Claude Code's auto mode can
+  deny calls as well as approve them. Let the person review it in their harness or run that step themselves. A refused
+  call doesn't prove the OpenRig command failed.
+- **`rig setup` installs herdr by default** on macOS and Linux; `--no-herdr` declines it. On a Mac, ask once about
+  Ghostty and on yes rerun `rig setup --ghostty`, keeping `--no-herdr` if it was chosen. Setup no longer installs cmux,
+  and an existing cmux still works. In `--json` output the `cmux_install` step is gone and `herdr_install` and
+  `ghostty_install` appear.
+- **`rig doctor` checks Claude and Codex installs, and a login or configured provider credential,** the way setup does.
+  It exits 1 when either harness is missing or has neither, including one the person doesn't use, so ignore a failure
+  on an unused harness. A pass means a login or configured provider credential is available locally, not that a
+  provider accepts the credential or that an agent can work; no provider request or agent work is tested.
+- **When setting up permissions,** recommend keeping the team default and offer remembered allowances only if the
+  person wants fewer prompts. People slowed by prompts can be pointed to the workshop listing.
+- **Windows users go through WSL2.** For Pi seats there, offer either credential route; a global Pi login still isn't
+  shared with managed seats.
+
+## Fewer prompts
+
+- **In Claude team seats, help on lifecycle commands runs without a prompt.** `rig down --help` and `-h` forms run;
+  the lifecycle actions themselves still ask. Pipelines, command substitutions, redirects and heredocs aren't allowed
+  automatically.
+- **The kernel operator's Claude session runs routine inspection without prompts:** Python, command lookup, `cd`, text
+  helpers and WebFetch. Compound commands and redirects still go to Claude's own permission check.
+- **Managed Codex seats no longer stop at the update menu on start.** Updating Codex is the operator's job: if a Codex
+  seat says its model needs a newer Codex, offer to update Codex and restart that seat, without stopping the team. If a
+  Codex seat shows a model-switch menu near a rate limit, ask the person; don't change the team's model.
+
+## Messages, wakes and Slack
+
+- **A send or wake no longer answers a question that's waiting for a person.** It's refused with
+  `target_needs_input`, and the reason ends `; latest hook, pane unrecognized` when the screen can't be read, even if
+  the hook is minutes old. Read the seat with `rig capture` and get the question answered by whoever should answer it.
+  Don't retry the send.
+- **Slack can post to a channel per rig or seat:** `rig slack channel-map list`, `set <match> <channel>` and
+  `remove <match>`. After a change, invite the app to each channel, run `rig slack verify`, then `rig slack disable`
+  and `rig slack enable` (or restart the daemon). Thread replies still reach the seat in any channel.
+- **A reaction on any part of a Slack ask reaches the seat that asked,** as a task tagged `human-reaction`. Treat it as
+  a signal to interpret, not an answer; the ask stays open. An existing app needs the `reactions:read` scope, the
+  `reaction_added` event and a reinstall, and `rig slack verify` warns when the scope is missing.
+- **A long Slack ask is posted in parts.** If it still can't be posted, you get a task `<ask id>-undeliverable`, tagged
+  `slack-undeliverable`: shorten the ask or link a file for the long part, and send it as a new ask.
+- **Replies sent with "Also send to #channel" now arrive** at the seat that asked, like any other thread reply.
+
+## Running teams
+
+- **`rig down` prints what each agent seemed to be doing before it stops them,** on one stderr line, or "unknown". It's
+  a best-effort snapshot, not a record of what was interrupted. `rig down --host` now exits 2 when the remote teardown
+  reports errors.
+- **Before a handover or compaction, write the seat's recap** with
+  `rig context recap-write --rig <rig> --seat <seat> --file <draft.md>`, not a file tool, so earlier recaps are kept.
+  `rig seat handover <seat>` now works on the same seat again and again; a seat left half-handed-over recovers by
+  running it again.
+- **After a managed compaction, read the `refocusing` skill and consume the current topology and work traces
+  delivered with the restore.** Don't rerun them just to duplicate the delivery; name a missing trace. For a new trace
+  outside that context, use the skill's one-command form. The daemon now installs the skill globally.
+- **The built-in starter and factory leads publish their team's roster** at first start, so `rig roster list` and
+  `rig roster find <topic>` know those teams.
+- **Claiming a parked queue item clears its `blocked_on`.** To park it again on the same gate, run
+  `rig queue update <id> --state blocked` without `--blocked-on`: it reuses the previous gate. Add the usual wake when
+  one is required.
+- **A periodic reminder first fires one interval after you register it,** not immediately.
+- **Workflows:** `rig workflow run` and `rig workflow watch` exit 3 for an aborted instance. When a step that was sent
+  back completes again, the steps that depend on it run again too, including ones that had passed.
+- **Sharing teams:** `rig bundle create` and `rig up <link>` name the bundle after `rig.yaml`'s `name`, and
+  `rig bundle check` names the file in each finding. Submissions go to `mvschwarz/openrig-registry`. The bundle safety
+  check always runs, even with `--skip-version-check --force`.
+- **`rig context add <url> --git` retrieves shallowly by default:** the initial retrieval fetches only the current
+  commit, and a server that refuses shallow retrieval falls back to a full clone with a warning. Use
+  `rig context source update` for later revisions.
+- **Values that used to fail quietly are refused:** a bad `rig chatroom history --since` (fix the value; the room isn't
+  empty) and a `--wake-after` such as `7d` (use hours, for example `168h`).
+- **Pi seats print a `[pi-runner] seat …:` line at start** saying whether a credential was found and, if not, how to
+  fix it. A MiniMax model gets `MINIMAX_API_KEY` when that name is in `recovery.provider_auth_env_allowlist`.
+- **`agents.advisor_session` defaults to the kernel's advisor seat.**
+
+## What to stop doing
+
+- **Stop asking whether to open the OpenRig view, or waiting for a phrase.** Open it after install or start.
+- **Stop using `--provider herdr` for the first view,** and stop pre-warning about macOS prompts from Terminal or
+  Ghostty.
+- **Stop suggesting `--skip-version-check --force` to get past a bundle pre-check failure.** The check always runs.
+- **Stop retrying a send refused with `target_needs_input`.** Get the question answered instead.
+- **Stop telling people to untick "Also send to #channel" when they answer in Slack.** Those replies now arrive.
+
+## Known gaps in 0.6.7
+
+- **Not yet checked on a real machine:** opening the view from Claude Desktop, and the plain-tmux layout without herdr.
+  The full first install from nothing and a Linux run come after this release.
+- **Only one selected lifecycle-help command has been checked in a live Claude session;** source and parser coverage
+  is broader. If a help command still asks, report it.
+- **Codex team seats aren't asked before lifecycle commands yet.**
+- **The send gate trusts the most recently recorded hook.** If hooks are recorded out of order, it can hold a send for
+  a question that's already answered, or miss one that's waiting. `rig capture` shows the real screen.
+- **A Codex seat whose permission request was approved automatically can still read "needs input".**
+- **A launched team still writes its skills into its working folder.**
+- **After a restart, `rig status` shows `Kernel: skipped` whatever the kernel seats' state.** Read them with
+  `rig ps --nodes --rig kernel --full`.

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.5"
+version: "0.6.7"
 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.5"
+version: "0.6.7"
 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