@azure-id/orc 1.0.0 → 1.2.0

package/bin/webui/js/panels/wait.js

@@ -0,0 +1,253 @@
+"use strict";
+/* panels/wait.js — orc ui client
+   The usage window, and the wait that answers it.
+
+   THE PANEL DERIVES NOTHING. Not the state word, not which window is worst,
+   not the threshold, not a lane's checkpoint kind, not whether a wait is
+   running. It draws `orc usage check --json` and `orc wait … --json`. (The
+   Flow-stepper rule: a second idea of the mechanic is exactly the drift this
+   panel exists to make impossible.)
+
+   AND IT CANNOT START A WAIT. A wait lives in a Claude Code session, and
+   `orc ui` never runs a lane. What it can do is show the reading, show a wait
+   that is running, cancel one, and lift a block. Everything that COSTS a
+   decision — starting a wait, blocking a gate — is a copy-able command.
+
+   Loaded by app.html in the order its numeric prefix names. Classic script,
+   no import/export: an ES module import carries no query string, and every
+   static request here needs the per-launch session token. */
+
+/* ------------------------------------------------------------------- WAIT */
+
+// The CLI's own state words, and only those. A friendlier synonym would be a
+// state that does not exist.
+const USAGE_KIND = { ok: "ok", low: "warn", unknown: null };
+
+PANELS.wait = function (host) {
+  head(host, t("wait.title"), t("wait.sub"));
+
+  section(
+    host,
+    () =>
+      Promise.all([
+        read("/api/usage").then((r) => r.data),
+        read("/api/wait/status").then((r) => r.data),
+        read("/api/wait/lanes").then((r) => r.data),
+      ]),
+    ([usage, status, lanes]) => {
+      const out = frag();
+      out.append(usageCard(usage));
+      out.append(runCard(status));
+      out.append(lanesCard(lanes));
+      out.append(settingsCard(usage));
+      return out;
+    }
+  );
+};
+
+// ── the reading ────────────────────────────────────────────────────────────
+function usageCard(u) {
+  const c = card(t("wait.window"));
+  if (!u) return c;
+
+  // UNKNOWN IS A STATE, NOT A GAP. It gets the same card, the same size and a
+  // sentence saying a run is never stopped on it — because the alternative is a
+  // user believing the gate is watching when Claude Code sends no headers.
+  if (u.state === "unknown") {
+    const row = el("div", "row-actions");
+    row.append(chip(u.state, null));
+    c.append(row);
+    c.append(el("div", "note", u.reason || ""));
+    c.append(el("div", "note", u.note || ""));
+    c.append(gateNote(u));
+    return c;
+  }
+
+  const row = el("div", "row-actions");
+  row.append(chip(u.state, USAGE_KIND[u.state]));
+  if (u.worst) row.append(chip(t("wait.worst", { w: u.worst }), u.state === "low" ? "warn" : null));
+  if (typeof u.reading_age_minutes === "number")
+    row.append(chip(tn(u.reading_age_minutes, "wait.age"), null));
+  c.append(row);
+
+  const rows = [];
+  for (const w of [u.five_hour, u.seven_day]) {
+    if (!w) continue;
+    rows.push([
+      w.window,
+      // The bar is a WIDTH INSIDE the row, so nothing can fight it for space.
+      barFor(w),
+    ]);
+  }
+  const grid = el("div", "wait-windows");
+  for (const [label, node] of rows) {
+    const r = el("div", "wait-win");
+    r.append(el("span", "mono wait-win-label", label));
+    r.append(node);
+    grid.append(r);
+  }
+  c.append(grid);
+
+  // A context figure the CLI could not compute is an em dash, never a guess.
+  const ctx = el("div", "note");
+  ctx.textContent =
+    typeof u.context === "number"
+      ? t("wait.context", { n: String(u.context) })
+      : t("wait.contextUnknown");
+  c.append(ctx);
+  if (typeof u.context === "number" && u.context >= 70)
+    c.append(el("div", "note warn", t("wait.contextLarge")));
+
+  c.append(el("div", "note", u.note || ""));
+  c.append(gateNote(u));
+  return c;
+}
+
+function barFor(w) {
+  const wrap = el("div", "wait-bar-wrap");
+  const bar = el("div", "wait-bar" + (w.low ? " low" : ""));
+  const fill = el("div", "wait-bar-fill");
+  fill.style.width = Math.max(0, Math.min(100, w.used_percentage)) + "%";
+  bar.append(fill);
+  wrap.append(bar);
+  const txt = el("span", "wait-bar-text");
+  txt.textContent =
+    w.used_percentage +
+    "% · " +
+    t("wait.left", { n: String(w.remaining_percentage) }) +
+    (w.resets_in_minutes != null ? " · " + t("wait.resets", { t: mins(w.resets_in_minutes) }) : "");
+  wrap.append(txt);
+  return wrap;
+}
+
+const mins = (n) => (n < 60 ? n + "m" : Math.floor(n / 60) + "h" + (n % 60 ? (n % 60) + "m" : ""));
+
+function gateNote(u) {
+  const n = el("div", "note");
+  n.textContent =
+    u.gate === "off"
+      ? t("wait.gateOff")
+      : t("wait.gateOn", { gate: u.gate, pct: String(u.stop_pct) });
+  return n;
+}
+
+// ── the run: a wait running, a block standing, or neither ──────────────────
+function runCard(s) {
+  const c = card(t("wait.run"));
+  if (!s || !s.run) {
+    // KEEPS ITS SLOT. "No run in flight" is an answer.
+    c.append(empty(t("wait.noRun"), t("wait.noRunHint")));
+    c.append(laneCommand("/orc-wait 30", t("wait.startWhy")));
+    return c;
+  }
+
+  const row = el("div", "row-actions");
+  row.append(el("span", "mono", s.run));
+  if (s.waiting) row.append(chip(t("wait.waiting"), "warn", true));
+  if (s.blocked) row.append(chip(t("wait.blocked"), "bad"));
+  if (!s.waiting && !s.blocked) row.append(chip(t("wait.idle"), null));
+  c.append(row);
+
+  if (s.waiting) {
+    c.append(
+      el(
+        "div",
+        "note",
+        t("wait.hops", {
+          mode: s.mode || "?",
+          done: String(s.hops_done || 0),
+          planned: String(s.hops_planned || "?"),
+          ends: s.ends_at ? new Date(s.ends_at).toLocaleTimeString() : "?",
+        })
+      )
+    );
+    c.append(el("div", "note", t("wait.zeroTokens")));
+    if (s.cancel_requested) c.append(el("div", "note warn", t("wait.cancelPending")));
+    // FREE action → a real button.
+    else c.append(actionRow("wait.cancel", "/api/wait/cancel", { slug: s.run }, t("wait.cancelWhy")));
+  }
+
+  if (s.blocked) {
+    const b = el("div", "wait-block");
+    b.append(el("div", "wait-block-head", t("wait.blockHead")));
+    // The reason VERBATIM. It is the record that makes the risk the user's.
+    b.append(el("div", "wait-block-reason", s.block_reason || ""));
+    // The AGE is what keeps an old block from applying invisibly — there is no
+    // auto-expiry, so the panel must always show how old it is.
+    if (typeof s.block_age_minutes === "number")
+      b.append(el("div", "note", tn(s.block_age_minutes, "wait.blockAge")));
+    b.append(el("div", "note", t("wait.blockRisk")));
+    b.append(actionRow("wait.unblock", "/api/wait/unblock", { slug: s.run }, t("wait.unblockWhy")));
+    c.append(b);
+  } else {
+    // A block CANNOT be created here: it needs a reason typed in the moment.
+    c.append(laneCommand("/orc-wait block <reason>", t("wait.blockWhy")));
+  }
+  return c;
+}
+
+// NOTE the parameter name: `route` is the ROUTER's function, and shadowing it
+// here made the post-action refresh call a string.
+function actionRow(labelKey, endpoint, body, why) {
+  const wrap = el("div", null);
+  const row = el("div", "row-actions");
+  const b = el("button", "btn btn-sm", t(labelKey));
+  b.type = "button";
+  b.addEventListener("click", async () => {
+    b.disabled = true;
+    try {
+      const r = await post(endpoint, body);
+      toast(r && r.ok ? t("wait.done") : t("wait.failed"), r && r.ok ? "ok" : "bad");
+      route();
+    } catch (e) {
+      toast(t("wait.failed"), "bad", String(e));
+      b.disabled = false;
+    }
+  });
+  row.append(b);
+  wrap.append(row);
+  if (why) wrap.append(el("div", "note", why));
+  return wrap;
+}
+
+// ── which lanes support a wait ─────────────────────────────────────────────
+function lanesCard(d) {
+  const c = card(t("wait.lanes"));
+  if (!d || !d.lanes) return c;
+  c.append(el("div", "note", t("wait.lanesWhy")));
+  const list = el("div", "wait-lanes");
+  for (const l of d.lanes) {
+    const r = el("div", "wait-lane");
+    r.append(el("span", "mono wait-lane-name", l.lane));
+    // `none` KEEPS ITS SLOT and reads as its own state, never as a blank.
+    r.append(chip(l.checkpoint, l.modes_differ ? "ok" : null));
+    r.append(el("span", "wait-lane-safe", l.safe_point));
+    r.append(el("div", "note wait-lane-detail", l.detail));
+    list.append(r);
+  }
+  c.append(list);
+  c.append(el("div", "note", d.note || ""));
+  return c;
+}
+
+// ── settings: read-only here, edited where every other key is edited ───────
+function settingsCard(u) {
+  const c = card(t("wait.settings"));
+  c.append(
+    kvList([
+      ["usage_gate", u && u.gate ? u.gate : "—"],
+      ["usage_stop_pct", u && u.stop_pct != null ? String(u.stop_pct) : "—"],
+    ])
+  );
+  // A SECOND editor for keys Settings already stages would be a second idea of
+  // the same thing — the drift this panel exists to prevent. Route to the panel
+  // that can change it instead (the FINDING_ROUTE rule).
+  c.append(el("div", "note", t("wait.settingsWhy")));
+  const b = el("button", "btn btn-ghost btn-sm", t("wait.openSettings"));
+  b.type = "button";
+  b.addEventListener("click", () => (location.hash = "#/settings"));
+  const row = el("div", "row-actions");
+  row.append(b);
+  c.append(row);
+  return c;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-id/orc",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "ORC — an orchestrator skill constellation for Claude Code: intake, planning, scored parallel subagents, code-pattern matching, review, verify, ship, plus a project knowledge-base wiki.",
   "bin": {
     "orc": "bin/cli.js"

package/templates/commands/orc-wait.md

@@ -0,0 +1,19 @@
+---
+description: Wait for wall-clock time to pass — usually a quota window reset — without losing the run you are in
+---
+
+Run the `orc-wait` skill.
+
+The user typed: `$ARGUMENTS`
+
+Parse the arguments as `<spec> [mode]`, where:
+
+- `<spec>` is `30` · `90m` · `2h` · `2h30m` · `until 18:41` · `reset`
+- `[mode]` is `safe` · `soft` · `hard`, or absent
+- `block <reason>` and `unblock` are the veto, not a wait — see the skill
+
+Never compute the hops yourself. `orc wait plan <spec> --json` does that, and it
+is the only place that arithmetic exists.
+
+A wait is a STOP: write the hand-back before you wait, every time, in every
+mode. `a lane that waits without a hand-back` has broken the contract.

package/templates/hooks/orc-statusline.js

@@ -90,6 +90,84 @@ process.stdin.on("end", () => {
     }
   } catch (_) {}
 
+  // ── Usage bridge (v1.1.0 W4, fail-silent) ─────────────────────────────────
+  // The `rate_limits` block below reaches ONLY this process: the statusline
+  // renders a string and exits, so nothing else in ORC has ever been able to
+  // see how full the window is. A lane therefore started a wave with no idea it
+  // was about to run out, and the wave stopped in the middle.
+  //
+  // Persist the RAW numbers (never a computed word like `LOW` — a stored state
+  // is wrong one minute later; `orc usage check` computes it on read) plus
+  // `context_window`, which the wait needs to decide whether continuing
+  // in-session is cheaper than a fresh one. Same fail-silent contract as the
+  // session-model bridge above: any error is swallowed, and a reading older
+  // than its freshness window reads as `unknown`, never as `low`.
+  try {
+    const rl0 = d.rate_limits;
+    const cw0 = d.context_window;
+    if (rl0 || cw0) {
+      const fs = require("fs");
+      const path = require("path");
+      const projectDir =
+        (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
+      const orcDir = path.join(projectDir, ".claude", "orc");
+      const win = (o) =>
+        o && typeof o.used_percentage === "number"
+          ? { used_percentage: o.used_percentage, resets_at: o.resets_at == null ? null : o.resets_at }
+          : null;
+      fs.mkdirSync(orcDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(orcDir, "usage.json"),
+        JSON.stringify({
+          five_hour: win(rl0 && rl0.five_hour),
+          seven_day: win(rl0 && rl0.seven_day),
+          context_used_percentage:
+            cw0 && typeof cw0.used_percentage === "number" ? cw0.used_percentage : null,
+          written_at: Date.now(),
+        }) + "\n"
+      );
+      // -- Session consumption (v1.2.0) -------------------------------------
+      // `usage.json` is a SNAPSHOT of the window. It cannot answer "how much
+      // has THIS session eaten", which is the question a user actually asks
+      // mid-run -- and the one they could otherwise only answer by remembering
+      // what the number was an hour ago.
+      //
+      // So keep a per-session ledger beside it: the reading when this session
+      // first rendered, and the reading now. Same rules as every other bridge
+      // here -- RAW numbers only, never a computed word, fail-silent, and the
+      // reader decides what it means.
+      //
+      // A window RESET mid-session (used_percentage drops) is not a refund:
+      // bank what was consumed before the reset into `accumulated` and
+      // re-baseline, so the running total keeps counting across the boundary.
+      const sid = String(d.session_id || d.sessionId || "");
+      const sfile = path.join(orcDir, "usage-session.json");
+      let led = null;
+      try { led = JSON.parse(fs.readFileSync(sfile, "utf8")); } catch (_) {}
+      const pctOf = (o) => (o && typeof o.used_percentage === "number" ? o.used_percentage : null);
+      const track = (prev, cur) => {
+        if (cur == null) return prev || null;
+        if (!prev) return { baseline: cur, last: cur, accumulated: 0, resets: 0 };
+        if (cur < prev.baseline)
+          return {
+            baseline: cur,
+            last: cur,
+            accumulated: prev.accumulated + Math.max(0, prev.last - prev.baseline),
+            resets: prev.resets + 1,
+          };
+        return { baseline: prev.baseline, last: cur, accumulated: prev.accumulated, resets: prev.resets };
+      };
+      if (!led || led.session_id !== sid) led = { session_id: sid, started_at: Date.now() };
+      led.five_hour = track(led.five_hour, pctOf(rl0 && rl0.five_hour));
+      led.seven_day = track(led.seven_day, pctOf(rl0 && rl0.seven_day));
+      led.context_used_percentage =
+        cw0 && typeof cw0.used_percentage === "number" ? cw0.used_percentage : null;
+      led.updated_at = Date.now();
+      fs.writeFileSync(sfile, JSON.stringify(led) + "\n");
+    }
+
+  } catch (_) {}
+
   // ── Subscription usage (Claude Code v2.1.80+) ──────────────────────────────
   // Official 5-hour + 7-day usage, surfaced by Claude Code straight from
   // Anthropic's API headers into this payload's `rate_limits`. Display-only,
@@ -197,6 +275,24 @@ process.stdin.on("end", () => {
   // older Claude Code that doesn't surface `rate_limits`.
   if (rlSeg) line += " · " + rlSeg;
 
+  // How far the window moved while THIS session ran (v1.2.0). The ledger below
+  // keeps the raw numbers; this renders the delta. Never shown as "this session
+  // used X%" — the window is per ACCOUNT, and a second terminal moves it too.
+  try {
+    const fs = require("fs");
+    const path = require("path");
+    const projectDir =
+      (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
+    const led = JSON.parse(
+      fs.readFileSync(path.join(projectDir, ".claude", "orc", "usage-session.json"), "utf8")
+    );
+    const w = led && led.five_hour;
+    if (w && typeof w.last === "number" && typeof w.baseline === "number") {
+      const used = Math.max(0, (w.accumulated || 0) + Math.max(0, w.last - w.baseline));
+      if (used > 0) line += " · sess +" + used + "%";
+    }
+  } catch (_) {}
+
   // Wiki freshness tier (computed on read from wiki-meta.json — zero model
   // tokens; the manifest is written only by `orc wiki sync`). Fail-silent: no
   // wiki / no git / any error → no segment. Thresholds mirror the config
@@ -301,5 +397,135 @@ process.stdin.on("end", () => {
     } catch (_) {}
   }
 
-  process.stdout.write(line);
+  // ── Session line (v1.2.0) ──────────────────────────────────────────────────
+  // Line 1 answers "what tier am I on and how full is the window". This second
+  // line answers "what has this session actually been DOING" — how many agents
+  // it spawned, which lanes ran, whether work can leave Claude, and how long it
+  // has been going. All of it is read from disk; none of it costs a model call.
+  //
+  // The dispatch count is the one that earns its place. v1.2.0 exists because a
+  // retry cloned a live agent three times over and nothing surfaced it. A count
+  // that says `7 (2 running)` makes that visible from the status bar.
+  //
+  // Fail-silent and THROTTLED: the statusline re-renders on every keystroke, so
+  // the trace scan runs at most every 5s and its answer is cached in the same
+  // per-session ledger. Any error → no second line, never a broken one.
+  let line2 = "";
+  try {
+    const fs = require("fs");
+    const path = require("path");
+    const projectDir =
+      (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
+    const orcDir = path.join(projectDir, ".claude", "orc");
+    const sfile = path.join(orcDir, "usage-session.json");
+    const sid = String(d.session_id || d.sessionId || "");
+
+    let led = null;
+    try { led = JSON.parse(fs.readFileSync(sfile, "utf8")); } catch (_) {}
+    if (!led || led.session_id !== sid) led = { session_id: sid, started_at: Date.now() };
+
+    // The hook cannot read the RESOLVED config — that is the lane resolver's
+    // job, and a hook has no lane — so this reads the two raw keys it needs
+    // straight from the file and takes the documented default
+    // otherwise — the same caveat the wiki segment above already carries. A
+    // user override shifts skill behaviour; this label follows the file.
+    let logRel = ".claude/orc/logs";
+    let extraOn = false;
+    try {
+      const raw = fs.readFileSync(path.join(projectDir, ".claude", "orc.config.yaml"), "utf8");
+      const ld = /^[ \t]*log_dir:[ \t]*["']?([^"'#\r\n]+)/m.exec(raw);
+      if (ld) logRel = ld[1].trim();
+      extraOn = /^[ \t]*extra_enabled:[ \t]*true[ \t]*$/m.test(raw);
+    } catch (_) {}
+
+    const now = Date.now();
+    // The scan interval is the ONE seam over this budget, on the
+    // ORC_TEST_PROBE_MS precedent: a test that proves the throttle by SLEEPING
+    // past it is a test that fails on a loaded machine, and a flake is recorded
+    // and removed, never retried away. Unset, this is byte-identical to a
+    // hardcoded 5000, and nothing in ORC ever sets it.
+    const scanEvery = (() => {
+      const n = Number(process.env.ORC_STATUSLINE_SCAN_MS);
+      return Number.isFinite(n) && n >= 0 ? n : 5000;
+    })();
+    const stale = !led.dispatch || typeof led.dispatch.scanned_at !== "number" ||
+      now - led.dispatch.scanned_at >= scanEvery;
+    if (stale) {
+      const logDir = path.isAbsolute(logRel) ? logRel : path.join(projectDir, logRel);
+      const sessionFloor = Math.floor((led.started_at || 0) / 1000) * 1000;
+      let spawns = 0;
+      let running = 0;
+      const lanes = [];
+      try {
+        for (const f of fs.readdirSync(logDir)) {
+          if (!f.startsWith("run-") || !f.endsWith(".txt")) continue;
+          const full = path.join(logDir, f);
+          // Only traces touched since this session began. A trace from last
+          // week is not this session's spend.
+          let st;
+          try { st = fs.statSync(full); } catch (_) { continue; }
+          if (st.mtimeMs < (led.started_at || 0)) continue;
+          const text = fs.readFileSync(full, "utf8");
+          // Count by the trace's OWN line timestamps, not the file's mtime. A
+          // run that was already going when this session started shares its
+          // file with the session before it, and mtime cannot tell the two
+          // apart — it would attribute the whole file to whoever looked last.
+          let mine = 0;
+          for (const raw of text.split("\n")) {
+            const t = /^\[(\d{2})(\d{2})(\d{2}) (\d{2}):(\d{2}):(\d{2})/.exec(raw);
+            if (!t) continue;
+            if (raw.indexOf("] hook") === -1 || raw.indexOf(" SPAWN ") === -1) continue;
+            const at = new Date(
+              2000 + Number(t[3]), Number(t[2]) - 1, Number(t[1]),
+              Number(t[4]), Number(t[5]), Number(t[6])
+            ).getTime();
+            // Trace stamps have SECOND resolution and started_at has
+            // milliseconds, so a dispatch in the same second as the
+            // session start compares as earlier than it. Floor the
+            // boundary to the second the trace could actually express.
+            if (at >= sessionFloor) mine += 1;
+          }
+          spawns += mine;
+          let openHere = 0;
+          try {
+            const pend = JSON.parse(fs.readFileSync(full + ".pending.json", "utf8"));
+            if (Array.isArray(pend)) openHere = pend.length;
+          } catch (_) {}
+          running += openHere;
+          // A lane earns its name by having actually dispatched in this
+          // session — listing a lane that contributed nothing is noise.
+          if (mine > 0 || openHere > 0) {
+            const m = /^run-([a-z0-9-]+?)-.+-\d{6}-\d{6}\.txt$/.exec(f);
+            if (m && lanes.indexOf(m[1]) === -1) lanes.push(m[1]);
+          }
+        }
+      } catch (_) {}
+      led.dispatch = { spawns, running, lanes, scanned_at: now };
+    }
+
+    led.updated_at = now;
+    try {
+      fs.mkdirSync(orcDir, { recursive: true });
+      fs.writeFileSync(sfile, JSON.stringify(led) + "\n");
+    } catch (_) {}
+
+    const dsp = led.dispatch || { spawns: 0, running: 0, lanes: [] };
+    const parts = [];
+    // `running` is never hidden, because an agent still in flight is the thing
+    // a user most needs to see (v1.2.0). Zero is simply not printed.
+    parts.push(
+      "agents " + dsp.spawns + (dsp.running ? " (" + dsp.running + " running)" : "")
+    );
+    parts.push("orc-extra: " + (extraOn ? "on" : "off"));
+    // An empty lane list means no ORC lane has dispatched yet this session —
+    // an ANSWER, not a gap, so it keeps its slot and says so.
+    parts.push("lanes: " + (dsp.lanes.length ? dsp.lanes.join(", ") : "none yet"));
+    if (led.started_at)
+      parts.push(Math.max(0, Math.round((now - led.started_at) / 60000)) + "m");
+    line2 = "   " + parts.join(" · ");
+  } catch (_) {
+    line2 = "";
+  }
+
+  process.stdout.write(line2 ? line + "\n" + line2 : line);
 });

package/templates/skills/_shared/phases/execution.md

@@ -91,6 +91,8 @@ the codifier); hold resolved patterns in run state.
 invalidates a DONE task → re-run once, then set every reverse-`depends_on`
 consumer to `stale_review`. **Worker failure/garbage/timeout:** flag +
 continue the wave; audit and re-dispatch at the next batch checkpoint
+
+**Before any re-dispatch, run `orc run inflight`** (0 clear · 1 in-flight · 2 unknown). A Task error does not kill the agent behind it, and exit 2 REFUSES by default — `a lane that re-dispatches over a live attempt` has broken the contract. Canonical: `../return-validation.md`.
 (`requeued`, retry_count++). Hard retry cap 2 → STOP and surface.
 
 <!-- /orc:layer -->

package/templates/skills/_shared/phases/preflight.md

@@ -55,6 +55,28 @@ never a fifth step before step 2.
   ledger yet, this is a first run"; `orc gotcha status` exit 1 is an empty
   ledger. Say what it means, not that it failed.
 
+## The usage line (v1.1.0) — printed whenever `usage_gate` is armed
+
+`usage_gate` resolves in step 1 like any other key. When it is anything but
+`off`, run `orc usage check --json` in step 3 and print ONE line:
+
+```
+usage:    5h 71% · wk 38% · gate at 10% left · warn
+usage:    unknown (no reading in the last 30 minutes) · a run is never stopped on this
+```
+
+Both spellings are mandatory in their state. A gate that prints only when it
+fires is a gate the user cannot tell from a gate that is not running — and the
+`unknown` line is what stops someone believing they are protected when Claude
+Code is sending no usage headers at all.
+
+**Exit 2 (`unknown`) NEVER stops a run.** Absent is not low.
+
+A `blocked` run (`orc wait status --json`) prints the block and its AGE here too,
+and again at every gate it suppresses. The rest of the mechanic — the modes, the
+hops, what `stop` and `wait` actually do — is `../wait.md`; this file only says
+that the line is printed and when.
+
 <!-- /orc:layer -->
 
 <!-- orc:layer full -->