@openrig/cli 0.6.5 → 0.6.6

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

@@ -1,13 +1,43 @@
 # Agent Startup Guide
 
-Version: 0.2.0
-Last validated: 2026-04-11
-Applies to: OpenRig 0.1.x
+Last validated: 2026-10-05, against main `9b88b118`
+Applies to: OpenRig 0.6.6
 
 This guide teaches you how to think about what goes into an agent's startup experience — what files to write, where to put them, and how the layering model delivers them. It is an authoring guide, not a schema reference. For field-level details, see `rig-spec.md` and `agent-spec.md`.
 
 ---
 
+## Continue after a native consent prompt
+
+If a fresh Claude seat is waiting at its bypass-permissions warning, review and
+answer that warning in the seat's native pane. Unless the rig was launched with
+`--non-interruptive` (see [non-interruptive mode](non-interruptive-mode.md)),
+OpenRig does not accept it for you, and it never sends configured startup context
+into the active dialog. The seat reports `attention_required` and retains that
+context for the same occupant.
+
+After accepting, run `rig seat continue <seat>` (or press `c` on the seat in the
+TUI, shown while its context is pending). This delivers the pending context
+without relaunching Claude, and its first prompt reminds the seat that this is a
+fresh conversation and how to find its work. It does not replay a delivery that
+already started. A timeout, or a refusal because nothing is pending, reports an
+unknown outcome; inspect `rig seat status <seat>` before taking another action.
+It is also refused while the prompt is still showing (`attention_required`), or
+when the seat's binding or runtime has changed since launch.
+Runtime readiness, startup delivery, and orientation proof remain separate;
+a missing proof does not block this continuation.
+
+Other fresh-launch prerequisites, such as login or workspace trust, use the same
+continuation: resolve the prerequisite in the native pane, then run the displayed
+command. `rig ps --nodes` shows it under "Startup details (<seat>)", and
+`rig up` and `rig bundle install` print it as "Startup attention (<seat>)":
+"After resolving it in <session>, run: rig seat continue <session>".
+
+The attention codes that stop startup this way are `trust_gate`,
+`hook_trust_gate`, `update_gate`, `login_required`, `mcp_gate`,
+`bypass_consent_gate`, `codex_auth_refusal` and `codex_client_incompatible`.
+They are recognized from each harness's English prompt text.
+
 ## Two Categories of Startup
 
 Everything an agent receives at boot time falls into one of two categories:
@@ -26,14 +56,14 @@ Context loading shapes what the agent knows, believes, and is capable of:
 ### Category 2: Deterministic Configuration
 
 The rig spec declaratively installs things into the agent's runtime environment:
-- Hooks (git hooks, pre-commit scripts)
+- Hooks (shipped inside plugins)
 - Permissions (`.claude/settings.json` allowlists, approval modes)
 - MCPs (Model Context Protocol servers)
 - System dependencies (tools, packages)
 
 See the **Current Support Matrix** section at the end of this guide for what is reliable today vs experimental.
 
-**The v0.2.0 recommendation:** Put as much of your setup logic as possible into Category 1 (context loading via markdown files). Describe the desired end state in startup files and let the agent handle the configuration. The deterministic path exists in the spec and will become more reliable over time, but for now the context-loading path is the one that works consistently across runtimes.
+**The recommendation:** Put as much of your setup logic as possible into Category 1 (context loading via markdown files). Describe the desired end state in startup files and let the agent handle the configuration. The deterministic path exists in the spec and will become more reliable over time, but for now the context-loading path is the one that works consistently across runtimes.
 
 ---
 
@@ -118,30 +148,35 @@ Startup content is merged additively through layers. Each layer adds to what the
 ```
 1. Agent layer     — from the AgentSpec's top-level startup block
 2. Profile layer   — from the active profile's startup block
-3. Rig layer       — from the RigSpec's top-level startup block
-4. Culture layer   — from the RigSpec's culture_file
+3. Culture layer   — OpenRig's default culture, then the RigSpec's culture_file
+4. Rig layer       — from the RigSpec's top-level startup block
 5. Pod layer       — from the pod's startup block
 6. Member layer    — from the member's startup block in the RigSpec
-7. Operator layer  — injected at runtime (openrig-start overlay, context collector, etc.)
+7. Operator layer  — added by OpenRig: openrig-start.md and, on a fresh start, the onboarding pack
 ```
 
+A member with a `starter_ref` gets that agent starter's files in front of the agent layer. Terminal seats
+(`builtin:terminal`) skip the agent and profile layers.
+
 ### What Each Layer Is For
 
 | Layer | Authored by | Purpose | Example content |
 |-------|-------------|---------|-----------------|
 | Agent | Agent spec author | Core identity and capabilities that travel with this agent type | Role guidance, default skills |
 | Profile | Agent spec author | Profile-specific variations | Different skill sets for "default" vs "minimal" profiles |
-| Rig | Rig spec author | Rig-wide context for all agents | Team norms, project documentation |
-| Culture | Rig spec author | Rig constitution | `CULTURE.md` — communication, quality, operating philosophy |
+| Culture | OpenRig, then the rig spec author | Team norms | OpenRig's `CULTURE-default.md` for every seat, then the rig's own `CULTURE.md` |
+| Rig | Rig spec author | Rig-wide context for all agents | Project documentation |
 | Pod | Rig spec author | Pod-specific coordination context | Pod SOP, intra-pod workflow |
 | Member | Rig spec author | Individual member overrides | Member-specific instructions, cwd-specific context |
-| Operator | OpenRig system | System-injected runtime content | `openrig-start.md`, context collector |
+| Operator | OpenRig system | System-injected runtime content | `openrig-start.md` (optional delivery); on a fresh start, `openrig-onboarding-01.md` and `-02.md` unless `onboarding.default_pack.enabled` is false |
+
+After the files, OpenRig sends a session-identity message (rig, pod, member, logical ID) once the seat is ready.
 
 ### Practical Guidance
 
-**Most rigs only need three layers:** agent (role.md), rig (culture), and operator (openrig-start). Start simple. Add pod and member layers only when agents in the same pod need different startup content.
+**Most rigs only need three layers:** agent (role.md), culture, and the built-in operator layer. Start simple. Add pod and member layers only when agents in the same pod need different startup content.
 
-**The culture layer is high-value and often skipped.** A rig without a `CULTURE.md` relies on agents to guess how the team communicates and coordinates. Write one. Even a short culture file dramatically improves team coherence.
+**The rig's own culture file is high-value and often skipped.** Every seat gets OpenRig's default culture, but that says nothing about how this team communicates and coordinates. Write a `CULTURE.md`. Even a short one dramatically improves team coherence.
 
 **Member-level startup is for exceptions, not the rule.** If every member has its own startup block, the layering model is being used as a configuration dump. Refactor shared content up to the pod or rig level.
 
@@ -153,8 +188,8 @@ Startup content is merged additively through layers. Each layer adds to what the
 
 | Delivery Hint | When | How | Use For |
 |---------------|------|-----|---------|
-| `auto` | Before harness boot | System chooses | Default — let OpenRig decide |
-| `guidance_merge` | Before harness boot | Merged into `CLAUDE.md` / `AGENTS.md` as a managed block | Role guidance, culture, project context |
+| `auto` | Depends on the file | Resolved per file: a `SKILL.md` (or content starting `# SKILL`) is `skill_install`, any other `.md` is `guidance_merge`, and any other file is `send_text` | Default — let OpenRig decide |
+| `guidance_merge` | Before harness boot | Merged as a managed block into `AGENTS.md` (Codex, Pi) or `CLAUDE.md` (Claude; `CLAUDE.local.md` with the rig's `managed_blocks: { claude-code: CLAUDE.local.md }`) | Role guidance, culture, project context |
 | `skill_install` | Before harness boot | Copied to runtime's skill directory | Skills |
 | `send_text` | After harness is ready | Sent as text to agent's terminal via tmux | Boot-time grounding, identity hints, instructions to read skills |
 
@@ -167,11 +202,46 @@ Files delivered via `send_text` happen AFTER the harness is ready. The agent rec
 - Instructions to load skills (the files are already projected, the message tells the agent to read them)
 - Context that should feel like an operator briefing, not pre-loaded content
 
+On a fresh launch the first message is one turn: the session identity, the first `send_text` file and, when a startup
+proof is selected, its challenge (below).
+
+A file's `required` field defaults to `true`: a required file that can't be delivered fails startup, and an optional
+one is dropped without a message.
+
+### Readiness, startup proof and failure
+
+**Readiness.** After launch OpenRig polls the pane until the harness is interactive (backing off 1, 2, 4, 8 and 16
+seconds), for up to 30 seconds by default. Change the window with
+`rig config set runtime.readiness_timeout_seconds <1-600>` (or `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`); it
+applies to the next launch. A recognized prompt (the attention codes above) ends the wait at once as
+`attention_required`. A timeout ends startup as `failed` ("Readiness timeout after Ns — harness did not become
+interactive"), and the post-launch files aren't sent.
+
+**Claude submission check.** For each startup message to a Claude seat, OpenRig makes a bounded check that the prompt
+was submitted. When the capture can't tell, it records the submission as unverified and carries on. When it sees the
+same prompt still sitting in the input, it presses Enter once more; if it's still there, it warns "Startup prompt still
+staged in <session>; press Enter in that pane." The seat can still end `ready` with its submission `unverified` or
+`staged`, so `ready` doesn't prove the prompt was submitted. After all files and actions are delivered, readiness is
+checked once more, so a prompt that appears by then gives `attention_required`.
+
+**Startup proof.** A `startup_proof` action selects `authenticated` or `none` (the default is none; the last applicable
+one wins, and it needs `idempotent: true`). With `authenticated`, a fresh launch of an agent seat includes a challenge,
+and the seat answers it with `rig startup-proof submit --challenge-id <id> --answer <answer>`. `rig ps --nodes --full`
+shows the result in the ORIENTED column: `verified`, `missing`, `rejected` or `n-a`. A missing proof doesn't block startup.
+
+**After a failure.** Delivery, launch and action failures, and readiness timeouts, give `failed`. Every 30 seconds the
+context monitor marks a `failed` or `attention_required` seat `ready` once its pane reads ready, unless fresh context
+is still pending for `rig seat continue`. A seat that timed out can therefore read `ready` without having received its
+post-launch files. If it needs them, first look at what that occupant has done; then
+`rig seat launch <seat> --fresh --reason <text>` starts a blank conversation for the seat. If the occupant is still
+live, the command refuses with `session_live` unless you also pass `--stop`, which replaces that occupant deliberately.
+
 ### The `applies_on` Field
 
 Each startup file and action specifies when it applies:
-- `fresh_start` — delivered on first launch only
-- `restore` — delivered on restore from snapshot
+- `fresh_start` — delivered when a new conversation starts: the first launch, `rig seat launch --fresh`,
+  `rig seat continue`, and seats restored with `--fresh`
+- `restore` — delivered when a seat is restored, including a restore whose resume falls back to a fresh conversation
 - Default: `[fresh_start, restore]` (both)
 
 Use this to avoid re-sending context that the agent already has from its resumed conversation. For example, a one-time project briefing might only apply on `fresh_start`, while identity grounding should apply on both.
@@ -184,15 +254,8 @@ The AgentSpec and RigSpec allow declaring deterministic environment configuratio
 
 ### What the Spec Supports
 
-**Hooks** (in `resources.hooks`):
-```yaml
-resources:
-  hooks:
-    - id: pre-commit
-      path: hooks/pre-commit.sh
-      runtimes: [claude-code]
-```
-Hooks are scripts copied to the agent's workspace. They can be git hooks, automation scripts, or environment setup.
+**Hooks** ship inside plugins: declare the plugin under `resources.plugins[]`. AgentSpec validation refuses
+`resources.hooks`.
 
 **Runtime resources** (in `resources.runtime_resources`):
 ```yaml
@@ -214,23 +277,26 @@ startup:
       phase: after_ready
       idempotent: true
 ```
-Commands sent to the agent's terminal after it's ready. Can install MCPs, run setup commands, etc.
+Each value is typed into the harness's input and submitted, so it is a prompt or a slash command, not a shell command.
+Types are `send_text`, `slash_command` and `startup_proof` (see "Startup proof" above); `shell` is refused.
+`idempotent` is required, and an action that isn't idempotent must not list `restore` in `applies_on`. Both phases
+run after the harness is ready: `after_files` (the default) after the post-launch files, then `after_ready`.
 
-### Current Support Matrix (OpenRig 0.1.x)
+### Current Support Matrix
 
 | Capability | Status | Notes |
 |------------|--------|-------|
 | Guidance file projection (`guidance_merge`) | **Supported** | Reliable. Primary delivery mechanism. |
 | Skill projection (`skill_install`) | **Supported** | Reliable. Skills are copied to workspace. |
 | `send_text` delivery after ready | **Supported** | Reliable. Requires harness to be ready. |
-| Hook projection | **Experimental** | Files are copied but execution/integration varies by runtime. |
+| Hooks | **Through plugins** | Declare a plugin under `resources.plugins[]`; `resources.hooks` is refused. |
 | Runtime resource projection | **Supported for recognized fragments** | `claude_settings_fragment`, `claude_mcp_fragment`, and `codex_config_fragment` are applied to provider config. Unknown types are copied to runtime extension directories. |
-| Permission configuration | **Native settings plus managed launch flags** | OpenRig launches Claude with `acceptEdits` and Codex with `workspace-write` unless an explicit supported selection changes them. It does not add a global Claude `Bash(rig:*)` allowance. Use [the first-user permission guide](getting-started.md#opt-in-permissive-operation) for opt-in and custom choices. |
-| MCP installation | **Experimental** | Claude Code: `/mcp` interactive command or `claude mcp add` from CLI. Can also be described in startup files for agent self-configuration. Reliability depends on runtime TUI state. |
+| Permission configuration | **Native settings plus managed launch flags** | OpenRig launches Claude with `acceptEdits` and Codex with `workspace-write` unless an explicit supported selection changes them; the `kernel` rig's seats get a wider operational default ([rig spec, "At launch"](rig-spec.md)). It does not add a global Claude `Bash(rig:*)` allowance. Use [the first-user permission guide](getting-started.md#opt-in-permissive-operation) for opt-in and custom choices. |
+| MCP installation | **Supported for Claude fragments** | A selected `claude_mcp_fragment` is merged into the project's `.mcp.json`. Claude asks to approve new servers found there; that prompt stops startup as `mcp_gate` until someone answers it and runs `rig seat continue`. Otherwise use `/mcp` or `claude mcp add`, or describe the servers in startup files for the agent to configure. |
 | System dependency installation | **Not deterministic** | Describe in startup files; agent handles via shell commands. |
 | Recurring tasks / wake timers | **Runtime-dependent** | Claude Code supports recurring tasks via the `/loop` command. Codex does not have a confirmed equivalent. Orchestrators should include `/loop` instructions in startup for Claude Code agents. |
 
-### The v0.2.0 Approach: Describe, Then Let the Agent Handle It
+### The Approach: Describe, Then Let the Agent Handle It
 
 For anything beyond `guidance_merge`, `skill_install`, and `send_text`, the recommended approach is:
 
@@ -329,6 +395,13 @@ remain shared.
   `CODEX_HOME`, read its login and fetch managed policy, as a Codex start does.
 - Can self-install dependencies from instructions but timer/recurring behavior is not reliably available
 
+**Pi and OMP:**
+- Read `AGENTS.md` in the working directory; guidance is merged there, added to Pi's own system prompt
+- Selected skills are projected into the seat's own agent directory under OpenRig's state, not into a shared
+  workspace folder
+
+**Terminal seats** (`builtin:terminal`) get no agent or profile layers and no startup proof.
+
 When authoring startup content, note which instructions are runtime-specific. For example, an orchestrator that needs a monitoring loop should include instructions like: "If running Claude Code, use `/loop 3m` to periodically check rig health. If running Codex, check rig health at the start of each task cycle instead."
 
 ---
@@ -399,7 +472,7 @@ This prompts the agent to actually invoke the skills, not just have them as pass
 
 After identity recovery, verify:
 1. `rig ps --nodes` shows your rig running (scoped to your session's rig by default; outside a managed session name it explicitly: `rig ps --nodes --rig <name>`)
-2. `rig env status` shows services healthy (if applicable)
+2. `rig env status <rig>` shows services healthy (if applicable)
 3. Your working directory is correct
 4. Required tools are available (node, npm, git, etc.)
 

package/daemon/docs/reference/agent-state-taxonomy.md

@@ -1,8 +1,11 @@
 # Agent state taxonomy
 
-The formal state language every OpenRig surface renders from — TUI, `rig ps`, the node
-inventory, and any future consumer. One oracle computes it; surfaces render it; no
-surface keeps a private vocabulary.
+The formal activity language OpenRig's surfaces render from — the TUI and the `rig ps`
+ACTIVITY column. One oracle computes it; surfaces render it. Two exceptions remain: the web
+UI's graph node still derives its own running/needs-input/idle/unknown from the legacy
+`agentActivity`, and `rig ps --active` / `--filter agentActivity.state` filter on that legacy
+field. Startup, orientation, restore and attention states are separate vocabularies, listed
+under "Other state on the same surfaces" below.
 
 **This document is the canonical text for the shipped taxonomy** and adds the
 engineering reconciliation; it never forks a second vocabulary. Its typed source of
@@ -16,6 +19,12 @@ truth is `packages/daemon/src/domain/activity-taxonomy.ts`.
 | activity | `working` · `idle-at-prompt` · `unknown` (+ needs-input as count+reason, below) | what a present agent is doing |
 | resumability | `live` · `resumable` · `context-walled` | what a non-present agent can come back as |
 
+Only the activity axis is served today. The session and resumability values are declared in
+`activity-taxonomy.ts` but no surface reads them: `rig ps --nodes --full` shows the raw session
+STATUS, both node views show a LIFECYCLE of `running`, `detached`, `recoverable` or `attention_required` (`run`, `det`, `rec`,
+`att`), and node inventory serves `occupantLifecycle` (`active`, `retiring`, `retired`,
+`context_walled`, `compacted`, `crashed`, `unknown`).
+
 The axes never blend. Reachability is strict; revival optimism is a different field
 (omnigent's strict-liveness split). `unknown` is a first-class honest value — the oracle
 saying it cannot tell. Unknown beats a confident wrong answer.
@@ -35,15 +44,18 @@ collision in both codebases.
 ## Derived diagnoses — computed at read time, never stored
 
 - **PARKED** — the disease: `(activity = idle-at-prompt OR needs-input pending) ×
-  (open obligations exist)`. A dropped baton or an unanswered block. Queryable at rig and
-  seat level; the join lives in the parked query surface, never inside the oracle
-  (the oracle's non-inference contract: it never reads queue state).
+  (open obligations OR unhealthy HELD rows)`. A dropped baton or an unanswered block. When
+  activity is `unknown` the verdict is `indeterminate`, never parked or not-parked. Queryable
+  at rig and seat level with `rig parked [seat] [--rig <name>] [--json]`; the join lives in the
+  parked query, never inside the oracle (the oracle's non-inference contract: it never reads
+  queue state).
 - **HELD** — the deliberate counterpart: a queue-level hold with a named owner and an
   armed wake (`rig view show held`). Stopping on purpose is HELD; stopping by accident is
-  PARKED. A HELD row is **not** parked.
+  PARKED. A HELD row is healthy only while its wake is live, and not fired-but-unconsumed
+  unless the stuck sweep owns its recovery; an unhealthy HELD row on a stopped seat makes
+  the seat parked.
 - **DONE-UNSEEN** — finished work whose completion nobody consumed (herdr derives it as
-  idle ∧ unseen). Declared here and computed at read time from claims/transitions,
-  outside the activity oracle, preserving its non-inference boundary.
+  idle ∧ unseen). Declared as a concept only; no surface computes it yet.
 
 ## Reconciliation with prior art
 
@@ -65,8 +77,10 @@ time-bounded evidence. Rungs, top down, with each rung's retirement condition:
 - **r3 — Claude `sessions/<pid>.json` self-report** (busy/shell/idle/waiting, since
   v2.1.139): standing, above hooks for working/idle. Undocumented internal — unreadable
   means fall down the ladder, never error.
-- **r2 — lifecycle hooks** (Claude Stop/StopFailure; Codex UserPromptSubmit/Stop/
-  PermissionRequest): standing. Exactly-once turn boundaries; SubagentStop filtered (it
+- **r2 — lifecycle hooks** (Claude SessionStart/UserPromptSubmit/Stop/Notification;
+  Codex SessionStart/UserPromptSubmit/Stop/PermissionRequest): standing for Claude; Codex's
+  hook rung starts at trial and is promoted after 50 agreeing observations over at least an
+  hour. Exactly-once turn boundaries; SubagentStop filtered (it
   can fire post-turn and must never revive an idle seat). Hook-rung authority is
   TIME-BOUNDED: the hook rung is the only rung that does not self-date its evidence, so
   persistent cross-rung contradiction degrades it to identity-only, visibly, with a
@@ -76,8 +90,9 @@ time-bounded evidence. Rungs, top down, with each rung's retirement condition:
 - **r1 — window-activity sampling** (today's oracle): the fallback tier. Retires
   PER-HARNESS when that harness's hook rung earns trust through a measured agreement
   window in production — never by fixture pass alone (symmetric admission: a fixture
-  pass admits a rung to TRIAL; production agreement promotes it; identity-only until
-  promoted).
+  pass admits a rung to TRIAL, where it is measured but not consulted; production agreement
+  promotes it). Undeclared and partial-coverage rungs are identity-only, which is also where
+  a degraded rung goes.
 
 Partial-coverage honesty: a source with partial lifecycle coverage gets identity-only
 trust. The ladder is also the migration path — new oracles slot in above existing
@@ -88,6 +103,22 @@ generation swap is its own visible event — never an activity transition — an
 rung-inventory re-declaration: a successor never inherits its predecessor's rung
 authority (hooks live in occupant config while the pane is seat-persistent).
 
+## Other state on the same surfaces
+
+These are separate vocabularies, not activity values. `rig ps --nodes --full` shows them in
+its STARTUP, ORIENTED, LIFECYCLE and RESTORE columns (the default compact view shows only
+LIFECYCLE); see the
+[startup guide](agent-startup-guide.md) for how each arises.
+
+- **Startup status:** `pending`, `ready`, `attention_required`, `failed`. `ready` means
+  startup finished, never that the seat is oriented, and a seat isn't marked `ready` while
+  its startup context is still pending for `rig seat continue`.
+- **Oriented:** `verified`, `missing`, `rejected`, `n-a`, from the startup proof.
+- **Attention codes:** `trust_gate`, `hook_trust_gate`, `update_gate`, `login_required`,
+  `mcp_gate`, `bypass_consent_gate`, `codex_auth_refusal`, `codex_client_incompatible`.
+- **Restore outcome:** `resumed`, `fresh-primed`, `awaiting-decision`, `attention_required`,
+  `failed` (plus `rebuilt`, `operator_recovered` and the legacy `fresh`).
+
 ## Rejected oracles — dated receipts (2026-08-26), so nobody re-derives them expensively
 
 - **transcript-quiescence as an activity oracle: REJECTED.** omnigent's 1-second version

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

@@ -12,10 +12,9 @@ comes from a web page, only when that page is the OpenRig UI or a page you allow
   its own Tailscale name (for example `my-machine.your-tailnet.ts.net`, or the short `my-machine`).
   The daemon learns its own Tailscale name automatically from Tailscale on this machine.
 - The web UI, when it is turned on (`rig config set ui.enabled true`, then restart the daemon) and
-  opened at the daemon's own address and port. To open it at a non-loopback name or address, such
-  as its Tailscale name, also list that page's exact origin in `OPENRIG_ALLOWED_ORIGINS` (for
-  example `http://my-machine.your-tailnet.ts.net:7433`), then restart the daemon. Without it, the
-  UI's terminal is refused there, and at a non-loopback IPv6 address its API requests are too.
+  opened over `http` on the daemon's own port at any address the daemon accepts, including its
+  Tailscale name. A UI page served any other way, such as over `https` through your own domain,
+  also needs its exact origin in `OPENRIG_ALLOWED_ORIGINS`, then a daemon restart.
 
 ### When you see a refusal
 
@@ -35,14 +34,16 @@ The daemon answers `403` with a sentence that says what to do. There are two kin
 
 `OPENRIG_ALLOWED_HOSTS` lists names you use to reach the daemon. `OPENRIG_ALLOWED_ORIGINS` lists
 web pages allowed to call it. They are separate: a UI served through your own domain usually needs
-both. Pages on other origins cannot read the refusal; the message is for you, the CLI and agents.
+both. Separate several entries with commas. Pages on other origins cannot read the refusal; the
+message is for you, the CLI and agents.
 
 ### Limits
 
 - If you rename the machine in Tailscale, the daemon keeps accepting its previous name until it
   restarts or until it next looks its name up after seeing an unrecognized one.
-- If the daemon cannot reach Tailscale's resolver, its Tailscale name is refused until a later
-  lookup succeeds. `localhost` and IP addresses keep working.
+- If the daemon has not reached Tailscale's resolver since it started, its Tailscale name is
+  refused until a lookup succeeds. A later failed lookup keeps the name it already learned.
+  `localhost` and IP addresses keep working.
 - This protects against unknown web pages and unknown names. It is not complete browser isolation:
   a page on another site can still cause a simple read request to an address the daemon accepts,
   although it cannot read the answer. Keep the daemon on loopback or your tailnet.

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

@@ -0,0 +1,207 @@
+# Bundle formats (v1)
+
+The shared data formats for sharing rig bundles: the configurations a bundle offers, the before-install view of what it
+will do, run records and the public status file, and registry entries. The schemas are in [`schemas/`](schemas/), with
+fixtures that pass and fail them in [`schemas/fixtures/`](schemas/fixtures/). Tools outside this repository read them
+at a pinned commit.
+
+**A v1 format only grows:** new optional properties may appear, and consumers ignore properties they don't know. Any
+other change is a v2. The schemas are open to new properties, with three closed on purpose: the package digest (an exact
+value), a run record's subject (a harness check can never carry a team's identity), and the public status file, where
+nothing outside the schema may appear, so a private field can't leak in. A new property in a closed part is a v2. The
+status schema also rejects labels that contradict their evidence: a tested label needs records and a package, tested
+with help needs its count, tested can't carry a count above zero, and an unreadable listing carries only Status
+unavailable.
+
+## Three identities, kept apart
+
+| What | Name | Defined by |
+|---|---|---|
+| What someone chose | configuration ID | the mapping of every seat to a runtime |
+| What was packaged | package digest | the built archive's files |
+| What actually ran | execution binding | a run record (resolved resources, settings, environment, unknowns) |
+
+None stands in for another. A package digest doesn't describe what ran, and a configuration ID doesn't describe what was
+packaged.
+
+### Source identity
+
+A bundle on GitHub is named by `repository` (`https://github.com/<owner>/<repo>`, no credentials), `folder` (the
+repo-relative path of the folder holding `rig.yaml`, or `.` for the repository root) and `resolvedCommit` (40 lowercase
+hex).
+- `requestedRef` (the branch, tag or commit someone gave, or `HEAD` for a link without `/tree/…`) and `canonicalUrl`
+  (`…/tree/<resolvedCommit>/<folder>`, with each folder segment percent-encoded and no folder part for the root)
+  explain it, and aren't part of it.
+- A built bundle records its source in its manifest's provenance, which is outside the package digest.
+
+### Configuration ID
+
+Every member's `pod.member=runtime`, sorted by `pod.member` in UTF-16 code-unit order, joined with `,`. There's no
+whitespace, and runtimes are spelled as in `rig.yaml`. For example:
+
+```text
+build.impl=claude-code,build.lead=claude-code,check.qa=codex,check.review=codex
+```
+
+Preset names such as `recommended` or `all-claude` are aliases shown beside the ID, never part of it.
+
+### Package digest
+
+`{ algorithm: "sha256", value, coverage: "openrig.package-digest/v1" }`:
+- `value` is SHA-256 over UTF-8 lines `<quoted path>\t<sha256>\n`, one for each entry of the built archive's
+  `integrity.files`, sorted by path in UTF-16 code-unit order;
+- `<quoted path>` is the path as a JSON string, exactly as JavaScript's `JSON.stringify(path)` writes it, so a tab or
+  newline in a file name can't make two different file lists hash the same. In words: wrapped in `"`; `"` and `\`
+  escaped with a backslash; U+0008, U+0009, U+000A, U+000C and U+000D written `\b`, `\t`, `\n`, `\f` and `\r`; any
+  other character below U+0020, and any lone surrogate, written `\uXXXX` in lowercase hex; everything else as itself;
+- it's the same when the same folder is rebuilt by the same OpenRig, while the archive's own hash changes with every
+  build (`createdAt`).
+
+**Coverage, shown wherever the digest is:** the bytes of every packaged file. It doesn't cover:
+- `bundle.yaml`, so no manifest field, provenance or `createdAt`;
+- the names the integrity walk skips (`.DS_Store`, `Thumbs.db`, `.gitkeep`);
+- file modes;
+- anything resolved on the installing machine at launch, for example an `openrig-home:` plugin, catalog skills, or a
+  model or effort nothing declares.
+
+**A build result** carries `source` (`null` unless the bundle was built from a GitHub link), `configurationId`,
+`packageDigest`, `archiveHash` and `assembler`. `rig bundle inspect` reports the same fields for an archive, and any the
+archive doesn't state are `null`. `assembler` is `{ openrigVersion }`: the format also allows a `commit`, which this
+OpenRig doesn't write. `configurationId()` and `packageDigest()` are exported from `@openrig/daemon/bundle-identity`.
+Shared test vectors are in `schemas/fixtures/identity-vectors.json`.
+
+## The formats
+
+| Format | Schema | Lives | Written by |
+|---|---|---|---|
+| Declared configurations | `bundle-configurations.v1` | `configurations.yaml` beside `rig.yaml` | the bundle's author |
+| Before-install view | `bundle-behaviour.v1` (`openrig.bundle-behaviour/v1`) | the registry, one file per configuration and assembler version; never inside the archive | the daemon's inspect: `rig bundle inspect`, under `behaviour` with `--json` |
+| Run record | `run-record.v1` | beside its receipt, private | Fleet, Dev QA, and maintainers for community reports |
+| Public status | `bundle-status.v1` | `openrig-world` status, generated | the status generator only |
+| Registry entry | `registry-entry.v1` | `openrig-world/registry/<slug>.yaml` | maintainers, through review |
+
+### Declared configurations
+
+`seats` gives a `pod.member` the runtimes it may use, and the profile each runtime uses. A member it doesn't list keeps
+the runtime `rig.yaml` gives it. `presets` names full mappings, and `recommended` names one of them, which must be
+`rig.yaml` as written. `rig bundle create`, `rig bundle configurations` and `rig bundle check` refuse a file that breaks
+these rules.
+
+`--preset` and `--seat` choose a configuration (see the [rig bundle reference](rig-bundle.md)). Any mix of each seat's
+declared runtimes can be built, not only the presets; a runtime a seat doesn't declare is refused, and nothing is built.
+Without either flag, create builds `rig.yaml` as written. The built archive's manifest records
+`configuration: { id, preset }` outside the package digest; `preset` is there only when `--preset` or `--seat` chose a
+mapping that matches a declared preset.
+
+### Before-install view
+
+It's derived from the archive's files alone. Nothing is launched, probed or fetched. It's a view, never a gate, and
+carries no tested status.
+- **`identity`:** source, configuration ID, package digest, the archive's assembler, the generator that made the view,
+  stated compatibility, stated provenance (not verified), and integrity (self-consistency, not authorship). A source,
+  configuration ID, package digest or assembler the archive doesn't state is `null`; unstated compatibility and
+  provenance are empty objects. None of it is filled from the inspecting OpenRig.
+- **`team`, `posture`, `toldFiles`, `alsoRuns`, `writes`, `outsideAddresses`, `needs` and `unknownBeforeLaunch`**, in
+  that order. Facts cite the archive file they come from (`sourceRefs`), except `team` entries and the bundle-wide
+  unknowns. `toldFiles` and `alsoRuns` also say how each resolves: `archive`, `host_at_launch` or `unresolved`.
+  - Posture separates what the archive declares from the product's default. Its effect on the host is `unknown`,
+    because host settings decide it.
+    Optional `posture[].permissionPrompts` is `off` for declared `full_bypass` (including rig- or member-level
+    `builtin:yolo`) on any runtime; for Claude/Codex, `on` for a declared flag-surface floor policy or `default` when
+    no policy is declared (prompts on unless the installing machine's settings turn them off); for Codex, `on` for
+    declared `auto`. Omit it for Claude under auto (naming auto mode in `selection`), config-surface policies
+    (`builtin:locked`, `builtin:standard`, `builtin:open` or an archived `surface: config` policy), host-resolved
+    Codex profiles, `permission_policy: none`, a policy the archive can't resolve, and every runtime other than Claude
+    and Codex (Pi, terminal) except declared full bypass. `selection` names the declared policy.
+    An absent field means not stated, never `on`. For `off`, Claude
+    bypasses permissions, Codex runs with full access and never asks, and Pi gets full resource trust (`--approve`,
+    not a permission mode). These are archive facts; `nativeEffect` remains `unknown`.
+    Optional `posture[].firstRunWarnings.claudeBypass: "harness_asks_once"` names the first-run bypass warning for a
+    declared full-bypass Claude seat, conditional on whether the harness has remembered acceptance.
+    `posture[].nonInterruptive: "available"` says a full-bypass Claude/Codex seat can use
+    [non-interruptive launch flags](non-interruptive-mode.md). It does not select the option, read host acceptance
+    state or prove a prompt-free launch. Both fields are omitted where inapplicable or unresolved; older v1 views
+    remain valid without them. Pi has no additional warning-suppression flag. `nativeEffect` stays `unknown`.
+  - An empty list means none are known. Something unknown goes in `unknownBeforeLaunch`.
+  - Per-seat facts carry `seat` (`pod.member`) and human output labels them with that identity. It's required on
+    `team` and `posture`. Elsewhere it's optional: bundle-wide facts (services, library and project writes, setup and
+    version needs) omit it, and older generators may not have stated it.
+- **`not_generated`:** a combination without a generated view, or an archive the generator can't describe: schema 1, no
+  readable pod-aware rig spec, a member missing its pod, id or agent reference, a runtime that depends on an AgentSpec
+  the archive can't read, or an error while reading. It carries a reason and the local command that shows it, and no
+  sections.
+
+### Declared setup preconditions
+
+The author's `bundle.yaml`, beside `rig.yaml`, may declare setup that the user must do before installing:
+
+```yaml
+preconditions:
+  - name: Run inside an OpenRig source clone with dependencies installed and packages built.
+    commands:
+      - git clone https://github.com/mvschwarz/openrig.git
+      - cd openrig
+      - npm ci
+      - npm run build
+  - name: Sign in to the selected coding runtimes before starting the team.
+```
+
+Local-folder creation and GitHub-link imports carry these declarations into the archive manifest. A generated
+before-install view lists each as `needs[]` with `kind: precondition`, the author's `name`, optional ordered `commands`,
+`status: not_checked`, and a `sourceRefs` entry naming `bundle.yaml` and `preconditions[index]`. Inspect, plan and apply
+previews show the same declaration. A legacy schema-1 archive retains it in the manifest, but its view remains
+`not_generated`. Missing preconditions mean none were declared, not that no setup is needed.
+
+Each command is one plain command line, without shell operators (`;`, `&&`, pipes, command substitution, backticks or
+redirection). Run them in order in **one shell**, then run the install command in that same shell: it inherits the
+working directory left by the setup commands. There is no separate `workdir` field. Commands are untrusted author data;
+a site building a copyable block must validate every line and bound the number of entries, omitting all setup lines
+if any fails its plain-command rule. OpenRig displays these declarations; it does not execute them, verify that setup
+was done, or add a prerequisite gate. The archive hash covers the manifest; `packageDigest` excludes `bundle.yaml`
+and therefore does not cover these declarations.
+
+At creation, malformed preconditions produce a warning and the whole block is omitted; other author-field validation
+is unchanged. Shell operators in otherwise valid command lines produce a warning, but the declarations are retained
+as data. An already-built archive with malformed preconditions reports them as unknown before launch.
+
+### Run records and status
+
+**A run record's subject** is either a team (source, configuration ID, package digest, assembler) or a harness check (a
+runtime). A harness check never upgrades a team label.
+
+**A run record's `environment.platform` and `arch`** are Node's `process.platform` (`linux`, `darwin` or `win32`) and
+`process.arch` (`x64` or `arm64`): the values a status platform key can carry, so every valid record can be labelled.
+
+**Records are private.** Only `outcome.publicNote` (a short public cause) reaches the status file.
+
+**Relations:** `supersedes`, `withdraws` and `resolves`. Reusing earlier evidence for a changed package is a reviewer's
+decision, recorded in the registry entry's `evidenceReuse`.
+
+**The status file** is generated from records by rule `openrig.status-rule/v1`:
+- **Labels:** `known_problem`, `tested`, `tested_with_help`, `partly_tested`, `not_tested` and `status_unavailable`.
+  They're shown as Known problem, Tested by OpenRig, Tested with help (N), Partly tested, Not tested by OpenRig
+  and Status unavailable.
+- **A label belongs to one configuration ID.** No configuration is ever shown another configuration's label.
+- **Empty `platforms`** means Not tested by OpenRig. So does a custom configuration, one the listing doesn't offer.
+- **Status unavailable is only for a listed configuration** whose records can't be read, or that's missing from the
+  status file; never Not tested by OpenRig. A listing whose records can't be read is `status_unavailable` as a whole.
+- **Platform keys** are `<os>-<arch>` (`linux`, `darwin` or `win32`; `x64` or `arm64`).
+- **`tested` means no help was needed:** it can't carry an assistance count above zero.
+- **An assist** is one action a person or the test runner took to get past a problem during the run, such as restarting a seat or re-running a command; following the bundle's own documented steps doesn't count.
+- **The file holds no private paths, host names, row IDs, account names or receipt text,** and regenerating it gives
+  identical bytes.
+- **`bodyDigest`** is SHA-256, lowercase hex, over the RFC 8785 (JCS) canonical JSON, as UTF-8, of an object holding
+  every other top-level field. The site import recomputes it and rejects a hand-edited file. `harnessChecks` has its own
+  `state`, so an unreadable harness-check record reads Status unavailable too.
+
+### Registry entries
+
+Each entry records:
+- the source at its reviewed commit;
+- each offered configuration with its package digest, assembler and behaviour-view file;
+- optional `evidenceReuse`;
+- the review date, and `listed` or `withdrawn` (with `withdrawnOn`).
+
+v1 has no author field: a listing shows the owner of `source.repository`.
+
+A listing shows "Reviewed for listing on `<date>` at commit `<short>`. Review is not a security audit."