codemax-cli 0.0.0-stage → 0.1.3

package/src/chat/transcript.ts

@@ -0,0 +1,342 @@
+import { BoxRenderable, ScrollBoxRenderable, StyledText, TextRenderable, fg, italic, strikethrough, stringToStyledText, type CliRenderer, type TextChunk } from "@opentui/core";
+import { C, G } from "./theme.ts";
+import { styleMarkdown, styleToolOutput } from "./markdown.ts";
+
+export interface PlanEntry {
+  content: string;
+  status: string;
+}
+
+export interface AgentBlock {
+  /** Stream assistant text. A new `messageId` (or a tool row in between) starts a new `⏺` paragraph. */
+  append(text: string, messageId?: string): void;
+  /** Stream reasoning into a collapsed, dim "Thinking" block. */
+  thought(text: string, messageId?: string): void;
+  /** Show or update the agent's plan as a checklist. */
+  plan(entries: PlanEntry[]): void;
+  tool(id: string, title: string, status: string, detail?: string): void;
+  toolUpdate(id: string, status?: string, title?: string, detail?: string): void;
+  /** Closing dim line, e.g. "✻ Worked for 13s · done 7:25 PM". */
+  footer(text: string): void;
+  /** The reply as plain text: paragraphs joined by blank lines. */
+  text(): string;
+  toolCount(): number;
+}
+
+/** Something that can be shown cut down or in full (Ctrl+O toggles all of them). */
+interface Collapsible {
+  node: TextRenderable;
+  full: string;
+  render: (text: string, expanded: boolean) => string | StyledText;
+}
+
+/**
+ * Conversation view in Claude Code's idiom: `❯ prompt`, `⏺ text`, `⏺ Tool(args)`
+ * with `  ⎿  result` nested beneath, dim notes, and a divider on agent switches.
+ * Every line is a row box: a fixed glyph column and a wrapping text column, so
+ * wrapped continuation lines stay aligned under the text.
+ */
+export class Transcript {
+  readonly box: ScrollBoxRenderable;
+  private n = 0;
+  private expanded = false;
+  private collapsibles: Collapsible[] = [];
+
+  constructor(private renderer: CliRenderer) {
+    this.box = new ScrollBoxRenderable(renderer, {
+      id: "transcript",
+      width: "100%",
+      flexGrow: 1,
+      flexShrink: 1,
+      stickyScroll: true,
+      stickyStart: "bottom",
+      scrollY: true,
+      scrollX: false,
+      contentOptions: { flexDirection: "column", paddingX: 1 },
+      verticalScrollbarOptions: { width: 0, showArrows: false },
+    });
+  }
+
+  get isExpanded() {
+    return this.expanded;
+  }
+
+  /** Ctrl+O: show every tool result and thinking block in full, or cut them back down. */
+  toggleExpanded(): boolean {
+    this.expanded = !this.expanded;
+    for (const c of this.collapsibles) c.node.content = c.render(c.full, this.expanded);
+    this.scrollToEnd();
+    return this.expanded;
+  }
+
+  /** Startup card: brand mark, what codemax is, the project, and any notes. */
+  header(lines: { title: string; subtitle: string; path: string; notes: string[]; logo?: string[] }) {
+    if (this.gone) return;
+    const card = new BoxRenderable(this.renderer, {
+      id: `header-${++this.n}`,
+      width: "100%",
+      flexDirection: "column",
+      border: true,
+      borderStyle: "rounded",
+      borderColor: C.accent,
+      paddingX: 1,
+      marginTop: 1,
+    });
+    if (lines.logo?.length) {
+      // The wordmark: one line per two rows of the website's halftone grid, never wrapped.
+      for (const [i, l] of lines.logo.entries()) card.add(new TextRenderable(this.renderer, { id: `h-l-${this.n}-${i}`, content: l, fg: C.accent, wrapMode: "none" } as any));
+      card.add(new TextRenderable(this.renderer, { id: `h-s-${this.n}`, content: `${lines.title} · ${lines.subtitle}`, fg: C.dim }));
+    } else {
+      const title = new StyledText([fg(C.accent)("✻ "), fg(C.accent)(lines.title)]);
+      card.add(new TextRenderable(this.renderer, { id: `h-t-${this.n}`, content: title, attributes: 1 } as any));
+      card.add(new TextRenderable(this.renderer, { id: `h-s-${this.n}`, content: lines.subtitle, fg: C.dim }));
+    }
+    card.add(new TextRenderable(this.renderer, { id: `h-gap-${this.n}`, content: "", height: 1 }));
+    card.add(new TextRenderable(this.renderer, { id: `h-p-${this.n}`, content: `cwd: ${lines.path}`, fg: C.dim, wrapMode: "char" } as any));
+    for (const [i, note] of lines.notes.entries()) card.add(new TextRenderable(this.renderer, { id: `h-n-${this.n}-${i}`, content: note, fg: C.dim, wrapMode: "word" } as any));
+    this.box.add(card);
+  }
+
+  /** A side agent's note: a bordered card that stands apart from the conversation. */
+  noteCard(title: string, body: string, hint: string) {
+    if (this.gone) return;
+    this.gap();
+    const card = new BoxRenderable(this.renderer, { id: `note-${++this.n}`, width: "100%", flexDirection: "column", border: true, borderStyle: "rounded", borderColor: C.warn, paddingX: 1 });
+    card.add(new TextRenderable(this.renderer, { id: `nt-${this.n}`, content: title, fg: C.warn, attributes: 1 } as any));
+    card.add(new TextRenderable(this.renderer, { id: `nb-${this.n}`, content: styleMarkdown(body), wrapMode: "word", width: "100%" } as any));
+    card.add(new TextRenderable(this.renderer, { id: `nh-${this.n}`, content: hint, fg: C.dim, wrapMode: "word" } as any));
+    this.box.add(card);
+    this.scrollToEnd();
+  }
+
+  user(text: string) {
+    this.gap();
+    this.line(`${G.prompt} `, text, { fg: undefined, glyphFg: C.accent });
+  }
+
+  note(text: string, fg_: string = C.dim) {
+    this.nested(text, fg_);
+  }
+
+  error(text: string) {
+    this.nested(text, C.error);
+  }
+
+  divider(text: string) {
+    this.gap();
+    const w = Math.max(20, this.renderer.width - 4);
+    const label = ` ${text} `;
+    const side = Math.max(3, Math.floor((w - label.length) / 2));
+    const content = new StyledText([fg(C.dimmer)(G.rule.repeat(side)), fg(C.accent)(label), fg(C.dimmer)(G.rule.repeat(side))]);
+    this.line("", "", {}).content = content;
+    this.gap();
+  }
+
+  agent(): AgentBlock {
+    const self = this;
+    let para: { node: TextRenderable; text: string; id?: string } | null = null;
+    let thinking: { node: TextRenderable; c: Collapsible; id?: string } | null = null;
+    let planNode: TextRenderable | null = null;
+    let styleTimer: ReturnType<typeof setTimeout> | null = null;
+    const tools = new Map<string, { glyph: TextRenderable; title: TextRenderable; result?: Collapsible; name: string; status: string }>();
+    const paragraphs: string[] = [];
+
+    const settle = () => {
+      if (para) {
+        if (styleTimer) clearTimeout(styleTimer);
+        styleTimer = null;
+        para.node.content = styleMarkdown(para.text);
+      }
+    };
+    const toolResult = (detail: string, failed: boolean): Collapsible => {
+      const c: Collapsible = {
+        node: null as unknown as TextRenderable,
+        full: detail,
+        render: (t, expanded) => styleToolOutput(expanded ? t.replace(/\s+$/, "") : summarize(t)),
+      };
+      c.node = self.nestedNode("", failed ? C.error : C.dim);
+      c.node.content = c.render(detail, self.expanded);
+      self.collapsibles.push(c);
+      return c;
+    };
+
+    return {
+      append(t, messageId) {
+        if (para && messageId && para.id && messageId !== para.id) {
+          settle();
+          para = null;
+        }
+        thinking = null;
+        if (!para) {
+          const start = t.replace(/^\n+/, "");
+          const node = self.line(`${G.bullet} `, start, { glyphFg: C.assistant });
+          para = { node, text: start, id: messageId };
+          paragraphs.push(start);
+        } else {
+          para.text += t;
+          paragraphs[paragraphs.length - 1] = para.text;
+        }
+        const p = para;
+        // Restyle at most every 80ms while streaming; the final append is always styled.
+        if (!styleTimer) styleTimer = setTimeout(() => { styleTimer = null; p.node.content = styleMarkdown(p.text); }, 80);
+        self.scrollToEnd();
+      },
+      thought(t, messageId) {
+        if (thinking && messageId && thinking.id && messageId !== thinking.id) thinking = null;
+        if (!thinking) {
+          settle();
+          para = null;
+          const c: Collapsible = {
+            node: null as unknown as TextRenderable,
+            full: "",
+            render: (text, expanded) => {
+              const body = text.trim();
+              const shown = expanded ? body : clip(body, 2, 160);
+              return new StyledText([fg(C.thought)(italic(`Thinking${shown ? "… " : "…"}`)), fg(C.thought)(italic(shown))]);
+            },
+          };
+          c.node = self.line(`${G.thought} `, "", { glyphFg: C.thought });
+          self.collapsibles.push(c);
+          thinking = { node: c.node, c, id: messageId };
+        }
+        thinking.c.full += t;
+        thinking.node.content = thinking.c.render(thinking.c.full, self.expanded);
+        self.scrollToEnd();
+      },
+      plan(entries) {
+        if (!entries.length) return;
+        settle();
+        para = null;
+        const chunks: TextChunk[] = [fg(C.assistant)("Plan")];
+        for (const e of entries) {
+          const done = e.status === "completed";
+          const doing = e.status === "in_progress";
+          const box = done ? G.done_ : doing ? G.doing : G.todo;
+          // A line break inside a coloured chunk is not laid out; it must be its own plain chunk.
+          chunks.push(...stringToStyledText("\n").chunks, fg(C.dimmer)(`${G.nest}  `));
+          if (done) chunks.push(fg(C.dim)(`${box} `), fg(C.dim)(strikethrough(e.content)));
+          else if (doing) chunks.push(fg(C.accent)(`${box} ${e.content}`));
+          else chunks.push(fg(C.text ?? C.dim)(`${box} ${e.content}`));
+        }
+        const content = new StyledText(chunks);
+        // One live checklist per turn: later updates redraw it in place.
+        if (planNode) planNode.content = content;
+        else {
+          planNode = self.line(`${G.bullet} `, "", { glyphFg: C.tool });
+          planNode.content = content;
+        }
+        self.scrollToEnd();
+      },
+      tool(id, title, status, detail) {
+        settle();
+        para = null;
+        thinking = null;
+        if (self.gone) return;
+        const glyph = new TextRenderable(self.renderer, { id: `tg-${++self.n}`, content: `${G.bullet} `, width: 2, fg: toolColor(status), wrapMode: "none" });
+        const title_ = self.lineWithGlyph(glyph, title);
+        const entry = { glyph, title: title_, name: title, status, result: undefined as Collapsible | undefined };
+        tools.set(id, entry);
+        if (detail) entry.result = toolResult(detail, status === "failed");
+        self.scrollToEnd();
+      },
+      toolUpdate(id, status, title, detail) {
+        const e = tools.get(id);
+        if (!e) return;
+        if (title) {
+          e.name = title;
+          e.title.content = title;
+        }
+        if (status) {
+          e.status = status;
+          e.glyph.fg = toolColor(status);
+        }
+        if (status === "failed") e.title.fg = C.error;
+        if (detail) {
+          if (e.result) {
+            e.result.full = detail;
+            e.result.node.content = e.result.render(detail, self.expanded);
+          } else e.result = toolResult(detail, status === "failed");
+        }
+      },
+      footer(text) {
+        settle();
+        para = null;
+        thinking = null;
+        self.line(`${G.done} `, text, { fg: C.dim, glyphFg: C.dim });
+        self.scrollToEnd();
+      },
+      text: () => paragraphs.map((p) => p.trim()).filter(Boolean).join("\n\n"),
+      toolCount: () => tools.size,
+    };
+  }
+
+  // ---------- primitives ----------
+
+  /** After quit the native scene is gone; late async writes (a finishing handoff) are dropped. */
+  private get gone() {
+    return (this.renderer as { isDestroyed?: boolean }).isDestroyed === true;
+  }
+
+  private gap() {
+    if (this.gone) return;
+    this.box.add(new TextRenderable(this.renderer, { id: `gap-${++this.n}`, content: "", height: 1 }));
+  }
+
+  private line(glyph: string, text: string, o: { fg?: string; glyphFg?: string; bold?: boolean } = {}): TextRenderable {
+    if (this.gone) return { content: "" } as unknown as TextRenderable;
+    const g = glyph ? new TextRenderable(this.renderer, { id: `g-${++this.n}`, content: glyph, width: glyph.length, fg: o.glyphFg ?? o.fg, wrapMode: "none" }) : null;
+    return this.lineWithGlyph(g, text, o);
+  }
+
+  private lineWithGlyph(glyph: TextRenderable | null, text: string, o: { fg?: string; bold?: boolean } = {}): TextRenderable {
+    if (this.gone) return { content: "" } as unknown as TextRenderable;
+    const row = new BoxRenderable(this.renderer, { id: `row-${++this.n}`, width: "100%", flexDirection: "row" });
+    if (glyph) row.add(glyph);
+    const body = new TextRenderable(this.renderer, { id: `t-${this.n}`, content: text, fg: o.fg, flexGrow: 1, flexShrink: 1, wrapMode: "word", attributes: o.bold ? 1 : undefined } as any);
+    row.add(body);
+    this.box.add(row);
+    return body;
+  }
+
+  private nested(text: string, fg_: string) {
+    this.nestedNode(text, fg_);
+    this.scrollToEnd();
+  }
+
+  private nestedNode(text: string, fg_: string, toolOutput = false): TextRenderable {
+    const node = this.line(`  ${G.nest}  `, text, { fg: fg_, glyphFg: C.dimmer });
+    if (toolOutput) node.content = styleToolOutput(text);
+    return node;
+  }
+
+  scrollToEnd() {
+    queueMicrotask(() => {
+      try {
+        this.box.scrollTo({ x: 0, y: this.box.scrollHeight });
+      } catch {
+        /* not laid out yet */
+      }
+    });
+  }
+}
+
+function toolColor(status: string): string {
+  if (status === "completed") return C.ok;
+  if (status === "failed") return C.error;
+  return C.dim;
+}
+
+/** First `lines` lines of text, each clipped, with an ellipsis when anything was cut. */
+function clip(text: string, lines: number, width: number): string {
+  const all = text.split("\n").filter((l) => l.trim());
+  const kept = all.slice(0, lines).map((l) => (l.length > width ? l.slice(0, width - 1) + "…" : l));
+  const cut = all.length > lines || kept.some((l, i) => l !== all[i]);
+  return kept.join(" ") + (cut ? " (ctrl+o)" : "");
+}
+
+/** Tool output: first lines, then "… +N lines" like Claude Code's collapsed results. */
+export function summarize(detail: string, keep = 3): string {
+  const lines = detail.replace(/\s+$/, "").split("\n");
+  if (lines.length <= keep) return lines.join("\n");
+  return lines.slice(0, keep).join("\n") + `\n… +${lines.length - keep} lines (ctrl+o to expand)`;
+}

package/src/cli.ts

@@ -0,0 +1,254 @@
+import { loadConfig, CONFIG_PATH, hotkeyLabel, saveConfigKey } from "./config.ts";
+import { defaultAwakeDeps, recoverAwake } from "./core/awake.ts";
+import { checkForUpdate, installKind, updatePlan } from "./core/update.ts";
+import { platformArgv } from "./core/spawn.ts";
+import pkg from "../package.json" with { type: "json" };
+import { canonicalCwd } from "./core/paths.ts";
+import { Ledger } from "./core/ledger.ts";
+import { Orchestrator } from "./core/orchestrator.ts";
+import { runApp } from "./tui/app.ts";
+import { runChat } from "./chat/app.ts";
+import { hasEngine } from "./engines/index.ts";
+import { listAdapters, getAdapter } from "./adapters/index.ts";
+import { buildBrief } from "./core/brief.ts";
+import { quotaLabel } from "./core/quota.ts";
+import type { AgentId } from "./adapters/types.ts";
+import { describeBytes, findHotkey, parseHotkeys } from "./core/hotkey.ts";
+import { diagnose } from "./core/doctor.ts";
+import { renderUsageTable, sumCost } from "./core/usage.ts";
+import { fmtUsd, priceFor, priceProvenance, resetPriceCache } from "./core/pricing.ts";
+import { fetchLivePrices, loadLivePrices, LIVE_PRICES_PATH } from "./core/prices-live.ts";
+
+const HELP = `codemax — one terminal for all your coding agents
+
+usage:
+  codemax [start] [--agent <id>] [--fresh]   codemax chat UI driving the agent over its protocol (default)
+                 [--tui]                     show the agent's own TUI inside the codemax screen instead
+                 [--raw]                     legacy passthrough mode without the codemax screen
+  codemax agents                             show detected agents, saved sessions, quota
+  codemax status                             project ledger summary
+  codemax history [-n <count>]               print recorded turns for this project
+  codemax brief [--to <id>]                  print the handoff brief that would be injected
+  codemax config                             print config path and values
+  codemax keys                               show the raw bytes your terminal sends per keypress (hotkey debugging)
+  codemax update [--check]                    update codemax the way it was installed (--check only reports)
+  codemax awake [on|lid|off|status]          keep the machine awake while codemax runs (lid: also with the lid closed)
+  codemax quota [clear [<id>]]               show or clear remembered quota state for this project
+  codemax doctor [--fix]                     check agent auth/permission setup (API keys that would be billed, silent modes)
+  codemax usage [--all]                      tokens and API-equivalent cost per agent for this project (or every project)
+  codemax prices [update] [<model>]          show price source and age, refresh the public list, or look up one model
+
+inside an agent, press the hotkey (default Ctrl+/ or Ctrl+^) to open the codemax menu.
+set "hotkeys": ["ctrl+<key>", ...] in the config to change it.
+`;
+
+function flag(args: string[], name: string): string | undefined {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+async function main(argv: string[]) {
+  const config = loadConfig();
+  const cwd = canonicalCwd();
+  const [cmdRaw, ...rest] = argv;
+  const cmd = cmdRaw && !cmdRaw.startsWith("-") ? cmdRaw : "start";
+  const args = cmdRaw && !cmdRaw.startsWith("-") ? rest : argv;
+
+  if (args.includes("--help") || args.includes("-h") || cmd === "help") {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  switch (cmd) {
+    case "start": {
+      if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error("codemax start needs a TTY");
+        process.exit(2);
+      }
+      const ledger = new Ledger(cwd);
+      const agentFlag = flag(args, "--agent") ?? flag(args, "-a");
+      const agent = (agentFlag ?? config.order[0] ?? "claude") as AgentId;
+      getAdapter(agent); // validate
+      if (args.includes("--raw")) {
+        const orch = new Orchestrator(config, ledger, cwd);
+        await orch.start(agent, args.includes("--fresh"));
+      } else if (args.includes("--tui") || !hasEngine(agent)) {
+        await runApp(config, ledger, cwd, agent, args.includes("--fresh"));
+      } else {
+        await runChat(config, ledger, cwd, agent, args.includes("--fresh"), !agentFlag);
+      }
+      process.exit(0);
+    }
+    case "agents": {
+      const ledger = new Ledger(cwd);
+      const sessions = ledger.sessions();
+      const quota = ledger.quota();
+      for (const a of listAdapters(config.order)) {
+        const d = await a.detect();
+        const s = sessions[a.id];
+        const q = quota[a.id];
+        console.log(
+          `${a.id.padEnd(9)} ${a.name.padEnd(13)} ${d.installed ? `✓ ${d.version ?? ""}`.padEnd(14) : "✗ not found".padEnd(14)} ` +
+            `${s ? `session ${s.id.slice(0, 8)}…` : "no session".padEnd(16)} ${q ? quotaLabel(q) : ""}`,
+        );
+      }
+      return;
+    }
+    case "status": {
+      const ledger = new Ledger(cwd);
+      const turns = ledger.turns();
+      const events = ledger.events();
+      console.log(`project: ${cwd}\nledger:  ${ledger.dir}\nturns:   ${turns.length}\nevents:  ${events.length}`);
+      const byAgent = new Map<string, number>();
+      for (const t of turns) byAgent.set(t.agent, (byAgent.get(t.agent) ?? 0) + 1);
+      for (const [a, n] of byAgent) console.log(`  ${a}: ${n} turns`);
+      const last = events.slice(-5);
+      if (last.length) {
+        console.log("recent events:");
+        for (const e of last) console.log(`  ${new Date(e.ts).toLocaleString()}  ${e.kind}  ${e.agent ?? ""}${e.to ? ` → ${e.to}` : ""}  ${e.detail ?? ""}`);
+      }
+      return;
+    }
+    case "history": {
+      const n = Number(flag(args, "-n") ?? 20);
+      const turns = new Ledger(cwd).turns().slice(-n);
+      for (const t of turns) {
+        const who = t.role === "user" ? "USER" : `${t.agent.toUpperCase()}`;
+        console.log(`\n[${new Date(t.ts).toLocaleTimeString()}] ${who}${t.tools?.length ? ` (tools: ${t.tools.join(", ")})` : ""}\n${t.text.slice(0, 600)}`);
+      }
+      return;
+    }
+    case "brief": {
+      const to = (flag(args, "--to") ?? "codex") as AgentId;
+      console.log(await buildBrief({ ledger: new Ledger(cwd), cwd, to, config }));
+      return;
+    }
+    case "config": {
+      console.log(`${CONFIG_PATH}\nhotkeys: ${hotkeyLabel(config.hotkeys)}\n${JSON.stringify(config, null, 2)}`);
+      return;
+    }
+    case "prices": {
+      if (args[0] === "update") {
+        const l = await fetchLivePrices();
+        if (!l) return console.log("could not reach openrouter.ai or the LiteLLM list; keeping the current table");
+        resetPriceCache();
+        console.log(`updated: ${Object.keys(l.prices).length} models from ${l.source} → ${LIVE_PRICES_PATH}`);
+      }
+      const prov = priceProvenance();
+      const cache = loadLivePrices();
+      console.log(`price source: ${prov.source} list as of ${prov.asOf}${cache ? ` (${Object.keys(cache.prices).length} models cached, refreshed weekly)` : " (built-in table; run codemax prices update to download the current list)"}`);
+      console.log(`overrides: ~/.codemax/prices.json`);
+      const model = args.find((a) => a !== "update");
+      if (model) {
+        const hit = priceFor(model);
+        console.log(hit ? `${model}: $${hit.price.input}/M in · $${hit.price.output}/M out · cache read $${hit.price.cacheRead ?? hit.price.input * 0.1}/M (matched "${hit.key}" from ${hit.source})` : `${model}: no price found`);
+      }
+      return;
+    }
+    case "usage": {
+      if (args.includes("--all")) {
+        const { readdirSync, existsSync } = await import("node:fs");
+        const { join } = await import("node:path");
+        const { CODEMAX_HOME } = await import("./core/paths.ts");
+        const root = join(CODEMAX_HOME, "projects");
+        const all = existsSync(root) ? readdirSync(root).flatMap((d) => new Ledger("/", join(root, d)).usage()) : [];
+        for (const l of renderUsageTable(all, { title: "Usage across all projects" })) console.log(l);
+        return;
+      }
+      const u = new Ledger(cwd).usage();
+      for (const l of renderUsageTable(u, { title: `Usage for ${cwd}` })) console.log(l);
+      console.log(`  total ${fmtUsd(sumCost(u))} · prices: ~/.codemax/prices.json overrides the built-in list`);
+      return;
+    }
+    case "doctor": {
+      const findings = diagnose();
+      if (!findings.length) return console.log("all clear: no API-key billing or silent-permission issues found");
+      for (const f of findings) {
+        console.log(`${f.severity === "block" ? "BLOCK" : "warn "} [${f.agent}] ${f.message}`);
+        if (f.fix) console.log(`      fix: ${f.fix.description}${args.includes("--fix") ? "" : "  (run: codemax doctor --fix)"}`);
+        if (f.fix && args.includes("--fix")) console.log(`      → ${f.fix.apply()}`);
+      }
+      return;
+    }
+    case "update": {
+      const latest = await checkForUpdate(pkg.version, { force: true });
+      console.log(latest ? `codemax ${latest} is available (you have ${pkg.version})` : `codemax ${pkg.version} is the latest`);
+      if (args.includes("--check") || !latest) return;
+      const plan = updatePlan();
+      if (plan.manual) return console.log(plan.manual);
+      console.log(`updating with ${plan.label} (${installKind().kind} install)\n`);
+      for (const cmd of plan.cmd) {
+        const p = Bun.spawn(platformArgv(cmd), { stdin: "inherit", stdout: "inherit", stderr: "inherit", env: { ...process.env, ...(plan.env ?? {}) } });
+        if ((await p.exited) !== 0) {
+          console.error(`\nupdate failed · run it yourself: ${plan.cmd.map((c) => c.join(" ")).join(" && ")}`);
+          process.exit(1);
+        }
+      }
+      console.log("\ncodemax updated.");
+      return;
+    }
+    case "awake": {
+      const v = (args[0] ?? "status").toLowerCase();
+      const support = process.platform === "linux" ? "sleep, lid close and shutdown are blocked (systemd-inhibit)" : process.platform === "darwin" ? "sleep is blocked; lid close needs your admin password once; macOS cannot block shutdown" : process.platform === "win32" ? "sleep is blocked; lid close switches the lid action to 'do nothing' and back; Windows cannot block shutdown" : "not supported on this platform";
+      if (v === "status") {
+        console.log(`awake: ${config.awake ?? "off"} (applies while codemax runs)\n${process.platform}: ${support}`);
+        return;
+      }
+      if (v !== "on" && v !== "lid" && v !== "off") {
+        console.error("usage: codemax awake [on|lid|off|status]");
+        process.exit(2);
+      }
+      if (v === "off") for (const n of await recoverAwake({ ...defaultAwakeDeps(), pid: -1, interactive: (fn) => fn() })) console.log(n);
+      if (v === "lid" && process.platform === "darwin") {
+        console.log("macOS needs your admin password to keep working with the lid closed (pmset disablesleep).");
+        const ok = Bun.spawnSync(["sudo", "-v"], { stdin: "inherit", stdout: "inherit", stderr: "inherit" }).exitCode === 0;
+        if (!ok) console.log("no admin rights: lid-close will not be enabled; the Mac still will not idle-sleep.");
+      }
+      saveConfigKey("awake", v);
+      console.log(v === "off" ? "awake off: the machine sleeps normally" : `awake ${v}: applies whenever codemax is running · ${support}`);
+      if (v === "lid") console.log("With the lid closed, keep the laptop somewhere it can breathe: not in a bag.");
+      return;
+    }
+    case "quota": {
+      const ledger = new Ledger(cwd);
+      if (args[0] === "clear") {
+        ledger.clearQuota(args[1] as AgentId | undefined);
+        console.log(args[1] ? `cleared quota state for ${args[1]}` : "cleared all quota state");
+        return;
+      }
+      const all = ledger.quota();
+      if (!Object.keys(all).length) return console.log("no quota state recorded");
+      for (const q of Object.values(all)) console.log(`${q.agent.padEnd(9)} ${quotaLabel(q) || "ok"}  (${q.source}, ${new Date(q.at).toLocaleString()}${q.detail ? `, ${q.detail}` : ""})`);
+      return;
+    }
+    case "keys": {
+      if (!process.stdin.isTTY) {
+        console.error("codemax keys needs a TTY");
+        process.exit(2);
+      }
+      const specs = parseHotkeys(config.hotkeys);
+      console.log(`press keys to see what your terminal sends. configured hotkeys: ${hotkeyLabel(config.hotkeys)}. q or Ctrl+C to quit.\n`);
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.on("data", (chunk: Buffer) => {
+        const bytes = new Uint8Array(chunk);
+        const hit = findHotkey(bytes, specs);
+        process.stdout.write(`${describeBytes(bytes)}${hit ? `   ← matches hotkey ${hit.name}` : ""}\r\n`);
+        if (bytes.length === 1 && (bytes[0] === 0x03 || bytes[0] === 0x71)) {
+          process.stdin.setRawMode(false);
+          process.exit(0);
+        }
+      });
+      await new Promise(() => {});
+      return;
+    }
+    default:
+      console.error(`unknown command "${cmd}"\n\n${HELP}`);
+      process.exit(2);
+  }
+}
+
+main(process.argv.slice(2)).catch((e) => {
+  console.error(`codemax: ${e?.message ?? e}`);
+  process.exit(1);
+});