Scoped kills

Most port janitors kill one PID. That is still Kickoutchi’s default. Scoped kill is the explicit path for the cases where one PID is not the whole mess: dev servers with workers, package runners, agent shells, file watchers, and process groups that leave orphans behind.

Inspect first

inspect is read-only. It never signals anything. Use it when you need to see whether the port owner is the real root, whether a parent is supervising it, and on Linux/macOS whether process-group members sit outside the descendant tree.

kick inspect --port 3000
kick inspect --pid 18422

The report shows:

• The target PID, command line, visible ports, and on Linux/macOS the process group.
• Ancestors nearest-first, so supervisors and package runners are visible.
• Siblings under the same parent.
• The bounded descendant tree, with ports on members that own sockets.
• Process-group members on Linux/macOS, marking members outside the tree.
• A suggested kick kill --pid <root> --tree command, and on Linux/macOS a --group command only when group scope would catch processes the tree would leave alive.

Tree kill

Tree kill targets the confirmed root and its descendants. It is the right tool when a stale dev server owns the port and has workers underneath it.

kick kill --port 3000 --tree
kick kill --pid 18422 --tree
kick kill --pid 18422 --tree --force

Interactive tree kill requires typing tree for normal termination or force for force kill. A protected root still requires the PID/name confirmation first. A protected descendant refuses the whole tree.

On Linux and macOS, the execution path is freeze-first:

• Re-check the confirmed root right before acting.
• Count the tree before any signal; over the cap refuses with zero side effects.
• SIGSTOP the root first, then sweep descendants to a fixed point.
• Verify each stopped member’s identity while PID reuse is impossible.
• Send SIGTERM, then SIGCONT, leaves first and root last. --force sends SIGKILL instead.
• If anything becomes uncertain, thaw every stopped process and send no termination.

On Windows, tree kill uses Job Object containment instead of pretending there is a SIGSTOP equivalent:

• Re-check the confirmed root and tree before the Job Object commit.
• Refuse before commit for unsafe PIDs, protected descendants, incomplete metadata, identity drift, or an over-cap tree.
• Assign the root to a Job Object as the irreversible commit boundary, then converge descendants into the same containment.
• Terminate contained members with TerminateJobObject. Windows tree termination is hard termination only.
• Report partial containment, fallback termination, and not-terminated members honestly instead of collapsing them into success.

Process-group kill

Group kill targets every visible process sharing the target’s POSIX process group. It is Linux/macOS CLI-only and exists for cases a descendant tree cannot cover: double-forked helpers, reparented workers, or runaway trees where group membership is the more honest blast radius.

kick kill --pid 18422 --group
kick kill --port 3000 --group
kick kill --pid 18422 --group --force

Group scope is stronger than tree scope:

• It conflicts with --tree.
• It lists every visible member before confirmation.
• It warns that process groups can include unrelated commands from the same shell.
• It requires typing group or force unless --yes passes the strict all-clear group gate.
• During normal termination, every SIGTERM is queued before any stopped member is continued, so a parent-like member cannot wake up and spawn survivors while siblings are still frozen.

TUI support

The TUI exposes tree scope on Linux/macOS. Windows supports CLI --tree, but the Windows TUI still omits these keys:

Tree preview runs on a background worker so the table stays responsive. The preview is informational: execution re-collects the tree fresh, re-checks the root, and refuses if the fresh tree no longer passes the same gates.

Windows specifics

Windows supports read-only inspect and CLI kill --tree. It keeps normal kick kill precise to one confirmed PID, and it keeps --group unavailable because Windows has no POSIX process-group analog.

Windows parent links are accepted only after creation-time sanity checks. If metadata is missing and could hide a descendant inside the confirmed tree, --tree fails closed as incomplete metadata instead of silently omitting that process. Native Windows collection also cannot see individual Linux processes inside WSL2; use the Linux build inside WSL2 for those trees.