@azure-id/orc 0.56.0 → 1.0.0

package/templates/skills/_shared/config-precedence.md

@@ -0,0 +1,198 @@
+# Shared contract — config precedence: ranks, families, and one resolver per lane
+
+Canonical rule for how EVERY ORC lane learns what it is configured to do.
+Consumed by every lane that reads a setting; the lint pins the
+`config-precedence.md` pointer into each of them.
+
+Two sentences carry the whole file:
+
+> **ONE resolver, and it is not you:** `orc lane config <lane> --json`.
+>
+> **Read a family top-down and stop at the first rank that resolves.**
+
+---
+
+## 1. The resolver
+
+A lane never reads `.claude/orc.config.yaml`. It runs
+`orc lane config <lane> --json` once, at preflight, and obeys the answer.
+
+| field | what a lane does with it |
+|---|---|
+| `effective` | the flat answer. Obey it and reason about nothing. |
+| `announce[]` | print every line VERBATIM at preflight, before the first dispatch |
+| `stops[]` | every value that can HARD-STOP this run; honour each before wave 1 |
+| `keys[]` | per key: `value`, `default`, `prio`, `family`, `state`, `is_shadowed` / `shadow_reason`, `is_inert` / `inert_reason` |
+| `families{}` | which rank answered each question, and why the rest were not read |
+| `not_read[]` | the keys this lane deliberately ignores |
+
+`not_read[]` is an ANSWER, not a gap. "This lane does not read `doc_language`"
+is information, and it is what makes the two-way registry lint possible.
+
+**Never re-derive a value, a precedence, or an inertness.** A key this lane does
+not read is not in the answer; a key another key shadows comes back already
+marked, with the sentence already worded. A lane that reasons *"`opus5_only` is
+on, so the fable block must be inert"* has forked the resolver — it reads
+`is_shadowed` and prints `shadow_reason`.
+
+---
+
+## 2. Ranks, and the rule that makes them mean something
+
+Every key declares `answers[]`: which FAMILY question it answers, at which
+RANK (`P0` · `P1` · `P2` · `P3`), in which MODE.
+
+> **Read a family top-down and stop at the first rank that resolves.**
+> If the P0 key of a family resolves, P1, P2 and P3 of that family are **not
+> read at all** — not consulted, not defaulted, not mentioned as a fallback. A
+> rank below a resolved rank has no effect and no meaning for this decision.
+
+**A rank compares only INSIDE its family.** `log_dir` being P2 and `opus5_only`
+being P1 says nothing whatever: they never compete. A family whose keys do not
+compete has every key at P2, the neutral rank, and the lint asserts it — rank
+distinctness is required only where a family is declared contested.
+
+| `mode` | resolves when | effect on the ranks below it |
+|---|---|---|
+| `replace` | the key is set to a truthy / non-default value | every lower rank is shadowed, entirely |
+| `overlay` | the key is on **and** at least one row applies to THIS decision | lower ranks are shadowed only for the ranges or slots it covers |
+| `gate` | — | it never resolves the family; it makes its own dependants **inert** (§4) |
+
+An `overlay` resolves PARTIALLY, so the honest report is WHICH ranges and WHICH
+positions it took — never a single word. The ranges it did not take fall through
+to the next rank normally. That is what lets "cheap work goes to a foreign
+worker, hard work stays on Opus 5" be two rows rather than a table rewrite.
+
+**The lowest rank of a contested family is TOTAL.** Something must answer when
+nothing above resolved, so that terminal row is the shipped default and it is
+declared as a row, not as a key — a fall-through is not a setting.
+
+---
+
+## 3. The two contested families
+
+Everything else is uncontested: one question, no competition, every key P2.
+
+**`executor-band` — which model executes a SCORED task**
+
+| rank | key | mode | |
+|---|---|---|---|
+| P0 | `extra_enabled` | overlay | a route row covering this score sends it off Claude |
+| P1 | `opus5_only` | replace | the fixed 2-band Opus 5 ladder |
+| P2 | `rubric_bands_override` | replace | hand-edited, registry-less by design; resolves on PRESENCE |
+| P3 | — | terminal | the shipped score→model table |
+
+**`fixed-role-model` — which model runs a role that has no score**
+
+| rank | key | mode | |
+|---|---|---|---|
+| P0 | `extra_enabled` | overlay | a slot row holds that POSITION |
+| P1 | `opus5_only` | replace | the shipped Opus 5 variant of that position's agent |
+| P2 | — | terminal | the agent shipped for that position |
+
+Said once, for both shapes: **extra decides whether a Claude agent runs at all;
+`opus5_only` and the score tables only decide WHICH Claude agent runs where
+extra did not take it.** Under a taken band or a taken slot, `opus5_only` is
+**not consulted** — not "inert" — and it stays fully live everywhere else.
+
+---
+
+## 4. A gate is not a rank — it is inertness
+
+`extra_enabled: false` does not lose a precedence contest. It means **no
+`extra_*` key is consulted at all**. A key declares `gated_by`, inherits its
+gate's row, and comes back `inert` with the reason already worded.
+
+Lane-level inertness is a THIRD thing, with nothing in the config file involved:
+
+| lane | inert | reason (must not be softened) |
+|---|---|---|
+| `/orc-quick` | `opus5_only`, `rubric_bands_override`, `extra_*` | this lane asks WHICH AGENT before every dispatch — a config that silently answered that question would break the lane's entire premise |
+| `/orc-challenge` | `opus5_only` | every agent in this lane is already `claude-opus-5` — a **no-op; the lane is unaffected, not exempt** |
+| `/orc-doc` | `opus5_only` | the same — unaffected, not exempt |
+
+**"Unaffected, not exempt"** survives verbatim. A generic "not applicable" loses
+the fact that turning the key on breaks nothing here.
+
+---
+
+## 5. `announce[]` — and its exact boundary
+
+A shadowed setting must never be silent, and work must never leave Claude
+without the run saying so. Those lines are computed, worded once by the CLI, and
+printed by the lane verbatim.
+
+| goes in `announce[]` | stays with the lane |
+|---|---|
+| anything derivable from config + disk the CLI already reads: the wiki tier, pattern-cache presence, crosslink state, extra route rows and taken slots, pact / boundary / challenge state, which keys are shadowed or inert, the resolved scan tier, a run-scoped demotion | anything needing a per-task or per-run value the CLI cannot know: a task's score, a task id, a slug, a file count, a forecast number, a wave index |
+
+A line needing a runtime value is **not** emitted as a template with holes. Half
+a sentence from the CLI and half from the model is worse than either — it is a
+sentence nobody owns. Those lines stay with the lane.
+
+---
+
+## 6. The ladder can move at runtime
+
+A profile that stalls twice in one run, or holds one live attempt quiet past
+`extra_demote_stale_min`, is DEMOTED to the bottom of its families for the rest
+of that run — so the next rank down becomes the effective P0. The verdict is
+recomputed from disk on every read and never stored; it is run-scoped and never
+touches the config file; it is never promoted back on its own; and it is
+ANNOUNCED, because the mirror of sending work off Claude silently is quietly
+stopping. Full rule: `extra-dispatch.md`.
+
+---
+
+## 7. When the CLI is not there
+
+Exit ≠ 0, or the command is not found:
+
+1. **Say so, in one line.** Fail open with the failure stated.
+2. Use the documented defaults below.
+3. Treat **every P0 forcing mode as OFF**.
+4. Never guess a user override, and never present a default as a resolved value.
+
+The floor is the keys a run cannot start without — `max_wave_tasks: 3` ·
+`batch_pause_every: 2` · `rubric_bands: 5` · `max_scouts: 3` ·
+`default_analysis_depth: standard` · `generate_tests: false` ·
+`pattern_findings: ask` · `security_review: off`.
+
+Every other key's default is the CLI's to state. **A lane never guesses one** —
+if a decision needs a key not on that list and the CLI cannot answer, the lane
+says which key it could not resolve and stops, rather than inventing a value the
+user may have overridden.
+
+---
+
+## 8. The `## Config` section every lane carries
+
+Verbatim, and identical in every lane but its own name:
+
+```markdown
+## Config
+
+**ONE resolver, and it is not you:** `orc lane config <lane> --json`. Obey
+`effective`, print every line in `announce[]` VERBATIM at preflight, and honour
+`stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
+from `.claude/orc.config.yaml` — a key this lane does not read is not in the
+answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
+the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
+documented defaults, out loud. Priorities and families:
+`../_shared/config-precedence.md`.
+```
+
+---
+
+## 9. The file the user edits
+
+`.claude/orc.config.yaml` holds only the keys the user changed, sits outside
+`templates/` (so `orc update` never clobbers it), and is written exclusively by
+`orc config set`. It is grouped by the QUESTION each key answers, ordered by
+rank only inside a contested family.
+
+`orc config set` regenerates its own group comments on every write and
+**never rewrites a value it was not given**: a comment the user wrote stays with
+the key it sits above, and a hand-edited multi-line block survives byte for
+byte. A key written under a retired spelling is rebuilt under its current name —
+a renamed mechanism must never be a silent revert.

package/templates/skills/_shared/drift-recovery.md

@@ -29,7 +29,7 @@ never in `.claude/`, never in the run folder):
 **Who builds it: NOT you.** The example is DISPATCHED like any task (orc hard
 rule 1 — the orchestrator never implements, not even the smallest task). It is
 an orchestrator-SYNTHESIZED task, so it is scored from a DERIVED vector, never a
-judged one — see `orc/references/wave-grouping.md` "Orchestrator-synthesized
+judged one — see `_shared/phases/wave-grouping.md` "Orchestrator-synthesized
 tasks".
 
 **Git: NEVER committed.** The ship phase explicitly excludes `mock-examples/`

package/templates/skills/_shared/extra-dispatch.md

@@ -169,7 +169,7 @@ A slot is a **point**, not an interval, so the band table's overlap refusal has
 no analogue here and none is invented. `orc extra role set` on an occupied slot
 REPLACES, and says what it replaced.
 
-### The nine hold-backs, each answered by name
+### The ten hold-backs, each answered by name
 
 1. **unknown slot** — refused, exit 2, listing the six.
 2. **`extra_enabled` false** — claude. The master gate.
@@ -191,6 +191,11 @@ REPLACES, and says what it replaced.
    preflight` STOPS the run. `extra_on_failure` never covers it: that key is
    about an endpoint that failed, and a deadline you set 30 days ago deserves a
    stop.
+10. **the profile is DEMOTED in this run** (v1.0.0) — claude, named, with the
+    promote command. The tenth hold-back and the only one that is about the RUN
+    rather than about the row: two consecutive stalls, a 20-minute stale live
+    attempt, or a human running `orc extra demote`. The position falls through
+    to the SAME pinned Claude agent it always had.
 
 ### What it hands back
 
@@ -202,7 +207,7 @@ REPLACES, and says what it replaced.
 | `band` | the ROUTE row's band, not the Claude band. On a slot answer it is the string **`slot:<slot>`** — the field NAME is unchanged, so the trace parser, the eight-field dedupe and the ` :: ` tolerance keep working untouched |
 | `slot` · `lane` · `asks` | present on a slot answer only. `score` is `null` there, and **is not derived from anything** |
 | `claude` | `{via, band, agent, table}` — **always present**, on both answers. It is the fall-through target AND the fallback target, so nothing ever needs a second lookup |
-| `held_back` | `null` · `role` · `risk` · `boundary` · `missing-profile` · `unverified` |
+| `held_back` | `null` · `role` · `risk` · `boundary` · `missing-profile` · `unverified` · `demoted` |
 | `verify_state` · `needs_reping` | `FRESH` / `STALE`. **A STALE profile still routes** — a stale check is not a failed one |
 | `model_known` | whether the routed model id was in the last ping's `models_seen`. `false` is a WARNING, never a block: the list is a cache, not an authority |
 | `credential` | `{source, key_name, present}` — never a value |
@@ -228,7 +233,7 @@ One sentence, and it is the same sentence for both shapes:
 an extra route row covering this score      (only for the scores it covers)
   > opus5_only
   > rubric_bands_override
-  > the default 8-band table
+  > the default 6-band table
 ```
 
 **A slot**, highest wins:
@@ -260,7 +265,7 @@ it, `orc extra route set` names the Claude band each new row displaces, and
 `orc config list --json`'s `score_table.active` can read `extra+opus5_only` —
 a composite, because the truth is a composite and a single word would be a lie.
 
-**`/orc-quick` is a GATED CHOICE, not a route.** `opus5_only`, `fable5_*`,
+**`/orc-quick` is a GATED CHOICE, not a route.** `opus5_only`,
 `rubric_bands_override` and `extra_resume` stay INERT there — that lane asks
 *which agent* before every dispatch, so a config that silently answered that
 question, or that silently continued the previous foreign worker's half-finished
@@ -686,7 +691,7 @@ only moment anyone can act on it is now.
 
 The trace line is still yours to relay, and it still matters: it is the
 human-readable narrative of the run, it is what `/orc-retro` reads, and the
-trace-cadence rule in `references/trace-protocol.md` still binds every phase.
+trace-cadence rule in `phases/trace.md` still binds every phase.
 What changed is that the SPEND no longer depends on it.
 
 One `EXTRA` line per foreign dispatch, plus its continuations. **Copy
@@ -978,12 +983,289 @@ supplies it pre-composed in `trace_extras[]`.
 
 ---
 
-## The config surface — eleven keys, and the count is still the point
+## The stall — a worker that is alive and doing nothing (v0.56.1)
+
+### `a lane that waits out a wall clock on a worker that stopped` has broken this contract
+
+A wall clock cannot tell a worker that is thinking hard from a worker that has
+stopped. Both look like fifteen minutes of nothing. So until v0.56.1 an opencode
+session that went quiet mid-task — the thing you fix by hand by typing
+`continue` into its window — burned the whole `extra_timeout_s` budget and then
+reported `timeout`, which is a statement about **ORC's patience** and not about
+what happened. It read as a budget somebody should raise. It was a **position
+somebody should resume from**.
+
+### What the stall clock measures
+
+`config.extra_stall_s` (default **180**, `0` disables) is the seconds a foreign
+worker may produce **nothing at all** before the dispatch is stopped. It is not
+a second wall clock: it is reset by **observable progress**, in the only three
+places progress can show up.
+
+| signal | why it counts |
+|---|---|
+| new bytes on the worker's own stream | it is talking |
+| new bytes on its stderr | it is complaining, which is still working |
+| a **declared file** changed size or mtime on disk | it just wrote something, whatever its stream is doing |
+
+Any one of the three resets the clock. All three quiet for the whole budget is
+the finding. That third row is what stops the clock firing on a worker that
+thinks for four minutes and then writes a file in one go.
+
+Ordered with the other three, once, in `extraTimeouts`: **stall < idle < api <
+wall**. A budget at or past the wall clock could never fire, so it is CLAMPED
+rather than honoured, and `orc extra health` reports the clamp.
+
+**Engine `cli` only.** Engine `api` already has a per-request inactivity timeout
+on its own socket, and engine `claude-shim` gets one from the child's own byte
+watchdog. Adding a fourth clock to either would be three timeouts disagreeing
+about which one fires first, which is the bug `extraTimeouts` exists to prevent.
+
+### `stalled` is its own failure class, and it is RETRYABLE
+
+`EXTRA_FAILURES.stalled` — *"the worker went quiet and stopped changing
+anything"*, `retry: true`. That is the whole point: a stall is retryable, so the
+recovery procedure above applies to it unchanged. `orc extra reconcile` reads the
+position out of the journal baseline; `orc extra resume-slice` composes the
+continuation carrying what is already on disk; `extra_resume` continues from
+there instead of starting over.
+
+**That IS ORC's spelling of typing `continue`.** There is deliberately no key
+that nudges the child on its stdin: `opencode run` is not an interactive session,
+so a keystroke nobody reads would be a fake fix — and a fake fix here is worse
+than none, because it would look like the problem was handled.
+
+### Every outcome carries a TIMELINE
+
+`timeline` rides on every engine-`cli` return, not only on a stall:
+`first_byte_ms` · `last_progress_ms` · `longest_gap_ms` · `quiet_for_ms` ·
+`stall_budget_ms` · `wall_budget_ms`. Print it. **A budget you can only see when
+it fires is a budget nobody can set before it does** — and `first_byte_ms: null`
+is the honest reading of a worker that never said anything, never `0`.
+
+### `orc extra health <profile> [--model <id>]` — does this model stall?
+
+Exit **0** answered · **1** stalled or failed · **2** unknown profile.
+
+It runs the live probe through **the same watchdog a dispatch uses** — not a
+second idea of the path, which is the v0.53.3 rule that a green badge must be
+earned by the path a wave actually runs. What it adds over
+`orc extra ping --live` is the timeline and the verdict: `answered` · `stalled` ·
+`timeout` · `failed` · `spawn-failed`, plus the bytes the worker produced, capped
+and rendered as text.
+
+A **listed** model is not a **working** model and a working model is not a model
+that **finishes**: those are three different facts and this is the command that
+tells the third one apart. Run it before routing a band at a model you have not
+used. A CLI ping is not a cheap ping — say so.
+
+---
+
+## The demotion — the ladder moves at runtime (v1.0.0)
+
+### `a lane that keeps paying a provider that stopped working` has broken this contract
+
+`extra_stall_s` stops ONE dispatch. It has nothing to say about the second one,
+or the third. A provider that goes quiet twice in a row is not having a bad
+minute — it is costing you a wave and buying nothing — and ORC used to keep
+handing it the next task anyway, because nothing counted.
+
+So it counts now. **Two consecutive `stalled` dispatches on one profile inside
+one run, or one live attempt with no observable progress for 20 minutes, drop
+that profile to the BOTTOM of its families for the rest of the run.**
+`opus5_only` — or the shipped score→model table — becomes the effective P0, and
+the work stays on Claude.
+
+### It writes no new measurement, and it is never remembered
+
+Every fact the trigger reads already shipped: `EXTRA_FAILURES.stalled` and the
+`timeline` block (v0.56.1), and the extra journal written by `orc extra dispatch`
+itself before the first byte leaves the machine (v0.54.0). The demotion READS
+the journal and decides — **computed by the CLI from disk on every read, never
+stored as a verdict and never carried in your head.** That is the lesson this
+repo has now lost to four times: v0.32.0 narration, v0.49.5 the hand-back,
+v0.53.2 the spend log, v0.54.0 the journal. **A fact relayed through a model's
+memory is a fact this repo has already lost.**
+
+The only thing written to disk is the HUMAN half — a promote or a manual demote,
+with its reason — under `{run_dir}/{slug}/extra-demotion.json`, beside
+`RESUME.md`. That is a decision, not a verdict, and it is deleted with the run.
+
+### The two clocks measure different things and stay two clocks
+
+```
+demote(profile, run) ⇔
+      consecutive_stalls(profile, run) >= extra_demote_after         (default 2)
+   OR a LIVE attempt quiet for >= extra_demote_stale_min minutes     (default 20)
+```
+
+- **The consecutive clock is about attempts that ENDED.** A stall is a stall
+  whether its resume succeeded or not: a profile that needs a continuation twice
+  in a row is costing more than it saves.
+- **The stale clock is about an attempt that has NOT ended.** `extra_stall_s`
+  already stops one dispatch after 180 seconds of silence. This one is about the
+  RUN — two workers in flight, both quiet, and a wave that is going nowhere.
+  Different question, different budget, its own key and its own off value.
+  **Neither is a simplification of the other**, and merging them "for
+  simplicity" is the failure this paragraph exists to prevent.
+- **The counter is per PROFILE**, not per provider and not global. Two profiles
+  on one provider can hold different keys, different models and different
+  reliability.
+- **A resume of the same stalled attempt is the SAME stall.** It neither
+  increments the counter nor resets it.
+- **`consecutive` resets on a completed dispatch that was not a stall** —
+  including a 401.
+- **ONLY `stalled` counts.** Not `timeout` (the budget was the operator's
+  choice), not `rate_limit`, not `authentication_failed`. Each of those has its
+  own answer — `extra_on_failure`, the vault, `extra_resume` — and **a demotion
+  triggered by a 401 would hide a credential problem behind a routing change**,
+  where the user would never see the real fault.
+- **`extra_stall_s: 0` silently turns the consecutive clock off too:** no
+  dispatch is ever classified `stalled`, so the counter can never move and only
+  the stale clock remains. `orc extra demotion` says so rather than reporting a
+  clock that cannot fire.
+
+### The four things it must never do
+
+1. **It never writes your config.** Run-scoped, like `/orc-ultra`'s
+   `ultra_mode`. A run that had a bad afternoon must not silently turn off a
+   subsystem you paid to set up.
+2. **It never auto-promotes inside the run.** Two stalls is evidence, and a
+   timer that re-arms a provider spends money on the evidence it already has.
+   `orc extra promote <run> --reason "<why>"` is a human action and the reason is
+   stored verbatim — the `/orc-pact` retirement rule. **A promote is a
+   WATERMARK, not a mute:** it forgives the evidence it saw, and two fresh stalls
+   after it demote again.
+3. **It never changes WHAT.** The score does not move, `declared_files` is not
+   widened, `acceptance[]` is not touched — `extra_fallback_agent`'s rule
+   inherited verbatim. **A demotion changes WHERE the work runs and nothing
+   else**, and the task lands on the SAME Claude agent it would have had.
+4. **It never abandons the position.** A demoted run still goes
+   `orc extra reconcile` → `orc extra resume-slice` → an ordinary Claude
+   dispatch. `a lane that re-does work the worktree already contains` applies
+   here exactly as it applies to the fallback, and it is the same code path.
+
+### It is ANNOUNCED, and that is not optional
+
+The mirror of `a lane that sends work off Claude without saying so` is **a lane
+that quietly STOPS.** A user who connected a provider deserves to be told the
+run left it. The line is CLI-worded (`announce` on the demotion state), it
+arrives in `orc lane config`'s `announce[]`, and it must be printed **before the
+next dispatch**. `orc lane config` renders the overlay rank as `state:
+"demoted"` — its own word, keeping its slot, because rendering it as
+`extra: off` would make *"I turned this off"* and *"this run left your provider
+after two stalls"* look identical.
+
+The trace verb is **CLI-composed and copied verbatim**, because **a demotion
+that leaves no line cannot be counted** (the v0.53.2 rule, restated):
+
+```
+EXTRA demote run=<slug> :: profile=<p> reason=<consecutive-stall|stale-live-attempt|manual> n=<k> → <the ladder that answers now>
+```
+
+### The three commands
+
+| command | exit codes | notes |
+|---|---|---|
+| `orc extra demotion [<run>] [--json]` | `0` armed · `1` demoted · `2` unknown run | a READ, and the exit code is the answer. `--json is not a summary`: it carries both clocks, the counter, the evidence task ids, the ladder before and after, and the announce line |
+| `orc extra promote <run> --reason "<why>"` | `0` promoted · `1` nothing was demoted · `2` unknown run | the reason is REQUIRED and stored verbatim |
+| `orc extra demote <run> --reason "<why>"` | `0` demoted · `2` unknown run | the manual half. Somebody who knows the provider is down should not have to wait for two stalls |
+
+`orc extra preflight` **reports a live demotion and does not move its exit
+code** — a demotion is a finding, not a stop, the `extra-orphan-dispatch`
+precedent. `orc doctor` gains **`extra-demoted-run`**, routed to the Extra
+panel's Recovery tab, which is where `orc extra promote` lives.
+
+`orc extra stats` aggregates it **per profile across every run the journal still
+holds** — a provider that demotes in every run is a pattern; one that demoted
+once is an afternoon, and the difference is only visible if somebody counts.
+There is **no rate below 3 runs**, the `extra-profile-unreliable` restraint
+verbatim.
+
+### The keys, and the two that were refused
+
+| key | default | off |
+|---|---:|---|
+| `config.extra_demote_after` | `2` | `0` — never demote on consecutive stalls |
+| `config.extra_demote_stale_min` | `20` | `0` — never demote on a stale live attempt |
+
+Both gated by `extra_enabled`. **Setting both to `0` is the honest off switch**,
+which is why there is no third key:
+
+- **REFUSED — `extra_demote` (`on`/`off`).** The two zeros already are it, and a
+  master switch over two numbers is a third spelling of one thing — the drift
+  this subsystem lints for everywhere else.
+- **REFUSED — `extra_promote_after` (an auto re-promote timer).** A timer that
+  re-arms a provider which stalled twice is a timer that spends money on the
+  evidence it already has. Promotion is a human decision with a recorded reason.
+
+---
+
+## Who picks the task up — `extra_fallback_agent` (v0.56.1)
+
+`fallback_to` has always carried the band's (or the slot's) own Claude agent.
+That is the right default and the only one ORC can compute on its own: **a
+fallback that changes tier is a re-plan nobody asked for.**
+
+What it could not do is let a human choose. A stall costs real minutes before
+anybody hears about it, and by the time the wave stops the user often knows
+something ORC does not — that this slice wants more thinking than its band
+bought, or less.
+
+| `extra_fallback_agent` | what the lane does |
+|---|---|
+| `band` (default) | dispatch `fallback.agent`, which is `fallback_to.agent`. Pre-v0.56.1 behaviour, unchanged. |
+| `ask` | **STOP and put `fallback.options[]` to the user.** Dispatch what they pick. |
+| any `orc-…` agent name | dispatch that one, and say it overrode the task's own agent. |
+
+The return carries `fallback` beside `fallback_to`: `mode`, `agent`,
+`band_agent`, `options[]` (each with `agent`, `why`, `is_band`) and a `note` that
+is already worded — print it rather than composing a second wording.
+
+Three rules hold it together.
+
+1. **Under `ask` the lane does not choose.** `fallback.agent` is `null` and the
+   trace line says `→ pending (extra_fallback_agent=ask)`. A lane that picked the
+   first option would be answering the one question the setting exists to ask,
+   and `/orc-retro` would aggregate a decision nobody made.
+2. **The menu is COMPUTED and the band's own agent LEADS it.** It is what
+   happens if the user just presses enter. The three alternates —
+   `orc-executor-opus-5-med`, `orc-executor-opus-5-low`,
+   `orc-executor-sonnet-4-6-high` — are offered, and so is any installed agent
+   name, because the roster is generated and a closed list here would go stale
+   the next time a band moves.
+3. **It changes WHO, never WHAT.** The score does not move, `declared_files` is
+   not widened, `acceptance[]` is not touched, and a resume slice stays a resume
+   slice. This is the `extra resume-slice` rule applied to the fallback.
+
+**`/orc-quick` is INERT here too,** and announces it at the agent gate — beside
+`extra_enabled`, `extra_on_failure`, `extra_resume`, `opus5_only` and
+`rubric_bands_override`. That lane asks which agent before every dispatch, so a
+config that pre-answered it would be the exact failure the gate exists to
+prevent.
+
+---
+
+## The config surface — fifteen keys, and the count is still the point
 
 The combinatorial part — providers × models × bands **× positions** — is a
 **ledger with a CLI and a panel** (`orc extra`), not a YAML block nobody can hold
 in their head.
 
+**v1.0.0 added TWO** — `extra_demote_after` and `extra_demote_stale_min` — and
+both are NUMBERS WITH A DOCUMENTED OFF VALUE rather than a switch, because the
+two zeros already are the off switch and a master key over them would be a third
+spelling of one thing. Two more were refused and are written down above.
+
+**v0.56.1 added TWO**, and both come from the same observed failure: a foreign
+worker that goes quiet mid-task. Three more were refused and are written down so
+nobody proposes them again — **a stdin nudge** (`opencode run` is not an
+interactive session, so a keystroke nobody reads is a fake fix, and a fake fix
+looks like the problem was handled), **a per-profile stall budget** (the number
+describes ORC's patience, not a provider), and **a key to disable the timeline**
+(the spend-log reasoning verbatim: a record you can switch off is off on the run
+you needed it for).
+
 **v0.55.0 added ZERO keys.** A slot row's presence is its arming, so the four
 that were proposed were all refused: **`extra_slots_enabled`** (a second master
 gate — `extra_enabled` is one), **per-lane on/off keys** (`extra_doc`,
@@ -1008,6 +1290,10 @@ of being a string nobody checked).
 | `config.extra_verify_max_days` | `7` | Past this a verification reads STALE and is re-pinged before wave 1. **A STALE profile still routes** — a stale check is not a failed one. |
 | `config.extra_resume` | `on` | Whether a partial or crashed foreign dispatch is RESUMED rather than re-done. **Default `on`, because `off` is what is broken.** INERT in `/orc-quick`. |
 | `config.extra_resume_max` | `2` | Resume attempts per task before P6 takes over. The cap STOPS with an honest report naming the Claude agent — never a silent third loop, the same shape as every other bounded repair loop in ORC. |
+| `config.extra_stall_s` | `180` | Seconds a foreign worker may produce NOTHING before the dispatch is stopped as `stalled`. Reset by observable progress — the worker's stream, its stderr, or a declared file that changed on disk — so it never fires on a worker that is merely slow. `0` disables and the wall clock is the only stop again. **Clamped below `extra_timeout_s`**, because a budget that can never fire is worse than none. Engine `cli` only. |
+| `config.extra_demote_after` | `2` | Consecutive `stalled` dispatches on ONE profile inside one run before that profile is DEMOTED to the bottom of the ladder for the rest of the run. Only `stalled` counts; a resume of the same stall is the same stall; a completed dispatch that was not a stall resets it. Run state — it never writes your config, it is ANNOUNCED, and it is never promoted back on its own. `0` turns this clock off. |
+| `config.extra_demote_stale_min` | `20` | Minutes a LIVE attempt may show no observable progress before its profile is demoted. A different question from `extra_stall_s`, which stops ONE dispatch: this clock is about the RUN. `0` turns this clock off. |
+| `config.extra_fallback_agent` | `band` | WHICH Claude agent picks up a task the foreign worker could not finish. `band` is the pre-v0.56.1 behaviour. `ask` STOPS and puts the menu to the user. Any installed agent name pins one. It changes WHO, never the score, the declared files or the acceptance criteria. INERT in `/orc-quick`. |
 
 **Keys deliberately NOT added, and why each one would be a trap:**
 

package/templates/skills/_shared/interview.md

@@ -3,7 +3,7 @@
 Canonical file: `_shared/interview.md`. THE canonical way any ORC lane
 interrogates a human until an idea is sharp enough to act on. Load it wherever a
 lane must ask more than a fixed questionnaire's worth of questions: `/orc-grill`
-runs it end to end, and `references/intake.md` borrows its round format when a
+runs it end to end, and `phases/intake.md` borrows its round format when a
 tier's question set runs long.
 
 This is not "ask good questions". It is a specific mechanic with a termination

package/templates/skills/_shared/opus5-only.md

@@ -13,14 +13,18 @@ is inert.
 
 ## The mapping (only when `opus5_only: true`)
 
-**Scored executors** — one model, EFFORT as the cost dial, replacing the 8-band
+**Scored executors** — one model, EFFORT as the cost dial, replacing the 6-band
 mixed-model table:
 
 | Score | Executor agent |
 |-----------|---------------------------|
-| `[0,40)`   | `orc-executor-opus-5-low`  |
-| `[40,80)`  | `orc-executor-opus-5-med`  |
-| `[80,100]` | `orc-executor-opus-5-high` |
+| `[0,90)`   | `orc-executor-opus-5-low`  |
+| `[90,100]` | `orc-executor-opus-5-med`  |
+
+Two bands, sharing the 90 edge with the default table's top two rows. Since
+v1.0.0 the default table's high end is ALREADY Opus 5 with effort as the dial,
+so this mode differs from it only below 65 — a third band here would be a
+distinction the default table stopped making.
 
 **Fixed roles** — dispatch the Opus 5 variant **instead of** the default role
 agent: same task slice, same return contract, same phase.
@@ -77,12 +81,10 @@ exists to prevent. Ladder: `../orc-wiki/references/partial-refresh.md`.
 `opus5_only: true` outranks every other dispatch selector:
 
 - each role's default frontmatter pin;
-- **`fable5_enabled` / `fable5_roles`** — the Fable 5 role override is fully
-  INERT while the mode is on (`../_shared/fable5-override.md` does not apply);
 - **`rubric_bands_override`** — a hand-written executor table is ignored while
   the mode is on.
 
-Turning the mode off restores all three. `rubric_bands` remains granularity
+Turning the mode off restores both. `rubric_bands` remains granularity
 only, never a preset selector, in both modes.
 
 The forcing is flat across every lane that HONORS the mode — `orc-quick` does