pi-deadman 1.0.0 → 1.2.0

package/README.md

@@ -4,105 +4,65 @@ 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.
+**Zones** — Polls system health and classifies into GREEN, YELLOW, ORANGE, or RED based on memory pressure signals.
 
-### Background Monitor
+**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.
 
-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.
+**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 |
+| `/deadman` | Show current zone and memory stats |
 
-## 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
-```
+## Security & System Calls
 
-## Logs
+pi-deadman makes **no network requests** and reads **no environment variables**. All system access is local and documented here:
 
-Stored in `~/.pi/deadman/logs/`:
+**Shell commands** (all read-only queries, no mutations):
+| Command | File | Purpose |
+|---|---|---|
+| `sysctl -n kern.ostype` | canary.ts | Canary timing benchmark |
+| `/usr/bin/true` | canary.ts | Canary timing benchmark |
+| `sysctl -n vm.swapusage` | signals.ts | Read swap usage stats |
+| `sysctl -n kern.memorystatus_vm_pressure_level` | signals.ts | Read memory pressure level |
+| `sysctl -n kern.memorystatus_level` | signals.ts | Read memorystatus level |
+| `vm_stat` | signals.ts | Read VM page statistics |
+| `ps -eo pid,rss,comm -r` | processes.ts | List processes by memory |
+| `ps -eo pid,ppid,etime,comm` | monitor.ts | Process tree for watchdog |
+| `python3 helpers/footprint.py` | processes.ts | Read process footprints via `proc_pid_rusage` |
+| `python3 helpers/footprint_worker.py` | worker.ts | Persistent worker for fast footprint queries |
+
+**Process kills** (only pi's own child processes, only in confirmed RED):
+| Signal | File | Trigger |
+|---|---|---|
+| `SIGKILL` | monitor.ts | Watchdog auto-kill in confirmed RED zone |
+| `SIGTERM` | processes.ts | User-initiated kill from interactive menu |
 
-- `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
+**Filesystem writes** (scoped to `~/.pi/deadman/` only):
+| What | File | Purpose |
+|---|---|---|
+| `~/.pi/deadman/baseline.json` | calibration.ts | Persisted canary baseline |
+| `~/.pi/deadman/logs/*.jsonl` | logging.ts | Structured decision/system logs (auto-GC after 3 days) |
 
 ## Development
 
 ```bash
-cd pi-deadman
 npm install
-npm test              # 202 tests across 13 files
-npx vitest --watch    # watch mode
+npm test
 ```
 
 ## License

package/extensions/canary.ts

@@ -1,6 +1,7 @@
 // canary.ts — 5 micro-operations timed in sequence for system degradation detection
 import { execSync, spawnSync } from 'child_process';
 import { readFileSync, readdirSync } from 'fs';
+import { fileURLToPath } from 'url';
 
 export interface CanaryResult {
   sysctl_ms: number;
@@ -22,9 +23,9 @@ export async function runCanary(): Promise<CanaryResult> {
   spawnSync('/usr/bin/true');
   const spawn_ms = performance.now() - spawn_start;
 
-  // read_ms: Read `/etc/hosts` via `fs.readFileSync` and time it
+  // read_ms: Read this file as a disk I/O benchmark
   const read_start = performance.now();
-  readFileSync('/etc/hosts');
+  readFileSync(fileURLToPath(import.meta.url));
   const read_ms = performance.now() - read_start;
 
   // dir_ms: Read `/tmp` directory via `fs.readdirSync` and time it

package/extensions/monitor.ts

@@ -251,6 +251,7 @@ export class Monitor {
           );
 
           if (decision) {
+            // Auto-kill: SIGKILL pi's own child processes in confirmed RED zone
             for (const target of decision.targets) {
               try {
                 process.kill(target.pid, "SIGKILL");
@@ -411,6 +412,7 @@ export class Monitor {
       );
 
       if (decision) {
+        // Fast watchdog auto-kill: SIGKILL pi's child processes in confirmed RED
         for (const target of decision.targets) {
           try {
             process.kill(target.pid, "SIGKILL");

package/extensions/processes.ts

@@ -84,6 +84,7 @@ export function formatProcessList(processes: ProcessInfo[], limit: number): stri
     .map(proc => `${proc.name} (PID ${proc.pid}) — ${proc.footprint_mb} MB`);
 }
 
+// User-initiated kill from interactive menu — graceful SIGTERM
 export function killProcess(pid: number): boolean {
   try {
     process.kill(pid, "SIGTERM");

package/extensions/signals.ts

@@ -76,6 +76,7 @@ export async function collectSignals(): Promise<SystemSignals> {
   };
 }
 
+// Read macOS virtual memory page statistics (pages paged in/out, compressed, etc.)
 function getVmStat(): Record<string, number> {
   try {
     const output = execSync("vm_stat", { encoding: "utf8", timeout: 5000 });
@@ -98,6 +99,7 @@ function getVmStat(): Record<string, number> {
   }
 }
 
+// Read macOS memory pressure level: 1=normal, 2=warn, 4=critical
 function getPressureLevel(): number {
   try {
     const output = execSync("sysctl -n kern.memorystatus_vm_pressure_level", { 
@@ -114,6 +116,7 @@ function getPressureLevel(): number {
   }
 }
 
+// Read macOS memorystatus percentage (0-100, higher = more available)
 function getMemorystatusLevel(): number {
   try {
     const output = execSync("sysctl -n kern.memorystatus_level", { 
@@ -127,6 +130,7 @@ function getMemorystatusLevel(): number {
   }
 }
 
+// Read macOS swap usage: total and used bytes
 function getSwapUsage(): [number, number] {
   try {
     const output = execSync("sysctl -n vm.swapusage", { 

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.2.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.
-});