Why use a stopped shell rather than start the command immediately?
A process tracer that attaches after a target begins can miss its early file opens, subprocess launches, or network activity. In the v1.0.35 run_exec path, AgentSight prepares credentials and resolves the TLS attach executable first, but it does not start the real workload immediately. It launches a small shell with the argument-preserving sequence:
target=$1; shift; kill -STOP $$; exec "$target" "$@"The shell raises SIGSTOP on itself, not on an already running agent. Its PID is used for pid and session_id in the trace configuration. After starting the sensors, the parent waits 250 ms, calls kill(pid, SIGCONT), and the shell executes the requested command. The fixed delay is a startup sequencing choice, not a measured proof of zero loss.
This is a source-level reconstruction of AgentSight v1.0.35at commit c1574366122a90c451bca6a84713e28813ab95e2, not a measured tracer-startup latency experiment. It addresses launch ordering and cleanup; the existing process exit articleaddresses event status interpretation, and the TLS filter articleaddresses attachment scope.
The six-stage launch sequence
| Stage | What the source does | What it establishes |
|---|---|---|
| Command and TLS target resolution | Resolve requested executable or SSL-embedding binary; perform visible sudo preflight if needed | No target shell exists yet; a failure here cannot leave the target suspended |
| Spawn into a new session | Start /bin/sh -c with positional arguments; run setsid, and optionally restore SUDO_UID/SUDO_GID | The new shell PID becomes the trace PID and session attribution key |
| Launch barrier | The shell invokes kill -STOP $$ before exec of the requested command | Target workload is held while tracer startup proceeds; this does not make all future captures lossless |
| Configure and start sensors | Seed process tracking, create materialized view/optional SQLite sink, optionally start web server, then await agent.run() | Several fallible setup calls occur after spawn and before resume |
| Release target | After a fixed 250 ms sleep, send SIGCONT to the shell PID | The shell then execs the requested program and normally retains its PID |
| Run and wind down | Consume trace events or wait for child exit/shutdown; drain events for up to 5 s after exit | A bounded drain is not a guarantee that every buffered event was recorded |
The command is launched into a new session using setsid(); when invoked as root under sudo with valid original-user environment values, AgentSight restores the child's UID/GID before the shell begins. The tracer can still require elevated privileges. These two identities must not be confused: the target's effective user need not be the tracer's effective user.
The default session database is named agentsight-YYYYMMDD-HHMMSS.dbin the current directory. The record configuration enables TLS, process, network, stdio, and sampled system tracing, but their respective filters, permissions, buffer limits, and evidence boundaries still apply.
Failure-path audit: a possible suspended-child leak before resume
After spawn() and before SIGCONT, three fallible steps—prepare_process_seeds(), build_trace_agent_with_view(), and optional start_web_server_if_enabled()—can return using ? without an explicit stop_child(). The same function does call stop_child() for errors returned by agent.run() and continue_child().
The Tokio process handle does not terminate the child on drop by default, and this command builder does not set kill_on_drop(true). The combination creates a source-supported risk that a stopped shell survives a recorder setup failure, requiring manual diagnosis by an operator. Whether the race is hit depends on the precise failure and scheduling order; no field incident or reproduction is claimed here.
A robust implementation could scope child ownership with an explicit cleanup guard across all post-spawn setup errors and avoid relying on implicit drop behavior. This is a source-level engineering recommendation, not a claim that it is already fixed in v1.0.35.
Nine failure and lifecycle cases
| Condition | Control flow | Safe inference |
|---|---|---|
| sudo authentication fails | Return before spawn | No launched target to clean up |
| Executable or TLS attachment path cannot be resolved | Return before spawn | No suspended target |
| Process snapshot/seed collection fails after spawn | Early ? return | Potentially stopped child; no explicit stop_child on that path |
| Tracer/materialized-view setup fails after spawn | Early ? return | Potentially stopped child; cleanup is not called on this path |
| Optional web-server startup fails | Early ? return | Potentially stopped child; cleanup is not called on this path |
| agent.run() returns an error | Explicit stop_child then return error | Wait up to two seconds for child; then kill if still running |
| SIGCONT fails | Explicit stop_child then return error | Unsuccessful resume does not silently proceed to normal monitoring |
| Target exits normally | Record status, drain stream for up to five seconds | Exit does not imply a fully complete trace or successful agent task |
| Shutdown event arrives before child exit | Break then stop_child | Recorder attempts cleanup, but does not promise graceful application shutdown |
After a normal target exit, the recorder performs a bounded five-second stream drain and may print a SQLite-backed session summary. It does not guarantee that kernel buffers, TLS plaintext, child process work, or agent-native events form a complete causal history. A successful exec and observed process exit are distinct from successful task completion.
Reproduce the implementation inspection safely
Inspect the exact released code in a local product checkout; these commands only read source and do not launch a tracer, send signals to processes, or generate sensitive session artifacts:
git checkout c1574366122a90c451bca6a84713e28813ab95e2
grep -n -E "kill -STOP|setsid|prepare_process_seeds|build_trace_agent_with_view|start_web_server_if_enabled|agent.run|continue_child|stop_child|drain_stream_for" collector/src/cmd_exec.rs
grep -n -E "fn for_record|build_stdio_args|fn build_trace_agent_with_view" collector/src/cmd_trace.rs
grep -n -E "kill_on_drop" collector/src/cmd_exec.rs || trueThe last grep is expected to find no kill_on_drop call in this source file. For a real failed launch, record the error phase first; before manually signaling any suspected stopped PID, independently confirm its executable, parent, owner, and session identity. Do not blindly resume or kill a PID inferred only from a stale error message.
Sources and limitations
- record spawn, SIGSTOP/SIGCONT, early returns, and shutdown
- record TraceConfig defaults, process/stdio/TLS runners and materialization
- Tokio Child drop does not kill by default
- AgentSight v1.0.35 release
Reviewed 13 November 2026. This audit covers the Linux record -- command path in tagged v1.0.35, not arbitrary trace, top, Windows/macOS native-session viewing, or all process supervisors. It infers potential failure behavior from the visible Rust control flow and documented Tokio drop semantics; it does not establish how frequently failures occur or prove a specific user process was left stopped.