@openrig/cli 0.5.2 → 0.5.3

package/daemon/assets/plugins/openrig-core/hooks/claude.json

@@ -19,6 +19,15 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -39,6 +48,15 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "PreCompact": [
@@ -61,6 +79,15 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "Stop": [
@@ -72,6 +99,15 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "Notification": [

package/daemon/assets/plugins/openrig-core/hooks/codex.json

@@ -9,6 +9,15 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -20,6 +29,15 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "Stop": [
@@ -31,6 +49,15 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "PermissionRequest": [

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+"use strict";
+// openrig-core REFOCUS hook (OPR.0.5.3.6 — promoted from the lab where it ran
+// live on 6+ seats; the mechanism ships, the CONTENT is configurable).
+//
+// WHY: the moment an agent most needs to reorient is the moment it is least
+// able to choose to. Drift does not feel like drift — it feels like work. So
+// refocus FIRES rather than waits to be invoked.
+//
+// THIS IS ALSO HOW TOPOLOGY CHAIN FILES REACH A RUNNING SEAT. Editing a file
+// under topology.root is not delivery — a running seat reads its config at
+// session start and its context never re-reads disk on its own. This hook is
+// the delivery channel: it injects orientation content at the seat's next
+// hook boundary (SessionStart / UserPromptSubmit / Stop / PostCompact), so a
+// shipped or updated chain file becomes live doctrine without a relaunch.
+//
+// SIGNAL = TRANSCRIPT GROWTH, not turns and not wall-clock. A "turn" is one
+// prompt submission; an agent can burn 200k tokens across fifty tool calls
+// inside ONE turn, so a turn counter is blind to exactly the drift that
+// matters. The JSONL grows monotonically with work done (measured ~8.9 bytes
+// per context token, so ~300k tokens ≈ 2.6MB — rough on purpose; it needs to
+// be monotonic, not exact). Tune with OPENRIG_REFOCUS_BYTES.
+//
+// CONTENT IS CONFIGURABLE, NEVER PROJECT-SPECIFIC IN SOURCE. Resolution:
+//   1. OPENRIG_REFOCUS_CONTENT_REF env — resolved by `rig context get`.
+//   2. OPENRIG_REFOCUS_CONTENT_FILE env — an operator-authored file.
+//   3. $OPENRIG_HOME/refocus/REFOCUS.md — the instance's standing content.
+//   4. The generic three-question orientation below (project-neutral).
+// Project- or mission-specific refocus text belongs in those FILES, on the
+// instance that needs it — it must never be committed here.
+//
+// Fires on: SessionStart (fresh orientation), Stop (catches the long single
+// turn), UserPromptSubmit, and PostCompact on Claude (post-compaction
+// re-orientation; Codex exposes no compact hook — growth+Stop is the coverage
+// there). Silent unless due. A configured REF failure degrades loudly inside
+// the delivered payload; every failure remains non-blocking because a refocus
+// hook must never break a seat's turn.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const THRESH = Number(process.env.OPENRIG_REFOCUS_BYTES || 2_600_000);
+
+const readStdin = () => new Promise((r) => { let d = ""; process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => d += c); process.stdin.on("end", () => r(d)); process.stdin.on("error", () => r("")); });
+
+(async () => {
+  let input = {}; try { input = JSON.parse((await readStdin()) || "{}") || {}; } catch {}
+  const ev = input.hook_event_name || "UserPromptSubmit";
+  const seat = process.env.OPENRIG_SESSION_NAME || "unknown-seat";
+  const home = process.env.OPENRIG_HOME || path.join(process.env.HOME || "/tmp", ".openrig");
+  const tpath = input.transcript_path || input.transcriptPath || "";
+
+  let size = 0; try { size = fs.statSync(tpath).size; } catch {}
+
+  const dir = path.join(home, "refocus");
+  const file = path.join(dir, `${seat.replace(/[^A-Za-z0-9@._-]/g, "_")}.json`);
+  let st = { lastBytes: 0 };
+  try { st = JSON.parse(fs.readFileSync(file, "utf8")) || st; } catch {}
+
+  const grown = size > 0 ? size - (st.lastBytes || 0) : 0;
+  const due = ev === "SessionStart" || ev === "PostCompact" || grown >= THRESH;
+  if (!due) { process.exit(0); } // silent no-op — the common path
+
+  st.lastBytes = size; st.firedAt = new Date().toISOString(); st.firedOn = ev;
+  try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(file, JSON.stringify(st)); } catch {}
+
+  // A library ref wins over file configuration and reuses the public assembler instead of
+  // growing a second resolver inside this hook. REF failures stay visible without blocking
+  // the session boundary; REF-unset follows the folded FILE/default path byte-for-byte.
+  const contentRef = process.env.OPENRIG_REFOCUS_CONTENT_REF || "";
+  let configured = null;
+  let refFailure = null;
+  if (contentRef) {
+    const result = spawnSync("rig", ["context", "get", contentRef], {
+      encoding: "utf8",
+      env: process.env,
+      timeout: 4_000,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    if (!result.error && result.status === 0 && result.stdout.trim()) {
+      configured = result.stdout;
+    } else {
+      refFailure = result.error?.message
+        || result.stderr?.trim()
+        || result.stdout?.trim()
+        || `rig context get exited ${result.status ?? "without a status"}`;
+      refFailure = String(refFailure).replace(/\s+/g, " ").trim();
+    }
+  } else {
+    // Configurable content: operator file beats instance file beats the generic default.
+    const contentFile = [
+      process.env.OPENRIG_REFOCUS_CONTENT_FILE,
+      path.join(home, "refocus", "REFOCUS.md"),
+    ].filter(Boolean).find((p) => { try { return fs.existsSync(p); } catch { return false; } });
+    if (contentFile) {
+      try { configured = fs.readFileSync(contentFile, "utf8").trim() || null; } catch {}
+    }
+  }
+
+  const why = ev === "SessionStart" ? "fresh session"
+            : ev === "PostCompact" ? "just compacted — your picture is lossy"
+            : `${Math.round(grown / 1e6 * 10) / 10}MB of work since your last refocus`;
+
+  const generic = [
+    `1. What is the person actually trying to get? Not your current task — the outcome.`,
+    `2. Does what you are doing RIGHT NOW move that? If you cannot say what a user gets, stop and say so.`,
+    `3. What have you concluded without opening the file or running the thing?`,
+    ``,
+    `Discomfort on any of these IS the signal — drift feels like work.`,
+    ``,
+    `Your topology context (instance/rig/seat craft and this seat's LEARNED) is one walk away:`,
+    `rig context trace --rig <rig> --seat <seat> --name CRAFT.md — read it, do not recall it.`,
+    `A seat's LEARNED.md is written by previous occupants in the first person: it is evidence`,
+    `about the SEAT, never your own memory.`,
+  ];
+
+  const payload = refFailure ? [
+    `REFOCUS CONTENT REF FAILED: ${contentRef} — ${refFailure}`,
+    ``,
+    `REFOCUS (${why}). Answer briefly, out loud, before your next move:`,
+    ``,
+    ...generic,
+  ] : [
+    `REFOCUS (${why}). Answer briefly, out loud, before your next move:`,
+    ``,
+    ...(contentRef
+      ? [`REFOCUS CONTENT SOURCE: OPENRIG_REFOCUS_CONTENT_REF=${contentRef}`, ``, configured]
+      : configured ? [configured] : generic),
+  ];
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: ev, additionalContext: payload.join("\n") } }));
+})();

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/SKILL.md

@@ -92,6 +92,32 @@ restored from packet at <path>; resumed at step <X>
 
 Include the main files you read in full when you make that statement.
 
+9. **REFOCUS BEFORE YOU RESUME — the restore returns your TASK, not your BEARINGS.** Everything
+   above rebuilds *what you were doing*. None of it rebuilds *what the work is for* or *how this
+   rig operates* — those live in the chains, and nothing in steps 1–8 walks them. Invoke the
+   `refocus` skill and do its reads before your next substantive move.
+
+   **Measured 2026-08-13, and this step exists because of it:** a seat completed this protocol
+   faithfully — packet built, narrative read tail-first, read-depth audit reported honestly — and
+   resumed with a perfect picture of its atom and *zero* work-tree context. It had never opened
+   the mission or project nodes, and could only paraphrase the release's intent second-hand from
+   a peer's message. It then produced a technically-correct trace concluding *"I hold nothing"*
+   while holding 18 pending rows. **A restore that returns you to your task without your bearings
+   is how a confidently-wrong agent gets back to work.**
+
+**On the marker and the packet's size (measured across restores, 2026-08):** two realities the restore
+must handle honestly —
+
+- **The per-seat marker (`restore-pending/<session>.json`) is frequently absent** — in five observed
+  restores it was never present. Treat the JSONL rebuild via `restore-from-jsonl.mjs` as the **primary**
+  path, not a fallback: run it regardless of whether a marker exists. (When product-infra reliably writes
+  the marker for tmux-launched seats, it becomes a fast-path upgrade — not a prerequisite that keeps failing.)
+- **The generated transcript can be very large** (measured at ~346k tokens in one restore). Do **not**
+  read it front-to-back or claim to. `restore-instructions.md` declares its token cost up front; default
+  to the **most recent ~50k tokens of unique narrative first** (recency is what a restore needs — the
+  thread that produced the current frontier, not the boot handshake), and go earlier only if a specific
+  question requires it. A restore must leave room for the work it was restored to do.
+
 ## Required Read-Depth Audit
 
 After the first restore pass, audit yourself before continuing.
@@ -101,9 +127,15 @@ After the first restore pass, audit yourself before continuing.
 2. Mark each item as `FULL`, `PARTIAL`, or `NOT_READ`.
 3. You will be given a task where all of these files are required reading in
    order to understand the task.
-4. Do not optimize for token conservation.
-5. Read every `PARTIAL` or `NOT_READ` item in full now.
-6. Report the final read-depth table before doing any substantive task work.
+4. Read `PARTIAL`/`NOT_READ` items in full — but **to a declared budget with a stopping rule**, not
+   unbounded. Prioritize by relevance to the active task; for a large transcript read the most recent
+   unique narrative first (see *If You Just Compacted*), not front-to-back.
+5. **Stop** when either every task-relevant item is `FULL`, or you reach the budget — *a restore that
+   cannot leave room for the work it was restored to do is not a successful restore.* "Read everything,
+   never conserve" has no termination condition; that open-endedness is the bug, not the goal.
+6. Report the final read-depth table **honestly** (`FULL`/`PARTIAL`/`NOT_READ`, each with a reason)
+   before task work. **An honest `PARTIAL` with its reason is a correct outcome, not a failure** — do
+   not claim a completion you did not reach.
 
 ## Guardrails
 

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

@@ -6,12 +6,7 @@ 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");
-// 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 outRoot = "/tmp/claude-compaction-restore";
 const defaultRestoreInstruction =
   "Read the claude-compaction-restore skill and follow its \"If You Just Compacted\" protocol.";
 
@@ -29,14 +24,6 @@ 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}/")) {
@@ -54,50 +41,6 @@ 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,
@@ -115,28 +58,12 @@ 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: nowIso(),
+    createdAt: new Date().toISOString(),
     sessionName: process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || null,
     sessionId: input.session_id || input.sessionId || null,
     transcriptPath: input.transcript_path || null,
@@ -191,18 +118,13 @@ function readClaudeCompactionMessage() {
     parts.push(`Inline restore instruction:\n${inline}`);
   }
   if (filePath && filePath.length > 0) {
-    // 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.
+    try {
+      const fileText = readInstructionFile(filePath);
+      if (fileText) {
+        parts.push(`Additional restore instruction file (${filePath}):\n${fileText}`);
       }
+    } catch {
+      // Keep any inline instruction; unreadable extra files degrade quietly.
     }
   }
   if (parts.length > 0) return parts.join("\n\n");
@@ -218,16 +140,7 @@ 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

@@ -3,12 +3,26 @@ 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;
-// 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";
+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 = {
@@ -86,8 +100,9 @@ function stringifyContent(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(stringifyContent(block.content), TEXT_LIMIT)}`;
+        if (block?.type === "tool_result") return `[tool_result] ${truncate(stripBinary(stringifyContent(block.content)), TEXT_LIMIT)}`;
         return JSON.stringify(block);
       })
       .join("\n");
@@ -239,6 +254,8 @@ 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;
 
@@ -262,20 +279,26 @@ function analyze(jsonlPath, cwd) {
 
     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`);
@@ -284,12 +307,21 @@ function analyze(jsonlPath, cwd) {
           for (const file of extractPaths(text, cwd)) registry.add(file, kind, `tool:${name}:input`);
         }
       } else if (block?.type === "tool_result") {
-        const resultText = stringifyContent(block.content);
-        parts.push(`\n[tool_result]\n${truncate(resultText, TEXT_LIMIT)}`);
+        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
@@ -300,12 +332,17 @@ function analyze(jsonlPath, cwd) {
   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: transcript.join("\n"),
+    transcript: transcriptText,
+    narrative: narrativeText,
+    transcriptTokens: Math.round(transcriptText.length / 4),
+    narrativeTokens: Math.round(narrativeText.length / 4),
     files: rankedFiles,
     docs: discoverDocs(effectiveCwd),
   };
@@ -346,10 +383,18 @@ function restoreInstructions(summary, outputPaths) {
   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}\``);
+  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`.");
@@ -378,31 +423,25 @@ 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 = nowIso().replace(/[:.]/g, "-");
+  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, outputPaths }, null, 2));
+  fs.writeFileSync(outputPaths.summary, JSON.stringify({ ...summary, transcript: undefined, narrative: undefined, outputPaths }, null, 2));
 
   return outputPaths;
 }
@@ -421,6 +460,9 @@ function main() {
     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,
@@ -432,7 +474,8 @@ function main() {
     console.log(`Restore packet: ${result.outputDir}`);
     console.log(`Instructions: ${result.instructions}`);
     console.log(`Touched files: ${result.touchedFiles}`);
-    console.log(`Transcript: ${result.transcript}`);
+    console.log(`Narrative (read first): ${result.narrative} (~${result.narrativeTokens} tokens)`);
+    console.log(`Transcript (drill-down): ${result.transcript} (~${result.transcriptTokens} tokens)`);
   }
 }
 

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

@@ -1,7 +1,11 @@
 ---
 name: forming-an-openrig-mental-model
-description: |
-  Use when an agent is newly oriented to OpenRig and needs to form an accurate mental model of the system fast — what rigs are, how skills load, what the topology shapes mean, what the product loop is. For agents booting into a new seat or returning to OpenRig work after time away. NOT for compaction recovery (use claude-compaction-restore for that) or for specific operational procedures.
+description: >-
+  Use when the system around you does not make sense yet: you just booted into a seat and do not
+  know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not
+  certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do
+  not know how skills reach you or where context comes from; or you are about to act on a guess
+  about how OpenRig works. Gives the runtime mental model fast, so you stop guessing.
 metadata:
   cli_surfaces_referenced:
     - ask