Skip to content

feat(rust): process-tree control by subreaper and process groups - #22

Open
Overbaker wants to merge 1 commit into
deploy/nextfrom
rust/proctree-redesign
Open

Overbaker wants to merge 1 commit into
deploy/nextfrom
rust/proctree-redesign

Conversation

@Overbaker

Copy link
Copy Markdown
Owner

Fork-only PR; upstream HAPI stays TypeScript-only, see tiann/hapi#2534

What

Add process-tree cleanup to the Rust wrapper core. Preserve the three public lifecycle functions and the internal runner and terminal entry points. Provide configure_child_group(&mut tokio::process::Command) for agent and tool spawns. The wrapper and flavor binaries are absent from this base branch.

Principle

Linux enforces wrapper ownership through parentage and child-subreaper adoption. Cleanup walks the wrapper's task children, sends SIGTERM to private groups, then escalates to SIGKILL for surviving groups and individual descendants. Per-child cleanup preserves the direct child's exit status for its caller on Linux with glibc or musl.

Known gaps

  • A daemon that leaves its session and is adopted before the first per-tool walk loses its link to the originating tool. Per-child termination can report success while that daemon lives. Wrapper-wide shutdown still finds and reaps it. Exact attribution would require a separate kernel ownership boundary per tool.
  • PID reuse, hostile group membership, and deadline changes during wrapper-wide cleanup are outside this draft.
  • Linux requires readable procfs task children. Other Unix systems use process groups. Non-Unix cleanup is a no-op. Verification covered Linux only.
  • Mirror flavor code that skips process-group setup on Linux must use the spawn helper when ported.

Verification

The requested foreground aedas-me verification exited 0. Cargo formatting and all-target Clippy with warnings denied passed. Workspace tests passed once normally and three times pinned to CPU 0 at nice 19. The Linux process fixture checked a three-level tree, sibling and external sentinels, and deadline escalation for a TERM-ignoring orphan after setsid and subreaper adoption.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Needs changes (1 Major, 1 Minor)

Review mode: initial

Requirement — Pass

The fork needs reliable cleanup of agent and tool process trees, including orphan adoption and TERM-to-KILL escalation, while retaining lifecycle entry points.

Evidence

  • The PR description defines the fork-only use case, lifecycle behavior, platform scope, and known limitations.
  • tiann/hapi#2534 confirms the Rust implementation will be maintained in this fork after upstream declined adopting a second wrapper language.

Approach — Pass

Linux subreaper adoption combined with private process groups and parentage traversal is a viable mechanism for the stated cleanup scope.

Evidence

  • crates/hapi-wrapper-core/src/lifecycle/proctree.rs:12 configures private child process groups.
  • crates/hapi-wrapper-core/src/lifecycle/proctree.rs:33 establishes subreaper ownership, while lines 79-145 discover owned descendants.
  • crates/hapi-wrapper-core/src/lifecycle/proctree.rs:196 implements TERM/KILL sweeping and reaping.

Code — Reviewed

The core direction is coherent, but two deadline-handling defects can delay wrapper shutdown beyond its requested bound.

  • [Major] Procfs traversal can overrun the hard deadline — crates/hapi-wrapper-core/src/lifecycle/proctree.rs:197
  • [Minor] Later deadline reductions are ignored — crates/hapi-wrapper-core/src/lifecycle/proctree.rs:280

Testing

Not run (automation; PR code execution is prohibited).

  • The added Linux test covers private groups, descendant cleanup, external/sibling sentinels, subreaper adoption, and TERM-to-KILL escalation.
  • No regression coverage exercises a deadline change after cleanup starts or an already-expired/blocked hard deadline; non-Linux Unix behavior is also unverified.
  • Both Rust and core CI runs passed. One aggregate test run failed because unit-cli referenced the fork's absent ios files and wrapper-parity detected unrelated fixture drift; the parallel aggregate run passed.

HAPI Bot

}

fn step(&mut self) -> io::Result<Option<bool>> {
let members = self.tree.members(&self.known)?;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Major] Procfs traversal can overrun the hard deadline

Every sweep performs the complete synchronous descendant traversal before checking elapsed time. For example, kill_agent_tree(Instant::now()) with a living descendant still walks /proc and sends signals after the deadline. A large threaded/process tree or a slow procfs read can therefore block the cleanup task and wrapper exit beyond the advertised hard bound.

Suggested fix

Do not begin a traversal at or after the hard deadline, and run scans through a cancellable blocking worker raced against the deadline. Check cancellation while enumerating tasks and retain already-discovered targets for a bounded final escalation.

let now = Instant::now();
let soft =
now + Duration::from_secs(2).min(deadline.saturating_duration_since(now) * 2 / 3);
Tree(None).terminate(soft, deadline, None).await

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Minor] Later deadline reductions are ignored

kill_agent_tree_by reads the watch receiver only once and then calls terminate without it. If another cleanup request shortens the deadline while the TERM grace period is running, the sweep continues using the original deadline, defeating the receiver's purpose and delaying shutdown.

Suggested fix

Propagate the receiver into the sweep, wait on receiver changes alongside the timer, and clamp both soft and hard deadlines whenever a smaller cap arrives. Add a regression test that tightens the deadline after cleanup starts.

@github-actions github-actions Bot added the codex-review:changes HAPI Bot: review requests changes label Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

codex-review:changes HAPI Bot: review requests changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant