heyspex 0.2.1 → 0.2.3

package/scripts/claude-statusline/statusline-command.mjs

@@ -0,0 +1,1058 @@
+#!/usr/bin/env node
+// HeySpex Claude Code statusline — renders a one-line footer with the
+// current model + context %, a sticky 2-6 word thread label, the pinned
+// focus epic, the git branch, and the most recent worked-on doc with its
+// pillar ("HS-<fileKey>-<familyKey>-<TYPE>"). Wired via `.claude/settings.json`
+// `statusLine.command` by `scripts/install-statusline.mjs`.
+//
+// Both the pinned-epic segment and the active-claim segment use the same
+// HeySpex marker (glyph at U+E000 when HeySpexIcons.ttf is installed and
+// HEYSPEX_STATUSLINE_GLYPH=1; plain `[HS]` otherwise). The earlier `▶`
+// claim prefix was retired so the two segments brand consistently.
+//
+// Contract:
+//   stdin  ← Claude Code session JSON (see code.claude.com/docs/en/statusline)
+//   stdout → one line of text (may contain ANSI / U+E000 glyph)
+//   exit 0 always — a failing statusline silently degrades, never breaks
+//                   Claude Code rendering.
+//
+// Data sources (all under $CLAUDE_PROJECT_DIR):
+//   GET <console>/api/control/pin — pin.specId (the pinned epic/milestone),
+//                                          read from Neon. Console URL comes from
+//                                          .heyspex/console-url (or HEYSPEX_CONSOLE_URL).
+//                                          Focus has no focus.yaml fallback
+//                                          ([[no-fallbacks-by-default]]); when the
+//                                          console is not running this segment is dropped.
+//
+// Focus-pin caching (hybrid push + pull, [[HS-RES-YCPL]]): Claude Code re-invokes
+// this script after every assistant message AND on the `refreshInterval` timer in
+// settings.json, so an uncached GET would hit the console dozens of times in a
+// burst during active sessions.
+//   - PUSH: the console's control-plane pin writers (setFocusPin/clearFocusPin)
+//     write the current pin to `.heyspex/statusline-focus-cache.json` on every
+//     change, so the file reflects the live pin within ms of a change.
+//   - PULL: within FOCUS_CACHE_TTL_MS we read that file with no HTTP at all
+//     (including a negative-cached null when the console is down); only past the
+//     TTL do we fall back to one GET to reconcile (console restarted, cache
+//     deleted, first run before any pin change), then rewrite the file.
+// Because push keeps the value fresh, the TTL is just a reconciliation interval —
+// default 60s, overridable via HEYSPEX_STATUSLINE_FOCUS_TTL_MS (0 = always fetch).
+//   .heyspex/active-claims.json  — claims[*].sessionId / specId / status (still
+//                                  file-backed pending its own Neon migration, [[HS-TASK-ACLM]]).
+//   .git (via `git branch --show-current`) — current branch
+//
+// Each segment degrades independently: an unreachable console / unreadable file
+// drops just that segment. The script never throws.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { isMainModule } from '../lib/shared-path-helpers.mjs';
+
+import { resolveActiveVault } from '../../vendor/heyspex-mcp/vault-resolve.mjs';
+
+// Entry-point guard (HS-IVJE): true only when this file is run directly as a script
+// (`node scripts/claude-statusline/statusline-command.mjs`, which is how Claude Code's
+// statusLine.command and the CLI invoke it) — false when another module `import`s it for
+// its exports (welcome.mjs imports `marker`/GLYPH/PLAIN_MARKER, HS-IVJE). Both the
+// off-switch below and the CLI dispatch at the bottom of the file are gated on it so an
+// import never triggers the off-switch's process.exit, stdin reads, git spawns, or stdout
+// writes that main() performs — side effects that belong to running the CLI, not to
+// reading its exports.
+const isDirectRun = isMainModule(import.meta.url);
+
+// HeySpex master off-switch (`hs mode off`). Every segment this script renders
+// — pinned epic, active claim, the [HS] marker — is HeySpex state, so when the
+// layer is off there is nothing honest left to draw: print nothing and let
+// Claude Code fall back to its own footer. Kept inline and first so the check
+// costs one small read, and fail-open so a corrupt state file can never blank
+// a statusline that should be live. Contract: scripts/heyspex-mode.mjs.
+if (isDirectRun) {
+  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+  let off = false;
+  try {
+    const raw = String(process.env.HEYSPEX_MODE ?? '').trim().toLowerCase();
+    off = raw
+      ? ['off', '0', 'false', 'disabled', 'disable', 'no'].includes(raw)
+      : JSON.parse(fs.readFileSync(path.join(repoRoot, '.heyspex', 'mode.json'), 'utf8'))?.mode === 'off';
+  } catch {
+    off = false;
+  }
+  if (off) process.exit(0);
+}
+
+export const GLYPH = ''; // Private-Use codepoint used by HeySpexIcons.ttf
+export const PLAIN_MARKER = '[HS]';
+// GitHub mark (MIT-licensed octicon) at U+E001 in HeySpexIcons.ttf — the
+// branch-segment prefix in glyph mode (owner ask 2026-08-12). Ships in the
+// same font as the brand glyph, so the U+E000 gate covers it too.
+const GITHUB_GLYPH = '';
+// Claude spark (12-ray starburst) at U+E002 - the model-segment prefix in
+// glyph mode (owner ask 2026-08-12). Same font, same gate.
+const CLAUDE_GLYPH = "";
+const GIT_TIMEOUT_MS = 300;
+const STDIN_TIMEOUT_MS = 200;
+const CONSOLE_TIMEOUT_MS = 400;
+
+// Reconciliation interval for the focus-pin cache (see header). The console pushes
+// every pin change to the cache file, so this is just how long we trust the file
+// before doing one reconciliation GET. Default 60s; HEYSPEX_STATUSLINE_FOCUS_TTL_MS
+// overrides (0 disables caching — every invocation fetches).
+const FOCUS_CACHE_TTL_MS = (() => {
+  const raw = Number(process.env.HEYSPEX_STATUSLINE_FOCUS_TTL_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : 60000;
+})();
+
+// A null result from a *pull* may be a transient miss (console cold-starting or
+// briefly down), so we trust it only briefly before retrying — unlike a real spec
+// id or a control-plane-pushed clear (source: "control-plane"), which are trusted
+// for the full window. Without this, one cold-route timeout would hide the pin for
+// a whole TTL.
+const FOCUS_CACHE_NEG_TTL_MS = Math.min(5000, FOCUS_CACHE_TTL_MS);
+
+function repoRoot() {
+  // $CLAUDE_PROJECT_DIR is set by Claude Code when this script runs as
+  // a statusLine command. Falling back to walking up from this file so
+  // the script also works when invoked directly for smoke-testing.
+  if (process.env.CLAUDE_PROJECT_DIR) return process.env.CLAUDE_PROJECT_DIR;
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+// Repo split (2026-08-31): specs/ lives in the vault repo, so the worked-doc
+// and pillar segments read it from the registry-resolved active vault when the
+// project root has none. Memoized — this script runs after every assistant
+// message. `.heyspex/` state files keep using repoRoot() (code-repo state).
+let _specsRootCache;
+function specsRootFor(root) {
+  if (_specsRootCache !== undefined) return _specsRootCache;
+  if (fs.existsSync(path.join(root, 'specs'))) {
+    _specsRootCache = root;
+    return root;
+  }
+  try {
+    const resolved = resolveActiveVault();
+    if (resolved?.specsDirAbs && fs.existsSync(resolved.specsDirAbs)) {
+      _specsRootCache = resolved.repoRootAbs;
+      return _specsRootCache;
+    }
+  } catch {
+    // resolver unavailable — degrade to the project root as before
+  }
+  _specsRootCache = root;
+  return root;
+}
+
+function readStdinSync() {
+  if (process.stdin.isTTY) return null;
+  try {
+    // Use a one-shot blocking read of fd 0; Claude Code closes stdin
+    // after piping the session JSON, so this returns immediately.
+    const chunks = [];
+    const buf = Buffer.alloc(65536);
+    while (true) {
+      let bytes;
+      try {
+        bytes = fs.readSync(0, buf, 0, buf.length, null);
+      } catch (err) {
+        if (err && err.code === 'EAGAIN') break;
+        break;
+      }
+      if (!bytes) break;
+      chunks.push(Buffer.from(buf.subarray(0, bytes)));
+      if (bytes < buf.length) break;
+    }
+    if (chunks.length === 0) return null;
+    return Buffer.concat(chunks).toString('utf8');
+  } catch {
+    return null;
+  }
+}
+
+function parseSession(raw) {
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+// Console base URL — the dev server publishes its bound URL to
+// `.heyspex/console-url` (ensure-next-dev.mjs); HEYSPEX_CONSOLE_URL overrides.
+// The file is removed when the dev server stops, so an absent pointer means
+// "console not running" → we skip the HTTP call entirely (no wait, no throw).
+function consoleUrl(root) {
+  const env = process.env.HEYSPEX_CONSOLE_URL;
+  if (env && env.trim()) return env.trim().replace(/\/+$/, '');
+  try {
+    const u = fs.readFileSync(path.join(root, '.heyspex', 'console-url'), 'utf8').trim();
+    if (u) return u.replace(/\/+$/, '');
+  } catch {
+    // Missing or unreadable — console not running.
+  }
+  return null;
+}
+
+// Cache file for the focus-pin result. Lives in the vault's `.heyspex/` (gitignored)
+// so the console's control-plane pin writers and this reader agree on one path
+// (statusline-focus-cache.ts → STATUSLINE_FOCUS_CACHE_BASENAME). Co-located with
+// the vault, so the temp+rename below stays on one filesystem (atomic rename).
+function focusCacheFile(root) {
+  return path.join(root, '.heyspex', 'statusline-focus-cache.json');
+}
+
+// Fresh-cache read. Returns `{ specId, telemetry }` on a hit within the TTL
+// (specId may be a string OR a negative-cached null; telemetry is the optional
+// block pushed by the console precompute), or `undefined` on miss/stale/
+// unreadable so the caller falls through to a live fetch.
+function readFocusCache(file) {
+  if (FOCUS_CACHE_TTL_MS === 0) return undefined;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed.at !== 'number') return undefined;
+    const specId = typeof parsed.specId === 'string' ? parsed.specId : null;
+    const ttl =
+      specId === null && parsed.source !== 'control-plane'
+        ? FOCUS_CACHE_NEG_TTL_MS
+        : FOCUS_CACHE_TTL_MS;
+    if (Date.now() - parsed.at >= ttl) return undefined;
+    return { specId, telemetry: parsed.telemetry };
+  } catch {
+    return undefined;
+  }
+}
+
+// Budget-warning threshold as a percentage of a plan rate-limit window. The
+// warning must trip BEFORE the cap, so the default is 80%.
+// HEYSPEX_STATUSLINE_BUDGET_WARN_PCT overrides.
+const BUDGET_WARN_PCT = (() => {
+  const raw = Number(process.env.HEYSPEX_STATUSLINE_BUDGET_WARN_PCT);
+  return Number.isFinite(raw) && raw > 0 && raw <= 100 ? raw : 80;
+})();
+
+// Live telemetry from the stdin session payload — the primary source, because it
+// is about THIS session, is always current, and costs nothing (Claude Code has
+// already computed it; see code.claude.com/docs/en/statusline). The console's
+// DB-backed feed remains the fallback for the cross-session aggregate.
+//
+// `context_window.total_input_tokens` already includes cache reads and writes;
+// adding output tokens gives total burn in the window. Both are 0 before the
+// first API response, and `rate_limits` is absent for non-subscription auth —
+// each is treated as "no signal", never as a zero worth rendering.
+//
+// Note on `burnSoFar`: this is "tokens currently loaded in the context window
+// as of the most recent API response," not a running total of everything ever
+// spent this session — it can go DOWN after a `/compact`. It is still always
+// scoped to this session/thread alone, never a weekly or cross-session figure
+// (that's `rate_limits.*.used_percentage`, which this script does not render).
+function sessionTelemetry(session) {
+  const cw = session?.context_window;
+  if (typeof cw?.total_input_tokens !== 'number') return null;
+  const out = typeof cw.total_output_tokens === 'number' ? cw.total_output_tokens : 0;
+  const cost = session?.cost?.total_cost_usd;
+  const pcts = [
+    session?.rate_limits?.five_hour?.used_percentage,
+    session?.rate_limits?.seven_day?.used_percentage,
+  ].filter((n) => typeof n === 'number');
+  return {
+    burnSoFar: cw.total_input_tokens + out,
+    ...(typeof cost === 'number' ? { costUSD: cost } : {}),
+    budgetWarning: pcts.some((p) => p >= BUDGET_WARN_PCT) || session?.exceeds_200k_tokens === true,
+  };
+}
+
+// Tokens + context segment ([[HS-4TLP]] + owner ask 2026-08-12): rendered as
+// "xxx tok * xx% used", unbranded (no glyph), dollar cost hidden. Token burn
+// comes from the live session payload when Claude Code piped one, else from
+// the optional `telemetry` block the console precompute pushes into the focus
+// cache; the context % is live-payload only. Untrusted input — each half is
+// rendered only when its shape is sane, and the segment is omitted entirely
+// when neither is available (never stale or invented numbers).
+//
+// `usedPct` is explicitly labeled "used" (owner report 2026-08-12: a bare
+// number here read as "% used" when it was actually `remaining_percentage`,
+// i.e. backwards from the natural reading). Computed as 100 - remaining so
+// the label always matches what's shown.
+function formatTelemetry(telemetry, usedPct) {
+  const burn = typeof telemetry?.burnSoFar === 'number' ? telemetry.burnSoFar : null;
+  const burnStr =
+    burn === null ? null
+    : burn >= 1_000_000 ? `${(burn / 1_000_000).toFixed(1)}M tok`
+    : burn >= 1_000 ? `${(burn / 1_000).toFixed(1)}k tok`
+    : `${burn} tok`;
+  const parts = [burnStr, typeof usedPct === 'number' ? `${usedPct}% used` : null].filter(
+    Boolean,
+  );
+  if (parts.length === 0) return null;
+  // Budget-warning ⚠ removed from this segment by owner ask 2026-08-12.
+  return parts.join(' · ');
+}
+
+// Best-effort atomic cache write: temp file in the same dir (so rename is atomic)
+// with a per-process-unique name, then rename into place. On Windows, concurrent
+// cross-process renames of a shared cache file can throw EPERM (write-file-atomic
+// #28); we already hold the value, so a failed write is harmless — clean up and
+// move on rather than retry or throw.
+function writeFocusCache(file, specId) {
+  if (FOCUS_CACHE_TTL_MS === 0) return;
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  // Carry the console-pushed `telemetry` block forward. This writer owns only the
+  // pin; without the read-back a pull-path refresh (every repaint on a cache miss)
+  // would drop telemetry the console precompute had pushed, and the segment could
+  // never survive to render.
+  let telemetry;
+  try {
+    telemetry = JSON.parse(fs.readFileSync(file, 'utf8'))?.telemetry;
+  } catch {
+    telemetry = undefined;
+  }
+  try {
+    fs.writeFileSync(
+      tmp,
+      JSON.stringify({
+        specId: specId ?? null,
+        at: Date.now(),
+        source: 'pull',
+        ...(telemetry ? { telemetry } : {}),
+      }),
+    );
+    fs.renameSync(tmp, file);
+  } catch {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+// Live focus-pin fetch from the console. Short timeout so a slow/absent console
+// never makes the statusline sluggish. Returns the spec id, or null when the
+// console is unreachable / has no pin.
+async function fetchPinnedSpecId(base) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), CONSOLE_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${base}/api/control/pin`, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const id = body?.pin?.specId;
+    return typeof id === 'string' && id ? id : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// The pinned focus spec id, read from Neon via the console. Focus has no
+// focus.yaml fallback ([[no-fallbacks-by-default]]) — when the console is not
+// running this returns null and the segment is simply dropped. A short-TTL file
+// cache (see header) collapses the per-message / per-refresh burst of statusline
+// invocations into at most one backend call per TTL window.
+async function readPinnedSpecId(root) {
+  const base = consoleUrl(root);
+  if (!base) return null;
+
+  const cacheFile = focusCacheFile(root);
+  const cached = readFocusCache(cacheFile);
+  if (cached) return cached.specId;
+
+  const specId = await fetchPinnedSpecId(base);
+  writeFocusCache(cacheFile, specId);
+  return specId;
+}
+
+// Session-matched only — deliberately no "most-recently-active claim"
+// cross-session fallback. That fallback was the original bug: every window
+// with no claim of its own showed whatever ANY agent/session last claimed,
+// so the segment never changed window to window. The live-relevance signal
+// (mostRecentTranscriptSpecRef, below) replaces it for the "nothing claimed
+// yet" case.
+function readActiveClaim(root, sessionId) {
+  if (!sessionId) return null;
+  try {
+    const raw = fs.readFileSync(path.join(root, '.heyspex', 'active-claims.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    const claims = parsed && typeof parsed === 'object' && parsed.claims ? parsed.claims : {};
+    for (const claim of Object.values(claims)) {
+      if (claim && claim.sessionId === sessionId) return claim;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// Most recent spec/task reference in the LIVE conversation — a HeySpex tool
+// call's spec_id argument, a Read/Edit/Write on a specs/ file, or a plain
+// HS-XXXX mention in real user text. Bounded tail read keeps cost flat
+// regardless of session length — "most relevant right now" only needs recent
+// activity, not full history. Scans backward and returns on the first hit,
+// so it's always the CHRONOLOGICALLY LAST reference in the window.
+//
+// Deliberately narrow about what counts as a "real" reference: only genuine
+// user text and specific tool-call arguments are scanned — never tool_result
+// content, system-reminder blocks, or CLAUDE.md dumps that get re-shown every
+// turn. Those are full of unrelated HS- ids (examples, cross-links, other
+// people's specs) that would otherwise hijack the segment.
+function mostRecentTranscriptSpecRef(transcriptPath) {
+  let raw;
+  try {
+    const size = fs.statSync(transcriptPath).size;
+    const len = Math.min(size, TRANSCRIPT_TAIL_BYTES);
+    const fd = fs.openSync(transcriptPath, 'r');
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, size - len);
+    fs.closeSync(fd);
+    raw = buf.toString('utf8');
+  } catch {
+    return null;
+  }
+  const lines = raw.split('\n').filter((l) => l.trim());
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let entry;
+    try {
+      entry = JSON.parse(lines[i]);
+    } catch {
+      continue; // torn line at the tail boundary — keep walking back
+    }
+    const isRealUser = entry?.type === 'user' && !entry.isMeta;
+    const content = entry?.message?.content;
+    if (isRealUser && typeof content === 'string') {
+      const id = specIdFromUserText(content);
+      if (id) return { specId: id, at: entry.timestamp };
+      continue;
+    }
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (!block) continue;
+      if (block.type === 'tool_use' && SPEC_TARGETING_TOOLS.has(block.name)) {
+        const id =
+          extractSpecIdToken(block.input?.spec_id) ??
+          extractSpecIdToken(block.input?.specId) ??
+          extractSpecIdToken(block.input?.id);
+        if (id) return { specId: id, at: entry.timestamp };
+      }
+      if (block.type === 'tool_use' && SPEC_FILE_TOOLS.has(block.name)) {
+        const fp = block.input?.file_path;
+        if (typeof fp === 'string' && /[\\/]specs[\\/].*\.md$/i.test(fp)) {
+          const id = extractSpecIdToken(basename(fp));
+          if (id) return { specId: id, at: entry.timestamp };
+        }
+      }
+      if (isRealUser && block.type === 'text') {
+        const id = specIdFromUserText(String(block.text || ''));
+        if (id) return { specId: id, at: entry.timestamp };
+      }
+    }
+  }
+  return null;
+}
+
+function specIdFromUserText(text) {
+  const clean = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim();
+  if (!clean || /^<(command-|local-command|task-notification|persisted-output)/.test(clean)) {
+    return null;
+  }
+  return extractSpecIdToken(clean);
+}
+
+// Cached wrapper: reuses the per-session label-cache file (one JSON file per
+// session already exists for the sticky thread label) so this doesn't add a
+// new file, and re-scans only when the transcript has actually grown since
+// last checked — the common case (idle between messages, a refreshInterval
+// tick with nothing new) costs a single fs.statSync, not a tail read.
+function relevantSpecFromTranscript(session) {
+  const sessionId = session?.session_id;
+  const transcript = session?.transcript_path;
+  if (!sessionId || !transcript) return null;
+  const file = labelCacheFile(sessionId);
+  const cache = readLabelCache(file);
+  let size;
+  try {
+    size = fs.statSync(transcript).size;
+  } catch {
+    return cache.relevantDoc ?? null;
+  }
+  if (cache.relevantDocScannedSize === size) return cache.relevantDoc ?? null;
+  const ref = mostRecentTranscriptSpecRef(transcript);
+  writeLabelCache(file, { ...cache, relevantDoc: ref ?? null, relevantDocScannedSize: size });
+  return ref;
+}
+
+// Picks the single most relevant spec for this thread right now: this
+// session's own claim vs. the live transcript reference, whichever is more
+// recent. A claim wins ties/indeterminate timestamps — it's the steadier,
+// cheaper signal (owner: "if a single file has been claimed, that will most
+// likely be the most relevant filename"). HEYSPEX_STATUSLINE_NO_CLAIM=1
+// disables the transcript scan, restricting the segment to explicit claims
+// only (name kept for backward compat with the original "suppress fallback"
+// meaning — the fallback it originally guarded no longer exists).
+function pickRelevantSpec(root, session) {
+  const claim = readActiveClaim(root, session?.session_id);
+  const claimAt = claim ? Date.parse(claim.lastActivityAt ?? claim.claimedAt ?? '') : NaN;
+  const ref = process.env.HEYSPEX_STATUSLINE_NO_CLAIM === '1'
+    ? null
+    : relevantSpecFromTranscript(session);
+  const refAt = ref?.at ? Date.parse(ref.at) : NaN;
+  if (claim && ref) {
+    return Number.isFinite(refAt) && Number.isFinite(claimAt) && refAt > claimAt
+      ? { specId: ref.specId }
+      : { specId: claim.specId };
+  }
+  if (claim) return { specId: claim.specId };
+  if (ref) return { specId: ref.specId };
+  return null;
+}
+
+function readGitBranch(root) {
+  try {
+    const res = spawnSync('git', ['-C', root, 'branch', '--show-current'], {
+      encoding: 'utf8',
+      timeout: GIT_TIMEOUT_MS,
+      windowsHide: true,
+    });
+    if (res.status !== 0) return null;
+    const out = (res.stdout || '').trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Where the OS keeps the per-user copy of the font, mirroring install-statusline.mjs. */
+function osFontPath() {
+  if (process.platform === 'win32') {
+    return process.env.LOCALAPPDATA
+      ? path.join(process.env.LOCALAPPDATA, 'Microsoft', 'Windows', 'Fonts', 'HeySpexIcons.ttf')
+      : null;
+  }
+  if (process.platform === 'darwin') return path.join(os.homedir(), 'Library', 'Fonts', 'HeySpexIcons.ttf');
+  return path.join(os.homedir(), '.fonts', 'HeySpexIcons.ttf');
+}
+
+export function marker(root, env = process.env) {
+  if (env.HEYSPEX_STATUSLINE_GLYPH !== '1') return PLAIN_MARKER;
+  // The gate is the OS-INSTALLED font, not the repo copy — only the installed
+  // one decides what the terminal can actually draw. Byte size stands in for
+  // identity here (a full hash on every 5s repaint is not worth it); it is
+  // enough to catch the failure this guards against: a machine still carrying
+  // an OLD single-glyph build renders the U+E001/U+E002 marks as boxes while
+  // the repo copy sits happily on disk. Mismatch → degrade to text, never tofu.
+  // Checked relative to THIS SCRIPT first — the TTF ships next to the renderer,
+  // and in a customer vault the renderer runs from the platform checkout while
+  // `root` is the customer repo (which has no scripts/ tree). Root-relative
+  // kept as the legacy fallback. See [[statusline-install-protocol]].
+  try {
+    const installed = osFontPath();
+    if (!installed || !fs.existsSync(installed)) return PLAIN_MARKER;
+    const installedSize = fs.statSync(installed).size;
+    const here = path.join(path.dirname(fileURLToPath(import.meta.url)), 'fonts', 'HeySpexIcons.ttf');
+    const ttf = fs.existsSync(here)
+      ? here
+      : path.join(root, 'scripts', 'claude-statusline', 'fonts', 'HeySpexIcons.ttf');
+    if (!fs.existsSync(ttf)) return PLAIN_MARKER;
+    if (fs.statSync(ttf).size === installedSize) return GLYPH;
+  } catch {
+    // fall through
+  }
+  return PLAIN_MARKER;
+}
+
+function basename(p) {
+  if (!p) return null;
+  return path.basename(p);
+}
+
+// ---------------------------------------------------------------------------
+// Worked-doc segment — "HS-<fileKey>-<familyKey>-<TYPE>" for the spec most
+// RELEVANT to this thread right now (owner ask 2026-08-13, correcting an
+// earlier claim-only design: [[HS-O6QA-RES-branded-coding-agent-statusline-customer]]).
+// "Relevant" is not "claimed" — it's whichever of these is more recent:
+//   1) this session's own active claim (session-matched only — a claim made
+//      by a DIFFERENT session/agent is never shown; that was the original bug
+//      report, every window showing the same stale cross-session claim).
+//   2) the most recent spec/task reference found by scanning the live
+//      transcript — a HeySpex tool call's spec_id argument, a Read/Edit/Write
+//      on a specs/ file, or a plain HS-XXXX mention in real user text. This
+//      is what lets the segment track a document being discussed/edited
+//      before (or instead of) being formally claimed, and update live as the
+//      conversation's focus moves — see mostRecentTranscriptSpecRef() below.
+// A single active claim is still the strongest, cheapest signal (owner:
+// "if a single file has been claimed, that will most likely be the most
+// relevant filename"), so it wins ties / indeterminate timestamps; the
+// transcript reference only overrides it when strictly more recent.
+// Claims/mentions carry only the short file key (e.g. HS-XKCD), so the id is
+// resolved against specs/ filenames to recover the doc type and family key;
+// resolution is cached because it scans the vault. Naming eras differ
+// ([[how-spec-ids-and-naming-work]]): the TYPE token's position tells the
+// era, so both eras are parsed positionally.
+
+const DOC_TYPE_LABELS = {
+  MIL: 'Milestone',
+  EPIC: 'Epic',
+  TASK: 'Task',
+  RES: 'Research',
+  CAP: 'Capture',
+  REV: 'Review',
+  DIAG: 'Diagnose',
+  DOC: 'Doc',
+  ADR: 'ADR',
+  PROTO: 'Protocol',
+};
+const KEY_RE = /^[A-Z0-9]{3,}$/;
+const DOC_CACHE_TTL_MS = 10 * 60 * 1000;
+const DOC_CACHE_NEG_TTL_MS = 60 * 1000; // a just-filed spec should appear within a minute
+
+// Matches a short spec/task key immediately after "HS-" — e.g. "HS-XKCD" out
+// of "HS-XKCD-3PSH-TASK-foo.md" or a plain-text "please look at HS-89JG".
+// \b naturally stops at the next hyphen, so this only ever captures the one
+// token right after "HS-", never the whole slug.
+const SPEC_ID_TOKEN_RE = /\bHS-([A-Z0-9]{3,})\b/i;
+// Tail-read bound for transcript scanning (see mostRecentTranscriptSpecRef) —
+// large enough to cover several recent turns even with big tool outputs
+// interspersed, small enough to keep every statusline tick fast.
+const TRANSCRIPT_TAIL_BYTES = 500_000;
+// HeySpex tool calls that name a spec directly — scanned for their spec_id
+// argument specifically (not free-text) so an unrelated id elsewhere in the
+// same tool-call JSON can't be picked up by accident.
+const SPEC_TARGETING_TOOLS = new Set([
+  'mcp__heyspex__heyspex_claim_spec',
+  'mcp__heyspex__heyspex_report_progress',
+  'mcp__heyspex__heyspex_submit_for_review',
+  'mcp__heyspex__heyspex_release_spec',
+  'mcp__heyspex__heyspex_defer_spec',
+  'mcp__heyspex__heyspex_record_wip',
+  'mcp__heyspex__heyspex_file_spec',
+]);
+const SPEC_FILE_TOOLS = new Set(['Read', 'Edit', 'Write']);
+
+function extractSpecIdToken(value) {
+  if (typeof value !== 'string') return null;
+  const m = SPEC_ID_TOKEN_RE.exec(value);
+  return m ? `HS-${m[1].toUpperCase()}` : null;
+}
+
+function docCacheFile(root) {
+  return path.join(root, '.heyspex', 'statusline-doc-cache.json');
+}
+
+function parseSpecBasename(base) {
+  const tokens = base.replace(/\.md$/i, '').split('-');
+  if ((tokens[0] || '').toUpperCase() === 'HS') tokens.shift();
+  const typeIdx = tokens.findIndex((t) => DOC_TYPE_LABELS[t.toUpperCase()]);
+  if (typeIdx === -1) return null;
+  const type = tokens[typeIdx].toUpperCase();
+  // Era 3 (file-key-first): <fileKey>-<familyKey>-<TYPE>-<slug>
+  if (typeIdx === 2 && KEY_RE.test(tokens[0]) && KEY_RE.test(tokens[1])) {
+    return { type, fileId: tokens[0], family: tokens[1] };
+  }
+  // Era 2 (family-first): <familyKey>-<TYPE>-<fileKey>-<slug>
+  if (typeIdx === 1 && KEY_RE.test(tokens[0]) && KEY_RE.test(tokens[2] ?? '')) {
+    return { type, fileId: tokens[2], family: tokens[0] };
+  }
+  // Legacy (e.g. 4-digit numeric epics): <id>-<TYPE>-<slug>
+  if (typeIdx === 1 && KEY_RE.test(tokens[0])) {
+    return { type, fileId: tokens[0], family: null };
+  }
+  return null;
+}
+
+/**
+ * Head of a spec file — enough to cover frontmatter without paying to read a
+ * whole doc on a 5s repaint. Frontmatter is read by regex on purpose: pulling a
+ * YAML parser into the renderer would cost more than the three fields we want.
+ */
+function readSpecHead(file) {
+  try {
+    const fd = fs.openSync(file, 'r');
+    try {
+      const buf = Buffer.alloc(4096);
+      const n = fs.readSync(fd, buf, 0, buf.length, 0);
+      return buf.toString('utf8', 0, n);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+
+function frontmatterField(head, field) {
+  if (!head) return null;
+  const m = new RegExp(`^${field}:[ \\t]*(.+)$`, 'm').exec(head);
+  if (!m) return null;
+  const value = m[1].trim().replace(/^['"]|['"]$/g, '').trim();
+  return value || null;
+}
+
+/** `[[HS-PILR-console-platform]]` → "Console platform" (the pillar's `name:`). */
+function pillarName(root, raw) {
+  const base = String(raw).replace(/^\[\[/, '').replace(/\]\]$/, '').trim();
+  if (!base) return null;
+  const name = frontmatterField(
+    readSpecHead(path.join(specsRootFor(root), 'specs', 'pillars', `${base}.md`)),
+    'name',
+  );
+  if (name) return name;
+  // Pillar file absent (customer vault, or renamed) — derive from the slug.
+  const slug = base.replace(/^HS-PILR-/i, '').replace(/-/g, ' ').trim();
+  return slug ? slug.charAt(0).toUpperCase() + slug.slice(1) : null;
+}
+
+/**
+ * Pillar of the worked doc. Only epics carry `pillar:` (entity-model), so a
+ * task inherits it by walking `parent:` upward. Two hops covers task → epic and
+ * the occasional task → task → epic without risking a cycle.
+ */
+function resolvePillar(root, specFile, byBasename) {
+  let file = specFile;
+  for (let hop = 0; hop < 3 && file; hop++) {
+    const head = readSpecHead(file);
+    const pillar = frontmatterField(head, 'pillar');
+    if (pillar) return pillarName(root, pillar);
+    const parent = frontmatterField(head, 'parent');
+    if (!parent) return null;
+    const base = parent.replace(/^\[\[/, '').replace(/\]\]$/, '').trim();
+    file = byBasename.get(base.toUpperCase()) ?? null;
+  }
+  return null;
+}
+
+// Resolve a short claim id (HS-XKCD) to its display form by scanning specs/
+// filenames for the key. Returns e.g. { display: "HS-XKCD-3PSH-TASK", pillar:
+// "Console platform" }; display falls back to the bare id when no file matches
+// (spec not on disk yet, or an unparseable name) and pillar to null.
+//
+// Display mirrors the FILENAME order — HS-<fileKey>-<familyKey>-<TYPE> (owner
+// ask 2026-08-14, replacing the earlier "Task: HS-XKCD-3PSH" prose form). That
+// is the type-suffixed variant sanctioned by the display contract in CLAUDE.md
+// ("with the type visible — suffixed, or as adjacent prose, never both"), and
+// it makes the segment copy-pasteable against `specs/` on disk.
+function resolveWorkedDoc(root, specId) {
+  const key = String(specId).replace(/^HS-/i, '').toUpperCase();
+  if (!KEY_RE.test(key)) return { display: specId, pillar: null };
+  const specsDir = path.join(specsRootFor(root), 'specs');
+  let entries;
+  try {
+    entries = fs.readdirSync(specsDir, { recursive: true });
+  } catch {
+    return { display: specId, pillar: null };
+  }
+  // One pass builds both the basename index (for the parent hop) and the match.
+  const byBasename = new Map();
+  let hit = null;
+  let familyHit = null;
+  for (const entry of entries) {
+    const rel = String(entry);
+    const base = path.basename(rel);
+    if (!/\.md$/i.test(base)) continue;
+    byBasename.set(base.replace(/\.md$/i, '').toUpperCase(), path.join(specsDir, rel));
+    if (!base.toUpperCase().includes(key)) continue;
+    const parsed = parseSpecBasename(base);
+    if (!parsed) continue;
+    const display = `HS-${parsed.fileId}${parsed.family ? `-${parsed.family}` : ''}-${parsed.type}`;
+    if (parsed.fileId.toUpperCase() === key) {
+      if (!hit) hit = { display, file: path.join(specsDir, rel) };
+    } else if (!familyHit && parsed.family && parsed.family.toUpperCase() === key) {
+      familyHit = { display, file: path.join(specsDir, rel) };
+    }
+  }
+  const match = hit ?? familyHit;
+  if (!match) return { display: specId, pillar: null };
+  return { display: match.display, pillar: resolvePillar(root, match.file, byBasename) };
+}
+
+/** { display, pillar } for the worked doc, cached — the resolve walks specs/. */
+function workedDoc(root, claim) {
+  const specId = claim?.specId;
+  if (!specId) return null;
+  const file = docCacheFile(root);
+  try {
+    const cached = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (cached?.specId === specId && typeof cached.display === 'string') {
+      const ttl = cached.resolved ? DOC_CACHE_TTL_MS : DOC_CACHE_NEG_TTL_MS;
+      if (Date.now() - (cached.at ?? 0) < ttl) {
+        return { display: cached.display, pillar: cached.pillar ?? null };
+      }
+    }
+  } catch {
+    // miss — resolve below
+  }
+  const resolved = resolveWorkedDoc(root, specId);
+  try {
+    fs.writeFileSync(
+      file,
+      JSON.stringify({
+        specId,
+        display: resolved.display,
+        pillar: resolved.pillar,
+        resolved: resolved.display !== specId,
+        at: Date.now(),
+      }),
+    );
+  } catch {
+    // cache write is best-effort
+  }
+  return resolved;
+}
+
+// ---------------------------------------------------------------------------
+// Sticky thread label — a 2-6 word summary of what this session is about
+// (owner ask 2026-08-12, capture [[HS-GWZ8]]). Deliberately sticky: a detached
+// background copy of this script (--refresh-label) asks Haiku to re-judge the
+// label only when new user messages exist, and the prompt rewrites it ONLY on
+// a genuine topic pivot — natural progress within one effort keeps the label.
+// The fast path reads a small per-session cache and never waits on the LLM.
+// Cache lives under ~/.claude/statusline-cache/ (machine state, not vault state).
+
+const LABEL_CHECK_INTERVAL_MS = 10_000;
+const LABEL_REFRESH_STALE_MS = 120_000; // consider a background refresh dead after this
+const LABEL_FAIL_BACKOFF_MS = 60_000;
+const LABEL_MAX_MSGS = 8;
+const LABEL_MAX_MSG_CHARS = 400;
+
+function labelCacheFile(sessionId) {
+  return path.join(os.homedir(), '.claude', 'statusline-cache', `${sessionId}.json`);
+}
+
+function readLabelCache(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8')) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function writeLabelCache(file, obj) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(obj));
+  } catch {
+    // best-effort — the statusline must never throw
+  }
+}
+
+// Real human turns only: skip meta entries, tool results, slash-command
+// wrappers, and system-reminder noise in the session transcript JSONL.
+function transcriptUserMessages(transcriptPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line.includes('"type":"user"')) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry.type !== 'user' || entry.isMeta) continue;
+    const content = entry.message?.content;
+    let text = '';
+    if (typeof content === 'string') text = content;
+    else if (Array.isArray(content))
+      text = content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n');
+    text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim();
+    if (!text) continue;
+    if (/^<(command-|local-command|task-notification|persisted-output)/.test(text)) continue;
+    if (text.startsWith('[Request interrupted')) continue;
+    out.push(text);
+  }
+  return out;
+}
+
+function sanitizeLabel(rawOutput) {
+  if (!rawOutput) return '';
+  let label = rawOutput.split('\n').map((l) => l.trim()).filter(Boolean)[0] || '';
+  label = label.replace(/^["'`]+|["'`.]+$/g, '').replace(/\s+/g, ' ').trim();
+  // Defense-in-depth for the "never a raw id" rule in labelPrompt() below —
+  // the id already has its own segment (see pickRelevantSpec); repeating it
+  // here defeats the label's whole purpose, a plain-English recall aid.
+  // Reject rather than strip: a title built around an id (e.g. "Promote
+  // HS-89JG") reads as broken with the id removed, so this forces a retry.
+  if (SPEC_ID_TOKEN_RE.test(label)) return '';
+  const words = label.split(' ');
+  if (words.length > 6) label = words.slice(0, 6).join(' ');
+  if (!label || label.length > 60) return '';
+  return label;
+}
+
+function labelPrompt(current, recent) {
+  const msgs = recent.map((m, i) => `${i + 1}. ${m}`).join('\n');
+  return [
+    'You maintain a short, sticky title for an ongoing coding-assistant session.',
+    '',
+    current ? `Current title: "${current}"` : 'Current title: none yet.',
+    '',
+    'Recent user messages, oldest to newest:',
+    msgs,
+    '',
+    'Rules:',
+    "- If there is no current title, write one: 2-6 plain words naming the session's main focus.",
+    '- If the current title still fits what the user is working on now, reply with the current title EXACTLY as given, unchanged.',
+    '- Only if the conversation has clearly pivoted to a different focus, write a new 2-6 word title for the new focus.',
+    '- Lean strongly toward keeping the current title. Natural progress, follow-ups, sub-steps, or debugging within the same effort are NOT a pivot.',
+    '- NEVER include a raw spec/task id (e.g. "HS-XKCD", "HS-89JG") in the title. Describe the actual work in plain words instead — the id already appears elsewhere in the footer, so repeating it here wastes the one thing this title is for: letting the user recall what the thread is about without decoding an id.',
+    '',
+    'Reply with ONLY the title text - no quotes, no trailing punctuation, no explanation.',
+  ].join('\n');
+}
+
+// Background child (--refresh-label): one Haiku call, then update the cache.
+function refreshLabel(cacheFile, transcriptPath, countStr) {
+  const count = Number(countStr) || 0;
+  const cache = readLabelCache(cacheFile);
+  const recent = transcriptUserMessages(transcriptPath)
+    .slice(-LABEL_MAX_MSGS)
+    .map((m) => (m.length > LABEL_MAX_MSG_CHARS ? `${m.slice(0, LABEL_MAX_MSG_CHARS)} …` : m));
+  if (recent.length === 0) {
+    writeLabelCache(cacheFile, { ...cache, refreshStartedAt: null });
+    return;
+  }
+  const res = spawnSync('claude -p --model haiku --strict-mcp-config', {
+    shell: true,
+    input: labelPrompt(cache.label || '', recent),
+    encoding: 'utf8',
+    timeout: 90_000,
+    windowsHide: true,
+    cwd: os.tmpdir(),
+  });
+  const label = res.status === 0 ? sanitizeLabel(res.stdout) : '';
+  const fresh = readLabelCache(cacheFile); // fast path may have bumped lastCheckAt meanwhile
+  if (label) {
+    writeLabelCache(cacheFile, {
+      ...fresh,
+      label,
+      msgCountAtLabel: count,
+      refreshStartedAt: null,
+      lastFailAt: null,
+      updatedAt: Date.now(),
+    });
+  } else {
+    writeLabelCache(cacheFile, { ...fresh, refreshStartedAt: null, lastFailAt: Date.now() });
+  }
+}
+
+// Fast path: return the cached label instantly; kick off a detached refresh
+// when new user messages exist and no refresh is already running.
+function threadLabel(session) {
+  const sessionId = session?.session_id;
+  const transcript = session?.transcript_path;
+  if (!sessionId) return null;
+  const file = labelCacheFile(sessionId);
+  const cache = readLabelCache(file);
+  const now = Date.now();
+  if (transcript && now - (cache.lastCheckAt ?? 0) > LABEL_CHECK_INTERVAL_MS) {
+    const count = transcriptUserMessages(transcript).length;
+    const refreshing =
+      cache.refreshStartedAt && now - cache.refreshStartedAt < LABEL_REFRESH_STALE_MS;
+    const backingOff = cache.lastFailAt && now - cache.lastFailAt < LABEL_FAIL_BACKOFF_MS;
+    if (
+      !refreshing &&
+      !backingOff &&
+      count > 0 &&
+      (!cache.label || count !== cache.msgCountAtLabel)
+    ) {
+      writeLabelCache(file, { ...cache, lastCheckAt: now, refreshStartedAt: now });
+      try {
+        const child = spawn(
+          process.execPath,
+          [fileURLToPath(import.meta.url), '--refresh-label', file, transcript, String(count)],
+          { detached: true, stdio: 'ignore', windowsHide: true },
+        );
+        child.unref();
+      } catch {
+        // label refresh is best-effort
+      }
+    } else {
+      writeLabelCache(file, { ...cache, lastCheckAt: now });
+    }
+  }
+  return typeof cache.label === 'string' && cache.label ? cache.label : null;
+}
+
+async function build(root, session) {
+  const segments = [];
+
+  const mark = marker(root);
+
+  // Segment order (owner ask 2026-08-14): Claude first, then GitHub, then the
+  // HeySpex items — left to right, harness → repo → vault.
+  const model = session?.model?.display_name;
+
+  const usedPct =
+    typeof session?.context_window?.remaining_percentage === 'number'
+      ? Math.round(100 - session.context_window.remaining_percentage)
+      : null;
+  // Model + tokens + context share one dot-joined segment (owner ask
+  // 2026-08-12): "Fable 5 · 162.0k tok · 38% used" — no pipe between model
+  // and token usage, and dots (not asterisks) inside the token/context pair.
+  const telemetrySegment = formatTelemetry(
+    sessionTelemetry(session) ?? readFocusCache(focusCacheFile(root))?.telemetry,
+    usedPct,
+  );
+  const modelSegment = [model, telemetrySegment].filter(Boolean).join(' · ');
+  if (modelSegment)
+    segments.push(mark === GLYPH ? `${CLAUDE_GLYPH} ${modelSegment}` : modelSegment);
+
+  // GitHub cluster: repo name + branch under one GitHub-mark prefix.
+  // Plain mode keeps the generic ⎇ ([HS] here would read as a claim segment).
+  const dir = basename(session?.workspace?.current_dir ?? session?.cwd) ?? basename(root);
+  const branch = readGitBranch(root);
+  const githubCluster = [dir, branch].filter(Boolean).join(' > ');
+  if (githubCluster) segments.push(`${mark === GLYPH ? GITHUB_GLYPH : '⎇'} ${githubCluster}`);
+
+  const pinned = await readPinnedSpecId(root);
+  if (pinned) segments.push(`${mark} ${pinned}`);
+
+  // HeySpex cluster, far right: "<glyph> <pillar> > <fileID> > <summary>"
+  // (owner ask 2026-08-14 added the pillar). Pillar: which perpetual area of
+  // the product this work belongs to, inherited from the worked doc's epic.
+  // Worked-doc: the spec most RELEVANT to this thread right now — this
+  // session's own claim vs. the live transcript reference, whichever is more
+  // recent (pickRelevantSpec, above) — so it updates as the conversation's
+  // focus moves, and never shows another session's claim.
+  // Summary: what this session is about, in 2-6 words (sticky, pivot-only).
+  const worked = workedDoc(root, pickRelevantSpec(root, session));
+  const label = threadLabel(session);
+  const heyspexCluster = [worked?.pillar, worked?.display, label].filter(Boolean).join(' > ');
+  if (heyspexCluster) segments.push(`${mark} ${heyspexCluster}`);
+
+  return segments.join(' | ');
+}
+
+async function main() {
+  try {
+    const root = repoRoot();
+    // stdin is read with a tiny timeout — if Claude Code didn't pipe
+    // session JSON (e.g. smoke-test from a shell), we still render the
+    // segments that don't depend on it.
+    const raw = readStdinSync();
+    const session = parseSession(raw);
+    if (process.env.HS_SL_DEBUG === '1') console.error('DEBUG raw:', JSON.stringify(raw));
+    const line = await build(root, session);
+    if (line) process.stdout.write(`${line}\n`);
+  } catch {
+    // Never break Claude Code — silent degrade.
+  }
+}
+
+if (isDirectRun) {
+  if (process.argv[2] === '--refresh-label') {
+    refreshLabel(process.argv[3], process.argv[4], process.argv[5]);
+  } else {
+    main();
+  }
+}