@openrig/cli 0.5.5 → 0.5.7

package/daemon/assets/continuity/apprentice-cutover.md

@@ -0,0 +1,19 @@
+# Apprentice handover — cutover fire stack
+
+Purpose: turn the second context threshold into an **owned baton** for a named mechanic. The
+notice may prepare and prove the cutover, but it must **never auto-rebind** the seat. The word of
+the named owner remains the gate.
+
+1. Confirm the prepare rung fired in an earlier evaluation pass and the successor is still the
+   exact accepted history and model.
+2. Reconcile every deposit and enumerate standing-duty custody. A duty named in the deposit set
+   but absent from the custody table stops the cutover.
+3. Record gate receipts G0–G3—gate, evidence, and worder—or the policy's declared simpler model.
+4. Create or identify one accountable mechanic baton. Record one-active-walker ownership and
+   staged/submitted/consumed delivery boundaries.
+5. The mechanic follows `seat-continuity-and-handover/references/apprentice-successor-seat-cutover.md`:
+   fence, derive, quiesce, realize the exact token, commit provenance, self-check READY, then
+   unfreeze only after the effect receipt.
+6. Preserve the predecessor's verbatim reach-back handle and pre-formed questions. Report
+   current seat identity, current generation, canonical tmux pane, duty acceptance, and usable
+   post-restore width in the final receipt.

package/daemon/assets/continuity/apprentice-prepare.md

@@ -0,0 +1,17 @@
+# Apprentice handover — prepare fire stack
+
+Purpose: turn the first context threshold into a prepared successor without moving seat
+authority. This is orchestration over existing verbs, never a second scheduler or workflow.
+
+1. Create a **fresh**, staged, unbound successor and persist its exact provider history.
+2. Run the **model-divergence gate** before installing anything. A fallback model or reused
+   history stops the stack because every later receipt would describe the wrong occupant.
+3. Install the **world** and have the successor state the product outcome in its own words.
+4. Install the **mission**, including the whole mission and its addressed primary sources.
+5. Install the **position** from the seat chain and issue an explicit authority-free grant.
+6. Derive the successor's layer-5 delta, verify it independently, then **introduce** incumbent
+   and apprentice to open a conversation grounded in real work.
+
+The successor packet carries `orienting-to-an-inherited-seat`; the incumbent notice carries
+`retiring-and-inheriting-a-seat`. Record delivery as staged, submitted, and consumed. No step in
+this stack binds the successor into the live seat.

package/daemon/assets/plugins/openrig-core/README.md

@@ -4,7 +4,7 @@ Canonical OpenRig skills and hooks for cross-runtime agent topology coordination
 
 ## What this plugin ships
 
-**Skills (16):** canonical OpenRig operating knowledge, including the public `refocusing` skill and
+**Skills (17):** canonical OpenRig operating knowledge, including the public `refocusing` skill and
 its path-only topology/work trace.
 
 **Hooks:** activity tracking, compaction continuity, and the default-on refocus channel. Refocus is

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

@@ -9,6 +9,7 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
 
 const DEFAULT_THRESHOLD = 2_600_000;
@@ -133,9 +134,65 @@ function renderTrace() {
   try { size = fs.statSync(transcriptPath).size; } catch {}
 
   const stateDir = path.join(home, "refocus");
-  const stateFile = path.join(stateDir, `${seat.replace(/[^A-Za-z0-9@._-]/g, "_")}.json`);
-  let state = { lastBytes: 0 };
-  try { state = JSON.parse(fs.readFileSync(stateFile, "utf8")) || state; } catch {}
+
+  // OPR.0.5.6.25 — state keys to the OCCUPANT, not the seat. A seat-keyed file made
+  // a fresh occupant inherit its predecessor's lastBytes (permanently zero growth on
+  // exactly the seats that swap) and its pending delivery. Identity derives from the
+  // hook family's own fields; the guarded expression never evaluates basename on an
+  // absent value. The legacy `${seat}.json` is NEVER read, imported, or rewritten —
+  // it stays on disk as diagnosis/migration material only.
+  const sanitize = (raw) => String(raw).replace(/[^A-Za-z0-9@._-]/g, "_");
+  const seatKey = sanitize(seat);
+  const firstString = (...vals) => {
+    for (const v of vals) if (typeof v === "string" && v.trim()) return v.trim();
+    return null;
+  };
+  const transcriptIdentity = input.transcript_path
+    ? path.basename(input.transcript_path, ".jsonl")
+    : input.transcriptPath
+      ? path.basename(input.transcriptPath, ".jsonl")
+      : null;
+  const identity = firstString(input.session_id, input.sessionId, transcriptIdentity);
+
+  // Bounded, deterministic, collision-stable key: lossy sanitization or truncation
+  // appends a stable short hash of the full pre-sanitization identity, so distinct
+  // identities stay distinct and every path stays inside the state directory.
+  const KEY_MAX = 64;
+  const keyFor = (raw) => {
+    const bounded = sanitize(raw).slice(0, KEY_MAX);
+    if (bounded === String(raw)) return bounded;
+    const suffix = crypto.createHash("sha256").update(String(raw)).digest("hex").slice(0, 8);
+    return `${bounded}__${suffix}`;
+  };
+
+  // No-identity diagnostic sentinel: an ACTIVE-EPISODE marker only — never a
+  // baseline, growth claim, pending, or fire. "#" is outside the key character
+  // class, so no derived identity path can ever collide with it. First missing
+  // event records and surfaces once; repeats stay silent; a valid-identity event
+  // clears the marker so a later distinct episode surfaces once again.
+  const sentinelFile = path.join(stateDir, `${seatKey}#no-identity-sentinel.json`);
+  if (identity === null) {
+    let sentinel = null;
+    try { sentinel = JSON.parse(fs.readFileSync(sentinelFile, "utf8")); } catch {}
+    if (!sentinel || sentinel.activeEpisode !== true) {
+      try {
+        fs.mkdirSync(stateDir, { recursive: true });
+        fs.writeFileSync(sentinelFile, JSON.stringify({ activeEpisode: true, recordedAt: new Date().toISOString() }));
+      } catch {}
+      process.stderr.write(`refocus: no session identity and no transcript path for ${seat} — measurement unavailable this episode\n`);
+    }
+    process.exit(0);
+  }
+  try {
+    const sentinel = JSON.parse(fs.readFileSync(sentinelFile, "utf8"));
+    if (sentinel && sentinel.activeEpisode === true) {
+      fs.writeFileSync(sentinelFile, JSON.stringify({ activeEpisode: false, clearedAt: new Date().toISOString() }));
+    }
+  } catch {}
+
+  const stateFile = path.join(stateDir, `${seatKey}__${keyFor(identity)}.json`);
+  let state = null;
+  try { state = JSON.parse(fs.readFileSync(stateFile, "utf8")) || null; } catch {}
   const persist = () => {
     try {
       fs.mkdirSync(stateDir, { recursive: true });
@@ -143,6 +200,26 @@ function renderTrace() {
     } catch {}
   };
 
+  if (state === null) {
+    // First observation for this occupant: the baseline is its OWN current size —
+    // growth accumulates from here; nothing is inherited. A zero-size read means
+    // the transcript is absent/unreadable, which is instrument absence, not a
+    // baseline: record zero only when that is what was genuinely measured.
+    state = { lastBytes: size, baselineAt: new Date().toISOString() };
+    persist();
+  } else if (size > 0 && size < Number(state.lastBytes || 0)) {
+    // Shrink clears pending and resets the baseline BEFORE due computation. The
+    // reset itself emits no refocus, and a stale pending can never ride through a
+    // reset into a delivery. Advisory once per reset episode: the reset moment is
+    // the dedupe (afterwards lastBytes === size), and the marker records in state.
+    delete state.pendingOn;
+    delete state.pendingAt;
+    state.lastReset = { at: new Date().toISOString(), fromBytes: Number(state.lastBytes || 0), toBytes: size };
+    state.lastBytes = size;
+    persist();
+    process.stderr.write(`refocus: transcript shrank for ${seat} — baseline reset, pending cleared\n`);
+  }
+
   const lastBytes = Number(state.lastBytes || 0);
   const grown = size > lastBytes ? size - lastBytes : 0;
   const onDemand = enabled(process.env.OPENRIG_REFOCUS_NOW, false);
@@ -212,7 +289,7 @@ function renderTrace() {
     },
   });
   process.stdout.write(output, () => {
-    state.lastBytes = size;
+    if (size > 0) state.lastBytes = size;
     state.firedAt = new Date().toISOString();
     state.firedOn = event;
     delete state.pendingOn;

package/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md

@@ -3,12 +3,12 @@ name: applying-a-permission-policy
 description: "Use when a permission policy is attached to a rig/seat (rig.yaml permission_policy:), or a user asks you to apply one, and you must translate that harness-neutral policy into the target harness's LIVE permission config — Claude settings.json / Codex config.toml / Pi run flags. Agent-driven and interactive: you read the policy, ground yourself in YOUR harness version, show the diff, and ask before writing. NOT for defining policies (that's the policy spec) and NOT a set-and-forget updater."
 metadata:
   openrig:
-    stage: established             # config cells VM-verified + cold-transfer PASSING (rerun #2, 627abbb6) + built-in SPEC FILES landed → skill translates FROM the spec (POINT-not-COPY). The two established criteria met 2026-08-04. Reviewed at push.
+    stage: established             # config cells VM-verified + cold-transfer PASSING (rerun #2) + built-in SPEC FILES landed → skill translates FROM the spec (POINT-not-COPY). The two established criteria met 2026-08-04. Reviewed at push.
     tested_against:                # VERSION STAMP — the whole point; re-verify at every harness bump
       claude_code: "2.1.220 — VM-CONFIRMED 2026-08-03 (all cells)"
       codex: "0.120.0 — VM-CONFIRMED 2026-08-03 (sandbox_mode/approval_policy; on-failure deprecated-but-accepted)"
       pi: "0.83.0 — VM-CONFIRMED 2026-08-03: --approve/--no-approve govern PROJECT-RESOURCE TRUST, NOT tool permissions; Pi has NO permission surface (see Pi leg)"
-    verification_status: "Live-verified 2026-08-03/04 (dev-qa @ v-openrig-build). Claude 2.1.220 + Codex 0.120.0 config cells CONFIRMED live. Pi 0.83.0 divergence folded (flags = project-resource trust, not a permission gate). Cold-transfer rerun #1 blocked on the force_push/push_to_remote prefix collision → added the PREFIX-COLLISION rule. Cold-transfer rerun #2 (qitem 001c95fd, verdict SHA 627abbb6bf08ad2f350e2101f11438975def7b193b8da8bbcb747647239afc358): TRANSFERS — all 5 gate checks pass (collision resolved deterministically without asking; single ordinary write confirmation; defaultMode floor written; Codex workspace-write/on-request; Pi compute-nothing). Blocking collision/floor defect CLOSED → gate cleared, 4.8-shippable (provisional-with-passing-cold-transfer). Non-blocking seam closed: the built-in SPEC FILES landed (arch-accepted, source:builtin) → skill translates FROM the spec, interim in-skill pinned summary retired (POINT-not-COPY). stage:ESTABLISHED 2026-08-04 — both criteria met."
+    verification_status: "Live-verified 2026-08-03/04. Claude 2.1.220 + Codex 0.120.0 config cells CONFIRMED live. Pi 0.83.0 divergence folded (flags = project-resource trust, not a permission gate). Cold-transfer rerun #1 blocked on the force_push/push_to_remote prefix collision → added the PREFIX-COLLISION rule. Cold-transfer rerun #2: TRANSFERS — all 5 gate checks pass (collision resolved deterministically without asking; single ordinary write confirmation; defaultMode floor written; Codex workspace-write/on-request; Pi compute-nothing). Blocking collision/floor defect CLOSED → gate cleared, 4.8-shippable (provisional-with-passing-cold-transfer). Non-blocking seam closed: the built-in SPEC FILES landed (arch-accepted, source:builtin) → skill translates FROM the spec, interim in-skill pinned summary retired (POINT-not-COPY). stage:ESTABLISHED 2026-08-04 — both criteria met."
 ---
 
 # Applying a permission policy
@@ -117,4 +117,4 @@ Built-ins ship read-only in the package (canonical names); copy-to-customize int
 This skill TRANSLATES + APPLIES only. It does **not** define policies (the policy spec does) and does **not** enforce at the daemon (OpenRig is agnostic). Spec = *what* (neutral intent); this skill = *how, on this harness version* (the caveated, version-stamped translation).
 
 ---
-*Stage: ESTABLISHED (2026-08-04) — both criteria met: (1) cold-transfer PASSING (rerun #2, verdict SHA 627abbb6, all 5 gate checks TRANSFER); (2) the built-in policy SPEC FILES landed (`source: builtin`, arch-accepted) as the authoritative source — the skill now translates FROM the spec and the interim in-skill pinned summary is retired (POINT-not-COPY). Config cells VM-CONFIRMED (Claude 2.1.220 / Codex 0.120.0); Pi has no permission surface (compute-nothing). Reviewed at push. feedback.md maintained.*
+*Stage: ESTABLISHED (2026-08-04) — both criteria met: (1) cold-transfer PASSING (rerun #2, all 5 gate checks TRANSFER); (2) the built-in policy SPEC FILES landed (`source: builtin`, arch-accepted) as the authoritative source — the skill now translates FROM the spec and the interim in-skill pinned summary is retired (POINT-not-COPY). Config cells VM-CONFIRMED (Claude 2.1.220 / Codex 0.120.0); Pi has no permission surface (compute-nothing). Reviewed at push. feedback.md maintained.*

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

@@ -263,17 +263,12 @@ For real depth, these are the load-bearing canonical docs:
 | `openrig/docs/reference/agent-spec.md` | The AgentSpec YAML format — resources, profiles, imports |
 | `openrig/docs/reference/agent-startup-guide.md` | The 7-layer startup layering model; delivery hints |
 | the product taxonomy | Canonical vocabulary (read literally) |
-| `substrate/shared-docs/HOST-TOPOLOGY.md` | Host-level doctrine — rig classes, context patterns, lifecycle, authoring SOP |
-| `substrate/shared-docs/SUBSTRATE-CONVENTIONS.md` | Filesystem layout doctrine for substrate |
+| `openrig-operating-model` skill | Placement and operating-model guidance — topology and work trees, context altitude |
+| `openrig-architect` skill | Rig and topology authoring |
 | `https://agentskills.io/specification` | The cross-runtime skill standard |
 
-If you're going to be authoring rigs, read `HOST-TOPOLOGY.md` §7 (the
-authoring SOP) before touching YAML.
-
-If you're going to be doing skill work, read
-the factory-design reference and the
-`operating-the-skill-library` skill that lives in
-`substrate/shared-docs/rigs/skill-library/agents/shared/skills/`.
+If you're going to be authoring rigs, use the `openrig-architect` skill before
+touching YAML.
 
 ---
 

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

@@ -0,0 +1,34 @@
+---
+name: loading-addressable-markdown
+description: Use when a mission, slice, dashboard, or task references Markdown as path#h2-slug or path#h2-slug/h3-slug outside the OpenRig context-pack library.
+---
+
+# Loading Addressable Markdown
+
+## Overview
+
+Load exactly one addressed Markdown section from any filesystem tree. The resolver mirrors OpenRig's shipped H2/H3 grammar without requiring the file to live in the context library.
+
+## Use
+
+Run the bundled script. Relative file references resolve from `--root`; without it they resolve from the current directory.
+
+```bash
+node ~/.agents/skills/loading-addressable-markdown/scripts/resolve-markdown.mjs \
+  --root /path/to/mission \
+  'slices/09-source-cleanup/SPEC.md#proposal'
+```
+
+The accepted forms are:
+
+- `file.md` — whole file
+- `file.md#h2-slug` — full H2 span, including child sections
+- `file.md#h2-slug/h3-slug` — full H3 span
+
+Slugs are lowercase; Markdown emphasis/code markers are removed; each other non-alphanumeric run becomes `-`. Duplicate or missing paths fail loudly. Headings inside fenced code blocks are ignored.
+
+## Common mistakes
+
+- Do not use `rig context get` for an arbitrary filesystem path; that command resolves context-library refs.
+- Do not hand-slice headings with `sed` or line numbers; the bundled resolver owns span and fence behavior.
+- Quote addresses in shell commands.

package/daemon/assets/plugins/openrig-core/skills/loading-addressable-markdown/scripts/resolve-markdown.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MIN_LEVEL = 2;
+const MAX_LEVEL = 3;
+
+export class AddressResolutionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AddressResolutionError";
+  }
+}
+
+export function slugifyHeader(title) {
+  return title
+    .toLowerCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function parseAddress(address) {
+  const hashCount = (address.match(/#/g) ?? []).length;
+  if (hashCount > 1) {
+    throw new AddressResolutionError(`address '${address}' must contain at most one '#' separator`);
+  }
+
+  const [ref, headerPart] = hashCount === 1 ? address.split("#") : [address, undefined];
+  if (!ref) throw new AddressResolutionError(`address '${address}' has no file before '#'`);
+  if (headerPart === undefined) return { ref, headerPath: [] };
+
+  const headerPath = headerPart.split("/");
+  if (headerPath.some((segment) => segment.length === 0)) {
+    throw new AddressResolutionError(`address '${address}' has an empty header segment`);
+  }
+  if (headerPath.length > MAX_LEVEL - MIN_LEVEL + 1) {
+    throw new AddressResolutionError(`address '${address}' is too deep; addresses target H2 and H3 only`);
+  }
+  return { ref, headerPath };
+}
+
+function scanHeaders(lines) {
+  const hits = [];
+  let fence = null;
+
+  for (let lineNumber = 0; lineNumber < lines.length; lineNumber++) {
+    const line = lines[lineNumber];
+    const fenceMatch = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      const marker = fenceMatch[1][0];
+      const length = fenceMatch[1].length;
+      if (!fence) fence = { marker, length };
+      else if (fence.marker === marker && length >= fence.length) fence = null;
+      continue;
+    }
+    if (fence) continue;
+
+    const heading = line.match(/^(#{1,6})\s+(.*\S)\s*$/);
+    if (heading) hits.push({ level: heading[1].length, title: heading[2], line: lineNumber });
+  }
+  return hits;
+}
+
+export function parseMarkdownSections(text) {
+  const lines = text.split("\n");
+  const headers = scanHeaders(lines);
+  const sections = [];
+  let currentH2 = null;
+
+  for (let index = 0; index < headers.length; index++) {
+    const heading = headers[index];
+    if (heading.level < MIN_LEVEL || heading.level > MAX_LEVEL) {
+      if (heading.level < MIN_LEVEL) currentH2 = null;
+      continue;
+    }
+
+    const slug = slugifyHeader(heading.title);
+    if (heading.level === 2) currentH2 = slug;
+    const headerPath = heading.level === 2
+      ? [slug]
+      : currentH2 !== null
+        ? [currentH2, slug]
+        : [slug];
+    const fullEnd = headers.slice(index + 1).find((next) => next.level <= heading.level)?.line ?? lines.length;
+    const ownEnd = headers[index + 1]?.line ?? lines.length;
+
+    sections.push({
+      level: heading.level,
+      title: heading.title,
+      headerPath,
+      headerLine: heading.line,
+      text: lines.slice(heading.line, fullEnd).join("\n"),
+      ownText: lines.slice(heading.line, ownEnd).join("\n"),
+    });
+  }
+  return sections;
+}
+
+export function resolveAddress(text, headerPath) {
+  if (headerPath.length === 0) {
+    throw new AddressResolutionError("a bare file resolves without section lookup");
+  }
+
+  const sections = parseMarkdownSections(text);
+  const wanted = headerPath.join("/");
+  const hits = sections.filter((section) => section.headerPath.join("/") === wanted);
+  if (hits.length > 1) {
+    throw new AddressResolutionError(
+      `address '#${wanted}' is AMBIGUOUS: ${hits.length} sections match at lines ${hits.map((hit) => hit.headerLine + 1).join(", ")}`,
+    );
+  }
+  if (hits.length === 1) return hits[0];
+
+  const parentPath = headerPath.slice(0, -1).join("/");
+  const candidates = sections
+    .filter((section) => section.headerPath.slice(0, -1).join("/") === parentPath)
+    .map((section) => section.headerPath.join("/"));
+  throw new AddressResolutionError(
+    `address '#${wanted}' matches no header. ` +
+      (candidates.length > 0
+        ? `Addressable sections under '${parentPath || "(top)"}': ${candidates.join(", ")}.`
+        : `Addressable sections: ${sections.map((section) => section.headerPath.join("/")).join(", ") || "(none)"}.`),
+  );
+}
+
+function usage() {
+  return "Usage: resolve-markdown.mjs [--root DIR] FILE[#h2-slug[/h3-slug]]\n";
+}
+
+async function main(argv) {
+  let root = process.cwd();
+  const args = [...argv];
+
+  if (args[0] === "--help" || args[0] === "-h") {
+    process.stdout.write(usage());
+    return;
+  }
+  if (args[0] === "--root") {
+    if (!args[1]) throw new AddressResolutionError("--root needs a directory");
+    root = path.resolve(args[1]);
+    args.splice(0, 2);
+  }
+  if (args.length !== 1) throw new AddressResolutionError(usage().trim());
+
+  const { ref, headerPath } = parseAddress(args[0]);
+  const filePath = path.isAbsolute(ref) ? ref : path.resolve(root, ref);
+  const text = await readFile(filePath, "utf8");
+  process.stdout.write(headerPath.length === 0 ? text : resolveAddress(text, headerPath).text);
+}
+
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error.name ?? "Error"}: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

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

@@ -1,134 +1,98 @@
 ---
 name: messaging-the-human
-description: |
-  When and who should send a message to the human operator, at
-  operator-human@your-rig — which routes straight to his Slack. Role-gated:
-  orchestrators and PMs use discretion to send anything worth his attention
-  (blockers, ships/completions, changes, good news); every other agent may
-  message him ONLY for a real blocker he can personally unblock, and routes
-  everything else through an orchestrator. Use to protect a scarce human's
-  manage-by-exception attention. NOT for agent-to-agent coordination (send/queue
-  a peer) or durable agent work-handoffs (use the queue to the owning seat).
+description: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."
 metadata:
+  cli_surfaces_referenced:
+    - gateway human add
+    - gateway human list
+    - queue block
+    - queue handoff
+    - queue transitions
+    - send
   openrig:
-    stage: provisional   # operator-directed, freshly authored 2026-07-30; hardens as agents use it
-    audience: ALL agents (universal); orchestrators + PMs are the primary discretionary senders
+    stage: provisional
+    audience: all agents
     sibling_skills:
       - queue-handoff
-      - status-not-chat-orchestrator
       - human-in-the-loop
       - openrig-user
 ---
 
 # Messaging the Human
 
-## The one-line mechanism
+The human is an addressable participant, but their attention is scarce and they
+may not be at a terminal. Anything that must survive their absence needs a
+durable queue row; the gateway turns the human blocker on that row into the
+external notification.
+
+Any seat may contact the human directly for a real escalation. Orchestrators
+and product managers may also send updates they judge the human would want to
+know. Do not add a routing intermediary merely because of your role.
+
+## The supported route
+
+First discover the registered human identity. Never invent or remember an
+address:
+
+```bash
+rig gateway human list --json
+```
+
+Use `humans[].entityId` to derive the durable blocker as `<entityId>@host`.
+The entity id must use the human-seat prefix (`human` or `human-...`); if it
+does not, stop and repair the registration rather than guessing. The returned
+`humans[].address` is the gateway delivery address, not the `--on` value. If no
+unambiguous registered human is returned, stop: registration is lifecycle work
+(`rig gateway human add --help`), not an address to guess.
+
+Keep the work row owned by the agent who must resume it, then park that row on
+the registered human:
+
+```bash
+rig queue block <qitem-id> --on <entityId>@host \
+  --summary "<decision owed>" \
+  --evidence-ref "<durable artifact the human should judge>" \
+  --continuation "<what resumes after the answer>"
+```
+
+The gateway resolves the registered human to the configured connector, sends
+the Slack notification, and records its receipt on the same row. Confirm the
+effect from the append-only history:
 
 ```bash
-rig send operator-human@your-rig "your message"
+rig queue transitions <qitem-id>
 ```
 
-That goes straight to the human's Slack — that is the *how* for **text**. For **images**
-(screenshots, renders), send through the **image connector** instead; text and images are separate
-live channels today (a release upgrade will unify them). Either way the *how* is trivial; everything
-below is the *when* and the *who* — the part that actually matters.
-
-## The mental model: the human is a scarce attention resource managing by exception
-
-There is one human. He is single-threaded across many agents, so his attention
-is the bottleneck of the whole system. He operates **by exception**: he wants to
-be pulled in when it genuinely matters and left alone when it doesn't. Every
-message you send spends a slice of that scarce attention.
-
-So the rule is not "can I reach him" (you can, trivially — one `rig send`). The
-rule is **should this reach him, coming from me**. Two things decide that: **who
-you are** (your role sets how much of his attention you're trusted to spend) and
-**what it is** (does it clear the bar for that role). Get the altitude wrong in
-either direction and you fail him: spam his Slack with noise, or sit silently on
-something he needed to know or could have unblocked.
-
-## WHO sends WHAT
-
-### If you are an ORCHESTRATOR or a PRODUCT MANAGER — use discretion
-
-You are the primary channel to the human. You may send **more than blockers** —
-anything you judge he would want to know:
-
-- something **shipped**, **completed**, or a **milestone** was hit
-- something **important happened**, or something **changed**
-- **environmental** changes (infra, hosts, tools, external state)
-- **good news**
-- anything that needs his attention, or is simply **good for him to know**
-
-There is no hard trigger here — it is judgment, and you are trusted with it. The
-test is: **"would he want to know this?"** If yes, send it. Lean toward sending
-genuine signal and real good news; do not manufacture noise or narrate routine
-churn. Discernment is the skill: you are curating his attention, not flooding it.
-
-### The v0 event classes — reach out on these, unprompted
-
-"Use discretion" left the *when* unspecified, so it did not happen — the channel exists and nobody
-reaches for it. Here are the **named event classes** that should trigger a proactive message —
-anchors for the judgment, not an exhaustive gate:
-
-- **Model-fallback boots** — a seat that came up on a fallback model instead of its pinned one. Send
-  on **every occurrence**; a silent downgrade is exactly what the human needs to see.
-- **Capacity / authority requests** — you need a fork/spin-up authorization, a spend-or-limit call, or
-  any authority only the human holds. This is a **guaranteed-answer** path — don't sit blocked on it.
-- **Security-category flags** — anything in the security / consequence-boundary class.
-- **Acceptance / milestone moments** — a slice proven, a release cut, a real "it's done and it works."
-- **Human-addressed work blocked beyond its settle window** — a decision or request routed to the
-  human that has sat past the time it should have moved.
-- **Idle / stall alarms** — the line stopped and isn't resuming (the idle-detector's signal).
-
-These are v0, drawn from real rulings; treat them as the anchors that make the *when* concrete. New
-classes earn their place the same way — from a real event the human wanted to know about.
-
-**Why this is a norm, not a nicety — WORKS ≠ USED.** A channel that *works* is not a channel that is
-*used*. This path is proven only when agents **reach for it unprompted** across the lifecycle — a
-boot, a blocker, a ship, an alarm. If the channel exists and nobody reaches for it, the human is
-blind by default. Reaching out on these classes is the job, not an interruption of it.
-
-### If you are ANY OTHER agent — blockers only
-
-You may message the human **only** when you are **blocked** and **he** is the one
-who can unblock you. That authority is universal — you do **not** have to be an
-orchestrator to raise a real blocker. But a blocker is the **only** thing you may
-send him directly.
-
-For anything that is **not** a blocker — an update, an idea, a question, an
-interesting finding — do **not** message the human. Send it to your
-**orchestrator**, who decides whether it is the human's role to handle or whether
-it is handled another way. The orchestrator/PM layer is the filter that protects
-the human's attention; routing through it is how the system keeps his queue at
-manage-by-exception altitude.
-
-## What counts as a real blocker (for non-orchestrator / non-PM agents)
-
-You are **blocked** AND **only the human** can clear it:
-
-- a **decision** only he can make,
-- **access / a credential / an authority** only he holds,
-- an **external action** only he can take (something in the real world, an
-  account or service he owns).
-
-Not a blocker: "I'd like a second opinion," "which approach do you prefer,"
-"here's a cool thing I found." Those go to your **orchestrator**. And if an
-orchestrator or PM *could* unblock you, route to them first — reserve the human
-for what genuinely only he can do.
-
-## How to write it (so it earns the interruption)
-
-- **Lead with the point.** Blocker: what is blocked + exactly what you need from
-  him. Update: the headline first, detail after.
-- **Full absolute paths.** No internal jargon he can't parse. **No backticks** in
-  `rig send` bodies (they trigger shell substitution).
-- `rig send` is an **ephemeral conversation** to his Slack. For a durable *agent*
-  work-handoff, use the queue to the owning seat — not the human.
-
-## Quick reference
-
-| You are… | You may send the human… |
-|---|---|
-| Orchestrator / PM | anything worth his attention — blockers, ships, completions, changes, good news (your discretion) |
-| Any other agent | a real blocker only he can unblock — **and nothing else** (everything else → your orchestrator) |
+The row is the obligation and the audit trail. Slack is the attention leg. A
+reply resolves the durable blocker and wakes the row owner; it does not create
+a second private work stream.
+
+## When to use it
+
+Escalate directly when only the human can supply the missing capability:
+
+- a decision or irreversible judgment only they own;
+- access, credentials, authority, or capacity only they can grant;
+- an external action only they can perform;
+- a security-class or provider/model-fallback event they need to know about.
+
+Orchestrators and product managers may additionally send meaningful milestone,
+environment, or completion updates. Prefer signal over routine narration.
+
+## Boundaries
+
+- `rig send` sends text to an agent's terminal. It is not the Slack route and
+  does not create a durable human obligation.
+- An unregistered or ambiguous human identity must fail loudly. Register or
+  repair the identity; never downgrade it to an agent seat or a guessed
+  `@external` address.
+- Agent-to-agent work that needs closure uses `rig queue handoff`, not this
+  human-blocker path.
+- Deferred work that is not imminent belongs in the mission workspace, not on
+  the queue.
+
+## Writing the escalation
+
+Lead with what is blocked and the exact decision or action needed. Point at the
+durable evidence instead of pasting a second copy, and name the continuation so
+the system can resume the right work when the answer arrives.