@openrig/cli 0.5.1 → 0.5.3

package/daemon/context-packs/skills/core/cross-host-rig-commands/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: cross-host-rig-commands
+description: Use when issuing `rig` commands against a remote host via `--host <id>` flag (single-hop SSH to a host declared in `~/.openrig/hosts.yaml`). Covers the 4 structured failure modes (ssh-unreachable / permission-gate / remote-daemon-unreachable / remote-command-failed), the `--verify` honest pass-through (SSH success is NOT verify success), and the host-registry shape. v0 supports `rig send / capture / ps / whoami --host <id>`.
+metadata:
+  cli_surfaces_referenced:
+    - capture
+    - daemon start
+    - host list
+    - host show
+    - ps
+    - send
+    - whoami
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - rig-lifecycle
+      - topology-mutation-and-seat-management
+      - seat-scaling-and-specialization
+      - sidecar-operator
+      - rig-bundles-and-shareable-artifacts
+      - specification-system
+      - extension-and-user-workspace
+---
+
+# Cross-Host Rig Commands
+
+A first-class OpenRig surface for issuing `rig` commands against a
+remote host via single-hop SSH. v0 productizes the existing SSH-envelope
+operator pattern (`ssh <host> rig <cmd>`) with declared host identity,
+explicit cross-host invocation path, preserved `--verify` semantics, and
+4 named failure modes.
+
+**Current-host note (2026-07-14):** this skill still preserves the original
+SSH-v0 doctrine below, but the live host registry may also contain HTTP
+read-through/tunnel entries such as `your-vm` and `your-other-vm`. Use the
+host registry entry as ground truth for transport shape, and use
+`conventions/multi-host-naming/README.md` for host-id naming. HTTP entries
+require `url` plus exactly one of `bearer_file` or `bearer_env`.
+
+**v0 is CLI-side shell-out only — `packages/daemon/` is NOT touched.**
+The remote host has its own managed `rig` available on `$PATH`.
+
+## Use this when
+
+- Driving a Tart VM from the host (the immediate cross-host consumer)
+- Operating Mac host A against Mac host B
+- Reading remote state via `rig ps --host` / `rig whoami --host`
+- Sending or capturing on a remote rig session (`rig send/capture --host <id>`)
+- Authoring a `~/.openrig/hosts.yaml` registry entry
+
+## Don't use this when
+
+- The target is local. Don't pass `--host` for local commands.
+- You need multi-hop SSH (host A → host B → host C). v0 is single-hop only.
+- You want reverse direction (remote initiates back to local). v0 is originator-pull only.
+- Cross-host **seat handover** (moving a durable owned seat across hosts) — deferred to higher-level primitives. (Cross-host **queue writes**, by contrast, now ship — see "Cross-host queue writes" below.)
+- The transport isn't SSH. v0 supports `transport: ssh` only.
+
+## Cross-host queue writes (updated 2026-07-21 vs main d37a08ad)
+
+Cross-host **queue writes** are no longer deferred — they ship — but the rule
+differs from the interactive verbs (`send`/`capture`/`ps`/`whoami`):
+
+- **Queue writes are EXPLICIT-only.** Address the target host explicitly with
+  `--host <id>` or the `member@rig@<host>` form. A queue write **never** follows a
+  persisted host selection.
+- **`host select` stickiness does NOT apply to queue.** `host select` affects the
+  `resolveEffectiveHost` verbs (`send`/`capture`/`ps`/`whoami`) — those follow the
+  selected host — but a queue write ignores it and requires explicit addressing.
+- **Host address parsing differs** between the interactive verbs and the queue
+  verbs; do not assume the interactive form carries over. When unsure, address the
+  host explicitly.
+
+## Host registry shape (`~/.openrig/hosts.yaml`)
+
+Host ids should follow the OpenRig-work multi-host naming convention:
+`conventions/multi-host-naming/README.md`. In this environment that means
+physical hosts such as `your-vm`, local OpenRig development VMs such as
+`your-vm`, persistent product VMs such as `your-other-vm`, and VPS hosts such
+as `your-vps`. Keep old aliases during migration until no live routing
+depends on them.
+
+```yaml
+hosts:
+  - id: a-test-vm
+    transport: ssh                       # v0 supports "ssh" only
+    target: a-test-vm.local         # DNS name, SSH config alias, or IP
+    user: wrandom                        # optional
+    notes: "Tart VM"                     # optional
+  - id: laptop-b
+    transport: ssh
+    target: laptop-b.tail-scale-net
+    user: wrandom
+```
+
+Validation rules:
+
+- `hosts` required, non-null array
+- Each entry: `id` required (non-empty, unique), `transport` required (`ssh` only), `target` required
+- `user` and `notes` optional
+- Operator-managed file; v0 does NOT include any sub-command to add/remove/list hosts (operators edit YAML directly)
+- Missing or invalid file returns a clear error pointing at the canonical path
+
+## CLI surface (v0 shipped)
+
+```bash
+rig send <session> "msg" --host <id> --verify
+rig capture <session> --host <id>
+rig ps --host <id> [--nodes] [...]
+rig whoami --host <id>
+```
+
+Forwards every shaping flag (`--nodes`, `--full`, `--limit`, `--fields`,
+`--summary`, `--filter`, `--json`) to the remote `rig` invocation. The
+remote rig's output is verbatim passthrough on success.
+
+## The 4 structured failure modes (load-bearing API contract)
+
+The CLI distinguishes 4 failure modes; operators get an actionable error
+per mode; JSON output preserves the `failedStep` enum:
+
+| Mode | Cause | Action |
+|---|---|---|
+| `ssh-unreachable` | SSH itself failed (connection refused, host key mismatch, DNS failure, timeout) | Verify SSH access and the registry entry |
+| `permission-gate` | SSH hit auth/permission gate (Permission denied, Keychain) | Error includes hint to keychain-over-SSH field note (L4-3 D6) |
+| `remote-daemon-unreachable` | SSH succeeded but remote `rig` reported the remote daemon was not reachable | `ssh <target> rig daemon start` |
+| `remote-command-failed` | SSH succeeded but remote `rig` exited non-zero for some other reason; remote stderr is surfaced | Read remote stderr; debug remote command |
+
+Each is distinct and routable. Don't conflate them.
+
+## `--verify` honest pass-through (load-bearing)
+
+`--verify` against a remote target must:
+
+- **Propagate** the verification request to the remote daemon (or remote `rig` invocation that talks to it)
+- **Bring back a structured verification result** (true/false + reason if false), NOT just SSH exit code 0
+- **Distinguish "SSH succeeded but verify returned false" from "SSH itself failed"** — these are different operator actions
+
+**SSH success is NOT verify success.** The remote rig is authoritative
+on `--verify`; its `Verified: yes/no` line is surfaced verbatim. Verified
+at 3 layers (executor unit, command integration, source impl).
+
+## Hard boundaries (do-not list)
+
+- **Do NOT collapse `--verify` honest result into SSH exit code.** Operators and agents rely on the distinction.
+- **Do NOT silently retry SSH failures inside the primitive.** Surface them; let the caller decide.
+- **Do NOT introduce non-SSH transports in v0.** Goal is productizing the existing shipped pattern, not replacing it.
+- **Do NOT touch host-side daemon code as part of v0.** Cross-host shape is on the originator side.
+
+## Cross-host annotation
+
+Every cross-host invocation is observable as cross-host:
+
+- **Operator output**: `[via host=<id> (<target>)]` annotation
+- **JSON output**: `cross_host: { host, target }` field
+
+Annotation is PRESENT when `--host` is set and ABSENT otherwise
+(compat regression).
+
+## Currently shipped (v0) vs deferred
+
+Shipped at openrig `cdce3a6` (2026-04-30):
+- `--host <id>` flag on `rig send / capture / ps / whoami` (initial 2 commands; promoted to 4 at `6b7043a` same day)
+- Read-only host registry validation
+- Single-hop SSH executor with 4-mode `failedStep` enum
+- `--verify` honest pass-through
+- Cross-host annotation (operator + JSON)
+- Daemon untouched
+
+Deferred:
+- Tier 2 real-runtime cross-host proof (disposable Tart VM cycle)
+- `rig host list / show` read-only sub-namespace (only if host count grows past comfortable manual editing)
+- Non-SSH transports
+- Multi-hop SSH
+- Reverse direction (remote initiates)
+- Connection pooling/caching
+
+## See also
+
+- `seat-continuity-and-handover` skill — host-aware seat-binding semantics for cross-host handover (deferred to v1 on top of this v0 baseline)
+- `openrig-user` skill — the local CLI surface that cross-host commands wrap
+
+## Sender identity carries the ORIGIN host (51-09, 2026-08-06)
+
+The `@host` sugar on a TARGET is **addressing** (`member@rig@<host>` routes to that host).
+The **From:** sender now ALWAYS carries the **origin** host: a cross-host (and local) message's
+signature is **`member@rig@<originHost>`** — the sender reflects the host it was sent from, so a
+received signature names the ORIGIN, and the `↩ Reply:` hint round-trips **verbatim** back to that
+origin (never a same-named local lookalike). This is the always-suffix rule — deterministic and
+collision-proof: a signature means one thing to every receiver. (This SUPERSEDES the pre-51-09
+asymmetry — "the sender carries no `@host` suffix" — that pm@your-rig flagged as a core gap on
+2026-07-25; 51-09 closed it.) Per BR-1 the host is NEVER folded into the session string on the
+wire: the CLI edge renders/strips it, the daemon refuses an in-band 3-part destination with a
+teaching hint, and a stale 2-part same-name destination is closed by `--host` + that teaching —
+not by any in-string magic.

package/daemon/context-packs/skills/core/cross-host-rig-commands/manifest.yaml

@@ -0,0 +1,9 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "cross-host-rig-commands"
+version: "0.5.3"
+purpose: "Use when issuing `rig` commands against a remote host via `--host <id>` flag (single-hop SSH to a host declared in `~/.openrig/hosts.yaml`). Covers the 4 structured failure modes (ssh-unreachable / permission-gate / remote-daemon-unreachable / remote-command-failed), the `--verify` honest pass-through (SSH success is NOT verify success), and the host-registry shape. v0 supports `rig send / capture / ps / whoami --host <id>`."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when issuing `rig` commands against a remote host via `--host <id>` flag (single-hop SSH to a host declared in `~/.openrig/hosts.yaml`). Covers the 4 structured failure modes (ssh-unreachable / permission-gate / remote-daemon-unreachable / remote-command-failed), the `--verify` honest pass-through (SSH success is NOT verify success), and the host-registry shape. v0 supports `rig send / capture / ps / whoami --host <id>`."

package/daemon/context-packs/skills/core/human-in-the-loop/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: human-in-the-loop
+description: Use when classifying a slice closeout (auto-continue / human gate / park), routing a real decision to a human, or designing a human queue/dashboard surface. Treats humans as durable network participants with attention surfaces, queues, and decision records — escalation lands as a durable attention item, not a chat message. Approval is NOT required for every clean closeout; the default RSI conveyor continues unless an explicit human gate is reached.
+metadata:
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - queue-handoff
+      - workflow-runtime
+      - watchdog
+      - refocus
+      - looping-workflows
+      - intake-routing
+      - attention-queue
+      - dispatching-parallel-agents
+      - subagent-driven-development
+      - control-plane-capabilities
+      - status-not-chat-orchestrator
+      - control-plane-queue
+      - control-plane-watchdog
+      - control-plane-workflows
+      - control-plane-delivery-loop
+      - control-plane-rollout-manager
+---
+
+# Human In The Loop
+
+The primitive that treats humans as **durable network participants** —
+attention surfaces, queues, decision records, routing semantics — not
+as ad-hoc chat receivers.
+
+**Autonomy is not the absence of humans; it is knowing when human
+judgment is needed and making that handoff crisp.**
+
+## Use this when
+
+- A slice closeout needs classifying: auto-continue, human gate, or park
+- A real decision needs to land in front of a human (usage limits, provider auth, roadmap tradeoff, product-intent ambiguity)
+- Designing a human queue/dashboard surface
+- Returning a hot potato to orchestration after human approval
+
+## Don't use this when
+
+- The slice closeout is clean and `PROGRESS.md` already names the next safe slice. **Default RSI conveyor continues; do NOT manufacture a human gate.**
+- The escalation is just a status update. Humans are participants for *decisions*, not narration.
+- The next owner is another agent. Use queue-handoff, not human-in-the-loop.
+
+## The 3-class closeout classification
+
+In a productized daemon-backed version, closeout classifies the next
+step BEFORE touching the human queue:
+
+| Class | When | Action |
+|---|---|---|
+| **auto-continue** | Slice closes cleanly, next named slice in workstream plan | Mark closed; create next-owner qitem from plan |
+| **human gate** | Genuine decision needed (usage limits, provider auth, product-intent ambiguity, roadmap tradeoff) | Create human queue item with proof + decision text + recommended default + action outcomes |
+| **park** | Intentionally stop the conveyor (e.g., waiting on external) | Stop with reason + resumption path |
+
+## Failure modes (5)
+
+1. **Human decision needed, but the rig only mentions it in chat.** Decisions belong as durable attention items, not chat messages.
+2. **Human queue item lacks enough plain-English context for a decision.** Include proof + decision text + recommended default + action outcomes.
+3. **Human response updates a file but does not wake the next owner.** Approval should return the hot potato; feedback should create the next durable qitem.
+4. **The dashboard shows too much raw rig state and hides the actual decision queue.** Decision queue is the primary surface; rig state is secondary.
+5. **A clean closeout is parked on the human even though `PROGRESS.md` already names the next safe slice.** Don't manufacture human gates.
+
+## Proof standard (both paths)
+
+A trustworthy human-in-the-loop system proves both directions:
+
+- **Blocking gate path**: real item routed to human → human decision recorded through UI → resulting hot-potato handoff wakes correct next owner
+- **Non-blocking closeout path**: proof inspectable by human, but orchestrator continues to next named slice without manufacturing a human gate
+
+A primitive that only wakes humans is not trustworthy. It must also know when NOT to.
+
+## Product shape (SHIPPED — Mission Control, PL-005)
+
+This surface has shipped as **Mission Control** (product UI, `/mission-control`
+route; actions via `POST /api/mission-control/action`). The seven verbs the
+human acts with:
+- **approve** (returns the hot potato to orchestration or the chosen owner)
+- **deny** (reject the item)
+- **route** (send to a different owner)
+- **annotate** (add context without action)
+- **hold** (intentional pause with reason)
+- **drop** (mark not-actionable)
+- **handoff** (hand to a specific next owner — creates the next durable qitem)
+
+**Approval returns the hot potato to orchestration or the chosen owner;
+feedback creates the next durable qitem rather than only mutating the source
+queue file** — enforced by the shipped verbs (handoff/route create qitems).
+See `docs/as-built/architecture/mission-control.md`.
+
+## Long-term shape
+
+Likely needs **multiple humans with different scopes**, not a singleton
+human attention feed. Different humans own different decision
+domains; queue items route by scope.
+
+## See also
+
+- `queue-handoff` skill — durable handoff via queue items; human-in-the-loop is the human-side complement
+- `watchdog` skill — when to wake (humans included) vs no-op
+- `looping-workflows` (convention) — the looping-workflows convention covers loop closeouts; human-in-the-loop is the escape hatch

package/daemon/context-packs/skills/core/human-in-the-loop/manifest.yaml

@@ -0,0 +1,9 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "human-in-the-loop"
+version: "0.5.3"
+purpose: "Use when classifying a slice closeout (auto-continue / human gate / park), routing a real decision to a human, or designing a human queue/dashboard surface. Treats humans as durable network participants with attention surfaces, queues, and decision records — escalation lands as a durable attention item, not a chat message. Approval is NOT required for every clean closeout; the default RSI conveyor continues unless an explicit human gate is reached."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when classifying a slice closeout (auto-continue / human gate / park), routing a real decision to a human, or designing a human queue/dashboard surface. Treats humans as durable network participants with attention surfaces, queues, and decision records — escalation lands as a durable attention item, not a chat message. Approval is NOT required for every clean closeout; the default RSI conveyor continues unless an explicit human gate is reached."