@openrig/cli 0.4.8 → 0.5.1

package/daemon/assets/claude-statusline-context.cjs

@@ -3,12 +3,13 @@
 // Reads Claude status line JSON from stdin, extracts context window data,
 // and writes atomically to a sidecar file.
 //
-// Usage: node claude-statusline-context.js <sidecar-output-path-or-dir>
+// Usage: node claude-statusline-context.js <context-output-path-or-dir> [provider-usage-dir]
 
 const fs = require("fs");
 const path = require("path");
 
 const outputTarget = process.argv[2];
+const providerUsageTarget = process.argv[3];
 if (!outputTarget) {
   process.exit(0); // No output path — silently exit
 }
@@ -51,14 +52,22 @@ process.stdin.on("end", () => {
       process.exit(0);
     }
 
-    // Atomic write: write to .tmp then rename
-    const tmpPath = outputPath + ".tmp";
-    const dir = path.dirname(outputPath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
+    writeJsonAtomic(outputPath, sample);
+
+    if (providerUsageTarget) {
+      const providerUsagePath = resolveOutputPath(providerUsageTarget, raw);
+      if (!providerUsagePath) {
+        logFailure("could not resolve provider_usage output path from Claude status line payload");
+        process.exit(0);
+      }
+      const rateLimits = normalizeRateLimits(raw.rate_limits);
+      const providerUsage = {
+        seatSession: raw.session_name || raw.session_id,
+        asOf: new Date().toISOString(),
+        ...(rateLimits ? { accountKind: "subscription", rateLimits } : {}),
+      };
+      writeJsonAtomic(providerUsagePath, providerUsage);
     }
-    fs.writeFileSync(tmpPath, JSON.stringify(sample), "utf-8");
-    fs.renameSync(tmpPath, outputPath);
   } catch (error) {
     logFailure("failed to collect Claude context status line", error);
     process.exit(0);
@@ -78,3 +87,26 @@ function resolveOutputPath(target, raw) {
   const safe = String(sessionKey).replace(/[^a-zA-Z0-9@._-]/g, "_");
   return path.join(target, safe + ".json");
 }
+
+function normalizeRateLimits(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const result = {};
+  for (const key of ["five_hour", "seven_day"]) {
+    const window = value[key];
+    if (!window || typeof window !== "object" || Array.isArray(window)) continue;
+    if (typeof window.used_percentage !== "number" || !Number.isFinite(window.used_percentage)
+      || typeof window.resets_at !== "string") continue;
+    result[key] = { usedPercent: window.used_percentage, resetsAt: window.resets_at };
+  }
+  return result.five_hour || result.seven_day ? result : null;
+}
+
+function writeJsonAtomic(outputPath, value) {
+  const tmpPath = outputPath + ".tmp";
+  const dir = path.dirname(outputPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(tmpPath, JSON.stringify(value), "utf-8");
+  fs.renameSync(tmpPath, outputPath);
+}

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 (10):** the canonical OpenRig operating knowledge — how to use the `rig` CLI, how to design rig topologies, how to recover from compaction, how to hand work off durably between agents, and how to maintain seat continuity across handovers and restarts.
+**Skills (12):** the canonical OpenRig operating knowledge — how to use the `rig` CLI, how to design rig topologies, how to recover from compaction, how to hand work off durably between agents, how to maintain seat continuity across handovers and restarts, how to apply a permission policy to a seat's live harness, and how to decide who does a task.
 
 **Hooks:** activity-tracking hooks (Claude Code: 4 events; Codex: 3 events) that POST agent state to the OpenRig daemon for real-time UI seat-status updates.
 

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

@@ -45,6 +45,7 @@ function buildOpenRigPayload(providerPayload, env = process.env, now = () => new
   const sessionName = firstString(env.OPENRIG_SESSION_NAME, env.RIGGED_SESSION_NAME);
   const nodeId = firstString(env.OPENRIG_NODE_ID, env.RIGGED_NODE_ID);
   const runtime = firstString(env.OPENRIG_RUNTIME, env.RIGGED_RUNTIME);
+  const generation = firstString(env.OPENRIG_OCCUPANT_GENERATION, env.RIGGED_OCCUPANT_GENERATION);
   const hookEvent = firstString(
     providerPayload.hookEvent,
     providerPayload.hookEventName,
@@ -69,6 +70,7 @@ function buildOpenRigPayload(providerPayload, env = process.env, now = () => new
     sessionName,
     nodeId,
     runtime,
+    generation,
     hookEvent,
     subtype,
     occurredAt: now().toISOString(),

package/daemon/assets/plugins/openrig-core/hooks/scripts/compaction-restore-bridge.cjs

@@ -44,6 +44,15 @@ function firstString(...values) {
   return null;
 }
 
+// A3-R3 injectable clock (slice 51-01): the marker stamps below default to real
+// wall-clock, but become deterministic when the shared hermetic env-var
+// OPENRIG_TEST_CLOCK_NOW is set (an ISO instant). An empty/absent var = production
+// real-time (absence is the production state — the only unguarded path, on purpose).
+function nowIso(env = process.env) {
+  const injected = env.OPENRIG_TEST_CLOCK_NOW;
+  return typeof injected === "string" && injected.trim().length > 0 ? injected : new Date().toISOString();
+}
+
 function openrigHome(env = process.env) {
   return firstString(env.OPENRIG_HOME, env.RIGGED_HOME) || path.join(os.homedir(), ".openrig");
 }
@@ -97,6 +106,24 @@ function findMarker(payload, env = process.env) {
   return marker;
 }
 
+// R5 absent-when-needed: the expected-sentinel the PreCompact hook drops FIRST (same seat
+// key + identity binding as the marker). Its presence-without-a-marker is what makes an
+// absent marker LOUD; its lifecycle mirrors the marker (removed once the marker delivers).
+function sentinelPath(payload, env = process.env) {
+  const key = sessionKey(payload, env);
+  return key ? path.join(markerDir(env), `${key}.expected.json`) : null;
+}
+
+function findSentinel(payload, env = process.env) {
+  const p = sentinelPath(payload, env);
+  return p ? readMarker(p) : null;
+}
+
+function removeSentinel(payload, env = process.env) {
+  const p = sentinelPath(payload, env);
+  if (p) { try { fs.unlinkSync(p); } catch { /* best-effort cleanup */ } }
+}
+
 function writeMarker(marker) {
   fs.writeFileSync(marker.filePath, `${JSON.stringify(marker.data, null, 2)}\n`, "utf8");
 }
@@ -123,6 +150,22 @@ function buildRestoreContext(marker) {
   return pieces.join("\n");
 }
 
+// R5 marker-lifecycle (stale-firing-premise-false): a marker records the identity of
+// the compaction it was written for (its own transcriptPath / sessionId, stamped by the
+// PreCompact writer from the same Claude input). The bridge fires ONLY when the current
+// start MATCHES that premise — binding to EVENT+IDENTITY, not recency (a clock window
+// misfires both directions; recency would only ever be a belt). A legacy marker that
+// recorded no identity falls back to the seat-key + deliver-once behavior (transitional).
+function premiseMatches(markerData, payload) {
+  const markerTranscript = firstString(markerData.transcriptPath);
+  const markerSession = firstString(markerData.sessionId);
+  if (!markerTranscript && !markerSession) return true; // legacy marker: no identity to gate on
+  const payloadTranscript = firstString(payload.transcript_path, payload.transcriptPath);
+  const payloadSession = firstString(payload.session_id, payload.sessionId);
+  if (markerTranscript) return payloadTranscript === markerTranscript;
+  return payloadSession === markerSession;
+}
+
 function hookEventName(payload) {
   return firstString(
     payload.hook_event_name,
@@ -138,22 +181,41 @@ async function main() {
   const payload = parseJson(await readStdin());
   const eventName = hookEventName(payload);
   const marker = findMarker(payload);
-  if (!marker) return;
+  if (!marker) {
+    // R5 absent-when-needed: LOUD iff a matching expected-sentinel is present (a compaction
+    // WAS expected for this seat/session — the PreCompact hook drops the sentinel FIRST) but
+    // the marker is absent/unresolvable (write failed / hook died partway / packet lost).
+    // No sentinel = no hook = policy off = silent by construction. Stderr, so it never
+    // pollutes the additionalContext stdout.
+    const sentinel = findSentinel(payload);
+    if (sentinel && premiseMatches(sentinel.data, payload)) {
+      process.stderr.write(
+        "OpenRig compaction restore: a restore packet was EXPECTED for this session but its marker is missing or unresolvable — the PreCompact write may have failed. Fall back to the JSONL restore (claude-compaction-restore skill).\n",
+      );
+    }
+    return;
+  }
 
   marker.data.lastBridgeEvent = eventName;
   if (eventName === "PostCompact") {
-    marker.data.postCompactAt = new Date().toISOString();
+    marker.data.postCompactAt = nowIso();
     writeMarker(marker);
     return;
   }
 
+  // R5: stale-firing gate — never deliver a marker written for a different compaction.
+  if (!premiseMatches(marker.data, payload)) {
+    return;
+  }
+
   if (marker.data.deliveryCount && marker.data.deliveryCount > 0) {
     return;
   }
 
-  marker.data.deliveredAt = new Date().toISOString();
+  marker.data.deliveredAt = nowIso();
   marker.data.deliveryCount = Number(marker.data.deliveryCount || 0) + 1;
   writeMarker(marker);
+  removeSentinel(payload); // R5: expectation fulfilled — clear the sentinel so it can't false-loud later
 
   process.stdout.write(`${JSON.stringify({
     continue: true,

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/scripts/precompact-hook.mjs

@@ -6,7 +6,12 @@ import { spawnSync } from "node:child_process";
 
 const skillRoot = path.resolve(new URL("..", import.meta.url).pathname);
 const restoreScript = path.join(skillRoot, "scripts", "restore-from-jsonl.mjs");
-const outRoot = "/tmp/claude-compaction-restore";
+// P6(C) injectable output-root: the packet base defaults to the shared
+// /tmp/claude-compaction-restore (production), but becomes per-run isolated when the
+// hermetic env-var OPENRIG_COMPACTION_OUT_ROOT is set — so concurrent writers with the
+// same injected clock + sessionId no longer collide on the same `${sessionId}-${stamp}`
+// dir. Mirrors the injectable-clock seam (OPENRIG_TEST_CLOCK_NOW). Empty/absent = /tmp.
+const outRoot = process.env.OPENRIG_COMPACTION_OUT_ROOT || "/tmp/claude-compaction-restore";
 const defaultRestoreInstruction =
   "Read the claude-compaction-restore skill and follow its \"If You Just Compacted\" protocol.";
 
@@ -24,6 +29,14 @@ function getOpenRigHome() {
   return process.env.OPENRIG_HOME || process.env.RIGGED_HOME || path.join(os.homedir(), ".openrig");
 }
 
+// A3-R3 injectable clock (slice 51-01): marker.createdAt defaults to real wall-clock,
+// but becomes deterministic when the shared hermetic env-var OPENRIG_TEST_CLOCK_NOW is
+// set (an ISO instant). Empty/absent = production real-time.
+function nowIso() {
+  const injected = process.env.OPENRIG_TEST_CLOCK_NOW;
+  return typeof injected === "string" && injected.trim().length > 0 ? injected : new Date().toISOString();
+}
+
 function expandInstructionPath(filePath) {
   if (filePath.startsWith("~/")) return path.join(os.homedir(), filePath.slice(2));
   if (filePath.startsWith("${OPENRIG_HOME}/")) {
@@ -41,6 +54,50 @@ function readInstructionFile(filePath) {
   return fs.readFileSync(expanded, "utf8");
 }
 
+// OPR.0.4.1.09 / R5 marker-lifecycle (foreign-content-in-marker face): the hook
+// path must apply the SAME seat-check the daemon enforcer's resolvePostCompactExtra
+// applies (rev1-r2 dcd95bd9), or a FOREIGN seat's global messageFilePath leaks into
+// THIS seat's marker. Parse a WELL-FORMED leading `---` frontmatter for a declared
+// seat (target_seat / seat / session); body text is never scanned; a broken/absent
+// fence is GENERIC (valid for any seat). Byte-mirrors the enforcer regexes.
+function declaredSeatOf(content) {
+  const fm = /^\s*---\s*\n([\s\S]*?)\n---/.exec(content);
+  if (!fm) return null;
+  const m = /^[ \t]*(?:target[_-]?seat|seat|session(?:[_-]?name)?)[ \t]*:[ \t]*["']?([^"'\n#]+?)["']?[ \t]*$/im.exec(fm[1]);
+  return m ? m[1].trim() : null;
+}
+
+function sanitizeSeat(value) {
+  return value.replace(/[^a-zA-Z0-9_.@-]/g, "_");
+}
+
+// Resolve the post-compaction extra FOR THIS SEAT (mirror of the enforcer): (1) prefer
+// a per-seat compaction/post-compact-extra/<seat>.md — no cross-seat contamination
+// possible; (2) fall back to the global ONLY when it does not declare a DIFFERENT seat
+// (a wrong-seat global is REFUSED). Generic/undeclared/configured-but-absent stay
+// allowed. Returns the path to read, or null when nothing valid for this seat.
+function resolveSeatSafeExtraPath(globalFilePathRaw) {
+  const rawSeat = process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || "";
+  const seatKey = rawSeat ? sanitizeSeat(rawSeat) : "";
+  if (seatKey) {
+    const perSeatPath = path.join(getOpenRigHome(), "compaction", "post-compact-extra", `${seatKey}.md`);
+    if (fs.existsSync(perSeatPath)) {
+      const declared = declaredSeatOf(fs.readFileSync(perSeatPath, "utf8"));
+      if (declared && sanitizeSeat(declared) !== seatKey) return null; // wrong-seat per-seat file
+      return perSeatPath;
+    }
+  }
+  const trimmed = (globalFilePathRaw || "").trim();
+  if (!trimmed) return null;
+  const expanded = expandInstructionPath(trimmed);
+  // configured-but-absent: keep the path (an absent file cannot be a wrong-seat leak;
+  // readInstructionFile returns "" so nothing is appended).
+  if (!fs.existsSync(expanded)) return trimmed;
+  const declared = declaredSeatOf(fs.readFileSync(expanded, "utf8"));
+  if (declared && sanitizeSeat(declared) !== seatKey) return null; // foreign-seat global REFUSED
+  return trimmed;
+}
+
 function sessionKey(input) {
   const raw = [
     process.env.OPENRIG_SESSION_NAME,
@@ -58,12 +115,28 @@ function pendingMarkerPath(input) {
   return path.join(getOpenRigHome(), "compaction", "restore-pending", `${sessionKey(input)}.json`);
 }
 
+// R5 absent-when-needed: drop a lightweight EXPECTED sentinel FIRST (before the packet is
+// generated + the marker is written), carrying the SAME identity binding the marker gets.
+// Its presence-without-a-marker is what lets the bridge be LOUD about a missing packet
+// (hook died partway / write failed); policy off = no hook = no sentinel = silent.
+function writeExpectedSentinel(input) {
+  const p = path.join(getOpenRigHome(), "compaction", "restore-pending", `${sessionKey(input)}.expected.json`);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, `${JSON.stringify({
+    version: 1,
+    sessionName: process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || null,
+    sessionId: input.session_id || input.sessionId || null,
+    transcriptPath: input.transcript_path || null,
+    createdAt: nowIso(),
+  }, null, 2)}\n`, "utf8");
+}
+
 function writePendingRestoreMarker(input, parsed, restoreInstruction, customMessage) {
   const markerPath = pendingMarkerPath(input);
   fs.mkdirSync(path.dirname(markerPath), { recursive: true });
   const payload = {
     version: 1,
-    createdAt: new Date().toISOString(),
+    createdAt: nowIso(),
     sessionName: process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || null,
     sessionId: input.session_id || input.sessionId || null,
     transcriptPath: input.transcript_path || null,
@@ -118,13 +191,18 @@ function readClaudeCompactionMessage() {
     parts.push(`Inline restore instruction:\n${inline}`);
   }
   if (filePath && filePath.length > 0) {
-    try {
-      const fileText = readInstructionFile(filePath);
-      if (fileText) {
-        parts.push(`Additional restore instruction file (${filePath}):\n${fileText}`);
+    // R5 seat-check: resolve to the per-seat extra or a seat-safe global; a
+    // foreign-seat global resolves to null and is never injected into this marker.
+    const resolved = resolveSeatSafeExtraPath(filePath);
+    if (resolved) {
+      try {
+        const fileText = readInstructionFile(resolved);
+        if (fileText) {
+          parts.push(`Additional restore instruction file (${resolved}):\n${fileText}`);
+        }
+      } catch {
+        // Keep any inline instruction; unreadable extra files degrade quietly.
       }
-    } catch {
-      // Keep any inline instruction; unreadable extra files degrade quietly.
     }
   }
   if (parts.length > 0) return parts.join("\n\n");
@@ -140,7 +218,16 @@ function buildSystemMessage(restoreInstruction, customMessage) {
 }
 
 try {
+  // Slice 51-01 RIDER (leak-visibility, review-r1 escalation): OPENRIG_TEST_CLOCK_NOW is
+  // read by nowIso() to make createdAt deterministic in tests — but a LEAKED var in a
+  // real seat would silently FREEZE production createdAt. Announce loudly on stderr when
+  // active so any leak is visible in seat logs; absence stays silent (production path).
+  // MUST stay byte-identical to STUB_CLOCK_ANNOUNCEMENT in stub-runner.ts.
+  if (typeof process.env.OPENRIG_TEST_CLOCK_NOW === "string" && process.env.OPENRIG_TEST_CLOCK_NOW.trim().length > 0) {
+    process.stderr.write("OPENRIG_TEST_CLOCK_NOW active — timestamps are injected\n");
+  }
   const input = readHookInput();
+  writeExpectedSentinel(input); // R5: sentinel FIRST, before the packet + marker (catches hook-died-partway)
   const args = [restoreScript, "--out", outRoot, "--json"];
   if (input.cwd) args.push("--cwd", input.cwd);
   if (input.transcript_path && input.transcript_path.endsWith(".jsonl") && fs.existsSync(input.transcript_path)) {

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs

@@ -5,7 +5,10 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 
 const TEXT_LIMIT = 4000;
-const DEFAULT_OUT = "/tmp/claude-compaction-restore";
+// P6(C) injectable output-root (mirrors precompact-hook.mjs): per-run isolation when
+// OPENRIG_COMPACTION_OUT_ROOT is set, real /tmp default in production. Guards a direct
+// invocation (the hook passes --out explicitly) against the same cross-writer collision.
+const DEFAULT_OUT = process.env.OPENRIG_COMPACTION_OUT_ROOT || "/tmp/claude-compaction-restore";
 
 function parseArgs(argv) {
   const args = {
@@ -375,8 +378,16 @@ function restoreInstructions(summary, outputPaths) {
   return lines.join("\n");
 }
 
+// A3-R3 injectable clock (slice 51-01): the packet output-dir timestamped path
+// defaults to real wall-clock, but becomes deterministic when the shared hermetic
+// env-var OPENRIG_TEST_CLOCK_NOW is set (an ISO instant). Empty/absent = production.
+function nowIso() {
+  const injected = process.env.OPENRIG_TEST_CLOCK_NOW;
+  return typeof injected === "string" && injected.trim().length > 0 ? injected : new Date().toISOString();
+}
+
 function writeOutputs(summary, outRoot) {
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const stamp = nowIso().replace(/[:.]/g, "-");
   const base = path.join(outRoot, `${summary.sessionId ?? "unknown-session"}-${stamp}`);
   fs.mkdirSync(base, { recursive: true });
 

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

@@ -12,7 +12,10 @@ metadata:
 
 # Mission/Slice SOP — how you work a mission & slice
 
-Use this skill to actually **do** mission/slice work the way OpenRig expects: author the convention sections, track on the canonical files, prove on them, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.** The deterministic backstop is `rig scope audit` — the audit classifier is the source of truth for adherence. The conventions themselves live in ONE document: **`docs/reference/sdlc-conventions.md`** in the repo, materialized by the daemon at **`$OPENRIG_HOME/reference/sdlc-conventions.md`** (default `~/.openrig/reference/sdlc-conventions.md`) on an installed package — this skill teaches the flow; the SSOT defines the formats.
+Use this skill to actually **do** mission/slice work the way OpenRig expects: author the convention sections, track on the canonical files, prove on them, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.** The deterministic backstop is `rig scope audit` — an **advisory, fail-open** check (it records and advises, never blocks a write; see Proportionality below), not an authority you serve. The conventions themselves live in ONE document: **`docs/reference/sdlc-conventions.md`** in the repo, materialized by the daemon at **`$OPENRIG_HOME/reference/sdlc-conventions.md`** (default `~/.openrig/reference/sdlc-conventions.md`) on an installed package — this skill teaches the flow; the SSOT defines the formats.
+
+## Proportionality — this SOP serves shipping; it is not the work itself
+The working product is the deliverable. This bookkeeping exists so the work survives handoff, compaction, and review — nothing more. **Match it to stakes:** OpenRig core = full ceremony; Studio Box / SDK / app slices = pragmatic — the mini-requirements may BE the whole PRD, and a couple of honest, LOOKed proof lines beat an elaborate contract. The `rig scope audit` backstop is **advisory and fail-open** (its own SSOT says so): it never blocks a build and is not a gate you clear before proceeding. If you're spending more time on the convention files or the audit than on the running product, stop and go build. Running the full apparatus on a small change is the letter-worship failure, not diligence.
 
 ## The SDLC flow (intent → proof)
 
@@ -30,7 +33,7 @@ intent → mini-requirements + proof contract → (UI slices: mockups)
    - **PARSER CONTRACT (README AND IMPLEMENTATION-PRD, from first draft — a parser contract, not stylistic):** each doc carries a verbatim, **undecorated** `## Mini-requirements` heading with a **numbered list**, and a verbatim, **undecorated** `## Proof contract` heading whose checkbox (`- [ ]`) lines are **character-identical** across the two files. `rig scope audit` parses the PRD's `## Proof contract`; a prose rollup (e.g. `## Required proof …`) or any renamed/decorated heading trips **`proof_contract_missing_or_malformed`** and forces a post-lock format patch. Never rename or decorate these two headings, and keep the PRD's checkbox lines byte-for-byte equal to the README's.
    - **REFERENCE-NOT-RESTATE (public / runnable examples — an honesty rail, from first draft):** any example that shows output or a value the referenced file/command **derives** — repo/runtime counts, current-state totals, hashes, timestamps — must **reference the source/derivation, omit the volatile value, or pin an explicitly stable fixture**; never hardcode the live count/state in a public or shipped doc. "Illustrative" derived output is a lie on a timer: `OK registry (2 manifests)` goes false the instant an entry lands. Write the invariant form (`OK registry (<N> manifests)`, N = entries in `registry.json`) or name the fixture instead of the momentary number. Restated derivable state in a public doc is a defect `rig scope audit` will not catch — the author owns it.
 3. **Plan-lock**: `rig scope slice approve <slice> --scope spec` — "the PRD matches the intent; THIS artifact set is what gets built." One daemon-side write: frontmatter stamp + append-only audit row.
-   - **PRE-PLAN-LOCK SELF-CHECK (MANDATORY):** before requesting `--scope spec`, run `rig scope audit --mission <mission> --json`, inspect the target slice's entry, and request the lock **only when that slice shows ZERO findings**. Do not carry a format defect (e.g. `proof_contract_missing_or_malformed`) into the lock and force a post-lock correction.
+   - **PRE-PLAN-LOCK SELF-CHECK (advisory, not a gate):** before requesting `--scope spec`, it's worth running `rig scope audit --mission <mission> --json` and clearing any real **format** defect (e.g. `proof_contract_missing_or_malformed`) so the parser can read your proof contract — that's a genuine machine-parsing need, cheap to fix. But the audit is fail-open: findings do NOT block the lock or the build, and you do NOT need a zero-findings score to proceed. Fix what's real, skip what isn't, keep moving.
 4. **Build the locked set** — look at the mockups, not just the spec text.
 5. **QA visual compare**: for each deliverable, load the planned mockup, produce the real artifact in a test/demo environment, visually compare, and record the verdict.
 6. **Drop proof**: `rig proof add <slice> --artifact-type qa --verdict PASS --candidate-sha <tip> --money-evidence "…" --evidences "1,3" --media "walk.webm,panel.png" --self-check "…"` — the C1 header's closed sets validate at drop time; `--evidences` joins the drop to its proof-contract items and `--media` names the curated proof/-relative media the drop stands behind (that pairing + media set is what the UI's DELIVERED section renders).
@@ -44,7 +47,7 @@ intent → mini-requirements + proof contract → (UI slices: mockups)
 
 ## The canonical files (the operating surface)
 
-> The canonical files below are the **operating surface of the work** — you track on them, prove on them, hand off through them, and survive compaction on them. They are NOT side-artifacts to "maintain"; keeping them current *is* the work.
+> The canonical files below are the **operating surface of the work** — you track on them, prove on them, hand off through them, and survive compaction on them. Keep them current because that is what lets the work survive handoff, compaction, and review — but they **serve** the product, they are not the product. If you're polishing these files while the actual thing isn't shipping, you've inverted it: go build, then update them.
 
 - **README.md** (mission + slice) — the overview, OPENING with the convention sections (`## Intent` / `## Mini-requirements` / `## Proof contract`). The **mission README carries this SOP at its bottom.**
 - **IMPLEMENTATION-PRD.md** — the full PRD; opens with the mini-requirements; the `## Proof contract` here is what the UI's DELIVERED pairing joins proof against.
@@ -100,7 +103,7 @@ When you `rig capture` a pane, **greyed / ghost autocomplete suggestions are NOT
 
 ## Moment-of-truth checklist
 
-- **Starting a slice?** → intent recorded verbatim? **PRD carries a verbatim numbered `## Mini-requirements` + a verbatim `## Proof contract` whose `- [ ]` lines are character-identical to the README's** (parser contract)? **no example restates derivable state** — counts/hashes/timestamps referenced, omitted, or pinned to a stable fixture, never hardcoded (reference-not-restate)? mockups attached (UI slices)? **`rig scope audit --mission <m> --json` shows ZERO findings for this slice** BEFORE plan-lock (`--scope spec`)?
+- **Starting a slice?** → intent recorded verbatim? **PRD carries a verbatim numbered `## Mini-requirements` + a verbatim `## Proof contract` whose `- [ ]` lines are character-identical to the README's** (parser contract)? **no example restates derivable state** — counts/hashes/timestamps referenced, omitted, or pinned to a stable fixture, never hardcoded (reference-not-restate)? mockups attached (UI slices)? ran `rig scope audit` and fixed any real **format** defect so the parser reads the proof contract (advisory — a clean score is NOT required to lock)?
 - **Finishing a slice?** → every proof-contract item has curated evidence via `rig proof add … --evidences --media` (C1 drops — never only hand-placed files)? PROGRESS updated? MISSION_NOTES `§1` refreshed? proof locked (`--scope delivery`)? Handed off via queue?
 - **Committing?** → PROGRESS updated?
 - **Compacting?** → filed your state in MISSION_NOTES?

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

@@ -311,7 +311,7 @@ The floor and YOLO are **launch flags** OpenRig sets deterministically; the Lock
 ## v0.3.x Starter, Workspace, And Plugin Surfaces
 
 OpenRig v0.3.0 adds `rig agent-image`, `rig context-pack`, `rig workspace`, and
-`rig config init-workspace`. It also shifts fresh-user starter guidance toward
+`rig config init-workspace`. *(0.5.0: the `rig context-pack` alias is retired — the store + compose library is the single `rig context` noun; see "Context packs and paced delivery (0.5.0)".)* It also shifts fresh-user starter guidance toward
 `product-team` for human-directed work and `conveyor` for workflow-oriented
 work. Treat `demo` as legacy/test content unless a task specifically asks for
 the old demo spec.
@@ -471,14 +471,14 @@ honestly and the UI exposes a one-click open-missing affordance.
 
 v0.4.0 flips the five most frequently invoked read-commands from firehose-by-default to compact-by-default, and `rig queue list` adopts the docker / kubectl read-command grammar. **All defaults preserve breadth and capability — the firehose is one explicit flag away.**
 
-### `rig ps` — current-rig default + compact-by-default + `-A`/`--all-rigs` + `--full`
+### `rig ps` — scope-aware: bare `rig ps` = ALL rigs; `--nodes` = your rig only
 
 ```bash
-rig ps                      # CURRENT-RIG, all-states, compact rig summaries (default)
-rig ps --json               # compact JSON array (TL;DR per node: session, rig, activity, assigned/pending, resumeTokenPresent boolean)
-rig ps -A                   # all-rigs (fleet breadth; was the v0.3.4 default)
-rig ps --rig <name>         # explicit-rig (overrides current-rig default)
-rig ps --nodes              # compact node inventory (current rig)
+rig ps                      # ALL active rigs on the host, one compact row each — RUN FIRST to know the world
+rig ps --rig <name>         # one named rig's summary
+rig ps --nodes --rig <name> # per-node (seat) detail for a NAMED rig — the normal drill-in
+rig ps --nodes              # per-node detail — CURRENT rig ONLY (deliberately narrow; NOT the whole host)
+rig ps --json               # compact JSON (default = a bare array of ALL non-archived rigs)
 rig ps --nodes -A           # cross-rig node inventory (was v0.3.4 default)
 rig ps --nodes --full       # complete record (the v0.3.4 per-node default shape; resumeToken VALUE retained here for downstream consumers)
 rig ps --nodes --session <sess>  # narrow to one canonical session
@@ -486,12 +486,12 @@ rig ps --active             # opt-in active-state filter (does NOT change the al
 ```
 
 **v0.4.0 breadth + projection changes**:
-- **Default breadth is CURRENT-RIG** (derived from `OPENRIG_SESSION_NAME`'s `@<rig>` suffix), not all-rigs. `-A` / `--all-rigs` widens to fleet. Matches the `rig queue list -A` pattern.
+- **Rig-level `rig ps` lists ALL active rigs** (one row each — the cheap "know the world" view). The **`--nodes` (per-seat) view defaults to your CURRENT rig only** (from `OPENRIG_SESSION_NAME`'s `@<rig>` suffix); `--rig <name>` picks another rig, `-A` widens `--nodes` to the whole host (expensive — prefer `--fields`/`--limit`).
 - **Per-node TL;DR projection (compact) is the default**; `--full` returns the raw byte-equivalent passthrough. Daemon-side `recoveryGuidance` relocated to a guidance-by-reference map (no longer duplicated per-node) — even `--full` benefits.
 - **All-states stays default** (different from `rig queue list` which defaults to active-only) — for `ps`, non-running states ARE often the actionable signal.
 - **Resume-token security**: `--full` JSON emits `resumeTokenPresent` (boolean) — the actual `resumeToken` value also remains in `--full` for downstream consumers that legitimately need it, but the compact default never carries it (an orch glance never accidentally leaks token material).
 
-**STOP using `rig ps --nodes --json` as a fleet-wide casual status check assuming the v0.3.4 shape.** The v0.4.0 default is CURRENT-RIG + compact; explicit `-A --full` is the fleet firehose. The ~77,000-token status-glance incident is closed twice over (compact + scope).
+**⚠ SCOPE-AWARENESS — the one that bites:** `rig ps --nodes` (and `--nodes --json`) show ONLY your current rig's seats, by design — the narrow default protects your context window. **Narrow output is not the whole world.** Never conclude "my rig is the only rig on the host" from a `--nodes` read — run bare `rig ps` FIRST (cheap; it lists every rig), then `rig ps --nodes --rig <name>` for the one you need. (`-A` = the expensive whole-host node read; use sparingly. The ~77k-token status-glance incident is closed by compact + scope.)
 
 ### `rig whoami` — compact-by-default + `--full` (`--verbose` alias)
 
@@ -532,16 +532,16 @@ rig restore-check --as <session>  # narrow to one seat
 
 Closes the largest measured bomb (~79,000 → low thousands). Summary correctly identifies EVERY not-ready seat (no false-ready omission); detail is dropped only for ready seats.
 
-### `rig context` — compact summary + `--full`
+### `rig context` — context-window usage viewer (0.4.x; REMOVED in 0.5.0)
 
 ```bash
-rig context                # compact summary
+rig context                # compact summary        (0.4.x only)
 rig context --full         # complete current payload
 rig context --rig <name>   # narrow to one rig
 rig context --threshold 80 # filter to seats at/above 80%
 ```
 
-Lower leverage than the others but keeps the read-command surface compact-by-default after the upgrade.
+Lower leverage than the others; keeps the read-command surface compact-by-default after the 0.4.0 upgrade. **⚠ 0.5.0: this usage viewer is removed entirely and the `rig context` name is reassigned to the context library (store + compose) — see "Context packs and paced delivery (0.5.0)" below. On a 0.5.0 host, bare `rig context` is the library, not this viewer.**
 
 ### Why this matters
 
@@ -701,7 +701,7 @@ JSON form exposes `peersNote` directly for programmatic consumers.
 ## Inventory and Monitoring
 
 ```bash
-rig ps                      # CURRENT-RIG, compact rig summaries (v0.4.0 default)
+rig ps                      # ALL active rigs on the host, one compact row each (run FIRST to know the world)
 rig ps --nodes              # compact node inventory (current rig)
 rig ps -A                   # all-rigs breadth (was the pre-0.4.0 default)
 rig ps --nodes --full       # complete per-node record (the firehose — opt-in)
@@ -759,6 +759,7 @@ rig send <session> "message" --json
 - `--dangerously-interact --reason "<why>"` — the ONLY override of the prompt/permission guard: deliberately drive an interactive prompt/permission block (implies `--raw`, requires `--reason`, audit-logged).
 - `--host <id>` — send on a remote host declared in `~/.openrig/hosts.yaml` (ssh hosts shell out; http hosts go CLI-direct to the remote daemon).
 - `--from <session>` — originating session for the envelope sender/actor (provenance; defaults to `$OPENRIG_SESSION_NAME`, and is plumbed through cross-host sends so the remote envelope names the origin, not the relay).
+- `--context <ref>` **(0.5.0)** — attach a composed context pack/piece by ref (see "Context packs and paced delivery"). Small piece → `send --context`; a real pack → `rig walk`. The noun `rig context` composes the ref; the verb delivers it.
 
 > **Durable work goes to the QUEUE, not `send`.** `rig send` is an *ephemeral* message to a pane — it can be missed, and its delivery status is pane-render, not receipt. If you are **assigning work, or the message is important enough that losing it would be a real bummer**, use `rig queue` (below): it's durable, owned, tracked, and survives compaction and restart. Reach for `send` for a quick conversational nudge; reach for the **queue** for anything that must not get lost. Do not default to `send` for work — that's the most common mistake.
 
@@ -905,6 +906,56 @@ rig auth seats … --runtime codex         # seat -> profile registry (metadata
 
 **Hard secret boundary:** no token value is ever printed, logged, queued, streamed, or committed; status/validate report presence/mode/login-state only; seat labels are metadata, not live-account proof. MVP is `--runtime codex`; other runtimes use the same surface with a different `--runtime`, never a parallel command.
 
+## Context packs and paced delivery (0.5.0)
+
+**Compose context once, hand it to a seat cleanly.** A library primitive plus a set of delivery flags. The rule that keeps the grammar coherent — internalize this one: **the noun stores and composes; the verbs deliver.** `rig context` never sends anything; delivery is only ever `rig send` / `rig broadcast` / `rig walk` / `rig queue`.
+
+> Version note: this is the 0.5.0 surface, pinned to the team-locked spec — not yet on lagging hosts. In 0.4.x, bare `rig context` was a context-window usage viewer (above); in 0.5.0 that viewer is removed and the `rig context` name belongs to the library here.
+
+### `rig context` — the store + compose library (never delivers)
+
+Manage and compose context (any text/markdown) into reusable **packs**. Every piece and pack has a stable, **path-like ref** — you address context the way you address files (`packs/compaction-restore`, `as-built/queue-internals`).
+
+```bash
+rig context list                     # what's in the library
+rig context show <ref>               # read a piece or pack
+rig context add <ref> --from <file>  # put a piece in the store
+rig context rm <ref>
+rig context compose --out packs/<ref> --from <fileA> <fileB> ...   # ordered pieces -> a durable pack
+```
+
+- Sensible default store location; works unconfigured, can be pointed elsewhere later (another folder now; a machine or URL later).
+- `compose` (v1) is honest ordered concatenation of named files into a durable pack with a ref — "here's a file, read a file."
+- **No delivery verb lives on the noun.** To get a pack to a seat, hand its ref to a delivery verb below.
+
+### `rig walk` — paced delivery of a sequence
+
+```bash
+rig walk <seat> --through <ref | file ...> --pace 10s
+```
+
+Walk a seat *through* a pack: each piece is sent into the pane, spaced by `--pace`, so the agent processes between sends (the human paste → wait → paste rhythm). Its own top-level verb, push-direction — the walker leads and does not wait for replies; the spacing does the work. Reach for `walk` on onboarding, repriming, or a fleet update — anything absorbed in order rather than all at once.
+
+### The delivery grammar — send a ref, walk a pack, or attach it to a qitem
+
+| When | Verb |
+|---|---|
+| One thing, now | `rig send <seat> --context <ref>` |
+| One thing, everyone | `rig broadcast --rig <rig> --context <ref>` |
+| A sequence, absorbed | `rig walk <seat> --through <ref> --pace 10s` |
+| Context riding a durable handoff | `rig queue create … --body-context <ref>` |
+
+- **Rule of thumb:** small piece → `send --context`; real pack → `walk`. An oversized `send --context` warns "this is walk-sized" instead of blasting the pane.
+- **`--body-context` snapshot rule:** a qitem built from a ref stores the **resolved content** in its body **plus the ref for provenance** — the handoff carries what was actually sent, and a later library edit never silently rewrites a past handoff's history.
+- **The orchestrator habit — assign work *with* its context attached:**
+  ```bash
+  rig context compose --out packs/qitem-brief --from as-built/queue.md conventions/c1-proof.md
+  rig queue create --destination dev-driver@build --body-context packs/qitem-brief --summary "…"
+  ```
+  The assignee never greps for the as-built; the curated context rides the durable handoff, survives compaction, and is auditable.
+
+**Skills tier vs context tier:** skills are the HOT tier (ambient, finite, always-visible front-matter); context packs are the COLD tier (unbounded, fetched on instruction — "walk yourself through `packs/tui-onboarding`"). Don't overrun the skill layer by using skills as context packs — that's what this primitive is for.
+
 ## Lifecycle
 
 ### Bring a rig up
@@ -1161,13 +1212,13 @@ Verification loop:
 ```bash
 rig discover --json
 rig adopt <fragment.yaml> --bindings-file <bindings.yaml> --target-rig <rigId>
-rig ps --nodes --json
+rig ps --nodes --rig <rigId>   # the target rig's nodes (--nodes alone = your current rig)
 rig export <rigId> -o rig.yaml
 ```
 
 Success looks like:
 - the new sessions stop appearing in `rig discover`
-- the new logical IDs appear in `rig ps --nodes --json`
+- the new logical IDs appear in `rig ps --nodes --rig <rigId>`
 - `rig export` includes the new pod
 
 ### Mixed-origin rigs are allowed
@@ -1185,7 +1236,7 @@ Current safety rule:
 The proven operator pattern is:
 - keep one OpenRig manager session outside the rig it manages
 - address the target by rig name, not cached rig ID
-- resolve the current owner from fresh `rig ps --nodes --json`
+- find the target rig with bare `rig ps` (lists all rigs), then resolve its owner from `rig ps --nodes --rig <target>` (a bare `--nodes` read is your current rig only, not the target's)
 - send the manager the spec path, bindings path, and verification steps with `rig send`
 
 This lets ordinary agents ask the manager for OpenRig help instead of every agent needing to be an OpenRig expert.
@@ -1318,7 +1369,7 @@ Design assumptions that hold in the shipped CLI:
 
 1. `rig whoami --json`
 2. `rig transcript <your-session> --tail 100`
-3. `rig ps --nodes --json`
+3. `rig ps` — lists ALL rigs on the host (know the world FIRST); then `rig ps --nodes --rig <your-rig>` for your seats. ⚠ `rig ps --nodes --json` alone is your CURRENT rig only — do NOT mistake it for the whole host (a freshly-compacted agent has no other context to catch the lie).
 4. `rig chatroom history <rig> --limit 50`
 
 ## Commands That Do Not Exist

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

@@ -151,6 +151,8 @@ Every qitem carries:
 - `state` — one of: `pending | in-progress | done | blocked | failed | denied | canceled | handed-off`
 - `closure_reason` + `closure_target` — set on terminal closure per hot-potato rule
 
+**(0.5.0) `--body-context <ref>` — context riding the handoff.** `rig queue create … --body-context <ref>` attaches a composed context pack to the qitem. The snapshot rule: the qitem stores the **resolved content** in its body **plus the ref for provenance** — the handoff carries what was actually sent, and a later edit to the library never silently rewrites a past handoff's history. (The `rig context` noun composes the ref; the queue delivers it — the noun has no send.) See `openrig-user` → "Context packs and paced delivery."
+
 The fields are auditable across both `rigx queue` (config-layer) and
 `rig queue` (daemon-shipped) surfaces. Watchdog policies and workflow
 runtime project new owners off these fields.