fix: agentcore dev orphaned processes

[avi-alpert]

Description

When agentcore dev is killed programmatically (SIGTERM/SIGKILL), the underlying uvicorn reloader and worker processes are not terminated. They get reparented to PID 1 and continue holding the port. Subsequent agentcore dev runs then fall back to a different port, leaking processes with each run.

Interactive Ctrl+C (SIGINT) was unaffected since it hits the entire process group and was already handled. This fix addresses only the programmatic kill $PID (SIGTERM) path used by scripts, CI, and agent tooling.

Root cause: Two issues combined:

1. Only SIGINT was handled — SIGTERM (from kill $PID) exited without triggering cleanup.
2. child.kill('SIGTERM') only signals the direct child PID. uvicorn --reload forks a reloader that spawns a worker, so grandchild processes survived.

Fix:

• Spawn the child with detached: true (POSIX) so it gets its own process group.
• Kill the entire process tree: process.kill(-pid, signal) on POSIX, taskkill /pid <pid> /T /F on Windows.
• Add SIGTERM handling to all three dev server code paths: --logs and browser/web-UI use onShutdownSignal() (SIGINT + SIGTERM), TUI adds SIGTERM only (Ink handles SIGINT).
• Extract onShutdownSignal() helper to avoid duplicating signal registration.

Related Issue

Closes #1440

Documentation PR

N/A

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

Manually verified on macOS and Windows:

# macOS/Linux
agentcore dev --logs &
DEV_PID=$!
sleep 5
kill $DEV_PID
wait $DEV_PID 2>/dev/null
sleep 1
lsof -ti :8080  # No orphaned processes

Manually tested on windows by running agentcore dev and then Stop-Process on the node process, making sure no child processes remained.

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[github-actions]

Package Tarball

aws-agentcore-0.16.0.tgz

How to install

gh release download pr-1438-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-0.16.0.tgz

[agentcore-cli-automation]

Thanks for tackling the orphaned process bug. The fix on Linux/macOS is sound — detached: true puts the child in its own process group and process.kill(-pid, signal) signals the whole tree, which is exactly what's needed for uvicorn --reload's reloader/worker pair.

However, this approach is broken on Windows, which src/lib/utils/platform.ts and AGENTS.md indicate is a supported platform. Two issues called out inline:

1. detached: true on Windows spawns the child in a new console window (visible flash, separate console).
2. Windows has no POSIX process groups — process.kill(-pid, ...) will throw EINVAL/ESRCH, the catch falls back to child.kill(signal), and child.kill on Windows does not kill the process tree either. So on Windows we'd be back to orphaning subprocesses — same bug this PR is fixing.

The usual fix is to gate the new behavior on !isWindows and use taskkill /pid <pid> /T /F (or the tree-kill package) for Windows process tree termination.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-cli-automation]

Nice fix — the POSIX-side approach (detached: true + process.kill(-pid, sig)) is exactly right for uvicorn --reload's reloader/worker pair, and the Windows path via taskkill /T /F covers the cross-platform gap raised in earlier review threads.

Most of my concerns were already covered in those threads (Windows handling, the this.child! footgun, the SIGTERM-only handler in TUI mode). One additional test-correctness item below — non-blocking for CI (since CI only runs on ubuntu-latest) but worth fixing for parity with codezip-dev-server.test.ts, which already mocks isWindows.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[jariy17]

LGTM

[jariy17]

LGTM