@selesai/code 0.5.28 → 0.5.29

package/dist/extensions/pi-intercom/broker/spawn.ts

@@ -1,15 +1,25 @@
 import { spawn } from "child_process";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
-import { createRequire } from "module";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { createRequire } from "module";
 import net from "net";
-import { getBrokerSocketPath, getIntercomDir } from "./paths.js";
-
-const require = createRequire(import.meta.url);
-const INTERCOM_DIR = getIntercomDir();
+import { randomUUID } from "crypto";
+import { createMessageReader, writeMessage } from "./framing.ts";
+import {
+  ensureIntercomRuntimeDir,
+  getAgentDirPath,
+  getBrokerConnectTarget,
+  getIntercomDirPath,
+  INTERCOM_PROTOCOL_NAME,
+  INTERCOM_PROTOCOL_VERSION,
+  INTERCOM_RUNTIME_FILE_MODE,
+  restrictIntercomRuntimeFile,
+  type BrokerConnectTarget,
+} from "./paths.ts";
+
+const INTERCOM_DIR = getIntercomDirPath();
 const EXTENSION_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
-const BROKER_SOCKET = getBrokerSocketPath();
 const BROKER_PID = join(INTERCOM_DIR, "broker.pid");
 const BROKER_SPAWN_LOCK = join(INTERCOM_DIR, "broker.spawn.lock");
 
@@ -31,8 +41,19 @@ function sleep(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-export function getTsxCliPath(): string {
-  return require.resolve("tsx/cli");
+export function getTsxCliPath(extensionDir: string = EXTENSION_DIR): string {
+  // Resolve tsx via Node's module resolution so it works regardless of whether
+  // tsx is bundled under extensionDir/node_modules or hoisted to a workspace
+  // root by npm. We resolve the tsx package main entry (its "exports" field
+  // does not expose ./dist/cli.mjs as a subpath) and then locate cli.mjs next
+  // to it. Falls back to the legacy relative path if resolution fails.
+  try {
+    const requireFromExtension = createRequire(import.meta.url);
+    const tsxMain = requireFromExtension.resolve("tsx");
+    return join(dirname(tsxMain), "cli.mjs");
+  } catch {
+    return join(extensionDir, "node_modules", "tsx", "dist", "cli.mjs");
+  }
 }
 
 function quoteWindowsArg(value: string): string {
@@ -50,6 +71,13 @@ function usesDefaultBrokerCommand(brokerCommand: string, brokerArgs: string[]):
     && brokerArgs[1] === "tsx";
 }
 
+function getNodeCommand(nodePath: string): string {
+  const executableName = nodePath.split(/[\\/]/).pop();
+  return executableName && /^node(?:js)?(?:\.exe)?$/i.test(executableName)
+    ? nodePath
+    : "node";
+}
+
 export function getWindowsBrokerCommandLine(
   brokerPath: string,
   extensionDir: string = EXTENSION_DIR,
@@ -58,7 +86,7 @@ export function getWindowsBrokerCommandLine(
   brokerArgs: string[] = ["--no-install", "tsx"],
 ): string {
   if (usesDefaultBrokerCommand(brokerCommand, brokerArgs)) {
-    return [quoteWindowsArg(nodePath), quoteWindowsArg(getTsxCliPath()), quoteWindowsArg(brokerPath)].join(" ");
+    return [quoteWindowsArg(getNodeCommand(nodePath)), quoteWindowsArg(getTsxCliPath(extensionDir)), quoteWindowsArg(brokerPath)].join(" ");
   }
 
   return [quoteWindowsArg(brokerCommand), ...brokerArgs.map(quoteWindowsArg), quoteWindowsArg(brokerPath)].join(" ");
@@ -73,12 +101,27 @@ export function getWindowsHiddenLauncherScript(commandLine: string): string {
   ].join("\r\n");
 }
 
+export function isBrokerHealthOkMessage(message: unknown, requestId: string): boolean {
+  if (typeof message !== "object" || message === null || !("type" in message)) {
+    return false;
+  }
+  const response = message as Record<string, unknown>;
+  return response.type === "health_ok"
+    && response.requestId === requestId
+    && response.protocol === INTERCOM_PROTOCOL_NAME
+    && response.version === INTERCOM_PROTOCOL_VERSION;
+}
+
 function writeWindowsHiddenLauncher(
   commandLine: string,
   launcherPath: string = getWindowsHiddenLauncherPath(),
 ): string {
-  mkdirSync(dirname(launcherPath), { recursive: true });
-  writeFileSync(launcherPath, getWindowsHiddenLauncherScript(commandLine), "utf-8");
+  ensureIntercomRuntimeDir(dirname(launcherPath));
+  writeFileSync(launcherPath, getWindowsHiddenLauncherScript(commandLine), {
+    encoding: "utf-8",
+    mode: INTERCOM_RUNTIME_FILE_MODE,
+  });
+  restrictIntercomRuntimeFile(launcherPath);
   return launcherPath;
 }
 
@@ -102,6 +145,14 @@ export function getBrokerLaunchSpec(
     };
   }
 
+  if (usesDefaultBrokerCommand(brokerCommand, brokerArgs)) {
+    return {
+      kind: "direct",
+      command: getNodeCommand(nodePath),
+      args: [getTsxCliPath(extensionDir), brokerPath],
+    };
+  }
+
   return {
     kind: "direct",
     command: brokerCommand,
@@ -109,7 +160,10 @@ export function getBrokerLaunchSpec(
   };
 }
 
-export function getBrokerSpawnOptions(extensionDir: string = EXTENSION_DIR): {
+export function getBrokerSpawnOptions(
+  extensionDir: string = EXTENSION_DIR,
+  env: NodeJS.ProcessEnv = process.env,
+): {
   detached: true;
   stdio: "ignore";
   cwd: string;
@@ -120,7 +174,7 @@ export function getBrokerSpawnOptions(extensionDir: string = EXTENSION_DIR): {
     detached: true,
     stdio: "ignore",
     cwd: extensionDir,
-    env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    env: { ...env, SELESAI_CODING_AGENT_DIR: getAgentDirPath(env), NODE_NO_WARNINGS: "1" },
     windowsHide: true,
   };
 }
@@ -130,7 +184,7 @@ function toError(error: unknown): Error {
 }
 
 export async function spawnBrokerIfNeeded(brokerCommand: string, brokerArgs: string[]): Promise<void> {
-  mkdirSync(INTERCOM_DIR, { recursive: true });
+  ensureIntercomRuntimeDir(INTERCOM_DIR);
 
   if (await isBrokerRunning()) {
     return;
@@ -211,29 +265,57 @@ async function isBrokerRunning(): Promise<boolean> {
   }
 }
 
+function connectToBrokerTarget(target: BrokerConnectTarget): net.Socket {
+  return typeof target === "string"
+    ? net.connect(target)
+    : net.connect({ host: target.host, port: target.port });
+}
+
 function checkSocketConnectable(): Promise<boolean> {
   return new Promise((resolve) => {
-    const socket = net.connect(BROKER_SOCKET);
+    let target: BrokerConnectTarget;
+    try {
+      target = getBrokerConnectTarget();
+    } catch {
+      resolve(false);
+      return;
+    }
+
+    const socket = connectToBrokerTarget(target);
+    const requestId = randomUUID();
+    const expectedStateId = typeof target === "string" ? undefined : target.stateId;
+    let settled = false;
     const finish = (isConnected: boolean) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
       clearTimeout(timeout);
       socket.off("connect", onConnect);
       socket.off("error", onError);
+      socket.off("data", reader);
+      socket.destroy();
       resolve(isConnected);
     };
     const onConnect = () => {
-      socket.end();
-      finish(true);
-    };
-    const onError = () => {
-      socket.destroy();
-      finish(false);
+      try {
+        writeMessage(socket, {
+          type: "health",
+          requestId,
+          ...(expectedStateId ? { stateId: expectedStateId } : {}),
+        });
+      } catch {
+        finish(false);
+      }
     };
+    const onError = () => finish(false);
+    const reader = createMessageReader((message) => {
+      finish(isBrokerHealthOkMessage(message, requestId));
+    }, () => finish(false));
     socket.on("connect", onConnect);
     socket.on("error", onError);
-    const timeout = setTimeout(() => {
-      socket.destroy();
-      finish(false);
-    }, 1000);
+    socket.on("data", reader);
+    const timeout = setTimeout(() => finish(false), 1000);
   });
 }
 
@@ -241,7 +323,11 @@ function acquireSpawnLock(): boolean {
   const maxRetries = 5;
   for (let attempt = 0; attempt < maxRetries; attempt++) {
     try {
-      writeFileSync(BROKER_SPAWN_LOCK, `${process.pid}\n${Date.now()}\n`, { flag: "wx" });
+      writeFileSync(BROKER_SPAWN_LOCK, `${process.pid}\n${Date.now()}\n`, {
+        flag: "wx",
+        mode: INTERCOM_RUNTIME_FILE_MODE,
+      });
+      restrictIntercomRuntimeFile(BROKER_SPAWN_LOCK);
       return true;
     } catch (error) {
       if (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== "EEXIST") {

package/dist/extensions/pi-intercom/config.test.ts

@@ -0,0 +1,93 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getConfigPath, loadConfig } from "./config.ts";
+
+async function withAgentDir<T>(agentDir: string, fn: () => T | Promise<T>): Promise<T> {
+  const previousAgentDir = process.env.SELESAI_CODING_AGENT_DIR;
+  process.env.SELESAI_CODING_AGENT_DIR = agentDir;
+  try {
+    return await fn();
+  } finally {
+    if (previousAgentDir === undefined) delete process.env.SELESAI_CODING_AGENT_DIR;
+    else process.env.SELESAI_CODING_AGENT_DIR = previousAgentDir;
+  }
+}
+
+test("getConfigPath uses the centralized intercom runtime directory", () => {
+  assert.equal(getConfigPath("/tmp/pi-agent/intercom"), join("/tmp/pi-agent", "intercom", "config.json"));
+});
+
+test("loadConfig reads config below SELESAI_CODING_AGENT_DIR", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
+
+  try {
+    const intercomDir = join(root, "intercom");
+    mkdirSync(intercomDir, { recursive: true });
+    writeFileSync(join(intercomDir, "config.json"), JSON.stringify({ status: "platform-test" }));
+
+    await withAgentDir(root, () => {
+      assert.equal(loadConfig().status, "platform-test");
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("loadConfig defaults inboundTrigger to current auto-trigger behavior", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
+  try {
+    await withAgentDir(root, () => {
+      assert.equal(loadConfig().inboundTrigger, "always");
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("loadConfig accepts inboundTrigger replies policy", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
+  try {
+    mkdirSync(join(root, "intercom"), { recursive: true });
+    writeFileSync(join(root, "intercom", "config.json"), JSON.stringify({ inboundTrigger: "replies" }));
+    await withAgentDir(root, () => {
+      assert.equal(loadConfig().inboundTrigger, "replies");
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("loadConfig accepts a restart-stable intercom id", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
+  try {
+    mkdirSync(join(root, "intercom"), { recursive: true });
+    writeFileSync(join(root, "intercom", "config.json"), JSON.stringify({ stableId: " pinned-worker " }));
+    await withAgentDir(root, () => {
+      assert.equal(loadConfig().stableId, "pinned-worker");
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("loadConfig rejects invalid inboundTrigger values by failing closed", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
+  try {
+    mkdirSync(join(root, "intercom"), { recursive: true });
+    writeFileSync(join(root, "intercom", "config.json"), JSON.stringify({ inboundTrigger: "prompt" }));
+    const previousError = console.error;
+    console.error = () => undefined;
+    try {
+      await withAgentDir(root, () => {
+        assert.equal(loadConfig().inboundTrigger, "never");
+      });
+    } finally {
+      console.error = previousError;
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/dist/extensions/pi-intercom/config.ts

@@ -1,6 +1,23 @@
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
-import { getIntercomDir } from "./broker/paths.js";
+import { getIntercomDirPath } from "./broker/paths.ts";
+
+export const DEFAULT_ASK_TIMEOUT_MS = 10 * 60 * 1000;
+
+export function getAskTimeoutMs(): number {
+  const raw = process.env.PI_INTERCOM_ASK_TIMEOUT_MS;
+  if (raw === undefined || raw.trim() === "") {
+    return DEFAULT_ASK_TIMEOUT_MS;
+  }
+
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error("PI_INTERCOM_ASK_TIMEOUT_MS must be a positive integer number of milliseconds");
+  }
+  return value;
+}
+
+export type InboundTriggerPolicy = "always" | "replies" | "never";
 
 export interface IntercomConfig {
   /** Broker command used to spawn the broker process (e.g. "npx" or "bun") */
@@ -12,8 +29,14 @@ export interface IntercomConfig {
   /** Require confirmation before non-reply sends from interactive sessions */
   confirmSend: boolean;
 
+  /** Controls whether inbound broker messages may automatically trigger a model turn */
+  inboundTrigger: InboundTriggerPolicy;
+
   /** Optional custom status suffix shown after automatic lifecycle status */
   status?: string;
+
+  /** Optional stable intercom session ID for restart-stable addressing */
+  stableId?: string;
   
   /** Enable/disable intercom (default: true) */
   enabled: boolean;
@@ -22,23 +45,27 @@ export interface IntercomConfig {
   replyHint: boolean;
 }
 
-const CONFIG_PATH = join(getIntercomDir(), "config.json");
+export function getConfigPath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "config.json");
+}
 
 const defaults: IntercomConfig = {
   brokerCommand: "npx",
   brokerArgs: ["--no-install", "tsx"],
   confirmSend: false,
+  inboundTrigger: "always",
   enabled: true,
   replyHint: true,
 };
 
 export function loadConfig(): IntercomConfig {
-  if (!existsSync(CONFIG_PATH)) {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) {
     return { ...defaults };
   }
   
   try {
-    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    const raw = readFileSync(configPath, "utf-8");
     const parsed: unknown = JSON.parse(raw);
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
       throw new Error("Config must be a JSON object");
@@ -86,6 +113,17 @@ export function loadConfig(): IntercomConfig {
       config.enabled = parsedConfig.enabled;
     }
 
+    if (Object.hasOwn(parsedConfig, "inboundTrigger")) {
+      if (
+        parsedConfig.inboundTrigger !== "always"
+        && parsedConfig.inboundTrigger !== "replies"
+        && parsedConfig.inboundTrigger !== "never"
+      ) {
+        throw new Error(`"inboundTrigger" must be "always", "replies", or "never"`);
+      }
+      config.inboundTrigger = parsedConfig.inboundTrigger;
+    }
+
     if (Object.hasOwn(parsedConfig, "replyHint")) {
       if (typeof parsedConfig.replyHint !== "boolean") {
         throw new Error(`"replyHint" must be a boolean`);
@@ -100,9 +138,20 @@ export function loadConfig(): IntercomConfig {
       config.status = parsedConfig.status;
     }
 
+    if (Object.hasOwn(parsedConfig, "stableId")) {
+      if (typeof parsedConfig.stableId !== "string") {
+        throw new Error(`"stableId" must be a string`);
+      }
+      const stableId = parsedConfig.stableId.trim();
+      if (!stableId) {
+        throw new Error(`"stableId" must not be empty`);
+      }
+      config.stableId = stableId;
+    }
+
     return config;
   } catch (error) {
-    console.error(`Failed to load intercom config at ${CONFIG_PATH}:`, error);
-    return { ...defaults };
+    console.error(`Failed to load intercom config at ${configPath}:`, error);
+    return { ...defaults, inboundTrigger: "never" };
   }
 }

package/dist/extensions/pi-intercom/cwd.test.ts

@@ -0,0 +1,40 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, symlinkSync, mkdirSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { normalizeCwd, sameCwd } from "./cwd.ts";
+
+test("sameCwd collapses a trailing slash", () => {
+  assert.equal(sameCwd("/usr/local", "/usr/local/"), true);
+});
+
+test("sameCwd collapses lexical '.' and '..' segments", () => {
+  assert.equal(sameCwd("/usr/local/../local/./bin", "/usr/local/bin"), true);
+});
+
+test("sameCwd treats genuinely different directories as different", () => {
+  assert.equal(sameCwd("/usr/local", "/usr/lib"), false);
+});
+
+test("sameCwd collapses a symlink to its real target", () => {
+  const base = mkdtempSync(join(tmpdir(), "cwd-symlink-"));
+  try {
+    const real = join(base, "real");
+    const link = join(base, "link");
+    mkdirSync(real);
+    symlinkSync(real, link);
+    // Reached via the symlink vs its canonical path — must compare equal.
+    assert.equal(sameCwd(link, real), true);
+    // And normalizeCwd resolves the link to the real path.
+    assert.equal(normalizeCwd(link), realpathSync(real));
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("normalizeCwd falls back to the resolved path for a nonexistent dir", () => {
+  // realpathSync throws for a missing dir; normalizeCwd must still collapse the
+  // lexical variants rather than throw.
+  assert.equal(normalizeCwd("/no/such/dir/../dir"), "/no/such/dir");
+});

package/dist/extensions/pi-intercom/cwd.ts

@@ -0,0 +1,31 @@
+import { resolve } from "node:path";
+import { realpathSync } from "node:fs";
+
+// Normalize a cwd for same-directory comparison. A raw string match ("a === b")
+// hides genuine same-directory peers when two cwd strings differ only by a
+// trailing slash, a "."/".." segment, or a symlink (e.g. macOS /tmp <->
+// /private/tmp). resolve() collapses the lexical variants; realpathSync()
+// collapses symlinks (best-effort: falls back to the resolved path if the
+// directory no longer exists). Memoized — the set of distinct cwd strings is
+// small and stable, so repeat comparisons are free after warmup.
+const normalizeCache = new Map<string, string>();
+
+export function normalizeCwd(cwd: string): string {
+  const cached = normalizeCache.get(cwd);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const resolved = resolve(cwd);
+  let normalized: string;
+  try {
+    normalized = realpathSync(resolved);
+  } catch {
+    normalized = resolved;
+  }
+  normalizeCache.set(cwd, normalized);
+  return normalized;
+}
+
+export function sameCwd(a: string, b: string): boolean {
+  return normalizeCwd(a) === normalizeCwd(b);
+}

package/dist/extensions/pi-intercom/extension-api.ts

@@ -0,0 +1,44 @@
+import type { SessionInfo } from "./types.ts";
+
+export const INTERCOM_EXTENSION_REGISTER_EVENT = "intercom:extension-register";
+export const INTERCOM_EXTENSION_REGISTRY_READY_EVENT = "intercom:extension-registry-ready";
+
+export interface IntercomExtensionOwner {
+  sessionId: string;
+  epoch: string;
+}
+
+export interface IntercomExtensionState {
+  revision: number;
+  payload: unknown;
+}
+
+export type IntercomExtensionEvent =
+  | { type: "connection"; connected: boolean; supported: boolean }
+  | { type: "owner"; owner?: IntercomExtensionOwner }
+  | { type: "message"; fromSessionId: string; owner?: IntercomExtensionOwner; payload: unknown }
+  | { type: "state"; state: IntercomExtensionState }
+  | { type: "state_result"; committed: boolean; revision: number; reason?: string }
+  | { type: "session_joined"; session: SessionInfo }
+  | { type: "session_left"; sessionId: string }
+  | { type: "presence_update"; session: SessionInfo };
+
+export interface IntercomExtensionChannel {
+  readonly namespace: string;
+  snapshot(): {
+    connected: boolean;
+    supported: boolean;
+    owner?: IntercomExtensionOwner;
+    state?: IntercomExtensionState;
+  };
+  publish(payload: unknown, options?: { audience?: "owner" | "capable"; ownerOnly?: boolean }): void;
+  commitState(payload: unknown, expectedRevision?: number): void;
+  listSessions(): Promise<SessionInfo[]>;
+}
+
+export interface IntercomExtensionRegistration {
+  namespace: string;
+  ownerEligible: boolean;
+  onEvent(event: IntercomExtensionEvent): void;
+  onReady(channel: IntercomExtensionChannel): void;
+}

package/dist/extensions/pi-intercom/format-context.test.ts

@@ -0,0 +1,31 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { formatTokenCount, formatContextUsage } from "./format-context.ts";
+import type { SessionInfo } from "./types.ts";
+
+const base: SessionInfo = { id: "s1", cwd: "/w", model: "m", pid: 1, startedAt: 0, lastActivity: 0 };
+
+test("formatTokenCount compacts thousands", () => {
+  assert.equal(formatTokenCount(0), "0");
+  assert.equal(formatTokenCount(999), "999");
+  assert.equal(formatTokenCount(1432), "1.4k");
+  assert.equal(formatTokenCount(144000), "144k");
+  assert.equal(formatTokenCount(200000), "200k");
+});
+
+test("formatContextUsage renders percent + token detail when all known", () => {
+  assert.equal(
+    formatContextUsage({ ...base, contextPct: 72, contextTokens: 144000, contextWindow: 200000 }),
+    " · 72% ctx (144k/200k)",
+  );
+});
+
+test("formatContextUsage shows percent only when token counts are absent", () => {
+  assert.equal(formatContextUsage({ ...base, contextPct: 30 }), " · 30% ctx");
+});
+
+test("formatContextUsage renders nothing when percent is unknown (never a stale %)", () => {
+  assert.equal(formatContextUsage(base), "");
+  // Tokens present but no percent (e.g. right after a compaction) still renders nothing.
+  assert.equal(formatContextUsage({ ...base, contextTokens: 100, contextWindow: 200 }), "");
+});

package/dist/extensions/pi-intercom/format-context.ts

@@ -0,0 +1,32 @@
+import type { SessionInfo } from "./types.ts";
+
+// Compact token count for display: 1432 -> "1.4k", 144000 -> "144k". Keeps list
+// rows short while staying legible.
+export function formatTokenCount(tokens: number): string {
+  if (tokens < 1000) {
+    return String(Math.max(0, Math.round(tokens)));
+  }
+  const k = tokens / 1000;
+  const value = k >= 100 ? String(Math.round(k)) : k.toFixed(1).replace(/\.0$/, "");
+  return `${value}k`;
+}
+
+// Render a session's context-window usage to sit beside its model, e.g.
+// " · 72% ctx (144k/200k)". The token detail is appended only when both counts
+// are known. Unknown percent (e.g. right after a compaction, before the next
+// assistant response) renders nothing, so a frozen value is never shown as a
+// stale percentage.
+export function formatContextUsage(session: SessionInfo): string {
+  if (typeof session.contextPct !== "number") {
+    return "";
+  }
+  let out = ` · ${session.contextPct}% ctx`;
+  if (
+    typeof session.contextTokens === "number"
+    && typeof session.contextWindow === "number"
+    && session.contextWindow > 0
+  ) {
+    out += ` (${formatTokenCount(session.contextTokens)}/${formatTokenCount(session.contextWindow)})`;
+  }
+  return out;
+}