pi-deadman 1.1.0 → 1.2.0

package/README.md

@@ -28,6 +28,36 @@ On first run, it calibrates a baseline for your machine (~10 seconds). After tha
 |---|---|
 | `/deadman` | Show current zone and memory stats |
 
+## Security & System Calls
+
+pi-deadman makes **no network requests** and reads **no environment variables**. All system access is local and documented here:
+
+**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 |
+
+**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

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,6 +1,6 @@
 {
   "name": "pi-deadman",
-  "version": "1.1.0",
+  "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": [