@integsec/agentic-pentest-proxy 0.3.4 → 0.3.6

package/docs/superpowers/plans/2026-03-28-tui-monitor.md

@@ -0,0 +1,863 @@
+# TUI Monitor Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a standalone Ink-based terminal dashboard that monitors audit JSONL files in real time.
+
+**Architecture:** A separate bin entry (`integsec-agentic-pentest-tui`) renders an Ink React app. A custom hook watches the audit directory for new JSONL lines, parses them into `AuditEntry` objects, and feeds them to a dashboard with three panels: engagement header, stats, and live decision feed.
+
+**Tech Stack:** Ink 5, React 18, TypeScript TSX, fs.watch()
+
+---
+
+### Task 1: Install dependencies and configure TSX build
+
+**Files:**
+- Modify: `package.json`
+- Modify: `tsconfig.json`
+
+- [ ] **Step 1: Install ink, react, and types**
+
+```bash
+npm install ink@^5.0.0 react@^18.0.0 ink-spinner@^5.0.0
+npm install -D @types/react@^18.0.0
+```
+
+- [ ] **Step 2: Add jsx support to tsconfig.json**
+
+In `tsconfig.json`, add `"jsx": "react-jsx"` to `compilerOptions`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src/**/*", "bin/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+- [ ] **Step 3: Add bin entry to package.json**
+
+Add to the `"bin"` section:
+
+```json
+"bin": {
+  "integsec-agentic-pentest-proxy": "dist/bin/integsec-agentic-pentest-proxy.js",
+  "integsec-agentic-pentest-tui": "dist/bin/integsec-agentic-pentest-tui.js"
+},
+```
+
+Add `"src/tui/**/*"` is already covered by `"src/**/*"` in tsconfig include — no change needed.
+
+- [ ] **Step 4: Verify build still works**
+
+```bash
+npm run build
+npm test
+```
+
+Expected: All 598 tests pass, no TSX compilation errors (no TSX files yet, just verifying config doesn't break).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add package.json package-lock.json tsconfig.json
+git commit -m "chore: add ink/react deps and jsx support for TUI"
+```
+
+---
+
+### Task 2: Build the JSONL tail/watcher utility
+
+**Files:**
+- Create: `src/tui/audit-tailer.ts`
+- Test: `tests/unit/audit-tailer.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/unit/audit-tailer.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { readNewEntries, scanExistingEntries } from "../src/tui/audit-tailer.js";
+import type { AuditEntry } from "../src/types.js";
+
+function makeEntry(overrides: Partial<AuditEntry> = {}): AuditEntry {
+  return {
+    timestamp: new Date().toISOString(),
+    engagement_id: "ENG-TEST-001",
+    client: "Test Client",
+    operator: "test@test.com",
+    tool_name: "nmap_scan",
+    tool_parameters: { target: "10.0.0.1" },
+    extracted_target: "10.0.0.1",
+    resolved_ips: ["10.0.0.1"],
+    decision: "ALLOWED",
+    decision_reason: "Target matches authorized IP range",
+    matched_scope_item: "10.0.0.0/24",
+    duration_ms: 2,
+    proxy_version: "0.1.2",
+    ...overrides,
+  };
+}
+
+describe("audit-tailer", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tui-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("readNewEntries", () => {
+    it("reads entries from a given byte offset", () => {
+      const filePath = path.join(tmpDir, "ENG-TEST-001.jsonl");
+      const entry1 = makeEntry({ tool_name: "nmap_scan" });
+      const entry2 = makeEntry({ tool_name: "curl" });
+      fs.writeFileSync(filePath, JSON.stringify(entry1) + "\n" + JSON.stringify(entry2) + "\n");
+
+      const result = readNewEntries(filePath, 0);
+      expect(result.entries).toHaveLength(2);
+      expect(result.entries[0].tool_name).toBe("nmap_scan");
+      expect(result.entries[1].tool_name).toBe("curl");
+      expect(result.newOffset).toBeGreaterThan(0);
+    });
+
+    it("reads only new entries after offset", () => {
+      const filePath = path.join(tmpDir, "ENG-TEST-001.jsonl");
+      const entry1 = makeEntry({ tool_name: "nmap_scan" });
+      fs.writeFileSync(filePath, JSON.stringify(entry1) + "\n");
+      const firstRead = readNewEntries(filePath, 0);
+
+      const entry2 = makeEntry({ tool_name: "curl" });
+      fs.appendFileSync(filePath, JSON.stringify(entry2) + "\n");
+      const secondRead = readNewEntries(filePath, firstRead.newOffset);
+
+      expect(secondRead.entries).toHaveLength(1);
+      expect(secondRead.entries[0].tool_name).toBe("curl");
+    });
+
+    it("skips malformed lines", () => {
+      const filePath = path.join(tmpDir, "ENG-TEST-001.jsonl");
+      const entry = makeEntry();
+      fs.writeFileSync(filePath, "not json\n" + JSON.stringify(entry) + "\n" + "{bad\n");
+
+      const result = readNewEntries(filePath, 0);
+      expect(result.entries).toHaveLength(1);
+      expect(result.entries[0].tool_name).toBe("nmap_scan");
+    });
+
+    it("returns empty for nonexistent file", () => {
+      const result = readNewEntries(path.join(tmpDir, "nope.jsonl"), 0);
+      expect(result.entries).toHaveLength(0);
+      expect(result.newOffset).toBe(0);
+    });
+  });
+
+  describe("scanExistingEntries", () => {
+    it("reads all entries from all jsonl files in directory", () => {
+      const entry1 = makeEntry({ engagement_id: "ENG-001", tool_name: "nmap" });
+      const entry2 = makeEntry({ engagement_id: "ENG-002", tool_name: "curl" });
+      fs.writeFileSync(path.join(tmpDir, "ENG-001.jsonl"), JSON.stringify(entry1) + "\n");
+      fs.writeFileSync(path.join(tmpDir, "ENG-002.jsonl"), JSON.stringify(entry2) + "\n");
+
+      const result = scanExistingEntries(tmpDir);
+      expect(result.entries).toHaveLength(2);
+      expect(result.offsets.size).toBe(2);
+    });
+
+    it("filters by engagement ID when provided", () => {
+      const entry1 = makeEntry({ engagement_id: "ENG-001" });
+      const entry2 = makeEntry({ engagement_id: "ENG-002" });
+      fs.writeFileSync(path.join(tmpDir, "ENG-001.jsonl"), JSON.stringify(entry1) + "\n");
+      fs.writeFileSync(path.join(tmpDir, "ENG-002.jsonl"), JSON.stringify(entry2) + "\n");
+
+      const result = scanExistingEntries(tmpDir, "ENG-001");
+      expect(result.entries).toHaveLength(1);
+      expect(result.entries[0].engagement_id).toBe("ENG-001");
+    });
+
+    it("returns empty for empty directory", () => {
+      const result = scanExistingEntries(tmpDir);
+      expect(result.entries).toHaveLength(0);
+      expect(result.offsets.size).toBe(0);
+    });
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npx vitest run tests/unit/audit-tailer.test.ts
+```
+
+Expected: FAIL — cannot resolve `../src/tui/audit-tailer.js`
+
+- [ ] **Step 3: Write the implementation**
+
+Create `src/tui/audit-tailer.ts`:
+
+```typescript
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AuditEntry } from "../types.js";
+
+export interface TailResult {
+  entries: AuditEntry[];
+  newOffset: number;
+}
+
+export interface ScanResult {
+  entries: AuditEntry[];
+  offsets: Map<string, number>;
+}
+
+/**
+ * Read new JSONL entries from a file starting at the given byte offset.
+ * Skips malformed lines. Returns parsed entries and the new offset.
+ */
+export function readNewEntries(filePath: string, offset: number): TailResult {
+  if (!fs.existsSync(filePath)) {
+    return { entries: [], newOffset: offset };
+  }
+
+  const stat = fs.statSync(filePath);
+  if (stat.size <= offset) {
+    return { entries: [], newOffset: offset };
+  }
+
+  const fd = fs.openSync(filePath, "r");
+  const buf = Buffer.alloc(stat.size - offset);
+  fs.readSync(fd, buf, 0, buf.length, offset);
+  fs.closeSync(fd);
+
+  const text = buf.toString("utf-8");
+  const lines = text.split("\n").filter((l) => l.trim().length > 0);
+  const entries: AuditEntry[] = [];
+
+  for (const line of lines) {
+    try {
+      entries.push(JSON.parse(line) as AuditEntry);
+    } catch {
+      // Skip malformed lines
+    }
+  }
+
+  return { entries, newOffset: stat.size };
+}
+
+/**
+ * Scan all .jsonl files in the audit directory and return all entries
+ * plus the current byte offsets for each file (for subsequent tailing).
+ * Optionally filter to a single engagement ID.
+ */
+export function scanExistingEntries(
+  auditDir: string,
+  engagementId?: string
+): ScanResult {
+  if (!fs.existsSync(auditDir)) {
+    return { entries: [], offsets: new Map() };
+  }
+
+  const files = fs.readdirSync(auditDir).filter((f) => f.endsWith(".jsonl"));
+  const allEntries: AuditEntry[] = [];
+  const offsets = new Map<string, number>();
+
+  for (const file of files) {
+    if (engagementId && file !== `${engagementId}.jsonl`) {
+      continue;
+    }
+    const filePath = path.join(auditDir, file);
+    const result = readNewEntries(filePath, 0);
+    allEntries.push(...result.entries);
+    offsets.set(filePath, result.newOffset);
+  }
+
+  allEntries.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  return { entries: allEntries, offsets };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm run build && npx vitest run tests/unit/audit-tailer.test.ts
+```
+
+Expected: All 7 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/tui/audit-tailer.ts tests/unit/audit-tailer.test.ts
+git commit -m "feat: add JSONL audit tailer for TUI monitor"
+```
+
+---
+
+### Task 3: Build the DecisionRow component
+
+**Files:**
+- Create: `src/tui/DecisionRow.tsx`
+
+- [ ] **Step 1: Create DecisionRow component**
+
+Create `src/tui/DecisionRow.tsx`:
+
+```tsx
+import React from "react";
+import { Text } from "ink";
+import type { AuditEntry } from "../types.js";
+
+interface DecisionRowProps {
+  entry: AuditEntry;
+}
+
+export function DecisionRow({ entry }: DecisionRowProps): React.ReactElement {
+  const time = entry.timestamp.slice(11, 19); // HH:MM:SS
+  const isBlocked = entry.decision.startsWith("BLOCKED");
+  const isNoTarget = entry.decision === "ALLOWED_NO_TARGET";
+
+  const icon = isBlocked ? "✗" : "✓";
+  const color = isBlocked ? "red" : isNoTarget ? "gray" : "green";
+
+  const shortDecision = entry.decision.replace("BLOCKED_", "");
+  const target = entry.extracted_target ?? "—";
+  const reason = isBlocked ? ` [${shortDecision}]` : "";
+
+  return (
+    <Text color={color}>
+      {time} {icon} {entry.decision.split("_")[0].padEnd(7)} {entry.tool_name} → {target}{reason} ({entry.duration_ms}ms)
+    </Text>
+  );
+}
+```
+
+- [ ] **Step 2: Verify build**
+
+```bash
+npm run build
+```
+
+Expected: Compiles without errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/tui/DecisionRow.tsx
+git commit -m "feat: add DecisionRow TUI component"
+```
+
+---
+
+### Task 4: Build the EngagementHeader component
+
+**Files:**
+- Create: `src/tui/EngagementHeader.tsx`
+
+- [ ] **Step 1: Create EngagementHeader component**
+
+Create `src/tui/EngagementHeader.tsx`:
+
+```tsx
+import React from "react";
+import { Box, Text } from "ink";
+import type { AuditEntry } from "../types.js";
+
+interface EngagementHeaderProps {
+  entry: AuditEntry | null;
+}
+
+export function EngagementHeader({ entry }: EngagementHeaderProps): React.ReactElement {
+  if (!entry) {
+    return (
+      <Box borderStyle="single" paddingX={1}>
+        <Text dimColor>Waiting for audit data...</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box borderStyle="single" paddingX={1} flexDirection="column">
+      <Text bold>
+        {entry.engagement_id} <Text dimColor>|</Text> {entry.client} <Text dimColor>|</Text> {entry.operator}
+      </Text>
+    </Box>
+  );
+}
+```
+
+- [ ] **Step 2: Verify build**
+
+```bash
+npm run build
+```
+
+Expected: Compiles without errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/tui/EngagementHeader.tsx
+git commit -m "feat: add EngagementHeader TUI component"
+```
+
+---
+
+### Task 5: Build the StatsPanel component
+
+**Files:**
+- Create: `src/tui/StatsPanel.tsx`
+
+- [ ] **Step 1: Create StatsPanel component**
+
+Create `src/tui/StatsPanel.tsx`:
+
+```tsx
+import React from "react";
+import { Box, Text } from "ink";
+import type { AuditEntry } from "../types.js";
+
+interface StatsPanelProps {
+  entries: AuditEntry[];
+}
+
+function topN(counts: Map<string, number>, n: number): string {
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, n)
+    .map(([name, count]) => `${name} (${count})`)
+    .join("  ");
+}
+
+export function StatsPanel({ entries }: StatsPanelProps): React.ReactElement {
+  const allowed = entries.filter((e) => e.decision.startsWith("ALLOWED")).length;
+  const blocked = entries.length - allowed;
+
+  const targetCounts = new Map<string, number>();
+  const toolCounts = new Map<string, number>();
+
+  for (const e of entries) {
+    if (e.extracted_target) {
+      targetCounts.set(e.extracted_target, (targetCounts.get(e.extracted_target) ?? 0) + 1);
+    }
+    toolCounts.set(e.tool_name, (toolCounts.get(e.tool_name) ?? 0) + 1);
+  }
+
+  return (
+    <Box borderStyle="single" paddingX={1} flexDirection="column">
+      <Text>
+        <Text color="green">✓ Allowed: {allowed}</Text>
+        {"   "}
+        <Text color="red">✗ Blocked: {blocked}</Text>
+        {"   "}
+        <Text>Total: {entries.length}</Text>
+      </Text>
+      {targetCounts.size > 0 && (
+        <Text dimColor>Targets: {topN(targetCounts, 3)}</Text>
+      )}
+      {toolCounts.size > 0 && (
+        <Text dimColor>Tools: {topN(toolCounts, 3)}</Text>
+      )}
+    </Box>
+  );
+}
+```
+
+- [ ] **Step 2: Verify build**
+
+```bash
+npm run build
+```
+
+Expected: Compiles without errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/tui/StatsPanel.tsx
+git commit -m "feat: add StatsPanel TUI component"
+```
+
+---
+
+### Task 6: Build the LiveFeed component
+
+**Files:**
+- Create: `src/tui/LiveFeed.tsx`
+
+- [ ] **Step 1: Create LiveFeed component**
+
+Create `src/tui/LiveFeed.tsx`:
+
+```tsx
+import React from "react";
+import { Box, Text } from "ink";
+import type { AuditEntry } from "../types.js";
+import { DecisionRow } from "./DecisionRow.js";
+
+interface LiveFeedProps {
+  entries: AuditEntry[];
+  maxRows: number;
+}
+
+export function LiveFeed({ entries, maxRows }: LiveFeedProps): React.ReactElement {
+  const visible = entries.slice(-maxRows);
+
+  if (visible.length === 0) {
+    return (
+      <Box borderStyle="single" paddingX={1} flexDirection="column">
+        <Text bold> LIVE FEED</Text>
+        <Text dimColor>No decisions yet...</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box borderStyle="single" paddingX={1} flexDirection="column">
+      <Text bold> LIVE FEED</Text>
+      {visible.map((entry, i) => (
+        <DecisionRow key={`${entry.timestamp}-${i}`} entry={entry} />
+      ))}
+    </Box>
+  );
+}
+```
+
+- [ ] **Step 2: Verify build**
+
+```bash
+npm run build
+```
+
+Expected: Compiles without errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/tui/LiveFeed.tsx
+git commit -m "feat: add LiveFeed TUI component"
+```
+
+---
+
+### Task 7: Build the App root component and useAuditWatcher hook
+
+**Files:**
+- Create: `src/tui/useAuditWatcher.ts`
+- Create: `src/tui/App.tsx`
+
+- [ ] **Step 1: Create the useAuditWatcher hook**
+
+Create `src/tui/useAuditWatcher.ts`:
+
+```typescript
+import { useState, useEffect, useRef } from "react";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AuditEntry } from "../types.js";
+import { readNewEntries, scanExistingEntries } from "./audit-tailer.js";
+
+interface WatcherState {
+  entries: AuditEntry[];
+}
+
+export function useAuditWatcher(auditDir: string, engagementId?: string): WatcherState {
+  const [entries, setEntries] = useState<AuditEntry[]>([]);
+  const offsetsRef = useRef<Map<string, number>>(new Map());
+
+  useEffect(() => {
+    // Load existing entries
+    const scan = scanExistingEntries(auditDir, engagementId);
+    setEntries(scan.entries);
+    offsetsRef.current = scan.offsets;
+
+    // Ensure directory exists for watcher
+    if (!fs.existsSync(auditDir)) {
+      fs.mkdirSync(auditDir, { recursive: true });
+    }
+
+    // Watch for changes
+    const watcher = fs.watch(auditDir, (_event, filename) => {
+      if (!filename || !filename.endsWith(".jsonl")) return;
+      if (engagementId && filename !== `${engagementId}.jsonl`) return;
+
+      const filePath = path.join(auditDir, filename);
+      const currentOffset = offsetsRef.current.get(filePath) ?? 0;
+      const result = readNewEntries(filePath, currentOffset);
+
+      if (result.entries.length > 0) {
+        offsetsRef.current.set(filePath, result.newOffset);
+        setEntries((prev) => [...prev, ...result.entries]);
+      }
+    });
+
+    return () => {
+      watcher.close();
+    };
+  }, [auditDir, engagementId]);
+
+  return { entries };
+}
+```
+
+- [ ] **Step 2: Create the App root component**
+
+Create `src/tui/App.tsx`:
+
+```tsx
+import React from "react";
+import { Box, useStdout } from "ink";
+import { EngagementHeader } from "./EngagementHeader.js";
+import { StatsPanel } from "./StatsPanel.js";
+import { LiveFeed } from "./LiveFeed.js";
+import { useAuditWatcher } from "./useAuditWatcher.js";
+
+interface AppProps {
+  auditDir: string;
+  engagementId?: string;
+}
+
+export function App({ auditDir, engagementId }: AppProps): React.ReactElement {
+  const { entries } = useAuditWatcher(auditDir, engagementId);
+  const { stdout } = useStdout();
+  const termHeight = stdout?.rows ?? 24;
+
+  // Reserve rows for header (~3), stats (~4), feed border/title (~2), padding
+  const feedRows = Math.max(5, termHeight - 12);
+  const firstEntry = entries.length > 0 ? entries[0] : null;
+
+  return (
+    <Box flexDirection="column">
+      <EngagementHeader entry={firstEntry} />
+      <StatsPanel entries={entries} />
+      <LiveFeed entries={entries} maxRows={feedRows} />
+    </Box>
+  );
+}
+```
+
+- [ ] **Step 3: Verify build**
+
+```bash
+npm run build
+```
+
+Expected: Compiles without errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/tui/useAuditWatcher.ts src/tui/App.tsx
+git commit -m "feat: add App root component and useAuditWatcher hook"
+```
+
+---
+
+### Task 8: Build the CLI entry point
+
+**Files:**
+- Create: `bin/integsec-agentic-pentest-tui.tsx`
+
+- [ ] **Step 1: Create the entry point**
+
+Create `bin/integsec-agentic-pentest-tui.tsx`:
+
+```tsx
+#!/usr/bin/env node
+
+import React from "react";
+import { render } from "ink";
+import { App } from "../src/tui/App.js";
+
+function parseArgs(): { auditDir: string; engagementId?: string } {
+  const args = process.argv.slice(2);
+  let auditDir = process.env.AUDIT_LOG_PATH ?? "./audit";
+  let engagementId: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--audit-path" && args[i + 1]) {
+      auditDir = args[i + 1];
+      i++;
+    } else if (args[i] === "--engagement" && args[i + 1]) {
+      engagementId = args[i + 1];
+      i++;
+    } else if (args[i] === "--help" || args[i] === "-h") {
+      console.log(`
+IntegSec Agentic Pentest MCP Proxy — TUI Monitor
+
+Usage:
+  integsec-agentic-pentest-tui [options]
+
+Options:
+  --audit-path <dir>      Path to audit log directory (default: AUDIT_LOG_PATH or ./audit)
+  --engagement <id>       Filter to a specific engagement ID
+  -h, --help              Show this help message
+`);
+      process.exit(0);
+    }
+  }
+
+  return { auditDir, engagementId };
+}
+
+const { auditDir, engagementId } = parseArgs();
+render(<App auditDir={auditDir} engagementId={engagementId} />);
+```
+
+- [ ] **Step 2: Build and verify**
+
+```bash
+npm run build
+```
+
+Expected: Compiles, `dist/bin/integsec-agentic-pentest-tui.js` exists.
+
+- [ ] **Step 3: Smoke test with empty audit directory**
+
+```bash
+mkdir -p ./audit-test
+node dist/bin/integsec-agentic-pentest-tui.js --audit-path ./audit-test
+```
+
+Expected: Shows engagement header with "Waiting for audit data..." and empty live feed. Ctrl+C to exit.
+
+```bash
+rm -rf ./audit-test
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add bin/integsec-agentic-pentest-tui.tsx
+git commit -m "feat: add TUI monitor CLI entry point"
+```
+
+---
+
+### Task 9: Run full test suite and update README
+
+**Files:**
+- Modify: `README.md`
+- Modify: `package.json` (files field)
+
+- [ ] **Step 1: Run full test suite**
+
+```bash
+npm run build && npm test
+```
+
+Expected: All tests pass (existing 598 + 7 new audit-tailer tests = 605).
+
+- [ ] **Step 2: Add TUI section to README**
+
+In `README.md`, add a new section after the "Usage" section and before "How Validation Works". Add the following:
+
+```markdown
+## TUI Monitor
+
+A real-time terminal dashboard for monitoring proxy decisions as they happen.
+
+```bash
+# Monitor the default audit directory
+integsec-agentic-pentest-tui
+
+# Monitor a specific directory
+integsec-agentic-pentest-tui --audit-path /path/to/audit
+
+# Filter to a specific engagement
+integsec-agentic-pentest-tui --engagement ENG-2026-TEST-001
+```
+
+The TUI displays three panels:
+
+- **Engagement Header** — engagement ID, client, operator
+- **Stats Panel** — running allowed/blocked counts, top targets, top tools
+- **Live Feed** — color-coded scrolling decision feed (green = allowed, red = blocked)
+
+Run the TUI in a separate terminal while the proxy is active (via Claude Desktop, Claude Code, or CLI). It tails the audit JSONL files and updates in real time.
+```
+
+- [ ] **Step 3: Add TUI to Table of Contents**
+
+In the Table of Contents section, add after the Docker entry:
+
+```markdown
+- [TUI Monitor](#tui-monitor)
+```
+
+- [ ] **Step 4: Ensure TUI files are included in npm package**
+
+The `"files"` field in `package.json` already includes `"dist/"` which covers the compiled TUI. No change needed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: add TUI monitor section to README"
+```
+
+---
+
+### Task 10: Bump version, publish, and push
+
+**Files:**
+- Modify: `package.json` (version)
+
+- [ ] **Step 1: Bump version**
+
+```bash
+npm version minor --no-git-tag-version
+```
+
+This bumps to 0.2.0 since TUI is a new feature.
+
+- [ ] **Step 2: Build and run full test suite one more time**
+
+```bash
+npm run build && npm test
+```
+
+Expected: All tests pass.
+
+- [ ] **Step 3: Commit and push**
+
+```bash
+git add -A
+git commit -m "feat: add TUI monitor dashboard (v0.2.0)"
+git push
+```
+
+- [ ] **Step 4: Publish to npm**
+
+```bash
+npm publish --access public
+```
+
+- [ ] **Step 5: Update global install**
+
+```bash
+npm install -g @integsec/agentic-pentest-proxy@latest
+```