rmux_helper: add parent-pid-tree subcommand for tmux pane resolution

[idvorkin-ai-tools]

Summary

• Adds a parent-pid-tree subcommand to rmux_helper that walks the caller's parent-PID chain against tmux list-panes to deterministically find the caller's owning tmux pane.
• Documents the new subcommand in rust/tmux_helper/CLAUDE.md with exit-code contract and usage.
• Factors the walker into a DI-friendly helper with unit tests for the multi-session scenario, no-match case, and vanished-parent case.

Motivation

Observed 2026-04-14: harden-telegram's watchdog.py auto-recovery sent /reload-plugins to the wrong Claude session for ~45 minutes because it resolved the target pane via tmux display-message -p '#{pane_id}', which returns the tmux-active pane, not the caller's pane. With two Claude sessions running concurrently (Larry in pane %35, blog in pane %65), the watchdog reloaded the wrong session every time.

The correct primitive is a parent-PID walk: start from the caller's pid, read /proc/<pid>/stat field 4 for ppid, and match ancestors against tmux list-panes -a -F '#{pane_pid}'. First match is the answer. That's deterministic regardless of focus state.

This PR encapsulates that primitive in rmux_helper so future tmux-integration code can call rmux_helper parent-pid-tree and trust the answer instead of hand-rolling the walk. A companion PR in chop-conventions (#101) is fixing the specific watchdog.py case; this one makes the primitive reusable.

Test plan

• cargo test passes with the new unit tests (181 total, 9 new)
• cargo clippy --all-targets clean on new code (pre-existing link_picker warnings unchanged)
• rmux_helper parent-pid-tree from inside a tmux pane prints that pane's id
• rmux_helper parent-pid-tree --pid 1 (init) returns no-match, exit 1
• rmux_helper parent-pid-tree --verbose shows the walk chain on stderr
• rmux_helper parent-pid-tree --json emits valid JSON

Live smoke test output (from a tmux pane):

$ rmux_helper parent-pid-tree --verbose
parent-pid-tree: starting walk at pid 485370
parent-pid-tree: walked 485370 -> 4114505 -> 4114434 -> 2594534 (pane_pid) -> pane %35
%35

Follow-up: --tree

Added a --tree flag that prints the full ancestor chain as a visual tree with per-PID metadata: short comm, full cmdline (from /proc/<pid>/cmdline, null-separated argv joined with spaces), and exe readlink. Leverages the TmuxProvider / ProcReader DI layout from the earlier commits so the tree-builder and formatters are testable in isolation.

Composition:

• --tree alone — ASCII tree on stdout, exit 0/1 matches the walk result
• --tree --json — structured payload (start_pid, pane_id, pane_pid, chain[] with pid/comm/cmdline/exe)
• --tree --verbose — tree on stdout, walk log on stderr (streams don't cross)
• --tree --pid N — tree for an arbitrary start pid
• Default (no --tree) — unchanged; still emits just %N

Kernel-thread / permission-denied paths degrade gracefully: empty cmdline falls back to [comm]; unreadable exe prints exe: (unreadable) (or null in JSON). Long cmdlines truncate at 120 chars with … in the text view; full values always available via --json.

Eleven new tests cover: metadata collection, missing cmdline/exe handling, tree+json combination, no-match tree population (for debugging), formatter truncation, ASCII box-drawing, pane annotation at the leaf, and a real-/proc smoke test against the test process itself.

Live sample:

$ rmux_helper parent-pid-tree --tree
parent-pid-tree
├─ [pid 597447 ] zsh             /home/linuxbrew/.linuxbrew/bin/zsh -c source ...
│     exe: /home/linuxbrew/.linuxbrew/Cellar/zsh/5.9/bin/zsh
├─ [pid 4114505] claude          claude /startup-larry --dangerously-skip-permissions --channels plugin:telegram@claude-plugins-official
│     exe: /home/developer/.local/share/claude/versions/2.1.107
├─ [pid 4114434] larry_start.sh  /bin/bash ./larry_start.sh
│     exe: /usr/bin/bash
└─ [pid 2594534] zsh             /home/linuxbrew/.linuxbrew/bin/zsh  (pane shell)
      exe: /home/linuxbrew/.linuxbrew/Cellar/zsh/5.9/bin/zsh
      tmux pane: %35

🤖 Generated with Claude Code

Follow-up: shell completions

Adds an install-completions subcommand that writes shell completion scripts to the conventional location for zsh/bash/fish (powershell/elvish supported via --print-only). Auto-detects shell from $SHELL; override via --shell. Supports --dry-run (reports target path) and --print-only (stdout) for scripted use — mutually exclusive via clap.

rmux_helper install-completions              # auto-detect
rmux_helper install-completions --shell zsh  # explicit
rmux_helper install-completions --print-only # dump to stdout
rmux_helper install-completions --dry-run    # report path, skip write

Default install paths:

Shell	Path
zsh	$ZDOTDIR/.zfunc/_rmux_helper or $HOME/.zfunc/_rmux_helper
bash	$XDG_DATA_HOME/bash-completion/completions/rmux_helper or $HOME/.local/share/bash-completion/completions/rmux_helper
fish	$XDG_CONFIG_HOME/fish/completions/rmux_helper.fish or $HOME/.config/fish/completions/rmux_helper.fish

Dynamic completion — live values at tab-time

parent-pid-tree --pid <TAB> resolves live pids from /proc at tab-time, annotated with each process's comm as the completion description — capped at 500 entries, sorted newest-first so the most recently spawned processes appear first.

Uses clap_complete::CompleteEnv::with_factory(Cli::command).complete() at the top of main() (feature unstable-dynamic). When invoked with COMPLETE=<shell> in env, clap_complete intercepts and emits the shell script to stdout. The installed shell script re-invokes the binary with COMPLETE set on every tab press, so values are always live — no static snapshot to regenerate on upgrade.

Static completions (subcommand names, flag names, enum values like --shell <TAB>) come free from clap. side-edit <file> is annotated with ValueHint::FilePath for default shell file completion.

Live smoke

$ rmux_helper install-completions --shell zsh --dry-run
would install zsh completions to /home/developer/.zfunc/_rmux_helper

$ _CLAP_COMPLETE_INDEX=3 COMPLETE=zsh rmux_helper -- rmux_helper parent-pid-tree --pid "" | head -5
4114505:claude
4114434:larry_start.sh
4024124:tmux: client
4023867:bash
4023865:etterminal

Tests

14 new unit tests (shell detection, install-path resolution per shell+XDG, pid enumeration / truncation, missing-/proc tolerance, clap-level conflicts and unknown-shell rejection). cargo test now: 222 passed, 0 failed (was 208).

Summary by CodeRabbit

• New Features

  • Added parent-pid-tree command with --json, --pid, and --verbose flags for resolving tmux pane ownership via parent process chain.
  • Added dynamic shell completion support for the new command.

• Chores

  • Added dependency for shell completion generation.

[coderabbitai]

Warning

Rate limit exceeded

@idvorkin-ai-tools has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 54 minutes and 11 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 54 minutes and 11 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8656892e-49cf-4e62-bd5d-cfeb86de8a84

📥 Commits

Reviewing files that changed from the base of the PR and between bf7601e and c1f6f63.

📒 Files selected for processing (1)

• rust/tmux_helper/src/main.rs

📝 Walkthrough

Walkthrough

Added comprehensive documentation for a new parent-pid-tree command that resolves tmux panes via parent-PID chain traversal, along with a dependency addition (clap_complete v4) to support shell completion generation. No implementation code is included in these changes.

Changes

Cohort / File(s)	Summary
Documentation & Specification rust/tmux_helper/CLAUDE.md	Added complete behavioral specification for parent-pid-tree command, including usage modes, flags (--json, --pid, --verbose), exit codes (0–3), implementation location reference, testable architecture components, and shell completion dynamics.
Dependency Management rust/tmux_helper/Cargo.toml	Added clap_complete v4 dependency with unstable-dynamic feature to enable dynamic shell completion generation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Through parent PIDs we gently hop,
With tmux panes we'll never stop,
New docs chart the path so clear,
Completions bloom throughout the year! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding a parent-pid-tree subcommand to rmux_helper for resolving tmux panes via parent-PID chain walking.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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