@d3ara1n/pi-editor-shell 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-editor-shell",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Replaces pi's default editor and status bar with a unified rounded-corner shell — no Nerd Font required",
   "keywords": [

package/src/card-editor.ts

@@ -58,24 +58,16 @@ export interface FrameSegments {
   bottomRight: string;
 }
 
-/** Fresh, already-themed segments. The frame color itself comes from pi's
- *  editor.borderColor field (same source as the default editor), kept in
- *  sync by pi on thinking-level / bash-mode changes — so the border
- *  matches the built-in behavior.
- *
- *  (An optional `frame` override exists for experiments; when omitted the
- *  editor falls back to editor.borderColor.) */
-export interface Frame {
-  segments: FrameSegments;
-  frame?: (s: string) => string;
-}
-
-/** Returns a fresh Frame on each render call. */
-export type FrameProvider = () => Frame;
+/** Fresh, already-themed segments on each render call. The frame color
+ *  itself always follows `this.borderColor` (pi keeps it in sync with the
+ *  thinking level / bash mode), so the provider only supplies text. */
+export type FrameProvider = () => FrameSegments;
 
-const EMPTY_FRAME: Frame = {
-  segments: { topLeft: "", topRight: "", bottomLeft: "", bottomRight: "" },
-  frame: (s) => s,
+const EMPTY_SEGMENTS: FrameSegments = {
+  topLeft: "",
+  topRight: "",
+  bottomLeft: "",
+  bottomRight: "",
 };
 
 /** Strip ANSI SGR escapes and pi's zero-width cursor marker so a line can
@@ -122,15 +114,25 @@ function fitFrameRow(
   const minGap = 3;
   let l = leftText;
   let r = rightText;
+  let lw = visibleWidth(l);
+  let rw = visibleWidth(r);
 
-  while (visibleWidth(l) + visibleWidth(r) + minGap > inner && visibleWidth(r) > 0) {
-    r = truncateToWidth(r, Math.max(0, visibleWidth(r) - 1), "");
-  }
-  while (visibleWidth(l) + visibleWidth(r) + minGap > inner && visibleWidth(l) > 0) {
-    l = truncateToWidth(l, Math.max(0, visibleWidth(l) - 1), "");
+  // Shrink right first, then left, so a minimum gap always survives —
+  // but at most one truncate per side instead of a per-character loop.
+  if (lw + rw + minGap > inner) {
+    const maxR = Math.max(0, inner - lw - minGap);
+    if (rw > maxR) {
+      r = truncateToWidth(r, maxR, "");
+      rw = visibleWidth(r);
+    }
+    const maxL = Math.max(0, inner - rw - minGap);
+    if (lw > maxL) {
+      l = truncateToWidth(l, maxL, "");
+      lw = visibleWidth(l);
+    }
   }
 
-  const gap = Math.max(0, inner - visibleWidth(l) - visibleWidth(r));
+  const gap = Math.max(0, inner - lw - rw);
   return `${border(leftCap)}${l}${border("─".repeat(gap))}${r}${border(rightCap)}`;
 }
 
@@ -172,11 +174,15 @@ export class CardEditor extends CustomEditor {
     this.spinnerPhase = phase;
     if (phase) {
       this.spinnerIdx = 0;
+      // One timer serves all phases: the callback re-reads spinnerPhase each
+      // tick so a thinking→outputting transition swaps frames without
+      // rebuilding the interval. The guard keeps TS happy; in practice phase
+      // is always set while the timer is live (cleared the instant it nulls).
       if (!this.spinnerTimer) {
         this.spinnerTimer = setInterval(() => {
-          const frames = this.spinnerPhase ? SPINNERS[this.spinnerPhase] : null;
-          if (!frames) return;
-          this.spinnerIdx = (this.spinnerIdx + 1) % frames.length;
+          const phase = this.spinnerPhase;
+          if (!phase) return;
+          this.spinnerIdx = (this.spinnerIdx + 1) % SPINNERS[phase].length;
           this.tui.requestRender();
         }, SPINNER_INTERVAL_MS);
       }
@@ -187,6 +193,13 @@ export class CardEditor extends CustomEditor {
     this.tui.requestRender();
   }
 
+  /** Request a re-render after external async state changes (e.g. git dirty
+   *  settling). The Editor's own TUI handle is protected, so callers outside
+   *  the class — like the extension's event handlers — go through here. */
+  requestRender(): void {
+    this.tui.requestRender();
+  }
+
   render(width: number): string[] {
     // Too narrow — delegate to the default rendering, untouched.
     if (width < MIN_WIDTH) {
@@ -198,17 +211,17 @@ export class CardEditor extends CustomEditor {
     const inner = super.render(width - 2);
     if (inner.length === 0) return inner;
 
-    // Border color: prefer the provider's override when given, otherwise
-    // fall back to pi's editor.borderColor (same field the default editor
-    // reads, updated by pi on thinking / bash changes).
-    const frameObj = this.frameProvider?.() ?? EMPTY_FRAME;
-    const border = frameObj.frame ?? this.borderColor;
-    const seg = frameObj.segments;
+    // Border color always follows this.borderColor — pi mutates it to encode
+    // thinking level / bash mode (same field the default editor reads), so
+    // the frame retints in lockstep with no extra wiring.
+    const border = this.borderColor;
+    const seg = this.frameProvider?.() ?? EMPTY_SEGMENTS;
     // While the agent is active, the current phase spinner replaces the
     // model text in the top-left slot — a moving indicator reads as "busy"
-    // more strongly than a static label.
+    // more strongly than a static label. spinnerIdx is kept in range by
+    // setSpinner's timer, so no modulo is needed here.
     const topLeft = this.spinnerPhase
-      ? `${RESET}${border(` ${SPINNERS[this.spinnerPhase][this.spinnerIdx % SPINNERS[this.spinnerPhase].length]} `)}${seg.topLeft.trimStart()}`
+      ? `${RESET}${border(` ${SPINNERS[this.spinnerPhase][this.spinnerIdx]} `)}${seg.topLeft.trimStart()}`
       : seg.topLeft;
 
     // The default Editor appends autocomplete rows *after* the bottom border.
@@ -241,25 +254,10 @@ export class CardEditor extends CustomEditor {
         // ctx/cwd always sit just under the editor. With a popup below, this
         // border becomes a T-junction divider; without one it's the rounded
         // bottom of the card.
-        out.push(
-          hasPopup
-            ? fitFrameRow(
-                GLYPH.divLeft,
-                GLYPH.divRight,
-                seg.bottomLeft,
-                seg.bottomRight,
-                width,
-                border,
-              )
-            : fitFrameRow(
-                GLYPH.bottomLeft,
-                GLYPH.bottomRight,
-                seg.bottomLeft,
-                seg.bottomRight,
-                width,
-                border,
-              ),
-        );
+        const [lc, rc] = hasPopup
+          ? [GLYPH.divLeft, GLYPH.divRight]
+          : [GLYPH.bottomLeft, GLYPH.bottomRight];
+        out.push(fitFrameRow(lc, rc, seg.bottomLeft, seg.bottomRight, width, border));
       } else {
         // Content row and popup items alike live inside the card. Reset around
         // the text so its styling never leaks into the frame and vice versa.

package/src/config.ts

@@ -1,8 +1,9 @@
 /**
  * Read editor-shell configuration from settings files.
  *
- * Global (~/.pi/agent/settings.json) + project (.pi/settings.json),
- * project overrides global.
+ * Global (~/.pi/agent/settings.json) + project (.pi/settings.json).
+ * Project settings, when present, override global wholesale — standard
+ * "project wins" design, no field-level merging.
  */
 
 import * as fs from "node:fs";
@@ -27,45 +28,32 @@ function getAgentDir(): string {
   return path.join(os.homedir(), ".pi", "agent");
 }
 
-function readSettingsFile(filePath: string): any {
+/** Read the `editorShell` block from a settings file.
+ *  Returns undefined on missing file / parse error / non-object value —
+ *  pi surfaces its own settings errors, this loader stays lenient. */
+function readEditorShell(filePath: string): Record<string, unknown> | undefined {
   try {
-    if (!fs.existsSync(filePath)) return {};
-    const content = fs.readFileSync(filePath, "utf-8");
-    return JSON.parse(content);
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"))?.editorShell;
+    return raw && typeof raw === "object" ? (raw as Record<string, unknown>) : undefined;
   } catch {
-    return {};
+    return undefined;
   }
 }
 
-function merge(target: any, source: any): any {
-  if (!source || typeof source !== "object") return target;
-  if (!target || typeof target !== "object") return source;
-  const result = { ...target };
-  for (const key of Object.keys(source)) {
-    if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key])) {
-      result[key] = merge(result[key], source[key]);
-    } else {
-      result[key] = source[key];
-    }
-  }
-  return result;
-}
-
 /**
- * Load editorShell config from merged settings.
+ * Load editorShell config. Project overrides global wholesale.
  * @param cwd - Project working directory
  */
 export function loadEditorShellConfig(cwd?: string): EditorShellConfig {
-  const globalSettings = readSettingsFile(path.join(getAgentDir(), "settings.json"));
-  const projectSettings = cwd ? readSettingsFile(path.join(cwd, ".pi", "settings.json")) : {};
-  const settings = merge(globalSettings, projectSettings);
-
-  const raw = settings?.editorShell;
+  const globalRaw = readEditorShell(path.join(getAgentDir(), "settings.json"));
+  const projectRaw = cwd ? readEditorShell(path.join(cwd, ".pi", "settings.json")) : undefined;
+  const raw = projectRaw ?? globalRaw;
   if (!raw) return { ...DEFAULT_CONFIG };
 
+  const pinned = raw.pinnedStatus;
   return {
-    pinnedStatus: Array.isArray(raw.pinnedStatus)
-      ? raw.pinnedStatus.filter((k: any) => typeof k === "string")
+    pinnedStatus: Array.isArray(pinned)
+      ? pinned.filter((k): k is string => typeof k === "string")
       : DEFAULT_CONFIG.pinnedStatus,
   };
 }

package/src/index.ts

@@ -1,6 +1,8 @@
 import type { ExtensionAPI, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { visibleWidth } from "@earendil-works/pi-tui";
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
+import * as os from "node:os";
+import * as path from "node:path";
 import { CardEditor, type FrameProvider, type SpinnerPhase } from "./card-editor";
 import { loadEditorShellConfig, type EditorShellConfig } from "./config";
 
@@ -15,10 +17,14 @@ import { loadEditorShellConfig, type EditorShellConfig } from "./config";
  * rainbow-editor, modal-editor, …). Disable those when enabling this one.
  */
 
-/** Collapse $HOME to `~` for display. */
+/** Collapse the user's home directory to `~` for display.
+ *  Uses os.homedir() + path.sep so it works across platforms and does not
+ *  match sibling dirs that merely share a string prefix with home. */
 function formatCwd(cwd: string): string {
-  const home = process.env.HOME;
-  if (home && cwd.startsWith(home)) return `~${cwd.slice(home.length)}`;
+  const home = os.homedir();
+  if (!home) return cwd;
+  if (cwd === home) return "~";
+  if (cwd.startsWith(home + path.sep)) return `~${cwd.slice(home.length)}`;
   return cwd;
 }
 
@@ -35,7 +41,7 @@ const THINKING_TOKEN: Record<string, ThemeColor> = {
 
 /** Context-fill severity by usage ratio — green / amber / red. */
 function contextToken(pct: number | null | undefined): ThemeColor {
-  if (pct === null || pct === undefined) return "muted";
+  if (pct == null) return "muted";
   if (pct >= 80) return "error";
   if (pct >= 50) return "warning";
   return "success";
@@ -43,28 +49,32 @@ function contextToken(pct: number | null | undefined): ThemeColor {
 
 // ── Nerd Font icons (Octicons + FontAwesome) ──────────────────────────
 const ICON = {
-  model: "\uf4bc", //   oct-cpu
-  thinking: "\uf400", //   oct-light-bulb
-  context: "\uf49b", //   oct-cache
+  model: "\uf4bc", //   oct-cpu
+  thinking: "\uf400", //   oct-light-bulb
+  context: "\uf49b", //   oct-cache
   cache: "\u26a1", // ⚡  oct-zap
-  folder: "\uf07c", //   fa-folder
+  hitRate: "\uf140", //   fa-bullseye（靶心，缓存命中率）
+  folder: "\uf07c", //   fa-folder
 } as const;
 
-/** Sum cache-read tokens across all assistant messages — same source and
- *  same accumulation as pi's own footer (which renders "R14M").
- *  Returns null when there is nothing to measure.
- *  Inline types avoid importing the full pi-ai message union tree. */
+/** Minimal inline types to read cache-read totals without importing the
+ *  full pi-ai message union tree. */
+interface UsageSnap {
+  input?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
 interface MsgSnap {
   role: string;
-  usage?: { cacheRead?: number };
+  usage?: UsageSnap;
 }
 interface EntrySnap {
   type: string;
   message?: MsgSnap;
 }
 
-/** Sum cache-read tokens across all assistant messages,
- *  matching pi's own footer filtering (type === "message"). */
+/** Sum cache-read tokens across all assistant messages, matching pi's own
+ *  footer filtering (type === "message") and accumulation ("R14M"). */
 function sumCacheRead(ctx: { sessionManager: { getEntries(): unknown[] } }): number {
   let total = 0;
   for (const entry of ctx.sessionManager.getEntries()) {
@@ -75,6 +85,28 @@ function sumCacheRead(ctx: { sessionManager: { getEntries(): unknown[] } }): num
   return total;
 }
 
+/** Usage of the most recent assistant message — drives the per-turn
+ *  cacheRead and the hit rate, matching pi's footer (last entry wins). */
+function latestAssistantUsage(ctx: { sessionManager: { getEntries(): unknown[] } }): UsageSnap | undefined {
+  let latest: UsageSnap | undefined;
+  for (const entry of ctx.sessionManager.getEntries()) {
+    const e = entry as EntrySnap;
+    if (e.type !== "message" || e.message?.role !== "assistant" || !e.message.usage) continue;
+    latest = e.message.usage;
+  }
+  return latest;
+}
+
+/** Cache hit rate for a single turn: cacheRead / (input + cacheRead +
+ *  cacheWrite) × 100 — same formula pi's footer uses for "CHxx%".
+ *  Returns undefined when there's no usage or no prompt tokens. */
+function cacheHitRate(u: UsageSnap | undefined): number | undefined {
+  if (!u) return undefined;
+  const prompt = (u.input ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+  if (prompt <= 0) return undefined;
+  return ((u.cacheRead ?? 0) / prompt) * 100;
+}
+
 /** Format a token count for display: 14000000 → "14.0M", 132000 → "132.0k". */
 function formatTokens(n: number): string {
   if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
@@ -90,34 +122,57 @@ interface GitDirty {
 }
 let _gitDirty: GitDirty | undefined;
 
-/** Run `git status --porcelain` and count staged / unstaged files. */
-function refreshGitDirty(cwd: string): void {
-  try {
-    const r = spawnSync(
-      "git",
-      ["--no-optional-locks", "status", "--porcelain"],
-      { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2000 },
-    );
-    if (r.status !== 0 || r.error) { _gitDirty = undefined; return; }
-    const lines = r.stdout.trim();
-    if (!lines) { _gitDirty = { staged: 0, unstaged: 0 }; return; }
-
-    let staged = 0;
-    let unstaged = 0;
-    for (const line of lines.split("\n")) {
-      if (line.length < 2) continue;
-      const x = line[0];
-      const y = line[1];
-      if (x !== " " && x !== "?" && x !== "!") staged++;
-      if (y !== " ") unstaged++;
-    }
-    _gitDirty = { staged, unstaged };
-  } catch {
-    _gitDirty = undefined;
+/** Parse `git status --porcelain` output into staged / unstaged counts. */
+function parseGitPorcelain(stdout: string): GitDirty {
+  const lines = stdout.trim();
+  if (!lines) return { staged: 0, unstaged: 0 };
+
+  let staged = 0;
+  let unstaged = 0;
+  for (const line of lines.split("\n")) {
+    if (line.length < 2) continue;
+    const x = line[0];
+    const y = line[1];
+    if (x !== " " && x !== "?" && x !== "!") staged++;
+    if (y !== " ") unstaged++;
   }
+  return { staged, unstaged };
+}
+
+/** Run `git status --porcelain` asynchronously so a slow / hanging git never
+ *  blocks the event loop (turn_end is the most latency-sensitive moment —
+ *  the agent just finished and the user wants to type). Updates `_gitDirty`
+ *  and invokes `onDone` once settled so the caller can trigger a re-render.
+ *  A 2s guard kills a runaway process. */
+function refreshGitDirty(cwd: string, onDone?: () => void): void {
+  const child = spawn(
+    "git",
+    ["--no-optional-locks", "status", "--porcelain"],
+    { cwd, stdio: ["ignore", "pipe", "ignore"] },
+  );
+  let stdout = "";
+  const timer = setTimeout(() => child.kill("SIGTERM"), 2000);
+
+  // spawn emits both 'error' (e.g. git missing → ENOENT) and a subsequent
+  // 'close'; guard so onDone fires exactly once.
+  let done = false;
+  const settle = (ok: boolean, out: string): void => {
+    if (done) return;
+    done = true;
+    clearTimeout(timer);
+    _gitDirty = ok ? parseGitPorcelain(out) : undefined;
+    onDone?.();
+  };
+
+  child.stdout?.on("data", (chunk: Buffer | string) => {
+    stdout += chunk;
+  });
+  child.on("error", () => settle(false, ""));
+  child.on("close", (code) => settle(code === 0, stdout));
 }
 
-/** Format dirty state as pi-style "+2 ~1" string, or "" if clean / unknown. */
+/** Format dirty state as pi-style "+2 ~1" string (leading space), or "" if
+ *  clean / unknown — ready to splice into a "(branch…)" segment. */
 function gitDirtyDisplay(): string {
   if (!_gitDirty) return "";
   const parts: string[] = [];
@@ -143,17 +198,16 @@ export default function (pi: ExtensionAPI) {
   let footerSnap: FooterSnap | undefined;
   // CWD cached from session_start — used by turn_end to refresh git dirty.
   let _cwd = "";
-
-  // ── Phase-aware spinner ────────────────────────────────────────
-  // Track which sub-phase the agent is in so we can pick the right
-  // spinner animation: thinking (●/○), outputting (sand-pile),
-  // toolcall drafting (arc rotation), tool execution (progress bar).
-  let _phase: SpinnerPhase | null = null;
-
-  pi.on("turn_start", () => {
-    _phase = "thinking";
-    editor?.setSpinner("thinking");
-  });
+  // cacheRead total + latest-turn usage, refreshed at session_start +
+  // agent_end. The render provider reads these instead of re-scanning
+  // entries every frame.
+  let _cacheTotal = 0;
+  let _latestUsage: UsageSnap | undefined;
+
+  // ── Phase-aware spinner + lifecycle ────────────────────────────
+  // Each event asks the editor for a phase; CardEditor.setSpinner is itself
+  // a same-phase no-op, so rapid event streams never reset the animation.
+  pi.on("turn_start", () => editor?.setSpinner("thinking"));
   pi.on("message_update", (event) => {
     const t = event.assistantMessageEvent.type;
     let next: SpinnerPhase;
@@ -161,77 +215,25 @@ export default function (pi: ExtensionAPI) {
     else if (t.startsWith("text_")) next = "outputting";
     else if (t.startsWith("toolcall_")) next = "toolcall";
     else return;
-    if (next !== _phase) {
-      _phase = next;
-      editor?.setSpinner(next);
-    }
+    editor?.setSpinner(next);
   });
-  pi.on("tool_execution_start", () => {
-    _phase = "exec";
-    editor?.setSpinner("exec");
-  });
-  pi.on("agent_end", () => {
-    _phase = null;
+  pi.on("tool_execution_start", () => editor?.setSpinner("exec"));
+  pi.on("agent_end", (_event, ctx) => {
+    // cacheRead totals + latest usage are stable once a turn finishes —
+    // recompute here instead of on every render frame.
+    _cacheTotal = sumCacheRead(ctx);
+    _latestUsage = latestAssistantUsage(ctx);
     editor?.setSpinner(null);
   });
   pi.on("session_shutdown", () => {
-    _phase = null;
     editor?.setSpinner(null);
     editor = undefined;
   });
 
-  // ── Debug command ──────────────────────────────────────────────
-  pi.registerCommand("editor-shell:status", {
-    description: "Show editor-shell debug state: status keys, pinned config, cache totals",
-    handler: async (_args, ctx) => {
-      const lines: string[] = [];
-
-      lines.push("[editor-shell config]");
-      lines.push(`  pinnedStatus: [${config.pinnedStatus.join(", ")}]`);
-
-      lines.push("");
-      lines.push("[extension statuses]");
-      if (footerSnap) {
-        const entries = Array.from(footerSnap.getExtensionStatuses().entries());
-        if (entries.length === 0) {
-          lines.push("  (none)");
-        } else {
-          const pinned = new Set(config.pinnedStatus);
-          for (const [key, text] of entries.sort(([a], [b]) => a.localeCompare(b))) {
-            const mark = pinned.has(key) ? " ← pinned" : "";
-            lines.push(`  ${key}: ${text}${mark}`);
-          }
-        }
-      } else {
-        lines.push("  (footer not initialized)");
-      }
-
-      lines.push("");
-      lines.push("[cache totals]");
-      const tokens = sumCacheRead(ctx);
-      lines.push(`  cacheRead: ${tokens > 0 ? formatTokens(tokens) : "0"}`);
-
-      lines.push("");
-      const cwd = ctx.cwd;
-      lines.push(`[context] cwd: ${cwd}`);
-      const branch = footerSnap?.getGitBranch();
-      lines.push(`  git branch: ${branch ?? "(not in repo)"}`);
-      if (branch) {
-        const ds = _gitDirty
-          ? `+${_gitDirty.staged} ~${_gitDirty.unstaged}`
-          : "(clean)";
-        lines.push(`  git dirty: ${ds}`);
-      }
-      const m = ctx.model;
-      lines.push(`  model: ${m ? `${m.provider}/${m.id}` : "none"}`);
-
-      ctx.ui.notify(lines.join("\n"), "info");
-    },
-  });
-
   // Refresh git dirty after every agent turn (tools may have changed files).
+  // Async — never blocks the event loop; re-renders once settled.
   pi.on("turn_end", () => {
-    if (_cwd) refreshGitDirty(_cwd);
+    if (_cwd) refreshGitDirty(_cwd, () => editor?.requestRender());
   });
 
   pi.on("session_start", (_event, ctx) => {
@@ -239,7 +241,9 @@ export default function (pi: ExtensionAPI) {
 
     _cwd = ctx.cwd;
     config = loadEditorShellConfig(ctx.cwd);
-    refreshGitDirty(ctx.cwd);
+    _cacheTotal = sumCacheRead(ctx);
+    _latestUsage = latestAssistantUsage(ctx);
+    refreshGitDirty(ctx.cwd, () => editor?.requestRender());
 
     // Fresh segments on every render — reads live ctx state, so thinking /
     // context % updates show up on the next paint without extra wiring.
@@ -247,6 +251,19 @@ export default function (pi: ExtensionAPI) {
     // the default editor's behavior.
     const provider: FrameProvider = () => {
       const theme = ctx.ui.theme;
+
+      // Resolve pinned status keys → already-themed text, " · "-joined.
+      const buildPinned = (): string => {
+        const keys = config.pinnedStatus;
+        if (keys.length === 0 || !footerSnap) return "";
+        const all = footerSnap.getExtensionStatuses();
+        const texts = keys
+          .map((k) => all.get(k))
+          .filter((s): s is string => s != null);
+        if (texts.length === 0) return "";
+        return ` ${texts.map((s) => theme.fg("muted", s)).join(theme.fg("dim", " · "))} `;
+      };
+
       const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "no model";
       const thinking = pi.getThinkingLevel();
       const thinkingColor = THINKING_TOKEN[thinking] ?? "muted";
@@ -255,15 +272,18 @@ export default function (pi: ExtensionAPI) {
       const pct = usage?.percent;
       const ctxWindow = usage?.contextWindow ?? ctx.model?.contextWindow;
       const ctxText =
-        pct !== null && pct !== undefined && ctxWindow
-          ? `${Math.round(pct)}%/${(ctxWindow / 1000).toFixed(0)}k`
+        pct != null && ctxWindow
+          ? `${pct.toFixed(1)}%/${(ctxWindow / 1000).toFixed(0)}k`
           : "?/??k";
 
-      // Cache-read token total — same data source pi's own footer uses for "R14M".
-      const cacheTokens = sumCacheRead(ctx);
+      // Cache-read tokens — per-turn figure first, session total in parens,
+      // then hit rate (pi's "CHxx%" formula). All refreshed at agent_end and
+      // read from cache off the hot path.
+      const cacheReadNow = _latestUsage?.cacheRead ?? 0;
+      const hitRate = cacheHitRate(_latestUsage);
       const cachePart =
-        cacheTokens > 0
-          ? `${theme.fg("dim", " · ")}${theme.fg("warning", `${ICON.cache} ${formatTokens(cacheTokens)}`)}`
+        _cacheTotal > 0
+          ? `${theme.fg("dim", " · ")}${theme.fg("warning", `${ICON.cache} ${formatTokens(cacheReadNow)} (${formatTokens(_cacheTotal)})${hitRate != null ? ` ${ICON.hitRate} ${hitRate.toFixed(1)}%` : ""}`)}`
           : "";
 
       // Git branch + dirty state — pi's format: ~/Projects (main).
@@ -275,29 +295,15 @@ export default function (pi: ExtensionAPI) {
           ? `${ICON.folder} ${cwdText} (${branch}${dirty})`
           : `${ICON.folder} ${cwdText}`;
 
+      // Model in accent; thinking label in its level token — same hue the
+      // border takes on, so switching levels visibly retints both together.
       return {
-        segments: {
-          // Model in accent; thinking label in its level token — same hue the
-          // border takes on, so switching levels visibly retints both together.
-          topLeft: ` ${theme.fg("accent", `${ICON.model} ${model}`)}${theme.fg("dim", " · ")}${theme.fg(thinkingColor, `${ICON.thinking} ${thinking}`)} `,
-          topRight: buildPinned(theme),
-          // Context in severity color; cwd stays muted so it never competes.
-          bottomLeft: ` ${theme.fg(contextToken(pct), `${ICON.context} ${ctxText}`)}${cachePart} `,
-          bottomRight: theme.fg("muted", ` ${cwdDisplay} `),
-        },
+        topLeft: ` ${theme.fg("accent", `${ICON.model} ${model}`)}${theme.fg("dim", " · ")}${theme.fg(thinkingColor, `${ICON.thinking} ${thinking}`)} `,
+        topRight: buildPinned(),
+        // Context in severity color; cwd stays muted so it never competes.
+        bottomLeft: ` ${theme.fg(contextToken(pct), `${ICON.context} ${ctxText}`)}${cachePart} `,
+        bottomRight: theme.fg("muted", ` ${cwdDisplay} `),
       };
-
-      /** Resolve pinned status keys → already-themed text, " · "-joined. */
-      function buildPinned(theme: typeof ctx.ui.theme): string {
-        const keys = config.pinnedStatus;
-        if (keys.length === 0 || !footerSnap) return "";
-        const all = footerSnap.getExtensionStatuses();
-        const texts = keys
-          .map((k) => all.get(k))
-          .filter((s): s is string => s != null);
-        if (texts.length === 0) return "";
-        return ` ${texts.map((s) => theme.fg("muted", s)).join(theme.fg("dim", " · "))} `;
-      }
     };
 
     // CardEditor has its own phase-aware spinner — hide pi's built-in working loader.
@@ -342,4 +348,67 @@ export default function (pi: ExtensionAPI) {
       };
     });
   });
+
+  // ── Debug command ──────────────────────────────────────────────
+  pi.registerCommand("editor-shell:status", {
+    description: "Show editor-shell debug state: status keys, pinned config, cache totals",
+    handler: async (_args, ctx) => {
+      const lines: string[] = [];
+
+      lines.push("[editor-shell config]");
+      lines.push(`  pinnedStatus: [${config.pinnedStatus.join(", ")}]`);
+
+      lines.push("");
+      lines.push("[extension statuses]");
+      if (footerSnap) {
+        const entries = Array.from(footerSnap.getExtensionStatuses().entries());
+        if (entries.length === 0) {
+          lines.push("  (none)");
+        } else {
+          const pinned = new Set(config.pinnedStatus);
+          for (const [key, text] of entries.sort(([a], [b]) => a.localeCompare(b))) {
+            // The pin marker sits after status text, whose embedded reset
+            // would wash it to default white — re-wrap it in dim so it stays
+            // consistent with the surrounding text. (status text itself
+            // keeps its original color by design.)
+            const mark = pinned.has(key) ? ctx.ui.theme.fg("dim", " ← pinned") : "";
+            lines.push(`  ${key}: ${text}${mark}`);
+          }
+        }
+      } else {
+        lines.push("  (footer not initialized)");
+      }
+
+      lines.push("");
+      lines.push("[cache totals]");
+      const tokens = sumCacheRead(ctx);
+      lines.push(`  cacheRead (session): ${tokens > 0 ? formatTokens(tokens) : "0"}`);
+      const latest = latestAssistantUsage(ctx);
+      const now = latest?.cacheRead ?? 0;
+      lines.push(`  cacheRead (this turn): ${formatTokens(now)}`);
+      const hr = cacheHitRate(latest);
+      lines.push(`  hit rate: ${hr != null ? `${hr.toFixed(1)}%` : "n/a"}`);
+
+      lines.push("");
+      lines.push(`[context] cwd: ${ctx.cwd}`);
+      const branch = footerSnap?.getGitBranch();
+      lines.push(`  git branch: ${branch ?? "(not in repo)"}`);
+      if (branch) {
+        const dirty = gitDirtyDisplay().trim();
+        lines.push(`  git dirty: ${dirty || "clean"}`);
+      }
+      const m = ctx.model;
+      lines.push(`  model: ${m ? `${m.provider}/${m.id}:${pi.getThinkingLevel()}` : "none"}`);
+
+      // Wrap each line in dim explicitly. notify adds its own outer dim
+      // layer, but extension status text carries its own color codes that
+      // reset the foreground mid-message. Per-line wrapping re-asserts dim
+      // at the start of every line, so a status row's reset can't bleed past
+      // it: status stays in its original color, everything else reads dim.
+      ctx.ui.notify(
+        lines.map((l) => ctx.ui.theme.fg("dim", l)).join("\n"),
+        "info",
+      );
+    },
+  });
 }