@openrig/cli 0.5.5 → 0.5.7

package/daemon/context-packs/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs

@@ -0,0 +1,487 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+
+const TEXT_LIMIT = 4000;
+const BASE64_RUN = 800; // strip contiguous base64 runs at least this long (screenshots, data URIs)
+
+function sha256(text) {
+  return crypto.createHash("sha256").update(String(text ?? "")).digest("hex").slice(0, 16);
+}
+
+// R3: replace binary / base64 payloads (data: URIs, long base64 runs) with a compact marker,
+// so a single screenshot block does not blow the transcript into un-chunkable size.
+function stripBinary(text) {
+  let s = String(text ?? "");
+  s = s.replace(/data:([\w.+-]+\/[\w.+-]+)?;base64,[A-Za-z0-9+/=\s]{200,}/g,
+    (m, mime) => `[binary omitted: ~${m.length} bytes${mime ? `, ${mime}` : ""}]`);
+  s = s.replace(new RegExp(`[A-Za-z0-9+/]{${BASE64_RUN},}={0,2}`, "g"),
+    (m) => `[base64 omitted: ~${m.length} bytes]`);
+  return s;
+}
+const DEFAULT_OUT = "/tmp/claude-compaction-restore";
+
+function parseArgs(argv) {
+  const args = {
+    jsonl: null,
+    out: DEFAULT_OUT,
+    cwd: process.cwd(),
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--jsonl") args.jsonl = argv[++i];
+    else if (arg === "--out") args.out = argv[++i];
+    else if (arg === "--cwd") args.cwd = argv[++i];
+    else if (arg === "--json") args.json = true;
+    else if (!arg.startsWith("-") && !args.jsonl) args.jsonl = arg;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+
+  return args;
+}
+
+function readJsonLines(file) {
+  const raw = fs.readFileSync(file, "utf8");
+  return raw
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        return { type: "parse-error", line: index + 1, error: String(error), raw: line };
+      }
+    });
+}
+
+function findLatestJsonl(cwd) {
+  const projectsRoot = path.join(os.homedir(), ".claude", "projects");
+  if (!fs.existsSync(projectsRoot)) return null;
+
+  const encoded = cwd ? cwd.replaceAll("/", "-") : null;
+  const candidates = [];
+  const roots = [];
+
+  if (encoded) {
+    const exact = path.join(projectsRoot, encoded);
+    if (fs.existsSync(exact)) roots.push(exact);
+  }
+  roots.push(projectsRoot);
+
+  for (const root of roots) {
+    const result = spawnSync("find", [root, "-name", "*.jsonl", "-maxdepth", root === projectsRoot ? "4" : "2"], {
+      encoding: "utf8",
+    });
+    if (result.status !== 0 && !result.stdout) continue;
+    for (const file of result.stdout.split(/\r?\n/).filter(Boolean)) {
+      try {
+        const stat = fs.statSync(file);
+        candidates.push({ file, mtimeMs: stat.mtimeMs });
+      } catch {
+        // Ignore raced/deleted transcript files.
+      }
+    }
+    if (candidates.length) break;
+  }
+
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return candidates[0]?.file ?? null;
+}
+
+function stringifyContent(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((block) => {
+        if (typeof block === "string") return block;
+        if (block?.type === "text") return block.text ?? "";
+        if (block?.type === "image") return `[image omitted: ${block.source?.media_type ?? "image"}]`;
+        if (block?.type === "tool_use") return `[tool_use:${block.name}] ${JSON.stringify(block.input ?? {})}`;
+        if (block?.type === "tool_result") return `[tool_result] ${truncate(stripBinary(stringifyContent(block.content)), TEXT_LIMIT)}`;
+        return JSON.stringify(block);
+      })
+      .join("\n");
+  }
+  if (content == null) return "";
+  return JSON.stringify(content);
+}
+
+function truncate(text, max) {
+  const s = String(text ?? "");
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}\n[...truncated ${s.length - max} chars...]`;
+}
+
+function walkStrings(value, acc = []) {
+  if (typeof value === "string") acc.push(value);
+  else if (Array.isArray(value)) value.forEach((item) => walkStrings(item, acc));
+  else if (value && typeof value === "object") Object.values(value).forEach((item) => walkStrings(item, acc));
+  return acc;
+}
+
+function normalizeFile(candidate, cwd) {
+  let file = candidate.trim().replace(/[),.;:'"`\]\}>]+$/g, "").replace(/^[('"`<\[]+/g, "");
+  if (!file || file.includes("\n")) return null;
+  if (/\.(?:md|mdx|txt|json|jsonl|yaml|yml|toml|ts|tsx|js|jsx|mjs|cjs|py|sh|rs|go|sql|css|scss|html|xml|svg|csv|log|lock)\//i.test(file)) return null;
+  if (file.startsWith("~")) file = path.join(os.homedir(), file.slice(1));
+  let normalized = null;
+  if (file.startsWith("/")) normalized = path.normalize(file);
+  else if (file.startsWith("./") || file.startsWith("../")) normalized = path.normalize(path.resolve(cwd, file));
+  else if (/^[A-Za-z0-9_@.+-][A-Za-z0-9_@.+/\-:]*\.[A-Za-z0-9]+$/.test(file)) {
+    normalized = path.normalize(path.resolve(cwd, file));
+  } else if (/^(CLAUDE|AGENTS|README|DESIGN|CULTURE|MEMORY)\.md$/.test(file)) {
+    normalized = path.normalize(path.resolve(cwd, file));
+  }
+
+  if (!normalized) return null;
+  try {
+    if (fs.existsSync(normalized) && fs.statSync(normalized).isDirectory()) return null;
+  } catch {
+    // Keep the candidate if stat races; the restore agent can decide.
+  }
+  return normalized;
+}
+
+function extractPaths(text, cwd) {
+  const paths = new Set();
+  const s = String(text ?? "");
+  const absolute = /(?:^|[\s"'(<\[])(\/(?:Users|private|tmp|var|opt|Volumes)\/[^\s"'()\]<>]+)/g;
+  const relative = /(?:^|[\s"'(<\[])((?:\.{1,2}\/)?[A-Za-z0-9_@.+-][A-Za-z0-9_@.+/\-:]*\.(?:md|mdx|txt|json|jsonl|yaml|yml|toml|ts|tsx|js|jsx|mjs|cjs|py|sh|rs|go|sql|css|scss|html|xml|svg|csv|log|lock))(?:$|[\s"')>\],.;:])/g;
+  const namedMarkdown = /(?:^|[\s"'(<\[])((?:CLAUDE|AGENTS|README|DESIGN|CULTURE|MEMORY)\.md)(?:$|[\s"')>\],.;:])/g;
+
+  for (const regex of [absolute, relative, namedMarkdown]) {
+    let match;
+    while ((match = regex.exec(s)) !== null) {
+      const normalized = normalizeFile(match[1], cwd);
+      if (normalized) paths.add(normalized);
+    }
+  }
+  return [...paths];
+}
+
+function createRegistry() {
+  const files = new Map();
+  let sequence = 0;
+
+  return {
+    add(file, kind, source) {
+      if (!file) return;
+      const existing = files.get(file) ?? {
+        path: file,
+        kinds: {},
+        sources: new Set(),
+        firstSeen: sequence,
+        lastSeen: sequence,
+      };
+      existing.kinds[kind] = (existing.kinds[kind] ?? 0) + 1;
+      existing.sources.add(source);
+      existing.lastSeen = sequence;
+      files.set(file, existing);
+    },
+    tick() {
+      sequence += 1;
+    },
+    values() {
+      return [...files.values()].map((entry) => ({
+        ...entry,
+        sources: [...entry.sources].slice(0, 8),
+      }));
+    },
+  };
+}
+
+function toolKind(name, input) {
+  if (["Write", "Edit", "MultiEdit", "NotebookEdit"].includes(name)) return "written";
+  if (name === "Read") return "read";
+  if (["Grep", "Glob", "LS"].includes(name)) return "discovered";
+  if (name === "Bash") {
+    const command = input?.command ?? "";
+    if (/\b(apply_patch|tee|touch|mkdir|mv|cp|rm)\b|(^|[^>])>{1,2}[^>]/.test(command)) return "shell-write";
+    return "shell-mentioned";
+  }
+  return "mentioned";
+}
+
+function scoreFile(entry) {
+  const ext = path.extname(entry.path).toLowerCase();
+  let score = 0;
+  if (entry.kinds.written) score += 40;
+  if (entry.kinds["shell-write"]) score += 30;
+  if (entry.kinds["file-history"]) score += 35;
+  if (ext === ".md" || ext === ".mdx") score += 20;
+  if (entry.kinds.read) score += 10;
+  if (entry.kinds.discovered) score += 4;
+  if (/\/docs\/as-built\//.test(entry.path)) score += 25;
+  if (/(codemap|architecture|CLAUDE|AGENTS|README|DESIGN|CULTURE|session\.log|queue\.md)/i.test(entry.path)) score += 15;
+  score += Math.min(10, Object.values(entry.kinds).reduce((a, b) => a + b, 0));
+  return score;
+}
+
+function discoverDocs(cwd) {
+  const candidates = [
+    "CLAUDE.md",
+    "AGENTS.md",
+    "README.md",
+    "docs/as-built",
+    "docs",
+  ];
+  const docs = new Set();
+
+  for (const candidate of candidates) {
+    const full = path.resolve(cwd, candidate);
+    if (!fs.existsSync(full)) continue;
+    const stat = fs.statSync(full);
+    if (stat.isFile()) docs.add(full);
+    if (stat.isDirectory()) {
+      const result = spawnSync("find", [full, "-maxdepth", candidate === "docs" ? "2" : "1", "-type", "f", "-name", "*.md"], {
+        encoding: "utf8",
+      });
+      for (const file of result.stdout.split(/\r?\n/).filter(Boolean)) {
+        if (/as-built|codemap|architecture|README|overview/i.test(file)) docs.add(path.normalize(file));
+      }
+    }
+  }
+
+  return [...docs].sort();
+}
+
+function analyze(jsonlPath, cwd) {
+  const records = readJsonLines(jsonlPath);
+  const registry = createRegistry();
+  const transcript = [];
+  const narrative = []; // R4: message-turns only (assistant/user text), no tool bodies
+  const readTargets = new Map(); // R1: tool_use_id -> file_path for Read calls
+  const cwdCounts = new Map();
+  let sessionId = null;
+
+  for (const record of records) {
+    registry.tick();
+    if (record.sessionId || record.session_id) sessionId = record.sessionId ?? record.session_id;
+    if (record.cwd) {
+      cwdCounts.set(record.cwd, (cwdCounts.get(record.cwd) ?? 0) + 1);
+      cwd = record.cwd;
+    }
+
+    if (record.type === "file-history-snapshot") {
+      const backups = record.snapshot?.trackedFileBackups ?? {};
+      for (const file of Object.keys(backups)) registry.add(path.normalize(file), "file-history", "file-history-snapshot");
+    }
+
+    const message = record.message;
+    if (!message) continue;
+    const role = message.role ?? record.type ?? "unknown";
+    const content = message.content;
+
+    if (typeof content === "string") {
+      transcript.push(`\n## ${role}\n\n${content}`);
+      narrative.push(`\n## ${role}\n\n${content}`);
+      for (const file of extractPaths(content, cwd)) registry.add(file, "mentioned", `${role}:text`);
+      continue;
+    }
+
+    if (!Array.isArray(content)) continue;
+    const parts = [];
+    const narrativeParts = [];
+    for (const block of content) {
+      if (block?.type === "text") {
+        parts.push(block.text ?? "");
+        narrativeParts.push(block.text ?? "");
+        for (const file of extractPaths(block.text ?? "", cwd)) registry.add(file, "mentioned", `${role}:text`);
+      } else if (block?.type === "tool_use") {
+        const name = block.name ?? "unknown";
+        const input = block.input ?? {};
+        parts.push(`\n[tool_use:${name}]\n${JSON.stringify(input, null, 2)}`);
+        if (name === "Read" && block.id && (input.file_path || input.path)) {
+          readTargets.set(block.id, input.file_path || input.path);
+        }
+        const kind = toolKind(name, input);
+        if (input.file_path) registry.add(normalizeFile(input.file_path, cwd), kind, `tool:${name}:file_path`);
+        if (input.path) registry.add(normalizeFile(input.path, cwd), kind, `tool:${name}:path`);
+        if (input.notebook_path) registry.add(normalizeFile(input.notebook_path, cwd), kind, `tool:${name}:notebook_path`);
+        for (const text of walkStrings(input)) {
+          for (const file of extractPaths(text, cwd)) registry.add(file, kind, `tool:${name}:input`);
+        }
+      } else if (block?.type === "tool_result") {
+        const resultText = stripBinary(stringifyContent(block.content));
+        const target = block.tool_use_id && readTargets.get(block.tool_use_id);
+        if (target) {
+          // R1: a Read result reproduces a whole file — emit a pointer, not the body.
+          // The live file is current; this transcript copy is a snapshot that may be stale.
+          const lineCount = resultText.split("\n").length;
+          parts.push(`\n[tool_result: Read ${target} — ${lineCount} lines, sha256 ${sha256(resultText)} — READ THE LIVE FILE; this snapshot may be stale]`);
+        } else {
+          parts.push(`\n[tool_result]\n${truncate(resultText, TEXT_LIMIT)}`);
+        }
+        for (const file of extractPaths(resultText, cwd)) registry.add(file, "mentioned", "tool_result");
+      }
+    }
+    if (parts.length) transcript.push(`\n## ${role}\n\n${parts.join("\n")}`);
+    if (narrativeParts.some((p) => String(p).trim())) narrative.push(`\n## ${role}\n\n${narrativeParts.join("\n")}`);
+  }
+
+  const rankedFiles = registry
+    .values()
+    .map((entry) => ({ ...entry, score: scoreFile(entry), markdown: [".md", ".mdx"].includes(path.extname(entry.path).toLowerCase()) }))
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+
+  const cwdRanked = [...cwdCounts.entries()].sort((a, b) => b[1] - a[1]);
+  const effectiveCwd = cwdRanked[0]?.[0] ?? cwd;
+
+  const transcriptText = transcript.join("\n");
+  const narrativeText = narrative.join("\n");
+  return {
+    sessionId,
+    jsonlPath,
+    cwd: effectiveCwd,
+    records: records.length,
+    transcript: transcriptText,
+    narrative: narrativeText,
+    transcriptTokens: Math.round(transcriptText.length / 4),
+    narrativeTokens: Math.round(narrativeText.length / 4),
+    files: rankedFiles,
+    docs: discoverDocs(effectiveCwd),
+  };
+}
+
+function markdownFileList(files) {
+  const lines = [];
+  lines.push("# Touched Files");
+  lines.push("");
+  lines.push("Files are ranked for restore relevance. Markdown and written files are the first candidates to read in full.");
+  lines.push("");
+
+  const sections = [
+    ["Highest-priority Markdown/state files", (f) => f.markdown && (f.kinds.written || f.kinds["shell-write"] || f.kinds["file-history"])],
+    ["Other written/tracked files", (f) => !f.markdown && (f.kinds.written || f.kinds["shell-write"] || f.kinds["file-history"])],
+    ["Read/discovered/mentioned files", (f) => !(f.kinds.written || f.kinds["shell-write"] || f.kinds["file-history"])],
+  ];
+
+  for (const [title, predicate] of sections) {
+    const group = files.filter(predicate);
+    if (!group.length) continue;
+    lines.push(`## ${title}`);
+    lines.push("");
+    for (const file of group) {
+      const kinds = Object.entries(file.kinds).map(([kind, count]) => `${kind}:${count}`).join(", ");
+      lines.push(`- score ${file.score} — \`${file.path}\` — ${kinds}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function restoreInstructions(summary, outputPaths) {
+  const lines = [];
+  lines.push("# Claude Compaction Restore Instructions");
+  lines.push("");
+  lines.push("You have just been compacted or are restoring a compacted Claude Code seat. Your mental model is compressed and unreliable.");
+  lines.push("");
+  lines.push(`- JSONL transcript: \`${summary.jsonlPath}\``);
+  lines.push(`- Reconstructed transcript: \`${outputPaths.transcript}\` (~${summary.transcriptTokens ?? "?"} tokens — do NOT read front-to-back)`);
+  lines.push(`- Narrative companion (READ THIS FIRST): \`${outputPaths.narrative}\` (~${summary.narrativeTokens ?? "?"} tokens — message turns only, no tool bodies)`);
+  lines.push(`- Touched-file triage: \`${outputPaths.touchedFiles}\``);
+  lines.push(`- Working directory inferred: \`${summary.cwd}\``);
+  lines.push("");
+  lines.push("## Read budget (the restore must leave room for the work)");
+  lines.push("");
+  lines.push(`- The full transcript is ~${summary.transcriptTokens ?? "?"} tokens. **Reading it front-to-back can consume the window the restore exists to rebuild.**`);
+  lines.push(`- Default order: read the **narrative companion first** (~${summary.narrativeTokens ?? "?"} tokens — message turns + decisions), tail-first (most recent first).`);
+  lines.push("- Drop to the full transcript only for a specific question the narrative can't answer. File bodies inside tool-results are pointers now — **read the live file, not the transcript snapshot.**");
+  lines.push("- Read to a budget with a stopping rule; report depth honestly (an honest PARTIAL beats a false completion). See the skill's *Required Read-Depth Audit*.");
+  lines.push("");
+  lines.push("## Required Sequence");
+  lines.push("");
+  lines.push("1. Read this file and `touched-files.md`.");
+  lines.push("2. Ask yourself: which files do I recognize as important to the work and project state?");
+  lines.push("3. Mark those files mentally or in a short note.");
+  lines.push("4. Read every important Markdown/state/planning file in full.");
+  lines.push("5. Read project root docs in full when present: `CLAUDE.md`, `AGENTS.md`, `README.md`.");
+  lines.push("6. Read as-built docs and codemaps in full before product work, code review, or architecture decisions.");
+  lines.push("7. State exactly: `restored from packet at <path>; resumed at step <X>`.");
+  lines.push("");
+  lines.push("## Documentation Candidates");
+  lines.push("");
+  if (summary.docs.length) {
+    for (const doc of summary.docs) lines.push(`- \`${doc}\``);
+  } else {
+    lines.push("- No root/as-built/codemap candidates were found automatically. Search manually before resuming code/review work.");
+  }
+  lines.push("");
+  lines.push("## Top File Candidates");
+  lines.push("");
+  for (const file of summary.files.slice(0, 30)) {
+    lines.push(`- \`${file.path}\` — score ${file.score}`);
+  }
+  lines.push("");
+  lines.push("Do not continue from fuzzy memory alone.");
+  return lines.join("\n");
+}
+
+function writeOutputs(summary, outRoot) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const base = path.join(outRoot, `${summary.sessionId ?? "unknown-session"}-${stamp}`);
+  fs.mkdirSync(base, { recursive: true });
+
+  const outputPaths = {
+    dir: base,
+    transcript: path.join(base, "transcript.txt"),
+    narrative: path.join(base, "transcript-narrative.txt"),
+    touchedFiles: path.join(base, "touched-files.md"),
+    instructions: path.join(base, "restore-instructions.md"),
+    summary: path.join(base, "restore-summary.json"),
+  };
+
+  fs.writeFileSync(outputPaths.transcript, summary.transcript || "(no message transcript reconstructed)\n");
+  fs.writeFileSync(outputPaths.narrative, summary.narrative || "(no narrative reconstructed)\n");
+  fs.writeFileSync(outputPaths.touchedFiles, markdownFileList(summary.files));
+  fs.writeFileSync(outputPaths.instructions, restoreInstructions(summary, outputPaths));
+  fs.writeFileSync(outputPaths.summary, JSON.stringify({ ...summary, transcript: undefined, narrative: undefined, outputPaths }, null, 2));
+
+  return outputPaths;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cwd = path.resolve(args.cwd);
+  const jsonlPath = args.jsonl ? path.resolve(args.jsonl) : findLatestJsonl(cwd);
+  if (!jsonlPath) throw new Error("could not find a Claude JSONL transcript; pass one explicitly");
+  if (!fs.existsSync(jsonlPath)) throw new Error(`JSONL transcript not found: ${jsonlPath}`);
+
+  const summary = analyze(jsonlPath, cwd);
+  const outputPaths = writeOutputs(summary, path.resolve(args.out));
+  const result = {
+    ok: true,
+    jsonlPath,
+    outputDir: outputPaths.dir,
+    transcript: outputPaths.transcript,
+    narrative: outputPaths.narrative,
+    transcriptTokens: summary.transcriptTokens,
+    narrativeTokens: summary.narrativeTokens,
+    touchedFiles: outputPaths.touchedFiles,
+    instructions: outputPaths.instructions,
+    fileCount: summary.files.length,
+    topFiles: summary.files.slice(0, 12).map((file) => file.path),
+  };
+
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`Restore packet: ${result.outputDir}`);
+    console.log(`Instructions: ${result.instructions}`);
+    console.log(`Touched files: ${result.touchedFiles}`);
+    console.log(`Narrative (read first): ${result.narrative} (~${result.narrativeTokens} tokens)`);
+    console.log(`Transcript (drill-down): ${result.transcript} (~${result.transcriptTokens} tokens)`);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`claude-compaction-restore failed: ${error.message}`);
+  process.exit(1);
+}

package/daemon/context-packs/skills/claude-compaction-restore/templates/compact-instruction.md

@@ -0,0 +1 @@
+Optional. Leave blank to use Claude Code's native compaction summary behavior; OpenRig's pre-compaction preparation and post-compaction restore prompts carry the durable continuity protocol.

package/daemon/context-packs/skills/claude-compaction-restore/templates/post-compact-restore-instruction.md

@@ -0,0 +1 @@
+Read the claude-compaction-restore skill and follow its "If You Just Compacted" protocol.

package/daemon/context-packs/skills/core/agent-starters/manifest.yaml

@@ -1,7 +1,8 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-starters"
-version: "0.5.5"
+version: "0.5.7"
+taxonomy: "skills"
 purpose: "Use when creating, refreshing, packaging, inspecting, promoting, or deprecating a named per-seat starting point — Agent Starter manifest authoring, the 6-state lifecycle (captured → named → inspectable → used → promoted → deprecated), provenance honesty, and refusal rules. NOT a VM image; a managed starting point composed from agent role + startup context + optional native session source + provenance."
 files:
   - path: "SKILL.md"

package/daemon/context-packs/skills/core/agent-startup-and-context-ingestion/manifest.yaml

@@ -1,7 +1,8 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-startup-and-context-ingestion"
-version: "0.5.5"
+version: "0.5.7"
+taxonomy: "skills"
 purpose: "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)."
 files:
   - path: "SKILL.md"

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

@@ -30,11 +30,8 @@ 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
+The live host registry may contain SSH or HTTP read-through/tunnel entries.
+Use each registry entry as ground truth for transport shape. 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.**
@@ -73,24 +70,20 @@ differs from the interactive verbs (`send`/`capture`/`ps`/`whoami`):
 
 ## 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.
+Host ids must be non-empty and unique. Choose stable, operator-meaningful ids
+that describe the destination without depending on transient network details.
 
 ```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
+    user: example-user                   # optional
     notes: "Tart VM"                     # optional
   - id: laptop-b
     transport: ssh
     target: laptop-b.tail-scale-net
-    user: wrandom
+    user: example-user
 ```
 
 Validation rules:

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

@@ -1,7 +1,8 @@
 # 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.5"
+version: "0.5.7"
+taxonomy: "skills"
 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"

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

@@ -1,7 +1,8 @@
 # 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.5"
+version: "0.5.7"
+taxonomy: "skills"
 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"

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

@@ -0,0 +1,98 @@
+---
+name: messaging-the-human
+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
+    audience: all agents
+    sibling_skills:
+      - queue-handoff
+      - human-in-the-loop
+      - openrig-user
+---
+
+# Messaging the Human
+
+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 queue transitions <qitem-id>
+```
+
+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.