@openrig/cli 0.6.10 → 0.6.12

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

@@ -38,6 +38,31 @@ The attention codes that stop startup this way are `trust_gate`,
 `bypass_consent_gate`, `codex_auth_refusal` and `codex_client_incompatible`.
 They are recognized from each harness's English prompt text.
 
+## Continue a Codex fork whose child ID arrived late
+
+For a member with `session_source.mode: fork`, OpenRig waits for Codex's new
+child thread ID before sending its role and other startup prompts. It saves the
+ID and sends the role only for a verified child: the bound pane's foreground
+process forks the requested parent, and its own native record, matched to its
+start time, supplies the ID. This capture uses `runtime.readiness_timeout_seconds`
+(30 seconds by default, configurable from 1 to 600 seconds), as does the later
+readiness check. The two waits have separate budgets. A seat handover with
+`--source fork:<seat>` is different: its fork carries the conversation itself,
+and a missed ID capture leaves the ID pending rather than stopping the handover.
+
+If the ID is still unavailable, the seat reports `attention_required` and keeps
+its startup context pending. Wait for the child to finish starting, resolve any
+native prompt, then run `rig seat continue <seat>`. The continuation verifies
+that the bound pane is running a fork of the requested parent and reads the
+child's own native identity before delivering the saved context. It does not
+launch another fork or resume the parent. The parent ID is never saved as the
+child's resume token.
+
+An unavailable or conflicting identity leaves the context pending. Once prompt
+delivery has been attempted, it cannot be replayed by `continue`, including
+after a daemon restart: inspect `rig seat status <seat>` and the native pane
+before deciding how to recover an uncertain delivery.
+
 ## Two Categories of Startup
 
 Everything an agent receives at boot time falls into one of two categories:
@@ -215,7 +240,9 @@ 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.
+interactive"), and the post-launch files aren't sent. A Codex fork that the rig launches (a member with
+`session_source.mode: fork`, or an agent image's fork) is the exception: its timeout ends as `attention_required`,
+with its startup context kept for `rig seat continue` (see below). A seat handover's fork has its own readiness check.
 
 **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
@@ -229,13 +256,32 @@ one wins, and it needs `idempotent: true`). With `authenticated`, a fresh launch
 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
+**After a failure.** Delivery, launch and action failures, and readiness timeouts other than a Codex fork's, give
+`failed`. Every 30 seconds the context monitor marks a `failed` or `attention_required` seat `ready` once its pane reads
+ready, unless its fresh or Codex fork 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.
 
+**Preview before replacing a seat.** `rig seat launch <seat> --fresh --plan` inspects the selected
+seat without starting tmux, stopping or launching a process, projecting startup files, or changing
+lifecycle/queue records. Add `--json` for structured output. `--fresh` is still required;
+`--reason` is optional for the preview and required when executing. Pass `--stop` to preview the
+intended replacement of a live managed occupant. Adopted and unmanaged occupants remain blocked.
+
+The plan identifies the target, current occupant, stop requirements, blockers, startup counts,
+and each sibling seat's unchanged effect. Siblings stay attached and untouched. Launch composes
+a new command through the runtime adapter using current settings; it does not replay a stored
+wrapper command. The seat's launch environment and managed executable selection still apply.
+The plan does not construct or display the launch command.
+
+A preview is a snapshot, not a reservation or a native-readiness check. Unreadable tmux produces
+`complete: false` and `launchable: null` (unknown), unless a known blocker already proves
+`launchable: false`. A successful preview exits 0, including blocked or incomplete plans; scripts
+must inspect `launchable === true` before deciding to execute. Request failures still exit nonzero.
+Execution always resolves and checks the current state again. An older daemon without the preview
+endpoint refuses the request; the CLI never falls back to executing a launch.
+
 ### The `applies_on` Field
 
 Each startup file and action specifies when it applies:
@@ -255,7 +301,9 @@ The AgentSpec and RigSpec allow declaring deterministic environment configuratio
 ### What the Spec Supports
 
 **Hooks** ship inside plugins: declare the plugin under `resources.plugins[]`. AgentSpec validation refuses
-`resources.hooks`.
+`resources.hooks`. OpenRig loads one plugin's hooks into a seat itself: the shipped `openrig-core` plugin, for a Claude seat
+that selects it (see [the refocus channel](refocus-channel.md#the-mechanism)). The folder a declared plugin is projected into
+is not one Claude Code or Codex loads, so a plugin of your own does not get its hooks run by that projection.
 
 **Runtime resources** (in `resources.runtime_resources`):
 ```yaml
@@ -289,7 +337,7 @@ run after the harness is ready: `after_files` (the default) after the post-launc
 | 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. |
-| Hooks | **Through plugins** | Declare a plugin under `resources.plugins[]`; `resources.hooks` is refused. |
+| Hooks | **Through plugins, limited** | `resources.hooks` is refused. OpenRig loads the shipped `openrig-core` plugin's hooks into a Claude seat that selects it (Claude Code v2.1.280 or later); a plugin you declare under `resources.plugins[]` is projected, but its hooks are not loaded. |
 | 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; a seat with no policy, selection or named Codex profile also gets the per-launch [team default](rig-spec.md#team-launch-defaults), and the `kernel` rig's seats get a wider operational default ([rig spec, "At launch"](rig-spec.md)). Neither is written to a settings file. 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. |
@@ -407,6 +455,66 @@ remain shared.
 
 **Terminal seats** (`builtin:terminal`) get no agent or profile layers and no startup proof.
 
+### Codex compaction and sizing
+
+OpenRig's managed compaction is for Claude Code seats only, by design. That covers `rig compact`, the
+`policies.claude_compaction.*` automatic policy, and the watchdog jobs that the `managed-compaction` and
+`apprentice-handover` strategies create. A Codex seat compacts with Codex's own automatic compaction, and OpenRig
+leaves that to Codex.
+
+- `rig compact <session>` refuses a Codex seat: "not a Claude (claude-code) seat".
+- `rig compact-plan` lists a Codex seat as skipped (`codex_not_managed_by_claude_compact_in_place`).
+- The automatic policy never acts on a Codex seat.
+- A Codex member with `compaction_strategy: managed-compaction` or `apprentice-handover` gets no watchdog jobs.
+
+**What Codex compacts at.** Codex describes `model_auto_compact_token_limit` as the "token threshold that triggers
+automatic history compaction (unset uses model defaults)". Its configuration reference does not say what those
+defaults are, and the model catalog's `auto_compact_token_limit` is null for the models we checked in Codex 0.162.1.
+Measure a seat's own compactions before relying on an unset limit.
+
+**What window the model has.** `codex debug models` prints the catalog. Each model carries `context_window`,
+`max_context_window` and `effective_context_window_percent`. In Codex 0.162.1, `gpt-5.6-sol` has a `context_window`
+of 272000 at 95%, which is 258400. That is the `model_context_window` its rollout `token_count` events report.
+A limit only matters when it is below that effective window. Leave `model_context_window` alone: don't raise it toward
+`max_context_window` to avoid compaction. Set the limit instead.
+
+**Setting the limit for seats only.** Put `model_auto_compact_token_limit` in a Codex profile file,
+`$CODEX_HOME/<name>.config.toml` (`~/.codex/<name>.config.toml` when `CODEX_HOME` is unset), and name it on each
+Codex member that should use it:
+
+```toml
+# ~/.codex/seat-compaction.config.toml
+model_auto_compact_token_limit = 150000   # choose your own value
+```
+
+```yaml
+codex_config_profile: seat-compaction
+```
+
+OpenRig passes `-p seat-compaction` on that seat's fresh, fork and resume launches. Codex layers the profile file on
+top of the base user config, so only seats that name the profile see the lower limit. A Codex session started without
+that profile keeps the base `config.toml` in the same Codex home (`$CODEX_HOME/config.toml`, or `~/.codex/config.toml`
+when `CODEX_HOME` is unset). The `150000` is an example, not a recommendation.
+
+With the normal launch mode, `codex_config_profile` replaces OpenRig's explicit workspace-write sandbox flag, so the
+profile must set the sandbox and approvals you want. See
+[permission precedence and limits](getting-started.md#custom-settings-and-precedence), which also gives Codex's order
+of precedence between a profile, project settings and CLI overrides.
+
+**The trade-off.** Every model call carries the whole context so far, so a smaller context makes each call cheaper. The
+cost is that Codex compacts sooner and more often, so more of the conversation is carried as a summary instead of
+verbatim. A higher limit keeps more detail and makes each call larger.
+
+**Related keys.** These also shape compaction. This guide doesn't recommend values for them. See Codex's
+[configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference):
+
+| Key | What Codex says it does |
+|---|---|
+| `model_auto_compact_token_limit_scope` | `total` (the default) counts the full active context; `body_after_prefix` counts only growth after the carried compaction-window prefix. |
+| `compact_prompt` | Inline override for the history compaction prompt. |
+| `experimental_compact_prompt_file` | Loads the compaction prompt override from a file (experimental). |
+| `tool_output_token_limit` | Token budget for storing individual tool or function outputs in history. |
+
 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."
 
 ---

package/daemon/docs/reference/claude-status-line.md

@@ -0,0 +1,69 @@
+# Custom Claude status line
+
+OpenRig installs a silent context collector as `statusLine.command` in the seat
+working directory's `.claude/settings.local.json`. Claude's project-local setting
+overrides your user-level status line, so a renderer configured only in
+`~/.claude/settings.json` can disappear in that directory. Other Claude sessions
+using the same directory also read that setting.
+
+Since 0.6.5, OpenRig preserves a custom, nonempty project-local status line command,
+including a wrapper or a command composed with shell operators. It still refreshes
+its own collector script. If your command does not run the collector, context and
+provider usage stop updating, and Claude resume-token capture at adoption or
+handover loses its current session evidence. An earlier sidecar can remain and
+contain an older session ID; without one, context and capture report
+`missing_sidecar`, and provider usage reports `no_statusline_cache_yet` unless an
+earlier cache remains.
+
+## Feed both commands the same input
+
+On macOS, Linux or WSL2, save a wrapper such as this, replacing the three
+placeholder paths and `my-statusline` with your actual commands:
+
+```sh
+#!/bin/sh
+input=$(cat)
+printf '%s' "$input" |
+  node '/seat/cwd/.openrig/context-collector.cjs' \
+    '/instance/home/state/context-usage' \
+    '/instance/home/state/provider-usage' >/dev/null 2>&1
+printf '%s' "$input" | my-statusline
+```
+
+Take the collector path and both directory arguments from the existing generated
+`statusLine.command` in that seat's `.claude/settings.local.json`; the instance
+home is the selected `OPENRIG_HOME`. Keep paths quoted, including paths with
+spaces. Each command needs the same status line JSON on stdin: simply running
+the collector and renderer in sequence against a single stdin lets the first
+consume the input.
+
+In that same settings file, merge this field while preserving your other settings:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "sh '/absolute/path/to/openrig-status-line.sh'"
+  }
+}
+```
+
+Use the renderer command from your user-level configuration in the wrapper. The
+collector stays silent and the renderer supplies the visible status line. This
+POSIX-shell example applies to WSL2's Linux installation; it does not establish
+native Windows support.
+
+## Check after an upgrade or instance change
+
+The collector command's paths and arguments are implementation details. OpenRig
+preserves your wrapper, so it cannot refresh those arguments for you. Recheck
+them after an upgrade, a seat-directory move or an `OPENRIG_HOME` change.
+
+After Claude next updates its status line, inspect context usage in `rig ps` or
+`rig whoami --full` from the seat. Unknown or stale context is a reason to check
+the wrapper; it does not prove the collector is running. For a direct check,
+inspect the current session's JSON under the configured `state/context-usage`
+directory: its timestamp should advance and its `session_id` should match the
+current Claude session. A visible custom status line alone does not verify
+collection or end-to-end adoption/handover recovery. The wrapper above suppresses
+collector errors; remove its stderr redirection temporarily when diagnosing it.

package/daemon/docs/reference/getting-started.md

@@ -27,6 +27,10 @@ supports, though OpenRig's automated tests don't run on it yet. One user's
 odd-numbered releases (23, 25 and so on) are not supported; Node 26 and later
 even-numbered releases are untested.
 
+On Linux, if Codex cannot run commands and reports `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`,
+ask the machine owner to follow [OpenAI's sandbox prerequisites](https://developers.openai.com/codex/concepts/sandboxing#prerequisites),
+including its `bwrap` AppArmor profile guidance; changes to AppArmor are the owner's choice.
+
 **Choose permissions before starting the team.** Ordinary OpenRig launches use
 Codex's `-s workspace-write`, with approval policy from your native configuration,
 or Claude Code's `acceptEdits`, which still leaves commands subject to native
@@ -98,18 +102,32 @@ user.
 
 **Agents:** if you're setting OpenRig up for someone, load the `rigs` skill and follow it. It carries the install, the
 OpenRig view and the handoff to the operator as one procedure. From 0.6.7, OpenRig installs it as `rigs` in
-`~/.claude/skills` and `~/.agents/skills` when the daemon starts. Before that, add it with
-`npx skills add mvschwarz/openrig --skill rigs`, or read [`skills/rigs/SKILL.md`](../../skills/rigs/SKILL.md).
+`~/.claude/skills` and `~/.agents/skills` when the daemon starts. To add it manually, use the release tag matching
+your installed `rig --version`: replace `<release-tag>` below with that tag, including its `v` prefix.
+`rig --version` prints the version and a commit, for example `0.6.11 (379f0a0d)`; the tag is `v0.6.11`.
+The skill is in the repository from v0.6.6; on an older install, use the v0.6.6 tag or upgrade first.
+Choose the command for the agent doing the setup:
+
+```sh
+# Claude Code
+npx skills add "https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs" --skill rigs --agent claude-code
+
+# Codex
+npx skills add "https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs" --skill rigs --agent codex
+```
+
+These are the pinned, per-agent forms used on the [rigs pages](https://openrig.dev/rigs).
+You can also read [`skills/rigs/SKILL.md`](../../skills/rigs/SKILL.md) directly.
 
 **One command, for the full setup.** It needs Node.js 22 or 24 with npm already installed. The preview prints what the
 script will do and changes nothing:
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.8/scripts/install.sh | sh -s -- --dry-run
+curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.12/scripts/install.sh | sh -s -- --dry-run
 ```
 
 The same command without `--dry-run`,
-`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.8/scripts/install.sh | sh`, installs the
+`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.12/scripts/install.sh | sh`, installs the
 latest published `@openrig/cli` with `npm install -g`,
 runs the Node.js and SQLite check, then `rig setup --dry-run` and `rig setup`. `rig setup` checks both Claude Code and
 Codex and may install a missing one, as described below. A failed step prints
@@ -306,6 +324,7 @@ different points in the same journey:
 | Herdr shows its introduction or agent-integration panel | These are Herdr's first-run panels. Follow the displayed controls: Return continues the intro and Esc closes the integration panel. Opening this view does not require installing Herdr's agent integrations or changing your Claude/Codex settings. |
 | A saved layout is cramped in an 80×24 window | The default kernel view gives each role a full-width page. A custom saved `kernel` view still controls its own layout; adjust that saved view if needed. Changing or restarting the team is unnecessary. |
 | The command returned, but visibility is unconfirmed | With authorized desktop tools, inspect the new window and a screenshot of its contents. A window listing alone proves only that a window exists. If the agent has only shell access, report what the command confirmed and ask the person to confirm the visible operator and that the dashboard and advisor tabs or windows are available. Do not report visual success without seeing it. |
+| In a Claude Code seat's terminal, Shift+Enter submits instead of adding a newline | Whether Shift+Enter reaches Claude Code as its own key depends on the terminal and on tmux's extended-key support and settings ([`extended-keys`](https://man.openbsd.org/tmux.1#extended-keys), [`terminal-features`](https://man.openbsd.org/tmux.1#terminal-features__)). To add a newline anyway, press Ctrl+J, or type `\` and then press Enter. Claude Code's [tmux configuration guide](https://code.claude.com/docs/en/terminal-config#configure-tmux) covers the setup. |
 
 After a failure, inspect any newly opened surface before retrying. A tmux failure
 may name a newly created viewing session for inspection. Do not replace a failed
@@ -589,6 +608,7 @@ the lifecycle API without booting a new kernel, then stop the remaining rigs.
 | Tool missing or login fails | Use the specific setup/auth hint; recheck that executable in the launch shell. Do not send work to an unready seat. |
 | "Startup attention" or "Startup details" names a prompt | Answer the login, trust or bypass prompt in that seat's terminal, then run the `rig seat continue <seat>` it shows. |
 | "Readiness timeout after 30s — harness did not become interactive" | The harness took longer than the readiness window. Raise it for the next launch with `rig config set runtime.readiness_timeout_seconds <1-600>`, then relaunch that seat. |
+| "Claude resume did not finish within Ns; Claude may still be starting, so the launch was kept" | A restored Claude seat was not interactive when the wait ended. Its pane and resume token are kept. Look at the pane; once Claude is up, run `rig seat clear-attention <seat>`. The wait is about `runtime.readiness_timeout_seconds` in total for each seat (default 30 s), counting the first 3.2 s, and the time adds up seat by seat in a restore. Raising the setting for slow fresh launches lengthens it. If `rig up` or `rig launch` times out at 120 s, that is not a rollback: check `rig ps` before running it again. |
 | Daemon is healthy, kernel is still starting | Read `rig status` and `rig ps --nodes --rig kernel`; kernel readiness is separate. |
 | Kernel seats fail within a second of the first start, and tmux reports "server exited unexpectedly" | Check that your tmux can capture a pane, then start the failed seats again; see the tmux check below this table. |
 | Shared terminal is absent | Inspect the existing kernel binding and recovery state; use standalone `rig tui` while resolving it. |
@@ -883,7 +903,10 @@ after an authorized launch before claiming its actual permission behavior.
 The rig-level verbs are `rig policy permissions list`, `show`, `current` and
 `apply`. Existing `rig policy list/show/current/apply` remain compatibility
 aliases with the same JSON and exit behavior. Pi resource trust and the per-seat
-typing guard are separate controls.
+typing guard are separate controls. To retain automatic messages while you have
+an unfinished terminal input, opt that seat into [draft-aware delivery](seat-delivery.md).
+The same typing guard offers `hold` for a manual terminal (`--enabled true`)
+and `off` for ordinary automatic sends (`--enabled false`).
 
 ### Claude Code: a different launch flag
 
@@ -923,7 +946,17 @@ and managed restrictions still matter; this flag is not a promise about sandbox
 or account access. See [Claude permissions](https://code.claude.com/docs/en/permissions).
 
 **Already running:** changing a file or running `rig policy apply` does not revoke
-a live agent's permissions, nor rewrite a stored rig's policy on restore. Pause
+a live agent's permissions, and a spec edit does not rewrite a stored rig's policy
+on restore: restore and resume read each seat's stored policy. To change that
+for an existing seat, run `rig policy apply <name> --seat <seat> --reason <text>`,
+adding `--operator <address>` outside a managed seat. Restore, resume and launches
+that read the seat's stored state then use it, unless an explicit native selection
+(`rig seat set-permissions`) takes precedence; the running process and the spec
+file are unchanged. `rig up <rig name>` uses it, while launching from a spec that
+declares a policy replaces it with the spec's policy, which later restores then
+use. `--seat none` is an explicit floor for that seat, not "no policy", and it does
+not inherit the rig's policy. After `--seat`, a `rig launch --retry-startup-from`
+file has to carry the new policy. Pause
 work and use the native permission controls for that conversation (current
 Codex and Claude CLIs expose `/permissions`); inspect the effective mode again.
 Keep the launch spec/profile consistent for subsequent launches. If the native

package/daemon/docs/reference/keeping-a-watch.md

@@ -0,0 +1,253 @@
+# Keeping a Watch for a Person
+
+**How an operator turns "remind me in 20 minutes" or "tell me when X happens, check every hour" into a watch it
+keeps, using today's queue commands.** The person speaks in sentences. They never see YAML, a job ID or a policy name
+unless they ask.
+
+> **Status (0.7.0).** The kernel operator's role guidance points here: when a person asks it to watch something or
+> remind them, it reads this page (installed at `$OPENRIG_HOME/reference/keeping-a-watch.md`) first. Every step below
+> was exercised with the CLI on an isolated private daemon: create, set aside, fire, re-arm, list, change, stop, a
+> daemon restart and a handover. A native run with a real operator, install and channel has **not** been run yet.
+> The usage warning's command and field names are checked against the served command on a test fixture; it hasn't
+> been run as a watch.
+
+## The shape
+
+A watch is a **queue task the operator owns**, set aside with a **one-shot timer**:
+
+1. The person asks. The operator creates one task for itself and sets it aside with `--wake-after`.
+2. The timer fires once and wakes the operator. The operator reads the task and checks the condition.
+3. Then it tells the person, re-arms the timer, or both. **A timer fires once: a watch that isn't re-armed goes
+   quiet.**
+
+OpenRig keeps the record and the timer. The operator does the judgment: what to check, and whether it's worth telling
+the person.
+
+## Before you set one: can you reach the person?
+
+Run `rig gateway human list --json`. A watch tells the person through the registered human channel (Slack today,
+also shown in the TUI Feed), at `<entityId>@external`. **A terminal is never a person's address.** If no human is
+registered, say so now, before setting anything up: a watch that can't reach them is a watch they'll never hear from.
+
+## Setting a watch
+
+**1. Write the task body for a successor.** You may be restarted, compacted or replaced before the watch ends. A new
+operator must be able to act from the task alone. Put these in the body:
+
+```markdown
+Person's words: "Tell me when the release PR merges; check every hour."
+Check: `gh pr view <n> --json state` — met when state is MERGED.
+Interval: 1h.
+Tell them: <entityId>@external (human channel), once, when met.
+Stop: after telling them once, or when they say stop.
+Unknown: not said yet.
+```
+
+**2. Create it for yourself,** with a `watch` tag so it can be listed later (tags can't be changed after creation).
+`<your session>` is your session name from `rig whoami --json`:
+
+```bash
+rig queue create --destination <your session> --tags watch \
+  --summary "Watch: tell <person> when the release PR merges (hourly)" --body-file <file>
+```
+
+**3. Set it aside with the timer.** A new pending task can be set aside directly; no claim is needed:
+
+```bash
+rig queue block <task> --on external:<what you check> --wake-after 1h \
+  --continuation "check <what>; tell <person> if met, else re-arm 1h"
+```
+
+`--on` is always required; `external:<what>` names the outside thing you're waiting on. The timer first fires after
+the interval, not now.
+
+**4. Say back what you set, in one or two plain lines:** what you'll check, how often, how they'll be told, and when
+it stops. For example: "I'll check the release PR every hour and message you here once it merges. Then I'll stop."
+
+A plain reminder ("remind me in 20 minutes to look at the release notes") is the same with no condition. Set it aside
+with `--wake-after 20m`, and when it fires, tell them and close it.
+
+## Every time the timer fires: read the record first
+
+When the timer's message arrives, **run `rig queue show <task> --full --json` before doing anything.** A message already
+on its way can still arrive after the watch was stopped or changed. If the task is no longer set aside (done, canceled, or replaced),
+do nothing.
+
+Otherwise, check the condition, then do exactly one of these:
+
+| What you found | Do |
+|---|---|
+| **Met, and the watch was "once"** | Tell the person (below), then close: `rig queue update <task> --state done --closure-reason no-follow-on --note "<what you saw>"` |
+| **Met, and it's "every time"** | Tell the person, then re-arm |
+| **Not met** | Re-arm. Say nothing to the person: never send "nothing yet" |
+| **Can't tell** (no fresh reading) | The first time, tell them once that you can't tell, and why. Record that in a note (`Unknown: said <time>`), then re-arm. **Never say "all fine" for an unknown.** Stay quiet on later unknowns until the reading returns or changes |
+
+**Re-arm** by setting it aside again with a fresh timer:
+
+```bash
+rig queue block <task> --on external:<what> --wake-after 1h --note "checked <time>: not met"
+```
+
+A new set-aside replaces the old one and retires any earlier timer, so a task never carries two live timers.
+
+**Put what changed in `--note` or `--continuation`, not both.** When `rig queue block` gets `--continuation`, that is
+the note it records, and `--note` is dropped.
+
+Each check costs one of your turns on the person's subscription. **Use the longest interval that serves the ask.**
+
+## Telling the person
+
+```bash
+rig queue create --destination <entityId>@external --human-intent update \
+  --summary "<subject>" --body-file <brief> --evidence-ref <watch task id> --verify --json
+```
+
+- Always pass `--evidence-ref`; the watch task's ID is a durable pointer the person can open.
+- Later messages about the same watch can thread with `--reply-to <earlier message's id>`.
+- **`posted` means the connector posted it, not that they read it.** Don't say they saw it.
+- **If delivery fails or is indeterminate,** inspect that task before anything else. Never resend blindly.
+
+## "What are you watching for me?"
+
+List **every active state**, not just set-aside ones. A watch being checked can be in progress, and a new one can be
+pending:
+
+```bash
+rig queue list --owned --state pending,in-progress,blocked --full --limit 200 -o json
+```
+
+Then keep the tasks tagged `watch`. Two rules:
+
+- **Check that the number of tasks returned is below the limit.** The limit applies before you filter by tag. If you got
+  exactly the limit, raise it and list again. **Never report "no watch" from a page that was cut off.**
+- **Use `--full`.** Compact output leaves out the body and the waiting view.
+
+For each watch, say what it checks, how often, how they'll be told, and the next check. The next check is
+`waiting.nextBackstop.dueAt` when `waiting.nextBackstop.mechanism` starts with `watchdog:`. If a set-aside watch shows
+no timed backstop instead, its timer has fired and wasn't re-armed. Check it now and re-arm it.
+
+Answer from the records, so a second reader would give the same list.
+
+## Changing or stopping a watch
+
+| The person says | Do |
+|---|---|
+| **"Check every 2 hours instead"** | Re-arm with the new interval and a note saying what changed: `rig queue block <task> --on external:<what> --wake-after 2h --note "<person's words>"` |
+| **"Watch Y instead"** (what's checked changes) | A task's body can't be edited. Create the new watch, then retire the old one: `rig queue update <old> --state canceled --closure-reason superseded --closure-target <new> --note "<person's words>"` |
+| **"Stop watching that"** | `rig queue update <task> --state canceled --note "<person's words>"`. Leaving the set-aside state retires its timer. A plain cancel takes no other closure fields |
+
+Tell the person in one line what changed. After a stop, take no further action for that watch.
+
+## Across a restart or handover
+
+A set-aside watch's current timer is **kept** when the operator is restarted or replaced, and it fires at whoever is
+the operator next. That's why the body must stand alone.
+
+**One gap:** a timer fires once. If the operator is replaced **after a fire and before the re-arm**, the successor
+inherits a set-aside watch with no live timer. OpenRig's idle-owner check may remind the new operator once, but only
+under some conditions, with no delay guarantee. So:
+
+- **Re-arm promptly** after every fire.
+- **After a restart or handover, list your watches** (above) and re-arm any that show no timed backstop.
+- **Handing a watch to another session** (`rig queue handoff <task> --to <session>`) closes the old task and retires its
+  timer (unless another task shares that timer through `--wake-watchdog`; a watch set up as above never does). The new
+  task arrives pending, with its body and `watch` tag but no timer: the new owner sets it aside again with a fresh
+  timer, as in step 3.
+
+## A usage warning: "warn me when my allowance runs low"
+
+This is a conditional watch like any other: the same task, timer, re-arm, stop and human channel. Only the check is
+specific.
+
+**The check is `rig provider status --all-hosts --json`.** It returns what every registered machine already holds,
+this one included, and never starts a read on any account. With no host registry it covers this machine only, and
+says so. Use it rather than the single-machine `rig provider status --json`: one allowance used from several
+machines appears once, with each machine's own observation beside it, so you can't count it twice. If it answers that
+usage windows are off, tell the person that before setting the watch, as you would an unreachable channel.
+
+**Never put `--refresh` in the timer's check.** `rig provider status --all-hosts --refresh` starts a native read of the
+accounts on every machine. Run it only when the person asks for a fresh reading now.
+
+**Choose the allowance with the person once, and write its identity into the body.**
+- **The allowance:** its `items[].key` and `items[].provider`, read from one run of the check. Show them the allowance
+  by its label in the plain `rig provider status --all-hosts` view, never a key they have to type. An item whose key
+  is null (a login that hasn't been identified) can't be watched: say so, and offer to watch it once it's identified.
+- **For Codex, the login email too:** `items[].observations[].row.identity.email`, shown on each machine's line in the
+  plain view. The same Codex account can appear as more than one item with the same key, one per login email (or none)
+  it was seen under. So on each fire, use the one item whose key matches and whose observations carry the recorded
+  email. If none or several do, you can't tell. A Codex allowance whose login email is missing can't be pinned this
+  way, so it stays can't tell. A changed email isn't followed: if the person's login email changes, set the watch
+  again with them.
+- **The window:** `items[].observations[].row.windows[].window`. Claude's are `five_hour` and `weekly`; Codex's are
+  `primary` and `secondary`, with `items[].observations[].row.windows[].durationMins` saying which is which.
+- **The threshold:** on `items[].observations[].row.windows[].remainingPercent`. It's a percentage, and no absolute
+  amount is served. Remaining is 100 minus `items[].observations[].row.windows[].usedPercent`, never below 0. Both are
+  null when the machine reported no usage for the window.
+
+**What each part of the answer means:**
+
+| Field | What it tells you |
+|---|---|
+| `items[].linkage` | `single`: one machine saw it. `same`: several machines saw one allowance. Compare their observations; **never add or average them**. `conflict`: the machines' fresh observations disagree (their reset times are more than 60 s apart); every observation is kept and none is chosen. `unknown`: the same id seen under another login, or with no login email, and not merged with it. `items[].notes` says why. For Codex, the one item carrying the person's recorded key and email is still theirs: its `unknown` is about the other login's item (see the decision). Any other `unknown` item is not theirs to watch |
+| `items[].observations[].hostId`, `items[].observations[].readAt` | Which machine the observation is from, and when this daemon read it |
+| `items[].observations[].row.windows[].observedAt` | When that machine's reading was taken: the time to tell the person |
+| `items[].observations[].row.windows[].resetsAt` | When that window resets: tell the person this too |
+| `items[].observations[].row.windows[].freshness` | `fresh`, `stale` or `unavailable`, with `items[].observations[].row.windows[].freshnessReason` saying why. A reading is fresh for 15 minutes |
+| `items[].observations[].row.windows[].level` | The served level, with `items[].observations[].row.windows[].levelReason`. Compare the person's threshold, not this level. But **`unknown` means the number can't be used**: no usage was reported, the window's reset time has passed (the number is from before it), or Claude seats report different windows (possibly different logins) |
+| `items[].observations[].row.lastRefresh` | **Codex:** that machine's last native read. When `items[].observations[].row.lastRefresh.outcome` is `failed`, the reading it kept is older and reads `stale`. **Claude:** the last read of the daemon's own Claude login (its identity) only. Claude's windows come from the seats' status-line readings at their own times, so they can stay `fresh` beside a failed identity read |
+| `items[].observations[].row.identityNote` | **Claude:** which login the identity is (as of the last identity read) and which seats the windows came from. The windows aren't proven to be that login. Say so when you tell the person |
+| `hosts[].usage`, `hosts[].usageReason` | Whether each machine's usage was read: `served`, `off`, `older` or `unavailable`, and why. A machine that wasn't read contributes nothing, never a zero |
+| `hosts[].lastRefresh` | The last refresh started from here for that machine, per provider. A `failed` one sits beside the older observation the machine kept |
+| `seatAccounts[].seats[].configured`, `seatAccounts[].seats[].allowance` | The account each seat is **configured** to use. `seatAccounts[].seats[].allowance.linked` is always false: configuration isn't proof of which allowance a running seat draws on, or that a Claude seat's windows are the identity's login. Never tell the person a seat uses this allowance because of it |
+| `seatAccounts[].seats[].observed` | What the seat itself was seen reporting: whether its status line has sent windows and when (`seatAccounts[].seats[].observed.lastSampledAt`), and `seatAccounts[].seats[].observed.differsFrom`, the seats whose readings disagree with it. Observed facts, still not a link to an allowance |
+
+**The decision on each fire,** using the table in "Every time the timer fires". A usable reading is a `fresh`
+observation of the chosen window whose `level` isn't `unknown`.
+- **Met:** a usable reading is below the threshold. Tell them the lowest one, with its machine, `observedAt` and
+  `resetsAt`. If the linkage is `conflict`, also tell them the machines disagree, from `items[].notes`, rather than
+  presenting the lowest as the reading.
+- **Not met:** every usable reading is at or above the threshold, and there is at least one.
+- **Another login on the same Codex account:** when the item matched by key and recorded email has `items[].notes`
+  saying the account is also observed under another login email (or with none), its linkage reads `unknown` on one
+  machine, or `same` on several. Use its own usable readings as above. When you tell the person, say that login's
+  observations are unlinked: not added, and not merged.
+- **Can't tell:** no usable reading: none `fresh`, or the fresh ones' `level` is `unknown`, which includes a null
+  `remainingPercent`. Also when the allowance is missing from the answer or its key is null, or (Codex) no login email
+  was recorded, or no item, or more than one, carries both the key and the recorded email. Use the once-then-quiet
+  unknown rule, and give the reason (`freshnessReason`, `levelReason`, or the machine's `usageReason`).
+
+The task body, for the person's own allowance, window and threshold:
+
+```markdown
+Person's words: "Warn me when my Claude allowance drops below 20% of its 5-hour window; check every 30 minutes."
+Check: `rig provider status --all-hosts --json` (served readings only; never --refresh).
+Allowance: key <allowance key>, provider claude, window five_hour. Chosen with the person.
+(For Codex, also: login email <email shown in the label>.)
+Usable: a fresh observation of that window whose level isn't unknown.
+Met: a usable reading with remainingPercent below 20. Report the lowest, with its machine, observedAt and resetsAt.
+Never add machines' numbers. If the linkage is conflict, say the machines disagree (items[].notes).
+Claude: say the windows come from seats' status lines and aren't proven to be the identity's login (identityNote).
+Codex: the one item with the recorded key and email is theirs even if its linkage is unknown; say the other login's
+observations are unlinked (items[].notes).
+Can't tell: no usable reading (none fresh, or level unknown: give its levelReason), the allowance missing or its key
+null, or (Codex) no email recorded, or no item, or more than one, carries both the key and the recorded email. Give the
+reason.
+Interval: 30m.
+Tell them: <entityId>@external (human channel), once, when met.
+Stop: after telling them once, or when they say stop.
+Unknown: not said yet.
+```
+
+## What not to use
+
+- **`rig watchdog register --policy periodic-reminder` for a person's watch.** It repeats every interval until it's
+  stopped (the first fire comes one interval after you register it), and it stops when the agent that registered it
+  is replaced. It's fine for agent-to-agent reminders. Your own watch timers also show as `periodic-reminder` in
+  `rig watchdog list`: that's the one-shot timer `--wake-after` arms, not a registered repeating reminder. It's retired
+  when it fires or when the task stops being set aside. A wake held back because you were typing (a retained
+  delivery) wasn't delivered, so it doesn't use the timer up: it's tried again at each interval until an attempt goes
+  through (delivered or failed), which retires it. A timer another task shares through `--wake-watchdog` stays live
+  for that task when this task is handed off or stopped, and the same rule applies to its wake. None of this is a
+  delivery guarantee.
+- **Transcript bytes as "usage".** `context-usage-threshold` measures an agent's transcript, not an account's
+  allowance. For an allowance, see "A usage warning" above.