aoaoe 0.109.0 → 0.114.0

package/README.md

@@ -4,7 +4,7 @@
     <a href="https://github.com/Talador12/agent-of-agent-of-empires/actions/workflows/ci.yml"><img src="https://github.com/Talador12/agent-of-agent-of-empires/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
     <a href="https://www.npmjs.com/package/aoaoe"><img src="https://img.shields.io/npm/v/aoaoe" alt="npm version"></a>
     <a href="https://github.com/Talador12/agent-of-agent-of-empires/releases"><img src="https://img.shields.io/github/v/release/Talador12/agent-of-agent-of-empires" alt="GitHub release"></a>
-    <img src="https://img.shields.io/badge/tests-1509-brightgreen" alt="tests">
+    <img src="https://img.shields.io/badge/tests-1739-brightgreen" alt="tests">
     <img src="https://img.shields.io/badge/node-%3E%3D20-blue" alt="Node.js >= 20">
     <img src="https://img.shields.io/badge/runtime%20deps-0-brightgreen" alt="zero runtime dependencies">
     <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
@@ -256,11 +256,18 @@ The daemon runs an interactive TUI with a rich command set. These commands are a
 | `/mute [N\|name]` | Mute/unmute a session's activity entries |
 | `/unmute-all` | Unmute all sessions at once |
 | `/filter [tag]` | Filter activity by tag -- presets: `errors`, `actions`, `system` (no arg = clear) |
-| `/who` | Show fleet status (all sessions at a glance) |
+| `/who` | Show fleet status: status, uptime, idle-since, context, errors, group, note |
 | `/uptime` | Show session uptimes |
+| `/top [mode]` | Rank sessions by `errors` (default), `burn`, or `idle` |
 | `/auto-pin` | Toggle auto-pin on error |
 | `/note N\|name text` | Attach a note to a session (no text = clear) |
 | `/notes` | List all session notes |
+| `/group N\|name tag` | Assign session to a group (lowercase, max 16 chars; no tag = clear) |
+| `/groups` | List all groups and their members |
+| `/group-filter [tag]` | Show only sessions in a group (no arg = clear) |
+| `/rename N\|name [display]` | Set custom TUI display name (no display = clear); persisted |
+| `/watchdog [N]` | Alert if session stalls N minutes (default 10); `/watchdog off` to disable |
+| `/broadcast <msg>` | Send message to all sessions; `/broadcast group:<tag> <msg>` for group |
 | `/clip [N]` | Copy last N activity entries to clipboard (default 20) |
 | `/diff N` | Show activity since bookmark N |
 | `/mark` | Bookmark current activity position |
@@ -276,7 +283,7 @@ The daemon runs an interactive TUI with a rich command set. These commands are a
 
 | Command | What it does |
 |---------|-------------|
-| `/status` | Show daemon state |
+| `/status` | Show daemon state (mode, reasoner, poll counts, last cycle) |
 | `/dashboard` | Show full dashboard |
 | `/tasks` | Show task progress table |
 | `/t ...` `/todo ...` `/idea ...` | Aliases for `/task ...` |
@@ -284,6 +291,10 @@ The daemon runs an interactive TUI with a rich command set. These commands are a
 | `/task <session> :: <goal>` | Fast path: update/create task for an existing session and set its goal |
 | `:<goal>` | Fastest path in drill-down: set goal for that session |
 | `just type` (in drill-down) | Default behavior: update goal for the focused session |
+| `/burn-rate` | Show context token burn rates (tokens/min) for all sessions |
+| `/ceiling` | Show context token usage vs limit for all sessions |
+| `/snapshot [md]` | Export session state snapshot to `~/.aoaoe/snapshot-<ts>.json` (or `.md`) |
+| `/alias /x /cmd` | Create command alias (`/x` expands to `/cmd`); no args = list |
 
 ### Other
 
@@ -296,9 +307,21 @@ The daemon runs an interactive TUI with a rich command set. These commands are a
 ### TUI Features
 
 - **Activity sparkline** -- 10-minute activity rate chart in the separator bar (Unicode blocks with color gradient)
-- **Session cards** -- per-session status with pin `▲`, mute `◌`, note `✎` indicators
-- **Sticky preferences** -- sort mode, compact, focus, bell, auto-pin, and tag filter persist across restarts (`~/.aoaoe/tui-prefs.json`)
+- **Session cards** -- per-session status with pin `▲`, mute `◌`, note `✎`, group `⊹tag`, and health score `⬡N` indicators
+- **Health score** -- composite 0–100 badge per session (errors, burn rate, context ceiling, stall time); LIME ≥80, AMBER ≥60, ROSE <60
+- **Error sparklines** -- ROSE 5-bucket mini-chart of recent error frequency in each card (last 5 min)
+- **Idle-since** -- time since last output change shown in idle/done card status and `/who` output
+- **Session grouping** -- `/group` assigns sessions to named groups; `/group-filter` narrows the panel view
+- **Session rename** -- `/rename` sets a custom TUI display name (bold with original dim alongside); persisted
+- **Watchdog** -- `/watchdog N` fires an alert if a session stalls for N minutes (rate-limited to once per 5 min)
+- **Burn-rate alerts** -- automatic "status" alert when context token usage exceeds 5k tokens/min; `/burn-rate` for on-demand view
+- **Context ceiling warning** -- automatic alert at 90% context usage when "X / Y tokens" format available; `/ceiling` for on-demand view
+- **Snapshot export** -- `/snapshot [md]` exports full session state (status, group, note, uptime, context, errors, burn rate) to `~/.aoaoe/`
+- **Broadcast** -- `/broadcast [group:<tag>] <message>` sends a message to all (or group-filtered) sessions via tmux
+- **Ranked view** -- `/top [errors|burn|idle]` ranks sessions by composite attention score or a single metric
+- **Sticky preferences** -- sort, compact, focus, bell, auto-pin, tag filter, aliases, groups, and renames persist across restarts
 - **Filter pipeline** -- mute, tag filter, and search compose: mute → tag → search
+- **Aliases** -- `/alias /x /cmd` creates command shortcuts; up to 50, persisted
 - **Activity heatmap** -- 24-hour colored block chart via `aoaoe stats`
 - **Bookmarks** -- mark positions in the activity stream, jump back to them, diff since a bookmark
 - **Clipboard export** -- `/clip` copies activity to system clipboard (macOS) or `~/.aoaoe/clip.txt`

package/dist/index.js

@@ -16,7 +16,7 @@ import { wakeableSleep } from "./wake.js";
 import { classifyMessages, formatUserMessages, buildReceipts, shouldSkipSleep, hasPendingFile, isInsistMessage, stripInsistPrefix } from "./message.js";
 import { TaskManager, loadTaskDefinitions, loadTaskState, formatTaskTable, importAoeSessionsToTasks } from "./task-manager.js";
 import { runTaskCli, handleTaskSlashCommand, quickTaskUpdate } from "./task-cli.js";
-import { TUI, hitTestSession, nextSortMode, SORT_MODES, formatUptime, formatClipText, loadTuiPrefs, saveTuiPrefs, validateGroupName, CONTEXT_BURN_THRESHOLD, buildSnapshotData, formatSnapshotJson, formatSnapshotMarkdown, formatBroadcastSummary } from "./tui.js";
+import { TUI, hitTestSession, nextSortMode, SORT_MODES, formatUptime, formatClipText, loadTuiPrefs, saveTuiPrefs, validateGroupName, CONTEXT_BURN_THRESHOLD, buildSnapshotData, formatSnapshotJson, formatSnapshotMarkdown, formatBroadcastSummary, rankSessions, TOP_SORT_MODES, formatIdleSince, CONTEXT_CEILING_THRESHOLD } from "./tui.js";
 import { isDaemonRunningFromState } from "./chat.js";
 import { sendNotification, sendTestNotification } from "./notify.js";
 import { startHealthServer } from "./health.js";
@@ -188,14 +188,19 @@ async function main() {
             tui.setTagFilter(prefs.tagFilter);
         if (prefs.sessionGroups)
             tui.restoreGroups(prefs.sessionGroups);
+        if (prefs.sessionAliases)
+            tui.restoreSessionAliases(prefs.sessionAliases);
     }
     const persistPrefs = () => {
         if (!tui)
             return;
-        // persist session groups (ID → group tag)
+        // persist session groups (ID → group tag) and session aliases (ID → display name)
         const groupsObj = {};
         for (const [id, g] of tui.getAllGroups())
             groupsObj[id] = g;
+        const aliasesObj = {};
+        for (const [id, name] of tui.getAllSessionAliases())
+            aliasesObj[id] = name;
         saveTuiPrefs({
             sortMode: tui.getSortMode(),
             compact: tui.isCompact(),
@@ -205,6 +210,7 @@ async function main() {
             tagFilter: tui.getTagFilter(),
             aliases: input.getAliases(),
             sessionGroups: groupsObj,
+            sessionAliases: aliasesObj,
         });
     };
     if (!useTui) {
@@ -751,6 +757,68 @@ async function main() {
             if (!any)
                 tui.log("system", `  threshold: ${CONTEXT_BURN_THRESHOLD.toLocaleString()} tokens/min`);
         });
+        // wire /rename custom display name
+        input.onRename((target, displayName) => {
+            const num = /^\d+$/.test(target) ? parseInt(target, 10) : undefined;
+            const ok = tui.renameSession(num ?? target, displayName || null);
+            if (ok) {
+                if (displayName) {
+                    tui.log("system", `renamed ${target} → "${displayName}"`);
+                }
+                else {
+                    tui.log("system", `rename cleared for ${target}`);
+                }
+                persistPrefs();
+            }
+            else {
+                tui.log("system", `session not found: ${target}`);
+            }
+        });
+        // wire /ceiling context usage view
+        input.onCeiling(() => {
+            const sessions = tui.getSessions();
+            if (sessions.length === 0) {
+                tui.log("system", "no sessions — context data not available");
+                return;
+            }
+            const ceilings = tui.getAllContextCeilings();
+            let any = false;
+            for (const s of sessions) {
+                const c = ceilings.get(s.id);
+                if (!c) {
+                    tui.log("system", `  ${s.title}: no ceiling data (${s.contextTokens ?? "no tokens"})`);
+                }
+                else {
+                    const pct = Math.round((c.current / c.max) * 100);
+                    const warn = pct >= CONTEXT_CEILING_THRESHOLD * 100 ? " ⚠" : "";
+                    tui.log("system", `  ${s.title}: ${pct}% — ${c.current.toLocaleString()} / ${c.max.toLocaleString()} tokens${warn}`);
+                    any = true;
+                }
+            }
+            if (!any)
+                tui.log("system", `  tip: context ceiling requires "X / Y tokens" format in session output`);
+        });
+        // wire /top ranked session view
+        input.onTop((modeArg) => {
+            const mode = TOP_SORT_MODES.includes(modeArg)
+                ? modeArg : "default";
+            const sessions = tui.getSessions();
+            if (sessions.length === 0) {
+                tui.log("system", "no sessions");
+                return;
+            }
+            const now = Date.now();
+            const entries = rankSessions(sessions, tui.getSessionErrorCounts(), tui.getAllBurnRates(now), tui.getAllLastChangeAt(), mode, now);
+            const modeLabel = mode === "default" ? "composite" : mode;
+            tui.log("system", `/top (${modeLabel}) — ${entries.length} sessions:`);
+            for (const e of entries) {
+                const errStr = e.errors > 0 ? ` ${e.errors}err` : "";
+                const burnStr = e.burnRatePerMin !== null && e.burnRatePerMin > 0
+                    ? ` ~${Math.round(e.burnRatePerMin / 100) * 100}tok/min` : "";
+                const idleStr = e.idleMs !== null ? ` ${formatIdleSince(e.idleMs) || "active"}` : "";
+                tui.log("system", `  #${e.rank} ${e.title} [${e.status}]${errStr}${burnStr}${idleStr}`);
+            }
+        });
         // wire /watchdog stall detection
         input.onWatchdog((thresholdMinutes) => {
             if (thresholdMinutes === null) {

package/dist/input.d.ts

@@ -30,6 +30,9 @@ export type BurnRateHandler = () => void;
 export type SnapshotHandler = (format: "json" | "md") => void;
 export type BroadcastHandler = (message: string, group: string | null) => void;
 export type WatchdogHandler = (thresholdMinutes: number | null) => void;
+export type TopHandler = (mode: string) => void;
+export type CeilingHandler = () => void;
+export type RenameHandler = (target: string, name: string) => void;
 export interface MouseEvent {
     button: number;
     col: number;
@@ -82,6 +85,9 @@ export declare class InputReader {
     private snapshotHandler;
     private broadcastHandler;
     private watchdogHandler;
+    private topHandler;
+    private ceilingHandler;
+    private renameHandler;
     private aliases;
     private mouseDataListener;
     onScroll(handler: (dir: ScrollDirection) => void): void;
@@ -117,6 +123,9 @@ export declare class InputReader {
     onSnapshot(handler: SnapshotHandler): void;
     onBroadcast(handler: BroadcastHandler): void;
     onWatchdog(handler: WatchdogHandler): void;
+    onTop(handler: TopHandler): void;
+    onCeiling(handler: CeilingHandler): void;
+    onRename(handler: RenameHandler): void;
     /** Set aliases from persisted prefs. */
     setAliases(aliases: Record<string, string>): void;
     /** Get current aliases as a plain object. */

package/dist/input.js

@@ -63,6 +63,9 @@ export class InputReader {
     snapshotHandler = null;
     broadcastHandler = null;
     watchdogHandler = null;
+    topHandler = null;
+    ceilingHandler = null;
+    renameHandler = null;
     aliases = new Map(); // /shortcut → /full command
     mouseDataListener = null;
     // register a callback for scroll key events (PgUp/PgDn/Home/End)
@@ -197,6 +200,18 @@ export class InputReader {
     onWatchdog(handler) {
         this.watchdogHandler = handler;
     }
+    // register a callback for /top [mode]
+    onTop(handler) {
+        this.topHandler = handler;
+    }
+    // register a callback for /ceiling
+    onCeiling(handler) {
+        this.ceilingHandler = handler;
+    }
+    // register a callback for /rename <N|name> [display name]
+    onRename(handler) {
+        this.renameHandler = handler;
+    }
     /** Set aliases from persisted prefs. */
     setAliases(aliases) {
         this.aliases.clear();
@@ -430,6 +445,9 @@ ${BOLD}navigation:${RESET}
   /snapshot [md]     export session state snapshot to JSON (or Markdown with md)
   /broadcast <msg>   send message to all sessions; /broadcast group:<tag> <msg> for group
   /watchdog [N]      alert if session stalls N minutes (default 10); /watchdog off to disable
+  /top [mode]        rank sessions by errors (default), burn, or idle
+  /ceiling           show context token usage vs limit for all sessions
+  /rename N|name [display] set custom display name in TUI (no display = clear)
   /clip [N]          copy last N activity entries to clipboard (default 20)
   /diff N            show activity since bookmark N
   /mark              bookmark current activity position
@@ -819,6 +837,47 @@ ${BOLD}other:${RESET}
                 }
                 break;
             }
+            case "/rename": {
+                const renameArg = line.slice("/rename".length).trim();
+                if (!renameArg) {
+                    console.error(`${DIM}usage: /rename <N|name> [display name] — set custom display name (no name = clear)${RESET}`);
+                    break;
+                }
+                if (this.renameHandler) {
+                    const spaceIdx = renameArg.indexOf(" ");
+                    if (spaceIdx > 0) {
+                        const target = renameArg.slice(0, spaceIdx);
+                        const display = renameArg.slice(spaceIdx + 1).trim();
+                        this.renameHandler(target, display);
+                    }
+                    else {
+                        // target only — clear alias
+                        this.renameHandler(renameArg, "");
+                    }
+                }
+                else {
+                    console.error(`${DIM}rename not available (no TUI)${RESET}`);
+                }
+                break;
+            }
+            case "/ceiling":
+                if (this.ceilingHandler) {
+                    this.ceilingHandler();
+                }
+                else {
+                    console.error(`${DIM}ceiling not available (no TUI)${RESET}`);
+                }
+                break;
+            case "/top": {
+                const topArg = line.slice("/top".length).trim().toLowerCase() || "default";
+                if (this.topHandler) {
+                    this.topHandler(topArg);
+                }
+                else {
+                    console.error(`${DIM}top not available (no TUI)${RESET}`);
+                }
+                break;
+            }
             case "/watchdog": {
                 const wdArg = line.slice("/watchdog".length).trim().toLowerCase();
                 if (this.watchdogHandler) {

package/dist/task-parser.js

@@ -54,9 +54,12 @@ export function parseModel(output) {
 }
 // extract context info from OpenCode pane output
 export function parseContext(output) {
-    // matches "137,918 tokens" or "111,881 tokens"
-    const match = output.match(/([\d,]+)\s+tokens/);
-    return match?.[1] ? `${match[1]} tokens` : undefined;
+    // matches "137,918 / 200,000 tokens" or plain "137,918 tokens"
+    const full = output.match(/([\d,]+)\s*\/\s*([\d,]+)\s+tokens/);
+    if (full?.[1] && full[2])
+        return `${full[1]} / ${full[2]} tokens`;
+    const simple = output.match(/([\d,]+)\s+tokens/);
+    return simple?.[1] ? `${simple[1]} tokens` : undefined;
 }
 // extract cost from OpenCode pane output
 export function parseCost(output) {

package/dist/tui.d.ts

@@ -74,6 +74,10 @@ export declare function formatUptime(ms: number): string;
  * Returns empty string if under threshold (< thresholdMs, default 2 min — not worth showing).
  */
 export declare function formatIdleSince(ms: number, thresholdMs?: number): string;
+/** Max visible length for a custom session display name. */
+export declare const MAX_RENAME_LEN = 32;
+/** Truncate a custom display name to the max length. */
+export declare function truncateRename(name: string): string;
 /** Default watchdog threshold: 10 minutes of no output change triggers alert. */
 export declare const WATCHDOG_DEFAULT_MINUTES = 10;
 /** Cooldown between watchdog alerts for the same session (5 minutes). */
@@ -119,6 +123,42 @@ export declare function buildSnapshotData(sessions: readonly DaemonSessionState[
 export declare function formatSnapshotJson(data: SnapshotData): string;
 /** Format a SnapshotData as a Markdown report. */
 export declare function formatSnapshotMarkdown(data: SnapshotData): string;
+/** Health score color thresholds. */
+export declare const HEALTH_GOOD = 80;
+export declare const HEALTH_WARN = 60;
+/** Health score badge icon. */
+export declare const HEALTH_ICON = "\u2B21";
+/**
+ * Compute a composite health score (0–100) for a session.
+ * Higher = healthier. Deductions for: errors, high burn rate, context ceiling proximity, stall.
+ */
+export declare function computeHealthScore(opts: {
+    errorCount: number;
+    burnRatePerMin: number | null;
+    contextFraction: number | null;
+    idleMs: number | null;
+    watchdogThresholdMs: number | null;
+}): number;
+/**
+ * Format a health score as a colored badge string: "⬡83" in LIME/AMBER/ROSE.
+ * Returns empty string for score of exactly 100 (no badge clutter on healthy sessions).
+ */
+export declare function formatHealthBadge(score: number): string;
+export type TopSortMode = "errors" | "burn" | "idle" | "default";
+export declare const TOP_SORT_MODES: TopSortMode[];
+export interface TopEntry {
+    title: string;
+    status: string;
+    rank: number;
+    errors: number;
+    burnRatePerMin: number | null;
+    idleMs: number | null;
+}
+/**
+ * Rank sessions for /top output. Returns entries sorted by the given mode.
+ * "default" = composite: errors first, then burn rate, then idle.
+ */
+export declare function rankSessions(sessions: readonly DaemonSessionState[], errorCounts: ReadonlyMap<string, number>, burnRates: ReadonlyMap<string, number | null>, lastChangeAt: ReadonlyMap<string, number>, mode: TopSortMode, now?: number): TopEntry[];
 /** Format a broadcast summary for the activity log. */
 export declare function formatBroadcastSummary(count: number, group: string | null): string;
 export interface TuiPrefs {
@@ -130,6 +170,7 @@ export interface TuiPrefs {
     tagFilter?: string | null;
     aliases?: Record<string, string>;
     sessionGroups?: Record<string, string>;
+    sessionAliases?: Record<string, string>;
 }
 /** Load persisted TUI preferences. Returns empty object on any error. */
 export declare function loadTuiPrefs(): TuiPrefs;
@@ -174,8 +215,10 @@ export declare class TUI {
     private sessionErrorTimestamps;
     private sessionContextHistory;
     private burnRateAlerted;
+    private ceilingAlerted;
     private sessionGroups;
     private groupFilter;
+    private sessionAliases;
     private watchdogThresholdMs;
     private watchdogAlerted;
     private viewMode;
@@ -267,6 +310,11 @@ export declare class TUI {
     getSessionErrorTimestamps(id: string): readonly number[];
     /** Return context token history for a session (for burn-rate reporting). */
     getSessionContextHistory(id: string): readonly ContextHistoryEntry[];
+    /** Return parsed context ceiling for all sessions ({current, max} or null). */
+    getAllContextCeilings(): Map<string, {
+        current: number;
+        max: number;
+    } | null>;
     /** Return all sessions with their current burn rates (tokens/min, null if insufficient data). */
     getAllBurnRates(now?: number): Map<string, number | null>;
     /**
@@ -294,6 +342,17 @@ export declare class TUI {
     setGroupFilter(group: string | null): void;
     /** Get the current group filter (or null if none). */
     getGroupFilter(): string | null;
+    /**
+     * Set or clear a custom display name for a session (by 1-indexed number, ID, ID prefix, or title).
+     * Returns true if session found. Pass empty/null to clear.
+     */
+    renameSession(sessionIdOrIndex: string | number, displayName: string | null): boolean;
+    /** Get the custom display name for a session (or undefined if not renamed). */
+    getSessionAlias(id: string): string | undefined;
+    /** Return all session aliases (for persistence and listing). */
+    getAllSessionAliases(): ReadonlyMap<string, string>;
+    /** Restore session aliases from persisted prefs (bulk restore). */
+    restoreSessionAliases(aliases: Record<string, string>): void;
     /**
      * Add a bookmark at the current activity position.
      * Returns the bookmark number (1-indexed) or 0 if buffer is empty.
@@ -365,7 +424,7 @@ export declare class TUI {
     private repaintDrilldownContent;
     private paintInputLine;
 }
-declare function formatSessionCard(s: DaemonSessionState, maxWidth: number, errorSparkline?: string, idleSinceMs?: number): string;
+declare function formatSessionCard(s: DaemonSessionState, maxWidth: number, errorSparkline?: string, idleSinceMs?: number, healthBadge?: string, displayName?: string): string;
 declare function formatActivity(entry: ActivityEntry, maxCols: number): string;
 declare function padBoxLine(line: string, totalWidth: number): string;
 declare function padBoxLineHover(line: string, totalWidth: number, hovered: boolean): string;
@@ -390,6 +449,18 @@ declare function formatDrilldownScrollIndicator(offset: number, totalLines: numb
 declare function computeSparkline(timestamps: number[], now?: number, buckets?: number, windowMs?: number): number[];
 /** Format sparkline bucket counts as a colored Unicode block string. Returns empty string if all zeros. */
 declare function formatSparkline(counts: number[]): string;
+/**
+ * Parse a context token string that may include a ceiling: "137,918 / 200,000 tokens".
+ * Returns { current, max } if both values are present, null otherwise.
+ */
+export declare function parseContextCeiling(contextTokens: string | undefined): {
+    current: number;
+    max: number;
+} | null;
+/** Alert threshold: fire ceiling warning when context usage exceeds this fraction. */
+export declare const CONTEXT_CEILING_THRESHOLD = 0.9;
+/** Format a context ceiling alert for the activity log. */
+export declare function formatContextCeilingAlert(title: string, current: number, max: number): string;
 /** Parse a context token string like "137,918 tokens" to a raw number, or null if unparseable. */
 export declare function parseContextTokenNumber(contextTokens: string | undefined): number | null;
 /** Context history entry: token count at a timestamp. */

package/dist/tui.js

@@ -259,6 +259,13 @@ export function formatIdleSince(ms, thresholdMs = 2 * 60_000) {
         return "";
     return `idle ${formatUptime(ms)}`;
 }
+// ── Session rename ────────────────────────────────────────────────────────────
+/** Max visible length for a custom session display name. */
+export const MAX_RENAME_LEN = 32;
+/** Truncate a custom display name to the max length. */
+export function truncateRename(name) {
+    return name.length > MAX_RENAME_LEN ? name.slice(0, MAX_RENAME_LEN - 2) + ".." : name;
+}
 // ── Watchdog ──────────────────────────────────────────────────────────────────
 /** Default watchdog threshold: 10 minutes of no output change triggers alert. */
 export const WATCHDOG_DEFAULT_MINUTES = 10;
@@ -274,7 +281,7 @@ export const BUILTIN_COMMANDS = new Set([
     "/pin", "/bell", "/focus", "/mute", "/unmute-all", "/filter", "/who",
     "/uptime", "/auto-pin", "/note", "/notes", "/clip", "/diff", "/mark",
     "/jump", "/marks", "/search", "/alias", "/insist", "/task", "/tasks",
-    "/group", "/groups", "/group-filter", "/burn-rate", "/snapshot", "/broadcast", "/watchdog",
+    "/group", "/groups", "/group-filter", "/burn-rate", "/snapshot", "/broadcast", "/watchdog", "/top", "/ceiling", "/rename",
 ]);
 /** Resolve a slash command through the alias map. Returns the expanded command or the original. */
 export function resolveAlias(line, aliases) {
@@ -391,6 +398,84 @@ export function formatSnapshotMarkdown(data) {
     }
     return lines.join("\n");
 }
+// ── Session health score ──────────────────────────────────────────────────────
+/** Health score color thresholds. */
+export const HEALTH_GOOD = 80;
+export const HEALTH_WARN = 60;
+/** Health score badge icon. */
+export const HEALTH_ICON = "⬡";
+/**
+ * Compute a composite health score (0–100) for a session.
+ * Higher = healthier. Deductions for: errors, high burn rate, context ceiling proximity, stall.
+ */
+export function computeHealthScore(opts) {
+    let score = 100;
+    // errors: -10 per error, cap deduction at 50
+    const errDeduction = Math.min(50, opts.errorCount * 10);
+    score -= errDeduction;
+    // burn rate: -20 when above CONTEXT_BURN_THRESHOLD
+    if (opts.burnRatePerMin !== null && opts.burnRatePerMin > CONTEXT_BURN_THRESHOLD) {
+        score -= 20;
+    }
+    // context ceiling: -10 per 10% above 70% (so 80%→-10, 90%→-20, 100%→-30)
+    if (opts.contextFraction !== null) {
+        const overPct = Math.max(0, opts.contextFraction - 0.70);
+        const tenPctSteps = Math.floor(overPct * 10); // number of 10% increments over 70%
+        const ceDeduction = Math.min(30, tenPctSteps * 10);
+        score -= ceDeduction;
+    }
+    // stall: -15 when idle longer than watchdog threshold
+    if (opts.idleMs !== null && opts.watchdogThresholdMs !== null && opts.idleMs >= opts.watchdogThresholdMs) {
+        score -= 15;
+    }
+    return Math.max(0, Math.min(100, score));
+}
+/**
+ * Format a health score as a colored badge string: "⬡83" in LIME/AMBER/ROSE.
+ * Returns empty string for score of exactly 100 (no badge clutter on healthy sessions).
+ */
+export function formatHealthBadge(score) {
+    if (score >= 100)
+        return "";
+    const color = score >= HEALTH_GOOD ? LIME : score >= HEALTH_WARN ? AMBER : ROSE;
+    return `${color}${HEALTH_ICON}${score}${RESET}`;
+}
+export const TOP_SORT_MODES = ["default", "errors", "burn", "idle"];
+/**
+ * Rank sessions for /top output. Returns entries sorted by the given mode.
+ * "default" = composite: errors first, then burn rate, then idle.
+ */
+export function rankSessions(sessions, errorCounts, burnRates, lastChangeAt, mode, now) {
+    const nowMs = now ?? Date.now();
+    const entries = sessions.map((s) => ({
+        title: s.title,
+        status: s.status,
+        rank: 0,
+        errors: errorCounts.get(s.id) ?? 0,
+        burnRatePerMin: burnRates.get(s.id) ?? null,
+        idleMs: lastChangeAt.has(s.id) ? nowMs - lastChangeAt.get(s.id) : null,
+    }));
+    switch (mode) {
+        case "errors":
+            entries.sort((a, b) => b.errors - a.errors);
+            break;
+        case "burn":
+            entries.sort((a, b) => (b.burnRatePerMin ?? 0) - (a.burnRatePerMin ?? 0));
+            break;
+        case "idle":
+            entries.sort((a, b) => (b.idleMs ?? 0) - (a.idleMs ?? 0));
+            break;
+        default: {
+            // composite: weight errors heavily, then burn rate, then idle
+            const score = (e) => e.errors * 10000 +
+                (e.burnRatePerMin ?? 0) * 0.01 +
+                (e.idleMs ?? 0) * 0.0001;
+            entries.sort((a, b) => score(b) - score(a));
+        }
+    }
+    entries.forEach((e, i) => { e.rank = i + 1; });
+    return entries;
+}
 // ── Broadcast helpers ────────────────────────────────────────────────────────
 /** Format a broadcast summary for the activity log. */
 export function formatBroadcastSummary(count, group) {
@@ -455,8 +540,10 @@ export class TUI {
     sessionErrorTimestamps = new Map(); // session ID → recent error epoch ms (last 100)
     sessionContextHistory = new Map(); // session ID → context token history
     burnRateAlerted = new Map(); // session ID → epoch ms of last burn-rate alert (cooldown)
+    ceilingAlerted = new Map(); // session ID → epoch ms of last ceiling alert (cooldown)
     sessionGroups = new Map(); // session ID → group tag
     groupFilter = null; // active group filter (null = show all)
+    sessionAliases = new Map(); // session ID → custom display name
     watchdogThresholdMs = null; // null = disabled; ms of inactivity before alert
     watchdogAlerted = new Map(); // session ID → epoch ms of last watchdog alert
     // drill-down mode: show a single session's full output
@@ -754,6 +841,14 @@ export class TUI {
     getSessionContextHistory(id) {
         return this.sessionContextHistory.get(id) ?? [];
     }
+    /** Return parsed context ceiling for all sessions ({current, max} or null). */
+    getAllContextCeilings() {
+        const result = new Map();
+        for (const s of this.sessions) {
+            result.set(s.id, parseContextCeiling(s.contextTokens));
+        }
+        return result;
+    }
     /** Return all sessions with their current burn rates (tokens/min, null if insufficient data). */
     getAllBurnRates(now) {
         const result = new Map();
@@ -835,6 +930,46 @@ export class TUI {
     getGroupFilter() {
         return this.groupFilter;
     }
+    /**
+     * Set or clear a custom display name for a session (by 1-indexed number, ID, ID prefix, or title).
+     * Returns true if session found. Pass empty/null to clear.
+     */
+    renameSession(sessionIdOrIndex, displayName) {
+        let sessionId;
+        if (typeof sessionIdOrIndex === "number") {
+            sessionId = this.sessions[sessionIdOrIndex - 1]?.id;
+        }
+        else {
+            const needle = sessionIdOrIndex.toLowerCase();
+            const match = this.sessions.find((s) => s.id === sessionIdOrIndex || s.id.startsWith(needle) || s.title.toLowerCase() === needle);
+            sessionId = match?.id;
+        }
+        if (!sessionId)
+            return false;
+        if (!displayName || displayName.trim() === "") {
+            this.sessionAliases.delete(sessionId);
+        }
+        else {
+            this.sessionAliases.set(sessionId, truncateRename(displayName.trim()));
+        }
+        if (this.active)
+            this.paintSessions();
+        return true;
+    }
+    /** Get the custom display name for a session (or undefined if not renamed). */
+    getSessionAlias(id) {
+        return this.sessionAliases.get(id);
+    }
+    /** Return all session aliases (for persistence and listing). */
+    getAllSessionAliases() {
+        return this.sessionAliases;
+    }
+    /** Restore session aliases from persisted prefs (bulk restore). */
+    restoreSessionAliases(aliases) {
+        this.sessionAliases.clear();
+        for (const [id, name] of Object.entries(aliases))
+            this.sessionAliases.set(id, name);
+    }
     /**
      * Add a bookmark at the current activity position.
      * Returns the bookmark number (1-indexed) or 0 if buffer is empty.
@@ -929,6 +1064,15 @@ export class TUI {
                         }
                     }
                 }
+                // check context ceiling and emit alert if above threshold (with cooldown)
+                const ceiling = parseContextCeiling(s.contextTokens);
+                if (ceiling !== null && ceiling.current / ceiling.max >= CONTEXT_CEILING_THRESHOLD) {
+                    const lastCeiling = this.ceilingAlerted.get(s.id) ?? 0;
+                    if (now - lastCeiling >= BURN_ALERT_COOLDOWN_MS) {
+                        this.ceilingAlerted.set(s.id, now);
+                        this.log("status", formatContextCeilingAlert(s.title, ceiling.current, ceiling.max), s.id);
+                    }
+                }
             }
             // watchdog: alert if session has been idle longer than threshold
             if (this.watchdogThresholdMs !== null) {
@@ -1400,6 +1544,20 @@ export class TUI {
                 const errSparkline = errTs ? formatSessionErrorSparkline(errTs, nowMs) : "";
                 const lastChange = this.lastChangeAt.get(s.id);
                 const idleSinceMs = lastChange !== undefined ? nowMs - lastChange : undefined;
+                // compute health score
+                const ceiling = parseContextCeiling(s.contextTokens);
+                const contextFraction = ceiling ? ceiling.current / ceiling.max : null;
+                const burnHist = this.sessionContextHistory.get(s.id);
+                const burnRate = burnHist ? computeContextBurnRate(burnHist, nowMs) : null;
+                const healthScore = computeHealthScore({
+                    errorCount: this.sessionErrorCounts.get(s.id) ?? 0,
+                    burnRatePerMin: burnRate,
+                    contextFraction,
+                    idleMs: idleSinceMs ?? null,
+                    watchdogThresholdMs: this.watchdogThresholdMs,
+                });
+                const healthBadge = formatHealthBadge(healthScore);
+                const displayName = this.sessionAliases.get(s.id);
                 const muteBadge = muted ? formatMuteBadge(this.mutedEntryCounts.get(s.id) ?? 0) : "";
                 const muteBadgeWidth = muted ? String(Math.min(this.mutedEntryCounts.get(s.id) ?? 0, 9999)).length + 2 : 0; // "(N)" visible chars, 0 when count is 0
                 const actualBadgeWidth = (this.mutedEntryCounts.get(s.id) ?? 0) > 0 ? muteBadgeWidth + 1 : 0; // +1 for trailing space
@@ -1411,7 +1569,7 @@ export class TUI {
                 const badgeSuffix = muteBadge ? `${muteBadge} ` : "";
                 const iconsWidth = (pinned ? 2 : 0) + (muted ? 2 : 0) + (noted ? 2 : 0) + actualBadgeWidth + groupBadgeWidth;
                 const cardWidth = innerWidth - 1 - iconsWidth;
-                const line = `${bg}${SLATE}${BOX.v}${RESET}${bg} ${pin}${mute}${badgeSuffix}${note}${groupBadge}${formatSessionCard(s, cardWidth, errSparkline || undefined, idleSinceMs)}`;
+                const line = `${bg}${SLATE}${BOX.v}${RESET}${bg} ${pin}${mute}${badgeSuffix}${note}${groupBadge}${formatSessionCard(s, cardWidth, errSparkline || undefined, idleSinceMs, healthBadge || undefined, displayName)}`;
                 const padded = padBoxLineHover(line, this.cols, isHovered);
                 process.stderr.write(moveTo(startRow + 1 + i, 1) + CLEAR_LINE + padded);
             }
@@ -1451,6 +1609,19 @@ export class TUI {
         const errSparkline = errTs ? formatSessionErrorSparkline(errTs, nowMs2) : "";
         const lastChange = this.lastChangeAt.get(s.id);
         const idleSinceMs = lastChange !== undefined ? nowMs2 - lastChange : undefined;
+        const ceiling2 = parseContextCeiling(s.contextTokens);
+        const contextFraction2 = ceiling2 ? ceiling2.current / ceiling2.max : null;
+        const burnHist2 = this.sessionContextHistory.get(s.id);
+        const burnRate2 = burnHist2 ? computeContextBurnRate(burnHist2, nowMs2) : null;
+        const healthScore2 = computeHealthScore({
+            errorCount: this.sessionErrorCounts.get(s.id) ?? 0,
+            burnRatePerMin: burnRate2,
+            contextFraction: contextFraction2,
+            idleMs: idleSinceMs ?? null,
+            watchdogThresholdMs: this.watchdogThresholdMs,
+        });
+        const healthBadge2 = formatHealthBadge(healthScore2);
+        const displayName2 = this.sessionAliases.get(s.id);
         const muteBadge = muted ? formatMuteBadge(this.mutedEntryCounts.get(s.id) ?? 0) : "";
         const actualBadgeWidth = (this.mutedEntryCounts.get(s.id) ?? 0) > 0
             ? String(Math.min(this.mutedEntryCounts.get(s.id) ?? 0, 9999)).length + 3 : 0; // "(N) " visible chars
@@ -1462,7 +1633,7 @@ export class TUI {
         const badgeSuffix = muteBadge ? `${muteBadge} ` : "";
         const iconsWidth = (pinned ? 2 : 0) + (muted ? 2 : 0) + (noted ? 2 : 0) + actualBadgeWidth + groupBadgeWidth;
         const cardWidth = innerWidth - 1 - iconsWidth;
-        const line = `${bg}${SLATE}${BOX.v}${RESET}${bg} ${pin}${mute}${badgeSuffix}${note}${groupBadge}${formatSessionCard(s, cardWidth, errSparkline || undefined, idleSinceMs)}`;
+        const line = `${bg}${SLATE}${BOX.v}${RESET}${bg} ${pin}${mute}${badgeSuffix}${note}${groupBadge}${formatSessionCard(s, cardWidth, errSparkline || undefined, idleSinceMs, healthBadge2 || undefined, displayName2)}`;
         const padded = padBoxLineHover(line, this.cols, isHovered);
         process.stderr.write(SAVE_CURSOR + moveTo(startRow + 1 + i, 1) + CLEAR_LINE + padded + RESTORE_CURSOR);
     }
@@ -1584,13 +1755,18 @@ export class TUI {
 // format a session as a card-style line (inside the box)
 // errorSparkline: optional pre-formatted ROSE sparkline string (5 chars) for recent errors
 // idleSinceMs: optional ms since last activity change (shown when idle/stopped)
-function formatSessionCard(s, maxWidth, errorSparkline, idleSinceMs) {
+// healthBadge: optional pre-formatted health score badge ("⬡83" colored)
+// displayName: optional custom name override (from /rename)
+function formatSessionCard(s, maxWidth, errorSparkline, idleSinceMs, healthBadge, displayName) {
     const dot = STATUS_DOT[s.status] ?? `${AMBER}${DOT.filled}${RESET}`;
-    const name = `${BOLD}${s.title}${RESET}`;
+    const title = displayName ?? s.title;
+    const name = displayName ? `${BOLD}${displayName}${DIM} (${s.title})${RESET}` : `${BOLD}${s.title}${RESET}`;
     const toolBadge = `${SLATE}${s.tool}${RESET}`;
     const contextBadge = s.contextTokens ? ` ${DIM}(${s.contextTokens})${RESET}` : "";
     const sparkSuffix = errorSparkline ? ` ${errorSparkline}` : "";
-    // sparkline takes fixed space so status desc gets less room
+    const healthPrefix = healthBadge ? `${healthBadge} ` : "";
+    const healthPrefixWidth = healthBadge ? stripAnsiForLen(healthBadge) + 1 : 0;
+    // sparkline + health badge take fixed space so status desc gets less room
     const sparkWidth = errorSparkline ? SESSION_SPARK_BUCKETS + 1 : 0;
     // idle-since label: show when session is idle/stopped and stale > 2min
     const idleLabel = (idleSinceMs !== undefined && (s.status === "idle" || s.status === "stopped" || s.status === "done"))
@@ -1603,7 +1779,7 @@ function formatSessionCard(s, maxWidth, errorSparkline, idleSinceMs) {
     }
     else if (s.status === "working" || s.status === "running") {
         desc = s.currentTask
-            ? truncatePlain(s.currentTask, Math.max(20, maxWidth - s.title.length - s.tool.length - 16 - sparkWidth))
+            ? truncatePlain(s.currentTask, Math.max(20, maxWidth - title.length - s.tool.length - 16 - sparkWidth))
             : `${LIME}working${RESET}`;
     }
     else if (s.status === "idle" || s.status === "stopped") {
@@ -1621,7 +1797,7 @@ function formatSessionCard(s, maxWidth, errorSparkline, idleSinceMs) {
     else {
         desc = `${SLATE}${s.status}${RESET}`;
     }
-    return truncateAnsi(`${dot} ${name} ${toolBadge}${contextBadge} ${SLATE}${BOX.h}${RESET} ${desc}${sparkSuffix}`, maxWidth);
+    return truncateAnsi(`${dot} ${healthPrefix}${name} ${toolBadge}${contextBadge} ${SLATE}${BOX.h}${RESET} ${desc}${sparkSuffix}`, maxWidth);
 }
 // colorize an activity entry based on its tag
 function formatActivity(entry, maxCols) {
@@ -1824,6 +2000,31 @@ function formatSparkline(counts) {
     });
     return blocks.join("");
 }
+// ── Context ceiling warning (pure, exported for testing) ─────────────────────
+/**
+ * Parse a context token string that may include a ceiling: "137,918 / 200,000 tokens".
+ * Returns { current, max } if both values are present, null otherwise.
+ */
+export function parseContextCeiling(contextTokens) {
+    if (!contextTokens)
+        return null;
+    const stripped = contextTokens.replace(/,/g, "");
+    const match = stripped.match(/(\d+)\s*\/\s*(\d+)/);
+    if (!match)
+        return null;
+    const current = parseInt(match[1], 10);
+    const max = parseInt(match[2], 10);
+    if (isNaN(current) || isNaN(max) || max <= 0)
+        return null;
+    return { current, max };
+}
+/** Alert threshold: fire ceiling warning when context usage exceeds this fraction. */
+export const CONTEXT_CEILING_THRESHOLD = 0.90;
+/** Format a context ceiling alert for the activity log. */
+export function formatContextCeilingAlert(title, current, max) {
+    const pct = Math.round((current / max) * 100);
+    return `${title}: context at ${pct}% (${current.toLocaleString()} / ${max.toLocaleString()} tokens) — approaching limit`;
+}
 // ── Context burn-rate tracking (pure, exported for testing) ─────────────────
 /** Parse a context token string like "137,918 tokens" to a raw number, or null if unparseable. */
 export function parseContextTokenNumber(contextTokens) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aoaoe",
-  "version": "0.109.0",
+  "version": "0.114.0",
   "description": "Autonomous supervisor for agent-of-empires sessions using OpenCode or Claude Code",
   "type": "module",
   "main": "dist/index.js",