@azure-id/orc 1.0.0 → 1.1.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.1.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,45 @@ 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"
+      );
+    }
+  } 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,

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 -->

package/templates/skills/_shared/wait.md

@@ -0,0 +1,240 @@
+# Shared contract — the WAIT (`/orc-wait`, and the computed gate)
+
+Canonical file: `_shared/wait.md`. THE canonical mechanic for a lane that must
+**stop where it stands, wait for wall-clock time to pass, and carry on from the
+same place**. Load it wherever a lane can be interrupted by a wait — which,
+since v1.1.0, is every lane in the table below.
+
+## Why a wait is not a suspend and not a fallback
+
+ORC already has two shapes for leaving a run. This is a third, and conflating
+them loses work.
+
+| | `FALLBACK-FROM` | `RETURN-TO` | **WAIT** |
+|---|---|---|---|
+| Why it leaves | it cannot proceed | another lane must settle something | **wall-clock time must pass** |
+| Who finishes | the receiver | the sender, after coming back | **the same lane, same run** |
+| Another lane runs | yes | yes | **no — nothing runs** |
+| Traces | one | two | **one** |
+
+A wait dispatches nothing and decides nothing. It is the only ORC mechanic
+whose entire purpose is that **no model is running**.
+
+## The one rule
+
+> **`a lane that waits without a hand-back` has broken this contract.**
+
+A wait is a stop. Every stop in ORC writes its hand-back before it ends, because
+the thing that resumes the run may not be this session — the user can close the
+terminal, the machine can sleep, and the wake-up message is a Claude Code
+behaviour ORC cannot promise. `RESUME.md` on disk is what makes a lost wake-up
+cost nothing.
+
+This is `_shared/phases/stop-resume.md` applied to a stop nobody asked a
+question about. It does not replace that phase; it scales it.
+
+## The three modes
+
+A wait is requested with a mode. The modes differ in ONE thing: how much the
+lane finishes before it stops.
+
+| Mode | Stops at | Hand-back | Dispatches | Can lose |
+|---|---|---|---|---|
+| `safe` | the next **safe point** | full stop sequence | yes (checkpoint) | nothing |
+| `soft` | the next **model turn** | full stop sequence, **forced** | yes (checkpoint) | an in-flight return |
+| `hard` | the next **model turn** | `RESUME.md` only, best effort | **no** | an in-flight return, the checkpoint, the phase's trace packet |
+
+**`soft` is forced.** On a lane the table below marks as checkpointing, `soft`
+does not merely attempt the hand-back: if the checkpoint write fails, **`soft`
+does not stop**. It reports the failure and stays in the run. That is
+`stop-resume.md` step 2 unchanged — *stopping without a good checkpoint is the
+one thing that loses work* — and it is the whole reason the mode exists.
+
+**`hard` is the dispatch-free stop.** It writes only what ORC can write with its
+own hand (`RESUME.md`, per stop-resume step 3b — never a dispatched agent). It
+is fast BECAUSE it dispatches nothing, not in spite of it. It is the one mode
+that can lose work, and it says so every time it runs.
+
+### "the next model turn" is the honest promise
+
+A typed message reaches ORC at a turn boundary. `hard` therefore **cannot**
+interrupt a dispatch that is already in flight. What it promises is:
+
+> stop at the first moment ORC can act, and do not wait for the current wave,
+> phase or gate to finish.
+
+Never write "immediately". A user who reads "immediately" and sees a wave finish
+believes the command failed.
+
+## Safe points
+
+A safe point is a place where the run can stop with no loss. `safe` waits for
+one. `soft` and `hard` do not — that is what they are for, and what they risk.
+
+**Never begin a wait at any of these, in any mode:**
+
+- between a dispatch and its validated return
+- inside the stop sequence itself
+- during a file write, a `splice`, or a wiki registration write
+- before the smoke gate has reported
+
+These are not a style preference. Each one leaves an artifact that no resume can
+reconstruct.
+
+## Which lanes support a wait
+
+The machine-readable copy of this table is `WAIT_LANE_SHAPES` in `bin/cli.js`,
+rendered by `orc wait lanes`. A golden test compares the two IN BOTH DIRECTIONS
+— the `EXTRA_LANE_SHAPES` / `DIY_STEPS` precedent. A lane added to one and not
+the other fails the suite.
+
+| Lane | Checkpoint | Safe point |
+|---|---|---|
+| `/orc` | full | wave or phase edge |
+| `/orc-ultra` | full | wave or judge gate |
+| `/orc-mini` | full | after the executor returns |
+| `/orc-fast` | full | after the executor returns |
+| `/orc-diy` | full | compiled phase edge |
+| `/orc-doc` | full | wave edge |
+| `/orc-wiki` | full | scan-task boundary |
+| `/orc-analyze` | full | after the analyst returns |
+| `/orc-poly` | docset | after a per-repo plan is written |
+| `/orc-quick` | entry | after an entry closes |
+| `/orc-challenge` | cycle | after a cycle records |
+| `/orc-brainstorm` | snapshot | phase edge |
+| `/orc-grill` | snapshot | round edge |
+| `/orc-learn` | none | single dispatch |
+| `/orc-plan` | none | single dispatch |
+| `/orc-verify` | none | single dispatch |
+| `/orc-pattern` | none | single dispatch |
+| `/orc-claude` | none | single dispatch |
+| `/orc-explain` | none | read-only, seconds long |
+| `/orc-route` | none | read-only, seconds long |
+| `/orc-boundary` | none | read-only, seconds long |
+| `/orc-budget` | none | read-only, seconds long |
+| `/orc-aftermath` | none | read-only, seconds long |
+| `/orc-export` | none | read-only, seconds long |
+| `/orc-retro` | none | read-only, seconds long |
+| `/orc-pact` | none | read-only, seconds long |
+
+**`checkpoint: none` is an ANSWER, not a gap.** A single-dispatch lane has
+nothing to checkpoint, so a wait there is a plain wait and the message says so.
+On such a lane `safe`, `soft` and `hard` are the SAME thing, and
+`orc wait lanes` states that rather than pretending to a distinction. A row that
+reads `none` must never render like a row that is missing.
+
+## The hop loop
+
+The lane does not sleep. A **detached** command sleeps. It costs zero tokens and
+no model runs during it.
+
+```
+1. Write the hand-back for the mode (above).
+2. remaining = the requested time, or resets_at - now
+3. hop = min(wait_hop_minutes, remaining)
+4. Run a DETACHED command that waits hop seconds.
+5. On wake: `orc usage check --json`
+6. Exit 0, or the requested time has elapsed → continue. Else go to 3.
+7. wait_max_hops reached → stop, keep the hand-back, say why.
+```
+
+**A hop is short on purpose.** Each wake-up is session activity, and session
+activity is the only thing that makes the statusline run again — so each hop
+buys a fresh reading. A single long sleep wakes into a reading as stale as the
+sleep was long.
+
+## After the wait — ORC does not drag a large context forward
+
+`stop-resume.md` step 6 already requires offering both continue paths. This
+decides which one ORC takes without asking:
+
+- **context small** → continue here, and say so in one line.
+- **context large** → STOP and offer both paths, recommending the fresh session.
+
+A wait longer than one hour has already expired the prompt cache, so continuing
+in-session re-reads the whole context at full input price — exactly when quota
+is lowest. Auto-continuing into a bloated context is the cost the wait existed
+to avoid.
+
+**ORC cannot clear its own context.** `/clear` is the user's action. The wait
+offers the swap; it never performs it.
+
+## The computed gate (`usage_gate`)
+
+The same engine, triggered by the CLI instead of by a typed command. It is
+**`off` by default** — nothing below happens until the user turns it on.
+
+Check **before a wave, never during one**: `orc usage check --json`.
+
+| exit | state | `warn` | `stop` | `wait` |
+|---|---|---|---|---|
+| 0 | ok | continue | continue | continue |
+| 1 | low | print and continue | hand back and stop | hand back, hop, come back |
+| 2 | unknown | print and continue | print and continue | print and continue |
+
+**Exit 2 never stops a run**, in any mode. An absent reading is absent, not low:
+older Claude Code sends no usage headers, and a long dispatch leaves the reading
+stale by exactly its own length. A gate that blocks on a missing number is a
+gate people switch off.
+
+**The worst window decides.** `orc usage check` already resolves that; never
+re-derive it from one window.
+
+A computed stop offers the cheaper answers before the expensive one — a lower
+band for this wave, or `orc extra` if a profile is ready — because a wait is the
+only one of them that costs wall-clock time.
+
+**A typed `/orc-wait` is never suppressed by any of this**, and a computed wait
+is suppressed entirely while a block is active.
+
+## The block — the user's veto
+
+`/orc-wait block <reason>` suppresses every COMPUTED wait for the rest of the
+run. It is for the case where stopping costs more than continuing: the window
+resets in five minutes and the task needs ten.
+
+1. **The reason is REQUIRED.** A block with no reason is refused by name. The
+   recorded reason is what makes the risk demonstrably the user's — the same
+   `--reason` rule the run-close and doc-ship writers already use.
+2. **Run-scoped. It NEVER writes the user's config.** The same rule the ultra
+   lane's forced run-scoped mode already follows. A veto set today must not
+   apply to a run started next month.
+3. **It is ANNOUNCED at every gate it suppresses, with its age.** A shadowed
+   setting must never be silent. There is no auto-expiry — ORC does not decide
+   that a user's reason stopped being true — so the age is what keeps an old
+   block from applying invisibly.
+4. **It blocks what ORC COMPUTES, never what the user TYPES.** A typed
+   `/orc-wait 30 hard` still waits while a block is active. `/orc-boundary`'s
+   rule, unchanged: a gate constrains ORC's own dispatch, never an explicit
+   instruction.
+5. It survives a resume, and is re-announced on the first gate after it.
+
+`orc wait cancel` is a DIFFERENT command: it ends a wait that is already
+running. Block is before, cancel is during. Never conflate them in prose or in a
+menu.
+
+## What a wait never does
+
+- It never dispatches an agent to do the waiting. An agent runs on the same
+  account and consumes the same window the wait exists to protect.
+- It never runs another lane.
+- It never writes the user's config.
+- It never widens or narrows the work: the same tasks, the same slice, the same
+  agent resolve after the wait as before it.
+- It never decides on its own that a user's block has expired.
+
+## Trace
+
+The wait writes CLI-composed lines into the trace that is ALREADY open, and
+nothing when no run is active. `/orc-wait` opens no run, so it is **not a lane**
+in the trace enum and has no `run-<lane>-<slug>` pointer — the `/orc-explain`
+precedent, a stated blind spot rather than an oversight.
+
+```
+WAIT   mode=hard requested=30m start=18:44 end=19:14 hops=1/4 trigger=user
+WAIT   block reason="window resets in 5m, task needs 10" by=user
+WAIT   unblock
+```
+
+A wait that leaves no line cannot be counted, and a block that leaves no line
+hides the fact that a run continued through a gate on the user's authority.

package/templates/skills/orc/SKILL.md

@@ -235,4 +235,9 @@ a `trim` layer beside the `full` one.
 | 8 | Ship | `../_shared/phases/ship.md` | `full` | `PHASE ship`, `FINISH` |
 
 Phase 4 runs only in worktree mode. Phases 5.5, 6.5 and 6.7 are opt-in and
-their config key is resolved by `orc lane config orc --json`, never read raw.
+their config key is resolved by `orc lane config orc --json`, never read raw.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **full** · safe point **wave or phase edge**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

package/templates/skills/orc-aftermath/SKILL.md

@@ -150,4 +150,9 @@ exit code, and never re-derive a state word — the CLI's state words are the on
 state words, and **an exit code is an ANSWER wherever that contract says so, not
 a failure**. A call the answer does not name is a call this lane does not make.
 Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
+command you are about to run, out loud, before running it.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **none** · safe point **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

package/templates/skills/orc-analyze/SKILL.md

@@ -244,4 +244,9 @@ exit code, and never re-derive a state word — the CLI's state words are the on
 state words, and **an exit code is an ANSWER wherever that contract says so, not
 a failure**. A call the answer does not name is a call this lane does not make.
 Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
+command you are about to run, out loud, before running it.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **full** · safe point **after the analyst returns**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

package/templates/skills/orc-boundary/SKILL.md

@@ -241,4 +241,9 @@ exit code, and never re-derive a state word — the CLI's state words are the on
 state words, and **an exit code is an ANSWER wherever that contract says so, not
 a failure**. A call the answer does not name is a call this lane does not make.
 Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
+command you are about to run, out loud, before running it.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **none** · safe point **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

package/templates/skills/orc-brainstorm/SKILL.md

@@ -369,4 +369,9 @@ exit code, and never re-derive a state word — the CLI's state words are the on
 state words, and **an exit code is an ANSWER wherever that contract says so, not
 a failure**. A call the answer does not name is a call this lane does not make.
 Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
+command you are about to run, out loud, before running it.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **snapshot** · safe point **phase edge**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

package/templates/skills/orc-budget/SKILL.md

@@ -240,4 +240,9 @@ exit code, and never re-derive a state word — the CLI's state words are the on
 state words, and **an exit code is an ANSWER wherever that contract says so, not
 a failure**. A call the answer does not name is a call this lane does not make.
 Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
+command you are about to run, out loud, before running it.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **none** · safe point **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.