pi-deadman 1.0.0

package/README.md

@@ -0,0 +1,110 @@
+# pi-deadman
+
+Dead man's switch for AI coding agents.
+
+Monitors macOS memory pressure, gates heavy operations, and auto-kills runaway processes before your system locks up.
+
+## The Problem
+
+AI coding agents run builds, tests, installs, and browser automation with no awareness of system memory state. On an 8 GB Mac, this regularly pushes the system into swap thrashing — minutes of lag, system freezes, sometimes requiring a hard reboot.
+
+## Install
+
+```bash
+pi install git:github.com/gaherwar/pi-deadman
+```
+
+On first run, pi-deadman calibrates a baseline for your machine (~10 seconds of canary tests). After that, it runs in the background — no configuration needed.
+
+**macOS only.** Silent no-op on other platforms.
+
+## How It Works
+
+### Pre-Execution Gate
+
+Every `bash` tool call goes through a tier × zone matrix:
+
+| | GREEN | YELLOW | ORANGE | RED |
+|---|---|---|---|---|
+| **Tier 0–1** (read-only: ls, cat, grep) | ✅ | ✅ | ✅ | ❌ |
+| **Tier 2** (medium: test, server, spawn) | ✅ | ✅ | ✅ | ❌ |
+| **Tier 3** (heavy: npm install, docker, build) | ✅ | ✅ | ❌ | ❌ |
+| **Tier 4** (destructive: kill, pkill, rm -rf) | ✅ | ✅ | ❌ | ❌ |
+
+When blocked in **ORANGE**, you choose: run anyway or free memory first.
+When blocked in **RED**, you must kill a process to proceed — or force-run after the first attempt.
+
+### Background Monitor
+
+Polls system health at adaptive intervals (5s in GREEN → 1s in RED):
+
+- **Canary test** — micro-ops (array sort, Map ops, regex, JSON parse, Buffer alloc) timed via `performance.now()`. Slowdown ratio vs baseline determines zone.
+- **System signals** — swap usage, swap in/out rates, compression ratio, memorystatus level via `sysctl` and `vm_stat`.
+- **Process snapshots** — footprint (true memory) via `proc_pid_rusage` Python helper, stored in a ring buffer of 10 snapshots.
+
+### Watchdog (Confirmed RED)
+
+When the system enters confirmed RED (3 consecutive RED polls), the watchdog auto-kills processes across **all pi sessions**. Processes with < 50 MB footprint are never kill candidates.
+
+| Priority | Signal | Catches |
+|---|---|---|
+| 1. **Growing** | ≥100 MB delta across 3+ of 10 snapshots | Memory leaks, sawtooth patterns |
+| 2. **Swarm** | ≥3 same-name processes, combined ≥500 MB | Worker pools (vitest ×7, webpack workers) |
+| 3. **Heavy & young** | Age < 10 min AND footprint ≥ 200 MB | Burst allocators |
+| 4. **Newest** | Appeared after last stable non-RED state | Temporal correlation (largest only) |
+| 5. **No match** | Block commands, wait | Pressure from outside pi's tree |
+
+Two execution paths:
+- **Slow poll** — full canary + signals + footprint worker. Populates snapshot ring buffer.
+- **Fast watchdog** — independent 2s loop using `ps` (~17ms). Parses fresh `etime` for age. Walks children of ALL pi instances (cross-session). Acts even when the slow poll is stuck during system thrashing.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/deadman` | Show current zone, memory stats, recent kills |
+
+## Files
+
+```
+pi-deadman/
+├── extensions/
+│   ├── index.ts          — Entry point: tool_call gate, /deadman command
+│   ├── monitor.ts        — Background polling, adaptive intervals, watchdog
+│   ├── canary.ts         — Performance micro-ops timing
+│   ├── signals.ts        — macOS kernel metrics (sysctl, vm_stat)
+│   ├── zones.ts          — Zone classification (GREEN/YELLOW/ORANGE/RED)
+│   ├── calibration.ts    — Baseline persistence
+│   ├── keywords.ts       — Command tier classification (25+ keywords, 5 tiers)
+│   ├── processes.ts      — System-wide process list (footprint.py)
+│   ├── watchdog.ts       — Kill target selection
+│   ├── tree.ts           — Snapshot diffing, growth detection, swarm detection
+│   ├── worker.ts         — Persistent Python worker for fast footprint queries
+│   └── logging.ts        — JSONL structured logs (GC after 3 days)
+├── helpers/
+│   ├── footprint.py        — proc_pid_rusage footprint extraction
+│   └── footprint_worker.py — Persistent worker process
+└── __tests__/              — 202 tests across 13 files
+```
+
+## Logs
+
+Stored in `~/.pi/deadman/logs/`:
+
+- `system.jsonl` — zone, canary, swap, signals per poll
+- `decisions.jsonl` — pass/block/kill per tool call
+- `processes.jsonl` — top process snapshots
+- `tool_impact.jsonl` — swap delta per command
+
+## Development
+
+```bash
+cd pi-deadman
+npm install
+npm test              # 202 tests across 13 files
+npx vitest --watch    # watch mode
+```
+
+## License
+
+MIT

package/__tests__/calibration.test.ts

@@ -0,0 +1,73 @@
+// __tests__/calibration.test.ts
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { saveBaseline, loadBaseline, type Baseline, DEFAULT_BASELINE_MS } from "../extensions/calibration";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+describe("Baseline persistence", () => {
+  let tmpDir: string;
+  let baselinePath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "deadman-test-"));
+    baselinePath = path.join(tmpDir, "baseline.json");
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("saves and loads a baseline", () => {
+    const baseline: Baseline = {
+      canary_ms: 7.5,
+      calibrated_at: "2026-02-28T10:00:00.000Z",
+      source: "calibrated",
+    };
+    saveBaseline(baseline, baselinePath);
+    const loaded = loadBaseline(baselinePath);
+    expect(loaded).toEqual(baseline);
+  });
+
+  it("returns null for missing file", () => {
+    expect(loadBaseline("/nonexistent/path/baseline.json")).toBeNull();
+  });
+
+  it("returns null for corrupted JSON", () => {
+    fs.writeFileSync(baselinePath, "not json{{{");
+    expect(loadBaseline(baselinePath)).toBeNull();
+  });
+
+  it("returns null for incomplete data", () => {
+    fs.writeFileSync(baselinePath, JSON.stringify({ canary_ms: 5 }));
+    expect(loadBaseline(baselinePath)).toBeNull();
+  });
+
+  it("creates parent directories if needed", () => {
+    const deepPath = path.join(tmpDir, "a", "b", "c", "baseline.json");
+    const baseline: Baseline = {
+      canary_ms: 8.0,
+      calibrated_at: "2026-02-28T10:00:00.000Z",
+      source: "calibrated",
+    };
+    saveBaseline(baseline, deepPath);
+    const loaded = loadBaseline(deepPath);
+    expect(loaded).toEqual(baseline);
+  });
+
+  it("default baseline backward-compatible with missing source field", () => {
+    fs.writeFileSync(baselinePath, JSON.stringify({
+      canary_ms: 9.0,
+      calibrated_at: "2026-02-28T10:00:00.000Z",
+    }));
+    const loaded = loadBaseline(baselinePath);
+    expect(loaded).not.toBeNull();
+    expect(loaded!.source).toBe("calibrated");
+  });
+});
+
+describe("DEFAULT_BASELINE_MS", () => {
+  it("is 10ms (conservative default)", () => {
+    expect(DEFAULT_BASELINE_MS).toBe(10.0);
+  });
+});

package/__tests__/canary.test.ts

@@ -0,0 +1,68 @@
+// __tests__/canary.test.ts
+import { describe, it, expect } from "vitest";
+import { runCanary, type CanaryResult } from "../extensions/canary";
+
+describe("runCanary", () => {
+  it("returns a CanaryResult with all 5 sub-timings", async () => {
+    const result = await runCanary();
+    expect(result).toHaveProperty("sysctl_ms");
+    expect(result).toHaveProperty("spawn_ms");
+    expect(result).toHaveProperty("read_ms");
+    expect(result).toHaveProperty("dir_ms");
+    expect(result).toHaveProperty("alloc_ms");
+    expect(result).toHaveProperty("total_ms");
+  });
+
+  it("all timings are positive numbers", async () => {
+    const result = await runCanary();
+    expect(result.sysctl_ms).toBeGreaterThan(0);
+    expect(result.spawn_ms).toBeGreaterThan(0);
+    expect(result.read_ms).toBeGreaterThan(0);
+    expect(result.dir_ms).toBeGreaterThan(0);
+    expect(result.alloc_ms).toBeGreaterThan(0);
+    expect(result.total_ms).toBeGreaterThan(0);
+  });
+
+  it("total_ms equals sum of 5 sub-timings", async () => {
+    const result = await runCanary();
+    const sum = result.sysctl_ms + result.spawn_ms + result.read_ms + result.dir_ms + result.alloc_ms;
+    expect(result.total_ms).toBeCloseTo(sum, 1);
+  });
+
+  it("completes in under 500ms on a healthy system", async () => {
+    const result = await runCanary();
+    expect(result.total_ms).toBeLessThan(500);
+  });
+
+  it("sysctl_ms reads kern.ostype successfully", async () => {
+    const result = await runCanary();
+    expect(result.sysctl_ms).toBeLessThan(50);
+  });
+
+  it("spawn_ms spawns a real process", async () => {
+    const result = await runCanary();
+    expect(result.spawn_ms).toBeLessThan(100);
+  });
+
+  it("read_ms reads a real file", async () => {
+    const result = await runCanary();
+    expect(result.read_ms).toBeLessThan(50);
+  });
+
+  it("dir_ms scans a real directory", async () => {
+    const result = await runCanary();
+    expect(result.dir_ms).toBeLessThan(50);
+  });
+
+  it("alloc_ms allocates and fills memory", async () => {
+    const result = await runCanary();
+    expect(result.alloc_ms).toBeLessThan(50);
+  });
+
+  it("is deterministic-ish — two runs produce similar results", async () => {
+    const r1 = await runCanary();
+    const r2 = await runCanary();
+    expect(r2.total_ms).toBeLessThan(r1.total_ms * 5);
+    expect(r1.total_ms).toBeLessThan(r2.total_ms * 5);
+  });
+});

package/__tests__/fast-watchdog.test.ts

@@ -0,0 +1,188 @@
+// __tests__/fast-watchdog.test.ts — integration test for the fast watchdog loop
+// Spawns a real child process, seeds growth evidence, forces RED, verifies kill
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { Monitor } from "../extensions/monitor";
+import { Zone } from "../extensions/zones";
+import { spawn, type ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+describe("Fast Watchdog Integration", () => {
+  let tmpDir: string;
+  let baselinePath: string;
+  let logDir: string;
+  let monitor: Monitor;
+  let childProc: ChildProcess | null = null;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "deadman-watchdog-int-"));
+    baselinePath = path.join(tmpDir, "baseline.json");
+    logDir = path.join(tmpDir, "logs");
+
+    fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
+    fs.writeFileSync(baselinePath, JSON.stringify({
+      canary_ms: 5.0,
+      calibrated_at: new Date().toISOString(),
+      source: "test",
+    }));
+
+    monitor = new Monitor({ baselinePath, logDir });
+  });
+
+  afterEach(() => {
+    monitor.stop();
+    if (childProc && !childProc.killed) {
+      childProc.kill("SIGKILL");
+    }
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Seed the watchdog's snapshot history with fake growth data for a PID.
+   * This simulates the monitor having observed the process growing over time.
+   */
+  function seedGrowthHistory(pid: number, name: string) {
+    const state = monitor.getWatchdogState();
+    state.snapshotHistory = [
+      [{ pid, name, footprint_mb: 200, age_seconds: 10 }],
+      [{ pid, name, footprint_mb: 400, age_seconds: 15 }],
+      [{ pid, name, footprint_mb: 600, age_seconds: 20 }],
+      [{ pid, name, footprint_mb: 800, age_seconds: 25 }],
+    ];
+  }
+
+  it("kills a growing child process within 6 seconds of confirmed RED", async () => {
+    childProc = spawn("sleep", ["60"], { stdio: "ignore" });
+    const childPid = childProc.pid!;
+    expect(childPid).toBeGreaterThan(0);
+
+    const kills: any[] = [];
+    monitor.onAutoKill((decision) => {
+      kills.push(decision);
+    });
+
+    monitor.start();
+    await new Promise(r => setTimeout(r, 1500));
+
+    // Seed growth evidence for the child — simulates monitor having tracked it
+    seedGrowthHistory(childPid, "sleep");
+
+    // Force RED confirmed
+    monitor._forceZone(Zone.RED, true);
+
+    // Wait up to 6 seconds for the fast watchdog to fire
+    const deadline = Date.now() + 6000;
+    while (Date.now() < deadline) {
+      await new Promise(r => setTimeout(r, 200));
+      try {
+        process.kill(childPid, 0);
+      } catch {
+        break;
+      }
+    }
+
+    let alive = true;
+    try {
+      process.kill(childPid, 0);
+    } catch {
+      alive = false;
+    }
+
+    expect(alive).toBe(false);
+    expect(kills.length).toBeGreaterThanOrEqual(1);
+    expect(kills[0].targets.some((t: any) => t.pid === childPid)).toBe(true);
+
+    // Verify decision log
+    const decisionsPath = path.join(logDir, "decisions.jsonl");
+    expect(fs.existsSync(decisionsPath)).toBe(true);
+    const entries = fs.readFileSync(decisionsPath, "utf-8").trim().split("\n").map(l => JSON.parse(l));
+    const killEntry = entries.find((e: any) => e.action === "auto_kill_fast");
+    expect(killEntry).toBeDefined();
+    expect(killEntry.targets.some((t: any) => t.pid === childPid)).toBe(true);
+  });
+
+  it("does NOT kill when zone is GREEN even with growth evidence", async () => {
+    childProc = spawn("sleep", ["60"], { stdio: "ignore" });
+    const childPid = childProc.pid!;
+
+    const kills: any[] = [];
+    monitor.onAutoKill((decision) => {
+      kills.push(decision);
+    });
+
+    monitor.start();
+    await new Promise(r => setTimeout(r, 200));
+
+    seedGrowthHistory(childPid, "sleep");
+
+    // Zone stays GREEN
+    expect(monitor.currentZone).toBe(Zone.GREEN);
+
+    await new Promise(r => setTimeout(r, 3000));
+
+    let alive = true;
+    try {
+      process.kill(childPid, 0);
+    } catch {
+      alive = false;
+    }
+    expect(alive).toBe(true);
+    expect(kills).toHaveLength(0);
+  });
+
+  it("kills newest process in RED even without growth evidence", async () => {
+    // The "newest" filter catches processes that appeared after the last
+    // non-RED snapshot. Since the child spawned during warm-up (when system
+    // was GREEN), forcing RED should trigger "newest" detection.
+    // We seed a cached snapshot with non-zero footprint so the process
+    // passes the footprint_mb > 0 guard (0 MB processes are infrastructure noise).
+    childProc = spawn("sleep", ["60"], { stdio: "ignore" });
+    const childPid = childProc.pid!;
+
+    const kills: any[] = [];
+    monitor.onAutoKill((decision) => {
+      kills.push(decision);
+    });
+
+    monitor.start();
+    await new Promise(r => setTimeout(r, 1500));
+
+    // Seed a single snapshot with meaningful footprint (no growth pattern,
+    // just proves the process exists with real memory usage).
+    // Also set lastNonRedTimestamp explicitly — with hysteresis, the warm-up
+    // period (1.5s) isn't long enough for 3 consecutive non-RED polls.
+    const state = monitor.getWatchdogState();
+    state.snapshotHistory = [
+      [{ pid: childPid, name: "sleep", footprint_mb: 150, age_seconds: 3 }],
+    ];
+    state.lastNonRedTimestamp = Date.now() / 1000 - 5; // system was healthy 5s ago
+
+    monitor._forceZone(Zone.RED, true);
+
+    // Wait for the fast watchdog to fire
+    const deadline = Date.now() + 6000;
+    while (Date.now() < deadline) {
+      await new Promise(r => setTimeout(r, 200));
+      try {
+        process.kill(childPid, 0);
+      } catch {
+        break;
+      }
+    }
+
+    let alive = true;
+    try {
+      process.kill(childPid, 0);
+    } catch {
+      alive = false;
+    }
+    expect(alive).toBe(false);
+    expect(kills.length).toBeGreaterThanOrEqual(1);
+  });
+
+  // Cooldown is tested at the unit level in watchdog.test.ts.
+  // Integration testing cooldown with real processes is timing-sensitive
+  // and flaky — the unit test covers the logic reliably.
+});

package/__tests__/index.test.ts

@@ -0,0 +1,103 @@
+// __tests__/index.test.ts
+import { describe, it, expect } from "vitest";
+import {
+  buildBlockReason,
+  getQuickMemorySnapshot,
+  buildProcessOptions,
+} from "../extensions/index";
+import { Zone } from "../extensions/zones";
+import type { SnapshotProcess } from "../extensions/tree";
+
+describe("buildBlockReason", () => {
+  it("includes zone in the message", () => {
+    const reason = buildBlockReason(Zone.RED, "npm install", 3);
+    expect(reason).toContain("RED");
+  });
+
+  it("includes the command in the message", () => {
+    const reason = buildBlockReason(Zone.ORANGE, "docker build .", 3);
+    expect(reason).toContain("docker build .");
+  });
+
+  it("includes tier context for ORANGE + tier 3", () => {
+    const reason = buildBlockReason(Zone.ORANGE, "npm run build", 3);
+    expect(reason).toContain("heavy");
+  });
+
+  it("RED blocks everything — message reflects that", () => {
+    const reason = buildBlockReason(Zone.RED, "cat file.txt", 0);
+    expect(reason).toContain("RED");
+    expect(reason).toContain("critical");
+  });
+
+  it("ORANGE message suggests freeing memory", () => {
+    const reason = buildBlockReason(Zone.ORANGE, "npm install", 3);
+    expect(reason).toContain("Free memory");
+  });
+
+  it("RED message mentions close applications", () => {
+    const reason = buildBlockReason(Zone.RED, "ls", 1);
+    expect(reason).toContain("close applications");
+  });
+});
+
+describe("getQuickMemorySnapshot", () => {
+  it("returns swap_used_mb and memorystatus_level", async () => {
+    const snap = await getQuickMemorySnapshot();
+    expect(snap).toHaveProperty("swap_used_mb");
+    expect(snap).toHaveProperty("memorystatus_level");
+    expect(typeof snap.swap_used_mb).toBe("number");
+    expect(typeof snap.memorystatus_level).toBe("number");
+  });
+});
+
+describe("buildProcessOptions", () => {
+  it("returns pi children first, sorted by footprint descending", () => {
+    const piChildren: SnapshotProcess[] = [
+      { pid: 1, name: "node", footprint_mb: 100, age_seconds: 10 },
+      { pid: 2, name: "python3", footprint_mb: 300, age_seconds: 20 },
+      { pid: 3, name: "bash", footprint_mb: 50, age_seconds: 5 },
+    ];
+    const options = buildProcessOptions(piChildren, 5);
+    // Should be sorted: python3 (300), node (100), bash (50)
+    expect(options.length).toBeGreaterThanOrEqual(3);
+    expect(options[0]).toContain("python3");
+    expect(options[0]).toContain("300");
+    expect(options[1]).toContain("node");
+  });
+
+  it("limits to top N", () => {
+    const piChildren: SnapshotProcess[] = [
+      { pid: 1, name: "a", footprint_mb: 100, age_seconds: 10 },
+      { pid: 2, name: "b", footprint_mb: 200, age_seconds: 20 },
+      { pid: 3, name: "c", footprint_mb: 300, age_seconds: 30 },
+    ];
+    const options = buildProcessOptions(piChildren, 2);
+    // 2 process options + "Kill an external app"
+    expect(options.filter(o => !o.startsWith("Kill an external"))).toHaveLength(2);
+  });
+
+  it("includes 'Kill an external app' as last option", () => {
+    const piChildren: SnapshotProcess[] = [
+      { pid: 1, name: "node", footprint_mb: 100, age_seconds: 10 },
+    ];
+    const options = buildProcessOptions(piChildren, 5);
+    expect(options[options.length - 1]).toContain("external");
+  });
+
+  it("shows only 'Kill an external app' when no pi children", () => {
+    const options = buildProcessOptions([], 5);
+    expect(options).toHaveLength(1);
+    expect(options[0]).toContain("external");
+  });
+
+  it("uses natural language descriptions with name, MB, and age", () => {
+    const piChildren: SnapshotProcess[] = [
+      { pid: 1, name: "npm", footprint_mb: 340, age_seconds: 12 },
+    ];
+    const options = buildProcessOptions(piChildren, 5);
+    expect(options[0]).toContain("npm");
+    expect(options[0]).toContain("340");
+    expect(options[0]).toContain("12s");
+  });
+});

package/__tests__/keywords.test.ts

@@ -0,0 +1,130 @@
+// __tests__/keywords.test.ts
+import { describe, it, expect } from "vitest";
+import { classifyTier, KEYWORD_TIERS } from "../extensions/keywords";
+
+describe("classifyTier", () => {
+  // Tier 4 — Destructive
+  it("classifies 'kill -9 1234' as tier 4", () => {
+    expect(classifyTier("kill -9 1234")).toBe(4);
+  });
+  it("classifies 'pkill node' as tier 4", () => {
+    expect(classifyTier("pkill node")).toBe(4);
+  });
+  it("classifies 'killall Safari' as tier 4", () => {
+    expect(classifyTier("killall Safari")).toBe(4);
+  });
+  it("classifies 'rm -rf /tmp/stuff' as tier 4", () => {
+    expect(classifyTier("rm -rf /tmp/stuff")).toBe(4);
+  });
+
+  // Tier 3 — Heavy
+  it("classifies 'npm install react' as tier 3", () => {
+    expect(classifyTier("npm install react")).toBe(3);
+  });
+  it("classifies 'docker build .' as tier 3", () => {
+    expect(classifyTier("docker build .")).toBe(3);
+  });
+  it("classifies 'npm run build' as tier 3", () => {
+    expect(classifyTier("npm run build")).toBe(3);
+  });
+  it("classifies 'webpack --mode production' as tier 3", () => {
+    expect(classifyTier("webpack --mode production")).toBe(3);
+  });
+  it("classifies 'cargo build --release' as tier 3", () => {
+    expect(classifyTier("cargo build --release")).toBe(3);
+  });
+  it("classifies 'brew install node' as tier 3", () => {
+    expect(classifyTier("brew install node")).toBe(3);
+  });
+  it("classifies 'pip install -r requirements.txt' as tier 3", () => {
+    expect(classifyTier("pip install -r requirements.txt")).toBe(3);
+  });
+  it("classifies 'make all' as tier 3", () => {
+    expect(classifyTier("make all")).toBe(3);
+  });
+
+  // Tier 2 — Medium
+  it("classifies 'pytest tests/' as tier 2", () => {
+    expect(classifyTier("pytest tests/")).toBe(2);
+  });
+  it("classifies 'npx jest --watch' as tier 2", () => {
+    expect(classifyTier("npx jest --watch")).toBe(2);
+  });
+  it("classifies 'npx vitest run' as tier 2", () => {
+    expect(classifyTier("npx vitest run")).toBe(2);
+  });
+  it("classifies 'uvicorn app:main' as tier 2", () => {
+    expect(classifyTier("uvicorn app:main")).toBe(2);
+  });
+  it("classifies 'node server.js' as tier 2", () => {
+    expect(classifyTier("node server.js")).toBe(2);
+  });
+  it("classifies 'cargo test' as tier 2", () => {
+    expect(classifyTier("cargo test")).toBe(2);
+  });
+
+  // Tier 1 — Light
+  it("classifies 'git status' as tier 1", () => {
+    expect(classifyTier("git status")).toBe(1);
+  });
+  it("classifies 'grep -r TODO src/' as tier 1", () => {
+    expect(classifyTier("grep -r TODO src/")).toBe(1);
+  });
+  it("classifies 'curl https://api.example.com' as tier 1", () => {
+    expect(classifyTier("curl https://api.example.com")).toBe(1);
+  });
+  it("classifies 'cat file.txt' as tier 1", () => {
+    expect(classifyTier("cat file.txt")).toBe(1);
+  });
+  it("classifies 'ls -la' as tier 1", () => {
+    expect(classifyTier("ls -la")).toBe(1);
+  });
+  it("classifies 'rg pattern .' as tier 1", () => {
+    expect(classifyTier("rg pattern .")).toBe(1);
+  });
+
+  // Tier 0 — Unknown / trivial
+  it("classifies unknown commands as tier 0", () => {
+    expect(classifyTier("whoami")).toBe(0);
+  });
+  it("classifies empty string as tier 0", () => {
+    expect(classifyTier("")).toBe(0);
+  });
+  it("classifies undefined as tier 0", () => {
+    expect(classifyTier(undefined)).toBe(0);
+  });
+
+  // Highest tier wins
+  it("takes highest tier when multiple keywords match", () => {
+    expect(classifyTier("npm install && pytest")).toBe(3);
+  });
+  it("npm install && cat → tier 3 (install wins)", () => {
+    expect(classifyTier("npm install && cat package.json")).toBe(3);
+  });
+
+  // Known false positive — documented, safe failure mode
+  it("cat package.json matches 'package' → tier 3 (known false positive)", () => {
+    expect(classifyTier("cat package.json")).toBe(3);
+  });
+
+  // Case insensitive
+  it("is case insensitive", () => {
+    expect(classifyTier("NPM INSTALL")).toBe(3);
+    expect(classifyTier("Docker Build")).toBe(3);
+  });
+});
+
+describe("KEYWORD_TIERS", () => {
+  it("has entries for all 5 tiers", () => {
+    const tiers = new Set(Object.values(KEYWORD_TIERS));
+    expect(tiers).toContain(0);
+    expect(tiers).toContain(1);
+    expect(tiers).toContain(2);
+    expect(tiers).toContain(3);
+    expect(tiers).toContain(4);
+  });
+
+  it("has at least 20 keywords", () => {
+    expect(Object.keys(KEYWORD_TIERS).length).toBeGreaterThanOrEqual(20);
+  });
+});