fix(linux): avoid blocking proc reads for WSL agents

[dark2momo]

Context

This was encountered on WSL2 while Herdr was managing several Codex panes. After one of the Codex processes became stuck in an uninterruptible or exiting state, Herdr commands repeatedly failed with:

herdr: protocol error: I/O error: Resource temporarily unavailable (os error 11)

The failure occurred three times in one day. Restarting the affected pane did not reliably clear the stuck process; terminating the WSL distribution was the recovery used in each case.

Inspection showed affected Codex threads blocked in kernel process-exit and virtual-memory paths. Herdr already identified the foreground executable as codex from /proc/<pid>/stat, so reading its remote-memory-backed cmdline or environ was unnecessary and exposed Herdr to the same stall.

This PR does not attempt to recover the stuck agent or fix the underlying WSL kernel behavior. It keeps Herdr's process discovery responsive when an already identifiable agent enters that state, while preserving argv inspection for wrapper processes.

Environment

• Windows 11
• WSL 2.7.10.0
• Ubuntu 22.04
• Linux 6.18.33.2-microsoft-standard-WSL2
• Codex CLI 0.145.0

Summary

• avoid reading /proc/<pid>/cmdline for known agent executables on WSL, where procfs can block in access_remote_vm while a multithreaded process exits
• skip remote-memory-backed proc reads for uninterruptible and dead process states
• preserve argv inspection for wrappers such as node, and apply the same guard to agent environment hints
• cover the WSL fast path and unsafe process states with unit tests

Validation

• just test-one remote_memory
• just test-one foreground_job_on_wsl
• just test-one proc_stat_parsing
• just lint
• just check through formatting, Clippy, 3,149 Rust tests, integration assets, plugin marketplace tests, and Windows target Clippy

The final maintenance-script step of just check could not run locally because this machine provides Python 3.10, while scripts/agent_detection_manifest_check.py imports the Python 3.11+ standard-library tomllib module. The other maintenance tests in that invocation completed before the missing-module error; CI provides the repository's supported environment.

[coderabbitai]

📝 Walkthrough

Walkthrough

Linux process metadata now includes process state. Foreground-group discovery and process-agent lookup guard command-line reads for unsafe states and known WSL agents. WSL detection is cached, and tests cover state parsing and wrapper handling.

Changes

Linux process discovery

Layer / File(s)	Summary
Process metadata and read safety src/platform/linux.rs	Process metadata now includes process state. Cached WSL detection and safety checks suppress reads for uninterruptible, zombie, dead, and known agent processes.
Foreground group discovery integration src/platform/linux.rs	Foreground lookup uses the native terminal group first and configured child-group fallback second. Unsafe processes skip command-line reads while wrappers remain inspectable.
Process-state and command-line validation src/platform/linux.rs	Tests cover process-state parsing, updated process fixtures, unsafe states, WSL agents, and readable wrapper processes.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ForegroundJobLookup
  participant ProcMetadataParser
  participant CmdlineReader
  ForegroundJobLookup->>ProcMetadataParser: Read process-group metadata
  ProcMetadataParser-->>ForegroundJobLookup: Return PID, group, command name, and state
  ForegroundJobLookup->>CmdlineReader: Read command arguments when safety checks pass
  CmdlineReader-->>ForegroundJobLookup: Return command arguments or no result

Loading

Possibly related PRs

• herdrdev/herdr#2042: Both changes update foreground process-group discovery and fallback logic.
• herdrdev/herdr#2052: Both changes update foreground-process discovery and /proc metadata parsing.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: preventing blocking proc reads for WSL agents.
Description check	✅ Passed	The description directly explains the WSL proc-read issue, the implemented safeguards, and the validation performed.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR avoids potentially blocking remote-memory-backed procfs reads on WSL while retaining argv inspection for wrapper processes.

• Adds process-state parsing and rejects cmdline/environment reads for dead or uninterruptible processes.
• Uses comm-based agent identity to bypass cmdline reads for known agents on WSL.
• Caches WSL detection and adds focused unit coverage for the guarded paths.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete changed-code failure identified.

The guarded paths preserve argv inspection for wrappers while avoiding remote-memory-backed procfs reads for known WSL agents and unsafe process states, and the added tests cover the principal branching behavior.

Important Files Changed

Filename	Overview
src/platform/linux.rs	Adds WSL-aware procfs read guards, process-state propagation, cached platform detection, and unit tests without an established actionable defect.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Read proc stat] --> B{State permits remote-memory read?}
    B -- No --> E[Use comm only]
    B -- Yes --> C{Running inside WSL and comm identifies agent?}
    C -- Yes --> E
    C -- No --> D[Read cmdline or environ]
    D --> F[Build process or agent detection result]
    E --> F

Loading

_{Reviews (1): Last reviewed commit: "fix(linux): avoid blocking proc reads fo..." | Re-trigger Greptile}