@azure-id/orc 1.2.1 → 1.4.1

package/templates/hooks/orc-statusline.js

@@ -339,6 +339,123 @@ function fmtTokens(tok) {
   return String(n);
 }
 
+// ── The per-session ledger: ONE read, ONE write, ONE throttle (v1.3.0 W0) ───
+// `.claude/orc/usage-session.json` is the per-session ledger, and three
+// separate blocks below want it: the rate-limit tracker, `ucs`, and the
+// throttled line-2 scan. Each used to open the file itself and two of them
+// wrote it, so one render cost three reads and two writes — on a surface that
+// re-renders on every keystroke. It is memoised here instead: loaded at most
+// once per process, mutated in place by whoever needs it, and flushed exactly
+// once at the end. Same rules as before — RAW numbers only, never a computed
+// word, fail-silent, and the reader decides what it means.
+//
+// The scan interval is the ONE seam over this budget, on the ORC_TEST_PROBE_MS
+// precedent: a test that proves the throttle by SLEEPING past it is a test that
+// fails on a loaded machine, and a flake is recorded and removed, never retried
+// away. Unset, this is byte-identical to a hardcoded 5000, and nothing in ORC
+// ever sets it.
+let LED = null;
+let LED_FILE = null;
+
+// The scan's own answers, in ONE shape, so a composed layout (v1.3.0) reads
+// exactly what the shipped lines read. It is populated as the blocks below
+// compute their segments — never by a second pass over the disk. A provider
+// nothing binds is simply never filled in, and every binding over it answers
+// null, which renders an em dash. UNKNOWN IS NOT ZERO.
+const SCAN = {
+  spawns: 0, running: 0, lanes: [], phase: null, slug: null,
+  branch: null, head: null, wiki: null, diy: null,
+  extra_enabled: false, update_version: null, inflight: null,
+  trace_age_min: null, trace_state: null, last_agent: null, retries: null,
+};
+
+function ledger(projectDir, sid) {
+  if (LED) return LED;
+  const fs = require("fs");
+  const path = require("path");
+  LED_FILE = path.join(projectDir, ".claude", "orc", "usage-session.json");
+  let led = null;
+  try {
+    led = JSON.parse(fs.readFileSync(LED_FILE, "utf8"));
+  } catch (_) {}
+  if (!led || led.session_id !== sid) led = { session_id: sid, started_at: Date.now() };
+  LED = led;
+  return LED;
+}
+
+function ledgerFlush() {
+  if (!LED || !LED_FILE) return;
+  try {
+    const fs = require("fs");
+    const path = require("path");
+    LED.updated_at = Date.now();
+    fs.mkdirSync(path.dirname(LED_FILE), { recursive: true });
+    fs.writeFileSync(LED_FILE, JSON.stringify(LED) + "\n");
+  } catch (_) {}
+}
+
+function scanEveryMs() {
+  const n = Number(process.env.ORC_STATUSLINE_SCAN_MS);
+  return Number.isFinite(n) && n >= 0 ? n : 5000;
+}
+
+// Per-provider TTL (v1.3.0 W2), replacing the single global throttle for
+// everything but the trace scan. A wiki tier does not move in five seconds and
+// a flow lock moves when somebody runs a command, so paying the 5-second rate
+// for either is paying for a change that cannot have happened.
+//
+// `ORC_STATUSLINE_SCAN_MS` still overrides ALL of them — it stays the ONE seam
+// over this budget, and a seam that only covered one provider would be a seam
+// tests could not use.
+const TTL = {
+  trace: 5000, // a run moves; this is the one thing that really is that fast
+  git: 5000, // .git/HEAD, no subprocess
+  wiki: 60000, // a wiki tier does not move in five seconds
+  config: 30000, // a config file is edited by hand
+  diy: 30000, // a flow lock moves when somebody runs a command
+  knowledge: 60000, // a pattern cache, a peer list, a gotcha count
+  extra: 15000, // a spend log DOES move during a wave
+  run: 10000, // RESUME.md is rewritten at every stop
+  gates: 60000, // a pact does not drift between keystrokes
+};
+
+// `at` is a ledger `scanned_at` stamp. Absent is stale — unknown is not fresh.
+function scanStale(at, now, ttl) {
+  const budget = process.env.ORC_STATUSLINE_SCAN_MS !== undefined ? scanEveryMs() : ttl == null ? scanEveryMs() : ttl;
+  return typeof at !== "number" || now - at >= budget;
+}
+
+// The read plan, from the compiled layout's lock. Returns null in EVERY state
+// but one — the feature off, no lock, an unparseable lock — and null means
+// "read everything", which is what makes `off` byte-identical.
+//
+// It deliberately does NOT re-run the gate ladder. This is a question about
+// what to READ, and the ladder is a question about what to RENDER; a layout
+// that later fails the ladder falls back to the shipped lines and simply has a
+// segment or two missing for one render. That is a far better failure than
+// reading the disk twice on a surface that re-renders on every keystroke.
+function readPlan(d) {
+  try {
+    const fs = require("fs");
+    const path = require("path");
+    const projectDir =
+      (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
+    const raw = fs.readFileSync(path.join(projectDir, ".claude", "orc.config.yaml"), "utf8");
+    if (!/^[ \t]*statusline_custom:[ \t]*["']?on["']?[ \t]*\r?$/m.test(raw)) return null;
+    const lock = JSON.parse(
+      fs.readFileSync(path.join(projectDir, ".claude", "orc", "statusline.lock.json"), "utf8")
+    );
+    if (!lock || !Array.isArray(lock.bindings)) return null;
+    return {
+      bindings: new Set(lock.bindings),
+      providers: new Set(lock.providers || []),
+      series: new Set(lock.series || []),
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
 let raw = "";
 process.stdin.on("data", (c) => (raw += c));
 process.stdin.on("end", () => {
@@ -357,6 +474,23 @@ process.stdin.on("end", () => {
       ? `context (${d.context_window.used_percentage}%)`
       : "";
 
+  // ── THE READ PLAN (v1.3.0 W2) ──────────────────────────────────────────────
+  // The compiler knows exactly which bindings a layout uses, therefore exactly
+  // which providers it needs, and it records both in the lock. So: A PROVIDER
+  // NOTHING BINDS IS NOT READ.
+  //
+  // That is the claim this feature has to earn — the shipped status line pays
+  // for the wiki read, the diy read and the trace scan unconditionally, and a
+  // user whose layout names none of them should pay for none of them. Composing
+  // your own line is allowed to make the bar FASTER than the hardcoded one it
+  // replaces, and here is where that happens.
+  //
+  // `null` means the feature is off, and then everything below runs exactly as
+  // it always has. That is what keeps `off` byte-identical.
+  const PLAN = readPlan(d);
+  const wants = (b) => !PLAN || PLAN.bindings.has(b);
+  const wantsProvider = (p) => !PLAN || PLAN.providers.has(p);
+
   // ── Session-model bridge (fail-silent) ─────────────────────────────────────
   // The PreToolUse effort guard cannot see the model id; it can only read
   // effort. Persist {model_id, effort, written_at} here so the guard can grant
@@ -431,9 +565,7 @@ process.stdin.on("end", () => {
       // bank what was consumed before the reset into `accumulated` and
       // re-baseline, so the running total keeps counting across the boundary.
       const sid = String(d.session_id || d.sessionId || "");
-      const sfile = path.join(orcDir, "usage-session.json");
-      let led = null;
-      try { led = JSON.parse(fs.readFileSync(sfile, "utf8")); } catch (_) {}
+      const led = ledger(projectDir, sid);
       const pctOf = (o) => (o && typeof o.used_percentage === "number" ? o.used_percentage : null);
       const track = (prev, cur) => {
         if (cur == null) return prev || null;
@@ -447,13 +579,10 @@ process.stdin.on("end", () => {
           };
         return { baseline: prev.baseline, last: cur, accumulated: prev.accumulated, resets: prev.resets };
       };
-      if (!led || led.session_id !== sid) led = { session_id: sid, started_at: Date.now() };
       led.five_hour = track(led.five_hour, pctOf(rl0 && rl0.five_hour));
       led.seven_day = track(led.seven_day, pctOf(rl0 && rl0.seven_day));
       led.context_used_percentage =
         cw0 && typeof cw0.used_percentage === "number" ? cw0.used_percentage : null;
-      led.updated_at = Date.now();
-      fs.writeFileSync(sfile, JSON.stringify(led) + "\n");
     }
 
   } catch (_) {}
@@ -597,13 +726,9 @@ process.stdin.on("end", () => {
   // And it is still a delta of an ACCOUNT-WIDE window, not a private meter: a
   // second terminal moves it too.
   try {
-    const fs = require("fs");
-    const path = require("path");
     const projectDir =
       (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
-    const led = JSON.parse(
-      fs.readFileSync(path.join(projectDir, ".claude", "orc", "usage-session.json"), "utf8")
-    );
+    const led = ledger(projectDir, String(d.session_id || d.sessionId || ""));
     const w = led && led.five_hour;
     if (w && typeof w.last === "number" && typeof w.baseline === "number") {
       const used = Math.max(0, (w.accumulated || 0) + Math.max(0, w.last - w.baseline));
@@ -616,43 +741,85 @@ process.stdin.on("end", () => {
   // wiki / no git / any error → no segment. Thresholds mirror the config
   // defaults (wiki_fresh_max 10 / wiki_aging_max 30); the hook can't read the
   // resolved config, so a user override shifts skill behavior, not this label.
+  //
+  // The git distance rides in the SAME throttled scan as everything on line 2
+  // (v1.3.0 W0). It used to be an `execSync` on every render — one child
+  // process PER KEYSTROKE in any repo with a wiki, which is the exact hazard
+  // the throttle exists to prevent. The ledger caches the RAW facts (a commit
+  // count, a boolean) and never the word: `fresh` / `AGING` / `STALE` is
+  // computed here, on read, every time.
   try {
     const fs = require("fs");
     const path = require("path");
-    const { execSync } = require("child_process");
     const projectDir =
       (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
-    const metaPath = path.join(projectDir, ".claude", "orc", "wiki-meta.json");
-    if (!fs.existsSync(metaPath)) {
-      // Docs but no manifest = UNREGISTERED: a real wiki nothing has indexed
-      // (usually a scan stopped at a 5-area pause). It is otherwise invisible —
-      // consumers and `orc crosslink` read the manifest — so surface it here,
-      // with the free fix. Never say "no wiki": these docs are already paid for.
-      const wikiDir = path.join(projectDir, "wiki");
-      const docs =
-        fs.existsSync(wikiDir) &&
-        fs.readdirSync(wikiDir).some((f) => f.startsWith("orc-") && f.endsWith(".md"));
-      if (docs) line += " · wiki: UNREGISTERED (run `orc wiki sync`)";
-    } else {
-      const meta = JSON.parse(fs.readFileSync(metaPath, "utf8"));
-      if (meta && meta.scan_commit) {
-        const distance = parseInt(
-          execSync(`git rev-list --count ${meta.scan_commit}..HEAD`, {
-            cwd: projectDir,
-            timeout: 3000,
-            stdio: ["ignore", "pipe", "ignore"],
-          })
-            .toString()
-            .trim(),
-          10
-        );
-        if (Number.isFinite(distance)) {
-          if (distance >= 10 && distance <= 30)
-            line += ` · wiki: AGING (${distance}c)`;
-          else if (distance > 30) line += ` · wiki: STALE (${distance}c)`;
-          else line += " · wiki: fresh";
+    // A layout that names no wiki component performs ZERO wiki reads — not a
+    // cheaper one, none. This is the read planner's whole point.
+    if (!wants("wiki.tier") && !wants("wiki.distance")) throw new Error("not needed");
+    const led = ledger(projectDir, String(d.session_id || d.sessionId || ""));
+    const now = Date.now();
+    // A wiki tier does not move in five seconds. Per-provider TTL replaces the
+    // single global throttle for everything but the trace scan, which is the
+    // one thing that really does move that fast.
+    if (scanStale(led.wiki && led.wiki.scanned_at, now, TTL.wiki)) {
+      const w = { unregistered: false, distance: null, scanned_at: now };
+      const metaPath = path.join(projectDir, ".claude", "orc", "wiki-meta.json");
+      if (!fs.existsSync(metaPath)) {
+        // Docs but no manifest = UNREGISTERED: a real wiki nothing has indexed
+        // (usually a scan stopped at a 5-area pause). It is otherwise invisible
+        // — consumers and `orc crosslink` read the manifest — so surface it
+        // here, with the free fix. Never say "no wiki": these docs are already
+        // paid for.
+        const wikiDir = path.join(projectDir, "wiki");
+        w.unregistered =
+          fs.existsSync(wikiDir) &&
+          fs.readdirSync(wikiDir).some((f) => f.startsWith("orc-") && f.endsWith(".md"));
+      } else {
+        const meta = JSON.parse(fs.readFileSync(metaPath, "utf8"));
+        if (meta && meta.scan_commit) {
+          // A FAILED probe is a fact, and it is cached like any other. No git,
+          // a detached commit, a timeout — without this inner catch the whole
+          // block aborts before the ledger is stamped, and the subprocess runs
+          // again on the very next keystroke. The segment stays absent either
+          // way; what changes is that it costs nothing to stay absent.
+          try {
+            const { execSync } = require("child_process");
+            const n = parseInt(
+              execSync(`git rev-list --count ${meta.scan_commit}..HEAD`, {
+                cwd: projectDir,
+                timeout: 3000,
+                stdio: ["ignore", "pipe", "ignore"],
+              })
+                .toString()
+                .trim(),
+              10
+            );
+            if (Number.isFinite(n)) w.distance = n;
+          } catch (_) {}
         }
       }
+      led.wiki = w;
+    }
+    const w = led.wiki;
+    if (w) {
+      SCAN.wiki = {
+        distance: typeof w.distance === "number" ? w.distance : null,
+        tier: w.unregistered
+          ? "unregistered"
+          : typeof w.distance !== "number"
+            ? null
+            : w.distance > 30
+              ? "stale"
+              : w.distance >= 10
+                ? "aging"
+                : "fresh",
+      };
+    }
+    if (w && w.unregistered) line += " · wiki: UNREGISTERED (run `orc wiki sync`)";
+    else if (w && typeof w.distance === "number") {
+      if (w.distance >= 10 && w.distance <= 30) line += ` · wiki: AGING (${w.distance}c)`;
+      else if (w.distance > 30) line += ` · wiki: STALE (${w.distance}c)`;
+      else line += " · wiki: fresh";
     }
   } catch (_) {}
 
@@ -665,6 +832,8 @@ process.stdin.on("end", () => {
     const crypto = require("crypto");
     const projectDir =
       (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
+    if (!wants("diy.state") && !wants("diy.name") && !wants("diy.tier_state"))
+      throw new Error("not needed");
     const lockPath = path.join(projectDir, ".claude", "orc", "diy", "flow.lock.json");
     if (fs.existsSync(lockPath)) {
       const lock = JSON.parse(
@@ -715,6 +884,23 @@ process.stdin.on("end", () => {
     } catch (_) {}
   }
 
+  // The branch is its OWN provider: `.git/HEAD` with no subprocess, on a
+  // different clock from the trace scan, and a layout that shows a branch and
+  // nothing else must not pay for a trace scan to get it.
+  if (wantsProvider("scan.git")) {
+    try {
+      const projectDir =
+        (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
+      SCAN.branch = gitBranch(projectDir) || null;
+    } catch (_) {}
+  }
+
+  // The extended scan (v1.3.0 W3). Only a composed layout can reach it, and
+  // only for the providers its own lock names.
+  extendedScan(d, wants, wantsProvider);
+  // The sparkline series, sampled during the scan that already ran.
+  sampleSeries(d, PLAN);
+
   // ── Session line (v1.2.0) ──────────────────────────────────────────────────
   // Line 1 answers "what tier am I on and how full is the window". This second
   // line answers "what has this session actually been DOING" — how many agents
@@ -734,13 +920,7 @@ process.stdin.on("end", () => {
     const path = require("path");
     const projectDir =
       (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
-    const orcDir = path.join(projectDir, ".claude", "orc");
-    const sfile = path.join(orcDir, "usage-session.json");
-    const sid = String(d.session_id || d.sessionId || "");
-
-    let led = null;
-    try { led = JSON.parse(fs.readFileSync(sfile, "utf8")); } catch (_) {}
-    if (!led || led.session_id !== sid) led = { session_id: sid, started_at: Date.now() };
+    const led = ledger(projectDir, String(d.session_id || d.sessionId || ""));
 
     // The hook cannot read the RESOLVED config — that is the lane resolver's
     // job, and a hook has no lane — so this reads the two raw keys it needs
@@ -757,18 +937,8 @@ process.stdin.on("end", () => {
     } catch (_) {}
 
     const now = Date.now();
-    // The scan interval is the ONE seam over this budget, on the
-    // ORC_TEST_PROBE_MS precedent: a test that proves the throttle by SLEEPING
-    // past it is a test that fails on a loaded machine, and a flake is recorded
-    // and removed, never retried away. Unset, this is byte-identical to a
-    // hardcoded 5000, and nothing in ORC ever sets it.
-    const scanEvery = (() => {
-      const n = Number(process.env.ORC_STATUSLINE_SCAN_MS);
-      return Number.isFinite(n) && n >= 0 ? n : 5000;
-    })();
-    const stale = !led.dispatch || typeof led.dispatch.scanned_at !== "number" ||
-      now - led.dispatch.scanned_at >= scanEvery;
-    if (stale) {
+    if (!wantsProvider("scan.trace")) throw new Error("not needed");
+    if (scanStale(led.dispatch && led.dispatch.scanned_at, now, TTL.trace)) {
       const logDir = path.isAbsolute(logRel) ? logRel : path.join(projectDir, logRel);
       const sessionFloor = Math.floor((led.started_at || 0) / 1000) * 1000;
       let spawns = 0;
@@ -847,13 +1017,14 @@ process.stdin.on("end", () => {
       led.tok = scanTokens(led, d.transcript_path || null);
     }
 
-    led.updated_at = now;
-    try {
-      fs.mkdirSync(orcDir, { recursive: true });
-      fs.writeFileSync(sfile, JSON.stringify(led) + "\n");
-    } catch (_) {}
-
     const dsp = led.dispatch || { spawns: 0, running: 0, lanes: [], phase: null };
+    // The composed layout reads THESE — the same numbers the shipped line
+    // below prints, from the same scan.
+    SCAN.spawns = dsp.spawns || 0;
+    SCAN.running = dsp.running || 0;
+    SCAN.lanes = dsp.lanes || [];
+    SCAN.phase = dsp.phase || null;
+    SCAN.extra_enabled = !!extraOn;
     const parts = [];
     // `status:` leads, because what ORC is doing right now is the one thing on
     // this line that changes minute to minute. It is also the ONE segment
@@ -876,12 +1047,488 @@ process.stdin.on("end", () => {
     // MTok keeps its slot in every state. An em dash says "not measured"; a `0`
     // would say the session was free, and that is a different claim.
     parts.push("MTok " + (fmtTokens(led.tok) || "—"));
-    const branch = gitBranch(projectDir);
-    if (branch) parts.push(branch);
+    if (SCAN.branch) parts.push(SCAN.branch);
     line2 = "   " + parts.join(" · ");
   } catch (_) {
     line2 = "";
   }
 
+  // ONE write, after every block that touches the ledger has had its say. It is
+  // last on purpose: a render that throws half way through still prints, and a
+  // ledger that could not be written never takes the status line down with it.
+  ledgerFlush();
+
+  // ── THE CUSTOM LAYOUT (v1.3.0) ──────────────────────────────────────────
+  // Everything above is the SHIPPED status line, and it is what renders unless
+  // the user composed their own. `custom()` returns null in every state but
+  // one, and each of its gates is a FALLBACK rather than a throw: a hook cannot
+  // refuse, so a bad layout must degrade to something correct rather than paint
+  // garbage. The ladder is documented on the function itself.
+  const composed = custom(d, {
+    payload: d,
+    ledger: LED || {},
+    scan: SCAN,
+    derived: { verdict, reasons, version: ver },
+    now: Date.now(),
+  });
+  if (composed != null) {
+    process.stdout.write(composed);
+    return;
+  }
+
   process.stdout.write(line2 ? line + "\n" + line2 : line);
 });
+
+// ── The six-rung gate ladder ────────────────────────────────────────────────
+// In order, and EVERY RUNG IS A FALLBACK, never a throw:
+//
+//   1  statusline_custom is not `on`        the shipped lines. BYTE-IDENTICAL.
+//   2  statusline-compiled.json missing /   default + statusline-layout-unreadable
+//      unparseable / schema mismatch
+//   3  orc_version or catalog_hash moved    default + statusline-layout-stale
+//   4  an unknown op or an unknown binding  default + statusline-layout-skew
+//   5  the cheap shape guard fails          default + statusline-layout-invalid
+//   6  otherwise                            run the program
+//
+// Rungs 3 and 4 are why the lock file exists. Rung 5 is this hook RE-CHECKING
+// rather than trusting the file, because a hand-edited compiled file is a file
+// nobody validated. Every fallback RECORDS ITSELF in the ledger so `orc doctor`
+// can name it: a status line that quietly went back to the default and never
+// said why is a bug the user cannot report.
+function custom(d, ctx) {
+  try {
+    const fs = require("fs");
+    const path = require("path");
+    const projectDir =
+      (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
+    const orcDir = path.join(projectDir, ".claude", "orc");
+
+    // Rung 1. The hook cannot resolve config — that is the lane resolver's job,
+    // and a hook has no lane — so it reads the raw key off the file and takes
+    // the documented default otherwise, exactly as it already does for
+    // `log_dir` and `extra_enabled`.
+    let on = false;
+    try {
+      const raw = fs.readFileSync(path.join(projectDir, ".claude", "orc.config.yaml"), "utf8");
+      // The trailing \r is tolerated on purpose: a config file written on
+      // Windows carries CRLF, and a $-anchored match silently never fires
+      // there — which is a feature that is ON in the file and OFF on the bar.
+      on = /^[ \t]*statusline_custom:[ \t]*["']?on["']?[ \t]*\r?$/m.test(raw);
+    } catch (_) {}
+    if (!on) return null;
+
+    // Rung 2. THE HOOK NEVER READS THE AUTHORED LAYOUT — not as a fallback, not
+    // on a cache miss, not ever. One consumer per file.
+    let prog = null;
+    try {
+      prog = JSON.parse(fs.readFileSync(path.join(orcDir, "statusline-compiled.json"), "utf8"));
+    } catch (_) {}
+    if (!prog || prog.schema !== 1) return slFallback(orcDir, "statusline-layout-unreadable");
+
+    // Rung 3. An ORC upgrade that adds, removes or changes a component
+    // invalidates every compiled layout on the machine. Better the shipped
+    // lines than a program compiled against a catalogue that no longer exists.
+    let lock = null;
+    try {
+      lock = JSON.parse(fs.readFileSync(path.join(orcDir, "statusline.lock.json"), "utf8"));
+    } catch (_) {}
+    let installed = null;
+    try {
+      installed = JSON.parse(fs.readFileSync(path.join(__dirname, "orc-version.json"), "utf8")).version;
+    } catch (_) {}
+    if (!lock || (installed && lock.orc_version !== installed))
+      return slFallback(orcDir, "statusline-layout-stale");
+
+    const engine = require("./orc-statusline-render.js");
+
+    // Rung 4. A binding this build does not have is an INSTALL SKEW, not a
+    // rendering problem, and it must not be papered over one item at a time.
+    for (const b of lock.bindings || []) {
+      if (!engine.BINDINGS[b]) return slFallback(orcDir, "statusline-layout-skew");
+    }
+
+    // Rung 5. The cheap shape guard: at most three lines, at most five
+    // components on any of them, and the dense-prefix rule —
+    // A line may hold a component only if every line above it holds at least one.
+    if (!Array.isArray(prog.lines) || prog.lines.length > 3)
+      return slFallback(orcDir, "statusline-layout-invalid");
+    let seenEmpty = false;
+    for (const l of prog.lines) {
+      const n = (l.ops || []).filter((o) => o.op === "item").length;
+      if (n > 5) return slFallback(orcDir, "statusline-layout-invalid");
+      if (n === 0) seenEmpty = true;
+      else if (seenEmpty) return slFallback(orcDir, "statusline-layout-invalid");
+    }
+
+    // Rung 6. Run the program. Failure isolation lives inside the engine: one
+    // throwing item emits its unknown form and the rest of the line survives.
+    SCAN.preset = prog.preset || null;
+    const out = engine.render(prog, {
+      payload: ctx.payload,
+      ledger: ctx.ledger,
+      scan: ctx.scan,
+      derived: ctx.derived,
+      now: ctx.now,
+      cols: Number(process.env.COLUMNS) || 0,
+      env: process.env,
+    });
+    if (out.errors && out.errors.length) slNote(orcDir, "statusline-item-failed", out.errors[0]);
+    return out.text;
+  } catch (_) {
+    // Even the ladder must not throw. A status line that crashes is a status
+    // line that is simply absent, with no way to find out why.
+    return null;
+  }
+}
+
+// A fallback RECORDS ITSELF. `orc doctor` reads this file and names the finding
+// with the exact command that clears it.
+function slFallback(orcDir, finding) {
+  slNote(orcDir, finding, null);
+  return null;
+}
+function slNote(orcDir, finding, detail) {
+  try {
+    const fs = require("fs");
+    const path = require("path");
+    fs.mkdirSync(orcDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(orcDir, "statusline-state.json"),
+      JSON.stringify({ finding, detail: detail || null, at: Date.now() }) + "\n"
+    );
+  } catch (_) {}
+}
+
+// ── THE EXTENDED SCAN (v1.3.0 W3) ──────────────────────────────────────────
+// Groups D, E, F and G — knowledge, extra, flow and the health gates. Every one
+// of them is a `new read`: a read that does not exist in the shipped status
+// line and only happens when a layout asks for it.
+//
+// THE BAR IS 15 MILLISECONDS, NOT 300. W0 measured node startup at ~285 ms of a
+// 300 ms budget, so a component here has to be answerable from a small JSON
+// file, on its own clock, or it does not ship. Two are refused for that reason
+// and say so in the catalogue.
+//
+// Every read below is:
+//   - gated on a BINDING the compiled lock names (the read planner);
+//   - cached in the per-session ledger under its own key;
+//   - given its OWN TTL, because a pact ledger and a spend log do not move at
+//     the same rate.
+//
+// A read that throws leaves its slot null, and a null renders an em dash.
+// UNKNOWN IS NOT ZERO — a `0` would say the thing was measured and found empty.
+function extendedScan(d, wants, wantsProvider) {
+  if (!wantsProvider("scan.extended")) return;
+  let fs, path, projectDir, led, now;
+  try {
+    fs = require("fs");
+    path = require("path");
+    projectDir = (d.workspace && d.workspace.project_dir) || d.cwd || process.cwd();
+    led = ledger(projectDir, String(d.session_id || d.sessionId || ""));
+    now = Date.now();
+  } catch (_) {
+    return;
+  }
+  const orc = path.join(projectDir, ".claude", "orc");
+  const readJson = (p) => {
+    try {
+      return JSON.parse(fs.readFileSync(p, "utf8").replace(/^/, ""));
+    } catch (_) {
+      return null;
+    }
+  };
+  // One cached sub-scan. `key` is its ledger slot, `ttl` its own clock.
+  const cached = (key, ttl, fn) => {
+    const slot = led.ext && led.ext[key];
+    if (slot && !scanStale(slot.at, now, ttl)) return slot.v;
+    let v = null;
+    try {
+      v = fn();
+    } catch (_) {
+      v = null;
+    }
+    led.ext = led.ext || {};
+    led.ext[key] = { v, at: now };
+    return v;
+  };
+
+  // ── Group D — knowledge. All of it comes out of wiki-meta.json, which is
+  //    written ONLY by `orc wiki sync` and is 100% doc-header-derived. A wiki
+  //    tier does not move in a minute, so the TTL is generous.
+  if (wants("wiki.docs")) {
+    const w = cached("wiki_meta", TTL.wiki, () => {
+      const meta = readJson(path.join(orc, "wiki-meta.json"));
+      if (!meta) return null;
+      const docs = Array.isArray(meta.docs) ? meta.docs : [];
+      return {
+        docs: docs.length,
+      };
+    });
+    SCAN.wiki_meta = w;
+  }
+  if (wants("pattern.state")) {
+    // EXISTENCE only, and by the deterministic probe's own rule: the cache
+    // lives under the hidden .claude/ dir, so a raw filesystem search
+    // false-negatives from the wrong cwd.
+    SCAN.pattern = cached("pattern", TTL.knowledge, () => {
+      const dir = path.join(orc, "patterns");
+      try {
+        return fs.readdirSync(dir).some((f) => f.endsWith("-pattern.md")) ? "cached" : "none";
+      } catch (_) {
+        return "none";
+      }
+    });
+  }
+  if (wants("crosslink.state") || wants("crosslink.peers")) {
+    const c = cached("crosslink", TTL.knowledge, () => {
+      const raw = (() => {
+        try {
+          return fs.readFileSync(path.join(projectDir, ".claude", "orc-crosslink.config.yaml"), "utf8");
+        } catch (_) {
+          return null;
+        }
+      })();
+      if (!raw) return null;
+      const n = (raw.match(/^[ \t]*-[ \t]*name:/gm) || []).length;
+      return { peers: n, state: n ? "linked" : "none" };
+    });
+    SCAN.crosslink = c;
+  }
+  if (wants("gotchas.count")) {
+    SCAN.gotchas = cached("gotchas", TTL.knowledge, () => {
+      try {
+        return fs.readdirSync(path.join(orc, "gotchas")).filter((f) => f.endsWith(".md")).length;
+      } catch (_) {
+        return null;
+      }
+    });
+  }
+
+  // ── Group E — extra. `extra.json` is small; the SPEND LOG is not, so it is
+  //    read by TAIL and on its own faster clock, because a spend log is the one
+  //    thing here that moves during a wave.
+  if (wants("extra.profile") || wants("extra.provider") || wants("extra.inflight") || wants("extra.passphrase") || wants("extra.demoted")) {
+    SCAN.extra = cached("extra", TTL.extra, () => {
+      const j = readJson(path.join(orc, "extra.json"));
+      if (!j) return null;
+      const profiles = j.profiles || {};
+      const names = Object.keys(profiles);
+      const first = names.length ? profiles[names[0]] : null;
+      return {
+        profile: names.length ? names[0] : null,
+        provider: first && first.provider ? first.provider : null,
+        profiles: names.length,
+      };
+    });
+  }
+  if (wants("extra.spend") || wants("extra.tasks")) {
+    SCAN.extra_spend = cached("extra_spend", TTL.extra, () => {
+      // The tail only. A spend log grows for the life of a project and reading
+      // all of it on a per-keystroke surface is the hazard this whole subsystem
+      // is shaped around.
+      const p = path.join(orc, "extra-spend.jsonl");
+      let st;
+      try {
+        st = fs.statSync(p);
+      } catch (_) {
+        return null;
+      }
+      const want = Math.min(st.size, 64 * 1024);
+      const buf = Buffer.alloc(want);
+      const fd = fs.openSync(p, "r");
+      try {
+        fs.readSync(fd, buf, 0, want, st.size - want);
+      } finally {
+        fs.closeSync(fd);
+      }
+      const lines = buf.toString("utf8").split("\n").slice(1).filter(Boolean);
+      let tasks = 0;
+      let usd = 0;
+      let priced = false;
+      for (const l of lines) {
+        try {
+          const r = JSON.parse(l);
+          tasks++;
+          if (typeof r.usd === "number") {
+            usd += r.usd;
+            priced = true;
+          }
+        } catch (_) {}
+      }
+      // A cost figure ORC did not price itself is never printed: `usd` stays
+      // null rather than becoming a confident 0.
+      return { tasks, usd: priced ? usd : null, partial: st.size > want };
+    });
+  }
+
+  // ── Group F — flow and lanes. The diy lock is already read for the shipped
+  //    segment; `wait` is a small run-state file.
+  if (wants("wait.state")) {
+    SCAN.wait = cached("wait", TTL.run, () => {
+      const j = readJson(path.join(orc, "wait.json"));
+      if (!j) return "none";
+      if (j.block_reason) return "blocked";
+      return j.until || j.hops ? "waiting" : "none";
+    });
+  }
+  // `preset.name` is NOT read here: it rides in the compiled program, which is
+  // the only file that crosses the wall. The hook never opens the authored
+  // layout, and a field being convenient is not an exception to that.
+
+  // ── Group C remainder — the run's own progress, from RESUME.md, which is the
+  //    ONE line `orc resume` and `orc run list` parse. Reading the same line is
+  //    how a listing never has to open a checkpoint.
+  if (wants("run.wave") || wants("run.wave_total") || wants("run.resume") || wants("run.open")) {
+    SCAN.runs = cached("runs", TTL.run, () => {
+      let logRel = ".claude/orc/logs";
+      try {
+        const raw = fs.readFileSync(path.join(projectDir, ".claude", "orc.config.yaml"), "utf8");
+        const m = /^[ \t]*run_dir:[ \t]*["']?([^"'#\r\n]+)/m.exec(raw);
+        if (m) logRel = m[1].trim();
+      } catch (_) {}
+      const runDir = path.isAbsolute(logRel) ? logRel : path.join(projectDir, ".claude", "orc", "run");
+      let open = 0;
+      let wave = null;
+      let waves = null;
+      try {
+        for (const slug of fs.readdirSync(runDir)) {
+          const rp = path.join(runDir, slug, "RESUME.md");
+          if (!fs.existsSync(rp)) continue;
+          if (fs.existsSync(path.join(runDir, slug, "closed.json"))) continue;
+          open++;
+          // The byte-stable `Where it stands:` line, at column 0. It is the one
+          // line two other commands already parse, which is exactly why this
+          // does not open a checkpoint.
+          const m = /^Where it stands:.*wave (\d+) of (\d+)/m.exec(fs.readFileSync(rp, "utf8"));
+          if (m && wave == null) {
+            wave = Number(m[1]);
+            waves = Number(m[2]);
+          }
+        }
+      } catch (_) {
+        return null;
+      }
+      return { open, wave, waves, resume: open > 0 ? "waiting" : "none" };
+    });
+  }
+
+  // ── Group G — the health gates. Each is one small ledger, each on the slow
+  //    clock: a pact does not drift between keystrokes.
+  const gate = (key, file, fn) => {
+    if (!wants(key)) return null;
+    return cached(key.replace(/\./g, "_"), TTL.gates, () => fn(readJson(path.join(orc, file))));
+  };
+  SCAN.pact = gate("pact.state", "pact.json", (j) => {
+    if (!j || !Array.isArray(j.entries)) return null;
+    const live = j.entries.filter((e) => e.state !== "retired");
+    const broken = live.filter((e) => e.state === "broken").length;
+    const drifted = live.filter((e) => e.state === "drifted").length;
+    // UNCHECKABLE is the honest state and it never reads as a failure.
+    return { state: broken ? "broken" : drifted ? "drifted" : "holding", drifted, broken, total: live.length };
+  });
+  SCAN.boundary = gate("boundary.state", "boundary.json", (j) => {
+    if (!j || !Array.isArray(j.cards)) return null;
+    const refused = j.cards.filter((c) => c.verdict === "REFUSE").length;
+    // An area with no card is UNKNOWN, never assumed safe.
+    return { state: refused ? "refused" : "clear", refused, cards: j.cards.length };
+  });
+  SCAN.challenge = gate("challenge.state", "challenge.json", (j) => {
+    if (!j) return null;
+    const open = Array.isArray(j.findings) ? j.findings.filter((f) => !f.resolved).length : 0;
+    return { state: j.state || (open ? "open" : "pass"), open, iteration: j.iteration || null };
+  });
+  SCAN.doc = gate("doc.state", "doc.json", (j) => {
+    if (!j) return null;
+    const outline = Array.isArray(j.outline) ? j.outline : [];
+    const done = outline.filter((s) => s.hash).length;
+    return { state: j.shipped ? "shipped" : "draft", done, total: outline.length };
+  });
+
+  // `usage-gate` reads the usage bridge this hook already writes — so it is the
+  // cheapest `new read` in the set, and it is the only one that can say
+  // `unknown`, which is a real answer and never a stop.
+  if (wants("usage.state")) {
+    SCAN.usage = cached("usage", TTL.trace, () => {
+      const j = readJson(path.join(orc, "usage.json"));
+      if (!j || !j.written_at) return "unknown";
+      if (now - j.written_at > 30 * 60 * 1000) return "unknown";
+      const w = [j.five_hour, j.seven_day].filter(Boolean).map((x) => x.used_percentage);
+      if (!w.length) return "unknown";
+      return Math.max(...w) >= 90 ? "low" : "ok";
+    });
+  }
+
+  // A config key as a component. The config file is edited by hand, so 30s.
+  if (wants("config.value")) {
+    SCAN.config_raw = cached("config", TTL.config, () => {
+      try {
+        return fs.readFileSync(path.join(projectDir, ".claude", "orc.config.yaml"), "utf8");
+      } catch (_) {
+        return null;
+      }
+    });
+  }
+}
+
+// ── THE SERIES LEDGER (v1.3.0 W3) ──────────────────────────────────────────
+// `spark`, `spark-braille`, `trend` and `delta` need history, and a status line
+// has none: it is a fresh process every render. So the LAST 16 SAMPLES per
+// series live in the per-session ledger, appended during the throttled scan
+// that already ran.
+//
+// NO NEW READ, NO NEW TIMER. Every value sampled here was already computed for
+// something else this render; the series is a side effect of the scan, never a
+// reason for one.
+//
+// SIXTEEN, and only for the series a compiled layout actually names — the read
+// planner again. A series nothing binds is not kept, so the ledger does not
+// grow for a user whose layout has no sparkline on it.
+const SERIES_MAX = 16;
+const SERIES_MIN_GAP_MS = 20000;
+
+function sampleSeries(d, plan) {
+  try {
+    if (!plan || !plan.series || !plan.series.size) return;
+    const led = LED;
+    if (!led) return;
+    const now = Date.now();
+    // A sample every 20 seconds, not every render. Sixteen samples at the
+    // render rate would be five seconds of history, which is not history — it
+    // is the same number sixteen times.
+    if (led.series_at && now - led.series_at < SERIES_MIN_GAP_MS) return;
+    led.series_at = now;
+    led.series = led.series || {};
+    const push = (key, v) => {
+      if (!plan.series.has(key)) return;
+      if (typeof v !== "number" || !Number.isFinite(v)) return;
+      const arr = led.series[key] || [];
+      arr.push(Math.round(v));
+      while (arr.length > SERIES_MAX) arr.shift();
+      led.series[key] = arr;
+    };
+    const rl = d.rate_limits || {};
+    const w = led.five_hour;
+    push("quota5h", rl.five_hour && rl.five_hour.used_percentage);
+    push("quotawk", rl.seven_day && rl.seven_day.used_percentage);
+    push("ucs", w && typeof w.last === "number" && typeof w.baseline === "number"
+      ? Math.max(0, (w.accumulated || 0) + Math.max(0, w.last - w.baseline))
+      : null);
+    const tok = led.tok;
+    if (tok) {
+      push("mtok", (tok.input || 0) + (tok.cache_write || 0) + (tok.cache_read || 0) + (tok.output || 0));
+      push("mtokkind", tok.cache_read || 0);
+    }
+    push("agents", SCAN.spawns);
+    push("cost", d.cost && d.cost.total_cost_usd != null ? d.cost.total_cost_usd * 100 : null);
+    push("cachehit", d.prompt_cache && d.prompt_cache.hit_ratio != null
+      ? (d.prompt_cache.hit_ratio <= 1 ? d.prompt_cache.hit_ratio * 100 : d.prompt_cache.hit_ratio)
+      : null);
+    push("cachewrite", d.prompt_cache && d.prompt_cache.cache_write_tokens);
+    push("lines", d.cost && d.cost.total_lines_added != null
+      ? (d.cost.total_lines_added || 0) - (d.cost.total_lines_removed || 0)
+      : null);
+    push("extraspend", SCAN.extra_spend && SCAN.extra_spend.usd != null ? SCAN.extra_spend.usd * 100 : null);
+  } catch (_) {
+    // A series is a nicety. It never takes the status line down with it.
+  }
+}