@azure-id/orc 1.0.0 → 1.2.0

package/templates/skills/_shared/return-validation.md

@@ -1,145 +1,222 @@
-# Return validation (every lane, every subagent return)
-
-Canonical procedure for validating a spawned agent's return. Every ORC lane
-(full, mini, fast, wiki, diy) runs this on EVERY return; a malformed return is
-a failure (requeue/re-dispatch with reason — lane sets the retry cap).
-
-## 1. Contract shape
-
-The return must carry every field its agent contract names. Missing or extra
-shape = malformed. Never repair a return yourself; re-dispatch.
-
-## 2. Claimed-vs-actual model (tier-downgrade check)
-
-Every return carries:
-
-- `actual_model` — quoted VERBATIM from the agent's system-prompt model-id
-  line, never inferred (`unknown` when no such line exists)
-- `actual_effort` — the agent's `$CLAUDE_EFFORT` value
-
-Compare both against what the dispatch expected (the agent NAME encodes it).
-Append the `VERIFY` trace line with the comparison; any mismatch is surfaced
-to the user as a ⛔ DOWNGRADE — never silently accepted. (A subagent can't
-exceed the MAIN session's tier, so a downgrade usually means the main session
-is on the wrong model.)
-
-## 2b. A FOREIGN return — the SUBSTITUTION check (v0.50.0)
-
-A foreign worker (`orc extra dispatch`, `_shared/extra-dispatch.md`) is not a
-Claude subagent. It has no injected system-prompt model-id line, so **it cannot
-carry `actual_model`** — and §2 must not be faked for it. A foreign return that
-claimed an `actual_model` would be claiming evidence that does not exist.
-
-It carries instead, and every one of these is quoted from the wire rather than
-assumed:
-
-- `engine` (`api` | `claude-shim` | `cli`), `provider`, `profile`
-- `model_requested` — what the route row asked for
-- **`model_reported`** — the `model` field the endpoint echoed back
-- `usage` — the four token kinds, never blended, **or `null`**
-
-**`model_reported != model_requested` is ⛔ SUBSTITUTION**, surfaced to the user
-exactly as ⛔ DOWNGRADE is today and never silently accepted. It is the only
-defence against an aggregator quietly serving something else. `unknown` is a
-valid, honest value and is reported as `unknown` — **never as a match**.
-
-**A clean model check is not a clean answer.** An aggregator's *provider-level*
-fallback is on by default and it PRESERVES the model id, so the substitution
-check reads clean while the code went to a different company. Engine `api`
-records the response's `provider` echo and reports **⚠ REROUTE**; the other two
-engines cannot see it at all, and their `served_by_note` says so. An absent
-measurement is never a pass.
-
-**`usage: null` is not four zeros.** A worker that reported no token counts
-(engine `cli` frequently) returns `null` plus a note. `{0,0,0,0}` would tell
-`/orc-budget` the run was free. Engine `api`'s `cache_write: 0` is the opposite
-case — a real measurement — so the two must never be normalised together.
-
-**The fence is per-engine, and the return says which one it had.** Engine `api`
-ENFORCES `declared_files`; engines `claude-shim` and `cli` ASK. A return
-carrying `fence: {declared_files: false}` means the list was an instruction, not
-a rule — treat §6 below as the only real check, and say so to the user rather
-than reporting a constraint that was never applied.
-
-**A RESUMED foreign dispatch owes three more fields** (v0.54.0). The dispatch
-return sets `resume_expected: true`, so the obligation is never inferred:
-
-- **`resume_state`** — `continued` · `restarted` · `no-op`. Absent on a slice
-  with no `resumed_from` is correct; **absent on a resume slice is MALFORMED.**
-  A return claiming `restarted` while `preexisting[]` was non-empty is a
-  FINDING, not a failure — it is how `/orc-retro` learns which providers ignore
-  a resume preamble, so surface it rather than treating it as a bad return.
-- **`preexisting_read[]`** — which pre-existing files the worker actually
-  opened. Quoted like `wiki_used`: **what it did, never what the dispatcher
-  assumed.** An EMPTY list on a resume whose `preexisting[]` was not empty is an
-  honest and informative return — it says the worker ignored the preamble — and
-  it must be surfaced, never dropped.
-- **`journal_fidelity`** — relayed from the dispatch return (`per-turn` |
-  `streamed-opaque`), so a validator never reports `streamed-opaque` evidence as
-  if it had per-turn tool attribution.
-
-Everything else in this file applies to a foreign return unchanged: the
-honest-status rules, the pattern attestation, the TDD attestation, the wiki
-attestation, and above all **§6, the worktree delta** — which is engine-blind
-because it reads the worktree rather than the return, and is therefore what
-makes a foreign executor safe at all.
-
-## 3. Honest-status rules (executor returns)
-
-- `status=done` on a stack with a runnable build/test REQUIRES `evidence`
-  {command, exit_code, tail} quoted VERBATIM; a missing block or a false
-  `no_runner_detected` is malformed.
-- `done` with a non-empty `unmet[]` is `partial` — treat it as such.
-
-## 4. Pattern attestation (when a `pattern` was injected)
-
-A task that received a `pattern` slice must return `invariants_checked: true`
-plus the matching `pattern_version`; false/absent on a pattern task is
-malformed.
-
-## 5. TDD attestation (when a `tdd_spec` was injected — v0.33.0)
-
-A task whose slice carried a `tdd_spec` must return `tdd_state: green|red` —
-`green` only with the passing run quoted in `evidence`; `status=done` with
-`tdd_state: red` (or an absent field) is malformed. `red` is an HONEST return:
-the lane runs its repair loop up to `tdd_loop_max`, then STOPS with the red
-report — never re-dispatch past the cap.
-
-## 5b. Wiki attestation (when wiki content or page pointers were injected — v0.41.0)
-
-A task whose slice carried wiki material must return **`wiki_used`** — the doc
-paths it ACTUALLY read, or `none`. Quoted like `actual_model`: what the agent
-did, never what the dispatcher assumed.
-
-`none` is a valid and INFORMATIVE return, not a failure: it says the pages were
-not useful or were ignored. Record it and surface it — a wiki whose pages are
-shipped into every slice and read by nobody is the failure mode this field
-exists to make visible, and it is invisible if `none` is quietly dropped. Absent
-on a slice that carried wiki material is malformed. Not required otherwise.
-
-## 6. Worktree delta (post-wave, every lane that dispatches executors)
-
-Compare `git status --short` before and after each dispatch. A path that
-appears, disappears, or **reverts** and is absent from that task's
-`declared_files` is a slice violation regardless of what the return said —
-including a file that became LESS modified, which is how a destructive `git`
-command inside a slice disguises itself as a clean tree. `actual_files` is a
-CLAIM; the worktree is the EVIDENCE. An unexplained delta gates the wave: name
-it, attribute it, and get a decision before closing.
-
-**On a RESUMED task the "before" side of the delta is the JOURNAL BASELINE**
-(`orc extra reconcile`, `_shared/extra-dispatch.md`), not the state at the top of
-this wave. A file the previous attempt created is already in the tree and is
-**not** an unexplained delta — it is explained, by the journal, by name. Without
-that the first resumed wave trips its own gate on the work it just recovered.
-
-## 7. Gotcha capture (repair loops only — v0.40.0)
-
-A return that closes a repair loop (`tdd_state` went red → green, a drift
-round resolved, a reviewer P0/P1 was fixed in-run) carries
-`gotcha_recorded` — either the entry body (`trigger`, `symptom`, `cause`,
-`fix`, `scope`) or `none` with a one-line reason. Absent on a repair-closing
-return is malformed. It is NOT required on a return that never repaired
-anything, and a loop that hit its cap and STOPPED must return `none` — an
-unsolved failure is not a gotcha. The agent RETURNS the body; the
-orchestrator writes the file. See `gotchas.md`.
+# Return validation (every lane, every subagent return)
+
+Canonical procedure for validating a spawned agent's return. Every ORC lane
+(full, mini, fast, wiki, diy) runs this on EVERY return; a malformed return is
+a failure (requeue/re-dispatch with reason — lane sets the retry cap).
+
+## 0. Is the previous attempt still ALIVE? (v1.2.0) — BEFORE anything else
+
+> **`a lane that re-dispatches over a live attempt` has broken this contract.**
+
+**A Task error does not kill the agent behind it.** Claude Code's tool call can
+fail, time out, or be cut off mid-turn while the subagent it started keeps
+running — and keeps writing files. Every rule below this line ends in
+"re-dispatch", and every one of them silently assumed a failed call meant a dead
+agent. It does not.
+
+What that costs, measured: one graded `/orc-quick` entry put THREE
+`orc-executor-opus-5-low` agents on the SAME task — 50m19s, 115m22s and
+100m53s, **266 minutes of Opus 5 for one authorised dispatch**, all editing the
+same files, inside a 2h04m window. The second was dispatched 4m19s after the
+first, while the first was still working. The hook had recorded all three; no
+lane had ever read that record.
+
+### The rule
+
+Before ANY re-dispatch, requeue or repair round — and before the first dispatch
+of a resumed run — run:
+
+```
+orc run inflight --json      # 0 clear · 1 in-flight · 2 unknown
+```
+
+| exit | meaning | what the lane does |
+|---|---|---|
+| 0 | provably nothing in flight | dispatch |
+| 1 | ≥1 dispatch has not returned | **REFUSE. Name the agent, the task and its age.** Ask the user. |
+| 2 | cannot prove either way | **REFUSE by default.** Say why, and let the USER decide. |
+
+**Exit 2 refuses, and that is deliberate.** Everywhere else in ORC an absent
+reading is treated as absent and never blocks — `orc usage check` exit 2 never
+stops a run, an UNCHECKABLE pact never raises the exit code. This is the one
+place the default inverts, because the two outcomes are not symmetrical: a
+wrongly-refused dispatch costs one question, and a wrongly-issued one costs a
+second Opus agent for an hour. Refusing on `unknown` is the cheap error.
+
+### An interrupted turn is UNKNOWN, never FAILED
+
+A usage limit, an API error, a dropped connection or a `Ctrl+C` between a
+dispatch and its return says **nothing** about the agent. Treat it as §0 exit 2
+and ask. A lane that classifies an interruption as a failure re-dispatches into
+a live agent, gets interrupted again sooner because it is now paying twice, and
+the loop tightens on itself — which is exactly how the 266-minute entry
+happened.
+
+### What refusing looks like
+
+```
+⛔ 1 dispatch is still in flight — not re-dispatching.
+
+   orc-executor-opus-5-low   started 4m ago
+   "Fix approval flow defects"
+
+   A Task error does not kill the agent behind it. It may still be writing.
+   1. wait for it     2. dispatch anyway (2 agents on one task)     3. stop
+```
+
+Option 2 must always be offered and never be the default: the user is allowed
+to overrule this, and an unreadable sidecar must never trap a run.
+
+### The evidence, and its one honest limit
+
+`orc run inflight` reads the pending sidecar that `orc-trace.js` writes on every
+`SPAWN`, cross-checked against the trace's own SPAWN/RETURN balance. It reports
+`unknown` — never `clear` — when the sidecar is missing, unreadable, or holds
+only records older than six hours, and when the sidecar and the trace disagree.
+**Unknown is not zero.**
+
+It cannot see an **ad-hoc** dispatch (`/orc-quick` recon, model+effort rather
+than a pinned `orc-*` agent): the hook writes no `SPAWN` for one, so no record
+exists. Those are read-only and short, so the exposure is small — but the limit
+is stated rather than papered over, and a lane must not report `clear` as proof
+that an ad-hoc read is finished.
+
+## 1. Contract shape
+
+The return must carry every field its agent contract names. Missing or extra
+shape = malformed. Never repair a return yourself; re-dispatch.
+
+## 2. Claimed-vs-actual model (tier-downgrade check)
+
+Every return carries:
+
+- `actual_model` — quoted VERBATIM from the agent's system-prompt model-id
+  line, never inferred (`unknown` when no such line exists)
+- `actual_effort` — the agent's `$CLAUDE_EFFORT` value
+
+Compare both against what the dispatch expected (the agent NAME encodes it).
+Append the `VERIFY` trace line with the comparison; any mismatch is surfaced
+to the user as a ⛔ DOWNGRADE — never silently accepted. (A subagent can't
+exceed the MAIN session's tier, so a downgrade usually means the main session
+is on the wrong model.)
+
+## 2b. A FOREIGN return — the SUBSTITUTION check (v0.50.0)
+
+A foreign worker (`orc extra dispatch`, `_shared/extra-dispatch.md`) is not a
+Claude subagent. It has no injected system-prompt model-id line, so **it cannot
+carry `actual_model`** — and §2 must not be faked for it. A foreign return that
+claimed an `actual_model` would be claiming evidence that does not exist.
+
+It carries instead, and every one of these is quoted from the wire rather than
+assumed:
+
+- `engine` (`api` | `claude-shim` | `cli`), `provider`, `profile`
+- `model_requested` — what the route row asked for
+- **`model_reported`** — the `model` field the endpoint echoed back
+- `usage` — the four token kinds, never blended, **or `null`**
+
+**`model_reported != model_requested` is ⛔ SUBSTITUTION**, surfaced to the user
+exactly as ⛔ DOWNGRADE is today and never silently accepted. It is the only
+defence against an aggregator quietly serving something else. `unknown` is a
+valid, honest value and is reported as `unknown` — **never as a match**.
+
+**A clean model check is not a clean answer.** An aggregator's *provider-level*
+fallback is on by default and it PRESERVES the model id, so the substitution
+check reads clean while the code went to a different company. Engine `api`
+records the response's `provider` echo and reports **⚠ REROUTE**; the other two
+engines cannot see it at all, and their `served_by_note` says so. An absent
+measurement is never a pass.
+
+**`usage: null` is not four zeros.** A worker that reported no token counts
+(engine `cli` frequently) returns `null` plus a note. `{0,0,0,0}` would tell
+`/orc-budget` the run was free. Engine `api`'s `cache_write: 0` is the opposite
+case — a real measurement — so the two must never be normalised together.
+
+**The fence is per-engine, and the return says which one it had.** Engine `api`
+ENFORCES `declared_files`; engines `claude-shim` and `cli` ASK. A return
+carrying `fence: {declared_files: false}` means the list was an instruction, not
+a rule — treat §6 below as the only real check, and say so to the user rather
+than reporting a constraint that was never applied.
+
+**A RESUMED foreign dispatch owes three more fields** (v0.54.0). The dispatch
+return sets `resume_expected: true`, so the obligation is never inferred:
+
+- **`resume_state`** — `continued` · `restarted` · `no-op`. Absent on a slice
+  with no `resumed_from` is correct; **absent on a resume slice is MALFORMED.**
+  A return claiming `restarted` while `preexisting[]` was non-empty is a
+  FINDING, not a failure — it is how `/orc-retro` learns which providers ignore
+  a resume preamble, so surface it rather than treating it as a bad return.
+- **`preexisting_read[]`** — which pre-existing files the worker actually
+  opened. Quoted like `wiki_used`: **what it did, never what the dispatcher
+  assumed.** An EMPTY list on a resume whose `preexisting[]` was not empty is an
+  honest and informative return — it says the worker ignored the preamble — and
+  it must be surfaced, never dropped.
+- **`journal_fidelity`** — relayed from the dispatch return (`per-turn` |
+  `streamed-opaque`), so a validator never reports `streamed-opaque` evidence as
+  if it had per-turn tool attribution.
+
+Everything else in this file applies to a foreign return unchanged: the
+honest-status rules, the pattern attestation, the TDD attestation, the wiki
+attestation, and above all **§6, the worktree delta** — which is engine-blind
+because it reads the worktree rather than the return, and is therefore what
+makes a foreign executor safe at all.
+
+## 3. Honest-status rules (executor returns)
+
+- `status=done` on a stack with a runnable build/test REQUIRES `evidence`
+  {command, exit_code, tail} quoted VERBATIM; a missing block or a false
+  `no_runner_detected` is malformed.
+- `done` with a non-empty `unmet[]` is `partial` — treat it as such.
+
+## 4. Pattern attestation (when a `pattern` was injected)
+
+A task that received a `pattern` slice must return `invariants_checked: true`
+plus the matching `pattern_version`; false/absent on a pattern task is
+malformed.
+
+## 5. TDD attestation (when a `tdd_spec` was injected — v0.33.0)
+
+A task whose slice carried a `tdd_spec` must return `tdd_state: green|red` —
+`green` only with the passing run quoted in `evidence`; `status=done` with
+`tdd_state: red` (or an absent field) is malformed. `red` is an HONEST return:
+the lane runs its repair loop up to `tdd_loop_max`, then STOPS with the red
+report — never re-dispatch past the cap.
+
+## 5b. Wiki attestation (when wiki content or page pointers were injected — v0.41.0)
+
+A task whose slice carried wiki material must return **`wiki_used`** — the doc
+paths it ACTUALLY read, or `none`. Quoted like `actual_model`: what the agent
+did, never what the dispatcher assumed.
+
+`none` is a valid and INFORMATIVE return, not a failure: it says the pages were
+not useful or were ignored. Record it and surface it — a wiki whose pages are
+shipped into every slice and read by nobody is the failure mode this field
+exists to make visible, and it is invisible if `none` is quietly dropped. Absent
+on a slice that carried wiki material is malformed. Not required otherwise.
+
+## 6. Worktree delta (post-wave, every lane that dispatches executors)
+
+Compare `git status --short` before and after each dispatch. A path that
+appears, disappears, or **reverts** and is absent from that task's
+`declared_files` is a slice violation regardless of what the return said —
+including a file that became LESS modified, which is how a destructive `git`
+command inside a slice disguises itself as a clean tree. `actual_files` is a
+CLAIM; the worktree is the EVIDENCE. An unexplained delta gates the wave: name
+it, attribute it, and get a decision before closing.
+
+**On a RESUMED task the "before" side of the delta is the JOURNAL BASELINE**
+(`orc extra reconcile`, `_shared/extra-dispatch.md`), not the state at the top of
+this wave. A file the previous attempt created is already in the tree and is
+**not** an unexplained delta — it is explained, by the journal, by name. Without
+that the first resumed wave trips its own gate on the work it just recovered.
+
+## 7. Gotcha capture (repair loops only — v0.40.0)
+
+A return that closes a repair loop (`tdd_state` went red → green, a drift
+round resolved, a reviewer P0/P1 was fixed in-run) carries
+`gotcha_recorded` — either the entry body (`trigger`, `symptom`, `cause`,
+`fix`, `scope`) or `none` with a one-line reason. Absent on a repair-closing
+return is malformed. It is NOT required on a return that never repaired
+anything, and a loop that hit its cap and STOPPED must return `none` — an
+unsolved failure is not a gotcha. The agent RETURNS the body; the
+orchestrator writes the file. See `gotchas.md`.

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.