Process Supervisor (run)
Supervise agent execution processes, capture unbuffered stdout/stderr streams, and record deterministic telemetry traces.
The lastsignal run command is the entry point for forensic supervision. It launches your existing agent script as a supervised child process, non-invasively capturing real-time execution telemetry.
Command Syntax
Supervision Mechanics & Architecture
To ensure Last Signal never blocks or alters the timing of your agent's execution loop, the supervisor uses a non-blocking stream-reading architecture:
- Spawns subprocess with stdout=subprocess.PIPE and stderr=subprocess.PIPE.
- Starts two dedicated Python daemon threads to continuously read pipe buffers.
- Mirrors all output directly to the user's terminal in real time.
- Extracts JSONL telemetry events marked with __LS_EVENT__ prefixes or raw JSON payloads.
- Captures unhandled stack traces and system exit codes.
Why shell=False Matters
Many developer tools casually run subprocesses with shell=True, which introduces severe security vulnerabilities and process orphan bugs. Last Signal strictly uses shell=False:
- Security: Eliminates shell command injection when agents accept dynamic prompt arguments.
- Clean Signal Handling: Signals like Ctrl+C (SIGINT) are passed directly to the agent process rather than swallowed by a bash subshell.
- Deterministic PIDs: The monitored PID matches the actual runtime process, ensuring reliable exit code capture.
Output Artifacts
Every supervised run automatically persists its execution trace to .lastsignal/traces/<trace_id>.jsonl in your workspace directory.