@openrig/cli 0.4.6 → 0.4.8

package/daemon/{assets/plugins/openrig-core/skills → specs/agents/shared/skills/core}/agent-startup-and-context-ingestion/SKILL.md

@@ -2,17 +2,22 @@
 name: agent-startup-and-context-ingestion
 description: Use when designing or auditing how an agent becomes useful after launch — AGENTS.md overlays, role files, skills, rig specs, workflow specs, startup checklists, refocus messages, "rig context" surface. Covers the 4 failure modes that make startup context fail (old rig spec misses current operating mode; current agents never told about new guidance; startup file as dumping ground; orchestrator transmits implementation without preserving product intent).
 metadata:
+  cli_surfaces_referenced:
+    - context
+    - whoami
   openrig:
     stage: factory-approved
-    last_verified: "2026-05-04"
-    distribution_scope: product-bound
-    source_evidence: |
-      Cross-runtime restore/reentry packet standard + externalized memory
-      surfaces convention. Load at agent start; revisit after compaction.
     sibling_skills:
       - claude-compaction-restore
+      - mental-model-ha
+      - scope-recovery
+      - session-compaction-and-restore
+      - agent-starters
+      - composable-priming-packs
+      - session-source-fork
       - seat-continuity-and-handover
-    transfer_test: pending
+      - claude-compact-in-place
+      - pre-maintenance-agent-preservation
 ---
 
 # Agent Startup and Context Ingestion
@@ -43,8 +48,8 @@ is scattered or stale, agents execute the wrong thing very efficiently.
 ## Don't use this when
 
 - The agent is being created via Agent Starter — the starter's manifest carries startup context
-- The work is artifact-backed mental-model rebuild from a packet — that's `claude-compaction-restore`
-- The intent is to ship reusable startup content as a skill — write the skill against the agentskills.io specification, not as inline startup prose
+- The work is artifact-backed mental-model rebuild from a packet — that's `session-compaction-and-restore`
+- The intent is to ship reusable startup content as a skill — that's `writing-skills-for-openrig`
 
 ## Failure modes (4)
 
@@ -71,15 +76,14 @@ reentry case, distinct from reusable Agent Starters / priming packs):
 
 ## Memory surfaces consumed at startup
 
-The primary surfaces a startup ingestion path reads:
+Per the externalized-memory-surfaces convention's 13-row inventory:
 
-- AGENTS / role / CULTURE / startup overlays (the per-seat identity layer)
-- startup replay context (what the agent did before the current boot)
-- restore / reentry packets and Agent Starters (cross-runtime startup path)
+- **Row 7** — AGENTS/role/CULTURE/startup overlays (primary)
+- **Row 3** — startup replay context (primary)
+- **Row 12** — restore/reentry packets and Agent Starters (cross-runtime startup path)
 
-Authority-rank + read-vs-write posture governs which surfaces a
-startup-ingestion path can write vs only read; treat overlays as
-write-restricted unless your role explicitly authors them.
+The umbrella's authority-rank + permission-posture columns govern which
+surfaces a startup ingestion path can write vs only read.
 
 ## Startup files vs skills (the distinction)
 
@@ -89,7 +93,7 @@ Per `agent-startup-guide.md` (product reference doc) and the team handbook:
 |---|---|
 | Rig-specific, role-specific identity | Reusable SOPs / methodology / knowledge |
 | Tell agent WHO it is, WHAT it's working on, HOW this team operates | Tell agent HOW to do something (transferable across rigs) |
-| Examples: `role.md`, `CULTURE.md`, `startup/context.md` | Examples: `openrig-user`, `test-driven-development`, `dogfood` |
+| Examples: `role.md`, `CULTURE.md`, `startup/context.md` | Examples: `openrig-user`, `test-driven-development`, `vault-user` |
 | Authored per-rig | Authored once, used everywhere |
 
 Don't put skill content in startup files. Don't put identity content
@@ -98,7 +102,11 @@ culture / pod / member / operator) handles the layering.
 
 ## See also
 
+- `mission-slice-sop` skill — the universal operating procedure for working a mission/slice (the canonical PROGRESS/PROOF/MISSION_NOTES/MISSION_BRIEF files); every agent should reach for it at startup, so this general reading contract points at it here (do NOT duplicate the SOP into seat-specific startup files).
+- `writing-skills-for-openrig` skill — authoring discipline for skill content (what doesn't belong in startup)
 - `forming-an-openrig-mental-model` skill — orientation for new agents
-- `claude-compaction-restore` skill — restore-time startup ingestion after compaction
-- `seat-continuity-and-handover` skill — packet shape that survives seat resets
-- https://agentskills.io/specification — the cross-runtime skill standard (what skill content should and shouldn't be)
+- `session-compaction-and-restore` skill — restore-time startup ingestion
+- `agent-starters` skill — reusable starter manifests that compose startup context
+- `composable-priming-packs` skill — manifests that produce primed sessions
+- `externalized-memory-surfaces` skill — umbrella convention for memory surfaces this primitive consumes
+- `openrig/docs/reference/agent-startup-guide.md` (product reference doc; not a skill) — the 7-layer additive startup model + delivery hints

package/daemon/specs/agents/shared/skills/core/attention-queue/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: attention-queue
+description: Coordination primitive for OpenRig. Per-agent queue files tracking in-flight work with explicit state transitions + handoff semantics + cross-agent composition. Prevents memory-loss drops; surfaces stalls mechanically; closes the feedback loop on handed-off work. Applied liberally by every agent on every kernel-supervised rig; composed views serve human attention, orch pod-load, rig pending-work.
+status: L4-insight
+authored-by: advisor-peer-observer@your-rig
+date: 2026-04-13
+cited-captures:
+  - improvements-inbox.md 2026-04-13T12:54:50Z — broadcast primitive RSI (same batching-by-theme cluster)
+  - Mission 4 cmux stall (2026-04-13 midday) — packet-design + queue-for-cross-rig coordination
+metadata:
+  cli_surfaces_referenced:
+    - chatroom
+    - send
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - queue-handoff
+      - workflow-runtime
+      - watchdog
+      - alignment-trace
+      - looping-workflows
+      - intake-routing
+      - human-in-the-loop
+      - 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
+---
+
+# Attention queue
+
+Use this skill when coordinating work that must survive compaction, cross-agent handoffs, or multi-hour stall detection. Applies when you'd otherwise narrate status to chat or rely on memory for pending items.
+
+## Live protocol override
+
+Current live routing protocol:
+
+- **Known target / explicit owner that should wake now**: `rigx queue handoff <destination> "<body>" --type handoff --urgency soon`
+- **Passive durable assignment without wake-up**: `rigx queue create <destination> "<body>" --type handoff --urgency soon`
+- **Ambiguous or raw intake**: `rigx stream emit "<body>" ...`
+- **Direct dialogue / urgent 1:1 conversation**: `rig send ...`
+- **Summoned 3+ party roundtable**: `rig chatroom ...`
+
+Do not cargo-cult the earlier "stream everything with `--destination`" prototype shape into the
+live control-plane. Stream is now the ambiguous-intake lane, not the universal lane.
+
+## Core shape (minimum-viable discipline)
+
+1. **Author a queue file at** `substrate/shared-docs/rigs/<your-rig>/state/<your-pod>/<your-member>.queue.md`. Same per-pod directory as your session log.
+2. **Every known-target hot-potato work handoff** should arrive via `rigx queue handoff`, not via `rig send`. Use `rigx queue create` only when you intentionally want a passive durable item without wake-up.
+3. **State transitions** (start → promote; finish → complete; stuck → block; hand off → handoff; completed handed-off work notifies source → handoff-complete) are appended to the entry body with timestamp. Never in-place rewrites.
+4. **Cross-rig reads permitted; cross-rig writes forbidden.** Pod-as-authority-boundary doctrine.
+
+### Live command surface note
+
+When the queue control-plane wrapper is installed, treat queue identity as command-resolved, not
+seat-name-guessed:
+
+- `rigx queue whoami` resolves the durable queue that belongs to your current seat
+- `rigx queue list --mine` shows your queue without guessing from member name
+
+This matters for continuity successors such as `lead2` or `lead5`, which may intentionally share
+the canonical `lead.queue.md` file instead of owning a separate `lead2.queue.md` or `lead5.queue.md`.
+
+Known-target direct handoff on the live wrapper:
+
+```bash
+rigx queue handoff orch-lead5@your-rig "Need PM shaping on queue attention loop" --type handoff --urgency soon
+```
+
+Passive durable write without wake-up:
+
+```bash
+rigx queue create orch-lead5@your-rig "Need PM shaping on queue attention loop" --type handoff --urgency soon
+```
+
+## Six operations
+
+| Op | Effect |
+|---|---|
+| append | New entry (state=pending) on inbound request |
+| promote | state=in-progress when you start work |
+| complete | state=done with optional result |
+| block | state=blocked + blocked-on=<id or condition> |
+| handoff | state=handed-off + handed-off-to=<target>/<new-id>; send rig-send with `[queue-handoff:]` prefix to target |
+| handoff-complete | target signals source that handed-off work finished (closes feedback loop) |
+| escalate | walk authority chain when blocked past tier threshold |
+| defer / drop | push-to-later or drop-with-rationale |
+
+## When is something a queue handoff?
+
+**Queue handoff** (`rigx queue handoff`):
+- Asks a known recipient to do new work
+- Transfers ownership of pending work
+- Names a deliverable + acceptance criteria
+
+**NOT a queue handoff**:
+- Wake-ping `1`
+- PSA / broadcast / status update
+- Ack / courtesy notification / diagnostic ping / reply to question
+- Raw idea or bug where you do not yet know the right owner
+
+If you do not know the correct owner, emit to stream instead of guessing.
+
+## Tier-based ack + notification rules
+
+- **human-gate tier** (gated items; human-watching): mandatory ack on handoff; mandatory notification on completion
+- **agent-coordination tier** (standard inter-agent work): recommended ack + notification
+- **internal-self tier** (your own to-dos): optional
+
+## Read discipline
+
+- Read your own queue at turn start before picking up new work
+- Orchestrators read pod-member queues on wake cadence (`1` ping)
+- Advisor-pod reads cross-rig queues for composed views + human-attention
+- Past-threshold blocked entries surface during sweeps; execute escalate op if you can't self-unblock
+
+Recommended turn-start queue commands on the live wrapper:
+
+```bash
+rigx queue whoami
+rigx queue list --mine
+```
+
+### Resume-from-idle state sweep
+
+Agents returning from idle-standby (supervisor-wake-only pings; no substantive dispatch during the window) MUST sweep adjacent state before pulling new work. Minimum sweep:
+
+- Supervisor-log tail (~200 lines) at `rigs/kernel/state/supervisor-log.md`
+- human-attention.md at `substrate/shared-docs/human-attention.md`
+- Any doctrine-decisions added since last-active (`rigs/kernel/state/doctrine-decisions/`)
+- Partner queue files at `rigs/kernel/state/<pod>/<peer-member>.queue.md` (peer load-tracking for pairs)
+- **Fleet-changes-feed** at `substrate/shared-docs/fleet-changes-feed.md` (pull-native rollout surface; catches any fleet-wide doctrine / skill / convention / operational changes that landed during idle; filter by scope = fleet-wide + your rig/pod)
+
+**Trigger:** first active turn after ≥3 consecutive wake-only cycles OR on peer HA-check request. Sweep before responding to HA-check so the response is grounded in current reality, not stale memory.
+
+**Rationale:** own-queue-at-turn-start catches own-queue drift; adjacent-state drift is a separate failure class that requires its own read discipline. Composable with own-queue sweep (both at same reading point); adds ~2-5 minutes of read time; cheap insurance against peer-driven HA-check round-trips.
+
+**Worked example (genesis):** advisor-co-observer@your-rig after ~2h idle-standing-by on 2026-04-13 — 5-of-7 HA-check items out-of-sync when peer queried. Rule addition would have caught the drift pre-query via adjacent sweep on wake-to-active transition.
+
+## Status-not-chat corollary
+
+Your chat pane is for operational work + ad-hoc human exchanges. Your STATUS lives in queue files + composed views. If you finish work + hit a gate-requiring next-action, do NOT narrate to chat + idle-wait. Queue-handoff to advisor-pod with `tier: human-gate`. The operator doesn't watch agent panes; they watch human-attention.md (composed from human-gate queue entries).
+
+## Composed views (4 layers)
+
+- **Pod-load view** — who's loaded / blocked (orch reads)
+- **Rig pending-work** — cross-pod roll-up
+- **Fleet cross-rig** — host-wide
+- **human-attention** — human-gate-tier items across all queues (advisor-pod composes)
+
+v0: manual regen by orchestrators + advisor-pod.
+v0.5: terminal-node watch scripts auto-regen.
+v1: generative UI consuming structured queue data.
+
+## Codex-sandbox proxy-write pattern (sanctioned workaround)
+
+Codex members whose sandbox blocks substrate writes can still participate via proxy-write:
+- Codex authors content locally (e.g., `/tmp/<rig>-attention-queue/<member>.queue.md`)
+- Claude counterpart physically writes to substrate with sha256-verified integrity check
+- Subsequent state transitions via `[queue-update: <id> <new-state> <reason>]` rig-send from Codex to Claude-writer
+- Authorship preserved; only write-access delegated. Distinct from peer-injection (which is forbidden).
+
+## Escalation mechanics
+
+When entry stays blocked past tier threshold AND agent can't self-unblock:
+
+1. Identify escalation target per authority chain:
+   - Pod member → pod orchestrator
+   - Pod orch → rig orch-lead
+   - Rig orch-lead → kernel orch-lead OR advisor-pod (if human-gate)
+   - Skip-levels allowed when agent KNOWS correct target
+2. Create new entry in escalation-target's queue with `escalated-from: <source-id>`; state=pending; priority elevated
+3. Send handoff-shape rig-send: `[queue-escalate: <new-id>] <title> — blocked <Nh> on <reason>`
+4. Update own entry: state=escalated; escalated-to=<target>/<new-id>; transitions-log appended
+
+Threshold guidance: 1h human-gate / 4h agent-coordination / 24h internal-self. Rigs may tighten.
+
+## Task-close RSI-check (flywheel trigger)
+
+Every `complete` op on substantive work reflects briefly: "what did we learn? is this worth filing as L2 capture to improvements-inbox?"
+
+Two outcomes; both leave evidence in the transition trail:
+
+- **Novel observation worth filing:** append L2 capture entry to `rigs/kernel/state/improvements-inbox.md` per the v1 queue template (`state: pending` + transition trail started). Transition line in your own queue: `<ts> — RSI-check: filed <capture-id>`.
+- **Nothing novel:** transition line in your own queue: `<ts> — RSI-check: none`.
+
+Applies to substantive work-streams. Does NOT apply to:
+- Wake-pings (`1`) — not a work-stream
+- Trivial status updates — nothing to reflect on
+- Pure acks / routing-map updates — no work done
+
+Rationale: task-close is the deterministic interval that makes recursive-self-improvement mechanical rather than ad-hoc. Pattern named in skill-maturity-convention.md §"Task-close RSI-check discipline".
+
+## Push vs pull — when to use rig-send vs queue-write
+
+Not every communication belongs in the receiver's chat pane. The discipline mirrors status-not-chat: most inter-agent signals can flow through queue files (pull) rather than rig-sends (push). Reduces noise; respects receiver's attention cycle.
+
+**Sender's test:** *Does my message need the receiver's attention within their next turn cycle?*
+- **Yes → push** via `rig send` (lands in chat; receiver processes on next turn)
+- **No → pull** via queue-write (write to own queue OR receiver's queue via handoff; receiver sweeps at cadence)
+
+### Push (rig-send to chat) when:
+
+- Receiver needs info NOW to unblock their work
+- Question requires specific answer to proceed
+- Handoff is past ack-threshold + tier=human-gate (mandatory-ack window)
+- Blocker surfacing (can't self-unblock; need help from target)
+- human-gate item needing surface to advisor-pod
+- Destructive or time-critical coordination
+
+### Pull (queue-write only) when:
+
+- Status update / adoption signal / cascade-complete ack
+- Non-urgent ack (within tier threshold)
+- Information that can batch in receiver's curator sweep
+- Broadcast-receipt confirmation (receiver's cadence catches it)
+- Observed patterns or captures with no time pressure
+- Resync material for HA peers (they sweep on resume-from-idle)
+
+### Why this matters
+
+Push-as-default floods the receiver's chat pane with status that could be pulled. Today's rollout volume proved this: during attention-queue + EMM cascades, most acks arrived as push (rig-sends) when they could have been pull (queue-writes). Receiver (advisor-pod) had to process each ping; most were status signals needing no action.
+
+Pull-over-push is the queue primitive's whole point. Status lives in queue files; readers sweep at cadence; only genuine unblockers + gate-surfaces push to chat.
+
+### Worked example
+
+orch-lead@your-rig ack'd attention-queue cascade:
+- **Push version (what happened):** `rig send advisor-peer-observer@your-rig "[queue-handoff-ack: ...] ... cascaded to 8 pod members ..."` → lands in my chat; I read immediately; process the status
+- **Pull version (what should happen):** write ack-receipt to `rigs/openrig-build/state/orch/lead.queue.md` as state-transition on their adoption entry; I sweep their queue on my curator cadence; pick up the ack without chat-ping
+
+Ack-receipts for status are pull-native. Handoff-complete notifications for human-gate items stay push (they close feedback loops on time-sensitive work).
+
+### Corollary — orchestrator-to-advisor cadence
+
+Orchestrators writing to their own queue files lets advisor-pod read without being interrupted. The curator-sweep pattern (advisor reads pod queues on their cadence) is the canonical pull mechanism. Push only when time-matters.
+
+## Anti-patterns (don't do these)
+
+- **Chat-as-status** — narrating status/gates to your chat pane + idle-waiting. Use queue + human-attention instead.
+- **Duplicate-storage** — writing the same fact in queue + session-log + chat + mission-control. Queue is authoritative for in-flight state.
+- **Peer-injection** — writing directly to another agent's queue without their authorship. Only handoff op moves work cross-queue.
+- **Silent drops** — don't leave items in pending forever without state transitions. defer or drop with rationale.
+- **Global queue** — don't try to make one queue for everyone. Per-agent primary; compose for views.
+
+## Maturity status
+
+**L4-insight** per skill-maturity-convention. Applied liberally across the host; evolving via observation. Feedback loop: RSI filings reshape this skill; demotion valid if convention reveals wrong shape; promotion to L5-canon requires architect+reviewer pair-review per HOST-TOPOLOGY §7 SOP.
+
+Rollout date: 2026-04-13 host-wide adoption. 48h observation cycle active; RSI with learnings due ~2026-04-15.
+
+## Related
+
+- Spec (full reference): the internal attention-queue spec
+- Skill-maturity convention: `substrate/shared-docs/skill-maturity-convention.md`
+- Config-wrapper-code loop doctrine: `config-wrapper-code-loop` skill
+- HOST-TOPOLOGY §4 context-sharing patterns — attention queue is a new pattern here
+- SUBSTRATE-CONVENTIONS §7 HA session logs — queue lives in same per-pod directory

package/daemon/specs/agents/shared/skills/core/cross-host-rig-commands/SKILL.md

@@ -0,0 +1,190 @@
+---
+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 is ASYMMETRIC (verified vs current main, 2026-07-25)
+
+The `@host` sugar is **target-addressing only**, not sender-identity. A cross-host
+message's **From:** is `member@rig` — the sender carries **NO `@host` suffix**. The target
+supports `member@rig@<host>` for addressing; the sender does not reflect its own host in
+`From:`. **Do NOT teach or expect a host-qualified `from`** (in openrig-user / operator send
+docs or anywhere) until that core gap is fixed. (pm@your-rig verified this against
+current main, 2026-07-25 — a known asymmetry, not a doc error to paper over.)

package/daemon/specs/agents/shared/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
+      - alignment-trace
+      - 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