[danshapiro]

Problem

The Claude sidecar teardown tests (crates/freshell-freshagent/tests/claude_sidecar_teardown.rs) failed now and then:

• Linux (rust-gate): a_graceful_exit_does_not_leave_the_grandchild_running said the grandchild was still running after the stop was confirmed.
• Windows (Electron Build, step "Test Claude sidecar tree guard (Windows)"): an_abnormal_exit_is_not_graceful_and_the_tree_is_killed_at_once failed on PR fix(freshclaude): reliable alert bell, hidden-pane approvals, saved default model, and needs-attention marks on mobile #862 (job 120159949492) with SidecarExit { stop: AbnormalExit, elapsed: 6.78ms, status: Some(1), tree: Confirmed }. On PR feat(freshclaude): real-CLI ground truth, CLI simulator, Stop without a banner or a lost bell, and structured sidecar logs (core PR-A) #863, a_session_stop_confirms_the_whole_sidecar_tree_gone failed the same way (run 39888949438).

The "tree guard" makes sure that stopping a Claude session also stops every process under it, including the claude CLI the sidecar started. When it reports Confirmed, the session handoff treats the old session as fully gone.

Proven causes

Linux: the test was wrong. It used kill(pid, 0) to ask whether the grandchild still ran, and that call also finds a zombie (a killed process nobody has reaped yet). The grandchild's parent has already exited, so init or systemd --user adopts it, and on a busy machine it stays a zombie for a while after the guard has, correctly, confirmed it gone. With the test binary as process 1 of a new PID namespace (where nothing reaps orphans), the old test failed 60 of 60 times.

Windows: the product confirmed too early. The guard reported Confirmed as soon as the job object's count of active processes reached 0. Windows drops a process from that count as soon as it starts to exit, but signals its handle only once the exit is finished. That was 3-5 ms later for an idle node and 25-30 ms later for one holding 768 MB, in all 320 diagnostic runs (run 39882455815). Node keeps the children it starts in a kill-on-close job of its own, so a crashing node kills the grandchild while the guard is still collecting node's exit. The guard's first check therefore already read 0.

A review of the first fix found three more gaps, all fixed here:

1. Linux guard: the guard counted every process in state Z as gone. A process whose main thread has ended while another thread keeps running also reads Z. The guard reported Confirmed while such a process kept running and writing, and it never killed it.
2. Test strictness: the tests gave a member 5 seconds to finish exiting after Confirmed. A guard that confirmed right after sending its kill signal would have passed every Linux teardown test.
3. Windows guard: the guard saw only the processes the job listed when a stop began and at each check. A process started during the stop, and killed by node's crash before the next check, had already left the list and was never watched.

Fix

• Shared test probe (tests/support/process_probe.rs): one zombie-aware check is used by the integration tests and by the two unit tests (teardown_kills_a_grandchild_the_sidecar_left_behind, claude_catalog_probe_timeout_leaves_no_process_behind). It replaces main's inline copy from feat(freshclaude): durable transcript shows compaction, subagents, command output, errors, images, diffs and token usage #860. No kill(pid, 0) liveness check is left.
  • On Linux it reads /proc/<pid>/stat, where a zombie counts as exited once its last thread has ended.
  • On macOS a zombie counts as running until it is reaped.
  • On Windows it waits on a process handle.
• The probe now checks at once after a confirmed stop. It uses the same rule the guard uses to decide a member is gone, so a guard that confirms too early fails the test. Only kills that nothing confirms (dropping the guard, a test reaping its own zombie on macOS) still get a bounded wait.
• Linux guard: a Z process counts as alive while it still has other threads (/proc/<pid>/stat field 20).
• Windows guard (freshell-platform process_job.rs, used by claude_spawn.rs):
  • The guard keeps handles on the job's members. It confirms only when the job's count is 0 and every member's handle is signaled.
  • When a stop begins it also attaches a completion port to the job. The port reports every process already in the job and every process that joins later, and those reports can still be read after the process has started to exit.
  • A failed query counts as "still running".
• Load margin: an_abnormal_exit_is_not_graceful_and_the_tree_is_killed_at_once now uses a 20 s grace period and still requires the stop to take less than half of it. With 32 copies running at once, node's crash alone took 1.07-1.24 s and tripped the old 1 s limit in 21 of 192 runs. A guard that waits out the grace period still fails the test.

Tests and results

New tests:

• a_graceful_exit_does_not_leave_a_member_whose_main_thread_ended_running (Linux; Python pthread_exit). Before the fix the guard confirmed at 60 ms with the process still running. After the fix it passes.
• an_abnormal_exit_is_confirmed_only_once_a_slow_exiting_grandchild_has_exited and terminating_the_guard_is_confirmed_only_once_a_slow_exiting_grandchild_has_exited. Against the old Windows guard they failed 3 of 3 times (run 39884275738).
• an_abnormal_exit_is_confirmed_only_once_a_grandchild_started_during_the_stop_has_exited, plus the platform tests the_job_reports_the_processes_in_it_and_every_one_that_joins and a_member_the_job_no_longer_lists_is_still_watched_once_it_was_reported:
  • Without the completion port, both the integration test and the member test failed 3 of 3 times on Windows (run 39895152092).
  • With it, the Job Object tests and the teardown target each passed 20 of 20 times (run 39895154418).
• Probe self-tests: a running process reads as running, an unreaped zombie reads as exited, and a process whose main thread ended reads as running.
• Mutation check: with the guard changed to confirm right after its signal, 5 teardown tests fail 3 runs out of 3. With the old 5 s allowance, they passed.

Linux repeat runs at c03749de7 (15 tests in the teardown target):

Condition	Runs	Result
Teardown target, process 1 of a new PID namespace (no reaper)	60	all passed
Same, 24 namespaces at once	120	all passed
Teardown target, 24 copies at once	200	all passed
Teardown target, 32 copies at once	192	all passed
The two unit tests, 32 copies at once	128	all passed
The two unit tests, in PID namespaces	60	all passed

Checks:

• cargo fmt --all --check and cargo clippy -p freshell-freshagent -p freshell-platform --all-targets -- -D warnings pass on Linux.
• Clippy for x86_64-pc-windows-gnu and aarch64-apple-darwin reports no warnings in the changed files. Other files already have warnings on those targets.
• The pre-push hook passed.

Full Electron Build on this branch at c03749de7, run twice:

• Run 39897673777: every job passed.
  • Windows: the tree-guard step passed 11 of 11 tests and the Job Object step 7 of 7.
  • macOS: the tree-guard step passed 13 of 13 tests on both macos-latest and macos-15-intel.
• Run 39897683324: every job passed, with the same counts.

Not changed here

• session_lease::proc_starttime_observation (used by the Linux session confirmation) and freshell-codex sidecar_store also treat any Z process as gone. The Claude teardown does not depend on them, because the tree guard runs first and now waits for such a process and kills it.
• The checkpoint code's settle_checkpoint_job also treats a job count of 0 as done on Windows, so it may have the same early-confirm gap.
• freshell-server extensions::tests::scan_warns_with_legacys_two_log_lines_for_the_two_failure_classes failed once in the pre-push hook and passed on retry. It is unrelated to this change.

🤖 Generated with Claude Code