@azure-id/orc 1.2.1 → 1.4.1

package/bin/webui/js/panels/overview.js

@@ -64,6 +64,13 @@ const FINDING_ROUTE = {
   // rather than left to DEFAULT_FINDING_ROUTE because the CTA is specific --
   // a reader who sees "lane config drifted" should be told which button.
   "lane-keys-drifted": { panel: "maintenance", cta: "overview.item.laneKeysDrifted.cta" },
+  // v1.3.0. The rule again, and cleanly: every one of these is cleared on the
+  // CLI Hook Interface panel — the board is where an orphaned component is
+  // removed, the caution strip is where an invalid layout is named, and the
+  // Rebuild button is where a stale compile is fixed.
+  "statusline-layout-orphaned": { panel: "hookui", cta: "overview.item.statuslineOrphaned.cta" },
+  "statusline-layout-invalid": { panel: "hookui", cta: "overview.item.statuslineInvalid.cta" },
+  "statusline-layout-unreadable": { panel: "hookui", cta: "overview.item.statuslineUnreadable.cta" },
 };
 const DEFAULT_FINDING_ROUTE = { panel: "maintenance", cta: "overview.item.doctor.cta" };
 const findingRoute = (id) => FINDING_ROUTE[id] || DEFAULT_FINDING_ROUTE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-id/orc",
-  "version": "1.2.1",
+  "version": "1.4.1",
   "description": "ORC — an orchestrator skill constellation for Claude Code: intake, planning, scored parallel subagents, code-pattern matching, review, verify, ship, plus a project knowledge-base wiki.",
   "bin": {
     "orc": "bin/cli.js"

package/templates/hooks/README.md

@@ -188,6 +188,69 @@ The branch you are on. A detached HEAD shows as `@a1b2c3d`.
 
 ---
 
+## Your own status line
+
+You can build your own instead of this one. It is **off** by default, and while
+it is off this file describes exactly what you see.
+
+Open the panel:
+
+```
+orc ui
+```
+
+Then go to **CLI Hook Interface**. You put components into three lines and drag
+them where you want them. One rule decides where a component may go:
+
+> A line may hold a component only if every line above it holds at least one.
+
+So line 1 must hold something before line 2 can, and line 2 before line 3. Each
+line holds at most five components. The panel will not let you make an illegal
+move, and it tells you why.
+
+Every component can be changed: its words, its colour, its shape, how wide it
+is, and when it is allowed to disappear.
+
+**Three things a terminal cannot do**, said plainly so you do not look for them:
+
+| You may want | What you get |
+|---|---|
+| A bigger font | The terminal owns the font size. Use **bold**, or make a component wider — a bar at width 12 is a big object. |
+| A blinking part | Refused. Half of terminals turn it off, and no part of a status line needs it. |
+| Icon-font symbols | Not shipped. They need a font we cannot check for, and they draw as empty boxes without it. |
+
+There is a command-line half (`orc statusline`). It exists so the panel has
+something to run. Building a three-line layout by typing flags is harder than
+dragging, so the panel is the recommended way.
+
+---
+
+## The agent panel
+
+When ORC sends work to a subagent, Claude Code shows a row for it in the agent
+panel. ORC can draw that row too — `orc ui` ▸ **CLI Hook Interface**, then pick
+the **subagent** board.
+
+```
+● orc-executor-opus-5-low   O5/low   84K   ███▎░░░░  42%   for 17m
+```
+
+It is off by default, and while it is off you see Claude Code's own row.
+
+**One thing here runs whether the row is on or off**, and it is worth knowing
+about. Claude Code tells this hook **how many tokens each agent has used**.
+Nothing else tells ORC that: the conversation file records no token use for a
+subagent at all. So ORC writes down what the panel reports, and `orc usage
+report` shows it.
+
+**It is a floor, not a total.** ORC only sees an agent while it is in the panel.
+An agent that starts and ends between two redraws is never seen, and a number
+read just before an agent ended is short by whatever came after. `orc usage
+report` says so on every one of these numbers. It never shows `0` for something
+it did not see.
+
+---
+
 ## For maintainers
 
 - The hook is `orc-statusline.js`. `orc init` installs it and wires it into
@@ -195,8 +258,23 @@ The branch you are on. A detached HEAD shows as `@a1b2c3d`.
 - The phase list is **not** in the hook. `orc init` and `orc update` write it to
   `hooks/orc-lane-rails.json` from the CLI registries. Run `orc lane rails` to
   read it. The hook renders that file and decides nothing about it.
-- Line 2 reads the disk once every 5 seconds and caches the answer, because a
+- The hook reads the disk once every 5 seconds and caches the answer, because a
   status line redraws on every keystroke. `MTok` reads only the new bytes of the
-  transcript.
+  transcript. The wiki part joined that scan in v1.3.0: it used to start a `git`
+  process on every redraw.
 - `ORC_STATUSLINE_SCAN_MS` is the one seam over that budget. It exists for
   tests. Nothing in ORC sets it.
+- **The budget is small.** Claude Code waits 300 ms between redraws and stops a
+  script that is still running when the next redraw starts. On Windows, starting
+  `node` alone takes about 285 ms of that. So the hook has about 15 ms to do all
+  its work. This is why nothing here starts a process, and why every answer is
+  cached.
+- The custom layout is COMPILED. `orc statusline` turns what you composed into a
+  flat render program (`statusline-compiled.json`) with every colour worked out
+  in advance, and the hook only walks it. The hook never reads the layout you
+  authored. If the compiled file is missing, stale, or does not pass a cheap
+  shape check, the hook silently renders the shipped lines instead and
+  `orc doctor` names the reason.
+- The cache file is `.claude/orc/usage-session.json`. The hook reads it once and
+  writes it once, after the text is ready. It stores raw numbers only — never a
+  word like `fresh` or `STALE`, which is computed each time it is shown.