I Stopped the Headless Claude Code Job, but the Build Kept Running — Designing Teardown Around exit 143

What 2.1.212 changed — interrupt, kill, exit 143

Claude Code 2.1.212 fixes this. When a print/SDK-mode process receives SIGTERM while a Bash command is running, Claude Code now interrupts the in-flight turn, kills the process tree of the command it launched, and exits with 143.

That number is meaningful. On Unix, a process terminated by a signal reports an exit code of 128 + signal number. SIGTERM is signal 15, so 128 + 15 = 143. In other words, exit 143 is now a clear signal that says "I received SIGTERM, respected it, and wound down." It is no longer the ambiguous state where the parent quietly exits 0 while a grandchild lives on.

For automation this is a small change with a large effect. After you send the stop signal, what the supervisor needs to confirm shifts from "is the exit code 0?" to "is the exit code 143, and are there no descendants left?" Because the contract is now explicit, your own design can be written just as explicitly.

Before / After — rewriting the supervisor around exit 143

Here is the minimal supervisor for running a headless job under timeout. The old shape did not account for orphans at all.

Before (a shape that drops orphans):

#!/usr/bin/env bash
# A supervisor that only stops the job after a time limit
timeout 30m claude -p "$(cat nightly_task.md)" \
  --output-format json > run.log
echo "exit=$?"
# timeout sends SIGTERM to the parent only, by default.
# Even if a grandchild build survives, this line is reached and prints exit

timeout 30m sends SIGTERM to the parent at the time limit, and that is all. If a grandchild survives after claude exits, the script marches on as if nothing happened.

After (fold the whole group, and interpret exit 143):

#!/usr/bin/env bash
set -uo pipefail
 
LOG=run.log
# setsid creates a new process group so the whole job is one group.
# timeout sends TERM via --signal and, after a grace period, KILL via --kill-after.
setsid timeout --signal=TERM --kill-after=20s 30m \
  claude -p "$(cat nightly_task.md)" --output-format json > "$LOG" &
JOB_PGID=$!
 
# If the supervisor itself is stopped, send TERM to the whole job group
cleanup() {
  # leading minus = propagate to the process group
  kill -TERM -"$JOB_PGID" 2>/dev/null || true
  # after a grace period, KILL anything that remains
  sleep 20
  kill -KILL -"$JOB_PGID" 2>/dev/null || true
}
trap cleanup TERM INT
 
wait "$JOB_PGID"
CODE=$?
 
case "$CODE" in
  0)   echo "done: clean exit" ;;
  143) echo "stopped: honored SIGTERM and wound down (expected)" ;;
  124) echo "warning: timeout reached, force-stopped (work incomplete)" ;;
  *)   echo "abnormal: exit=$CODE" ;;
esac

Three things changed. setsid groups the job into its own process group; the stop signal is sent with a leading minus, kill -TERM -"$JOB_PGID", so it reaches the whole group; and exit code 143 is branched explicitly as an "expected, graceful stop." Because 2.1.212 makes Claude Code kill the child tree itself, --kill-after stays as a safety net while the real teardown can be left to Claude Code.

When you run it under systemd

If you run the job as a long-lived or scheduled systemd service, control how the stop is delivered at the unit level. If that layer is loose, it can undo the 2.1.212 fix from above.

[Service]
Type=simple
ExecStart=/usr/local/bin/nightly-claude.sh
# Send SIGTERM on stop (default). Let Claude Code wind down politely first
KillSignal=SIGTERM
# Target the whole control group so grandchildren are reached
KillMode=control-group
# Grace period on stop; long enough to let Claude Code kill its tree
TimeoutStopSec=45
# Do not treat 143 as a failure (it is a respected stop, so count it as success)
SuccessExitStatus=143

KillMode=control-group is the key line. systemd manages the service as a cgroup, so this delivers the signal to every process in the cgroup on stop. Even if Claude Code's behavior changes later, you keep the supervisor layer in full control of the whole tree. SuccessExitStatus=143 keeps a graceful stop from being misread as a failure and paging you awake at 3 a.m.

Confirm, after the fact, whether orphans were escaping

Rather than trusting "it should be fixed now," it is worth confirming in your own environment that no orphans remain. Here is a simple check that counts the PIDs in the job's process group before and after you send the stop signal.

#!/usr/bin/env bash
# Launch the job and capture its PGID
setsid claude -p "$(cat probe_task.md)" > /dev/null 2>&1 &
PGID=$!
sleep 8   # wait for the build etc. to spawn grandchildren
 
echo "processes in group before stop:"
pgrep -g "$PGID" | wc -l
 
# stop it politely
kill -TERM -"$PGID"
sleep 5   # wait for the tree kill to complete
 
REMAIN=$(pgrep -g "$PGID" | wc -l)
echo "remaining processes 5s after stop: $REMAIN"
if [ "$REMAIN" -eq 0 ]; then
  echo "OK: no orphans left"
else
  echo "investigate: $REMAIN still alive. Check the supervisor's KillMode"
  pgrep -g "$PGID" -a
fi

I run this check once whenever I update Claude Code. Watching the count settle to 0 five seconds after the stop tells me it is safe to tighten --kill-after in the supervisor or TimeoutStopSec in systemd. Being able to confirm it with a number breaks the habit of padding the grace period out of guesswork.

What you still clean up yourself — the split with SessionEnd hooks

Killing the process tree only goes as far as "stop the running processes." The side effects those processes held — a half-written lock file, a partially built artifact, a recorded port reservation — do not disappear just because the process is gone. That part is yours to fold up.

Here is how the responsibilities divide.

The tidy way to clean up temp files and locks is either to add it to the supervisor's trap or to move it into a Claude Code SessionEnd hook. I cover building cleanup on hooks in Unifying cleanup and logging with a SessionEnd hook. If you want to monitor from another angle whether the stop actually landed, the approach in A dead man's switch for silent skips combines well. For how to hold permissions in unattended runs more broadly, see Designing the permission prompt as deny by default.

Wrapping up — try a single stop next time

The 2.1.212 fix turned a headless Claude Code stop from an ambiguous 0 into an explicit exit 143. It interrupts, kills the tree, and honors the signal. Because the contract is now clear, the supervisor can be written just as simply: 143 is expected, anything else needs a look.

If you run headless Claude Code overnight or on a schedule, the next step is just one thing. Send a single manual SIGTERM to a running job and, five seconds later, check with pgrep -g whether any process remains. If it is 0, your teardown reaches the descendants. If something is left, there is still a gap to close in the supervisor's KillMode or grace settings.

I have had a single surviving orphan hold a port and make the following night's job miss entirely. The mechanism that stops your work deserves as much design as the mechanism that runs it. Thank you for reading.