@azure-id/orc 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -10,6 +10,151 @@ Format: `### v<version> — <title> _(<date>)_`.
 
 ---
 
+### 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.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.2.1** · 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.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
@@ -587,80 +587,64 @@ 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 line arrived in v1.2.0 saying which lanes had run. It could not say
+what any of them was doing *now*. This release puts the running phase in front —
+with a small animated mark per kind of phase, borrowed from `orc-cli`'s lane
+menu — and finishes the line with the two facts a terminal should always carry:
+what the session has cost, and which branch it is on.
 
 ```
-🚀 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 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
 ```
 
-  `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.
+- **The phase is CLI-computed and rendered, never derived.** `orc init` /
+  `orc update` stamps `hooks/orc-lane-rails.json` from the same registries
+  `orc lane phases` reads; the hook holds no idea of its own about what ORC's
+  phases are. Inspect it with the new `orc lane rails [--json]`. A second phase
+  table in a hook would be the Flow-stepper failure on a second surface, and no
+  lint could see it — so it is a registered contract token instead.
+- **A phase the disk cannot prove is HIDDEN.** The floor is the trace hook's
+  own `PHASE-EDGE`, written with zero model cooperation; a narrated verb the
+  lane's rail publishes may only *refine* it, never invent one. The cost is
+  stated rather than papered over: a phase that dispatches nothing and narrates
+  nothing — `/orc-quick` `Q1 LOOK`, `Q2 ASK`, every ask-the-user gate — shows
+  no segment at all. **Asking 24 spines to write a phase marker would have
+  covered those, and it is the remembered-not-dispatched bet this repo has
+  already lost five times.** A stale phase word gets believed.
+- **The animation is a liveness tell, not a progress bar.** A statusline is a
+  pull surface, so the frame comes off the wall clock: it moves while you type
+  and while ORC works, and freezes when the session is idle. `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), and `ORC_STATUSLINE_ASCII=1`
+  swaps in the ASCII twin every motif ships with.
+- **`MTok` — MAIN token — is honest about what it cannot see.** All four token
+  kinds summed, read incrementally from the session transcript. **Claude Code
+  records no token usage for a dispatched subagent**, so an hour of Opus
+  executors adds almost nothing: this is your conversation's cost, not the
+  run's. Unreadable renders `—`, **never `0`**, which would say the session was
+  free. `orc usage report` and `/orc-budget` remain the four-kind truth.
+- **The rest of the line.** The verdict WORD becomes the installed version and
+  the ICON keeps the verdict — the ⛔ branch still names every reason, because a
+  warning with no reason is an emoji. `ctx` → `context (N%)`. `sess +X%` → `ucs
+  X%`, which now keeps its slot at zero. `Dur` labels the duration, and the
+  branch comes off `.git/HEAD` with **no subprocess** on a per-keystroke
+  surface.
+- **`lanes:` is replaced by `status:`.** The running lane is its first word;
+  `orc stats` and `orc run list` still hold the session's whole history.
+- **The status line now explains itself.** `.claude/hooks/README.md` documents
+  every segment in Simplified Technical English, including what each absent
+  segment means.
+
+Everything rides in the one 5-second scan v1.2.0 already added. No new config
+key — a status line is display, and a hook cannot resolve a lane's config anyway.
 
 **Full entry: [CHANGELOG.md](CHANGELOG.md).**
 
 <details>
 <summary>Earlier releases</summary>
 
+- **v1.2.0 - a retry that cloned the agent, and a window you can watch empty — _(2026-09-04)_**
 - **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)_**
 

package/bin/cli.js

@@ -220,6 +220,16 @@ function installGuards(claudeDir) {
       JSON.stringify({ version: currentVersion() }) + "\n"
     );
   } catch (_) {}
+  // The statusline's phase rail (v1.2.1). Regenerated every install from the
+  // CLI's own registries, so the hook renders a phase list it never derives.
+  // Same fail-silent contract: a missing manifest hides the `status:` segment,
+  // it never breaks a render.
+  try {
+    fs.writeFileSync(
+      path.join(hooksDest, "orc-lane-rails.json"),
+      JSON.stringify(laneRailsManifest()) + "\n"
+    );
+  } catch (_) {}
 
   const guardCmd = nodeCmd(path.join(hooksDest, "orc-effort-guard.js"));
   const statusCmd = nodeCmd(path.join(hooksDest, "orc-statusline.js"));
@@ -346,6 +356,7 @@ function shippedFootprint() {
   for (const rel of listSrcRel(SRC_AGENTS)) files.push("agents/" + rel);
   for (const rel of listSrcRel(SRC_HOOKS)) files.push("hooks/" + rel);
   files.push("hooks/orc-version.json"); // generated by installGuards, ORC-owned
+  files.push("hooks/orc-lane-rails.json"); // generated by installGuards, ORC-owned
   return files;
 }
 
@@ -4089,6 +4100,150 @@ function lanePhaseRows(lane) {
   return rows;
 }
 
+// ---------------------------------------------------------------------------
+// The STATUSLINE RAIL MANIFEST (v1.2.1)
+//
+// `templates/hooks/orc-statusline.js` shows which phase an ORC run is in. It
+// cannot call this CLI: a statusline re-renders on every keystroke, so a
+// subprocess per render is not on the table. It also must never hold its own
+// idea of what the phases are — that is the Flow-stepper failure (`orc ui`
+// v0.43.7) applied to a second surface, and a second phase table is drift no
+// lint could see.
+//
+// So the CLI COMPUTES and the hook RENDERS: `orc init` / `orc update` writes
+// `hooks/orc-lane-rails.json` from the registries below, exactly the way
+// `hooks/orc-version.json` is stamped at install time.
+//
+// FRAMES ARE NOT IN HERE. The glyphs live in the hook, because they are
+// presentation: a motif change must not need a reinstall. What ships is the
+// KIND — a closed word the hook maps to a frame set.
+// ---------------------------------------------------------------------------
+
+// A phase's motif kind. The set is CLOSED, and a phase this table does not name
+// gets `generic` — the honest sweep, not a guess. Ported in spirit from
+// orc-cli's motifs.js, keyed on the PHASE rather than the lane: the lane name is
+// already the first word of the statusline's `status:` segment, so the glyph is
+// free to say what ORC is DOING.
+const PHASE_KINDS = ["look", "ask", "plan", "do", "check", "ship", "wait", "generic"];
+const PHASE_KIND = {
+  // reading, scanning, gathering evidence
+  preflight: "look",
+  trace: "look",
+  "wiki-consult": "look",
+  "analyst-gates": "look",
+  "house-rules": "look",
+  analysis: "look",
+  combine: "look",
+  // waiting on the user
+  intake: "ask",
+  // deciding what to do and in what order
+  planning: "plan",
+  "plan-handoff": "plan",
+  "wave-grouping": "plan",
+  scoring: "plan",
+  // executors running
+  execution: "do",
+  // grading what came back
+  review: "check",
+  security: "check",
+  "security-checklist": "check",
+  verify: "check",
+  testgen: "check",
+  "mock-example": "check",
+  "ultra-gate": "check",
+  // handing it over
+  ship: "ship",
+  summary: "ship",
+  // stopped on purpose
+  "stop-resume": "wait",
+};
+
+// A word in an own-phase heading that decides its kind. Checked in order, so
+// the first match wins; no match falls through to `generic`. This is how a
+// lane's own pipeline (`Q1 LOOK`, `D4 DRAFT`, `C6 ADVISE`) gets a motif without
+// a hand-maintained row per phase per lane.
+const OWN_PHASE_KIND_WORDS = [
+  [/\b(ask|question|intake|interview|frame|scope|choose|pick|gate)\b/i, "ask"],
+  [/\b(look|preflight|read|scan|ingest|evidence|load|context|recon|harvest)\b/i, "look"],
+  [/\b(plan|outline|cluster|shape|diverge|converge|order|batch|wave)\b/i, "plan"],
+  [/\b(do|write|build|execute|implement|draft|generate|dispatch|compile)\b/i, "do"],
+  [/\b(check|review|verify|judge|challenge|stress|grade|lint|audit|conserv)\b/i, "check"],
+  [/\b(ship|finish|exit|deliver|hand|summar|report|card|record)\b/i, "ship"],
+  [/\b(wait|stop|resume|pause|suspend)\b/i, "wait"],
+];
+
+// The display label for one phase. 18 visible chars, because line 2 of the
+// statusline already carries five other segments.
+//
+// A shared phase is its own id — those ids ARE the words ORC uses everywhere
+// else, and renaming them for a status bar would invent a second vocabulary.
+// An own phase is its heading up to the first bracket or dash, which is what
+// turns `## Q1 — LOOK (silent — no questions here)` into `Q1 LOOK`.
+function railLabel(row) {
+  if (!row.heading) return String(row.id).slice(0, 18);
+  let s = String(row.heading).replace(/^#+\s*/, "");
+  s = s.split(/\s+[—–-]\s+|\s*\(/)[0].trim();
+  // A heading whose whole first clause is just the code (`## C6 — Advise`)
+  // loses the only interesting word, so keep the second clause too when the
+  // first is a bare code.
+  if (/^[A-Za-z]{1,2}\d+[a-z]?$/.test(s)) {
+    const rest = String(row.heading)
+      .replace(/^#+\s*/, "")
+      .slice(s.length)
+      .replace(/^\s*[—–-]\s*/, "")
+      .split(/\s*\(/)[0]
+      .trim();
+    if (rest) s = s + " " + rest;
+  }
+  s = s.replace(/\s+/g, " ").trim();
+  if (s.length <= 18) return s;
+  // Cut at a word boundary. `D2 Supporting docu` is a typo the reader has to
+  // decode; `D2 Supporting` is a label.
+  const cut = s.slice(0, 18);
+  const sp = cut.lastIndexOf(" ");
+  return (sp > 3 ? cut.slice(0, sp) : cut).trim();
+}
+
+function railKind(row) {
+  if (PHASE_KIND[row.id]) return PHASE_KIND[row.id];
+  const hay = `${row.id} ${row.heading || ""}`;
+  for (const [re, kind] of OWN_PHASE_KIND_WORDS) if (re.test(hay)) return kind;
+  return "generic";
+}
+
+// The role families `templates/hooks/orc-trace.js` writes as `PHASE-EDGE <fam>`.
+// This is a MIRROR of that hook's `roleFamily()`, and it is the one new drift
+// surface this feature adds — a golden test compares the two by source text,
+// the way the `OPUS5_BANDS` alias is asserted.
+const TRACE_FAMILIES = ["combine", "analysis", "planning", "execution", "review", "verify", "testgen", "ultra-gate"];
+
+// The whole object, deterministic from the registries above. `--json is not a
+// summary`: this is what the file holds and what `orc lane rails` prints.
+function laneRailsManifest() {
+  const lanes = {};
+  for (const lane of LANE_NAMES) {
+    const t = LANE_TRACE[lane];
+    // A lane that opens no run writes no trace file, so no `run-<lane>-…` name
+    // can ever name it and the resolver could never reach the row. Omitting it
+    // is an answer, not a gap.
+    if (!t || !t.token) continue;
+    const rows = [];
+    for (const p of lanePhaseRows(lane))
+      rows.push({ id: p.id, label: railLabel(p), kind: railKind(p), verbs: [] });
+    for (const p of LANE_OWN_PHASES[lane] || [])
+      rows.push({
+        id: p.id,
+        label: railLabel(p),
+        kind: railKind(p),
+        verbs: Array.isArray(p.trace_verbs) ? p.trace_verbs.slice() : [],
+      });
+    lanes[t.token] = { lane, tier: t.tier, phases: rows };
+  }
+  const families = {};
+  for (const f of TRACE_FAMILIES) families[f] = { label: f, kind: PHASE_KIND[f] || "generic" };
+  return { version: currentVersion(), kinds: PHASE_KINDS, families, lanes };
+}
+
 // \`orc lane phases <lane>\` / \`--all\`. Exit 0 in every state; 2 for an unknown
 // lane or no argument — the \`orc lane calls\` contract, unchanged.
 //
@@ -4284,6 +4439,33 @@ function laneConfigCmd(lane, claudeDir) {
 }
 
 
+// `orc lane rails [--json]` — the statusline's phase rail, exactly as it is
+// written to `hooks/orc-lane-rails.json` at install. It exists so the manifest
+// is inspectable without opening a hook directory, and so a golden test reads
+// the same object the hook does. Exit 0 in every state.
+//
+// `--json is not a summary`: this prints the WHOLE object, not a count of it.
+function laneRailsCmd() {
+  const m = laneRailsManifest();
+  if (wantsJson()) {
+    emitJson(Object.assign({ ok: true }, m));
+    return 0;
+  }
+  console.log(`\nORC statusline rails  ${ui.color.gray("v" + m.version)}`);
+  console.log(ui.color.gray(`  kinds     ${m.kinds.join(", ")}`));
+  console.log(ui.color.gray(`  families  ${Object.keys(m.families).join(", ")}`));
+  for (const [token, row] of Object.entries(m.lanes)) {
+    console.log(`\n  ${ui.color.bold(token)}  ${ui.color.gray(row.lane + " · " + row.tier)}`);
+    for (const p of row.phases)
+      console.log(
+        "    " + String(p.kind).padEnd(8) + " " + String(p.label).padEnd(20) +
+          ui.color.gray(p.verbs.length ? "verbs: " + p.verbs.join(", ") : "")
+      );
+  }
+  console.log("");
+  return 0;
+}
+
 // `orc lane` — the noun. `list` and `config` today; `phases` lands in W12 and
 // `calls` in W10.
 function lane() {
@@ -4299,13 +4481,16 @@ function lane() {
       process.exit(laneCallsCmd(pos[2], claudeDir));
     case "phases":
       process.exit(lanePhasesCmd(pos[2], claudeDir));
+    case "rails":
+      process.exit(laneRailsCmd());
     default:
       console.error(
         `Unknown: orc lane ${pos[1]}\n` +
           "Usage: orc lane list [--json]\n" +
           "       orc lane config <lane> [--json]\n" +
           "       orc lane calls <lane> [--json]   |   orc lane calls --all [--json]\n" +
-          "       orc lane phases <lane> [--json]  |   orc lane phases --all [--json]"
+          "       orc lane phases <lane> [--json]  |   orc lane phases --all [--json]"  +
+          "\n       orc lane rails [--json]"
       );
       process.exit(2);
   }

package/bin/verify-contracts.js

@@ -411,6 +411,7 @@ const CONTRACTS = [
     token: "orc run inflight",
     binFiles: ["bin/cli.js"],
     files: [
+      "hooks/README.md",
       "skills/_shared/return-validation.md",
       "skills/_shared/phases/execution.md",
       "skills/orc/SKILL.md",
@@ -842,6 +843,10 @@ const CONTRACTS = [
     files: [
       "agents/orc-trace-writer-haiku-4-5.md",
       "hooks/orc-trace.js",
+      // v1.2.1: the statusline READS the pointer to decide which run `status:`
+      // is about. "The newest file" would be a different, wrong answer during
+      // a lane suspend, when two traces are live and only one is the run.
+      "hooks/orc-statusline.js",
       "skills/_shared/lane-suspend.md",
       "skills/context-combiner/SKILL.md",
       "skills/orc-aftermath/SKILL.md",
@@ -905,6 +910,18 @@ const CONTRACTS = [
       "skills/_shared/phases/trace.md",
     ],
   },
+  {
+    // v1.2.1 — the statusline's phase rail. The CLI COMPUTES the phase list
+    // (labels, order, motif kind) and stamps it at install; the hook RENDERS it
+    // and derives nothing, the same way `orc ui` renders the Flow stepper. The
+    // two halves live in two files, so a rename of the manifest silently blanks
+    // `status:` unless it fails here.
+    name: "statusline phase rail (v1.2.1 — orc-lane-rails.json)",
+    token: "orc-lane-rails.json",
+    binFiles: ["bin/cli.js"],
+    files: [
+      "hooks/README.md","hooks/orc-statusline.js"],
+  },
   {
     // v0.32.0: the hook's zero-model-dependence phase segmentation. Producer
     // (the hook) and both consumers (retro skill + its miner) must agree on the
@@ -922,6 +939,11 @@ const CONTRACTS = [
       // v0.42.0: the combiner is segmented as its own PHASE-EDGE family INSIDE the
       // analyze trace — the reason it needs no lane of its own.
       "skills/context-combiner/SKILL.md",
+      // v1.2.1: the statusline READS these edges to render `status:`. It is the
+      // deterministic floor under that segment — the model-narrated verb can
+      // only refine it — so a rename of this verb would silently blank the one
+      // segment on line 2 that changes minute to minute.
+      "hooks/orc-statusline.js",
     ],
   },
   {
@@ -946,6 +968,7 @@ const CONTRACTS = [
     token: "orc wiki sync",
     binFiles: ["bin/cli.js"],
     files: [
+      "hooks/README.md",
       "agents/orc-wiki-scanner-opus-4-8-high.md",
       "agents/orc-wiki-scanner-opus-5-med.md",
       "agents/orc-wiki-scanner-sonnet-5-high.md",
@@ -985,6 +1008,7 @@ const CONTRACTS = [
     name: "wiki UNREGISTERED state (v0.18.0 — docs without a manifest ≠ no wiki; sync, never re-scan)",
     token: "UNREGISTERED",
     files: [
+      "hooks/README.md",
       "hooks/orc-statusline.js",
       "skills/orc-wiki/README.md",
       "skills/orc-wiki/references/phases/phase-0.md",
@@ -1489,6 +1513,7 @@ const CONTRACTS = [
     name: "wiki freshness tier enum (v0.11.0 — FRESH/AGING/STALE, computed on read)",
     token: "AGING",
     files: [
+      "hooks/README.md",
       "hooks/orc-statusline.js",
       "skills/_shared/gotchas.md",
       "skills/_shared/interview.md",