codemax-cli 0.1.1 → 0.1.3

package/src/chat/logo.ts

@@ -0,0 +1,37 @@
+/**
+ * The codemax wordmark for the terminal: the same halftone grid the website
+ * uses ("codemax" in Inter Tight 800, 13 rows, 0 = empty … 9 = full), drawn
+ * with half blocks so two grid rows fit in one terminal line.
+ */
+const GRID = [
+  "0000000000000000000000000028870000000000000000000000000000000000000000000000",
+  "0000000000000000000000000029970000000000000000000000000000000000000000000000",
+  "0000000000000000000000000029970000000000000000000000000000000000000000000000",
+  "0036876200003687510000477429970004787410057715773027861000267863004773005773",
+  "0699999930069999993006999979970079999981079969999499998104999999501998029970",
+  "3999559980499856998039996599970599635996079996899976999319983399910599369920",
+  "7994006992899300799359960049970899100799079930299800699402210189920189899600",
+  "8992000000999100599569940029971999999999179920199700599401578999920049999100",
+  "8992000000999100599569940029971999777777179920199700599418998689920049999100",
+  "7994006992899300799359960049970999000121079920199700599449950079920199899600",
+  "3998459980599846999139996599970599634998079920199700599459951399920699369930",
+  "0699999930079999993007999979970189999993079920199700599429999989922997029980",
+  "0047886200004788620000577517750015788620057720177500477303787347725772004773",
+] as const;
+
+/** Logo lines for a terminal this wide: the full 76-column logo from 78 columns, none below. */
+export function logoLines(width: number): string[] {
+  // Squeezed to half width the letters run together, so narrow terminals get the text title instead.
+  if (width < 78) return [];
+  const on = (r: number, c: number) => Number(GRID[r]?.[c] ?? "0") >= 4;
+  const lines: string[] = [];
+  for (let r = 0; r < GRID.length; r += 2) {
+    let line = "";
+    for (let c = 0; c < GRID[0]!.length; c++) {
+      const up = on(r, c), down = on(r + 1, c);
+      line += up && down ? "█" : up ? "▀" : down ? "▄" : " ";
+    }
+    lines.push(line.replace(/\s+$/, ""));
+  }
+  return lines;
+}

package/src/chat/transcript.ts

@@ -70,7 +70,7 @@ export class Transcript {
   }
 
   /** Startup card: brand mark, what codemax is, the project, and any notes. */
-  header(lines: { title: string; subtitle: string; path: string; notes: string[] }) {
+  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}`,
@@ -82,15 +82,33 @@ export class Transcript {
       paddingX: 1,
       marginTop: 1,
     });
-    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 }));
+    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 });

package/src/cli.ts

@@ -1,4 +1,8 @@
-import { loadConfig, CONFIG_PATH, hotkeyLabel } from "./config.ts";
+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";
@@ -27,6 +31,8 @@ usage:
   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)
@@ -164,6 +170,45 @@ async function main(argv: string[]) {
       }
       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") {

package/src/config.ts

@@ -28,6 +28,20 @@ export interface Config {
   checkpoints: boolean;
   /** Refresh the public price list weekly for /usage (set false to stay offline). */
   priceUpdates: boolean;
+  /**
+   * Keep the machine awake while codemax runs: "on" prevents sleep, "lid" also keeps
+   * working with the laptop lid closed. See src/core/awake.ts for each platform.
+   */
+  awake: "off" | "on" | "lid";
+  /**
+   * Side agent: another agent that reviews the main agent's work after each turn and
+   * leaves a note when something needs attention. `forward: "auto"` sends notes to the
+   * main agent by itself; "ask" waits for /forward.
+   */
+  /** `every`: review every Nth working turn (1 = each turn, 0 = only on /review). Each review is a request on the side agent's plan. */
+  sideAgent: { agent: AgentId | null; forward: "ask" | "auto"; model?: string; every?: number };
+  /** Check npm for a newer codemax at most every 12 hours and offer /update. */
+  updateCheck: boolean;
   /** Colour theme: "auto" follows the terminal's background, or force "dark" / "light". */
   theme: "auto" | "dark" | "light";
   /**
@@ -49,6 +63,9 @@ export const DEFAULT_CONFIG: Config = {
   summarizeOnSwitch: true,
   bellAfterSeconds: 20,
   theme: "auto",
+  awake: "off",
+  updateCheck: true,
+  sideAgent: { agent: null, forward: "ask" },
   brief: { turns: 10, maxChars: 8000, turnChars: 1200, resumeChars: 24000 },
 };
 
@@ -71,6 +88,7 @@ export function loadConfig(): Config {
       brief: { ...DEFAULT_CONFIG.brief, ...(raw.brief ?? {}) },
       agentArgs: { ...(raw.agentArgs ?? {}) },
       budgets: { ...(raw.budgets ?? {}) },
+      sideAgent: { ...DEFAULT_CONFIG.sideAgent, ...(raw.sideAgent ?? {}) },
       routes: Array.isArray(raw.routes) ? raw.routes : [],
     };
   } catch {

package/src/core/awake.ts

@@ -0,0 +1,345 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CODEMAX_HOME, ensureDir } from "./paths.ts";
+
+/**
+ * Keep the machine awake while codemax runs, so agents keep working.
+ *
+ *   on   no idle/system sleep (and on Linux, no shutdown) while codemax runs
+ *   lid  the same, and keep working with the laptop lid closed
+ *
+ * How, per platform:
+ *   macOS    `caffeinate -ims -w <pid>`; lid: `pmset -a disablesleep 1` (admin
+ *            password once). A root watchdog started with the same password sets
+ *            it and puts it back within seconds of codemax exiting for any reason
+ *            (quit, crash, kill -9, closed terminal). macOS cannot block shutdown.
+ *   Linux    `systemd-inhibit --mode=block` on idle, sleep and shutdown, plus
+ *            handle-lid-switch for lid mode. No admin needed on a desktop session.
+ *   Windows  SetThreadExecutionState(ES_CONTINUOUS|ES_SYSTEM_REQUIRED) from a
+ *            PowerShell helper; lid: lid action set to "do nothing" on the current
+ *            power plan, restored afterwards. Windows cannot block shutdown.
+ *
+ * Safety: every holder process watches codemax's pid and exits with it, so a
+ * crash never leaves the machine unable to sleep. Settings that outlive a
+ * process (pmset, powercfg) are written to a restore record first and put back
+ * on release, on exit, or at the next start if codemax died.
+ */
+export type AwakeMode = "off" | "on" | "lid";
+
+export interface RunResult {
+  code: number;
+  out: string;
+  err: string;
+}
+
+export interface AwakeDeps {
+  platform: NodeJS.Platform;
+  pid: number;
+  /** Run a command to completion. `interactive` lets it use the terminal (a sudo prompt). */
+  run: (cmd: string[], o?: { interactive?: boolean }) => Promise<RunResult>;
+  /** Start a long-running holder process. */
+  spawn: (cmd: string[]) => { kill(): void };
+  which: (bin: string) => string | null;
+  recordPath: string;
+  /** Wraps an interactive command (the chat pauses its screen around it). */
+  interactive?: <T>(fn: () => Promise<T>) => Promise<T>;
+}
+
+interface RestoreRecord {
+  platform: NodeJS.Platform;
+  pid: number;
+  at: number;
+  mac?: { disablesleep: number };
+  win?: { ac: number; dc: number };
+}
+
+export interface AwakeStatus {
+  mode: AwakeMode;
+  /** True when lid-close is actually covered right now. */
+  lid: boolean;
+  notes: string[];
+}
+
+export function defaultAwakeDeps(): AwakeDeps {
+  return {
+    platform: process.platform,
+    pid: process.pid,
+    which: (b) => Bun.which(b),
+    recordPath: join(CODEMAX_HOME, "awake-restore.json"),
+    run: async (cmd, o) => {
+      const p = Bun.spawn(cmd, { stdin: o?.interactive ? "inherit" : "ignore", stdout: o?.interactive ? "inherit" : "pipe", stderr: o?.interactive ? "inherit" : "pipe" });
+      const [out, err] = o?.interactive ? ["", ""] : await Promise.all([new Response(p.stdout as ReadableStream).text(), new Response(p.stderr as ReadableStream).text()]);
+      return { code: await p.exited, out: out.trim(), err: err.trim() };
+    },
+    spawn: (cmd) => {
+      const p = Bun.spawn(cmd, { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+      return { kill: () => p.kill() };
+    },
+  };
+}
+
+const WHY = "A coding agent is working (codemax /awake)";
+// ES_CONTINUOUS | ES_SYSTEM_REQUIRED (0x80000001), written so PowerShell keeps it unsigned:
+// a bare 0x80000001 is read as a negative Int32 and the call fails.
+const ES_CONTINUOUS_SYSTEM_REQUIRED = "[uint32]2147483649";
+
+export class Awake {
+  mode: AwakeMode = "off";
+  private holder: { kill(): void } | null = null;
+  private lidActive = false;
+  /** macOS lid mode: the root watchdog and the flag file that keeps it holding. */
+  private macWatch: { kill(): void } | null = null;
+  private macFlag: string | null = null;
+
+  constructor(private d: AwakeDeps = defaultAwakeDeps()) {}
+
+  get status(): AwakeStatus {
+    return { mode: this.mode, lid: this.lidActive, notes: [] };
+  }
+
+  /** Switch modes. Returns what is in effect and anything the user should know. */
+  async set(mode: AwakeMode): Promise<AwakeStatus> {
+    const notes: string[] = [];
+    if (mode === this.mode) return { mode, lid: this.lidActive, notes };
+    await this.release(notes);
+    if (mode === "off") return { mode: "off", lid: false, notes };
+
+    // 1. The sleep hold, tied to codemax's lifetime.
+    let hold = this.holdCommand(mode === "lid");
+    if (hold && this.d.platform === "linux") hold = await this.linuxHold(mode === "lid", notes);
+    if (hold) this.holder = this.d.spawn(hold);
+    else notes.push(this.d.platform === "linux" ? "systemd-inhibit was not found, so codemax cannot keep this machine awake. Install systemd or use your desktop's 'caffeine' setting." : `keeping awake is not supported on ${this.d.platform}`);
+
+    // 2. Lid-close, where it needs a setting changed.
+    if (mode === "lid") {
+      if (this.d.platform === "darwin") this.lidActive = await this.macLidOn(notes);
+      else if (this.d.platform === "win32") this.lidActive = await this.winLidOn(notes);
+      else this.lidActive = !!hold && hold.some((a) => a.includes("handle-lid-switch")); // Linux: lid-switch inhibitor
+    }
+    if (this.d.platform === "linux" && hold && !hold.some((a) => a.includes("shutdown"))) notes.push("This session is not allowed to block shutdown; only sleep is prevented.");
+    if (this.d.platform !== "linux") notes.push(`${this.d.platform === "darwin" ? "macOS" : "Windows"} does not let apps block a shutdown; only sleep is prevented.`);
+    if (this.lidActive) notes.push("With the lid closed, keep the laptop somewhere it can breathe: not in a bag.");
+    this.mode = hold || this.lidActive ? mode : "off";
+    return { mode: this.mode, lid: this.lidActive, notes };
+  }
+
+  /** Undo everything: stop the holder and put changed settings back. */
+  async release(notes: string[] = []): Promise<string[]> {
+    this.holder?.kill();
+    this.holder = null;
+    if (this.macFlag) {
+      // The watchdog sees the flag gone and turns sleep back on as root.
+      rmSync(this.macFlag, { force: true });
+      this.macFlag = null;
+      const back = await this.waitSleepDisabled(false, 8000);
+      this.macWatch = null;
+      if (back) rmSync(this.d.recordPath, { force: true });
+    }
+    if (this.lidActive) await restoreFromRecord(this.d, notes, { interactive: true });
+    this.lidActive = false;
+    this.mode = "off";
+    return notes;
+  }
+
+  /** Best effort, synchronous: for process exit, where nothing can be awaited. */
+  releaseSync() {
+    this.holder?.kill();
+    // macOS: removing the flag is enough; the root watchdog restores sleep on its own.
+    if (this.macFlag) {
+      rmSync(this.macFlag, { force: true });
+      return;
+    }
+    if (!this.lidActive) return;
+    const rec = readRecord(this.d.recordPath);
+    if (!rec) return;
+    const cmds = restoreCommands(rec, { nonInteractive: true });
+    let ok = true;
+    for (const c of cmds) ok = Bun.spawnSync(c, { stdout: "ignore", stderr: "ignore" }).exitCode === 0 && ok;
+    if (ok) rmSync(this.d.recordPath, { force: true });
+  }
+
+  /**
+   * Linux: the system's policy decides which locks a session may take (a remote or
+   * headless session often may not block shutdown or the lid switch). Probe with an
+   * instant command, keep the widest set that is allowed, and say what was refused.
+   */
+  private async linuxHold(lid: boolean, notes: string[]): Promise<string[] | null> {
+    const sets = lid ? [["idle", "sleep", "shutdown", "handle-lid-switch"], ["idle", "sleep", "handle-lid-switch"], ["idle", "sleep"]] : [["idle", "sleep", "shutdown"], ["idle", "sleep"]];
+    let lastErr = "";
+    for (const set of sets) {
+      const r = await this.d.run(["systemd-inhibit", `--what=${set.join(":")}`, "--who=codemax", `--why=${WHY}`, "--mode=block", "true"]);
+      if (r.code === 0) {
+        if (lid && !set.includes("handle-lid-switch")) notes.push("This session is not allowed to hold the lid switch, so closing the lid may still suspend.");
+        return this.linuxCommand(set);
+      }
+      lastErr = r.err || r.out;
+    }
+    notes.push(`The system refused to let codemax keep it awake${lastErr ? ` (${lastErr.split("\n")[0]!.slice(0, 160)})` : ""}. This usually means a remote or non-desktop session.`);
+    return null;
+  }
+
+  private linuxCommand(what: string[]): string[] {
+    return ["systemd-inhibit", `--what=${what.join(":")}`, "--who=codemax", `--why=${WHY}`, "--mode=block", "sh", "-c", `while kill -0 ${this.d.pid} 2>/dev/null; do sleep 5; done`];
+  }
+
+  holdCommand(lid: boolean): string[] | null {
+    const pid = String(this.d.pid);
+    switch (this.d.platform) {
+      case "darwin":
+        // -i idle sleep, -m disk sleep, -s system sleep (on AC). The display may still sleep.
+        return this.d.which("caffeinate") ? ["caffeinate", "-ims", "-w", pid] : null;
+      case "linux": {
+        if (!this.d.which("systemd-inhibit")) return null;
+        return this.linuxCommand(["idle", "sleep", "shutdown", ...(lid ? ["handle-lid-switch"] : [])]);
+      }
+      case "win32":
+        return [
+          "powershell",
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `$k = Add-Type -MemberDefinition '[DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint f);' -Name K -Namespace CodemaxAwake -PassThru; ` +
+            `[void]$k::SetThreadExecutionState(${ES_CONTINUOUS_SYSTEM_REQUIRED}); ` +
+            `while (Get-Process -Id ${pid} -ErrorAction SilentlyContinue) { Start-Sleep -Seconds 5 }`,
+        ];
+      default:
+        return null;
+    }
+  }
+
+  private async macLidOn(notes: string[]): Promise<boolean> {
+    const cur = await this.d.run(["pmset", "-g"]);
+    const disabled = /SleepDisabled\s+1/.test(cur.out);
+    if (disabled && !readRecord(this.d.recordPath)) {
+      notes.push("Sleep is already disabled on this Mac (pmset disablesleep 1), so the lid can close; codemax will leave that setting as it found it.");
+      return true;
+    }
+    writeRecord(this.d.recordPath, { platform: "darwin", pid: this.d.pid, at: Date.now(), mac: { disablesleep: 0 } });
+    let auth = await this.d.run(["sudo", "-n", "-v"]);
+    if (auth.code !== 0 && this.d.interactive) {
+      notes.push("macOS needs your admin password to keep running with the lid closed.");
+      auth = await this.d.interactive(() => this.d.run(["sudo", "-v"], { interactive: true }));
+    }
+    if (auth.code !== 0) {
+      rmSync(this.d.recordPath, { force: true });
+      notes.push("Lid-close needs admin rights on macOS and was not enabled; the Mac still will not idle-sleep. Run `codemax awake lid` in a terminal to enter your password.");
+      return false;
+    }
+    // A root watchdog sets disablesleep and restores it the moment codemax is gone (or the flag
+    // is removed). It ignores INT/HUP/TERM so closing the terminal cannot kill it before it restores.
+    const flag = join(dirname(this.d.recordPath), `awake-${this.d.pid}.flag`);
+    writeFileSync(flag, "");
+    this.macFlag = flag;
+    this.macWatch = this.d.spawn(["sudo", "-n", "sh", "-c", macWatchdog(this.d.pid, flag, 0)]);
+    if (await this.waitSleepDisabled(true, 5000)) return true;
+    rmSync(flag, { force: true });
+    this.macFlag = null;
+    this.macWatch.kill();
+    this.macWatch = null;
+    await restoreFromRecord(this.d, notes, {});
+    notes.push("Could not switch off sleep (pmset), so lid-close was not enabled.");
+    return false;
+  }
+
+  /** Poll `pmset -g` until SleepDisabled matches. */
+  private async waitSleepDisabled(want: boolean, ms: number): Promise<boolean> {
+    for (let t = 0; t <= ms; t += 250) {
+      const cur = await this.d.run(["pmset", "-g"]);
+      if (/SleepDisabled\s+1/.test(cur.out) === want) return true;
+      await Bun.sleep(250);
+    }
+    return false;
+  }
+
+  private async winLidOn(notes: string[]): Promise<boolean> {
+    const q = await this.d.run(["powercfg", "/q", "SCHEME_CURRENT", "SUB_BUTTONS", "LIDACTION"]);
+    const ac = parsePowercfg(q.out, "AC"), dc = parsePowercfg(q.out, "DC");
+    if (ac === undefined || dc === undefined) {
+      notes.push("This PC reports no lid setting (a desktop or server has none), so only sleep is prevented.");
+      return false;
+    }
+    writeRecord(this.d.recordPath, { platform: "win32", pid: this.d.pid, at: Date.now(), win: { ac, dc } });
+    const cmds = [
+      ["powercfg", "/setacvalueindex", "SCHEME_CURRENT", "SUB_BUTTONS", "LIDACTION", "0"],
+      ["powercfg", "/setdcvalueindex", "SCHEME_CURRENT", "SUB_BUTTONS", "LIDACTION", "0"],
+      ["powercfg", "/setactive", "SCHEME_CURRENT"],
+    ];
+    for (const c of cmds) {
+      if ((await this.d.run(c)).code !== 0) {
+        await restoreFromRecord(this.d, notes, {});
+        notes.push("Could not change the lid setting (powercfg), so lid-close was not enabled.");
+        return false;
+      }
+    }
+    return true;
+  }
+}
+
+/** The root watchdog script: hold disablesleep while codemax lives and the flag exists, then restore. */
+export function macWatchdog(pid: number, flag: string, restoreTo: number): string {
+  const f = flag.replace(/'/g, `'\\''`);
+  return `trap '' INT HUP TERM; pmset -a disablesleep 1; while kill -0 ${pid} 2>/dev/null && [ -e '${f}' ]; do sleep 2; done; pmset -a disablesleep ${restoreTo}`;
+}
+
+/** At startup: if a previous codemax died with a lid setting changed, put it back. */
+export async function recoverAwake(d: AwakeDeps = defaultAwakeDeps()): Promise<string[]> {
+  const rec = readRecord(d.recordPath);
+  if (!rec || rec.platform !== d.platform) return [];
+  if (rec.pid !== d.pid && pidAlive(rec.pid)) return []; // another codemax still holds it
+  const notes: string[] = [];
+  await restoreFromRecord(d, notes, { interactive: !!d.interactive });
+  if (!readRecord(d.recordPath)) notes.unshift("Restored the lid/sleep setting a previous codemax session changed.");
+  return notes;
+}
+
+async function restoreFromRecord(d: AwakeDeps, notes: string[], o: { interactive?: boolean }) {
+  const rec = readRecord(d.recordPath);
+  if (!rec) return;
+  let ok = true;
+  for (const c of restoreCommands(rec, { nonInteractive: true })) ok = (await d.run(c)).code === 0 && ok;
+  if (!ok && rec.mac && o.interactive && d.interactive) {
+    const r = await d.interactive(() => d.run(["sudo", "pmset", "-a", "disablesleep", String(rec.mac!.disablesleep)], { interactive: true }));
+    ok = r.code === 0;
+  }
+  if (ok) rmSync(d.recordPath, { force: true });
+  else notes.push(rec.mac ? "Could not turn sleep back on. Run: sudo pmset -a disablesleep 0" : "Could not restore the lid setting. Run `codemax awake off` to retry.");
+}
+
+function restoreCommands(rec: RestoreRecord, o: { nonInteractive: boolean }): string[][] {
+  if (rec.mac) return [["sudo", ...(o.nonInteractive ? ["-n"] : []), "pmset", "-a", "disablesleep", String(rec.mac.disablesleep)]];
+  if (rec.win)
+    return [
+      ["powercfg", "/setacvalueindex", "SCHEME_CURRENT", "SUB_BUTTONS", "LIDACTION", String(rec.win.ac)],
+      ["powercfg", "/setdcvalueindex", "SCHEME_CURRENT", "SUB_BUTTONS", "LIDACTION", String(rec.win.dc)],
+      ["powercfg", "/setactive", "SCHEME_CURRENT"],
+    ];
+  return [];
+}
+
+/** "Current AC Power Setting Index: 0x00000001" → 1 */
+export function parsePowercfg(out: string, which: "AC" | "DC"): number | undefined {
+  const m = out.match(new RegExp(`Current ${which} Power Setting Index:\\s*0x([0-9a-f]+)`, "i"));
+  return m ? parseInt(m[1]!, 16) : undefined;
+}
+
+function readRecord(path: string): RestoreRecord | null {
+  try {
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as RestoreRecord) : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeRecord(path: string, rec: RestoreRecord) {
+  ensureDir(join(path, ".."));
+  writeFileSync(path, JSON.stringify(rec, null, 2) + "\n");
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/core/brief.ts

@@ -182,7 +182,7 @@ function whereItStopped(steps: Step[], end: StepOf<"end"> | undefined): string[]
   return out;
 }
 
-function formatStep(s: Step): string | null {
+export function formatStep(s: Step): string | null {
   switch (s.kind) {
     case "user":
       return `- USER: ${oneLine(s.text, 600)}`;

package/src/core/journal.ts

@@ -79,7 +79,8 @@ export class Journal {
    * follow-ups. Earlier steps are history.
    */
   task(steps = this.steps()): { request?: StepOf<"user">; followUps: StepOf<"user">[]; steps: Step[]; earlier: Step[] } {
-    const users = steps.filter((s): s is StepOf<"user"> => s.kind === "user");
+    // A forwarded side-agent note continues the current task; it never starts one.
+    const users = steps.filter((s): s is StepOf<"user"> => s.kind === "user" && !s.text.startsWith("A side agent ("));
     if (!users.length) return { followUps: [], steps: [], earlier: steps };
     // A task begins at a user message that follows a turn which ended "done";
     // messages sent while the work was cut short continue the same task.
@@ -91,7 +92,8 @@ export class Journal {
     }
     const task = steps.slice(startIdx);
     const taskUsers = task.filter((s): s is StepOf<"user"> => s.kind === "user");
-    return { request: taskUsers[0], followUps: taskUsers.slice(1), steps: task, earlier: steps.slice(0, startIdx) };
+    const request = taskUsers.find((s) => !s.text.startsWith("A side agent ("));
+    return { request, followUps: taskUsers.filter((s) => s !== request), steps: task, earlier: steps.slice(0, startIdx) };
   }
 
   /** When this agent last did any work (not counting being briefed). */

package/src/core/review.ts

@@ -0,0 +1,67 @@
+import type { AgentId } from "../adapters/types.ts";
+import type { Step, StepOf } from "./journal.ts";
+import { formatStep } from "./brief.ts";
+
+/**
+ * The side agent: a second agent (any harness) that reviews the main agent's
+ * work after each turn and speaks up only when something deserves the user's
+ * attention: drift from the request or plan, claims without evidence, risky
+ * assumptions, missing tests. Its notes can be forwarded to the main agent so
+ * it stays aligned with the plan, whichever harness it runs on.
+ */
+export const NO_NOTE = "NO_NOTE";
+
+export function reviewInstructions(mainAgent: string): string {
+  return [
+    `You are a side agent reviewing the work of another coding agent (${mainAgent}) for the user. You do not do the work yourself.`,
+    "Do not use any tools and do not change any files. Read only what is below.",
+    "Check the latest work against the user's request and the plan. Look for: drift from what the user asked; conclusions or claims the steps do not actually support; decisions resting on thin evidence (one run, one sample, a check that barely passed); risky assumptions; tests or edge cases that were skipped; work that will be wasted if an untested assumption is wrong.",
+    `If nothing is worth interrupting the user for, reply with exactly ${NO_NOTE} and nothing else. Most turns deserve ${NO_NOTE}; do not nitpick style.`,
+    "Otherwise reply with one note in exactly this shape, under 130 words, plain language, concrete facts from the work:",
+    "",
+    "Heads up · <one sentence: what could go wrong>",
+    "",
+    "**<short title>**",
+    "- <fact from the work>",
+    "- <why it matters for the user's goal>",
+    "- **Consider <one concrete, cheap action>.**",
+  ].join("\n");
+}
+
+/** What the reviewer sees: the request, the plan, and the main agent's steps since its last review. */
+export function buildReviewPrompt(o: { steps: Step[]; since: number; mainAgent: string; reviewer: AgentId; context?: string }): string | null {
+  // The reviewer's own turns are never journaled, so every step here is the main agent's,
+  // even when both run on the same harness (Claude reviewing Claude).
+  const recent = o.steps.filter((s) => s.ts > o.since && s.kind !== "handoff" && s.kind !== "thought");
+  const work = recent.filter((s) => s.kind === "tool" || s.kind === "text" || s.kind === "plan");
+  if (!work.length) return null;
+  const users = o.steps.filter((s): s is StepOf<"user"> => s.kind === "user");
+  const request = users.at(-1);
+  const plan = [...o.steps].reverse().find((s): s is StepOf<"plan"> => s.kind === "plan");
+  const out: string[] = [reviewInstructions(o.mainAgent), ""];
+  if (o.context) out.push("## Context (the task so far, recorded by codemax)", o.context, "");
+  if (request) out.push("## The user's latest request", request.text.trim().split("\n").map((l) => `> ${l}`).join("\n"), "");
+  if (plan) out.push("## Plan", ...plan.entries.map((e) => `${e.status === "completed" ? "[x]" : e.status === "in_progress" ? "[~]" : "[ ]"} ${e.content}`), "");
+  out.push("## Latest work to review (oldest first)", ...recent.map((s) => formatStep(s)).filter((l): l is string => !!l));
+  return out.join("\n");
+}
+
+/** The note, or null when the reviewer had nothing to say. */
+export function parseNote(reply: string): string | null {
+  const t = reply.trim();
+  if (!t || t.includes(NO_NOTE) || t.length < 40) return null;
+  const at = t.indexOf("Heads up");
+  return (at > 0 ? t.slice(at) : t).trim();
+}
+
+/** Forwarded notes start with this; they are follow-ups, never a new task, and never reviewed. */
+export const NOTE_PREFIX = "A side agent (";
+
+export function isForwardedNote(text: string): boolean {
+  return text.startsWith(NOTE_PREFIX);
+}
+
+/** The message that hands a note to the main agent. */
+export function forwardMessage(note: string, reviewerName: string): string {
+  return `${NOTE_PREFIX}${reviewerName}) reviewing your work left this note. Weigh it against the user's request and plan: say in a sentence whether you agree, and adjust your work if it is right.\n\n${note}`;
+}