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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 40841868-f6dd-4150-8ee2-a52bdcd7d834

📥 Commits

Reviewing files that changed from the base of the PR and between f83980d and 4127643.

📒 Files selected for processing (1)

• src/platform/linux.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• src/platform/linux.rs

---

📝 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.
• herdrdev/herdr#2269: Both changes update foreground process-group discovery, /proc parsing, and fallback handling.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main Linux and WSL change: preventing blocking proc reads for WSL agents.
Description check	✅ Passed	The description directly explains the WSL proc-read issue, the implemented safeguards, preserved wrapper inspection, and validation.
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.

✨ 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 makes Linux foreground-process discovery avoid potentially blocking remote-memory-backed procfs reads on WSL and for unsafe process states.

• Caches WSL detection and parses process state from /proc/<pid>/stat.
• Skips cmdline and environ reads for uninterruptible or dead processes.
• Uses process names directly for recognized WSL agents while retaining argv inspection for wrappers.
• Adds focused tests for proc-state parsing and guarded reads.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/platform/linux.rs	Adds WSL-aware and process-state-aware guards around procfs cmdline and environment reads, with unit coverage for the new branches.

Flowchart

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

Loading

_{Reviews (2): Last reviewed commit: "Merge branch 'master' into codex/fix-pro..." | Re-trigger Greptile}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[ogulcancelik]

Thanks for the detailed investigation. We cannot reproduce this WSL-specific failure locally. Before merging, could you capture the blocked Herdr thread's kernel stack or wchan, showing the /proc/<pid>/cmdline or environ read, and confirm that the patched build remains responsive under the same workload? The EAGAIN client error alone does not establish that procfs probing is the cause.