Repository navigation
First release.
Added
whystuck [--idle N] [--timeout N] [--kill] [--json] [--stdin pty|null|closed] -- COMMAND: runs a command on a PTY with an idle watchdog.- Ordered rule table with evidence, confidence and non-interactive fixes:
editor,pager,secret,confirm,watch,follow,lock,
network(TCPSYN_SENT),server,stdin_wait,sleeping,busy, and an honestunknownfallback. - Linux collector based on
/proc(stat, cmdline, wchan, syscall, fd links,/proc/net/tcp{,6}, lock holders, CPU sample). - Best-effort
ps/lsofcollector for macOS/BSD (not tested on real macOS in this release). - Exit codes: passthrough,
124timeout,125stuck and stopped,126/127exec errors. --jsonoutput,--include-snapshot,--explain PID(read-only),--tail-file,--rules,--color.- Importable API:
diagnose(pid, tail=...),classify(snapshot),collect_snapshot(pid),run_command(...). --demo: eight offline scenarios (pager, editor, y/n prompt, password prompt, watch mode, long-running server, lock, stalled connect).- Process-group/session kill with SIGTERM then SIGKILL; Linux subreaper so no zombies are left behind.
- Tests: pure rule tests, mutation-style rule coverage, snapshots recorded from real processes, real-PTY integration tests, golden output.
- English and Persian READMEs, CI for Python 3.9 to 3.13, an
AGENTS.mdsnippet.
Known limits
See the "Limits" section of the README (silence-only detection, last-line prompt matching, SYN_SENT-only network detection, no Windows).
Install: pip install git+https://github.com/mrzroot/whystuck.git (no PyPI release yet). Note: CI workflow is not yet enabled in this repo.