@openrig/cli 0.6.4 → 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:
 
@@ -250,11 +316,14 @@ OpenRig performs best-effort deterministic runtime configuration for managed ses
   installations may retain one; existing user settings are not removed.
 - Claude global state: `~/.claude.json`
   Purpose: pre-trust managed workspaces and mark onboarding complete for fresh managed sessions.
+  Explicit permission modes use the launch-selected `HOME/.claude.json`, or
+  `<CLAUDE_CONFIG_DIR>/.claude.json` when that variable is set. Classic startup
+  retains the daemon-home path.
 - Claude project-local config: `.claude/settings.local.json`
   Purpose: apply context collector/activity hooks and selected `claude_settings_fragment` resources inside the project without committing them to git.
 - Claude project-local MCP config: `.mcp.json`
   Purpose: apply selected `claude_mcp_fragment` resources for Claude in that project.
-- Codex global config: `~/.codex/config.toml`
+- Codex global config: `$CODEX_HOME/config.toml`, or `~/.codex/config.toml` when unset
   Purpose: pre-trust managed workspaces and apply selected `codex_config_fragment` resources. Codex currently has no equivalent project-local MCP config path for global profile settings.
 
 Two important caveats:
@@ -266,6 +335,39 @@ can affect native configuration, but OpenRig's launch flags can override those
 values. Recording a config-surface `permission_policy` is not proof that its
 rules were translated or applied. See [permission precedence and limits](getting-started.md#custom-settings-and-precedence).
 
+### Separate Codex homes for separate installations
+
+Set an **absolute `CODEX_HOME` in the environment that starts the daemon** when
+you want a separate Codex configuration and state root. OpenRig uses that root
+for its startup hook setup/removal and trust records, feature flag, workspace
+trust and selected config fragments. Startup can write those files even when
+the daemon has no seats.
+
+The explicit selection also applies to future managed Codex fresh, resume and
+fork launches, their capability/profile/configuration probes, native thread and
+context reads, and plugin-cache discovery. Launch commands reassert it after
+pane shell startup, so an rc file cannot silently switch that launch to another
+Codex home. Executable and PATH selection stay the same. Existing running
+sessions are not moved or restarted; a thread in another home is not searched
+as a fallback for an explicitly selected home.
+
+**With `CODEX_HOME` unset, a second install still shares `~/.codex`.** Setting only
+`OPENRIG_HOME` separates OpenRig state, not provider configuration. The default
+launch behavior is unchanged, including existing pane-shell overrides.
+
+OpenRig does not copy or migrate authentication, history, rules, trust or
+settings into the selected home. A separate file-backed home needs its intended
+authentication provisioned if absent; OS credential stores and other config
+layers can behave differently, so a new login is not universally required.
+Explicit Codex auth commands resolve their **caller's** `CODEX_HOME`, otherwise
+`$HOME/.codex`; contacting a daemon with `OPENRIG_URL` does not retarget auth
+save/switch/registry writes to that daemon's selection. Set the intended root
+on those commands as well.
+
+This separates provider files, not OS users or accounts. Project-local resources
+still use the selected project directory; shared project and system settings
+remain shared.
+
 ### Runtime Differences
 
 **Claude Code:**
@@ -283,8 +385,23 @@ rules were translated or applied. See [permission precedence and limits](getting
 - Approval policy and sandbox access are separate controls. OpenRig's default
   `-s workspace-write` selects the sandbox; it does not force `-a`. A member's
   `codex_config_profile` selects native `-p`, distinct from the AgentSpec `profile`.
+- On that plain `-s workspace-write` launch (fresh, resume, fork or restore), a
+  short-lived `codex app-server` first reads Codex's own configuration with the
+  seat's executable, home and working directory. OpenRig adds
+  `-c sandbox_workspace_write.network_access=true` only when no configuration
+  layer sets network access and no managed requirement could restrict it. A
+  timeout, error or unrecognized answer adds nothing. Named profiles and full
+  bypass are not read. The read may write Codex's own state files in
+  `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."
 
 ---
@@ -301,6 +418,41 @@ profile → uses.skills: [openrig-user]
 ```
 This is the minimum effective startup. The agent knows who it is, how the team works, and how to use the rig.
 
+For seats sharing a working directory, keep each role in its own AgentSpec startup entry:
+
+```yaml
+startup:
+  files:
+    - path: guidance/role.md
+      orientation: role
+      delivery_hint: send_text
+      required: true
+```
+
+`rig queue whoami --json` reports only the calling seat's explicitly marked role
+bindings, independently of its current work. The `role.state` is `no-record`,
+`not-declared`, `missing`, `present`, or `unknown` when identity, storage or the
+observation is unavailable. Files retain their original `path`, `absolutePath`
+and `ownerRoot` plus the currently resolved `resolvedPath` and
+`resolvedOwnerRoot`. Built-in packaged paths follow the running installation;
+existing development-checkout paths stay where they were recorded.
+
+`recordedAt` is the startup-context record write/attempt, which happens before
+launch succeeds. Exact resume can retain an older record. `present` means the
+resolved file currently exists, not that its bytes still match the spec or that
+the agent read it. Unmarked startup files and startup actions are not exposed.
+
+Refocus includes the role path and a re-read reminder with topology or both trees,
+even if the trace fails. Work-only mode omits it; disabling refocus still disables
+the entire hook. Custom refocus prose keeps its existing precedence. The hook
+reuses its work lookup, or makes one bounded lookup when the work node is explicit;
+a failed or skipped lookup reports `unknown`.
+
+The shipped kernel seats no longer project their role into shared guidance.
+Existing user files and legacy role blocks are left intact; this is not a cleanup
+of already-installed shared blocks. General user-authored guidance projection is
+unchanged.
+
 **Separate project context from role**
 
 Don't put project documentation inside the role guidance. The role is about the agent's function; project context is about what the agent is working on. Use rig-level or pod-level startup files for project context.
@@ -320,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.)
 
@@ -356,7 +508,7 @@ If your rig REQUIRES a hook to function and the hook installation fails silently
 When creating a new agent's startup experience:
 
 - [ ] Write a `guidance/role.md` — who is this agent?
-- [ ] Reference it in the agent spec's `resources.guidance` AND `startup.files`
+- [ ] Reference it in `startup.files` with `orientation: role` and `delivery_hint: send_text`. Avoid projecting distinct seat roles into one shared `AGENTS.md` or `CLAUDE.md`.
 - [ ] Write a rig `CULTURE.md` if the rig doesn't have one
 - [ ] Choose skills from the shared pool via profile `uses`
 - [ ] Write a `startup/context.md` if the agent needs environment grounding

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,7 +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.
+  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
 
@@ -32,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.