@openrig/cli 0.4.4 → 0.4.6

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

@@ -7,14 +7,12 @@ metadata:
     last_verified: "2026-07-06"
     distribution_scope: product-bound
     source_evidence: |
-      Authored + embedded in release-0.4.3 slice 32 (mission-slice-sop);
-      moved into the canonical product skill source and updated in
-      release-0.4.4 slice 23 (operationalize the SDLC control plane) to
-      teach the full SDLC flow the Living Notes UI projects: the convention
-      sections, the proof-contract pairing, the two staged-approval locks,
-      C1 proof drops, and the three role contracts. Conventions SSOT:
-      docs/reference/sdlc-conventions.md (shipped with the CLI package).
-      The deterministic backstop is the `rig scope audit` classifier.
+      The canonical product SDLC skill: it teaches the full SDLC flow the
+      Living Notes UI projects — the convention sections, the proof-contract
+      pairing, the two staged-approval locks, C1 proof drops, and the three
+      role contracts. Conventions SSOT: docs/reference/sdlc-conventions.md
+      (shipped with the CLI package). The deterministic backstop is the
+      `rig scope audit` classifier.
     sibling_skills:
       - queue-handoff
       - seat-continuity-and-handover

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

@@ -0,0 +1,86 @@
+---
+name: openrig-cmux
+description: >
+  Use when opening OpenRig fleet terminals into cmux — turning a rig, pod, mission, slice, or saved
+  view into live agent tiles via `rig terminal --provider cmux`, or driving cmux on an agent's
+  request. Same OpenRig view semantics as openrig-herdr (the verbs, honest-partial/degrade, read-only
+  cross-rig, scroll/copy, same-size-only duplicates); cmux is the **best-effort** provider (herdr is
+  the default and the proof-gated one). Prefer openrig-herdr unless cmux is specifically wanted.
+metadata:
+  openrig:
+    stage: candidate
+    distribution_scope: product-bound
+    source_evidence: |
+      cmux is OpenRig's shipped terminal provider generalized onto `rig terminal <provider>` —
+      best-effort, not proof-gated. Authored clean-room.
+    transfer_test: pending
+    sibling_skills:
+      - openrig-herdr
+      - openrig-user
+---
+
+# openrig-cmux
+
+cmux is a **provider** for OpenRig views — the same `rig terminal` surface as herdr, rendering the
+tiles into cmux instead. It is the provider OpenRig already shipped (the existing "Launch in cmux"
+affordance generalizes onto `rig terminal <provider>`), kept working. The OpenRig-semantic half is
+identical to openrig-herdr: OpenRig decides **which** agents form a view; the provider renders the
+pixels. **Read openrig-herdr first for the full model** — this skill only calls out what differs for
+cmux.
+
+## Provider status — cmux is best-effort
+
+- **herdr is the default and the proof-gated provider**; **cmux is best-effort** — it ships on the
+  same `rig terminal <provider>` + web-launcher neighborhood, but a cmux miss is not a slice failure.
+  Reach for cmux when it is specifically wanted; otherwise default to herdr (`rig terminal open <view>`
+  with no `--provider`).
+- Views are **provider-agnostic**: the same view + the same agents + the same semantics carry across
+  herdr and cmux. A saved view opens in either.
+
+## The surface (same three verbs, `--provider cmux`)
+
+```bash
+rig terminal open <view> --provider cmux [--json]   # open a view into cmux (herdr is the no-flag default)
+rig terminal views [--json]                          # the same view library, provider-agnostic
+rig terminal status --provider cmux [--json]         # cmux liveness / health
+```
+
+`<view>` resolves exactly as with herdr: a **rig name** · **`pod:<rig>/<podNamespace>`** ·
+**`mission:<id>`** · **`slice:<id>`** (derived live) · a **saved-view name**.
+
+## What carries over unchanged from openrig-herdr
+
+All of these behave identically — see openrig-herdr for the detail:
+
+- **Honest-partial / honest-degrade** — opened / absent / degraded, each named; partial opens exit 0,
+  zero-pane exits non-zero; an http-registered host's agents degrade with the reason ("host `<id>` is
+  http-registered; tiles need ssh"), never silently dropped.
+- **Read-only policy** — a rig or `pod:` view is interactive; `mission:` / `slice:` views are
+  read-only by construction; a saved view is per-member (`readOnly`). A read-only pane is
+  `tmux attach -r` (client `readonly=1`, keystrokes physically cannot reach the agent). See openrig-herdr.
+- **Safety rails (the fleet-safety rail)** — a tile is a *view* (nested `tmux attach`) of a
+  daemon-owned session; never move/join/kill/re-parent a daemon-owned pane; closing a tile detaches
+  one client and leaves the session untouched; never live-flip tmux options on a running seat in
+  production (prove it in an isolated environment first).
+- **Scroll + copy out of the box** — the daemon's terminal defaults (per-session scroll at launch +
+  the server's clipboard defaults); running seats pick up wheel-scroll at their next relaunch.
+- **Limits** — tile chrome v1 = a plain label; same-size panes for duplicate/multi-view membership
+  (the different-size resize mismatch is an inherent tmux multi-client limit, documented not fixed).
+
+## cmux-specific notes
+
+- **Open-or-focus per agent** — cmux's shipped integration opens a node or focuses it if already open;
+  expect focus (not a duplicate) when a seat is already tiled in cmux.
+- **The shipped "Launch in cmux" affordance is preserved** (byte-compatible) and generalizes into the
+  provider + view picker; opening cmux from the web launcher still works.
+- **No AGPL arm's-length concern** — unlike herdr, cmux is OpenRig's shipped provider integration; the
+  clean-room/never-embed rail that applies to herdr is not a cmux constraint. (This skill itself is
+  still authored clean-room.)
+
+## Saved views — provider-agnostic
+
+Saved views are **hand-authored** in `terminal-views.yaml` (v1 has no save/write verb) and are
+**provider-agnostic** — see **openrig-herdr** for the exact schema, the store facts (atomic tmp+rename,
+byte-stable, at the OpenRig home root), and the derived-views-never-persisted rule. Reopen any saved
+view in cmux with `rig terminal open <id> --provider cmux`. Derived views (a rig, `pod:<rig>/<pod>`,
+`mission:<id>`, `slice:<id>`) are computed live and never written to the file.

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

@@ -0,0 +1,158 @@
+---
+name: openrig-herdr
+description: >
+  Use when opening OpenRig fleet terminals as a herdr wall — turning a rig, pod, mission, slice, or
+  saved view into live interactive agent tiles via `rig terminal`, watching another rig read-only,
+  or driving herdr on an agent's request ("open all my rigs + a mission as views"). Covers the
+  `rig terminal open|views|status` verbs, the honest-partial/degrade reading of the result, the
+  read-only-by-construction rail for cross-rig views, scroll/copy out of the box, and the
+  same-size-only duplicate-pane limit. herdr is the default, proof-gated provider.
+metadata:
+  openrig:
+    stage: candidate
+    distribution_scope: product-bound
+    source_evidence: |
+      Empirical herdr 0.7.1 hands-on findings + the ratified implementation PRD. Authored
+      clean-room (patterns only, no herdr source text; AGPL arm's-length).
+    transfer_test: pending
+    sibling_skills:
+      - openrig-cmux
+      - openrig-user
+---
+
+# openrig-herdr
+
+OpenRig decides **which** agents make up a view (a rig, a pod, a mission, a slice, or a saved
+group); **herdr** renders the pixels. A view opens as live, interactive terminal tiles — each tile
+is a nested `tmux attach` to a daemon-owned agent session, so you get the real session, not a
+snapshot. OpenRig owns the semantics; herdr owns the surface. You drive it entirely through the
+`rig terminal` CLI, which rides the installed herdr binary at arm's length — never link, embed, or
+plugin it.
+
+## The whole surface — three verbs
+
+```bash
+rig terminal open <view> [--provider herdr|cmux] [--json]   # herdr is the default provider
+rig terminal views [--json]                                 # list openable views (saved + derived)
+rig terminal status [--provider] [--json]                   # provider liveness / health
+```
+
+`<view>` resolves, in order, to one of:
+- a **rig name** — every live agent in that rig, auto-laid-out;
+- **`pod:<rig>/<podNamespace>`** — every live agent in one pod of a rig (the rig's inventory filtered by pod);
+- **`mission:<id>`** — the agents working that mission (derived live from topology);
+- **`slice:<id>`** — the agents working that slice (derived live);
+- a **saved-view name** — a user-defined group (see Saved views).
+
+## Compose a view from a sentence
+
+An agent asked "open all my rigs plus a mission as views" runs one `open` per target:
+
+```bash
+rig terminal open acme-web                     # a whole rig, live agents as tiles
+rig terminal open mission:site-relaunch        # exactly the agents working the mission
+rig terminal open slice:02-search-filters      # the agents working one slice
+```
+
+No hand-listing of seats: the mission/slice membership is derived from live topology at open time.
+
+## Read the result honestly — partial and degrade
+
+The result is a partition — every seat lands in exactly one bucket, each **named**:
+
+- **opened** — the live agents now showing as tiles.
+- **absent** — seats in the view that aren't currently live: **named and skipped, never silently
+  dropped.** A view that opens *some* of its seats is a success (the partial is disclosed) and exits
+  **0**. Only a view where **no** pane opens exits **non-zero**.
+- **degraded** — an agent that structurally cannot tile, named **with the reason**. The v1 case:
+  an agent on a host registered over HTTP has no ssh path, so its tile can't be composed — it reads
+  as **"host `<id>` is http-registered; tiles need ssh"** and is skipped, never dropped. (ssh-reachable
+  hosts tile via an ssh-wrapped attach; full http-host tiling is deferred to the cross-host transport
+  seam.)
+
+Read `--json` to branch on the partition programmatically; the exit code alone tells you opened-something
+(0) vs opened-nothing (non-zero).
+
+## Read-only — who's interactive, who's watch-only
+
+Read-only is composed into the pane at open time — a read-only tile is a `tmux attach -r`, the client
+reports `readonly=1`, and it **physically cannot send input**. The current policy, by view kind:
+
+- **A rig view or a `pod:` view is interactive** — you asked for that rig (or pod) directly, so you
+  can drive its agents.
+- **`mission:` and `slice:` views are read-only by construction** — these derived views cut across
+  rigs; you watch and scroll, you don't keystroke into them.
+- **A saved view is per-member** — each member carries its own `readOnly` (omit = interactive;
+  `true` = `attach -r`).
+
+So you don't have to remember to be careful: the view kind (and, for a saved view, the per-member
+flag) sets it at open time.
+
+## Safety rails (hard — the fleet-safety rail)
+
+- A tile is a **view** (a nested `tmux attach`) of a daemon-owned session. **Never** move, join, kill,
+  or re-parent a daemon-owned pane. Closing a tile detaches one tmux client — the daemon's session is
+  untouched and its addressing (send/capture/nudge) is unaffected.
+- Host-local read-only viewing mutates nothing. Anything that would change a **live** daemon session's
+  shared state (e.g. flipping a tmux option on a running seat) is a config/design change — prove it in
+  an isolated environment, never live-flip in production.
+
+## Scroll + copy work out of the box
+
+On a freshly-launched agent tile the mouse wheel scrolls the pane's history and a drag-select copies
+to your **system** clipboard — with no tmux commands typed. This rides the daemon's terminal defaults
+(a per-session scroll option set at launch, plus the daemon tmux server's clipboard defaults). Honest
+timing: agents that were already running before this shipped pick up wheel-scroll at their **next
+natural relaunch** (the scroll default is per-session and running seats are never retro-flipped);
+system-clipboard copy works immediately (it's server-wide).
+
+## Limits — state them, don't paper over them
+
+- **Tile chrome v1 = a plain label** (agent + slice). Rich per-tile status is roadmap.
+- **Duplicate / multi-view membership** (the same agent live in two views at once) works — put the
+  duplicates in **same-size panes**. Different-sized duplicate panes have an inherent tmux
+  multi-client resize mismatch (tmux clamps to the smallest client); it is **documented, not fixed** —
+  don't expect a setting to remove it.
+- **Inner tmux status bar** is hidden by default (herdr provides the chrome); one config key
+  (`terminal.status_bar`) flips it back on for raw-tmux / no-provider surfaces, and the flip applies
+  to **future launches only**.
+
+## Saved views — the library (`terminal-views.yaml`)
+
+In v1 you **create** a saved view by **hand-authoring** `terminal-views.yaml` — there is no save/write
+verb (`open` / `views` / `status` are the whole surface; a `rig terminal save <id>` verb is a named
+stretch/follow-up). You **reopen** it like any other view: `rig terminal open <id>`.
+
+The file lives at the OpenRig home root (resolved via `getDefaultOpenRigPath()`), is written
+atomically (tmp + rename), and is byte-stable. **Only hand-authored saved views live here — derived
+views (a rig, `pod:<rig>/<pod>`, `mission:<id>`, `slice:<id>`) are computed live and never written to
+this file.**
+
+Schema — use these field names **exactly**, in this order; **omit** optional fields when absent
+(never write `null`):
+
+```yaml
+version: 1
+views:
+  - id: my-view-id             # required — the id `rig terminal open <id>` takes
+    name: Human Name           # required
+    members:
+      - seat: pod-member@rig    # required — the canonical session name
+        label: agent . slice    # optional — pane label
+        host: some-host-id      # optional — STRUCTURED host id (NEVER a `member@rig@host` string);
+                                #            omit for local. ssh-registered hosts tile;
+                                #            http-registered hosts honest-degrade (named + skipped, with reason)
+        tmuxSession: sessname   # optional — defaults to `seat`
+        readOnly: true          # optional — omit = interactive; true = `tmux attach -r`
+```
+
+An agent composing a saved view on request **writes this YAML** and then opens the id:
+`rig terminal open my-view-id` (add `--provider cmux` for cmux). The library is provider-agnostic —
+the same saved view opens in herdr or cmux.
+
+## AGPL / clean-room
+
+Driving herdr through the `rig terminal` CLI (which talks to the installed herdr binary over its
+CLI/socket) is arm's-length and fine. Do **not** link herdr's source, embed it in-process, or ship a
+herdr plugin — a plugin needs legal review. This skill and its docs are clean-room: patterns only,
+never herdr source text.