@phenx-inc/ctlsurf 0.16.1 → 0.17.1

package/src/main/monitor.ts

@@ -0,0 +1,540 @@
+/**
+ * Resource monitor
+ *
+ * Live resource use of this machine (CPU, RAM, disk, Apple GPU), the CPU and
+ * memory of each tab's agent process tree, and the plan quota of the LLM
+ * service the agents run on (Claude Code, Codex). Ported from
+ * ctlsurf_research's monitor.py.
+ *
+ * Design notes:
+ * - Sampled on demand: about every 3 s while the desktop resource panel is
+ *   open, every 10 s otherwise, and not at all once nobody has asked for a
+ *   snapshot in IDLE_STOP_MS. Read-only: vm_stat / ioreg / ps on macOS,
+ *   /proc on Linux.
+ * - Quota is fetched only for services some open tab actually uses, and the
+ *   UI shows the active tab's. Claude's comes from `claude -p /usage` (a local
+ *   command: no model call, nothing counted against the plan); Codex's from
+ *   the rate limits Codex writes into its newest session file as it runs.
+ * - Remote (SSH) tabs are reported against this machine only: their process
+ *   tree is the local ssh client, and their quota is the local account's —
+ *   right for Claude when the remote is logged in to the same account (usage
+ *   is account-wide), but Codex only reflects Codex runs on this machine.
+ */
+
+import { execFile } from 'child_process'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { AgentConfig, isRemoteAgent } from './agents'
+import { log } from './logger'
+
+const FAST_MS = 3_000
+const SLOW_MS = 10_000
+const IDLE_STOP_MS = 120_000
+const HISTORY_MS = 600_000
+// How long one `fast` snapshot request keeps the fast cadence going.
+const FAST_HOLD_MS = 15_000
+// Plan usage: every 5 min, every minute while the panel is open.
+const USAGE_SLOW_MS = 300_000
+const USAGE_FAST_MS = 60_000
+// Codex session files grow large; its rate limits are on every token-count
+// event, so the tail is enough.
+const CODEX_TAIL_BYTES = 512 * 1024
+
+// ─── Types ────────────────────────────────────────
+
+export type Service = 'claude' | 'codex'
+
+export interface UsageWindow {
+  /** Shown in the panel: "session (5h)", "week, all models", "week, Fable". */
+  label: string
+  /** Shown on the status-bar gauge; windows without one appear only in the panel. */
+  short: string | null
+  pct: number
+  /** Human-readable reset time, or null when the service doesn't say. */
+  resets: string | null
+}
+
+export interface PlanUsage {
+  ok: boolean
+  windows: UsageWindow[]
+  plan?: string | null
+  /** Where the numbers came from. */
+  source: string
+  /** When the numbers were current (ISO). */
+  ts: string
+  error?: string
+}
+
+export interface MachineSample {
+  ok: boolean
+  error?: string
+  ts: string
+  cpu?: { pct: number | null; cores: number; load: number[] }
+  mem?: { total: number; used: number; pct: number }
+  disk?: { total: number; free: number } | null
+  /** Apple GPU utilization %, macOS only. */
+  gpu?: number | null
+}
+
+export interface HistoryPoint {
+  t: number
+  cpu: number | null
+  mem: number | null
+  gpu: number | null
+}
+
+export interface AgentProcess {
+  tabId: string
+  name: string
+  active: boolean
+  remote: boolean
+  service: Service | null
+  pid: number | null
+  /** Summed over the agent's process tree; % of one core, like `ps`. */
+  cpu: number | null
+  mem: number | null
+  procs: number
+}
+
+export interface MonitorSnapshot {
+  machine: MachineSample & { label: string; history: HistoryPoint[] }
+  agents: AgentProcess[]
+  activeService: Service | null
+  usage: Partial<Record<Service, PlanUsage>>
+  interval: number
+}
+
+export interface TabProcess {
+  tabId: string
+  agent: AgentConfig
+  pid: number | null
+  active: boolean
+}
+
+// ─── Helpers ──────────────────────────────────────
+
+function now(): string {
+  return new Date().toISOString()
+}
+
+function round(x: number, digits = 1): number {
+  const f = 10 ** digits
+  return Math.round(x * f) / f
+}
+
+function run(cmd: string, args: string[], opts: { cwd?: string; timeout?: number } = {}): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: opts.timeout ?? 5_000, cwd: opts.cwd, maxBuffer: 16 * 1024 * 1024 }, (err, stdout) => {
+      if (err && !stdout) reject(err)
+      else resolve(stdout)
+    })
+  })
+}
+
+/** Which plan an agent runs on, from the CLI it launches. Remote agents carry
+ *  it in the ssh command line (args are ['-t', target, remoteCmd]); a bare
+ *  attach to an existing tmux session doesn't say, so it gets none. */
+export function serviceFor(agent: AgentConfig): Service | null {
+  const cmd = isRemoteAgent(agent) ? agent.args.slice(2).join(' ') : path.basename(agent.command)
+  if (/\bcodex\b/.test(cmd)) return 'codex'
+  if (/\bclaude\b/.test(cmd)) return 'claude'
+  return null
+}
+
+// ─── Machine sampling ─────────────────────────────
+
+function cpuTimes(): { idle: number; total: number } {
+  let idle = 0
+  let total = 0
+  for (const c of os.cpus()) {
+    const t = c.times
+    idle += t.idle
+    total += t.user + t.nice + t.sys + t.idle + t.irq
+  }
+  return { idle, total }
+}
+
+async function memory(): Promise<{ total: number; used: number; pct: number }> {
+  const total = os.totalmem()
+  let avail = os.freemem()
+  try {
+    if (process.platform === 'darwin') {
+      // os.freemem() counts only free pages. Like psutil, also treat inactive
+      // and speculative pages as available — macOS reclaims them on demand.
+      const out = await run('vm_stat', [])
+      const page = Number(/page size of (\d+) bytes/.exec(out)?.[1]) || 4096
+      const pages = (name: string) => Number(new RegExp(`Pages ${name}:\\s+(\\d+)`).exec(out)?.[1] ?? 0)
+      avail = (pages('free') + pages('inactive') + pages('speculative')) * page
+    } else if (process.platform === 'linux') {
+      const m = /MemAvailable:\s+(\d+) kB/.exec(await fs.promises.readFile('/proc/meminfo', 'utf-8'))
+      if (m) avail = Number(m[1]) * 1024
+    }
+  } catch { /* fall back to os.freemem() */ }
+  avail = Math.min(avail, total)
+  return { total, used: total - avail, pct: round((100 * (total - avail)) / total) }
+}
+
+async function diskUsage(): Promise<{ total: number; free: number } | null> {
+  // fs.statfs arrived in Node 18.15; terminal mode supports any Node 18.
+  if (typeof fs.promises.statfs !== 'function') return null
+  try {
+    const s = await fs.promises.statfs(os.homedir())
+    return { total: s.blocks * s.bsize, free: s.bavail * s.bsize }
+  } catch {
+    return null
+  }
+}
+
+/** Apple GPU load from the IOAccelerator registry entry (no sudo needed). */
+async function appleGpu(): Promise<number | null> {
+  if (process.platform !== 'darwin') return null
+  try {
+    const out = await run('ioreg', ['-r', '-d', '1', '-w', '0', '-c', 'IOAccelerator'], { timeout: 3_000 })
+    const m = /"Device Utilization %"=(\d+)/.exec(out)
+    return m ? Number(m[1]) : null
+  } catch {
+    return null
+  }
+}
+
+interface PsRow { ppid: number; cpu: number; rss: number }
+
+/** One `ps` for every process: pid → {ppid, %cpu, rss bytes}. */
+async function processTable(): Promise<Map<number, PsRow>> {
+  const table = new Map<number, PsRow>()
+  if (process.platform === 'win32') return table
+  try {
+    const out = await run('ps', ['-A', '-o', 'pid=,ppid=,pcpu=,rss='])
+    for (const line of out.split('\n')) {
+      const [pid, ppid, cpu, rss] = line.trim().split(/\s+/).map(Number)
+      if (pid) table.set(pid, { ppid, cpu: cpu || 0, rss: (rss || 0) * 1024 })
+    }
+  } catch { /* no per-agent numbers this round */ }
+  return table
+}
+
+function agentProcess(tab: TabProcess, table: Map<number, PsRow>): AgentProcess {
+  const base = {
+    tabId: tab.tabId,
+    name: tab.agent.name,
+    active: tab.active,
+    remote: isRemoteAgent(tab.agent),
+    service: serviceFor(tab.agent),
+    pid: tab.pid,
+  }
+  if (tab.pid == null || !table.has(tab.pid)) return { ...base, cpu: null, mem: null, procs: 0 }
+  const children = new Map<number, number[]>()
+  for (const [pid, row] of table) {
+    const list = children.get(row.ppid)
+    if (list) list.push(pid)
+    else children.set(row.ppid, [pid])
+  }
+  let cpu = 0
+  let mem = 0
+  let procs = 0
+  const queue = [tab.pid]
+  while (queue.length) {
+    const pid = queue.pop()!
+    const row = table.get(pid)
+    if (!row) continue
+    cpu += row.cpu
+    mem += row.rss
+    procs++
+    queue.push(...(children.get(pid) ?? []))
+  }
+  return { ...base, cpu: round(cpu), mem, procs }
+}
+
+// ─── Plan usage ───────────────────────────────────
+
+/** `claude -p /usage` text → windows (reset times as Claude Code words them). */
+export function parseClaudeUsage(text: string): UsageWindow[] {
+  const windows: UsageWindow[] = []
+  for (const line of text.split('\n')) {
+    let m = /^\s*Current session:\s*([\d.]+)% used(?:\s*·\s*resets (.+))?/.exec(line)
+    if (m) {
+      windows.push({ label: 'session (5h)', short: '5h', pct: Number(m[1]), resets: m[2]?.trim() || null })
+      continue
+    }
+    m = /^\s*Current week \((.+?)\):\s*([\d.]+)% used(?:\s*·\s*resets (.+))?/.exec(line)
+    if (m) {
+      const all = m[1].trim().toLowerCase() === 'all models'
+      windows.push({
+        label: all ? 'week, all models' : `week, ${m[1].trim()}`,
+        short: all ? 'wk' : null,
+        pct: Number(m[2]),
+        resets: m[3]?.trim() || null,
+      })
+    }
+  }
+  return windows
+}
+
+export async function claudeUsage(): Promise<PlanUsage> {
+  const source = 'claude /usage'
+  let text = ''
+  try {
+    const out = await run('claude', ['-p', '/usage', '--output-format', 'json', '--no-session-persistence'],
+      { cwd: os.tmpdir(), timeout: 40_000 })
+    text = String(JSON.parse(out || '{}').result ?? '')
+  } catch (err) {
+    const msg = (err as NodeJS.ErrnoException).code === 'ENOENT' ? 'claude not found on PATH' : String(err)
+    return { ok: false, windows: [], source, ts: now(), error: msg.slice(0, 200) }
+  }
+  const windows = parseClaudeUsage(text)
+  return windows.length
+    ? { ok: true, windows, source, ts: now() }
+    : { ok: false, windows: [], source, ts: now(), error: text.trim().slice(0, 200) || 'no usage reported' }
+}
+
+function findKey(obj: unknown, key: string): Record<string, unknown> | null {
+  if (Array.isArray(obj)) {
+    for (const v of obj) {
+      const found = findKey(v, key)
+      if (found) return found
+    }
+  } else if (obj && typeof obj === 'object') {
+    const rec = obj as Record<string, unknown>
+    if (rec[key] && typeof rec[key] === 'object') return rec[key] as Record<string, unknown>
+    for (const v of Object.values(rec)) {
+      const found = findKey(v, key)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+function codexWindow(minutes: unknown): { label: string; short: string } {
+  const m = Number(minutes)
+  if (!Number.isFinite(m)) return { label: 'window', short: 'win' }
+  if (m === 300) return { label: '5h', short: '5h' }
+  if (m === 1440) return { label: 'day', short: 'day' }
+  if (m === 10080) return { label: 'week', short: 'wk' }
+  const s = m < 1440 ? `${Math.floor(m / 60)}h` : `${Math.floor(m / 1440)}d`
+  return { label: s, short: s }
+}
+
+async function readTail(file: string, bytes: number): Promise<string> {
+  const fh = await fs.promises.open(file, 'r')
+  try {
+    const { size } = await fh.stat()
+    const start = Math.max(0, size - bytes)
+    const buf = Buffer.alloc(size - start)
+    await fh.read(buf, 0, buf.length, start)
+    return buf.toString('utf-8')
+  } finally {
+    await fh.close()
+  }
+}
+
+/** Newest Codex session files (~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl),
+ *  by mtime. Walks the newest day directories only. */
+async function codexSessionFiles(root: string, limit: number): Promise<string[]> {
+  const sortedDirs = async (dir: string) =>
+    (await fs.promises.readdir(dir, { withFileTypes: true }).catch(() => []))
+      .filter(d => d.isDirectory()).map(d => path.join(dir, d.name)).sort().reverse()
+  const days: string[] = []
+  for (const y of await sortedDirs(root)) {
+    for (const m of await sortedDirs(y)) {
+      days.push(...await sortedDirs(m))
+      if (days.length >= 14) break
+    }
+    if (days.length >= 14) break
+  }
+  const files: { file: string; mtime: number }[] = []
+  for (const day of days.slice(0, 14)) {
+    for (const name of await fs.promises.readdir(day).catch(() => [] as string[])) {
+      if (!name.startsWith('rollout-') || !name.endsWith('.jsonl')) continue
+      const file = path.join(day, name)
+      try {
+        files.push({ file, mtime: (await fs.promises.stat(file)).mtimeMs })
+      } catch { /* vanished */ }
+    }
+  }
+  return files.sort((a, b) => b.mtime - a.mtime).slice(0, limit).map(f => f.file)
+}
+
+export async function codexUsage(home: string = os.homedir()): Promise<PlanUsage> {
+  const source = 'your most recent Codex session'
+  for (const file of await codexSessionFiles(path.join(home, '.codex', 'sessions'), 5)) {
+    let lines: string[]
+    try {
+      lines = (await readTail(file, CODEX_TAIL_BYTES)).split('\n')
+    } catch {
+      continue
+    }
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (!lines[i].includes('"rate_limits"')) continue
+      let rl: Record<string, unknown> | null
+      try {
+        rl = findKey(JSON.parse(lines[i]), 'rate_limits')
+      } catch {
+        continue // the tail's first line is usually cut mid-record
+      }
+      if (!rl) continue
+      const windows: UsageWindow[] = []
+      for (const key of ['primary', 'secondary']) {
+        const w = rl[key] as Record<string, unknown> | null | undefined
+        if (!w || typeof w !== 'object' || w.used_percent == null) continue
+        const { label, short } = codexWindow(w.window_minutes)
+        const resets = typeof w.resets_at === 'number'
+          ? new Date(w.resets_at * 1000).toLocaleString(undefined, { month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' })
+          : null
+        windows.push({ label, short, pct: Number(w.used_percent), resets })
+      }
+      if (windows.length) {
+        const ts = new Date((await fs.promises.stat(file)).mtimeMs).toISOString()
+        return { ok: true, windows, plan: (rl.plan_type as string | null) ?? null, source, ts }
+      }
+    }
+  }
+  return { ok: false, windows: [], source, ts: now(), error: 'no Codex session with usage yet' }
+}
+
+const FETCH_USAGE: Record<Service, () => Promise<PlanUsage>> = {
+  claude: claudeUsage,
+  codex: () => codexUsage(),
+}
+
+const SERVICE_NAME: Record<Service, string> = { claude: 'Claude', codex: 'Codex' }
+
+// ─── Monitor ──────────────────────────────────────
+
+export class ResourceMonitor {
+  private machine: MachineSample = { ok: false, ts: now(), error: 'sampling…' }
+  private history: HistoryPoint[] = []
+  private agents: AgentProcess[] = []
+  private usage: Partial<Record<Service, PlanUsage>> = {}
+  private usageAt: Partial<Record<Service, number>> = {}
+  private usageBusy = new Set<Service>()
+  private prevCpu = cpuTimes()
+  private lastAsk = 0
+  private fastUntil = 0
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private inflight: Promise<void> | null = null
+
+  constructor(private tabs: () => TabProcess[]) {}
+
+  /** Latest sample plus 10 minutes of history. `fast` = the panel is open:
+   *  sample every ~3 s and refresh quota every minute. */
+  async snapshot(fast = false): Promise<MonitorSnapshot> {
+    const t = Date.now()
+    this.lastAsk = t
+    const speedUp = fast && t >= this.fastUntil
+    if (fast) this.fastUntil = t + FAST_HOLD_MS
+    // The first answer — and the first fast one — waits for a fresh sample.
+    if ((!this.timer && !this.inflight) || speedUp) await this.tick()
+    // A tab switch can bring in a service we haven't fetched yet.
+    else this.refreshUsage(this.tabs())
+    return this.build(fast)
+  }
+
+  stop(): void {
+    if (this.timer) clearTimeout(this.timer)
+    this.timer = null
+    this.lastAsk = 0
+  }
+
+  private tick(): Promise<void> {
+    if (!this.inflight) {
+      if (this.timer) clearTimeout(this.timer)
+      this.timer = null
+      this.inflight = this.sample()
+        .catch(err => log(`[monitor] sample failed: ${err}`))
+        .finally(() => {
+          this.inflight = null
+          if (Date.now() - this.lastAsk >= IDLE_STOP_MS) return // nobody's looking
+          this.timer = setTimeout(() => { void this.tick() }, Date.now() < this.fastUntil ? FAST_MS : SLOW_MS)
+          this.timer.unref?.()
+        })
+    }
+    return this.inflight
+  }
+
+  private async sample(): Promise<void> {
+    const tabs = this.tabs()
+    this.refreshUsage(tabs)
+    try {
+      const [mem, disk, gpu, table] = await Promise.all([memory(), diskUsage(), appleGpu(), processTable()])
+      const cur = cpuTimes()
+      const dTotal = cur.total - this.prevCpu.total
+      const cpuPct = dTotal > 0 ? round(100 * (1 - (cur.idle - this.prevCpu.idle) / dTotal)) : null
+      this.prevCpu = cur
+      this.machine = {
+        ok: true,
+        ts: now(),
+        cpu: { pct: cpuPct, cores: os.cpus().length, load: os.loadavg().map(x => round(x, 2)) },
+        mem,
+        disk,
+        gpu,
+      }
+      this.agents = tabs.map(tab => agentProcess(tab, table))
+      const t = Date.now()
+      this.history.push({ t, cpu: cpuPct, mem: mem.pct, gpu })
+      while (this.history.length && this.history[0].t < t - HISTORY_MS) this.history.shift()
+    } catch (err) {
+      this.machine = { ok: false, ts: now(), error: String(err).slice(0, 200) }
+    }
+  }
+
+  private refreshUsage(tabs: TabProcess[]): void {
+    const every = Date.now() < this.fastUntil ? USAGE_FAST_MS : USAGE_SLOW_MS
+    for (const s of this.servicesInUse(tabs)) {
+      if (this.usageBusy.has(s) || Date.now() - (this.usageAt[s] ?? 0) < every) continue
+      this.usageBusy.add(s)
+      FETCH_USAGE[s]()
+        .catch((err): PlanUsage => ({ ok: false, windows: [], source: s, ts: now(), error: String(err).slice(0, 200) }))
+        .then(u => {
+          this.usage[s] = u
+          this.usageAt[s] = Date.now()
+          if (!u.ok) log(`[monitor] ${s} usage unavailable: ${u.error}`)
+        })
+        .finally(() => this.usageBusy.delete(s))
+    }
+  }
+
+  private servicesInUse(tabs: TabProcess[]): Service[] {
+    return [...new Set(tabs.map(t => serviceFor(t.agent)).filter((s): s is Service => s !== null))]
+  }
+
+  private build(fast: boolean): MonitorSnapshot {
+    const tabs = this.tabs()
+    const active = tabs.find(t => t.active)
+    const usage: Partial<Record<Service, PlanUsage>> = {}
+    for (const s of this.servicesInUse(tabs)) {
+      if (this.usage[s]) usage[s] = this.usage[s]
+    }
+    return {
+      machine: {
+        ...this.machine,
+        label: process.platform === 'darwin' ? 'This Mac' : os.hostname(),
+        history: [...this.history],
+      },
+      agents: this.agents,
+      activeService: active ? serviceFor(active.agent) : null,
+      usage,
+      interval: fast ? FAST_MS : SLOW_MS,
+    }
+  }
+}
+
+/** One-line summary for the terminal-mode tab title:
+ *  "CPU 12% RAM 64% · Claude 5h 4% wk 4%". */
+export function summarizeSnapshot(s: MonitorSnapshot): string {
+  const parts: string[] = []
+  const m = s.machine
+  if (m.ok) {
+    const res = [
+      m.cpu?.pct != null ? `CPU ${Math.round(m.cpu.pct)}%` : '',
+      m.mem ? `RAM ${Math.round(m.mem.pct)}%` : '',
+    ].filter(Boolean).join(' ')
+    if (res) parts.push(res)
+  }
+  const u = s.activeService ? s.usage[s.activeService] : undefined
+  if (s.activeService && u?.ok) {
+    const wins = u.windows.filter(w => w.short).map(w => `${w.short} ${Math.round(w.pct)}%`)
+    if (wins.length) parts.push(`${SERVICE_NAME[s.activeService]} ${wins.join(' ')}`)
+  }
+  return parts.join(' · ')
+}

package/src/main/orchestrator.ts

@@ -742,6 +742,16 @@ export class Orchestrator {
     return [...this.tabs.keys()]
   }
 
+  // Every open tab's agent and PTY pid, for the resource monitor (monitor.ts).
+  getTabProcesses(): { tabId: string; agent: AgentConfig; pid: number | null; active: boolean }[] {
+    return [...this.tabs].map(([tabId, tab]) => ({
+      tabId,
+      agent: tab.agent,
+      pid: tab.ptyManager.pid,
+      active: tabId === this.activeTabId,
+    }))
+  }
+
   // ─── Tracking control (active tab) ──────────────
 
   isActiveTabTracking(): boolean {

package/src/main/pty.ts

@@ -39,6 +39,11 @@ export class PtyManager {
     })
   }
 
+  /** OS pid of the spawned agent (or ssh), null once it has exited. */
+  get pid(): number | null {
+    return this.process?.pid ?? null
+  }
+
   write(data: string): void {
     this.process?.write(data)
   }

package/src/main/tui.ts

@@ -23,12 +23,19 @@ const BG_MODAL = `${CSI}48;2;31;35;53m`    // #1f2335
 const BG_SELECTED = `${CSI}48;2;42;43;61m` // #2a2b3d
 const RESET = `${CSI}0m`
 
+// Title writes share stdout with the agent's output; wait this long after the
+// last PTY chunk so a title never lands inside one of the agent's escape
+// sequences (node-pty can split them across chunks).
+const TITLE_QUIET_MS = 50
+
 export interface TuiState {
   agentName: string
   cwd: string
   wsStatus: string
   workerId: string | null
   mode: string
+  // Resource + plan-quota summary from monitor.ts, appended to the title.
+  resources: string
 }
 
 export class Tui {
@@ -40,7 +47,12 @@ export class Tui {
     wsStatus: 'disconnected',
     workerId: null,
     mode: 'terminal',
+    resources: '',
   }
+  private lastPtyWrite = 0
+  private pendingTitle: string | null = null
+  private lastTitle = ''
+  private titleTimer: ReturnType<typeof setTimeout> | null = null
 
   constructor() {
     this.rows = process.stdout.rows || 24
@@ -60,6 +72,8 @@ export class Tui {
    * Restore terminal to normal state
    */
   destroy(): void {
+    if (this.titleTimer) clearTimeout(this.titleTimer)
+    this.titleTimer = null
     // Show cursor
     this.write(`${CSI}?25h`)
   }
@@ -94,6 +108,7 @@ export class Tui {
    * Write PTY output — full passthrough.
    */
   writePtyData(data: string): void {
+    this.lastPtyWrite = Date.now()
     this.write(data)
   }
 
@@ -101,14 +116,30 @@ export class Tui {
    * Update the terminal window/tab title via OSC escape sequence.
    */
   setTerminalTitle(title: string): void {
-    this.write(`${ESC}]0;${title}\x07`)
+    this.pendingTitle = title
+    this.flushTitle()
+  }
+
+  private flushTitle(): void {
+    if (this.pendingTitle === null || this.titleTimer) return
+    const wait = TITLE_QUIET_MS - (Date.now() - this.lastPtyWrite)
+    if (wait > 0) {
+      this.titleTimer = setTimeout(() => {
+        this.titleTimer = null
+        this.flushTitle()
+      }, wait)
+      return
+    }
+    if (this.pendingTitle !== this.lastTitle) this.write(`${ESC}]0;${this.pendingTitle}\x07`)
+    this.lastTitle = this.pendingTitle
+    this.pendingTitle = null
   }
 
   /**
    * Build a title string from current state for the terminal tab.
    */
   updateTerminalTitle(): void {
-    const { agentName, wsStatus, cwd } = this.state
+    const { agentName, wsStatus, cwd, resources } = this.state
     const displayCwd = this.shortenPath(cwd)
     const statusIcon = {
       connected: '\u25CF',
@@ -125,7 +156,10 @@ export class Tui {
       no_project: 'No Project',
     }[wsStatus] || wsStatus
 
-    this.setTerminalTitle(`ctlsurf \u00B7 ${agentName} \u00B7 ${statusIcon} ${statusLabel} \u00B7 ${displayCwd}`)
+    this.setTerminalTitle(
+      `ctlsurf \u00B7 ${agentName} \u00B7 ${statusIcon} ${statusLabel} \u00B7 ${displayCwd}` +
+      (resources ? ` \u00B7 ${resources}` : '')
+    )
   }
 
   /**

package/src/preload/index.ts

@@ -108,6 +108,10 @@ const api = {
     ipcRenderer.on('app:updateInfo', listener)
     return () => ipcRenderer.removeListener('app:updateInfo', listener)
   },
+  // Resources + plan quota for the status bar (shape: MonitorSnapshot in
+  // src/main/monitor.ts). `fast` = the details panel is open.
+  getResourceSnapshot: (fast: boolean): Promise<unknown> =>
+    ipcRenderer.invoke('monitor:snapshot', fast),
 
   // Settings (legacy)
   getSetting: (key: string): Promise<string | null> =>