Module agent 

Agent process helpers.

All agents run in non-interactive mode (claude -p, codex exec) under a detached monitor that owns the process and its capture files (see crate::monitor). The old synchronous launch/capture path (launch_agent + capture_agent_output) was removed in 14b — the monitor is now the single way an agent process is spawned.

Structs

StrayProcess

A process discovered by discover_stray_devflow_processes: its pid, the start time recorded at discovery time, and which layer matched it.

Enums

StrayLayer

Which structural layer of a DevFlow-spawned process tree discover_stray_devflow_processes matched a candidate against.

Constants

STRAY_MIN_AGE

The age floor reap_stray_candidates (devflow-cli::commands) refuses to signal a candidate below. An age floor, not a classifier: it refuses every candidate younger than this in BOTH directions — a mid-execve false positive and a genuine stray younger than the floor are both refused, because process_age cannot tell the two apart and does not try to.

TERMINATE_VERIFY_POLL

Default poll interval while terminate_and_verify waits for its target to exit. Callers that need a different ceiling or granularity should pass their own wait/poll rather than inventing new constants.

TERMINATE_VERIFY_WAIT

Default bounded wait for terminate_and_verify’s escalation to SIGKILL. A few seconds is long enough for a well-behaved process to shut down after SIGTERM, short enough that an unattended loop is not stalled indefinitely waiting on one that won’t.

Functions

agent_running

Check whether a process with the given PID is still running.

discover_stray_devflow_processes

Census both of DevFlow’s orphan-prone process layers directly from the OS process table — the only remaining discovery surface once a project root has been deleted off disk, taking every registry entry, lock file and state file with it (999.44).

is_same_process

Whether pid is the same process instance that recorded expected_start.

looks_like_devflow_processDeprecated

Best-effort, Linux-only identity check for devflow stop’s signalling fallback (T-23-52, PID reuse in a stale lock file): does /proc/<pid>/cmdline name a devflow process? Reads the NUL-separated argv and reports whether any argument’s file-name component starts with devflow. Returns false when the file cannot be read (process exited between the liveness check and this call, non-Linux, permission denied) — the fail-closed direction. A false return means “identity could not be confirmed,” and callers must treat that as “do not signal,” never as “signal anyway.”

process_age

How long pid has been running: /proc/uptime (seconds since boot) minus process_start_time (ticks since boot, converted to seconds via the kernel’s own reported tick rate — never a hardcoded divisor).

process_start_time

A process’s start time — field 22 of /proc/<pid>/stat, in clock ticks since boot.

terminate

Send SIGTERM to pid — the crate’s one process-termination call, used by devflow stop’s signalling fallback (23c). Applies exactly the same guards agent_running applies, for reasons that are catastrophic here rather than merely wrong: signalling pid 0 would target the caller’s own process group (kill(0, sig) reaches every process in the group, including this one), and a value above i32::MAX would wrap negative through the as libc::pid_t cast — kill(-1, sig) sends the signal to every process the caller may signal. Returns whether the signal was delivered.

terminate_and_verify

Terminate pid, escalating to SIGKILL if it has not exited within wait, and return a verified fact about whether it is dead — never an assumption.