pi-deadman 1.0.0 → 1.1.0

package/README.md

@@ -4,105 +4,35 @@ 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
+pi install npm: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.
+On first run, it calibrates a baseline for your machine (~10 seconds). 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)
+**Zones** — Polls system health and classifies into GREEN, YELLOW, ORANGE, or RED based on memory pressure signals.
 
-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.
+**Gate** — Every `bash` tool call is checked against the current zone. Light commands always pass; heavy operations (builds, installs, docker) are blocked in ORANGE and RED.
 
-| 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.
+**Watchdog** — In confirmed RED, automatically identifies and kills the process most likely causing the pressure. Runs independently so it works even when the system is 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
+| `/deadman` | Show current zone and memory stats |
 
 ## Development
 
 ```bash
-cd pi-deadman
 npm install
-npm test              # 202 tests across 13 files
-npx vitest --watch    # watch mode
+npm test
 ```
 
 ## License

package/package.json

@@ -1,24 +1,32 @@
 {
   "name": "pi-deadman",
-  "version": "1.0.0",
-  "description": "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.",
+  "version": "1.1.0",
+  "description": "Dead man's switch for AI coding agents — monitors memory pressure, gates heavy operations, and kills runaway processes.",
   "type": "module",
-  "keywords": ["pi-package", "memory", "macos", "watchdog", "system-health", "deadman"],
+  "keywords": [
+    "pi-package",
+    "memory",
+    "macos",
+    "watchdog",
+    "system-health",
+    "deadman"
+  ],
   "pi": {
-    "extensions": ["./extensions/index.ts"]
+    "extensions": [
+      "./extensions/index.ts"
+    ]
   },
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "vitest": "^3.0.0",
     "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   },
-  "dependencies": {
-    "@sinclair/typebox": "^0.34.0"
-  },
-  "os": ["darwin"],
+  "os": [
+    "darwin"
+  ],
   "license": "MIT"
 }

package/__tests__/calibration.test.ts

@@ -1,73 +0,0 @@
-// __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

@@ -1,68 +0,0 @@
-// __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

@@ -1,188 +0,0 @@
-// __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

@@ -1,103 +0,0 @@
-// __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");
-  });
-});