v0.1.15

v0.1.15 - Guard Automation & Provenance

Release Date: TBD
Status: Draft

Summary

v0.1.15 turns the recurring VSCodium runaway-plugin incident into a first-class sysprims workflow.
The release adds a reusable one-shot guard primitive, subtree-aware remediation, a managed guard
loop for long-lived watchdogs, a new ancestors surface for provenance, and operational guard
controls for background execution and discovery.

Highlights

• GuardStep: one-shot guard evaluation and optional remediation across Rust, FFI, Go, and
  TypeScript.
• Cascade remediation: kill-descendants --cascade and guard actions can expand each matched
  offender to its subtree so cleanup does not leave child work behind.
• GuardRunner: managed long-running guard loop with drift-resistant scheduling and clean stop
  semantics.
• Ancestors provenance: new ancestors APIs across Rust, CLI, FFI, Go, and TypeScript for
  answering "what spawned this?"
• Daemonized guard operations: sysprims guard now supports --daemon, --pidfile,
  --status, and --stop on Unix.
• Self-discovery: running guards are discoverable through sysprims itself via normalized
  sysprims-guard:<root_pid> naming.
• Shared runtime primitives: Tick, now_rfc3339(), and GuardSignals provide common timing,
  timestamp, and shutdown behavior for long-running loops.

Changes

GuardStep and Guard CLI

GuardStep provides the shared per-tick remediation kernel behind the new guard workflow. It
evaluates a guard rule, can expand a matched descendant to its subtree with cascade targeting,
applies an action only when explicitly enabled, and emits a structured event suitable for logs and
metrics.

sysprims guard now acts as a thin orchestrator over shared primitives rather than owning bespoke
loop logic in the CLI.

GuardRunner and Binding Support

GuardRunner in sysprims-proc extracts long-running watchdog behavior into a reusable Rust API.
It includes:

• drift-free scheduling via Tick
• signal-aware shutdown via GuardSignals
• cloneable stop handles
• max-iteration stop support
• summary stop reasons
• preset-driven interval and sample defaults

Bindings now have access to the same release surface:

• FFI: polling-style runner lifecycle with create, tick, stop, and free
• Go: GuardPreset, GuardRunnerConfig, NewGuardRunner, Tick(), Stop(), and Close()

TypeScript gets the one-shot guardStep() surface in this release; the managed runner remains a
Rust/FFI/Go surface for now.

The FFI and Go runner surfaces were hardened during devrev to ensure synchronized lifecycle access
and fail-fast validation of static guard configuration.

Provenance: ancestors

The release adds a new provenance surface for tracing parent chains:

sysprims ancestors <pid> --max-depth 10 --json

This closes the gap between "which descendant is hot?" and "what launched it?" without requiring
operators to leave sysprims.

Daemon Mode and Pidfiles

For long-running hosts and edge agents, sysprims guard now supports background operation on Unix:

sysprims guard 27776 --daemon --preset watchdog --yes
sysprims guard 27776 --status
sysprims guard 27776 --stop

Behavior highlights:

• --daemon detaches with setsid() and redirects stdio to null
• --pidfile <PATH> overrides the default /tmp/sysprims-guard-<root-pid>.pid
• stale or invalid pidfiles are cleaned up rather than trusted blindly
• --status and --stop verify that the pidfile target is actually a live sysprims guard process
• daemon startup waits for initialization to complete before reporting success

Windows daemon mode remains intentionally unsupported in v0.1.15; the CLI returns a clear
not-supported message directing operators to a service manager.

Self-Discovery

Running guards now set a best-effort platform title where supported, and sysprims process
inspection rewrites matching guard cmdlines to sysprims-guard:<root_pid> for ergonomic lookup.

Example workflows:

sysprims descendants 1 --name sysprims-guard --max-levels all
sysprims pstat --name sysprims-guard:27776 --table

On Linux, the kernel-visible thread name remains truncated by PR_SET_NAME, so the full identity
primarily comes from cmdline-backed discovery inside sysprims itself.

Shared Runtime Foundation

This release also adds shared runtime primitives in sysprims-core:

• now_rfc3339() for consistent timestamp rendering
• Tick for drift-resistant periodic scheduling
• GuardSignals for signal-aware shutdown with consistent stop semantics

These give future long-running sysprims workflows a common timing and shutdown contract.

Release Hardening

Release prep for v0.1.15 also tightened delivery discipline:

• stronger release preflight guidance
• explicit TypeScript binding validation in the release path
• clean prepush validation restored before release cut
• clearer CI-only policy for prebuilt native binding artifacts

Schema Versions

Schema	v0.1.14	v0.1.15	Change
process-info.schema.json	v1.1.0	v1.1.0	No change
process-info-sampled.schema.json	v1.1.0	v1.1.0	No change
descendants-result.schema.json	v1.0.0	v1.0.0	No change
descendants-result-sampled.schema.json	v1.1.0	v1.1.0	No change
batch-kill-result.schema.json	v1.0.0	v1.0.0	No change; cascade uses existing result shape
ancestors-result.schema.json	-	v1.0.0	New provenance chain contract
guard-event.schema.json	-	v1.0.0	New one-shot guard event contract

Upgrade Notes

• sysprims guard gains additive new flags only; existing foreground guard invocations continue to
  work.
• kill-descendants --cascade is additive; existing non-cascade behavior stays the default.
• Unix daemon mode is new; Windows remains intentionally unsupported in this release.
• ancestors is additive across all supported surfaces.
• FFI consumers must rebuild shared/static libraries to pick up new guard runner exports.
• Go verification for the new runner surface currently uses a freshly built local sysprims-ffi
  artifact during development until release workflows refresh checked-in prebuilt libraries.

References

• docs/decisions/ADR-0004-ffi-design.md
• docs/decisions/ADR-0005-schema-contracts.md
• docs/decisions/ADR-0011-pid-validation-safety.md
• docs/standards/platform-support.md
• RELEASE_CHECKLIST.md