@openrig/cli 0.6.11 → 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,9 +256,9 @@ 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.
@@ -274,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
@@ -308,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. |
@@ -426,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

@@ -4,9 +4,12 @@
 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, not on by default).** No agent's guidance points here yet, and no profile loads it. It's switched
-> on by adding one line to the kernel operator's role guidance, after a native run on a real install shows the
-> pattern holds. Until then, hand this page to an operator by hand (`docs/reference/keeping-a-watch.md`) to try it.
+> **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
 
@@ -146,11 +149,105 @@ 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.
+  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.
+  allowance. For an allowance, see "A usage warning" above.

package/daemon/docs/reference/project-workspace.md

@@ -189,7 +189,11 @@ ambiguity.
 ## Queue Mapping
 
 A `slice:<id>` tag is the authoritative way to attach a queue item to a slice;
-with a project selected, typed rows also need the `project:<id>` tag. As a
+with a project selected, typed rows also need the `project:<id>` tag. The tag
+value is either the slice's frontmatter `id` (a dot-ID such as `CUS.9775.1.1`)
+or its directory name (`01-custody-funds`); both resolve to the same slice on
+the Queue tab, the ownership lanes and the agents band. A row that carries both
+forms counts once. As a
 fallback, for slices with no typed rows, items attach when their body or tags
 mention one of:
 
@@ -210,6 +214,71 @@ Slice: capture-product-ideas
 This makes Story, Queue, Tests, and Topology tabs line up with the filesystem
 slice without adding a separate project database schema.
 
+### Workflow packets
+
+Packets that `rig workflow` projects carry the scope of their instance. Pass the
+scope when the instance is created and every packet it creates (the entry, each
+hand-off and gate, exception items, and resume packets) is tagged, so they show
+on the slice's Queue tab:
+
+```bash
+rig workflow instantiate ./spec.workflow.md \
+  --root-objective "Build the capture flow" --created-by orch@my-rig \
+  --project my-project --mission idea-ledger --slice capture-product-ideas \
+  --tags ticket-7
+```
+
+- `--project` should name a project in the workspace catalog. `--mission` and
+  `--slice` take the same ids as the slice routes. `rig workflow run` takes the
+  same flags. The CLI refuses what it can check itself (an id of the wrong shape,
+  a reserved tag, a tag that contradicts a flag) as a usage error, before
+  anything is sent. Only the daemon knows the catalog, so a mistyped `--project`
+  is **not refused**: the daemon creates the instance unscoped, its packets carry
+  no scope tags, and the CLI prints a warning on stderr (also with `--json`)
+  that names the instance and says the scope was not applied. The CLI does not
+  retry; instantiating again creates a second instance.
+- Packets carry `project:<id>`, `mission:<id>` and `slice:<id>` for the parts
+  you set, then your `--tags`, after the tags the workflow system writes. Tags
+  compose as in `rig queue create`: duplicates collapse, so `--slice S --tags
+  slice:S` is one tag.
+- `--tags` is refused locally when it carries what the workflow runtime reads
+  back to route packets: `workflow`, `handoff`, `gate`, `entry`, `resume`,
+  `re-route`, `workflow-exception`, and the `workflow:`, `instance:`, `step:`,
+  `exception:`, `occurrence:` and `recovery-for:` prefixes, a `project:`,
+  `mission:` or `slice:` tag that contradicts its flag, or a second value of
+  the same key.
+- `rig workflow instantiate-lifecycle` needs no flags: it takes the project and
+  mission from the lifecycle identity it compiles. A compiled step's packets
+  carry the `slice:<directory>` of the slice that step was compiled from, even
+  when another slice's directory has the same name as its `metadata.id`. A step
+  an authored graph names carries `slice:<directory>` when it names an active
+  slice: by its exact directory name, else by a `metadata.id` that exactly one
+  active slice claims (an id two slices claim maps to nothing, with a compile
+  advisory). A step that names no slice, such as an authored closing step,
+  carries only `project:` and `mission:`, so it appears on no slice's Queue tab.
+  A project id or mission name the compiler reads from the manifests that cannot
+  be a tag (a space, a `:`, a leading `.`, `_` or `-`, or too long) is left off
+  the packets with a compile advisory; the lifecycle still instantiates. Slice
+  metadata the lifecycle does not run is read only leniently, for step names, and
+  never fails compile or instantiate.
+- Over HTTP, `POST /api/workflow/instantiate` reads the scope from a `scope`
+  object (`{ project, mission, slice, tags }`). A scope that is valid and names
+  a catalogued project is applied as above. A scope the route cannot apply (a
+  project the catalog does not declare, a conflicting, reserved or malformed tag
+  or id, or a `scope` that is not an object) is ignored: the route does what it
+  did before the field existed and creates one unscoped instance, records
+  nothing the scope named, and never lets a rejected tag reach a packet. The
+  response `advisories` then carry a `Scope not applied (...)` note that names
+  the instance (`scopeIgnored` repeats it); `rig workflow run` prints
+  `advisories`. Bare `project`, `mission`, `slice` or `tags` fields in the body
+  are ignored the same way, with a note. A failure unrelated to the scope still
+  fails the request.
+- A Projects view scoped to a project lists a slice's packets only when they
+  carry `project:<id>` as well as `slice:<id>`, so pass `--project` with
+  `--slice`.
+- The scope is stored on the instance when it is created and does not change.
+  Instances created without it behave as before.
+
 ## Compatibility
 
 The default discovery root is `workspace.slices_root=<workspace.root>/missions`.

package/daemon/docs/reference/publishing-a-rig-bundle.md

@@ -21,7 +21,12 @@ Two rules matter most for strangers:
 - **Keep everything inside the folder.** Every `agent_ref` should be `local:` and point inside it. A path that exists on
   your machine won't exist on anyone else's.
 - **Never put credentials in it.** No tokens, keys or `.env` files. `rig bundle create` refuses well-known sensitive
-  file names (such as `.env`, `.pem` and `.key`) anyway.
+  file names (such as `.env`, `.pem` and `.key`) anyway. It also refuses contained `.claude/.credentials.json`,
+  `.codex/auth.json` and `.pi/agent/auth.json`, including nested copies in agents or a carried project. Remove them
+  and rebuild. Only if recipients should have these logins (for example, your own internal test bundle) and their
+  owner agrees, `rig bundle create --include-login-files` records the exact included login-file paths in the
+  manifest and consumers show a notice; anyone with the bundle could read those files.
+  Unrecorded login files and other sensitive paths still fail. See [harness login files](rig-bundle.md#harness-login-files).
 
 Two optional files sit beside `rig.yaml`:
 - **`bundle.yaml`** declares what people need before installing: setup steps (`preconditions`, shown before install

package/daemon/docs/reference/refocus-channel.md

@@ -16,6 +16,30 @@ it is the mechanism that makes shipped chain files (see
 | Stop | ✓ | — | catch a long Claude turn crossing the growth threshold |
 | PostCompact | ✓ | ✓ | retain exact compaction due-state; deliver on the next actionable prompt |
 
+**How the hooks reach a seat.** A Claude seat whose resolved plugin selection includes the shipped `openrig-core` plugin
+(for example `plugins: [shared:openrig-core]`, or the same plugin under another name) starts with `CLAUDE_CODE_PLUGIN_DIRS`
+set to the vendored plugin (`$OPENRIG_HOME/plugins/openrig-core`), so Claude loads `hooks/claude.json` with no setup step, on a
+fresh launch, a restore, a handover successor and a launch with a permission mode. A seat that didn't select the plugin is
+launched as before and doesn't load these hooks. The folder a spec's plugin selection projects into the seat's workspace is
+not what Claude loads. A list the seat declares itself in `CLAUDE_CODE_PLUGIN_DIRS` keeps working, with the vendored plugin
+added after it.
+Claude Code reads this variable from v2.1.280. OpenRig doesn't check the Claude version at launch: an older Claude ignores the
+variable, starts normally, and doesn't load these hooks. The behaviour was checked on Claude Code 2.1.296 and not on
+earlier versions.
+A Claude started from inside a seat (its shell or Bash tool) inherits the seat's environment and so loads the plugin as well.
+A seat that loads the plugin is also given `OPENRIG_SEAT_PROJECT_DIR`, its launch project, and the plugin's seat effects (the
+activity and session-identity posts, the compaction hooks, refocus, and the first-launch marker) run only when that Claude's
+`CLAUDE_PROJECT_DIR` names the same folder (compared by real path, so a trailing slash or symlink doesn't matter). A nested
+Claude in another project, or in a subfolder of the seat's project, therefore changes nothing for the seat, and a `cd` inside
+the seat's own session keeps working because `CLAUDE_PROJECT_DIR` is fixed when Claude starts. A nested Claude in the seat's
+own project folder is the same project and still acts as the seat, as before this change. Without either variable (a seat
+launched before this change, a manual run) the hooks do what they always did. The plugin's activity relay stays quiet next to
+the seat's own `settings.local.json` copy only when that entry is exactly OpenRig's and the script it names is the same
+script; an entry from an older install doesn't match, so both report until the seat's next launch refreshes it.
+Codex has no way to load a plugin from a directory; its hooks come from the daemon's
+managed block in `config.toml`, which today carries the activity relay only, so the Codex column above describes
+`hooks/codex.json`'s registration and not a hook a Codex seat currently runs.
+
 Claude's additional firing signal is **transcript growth** — not turns (one turn
 can burn 200k tokens across fifty tool calls) and not wall-clock (the failure is
 sustained work, not elapsed time). Its default threshold is ~2.6MB of JSONL
@@ -33,11 +57,23 @@ that request asks the seat to read the refocusing skill and consume the delivere
 traces rather than rerun them, and the read-depth audit accounts for them. Otherwise the hook
 is a no-op (it writes a stderr advisory when the transcript shrinks or the
 session has no identity), and it degrades to silence on unrelated hook errors.
-Both runtimes stop the hook after 5 seconds, and the content REF lookup gets 2;
-a slow REF shows as `REFOCUS CONTENT REF FAILED`. A
-configured REF resolution failure instead degrades
-loudly in the delivered payload while still completing the hook — a refocus
-must never break a seat's turn.
+**Time budget.** By default each lookup (the trace, the content REF, `rig queue whoami`, `rig config`) gets 2 seconds,
+as before, and a slow one ends as a reported gap (`TRACE GAP`, `REFOCUS CONTENT REF FAILED`, or a role marked
+unknown). Set `OPENRIG_REFOCUS_BUDGET_MS` in a seat's environment to give a slow trace more time, up to 52000 (52 s).
+Each lookup's cap then grows in proportion (at 45000 the trace may take 20 seconds; at 52000, about 23), and every lookup
+is also cut to what is left of that budget, so the attempt delivers what it has and counts as failed. After a failed
+attempt, the issue report gets its own 1.5 seconds once the lookups are done. Both registrations allow `refocus.cjs` 60
+seconds, where they used to stop it at 5; the other OpenRig hooks keep theirs. So a default fire whose lookups together
+pass 5 seconds now completes instead of being stopped with nothing delivered, and a hook that hangs outside its lookups
+can hold a prompt for up to those 60 seconds.
+
+A configured REF resolution failure degrades loudly in the delivered payload while still completing the hook — a
+refocus must never break a seat's turn.
+
+**Overlapping events (unresolved).** Two hook runs for the same seat and occupant are not serialized. If they overlap,
+a `PostCompact` recorded while a prompt is delivering can be lost, and one refocus can be delivered twice. This is
+reproduced between hook processes; whether a harness overlaps these events for one session is not established, so it is
+an open gap, not one shown to be safe.
 
 Failed trace or configured-content resolution keeps refocus due. After three
 consecutive failed attempts for the same seat and occupant, the hook emits one