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

StageWhat the source doesWhat it establishes
Command and TLS target resolutionResolve requested executable or SSL-embedding binary; perform visible sudo preflight if neededNo target shell exists yet; a failure here cannot leave the target suspended
Spawn into a new sessionStart /bin/sh -c with positional arguments; run setsid, and optionally restore SUDO_UID/SUDO_GIDThe new shell PID becomes the trace PID and session attribution key
Launch barrierThe shell invokes kill -STOP $$ before exec of the requested commandTarget workload is held while tracer startup proceeds; this does not make all future captures lossless
Configure and start sensorsSeed 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 targetAfter a fixed 250 ms sleep, send SIGCONT to the shell PIDThe shell then execs the requested program and normally retains its PID
Run and wind downConsume trace events or wait for child exit/shutdown; drain events for up to 5 s after exitA 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

ConditionControl flowSafe inference
sudo authentication failsReturn before spawnNo launched target to clean up
Executable or TLS attachment path cannot be resolvedReturn before spawnNo suspended target
Process snapshot/seed collection fails after spawnEarly ? returnPotentially stopped child; no explicit stop_child on that path
Tracer/materialized-view setup fails after spawnEarly ? returnPotentially stopped child; cleanup is not called on this path
Optional web-server startup failsEarly ? returnPotentially stopped child; cleanup is not called on this path
agent.run() returns an errorExplicit stop_child then return errorWait up to two seconds for child; then kill if still running
SIGCONT failsExplicit stop_child then return errorUnsuccessful resume does not silently proceed to normal monitoring
Target exits normallyRecord status, drain stream for up to five secondsExit does not imply a fully complete trace or successful agent task
Shutdown event arrives before child exitBreak then stop_childRecorder 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 || true

The 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

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.