@azure-id/orc 1.8.1 → 1.8.2

package/bin/verify-contracts.js

@@ -2722,6 +2722,144 @@ const CONTRACTS = [
       "skills/orc-mini/SKILL.md",
     ],
   },
+  // ── v1.8.2 W3 — the delivery flags (D1 · D2 · D3 · D5) ────────────────
+  {
+    // The slice call. A rename must reach the contract, the phase file that
+    // makes the call, the hook that dedupes against what it delivered, and the
+    // CLI that answers it.
+    name: "graph slice view (v1.8.2 — ctx --for-slice, the OUTSIDE view of a declared file)",
+    token: "--for-slice",
+    files: ["hooks/orc-graph-hook.js", "skills/_shared/code-graph.md", "skills/_shared/phases/execution.md"],
+    binFiles: ["bin/cli.js", "bin/graph-query.js"],
+  },
+  {
+    // The card and the range in one call. Pinned WITH its argument, because a
+    // bare `--source` is also `orc doc`'s own flag.
+    name: "graph source block (v1.8.2 — ctx --source [N], charged to the same budget)",
+    token: "--source [N]",
+    files: ["skills/_shared/code-graph.md", "skills/_shared/read-ladder.md"],
+    binFiles: ["bin/cli.js"],
+  },
+  {
+    // One call at a wave close. The two-call form still works; the lane text
+    // uses this one, so the flag has to exist wherever the text says it does.
+    name: "graph one-call update (v1.8.2 — update --notes-pending)",
+    token: "--notes-pending",
+    files: ["skills/_shared/code-graph.md", "skills/_shared/phases/execution.md"],
+    binFiles: ["bin/cli.js"],
+  },
+  {
+    // The fourth value of `code_graph_hooks`. It arms the whole-file READ hint
+    // and nothing else, and it is off until somebody types it.
+    name: "graph read hint (v1.8.2 — code_graph_hooks: on,read)",
+    token: "on,read",
+    files: ["hooks/orc-graph-hook.js", "hooks/README.md", "skills/_shared/code-graph.md"],
+    binFiles: ["bin/cli.js"],
+  },
+  // ── v1.8.2 W4 — the paid layer, paid less (N1 · N2) ──────────────────
+  {
+    // The noter's ONE call. The flag lives in the agent that makes it and in
+    // the contract that describes it; the CLI has to answer it.
+    name: "graph noter source (v1.8.2 — notes pending --with-source, so the noter reads nothing)",
+    token: "--with-source",
+    files: ["agents/orc-graph-noter-sonnet-4-6-med.md", "skills/_shared/code-graph.md"],
+    binFiles: ["bin/cli.js", "bin/graph-notes.js"],
+  },
+  {
+    // The doc note, at 0 model tokens. It is a note, not a fact, so it sits
+    // beside graph notes in the precedence line everywhere that line appears.
+    name: "doc notes precedence (v1.8.2 — graph notes AND doc notes, below a stale wiki)",
+    token: "graph notes and doc notes",
+    files: [
+      "skills/_shared/code-graph.md",
+      "skills/_shared/phases/wiki-consult.md",
+      "skills/_shared/read-ladder.md",
+      "skills/orc-wiki/references/staleness.md",
+    ],
+    binFiles: ["bin/graph-notes.js"],
+  },
+  // ── v1.8.2 W5 — the five new languages (G6) ──────────────────────────
+  {
+    // A language the contract claims and the engine cannot read is a promise
+    // the card breaks in silence. The claim and `LANG_BY_EXT` move together.
+    name: "graph languages (v1.8.2 — Ruby, Rust, Kotlin, plus SFC and C/C++)",
+    token: "Ruby, Rust, Kotlin",
+    files: ["skills/_shared/code-graph.md"],
+    binFiles: ["bin/graph.js"],
+  },
+  // ── v1.8.2 W6 — the borrowed toolchains (G7) ─────────────────────────
+  {
+    // The escape hatch. If the contract names it and the engine stops reading
+    // it, a project with a misbehaving toolchain has no way out.
+    name: "graph borrow escape (v1.8.2 — ORC_GRAPH_NO_BORROW forces the heuristic)",
+    token: "ORC_GRAPH_NO_BORROW",
+    files: ["skills/_shared/code-graph.md"],
+    binFiles: ["bin/graph-extract.js"],
+  },
+  // ── v1.8.2 W8 — the sharded read path (S1) ────────────
+  {
+    // The shards are a DERIVED store, and the contract's promise about every
+    // derived store is the one that keeps them safe: generation-pinned, and a
+    // missing one costs time and no answer. If the engine stops writing them,
+    // the sentence that tells a reader they exist has to go with it.
+    name: "graph shards (v1.8.2 — the resolved/ shards a one-symbol ctx reads)",
+    token: "resolved/<ab>.json",
+    files: ["skills/_shared/code-graph.md"],
+    binFiles: ["bin/graph-shard.js"],
+  },
+  // ── v1.8.2 W7 — the ranked map (D4) ──────────────────
+  {
+    // The command itself. Three lanes are told to run it at the START of
+    // planning; if the CLI stops offering it, every one of them opens a run
+    // with a call that does not exist.
+    name: "graph map (v1.8.2 — the ranked repository map, the orientation call)",
+    token: "orc graph map",
+    files: [
+      "skills/_shared/code-graph.md",
+      "skills/_shared/phases/planning.md",
+      "skills/_shared/phases/trace.md",
+      "skills/orc/SKILL.md",
+      "skills/orc-diy/references/flow-schema.md",
+    ],
+    binFiles: ["bin/cli.js", "bin/graph-map.js"],
+  },
+  {
+    // The trace verb. A lane that emits a verb the trace table does not hold
+    // writes a line `/orc-retro` cannot aggregate.
+    name: "graph map trace (v1.8.2 — GRAPH-MAP, one line at the start of planning)",
+    token: "GRAPH-MAP",
+    files: [
+      "skills/_shared/phases/trace.md",
+      "skills/_shared/phases/planning.md",
+    ],
+    binFiles: ["bin/cli.js"],
+  },
+  {
+    // The claim that keeps the map safe to read. It is the map's whole
+    // equivalent of "the graph is a LOCATOR": a rank is where to look first,
+    // never proof that a file matters to this change.
+    name: "graph map rank is a hint (v1.8.2 — never proof a file matters)",
+    token: "a HINT about where to look first",
+    files: ["skills/_shared/code-graph.md", "skills/_shared/phases/planning.md"],
+    binFiles: ["bin/graph-query.js"],
+  },
+  // ── v1.8.2 W4b — the gain meter (K) ─────────────────────────────
+  {
+    // The one line a run prints about what the graph cost and probably saved.
+    // The verb lives in the trace table and in the phase that emits it.
+    name: "graph gain line (v1.8.2 — GRAPH-GAIN, one line at ship, copied verbatim)",
+    token: "GRAPH-GAIN",
+    files: ["skills/_shared/phases/ship.md", "skills/_shared/phases/trace.md"],
+    binFiles: ["bin/cli.js"],
+  },
+  {
+    // `avoided` is a COUNTERFACTUAL. The word has to survive every rewrite of
+    // the contract and of the panel, because it is the claim.
+    name: "graph gain estimate (v1.8.2 — avoided is an estimate, never a bill)",
+    token: "AN ESTIMATE",
+    files: ["skills/_shared/code-graph.md"],
+    binFiles: ["bin/graph-gain.js"],
+  },
   {
     // The only notes writer, dispatched BY NAME. An unnamed dispatch cannot
     // enforce the Sonnet 4.6 pin and is invisible to the trace hook.
@@ -3919,6 +4057,8 @@ for (const b of BUDGETS) {
     // as `statusline_custom` is. Neither can have a lane, and that is an ANSWER.
     "code_graph_heal_ms",
     "code_graph_hooks",
+    // v1.8.2 W2 — the ignore globs, read by the CLI behind the same calls.
+    "code_graph_ignore",
   ]);
   for (const e of metaEntries) {
     if (!e.lanes) {

package/bin/verify-package.js

@@ -185,6 +185,20 @@ const required = [
   "bin/graph-resolve.js",
   "bin/graph-signals.js",
   "bin/graph-notes.js",
+
+  // v1.8.2 W4b — the gain meter. Dropping it breaks `orc graph gain` AND the
+  // one ledger line every read appends, so the map would go on working and
+  // quietly stop recording what it cost.
+  "bin/graph-gain.js",
+  // v1.8.2 W7 — the ranked map (D4). Dropping it breaks `orc graph map` AND the
+  // `map.json` every update writes, so planning would silently go back to the
+  // Glob-and-read sweep the map exists to replace.
+  "bin/graph-map.js",
+  // v1.8.2 W8 — the sharded read path (S1). Dropping it does not break a card:
+  // every read falls back to the full model. It breaks the SPEED, silently, on
+  // the one call every lane makes — which is the worst kind of missing file.
+  "bin/graph-shard.js",
+
   // The two DATED data files (v0.50.0). Both ship inside the package and both
   // are load-bearing on absence rather than on content: without the catalog
   // `orc extra providers` is a packaging bug it reports as one, and without the

package/bin/webui/api.js

@@ -224,6 +224,12 @@ const READS = {
   // v1.8.0 — the code graph. A READ whose exit code is DATA (0 fresh · 1 none ·
   // 2 drifted · 3 off), exactly like `wiki status` above.
   "/api/graph": () => ["graph", "status"],
+  // v1.8.2 W4b — the gain meter. Two READS, both with exit codes that are DATA
+  // (0 rows · 1 no ledger or no rows · 3 off). `--measured` is its OWN route
+  // because it reads Claude Code's transcripts and takes longer; the panel
+  // asks for it on a button, never on load.
+  "/api/graph/gain": () => ["graph", "gain"],
+  "/api/graph/gain/measured": () => ["graph", "gain", "--measured"],
   "/api/wiki/impact": () => ["wiki", "impact"],
   // v0.46.0. Every one is a READ with an exit-code contract, so the exit code is
   // DATA here exactly like `pattern status` and `wiki impact` above: pact 0/1/2/3,

package/bin/webui/fixtures/index.js

@@ -21,7 +21,7 @@
 // case here; it is never an edit to a 1 700-line module.
 const { PROJECT, doctor, where } = require("./shell.js");
 const { config } = require("./settings.js");
-const { wiki, wikiDocs, wikiShow, wikiCoverage, wikiCoverageFull, wikiUnregistered, wikiPlan, wikiDebt, wikiUsage, patterns, patternShow, gotchas, gotchasArchived, gotchaPrunePreview, wikiImpact, graph } = require("./knowledge.js");
+const { wiki, wikiDocs, wikiShow, wikiCoverage, wikiCoverageFull, wikiUnregistered, wikiPlan, wikiDebt, wikiUsage, patterns, patternShow, gotchas, gotchasArchived, gotchaPrunePreview, wikiImpact, graph, graphGain, graphGainMeasured } = require("./knowledge.js");
 const { runs, runDetail, runDetailClosed, aftermath } = require("./runs.js");
 const { stats, budgetForecast, budgetRates } = require("./stats.js");
 const { pact } = require("./pact.js");
@@ -309,6 +309,11 @@ module.exports.get = function get(route, q) {
     // v1.8.0 — the code graph, DRIFTED (the state the card must be designed for).
     case "/api/graph":
       return graph;
+    // v1.8.2 W4b — the gain meter, and the A/B behind its second button.
+    case "/api/graph/gain":
+      return graphGain;
+    case "/api/graph/gain/measured":
+      return graphGainMeasured;
     case "/api/patterns":
       return patterns;
     case "/api/gotchas":

package/bin/webui/fixtures/knowledge.js

@@ -313,4 +313,44 @@ const graph = {
   trace: "GRAPH-CONSULT drifted :: files=1920 symbols=5896 gen=42",
 };
 
-module.exports = { wiki, wikiDocs, wikiShow, wikiCoverage, wikiCoverageFull, wikiUnregistered, wikiPlan, wikiDebt, wikiUsage, patterns, patternShow, gotchas, gotchasArchived, gotchaPrunePreview, wikiImpact, graph };
+// v1.8.2 W4b — `orc graph gain --json`. The fixture carries the ESTIMATE word
+// and a RANGE, because those are the two things the card must never lose.
+const graphGain = {
+  ok: true,
+  state: "rows",
+  scope: "project",
+  run: null,
+  since: null,
+  calls_recorded: 41,
+  runs: 6,
+  generation_range: [38, 42],
+  paid: { card: 4120, source: 610, hints: 182, total: 4912 },
+  avoided: { low: 18900, high: 71400 },
+  calls: { low: 58, high: 113 },
+  net: { low: 13988, high: 66488 },
+  by_command: { ctx: 29, impact: 6, changes: 4, "for-slice": 2 },
+  hints: { injected: 11, read_notes: 3, updates: 9 },
+  estimate: true,
+  carry_note:
+    "a card is re-sent on every later turn of the agent that received it — and so is the read it replaced. Both halves carry the same multiplier, so these are FIRST-ENTRY tokens on both sides (eval/graph-replay.js).",
+};
+
+// The A/B, with enough runs in both groups to print a comparison.
+const graphGainMeasured = {
+  ok: true,
+  state: "compared",
+  min_runs: 3,
+  corpus: { dir: "~/.claude/projects/-home-dev-shop", ok: true },
+  runs: { on: 6, off: 4 },
+  rows: { on: [], off: [] },
+  compare: {
+    exec_retrieval_calls: { on: { n: 6, median: 19, min: 12, max: 27 }, off: { n: 4, median: 31, min: 24, max: 39 }, delta_pct: -39, off_spread_pct: 48 },
+    exec_bash_searches: { on: { n: 6, median: 2, min: 0, max: 5 }, off: { n: 4, median: 3, min: 1, max: 6 }, delta_pct: -33, off_spread_pct: 167 },
+    exec_result_tokens: { on: { n: 6, median: 27900, min: 18200, max: 41800 }, off: { n: 4, median: 41200, min: 29100, max: 60300 }, delta_pct: -32, off_spread_pct: 76 },
+    session_result_tokens: { on: { n: 6, median: 188000, min: 141000, max: 244000 }, off: { n: 4, median: 187000, min: 132000, max: 251000 }, delta_pct: 1, off_spread_pct: 64 },
+  },
+  note:
+    "executor windows and session totals are kept apart: the main session is 74–80% of a run and the graph never touches it. Every delta is printed beside the OFF group's own spread — a delta smaller than that spread is noise, not a result.",
+};
+
+module.exports = { wiki, wikiDocs, wikiShow, wikiCoverage, wikiCoverageFull, wikiUnregistered, wikiPlan, wikiDebt, wikiUsage, patterns, patternShow, gotchas, gotchasArchived, gotchaPrunePreview, wikiImpact, graph, graphGain, graphGainMeasured };

package/bin/webui/fixtures/stats.js

@@ -1,104 +1,107 @@
-"use strict";
-/* fixtures/stats.js — canned data for `orc ui --fixtures`.
-   Usage, the cost forecast and the dated rate table. The forecast is a RANGE
-   with a sample count, and cache-read is its own segment.
-
-   THE RULE FOR EVERY FILE IN HERE: carry ONE OF EVERY STATE, including the
-   ugly ones. You cannot DESIGN a STALE chip on a fresh wiki, and a state
-   with no fixture is a state nobody has ever looked at. A per-state count
-   test asserts this, so a new state cannot ship without one.
-
-   Shapes MUST match what `bin/cli.js --json` really emits — a drifted
-   fixture is worse than no fixture. */
-
-const { PROJECT } = require("./shell.js");
-
-const stats = {
-  log_dir: PROJECT + "/.claude/orc/logs",
-  runs: 61,
-  from: "2026-04-11",
-  to: "2026-08-08",
-  lanes: { orc: 22, quick: 17, mini: 9, wiki: 6, fast: 4, ultra: 2, grill: 1 },
-  agents: { "orc-executor": 88, "orc-system-analyst": 21, "orc-planner": 21, "orc-reviewer": 18, "orc-verifier": 18, "orc-scout": 12, "orc-wiki-scanner": 9, "orc-trace-writer": 61 },
-  dispatches: 248,
-  downgrades: 3,
-  unfinished: 2,
-  unknown_lane: 1,
-};
-
-/* ============================================================ v0.46.0 ====== */
-/* Same rule as everything above: ONE OF EVERY STATE, including the ugly ones.
-   You cannot design a BROKEN promise card on a ledger where everything holds,
-   a REFUSE checklist on a repo with no refusals, or an empty-debt Knowledge
-   panel on a wiki that owes four docs. test/webui.test.js asserts the count per
-   state, so a new state cannot ship without a fixture. */
-
-const budgetForecast = {
-  ok: true,
-  plan: PROJECT + "/.claude/orc/run/store-credit/plan.md",
-  tasks: 14,
-  waves: 5,
-  tokens: {
-    p50: { input: 53400, cache_write: 362800, cache_read: 733800, output: 75100 },
-    p90: { input: 81000, cache_write: 548000, cache_read: 1140000, output: 118000 },
-  },
-  raw: { p50: 1225100, p90: 1887000 },
-  weighted: { p50: 564680, p90: 861000 },
-  usd: { p50: 6.76, p90: 10.5 },
-  price_table: { as_of: "2026-08-01", age_days: 9, stale: false, path: "bin/pricing.json" },
-  quota: { available: true, plan: "max20", label: "Max 20x", window_pct: 18.2, weekly_pct: 4.1 },
-  // A task at CONTEXT RISK — the state that cannot be designed on a small plan.
-  context_risk: [{ task: "T12", agent: "orc-executor-opus-5-med", peak: 189000, window: 200000, pct: 95 }],
-  bands: [
-    { band: "[0,30)", agent: "orc-executor-haiku-4-5", count: 2, tasks: ["T01", "T02"], samples: 9, p50: { input: 1200, cache_write: 6400, cache_read: 11800, output: 900 }, p90: { input: 1800, cache_write: 9200, cache_read: 17000, output: 1400 } },
-    { band: "[40,55)", agent: "orc-executor-sonnet-4-6-high", count: 3, tasks: ["T03", "T05", "T07"], samples: 12, p50: { input: 7800, cache_write: 52100, cache_read: 104000, output: 8400 }, p90: { input: 11000, cache_write: 75000, cache_read: 150000, output: 12000 } },
-    { band: "[65,90)", agent: "orc-executor-opus-5-low", count: 1, tasks: ["T04"], samples: 6, p50: { input: 5700, cache_write: 40200, cache_read: 81000, output: 9300 }, p90: { input: 8100, cache_write: 58000, cache_read: 117000, output: 13400 } },
-    // A band with insufficient history — the low-confidence warning is not
-    // optional chrome, so the fixture has to be able to trigger it.
-    { band: "[90,100]", agent: "orc-executor-opus-5-med", count: 1, tasks: ["T12"], samples: 2, p50: { input: 9100, cache_write: 61000, cache_read: 128000, output: 17000 }, p90: { input: 14000, cache_write: 94000, cache_read: 198000, output: 26000 } },
-  ],
-  fixed_roles: [
-    { role: "orc-system-analyst-opus-5-high", samples: 11, p50: { input: 6100, cache_write: 41000, cache_read: 82000, output: 9000 }, p90: { input: 8600, cache_write: 58000, cache_read: 116000, output: 13000 } },
-    { role: "orc-planner-opus-5-med", samples: 11, p50: { input: 5000, cache_write: 33000, cache_read: 68000, output: 7400 }, p90: { input: 7100, cache_write: 47000, cache_read: 96000, output: 10500 } },
-    { role: "orc-trace-writer-haiku-4-5", samples: 41, p50: { input: 900, cache_write: 3000, cache_read: 5400, output: 700 }, p90: { input: 1300, cache_write: 4400, cache_read: 7800, output: 1000 } },
-  ],
-  low_confidence_bands: 1,
-  min_samples: 5,
-  // Non-zero on purpose: `unattributed` is shown whenever it is above 0, and a
-  // fixture where it is always 0 makes that branch undesignable.
-  unattributed: { blocks: 12, tokens: { input: 900, cache_write: 12000, cache_read: 24000, output: 1100 } },
-  transcripts_readable: true,
-  lanes: [
-    { lane: "ultra", cmd: "/orc-ultra", raw: 2410000, weighted: 1090000, usd: 14.2, low_confidence_bands: 1, low_confidence_roles: 0 },
-    { lane: "orc", cmd: "/orc", raw: 1225100, weighted: 564680, usd: 6.76, low_confidence_bands: 1, low_confidence_roles: 0 },
-    { lane: "mini", cmd: "/orc-mini", raw: 410000, weighted: 188000, usd: 2.1, low_confidence_bands: 0, low_confidence_roles: 0 },
-    { lane: "fast", cmd: "/orc-fast", raw: 0, weighted: 0, usd: null, low_confidence_bands: 1, low_confidence_roles: 1 },
-  ],
-  view: "auto",
-};
-
-const budgetRates = {
-  ok: true,
-  version: 1,
-  calibrated_at: "10-08-2026 09:40:11",
-  transcript_dir: "/home/you/.claude/projects/-example-project",
-  transcripts_readable: true,
-  transcript_files: 31,
-  traces_read: 42,
-  dispatches_joined: 96,
-  price_table_as_of: "2026-08-01",
-  bands: {
-    "[0,30)": { samples: 9, p50: { input: 1200, cache_write: 6400, cache_read: 11800, output: 900 }, p90: { input: 1800, cache_write: 9200, cache_read: 17000, output: 1400 }, peak_p50: 24000, peak_p90: 38000 },
-    "[40,55)": { samples: 12, p50: { input: 7800, cache_write: 52100, cache_read: 104000, output: 8400 }, p90: { input: 11000, cache_write: 75000, cache_read: 150000, output: 12000 }, peak_p50: 78000, peak_p90: 121000 },
-    "[70,80)": { samples: 6, p50: { input: 5700, cache_write: 40200, cache_read: 81000, output: 9300 }, p90: { input: 8100, cache_write: 58000, cache_read: 117000, output: 13400 }, peak_p50: 96000, peak_p90: 142000 },
-    "[90,100]": { samples: 2, p50: { input: 9100, cache_write: 61000, cache_read: 128000, output: 17000 }, p90: { input: 14000, cache_write: 94000, cache_read: 198000, output: 26000 }, peak_p50: 151000, peak_p90: 189000 },
-  },
-  roles: {
-    "orc-system-analyst-opus-5-high": { samples: 11, p50: { input: 6100, cache_write: 41000, cache_read: 82000, output: 9000 }, p90: { input: 8600, cache_write: 58000, cache_read: 116000, output: 13000 }, peak_p50: 88000, peak_p90: 131000 },
-    "orc-trace-writer-haiku-4-5": { samples: 41, p50: { input: 900, cache_write: 3000, cache_read: 5400, output: 700 }, p90: { input: 1300, cache_write: 4400, cache_read: 7800, output: 1000 }, peak_p50: 9000, peak_p90: 14000 },
-  },
-  lanes: {},
-  unattributed: { blocks: 12, tokens: { input: 900, cache_write: 12000, cache_read: 24000, output: 1100 } },
-};
-
-module.exports = { stats, budgetForecast, budgetRates };
+"use strict";
+/* fixtures/stats.js — canned data for `orc ui --fixtures`.
+   Usage, the cost forecast and the dated rate table. The forecast is a RANGE
+   with a sample count, and cache-read is its own segment.
+
+   THE RULE FOR EVERY FILE IN HERE: carry ONE OF EVERY STATE, including the
+   ugly ones. You cannot DESIGN a STALE chip on a fresh wiki, and a state
+   with no fixture is a state nobody has ever looked at. A per-state count
+   test asserts this, so a new state cannot ship without one.
+
+   Shapes MUST match what `bin/cli.js --json` really emits — a drifted
+   fixture is worse than no fixture. */
+
+const { PROJECT } = require("./shell.js");
+
+const stats = {
+  log_dir: PROJECT + "/.claude/orc/logs",
+  runs: 61,
+  from: "2026-04-11",
+  to: "2026-08-08",
+  lanes: { orc: 22, quick: 17, mini: 9, wiki: 6, fast: 4, ultra: 2, grill: 1 },
+  agents: { "orc-executor": 88, "orc-system-analyst": 21, "orc-planner": 21, "orc-reviewer": 18, "orc-verifier": 18, "orc-scout": 12, "orc-wiki-scanner": 9, "orc-trace-writer": 61 },
+  dispatches: 248,
+  downgrades: 3,
+  unfinished: 2,
+  unknown_lane: 1,
+  // v1.8.2 W4b — the code-graph row. `paid` is exact; the avoided pair is an
+  // ESTIMATE and always a RANGE, which is why the panel never shows one number.
+  graph: { calls: 41, runs: 6, paid: 4912, avoided_low: 18900, avoided_high: 71400, estimate: true },
+};
+
+/* ============================================================ v0.46.0 ====== */
+/* Same rule as everything above: ONE OF EVERY STATE, including the ugly ones.
+   You cannot design a BROKEN promise card on a ledger where everything holds,
+   a REFUSE checklist on a repo with no refusals, or an empty-debt Knowledge
+   panel on a wiki that owes four docs. test/webui.test.js asserts the count per
+   state, so a new state cannot ship without a fixture. */
+
+const budgetForecast = {
+  ok: true,
+  plan: PROJECT + "/.claude/orc/run/store-credit/plan.md",
+  tasks: 14,
+  waves: 5,
+  tokens: {
+    p50: { input: 53400, cache_write: 362800, cache_read: 733800, output: 75100 },
+    p90: { input: 81000, cache_write: 548000, cache_read: 1140000, output: 118000 },
+  },
+  raw: { p50: 1225100, p90: 1887000 },
+  weighted: { p50: 564680, p90: 861000 },
+  usd: { p50: 6.76, p90: 10.5 },
+  price_table: { as_of: "2026-08-01", age_days: 9, stale: false, path: "bin/pricing.json" },
+  quota: { available: true, plan: "max20", label: "Max 20x", window_pct: 18.2, weekly_pct: 4.1 },
+  // A task at CONTEXT RISK — the state that cannot be designed on a small plan.
+  context_risk: [{ task: "T12", agent: "orc-executor-opus-5-med", peak: 189000, window: 200000, pct: 95 }],
+  bands: [
+    { band: "[0,30)", agent: "orc-executor-haiku-4-5", count: 2, tasks: ["T01", "T02"], samples: 9, p50: { input: 1200, cache_write: 6400, cache_read: 11800, output: 900 }, p90: { input: 1800, cache_write: 9200, cache_read: 17000, output: 1400 } },
+    { band: "[40,55)", agent: "orc-executor-sonnet-4-6-high", count: 3, tasks: ["T03", "T05", "T07"], samples: 12, p50: { input: 7800, cache_write: 52100, cache_read: 104000, output: 8400 }, p90: { input: 11000, cache_write: 75000, cache_read: 150000, output: 12000 } },
+    { band: "[65,90)", agent: "orc-executor-opus-5-low", count: 1, tasks: ["T04"], samples: 6, p50: { input: 5700, cache_write: 40200, cache_read: 81000, output: 9300 }, p90: { input: 8100, cache_write: 58000, cache_read: 117000, output: 13400 } },
+    // A band with insufficient history — the low-confidence warning is not
+    // optional chrome, so the fixture has to be able to trigger it.
+    { band: "[90,100]", agent: "orc-executor-opus-5-med", count: 1, tasks: ["T12"], samples: 2, p50: { input: 9100, cache_write: 61000, cache_read: 128000, output: 17000 }, p90: { input: 14000, cache_write: 94000, cache_read: 198000, output: 26000 } },
+  ],
+  fixed_roles: [
+    { role: "orc-system-analyst-opus-5-high", samples: 11, p50: { input: 6100, cache_write: 41000, cache_read: 82000, output: 9000 }, p90: { input: 8600, cache_write: 58000, cache_read: 116000, output: 13000 } },
+    { role: "orc-planner-opus-5-med", samples: 11, p50: { input: 5000, cache_write: 33000, cache_read: 68000, output: 7400 }, p90: { input: 7100, cache_write: 47000, cache_read: 96000, output: 10500 } },
+    { role: "orc-trace-writer-haiku-4-5", samples: 41, p50: { input: 900, cache_write: 3000, cache_read: 5400, output: 700 }, p90: { input: 1300, cache_write: 4400, cache_read: 7800, output: 1000 } },
+  ],
+  low_confidence_bands: 1,
+  min_samples: 5,
+  // Non-zero on purpose: `unattributed` is shown whenever it is above 0, and a
+  // fixture where it is always 0 makes that branch undesignable.
+  unattributed: { blocks: 12, tokens: { input: 900, cache_write: 12000, cache_read: 24000, output: 1100 } },
+  transcripts_readable: true,
+  lanes: [
+    { lane: "ultra", cmd: "/orc-ultra", raw: 2410000, weighted: 1090000, usd: 14.2, low_confidence_bands: 1, low_confidence_roles: 0 },
+    { lane: "orc", cmd: "/orc", raw: 1225100, weighted: 564680, usd: 6.76, low_confidence_bands: 1, low_confidence_roles: 0 },
+    { lane: "mini", cmd: "/orc-mini", raw: 410000, weighted: 188000, usd: 2.1, low_confidence_bands: 0, low_confidence_roles: 0 },
+    { lane: "fast", cmd: "/orc-fast", raw: 0, weighted: 0, usd: null, low_confidence_bands: 1, low_confidence_roles: 1 },
+  ],
+  view: "auto",
+};
+
+const budgetRates = {
+  ok: true,
+  version: 1,
+  calibrated_at: "10-08-2026 09:40:11",
+  transcript_dir: "/home/you/.claude/projects/-example-project",
+  transcripts_readable: true,
+  transcript_files: 31,
+  traces_read: 42,
+  dispatches_joined: 96,
+  price_table_as_of: "2026-08-01",
+  bands: {
+    "[0,30)": { samples: 9, p50: { input: 1200, cache_write: 6400, cache_read: 11800, output: 900 }, p90: { input: 1800, cache_write: 9200, cache_read: 17000, output: 1400 }, peak_p50: 24000, peak_p90: 38000 },
+    "[40,55)": { samples: 12, p50: { input: 7800, cache_write: 52100, cache_read: 104000, output: 8400 }, p90: { input: 11000, cache_write: 75000, cache_read: 150000, output: 12000 }, peak_p50: 78000, peak_p90: 121000 },
+    "[70,80)": { samples: 6, p50: { input: 5700, cache_write: 40200, cache_read: 81000, output: 9300 }, p90: { input: 8100, cache_write: 58000, cache_read: 117000, output: 13400 }, peak_p50: 96000, peak_p90: 142000 },
+    "[90,100]": { samples: 2, p50: { input: 9100, cache_write: 61000, cache_read: 128000, output: 17000 }, p90: { input: 14000, cache_write: 94000, cache_read: 198000, output: 26000 }, peak_p50: 151000, peak_p90: 189000 },
+  },
+  roles: {
+    "orc-system-analyst-opus-5-high": { samples: 11, p50: { input: 6100, cache_write: 41000, cache_read: 82000, output: 9000 }, p90: { input: 8600, cache_write: 58000, cache_read: 116000, output: 13000 }, peak_p50: 88000, peak_p90: 131000 },
+    "orc-trace-writer-haiku-4-5": { samples: 41, p50: { input: 900, cache_write: 3000, cache_read: 5400, output: 700 }, p90: { input: 1300, cache_write: 4400, cache_read: 7800, output: 1000 }, peak_p50: 9000, peak_p90: 14000 },
+  },
+  lanes: {},
+  unattributed: { blocks: 12, tokens: { input: 900, cache_write: 12000, cache_read: 24000, output: 1100 } },
+};
+
+module.exports = { stats, budgetForecast, budgetRates };

package/bin/webui/i18n/en/knowledge.json

@@ -163,5 +163,20 @@
   "knowledge.wiki.unregistered": "The wiki is {state} — nothing can read it until it is registered.",
   "knowledge.wiki.why": "why: {reason}",
   "knowledge.graph.generation": "Generation",
-  "knowledge.graph.selfheal": "It keeps itself current: a read repairs the files it is about to answer for, and the installed hook updates the map when a worker finishes. Nothing runs on a timer."
+  "knowledge.graph.selfheal": "It keeps itself current: a read repairs the files it is about to answer for, and the installed hook updates the map when a worker finishes. Nothing runs on a timer.",
+  "knowledge.gain.none": "No graph reads recorded yet. The first `orc graph ctx` starts the ledger.",
+  "knowledge.gain.strip": "paid {paid} · avoided ~{low}–{high} (estimate) · {calls} calls",
+  "knowledge.gain.paid": "Tokens put in (cards · source · hints)",
+  "knowledge.gain.avoided": "Retrieval probably kept out (estimate)",
+  "knowledge.gain.net": "Net tokens · net tool calls",
+  "knowledge.gain.byCommand": "By command",
+  "knowledge.gain.hints": "Hints (injected · read notes · updates)",
+  "knowledge.gain.measure": "Compare my ON and OFF runs",
+  "knowledge.gain.estimate": "`avoided` is an estimate of the retrieval a read ladder would have paid for, never a bill. `paid` is exact.",
+  "knowledge.gain.measuredHead": "{on} runs with the graph on vs {off} with it off",
+  "knowledge.gain.measuredFew": "Too few runs to compare. Three runs in each group are needed; the rows are recorded and the comparison waits.",
+  "knowledge.gain.execCalls": "worker retrieval",
+  "knowledge.gain.execTokens": "worker tool results",
+  "knowledge.gain.sessionTokens": "session tool results",
+  "knowledge.gain.noise": "a change smaller than the spread beside it is noise, not a result"
 }

package/bin/webui/i18n/id/knowledge.json

@@ -163,5 +163,20 @@
   "knowledge.wiki.unregistered": "Wiki berstatus {state} — tidak ada yang bisa membacanya sampai terdaftar.",
   "knowledge.wiki.why": "sebab: {reason}",
   "knowledge.graph.generation": "Generasi",
-  "knowledge.graph.selfheal": "Peta ini memperbarui dirinya: satu pembacaan memperbaiki berkas yang akan dijawabnya, dan hook yang terpasang memperbarui peta saat satu pekerja selesai. Tidak ada yang berjalan dengan pewaktu."
+  "knowledge.graph.selfheal": "Peta ini memperbarui dirinya: satu pembacaan memperbaiki berkas yang akan dijawabnya, dan hook yang terpasang memperbarui peta saat satu pekerja selesai. Tidak ada yang berjalan dengan pewaktu.",
+  "knowledge.gain.none": "Belum ada pembacaan grafik yang tercatat. `orc graph ctx` pertama memulai catatannya.",
+  "knowledge.gain.strip": "dibayar {paid} · dihindari ~{low}–{high} (perkiraan) · {calls} panggilan",
+  "knowledge.gain.paid": "Token yang dimasukkan (kartu · sumber · petunjuk)",
+  "knowledge.gain.avoided": "Pembacaan yang mungkin dihindari (perkiraan)",
+  "knowledge.gain.net": "Token bersih · panggilan alat bersih",
+  "knowledge.gain.byCommand": "Menurut perintah",
+  "knowledge.gain.hints": "Petunjuk (dikirim · catatan baca · pembaruan)",
+  "knowledge.gain.measure": "Bandingkan proses ON dan OFF saya",
+  "knowledge.gain.estimate": "`dihindari` adalah perkiraan pembacaan yang akan dibayar tangga baca, bukan tagihan. `dibayar` adalah angka pasti.",
+  "knowledge.gain.measuredHead": "{on} proses dengan grafik hidup vs {off} dengan grafik mati",
+  "knowledge.gain.measuredFew": "Terlalu sedikit proses untuk dibandingkan. Perlu tiga proses di tiap kelompok; barisnya tercatat dan perbandingannya menunggu.",
+  "knowledge.gain.execCalls": "pembacaan pekerja",
+  "knowledge.gain.execTokens": "hasil alat pekerja",
+  "knowledge.gain.sessionTokens": "hasil alat sesi",
+  "knowledge.gain.noise": "perubahan yang lebih kecil dari sebarannya adalah derau, bukan hasil"
 }