@openrig/cli 0.6.14 → 0.7.1

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/scripts/precompact-hook.mjs

@@ -265,7 +265,7 @@ try {
 
   const customMessage = readClaudeCompactionMessage();
 
-  const result = spawnSync("node", args, { encoding: "utf8" });
+  const result = spawnSync(process.execPath, args, { encoding: "utf8" });
   if (result.status !== 0) {
     const baseFailure = `Claude compaction restore packet generation failed: ${(result.stderr || result.stdout || "unknown error").trim()}. After compaction, load the claude-compaction-restore skill and run restore-from-jsonl manually.`;
     emit({

package/daemon/assets/plugins/openrig-core/skills/forming-an-openrig-mental-model/SKILL.md

@@ -163,9 +163,12 @@ cost when you reach for one.
 ### Where skills come from in OpenRig
 
 - **Per-agent loadout:** your AgentSpec's `profile.uses.skills: [...]`
-  determines what skills get projected into your runtime skill folder
-  (`.claude/skills/` or `.agents/skills/`) before your harness boots. This
-  is the **structural composition** layer.
+  determines what skills get projected into your seat's own skill storage
+  before your harness boots. A Claude seat gets them through OpenRig's
+  generated plugin, named `openrig:<id>`; a Codex seat through its skill
+  catalog. A seat without that storage gets them in the project's
+  `.claude/skills/` or `.agents/skills/`. This is the **structural
+  composition** layer.
 - **Cross-pod sharing:** AgentSpecs can `imports: [shared]` to access a
   shared skill pool. Built-in agents commonly do this.
 - **Belt-and-suspenders:** the spec projects skill files; startup guidance
@@ -176,7 +179,8 @@ cost when you reach for one.
 
 | Home | Purpose |
 |---|---|
-| `<rig-cwd>/.claude/skills/`, `<rig-cwd>/.agents/skills/` | Where the harness actually loads from. Populated by `rig up`. |
+| `<OpenRig home>/state/seats/<rig id>/<logical seat>/<runtime>/` | A team seat's own skills, outside the project. Claude loads them through the generated plugin (`plugin/skills/`); Codex reads them by path from the seat's `catalog.md` (`skills/`). Populated at launch. |
+| `<rig-cwd>/.claude/skills/`, `<rig-cwd>/.agents/skills/` | The project's own skills, which the harness also loads. A seat without its own storage gets its skills here. |
 | `~/.claude/skills/`, `~/.agents/skills/` | User-level harness skill directories. Inspect the current projection and harness configuration to determine which skills are installed and where they came from. |
 | `packages/daemon/{specs/agents/shared/skills,assets/plugins/*/skills}/` (source checkout) | Product skills that ship with OpenRig — the spec pool + the bundled plugin assets (openrig-user, openrig-architect, forming-an-openrig-mental-model, queue-handoff, claude-compaction-restore, …). |
 | the skills authoring workspace | Skill authoring source (not runtime-loaded). |
@@ -239,11 +243,13 @@ If you're booting into a new seat in an OpenRig rig:
    `guidance/role.md` for your specific seat.
 3. **Read the rig's `CULTURE.md`** if it has one — the team operating
    manual.
-4. **Check what skills you have** — list `.claude/skills/` or
-   `.agents/skills/` in your cwd. Each skill has a frontmatter description
-   that tells you when to reach for it.
-5. **Check your peers** — `rig capture <peer-session>` to see what they're
-   doing.
+4. **Check what skills you have** — `rig skill loadout --seat self` shows
+   your seat's own skills; `.claude/skills/` or `.agents/skills/` in your
+   cwd hold the project's. Each skill has a frontmatter description that
+   tells you when to reach for it.
+5. **Check your peers** — `rig ps --nodes` and the queue first (who is up,
+   who holds what). Capture a peer (`rig capture <peer-session>`) only when
+   you actually need to see its screen.
 6. **Check the transcripts** if you're returning to an in-flight workstream
    — `rig transcript <session> --tail 100` for recent context.
 7. **Ask `rig ask <rig> "<question>"`** if you need cross-cutting evidence
@@ -301,7 +307,7 @@ that fit your actual work.
 | "I should manage Codex's compaction the way I manage Claude's" | No. Codex auto-compacts cleanly; Claude doesn't. Different runtimes, different lifecycles. |
 | "MEMORY.md auto-loads, so I don't need to read it" | Maybe. Sometimes MEMORY.md auto-loads via system reminders; sometimes not. Don't assume. If your work touches the topics it covers, read it explicitly. |
 | "Skills inherit from a parent or compose like classes" | No. Skills are flat artifacts; composition happens via AgentSpec `profile.uses.skills` (structural) or soft cross-references in skill bodies (advisory). Not via OO-style inheritance. |
-| "The substrate `shared-docs/skills/` folder is the canonical runtime path" | No. The harness doesn't read there. It's an authoring workspace. Runtime loads from `.claude/skills/`, `.agents/skills/`, and product built-in. |
+| "The substrate `shared-docs/skills/` folder is the canonical runtime path" | No. The harness doesn't read there. It's an authoring workspace. Runtime loads from the seat's own skill storage, `.claude/skills/`, `.agents/skills/`, and product built-in. |
 
 ---
 

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

@@ -5,6 +5,8 @@ metadata:
   cli_surfaces_referenced:
     - gateway human list
     - gateway human show
+    - gateway human mode room
+    - gateway human mode decide
     - queue create
     - queue transitions
     - queue block
@@ -69,6 +71,42 @@ rig queue create --destination <entityId>@external \
   --evidence-ref <durable-evidence> --verify --json
 ```
 
+An ask is on Steering and the TUI, where the person can answer it, choosing an
+option or typing a reply; it comes back to you exactly as a Slack answer does.
+Whether it also posts to Slack is the person's Slack subscription (`rig gateway
+human show <id>`, `slack-subscription`): by default (`every-ask`) every ask
+posts, and with `urgent-only` only an ask marked `--alert` does. So forgetting
+`--alert` never hides an ask from someone who reads Slack.
+
+Add `--alert` when the ask is urgent: something only they can do, or an approval
+whose wait costs now. A sign-in, a credential or an approval that expires needs
+it; a question that can wait for their next look doesn't. An alerted ask stands
+out in Slack (an interrupt with a mention, within their quiet hours and
+availability), and it's the only kind that reaches someone on `urgent-only`.
+An update (`--human-intent update`) posts as before and takes no `--alert`.
+
+Before asking a **decision**, check whether the person has a mode on with a
+decision room: what they said the team may decide for them meanwhile.
+
+```bash
+rig gateway human mode room <entityId>
+```
+
+If it names a room and your decision is plainly inside their words (and none of
+their exclusions), decide instead of waiting. Create the ask as above, then
+record your choice on it straight away:
+
+```bash
+rig gateway human mode decide <qitem-id> --application <applicationId> \
+  --choose <question>=<option> --reason "<why>" --reversible   # or --irreversible
+```
+
+It's recorded as decided on their behalf, never as their answer, the ask
+closes, and it's in their account when they're back. Say honestly whether it
+can be undone. A permission prompt or an approval is never decided this way.
+With no room, a room that doesn't plainly cover it, or any doubt, ask and wait;
+a recommended option is not a decision.
+
 An optional `--human-detail-file <path>` supplies one coherent supplemental
 reply in the same thread. Announce its purpose in the brief; the product also
 marks that a detail reply follows. The primary must already contain the complete
@@ -101,8 +139,8 @@ posts as a new message.
 A **decision** with a few clear choices can carry `--human-questions-file <path>`:
 a JSON array of 1–4 questions, each
 `{"id", "question", "options": [{"id", "label", "recommended"?}]}` with 2–4
-options (labels up to 75 characters, at most one recommended). Slack shows each
-question as a row of buttons. Each click records that answer on the item, and
+options (labels up to 75 characters, at most one recommended). The TUI lists
+each question with its options, and Slack (when alerted) shows each as a row of buttons. Each click records that answer on the item, and
 the decision resolves once every question has one. You then receive one reply
 row listing the answers. In `humanAnswers`, clicked answers are option-id strings.
 A whole typed reply is an object:
@@ -124,8 +162,9 @@ well would issue another notification for the same decision.
 
 The row persists before bounded delivery verification. Read its qitem ID and
 verification result; `posted` proves connector posting, **not human readership**.
-`transport-failed`, `never-posted`, or a pending/indeterminate result leaves the
-row intact. Inspect that same row and its next action; never create a second row
+`not-alerted` means the person's Slack subscription is `urgent-only`, so the ask is
+on Steering and the TUI without a Slack post, as they chose; it isn't a failure. `transport-failed`, `never-posted`, or a pending/indeterminate result
+leaves the row intact. Inspect that same row and its next action; never create a second row
 or blindly resend because verification timed out.
 
 ```bash

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

@@ -91,7 +91,7 @@ These ship in the OpenRig repo and reach a seat when its profile selects them. T
 Pod handbooks (load when you're in that pod):
 - **orchestration-team** — you're orchestrating a rig: dispatching, monitoring, keeping the loop moving.
 - **development-team** — you're on the dev pod: building and shipping product changes.
-- **review-team** — you're reviewing: fresh scrutiny, anti-slop, empirical verification.
+- **review-team** — you're reviewing: fresh scrutiny, anti-slop, grounded findings.
 - **oversight-team** — you're in an oversight pod: monitor boundaries and route findings without taking over the work.
 
 Product-management craft (load when shaping/reviewing work):
@@ -106,7 +106,7 @@ Product-management craft (load when shaping/reviewing work):
 ### Vendored craft — load when you're coding (ships with upstream provenance)
 General engineering skills OpenRig ships as vendored copies. Open when the task matches; they carry "modified by OpenRig" provenance.
 
-- **verification-before-completion** — about to claim done / passing / fixed: run the check and read the output first.
+- **verification-before-completion** — about to claim done / passing / fixed: have evidence that applies to the candidate you name first.
 - **systematic-debugging** — debugging: find the root cause before the fix.
 - **agent-browser** — driving a browser (screenshot / screencast) from an agent.
 - **frontend-design** — designing frontend / UI.

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

@@ -90,6 +90,23 @@ rig queue handoff <qitem-id> \
   --body-file /tmp/import-report-handoff.md
 ```
 
+### After a queue write — use the response; read back only when it doesn't show what you need
+
+A queue write (`create`, `claim`, `update`, `handoff`, `handoff-and-complete`) answers with the row it wrote; a
+handoff answers with the closed row and its successor. When that answer shows what you need to establish, use it.
+Read back (`rig queue show <id> --full --json`, or `rig queue transitions <id>`) when it doesn't, for example:
+
+- the outcome was INDETERMINATE (a transport failure, or a 502 `remote_queue_write_failed`), or the write warned
+  `qitem_body_not_saved` (an existing row came back). Reconcile by the original ID before any retry;
+- the output was compact or truncated and the field you need isn't in it (the compact receipt shows `bodyBytes`, not
+  the body, and its footer names what it left out);
+- you need a transition note, a closure or blocker detail, or a successor that the output you saw omits;
+- you need evidence from downstream of the write: the recipient's wake (`create --verify` waits for it), or its
+  pickup or claim (a later read);
+- your team's custody rule asks for a separate read-back.
+
+Don't read back only to see again a field the response already showed you.
+
 ### §1b doctrine — turn ends by passing the ball
 
 **A turn ends by passing the ball, never by going idle holding the slice waiting
@@ -440,6 +457,16 @@ clear updates the current binding and identity verdict without a clear event.
 Acknowledgment or responsiveness alone does not prove that the original
 conversation resumed.
 
+Two startup cases also end in `attention_required`, and the result says what to do:
+- **Assisted startup** (a community harness preset with `startup_assisted: true`): the startup text and Enter were
+  sent but submission isn't confirmed. Check the pane and submit any staged text, don't resend it, then run the
+  reported `rig seat clear-attention <session> --reason "..."` once the seat has responded.
+- **A refused startup turn** (Claude answered a startup turn with a refusal such as an expired login): nothing more is
+  typed into the seat, and the result names how many later startup inputs weren't sent. A fresh start that ran no
+  one-shot action stays continuable: `rig seat continue <seat>` delivers the whole startup again, the refused turn
+  included. A resumed or forked seat keeps its conversation and isn't offered continue; a fresh start that can't
+  continue names `rig seat launch <seat> --fresh --stop --reason "<why>"`.
+
 A 422 response names the uncleared class and its failed check. If the recorded
 native token needs correction and you know the actual token, use
 `rig seat set-resume-token <session> --token-stdin --reason <explanation>`, then
@@ -801,12 +828,15 @@ rig send <session> "message" --host <id>
 rig send <session> "message" --json
 ```
 
-**The send-guard (v0.4.0) — the default is SAFE.** A default `rig send` is guarded: it will NOT submit into an interactive prompt / permission block on the target pane. Flags:
+**The send-guard (v0.4.0) — the default is SAFE.** A default `rig send` is guarded: it will NOT submit into an interactive prompt / permission block on the target pane. That includes Claude's MCP server approval menu (`N new MCP servers found in .mcp.json`, ending `Space to select · Enter to confirm · Esc to reject all`) while it is the current screen: the send is refused with reason `target_needs_input` and `Refused: '<session>' is at an interactive prompt (selection_prompt). A message must not select or approve it. … No text was sent.` Approving or rejecting those servers is the person's call; `--dangerously-interact` drives it only deliberately. Flags:
 - `--verify` — delivery evidence.
 - `--force` — **a back-compat no-op on the send DECISION**: it never bypasses the interactive-prompt/permission guard and never changes whether a message is delivered (a mid-task/busy pane already sends-with-advisory by default). *(It does NOT "bypass activity-risk checks" — that earlier teaching is retired.)* It is **not fully inert**, though — it is still parsed solely to be **rejected in combination with `--wait-for-idle`**: `rig send … --force --wait-for-idle <n>` prints `--wait-for-idle cannot be combined with --force`, exits 1, and sends nothing. So do not read "no-op" as "`--force --wait-for-idle` is harmless"; that pairing errors. *(Verified against current product main `d37a08ad`: the guard-bypass no-op is declared at `send.ts` and confirmed by runtime capture — a plain `--force` send delivers through the ordinary path; the `--wait-for-idle` rejection is enforced at `send.ts`, `routes/transport.ts`, and `session-transport.ts`, and confirmed by runtime capture — exit 1, nothing sent.)*
 - `--wait-for-idle <seconds>` — wait until the target is explicitly idle before sending. **Cannot be combined with `--force`** (that pairing is rejected: exit 1, nothing sent).
 - `--raw` — send exact text/keystrokes without the From/To messaging envelope (still guarded against interactive prompts).
 - `--dangerously-interact --reason "<why>"` — the ONLY override of the prompt/permission guard: deliberately drive an interactive prompt/permission block (implies `--raw`, requires `--reason`, audit-logged).
+  On a guard-attached managed seat, a non-menu override stops and shows existing typed/pasted input (author unknown) with `override_input_present`; unreadable input stops with `override_input_unknown`. Recognized dim suggestions are shown separately and count as empty; a collapsed paste shows only its label, not hidden contents.
+  Inspect the input, deliberately clear the native prompt with native/tmux controls, then retry. Manual clearing is outside OpenRig's lease and observation checks and is not recorded; human typing can still race a read and paste.
+  When you deliberately need to type without that composer check (for example an unsupported input you inspected yourself), add `--type-without-checking` with `--dangerously-interact --reason "<why>"`. It does not clear input and may join or submit existing text. Ordinary sends and wakes keep their current rules.
 - `--host <id>` — send on a remote host declared in `~/.openrig/hosts.yaml` (ssh hosts shell out; http hosts go CLI-direct to the remote daemon).
 - `--from <session>` — deprecated and ignored; it does not select the sender. Sender identity comes from the current seat and transport provenance; cross-host envelopes use the durable local origin, not the supplied flag or a relay identity.
 - `--context <ref>` **(0.5.0)** — attach a composed context pack/piece by ref (see "Context packs and paced delivery"). Small piece → `send --context`; a real pack → `rig walk`. The noun `rig context` composes the ref; the verb delivers it.
@@ -956,12 +986,7 @@ rig auth seats … --runtime codex         # seat -> profile registry (metadata
 
 ### Manage subscriptions across a fleet (when the person asks you to)
 
-**This applies only when both hold:**
-- the daemon's `provider.subscription_moves` setting is on. It's off by default; the person turns it on with
-  `rig config set provider.subscription_moves true`;
-- the person has asked you to manage their subscriptions.
-
-Otherwise, don't take this job on. Installing or upgrading OpenRig appoints no agent, launches no bundle and starts no
+**This applies only when the person has asked you to manage their subscriptions.** Otherwise, don't take this job on. Installing or upgrading OpenRig appoints no agent, launches no bundle and starts no
 rotation.
 
 When a person runs several Claude and Codex subscriptions across machines, the fleet studio bundle's one agent is meant
@@ -969,63 +994,92 @@ to keep work running, through the Fleet app. Until that bundle is available, the
 subscriptions can use this section. If that's you, you decide which subscription or home moves, and when. You decide
 from:
 - the usage and assignment readings, and their freshness;
-- the move record;
-- the person's standing preferences.
+- your earlier move reports (`rig provider moves`);
+- the person's account policy, or their standing preferences when there's no policy.
 
 You say why, and you see the outcome through. OpenRig gives you the facts and the tools; it never decides for you,
 and there's no threshold to obey.
 
 **Who decides:**
-- **The person's operator agent** can ask you for a move, or look at the record. It doesn't make competing moves of
+- **The person's operator agent** can ask you for a move, or ask what you've moved. It doesn't make competing moves of
   its own.
 - **One agent manages subscriptions:** the one the person asked, or the fleet studio's agent once that bundle is
   available. There's no other fleet-manager role and no automatic manager. Use the commands below directly; no extra
   hand-off is needed.
-- **The Observatory is optional:** it can show your moves and readings, but you don't need it to rotate.
+- **The Observatory is optional:** it can show readings, but you don't need it to rotate.
 
 **The unit is a Codex home, with every seat on it.** Moving some seats on a shared home to a different account, and
 moving Claude seats, aren't supported moves yet: say so instead of improvising.
 
+0. **Load the person's account policy.**
+   - It's the context pack named `account-policy`: check `rig context list` for it, then read it with
+     `rig context get account-policy`. Its manifest's `version` is the version you follow and report.
+   - Follow it, and record the version in each report. A line the person approved ("move the build box's seats without
+     asking", "never move the reviewers") is standing authorization: act on it, don't ask again.
+   - A line grants only what the person actually gave. "Agents may do sign-ins" is usable only where a sign-in route
+     and access already exist; otherwise ask, and record that the preference couldn't be used.
+   - Something the policy doesn't cover: use your judgment or ask the way the policy says, record why, and propose a
+     one-line addition.
+   - **No policy** is never a reason to stop: work from this section, report the policy as `{ "none": true }`, and
+     offer once to write one with them (below).
 1. **Know the subscriptions.**
    - Each subscription is reached through a saved profile on a home (`rig auth list` and `rig auth save`) on each
      machine. Which seats use which profile is `rig auth seats`, and that's metadata: not proof of a live account.
    - Check you can read each subscription's usage, and name any you can't.
 2. **Read before deciding.**
    - Use `rig provider status --all-hosts --json` (add `--refresh` for fresh native readings). Each allowance has
-     its windows, reset times and when it was observed.
+     its windows, reset times and when it was observed, and when it was last observed exhausted.
    - **One allowance seen on two machines is one allowance:** never add its headroom twice.
    - **A stale reading** is usable only with its age recorded, or after a refresh.
-   - **An unknown or unavailable reading is never room.**
+   - **An unknown or unavailable reading is never observed room.**
+   - **After a known reset,** a window carries an `expectation` (expected full since that reset). You may plan on it,
+     but it isn't measured: report it as expected, and take a fresh reading when you can.
    - **Equal reset times don't mean the same account.**
    - **A seat's link to a subscription is observed, configured or unknown.** Only an observed link shows the seat
      actually uses it; a configured one (a profile, a registry row) is a claim.
+   - **A sign-in state of `unknown` isn't `needs_sign_in`.** An otherwise authorized move can go ahead, and its uptake
+     evidence settles it. A known `needs_sign_in` is step 6.
 3. **Decide, and leave seats alone for a reason.**
+   - **Balance, don't chase:** spread machines across the subscriptions with room rather than moving every machine onto
+     the one that just reset. `rig usage top` on each machine shows which work hardest: a high-use machine is worth a
+     subscription of its own, and lower-use machines can share one. Keep a backup where the policy says so.
    - `rig seat restart <seat> --keep-conversation --plan` shows what a restart keeps, and every peer on the same
      home. Moving the home moves them all.
    - Skip a seat that's mid-turn, running a service, or about to finish, and record why.
-   - The person's standing preferences ("never move the reviewers") are yours to follow and record.
 4. **Move the home.**
-   - On that machine, `CODEX_HOME=<that home> rig auth switch <profile> --runtime codex`. `rig auth` acts on
-     `CODEX_HOME`, or on the default home, and `rig auth status` prints which home it means: check it before
-     switching.
-   - Then restart each chosen seat: `rig seat restart <seat> --keep-conversation --reason "<why>"`.
+   - `rig auth switch <profile> --runtime codex --codex-home <that home>`, on that machine, or from here with
+     `--host <that machine's SSH entry>`. Without `--codex-home`, `rig auth` acts on `CODEX_HOME`, or on the default
+     home; `rig auth status --codex-home <home>` (with `--host` for another machine) prints which home it means:
+     check it before switching. A remote switch always names its home, and copies a profile already saved there.
+   - **Another machine** is reached through its SSH entry in `rig host list`. An entry registered only over HTTP
+     can't run these commands; use the machine's SSH entry, or run them on that machine.
+   - Then restart each chosen seat: `rig seat restart <seat> --keep-conversation --reason "<why>"`, with `--host <id>`
+     for a seat on another machine (the restart runs there, and its audit names you). If the connection drops, the
+     answer is `remote-outcome-unknown`: the switch or restart may have run there, so read what it names (for a
+     restart, `--plan`'s `lastRestart`) before anything else.
    - After it completes a real tool-using turn, check it: `rig seat restart <seat> --keep-conversation --verify
      --expect-account <the target's Account line>`. `--verify` only checks; it never restarts. Only that check
      reports `moved`, and anything less is unconfirmed.
    - **A slow reply isn't a failure:** never restart a seat a second time. Follow up at your next look.
-5. **Record every move, partial or unconfirmed included,** with `rig provider moves record --file <move.json>`
-   (`--help` shows the shape):
-   - the home and machine;
-   - from and to, as labels;
-   - your reason;
-   - each reading you acted on, with its observation time;
-   - each seat's result (`moved`, `unconfirmed` or `unknown`) with its evidence or what's missing;
+5. **Report every move, partial or unconfirmed included,** with
+   `rig provider moves report --file <move.json> --to <whoever asked>` (`--help` shows the shape). It becomes a queue
+   item to them; the Fleet app reads these reports once its page is connected to them. It holds:
+   - the home and machine, and from and to, as labels;
+   - your reason, and the policy version you followed (or `{ "none": true }`);
+   - each reading you acted on, `observed` with its observation time, `expected` with the reset it rests on, or
+     `unavailable`;
+   - each seat's result: `moved` only with the verify check's matched account and observed tool turn, kept as separate
+     facts; otherwise `unconfirmed` or `unknown`, with what's missing;
    - the peers, for example "not restarted; account unverified".
 
-   A seat marked `moved` needs its `evidence`, and an `unconfirmed` or `unknown` one needs what's `missing`. A home
-   switched with every seat left as a peer is still a move to record, with `seats: []`. A follow-up that confirms an
-   earlier unconfirmed seat records a new move with `supersedes`. Asked "why did this
-   seat move?", answer from `rig provider moves --seat <seat>`. Never put credentials in a record.
+   A home switched with every seat left as a peer is still a move to report. A follow-up that confirms an earlier
+   unconfirmed seat is a new report with `--follows <the earlier report's qitemId>`. A report to a person's seat names
+   its evidence with `--evidence-ref` (for example, the saved `--verify --json` output). Never put credentials in a
+   report: a value in a recognized credential format is refused. **A refused report changes nothing about the move:**
+   correct it and file it again; never repeat the switch or a restart because a report was refused. Asked "why did
+   these seats move?", even after your own restart, answer from `rig provider moves --seat <seat>`. It reads the newest
+   reports (50 by default, `--limit` up to 200) and then filters them, so it's a recent window, not a seat's whole
+   history: raise `--limit` when you need older ones.
 6. **When a sign-in is needed:**
    - Ask the person once, durably: a queue item to their seat, naming the machine and the subscription.
    - Move nothing onto that subscription until it's done.
@@ -1036,6 +1090,41 @@ moving Claude seats, aren't supported moves yet: say so instead of improvising.
 **What wakes you:** a watchdog, a usage-limit park on the queue, or the person asking. How often you look is your
 judgment within those.
 
+**If there's no policy yet.** Start from what you can see, and ask only what you can't; keep it to a few minutes, and
+never run it as a form. "Whatever you think" or "skip" is an answer: write down the default you'll use.
+1. **Look first:** `rig auth list` and `rig auth seats` on each machine you can reach, `rig provider status
+   --all-hosts --json`, and `rig usage top` on each machine. Draft what you can.
+2. **Confirm what you saw,** in one message ("three Codex subscriptions and one Claude one, on two machines; the build
+   box uses about four times the tokens of the laptop; any I can't see?").
+3. **Ask how they want them used,** offering the common shape: the busiest machine gets its own subscription, the
+   rest share, and one stays spare.
+4. **Ask what you may do on your own:** move a machine's Codex seats without asking; machines or seats to ask about
+   first or never move; sign-ins (may agents, and through which browser or profile, or always ask). Say what's
+   supported today: moves are by Codex home, Claude moves aren't supported yet, and a sign-in preference is used only
+   where a sign-in route and access exist.
+5. **Ask how to reach them** (their seat's queue, a chat channel, the Fleet app), for what, and what to do when they
+   don't answer. A channel they name is a preference: check the route with `messaging-the-human`, and use a queue
+   item to their seat if it isn't ready.
+6. **Ask what to do when things go wrong:** nothing has room, a sign-in is needed while they're away, a move didn't
+   confirm.
+7. **Show the draft in plain words,** let them correct it, and save it as a context pack named `account-policy` in
+   the context library where you run (`rig config get context.root`): a folder with `manifest.yaml` (`version: "1"`,
+   `name: account-policy`, `taxonomy: world`, a `purpose`, and `files: [{ path: POLICY.md, role: policy }]`) and
+   `POLICY.md`, installed with `rig context add <folder>` and read back with `rig context get account-policy`. To share
+   one policy across machines, use a Git repository: `rig context add <repo> --git`. Labels and references only:
+   never tokens, passwords, cookies or recovery codes.
+
+   `POLICY.md` has these parts, in their words: subscriptions (label, provider, plan, how each is reached); how they
+   want them used; what agents may do on their own; how to reach them; when things go wrong; and a dated **Changes**
+   list. Fill it from what you saw and what they said, never from another person's setup.
+
+**Changing the policy.** When they say what changed, copy `POLICY.md` aside as the before copy, edit it, add a dated
+line under **Changes**, and raise `version` in `manifest.yaml`. Keep one place where it's edited: edited where it's
+installed, run `rig context sync`; kept in a separate folder, replace it with `rig context rm account-policy` and
+`rig context add <folder>`; Git-backed, edit and commit in the checkout `rig context source inspect account-policy`
+reports, then `rig context source update account-policy` (it never pushes). Read it back with
+`rig context get account-policy`; your next decision follows the new version.
+
 ## Context packs and paced delivery (0.5.0)
 
 **Compose context once, hand it to a seat cleanly.** A library primitive plus a set of delivery flags. The rule that keeps the grammar coherent — internalize this one: **the noun stores and composes; the verbs deliver.** `rig context` never sends anything; delivery is only ever `rig send` / `rig broadcast` / `rig walk` / `rig queue`.
@@ -1280,6 +1369,8 @@ Notes:
 - for tmux-backed self-attach, `rig whoami --json` is the right verification
 - for raw/external self-attach, `rig ps --nodes --json` is currently the more reliable verification surface
 - if the current shell is outside tmux, pass `--display-name <name>` when you want a stable human session label recorded
+- to read a seat's identity or state later, use `rig whoami` or `rig seat status`, not `rig attach --json` output or a file holding a
+  seat's environment. Don't print `OPENRIG_ACTIVITY_*` values: the activity token is a credential, and it doesn't identify the seat
 
 ### Adopt a topology and bind live sessions
 
@@ -1393,9 +1484,10 @@ or `rig add` (one member) when a seat needs an explicit model, a permission poli
 different agent spec or role profile, per-seat runtime or cwd, or startup files.
 
 Node-granular managed partial restore (v0.3.4+):
-- `rig launch <rig> <nodeRef>` relaunches a single seat by logical id or node id through orchestration. `<rig>` is the
-  rig's name or ID; a name shared by more than one active rig stops with the candidate IDs.
-- `rig launch <rig> --seats <a,b,c>` relaunches a comma-separated subset of seats.
+- `rig launch <rig> <nodeRef>` launches a single seat that isn't running, by logical id or node id, through orchestration.
+  `<rig>` is the rig's name or ID; a name shared by more than one active rig stops with the candidate IDs. A seat that's
+  already running is left as it is; for a fresh occupant there, use `rig seat launch <seat> --fresh --stop --reason <why>`.
+- `rig launch <rig> --seats <a,b,c>` launches a comma-separated subset of seats.
 - `--hold-reason <text>` records a reason for holding non-target seats during the partial launch.
 - This is a SUPPORTED managed path. The prior `pod_aware_launch_unsupported` dead-end is retired; pod-aware narrow launch now goes through this surface rather than ad-hoc rebuilds.
 
@@ -1449,32 +1541,70 @@ rig specs rename <name-or-id> <new-name> [--json]
 ## MCP
 
 ```bash
-rig mcp serve [--port <port>]
-```
-
-Current shipped MCP tools:
-- `rig_up`
-- `rig_down`
-- `rig_ps`
-- `rig_status`
-- `rig_snapshot_create`
-- `rig_snapshot_list`
-- `rig_restore`
-- `rig_discover`
-- `rig_bind`
-- `rig_bundle_inspect`
-- `rig_agent_validate`
-- `rig_rig_validate`
-- `rig_rig_nodes`
-- `rig_send`
-- `rig_capture`
-- `rig_chatroom_send`
-- `rig_chatroom_watch`
-- `rig_add`
-- `rig_queue_create`, `rig_queue_show`, `rig_queue_list`, `rig_queue_claim`, `rig_queue_update`
-
-The server acts as one seat: the `OPENRIG_SESSION_NAME` in its environment. Every request carries that identity, so
-no tool call names a sender. Without it, writes that need an actor are refused with `actor_required`.
+rig mcp serve [--port <daemon-port>]        # stdio: a local app starts the server itself
+rig mcp serve --http [--bind <host:port>]   # Streamable HTTP at /mcp (default 127.0.0.1:7437)
+rig mcp token add <name> --seat <session> [--rig <name>...] [--root <name>...] [--workspace] [--owner]
+rig mcp token list [--json]
+rig mcp token revoke <name>
+```
+
+The 34 shipped tools fall into three groups. Over stdio, and over HTTP with no grants, every tool is offered. An HTTP
+grant offers the work tools; the workspace tools with `--workspace` or `--owner`; and the owner tools only with
+`--owner`, which offers every tool.
+- **Work (17):** orientation, communication and the durable work loop.
+  - `rig_whoami`: the seat the server acts as (rig, pod, peers, edges) and the `caller`: authenticated (an HTTP
+    credential, with its principal) or declared (`OPENRIG_SESSION_NAME` where the server was configured, which nothing
+    verifies).
+  - `rig_status`, `rig_ps`, `rig_rig_nodes`, and `rig_team`: a rig's lead (its one `delegates_to` root, the seat to
+    delegate to) and each seat's role, delegation and activity.
+  - `rig_send`, `rig_capture`, `rig_chatroom_send`, `rig_chatroom_watch`.
+  - `rig_queue_create`, `rig_queue_show`, `rig_queue_list`, `rig_queue_claim`, `rig_queue_update`:
+    - `revises` on create asks for a linked revision of an earlier item;
+    - show names a handed-off item's successor;
+    - `handedOffFrom` on list follows a handoff.
+  - `rig_artifact_read`: a finished item's artifact (its `evidenceRef`) or a named file, through the daemon's shared
+    roots (`OPENRIG_FILES_ALLOWLIST`), in windows (`offset`, `nextOffset`). Outside those roots it answers unavailable
+    rather than reading a local path.
+  - `rig_human_decision_room`, then `rig_queue_decide`: on your own pending ask to a person, read the decision room of
+    the mode they have on, and record a decision you made for them inside it. No tool writes a person's own answer.
+- **Workspace (4):** `rig_slices`, `rig_mission`, `rig_context_pack`, and `rig_context_get` (one context file or
+  section, as `rig context get` reads it).
+- **Owner (13):** `rig_up`, `rig_down`, `rig_snapshot_create`, `rig_snapshot_list`, `rig_discover`, `rig_bind`,
+  `rig_add`, `rig_bundle_inspect`, `rig_agent_validate`, `rig_rig_validate`, `rig_telemetry_events` (one bounded page
+  of event metadata), and:
+  - `rig_restore`, which starts a restore and returns its attempt;
+  - `rig_restore_status`, that attempt's receipt.
+
+**Results:**
+- A structured result comes beside the text from the queue tools, `rig_whoami`, `rig_team`, the four workspace tools,
+  `rig_artifact_read`, `rig_human_decision_room` and `rig_restore_status`. The other tools answer in text.
+- Every failure carries the same structured shape: `ok: false`, a `code` and a `message`.
+
+**Identity:**
+- **Over stdio, and over HTTP with no grants:** the server acts as one seat, the `OPENRIG_SESSION_NAME` in its
+  environment. Every request carries that identity, so no tool call names a sender. Without it, writes that need an
+  actor are refused with `actor_required`.
+- **Over HTTP with grants:** each caller acts as its own grant's seat.
+
+### Over HTTP: an assistant that can't start a local process
+
+- **No grants (no token file):**
+  - the listener stays on loopback and acts as `OPENRIG_SESSION_NAME`, declared, like stdio;
+  - a request whose `Host` isn't loopback is refused.
+- **With grants:** every request needs `Authorization: Bearer <token>`, loopback included, because a tunnel or proxy
+  delivers remote traffic to loopback.
+  - **Identity:** each caller acts as its grant's seat.
+  - **What it reaches:** only its rigs' seats and work, and its roots' artifacts. Anything else answers `out_of_scope`.
+  - **Bad credentials:** a missing, invalid or revoked token gets a 401, never the environment's seat.
+  - **A broken token file:** the server reads the file on every request. While it is missing or can't be read, every
+    request is refused (`auth_config_unreadable`); restore a valid, readable file and requests are served again, with
+    no restart. The other way back is a restart with no token file, which returns the server to the no-grants mode
+    above (loopback only). A restart never skips a token file that is present: its grants still apply.
+- **Beyond loopback** (`--bind`), the server starts only with a grant. TLS comes from the tunnel or proxy, not from
+  this server.
+- **`rig mcp token add`** prints the token once and stores only its hash.
+- **`revoke`:** the caller's next request is refused, and work it already handed over stays with its owners.
+- **Grants, binds and tunnels are the person's decisions.** Give them the commands, and don't run them on their behalf.
 
 ### Join a team from an agent with no terminal of its own (desktop apps)
 
@@ -1486,11 +1616,12 @@ use the `rig` CLI instead, the same way.
    Note the `OPENRIG_SESSION_NAME` it prints.
 2. **Give the person the MCP entry to add.** Don't edit their app's settings yourself. The entry runs
    `rig mcp serve`, with `OPENRIG_SESSION_NAME=<that seat>` in its environment. Most MCP clients take it as a
-   command, arguments and an `env` map.
+   command, arguments and an `env` map. An app that can't start a local process connects to `rig mcp serve --http`
+   instead, with a grant for that seat (see "Over HTTP" above).
 3. **Hand off work** with `rig_queue_create`, and keep the `qitemId` it returns.
 4. **Read the answer** with `rig_queue_show <qitemId>`. The item's state, closure and transition notes are where the
-   assignee records it. A call that times out has an unknown outcome: check `rig_queue_show` with the same id
-   before you retry, and retry only with that id.
+   assignee records it, and `rig_artifact_read` reads an artifact it names. A call that times out has an unknown
+   outcome: check `rig_queue_show` with the same id before you retry, and retry only with that id.
 5. **Take work** with `rig_queue_list` (`owned: true`), `rig_queue_claim` and `rig_queue_update`. Close with the
    answer in `note`.
 

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

@@ -29,8 +29,9 @@ without an owner.
   with the rig appearing dormant.
 - **Finishing a slice that has a clear next step.** Default-nudge:
   receiver gets a wake-ping plus the durable queue item.
-- **Blocked on another agent's work.** Park the qitem with
-  `closure_reason: blocked_on` and the blocker qitem id.
+- **Blocked on another agent's work.** Use `rig queue block <id> --on <child>`
+  (or `rig queue update <id> --state blocked --blocked-on <child>`). The item
+  stays active and returns to pending when its blocker completes.
 - **Escalating to the human.** Make the escalation a durable attention
   item, not just a chat message.
 
@@ -53,16 +54,20 @@ human. The qitem state machine enforces this:
 `pending → in-progress → done` requires `closure_reason` from one of:
 
 - `handed_off_to` — work continues at a different seat (target = new owner)
-- `blocked_on` — parked pending another qitem (target = blocker qitem id)
 - `denied` — receiver rejected the work
 - `canceled` — sender or receiver withdrew
 - `no-follow-on` — terminal completion, nothing else needed
 - `escalation` — kicked up to a higher tier (target = escalation target)
+- `superseded` — replaced by another qitem (target = successor qitem id)
 
-Three of those (`handed_off_to`, `blocked_on`, `escalation`) additionally
+Two of those (`handed_off_to`, `escalation`) additionally
 require `closure_target`. The daemon enforces this at the domain layer;
 every surface (CLI, MCP, future UI) inherits the same guarantee.
 
+`done` is terminal. `closure_reason: blocked_on` is valid only on an active
+`state=blocked` park record, as used by workflow writers; combining it with
+`state=done` is rejected. Use the block command above to wait on another qitem.
+
 **The drafted-park failure (draft ≠ throw).** The rule is about the *actual* pass, not the
 intention to pass. A turn that ends with a self-instruction **typed into your own prompt but left
 unsent** — a drafted go-ahead, a next-atom note you never sent — has **not** handed off; it has
@@ -120,6 +125,7 @@ inverted the default-nudge polarity.
 - **Scope tags `project:<id>`, `mission:<id>`, `slice:<id>`** on project work, set when you create the row (`--tags`; `create` also takes `--mission` and `--slice`). Tags can't be edited afterwards. A handoff keeps the source row's tags unless you pass `--tags` or `--gate`, either of which replaces them; repeat the scope tags in `--tags` when you use `--gate`.
 - **Pass work on with `handoff-and-complete`.** It closes your row as done and records the next row as its successor in one step. A `create` followed by `update --state done --closure-reason handed_off_to` records no successor, and the stuck sweep raises a recovery item for it.
 - **Close what you hold.** A row you claimed ends in a handoff or an `update --state done --closure-reason …`; `rig queue overdue` lists claimed rows past their deadline.
+- **Use the write's response.** Read the row back only when the response doesn't show what you need (an indeterminate outcome, a field the compact output left out, downstream wake or pickup, a team custody rule): openrig-user, "After a queue write".
 - **Brief for the model that will read it.** Before handing a peer open-ended work, check which model it runs: `delegating-work`, "Check what kind of agent you're handing it to".
 
 ## Queue-body hygiene (token + parse safety)