Bug: `agentcore dev` leaves orphaned Uvicorn process on Ctrl+C

[madhavvishnubhatta]

Description

Summary

When stopping agentcore dev --logs with Ctrl+C, the CLI's Node process exits but does not terminate the Uvicorn subprocess it spawned. The Uvicorn process (and its children) become orphaned under PID 1 and continue running indefinitely, holding the port. This happens every time, not intermittently.

Impact

• The orphaned server retains in-memory state (e.g., Strands Agent conversation history), making it appear that sessions persist across restarts.
• On next agentcore dev start, the port is occupied, forcing fallback to a different port (e.g., 8081).
• The CLI may still route prompts to the old port, talking to the stale server instance without the user's knowledge.
• Accumulated orphaned processes consume system resources.

Steps to Reproduce

1. Start the dev server:

   agentcore dev --no-browser --logs

2. Confirm the process tree:

   ps -ef | grep uvicorn
   # Shows: agentcore (node) → uvicorn reloader → uvicorn worker

3. Press Ctrl+C in the terminal running agentcore dev.

4. Verify the orphaned processes:

   lsof -i :8080
   # Uvicorn processes still listening on the port
   
   ps -ef | grep <uvicorn_pid>
   # PPID is now 1 (orphaned under launchd/init)

Expected Behavior

Expected behaviour is that the Uvicorn process listening on 8080 is also killed.

Actual Behavior

Ctrl+C should terminate both the agentcore CLI process and the entire Uvicorn subprocess tree cleanly, releasing the port.

CLI Version

0.22.0

Operating System

macOS

Additional Context

Observed Process Tree

Before Ctrl+C:

PID 15652  node /opt/homebrew/bin/agentcore dev --no-browser --logs   (PPID: 7376, shell)
  PID 15656  python3 ... uvicorn main:app --reload --host 127.0.0.1 --port 8080   (PPID: 15652)
    PID 15657  python3 ... multiprocessing.resource_tracker   (PPID: 15656)
    PID 15658  python3 ... multiprocessing.spawn              (PPID: 15656)

After Ctrl+C:

PID 15652  — GONE (agentcore node process exited)
PID 15656  python3 ... uvicorn ... --port 8080   (PPID: 1, orphaned under launchd)
  PID 15657  python3 ... resource_tracker          (PPID: 15656)
  PID 15658  python3 ... spawn                     (PPID: 15656)

Workaround (for users)

Until the fix is released, users can work around this by manually killing orphaned processes:

# Kill any process on port 8080
lsof -ti :8080 | xargs kill

# Or use SIGQUIT instead of SIGINT (more forceful)
# Press Ctrl+\ instead of Ctrl+C

[hagaym1]

I looked into this and believe I found the root cause — and it affects TypeScript/Node dev servers too, not just Python/uvicorn, and on both Ctrl+C (SIGINT) and programmatic kill $PID (SIGTERM).

Root cause: agentcore dev spawns the dev server detached (its own process group, added in #1438) and relies on the dev command's SIGINT/SIGTERM handler (onShutdownSignal, registered with process.once) to call server.kill() and tree-kill the group. But setupAltScreenCleanup() (in src/cli/cli.ts, called first thing in main()) registers a global process.on('SIGINT'/'SIGTERM') handler that calls process.exit(0). Node runs signal listeners in registration order, and the global handler is registered before the dev command's — so it fires first, process.exit(0) terminates the process, and server.kill() never runs. The detached child is reparented to PID 1 and keeps holding the port.

So #1438 correctly fixed the reparenting mechanics, but the compensating shutdown handler it added is preempted by the pre-existing global process.exit(0) handler — which is why the orphan is back in 0.22.0, and now also on interactive Ctrl+C (the detached child is in its own process group and no longer receives the terminal's group SIGINT directly).

Reproduced on macOS with a TypeScript agent (same shape as the Python repro above):

agentcore dev --logs --port 9137 &
DEV_PID=$!
# wait for the port to bind, then:
kill $DEV_PID
sleep 4
lsof -ti :9137   # orphaned node still listening, reparented to PPID 1

I have a fix — register a process.on('exit') reaper in DevServer.start() that SIGKILLs the child's process group (the 'exit' event always fires on process.exit(), so it runs even when the global handler exits first) — and will open a PR that closes this issue shortly.

[hagaym1]

Opened #1695 to fix this — the root cause, the mechanism, and a before/after A/B are in the PR description.