aoaoe 0.160.0 → 0.187.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-2005-brightgreen" alt="tests">
+    <img src="https://img.shields.io/badge/tests-2427-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>
@@ -15,6 +15,8 @@ An autonomous supervisor for [Agent of Empires](https://github.com/njbrake/agent
 
 **This project is a companion to [Agent of Empires (AoE)](https://github.com/njbrake/agent-of-empires) by [Nate Brake](https://x.com/natebrake).** AoE is the foundation -- it manages multiple AI coding agents in tmux sessions with git worktrees. aoaoe adds an autonomous supervisor layer on top. You need AoE running first; aoaoe plugs into it.
 
+> **Self-improvement mode**: `make self` starts aoaoe supervising its own AoE session — reading the roadmap from `aoaoe.tasks.json`, implementing features, committing, and pushing. It updates itself in real time.
+
 ## What is this?
 
 [AoE](https://github.com/njbrake/agent-of-empires) is great at spawning and organizing agents, but someone still needs to watch the tmux panes and intervene when agents get stuck, ask questions, or finish their work.
@@ -103,6 +105,18 @@ The real deal. Polls, reasons, and executes -- sending keystrokes to agents, res
 | `--confirm` | Yes | Yes | You approve each action |
 | `aoaoe` | Yes | Yes | Yes |
 
+## Self-improvement
+
+aoaoe can supervise its own development. With an `aoaoe` AoE session open on this repo:
+
+```bash
+make setup   # install deps, build, create AoE session if missing (one-time)
+make self    # aoaoe supervises itself: reads roadmap, implements, commits, pushes
+make self-dry  # watch-only — see what it would do without letting it act
+```
+
+The goal in `aoaoe.tasks.json` drives the session: pick backlog items, implement with tests, commit atomically, push, tag releases. The daemon watches its own tmux pane and nudges the agent when it stalls or needs direction.
+
 ## Quick Start
 
 aoaoe has two parts: a **daemon** (the brain) and a **chat UI** (your window into it). Here's how to get both running.
@@ -248,7 +262,7 @@ The daemon runs an interactive TUI with a rich command set. These commands are a
 | `1`-`9` | Quick-switch: jump to session N |
 | `/view [N\|name]` | Drill into a session's live output (default: 1) |
 | `/back` | Return to overview from drill-down |
-| `/sort [mode]` | Sort sessions: `status`, `name`, `activity`, `default` (no arg = cycle) |
+| `/sort [mode]` | Sort sessions: `status`, `name`, `activity`, `health`, `default` (no arg = cycle) |
 | `/compact` | Toggle compact mode (dense session panel) |
 | `/pin [N\|name]` | Pin/unpin a session to the top |
 | `/bell` | Toggle terminal bell on errors/completions |
@@ -276,6 +290,10 @@ The daemon runs an interactive TUI with a rich command set. These commands are a
 | `/color-all [c]` | Set accent color for all sessions at once |
 | `/mute-errors` | Toggle suppression of `error`/`! action` entries in activity log |
 | `/pin-all-errors` | Pin every session currently in error state |
+| `/pin-draining` | Pin all draining sessions to the top |
+| `/labels` | List all active session labels |
+| `/sort-by-health` | Sort sessions by health score (worst first) |
+| `/icon N [emoji]` | Set or clear a single emoji shown in the session row |
 | `/timeline N [n]` | Show last n activity entries for a session (default 30) |
 | `/find <text>` | Search all session pane outputs for text |
 | `/reset-health N` | Clear error counts + context history to reset a session's health score |
@@ -318,6 +336,10 @@ The daemon runs an interactive TUI with a rich command set. These commands are a
 | `/clear-history` | Truncate `~/.aoaoe/tui-history.jsonl` |
 | `/copy [N]` | Copy session's current pane output to clipboard (default: current drill-down) |
 | `/alias /x /cmd` | Create command alias (`/x` expands to `/cmd`); no args = list |
+| `/ctx-budget` | Show context budget allocation across sessions (activity-weighted) |
+| `/profile [name]` | Show active AoE profiles; optionally switch focus to a named profile |
+| `/replay <N\|name> [lps]` | Play back a session's stored pane output line by line (default 10 lps; run again to stop) |
+| `/notify-filter <session> <events...>` | Set per-session webhook event filter (`session_error`, `session_done`, etc.); no args = list; `clear` = remove all |
 
 ### Other
 
@@ -358,6 +380,9 @@ The daemon runs an interactive TUI with a rich command set. These commands are a
 - **Activity heatmap** -- 24-hour colored block chart via `aoaoe stats`
 - **Bookmarks** -- mark positions, jump back, diff since a bookmark
 - **Clipboard export** -- `/clip` and `/copy` copy activity or session pane output to clipboard
+- **Automatic context compaction** -- when a session hits 80% context usage, daemon sends a compaction nudge via tmux; 10-min cooldown per session
+- **Multi-profile polling** -- daemon polls all configured AoE profiles simultaneously; sessions deduped by ID across profiles
+- **Session replay** -- `/replay <N|name> [lps]` plays back stored pane output in the activity log at configurable speed
 
 ## Chat UI Commands
 
@@ -368,6 +393,9 @@ The chat UI (`aoaoe-chat`) runs inside an AoE tmux pane. Register it with `aoaoe
 | `/overview` | Show all AoE sessions with tasks, model, tokens, cost. **Works without the daemon.** |
 | `/tasks` | Alias for `/overview` |
 | `/status` | Daemon connection status + countdown to next reasoning cycle |
+| `/incident [opts]` | Incident quick view: response-flow runbook + recent supervisor activity (`--since`, `--limit`, `--json`, `--ndjson`, `--follow`) |
+| `/runbook [section] [--json]` | Print operator playbook slice (`quickstart`, `response-flow`/`incident`, `all`) |
+| `/supervisor [opts]` | Judge/orchestrator status across tasks/sessions (`--all`, `--since`, `--limit`, `--json`) |
 | `/interrupt` | Interrupt the current reasoner call |
 | `/dashboard` | Request full dashboard output from daemon |
 | `/pause` | Pause the daemon (stops reasoning) |
@@ -403,6 +431,29 @@ commands:
   (none)         start the supervisor daemon (interactive TUI)
   init           detect tools + sessions, import history, generate config
   status         quick daemon health check (is it running? what's it doing?)
+  runbook        print operator quickstart for day-2 supervision
+  runbook --json machine-readable runbook output for tooling
+  runbook --section <quickstart|response-flow|incident|all> print only one runbook section
+  incident       one-shot incident quick view (response-flow + recent activity)
+  incident --since <duration>      filter incident event window (30m, 2h, 1d)
+  incident --limit <N>             cap incident events shown (default: 5)
+  incident --json                  machine-readable incident output
+  incident --ndjson                emit compact one-line JSON snapshots
+  incident --watch                 stream incident snapshots continuously
+  incident --follow                shortcut for --watch --changes-only --heartbeat 30
+  incident --changes-only          emit only when incident state changes (implies --watch)
+  incident --heartbeat <sec>       keepalive interval (implies --changes-only + --watch)
+  incident --interval <ms>         watch refresh interval (default: 5000, min: 500)
+  supervisor     one-shot supervisor/task/session orchestration status
+  supervisor --all                 show full recent supervisor event buffer
+  supervisor --since <duration>    filter events to a time window (30m, 2h, 7d)
+  supervisor --limit <N>           cap number of events shown (default: 5)
+  supervisor --json                machine-readable output for automation
+  supervisor --ndjson              emit compact one-line JSON snapshots
+  supervisor --watch               stream supervisor snapshots continuously
+  supervisor --changes-only        emit only when state changes (implies --watch)
+  supervisor --heartbeat <sec>     keepalive interval (implies --changes-only + --watch)
+  supervisor --interval <ms>       watch refresh interval (default: 5000, min: 500)
   config         show the effective resolved config (defaults + file)
   config --validate  validate config + check tool availability
   config --diff  show only fields that differ from defaults
@@ -416,7 +467,7 @@ commands:
   export --format <json|markdown>  output format (default: json)
   export --output <file>           write to file (default: stdout)
   export --last <duration>         time window: 1h, 6h, 24h, 7d (default: 24h)
-  task           manage tasks and sessions (list, start, stop, new, rm, edit)
+  task           manage tasks and sessions (list, reconcile, start, stop, new, rm, edit, help)
   tasks          show task progress (from aoaoe.tasks.json)
   history        review recent actions (from ~/.aoaoe/actions.log)
   test-context   scan sessions + context files (read-only, no LLM, safe)
@@ -447,6 +498,62 @@ register options:
   --title, -t <name>                 session title in AoE (default: aoaoe)
 ```
 
+### Supervisor Streaming Examples
+
+```bash
+# Human-readable watch output (change-only)
+aoaoe supervisor --watch --changes-only --heartbeat 60
+
+# NDJSON stream for pipes/collectors
+aoaoe supervisor --watch --ndjson --changes-only --heartbeat 30
+
+# Filter to the last 2 hours and show only 20 events
+aoaoe supervisor --since 2h --limit 20
+```
+
+JSON/NDJSON payloads include `emitReason` with one of:
+- `snapshot` (one-shot invocation)
+- `interval` (periodic watch tick)
+- `change` (watch emission caused by state change)
+- `heartbeat` (keepalive emission from `--heartbeat`)
+
+### Incident Streaming Examples
+
+```bash
+# One-shot incident snapshot (human readable)
+aoaoe incident --since 30m --limit 10
+
+# Fast follow mode (alias for --watch --changes-only)
+aoaoe incident --follow --heartbeat 30 --ndjson
+
+# NDJSON incident stream for monitors (change-only + keepalive)
+aoaoe incident --watch --ndjson --changes-only --heartbeat 30
+
+# JSON watch stream (compact one object per tick in watch mode)
+aoaoe incident --watch --json --interval 5000
+```
+
+### Operator Playbook
+
+Use this when running aoaoe as a long-lived judge over many AoE sessions.
+
+```bash
+# 1) Start low-noise supervision stream in a side pane
+aoaoe supervisor --watch --ndjson --changes-only --heartbeat 30
+
+# 2) If sessions/tasks drift, force immediate reconciliation
+aoaoe task reconcile
+
+# 3) If a specific session needs new direction, inject a goal quickly
+aoaoe-chat
+# then type: /task <session> :: <new goal>
+```
+
+Recommended response flow:
+- `emitReason=change` spikes: inspect `/supervisor --since 30m --limit 20`
+- stalled task (pending/paused too long): run `aoaoe task reconcile`, then nudge via `/task ... :: ...`
+- noisy but unchanged systems: keep `--changes-only --heartbeat 30` so monitors still get liveness
+
 ## Configuration
 
 Config lives at `~/.aoaoe/aoaoe.config.json` (canonical, written by `aoaoe init`). A local `aoaoe.config.json` in cwd overrides for development. Defaults work fine without a config file:

package/dist/colors.d.ts

@@ -13,8 +13,23 @@ export declare const SLATE = "\u001B[38;5;245m";
 export declare const ROSE = "\u001B[38;5;204m";
 export declare const LIME = "\u001B[38;5;114m";
 export declare const SKY = "\u001B[38;5;117m";
-export declare const BG_DARK = "\u001B[48;5;236m";
+export declare const PURPLE = "\u001B[38;5;141m";
+export declare const ORANGE = "\u001B[38;5;208m";
+export declare const PINK = "\u001B[38;5;213m";
+export declare const GOLD = "\u001B[38;5;220m";
+export declare const SILVER = "\u001B[38;5;250m";
+export declare const STEEL = "\u001B[38;5;240m";
+export declare const BG_DARK = "\u001B[48;5;235m";
+export declare const BG_HEADER2 = "\u001B[48;5;237m";
 export declare const BG_HOVER = "\u001B[48;5;238m";
+export declare const BG_INPUT = "\u001B[48;5;234m";
+export declare const BG_SECTION = "\u001B[48;5;236m";
+export declare const BG_INDIGO = "\u001B[48;5;62m";
+export declare const BG_SKY = "\u001B[48;5;67m";
+export declare const BG_LIME = "\u001B[48;5;71m";
+export declare const BG_ROSE = "\u001B[48;5;160m";
+export declare const BG_AMBER = "\u001B[48;5;172m";
+export declare const BG_TEAL = "\u001B[48;5;30m";
 export declare const BOX: {
     readonly tl: "┌";
     readonly tr: "┐";
@@ -31,11 +46,34 @@ export declare const BOX: {
     readonly rtr: "╮";
     readonly rbl: "╰";
     readonly rbr: "╯";
+    readonly dh: "═";
+    readonly dv: "║";
+    readonly dtl: "╔";
+    readonly dtr: "╗";
+    readonly dbl: "╚";
+    readonly dbr: "╝";
+    readonly dltee: "╠";
+    readonly drtee: "╣";
 };
 export declare const SPINNER: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export declare const PROGRESS_BLOCKS = 12;
+export declare const PROGRESS_IDLE = "\u001B[38;5;240m";
+export declare const PROGRESS_TIP = "\u001B[38;5;75m";
 export declare const DOT: {
     readonly filled: "●";
     readonly hollow: "○";
     readonly half: "◐";
 };
+export declare const GLYPH: {
+    readonly agent: "◈";
+    readonly activity: "◉";
+    readonly input: "▸";
+    readonly thinking: "⟳";
+    readonly clock: "◷";
+    readonly check: "✓";
+    readonly cross: "✗";
+    readonly arrow: "→";
+    readonly bullet: "•";
+    readonly pipe: "┃";
+};
 //# sourceMappingURL=colors.d.ts.map

package/dist/colors.js

@@ -9,7 +9,6 @@ export const YELLOW = "\x1b[33m";
 export const CYAN = "\x1b[36m";
 export const WHITE = "\x1b[37m";
 // 256-color palette — tasteful accents for the TUI
-// use sparingly: these are highlights, not defaults
 export const INDIGO = "\x1b[38;5;105m"; // muted purple-blue for branding
 export const TEAL = "\x1b[38;5;73m"; // cool blue-green for info
 export const AMBER = "\x1b[38;5;214m"; // warm orange for warnings/active
@@ -17,9 +16,25 @@ export const SLATE = "\x1b[38;5;245m"; // neutral gray for secondary text
 export const ROSE = "\x1b[38;5;204m"; // soft red for errors
 export const LIME = "\x1b[38;5;114m"; // fresh green for success/working
 export const SKY = "\x1b[38;5;117m"; // light blue for reasoning
+export const PURPLE = "\x1b[38;5;141m"; // violet for special highlights
+export const ORANGE = "\x1b[38;5;208m"; // bright orange for warnings
+export const PINK = "\x1b[38;5;213m"; // hot pink for high-signal events
+export const GOLD = "\x1b[38;5;220m"; // gold for completed/done
+export const SILVER = "\x1b[38;5;250m"; // light gray for borders/structural
+export const STEEL = "\x1b[38;5;240m"; // dark gray for dim structural elements
 // background variants (256-color)
-export const BG_DARK = "\x1b[48;5;236m"; // dark gray for header bar
-export const BG_HOVER = "\x1b[48;5;238m"; // slightly brighter gray for hover highlight
+export const BG_DARK = "\x1b[48;5;235m"; // header bar (very dark)
+export const BG_HEADER2 = "\x1b[48;5;237m"; // secondary header sections
+export const BG_HOVER = "\x1b[48;5;238m"; // hover highlight
+export const BG_INPUT = "\x1b[48;5;234m"; // input box background
+export const BG_SECTION = "\x1b[48;5;236m"; // section panel background
+// bright foreground on dark background (for section labels in colored boxes)
+export const BG_INDIGO = "\x1b[48;5;62m"; // indigo bg for brand pill
+export const BG_SKY = "\x1b[48;5;67m"; // sky bg for reasoning pill
+export const BG_LIME = "\x1b[48;5;71m"; // lime bg for working pill
+export const BG_ROSE = "\x1b[48;5;160m"; // rose bg for error pill
+export const BG_AMBER = "\x1b[48;5;172m"; // amber bg for warning pill
+export const BG_TEAL = "\x1b[48;5;30m"; // teal bg for info pill
 // box-drawing characters — Unicode block elements
 export const BOX = {
     tl: "┌", tr: "┐", bl: "└", br: "┘",
@@ -27,9 +42,31 @@ export const BOX = {
     ltee: "├", rtee: "┤", ttee: "┬", btee: "┴", cross: "┼",
     // rounded corners (softer look)
     rtl: "╭", rtr: "╮", rbl: "╰", rbr: "╯",
+    // double-line (for section headers)
+    dh: "═", dv: "║",
+    dtl: "╔", dtr: "╗", dbl: "╚", dbr: "╝",
+    // mixed (double-horizontal, single-vertical tees)
+    dltee: "╠", drtee: "╣",
 };
 // braille spinner frames for phase animation
 export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+// bouncing progress bar frames (blue tip sweeping over grey blocks)
+export const PROGRESS_BLOCKS = 12; // width of the progress bar in chars
+export const PROGRESS_IDLE = "\x1b[38;5;240m"; // grey for idle blocks ░
+export const PROGRESS_TIP = "\x1b[38;5;75m"; // bright blue for active tip ▓
 // status dots — filled circle variants
 export const DOT = { filled: "●", hollow: "○", half: "◐" };
+// section label glyphs
+export const GLYPH = {
+    agent: "◈", // agents panel
+    activity: "◉", // activity log
+    input: "▸", // input prompt
+    thinking: "⟳", // reasoning in progress
+    clock: "◷", // countdown
+    check: "✓", // done/ok
+    cross: "✗", // error
+    arrow: "→", // action
+    bullet: "•", // generic
+    pipe: "┃", // vertical gutter bar (colored per tag)
+};
 //# sourceMappingURL=colors.js.map

package/dist/config.d.ts

@@ -23,8 +23,34 @@ export declare function parseCliArgs(argv: string[]): {
     testContext: boolean;
     runTest: boolean;
     showTasks: boolean;
+    showTasksJson: boolean;
+    runProgress: boolean;
+    progressSince?: string;
+    progressJson: boolean;
     showHistory: boolean;
     showStatus: boolean;
+    runRunbook: boolean;
+    runbookJson: boolean;
+    runbookSection?: string;
+    runIncident: boolean;
+    incidentSince?: string;
+    incidentLimit?: number;
+    incidentJson: boolean;
+    incidentNdjson: boolean;
+    incidentWatch: boolean;
+    incidentChangesOnly: boolean;
+    incidentHeartbeatSec?: number;
+    incidentIntervalMs?: number;
+    runSupervisor: boolean;
+    supervisorAll: boolean;
+    supervisorSince?: string;
+    supervisorLimit?: number;
+    supervisorJson: boolean;
+    supervisorNdjson: boolean;
+    supervisorWatch: boolean;
+    supervisorChangesOnly: boolean;
+    supervisorHeartbeatSec?: number;
+    supervisorIntervalMs?: number;
     showConfig: boolean;
     configValidate: boolean;
     configDiff: boolean;

package/dist/config.js

@@ -12,6 +12,7 @@ const CONFIG_SEARCH_DIRS = [AOAOE_DIR, process.cwd()];
 export const DEFAULTS = {
     reasoner: "opencode",
     pollIntervalMs: 10_000,
+    reasonIntervalMs: 60_000,
     opencode: {
         port: 4097,
     },
@@ -81,7 +82,7 @@ export function loadConfig(overrides) {
 }
 // known top-level and nested config keys — used to warn on typos
 const KNOWN_KEYS = {
-    reasoner: true, pollIntervalMs: true, captureLinesCount: true,
+    reasoner: true, pollIntervalMs: true, reasonIntervalMs: true, captureLinesCount: true,
     verbose: true, dryRun: true, observe: true, confirm: true,
     contextFiles: true, sessionDirs: true, protectedSessions: true, healthPort: true, tuiHistoryRetentionDays: true,
     opencode: new Set(["port", "model"]),
@@ -122,6 +123,9 @@ export function validateConfig(config) {
     if (typeof config.pollIntervalMs !== "number" || config.pollIntervalMs < 1000 || !isFinite(config.pollIntervalMs)) {
         errors.push(`pollIntervalMs must be a number >= 1000, got ${config.pollIntervalMs}`);
     }
+    if (typeof config.reasonIntervalMs !== "number" || config.reasonIntervalMs < config.pollIntervalMs || !isFinite(config.reasonIntervalMs)) {
+        errors.push(`reasonIntervalMs must be a number >= pollIntervalMs (${config.pollIntervalMs}), got ${config.reasonIntervalMs}`);
+    }
     if (typeof config.captureLinesCount !== "number" || config.captureLinesCount < 1 || !isFinite(config.captureLinesCount)) {
         errors.push(`captureLinesCount must be a positive number, got ${config.captureLinesCount}`);
     }
@@ -327,7 +331,7 @@ export function parseCliArgs(argv) {
     let initForce = false;
     let runTaskCli = false;
     let registerTitle;
-    const defaults = { overrides, help: false, version: false, register: false, testContext: false, runTest: false, showTasks: false, showHistory: false, showStatus: false, showConfig: false, configValidate: false, configDiff: false, notifyTest: false, runDoctor: false, runLogs: false, logsActions: false, logsGrep: undefined, logsCount: undefined, runExport: false, exportFormat: undefined, exportOutput: undefined, exportLast: undefined, runInit: false, initForce: false, runTaskCli: false, runTail: false, tailFollow: false, tailCount: undefined, runStats: false, statsLast: undefined, runReplay: false, replaySpeed: undefined, replayLast: undefined };
+    const defaults = { overrides, help: false, version: false, register: false, testContext: false, runTest: false, showTasks: false, showTasksJson: false, runProgress: false, progressSince: undefined, progressJson: false, showHistory: false, showStatus: false, runRunbook: false, runbookJson: false, runbookSection: undefined, runIncident: false, incidentSince: undefined, incidentLimit: undefined, incidentJson: false, incidentNdjson: false, incidentWatch: false, incidentChangesOnly: false, incidentHeartbeatSec: undefined, incidentIntervalMs: undefined, runSupervisor: false, supervisorAll: false, supervisorSince: undefined, supervisorLimit: undefined, supervisorJson: false, supervisorNdjson: false, supervisorWatch: false, supervisorChangesOnly: false, supervisorHeartbeatSec: undefined, supervisorIntervalMs: undefined, showConfig: false, configValidate: false, configDiff: false, notifyTest: false, runDoctor: false, runLogs: false, logsActions: false, logsGrep: undefined, logsCount: undefined, runExport: false, exportFormat: undefined, exportOutput: undefined, exportLast: undefined, runInit: false, initForce: false, runTaskCli: false, runTail: false, tailFollow: false, tailCount: undefined, runStats: false, statsLast: undefined, runReplay: false, replaySpeed: undefined, replayLast: undefined };
     // check for subcommand as first non-flag arg
     if (argv[2] === "test-context") {
         return { ...defaults, testContext: true };
@@ -339,7 +343,17 @@ export function parseCliArgs(argv) {
         return { ...defaults, runTaskCli: true };
     }
     if (argv[2] === "tasks") {
-        return { ...defaults, showTasks: true };
+        const json = argv.includes("--json");
+        return { ...defaults, showTasks: true, showTasksJson: json };
+    }
+    if (argv[2] === "progress") {
+        let since;
+        const json = argv.includes("--json");
+        for (let i = 3; i < argv.length; i++) {
+            if (argv[i] === "--since" && argv[i + 1])
+                since = argv[++i];
+        }
+        return { ...defaults, runProgress: true, progressSince: since, progressJson: json };
     }
     if (argv[2] === "history") {
         return { ...defaults, showHistory: true };
@@ -347,6 +361,148 @@ export function parseCliArgs(argv) {
     if (argv[2] === "status") {
         return { ...defaults, showStatus: true };
     }
+    if (argv[2] === "runbook") {
+        const json = argv.includes("--json");
+        let section;
+        for (let i = 3; i < argv.length; i++) {
+            if ((argv[i] === "--section" || argv[i] === "-s") && argv[i + 1]) {
+                section = argv[++i];
+            }
+            else if (!argv[i].startsWith("-") && !section) {
+                section = argv[i];
+            }
+        }
+        return { ...defaults, runRunbook: true, runbookJson: json, runbookSection: section };
+    }
+    if (argv[2] === "incident") {
+        let since;
+        let limit;
+        let json = false;
+        let ndjson = false;
+        let watch = false;
+        let follow = false;
+        let changesOnly = false;
+        let heartbeatSec;
+        let intervalMs;
+        for (let i = 3; i < argv.length; i++) {
+            if (argv[i] === "--json") {
+                json = true;
+            }
+            else if (argv[i] === "--ndjson") {
+                ndjson = true;
+            }
+            else if (argv[i] === "--follow" || argv[i] === "-f") {
+                follow = true;
+            }
+            else if (argv[i] === "--watch" || argv[i] === "-w") {
+                watch = true;
+            }
+            else if (argv[i] === "--changes-only") {
+                changesOnly = true;
+            }
+            else if ((argv[i] === "--heartbeat" || argv[i] === "-H") && argv[i + 1]) {
+                const val = parseInt(argv[++i], 10);
+                if (!isNaN(val) && val >= 1)
+                    heartbeatSec = val;
+            }
+            else if ((argv[i] === "--interval" || argv[i] === "-i") && argv[i + 1]) {
+                const val = parseInt(argv[++i], 10);
+                if (!isNaN(val) && val >= 500)
+                    intervalMs = val;
+            }
+            else if (argv[i] === "--since" && argv[i + 1]) {
+                since = argv[++i];
+            }
+            else if (argv[i] === "--limit" && argv[i + 1]) {
+                const val = parseInt(argv[++i], 10);
+                if (!isNaN(val) && val > 0)
+                    limit = val;
+            }
+        }
+        if (follow) {
+            if (!watch)
+                watch = true;
+            if (!changesOnly)
+                changesOnly = true;
+            if (heartbeatSec === undefined)
+                heartbeatSec = 30;
+        }
+        if (changesOnly && !watch)
+            watch = true;
+        if (heartbeatSec !== undefined) {
+            if (!changesOnly)
+                changesOnly = true;
+            if (!watch)
+                watch = true;
+        }
+        return {
+            ...defaults,
+            runIncident: true,
+            incidentSince: since,
+            incidentLimit: limit,
+            incidentJson: json,
+            incidentNdjson: ndjson,
+            incidentWatch: watch,
+            incidentChangesOnly: changesOnly,
+            incidentHeartbeatSec: heartbeatSec,
+            incidentIntervalMs: intervalMs,
+        };
+    }
+    if (argv[2] === "supervisor") {
+        let all = false;
+        let since;
+        let limit;
+        let json = false;
+        let ndjson = false;
+        let watch = false;
+        let changesOnly = false;
+        let heartbeatSec;
+        let intervalMs;
+        for (let i = 3; i < argv.length; i++) {
+            if (argv[i] === "--all") {
+                all = true;
+            }
+            else if (argv[i] === "--json") {
+                json = true;
+            }
+            else if (argv[i] === "--ndjson") {
+                ndjson = true;
+            }
+            else if (argv[i] === "--watch" || argv[i] === "-w") {
+                watch = true;
+            }
+            else if (argv[i] === "--changes-only") {
+                changesOnly = true;
+            }
+            else if ((argv[i] === "--heartbeat" || argv[i] === "-H") && argv[i + 1]) {
+                const val = parseInt(argv[++i], 10);
+                if (!isNaN(val) && val >= 1)
+                    heartbeatSec = val;
+            }
+            else if (argv[i] === "--since" && argv[i + 1]) {
+                since = argv[++i];
+            }
+            else if (argv[i] === "--limit" && argv[i + 1]) {
+                const val = parseInt(argv[++i], 10);
+                if (!isNaN(val) && val > 0)
+                    limit = val;
+            }
+            else if ((argv[i] === "--interval" || argv[i] === "-i") && argv[i + 1]) {
+                const val = parseInt(argv[++i], 10);
+                if (!isNaN(val) && val >= 500)
+                    intervalMs = val;
+            }
+        }
+        if (changesOnly && !watch)
+            watch = true;
+        if (heartbeatSec !== undefined) {
+            if (!changesOnly)
+                changesOnly = true;
+            if (!watch)
+                watch = true;
+        }
+        return { ...defaults, runSupervisor: true, supervisorAll: all, supervisorSince: since, supervisorLimit: limit, supervisorJson: json, supervisorNdjson: ndjson, supervisorWatch: watch, supervisorChangesOnly: changesOnly, supervisorHeartbeatSec: heartbeatSec, supervisorIntervalMs: intervalMs };
+    }
     if (argv[2] === "config") {
         const validate = argv.includes("--validate") || argv.includes("-V");
         const diff = argv.includes("--diff");
@@ -455,7 +611,7 @@ export function parseCliArgs(argv) {
         return argv[i + 1];
     };
     const knownFlags = new Set([
-        "--reasoner", "--poll-interval", "--port", "--model", "--profile", "--health-port",
+        "--reasoner", "--opencode", "--claude-code", "--poll-interval", "--reason-interval", "--port", "--model", "--profile", "--health-port",
         "--verbose", "-v", "--dry-run", "--observe", "--confirm", "--help", "-h", "--version",
     ]);
     for (let i = 2; i < argv.length; i++) {
@@ -465,6 +621,12 @@ export function parseCliArgs(argv) {
                 overrides.reasoner = toReasonerBackend(nextArg(i, arg));
                 i++;
                 break;
+            case "--opencode":
+                overrides.reasoner = "opencode";
+                break;
+            case "--claude-code":
+                overrides.reasoner = "claude-code";
+                break;
             case "--poll-interval": {
                 const val = parseInt(nextArg(i, arg), 10);
                 if (isNaN(val))
@@ -473,6 +635,14 @@ export function parseCliArgs(argv) {
                 i++;
                 break;
             }
+            case "--reason-interval": {
+                const val = parseInt(nextArg(i, arg), 10);
+                if (isNaN(val))
+                    throw new Error(`--reason-interval value '${argv[i + 1]}' is not a valid number`);
+                overrides.reasonIntervalMs = val;
+                i++;
+                break;
+            }
             case "--port": {
                 const val = parseInt(nextArg(i, arg), 10);
                 if (isNaN(val))
@@ -530,7 +700,7 @@ export function parseCliArgs(argv) {
                 break;
         }
     }
-    return { overrides, help, version, register: false, testContext: false, runTest: false, showTasks: false, showHistory: false, showStatus: false, showConfig: false, configValidate: false, configDiff: false, notifyTest: false, runDoctor: false, runLogs: false, logsActions: false, logsGrep: undefined, logsCount: undefined, runExport: false, exportFormat: undefined, exportOutput: undefined, exportLast: undefined, runInit: false, initForce: false, runTaskCli: false, runTail: false, tailFollow: false, tailCount: undefined, runStats: false, statsLast: undefined, runReplay: false, replaySpeed: undefined, replayLast: undefined };
+    return { overrides, help, version, register: false, testContext: false, runTest: false, showTasks: false, showTasksJson: false, runProgress: false, progressSince: undefined, progressJson: false, showHistory: false, showStatus: false, runRunbook: false, runbookJson: false, runbookSection: undefined, runIncident: false, incidentSince: undefined, incidentLimit: undefined, incidentJson: false, incidentNdjson: false, incidentWatch: false, incidentChangesOnly: false, incidentHeartbeatSec: undefined, incidentIntervalMs: undefined, runSupervisor: false, supervisorAll: false, supervisorSince: undefined, supervisorLimit: undefined, supervisorJson: false, supervisorNdjson: false, supervisorWatch: false, supervisorChangesOnly: false, supervisorHeartbeatSec: undefined, supervisorIntervalMs: undefined, showConfig: false, configValidate: false, configDiff: false, notifyTest: false, runDoctor: false, runLogs: false, logsActions: false, logsGrep: undefined, logsCount: undefined, runExport: false, exportFormat: undefined, exportOutput: undefined, exportLast: undefined, runInit: false, initForce: false, runTaskCli: false, runTail: false, tailFollow: false, tailCount: undefined, runStats: false, statsLast: undefined, runReplay: false, replaySpeed: undefined, replayLast: undefined };
 }
 export function printHelp() {
     console.log(`aoaoe - autonomous supervisor for agent-of-empires sessions
@@ -547,6 +717,29 @@ commands:
   init           detect tools + sessions, import history, generate config
   (none)         start the supervisor daemon (interactive TUI)
   status         quick daemon health check (is it running? what's it doing?)
+  runbook        print operator playbook for day-2 supervision
+  runbook --json machine-readable runbook output
+  runbook --section <quickstart|response-flow|incident|all> print only one runbook section
+  incident       one-shot incident quick view (response-flow + recent activity)
+  incident --since <duration>      filter incident events window (30m, 2h, 1d)
+  incident --limit <N>             cap incident events shown (default: 5)
+  incident --json                  machine-readable incident output
+  incident --ndjson                emit compact one-line JSON snapshots
+  incident --watch                 stream incident snapshots continuously
+  incident --follow                shortcut for --watch --changes-only --heartbeat 30
+  incident --changes-only          emit only when incident state changes (implies --watch)
+  incident --heartbeat <sec>       keepalive interval (implies --changes-only + --watch)
+  incident --interval <ms>         watch refresh interval (default: 5000, min: 500)
+  supervisor     one-shot supervisor/task/session orchestration status
+  supervisor --all                 show full recent supervisor event buffer
+  supervisor --since <duration>    filter events to a time window (30m, 2h, 7d)
+  supervisor --limit <N>           cap number of events shown (default: 5)
+  supervisor --json                machine-readable output for automation
+  supervisor --ndjson              emit one compact JSON object per snapshot
+  supervisor --watch               stream supervisor snapshot continuously
+  supervisor --changes-only        emit only when state changes (implies --watch)
+  supervisor --heartbeat <sec>     keepalive interval (implies --changes-only + --watch)
+  supervisor --interval <ms>       watch refresh interval (default: 5000, min: 500)
   config         show the effective resolved config (defaults + file)
   config --validate  validate config + check tool availability
   config --diff  show only fields that differ from defaults
@@ -569,8 +762,12 @@ commands:
   tail           live-stream daemon activity to a separate terminal
   tail -f        follow mode — keep watching for new entries (Ctrl+C to stop)
   tail -n <N>    number of entries to show (default: 50)
-  task           manage tasks and sessions (list, start, stop, new, rm, edit)
+  task           manage tasks and sessions (list, reconcile, start, stop, new, rm, edit, help)
   tasks          show task progress (from aoaoe.tasks.json)
+  tasks --json   machine-readable task state output
+  progress       per-session accomplishment digest (last 24h)
+  progress --since <duration>  filter progress window (1h, 8h, 7d)
+  progress --json              machine-readable progress output
   history        review recent actions (from ~/.aoaoe/actions.log)
   test           run integration test (creates sessions, tests, cleans up)
   test-context   scan sessions + context files (read-only, no LLM, safe)
@@ -578,7 +775,10 @@ commands:
 
 options:
   --reasoner <opencode|claude-code>  reasoning backend (default: opencode)
-  --poll-interval <ms>               poll interval in ms (default: 10000)
+  --opencode                         shorthand for --reasoner opencode
+  --claude-code                      shorthand for --reasoner claude-code
+  --poll-interval <ms>               tmux observation poll interval in ms (default: 10000)
+  --reason-interval <ms>             minimum ms between LLM reasoning calls (default: 60000)
   --port <number>                    opencode server port (default: 4097)
   --health-port <number>             start HTTP health check server on this port
   --model <model>                    model to use

package/dist/executor.d.ts

@@ -24,6 +24,7 @@ export declare class Executor {
     private resolveSession;
     private resolveTmuxName;
     private resolveSessionId;
+    private buildProfileAwareAoeArgs;
     private isProtected;
     private get cooldownMs();
     private isRateLimited;