Skip to content

v0.1.8

Choose a tag to compare

View all tags
@github-actions github-actions released this 31 Jan 22:12
· 145 commits to main since this release
v0.1.8
d63bc72

sysprims v0.1.8

Release Date: 2026-01-29
Status: CLI Tree Termination Release

Summary

This release adds the terminate-tree CLI subcommand for safe, structured termination of existing process trees. Combined with enhanced pstat sampling modes, sysprims now provides a complete workflow for diagnosing and cleaning up runaway processes without GPL-licensed utilities.

Highlights

  • sysprims terminate-tree: Terminate process trees with graceful-then-kill escalation
  • PID Reuse Protection: --require-start-time-ms and --require-exe-path identity guards
  • CLI Safety: Refuses to terminate PID 1, self, or parent without --force
  • pstat Sampling: --sample and --top flags for CPU investigation
  • Documentation: Real-world guide for runaway process diagnosis

New CLI Commands

sysprims terminate-tree

Terminate an existing process tree by PID. This wraps the terminate_tree() library function (added in v0.1.6) with CLI-specific safety guards.

sysprims terminate-tree <PID> [OPTIONS]

Basic Usage

# Terminate process tree rooted at PID 26021
sysprims terminate-tree 26021

# With JSON output for automation
sysprims terminate-tree 26021 --json

PID Reuse Protection (Recommended)

When automating process termination, use identity guards to ensure you're killing the right process:

sysprims terminate-tree 26021 \
  --require-exe-path "/Applications/VSCodium.app/Contents/MacOS/Electron" \
  --require-start-time-ms 1769432792261 \
  --json

If the current process at PID 26021 doesn't match the specified identity, the command fails safely.

Options Reference

Option Default Description
--grace <DURATION> 5s Grace period before escalation
--kill-after <DURATION> 10s Time to wait before sending kill signal
--signal <SIGNAL> TERM Signal for grace period
--kill-signal <SIGNAL> KILL Signal for forced termination
--require-start-time-ms <MS> - Refuse if PID start time doesn't match
--require-exe-path <PATH> - Refuse if PID exe path doesn't match
--force false Override safety checks
--json false Output as JSON

Output Schema

{
  "schema_id": "https://schemas.3leaps.dev/sysprims/process/v1.0.0/terminate-tree-result.schema.json",
  "timestamp": "2026-01-29T21:23:07.677021Z",
  "platform": "macos",
  "pid": 26021,
  "pgid": 26021,
  "signal_sent": 15,
  "escalated": false,
  "exited": true,
  "timed_out": false,
  "tree_kill_reliability": "guaranteed",
  "warnings": []
}
Field Description
signal_sent Signal number used (15=SIGTERM, 9=SIGKILL)
escalated Whether SIGKILL was needed after grace period
exited Process terminated successfully
tree_kill_reliability "guaranteed" if PGID kill was used
warnings Any edge cases encountered

CLI Safety Guards

The CLI includes interactive safety checks that refuse to proceed without --force:

  • PID 1 (init/launchd): System stability risk
  • Self: Would terminate the sysprims process
  • Parent: Would terminate the calling shell/process

These are CLI-specific protections. The underlying library allows these operations for controlled automation scenarios that may legitimately need them.

pstat Sampling Enhancements

New flags for real-time CPU investigation:

# Sample CPU over 250ms interval, show top 5
sysprims pstat --sample 250ms --top 5 --sort cpu --table

# Find VSCodium helpers with >50% CPU (sampled)
sysprims pstat --name "VSCodium Helper" --sample 500ms --cpu-above 50 --json
New Option Description
--sample <DURATION> Compute CPU rate over sampling interval
--top <N> Limit output to top N processes (after filtering)

Without --sample, cpu_percent is a lifetime average which may not reflect current activity. With --sample, you get near-instantaneous CPU usage similar to Activity Monitor.

Surgical vs Tree Termination

This release documents two strategies for handling runaway processes:

Option A: Surgical Strike (Try First)

Kill individual runaway processes while preserving the parent application:

sysprims kill 8436 -s TERM

If SIGTERM is ignored (common with runaway Electron/Node processes):

sysprims kill 8436 -s KILL

Benefits:

  • Preserves parent application windows
  • Minimal disruption
  • No respawn observed in testing

Option B: Tree Termination (If Surgical Fails)

If processes respawn or too many are affected:

sysprims terminate-tree 26021 --require-exe-path "..."

Trade-offs:

  • Terminates parent and ALL descendants
  • Closes all windows managed by that process
  • Guaranteed cleanup

Documentation

New Guide: Runaway Process Diagnosis

docs/guides/runaway-process-diagnosis.md provides a real-world walkthrough:

  1. Finding high-CPU processes with pstat --sample --cpu-above
  2. Identifying process relationships via ppid inspection
  3. Deciding on termination scope (surgical vs tree)
  4. Verifying termination completed successfully
  5. TypeScript library examples for automation

The guide uses a real scenario: nine VSCodium Helper (Plugin) processes consuming 95%+ CPU each, caused by a runaway extension.

Library vs CLI Protections

Protection Library CLI
PID 0 rejected Yes Yes (via library)
PID > MAX_SAFE_PID rejected Yes Yes (via library)
Don't group-kill own PGID Yes Yes (via library)
Refuse PID 1 No Yes (requires --force)
Refuse self No Yes (requires --force)
Refuse parent No Yes (requires --force)

The library provides safety against dangerous POSIX semantics. The CLI adds interactive footgun protections for common mistakes.

Migration Guide

For CLI Users

No breaking changes. The terminate-tree subcommand is additive.

If you were using sysprims timeout solely for tree termination of external processes, you can now use terminate-tree directly:

# Before: awkward workaround
sysprims timeout --pid-file /tmp/pid 0s -- sleep infinity &
# ... then read PID and terminate

# After: direct tree termination
sysprims terminate-tree <PID>

For Library Users

No changes required. The CLI wraps existing sysprims_timeout::terminate_tree().

Platform Support

Platform terminate-tree pstat --sample
Linux x64 (glibc) Yes Yes
Linux x64 (musl) Yes Yes
Linux arm64 (glibc) Yes Yes
Linux arm64 (musl) Yes Yes
macOS arm64 Yes Yes
Windows x64 Yes Yes
Windows arm64 Yes Yes

Known Limitations

  • Workspace identification: Determining which IDE window a child process belongs to requires OS tools (lsof on Unix). Future releases will add sysprims fds for self-contained investigation.
  • SIGTERM may be ignored: Runaway Electron/Node processes sometimes ignore SIGTERM. The guide documents escalation to SIGKILL.

Coming in v0.1.9

  • sysprims fds: Open file descriptor inspection (Linux/macOS first; Windows NotSupported)
  • Multi-PID kill: sysprims kill <PID> <PID> ... batch operations

Verification

Verify this release with the signed checksums:

# Download release and verification files
curl -LO https://github.com/3leaps/sysprims/releases/download/v0.1.8/SHA256SUMS
curl -LO https://github.com/3leaps/sysprims/releases/download/v0.1.8/SHA256SUMS.minisig
curl -LO https://github.com/3leaps/sysprims/releases/download/v0.1.8/sysprims-minisign.pub

# Verify signature
minisign -Vm SHA256SUMS -p sysprims-minisign.pub

# Verify checksums
shasum -a 256 -c SHA256SUMS --ignore-missing

Changes

Added

  • CLI: sysprims terminate-tree - tree termination for existing processes

    • --require-start-time-ms, --require-exe-path for PID reuse protection
    • --grace, --kill-after, --signal, --kill-signal timing/signal options
    • --force to override CLI safety guards
    • --json for machine-readable output

  • CLI: pstat sampling mode

    • --sample <DURATION> for CPU sampling over interval
    • --top <N> for limiting output

  • Documentation

    • docs/guides/runaway-process-diagnosis.md - real-world investigation guide
Assets 24
Loading