worktree_stop appears to hang / not return when the target process is already gone

[Seretos]

#ai-generated

Summary

worktree_stop (exposed via the agent-worktree MCP, backed by core/process_lifecycle.py) appeared to hang / not return in a session where the tracked Unity process had already exited externally (closed/Stop-Process), leaving a stale running record with a dead PID.

Context / observations

• The worktree record still showed status: running with an old PID (e.g. pids.main = 41020) while no Unity.exe was actually running.
• Calling worktree_stop (with kill_orphans=true) in this state did not return promptly; it had to be interrupted repeatedly.
• This surfaced during the cache-server investigation (see the companion ticket about worktree_start + Cache Server). It may share the same area of the codebase (process_lifecycle.py).

Hypotheses to check

• Graceful-shutdown wait (SIGTERM/CtrlBreak → timeout → kill) blocking when the PID is already dead/reparented.
• kill_orphans cwd/open-file scan blocking or iterating over a large/locked set.
• Reconciliation of a stale running record not short-circuiting when the recorded PID no longer exists.

Suggested next step

Add a fast path: if the recorded PID is not alive, mark the record stopped and return immediately (idempotent), and bound/parallelise the orphan scan with a hard timeout so worktree_stop always returns within the documented timeout.

Relevant code

• src/lib_python_worktree/core/process_lifecycle.py (stop / graceful-shutdown / orphan-scan logic).

Note: observed on Windows; not yet confirmed on POSIX.

[Seretos]

#ai-generated

Plan — fix worktree_stop hang

Goal: stop must always return within the documented timeout, regardless of system state (dead/stale PID, large orphan set, locked dirs on Windows).

Root cause: the kill_orphans branch calls _kill_blocking_processes, which loops sequentially over orphans calling _wait_or_kill(..., timeout=5.0) with a hardcoded 5s per orphan — N orphans ⇒ up to 5N seconds, unbounded and independent of the caller's timeout.

Approach:

• _kill_blocking_processes(path, *, timeout=5.0) — gain a timeout arg and distribute the budget across orphans via a shared monotonic deadline (even-split timeout/n, with a remaining guard); total runtime is bounded by timeout.
• stop — compute one deadline = monotonic() + timeout at entry; pass remaining budget to both _wait_or_kill(pid, …) and _kill_blocking_processes(…, timeout=…). A dead/stale PID consumes ~no time and leaves the full budget for the orphan scan; a live PID that used the whole budget leaves orphans to be force-killed immediately.
• Docstring updates on both functions.

Affected files:

• src/lib_python_worktree/core/process_lifecycle.py (stop, _kill_blocking_processes)
• tests/test_process_lifecycle.py (bounded-orphan-scan + fast-path regression tests)

Tests: python -m pytest

[Seretos]

#ai-generated

Draft PR opened: #53. Bounds the stop orphan scan by the caller timeout (shared monotonic deadline); reviewer APPROVE + Codex clean; full suite 321 passed.