codemax-cli 0.1.1 → 0.1.3

package/src/chat/app.ts

@@ -1,6 +1,7 @@
 import { BoxRenderable, TextRenderable, TextareaRenderable, createCliRenderer, type CliRenderer, type KeyEvent } from "@opentui/core";
 import type { Config } from "../config.ts";
-import { hotkeyLabel, saveConfigKey } from "../config.ts";
+import { CONFIG_PATH, hotkeyLabel, saveConfigKey } from "../config.ts";
+import { homedir } from "node:os";
 import type { AgentId, QuotaStatus, SessionRef } from "../adapters/types.ts";
 import { listAdapters, getAdapter } from "../adapters/index.ts";
 import { Ledger } from "../core/ledger.ts";
@@ -26,10 +27,16 @@ import pkg from "../../package.json" with { type: "json" };
 import { platformArgv, shellArgv } from "../core/spawn.ts";
 import { cleanError, isLimitNotice, parseResetTime } from "../engines/errors.ts";
 import { TurnRecorder } from "../core/journal.ts";
+import { Awake, defaultAwakeDeps, recoverAwake } from "../core/awake.ts";
+import { buildReviewPrompt, forwardMessage, isForwardedNote, parseNote } from "../core/review.ts";
+import { logoLines } from "./logo.ts";
+import { checkForUpdate, updatePlan } from "../core/update.ts";
 
 const HOTKEY_NAMES: Record<string, string[]> = { "/": ["/", "_", "?"], "^": ["^", "6"] };
 const VERSION = pkg.version;
 const MODE_CYCLE = ["default", "acceptEdits", "plan"];
+/** Most side-agent notes sent automatically per task; more wait for /forward. */
+const AUTO_FORWARD_CAP = 2;
 
 interface Active {
   agent: AgentId;
@@ -89,6 +96,19 @@ export class ChatApp {
   private switching = false;
   /** Set by quit(); async work that resumes afterwards (a handoff being built) stops. */
   private closed = false;
+  /** Side agent (/side): reviews the main agent's work after each turn. */
+  private reviewer: { agent: AgentId; name: string; engine: Engine; busy: boolean; pending: boolean; since: number; primed: boolean } | null = null;
+  private notes: { ts: number; agent: AgentId; name: string; text: string }[] = [];
+  /** Working turns since the side agent last reviewed (for `sideAgent.every`). */
+  private turnsSinceReview = 0;
+  /** Notes sent automatically per task (auto mode is capped so the two agents cannot loop). */
+  private autoForwards = new Map<string, number>();
+  /** A newer codemax on npm, when the update check found one. */
+  private updateAvailable: string | null = null;
+  /** Update check (tests swap it; it never runs under `bun test`). */
+  updateChecker: (current: string) => Promise<string | null> = (current) => (process.env.NODE_ENV === "test" ? Promise.resolve(null) : checkForUpdate(current));
+  /** Keep-awake (/awake). Tests swap its system runner. */
+  awake = new Awake({ ...defaultAwakeDeps(), interactive: (fn) => this.withTerminal(fn) });
   private resolveDone!: () => void;
   readonly done: Promise<void>;
   /** Test hooks. */
@@ -160,7 +180,10 @@ export class ChatApp {
     });
 
     renderer.keyInput.on("keypress", this.onKey);
-    renderer.on("resize", () => this.palette?.render());
+    renderer.on("resize", () => this.safely("resize", () => {
+      this.palette?.render();
+      this.renderFooter();
+    }));
     this.input.focus();
     this.renderFooter();
   }
@@ -177,10 +200,20 @@ export class ChatApp {
     if (!first) throw new Error("no agent with a protocol engine found (need claude, codex, opencode, grok or gemini on PATH)");
     const notes: string[] = [];
     if (first !== agent) notes.push(`${agent} has no protocol engine here; starting ${first}`);
+    for (const n of await recoverAwake({ ...defaultAwakeDeps(), interactive: (fn) => this.withTerminal(fn) }).catch(() => [])) notes.push(n);
+    if (this.config.awake && this.config.awake !== "off") {
+      const st = await this.awake.set(this.config.awake).catch(() => null);
+      if (st) notes.push(st.mode === "off" ? "keep-awake could not be turned on" : `keeping this machine awake${st.lid ? ", lid closed included" : ""} (/awake off to stop)`, ...st.notes);
+    }
     const stripped = strippedKeys();
     if (stripped.length) notes.push(`${stripped.join(", ")} unset for agents · subscription logins only`);
-    this.transcript.header({ title: `codemax v${VERSION}`, subtitle: "one terminal, every coding agent", path: this.cwd, notes });
+    // Card border (2) + padding (2) + transcript padding (2): the logo must fit inside without wrapping.
+    this.transcript.header({ title: `codemax v${VERSION}`, subtitle: "one terminal, every coding agent", path: this.cwd, notes, logo: logoLines(this.renderer.width - 6) });
     if ((this.config as any).priceUpdates !== false) void refreshLivePricesIfStale().then((l) => l && resetPriceCache());
+    if (this.config.updateCheck !== false)
+      void this.updateChecker(VERSION)
+        .then((v) => v && this.announceUpdate(v))
+        .catch(() => {});
     if (o.pick && !fresh && this.openPicker(first)) return this.done;
     await this.launch(first, { fresh });
     return this.done;
@@ -188,7 +221,29 @@ export class ChatApp {
 
   // ---------- keys ----------
 
-  private onKey = (key: KeyEvent) => {
+  /**
+   * The UI must never break: a failure while handling one event, key or redraw is
+   * shown as a short line and codemax carries on.
+   */
+  private uiErrors = 0;
+  private safely(where: string, fn: () => void) {
+    try {
+      fn();
+    } catch (e: any) {
+      this.uiErrors++;
+      if (this.uiErrors <= 5) {
+        try {
+          this.transcript.error(`display glitch in ${where}: ${String(e?.message ?? e).slice(0, 160)} (codemax keeps going)`);
+        } catch {
+          /* the screen itself is gone */
+        }
+      }
+    }
+  }
+
+  private onKey = (key: KeyEvent) => this.safely("key handling", () => this.handleKey(key));
+
+  private handleKey(key: KeyEvent) {
     if (key.eventType === "release") return;
     if (this.permission) {
       key.stopPropagation();
@@ -262,7 +317,7 @@ export class ChatApp {
       this.shortcuts.visible = !this.shortcuts.visible;
       return;
     }
-  };
+  }
 
   private isHotkey(key: KeyEvent): boolean {
     if (key.raw && findHotkey(new TextEncoder().encode(key.raw), this.hotkeys)) return true;
@@ -309,6 +364,10 @@ export class ChatApp {
       else this.palette.setFilter(text.slice(1));
     } else if (this.palette && this.paletteKind === "commands") {
       this.closePalette();
+    } else if (this.palette && this.paletteKind !== "handoff" && this.paletteKind !== "files" && !text.includes("\n")) {
+      // Every picker filters as you type (agents, models, settings…), like Claude Code's.
+      this.palette.setFilter(text);
+      this.paletteFiltered = text.length > 0;
     }
     if (this.shortcuts.visible && text) this.shortcuts.visible = false;
   }
@@ -552,24 +611,30 @@ export class ChatApp {
   }
 
   /** Startup picker: resume a recent session or start fresh. Returns false when there is nothing to pick. */
+  /**
+   * Startup: choose the agent to continue with. One row per usable agent, most
+   * recently used first, resuming its saved session when there is one.
+   */
   private openPicker(defaultAgent: AgentId): boolean {
-    const sessions = Object.values(this.ledger.sessions()).filter((s): s is SessionRef => !!s && !!this.detect.get(s.agent)?.engine);
-    if (!sessions.length) return false;
-    sessions.sort((a, b) => b.lastUsedAt - a.lastUsedAt);
+    const sessions = this.ledger.sessions();
     const turns = this.ledger.turns();
-    const items: PaletteItem[] = sessions.map((s, i) => {
-      const last = [...turns].reverse().find((t) => t.agent === s.agent && t.role === "user");
-      return {
-        label: `Resume ${getAdapter(s.agent).name}`,
-        description: `${ago(s.lastUsedAt)}${last ? ` · "${last.text.replace(/\s+/g, " ").slice(0, 60)}"` : ""}`,
-        value: `resume:${s.agent}`,
-        weight: 100 - i,
-      };
+    const usable = listAdapters(this.config.order).filter((a) => this.detect.get(a.id)?.installed && this.detect.get(a.id)?.engine);
+    if (!usable.length) return false;
+    const recent = [...usable].sort((a, b) => (sessions[b.id]?.lastUsedAt ?? 0) - (sessions[a.id]?.lastUsedAt ?? 0));
+    const items: PaletteItem[] = recent.map((a, i) => {
+      const s = sessions[a.id];
+      const last = [...turns].reverse().find((t) => t.agent === a.id && t.role === "user");
+      const q = this.quota.get(a.id);
+      const bits = [s ? `resume · ${ago(s.lastUsedAt)}${last ? ` · "${last.text.replace(/\s+/g, " ").slice(0, 50)}"` : ""}` : "new session"];
+      if (q && quotaLabel(q)) bits.push(quotaLabel(q));
+      return { label: a.name, description: bits.join(" · "), value: `resume:${a.id}`, weight: 100 - i };
     });
-    items.push({ label: `New session with ${getAdapter(defaultAgent).name}`, description: "start fresh (history stays in the ledger)", value: `new:${defaultAgent}`, weight: 0 });
+    const fresh = recent[0]!;
+    items.push({ label: `Start fresh with ${fresh.name}`, description: "new session (history stays in the ledger)", value: `new:${fresh.id}`, weight: 0 });
+    defaultAgent = sessions[fresh.id] ? fresh.id : defaultAgent;
     this.paletteKind = "picker";
     this.palette = new Palette(this.renderer, {
-      title: "Resume a session · Enter to continue · Esc for the most recent",
+      title: `Choose an agent to continue with · Enter to start · Esc for ${getAdapter(defaultAgent).name}`,
       items,
       onPick: (it) => {
         this.closePalette();
@@ -578,7 +643,7 @@ export class ChatApp {
       },
       onClose: () => {
         this.closePalette();
-        void this.launch(sessions[0]!.agent, { fresh: false });
+        void this.launch(defaultAgent, { fresh: false });
       },
     }, this.paletteAnchor);
     this.renderer.root.add(this.palette.box);
@@ -598,6 +663,7 @@ export class ChatApp {
   }
 
   private async send(active: Active, text: string) {
+    if (this.closed) return;
     this.transcript.user(text);
     text = this.withAttachments(text);
     const cp = await this.checkpoint(active, text);
@@ -635,11 +701,55 @@ export class ChatApp {
       { name: "/checkpoints", description: "List working-tree snapshots taken before each turn", run: () => void this.showCheckpoints() },
       { name: "/ask", description: "Send one message to another agent without switching: /ask codex <msg>", run: (a) => void this.ask(a) },
       { name: "/budget", description: "Today's spend against your daily budgets", run: () => this.showBudget() },
+      { name: "/update", description: "Update codemax to the latest version", run: () => void this.runUpdate() },
+      { name: "/config", description: "Settings: theme, keep awake, side agent and model, handoffs, checkpoints…", run: () => this.openConfig() },
+      { name: "/side", description: "Side agent that reviews each turn: /side (pick agent and model) · /side codex <model> [auto] · /side off", run: (a) => void this.setSide(a) },
+      { name: "/review", description: "Ask the side agent to review the latest work now", run: () => void this.reviewNow() },
+      { name: "/notes", description: "Notes the side agent left", run: () => this.showNotes() },
+      { name: "/forward", description: "Send the side agent's latest note (or /forward <n>) to the main agent", run: (a) => this.forwardNote(a.trim() ? Number(a) - 1 : undefined) },
+      { name: "/awake", description: "Keep the machine awake while agents work: /awake on | lid | off", run: (a) => void this.setAwake(a) },
       { name: "/theme", description: "Colour theme: /theme dark | light | auto (saved; restart to apply everywhere)", run: (a) => this.setThemePref(a) },
       { name: "/quit", description: "Quit codemax", run: () => void this.quit() },
     ];
   }
 
+  /** Run something that needs the real terminal (a sudo password prompt): pause the screen around it. */
+  private async withTerminal<T>(fn: () => Promise<T>): Promise<T> {
+    try {
+      await this.renderer.suspend();
+    } catch {
+      /* test renderer */
+    }
+    try {
+      return await fn();
+    } finally {
+      try {
+        await this.renderer.resume();
+      } catch {
+        /* test renderer */
+      }
+    }
+  }
+
+  private async setAwake(arg: string) {
+    const v = arg.trim().toLowerCase();
+    if (v !== "on" && v !== "lid" && v !== "off") {
+      const s = this.awake.status;
+      this.transcript.note(`awake: ${s.mode}${s.lid ? " (lid closed included)" : ""} · /awake on keeps the machine from sleeping · /awake lid also keeps working with the lid closed · /awake off`);
+      return;
+    }
+    const st = await this.awake.set(v);
+    try {
+      saveConfigKey("awake", st.mode);
+    } catch {
+      /* read-only home */
+    }
+    this.config.awake = st.mode;
+    this.transcript.note(st.mode === "off" ? (v === "off" ? "awake off: the machine can sleep normally again" : "keep-awake could not be turned on") : `awake ${st.mode}: this machine will not sleep while codemax runs${st.lid ? ", even with the lid closed" : ""}`, st.mode === "off" ? C.dim : C.accent);
+    for (const n of st.notes) this.transcript.note(n, C.warn);
+    this.renderFooter();
+  }
+
   private setThemePref(arg: string) {
     const v = arg.trim().toLowerCase();
     if (v !== "dark" && v !== "light" && v !== "auto") {
@@ -950,10 +1060,15 @@ export class ChatApp {
     this.renderer.root.add(this.palette.box);
   }
 
+  /** True while text in the prompt is only filtering a picker; it is cleared when the picker closes. */
+  private paletteFiltered = false;
+
   private closePalette(_focus = true) {
     this.palette?.destroy();
     this.palette = null;
     this.paletteKind = null;
+    if (this.paletteFiltered) this.input.clear();
+    this.paletteFiltered = false;
     this.input.focus();
   }
 
@@ -1035,6 +1150,7 @@ export class ChatApp {
   }
 
   private async runTurn(active: Active, text: string, o: { record?: boolean; rec?: TurnRecorder; journal?: boolean } = {}) {
+    if (this.closed) return;
     const block = this.transcript.agent();
     const rec = o.journal === false ? undefined : (o.rec ?? new TurnRecorder(this.ledger.journal, active.agent));
     active.turn = { block, tools: new Set(), startedAt: Date.now(), tokens: 0, chars: 0, verb: pick(VERBS), rec };
@@ -1057,6 +1173,14 @@ export class ChatApp {
       const reply = block.text().trim();
       if (isLimitNotice(reply)) turn.rec?.markLimit(reply);
       turn.rec?.end(stop);
+      // The side agent reviews main-agent turns that did work (not /ask, not summaries).
+      // A turn that only answers a forwarded note is not reviewed: note → turn → review → note
+      // would loop on both plans. Its work is covered by the next review after a user turn.
+      if (turn.rec && this.active === active && !this.side.has(active) && !isForwardedNote(text) && (turn.tools.size > 0 || reply.length > 0)) {
+        const every = this.config.sideAgent?.every ?? 1;
+        this.turnsSinceReview++;
+        if (every > 0 && this.turnsSinceReview >= every) void this.review();
+      }
       if (isLimitNotice(reply)) {
         // The agent ended the turn with only a limit notice: treat it as running out, and leave
         // the user's request unanswered in the ledger so the next agent is asked to finish it.
@@ -1076,6 +1200,10 @@ export class ChatApp {
   }
 
   private onEngineEvent(active: Active, e: EngineEvent) {
+    this.safely(`${active.name} event`, () => this.handleEngineEvent(active, e));
+  }
+
+  private handleEngineEvent(active: Active, e: EngineEvent) {
     if (this.active !== active && !this.side.has(active) && e.type !== "permission_request") return;
     const target = () => active.turn?.block ?? (active.replay ??= this.transcript.agent());
     switch (e.type) {
@@ -1124,27 +1252,7 @@ export class ChatApp {
           this.renderFooter();
         }
         if (typeof e.usedPercent === "number") this.onQuota({ agent: active.agent, usedPercent: e.usedPercent, exhausted: e.usedPercent >= 100, source: "probe", at: Date.now() });
-        const hasTokens = (e.inputTokens ?? 0) + (e.outputTokens ?? 0) + (e.cacheReadTokens ?? 0) + (e.cacheWriteTokens ?? 0) > 0;
-        // A zero cost with no tokens (free models report cost 0 on every update) is not usage.
-        if (hasTokens || (e.costUsd ?? 0) > 0) {
-          const rec = priceRecord({
-            ts: Date.now(),
-            agent: active.agent,
-            sessionId: active.engine.session?.id ?? "?",
-            model: e.model ?? active.engine.info?.currentModel,
-            input: e.inputTokens ?? 0,
-            output: e.outputTokens ?? 0,
-            cacheRead: e.cacheReadTokens ?? 0,
-            cacheWrite: e.cacheWriteTokens ?? 0,
-            agentCostUsd: typeof e.costUsd === "number" ? e.costUsd : undefined,
-          });
-          this.ledger.addUsage(rec);
-          this.sessionCost += recordCost(rec).usd;
-          this.sessionTokens += rec.input + rec.output + rec.cacheRead + rec.cacheWrite;
-          addSpend(this.today, rec);
-          this.renderFooter();
-          this.checkBudget(active.agent);
-        }
+        this.recordUsage(active.agent, active.engine, e);
         break;
       }
       case "session":
@@ -1205,6 +1313,393 @@ export class ChatApp {
 
   // ---------- working line, footer ----------
 
+  /** Price and record a usage event (main, /ask and side-agent sessions alike). */
+  private recordUsage(agent: AgentId, engine: Engine, e: Extract<EngineEvent, { type: "usage" }>) {
+    const hasTokens = (e.inputTokens ?? 0) + (e.outputTokens ?? 0) + (e.cacheReadTokens ?? 0) + (e.cacheWriteTokens ?? 0) > 0;
+    // A zero cost with no tokens (free models report cost 0 on every update) is not usage.
+    if (!hasTokens && !((e.costUsd ?? 0) > 0)) return;
+    const rec = priceRecord({
+      ts: Date.now(),
+      agent,
+      sessionId: engine.session?.id ?? "?",
+      model: e.model ?? engine.info?.currentModel,
+      input: e.inputTokens ?? 0,
+      output: e.outputTokens ?? 0,
+      cacheRead: e.cacheReadTokens ?? 0,
+      cacheWrite: e.cacheWriteTokens ?? 0,
+      agentCostUsd: typeof e.costUsd === "number" ? e.costUsd : undefined,
+    });
+    this.ledger.addUsage(rec);
+    this.sessionCost += recordCost(rec).usd;
+    this.sessionTokens += rec.input + rec.output + rec.cacheRead + rec.cacheWrite;
+    addSpend(this.today, rec);
+    this.renderFooter();
+    this.checkBudget(agent);
+  }
+
+  // ---------- side agent ----------
+
+  /**
+   * /side                     pick the side agent, then its model
+   * /side <agent> [model] [auto|ask]
+   * /side off
+   */
+  private async setSide(arg: string) {
+    const words = arg.trim().split(/\s+/).filter(Boolean);
+    const cfg = this.config.sideAgent ?? { agent: null, forward: "ask" as const };
+    if (!words.length) return this.openSidePicker();
+    const who = words[0]!.toLowerCase();
+    if (who === "off") {
+      await this.closeReviewer();
+      this.saveSide({ ...cfg, agent: null, model: undefined });
+      this.transcript.note("side agent off", C.dim);
+      return this.renderFooter();
+    }
+    if (!this.detect.get(who as AgentId)?.engine) return this.transcript.note(`no protocol engine for "${who}" · /side to pick one`, C.warn);
+    const rest = words.slice(1);
+    const forward = rest.includes("auto") ? "auto" : rest.includes("ask") ? "ask" : cfg.agent === who ? cfg.forward : "ask";
+    const model = rest.find((w) => w !== "auto" && w !== "ask");
+    await this.enableSide(who as AgentId, { forward, model, pickModel: false });
+  }
+
+  private saveSide(v: Config["sideAgent"]) {
+    this.config.sideAgent = v;
+    try {
+      saveConfigKey("sideAgent", v);
+    } catch {
+      /* read-only home */
+    }
+  }
+
+  private async enableSide(agent: AgentId, o: { forward: "ask" | "auto"; model?: string; pickModel: boolean }) {
+    const prev = this.config.sideAgent;
+    if (prev?.agent !== agent || (o.model && o.model !== prev.model)) await this.closeReviewer();
+    // Keep the user's other side-agent settings (review cadence) when switching agent.
+    this.saveSide({ ...prev, agent, forward: o.forward, model: o.model ?? (prev?.agent === agent ? prev.model : undefined) });
+    const name = getAdapter(agent).name;
+    if (agent === this.active?.agent) this.transcript.note(`${name} is also the main agent: both use one ${name} plan, so each review brings the main agent's limit closer. A different subscription (or a cheaper model: /side ${agent} <model>, or fewer reviews in /config) keeps it from running out sooner.`, C.warn);
+    this.transcript.note(`side agent: ${name}${this.config.sideAgent.model ? ` (${this.config.sideAgent.model})` : ""} reviews ${reviewCadence(this.config.sideAgent.every)} and speaks up only when something needs attention${o.forward === "auto" ? "; its notes go to the main agent automatically" : " · /forward sends a note to the main agent"}`, C.accent);
+    this.renderFooter();
+    if (!o.pickModel) return;
+    // Start the reviewer now so its real model list can be offered.
+    const r = await this.ensureReviewer();
+    const models = r?.engine.info?.models ?? [];
+    if (!r || models.length < 2) {
+      if (r && models.length === 1) this.transcript.note(`${name} offers one model on your plan: ${models[0]!.name}`);
+      return;
+    }
+    this.closePalette();
+    this.paletteKind = "modes";
+    this.palette = new Palette(this.renderer, {
+      title: `Model for the side agent (${name}) · Esc keeps ${shortModelName(r.engine.info?.currentModel ?? "default")}`,
+      items: models.map((m) => ({ label: m.id, description: `${m.name !== m.id ? m.name : ""}${m.id === r.engine.info?.currentModel ? "  (current)" : ""}`, value: m.id })),
+      onPick: (it) => {
+        this.closePalette();
+        void this.setSideModel(it.value);
+      },
+      onClose: () => this.closePalette(),
+    }, this.paletteAnchor);
+    this.renderer.root.add(this.palette.box);
+  }
+
+  private async setSideModel(model: string) {
+    const cfg = this.config.sideAgent;
+    if (!cfg?.agent) return this.transcript.note("no side agent · /side to pick one", C.warn);
+    this.saveSide({ ...cfg, model });
+    const r = this.reviewer;
+    try {
+      if (r?.engine.setModel) await r.engine.setModel(model);
+      this.transcript.note(`side agent model: ${model}`);
+      if (cfg.agent === "cursor") this.transcript.note("Cursor saves this as its default model, so Cursor uses it outside codemax too", C.warn);
+    } catch (e: any) {
+      this.transcript.error(`could not set the side agent's model: ${e?.message ?? e}`);
+    }
+    this.renderFooter();
+  }
+
+  // ---------- settings (/config) ----------
+
+  private settings(): { key: string; label: string; value: string; choices: { value: string; label?: string; description?: string }[]; apply: (v: string) => void | Promise<void> }[] {
+    const c = this.config;
+    const onOff = (b: boolean) => (b ? "on" : "off");
+    const bool = (key: "autoSwitch" | "summarizeOnSwitch" | "checkpoints" | "priceUpdates") => (v: string) => {
+      c[key] = v === "on";
+      saveConfigKey(key, c[key]);
+    };
+    const side = c.sideAgent ?? { agent: null, forward: "ask" as const };
+    const agents = listAdapters(c.order).filter((a) => this.detect.get(a.id)?.engine);
+    return [
+      { key: "theme", label: "Theme", value: c.theme ?? "auto", choices: [{ value: "auto", description: "follow the terminal's background" }, { value: "dark" }, { value: "light" }], apply: (v) => this.setThemePref(v) },
+      { key: "awake", label: "Keep awake", value: c.awake ?? "off", choices: [{ value: "off", description: "sleep normally" }, { value: "on", description: "no sleep while codemax runs" }, { value: "lid", description: "also keep working with the lid closed" }], apply: (v) => this.setAwake(v) },
+      { key: "side", label: "Side agent", value: side.agent ?? "off", choices: [{ value: "off" }, ...agents.map((a) => ({ value: a.id, label: a.name, description: "pick its model next" }))], apply: (v) => (v === "off" ? this.setSide("off") : this.enableSide(v as AgentId, { forward: side.forward, pickModel: true })) },
+      { key: "sideModel", label: "Side agent model", value: side.agent ? (side.model ?? "default") : "(no side agent)", choices: side.agent ? [{ value: "pick", label: "Choose from its models", description: "starts the side agent to list them" }] : [], apply: async () => { if (side.agent) await this.enableSide(side.agent, { forward: side.forward, pickModel: true }); } },
+      {
+        key: "sideEvery",
+        label: "Side agent reviews",
+        value: reviewCadence(side.every),
+        choices: [{ value: "1", label: "every turn" }, { value: "2", label: "every 2nd turn" }, { value: "3", label: "every 3rd turn" }, { value: "0", label: "only on /review", description: "no automatic reviews" }],
+        apply: (v) => this.saveSide({ ...side, every: Number(v) }),
+      },
+      { key: "sideForward", label: "Side agent notes", value: side.forward, choices: [{ value: "ask", description: "wait for /forward" }, { value: "auto", description: "send each note to the main agent" }], apply: (v) => this.saveSide({ ...side, forward: v === "auto" ? "auto" : "ask" }) },
+      { key: "autoSwitch", label: "Offer a handoff at limits", value: onOff(c.autoSwitch), choices: [{ value: "on" }, { value: "off" }], apply: bool("autoSwitch") },
+      { key: "summarizeOnSwitch", label: "Summary before switching", value: onOff(c.summarizeOnSwitch), choices: [{ value: "on", description: "only for history without a step journal" }, { value: "off" }], apply: bool("summarizeOnSwitch") },
+      { key: "checkpoints", label: "Snapshots for /undo", value: onOff(c.checkpoints), choices: [{ value: "on" }, { value: "off", description: "also turns off code diffs in handoffs" }], apply: bool("checkpoints") },
+      {
+        key: "bell",
+        label: "Bell after long turns",
+        value: c.bellAfterSeconds ? `${c.bellAfterSeconds}s` : "off",
+        choices: [{ value: "0", label: "off" }, { value: "10", label: "10s" }, { value: "20", label: "20s" }, { value: "60", label: "60s" }],
+        apply: (v) => {
+          c.bellAfterSeconds = Number(v);
+          saveConfigKey("bellAfterSeconds", c.bellAfterSeconds);
+        },
+      },
+      { key: "updateCheck", label: "Check for codemax updates", value: c.updateCheck === false ? "off" : "on", choices: [{ value: "on", description: "asks npm at most every 12 hours" }, { value: "off" }], apply: (v) => { c.updateCheck = v === "on"; saveConfigKey("updateCheck", c.updateCheck); } },
+      { key: "priceUpdates", label: "Weekly price list refresh", value: onOff(c.priceUpdates), choices: [{ value: "on" }, { value: "off", description: "stay fully offline" }], apply: bool("priceUpdates") },
+    ];
+  }
+
+  /** /config: every setting with its value; pick one to change it. */
+  private openConfig() {
+    const all = this.settings();
+    this.closePalette();
+    this.paletteKind = "modes";
+    this.palette = new Palette(this.renderer, {
+      title: `Settings · Enter to change · saved to ${CONFIG_PATH.replace(homedir(), "~")}`,
+      // Weights keep the settings in this order (the palette otherwise sorts by label).
+      items: all.map((x, i) => ({ label: x.label, description: x.value, value: x.key, disabled: !x.choices.length, weight: 100 - i })),
+      maxRows: 12,
+      onPick: (it) => {
+        const st = all.find((x) => x.key === it.value);
+        if (st) this.openSetting(st);
+      },
+      onClose: () => this.closePalette(),
+    }, this.paletteAnchor);
+    this.renderer.root.add(this.palette.box);
+  }
+
+  private openSetting(st: ReturnType<ChatApp["settings"]>[number]) {
+    this.closePalette();
+    this.paletteKind = "modes";
+    this.palette = new Palette(this.renderer, {
+      title: `${st.label} · now ${st.value} · Esc back to settings`,
+      items: st.choices.map((ch, i) => ({ label: ch.label ?? ch.value, description: `${ch.description ?? ""}${(ch.label ?? ch.value) === st.value || ch.value === st.value ? "  (current)" : ""}`, value: ch.value, weight: 100 - i })),
+      onPick: (it) => {
+        this.closePalette();
+        void (async () => {
+          try {
+            await st.apply(it.value);
+            if (!["theme", "awake", "side", "sideModel"].includes(st.key)) this.transcript.note(`${st.label.toLowerCase()}: ${it.label}`);
+          } catch (e: any) {
+            this.transcript.error(`could not change ${st.label.toLowerCase()}: ${e?.message ?? e}`);
+          }
+          this.renderFooter();
+          // Back to the list for the next change, unless a follow-up picker took over.
+          if (!this.palette) this.openConfig();
+        })();
+      },
+      onClose: () => this.openConfig(),
+    }, this.paletteAnchor);
+    this.renderer.root.add(this.palette.box);
+  }
+
+  /** /side with no arguments: pick the agent (then its model). */
+  private openSidePicker() {
+    const cfg = this.config.sideAgent;
+    const items: PaletteItem[] = listAdapters(this.config.order)
+      .filter((a) => this.detect.get(a.id)?.engine)
+      // A different subscription first: the same tool would share (and drain) the main agent's plan.
+      .map((a) => ({ label: a.name + (a.id === cfg?.agent ? " (current)" : ""), description: a.id === this.active?.agent ? "same plan as the main agent: reviews count against its limit" : "its own subscription: reviews do not touch the main agent's limit", value: a.id, weight: a.id === this.active?.agent ? 0 : 10 }));
+    items.push({ label: "Off", description: "no side agent", value: "off" });
+    this.closePalette();
+    this.paletteKind = "modes";
+    this.palette = new Palette(this.renderer, {
+      title: "Side agent · reviews each turn and leaves a note when something needs attention",
+      items,
+      onPick: (it) => {
+        this.closePalette();
+        if (it.value === "off") return void this.setSide("off");
+        void this.enableSide(it.value as AgentId, { forward: cfg?.forward ?? "ask", pickModel: true });
+      },
+      onClose: () => this.closePalette(),
+    }, this.paletteAnchor);
+    this.renderer.root.add(this.palette.box);
+  }
+
+  /** The side agent's session, started on first use with the chosen model. */
+  private async ensureReviewer() {
+    const cfg = this.config.sideAgent;
+    if (!cfg?.agent || this.closed) return null;
+    if (this.reviewer?.agent === cfg.agent) return this.reviewer;
+    await this.closeReviewer();
+    if (this.checkBlockers(cfg.agent).length) return null;
+    const engine = this.engineFactory(cfg.agent);
+    const r = { agent: cfg.agent, name: getAdapter(cfg.agent).name, engine, busy: false, pending: false, since: this.lastReviewBaseline(), primed: false };
+    this.reviewer = r;
+    try {
+      await engine.start({ cwd: this.cwd });
+      if (cfg.model && engine.setModel && engine.info?.currentModel !== cfg.model) await engine.setModel(cfg.model).catch((e: any) => this.transcript.note(`side agent: could not use model ${cfg.model} (${e?.message ?? e}); using ${engine.info?.currentModel ?? "its default"}`, C.warn));
+      return r;
+    } catch (e: any) {
+      if (this.reviewer === r) this.reviewer = null;
+      this.transcript.note(`side agent ${r.name} could not start: ${e?.message ?? e}`, C.warn);
+      return null;
+    }
+  }
+
+  private async closeReviewer() {
+    const r = this.reviewer;
+    this.reviewer = null;
+    if (r) await r.engine.close().catch(() => {});
+  }
+
+  /** After a main turn: let the side agent review the new steps (in the background). */
+  private async review() {
+    const cfg = this.config.sideAgent;
+    if (!cfg?.agent || this.closed) return;
+    if (this.reviewer?.busy) {
+      this.reviewer.pending = true;
+      return;
+    }
+    const r = await this.ensureReviewer();
+    if (!r) return;
+    this.turnsSinceReview = 0;
+    r.busy = true;
+    this.renderFooter();
+    try {
+      do {
+        r.pending = false;
+        const steps = this.ledger.journal.steps();
+        const startedAt = Date.now();
+        const context = r.primed ? undefined : await buildBrief({ ledger: this.ledger, cwd: this.cwd, to: r.agent, config: this.config, purpose: "context" }).catch(() => undefined);
+        const prompt = buildReviewPrompt({ steps, since: r.since, mainAgent: this.active?.name ?? "the main agent", reviewer: r.agent, context });
+        if (!prompt) break;
+        let reply = "";
+        let limited = false;
+        const engine = r.engine;
+        const off = engine.onEvent((e) => {
+          try {
+          if (e.type === "text_delta") reply += e.text;
+          else if (e.type === "permission_request") {
+            // A reviewer never acts: refuse anything it asks to do.
+            const no = e.request.options.find((o) => /reject|deny|decline/i.test(`${o.kind} ${o.id}`)) ?? e.request.options.at(-1);
+            if (no) engine.answerPermission(e.request.id, no.id);
+          } else if (e.type === "usage") this.recordUsage(r.agent, engine, e);
+          else if (e.type === "error" && e.kind === "quota") limited = true;
+          } catch {
+            /* a bad event must never break the reviewer or the screen */
+          }
+        });
+        await engine.prompt(prompt).catch(() => "error");
+        off();
+        if (this.closed) return;
+        r.primed = true;
+        r.since = startedAt;
+        if (limited || isLimitNotice(reply)) {
+          this.transcript.note(`side agent ${r.name} hit its usage limit; turning it off for this session`, C.warn);
+          await this.closeReviewer();
+          this.renderFooter();
+          return;
+        }
+        const note = parseNote(reply);
+        if (note && !this.closed) this.addNote(r.agent, r.name, note);
+      } while (r.pending && this.reviewer === r && !this.closed);
+    } finally {
+      if (this.reviewer === r) r.busy = false;
+      this.renderFooter();
+    }
+  }
+
+  /** Review from the start of the current task the first time. */
+  private lastReviewBaseline(): number {
+    const req = this.ledger.journal.task().request;
+    return req ? req.ts - 1 : Date.now();
+  }
+
+  private addNote(agent: AgentId, name: string, text: string) {
+    if (this.closed) return;
+    this.notes.push({ ts: Date.now(), agent, name, text });
+    this.ledger.addEvent({ kind: "note", agent, detail: `side agent note: ${text.slice(0, 2000)}` });
+    const main = this.active?.name ?? "the main agent";
+    const auto = this.config.sideAgent?.forward === "auto";
+    const task = this.ledger.journal.task().request?.id ?? "none";
+    const sent = this.autoForwards.get(task) ?? 0;
+    const capped = auto && sent >= AUTO_FORWARD_CAP;
+    this.transcript.noteCard(
+      `⚑ Note from ${name} (side agent)`,
+      text,
+      auto && !capped ? `sent to ${main} automatically` : capped ? `auto-forward paused: ${AUTO_FORWARD_CAP} notes already sent for this task · /forward to send this one` : `/forward sends this to ${main} · /notes lists all notes`,
+    );
+    if (auto && !capped) {
+      this.autoForwards.set(task, sent + 1);
+      this.forwardNote(this.notes.length - 1);
+    }
+  }
+
+  private forwardNote(index = this.notes.length - 1) {
+    if (this.closed) return;
+    const n = this.notes[index];
+    const a = this.active;
+    if (!n) return this.transcript.note("no side-agent notes yet");
+    if (!a) return this.transcript.note("no main agent to forward to", C.warn);
+    const msg = forwardMessage(n.text, n.name);
+    if (a.turn || this.switching) {
+      this.queue.push(msg);
+      this.transcript.note(`note queued for ${a.name} until its turn ends`);
+      this.renderFooter();
+      return;
+    }
+    void this.send(a, msg);
+  }
+
+  private announceUpdate(version: string) {
+    if (this.closed) return;
+    this.updateAvailable = version;
+    this.transcript.note(`codemax ${version} is available (you have ${VERSION}) · run /update to install it`, C.accent);
+    this.renderFooter();
+  }
+
+  /** /update: update the way codemax was installed, with its output on the real terminal. */
+  private async runUpdate() {
+    const plan = updatePlan();
+    if (plan.manual) return this.transcript.note(plan.manual, C.warn);
+    if (this.active?.turn) return this.transcript.note("an agent is working; /update when the turn ends", C.warn);
+    this.transcript.note(`updating with ${plan.label}…`);
+    let ok = true;
+    await this.withTerminal(async () => {
+      process.stdout.write(`\ncodemax: updating with ${plan.label}\n\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) {
+          ok = false;
+          break;
+        }
+      }
+      process.stdout.write(ok ? "\ncodemax: done. Returning to codemax…\n" : "\ncodemax: the update failed (see above). Returning to codemax…\n");
+      await Bun.sleep(1200);
+    });
+    if (ok) {
+      const to = this.updateAvailable;
+      this.updateAvailable = null;
+      this.transcript.note(`updated${to ? ` to ${to}` : ""} · restart codemax (/quit, then codemax) to use the new version`, C.ok);
+    } else this.transcript.error(`update failed · run it yourself: ${plan.cmd.map((c) => c.join(" ")).join(" && ")}`);
+    this.renderFooter();
+  }
+
+  private async reviewNow() {
+    if (!this.config.sideAgent?.agent) return this.transcript.note("no side agent · /side to pick one", C.warn);
+    this.transcript.note(`asking ${getAdapter(this.config.sideAgent.agent).name} to review…`);
+    const before = this.notes.length;
+    await this.review();
+    if (this.notes.length === before && !this.closed) this.transcript.note("the side agent found nothing worth a note");
+  }
+
+  private showNotes() {
+    if (!this.notes.length) return this.transcript.note(this.config.sideAgent?.agent ? "no notes yet: the side agent only speaks up when something needs attention" : "no side agent · /side codex adds one");
+    this.notes.forEach((n, i) => this.transcript.note(`${i + 1}. ${fmtTime(n.ts)} ${n.name}: ${n.text.split("\n")[0]!.slice(0, 140)}`));
+    this.transcript.note("/forward <n> sends a note to the main agent");
+  }
+
   private startSpinner(active: Active) {
     this.stopSpinner();
     this.spinnerTimer = setInterval(() => {
@@ -1240,6 +1735,7 @@ export class ChatApp {
   }
 
   private setWorking(text: string | null) {
+    if (this.closed && text) return;
     this.working.visible = !!text;
     this.working.content = text ?? "";
   }
@@ -1255,6 +1751,10 @@ export class ChatApp {
   }
 
   private renderFooter() {
+    this.safely("footer", () => this.drawFooter());
+  }
+
+  private drawFooter() {
     const a = this.active;
     const width = Math.max(20, this.renderer.width - 4);
     let color: string = C.dim;
@@ -1270,6 +1770,10 @@ export class ChatApp {
     else if (this.queue.length) left.push({ text: `${this.queue.length} queued`, prio: 1 });
     else if (!this.shortcuts.visible) left.push({ text: "? for shortcuts", prio: 2 });
     const right: { text: string; prio: number }[] = [];
+    if (this.updateAvailable) left.push({ text: `↑ ${this.updateAvailable} available · /update`, prio: 1 });
+    if (this.config.sideAgent?.agent) left.push({ text: `◆ side ${this.config.sideAgent.agent}${this.config.sideAgent.model ? ` ${shortModelName(this.config.sideAgent.model)}` : ""}${this.reviewer?.busy ? " reviewing…" : ""}`, prio: 2 });
+    // Narrow glyph: the footer is measured in characters, and an emoji takes two columns.
+    if (this.awake.mode !== "off") left.push({ text: `● awake${this.awake.status.lid ? " · lid" : ""}`, prio: 1 });
     const effort = a ? this.effortOption(a)?.current : undefined;
     if (a) right.push({ text: `${a.name}${a.engine.info?.currentModel ? ` · ${shortModelName(a.engine.info.currentModel)}` : ""}${effort ? ` ${effort}` : ""}`, prio: 2 });
     if (a?.context) right.push({ text: `ctx ${Math.min(100, Math.round((a.context.used / a.context.size) * 100))}%`, prio: 1 });
@@ -1345,6 +1849,8 @@ export class ChatApp {
 
   async quit() {
     this.closed = true;
+    await this.awake.release().catch(() => []);
+    await this.closeReviewer();
     this.switching = true;
     const a = this.active;
     this.closePalette();
@@ -1382,6 +1888,7 @@ export async function runChat(config: Config, ledger: Ledger, cwd: string, agent
   const pref = config.theme ?? "auto";
   applyTheme(pref === "auto" ? ((await renderer.waitForThemeMode(250).catch(() => null)) ?? "dark") : pref);
   const app = new ChatApp(renderer, config, ledger, cwd);
+  process.once("exit", () => app.awake.releaseSync());
   try {
     await app.start(agent, fresh, { pick });
   } finally {
@@ -1420,3 +1927,8 @@ async function copyToClipboard(renderer: CliRenderer, text: string): Promise<boo
   }
   return osc;
 }
+
+function reviewCadence(every: number | undefined): string {
+  const n = every ?? 1;
+  return n === 0 ? "only on /review" : n === 1 ? "every turn" : n === 2 ? "every 2nd turn" : n === 3 ? "every 3rd turn" : `every ${n}th turn`;
+}