Summary

• Problem: timeout/cancel paths need a graceful cleanup window, but the first draft sent SIGTERM only to the direct child and could leave descendants running.
• Solution: pass a 5s grace window through the supervisor adapter API and make child/PTY SIGTERM cancellation use the same process-tree/group path as hard cancellation.
• What changed: supervisor cancellation now calls adapter.kill("SIGTERM", { graceMs: 5000 }); child and PTY adapters route SIGTERM through killProcessTree; tests cover tree-aware SIGTERM and no-detach safeguards.
• What did NOT change (scope boundary): no new token/network/config behavior, no change to timeout reason semantics, and no claim that this PR changes production agent-provider behavior outside process cancellation.

Motivation

Timeouts can happen while tool subprocesses are writing session state, cleaning temp files, or closing resources. This PR gives subprocesses a bounded graceful shutdown window while preserving the existing process-tree stop guarantee for descendants.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related Process supervisor: graceful signal escalation and drain timeout for exec tool #66399
• Related fix: gracefully escalate process supervisor cancellations #85865 review feedback from ClawSweeper
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: process supervisor timeout cancellation now gives real child processes and descendants a bounded SIGTERM cleanup window while preserving tree-aware SIGKILL fallback.
• Real environment tested: fresh throwaway Linux checkout on a test server, Node.js v22.22.2, dependencies installed with corepack pnpm install --frozen-lockfile. The descendant regression was run against old PR head e7ed7242ceb18783de1559d6dd700c973d2b726c, then after applying the tree-aware patch that produced head 720a57df0358976503d2ec501fb68e32d8ecb910.
• Exact steps or command run after this patch:

git checkout -f e7ed7242ceb18783de1559d6dd700c973d2b726c
node --import tsx ../PR-2026-05-24-process-supervisor-66399-proof.mjs

git apply ../openclaw-66399-tree-aware-incremental.patch
node --import tsx ../PR-2026-05-24-process-supervisor-66399-proof.mjs

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

{
  "proof": "process-supervisor-graceful-cancel-66399",
  "cleanupCase": {
    "name": "cleanup",
    "exitReason": "overall-timeout",
    "exitCode": 0,
    "exitSignal": null,
    "timedOut": true,
    "stdout": [
      "child_ready=true",
      "child_observed_sigterm=true",
      "child_finished_async_cleanup=true"
    ],
    "markerWritten": true
  },
  "fallbackCase": {
    "name": "fallback",
    "exitReason": "overall-timeout",
    "exitCode": null,
    "exitSignal": "SIGKILL",
    "timedOut": true,
    "stdout": [
      "child_ready=true",
      "child_observed_sigterm=true",
      "child_ignores_sigterm=true"
    ],
    "markerWritten": false
  },
  "descendantCase": {
    "name": "descendant",
    "exitReason": "overall-timeout",
    "exitCode": 0,
    "exitSignal": null,
    "timedOut": true,
    "stdout": [
      "parent_ready=true",
      "descendant_pid=43906"
    ],
    "parentMarkerWritten": true,
    "descendantMarkerWritten": true,
    "descendantPid": 43906,
    "descendantAliveAfterWait": false
  }
}

• Observed result after fix: the cleanup child observed SIGTERM and completed async cleanup; the SIGTERM-ignoring child was force-killed by SIGKILL; the parent-exits/descendant case now signals the descendant, writes the descendant marker, and leaves no live descendant after wait.
• What was not tested: Windows live runtime and production external agent integrations were not exercised. This PR does not add separate pipe-close behavior beyond preserving the existing adapter wait/fallback behavior.
• Before evidence (optional but encouraged): the previous PR head reproduced ClawSweeper's descendant concern with the same proof runner:

{
  "proof": "process-supervisor-graceful-cancel-66399",
  "descendantCase": {
    "name": "descendant",
    "exitReason": "overall-timeout",
    "exitCode": 0,
    "exitSignal": null,
    "timedOut": true,
    "stdout": [
      "parent_ready=true",
      "descendant_pid=43701"
    ],
    "parentMarkerWritten": true,
    "descendantMarkerWritten": false,
    "descendantPid": 43701,
    "descendantAliveAfterWait": true
  }
}

Root Cause (if applicable)

• Root cause: the first draft changed the supervisor to request adapter.kill("SIGTERM"), but the child adapter treated non-SIGKILL signals as direct child-only signals instead of using the process-tree path.
• Missing detection / guardrail: tests covered direct-child cleanup and SIGKILL escalation, but did not cover a parent that exits on SIGTERM while its descendant would otherwise keep running.
• Contributing context (if known): the existing hard-kill path already had detached/no-detach safeguards; graceful cancellation needed to preserve that same boundary.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/process/supervisor/supervisor.test.ts, src/process/supervisor/adapters/child.test.ts, src/process/supervisor/adapters/pty.test.ts
• Scenario the test should lock in: cancellation sends tree-aware SIGTERM with the same grace window, does not SIGKILL if the run settles, and still preserves no-detach safeguards so the gateway process group is not signaled.
• Why this is the smallest reliable guardrail: the supervisor owns grace timing, while child/PTY adapters own process-tree signal semantics.
• Existing test that already covers this (if any): kill-tree.test.ts already covers the underlying process-group/direct-pid behavior; this PR adds adapter-level coverage for SIGTERM using that path.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Timed-out or cancelled exec/tool subprocesses now get a bounded 5s tree-aware SIGTERM cleanup window before SIGKILL. Processes or descendants that ignore SIGTERM are still force-killed by the existing process-tree path.

Diagram (if applicable)

Before first draft:
[timeout/cancel] -> [supervisor requests SIGKILL tree path]

First draft bug:
[timeout/cancel] -> [direct child SIGTERM] -> [parent exits] -> [descendant can survive]

After:
[timeout/cancel] -> [tree-aware SIGTERM with 5s grace]
                 -> [cleanup-capable tree exits]
                 -> [if still running after grace] -> [tree-aware SIGKILL]

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): Yes
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation: cancellation behavior changed in the command execution boundary. The mitigation is that SIGTERM now uses the existing process-tree kill helper and preserves detached:false safeguards before the bounded SIGKILL fallback.

Repro + Verification

Environment

• OS: Linux throwaway test server checkout
• Runtime/container: Node.js v22.22.2, pnpm via corepack
• Model/provider: N/A
• Integration/channel (if any): process supervisor child mode and PTY adapter unit coverage
• Relevant config (redacted): no private tokens or external services used

Steps

1. Run the proof script on old PR head e7ed7242ceb18783de1559d6dd700c973d2b726c to reproduce direct-child-only SIGTERM leaving a descendant alive.
2. Apply the tree-aware adapter patch.
3. Rerun the proof script and confirm the descendant receives SIGTERM and is no longer alive after wait.
4. Run focused supervisor/adapter/runtime tests, formatting, lint, and typechecks.

Expected

• Cleanup-capable direct child receives SIGTERM and exits cleanly before SIGKILL.
• SIGTERM-ignoring direct child is later force-killed by SIGKILL.
• Parent-exits/descendant case sends SIGTERM to the descendant and leaves no surviving descendant after wait.

Actual

• Matches expected after this patch.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Additional verification run on the same throwaway checkout after applying the patch:

node scripts/run-vitest.mjs src/process/supervisor/supervisor.test.ts src/process/supervisor/adapters/child.test.ts src/process/supervisor/adapters/pty.test.ts src/process/kill-tree.test.ts
Test Files 4 passed (4)
Tests 42 passed (42)

node scripts/run-vitest.mjs src/agents/bash-tools.exec-runtime.test.ts src/agents/bash-tools.exec-runtime.pty-fallback.test.ts src/agents/cli-runner.reliability.test.ts src/agents/bash-tools.process.supervisor.test.ts
Test Files 8 passed (8)
Tests 140 passed (140)

corepack pnpm exec oxfmt --check --threads=1 src/process/supervisor/types.ts src/process/supervisor/supervisor.ts src/process/supervisor/supervisor.test.ts src/process/supervisor/adapters/child.ts src/process/supervisor/adapters/child.test.ts src/process/supervisor/adapters/pty.ts src/process/supervisor/adapters/pty.test.ts
All matched files use the correct format.

git diff --check
passed

node scripts/run-oxlint.mjs --tsconfig config/tsconfig/oxlint.core.json src/process/supervisor/supervisor.ts src/process/supervisor/supervisor.test.ts src/process/supervisor/adapters/child.ts src/process/supervisor/adapters/child.test.ts
Found 0 warnings and 0 errors.

node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo
passed

node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfo
passed

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: live timeout behavior before and after patch with real child processes; graceful SIGTERM cleanup; SIGTERM-ignore fallback to SIGKILL; parent-exits/descendant-survives regression red and green; focused supervisor/adapter tests; exec runtime tests; formatting; targeted lint; core typechecks.
• Edge cases checked: cancellation passes the same grace value into tree-aware adapter cancellation; child adapter preserves detached:false behavior when spawn falls back to no-detach; PTY SIGTERM uses the process-tree path.
• What you did not verify: Windows live runtime and production external agent integrations.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

No inline review threads exist. The top-level ClawSweeper finding about process-tree cancellation is addressed by the latest commit.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: cancellation may keep process-tree cleanup work active for up to 5s before force kill.
  • Mitigation: fixed grace timer is passed to the tree-aware helper and SIGKILL fallback remains bounded.
• Risk: detached:false runtimes must not group-kill the gateway process group.
  • Mitigation: child adapter keeps passing { detached: false } when spawn falls back to no-detach or service-managed mode disables detachment.