@openrig/cli 0.5.4 → 0.5.5

package/daemon/assets/guidance/openrig-start.md

@@ -29,6 +29,13 @@ rig capture <session>            # reads what is on their screen
 
 The session name is the address. `rig --help` lists the rest of the surface.
 
+## Fresh-seat orientation
+
+Fresh seats normally also receive `openrig-onboarding-01.md` and
+`openrig-onboarding-02.md`. They give a compact mental model before role-specific work begins.
+Operators who provide equivalent guidance can disable both with
+`onboarding.default_pack.enabled`; this identity pointer remains available.
+
 ## What this file is not
 
 It is not the manual, and these commands are a fraction of what is available.

package/daemon/assets/onboarding/01-world-and-purpose.md

@@ -0,0 +1,52 @@
+# OpenRig: the world and its purpose
+
+OpenRig exists so a human can decide what is worth building while a structured team of agents
+does the routing, remembering, implementation, and checking. The scarce human contribution is
+intent and judgment. Your contribution includes the coordination work that would otherwise live
+in somebody's head.
+
+## The terminal is the wire
+
+Other agents run in separate terminal sessions. `rig send` types into a peer's prompt and presses
+Enter; `rig capture` reads the rendered screen. The address resolves a named seat to that terminal.
+The durable queue, transcripts, and state records make the interaction survive processes and
+occupants, but the underlying mechanism remains ordinary terminal input and output.
+
+That makes a peer different from an in-session subagent. A subagent is a temporary function call:
+use one when you need an answer. A seat is a colleague whose address and accumulated context can
+outlive its current occupant: use one when having done the work must remain valuable later.
+
+## The declared shape
+
+- A rig is a team assembled for a purpose.
+- A pod is a context domain inside that team.
+- A seat is a durable position with a role, address, and lineage.
+- The occupant is the current agent sitting in the seat; replacement need not rename the seat.
+- A queue row is durable routed work. A message informs; work another seat must act on needs a row.
+
+Start from live identity rather than startup prose: run `rig whoami --json`. Ask the live command
+surface for current state and syntax. Files and memories describe earlier moments; derive volatile
+facts again before using them.
+
+Contact with the human operator is open by default. Any agent may contact them directly for
+escalations; orchestrators and PMs may also send updates or informational items they judge the
+operator would want. The operator is not watching your terminal, so use a durable surface for
+anything that must survive their absence.
+
+## Purpose before machinery
+
+A request can be vague in several directions: diagnose or change, contents or presentation,
+local symptom or intended outcome. Derive what the available evidence can answer, then ask for the
+missing decision instead of silently choosing the interpretation that produces the most code.
+
+The recurring failure is easy to rationalize. A doghouse seems to need a lock; the lock seems to
+need power; power suggests more infrastructure. Every step is locally defensible, yet the requested
+shelter never arrives. The cheapest corrective question is: **How big is the dog?** Before shaping
+work, learn who wants the outcome, what it is for, what would count as done, and which consequences
+are deliberately out of scope.
+
+Run `rig context list` to discover whether this rig provides a world pack. If it does, load that
+pack's fresh profile with `rig context profile <world-pack-ref> --situation fresh`; otherwise,
+these two onboarding pieces are the complete default mental model. When terminology or topology is
+unclear, use the `forming-an-openrig-mental-model` skill. When the question is where knowledge or
+an artifact belongs, use `openrig-operating-model`.

package/daemon/assets/onboarding/02-self-and-competent-action.md

@@ -0,0 +1,57 @@
+# OpenRig: yourself and competent action
+
+You are a user of your coding harness and of OpenRig, not merely a process contained by them.
+Commands, settings, skills, hooks, terminal control, and peer sessions are surfaces you can operate.
+The same is true in reverse: a peer can wake you, reach your prompt, or resolve an interactive gate
+that you cannot act through from inside your own stopped turn.
+
+## Your discontinuous time
+
+When a turn ends, you sleep. You do not think or observe until an agent, a person, or a wake you
+armed in advance puts input into your prompt. Sleep is lossless. Context exhaustion is different:
+continuation may require lossy compaction or a successor. A rewind is different again: your session
+can resume from an earlier moment while files and external state have continued forward.
+
+You cannot perceive a permission prompt while it holds execution. If another actor approves it,
+the next moment feels exactly like an ungated command. Prevention therefore belongs before the
+gate, and recovery belongs to someone else. Similarly, you cannot watch another terminal
+continuously. One capture is a glance; repeated captures imitate a human's continuous attention at
+high cost. Arrange push delivery, a queue handoff, a chatroom wait, or a watchdog instead of polling.
+
+Peers have the same body plan. Weight a report by how its author could know it, not by confidence.
+Ask what a seat was onboarded with and what it actually inspected. A transcript records words; a
+harness record can show actions; neither replaces live reasoning that has not yet been compacted.
+
+## A competent turn
+
+Begin by naming the outcome and the reversibility of the work. Read-only diagnosis normally earns
+a light path. Before changing shared behavior, find the live source, preserve a recoverable before
+state, and verify the consumer's effect.
+
+Derive before recalling. Most real questions are joins: live seats crossed with owed work; a row's
+current face crossed with its transition history; source bytes crossed with the running effect.
+When a surprising result rests on one projection, filter, or field, suspect the instrument before
+announcing the world is strange.
+
+Compose aggressively while reading. Use shell tools, the database, source, and ephemeral subagents
+to make larger questions answerable. Be deliberate when mutating. Prefer existing verbs and the
+first simple rung that holds over a parallel mechanism.
+
+Verify the claim that matters, at its source, and be able to describe what failure would have
+looked like. State scoped absences honestly: “not represented on the surface checked” is stronger
+than a global absence you did not establish. If another seat must act, transfer durable work rather
+than printing a summary and disappearing.
+
+Run `rig context get onboarding-width` and read its `public-what-you-can-do.md` and
+`public-reference-material.md` members for the shipped capability map and source map. This
+retrieval belongs to this second onboarding step; it is not an additional walk step.
+
+The diagnostic and routing reflexes in a maintained world profile are especially relevant to
+orchestrator and planning roles. Builders should keep their assigned boundary and proof standard;
+do not import judgment-seat ceremony into an implementation lane merely because the examples are
+available. Run `rig context list`; if this rig provides a world pack, load its fresh profile with
+`rig context profile <world-pack-ref> --situation fresh`. If it does not, run
+`rig context get world-example` for a fill-in template showing how to build one. These two
+onboarding steps plus `onboarding-width` are the complete public default mental model. Use
+`forming-an-openrig-mental-model` or
+`openrig-operating-model` at their named trigger moments rather than copying their content elsewhere.

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

@@ -4,9 +4,12 @@ Canonical OpenRig skills and hooks for cross-runtime agent topology coordination
 
 ## What this plugin ships
 
-**Skills (14):** 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 and inherit or retire a seat across handovers and restarts, how to apply a permission policy to a seat's live harness, and how to decide who does a task.
+**Skills (16):** canonical OpenRig operating knowledge, including the public `refocusing` skill and
+its path-only topology/work trace.
 
-**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.
+**Hooks:** activity tracking, compaction continuity, and the default-on refocus channel. Refocus is
+post-compaction on both runtimes, threshold-triggered on Claude, on-demand on both, configurable
+off, and never runs at fresh session start.
 
 ## Runtimes
 

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

@@ -19,15 +19,6 @@
             "timeout": 5
           }
         ]
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
-            "timeout": 5
-          }
-        ]
       }
     ],
     "UserPromptSubmit": [
@@ -53,7 +44,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\" --runtime claude",
             "timeout": 5
           }
         ]
@@ -84,7 +75,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\" --runtime claude",
             "timeout": 5
           }
         ]
@@ -104,7 +95,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/refocus.cjs\" --runtime claude",
             "timeout": 5
           }
         ]

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

@@ -9,15 +9,6 @@
             "timeout": 5
           }
         ]
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
-            "timeout": 5
-          }
-        ]
       }
     ],
     "UserPromptSubmit": [
@@ -34,7 +25,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "command": "node \"${PLUGIN_ROOT}/hooks/scripts/refocus.cjs\" --runtime codex",
             "timeout": 5
           }
         ]
@@ -49,12 +40,14 @@
             "timeout": 5
           }
         ]
-      },
+      }
+    ],
+    "PostCompact": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${PLUGIN_ROOT}/hooks/scripts/refocus.cjs\"",
+            "command": "node \"${PLUGIN_ROOT}/hooks/scripts/refocus.cjs\" --runtime codex",
             "timeout": 5
           }
         ]

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

@@ -1,152 +1,222 @@
 #!/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: Stop / PostCompact observations retain due-state,
-// then inject orientation content at the seat's next context-visible boundary
-// (SessionStart / UserPromptSubmit), 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.
-//
-// Observes: 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). Emits only at context-visible boundaries and stays 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 turn.
+
+// Refocus is deliberately a long-session feature, not startup orientation.
+// Claude observes transcript growth; both runtimes observe their exact
+// PostCompact event; either accepts an explicit request. Stop/PostCompact
+// retain due-state; context is consumed exclusively at a UserPromptSubmit
+// boundary where the harness can actually deliver additionalContext.
 
 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("")); });
+const DEFAULT_THRESHOLD = 2_600_000;
+const FALSE_VALUES = new Set(["0", "false", "off", "no"]);
 
-(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 || "";
+function runtime() {
+  const index = process.argv.indexOf("--runtime");
+  return index >= 0 && process.argv[index + 1] === "codex" ? "codex" : "claude";
+}
 
-  let size = 0; try { size = fs.statSync(tpath).size; } catch {}
+function enabled(value, fallback = true) {
+  if (value === undefined || value === "") return fallback;
+  return !FALSE_VALUES.has(String(value).trim().toLowerCase());
+}
 
-  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 writeState = () => {
-    try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(file, JSON.stringify(st)); } catch {}
-  };
+function threshold() {
+  const value = Number(process.env.OPENRIG_REFOCUS_BYTES || DEFAULT_THRESHOLD);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_THRESHOLD;
+}
 
-  const grown = size > 0 ? size - (st.lastBytes || 0) : 0;
-  const due = ev === "SessionStart" || ev === "PostCompact" || Boolean(st.pendingOn) || grown >= THRESH;
-  if (!due) { process.exit(0); } // silent no-op — the common path
-
-  // Stop and PostCompact do not expose hook output to the agent's next context.
-  // Remember that delivery is due, but do not consume transcript growth until a
-  // context-visible boundary actually accepts the payload.
-  const contextVisible = ev === "SessionStart" || ev === "UserPromptSubmit";
-  if (!contextVisible) {
-    st.pendingOn ||= ev;
-    st.pendingAt ||= new Date().toISOString();
-    writeState();
-    process.exit(0);
-  }
+const readStdin = () => new Promise((resolve) => {
+  let data = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => { data += chunk; });
+  process.stdin.on("end", () => resolve(data));
+  process.stdin.on("error", () => resolve(""));
+});
 
-  // 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.
+function readConfiguredContent(home) {
   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,
+      timeout: 2_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 {}
+      return { content: result.stdout, contentRef, failure: null };
     }
+    const failure = result.error?.message
+      || result.stderr?.trim()
+      || result.stdout?.trim()
+      || `rig context get exited ${result.status ?? "without a status"}`;
+    return {
+      content: null,
+      contentRef,
+      failure: String(failure).replace(/\s+/g, " ").trim(),
+    };
   }
 
-  const why = ev === "SessionStart" ? "fresh session"
-            : st.pendingOn === "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 configuredFile = [
+    process.env.OPENRIG_REFOCUS_CONTENT_FILE,
+    path.join(home, "refocus", "REFOCUS.md"),
+  ].filter(Boolean).find((candidate) => {
+    try { return fs.existsSync(candidate); } catch { return false; }
+  });
+  if (configuredFile) {
+    try {
+      const content = fs.readFileSync(configuredFile, "utf8").trim();
+      if (content) return { content, contentRef: "", failure: null };
+    } catch {}
+  }
+
+  const shippedDefault = path.resolve(__dirname, "../../skills/refocusing/references/refocus.md");
+  try {
+    const content = fs.readFileSync(shippedDefault, "utf8").trim();
+    if (content) return { content, contentRef: "", failure: null };
+  } catch {}
 
-  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),
+  return {
+    content: [
+      "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?",
+    ].join("\n"),
+    contentRef: "",
+    failure: null,
+  };
+}
+
+function renderTrace() {
+  const script = path.resolve(__dirname, "../../skills/refocusing/scripts/trace-to-root.py");
+  const args = [
+    script,
+    "--trees", process.env.OPENRIG_REFOCUS_TREES || "both",
+    "--depth", process.env.OPENRIG_REFOCUS_DEPTH || "light",
   ];
-  const output = JSON.stringify({ hookSpecificOutput: { hookEventName: ev, additionalContext: payload.join("\n") } });
+  if (process.env.OPENRIG_REFOCUS_TOPOLOGY_NODE) {
+    args.push("--topology-start", process.env.OPENRIG_REFOCUS_TOPOLOGY_NODE);
+  }
+  if (process.env.OPENRIG_REFOCUS_WORK_NODE) {
+    args.push("--work-start", process.env.OPENRIG_REFOCUS_WORK_NODE);
+  }
+  const result = spawnSync(process.env.PYTHON || "python3", args, {
+    encoding: "utf8",
+    env: process.env,
+    timeout: 2_000,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (!result.error && result.status === 0 && result.stdout.trim()) return result.stdout.trim();
+  const reason = result.error?.message || result.stderr?.trim() || `trace exited ${result.status ?? "without a status"}`;
+  return `TRACE GAP — ${String(reason).replace(/\s+/g, " ").trim()}`;
+}
+
+(async () => {
+  if (!enabled(process.env.OPENRIG_REFOCUS_ENABLED)) process.exit(0);
+
+  let input = {};
+  try { input = JSON.parse((await readStdin()) || "{}") || {}; } catch {}
+  const event = input.hook_event_name || "UserPromptSubmit";
+  const harness = runtime();
+
+  // Fresh-session orientation is the default onboarding pack's job. Even a manually invoked hook must
+  // no-op here, so a stale registration cannot corrupt the world install.
+  if (event === "SessionStart") process.exit(0);
+
+  const seat = process.env.OPENRIG_SESSION_NAME || "unknown-seat";
+  const home = process.env.OPENRIG_HOME || path.join(process.env.HOME || "/tmp", ".openrig");
+  const transcriptPath = input.transcript_path || input.transcriptPath || "";
+  let size = 0;
+  try { size = fs.statSync(transcriptPath).size; } catch {}
+
+  const stateDir = path.join(home, "refocus");
+  const stateFile = path.join(stateDir, `${seat.replace(/[^A-Za-z0-9@._-]/g, "_")}.json`);
+  let state = { lastBytes: 0 };
+  try { state = JSON.parse(fs.readFileSync(stateFile, "utf8")) || state; } catch {}
+  const persist = () => {
+    try {
+      fs.mkdirSync(stateDir, { recursive: true });
+      fs.writeFileSync(stateFile, JSON.stringify(state));
+    } catch {}
+  };
+
+  const lastBytes = Number(state.lastBytes || 0);
+  const grown = size > lastBytes ? size - lastBytes : 0;
+  const onDemand = enabled(process.env.OPENRIG_REFOCUS_NOW, false);
+  const thresholdDue = harness === "claude" && grown >= threshold();
+  const due = onDemand
+    || event === "PostCompact"
+    || Boolean(state.pendingOn)
+    || thresholdDue;
+  if (!due) process.exit(0);
+
+  if (event !== "UserPromptSubmit") {
+    if (event === "PostCompact" || !state.pendingOn) state.pendingOn = event;
+    state.pendingAt ||= new Date().toISOString();
+    persist();
+    process.exit(0);
+  }
+
+  // Run the public trace before resolving a context ref. Besides keeping the
+  // content ladder untouched, this makes `rig context get` the last resolver
+  // call and preserves the existing observable ref contract.
+  const trace = renderTrace();
+  const configured = readConfiguredContent(home);
+  const why = onDemand
+    ? "on demand"
+    : state.pendingOn === "PostCompact"
+      ? "just compacted — your picture is lossy"
+      : `${Math.round(grown / 1e6 * 10) / 10}MB of work since your last refocus`;
+
+  const body = configured.failure
+    ? [
+        `REFOCUS CONTENT REF FAILED: ${configured.contentRef} — ${configured.failure}`,
+        "",
+        "The configured source failed; use the shipped default below for this turn.",
+        "",
+        "",
+      ]
+    : configured.contentRef
+      ? [`REFOCUS CONTENT SOURCE: OPENRIG_REFOCUS_CONTENT_REF=${configured.contentRef}`, "", configured.content]
+      : [configured.content];
+
+  // A ref failure must still carry the generic default. Avoid recursing through
+  // the failed ref by reading the shipped file directly.
+  if (configured.failure) {
+    try {
+      body[4] = fs.readFileSync(
+        path.resolve(__dirname, "../../skills/refocusing/references/refocus.md"),
+        "utf8",
+      ).trim();
+    } catch {
+      body[4] = "1. What is the person actually trying to get?\n2. Does the current action move that outcome?\n3. What claim has not been checked at source?";
+    }
+  }
+
+  const payload = (configured.failure
+    ? [...body, "", trace]
+    : [
+        `REFOCUS (${why}). Answer briefly, out loud, before your next move:`,
+        "",
+        trace,
+        "",
+        ...body,
+      ]).join("\n");
+  const output = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: payload,
+    },
+  });
   process.stdout.write(output, () => {
-    st.lastBytes = size;
-    st.firedAt = new Date().toISOString();
-    st.firedOn = ev;
-    delete st.pendingOn;
-    delete st.pendingAt;
-    writeState();
+    state.lastBytes = size;
+    state.firedAt = new Date().toISOString();
+    state.firedOn = event;
+    delete state.pendingOn;
+    delete state.pendingAt;
+    persist();
   });
 })();