@azure-id/orc 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -10,6 +10,302 @@ Format: `### v<version> — <title> _(<date>)_`.
 
 ---
 
+### v1.4.0 - the agent panel, and the number that was missing _(2026-09-04)_
+
+**Still on the unscoped `orc` package?** Do this once first — your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 — release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 — install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 — re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+The second board. Claude Code renders a custom row for every subagent in the
+agent panel, and that surface is ORC's exact domain: one row per dispatched
+agent, live, while it runs.
+
+```
+● orc-executor-opus-5-low   O5/low   84K   ███▎░░░░  42%   for 17m
+✓ orc-reviewer-opus-5-med   O5/med   31K   █▌░░░░░░  16%   for  4m
+```
+
+**AND IT ANSWERS A QUESTION v1.2.0 SAID COULD NOT BE ANSWERED.** That release
+established that Claude Code records no token usage for a dispatched subagent —
+`isSidechain` is never set, no sidechain message carries a usage block, verified
+across every transcript on two machines — so `orc usage report` has reported
+`tokens: null` for every Claude row ever since, and said why.
+
+That is still true **of the transcript**. It is not true of the agent panel,
+which carries `tokenCount` per task along with the resolved `model` and
+`effort`. So the hook writes down what it is handed, and `orc usage report`
+reads it.
+
+- **It is a FLOOR, and it is labelled one everywhere it appears.** The hook sees
+  a task only while it is in the panel: an agent that started and finished
+  between two renders is never seen, and a count read just before an agent
+  finished is short by whatever came after. `not-seen` means exactly that and
+  is never `0`. A floor reported as a total would be the same class of lie as a
+  zero reported for an unknown.
+- **The record is written even with the board OFF.** It is not part of the
+  display feature — it is a measurement Claude Code hands over either way, and
+  throwing it out because a display setting is off would be the wrong trade by a
+  wide margin. `orc init` and `orc update` wire `subagentStatusLine` for that
+  reason alone, and never clobber one you already have.
+- **A count can only go up**, so a lower reading is a stale one and never
+  overwrites a higher one.
+- **The model and effort are OBSERVED.** ORC's downgrade check has two readings
+  — one derived from the agent's name, one the agent reports about itself. This
+  is the third, and the only one nobody had to be trusted for.
+
+**ONE COMPILER, TWO BOARDS.** The second board reuses the compiler, the render
+program, every shape, every glyph set, the colour model, the validator and the
+gate ladder. What differs is a component set, three filenames and a config key —
+a table, not a fork. A test asserts there is exactly one compiler and that the
+new hook grew no renderer of its own, because that is the cheap mistake this
+whole design exists to avoid.
+
+- **A component belongs to one board**, and the other refuses it by name with
+  the board it belongs to. Two catalogues would be two lists somebody has to
+  keep in step; this is one catalogue with a column.
+- **A subagent row is one line by construction** — Claude Code renders one per
+  task — so the three-line board and its dense-prefix rule simply do not apply.
+- **Three presets**: what the agent is and what it has cost, a watch view with
+  its own context window, and the downgrade check made visible per agent.
+- Every gate rung falls back to **Claude Code's own row**, which is a real
+  answer and a better one than a blank. An empty render hides a task entirely,
+  which is almost never what anybody meant — so it is never emitted.
+
+`subagent_line_custom`, default `off`. Off is Claude Code's row, unchanged.
+
+---
+
+### v1.3.0 - build your own status line _(2026-09-04)_
+
+**Still on the unscoped `orc` package?** Do this once first — your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 — release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 — install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 — re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+The status line becomes **yours**. Three lines, each holding one to five parts
+from a catalogue ORC ships, each drawn through one of 35 shapes and restyled by
+you: two colours, a colour that follows the value, its own words, its own
+symbols, a stable width, and when it is allowed to appear at all.
+
+**It is off by default, and off is byte-identical to what shipped.** That is a
+test — nine states frozen glyph for glyph — not an intention.
+
+Compose it in **`orc ui` ▸ CLI Hook Interface**. A CLI half exists so the panel
+has something to run, and `orc statusline --help` says plainly that typing a
+three-line layout is worse than dragging one.
+
+```
+🚀 ORC v1.3.0 · Opus 5/high · CTX ████▊░░░░░ 47% · 5h 61%          main
+◐ orc · execution · agents 7 (2 running) · Dur 34m · MTok 312K
+cache ● ███████▊░░ 91% · $0.42 · wiki ◐ 14c
+```
+
+- **THE CLI COMPILES, THE HOOK RENDERS.** The layout you author is lowered into
+  a flat render program with every colour worked out in advance; the hook walks
+  it and resolves nothing. Three reasons, any one sufficient. Claude Code
+  debounces at 300 ms and **cancels** a script still running — and on Windows a
+  bare `node` start is 285 ms of that, so the hook has **about 15 ms**, and
+  resolving themes and ramps per keystroke is the wrong trade by four orders of
+  magnitude. Two ideas of what inheritance means would otherwise sit either side
+  of the one surface where you compare them. And a hook cannot refuse; it can
+  only fail silently or paint garbage, so validation has to happen where a
+  refusal is possible.
+- **The preview IS the bar.** `orc statusline preview` and the hook require the
+  SAME render module, so what the panel draws and what your terminal prints
+  cannot diverge — by construction, not by a test that would eventually drift.
+  All three degraded forms sit under it and are always visible: you cannot
+  design a plain-text fallback you cannot see.
+- **The illegal drop is made impossible.** A line may hold a part only if every
+  line above it holds at least one — so line 3 renders hatched and disabled with
+  the reason ON THE ZONE while line 2 is empty. Never a message after the fact.
+  Every drag has a keyboard path and a menu; a board only reachable by mouse is
+  a board a lot of people cannot use.
+- **A composed layout can be FASTER than the built-in one.** The compiler
+  records which readings a layout needs, and the hook reads nothing else.
+  Measured on the cold path: 346.7 ms for the built-in lines, **298.2 ms** for a
+  composed `minimal` — which is the difference between rendering and being
+  cancelled.
+- **Eight parts are REFUSED, each with the measurement.** `git status` is 53 ms
+  against 15 ms of headroom; three wiki numbers need a git walk PER DOCUMENT.
+  Reading a value that is not stored would have rendered a confident number
+  nobody measured, forever. `unknown` renders an em dash — **never `0`**, which
+  would say the thing was free.
+- **Three things a terminal cannot do, said plainly** rather than offered as a
+  picker that does nothing: the terminal owns the font size (bold reads bigger,
+  and a part gets visually larger by taking more cells), blinking is refused,
+  and icon-font symbols are not shipped because ORC cannot check for the font
+  and will not put an empty box on your bar.
+- **`orc doctor` gains three findings**, and only while the feature is armed — a
+  layout you built and never enabled is a draft, not a problem. An orphaned part
+  after an upgrade is REPORTED, never auto-repaired: which part replaces a
+  retired one is your decision.
+- **A fix that shipped with it:** the wiki freshness segment used to run
+  `git rev-list` on EVERY redraw, outside the throttle everything else rides in.
+  In a repo with a wiki that pushed the render past the cancel line, so a fast
+  typist got no status line at all while they typed.
+
+One config key, `statusline_custom`, default `off`. No key for a colour scheme —
+the layout carries its own — and none for the parts: those are a document, not a
+setting.
+
+---
+
+### v1.2.1 - the status line says what ORC is doing _(2026-09-04)_
+
+**Still on the unscoped `orc` package?** Do this once first — your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 — release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 — install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 — re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+v1.2.0 gave the status line a second row and it said which lanes had run. It
+could not say what any of them was doing *now* — which is the one thing you look
+down at a status bar to find out. This release puts the running phase in front
+of that row, gives each kind of phase its own small animated mark (the `orc-cli`
+lane-menu badge, keyed to the phase instead of the lane), and closes the row with
+the two facts a terminal should always carry: what the session has cost and which
+branch it is on.
+
+```
+🚀 ORC v1.2.1 - Opus 5/high · context (34%) · 5h 41% (2h13m) ↔ wk 12% · ucs 6% · wiki: fresh
+   ▰ status: quick · Q3 DO · agents 7 (2 running) · orc-extra: on · Dur 48m · MTok 412K · main
+```
+
+#### The phase is computed by the CLI and rendered by the hook
+
+`orc init` / `orc update` now stamps **`hooks/orc-lane-rails.json`** beside
+`hooks/orc-version.json`, built from the same `LANE_PHASES` / `LANE_OWN_PHASES`
+/ `LANE_TRACE` registries `orc lane phases` reads. The hook renders it and
+derives nothing — the Flow-stepper rule (`orc ui` v0.43.7) on a second surface.
+
+The hook cannot call the CLI: a status line re-renders on every keystroke, so a
+subprocess per render is not on the table. The alternative was a phase table
+hardcoded in the hook, which is a **second source of truth no lint could see**.
+The manifest is a registered contract token instead, plus three goldens: every
+phase has a label and a kind from the closed set, the rail names every traced
+lane **and no lane it does not**, and its role families are asserted against the
+trace hook's own `roleFamily()` **by source text** (the `OPUS5_BANDS` technique
+— the two live in different files, so no import can tie them).
+
+New read: **`orc lane rails [--json]`**, which prints the whole object.
+
+#### A phase the disk cannot prove is HIDDEN
+
+Four rungs, most recent line wins, and the floor is deterministic:
+
+1. the active run comes from `.current` — not "the newest file", which is a
+   different and wrong answer during a lane suspend, when two traces are live;
+2. a narrated trace verb **this lane's rail publishes** resolves the own-phase
+   (`Q3 DO`) — but only when it is later in the file than the edge below it, so
+   it can sharpen the answer and can never invent one;
+3. the trace hook's `PHASE-EDGE <family>` resolves the shared phase
+   (`execution`) with **zero model cooperation**;
+4. nothing, or a trace whose newest line is over 10 minutes old → **hidden**.
+
+**The cost is stated rather than papered over.** A phase that dispatches nothing
+and narrates nothing is invisible: `/orc-quick` `Q1 LOOK` and `Q2 ASK`, and every
+ask-the-user gate in every lane. Covering those would mean asking 24 spines to
+write a phase marker at phase open — the **remembered-not-dispatched** bet this
+repo has already lost five times (v0.32.0 narration, v0.49.5 hand-back, v0.53.2
+spend log, v0.54.0 journal, v1.0.0 W5 demotion). A `status:` that is right when
+the model is diligent and silently wrong when it is not is worse than one that is
+sometimes blank, because **a stale phase word gets believed** — the same
+reasoning as *unknown is not low* and *unknown is not zero*.
+
+Two more limits inherited and restated: a **continued** agent emits no
+PreToolUse/SubagentStop pair, so the skeleton is a floor and never a census; and
+`orc extra` runs its worker through Bash, so a foreign wave writes no `SPAWN` and
+resolves only through its narrated `EXTRA` verb, or hides.
+
+#### The animation is a liveness tell, not a progress bar
+
+Eight motif kinds — `look` · `ask` · `plan` · `do` · `check` · `ship` · `wait` ·
+`generic` — each one cell wide, each with an ASCII twin. A phase the kind table
+does not name gets `generic`, the honest sweep, **not a guess**.
+
+A status line is a **pull** surface: Claude Code re-renders it, ORC cannot. So
+the frame is picked off the wall clock. It advances while you type and while
+turns land, and it **freezes when the session is idle** — which is true, and is
+why frame 0 is designed as a still frame.
+
+- `ORC_STATUSLINE_MOTION=0` **removes** the motion rather than slowing it. A
+  frozen frame of a cycling animation is a bug that looks like a hang; the web
+  panel learned that at v0.44.0 and we are not learning it twice.
+- `ORC_STATUSLINE_ASCII=1` swaps the glyph set.
+
+#### `MTok` — MAIN token, and what it cannot see
+
+The tokens **this session's own turns** consumed, summed from the session
+transcript's `usage` blocks and read **incrementally** (only the bytes the file
+has grown by — a transcript reaches tens of megabytes and this loop runs every
+five seconds).
+
+**Claude Code records no token usage for a dispatched subagent** — v1.2.0
+verified that across every transcript on two machines — so an hour of Opus
+executors adds almost nothing here. `MTok` is what your conversation costs, not
+what a run costs; `orc usage report` and `/orc-budget` remain the truth for that.
+An unreadable transcript renders **`—`, never `0`**, because a zero would say the
+session was free.
+
+All four kinds are summed. That is a deliberate exception to `/orc-budget`'s
+*four kinds, never blended*, and it holds only because this is one cell on a
+status bar and not a report: any subset ORC picked would be a weighting **ORC
+invented**, which is worse. The ledger keeps all four apart regardless.
+
+#### The rest of the line
+
+- **The verdict word becomes the version, the ICON keeps the verdict.** The ⛔
+  branch still names every reason — a warning with no reason is an emoji. A
+  version ORC cannot read renders as plain `ORC`, never `ORC vnull`.
+- `34% ctx` → **`context (34%)`**.
+- `sess +6%` → **`ucs 6%`** (usage, current session), and it now **keeps its
+  slot at zero**: "nothing consumed yet" and "this build has no ucs segment" are
+  different facts. It is still a delta of an **account-wide** window.
+- **`Dur 48m`** labels the duration.
+- **The branch** comes from `.git/HEAD` with **no subprocess** — including the
+  `gitdir:` pointer file a worktree or submodule uses. Detached HEAD reads as
+  `@a1b2c3d`. Not a repository → the segment is absent, not empty.
+- **`lanes:` is replaced by `status:`.** The running lane is its first word, and
+  `orc stats` / `orc run list` still hold the session's whole history.
+
+#### The status line explains itself
+
+**`.claude/hooks/README.md`** ships next to the hook and documents every segment
+in Simplified Technical English (`bin/webui/i18n/TERMS.md` is the term list),
+including what each **absent** segment means — because a user who cannot find a
+segment needs to know whether it is broken or answering.
+
+#### Deliberately absent
+
+- **A config key.** A status line is display, and a hook cannot resolve a lane's
+  config anyway (it has no lane) — the caveat the `log_dir` and wiki segments
+  already carry. The two env seams exist for tests and terminals, and nothing in
+  ORC ever sets them.
+- **A second throttle.** Everything new rides in v1.2.0's one 5-second scan;
+  `ORC_STATUSLINE_SCAN_MS` stays the only seam over it.
+- **A `git` subprocess**, on a per-keystroke surface.
+- **A token estimate for dispatched subagents.** Claude Code records none, and a
+  fake measurement would be worse than none.
+- **An `orc ui` panel.** The statusline is not a panel surface; nothing in
+  `bin/webui/` moved.
+
+---
+
 ### v1.2.0 - a retry that cloned the agent, and a window you can watch empty _(2026-09-04)_
 
 **Still on the unscoped `orc` package?** Do this once first — your `orc upgrade`

package/README-id.md

@@ -619,6 +619,50 @@ Bacalah sebagai catatan putaran itu, bukan sebagai audit terkini:
 **Riwayat lengkap: [CHANGELOG.md](CHANGELOG.md)** — atau `orc changelog`, yang
 hanya mencetak yang lebih baru dari versi yang Anda punya.
 
+### v1.3.0 - bangun sendiri baris status Anda _(04-09-2026)_
+
+**Masih memakai paket `orc` yang tanpa awalan?** Lakukan ini sekali dulu —
+`orc upgrade` Anda adalah versi sebelum v0.56.0 dan tidak dapat memasang
+dirinya sendiri.
+
+- **Langkah 1 — lepaskan perintahnya dari paket lama:** `npm uninstall -g orc`
+- **Langkah 2 — pasang paket saat ini:** `npm i -g @azure-id/orc`
+- **Langkah 3 — terapkan lagi ke proyek Anda:** `orc update`
+
+**Jangan pakai `npm i -g -f`.**
+
+Baris status kini **milik Anda**. Tiga baris, tiap baris memuat satu sampai lima
+bagian dari katalog yang dikirim ORC, tiap bagian digambar lewat salah satu dari
+35 bentuk dan Anda beri gaya sendiri: dua warna, warna yang mengikuti nilai,
+kata-katanya sendiri, simbolnya sendiri, lebar yang tetap, dan kapan bagian itu
+boleh muncul.
+
+**Fitur ini mati secara bawaan, dan saat mati hasilnya sama persis byte per byte
+dengan sebelumnya.** Itu sebuah tes — sembilan keadaan dibekukan simbol demi
+simbol — bukan sekadar niat.
+
+Susun di **`orc ui` ▸ CLI Hook Interface**.
+
+- **CLI YANG MENYUSUN, HOOK YANG MENGGAMBAR.** Tata letak Anda diturunkan jadi
+  daftar instruksi datar dengan setiap warna sudah dihitung; hook menjalankannya
+  dan tidak memutuskan apa pun. Claude Code menggambar ulang paling cepat tiap
+  300 md dan **membatalkan** skrip yang masih berjalan — di Windows memulai
+  `node` saja sudah 285 md dari jatah itu, jadi hook hanya punya sekitar 15 md.
+- **Pratinjau ITU bilahnya.** Pratinjau dan hook memakai modul penggambar yang
+  SAMA, jadi keduanya tidak mungkin berbeda.
+- **Peletakan yang tidak sah dibuat MUSTAHIL.** Sebuah baris hanya boleh memuat
+  bagian jika setiap baris di atasnya sudah terisi. Setiap seret juga punya
+  jalur papan tombol dan menu.
+- **Tata letak susunan Anda bisa LEBIH CEPAT** daripada bawaan: 346,7 md untuk
+  bawaan, **298,2 md** untuk `minimal` susunan sendiri.
+- **Delapan bagian DITOLAK**, tiap-tiap dengan hasil pengukurannya. Nilai yang
+  tidak dapat dihitung tampil sebagai tanda pisah — **bukan `0`**, yang berarti
+  gratis.
+
+**Rincian lengkap: [`guides/status-line.md`](guides/status-line.md).**
+
+---
+
 ### v1.0.0 - konfigurasi, fase, dan panggilan berhenti jadi prosa _(30-08-2026)_
 
 **Masih memakai paket `orc` yang tanpa awalan?** Lakukan ini sekali dulu —

package/README.md

@@ -14,7 +14,7 @@
 ![Dependencies](https://img.shields.io/badge/dependencies-zero-lightgrey.svg?style=for-the-badge)
 ![GitHub stars](https://img.shields.io/github/stars/azure-id/orc?style=for-the-badge&color=yellow)
 
-**Latest: v1.2.0** · updated 2026-09-04 · [full changelog](CHANGELOG.md)
+**Latest: v1.4.0** · updated 2026-09-04 · [full changelog](CHANGELOG.md)
 
 **On npm: [`@azure-id/orc`](https://www.npmjs.com/package/@azure-id/orc)** — `npm i -g @azure-id/orc`
 
@@ -575,7 +575,7 @@ a current audit: [EVAL-REPORT.md](EVAL-REPORT.md).
 **Full history: [CHANGELOG.md](CHANGELOG.md)** — or `orc changelog`, which prints
 only what is newer than the version you have.
 
-### v1.2.0 - a retry that cloned the agent, and a window you can watch empty _(2026-09-04)_
+### v1.4.0 - the agent panel, and the number that was missing _(2026-09-04)_
 
 **Still on the unscoped `orc` package?** Do this once first — your `orc upgrade`
 is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
@@ -587,86 +587,62 @@ the top of this file.
 
 **Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
 
-A Task error does not kill the subagent behind it. Every lane's retry rule
-assumed it did. 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 trace hook had recorded every one of them. Nothing had ever read it.
-
-- **`orc run inflight`** — the one reader of the pending sidecar the trace hook
-  has written on every `SPAWN` since v0.34. `0` clear · `1` in-flight ·
-  `2` unknown. Every lane that re-dispatches now asks it first.
-- **A re-dispatch is refused over a live attempt.** New registered contract
-  token, `_shared/return-validation.md` **§0**, placed above every existing rule
-  because every one of them ends in "re-dispatch". The refusal names the agent,
-  the task and its age, and always offers "dispatch anyway" — never as the
-  default.
-- **Exit 2 refuses, and it is the one place in ORC where an absent reading
-  blocks.** `orc usage check` exit 2 never stops a run; an UNCHECKABLE pact
-  never raises an exit code. It inverts here because the two errors are not the
-  same size: a wrongly-refused dispatch costs one question, a wrongly-issued one
-  costs a second Opus agent for an hour.
-- **An interrupted turn is UNKNOWN, never FAILED.** A usage limit, an API error
-  or a `Ctrl+C` between a dispatch and its return says nothing about the agent.
-  Classifying that as a failure is what made the incident compound: it paid
-  twice, hit the limit sooner, and retried again.
-- **Unknown is not zero.** A missing sidecar, an unreadable one, records older
-  than six hours, or a sidecar that disagrees with the trace's own SPAWN/RETURN
-  balance all read `unknown` — never `clear`.
-- **The honest limit is stated, not papered over.** It cannot see an *ad-hoc*
-  dispatch (`/orc-quick` recon, dispatched by 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, and a lane must never read `clear` as proof one
-  finished.
-
-The other half — **you can now watch the window empty**:
-
-- **`orc usage report`** — 5-hour, 7-day and context in one place, plus the line
-  the snapshot could never give you: **"This session has consumed 59% of the
-  5-hour window and is still counting"**, with the caveat that other sessions on
-  the same account share that window.
-- **A window reset mid-session is not a refund.** The statusline keeps a
-  per-session ledger beside `usage.json` — raw numbers only, never a computed
-  word — and banks what was spent before a reset so the running total keeps
-  counting across the boundary. A new session re-baselines.
-- **The statusline grew a second line, and a `sess +X%` segment on the first.**
+The second board. Claude Code renders a custom row for every subagent in the
+agent panel, and that surface is ORC's exact domain: one row per dispatched
+agent, live, while it runs.
 
 ```
-🚀 ORC-boosted Opus 5/high · 22% ctx · 5h 69% (1h30m) ↔ wk 30% · sess +59%
-   agents 4 (1 running) · orc-extra: on · lanes: mini, quick · 41m
+● orc-executor-opus-5-low   O5/low   84K   ███▎░░░░  42%   for 17m
+✓ orc-reviewer-opus-5-med   O5/med   31K   █▌░░░░░░  16%   for  4m
 ```
 
-  `agents` counts what this session spawned and **never hides what is still
-  running** — the thing that was invisible while three agents worked on one
-  task. Dispatches are attributed by the trace's **own line timestamps**, not
-  the file's mtime, so a run that was already going when the session started is
-  not counted twice. A lane is named only if it actually dispatched, and
-  `lanes: none yet` keeps its slot rather than vanishing. The scan is throttled
-  to once every 5s, because a statusline re-renders on every keystroke.
-
-- **Top 5 by measured wall time, and it says that is what it is.** Claude Code
-  records **no token usage for a dispatched subagent** — `isSidechain` is never
-  set and no sidechain message carries a usage block — so a per-agent token
-  figure cannot be measured. Every Claude row reports `tokens: null` and the
-  reason, **never `0`**, which would tell you the work was free. Only
-  `orc extra` foreign workers report real four-kind vectors, and those rows say
-  so. Inventing the rest would be the same class of bug as the one above.
-
-**Nothing here is on by default that was not already.** `usage_gate` still ships
-`off`. The in-flight guard adds one free CLI read before a re-dispatch — it
-changes no dispatch that was already correct.
-
-**Full entry: [CHANGELOG.md](CHANGELOG.md).**
-
-<details>
-<summary>Earlier releases</summary>
-
-- **v1.1.0 - the wait, and a window ORC can finally see — _(2026-08-31)_**
-- **v1.0.0 - config, phases and calls stop being prose — _(2026-08-30)_**
-
-Full bodies for every one of these are in [CHANGELOG.md](CHANGELOG.md).
-
-</details>
+**AND IT ANSWERS A QUESTION v1.2.0 SAID COULD NOT BE ANSWERED.** That release
+established that Claude Code records no token usage for a dispatched subagent —
+`isSidechain` is never set, no sidechain message carries a usage block, verified
+across every transcript on two machines — so `orc usage report` has reported
+`tokens: null` for every Claude row ever since, and said why.
+
+That is still true **of the transcript**. It is not true of the agent panel,
+which carries `tokenCount` per task along with the resolved `model` and
+`effort`. So the hook writes down what it is handed, and `orc usage report`
+reads it.
+
+- **It is a FLOOR, and it is labelled one everywhere it appears.** The hook sees
+  a task only while it is in the panel: an agent that started and finished
+  between two renders is never seen, and a count read just before an agent
+  finished is short by whatever came after. `not-seen` means exactly that and
+  is never `0`. A floor reported as a total would be the same class of lie as a
+  zero reported for an unknown.
+- **The record is written even with the board OFF.** It is not part of the
+  display feature — it is a measurement Claude Code hands over either way, and
+  throwing it out because a display setting is off would be the wrong trade by a
+  wide margin. `orc init` and `orc update` wire `subagentStatusLine` for that
+  reason alone, and never clobber one you already have.
+- **A count can only go up**, so a lower reading is a stale one and never
+  overwrites a higher one.
+- **The model and effort are OBSERVED.** ORC's downgrade check has two readings
+  — one derived from the agent's name, one the agent reports about itself. This
+  is the third, and the only one nobody had to be trusted for.
+
+**ONE COMPILER, TWO BOARDS.** The second board reuses the compiler, the render
+program, every shape, every glyph set, the colour model, the validator and the
+gate ladder. What differs is a component set, three filenames and a config key —
+a table, not a fork. A test asserts there is exactly one compiler and that the
+new hook grew no renderer of its own, because that is the cheap mistake this
+whole design exists to avoid.
+
+- **A component belongs to one board**, and the other refuses it by name with
+  the board it belongs to. Two catalogues would be two lists somebody has to
+  keep in step; this is one catalogue with a column.
+- **A subagent row is one line by construction** — Claude Code renders one per
+  task — so the three-line board and its dense-prefix rule simply do not apply.
+- **Three presets**: what the agent is and what it has cost, a watch view with
+  its own context window, and the downgrade check made visible per agent.
+- Every gate rung falls back to **Claude Code's own row**, which is a real
+  answer and a better one than a blank. An empty render hides a task entirely,
+  which is almost never what anybody meant — so it is never emitted.
+
+`subagent_line_custom`, default `off`. Off is Claude Code's row, unchanged.
 
 ---