@openrig/cli 0.6.9 → 0.6.11

package/README.md

@@ -42,7 +42,7 @@ To install with Bun instead, run `bun add -g @openrig/cli`. OpenRig still runs o
 
 npm 11 and later can skip that postinstall script and print `npm warn install-scripts` naming `@openrig/cli`. That's expected: the CLI still works, and only the Node.js and SQLite check was skipped. To run it yourself, use `node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"`; `rig doctor` checks the Node.js version only.
 
-Choose the working account you already have: **Claude Code, Codex, or both**. Reuse an explicit choice; no second subscription is required. `rig setup --dry-run` previews the broader setup; applying `rig setup` checks both harnesses and installs a missing one, plus Herdr unless declined with `--no-herdr`. On macOS, the installing agent offers Ghostty once. Setup leaves an existing cmux installation alone. It is optional for the [selected-provider path](docs/reference/getting-started.md#choose-your-providers).
+Choose the working account you already have: **Claude Code, Codex, or both**. Reuse an explicit choice; no second subscription is required. `rig setup --dry-run` previews the broader setup; applying `rig setup` checks both harnesses and installs a missing one, plus Herdr unless declined with `--no-herdr`. Pass the choice with `--providers claude` or `--providers codex` so the other reads not selected instead of failed. The one-command install above doesn't know the choice, so it installs and checks both; for one provider, go step by step and run `rig setup --providers <choice>`. On macOS, the installing agent offers Ghostty once. Setup leaves an existing cmux installation alone. It is optional for the [selected-provider path](docs/reference/getting-started.md#choose-your-providers).
 
 A team seat with no permission policy, per-seat choice or (for Codex) named profile launches with OpenRig's [team default](docs/reference/rig-spec.md#team-launch-defaults): Claude runs ordinary `rig` commands, project reads and common tests without prompting, while lifecycle commands such as `rig up` and `rig down` still ask; Codex also gets the OpenRig workspace and its pod's state directory as writable directories. Before launching, your agent recommends keeping that default, and offers to remember selected OpenRig commands in your native settings only if you want that, at personal project scope unless you explicitly choose user-wide sessions. It is not global YOLO or permission to invent work. On Yes, the agent [adds and verifies native rules](docs/reference/getting-started.md#have-your-agent-configure-permissions); No or no answer keeps the team default and leaves settings unchanged. An existing explicit choice is reused. Say “Undo the OpenRig command allowances added by this setup” to remove only its additions.
 
@@ -447,7 +447,7 @@ Before setup or managed launch, review [what OpenRig changes on your machine](#w
 
 Already-running adopted sessions may need restart before they pick up newly written runtime config.
 
-**For agents:** First ask which available provider(s) the user wants, reusing an explicit choice. Recommend the working account they already have and follow the selected-provider guide above. Offer core setup (`rig setup`) or the fuller workstation path (`rig setup --full`) only when they want those additional tools. Inspect the result with `--json` and use `rig doctor` to finish any remaining machine-specific issues. Then start the daemon if it is stopped, open the OpenRig TUI and operator for them (say so, then run `rig terminal open saved:kernel --window --json`; no commands for the person to copy), and hand the person's goal and project folder to the kernel operator ([installing-agent handoff](docs/reference/getting-started.md#installing-agent-handoff)). Installation is finished when the person is talking to the operator; don't implement the project yourself. When OpenRig itself misbehaves, read [docs/reference/help.md](docs/reference/help.md) (installed agents can run `rig context get help`; the same text is at [openrig.dev/help/agents](https://www.openrig.dev/help/agents)): it covers the next step, known problems, and how to reach the team if you're still stuck.
+**For agents:** First ask which available provider(s) the user wants, reusing an explicit choice, and pass it to setup (`rig setup --providers claude`, `codex` or `both`). Recommend the working account they already have and follow the selected-provider guide above. Offer core setup (`rig setup`) or the fuller workstation path (`rig setup --full`) only when they want those additional tools. Inspect the result with `--json` and use `rig doctor` to finish any remaining machine-specific issues. Starting OpenRig and opening its view are the last steps of installing, not extras, so do them without stopping to ask whether to go on: start the daemon if it is stopped, open the OpenRig TUI and operator for them (say so, then run `rig terminal open saved:kernel --window --json`; no commands for the person to copy), and hand the person's goal and project folder to the kernel operator ([installing-agent handoff](docs/reference/getting-started.md#installing-agent-handoff)). Installation is finished when the person is talking to the operator; don't implement the project yourself. When OpenRig itself misbehaves, read [docs/reference/help.md](docs/reference/help.md) (installed agents can run `rig context get help`; the same text is at [openrig.dev/help/agents](https://www.openrig.dev/help/agents)): it covers the next step, known problems, and how to reach the team if you're still stuck.
 
 ## Comparison with Claude Managed Agents
 

package/daemon/assets/onboarding/02-self-and-competent-action.md

@@ -67,9 +67,10 @@ conversation. Explain the failure and help with the chosen fallback; do not atta
 Over headless SSH, explain that no visible terminal opened; tell the person to open a new terminal window or
 tab and give one complete connection and attachment command using the current Herdr endpoint, as in the guide.
 No, SSH and headless use are valid background outcomes. If the person chooses a manual operator attachment after
-a failure, find the `operator.agent` row with `rig ps --nodes --rig kernel --json`. Give the exact
-`env -u TMUX tmux attach-session -t '=<canonicalSessionName>'` with the observed name filled in for a new terminal
-on the same host and user (over SSH, connect there first). Ctrl-b, then d detaches without stopping it.
+a failure, find the `operator.agent` row with
+`rig ps --nodes --rig kernel --json --fields logicalId,canonicalSessionName,tmuxAttachCommand`. Give `env -u TMUX` followed by
+that row's `tmuxAttachCommand`, exactly as listed (it names the daemon's tmux server when that isn't the default
+one), for a new terminal on the same host and user (over SSH, connect there first). Ctrl-b, then d detaches without stopping it.
 Ask the person's goal and project folder, then hand them to the ready operator; do not implement the project yourself.
 Find the `operator.agent` row with `rig ps --nodes --rig kernel --json` and use its `canonicalSessionName` with
 `rig send <canonicalSessionName> 'This is the agent that installed OpenRig. The person will answer in your pane. Goal: <goal>. Project folder: <absolute path>.'`,

package/daemon/assets/plugins/openrig-core/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openrig-core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "OpenRig canonical skills and hooks for cross-runtime agent topology coordination, continuity, and operating discipline.",
   "author": {
     "name": "Mike Schwarz",

package/daemon/assets/plugins/openrig-core/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openrig-core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "OpenRig canonical skills and hooks for cross-runtime agent topology coordination, continuity, and operating discipline.",
   "author": {
     "name": "Mike Schwarz",

package/daemon/assets/plugins/openrig-core/hooks/scripts/activity-relay.cjs

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 "use strict";
 
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
 // OpenRig activity-relay hook script.
 // Reads a hook event payload from stdin, normalizes it, and POSTs to the
 // OpenRig daemon's /api/activity/hooks endpoint for real-time UI seat-status.
@@ -154,6 +159,13 @@ function buildSessionIdentityPayload(providerPayload, env = process.env, now = (
   const sessionName = firstString(env.OPENRIG_SESSION_NAME, env.RIGGED_SESSION_NAME);
   const nodeId = firstString(env.OPENRIG_NODE_ID, env.RIGGED_NODE_ID);
   const runtime = firstString(env.OPENRIG_RUNTIME, env.RIGGED_RUNTIME);
+  const generation = firstString(env.OPENRIG_OCCUPANT_GENERATION, env.RIGGED_OCCUPANT_GENERATION);
+  // How this session began (startup, resume, clear or compact). The daemon tells a resumed
+  // conversation's new id from a /clear by it; it is absent from runtimes that do not report it.
+  const source = firstString(providerPayload.source);
+  // Set only on the command OpenRig sends to resume this seat, so the daemon can tell the process
+  // it launched from another Claude sharing the seat's environment.
+  const resumeLaunch = firstString(env.OPENRIG_RESUME_LAUNCH);
 
   if ((!sessionName && !nodeId) || !runtime) return null;
 
@@ -162,18 +174,45 @@ function buildSessionIdentityPayload(providerPayload, env = process.env, now = (
     sessionName,
     nodeId,
     runtime,
+    generation,
     hookEvent,
+    source,
+    resumeLaunch,
+    // The daemon finds the Claude that ran this hook from its parent chain.
+    hookPid: process.pid,
     sessionId,
     occurredAt: now().toISOString(),
   };
 }
 
+// #1077 — whether this is the first SessionStart of the launch OpenRig armed (OPENRIG_RESUME_LAUNCH
+// for this occupant generation). Recorded on local disk before anything is posted, so a first hook
+// whose post never reaches the daemon still makes every later one (an in-process /resume, a child
+// sharing the environment) report false. Any error reports false.
+function claimFirstLaunchHook(resumeLaunch, generation, dir = path.join(os.tmpdir(), `openrig-resume-launch-${uid()}`)) {
+  if (!resumeLaunch || !generation) return false;
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const key = crypto.createHash("sha256").update(`${generation}\0${resumeLaunch}`).digest("hex");
+    fs.closeSync(fs.openSync(path.join(dir, key), "wx", 0o600));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function uid() {
+  try { return typeof process.getuid === "function" ? String(process.getuid()) : "user"; } catch { return "user"; }
+}
+
 async function main() {
   const providerPayload = parseJson(await readStdin());
   const payload = buildOpenRigPayload(providerPayload);
-  await postHookPayload(payload);
-
   const identityPayload = buildSessionIdentityPayload(providerPayload, process.env);
+  if (identityPayload && identityPayload.resumeLaunch) {
+    identityPayload.resumeLaunchFirst = claimFirstLaunchHook(identityPayload.resumeLaunch, identityPayload.generation);
+  }
+  await postHookPayload(payload);
   if (identityPayload) {
     await postHookPayload(identityPayload);
   }
@@ -185,6 +224,7 @@ if (require.main === module) {
 
 module.exports = {
   buildOpenRigPayload,
+  claimFirstLaunchHook,
   buildSessionIdentityPayload,
   parseJson,
   postHookPayload,

package/daemon/assets/plugins/openrig-core/skills/openrig-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openrig-skills
-description: "Use when you're operating OpenRig and need the right skill or context for fleet recovery, seat handover, new-seat orientation, a watchdog wake, cross-host reach to an agent on another machine, rig packaging, an OpenRig upgrade, systematic debugging, queue triage, or implementation planning; also use when you don't know what applies or nothing is projected on cold boot."
+description: "Use when an agent running inside OpenRig needs the right skill or context for fleet recovery, seat handover, new-seat orientation, a watchdog wake, cross-host reach to an agent on another machine, rig packaging, an OpenRig upgrade, systematic debugging, queue triage, or implementation planning; also when the agent doesn't know what applies or nothing is projected on cold boot. Installing, starting or updating OpenRig, getting back to a team or bringing a stopped one back from a person's own session is the rigs skill."
 allowed-tools: Bash(rig:*)
 metadata:
   openrig:

package/daemon/assets/plugins/openrig-core/skills/openrig-user/SKILL.md

@@ -1302,7 +1302,7 @@ Node-granular managed partial restore (v0.3.4+):
 ### Add a member to an existing pod — v0.3.3+
 
 ```bash
-rig add <rig-id> <pod-namespace> <member-fragment-path> [--json]
+rig add <rig> <pod-namespace> <member-fragment-path> [--json]
 ```
 
 `rig add` is the top-level verb for the `add_member` converge op. It adds a
@@ -1310,6 +1310,12 @@ single member to an existing pod from a YAML/JSON member fragment file. The
 daemon resolves the named pod, validates the member, runs preflight, and
 launches the member in place.
 
+`<rig>` is the rig id or its exact name (the `rigName` that `rig whoami --json`
+reports). A name shared by more than one rig is refused before anything is
+added, with the matching ids listed (`rig_ambiguous` under `--json`). `rig add`
+always targets the local daemon: while a remote host is selected it refuses to
+resolve a name (`remote_host_selected`); an exact local id still works.
+
 HTTP outcomes:
 - `201` — member added; per-node launch state included in the response.
 - `400` — `validation_failed` or `preflight_failed` (the fragment or its launch posture is rejected before any state change).

package/daemon/assets/plugins/openrig-core/skills/refocusing/scripts/trace-to-root.py

@@ -351,7 +351,12 @@ def render_held_and_next(evidence):
             missions = ", ".join(row.get("missions") or [])
             output.append(f"- {row.get('qitemId') or 'a row'} — {row.get('summary') or 'no summary'}"
                           + (f" [mission: {missions}]" if missions else ""))
-    if evidence.get("heldAndNextTruncated"):
+    if "heldTruncated" in evidence or "nextTruncated" in evidence:
+        if evidence.get("heldTruncated"):
+            output.append("(the held list was cut; `rig queue list --owned --state blocked` has the rest)")
+        if evidence.get("nextTruncated"):
+            output.append("(the next list was cut; `rig queue list --owned --state pending` has the rest)")
+    elif evidence.get("heldAndNextTruncated"):
         output.append("(held and next lists were cut; `rig queue list` has the rest)")
     return "\n".join(output)
 

package/daemon/assets/skills/rigs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rigs
-description: Use when the user mentions OpenRig, rigs or the rig command, or wants a team of coding agents (Claude Code, Codex) on their project. That includes installing, setting up, starting or updating OpenRig, seeing or getting back to their OpenRig agents, TUI or operator, starting or sharing a team, and joining this session to one.
+description: Use when a person in their own Claude Code or Codex session mentions OpenRig, rigs or the rig command, or wants a team of coding agents (Claude Code, Codex) on their project. That includes installing, setting up, starting or updating OpenRig, seeing, getting back to or re-attaching to their OpenRig agents (including bringing a stopped team back), TUI or operator, starting or sharing a team, and joining this session to one. Operating a running rig from inside it (fleet recovery, seat handover, watchdog wakes, in-rig upgrades) is the openrig-skills skill.
 ---
 
 # rigs: your route into OpenRig
@@ -68,9 +68,10 @@ guidance in `AGENTS.md` or `CLAUDE.md` plus the team's skills and plugins. Say s
     and ends with `run:` and a command (the `error` field with `--json`). That command already names the installed
     herdr binary and the daemon's socket, or the conversation to attach. Relay it exactly rather than composing one.
     If a note asks you to place the view once Herdr starts, run that `rig terminal open` yourself after they start it.
-  - **If it printed no command:** find `operator.agent` in `rig ps --nodes --rig kernel --json`, take its
-    `canonicalSessionName` (never a guessed name) and give
-    `env -u TMUX tmux attach-session -t '=<canonicalSessionName>'` for the operator's conversation.
+  - **If it printed no command:** find `operator.agent` in
+    `rig ps --nodes --rig kernel --json --fields logicalId,canonicalSessionName,tmuxAttachCommand` and give
+    `env -u TMUX` followed by its `tmuxAttachCommand`, exactly as listed (never a guessed name), for the operator's
+    conversation. That command names the daemon's tmux server when it isn't the default one.
 
   For any other failure, the table under "What can interrupt installation and the OpenRig view" in
   `rig context get reference/getting-started.md#open-the-kernel-conversations` says why and what to do next.
@@ -80,7 +81,8 @@ guidance in `AGENTS.md` or `CLAUDE.md` plus the team's skills and plugins. Say s
   `rig send <canonicalSessionName> 'This is the agent that installed OpenRig. The person will answer in your pane. Goal: <goal>. Project folder: <absolute path>. Branch: <branch>.'`
   Or the person types the goal and folder in the operator's pane. If they give you a goal later, forward it the same
   way. The operator helps them pick a team that fits their logins, starts it on their yes and gives the goal to the
-  team's lead. Show them where the operator answers, and don't build the project yourself.
+  team's lead. Before that yes, it says what launching into their folder changes for their own agent there; relay
+  that with the question. Show them where the operator answers, and don't build the project yourself.
 - **Relay the operator's questions:** the operator asks in its own pane, and the person may not be looking there.
   After each step you hand it, read its screen with `rig capture <canonicalSessionName>`. When it asks the person
   something (start this team? which folder? which option?), ask them here in the operator's words and send their

package/daemon/context-packs/help/manifest.yaml

@@ -1,6 +1,6 @@
 # Agent help: the single troubleshooting and escalation guide (docs/reference/help.md).
 name: help
-version: "0.6.9"
+version: "0.6.11"
 taxonomy: world
 purpose: "What an agent does when its user says OpenRig isn't working: diagnose, fix within permissions, verify, and escalate to OpenRig support."
 files:

package/daemon/context-packs/onboarding-width/manifest.yaml

@@ -1,6 +1,6 @@
 # Public capability and source-map width for the default onboarding walk.
 name: onboarding-width
-version: "0.6.9"
+version: "0.6.11"
 taxonomy: world
 purpose: "The public capability map and source map referenced by the default onboarding walk."
 files:

package/daemon/context-packs/onboarding-width/public-what-you-can-do.md

@@ -11,7 +11,7 @@ not know exists.** So the point of what follows is not skill. It is recognition:
 lands, something rhymes, and you go check instead of building.
 
 Eighty-seven top-level verbs ship (capability canon refreshed through
-`capability-delta-v0.6.9`). This marker describes the pack's teaching, not publication or live
+`capability-delta-v0.6.11`). This marker describes the pack's teaching, not publication or live
 adoption. Read this once for shape, and let it make you suspicious that a thing already exists.
 Model-divergence proclamations are live product (trust them; pins use canonical
 model IDs).
@@ -28,8 +28,9 @@ one command away. Your memory of the fleet is a claim about the past.
 - **`rig ps`** — what rigs exist. **`rig ps --nodes -A`** — the state of every seat everywhere,
   *including the broken ones*. **The bare form is the question you usually want:** `--active`
   filters to running and **hides detached, exited and attention states** — which are exactly the
-  cells you were scanning for. **`rig ps --resources`** shows this host's load and transcript
-  capture cost.
+  cells you were scanning for. A seat whose tmux session is confirmed gone reads `detached`
+  (activity reason `session_missing`), and `rig ps --nodes` says to restore or relaunch it.
+  **`rig ps --resources`** shows this host's load and transcript capture cost.
 - **`rig ps --all-hosts --nodes -A`** — the same across every registered machine. Rollup-only
   unless you ask for nodes.
 - **`rig discover`** — what is running on this box that OpenRig is *not* managing.
@@ -89,6 +90,8 @@ unseen — which makes messages the one delivery channel that never gets skipped
   confirm by effect, never relaunch on it. A send or wake to a seat whose latest hook is a
   question waiting for a person is refused with `target_needs_input`, even when its screen
   can't be read: read it with `rig capture` and get the question answered instead of retrying.
+  `--wait-for-idle N` waits before it takes the seat's delivery lease, so other sends and wakes to
+  that seat aren't held behind it; N is a deadline from the start of the wait.
   Over `--host` to an http-registered host, a send that may have reached the remote reads
   `remote-outcome-unknown` ("Delivery UNCONFIRMED"): check the target with `rig capture <session>
   --host <id>` before any resend. Only a host that was never reached reads as unreachable.
@@ -100,7 +103,9 @@ unseen — which makes messages the one delivery channel that never gets skipped
   the wording wrong on the fourth. **Blast radius is real** — on a large rig this lands in every
   seat's turn.
 - **`rig capture <seat>`** — read what is on their screen right now. **`--rig` / `--pod`** captures
-  every seat in one call.
+  every seat in one call. `--lines N` is the last N lines (stderr says how many earlier lines were
+  cut); `--history-plus-pane` gives the older N history lines plus the whole pane. A short capture
+  doesn't prove a seat is idle.
 - **`rig transcript <seat>`** — what has been *said* in a seat, and **seat-scoped rather than
   session-scoped**: one file spanning every agent generation that has occupied it, so it reaches
   back through handovers. Capped (`transcripts.lines`, default 1000 — raise it for depth), and
@@ -131,7 +136,9 @@ unseen — which makes messages the one delivery channel that never gets skipped
   window, and only then say that clicking macOS's Allow is fine. Herdr is visible only in a
   terminal the person can see; switching the shared TUI to `:terminals` does not open one. Over
   SSH, in CI or with no display, the command returns a definite no-window result with the reason
-  and an attach command: relay that command exactly. Inspect the result and visible content, or
+  and an attach command: relay that command exactly. When the daemon runs on a non-default tmux
+  server, attach commands carry `-L <name>` or `-S <path>`; from inside tmux run them as
+  `env -u TMUX <tmuxAttachCommand>`. Inspect the result and visible content, or
   say what cannot be verified. On a desktop, do not finish by printing a command for the person to
   type. Only if the window cannot open, `rig tui --shared` is the dashboard-only fallback; explain
   the failure. `--provider herdr` or `--provider cmux` adds tiles inside a workspace that is
@@ -177,7 +184,13 @@ your context, your compaction and your replacement — and it is the only thing
 
 - **`rig queue create`** — a row with an owner, a body and a transition history. Its reply, like
   `handoff`'s, confirms the row was saved; the owner is woken after that. Before you say they were
-  told, read the row's transitions (or use `--verify` for a person's request).
+  told, read the row's transitions, or use `--verify`. For a seat it reports the wake's terminal
+  receipt and any claim separately: an unconfirmed receipt is not a failed handoff, and a claim is
+  pickup, not proof the body was read. For a claimed row whose wake wasn't confirmed, `outcome`
+  reads `claimed`; it isn't a failed handoff, so don't re-run the create. For a registered person
+  who is also a seat with a pane, it also waits for the Slack receipt and reports it on its own,
+  up to the 30-second default, even when Slack isn't set up or the row won't be posted. With `output.compact` on (off by default), the queue write commands print a short
+  receipt and `--full` prints the whole row.
 - **`rig queue show`** — what a row *actually says*. The header is not the body.
 - **`rig queue claim` / `unclaim`** — is this mine and running, or still pending where two agents
   might double-work it. Put it down honestly when it is not yours.
@@ -192,13 +205,22 @@ your context, your compaction and your replacement — and it is the only thing
   visible**, with a plain-language summary and a pointer to what a human must judge; `resolve`
   writes their decision onto the durable record and wakes the owner. **Closing it would be a lie
   and sitting on it silently is indistinguishable from a crash.** `--wake-after <duration>` arms
-  one wake for this park episode; a new park supersedes it and every exit route retires it.
+  one wake for this park episode; a new park supersedes it and every exit route retires it. In
+  this release a wake the typing guard holds back (`retained`) is recorded as that one fire and
+  later wakes aren't, so the timer isn't retired: it can wake the owner again at each interval
+  while the row stays parked. A row attached to a shared timer with `--wake-watchdog` loses its
+  one wake if that wake is held back.
 - **`rig queue overdue`** — what was claimed and never closed in time. **Defaults to the current
   rig**; ask for more if you mean more.
 - **`rig queue undelivered`** — pending create-path nudge failures only. For gateway or human
   delivery, the row's transitions are the receipt ledger; `undelivered` does not answer whether a
   person received the escalation. **`overdue` and `undelivered` are the two halves of "is anything
   silently stuck", and a rig can be clean on one and rotten on the other.**
+- **`queue.wake_human_rung`** — when a seat can't be woken, the last escalation step posts to a
+  person. `rig config set queue.wake_human_rung explicit-only` (default `always`) keeps that post
+  for rows addressed to a person (an `@external` address or a registered human); the rest stop at
+  `rig view show escalations`. A seat stuck at a prompt only a person can clear still reaches one,
+  and an unreadable human registry posts everything.
 - **`rig queue inbox-drop` / `inbox-pending` / `inbox-absorb` / `inbox-deny`** — put something in
   front of a seat that it can *refuse*. Mail, not assignment.
 - **`rig queue outbox-record` / `outbox-list`** — what you dispatched, in a record that survives
@@ -343,6 +365,13 @@ not have to tear one down to change it, and you rarely have to start from nothin
   by name, a bundle someone handed you, a GitHub folder link (pinned to one commit), or a stopped
   rig. `rig up` with a pod-aware spec on a stopped team's name replaces that team (the earlier one
   is archived), so check `rig ps --nodes` first. Launch-created `AGENTS.md` or `CLAUDE` files now show in `git status`.
+  `rig up <rig> --existing` puts back the OpenRig guidance blocks `rig down` removed before a
+  resumed seat starts. A seat still missing one makes the rig `partially_restored` (its node lists
+  `guidanceGaps`) and `rig up` exits 1. A seat that wasn't running at the snapshot, but whose
+  earlier session left a resume token, stops at `awaiting-decision` instead of starting fresh, in
+  `rig up --existing` and in `rig launch` (exit 1); the message names the command that starts it
+  fresh on purpose. In a pod-aware rig, a seat is rolled back as unresumable only when its runtime
+  reports the conversation missing.
 - **`rig down`** — stop a rig's seats and take it out of the running set. It ends the agents'
   sessions and any work in progress; don't run it on a live team unless the person asked. In
   human mode it first prints one line with each agent's last known activity, or “unknown”: a
@@ -350,12 +379,24 @@ not have to tear one down to change it, and you rarely have to start from nothin
   that reports errors exits 2.
 - **`rig launch <rigId> [seat]`** — one seat is down; start just that one, without disturbing the
   rest. It takes the rig ID from `rig ps --json`; a rig name gives `rig_not_found`. Add `--plan` to preview it first, locally or with `--host`; a plan is never sent to a
-  daemon older than 0.5.9, which would ignore it and launch.
+  daemon older than 0.5.9, which would ignore it and launch. A seat whose agent exited to a shell in
+  its kept pane reads `attention_required` (exit 1), not already running: resume it, or
+  `rig seat launch <session> --fresh --stop`.
 - **`rig seat launch <seat> --fresh --reason <why>`** — deliberately create a blank occupant for
   exactly one existing seat. It uses no resume, fork, rebuild, snapshot, or restore packet;
-  siblings and durable work stay put, and unmanaged ambiguity refuses.
+  siblings and durable work stay put, and unmanaged ambiguity refuses. With `--stop`, a seat with a
+  still-live older session is refused before anything is stopped; `--plan` previews it.
+- **`rig seat restart <seat> --keep-conversation --reason <why>`** — restart one Codex seat in its
+  own pane on the same conversation, so it starts again on whatever account its Codex home now
+  holds; it doesn't switch accounts itself. It refuses with nothing stopped unless the seat is a
+  Codex seat OpenRig launched, in a single pane, with a conversation it can prove and unchanged
+  running settings. `--plan` runs every check and stops nothing; `--verify --expect-account
+  <account>` reports `moved` only when a tool turn has completed in the same conversation since
+  the restart and Codex's status names that account. Linux only: on macOS a
+  request that reaches the running-process check refuses before stopping the seat.
 - **`rig add`** / **`rig expand`** — graft one more member, or a whole new pod, onto a rig that is
-  already running. `rig grow --new-pod` and `rig expand` are one ingress; choose by input shape.
+  already running. `rig add` takes the rig's name or ID; a name two active rigs share is refused
+  with `rig_ambiguous` and the candidates. `rig grow --new-pod` and `rig expand` are one ingress; choose by input shape.
 - **`rig remove`** / **`rig shrink`** — take a seat, or an entire pod, out of a running topology.
   If it holds active work, pass `--fallback <live-seat>` to reroute before mutation; without a
   valid fallback the command refuses rather than strand the rows.
@@ -460,7 +501,8 @@ version, from checking the environment to a useful report to the OpenRig team.
   updating Codex is the operator's job.
 - **`rig seat set-model` / `stop` / `clean`** — persist the model for later managed resumes, stop
   exactly one live seat (ending its session and any work in progress), or clear a dead seat's
-  stale binding. When the topology is right and only
+  stale binding. A stop is recorded, so the rig doesn't read `degraded` for that seat, and a rig
+  whose seats were all stopped this way reads `stopped`. When the topology is right and only
   the occupant is wrong, use these seat lifecycle verbs or `rig handover`, not a rig down/up cycle.
   Effective-model detection follows the identity-verified current occupant, not a retained
   predecessor; a `<synthetic>` transcript record is skipped, so a PENDING model check is not a
@@ -548,7 +590,8 @@ scheme, and nothing downstream can see it.
   source actually bound. When someone later asks where the contract items came from, the drop's
   own echo is the answer — not a re-read of the files.
 - **`rig proof judge` / `rig proof show`** — record an attributed judgment on a contract item once,
-  then read derived proof, slice, mission and project readiness. The owning scope selects
+  then read derived proof, slice, mission and project readiness. Both take `--project <id>` or a
+  `<project>:` scope prefix. The owning scope selects
   `proofPolicy.judges` (nearest slice, mission or project policy wins); consult `rig proof --help`
   for that setup and the item/evidence selectors. Accept, reject or withdraw against readable
   evidence; corrections preserve history and unrelated judgments without ancestor status edits.
@@ -774,7 +817,11 @@ your circumstances is configuration, and the ones that are not, another agent ca
 - **`rig provider accounts` / `bindings` / `signals` / `switch`** — which seats are bound to which
   accounts, what the usage signals say, and whether a seat can be moved without stranding the
   conversation it is in the middle of. **`provider signals` reports anomalies rather than a
-  listing** — unbound seats, accounts shared across several seats.
+  listing** — unbound seats, accounts shared across several seats. A Codex seat showing its
+  usage-limit banner reads activity `unknown` with reason `usage_limit`, and keeps it while its
+  screen redraws; `provider signals` can show a provider-event signal for that seat's account that
+  allows a switch decision. With `provider.usage_windows` on (off by default), `rig provider status
+  --refresh` reads a Codex login's usage windows once.
 - **Codex configuration fragments** — a `codex_config_fragment` must open with a table header and
   never overrides a user-declared table; see `docs/reference/agent-spec.md`.
 - **`rig env`** — the real services behind a rig: are they up, what are they saying, how do you
@@ -782,7 +829,8 @@ your circumstances is configuration, and the ones that are not, another agent ca
 - **`rig setup`** — what OpenRig would change about this machine, shown before it touches anything.
   It installs herdr by default on macOS and Linux (`--no-herdr` declines; if the install fails,
   views fall back to plain tmux) and on a Mac offers Ghostty once (`--ghostty` / `--no-ghostty`).
-  It no longer installs cmux; an existing cmux still works.
+  It no longer installs cmux; an existing cmux still works. `--providers claude`, `codex` or
+  `both` sets which harnesses it installs and checks; one not chosen reads `skipped`, never failed.
 - **`rig usage series`** — what a seat's token curve has looked like over time: climbing steadily,
   reset, or stopped reporting entirely. The last one is a signal, not a gap.
 - **`rig tui`** — the interactive view over rigs, pods, seats and specs. `rig` and `rig tui` open
@@ -868,6 +916,8 @@ database. It is one more set of primitives on a machine full of them.
 - **"Did that actually land?"** — `rig queue show <qitemId>` gives a bounded preview,
   original byte size and the exact expansion command. Read the complete original record with
   `rig queue show <qitemId> --full --json`; a preview or a compact list is not the whole body.
+  Compact `rig queue list` rows carry `summary`; the fields they leave out are absent, not empty,
+  and `fieldsElided` names them.
   Delivery status is separate from content: inspect its receipt before claiming it was consumed.
 - **"What am I waiting on?"** — the queue row's `waiting` view derives its owner, exact blocker
   and blocker owner, last meaningful change, activity confidence and next backstop from live

package/daemon/context-packs/reference/getting-started.md

@@ -137,7 +137,9 @@ The other provider's CLI/login is optional. Herdr is installed by default unless
 you decline it; cmux remains optional. Do not copy credentials
 or start repeated sign-in attempts. Recheck the selected login after the user
 completes it. `rig setup --dry-run` previews the broader setup; applying
-`rig setup` checks **both** harnesses and installs a missing one with npm; on
+`rig setup` checks **both** harnesses and installs a missing one with npm, unless
+you pass the person's choice: `rig setup --providers claude` (or `codex`) leaves
+the other out, so it reads not selected instead of failed. On
 macOS it uses an existing Homebrew (it does not install Homebrew) to install a
 missing tmux (elsewhere tmux is checked, not installed). Herdr installs on
 macOS and Linux; pass `--no-herdr` to decline it. Setup also
@@ -198,7 +200,7 @@ leaves existing cmux settings alone and does not open a view during setup.
 
 On a Mac, the installing agent also asks once, "Install Ghostty for the OpenRig
 view?" On Yes it reruns setup with `--ghostty`, preserving earlier choices such
-as `--no-herdr`. This installs the
+as `--no-herdr` and `--providers`. This installs the
 [documented Homebrew cask](https://ghostty.org/docs/install/binary) and checks for
 the app. On No it uses `--no-ghostty`; Terminal.app remains available. Plain setup
 reports this offer without installing Ghostty or waiting for input. The person
@@ -331,17 +333,19 @@ For the first desktop handoff, use `--window`. Only if the window cannot open,
 For an explicitly requested manual attachment, inspect the current bindings:
 
 ```sh
-rig ps --nodes --rig kernel --json
+rig ps --nodes --rig kernel --json --fields logicalId,canonicalSessionName,tmuxAttachCommand
 ```
 
-Find `logicalId: operator.agent` and use its `canonicalSessionName` in a new
+Find `logicalId: operator.agent` and run its `tmuxAttachCommand`, after `env -u TMUX`, in a new
 terminal on the same host and account:
 
 ```sh
-env -u TMUX tmux attach-session -t '=<canonicalSessionName>'
+env -u TMUX <tmuxAttachCommand>
 ```
 
-The installing agent fills in the actual session name. This optional manual route
+When the daemon was started inside tmux on a non-default socket, its sessions live on that
+server, and `tmuxAttachCommand` names it (`tmux -L <name> …` or `tmux -S <path> …`). The installing
+agent fills in the actual command. This optional manual route
 is separate from the first-install desktop action above.
 
 ### Plain terminal: a new viewing session

package/daemon/context-packs/reference/manifest.yaml

@@ -1,7 +1,7 @@
 # Reference guides the help pack links to, loaded one file or section at a time by address
 # (rig context get reference/<file>#<section>). Each file is a symlink to docs/reference/.
 name: reference
-version: "0.6.9"
+version: "0.6.11"
 taxonomy: world
 purpose: "Version-matched reference guides the help guide links to. Load a single file or section by address; don't load the whole pack."
 files:

package/daemon/context-packs/reference/rig-spec.md

@@ -397,7 +397,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 | `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
 | `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
 | `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `pi`, `omp`, `terminal`, `stub`. `stub` is a deterministic test harness, not an agent: a Node runner in the seat's tmux pane goes through the normal launch, skill projection, startup-file and readiness path, follows `<cwd>/.openrig/stub/script.json` when present, and calls no model. See "What a stub can and cannot prove" in `docs/as-built/test-layers.md`. |
-| `cwd` | string | yes | — | Working directory for the agent. A relative path resolves against the rig root (the directory containing the rig spec); an absolute path is used as is. Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. A cwd inside the OpenRig installation fails preflight unless `--cwd` is given. |
+| `cwd` | string | yes | — | Working directory for the agent. A relative path resolves against the rig root (the directory containing the rig spec). If that path exists as written, it is used. Otherwise a leading `~` or `~/` expands to the home directory (`~user` does not) and `$VAR` / `${VAR}` expand from the daemon host's environment; a relative result still resolves against the rig root. A reference to an unset variable stays as written, so the cwd is that literal path and works only if it exists. Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. A cwd inside the OpenRig installation fails preflight unless `--cwd` is given. |
 | `label` | string | no | — | Human-readable member name. Shown in UI when present. |
 | `model` | string | no | — | Model override. Runtime-specific (e.g., `claude-opus-4-6` for Claude Code). |
 | `effort` | string | no | — | Reasoning effort override, trimmed. A non-string value is ignored with an advisory. |
@@ -406,7 +406,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 | `restore_policy` | string | no | the AgentSpec's | Restore behavior. One of: `resume_if_possible`, `relaunch_fresh`, `checkpoint_only`. The default comes from the AgentSpec's `defaults.lifecycle` (else `resume_if_possible`) as narrowed by its profile; a member value may only narrow it further, in that order. |
 | `compaction_strategy` | string | no | — | `default-compaction`, `managed-compaction`, `handover` or `apprentice-handover`; `harness_native` and `pod_continuity` are accepted as deprecated aliases, and `custom_prompt` is refused. |
 | `mechanic` | string | no | — | A canonical `seat@rig` session address, for `apprentice-handover`. |
-| `session_source` | object | no | — | Start the seat from an existing session: `fork` with `native_id`, `rebuild` with `artifact_set`, or `agent_image` with `image_name`. Not valid on terminal members. |
+| `session_source` | object | no | — | Start the seat from an existing session: `fork` with `native_id`, `rebuild` with `artifact_set`, or `agent_image` with `image_name`. A Claude Code `fork` needs Claude Code 2.0.73 or later. Not valid on terminal members. |
 | `starter_ref` | object | no | — | `{ name }` of an agent starter (`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`) whose files lead the seat's startup. Not valid on terminal members or with a fork. |
 | `startup` | StartupBlock | no | — | Member-level startup files and actions. Applied only to this member. |