@azure-id/orc 1.0.0 → 1.2.0

package/bin/cli.js

@@ -105,6 +105,12 @@ function positionals() {
       i++; // skip the flag's value
       continue;
     }
+    // v1.1.0 W1 — `orc wait plan 5h --max-hops 3` must not read "3" as part of
+    // the spec: "5h 3" parses as 5h3m, so the wait silently gains three minutes.
+    if (a === "--hop" || a === "--max-hops") {
+      i++;
+      continue;
+    }
     // `orc extra` takes value-flags that can legally precede a positional
     // (`orc extra add --provider deepseek deepseek`), and a value swallowed
     // as a positional is a profile named after a provider id.
@@ -1161,6 +1167,10 @@ const CONFIG_FAMILIES = {
   retro: { contested: false, question: "where a retro is delivered" },
   paths: { contested: false, question: "where ORC writes on disk" },
   session: { contested: false, question: "what the main session itself runs as" },
+  // v1.1.0 — when ORC stops for wall-clock time, and how much it finishes
+  // first. EVERY default here is off or ask: nothing in this family may stop a
+  // run the user did not ask it to stop.
+  wait: { contested: false, question: "when a run stops to wait for quota, and how much it finishes first" },
 };
 
 // Ordered, tiered metadata. Common first, then advanced.
@@ -1198,6 +1208,17 @@ const CONFIG_META = [
   { key: "stacked_pr_loc", def: 1000, tier: "common", answers: [{ family: "pr", prio: "P2", mode: "replace" }], lanes: ["orc", "orc-pr-setup"], validate: vInt(1), options: [500, 800, 1000, 1500, 2000], desc: "Change LoC (additions+deletions, exclusions applied) >= this trips the stacked-PR gate — and is ALSO the per-layer LoC ceiling: a change that cannot fit in one layer's budget is what is worth stacking." },
   { key: "stacked_pr_files", def: 20, tier: "common", answers: [{ family: "pr", prio: "P2", mode: "replace" }], lanes: ["orc", "orc-pr-setup"], validate: vInt(1), options: [10, 15, 20, 30, 40], desc: "Changed-file count >= this trips the stacked-PR gate; also the per-layer hard max (soft target = half of it)." },
   { key: "stacked_pr_max_layers", def: 6, tier: "common", answers: [{ family: "pr", prio: "P2", mode: "replace" }], lanes: ["orc", "orc-pr-setup"], validate: vInt(2), options: [4, 5, 6, 8, 10], desc: "Soft cap on layers per stack: <= cap proceed, cap+1..cap+2 warn + explicit override, beyond → STOP (multiple stacks or a phased release). N layers = N full CI runs." },
+  // --- v1.1.0 — the usage gate and the wait ---------------------------------
+  // EVERY DEFAULT IS OFF. A fresh install behaves exactly as it did before this
+  // release: `usage_gate: off` means the automatic half does nothing at all,
+  // and `wait_default_mode: ask` means there is no stop behaviour the user did
+  // not choose. `/orc-wait` needs none of these keys to work — a typed wait is
+  // the user's decision and no config may pre-empt it.
+  { key: "usage_gate", def: "off", tier: "common", answers: [{ family: "wait", prio: "P2", mode: "replace" }], lanes: ["orc", "orc-diy", "orc-doc", "orc-fast", "orc-mini", "orc-quick", "orc-wiki"], validate: vEnum("off", "warn", "stop", "wait"), options: ["off", "warn", "stop", "wait"], desc: "What ORC does when the 5-hour or 7-day window is nearly full, checked before a wave: off = nothing (the default — ORC never stops you until you ask it to), warn = print the reading and continue, stop = write the hand-back and stop, wait = hand back, then wait out the reset in detached hops that cost zero tokens. A missing or stale reading is `unknown` and NEVER stops a run. `/orc-wait block <reason>` suppresses this for one run; a typed `/orc-wait` is never suppressed." },
+  { key: "usage_stop_pct", def: 10, tier: "common", answers: [{ family: "wait", prio: "P2", mode: "replace" }], gated_by: "usage_gate", lanes: ["orc", "orc-diy", "orc-doc", "orc-fast", "orc-mini", "orc-quick", "orc-wiki"], validate: vInt(1), options: [5, 10, 15, 20, 30], desc: "How much of a window must REMAIN for a wave to start. The WORST of the two windows decides — a 7-day window at 96% is not a green light because the 5-hour one is at 20%. Inert while usage_gate is off." },
+  { key: "wait_default_mode", def: "ask", tier: "common", answers: [{ family: "wait", prio: "P2", mode: "replace" }], lanes: ["orc", "orc-diy", "orc-doc", "orc-fast", "orc-mini", "orc-quick", "orc-wiki"], validate: vEnum("ask", "safe", "soft", "hard"), options: ["ask", "safe", "soft", "hard"], desc: "The mode a wait uses when you do not name one: ask = ONE question with the cost of each spelled out (the default — there is no stop behaviour you did not choose), safe = finish the current wave first and lose nothing, soft = stop at the next model turn but FORCE the checkpoint (and do not stop if that write fails), hard = stop at the next model turn with the hand-back only, which can lose an in-flight return. A mode named on the command line always wins." },
+  { key: "wait_hop_minutes", def: 30, tier: "advanced", answers: [{ family: "wait", prio: "P2", mode: "replace" }], lanes: [], validate: vInt(1), options: [5, 10, 15, 30], desc: "How long ONE detached hop waits before ORC re-reads the window. Short on purpose: each wake-up is session activity, and session activity is the only thing that makes the statusline write a fresh reading. One long sleep wakes into a reading as stale as the sleep was long." },
+  { key: "wait_max_hops", def: 5, tier: "advanced", answers: [{ family: "wait", prio: "P2", mode: "replace" }], lanes: [], validate: vInt(1), options: [1, 2, 3, 5, 8, 12], desc: "How many hops before ORC gives up and stops with the hand-back. A wrong reset time must cost you a bounded wait, never a session that never comes back." },
   // --- v0.50.0 — orc extra: dispatch ORC's WORKERS to non-Claude agents -----
   // Nine keys, and the count is the feature: the combinatorial part —
   // providers x models x bands — is a LEDGER with a CLI and a panel
@@ -2603,6 +2624,9 @@ const LANES = [
   { lane: "orc-retro", command: "orc-retro" },
   { lane: "orc-route", command: "orc-route" },
   { lane: "orc-verify", command: "orc-verify" },
+  // v1.1.0 W2 — command-entry only, and it opens no run of its own: it waits
+  // INSIDE whatever run is already in flight, or with none at all.
+  { lane: "orc-wait", command: "orc-wait" },
   { lane: "orc-wiki", command: "orc-wiki" },
 ];
 const LANE_NAMES = LANES.map((l) => l.lane);
@@ -2647,6 +2671,16 @@ const LANE_INERT = {
   "orc-doc": [
     { key: "opus5_only", reason: "both agents in this lane are already claude-opus-5, so this is a no-op — the lane is unaffected, not exempt" },
   ],
+  // v1.1.0 W2 — this lane DISPATCHES NOTHING. A detached command does the
+  // waiting, so every family that answers "which model runs this" has no work
+  // to name here. Reporting an executor band as live for a lane that never
+  // executes is the mirror of a shadowed setting being silent: a setting that
+  // does nothing must never be reported as live.
+  "orc-wait": [
+    { family: "executor-band", reason: "this lane dispatches nothing — a detached command does the waiting, and no model runs during it" },
+    { family: "fixed-role-model", reason: "this lane dispatches nothing — there is no role here to pin a model to" },
+    { key: "opus5_only", reason: "this lane dispatches nothing, so there is no agent for a forcing mode to replace" },
+  ],
 };
 
 // A value that can HARD-STOP a run, so a lane prints the gate without deciding
@@ -3057,6 +3091,18 @@ const LANE_CALLS = {
     never: "never merge `.claude/orc.config.yaml` yourself, and never re-derive a precedence — the answer already carries it",
     lanes: ["context-combiner", "orc", "orc-aftermath", "orc-analyze", "orc-analyze-mini", "orc-boundary", "orc-brainstorm", "orc-budget", "orc-challenge", "orc-claude", "orc-diy", "orc-doc", "orc-explain", "orc-export", "orc-fast", "orc-grill", "orc-handoff", "orc-learn", "orc-mini", "orc-pact", "orc-pattern", "orc-poly", "orc-pr-driver", "orc-pr-setup", "orc-quick", "orc-retro", "orc-route", "orc-verify", "orc-wiki"],
   },
+  "run-inflight": {
+    cmd: "orc run inflight [--json]",
+    what: "is a dispatch from this run still alive — the ONE reader of the trace's pending sidecar",
+    exits: { 0: "clear — provably nothing in flight", 1: "in-flight — at least one dispatch has not returned", 2: "unknown — cannot prove either way" },
+    states: ["clear", "in-flight", "unknown"],
+    cost: "free",
+    when: "before ANY re-dispatch, requeue or repair round, and before the first dispatch of a resumed run",
+    on_absent: "exit 2 REFUSES by default — the one place an absent reading blocks, because a wrongly-refused dispatch costs a question and a wrongly-issued one costs a second Opus agent for an hour",
+    canonical: "_shared/return-validation.md",
+    never: "never read `clear` as proof that an AD-HOC dispatch finished — the hook writes no SPAWN for one, so no record exists",
+    lanes: ["orc", "orc-doc", "orc-fast", "orc-mini", "orc-quick", "orc-wiki"],
+  },
   "lane-phases": {
     cmd: "orc lane phases <lane> [--json]",
     what: "which SHARED phases this lane runs, in order — the file, the layers to read, and when",
@@ -8972,6 +9018,149 @@ function resume() {
 }
 
 // `orc run list` / `orc run show <slug|n>`
+// ── `orc run inflight` — is a previous dispatch still alive? (v1.2.0) ───────
+//
+// WHY THIS EXISTS. Claude Code's Task tool returning an error does NOT kill the
+// subagent behind it. The agent keeps running and keeps writing files. Every
+// lane's retry rule ("a broken return = a failure, re-dispatch") silently
+// assumed the opposite, so an interrupted turn produced a SECOND agent on the
+// same task while the first was still working. A graded run put THREE
+// `orc-executor-opus-5-low` agents on one task for 50m19s + 115m22s + 100m53s
+// — 266 minutes of Opus 5 for one authorised dispatch, all editing the same
+// files. The hook already recorded every one of them; nothing ever READ it.
+//
+// The pending sidecar (`<trace>.pending.json`, written by orc-trace.js on every
+// SPAWN) is the evidence. This command makes it authoritative:
+// `a lane that re-dispatches over a live attempt` has broken the contract in
+// `_shared/return-validation.md` §0.
+//
+// UNKNOWN IS NOT ZERO. A missing pointer, an unreadable sidecar or a record too
+// old to trust all exit 2 — never 0. "I cannot prove anything is running" and
+// "I proved nothing is running" are different facts, and re-dispatching on the
+// first one is exactly the bug. Only a readable sidecar that is EMPTY *and* a
+// trace whose SPAWN/RETURN counts agree earns exit 0.
+//
+//   exit 0  clear      — provably nothing in flight
+//   exit 1  in-flight  — >=1 dispatch has not returned
+//   exit 2  unknown    — cannot prove either way
+const INFLIGHT_STALE_MS = 6 * 60 * 60 * 1000;
+
+function runInflightCmd(claudeDir) {
+  const dir = resolveLogDir(claudeDir);
+  const out = {
+    ok: true,
+    state: "unknown",
+    reason: null,
+    count: 0,
+    entries: [],
+    trace: null,
+    lane: null,
+    slug: null,
+    log_dir: dir,
+    sidecar: null,
+    sidecar_readable: false,
+    spawns: null,
+    returns: null,
+    balance_agrees: null,
+    stale_entries: 0,
+  };
+
+  const finish = (state, reason, code) => {
+    out.state = state;
+    out.reason = reason;
+    if (wantsJson()) emitJson(out);
+    else renderInflight(out);
+    process.exit(code);
+  };
+
+  // 1. The run pointer. No pointer = no open run we can reason about.
+  let cur = null;
+  try {
+    cur = fs.readFileSync(path.join(dir, ".current"), "utf8").trim();
+  } catch (_) {}
+  if (!cur) return finish("unknown", "no trace pointer — no run is open, or the pointer was never written", 2);
+  out.trace = cur;
+  const m = TRACE_NAME.exec(cur);
+  if (m) { out.lane = m[1]; out.slug = m[2]; }
+
+  // 2. The trace's own SPAWN/RETURN balance — an independent second opinion.
+  //    Counted from the hook's own skeleton lines only.
+  const tracePath = path.join(dir, cur);
+  try {
+    const text = fs.readFileSync(tracePath, "utf8");
+    out.spawns = (text.match(/\] hook\s+SPAWN /g) || []).length;
+    const all = (text.match(/\] hook\s+RETURN /g) || []).length;
+    const loose = (text.match(/\] hook\s+RETURN ~agent :: unattributed/g) || []).length;
+    out.returns = all - loose;
+  } catch (_) {
+    return finish("unknown", `trace pointer names "${cur}" but it cannot be read`, 2);
+  }
+
+  // 3. The pending sidecar — the record of what was dispatched and never closed.
+  const side = path.join(dir, cur + ".pending.json");
+  out.sidecar = side;
+  let pend = null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(side, "utf8"));
+    if (Array.isArray(raw)) { pend = raw; out.sidecar_readable = true; }
+  } catch (_) {}
+
+  const now = Date.now();
+  if (pend) {
+    out.entries = pend.map((r) => {
+      const ts = typeof r.ts === "number" ? r.ts : null;
+      const age = ts == null ? null : Math.round((now - ts) / 1000);
+      return {
+        agent: r.agent == null ? null : String(r.agent),
+        desc: r.desc == null ? null : String(r.desc),
+        started_ms: ts,
+        age_s: age,
+        stale: ts != null && now - ts > INFLIGHT_STALE_MS,
+      };
+    });
+    out.count = out.entries.length;
+    out.stale_entries = out.entries.filter((e) => e.stale).length;
+  }
+
+  const balance = out.spawns != null && out.returns != null ? out.spawns - out.returns : null;
+  out.balance_agrees = balance == null || pend == null ? null : balance === out.count;
+
+  // 4. Verdict. Conservative in every direction.
+  if (!out.sidecar_readable) {
+    if (balance != null && balance > 0)
+      return finish("in-flight", `sidecar unreadable, but the trace shows ${balance} SPAWN(s) with no RETURN`, 1);
+    return finish("unknown", "the pending sidecar is missing or unreadable — cannot prove a dispatch finished", 2);
+  }
+  if (out.count > 0) {
+    if (out.stale_entries === out.count)
+      return finish(
+        "unknown",
+        `${out.count} record(s), all older than 6h — the run probably died without closing them`,
+        2
+      );
+    return finish("in-flight", `${out.count} dispatch(es) have not returned`, 1);
+  }
+  // Sidecar empty. Only trust it when the trace agrees.
+  if (balance != null && balance > 0)
+    return finish("unknown", `sidecar is empty but the trace shows ${balance} unmatched SPAWN(s) — they disagree`, 2);
+  return finish("clear", "no dispatch is in flight", 0);
+}
+
+function renderInflight(o) {
+  const head =
+    o.state === "clear" ? "clear" : o.state === "in-flight" ? `IN FLIGHT (${o.count})` : "unknown";
+  console.log(`${ui.color.bold("dispatch:")} ${head}`);
+  console.log(`  ${o.reason}`);
+  if (o.trace) console.log(`  trace   ${o.trace}`);
+  for (const e of o.entries) {
+    const age = e.age_s == null ? "age unknown" : `${Math.floor(e.age_s / 60)}m${e.age_s % 60}s ago`;
+    console.log(`  - ${e.agent || "(unnamed)"}  ${age}${e.stale ? "  [stale]" : ""}`);
+    if (e.desc) console.log(`      ${e.desc}`);
+  }
+  if (o.state === "in-flight")
+    console.log("\n  Do NOT re-dispatch these tasks. A Task error does not kill the agent behind it.");
+}
+
 function runCmd() {
   const claudeDir = resolveClaudeDir();
   const pos = positionals(); // ["run", <sub?>, <arg?>]
@@ -8982,6 +9171,9 @@ function runCmd() {
   // on disk. Neither deletes anything.
   if (sub === "close" || sub === "reopen") return runCloseCmd(claudeDir, runs, sub, pos[2]);
 
+  // Read-only, and the ONE reader of the pending sidecar. 0 clear / 1 in-flight / 2 unknown.
+  if (sub === "inflight") return runInflightCmd(claudeDir);
+
   if (sub === "show") {
     const arg = pos[2];
     const pick = /^\d+$/.test(String(arg)) ? runs[Number(arg) - 1] : runs.find((r) => r.slug === arg);
@@ -32847,6 +33039,12 @@ Usage:
     orc run reopen <slug|n>               put it back — it is waiting again  [--json]
   orc stats [--since YYYY-MM-DD] [--json] how much you actually use each lane and agent, counted
                                           from the trace filenames — no model, instant, free
+  orc wait                                the deterministic half of /orc-wait — a wait costs zero
+                                          tokens, because a detached command does it, not a model
+    orc wait lanes [--json]               which lanes support a wait, what each one checkpoints,
+                                          and where its safe point is
+    orc wait plan <spec> [--json]         turn 30 · 90m · 2h · until 18:41 · reset into hops
+      [--hop <min>] [--max-hops <n>]      (exit 0 planned / 1 unparsable / 2 no usage reading)
   orc onboarding [<topic>]                guided walkthrough (menu on a TTY; prints all when piped)
                                           topics: overview, install, first-run, lanes,
                                           config, knowledge, upgrade, troubleshooting
@@ -32901,6 +33099,904 @@ update vs upgrade:
 Skills installed: ${listSkillNames().join(", ")}`);
 }
 
+// ── `orc wait` (v1.1.0 W1) ──────────────────────────────────────────────────
+// The deterministic half of `/orc-wait`. The skill never does this arithmetic
+// itself: a pipeline the model recomputes is a pipeline that drifts (the
+// `orc doc next` / Flow-stepper rule). Canonical prose is
+// `templates/skills/_shared/wait.md`, and WAIT_LANE_SHAPES below is the
+// machine-readable copy of its `## Which lanes support a wait` table — a golden
+// test compares the two IN BOTH DIRECTIONS, the EXTRA_LANE_SHAPES precedent.
+//
+// `checkpoint: "none"` is an ANSWER, not a gap: a single-dispatch lane has
+// nothing to checkpoint, so all three modes collapse to the same plain wait
+// there and this table says so rather than omitting the row.
+const WAIT_LANE_SHAPES = [
+  { lane: "/orc", checkpoint: "full", safe_point: "wave or phase edge" },
+  { lane: "/orc-ultra", checkpoint: "full", safe_point: "wave or judge gate" },
+  { lane: "/orc-mini", checkpoint: "full", safe_point: "after the executor returns" },
+  { lane: "/orc-fast", checkpoint: "full", safe_point: "after the executor returns" },
+  { lane: "/orc-diy", checkpoint: "full", safe_point: "compiled phase edge" },
+  { lane: "/orc-doc", checkpoint: "full", safe_point: "wave edge" },
+  { lane: "/orc-wiki", checkpoint: "full", safe_point: "scan-task boundary" },
+  { lane: "/orc-analyze", checkpoint: "full", safe_point: "after the analyst returns" },
+  { lane: "/orc-poly", checkpoint: "docset", safe_point: "after a per-repo plan is written" },
+  { lane: "/orc-quick", checkpoint: "entry", safe_point: "after an entry closes" },
+  { lane: "/orc-challenge", checkpoint: "cycle", safe_point: "after a cycle records" },
+  { lane: "/orc-brainstorm", checkpoint: "snapshot", safe_point: "phase edge" },
+  { lane: "/orc-grill", checkpoint: "snapshot", safe_point: "round edge" },
+  { lane: "/orc-learn", checkpoint: "none", safe_point: "single dispatch" },
+  { lane: "/orc-plan", checkpoint: "none", safe_point: "single dispatch" },
+  { lane: "/orc-verify", checkpoint: "none", safe_point: "single dispatch" },
+  { lane: "/orc-pattern", checkpoint: "none", safe_point: "single dispatch" },
+  { lane: "/orc-claude", checkpoint: "none", safe_point: "single dispatch" },
+  { lane: "/orc-explain", checkpoint: "none", safe_point: "read-only, seconds long" },
+  { lane: "/orc-route", checkpoint: "none", safe_point: "read-only, seconds long" },
+  { lane: "/orc-boundary", checkpoint: "none", safe_point: "read-only, seconds long" },
+  { lane: "/orc-budget", checkpoint: "none", safe_point: "read-only, seconds long" },
+  { lane: "/orc-aftermath", checkpoint: "none", safe_point: "read-only, seconds long" },
+  { lane: "/orc-export", checkpoint: "none", safe_point: "read-only, seconds long" },
+  { lane: "/orc-retro", checkpoint: "none", safe_point: "read-only, seconds long" },
+  { lane: "/orc-pact", checkpoint: "none", safe_point: "read-only, seconds long" },
+];
+const WAIT_MODES = ["safe", "soft", "hard"];
+const WAIT_CHECKPOINTS = ["full", "docset", "entry", "cycle", "snapshot", "none"];
+const WAIT_HOP_DEFAULT_MIN = 30;
+const WAIT_MAX_HOPS_DEFAULT = 5;
+// The same freshness window the effort guard already uses for the session-model
+// bridge. A reading older than this is `unknown`, and unknown never blocks.
+const WAIT_BRIDGE_MAX_AGE_MS = 30 * 60 * 1000;
+
+// The reader half of the statusline usage bridge. The WRITER lands in W4; until
+// then every caller correctly reports `unknown`, which is the honest answer and
+// never a stop. Unknown is not zero.
+function readUsageBridge(claudeDir, now) {
+  const t = typeof now === "number" ? now : Date.now();
+  const file = path.join(claudeDir, "orc", "usage.json");
+  try {
+    const j = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!j || typeof j.written_at !== "number") return null;
+    if (t - j.written_at > WAIT_BRIDGE_MAX_AGE_MS) return null;
+    return j;
+  } catch (_) {
+    return null;
+  }
+}
+
+// `30` `90m` `2h` `2h30m` `until 18:41` `reset` → minutes.
+// Returns { ok, kind, minutes, ... } or { ok:false, reason }.
+function waitParseSpec(spec, now) {
+  const t = typeof now === "number" ? now : Date.now();
+  const s = String(spec == null ? "" : spec).trim().toLowerCase().replace(/\s+/g, " ");
+  if (!s) return { ok: false, reason: "empty", hint: "say how long. Example: orc wait plan 30" };
+  if (s === "reset") return { ok: true, kind: "reset", minutes: null };
+  let m = /^until (\d{1,2}):(\d{2})$/.exec(s);
+  if (m) {
+    const hh = Number(m[1]);
+    const mm = Number(m[2]);
+    if (hh > 23 || mm > 59)
+      return { ok: false, reason: "bad-time", hint: `${m[1]}:${m[2]} is not a time of day` };
+    const d = new Date(t);
+    const target = new Date(d.getFullYear(), d.getMonth(), d.getDate(), hh, mm, 0, 0);
+    // A time already past today means the next one — never a negative wait.
+    if (target.getTime() <= t) target.setDate(target.getDate() + 1);
+    return {
+      ok: true,
+      kind: "until",
+      minutes: Math.max(1, Math.round((target.getTime() - t) / 60000)),
+      until: target.toISOString(),
+    };
+  }
+  m = /^(\d+) ?h(?: ?(\d+) ?m?)?$/.exec(s);
+  if (m) {
+    const mins = Number(m[1]) * 60 + Number(m[2] || 0);
+    return mins > 0
+      ? { ok: true, kind: "duration", minutes: mins }
+      : { ok: false, reason: "zero", hint: "a wait of zero is not a wait" };
+  }
+  m = /^(\d+) ?m$/.exec(s) || /^(\d+)$/.exec(s);
+  if (m) {
+    const mins = Number(m[1]);
+    return mins > 0
+      ? { ok: true, kind: "duration", minutes: mins }
+      : { ok: false, reason: "zero", hint: "a wait of zero is not a wait" };
+  }
+  return {
+    ok: false,
+    reason: "unparsable",
+    hint: "use 30 · 90m · 2h · 2h30m · until 18:41 · reset",
+  };
+}
+
+// The LAST hop is the remainder, never a full hop. A wait that overshoots its
+// own reset time has waited for nothing.
+function waitHops(totalMinutes, hopMinutes, maxHops) {
+  const hop = Math.max(1, Number(hopMinutes) || WAIT_HOP_DEFAULT_MIN);
+  const cap = Math.max(1, Number(maxHops) || WAIT_MAX_HOPS_DEFAULT);
+  const hops = [];
+  let left = Math.max(0, Math.round(Number(totalMinutes) || 0));
+  while (left > 0 && hops.length < cap) {
+    const h = Math.min(hop, left);
+    hops.push(h);
+    left -= h;
+  }
+  return { hops, uncovered_minutes: left, truncated: left > 0 };
+}
+
+function waitPlanCmd(claudeDir) {
+  const asJson = wantsJson();
+  const pos = positionals().slice(2);
+  const spec = pos.join(" ");
+  const now = Date.now();
+  const cfg = resolvedConfig(claudeDir);
+  const hopMin = Number(flag("--hop")) || Number(cfg.wait_hop_minutes) || WAIT_HOP_DEFAULT_MIN;
+  const maxHops = Number(flag("--max-hops")) || Number(cfg.wait_max_hops) || WAIT_MAX_HOPS_DEFAULT;
+
+  const parsed = waitParseSpec(spec, now);
+  if (!parsed.ok) {
+    if (asJson) emitJson({ ok: false, reason: parsed.reason, spec, hint: parsed.hint }, 1);
+    console.error(ui.mark.err(`I cannot read "${spec}" as a wait.`));
+    console.error("  " + parsed.hint);
+    process.exit(1);
+  }
+
+  let minutes = parsed.minutes;
+  let source = parsed.kind;
+  let reading = null;
+  if (parsed.kind === "reset") {
+    reading = readUsageBridge(claudeDir, now);
+    const resets = reading && reading.five_hour && reading.five_hour.resets_at;
+    const at = resets == null ? NaN : Number(resets) < 1e12 ? Number(resets) * 1000 : Number(resets);
+    if (!Number.isFinite(at) || at <= now) {
+      const why = reading
+        ? "the reading has no usable reset time"
+        : "there is no reading in the last 30 minutes";
+      if (asJson)
+        emitJson(
+          { ok: false, reason: "no-reading", spec, hint: `${why}. Type a time instead. Example: orc wait plan 45` },
+          2
+        );
+      console.error(ui.mark.err("I cannot read the reset time."));
+      console.error("  " + why + ".");
+      console.error("  Type a time instead. Example: " + ui.color.cyan("orc wait plan 45"));
+      process.exit(2);
+    }
+    minutes = Math.max(1, Math.round((at - now) / 60000));
+    source = "reset";
+  }
+
+  const h = waitHops(minutes, hopMin, maxHops);
+  const endsAt = new Date(now + minutes * 60000);
+  const out = {
+    ok: true,
+    spec,
+    source,
+    minutes,
+    hop_minutes: hopMin,
+    max_hops: maxHops,
+    hops: h.hops,
+    hop_count: h.hops.length,
+    uncovered_minutes: h.uncovered_minutes,
+    truncated: h.truncated,
+    ends_at: endsAt.toISOString(),
+    // A wait longer than the prompt cache TTL re-reads the whole context on the
+    // next turn, at full input price. The caller must be able to say so.
+    crosses_cache_ttl: minutes > 60,
+    modes: WAIT_MODES,
+    note: "A detached command does the waiting. No model runs, and no tokens are spent.",
+  };
+  if (asJson) emitJson(out, 0);
+
+  console.log(ui.header("ORC · wait — the plan"));
+  console.log("");
+  console.log(`  ${ui.color.cyan("length")}    ${minutes} min  (from ${source})`);
+  console.log(`  ${ui.color.cyan("ends at")}   ${endsAt.toTimeString().slice(0, 5)}`);
+  console.log(`  ${ui.color.cyan("hops")}      ${h.hops.join(" + ")}  (${h.hops.length} of ${maxHops} max)`);
+  if (h.truncated)
+    console.log(
+      ui.mark.warn(`  ${h.uncovered_minutes} min are NOT covered — wait_max_hops is ${maxHops}.`)
+    );
+  if (out.crosses_cache_ttl)
+    console.log(
+      ui.color.gray(
+        "  Longer than one hour: the prompt cache expires, so the next turn re-reads\n" +
+          "  your whole context at full input price. A fresh session is cheaper."
+      )
+    );
+  console.log(ui.color.gray("\n  " + out.note + "\n"));
+}
+
+function waitLanesCmd() {
+  const asJson = wantsJson();
+  const lanes = WAIT_LANE_SHAPES.map((row) => {
+    const plain = row.checkpoint === "none";
+    return {
+      lane: row.lane,
+      checkpoint: row.checkpoint,
+      safe_point: row.safe_point,
+      // On a lane with nothing to checkpoint the three modes ARE the same
+      // thing. Saying so is the point; pretending to a distinction is not.
+      modes: WAIT_MODES,
+      modes_differ: !plain,
+      detail: plain
+        ? "nothing to checkpoint — one dispatch, or a read. safe, soft and hard behave identically here."
+        : `soft forces the ${row.checkpoint} checkpoint before it stops; hard writes RESUME.md only and can lose an in-flight return.`,
+    };
+  });
+  if (asJson)
+    emitJson(
+      {
+        ok: true,
+        modes: WAIT_MODES,
+        checkpoints: WAIT_CHECKPOINTS,
+        lanes,
+        note: "A lane not in this list does not support a wait.",
+      },
+      0
+    );
+
+  console.log(ui.header("ORC · wait — which lanes support a wait, and what they save"));
+  console.log("");
+  for (const l of lanes) {
+    // Pad the PLAIN text, then colour it — an ANSI escape has width 0 on screen
+    // and width 5+ to padEnd, so colouring first mis-aligns every row.
+    const cp = l.checkpoint.padEnd(9);
+    const mark = l.modes_differ ? ui.color.cyan(cp) : ui.color.gray(cp);
+    console.log(`  ${ui.color.cyan(l.lane.padEnd(17))} ${mark}  ${l.safe_point}`);
+    console.log("      " + ui.color.gray(l.detail));
+  }
+  console.log(ui.color.gray("\n  A lane not listed here does not support a wait.\n"));
+}
+
+// ── `orc usage check` (v1.1.0 W4) ───────────────────────────────────────────
+// THE one reader of the statusline's usage bridge. No skill reads that file, so
+// the threshold and the freshness rule exist in exactly one place.
+//
+// Exit codes are the contract, and the third one carries the whole design:
+//   0 ok       — enough quota. Continue.
+//   1 low      — at or below usage_stop_pct on the WORST window.
+//   2 unknown  — no reading, or one older than the freshness window.
+//
+// UNKNOWN IS NOT LOW, and it never stops a run. An absent number is an absent
+// number: older Claude Code, no headers, or simply no statusline render since
+// the last dispatch. A gate that blocks on a missing reading is a gate people
+// switch off.
+function usageResetMs(v) {
+  if (v == null) return NaN;
+  const n = Number(v);
+  if (Number.isFinite(n)) return n < 1e12 ? n * 1000 : n;
+  const p = Date.parse(String(v));
+  return Number.isFinite(p) ? p : NaN;
+}
+
+// ── `orc usage report` — where the window went (v1.2.0) ─────────────────────
+//
+// `orc usage check` answers "is there room". This answers the question a user
+// actually asks mid-run: "how much has THIS session eaten, and what ate it".
+//
+// THE HONEST PART, and it decides the whole shape of this command. Claude Code
+// records NO token usage for a dispatched subagent — `isSidechain` is never set
+// and no sidechain message carries a usage block, in any transcript on disk. So
+// a per-executor TOKEN figure cannot be measured, and inventing one would be
+// the same class of bug as a fake validator. What IS measured, exactly, is WALL
+// TIME, from the trace hook's own SPAWN/RETURN lines. Foreign workers are the
+// one exception: `orc extra` records real four-kind vectors, so those rows
+// carry tokens and say so. Every other row reports `tokens: null` plus the
+// reason — never 0. Unknown is not zero.
+const USAGE_TOP_N = 5;
+
+// "12m43s" | "1m7s" | "45s" → seconds. Anything else → null, never 0.
+function usageDurSeconds(s) {
+  if (!s) return null;
+  const m = /^(?:(\d+)m)?(\d+)s$/.exec(String(s).trim());
+  if (!m) return null;
+  return (m[1] ? Number(m[1]) * 60 : 0) + Number(m[2]);
+}
+
+// Per-agent wall time for the run the trace pointer names. Returns null when
+// there is no open run — an absent trace is an absent measurement, not zero.
+function usageRunConsumers(claudeDir) {
+  const dir = resolveLogDir(claudeDir);
+  let cur = null;
+  try {
+    cur = fs.readFileSync(path.join(dir, ".current"), "utf8").trim();
+  } catch (_) {}
+  if (!cur) return null;
+  let text = "";
+  try {
+    text = fs.readFileSync(path.join(dir, cur), "utf8");
+  } catch (_) {
+    return null;
+  }
+  const nameMatch = TRACE_NAME.exec(cur);
+  const by = new Map();
+  const bump = (agent, secs, running) => {
+    const k = agent || "(unnamed)";
+    const r = by.get(k) || { agent: k, dispatches: 0, wall_seconds: 0, running: 0, unmeasured: 0 };
+    r.dispatches += 1;
+    if (running) r.running += 1;
+    if (secs == null) r.unmeasured += 1;
+    else r.wall_seconds += secs;
+    by.set(k, r);
+  };
+  for (const line of text.split("\n")) {
+    // Only the hook's own skeleton lines. `~agent :: unattributed` is a
+    // bookkeeping artefact of >=2 in flight and is never a dispatch.
+    const r = /\] hook\s+RETURN ~?([^\s:]+) :: /.exec(line);
+    if (!r) continue;
+    if (r[1] === "agent") continue;
+    const d = /\bdur=(\S+)/.exec(line);
+    bump(r[1], usageDurSeconds(d && d[1]), false);
+  }
+  // Anything still open is real spend happening RIGHT NOW — the exact case the
+  // v1.2.0 in-flight guard exists for, and the one a user most wants to see.
+  let pending = [];
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(dir, cur + ".pending.json"), "utf8"));
+    if (Array.isArray(raw)) pending = raw;
+  } catch (_) {}
+  const now = Date.now();
+  for (const p of pending) {
+    const secs = typeof p.ts === "number" ? Math.round((now - p.ts) / 1000) : null;
+    bump(p.agent, secs, true);
+  }
+  return {
+    trace: cur,
+    lane: nameMatch ? nameMatch[1] : null,
+    slug: nameMatch ? nameMatch[2] : null,
+    agents: [...by.values()],
+    in_flight: pending.length,
+  };
+}
+
+// Foreign dispatches DO carry measured tokens. Same file the spend report reads.
+function usageForeignSpend(claudeDir) {
+  const f = path.join(claudeDir, "orc", "extra-spend.jsonl");
+  let lines = [];
+  try {
+    lines = fs.readFileSync(f, "utf8").split("\n").filter(Boolean);
+  } catch (_) {
+    return { rows: [], unreadable: 0 };
+  }
+  const rows = [];
+  let unreadable = 0;
+  for (const l of lines) {
+    try {
+      rows.push(JSON.parse(l));
+    } catch (_) {
+      unreadable += 1;
+    }
+  }
+  return { rows, unreadable };
+}
+
+function usageReportCmd(claudeDir) {
+  const asJson = wantsJson();
+  const now = Date.now();
+  const cfg = resolvedConfig(claudeDir);
+  const stopPct = Math.min(50, Math.max(1, Number(cfg.usage_stop_pct) || 10));
+
+  // Read the bridge RAW here rather than through readUsageBridge: a stale
+  // reading is still worth SHOWING, with its age, where a gate would rightly
+  // discard it. The state word still comes from freshness — age is displayed,
+  // never ignored.
+  let raw = null;
+  try {
+    raw = JSON.parse(fs.readFileSync(path.join(claudeDir, "orc", "usage.json"), "utf8"));
+  } catch (_) {}
+  const ageMin =
+    raw && typeof raw.written_at === "number" ? Math.round((now - raw.written_at) / 60000) : null;
+  const stale = ageMin == null ? true : now - raw.written_at > WAIT_BRIDGE_MAX_AGE_MS;
+
+  const view = (o, label) => {
+    if (!o || typeof o.used_percentage !== "number") return null;
+    const used = Math.round(o.used_percentage);
+    const at = usageResetMs(o.resets_at);
+    return {
+      window: label,
+      used_percentage: used,
+      remaining_percentage: Math.max(0, 100 - used),
+      resets_at: Number.isFinite(at) ? new Date(at).toISOString() : null,
+      resets_in_minutes: Number.isFinite(at) && at > now ? Math.round((at - now) / 60000) : null,
+      low: 100 - used <= stopPct,
+    };
+  };
+  const fh = raw ? view(raw.five_hour, "5h") : null;
+  const sd = raw ? view(raw.seven_day, "wk") : null;
+
+  // Session consumption — the ledger the statusline keeps.
+  let led = null;
+  try {
+    led = JSON.parse(fs.readFileSync(path.join(claudeDir, "orc", "usage-session.json"), "utf8"));
+  } catch (_) {}
+  const consumed = (w) =>
+    !w
+      ? null
+      : {
+          baseline_percentage: w.baseline,
+          now_percentage: w.last,
+          consumed_percentage: Math.max(0, w.accumulated + Math.max(0, w.last - w.baseline)),
+          window_resets: w.resets,
+        };
+  const session = !led
+    ? null
+    : {
+        session_id: led.session_id || null,
+        started_at: led.started_at ? new Date(led.started_at).toISOString() : null,
+        running_minutes: led.started_at ? Math.round((now - led.started_at) / 60000) : null,
+        five_hour: consumed(led.five_hour),
+        seven_day: consumed(led.seven_day),
+        still_counting: true,
+        // Never overclaim. The window is per ACCOUNT: a second Claude Code
+        // window, a cloud session, or anyone else on the same key moves it too.
+        caveat:
+          "this is how far the window moved while this session ran — other sessions on the same account share it",
+      };
+
+  const run = usageRunConsumers(claudeDir);
+  const foreign = usageForeignSpend(claudeDir);
+
+  // Rank by measured wall time. A row with nothing measured keeps its slot.
+  const top = [];
+  if (run) {
+    const sorted = run.agents.slice().sort((a, b) => b.wall_seconds - a.wall_seconds);
+    for (const a of sorted.slice(0, USAGE_TOP_N))
+      top.push({
+        agent: a.agent,
+        dispatches: a.dispatches,
+        running: a.running,
+        wall_seconds: a.wall_seconds,
+        unmeasured_dispatches: a.unmeasured,
+        tokens: null,
+        tokens_source: "unavailable",
+      });
+  }
+  for (const r of foreign.rows.slice(-USAGE_TOP_N)) {
+    top.push({
+      agent: "extra:" + (r.profile || "?") + "/" + (r.model || "?"),
+      dispatches: 1,
+      running: 0,
+      wall_seconds: usageDurSeconds(r.dur),
+      unmeasured_dispatches: 0,
+      tokens: r.usage || null,
+      tokens_source: r.usage ? "measured" : "not reported by the worker",
+    });
+  }
+
+  const windows = [fh, sd].filter(Boolean);
+  const state = !windows.length || stale ? "unknown" : windows.some((w) => w.low) ? "low" : "ok";
+  const code = state === "low" ? 1 : state === "unknown" ? 2 : 0;
+  const out = {
+    ok: true,
+    state,
+    five_hour: fh,
+    seven_day: sd,
+    context_used_percentage:
+      raw && typeof raw.context_used_percentage === "number" ? raw.context_used_percentage : null,
+    reading_age_minutes: ageMin,
+    reading_stale: stale,
+    stop_pct: stopPct,
+    gate: String(cfg.usage_gate || "off"),
+    session,
+    run: run
+      ? {
+          trace: run.trace,
+          lane: run.lane,
+          slug: run.slug,
+          dispatches: run.agents.reduce((n, a) => n + a.dispatches, 0),
+          in_flight: run.in_flight,
+          wall_seconds: run.agents.reduce((n, a) => n + a.wall_seconds, 0),
+        }
+      : null,
+    top,
+    foreign_spend_rows: foreign.rows.length,
+    unreadable_spend_lines: foreign.unreadable,
+    // Say it on every emission. A reader who does not know this reads a
+    // wall-time ranking as a token ranking.
+    tokens_note:
+      "Claude Code records no token usage for a dispatched subagent, so a Claude agent's tokens are null and never 0. Rows are ranked by MEASURED WALL TIME. Only `orc extra` foreign workers report real token vectors.",
+  };
+  if (asJson) emitJson(out, code);
+
+  console.log(ui.header("ORC · usage"));
+  console.log("");
+  const pctLine = (w) =>
+    !w
+      ? ui.color.gray("      —  (no reading)")
+      : "      " +
+        String(w.used_percentage).padStart(3) +
+        "% used · " +
+        w.remaining_percentage +
+        "% left" +
+        (w.resets_in_minutes != null ? " · resets in " + w.resets_in_minutes + "m" : "") +
+        (w.low ? "  " + ui.color.yellow("LOW") : "");
+  console.log("  5 hours");
+  console.log(pctLine(fh));
+  console.log("  7 days");
+  console.log(pctLine(sd));
+  if (out.context_used_percentage != null)
+    console.log("  context   " + out.context_used_percentage + "% of the window");
+  if (stale)
+    console.log(
+      ui.color.gray(
+        "  reading   " +
+          (ageMin == null ? "none" : ageMin + "m old") +
+          " — treated as unknown, and a run is never stopped on it"
+      )
+    );
+  console.log("");
+  if (session && session.five_hour) {
+    const c = session.five_hour;
+    console.log(
+      "  " +
+        ui.color.bold(
+          "This session has consumed " +
+            c.consumed_percentage +
+            "% of the 5-hour window and is still counting"
+        )
+    );
+    console.log(
+      ui.color.gray(
+        "      " +
+          c.baseline_percentage +
+          "% → " +
+          c.now_percentage +
+          "%" +
+          (c.window_resets ? " across " + c.window_resets + " window reset(s)" : "") +
+          (session.running_minutes != null ? " · " + session.running_minutes + "m in session" : "")
+      )
+    );
+    console.log(ui.color.gray("      " + session.caveat));
+  } else {
+    console.log(ui.color.gray("  session consumption: no reading yet (the statusline writes it)"));
+  }
+  console.log("");
+  if (top.length) {
+    console.log("  " + ui.color.bold("Top " + USAGE_TOP_N + " by measured wall time"));
+    for (const t of top.slice(0, USAGE_TOP_N)) {
+      const secs = t.wall_seconds;
+      const w =
+        secs == null
+          ? "—"
+          : Math.floor(secs / 60) + "m" + String(secs % 60).padStart(2, "0") + "s";
+      const tok = t.tokens ? "tokens measured" : ui.color.gray("tokens —");
+      console.log(
+        "      " +
+          w.padStart(8) +
+          "  " +
+          t.agent +
+          "  " +
+          ui.color.gray("x" + t.dispatches) +
+          (t.running ? "  " + ui.color.yellow(t.running + " RUNNING") : "") +
+          "  " +
+          tok
+      );
+    }
+    console.log(
+      ui.color.gray("      wall time, not tokens — Claude Code does not record a subagent's tokens")
+    );
+  } else {
+    console.log(ui.color.gray("  no dispatches in the open run (or no run is open)"));
+  }
+  process.exit(code);
+}
+
+function usageCheckCmd(claudeDir) {
+  const asJson = wantsJson();
+  const now = Date.now();
+  const cfg = resolvedConfig(claudeDir);
+  const stopPct = Math.min(50, Math.max(1, Number(cfg.usage_stop_pct) || 10));
+  const gate = String(cfg.usage_gate || "off");
+  const j = readUsageBridge(claudeDir, now);
+
+  const view = (o, label) => {
+    if (!o || typeof o.used_percentage !== "number") return null;
+    const used = Math.round(o.used_percentage);
+    const at = usageResetMs(o.resets_at);
+    const mins = Number.isFinite(at) && at > now ? Math.round((at - now) / 60000) : null;
+    return {
+      window: label,
+      used_percentage: used,
+      remaining_percentage: Math.max(0, 100 - used),
+      resets_at: Number.isFinite(at) ? new Date(at).toISOString() : null,
+      resets_in_minutes: mins,
+      low: 100 - used <= stopPct,
+    };
+  };
+
+  if (!j) {
+    const out = {
+      ok: true,
+      state: "unknown",
+      reason: "no reading in the last 30 minutes",
+      five_hour: null,
+      seven_day: null,
+      context: null,
+      stop_pct: stopPct,
+      gate,
+      // Say what unknown MEANS, every time. Silence here is what makes a user
+      // believe the gate is watching when it is not.
+      note: "unknown is not low — a run is never stopped on a missing reading. Claude Code before v2.1.80 sends no usage headers.",
+    };
+    if (asJson) emitJson(out, 2);
+    console.log(ui.color.gray("usage: unknown (no reading in the last 30 minutes) · a run is never stopped on this"));
+    process.exit(2);
+  }
+
+  const fh = view(j.five_hour, "5h");
+  const sd = view(j.seven_day, "wk");
+  const windows = [fh, sd].filter(Boolean);
+  if (!windows.length) {
+    const out = { ok: true, state: "unknown", reason: "the reading carries no window", stop_pct: stopPct, gate };
+    if (asJson) emitJson(out, 2);
+    console.log(ui.color.gray("usage: unknown (the reading carries no window)"));
+    process.exit(2);
+  }
+
+  // THE WORST WINDOW DECIDES. A 7-day window at 96% with a 5-hour window at 20%
+  // is not a green light: the run continues and dies twenty minutes later.
+  const worst = windows.reduce((a, b) => (a.remaining_percentage <= b.remaining_percentage ? a : b));
+  const low = windows.some((w) => w.low);
+  const out = {
+    ok: true,
+    state: low ? "low" : "ok",
+    five_hour: fh,
+    seven_day: sd,
+    worst: worst.window,
+    context: typeof j.context_used_percentage === "number" ? j.context_used_percentage : null,
+    stop_pct: stopPct,
+    gate,
+    reading_age_minutes: Math.round((now - j.written_at) / 60000),
+    note: "read BEFORE a wave; the wave then spends tokens, so this is a reading and not a promise.",
+  };
+  if (asJson) emitJson(out, low ? 1 : 0);
+
+  const fmt = (w) =>
+    w ? `${w.window} ${w.used_percentage}%${w.resets_in_minutes != null ? ` (${w.resets_in_minutes}m)` : ""}` : null;
+  const line = [fmt(fh), fmt(sd)].filter(Boolean).join(" · ");
+  console.log((low ? ui.mark.warn("usage: " + line) : ui.color.gray("usage: " + line)) +
+    ui.color.gray(` · gate at ${stopPct}% left · ${gate}`));
+  process.exit(low ? 1 : 0);
+}
+
+// ── the wait's run state (v1.1.0 W2) ────────────────────────────────────────
+// ONE file, ONE writer — this CLI. The skill never writes it, so it can never
+// be behind the disk: the v0.49.5 hand-back lesson, and the fifth time this
+// repo has applied it (v0.32.0 narration · v0.53.2 spend log · v0.54.0 journal
+// · v1.0.0 W5 demotion).
+//
+// It lives BESIDE RESUME.md in {run_dir}/{slug}/, so it is deleted with the run
+// and can never outlive the decision it records.
+const WAIT_STATE_FILE = "wait.json";
+
+function waitStatePath(claudeDir, slug) {
+  return path.join(resolveRunDir(claudeDir), slug, WAIT_STATE_FILE);
+}
+
+function readWaitState(claudeDir, slug) {
+  try {
+    const j = JSON.parse(fs.readFileSync(waitStatePath(claudeDir, slug), "utf8"));
+    return j && typeof j === "object" ? j : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeWaitState(claudeDir, slug, patch) {
+  const file = waitStatePath(claudeDir, slug);
+  const cur = readWaitState(claudeDir, slug) || { v: 1, slug };
+  const next = { ...cur, ...patch, v: 1, slug };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return next;
+}
+
+// The run this command is about. An explicit slug always wins; otherwise the
+// trace pointer names the run in flight. NEVER guess from "the newest folder" —
+// a wrong run is worse than no run, because the block would silently protect
+// something the user is not looking at.
+function waitResolveRun(claudeDir, slug) {
+  if (slug) {
+    const dir = path.join(resolveRunDir(claudeDir), slug);
+    return fs.existsSync(dir) ? { slug, dir } : null;
+  }
+  const cur = extraCurrentRun(claudeDir);
+  if (!cur || !cur.slug) return null;
+  const dir = path.join(resolveRunDir(claudeDir), cur.slug);
+  return fs.existsSync(dir) ? { slug: cur.slug, dir } : null;
+}
+
+// CLI-COMPOSED AND CLI-WRITTEN. A wait that leaves no line cannot be counted,
+// and a block that leaves no line hides that a run continued through a gate on
+// the user's authority. Best effort ALWAYS: a trace that cannot be written must
+// never take the command down with it.
+function waitTraceLine(claudeDir, verb, tail) {
+  try {
+    const cur = extraCurrentRun(claudeDir);
+    if (!cur || !cur.trace) return null;
+    const dir = resolveLogDir(claudeDir);
+    const d = new Date();
+    const p = (n, w) => String(n).padStart(w || 2, "0");
+    const stamp =
+      `${p(d.getDate())}${p(d.getMonth() + 1)}${p(d.getFullYear() % 100)} ` +
+      `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`;
+    const line = `[${stamp}] ${"cli".padEnd(8)} ${verb}${tail ? ` :: ${tail}` : ""}\n`;
+    fs.appendFileSync(path.join(dir, cur.trace), line);
+    return line.trimEnd();
+  } catch (_) {
+    return null;
+  }
+}
+
+function waitBlockCmd(claudeDir, unblock) {
+  const asJson = wantsJson();
+  const slug = positionals()[2];
+  const reason = typeof flag("--reason") === "string" ? String(flag("--reason")).trim() : "";
+  const run = waitResolveRun(claudeDir, slug);
+
+  if (!run) {
+    const hint = slug
+      ? `no run named "${slug}" under ${resolveRunDir(claudeDir)}`
+      : "no run is in flight, and no slug was given";
+    if (asJson) emitJson({ ok: false, reason: "no-run", slug: slug || null, hint }, 2);
+    console.error(ui.mark.err("I cannot find the run this is about."));
+    console.error("  " + hint + ".");
+    process.exit(2);
+  }
+
+  if (unblock) {
+    const cur = readWaitState(claudeDir, run.slug);
+    if (!cur || !cur.blocked_at) {
+      if (asJson) emitJson({ ok: false, reason: "not-blocked", slug: run.slug }, 1);
+      console.error(ui.mark.warn(`${run.slug} is not blocked.`));
+      process.exit(1);
+    }
+    const st = writeWaitState(claudeDir, run.slug, {
+      blocked_at: null,
+      block_reason: null,
+      unblocked_at: new Date().toISOString(),
+    });
+    const trace = waitTraceLine(claudeDir, "WAIT", "unblock");
+    if (asJson) emitJson({ ok: true, slug: run.slug, blocked: false, trace_line: trace }, 0);
+    console.log(ui.mark.ok(`${run.slug}: the gate is live again.`));
+    return;
+  }
+
+  // THE REASON IS REQUIRED. A recorded reason is what makes the risk
+  // demonstrably the user's — the same rule the run-close and doc-ship writers
+  // already follow. Refuse BY NAME rather than storing an empty string.
+  if (!reason) {
+    if (asJson)
+      emitJson(
+        {
+          ok: false,
+          reason: "no-reason",
+          slug: run.slug,
+          hint: 'a block records why you accepted the risk. Pass --reason "<why>".',
+        },
+        1
+      );
+    console.error(ui.mark.err("A block needs a reason."));
+    console.error('  orc wait block ' + run.slug + ' --reason "window resets in 5m, task needs 10"');
+    process.exit(1);
+  }
+
+  const st = writeWaitState(claudeDir, run.slug, {
+    blocked_at: new Date().toISOString(),
+    block_reason: reason,
+    unblocked_at: null,
+  });
+  const trace = waitTraceLine(claudeDir, "WAIT", `block reason="${reason}" by=user`);
+  if (asJson)
+    emitJson(
+      { ok: true, slug: run.slug, blocked: true, blocked_at: st.blocked_at, reason, trace_line: trace },
+      0
+    );
+  console.log(ui.mark.warn(`${run.slug}: computed waits are blocked for the rest of this run.`));
+  console.log("  reason  " + reason);
+  console.log(
+    ui.color.gray(
+      "  The risk is yours: if the window empties mid-wave, the wave stops in the\n" +
+        "  middle. A typed `/orc-wait` still waits. `orc wait unblock` restores the gate."
+    )
+  );
+}
+
+function waitCancelCmd(claudeDir) {
+  const asJson = wantsJson();
+  const run = waitResolveRun(claudeDir, positionals()[2]);
+  if (!run) {
+    if (asJson) emitJson({ ok: false, reason: "no-run", hint: "no run is in flight" }, 1);
+    console.error(ui.mark.warn("No run is in flight, so there is no wait to cancel."));
+    process.exit(1);
+  }
+  const cur = readWaitState(claudeDir, run.slug);
+  if (!cur || !cur.wait_started_at || cur.wait_ended_at) {
+    if (asJson) emitJson({ ok: false, reason: "no-wait", slug: run.slug }, 1);
+    console.error(ui.mark.warn(`${run.slug} has no wait running.`));
+    process.exit(1);
+  }
+  writeWaitState(claudeDir, run.slug, { cancel_requested_at: new Date().toISOString() });
+  if (asJson) emitJson({ ok: true, slug: run.slug, cancelled: true }, 0);
+  console.log(ui.mark.ok(`${run.slug}: the wait stops at the next hop.`));
+  console.log(ui.color.gray("  The hand-back is already on disk, so nothing is lost either way."));
+}
+
+function waitStatusCmd(claudeDir) {
+  const asJson = wantsJson();
+  const run = waitResolveRun(claudeDir, positionals()[2]);
+  if (!run) {
+    // An empty result is an ANSWER, so it still returns its object.
+    if (asJson)
+      emitJson({ ok: true, run: null, waiting: false, blocked: false, note: "no run is in flight" }, 1);
+    console.log(ui.color.gray("No run is in flight."));
+    process.exit(1);
+  }
+  const st = readWaitState(claudeDir, run.slug) || {};
+  const blocked = !!st.blocked_at;
+  const waiting = !!st.wait_started_at && !st.wait_ended_at;
+  const ageMin = blocked ? Math.round((Date.now() - Date.parse(st.blocked_at)) / 60000) : null;
+  const out = {
+    ok: true,
+    run: run.slug,
+    waiting,
+    mode: st.mode || null,
+    hop: st.hop || null,
+    hops_done: st.hops_done || 0,
+    hops_planned: st.hops_planned || null,
+    ends_at: st.ends_at || null,
+    cancel_requested: !!st.cancel_requested_at,
+    blocked,
+    block_reason: blocked ? st.block_reason : null,
+    blocked_at: st.blocked_at || null,
+    // The AGE is what keeps an old block from applying invisibly — there is no
+    // auto-expiry, because ORC does not decide a user's reason stopped being true.
+    block_age_minutes: ageMin,
+  };
+  if (asJson) emitJson(out, 0);
+
+  console.log(ui.header("ORC · wait — " + run.slug));
+  console.log("");
+  console.log(
+    `  ${ui.color.cyan("wait")}      ` +
+      (waiting
+        ? `${st.mode || "?"} · hop ${out.hops_done} of ${out.hops_planned || "?"} · ends ${out.ends_at || "?"}`
+        : ui.color.gray("none"))
+  );
+  console.log(
+    `  ${ui.color.cyan("block")}     ` +
+      (blocked ? ui.mark.warn(`${ageMin}m ago — "${st.block_reason}"`) : ui.color.gray("not blocked"))
+  );
+  if (out.cancel_requested) console.log(ui.color.gray("  a cancel is pending — the wait ends at the next hop"));
+  console.log("");
+}
+
+function waitCmd() {
+  const claudeDir = resolveClaudeDir();
+  const sub = positionals()[1];
+  switch (sub) {
+    case "lanes":
+      return waitLanesCmd();
+    case "plan":
+      return waitPlanCmd(claudeDir);
+    case "status":
+      return waitStatusCmd(claudeDir);
+    case "block":
+      return waitBlockCmd(claudeDir, false);
+    case "unblock":
+      return waitBlockCmd(claudeDir, true);
+    case "cancel":
+      return waitCancelCmd(claudeDir);
+    default:
+      console.error(`usage: orc wait lanes [--json]
+       orc wait plan <30|90m|2h|until 18:41|reset> [--hop <min>] [--max-hops <n>] [--json]
+       orc wait status [<slug>] [--json]
+       orc wait block <slug> --reason "<why>" [--json]
+       orc wait unblock [<slug>] [--json]
+       orc wait cancel [<slug>] [--json]`);
+      process.exit(1);
+  }
+}
+
 // ── the `--json` crash envelope (v0.49.2) ───────────────────────────────────
 // A read asked for JSON must answer in JSON or not at all. Before this, an
 // unexpected throw inside any `--json` route printed a Node stack to stderr and
@@ -33007,6 +34103,20 @@ function jsonCrash(err) {
     case "extra":
       await extra();
       break;
+    // v1.1.0 W1 — the deterministic half of `/orc-wait`. The skill asks; it
+    // never computes hops or the lane table itself.
+    case "wait":
+      waitCmd();
+      break;
+    // v1.1.0 W4 — the ONE reader of the statusline's usage bridge.
+    case "usage":
+      if (positionals()[1] === "check") usageCheckCmd(resolveClaudeDir());
+      else if (positionals()[1] === "report") usageReportCmd(resolveClaudeDir());
+      else {
+        console.error("usage: orc usage check|report [--json]");
+        process.exit(1);
+      }
+      break;
     case "ui":
       uiCmd();
       break;