codemax-cli 0.1.1 → 0.1.4

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

@@ -4,6 +4,7 @@ import { diffStat, headLine, recentCommits } from "./git.ts";
 import { checkpointDiff } from "./checkpoint.ts";
 import { BRIEF_MARKER, type Ledger } from "./ledger.ts";
 import type { Step, StepOf } from "./journal.ts";
+import { fmtTime12 } from "./time.ts";
 
 export interface BriefInput {
   ledger: Ledger;
@@ -161,7 +162,7 @@ export async function buildCatchup(input: BriefInput): Promise<string | null> {
 function whereItStopped(steps: Step[], end: StepOf<"end"> | undefined): string[] {
   const out: string[] = [];
   if (!end) return ["The last agent had not finished its first turn."];
-  const when = new Date(end.ts).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
+  const when = fmtTime12(end.ts);
   const why =
     end.outcome === "limit" ? `ran out of its usage limit${end.detail ? ` ("${oneLine(end.detail, 140)}")` : ""}`
     : end.outcome === "cancelled" ? "was interrupted by the user"
@@ -182,7 +183,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/quota.ts

@@ -1,5 +1,6 @@
 import type { AgentId, QuotaStatus } from "../adapters/types.ts";
 import { stripAnsi } from "./terminal.ts";
+import { fmtTime12 } from "./time.ts";
 
 /**
  * Vendor-neutral phrases. Deliberately narrow: "rate limit" or "429" alone
@@ -47,7 +48,7 @@ export class OutputScanner {
 export function quotaLabel(q?: QuotaStatus): string {
   if (!q) return "";
   if (isExhausted(q)) {
-    const reset = q.resetsAt ? ` until ${new Date(q.resetsAt).toLocaleTimeString()}` : "";
+    const reset = q.resetsAt ? ` until ${fmtTime12(q.resetsAt)}` : "";
     return q.source === "output" ? `exhausted? (text match)${reset}` : `EXHAUSTED${reset}`;
   }
   if (typeof q.usedPercent === "number") return `${Math.round(q.usedPercent)}% used`;

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}`;
+}

package/src/core/time.ts

@@ -0,0 +1,9 @@
+/** Every time codemax shows is 12-hour, whatever the system locale: "7:25 PM", "Oct 18, 7:25 PM". */
+export function fmtTime12(ts: number): string {
+  return new Date(ts).toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit", hour12: true });
+}
+
+export function fmtDateTime12(ts: number): string {
+  const d = new Date(ts);
+  return `${d.toLocaleDateString("en-US", { month: "short", day: "numeric" })}, ${fmtTime12(ts)}`;
+}

package/src/core/update.ts

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { CODEMAX_HOME, ensureDir } from "./paths.ts";
+
+/**
+ * Update checks and self-update. At most every 12 hours (3 s timeout, never
+ * blocking startup) codemax asks for the newest version from the place its own
+ * update comes from: npm for npm installs, GitHub releases for the installer,
+ * source checkouts and standalone builds. So a release is only offered where
+ * `/update` can actually fetch it. `/update` / `codemax update` then updates
+ * the way codemax was installed.
+ */
+const REGISTRY = "https://registry.npmjs.org/codemax-cli/latest";
+const RELEASES = "https://api.github.com/repos/SkidGod4444/codemax-cli/releases/latest";
+const CHECK_EVERY_MS = 12 * 60 * 60 * 1000;
+const CACHE = () => join(CODEMAX_HOME, "update-check.json");
+
+export type InstallKind = "npm" | "script" | "source" | "binary";
+
+/** How this codemax was installed, judged from where its code lives. */
+export function installKind(root = resolve(import.meta.dir, "..", "..")): { kind: InstallKind; root: string } {
+  if (root.includes("$bunfs") || root.startsWith("/$bunfs") || root.startsWith("B:\\~BUN")) return { kind: "binary", root };
+  if (root.includes(`${sep}node_modules${sep}codemax-cli`) || root.includes("/node_modules/codemax-cli")) return { kind: "npm", root };
+  if (existsSync(join(root, ".git")) && /[\\/]\.codemax[\\/]cli$/.test(root)) return { kind: "script", root };
+  if (existsSync(join(root, ".git"))) return { kind: "source", root };
+  return { kind: "npm", root };
+}
+
+/** a > b for x.y.z versions (pre-release suffixes ignored). */
+export function isNewer(a: string, b: string): boolean {
+  const p = (v: string) => v.replace(/^v/, "").split("-")[0]!.split(".").map((n) => Number(n) || 0);
+  const [x, y] = [p(a), p(b)];
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0);
+  return false;
+}
+
+export async function latestVersion(source: "npm" | "github" = "npm", fetchImpl: typeof fetch = fetch, timeoutMs = 3000): Promise<string | null> {
+  try {
+    const res = await fetchImpl(source === "npm" ? REGISTRY : RELEASES, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: source === "npm" ? "application/json" : "application/vnd.github+json" } });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { version?: unknown; tag_name?: unknown };
+    const v = String((source === "npm" ? body.version : body.tag_name) ?? "").replace(/^v/, "");
+    return /^\d+\.\d+\.\d+/.test(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Where this install's updates come from. */
+export function updateSource(kind: InstallKind = installKind().kind): "npm" | "github" {
+  return kind === "npm" ? "npm" : "github";
+}
+
+/** The latest version when it is newer than `current`; null otherwise. Cached for 12 hours. */
+export async function checkForUpdate(current: string, o: { force?: boolean; fetchImpl?: typeof fetch; source?: "npm" | "github" } = {}): Promise<string | null> {
+  const source = o.source ?? updateSource();
+  let cached: { at: number; latest: string | null; source?: string } | null = null;
+  try {
+    cached = existsSync(CACHE()) ? JSON.parse(readFileSync(CACHE(), "utf8")) : null;
+  } catch {
+    cached = null;
+  }
+  let latest = cached?.latest ?? null;
+  if (o.force || !cached || cached.source !== source || Date.now() - cached.at > CHECK_EVERY_MS) {
+    latest = await latestVersion(source, o.fetchImpl);
+    try {
+      ensureDir(CODEMAX_HOME);
+      writeFileSync(CACHE(), JSON.stringify({ at: Date.now(), latest, source }) + "\n");
+    } catch {
+      /* read-only home: check again next time */
+    }
+  }
+  return latest && isNewer(latest, current) ? latest : null;
+}
+
+/** The command that updates this install, or null with an explanation when it cannot update itself. */
+export function updatePlan(install = installKind(), platform = process.platform): { cmd: string[][]; env?: Record<string, string>; manual?: string; label: string } {
+  switch (install.kind) {
+    case "npm":
+      return { cmd: [["npm", "install", "-g", "codemax-cli@latest"]], label: "npm install -g codemax-cli@latest" };
+    case "script":
+      return platform === "win32"
+        ? { cmd: [["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", join(install.root, "install.ps1")]], env: { CODEMAX_DIR: install.root }, label: "the codemax installer (newest release)" }
+        : { cmd: [["bash", join(install.root, "install.sh")]], env: { CODEMAX_DIR: install.root }, label: "the codemax installer (newest release)" };
+    case "source":
+      return { cmd: [["git", "-C", install.root, "pull", "--ff-only"], ["bun", "install", "--cwd", install.root]], label: `git pull in ${install.root}` };
+    case "binary":
+      return { cmd: [], manual: "This is a standalone build; download the new release from https://github.com/SkidGod4444/codemax-cli/releases or switch to `npm install -g codemax-cli`.", label: "manual download" };
+  }
+}

package/src/engines/acp.ts

@@ -1,6 +1,6 @@
 import { ClientSideConnection, ndJsonStream, type Client, type Stream } from "@agentclientprotocol/sdk";
 import type { AgentId } from "../adapters/types.ts";
-import type { Engine, EngineEvent, EngineInfo, EngineOption, EngineSessionRef, EngineStartOptions, PermissionRequest, StopReason } from "./types.ts";
+import type { Engine, EngineEvent, EngineInfo, EngineOption, EngineSessionRef, EngineStartOptions, PermissionRequest, PlanLimit, StopReason } from "./types.ts";
 import { agentEnv } from "./env.ts";
 import { platformArgv } from "../core/spawn.ts";
 import { classifyError } from "./errors.ts";
@@ -204,7 +204,7 @@ export class AcpEngine implements Engine {
         // `used` is how full the context window is, not tokens spent: it feeds the context meter.
         // Token counts come from the prompt response (or session files) at turn end.
         if (typeof u.used === "number") this.turnContext = u.used;
-        this.emit({ type: "usage", contextUsed: u.used, contextSize: u.size, costUsd: delta, model: this.currentModelName() });
+        this.emit({ type: "usage", contextUsed: u.used, contextSize: u.size, costUsd: delta, model: this.currentModelName(), planLimits: planLimitsOf(u) });
         break;
       }
       default:
@@ -339,6 +339,15 @@ function extraOptions(config: unknown): EngineOption[] {
     }));
 }
 
+/** Claude's plan limits ride on usage updates as `_meta["_claude/rateLimit"]` (SDKRateLimitInfo). */
+function planLimitsOf(u: any): PlanLimit[] | undefined {
+  const rl = u?._meta?.["_claude/rateLimit"];
+  if (!rl || typeof rl !== "object") return undefined;
+  const util = typeof rl.utilization === "number" ? (rl.utilization <= 1 ? rl.utilization * 100 : rl.utilization) : undefined;
+  const reset = typeof rl.resetsAt === "number" ? (rl.resetsAt < 1e12 ? rl.resetsAt * 1000 : rl.resetsAt) : undefined;
+  return [{ window: String(rl.rateLimitType ?? "plan"), usedPercent: util, resetsAt: reset, status: rl.status }];
+}
+
 function mapStatus(s: string | undefined): "pending" | "in_progress" | "completed" | "failed" {
   if (s === "in_progress" || s === "completed" || s === "failed") return s;
   return "pending";